diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 60b39f8118..5078333c83 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -38,14 +38,6 @@ RUN GO_VERSION="1.23.8" && \
     && tar -C /usr/local -xzf go${GO_VERSION}.linux-${GOARCH}.tar.gz \
     && rm go${GO_VERSION}.linux-${GOARCH}.tar.gz
 
-RUN git clone https://github.com/alibaba/yalantinglibs.git \
-    && cd yalantinglibs \
-    && mkdir -p build \
-    && cd build \
-    && cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF \
-    && cmake --build . -j$(nproc) \
-    && cmake --install .
-
 ENV GOPROXY='https://goproxy.cn'
 ENV PATH=/usr/local/go/bin:$PATH
 
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 24dcbb753e..8e23479188 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -12,8 +12,29 @@
 /mooncake-integration/transfer_engine @ShangmingCai @alogfans
 /mooncake-integration/store @ykwd @stmatengss @zxpdemonio
 /mooncake-pg @UNIDY2002 @ympcMark @yuechen-sys
+/mooncake-reshard @ShangmingCai @stmatengss @Bo-Vincent @zxpdemonio
 /mooncake-store @ykwd @stmatengss @XucSh @YiXR
-/mooncake-store/*/ha/ @Libotry @YiXR @00fish0 @Icedcoco
+/mooncake-store/*/ha/ @Libotry @YiXR @00fish0 @Icedcoco @Aionw
+/python/mooncake/async_store.py @ykwd @stmatengss @zxpdemonio
+/python/tests/store/async_store_integration.py @ykwd @stmatengss @zxpdemonio
+/python/tests/store/test_async_store.py @ykwd @stmatengss @zxpdemonio
+/python/mooncake/buffer_pool.py @ykwd @stmatengss
+/python/mooncake/ep.py @UNIDY2002 @ympcMark @yuechen-sys
+/python/mooncake/mooncake_config.py @ykwd @stmatengss
+/python/mooncake/mooncake_elastic_buffer.py @UNIDY2002 @ympcMark @yuechen-sys
+/python/mooncake/mooncake_ep_buffer.py @UNIDY2002 @ympcMark @yuechen-sys
+/python/tests/ep/ @UNIDY2002 @ympcMark @yuechen-sys
+/python/mooncake/cli.py @ykwd @stmatengss @zxpdemonio
+/python/mooncake/cli_client.py @ykwd @stmatengss @zxpdemonio
+/python/mooncake/cli_bench.py @ShangmingCai @alogfans @stmatengss
+/python/mooncake/transfer_engine_topology_dump.py @ShangmingCai @alogfans @stmatengss
+/python/tests/integration/test_cli.py @ShangmingCai @stmatengss @zxpdemonio
+/python/tests/unit/test_cli_modules.py @ShangmingCai @stmatengss @zxpdemonio
+/python/tests/store/ @ykwd @stmatengss
+/python/tests/unit/test_mooncake_config.py @ykwd @stmatengss
+/python/mooncake/mooncake_ssd_*.py @ykwd @stmatengss
+/python/mooncake/spdk_tgt_create.py @ykwd @stmatengss
+/python/tests/ssd/ @ykwd @stmatengss
 /mooncake-transfer-engine @alogfans @doujiang24 @chestnut-Q @staryxchen
 /mooncake-transfer-engine/tent @alogfans @doujiang24 @chestnut-Q @staryxchen @00fish0 @dtcccc
 /mooncake-transfer-engine/*/transport/hip_transport/ @alogfans @amd-arozanov
diff --git a/.github/actions/ctest-diagnostics/action.yml b/.github/actions/ctest-diagnostics/action.yml
new file mode 100644
index 0000000000..eca7e3d6ae
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/action.yml
@@ -0,0 +1,50 @@
+name: Preserve CTest failure diagnostics
+description: Summarize a failed CTest run and upload its logs and JUnit report
+
+inputs:
+  summary-title:
+    description: Heading to add to the GitHub Actions job summary
+    required: true
+  artifact-name:
+    description: Name of the uploaded diagnostics artifact
+    required: true
+  junit-report:
+    description: Path to the CTest JUnit XML report
+    required: true
+  failed-tests-log:
+    description: Path to CTest's LastTestsFailed.log
+    required: true
+  last-test-log:
+    description: Path to CTest's LastTest.log
+    required: true
+  retention-days:
+    description: Number of days to retain the diagnostics artifact
+    required: false
+    default: "14"
+
+runs:
+  using: composite
+  steps:
+    - name: Add CTest failure summary
+      env:
+        SUMMARY_TITLE: ${{ inputs.summary-title }}
+        FAILED_TESTS_LOG: ${{ inputs.failed-tests-log }}
+        LAST_TEST_LOG: ${{ inputs.last-test-log }}
+      shell: bash
+      run: |
+        "$GITHUB_ACTION_PATH/summarize.sh" \
+          "$SUMMARY_TITLE" \
+          "$FAILED_TESTS_LOG" \
+          "$LAST_TEST_LOG"
+
+    - name: Upload CTest diagnostics
+      if: ${{ always() }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        if-no-files-found: warn
+        retention-days: ${{ inputs.retention-days }}
+        path: |
+          ${{ inputs.junit-report }}
+          ${{ inputs.last-test-log }}
+          ${{ inputs.failed-tests-log }}
diff --git a/.github/actions/ctest-diagnostics/summarize.sh b/.github/actions/ctest-diagnostics/summarize.sh
new file mode 100755
index 0000000000..d1d0c4b1dc
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/summarize.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -ne 3 ]]; then
+    echo "Usage: $0 <summary-title> <failed-tests-log> <last-test-log>" >&2
+    exit 2
+fi
+
+: "${GITHUB_STEP_SUMMARY:?GITHUB_STEP_SUMMARY must be set}"
+
+readonly SUMMARY_TITLE="$1"
+readonly FAILED_TESTS_LOG="$2"
+readonly LAST_TEST_LOG="$3"
+
+{
+    echo "## $SUMMARY_TITLE"
+    echo
+
+    if [[ -s "$FAILED_TESTS_LOG" ]]; then
+        echo "### Failed CTest targets"
+        echo '```text'
+        cat "$FAILED_TESTS_LOG"
+        echo '```'
+    fi
+
+    if [[ -s "$LAST_TEST_LOG" ]]; then
+        failed_cases=$(grep -E '^\[  FAILED  \]' "$LAST_TEST_LOG" |
+            sed -E \
+                -e '/^\[  FAILED  \] [0-9]+ tests?, listed below:$/d' \
+                -e 's/ \([0-9]+ ms\)$//' |
+            sort -u || true)
+        if [[ -n "$failed_cases" ]]; then
+            echo "### Failed test cases"
+            echo '```text'
+            echo "$failed_cases"
+            echo '```'
+        fi
+
+        failure_context=$(grep -n -B2 -A8 -E \
+            -e ':[0-9]+: Failure$' \
+            -e 'Assertion .* failed\.$' \
+            -e '(ERROR|WARNING): (AddressSanitizer|LeakSanitizer|ThreadSanitizer|UndefinedBehaviorSanitizer)' \
+            -e 'runtime error:|Segmentation fault|terminate called' \
+            "$LAST_TEST_LOG" | sed -n '1,200p' || true)
+        if [[ -n "$failure_context" ]]; then
+            echo "### Failure context"
+            echo '```text'
+            echo "$failure_context"
+            echo '```'
+        fi
+    else
+        echo "CTest did not produce LastTest.log. Check the failed step for setup errors."
+    fi
+
+    echo
+    echo "Download the CTest diagnostics artifact for the complete log and JUnit report."
+} >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/actions/ctest-diagnostics/test.sh b/.github/actions/ctest-diagnostics/test.sh
new file mode 100755
index 0000000000..745f0fb5f1
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/test.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+readonly ACTION_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly FIXTURE_DIR="$ACTION_DIR/testdata"
+readonly SUMMARY_FILE="$(mktemp)"
+
+trap 'rm -f "$SUMMARY_FILE"' EXIT
+
+GITHUB_STEP_SUMMARY="$SUMMARY_FILE" "$ACTION_DIR/summarize.sh" \
+    "CTest failure fixture" \
+    "$FIXTURE_DIR/last-tests-failed.txt" \
+    "$FIXTURE_DIR/last-test.txt"
+
+diff -u "$FIXTURE_DIR/expected-summary.md" "$SUMMARY_FILE"
diff --git a/.github/actions/ctest-diagnostics/testdata/expected-summary.md b/.github/actions/ctest-diagnostics/testdata/expected-summary.md
new file mode 100644
index 0000000000..24cb45e6da
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/testdata/expected-summary.md
@@ -0,0 +1,43 @@
+## CTest failure fixture
+
+### Failed CTest targets
+```text
+1:google_test
+2:native_assertion
+3:tsan_test
+```
+### Failed test cases
+```text
+[  FAILED  ] FooTest.Bar
+```
+### Failure context
+```text
+3-1/3 Testing: google_test
+4-[ RUN      ] FooTest.Bar
+5:/workspace/foo_test.cpp:42: Failure
+6-Expected equality of these values:
+7-  1
+8-  actual
+9-    Which is: 2
+10-[  FAILED  ] FooTest.Bar (5 ms)
+11-[==========] 1 test from 1 test suite ran. (5 ms total)
+12-[  PASSED  ] 0 tests.
+13-[  FAILED  ] 1 test, listed below:
+--
+15-
+16-2/3 Testing: native_assertion
+17:native_assertion: /workspace/assert.cpp:17: int main(): Assertion 'ready' failed.
+18-Subprocess aborted
+19-
+20-3/3 Testing: tsan_test
+21:WARNING: ThreadSanitizer: data race (pid=123)
+22-  Write of size 4 at 0x7b0400000800 by thread T1:
+23-    #0 worker /workspace/worker.cpp:9
+24-
+25-SUMMARY: ThreadSanitizer: data race /workspace/worker.cpp:9 in worker
+26-ThreadSanitizer: reported 1 warnings
+27-
+28-End testing
+```
+
+Download the CTest diagnostics artifact for the complete log and JUnit report.
diff --git a/.github/actions/ctest-diagnostics/testdata/last-test.txt b/.github/actions/ctest-diagnostics/testdata/last-test.txt
new file mode 100644
index 0000000000..4331103b20
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/testdata/last-test.txt
@@ -0,0 +1,28 @@
+Start testing: fixture
+----------------------------------------------------------
+1/3 Testing: google_test
+[ RUN      ] FooTest.Bar
+/workspace/foo_test.cpp:42: Failure
+Expected equality of these values:
+  1
+  actual
+    Which is: 2
+[  FAILED  ] FooTest.Bar (5 ms)
+[==========] 1 test from 1 test suite ran. (5 ms total)
+[  PASSED  ] 0 tests.
+[  FAILED  ] 1 test, listed below:
+[  FAILED  ] FooTest.Bar
+
+2/3 Testing: native_assertion
+native_assertion: /workspace/assert.cpp:17: int main(): Assertion 'ready' failed.
+Subprocess aborted
+
+3/3 Testing: tsan_test
+WARNING: ThreadSanitizer: data race (pid=123)
+  Write of size 4 at 0x7b0400000800 by thread T1:
+    #0 worker /workspace/worker.cpp:9
+
+SUMMARY: ThreadSanitizer: data race /workspace/worker.cpp:9 in worker
+ThreadSanitizer: reported 1 warnings
+
+End testing
diff --git a/.github/actions/ctest-diagnostics/testdata/last-tests-failed.txt b/.github/actions/ctest-diagnostics/testdata/last-tests-failed.txt
new file mode 100644
index 0000000000..dfb4965678
--- /dev/null
+++ b/.github/actions/ctest-diagnostics/testdata/last-tests-failed.txt
@@ -0,0 +1,3 @@
+1:google_test
+2:native_assertion
+3:tsan_test
diff --git a/.github/actions/run-ctest/action.yml b/.github/actions/run-ctest/action.yml
new file mode 100644
index 0000000000..03be26af77
--- /dev/null
+++ b/.github/actions/run-ctest/action.yml
@@ -0,0 +1,21 @@
+name: Run Mooncake CTest suite
+description: Run the source-build CTest suite with shared runtime settings
+inputs:
+  reserve-rpc-port:
+    description: Reserve the Mooncake client RPC port from ephemeral allocation
+    default: 'true'
+  junit-report:
+    description: Optional repository-relative JUnit output path
+    default: ''
+  label-exclude:
+    description: Optional CTest label regex to exclude
+    default: ''
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      env:
+        RESERVE_RPC_PORT: ${{ inputs.reserve-rpc-port }}
+        JUNIT_REPORT: ${{ inputs.junit-report }}
+        CTEST_LABEL_EXCLUDE: ${{ inputs.label-exclude }}
+      run: bash "$GITHUB_ACTION_PATH/run.sh"
diff --git a/.github/actions/run-ctest/run.sh b/.github/actions/run-ctest/run.sh
new file mode 100644
index 0000000000..5efd41a4cd
--- /dev/null
+++ b/.github/actions/run-ctest/run.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -e -o pipefail
+
+if [ "$RESERVE_RPC_PORT" = true ]; then
+  reserved_ports=$(sysctl -n net.ipv4.ip_local_reserved_ports)
+  sudo sysctl -w "net.ipv4.ip_local_reserved_ports=${reserved_ports:+$reserved_ports,}50052"
+fi
+args=(--parallel "$(nproc)" --output-on-failure)
+if [ -n "${CTEST_LABEL_EXCLUDE:-}" ]; then
+  args+=(--label-exclude "$CTEST_LABEL_EXCLUDE")
+fi
+if [ -n "$JUNIT_REPORT" ]; then
+  report="$GITHUB_WORKSPACE/$JUNIT_REPORT"
+  mkdir -p "$(dirname "$report")"
+  args+=(--output-junit "$report")
+fi
+cd build
+export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
+DEFAULT_KV_LEASE_TTL=500 \
+  ctest "${args[@]}"
diff --git a/.github/actions/setup-cuda-runtime/action.yml b/.github/actions/setup-cuda-runtime/action.yml
new file mode 100644
index 0000000000..d914c363af
--- /dev/null
+++ b/.github/actions/setup-cuda-runtime/action.yml
@@ -0,0 +1,8 @@
+name: Expose the CMake-selected CUDA driver runtime
+description: Expose the CMake-selected CUDA driver runtime
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: bash "$GITHUB_ACTION_PATH/run.sh"
diff --git a/.github/actions/setup-cuda-runtime/run.sh b/.github/actions/setup-cuda-runtime/run.sh
new file mode 100644
index 0000000000..0708a7f8eb
--- /dev/null
+++ b/.github/actions/setup-cuda-runtime/run.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e -o pipefail
+
+cuda_driver_library=$(sed -n \
+  's/^CUDA_cuda_driver_LIBRARY:FILEPATH=//p' build/CMakeCache.txt)
+if [ -z "$cuda_driver_library" ] || [ ! -f "$cuda_driver_library" ]; then
+  echo "::error::CMake did not resolve the CUDA driver library"
+  exit 1
+fi
+
+cuda_driver_dir=$(dirname "$cuda_driver_library")
+if [ ! -e "$cuda_driver_dir/libcuda.so.1" ]; then
+  sudo ln -s "$(basename "$cuda_driver_library")" \
+    "$cuda_driver_dir/libcuda.so.1"
+fi
+echo "LIBRARY_PATH=$cuda_driver_dir:${LIBRARY_PATH:-}" >> "$GITHUB_ENV"
+echo "LD_LIBRARY_PATH=$cuda_driver_dir:${LD_LIBRARY_PATH:-}" >> "$GITHUB_ENV"
diff --git a/.github/actions/setup-etcd/action.yml b/.github/actions/setup-etcd/action.yml
new file mode 100644
index 0000000000..126e2bfda9
--- /dev/null
+++ b/.github/actions/setup-etcd/action.yml
@@ -0,0 +1,8 @@
+name: Install and start the CI etcd service
+description: Install and start the CI etcd service
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: bash "$GITHUB_ACTION_PATH/run.sh"
diff --git a/.github/actions/setup-etcd/run.sh b/.github/actions/setup-etcd/run.sh
new file mode 100644
index 0000000000..41d23095ea
--- /dev/null
+++ b/.github/actions/setup-etcd/run.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -e -o pipefail
+
+wget -q https://github.com/etcd-io/etcd/releases/download/v3.6.1/etcd-v3.6.1-linux-amd64.tar.gz
+tar xzf etcd-v3.6.1-linux-amd64.tar.gz
+sudo mv etcd-v3.6.1-linux-amd64/etcd* /usr/local/bin/
+etcd --advertise-client-urls http://127.0.0.1:2379 --listen-client-urls http://127.0.0.1:2379 &
+sleep 3
+ETCDCTL_API=3 etcdctl --endpoints=http://127.0.0.1:2379 endpoint health
diff --git a/.github/actions/setup-metadata-server/action.yml b/.github/actions/setup-metadata-server/action.yml
new file mode 100644
index 0000000000..3e75b3bccd
--- /dev/null
+++ b/.github/actions/setup-metadata-server/action.yml
@@ -0,0 +1,8 @@
+name: Start the CI HTTP metadata service
+description: Start the CI HTTP metadata service
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: bash "$GITHUB_ACTION_PATH/run.sh"
diff --git a/.github/actions/setup-metadata-server/run.sh b/.github/actions/setup-metadata-server/run.sh
new file mode 100644
index 0000000000..711738bef6
--- /dev/null
+++ b/.github/actions/setup-metadata-server/run.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -e -o pipefail
+
+cd mooncake-transfer-engine/example/http-metadata-server-python
+pip install aiohttp
+python ./bootstrap_server.py &
+echo "NIGHTLY_METADATA_SERVER_PID=$!" >> "$GITHUB_ENV"
+sleep 2
diff --git a/.github/actions/setup-sccache/action.yml b/.github/actions/setup-sccache/action.yml
new file mode 100644
index 0000000000..f9cb3af713
--- /dev/null
+++ b/.github/actions/setup-sccache/action.yml
@@ -0,0 +1,12 @@
+name: Set up sccache with GitHub Actions cache credentials
+description: Set up sccache with GitHub Actions cache credentials
+
+runs:
+  using: composite
+  steps:
+    - uses: mozilla-actions/sccache-action@v0.0.9
+    - uses: actions/github-script@v7
+      with:
+        script: |
+          core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
+          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
diff --git a/.github/labeler.yml b/.github/labeler.yml
index aa76d0be22..4e55945282 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -5,11 +5,29 @@ run-ci:
 
 store:
   - changed-files:
-    - any-glob-to-any-file: 'mooncake-store/**/*'
+    - any-glob-to-any-file:
+      - 'mooncake-store/**/*'
+      - 'python/mooncake/async_store.py'
+      - 'python/mooncake/cli.py'
+      - 'python/mooncake/cli_client.py'
+      - 'python/mooncake/buffer_pool.py'
+      - 'python/mooncake/mooncake_config.py'
+      - 'python/tests/store/**/*'
+      - 'python/tests/unit/test_mooncake_config.py'
+      - 'python/mooncake/mooncake_ssd_*.py'
+      - 'python/mooncake/spdk_tgt_create.py'
+      - 'python/tests/ssd/**/*'
+
+Mooncake Conductor:
+  - changed-files:
+    - any-glob-to-any-file: 'mooncake-conductor/**/*'
 
 Transfer Engine:
   - changed-files:
-    - any-glob-to-any-file: 'mooncake-transfer-engine/**/*'
+    - any-glob-to-any-file:
+      - 'mooncake-transfer-engine/**/*'
+      - 'python/mooncake/cli_bench.py'
+      - 'python/mooncake/transfer_engine_topology_dump.py'
 
 PyTorch Backend:
   - changed-files:
@@ -17,11 +35,21 @@ PyTorch Backend:
 
 Mooncake EP:
   - changed-files:
-    - any-glob-to-any-file: 'mooncake-ep/**/*'
+    - any-glob-to-any-file:
+      - 'mooncake-ep/**/*'
+      - 'python/mooncake/ep.py'
+      - 'python/mooncake/mooncake_elastic_buffer.py'
+      - 'python/mooncake/mooncake_ep_buffer.py'
+      - 'python/tests/ep/**/*'
 
 Installation:
   - changed-files:
-    - any-glob-to-any-file: 'mooncake-wheel/**/*'
+    - any-glob-to-any-file:
+      - 'mooncake-wheel/**/*'
+      - 'python/mooncake/cli.py'
+      - 'python/mooncake/cli_client.py'
+      - 'python/mooncake/cli_bench.py'
+      - 'python/mooncake/transfer_engine_topology_dump.py'
 
 P2P Store:
   - changed-files:
@@ -33,7 +61,9 @@ Integration:
 
 Common:
   - changed-files:
-    - any-glob-to-any-file: 'mooncake-common/**/*'
+    - any-glob-to-any-file:
+      - 'mooncake-common/**/*'
+      - 'mooncake-reshard/**/*'
 
 CI/Build:
   - changed-files:
@@ -54,6 +84,8 @@ Tests:
     - any-glob-to-any-file:
       - 'scripts/test_*'
       - 'mooncake-wheel/tests/**/*'
+      - 'mooncake-reshard/tests/**/*'
+      - 'python/tests/**/*'
       - 'scripts/tone_tests/**/*'
 
 Ascend/NPU:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index a926d40787..dae6b530d8 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -6,6 +6,8 @@
 
 - [ ] Transfer Engine (`mooncake-transfer-engine`)
 - [ ] Mooncake Store (`mooncake-store`)
+- [ ] Mooncake Conductor (`mooncake-conductor`)
+- [ ] Reshard (`mooncake-reshard`)
 - [ ] Mooncake EP (`mooncake-ep`)
 - [ ] Mooncake PG (`mooncake-pg`)
 - [ ] Integration (`mooncake-integration`)
@@ -45,7 +47,7 @@
 
 - [ ] I have performed a self-review of my own code
 - [ ] I have formatted my code using `./scripts/code_format.sh`
-- [ ] I have run `pre-commit run --all-files` and all hooks pass
+- [ ] I have run pre-commit on the files changed in this PR and all hooks pass
 - [ ] I have updated the documentation (if applicable)
 - [ ] I have added tests to prove my changes are effective
 - [ ] For changes >500 LOC: I have filed an RFC issue
diff --git a/.github/workflows/_build-efa-wheel.yaml b/.github/workflows/_build-efa-wheel.yaml
index 730e7d87cc..ba03d3b2f7 100644
--- a/.github/workflows/_build-efa-wheel.yaml
+++ b/.github/workflows/_build-efa-wheel.yaml
@@ -11,9 +11,6 @@ on:
         # cuda | cuda13 | non-cuda
         type: string
         required: true
-      use-cuda:
-        type: boolean
-        required: true
       python-versions:
         # JSON array consumed by the called workflow's Python matrix.
         type: string
@@ -25,13 +22,6 @@ on:
       cmake-args:
         type: string
         required: true
-      variant-flag:
-        # build_wheel.sh package variant, e.g. EFA_BUILD.
-        type: string
-        required: true
-      cuda-version:
-        type: string
-        default: '12.8.1'
       torch-cuda-arch-list:
         type: string
         default: ''
@@ -52,9 +42,10 @@ jobs:
       BUILD_PROFILE: ${{ inputs.build-profile }}
       CMAKE_ARGS: ${{ inputs.cmake-args }}
       EFA_VARIANT: ${{ inputs.variant }}
-      USE_CUDA: ${{ inputs.use-cuda }}
-      VARIANT_FLAG: ${{ inputs.variant-flag }}
-      CUDA_VERSION: ${{ inputs.cuda-version }}
+      USE_CUDA: ${{ inputs.variant != 'non-cuda' }}
+      VARIANT_FLAG: ${{ fromJSON('{"cuda":"EFA_BUILD","cuda13":"EFA_CU13_BUILD","non-cuda":"EFA_NON_CUDA_BUILD"}')[inputs.variant] }}
+      CUDA_VERSION: ${{ inputs.variant == 'cuda13' && '13.0.2' || '12.8.1' }}
+      TORCH_CUDA_ARCH_LIST: ${{ inputs.torch-cuda-arch-list }}
 
     steps:
       - name: Validate build inputs
@@ -64,19 +55,12 @@ jobs:
             *) echo "::error::Unknown EFA build profile: $BUILD_PROFILE"; exit 1 ;;
           esac
 
-          case "$EFA_VARIANT:$USE_CUDA:$VARIANT_FLAG" in
-            cuda:true:EFA_BUILD|cuda13:true:EFA_CU13_BUILD|non-cuda:false:EFA_NON_CUDA_BUILD) ;;
-            *) echo "::error::Inconsistent EFA variant inputs"; exit 1 ;;
+          case "$EFA_VARIANT" in
+            cuda|cuda13|non-cuda) ;;
+            *) echo "::error::Unknown EFA variant: $EFA_VARIANT"; exit 1 ;;
           esac
         shell: bash
 
-      - name: Configure CUDA architecture list
-        if: ${{ inputs.torch-cuda-arch-list != '' }}
-        env:
-          ARCH_LIST: ${{ inputs.torch-cuda-arch-list }}
-        run: echo "TORCH_CUDA_ARCH_LIST=$ARCH_LIST" >> "$GITHUB_ENV"
-        shell: bash
-
       - name: Checkout source
         uses: actions/checkout@v4
         with:
@@ -91,10 +75,10 @@ jobs:
         uses: ./.github/actions/free-disk-space
 
       - name: Install CUDA Toolkit
-        if: ${{ inputs.use-cuda }}
+        if: ${{ inputs.variant != 'non-cuda' }}
         uses: Jimver/cuda-toolkit@v0.2.29
         with:
-          cuda: ${{ inputs.cuda-version }}
+          cuda: ${{ env.CUDA_VERSION }}
           method: 'network'
           sub-packages: '["nvcc", "nvrtc-dev"]'
           non-cuda-sub-packages: '["libcusparse-dev", "libcublas-dev", "libcusolver-dev"]'
@@ -201,7 +185,7 @@ jobs:
         shell: bash
 
       - name: Verify CUDA runtime dependency
-        if: ${{ inputs.use-cuda }}
+        if: ${{ inputs.variant != 'non-cuda' }}
         run: |
           WHL=$(ls mooncake-wheel/dist-py${{ steps.python-tag.outputs.python_version_tag }}/*.whl | head -1)
           inspect_dir=$(mktemp -d)
diff --git a/.github/workflows/_build-wheel.yaml b/.github/workflows/_build-wheel.yaml
index 11216c6c7d..c1ca05335c 100644
--- a/.github/workflows/_build-wheel.yaml
+++ b/.github/workflows/_build-wheel.yaml
@@ -62,17 +62,17 @@ jobs:
               variant_flag=''
               generator=''
               arch_list='8.0;9.0'
-              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0'
+              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0;2.14.0'
               build_nvlink=true
-              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DUSE_CUDA=ON -DWITH_EP=ON -DSTORE_USE_ETCD=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
+              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DUSE_CUDA=ON -DUSE_INTRA_NVLINK=ON -DWITH_EP=ON -DSTORE_USE_ETCD=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
               ;;
             cuda13:x86_64)
               variant_flag=CU13_BUILD
               generator=''
-              arch_list='8.0;9.0'
-              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0'
+              arch_list='8.0;9.0;10.3'
+              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0;2.14.0'
               build_nvlink=true
-              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DUSE_CUDA=ON -DWITH_EP=ON -DSTORE_USE_ETCD=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
+              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DUSE_CUDA=ON -DUSE_INTRA_NVLINK=ON -DWITH_EP=ON -DSTORE_USE_ETCD=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
               ;;
             non-cuda:x86_64)
               variant_flag=NON_CUDA_BUILD
@@ -82,16 +82,21 @@ jobs:
               build_nvlink=false
               cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DUSE_CUDA=OFF -DWITH_EP=OFF -DSTORE_USE_ETCD=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
               ;;
-            cuda:arm64|cuda13:arm64)
+            cuda:arm64)
               variant_flag=''
-              if [ "$BUILD_VARIANT" = cuda13 ]; then
-                variant_flag=CU13_BUILD
-              fi
               generator=Ninja
               arch_list='9.0'
-              ep_versions=''
+              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0;2.14.0'
               build_nvlink=false
-              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_CUDA=ON -DUSE_MNNVL=ON -DWITH_EP=OFF -DWITH_STORE_RUST=OFF -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
+              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_CUDA=ON -DUSE_MNNVL=ON -DWITH_EP=ON -DWITH_STORE_RUST=OFF -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
+              ;;
+            cuda13:arm64)
+              variant_flag=CU13_BUILD
+              generator=Ninja
+              arch_list='9.0;10.3'
+              ep_versions='2.11.0;2.12.0;2.12.1;2.13.0;2.14.0'
+              build_nvlink=false
+              cmake_args='-DBUILD_UNIT_TESTS=OFF -DUSE_HTTP=ON -DUSE_CUDA=ON -DUSE_MNNVL=ON -DWITH_EP=ON -DWITH_STORE_RUST=OFF -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Release'
               ;;
             non-cuda:arm64)
               variant_flag=NON_CUDA_BUILD
@@ -106,6 +111,7 @@ jobs:
               exit 1
               ;;
           esac
+          cmake_args="$cmake_args -DENABLE_KV_EVENTS=ON"
 
           {
             echo "VARIANT_FLAG=$variant_flag"
@@ -209,6 +215,7 @@ jobs:
           VERSION: ${{ env.VERSION }}
 
       - name: Smoke test repaired wheel
+        shell: bash
         run: |
           smoke_venv=$(mktemp -d)
           python -m venv "$smoke_venv"
@@ -218,11 +225,20 @@ jobs:
           if [ "${VARIANT_FLAG:-}" = "NON_CUDA_BUILD" ]; then
             site_packages=$("$smoke_venv/bin/python" -c \
               'import sysconfig; print(sysconfig.get_paths()["purelib"])')
-            master="$site_packages/mooncake/mooncake_master"
-            if readelf -d "$master" | grep -Eq \
-              'Shared library: \[(libcuda|libcudart)\.so'; then
-              echo "Non-CUDA mooncake_master depends on CUDA"
-              readelf -d "$master" | grep 'Shared library:'
+            cuda_dependency_found=false
+            for package_path in "$site_packages"/mooncake*; do
+              [ -e "$package_path" ] || continue
+              while IFS= read -r -d '' file; do
+                cuda_dependencies=$(readelf -d "$file" 2>/dev/null | grep -E \
+                  'Shared library: \[(libcuda|libcudart|libcublas|libcufft|libcurand|libcusolver|libcusparse|libcufile|libcupti|libnvrtc|libnvJitLink|libnvToolsExt|libnvfatbin|libnvidia|libnccl)\.so' || true)
+                if [ -n "$cuda_dependencies" ]; then
+                  echo "::error file=$file::Non-CUDA wheel artifact depends on CUDA"
+                  echo "$cuda_dependencies"
+                  cuda_dependency_found=true
+                fi
+              done < <(find "$package_path" -type f -print0)
+            done
+            if [ "$cuda_dependency_found" = true ]; then
               exit 1
             fi
           fi
diff --git a/.github/workflows/ci-on-label.yml b/.github/workflows/ci-on-label.yml
new file mode 100644
index 0000000000..f4d5929ca6
--- /dev/null
+++ b/.github/workflows/ci-on-label.yml
@@ -0,0 +1,53 @@
+name: Retrigger CI on run-ci label
+
+# Same-SHA retrigger for Build & Test. This is a separate workflow so labels
+# other than `run-ci` (especially `run-e2e-ci`) cannot start or cancel
+# `.github/workflows/ci.yml`.
+#
+# pull_request_target is required so fork PRs can rerun Actions. This
+# workflow only calls the GitHub API; it does not check out PR code.
+on:
+  pull_request_target:
+    branches:
+      - "main"
+      - "release/**"
+    types: [labeled]
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  retrigger:
+    if: >
+      github.event.label.name == 'run-ci' &&
+      github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Re-run Build & Test for this SHA
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          run_json=$(gh api \
+            "repos/${REPO}/actions/workflows/ci.yml/runs?head_sha=${SHA}&per_page=20")
+          run_id=$(echo "$run_json" | jq -r '.workflow_runs[0].id // empty')
+          status=$(echo "$run_json" | jq -r '.workflow_runs[0].status // empty')
+
+          if [ -z "$run_id" ]; then
+            echo "No Build & Test run found for SHA ${SHA}."
+            echo "Open or push to the PR first so ci.yml has a run to rerun."
+            exit 1
+          fi
+
+          echo "Matched workflow run ${run_id} (status=${status})"
+          if [ "$status" != "completed" ]; then
+            echo "Build & Test is still ${status}; not starting a duplicate."
+            exit 0
+          fi
+
+          gh run rerun "$run_id" --repo "$REPO"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 52f9955b11..99c59bda48 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,163 +9,26 @@ on:
     branches:
       - "main"
       - "release/**"
-    types: [opened, synchronize, reopened, labeled]
+    # `labeled` is intentionally omitted. Auto-labeler already applies
+    # `run-ci`, so any new label (including `run-e2e-ci`) would retrigger
+    # this whole workflow and cancel the in-progress run. Same-SHA
+    # retrigger via the `run-ci` label lives in ci-on-label.yml.
+    types: [opened, synchronize, reopened]
   workflow_dispatch: {}
 
 permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref_name }}-${{ github.event.pull_request.number || github.sha }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
-  build:
-    needs: [spell-check, clang-format, check-paths]
-    if: &run-ci-for-source-changes >-
-      (needs.check-paths.outputs.should-run-downstream == 'true' ||
-       github.event_name == 'workflow_dispatch') &&
-      (github.event_name == 'push' ||
-       github.event_name == 'workflow_dispatch' ||
-       github.event.action == 'opened' ||
-       contains(github.event.pull_request.labels.*.name, 'run-ci'))
-    runs-on: ubuntu-22.04
-    strategy:
-      matrix:
-        python-version: ['3.10', '3.12']
-    env:
-      CI: "true"
-      SCCACHE_GHA_ENABLED: "true"
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
-
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install Rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-
-    - name: Install and start etcd
-      run: |
-        wget https://github.com/etcd-io/etcd/releases/download/v3.6.1/etcd-v3.6.1-linux-amd64.tar.gz
-        tar xzf etcd-v3.6.1-linux-amd64.tar.gz
-        sudo mv etcd-v3.6.1-linux-amd64/etcd* /usr/local/bin/
-        etcd --advertise-client-urls http://127.0.0.1:2379 --listen-client-urls http://127.0.0.1:2379 &
-        sleep 3 # Give etcd time to start
-        etcdctl --endpoints=http://127.0.0.1:2379 endpoint health
-      shell: bash
-
-    - name: Free up disk space
-      uses: ./.github/actions/free-disk-space
-
-    - name: Install CUDA Toolkit
-      uses: Jimver/cuda-toolkit@v0.2.24
-      with:
-        cuda: '12.8.1'
-        linux-local-args: '["--toolkit"]'
-        method: 'network'
-        sub-packages: '["nvcc"]'
-
-    - name: Install build utilities
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y ninja-build
-
-    - name: Test HugeTLB sizing helper
-      run: |
-        python3 scripts/test_hicache_hugepage_requirements.py
-      shell: bash
-
-    - name: Run sccache-cache
-      uses: mozilla-actions/sccache-action@v0.0.9
-
-    - name: Configure sccache
-      uses: actions/github-script@v7
-      with:
-        script: |
-          core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
-          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
-
-    - name: Configure project
-      run: |
-        sudo apt update -y
-        sudo bash -x dependencies.sh -y
-        mkdir build
-        cd build
-        cmake -G Ninja .. -DUSE_HTTP=ON -DUSE_CXL=ON -DUSE_UB=ON -DUSE_ETCD=ON -DSTORE_USE_ETCD=ON -DENABLE_ASAN=ON -DENABLE_SCCACHE=ON -DCMAKE_BUILD_TYPE=Debug -DENABLE_DEBUG_SYMBOLS=OFF
-      shell: bash
-
-    - name: Build project
-      run: |
-        cd build
-        cmake --build .
-        sudo cmake --install .
-      shell: bash
-
-    - name: Build nvlink_allocator.so
-      run: |
-        mkdir -p build/mooncake-transfer-engine/nvlink-allocator
-        cd mooncake-transfer-engine/nvlink-allocator
-        export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
-        bash build.sh ../../build/mooncake-transfer-engine/nvlink-allocator/
-      shell: bash
-
-    - name: Run sccache stat for check
-      if: ${{ env.SCCACHE_PATH != '' }}
-      shell: bash
-      run: ${SCCACHE_PATH} --show-stats
-
-    - name: Start Metadata Server
-      run: |
-        cd mooncake-transfer-engine/example/http-metadata-server-python
-        pip install aiohttp
-        python ./bootstrap_server.py &
-      shell: bash
-
-    - name: Run Mooncake Store Rust smoke test and benchmark
-      env:
-        MOONCAKE_STORE_CLUSTER_ID: ci_rust_test_cluster
-        MOONCAKE_STORE_RUST_LINK_ASAN: "1"
-      run: ./scripts/ci/run_store_rust_smoke.sh
-      shell: bash
-
-    - name: Run Go store binding integration tests
-      env:
-        MOONCAKE_STORE_CLUSTER_ID: ci_go_test_cluster
-        MOONCAKE_STORE_GO_LINK_COMMON: "1"
-        MOONCAKE_STORE_GO_SANITIZED: "1"
-      run: ./scripts/ci/run_store_go_integration.sh
-      shell: bash
-
-    - name: Test (in build env)
-      run: |
-        cd build
-        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
-        ldconfig -v || echo "always continue"
-        MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 ctest -j --output-on-failure
-      shell: bash
-
-    - name: Drain HTTP E2E test
-      if: matrix.python-version == '3.12'
-      run: |
-        cd build
-        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
-        # Keep the sanitizer gate on the C++ integration test. The Python
-        # drain script is manual/nightly only because pybind + ASan teardown in
-        # a Python host process is not stable.
-        DEFAULT_KV_LEASE_TTL=500 ./mooncake-store/tests/task_integration_test --gtest_filter='TaskExecutorIntegrationTest.DrainJobCompleteFlow'
-      shell: bash
-
   # Build the artifact tested below through the exact release wheel path. The
   # Ubuntu jobs remain consumer tests, not an alternate wheel build environment.
   build-wheel:
     needs: [spell-check, clang-format, check-paths]
-    if: *run-ci-for-source-changes
+    if: &run-ci-for-source-changes needs.check-paths.outputs.src == 'true'
     uses: ./.github/workflows/_build-wheel.yaml
     with:
       python-versions: '["3.10", "3.12"]'
@@ -173,17 +36,16 @@ jobs:
       version-override: 0.0.0.dev0
 
   test-wheel-ubuntu:
-    needs: [spell-check, clang-format, build-wheel]
-    if: >-
-      needs.build-wheel.result == 'success' &&
-      (github.event_name == 'push' ||
-       github.event_name == 'workflow_dispatch' ||
-       github.event.action == 'opened' ||
-       contains(github.event.pull_request.labels.*.name, 'run-ci'))
+    needs: [build-wheel]
     strategy:
       matrix:
-        ubuntu-version: [ubuntu-22.04, ubuntu-24.04]
-        python-version: ['3.10', '3.12']
+        include:
+          - ubuntu-version: ubuntu-22.04
+            python-version: '3.12'
+            artifact: mooncake-wheel-ci-py312
+          - ubuntu-version: ubuntu-24.04
+            python-version: '3.10'
+            artifact: mooncake-wheel-ci-py310
     runs-on: ${{ matrix.ubuntu-version }}
     steps:
     - uses: actions/checkout@v4
@@ -195,16 +57,10 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Generate Python version tag
-      id: generate_tag_test
-      run: |
-        echo "python_version_tag=$(echo ${{ matrix.python-version }} | tr -d '.')" >> $GITHUB_OUTPUT
-      shell: bash
-
     - name: Download wheel artifact
       uses: actions/download-artifact@v4
       with:
-        name: mooncake-wheel-ci-py${{ steps.generate_tag_test.outputs.python_version_tag }}
+        name: ${{ matrix.artifact }}
         path: mooncake-wheel/dist
 
     - name: Verify wheel file exists
@@ -231,35 +87,47 @@ jobs:
         bash scripts/test_installation.sh
       shell: bash
 
-    - name: Run tests with ssd
+    - name: Run tensor snapshot regressions
+      env:
+        MASTER_SERVER: "127.0.0.1:50061"
+        MC_METADATA_SERVER: "P2PHANDSHAKE"
+        LOCAL_HOSTNAME: "127.0.0.1"
+        DEFAULT_KV_LEASE_TTL: "500"
       run: |
-        # Reserve port 50052 (mooncake_client RPC port) so the kernel never
-        # auto-allocates it as ephemeral source port for other outbound
-        # connections in the test suite. Without this, a random Python test
-        # connection can pick src_port=50052, leave a TIME_WAIT on
-        # <eth0_ip>:50052 for 60s, and block mooncake_client's bind to
-        # 0.0.0.0:50052 even with SO_REUSEADDR (Linux only relaxes
-        # TIME_WAIT+bind conflict for same-IP or loopback).
-        sudo sysctl -w net.ipv4.ip_local_reserved_ports=50052
         source test_env/bin/activate
-        MC_STORE_MEMCPY=false TEST_SSD_OFFLOAD_IN_EVICT=true ./scripts/run_tests.sh
-        rm -rf /tmp/mooncake_test_ssd
-        deactivate
-      shell: bash
-
-    - name: Start Mooncake Master
+        export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+        mooncake_master --port 50061 --default_kv_lease_ttl=500 \
+          >"$RUNNER_TEMP/tensor-snapshot-master.log" 2>&1 &
+        master_pid=$!
+        trap 'kill "$master_pid" 2>/dev/null || true; wait "$master_pid" 2>/dev/null || true' EXIT
+        python - <<'PY'
+        import socket
+        import time
+        for attempt in range(100):
+            try:
+                with socket.create_connection(("127.0.0.1", 50061), timeout=0.2):
+                    break
+            except OSError:
+                time.sleep(0.1)
+        else:
+            raise RuntimeError("Tensor snapshot test master did not start")
+        PY
+        python mooncake-wheel/tests/test_tensor_read_snapshot.py -v
+        python mooncake-wheel/tests/test_cuda_fabric_compat.py -v
+      shell: bash
+
+    - name: Run all PG CPU tests with latest PyTorch
+      if: matrix.ubuntu-version == 'ubuntu-22.04' && matrix.python-version == '3.12'
+      env:
+        MC_FORCE_TCP: "true"
       run: |
         source test_env/bin/activate
-        mkdir -p /tmp/mooncake_storage
-        mooncake_master \
-          --eviction_high_watermark_ratio=0.95 \
-          --cluster_id=ci_test_cluster \
-          --port 50051 \
-          --enable_http_metadata_server=true &
-        sleep 3
+        export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+        python -m unittest discover -s mooncake-pg/tests -k CPU -v
       shell: bash
 
-    - name: Run Python Tensor API Performance Test (CI check)
+    - name: Run Store API and RPC smoke tests
+      if: matrix.ubuntu-version == 'ubuntu-22.04' && matrix.python-version == '3.12'
       env:
         MOONCAKE_MASTER: "127.0.0.1:50051"
         MOONCAKE_TE_META_DATA_SERVER: "http://127.0.0.1:8080/metadata"
@@ -267,96 +135,134 @@ jobs:
         LOCAL_HOSTNAME: "127.0.0.1"
       run: |
         source test_env/bin/activate
-        python scripts/test_tensor_api.py -n 1
+        export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+        python -m pip install safetensors
+
+        reserved_ports=$(sysctl -n net.ipv4.ip_local_reserved_ports)
+        sudo sysctl -w \
+          "net.ipv4.ip_local_reserved_ports=${reserved_ports:+$reserved_ports,}50052"
+
+        ./scripts/ci/run_store_api_smoke.sh
+        ./scripts/ci/run_rpc_smoke.sh
       shell: bash
 
-    - name: Run Python Async API Test (CI check)
-      env:
-        MOONCAKE_MASTER: "127.0.0.1:50051"
-        MOONCAKE_TE_META_DATA_SERVER: "http://127.0.0.1:8080/metadata"
-        MOONCAKE_PROTOCOL: "tcp"
-        LOCAL_HOSTNAME: "127.0.0.1"
+    - name: Run SSD offload and promotion end-to-end tests
+      if: matrix.ubuntu-version == 'ubuntu-22.04' && matrix.python-version == '3.12'
       run: |
         source test_env/bin/activate
-        python scripts/test_async_store.py
+        ./scripts/ci/run_ssd_offload_smoke.sh
       shell: bash
 
-    - name: Test Mooncake Copy/Move API
-      env:
-        MOONCAKE_MASTER: "127.0.0.1:50051"
-        MOONCAKE_TE_META_DATA_SERVER: "http://127.0.0.1:8080/metadata"
-        MOONCAKE_PROTOCOL: "tcp"
-        LOCAL_HOSTNAME: "127.0.0.1"
+  unit-tests:
+    name: CTest unit tests (Python 3.12)
+    needs: [check-paths]
+    if: *run-ci-for-source-changes
+    runs-on: ubuntu-22.04
+    env:
+      CI: "true"
+      SCCACHE_GHA_ENABLED: "true"
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+
+    - name: Install and start etcd
+      uses: ./.github/actions/setup-etcd
+
+    - name: Free up disk space
+      uses: ./.github/actions/free-disk-space
+
+    - name: Install CUDA Toolkit
+      uses: Jimver/cuda-toolkit@v0.2.24
+      with:
+        cuda: '12.8.1'
+        linux-local-args: '["--toolkit"]'
+        method: 'network'
+        sub-packages: '["nvcc"]'
+
+    - name: Install build utilities and dependencies
       run: |
-        source test_env/bin/activate
-        python scripts/test_copy_move_api.py
+        sudo apt-get update
+        sudo apt-get install -y ninja-build
+        sudo bash -x dependencies.sh -y
+        echo "/usr/local/go/bin" >> "$GITHUB_PATH"
       shell: bash
 
-    - name: Run Python Drain HTTP E2E Test (CI check)
-      env:
-        MOONCAKE_MASTER: "127.0.0.1:50051"
-        MOONCAKE_TE_META_DATA_SERVER: "http://127.0.0.1:8080/metadata"
-        MOONCAKE_PROTOCOL: "tcp"
-        LOCAL_HOSTNAME: "127.0.0.1"
+    - name: Set up compiler cache
+      uses: ./.github/actions/setup-sccache
+
+    - name: Configure project with unit tests
       run: |
-        source test_env/bin/activate
-        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
-        python scripts/test_drain_http_api.py --timeout-sec 90
+        cmake -S . -B build -G Ninja \
+          -DUSE_HTTP=ON \
+          -DUSE_CXL=ON \
+          -DUSE_UB=ON \
+          -DUSE_ETCD=ON \
+          -DUSE_CUDA=ON \
+          -DUSE_MNNVL=ON \
+          -DWITH_P2P_STORE=ON \
+          -DWITH_CONDUCTOR=ON \
+          -DSTORE_USE_ETCD=ON \
+          -DCMAKE_BUILD_TYPE=Release \
+          -DBUILD_UNIT_TESTS=ON \
+          -DENABLE_SCCACHE=ON
       shell: bash
 
-    - name: Run RPC Communicator Bandwidth Test
-      run: |
-        source test_env/bin/activate
-        python mooncake-transfer-engine/tests/rpc_communicator_test.py server --url 127.0.0.1:9004 --data-size 1 &
-        SERVER_PID=$!
-        sleep 5
-        timeout 10 python mooncake-transfer-engine/tests/rpc_communicator_test.py client --url 127.0.0.1:9004 --threads 2 --data-size 1 || true
-        kill $SERVER_PID 2>/dev/null || true
-        wait $SERVER_PID 2>/dev/null || true
-
-    - name: Test Mooncake PyTorch Backend (CPU Only)
-      env:
-        MC_FORCE_TCP: "true"
+    - name: Configure CUDA driver runtime
+      uses: ./.github/actions/setup-cuda-runtime
+
+    - name: Build project and unit tests
       run: |
-        source test_env/bin/activate
-        python mooncake-pg/tests/test_pg_collectives.py
+        cmake --build build --parallel 128
+        sudo -E cmake --install build
       shell: bash
 
-    - name: Test PyTorch 2.13 Single-Buffer Collectives (CPU Only)
-      if: matrix.ubuntu-version == 'ubuntu-22.04' && matrix.python-version == '3.10'
+    - name: Run Mooncake Store Rust unit tests
       env:
-        MC_FORCE_TCP: "true"
+        MOONCAKE_BUILD_DIR: ${{ github.workspace }}/build
+        MOONCAKE_STORE_LIB_DIR: ${{ github.workspace }}/build/mooncake-store/src
+        MOONCAKE_STORE_INCLUDE_DIR: ${{ github.workspace }}/mooncake-store/include
       run: |
-        source test_env/bin/activate
-        python -m pip install --force-reinstall "torch==2.13.0" \
-          --index-url https://download.pytorch.org/whl/cu126 \
-          --extra-index-url https://pypi.org/simple
-        python mooncake-pg/tests/test_pg_collectives.py \
-          TestMooncakePGCollectivesCPU.test_all_gather_into_tensor \
-          TestMooncakePGCollectivesCPU.test_reduce_scatter_sum
+        export LD_LIBRARY_PATH="$GITHUB_WORKSPACE/build/mooncake-asio:$GITHUB_WORKSPACE/build/mooncake-store/src:$GITHUB_WORKSPACE/build/mooncake-store/src/cachelib_memory_allocator:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base:$GITHUB_WORKSPACE/build/mooncake-common/etcd:/usr/local/lib:${LD_LIBRARY_PATH:-}"
+        cargo test --manifest-path mooncake-store/rust/Cargo.toml --lib
       shell: bash
 
-    - name: Test Safetensor Functions
-      run: |
-        source test_env/bin/activate
-        pip install safetensors
-        python -m unittest mooncake-wheel.tests.test_safetensor_functions
-      shell: bash
+    - name: Start Metadata Server
+      uses: ./.github/actions/setup-metadata-server
+
+    - name: Run all CTest unit tests
+      id: ctest
+      uses: ./.github/actions/run-ctest
+      with:
+        junit-report: build/test-results/ctest.xml
+        label-exclude: '^nvlink_gpu$'
+
+    - name: Preserve CTest diagnostics
+      if: ${{ always() && steps.ctest.outcome == 'failure' }}
+      uses: ./.github/actions/ctest-diagnostics
+      with:
+        summary-title: PR CTest failure
+        artifact-name: ctest-diagnostics-pr
+        junit-report: build/test-results/ctest.xml
+        failed-tests-log: build/Testing/Temporary/LastTestsFailed.log
+        last-test-log: build/Testing/Temporary/LastTest.log
 
   build-flags:
-    needs: [spell-check, clang-format, check-paths]
+    needs: [check-paths]
     if: *run-ci-for-source-changes
     runs-on: ubuntu-22.04
-    strategy:
-      matrix:
-        python-version: ['3.10', '3.12']
     env:
       CI: "true"
-      TORCH_CUDA_ARCH_LIST: "8.0;9.0"
       SCCACHE_GHA_ENABLED: "true"
       PIP_NO_CACHE_DIR: "1"
-      MAX_JOBS: "2"
-      EP_TORCH_VERSIONS: "2.11.0;2.12.0;2.12.1;2.13.0"
       CMAKE_RELWITHDEBINFO_FLAGS: "-O2 -DNDEBUG"
 
     steps:
@@ -364,10 +270,10 @@ jobs:
       with:
         persist-credentials: false
 
-    - name: Set up Python ${{ matrix.python-version }}
+    - name: Set up Python 3.12
       uses: actions/setup-python@v5
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: '3.12'
 
     - name: Free up disk space
       uses: ./.github/actions/free-disk-space
@@ -381,15 +287,8 @@ jobs:
         sub-packages: '["nvcc", "nvrtc-dev"]'
         non-cuda-sub-packages: '["libcusparse-dev", "libcublas-dev", "libcusolver-dev"]'
 
-    - name: Run sccache-cache
-      uses: mozilla-actions/sccache-action@v0.0.9
-
-    - name: Configure sccache
-      uses: actions/github-script@v7
-      with:
-        script: |
-          core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
-          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+    - name: Set up compiler cache
+      uses: ./.github/actions/setup-sccache
 
     - name: Install dependencies
       run: |
@@ -399,9 +298,6 @@ jobs:
         df -h
       shell: bash
 
-    - name: Install Rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-
     - name: Build transfer engine only
       run: |
         cd mooncake-transfer-engine
@@ -433,149 +329,75 @@ jobs:
         df -h
       shell: bash
 
-    - name: Configure project with all settings are ON
-      run: |
-        mkdir build
-        cd build
-        # ENABLE_DEBUG_SYMBOLS=OFF alone still leaves CMake's RelWithDebInfo -g.
-        cmake -G Ninja .. \
-          -DUSE_ETCD=ON \
-          -DUSE_CXL=ON \
-          -DUSE_REDIS=ON \
-          -DUSE_HTTP=ON \
-          -DWITH_STORE=ON \
-          -DWITH_P2P_STORE=ON \
-          -DWITH_METRICS=ON \
-          -DBUILD_UNIT_TESTS=ON \
-          -DBUILD_EXAMPLES=ON \
-          -DENABLE_SCCACHE=ON \
-          -DUSE_CUDA=ON \
-          -DUSE_MNNVL=OFF \
-          -DUSE_UB=OFF \
-          -DCMAKE_EXE_LINKER_FLAGS="-L/usr/local/cuda/lib64/stubs" \
-          "-DCMAKE_C_FLAGS_RELWITHDEBINFO=${CMAKE_RELWITHDEBINFO_FLAGS}" \
-          "-DCMAKE_CXX_FLAGS_RELWITHDEBINFO=${CMAKE_RELWITHDEBINFO_FLAGS}" \
-          -DENABLE_DEBUG_SYMBOLS=OFF
-      shell: bash
-      # TODO: lack USE_NVMEOF,USE_MNNVL
-
-    - name: Build project with all settings are ON
-      run: |
-        export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
-        export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
-        cd build
-        cmake --build .
-        sudo cmake --install .
-        df -h
-      shell: bash
-
-    - name: Configure project with unit tests and examples
-      run: |
-        cd build
-        cmake -G Ninja .. -DBUILD_UNIT_TESTS=ON -DBUILD_EXAMPLES=ON -DWITH_STORE_RUST=ON -DENABLE_SCCACHE=ON -DENABLE_DEBUG_SYMBOLS=OFF
-      shell: bash
+  spell-check:
+    name: Spell Check with Typos
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Checkout Actions Repository
+      uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Spell Check Repo
+      uses: crate-ci/typos@v1.30.2
 
-    - name: Build project with unit tests and examples
-      run: |
-        export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
-        export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
-        cd build
-        cmake --build .
-        sudo cmake --install .
-      shell: bash
+  reshard-type-check:
+    name: Check reshard manifest types
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
 
-    - name: Check Mooncake Store Rust bindings, examples, and tests
-      run: |
-        # libcuda.so.1 (SONAME of the CUDA stub) must be findable at runtime.
-        # The toolkit stubs dir only ships libcuda.so; create the versioned symlink.
-        if [ -f /usr/local/cuda/lib64/stubs/libcuda.so ] && \
-           [ ! -e /usr/local/cuda/lib64/stubs/libcuda.so.1 ]; then
-          sudo ln -s libcuda.so /usr/local/cuda/lib64/stubs/libcuda.so.1
-        fi
-        export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
-        cd mooncake-store/rust
-        export MOONCAKE_BUILD_DIR=$GITHUB_WORKSPACE/build
-        cargo test --lib
-        MOONCAKE_STORE_LIB_DIR=$GITHUB_WORKSPACE/build/mooncake-store/src \
-        MOONCAKE_STORE_INCLUDE_DIR=$GITHUB_WORKSPACE/mooncake-store/include \
-          cargo test --examples --tests --no-run
-        cargo clean
-      shell: bash
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
 
-    - name: Verify Mooncake Store Rust dlopen bindings and packaging
+    - name: Check canonical reshard contract types
       run: |
-        cd mooncake-store/rust
-        # 1. Committed dlopen bindings must stay in sync with store_c.h.
-        cargo run --locked --example generate_dlopen_bindings
-        git diff --exit-code -- src/generated/ffi_dlopen_bindings.rs
-        # 2. The published dlopen crate must build with no header/bindgen: package
-        #    it, extract, and check the dlopen feature against the packaged files.
-        cargo package --no-verify --allow-dirty
-        crate=$(ls target/package/mooncake_store-*.crate | head -1)
-        dest=$(mktemp -d)
-        tar xzf "$crate" -C "$dest"
-        (cd "$dest"/mooncake_store-* && cargo check --no-default-features --features dlopen)
+        python -m pip install --disable-pip-version-check pyright==1.1.411
+        bash scripts/check_reshard_types.sh
       shell: bash
 
-    - name: Configure project
-      run: |
-        cd build
-        rm -r */tests
-        cmake -G Ninja .. \
-          -DBUILD_UNIT_TESTS=OFF \
-          -DBUILD_EXAMPLES=OFF \
-          -DUSE_HTTP=ON \
-          -DENABLE_SCCACHE=ON \
-          -DUSE_CXL=ON \
-          -DWITH_EP=ON \
-          "-DEP_TORCH_VERSIONS=${EP_TORCH_VERSIONS}" \
-          -DENABLE_DEBUG_SYMBOLS=OFF
-      shell: bash
+  ci-script-tests:
+    name: Test CI scripts
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
 
-    - name: Build project
-      run: |
-        export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
-        export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
-        cd build
-        cmake --build .
-        sudo cmake --install .
-      shell: bash
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
 
-    - name: Build nvlink_allocator.so
+    - name: Run focused release gate tests
       run: |
-        mkdir -p build/mooncake-transfer-engine/nvlink-allocator
-        cd mooncake-transfer-engine/nvlink-allocator
-        export PATH=/usr/local/nvidia/bin:/usr/local/nvidia/lib64:$PATH
-        export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
-        export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
-        bash build.sh ../../build/mooncake-transfer-engine/nvlink-allocator/
-      shell: bash
-
-    - name: Run sccache stat for check
-      if: ${{ env.SCCACHE_PATH != '' }}
+        python -m pip install --disable-pip-version-check \
+          packaging pytest==8.3.5 pyyaml
+        python -m pytest -q mooncake-wheel/tests/test_testpypi_wheel_gate.py
       shell: bash
-      run: ${SCCACHE_PATH} --show-stats
 
+    - name: Test CI service and smoke scripts
+      run: python -m unittest discover -s scripts/ci/tests -v
 
-  spell-check:
-    name: Spell Check with Typos
-    if: &run-ci >-
-      (github.event_name == 'push' ||
-       github.event_name == 'workflow_dispatch' ||
-       github.event.action == 'opened' ||
-       contains(github.event.pull_request.labels.*.name, 'run-ci'))
+  tone-script-tests:
+    name: Test external CI lifecycle helpers
     runs-on: ubuntu-22.04
     steps:
-    - name: Checkout Actions Repository
-      uses: actions/checkout@v4
+    - uses: actions/checkout@v4
       with:
         persist-credentials: false
-    - name: Spell Check Repo
-      uses: crate-ci/typos@v1.30.2
+
+    - name: Run focused shell regression tests
+      run: |
+        bash scripts/tone_tests/tests/test_common_cleanup.sh
+        python3 scripts/tone_tests/tests/test_hicache_model_selection.py
+      shell: bash
 
   clang-format:
     name: Check code format
-    if: *run-ci
     runs-on: ubuntu-22.04
     steps:
     - name: Checkout Actions Repository
@@ -618,59 +440,86 @@ jobs:
         ./scripts/code_format.sh --check --changed-lines --base "${BASE_REF}"
       shell: bash
 
+  python-lint:
+    name: Check Python with Ruff
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        persist-credentials: false
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install Ruff
+      run: python -m pip install --disable-pip-version-check ruff==0.6.9
+
+    - name: Check changed Python files
+      run: |
+        if [ "${{ github.event_name }}" = "pull_request" ]; then
+          base_ref="origin/${{ github.base_ref }}"
+        elif [ "${{ github.event.before }}" = \
+               "0000000000000000000000000000000000000000" ]; then
+          base_ref="origin/${{ github.event.repository.default_branch }}"
+        elif [ -n "${{ github.event.before }}" ]; then
+          base_ref="${{ github.event.before }}"
+        else
+          base_ref="HEAD^"
+        fi
+
+        mapfile -d '' python_files < <(
+          git diff --name-only --diff-filter=ACMR -z "$base_ref"...HEAD -- \
+            '*.py' \
+            ':(exclude)extern/**' \
+            ':(exclude)FAST25-release/**'
+        )
+        if [ "${#python_files[@]}" -eq 0 ]; then
+          echo "No changed Python files to check."
+          exit 0
+        fi
+
+        ruff check "${python_files[@]}"
+        ruff format --check "${python_files[@]}"
+      shell: bash
+
 
   docs-check:
     name: Check Sphinx docs build
-    if: *run-ci
+    needs: check-paths
+    if: needs.check-paths.outputs.docs == 'true'
     runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
       with:
-        fetch-depth: 2
         persist-credentials: false
 
-    - uses: dorny/paths-filter@v3
-      id: filter
-      with:
-        filters: |
-          docs:
-            - 'docs/**'
-            - 'docs/requirements-docs.txt'
-
     - name: Set up Python
-      if: steps.filter.outputs.docs == 'true'
       uses: actions/setup-python@v5
       with:
         python-version: '3.12'
 
     - name: Install documentation dependencies
-      if: steps.filter.outputs.docs == 'true'
       run: |
         python -m pip install --upgrade pip
         pip install -r docs/requirements-docs.txt
 
     - name: Build docs with strict mode
-      if: steps.filter.outputs.docs == 'true'
-      run: |
-        cd docs
-        make html SPHINXOPTS=-W
-      shell: bash
-
+      working-directory: docs
+      run: make html SPHINXOPTS=-W
 
   check-paths:
-    if: *run-ci
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
-      should-run-downstream: ${{ steps.dispatch-override.outputs.src || steps.filter.outputs.src }}
-      should-run-tent: ${{ steps.dispatch-override.outputs.tent || steps.filter.outputs.tent }}
+      src: ${{ github.event_name == 'workflow_dispatch' && 'true' || steps.filter.outputs.src }}
+      tent: ${{ github.event_name == 'workflow_dispatch' && 'true' || steps.filter.outputs.tent }}
+      docs: ${{ github.event_name == 'workflow_dispatch' && 'true' || steps.filter.outputs.docs }}
     steps:
-      # workflow_dispatch has no PR/push diff context — skip paths-filter and default to true
-      - name: Default to true for workflow_dispatch
-        id: dispatch-override
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          echo "src=true" >> $GITHUB_OUTPUT
-          echo "tent=true" >> $GITHUB_OUTPUT
       - uses: actions/checkout@v4
         if: github.event_name != 'workflow_dispatch'
         with:
@@ -680,10 +529,14 @@ jobs:
         if: github.event_name != 'workflow_dispatch'
         id: filter
         with:
+          # PRs use their base branch; pushes compare against the previous push
+          # on this ref, including release branches.
+          base: ${{ github.event_name == 'push' && github.ref || '' }}
           filters: |
             src:
               - 'mooncake-*/**'
               - 'extern/**'
+              - 'cmake/**'
               - 'CMakeLists.txt'
               - 'dependencies.sh'
               - 'scripts/**'
@@ -691,9 +544,19 @@ jobs:
               - '.github/workflows/**'
             tent:
               - 'mooncake-transfer-engine/**'
+              - 'mooncake-store/src/transfer_task.cpp'
+              - 'mooncake-store/tests/transfer_task_test.cpp'
+              - 'mooncake-store/tests/CMakeLists.txt'
               - 'mooncake-common/**'
+              - 'extern/**'
+              - 'cmake/**'
               - 'CMakeLists.txt'
               - 'dependencies.sh'
+              - 'scripts/ci/run_transfer_engine_rust_smoke.sh'
+              - '.github/actions/**'
+              - '.github/workflows/ci.yml'
+            docs:
+              - 'docs/**'
               - '.github/workflows/ci.yml'
 
   build-wheel-cu13:
@@ -702,7 +565,7 @@ jobs:
     uses: ./.github/workflows/_build-wheel.yaml
     with:
       variant: cuda13
-      python-versions: '["3.10", "3.12"]'
+      python-versions: '["3.12"]'
       artifact-prefix: mooncake-wheel-cu130
       version-override: 0.0.0.dev0
 
@@ -714,31 +577,13 @@ jobs:
 
   build-wheel-rocm:
     needs: [spell-check, clang-format, check-paths]
-    if: >-
-      (needs.check-paths.outputs.should-run-downstream == 'true' ||
-       github.event_name == 'workflow_dispatch') &&
-      (github.event_name == 'push' ||
-       github.event_name == 'workflow_dispatch' ||
-       github.event.action == 'opened' ||
-       contains(github.event.pull_request.labels.*.name, 'run-ci'))
+    if: needs.check-paths.outputs.src == 'true'
     uses: ./.github/workflows/ci_rocm.yml
     secrets: inherit
 
-  integration-test:
-    needs: [build, build-wheel-cu13, check-paths]
-    if: needs.check-paths.outputs.should-run-downstream == 'true'
-    uses: ./.github/workflows/integration-test.yml
-    secrets: inherit
-
   tent-ci:
     needs: [spell-check, clang-format, check-paths]
-    if: >-
-      (needs.check-paths.outputs.should-run-tent == 'true' ||
-       github.event_name == 'workflow_dispatch') &&
-      (github.event_name == 'push' ||
-       github.event_name == 'workflow_dispatch' ||
-       github.event.action == 'opened' ||
-       contains(github.event.pull_request.labels.*.name, 'run-ci'))
+    if: needs.check-paths.outputs.tent == 'true'
     runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
@@ -749,7 +594,7 @@ jobs:
             need_cuda: true
             metrics_flags: ''
           - name: cuda-off
-            cmake_flags: '-DUSE_CUDA=OFF'
+            cmake_flags: '-DUSE_CUDA=OFF -DUSE_EVENT_DRIVEN_COMPLETION=ON'
             need_cuda: false
             metrics_flags: ''
           - name: cuda-off-metrics-on
@@ -785,15 +630,8 @@ jobs:
         method: 'network'
         sub-packages: '["nvcc", "nvrtc-dev"]'
 
-    - name: Run sccache-cache
-      uses: mozilla-actions/sccache-action@v0.0.9
-
-    - name: Configure sccache
-      uses: actions/github-script@v7
-      with:
-        script: |
-          core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
-          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+    - name: Set up compiler cache
+      uses: ./.github/actions/setup-sccache
 
     - name: Install dependencies
       run: |
@@ -803,6 +641,9 @@ jobs:
         df -h
       shell: bash
 
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+
     - name: Configure project with TENT
       run: |
         mkdir build-tent
@@ -821,27 +662,76 @@ jobs:
         sudo cmake --install .
       shell: bash
 
+    # Check the Transfer Engine Rust crate against the freshly built C++
+    # libraries. This is a compile/link check, so it is safe to run on every
+    # matrix leg (including the cuda-on leg, which only verifies that the
+    # USE_CUDA code paths compile).
+    - name: Check Transfer Engine Rust bindings, examples, and tests
+      run: |
+        if [ -f /usr/local/cuda/lib64/stubs/libcuda.so ] && \
+           [ ! -e /usr/local/cuda/lib64/stubs/libcuda.so.1 ]; then
+          sudo ln -s libcuda.so /usr/local/cuda/lib64/stubs/libcuda.so.1
+        fi
+        if [ "${{ matrix.need_cuda }}" = "true" ]; then
+          export LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LD_LIBRARY_PATH
+        fi
+        cd mooncake-transfer-engine/rust
+        export MOONCAKE_BUILD_DIR=$GITHUB_WORKSPACE/build-tent
+        export MOONCAKE_TE_LIB_DIR=$GITHUB_WORKSPACE/build-tent/mooncake-transfer-engine/src
+        export MOONCAKE_TE_INCLUDE_DIR=$GITHUB_WORKSPACE/mooncake-transfer-engine/include
+        cargo test --lib
+        cargo test --examples --tests --no-run
+        cargo clean
+      shell: bash
+
+    - name: Test Store completion with TENT
+      if: matrix.name == 'cuda-off'
+      run: |
+        ctest --test-dir build-tent --output-on-failure --no-tests=error \
+          -R '^transfer_task_tent_completion_test$'
+      shell: bash
+
     # Only run tests on the cuda-off leg. GitHub runners have no real GPU;
     # with USE_CUDA=ON tent's cuda_probe hits the CUDA stub library at
     # runtime and drives some dispatch paths past the fake objects the
     # unit tests rely on, causing false failures. cuda-on still validates
     # that every #ifdef USE_CUDA branch compiles.
     - name: Test (TENT)
+      id: ctest
       if: '!matrix.need_cuda'
       run: |
         cd build-tent
-        ctest --test-dir mooncake-transfer-engine/tent/tests -j --output-on-failure
+        mkdir -p test-results
+        ctest --test-dir mooncake-transfer-engine/tent/tests -j \
+          --output-on-failure \
+          --output-junit "$GITHUB_WORKSPACE/build-tent/test-results/ctest.xml"
       shell: bash
 
-    - name: Smoke test TENT UB benchmark CLI
-      if: matrix.name == 'ub-mock'
+    - name: Preserve TENT CTest diagnostics
+      if: ${{ always() && steps.ctest.outcome == 'failure' }}
+      uses: ./.github/actions/ctest-diagnostics
+      with:
+        summary-title: TENT CTest failure (${{ matrix.name }})
+        artifact-name: ctest-diagnostics-tent-${{ matrix.name }}
+        junit-report: build-tent/test-results/ctest.xml
+        failed-tests-log: build-tent/mooncake-transfer-engine/tent/tests/Testing/Temporary/LastTestsFailed.log
+        last-test-log: build-tent/mooncake-transfer-engine/tent/tests/Testing/Temporary/LastTest.log
+
+    - name: Start Metadata Server
+      if: '!matrix.need_cuda'
       run: |
-        cd build-tent
-        help_output="$(./mooncake-transfer-engine/benchmark/tebench \
-          --backend=tent --xport_type=ub --tent_transport_hint=ub \
-          --help 2>&1)"
-        grep -q 'iouring|ub|sunrise_link' <<< "${help_output}"
-        grep -q 'ascend|ub|sunrise_link' <<< "${help_output}"
+        cd mooncake-transfer-engine/example/http-metadata-server-python
+        pip install aiohttp
+        python ./bootstrap_server.py &
+        sleep 2
+      shell: bash
+
+    - name: Run Transfer Engine Rust smoke test
+      if: '!matrix.need_cuda'
+      env:
+        MOONCAKE_BUILD_DIR: ${{ github.workspace }}/build-tent
+        MOONCAKE_TE_RUST_LINK_ASAN: "0"
+      run: ./scripts/ci/run_transfer_engine_rust_smoke.sh
       shell: bash
 
     - name: Run sccache stat for check
@@ -853,31 +743,65 @@ jobs:
     name: CI Gate
     if: always()
     needs:
+      - check-paths
       - spell-check
       - clang-format
+      - python-lint
       - docs-check
-      - build
+      - reshard-type-check
+      - ci-script-tests
+      - tone-script-tests
       - build-wheel
+      - unit-tests
       - build-flags
       - test-wheel-ubuntu
       - build-wheel-cu13
       - build-wheel-efa
       - build-wheel-rocm
       - tent-ci
-      - integration-test
     runs-on: ubuntu-latest
     steps:
-      - name: Check required job results
-        run: |
-          failing=$(echo "$NEEDS_JSON" | jq -r '
-            to_entries[] |
-            select(.value.result != "success" and .value.result != "skipped") |
-            "\(.key): \(.value.result)"')
-          if [ -n "$failing" ]; then
-            echo "::error::The following jobs failed or were cancelled:"
-            echo "$failing"
-            exit 1
-          fi
-          echo "All checks passed or were acceptably skipped."
+      # Each path-gated group must succeed when selected and be skipped otherwise.
+      # A failed selector must never turn skipped builds into a successful gate.
+      - name: Check unconditional jobs
         env:
           NEEDS_JSON: ${{ toJSON(needs) }}
+          PASSED: >-
+            ${{ needs.check-paths.result == 'success' &&
+                needs.spell-check.result == 'success' &&
+                needs.clang-format.result == 'success' &&
+                needs.python-lint.result == 'success' &&
+                needs.reshard-type-check.result == 'success' &&
+                needs.ci-script-tests.result == 'success' &&
+                needs.tone-script-tests.result == 'success' }}
+        run: |
+          echo "$NEEDS_JSON"
+          test "$PASSED" = true
+
+      - name: Check source jobs
+        env:
+          EXPECTED: ${{ needs.check-paths.outputs.src == 'true' && 'success' || 'skipped' }}
+          RESULTS: >-
+            ${{ needs.build-wheel.result }}
+            ${{ needs.unit-tests.result }}
+            ${{ needs.build-flags.result }}
+            ${{ needs.test-wheel-ubuntu.result }}
+            ${{ needs.build-wheel-cu13.result }}
+            ${{ needs.build-wheel-efa.result }}
+            ${{ needs.build-wheel-rocm.result }}
+        run: |
+          for result in $RESULTS; do
+            test "$result" = "$EXPECTED" || exit 1
+          done
+
+      - name: Check TENT jobs
+        env:
+          EXPECTED: ${{ needs.check-paths.outputs.tent == 'true' && 'success' || 'skipped' }}
+          RESULT: ${{ needs.tent-ci.result }}
+        run: test "$RESULT" = "$EXPECTED"
+
+      - name: Check documentation job
+        env:
+          EXPECTED: ${{ needs.check-paths.outputs.docs == 'true' && 'success' || 'skipped' }}
+          RESULT: ${{ needs.docs-check.result }}
+        run: test "$RESULT" = "$EXPECTED"
diff --git a/.github/workflows/ci_ascend.yml b/.github/workflows/ci_ascend.yml
index 13f79a244f..1f2b6d1ea2 100644
--- a/.github/workflows/ci_ascend.yml
+++ b/.github/workflows/ci_ascend.yml
@@ -45,12 +45,13 @@ jobs:
         fetch-depth: 1
         persist-credentials: false
 
-    - name: Retry checkout via GitHub mirror
+    # Mirror is only a git transport fallback. Keep retry on actions/checkout so
+    # pull_request_target fork checks still run; do not fetch with raw git.
+    - name: Configure GitHub mirror rewrite
       if: steps.checkout_code.outcome == 'failure'
       shell: bash
       env:
         ASCEND_GITHUB_MIRROR_URLS: 'https://ghfast.top/'
-        CHECKOUT_REF: ${{ inputs.checkout_ref || github.sha }}
       run: |
         set -euo pipefail
 
@@ -83,27 +84,21 @@ jobs:
 
         workdir="${GITHUB_WORKSPACE}"
         git config --global --add safe.directory "$workdir"
+        find "$workdir" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
 
-        for base in "${candidates[@]}"; do
-          mirror_url="${base}https://github.com/${GITHUB_REPOSITORY}.git"
-          echo "Retrying checkout with ${mirror_url}"
-
-          find "$workdir" -mindepth 1 -maxdepth 1 -exec rm -rf {} +
-          git init "$workdir"
-          git -C "$workdir" remote add origin "$mirror_url"
-
-          if git -C "$workdir" fetch --depth=1 origin "$CHECKOUT_REF" && \
-             git -C "$workdir" checkout --force --detach FETCH_HEAD; then
-            echo "Mirror checkout succeeded via ${base}"
-            exit 0
-          fi
-
-          echo "Mirror checkout failed via ${base}"
-          rm -rf "$workdir/.git"
-        done
+        # insteadOf only rewrites github.com fetches; checkout still runs
+        # assertSafePrCheckout before any git network I/O.
+        mirror_base="${candidates[0]}"
+        echo "Rewriting https://github.com/ to ${mirror_base}https://github.com/"
+        git config --global url."${mirror_base}https://github.com/".insteadOf "https://github.com/"
 
-        echo "Direct GitHub checkout failed and all mirror retries failed"
-        exit 1
+    - name: Retry checkout via GitHub mirror
+      if: steps.checkout_code.outcome == 'failure'
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ inputs.checkout_ref || github.sha }}
+        fetch-depth: 1
+        persist-credentials: false
 
     - name: Configure CMake
       shell: bash
diff --git a/.github/workflows/ci_efa.yml b/.github/workflows/ci_efa.yml
index 6bf8967c72..0a448c1cf4 100644
--- a/.github/workflows/ci_efa.yml
+++ b/.github/workflows/ci_efa.yml
@@ -11,31 +11,19 @@ jobs:
       matrix:
         include:
           - variant: cuda
-            use_cuda: "ON"
-            build_env: "EFA_BUILD"
-            cuda-version: "12.8.1"
             python-version: "3.12"
           - variant: cuda13
-            use_cuda: "ON"
-            build_env: "EFA_CU13_BUILD"
-            cuda-version: "13.0.2"
             python-version: "3.12"
           - variant: non-cuda
-            use_cuda: "OFF"
-            build_env: "EFA_NON_CUDA_BUILD"
-            cuda-version: "12.8.1"
             python-version: "3.10"
     uses: ./.github/workflows/_build-efa-wheel.yaml
     with:
       variant: ${{ matrix.variant }}
-      use-cuda: ${{ matrix.use_cuda == 'ON' }}
       python-versions: ${{ format('["{0}"]', matrix.python-version) }}
       build-profile: ci
       cmake-args: >-
         -DUSE_ETCD=ON -DUSE_HTTP=ON -DWITH_STORE=ON -DWITH_METRICS=ON
         -DBUILD_UNIT_TESTS=OFF -DBUILD_EXAMPLES=ON -DBUILD_BENCHMARK=ON
         -DENABLE_DEBUG_SYMBOLS=OFF
-      variant-flag: ${{ matrix.build_env }}
-      cuda-version: ${{ matrix.cuda-version }}
       torch-cuda-arch-list: '8.0;9.0'
       artifact-prefix: mooncake-wheel-efa-${{ matrix.variant }}-ubuntu
diff --git a/.github/workflows/ci_hygon.yml b/.github/workflows/ci_hygon.yml
new file mode 100644
index 0000000000..8887d09905
--- /dev/null
+++ b/.github/workflows/ci_hygon.yml
@@ -0,0 +1,358 @@
+name: 'Hygon HCU PR Build & Test'
+
+on:
+  pull_request_target:
+    branches: [main]
+    types: [labeled]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: hcu-upstream-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  build-wheel:
+    name: Build wheel
+    if: >-
+      github.repository == 'kvcache-ai/Mooncake' &&
+      github.event.label.name == 'run-hygon-ci'
+    runs-on: [self-hosted, Linux, X64, hcu1]
+    timeout-minutes: 120
+    container:
+      image: harbor.sourcefind.cn:5443/hcu/admin/base/dtk:26.04-ubuntu22.04-mpi5.0-gcc11.4-cmake3.29-py3.10
+      options: --mount type=bind,source=/etc/hygon-ci,target=/etc/hygon-ci,readonly
+    env:
+      CI: "false"
+      FREE_BUILD_DIR: "0"
+    steps:
+      - name: Checkout PR source
+        uses: actions/checkout@v4
+        with:
+          allow-unsafe-pr-checkout: true
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 1
+          persist-credentials: false
+          submodules: recursive
+          path: pr-source
+
+      - name: Mark workspace safe for git
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE/pr-source"
+
+      - name: Record tested commit
+        shell: bash
+        working-directory: pr-source
+        run: |
+          git rev-parse HEAD
+          printf 'HCU source commit: `%s`\n' "$(git rev-parse HEAD)" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Load HCU CI configuration
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          config_file=/etc/hygon-ci/config.env
+          test -r "${config_file}" || {
+            echo "ERROR: ${config_file} is not readable" >&2
+            exit 1
+          }
+          set -a
+          source "${config_file}"
+          set +a
+          for name in DTK_PKG_URL PIP_INDEX_URL; do
+            value="${!name:-}"
+            test -n "${value}" || {
+              echo "ERROR: ${name} is missing from ${config_file}" >&2
+              exit 1
+            }
+            echo "::add-mask::${value}"
+            printf '%s=%s\n' "${name}" "${value}" >> "${GITHUB_ENV}"
+          done
+
+      - name: Install DTK
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          cd /opt
+          wget -q "${DTK_PKG_URL}"
+          tarball="$(basename "${DTK_PKG_URL}")"
+          tar -xzf "${tarball}"
+          dtk_dir="$(find /opt -mindepth 1 -maxdepth 1 -type d -name 'dtk-*' -print -quit)"
+          test -n "${dtk_dir}"
+          ln -s "${dtk_dir}" dtk
+
+      - name: Configure and build Mooncake
+        shell: bash
+        working-directory: pr-source
+        run: |
+          set -Eeuo pipefail
+          export GOPROXY="${GOPROXY:-https://goproxy.cn,https://goproxy.io,direct}"
+          set +u
+          source /opt/dtk/env.sh
+          set -u
+
+          bash dependencies.sh -y
+          mkdir -p build
+          cd build
+          cmake .. -DUSE_HTTP=ON -DCMAKE_BUILD_TYPE=Release
+          cmake --build . -j"$(nproc)"
+          cmake --install .
+
+      - name: Build wheel
+        shell: bash
+        working-directory: pr-source
+        run: |
+          set -Eeuo pipefail
+          set +u
+          source /opt/dtk/env.sh
+          set -u
+
+          python3 -m pip install patchelf==0.14.5
+          PYTHON_VERSION=3.10 OUTPUT_DIR=dist bash scripts/build_wheel.sh
+
+          wheel_count="$(find mooncake-wheel/dist -maxdepth 1 -type f -name '*.whl' | wc -l)"
+          if [ "${wheel_count}" -ne 1 ]; then
+            echo "Expected exactly one wheel, found ${wheel_count}" >&2
+            find mooncake-wheel/dist -maxdepth 1 -type f -print || true
+            exit 1
+          fi
+          ls -lh mooncake-wheel/dist/*.whl
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: pr-source/mooncake-wheel/dist/*.whl
+          if-no-files-found: error
+          retention-days: 3
+
+      - name: Cleanup build environment
+        if: always()
+        shell: bash
+        run: |
+          set -u
+          rm -rf /opt/dtk
+          if [ -n "${DTK_PKG_URL:-}" ]; then
+            tarball="$(basename "${DTK_PKG_URL}")"
+            rm -f "/opt/${tarball}"
+          fi
+          rm -rf pr-source/build pr-source/mooncake-wheel/dist
+
+  test-transfer-engine-cross-node:
+    name: Transfer Engine cross-node test
+    needs: build-wheel
+    runs-on: [self-hosted, Linux, X64, hcu1]
+    timeout-minutes: 60
+    env:
+      TEST_IMAGE: harbor.sourcefind.cn:5443/hcu/admin/base/dtk:26.04-ubuntu22.04-mpi5.0-gcc11.4-cmake3.29-py3.10
+    steps:
+      - name: Checkout authorized PR test scripts
+        uses: actions/checkout@v4
+        with:
+          allow-unsafe-pr-checkout: true
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 1
+          persist-credentials: false
+          path: ci-control
+
+      - name: Download wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel
+          path: ${{ runner.temp }}/artifacts/${{ github.run_id }}-${{ github.run_attempt }}/wheel
+
+      - name: Load HCU CI configuration
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          config_file=/etc/hygon-ci/config.env
+          test -r "${config_file}" || {
+            echo "ERROR: ${config_file} is not readable" >&2
+            exit 1
+          }
+          set -a
+          source "${config_file}"
+          set +a
+          for name in DTK_PKG_URL PIP_INDEX_URL TARGET_HOST INITIATOR_HOST TARGET_FILTER INITIATOR_FILTER; do
+            value="${!name:-}"
+            test -n "${value}" || {
+              echo "ERROR: ${name} is missing from ${config_file}" >&2
+              exit 1
+            }
+            echo "::add-mask::${value}"
+            printf '%s=%s\n' "${name}" "${value}" >> "${GITHUB_ENV}"
+          done
+          for host in "${TARGET_HOST}" "${INITIATOR_HOST}"; do
+            getent ahostsv4 "${host}" | awk '{print $1}' | sort -u | while read -r address; do
+              test -z "${address}" || echo "::add-mask::${address}"
+            done
+          done
+
+      - name: Run Transfer Engine cross-node test
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          artifact_dir="${RUNNER_TEMP}/artifacts/${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}/wheel"
+          mapfile -t wheels < <(find "${artifact_dir}" -maxdepth 1 -type f -name '*.whl' -print)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "Expected exactly one wheel, found ${#wheels[@]}" >&2
+            exit 1
+          fi
+          bash ci-control/scripts/hygon/test_transfer_engine_cross_node.sh "${wheels[0]}"
+
+      - name: Redact Transfer Engine cross-node test logs
+        id: redact-transfer-engine-logs
+        if: always()
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          python3 ci-control/scripts/hygon/redact_ci_logs.py \
+            "${RUNNER_TEMP}/transfer-engine-logs" \
+            "${RUNNER_TEMP}/artifacts/${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}/transfer-engine-logs-redacted"
+
+      - name: Upload Transfer Engine cross-node test logs
+        if: always() && steps.redact-transfer-engine-logs.outcome == 'success'
+        uses: actions/upload-artifact@v4
+        with:
+          name: transfer-engine-logs
+          path: ${{ runner.temp }}/artifacts/${{ github.run_id }}-${{ github.run_attempt }}/transfer-engine-logs-redacted/*.log
+          if-no-files-found: warn
+          retention-days: 7
+
+  test-mooncake-store-cross-node:
+    name: Mooncake Store cross-node test
+    needs: test-transfer-engine-cross-node
+    runs-on: [self-hosted, Linux, X64, hcu1]
+    timeout-minutes: 60
+    env:
+      TEST_IMAGE: harbor.sourcefind.cn:5443/hcu/admin/base/dtk:26.04-ubuntu22.04-mpi5.0-gcc11.4-cmake3.29-py3.10
+    steps:
+      - name: Checkout authorized PR test scripts
+        uses: actions/checkout@v4
+        with:
+          allow-unsafe-pr-checkout: true
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 1
+          persist-credentials: false
+          path: ci-control
+
+      - name: Download wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel
+          path: ${{ runner.temp }}/artifacts/${{ github.run_id }}-${{ github.run_attempt }}/wheel
+
+      - name: Load HCU CI configuration
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          config_file=/etc/hygon-ci/config.env
+          test -r "${config_file}" || {
+            echo "ERROR: ${config_file} is not readable" >&2
+            exit 1
+          }
+          set -a
+          source "${config_file}"
+          set +a
+          for name in DTK_PKG_URL PIP_INDEX_URL TARGET_HOST INITIATOR_HOST TARGET_FILTER INITIATOR_FILTER; do
+            value="${!name:-}"
+            test -n "${value}" || {
+              echo "ERROR: ${name} is missing from ${config_file}" >&2
+              exit 1
+            }
+            echo "::add-mask::${value}"
+            printf '%s=%s\n' "${name}" "${value}" >> "${GITHUB_ENV}"
+          done
+          for host in "${TARGET_HOST}" "${INITIATOR_HOST}"; do
+            getent ahostsv4 "${host}" | awk '{print $1}' | sort -u | while read -r address; do
+              test -z "${address}" || echo "::add-mask::${address}"
+            done
+          done
+
+      - name: Run mooncake store cross-node test
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          artifact_dir="${RUNNER_TEMP}/artifacts/${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}/wheel"
+          mapfile -t wheels < <(find "${artifact_dir}" -maxdepth 1 -type f -name '*.whl' -print)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "Expected exactly one wheel, found ${#wheels[@]}" >&2
+            exit 1
+          fi
+
+          bash ci-control/scripts/hygon/test_mooncake_store_cross_node.sh "${wheels[0]}"
+
+      - name: Redact mooncake store cross-node test logs
+        id: redact-store-logs
+        if: always()
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          python3 ci-control/scripts/hygon/redact_ci_logs.py \
+            "${RUNNER_TEMP}/mooncake-store-logs" \
+            "${RUNNER_TEMP}/artifacts/${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}/mooncake-store-logs-redacted"
+
+      - name: Upload mooncake store cross-node test logs
+        if: always() && steps.redact-store-logs.outcome == 'success'
+        uses: actions/upload-artifact@v4
+        with:
+          name: mooncake-store-logs
+          path: ${{ runner.temp }}/artifacts/${{ github.run_id }}-${{ github.run_attempt }}/mooncake-store-logs-redacted/*.log
+          if-no-files-found: warn
+          retention-days: 7
+
+  hcu-pr-gate:
+    name: HCU PR gate
+    if: >-
+      always() &&
+      github.repository == 'kvcache-ai/Mooncake' &&
+      github.event.label.name == 'run-hygon-ci'
+    needs:
+      - build-wheel
+      - test-transfer-engine-cross-node
+      - test-mooncake-store-cross-node
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require build and cross-node tests to pass
+        shell: bash
+        env:
+          BUILD_RESULT: ${{ needs.build-wheel.result }}
+          RDMA_TEST_RESULT: ${{ needs.test-transfer-engine-cross-node.result }}
+          STORE_TEST_RESULT: ${{ needs.test-mooncake-store-cross-node.result }}
+        run: |
+          set -Eeuo pipefail
+          printf 'Build wheel:           %s\n' "${BUILD_RESULT}"
+          printf 'Transfer-Engine test:       %s\n' "${RDMA_TEST_RESULT}"
+          printf 'Mooncake Store benchmark test: %s\n' "${STORE_TEST_RESULT}"
+
+          if [ "${BUILD_RESULT}" != "success" ] || \
+             [ "${RDMA_TEST_RESULT}" != "success" ] || \
+             [ "${STORE_TEST_RESULT}" != "success" ]; then
+            echo "::error::HCU PR validation failed or was skipped."
+            exit 1
+          fi
+
+          echo "The wheel built successfully and all HCU tests passed."
+
+  cleanup-label:
+    name: Remove HCU CI request label
+    needs: hcu-pr-gate
+    if: >-
+      always() &&
+      github.repository == 'kvcache-ai/Mooncake' &&
+      github.event.label.name == 'run-hygon-ci'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Remove request label
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: gh pr edit "$PR_NUMBER" --remove-label run-hygon-ci
diff --git a/.github/workflows/ci_rocm.yml b/.github/workflows/ci_rocm.yml
index c445be1230..c042eb1dc0 100644
--- a/.github/workflows/ci_rocm.yml
+++ b/.github/workflows/ci_rocm.yml
@@ -3,11 +3,26 @@ name: 'Build Wheel (ROCm)'
 # ROCm/HIP CI parity with the standard CUDA wheel CI: build the AMD ROCm wheel
 # on PRs so packaging regressions are caught. Runs inside the ROCm dev image so
 # hipcc / HIP headers / hsa-runtime are available; no GPU is needed to compile.
-# On-device transfer tests (test_transfer_on_hip.py) require AMD hardware and
-# run outside GitHub-hosted runners.
+# On-device external-PD tests consume these artifacts later on the trusted
+# self-hosted ROCm runner in integration-test-rocm.yml.
 
 on:
-  workflow_call: {}
+  workflow_call:
+    inputs:
+      checkout_ref:
+        description: 'Git revision to build (used by trusted E2E dispatches)'
+        required: false
+        type: string
+      python_versions:
+        description: 'JSON array of Python versions to build'
+        required: false
+        default: '["3.10", "3.12"]'
+        type: string
+      version_override:
+        description: 'Optional wheel version override for nightly snapshots'
+        required: false
+        default: ''
+        type: string
 
 jobs:
   build-wheel-rocm:
@@ -17,9 +32,10 @@ jobs:
     # so it also loads on the ROCm 7.0 image variants.
     container: rocm/dev-ubuntu-22.04:7.2.3-complete
     strategy:
+      fail-fast: false
       matrix:
         # 3.10 covers the SGLang ROCm image; 3.12 covers vLLM ROCm.
-        python-version: ['3.10', '3.12']
+        python-version: ${{ fromJSON(inputs.python_versions) }}
     env:
       HIP_BUILD: "1"
       SCCACHE_GHA_ENABLED: "true"
@@ -37,15 +53,35 @@ jobs:
         apt-get update -y
         apt-get install -y --no-install-recommends git ca-certificates
 
-    - uses: actions/checkout@v4
+    - name: Check out source
+      uses: actions/checkout@v4
       with:
+        ref: ${{ inputs.checkout_ref || github.sha }}
         persist-credentials: false
-        submodules: recursive
+        submodules: false
 
     - name: Mark repository as safe
       run: git config --global --add safe.directory "$GITHUB_WORKSPACE" || true
       shell: bash
 
+    - name: Check out submodules
+      shell: bash
+      run: |
+        set -eo pipefail
+        git submodule sync --recursive
+        for attempt in 1 2 3; do
+          if git -c http.version=HTTP/1.1 submodule update \
+            --init --recursive --depth=1 --jobs=2; then
+            exit 0
+          fi
+          if [ "$attempt" -eq 3 ]; then
+            echo "Submodule checkout failed after $attempt attempts" >&2
+            exit 1
+          fi
+          echo "Submodule checkout attempt $attempt failed; retrying..." >&2
+          sleep $((attempt * 10))
+        done
+
     - name: Install toolchain and Python ${{ matrix.python-version }}
       shell: bash
       run: |
@@ -96,12 +132,15 @@ jobs:
         rm -rf build && mkdir build && cd build
         cmake -G Ninja .. \
           -DUSE_HIP=ON -DUSE_CUDA=OFF -DWITH_EP=OFF \
+          -DENABLE_MULTI_PROTOCOL=ON \
           -DUSE_HTTP=ON -DUSE_ETCD=ON -DSTORE_USE_ETCD=ON \
           -DBUILD_UNIT_TESTS=OFF -DENABLE_SCCACHE=ON \
           -DCMAKE_BUILD_TYPE=Release \
           -DPython3_EXECUTABLE="${PYTHON_BIN}"
 
     - name: Build project
+      env:
+        MAX_JOBS: "2"
       shell: bash
       run: |
         set -eo pipefail
@@ -110,7 +149,7 @@ jobs:
         # Retry to ride out transient Go module (proxy.golang.org) fetch errors
         # during the etcd-wrapper build; Go caches modules, so retries resume.
         n=0
-        until cmake --build . -j"$(nproc)"; do
+        until cmake --build . -j"${MAX_JOBS}"; do
           n=$((n+1))
           if [ "$n" -ge 3 ]; then echo "Build failed after $n attempts"; exit 1; fi
           echo "Build attempt $n failed; retrying in 15s..."; sleep 15
@@ -127,6 +166,17 @@ jobs:
       shell: bash
       run: echo "python_version_tag=$(echo ${{ matrix.python-version }} | tr -d '.')" >> "$GITHUB_OUTPUT"
 
+    - name: Apply wheel version override
+      if: ${{ inputs.version_override != '' }}
+      shell: bash
+      env:
+        VERSION_OVERRIDE: ${{ inputs.version_override }}
+      run: |
+        set -euo pipefail
+        sed -i "s/^version = .*/version = \"${VERSION_OVERRIDE}\"/" \
+          mooncake-wheel/pyproject.toml
+        grep '^version = ' mooncake-wheel/pyproject.toml
+
     - name: Build Python wheel
       shell: bash
       run: |
@@ -147,7 +197,8 @@ jobs:
           mooncake-wheel/dist-rocm-py${{ steps.generate_tag.outputs.python_version_tag }}/*.whl
         # ROCm runtime is excluded from the wheel and bound at load time.
         export LD_LIBRARY_PATH="/opt/rocm/lib:/usr/local/lib:${LD_LIBRARY_PATH:-}"
-        site="$("$smoke_venv/bin/python" -c 'import mooncake,os;print(os.path.dirname(mooncake.__file__))')"
+        "$smoke_venv/bin/python" scripts/tone_tests/python/verify_rocm_wheel.py
+        site="$("$smoke_venv/bin/python" -c 'import mooncake, os; print(os.path.dirname(mooncake.__file__))')"
         "$site/mooncake_master" --version
 
     - name: Upload Python wheel artifact
diff --git a/.github/workflows/e2e-ci.yml b/.github/workflows/e2e-ci.yml
index b6abfee2e8..d3ec8215e3 100644
--- a/.github/workflows/e2e-ci.yml
+++ b/.github/workflows/e2e-ci.yml
@@ -37,6 +37,14 @@ jobs:
       checkout_ref: ${{ inputs.pr_sha || github.event.pull_request.head.sha }}
     secrets: inherit
 
+  build-wheel-rocm:
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      github.event.label.name == 'run-e2e-ci'
+    uses: ./.github/workflows/ci_rocm.yml
+    with:
+      checkout_ref: ${{ inputs.pr_sha || github.event.pull_request.head.sha }}
+
   integration-test:
     if: >
       github.event_name == 'workflow_dispatch' ||
@@ -47,6 +55,17 @@ jobs:
       pr_number: ${{ inputs.pr_number || github.event.pull_request.number }}
     secrets: inherit
 
+  rocm-integration-test:
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      github.event.label.name == 'run-e2e-ci'
+    needs:
+      - build-wheel-rocm
+    uses: ./.github/workflows/integration-test-rocm.yml
+    with:
+      checkout_ref: ${{ inputs.pr_sha || github.event.pull_request.head.sha }}
+    secrets: inherit
+
   e2e-gate:
     name: E2E Gate
     if: >
@@ -55,7 +74,9 @@ jobs:
        github.event.label.name == 'run-e2e-ci')
     needs:
       - ascend-test
+      - build-wheel-rocm
       - integration-test
+      - rocm-integration-test
     runs-on: ubuntu-latest
     steps:
       - name: Check E2E results
diff --git a/.github/workflows/integration-test-rocm.yml b/.github/workflows/integration-test-rocm.yml
new file mode 100644
index 0000000000..2dea302e85
--- /dev/null
+++ b/.github/workflows/integration-test-rocm.yml
@@ -0,0 +1,167 @@
+name: 'Integration test (ROCm)'
+
+on:
+  workflow_call:
+    inputs:
+      checkout_ref:
+        description: 'Git revision whose ROCm wheel and integration tests are exercised'
+        required: false
+        type: string
+      run_sglang:
+        description: 'Run SGLang cases in addition to vLLM'
+        required: false
+        default: true
+        type: boolean
+
+jobs:
+  test-rocm-integration:
+    name: ROCm MI350X external PD
+    runs-on: [self-hosted, Linux, X64, amd, rocm, gfx950, mooncake-pd]
+    timeout-minutes: 390
+    concurrency:
+      group: mooncake-rocm-mi350x
+      cancel-in-progress: false
+    env:
+      REGISTRY_ADDR_SGLANG: 'lmsysorg/sglang:v0.5.18-rocm720-mi35x@sha256:6d68cd19206716cb3f1e31e2ad89cd0852d7ae614a792773c30a4277f8955c72'
+      REGISTRY_ADDR_VLLM: 'vllm/vllm-openai-rocm:v0.21.0@sha256:98a77b20df03adeb1cfc0ced009b4df6dd52b0a994ab99a32421f30876a9ae0c'
+    steps:
+      # Pytest previously ran as root in a bind-mounted container and left
+      # caches that the non-root runner could not remove on the next checkout.
+      - name: Remove root-owned Python test caches
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker run --rm --network=none \
+            -v "${GITHUB_WORKSPACE}:/workspace" \
+            --entrypoint /bin/rm \
+            "${REGISTRY_ADDR_VLLM}" \
+            -rf \
+            /workspace/scripts/tone_tests/python/.pytest_cache \
+            /workspace/scripts/tone_tests/python/__pycache__
+
+      - name: Check out tested revision
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.checkout_ref || github.sha }}
+          persist-credentials: false
+          clean: true
+
+      - name: Download Python 3.10 ROCm wheel
+        if: inputs.run_sglang
+        uses: actions/download-artifact@v4
+        with:
+          name: mooncake-wheel-rocm-ubuntu-py310
+          path: ${{ runner.temp }}/mooncake-wheel-rocm-py310
+
+      - name: Download Python 3.12 ROCm wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: mooncake-wheel-rocm-ubuntu-py312
+          path: ${{ runner.temp }}/mooncake-wheel-rocm-py312
+
+      - name: Run two-node ROCm external PD suite
+        shell: bash
+        env:
+          WHEEL_DIR_SGLANG: ${{ runner.temp }}/mooncake-wheel-rocm-py310
+          WHEEL_DIR_VLLM: ${{ runner.temp }}/mooncake-wheel-rocm-py312
+        run: |
+          set -euo pipefail
+          [ "$(id -u)" -ne 0 ] || {
+            echo "The self-hosted runner must not run as root" >&2
+            exit 1
+          }
+          [ -r /etc/mooncake-ci/runner.env ] || {
+            echo "Missing controller profile: /etc/mooncake-ci/runner.env" >&2
+            exit 1
+          }
+          set -a
+          # shellcheck disable=SC1091
+          source /etc/mooncake-ci/runner.env
+          set +a
+          export REGISTRY_ADDR_SGLANG REGISTRY_ADDR_VLLM
+          export WHEEL_DIR_SGLANG WHEEL_DIR_VLLM
+
+          required_vars=(
+            CI_ACCELERATOR LOCAL_IP REMOTE_IP REMOTE_SSH_TARGET
+            MODEL_CACHE MOONCAKE_RUNTIME_CACHE MOONCAKE_CI_TIER
+            MOONCAKE_GPU_INDICES
+            MOONCAKE_RENDER_DEVICES MOONCAKE_CPUSET_CPUS
+            MOONCAKE_CPUSET_MEMS MOONCAKE_SSH_CONFIG
+            MOONCAKE_LOCK_FILE REMOTE_TEST_DIR MOONCAKE_RDMA_DEVICES
+            MOONCAKE_RDMA_NETDEVS MOONCAKE_TRANSFER_DEVICE
+            MOONCAKE_GID_INDEX MOONCAKE_SGLANG_BASE_GPU_ID
+            MOONCAKE_EPD_ENCODER_GPU_ID MOONCAKE_EPD_PREFILL_GPU_ID
+            MOONCAKE_EPD_DECODE_GPU_ID MOONCAKE_VLLM_VISIBLE_DEVICES
+            MOONCAKE_SGLANG_MEM_FRACTION_STATIC AINIC_VERSION
+          )
+          for variable in "${required_vars[@]}"; do
+            [ -n "${!variable:-}" ] || {
+              echo "Missing controller setting: $variable" >&2
+              exit 1
+            }
+          done
+          [ "$CI_ACCELERATOR" = rocm ]
+          export SSH_CMD="ssh -F ${MOONCAKE_SSH_CONFIG}"
+
+          for command in docker flock python3 realpath rocm-smi rsync ssh; do
+            command -v "$command" >/dev/null || {
+              echo "Missing required command: $command" >&2
+              exit 1
+            }
+          done
+          test -c /dev/kfd
+          test -d /sys/class/kfd/kfd/topology/nodes
+          test -d /sys/class/kfd/kfd/proc
+          ssh -F "${MOONCAKE_SSH_CONFIG}" "${REMOTE_SSH_TARGET}" '
+            set -eu
+            for command in docker python3 rocm-smi; do
+              command -v "$command" >/dev/null || {
+                echo "Missing required remote command: $command" >&2
+                exit 1
+              }
+            done
+            test -c /dev/kfd
+            test -d /sys/class/kfd/kfd/topology/nodes
+            test -d /sys/class/kfd/kfd/proc
+          '
+          [ -w "$(dirname "$MOONCAKE_LOCK_FILE")" ] || {
+            echo "Runner cannot write the Mooncake lock directory" >&2
+            exit 1
+          }
+
+          exec 9>"${MOONCAKE_LOCK_FILE}"
+          flock -n 9 || {
+            echo "The MI350X Mooncake allocation is already in use" >&2
+            exit 1
+          }
+
+          cleanup_best_effort() {
+            local exit_code=$?
+            trap - EXIT
+            if [ -f scripts/tone_tests/run/.shrc ]; then
+              set +e
+              # shellcheck disable=SC1091
+              source scripts/tone_tests/run/.shrc
+              # shellcheck disable=SC1091
+              source scripts/tone_tests/scripts/common.sh
+              cleanup_test_env double || true
+            fi
+            exit "$exit_code"
+          }
+          trap cleanup_best_effort EXIT
+          trap 'exit 130' INT
+          trap 'exit 143' TERM
+          if ${{ inputs.run_sglang }}; then
+            bash scripts/tone_tests/scripts/run_test.sh run-all
+          else
+            bash scripts/tone_tests/scripts/run_test.sh run-all VLLM
+          fi
+
+      - name: Upload ROCm external PD logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: rocm-external-pd-logs-${{ github.run_id }}-${{ github.run_attempt }}
+          path: scripts/tone_tests/run/logs
+          if-no-files-found: warn
+          retention-days: 14
diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml
index 4d5cb8ad52..3888e68237 100644
--- a/.github/workflows/integration-test.yml
+++ b/.github/workflows/integration-test.yml
@@ -11,6 +11,19 @@ on:
         description: 'PR number (passed from parent workflow for workflow_dispatch)'
         required: false
         type: string
+      source_run_id:
+        description: 'Workflow run containing the wheel artifact'
+        required: false
+        type: string
+      artifact_name:
+        description: 'Exact wheel artifact name'
+        required: false
+        type: string
+      testpypi_version:
+        description: 'Exact TestPyPI CUDA 13 package version to test instead of a CI artifact'
+        required: false
+        default: ''
+        type: string
 
 jobs:
   test-sglang-integration:
@@ -18,64 +31,117 @@ jobs:
     env:
       tone_user_name: ${{ secrets.TONE_USER_NAME }}
     steps:
+      - name: Require T-one credentials for gated integration
+        if: ${{ inputs.testpypi_version != '' || inputs.source_run_id != '' || inputs.artifact_name != '' }}
+        env:
+          TONE_USER_NAME: ${{ secrets.TONE_USER_NAME }}
+          TONE_USER_TOKEN: ${{ secrets.TONE_USER_TOKEN }}
+        run: |
+          if [ -z "$TONE_USER_NAME" ] || [ -z "$TONE_USER_TOKEN" ]; then
+            echo "TONE_USER_NAME and TONE_USER_TOKEN are required for gated integration"
+            exit 1
+          fi
+
+      - name: Set up Python for TestPyPI download
+        if: ${{ inputs.testpypi_version != '' }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Download the exact indexed CUDA 13 wheel
+        if: ${{ inputs.testpypi_version != '' }}
+        env:
+          TESTPYPI_VERSION: ${{ inputs.testpypi_version }}
+        run: |
+          python -m pip download \
+            --index-url https://test.pypi.org/simple \
+            --no-cache-dir \
+            --no-deps \
+            --only-binary=:all: \
+            --pre \
+            --dest integration-wheel \
+            "mooncake-transfer-engine-cuda13==${TESTPYPI_VERSION}"
+
+      - name: Stage the indexed wheel for T-one
+        if: ${{ inputs.testpypi_version != '' }}
+        id: testpypi-wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: mooncake-testpypi-tone-${{ inputs.testpypi_version }}
+          path: integration-wheel/*.whl
+          if-no-files-found: error
+          retention-days: 14
+
       - name: trigger T-one test
         if: ${{ env.tone_user_name != '' }}
+        env:
+          TESTPYPI_ARTIFACT_ID: ${{ steps.testpypi-wheel.outputs.artifact-id }}
         run: |
           # Priority: explicit inputs > PR event context > push SHA
           SHA="${{ inputs.pr_sha || github.event.pull_request.head.sha || github.sha }}"
           PR_ID="${{ inputs.pr_number || github.event.pull_request.number }}"
+          SOURCE_RUN_ID="${{ inputs.source_run_id }}"
+          ARTIFACT_NAME="${{ inputs.artifact_name }}"
 
           if [ "${{ github.event_name }}" = "push" ]; then
             SHA="${{ github.sha }}"
             PR_ID=""
           fi
           echo "PR_ID=${PR_ID}"
+          artifact_id="$TESTPYPI_ARTIFACT_ID"
           max_attempts=120
           attempt=1
-          while [ $attempt -le $max_attempts ]; do
+          while [ -z "$artifact_id" ] && [ $attempt -le $max_attempts ]; do
             echo "Attempt $attempt: Fetching artifact..."
             echo "Target SHA=${SHA}"
             artifact_id=""
-            run_id=""
-            if curl -L -fs -o runs.json -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "https://api.github.com/repos/${{ github.repository }}/actions/runs?head_sha=${SHA}&per_page=100"; then
-              if jq empty runs.json >/dev/null 2>&1; then
-                run_id=$(jq -r '.workflow_runs[] | select((.path == ".github/workflows/ci.yml") or (.name == "Build & Test (Linux)")) | .id' runs.json | head -n 1)
+            run_id="$SOURCE_RUN_ID"
+            if [ -z "$run_id" ]; then
+              if curl -L -fs -o runs.json -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "https://api.github.com/repos/${{ github.repository }}/actions/runs?head_sha=${SHA}&per_page=100"; then
+                if jq empty runs.json >/dev/null 2>&1; then
+                  run_id=$(jq -r '.workflow_runs[] | select((.path == ".github/workflows/ci.yml") or (.name == "Build & Test (Linux)")) | .id' runs.json | head -n 1)
+                else
+                  echo "Failed to download workflow run list. Retrying..."
+                fi
               else
-                echo "Failed to download workflow run list. Retrying..."
+                echo "Failed to fetch workflow runs. Retrying..."
               fi
-              if [ -n "$run_id" ]; then
-                echo "Matched workflow run id $run_id"
-                if curl -L -fs -o artifact.json -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "https://api.github.com/repos/${{ github.repository }}/actions/runs/${run_id}/artifacts?per_page=100"; then
-                  if jq empty artifact.json >/dev/null 2>&1; then
-                    artifact_id=$(jq -r '.artifacts[] | select(.name | contains("py312") ) | select(.name | contains("mooncake") ) | select(.name | contains("cu130") ) | .id' artifact.json | head -n 1)
-                    if [ -z "$artifact_id" ]; then
-                      echo "Available artifacts in workflow run $run_id:"
-                      jq -r '.artifacts[].name' artifact.json || true
-                    fi
+            fi
+
+            if [ -n "$run_id" ]; then
+              echo "Matched workflow run id $run_id"
+              if curl -L -fs -o artifact.json -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "https://api.github.com/repos/${{ github.repository }}/actions/runs/${run_id}/artifacts?per_page=100"; then
+                if jq empty artifact.json >/dev/null 2>&1; then
+                  if [ -n "$ARTIFACT_NAME" ]; then
+                    artifact_id=$(jq -r --arg name "$ARTIFACT_NAME" '.artifacts[] | select(.name == $name) | .id' artifact.json | head -n 1)
                   else
-                    echo "Failed to download artifact list. Retrying..."
+                    artifact_id=$(jq -r '.artifacts[] | select(.name | contains("py312") ) | select(.name | contains("mooncake") ) | select(.name | contains("cu130") ) | .id' artifact.json | head -n 1)
+                  fi
+                  if [ -z "$artifact_id" ]; then
+                    echo "Available artifacts in workflow run $run_id:"
+                    jq -r '.artifacts[].name' artifact.json || true
                   fi
                 else
-                  echo "Failed to fetch artifacts for workflow run $run_id. Retrying..."
+                  echo "Failed to download artifact list. Retrying..."
                 fi
               else
-                echo "Failed to find Build & Test workflow run for SHA $SHA. Retrying..."
+                echo "Failed to fetch artifacts for workflow run $run_id. Retrying..."
+              fi
+            else
+              echo "Failed to find Build & Test workflow run for SHA $SHA. Retrying..."
+              if jq empty runs.json >/dev/null 2>&1; then
                 echo "Available workflow runs for SHA:"
                 jq -r '.workflow_runs[] | "\(.id) \(.name) \(.path) \(.status) \(.conclusion)"' runs.json || true
               fi
-              if [ -n "$artifact_id" ]; then
-                echo "Successfully fetched expected artifact id $artifact_id"
-                break
-              else
-                echo "Failed to fetch expected artifact. Retrying..."
-                if [ $attempt -lt $max_attempts ]; then
-                  sleep $((attempt * 60 < 600 ? attempt * 60 : 600))
-                fi
-              fi
+            fi
+
+            if [ -n "$artifact_id" ]; then
+              echo "Successfully fetched expected artifact id $artifact_id"
+              break
             else
-              echo "Failed to fetch workflow runs. Retrying..."
+              echo "Failed to fetch expected artifact. Retrying..."
               if [ $attempt -lt $max_attempts ]; then
-                sleep $((attempt * 60))
+                sleep $((attempt * 60 < 600 ? attempt * 60 : 600))
               fi
             fi
             attempt=$((attempt + 1))
@@ -86,6 +152,9 @@ jobs:
           fi
 
           ENV_INFO="ARTIFACT_ID=${artifact_id} GIT_REPO=${{ github.repository }}"
+          if [ -n "${{ inputs.testpypi_version }}" ]; then
+            ENV_INFO="${ENV_INFO} BRANCH=${{ github.ref_name }}"
+          fi
           if [ -n "$PR_ID" ]; then
             ENV_INFO="${ENV_INFO} PR_ID=${PR_ID}"
           fi
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index ec31a8082c..e657a6fbd1 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -20,10 +20,10 @@ concurrency:
 # ── Workflow Design Notes ──────────────────────────────────────────────────────
 # 1. version-stamp computes a forward-looking nightly version (next patch + .devYYYYMMDD)
 #    that sorts AFTER the current release per PEP 440, e.g. "0.3.12.dev20260720".
-# 2. Build jobs pass the nightly version via `version-override` to _build-wheel.yaml
-#    so each wheel is stamped with the correct dev version for TestPyPI.
+# 2. Build jobs pass the nightly version to their reusable wheel workflows so
+#    each wheel is stamped with the correct dev version for TestPyPI.
 # 3. Specialized platform and packaging checks run nightly instead of on every PR.
-# 4. publish-testpypi uploads all nightly-* artifacts to TestPyPI.
+# 4. publish-testpypi uploads standard and ROCm nightly artifacts to TestPyPI.
 # 5. nightly-gate aggregates ALL build + test results; notify-failure files an issue.
 # ──────────────────────────────────────────────────────────────────────────────
 
@@ -74,14 +74,38 @@ jobs:
           - variant: non-cuda
             architecture: x86_64
             artifact-prefix: nightly-non-cuda-x86
+          - variant: non-cuda
+            architecture: arm64
+            artifact-prefix: nightly-non-cuda-arm64
     uses: ./.github/workflows/_build-wheel.yaml
     with:
       variant: ${{ matrix.variant }}
       architecture: ${{ matrix.architecture }}
-      python-versions: '["3.10", "3.12"]'
       artifact-prefix: ${{ matrix.artifact-prefix }}
       version-override: ${{ needs.version-stamp.outputs.nightly_version }}
 
+  tone-sglang-integration:
+    needs: build-wheels
+    uses: ./.github/workflows/integration-test.yml
+    with:
+      pr_sha: ${{ github.sha }}
+      source_run_id: ${{ github.run_id }}
+      artifact_name: nightly-cuda13-x86-py312
+    secrets: inherit
+
+  build-wheel-rocm:
+    needs: version-stamp
+    uses: ./.github/workflows/ci_rocm.yml
+    with:
+      version_override: ${{ needs.version-stamp.outputs.nightly_version }}
+
+  rocm-integration-test:
+    needs: build-wheel-rocm
+    uses: ./.github/workflows/integration-test-rocm.yml
+    with:
+      checkout_ref: ${{ github.sha }}
+    secrets: inherit
+
   build-musa:
     runs-on: ubuntu-22.04
     container: registry.mthreads.com/mcconline/inference/pytorch:2.9.1.post1-py3.10-musa5.2.0-mp31-devel-ubuntu22.04-amd64
@@ -108,7 +132,10 @@ jobs:
         run: |
           cd build
           source ~/.bashrc
-          cmake --build . --parallel 1
+          # Limit concurrency of Mooncake PG's setup.py build to avoid OOM
+          export MAX_JOBS=2
+          # Does not affect the Ninja system
+          cmake --build .
           cmake --install .
         shell: bash
 
@@ -130,7 +157,7 @@ jobs:
         run: |
           docker build -f docker/mooncake.Dockerfile \
             --build-arg PYTHON_VERSION=3.10 \
-            --build-arg EP_TORCH_VERSIONS="2.13.0" \
+            --build-arg EP_TORCH_VERSIONS="2.14.0" \
             --build-arg CLEAN_BUILD_ARTIFACTS=1 \
             -t mooncake:from-source .
 
@@ -139,7 +166,7 @@ jobs:
     secrets: inherit
 
   publish-testpypi:
-    needs: [version-stamp, build-wheels, nightly-test]
+    needs: [version-stamp, build-wheels, build-wheel-rocm, nightly-test]
     if: ${{ !(github.event_name == 'workflow_dispatch' && github.event.inputs.skip_publish == 'true') }}
     runs-on: ubuntu-22.04
     environment: nightly
@@ -150,13 +177,21 @@ jobs:
         run: |
           echo "Publishing nightly version: ${{ needs.version-stamp.outputs.nightly_version }}"
 
-      - name: Download all nightly wheel artifacts
+      - name: Download standard nightly wheel artifacts
         uses: actions/download-artifact@v4
         with:
           path: dist-all
           pattern: 'nightly-*'
 
-      - name: Collect and rename wheels with nightly version
+      # Keep the established artifact names because integration-test-rocm.yml
+      # consumes them from the same run.
+      - name: Download ROCm nightly wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist-all
+          pattern: 'mooncake-wheel-rocm-ubuntu-*'
+
+      - name: Collect wheels for nightly publication
         run: |
           mkdir -p dist-publish
           find dist-all -name "*.whl" -exec cp {} dist-publish/ \;
@@ -201,13 +236,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install and start etcd
-        run: |
-          wget -q https://github.com/etcd-io/etcd/releases/download/v3.6.1/etcd-v3.6.1-linux-amd64.tar.gz
-          tar xzf etcd-v3.6.1-linux-amd64.tar.gz
-          sudo mv etcd-v3.6.1-linux-amd64/etcd* /usr/local/bin/
-          etcd --advertise-client-urls http://127.0.0.1:2379 --listen-client-urls http://127.0.0.1:2379 &
-          sleep 3
-          ETCDCTL_API=3 etcdctl --endpoints=http://127.0.0.1:2379 endpoint health
+        uses: ./.github/actions/setup-etcd
 
       - name: Free up disk space
         run: |
@@ -227,15 +256,8 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y ninja-build
 
-      - name: Run sccache-cache
-        uses: mozilla-actions/sccache-action@v0.0.9
-
-      - name: Configure sccache
-        uses: actions/github-script@v7
-        with:
-          script: |
-            core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
-            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+      - name: Set up compiler cache
+        uses: ./.github/actions/setup-sccache
 
       - name: Configure project (Release, no ASAN)
         run: |
@@ -245,13 +267,16 @@ jobs:
           mkdir build && cd build
           cmake -G Ninja .. \
             -DUSE_HTTP=ON -DUSE_CXL=ON -DUSE_UB=ON -DUSE_ETCD=ON -DUSE_CUDA=ON \
+            -DWITH_P2P_STORE=ON \
             -DSTORE_USE_ETCD=ON -DCMAKE_BUILD_TYPE=Release \
             -DBUILD_UNIT_TESTS=ON -DENABLE_SCCACHE=ON
 
+      - name: Configure CUDA driver runtime
+        uses: ./.github/actions/setup-cuda-runtime
+
       - name: Build project
         run: |
           cd build
-          export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:${LIBRARY_PATH:-}
           cmake --build . -j$(nproc)
           sudo -E cmake --install .
 
@@ -259,23 +284,13 @@ jobs:
         run: |
           mkdir -p build/mooncake-transfer-engine/nvlink-allocator
           cd mooncake-transfer-engine/nvlink-allocator
-          export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH
           bash build.sh ../../build/mooncake-transfer-engine/nvlink-allocator/
 
       - name: Start Metadata Server
-        run: |
-          cd mooncake-transfer-engine/example/http-metadata-server-python
-          pip install aiohttp
-          python ./bootstrap_server.py &
-          sleep 2
+        uses: ./.github/actions/setup-metadata-server
 
       - name: Run CTest unit tests
-        run: |
-          cd build
-          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
-          MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
-          DEFAULT_KV_LEASE_TTL=500 \
-            ctest --parallel $(nproc) --output-on-failure
+        uses: ./.github/actions/run-ctest
 
       - name: Run Mooncake Store Rust smoke test
         env:
@@ -283,32 +298,99 @@ jobs:
           MOONCAKE_STORE_RUST_LINK_ASAN: "0"
         run: ./scripts/ci/run_store_rust_smoke.sh
 
+      - name: Run Transfer Engine Rust smoke test
+        env:
+          MOONCAKE_TE_RUST_LINK_ASAN: "0"
+        run: ./scripts/ci/run_transfer_engine_rust_smoke.sh
+
+      - name: Check Mooncake Store Rust bindings, examples, and tests
+        env:
+          MOONCAKE_BUILD_DIR: ${{ github.workspace }}/build
+          MOONCAKE_STORE_LIB_DIR: ${{ github.workspace }}/build/mooncake-store/src
+          MOONCAKE_STORE_INCLUDE_DIR: ${{ github.workspace }}/mooncake-store/include
+        run: |
+          export LD_LIBRARY_PATH="$GITHUB_WORKSPACE/build/mooncake-asio:$GITHUB_WORKSPACE/build/mooncake-store/src:$GITHUB_WORKSPACE/build/mooncake-store/src/cachelib_memory_allocator:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base:$GITHUB_WORKSPACE/build/mooncake-common/etcd:/usr/local/lib:${LD_LIBRARY_PATH:-}"
+          cd mooncake-store/rust
+          cargo test --lib
+          cargo test --examples --tests --no-run
+          cargo clean
+
+      - name: Verify Mooncake Store Rust dlopen bindings and packaging
+        env:
+          MOONCAKE_STORE_INCLUDE_DIR: ${{ github.workspace }}/mooncake-store/include
+        run: |
+          cd mooncake-store/rust
+          cargo run --locked --example generate_dlopen_bindings
+          git diff --exit-code -- src/generated/ffi_dlopen_bindings.rs
+          cargo package --no-verify --allow-dirty
+          crate=$(ls target/package/mooncake_store-*.crate | head -1)
+          dest=$(mktemp -d)
+          tar xzf "$crate" -C "$dest"
+          (cd "$dest"/mooncake_store-* && cargo check --no-default-features --features dlopen)
+
       - name: Run Go store binding integration tests
         env:
           MOONCAKE_STORE_CLUSTER_ID: nightly_go_cluster
-          MOONCAKE_STORE_GO_LINK_COMMON: "0"
           MOONCAKE_STORE_GO_SANITIZED: "0"
         run: ./scripts/ci/run_store_go_integration.sh
 
       - name: Build and install Python wheel for integration tests
         run: |
+          python -m venv "${RUNNER_TEMP}/mooncake-nightly-venv"
+          echo "${RUNNER_TEMP}/mooncake-nightly-venv/bin" >> "$GITHUB_PATH"
+          source "${RUNNER_TEMP}/mooncake-nightly-venv/bin/activate"
           export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
           export CUDA_HOME=/usr/local/cuda
           PYTHON_VERSION=3.12 OUTPUT_DIR=dist ./scripts/build_wheel.sh
-          pip install mooncake-wheel/dist/*.whl
+          python -m pip install mooncake-wheel/dist/*.whl
 
       - name: Run Python integration tests (full suite)
         env:
           MC_METADATA_SERVER: http://127.0.0.1:8080/metadata
           RUN_TESTS_METADATA_SERVER_MODE: external
           DEFAULT_KV_LEASE_TTL: "500"
-          TEST_SSD_OFFLOAD_IN_EVICT: "1"
-          TEST_PROMOTION_ON_HIT: "1"
           TEST_CXL: "1"
         run: |
           export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
           bash scripts/run_tests.sh
 
+      - name: Run Python API end-to-end tests
+        env:
+          MOONCAKE_MASTER: "127.0.0.1:50051"
+          MOONCAKE_TE_META_DATA_SERVER: "http://127.0.0.1:8080/metadata"
+          MOONCAKE_PROTOCOL: "tcp"
+          LOCAL_HOSTNAME: "127.0.0.1"
+        run: |
+          export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+          kill "$NIGHTLY_METADATA_SERVER_PID" 2>/dev/null || true
+          for _ in {1..50}; do
+            if ! kill -0 "$NIGHTLY_METADATA_SERVER_PID" 2>/dev/null; then
+              break
+            fi
+            sleep 0.1
+          done
+          if kill -0 "$NIGHTLY_METADATA_SERVER_PID" 2>/dev/null; then
+            kill -KILL "$NIGHTLY_METADATA_SERVER_PID"
+          fi
+          mkdir -p /tmp/mooncake_storage
+          mooncake_master \
+            --default_kv_lease_ttl=500 \
+            --eviction_high_watermark_ratio=0.95 \
+            --cluster_id=nightly_test_cluster \
+            --port 50051 \
+            --enable_http_metadata_server=true &
+          master_pid=$!
+          trap 'kill "$master_pid" 2>/dev/null || true; wait "$master_pid" 2>/dev/null || true' EXIT
+          sleep 3
+          python -m unittest mooncake-wheel.tests.test_weight_snapshot_api
+          python python/tests/store/async_store_integration.py
+          python scripts/test_copy_move_api.py
+          python scripts/test_drain_http_api.py --timeout-sec 90
+
+      - name: Run RPC Communicator Bandwidth Test
+        run: ./scripts/ci/run_rpc_smoke.sh
+        shell: bash
+
   nightly-coverage:
     runs-on: ubuntu-22.04
     env:
@@ -331,13 +413,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install and start etcd
-        run: |
-          wget -q https://github.com/etcd-io/etcd/releases/download/v3.6.1/etcd-v3.6.1-linux-amd64.tar.gz
-          tar xzf etcd-v3.6.1-linux-amd64.tar.gz
-          sudo mv etcd-v3.6.1-linux-amd64/etcd* /usr/local/bin/
-          etcd --advertise-client-urls http://127.0.0.1:2379 --listen-client-urls http://127.0.0.1:2379 &
-          sleep 3
-          ETCDCTL_API=3 etcdctl --endpoints=http://127.0.0.1:2379 endpoint health
+        uses: ./.github/actions/setup-etcd
 
       - name: Free up disk space
         uses: ./.github/actions/free-disk-space
@@ -355,15 +431,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y lcov gcovr ninja-build
 
-      - name: Run sccache-cache
-        uses: mozilla-actions/sccache-action@v0.0.9
+      - name: Test HugeTLB sizing helper
+        run: python3 scripts/test_hicache_hugepage_requirements.py
 
-      - name: Configure sccache
-        uses: actions/github-script@v7
-        with:
-          script: |
-            core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
-            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+      - name: Set up compiler cache
+        uses: ./.github/actions/setup-sccache
 
       - name: Configure project with coverage support
         run: |
@@ -380,19 +452,29 @@ jobs:
           sudo cmake --install .
 
       - name: Start Metadata Server
-        run: |
-          cd mooncake-transfer-engine/example/http-metadata-server-python
-          pip install aiohttp
-          python ./bootstrap_server.py &
-          sleep 2
+        uses: ./.github/actions/setup-metadata-server
 
       - name: Run CTest with coverage
-        run: |
-          cd build
-          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
-          MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
-          DEFAULT_KV_LEASE_TTL=500 \
-            ctest --parallel $(nproc) --output-on-failure
+        uses: ./.github/actions/run-ctest
+        with:
+          reserve-rpc-port: 'false'
+
+      - name: Run Mooncake Store Rust sanitizer smoke test
+        env:
+          MOONCAKE_STORE_CLUSTER_ID: nightly_asan_rust_cluster
+          MOONCAKE_STORE_RUST_LINK_ASAN: "1"
+        run: ./scripts/ci/run_store_rust_smoke.sh
+
+      - name: Run Transfer Engine Rust sanitizer smoke test
+        env:
+          MOONCAKE_TE_RUST_LINK_ASAN: "1"
+        run: ./scripts/ci/run_transfer_engine_rust_smoke.sh
+
+      - name: Run Go store binding sanitizer integration tests
+        env:
+          MOONCAKE_STORE_CLUSTER_ID: nightly_asan_go_cluster
+          MOONCAKE_STORE_GO_SANITIZED: "1"
+        run: ./scripts/ci/run_store_go_integration.sh
 
       - name: Generate coverage report
         id: coverage
@@ -453,6 +535,9 @@ jobs:
     needs:
       - version-stamp
       - build-wheels
+      - tone-sglang-integration
+      - build-wheel-rocm
+      - rocm-integration-test
       - build-musa
       - build-docker
       - ascend-test
diff --git a/.github/workflows/pre-release.yaml b/.github/workflows/pre-release.yaml
index 2a07c4b4ad..ccd01b6aab 100644
--- a/.github/workflows/pre-release.yaml
+++ b/.github/workflows/pre-release.yaml
@@ -1,11 +1,8 @@
 name: Pre-Release
 
-# Dry run of the release pipelines: build wheels through the same _build-wheel.yaml
-# the Release / Release Non-CUDA / Release CUDA 13 workflows use, validate the
-# artifacts, but do not create a GitHub Release or publish to PyPI.
-#
-# Trigger by pushing a pre-release tag, for example:
-#   git tag v1.0.0-rc1 && git push origin v1.0.0-rc1
+# Build the same core wheel matrix as the stable release workflows and attach
+# the artifacts to a GitHub Pre-release. Also publish the exact artifacts to
+# TestPyPI, then consume them in smoke and T-one tests. No production PyPI upload.
 on:
   push:
     tags:
@@ -15,7 +12,40 @@ on:
       - 'v*-pre*'
 
 jobs:
+  version-stamp:
+    name: Normalize pre-release version
+    if: github.repository == 'kvcache-ai/Mooncake'
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+    outputs:
+      package_version: ${{ steps.version.outputs.package_version }}
+    steps:
+      - name: Checkout release gate
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install version parser
+        run: python -m pip install packaging
+
+      - name: Normalize tag as a PEP 440 pre-release
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          normalized=$(python scripts/ci/testpypi_wheel_gate.py \
+            normalize-version --tag "$RELEASE_TAG")
+          echo "package_version=${normalized}" >> "$GITHUB_OUTPUT"
+          echo "Normalized ${RELEASE_TAG} to ${normalized}"
+
   build:
+    needs: version-stamp
     strategy:
       fail-fast: false
       matrix:
@@ -43,13 +73,46 @@ jobs:
       variant: ${{ matrix.variant }}
       architecture: ${{ matrix.architecture }}
       artifact-prefix: ${{ matrix.artifact-prefix }}
+      version-override: ${{ needs.version-stamp.outputs.package_version }}
 
-  validate-release:
-    name: Validate release artifacts
+  publish-github-release:
+    name: Upload wheels to GitHub Pre-release
     needs: build
     runs-on: ubuntu-22.04
+    concurrency:
+      group: pre-release-github-${{ github.ref_name }}
+      cancel-in-progress: false
+    permissions:
+      contents: write
+    steps:
+      - name: Download all pre-release wheel artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: mooncake-wheel/dist-release
+          pattern: mooncake-wheel*pre-release*
+          merge-multiple: true
+
+      - name: Upload wheels to GitHub Pre-release
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ github.ref_name }}
+          prerelease: true
+          make_latest: false
+          files: mooncake-wheel/dist-release/*.whl
+          fail_on_unmatched_files: true
+
+  publish-testpypi:
+    name: Validate and publish wheels to TestPyPI
+    needs: [version-stamp, build]
+    runs-on: ubuntu-22.04
+    environment: nightly
+    concurrency:
+      group: pre-release-testpypi-${{ needs.version-stamp.outputs.package_version }}
+      cancel-in-progress: false
     permissions:
       contents: read
+    env:
+      PACKAGE_VERSION: ${{ needs.version-stamp.outputs.package_version }}
     steps:
       - name: Checkout source
         uses: actions/checkout@v4
@@ -60,42 +123,173 @@ jobs:
           path: mooncake-wheel/dist-all
           pattern: mooncake-wheel*pre-release*
 
-      - name: Prepare wheels for validation
+      - name: Collect wheels for publication
         run: |
           mkdir -p mooncake-wheel/dist-release
-          find mooncake-wheel/dist-all -name "*.whl" -exec cp {} mooncake-wheel/dist-release/ \;
+          find mooncake-wheel/dist-all -name "*.whl" \
+            -exec cp {} mooncake-wheel/dist-release/ \;
           echo "Pre-release tag: ${GITHUB_REF_NAME}"
+          echo "Package version: ${PACKAGE_VERSION}"
           echo "Collected wheels:"
           ls -la mooncake-wheel/dist-release/
-          wheel_count=$(find mooncake-wheel/dist-release -name "*.whl" | wc -l)
-          echo "wheel_count=${wheel_count}" >> "$GITHUB_ENV"
-          if [ "${wheel_count}" -lt 24 ]; then
-            echo "Expected at least 24 wheels (4 Python versions x 3 variants x 2 architectures), found ${wheel_count}"
-            exit 1
-          fi
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: '3.12'
 
+      - name: Install publication tools
+        run: python -m pip install packaging twine
+
+      - name: Require TestPyPI credentials
+        env:
+          TESTPYPI_API_TOKEN: ${{ secrets.TESTPYPI_API_TOKEN }}
+        run: |
+          if [ -z "$TESTPYPI_API_TOKEN" ]; then
+            echo "TESTPYPI_API_TOKEN is required"
+            exit 1
+          fi
+
       - name: Validate wheels with twine
+        run: twine check mooncake-wheel/dist-release/*.whl
+
+      - name: Validate empty or resumable TestPyPI upload state
         run: |
-          pip install twine
-          twine check mooncake-wheel/dist-release/*.whl
+          python scripts/ci/testpypi_wheel_gate.py validate-upload-state \
+            --directory mooncake-wheel/dist-release \
+            --version "$PACKAGE_VERSION"
 
-      - name: Upload validated wheels as workflow artifacts
-        uses: actions/upload-artifact@v4
+      - name: Publish exact wheels to TestPyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TESTPYPI_API_TOKEN }}
+        run: >-
+          twine upload --repository testpypi --skip-existing
+          mooncake-wheel/dist-release/*.whl
+
+      - name: Verify every published wheel hash
+        run: |
+          python scripts/ci/testpypi_wheel_gate.py wait-upload-state \
+            --directory mooncake-wheel/dist-release \
+            --version "$PACKAGE_VERSION"
+
+  consume-testpypi:
+    name: Consume ${{ matrix.package }} on ${{ matrix.architecture }}
+    needs: [version-stamp, publish-testpypi]
+    runs-on: ${{ matrix.architecture == 'aarch64' && 'ubuntu-22.04-arm' || 'ubuntu-22.04' }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - mooncake-transfer-engine
+          - mooncake-transfer-engine-cuda13
+          - mooncake-transfer-engine-non-cuda
+        architecture:
+          - x86_64
+          - aarch64
+    env:
+      PACKAGE_VERSION: ${{ needs.version-stamp.outputs.package_version }}
+      TARGET_PACKAGE: ${{ matrix.package }}
+    steps:
+      - name: Install CUDA runtime and driver stub
+        if: ${{ matrix.package != 'mooncake-transfer-engine-non-cuda' }}
+        env:
+          CUDA_PACKAGE_VERSION: ${{ matrix.package == 'mooncake-transfer-engine-cuda13' && '13-0' || '12-8' }}
+        run: |
+          set -euo pipefail
+          if [ "$(uname -m)" = x86_64 ]; then
+            repository_architecture=x86_64
+          else
+            repository_architecture=sbsa
+          fi
+          keyring=$(mktemp --suffix=.deb)
+          curl --fail --location --retry 3 \
+            "https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/${repository_architecture}/cuda-keyring_1.1-1_all.deb" \
+            --output "$keyring"
+          sudo dpkg -i "$keyring"
+          sudo apt-get update
+          sudo apt-get install -y \
+            "cuda-cudart-${CUDA_PACKAGE_VERSION}" \
+            "cuda-driver-dev-${CUDA_PACKAGE_VERSION}"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          name: mooncake-wheels-pre-release-${{ github.ref_name }}
-          path: mooncake-wheel/dist-release/*.whl
-          retention-days: 14
+          python-version: '3.12'
 
-      - name: Pre-release validation summary
+      - name: Download, install, and smoke the indexed wheel
         run: |
-          echo "## Pre-Release validation passed" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Tag: \`${GITHUB_REF_NAME}\`" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Wheels built: ${wheel_count}" >> "$GITHUB_STEP_SUMMARY"
-          echo "- PyPI publish: skipped (pre-release dry run)" >> "$GITHUB_STEP_SUMMARY"
-          echo "- GitHub Release upload: skipped (pre-release dry run)" >> "$GITHUB_STEP_SUMMARY"
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcurl4 libibverbs1 rdma-core librdmacm1 libnuma1 liburing2
+
+          download_dir=$(mktemp -d)
+
+          python -m pip download \
+            --index-url https://test.pypi.org/simple \
+            --no-cache-dir \
+            --no-deps \
+            --only-binary=:all: \
+            --pre \
+            --dest "$download_dir" \
+            "${TARGET_PACKAGE}==${PACKAGE_VERSION}"
+
+          # Install the wheel downloaded above. Its ordinary dependencies are
+          # resolved from production PyPI, never TestPyPI.
+          python -m pip install \
+            --index-url https://pypi.org/simple \
+            "$download_dir"/*.whl
+
+          if [ "$TARGET_PACKAGE" != mooncake-transfer-engine-non-cuda ]; then
+            cuda_stub=
+            for candidate in /usr/local/cuda*/lib64/stubs/libcuda.so \
+                             /usr/local/cuda*/targets/*/lib/stubs/libcuda.so; do
+              if [ -f "$candidate" ]; then
+                cuda_stub="$candidate"
+                break
+              fi
+            done
+            if [ -z "$cuda_stub" ]; then
+              echo "CUDA driver stub libcuda.so was not found"
+              exit 1
+            fi
+            stub_dir=$(mktemp -d)
+            ln -s "$cuda_stub" "$stub_dir/libcuda.so.1"
+            export LD_LIBRARY_PATH="$stub_dir:${LD_LIBRARY_PATH:-}"
+            for directory in /usr/local/cuda*/lib64 \
+                             /usr/local/cuda*/targets/*/lib; do
+              if [ -d "$directory" ]; then
+                export LD_LIBRARY_PATH="$directory:$LD_LIBRARY_PATH"
+              fi
+            done
+          fi
+
+          python - "$TARGET_PACKAGE" "$PACKAGE_VERSION" <<'PY'
+          import importlib.metadata
+          import sys
+
+          package, expected = sys.argv[1:]
+          installed = importlib.metadata.version(package)
+          if installed != expected:
+              raise SystemExit(
+                  f"installed {package} version {installed}, expected {expected}"
+              )
+
+          import mooncake
+          import mooncake.engine
+          import mooncake.http_metadata_server
+          import mooncake.store
+          PY
+          mooncake_http_metadata_server --help >/dev/null
+          mooncake_master --version
+
+  tone-integration:
+    name: Validate T-one integration with TestPyPI wheel
+    needs: [version-stamp, consume-testpypi]
+    uses: ./.github/workflows/integration-test.yml
+    with:
+      testpypi_version: ${{ needs.version-stamp.outputs.package_version }}
+    secrets: inherit
diff --git a/.github/workflows/publish-master-image.yaml b/.github/workflows/publish-master-image.yaml
index 9a62b6e6b1..0e941e67fc 100644
--- a/.github/workflows/publish-master-image.yaml
+++ b/.github/workflows/publish-master-image.yaml
@@ -6,20 +6,20 @@ name: Publish Master Image
 #
 # Two CUDA flavors are published from the same version input, because the wheel ships as
 # two PyPI projects that are versioned in lockstep:
-#   cuda12 -> mooncake-transfer-engine         -> :<version>            (and :latest)
-#   cuda13 -> mooncake-transfer-engine-cuda13  -> :<version>-cuda13     (and :latest-cuda13)
-# The cuda12 tag stays unsuffixed so existing pulls keep working. Each flavor is built
-# from its own Dockerfile (docker/master.Dockerfile, docker/master-cuda13.Dockerfile);
-# those two files must differ only in the CUDA-flavor lines, which `prepare` enforces.
+#   cuda12 -> mooncake-transfer-engine         -> :<version>-cuda12
+#   cuda13 -> mooncake-transfer-engine-cuda13  -> :<version>-cuda13
+# CUDA 13 is the default flavor: after smoke, :<version> aliases :<version>-cuda13. The
+# floating flavor tags are :cuda12 and :cuda13; :latest aliases :cuda13 when requested.
+# Each flavor is built from its own Dockerfile (docker/master.Dockerfile,
+# docker/master-cuda13.Dockerfile); those two files must differ only in the CUDA-flavor
+# lines, which `prepare` enforces.
 #
 # Publish flow: validate input -> check the Dockerfiles are in sync -> per flavor: confirm
-# amd64+arm64 wheels exist -> build multi-arch and push the :<version>[-cuda13] tag ->
-# smoke-test amd64 AND arm64 -> only then promote :latest[-cuda13] (when requested).
-# :latest is copied from the smoked :<version> digest, so the default pull tag can never
-# point at an image that failed smoke. A failed smoke still leaves the :<version> tag
-# public; since this is manual, delete it from Docker Hub by hand. The flavors run as
-# independent matrix legs with fail-fast disabled, so one flavor failing never cancels
-# the other mid-push.
+# amd64+arm64 wheels exist -> build multi-arch and push the :<version>-<flavor> tag ->
+# smoke-test amd64 AND arm64 -> only then promote aliases (when requested). A failed smoke
+# still leaves the fixed flavor tag public; since this is manual, delete it from Docker Hub
+# by hand. The flavors run as independent matrix legs with fail-fast disabled, so one flavor
+# failing never cancels the other mid-push.
 on:
   workflow_dispatch:
     inputs:
@@ -36,8 +36,8 @@ on:
           - both
           - cuda12
           - cuda13
-      tag_latest:
-        description: "Also move :latest (per flavor) to this build. Only enable when publishing the newest release (a backfill/retry of an older wheel must NOT move :latest)."
+      update_floating_tags:
+        description: "Move :cuda12/:cuda13 and the CUDA 13 default :latest. Enable only for the newest release."
         required: false
         default: false
         type: boolean
@@ -103,13 +103,11 @@ jobs:
                   "flavor": "cuda12",
                   "package": "mooncake-transfer-engine",
                   "dockerfile": "docker/master.Dockerfile",
-                  "tag_suffix": "",
               },
               "cuda13": {
                   "flavor": "cuda13",
                   "package": "mooncake-transfer-engine-cuda13",
                   "dockerfile": "docker/master-cuda13.Dockerfile",
-                  "tag_suffix": "-cuda13",
               },
           }
           sel = os.environ["FLAVORS"]
@@ -134,8 +132,8 @@ jobs:
       # inputs.*/matrix.* placed in env (not interpolated into shell source) — injection-safe.
       MOONCAKE_VERSION: ${{ inputs.mooncake_version }}
       MOONCAKE_PACKAGE: ${{ matrix.package }}
-      IMAGE_TAG: ${{ inputs.mooncake_version }}${{ matrix.tag_suffix }}
-      TAG_SUFFIX: ${{ matrix.tag_suffix }}
+      FLAVOR: ${{ matrix.flavor }}
+      IMAGE_TAG: ${{ inputs.mooncake_version }}-${{ matrix.flavor }}
       # Pinned for the official image: provenance must always be the public PyPI index.
       # Debug builds against another index belong in a separate workflow that does NOT
       # push official kvcacheai/mooncake tags.
@@ -193,11 +191,11 @@ jobs:
           username: kvcacheai
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      # Build multi-arch and push ONLY the immutable :<version>[-cuda13] tag. :latest is
-      # promoted in a later step, after smoke passes. provenance/sbom disabled to keep the
-      # index free of unknown/unknown attestation entries (they would otherwise show up in
-      # `imagetools inspect`).
-      - name: Build and push :<version>${{ matrix.tag_suffix }} (multi-arch)
+      # Build multi-arch and push ONLY the immutable :<version>-<flavor> tag. Default and
+      # floating aliases are promoted in later steps, after smoke passes. provenance/sbom
+      # disabled to keep the index free of unknown/unknown attestation entries (they would
+      # otherwise show up in `imagetools inspect`).
+      - name: Build and push :<version>-${{ matrix.flavor }} (multi-arch)
         id: build
         uses: docker/build-push-action@v6
         with:
@@ -209,12 +207,13 @@ jobs:
           build-args: |
             MOONCAKE_VERSION=${{ inputs.mooncake_version }}
             PIP_INDEX_URL=${{ env.PIP_INDEX_URL }}
-          tags: ${{ env.REPO }}:${{ inputs.mooncake_version }}${{ matrix.tag_suffix }}
+          tags: ${{ env.REPO }}:${{ inputs.mooncake_version }}-${{ matrix.flavor }}
           push: true
 
-      # Smoke tests run AFTER the :<version> push (a failed smoke leaves :<version> public
-      # — delete it from Docker Hub by hand; this manual workflow wires no auto-cleanup).
-      # :latest is NOT pushed yet, so a bad build can never poison the default pull tag.
+      # Smoke tests run AFTER the :<version>-<flavor> push (a failed smoke leaves the fixed
+      # flavor tag public — delete it from Docker Hub by hand; this manual workflow wires no
+      # auto-cleanup). Default and floating aliases are NOT pushed yet, so a bad build can
+      # never poison them.
       # We exercise real entrypoints, not just imports: `mooncake_master --version` runs the
       # compiled binary through the console-script/cli.py path and exits 0 (gflags
       # SetVersionString) — note `--help` would exit 1 under gflags, so --version is used.
@@ -243,13 +242,35 @@ jobs:
               echo "arm64 ok"
             '
 
-      # Promote :latest[-cuda13] ONLY after both arches pass smoke, and only when explicitly
-      # requested. imagetools create copies the tested :<version> manifest by digest
-      # (no rebuild), so :latest can never point at an image that didn't pass smoke.
-      # Each flavor promotes its own latest tag: cuda12 -> :latest, cuda13 -> :latest-cuda13.
-      - name: Promote :latest${{ matrix.tag_suffix }} (post-smoke)
-        if: ${{ inputs.tag_latest }}
+      # CUDA 13 is the default flavor. Create the unsuffixed version alias only after both
+      # arches pass smoke, using the build output digest rather than a mutable source tag.
+      - name: Promote :<version> (CUDA 13 default)
+        if: ${{ matrix.flavor == 'cuda13' }}
+        env:
+          BUILD_DIGEST: ${{ steps.build.outputs.digest }}
         run: |
           docker buildx imagetools create \
-            --tag "${REPO}:latest${TAG_SUFFIX}" \
-            "${REPO}:${IMAGE_TAG}"
+            --tag "${REPO}:${MOONCAKE_VERSION}" \
+            "${REPO}@${BUILD_DIGEST}"
+
+      # Promote the latest successful build for this CUDA flavor only when explicitly
+      # requested. A CUDA 12 backfill cannot move the default :latest tag.
+      - name: Promote :${{ matrix.flavor }} (post-smoke)
+        if: ${{ inputs.update_floating_tags }}
+        env:
+          BUILD_DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          docker buildx imagetools create \
+            --tag "${REPO}:${FLAVOR}" \
+            "${REPO}@${BUILD_DIGEST}"
+
+      # Keep exactly one default floating tag. It follows CUDA 13, matching the unsuffixed
+      # version alias above and Docker's meaning of :latest as the repository default.
+      - name: Promote :latest (CUDA 13 default, post-smoke)
+        if: ${{ inputs.update_floating_tags && matrix.flavor == 'cuda13' }}
+        env:
+          BUILD_DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          docker buildx imagetools create \
+            --tag "${REPO}:latest" \
+            "${REPO}@${BUILD_DIGEST}"
diff --git a/.github/workflows/release-efa-cuda13.yaml b/.github/workflows/release-efa-cuda13.yaml
index dcbfe7434f..4115a4bb89 100644
--- a/.github/workflows/release-efa-cuda13.yaml
+++ b/.github/workflows/release-efa-cuda13.yaml
@@ -8,18 +8,16 @@ on:
 # Publishes mooncake-transfer-engine-efa-cuda13, the CUDA 13-aware AWS EFA wheel.
 jobs:
   build:
+    if: ${{ !contains(github.ref_name, '-') }}
     permissions:
       contents: write
     uses: ./.github/workflows/_build-efa-wheel.yaml
     with:
       variant: cuda13
-      use-cuda: true
-      cuda-version: '13.0.2'
       python-versions: '["3.10", "3.11", "3.12", "3.13"]'
       build-profile: release
       cmake-args: >-
         -DUSE_HTTP=ON -DUSE_ETCD=ON -DWITH_EP=OFF -DSTORE_USE_ETCD=ON
-      variant-flag: EFA_CU13_BUILD
       artifact-prefix: mooncake-wheel-efa-cuda13
 
   publish-release:
diff --git a/.github/workflows/release-efa-non-cuda.yaml b/.github/workflows/release-efa-non-cuda.yaml
index 6ea27b00d6..e7825ae26d 100644
--- a/.github/workflows/release-efa-non-cuda.yaml
+++ b/.github/workflows/release-efa-non-cuda.yaml
@@ -8,17 +8,16 @@ on:
 # Publishes mooncake-transfer-engine-efa-non-cuda, the CPU/DRAM AWS EFA wheel.
 jobs:
   build:
+    if: ${{ !contains(github.ref_name, '-') }}
     permissions:
       contents: write
     uses: ./.github/workflows/_build-efa-wheel.yaml
     with:
       variant: non-cuda
-      use-cuda: false
       python-versions: '["3.10", "3.11", "3.12", "3.13"]'
       build-profile: release
       cmake-args: >-
         -DUSE_HTTP=ON -DUSE_ETCD=ON -DWITH_EP=OFF -DSTORE_USE_ETCD=ON
-      variant-flag: EFA_NON_CUDA_BUILD
       artifact-prefix: mooncake-wheel-efa-non-cuda
 
   publish-release:
diff --git a/.github/workflows/release-efa.yaml b/.github/workflows/release-efa.yaml
index c10d46bc89..ad3d30681c 100644
--- a/.github/workflows/release-efa.yaml
+++ b/.github/workflows/release-efa.yaml
@@ -8,18 +8,16 @@ on:
 # Publishes mooncake-transfer-engine-efa, the CUDA 12-aware AWS EFA wheel.
 jobs:
   build:
+    if: ${{ !contains(github.ref_name, '-') }}
     permissions:
       contents: write
     uses: ./.github/workflows/_build-efa-wheel.yaml
     with:
       variant: cuda
-      use-cuda: true
-      cuda-version: '12.8.1'
       python-versions: '["3.10", "3.11", "3.12", "3.13"]'
       build-profile: release
       cmake-args: >-
         -DUSE_HTTP=ON -DUSE_ETCD=ON -DWITH_EP=OFF -DSTORE_USE_ETCD=ON
-      variant-flag: EFA_BUILD
       artifact-prefix: mooncake-wheel-efa
 
   publish-release:
diff --git a/.github/workflows/release-rocm.yaml b/.github/workflows/release-rocm.yaml
index 060285da36..5f989ec0f3 100644
--- a/.github/workflows/release-rocm.yaml
+++ b/.github/workflows/release-rocm.yaml
@@ -56,6 +56,18 @@ jobs:
           fetch-depth: 0
           submodules: recursive
 
+      # workflow_dispatch may build a tag older than the verification helper.
+      # Keep release policy tied to the trusted workflow revision instead of
+      # relying on files from the historical source tree.
+      - name: Check out release verification helper
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.workflow_sha }}
+          path: .release-ci
+          persist-credentials: false
+          sparse-checkout: scripts/tone_tests/python/verify_rocm_wheel.py
+          sparse-checkout-cone-mode: false
+
       - name: Mark repository as safe
         shell: bash
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE" || true
@@ -131,12 +143,15 @@ jobs:
           rm -rf build && mkdir build && cd build
           cmake -G Ninja .. \
             -DUSE_HIP=ON -DUSE_CUDA=OFF -DWITH_EP=OFF \
+            -DENABLE_MULTI_PROTOCOL=ON \
             -DUSE_HTTP=ON -DUSE_ETCD=ON -DSTORE_USE_ETCD=ON \
             -DBUILD_UNIT_TESTS=OFF -DENABLE_DEBUG_SYMBOLS=OFF \
             -DCMAKE_BUILD_TYPE=Release \
             -DPython3_EXECUTABLE="${PYTHON_BIN}"
 
       - name: Build project
+        env:
+          MAX_JOBS: "2"
         shell: bash
         run: |
           set -eo pipefail
@@ -145,7 +160,7 @@ jobs:
           # Retry to ride out transient Go module (proxy.golang.org) fetch errors
           # during the etcd-wrapper build; Go caches modules, so retries resume.
           n=0
-          until cmake --build . -j"$(nproc)"; do
+          until cmake --build . -j"${MAX_JOBS}"; do
             n=$((n+1))
             if [ "$n" -ge 3 ]; then echo "Build failed after $n attempts"; exit 1; fi
             echo "Build attempt $n failed; retrying in 15s..."; sleep 15
@@ -187,13 +202,16 @@ jobs:
           # Install the actual per-matrix release artifact (cp310-cp313) into a
           # fresh venv and exercise the packaged binary, so packaging/ELF-layout
           # failures in any version are caught before this wheel reaches PyPI.
-          # No GPU is needed for `mooncake_master --version`.
+          # Import both native bindings as well as exercising the packaged
+          # binary. No GPU is needed for these load-time checks.
           smoke_venv=$(mktemp -d)
           "${PYTHON_BIN}" -m venv "$smoke_venv"
           "$smoke_venv/bin/python" -m pip install --no-deps \
             mooncake-wheel/dist-rocm-py${{ steps.generate_tag_release.outputs.python_version_tag }}/*.whl
           export LD_LIBRARY_PATH="/opt/rocm/lib:/usr/local/lib:${LD_LIBRARY_PATH:-}"
-          site="$("$smoke_venv/bin/python" -c 'import mooncake,os;print(os.path.dirname(mooncake.__file__))')"
+          "$smoke_venv/bin/python" \
+            .release-ci/scripts/tone_tests/python/verify_rocm_wheel.py
+          site="$("$smoke_venv/bin/python" -c 'import mooncake, os; print(os.path.dirname(mooncake.__file__))')"
           "$site/mooncake_master" --version
 
       - name: Upload Python wheel artifact
diff --git a/.gitmodules b/.gitmodules
index acc910c38d..aecfec5a1c 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -2,7 +2,3 @@
 	path = extern/pybind11
 	url = https://github.com/pybind/pybind11.git
 	branch = stable
-[submodule "extern/yalantinglibs"]
-	path = extern/yalantinglibs
-	url = https://github.com/alibaba/yalantinglibs.git
-	branch = v0.5.7
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e29bb9c9be..06600a0e65 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,8 @@
 # Pre-commit hooks configuration for Mooncake
 # Install: pip install -r requirements-dev.txt && pre-commit install
-# Run manually on all files: pre-commit run --all-files
+# Staged files: pre-commit run
+# PR-changed files: git fetch origin main && pre-commit run --files $(git diff --name-only --diff-filter=ACMR origin/main...HEAD)
+# Full-repo (intentional cleanup only): pre-commit run --all-files
 # Format all C/C++ files explicitly: ./scripts/code_format.sh --all
 # Note: clang-format should already be available (installed via system packages or dependencies.sh)
 # Exclusions: build artifacts, vendored extern code, generated wheels.
@@ -60,7 +62,7 @@ repos:
     hooks:
       - id: codespell
         exclude: '^(extern/|FAST25-release/)'
-        args: ['--ignore-words-list=te,mooncake,KVCache,cann,hsa']
+        args: ['--ignore-words-list=te,mooncake,KVCache,cann,hsa,crate']
 
   - repo: https://github.com/cheshirekow/cmake-format-precommit
     rev: v0.6.13
diff --git a/.typos.toml b/.typos.toml
index 4843e506f2..687e48866c 100644
--- a/.typos.toml
+++ b/.typos.toml
@@ -18,4 +18,8 @@ extend-exclude = [
   # DeepEP-derived elastic kernel headers keep upstream identifiers such as
   # `ue8m0x4`; exclude the imported header block from spelling checks.
   "mooncake-ep/include/elastic/*",
+  # Conductor hash golden vectors are generated digests and pickle byte
+  # dumps; hex runs collide with dictionary words. The generator scripts
+  # stay checked.
+  "mooncake-conductor/tests/fixtures/*.json",
 ]
diff --git a/AGENTS.md b/AGENTS.md
index f7332c2d0a..6ab75b16b9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,8 +18,10 @@
   checklist, and AI assistance disclosure.
 - For AI-assisted changes, make sure the human submitter has reviewed every
   changed line and can defend the change end-to-end.
-- Run pre-commit locally on the files touched by the change before handoff when
-  the toolchain is available. If broader hooks or `pre-commit run --all-files`
-  rewrite unrelated files, do not include those unrelated edits in the PR.
+- Before handoff, run pre-commit on the files touched by the change when the
+  toolchain is available (see `CONTRIBUTING.md` for the PR-scoped
+  `pre-commit run --files ...` command). Do not use
+  `pre-commit run --all-files` for routine PRs; if it rewrites unrelated
+  files, leave those edits out of the PR.
 - Keep PRs lean: review `git diff` before staging, and include only changes
   required for the requested task.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index a82f333c77..fe9c2569d6 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -4,21 +4,30 @@ project(mooncake CXX C)
 # indicates cmake is invoked from top-level dir
 set(GLOBAL_CONFIG "true")
 
+if(SKBUILD)
+  add_subdirectory(python)
+endif()
+
 include(mooncake-common/FindJsonCpp.cmake)
 include(mooncake-common/FindGLOG.cmake)
 include(mooncake-common/common.cmake)
 # unit test
-if (BUILD_UNIT_TESTS)
+if(BUILD_UNIT_TESTS)
   enable_testing()
 endif()
 
 option(WITH_TE "build mooncake transfer engine and sample code" ON)
 option(WITH_STORE "build mooncake store library and sample code" ON)
 option(WITH_STORE_GO "build Go bindings for mooncake store" OFF)
+option(WITH_CONDUCTOR "build mooncake conductor service" OFF)
 option(WITH_P2P_STORE "build p2p store library and sample code" OFF)
-option(WITH_RUST_EXAMPLE "build the Rust interface and sample code for the transfer engine" OFF)
+option(WITH_RUST_EXAMPLE
+       "build the Rust interface and sample code for the transfer engine" OFF)
 option(WITH_STORE_RUST "build the Rust bindings for the Mooncake Store" ON)
-option(WITH_STORE_C_SHARED "build a self-contained libmooncake_store.so exposing only the store_c.h C ABI (for dlopen consumers)" OFF)
+option(
+  WITH_STORE_C_SHARED
+  "build a self-contained libmooncake_store.so exposing only the store_c.h C ABI (for dlopen consumers)"
+  OFF)
 option(WITH_EP "build mooncake with expert parallelism support" OFF)
 option(USE_NOF "build mooncake store with NoF SSD pool support" OFF)
 option(MOONCAKE_ENABLE_TEST_FAILPOINTS
@@ -30,48 +39,82 @@ option(MOONCAKE_ENABLE_OPLOG_PERF_METRICS
        "Enable detailed batch OpLog performance metrics" OFF)
 
 include(${CMAKE_CURRENT_SOURCE_DIR}/mooncake-common/SetupPython.cmake)
-add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/extern/pybind11)
+if(SKBUILD)
+  set(PYBIND11_FINDPYTHON ON)
+  find_package(pybind11 CONFIG REQUIRED)
+else()
+  add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/extern/pybind11)
+endif()
 execute_process(
-    COMMAND ${PYTHON_EXECUTABLE} -c "import sys; print(sys.path[-1])"
-    OUTPUT_VARIABLE PYTHON_SYS_PATH
-)
+  COMMAND ${PYTHON_EXECUTABLE} -c "import sys; print(sys.path[-1])"
+  OUTPUT_VARIABLE PYTHON_SYS_PATH)
 string(STRIP ${PYTHON_SYS_PATH} PYTHON_SYS_PATH)
 
-if (USE_ETCD)
+if(USE_ETCD)
   add_compile_definitions(USE_ETCD)
-  if (USE_ETCD_LEGACY)
+  if(USE_ETCD_LEGACY)
     add_compile_definitions(USE_ETCD_LEGACY)
-    message(STATUS "etcd as metadata server support is enabled (etcd-cpp-api-v3)")
+    message(
+      STATUS "etcd as metadata server support is enabled (etcd-cpp-api-v3)")
   else()
     message(STATUS "etcd as metadata server support is enabled (go package)")
   endif()
 endif()
 option(STORE_USE_ETCD "build mooncake store with etcd" OFF)
-if (STORE_USE_ETCD)
+if(STORE_USE_ETCD)
   add_compile_definitions(STORE_USE_ETCD)
 endif()
 option(STORE_USE_REDIS "build mooncake store with redis" OFF)
-if (STORE_USE_REDIS)
+if(STORE_USE_REDIS)
   add_compile_definitions(STORE_USE_REDIS)
 endif()
-option(STORE_USE_K8S_LEASE "build mooncake store with K8s Lease leader election" OFF)
-if (STORE_USE_K8S_LEASE)
-  if (STORE_USE_ETCD)
-    message(FATAL_ERROR "STORE_USE_K8S_LEASE and STORE_USE_ETCD cannot be enabled together because both build Go c-shared HA backends.")
+option(ENABLE_KV_EVENTS
+       "Build master KV events ZMQ publisher (requires libzmq when ON)" OFF)
+option(STORE_USE_K8S_LEASE
+       "build mooncake store with K8s Lease leader election" OFF)
+if(STORE_USE_K8S_LEASE)
+  if(STORE_USE_ETCD)
+    message(
+      FATAL_ERROR
+        "STORE_USE_K8S_LEASE and STORE_USE_ETCD cannot be enabled together because both build Go c-shared HA backends."
+    )
   endif()
-  if (USE_ETCD AND NOT USE_ETCD_LEGACY)
-    message(FATAL_ERROR "STORE_USE_K8S_LEASE cannot be enabled with non-legacy USE_ETCD because both build Go c-shared libraries in the same process.")
+  if(USE_ETCD AND NOT USE_ETCD_LEGACY)
+    message(
+      FATAL_ERROR
+        "STORE_USE_K8S_LEASE cannot be enabled with non-legacy USE_ETCD because both build Go c-shared libraries in the same process."
+    )
   endif()
   add_compile_definitions(STORE_USE_K8S_LEASE)
 endif()
 
-if (USE_NOF)
+if(USE_NOF)
   add_compile_definitions(USE_NOF)
 else()
   message(STATUS "USE_NOF=OFF, NoF SSD pool support is disabled")
 endif()
 
-option(STORE_USE_JEMALLOC "Use jemalloc in mooncake store master" OFF)
+# The matching STORE_USE_JEMALLOC compile definition is scoped to the master and
+# client executables in mooncake-store/src, since only they link the allocator.
+option(STORE_USE_JEMALLOC
+       "Use jemalloc in the mooncake store master and client binaries" OFF)
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/Dependencies.cmake)
+if(WITH_STORE)
+  mooncake_provide_zstd()
+  mooncake_provide_xxhash()
+  if(ENABLE_KV_EVENTS)
+    mooncake_provide_libzmq()
+  endif()
+endif()
+if(WITH_STORE OR (WITH_TE AND USE_TENT))
+  mooncake_provide_liburing()
+endif()
+if((WITH_TE AND USE_REDIS) OR (WITH_STORE AND STORE_USE_REDIS))
+  mooncake_provide_hiredis(REQUIRED)
+elseif(WITH_TE AND USE_TENT)
+  mooncake_provide_hiredis()
+endif()
 
 # Define ASIO macros before building targets that include ASIO headers.
 add_compile_definitions(ASIO_SEPARATE_COMPILATION ASIO_DYN_LINK)
@@ -81,19 +124,24 @@ include_directories(mooncake-common/etcd)
 include_directories(mooncake-common/k8s-lease)
 include_directories(mooncake-common/include)
 
-if (WITH_TE)
+if(WITH_TE)
   add_subdirectory(mooncake-transfer-engine)
   include_directories(mooncake-transfer-engine/include)
 endif()
 
-if (WITH_STORE)
+if(WITH_STORE)
   message(STATUS "Mooncake Store will be built")
   add_subdirectory(mooncake-store)
   include_directories(mooncake-store/include)
 endif()
 
-if (WITH_STORE_RUST)
-  if (NOT WITH_STORE)
+if(WITH_CONDUCTOR)
+  message(STATUS "Mooncake Conductor will be built")
+  add_subdirectory(mooncake-conductor)
+endif()
+
+if(WITH_STORE_RUST)
+  if(NOT WITH_STORE)
     message(FATAL_ERROR "WITH_STORE_RUST=ON requires WITH_STORE=ON")
   endif()
   message(STATUS "Mooncake Store Rust bindings will be built")
@@ -101,115 +149,140 @@ if (WITH_STORE_RUST)
 endif()
 
 option(EP_USE_IDE "Enable intelligent indexing for IDEs" OFF)
-if (WITH_EP)
+if(WITH_EP)
   add_subdirectory(mooncake-pg)
   include_directories(mooncake-pg/include)
 
-  if (EP_USE_IDE)
+  if(EP_USE_IDE)
     message(WARNING "EP_USE_IDE enabled. DO NOT USE IN PRODUCTION!")
     add_subdirectory(mooncake-ep)
     include_directories(mooncake-ep/include)
     add_library(
       mooncake_pg_torch_ide OBJECT
       mooncake-pg/torch/src/mooncake_backend.cpp
-      mooncake-pg/torch/src/pg_py.cpp
-      mooncake-pg/torch/src/work_handles.cpp)
+      mooncake-pg/torch/src/pg_py.cpp mooncake-pg/torch/src/work_handles.cpp)
     # Reuse Mooncake EP's dependency include paths for clangd indexing.
     target_include_directories(
       mooncake_pg_torch_ide
-      PRIVATE mooncake-pg/torch/include
-              mooncake-pg/include
-              $<TARGET_PROPERTY:mooncake_ep,INCLUDE_DIRECTORIES>)
-  else ()
-    message(STATUS "WITH_EP enabled: building Mooncake EP and PG Python extensions")
+      PRIVATE mooncake-pg/torch/include mooncake-pg/include
+              $<TARGET_PROPERTY:_ep,INCLUDE_DIRECTORIES>)
+  else()
+    message(
+      STATUS
+        "WITH_EP enabled: building Mooncake EP natively and PG via setup.py")
     if(USE_CUDA)
       find_package(CUDAToolkit REQUIRED)
       message(STATUS "Detected CUDA version: ${CUDAToolkit_VERSION}")
     endif()
 
-    # EP_TORCH_VERSIONS: semicolon-separated list of PyTorch versions to build for.
-    # Can be set via -DEP_TORCH_VERSIONS="2.9.1;2.8.0" or the EP_TORCH_VERSIONS env var.
-    # Empty means build with the currently-installed torch.
+    add_subdirectory(mooncake-ep)
+    include_directories(mooncake-ep/include)
+
+    # EP_TORCH_VERSIONS: semicolon-separated list of PyTorch versions to build
+    # for. Can be set via -DEP_TORCH_VERSIONS="2.9.1;2.8.0" or the
+    # EP_TORCH_VERSIONS env var. Empty means build with the currently-installed
+    # torch.
     if(NOT EP_TORCH_VERSIONS)
       set(EP_TORCH_VERSIONS "$ENV{EP_TORCH_VERSIONS}")
     endif()
-    set(EP_TORCH_VERSIONS "${EP_TORCH_VERSIONS}" CACHE STRING
-        "PyTorch versions for EP/PG extensions, semicolon-separated (empty = use currently-installed torch)")
+    set(EP_TORCH_VERSIONS
+        "${EP_TORCH_VERSIONS}"
+        CACHE
+          STRING
+          "PyTorch versions for EP/PG extensions, semicolon-separated (empty = use currently-installed torch)"
+    )
+
+    if(SKBUILD AND NOT EP_TORCH_VERSIONS)
+      execute_process(
+        COMMAND ${Python3_EXECUTABLE} -c "import torch"
+        RESULT_VARIABLE _mooncake_python_has_torch
+        OUTPUT_QUIET ERROR_QUIET)
+      if(NOT _mooncake_python_has_torch EQUAL 0)
+        message(
+          FATAL_ERROR
+            "WITH_EP requires EP_TORCH_VERSIONS in an isolated scikit-build-core build because PyTorch is not installed in the build environment"
+        )
+      endif()
+    endif()
 
     # TORCH_CUDA_ARCH_LIST forwarded to the torch CUDA extension build.
     if(NOT TORCH_CUDA_ARCH_LIST)
       set(TORCH_CUDA_ARCH_LIST "$ENV{TORCH_CUDA_ARCH_LIST}")
     endif()
     if(NOT TORCH_CUDA_ARCH_LIST)
-      set(TORCH_CUDA_ARCH_LIST "8.0;9.0")
+      if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL "13.0")
+        set(TORCH_CUDA_ARCH_LIST "8.0;9.0;10.3")
+      else()
+        set(TORCH_CUDA_ARCH_LIST "8.0;9.0")
+      endif()
     endif()
-    set(TORCH_CUDA_ARCH_LIST "${TORCH_CUDA_ARCH_LIST}" CACHE STRING
-        "CUDA arch list for EP/PG extension builds (e.g. \"8.0;9.0\")")
+    set(TORCH_CUDA_ARCH_LIST
+        "${TORCH_CUDA_ARCH_LIST}"
+        CACHE STRING
+              "CUDA arch list for EP/PG extension builds (e.g. \"8.0;9.0\")")
 
-    # Staging directory: EP/PG .so files are placed here during make and later
-    # injected into the wheel AFTER auditwheel, so patchelf never touches the
-    # CUDA fatbins (which would cause cudaErrorInvalidKernelImage at runtime).
+    # Keep generated Torch extensions and device libraries in backend-owned
+    # build directories. The legacy release path injects the staged device
+    # artifacts after auditwheel; scikit-build-core installs them directly into
+    # its private wheel tree.
     set(EP_PG_STAGING_DIR "${CMAKE_BINARY_DIR}/ep_pg_staging")
+    set(EP_PG_BUILD_DIR "${CMAKE_BINARY_DIR}/ep_pg_build")
+    file(REMOVE_RECURSE "${EP_PG_STAGING_DIR}" "${EP_PG_BUILD_DIR}")
+    file(MAKE_DIRECTORY "${EP_PG_STAGING_DIR}" "${EP_PG_BUILD_DIR}")
 
-    # Convert semicolon-separated lists to pipe-separated strings so they survive
-    # CMake's COMMAND list-splitting (semicolons are CMake list separators).
+    # Convert semicolon-separated lists to pipe-separated strings so they
+    # survive CMake's COMMAND list-splitting (semicolons are CMake list
+    # separators).
     string(REPLACE ";" "|" _ep_torch_versions_pipe "${EP_TORCH_VERSIONS}")
     string(REPLACE ";" "|" _torch_cuda_arch_list_pipe "${TORCH_CUDA_ARCH_LIST}")
 
-    add_custom_target(mooncake_ep_ext ALL
-      COMMAND ${CMAKE_COMMAND} -E make_directory "${EP_PG_STAGING_DIR}"
-      COMMAND ${CMAKE_COMMAND}
-        "-DSOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR}/mooncake-ep"
-        "-DEP_CUDA_MAJOR=${CUDAToolkit_VERSION_MAJOR}"
-        "-DEP_CUDA_MINOR=${CUDAToolkit_VERSION_MINOR}"
-        "-DEP_TORCH_VERSIONS=${_ep_torch_versions_pipe}"
-        "-DTORCH_CUDA_ARCH_LIST=${_torch_cuda_arch_list_pipe}"
-        "-DSTAGING_DIR=${EP_PG_STAGING_DIR}"
-        "-DENGINE_SO_PATH=$<TARGET_FILE:engine>"
-        "-DPython3_EXECUTABLE=${Python3_EXECUTABLE}"
-        "-DEP_USE_MUSA=$<IF:$<BOOL:${USE_MUSA}>,1,0>"
-        "-DEP_USE_MACA=$<IF:$<BOOL:${USE_MACA}>,1,0>"
-        -P "${CMAKE_CURRENT_SOURCE_DIR}/mooncake-ep/BuildEpExt.cmake"
-      COMMENT "Building Mooncake EP Python extension(s)"
-      DEPENDS engine
-      VERBATIM
-    )
+    if(USE_CUDA)
+      add_custom_target(
+        mooncake_ep_device_stage ALL
+        COMMAND ${CMAKE_COMMAND} -E make_directory "${EP_PG_STAGING_DIR}"
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+                "$<TARGET_FILE:mooncake_ep_device>" "${EP_PG_STAGING_DIR}/"
+        COMMENT "Staging Mooncake EP CUDA device library"
+        DEPENDS mooncake_ep_device
+        VERBATIM)
+    endif()
 
-    add_custom_target(mooncake_pg_ext ALL
+    add_custom_target(
+      mooncake_pg_ext ALL
       COMMAND ${CMAKE_COMMAND} -E make_directory "${EP_PG_STAGING_DIR}"
-      COMMAND ${CMAKE_COMMAND}
+      COMMAND
+        ${CMAKE_COMMAND}
         "-DSOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR}/mooncake-pg/torch"
         "-DEP_CUDA_MAJOR=${CUDAToolkit_VERSION_MAJOR}"
         "-DEP_CUDA_MINOR=${CUDAToolkit_VERSION_MINOR}"
         "-DEP_TORCH_VERSIONS=${_ep_torch_versions_pipe}"
-        "-DSTAGING_DIR=${EP_PG_STAGING_DIR}"
+        "-DSTAGING_DIR=${EP_PG_STAGING_DIR}" "-DBUILD_DIR=${EP_PG_BUILD_DIR}"
         "-DPG_CORE_SO_PATH=$<TARGET_FILE:mooncake_pg>"
         "-DPG_DEVICE_SO_PATH=$<TARGET_FILE:mooncake_pg_device>"
         "-DPython3_EXECUTABLE=${Python3_EXECUTABLE}"
         "-DEP_USE_MUSA=$<IF:$<BOOL:${USE_MUSA}>,1,0>"
-        "-DEP_USE_MACA=$<IF:$<BOOL:${USE_MACA}>,1,0>"
-        -P "${CMAKE_CURRENT_SOURCE_DIR}/mooncake-pg/torch/BuildPgExt.cmake"
+        "-DEP_USE_MACA=$<IF:$<BOOL:${USE_MACA}>,1,0>" -P
+        "${CMAKE_CURRENT_SOURCE_DIR}/mooncake-pg/torch/BuildPgExt.cmake"
       COMMENT "Building Mooncake PG Python extension(s)"
-      DEPENDS mooncake_pg mooncake_pg_device mooncake_ep_ext
-      VERBATIM
-    )
-  endif ()
+      DEPENDS mooncake_pg mooncake_pg_device
+      VERBATIM)
+  endif()
 endif()
 
 add_subdirectory(mooncake-integration)
 
-if (WITH_STORE_GO AND WITH_STORE)
+if(WITH_STORE_GO AND WITH_STORE)
   add_custom_target(build_store_go DEPENDS mooncake_store transfer_engine)
   add_custom_command(
-      TARGET build_store_go
-      COMMAND bash build.sh ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR} ${USE_ETCD} ${USE_REDIS} ${USE_HTTP} ${USE_ETCD_LEGACY}
-      WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/mooncake-store/go
-  )
+    TARGET build_store_go
+    COMMAND bash build.sh ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}
+            ${USE_ETCD} ${USE_REDIS} ${USE_HTTP} ${USE_ETCD_LEGACY}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/mooncake-store/go)
   set_property(TARGET build_store_go PROPERTY EXCLUDE_FROM_ALL FALSE)
   message(STATUS "Mooncake Store Go bindings will be built")
 endif()
 
-if (WITH_P2P_STORE)
+if(WITH_P2P_STORE)
   add_subdirectory(mooncake-p2p-store)
   message(STATUS "P2P Store will be built")
 endif()
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 68d0741220..d29ca43570 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,6 +22,7 @@ Prefer one of the following documented prefixes:
 - ``[Bugfix]`` for bug fixes.
 - ``[CI/Build]`` for build or continuous integration improvements.
 - ``[Doc]`` for documentation fixes and improvements.
+- ``[Conductor]`` for changes in the ``mooncake-conductor``.
 - ``[Integration]`` for changes in the ``mooncake-integration``.
 - ``[P2PStore]`` for changes in the ``mooncake-p2p-store``.
 - ``[Store]`` for changes in the ``mooncake-store``.
@@ -34,9 +35,12 @@ when they better match the change scope: ``[Bug fix]``, ``[Build]``, ``[CI]``,
 ``[Docs]``, ``[EP]``, ``[Feature]``, ``[MUSA]``, ``[PG]``, ``[TE]``,
 ``[TENT]``, and ``[Wheel]``.
 
-### RFC Discussion
+### Notes for Large Changes
 
-For major architectural changes (>500 LOC excluding tests), we would expect a GitHub issue (RFC) discussing the technical design and justification.
+Please keep changes as concise as possible. For major architectural changes
+(>500 LOC excluding kernel/data/config/test), we expect a GitHub issue (RFC)
+that discusses the technical design and justification. Otherwise, the PR may be
+tagged with `rfc-required` and might not be reviewed until an RFC is provided.
 
 
 ### Development Workflow & Pre-commit Hooks
@@ -65,9 +69,21 @@ committing again. Use `./scripts/code_format.sh --all` only when intentionally
 formatting the whole project.
 
 #### Usage
-Run hooks on all files (the first run installs hook environments). The C/C++
-hook remains limited to staged line ranges; use `./scripts/code_format.sh --all`
-for an intentional whole-project C/C++ format:
+After `pre-commit install`, hooks run on each commit. To run them manually on
+staged files (the first run may install hook environments):
+```bash
+pre-commit run
+```
+Before opening a PR, run hooks only on files changed against the PR base
+(default `origin/main`). The C/C++ hook remains limited to staged or changed
+line ranges:
+```bash
+git fetch origin main
+pre-commit run --files $(git diff --name-only --diff-filter=ACMR origin/main...HEAD)
+```
+Use full-repo checks only for intentional whole-project cleanup; do not fold
+unrelated rewrites into a feature PR. Prefer `./scripts/code_format.sh --all`
+for a deliberate whole-project C/C++ format:
 ```bash
 pre-commit run --all-files
 ```
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
index 297963d94c..24260e376e 100644
--- a/MAINTAINERS.md
+++ b/MAINTAINERS.md
@@ -12,6 +12,7 @@ Current list of codeowners on this project:
 | ---------------------------- | ---------------------------- | ---------------------------- | ---------------------------- |
 | <img src="image/partners/approaching_ai_logo.png" width="120"/> | <img src="image/partners/ant_group_logo.png" width="120"/> | <img src="image/partners/huawei_logo.png" width="120"/> | <img src="image/partners/nvidia_logo.png" width="120"/> |
 | <img src="image/partners/moore_thread_logo.jpg" width="120"/> | <img src="image/partners/tencent_logo.png" width="120"/> | <img src="image/partners/volcengine_logo.png" width="120"/> | <img src="image/partners/amd_logo.png" width="120"/> |
-| <img src="image/partners/ieitsystems_logo.png" width="120"/> | <img src="image/partners/sunrise_logo.png" width="120"/> | <img src="image/partners/hygon_logo.png" width="120"/> | |
+| <img src="image/partners/ieitsystems_logo.png" width="120"/> | <img src="image/partners/sunrise_logo.png" width="120"/> | <img src="image/partners/hygon_logo.png" width="120"/> | <img src="image/partners/aws-logo.png" width="120"/> |
+| <img src="image/hardwares/MetaX_logo.png" width="120"/> | | | |
 
 Want to include your company logo? Just open a Pull Request!
\ No newline at end of file
diff --git a/README.md b/README.md
index 5d0cb1f2ee..afd83df98c 100644
--- a/README.md
+++ b/README.md
@@ -24,9 +24,8 @@
   [![PyPI Non-CUDA](https://img.shields.io/static/v1?label=pypi&message=non-CUDA&color=00BFFF)](https://pypi.org/project/mooncake-transfer-engine-non-cuda/)
   [![PyPI NPU](https://img.shields.io/static/v1?label=pypi&message=NPU&color=F87171)](https://pypi.org/project/mooncake-transfer-engine-npu/)
   [![PyPI MUSA](https://img.shields.io/static/v1?label=pypi&message=MUSA&color=F97316)](https://pypi.org/project/mooncake-transfer-engine-musa/)
-  [![PyPI EFA CUDA 12](https://img.shields.io/static/v1?label=pypi&message=EFA%20%2B%20CUDA%2012&color=F59E0B)](https://pypi.org/project/mooncake-transfer-engine-efa/)
-  [![PyPI EFA CUDA 13](https://img.shields.io/static/v1?label=pypi&message=EFA%20%2B%20CUDA%2013&color=F59E0B)](https://pypi.org/project/mooncake-transfer-engine-efa-cuda13/)
-  [![PyPI EFA Non-CUDA](https://img.shields.io/static/v1?label=pypi&message=EFA%20non-CUDA&color=F59E0B)](https://pypi.org/project/mooncake-transfer-engine-efa-non-cuda/)
+  [![PyPI EFA](https://img.shields.io/static/v1?label=pypi&message=EFA&color=F59E0B)](https://pypi.org/project/mooncake-transfer-engine-efa/)
+  [![PyPI ROCm](https://img.shields.io/static/v1?label=pypi&message=ROCm&color=black)](https://pypi.org/project/mooncake-transfer-engine-rocm/)
 </div>
 <br/>
 
@@ -35,16 +34,18 @@ Under real workloads, Mooncake’s innovative architecture enables Kimi to handl
 
 <h2 id="updates">🔄 Updates</h2>
 
-- **Jul 2, 2026**: [DSpark](https://x.com/mgoin_/status/2072785822231728363) scales fully online training on a GB300 NVL72 system with Speculators and Mooncake: 9 vLLM nodes serve the GLM 5.2 FP8 verifier through Mooncake RDMA Store to 6 FSDP training nodes (DP=24), achieving 125k prefill tokens/s and 1.5 steps/s.
+- **Aug 24, 2026**: [AgentX / InferenceX v3](https://newsletter.semianalysis.com/p/agentx-inferencexv3-does-cuda-moat) highlights Mooncake's contributions to agentic inference workloads, including ROCm wheels, CI, and packaging improvements. [Mooncake optimization details](https://inferencex.semianalysis.com/agentx/optimizations/mooncake).
+- **Aug 20, 2026**: Mooncake is integrated into [Miles](https://github.com/radixark/miles) as a rollout data-transfer backend for the fragmented, heterogeneous data moving between rollout and training in disaggregated RL. Blogs: [KVCache.AI](https://kvcache.ai/blog/mooncake-rl-rollout-data-transfer/), [lmsys](https://www.lmsys.org/blog/2026-08-20-miles-mooncake-rollout-data-transfer).
+- **Aug 17, 2026**: Mooncake is integrated into [Speculators](https://github.com/vllm-project/speculators) as a distributed backend for multi-node online training, efficiently moves hidden-state between vLLM inference workers and Speculators trainers through RDMA, eliminating the need for massive hidden-state storage in offline training. [Benchmark on GB300 NVL72](https://x.com/mgoin_/status/2072785822231728363).
 - **May 7, 2026**: 🚀 [vLLM officially features Mooncake Store](https://vllm.ai/blog/mooncake-store) — a deep dive into how Mooncake's distributed KVCache engine supercharges vLLM inference with high-throughput, memory-efficient, cross-instance KV cache sharing!
 - **Apr 29, 2026**: SGLang introduces [RDMA-based P2P weight transfer for large-scale distributed RL](https://lmsys.org/blog/2026-04-29-p2p-update/) using Mooncake TransferEngine, achieving 7x faster weight updates for the 1T-parameter Kimi-K2 model (53s → 7.2s) with zero-copy RDMA transfer across thousands of GPUs.
 - **Mar 19, 2026**: [TorchSpec: Speculative Decoding Training at Scale](https://pytorch.org/blog/torchspec-speculative-decoding-training-at-scale) is [open sourced](https://github.com/torchspec-project/TorchSpec), using Mooncake to decouple inference and training via efficient hidden states management.
-- **Mar 5, 2026**: [LightX2V](https://github.com/ModelTC/LightX2V/pull/893) now supports disaggregated deployment based on Mooncake, enabling encoder/transformer service decoupling with Mooncake Transfer Engine for high-performance cross-device and cross-machine data transfer. Details in [blog](https://light-ai.top/LightX2V-BLOG/posts/Disaggregation/).
-- **Feb 25, 2026**: [SGLang](https://github.com/sgl-project/sglang) merged [Encoder Global Cache Manager](https://github.com/sgl-project/sglang/pull/16137), introducing a Mooncake-powered global multimodal embedding cache that enables cross-instance sharing of ViT embeddings to avoid redundant GPU computation.
 
 <details>
 <summary>More</summary>
 
+- **Mar 5, 2026**: [LightX2V](https://github.com/ModelTC/LightX2V/pull/893) now supports disaggregated deployment based on Mooncake, enabling encoder/transformer service decoupling with Mooncake Transfer Engine for high-performance cross-device and cross-machine data transfer. Details in [blog](https://light-ai.top/LightX2V-BLOG/posts/Disaggregation/).
+- **Feb 25, 2026**: [SGLang](https://github.com/sgl-project/sglang) merged [Encoder Global Cache Manager](https://github.com/sgl-project/sglang/pull/16137), introducing a Mooncake-powered global multimodal embedding cache that enables cross-instance sharing of ViT embeddings to avoid redundant GPU computation.
 - **Feb 24, 2026**: [vLLM-Omni](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/disaggregated_inference/) introduces disaggregated inference connectors with support for both `MooncakeStoreConnector` and `MooncakeTransferEngineConnector` for multi-node omni-modality pipelines.
 - **Feb 12, 2026**: [Mooncake Joins PyTorch Ecosystem](https://pytorch.org/blog/mooncake-joins-pytorch-ecosystem/) We are thrilled to announce that Mooncake has officially joined the PyTorch Ecosystem!
 - **Jan 28, 2026**: [FlexKV](https://github.com/taco-project/FlexKV), a distributed KV store and cache system from Tencent and NVIDIA in collaboration with the community, now supports [distributed KVCache reuse](https://github.com/taco-project/FlexKV/blob/main/docs/dist_reuse/README_en.md) with the Mooncake Transfer Engine.
@@ -214,6 +215,29 @@ pip install mooncake-transfer-engine
 pip install mooncake-transfer-engine-cuda13
 ```
 
+#### Master image
+
+The multi-architecture master image publishes explicit CUDA flavor tags:
+
+```bash
+# Fixed versions, recommended for production
+docker pull kvcacheai/mooncake:0.3.14-cuda12
+docker pull kvcacheai/mooncake:0.3.14-cuda13
+
+# CUDA 13 is the default flavor
+docker pull kvcacheai/mooncake:0.3.14
+docker pull kvcacheai/mooncake:latest
+
+# Floating flavor aliases
+docker pull kvcacheai/mooncake:cuda12
+docker pull kvcacheai/mooncake:cuda13
+```
+
+The unqualified `:<version>` and `:latest` tags point to CUDA 13 starting with the first
+release published by the new tagging workflow. Existing releases keep their original contents;
+use `:cuda12` or `:<version>-cuda12` when CUDA 12 is required. The former `:latest-cuda13` tag
+is deprecated and is not part of the new naming contract.
+
 In addition to CUDA, Mooncake also supports other accelerator backends, along with flexible installation and deployment options. See the guides below for details:
 
 - [Quick Start](https://kvcache-ai.github.io/Mooncake/getting_started/quick-start.html)
diff --git a/benchmarks/storage_benchmark_v1/benchmark.py b/benchmarks/storage_benchmark_v1/benchmark.py
index f840732393..a28f5493f6 100644
--- a/benchmarks/storage_benchmark_v1/benchmark.py
+++ b/benchmarks/storage_benchmark_v1/benchmark.py
@@ -24,9 +24,11 @@
 # Data Structures
 # ============================================================================
 
+
 @dataclass
 class KVCacheRequest:
     """KVCache request from trace"""
+
     timestamp: float
     hash_ids: List[int]
     input_length: int
@@ -37,6 +39,7 @@ class KVCacheRequest:
 # Trace Replay
 # ============================================================================
 
+
 class TraceReplay:
     """Trace replay handler"""
 
@@ -46,17 +49,19 @@ def __init__(self, trace_path: str):
     def load_all(self) -> List[KVCacheRequest]:
         """Load all requests from trace file"""
         requests = []
-        with open(self.trace_path, 'r', encoding='utf-8') as f:
+        with open(self.trace_path, "r", encoding="utf-8") as f:
             for line in f:
                 line = line.strip()
                 if line:
                     req = json.loads(line)
-                    requests.append(KVCacheRequest(
-                        timestamp=req.get('timestamp', 0),
-                        hash_ids=req.get('hash_ids', []),
-                        input_length=req.get('input_length', 0),
-                        output_length=req.get('output_length', 0),
-                    ))
+                    requests.append(
+                        KVCacheRequest(
+                            timestamp=req.get("timestamp", 0),
+                            hash_ids=req.get("hash_ids", []),
+                            input_length=req.get("input_length", 0),
+                            output_length=req.get("output_length", 0),
+                        )
+                    )
         return requests
 
 
@@ -64,16 +69,23 @@ def load_all(self) -> List[KVCacheRequest]:
 # Storage Benchmark
 # ============================================================================
 
+
 class StorageBenchmark:
     """KVCache storage benchmark
 
     Processes KVCache requests using layout-generated access patterns.
     """
 
-    def __init__(self, storage_dir: str, model_config: dict,
-                 page_size_tokens: int = 512,
-                 max_pages: int = 100000,
-                 fsync_mode: str = 'none', fsync_batch_size: int = 100):
+    def __init__(
+        self,
+        storage_dir: str,
+        model_config: dict,
+        page_size_tokens: int = 512,
+        max_pages: int = 100000,
+        file_mode: str = "single",
+        fsync_mode: str = "none",
+        fsync_batch_size: int = 100,
+    ):
         """Initialize benchmark
 
         Args:
@@ -81,6 +93,8 @@ def __init__(self, storage_dir: str, model_config: dict,
             model_config: Model configuration dict
             page_size_tokens: Tokens per page (default: 512)
             max_pages: Maximum number of pages
+            file_mode: 'single' = one big data.bin with slot offsets (default);
+                       'per-file' = one file per page
             fsync_mode: When to fsync ('none', 'batch', 'always', 'end')
             fsync_batch_size: Number of writes between fsync in batch mode
         """
@@ -93,19 +107,20 @@ def __init__(self, storage_dir: str, model_config: dict,
             storage_dir=storage_dir,
             page_size=self.page_size_bytes,
             max_pages=max_pages,
+            file_mode=file_mode,
             fsync_mode=fsync_mode,
-            fsync_batch_size=fsync_batch_size
+            fsync_batch_size=fsync_batch_size,
         )
 
         # Statistics
         self.stats = {
-            'total_requests': 0,
-            'total_tokens': 0,
-            'read_pages': 0,
-            'write_pages': 0,
-            'page_hits': 0,
-            'request_io_latencies_ms': [],
-            'request_wall_latencies_ms': [],
+            "total_requests": 0,
+            "total_tokens": 0,
+            "read_pages": 0,
+            "write_pages": 0,
+            "page_hits": 0,
+            "request_io_latencies_ms": [],
+            "request_wall_latencies_ms": [],
         }
 
     def process_request(self, req: KVCacheRequest) -> float:
@@ -117,8 +132,8 @@ def process_request(self, req: KVCacheRequest) -> float:
         Returns:
             Total latency in milliseconds
         """
-        self.stats['total_requests'] += 1
-        self.stats['total_tokens'] += req.input_length + req.output_length
+        self.stats["total_requests"] += 1
+        self.stats["total_tokens"] += req.input_length + req.output_length
 
         request_start = time.perf_counter()
         io_latency_ms = 0.0
@@ -127,47 +142,57 @@ def process_request(self, req: KVCacheRequest) -> float:
         for access in self.layout.get_operations(req):
             if self.storage.exists(access.page_id):
                 # Page exists, perform READ
-                io_latency_ms += self.storage.read(
+                latency = self.storage.read(
                     access.page_id,
                     offset_in_page=access.offset_in_page,
-                    length=access.length
+                    length=access.length,
                 )
-                self.stats['read_pages'] += 1
-                self.stats['page_hits'] += 1
+                if latency is None:
+                    continue
+                io_latency_ms += latency
+                self.stats["read_pages"] += 1
+                self.stats["page_hits"] += 1
             else:
                 # Page doesn't exist, perform WRITE
-                io_latency_ms += self.storage.write(
+                latency = self.storage.write(
                     access.page_id,
                     offset_in_page=access.offset_in_page,
-                    length=access.length
+                    length=access.length,
                 )
-                self.stats['write_pages'] += 1
+                if latency is None:
+                    continue
+                io_latency_ms += latency
+                self.stats["write_pages"] += 1
 
         wall_latency_ms = (time.perf_counter() - request_start) * 1000.0
-        self.stats['request_io_latencies_ms'].append(io_latency_ms)
-        self.stats['request_wall_latencies_ms'].append(wall_latency_ms)
+        self.stats["request_io_latencies_ms"].append(io_latency_ms)
+        self.stats["request_wall_latencies_ms"].append(wall_latency_ms)
         return io_latency_ms
 
     def get_stats(self) -> Dict:
         """Get statistics"""
         storage_stats = self.storage.get_stats()
-        request_io_latencies = self.stats['request_io_latencies_ms']
-        request_wall_latencies = self.stats['request_wall_latencies_ms']
+        request_io_latencies = self.stats["request_io_latencies_ms"]
+        request_wall_latencies = self.stats["request_wall_latencies_ms"]
 
-        total_pages = self.stats['read_pages'] + self.stats['write_pages']
+        total_pages = self.stats["read_pages"] + self.stats["write_pages"]
 
         return {
-            'total_requests': self.stats['total_requests'],
-            'total_tokens': self.stats['total_tokens'],
-            'total_pages': total_pages,
-            'read_pages': self.stats['read_pages'],
-            'write_pages': self.stats['write_pages'],
-            'page_hits': self.stats['page_hits'],
-            'page_hit_rate': self.stats['read_pages'] / total_pages if total_pages > 0 else 0,
-            'write_ratio': self.stats['write_pages'] / total_pages if total_pages > 0 else 0,
-            'request_io_latency': latency_stats(request_io_latencies),
-            'request_wall_latency': latency_stats(request_wall_latencies),
-            'storage': storage_stats,
+            "total_requests": self.stats["total_requests"],
+            "total_tokens": self.stats["total_tokens"],
+            "total_pages": total_pages,
+            "read_pages": self.stats["read_pages"],
+            "write_pages": self.stats["write_pages"],
+            "page_hits": self.stats["page_hits"],
+            "page_hit_rate": self.stats["read_pages"] / total_pages
+            if total_pages > 0
+            else 0,
+            "write_ratio": self.stats["write_pages"] / total_pages
+            if total_pages > 0
+            else 0,
+            "request_io_latency": latency_stats(request_io_latencies),
+            "request_wall_latency": latency_stats(request_wall_latencies),
+            "storage": storage_stats,
         }
 
     def __enter__(self):
@@ -185,6 +210,7 @@ def close(self, force_sync: bool = True):
 # Benchmark Runner
 # ============================================================================
 
+
 def get_max_page_id(requests: List[KVCacheRequest]) -> int:
     max_id = 0
     for req in requests:
@@ -194,16 +220,17 @@ def get_max_page_id(requests: List[KVCacheRequest]) -> int:
 
 
 def parse_csv_floats(value: str) -> List[float]:
-    return [float(item.strip()) for item in value.split(',') if item.strip()]
+    return [float(item.strip()) for item in value.split(",") if item.strip()]
 
 
-def wait_for_replay_time(req: KVCacheRequest, base_timestamp: float,
-                         start_time: float, replay_scale: float):
+def wait_for_replay_time(
+    req: KVCacheRequest, base_timestamp: float, start_time: float, replay_scale: float
+):
     if replay_scale <= 0 or req.timestamp == 0:
         return
-    target_time = (start_time +
-                   max(0.0, req.timestamp - base_timestamp) /
-                   (1000.0 * replay_scale))
+    target_time = start_time + max(0.0, req.timestamp - base_timestamp) / (
+        1000.0 * replay_scale
+    )
     delay = target_time - time.perf_counter()
     if delay > 0:
         time.sleep(delay)
@@ -211,7 +238,7 @@ def wait_for_replay_time(req: KVCacheRequest, base_timestamp: float,
 
 def latency_stats(values: List[float]) -> Dict[str, float]:
     if not values:
-        return {'avg_ms': 0, 'p50_ms': 0, 'p95_ms': 0, 'p99_ms': 0}
+        return {"avg_ms": 0, "p50_ms": 0, "p95_ms": 0, "p99_ms": 0}
 
     sorted_values = sorted(values)
 
@@ -222,51 +249,46 @@ def get_percentile(p: float) -> float:
         lower = int(rank)
         upper = min(lower + 1, len(sorted_values) - 1)
         weight = rank - lower
-        return (sorted_values[lower] * (1.0 - weight) +
-                sorted_values[upper] * weight)
+        return sorted_values[lower] * (1.0 - weight) + sorted_values[upper] * weight
 
     return {
-        'avg_ms': statistics.mean(values),
-        'p50_ms': get_percentile(0.50),
-        'p95_ms': get_percentile(0.95),
-        'p99_ms': get_percentile(0.99),
+        "avg_ms": statistics.mean(values),
+        "p50_ms": get_percentile(0.50),
+        "p95_ms": get_percentile(0.95),
+        "p99_ms": get_percentile(0.99),
     }
 
 
 def snapshot_thread_stats(benchmark: StorageBenchmark) -> Dict[str, Any]:
     storage = benchmark.storage
-    total_pages = benchmark.stats['read_pages'] + benchmark.stats['write_pages']
+    total_pages = benchmark.stats["read_pages"] + benchmark.stats["write_pages"]
     return {
-        'total_requests': benchmark.stats['total_requests'],
-        'total_tokens': benchmark.stats['total_tokens'],
-        'read_pages': benchmark.stats['read_pages'],
-        'write_pages': benchmark.stats['write_pages'],
-        'page_hits': benchmark.stats['page_hits'],
-        'request_io_latencies_ms': list(
-            benchmark.stats['request_io_latencies_ms']
-        ),
-        'request_wall_latencies_ms': list(
-            benchmark.stats['request_wall_latencies_ms']
-        ),
-        'read_bytes': storage.stats['read_bytes'],
-        'write_bytes': storage.stats['write_bytes'],
-        'read_time_s': storage.stats['read_time_s'],
-        'write_time_s': storage.stats['write_time_s'],
-        'read_latencies_ms': list(storage.stats['read_latencies_ms']),
-        'write_latencies_ms': list(storage.stats['write_latencies_ms']),
-        'sync_count': storage.stats['sync_count'],
-        'max_pages': storage.max_pages,
-        'written_pages': len(storage._written_pages),
-        'total_pages': total_pages,
+        "total_requests": benchmark.stats["total_requests"],
+        "total_tokens": benchmark.stats["total_tokens"],
+        "read_pages": benchmark.stats["read_pages"],
+        "write_pages": benchmark.stats["write_pages"],
+        "page_hits": benchmark.stats["page_hits"],
+        "request_io_latencies_ms": list(benchmark.stats["request_io_latencies_ms"]),
+        "request_wall_latencies_ms": list(benchmark.stats["request_wall_latencies_ms"]),
+        "read_bytes": storage.stats["read_bytes"],
+        "write_bytes": storage.stats["write_bytes"],
+        "read_time_s": storage.stats["read_time_s"],
+        "write_time_s": storage.stats["write_time_s"],
+        "read_latencies_ms": list(storage.stats["read_latencies_ms"]),
+        "write_latencies_ms": list(storage.stats["write_latencies_ms"]),
+        "sync_count": storage.stats["sync_count"],
+        "max_pages": storage.max_pages,
+        "written_pages": len(storage._written_pages),
+        "total_pages": total_pages,
     }
 
 
 def aggregate_thread_stats(thread_stats: List[Dict[str, Any]]) -> Dict:
-    total_requests = sum(s['total_requests'] for s in thread_stats)
-    total_tokens = sum(s['total_tokens'] for s in thread_stats)
-    read_pages = sum(s['read_pages'] for s in thread_stats)
-    write_pages = sum(s['write_pages'] for s in thread_stats)
-    page_hits = sum(s['page_hits'] for s in thread_stats)
+    total_requests = sum(s["total_requests"] for s in thread_stats)
+    total_tokens = sum(s["total_tokens"] for s in thread_stats)
+    read_pages = sum(s["read_pages"] for s in thread_stats)
+    write_pages = sum(s["write_pages"] for s in thread_stats)
+    page_hits = sum(s["page_hits"] for s in thread_stats)
     total_pages = read_pages + write_pages
 
     request_io_latencies = []
@@ -274,74 +296,83 @@ def aggregate_thread_stats(thread_stats: List[Dict[str, Any]]) -> Dict:
     read_latencies = []
     write_latencies = []
     for stats in thread_stats:
-        request_io_latencies.extend(stats['request_io_latencies_ms'])
-        request_wall_latencies.extend(stats['request_wall_latencies_ms'])
-        read_latencies.extend(stats['read_latencies_ms'])
-        write_latencies.extend(stats['write_latencies_ms'])
+        request_io_latencies.extend(stats["request_io_latencies_ms"])
+        request_wall_latencies.extend(stats["request_wall_latencies_ms"])
+        read_latencies.extend(stats["read_latencies_ms"])
+        write_latencies.extend(stats["write_latencies_ms"])
 
-    read_bytes = sum(s['read_bytes'] for s in thread_stats)
-    write_bytes = sum(s['write_bytes'] for s in thread_stats)
-    read_time = sum(s['read_time_s'] for s in thread_stats)
-    write_time = sum(s['write_time_s'] for s in thread_stats)
+    read_bytes = sum(s["read_bytes"] for s in thread_stats)
+    write_bytes = sum(s["write_bytes"] for s in thread_stats)
+    read_time = sum(s["read_time_s"] for s in thread_stats)
+    write_time = sum(s["write_time_s"] for s in thread_stats)
 
     return {
-        'total_requests': total_requests,
-        'total_tokens': total_tokens,
-        'total_pages': total_pages,
-        'read_pages': read_pages,
-        'write_pages': write_pages,
-        'page_hits': page_hits,
-        'page_hit_rate': read_pages / total_pages if total_pages > 0 else 0,
-        'write_ratio': write_pages / total_pages if total_pages > 0 else 0,
-        'request_io_latency': latency_stats(request_io_latencies),
-        'request_wall_latency': latency_stats(request_wall_latencies),
-        'storage': {
-            'read': {
-                'count': read_pages,
-                'mb': read_bytes / 1024 / 1024,
-                'time_s': read_time,
+        "total_requests": total_requests,
+        "total_tokens": total_tokens,
+        "total_pages": total_pages,
+        "read_pages": read_pages,
+        "write_pages": write_pages,
+        "page_hits": page_hits,
+        "page_hit_rate": read_pages / total_pages if total_pages > 0 else 0,
+        "write_ratio": write_pages / total_pages if total_pages > 0 else 0,
+        "request_io_latency": latency_stats(request_io_latencies),
+        "request_wall_latency": latency_stats(request_wall_latencies),
+        "storage": {
+            "read": {
+                "count": read_pages,
+                "mb": read_bytes / 1024 / 1024,
+                "time_s": read_time,
                 **latency_stats(read_latencies),
             },
-            'write': {
-                'count': write_pages,
-                'mb': write_bytes / 1024 / 1024,
-                'time_s': write_time,
+            "write": {
+                "count": write_pages,
+                "mb": write_bytes / 1024 / 1024,
+                "time_s": write_time,
                 **latency_stats(write_latencies),
             },
-            'sync_count': sum(s['sync_count'] for s in thread_stats),
-            'max_pages': sum(s['max_pages'] for s in thread_stats),
-            'written_pages': sum(s['written_pages'] for s in thread_stats),
-            'page_hits': page_hits,
-            'page_misses': write_pages,
+            "sync_count": sum(s["sync_count"] for s in thread_stats),
+            "max_pages": sum(s["max_pages"] for s in thread_stats),
+            "written_pages": sum(s["written_pages"] for s in thread_stats),
+            "page_hits": page_hits,
+            "page_misses": write_pages,
         },
     }
 
 
-def print_progress(done: int, total: int, start_time: float,
-                   stats: Dict, req: KVCacheRequest = None,
-                   suffix: str = ""):
+def print_progress(
+    done: int,
+    total: int,
+    start_time: float,
+    stats: Dict,
+    req: KVCacheRequest = None,
+    suffix: str = "",
+):
     elapsed = time.perf_counter() - start_time
     qps = done / elapsed if elapsed > 0 else 0
-    storage = stats.get('storage', {})
-    read_stats = storage.get('read', {})
-    write_stats = storage.get('write', {})
-    read_time = read_stats.get('time_s', 0)
-    write_time = write_stats.get('time_s', 0)
-    read_mbps = read_stats.get('mb', 0) / read_time if read_time > 0 else 0
-    write_mbps = write_stats.get('mb', 0) / write_time if write_time > 0 else 0
+    storage = stats.get("storage", {})
+    read_stats = storage.get("read", {})
+    write_stats = storage.get("write", {})
+    read_time = read_stats.get("time_s", 0)
+    write_time = write_stats.get("time_s", 0)
+    read_mbps = read_stats.get("mb", 0) / read_time if read_time > 0 else 0
+    write_mbps = write_stats.get("mb", 0) / write_time if write_time > 0 else 0
 
     if req is None:
         req_info = ""
     else:
-        req_info = (f" ids={len(req.hash_ids):3d} "
-                    f"tokens={req.input_length + req.output_length:6d} |")
+        req_info = (
+            f" ids={len(req.hash_ids):3d} "
+            f"tokens={req.input_length + req.output_length:6d} |"
+        )
 
-    print(f"  [{done:5d}/{total}]{req_info} QPS={qps:7.2f} | "
-          f"R={stats['read_pages']:6d} "
-          f"({read_stats.get('avg_ms', 0):6.2f}ms, {read_mbps:6.1f}MB/s) | "
-          f"W={stats['write_pages']:6d} "
-          f"({write_stats.get('avg_ms', 0):6.2f}ms, {write_mbps:6.1f}MB/s)"
-          f"{suffix}")
+    print(
+        f"  [{done:5d}/{total}]{req_info} QPS={qps:7.2f} | "
+        f"R={stats['read_pages']:6d} "
+        f"({read_stats.get('avg_ms', 0):6.2f}ms, {read_mbps:6.1f}MB/s) | "
+        f"W={stats['write_pages']:6d} "
+        f"({write_stats.get('avg_ms', 0):6.2f}ms, {write_mbps:6.1f}MB/s)"
+        f"{suffix}"
+    )
 
 
 def should_print_progress(done: int, total: int, progress_interval: int) -> bool:
@@ -350,10 +381,12 @@ def should_print_progress(done: int, total: int, progress_interval: int) -> bool
     return progress_interval > 0 and done % progress_interval == 0
 
 
-def run_single_thread(benchmark: StorageBenchmark,
-                      requests: List[KVCacheRequest],
-                      replay_scale: float,
-                      progress_interval: int) -> Dict[str, Any]:
+def run_single_thread(
+    benchmark: StorageBenchmark,
+    requests: List[KVCacheRequest],
+    replay_scale: float,
+    progress_interval: int,
+) -> Dict[str, Any]:
     start_time = time.perf_counter()
     base_timestamp = requests[0].timestamp if requests else 0
     completed = 0
@@ -363,19 +396,22 @@ def run_single_thread(benchmark: StorageBenchmark,
         benchmark.process_request(req)
         completed += 1
         if should_print_progress(completed, len(requests), progress_interval):
-            print_progress(completed, len(requests), start_time,
-                           benchmark.get_stats(), req)
+            print_progress(
+                completed, len(requests), start_time, benchmark.get_stats(), req
+            )
 
     return {
-        'completed': completed,
-        'elapsed': time.perf_counter() - start_time,
-        'stats': benchmark.get_stats(),
+        "completed": completed,
+        "elapsed": time.perf_counter() - start_time,
+        "stats": benchmark.get_stats(),
     }
 
 
-def run_multi_thread(benchmarks: List[StorageBenchmark],
-                     requests: List[KVCacheRequest],
-                     replay_scale: float) -> Dict[str, Any]:
+def run_multi_thread(
+    benchmarks: List[StorageBenchmark],
+    requests: List[KVCacheRequest],
+    replay_scale: float,
+) -> Dict[str, Any]:
     start_time = time.perf_counter()
     base_timestamp = requests[0].timestamp if requests else 0
     total_requests = len(requests) * len(benchmarks)
@@ -397,24 +433,36 @@ def run_worker(thread_id: int):
         for future in as_completed(futures):
             worker_stats = future.result()
             thread_stats.append(worker_stats)
-            completed += worker_stats['total_requests']
-            print_progress(completed, total_requests, start_time,
-                           aggregate_thread_stats(thread_stats),
-                           suffix=" | completed worker")
+            completed += worker_stats["total_requests"]
+            print_progress(
+                completed,
+                total_requests,
+                start_time,
+                aggregate_thread_stats(thread_stats),
+                suffix=" | completed worker",
+            )
 
     return {
-        'completed': completed,
-        'elapsed': time.perf_counter() - start_time,
-        'stats': aggregate_thread_stats(thread_stats),
+        "completed": completed,
+        "elapsed": time.perf_counter() - start_time,
+        "stats": aggregate_thread_stats(thread_stats),
     }
 
 
-def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
-                  max_requests: int = None, max_pages: int = None,
-                  page_size_tokens: int = 512,
-                  fsync_mode: str = 'none', fsync_batch_size: int = 100,
-                  threads: int = 1, replay_scale: float = 0.0,
-                  progress_interval: int = 100) -> Dict:
+def run_benchmark(
+    trace_path: str,
+    storage_dir: str,
+    model_config: dict,
+    max_requests: int = None,
+    max_pages: int = None,
+    page_size_tokens: int = 512,
+    file_mode: str = "single",
+    fsync_mode: str = "none",
+    fsync_batch_size: int = 100,
+    threads: int = 1,
+    replay_scale: float = 0.0,
+    progress_interval: int = 100,
+) -> Dict:
     """Run benchmark
 
     Args:
@@ -424,6 +472,8 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
         max_requests: Maximum number of requests (None = all)
         max_pages: Maximum number of pages (None = auto-calculate)
         page_size_tokens: Tokens per page
+        file_mode: 'single' = one big data.bin with slot offsets (default);
+                   'per-file' = one file per page
         fsync_mode: When to fsync
         fsync_batch_size: Number of writes between fsync
         threads: Benchmark client worker threads
@@ -438,8 +488,13 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
     print(f"Model: {model_config['name']}")
     print(f"Layers: {model_config['num_layers']}")
     print(f"Page size: {page_size_tokens} tokens")
+    print(f"File mode: {file_mode}")
     print(f"Threads: {threads}")
-    print(f"Fast-forward: {replay_scale:g}x" if replay_scale > 0 else "Fast-forward: unpaced")
+    print(
+        f"Fast-forward: {replay_scale:g}x"
+        if replay_scale > 0
+        else "Fast-forward: unpaced"
+    )
     print(f"{'='*80}")
 
     # Load trace
@@ -472,7 +527,7 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
     max_size_gb = max_pages * page_size_bytes / (1024**3)
     trace_size_gb = max_pages_needed * page_size_bytes / (1024**3)
 
-    print(f"\n[Storage Configuration]")
+    print("\n[Storage Configuration]")
     print(f"  Max page_id in trace:             {max_page_id:,}")
     print(f"  Pages needed (trace):             {max_pages_needed:,}")
     print(f"  Trace storage size:               {trace_size_gb:.2f} GB")
@@ -487,12 +542,18 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
         shortfall = max_pages_needed - max_pages
         shortfall_gb = shortfall * page_size_bytes / (1024**3)
         compression_ratio = max_pages / max_pages_needed
-        print(f"\n  ⚠️  Storage insufficient: {shortfall:,} pages shortfall ({shortfall_gb:.2f} GB)")
-        print(f"  ⚠️  Consider increasing --max-pages to at least {max_pages_needed:,} for full simulation")
+        print(
+            f"\n  ⚠️  Storage insufficient: {shortfall:,} pages shortfall ({shortfall_gb:.2f} GB)"
+        )
+        print(
+            f"  ⚠️  Consider increasing --max-pages to at least {max_pages_needed:,} for full simulation"
+        )
     else:
         surplus = max_pages - max_pages_needed
         surplus_pct = (surplus / max_pages) * 100 if max_pages > 0 else 0
-        print(f"  ✓ Direct mapping: all {max_pages_needed:,} logical pages uniquely mapped")
+        print(
+            f"  ✓ Direct mapping: all {max_pages_needed:,} logical pages uniquely mapped"
+        )
 
     try:
         if threads <= 1:
@@ -501,62 +562,76 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
                 model_config=model_config,
                 page_size_tokens=page_size_tokens,
                 max_pages=max_pages,
+                file_mode=file_mode,
                 fsync_mode=fsync_mode,
-                fsync_batch_size=fsync_batch_size
+                fsync_batch_size=fsync_batch_size,
             ) as benchmark:
-                result = run_single_thread(benchmark, requests, replay_scale,
-                                           progress_interval)
+                result = run_single_thread(
+                    benchmark, requests, replay_scale, progress_interval
+                )
         else:
             with ExitStack() as stack:
                 benchmarks = [
-                    stack.enter_context(StorageBenchmark(
-                        storage_dir=str(Path(storage_dir) / f"thread_{thread_id}"),
-                        model_config=model_config,
-                        page_size_tokens=page_size_tokens,
-                        max_pages=max_pages,
-                        fsync_mode=fsync_mode,
-                        fsync_batch_size=fsync_batch_size
-                    ))
+                    stack.enter_context(
+                        StorageBenchmark(
+                            storage_dir=str(Path(storage_dir) / f"thread_{thread_id}"),
+                            model_config=model_config,
+                            page_size_tokens=page_size_tokens,
+                            max_pages=max_pages,
+                            file_mode=file_mode,
+                            fsync_mode=fsync_mode,
+                            fsync_batch_size=fsync_batch_size,
+                        )
+                    )
                     for thread_id in range(threads)
                 ]
                 result = run_multi_thread(benchmarks, requests, replay_scale)
     except KeyboardInterrupt:
         print(f"\n\n{'='*80}")
-        print(f"Interrupted! Showing partial results:")
+        print("Interrupted! Showing partial results:")
         print(f"{'='*80}")
-        result = result if 'result' in locals() else {
-            'completed': 0,
-            'elapsed': 0,
-            'stats': {},
-        }
-        print_results([{
-            'trace_file': Path(trace_path).name,
-            'total_requests': result['completed'],
-            'io_time_s': result['elapsed'],
-            'requests_per_second': (
-                result['completed'] / result['elapsed']
-                if result['elapsed'] > 0 else 0
-            ),
-            'model': model_config['name'],
-            'fsync_mode': fsync_mode,
-            'threads': threads,
-            'replay_scale': replay_scale,
-            **result['stats'],
-        }])
+        result = (
+            result
+            if "result" in locals()
+            else {
+                "completed": 0,
+                "elapsed": 0,
+                "stats": {},
+            }
+        )
+        print_results(
+            [
+                {
+                    "trace_file": Path(trace_path).name,
+                    "total_requests": result["completed"],
+                    "io_time_s": result["elapsed"],
+                    "requests_per_second": (
+                        result["completed"] / result["elapsed"]
+                        if result["elapsed"] > 0
+                        else 0
+                    ),
+                    "model": model_config["name"],
+                    "fsync_mode": fsync_mode,
+                    "threads": threads,
+                    "replay_scale": replay_scale,
+                    **result["stats"],
+                }
+            ]
+        )
         sys.exit(0)
 
     return {
-        'trace_file': Path(trace_path).name,
-        'total_requests': result['completed'],
-        'io_time_s': result['elapsed'],
-        'requests_per_second': (
-            result['completed'] / result['elapsed'] if result['elapsed'] > 0 else 0
+        "trace_file": Path(trace_path).name,
+        "total_requests": result["completed"],
+        "io_time_s": result["elapsed"],
+        "requests_per_second": (
+            result["completed"] / result["elapsed"] if result["elapsed"] > 0 else 0
         ),
-        'model': model_config['name'],
-        'fsync_mode': fsync_mode,
-        'threads': threads,
-        'replay_scale': replay_scale,
-        **result['stats'],
+        "model": model_config["name"],
+        "fsync_mode": fsync_mode,
+        "threads": threads,
+        "replay_scale": replay_scale,
+        **result["stats"],
     }
 
 
@@ -564,23 +639,26 @@ def run_benchmark(trace_path: str, storage_dir: str, model_config: dict,
 # Output Formatting
 # ============================================================================
 
+
 def format_storage_stats(stats: Dict, title: str = "Storage"):
     """Format storage statistics with clear read/write separation"""
-    storage = stats.get('storage', {})
-    read_stats = storage.get('read', {})
-    write_stats = storage.get('write', {})
-    request_wall = stats.get('request_wall_latency', {})
-    request_io = stats.get('request_io_latency', {})
+    storage = stats.get("storage", {})
+    read_stats = storage.get("read", {})
+    write_stats = storage.get("write", {})
+    request_wall = stats.get("request_wall_latency", {})
+    request_io = stats.get("request_io_latency", {})
 
     output = []
     output.append(f"\n[{title}]")
 
     # General info
-    output.append(f"\n[General]")
+    output.append("\n[General]")
     output.append(f"  Model:            {stats.get('model', 'N/A')}")
     output.append(f"  Threads:          {stats.get('threads', 1)}")
-    replay_scale = stats.get('replay_scale', 0)
-    output.append(f"  Fast-forward:     {f'{replay_scale:g}x' if replay_scale else 'unpaced'}")
+    replay_scale = stats.get("replay_scale", 0)
+    output.append(
+        f"  Fast-forward:     {f'{replay_scale:g}x' if replay_scale else 'unpaced'}"
+    )
     output.append(f"  Requests:         {stats.get('total_requests', 0):,}")
     output.append(f"  Tokens:           {stats.get('total_tokens', 0):,}")
     output.append(f"  Total I/O Time:    {stats.get('io_time_s', 0):.3f} s")
@@ -588,48 +666,48 @@ def format_storage_stats(stats: Dict, title: str = "Storage"):
     output.append(f"  Hit Rate:         {stats.get('page_hit_rate', 0):.2%}")
 
     # Request Stats
-    output.append(f"\n[Request Wall Latency]")
+    output.append("\n[Request Wall Latency]")
     output.append(f"  Avg:              {request_wall.get('avg_ms', 0):.3f} ms")
     output.append(f"  P50:              {request_wall.get('p50_ms', 0):.3f} ms")
     output.append(f"  P95:              {request_wall.get('p95_ms', 0):.3f} ms")
     output.append(f"  P99:              {request_wall.get('p99_ms', 0):.3f} ms")
 
-    output.append(f"\n[Request Storage I/O Latency]")
+    output.append("\n[Request Storage I/O Latency]")
     output.append(f"  Avg:              {request_io.get('avg_ms', 0):.3f} ms")
     output.append(f"  P50:              {request_io.get('p50_ms', 0):.3f} ms")
     output.append(f"  P95:              {request_io.get('p95_ms', 0):.3f} ms")
     output.append(f"  P99:              {request_io.get('p99_ms', 0):.3f} ms")
 
     # Read Stats
-    output.append(f"\n[Read Operations]")
+    output.append("\n[Read Operations]")
     output.append(f"  Count:            {read_stats.get('count', 0):,}")
     output.append(f"  Data Volume:      {read_stats.get('mb', 0):.2f} MB")
-    read_time = read_stats.get('time_s', 0)
-    read_mbps = read_stats.get('mb', 0) / read_time if read_time > 0 else 0
+    read_time = read_stats.get("time_s", 0)
+    read_mbps = read_stats.get("mb", 0) / read_time if read_time > 0 else 0
     output.append(f"  Total Time:       {read_time:.3f} s")
     output.append(f"  Bandwidth:        {read_mbps:.2f} MB/s")
-    output.append(f"  Latency:")
+    output.append("  Latency:")
     output.append(f"    Avg:            {read_stats.get('avg_ms', 0):.3f} ms")
     output.append(f"    P50:            {read_stats.get('p50_ms', 0):.3f} ms")
     output.append(f"    P95:            {read_stats.get('p95_ms', 0):.3f} ms")
     output.append(f"    P99:            {read_stats.get('p99_ms', 0):.3f} ms")
 
     # Write Stats
-    output.append(f"\n[Write Operations]")
+    output.append("\n[Write Operations]")
     output.append(f"  Count:            {write_stats.get('count', 0):,}")
     output.append(f"  Data Volume:      {write_stats.get('mb', 0):.2f} MB")
-    write_time = write_stats.get('time_s', 0)
-    write_mbps = write_stats.get('mb', 0) / write_time if write_time > 0 else 0
+    write_time = write_stats.get("time_s", 0)
+    write_mbps = write_stats.get("mb", 0) / write_time if write_time > 0 else 0
     output.append(f"  Total Time:       {write_time:.3f} s")
     output.append(f"  Bandwidth:        {write_mbps:.2f} MB/s")
-    output.append(f"  Latency:")
+    output.append("  Latency:")
     output.append(f"    Avg:            {write_stats.get('avg_ms', 0):.3f} ms")
     output.append(f"    P50:            {write_stats.get('p50_ms', 0):.3f} ms")
     output.append(f"    P95:            {write_stats.get('p95_ms', 0):.3f} ms")
     output.append(f"    P99:            {write_stats.get('p99_ms', 0):.3f} ms")
 
     # Storage Info
-    output.append(f"\n[Storage Info]")
+    output.append("\n[Storage Info]")
     output.append(f"  Max Pages:        {storage.get('max_pages', 0):,}")
     output.append(f"  Written Pages:    {storage.get('written_pages', 0):,}")
     output.append(f"  Sync Count:       {storage.get('sync_count', 0):,}")
@@ -650,43 +728,101 @@ def print_results(results: List[Dict]):
 # CLI Entry Point
 # ============================================================================
 
+
 def main():
     """Main entry point"""
     parser = argparse.ArgumentParser(
-        description='Mooncake KVCache Storage Benchmark',
+        description="Mooncake KVCache Storage Benchmark",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
 
-    parser.add_argument('--trace-dir', type=str, default='../../FAST25-release/traces',
-                       help='Trace files directory')
-    parser.add_argument('--scenario', type=str, choices=['conversation', 'synthetic', 'toolagent', 'all'],
-                       default='toolagent', help='Test scenario')
-    parser.add_argument('--storage-dir', type=str, default='/tmp/mooncake_bench',
-                       help='Storage directory')
-    parser.add_argument('--model', type=str, default='glm5', choices=['glm5', 'kimi-k2.6'],
-                       help='Model preset')
-    parser.add_argument('--page-size-tokens', type=int, default=512,
-                       help='Page size in tokens (default: 512)')
-    parser.add_argument('--max-requests', type=int, default=None,
-                       help='Maximum number of requests')
-    parser.add_argument('--max-pages', type=int, default=2000,
-                       help='Maximum number of pages')
-    parser.add_argument('--fsync-mode', type=str, choices=['batch', 'always', 'end', 'none'],
-                       default='none', help='When to fsync')
-    parser.add_argument('--fsync-batch-size', type=int, default=100,
-                       help='Number of writes between fsync')
-    parser.add_argument('--threads', type=int, default=1,
-                       help='Number of benchmark client worker threads')
-    parser.add_argument('--replay-scales', type=str, default='0',
-                       help='Comma-separated trace fast-forward speeds; 0 means unpaced')
-    parser.add_argument('--progress-interval', type=int, default=100,
-                       help='Print progress every N requests; 0 disables per-request progress')
+    parser.add_argument(
+        "--trace-dir",
+        type=str,
+        default="../../FAST25-release/traces",
+        help="Trace files directory",
+    )
+    parser.add_argument(
+        "--scenario",
+        type=str,
+        choices=["conversation", "synthetic", "toolagent", "all"],
+        default="toolagent",
+        help="Test scenario",
+    )
+    parser.add_argument(
+        "--storage-dir",
+        type=str,
+        default="/tmp/mooncake_bench",
+        help="Storage directory",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="glm5",
+        choices=["glm5", "kimi-k2.6"],
+        help="Model preset",
+    )
+    parser.add_argument(
+        "--page-size-tokens",
+        type=int,
+        default=512,
+        help="Page size in tokens (default: 512)",
+    )
+    parser.add_argument(
+        "--file-mode",
+        type=str,
+        choices=["single", "per-file"],
+        default="single",
+        help="Storage layout: single = one data.bin with slot "
+        "offsets (default); per-file = one file per page. "
+        "Per-file writes open with O_TRUNC and replace the "
+        "whole page file",
+    )
+    parser.add_argument(
+        "--max-requests", type=int, default=None, help="Maximum number of requests"
+    )
+    parser.add_argument(
+        "--max-pages", type=int, default=2000, help="Maximum number of pages"
+    )
+    parser.add_argument(
+        "--fsync-mode",
+        type=str,
+        choices=["batch", "always", "end", "none"],
+        default="none",
+        help="When to fsync. With --file-mode per-file, end does "
+        "zero fsyncs and batch fsyncs only the last file in "
+        "each batch; durability is weaker than single",
+    )
+    parser.add_argument(
+        "--fsync-batch-size",
+        type=int,
+        default=100,
+        help="Number of writes between fsync",
+    )
+    parser.add_argument(
+        "--threads",
+        type=int,
+        default=1,
+        help="Number of benchmark client worker threads",
+    )
+    parser.add_argument(
+        "--replay-scales",
+        type=str,
+        default="0",
+        help="Comma-separated trace fast-forward speeds; 0 means unpaced",
+    )
+    parser.add_argument(
+        "--progress-interval",
+        type=int,
+        default=100,
+        help="Print progress every N requests; 0 disables per-request progress",
+    )
 
     args = parser.parse_args()
     if args.threads < 1:
-        parser.error('--threads must be at least 1')
+        parser.error("--threads must be at least 1")
     if args.progress_interval < 0:
-        parser.error('--progress-interval must be non-negative')
+        parser.error("--progress-interval must be non-negative")
 
     print(f"\n{'='*80}")
     print(f"{'Mooncake KVCache Storage Benchmark':^80}")
@@ -696,16 +832,20 @@ def main():
     print(f"Model: {args.model} ({model_config['num_layers']} layers)")
     replay_scales = parse_csv_floats(args.replay_scales)
     if not replay_scales:
-        parser.error('--replay-scales must include at least one value')
+        parser.error("--replay-scales must include at least one value")
     if any(scale < 0 for scale in replay_scales):
-        parser.error('--replay-scales values must be non-negative')
+        parser.error("--replay-scales values must be non-negative")
 
     # Determine scenarios
-    scenarios = ['conversation', 'synthetic', 'toolagent'] if args.scenario == 'all' else [args.scenario]
+    scenarios = (
+        ["conversation", "synthetic", "toolagent"]
+        if args.scenario == "all"
+        else [args.scenario]
+    )
     trace_files = {
-        'conversation': 'conversation_trace.jsonl',
-        'synthetic': 'synthetic_trace.jsonl',
-        'toolagent': 'toolagent_trace.jsonl'
+        "conversation": "conversation_trace.jsonl",
+        "synthetic": "synthetic_trace.jsonl",
+        "toolagent": "toolagent_trace.jsonl",
     }
 
     # Run benchmarks
@@ -725,11 +865,12 @@ def main():
                     args.max_requests,
                     args.max_pages,
                     args.page_size_tokens,
+                    args.file_mode,
                     args.fsync_mode,
                     args.fsync_batch_size,
                     args.threads,
                     replay_scale,
-                    args.progress_interval
+                    args.progress_interval,
                 )
                 results.append(result)
         else:
@@ -742,5 +883,6 @@ def main():
         print("Error: No trace files were successfully processed.", file=sys.stderr)
         sys.exit(1)
 
-if __name__ == '__main__':
+
+if __name__ == "__main__":
     main()
diff --git a/benchmarks/storage_benchmark_v1/doc/README.md b/benchmarks/storage_benchmark_v1/doc/README.md
index 8b53be660a..642dc87405 100644
--- a/benchmarks/storage_benchmark_v1/doc/README.md
+++ b/benchmarks/storage_benchmark_v1/doc/README.md
@@ -24,9 +24,10 @@ python benchmark.py --scenario conversation \
 | `--storage-dir` | `/tmp/mooncake_bench` | Directory for storage files |
 | `--model` | `glm5` | Model preset: `glm5` or `kimi-k2.6` |
 | `--page-size-tokens` | `512` | Page size in tokens |
+| `--file-mode` | `single` | Storage layout: `single` = one `data.bin` with slot offsets; `per-file` = one file per page. Per-file writes open with `O_TRUNC` and replace the whole page file |
 | `--max-requests` | `None` | Maximum number of requests to process |
 | `--max-pages` | `2000` | Maximum number of pages (creates modulo mapping if trace is larger) |
-| `--fsync-mode` | `none` | When to fsync: `none`, `batch`, `always`, or `end` |
+| `--fsync-mode` | `none` | When to fsync: `none`, `batch`, `always`, or `end`. With `--file-mode per-file`, `end`/`batch` are weaker than in `single` (see File Mode) |
 | `--fsync-batch-size` | `100` | Number of writes between fsync in batch mode |
 | `--threads` | `1` | Number of benchmark client worker threads |
 | `--replay-scales` | `0` | Comma-separated trace fast-forward speeds; `0` means unpaced |
@@ -58,11 +59,46 @@ python benchmark.py --scenario toolagent \
 ```
 
 With `--threads > 1`, each benchmark client thread uses an independent storage
-file under `thread_N/data.bin`, similar to running multiple clients at the same
+directory under `thread_N/`, similar to running multiple clients at the same
 time. Final results aggregate the per-thread counters and latency samples. For
 strict single-client trace-order read/write and hit-rate accounting, use
 `--threads 1`.
 
+### File Mode
+
+`--file-mode` selects the on-disk layout:
+
+- `single` (default): one preallocated `data.bin`. Each page is a slot at
+  `physical_page_id * page_size`. Partial writes keep the rest of the file.
+- `per-file`: one `page_<id>.bin` per page. Each operation opens, reads or
+  writes, then closes that file. A write opens with `O_WRONLY | O_CREAT |
+  O_TRUNC`, so it replaces the entire page file and does not preserve earlier
+  bytes in that file.
+
+With `--threads > 1`, each thread still uses its own `thread_N/` directory.
+In `single` mode that directory contains `data.bin`; in `per-file` mode it
+contains `page_*.bin`.
+
+Per-file mode does not delete leftover `page_*.bin` files or `thread_N/`
+directories between runs. A re-run with a smaller `--max-pages` or fewer
+`--threads` can leave orphaned files. Within a run this is harmless
+(`_written_pages` starts empty and writes use `O_TRUNC`); remove them
+manually from `--storage-dir` if disk space matters.
+
+`--fsync-mode none` and `always` are comparable across file modes. Combined
+with `--file-mode per-file`, `end` and `batch` are weaker than in `single`
+and should not be compared as the same durability cost:
+
+- `end`: `write()` never fsyncs, and `close()` only fsyncs the persistent
+  `data.bin` fd, which per-file never opens. Expected result: zero fsyncs,
+  write latency and `Sync Count` look like `none`.
+- `batch`: `_pending_syncs` counts across files, but `os.fsync(fd)` runs
+  only on the current per-op fd. Expected result: one file per batch is
+  synced (the Nth write); the other N-1 files are already closed, and the
+  trailing partial batch is never flushed. `Sync Count` still increments,
+  but most writes are not durable, so write latency is much closer to
+  `none` than to `single` + `batch`.
+
 ## Output Format
 
 ### Progress Output
diff --git a/benchmarks/storage_benchmark_v1/storage/disk.py b/benchmarks/storage_benchmark_v1/storage/disk.py
index b54de98a64..388d45ddd1 100644
--- a/benchmarks/storage_benchmark_v1/storage/disk.py
+++ b/benchmarks/storage_benchmark_v1/storage/disk.py
@@ -15,8 +15,9 @@
 def calc_percentiles(data):
     """Calculate latency percentiles"""
     if not data:
-        return {'avg_ms': 0, 'p50_ms': 0, 'p95_ms': 0, 'p99_ms': 0}
+        return {"avg_ms": 0, "p50_ms": 0, "p95_ms": 0, "p99_ms": 0}
     import statistics
+
     sorted_data = sorted(data)
 
     def get_percentile(p):
@@ -29,10 +30,10 @@ def get_percentile(p):
         return sorted_data[lower] * (1.0 - weight) + sorted_data[upper] * weight
 
     return {
-        'avg_ms': statistics.mean(data),
-        'p50_ms': get_percentile(50),
-        'p95_ms': get_percentile(95),
-        'p99_ms': get_percentile(99),
+        "avg_ms": statistics.mean(data),
+        "p50_ms": get_percentile(50),
+        "p95_ms": get_percentile(95),
+        "p99_ms": get_percentile(99),
     }
 
 
@@ -51,15 +52,26 @@ class DiskHashTable(Storage):
     This allows simulating large traces with limited storage.
     """
 
-    def __init__(self, storage_dir: str, page_size: int,
-                 max_pages: int = 100000,
-                 fsync_mode: str = 'batch', fsync_batch_size: int = 100):
+    def __init__(
+        self,
+        storage_dir: str,
+        page_size: int,
+        max_pages: int = 100000,
+        file_mode: str = "single",
+        fsync_mode: str = "batch",
+        fsync_batch_size: int = 100,
+    ):
         """Initialize disk hash table
 
         Args:
             storage_dir: Storage directory
             page_size: Size of each entry (page) in bytes
             max_pages: Maximum number of entries (creates circular mapping if trace is larger)
+            file_mode: 'single' = one big data.bin with slot offsets (default);
+                       'per-file' = one file per page (open/read-write/close per op).
+                       Per-file writes use O_TRUNC, so a partial-page
+                       (offset_in_page > 0 or length < page_size) write
+                       replaces the whole file and discards the rest of the page.
             fsync_mode: When to fsync ('batch', 'always', 'end', 'none')
             fsync_batch_size: Writes between fsync
         """
@@ -67,25 +79,27 @@ def __init__(self, storage_dir: str, page_size: int,
         self.page_size = page_size
         self.max_pages = max_pages
         self.max_page_id = max_pages - 1
+        self.file_mode = file_mode
         self.fsync_mode = fsync_mode
         self.fsync_batch_size = fsync_batch_size
         self.storage_dir.mkdir(parents=True, exist_ok=True)
         self.storage_file = self.storage_dir / "data.bin"
-        self._allocate_file()
+        if self.file_mode == "single":
+            self._allocate_file()
         self.fd = None
         self._buffer = os.urandom(page_size)
         self.stats = {
-            'read_count': 0,
-            'write_count': 0,
-            'read_bytes': 0,
-            'write_bytes': 0,
-            'read_latencies_ms': [],
-            'write_latencies_ms': [],
-            'read_time_s': 0.0,
-            'write_time_s': 0.0,
-            'sync_count': 0,
-            'hit': 0,
-            'miss': 0,
+            "read_count": 0,
+            "write_count": 0,
+            "read_bytes": 0,
+            "write_bytes": 0,
+            "read_latencies_ms": [],
+            "write_latencies_ms": [],
+            "read_time_s": 0.0,
+            "write_time_s": 0.0,
+            "sync_count": 0,
+            "hit": 0,
+            "miss": 0,
         }
         self._pending_syncs = 0
         self._written_pages: set = set()
@@ -95,30 +109,39 @@ def _allocate_file(self):
         file_size = self.max_pages * self.page_size
         if not self.storage_file.exists():
             print(f"  [Storage] Creating file: {self.storage_file}")
-            print(f"  [Storage] Requested size: {file_size / (1024**3):.2f} GB ({self.max_pages:,} pages × {self.page_size} bytes = {file_size:,} bytes)")
+            print(
+                f"  [Storage] Requested size: {file_size / (1024**3):.2f} GB ({self.max_pages:,} pages × {self.page_size} bytes = {file_size:,} bytes)"
+            )
             # Use fallocate for efficient preallocation (Linux)
             fd = os.open(self.storage_file, os.O_RDWR | os.O_CREAT | os.O_TRUNC, 0o644)
             try:
                 # Try fallocate first (Linux specific, much faster)
                 try:
                     import fcntl
+
                     fcntl.fallocate(fd, 0, file_size)
                     method = "fallocate"
                 except (ImportError, AttributeError, OSError):
                     # Fallback to seek+write method
                     os.lseek(fd, file_size - 1, os.SEEK_SET)
-                    os.write(fd, b'\0')
+                    os.write(fd, b"\0")
                     os.fsync(fd)
                     method = "seek+write"
             finally:
                 os.close(fd)
-            actual_size = self.storage_file.stat().st_size if self.storage_file.exists() else 0
-            print(f"  [Storage] Pre-allocated {actual_size / (1024**3):.2f} GB using {method}")
+            actual_size = (
+                self.storage_file.stat().st_size if self.storage_file.exists() else 0
+            )
+            print(
+                f"  [Storage] Pre-allocated {actual_size / (1024**3):.2f} GB using {method}"
+            )
         else:
             actual_size = self.storage_file.stat().st_size
             actual_pages = actual_size // self.page_size
             print(f"  [Storage] Reusing existing file: {self.storage_file}")
-            print(f"  [Storage] Current file size: {actual_size / (1024**3):.2f} GB ({actual_pages:,} pages × {self.page_size} bytes = {actual_size:,} bytes)")
+            print(
+                f"  [Storage] Current file size: {actual_size / (1024**3):.2f} GB ({actual_pages:,} pages × {self.page_size} bytes = {actual_size:,} bytes)"
+            )
 
     def _get_fd(self):
         if self.fd is None:
@@ -127,7 +150,9 @@ def _get_fd(self):
             if self.storage_file.exists():
                 actual_size = self.storage_file.stat().st_size
                 actual_pages = actual_size // self.page_size
-                print(f"  [Storage] File size: {actual_size / (1024**3):.2f} GB ({actual_pages:,} pages × {self.page_size} bytes = {actual_size:,} bytes)")
+                print(
+                    f"  [Storage] File size: {actual_size / (1024**3):.2f} GB ({actual_pages:,} pages × {self.page_size} bytes = {actual_size:,} bytes)"
+                )
         return self.fd
 
     # ========================================================================
@@ -147,6 +172,22 @@ def _map_page_id(self, page_id: int) -> int:
         """
         return page_id % self.max_pages
 
+    def _open_page(self, page_id: int, write: bool):
+        """Resolve a page access to (fd, base_offset, owned).
+
+        single: reuse the persistent data.bin fd, base = physical * page_size.
+        per-file: open page_<physical>.bin for this op, base = 0, owned = True
+                  (caller must close fd when done). Writes use O_TRUNC, so a
+                  partial-page(offset_in_page > 0 or length < page_size)
+                  write replaces the whole file.
+        """
+        physical_page_id = self._map_page_id(page_id)
+        if self.file_mode == "per-file":
+            path = self.storage_dir / f"page_{physical_page_id}.bin"
+            flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC if write else os.O_RDONLY
+            return os.open(str(path), flags, 0o644), 0, True
+        return self._get_fd(), physical_page_id * self.page_size, False
+
     def read(self, page_id: int, offset_in_page: int = 0, length: int = None) -> float:
         """Read entry from disk
 
@@ -163,29 +204,40 @@ def read(self, page_id: int, offset_in_page: int = 0, length: int = None) -> flo
 
         # Validate parameters
         if offset_in_page < 0 or offset_in_page >= self.page_size:
-            raise ValueError(f"offset_in_page {offset_in_page} out of range [0, {self.page_size})")
+            raise ValueError(
+                f"offset_in_page {offset_in_page} out of range [0, {self.page_size})"
+            )
         if length <= 0 or offset_in_page + length > self.page_size:
-            raise ValueError(f"length {length} invalid with offset_in_page {offset_in_page} (page_size={self.page_size})")
+            raise ValueError(
+                f"length {length} invalid with offset_in_page {offset_in_page} (page_size={self.page_size})"
+            )
 
-        # Map to physical page_id and calculate offset
-        physical_page_id = self._map_page_id(page_id)
-        offset = physical_page_id * self.page_size + offset_in_page
         start = time.perf_counter()
-
+        fd = None
+        owned = False
         try:
-            fd = self._get_fd()
-            os.pread(fd, length, offset)
+            fd, base, owned = self._open_page(page_id, write=False)
+            os.pread(fd, length, base + offset_in_page)
+            if owned:
+                close_fd, fd = fd, None
+                os.close(close_fd)
 
             latency = (time.perf_counter() - start) * 1000.0
-            self.stats['read_count'] += 1
-            self.stats['read_bytes'] += length
-            self.stats['read_latencies_ms'].append(latency)
-            self.stats['read_time_s'] += latency / 1000.0
-            self.stats['hit'] += 1
+            self.stats["read_count"] += 1
+            self.stats["read_bytes"] += length
+            self.stats["read_latencies_ms"].append(latency)
+            self.stats["read_time_s"] += latency / 1000.0
+            self.stats["hit"] += 1
             return latency
         except OSError as e:
-            print(f"Read error (page_id={page_id}, physical_page_id={physical_page_id}): {e}")
-            return 0.0
+            print(f"Read error (page_id={page_id}): {e}")
+            return None
+        finally:
+            if owned and fd is not None:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
 
     def write(self, page_id: int, offset_in_page: int = 0, length: int = None) -> float:
         """Write entry to disk
@@ -203,47 +255,61 @@ def write(self, page_id: int, offset_in_page: int = 0, length: int = None) -> fl
 
         # Validate parameters
         if offset_in_page < 0 or offset_in_page >= self.page_size:
-            raise ValueError(f"offset_in_page {offset_in_page} out of range [0, {self.page_size})")
+            raise ValueError(
+                f"offset_in_page {offset_in_page} out of range [0, {self.page_size})"
+            )
         if length <= 0 or offset_in_page + length > self.page_size:
-            raise ValueError(f"length {length} invalid with offset_in_page {offset_in_page} (page_size={self.page_size})")
+            raise ValueError(
+                f"length {length} invalid with offset_in_page {offset_in_page} (page_size={self.page_size})"
+            )
 
-        # Map to physical page_id and calculate offset
-        physical_page_id = self._map_page_id(page_id)
-        offset = physical_page_id * self.page_size + offset_in_page
         start = time.perf_counter()
-
+        fd = None
+        owned = False
         try:
-            fd = self._get_fd()
+            fd, base, owned = self._open_page(page_id, write=True)
             # Use corresponding portion of buffer
-            os.pwrite(fd, self._buffer[:length], offset)
+            os.pwrite(fd, self._buffer[:length], base + offset_in_page)
             write_done = time.perf_counter()
 
             # Fsync
-            if self.fsync_mode == 'always':
+            if self.fsync_mode == "always":
                 os.fsync(fd)
-                self.stats['sync_count'] += 1
+                self.stats["sync_count"] += 1
                 self._pending_syncs = 0
-                latency = (time.perf_counter() - start) * 1000.0
-            elif self.fsync_mode == 'batch':
+            elif self.fsync_mode == "batch":
                 self._pending_syncs += 1
                 if self._pending_syncs >= self.fsync_batch_size:
                     os.fsync(fd)
-                    self.stats['sync_count'] += 1
+                    self.stats["sync_count"] += 1
                     self._pending_syncs = 0
-                latency = (write_done - start) * 1000.0
+            if owned:
+                close_fd, fd = fd, None
+                os.close(close_fd)
+
+            if self.fsync_mode == "always" or owned:
+                latency = (time.perf_counter() - start) * 1000.0
             else:
                 latency = (write_done - start) * 1000.0
 
             self._written_pages.add(page_id)
-            self.stats['write_count'] += 1
-            self.stats['write_bytes'] += length
-            self.stats['write_latencies_ms'].append(latency)
-            self.stats['write_time_s'] += latency / 1000.0
-            self.stats['miss'] += 1
+            self.stats["write_count"] += 1
+            self.stats["write_bytes"] += length
+            self.stats["write_latencies_ms"].append(latency)
+            self.stats["write_time_s"] += latency / 1000.0
+            self.stats["miss"] += 1
             return latency
         except OSError as e:
-            print(f"Write error (page_id={page_id}, offset_in_page={offset_in_page}, length={length}): {e}")
-            return 0.0
+            print(
+                f"Write error (page_id={page_id}, offset_in_page={offset_in_page}, length={length}): {e}"
+            )
+            return None
+        finally:
+            if owned and fd is not None:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
 
     # ========================================================================
     # Storage interface methods
@@ -278,30 +344,30 @@ def get_stats(self) -> Dict[str, Any]:
 
         def calc_stats(latencies):
             if not latencies:
-                return {'avg_ms': 0, 'p50_ms': 0, 'p95_ms': 0, 'p99_ms': 0}
+                return {"avg_ms": 0, "p50_ms": 0, "p95_ms": 0, "p99_ms": 0}
             return {
-                'avg_ms': statistics.mean(latencies),
+                "avg_ms": statistics.mean(latencies),
                 **calc_percentiles(latencies),
             }
 
         return {
-            'read': {
-                'count': self.stats['read_count'],
-                'mb': self.stats['read_bytes'] / 1024 / 1024,
-                'time_s': self.stats['read_time_s'],
-                **calc_stats(self.stats['read_latencies_ms'])
+            "read": {
+                "count": self.stats["read_count"],
+                "mb": self.stats["read_bytes"] / 1024 / 1024,
+                "time_s": self.stats["read_time_s"],
+                **calc_stats(self.stats["read_latencies_ms"]),
             },
-            'write': {
-                'count': self.stats['write_count'],
-                'mb': self.stats['write_bytes'] / 1024 / 1024,
-                'time_s': self.stats['write_time_s'],
-                **calc_stats(self.stats['write_latencies_ms'])
+            "write": {
+                "count": self.stats["write_count"],
+                "mb": self.stats["write_bytes"] / 1024 / 1024,
+                "time_s": self.stats["write_time_s"],
+                **calc_stats(self.stats["write_latencies_ms"]),
             },
-            'sync_count': self.stats['sync_count'],
-            'max_pages': self.max_pages,
-            'written_pages': len(self._written_pages),
-            'page_hits': self.stats['hit'],
-            'page_misses': self.stats['miss'],
+            "sync_count": self.stats["sync_count"],
+            "max_pages": self.max_pages,
+            "written_pages": len(self._written_pages),
+            "page_hits": self.stats["hit"],
+            "page_misses": self.stats["miss"],
         }
 
     # ========================================================================
@@ -310,11 +376,11 @@ def calc_stats(latencies):
 
     def close(self, force_sync: bool = True):
         """Close file"""
-        if force_sync and self.fsync_mode in ['end', 'batch']:
+        if force_sync and self.fsync_mode in ["end", "batch"]:
             if self.fd is not None:
                 try:
                     os.fsync(self.fd)
-                    self.stats['sync_count'] += 1
+                    self.stats["sync_count"] += 1
                 except OSError:
                     pass
 
diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake
new file mode 100644
index 0000000000..a9ccc3e787
--- /dev/null
+++ b/cmake/Dependencies.cmake
@@ -0,0 +1,74 @@
+# Build entry points own these targets and call each provider at most once.
+# Consumer directories only link the resulting Mooncake::* targets.
+
+function(mooncake_provide_zstd)
+  find_path(MOONCAKE_ZSTD_INCLUDE_DIR zstd.h)
+  find_library(MOONCAKE_ZSTD_LIBRARY zstd)
+  if(NOT MOONCAKE_ZSTD_INCLUDE_DIR OR NOT MOONCAKE_ZSTD_LIBRARY)
+    message(FATAL_ERROR "zstd development files not found")
+  endif()
+  add_library(Mooncake::zstd UNKNOWN IMPORTED)
+  set_target_properties(
+    Mooncake::zstd
+    PROPERTIES IMPORTED_LOCATION "${MOONCAKE_ZSTD_LIBRARY}"
+               INTERFACE_INCLUDE_DIRECTORIES "${MOONCAKE_ZSTD_INCLUDE_DIR}")
+endfunction()
+
+function(mooncake_provide_xxhash)
+  find_path(MOONCAKE_XXHASH_INCLUDE_DIR xxhash.h)
+  find_library(MOONCAKE_XXHASH_LIBRARY NAMES xxhash libxxhash)
+  if(NOT MOONCAKE_XXHASH_INCLUDE_DIR OR NOT MOONCAKE_XXHASH_LIBRARY)
+    message(FATAL_ERROR "xxHash development files not found")
+  endif()
+  add_library(Mooncake::xxhash UNKNOWN IMPORTED)
+  set_target_properties(
+    Mooncake::xxhash
+    PROPERTIES IMPORTED_LOCATION "${MOONCAKE_XXHASH_LIBRARY}"
+               INTERFACE_INCLUDE_DIRECTORIES "${MOONCAKE_XXHASH_INCLUDE_DIR}")
+endfunction()
+
+function(mooncake_provide_liburing)
+  find_path(MOONCAKE_LIBURING_INCLUDE_DIR liburing.h)
+  find_library(MOONCAKE_LIBURING_LIBRARY uring)
+  if(MOONCAKE_LIBURING_INCLUDE_DIR AND MOONCAKE_LIBURING_LIBRARY)
+    add_library(Mooncake::liburing UNKNOWN IMPORTED)
+    set_target_properties(
+      Mooncake::liburing
+      PROPERTIES IMPORTED_LOCATION "${MOONCAKE_LIBURING_LIBRARY}"
+                 INTERFACE_INCLUDE_DIRECTORIES
+                 "${MOONCAKE_LIBURING_INCLUDE_DIR}")
+  endif()
+endfunction()
+
+function(mooncake_provide_libzmq)
+  find_path(MOONCAKE_LIBZMQ_INCLUDE_DIR zmq.h)
+  find_library(MOONCAKE_LIBZMQ_LIBRARY NAMES zmq libzmq)
+  if(NOT MOONCAKE_LIBZMQ_INCLUDE_DIR OR NOT MOONCAKE_LIBZMQ_LIBRARY)
+    message(FATAL_ERROR "libzmq development files not found")
+  endif()
+  add_library(Mooncake::libzmq UNKNOWN IMPORTED)
+  set_target_properties(
+    Mooncake::libzmq
+    PROPERTIES IMPORTED_LOCATION "${MOONCAKE_LIBZMQ_LIBRARY}"
+               INTERFACE_INCLUDE_DIRECTORIES "${MOONCAKE_LIBZMQ_INCLUDE_DIR}")
+endfunction()
+
+function(mooncake_provide_hiredis)
+  cmake_parse_arguments(ARG "REQUIRED" "" "" ${ARGN})
+  find_path(MOONCAKE_HIREDIS_INCLUDE_DIR hiredis/hiredis.h)
+  find_library(MOONCAKE_HIREDIS_LIBRARY hiredis)
+  if(ARG_REQUIRED)
+    if(NOT MOONCAKE_HIREDIS_INCLUDE_DIR OR NOT MOONCAKE_HIREDIS_LIBRARY)
+      message(FATAL_ERROR "hiredis development files not found")
+    endif()
+  endif()
+
+  if(MOONCAKE_HIREDIS_INCLUDE_DIR AND MOONCAKE_HIREDIS_LIBRARY)
+    add_library(Mooncake::hiredis UNKNOWN IMPORTED)
+    set_target_properties(
+      Mooncake::hiredis
+      PROPERTIES IMPORTED_LOCATION "${MOONCAKE_HIREDIS_LIBRARY}"
+                 INTERFACE_INCLUDE_DIRECTORIES
+                 "${MOONCAKE_HIREDIS_INCLUDE_DIR}")
+  endif()
+endfunction()
diff --git a/dependencies.sh b/dependencies.sh
index c1e42a772c..d218894c53 100755
--- a/dependencies.sh
+++ b/dependencies.sh
@@ -49,6 +49,19 @@ check_success() {
     fi
 }
 
+# Detect ScaleFabric SHCA (shca-tools).
+has_shca_tools() {
+    if command -v dpkg-query >/dev/null 2>&1; then
+        dpkg-query -W -f='${Status}' shca-tools 2>/dev/null | grep -q "install ok installed"
+        return $?
+    fi
+    if command -v rpm >/dev/null 2>&1; then
+        rpm -q shca-tools >/dev/null 2>&1
+        return $?
+    fi
+    return 1
+}
+
 read_os_release_value() {
     local key="$1"
     awk -F= -v key="$key" '
@@ -72,7 +85,7 @@ detect_os() {
     elif [ -f /etc/redhat-release ]; then
         OS="centos"
     else
-        print_error "Cannot detect OS. Supported OS: Ubuntu, Debian, CentOS, RHEL, Rocky, AlmaLinux, EulerOS, and openEuler."
+        print_error "Cannot detect OS. Supported OS: Ubuntu, Debian, CentOS, RHEL, Rocky, AlmaLinux, EulerOS, openEuler, and Kylin."
     fi
 
     echo -e "${GREEN}Detected OS: $OS ${OS_VERSION:-unknown}${NC}"
@@ -110,7 +123,7 @@ echo -e "${YELLOW}Mooncake Dependencies Installer${NC}"
 echo -e "This script will install all required dependencies for Mooncake."
 echo -e "The following components will be installed:"
 echo -e "  - System packages (build tools, libraries)"
-echo -e "  - Git submodules (including pybind11 and yalantinglibs)"
+echo -e "  - Git submodules (pybind11)"
 echo -e "  - Go $GOVER"
 if [ "$INSTALL_SPDK" = true ]; then
     echo -e "  - SPDK (for NVMe-oF support)"
@@ -135,7 +148,7 @@ print_section "Updating package lists"
 if [ "$OS" = "ubuntu" ] || [ "$OS" = "debian" ]; then
     apt-get update
     check_success "Failed to update package lists"
-elif [ "$OS" = "centos" ] || [ "$OS" = "rhel" ] || [ "$OS" = "rocky" ] || [ "$OS" = "almalinux" ] || [ "$OS" = "euleros" ] || [ "$OS" = "openeuler" ]; then
+elif [ "$OS" = "centos" ] || [ "$OS" = "rhel" ] || [ "$OS" = "rocky" ] || [ "$OS" = "almalinux" ] || [ "$OS" = "euleros" ] || [ "$OS" = "openeuler" ] || [ "$OS" = "kylin" ]; then
     yum install -y dnf-plugins-core epel-release || true
     yum config-manager --set-enabled powertools || yum config-manager --set-enabled crb || true
     yum clean all
@@ -183,6 +196,15 @@ if [ "$OS" = "ubuntu" ] || [ "$OS" = "debian" ]; then
                      libc6-dev \
                      libc-bin"
 
+    # ScaleFabric SHCA (shca-tools) ships its own libibverbs headers/libs; installing
+    # libibverbs-dev conflicts with it. libboost-all-dev pulls OpenMPI/libfabric,
+    # which also depend on distro ibverbs and fail on SHCA systems.
+    if has_shca_tools; then
+        SYSTEM_PACKAGES=$(echo $SYSTEM_PACKAGES | sed 's/libibverbs-dev//g')
+        SYSTEM_PACKAGES=$(echo $SYSTEM_PACKAGES | sed "s/libboost-all-dev/libboost-dev/g")
+        echo -e "${GREEN}shca-tools package detected. Adjusting system packages accordingly; build with -DUSE_SHCA=ON to enable SHCA support.${NC}"
+    fi
+
     apt-get install -y $SYSTEM_PACKAGES
     check_success "Failed to install system packages"
 
@@ -208,6 +230,7 @@ elif [ "$OS" = "centos" ] || [ "$OS" = "rhel" ] || [ "$OS" = "rocky" ] || [ "$OS
                      liburing-devel \
                      jemalloc-devel \
                      msgpack-devel \
+                     zeromq-devel \
                      libzstd-devel \
                      pkgconf-pkg-config \
                      elfutils-libelf-devel \
@@ -215,8 +238,68 @@ elif [ "$OS" = "centos" ] || [ "$OS" = "rhel" ] || [ "$OS" = "rocky" ] || [ "$OS
                      xxhash-devel \
                      libbsd-devel"
 
+    # Same SHCA conflict on RHEL-family: skip rdma-core-devel when shca-tools is present.
+    if has_shca_tools; then
+        SYSTEM_PACKAGES=$(echo $SYSTEM_PACKAGES | sed 's/rdma-core-devel//g')
+        echo -e "${GREEN}shca-tools package detected. Skipping rdma-core-devel (provided by shca-tools).${NC}"
+    fi
+
     yum install -y $SYSTEM_PACKAGES
     check_success "Failed to install system packages"
+
+elif [ "$OS" = "kylin" ]; then
+    SYSTEM_PACKAGES="@development \
+                     cmake \
+                     ninja-build \
+                     git \
+                     wget \
+                     rdma-core-devel \
+                     glog-devel \
+                     gflags-devel \
+                     jsoncpp-devel \
+                     libunwind-devel \
+                     numactl-devel \
+                     python3-devel \
+                     boost-devel \
+                     openssl-devel \
+                     protobuf-devel \
+                     yaml-cpp-devel \
+                     libcurl-devel \
+                     hiredis-devel \
+                     liburing-devel \
+                     jemalloc-devel \
+                     msgpack-devel \
+                     libzstd-devel \
+                     pkgconf-pkg-config \
+                     elfutils-libelf-devel \
+                     patchelf  \
+                     xxhash-devel \
+                     libbsd-devel"
+
+    if [ -z "${KYLIN_EPKL_URL:-}" ]; then
+        KYLIN_NKVERS_OUTPUT=""
+        if command -v nkvers >/dev/null 2>&1; then
+            KYLIN_NKVERS_OUTPUT=$(nkvers 2>/dev/null)
+        fi
+
+        KYLIN_VERSION=${KYLIN_VERSION:-$(printf '%s\n' "$KYLIN_NKVERS_OUTPUT" | sed -nE 's/.*release[[:space:]]+(V[0-9]+).*/\1/p' | head -n 1)}
+        KYLIN_VERSION=${KYLIN_VERSION:-$OS_VERSION}
+        case "$KYLIN_VERSION" in
+            V*) ;;
+            [0-9]*) KYLIN_VERSION="V${KYLIN_VERSION}" ;;
+        esac
+
+        KYLIN_EPKL_RELEASE=${KYLIN_EPKL_RELEASE:-$(printf '%s\n' "$KYLIN_NKVERS_OUTPUT" | sed -nE 's/.*release[[:space:]]+V[0-9]+[[:space:]]+([0-9]{4})\/.*/\1/p' | head -n 1)}
+        if [ -z "$KYLIN_VERSION" ] || [ -z "$KYLIN_EPKL_RELEASE" ]; then
+            print_error "Cannot detect Kylin release. Set KYLIN_EPKL_URL or KYLIN_EPKL_RELEASE explicitly."
+        fi
+
+        KYLIN_EPKL_URL="https://eps-server.openkylin.top/NS/${KYLIN_VERSION}/${KYLIN_EPKL_RELEASE}/EPKL/main/$(uname -m)/"
+    fi
+    dnf --repofrompath="kylin-epkl,$KYLIN_EPKL_URL" \
+        --setopt=kylin-epkl.gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-kylin \
+        --enablerepo=kylin-epkl install -y $SYSTEM_PACKAGES
+    check_success "Failed to install system packages"
 else
     print_error "Unsupported OS: $OS"
 fi
@@ -244,31 +327,6 @@ else
     exit 1
 fi
 
-# Build and install yalantinglibs from submodule
-print_section "Installing yalantinglibs"
-cd "${REPO_ROOT}/extern/yalantinglibs"
-check_success "Failed to change to yalantinglibs submodule directory"
-
-mkdir -p build
-check_success "Failed to create build directory"
-cd build
-check_success "Failed to change to build directory"
-
-echo "Configuring yalantinglibs..."
-cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-check_success "Failed to configure yalantinglibs"
-
-echo "Building yalantinglibs (using $(nproc) cores)..."
-cmake --build . -j$(nproc)
-check_success "Failed to build yalantinglibs"
-
-echo "Installing yalantinglibs..."
-cmake --install .
-check_success "Failed to install yalantinglibs"
-
-print_success "yalantinglibs installed successfully"
-cd "${REPO_ROOT}"
-
 print_section "Verifying essential build tools"
 
 # Verify getconf and ldd (required for glibc version detection in build_wheel.sh)
@@ -373,6 +431,11 @@ fi
 if [ "$INSTALL_SPDK" = true ]; then
     print_section "Installing SPDK"
 
+    if [ "$OS" = "ubuntu" ] || [ "$OS" = "debian" ]; then
+        apt-get install -y libelf-dev
+        check_success "Failed to install NoF dependencies"
+    fi
+
     cd "${REPO_ROOT}/extern"
     check_success "Failed to change to extern directory"
 
@@ -403,8 +466,8 @@ if [ "$INSTALL_SPDK" = true ]; then
 
     # Install SPDK dependencies
     echo "Installing SPDK dependencies..."
-    ./scripts/pkgdep.sh
-    check_success "Failed to install SPDK dependencies"
+    ./scripts/pkgdep.sh --rdma
+    check_success "Failed to install SPDK RDMA dependencies"
 
     # Configure SPDK with RDMA support
     echo "Configuring SPDK with RDMA support..."
@@ -440,7 +503,6 @@ print_section "Installation Complete"
 echo -e "${GREEN}All dependencies have been successfully installed!${NC}"
 echo -e "The following components were installed:"
 echo -e "  ${GREEN}✓${NC} System packages"
-echo -e "  ${GREEN}✓${NC} yalantinglibs"
 echo -e "  ${GREEN}✓${NC} Git submodules"
 echo -e "  ${GREEN}✓${NC} Go $GOVER"
 if [ "$INSTALL_SPDK" = true ]; then
diff --git a/docker/mooncake.Dockerfile b/docker/mooncake.Dockerfile
index c0a9c8d760..ddebfa48dd 100644
--- a/docker/mooncake.Dockerfile
+++ b/docker/mooncake.Dockerfile
@@ -15,8 +15,8 @@ ENV DEBIAN_FRONTEND=noninteractive \
 ARG PYTHON_VERSION=3.10
 ARG PYPA_INDEX_URL=https://bootstrap.pypa.io
 ARG CMAKE_BUILD_TYPE=Release
-ARG EP_TORCH_VERSIONS="2.13.0"
-ARG TORCH_CUDA_ARCH_LIST="8.0;9.0"
+ARG EP_TORCH_VERSIONS="2.14.0"
+ARG TORCH_CUDA_ARCH_LIST=""
 # CI can opt in to removing /workspace/build from the builder layer.
 ARG CLEAN_BUILD_ARTIFACTS=0
 
@@ -49,7 +49,7 @@ RUN apt-get update && \
 WORKDIR /workspace
 COPY . /workspace
 
-# Install Mooncake dependencies (yalantinglibs, Go, etc.)
+# Install Mooncake dependencies (submodules, Go, etc.)
 RUN bash dependencies.sh -y
 
 # Configure and build the wheel in one layer, then remove build/ only after
diff --git a/docker/musa.Dockerfile b/docker/musa.Dockerfile
index d33f65d263..1aff6ce363 100644
--- a/docker/musa.Dockerfile
+++ b/docker/musa.Dockerfile
@@ -32,7 +32,7 @@ ENV PYTHON_VERSION=${PYTHON_VERSION} \
 WORKDIR /workspace
 COPY . /workspace
 
-# Install Mooncake dependencies (submodules, yalantinglibs, Go, etc.)
+# Install Mooncake dependencies (submodules, Go, etc.)
 RUN bash dependencies.sh -y
 
 # Configure & build Mooncake
diff --git a/docker/xpu.Dockerfile b/docker/xpu.Dockerfile
new file mode 100644
index 0000000000..24dfc50e2e
--- /dev/null
+++ b/docker/xpu.Dockerfile
@@ -0,0 +1,87 @@
+# syntax=docker/dockerfile:1.7
+
+###############################################################################
+# Mooncake Intel XPU (oneAPI SYCL) development / build image.
+#
+# USE_XPU is a native, direct-link SYCL build: the XPU platform sources include
+# <sycl/sycl.hpp> and link libsycl directly, so the whole Transfer Engine build
+# must use the Intel DPC++ compiler (icpx).
+#
+# Base image: intel/pytorch:xpu. It already ships the Intel GPU runtime
+# (level-zero / libze_loader, the OpenCL ICD, and the graphics compute runtime)
+# plus a torch build with XPU support, but -- like vLLM's Dockerfile.xpu, which
+# only consumes prebuilt torch-xpu wheels -- it does NOT include a SYCL
+# compiler. We add one via Intel's oneAPI apt repo
+# (intel-oneapi-compiler-dpcpp-cpp -> icpx). The result is a single image that
+# can BUILD the native XPU platform *and* run it against a real Intel GPU (or
+# fall back to the OpenCL CPU device for tent_xpu_platform_test on a GPU-less
+# host), with torch available for XPU integration work.
+#
+# Build:
+#   docker build -f docker/xpu.Dockerfile -t mooncake-xpu:dev .
+# Run the XPU platform test inside the image:
+#   docker run --rm --device /dev/dri mooncake-xpu:dev \
+#     bash -lc '. /opt/intel/oneapi/setvars.sh >/dev/null && \
+#               ctest --test-dir build-xpu -R tent_xpu_platform_test --output-on-failure'
+###############################################################################
+
+ARG BASE_IMAGE=intel/pytorch:xpu-2.13.0-ubuntu24.04-20260907
+
+FROM ${BASE_IMAGE}
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PATH="/usr/local/go/bin:${PATH}"
+
+ARG CMAKE_BUILD_TYPE=RelWithDebInfo
+# Pin the DPC++ compiler version to keep image builds reproducible.
+ARG DPCPP_VERSION=2026.1
+
+# Add Intel's oneAPI apt repository (the base image only carries the GPU
+# *runtime* repo, intel-gpu-*, not the compiler), then install the DPC++
+# compiler (icpx) plus the build utilities Mooncake needs. The base image
+# provides cmake but not ninja/git/RDMA dev headers.
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl gpg && \
+    curl -fsSL https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
+        | gpg --dearmor -o /usr/share/keyrings/oneapi-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main" \
+        > /etc/apt/sources.list.d/oneAPI.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+        intel-oneapi-compiler-dpcpp-cpp-${DPCPP_VERSION} \
+        build-essential \
+        cmake \
+        git \
+        ninja-build \
+        pkg-config \
+        libibverbs-dev \
+        librdmacm-dev \
+        libnuma-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+COPY . /workspace
+
+# Install Mooncake dependencies (submodules, Go, system libs, etc.).
+RUN bash dependencies.sh -y
+
+# Configure and build the Transfer Engine with the native XPU platform. icpx is
+# selected as the C/C++ compiler because USE_XPU links SYCL directly;
+# common.cmake enforces this and fails fast otherwise. Store/P2P components are
+# disabled to keep the DPC++ build focused on the XPU transfer path.
+RUN . /opt/intel/oneapi/setvars.sh >/dev/null && \
+    cmake -G Ninja -S . -B build-xpu \
+        -DCMAKE_C_COMPILER=icx \
+        -DCMAKE_CXX_COMPILER=icpx \
+        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} \
+        -DUSE_TENT=ON \
+        -DUSE_XPU=ON \
+        -DBUILD_UNIT_TESTS=ON \
+        -DWITH_STORE=OFF \
+        -DWITH_STORE_RUST=OFF \
+        -DWITH_P2P_STORE=OFF && \
+    cmake --build build-xpu --target tent_xpu_platform_test -j "$(nproc)"
+
+CMD ["bash"]
diff --git a/docs/source/api-reference/cpp/index.md b/docs/source/api-reference/cpp/index.md
index 089c657c8b..022c3a08b8 100644
--- a/docs/source/api-reference/cpp/index.md
+++ b/docs/source/api-reference/cpp/index.md
@@ -4,7 +4,7 @@
 |--------|-------------|
 | [Transfer Engine C++ API](transfer-engine) | `TransferEngine` class — memory registration, batch transfer, segment management, RDMA transport |
 | [TENT C++ API](tent) | `mooncake::tent::TransferEngine` — next-gen transfer engine with automatic transport selection and fault tolerance |
-| [Mooncake Store Client C++ API](mooncake-store) | `Client` class — `Put`/`Get`/`Remove`/`Replicate` operations, `BufferAllocatorBase` interface |
+| [Mooncake Store Client C++ API](mooncake-store) | `Client` class — `Put`/`Get`/`Remove`/`Replicate` operations |
 
 :::{toctree}
 :maxdepth: 1
diff --git a/docs/source/api-reference/cpp/mooncake-store.md b/docs/source/api-reference/cpp/mooncake-store.md
index 779655148c..49d9ca4ed8 100644
--- a/docs/source/api-reference/cpp/mooncake-store.md
+++ b/docs/source/api-reference/cpp/mooncake-store.md
@@ -26,7 +26,7 @@ tl::expected<void, ErrorCode> Get(const std::string& object_key,
                                   std::vector<Slice>& slices);
 ```
 
-`Get` retrieves the value of `object_key` into the provided `slices`. The returned data is guaranteed to be complete and correct. Each slice must reference local DRAM/VRAM memory that has been pre-registered with `registerLocalMemory(addr, len)` (not the global segments that contribute to the distributed memory pool). When persistence is enabled and the requested data is not found in the distributed memory pool, `Get` will fall back to loading the data from SSD.
+`Get` retrieves the value of `object_key` into the provided `slices`. The returned data is guaranteed to be complete and correct. Each slice must reference local DRAM/VRAM memory that has been pre-registered with `registerLocalMemory(addr, len)` (not the global segments that contribute to the distributed memory pool). The master returns the readable replica list and the client selects a complete replica. Depending on the selected replica, the data may be read from memory, NoF SSD, legacy shared-filesystem `DISK`, client-owned `LOCAL_DISK`, or the configured descriptor-based DFS backend.
 
 ### Put
 
@@ -36,24 +36,45 @@ tl::expected<void, ErrorCode> Put(const ObjectKey& key,
                                   const ReplicateConfig& config);
 ```
 
-`Put` stores the value associated with `key` in the distributed memory pool. The `config` parameter allows specifying the required number of replicas as well as the preferred segment for storing the value. When persistence is enabled, `Put` also asynchronously triggers a persistence operation to SSD.
+`Put` stores the value associated with `key` in the configured replica tiers. The `config` parameter controls the number of memory, NoF, and DFS replicas as well as placement preferences. Legacy `DISK` persistence and client-owned `LOCAL_DISK` SSD offload remain asynchronous. When `dfs_replica_num` is `1`, `Put` waits for the requested DFS `WriteAt` operation before returning success; this does not provide an additional `fsync` durability guarantee.
 
-**Replication Guarantees and Best Effort Behavior:**
+**Memory Replication Guarantees and Best Effort Behavior:**
 - Each slice of an object is guaranteed to be replicated to different segments, ensuring distribution across separate storage nodes
 - Different slices from different objects may be placed in the same segment
 - Replication operates on a best-effort basis: if insufficient space is available for all requested replicas, the object will still be written with as many replicas as possible
 
-The data structure details of `ReplicateConfig` are as follows:
+Requests with `dfs_replica_num == 1` use reliable multi-replica mode: allocation and every requested transfer must succeed, otherwise `Put` fails and allocated replicas are revoked.
+
+```{warning}
+Descriptor-based DFS is a work-in-progress feature for development and evaluation. It is not covered by the Store's production fault-tolerance, HA, durability, or multi-tenant guarantees.
+```
+
+The DFS-related replica-count fields of `ReplicateConfig` are as follows:
 
 ```C++
 struct ReplicateConfig {
-    size_t replica_num{1};                    // Total number of replicas for the object
-    bool with_soft_pin{false};               // Whether to enable soft pin mechanism for this object
-    bool with_hard_pin{false};               // Whether to enable hard pin (never evicted)
-    std::string preferred_segment{};         // Preferred segment for allocation
+    size_t replica_num{1};                       // Memory replicas
+    size_t nof_replica_num{0};                   // NoF SSD replicas
+    size_t dfs_replica_num{0};                   // Shared DFS replicas (0 or 1)
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE};
+    std::optional<uint64_t> soft_pin_ttl_ms{};   // ENABLE override; omitted uses the Master default
+    bool with_hard_pin{false};                   // Whether to enable hard pin (never evicted)
+    std::string preferred_segment{};             // Preferred segment for allocation
+    // Other placement, data-type, and grouping fields are omitted.
 };
 ```
 
+`dfs_replica_num` may currently be `0` or `1`. When it is `1`, `replica_num >= 1` is required, so DFS-only placement is not supported. DFS replicas currently support only the `default` tenant and require the master and client DFS backends to be configured with the same shared root and shard layout. See the {ref}`DFS deployment documentation <dfs-storage>` for setup and lifecycle limitations. Native C++ clients must initialize a `DistributedStorageBackend` and attach it with `SetDfsStorageBackend()` before issuing DFS reads or writes. DFS descriptors are carried by each `PutStart`, `UpsertStart`, or query response; there is no client-side descriptor cache. The Python/RealClient setup path attaches the backend through `FileStorage`.
+
+Soft pinning starts when the first replica becomes readable and has a fixed
+lifetime: reads do not extend it. `PRESERVE` keeps the committed deadline on an
+Upsert, `ENABLE` starts a new lifetime, and `DISABLE` removes it when the write
+commits. `soft_pin_ttl_ms` is valid only with `ENABLE`; zero commits ordinary
+cache, and values above the Master's configured maximum are rejected.
+Soft-pin state is not persisted in snapshots or the HA OpLog; after recovery or
+Standby promotion, restored objects are ordinary cache until a later write
+explicitly enables soft pinning again.
+
 ### Upsert
 
 ```C++
@@ -70,8 +91,11 @@ std::vector<tl::expected<void, ErrorCode>> BatchUpsert(
 `Upsert` inserts `key` if it does not exist and updates the existing object if
 it does. It uses the same replication configuration model as `Put`, while
 allowing the store to reuse existing placement for in-place updates when the
-current layout permits it. `BatchUpsert` performs the same operation for
-multiple keys using a shared replication configuration.
+current layout permits it. If either the existing object or the new request has
+a DFS replica, a same-size update requires the requested memory, NoF, and DFS
+replica counts to match the existing topology. A different-size update releases
+the old placement and allocates a new topology. `BatchUpsert` performs the same
+operation for multiple keys using a shared replication configuration.
 
 ### Remove
 
diff --git a/docs/source/api-reference/cpp/tent.md b/docs/source/api-reference/cpp/tent.md
index 22b56a0c68..46b68c7e56 100644
--- a/docs/source/api-reference/cpp/tent.md
+++ b/docs/source/api-reference/cpp/tent.md
@@ -106,6 +106,64 @@ export MC_USE_TENT=1
 
 When this variable is set, the `mooncake::TransferEngine` class internally delegates to `mooncake::tent::TransferEngine`. Most TE APIs are translated automatically. APIs that have no TENT equivalent (e.g., `installTransport`, `getMetadata`) become no-ops or return placeholder values.
 
+Passing a NIC priority matrix through `installTransport(..., args)` is **not** supported under TENT. Configure custom topology via `MC_TENT_CONF` or `MC_CUSTOM_TOPO_JSON` instead (see below).
+
+(custom-nic-priority-matrix)=
+### Custom NIC Priority Matrix
+
+TENT accepts the same classic Transfer Engine priority-matrix JSON format:
+
+```json
+{
+  "cpu:0": [["mlx5_0"], ["mlx5_1"]],
+  "cpu:1": [["mlx5_1"], ["mlx5_0"]],
+  "cuda:0": [["mlx5_0"], ["mlx5_1"]]
+}
+```
+
+Keys must match discovered location names (`cpu:N`, `cuda:N`, `hip:N` on AMD).
+TENT accepts the legacy AMD prefix `rocm:N` when parsing matrices so existing
+configs keep working — such keys are canonicalized to `hip:N` on load, and
+specifying both `rocm:N` and `hip:N` for the same device is rejected as a
+conflict. Discovery and dumps emit `hip:N`, matching classic TE.
+
+Preferred HCAs map to topology rank 0; available/fallback HCAs map to rank 1.
+
+Configuration priority (highest first):
+
+1. Inline matrix in `MC_TENT_CONF` / `Config`: `topology/priority_matrix`
+2. File path: `topology/custom_json_path` (also set by `MC_CUSTOM_TOPO_JSON`)
+3. Automatic topology discovery
+
+**Inline example (`MC_TENT_CONF`):**
+
+```json
+{
+  "topology": {
+    "priority_matrix": {
+      "cpu:0": [["mlx5_0"], ["mlx5_1"]],
+      "cuda:0": [["mlx5_0"], ["mlx5_1"]]
+    }
+  }
+}
+```
+
+**Path example:**
+
+```json
+{
+  "topology": {
+    "custom_json_path": "/etc/mooncake/nic_priority_matrix.json"
+  }
+}
+```
+
+```bash
+export MC_CUSTOM_TOPO_JSON=/etc/mooncake/nic_priority_matrix.json
+```
+
+A topology file may also use TENT's native `{"nics":[...],"mems":[...]}` format when loaded via `custom_json_path` / `MC_CUSTOM_TOPO_JSON`. If loading or parsing fails, TENT falls back to auto-discovery.
+
 ## Core APIs
 
 ### Core Usage Path (C++)
@@ -484,7 +542,7 @@ Status receiveNotification(std::vector<Notification>& notifi_list);
 
 Receives pending notifications from peers.
 
-- `notifi_list`: Output vector of received notifications.
+- `notifi_list`: Output vector of received notifications. The vector is cleared on entry, so each call reports only what that call delivered; a caller reusing one buffer across polls does not see the previous batch again. (Note that the classic Transfer Engine's `getNotifies()` appends instead of replacing.)
 - Return value: `Status::OK()` on success; otherwise a non-OK status.
 - Typical use: Polling loop to trigger follow-up actions on received data.
 
@@ -541,7 +599,7 @@ using Location = std::string;
 const static std::string kWildcardLocation = "*";
 ```
 
-Location strings identify device affinity: `"cpu:0"`, `"cuda:0"`, `"cuda:1"`, etc. Use `"*"` for automatic detection.
+Location strings identify device affinity: `"cpu:0"`, `"cuda:0"`, `"hip:0"`, etc. Use `"*"` for automatic detection. On AMD GPUs the canonical prefix is `hip:` (same as classic TE). The legacy TENT prefix `rocm:` is still accepted when parsing locations and custom NIC matrices.
 
 ### TransportType
 
diff --git a/docs/source/api-reference/cpp/transfer-engine.md b/docs/source/api-reference/cpp/transfer-engine.md
index d1fa4f8838..a438e064c0 100644
--- a/docs/source/api-reference/cpp/transfer-engine.md
+++ b/docs/source/api-reference/cpp/transfer-engine.md
@@ -199,6 +199,20 @@ Unregisters the region.
 - `update_metadata`: Whether to publish the unregistration to the metadata service.
 - Return value: If successful, returns 0; otherwise, returns a negative value.
 
+#### TransferEngine::allocateSharedMemory
+
+```cpp
+void* allocateSharedMemory(size_t length);
+void* allocateSharedMemory(size_t length, const SharedMemoryOptions& opt);
+int freeSharedMemory(void* addr);
+```
+
+Allocates a shared-memory region that `ShmTransport` can export to same-host peers. Ordinary `malloc` cannot be advertised this way. Requires `ShmTransport` (`MC_FORCE_SHM=1` or `installTransport("shm")`). Call `registerLocalMemory` on the returned pointer before remote access; a sub-range inside that allocation, or a length larger than the allocation, returns an error. Classic Transfer Engine only; TENT returns `nullptr` / `ERR_NOT_IMPLEMENTED`. Combining SHM with RDMA/TCP on one engine requires `-DENABLE_MULTI_PROTOCOL=ON`. Without that flag, `installTransport("shm")` logs a WARNING if it replaces an existing rdma/tcp segment protocol.
+
+The no-options overload (and `SharedMemoryOptions{}`) creates a POSIX shm object in `/dev/shm` named `/mooncake_<pid>_xxxxxxxx`, mode `0600` (same UID). With `opt.use_hugepage` and `hugepage_size` of 2MB, 512MB, or 1GB, TE creates a file on a matching hugetlbfs mount (`opt.hugetlbfs_path`, or `/dev/hugepages`, `/dev/hugepages-512M`, `/dev/hugepages-1G`) named `<mount>/mooncake_<pid>_xxxxxxxx`. Hugepage `length` must already be a multiple of that page size; TE does not round up, and it does not fall back to tmpfs if the mount is missing or the page size mismatches. `freeSharedMemory` only accepts pointers returned by `allocateSharedMemory`; a `malloc` pointer is rejected without unregistering other transports.
+
+`freeSharedMemory` and `ShmTransport`'s destructor unlink the object. Crash or `SIGKILL` skips that. POSIX leftovers sit in `/dev/shm` until reboot or manual `shm_unlink`. Hugetlbfs leftovers stay on the mount and **keep hugepages reserved** until the file is unlinked or the node reboots — worse than tmpfs leftovers. There is no automatic startup reaper: several processes share a mount, so deleting every `mooncake_*` on start would remove live peers' files. After a crash, remove only files whose encoded pid is gone, for example `rm /dev/hugepages/mooncake_<dead-pid>_*` (and the 512MB/1GB mounts if used). Peers detect an unlinked object on the next transfer, drop the orphaned mmap, and refetch metadata once; if realloc changes the virtual address, the initiator must use the new `BufferDesc.addr`.
+
 #### TransferEngine::registerLocalMemoryBatch
 
 ```cpp
@@ -240,6 +254,36 @@ int closeSegment(SegmentHandle segment_id);
 - `segment_id`: The unique identifier of the segment.
 - Return value: If successful, returns 0; otherwise, returns a negative value.
 
+#### TransferEngine::getSegmentBuffers
+
+```cpp
+struct SegmentBufferInfo {
+    uint64_t addr;
+    uint64_t length;
+    std::string location;
+};
+
+int getSegmentBuffers(SegmentHandle handle,
+                      std::vector<SegmentBufferInfo>& buffers);
+```
+
+Returns a snapshot of the memory buffers published in a segment, using the
+selected classic or TENT backend. This supports buffer inspection without
+accessing `getMetadata()`, which is unavailable under TENT.
+
+- `handle`: A segment handle returned by `openSegment()`.
+- `buffers`: Replaces any existing contents with buffer addresses, lengths in
+  bytes, and backend-reported location labels. Classic copies `BufferDesc::name`
+  (some transports, such as TCP, use a server name); TENT copies the native
+  location. Entries preserve the backend descriptor's order, which is not
+  guaranteed to be sorted by address. TENT internal buffers are excluded.
+- Return value: `0` on success, including a segment with no memory buffers;
+  `ERR_METADATA` if the descriptor cannot be retrieved; `ERR_NOT_IMPLEMENTED`
+  for file segments. On error, `buffers` is empty.
+- The call may fetch remote metadata and block. It does not close the handle,
+  register memory, or keep the reported buffers alive; the caller must coordinate
+  buffer lifetime with the owning peer.
+
 #### TransferEngine::removeLocalSegment
 
 ```cpp
@@ -399,7 +443,7 @@ Transport* installTransport(const std::string& proto, void** args);
 
 Installs a transport backend explicitly.
 
-- `proto`: Transport protocol name, such as `rdma`, `tcp`, or `nvmeof`.
+- `proto`: Transport protocol name, such as `rdma`, `tcp`, `nvmeof`, or `shm`.
 - `args`: Transport-specific arguments.
 > Note: In TENT, `installTransport` is not exposed (removed from the public API, including compatibility surfaces). Transport selection is internal to TENT.
 
@@ -426,6 +470,18 @@ Returns a transport instance by protocol name, mainly for advanced inspection or
 
 TransferEngine can send and receive lightweight notifications across segments to coordinate data movement.
 
+Notifications are sent only when requested through the APIs below. For classic TE:
+
+- `MC_RDMA_NOTIFY_ENABLED=1` (default) enables RDMA notifications for both `rdma` and
+  `rdma_twosided`; set it to `0` before initialization to use TCP.
+- Ordinary `rdma` supports up to 65528 combined bytes of `name` and `msg`. Unsupported
+  peers or larger messages fall back to TCP when `MC_RDMA_NOTIFY_OOB_FALLBACK=1`
+  (default); set it to `0` to return an error instead.
+- A successful ordinary RDMA send indicates local submission, without confirming
+  remote receipt. Connection setup or backpressure may block; applications must
+  ensure delivery before shutting down either engine.
+- Ordinary RDMA notifications use 32 MiB of registered host memory per endpoint.
+
 #### TransferEngine::submitTransferWithNotify
 
 ```cpp
diff --git a/docs/source/api-reference/http/http-service.md b/docs/source/api-reference/http/http-service.md
index 8c8ee90fdd..0050adcd50 100644
--- a/docs/source/api-reference/http/http-service.md
+++ b/docs/source/api-reference/http/http-service.md
@@ -260,6 +260,29 @@ Basic health check endpoint for service availability verification.
 curl http://localhost:8080/health
 ```
 
+#### `/version`
+Report the master version. Always available, including while the master is in
+standby.
+
+**Method**: `GET`
+**Content-Type**: `application/json; charset=utf-8`
+**Response**: JSON object with:
+- `version` (string): Store version used for RPC handshake compatibility
+- `display_version` (string): Human-readable release plus short git hash
+
+**Example**:
+```bash
+curl http://localhost:8080/version
+```
+
+```json
+{"version":"2.0.0","display_version":"0.3.12.post1 (git: f9e8311f)"}
+```
+
+Real clients expose the same `/version` payload on their own client HTTP port
+when `enable_client_http_server` is on. See
+[Client Metrics Endpoint](../../getting_started/observability.md#client-metrics-endpoint).
+
 ## Store REST API Endpoints
 
 The following endpoints are served by the Python store REST service, which wraps
@@ -280,9 +303,10 @@ mc_store_rest_server --config /path/to/mooncake_config.json --port 8080
 ```
 
 ### `/api/mount_shm`
-Mount a named shared memory object as one or more Mooncake store segments. If
-the requested size exceeds the maximum registration size, the service may split
-the region and return multiple segment ids.
+Mount a named shared memory object as one or more Mooncake store segments.
+Protocols with a registration-size limit split oversized regions and return
+multiple segment ids. Protocols without such a Store-level limit, such as TCP
+and RDMA, use a single segment regardless of `max_mr_size`.
 
 **Method**: `POST`
 **Content-Type**: `application/json`
@@ -366,9 +390,10 @@ curl -X POST http://localhost:8080/api/unmount_shm \
 
 ### `/api/mount`
 Allocate memory inside the store process and mount it as one or more Mooncake
-store segments. If the requested size exceeds the maximum registration size,
-the service may split it and return multiple segment ids. The response includes
-the actual allocated size after alignment.
+store segments. Protocols with a registration-size limit split oversized
+requests and return multiple segment ids. Protocols without such a Store-level
+limit, such as TCP and RDMA, use a single segment regardless of `max_mr_size`.
+The response includes the actual allocated size after alignment.
 
 **Method**: `POST`
 **Content-Type**: `application/json`
@@ -440,3 +465,54 @@ curl -X POST http://localhost:8080/api/unmount \
   -d '{"segment_ids": ["00000000-0000-0000-0000-000000000002"],
        "grace_period_seconds": 30}'
 ```
+
+### `/api/unmount_local_disk`
+Deregister this store's SSD offload tier from the master before the process
+goes away. Intended for a shutdown hook.
+
+The master stops naming this store as the owner of the keys it offloaded, so a
+reader gets a clean miss instead of a peer that is about to disappear. Without
+this, a `LOCAL_DISK` segment leaves the master only when the client expires —
+one `client_ttl` after the store stops pinging — and reads that pick up the
+stale owner in that window block on the connect retries (see
+`MC_RPC_CONNECT_TIMEOUT_MS`) before missing.
+
+The call then holds for `grace_period_seconds` before returning. Unlike a memory
+replica, which the NIC serves without help from the store process, a disk
+replica is read and pushed by that process, so it has to stay alive for the
+reads the master handed out before the deregistration. Offloading is stopped for
+good when this is called; the store is expected to exit afterwards.
+
+Returns success and does nothing when SSD offload is not enabled on this store.
+Safe to call more than once.
+
+**Method**: `POST`
+**Content-Type**: `application/json`
+
+**Request Body**:
+```json
+{
+  "grace_period_seconds": 30
+}
+```
+
+`grace_period_seconds` is optional and defaults to `0`, which returns as soon as
+the master has dropped the segment. Must be a non-negative integer no greater
+than 3600 (1 hour); a malformed body or an out-of-range value gets a `400`
+without touching the store, so a mistake here (seconds where milliseconds were
+meant, say) cannot block a preStop hook for hours.
+
+**Success Response**:
+```json
+{
+  "status": "success"
+}
+```
+
+**Example** — as a Kubernetes preStop hook, with a
+`terminationGracePeriodSeconds` longer than the grace period:
+```bash
+curl -X POST http://localhost:8080/api/unmount_local_disk \
+  -H "Content-Type: application/json" \
+  -d '{"grace_period_seconds": 30}'
+```
diff --git a/docs/source/api-reference/python/ep-backend.md b/docs/source/api-reference/python/ep-backend.md
index a3c12a38dd..c2d10f290d 100644
--- a/docs/source/api-reference/python/ep-backend.md
+++ b/docs/source/api-reference/python/ep-backend.md
@@ -1,14 +1,13 @@
-# Mooncake EP & Mooncake Backend (PG)
+# Mooncake EP & Mooncake PG
 
 ## Overview
 
 Mooncake provides two closely related components for fault-tolerant MoE
 inference:
 
-- **Mooncake Backend (PG)** is a `torch.distributed` ProcessGroup backend. It
-  registers the `mooncake` accelerator backend and the `mooncake-cpu` backend,
-  implements common collective and point-to-point APIs, tracks active ranks, and
-  exposes elastic recovery helpers.
+- **Mooncake PG** is a `torch.distributed` ProcessGroup backend. It registers
+  the `mooncake` accelerator backend and the `mooncake-cpu` backend, implements
+  collective and point-to-point APIs, and exposes dynamic-membership helpers.
 - **Mooncake EP** is an expert-parallel dispatch/combine runtime for
   latency-sensitive MoE inference. It follows the DeepEP low-latency programming
   model while adding rank activeness awareness and Mooncake transport support.
@@ -17,8 +16,9 @@ The usual integration pattern is to initialize a Mooncake process group first,
 then construct a Mooncake EP `Buffer` from that group. The process group is used
 both for regular collectives and for exchanging EP bootstrap metadata.
 
-For implementation details, see the [Mooncake Backend (PG) design guide](../../design/mooncake-backend-pg.md)
-and the [Mooncake EP design guide](../../design/mooncake-ep.md).
+For implementation details, see the
+[Mooncake PG design guide](../../design/mooncake-backend-pg.md) and the
+[Mooncake EP design guide](../../design/mooncake-ep.md).
 
 ## Installation and build notes
 
@@ -35,7 +35,7 @@ match the active `torch.__version__`. If the current PyTorch version does not
 match a built extension, import will fail with a message such as
 `Mooncake PG was not built against torch==...`.
 
-## Mooncake Backend (PG) quick start
+## Mooncake PG quick start
 
 ### CUDA backend
 
@@ -54,14 +54,10 @@ local_rank = int(os.environ.get("LOCAL_RANK", rank))
 torch.cuda.set_device(local_rank)
 device = torch.device("cuda", local_rank)
 
-# Backend-level active-rank mask. Use int32 and place it on the backend device.
-active_ranks = torch.ones(world_size, dtype=torch.int32, device=device)
-
 dist.init_process_group(
     backend="mooncake",
     rank=rank,
     world_size=world_size,
-    pg_options=pg.MooncakeBackendOptions(active_ranks),
 )
 
 x = torch.tensor([rank + 1], dtype=torch.int32, device=device)
@@ -77,18 +73,20 @@ torchrun --nproc-per-node=2 pg_quickstart.py
 
 ### CPU backend
 
-Use `backend="mooncake-cpu"` and put `active_ranks` on CPU:
+Use `backend="mooncake-cpu"`:
 
 ```python
-active_ranks = torch.ones(world_size, dtype=torch.int32)
 dist.init_process_group(
     backend="mooncake-cpu",
     rank=rank,
     world_size=world_size,
-    pg_options=pg.MooncakeBackendOptions(active_ranks),
 )
 ```
 
+`pg_options` is optional for a fixed-size group using the default failure
+handling. Pass `MooncakeBackendOptions` when reserving additional group
+capacity, joining as an extension, or selecting a non-default failure mode.
+
 ### Selecting network devices
 
 To explicitly restrict Mooncake to a list of NIC / HCA devices, call
@@ -103,27 +101,38 @@ pg.set_device_filter(["mlx5_1", "mlx5_2"])
 For test and benchmark commands, the same setting is commonly passed through
 `MOONCAKE_PGTEST_DEVICE_FILTERS=mlx5_1,mlx5_2`.
 
-## Mooncake Backend (PG) API reference
+## Mooncake PG Torch API reference
 
 ### `MooncakeBackendOptions`
 
 ```python
+pg.MooncakeBackendOptions(max_group_size)
+pg.MooncakeBackendOptions(max_group_size, is_extension)
+pg.MooncakeBackendOptions(
+    max_group_size,
+    is_extension,
+    auto_deactivate_on_failure,
+    auto_sync_on_failure,
+)
+
+# Explicit active-rank mirror overloads
 pg.MooncakeBackendOptions(active_ranks)
 pg.MooncakeBackendOptions(active_ranks, is_extension)
-pg.MooncakeBackendOptions(active_ranks, is_extension, max_world_size)
+pg.MooncakeBackendOptions(active_ranks, is_extension, max_group_size)
 ```
 
 Arguments:
 
-- `active_ranks`: `torch.int32` tensor used as the backend-level rank-health
-  mask. For `mooncake`, it must be on the accelerator device; for
-  `mooncake-cpu`, it must be on CPU. When `max_world_size` is set, size this
-  tensor to `max_world_size`, not the current visible world size.
+- `max_group_size`: fixed in-group slot capacity. It must be at least the
+  initially declared group size and cannot be increased later.
+- `active_ranks`: optional contiguous `torch.int32` storage used as a mirror of
+  committed PG membership. Its initial contents are ignored. Size it to
+  `max_group_size`; it may be on CPU or GPU.
 - `is_extension`: set to `True` for a replacement or joining process that will
   enter an existing group through `join_group()`.
-- `max_world_size`: optional upper bound for reserved rank slots. It lets
-  healthy ranks reserve inactive future ranks while keeping
-  `dist.get_world_size()` equal to the current active size.
+- `auto_deactivate_on_failure` and `auto_sync_on_failure`: select automatic or
+  framework-managed failure handling. Both default to `True`; auto-sync
+  requires auto-deactivation.
 
 ### Utility functions
 
@@ -133,15 +142,17 @@ Arguments:
 | `pg.set_device_filter(filters)` | Restrict NIC/HCA selection. | Call before `init_process_group()`. |
 | `pg.set_transfer_engine(engine)` | Reuse an external `TransferEngine`. | The engine must outlive all process groups. |
 | `pg.get_active_ranks(backend)` | Return the backend active-rank tensor. | Used by EP fallback and recovery paths. |
-| `pg.get_num_synced_ranks(backend)` | Return the number of ranks synchronized by the backend. | Diagnostic helper. |
-| `pg.extend_group_size_to(backend, size)` | Reserve additional inactive ranks. | Newly extended ranks do not participate until recovered. |
-| `pg.get_peer_state(backend, ranks)` | Check whether candidate ranks have published peer metadata. | Collective among healthy ranks. |
-| `pg.recover_ranks(backend, ranks)` | Activate ready ranks and publish extension state. | Requires peer metadata to be ready. |
-| `pg.join_group(backend)` | Joiner-side blocking call for extension ranks. | Used after `is_extension=True` initialization. |
+| `pg.get_num_synced_ranks(backend)` | Return the number of locally activatable group slots. | Diagnostic helper. |
+| `pg.get_peer_state(backend, ranks)` | Read locally mirrored activation readiness. | A lightweight, communication-free query. |
+| `pg.activate_ranks(backend, ranks)` | Propose activation through the Coordinator. | A single call from any online rank is sufficient. |
+| `pg.recover_ranks(backend, ranks)` | Propose activation through the Coordinator. | Compatibility alias to `activate_ranks`. |
+| `pg.deactivate_ranks(backend, ranks)` | Propose deactivation through the Coordinator. | A single call from any online rank is sufficient. |
+| `pg.join_group(backend)` | Confirm readiness for activation and remain blocked until activation actually occurs. | Used for scale-up, replacement, and in-place rejoin. |
+| `pg.sync_after_failure(backend)` | Report current link observations, wait for reconciliation, and apply the latest group view. | Called automatically when `auto_sync_on_failure=True`; it may also be called manually. |
 
 ### Supported distributed operations
 
-Mooncake Backend implements the following `torch.distributed` APIs. Support may
+Mooncake PG implements the following `torch.distributed` APIs. Support may
 depend on device type, dtype, PyTorch version, and whether the current backend is
 `mooncake` or `mooncake-cpu`; run the PG tests on the target environment before
 production use.
@@ -150,29 +161,27 @@ production use.
 | --- | --- | --- |
 | Collectives | `all_reduce`, `broadcast`, `all_gather`, `all_gather_into_tensor`, `reduce_scatter_tensor`, `all_to_all`, `barrier`, `reduce`, `gather`, `scatter` | Active ranks participate; inactive ranks are skipped by backend internals. |
 | Async work | `dist.all_reduce(..., async_op=True)` | Wait on the returned work object, then synchronize the device stream as needed. |
-| P2P | `isend`, `irecv`, `batch_isend_irecv` | Single-tensor P2P is routed through the Mooncake P2P shim. |
+| P2P | `isend`, `irecv`, `batch_isend_irecv` | Single-tensor P2P is routed through the Mooncake backend shim. |
 
 ## Elastic recovery protocol
 
-Mooncake PG supports a two-sided recovery protocol. Existing healthy ranks poll
-for replacement rank readiness, then activate those ranks. Replacement ranks
-start in extension mode, publish metadata, and wait until healthy ranks recover
-them.
+Mooncake PG separates join preparation from membership activation. A joining or
+recovering rank completes local warmup, calls `join_group()`, and waits. An
+existing rank may poll local readiness and then issue the activation proposal.
+The Coordinator validates and distributes the resulting membership.
 
 ### Healthy-rank side
 
 ```python
 from mooncake import pg
 
-active_ranks = torch.tensor([1, 1, 0], dtype=torch.int32, device=device)
 dist.init_process_group(
     backend="mooncake",
     rank=rank,
     world_size=2,
     pg_options=pg.MooncakeBackendOptions(
-        active_ranks,
+        3,                 # max_group_size
         False,             # is_extension
-        3,                 # max_world_size
     ),
 )
 
@@ -191,31 +200,35 @@ pg.recover_ranks(backend, join_ranks)
 ```python
 from mooncake import pg
 
-active_ranks = torch.tensor([1, 1, 1], dtype=torch.int32, device=device)
 dist.init_process_group(
     backend="mooncake",
     rank=2,
     world_size=3,
     pg_options=pg.MooncakeBackendOptions(
-        active_ranks,
+        3,                 # max_group_size
         True,              # is_extension
-        3,                 # max_world_size
     ),
 )
 
 backend = dist.group.WORLD
+
+# Collectives are local-only before join_group. Use this
+# window for framework-specific preparation, for example:
+# capture_cuda_graphs()
+# warm_up_model()
+
 pg.join_group(backend)
 ```
 
 Important semantics:
 
-- `get_peer_state()` is collective among the current healthy ranks. Call it in a
-  consistent order across those ranks.
-- New ranks are inactive after `extend_group_size_to()` and become collective
-  participants only after `recover_ranks()`.
-- A joining rank initialized with `is_extension=True` starts with local-only
-  behavior and blocks in `join_group()` until the corresponding healthy ranks
-  publish recovery state.
+- `get_peer_state()` is a local best-effort readiness query, not a collective.
+- Capacity must be reserved with `max_group_size` when founding members create
+  the group. A joining registration appends inactive slots within that capacity.
+- A joining rank starts with local-only collective behavior until `join_group`.
+  The join call then blocks until a Coordinator-approved activation commits.
+- A single `activate_ranks()` call, or its `recover_ranks()` alias, from any
+  online rank is sufficient; redundant equivalent calls are safe.
 - Subgroups must be created in the same order on healthy and joining processes,
   following PyTorch `new_group()` ordering rules.
 
@@ -399,27 +412,132 @@ matching dispatch `handle` and pass the resulting tensor back to `combine()` wit
 Reconnects EP peers after backend membership changes. Call it after PG recovery
 updates rank activeness so EP transport metadata and QPs can be refreshed.
 
+## Default NCCL backend for `ElasticBuffer`
+
+`mooncake.mooncake_elastic_buffer.ElasticBuffer` now defaults to
+`transport="auto"`. Auto mode uses NCCL when the extension was built with the
+NCCL Device API and the inferred EP topology is supported by the compiled NCCL
+kernels. Existing constructor calls require no changes. If NCCL cannot be
+used, auto mode falls back to IPC + IBGDA and retains the previous backend
+behavior. As before, the requested workload must have a compiled elastic kernel
+shape.
+
+NCCL support is opt-in. Build with
+`-DWITH_EP=ON -DUSE_CUDA=ON -DUSE_NCCL_DEVICE=ON`; the option defaults to
+`OFF`. NCCL-enabled EP extensions currently link directly to `libnccl`, so
+importing `mooncake.ep` requires a matching NCCL runtime even when the NCCL
+transport is not selected. Keep the option disabled for deployments that must
+remain compatible with older NCCL runtimes.
+
+No application-side communicator bootstrap is required. Auto mode creates one
+NCCL unique ID on process-group rank zero and broadcasts it to the group:
+
+```python
+import torch.distributed as dist
+
+from mooncake.mooncake_elastic_buffer import ElasticBuffer
+
+# Run this program with torchrun so rank metadata is available.
+dist.init_process_group(backend="nccl")
+buffer = ElasticBuffer(
+    dist.group.WORLD,
+    num_max_tokens_per_rank=128,
+    hidden=4096,
+    num_topk=8,
+)
+print(f"Mooncake EP selected {buffer.transport}")
+
+try:
+    # Call buffer.dispatch(...) and buffer.combine(...).
+    pass
+finally:
+    # Deterministic collective cleanup is recommended when NCCL was selected.
+    buffer.destroy()
+
+dist.destroy_process_group()
+```
+
+For a controlled rollout, pass `transport="ibgda"` or set
+`MOONCAKE_EP_TRANSPORT=ibgda`. Explicit `transport="nccl"` disables automatic
+fallback and reports an error if NCCL support is unavailable. The
+`explicitly_destroy` argument remains optional for compatibility with the
+DeepEP API; calling `destroy()` collectively is still the most predictable way
+to release NCCL symmetric windows before destroying the process group.
+
+The NCCL backend currently has the following constraints:
+
+- It requires NCCL 2.30.4 or newer with Device API and GIN support. The NCCL
+  headers used to build Mooncake must exactly match the loaded `libnccl`.
+  Rebuild Mooncake after an NCCL upgrade. If PyTorch would load another NCCL
+  first, configure or preload the matching runtime before initializing the
+  process group.
+- Process-group ranks must form contiguous, equal-sized NCCL LSA teams. The
+  compiled kernels support one team of two or eight GPUs (`1x2` or `1x8`), two
+  teams of four or eight GPUs (`2x4` or `2x8`), and four teams of four GPUs
+  (`4x4`). Cross-team communication uses hybrid mode and rail GIN. Auto mode
+  selects IPC + IBGDA for other shapes.
+- Groups with more than one rank request GIN resources, including runs whose
+  data path remains inside one LSA team.
+- Logical membership remains fixed. After every process observes that Mooncake
+  PG has restored every original logical rank slot, rebuild between EP
+  iterations. Each surviving process
+  calls `update_ep_member()` on its existing buffer while each replacement
+  process constructs an `ElasticBuffer` with the same arguments. Healthy
+  reconfiguration, with no replaced process, calls `update_ep_member()` on
+  every rank. These calls are one coordinated operation; do not start a new EP
+  operation until all calls return.
+- Reconfiguration rebuilds the host and device communicators, GIN resources,
+  symmetric window, and buffer allocation while preserving survivor Python
+  buffer objects. The recovered placement must still match a supported
+  topology. All dispatch handles and views created before the update are
+  invalid and must not be reused. Until the replacement is ready, the update
+  temporarily owns two complete NCCL generations: communicators, symmetric
+  windows, EP buffer allocations, and exclusive GIN contexts. Deployments near
+  memory, GIN-context, or QP limits must reserve capacity for both generations.
+- `update_ep_member()` does not complete an operation interrupted by failure or
+  run with missing logical ranks. Retry interrupted work after PG recovery.
+- A rank-local failure before the internal status collective is established
+  (for example, mismatched configuration/runtime or failure to allocate its
+  minimal CUDA control resources) is not recoverable in place and may require
+  restarting the process group. Use identical NCCL/CUDA configuration on every
+  rank.
+
 ## Active-rank tensors: PG vs EP
 
 There are two active-rank tensors in the API surface:
 
-- **PG active-rank mask**: passed to `pg.MooncakeBackendOptions`. This is the
-  backend-level health mask used by collective and recovery logic.
+- **PG active-rank mask**: passed to `pg.MooncakeBackendOptions`. This mirrors
+  the Coordinator's committed membership.
 - **EP active-rank tensor**: passed to `Buffer.dispatch()` and `Buffer.combine()`.
   It is also rank-level (`[num_ranks]`, `torch.int32`) and may be updated by EP
   kernels when timeout detection marks a peer as failed.
 
-In simple integrations these tensors often carry the same health information,
-but they are passed through different API layers. Keep their dtype, device, and
-shape consistent with the process group world size or reserved `max_world_size`.
+Their values may coincide in a simple integration, but their semantics are not
+interchangeable: PG membership is configuration, while EP may update its mask
+from kernel-level timeout observations. Keep the mapping, dtype, device, and
+capacity consistent when propagating committed PG membership into EP.
 
 ## Tests and examples
 
 - PG collectives: `mooncake-pg/tests/test_pg_collectives.py`
 - PG elastic recovery and subgroup extension: `mooncake-pg/tests/test_pg_elastic.py`
 - PG benchmark harness: `mooncake-pg/benchmark/README.md`
-- EP correctness and failure simulation: `mooncake-ep/tests/test_ep_grid.py`
-- Wheel-level EP example: `mooncake-wheel/tests/test_mooncake_ep.py`
+- EP correctness and failure simulation: `python/tests/ep/test_ep_grid.py`
+- EP wrapper example: `python/tests/ep/test_mooncake_ep.py`
+- NCCL EP rank-replacement recovery: `python/tests/ep/test_elastic_buffer_recovery.py`
+
+Run the NCCL EP recovery tests from the repository root with two visible CUDA
+devices and NCCL-enabled EP/PG extensions:
+
+```bash
+python -m pytest -q python/tests/ep/test_elastic_buffer_recovery.py
+```
+
+These tests check dispatch/combine before and after worker replacement, reject
+stale EP handles, and cover reserved PG capacity and a `mooncake-cpu` control
+group. The EP data path remains on the GPUs when the control group uses CPU
+tensors. The tests reuse the PG worker harness and honor
+`MOONCAKE_PGTEST_DEVICE_FILTERS` for NIC selection.
 
 See [PG/EP troubleshooting](../../troubleshooting/pg-ep-troubleshooting.md) for
 common setup and runtime issues.
diff --git a/docs/source/api-reference/python/mooncake-store.md b/docs/source/api-reference/python/mooncake-store.md
index fe6d71d3da..05d3a4923a 100644
--- a/docs/source/api-reference/python/mooncake-store.md
+++ b/docs/source/api-reference/python/mooncake-store.md
@@ -277,6 +277,33 @@ Zero-copy operations require registered memory buffers. For repeated reads and w
 #### register_buffer()
 Register a memory buffer for direct RDMA access.
 
+For a contiguous PyTorch CPU tensor, including one created with
+`pin_memory=True`, pass its address and **byte size**:
+
+```python
+import torch
+
+# Assumes store.setup(...) or store.setup_dummy(...) has already succeeded.
+tensor = torch.empty(1024, dtype=torch.float32, pin_memory=True)
+tensor.fill_(1)
+ptr = tensor.data_ptr()
+size = tensor.numel() * tensor.element_size()
+assert store.register_buffer(ptr, size) == 0
+try:
+    assert store.put_from("pinned_tensor", ptr, size) == 0
+    tensor.zero_()
+    assert store.get_into("pinned_tensor", ptr, size) == size
+    assert torch.all(tensor == 1)
+finally:
+    assert store.unregister_buffer(ptr) == 0
+```
+
+Keep the tensor alive and its storage unchanged until all operations finish and
+the buffer is unregistered. `put_from` stores raw bytes; it does not serialize
+the tensor's shape or dtype. With `setup_dummy()`, external CPU buffers use
+shared-memory staging and read copy-back across the RealClient process boundary.
+Pinned allocation alone does not make this path zero-copy.
+
 #### unregister_buffer()
 Unregister a previously registered buffer.
 
@@ -602,23 +629,70 @@ config = ReplicateConfig()
 #### replica_num
 **Type:** `int`
 **Default:** `1`
-**Description:** Specifies the total number of replicas to create for the stored object.
+**Description:** Specifies the number of memory replicas to create for the
+stored object.
 
 ```python
 config = ReplicateConfig()
-config.replica_num = 3  # Store 3 copies of the data
+config.replica_num = 3  # Store 3 memory replicas
 ```
 
-#### with_soft_pin
-**Type:** `bool`
-**Default:** `False`
-**Description:** Enables soft pinning for the stored object. Soft pinned objects are prioritized to remain in memory during eviction - they are only evicted when memory is insufficient and no other objects are eligible for eviction. This is useful for frequently accessed or important objects like system prompts.
+#### nof_replica_num
+**Type:** `int`
+**Default:** `0`
+**Description:** Specifies the number of replicas to create in the configured
+NVMe-oF SSD pool.
+
+```python
+config = ReplicateConfig()
+config.replica_num = 1
+config.nof_replica_num = 1
+```
+
+#### dfs_replica_num
+**Type:** `int`
+**Default:** `0`
+**Status:** **Work in progress; development and evaluation only.**
+**Description:** Requests an additional replica in the configured shared
+distributed filesystem. The supported values are currently `0` and `1`. When
+set to `1`, `replica_num` must be at least `1`, so DFS-only placement is not
+supported. DFS replicas currently support only the `default` tenant.
+
+```python
+config = ReplicateConfig()
+config.replica_num = 1
+config.dfs_replica_num = 1
+```
+
+Writes that request a DFS replica return success after the DFS `WriteAt`
+operation completes, but without an additional `fsync` durability guarantee.
+The master and client DFS backends must be enabled and configured with the same
+absolute shared-root path and shard layout. See the
+{ref}`DFS deployment documentation <dfs-storage>` for the required environment
+variables and current limitations.
+
+For a same-size `upsert`, if either the existing object or the new request has
+a DFS replica, the requested memory, NoF, and DFS replica counts must match the
+existing topology. A different-size update allocates a new topology.
+
+#### soft_pin_action
+**Type:** `SoftPinAction`
+**Default:** `SoftPinAction.PRESERVE`
+**Description:** Controls the soft-pin transition committed when the first replica becomes readable. `PRESERVE` keeps an existing deadline during Upsert, `ENABLE` starts a fixed soft-pin lifetime, and `DISABLE` removes it. Reads do not extend the lifetime.
 
 ```python
+from mooncake.store import ReplicateConfig, SoftPinAction
+
 config = ReplicateConfig()
-config.with_soft_pin = True  # Keep this object in memory longer
+config.soft_pin_action = SoftPinAction.ENABLE
+config.soft_pin_ttl_ms = 60_000  # Optional; omitted uses the Master default
 ```
 
+`soft_pin_ttl_ms` is valid only with `ENABLE`. The Master rejects TTLs above
+`max_kv_soft_pin_ttl`; a value of zero commits the object as ordinary cache.
+Soft-pin state is not persisted in snapshots or the HA OpLog. Restored objects
+therefore become ordinary cache after recovery or Standby promotion.
+
 #### with_hard_pin
 **Type:** `bool`
 **Default:** `False`
@@ -648,13 +722,13 @@ config.preferred_segment = self.get_hostname()
 ```
 
 #### prefer_alloc_in_same_node
-**Type:** `str`
-**Default:** `""` (empty string)
-**Description:** Enables the preference for allocating data on the same node. Currently, this only supports `batch_put_from_multi_buffers`. Additionally, it does not support disk segments, and the `replica_num` can only be set to 1.
+**Type:** `bool`
+**Default:** `False`
+**Description:** Enables host-aware local-first allocation for this request, using the writer host identity and the normal ordered remote fallback. This can be used with direct multi-buffer writes and tensor write APIs to avoid staging when the selected segment is local and local memcpy is enabled. It does not support disk segments, and the `replica_num` can only be set to 1. Tensor APIs keep their default staging behavior unless this flag is explicitly enabled.
 
 ```python
 config = ReplicateConfig()
-config.prefer_alloc_in_same_node = "True"
+config.prefer_alloc_in_same_node = True
 ```
 
 #### group_ids
@@ -686,233 +760,104 @@ store.put("key-a", b"value-a", config)
 
 ---
 
-## Unified Parallel Tensor IO API
-
-Mooncake Store also provides a unified tensor IO family for tensors that are stored either as full objects or as explicitly identified parallel shards.
-
-This API family is the long-term interface for TP / DP / EP / PP-aware tensor IO:
+(choosing-a-parallel-tensor-io-api)=
+## Choosing a Parallel Tensor IO API
 
-- write and upsert use `TensorParallelism`
-- reads use `ReadTarget`
-- legacy TP-only APIs remain available as compatibility wrappers
+Use the API that matches the object being stored. The single-axis TP methods
+and the manifest-backed weight snapshot API have different storage contracts.
 
-### ParallelAxis
+| Requirement | Public API | Contract |
+| --- | --- | --- |
+| Store and retrieve a complete tensor | `put_tensor()` / `get_tensor()` | One ordinary Store tensor object. |
+| Split a full tensor and read a TP shard | `put_tensor_with_tp()` / `get_tensor_with_tp()` | Legacy single-axis TP tensor objects; batch and registered-buffer variants are also available. |
+| Save weights and restore into a different TP/DP/EP/PP placement | `begin_weight_snapshot()` and `WeightStore.load_manifest()` / `plan_load()` / `load()` | Immutable manifest-managed fragments, with framework-supplied placement and runtime bindings. |
+| Use `put/get_tensor_with_cp`, `*_with_dp`, `*_with_ep`, or `*_with_pp` | No such public convenience methods | DP/EP/PP weight placement is expressed through the manifest API; CP is not a supported axis. |
+| Supply an arbitrary parallel strategy through `*_with_config` | No such public tensor API | `ReplicateConfig` controls Store replication and placement policy, not tensor parallel topology. |
 
-`ParallelAxis` describes one axis in a shard identity.
+For example, with an already initialized `MooncakeDistributedStore`, the
+legacy TP write accepts the **full** tensor and writes all shards. `tp_rank`
+on this write does not select a single shard to persist:
 
 ```python
-axis = mooncake.store.ParallelAxis()
-axis.kind = "tp"      # one of: "tp", "dp", "ep", "pp"
-axis.rank = 0
-axis.size = 8
-axis.split_dim = 1     # used for layout-sharding axes such as TP
-axis.expert_id = 3     # optional, for EP
-axis.stage_id = 1      # optional, for PP
-```
-
-**Fields:**
-- `kind`: Parallelism axis kind.
-- `rank`: Current shard rank on that axis.
-- `size`: Total number of shards on that axis.
-- `split_dim`: Optional tensor split dimension for layout-sharding axes.
-- `expert_id`: Optional expert identifier for EP layouts.
-- `stage_id`: Optional pipeline stage identifier for PP layouts.
-
-### TensorParallelism
-
-`TensorParallelism` is an ordered list of axes that identifies the stored or requested shard.
-
-```python
-parallelism = mooncake.store.TensorParallelism()
-parallelism.axes = [
-    tp_axis,
-]
-```
-
-Examples:
-- TP shard: `axes=[TP(...)]`
-- DP + TP shard: `axes=[DP(...), TP(...)]`
-- PP + TP shard: `axes=[PP(...), TP(...)]`
-- EP shard: `axes=[EP(...)]`
-
-### ReadTarget
-
-`ReadTarget` tells Mooncake whether the caller wants the stored form, a specific shard view, or the reconstructed full tensor.
-
-```python
-target = mooncake.store.ReadTarget()
-target.mode = "full"          # one of: "as_stored", "shard", "full"
-target.parallelism = None      # required for target shard reads
-```
-
-**Fields:**
-- `mode`: Read materialization mode.
-- `parallelism`: Optional `TensorParallelism`. Required when `mode="shard"`.
-
-### put_tensor_with_parallelism()
-
-Store a tensor using the unified parallelism model.
-
-```python
-def put_tensor_with_parallelism(
-    self,
-    key: str,
-    tensor,
-    parallelism: mooncake.store.TensorParallelism | None = None,
-    config: ReplicateConfig | None = None,
-    writer_partition = None,
-) -> int
-```
-
-Use `parallelism=None` to store a full tensor object. Provide `TensorParallelism` to store a shard-scoped object.
-
-`writer_partition` is an optional write-side shorthand for full-tensor inputs that should be stored as one shard. It describes the writer's `(rank, size, split_dim)` and is mutually exclusive with `parallelism`; do not provide both in one call.
-
-For TP-containing multi-axis layouts, the caller may pass the full source tensor; Mooncake derives and persists the uniform shard selected by the requested TP rank/layout. That applies to layouts such as `dp_tp`, `pp_tp`, and `ep_tp`.
-
-Plain single-axis TP remains shard-input for compatibility.
-
-Pure DP still does not imply a split axis by itself.
-
-### batch_put_tensor_with_parallelism()
-
-Batch version of unified tensor writes.
-
-```python
-def batch_put_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    tensors: list,
-    parallelisms: list[mooncake.store.TensorParallelism | None] | None = None,
-    config: ReplicateConfig | None = None,
-    writer_partitions = None,
-) -> list[int]
-```
-
-`writer_partitions` is an optional write-side convenience input for batch full-tensor writes that should be partitioned into stored shards. Each entry describes the target shard write as `(rank, size, split_dim)`.
-
-Use `writer_partitions` when the caller has full tensors and wants Mooncake to derive the stored shard objects from writer-side partition info instead of constructing full `TensorParallelism` objects per element. TP-containing `parallelisms` can now express the same full-tensor-input behavior too; `writer_partitions` remains the lighter explicit write-side shorthand.
-
-### get_tensor_with_parallelism()
-
-Read a tensor through the unified read path.
-
-```python
-def get_tensor_with_parallelism(
-    self,
-    key: str,
-    target: mooncake.store.ReadTarget | None = None,
-)
-```
-
-Typical modes:
-- `target=None` or `mode="as_stored"`: return the stored local object.
-- `mode="shard"`: return the target shard described by `target.parallelism`.
-- `mode="full"`: reconstruct and return the full tensor.
-
-### batch_get_tensor_with_parallelism()
-
-Batch version of unified tensor reads.
+import torch
 
-```python
-def batch_get_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    targets: list[mooncake.store.ReadTarget | None] | None = None,
-) -> list
+tensor = torch.linspace(0, 23, 24, dtype=torch.float32).reshape(4, 6)
+assert store.put_tensor_with_tp("tp-example", tensor, tp_size=2, split_dim=1) == 0
+shard = store.get_tensor_with_tp("tp-example", tp_rank=1, tp_size=2, split_dim=1)
+assert torch.equal(shard, tensor[:, 3:])
 ```
 
-### get_tensor_with_parallelism_into() / batch_get_tensor_with_parallelism_into()
+### Parallel configuration boundaries
 
-Zero-copy unified read forms. The destination buffers must resolve to Store-managed registered memory, either from `BufferPool`/the setup-time local buffer or from an explicit `register_buffer()` call.
+The model-weight API uses typed `ParallelTopology`, `WeightPlacementManifest`,
+and `WeightRuntimeBindingManifest` values supplied by the framework adapter.
+It does not provide a factory that generates a separate put/get method family
+for each axis, or accept an arbitrary strategy dictionary.
 
-```python
-def get_tensor_with_parallelism_into(
-    self,
-    key: str,
-    buffer_ptr: int,
-    size: int,
-    target: mooncake.store.ReadTarget | None = None,
-)
-```
+- TP and EP can describe logical splits. EP splits the leading logical expert
+  dimension; TP names an explicit logical dimension.
+- DP describes replicas or ownership. PP describes framework-provided tensor
+  or layer ownership. Neither implies a tensor split dimension.
+- CP (context parallelism) is absent from the current topology and axis types.
+  A sequence-dimension slice through the TP API does not establish CP topology
+  support or CP-aware KV-cache resharding.
+- Combining supported axes still requires complete logical coverage and
+  compatible source/target tensor descriptors. The planner is copy-only; it
+  does not convert dtype, quantization, packing, or model semantics.
 
-```python
-def batch_get_tensor_with_parallelism_into(
-    self,
-    keys: list[str],
-    buffer_ptrs: list[int],
-    sizes: list[int],
-    targets: list[mooncake.store.ReadTarget | None] | None = None,
-) -> list
-```
+See the [manifest contracts](../../design/mooncake-reshard/reshard-manifest.md),
+[weight reshard planner](../../design/mooncake-reshard/model-weight-reshard-planner.md), and
+[Store upload planning](../../design/mooncake-reshard/model-weight-store-upload-planning.md)
+for the configuration and execution boundaries.
 
-### upsert_tensor_with_parallelism()
+## Model Weight Snapshot API
 
-Unified upsert form for tensor objects.
+Heterogeneous model-weight snapshots use the manifest-backed Reshard API.
+The framework adapter owns model semantics and exports a complete source
+placement plus live runtime bindings. Mooncake Store persists the resulting
+payloads and the immutable stored manifest.
 
 ```python
-def upsert_tensor_with_parallelism(
-    self,
-    key: str,
-    tensor,
-    parallelism: mooncake.store.TensorParallelism | None = None,
-    config: ReplicateConfig | None = None,
-    writer_partition = None,
-) -> int
-```
-
-The write semantics match `put_tensor_with_parallelism()`, including full-tensor input for TP-containing layouts and the mutually exclusive `writer_partition` shorthand.
-
-### batch_upsert_tensor_with_parallelism()
-
-Batch unified upsert form.
+from mooncake.reshard.weight.store import WeightStore
 
-```python
-def batch_upsert_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    tensors: list,
-    parallelisms: list[mooncake.store.TensorParallelism | None] | None = None,
-    config: ReplicateConfig | None = None,
-    writer_partitions = None,
-) -> list[int]
+weight_store = WeightStore(store)
+session = weight_store.begin_weight_snapshot(descriptor, adapter)
+session.write_tensor(tensor_id, tensor)
+manifest = session.commit()
 ```
 
-The write semantics match `put_tensor_with_parallelism()`, including full-tensor input for TP-containing layouts.
+`MooncakeDistributedStore.begin_weight_snapshot(descriptor, adapter)` provides
+the same session for callers that already hold the native Store object.
 
-### *_from zero-copy write variants
+`write_tensor()` validates the adapter-selected source fragments against the
+session placement and runtime bindings. `commit()` publishes one
+`StoredWeightManifest` after complete durable coverage. Restore uses
+`WeightStore.load_manifest()`, `plan_load()`, and `load()` with the target
+placement and runtime binding manifests.
 
-The unified write and upsert family also has `_from` variants for registered-memory inputs, including:
+### Breaking Change and Migration
 
-- `put_tensor_with_parallelism_from(...)`
-- `batch_put_tensor_with_parallelism_from(...)`
-- `upsert_tensor_with_parallelism_from(...)`
-- `batch_upsert_tensor_with_parallelism_from(...)`
+PR [#3772](https://github.com/kvcache-ai/Mooncake/pull/3772) removed the public
+`*_with_parallelism` API family and the
+associated `ParallelAxis`, `TensorParallelism`, and `ReadTarget` helper types.
+Applications that create heterogeneous model-weight snapshots migrate their
+write path to `begin_weight_snapshot()`, `write_tensor()`, and `commit()`.
+The writer creates manifest-managed payload fragments and one
+`StoredWeightManifest`; it does not create ordinary Store tensor objects.
 
-These APIs accept Store-managed registered buffer pointers that contain serialized tensor objects in the current Mooncake tensor format:
-
-```text
-[TensorObjectHeader + layout metadata][tensor data]
-```
+Applications restore a snapshot through `load_manifest()`, `plan_load()`, and
+`load()` with the target placement and runtime binding manifests. The existing
+single-axis TP APIs named `*_with_tp` remain separate compatibility APIs.
 
-As with other zero-copy APIs, every source pointer must resolve to Store-managed registered memory, either from `BufferPool`/the setup-time local buffer or from an explicit `register_buffer()` call.
-
-### Compatibility wrappers
-
-Legacy TP-only methods such as:
-
-- `put_tensor_with_tp(...)`
-- `batch_put_tensor_with_tp(...)`
-- `get_tensor_with_tp(...)`
-- `batch_get_tensor_with_tp(...)`
-- corresponding `_into`, `_from`, and upsert variants
-
-remain supported for compatibility, but they are wrapper-style APIs around the unified parallel tensor IO model. Prefer the unified `*_with_parallelism` family for new code and new documentation examples.
+When `commit()` reports a manifest publication failure after Store records the
+commit decision, the writer remains open and preserves its payloads. Retry
+`commit()` on that writer to complete manifest publication.
 
 ---
 
 ## Non-Zero-Copy API (Simple Usage)
 
+
 For simpler use cases, use the standard API without memory registration:
 
 ### Basic Operations
@@ -1054,30 +999,57 @@ def setup(
     self,
     local_hostname: str,
     metadata_server: str,
-    global_segment_size: int = 16777216,
-    local_buffer_size: int = 1073741824,
-    protocol: str = "tcp",
-    rdma_devices: str = "",
+    global_segment_size: int,
+    local_buffer_size: int,
+    protocol: str,
+    rdma_devices: str,
     master_server_addr: str,
     engine: Optional[TransferEngine] = None,
     enable_ssd_offload: bool = False,
     ssd_offload_path: str = "",
     tenant_id: str = "default",
+    enable_client_http_server: bool = False,
+    client_http_port: int = 9300,
 ) -> int
 ```
 
+The positional overload requires every argument through
+`master_server_addr`. To use defaults for those fields, pass a configuration
+dictionary instead:
+
+```python
+def setup(self, config: Dict[str, object]) -> int
+```
+
+The dictionary overload requires `local_hostname` and `metadata_server`. Its
+other keys are optional; the defaults are `16777216` (16 MiB) for both
+`global_segment_size` and `local_buffer_size`, `"tcp"` for `protocol`, an empty
+string for `rdma_devices`, and `"127.0.0.1:50051"` for
+`master_server_addr`. It also accepts `ipc_socket_path` and the optional
+configuration fields listed below. The `engine` argument is available only in
+the positional overload.
+
 **Parameters:**
 - `local_hostname` (str): **Required**. Local hostname and port (e.g., "localhost" or "localhost:12345")
 - `metadata_server` (str): **Required**. Metadata connection string, e.g. `"P2PHANDSHAKE"` or `"http://localhost:8080/metadata"`.
-- `global_segment_size` (int): Memory segment size in bytes for mounting.
-- `local_buffer_size` (int): Local buffer size in bytes.
-- `protocol` (str): Network protocol, usually `"tcp"`, `"rdma"`, `"efa"`, `"cxl"`, or `"ascend"` depending on the build.
-- `rdma_devices` (str): RDMA/EFA device name(s), e.g. `"mlx5_0"` or `"mlx5_0,mlx5_1"`. Leave empty to auto-discover NICs unless `MC_MS_AUTO_DISC=0`; always empty for TCP.
-- `master_server_addr` (str): **Required**. Master server address (e.g., "localhost:50051")
+- `global_segment_size` (int): **Required by the positional overload**. Memory segment size in bytes for mounting.
+- `local_buffer_size` (int): **Required by the positional overload**. Local buffer size in bytes.
+- `protocol` (str): **Required by the positional overload**. Network protocol, usually `"tcp"`, `"rdma"`, `"efa"`, `"cxl"`, or `"ascend"` depending on the build.
+- `rdma_devices` (str): **Required by the positional overload**. RDMA/EFA device name(s), e.g. `"mlx5_0"` or `"mlx5_0,mlx5_1"`. Leave empty to auto-discover NICs unless `MC_MS_AUTO_DISC=0`; always empty for TCP.
+- `master_server_addr` (str): **Required by the positional overload**. Master server address (e.g., "localhost:50051")
 - `engine` (Optional[TransferEngine]): Existing Transfer Engine instance to reuse. Defaults to `None`.
-- `enable_ssd_offload` (bool): Enable client-side SSD offload support. Defaults to `False`.
-- `ssd_offload_path` (str): SSD offload directory. When provided, overrides the storage path environment configuration.
+- `enable_ssd_offload` (bool): Initialize client-side `FileStorage`. With a
+  normal file backend this enables SSD offload; with
+  `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=distributed_storage_backend`,
+  it initializes the DFS backend and is required for DFS reads and writes.
+  Defaults to `False`.
+- `ssd_offload_path` (str): FileStorage directory. When provided, it overrides
+  `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH`. With the distributed backend, DFS shard
+  data is stored under `MOONCAKE_DFS_ROOT_DIR`, but this separate directory is
+  still validated during FileStorage initialization.
 - `tenant_id` (str): Tenant namespace for object keys. Defaults to `"default"`.
+- `enable_client_http_server` (bool): Enable the client-local `/health`, `/metrics`, `/metrics/summary`, and `/version` HTTP endpoints. Defaults to `False`.
+- `client_http_port` (int): Port for the client-local HTTP endpoints. Defaults to `9300`.
 
 **Store segment pinned memory:** CUDA-enabled builds can register Store-managed
 host segments as pinned memory when `MC_STORE_PIN_MEMORY_MAX_BYTES` is set to a
@@ -1135,8 +1107,9 @@ store.setup_dummy(1024*1024*256, 1024*1024*64, "localhost:8080")
 Dummy clients do not own Store segments. They use a local shared-memory buffer
 that is mapped by a real client process at `server_address`. Tensor APIs that
 stage through this SHM buffer are supported, including tensor put/get,
-`*_tensor_from`, `*_tensor_into`, tensor upsert/pub, TP wrappers, and unified
-parallelism write wrappers.
+`*_tensor_from`, `*_tensor_into`, tensor upsert/pub, and the single-axis TP
+wrappers. Model-weight snapshots use the explicit snapshot API described
+above.
 
 The real client owns the SHM buffer allocator. This keeps tensor writes and
 regular object writes from allocating overlapping offsets when they run
@@ -1539,6 +1512,67 @@ for key, exists in zip(keys, results):
 
 ---
 
+#### probe_key()
+Point-in-time existence check that grants no read lease.
+
+Unlike `is_exist()`, a successful probe does not extend the object's lease,
+so probed objects remain eligible for eviction. A `1` result only means the
+object existed at the time of the call; it may be evicted before a
+subsequent `get`, and callers must treat a following miss as normal. This is
+suited for speculative scans (e.g., probing candidate keys to estimate
+prefix reuse) where the caller reads back only a subset of the probed keys.
+
+```python
+def probe_key(self, key: str) -> int
+```
+
+**Parameters:**
+- `key` (str): Object identifier to check
+
+**Returns:**
+- `int`:
+  - `1`: Object existed at the time of the call
+  - `0`: Object didn't exist
+  - `-1`: Error occurred
+
+**Example:**
+```python
+exists = store.probe_key("my_key")
+if exists == 1:
+    print("Object existed at probe time (no lease granted)")
+elif exists == 0:
+    print("Object not found")
+else:
+    print("Error checking existence")
+```
+
+---
+
+#### batch_probe_key()
+Point-in-time existence check for multiple objects in a single batch
+operation, granting no read leases.
+
+```python
+def batch_probe_key(self, keys: List[str]) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): List of object identifiers to check
+
+**Returns:**
+- `List[int]`: List of existence results (1=existed at probe time,
+0=not exists, -1=error)
+
+**Example:**
+```python
+keys = ["key1", "key2", "key3"]
+results = store.batch_probe_key(keys)
+candidates = [key for key, exists in zip(keys, results) if exists == 1]
+print("Probed candidates (unprotected from eviction):", candidates)
+```
+
+---
+
 #### get_size()
 Get the size of a stored object in bytes.
 
@@ -2141,7 +2175,7 @@ def pub_tensor(self, key: str, tensor: torch.Tensor, config: ReplicateConfig = N
 **Example:**
 ```python
 import torch
-from mooncake.store import ReplicateConfig
+from mooncake.store import ReplicateConfig, SoftPinAction
 
 # Create a tensor
 tensor = torch.randn(100, 100)
@@ -2149,7 +2183,7 @@ tensor = torch.randn(100, 100)
 # Create replication config
 config = ReplicateConfig()
 config.replica_num = 3
-config.with_soft_pin = True
+config.soft_pin_action = SoftPinAction.ENABLE
 
 # Publish tensor with replication settings
 result = store.pub_tensor("my_tensor", tensor, config)
@@ -2555,13 +2589,13 @@ shared-memory staging buffer.
 **Example:**
 ```python
 import torch
-from mooncake.store import ReplicateConfig
+from mooncake.store import ReplicateConfig, SoftPinAction
 
 tensor = torch.randn(100, 100)
 
 config = ReplicateConfig()
 config.replica_num = 2
-config.with_soft_pin = True
+config.soft_pin_action = SoftPinAction.ENABLE
 
 result = store.upsert_pub_tensor("my_tensor", tensor, config)
 if result == 0:
@@ -2910,6 +2944,207 @@ store.unregister_buffer(target_tensor.data_ptr())
 ```
 </details>
 
+---
+
+### Session-based ranged multi-buffer transfer
+
+For layerwise KV load/save, resolve Master metadata once per object, then transfer
+object-byte ranges across multiple buffers without re-querying Master on every layer.
+
+Typical flow:
+
+- Get: `batch_get_session_start` → `batch_get_into_multi_buffer_ranges` (per layer) → `batch_get_session_end`
+- Put: `batch_put_session_start` → `batch_put_from_multi_buffer_ranges` (per layer) → `batch_put_session_end` / `batch_put_session_revoke`
+
+Get sessions cache a filtered `QueryResult` (one complete MEMORY or DFS replica
+plus its lease). The MEMORY path remains zero-copy. DFS replicas are read into
+request-scoped host staging and then scattered to host or device destinations.
+If a key has no complete MEMORY or DFS replica, for example because it has only
+LOCAL_DISK, DISK, or NOF replicas, `batch_get_session_start` returns
+`INVALID_REPLICA` for that key and does not open a session.
+For device destinations, DFS staging first uses the fixed-capacity pinned restore
+arena configured by `MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES`; if that arena is
+unavailable or exhausted, it falls back to the regular client buffer allocator.
+Host-only reads use the regular client buffer allocator. Range calls only check
+the cached lease locally (zero Master RPCs). Put sessions reserve object space
+via Master `BatchPutStart` and finalize with `BatchPutEnd`.
+
+Put sessions write MEMORY replicas only. `nof_replica_num > 0` is accepted only for
+flexible dual-replica configs (`replica_num == 1` and `nof_replica_num == 1`), where
+`batch_put_session_end` finalizes MEMORY and revokes the unused NoF reservation.
+Reliable multi-replica NoF configs are rejected at session start. `end` / `revoke`
+seal the session (no further range writes) and wait for in-flight range transfers
+before talking to Master.
+
+⚠️ **Store-managed Buffer Required**: All destination buffers must resolve to
+Store-managed registered memory. DFS session reads use temporary staging; the
+staging allocation is released after the synchronous read and scatter finish.
+
+#### batch_get_session_start()
+
+Query replicas once and open a get session for the given keys.
+
+```python
+def batch_get_session_start(self, keys: List[str]) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers
+
+**Returns:**
+- `List[int]`: Per-key status (0 = success, negative = error)
+
+#### batch_get_into_multi_buffer_ranges()
+
+Ranged get into multiple buffers using an active get session (no Master RPC).
+
+```python
+def batch_get_into_multi_buffer_ranges(
+    self,
+    keys: List[str],
+    all_buffer_ptrs: List[List[int]],
+    all_sizes: List[List[int]],
+    all_src_offsets: List[List[int]],
+) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers (must have an active get session)
+- `all_buffer_ptrs` (List[List[int]]): Per-key list of destination buffer addresses
+- `all_sizes` (List[List[int]]): Per-key list of transfer sizes in bytes
+- `all_src_offsets` (List[List[int]]): Per-key list of object-byte source offsets
+
+**Returns:**
+- `List[int]`: Bytes transferred per key (positive = success, negative = error)
+
+#### batch_get_session_end()
+
+Drop cached get-session metadata for the given keys.
+
+```python
+def batch_get_session_end(self, keys: List[str]) -> int
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers
+
+**Returns:**
+- `int`: 0 on success, negative on error
+
+#### batch_put_session_start()
+
+Reserve objects and open a put session without transferring data.
+
+```python
+def batch_put_session_start(
+    self,
+    keys: List[str],
+    sizes: List[int],
+    config: ReplicateConfig = None,
+) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers
+- `sizes` (List[int]): Full object sizes in bytes
+- `config` (ReplicateConfig, optional): Replication configuration (applies at start only).
+  If `group_ids` is set, its length must equal `len(keys)`. When some keys already
+  have a put session, they are skipped and `group_ids` is filtered to match the
+  remaining keys.
+
+**Returns:**
+- `List[int]`: Per-key status (0 = success, negative = error)
+
+#### batch_put_from_multi_buffer_ranges()
+
+Ranged put from multiple buffers using an active put session (no Master RPC).
+
+```python
+def batch_put_from_multi_buffer_ranges(
+    self,
+    keys: List[str],
+    all_buffer_ptrs: List[List[int]],
+    all_sizes: List[List[int]],
+    all_dst_offsets: List[List[int]],
+) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers (must have an active put session)
+- `all_buffer_ptrs` (List[List[int]]): Per-key list of source buffer addresses
+- `all_sizes` (List[List[int]]): Per-key list of transfer sizes in bytes
+- `all_dst_offsets` (List[List[int]]): Per-key list of object-byte destination offsets
+
+**Returns:**
+- `List[int]`: Bytes transferred per key (positive = success, negative = error)
+
+#### batch_put_session_end()
+
+Finalize a put session and make objects readable.
+
+```python
+def batch_put_session_end(self, keys: List[str]) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers
+
+**Returns:**
+- `List[int]`: Per-key status (0 = success, negative = error)
+
+#### batch_put_session_revoke()
+
+Abort an incomplete put session and release reserved space.
+
+```python
+def batch_put_session_revoke(self, keys: List[str]) -> List[int]
+```
+
+**Parameters:**
+- `keys` (List[str]): Object identifiers
+
+**Returns:**
+- `List[int]`: Per-key status (0 = success, negative = error)
+
+**Example:**
+
+<details>
+<summary>Click to expand: Session ranged put/get example</summary>
+
+```python
+import numpy as np
+
+page = 1024
+layers = 4
+keys = ["block0", "block1"]
+object_sizes = [page * layers] * len(keys)
+
+# Prepare one registered buffer per layer for each key
+src = [np.full(page, i, dtype=np.uint8) for i in range(layers)]
+dst = [np.zeros(page, dtype=np.uint8) for _ in range(layers)]
+for buf in src + dst:
+    store.register_buffer(buf.ctypes.data, buf.nbytes)
+
+assert all(rc == 0 for rc in store.batch_put_session_start(keys, object_sizes))
+for layer in range(layers):
+    ptrs = [[src[layer].ctypes.data] for _ in keys]
+    sizes = [[page] for _ in keys]
+    offsets = [[layer * page] for _ in keys]
+    rcs = store.batch_put_from_multi_buffer_ranges(keys, ptrs, sizes, offsets)
+    assert all(rc == page for rc in rcs)
+assert all(rc == 0 for rc in store.batch_put_session_end(keys))
+
+assert all(rc == 0 for rc in store.batch_get_session_start(keys))
+for layer in range(layers):
+    ptrs = [[dst[layer].ctypes.data] for _ in keys]
+    sizes = [[page] for _ in keys]
+    offsets = [[layer * page] for _ in keys]
+    rcs = store.batch_get_into_multi_buffer_ranges(keys, ptrs, sizes, offsets)
+    assert all(rc == page for rc in rcs)
+assert store.batch_get_session_end(keys) == 0
+```
+</details>
+
 ## MooncakeHostMemAllocator Class
 
 The `MooncakeHostMemAllocator` class provides host memory allocation capabilities for Mooncake Store operations.
diff --git a/docs/source/api-reference/python/transfer-engine.md b/docs/source/api-reference/python/transfer-engine.md
index 9958d9edf7..955b7ac257 100644
--- a/docs/source/api-reference/python/transfer-engine.md
+++ b/docs/source/api-reference/python/transfer-engine.md
@@ -636,7 +636,7 @@ The Transfer Engine respects the following environment variables:
 - `MC_LEGACY_RPC_PORT_BINDING`: Enables legacy RPC port binding behavior
 - `MC_TCP_BIND_ADDRESS`: Specifies the TCP bind address
 - `MC_RDMA_BIND_ADDRESS`: Specifies the RDMA bind address for NIC path construction in dual-NIC environments. When set, RDMA NIC paths use this address while TCP handshake uses the address from `local_hostname`. This is useful when TCP and RDMA traffic use separate network interfaces (e.g., `eth0` for TCP and `rdma-net1` for RDMA).
-- `MC_CUSTOM_TOPO_JSON`: Path to custom topology JSON file
+- `MC_CUSTOM_TOPO_JSON`: Path to custom topology JSON file (classic NIC priority matrix, or under TENT also native `nics`/`mems` JSON). Honored by classic Transfer Engine and by TENT when `MC_USE_TENT=1` (maps to `topology/custom_json_path`). For TENT, prefer inlining `topology/priority_matrix` in `MC_TENT_CONF` when possible; see the {ref}`TENT C++ API <custom-nic-priority-matrix>`.
 - `MC_TE_FILTERS`: Optional comma-separated whitelist of IB device names (e.g. `mlx5_0,mlx5_2`) for legacy Transfer Engine topology discovery. When unset, all available devices are discovered.
 - `MC_TE_METRIC`: Enables metrics reporting (set to "1", "true", "yes", or "on"). **Note:** Not supported when using Transfer Engine TENT.
 - `MC_TE_METRIC_INTERVAL_SECONDS`: Sets metrics reporting interval in seconds
@@ -849,6 +849,7 @@ The `mooncake.engine` module provides boolean attributes that indicate whether s
 - `engine.SUPPORT_EFA`: Whether EFA (Elastic Fabric Adapter) support is enabled
 - `engine.SUPPORT_HIP`: Whether HIP (Heterogeneous-compute Interface for Portability) support is enabled
 - `engine.SUPPORT_MNNVL`: Whether MNNVL transport protocol support is enabled
+- `engine.SUPPORT_MUSA`: Whether the Moore Threads MUSA GPU IPC transport is enabled
 - `engine.SUPPORT_INTRA_NVLINK`: Whether intra-node NVLink support is enabled
 
 ### Usage Example
@@ -865,5 +866,6 @@ print(f"CUDA: {engine.SUPPORT_CUDA}")
 print(f"EFA: {engine.SUPPORT_EFA}")
 print(f"HIP: {engine.SUPPORT_HIP}")
 print(f"MNNVL: {engine.SUPPORT_MNNVL}")
+print(f"MUSA: {engine.SUPPORT_MUSA}")
 print(f"Intra-NVLink: {engine.SUPPORT_INTRA_NVLINK}")
 ```
diff --git a/docs/source/api-reference/rust/index.md b/docs/source/api-reference/rust/index.md
index 30ab8e8325..59bb1b8f69 100644
--- a/docs/source/api-reference/rust/index.md
+++ b/docs/source/api-reference/rust/index.md
@@ -3,7 +3,7 @@
 | Module | Description |
 |--------|-------------|
 | [Mooncake Store](./mooncake-store) | Safe Rust bindings for the distributed KV-cache store (`mooncake_store`) |
-| [Transfer Engine](./transfer-engine) | Rust bindings for Transfer Engine (FFI wrapper used by the Rust example crate) |
+| [Transfer Engine](./transfer-engine) | High-performance Rust library for Transfer Engine (`transfer_engine_rust`) |
 
 ```{toctree}
 :maxdepth: 1
diff --git a/docs/source/api-reference/rust/mooncake-store.md b/docs/source/api-reference/rust/mooncake-store.md
index f589246d9c..dc276f9879 100644
--- a/docs/source/api-reference/rust/mooncake-store.md
+++ b/docs/source/api-reference/rust/mooncake-store.md
@@ -182,19 +182,21 @@ Replication settings for write operations (`put`, `put_from`, `batch_put_from`).
 Fields:
 
 - `replica_num`: number of replicas (0 means “use server default”).
-- `with_soft_pin`: prefer retaining the object in memory (soft pin).
+- `soft_pin_action`: soft-pin intent for the write, one of `SoftPinAction::Preserve` (default; keeps an existing unexpired deadline), `SoftPinAction::Enable` (commits a new soft pin when the write becomes readable), or `SoftPinAction::Disable` (removes an existing soft pin). A soft pin guards an object from eviction until a deadline fixed at write time; reads never extend it.
+- `soft_pin_ttl_ms`: optional soft-pin TTL override in milliseconds. Only valid with `SoftPinAction::Enable`; `None` uses the master’s default TTL.
 - `with_hard_pin`: never evict (hard pin).
 - `preferred_segments`: whitelist of segment names that should host a replica.
 
 Example:
 
 ```rust
-use mooncake_store::{MooncakeStore, ReplicateConfig};
+use mooncake_store::{MooncakeStore, ReplicateConfig, SoftPinAction};
 
 fn write_with_replication(store: &MooncakeStore) -> Result<(), mooncake_store::StoreError> {
     let cfg = ReplicateConfig {
         replica_num: 2,
-        with_soft_pin: true,
+        soft_pin_action: SoftPinAction::Enable,
+        soft_pin_ttl_ms: None,
         with_hard_pin: false,
         preferred_segments: vec!["seg-a".to_string(), "seg-b".to_string()],
     };
diff --git a/docs/source/api-reference/rust/transfer-engine.md b/docs/source/api-reference/rust/transfer-engine.md
index ed3d13e432..62ada671ec 100644
--- a/docs/source/api-reference/rust/transfer-engine.md
+++ b/docs/source/api-reference/rust/transfer-engine.md
@@ -1,206 +1,172 @@
 # Transfer Engine Rust API
 
-This page documents the Rust bindings living under `mooncake-transfer-engine/rust`.
+This page documents the Rust crate `transfer_engine_rust` (located at
+`mooncake-transfer-engine/rust`). It is a **library** wrapper around the
+Transfer Engine C API (`transfer_engine_c.h`).
 
-At the time of writing, the Rust package (`transfer_engine_rust`) is primarily used as a **Rust-side binding + example binary**. The public Rust types are implemented in `src/transfer_engine.rs` and wrap the Transfer Engine C API (`transfer_engine_c.h`).
+Hot-path types (`TransferRequest`, `BufferEntry`, `TransferStatus`) are
+`#[repr(C)]` and compile-time layout-checked against the bindgen C types, so
+`submit_transfer` passes a Rust slice to C with **no heap allocation and no
+per-request copy** on the Rust side.
 
 For Transfer Engine design docs and non-Rust APIs, see:
 
 - Transfer Engine design docs: `design/transfer-engine/index`
 - Transfer Engine C++ API: `api-reference/cpp/transfer-engine`
+- Transfer Engine Python API: `api-reference/python/transfer-engine`
 
 ## Build & runtime prerequisites
 
-The Rust package uses bindgen + CMake to link against the Transfer Engine C/C++ build outputs.
-
 - **Build**:
-  - Requires Rust toolchain and libclang (bindgen).
-  - The package has `build.rs` that expects to find / build the native library via CMake.
+  - Requires a Rust toolchain and libclang (bindgen).
+  - CMake: `-DWITH_RUST_EXAMPLE=ON`, then
+    `cmake --build build --target build_transfer_engine_rust`.
+  - Or Cargo after exporting `MOONCAKE_BUILD_DIR` / `MOONCAKE_TE_LIB_DIR` /
+    `MOONCAKE_TE_INCLUDE_DIR` (see `mooncake-transfer-engine/rust/README.md`).
 - **Runtime**:
-  - Dynamic linker must find Transfer Engine shared libraries.
-  - You need a metadata server backend (commonly etcd) and a reachable peer segment registry.
-
-## Mental model
+  - Dynamic linker must find Transfer Engine shared libraries (`libasio.so`, …).
+  - A metadata server (HTTP metadata, etcd, or `P2PHANDSHAKE`) must be reachable.
+  - GitHub Actions runs `scripts/ci/run_transfer_engine_rust_smoke.sh` after the
+    C++ build (`cargo test --lib` plus the TCP loopback `minimal_smoke` test).
 
-The Transfer Engine operates on **segments** and **transfer batches**:
+## Quick start
 
-- You create a `TransferEngine` bound to:
-  - `metadata_uri` (for example, etcd endpoint)
-  - `local_server_name` (this node's address/name)
-  - `rpc_port` (RPC listener port)
-- You register local memory regions as RDMA-capable buffers.
-- You open a remote segment to obtain a `segment_id` (an integer handle).
-- You allocate a batch id for a fixed number of transfer requests.
-- You submit a batch of `TransferRequest`.
-- You poll status per task id inside the batch, then free the batch id.
+```rust
+use transfer_engine_rust::{MemoryPool, TransferEngine, TransferRequest, WILDCARD_LOCATION};
+
+fn main() -> Result<(), transfer_engine_rust::EngineError> {
+    let engine = TransferEngine::initialize(
+        "127.0.0.1:12345",
+        "http://127.0.0.1:8080/metadata",
+        "tcp",
+        "",
+    )?;
+
+    let pool = MemoryPool::new(1 << 20);
+    unsafe {
+        engine.register_local_memory(pool.as_void_ptr(), pool.len(), WILDCARD_LOCATION)?;
+
+        let seg = engine.open_segment("peer:12345")?;
+        let req = TransferRequest::write(pool.as_void_ptr(), seg, /*offset*/ 0, 4096);
+        engine.submit_and_wait(&[req], None)?;
+
+        engine.unregister_local_memory(pool.as_void_ptr())?;
+    }
+    Ok(())
+}
+```
 
-## API reference
+`initialize(local_hostname, metadata_server, protocol, device_name)` matches
+the Python constructor. `device_name` is accepted for API compatibility; NIC
+filtering is done with `MC_TE_FILTERS` because the C ABI has no device-name
+argument.
 
-### Enums
+The lower-level constructors map onto `createTransferEngine`:
 
-#### `OpcodeEnum`
+- `TransferEngine::new(metadata_uri, local_server_name, rpc_port)`
+- `TransferEngine::create(TransferEngineOptions { … })`
 
-- `OpcodeEnum::Read`
-- `OpcodeEnum::Write`
+## Mental model
 
-Used by `TransferRequest.opcode`.
+- Register local memory regions as RDMA/TCP-capable buffers.
+- Open a remote segment to obtain a `SegmentId`.
+- Allocate a `BatchId` for a fixed number of requests.
+- Submit a `&[TransferRequest]` (zero-copy FFI).
+- Poll `get_transfer_status` / `wait_all`, then `free_batch_id`.
 
-#### `TransferStatusEnum`
+Python-shaped helpers (`transfer_sync_write`, `batch_transfer_sync_*`,
+`transfer_submit_write`) cache segment ids by hostname. They allocate a
+batch internally. Use `submit_transfer` + `wait_all` when you need to keep
+the batch/request arrays on the stack.
 
-Status values returned by the C layer. Common values you will check for:
+## API reference
 
-- `Completed`
-- `Failed`
+### Types
+
+- `Opcode::{Read, Write}` — `OPCODE_READ` / `OPCODE_WRITE`
+- `TransferStatusCode::{Waiting, Pending, Invalid, Canceled, Completed, Timeout, Failed}`
+- `TransferRequest { opcode, source, target_id, target_offset, length }` —
+  layout matches `transfer_request_t`. Helpers: `TransferRequest::read`,
+  `TransferRequest::write`.
+- `BufferEntry { addr, length }` — layout matches `buffer_entry_t`
+- `TransferStatus { status, transferred_bytes }` — layout matches `transfer_status_t`
+- `BatchId(u64)` — `INVALID_BATCH` on allocate failure
+- `NotifyMsg { name, msg }`
+- `NicLoadStat { device_name, inflight_bytes, ewma_bandwidth_bps }`
+- `MemoryPool` — page-aligned, zeroed host buffer for registration
+- `WILDCARD_LOCATION` (`"*"`), `LOCAL_SEGMENT` (`0`)
+
+### Engine lifecycle
+
+- `initialize(local_hostname, metadata_server, protocol, device_name)`
+- `new` / `create`
+- `discover_topology`
+- `install_transport` / `uninstall_transport`
+- `local_ip_and_port`
+- Drop destroys the native handle (no double-free)
+
+### Memory
+
+All pointer APIs are `unsafe`. Registered memory must stay valid until
+unregistered.
+
+- `register_local_memory` / `register_local_memory_ex` (remote-accessible flag)
+- `unregister_local_memory`
+- `register_memory` / `unregister_memory` — Python aliases using `WILDCARD_LOCATION`
+- `register_local_memory_batch(&[BufferEntry])` — zero-copy
+- `unregister_local_memory_batch(&[*mut c_void])`
+
+### Segments
+
+- `open_segment` / `open_segment_no_cache` / `open_segment_cached`
+- `close_segment`
+- `warmup_efa_segment`
+- `remove_local_segment`
+- `sync_segment_cache`
+
+### Transfers (zero-copy hot path)
+
+- `allocate_batch_id(batch_size)`
+- `submit_transfer(batch_id, &[TransferRequest])`
+- `submit_transfer_with_notify(batch_id, requests, &NotifyMsg)`
+- `get_transfer_status(batch_id, task_id) -> TransferStatus`
+- `wait_all(batch_id, count, timeout)`
+- `submit_and_wait(&[TransferRequest], timeout)` — allocate + submit + wait + free
+- `free_batch_id`
+
+### Python-shaped transfers
+
+These open (and cache) a segment by hostname:
+
+- `transfer_sync` / `transfer_sync_write` / `transfer_sync_read`
+- `batch_transfer_sync` / `batch_transfer_sync_write` / `batch_transfer_sync_read`
+- `transfer_submit_write` — returns `BatchId`; caller must `free_batch_id`
+- `transfer_check_status` — polls task 0; does **not** free the batch
+
+### Notifications and diagnostics
+
+- `take_notifies() -> Vec<NotifyMsg>`
+- `send_notify(target_id, &NotifyMsg)`
+- `nic_load_stats() -> Vec<NicLoadStat>`
+- `enable_graceful_shutdown`
+- `show_links(json: bool) -> String`
+
+### Errors
+
+`EngineError` (`thiserror`, `#[non_exhaustive]`):
+
+- `NullHandle`
+- `InvalidString` (interior NUL)
+- `OperationFailed(i32)` — raw C status
+- `InvalidArgument`
+- `TransferFailed`
 - `Timeout`
 
-### Structs
-
-#### `TransferRequest`
-
-One transfer operation inside a batch.
-
-Fields:
-
-- `opcode: OpcodeEnum`
-- `source: *mut c_void`: local source/destination pointer (depends on opcode).
-- `target_id: i32`: segment id returned by `open_segment()`.
-- `target_offset: u64`: byte offset inside the target segment.
-- `length: u64`: transfer length in bytes.
-
-#### `BufferEntry`
-
-Used for batch memory registration:
-
-- `addr: *mut c_void`
-- `length: u64`
-
-### `TransferEngine`
-
-#### `new(metadata_uri, local_server_name, rpc_port) -> anyhow::Result<TransferEngine>`
-
-Create a new engine handle.
-
-Notes:
-
-- `metadata_uri` and `local_server_name` are passed through `CString`; interior `\0` bytes will error.
-- The wrapper currently disables `auto_discover` in the underlying C call.
-
-#### `discover_topology() -> anyhow::Result<()>`
-
-Trigger topology discovery.
-
-#### `install_transport(proto) -> anyhow::Result<()>`
-
-Install a transport by name (e.g. `"tcp"`, `"rdma"`, `"efa"` depending on build/runtime support).
-
-#### `register_local_memory(addr, length, location) -> anyhow::Result<()>`
-
-Register a local memory region for zero-copy transfers.
-
-- `addr`: pointer to the memory region.
-- `length`: size in bytes.
-- `location`: location string such as `"cpu:0"`.
-
-#### `unregister_local_memory(addr) -> anyhow::Result<()>`
-
-Unregister a previously registered memory region.
-
-#### `register_local_memory_batch(buffer_list, location) -> anyhow::Result<()>`
-
-Batch register multiple local buffers.
-
-- No-op when `buffer_list` is empty.
-
-#### `unregister_local_memory_batch(buffer_list) -> anyhow::Result<()>`
-
-Batch unregister multiple local buffers.
-
-#### `open_segment(name: String) -> anyhow::Result<i32>`
-
-Open a remote segment by name and get a segment id.
-
-#### `close_segment(segment_id: i32) -> anyhow::Result<()>`
-
-Close a previously opened segment.
-
-#### `warmup_efa_segment(name: &str) -> anyhow::Result<()>`
-
-Eagerly establish EFA endpoints so the first `submit_transfer()` does not pay the serial connection setup cost.
-
-- No-op on non-EFA transports.
-- Call after `open_segment()` and after the metadata server has published the peer's NIC list.
-
-#### `sync_segment_cache() -> anyhow::Result<()>`
-
-Synchronize segment cache from metadata.
-
-#### `allocate_batch_id(batch_size) -> anyhow::Result<u64>`
-
-Allocate a batch id for `batch_size` transfer requests.
-
-You must call `free_batch_id(batch_id)` after all tasks are done.
-
-#### `submit_transfer(batch_id, requests) -> anyhow::Result<()>`
-
-Submit a batch transfer request list.
-
-- No-op when `requests` is empty.
-- The wrapper converts each `TransferRequest` into the C representation (`transfer_request_t`).
-
-#### `get_transfer_status(batch_id, task_id) -> anyhow::Result<(i32, u64)>`
-
-Get status for one task in a batch.
-
-- `task_id` is an index inside the batch, typically `0..batch_size`.
-- Returns `(status_code, transferred_bytes)`.
-
-The `status_code` maps to values in `TransferStatusEnum` (represented as `i32`).
-
-#### `free_batch_id(batch_id) -> anyhow::Result<()>`
-
-Free a previously allocated batch id.
-
-## Minimal usage example (pseudo-code)
-
-The crate's `src/main.rs` contains a full benchmark-style example. The following sketch shows the typical control flow:
-
-```rust
-use std::ffi::c_void;
-use transfer_engine_rust::transfer_engine::{OpcodeEnum, TransferEngine, TransferRequest};
-
-fn main() -> anyhow::Result<()> {
-    let engine = TransferEngine::new("127.0.0.1:2379", "127.0.0.1", 12345)?;
-    engine.discover_topology()?;
-    engine.install_transport("tcp")?;
-
-    // Register local memory (example only; you must allocate and pin memory appropriately).
-    let mut buffer = vec![0u8; 4096];
-    engine.register_local_memory(buffer.as_mut_ptr() as *mut c_void, buffer.len(), "cpu:0")?;
-
-    let seg_id = engine.open_segment("target-seg".to_string())?;
-    let batch_id = engine.allocate_batch_id(1)?;
-
-    let mut reqs = [TransferRequest {
-        opcode: OpcodeEnum::Write,
-        source: buffer.as_mut_ptr() as *mut c_void,
-        target_id: seg_id,
-        target_offset: 0,
-        length: buffer.len() as u64,
-    }];
-
-    engine.submit_transfer(batch_id, &mut reqs)?;
-    let (status, bytes) = engine.get_transfer_status(batch_id, 0)?;
-    println!("status={status}, bytes={bytes}");
-
-    engine.free_batch_id(batch_id)?;
-    engine.close_segment(seg_id)?;
-    engine.unregister_local_memory(buffer.as_mut_ptr() as *mut c_void)?;
-    Ok(())
-}
-```
-
 ## Safety & thread-safety
 
-- The wrapper marks `TransferEngine` as `Send + Sync`, but it owns an FFI handle (`transfer_engine_t`).
-- All pointer-based arguments must satisfy Rust’s aliasing and lifetime rules.
-- You must ensure registered memory remains valid until it is unregistered.
+- `TransferEngine` is `Send + Sync`; the C++ engine serializes internally.
+- Pointer arguments must satisfy Rust aliasing and lifetime rules.
+- Registered memory must remain valid until unregistered.
+- `submit_transfer` does not copy request bytes; do not mutate a submitted
+  `TransferRequest` until the C call returns (the C layer copies into its own
+  vector before returning).
diff --git a/docs/source/conf.py b/docs/source/conf.py
index c10fad2189..51145545e0 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -27,9 +27,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Mooncake'
-copyright = f'{datetime.datetime.now().year}, Mooncake Team'
-author = 'the Mooncake Team'
+project = "Mooncake"
+copyright = f"{datetime.datetime.now().year}, Mooncake Team"
+author = "the Mooncake Team"
 
 # -- General configuration ---------------------------------------------------
 
@@ -54,7 +54,7 @@
 ]
 myst_fence_as_directive = ["mermaid"]
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -75,20 +75,20 @@
 # a list of builtin themes.
 #
 html_title = project
-html_theme = 'sphinx_book_theme'
-html_logo = 'image/mooncake-icon.png'
-html_favicon = 'image/moonshot.ico'
+html_theme = "sphinx_book_theme"
+html_logo = "image/mooncake-icon.png"
+html_favicon = "image/moonshot.ico"
 html_theme_options = {
-    'path_to_docs': 'docs/source',
-    'repository_url': 'https://github.com/kvcache-ai/Mooncake',
-    'use_repository_button': True,
-    'use_edit_page_button': True,
+    "path_to_docs": "docs/source",
+    "repository_url": "https://github.com/kvcache-ai/Mooncake",
+    "use_repository_button": True,
+    "use_edit_page_button": True,
     # Prevents the full API being added to the left sidebar of every page.
     # Reduces build time by 2.5x and reduces build size from ~225MB to ~95MB.
-    'collapse_navbar': True,
-    'show_navbar_depth': 2,
+    "collapse_navbar": True,
+    "show_navbar_depth": 2,
     # Makes API visible in the right sidebar on API reference pages.
-    'show_toc_level': 3,
+    "show_toc_level": 3,
 }
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -99,19 +99,17 @@
 
 myst_heading_anchors = 2
 myst_url_schemes = {
-    'http': None,
-    'https': None,
-    'mailto': None,
-    'ftp': None,
+    "http": None,
+    "https": None,
+    "mailto": None,
+    "ftp": None,
     "gh-issue": {
-        "url":
-        "https://github.com/kvcache-ai/Mooncake/issues/{{path}}#{{fragment}}",
+        "url": "https://github.com/kvcache-ai/Mooncake/issues/{{path}}#{{fragment}}",
         "title": "Issue #{{path}}",
         "classes": ["github"],
     },
     "gh-pr": {
-        "url":
-        "https://github.com/kvcache-ai/Mooncake/pull/{{path}}#{{fragment}}",
+        "url": "https://github.com/kvcache-ai/Mooncake/pull/{{path}}#{{fragment}}",
         "title": "Pull Request #{{path}}",
         "classes": ["github"],
     },
@@ -133,8 +131,7 @@
 }
 
 # Always remove the warning banner
-header_file = os.path.join(os.path.dirname(__file__),
-                           "_templates/sections/header.html")
+header_file = os.path.join(os.path.dirname(__file__), "_templates/sections/header.html")
 if os.path.exists(header_file):
     os.remove(header_file)
 
@@ -158,8 +155,8 @@ def get_repo_base_and_branch(pr_number):
     response = requests.get(url)
     if response.status_code == 200:
         data = response.json()
-        _cached_base = data['head']['repo']['full_name']
-        _cached_branch = data['head']['ref']
+        _cached_base = data["head"]["repo"]["full_name"]
+        _cached_branch = data["head"]["ref"]
         return _cached_base, _cached_branch
     else:
         logger.error("Failed to fetch PR details: %s", response)
@@ -167,9 +164,9 @@ def get_repo_base_and_branch(pr_number):
 
 
 def linkcode_resolve(domain, info):
-    if domain != 'py':
+    if domain != "py":
         return None
-    if not info['module']:
+    if not info["module"]:
         return None
 
     # Get path from module name
@@ -183,8 +180,8 @@ def linkcode_resolve(domain, info):
     # Get the line number of the object
     with open(path) as f:
         lines = f.readlines()
-    name = info['fullname'].split(".")[-1]
-    pattern = fr"^( {{4}})*((def|class) )?{name}\b.*"
+    name = info["fullname"].split(".")[-1]
+    pattern = rf"^( {{4}})*((def|class) )?{name}\b.*"
     for lineno, line in enumerate(lines, 1):
         if not line or line.startswith("#"):
             continue
@@ -237,12 +234,12 @@ def linkcode_resolve(domain, info):
             "Potentially problematic mock target (%s) found; "
             "autodoc_mock_imports cannot mock modules that have already "
             "been loaded into sys.modules when the sphinx build starts.",
-            mock_target)
+            mock_target,
+        )
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "typing_extensions":
-    ("https://typing-extensions.readthedocs.io/en/latest", None),
+    "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest", None),
     "aiohttp": ("https://docs.aiohttp.org/en/stable", None),
     "pillow": ("https://pillow.readthedocs.io/en/stable", None),
     "numpy": ("https://numpy.org/doc/stable", None),
@@ -255,83 +252,58 @@ def linkcode_resolve(domain, info):
 # Preserve published URLs when documentation is reorganized. Redirect targets
 # are relative to the generated location of each legacy page.
 redirects = {
+    "design/mooncake-store": "store/mooncake-store.html",
+    "design/ssd-offload": "store/ssd-offload.html",
+    "design/ssd-free-ratio-first-allocation": "store/ssd-free-ratio-first-allocation.html",
+    "design/engram": "store/engram.html",
+    "design/tent/tebench": "../../performance/mooncake/tebench.html",
     "deployment/ssd-offload": "ssd/ssd-offload.html",
-    "deployment/nvmf-ssd-deployment-guide":
-    "ssd/nvmf-ssd-deployment-guide.html",
+    "deployment/nvmf-ssd-deployment-guide": "ssd/nvmf-ssd-deployment-guide.html",
     "integrations/index": "../deployment/index.html",
-    "integrations/lmcache":
-    "../deployment/integrations/lmcache/index.html",
-    "integrations/lmdeploy":
-    "../deployment/integrations/lmdeploy.html",
-    "integrations/sglang/index":
-    "../../deployment/integrations/sglang/index.html",
-    "integrations/sglang/hicache-integration-v1":
-    "../../deployment/integrations/sglang/hicache-integration-v1.html",
-    "integrations/sglang/hicache-quick-start":
-    "../../deployment/integrations/sglang/hicache-quick-start.html",
-    "integrations/sglang/pd-disaggregation":
-    "../../deployment/integrations/sglang/pd-disaggregation.html",
-    "integrations/vllm/index":
-    "../../deployment/integrations/vllm/index.html",
-    "integrations/vllm/disagg-prefill-decode":
-    "../../deployment/integrations/vllm/disagg-prefill-decode.html",
-    "integrations/vllm/kv-cache-storage":
-    "../../deployment/integrations/vllm/kv-cache-storage.html",
-    "integrations/vllm/vllm-integration-v0.2":
-    "../../deployment/integrations/vllm/vllm-integration-v0.2.html",
-    "integrations/vllm/vllm-integration-v0.3":
-    "../../deployment/integrations/vllm/vllm-integration-v0.3.html",
-    "integrations/vllm/vllm-integration-v1.0":
-    "../../deployment/integrations/vllm/vllm-integration-v1.0.html",
-    "integrations/vllm/vllm-mooncakestoreconnector":
-    "../../deployment/integrations/vllm/vllm-mooncakestoreconnector.html",
-    "integrations/vllm/vllmv1-lmcache-integration":
-    "../../deployment/integrations/lmcache/vllmv1-lmcache-integration.html",
-    "integrations/vllm/vllmv1-lmcache-mp-integration":
-    "../../deployment/integrations/lmcache/vllmv1-lmcache-mp-integration.html",
-    "getting_started/examples/lmcache-integration":
-    "../../deployment/integrations/lmcache/index.html",
-    "getting_started/examples/lmdeploy-integration-v0.9":
-    "../../deployment/integrations/lmdeploy.html",
-    "getting_started/examples/sglang-integration-v1":
-    "../../deployment/integrations/sglang/pd-disaggregation.html",
-    "getting_started/examples/sglang-integration/index":
-    "../../../deployment/integrations/sglang/index.html",
-    "getting_started/examples/sglang-integration/hicache-integration-v1":
-    "../../../deployment/integrations/sglang/hicache-integration-v1.html",
-    "getting_started/examples/sglang-integration/hicache-quick-start":
-    "../../../deployment/integrations/sglang/hicache-quick-start.html",
-    "getting_started/examples/vllm-integration/index":
-    "../../../deployment/integrations/vllm/index.html",
-    "getting_started/examples/vllm-integration/disagg-prefill-decode":
-    "../../../deployment/integrations/vllm/disagg-prefill-decode.html",
-    "getting_started/examples/vllm-integration/kv-cache-storage":
-    "../../../deployment/integrations/vllm/kv-cache-storage.html",
-    "getting_started/examples/vllm-integration/vllm-integration-v0.2":
-    "../../../deployment/integrations/vllm/vllm-integration-v0.2.html",
-    "getting_started/examples/vllm-integration/vllm-integration-v0.3":
-    "../../../deployment/integrations/vllm/vllm-integration-v0.3.html",
-    "getting_started/examples/vllm-integration/vllm-integration-v1.0":
-    "../../../deployment/integrations/vllm/vllm-integration-v1.0.html",
-    "getting_started/examples/vllm-integration/vllm-mooncakestoreconnector":
-    "../../../deployment/integrations/vllm/vllm-mooncakestoreconnector.html",
-    "getting_started/examples/vllm-integration/vllmv1-lmcache-integration":
-    "../../../deployment/integrations/lmcache/vllmv1-lmcache-integration.html",
-    "getting_started/examples/vllm-integration/vllmv1-lmcache-mp-integration":
-    "../../../deployment/integrations/lmcache/vllmv1-lmcache-mp-integration.html",
-    "python-api-reference/dataproto-structured-object-transfer":
-    "../api-reference/python/dataproto-structured-object-transfer.html",
-    "python-api-reference/ep-backend":
-    "../api-reference/python/ep-backend.html",
-    "python-api-reference/mooncake-store":
-    "../api-reference/python/mooncake-store.html",
-    "python-api-reference/transfer-engine":
-    "../api-reference/python/transfer-engine.html",
-    "http-api-reference/http-service":
-    "../api-reference/http/http-service.html",
-    "design/transfer-engine/cpp-api":
-    "../../api-reference/cpp/transfer-engine.html",
+    "integrations/lmcache": "../deployment/integrations/lmcache/index.html",
+    "integrations/lmdeploy": "../deployment/integrations/lmdeploy.html",
+    "integrations/sglang/index": "../../deployment/integrations/sglang/index.html",
+    "integrations/sglang/hicache-integration-v1": "../../deployment/integrations/sglang/hicache-integration-v1.html",
+    "integrations/sglang/hicache-quick-start": "../../deployment/integrations/sglang/hicache-quick-start.html",
+    "integrations/sglang/pd-disaggregation": "../../deployment/integrations/sglang/pd-disaggregation.html",
+    "integrations/vllm/index": "../../deployment/integrations/vllm/index.html",
+    "integrations/vllm/disagg-prefill-decode": "../../deployment/integrations/vllm/disagg-prefill-decode.html",
+    "integrations/vllm/kv-cache-storage": "../../deployment/integrations/vllm/kv-cache-storage.html",
+    "integrations/vllm/vllm-integration-v0.2": "../../deployment/integrations/vllm/vllm-integration-v0.2.html",
+    "integrations/vllm/vllm-integration-v0.3": "../../deployment/integrations/vllm/vllm-integration-v0.3.html",
+    "integrations/vllm/vllm-integration-v1.0": "../../deployment/integrations/vllm/vllm-integration-v1.0.html",
+    "integrations/vllm/vllm-mooncakestoreconnector": "../../deployment/integrations/vllm/vllm-mooncakestoreconnector.html",
+    "integrations/vllm/vllmv1-lmcache-integration": "../../deployment/integrations/lmcache/vllmv1-lmcache-integration.html",
+    "integrations/vllm/vllmv1-lmcache-mp-integration": "../../deployment/integrations/lmcache/vllmv1-lmcache-mp-integration.html",
+    "getting_started/examples/lmcache-integration": "../../deployment/integrations/lmcache/index.html",
+    "getting_started/examples/lmdeploy-integration-v0.9": "../../deployment/integrations/lmdeploy.html",
+    "getting_started/examples/sglang-integration-v1": "../../deployment/integrations/sglang/pd-disaggregation.html",
+    "getting_started/examples/sglang-integration/index": "../../../deployment/integrations/sglang/index.html",
+    "getting_started/examples/sglang-integration/hicache-integration-v1": "../../../deployment/integrations/sglang/hicache-integration-v1.html",
+    "getting_started/examples/sglang-integration/hicache-quick-start": "../../../deployment/integrations/sglang/hicache-quick-start.html",
+    "getting_started/examples/vllm-integration/index": "../../../deployment/integrations/vllm/index.html",
+    "getting_started/examples/vllm-integration/disagg-prefill-decode": "../../../deployment/integrations/vllm/disagg-prefill-decode.html",
+    "getting_started/examples/vllm-integration/kv-cache-storage": "../../../deployment/integrations/vllm/kv-cache-storage.html",
+    "getting_started/examples/vllm-integration/vllm-integration-v0.2": "../../../deployment/integrations/vllm/vllm-integration-v0.2.html",
+    "getting_started/examples/vllm-integration/vllm-integration-v0.3": "../../../deployment/integrations/vllm/vllm-integration-v0.3.html",
+    "getting_started/examples/vllm-integration/vllm-integration-v1.0": "../../../deployment/integrations/vllm/vllm-integration-v1.0.html",
+    "getting_started/examples/vllm-integration/vllm-mooncakestoreconnector": "../../../deployment/integrations/vllm/vllm-mooncakestoreconnector.html",
+    "getting_started/examples/vllm-integration/vllmv1-lmcache-integration": "../../../deployment/integrations/lmcache/vllmv1-lmcache-integration.html",
+    "getting_started/examples/vllm-integration/vllmv1-lmcache-mp-integration": "../../../deployment/integrations/lmcache/vllmv1-lmcache-mp-integration.html",
+    "python-api-reference/dataproto-structured-object-transfer": "../api-reference/python/dataproto-structured-object-transfer.html",
+    "python-api-reference/ep-backend": "../api-reference/python/ep-backend.html",
+    "python-api-reference/mooncake-store": "../api-reference/python/mooncake-store.html",
+    "python-api-reference/transfer-engine": "../api-reference/python/transfer-engine.html",
+    "http-api-reference/http-service": "../api-reference/http/http-service.html",
+    "design/transfer-engine/cpp-api": "../../api-reference/cpp/transfer-engine.html",
+    "design/transfer-engine/efa_transport": "transport/efa_transport.html",
+    "design/transfer-engine/ascend_transport": "transport/ascend_transport.html",
+    "design/transfer-engine/ascend_direct_transport": "transport/ascend_direct_transport.html",
+    "design/transfer-engine/kunpeng_ub_transport": "transport/kunpeng_ub_transport.html",
+    "design/transfer-engine/sunrise_link_transport": "transport/sunrise_link_transport.html",
+    "design/transfer-engine/flagcx_transport": "transport/flagcx_transport.html",
+    "design/transfer-engine/mpcomm_transport": "transport/mpcomm_transport.html",
+    "design/transfer-engine/heterogeneous_ascend": "transport/heterogeneous_ascend.html",
     "design/tent/cpp-api": "../../api-reference/cpp/tent.html",
-    "design/conductor/indexer-api-design":
-    "../../api-reference/http/conductor-indexer.html",
+    "design/conductor/indexer-api-design": "../../api-reference/http/conductor-indexer.html",
 }
diff --git a/docs/source/deployment/integrations/vllm/disagg-prefill-decode.md b/docs/source/deployment/integrations/vllm/disagg-prefill-decode.md
index 93453080f1..6b02fbce2c 100644
--- a/docs/source/deployment/integrations/vllm/disagg-prefill-decode.md
+++ b/docs/source/deployment/integrations/vllm/disagg-prefill-decode.md
@@ -67,13 +67,21 @@ vllm serve Qwen/Qwen2.5-7B-Instruct \
 **Proxy Server:**
 
 ```bash
-# In vllm root directory.
-python tests/v1/kv_connector/nixl_integration/toy_proxy_server.py \
-  --prefiller-host 192.168.0.2 --prefiller-port 8010 \
-  --decoder-host 192.168.0.3 --decoder-port 8020
+# From a vLLM repository checkout. The proxy lives under examples/ and is
+# not included in the pip wheel.
+python examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \
+  --port 8000 \
+  --prefill http://192.168.0.2:8010 8998 \
+  --decode http://192.168.0.3:8020
 ```
 
-> NOTE: The Mooncake Connector currently uses the proxy from nixl_integration. This will be replaced with a self-developed proxy in the future.
+> NOTE: `MooncakeConnector` requires a router that generates a `transfer_id`
+> and forwards the prefiller bootstrap address to the decoder
+> ([vllm-project/vllm#31034](https://github.com/vllm-project/vllm/pull/31034)).
+> The toy proxy under `tests/v1/kv_connector/nixl_integration/` does not
+> implement this contract: outputs stay correct, but KV caches are silently
+> recomputed on the decoder instead of transferred. The bootstrap port must
+> match the prefiller's `VLLM_MOONCAKE_BOOTSTRAP_PORT` (default: 8998).
 
 Now you can send requests to the proxy server through port 8000.
 
diff --git a/docs/source/deployment/integrations/vllm/kv-cache-storage.md b/docs/source/deployment/integrations/vllm/kv-cache-storage.md
index 53b5f7a50c..9dd33f22b2 100644
--- a/docs/source/deployment/integrations/vllm/kv-cache-storage.md
+++ b/docs/source/deployment/integrations/vllm/kv-cache-storage.md
@@ -135,8 +135,8 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct \
 Proxy:
 
 ```shell
-python examples/disaggregated/disaggregated_serving/mooncake_connector/mooncake_connector_proxy.py \
-    --prefill http://192.168.0.2:8100 \
+python examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \
+    --prefill http://192.168.0.2:8100 50052 \
     --decode http://192.168.0.3:8200
 ```
 
diff --git a/docs/source/deployment/integrations/vllm/vllm-mooncakestoreconnector.md b/docs/source/deployment/integrations/vllm/vllm-mooncakestoreconnector.md
index 8517cb5de8..48af7deff7 100644
--- a/docs/source/deployment/integrations/vllm/vllm-mooncakestoreconnector.md
+++ b/docs/source/deployment/integrations/vllm/vllm-mooncakestoreconnector.md
@@ -123,8 +123,8 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct \
 Proxy:
 
 ```shell
-python examples/disaggregated/disaggregated_serving/mooncake_connector/mooncake_connector_proxy.py \
-    --prefill http://192.168.0.2:8100 \
+python examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \
+    --prefill http://192.168.0.2:8100 50052 \
     --decode http://192.168.0.3:8200
 ```
 
diff --git a/docs/source/deployment/kv-cache-sharing-and-isolation.md b/docs/source/deployment/kv-cache-sharing-and-isolation.md
index cb7706f166..79d172a6c3 100644
--- a/docs/source/deployment/kv-cache-sharing-and-isolation.md
+++ b/docs/source/deployment/kv-cache-sharing-and-isolation.md
@@ -123,7 +123,7 @@ Use a new namespace whenever cache compatibility may have changed, including cha
 
 Mooncake tenant configuration is independent of the framework-level model, release, and request namespaces. When the master is started with `--enable_multi_tenants=true`, the client `tenant_id` selects a tenant-scoped object namespace and the master applies that tenant's quota during admission.
 
-Use the same `tenant_id` for framework instances that should share one quota and tenant namespace. See [Tenant Quota Management](mooncake-store-deployment-guide.md#tenant-quota-management) for configuration details.
+Use the same `tenant_id` for framework instances that should share one quota and tenant namespace. See [Multi-Tenant Deployment](multi-tenancy) for configuration details.
 
 ## Operational Checklist
 
diff --git a/docs/source/deployment/mooncake-store-deployment-guide.md b/docs/source/deployment/mooncake-store-deployment-guide.md
index 640aec3c2e..b1434740ef 100644
--- a/docs/source/deployment/mooncake-store-deployment-guide.md
+++ b/docs/source/deployment/mooncake-store-deployment-guide.md
@@ -13,7 +13,7 @@ This guide covers minimal deployment, and operational tuning of Mooncake Store.
 
 **Metadata Service**: A separate service (etcd, Redis, or HTTP) used by the Transfer Engine for peer discovery and configuration. The master's embedded HTTP metadata server can replace an external etcd/Redis for simple deployments. We also provide a P2P handshake mechanism (`P2PHANDSHAKE`) that enables decentralized metadata management by storing metadata locally on each node, eliminating the need for a centralized service — this is the simplest metadata handshake method and the recommended starting point (see [Quick Start](#quick-start)).
 
-For a detailed design discussion, see the [Mooncake Store Design](../design/mooncake-store.md).
+For a detailed design discussion, see the [Mooncake Store Design](../design/store/mooncake-store.md).
 
 ---
 
@@ -191,6 +191,116 @@ mooncake_master \
 
 ---
 
+### Batch OpLog Snapshot Metrics
+
+The master Prometheus endpoint exposes `ha_snapshot_*` metrics for
+`enable_oplog_snapshot`. They are available without the optional OpLog performance
+metrics build flag. Updates use existing scheduler, reader, and maintenance
+observations; scraping does not read etcd or the object store.
+
+All names in the table have the `ha_snapshot_` prefix:
+
+| Metric suffix | Meaning |
+| --- | --- |
+| `enabled` | Whether the runtime is configured for batch snapshots; legacy mode is 0. |
+| `active` | `enabled` and standby state is connecting, syncing, watching, recovering, or reconnecting. Filter snapshot freshness/capacity alerts on this gauge; it is 0 during promotion, after stop, and after fatal failure. Historical observations and in-flight operation counters remain available. |
+| `latest_present`, `fallback_present`, `count` | Decodable pointers observed locally (0–2); not proof that all referenced artifacts remain intact. |
+| `latest_age_seconds`, `fallback_age_seconds` | Time since the observed descriptor's creation, computed at scrape time. Missing pointers and future timestamps report 0; check `*_present` to distinguish absence. |
+| `bytes`, `chunk_bytes`, `chunk_count` | Size/count of the last fully verified upload or successful snapshot restore. Total bytes include segments, chunks, manifest, and descriptor; they do not measure the whole bucket or imply publication success. |
+| `capture_pause_us` | Last completed pause of standby apply for capture, including chunk encoding/upload while capture is held. |
+| `suffix_batches` | Applied batches in the most recent bootstrap suffix replay attempt. |
+| `catch_up_target_batch`, `catch_up_target_sequence` | Durable cursor observed when capture was released; zero after local apply reaches it. |
+| `applied_batch`, `latest_batch`, `fallback_batch` | Local applied cursor and last observed pointer cursors; compare with the catch-up target and durable batch. |
+| `durable_batch`, `compaction_floor`, `candidate_floor` | Last observed durable batch, reader-visible retention floor, and latest pruning candidate. The floor updates immediately after its CAS, before batch deletion. |
+| `uncompacted_batches` | `max(durable_batch - compaction_floor, 0)`: the logical retained suffix, not a physical etcd key count or database size. Failed deletion can retain additional keys below the floor. |
+| `floor_advances_total`, `lease_lost_total` | Successful floor advances and acquired maintenance leases observed lost before release. A failed publish CAS alone does not prove lease loss. |
+| `gc_orphan_prefixes`, `gc_deleted_prefixes` | Unprotected attempt prefixes found by the last completed GC listing, and how many that sweep deleted. A failure before listing leaves the previous observation. |
+| `operations_total{operation}`, `errors_total{operation}`, `duration_us_total{operation}` | Completed calls, failed calls (including exceptions), and total elapsed microseconds. Operations are `schedule`, `upload`, `bootstrap`, `replay`, `publish`, `gc`, `prune`, and `rebootstrap`. Scheduling decisions past the interval/lifecycle gates and no-op pruning calls are included in completed calls; inspect skip reasons and floor advances for its effect. |
+| `skip_reason{reason}`, `skips_total{reason}` | One-hot most recent skip reason and cumulative skipped decisions. Fixed reasons are `none`, `disabled`, `interval`, `in_flight`, `stopped`, `promotion`, `no_new_batch`, `catch_up`, `lease_busy`, `capture_unavailable`, `no_fallback`, `invalid_pair`, and `floor_ahead`. |
+
+Upload time includes encoding, uploads, and verification. Bootstrap time includes
+restore and suffix replay; rebootstrap also includes the floor recheck and state
+replacement. These durations overlap and should not be added together. For
+example, mean upload duration over five minutes in seconds is:
+
+```promql
+rate(ha_snapshot_duration_us_total{operation="upload"}[5m])
+/ rate(ha_snapshot_operations_total{operation="upload"}[5m]) / 1e6
+```
+
+Current gauges reset for a new standby runtime. Event counters remain cumulative
+for the process; in legacy mode they stop increasing and gauges report
+`enabled=0`, `skip_reason{reason="disabled"}=1`, and zero capacity values. Historical
+counters do not indicate activity in the current mode. Publication, GC, and pruning
+have independent error counters: a GC failure does not turn a committed publication
+into a failure. Pointer observations may lag changes made by another standby until
+the next scheduler/bootstrap read.
+
+---
+
+### Batch OpLog Capacity Operations
+
+Batch pruning removes keys, but etcd MVCC history and backend files require
+separate compaction and defragmentation. Mooncake does not run these operations.
+The snapshot `compaction_floor` is a **batch ID**, not an etcd revision.
+
+Before enabling pruning through `enable_oplog_snapshot`, deploy compaction-floor
+rebootstrap support to every electable standby; older binaries cannot follow a
+pruned log. Verify shared durable snapshot storage and two distinct, readable
+latest/fallback snapshots, with matching descriptor/manifest cursors and
+`latest.last_included_batch_id > fallback.last_included_batch_id`. Pointer presence
+alone is insufficient. The runtime revalidates both snapshots before pruning;
+rehearse cold restore and promotion before rollout.
+
+Configure `--quota-backend-bytes` for measured history growth and disk headroom.
+For auto-compaction, `--auto-compaction-mode=periodic --auto-compaction-retention=1h`
+is an example; choose retention for all watch/revision consumers and keep member
+configuration consistent. Monitor each member's `dbSize`, `dbSizeInUse`, quota
+utilization and free disk space. Increasing quota does not replace cleanup.
+
+For Mooncake alerts, use `ha_snapshot_active=1` and the metrics described above.
+Snapshot storage outages stall new baselines and pruning; GC failures retain
+orphan artifacts. These failures retain recovery data safely but grow storage
+until availability is at risk. The logical retained suffix does not include
+undeleted keys below the floor. Never lower the floor or manually delete batch
+keys/pointers to clear a capacity alarm.
+
+Use your deployment's TLS/authentication options. Before and after maintenance,
+save these checks; `$ENDPOINTS` lists all members:
+
+```bash
+etcdctl --endpoints="$ENDPOINTS" member list -w json
+etcdctl --endpoints="$ENDPOINTS" endpoint health
+etcdctl --endpoints="$ENDPOINTS" endpoint status -w json
+etcdctl --endpoints="$ENDPOINTS" alarm list
+```
+
+Confirm healthy quorum and identify the leader. Select `$REVISION` from a successful
+linearizable read, respecting required history; with mutations quiesced, the current
+revision can be used for emergency reclamation. Compact once, then defragment one
+member at a time, healthy followers first and leader last. `$MEMBER` must name one
+endpoint. Defrag blocks that member; recheck health/quorum between members and stop
+if degraded. Compare sizes before/after rather than relying only on exit status.
+
+```bash
+etcdctl --endpoints="$MEMBER" compact "$REVISION" --physical
+etcdctl --endpoints="$MEMBER" defrag  # Repeat separately for each member.
+```
+
+For `NOSPACE`: stop/limit mutations → compact → defrag each member → confirm space
+below quota on every member → `etcdctl --endpoints="$ENDPOINTS" alarm disarm` →
+repeat checks and verify a controlled write/read → gradually restore traffic.
+Health probes requiring a commit may fail under the alarm; inspect member status
+as well. After writer fail-stop, Mooncake may need master restart/re-election;
+verify acknowledged data and promotion readiness before resuming load.
+
+See the etcd [maintenance](https://etcd.io/docs/v3.5/op-guide/maintenance/) and
+[configuration](https://etcd.io/docs/v3.5/op-guide/configuration/) guides for details.
+Capacity test commands and evidence are documented in
+`mooncake-store/tests/e2e/readme.md` under “Batch OpLog capacity tests”.
+
+---
+
 ### Tiered Storage with SSD Offload — Cost-Effective Capacity
 
 Extends the cache pool from DRAM to SSD while keeping normal reads and writes on the distributed memory path. With `--enable_offload=true`, completed memory writes are queued for asynchronous SSD persistence through the master control plane. Set `--offload_on_evict=true` to defer that SSD write until the memory eviction path selects an object for reclamation. When `--promotion_on_hit=true`, SSD-only objects can be promoted back to DRAM after repeated reads; admission is gated by `--promotion_admission_threshold`.
@@ -262,25 +372,47 @@ HA leadership and metadata replication are configured separately:
 
 - The HA coordinator elects the active master. Configure it with `--enable_ha`, `--ha_backend_type`, `--ha_backend_connstring`, and `--cluster_id`. For `ha_backend_type=etcd`, legacy `--etcd_endpoints` is used only when `--ha_backend_connstring` is empty.
 - The optional batch-record OpLog persists metadata mutations so standby masters can catch up and later be promoted. Enable it explicitly with `--enable_oplog=true`; it is disabled by default and requires `ha_backend_type=etcd` and a build with `STORE_USE_ETCD`.
+- The optional standby-generated batch OpLog snapshot path is enabled with `--enable_oplog_snapshot=true` together with `--enable_oplog=true`. It uses the batch snapshot provider/coordinator and does not use the legacy catalog snapshot manager. Startup fails when the required etcd, cluster ID, object-store, or chunk configuration is invalid; a temporary upload failure leaves OpLog apply running for a later attempt.
 
 
 - `--enable_oplog`: Enable the primary OpLog writer and standby reader. Defaults to `false`.
+- `--enable_oplog_snapshot`: Enable standby-generated snapshots for batch OpLog recovery. Defaults to `false`; requires `enable_oplog=true`, HA with etcd, a valid snapshot object store, and a persistent `MOONCAKE_SNAPSHOT_LOCAL_PATH` when using `local`.
+- With `enable_oplog_snapshot=true`, each successful publication also attempts batch OpLog pruning under the same maintenance lease. Pruning requires two independently validated snapshots: it publishes a monotonic `compaction_floor` at the fallback snapshot's batch ID before deleting covered batches. The first snapshot does not prune. GC or pruning failures keep the published snapshot successful; failed deletions can be retried after a later successful publication.
+- Before enabling this mode, every standby that may be promoted must support compaction-floor rebootstrap. Once pruning has started, rollback requires a binary that understands the batch snapshot and floor protocol. This maintenance does not perform etcd MVCC compaction/defragmentation or delete legacy snapshot/OpLog data.
+- `--snapshot_chunk_object_count`: Maximum objects written to one batch OpLog snapshot chunk. Defaults to `1000000`; must be greater than zero when `enable_oplog_snapshot=true`.
 - `--oplog_poll_interval_ms`: Base polling and retry delay for the batch standby, in milliseconds.
 - `--oplog_batch_max_entries`: Maximum number of entries admitted to an ordered batch. Defaults to `1024`.
 - `--batch_oplog_retry_timeout_sec`: Maximum consecutive retryable batch-standby failure window in seconds (default `180`).
 
-For snapshot-based standby bootstrap, also configure:
+For legacy catalog snapshot-based standby bootstrap, configure:
 
 - `--enable_snapshot_restore` (bool, default `false`): Enable standby to bootstrap from the latest snapshot at startup.
 - `--snapshot_object_store_type` (str): Snapshot object store type: `local` or `s3`.
 - `--snapshot_catalog_store_type` (str): Snapshot catalog store type: `embedded` (default) or `redis`.
 
+For the new batch OpLog snapshot path, configure:
+
+```yaml
+enable_ha: true
+ha_backend_type: "etcd"
+enable_oplog: true
+enable_oplog_snapshot: true
+snapshot_chunk_object_count: 1000000
+snapshot_interval_seconds: 600
+snapshot_object_store_type: "local"
+```
+
+The new path stores immutable artifacts below a cluster-specific batch OpLog
+snapshot root. It restores `latest`, then `fallback`, then a proven complete
+OpLog and replays only the suffix after the snapshot cursor. It remains
+non-serving if recovery cannot prove a complete state.
+
 ### Standby Bootstrap
 
 When a Standby starts, it follows this sequence:
 
-1. **Snapshot Bootstrap** (if `enable_snapshot_restore=true`):
-   - Load the latest snapshot from the configured catalog and object store.
+1. **Snapshot Bootstrap** (if `enable_snapshot_restore=true` for legacy catalog snapshots, or `enable_oplog_snapshot=true` for batch OpLog snapshots):
+   - Legacy mode loads the latest snapshot from the configured catalog and object store. Batch OpLog mode loads the latest/fallback descriptor and manifest directly from the batch snapshot control keys.
    - Rebuild object metadata and segment state from the snapshot baseline.
 2. **OpLog Catch-up**:
    - Start from the snapshot's `last_included_seq` (or from 1 if no snapshot).
@@ -304,8 +436,11 @@ When the Primary fails, the Standby is promoted through the following steps:
    - `applied_seq_id`: The latest applied OpLog sequence ID.
    - `objects`: All object metadata from the in-memory store.
    - `segments`: All segment registry entries.
-4. **State Restoration**: The new Primary restores its state from the `PromotionContext`, populating metadata shards and the segment manager.
-5. **Invalid Endpoint Filtering**: During restoration, any replica endpoints that correspond to segments no longer in the registry are automatically filtered out from `GetReplicaList` results.
+4. **State Restoration**: The new Primary restores and validates the complete `PromotionContext`, populating metadata shards and the segment manager. A context with zero objects and segments still passes through restoration so that unsupported recovery modes cannot bypass validation.
+5. **Serving Gate**: The supervisor revalidates leadership and exposes the RPC service only after restoration succeeds. Promotion, restoration, or leadership validation failure leaves `service_ready=false`, keeps data endpoints unavailable, and releases leadership. Failure to release leadership does not make the candidate serviceable.
+6. **Invalid Endpoint Filtering**: During restoration, any replica endpoints that correspond to segments no longer in the registry are automatically filtered out from `GetReplicaList` results.
+
+This fail-closed behavior is intentional. Older versions could log a restoration error and continue serving from empty or partially restored metadata. That behavior was a correctness bug, not a supported availability fallback: the serving state could disagree with the durable OpLog and poison later recovery attempts. Mooncake does not automatically discard snapshots, OpLog records, or metadata after a recovery error.
 
 ### Example: HA Deployment with etcd
 
@@ -319,9 +454,10 @@ cluster_id: "mooncake_cluster"
 enable_oplog: true
 oplog_poll_interval_ms: 1000
 oplog_batch_max_entries: 1024
-enable_snapshot: true
+enable_oplog_snapshot: true
+snapshot_chunk_object_count: 1000000
+snapshot_interval_seconds: 600
 snapshot_object_store_type: "local"
-snapshot_catalog_store_type: "embedded"
 rpc_port: 50051
 ```
 
@@ -335,9 +471,10 @@ cluster_id: "mooncake_cluster"
 enable_oplog: true
 oplog_poll_interval_ms: 1000
 oplog_batch_max_entries: 1024
-enable_snapshot_restore: true
+enable_oplog_snapshot: true
+snapshot_chunk_object_count: 1000000
+snapshot_interval_seconds: 600
 snapshot_object_store_type: "local"
-snapshot_catalog_store_type: "embedded"
 rpc_port: 50052
 ```
 
@@ -357,6 +494,18 @@ mooncake_master --config_path=primary.yaml
 mooncake_master --config_path=standby.yaml
 ```
 
+### Recovery from Unusable HA State
+
+First repair temporary backend, configuration, or snapshot-access failures and restart the affected Standby. If the recovery history is confirmed unusable and losing all cached metadata is acceptable, start a new empty cluster explicitly:
+
+1. Stop every Primary and Standby process that uses the old `cluster_id`.
+2. Confirm that losing the old cache metadata and snapshots is acceptable.
+3. Change every node to a new, previously unused `cluster_id`.
+4. Start the new cluster and allow applications to repopulate the cache.
+5. Keep the old namespace for diagnosis, then remove it separately after confirming that no old process can reconnect.
+
+Using a new `cluster_id` isolates the new cluster from the old OpLog, durable prefix, producer view, and snapshot namespace. Do not delete individual recovery keys or reuse the old `cluster_id` while any old process may still run. There is no automatic reset-on-restore-failure option.
+
 ### Resetting a Legacy OpLog Namespace
 
 The batch-only implementation does not migrate or read older per-entry OpLog data. Reusing a namespace that contains legacy `latest`, numeric entry, or snapshot sidecar keys is rejected.
@@ -386,10 +535,8 @@ When tenant quota is enabled, `/metrics` also includes per-tenant quota gauges a
 
 - `mooncake_tenant_quota_requested_bytes{tenant_id}`
 - `mooncake_tenant_quota_effective_bytes{tenant_id}`
-- `mooncake_tenant_quota_used_bytes{tenant_id}`
-- `mooncake_tenant_quota_reserved_bytes{tenant_id}`
-- `mooncake_tenant_quota_committed_count{tenant_id}`
-- `mooncake_tenant_quota_metadata_object_count{tenant_id}`
+- `mooncake_tenant_quota_charged_bytes{tenant_id}`
+- `mooncake_tenant_quota_admission_closed{tenant_id}`
 - `mooncake_tenant_quota_over_quota{tenant_id}`
 - `mooncake_tenant_quota_explicit_policy{tenant_id}`
 - `mooncake_tenant_quota_reject_total{tenant_id,reason}`
@@ -402,78 +549,11 @@ When tenant quota is enabled, `/metrics` also includes per-tenant quota gauges a
 
 ## Tenant Quota Management
 
-Tenant quota admission is disabled by default. Enable strict multi-tenant mode on the master when you want memory writes admitted against connector-managed per-tenant quota:
-
-```bash
-mooncake_master \
-  --enable_multi_tenants=true \
-  --tenant_quota_connector_type=file \
-  --tenant_quota_connector_uri=/etc/mooncake/tenant_quotas.yaml
-```
-
-You can also store the same YAML policy in etcd when Mooncake Store is built with `STORE_USE_ETCD=ON`:
-
-```bash
-mooncake_master \
-  --enable_multi_tenants=true \
-  --cluster_id=mooncake_cluster \
-  --tenant_quota_connector_type=etcd \
-  --tenant_quota_connector_uri=127.0.0.1:2379
-```
-
-The etcd connector stores the policy at `mooncake-store/<cluster_id>/tenant_quota_policy`. If the key does not exist, the master starts with an empty policy so the first tenant policy can be created through the admin API. It shares the process-wide store etcd client used by HA/oplog, so if HA or oplog also uses etcd, `tenant_quota_connector_uri` must match those etcd endpoints. The policy must use schema version `1`; tenant names must be non-empty, unique, must not start with `_`, and must not contain NUL or control characters; quotas must be positive integers with optional `B`, `KB`, `MB`, `GB`, or `TB` units:
-
-```yaml
-version: 1
-
-tenants:
-  - name: tenant-a
-    quota: 200GB
-
-  - name: tenant-b
-    quota: 500GB
-```
-
-When strict multi-tenant mode is enabled, write requests must include a registered tenant. The `default` tenant is not special unless it is explicitly registered in the connector policy.
-
-The same HTTP port used for metrics exposes the tenant quota admin API:
-
-```bash
-# List tenant quota snapshots
-curl -s http://<master_host>:9003/api/v1/tenant_quotas
-
-# Query one tenant
-curl -s "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a"
-
-# Upsert an explicit policy. Explicit tenant policies must be positive.
-curl -s -X PUT "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a" \
-  -H 'Content-Type: application/json' \
-  -d '{"requested_quota_bytes":2147483648}'
-
-# Delete an explicit policy. The tenant must not own objects or quota usage.
-curl -s -X DELETE "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a"
-```
-
-Each tenant quota snapshot returns:
-
-```json
-{
-  "success": true,
-  "data": {
-    "tenant_id": "tenant-a",
-    "requested_quota_bytes": 2147483648,
-    "effective_quota_bytes": 2147483648,
-    "used_bytes": 0,
-    "reserved_bytes": 0,
-    "committed_count": 0,
-    "metadata_object_count": 0,
-    "over_quota": false,
-    "has_explicit_policy": true
-  }
-}
-```
+:::{toctree}
+:maxdepth: 1
 
-In HA mode, quota admin requests are served only by the active master service. Standby, candidate, or inactive services return HTTP 503. If strict multi-tenant mode is disabled, the quota admin API returns HTTP 409 with `UNAVAILABLE_IN_CURRENT_MODE`. Deleting a non-empty tenant returns HTTP 409 with `TENANT_NOT_EMPTY`.
+Multi-Tenant Deployment <multi-tenancy>
+:::
 
 ---
 
@@ -483,8 +563,9 @@ In HA mode, quota admin requests are served only by the active master service. S
 - Start with default eviction settings; adjust `--eviction_high_watermark_ratio` and `--eviction_ratio` based on memory pressure and object churn.
 - Use `/metrics/summary` during bring-up; integrate `/metrics` with Prometheus/Grafana for production.
 - For detailed SSD offload configuration (storage backends, eviction policies, io_uring), see the [SSD Offload guide](ssd/ssd-offload).
+- For OSS offload configuration, see the [OSS Offload guide](oss-offload).
 - For NVMe-oF SSD pool configuration see the [NVMe-oF SSD Pool Deployment Guide](ssd/nvmf-ssd-deployment-guide)
-- For experimental 3FS (USRBIO) integration as a persistent storage backend, see the [3FS USRBIO Plugin guide](../getting_started/plugin-usage/3FS-USRBIO-Plugin).
+- For the experimental HF3FS USRBIO adapter used by descriptor-based DFS replicas, see the [HF3FS USRBIO adapter guide](../getting_started/plugin-usage/3FS-USRBIO-Plugin).
 - For detailed monitoring and observation see [Observability](../getting_started/observability)
 
 :::{toctree}
@@ -493,7 +574,8 @@ In HA mode, quota admin requests are served only by the active master service. S
 
 KV Cache Sharing and Isolation<kv-cache-sharing-and-isolation>
 SSD Storage<ssd/index>
-HF3FS Plugin (Experimental)<../getting_started/plugin-usage/3FS-USRBIO-Plugin>
+OSS Offload<oss-offload>
+HF3FS USRBIO Adapter (Experimental)<../getting_started/plugin-usage/3FS-USRBIO-Plugin>
 ../getting_started/observability
 :::
 
@@ -554,15 +636,21 @@ master publisher <mooncake-store-master-publisher>` reference.
 | `--kv_events_bind_endpoint` | empty | ZMQ PUB bind endpoint, for example `tcp://0.0.0.0:5557`; required when enabled |
 | `--kv_events_backend_id` | empty | Cache-owner identity emitted as `backend_id`; required when enabled |
 | `--kv_events_emit_legacy_compat` | `true` | Include vLLM/SGLang-compatible aliases such as `type` and `block_hashes` |
-| `--kv_events_emit_object_key` | `true` | Include the Mooncake `object_key`; unparsable sequence hashes are still published when this is enabled |
-| `--kv_events_queue_capacity` | `65536` | Maximum pending events; the publisher drops the oldest event when the queue is full. Set to `0` for an unbounded queue |
+| `--kv_events_emit_object_key` | `true` | Emit the raw Mooncake `object_key`. Setting this to `false` suppresses `stored` and `removed` entirely, since those events then carry no object identity; `cleared` is unaffected |
+| `--kv_events_queue_capacity` | `65536` | Maximum pending events; the publisher drops the oldest event when the queue is full and reserves its sequence number so the loss stays visible. Set to `0` for an unbounded queue |
+
+One master publisher serves one fixed model and parallel context, so the
+remaining flags below are emitted verbatim in every event envelope. Empty
+strings and `--kv_events_block_size=0` are encoded as nil.
 
-The legacy flags `--kv_events_model_name`, `--kv_events_tenant_id`,
-`--kv_events_additional_salt`, `--kv_events_lora_name`,
-`--kv_events_block_size`, and `--kv_events_dp_rank` are retained for config
-compatibility but are not emitted in event payloads. Supply model, block-size,
-hash-namespace, LoRA, and data-parallel metadata when registering the publisher
-with the indexer; each event carries its object's tenant ID.
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--kv_events_model_name` | empty | Emitted as `model_name` |
+| `--kv_events_additional_salt` | empty | Emitted as `additional_salt`; the hash namespace this publisher's keys belong to |
+| `--kv_events_lora_name` | empty | Emitted as `lora_name` |
+| `--kv_events_block_size` | `0` | Emitted as `block_size` |
+| `--kv_events_dp_rank` | `0` | Emitted as `dp_rank`, both per event and in the batch trailer |
+| `--kv_events_tenant_id` | `default` | Accepted for configuration compatibility but not emitted. Every event carries the tenant of the Store operation that produced it |
 
 ### HTTP Metadata Server (Embedded)
 
@@ -647,6 +735,7 @@ mooncake_master \
 |------|---------|-------------|
 | `--default_kv_lease_ttl` | `10000` ms | Lease TTL for KV objects. Supports `5000ms`, `5s`, `30m`, `1h` |
 | `--default_kv_soft_pin_ttl` | `1800000` ms | Soft pin TTL (30 min) |
+| `--max_kv_soft_pin_ttl` | `86400000` ms | Maximum request-level soft pin TTL (24 h) |
 | `--allow_evict_soft_pinned_objects` | `true` | Allow evicting soft-pinned objects |
 | `--eviction_ratio` | `0.05` | Fraction evicted at high watermark |
 | `--eviction_high_watermark_ratio` | `0.90` | Usage ratio triggering eviction |
@@ -659,6 +748,7 @@ mooncake_master \
 | `--enable_multi_tenants` | `false` | Enable strict tenant registration and per-tenant memory quota admission |
 | `--tenant_quota_connector_type` | `file` | Tenant quota policy connector type: `file` or `etcd` when built with `STORE_USE_ETCD=ON` |
 | `--tenant_quota_connector_uri` | empty | Connector URI; for `file`, the writable YAML policy path; for `etcd`, the endpoints string |
+| `--tenant_eviction_high_watermark_ratio` | `0.90` | Usage ratio of a tenant's own effective quota that triggers background eviction for that tenant; `0` disables it |
 
 ### High Availability
 
@@ -671,6 +761,8 @@ mooncake_master \
 | `--etcd_endpoints` | empty | Backward-compatible etcd HA endpoints, used only for `ha_backend_type=etcd` when `--ha_backend_connstring` is empty |
 | `--cluster_id` | `mooncake_cluster` | Cluster ID for HA persistence |
 | `--enable_oplog` | `false` | Enable the primary OpLog writer and standby reader; currently requires `enable_ha=true` and `ha_backend_type=etcd` |
+| `--enable_oplog_snapshot` | `false` | Enable standby-generated batch OpLog snapshots; requires batch OpLog, HA/etcd, valid object-store configuration, and persistent local snapshot storage when applicable |
+| `--snapshot_chunk_object_count` | `1000000` | Maximum objects per batch OpLog snapshot chunk; must be positive when the new snapshot path is enabled |
 | `--oplog_poll_interval_ms` | `1000` | Base polling and retry delay for the batch standby, in milliseconds |
 | `--oplog_batch_max_entries` | `1024` | Maximum number of entries admitted to an ordered batch |
 | `--batch_oplog_retry_timeout_sec` | `180` | Maximum consecutive retryable batch-standby failure window in seconds |
@@ -744,14 +836,247 @@ When `--offload_on_evict=true` is active, each `BatchEvict` cycle can queue at m
 
 When `--allocation_strategy=cxl` is set alongside `--enable_cxl=true`, the master preferentially allocates new objects on CXL memory.
 
-### DFS Storage
+### Legacy Shared-filesystem `DISK` Persistence
+
+The older shared-filesystem persistence path remains available independently
+of descriptor-based DFS:
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--root_fs_dir` | empty | Legacy DFS persistence directory; do not use with SSD offload |
-| `--global_file_segment_size` | `INT64_MAX` (unlimited) | Max available space for DFS segments; default does not cap DFS usage |
+| `--root_fs_dir` | empty | Enable legacy `DISK` replicas under `<root_fs_dir>/<cluster_id>`. The path must resolve to the same shared filesystem location on every participating client. |
+| `--global_file_segment_size` | `INT64_MAX` (unlimited) | Declared legacy file capacity used by master usage metrics. It does not configure descriptor-based DFS shard files. |
+
+With `--root_fs_dir` set, the master adds a legacy `DISK` replica to each new
+object and clients write it asynchronously. This path is distinct from both
+client-owned `LOCAL_DISK` SSD offload and descriptor-based `DFS` replicas. Do
+not combine `--root_fs_dir` with `--enable_offload=true`; configure real-client
+SSD offload with `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` instead.
+
+(dfs-storage)=
+### Descriptor-based DFS Storage
+
+```{warning}
+**Work in progress.** Descriptor-based DFS is intended for development and
+evaluation only. It is not production-ready and is not covered by Mooncake
+Store's general fault-tolerance, HA continuity, durability, or multi-tenant
+guarantees.
+```
+
+Mooncake Store can place an additional replica in a shared distributed
+filesystem. The master allocates aligned ranges in pre-created shard files and
+publishes a descriptor containing the shard, offset, and object size. Clients
+use that descriptor to access the same files through either regular POSIX I/O
+or the HF3FS USRBIO adapter.
+
+DFS replicas are separate from `LOCAL_DISK` SSD-offload replicas. They do not
+use the legacy `--root_fs_dir` persistence path or the master's asynchronous
+offload task queue.
+
+```{note}
+DFS allocator state is not yet restored after a master restart or HA leader
+failover. Do not enable descriptor-based DFS in a deployment that requires
+master recovery, HA continuity, or multiple tenants. See the complete list of
+limitations below.
+```
+
+#### Master configuration
+
+Enable the DFS allocator in the master process and select a shared root and
+shard layout. For example, to use HF3FS:
+
+```bash
+export MOONCAKE_ENABLE_DFS=1
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
+
+mooncake_master [other master arguments]
+```
+
+At startup, the master creates `MOONCAKE_DFS_SHARD_COUNT` shard files and
+preallocates each file to `MOONCAKE_DFS_SHARD_CAPACITY`. The example therefore
+configures 256 GiB of total logical shard capacity (`64 * 4 GiB`). Ensure the
+shared filesystem has sufficient capacity; whether all backing space is
+reserved immediately depends on the selected filesystem adapter.
+
+The `hf3fs` adapter requires Mooncake to be built with `USE_3FS=ON`. Use
+`MOONCAKE_DFS_FS_ADAPTER=posix` for development and integration testing on a
+regular shared filesystem.
 
-`--root_fs_dir` is a legacy persistence parameter and is expected to be replaced as the distributed filesystem path is refactored. For SSD offload, configure `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` on each real client instead.
+#### Client configuration
+
+Every client that may read or write a DFS replica must initialize
+`FileStorage` and select the distributed backend. Use an absolute DFS root path;
+the root string, shard count, shard capacity, and alignment must match the
+master configuration. Select an adapter that can access the same underlying
+shared files; the examples use the same adapter in every process.
+
+```bash
+export MOONCAKE_OFFLOAD_ENABLED=true
+export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=distributed_storage_backend
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/data/file_storage
+export MOONCAKE_MASTER=127.0.0.1:50051
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
+
+python -m mooncake.mooncake_store_service
+```
+
+For a programmatic Python client, pass `enable_ssd_offload=True` to `setup()`
+instead of `MOONCAKE_OFFLOAD_ENABLED`. Programmatic setup still reads the
+backend-specific `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR` and
+`MOONCAKE_DFS_*` variables shown above; only the launcher-level setup fields are
+supplied as Python arguments. The
+`MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` directory must already exist and be an
+absolute, writable, non-symlink directory. DFS shard data is stored under
+`MOONCAKE_DFS_ROOT_DIR`; the FileStorage path is still required for client
+initialization because the shared `FileStorageConfig` validates it even when
+the selected backend stores data in the DFS root.
+
+Native C++ clients must initialize a `DistributedStorageBackend` with the same
+DFS layout and attach it to the client with `SetDfsStorageBackend()` before
+issuing DFS reads or writes. Reads and writes use the DFS descriptor carried by
+the current query or start-operation response; no client-side descriptor cache
+is required.
+
+#### DFS configuration reference
+
+| Variable | Scope | Default | Description |
+|----------|-------|---------|-------------|
+| `MOONCAKE_ENABLE_DFS` | Master | `false` | Enable master-side DFS allocation. `MOONCAKE_DFS_ENABLED` is accepted as a compatibility fallback. |
+| `MOONCAKE_DFS_ROOT_DIR` | Master and clients | `/mnt/3fs/mooncake` | Absolute shared shard root; use the same path string in every process. Falls back to `MOONCAKE_DISTRIBUTED_ROOT_DIR`. |
+| `MOONCAKE_DFS_FS_ADAPTER` | Master and clients | `hf3fs` | Filesystem adapter: `hf3fs` or `posix`. Falls back to `MOONCAKE_DISTRIBUTED_FS_TYPE`. |
+| `MOONCAKE_DFS_SHARD_COUNT` | Master and clients | `64` | Initial shard count. The master also discovers existing contiguous shard files at startup; running clients open added shards on demand. |
+| `MOONCAKE_DFS_SHARD_CAPACITY` | Master and clients | `4294967296` (4 GiB) | Logical file capacity of each shard in bytes. Each object is allocated wholly within one shard. |
+| `MOONCAKE_DFS_ALIGNMENT` | Master and clients | `4096` | Allocation alignment in bytes; must be a power of two and divide the shard capacity. |
+| `MOONCAKE_DFS_SINGLE_TENANT` | Master and clients | `true` | Currently must remain `true`. |
+| `MOONCAKE_DFS_EVICTION_ENABLED` | Master | `true` | Enable DFS allocator eviction. |
+| `MOONCAKE_DFS_EVICTION_HIGH_WATERMARK` | Master | `0.9` | Usage ratio that triggers eviction. |
+| `MOONCAKE_DFS_EVICTION_LOW_WATERMARK` | Master | `0.7` | Usage ratio targeted by an eviction cycle. |
+| `MOONCAKE_DFS_DEFERRED_FREE_SECONDS` | Master | `30` | Delay before a freed shard range may be reused. |
+| `MOONCAKE_DFS_EVICTION_CHECK_INTERVAL` | Master | `5` | Eviction check interval in seconds. |
+
+#### Growing DFS capacity online
+
+The default shard allocator supports adding shard files while the master and
+clients remain running. Use the master's existing HTTP admin listener:
+
+```bash
+curl http://127.0.0.1:9003/api/v1/dfs/shard_count
+curl -X PUT http://127.0.0.1:9003/api/v1/dfs/shard_count \
+  -H 'Content-Type: application/json' -d '{"shard_count": 128}'
+```
+
+Both requests return the current count, for example
+`{"success":true,"shard_count":128}`. A PUT sets the desired **total** count,
+not the number to add. Repeating the current count succeeds without changing
+anything; shrinking, non-integer values, and non-positive counts return HTTP
+400. DFS-disabled masters and concurrent expansion requests return HTTP 409;
+unavailable or standby services return HTTP 503. Filesystem preparation runs
+off the HTTP I/O threads, so health checks and other administration remain
+available while an expansion is pending.
+
+Upgrade the master and every DFS client to a version supporting online shard
+expansion before increasing capacity. An already running upgraded client can
+open a new shard from its descriptor even when its initial
+`MOONCAKE_DFS_SHARD_COUNT` is smaller. Older binaries reject those descriptors.
+Every process must still use the same shared root, adapter, shard capacity, and
+alignment. Provision sufficient backing filesystem space before expanding;
+changing the root or per-shard capacity online is unsupported.
+
+Only one active master may manage a DFS root. Do not create, rename, truncate,
+or remove its shard files outside that master. Clients do not create shard
+files during initialization; they open them only from published descriptors.
+
+The allocator prepares new files and allocation state before publishing the
+expanded shard set. Existing paths and allocated ranges remain unchanged,
+including when the shard index gains another decimal digit. Allocation, reads,
+writes, deferred frees, and eviction continue to use ready shards. A failed
+expansion leaves the published shard count unchanged.
+
+On startup, the master discovers the contiguous existing shard layout and uses
+at least the configured count. Duplicate indices, missing intermediate shards,
+and unexpected file sizes are rejected rather than silently changing the
+layout. This preserves **capacity**, not cached key metadata or allocation
+ownership: DFS allocator recovery, snapshots, and HA remain subject to the
+limitations below. Do not treat online expansion as a data durability guarantee.
+
+#### Requesting and accessing DFS replicas
+
+Callers request DFS placement through `ReplicateConfig`:
+
+```python
+from mooncake.store import ReplicateConfig
+
+config = ReplicateConfig()
+config.replica_num = 1
+config.dfs_replica_num = 1
+store.put("key", b"value", config)
+```
+
+`dfs_replica_num` may currently be `0` or `1`. A DFS replica must be requested
+with at least one memory replica (`replica_num >= 1`), so DFS-only placement is
+not supported.
+
+Allocation first tries the key's hash-selected DFS shard, then tries other
+ready shards if that shard has no suitable extent. This lets new shards accept
+writes even when older shards are full. `NO_AVAILABLE_HANDLE` means no ready
+shard could satisfy the allocation. A DFS object is never striped across shards.
+The selected shard must have room for the object rounded
+up to `MOONCAKE_DFS_ALIGNMENT`, plus up to one alignment unit of allocator
+padding (`MOONCAKE_DFS_ALIGNMENT - 1` bytes); usable object capacity is
+therefore lower than the shard file's
+logical size.
+
+For `Put`, `BatchPut`, `Upsert`, and `BatchUpsert`, the client writes requested
+memory and NoF replicas, stages device buffers to host memory when necessary,
+and then performs positional DFS writes. A successful request means the
+requested DFS `WriteAt` operations completed. It does **not** imply that an
+additional `fsync` completed. Batch operations isolate failures by key; a
+failed key is revoked without downgrading successful keys.
+
+For a same-size `Upsert`, if either the existing object or the new request has
+a DFS replica, the requested memory, NoF, and DFS replica counts must match the
+existing topology. A different-size update releases the old placement and
+allocates a new topology.
+
+On reads, the master returns the readable replica list through the normal query
+path, and the client selects the first complete replica. If it selects DFS, any
+client configured with the same DFS root and shard layout can issue positional
+reads for that descriptor.
+
+#### Current limitations
+
+- Only the `default` tenant is supported.
+- `dfs_replica_num` must be `0` or `1`, and `replica_num >= 1` is required when
+  it is enabled.
+- C and Rust clients cannot currently request or access descriptor-based DFS:
+  their replication configuration does not expose `dfs_replica_num`, and their
+  setup API cannot initialize the distributed `FileStorage` backend. Use the
+  native C++ or Python/RealClient API.
+- A DFS object must fit in a single shard after alignment and allocator
+  padding; objects are not striped across shards.
+- DFS allocator state is currently in memory. A master restart or HA leader
+  failover does not reconstruct existing DFS allocations, so DFS cannot provide
+  continuity across those events.
+- DFS cannot be enabled with snapshot generation, snapshot restore, oplog
+  recovery, or standby restore until DFS allocator state restoration is
+  implemented.
+- There is currently no background DFS retry queue or configurable
+  asynchronous acknowledgement policy.
+- DFS writes currently have no DFS-specific timeout, request cancellation, or
+  `fsync` durability guarantee.
+
+The older `--root_fs_dir` and `--global_file_segment_size` flags configure the
+legacy `DISK` path described above and are not used by descriptor-based DFS
+replicas.
 
 ### NoF (NVMe-oF SSD Pool)
 
@@ -794,7 +1119,23 @@ allocation_strategy: "local_first"
 
 When enabled, the master applies local-first allocation only for memory replicas with `replica_num == 1`. Explicit `preferred_segment` or `preferred_segments` are tried first; if they are unavailable or full, Mooncake falls back through active hosts in cyclic lexicographic host-id order, starting from the writer host when it has active segments, or otherwise from the next greater active host id. Within the same host, segment names are sorted and rotated by key hash so multiple segments on one host do not always receive the first allocation attempt.
 
-The client derives the host id from `local_hostname` by removing the port. For example, `host-a:50051` and `host-a:50052` map to the same host id, `host-a`. For local-first allocation to work correctly, all writer and store processes on the same physical or logical host must use the same stable, globally unique host part in `local_hostname`. In deployments with multiple NIC IPs, hostname aliases, or container/pod networking, choose one canonical host name or IP and use it consistently across processes on that host. Empty, loopback, and wildcard values such as `localhost`, `127.0.0.1`, `0.0.0.0`, `::1`, and `::` are treated as unknown and do not trigger automatic local-first placement for that client.
+By default, the client derives the host id from `local_hostname` by removing the port. For example, `host-a:50051` and `host-a:50052` map to the same host id, `host-a`. Set `MOONCAKE_HOST_ID` to override this derived value with a stable, globally unique node identifier. The override is read directly by the C++ client, so it applies to every client initialization method. It must be set before creating the client, and all writer and store processes on the same physical or logical host must use the same value. An empty or whitespace-only override falls back to `local_hostname`. Loopback and wildcard values such as `localhost`, `127.0.0.1`, `0.0.0.0`, `::1`, and `::` are treated as unknown and do not trigger automatic local-first placement.
+
+In Kubernetes, keep `MOONCAKE_LOCAL_HOSTNAME` as the routable pod IP for the transfer endpoint and use `spec.nodeName` as the shared placement identity:
+
+```yaml
+env:
+  - name: MOONCAKE_LOCAL_HOSTNAME
+    valueFrom:
+      fieldRef:
+        fieldPath: status.podIP
+  - name: MOONCAKE_HOST_ID
+    valueFrom:
+      fieldRef:
+        fieldPath: spec.nodeName
+```
+
+Apply the same `MOONCAKE_HOST_ID` mapping to every writer and store pod. This separates the per-pod network address from the node-level placement identity, allowing colocated pods with different IPs to match for local-first allocation.
 
 ---
 
@@ -803,7 +1144,7 @@ The client derives the host id from `local_hostname` by removing the port. For e
 
 A client is configured through one of the **methods** introduced in [Start a Store Client](#start-a-store-client), plus a shared family of engine-tuning variables:
 
-- **Method A — Programmatic (`setup()` arguments)**: you pass configuration as explicit Python arguments. `MOONCAKE_*` variables are **not** read in this method.
+- **Method A — Programmatic (`setup()` arguments)**: launcher-level fields are passed as explicit Python arguments instead of being loaded through `MooncakeConfig`. Backend-specific variables read by C++, including `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR` and `MOONCAKE_DFS_*`, still apply.
 - **Method B — Service / Integration (`MOONCAKE_*` + CLI)**: `mooncake.mooncake_store_service` and the vLLM/SGLang connectors read `MOONCAKE_*` environment variables (via `MooncakeConfig`).
 - **Method C — Resource-owning real client (`mooncake_client`)**: configured through `mooncake_client` CLI flags (see the **Method C** subsection below).
 - **Engine runtime tuning (`MC_*`)**: low-level variables read by the C++ Transfer Engine / store client at runtime. They are orthogonal to the above and **apply to all methods**.
@@ -824,14 +1165,14 @@ Arguments of `MooncakeDistributedStore.setup(...)`:
 | `rdma_devices` | str | required | RDMA NIC(s), comma-separated (pass `""` for non-RDMA). **Keyword is `rdma_devices`, not `device_name`** |
 | `master_server_addr` | str | required | Master `host:port`. **Keyword is `master_server_addr`, not `master_server_address`** |
 | `engine` | TransferEngine | `None` | *(advanced)* Reuse an existing Transfer Engine instance instead of creating one |
-| `enable_ssd_offload` | bool | `false` | *(advanced)* Enable client-side SSD offload |
-| `ssd_offload_path` | str | empty | *(advanced)* SSD offload directory |
+| `enable_ssd_offload` | bool | `false` | *(advanced)* Initialize client-side `FileStorage`; required for SSD offload and descriptor-based DFS |
+| `ssd_offload_path` | str | empty | *(advanced)* FileStorage path; with the distributed backend, DFS data uses `MOONCAKE_DFS_ROOT_DIR` |
 | `tenant_id` | str | `default` | *(advanced)* Tenant identifier |
-| `enable_client_http_server` | bool | `false` | Enable the client-side HTTP `/health`, `/metrics`, and `/metrics/summary` endpoints |
+| `enable_client_http_server` | bool | `false` | Enable the client-side HTTP `/health`, `/metrics`, `/metrics/summary`, and `/version` endpoints |
 | `client_http_port` | int | `9300` | Client-side HTTP endpoint port, used only when `enable_client_http_server=true` |
 
 ```{note}
-The first seven arguments have **no Python default** — the C++ defaults are not exposed by the pybind binding, so they must all be supplied (a bare `setup(local_hostname, metadata_server)` raises `TypeError`). The later arguments (`engine`, SSD offload fields, `tenant_id`, and client HTTP endpoint fields) are optional. Also, in Method A the `MOONCAKE_*` variables used by `MooncakeConfig` are ignored; low-level runtime variables such as the `MC_*` engine variables below are still read by the C++ client.
+The first seven arguments have **no Python default** — the C++ defaults are not exposed by the pybind binding, so they must all be supplied (a bare `setup(local_hostname, metadata_server)` raises `TypeError`). The later arguments (`engine`, SSD offload fields, `tenant_id`, and client HTTP endpoint fields) are optional. In Method A, launcher-level `MOONCAKE_*` variables used only by `MooncakeConfig` are ignored. Variables consumed directly by the C++ client, including the FileStorage/DFS backend variables and low-level `MC_*` engine variables below, are still read.
 ```
 
 ### Method B — Service / Integration (`MOONCAKE_*` + CLI)
@@ -855,10 +1196,10 @@ The store service CLI only accepts `--config`, `-D/--define`, `--port`, and `--m
 | `MOONCAKE_GLOBAL_SEGMENT_SIZE` | `global_segment_size` | `3355443200` (3.125 GiB) | DRAM contributed; accepts byte integer **or** suffixed form like `500gb` |
 | `MOONCAKE_LOCAL_BUFFER_SIZE` | `local_buffer_size` | `1073741824` (1 GiB) | Transfer Engine buffer; same parsing as above |
 | `MOONCAKE_LOCAL_HOSTNAME` | `local_hostname` | `localhost` | |
-| `MOONCAKE_OFFLOAD_ENABLED` | `enable_ssd_offload` | `false` | Client-side SSD offload |
-| `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` | `ssd_offload_path` | empty | Offload directory |
+| `MOONCAKE_OFFLOAD_ENABLED` | `enable_ssd_offload` | `false` | Initialize client-side `FileStorage`; required for SSD offload and descriptor-based DFS |
+| `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` | `ssd_offload_path` | empty | FileStorage path; DFS shard data uses `MOONCAKE_DFS_ROOT_DIR` with the distributed backend |
 | `MOONCAKE_TENANT_ID` | `tenant_id` | `default` | Tenant identifier |
-| `MOONCAKE_ENABLE_CLIENT_HTTP_SERVER` | `enable_client_http_server` | `false` | Enable client-side `/health`, `/metrics`, and `/metrics/summary` endpoints |
+| `MOONCAKE_ENABLE_CLIENT_HTTP_SERVER` | `enable_client_http_server` | `false` | Enable client-side `/health`, `/metrics`, `/metrics/summary`, and `/version` endpoints |
 | `MOONCAKE_CLIENT_HTTP_PORT` | `client_http_port` | `9300` | Client-side HTTP endpoint port |
 | `MOONCAKE_CONFIG_PATH` | — | unset | Path to a JSON config file (takes precedence over the variables above) |
 
@@ -927,9 +1268,12 @@ mooncake_client \
 | `--tenant_id` | `default` | Tenant identifier |
 | `--enable_offload` | `false` | Enable client-side SSD offload |
 | `--start_offload_rpc_server` | `true` | Start the offload RPC server for dummy clients |
-| `--enable_http_server` | `false` | Enable client-side `/health`, `/metrics`, and `/metrics/summary` endpoints |
+| `--enable_http_server` | `false` | Enable client-side `/health`, `/metrics`, `/metrics/summary`, and `/version` endpoints |
 | `--http_port` | `9300` | Client-side HTTP endpoint port |
 
+`mooncake_client --version` prints the release version plus the short git hash,
+and the same value is logged at startup.
+
 ### Client HTTP Health and Metrics Endpoint
 
 Each real client can expose its own lightweight HTTP endpoint independently of the master admin HTTP server and the Python store REST API. This endpoint is disabled by default for programmatic clients and `mooncake_store_service`; enable it explicitly when you want to scrape client-local metrics:
@@ -955,9 +1299,18 @@ For `mooncake_store_service`, use `MOONCAKE_ENABLE_CLIENT_HTTP_SERVER=true` and
 | `GET /health` | Client health check |
 | `GET /metrics` | Prometheus-format client metrics |
 | `GET /metrics/summary` | Human-readable client metrics summary |
+| `GET /version` | Client version as JSON (`version` for RPC handshake compatibility, `display_version` for release plus short git hash) |
+
+```bash
+curl http://<client-host>:9300/version
+```
+
+```json
+{"version":"2.0.0","display_version":"0.3.12.post1 (git: f9e8311f)"}
+```
 
 ```{note}
-`MC_STORE_CLIENT_METRIC` controls whether client metrics are collected. If the client HTTP server is enabled but `MC_STORE_CLIENT_METRIC=0`, `/metrics` and `/metrics/summary` return HTTP 503 with `metrics not available`.
+`MC_STORE_CLIENT_METRIC` controls whether client metrics are collected. If the client HTTP server is enabled but `MC_STORE_CLIENT_METRIC=0`, `/metrics` and `/metrics/summary` return HTTP 503 with `metrics not available`. `/health` and `/version` are unaffected.
 ```
 
 ### Engine Runtime Tuning (`MC_*`)
@@ -969,8 +1322,8 @@ The following `MC_*` variables are read directly by the engine/client at runtime
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `MC_RPC_PROTOCOL` | `tcp` | RPC transport protocol between master and clients: `tcp` or `rdma` |
-| `MC_RPC_TIMEOUT_MS` | `30000` | Per-request deadline (ms) for all client→master RPCs. Applies uniformly to every RPC method. A negative value disables the timeout. On expiry the call returns `RPC_TIMEOUT` |
-| `MC_RPC_CONNECT_TIMEOUT_MS` | `30000` | Connection-establishment timeout (ms) for the master RPC client |
+| `MC_RPC_TIMEOUT_MS` | `30000` | Per-request deadline (ms) for client→master RPCs and for store→store SSD offload reads. Applies uniformly to every RPC method. A negative value disables the timeout. On expiry the call returns `RPC_TIMEOUT` |
+| `MC_RPC_CONNECT_TIMEOUT_MS` | `30000` initially; `1000` during HA runtime | Connection-establishment timeout (ms) for the master RPC client and for the store→store SSD offload client. HA clients retain the normal retry budget during initial discovery and configuration, then use one bounded attempt per runtime reconnect because their monitor and heartbeat loops own the retry schedule. An explicit value overrides both defaults. Worth lowering when SSD offload is enabled: an offload read that picks a store which has gone away without deregistering waits this long on each of 3 connect attempts (91 s at the default) before returning a clean miss |
 | `MC_RPC_CLIENT_IO_THREADS` | `min(16, online CPU count)`, minimum `1` | Fallback number of threads and `io_context` instances for each component's RPC client I/O pool. A positive integer overrides the default; invalid values and `0` use the default |
 | `MC_STORE_RPC_CLIENT_IO_THREADS` | `MC_RPC_CLIENT_IO_THREADS` | Store/Master client RPC I/O pool size. This pool is isolated from Transfer Engine traffic. Invalid values and `0` use the fallback |
 | `MC_TE_RPC_CLIENT_IO_THREADS` | `MC_RPC_CLIENT_IO_THREADS` | Transfer Engine and TENT client RPC I/O pool size. This pool is isolated from Store/Master traffic. Invalid values and `0` use the fallback |
@@ -1039,9 +1392,10 @@ Do not run binaries from before and after checksum support was introduced in the
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `MC_STORE_USE_HUGEPAGE` | unset | Set `1` to request HugeTLB-backed `mmap()` |
-| `MC_STORE_HUGEPAGE_SIZE` | `2MB` | Supported: `2MB`, `1GB` |
+| `MC_STORE_HUGEPAGE_SIZE` | `2MB` | Supported: `2MB`, `512MB`, `1GB` |
 | `MC_MMAP_ARENA_POOL_SIZE` | unset | Pre-allocated arena pool size (e.g., `8gb`). Explicitly set to enable the arena |
 | `MC_DISABLE_MMAP_ARENA` | unset | Disable arena, fall back to per-call `mmap()`. Accepts `1`/`true`/`yes`/`on` (or `0`/`false`/`no`/`off`) |
+| `MC_STORE_REGISTER_SPDK` | unset | Set `1` to register `ShmHelper`-allocated shared memory (host pool, dummy local buffer) with SPDK for NoF zero-copy transfers. Forces HugeTLB backing for those allocations, defaulting to 2MB hugepages when `MC_STORE_USE_HUGEPAGE` is unset. Must be set on BOTH the dummy and the real process (SPDK registration is per-process) |
 
 RDMA Store segments backed by HugeTLB are populated in parallel immediately
 before transfer-engine registration. No additional population-mode setting is
@@ -1058,6 +1412,25 @@ with its `mbind()` region before touching pages. The mmap arena retains its
 eager `MAP_POPULATE` behavior for DMA safety; set `MC_DISABLE_MMAP_ARENA=1` if
 the deferred direct-mmap path is desired while the arena is otherwise enabled.
 
+For NoF (NVMe-oF) zero-copy, `MC_STORE_REGISTER_SPDK=1` registers the shared
+memory allocated by `ShmHelper` (SGLang host pool, dummy local buffer) with
+SPDK (`spdk_mem_register`) so the NoF RDMA transport can DMA to/from it
+directly — without it those buffers fail with `No translation for ptr`.
+`spdk_mem_register` is per-process, so set this switch on BOTH the dummy
+(sender) and the real client (receiver): the dummy registers its own mapping
+in `ShmHelper::allocate`, and the real client registers its separate mapping
+of the same shared fd in `RealClient::map_shm_internal_with_device`. Setting
+it on only one process leaves the other without an SPDK translation and NoF
+transfers still fail with `No translation for ptr`. SPDK
+registration in iova=pa mode requires PHYSICALLY 2MB-aligned memory, which only
+HugeTLB pages satisfy, so this switch forces HugeTLB for the affected
+allocations even when `MC_STORE_USE_HUGEPAGE` is unset; it then defaults to 2MB
+hugepages (set `MC_STORE_USE_HUGEPAGE=1` and `MC_STORE_HUGEPAGE_SIZE=1GB` for
+1GB). Reserve enough HugeTLB pages (`/proc/sys/vm/nr_hugepages`) for the host
+pool plus any hugepage-backed segments; when the pool is exhausted the first
+allocation aborts with a clear error naming the hugepage size and count needed
+rather than silently degrading.
+
 #### yalantinglibs Log Level
 
 ```bash
diff --git a/docs/source/deployment/multi-tenancy.md b/docs/source/deployment/multi-tenancy.md
new file mode 100644
index 0000000000..8c8614eed4
--- /dev/null
+++ b/docs/source/deployment/multi-tenancy.md
@@ -0,0 +1,130 @@
+# Multi-Tenant Deployment
+
+## Configure the Master
+
+### File Connector
+
+Tenant quota admission is disabled by default. Enable strict multi-tenant mode on the master when you want memory writes admitted against connector-managed per-tenant quota:
+
+```bash
+mooncake_master \
+  --enable_multi_tenants=true \
+  --tenant_quota_connector_type=file \
+  --tenant_quota_connector_uri=/etc/mooncake/tenant_quotas.yaml
+```
+
+### etcd Connector
+
+You can also store the same YAML policy in etcd when Mooncake Store is built with `STORE_USE_ETCD=ON`:
+
+```bash
+mooncake_master \
+  --enable_multi_tenants=true \
+  --cluster_id=mooncake_cluster \
+  --tenant_quota_connector_type=etcd \
+  --tenant_quota_connector_uri=127.0.0.1:2379
+```
+
+The etcd connector stores the policy at `mooncake-store/<cluster_id>/tenant_quota_policy`. If the key does not exist, the master starts with an empty policy so the first tenant policy can be created through the admin API. It shares the process-wide store etcd client used by HA/oplog, so if HA or oplog also uses etcd, `tenant_quota_connector_uri` must match those etcd endpoints.
+
+## Define the Tenant Policy
+
+The policy must use schema version `1`; tenant names must be non-empty, unique, must not start with `_`, and must not contain NUL or control characters; quotas must be positive integers with optional `B`, `KB`, `MB`, `GB`, or `TB` units:
+
+```yaml
+version: 1
+
+tenants:
+  - name: tenant-a
+    quota: 200GB
+
+  - name: tenant-b
+    quota: 500GB
+```
+
+When strict multi-tenant mode is enabled, write requests must include a registered tenant. The `default` tenant is not special unless it is explicitly registered in the connector policy.
+
+## Manage Tenant Quotas
+
+The same HTTP port used for metrics exposes the tenant quota admin API:
+
+```bash
+# List tenant quota snapshots
+curl -s http://<master_host>:9003/api/v1/tenant_quotas
+
+# Query one tenant
+curl -s "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a"
+
+# Upsert an explicit policy. Explicit tenant policies must be between 1 byte
+# and 2^63 - 1 bytes.
+curl -s -X PUT "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a" \
+  -H 'Content-Type: application/json' \
+  -d '{"requested_quota_bytes":2147483648}'
+
+# Delete an explicit policy. The tenant must not own objects or quota usage.
+curl -s -X DELETE "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a"
+```
+
+Each tenant quota snapshot returns:
+
+```json
+{
+  "success": true,
+  "data": {
+    "tenant_id": "tenant-a",
+    "requested_quota_bytes": 2147483648,
+    "effective_quota_bytes": 2147483648,
+    "charged_bytes": 0,
+    "admission_closed": false,
+    "over_quota": false,
+    "has_explicit_policy": true
+  }
+}
+```
+
+`charged_bytes` includes completed MEMORY replicas and in-flight MEMORY allocations. Put, Copy, Move, and promotion charge quota when admission starts; failed, revoked, partially completed, or expired operations refund the unused charge. `admission_closed` is `true` when the account rejects new writes, including after its explicit policy is removed.
+
+In HA mode, quota admin requests are served only by the active master service. Standby, candidate, or inactive services return HTTP 503. If strict multi-tenant mode is disabled, the quota admin API returns HTTP 409 with `UNAVAILABLE_IN_CURRENT_MODE`. Deleting a non-empty tenant returns HTTP 409 with `TENANT_NOT_EMPTY`.
+
+## SGLang
+
+When Mooncake is used as the HiCache storage backend, set `tenant_id` in the
+Mooncake backend configuration:
+
+```bash
+--hicache-storage-backend mooncake \
+--hicache-storage-backend-extra-config \
+  '{"master_server_address":"127.0.0.1:50051","tenant_id":"tenant-a"}'
+```
+
+Alternatively, add `tenant_id` to the JSON file selected by
+`SGLANG_HICACHE_MOONCAKE_CONFIG_PATH`, or use `MOONCAKE_TENANT_ID` when loading
+the Mooncake configuration from environment variables. SGLang forwards the
+resolved value to the Mooncake client.
+
+All prefill, decode, and replica instances that should share KV cache entries
+must use the same `tenant_id` and compatible model and release namespaces.
+
+## vLLM
+
+Add `tenant_id` to the Mooncake client JSON configuration:
+
+```json
+"tenant_id": "tenant-a"
+```
+
+Point `MOONCAKE_CONFIG_PATH` at that file and enable
+`MooncakeStoreConnector` through `--kv-transfer-config`:
+
+```bash
+MOONCAKE_CONFIG_PATH=/path/to/mooncake_config.json \
+vllm serve <model> \
+  --kv-transfer-config \
+  '{"kv_connector":"MooncakeStoreConnector","kv_role":"kv_both"}'
+```
+
+`MooncakeStoreConnector` reads the JSON during initialization and passes its
+tenant ID to the Mooncake client.
+
+All prefill, decode, and replica instances that should share KV cache entries
+must use the same `tenant_id` and compatible model and release namespaces.
diff --git a/docs/source/deployment/oss-offload.md b/docs/source/deployment/oss-offload.md
new file mode 100644
index 0000000000..fdd34226cd
--- /dev/null
+++ b/docs/source/deployment/oss-offload.md
@@ -0,0 +1,184 @@
+# OSS Offload
+
+## Overview
+
+Object storage services, such as OSS and S3, provide key-based storage.
+Mooncake Store integrates object storage through `ObjectStorageAdapter` in the
+existing `FileStorage` offload path. As with local SSD and NVMe KV backends,
+the master records `LOCAL_DISK` replicas owned by a real client; readers still
+access the payload through that owner.
+
+The examples below use the OSS adapter. Other services require a compatible
+adapter; changing the endpoint alone does not add S3 support.
+
+For implementation details, see [OSS Backend Design](../design/store/oss-backend.md).
+
+## Prerequisites
+
+- An existing OSS bucket and an endpoint reachable from each offload owner.
+  No OSS filesystem mount is required.
+- Credentials with permission to PUT, GET, HEAD, LIST, and DELETE within the
+  chosen namespace. STS credentials are supported.
+- A dedicated object-key prefix for each offload owner.
+- An existing absolute, writable, non-symlink directory for
+  `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH`, required by common `FileStorage`
+  initialization. This does not enable a local SSD cache for OSS.
+- libcurl and OpenSSL development libraries and headers.
+
+## Build Support
+
+The build enables the OSS adapter when libcurl and OpenSSL are available.
+No OSS SDK or additional OSS-specific build flag is required. Follow the
+[build guide](../getting_started/build.md) to build and install Mooncake.
+
+Batch I/O uses `curl_multi_wait`; libcurl 7.66.0 is not required. Upload-buffer
+tuning is optional: with headers older than 7.62.0, the library default is used.
+
+## Topology
+
+```mermaid
+flowchart TD
+    App["Application or requesting Mooncake client"]
+    Master["Mooncake master"]
+    Owner["Offload-owning real client"]
+    FileStorage["FileStorage"]
+    Backend["DistributedStorageBackend"]
+    Adapter["OssObjectStorageAdapter"]
+    OSS["OSS bucket and owner prefix"]
+
+    App <-->|"metadata query"| Master
+    App <-->|"offload RPC and Transfer Engine"| Owner
+    Owner <-->|"offload heartbeat and LOCAL_DISK updates"| Master
+    Owner --> FileStorage --> Backend --> Adapter
+    Adapter <-->|"HTTP requests"| OSS
+```
+
+Only the offload owner needs OSS credentials. The master and requesting clients
+do not directly read or write OSS objects.
+
+## Configuration
+
+Set the backend and OSS variables in each offload owner's environment:
+
+```bash
+export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=distributed_storage_backend
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/data/file_storage
+export MOONCAKE_DISTRIBUTED_FS_TYPE=oss
+export MOONCAKE_DISTRIBUTED_ROOT_DIR=/mooncake/my-cluster/owner-1
+export MOONCAKE_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+export MOONCAKE_OSS_BUCKET=my-mooncake-bucket
+export MOONCAKE_OSS_REGION=cn-hangzhou
+# Supply MOONCAKE_OSS_ACCESS_KEY_ID and MOONCAKE_OSS_ACCESS_KEY_SECRET
+# through your credential-management mechanism, not checked-in scripts.
+```
+
+Replace the example endpoint, bucket, region, and owner prefix for your
+deployment. Each `FileStorage` instance selects one backend: OSS does not run
+alongside the local-file or NVMe KV backend within that instance.
+
+### Backend and namespace
+
+| Environment variable | Setting for OSS | Description |
+|----------------------|-----------------|-------------|
+| `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR` | `distributed_storage_backend` | Select the backend that hosts the OSS adapter. |
+| `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` | `/data/file_storage` by default | Existing local directory required by common initialization; object payloads go to OSS. |
+| `MOONCAKE_DISTRIBUTED_FS_TYPE` | `oss` | Select object-storage mode rather than a filesystem adapter. |
+| `MOONCAKE_DISTRIBUTED_ROOT_DIR` | An owner-specific prefix | Use an absolute-style path; the adapter strips leading and trailing slashes. This is not a mount point. |
+
+OSS offload does not require Master DFS configuration and does not require
+disabling a separately configured DFS tier. In the offload owner's environment,
+`MOONCAKE_DFS_FS_ADAPTER` and `MOONCAKE_DFS_ROOT_DIR` override the corresponding
+`MOONCAKE_DISTRIBUTED_*` values because they share a configuration parser.
+Leave these overrides unset when using the example above.
+
+### Endpoint and credentials
+
+| Environment variable | Default | Description |
+|----------------------|---------|-------------|
+| `MOONCAKE_OSS_ENDPOINT` | Required | Endpoint including `http://` or `https://`. Alias: `OSS_ENDPOINT`. |
+| `MOONCAKE_OSS_BUCKET` | Required | Existing bucket. Alias: `OSS_BUCKET`. |
+| `MOONCAKE_OSS_REGION` | Required | OSS signing region. Alias: `OSS_REGION`. |
+| `MOONCAKE_OSS_ACCESS_KEY_ID` | Required unless anonymous | Access key ID. Alias: `OSS_ACCESS_KEY_ID`. |
+| `MOONCAKE_OSS_ACCESS_KEY_SECRET` | Required unless anonymous | Access key secret. Alias: `OSS_ACCESS_KEY_SECRET`. |
+| `MOONCAKE_OSS_SECURITY_TOKEN` | Empty | Optional STS token. Alias: `OSS_SESSION_TOKEN`. |
+| `MOONCAKE_OSS_PATH_STYLE` | `false` | Use `endpoint/bucket/key` instead of virtual-hosted bucket addressing. |
+| `MOONCAKE_OSS_ANONYMOUS` | `false` | Disable signing; only for test endpoints or suitably configured public access. |
+
+Primary names take precedence over aliases, including explicitly empty values.
+Configuration is read at initialization; changing environment variables does
+not reconfigure an active adapter or refresh its credentials.
+
+### Backend concurrency and health check
+
+| Environment variable | Default | Description |
+|----------------------|---------|-------------|
+| `MOONCAKE_OSS_MAX_CONNECTIONS` | `64` | Maximum admitted requests and total/per-host connections per batch; minimum `1`. Not a process-wide limit. |
+| `MOONCAKE_OSS_RECEIVE_BUFFER_SIZE` | `1048576` (1 MiB) | libcurl receive-buffer suggestion for batch requests, clamped to 16 KiB–10 MiB. Single-request GETs keep the library default. |
+| `MOONCAKE_OSS_UPLOAD_BUFFER_SIZE` | `1048576` (1 MiB) | Upload-buffer suggestion for `PutV` / `PutBatch`, clamped to 16 KiB–2 MiB. Applied only with libcurl headers 7.62.0 or newer; otherwise the library default is used. |
+| `MOONCAKE_DISTRIBUTED_HEALTH_CHECK` | `false` | Write and read back a probe object during initialization, then best-effort delete it. |
+
+Numeric tuning values are decimal integers. Invalid or out-of-range integers
+use the default; the bounds above then apply. Buffer sizes are libcurl
+suggestions, not TCP socket-buffer sizes or guaranteed throughput settings.
+
+The common offload heartbeat defaults to 10 seconds and is configured through
+`MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS`. Other common client settings are
+described in [SSD Offload](ssd/ssd-offload.md).
+
+## Start Mooncake
+
+Start the master with offload enabled:
+
+```bash
+mooncake_master --rpc_port=50051 --enable_offload=true
+```
+
+After applying the backend settings above, create the required local directory
+and start a real client. This example uses a local master and TCP transfers:
+
+```bash
+mkdir -p /data/file_storage
+export MOONCAKE_MASTER=127.0.0.1:50051
+export MOONCAKE_LOCAL_HOSTNAME=127.0.0.1
+export MOONCAKE_PROTOCOL=tcp
+export MOONCAKE_TE_META_DATA_SERVER=P2PHANDSHAKE
+export MOONCAKE_OFFLOAD_ENABLED=true
+
+python -m mooncake.mooncake_store_service
+```
+
+Use routable addresses for a multi-node deployment. This launcher example
+assumes `MOONCAKE_CONFIG_PATH` is unset; a service configuration file otherwise
+takes precedence.
+
+Embedded real-client mode uses the same backend and OSS variables. Pass
+`enable_ssd_offload=True` and `ssd_offload_path` to
+`MooncakeDistributedStore.setup()` alongside the normal connection and memory
+arguments. The [SSD Offload guide](ssd/ssd-offload.md) describes embedded and
+standalone real-client deployment modes.
+
+## Troubleshooting
+
+### The adapter cannot initialize
+
+Check build dependencies, required endpoint/region/credential settings, and the
+local directory. Check for stale `MOONCAKE_DFS_*` overrides. The optional health
+check exercises OSS access; it does not test the complete Store read path.
+
+### Requests fail with authentication or permission errors
+
+Verify the endpoint, signing region, bucket permissions, and STS token lifetime.
+The adapter does not refresh credentials automatically.
+
+### An object is in OSS but cannot be read through Store
+
+A bucket object alone is not a readable Store replica. The master must have
+the key's metadata and a reachable owner. Keep prefixes owner-specific; a shared
+bucket does not make owners interchangeable.
+
+### SSD capacity metrics do not match OSS usage
+
+`MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES` supplies a configured capacity value
+(default: 2 TiB), not a queried OSS bucket capacity. Master usage tracks registered
+`LOCAL_DISK` replicas. OSS has no backend quota enforcement or automatic object
+GC here, so these metrics are not physical bucket usage or a cloud-cost limit.
diff --git a/docs/source/deployment/ssd/index.md b/docs/source/deployment/ssd/index.md
index 110445391a..a71448040f 100644
--- a/docs/source/deployment/ssd/index.md
+++ b/docs/source/deployment/ssd/index.md
@@ -6,6 +6,7 @@ storage pools. Choose the guide that matches the storage tier in your deployment
 | Storage option | Description |
 |----------------|-------------|
 | [SSD Offload](ssd-offload) | Configure local SSD offload, eviction, and I/O behavior. |
+| [NVMe KV Local-Disk Backend](nvme-kv) | Configure a local NVMe KV namespace for SSD offload. |
 | [NVMe-oF SSD Pool](nvmf-ssd-deployment-guide) | Configure a shared NVMe-over-Fabrics storage tier. |
 
 :::{toctree}
@@ -13,5 +14,6 @@ storage pools. Choose the guide that matches the storage tier in your deployment
 :hidden:
 
 ssd-offload
+nvme-kv
 nvmf-ssd-deployment-guide
 :::
diff --git a/docs/source/deployment/ssd/nvme-kv.md b/docs/source/deployment/ssd/nvme-kv.md
new file mode 100644
index 0000000000..242dcc2dbb
--- /dev/null
+++ b/docs/source/deployment/ssd/nvme-kv.md
@@ -0,0 +1,150 @@
+# NVMe KV Local-Disk Backend
+
+## Overview
+
+Mooncake Store can use a node-local NVMe Key-Value namespace as an SSD offload backend. The backend implements `StorageBackendInterface`, so the master tracks offloaded objects as `LOCAL_DISK` replicas and applications continue to use the normal Mooncake Store APIs.
+
+For implementation details, see [NVMe KV Backend Design](../../design/store/nvme-kv-backend.md).
+
+## Prerequisites
+
+- A Linux host with an NVMe KV namespace exposed as a device node.
+- Device support for NVMe KV Store, Retrieve, Delete, and store-if-not-exists semantics.
+- Read and write permission on the configured device for the Mooncake real client process.
+- An existing writable directory for `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH`, as required by the common `FileStorage` configuration.
+- `liburing` headers and library when the io_uring executor is required.
+
+## Build Support
+
+The ioctl executor is built as part of Mooncake Store. NVMe uring command support is enabled automatically when CMake finds `liburing` and Linux headers that expose `nvme_uring_cmd`, `IORING_OP_URING_CMD`, SQE128, and CQE32 support.
+
+During configuration, check for:
+
+```text
+io_uring: NVMe uring command support enabled
+```
+
+If this support is unavailable, the backend can still use the ioctl executor.
+
+## Topology
+
+```mermaid
+flowchart TD
+    App["Application or requesting Mooncake client"]
+    Master["Mooncake master"]
+    Client["Mooncake real client"]
+    FileStorage["FileStorage"]
+    Backend["NvmeKvStorageBackend"]
+    Connector["NvmeKvConnector"]
+    Executor["io_uring or ioctl executor"]
+    Device["Local NVMe KV namespace"]
+
+    App <-->|"metadata and offload coordination"| Master
+    App <-->|"object RPC and data transfer"| Client
+    Client <-->|"LOCAL_DISK replica updates"| Master
+    Client --> FileStorage --> Backend --> Connector --> Executor --> Device
+```
+
+The master selects the real client that owns a `LOCAL_DISK` replica. Only that real client opens the local NVMe KV device and issues device commands.
+
+## Configuration
+
+Set the NVMe KV variables in the real client environment. They are not required by the master.
+
+```bash
+export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=nvme_kv_storage_backend
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/var/lib/mooncake/nvme-kv
+export MOONCAKE_NVME_KV_DEVICE_PATH=/dev/nvme1n1
+export MOONCAKE_NVME_KV_TRANSPORT=auto
+```
+
+The directory configured by `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` must already exist and be writable. NVMe KV object values are stored on the device selected by `MOONCAKE_NVME_KV_DEVICE_PATH`.
+
+### Required settings
+
+| Environment variable | Default | Description |
+|----------------------|---------|-------------|
+| `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR` | `bucket_storage_backend` | Set to `nvme_kv_storage_backend`. |
+| `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` | `/data/file_storage` | Existing writable directory required by the common `FileStorage` configuration. |
+| `MOONCAKE_NVME_KV_DEVICE_PATH` | None | Namespace block-device path or NVMe generic character-device path. io_uring resolves namespace block paths to the matching `/dev/ng*` device. |
+
+### Transport and command settings
+
+| Environment variable | Default | Description |
+|----------------------|---------|-------------|
+| `MOONCAKE_NVME_KV_TRANSPORT` | `auto` | `auto`, `io_uring`, or `ioctl`. `auto` tries io_uring first and falls back to ioctl only when io_uring initialization fails. |
+| `MOONCAKE_NVME_KV_NSID` | `1` | Namespace ID encoded in NVMe KV commands. |
+| `MOONCAKE_NVME_KV_QUEUE_DEPTH` | `256` | io_uring queue depth and executor capability exposed to the backend. |
+| `MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT` | `270336` | Runtime upper bound for one NVMe KV value transfer, in bytes. |
+| `MOONCAKE_NVME_KV_PROTOCOL_MAX_VALUE_SIZE` | `524288` | Protocol or device value-size ceiling. |
+| `MOONCAKE_NVME_KV_TRANSFER_ALIGNMENT_BYTES` | `4096` | DMA buffer and transfer-length alignment. |
+| `MOONCAKE_NVME_KV_VALUE_BLOCK_UNIT_BYTES` | `512` | Unit used to encode the NVMe KV value block count. |
+
+The effective maximum value size is the smaller of the runtime transfer limit and protocol maximum, rounded down to the configured transfer alignment.
+
+### Backend concurrency
+
+| Environment variable | Default | Description |
+|----------------------|---------|-------------|
+| `MOONCAKE_NVME_KV_IO_CONCURRENCY` | `18` | Total backend I/O concurrency. When unset, Mooncake uses the smaller of 18, queue depth, and the configured maximum. |
+| `MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY` | `256` | Upper bound for automatic or explicit backend I/O concurrency. |
+| `MOONCAKE_NVME_KV_PREPARE_CONCURRENCY` | `12` | Workers used for checksum and object-layout preparation. |
+| `MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY` | `6` | Independent chunk submission lanes. |
+| `MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY` | `1` | Root submission lanes. A chunked object's root is queued only after its chunks complete. |
+| `MOONCAKE_NVME_KV_READ_PLAN_BATCH_SIZE` | `8` | Logical objects grouped into one chunk-read planning task. |
+
+Preparation, chunk submission, and root submission use bounded worker pools. Explicit lane counts are capped by the effective I/O concurrency.
+
+## Transport Selection
+
+### `auto` (recommended)
+
+Configure a namespace block-device path such as `/dev/nvme1n1`. When NVMe uring command support is compiled in, Mooncake resolves the matching NVMe generic character device, such as `/dev/ng1n1`, and initializes io_uring. If initialization fails, Mooncake opens the original block-device path with ioctl. The selected transport remains fixed for the connector lifetime.
+
+### `io_uring`
+
+Use this mode to require io_uring. Mooncake accepts either a namespace block-device path with a matching `/dev/ng*` device or the generic character-device path directly. Initialization fails instead of falling back.
+
+### `ioctl`
+
+Use this mode to require Linux NVMe passthrough ioctl. Configure the namespace block-device path. Each command is synchronous within one backend worker, and the backend worker pool supplies parallelism.
+
+## Start Mooncake
+
+Start the master with SSD offload enabled:
+
+```bash
+mooncake_master \
+    --rpc_port=50051 \
+    --enable_offload=true
+```
+
+Start a real client on the host that owns the NVMe KV device:
+
+```bash
+mooncake_client \
+    --master_server_address=127.0.0.1:50051 \
+    --host=<machine-ip> \
+    --protocol=rdma \
+    --device_names=<rdma-device> \
+    --port=50052 \
+    --global_segment_size="4 GB" \
+    --enable_offload=true \
+    --metadata_server=P2PHANDSHAKE
+```
+
+Embedded real-client mode uses the same environment variables. Set `enable_ssd_offload=True` when calling `MooncakeDistributedStore.setup()`. See [SSD Offload](ssd-offload.md) for the complete client flows.
+
+## Troubleshooting
+
+### io_uring falls back to ioctl
+
+Check that the build enabled NVMe uring command support and that the matching generic character device exists. Set `MOONCAKE_NVME_KV_TRANSPORT=io_uring` to turn fallback into an initialization error while diagnosing the setup.
+
+### Backend initialization reports an empty device path
+
+Set `MOONCAKE_NVME_KV_DEVICE_PATH` in the real client environment.
+
+### Store or Retrieve reports invalid parameters
+
+Verify namespace ID, effective maximum value size, transfer alignment, and value block unit against the device implementation. The runtime transfer limit must be at least one transfer-alignment unit.
diff --git a/docs/source/deployment/ssd/nvmf-ssd-deployment-guide.md b/docs/source/deployment/ssd/nvmf-ssd-deployment-guide.md
index 5b27e077b1..56745af781 100644
--- a/docs/source/deployment/ssd/nvmf-ssd-deployment-guide.md
+++ b/docs/source/deployment/ssd/nvmf-ssd-deployment-guide.md
@@ -126,6 +126,7 @@ python3 -m mooncake.spdk_tgt_create \
 | `ip` | IP address of the target node. |
 | `path` | SPDK installation path on the target node. |
 | `pci` | PCI addresses of SSDs to register with the target. Use commas to separate multiple PCI addresses. If this field is omitted, SPDK-ready or unmounted NVMe devices on the target node are registered. |
+| `--port` | SSH port used to connect to target nodes. The default value is `22`. |
 | `--core-mask` | CPU core mask used to start `nvmf_tgt` with `-m`. The default value is `0xff`. |
 
 **Tip**: Run `/path/scripts/setup.sh status` on a target node to list available PCI addresses.
diff --git a/docs/source/deployment/ssd/ssd-offload.md b/docs/source/deployment/ssd/ssd-offload.md
index 34d2dd28a9..7a51e61969 100644
--- a/docs/source/deployment/ssd/ssd-offload.md
+++ b/docs/source/deployment/ssd/ssd-offload.md
@@ -133,6 +133,7 @@ Start with `--enable_offload=true` for eager SSD persistence. Add `--offload_on_
 | `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` | `/data/file_storage` | Absolute path to the SSD storage directory |
 | `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR` | `bucket_storage_backend` | Storage backend type (see below) |
 | `MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES` | `1342177280` (1.25 GB) | Client-side staging buffer size |
+| `MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES` | `0` | Size of the additional preallocated pinned-host arena for same-process SSD-to-GPU restores and DFS ranged-session reads into device memory. See the constraints below |
 | `MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT` | `20000` | Max keys processed per iteration when scanning existing SSD metadata on startup |
 | `MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES` | `2199023255552` (2 TB) | Maximum disk usage |
 | `MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT` | `10000000` | Maximum number of objects on disk |
@@ -146,6 +147,8 @@ Start with `--enable_offload=true` for eager SSD persistence. Add `--offload_on_
 
 The `MOONCAKE_OFFLOAD_*` watermark names are preferred. Short aliases `MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO` and `MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO` are also accepted. The high watermark must be greater than the low watermark.
 
+The pinned restore quota is separate from `MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES`; it does not convert the normal FileStorage arena to pinned memory. It is allocated only when `MC_STORE_MEMCPY=1`. The arena is selected when the current process owns the SSD replica and the restore destination is GPU memory, and is also used as request-scoped staging for DFS ranged-session reads into device memory. Tensor payload ranges are copied from their source offset without an additional FileStorage staging allocation. Remote and CPU-destination reads continue to use the existing path. If the pinned quota is exhausted, the request uses the normal client buffer arena; if the quota cannot be pinned at startup, the optimization remains disabled. io_uring disables the pinned restore arena. The file-per-key backend may still use its own temporary pageable buffer internally; the bucket and offset-allocator backends can read into the supplied restore buffer directly.
+
 ### Bucket backend settings
 
 Applies when `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=bucket_storage_backend`.
@@ -156,6 +159,8 @@ Applies when `MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=bucket_storage_backend
 | `MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT` | `500` | Max keys per bucket |
 | `MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` | `0` | Eviction threshold in bytes. When set to `0`, the backend uses **90% of the physical disk capacity** as the quota — it does not mean unlimited. Set an explicit value to control disk usage precisely. |
 | `MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY` | `fifo` | Eviction policy: `none` / `fifo` / `lru` |
+| `MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES` | `0` (disabled) | Hard cap on **real on-disk** bytes (`du`-equivalent) under this backend's `ssd_offload_path`. `0` disables it. Its scope depends on the deployment — see below. |
+| `MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS` | `500` | How long the directory-scan result is cached before re-scanning, to bound the cost of the physical-usage check. `<= 0` scans on every check. |
 
 ### File-per-key backend settings
 
@@ -212,7 +217,7 @@ Best for: high-concurrency scenarios with many small objects where restart durab
 
 ### Write-time eviction
 
-When `MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` is set, the backend automatically evicts buckets before writing new ones if total disk usage would exceed the limit.
+When `MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` or `MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES` is set, the backend automatically evicts buckets before writing new ones if total disk usage would exceed the limit.
 
 | Policy | Behavior |
 |--------|----------|
@@ -222,6 +227,21 @@ When `MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` is set, the backend automatically
 
 Eviction is two-phase: the bucket is removed from metadata and master is notified first, then in-flight reads are drained before files are deleted.
 
+**`MAX_TOTAL_SIZE` vs `MAX_PHYSICAL_BYTES`**
+
+`MAX_TOTAL_SIZE` bounds a *logical* in-memory counter (`data_size + meta_size` summed per object). It undercounts real disk usage: it ignores filesystem block rounding, and a bucket file stays on disk until *every* object in it is evicted while the counter drops per object. `MAX_PHYSICAL_BYTES` instead measures the *real* on-disk bytes (`du`-equivalent), so prefer it when you must not exceed a hard physical limit — most importantly a Kubernetes `emptyDir` with a `sizeLimit`, which the kubelet enforces by the volume's actual `du` usage and evicts the pod when exceeded.
+
+**Scope depends on the deployment.** `MAX_PHYSICAL_BYTES` scans this backend's own `ssd_offload_path`, so its meaning changes with the directory layout:
+
+- **Shared directory** — all TP ranks point at the same path (SGLang's current default). Each rank scans the whole directory, so the cap bounds the **combined** usage of all ranks. Set it to the total capacity you must stay under (e.g. the `emptyDir` `sizeLimit`).
+- **Per-rank directory or separate disks** — each rank scans only its own files, so the cap bounds **each rank individually**. Set it to the per-rank budget (e.g. `sizeLimit / N` when N ranks share one volume via separate subdirectories, or the disk capacity when each rank has its own disk).
+
+> A cap on the *global* sum across ranks that holds under any layout (including ranks on separate disks) cannot be done by a per-directory scan and would require master-side aggregation; it is not part of this feature.
+
+The two limits are independent and may be combined — eviction fires when either would be exceeded. `MAX_PHYSICAL_BYTES` only takes effect when an eviction policy is set (`fifo`/`lru`); with `none`, eviction never runs.
+
+---
+
 ### Proactive watermark eviction
 
 When `MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION=true`, the FileStorage heartbeat asks the backend to check local-disk usage every `MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS` seconds. If usage exceeds `MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO`, the backend evicts toward `MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO`.
@@ -266,6 +286,8 @@ mooncake_master \
 export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/nvme/mooncake_offload
 export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=bucket_storage_backend
 export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((200 * 1024 * 1024 * 1024))  # 200 GB
+export MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES=$((200 * 1024 * 1024 * 1024)) # optional; shared dir: total cap. per-rank dir: per-rank cap
+export MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS=500 # optional
 export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru
 
 mooncake_client \
diff --git a/docs/source/design/conductor/conductor-architecture-design.md b/docs/source/design/conductor/conductor-architecture-design.md
index 115156b5c4..2b13da0772 100644
--- a/docs/source/design/conductor/conductor-architecture-design.md
+++ b/docs/source/design/conductor/conductor-architecture-design.md
@@ -1,4 +1,4 @@
-# Mooncake Conductor Architecture
+# Conductor Architecture
 
 ## Overview
 
@@ -68,8 +68,10 @@ Within each context, Conductor stores:
   per-instance access metadata;
 - a DP-rank set used to report rank-level hit information.
 
-The current implementation computes complete-block prefix hashes from token IDs
-and ignores trailing partial blocks during `/query`.
+The vLLM strategy computes complete-block prefix hashes from token IDs and
+ignores trailing partial blocks during `/query`. The SGLang strategies also hash
+the trailing partial block, so a match that reaches it is reported as the number
+of tokens the request actually carries, never as a whole block.
 
 ## Event flow
 
diff --git a/docs/source/design/conductor/index.md b/docs/source/design/conductor/index.md
new file mode 100644
index 0000000000..61226e0b84
--- /dev/null
+++ b/docs/source/design/conductor/index.md
@@ -0,0 +1,14 @@
+# Mooncake Conductor
+
+Mooncake Conductor is the KV-cache indexer used by cache-aware routers. It
+subscribes to KV cache events from inference engines or storage backends,
+normalizes those events, maintains a global prefix cache table, and exposes
+HTTP APIs for dynamic service registration and cache-hit queries.
+
+:::{toctree}
+:maxdepth: 1
+
+conductor-architecture-design
+publisher-design
+subscriber-guide
+:::
diff --git a/docs/source/design/conductor/publisher-design.md b/docs/source/design/conductor/publisher-design.md
new file mode 100644
index 0000000000..8a2c2255a4
--- /dev/null
+++ b/docs/source/design/conductor/publisher-design.md
@@ -0,0 +1,150 @@
+# KV Event Publisher Design
+
+## Goals
+
+The master publishes logical cache availability for external indexers while
+keeping physical replica management internal. The implementation uses the
+existing RFC #1527 map protocol and supports `stored`, `removed`, and
+`cleared`. It does not include an indexer, replay service, or Conductor.
+
+## Transport
+
+The master binds a ZeroMQ PUB socket. Each multipart message is:
+
+1. an empty topic frame;
+2. an unsigned 64-bit big-endian transport sequence;
+3. a msgpack payload `[timestamp_ms, [event_maps], dp_rank]`.
+
+Publishing is asynchronous. A bounded in-process queue drops the oldest event
+when full and reserves a sequence gap so subscribers can detect loss. Relevant
+master flags are:
+
+- `enable_kv_events`
+- `kv_events_bind_endpoint`
+- `kv_events_backend_id`
+- `kv_events_model_name`
+- `kv_events_block_size`
+- `kv_events_additional_salt`
+- `kv_events_lora_name`
+- `kv_events_dp_rank`
+- `kv_events_emit_object_key`
+- `kv_events_emit_legacy_compat`
+- `kv_events_queue_capacity`
+
+The feature is compiled only when `ENABLE_KV_EVENTS=ON`; public client APIs
+remain available and become no-ops for event metadata in builds without ZMQ.
+
+## Object and medium state
+
+Event identity is `backend_id`, `tenant_id`, and `object_key`. The `medium`
+field is one string, either `cpu` or `disk`. If an object is present in both
+tiers, the publisher emits one event per tier.
+
+Replica types are collapsed onto those two logical tiers: memory replicas map to
+`cpu`, and every non-memory replica type — disk, local disk, NOF SSD, and DFS —
+maps to `disk`. Subscribers see one entry per storage class and are not exposed
+to Mooncake's internal replica taxonomy, which can grow without becoming a
+protocol change.
+
+Replica topology is normalized to medium availability:
+
+- the first completed replica on a medium emits `stored`;
+- removing the last completed replica on a medium emits `removed`;
+- changing the number or location of replicas within an available medium emits
+  no event;
+- a successful Put or Upsert commit emits `stored` for every current medium.
+
+The publisher holds no per-object state. Every delta is computed from the
+arguments of a single call: the medium set after the mutation, plus the set the
+caller captured before it. The master already snapshots that set before mutating
+metadata, so keeping a second copy in the publisher would only duplicate it, and
+a per-object map would shadow the master's whole key space.
+
+This makes the caller responsible for the "before" set. A path that mutates
+metadata and then publishes without a snapshot cannot produce a correct delta,
+which is why the snapshot and the publish call sit in the same function
+throughout the master.
+
+Duplicate `removed` events are not suppressed by the publisher. Where the same
+removal can be reached twice — an eviction that drops the last replica, followed
+by the erase of the now-invalid object — the master picks one publisher, not
+both: the eviction path returns early when the object is no longer valid and
+leaves the announcement to the erase path. Subscribers additionally treat
+`removed` as idempotent, so a duplicate is harmless rather than load-bearing.
+
+## Event payload fields
+
+The publisher is deliberately key-agnostic. Store never parses, splits, or
+interprets an object key, so no key format is privileged and no connector needs
+a Mooncake-specific key convention. The raw Store key is forwarded verbatim as
+`object_key`, and every field that would require interpreting that key stays
+empty:
+
+- `seq_hashes` and the legacy `block_hashes` are emitted as empty arrays;
+- `token_ids` and `parent_hash` are nil on `stored`; `base_block_idx` is nil on
+  both `stored` and `removed`;
+- `group_id` carries the Store group identity, not a connector group field.
+
+A `cleared` event is envelope-only. It omits `object_key`, `group_id`,
+`seq_hashes`, `block_hashes`, and `base_block_idx` entirely rather than
+emitting them as nil.
+
+The remaining envelope fields come from master configuration, because one
+publisher serves one fixed model, block-size, LoRA, additional-salt, and
+data-parallel context: `model_name`, `block_size`, `additional_salt`,
+`lora_name`, and `dp_rank`. `block_size=0` is encoded as nil, as are empty salt
+and LoRA names. The configured `dp_rank` appears both in each event envelope and
+in the batch trailer. Per-object `tenant_id` comes from the Store operation
+rather than the global tenant config.
+
+Setting `kv_events_emit_object_key=false` suppresses `stored` and `removed`
+entirely, since without the key those events carry no identity a subscriber can
+act on. Suppressed events are counted as `skipped_keyless_events`. `cleared` is
+unaffected: it is tenant-scoped and needs no object identity.
+
+With `kv_events_emit_legacy_compat=true` (the default) each event also carries a
+legacy `type` alias alongside `event_type`: `BlockStored`, `BlockRemoved`, and
+`AllBlocksCleared`. Legacy mode also adds the `block_hashes` array and, on
+`stored`, a nil `parent_block_hash`. This lets subscribers written against the
+pre-RFC field names consume the same stream unchanged.
+
+A subscriber that needs block-level or shard-level semantics must derive them
+from the key itself, using the same connector convention that produced it, plus
+its own registered topology. The publisher cannot help here:
+it does not know which connector wrote a key, how many layers or shards a block
+spans, or how deep a block sits in a prefix chain.
+
+## Publication points
+
+| Operation | Event behavior |
+|---|---|
+| Put/BatchPut commit | `stored` for all completed media |
+| Upsert of an existing object | `removed` when the old value becomes unreadable, then `stored` for all completed media on commit |
+| Copy/Move completion | Medium availability delta |
+| Offload/promotion completion | `stored` when the target medium first appears |
+| Replica clear or eviction | `removed` when the last replica on a medium disappears |
+| Stale handle/client cleanup | Medium availability delta |
+| Remove/BatchRemove/regex remove | `removed` for every available medium |
+| RemoveAll | Per-object `removed`, then tenant `cleared` when every object was removed |
+| Failed uncommitted new Put | No event |
+
+`cleared` uses `medium=nil` and clears all media for the specified
+`backend_id + tenant_id`. It is emitted only when the tenant actually held
+objects and none were skipped, so a tenant that never existed produces no
+`cleared`, and a `RemoveAll` that leaves a still-leased object behind produces
+none either. Under HA with the oplog the metadata erase is deferred to the
+durable callback, so the decision is based on what the removal loop accepted, not
+on whether the metadata map looks empty. Every skip counts, including the less
+obvious ones: an object whose replicas are not all completed, an object with a
+pending replication task, a failed oplog slot reservation, and a failed oplog
+append.
+
+## Limitations
+
+The publisher is PUB-only. It does not replay missed events, publish a startup
+snapshot, or persist its compact context cache. Subscribers must detect
+transport sequence gaps and recover through their own reconciliation path.
+Because the compact context is per-process and not persisted, a master restart
+resets it: the first event for a previously known object is a fresh `stored`
+rather than a delta. Objects restored before the publisher starts are only
+described by tenant, backend, fixed publisher context, and object key.
diff --git a/docs/source/design/conductor/subscriber-guide.md b/docs/source/design/conductor/subscriber-guide.md
new file mode 100644
index 0000000000..0ed39e2e7b
--- /dev/null
+++ b/docs/source/design/conductor/subscriber-guide.md
@@ -0,0 +1,141 @@
+# KV Event Subscriber Guide
+
+How to consume the Mooncake Store KV event stream. For why the publisher is
+built the way it is, see [publisher-design](publisher-design.md).
+
+## Transport
+
+Events arrive on a ZMQ `PUB` socket as a three-frame multipart message:
+
+| Frame | Contents |
+|---|---|
+| 0 | Topic. Always empty, but always present. |
+| 1 | Unsigned 64-bit big-endian sequence number, 8 bytes. |
+| 2 | MessagePack payload. |
+
+The payload is a 3-element array: `[timestamp_ms, [event_map, ...], dp_rank]`.
+One message carries up to 64 events, so a subscriber must iterate the middle
+element rather than assuming one event per message.
+
+## Event envelope
+
+Every event map contains these fields:
+
+| Field | Type |
+|---|---|
+| `event_id` | `u64`, monotonic per publisher process |
+| `timestamp` | `i64` milliseconds |
+| `event_type` | `stored`, `removed`, or `cleared` |
+| `model_name` | string or nil |
+| `block_size` | `u32`, nil when configured as 0 |
+| `additional_salt` | string or nil |
+| `lora_name` | string or nil |
+| `tenant_id` | string |
+| `backend_id` | string |
+| `medium` | string or nil |
+| `dp_rank` | `u32` |
+
+`stored` and `removed` add `group_id`, `object_key` (unless
+`kv_events_emit_object_key=false`), `seq_hashes`, and `base_block_idx`. `stored`
+additionally carries `parent_hash` and `token_ids`.
+
+## Keys are not interpreted
+
+Store never parses, splits, or interprets an object key. The raw Store key is
+forwarded verbatim as `object_key`, and every field that would require
+interpreting it is empty or nil:
+
+- `seq_hashes` and the legacy `block_hashes` are always empty arrays;
+- `token_ids` and `parent_hash` are always nil on `stored`;
+- `base_block_idx` is always nil.
+
+A subscriber that needs block-level identity must derive it from `object_key`
+itself using whatever convention the producer applied. Do not expect Mooncake to
+supply block hashes, token ids, or block depth.
+
+## Media
+
+`medium` is normalized to exactly two logical tiers: `cpu` for memory replicas,
+`disk` for every non-memory class (local disk, NVMe-oF, DFS). One event names one
+medium.
+
+## Stored
+
+`stored` announces that the object is readable on the event's medium. Treat
+repeated `stored` for the same object/backend/medium as idempotent, and do not
+infer physical replica count from event count.
+
+An Upsert of an existing object publishes `removed` for the old value and
+`stored` for the replacement, in that order. There is no separate update event.
+
+## Removed
+
+`removed` retracts availability for the event's medium only. Other media for the
+same object may remain valid, so drop the object entirely only once no medium
+remains.
+
+Treat repeated `removed` for the same object/backend/medium as idempotent. The
+publisher does not deduplicate retractions, so a subscriber that reference-counts
+media instead of storing a set can decrement past zero.
+
+## Cleared
+
+`cleared` is envelope-only. It omits `object_key`, `group_id`, `seq_hashes`,
+`block_hashes`, and `base_block_idx` entirely rather than emitting them as nil,
+and carries `medium=nil`. It means every object under the event's
+`backend_id + tenant_id` is gone.
+
+Mooncake emits `cleared` when a `RemoveAll` actually empties a tenant. It is not
+emitted for a tenant that held no objects, and it is not emitted when any object
+was skipped (for example a still-leased object without `force`).
+
+## Legacy compatibility
+
+With `kv_events_emit_legacy_compat=true` (the default) each event also carries a
+`type` field alongside `event_type`:
+
+| `event_type` | legacy `type` |
+|---|---|
+| `stored` | `BlockStored` |
+| `removed` | `BlockRemoved` |
+| `cleared` | `AllBlocksCleared` |
+
+Per-object events additionally carry an empty `block_hashes` array, and `stored`
+carries a nil `parent_block_hash`. Set the flag to `false` to emit only the
+RFC #1527 field names.
+
+## Ordering, loss, and recovery
+
+Sequence numbers are strictly monotonic and gap-free while the publisher runs.
+Use frame 1 for transport ordering and `event_id` for event ordering within the
+stream.
+
+A sequence gap means events were dropped. When the publisher's async queue is
+full it drops the oldest events and **reserves the sequence numbers they would
+have used**, so a gap is always visible rather than silent. On seeing a gap, a
+subscriber must either invalidate the affected `backend_id + tenant_id` state or
+reconcile it against the master, which is the authoritative source for key
+placement.
+
+There is no replay endpoint and no startup snapshot. A subscriber that joins
+after objects were stored receives nothing about them. Publisher state is
+per-process and not persisted, so a master restart resets the sequence counter to
+1 without emitting a reset signal; a subscriber that filters on monotonic
+sequence must be prepared for the counter to move backwards and should reconcile
+against the master rather than discarding the new events.
+
+## Observability
+
+`GET /kv_events/status` on the master admin port reports:
+
+| Field | Meaning |
+|---|---|
+| `enabled` | Whether a publisher is live |
+| `published_batches` | ZMQ messages sent |
+| `published_events` | Events inside those messages |
+| `dropped_events` | Events dropped by a full queue; each leaves a sequence gap |
+| `skipped_keyless_events` | Per-object events suppressed because no `object_key` was available |
+
+A nonzero `skipped_keyless_events` with `kv_events_emit_object_key=false` is
+expected: that flag suppresses all `stored` and `removed` events, leaving only
+`cleared`.
diff --git a/docs/source/design/engram.md b/docs/source/design/engram.md
deleted file mode 100644
index 0372ee4482..0000000000
--- a/docs/source/design/engram.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# EngramStore Backend
-
-Mooncake provides EngramStore as the storage backend for Engram embedding tables.
-
-The scope is intentionally narrow:
-
-- the caller defines the physical table layout
-- the caller uploads one table per head
-- the caller provides precomputed row ids with shape `[B, L, H]`
-- Mooncake returns the selected rows as `[B, L, H, D]`
-
-Mooncake does not implement tokenizer compression, N-gram hashing, query logic,
-or any other model-side Engram algorithm.
-
-## Current Backend Boundary
-
-The current implementation is intentionally conservative. It keeps EngramStore
-on top of the existing Store interfaces and does not depend on:
-
-- transfer scatter read
-- grouped transfer task
-- `get_into_range`
-- `batch_query`
-- local direct mapping
-- query cache
-- remote gather control-plane changes
-
-Those optimizations are deferred to follow-up PRs so that the EngramStore backend can
-land first as a small, reviewable unit.
-
-## Configuration
-
-`EngramStoreConfig` contains the physical layout for one EngramStore layer:
-
-- `table_vocab_sizes`: per-head table sizes `[N_0, N_1, ..., N_{H-1}]`
-- `embedding_dim`: row width `D`
-
-For `layer_id`, Mooncake generates one store key per head:
-
-```text
-engram:l{layer_id}:h{head_idx}
-```
-
-Each key stores a `float32` table with shape `[N_h, D]`.
-
-## Public Interface
-
-Python:
-
-- `EngramStore(layer_id, config, store=None)`
-- `populate(embedding_buffers)`
-- `lookup(row_ids)`
-- `remove_from_store(force=False)`
-- `get_table_vocab_sizes()`
-- `get_store_keys()`
-- `get_num_heads()`
-- `get_embedding_dim()`
-
-The Python `store` argument accepts the existing `MooncakeDistributedStore`
-wrapper, or `None` for metadata-only construction.
-
-C++:
-
-- constructor `EngramStore(int layer_id, const EngramStoreConfig&, std::shared_ptr<PyClient>)`
-- `populate(...)`
-- `lookup_rows(...)`
-- `lookup_rows_contiguous(...)`
-- `remove_from_store(...)`
-- metadata getters matching the Python surface
-
-## Data Contract
-
-Populate expects one NumPy `float32` array per head:
-
-```text
-embedding_buffers[h].shape == [N_h, D]
-```
-
-Lookup accepts either:
-
-- nested Python lists with logical shape `[B, L, H]`, or
-- a contiguous NumPy `int64` array with shape `[B, L, H]`
-
-Lookup returns:
-
-```text
-output.shape == [B, L, H, D]
-```
-
-## Populate Flow
-
-Populate follows the existing Store write path:
-
-1. validate that exactly one table is provided for each head
-2. validate that every table matches `[N_h, D]`
-3. verify that the target head-table keys do not already exist
-4. register each embedding table buffer
-5. upload all head tables with `batch_put_from(...)`
-6. unregister the staging buffers
-
-`populate(...)` is defined as a create-only operation for one EngramStore layer. To
-reuse a `layer_id`, first remove the old tables with `remove_from_store(...)`.
-
-If upload fails after some head tables have already been written, or if publish
-finishes but post-write buffer cleanup fails, the backend best-effort removes
-the keys written by the failed populate attempt before returning an error.
-
-## Lookup Flow
-
-Each lookup follows the same simplified backend flow:
-
-1. validate the `row_ids` shape and bounds
-2. build per-head byte ranges for the requested rows
-3. issue one `get_into_ranges(...)` call to materialize those rows into the output buffer
-
-For NumPy `row_ids`, the binding uses a contiguous fast path and builds ranges
-directly from the input tensor without first converting the entire input into a
-nested C++ container.
-
-## Validation
-
-The backend enforces these invariants:
-
-- `table_vocab_sizes` is non-empty and every entry is positive
-- `embedding_dim` is positive
-- `populate(...)` receives exactly one table per head
-- every populated table matches `[N_h, D]`
-- `lookup(...)` receives a non-empty `[B, L, H]` input
-- every row id satisfies `0 <= row_ids[..., h] < N_h`
-
-## Validation Status
-
-This backend is covered by:
-
-- correctness tests in `scripts/test_engram_store.py`
-- benchmark coverage in `scripts/bench_engram_store_27b.py`
-
-`scripts/test_engram_store.py` can run against an existing Mooncake deployment through
-`MOONCAKE_CONFIG_PATH` / `MOONCAKE_MASTER`, or it can start a local
-`mooncake_master` instance automatically for a self-contained TCP test run.
-
-By default, the benchmark exercises `engram_store.populate(...)` directly. Its
-fallback populate paths are gated behind `ENGRAM_ALLOW_POPULATE_FALLBACK=1` so
-they do not silently mask regressions in the current implementation.
diff --git a/docs/source/design/index.md b/docs/source/design/index.md
deleted file mode 100644
index 6b69421b4e..0000000000
--- a/docs/source/design/index.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-orphan: true
----
-
-# Design Documents
-
-Architecture and implementation details for Mooncake's storage, transfer, and
-distributed execution components.
-
-## Core Architecture
-
-| Document | Description |
-|----------|-------------|
-| [Mooncake Architecture](architecture) | KVCache-centric disaggregated serving architecture. |
-| [Mooncake Store](mooncake-store) | Distributed object and KV cache storage design. |
-| [Transfer Engine](transfer-engine/index) | High-performance data movement architecture and transports. |
-| [P2P Store](p2p-store) | Peer-to-peer checkpoint and object transfer design. |
-
-## Serving and Cache Systems
-
-| Document | Description |
-|----------|-------------|
-| [HiCache](hicache-design) | Hierarchical KV cache design. |
-| [Engram](engram) | Distributed serving and cache architecture. |
-| [Unified Parallel Tensor I/O](unified-parallel-tensor-io) | Parallel tensor storage and transfer model. |
-| [SSD Offload](ssd-offload) | SSD-backed cache hierarchy design. |
-| [SSD Free-Ratio-First Allocation](ssd-free-ratio-first-allocation) | Capacity-aware replica placement strategy. |
-
-## Distributed Execution and Routing
-
-| Document | Description |
-|----------|-------------|
-| [Mooncake Backend (PG)](mooncake-backend-pg) | Fault-tolerant PyTorch process-group backend. |
-| [Mooncake EP](mooncake-ep) | Expert-parallel communication and recovery. |
-| [TENT](tent/overview) | Next-generation transfer engine design. |
-| [TENT Benchmark](tent/tebench) | TENT benchmark framework and methodology. |
-| [Conductor](conductor/conductor-architecture-design) | Cache-aware request routing architecture. |
diff --git a/docs/source/design/mooncake-backend-pg.md b/docs/source/design/mooncake-backend-pg.md
index ed61f776a3..630b3ea5ba 100644
--- a/docs/source/design/mooncake-backend-pg.md
+++ b/docs/source/design/mooncake-backend-pg.md
@@ -1,210 +1,521 @@
-# Mooncake Backend (PG) Design
+# Mooncake PG Design
 
-Mooncake Backend is a `torch.distributed` ProcessGroup backend for Mooncake. It
-provides collective and point-to-point communication primitives, rank-health
-tracking, and elastic recovery hooks for inference systems that need to keep
-serving after partial rank failures.
+Mooncake PG is a communication library built on Mooncake Transfer Engine. It
+provides collective and P2P operations together with dynamic membership, fault
+tolerance, and recovery.
 
-This document is intended for developers who maintain Mooncake PG itself or
-integrate it into higher-level serving systems.
+## Dynamic Membership at a Glance
 
-## Goals
+If you are used to a fixed-membership process group, a natural mental model is
+that a group is simply _the set of ranks that were there when the group was
+created_. If the set changes, you create another group.
 
-Mooncake Backend is designed to:
+Mooncake PG uses a slightly different model. Think of a group as a **dinner
+table with numbered seats**.
 
-- integrate with PyTorch through the standard ProcessGroup extension mechanism;
-- expose `mooncake` for accelerator tensors and `mooncake-cpu` for CPU tensors;
-- support common collective APIs used by inference engines;
-- track active and inactive ranks so collectives can continue after failures;
-- allow replacement ranks to publish metadata, join an existing group, and be
-  activated by healthy ranks;
-- reuse Mooncake Transfer Engine and topology information for data movement.
+The table has a fixed number of seats, decided before dinner starts. During the
+meal, however, not every seat has to be occupied.
 
-Non-goals:
+A diner may leave, but the seat does not disappear. The other diners do not
+shuffle around to fill the gap; nobody gets a new seat number just because
+someone stepped away. Later, that diner may return to the same seat, or someone
+else may occupy it. New diners may also occupy seats that were reserved but
+never used.
 
-- It is not a drop-in replacement for every NCCL/Gloo behavior. Validate each
-  collective, dtype, and topology required by the application.
-- Elastic recovery is an explicit protocol. The backend does not silently add a
-  new process to all collectives without application coordination.
+So there are really two separate questions:
 
-## Relationship with `torch.distributed`
+- **How many seats does the table have?**
+- **Which seats are currently occupied and participating in the dinner?**
 
-Mooncake registers two PyTorch backends when the PG extension module is imported:
+The first stays fixed. The second may change over time.
 
-- `mooncake-cpu`, registered for CPU devices;
-- `mooncake`, registered for accelerator devices such as CUDA or MUSA depending
-  on the build.
+That is the basic intuition behind Mooncake PG's dynamic membership.
 
-The backend class itself derives from `c10d::ProcessGroup`. Applications use
-regular PyTorch APIs such as `dist.init_process_group()`, `dist.all_reduce()`,
-`dist.new_group()`, and `dist.batch_isend_irecv()`.
+### From the dinner table to Mooncake PG
 
-Point-to-point dispatch in PyTorch expects a `c10d::Backend` object. Mooncake PG
-therefore includes a lightweight P2P shim that delegates `send` and `recv` calls
-back to the owning `MooncakeBackend` instance.
+In Mooncake PG, the numbered seats correspond to **rank slots**. A group
+reserves a fixed number of rank slots when it is created, bounded by
+`max_group_size`. Which of those ranks currently participate in group
+operations is tracked separately by `active_ranks`.
 
-## Main runtime objects
+For example, a group can reserve eight rank slots while initially activating
+only four -- four diners at an eight-seat table:
 
-### `MooncakeBackendOptions`
+```
+max_group_size = 8
+active_ranks = [1, 1, 1, 1, 0, 0, 0, 0]
+```
+
+If rank 2 is later deactivated -- one diner leaves the table:
+
+```
+active_ranks = [1, 1, 0, 1, 0, 0, 0, 0]
+```
+
+its rank slot remains reserved, and the other ranks are not renumbered -- the
+empty seat simply remains empty.
+
+Rank 4 may also subsequently become active without filling that hole:
+
+```
+active_ranks = [1, 1, 0, 1, 1, 0, 0, 0]
+```
+
+The group keeps the same rank structure throughout these changes; only the set
+of active participants changes.
+
+This design also extends naturally to fault tolerance and recovery. A failed
+rank can be removed from the active membership without reshaping the group,
+while a recovered rank can later rejoin through the same membership mechanism.
+
+## Core Concepts
 
-`MooncakeBackendOptions` carries Mooncake-specific process-group configuration:
+### Capacity and size
 
-| Field | Meaning |
-| --- | --- |
-| `activeRanks_` | Rank-health tensor exposed to collectives and user code. |
-| `isExtension_` | Whether this process is a joining/replacement rank. |
-| `maxWorldSize_` | Optional reserved capacity for future ranks. |
+Mooncake PG has capacity at two scopes:
 
-The `activeRanks_` tensor must be `torch.int32`. It must be on CPU for
-`mooncake-cpu` and on the accelerator device for `mooncake`. When
-`maxWorldSize_` is set, `activeRanks_` must be sized to `maxWorldSize_` so the
-backend can reserve inactive rank slots.
+- Process-level `max_world_size` bounds the number of ranks in the whole world.
+- Group-level `max_group_size` bounds the number of ranks in a group.
 
-### Transfer group metadata
+Despite the name, a group's `size` is not the number of active members. It is
+one past the highest active in-group rank and therefore acts as a rank-index
+upper bound. For example:
 
-Each backend owns shared metadata for:
+```text
+active_ranks   = [1, 0, 1, 0]
+size           = 3
+max_group_size = 4
+```
+
+User code that allocates rank-indexed buffers must cover at least `size`
+entries, including inactive holes below that bound. Per-group masks such as
+`active_ranks` and `failed_ranks_hint` span `max_group_size`.
+
+An extension rank before `joinGroup` (`Isolated` or `Quiescing`) is the
+exception: `getSize()` continues to report the group's declared size for
+PyTorch rank validation, even though its effective membership is temporarily
+`{self}`.
+
+Holes preserve rank numbers. So user code that needs the number of participants
+must count `active_ranks` rather than use `getSize()` or
+`dist.get_world_size()`.
+
+### Rank namespaces
+
+A process has one `GlobalRank` in the world and may have a different
+`InGroupRank` in each group:
+
+- `GlobalRank` indexes the world-capacity namespace `[0, max_world_size)`.
+- `InGroupRank` indexes the group-capacity namespace `[0, max_group_size)`.
 
-- the current rank and backend index;
-- current capacity (`size`) and visible active size (`activeSize`);
-- host and device active-rank masks;
-- peer connection state;
-- rank-local and rank-global mapping;
-- store handles and extension state used by recovery;
-- P2P proxy and connection poller state.
+The distinction matters whenever a group contains only part of the world or
+orders its ranks differently. Group-level operations, including
+`activate_ranks` and `deactivate_ranks`, use in-group ranks unless stated
+otherwise.
 
-`size` is the reserved capacity. `activeSize` is the visible group size returned
-by `dist.get_world_size()`. With `max_world_size`, `size` may be larger than
-`activeSize`; inactive slots are masked out by the active-rank state.
+### Rank state
 
-### Transfer Engine ownership
+The Coordinator tracks a process-level `RankState`:
 
-By default, Mooncake Backend initializes its own Transfer Engine. Advanced
-integrations may call `pg.set_transfer_engine(engine)` before
-`init_process_group()` to inject an external Transfer Engine. In that mode, the
-caller owns the engine and must keep it alive until all Mooncake process groups
-using it are destroyed.
+| State     | Meaning                                                                                         |
+| --------- | ----------------------------------------------------------------------------------------------- |
+| `Offline` | No usable Agent session exists for this global rank.                                            |
+| `Synced`  | The Agent session is synchronized, but the rank is not in the current healthy set.              |
+| `Healthy` | The Agent session is synchronized and current link evidence places the rank in the healthy set. |
 
-## Initialization lifecycle
+A new Agent session moves a rank from `Offline` to `Synced`. Link evidence can
+promote it to `Healthy` or demote it back to `Synced`; losing the Agent session
+makes it `Offline`.
 
-The initialization flow is:
+The Coordinator combines link reports from all ranks to determine which ranks
+are `Healthy`. The healthy ranks must be connected to one another in both
+directions. A registered rank that does not meet these conditions remains
+`Synced`.
 
-1. Python imports `mooncake.pg`, which loads a PyTorch-version-specific native
-   extension.
-2. The extension registers `mooncake` / `mooncake-cpu` with PyTorch.
-3. `dist.init_process_group()` invokes the backend factory with PyTorch
-   distributed options and optional `MooncakeBackendOptions`.
-4. The backend initializes active-rank masks and reserved rank slots.
-5. Non-extension ranks publish local peer metadata and wait until current peers
-   are connected.
-6. Extension ranks enter local-only mode and wait for the explicit join protocol.
+`RankState` is independent of any group. It describes whether a process is
+ready for data-plane communication; participation in a particular group is
+described separately by group membership.
 
-The important distinction is that reserving capacity does not automatically make
-future ranks active. New ranks are masked until `recover_ranks()` activates them.
+### Group membership
 
-## Active ranks and dynamic world size
+`rank_order` connects the two namespaces: it records the `GlobalRank` assigned
+to each `InGroupRank`. This is a stable slot assignment, not a list of current
+participants. Whether an assigned rank participates is recorded separately by
+its `GroupMemberState` and reflected in `active_ranks`.
 
-Mooncake PG tracks two related concepts:
+For example, suppose global ranks 2, 5, and 7 form a group with
+`max_group_size = 5`. Inside that group they are in-group ranks 0, 1, and 2, so
+`rank_order = [2, 5, 7]`. Calling `deactivate_ranks([1])` targets global rank 5:
+its member state becomes `Inactive`, `active_ranks` becomes
+`[1, 0, 1, 0, 0]`, and the rank order does not change.
 
-- **Reserved capacity** (`size`): how many rank slots the backend knows about.
-- **Visible active size** (`activeSize`): the current group size visible through
-  PyTorch APIs.
+If global rank 9 is later added, it is assigned in-group rank 3 and the rank
+order becomes `[2, 5, 7, 9]`. Existing in-group ranks are never renumbered;
+new ranks extend the order, while unused group capacity remains unassigned.
 
-When `max_world_size` is larger than the initial `world_size`, Mooncake reserves
-extra slots but marks them inactive. This lets healthy ranks poll for joiner
-metadata and activate the joiners later without reconstructing the process group.
+`GroupMemberState` has the following values:
 
-`extend_group_size_to(size)` can also increase capacity. Newly extended ranks
-start inactive; the application must call `get_peer_state()` and
-`recover_ranks()` before they participate in collectives.
+| State                | Meaning                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| `None`               | The rank has not registered with this group.                             |
+| `Inactive`           | The rank is registered but has not declared itself ready for activation. |
+| `AwaitingActivation` | The rank calls `join_group` and declares itself ready for activation.    |
+| `Active`             | The rank participates in collective operations.                          |
+| `Left`               | The rank unregistered from this group.                                   |
 
-## Elastic recovery protocol
+Founding members become `Active` directly during group bootstrap. A joining
+member's activation follows `Inactive` → `AwaitingActivation` → `Active`.
+Deactivation returns an active member to `Inactive`.
 
-Mooncake PG uses a two-phase protocol for recovery and scale-up:
+A `Healthy` rank is ready for data-plane communication, but it participates in
+a group only when its group member state is `Active`.
+
+Membership changes are checked against both kinds of state. To activate ranks,
+the group must be ready, every newly activated target must be
+`AwaitingActivation`, `Healthy`, and have a published endpoint, and every rank
+in the resulting active set must be mutually connected with every other rank in
+that set. An early activation request remains pending until these conditions
+hold or its admission timeout expires.
+
+## Architecture
+
+The data plane executes transfers directly through Mooncake Transfer Engine,
+while the control plane tracks processes, connectivity, endpoints, and
+committed membership.
 
 ```mermaid
-sequenceDiagram
-    participant H as Healthy ranks
-    participant J as Joining rank
-    participant S as Store / metadata
-
-    H->>S: init_process_group(world_size=M, max_world_size=N)
-    J->>S: init_process_group(world_size=N, is_extension=True)
-    J->>S: publish local peer metadata
-    H->>S: get_peer_state(join_ranks)
-    H->>S: recover_ranks(join_ranks)
-    S-->>J: extension state
-    J->>J: join_group() returns
-    H->>J: collectives include recovered ranks
+flowchart LR
+    Framework[Framework] --> Torch[torch.distributed]
+
+    subgraph PG[Mooncake PG]
+        Comm[Communicator]
+        Agent[Agent]
+        Coordinator[Coordinator on rank 0]
+        Workers[Collective worker and P2P proxy]
+        Comm <--> Agent
+        Agent <--> Coordinator
+        Comm --> Workers
+    end
+
+    Torch --> Comm
+    Workers --> TE[Transfer Engine]
+```
+
+### Process context and communicators
+
+Each process has one Mooncake PG context. It owns or references the Transfer
+Engine and hosts an Agent and the process-wide worker managers; global rank 0
+also hosts the Coordinator.
+
+### Coordinator and Agents
+
+The Coordinator owns process `RankState` and each group's member states.
+It serializes membership changes and publishes them as `GroupView`s. Agents
+mirror those views and apply them to local communicators. Collective and P2P
+workers report link evidence; the Coordinator derives the mutually connected
+healthy set and decides the resulting state changes.
+
+The Coordinator currently runs on global rank 0 and is not highly available.
+
+### Collectives
+
+Collectives use a direct-write design over Transfer Engine. Each communicator
+registers their send, receive, and synchronization buffers.
+The worker records transfer failures in `failed_ranks_hint` and reports to the
+Agent; membership is not changed on the collective worker side.
+
+### P2P
+
+P2P send and receive use a receiver-driven, credit-based protocol. A receive
+operation reserves chunks from a receive pool and writes `CreditSlot`s to the
+sender. Each credit identifies the destination chunk and length. The sender
+then stages the corresponding data in a send-pool chunk, performs a TE write to
+that destination, and writes an `AckSlot` back. The receiver copies the
+acknowledged chunk into the user buffer and returns the chunk to the pool.
+
+Each communicator has per-peer operation queues and separate credit and
+acknowledgement rings. The control slots carry a group epoch and sequence
+number, and a matching header/footer token prevents a partially written slot
+from being consumed. Epoch checks discard control traffic left over from an
+older group view.
+
+The send and receive polling threads and their fixed-size chunk pools are
+shared by all communicators on the same device. Chunk allocation never blocks
+a polling thread. When a pool has no free chunk, the operation remains pending
+and the poller retries it later.
+A transfer error or timeout resets the affected peer lane and reports failure
+evidence through the same control-plane path as a collective failure.
+
+## Planned scaling
+
+This section describes planned scaling through Mooncake PG dynamic membership.
+
+### Scale-up
+
+The group must have enough unused `max_group_size` capacity. A joining process
+declares an extended rank order (also `is_extension=True` in the PyTorch
+integration). The existing group adopts the appended slots as inactive; this
+step alone never activates them.
+
+The later join and activation steps are:
+
+1. The joining rank starts in `Isolated` with an effective `{self}`
+   membership. This gives the upper layer framework a local-only window for
+   initialization and warmup before the rank can affect existing members.
+   Collectives in this state must not be interpreted as results from the
+   eventual group.
+2. When local preparation is complete, the joining rank calls `join_group`.
+   The call enters `Quiescing`, drains previously issued collective and P2P
+   work, marks the member `AwaitingActivation`, and waits.
+3. Any online rank calls `activate_ranks`. The Coordinator admits the request
+   only after the activation conditions described above hold for the complete
+   future active set. It distributes the new membership and waits for the
+   required ranks to apply it; both `join_group` and `activate_ranks` then
+   return.
+
+An activation request may arrive before `join_group`; it waits for the joining
+rank to become ready rather than bypassing the checks.
+
+### Scale-down
+
+After the upper layer framework stops issuing operations that use the old
+membership, any online rank can call `deactivate_ranks` for one or more in-group
+ranks. The Coordinator changes those members from `Active` to `Inactive`,
+distributes the new membership, and waits for acknowledgements from online
+ranks in the old or new active set before returning.
+
+Deactivation does not renumber slots or mark the target process
+unhealthy. Its Agent session and data-plane links remain available; to
+participate again, that process calls `join_group` and follows the normal
+activation path.
+
+## Fault tolerance
+
+### Failure handling
+
+A failed operation reports the caller's data-plane observations to the
+Coordinator; the worker itself does not make a membership decision. The two
+caller-visible results are:
+
+- `local_success`: whether all transfers required by this operation completed
+  at the caller. A successful local result is valid for that caller, but says
+  nothing about whether the operation completed at every other rank.
+- `failed_ranks_hint`: a per-operation bitmap of length `max_group_size`,
+  indexed by in-group rank. It records the ranks for which the caller observed
+  a transfer failure; a set bit is evidence, not a global conclusion that the
+  peer is faulty.
+
+Failure hints can differ across ranks. Workers submit such observations to the
+Coordinator instead of changing membership locally.
+
+#### Reconciliation and `sync_after_failure`
+
+Negative evidence opens a reconciliation window in the Coordinator, allowing
+reports from different ranks to arrive before a single decision is made. The
+window is 30 seconds by default and must be configured to exceed the default
+collective timeout. When the window closes, the Coordinator derives the
+mutually connected healthy set, updates `RankState`, and distributes the
+result. For groups with auto-deactivation enabled, it also changes unhealthy
+active members to `Inactive`.
+
+`sync_after_failure` is both a reporting path and a synchronization point. Its
+request piggybacks the Agent's current, unacknowledged link observations. If the
+caller has just observed `local_success=false`, those observations can open or
+join the Coordinator's reconciliation window. The call then waits for any
+pending reconciliation and applies the group view returned by
+the Coordinator.
+
+With `auto_deactivate_on_failure=true`, a successful return means that the
+caller has applied the membership produced by reconciliation. Its local
+`active_ranks` therefore reflects the Coordinator's deactivation decision, and
+locally cached readiness queries such as `get_peer_state` are based on the
+reconciled state.
+
+With auto-deactivation disabled, reconciliation does not remove members, so
+the membership in the returned view may be unchanged.
+
+#### Failure-handling modes
+
+The two options control different parts of the failure path:
+
+- `auto_deactivate_on_failure` selects who owns failure-driven membership
+  changes: Mooncake PG or the upper layer framework.
+- `auto_sync_on_failure` selects whether a failed collective or P2P operation
+  calls `sync_after_failure` automatically before it completes. It does not
+  control whether the Coordinator reconciles observations or automatically
+  changes membership.
+
+With auto-deactivation disabled, an unhealthy rank may remain active. An
+`Offline` rank rejects new operations locally, whereas a `Synced` but unhealthy
+rank may still issue them. Successful transfers provide positive link evidence
+and can return a `Synced` rank to `Healthy`.
+
+There are three valid configurations.
+
+##### PG-managed, synchronized (default)
+
+```text
+auto_deactivate_on_failure = true
+auto_sync_on_failure       = true
+```
+
+After a local transfer failure, the operation reports its observations and
+automatically enters `sync_after_failure`. The Coordinator reconciles rank
+state, deactivates unhealthy members, and returns the resulting view; the
+caller applies that view before the failed operation completes. The framework
+does not need a separate synchronization or deactivation step.
+
+This is the safest and simplest mode, but it deliberately puts control-plane
+latency on the failure-completion path. A negative observation opens a
+reconciliation window, so the failed operation may remain pending for tens of
+seconds while the Coordinator reconciles reports from different ranks.
+
+##### PG-managed, deferred synchronization
+
+```text
+auto_deactivate_on_failure = true
+auto_sync_on_failure       = false
+```
+
+Mooncake PG still reconciles observations and owns the failure-driven
+deactivation decision. The difference is that the operation returns after its
+data-plane work finishes and exposes `local_success` and `failed_ranks_hint`
+without waiting for the reconciliation window. The framework may perform
+other work first and call `sync_after_failure` later, before relying on the new
+membership or resuming communication on the group.
+
+This mode is useful because `local_success` and `failed_ranks_hint` are
+data-plane results, whereas reconciliation is a much slower control-plane
+operation. It separates failure notification from membership synchronization
+without transferring the membership decision back to the framework.
+
+##### Framework-managed
+
+```text
+auto_deactivate_on_failure = false
+auto_sync_on_failure       = false
 ```
 
-Healthy rank responsibilities:
+The failed operation returns its local evidence without changing membership.
+The framework observes failures through `local_success` and
+`failed_ranks_hint`, chooses the ranks to remove, and then calls
+`deactivate_ranks`.
 
-1. Reserve capacity with `max_world_size` or `extend_group_size_to()`.
-2. Poll `get_peer_state(backend, ranks)` from all healthy ranks in a consistent
-   order.
-3. Call `recover_ranks(backend, ranks)` once candidate ranks are connected.
-4. Refresh higher-level components, such as Mooncake EP buffers, if they cache
-   transport metadata.
+##### Invalid combination
 
-Joining rank responsibilities:
+```text
+auto_deactivate_on_failure = false
+auto_sync_on_failure       = true
+```
+
+This combination is rejected at construction. Automatic synchronization is
+meaningful only when Mooncake PG also owns failure-driven deactivation;
+otherwise synchronization cannot produce an automatically updated membership
+for the failed operation.
+
+This restriction applies only to automatic synchronization.
+`sync_after_failure` may still be called manually in any mode, including when
+`auto_deactivate_on_failure=false`. The call also acts as an explicit pull of
+the Coordinator's latest group view, rather than relying only on pushed view
+updates. The framework can therefore obtain a current view while retaining its
+own deactivation policy.
+
+### Recovery
+
+A replacement process and a same-process in-place rejoin are separate ways to
+bring an inactive slot back. Both reuse the scale-up flow: restored
+connectivity can make a rank `Healthy`, but rejoining membership still requires
+`join_group` and activation.
+
+#### Replacement process
+
+A replacement registers a new Agent session for the same global rank. The
+Coordinator increments the rank epoch and invalidates the old process's link
+evidence and endpoints. The replacement recreates its local communicators in
+extension mode, starts at `Synced`, may perform local warmup while isolated,
+and then follows the normal join and activation flow.
 
-1. Initialize the process group with `is_extension=True`.
-2. Publish local peer metadata through the backend initialization path.
-3. Call `join_group(backend)` and block until healthy ranks publish extension
-   state.
-4. Re-enter normal collectives after `join_group()` returns.
+#### In-place rejoin
 
-## Subgroup semantics
+In-place rejoin applies when the process and its control-plane session remain
+alive but the rank has become inactive, commonly after a transient data-plane
+failure. Once connectivity recovers, the Coordinator can mark the rank
+`Healthy` again. The same process calls `join_group`, drains old
+work, republishes the endpoint under a fresh epoch, and
+waits for activation. No process restart is required.
 
-Mooncake PG follows PyTorch process-group ordering requirements. All processes
-that participate in a parent group should call `dist.new_group()` in a consistent
-order. This is especially important for elastic subgroups because healthy ranks
-and joining ranks must agree on store prefixes and backend indices.
+## Integration
 
-For split-rank elastic patterns, create subgroups using the current membership
-on healthy ranks and the eventual membership on joining ranks, while preserving
-the same creation order. The PG elastic tests contain executable examples of this
-pattern.
+### Choosing an integration model
 
-## Collective behavior
+An integration combines two independent choices: how planned scaling changes
+the communication group, and who owns failure-driven deactivation.
 
-Collectives use the backend active-rank state to skip inactive ranks. The exact
-implementation varies by operation and device type, but the high-level contract
-is:
+For planned scaling, framework-level group replacement creates another group
+and switches to it, so it works with a fixed-membership CCL. Mooncake PG dynamic
+membership instead keeps the same group and changes its active ranks.
 
-- active ranks participate in the collective;
-- inactive ranks are not waited on;
-- if communication detects a rank failure, active-rank state can be updated;
-- user code can read the current mask with `pg.get_active_ranks(backend)`.
+For failure handling, `auto_deactivate_on_failure` determines ownership. When
+it is `true`, Mooncake PG owns deactivation; when it is `false`, the framework
+does. `auto_sync_on_failure` is separate from ownership: it only controls
+whether a failed operation invokes `sync_after_failure` automatically and waits
+for any pending reconciliation before completing.
 
-The backend currently implements common collective APIs including all-reduce,
-broadcast, all-gather, reduce-scatter, all-to-all, barrier, reduce, gather,
-scatter, and single-tensor P2P send/recv.
+The table below summarizes the four supported combinations:
 
-## Failure and recovery boundaries
+| Scaling × Failure mode                                                                   | **PG-managed membership**<br><span style="font-weight: normal;">PG reconciles and deactivates</span>                                                                                                                                                                                 | **Framework-managed membership**<br><span style="font-weight: normal;">Framework synchronizes and decides </span>                                                                                                                                                                              |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Mooncake PG dynamic membership**<br>Keep the current group and change its active ranks | Mooncake PG commits requested scaling changes and handles failure-driven deactivation in the existing group. This fits a lean integration with minimal membership orchestration and no group rebuilds.  | The group stays in place, while the framework synchronizes after failures and submits its own deactivation decisions. This fits applications that need direct control over group membership; it uses dynamic membership without group rebuilds, but requires an explicit failure-control path. |
+| **Framework-level group replacement**<br>Create a standby/new group and switch to it     | The framework switches groups for planned scaling, while Mooncake PG handles failure-driven deactivation in the current group. This fits an existing standby-group design with minimal failure orchestration; planned scaling still incurs the cost of group creation and switching. | The framework's control plane manages both replacement groups and failure policy. This fits frameworks that already manage group lifecycle and failure policy centrally; it offers the most flexibility but requires the most orchestration.                                                      |
 
-Mooncake PG exposes low-level recovery primitives; higher-level systems are
-responsible for policy decisions such as:
+### Interfaces
 
-- which ranks are safe to replace;
-- when to stop routing traffic to a failed rank;
-- how to recreate model state on a replacement process;
-- when to refresh EP, scheduler, or application-level metadata;
-- how to coordinate subgroup recovery.
+Mooncake PG exposes a PyTorch integration and an experimental C API.
 
-Avoid assuming that `recover_ranks()` alone reconstructs all higher-level state.
-It activates the process-group communication path; the application still owns
-model weights, KV-cache state, routing policy, and request scheduling.
+Importing `mooncake.pg` registers two `torch.distributed` backends:
 
-## Testing checklist for PG changes
+- `mooncake-cpu` for CPU devices;
+- `mooncake` for the accelerator supported by the build.
 
-When modifying PG internals, run at least:
+`MooncakeBackend` derives from `c10d::ProcessGroup`, so applications use the
+usual PyTorch entry points, including `dist.init_process_group()`,
+`dist.new_group()`, `dist.all_reduce()`, and `dist.batch_isend_irecv()`.
+Mooncake-specific capacity, extension, and failure-handling options are passed
+through `MooncakeBackendOptions`.
+
+PyTorch dispatches P2P operations and some collective entry points through a
+`c10d::Backend` object. Each `MooncakeBackend` therefore registers a lightweight
+`MooncakeBackendShim` that forwards supported operations back to its owning
+`MooncakeBackend`.
+See the [Python API](../api-reference/python/ep-backend.md) for
+initialization examples and API details.
+
+Non-PyTorch integrations can use the experimental C API declared in
+[`mooncake_pg.h`](https://github.com/kvcache-ai/Mooncake/blob/main/mooncake-pg/include/mooncake_pg.h).
+
+## Contributing
+
+The PG tests are the executable contracts for current behavior:
+
+| Test file                          | Contract covered                                                                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `test_pg_init_functional.py`       | Initialization, single rank, subgroup creation, destruction, and reinitialization                                                    |
+| `test_pg_collectives.py`           | Collective coverage                                                                                                                  |
+| `test_pg_p2p.py`                   | Direct and batched P2P, ordering, multiple senders, and failure detection                                                            |
+| `test_pg_elastic.py`               | Automatic and manual failure handling, scale-up, process replacement, graceful leave, subgroup extension, holes, and in-place rejoin |
+| `test_pg_inference_topologies.py`  | TP, PP, DP, EP, and prefill/decode group layouts                                                                                     |
+| `test_pg_inference_collectives.py` | Traffic across inference-style groups                                                                                                |
+
+Run tests from the repository root:
 
 ```bash
-# CPU functional tests
+# Run all PG tests
+python -m unittest discover -s mooncake-pg/tests -v
+
+# Run CPU-only PG tests
 python -m unittest discover -s mooncake-pg/tests -k CPU -v
 
-# CUDA functional tests, when GPUs are available
+# Run CUDA PG tests
 python -m unittest discover -s mooncake-pg/tests -k CUDA -v
 
 # Collective benchmark smoke test
@@ -213,9 +524,8 @@ python mooncake-pg/benchmark/pgbench.py \
   --collective all_reduce --backend mooncake --device cuda -g 2 -b 8 -e 1M -f 2
 ```
 
-Also run elastic tests for changes that touch active ranks, metadata polling,
-subgroups, `extend_group_size_to()`, `get_peer_state()`, `recover_ranks()`, or
-`join_group()`.
+Set `MOONCAKE_PGTEST_DEVICE_FILTERS` to a comma-separated NIC/HCA list when the
+test environment needs explicit device selection.
 
 ## Related documentation
 
diff --git a/docs/source/design/mooncake-ep.md b/docs/source/design/mooncake-ep.md
index cbd977e0af..f8ec989073 100644
--- a/docs/source/design/mooncake-ep.md
+++ b/docs/source/design/mooncake-ep.md
@@ -16,7 +16,7 @@ Mooncake EP is designed to:
 - keep the Python programming model close to DeepEP low-latency mode;
 - use Mooncake device transports for fast intra-node and inter-node movement;
 - detect failed source ranks through timeout-aware kernels;
-- interoperate with Mooncake Backend (PG) for bootstrap metadata exchange and
+- interoperate with Mooncake PG for bootstrap metadata exchange and
   rank-health state.
 
 ## High-level data flow
@@ -232,16 +232,16 @@ Useful entry points:
 
 ```bash
 # EP grid correctness test
-python mooncake-ep/tests/test_ep_grid.py
+python python/tests/ep/test_ep_grid.py
 
-# Wheel-level EP smoke test
-python mooncake-wheel/tests/test_mooncake_ep.py
+# EP wrapper smoke test
+python python/tests/ep/test_mooncake_ep.py
 ```
 
 Adapt launch commands to the target environment and number of GPUs.
 
 ## Related documentation
 
-- [Mooncake Backend (PG) design](mooncake-backend-pg.md)
+- [Mooncake PG design](mooncake-backend-pg.md)
 - [Python API reference](../api-reference/python/ep-backend.md)
 - [PG/EP troubleshooting](../troubleshooting/pg-ep-troubleshooting.md)
diff --git a/docs/source/design/mooncake-reshard/index.md b/docs/source/design/mooncake-reshard/index.md
new file mode 100644
index 0000000000..bf529efdb1
--- /dev/null
+++ b/docs/source/design/mooncake-reshard/index.md
@@ -0,0 +1,14 @@
+# Mooncake Reshard
+
+`mooncake-reshard` plans address-free conversions between complete resource
+placements, then binds the selected logical regions to immutable runtime
+snapshots.
+
+:::{toctree}
+:maxdepth: 1
+
+reshard-manifest
+model-weight-reshard-planner
+model-weight-store-upload-planning
+weight-management
+:::
diff --git a/docs/source/design/mooncake-reshard/model-weight-reshard-planner.md b/docs/source/design/mooncake-reshard/model-weight-reshard-planner.md
new file mode 100644
index 0000000000..eb8c689b7a
--- /dev/null
+++ b/docs/source/design/mooncake-reshard/model-weight-reshard-planner.md
@@ -0,0 +1,166 @@
+# Model Weight Reshard Planner And Runtime Binding
+
+`mooncake-reshard` plans an address-free conversion between complete model
+weight placements, then binds the selected logical regions to immutable
+runtime snapshots. It does not inspect framework runtime objects or submit a
+transfer.
+
+## Inputs and Output
+
+The source is either a complete `WeightPlacementManifest` or a committed
+`StoredWeightManifest` snapshot. The target is a complete
+`WeightPlacementManifest`. Both sides must identify the same resource,
+revision, and weight generation.
+
+The public APIs are:
+
+- `plan_placement_transfer(source_placement, target_placement)`;
+- `plan_placement_transfer_to_local_target(source_placement,
+  target_placement, target_participant_id)`;
+- `plan_stored_transfer_to_target_placement(source_manifest,
+  target_placement)`.
+
+Each API returns a `LogicalTransferPlan`. It contains only canonical tensor
+descriptors, selected placement participants, and logical regions. It contains
+no GPU address, endpoint, allocation range, lease, or backend handle.
+
+`bind_logical_transfer_plan(logical_plan, target_bindings, ...)` is the second
+public step. It accepts typed `WeightRuntimeBindingManifest` values and returns
+a `TransferPlan` with selected runtime fragments, binding attestations, and
+executor projections. A Store source is represented by a persistent
+`StoredFragmentSnapshot`; a live runtime executor carries an ephemeral
+`RuntimeFragmentSnapshot` for each selected fragment.
+For a Store source, `TransferPlan` retains the authoritative canonical
+`StoredWeightManifest` and its `StoredManifestIdentity.content_sha256`. Each selected
+operation source is revalidated against that committed manifest during plan
+construction and restore. The selected-fragment cache is derived state, so a
+coordinated operation/cache mutation cannot redirect a plan to another Store
+object.
+
+## N-D Regions
+
+Each `TransferRegion` represents one source/target N-D box overlap. It records
+the overlap offset and shape, source and target base byte offsets, contiguous
+`inner_bytes`, outer loop counts, and source/target byte strides.
+
+The planner preserves a compact strided representation. It does not expand a
+cross-dimension overlap into one operation per row or element. `PlanningLimits`
+bounds the total number of regions and any later segment expansion fails closed
+when it exceeds the configured limit.
+
+## Parallel Semantics
+
+- **TP** changes logical boxes. The same overlap algorithm handles split,
+  merge, and source/target sharding on different dimensions.
+- **PP** is explicit framework-provided tensor or layer ownership. Regions are
+  grouped by source and target PP owner and optional pipeline stage; the
+  planner does not infer ownership from a tensor name or layer-count formula.
+- **EP** is represented by a logical expert coordinate. Independent expert
+  allocations remain independent logical fragments and are never packed or
+  all-gathered by the planner.
+- **DP** does not change tensor geometry. A `ReplicatedAxis(kind="dp")` uses a
+  complete source replica. An `OwnershipAxis(kind="dp")` routes each tensor
+  through its declared owner and does not require every tensor on every DP
+  rank.
+
+All four axes are resolved by one logical-box plan, rather than by model-wide
+per-axis conversion passes.
+
+### Supported axes and Store API selection
+
+The current `ParallelTopology` and `ParallelRank` types contain TP, PP, EP, and
+DP only. CP (context parallelism) is not a supported axis, and `SplitAxis`
+accepts only TP and EP. N-D logical planning therefore does not imply support
+for arbitrary named parallel strategies or CP-aware KV-cache layouts.
+
+Store callers use the manifest-backed weight snapshot lifecycle for these
+multi-axis weight placements. Legacy `*_with_tp` methods remain available for
+ordinary TP tensor objects, but there are no corresponding CP/DP/EP/PP method
+factories or `*_with_config` tensor methods. The former public
+`*_with_parallelism` family was removed by
+PR [#3772](https://github.com/kvcache-ai/Mooncake/pull/3772).
+See {ref}`Choosing a Parallel Tensor IO API <choosing-a-parallel-tensor-io-api>`
+for entry points and the distinction between parallel topology and Store
+replication configuration.
+
+## Validation
+
+Placement construction validates the complete participant set, tensor
+descriptors, topology, and logical coverage before planning. Planning then
+fails closed when source and target tensor identity, dtype, shape, layout
+fingerprint, ownership, or coverage differ.
+
+A `StoredWeightManifest` source is retained as an immutable logical snapshot. Its
+canonical identity and selected stored fragments are revalidated whenever a
+logical plan is constructed or reconstructed. This proves that the plan still
+refers to the same Store snapshot; it does not make Store persistence or
+runtime loading part of this layer.
+
+Coverage validation uses an ordered interval scan for 1-D inputs and a
+coordinate-compressed sweep for 2-D inputs, both with `O(N log N)` behavior.
+For 3-D and higher logical boxes, exact intersection remains supported under an
+explicit pairwise-comparison budget; inputs that exceed it fail closed rather
+than making validation work unbounded.
+
+## Runtime Binding
+
+Binding rechecks the exact source and target placement identities, placement
+digests, participant selection, runtime fragment geometry, device/allocation
+bounds, lease generation, and declared alias scope. It rejects a reconstructed
+logical plan with incomplete target coverage, forged Store fragments, or
+conflicting physical target ranges.
+
+The returned `TransferPlan` is a bound, attested snapshot. It has no `execute`
+or `submit` operation. `RuntimeBindingAttestation` stores owner-free
+`RuntimeBindingEvidence`: view geometry, worker/endpoint/device, backing
+allocation range, lease, and generation. Framework allocation owners remain at
+the runtime submission boundary, where a later Transfer Engine executor
+acquires its allocation guard and revalidates bindings atomically with
+submission.
+
+Transfer Engine lowering, DMA submission, Store persistence/lifecycle, and
+framework activation remain outside this phase. Framework adapters own model
+semantics and conversion into canonical manifests; Mooncake core does not infer
+those semantics from framework objects or parameter names.
+
+## Reproducible Contract Benchmark
+
+The following opt-in benchmark measures only Python-side planning and binding
+contracts. It creates synthetic manifests and runtime bindings but does not
+allocate GPU memory, contact Store, or submit work to Transfer Engine:
+
+```bash
+PYTHONPATH=mooncake-reshard/python \
+  python mooncake-reshard/benchmarks/runtime_binding.py
+```
+
+The fixed topology is source `TP4/PP1/EP1/DP2` to target
+`TP8/PP2/EP2/DP1`: 8 source fragments, 8 target fragments, and 8 logical
+operations. Only the selected source DP replica appears in the bound executor
+projection. It reports medians for logical planning, runtime binding,
+`TransferPlan` revalidation, pickle serialization and restore, binding peak
+memory, and a 128-region/16,384-segment physical-validation workload. It also
+compares selected and complete source projections, and records accepted and
+rejected logical and physical segment budgets. Results are metadata costs only
+and must not be interpreted as TE, Store, G2G, or serving end-to-end
+throughput.
+
+## Store Adapter Boundary
+
+This phase does not accept Store `with_parallelism` metadata or Store keys as a
+planner input. A future Store adapter must translate one committed Store
+snapshot into a complete canonical `StoredWeightManifest` or
+`WeightPlacementManifest`, including tensor identity and descriptor, every
+logical fragment's offset, shape, object range, and all TP, PP, EP, and DP
+semantics. If Store metadata cannot represent any required fact, the adapter
+must reject that snapshot; it must not infer a tensor layout from a key,
+parameter name, rank, or `mode="full"` reconstruction.
+
+In particular, the current Store `validate_parallelism_spec()` representation
+accepts a TP `split_dim`, but an EP axis requires an `expert_id` and rejects a
+`split_dim`. It cannot losslessly encode a planner
+`SplitAxis(kind="ep", dim=0)`. A Store-backed source with that layout is
+therefore unsupported until the Store encoding is extended or the adapter has
+an additional authoritative canonical manifest. This is an explicit
+fail-closed limitation, not a request for the adapter to materialize or
+all-gather a full tensor.
diff --git a/docs/source/design/mooncake-reshard/model-weight-store-upload-planning.md b/docs/source/design/mooncake-reshard/model-weight-store-upload-planning.md
new file mode 100644
index 0000000000..9d5fdcb777
--- /dev/null
+++ b/docs/source/design/mooncake-reshard/model-weight-store-upload-planning.md
@@ -0,0 +1,85 @@
+# Model Weight Store Upload Planning
+
+`plan_weight_upload` turns one complete runtime weight placement into an
+immutable `WeightUploadPlan`. The plan supplies the Store writer with a
+canonical `StoredWeightManifest`, payload object locations, and source
+evidence for each upload operation.
+
+## Inputs
+
+- `WeightPlacementManifest` describes global tensor geometry and TP, PP, EP,
+  and DP ownership.
+- `WeightRuntimeBindingManifest` values provide the live source bindings for
+  populated placement participants.
+
+The planner validates every supplied binding against the placement. Model
+semantics remain in framework adapters, which export canonical tensor and
+parallel-axis metadata before calling this API.
+
+## Replica Selection
+
+The planner stores one complete source replica:
+
+1. It requires replicated DP semantics and a complete logical coverage for a
+   DP replica.
+2. It requires every selected source binding in that replica to have the same
+   generation.
+3. It selects the lowest eligible DP rank deterministically.
+4. It retains logical TP, PP, and EP ownership in every selected fragment.
+
+The resulting manifest has one stored fragment per selected logical source
+fragment. DP replicas do not duplicate payload objects.
+
+## Plan Contents
+
+`WeightUploadPlan` contains:
+
+- a `StoredWeightManifest` with immutable Store group, manifest, and payload keys;
+- an `UploadOperation` for each stored fragment;
+- the source placement identity and digest;
+- an upload transaction group and its control key.
+
+An operation stores an owner-free `RuntimeFragmentSnapshot`, source
+participant and instance IDs, lease ID, and generation. The payload writer
+rebinds this evidence to a fresh runtime manifest and acquires the framework
+allocation guard before Store I/O.
+
+## Execution Boundary
+
+The Store writer performs payload writes, registration, transaction commit/abort,
+and Store-to-runtime reads. These layers consume `WeightUploadPlan`; they do
+not infer model layouts or parallelism from Store keys.
+
+## Snapshot API
+
+`MooncakeDistributedStore.begin_weight_snapshot(descriptor, adapter)` returns
+one `WeightStoreWriter`. The framework adapter exports the complete source
+placement and live bindings once. The caller then writes each framework tensor
+through `writer.write_tensor(tensor_id, tensor)`.
+
+The adapter maps that tensor to canonical placement fragment IDs. The writer
+uploads only the runtime fragments attested by those bindings and
+`commit()` publishes one `StoredWeightManifest` after every required fragment
+is durable.
+
+The writer owns the storage policy for its immutable payload and metadata
+objects. Per-tensor replication, partition, and upsert parameters are outside
+this API, so every committed snapshot has one explicit manifest contract.
+
+Restore begins from `StoredWeightManifest`. The loader reconstructs sources
+from each stored fragment's tensor ID, global offset, local shape, object key,
+object offset, and byte length, then uses `get_into_ranges` with the target
+placement and runtime binding. This path uses no legacy `TensorMetadata` head
+or legacy parallel-tensor reconstruction metadata.
+
+The persisted manifest contains logical tensor descriptors, fragment geometry,
+payload keys, and snapshot identity. Runtime addresses, allocation owners,
+leases, and worker instances remain in the live binding and allocation-guard
+path used during Store I/O.
+
+## Native Store Requirement
+
+The native Store writer uses group semantics to keep payload, manifest, and
+transaction-control objects in their declared groups. It requires a Mooncake wheel
+whose `ReplicateConfig` exposes `group_ids` (the API introduced by PR #3000).
+The adapter rejects an older binding before Store I/O starts.
diff --git a/docs/source/design/mooncake-reshard/reshard-manifest.md b/docs/source/design/mooncake-reshard/reshard-manifest.md
new file mode 100644
index 0000000000..1b310234c9
--- /dev/null
+++ b/docs/source/design/mooncake-reshard/reshard-manifest.md
@@ -0,0 +1,181 @@
+# Resource Reshard Manifest Contract
+
+This document defines the framework-neutral resource contract used by
+Mooncake resharding and its model-weight specialization. The contract separates
+complete logical placement from live physical addresses so planning can finish
+before a runtime binding is available.
+
+The implementation is owned by the top-level `mooncake-reshard` module. Common
+contracts are exposed through `mooncake.reshard.contracts`; the public weight API
+is `mooncake.reshard.weight`.
+
+Framework-owned adapters outside Mooncake inspect framework runtime objects,
+normalize framework-specific values, and construct the typed canonical
+manifests. Mooncake core accepts only those typed values; it does not import or
+inspect framework objects or accept alternate field names or duck-typed
+records.
+
+## Contract Split
+
+| Contract | Contents | Lifetime |
+|----------|----------|----------|
+| `ResourceManifest` | structural protocol for resource identity and kind | shared public contract |
+| `PlacementManifest` | structural protocol for address-free placement identity and digest | serializable and reusable |
+| `RuntimeBindingManifest` | structural protocol for placement attestation, runtime instance, generation, and lease | one live runtime snapshot |
+| `ParallelTopology` | TP/PP/EP/DP sizes and the explicit participant-to-rank mapping | one logical placement |
+| `SplitAxis` | a parallel kind that shards one explicit logical dimension | one tensor descriptor |
+| `ReplicatedAxis` | a parallel kind whose ranks each hold a complete replica | one tensor descriptor |
+| `OwnershipAxis` | a parallel kind that assigns tensor or object ownership without splitting a dimension | one tensor descriptor |
+| `WeightPlacementPart` | one participant's address-free tensors and logical fragments | framework-local contribution |
+| `WeightPlacementManifest` | one complete global logical placement of a weight generation | serializable and reusable |
+| `WeightRuntimeBindingManifest` | one participant's physical fragments for that global placement | one live runtime snapshot |
+
+The three common manifest contracts are public structural `Protocol` types.
+Consumers depend on their fields and behavior, not inheritance from a Mooncake
+base class.
+
+Weight revision, tensor geometry, model semantics, parallel ownership, and
+weight generation belong to the weight specialization. GPU addresses,
+endpoints, owners, generations, and leases never appear in
+`WeightPlacementManifest`.
+
+`model_weight` is the serialized resource discriminator. Typed manifests carry
+their `ResourceKind` explicitly; Mooncake does not infer a resource or model
+type from parameter names.
+
+## Global Placement Assembly
+
+`ParallelTopology` declares the runtime's TP, PP, EP, and DP sizes and the exact
+participants selected for this placement. Its `world_size` is the number of
+declared participants, not `tp_size * pp_size * ep_size * dp_size`. Frameworks
+may map axes such as TP and EP onto the same workers, and a placement may select
+one DP replica while retaining the runtime's declared `dp_size`.
+
+For each participant, the framework adapter constructs one typed
+`WeightPlacementPart`. A part carries the common resource ID, revision, weight
+generation, placement-set ID, topology ID, participant ID, parallel rank,
+tensor descriptors, and logical fragments. It contains no physical address. A
+part declares exactly the tensor descriptors referenced by its fragments; an
+empty part declares neither.
+
+A collection barrier assembles all declared parts into one
+`WeightPlacementManifest`. Assembly fails when a participant is missing or
+duplicated, when a part belongs to a different resource, generation, placement
+set, or topology, or when its rank disagrees with the topology. Only after the
+complete placement validates are its canonical `placement_id` and digest
+available.
+
+For each live participant, the framework adapter then constructs a typed
+`WeightRuntimeBindingManifest` that names its `participant_id` and attests the
+same global `placement_id` and digest. Binding-set validation requires every
+participant that owns fragments exactly once, and exact logical-fragment
+membership for each such participant. Empty participants require no runtime
+binding.
+
+## Logical Semantics
+
+Each tensor has a stable `tensor_id`, full `global_shape`, dtype, item size,
+layout fingerprint, and optional layer or expert identity. Each fragment is an
+N-D logical box described by `global_offset` and `local_shape`.
+
+`TensorDescriptor.shard_dims` is the only canonical shard representation.
+`SplitAxis(kind, dim)` explicitly shards one logical dimension;
+`ReplicatedAxis(kind)` requires each selected rank to provide a complete copy;
+and `OwnershipAxis(kind)` assigns tensor or object ownership without splitting
+a logical dimension. Axis size comes from `ParallelTopology`, and a fragment's
+axis rank comes from `ParallelRank`. The dimensions named by all `SplitAxis`
+values must match `shard_dims` exactly.
+
+The global manifest validates complete logical coverage. Every selected DP
+replica must provide a gap-free cover of every tensor. `OwnershipAxis` and
+`ReplicatedAxis` values form independent covers. Fragments across a `SplitAxis`
+instead form one non-overlapping cover, and every split-axis rank declared by
+the topology must participate. The explicit participant mapping defines the
+selected workers and may be non-Cartesian overall. Within one tensor's owner and
+replica cover, however, coordinates for multiple declared `SplitAxis` values
+must form their Cartesian product so that each rank-to-dimension assignment is
+provable. A physical coordinate coupled to another split rank but not
+independently sharding the tensor is left out of that tensor's `parallel_axes`.
+DP may therefore select one complete replica for transfer while the topology
+retains the original `dp_size`.
+
+PP is layer or tensor ownership. A logical tensor may have complete replicas on
+multiple PP owners, but every owner must independently provide a gap-free
+cover; fragments from different PP owners cannot be combined to satisfy
+coverage. For grouped expert tensors, EP uses `SplitAxis` on the leading logical
+expert dimension rather than only an EP rank label. Independently allocated
+experts use `OwnershipAxis` and remain independent tensors with an explicit
+expert identity.
+
+Mooncake does not infer layer, expert, layout, or partition semantics from
+model parameter names. Framework adapters must provide those facts.
+
+`placement_fragment_id` defaults to a canonical hash of tensor identity,
+logical box, parallel rank, byte size, and alias group. Frameworks may supply
+an explicit stable ID when they intentionally need a different identity. An
+alias group is valid only when it contains the fragment's own `tensor_id`; two
+fragments may share one runtime range only when both tensor IDs belong to the
+same compatible alias group.
+
+Because an alias group can cross placement participants, a local
+`WeightPlacementPart` validates only its own fragments. Complete
+`WeightPlacementManifest` assembly is the authorization boundary: every alias
+member must be in the global tensor catalog and every fragment of every member
+must declare the same alias group before any runtime binding is accepted.
+
+## Identity And Fencing
+
+Canonical placement identity covers the resource, revision, weight generation,
+placement-set ID, topology, global tensor descriptors, participant ownership,
+and logical fragments. Runtime addresses, workers, endpoints, owners, and
+leases do not affect placement identity.
+
+Every runtime binding carries the global placement ID and digest. Validation
+rejects a binding when the logical placement changes, a participant is unknown,
+a fragment is missing or unexpected, or its byte range differs. Generation and
+lease fences remain live-runtime state and must be checked before transfer.
+
+Every runtime `address` points to the first transferable byte of a contiguous
+tensor view. A runtime fragment preserves `itemsize`, `local_shape`, byte
+strides normalized on singleton dimensions, storage base address, normalized
+storage byte offset, and storage allocation size. Binding validation compares
+item size, shape, and contiguous
+row-major byte strides with the logical placement; singleton dimensions do not
+constrain their corresponding stride. It also verifies
+`address = storage_address + storage_offset_bytes`, and requires the complete
+view range to remain inside the allocation. An optional
+framework `is_contiguous` flag may reject a view early but is never accepted as
+the sole proof of contiguity. Address zero is reserved as a null sentinel, and
+all address ranges must have representable unsigned 64-bit exclusive ends.
+Owner objects may keep framework allocations alive but are never serialized.
+
+## Integration Flow
+
+1. A framework-owned adapter reads framework state and constructs one typed
+   `ParallelTopology` plus the shared resource, revision, weight generation,
+   and placement-set ID.
+2. The adapter constructs one typed `WeightPlacementPart` for every selected
+   participant.
+3. A barrier collects the exact part set and constructs one complete
+   `WeightPlacementManifest`.
+4. The adapter constructs a typed `WeightRuntimeBindingManifest` for each live
+   participant against the resulting placement ID and digest.
+5. Planning consumes one source and one target `WeightPlacementManifest`.
+6. Binding and execution use only the participant bindings referenced by the
+   logical plan, while preserving their generation and lease fences.
+
+`weight_placement_to_json` and `weight_placement_from_json` are the explicit
+public JSON APIs for the canonical wire schema. Deserialization accepts exactly
+the canonical fields and values; it does not accept aliases, attribute-based
+records, or other framework-shaped inputs. Integer-valued contract fields
+require Python `int` values and reject `bool`; framework adapters must normalize
+framework-specific scalar types before constructing a manifest.
+
+## Boundaries
+
+The manifest contract does not inspect framework objects, infer model semantics,
+synthesize framework placements, execute transfers, or define discovery,
+activation, rollback, and other control-plane policies. Framework adapters own
+object inspection and normalization. Planner, Store, and Transfer Engine
+adapters consume the resulting canonical manifests without changing their
+logical identity rules.
diff --git a/docs/source/design/mooncake-reshard/weight-management.md b/docs/source/design/mooncake-reshard/weight-management.md
new file mode 100644
index 0000000000..bf4fc67b65
--- /dev/null
+++ b/docs/source/design/mooncake-reshard/weight-management.md
@@ -0,0 +1,182 @@
+# Weight Management Architecture
+
+Mooncake Store manages one immutable model-weight revision as a first-class
+resource. A caller discovers the revision by its exact identity, acquires a
+revision lease, resolves its immutable manifest, and then transfers the
+manifest's payload ranges. Callers do not need to know the manifest object key
+in advance.
+
+This design adds revision-level discovery and lifecycle control without adding
+independent tensor-level management metadata.
+
+## Delivery Status
+
+The first implementation stage introduces the weight-management contracts and
+the standalone `WeightMetadataStore` state machine. Master integration, HA
+replication, managed payload-group operations, and client RPCs are delivered
+as follow-up changes. The state machine is intentionally independent of tensor
+geometry and physical placement so those integrations do not redefine its
+metadata contract.
+
+## Authority Model
+
+Three records have distinct authority:
+
+| Authority | Location | Owns | Does not own |
+| --- | --- | --- | --- |
+| Weight Metadata Store | Store Master memory, HA OpLog, and Master snapshot | exact revision discovery, availability, residency summary, operation progress, revision leases, manifest reference | tensor geometry, payload contents, physical replica addresses |
+| `StoredWeightManifest` | immutable Store `METADATA` object | tensor descriptors and tensor-fragment-to-object-range mapping | lifecycle state, leases, live runtime addresses |
+| Store object metadata | existing per-key Master metadata | replica placement and status in memory, local disk, DFS, or NoF | revision discovery, tensor meaning, serving activation |
+
+```mermaid
+flowchart TD
+    C[Weight Metadata Store record] -->|manifest key and SHA-256| M[StoredWeightManifest]
+    C -->|payload group ID| G[Store group]
+    M -->|fragments: object key, offset, bytes| P[Weight payload objects]
+    G --> M
+    G --> P
+    P --> O[Per-object replica metadata]
+    M --> O
+```
+
+The metadata record stays outside the payload group. It therefore remains
+discoverable while the group is cold, degraded, deleting, or physically
+absent. The manifest and every payload object share one `payload_group_id`.
+Generic eviction and removal paths recognize that group as managed and cannot
+independently reclaim one member.
+
+The group is a logical lifecycle boundary, not a distributed transaction.
+Physical work may be partial while an operation is running. The metadata store keeps
+the operation non-terminal until reconciliation observes the required state
+for every member.
+
+## Revision Identity and Manifest Location
+
+A revision is addressed by:
+
+```text
+(tenant_id, namespace, resource_id, revision, weight_generation)
+```
+
+Its manifest object key is canonical:
+
+```text
+weights/<namespace>/<resource_id>/<revision>/<weight_generation>/manifest
+```
+
+`WeightMetadataStore` validates that the payload group ID and manifest key are
+the canonical values derived from the revision identity. The Master integration
+separately validates those references against physical Store object type,
+membership, count, logical bytes, and payload-key digest.
+
+The three textual path components are UTF-8 URL-encoded as individual path
+segments. The manifest is hard-pinned during import and stored as
+`ObjectDataType::METADATA`. Payload fragments are stored as
+`ObjectDataType::WEIGHT` in the same group.
+
+After publication, the manifest key, manifest SHA-256, payload group ID,
+payload-key SHA-256, payload count, and logical byte count are immutable.
+The Master validates object type, exact group membership, count, logical
+bytes, and the digest of sorted payload keys. It deliberately does not parse
+the tensor manifest body. A consumer must verify the stored manifest's identity
+and SHA-256 before planning tensor ranges.
+
+## State Model
+
+Availability, physical residency, and an in-progress operation are separate:
+
+| Dimension | Values | Meaning |
+| --- | --- | --- |
+| Availability | `IMPORTING`, `READY`, `DEGRADED`, `DELETING`, `DELETED` | whether the complete revision is safe to discover and load |
+| Residency | `UNKNOWN`, `HOT`, `COLD`, `MIXED`, `ABSENT` | observed placement across required group members |
+| Operation | `NONE`, `EVICTING`, `REHYDRATING`, `REPAIRING` | durable non-terminal group work |
+
+`READY` means the manifest and every required payload object have a readable
+replica. DRAM eviction changes residency but does not by itself make a revision
+unavailable. Missing required members produce `DEGRADED`; complete physical
+removal produces the retained `DELETED`/`ABSENT` tombstone.
+
+Every mutation is fenced by `expected_metadata_generation`. A stale writer
+fails with `STALE_GENERATION`. A retry of an uncertain import commit with the
+same generation and immutable manifest reference is idempotent.
+
+## Import and Publication
+
+The managed upload sequence is:
+
+1. `BeginWeightImport` creates or returns the `IMPORTING` metadata record and
+   Store-issued canonical payload group ID.
+2. `WeightStore` writes every payload object into that group.
+3. The immutable `StoredWeightManifest` is committed last into the same group.
+4. `CommitWeightImport` validates exact group membership and the manifest
+   reference, then durably publishes `READY`.
+5. `GetWeightRevision` or bounded `ListWeightRevisions` can discover it.
+
+`READY` is never inferred from key prefixes. An abandoned import is handled by
+the explicit abort/reconciliation policy.
+
+## Load and Revision Leases
+
+A reader first resolves the exact metadata identity with `GetWeightRevision`
+and acquires a revision lease against the returned metadata generation. It then
+reads and validates the manifest, plans ranges, and executes Store-to-runtime
+transfers. The caller renews short leases until all transfer work reaches a
+terminal state and releases the lease on both success and failure.
+
+A live revision lease blocks deletion and residency operations that could
+remove the last readable replica. Revision leases do not replace framework
+allocation guards, runtime binding generations, or Store's per-object read
+leases; those protect different ownership boundaries.
+
+## Residency, Rehydration, and Deletion
+
+`StartWeightResidencyOperation` durably records the operation ID, target,
+fenced metadata generation, and progress. Reconciliation then uses existing
+per-object primitives:
+
+- `EVICTING` removes memory replicas only after a readable cold replica exists
+  for each affected member;
+- `REHYDRATING` queues promotion for every group member and waits until all
+  required members have readable memory replicas;
+- busy or incomplete members keep the operation in progress;
+- deletion blocks new leases, waits for live leases, removes payload objects,
+  removes the manifest last, verifies absence, and retains a tombstone.
+
+Generic `BatchEvict`, quota eviction, explicit remove, and cleanup paths skip
+managed groups. Only the weight lifecycle path may change their aggregate
+residency or availability.
+
+## Recovery and HA Rollout
+
+Weight metadata, leases, and operation records use durable-before-visible
+OpLog publication. Standby replay stores them in a separate weight-metadata
+namespace rather than encoding them as fake object metadata. Master snapshots
+carry an optional `weight_metadata` section; an older snapshot without the
+section restores empty Weight metadata while preserving ordinary KV metadata.
+Derived group indexes are rebuilt from restored metadata records.
+
+Clusters using HA plus the etcd batch OpLog fail closed for weight-management
+mutations unless the operator sets
+`weight_management_oplog_capability_confirmed=true`. Set it only after every
+configured standby runs a version that understands all weight metadata and
+lease OpLog entries. This is an explicit rolling-upgrade capability assertion,
+not automatic standby discovery. Reads and ordinary KV operations are not
+gated by it.
+
+## Serving-System Boundary
+
+Store owns durable revision discovery, readable-residency state, leases, and
+safe reclamation. SGLang or another runtime owns live GPU addresses, runtime
+bindings, allocation guards, and worker-local snapshot generations. Slime,
+Kubernetes, Ray, or another serving control plane owns multi-worker activation,
+traffic switching, and rollback. Store does not choose a globally active
+serving revision.
+
+## Integration Boundary
+
+Follow-up changes expose the lifecycle primitives through the Master RPC and
+C++ client surfaces, then add a managed `WeightStore` Python facade for
+manifest upload and load. Framework adapters remain responsible for building
+and validating tensor manifests, holding runtime allocation guards, and
+activating revisions. Manifest-only objects without a Weight metadata record
+remain outside this lifecycle.
diff --git a/docs/source/design/store/engram.md b/docs/source/design/store/engram.md
new file mode 100644
index 0000000000..fb596843f3
--- /dev/null
+++ b/docs/source/design/store/engram.md
@@ -0,0 +1,225 @@
+# EngramStore Backend
+
+Mooncake provides EngramStore as the storage backend for Engram embedding tables.
+
+The scope is intentionally narrow:
+
+- the caller defines the physical table layout
+- the caller uploads one table per head
+- the caller provides precomputed row ids with shape `[B, L, H]`
+- Mooncake writes selected rows into caller-owned `[B, L, H, row_bytes]` memory
+
+Mooncake does not implement tokenizer compression, N-gram hashing, query logic,
+or any other model-side Engram algorithm.
+
+## Current Backend Boundary
+
+EngramStore uses the existing `batch_put_from`, `batch_query`, and
+`get_into_ranges` Store interfaces. It stores one object per head and reads only
+the requested byte ranges. Lookup is synchronous; the Python binding releases
+the GIL during I/O. There is no model-specific hashing or GPU execution here.
+
+## Configuration
+
+`EngramStore` manages all Engram layers of a model. Its constructor accepts a
+map from layer ID to `EngramStoreConfig`; each config describes one layer:
+
+- `table_vocab_sizes`: per-head table sizes `[N_0, N_1, ..., N_{H-1}]`
+- `row_bytes`: required positive byte width of each row; the default `0` must be set before constructing the store
+
+```python
+layer1 = EngramStoreConfig()
+layer1.table_vocab_sizes = [17, 19]
+layer1.row_bytes = 264
+layer14 = EngramStoreConfig()
+layer14.table_vocab_sizes = [23, 29]
+layer14.row_bytes = 264
+table = EngramStore({1: layer1, 14: layer14}, store)
+```
+
+The constructor copies layouts and creates no stored data. Each layer may have
+different head counts, table sizes and row widths. For `layer_id`, Mooncake
+generates one store key per head:
+
+```text
+engram:l{layer_id}:h{head_idx}
+```
+
+Each key stores a contiguous `uint8` table with shape `[N_h, row_bytes]`.
+The backend treats rows as opaque bytes. Callers pack and interpret embedding
+values and any quantization scales. For example, a DeepSeek-V4.1 hash-head row
+contains 256 FP8 bytes followed by 8 E8M0 scale bytes, so `row_bytes = 264`.
+There is no dtype mode or configurable key prefix. Models with overlapping layer
+IDs need separate Store deployments or explicit removal before replacement.
+
+## Public Interface
+
+Python:
+
+- `EngramStore(layers, store=None)`
+- `populate(layer_id, embedding_buffers, config=ReplicateConfig())`
+- `bind_local(layer_id, embedding_buffers)`
+- `lookup_into(layer_id, row_ids, output)`
+- `remove_from_store(layer_id, force=False)`
+- `get_layer_ids()`
+- `get_table_vocab_sizes(layer_id)`
+- `get_store_keys(layer_id)`
+- `get_num_heads(layer_id)`
+- `get_row_bytes(layer_id)`
+
+The Python `store` argument accepts the existing `MooncakeDistributedStore`
+wrapper, or `None` for metadata-only construction or local table binding.
+
+### Local table mode
+
+Construct without a Store client and bind immutable, contiguous `uint8` tables
+before starting lookup workers:
+
+```python
+table = EngramStore({1: layer1})
+heads = [np.memmap(path, mode="r", dtype=np.uint8, shape=(rows, layer1.row_bytes))
+         for path, rows in zip(paths, layer1.table_vocab_sizes)]
+table.bind_local(1, heads)
+table.lookup_into(1, row_ids, output)
+```
+
+This mode copies selected rows directly from CPU-addressable memory into output;
+it performs no Store metadata queries, registration, or network transfers. The
+Python binding retains the supplied list and arrays. Do not change that list,
+modify/resize the arrays, or truncate/unmap their backing files while bound.
+Binding a layer twice, binding with a Store client, and lookup of an unbound
+layer are rejected. C++ callers retain ownership of the bound memory.
+
+Same-host ranks can map the same immutable tmpfs files to share physical pages
+without RDMA. Each rank still owns its staging output. Merely placing data in
+another process on the same host does not make that process's pointers locally
+addressable. Use separate directories for separate model instances.
+
+For large memory-mapped tables, consider prefaulting the mappings at startup
+(for example, with Linux `MAP_POPULATE`). Resident file pages can still require
+per-process page-table faults on first access, delaying random row lookups.
+
+C++:
+
+- constructor `EngramStore(const std::map<int, EngramStoreConfig>& layers, std::shared_ptr<PyClient>)`
+- `populate(...)`
+- `lookup_into(int layer_id, const int64_t* row_ids, int B, int L, void* output, size_t output_size)`
+- `remove_from_store(...)`
+- metadata getters matching the Python surface
+
+## Data Contract
+
+Populate expects one C-contiguous NumPy `uint8` array per head; it does not
+cast numeric arrays to bytes:
+
+```text
+embedding_buffers[h].shape == [N_h, row_bytes]
+```
+
+`lookup_into` requires a C-contiguous NumPy `int64` row-ID array with shape
+`[B, L, H]` and caller-owned, writable C-contiguous `uint8` output:
+
+```text
+output.shape == [B, L, H, row_bytes]
+```
+
+It writes output in place and returns `None`. Neither argument is implicitly
+converted. The explicit `layer_id` selects a configured layer; position
+`h` in the last row-ID dimension selects `engram:l{layer_id}:h{h}`.
+
+For Store-backed reads, the caller must register the entire output buffer with the same Store client
+before the first nonempty lookup, keep it registered throughout each call, and
+unregister it when finished. `lookup_into` does not allocate, register, or
+unregister output; there is no registration flag or automatic-registration mode.
+An empty batch is a no-op and does not require registration.
+
+```python
+output = np.empty((*row_ids.shape, table.get_row_bytes(layer_id)), dtype=np.uint8)
+assert store.register_buffer(output.ctypes.data, output.nbytes) == 0
+try:
+    table.lookup_into(layer_id, row_ids, output)  # Repeat using this buffer as needed.
+finally:
+    assert store.unregister_buffer(output.ctypes.data) == 0
+```
+
+Store registration does not allocate CUDA pinned memory. SGLang allocates
+persistent pinned host buffers separately, fills them outside CUDA Graph, and
+captures the per-layer H2D copy and dequantization inside the graph. The caller
+must wait for both Store writes and any GPU reads before reusing or releasing
+these buffers.
+
+To store existing floating-point arrays, explicitly expose their bytes, e.g.
+`table.view(np.uint8).reshape(num_rows, row_bytes)`. The caller is responsible for
+the dtype and layout when interpreting lookup results.
+
+## Populate Flow
+
+Populate follows the existing Store write path:
+
+1. validate that exactly one table is provided for each head
+2. validate that every table matches `[N_h, row_bytes]`
+3. verify that the target head-table keys do not already exist
+4. register each embedding table buffer
+5. upload all head tables with `batch_put_from(...)`
+6. unregister the staging buffers
+
+`populate(...)` is defined as a create-only operation for the selected layer. To
+reuse a `layer_id`, first remove that layer's old tables with `remove_from_store(layer_id, ...)`. Other layers are unaffected.
+
+If upload fails after some head tables have already been written, or if publish
+finishes but post-write buffer cleanup fails, the backend best-effort removes
+the keys written by the failed populate attempt before returning an error.
+
+## Lookup Flow
+
+Each Store-backed lookup follows this flow (local mode validates IDs and copies
+rows directly):
+
+1. validate the `row_ids` shape and bounds
+2. build per-head byte ranges for the requested rows
+3. query head-table locations with `batch_query(...)`
+4. issue one `get_into_ranges(...)` call to write the rows into the registered output buffer
+
+The binding builds ranges directly from contiguous NumPy row IDs.
+It rejects Python lists and implicit dtype or layout conversion.
+
+## Validation
+
+The backend enforces these invariants:
+
+- the layer map is nonempty, IDs are nonnegative, and operations reject unknown layers
+
+- `table_vocab_sizes` is non-empty and every entry is positive
+- `row_bytes` is positive and table/output byte sizes do not overflow
+- `populate(...)` receives exactly one table per head
+- every populated table matches `[N_h, row_bytes]`
+- `lookup_into(...)` receives matching `[B, L, H]` IDs and registered output
+- every row id satisfies `0 <= row_ids[..., h] < N_h`
+
+## Validation Status
+
+This backend is covered by:
+
+- correctness tests in `scripts/test_engram_store.py`
+- benchmark coverage in `scripts/bench_engram_store_27b.py`
+
+`scripts/test_engram_store.py` can run against an existing Mooncake deployment through
+`MOONCAKE_CONFIG_PATH` / `MOONCAKE_MASTER`, or it can start a local
+`mooncake_master` instance automatically for a self-contained TCP test run.
+
+By default, the benchmark exercises `engram_store.populate(...)` directly. Its
+fallback populate paths are gated behind `ENGRAM_ALLOW_POPULATE_FALLBACK=1` so
+they do not silently mask regressions in the current implementation.
+
+## Client Instances and Storage
+
+SGLang shares one EngramStore and one Store client across all Engram layers in
+each rank. Each layer still owns its fixed pinned output buffers for CUDA Graph.
+Different ranks access the same backend keys; creating additional clients or
+EngramStore handles does not replicate table data. Storage replicas are controlled
+by the Store replication configuration used during upload.
+
+Per-rank reads currently duplicate network traffic and fetched rows in staging
+buffers. Reducing that traffic requires a separate optimization such as one reader
+per TP group followed by broadcast, or coordinated shared host buffers. Sharing a
+multi-layer EngramStore instance alone does not deduplicate reads across processes.
diff --git a/docs/source/design/store/immutable-dfs-bucket-allocator.md b/docs/source/design/store/immutable-dfs-bucket-allocator.md
new file mode 100644
index 0000000000..69e386b1b3
--- /dev/null
+++ b/docs/source/design/store/immutable-dfs-bucket-allocator.md
@@ -0,0 +1,108 @@
+# Immutable DFS bucket allocator
+
+The immutable bucket allocator is an experimental alternative to the default
+DFS shard allocator. It stores immutable objects by appending them to
+fixed-capacity bucket files and reclaims space only by deleting a whole bucket.
+The default remains `shard`; selecting `bucket` is an explicit deployment
+choice.
+
+## On-disk layout
+
+Each bucket is named `bucket_<16-digit-id>.data` below
+`MOONCAKE_DFS_ROOT_DIR`. Bucket IDs increase monotonically for the lifetime of
+the master and are not reused.
+
+An entry contains only its value bytes followed by zero padding to
+`MOONCAKE_DFS_ALIGNMENT`:
+
+```text
+bucket_N.data
++----------------------+--------------------+----------------------+-----+
+| object A value bytes | zero alignment pad | object B value bytes | ... |
++----------------------+--------------------+----------------------+-----+
+^ descriptor.offset                         ^ next descriptor.offset
+```
+
+There is no per-entry header, footer, checksum, or persisted allocator
+metadata in this first implementation. A DFS descriptor records the bucket
+path and ID, value offset, object size, and aligned allocation size. The data
+plane opens an existing bucket for each request and uses synchronous buffered
+positional I/O. A successful request means that the requested `WriteAt` calls
+completed; it is not an `fsync` durability guarantee.
+
+Allocations append in request order. A rollback or removal changes the
+in-memory entry to a tombstone but never rewinds the append cursor and never
+reuses that range. This rule also applies when the same key is allocated again.
+Batch allocation is atomic at allocator level: if any request fails, all ranges
+reserved by that batch become tombstones and no descriptor is returned.
+
+## Lifecycle and eviction
+
+New entries are `PENDING` until `PutEnd` commits them. A bucket containing a
+pending entry cannot be selected for eviction. Full buckets are sealed and the
+allocator creates a new bucket, up to the configured maximum.
+
+Eviction uses bucket-level LRU. Before deleting a candidate, the master locks
+the affected metadata shards in a stable order and verifies that every live
+entry still refers to the exact descriptor and is not leased or processing.
+One failed check aborts the entire candidate; entries are never partially
+evicted from a bucket. Metadata is removed only after every entry passes
+validation. If physical deletion fails, the bucket remains charged against
+capacity and is retained for a later deletion retry.
+
+## Configuration
+
+Set the same DFS root, adapter, allocator selection, alignment, and
+`MOONCAKE_DFS_BUCKET_CAPACITY` on the master and every client that accesses
+DFS replicas. `MOONCAKE_DFS_MAX_BUCKET_COUNT` and the bucket eviction settings
+are consumed only by the master allocator.
+
+| Environment variable | Default | Description |
+| --- | --- | --- |
+| `MOONCAKE_DFS_ALLOCATOR` | `shard` | Select `bucket` to enable this allocator, or `shard` for the existing allocator. |
+| `MOONCAKE_DFS_BUCKET_CAPACITY` | `1073741824` (1 GiB) | Logical and preallocated size of every bucket; must be nonzero, aligned, fit in a signed 64-bit file offset, and match on the master and every DFS client. |
+| `MOONCAKE_DFS_MAX_BUCKET_COUNT` | `64` | Maximum number of live bucket files; must be positive. Buckets awaiting a successful deletion still count. |
+| `MOONCAKE_DFS_ROOT_DIR` | `/mnt/3fs/mooncake` | Absolute shared directory containing the bucket files. |
+| `MOONCAKE_DFS_FS_ADAPTER` | `hf3fs` | Filesystem adapter (`hf3fs` or `posix`). This version uses its buffered synchronous interface. |
+| `MOONCAKE_DFS_ALIGNMENT` | `4096` | Power-of-two entry alignment; must divide the bucket capacity. |
+| `MOONCAKE_DFS_EVICTION_ENABLED` | `true` | Enable bucket-level eviction. |
+| `MOONCAKE_DFS_EVICTION_HIGH_WATERMARK` | `0.9` | Usage ratio that starts normal eviction. |
+| `MOONCAKE_DFS_EVICTION_LOW_WATERMARK` | `0.7` | Usage ratio at which normal eviction stops. |
+| `MOONCAKE_DFS_EVICTION_CHECK_INTERVAL` | `5` | Background eviction check interval in seconds. |
+
+For example:
+
+```bash
+export MOONCAKE_ENABLE_DFS=1
+export MOONCAKE_DFS_ALLOCATOR=bucket
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=posix
+export MOONCAKE_DFS_BUCKET_CAPACITY=1073741824
+export MOONCAKE_DFS_MAX_BUCKET_COUNT=64
+export MOONCAKE_DFS_ALIGNMENT=4096
+```
+
+`MOONCAKE_DFS_SHARD_COUNT`, `MOONCAKE_DFS_SHARD_CAPACITY`, and online shard
+expansion apply only to the `shard` allocator. Conversely, the two bucket
+capacity variables have no effect while `MOONCAKE_DFS_ALLOCATOR=shard`.
+
+## Current limitations
+
+This initial backend intentionally provides only the minimal runtime path:
+
+- Allocator and key metadata exist only in master memory. Startup fails closed
+  when the DFS root already contains a `bucket_*.data` or `bucket_*.meta`
+  artifact; restart recovery and persisted manifests are not implemented.
+- Snapshot restore, OpLog recovery, standby promotion, and HA continuity do not
+  reconstruct bucket state. Do not select `bucket` when those guarantees are
+  required.
+- I/O is synchronous and buffered. There is no asynchronous DFS pipeline,
+  Direct I/O (`O_DIRECT`), read coalescing, prefetch, or bucket read cache.
+- There is no public administrator API for changing the maximum bucket count
+  while the service is running.
+- The backend remains single-tenant and experimental. Only one active master
+  may own a DFS bucket root, and operators must not create, truncate, rename,
+  or delete bucket files behind it.
+
+See the {ref}`Mooncake Store deployment guide <dfs-storage>` for the common DFS
+replica setup and client requirements.
diff --git a/docs/source/design/mooncake-store.md b/docs/source/design/store/mooncake-store.md
similarity index 83%
rename from docs/source/design/mooncake-store.md
rename to docs/source/design/store/mooncake-store.md
index aa68f03cf8..71ade57a4d 100644
--- a/docs/source/design/mooncake-store.md
+++ b/docs/source/design/store/mooncake-store.md
@@ -10,7 +10,7 @@ Mooncake Store provides low-level object storage and management capabilities, in
 
 Key features of Mooncake Store include:
 - **Object-level storage operations**: Mooncake Store provides simple and easy-to-use object-level APIs, including `Put`, `Get`, and `Remove` operations.
-- **Optional object grouping**: Related objects can carry an optional group ID so that the Master can route their metadata to the same shard and apply best-effort shared lifecycle behavior.
+- **Optional object grouping**: Related objects can carry an optional group ID so that the Master applies best-effort shared lifecycle behavior. Object routing stays decoupled from groups (always `hash(tenant, key)`); grouping only carries a shared group TTL.
 - **Multi-replica support**: Mooncake Store supports storing multiple data replicas for the same object, effectively alleviating hotspots in access pressure. Each slice within an object is guaranteed to be placed in different segments, while different objects' slices may share segments. Replication operates on a best-effort basis.
 - **Strong consistency**: Mooncake Store guarantees that `Get` operations always return correct and complete data. Once an object has been successfully `Put`, it remains immutable until removal, ensuring that all subsequent `Get` requests retrieve the most recent value.
 - **Zero-copy, bandwidth-saturating transfers**: Powered by the Transfer Engine, Mooncake Store eliminates redundant memory copies and exploits multi-NIC GPUDirect RDMA pooling to drive data across the network at full line rate while keeping CPU overhead negligible.
@@ -21,7 +21,7 @@ Key features of Mooncake Store include:
 
 ## Architecture
 
-![architecture](../image/mooncake-store-preview.png)
+![architecture](../../image/mooncake-store-preview.png)
 
 As shown in the figure above, there are two key components in Mooncake Store: **Master Service** and **Client**.
 
@@ -45,30 +45,10 @@ The `Client` can be used in three ways:
 Mooncake store supports two deployment methods to accommodate different availability requirements:
 1. **Default mode**: In this mode, the master service consists of a single master node, which simplifies deployment but introduces a single point of failure. If the master crashes or becomes unreachable, the system cannot continue to serve requests until it is restored.
 2. **High availability mode**: This mode enhances fault tolerance by running the master service as a cluster of multiple master nodes coordinated through an etcd cluster. The master nodes use etcd to elect a leader, which is responsible for handling client requests.
-If the current leader fails or becomes partitioned from the network, the remaining master nodes automatically perform a new leader election, ensuring continuous availability.
+If the current leader fails or becomes partitioned from the network, the remaining master nodes automatically perform a new leader election. Election alone does not make a node ready to serve: the elected node must complete standby catch-up, export and validate the complete promotion context, restore that context (including a valid empty context), and revalidate leadership. If any step fails, the node remains unavailable rather than serving from unverified or partial metadata.
 
 In both modes, the leader monitors the health of all client nodes through periodic heartbeats. If a client crashes or becomes unreachable, the leader quickly detects the failure and takes appropriate action. When a client node recovers or reconnects, it can automatically rejoin the cluster without manual intervention.
 
-(client-c-api)=
-## Client C++ API
-
-The `Client` class provides the primary interface for Mooncake Store operations:
-
-| API | Description |
-|-----|-------------|
-| `Init` | Initialize the client with metadata server, protocol, and master address |
-| `Get` | Retrieve object data into pre-registered local memory slices |
-| `Put` | Store object data with configurable replication and persistence |
-| `Upsert` / `BatchUpsert` | Insert or update with existing placement reuse |
-| `Remove` | Delete an object and all its replicas |
-| `CreateCopyTask` / `CreateMoveTask` | Asynchronous cross-node data transfer |
-| `QueryTask` | Monitor the status of async copy/move tasks |
-| `BatchQueryIp` | Discover network locations of storage nodes |
-| `BatchReplicaClear` | Batch clear replicas on specific segments |
-| `QueryByRegex` / `RemoveByRegex` | Query or delete objects matching a regex |
-
-For full API signatures, parameter details, and usage examples, see the [Mooncake Store C++ API Reference](../api-reference/cpp/mooncake-store.md).
-
 ## Master Service
 
 The cluster's available resources are viewed as a large resource pool, managed centrally by a Master process for space allocation and guiding data replication
@@ -95,19 +75,7 @@ To reduce cache warm-up time after a master restart, the Master Service supports
 
 The Master Service can optionally enforce strict multi-tenant memory quota admission. This feature is disabled by default. When `enable_multi_tenants=false`, request tenant IDs are ignored for object placement, all objects use the `default` namespace, and tenant quota management requests return `UNAVAILABLE_IN_CURRENT_MODE`.
 
-When strict multi-tenant mode is enabled, the tenant quota policy is loaded from the configured connector. Supported connector types are `file` and, when the store is built with `STORE_USE_ETCD=ON`, `etcd`. The `file` connector uses `tenant_quota_connector_uri=<path>` as a writable YAML policy path. The `etcd` connector uses `tenant_quota_connector_uri=<endpoints>` as the etcd endpoints string and stores the same YAML policy in `mooncake-store/<cluster_id>/tenant_quota_policy`; if that key does not exist, the master starts with an empty policy so the first policy can be created through the admin API. The etcd connector shares the process-wide store etcd client used by HA/oplog, so deployments that enable both must configure matching etcd endpoints. Tenants must be explicitly present in that connector policy before they can write. Missing tenants, empty tenants, and an unregistered `default` tenant are rejected with `TENANT_NOT_REGISTERED`.
-
-The YAML policy uses schema version `1`:
-
-```yaml
-version: 1
-
-tenants:
-  - name: tenant-a
-    quota: 200GB
-```
-
-Tenant names must be non-empty, unique, must not start with `_`, and must not contain NUL or control characters. Quotas must be positive integers and may use `B`, `KB`, `MB`, `GB`, or `TB` units.
+See [Multi-Tenant Deployment](../../deployment/multi-tenancy.md) for configuration details.
 
 Effective quota is recomputed from the current registered memory capacity:
 
@@ -118,262 +86,10 @@ Effective quota is recomputed from the current registered memory capacity:
 
 `PutStart` and size-changing `UpsertStart` charge quota before memory is allocated. If the first reservation fails, the master performs tenant-scoped memory eviction for the target tenant and retries the reservation. The retry is bounded to two eviction attempts. Tenant quota eviction scans only the target tenant, skips hard-pinned objects, honors soft-pin eviction configuration, and preserves grouped-object lease safety checks.
 
-Admin policy changes are persisted before the final in-memory policy is applied. `PUT` writes the connector first and then applies the policy in memory. `DELETE` first marks the tenant unregistered in memory to block concurrent writes, verifies the tenant is empty, writes the connector, and rolls back the in-memory mark if the connector write fails. The admin HTTP API exposes:
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/api/v1/tenant_quotas` | List quota snapshots for active or explicit tenants |
-| `GET` | `/api/v1/tenant_quotas?tenant_id=<tenant>` | Query one tenant quota snapshot |
-| `PUT` | `/api/v1/tenant_quotas?tenant_id=<tenant>` | Create or update a tenant quota policy |
-| `DELETE` | `/api/v1/tenant_quotas?tenant_id=<tenant>` | Delete an empty tenant quota policy |
-
-Tenant quota snapshots include `tenant_id`, `requested_quota_bytes`, `effective_quota_bytes`, `used_bytes`, `reserved_bytes`, `committed_count`, `metadata_object_count`, `over_quota`, and `has_explicit_policy`.
+Admin policy changes are persisted before the final in-memory policy is applied. `PUT` writes the connector first and then applies the policy in memory. `DELETE` first marks the tenant unregistered in memory to block concurrent writes, verifies the tenant is empty, writes the connector, and rolls back the in-memory mark if the connector write fails.
 
 Snapshots restore object runtime state only. Tenant quota policy is always loaded from the connector after metadata restore, then usage and effective quota are rebuilt from restored metadata and current registered capacity. If the connector cannot be loaded in strict multi-tenant mode, startup fails.
 
-### Master Service APIs
-
-The protobuf definition between Master and Client is as follows:
-
-```protobuf
-message BufHandle {
-  required uint64 segment_name = 1;  // Storage segment name (can be simply understood as the name of the storage node)
-  required uint64 size = 2;          // Size of the allocated space
-  required uint64 buffer = 3;        // Pointer to the allocated space
-
-  enum BufStatus {
-    INIT = 0;          // Initial state, space reserved but not used
-    COMPLETE = 1;      // Completed usage, space contains valid data
-    FAILED = 2;        // Usage failed, upstream should update the handle state to this value
-    UNREGISTERED = 3;  // Space has been unregistered, metadata deleted
-  }
-  required BufStatus status = 4 [default = INIT]; // Space status
-};
-
-message ReplicaInfo {
-  repeated BufHandle handles = 1; // Specific locations of the stored object data
-
-  enum ReplicaStatus {
-    UNDEFINED = 0;   // Uninitialized
-    INITIALIZED = 1; // Space allocated, waiting for write
-    PROCESSING = 2;  // Writing data in progress
-    COMPLETE = 3;    // Write completed, replica available
-    REMOVED = 4;     // Replica has been removed
-    FAILED = 5;      // Replica write failed, consider reallocation
-  }
-  required ReplicaStatus status = 2 [default = UNDEFINED]; // Replica status
-};
-
-service MasterService {
-  // Get the list of replicas for an object
-  rpc GetReplicaList(GetReplicaListRequest) returns (GetReplicaListResponse);
-
-  // Get replica lists for objects matching a regex
-  rpc GetReplicaListByRegex(GetReplicaListByRegexRequest) returns (GetReplicaListByRegexResponse);
-
-  // Batch query IP addresses for multiple client IDs
-  rpc BatchQueryIp(BatchQueryIpRequest) returns (BatchQueryIpResponse);
-
-  // Batch clear replicas for multiple object keys
-  rpc BatchReplicaClear(BatchReplicaClearRequest) returns (BatchReplicaClearResponse);
-
-  // Start Put operation, allocate storage space
-  rpc PutStart(PutStartRequest) returns (PutStartResponse);
-
-  // End Put operation, mark object write completion
-  rpc PutEnd(PutEndRequest) returns (PutEndResponse);
-
-  // Delete all replicas of an object
-  rpc Remove(RemoveRequest) returns (RemoveResponse);
-
-  // Remove objects matching a regex
-  rpc RemoveByRegex(RemoveByRegexRequest) returns (RemoveByRegexResponse);
-
-  // Storage node (Client) registers a storage segment
-  rpc MountSegment(MountSegmentRequest) returns (MountSegmentResponse);
-
-  // Storage node (Client) unregisters a storage segment
-  rpc UnmountSegment(UnmountSegmentRequest) returns (UnmountSegmentResponse);
-}
-```
-
-1. GetReplicaList
-
-```protobuf
-message GetReplicaListRequest {
-  required string key = 1;
-};
-
-message GetReplicaListResponse {
-  required int32 status_code = 1;
-  repeated ReplicaInfo replica_list = 2; // List of replica information
-};
-```
-
-- **Request**: `GetReplicaListRequest` containing the key to query.
-- **Response**: `GetReplicaListResponse` containing the status code status_code and the list of replica information `replica_list`.
-- **Description**: Used to retrieve information about all available replicas for a specified key. The Client can select an appropriate replica for reading based on this information.
-
-2. GetReplicaListByRegex
-
-```protobuf
-message GetReplicaListByRegexRequest {
-  required string key_regex = 1;
-};
-
-message ObjectReplicaList {
-  repeated ReplicaInfo replica_list = 1;
-};
-
-message GetReplicaListByRegexResponse {
-  required int32 status_code = 1;
-  map<string, ObjectReplicaList> object_map = 2; // Matched objects and their replica information.
-};
-```
-
-- **Request**: GetReplicaListByRegexRequest, which contains the regular expression key_regex to be matched.
-- **Response**: GetReplicaListByRegexResponse, which contains a status_code and an object_map. The keys of this map are the successfully matched object keys, and the values are the lists of replica information for each key.
-- **Description**: Used to query for all keys and their replica information that match the specified regular expression. This interface facilitates bulk queries and management.
-
-3. BatchQueryIp
-
-```protobuf
-message BatchQueryIpRequest {
-  repeated UUID client_ids = 1; // List of client IDs to query
-};
-
-message BatchQueryIpResponse {
-  required int32 status_code = 1;
-  map<UUID, IPAddressList> client_ip_map = 2; // Map from client ID to their IP address lists
-};
-
-message IPAddressList {
-  repeated string ip_addresses = 1; // List of unique IP addresses
-};
-```
-
-- **Request**: `BatchQueryIpRequest` containing a list of client IDs to query.
-- **Response**: `BatchQueryIpResponse` containing the status code `status_code` and a `client_ip_map`. The keys of this map are the client IDs that have successfully mounted segments, and the values are lists of unique IP addresses extracted from all segments mounted by each client. Client IDs that have no mounted segments or are not found are silently skipped and not included in the result map.
-- **Description**: Used to batch query the IP addresses for multiple client IDs. For each client ID in the input list, this interface retrieves the unique IP addresses from all segments mounted by that client.
-
-4. BatchReplicaClear
-
-```protobuf
-message BatchReplicaClearRequest {
-  repeated string object_keys = 1; // List of object keys to clear
-  required UUID client_id = 2;     // Client ID that owns the objects
-  optional string segment_name = 3; // Optional segment name. If empty, clears all segments
-};
-
-message BatchReplicaClearResponse {
-  required int32 status_code = 1;
-  repeated string cleared_keys = 2; // List of object keys that were successfully cleared
-};
-```
-
-- **Request**: `BatchReplicaClearRequest` containing a list of object keys to clear, the client ID that owns the objects, and an optional segment name. If `segment_name` is empty, all replicas of the specified objects are cleared (the objects are deleted entirely). If `segment_name` is provided, only replicas located on that specific segment are cleared.
-- **Response**: `BatchReplicaClearResponse` containing the status code `status_code` and a list of `cleared_keys` representing the object keys that were successfully cleared. Only objects that belong to the specified `client_id`, have expired leases, and meet the clearing criteria are included in the result. Objects with active leases, incomplete replicas (when clearing all segments), or belonging to different clients are silently skipped.
-- **Description**: Used to batch clear replicas for multiple object keys belonging to a specific client ID. This interface allows clearing replicas either on a specific segment or across all segments, providing flexible storage resource management capabilities.
-
-5. PutStart
-
-```protobuf
-message PutStartRequest {
-  required string key = 1;             // Object key
-  required int64 value_length = 2;     // Total length of data to be written
-  required ReplicateConfig config = 3; // Replica configuration information
-  repeated uint64 slice_lengths = 4;   // Lengths of each data slice
-};
-
-message PutStartResponse {
-  required int32 status_code = 1;
-  repeated ReplicaInfo replica_list = 2;  // Replica information allocated by the Master Service
-};
-```
-
-- **Request**: `PutStartRequest` containing the key, data length, and replica configuration config.
-- **Response**: `PutStartResponse` containing the status code status_code and the allocated replica information replica_list.
-- **Description**: Before writing an object, the Client must call PutStart to request storage space from the Master Service. The Master Service allocates space based on the config and returns the allocation results (`replica_list`) to the Client. The allocation strategy ensures that each slice of the object is placed in different segments, while operating on a best-effort basis - if insufficient space is available for all requested replicas, as many replicas as possible will be allocated. The Client then writes data to the storage nodes where the allocated replicas are located. The need for both start and end steps ensures that other Clients do not read partially written values, preventing dirty reads.
-
-6. PutEnd
-
-```protobuf
-message PutEndRequest {
-  required string key = 1;
-};
-
-message PutEndResponse {
-  required int32 status_code = 1;
-};
-```
-
-- **Request**: `PutEndRequest` containing the key.
-- **Response**: `PutEndResponse` containing the status code status_code.
-- **Description**: After the Client completes data writing, it calls `PutEnd` to notify the Master Service. The Master Service updates the object's metadata, marking the replica status as `COMPLETE`, indicating that the object is readable.
-
-7. Remove
-
-```protobuf
-message RemoveRequest {
-  required string key = 1;
-};
-
-message RemoveResponse {
-  required int32 status_code = 1;
-};
-```
-
-- **Request**: `RemoveRequest` containing the key of the object to be deleted.
-- **Response**: `RemoveResponse` containing the status code `status_code`.
-- **Description**: Used to delete the object and all its replicas corresponding to the specified key. The Master Service marks all replicas of the corresponding object as deleted.
-
-8. RemoveByRegex
-
-```protobuf
-message RemoveByRegexRequest {
-  required string key_regex = 1;
-};
-
-message RemoveByRegexResponse {
-  required int32 status_code = 1;
-  optional int64 removed_count = 2; // The number of objects removed.
-};
-```
-
-- **Request**: RemoveByRegexRequest, which contains the regular expression key_regex to be matched.
-- **Response**: RemoveByRegexResponse, which contains a status_code and the number of objects that were removed, removed_count.
-- **Description**: Used to delete all objects and their corresponding replicas for keys that match the specified regular expression. Similar to the Remove interface, this is a metadata operation where the Master Service marks the status of all matched object replicas as removed.
-
-9. MountSegment
-
-```protobuf
-message MountSegmentRequest {
-  required uint64 buffer = 1;       // Starting address of the space
-  required uint64 size = 2;         // Size of the space
-  required string segment_name = 3; // Storage segment name
-}
-
-message MountSegmentResponse {
-  required int32 status_code = 1;
-};
-```
-
-The storage node (Client) allocates a segment of memory and, after calling `TransferEngine::registerLocalMemory` to complete local mounting, calls this interface to mount the allocated continuous address space to the Master Service for allocation.
-
-10. UnmountSegment
-
-```protobuf
-message UnmountSegmentRequest {
-  required string segment_name = 1;  // Storage segment name used during mounting
-}
-
-message UnMountSegmentResponse {
-  required int32 status_code = 1;
-};
-```
-
-When the space needs to be released, this interface is used to remove the previously mounted resources from the Master Service.
-
 ### Object Information Maintenance
 
 The Master Service needs to maintain mappings related to buffer allocators and object metadata to efficiently manage memory resources and precisely control replica states in multi-replica scenarios. Additionally, the Master Service uses read-write locks to protect critical data structures, ensuring data consistency and security in multi-threaded environments. The following are the interfaces maintained by the Master Service for storage space information:
@@ -474,13 +190,14 @@ Mooncake Store remains an object-oriented KV cache: objects are still put, queri
 
 For single-object writes, `group_ids` contains one entry. For batch writes, it must have the same length as the key list, and entry `i` is the group ID for key `i`. An empty string stores that key as ungrouped, and leaving the field unset preserves the legacy ungrouped behavior. For an existing object, group membership is immutable: `Upsert` may preserve the existing group, but it cannot move the object to another group or clear its group while the object exists.
 
-On the Master side, group state is tenant-scoped. Objects with a non-empty group ID are routed to the metadata shard selected by `hash(group_id)`, and the Master keeps a tenant-scoped object-to-group routing index so existing key-based APIs can still locate grouped objects. The Master tracks only the current member set of each group; it does not require an expected member count, a member index, or a commit protocol for group completeness.
+On the Master side, objects are always routed by `hash(tenant, key)` — group membership is an annotation, not a routing key. Group state is tenant-scoped and kept in a separate, single group domain (`group_domain_`) keyed by `scoped(tenant, group_id)`; it holds only the current member key list plus one shared group TTL. Existing key-based APIs locate grouped objects via `hash(tenant, key)` as usual; there is no object-to-group routing index. The Master tracks only the current member set of each group; it does not require an expected member count, a member index, or a commit protocol for group completeness.
 
 Group metadata affects lifecycle behavior on a best-effort basis:
 
-- `ExistKey` and `GetReplicaList` refresh the lease, and the soft-pin timeout if present, for the current members of the group.
-- Memory eviction expands a grouped candidate to the group's current members and then applies the existing per-object safety checks. Members with active leases, hard pins, soft pins when soft-pin eviction is disabled, incomplete writes, busy replicas, or unavailable replica states are skipped.
-- Object removal APIs, copy/move tasks, and NoF eviction keep their existing object-level semantics. Group routing and membership metadata are cleaned up when objects are removed.
+- `ExistKey` and `GetReplicaList` refresh the group's shared read TTL. A read of any member extends the same group TTL, so the whole group is protected together; a grouped object's own per-member lease is not authoritative. Object soft-pin deadlines are independent and are not extended.
+- Memory eviction first consults the group's single shared TTL: if the group was read recently it is skipped as a whole; otherwise the group's current members are evicted all-or-none, applying the existing per-object safety checks (hard pins, soft pins when soft-pin eviction is disabled, incomplete writes, busy replicas, unavailable replica states) on a best-effort basis. The number of evicted objects is bounded by the requested eviction ratio.
+- Object removal APIs, copy/move tasks, and NoF eviction keep their existing object-level semantics. Group membership metadata is cleaned up when objects are removed.
+- On snapshot/standby restore, group state is rebuilt from object metadata, preserving the group's maximum restored lease deadline so grouped objects are not dropped as expired. Snapshots produced by a router that placed grouped objects on `hash(group_id)` shards are automatically re-routed to `hash(tenant, key)` on restore (`ReRouteRestoredObjectsByKey`), so they need not be regenerated; current-format snapshots restore correctly.
 
 This design is intentionally lightweight and backward compatible. Grouping should be treated as a lifecycle hint for related objects, not as a transactional guarantee that all members are created, made visible, or evicted atomically.
 
@@ -494,7 +211,7 @@ Mooncake Store provides two concrete implementations of `BufferAllocatorBase`:
 
 **OffsetBufferAllocator (default and recommended)**: This allocator is derived from [OffsetAllocator](https://github.com/sebbbi/OffsetAllocator), which uses a custom bin-based allocation strategy that supports fast hard realtime `O(1)` offset allocation with minimal fragmentation. Mooncake Store optimizes this allocator based on the specific memory usage characteristics of LLM inference workloads, thereby enhancing memory utilization in LLM scenarios.
 
-For measured utilization and allocation latency across LLM-style workloads, see [Allocator Performance](../performance/mooncake/allocator-benchmark-result.md).
+For measured utilization and allocation latency across LLM-style workloads, see [Allocator Performance](../../performance/mooncake/allocator-benchmark-result.md).
 
 **CachelibBufferAllocator (deprecated)**: This allocator leverages Facebook's [CacheLib](https://github.com/facebook/CacheLib) to manage memory using a slab-based allocation strategy. It provides efficient memory allocation with good fragmentation resistance and is well-suited for high-performance scenarios. However, in our modified version, it does not handle workloads with highly variable object sizes effectively, so it is currently marked as deprecated.
 
@@ -574,7 +291,7 @@ Valid values are: `random` (default), `free_ratio_first`, `ssd_free_ratio_first`
 | `free_ratio_first` | Balanced utilization, dynamic scaling | Slightly lower throughput due to sampling and sorting overhead |
 | `ssd_free_ratio_first` | SSD-aware memory allocation when SSD offloading is enabled | Depends on SSD usage metrics; falls back to random allocation when needed |
 | `cxl` | CXL memory hardware | CXL-specific; single-replica only |
-| `local_first` | Colocated inference workers and memory store segments | Requires stable host identity in `local_hostname`; single memory replica only |
+| `local_first` | Colocated inference workers and memory store segments | Requires stable host identity from `MOONCAKE_HOST_ID` or `local_hostname`; single memory replica only |
 
 **Use `random`** (default) when your cluster is relatively stable (segments rarely join or leave) and you want the highest possible allocation throughput.
 
@@ -586,9 +303,9 @@ Valid values are: `random` (default), `free_ratio_first`, `ssd_free_ratio_first`
 
 **Use `cxl`** only when your hardware includes CXL (Compute Express Link) memory devices and you want to allocate data exclusively on CXL segments.
 
-**Use `local_first`** when inference workers and Mooncake Store memory segments are colocated and you want writes to prefer the writer's host before falling back to other hosts. For this strategy to work correctly, all writer and store processes on the same physical or logical host must use the same stable, globally unique host part in `local_hostname`.
+**Use `local_first`** when inference workers and Mooncake Store memory segments are colocated and you want writes to prefer the writer's host before falling back to other hosts. For this strategy to work correctly, all writer and store processes on the same physical or logical host must use the same stable, globally unique `MOONCAKE_HOST_ID`. When the variable is unset or empty, Mooncake derives the host identity from `local_hostname` by removing the port.
 
-For benchmark data comparing `random` and `free_ratio_first` across segment counts, replica counts, and skewed capacities, see [AllocationStrategy Performance](../performance/mooncake/allocation-strategy-benchmark-result.md).
+For benchmark data comparing `random` and `free_ratio_first` across segment counts, replica counts, and skewed capacities, see [AllocationStrategy Performance](../../performance/mooncake/allocation-strategy-benchmark-result.md).
 
 #### Strategy Details
 
@@ -625,6 +342,8 @@ An SSD-aware variant of the free-ratio-first strategy. It first tries preferred
 
 Host-aware local-first allocation reuses the normal preferred-segment flow. The master derives the writer host id from the request's client host identity and builds an ordered preferred segment list: active hosts are visited in cyclic lexicographic host-id order, starting from the writer host when it has active segments, or otherwise from the next greater active host id. Within the same host, segment names are sorted and rotated by key hash so multiple local segments do not always receive the first allocation attempt.
 
+The C++ client reads `MOONCAKE_HOST_ID` as an explicit deployment override for the client identity carried in allocation requests and the identity recorded for mounted segments. This lets containerized deployments keep `local_hostname` as a routable per-pod transfer endpoint while using a shared node-level placement identity. Loopback and wildcard overrides are rejected; an empty override preserves the derived-hostname behavior.
+
 This strategy currently applies to memory allocation with `replica_num == 1`. Explicit `preferred_segment` or `preferred_segments` in `ReplicateConfig` are still tried first; if they are unavailable or full, allocation continues with the local-first ordered fallback list.
 
 **`cxl` — CxlAllocationStrategy**
@@ -659,14 +378,21 @@ The default lease TTL is 10 seconds and is configurable via a startup parameter
 
 For important and frequently used objects, such as system prompts, Mooncake Store provides a soft pin mechanism. When putting an object, it can be configured to enable soft pin. During eviction, objects that are not soft pinned are prioritized for eviction. Soft pinned objects are only evicted when memory is insufficient and no other objects are eligible for eviction.
 
-If a soft pinned object is not accessed for an extended period, its soft pin status will be removed. If it is accessed again later, it will automatically be soft pinned once more.
+The soft-pin lifetime starts when the first replica becomes readable. When its deadline is reached, the object becomes ordinary cache; later reads grant only an ordinary read lease and do not reactivate soft pinning. A later write can explicitly enable it again.
+
+Soft pin is runtime-only eviction-priority state. It is not persisted in snapshots or the HA OpLog, so recovery and Standby promotion downgrade restored objects to ordinary cache. Existing snapshot fields are retained only for format compatibility and ignored during recovery.
 
-There are two startup parameters in `master_service` related to the soft pin mechanism:
+There are three startup parameters in `master_service` related to the soft pin mechanism:
 
-- `default_kv_soft_pin_ttl`: The duration (in milliseconds) after which a soft pinned object will have its soft pin status removed if not accessed. The default value is `30 minutes`.
+- `default_kv_soft_pin_ttl`: The fixed soft-pin lifetime (in milliseconds) used when an `ENABLE` request omits `soft_pin_ttl_ms`. The default value is `30 minutes`; reads do not extend it.
+
+- `max_kv_soft_pin_ttl`: The largest request-level soft-pin TTL accepted by the Master. The default value is `24 hours`.
 
 - `allow_evict_soft_pinned_objects`: Whether soft pinned objects are allowed to be evicted. The default value is `true`.
 
+An explicit `ENABLE` TTL of zero commits the object as ordinary cache. TTL
+overrides are rejected for `PRESERVE` and `DISABLE`.
+
 Notably, soft pinned objects can still be removed using APIs such as `Remove` or `RemoveAll`.
 
 ## Hard Pin
@@ -677,9 +403,9 @@ Hard pin is set at object creation time through the `with_hard_pin` field in `Re
 
 Key differences from soft pin:
 
-- Hard pin never expires. Soft pin status is removed after a configurable TTL if the object is not accessed.
+- Hard pin never expires. Soft pin expires at a fixed deadline that starts when the first replica becomes readable, regardless of later accesses.
 - Hard-pinned objects are completely skipped during eviction. Soft-pinned objects may still be evicted when no other candidates are available.
-- Hard pin is immutable once set. Soft pin status is automatically refreshed on access.
+- Hard pin is immutable once set. Soft pin can be explicitly preserved, enabled, or disabled by write requests; reads do not refresh or reactivate it.
 
 ## Zombie Object Cleanup
 
@@ -697,16 +423,19 @@ Replica space allocated during a `PutStart` is considered releasable by the Mast
 
 Mooncake Store provides a **preferred segment allocation** feature that allows users to specify a preferred storage segment (node) for object allocation. This feature is particularly useful for optimizing data locality and reducing network overhead in distributed scenarios.
 
-### How It Works
-
-The preferred segment allocation feature is implemented through the `AllocationStrategy` system and is controlled via the `preferred_segment` field in the `ReplicateConfig` structure:
+The preferred segment allocation feature is implemented through the
+`AllocationStrategy` system. The following excerpt shows the legacy
+single-segment field and the memory-replica count used by this path; other
+`ReplicateConfig` fields are omitted:
 
 ```cpp
 struct ReplicateConfig {
-    size_t replica_num{1};                    // Total number of replicas for the object
-    bool with_soft_pin{false};               // Whether to enable soft pin mechanism for this object
+    size_t replica_num{1};                    // Number of memory replicas
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE};
+    std::optional<uint64_t> soft_pin_ttl_ms{}; // ENABLE override; omitted uses the Master default
     bool with_hard_pin{false};               // Whether to enable hard pin (never evicted)
     std::string preferred_segment{};         // Preferred segment for allocation
+    // Other fields, including nof_replica_num and dfs_replica_num, are omitted.
 };
 ```
 
@@ -723,38 +452,92 @@ When a `Put` operation is initiated with a non-empty `preferred_segment` value,
 
 ## Multi-layer Storage Support
 
-This system provides support for a hierarchical cache architecture, enabling efficient data access through a combination of in-memory caching and persistent storage. Data is initially stored in memory cache and asynchronously backed up to a Distributed File System (DFS), forming a two-tier "memory-SSD persistent storage" cache structure.
-
-### Enabling Persistence Functionality
+Mooncake Store supports three file-backed storage models in addition to memory
+and NoF replicas:
 
-When the user specifies `--root_fs_dir=/path/to/dir` when starting the master, and this path is a valid DFS-mounted directory on all machines where the clients reside, Mooncake Store's tiered caching functionality will work properly. Additionally, during master initialization, a `cluster_id` is loaded. This ID can be specified during master initialization (`--cluster_id=xxxx`). If not specified, the default value `mooncake_cluster` will be used. Subsequently, the root directory for client persistence will be `<root_fs_dir>/<cluster_id>`.
+- `DISK` is the legacy shared-filesystem persistence path enabled by the
+  master's `--root_fs_dir` flag.
+- `LOCAL_DISK` replicas are owned by a real client and use the asynchronous SSD
+  offload and heartbeat protocol.
+- `DFS` replicas occupy globally allocated ranges in shard files on a shared
+  distributed filesystem. Any correctly configured client can access them.
 
-​Note​​: When enabling this feature, the user must ensure that the DFS-mounted directory (`root_fs_dir=/path/to/dir`) is valid and consistent across all client hosts. If some clients have invalid or incorrect mount paths, it may cause abnormal behavior in Mooncake Store.
+These models have independent placement, metadata, and lifecycle rules.
 
-This `root_fs_dir` path is a legacy persistence path. SSD offload uses `--enable_offload=true` on the master and real client, stores data under the real client's `MOONCAKE_OFFLOAD_FILE_STORAGE_PATH`, and records `LOCAL_DISK` replicas. Do not use `--root_fs_dir` with `--enable_offload=true`.
+### Legacy shared-filesystem `DISK` replicas
 
-### Persistent Storage Space Configuration​
-Mooncake provides configurable DFS available space. Users can specify `--global_file_segment_size=1048576` when starting the master, indicating a maximum usable space of 1MB on DFS.
-The current default setting is the maximum value of int64 (as we generally do not restrict DFS storage usage), which is displayed as `infinite` in `mooncake_maseter`'s console logs.
-**Notice**  The DFS cache space configuration must be used together with the `--root_fs_dir` parameter. Otherwise, you will observe that the `SSD Storage` usage consistently shows: `0 B / 0 B`
-**Notice** The capability for file eviction on DFS has not been provided yet
+When the master starts with `--root_fs_dir=/shared/path`, it adds a legacy
+`DISK` replica to each new object. Clients write that replica asynchronously to
+the per-cluster directory `<root_fs_dir>/<cluster_id>` and can read it when the
+normal replica-selection path chooses `DISK`. The path must identify the same
+shared filesystem location on every participating client.
 
-### Data Access Mechanism
+`--global_file_segment_size` declares the legacy file capacity used by master
+metrics; its default is unlimited. It does not configure or limit the
+descriptor-based DFS shard allocator. Do not combine the legacy path with the
+client-owned SSD-offload mode; see the deployment guide for the corresponding
+flags and restrictions.
 
-The persistence feature also follows Mooncake Store's design principle of separating control flow from data flow. The read/write operations of kvcache objects are completed on the client side, while the query and management functions of kvcache objects are handled on the master side. In the file system, the key -> kvcache object index information is maintained by a fixed indexing mechanism, with each file corresponding to one kvcache object (the filename serves as the associated key name).
+### Descriptor-based DFS replicas
 
-After enabling the persistence feature:
-
-- For each `Put` or `BatchPut` operation, both a synchronous memory pool write operation and an asynchronous DFS persistence operation will be initiated.
-- For each `Get` or `BatchGet` operation, if the corresponding kvcache is not found in the memory pool, the system will attempt to read the file data from DFS and return it to the user.
+```{warning}
+**Work in progress.** Descriptor-based DFS is not production-ready and is not
+covered by the general fault-tolerance, HA continuity, durability, or
+multi-tenant guarantees described elsewhere in this design document.
+```
 
-### 3FS USRBIO Plugin (Experimental)
+The master owns DFS placement metadata and an allocator for the shared shard
+files. During `PutStart` or `UpsertStart`, it allocates an aligned range and
+returns a descriptor containing the shard path, shard index, offset, object
+size, and aligned size. The replica remains `PROCESSING` until the request is
+finalized. Removal, revocation, replacement, and allocator eviction release
+the range, with a configurable deferred-free interval preventing immediate
+offset reuse.
+
+The shard set can grow online through the master admin API. Expansion prepares
+new shard files and allocator state, then atomically publishes the complete
+ready set; existing shard paths and ranges remain unchanged. Allocation tries
+the hash-selected shard first and falls back to other ready shards, so added
+capacity can relieve full shards. Startup discovers the existing contiguous
+layout to retain the expanded capacity; it does not recover allocation or key
+metadata.
+
+The client owns the DFS data plane. `DistributedStorageBackend` validates the
+descriptor and delegates positional I/O to either `PosixFsAdapter` or
+`Hf3fsAdapter`. The master and clients must use the same DFS root and shard
+layout so that a descriptor identifies the same physical file everywhere.
+Clients do not open or create shard files during initialization. They open a
+shard only when first using its published descriptor, validating the path,
+shard index, and file capacity before caching the file handle. This prevents
+clients from retaining files that an unsuccessful expansion rolls back.
+
+For a write, the client first completes the requested memory and NoF transfers,
+then writes the DFS replica. `Put`, `BatchPut`, `Upsert`, and `BatchUpsert`
+acknowledge success only after the requested DFS `WriteAt` operations return
+successfully. This is request-synchronous acknowledgement, not an `fsync`
+durability guarantee. If either an existing object or an incoming same-size
+`Upsert` has a DFS replica, the requested memory, NoF, and DFS replica counts
+must match the existing topology.
+
+For a read, the master returns the readable replica list through the normal
+query path. The client selects the first complete replica; if that replica is a
+DFS replica, it uses the descriptor to read the requested range directly from
+the shared shard file.
+
+See the {ref}`Mooncake Store deployment guide <dfs-storage>` for
+configuration, usage, and current limitations.
+
+### HF3FS USRBIO Adapter (Experimental)
 
 ```{note}
 This integration is **experimental** and incomplete; see the plugin page for details before relying on it.
 ```
 
-If you need to use 3FS's native API (USRBIO) to achieve high-performance persistent file reads and writes, you can refer to the configuration instructions in this document [3FS USRBIO Plugin](../getting_started/plugin-usage/3FS-USRBIO-Plugin.md).
+The descriptor-based DFS data plane can use the native HF3FS USRBIO API instead
+of POSIX I/O. Select it with `MOONCAKE_DFS_FS_ADAPTER=hf3fs`; the legacy
+`--root_fs_dir` option does not enable this path, and there is no automatic
+fallback to POSIX. See the [HF3FS USRBIO adapter guide](../../getting_started/plugin-usage/3FS-USRBIO-Plugin.md)
+for build prerequisites and configuration.
 
 ## Builtin Metadata Server
 Mooncake Store provides a built-in HTTP metadata server as an alternative to etcd for storing cluster metadata. This feature is particularly useful for development environments or scenarios where etcd is not available.
@@ -785,11 +568,7 @@ To start the master service with the HTTP metadata server enabled:
 When enabled, the HTTP metadata server will start automatically and provide metadata services for the Mooncake Store cluster. This eliminates the need for an external etcd deployment, simplifying the setup process for development and testing environments.
 Note that the HTTP metadata server is designed for single-node deployments and does not provide the high availability features that etcd offers. For production environments requiring high availability, etcd is still the recommended choice.
 
-For detailed guidance on monitoring master metrics, Prometheus endpoints, and health checks, see the [Observability guide](../getting_started/observability.md).
-
-## Mooncake Store Python API
-
-**Complete Python API Documentation**: [https://kvcache-ai.github.io/Mooncake/api-reference/python/mooncake-store.html](https://kvcache-ai.github.io/Mooncake/api-reference/python/mooncake-store.html)
+For detailed guidance on monitoring master metrics, Prometheus endpoints, and health checks, see the [Observability guide](../../getting_started/observability.md).
 
 ## Version Management Policy
 
@@ -801,6 +580,258 @@ When to bump the version:
 * **Minor version (0.X.0)**: For new features, API additions, or notable improvements that maintain backward compatibility
 * **Patch version (0.0.X)**: For bug fixes, performance optimizations, or minor improvements that don't affect the API
 
+## Mooncake Store API
+
+Mooncake Store can be accessed through Python, C++, HTTP, and Master RPC APIs.
+
+For Python, C++, and HTTP API signatures, parameter details, and usage examples, see:
+
+- [Mooncake Store Python API](../../api-reference/python/mooncake-store.md)
+- [Mooncake Store C++ API Reference](../../api-reference/cpp/mooncake-store.md)
+- [Mooncake Store HTTP Service](../../api-reference/http/http-service.md)
+
+### Master Service APIs
+
+The protobuf definition between Master and Client is as follows:
+
+```protobuf
+message BufHandle {
+  required uint64 segment_name = 1;  // Storage segment name (can be simply understood as the name of the storage node)
+  required uint64 size = 2;          // Size of the allocated space
+  required uint64 buffer = 3;        // Pointer to the allocated space
+
+  enum BufStatus {
+    INIT = 0;          // Initial state, space reserved but not used
+    COMPLETE = 1;      // Completed usage, space contains valid data
+    FAILED = 2;        // Usage failed, upstream should update the handle state to this value
+    UNREGISTERED = 3;  // Space has been unregistered, metadata deleted
+  }
+  required BufStatus status = 4 [default = INIT]; // Space status
+};
+
+message ReplicaInfo {
+  repeated BufHandle handles = 1; // Specific locations of the stored object data
+
+  enum ReplicaStatus {
+    UNDEFINED = 0;   // Uninitialized
+    INITIALIZED = 1; // Space allocated, waiting for write
+    PROCESSING = 2;  // Writing data in progress
+    COMPLETE = 3;    // Write completed, replica available
+    REMOVED = 4;     // Replica has been removed
+    FAILED = 5;      // Replica write failed, consider reallocation
+  }
+  required ReplicaStatus status = 2 [default = UNDEFINED]; // Replica status
+};
+
+service MasterService {
+  // Get the list of replicas for an object
+  rpc GetReplicaList(GetReplicaListRequest) returns (GetReplicaListResponse);
+
+  // Get replica lists for objects matching a regex
+  rpc GetReplicaListByRegex(GetReplicaListByRegexRequest) returns (GetReplicaListByRegexResponse);
+
+  // Batch query IP addresses for multiple client IDs
+  rpc BatchQueryIp(BatchQueryIpRequest) returns (BatchQueryIpResponse);
+
+  // Batch clear replicas for multiple object keys
+  rpc BatchReplicaClear(BatchReplicaClearRequest) returns (BatchReplicaClearResponse);
+
+  // Start Put operation, allocate storage space
+  rpc PutStart(PutStartRequest) returns (PutStartResponse);
+
+  // End Put operation, mark object write completion
+  rpc PutEnd(PutEndRequest) returns (PutEndResponse);
+
+  // Delete all replicas of an object
+  rpc Remove(RemoveRequest) returns (RemoveResponse);
+
+  // Remove objects matching a regex
+  rpc RemoveByRegex(RemoveByRegexRequest) returns (RemoveByRegexResponse);
+
+  // Storage node (Client) registers a storage segment
+  rpc MountSegment(MountSegmentRequest) returns (MountSegmentResponse);
+
+  // Storage node (Client) unregisters a storage segment
+  rpc UnmountSegment(UnmountSegmentRequest) returns (UnmountSegmentResponse);
+}
+```
+
+1. GetReplicaList
+
+```protobuf
+message GetReplicaListRequest {
+  required string key = 1;
+};
+
+message GetReplicaListResponse {
+  required int32 status_code = 1;
+  repeated ReplicaInfo replica_list = 2; // List of replica information
+};
+```
+
+- **Request**: `GetReplicaListRequest` containing the key to query.
+- **Response**: `GetReplicaListResponse` containing the status code status_code and the list of replica information `replica_list`.
+- **Description**: Used to retrieve information about all available replicas for a specified key. The Client can select an appropriate replica for reading based on this information.
+
+2. GetReplicaListByRegex
+
+```protobuf
+message GetReplicaListByRegexRequest {
+  required string key_regex = 1;
+};
+
+message ObjectReplicaList {
+  repeated ReplicaInfo replica_list = 1;
+};
+
+message GetReplicaListByRegexResponse {
+  required int32 status_code = 1;
+  map<string, ObjectReplicaList> object_map = 2; // Matched objects and their replica information.
+};
+```
+
+- **Request**: GetReplicaListByRegexRequest, which contains the regular expression key_regex to be matched.
+- **Response**: GetReplicaListByRegexResponse, which contains a status_code and an object_map. The keys of this map are the successfully matched object keys, and the values are the lists of replica information for each key.
+- **Description**: Used to query for all keys and their replica information that match the specified regular expression. This interface facilitates bulk queries and management.
+
+3. BatchQueryIp
+
+```protobuf
+message BatchQueryIpRequest {
+  repeated UUID client_ids = 1; // List of client IDs to query
+};
+
+message BatchQueryIpResponse {
+  required int32 status_code = 1;
+  map<UUID, IPAddressList> client_ip_map = 2; // Map from client ID to their IP address lists
+};
+
+message IPAddressList {
+  repeated string ip_addresses = 1; // List of unique IP addresses
+};
+```
+
+- **Request**: `BatchQueryIpRequest` containing a list of client IDs to query.
+- **Response**: `BatchQueryIpResponse` containing the status code `status_code` and a `client_ip_map`. The keys of this map are the client IDs that have successfully mounted segments, and the values are lists of unique IP addresses extracted from all segments mounted by each client. Client IDs that have no mounted segments or are not found are silently skipped and not included in the result map.
+- **Description**: Used to batch query the IP addresses for multiple client IDs. For each client ID in the input list, this interface retrieves the unique IP addresses from all segments mounted by that client.
+
+4. BatchReplicaClear
+
+```protobuf
+message BatchReplicaClearRequest {
+  repeated string object_keys = 1; // List of object keys to clear
+  required UUID client_id = 2;     // Client ID that owns the objects
+  optional string segment_name = 3; // Optional segment name. If empty, clears all segments
+};
+
+message BatchReplicaClearResponse {
+  required int32 status_code = 1;
+  repeated string cleared_keys = 2; // List of object keys that were successfully cleared
+};
+```
+
+- **Request**: `BatchReplicaClearRequest` containing a list of object keys to clear, the client ID that owns the objects, and an optional segment name. If `segment_name` is empty, all replicas of the specified objects are cleared (the objects are deleted entirely). If `segment_name` is provided, only replicas located on that specific segment are cleared.
+- **Response**: `BatchReplicaClearResponse` containing the status code `status_code` and a list of `cleared_keys` representing the object keys that were successfully cleared. Only objects that belong to the specified `client_id`, have expired leases, and meet the clearing criteria are included in the result. Objects with active leases, incomplete replicas (when clearing all segments), or belonging to different clients are silently skipped.
+- **Description**: Used to batch clear replicas for multiple object keys belonging to a specific client ID. This interface allows clearing replicas either on a specific segment or across all segments, providing flexible storage resource management capabilities.
+
+5. PutStart
+
+```protobuf
+message PutStartRequest {
+  required string key = 1;             // Object key
+  required int64 value_length = 2;     // Total length of data to be written
+  required ReplicateConfig config = 3; // Replica configuration information
+  repeated uint64 slice_lengths = 4;   // Lengths of each data slice
+};
+
+message PutStartResponse {
+  required int32 status_code = 1;
+  repeated ReplicaInfo replica_list = 2;  // Replica information allocated by the Master Service
+};
+```
+
+- **Request**: `PutStartRequest` containing the key, data length, and replica configuration config.
+- **Response**: `PutStartResponse` containing the status code status_code and the allocated replica information replica_list.
+- **Description**: Before writing an object, the Client must call PutStart to request storage space from the Master Service. The Master Service allocates space based on the config and returns the allocation results (`replica_list`) to the Client. The allocation strategy ensures that each slice of the object is placed in different segments, while operating on a best-effort basis - if insufficient space is available for all requested replicas, as many replicas as possible will be allocated. The Client then writes data to the storage nodes where the allocated replicas are located. The need for both start and end steps ensures that other Clients do not read partially written values, preventing dirty reads.
+
+6. PutEnd
+
+```protobuf
+message PutEndRequest {
+  required string key = 1;
+};
+
+message PutEndResponse {
+  required int32 status_code = 1;
+};
+```
+
+- **Request**: `PutEndRequest` containing the key.
+- **Response**: `PutEndResponse` containing the status code status_code.
+- **Description**: After the Client completes data writing, it calls `PutEnd` to notify the Master Service. The Master Service updates the object's metadata, marking the replica status as `COMPLETE`, indicating that the object is readable.
+
+7. Remove
+
+```protobuf
+message RemoveRequest {
+  required string key = 1;
+};
+
+message RemoveResponse {
+  required int32 status_code = 1;
+};
+```
+
+- **Request**: `RemoveRequest` containing the key of the object to be deleted.
+- **Response**: `RemoveResponse` containing the status code `status_code`.
+- **Description**: Used to delete the object and all its replicas corresponding to the specified key. The Master Service marks all replicas of the corresponding object as deleted.
+
+8. RemoveByRegex
+
+```protobuf
+message RemoveByRegexRequest {
+  required string key_regex = 1;
+};
+
+message RemoveByRegexResponse {
+  required int32 status_code = 1;
+  optional int64 removed_count = 2; // The number of objects removed.
+};
+```
+
+- **Request**: RemoveByRegexRequest, which contains the regular expression key_regex to be matched.
+- **Response**: RemoveByRegexResponse, which contains a status_code and the number of objects that were removed, removed_count.
+- **Description**: Used to delete all objects and their corresponding replicas for keys that match the specified regular expression. Similar to the Remove interface, this is a metadata operation where the Master Service marks the status of all matched object replicas as removed.
+
+9. MountSegment
+
+```protobuf
+message MountSegmentRequest {
+  required uint64 buffer = 1;       // Starting address of the space
+  required uint64 size = 2;         // Size of the space
+  required string segment_name = 3; // Storage segment name
+}
+
+message MountSegmentResponse {
+  required int32 status_code = 1;
+};
+```
+
+The storage node (Client) allocates a segment of memory and, after calling `TransferEngine::registerLocalMemory` to complete local mounting, calls this interface to mount the allocated continuous address space to the Master Service for allocation.
+
+10. UnmountSegment
+
+```protobuf
+message UnmountSegmentRequest {
+  required string segment_name = 1;  // Storage segment name used during mounting
+}
+
+message UnMountSegmentResponse {
+  required int32 status_code = 1;
+};
+```
+
+When the space needs to be released, this interface is used to remove the previously mounted resources from the Master Service.
 
 ---
 
@@ -809,4 +840,10 @@ When to bump the version:
 :maxdepth: 1
 
 ssd-offload
+immutable-dfs-bucket-allocator
+ssd-free-ratio-first-allocation
+nvme-kv-backend
+oss-backend
+engram
+
 :::
diff --git a/docs/source/design/store/nvme-kv-backend.md b/docs/source/design/store/nvme-kv-backend.md
new file mode 100644
index 0000000000..a54e991550
--- /dev/null
+++ b/docs/source/design/store/nvme-kv-backend.md
@@ -0,0 +1,178 @@
+# NVMe KV Backend Design
+
+## Overview
+
+The NVMe KV backend extends Mooncake Store's node-local SSD offload path with an NVMe Key-Value namespace. It preserves Mooncake's logical object API while translating variable-length logical keys and values into fixed-size NVMe KV keys and bounded device values.
+
+The implementation separates object semantics from command transport. `NvmeKvStorageBackend` owns logical object layout, integrity validation, key-conflict handling, and batched I/O orchestration. `NvmeKvConnector` binds one configured device to one executor. `NvmeKvCommandExecutor` submits Store, Retrieve, and Delete commands through io_uring or ioctl.
+
+## Design Goals
+
+- Integrate one node-local NVMe KV namespace with the existing SSD offload flow.
+- Preserve object identity and integrity with placement validation and checksums.
+- Support logical objects larger than one device value.
+- Use store-if-not-exists for idempotent writes and explicit hash-collision handling.
+- Overlap object preparation, chunk submission, and root submission with bounded concurrency.
+- Use io_uring when available and ioctl as an initialization fallback.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Control["Mooncake control plane"]
+        Master["Mooncake master\ntracks LOCAL_DISK replicas"]
+    end
+
+    subgraph Requester["Requesting node"]
+        App["Application"]
+        RequestClient["Mooncake client"]
+        App --> RequestClient
+    end
+
+    subgraph Owner["NVMe KV owner node"]
+        RealClient["Mooncake real client"]
+        FileStorage["FileStorage"]
+        Backend["NvmeKvStorageBackend"]
+        Connector["NvmeKvConnector"]
+        Executor["io_uring or ioctl executor"]
+        Device["Local NVMe KV namespace"]
+
+        RealClient --> FileStorage --> Backend --> Connector --> Executor --> Device
+    end
+
+    RequestClient <-->|"metadata query"| Master
+    RealClient <-->|"offload heartbeat and replica updates"| Master
+    RequestClient <-->|"object RPC and Transfer Engine data movement"| RealClient
+```
+
+The master records the object as a `LOCAL_DISK` replica owned by a real client. NVMe KV commands remain local to that client.
+
+## Layer Responsibilities
+
+| Layer | Responsibilities |
+|------|------------------|
+| `FileStorage` | Obtains memory slices, invokes the backend, reports successful replicas, and serves remote SSD reads. |
+| `NvmeKvStorageBackend` | Builds object layouts, applies key-conflict policy, coordinates bounded batch I/O, and verifies data returned by the device. |
+| `NvmeKvConnector` | Resolves the configured device, selects one executor during initialization, and forwards commands. |
+| `NvmeKvCommandExecutor` | Encodes and submits NVMe KV Store, Retrieve, and Delete commands while owning transport-specific buffers and completion handling. |
+| NVMe KV namespace | Executes commands submitted through the Linux device node. |
+
+## Physical Keys and Conflicts
+
+NVMe KV namespaces expose key/value limits through their KV format, including
+the maximum key length and maximum value length supported by the namespace.
+Command completion can also report invalid key or value sizes. Mooncake logical
+keys are variable-length strings, so they cannot be passed to the device
+unchanged.
+
+NVMe KV commands use a 16-byte physical key, while Mooncake logical keys can be longer. The key codec derives root and chunk keys from the complete logical key, object role, chunk index, and conflict slot. Two independently seeded XXH64 values form the physical key, and four independently seeded XXH64 values form the identity verification hash stored in the root header. No logical-key byte is reserved or discarded.
+
+The backend tries at most 64 conflict slots. Every Store uses store-if-not-exists. When a physical key already exists, the backend retrieves the value and compares it with the expected bytes. Identical bytes mean the same object and make the operation idempotently successful. Different bytes mean a physical-key collision, so the backend tries the next slot. Other device errors are returned to `FileStorage`.
+
+Reads derive the same root keys and probe conflict slots until the stored logical identity matches the requested key. Placement metadata in the root must agree with both the observed physical key and the selected slot.
+
+## Object Layout
+
+The value side has the same shape constraint. Mooncake objects can be larger
+than one NVMe KV value, while each Store or Retrieve must stay within the
+effective value limit derived from the protocol/device ceiling, runtime
+transfer limit, and transfer alignment. Chunking exists to adapt Mooncake's
+logical object size to that bounded value model.
+
+```mermaid
+flowchart LR
+    Logical["Mooncake logical object"]
+    Decision{"Fits in one device value?"}
+    Inline["Root value\nheader + identity + payload"]
+    Manifest["Root manifest\nheader + identity + chunk records"]
+    Chunks["Raw chunk values\nchunk0 ... chunkN"]
+
+    Logical --> Decision
+    Decision -->|"yes"| Inline
+    Decision -->|"no"| Manifest
+    Manifest --> Chunks
+```
+
+An inline root contains `NvmeKvObjectHeader`, stored identity metadata, and the logical payload. The header records object type, payload size, identity verification hash, payload checksum, header checksum, and identity metadata size.
+
+A larger object is split into raw chunk values followed by one root manifest. Each manifest record stores the physical chunk key, chunk size, and checksum. The root manifest is written only after all chunks for that object complete successfully, so the root acts as the visibility marker. The manifest itself must fit in one device value.
+
+## Write Path
+
+```mermaid
+sequenceDiagram
+    participant F as FileStorage
+    participant B as NvmeKvStorageBackend
+    participant E as Executor
+
+    F->>B: BatchOffload(key to slices)
+    B->>B: validate limits and prepare checksums/layout
+    alt inline object
+        B->>E: Store root if not exists
+    else chunked object
+        B->>E: StoreBatch chunks if not exists
+        E-->>B: all chunks for one object complete
+        B->>E: queue root on the root lane
+    end
+    alt physical key already exists
+        B->>E: Retrieve existing value
+        B->>B: accept identical object or try next slot
+    end
+    B-->>F: successful keys and object metadata
+```
+
+Preparation workers build payload views, checksums, chunks, and root manifests while independent submission lanes issue device commands. Chunk lanes feed completed objects to a dedicated root lane instead of waiting for every object in the batch. Worker counts and command batches are bounded by the configured concurrency budget and executor queue depth.
+
+On failure, the backend best-effort deletes only keys created by the current attempt. Pre-existing values accepted as the same object are never deleted.
+
+## Read Path
+
+For each requested logical key, the backend derives and validates its root object. Inline payloads are checksum-verified and copied directly to the destination. Manifest roots are validated and converted into chunk records and destination offsets for the current request.
+
+Chunk reads are grouped into bounded tasks. When the selected executor supports direct destination reads, aligned destinations use `RetrieveIntoBatch` so the device can read directly into the Mooncake buffer. Other destinations, and executors that use the default batch implementation, use executor-owned buffers through `RetrieveBufferBatch` followed by a validated copy. Header, identity, placement, manifest, payload, and every chunk checksum are verified before the operation returns.
+
+## Executor Design
+
+### Common command layer
+
+Common utilities own physical-key packing, NVMe KV opcodes, Store/Retrieve/Delete command construction, transfer rounding, aligned buffer allocation, status mapping, and capability calculation. The effective value limit is:
+
+```text
+round_down(min(protocol_max_value_size, runtime_transfer_limit),
+           transfer_alignment)
+```
+
+### io_uring
+
+The io_uring executor uses a thread-local ring and NVMe uring commands with 128-byte SQEs. It requests CQE32 for command results and retries initialization without CQE32 when the kernel does not support it.
+
+Batch submission maintains a bounded number of commands in flight, drains available CQEs, and refills released SQEs immediately. A generation token plus command index in `user_data` rejects stale, duplicate, and out-of-batch completions. Request buffers remain alive until all accepted commands complete. On partial submission failure, the executor drains commands already accepted by the kernel before resetting the ring.
+
+### ioctl
+
+The ioctl executor builds the same command fields in `nvme_passthru_cmd` and submits them through `NVME_IOCTL_IO_CMD`. Calls are synchronous within one backend worker, while the backend worker pool provides parallelism across requests.
+
+### Selection
+
+`auto` tries io_uring first when compiled in and falls back to ioctl only if io_uring initialization fails. Runtime command failures are returned without changing transports. Explicit `io_uring` and `ioctl` modes fail initialization when the requested executor cannot be created.
+
+## Concurrency and Ownership
+
+- Backend worker pools bound object preparation, chunk submission, root submission, and fallback I/O.
+- io_uring rings are thread-local, avoiding a shared hot-path ring lock.
+- Batch APIs are synchronous at their boundary, so request arrays and DMA buffers outlive all command completions.
+- Direct reads verify checksums in the destination buffer after completion.
+- Root submission for a chunked object occurs only after its chunks finish successfully.
+
+## Failure Semantics
+
+| Condition | Behavior |
+|----------|----------|
+| Key not found | Return `OBJECT_NOT_FOUND`. |
+| Store-if-not-exists finds identical bytes | Treat as idempotent success. |
+| Store-if-not-exists finds different bytes | Treat as a physical-key collision and try the next slot. |
+| Header, identity, placement, manifest, or checksum failure | Return `FILE_READ_FAIL`. |
+| Partial chunk write | Best-effort cleanup of keys created by the failed attempt. |
+| io_uring submission or completion anomaly | Drain accepted commands, reset the thread-local ring, and fail the operation. |
+| io_uring initialization failure in `auto` mode | Try ioctl. |
+| Runtime device I/O failure | Return the mapped error without transport fallback. |
diff --git a/docs/source/design/store/oss-backend.md b/docs/source/design/store/oss-backend.md
new file mode 100644
index 0000000000..57d6334c4e
--- /dev/null
+++ b/docs/source/design/store/oss-backend.md
@@ -0,0 +1,183 @@
+# OSS Backend Design
+
+## Overview
+
+The object-storage backend extends Mooncake Store's client-owned offload path
+to key-based storage services, such as OSS and S3, through service-specific
+adapters. It uses the same `LOCAL_DISK` replica model as local-file and NVMe KV
+backends: the master records an owner and the requesting client reads through
+that owner. Object storage is not a separate first-class replica type here.
+
+This document describes the OSS adapter implementation. Its signing protocol
+is OSS-specific; S3 requires a compatible adapter, not just a different endpoint.
+
+For prerequisites, configuration, and startup examples, see
+[OSS Local-Disk Backend](../../deployment/oss-offload.md).
+
+## Design Goals
+
+- Reuse `FileStorage` offload coordination and existing Store APIs.
+- Issue concurrent object GETs and PUTs within a synchronous batch.
+- Give each batch its own libcurl multi handle, without a shared batch lock.
+- Avoid a full-object intermediate string on the direct GET path and avoid
+  concatenating upload slices into a full-object buffer.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    Master["Mooncake master<br/>LOCAL_DISK replicas and owners"]
+    Requester["Requesting Mooncake client"]
+    subgraph Owner["Offload owner process"]
+        RealClient["RealClient"]
+        FileStorage["FileStorage"]
+        Backend["DistributedStorageBackend"]
+        Adapter["OssObjectStorageAdapter<br/>libcurl and OSS signing"]
+        RealClient --> FileStorage --> Backend --> Adapter
+    end
+    OSS["OSS bucket / owner prefix"]
+
+    Requester <-->|"metadata query"| Master
+    RealClient <-->|"offload heartbeat and completion"| Master
+    Requester <-->|"offload RPC and Transfer Engine"| RealClient
+    Adapter <-->|"HTTP"| OSS
+```
+
+## Layer Responsibilities
+
+| Layer | Responsibilities |
+|-------|------------------|
+| Master | Schedule offload tasks and track completed `LOCAL_DISK` replicas and their owners. |
+| `FileStorage` | Obtain source slices, call the selected backend, report successful writes, and manage read staging buffers. |
+| `DistributedStorageBackend` | Convert `BatchOffload` / `BatchLoad` into object batches and check per-object results and read lengths. |
+| `OssObjectStorageAdapter` | Map keys, sign HTTP requests, run libcurl transfers, and implement GET/PUT/HEAD/LIST/DELETE. |
+| OSS | Store object payloads under the configured bucket and prefix. |
+
+One `FileStorage` instance selects one backend. Selecting OSS does not also
+enable the local-file or NVMe KV backend, or create an SSD-to-OSS cache hierarchy.
+
+## Physical Keys and Object Layout
+
+The adapter maps each storage key supplied by `FileStorage` to one OSS object:
+
+```text
+physical_key = owner_prefix + "/" + URIEncode(storage_key)
+object_body  = concatenated payload slices
+```
+
+The prefix separator is omitted when the prefix is empty. LIST decodes matching
+object keys back into logical storage keys; `ScanMeta` uses these keys and object
+sizes for metadata registration.
+
+There is no shard/offset allocation, per-object UUID descriptor, root manifest,
+or adapter-level checksum envelope. A PUT targets the mapped key, not a
+store-if-not-exists operation. Separate owner prefixes prevent owners from
+overwriting each other's objects.
+
+## Write Path
+
+```mermaid
+sequenceDiagram
+    participant M as Master
+    participant F as Owner FileStorage
+    participant B as DistributedStorageBackend
+    participant A as OSS adapter
+    participant O as OSS
+
+    F->>M: OffloadObjectHeartbeat (default: every 10 s)
+    M-->>F: Offload tasks for this owner
+    F->>B: BatchOffload(keys and source slices)
+    B->>A: PutBatch(key, iov, iovcnt)
+    A->>O: Concurrent object PUTs
+    O-->>A: Per-request completion
+    A-->>B: Per-object results
+    B-->>F: Completion callback for successful objects
+    F->>M: NotifyOffloadSuccess
+    Note over M: Register completed LOCAL_DISK replicas
+```
+
+The application's memory `Put` is not a synchronous OSS write. Offload is
+scheduled separately; only successful uploads are reported as completed
+replicas. A batch is not a transaction: successful objects remain in OSS when
+another upload fails.
+
+## Read Path
+
+```mermaid
+sequenceDiagram
+    participant R as Requesting client
+    participant M as Master
+    participant F as Owner RealClient / FileStorage
+    participant B as Backend / OSS adapter
+    participant O as OSS
+
+    R->>M: Query key
+    M-->>R: LOCAL_DISK owner and object size
+    R->>F: batch_get_offload_object
+    F->>B: BatchLoad into staging buffers
+    B->>O: Concurrent GETs (GetBatch)
+    O-->>B: Object bytes
+    B-->>F: Validate results and lengths
+    F-->>R: Staging buffer descriptors
+    R->>F: Fetch bytes through Transfer Engine
+    R->>F: Release staging buffers after transfer
+```
+
+The RPC coroutine posts blocking work to the existing blocking pool. It can
+yield while a worker executes `BatchLoad`; the worker waits until the HTTP batch
+finishes. No dedicated OSS worker pool is introduced.
+
+`Get`, `GetRange`, and `GetBatch` copy incoming libcurl chunks directly into the
+destination buffer. This removes the full-object response string and its final
+copy, not all copies. `GetV` still reads into a contiguous temporary buffer and
+then scatters. `PutV` / `PutBatch` consume iovec arrays through the upload
+callback; copies into libcurl's upload buffer remain.
+
+## Batch Execution
+
+Each `GetBatch` or `PutBatch` call creates a temporary `CURLM` and one easy handle
+per prepared request. It admits up to `MOONCAKE_OSS_MAX_CONNECTIONS` requests
+(default: 64), advances them together, and admits more as requests complete.
+Requests waiting for admission stay outside `CURLM` so that their transfer
+timeout is not consumed in libcurl's connection queue.
+
+Connections are reused within a batch, not across batches. Different caller
+threads can execute separate batches concurrently; the limit is per batch,
+not per adapter or process. Completion order may differ from input order, but
+the returned result vector preserves input order and cardinality.
+
+## Concurrency and Ownership
+
+- Adapter APIs are synchronous: they return after batch processing and cleanup.
+- Each batch owns its request contexts and libcurl handles; there is no shared
+  `CURLM` or adapter-wide lock serializing complete batches.
+- **Download buffers, upload iovec arrays, and upload payloads must remain alive
+  until the call returns. Upload descriptors and payloads must not be modified
+  while in use.**
+- **A failed read may have partially modified its destination; do not consume
+  that buffer as valid data.** A failed `BatchLoad` does not expose the batch as
+  a successful Store read, even if some underlying GETs completed.
+
+## Failure Semantics
+
+| Condition | Behavior |
+|-----------|----------|
+| Invalid buffer or iovec arguments detected before batch setup | Return `INVALID_PARAMS` for that entry; other valid entries can proceed. |
+| GET reports a missing object | Return `FILE_NOT_FOUND`. |
+| GET returns an unexpected status or length | Return a read failure; a nonempty range GET requires HTTP 206 and the requested length. |
+| PUT returns a non-success HTTP status | Return a write failure; do not report that object as successfully offloaded. |
+| Transport error or timeout | Return a request error; a timed-out PUT does not prove that OSS stored nothing. |
+| Request setup or multi-handle failure | Return errors for requests that could not complete; do not roll back successful cloud writes. |
+| One object fails in a batch | Preserve per-object results; successful uploads are not automatically deleted. |
+
+## Current Limitations
+
+- Readers depend on a reachable owner and valid Master metadata, not just the
+  existence of an OSS object. This is different from a first-class DFS replica.
+- Master capacity accounting uses each owner's configured capacity and live
+  replica sizes. It neither queries OSS free space nor enforces a bucket quota.
+- The backend does not implement capacity eviction or automatic cloud-object
+  garbage collection. Removing Master metadata does not issue an OSS DELETE;
+  metadata usage can therefore differ from actual bucket usage.
+- Multipart uploads, automatic parallel range splitting, and automatic
+  credential refresh are not implemented.
diff --git a/docs/source/design/ssd-free-ratio-first-allocation.md b/docs/source/design/store/ssd-free-ratio-first-allocation.md
similarity index 100%
rename from docs/source/design/ssd-free-ratio-first-allocation.md
rename to docs/source/design/store/ssd-free-ratio-first-allocation.md
diff --git a/docs/source/design/ssd-offload.md b/docs/source/design/store/ssd-offload.md
similarity index 80%
rename from docs/source/design/ssd-offload.md
rename to docs/source/design/store/ssd-offload.md
index 1ca2607499..f3be569cb7 100644
--- a/docs/source/design/ssd-offload.md
+++ b/docs/source/design/store/ssd-offload.md
@@ -6,7 +6,7 @@ Mooncake Store supports offloading KV cache objects from distributed memory to l
 
 SSD offload is implemented as a background subsystem within the **real client** process. It is transparent to the application: a `Put` that would otherwise be evicted from memory is persisted to disk, and a `Get` that finds no memory replica automatically falls back to reading from SSD.
 
-For multi-turn conversation benchmark results, see [Mooncake SSD Offload Benchmark](../performance/mooncake/ssd-offload-benchmark-results.md).
+For multi-turn conversation benchmark results, see [Mooncake SSD Offload Benchmark](../../performance/mooncake/ssd-offload-benchmark-results.md).
 
 ---
 
@@ -93,7 +93,7 @@ Step by step:
 
 ### Load (SSD → memory)
 
-The load path involves three parties: the **requesting client**, the **target client** that holds the SSD data, and the **Transfer Engine** for zero-copy data movement.
+The default load path involves three parties: the **requesting client**, the **target client** that holds the SSD data, and the **Transfer Engine** for data movement.
 
 ```
 Requesting Client                 Target Client                    Master
@@ -119,13 +119,15 @@ Requesting Client                 Target Client                    Master
        │                                    │ (free ClientBuffer slot)│
 ```
 
+For a same-process GPU destination, FileStorage reads into a quota-bounded pinned restore arena and submits H2D copies to the caller's GPU slices. Tensor ranges use a source offset, avoiding another CPU staging allocation. This path requires local memcpy and a pinned quota; CPU and remote restores are unchanged.
+
 Step by step:
 
 1. **Query master**: The requesting client calls `client_->BatchGet(keys, ...)` to query the master for replica locations. If the object has been offloaded, the master returns a `LOCAL_DISK` replica descriptor containing the target client's RPC address (`transport_endpoint`).
-2. **RPC to target client**: The requesting client calls `batch_get_offload_object(keys, sizes)` on the target client identified by `transport_endpoint`. The target client calls `FileStorage::BatchGet`, which allocates slots in `ClientBuffer` and reads the requested objects from SSD via `StorageBackend::BatchLoad`.
-3. **Response with buffer pointers**: The target client returns a `BatchGetOffloadObjectResponse` containing `batch_id`, a list of buffer `pointers` (addresses within `ClientBuffer`), the Transfer Engine address, and `gc_ttl_ms` (the buffer lease TTL).
-4. **Zero-copy transfer**: The requesting client invokes `client_->BatchGetOffloadObject(transfer_engine_addr, keys, pointers, slices)`, which uses the Transfer Engine (RDMA or TCP) to pull the data directly from the target client's `ClientBuffer` into the application's target memory (DRAM or VRAM). No intermediate copy is made on the requesting client side.
-5. **Release buffer**: After the transfer completes, the requesting client immediately calls `release_offload_buffer(batch_id)` on the target client to free the `ClientBuffer` slots. If the transfer takes longer than `gc_ttl_ms`, the buffer GC thread reclaims the slot automatically as a fallback.
+2. **Select the owner path**: For a different process, the requesting client calls `batch_get_offload_object(keys, sizes)` on the target client identified by `transport_endpoint`. For a same-process GPU restore with pinned quota and local memcpy enabled, it calls the local `FileStorage::BatchGetLocal` path.
+3. **Response with buffer pointers**: Remote requests receive pointers within `ClientBuffer`, plus a `batch_id`, Transfer Engine address, and buffer lease TTL. The local path receives pointers within the pinned restore arena and keeps their allocation owner in the requesting process.
+4. **Transfer data**: Remote restores use the Transfer Engine (RDMA or TCP). The same-process pinned branch submits H2D copies from the local restore arena and supports per-object source offsets for tensor payloads.
+5. **Release buffer**: Remote restores call `release_offload_buffer(batch_id)` and retain TTL GC as a failure fallback. A same-process allocation is held by an RAII owner through the synchronous H2D operation and released automatically on success or failure; it is never published in the remote batch map.
 
 ---
 
@@ -160,6 +162,22 @@ A single pre-allocated file (`kv_cache.data`) is shared by all objects. Space wi
 
 When `MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` is set, the backend evicts existing buckets to make room before writing a new one. Eviction is disabled by default (`BucketEvictionPolicy::NONE`).
 
+### Physical disk cap (BucketStorageBackend)
+
+`MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE` bounds `total_size_`, a *logical* byte counter kept in memory: incremented on write, decremented per object as buckets are evicted. Two properties limit what it can guarantee:
+
+- It is **per backend instance**. At runtime each instance's `total_size_` counts only the bytes *it* wrote. So when several instances share one offload directory (e.g. one per tensor-parallel rank, all on the same `ssd_offload_path`), each caps only its own `~1/N` share and the directory as a whole is never bounded. (One exception: on restart, `Init()` rebuilds `total_size_` by scanning `storage_path_`, so in a shared directory a restarted instance folds *all* ranks' files into its own counter — a recovery-time double-count.)
+- It is **logical, not physical**. It ignores filesystem block rounding and can lag the real on-disk footprint — a 256 MB bucket file stays on disk until every object packed into it has been evicted.
+
+`MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES` (default `0` = disabled) adds a hard cap on the *real* on-disk usage of the offload directory, measured by `ActualDiskBytesUsedLocked()`:
+
+- It scans `storage_path_` with `std::filesystem::recursive_directory_iterator` and sums `stat.st_blocks * 512` over the entries. `st_blocks` is the number of 512-byte blocks actually allocated to a file — a fixed POSIX unit, independent of the filesystem block size — so the total equals what `du` reports and what a Kubernetes `emptyDir` `sizeLimit` is accounted against (it includes block rounding and excludes sparse holes).
+- The scan is scoped to `storage_path_`, so the cap's meaning follows the layout: when instances **share** one directory, each scans the whole directory and the cap bounds their **combined** usage; with **per-rank** directories (or separate disks), each scans only its own files and the cap bounds **each rank individually**. (A cap on the global sum across ranks under any layout would require master-side aggregation and is out of scope here.)
+- The scan is cached for `MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS` (default 500 ms; `<= 0` re-scans on every check) to bound its cost, and is snapshotted once per `PrepareEviction` call under the metadata lock. `FinalizeEviction` invalidates the cache after deleting files so the next check re-measures.
+- If the directory cannot be scanned — an open error, or an iteration error partway through — the function **fails closed**: it reports the cap as reached and does not cache the partial total, so a transient scan failure drives eviction/rejection instead of silently disabling the cap.
+
+The two caps are independent and may be combined; when both are set a write must satisfy both, and eviction continues until the projected post-eviction usage is under both limits.
+
 ### Proactive watermark eviction
 
 `FileStorage::Heartbeat()` also calls the backend-level proactive disk watermark path when `MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION=true`. The high watermark decides when eviction starts and the low watermark decides the target usage after eviction. This path is independent of write admission, so disk usage can move back toward the low watermark even when no new write arrives.
@@ -189,7 +207,7 @@ Eviction is split into two phases to ensure that the master is notified before f
 
 **Phase 1 — `PrepareEviction(required_size)`** (called under exclusive lock):
 
-1. Repeatedly call `SelectEvictionCandidate()` until `total_size_ + required_size <= max_total_size`.
+1. Repeatedly call `SelectEvictionCandidate()` until the projected post-eviction usage is within every configured cap: `total_size_ + required_size <= max_total_size` (logical), and — when `max_physical_bytes > 0` — `physical_used_start + required_size - accumulated_freed_space <= max_physical_bytes` (physical), where `physical_used_start` is the `ActualDiskBytesUsedLocked()` snapshot taken once at the start of the call. If the candidate supply is exhausted before the caps are satisfied, the write is rejected with `FILE_WRITE_FAIL`.
 2. For each selected bucket: remove it from `buckets_` and `object_bucket_map_`, subtract its size from `total_size_`.
 3. Collect all evicted keys and bucket metadata into a `PendingEviction` struct and return it — no file I/O at this point.
 
diff --git a/docs/source/design/tent/deadline-scheduling.md b/docs/source/design/tent/deadline-scheduling.md
new file mode 100644
index 0000000000..5b763722a5
--- /dev/null
+++ b/docs/source/design/tent/deadline-scheduling.md
@@ -0,0 +1,610 @@
+# TENT Deadline Scheduling
+
+## Overview
+
+This document describes how TENT schedules transfers that carry a deadline: the
+**admission queue** that orders, promotes and drops requests before they reach
+a transport, and the **RDMA bandwidth arbitration** that orders slices on a NIC
+before they are posted. Both are opt-in and both predict deadline feasibility
+with one shared formula; they differ in what they can see ahead of a request,
+and in what they do about it.
+
+It also sets the two next to [device selection](slice-spraying.md), which
+runs on the same NICs and keeps its own bandwidth estimate, because the three
+are easy to confuse and are deliberately not the same thing.
+
+The document is ordered from the shared parts to the specific ones: the path a
+deadline takes, the prediction both layers make and the bandwidth series that
+feeds it, then the admission queue and the arbitration each with a worked
+example, then configuration, metrics and known limits.
+
+## Background
+
+A KV-cache transfer in disaggregated serving is only useful if it lands before
+the consumer needs it. TENT's QoS priorities (see [Quality of
+Service](qos.md)) separate business classes, but within one class every flow is
+served alike: a NIC splits its bandwidth equally among contenders, and the
+engine dispatches in arrival order. Neither knows that one flow has ten
+milliseconds left and another has a second.
+
+RFC #2519 introduced an absolute deadline on `Request` and built on it in three
+steps, each opt-in and each leaving the previous behavior byte-identical when
+off:
+
+1. **Observe**: on completion, record how much of its window a transfer
+   actually took, as measured latency over window. This ratio is the MLU
+   (`tent_deadline_mlu_permille`).
+2. **Order**: dispatch the request with the earliest deadline first.
+3. **Degrade**: predict which requests cannot make their window and cancel
+   them up front, so the caller can fall back (recompute locally, for
+   example) instead of waiting for a late transfer.
+
+RFC #2792 added the same prediction at the NIC: among slices that are about to
+be posted on one queue pair, post the most urgent first.
+
+## The Path of a Deadline
+
+```
+Request{deadline_ns, intent_type, priority}
+        |
+        v
+  submitTransfer
+        |
+        v
+  Admission queue (enable_runtime_queue)          <- runtime_queue/*
+     tryAdmit      : capacity limits, EDF insert
+     pickForDispatch: promotion, drop, dispatch window
+        |
+        v
+  Transport (RDMA)
+     device selection : which NIC                 <- transports/rdma/* (slice-spraying.md)
+     arbitration      : post order on that NIC    <- deadline_bw_arbitration
+        |
+        v
+  Completion -> tent_deadline_mlu_permille
+```
+
+A request with `deadline_ns == 0` takes the same path and is never reordered,
+promoted or dropped: every predicate below treats "no deadline" as "nothing to
+predict".
+
+## Predicting Feasibility: MLU
+
+The scheduling layers use the same ratio as the metric, with a **predicted**
+transfer time in place of the measured latency: the metric reports what a
+transfer took, the predictor estimates what it will take before it runs. Both
+layers use one definition, `DeadlineMlu()` in `tent/runtime/deadline_mlu.h`:
+
+```
+predicted_mlu = ((bytes_ahead + length) / bandwidth) / (deadline_ns - now_ns)
+```
+
+- `length` is the request's own bytes.
+- `bytes_ahead` is what must move before them. The deadline is absolute, so
+  this wait counts against the window as an **additive** delay over the wire
+  rate. It is not folded into a slower bandwidth, which would multiply the
+  wait by the request's size.
+- `bandwidth` is the **transmit estimate**, one of the two per-NIC series
+  described in [Bandwidth Series](#bandwidth-series) below, never the
+  selection EWMA that device selection reads.
+
+MLU below 1 means the request is predicted to make its window; 1 is the
+boundary; above 1 it is predicted to miss. Two edge rules: no deadline or no
+usable bandwidth (`<= 0`) yields 0, so such a request is never urgent and never
+dropped; a deadline already in the past is infinitely urgent, which in the
+queue means it is dropped whenever the drop is on, and in the arbitration
+means it posts first.
+
+The two layers deliberately read **different** `bytes_ahead`, each counting the
+bytes it can actually see at its decision point:
+
+| Layer | Decides | `bytes_ahead` |
+|---|---|---|
+| Admission queue | before the request reaches a worker | every drop-eligible owner already dispatched and not yet completed, including slices still waiting in worker queues (`dispatching_bytes_`) |
+| RDMA arbitration | at posting time, on one NIC | bytes already posted to that NIC's hardware (`getPostedBytes`), plus the slots the arbitration has already placed ahead in this pass |
+
+The admission side reads the wider set on purpose: its decision (a drop) is
+irreversible, so it is the conservative one. The arbitration only reorders, and
+the worker-queue slices it would otherwise count are its own contenders.
+
+### How Each Layer Evaluates It
+
+The formula is shared; every input to it is chosen per layer.
+
+| | Admission drop | RDMA arbitration |
+|---|---|---|
+| Evaluated | once per queued owner, in `pickForDispatch`, before the request reaches any worker | once per slice per slot, in `orderByDeadline`, just before `submitSlices` |
+| `length` | the whole request | one slice |
+| `bandwidth` | the transmit estimate of the transport that will carry the owner: RDMA's `getEstimatedBandwidth()` (sum over its RNICs) or UB's own estimate | the transmit estimate of the NIC these slices will post on |
+| `bytes_ahead` on entry | `dispatching_bytes_`: every eligible owner dispatched and not yet completed, on any NIC, including slices still in worker queues | `getPostedBytes(dev)`: bytes on this NIC's hardware, not yet completed; nothing from worker queues |
+| `bytes_ahead` during the pass | grows by each owner **dispatched** in this call; a dropped owner adds nothing | grows by each slice **placed** in an earlier slot; every slice is placed eventually |
+| `now` | read once per `pickForDispatch` | read once per `orderByDeadline` |
+| Who is scored | eligible owners only (RDMA or UB route, not staged); others are dispatched without a prediction | every slice in the group; a slice without a deadline scores 0 |
+| Threshold | `mlu >= mlu_local_threshold` → cancel | none; scores are only compared with each other |
+| Effect of a high value | the request never runs | the slice posts earlier |
+| Past deadline | infinite → cancelled | infinite → first slot |
+| No usable bandwidth | drop disabled for this pass, everything dispatched | order left as it arrived |
+
+Two consequences follow. The admission prediction treats all in-flight bytes
+as if they were served serially ahead of the request, although they are spread
+over several NICs and move in parallel, so it is systematically pessimistic;
+that is why θ_local sits above 1.0. The arbitration prediction is per NIC and
+per slice, so it is close to what that queue pair will actually do, but it
+only ever sees the slices that reached this worker in this tick: a more urgent
+slice arriving one tick later takes its turn in the next batch.
+
+## Bandwidth Series
+
+Each RDMA device keeps two bandwidth estimates, learned from the same
+completion events but along two different loops. Both use the update
+`new = α × old + (1 − α) × sample` and both are clamped to
+`ewma_min_bandwidth_multiplier` .. `ewma_max_bandwidth_multiplier` of the
+link speed; everything else differs.
+
+### One Slice, Two Meters
+
+```
+ worker posts slice            NIC completes it          poller handles it
+ ---------+------------------------+-------------------------+----------------
+          | submit_ts recorded     |                         | poll_ts
+          | posted_bytes += len    |                         | posted_bytes -= len
+          | (busy stretch opens    |                         | completed_bytes += len
+          |  if it was 0)          |                         |
+          |                        |                         |
+          |<------- post -> completion latency ------------->|  selection sample:
+          |                                                  |  len / latency
+          |                                                  |
+          |  busy time: only while posted_bytes > 0          |  transmit sample, at most
+          |  (this and every other slice on the NIC)         |  every 10 ms, last completion
+          |                                                  |  of a poll pass:
+          |                                                  |  Δcompleted_bytes / Δbusy_time
+```
+
+### Selection EWMA (device selection)
+
+1. **Sample source**: one slice, on its own successful completion. The
+   worker takes `poll_ts − submit_ts`, the time from this post to this
+   completion, and the sample is `slice length / that time`.
+2. **What it contains**: the slice's wire time **plus** its wait behind every
+   work request the NIC already held when it was posted. A backed-up NIC
+   therefore produces low samples.
+3. **When**: every successful completion, unconditionally. Failed, flushed,
+   timed-out, cancelled or re-routed slices contribute nothing.
+4. **Update**: α = `bandwidth_learning_rate` = 0.01, so the estimate is
+   almost entirely the latest sample; it reacts within one or two
+   completions.
+5. **Reader**: device selection, as `predicted_time = (inflight + slice) /
+   ewma` when scoring NICs. Queueing being inside the sample is what the
+   selector wants: it is choosing *among* NICs, and a NIC that is slow
+   because it is busy should lose the comparison.
+
+### Transmit Estimate (admission drop and arbitration)
+
+1. **Sample source**: the NIC as a whole, over a time interval. Two counters
+   run per device: `completed_bytes`, added to by every completion, and
+   `busy_ns`, which accumulates only while the NIC has at least one posted,
+   uncompleted work request (a stretch opens when `posted_bytes` goes from 0
+   to non-zero and closes when it returns to 0).
+2. **What it contains**: bytes moved per unit of time the NIC was actually
+   working. Idle gaps between bursts are not charged, and a slice's own wait
+   behind earlier work is not visible, because the ratio does not look at
+   individual slices at all.
+3. **When**: at most once per `transmit_meter_interval_ns` (10 ms), taken at
+   the last completion of a poll pass (every completion in a pass carries the
+   same timestamp, so a sample mid-pass would split one burst across two
+   intervals). One sampler per interval is chosen by CAS when several lanes
+   poll at once. The first sample only sets the baseline. An interval that
+   spans more than `transmit_meter_max_interval_ns` (50 ms) of wall clock is
+   discarded: it describes a link too far in the past. A slice that ends
+   without moving its bytes (failed, flushed, timed out) invalidates the
+   current stretch and the meter starts fresh.
+4. **Update**: α = `transmit_bandwidth_learning_rate` = 0.9, so a single
+   sample moves the estimate by a tenth of the difference; about ten
+   intervals, roughly 100 ms under load, to follow a real change. With no
+   usable interval the estimate keeps its last value, or the link-speed seed
+   from `openDevice()`: the optimistic direction, which cannot cause a false
+   drop.
+5. **Readers**: the admission drop, as the estimate of the owner's own transport
+   (RDMA sums its RNICs, UB reports its own), and the arbitration, as this NIC's
+   value.
+   Both add the queueing term themselves through `bytes_ahead`, so the rate
+   must not contain it, or the wait would be counted twice.
+
+### Side by Side
+
+The two series, input by input:
+
+| | Selection EWMA | Transmit estimate |
+|---|---|---|
+| Unit of measurement | one slice | one NIC over one interval |
+| Numerator | slice length | bytes completed in the interval |
+| Denominator | post → completion of that slice | NIC busy time in the interval |
+| Includes queueing behind earlier work | yes, on purpose | no, on purpose |
+| Sampled | every successful completion | at most every 10 ms, last completion of a pass |
+| α | 0.01 (follows the latest sample) | 0.9 (~100 ms to converge) |
+| Fed by | `release()` | `maybeSampleTransmit()` |
+| Read by | `DeviceSelector::allocate()` | `getEstimatedBandwidth()` (sum, RDMA) or the UB transport's estimate, `orderByDeadline()` (per NIC) |
+| Question answered | which NIC is the better choice right now | how fast does this NIC move bytes once posted |
+
+Why per-completion timing cannot serve the predictors: up to `max_qp_wr` work
+requests are posted in one call with effectively one timestamp, and a poll
+pass timestamps every completion it collects alike, so a slice's own
+post-to-completion time grows with the depth of the batch it travelled in.
+Deep enough, the selection sample would sit on its lower clamp on a perfectly
+healthy link. Bytes over busy time does not depend on how the work was
+batched.
+
+## Admission Queue
+
+The queue lives in `LocalTransferAdmissionQueue`
+(`tent/runtime/admission_queue.*`) and is owned by `TransferEngineImpl`. It is
+off unless `enable_runtime_queue` is true; with it off, `submitTransfer` hands
+requests straight to the transport, as before.
+
+### What Enters the Queue
+
+A submit is queued as a whole or not at all. A submit that contains any
+**staged** owner (one that must be copied through a staging buffer, see the
+proxy path) bypasses the queue entirely; staging-internal submits always
+queue. Each owner records whether it is **degradation eligible**: routed to
+RDMA or UB and not staged. Only eligible owners can be dropped and only their
+bytes count toward `bytes_ahead`, because the bandwidth provider belongs to the
+owner's own transport and says nothing about a TCP, NVLink or staging transfer.
+
+`tryAdmit` enforces the capacity limits: `max_outstanding_owners` and
+`max_outstanding_bytes` bound everything admitted and not yet terminal, with
+`staging_owner_reserve` and `staging_byte_reserve` held back so staging-internal
+work can always make progress. A request longer than `max_dispatch_bytes` is
+rejected at submit, since it could never fit a dispatch window.
+
+### Ordering
+
+With `deadline_aware` off the queue is FIFO. With it on, owners carrying a
+deadline are inserted in **earliest-deadline-first** order at admission time,
+and owners without a deadline keep FIFO order behind them. Dispatch then
+consumes from the front, so the hot path stays O(picked) rather than re-sorting
+on every call.
+
+### Promotion
+
+`promotion_slack_ns`, when positive, moves any queued owner whose remaining
+slack (`deadline_ns - now`) has fallen below that value to the front of the
+queue, ahead of owners with more slack or none. A stable partition keeps EDF
+order inside each group. This is how a request that was comfortable when it
+was admitted but has since become urgent overtakes the ones admitted before
+it. It requires `deadline_aware`.
+
+### Deadline-Infeasible Drop
+
+`mlu_local_threshold` (θ_local), when positive and combined with
+`deadline_aware` and an installed bandwidth provider, turns on the drop.
+`pickForDispatch` walks the queue from the front; for each eligible owner it
+computes the predicted MLU against the current `dispatching_bytes_` and, if the
+value reaches θ_local, marks the owner **CANCELED** instead of dispatching it,
+releases its capacity, and raises the `on_local_decode_suggested` hook. The
+scan continues, since later owners have looser deadlines. A dropped owner does
+not consume dispatch budget.
+
+The caller sees the drop as a `CANCELED` task status. The hook is the intended
+signal for "recompute locally"; today the engine installs an empty hook set,
+so nothing beyond the status is delivered (see [Known Limits](#known-limits)).
+
+### Bandwidth Provider
+
+`TransferEngineImpl` installs a transport-aware provider, so an owner is
+predicted with the rate of the transport that will carry it: for RDMA that is
+`RdmaTransport::getEstimatedBandwidth()`, the sum over the local RNICs of each
+device's transmit estimate; for UB it is the UB transport's own estimate. It is
+installed only when at least one of those transports is present; without either
+the drop is inactive even if θ_local is set, and a warning is logged at startup.
+The provider is resolved at most once per transport in a dispatch pass, and the
+transport is snapshotted with the admission decision, so a later transport
+failover does not re-score an owner that is already queued.
+
+### Choosing θ_local
+
+MLU 1.0 is the boundary between met and missed, so a
+threshold **below 1.0 drops requests the predictor itself expects to
+succeed**. Measured on hardware with θ = 0.5, dispatch fell to a fraction of
+the offered load while every request that was dropped would have made its
+window. Dropping does not depress the bandwidth estimate in return: the
+transmit meter charges bytes to the NIC's busy time, so a NIC carrying half the
+load reads the same rate over half the time. The loss is throughput, in
+proportion to how much feasible work the threshold refuses.
+
+A value slightly **above** 1.0 is the useful setting, because the predictor is
+conservative by construction. `bytes_ahead` is every eligible byte dispatched
+and not yet completed, and the formula charges all of it ahead of the new
+request as if it were served serially; in practice those bytes are spread over
+several NICs and queue pairs and move in parallel, and the new request's own
+slices are spread the same way. So a predicted MLU of 1.1 usually still lands
+on time. θ in the range 1.2 to 1.5 absorbs that bias and drops only requests
+the wait alone rules out. The code does not currently validate the lower
+bound; treat 1.0 as the floor.
+
+### Dispatch Window and Progress
+
+`max_dispatch_owners` and `max_dispatch_bytes` bound how much the queue hands
+to transports at once. The window refills on every submit and on every poll,
+and the `ProgressWorker` refills it again whenever a transport reports task
+completion. RDMA completions do not yet wake the worker, so with the queue
+active the worker also refills on a timer, `progress_fallback_interval_us`
+(50 ms by default). That timer is the upper bound on how long a dispatch slot
+can sit free after an RDMA transfer finishes.
+
+### Worked Example: Three Requests
+
+Two RNICs whose transmit estimates sum to 800 Gb/s (100 GB/s), `deadline_aware`
+on, θ_local = 1.2, `max_dispatch_bytes` raised to 1 GiB so the sizes below fit
+one window, and an empty queue. Three submits arrive in this order:
+
+| Request | Length | Deadline window at submit | Eligible |
+|---|---|---|---|
+| R1 | 64 MiB | 20 ms | yes (RDMA) |
+| R2 | 512 MiB | 5 ms | yes (RDMA) |
+| R3 | 16 MiB | 3 ms | no (routed to TCP) |
+
+**Admission.** Each `tryAdmit` inserts by deadline, so the queue reads R3
+(3 ms), R2 (5 ms), R1 (20 ms) regardless of arrival order. Suppose the first
+`pickForDispatch` runs after all three are queued.
+
+**Dispatch pass 1.** `bytes_ahead` starts at 0 (`dispatching_bytes_`).
+
+- R3 is first. It is not eligible, so the drop check is skipped; it is
+  dispatched to TCP. Its bytes do not enter `dispatching_bytes_`.
+- R2: predicted time 512 MiB / 100 GB/s ≈ 5.4 ms against a 5 ms window, MLU
+  ≈ 1.07. Below 1.2, so it is dispatched; `dispatching_bytes_` becomes
+  512 MiB.
+- R1: predicted time (512 + 64) MiB / 100 GB/s ≈ 6.0 ms against 20 ms, MLU
+  ≈ 0.30. Dispatched; `dispatching_bytes_` is now 576 MiB.
+
+**A fourth request.** R4, 256 MiB with a 6 ms window, arrives while R2 and R1
+are still in flight. Its predicted time is (576 + 256) MiB / 100 GB/s ≈ 8.7
+ms, MLU ≈ 1.45. That reaches 1.2: R4 is marked `CANCELED` at pick time and
+never reaches a transport. The caller sees `CANCELED` on its next poll and can
+recompute locally instead of waiting almost 9 ms for a transfer that would
+land close to 3 ms late.
+
+Had θ_local been 0.9, R2 would have been dropped in pass 1 with MLU 1.07: a
+request the predictor expected to miss by only 0.4 ms, and one that on a
+slightly better link would have made it. That is the sense in which values
+below 1.0 are too aggressive and values just above 1.0 are the useful range.
+
+**Completion.** When R2 completes, `complete()` subtracts its 512 MiB from
+`dispatching_bytes_`, and the transmit meter has meanwhile learned from the
+bytes R2 moved: if the NICs sustained 380 Gb/s rather than 400, the provider's
+sum drifts down over the next ~100 ms and later predictions become slightly
+more conservative.
+
+## RDMA Bandwidth Arbitration
+
+Arbitration is in `Workers::orderByDeadline` with the pure ordering policy in
+`tent/transport/rdma/bw_arbitration.h`. It is off unless
+`transports/rdma/deadline_bw_arbitration` is true; off, the post order is
+exactly the arrival order.
+
+It runs **within one priority tier**: QoS priorities still decide which tier
+posts first, arbitration decides the order inside the tier. When a worker has
+gathered the slices it is about to post on one NIC, it:
+
+1. Reads that NIC's transmit estimate. Zero or below means nothing to predict
+   from and the order is left alone.
+2. Checks whether any slice carries a deadline; if none does, every MLU would
+   be 0 and the pass is skipped.
+3. Takes `bytes_ahead` as the NIC's **posted bytes**: work that has reached
+   the hardware and has not completed. None of the candidates is in it, and
+   neither is work still sitting in a worker queue.
+4. Builds the order one slot at a time: the slice with the highest predicted
+   MLU takes the next slot and its bytes join `bytes_ahead` for the ones still
+   waiting, since the queue pair will post them in that order. Ties keep
+   arrival order. The first 64 slots are resolved exactly; the remainder is
+   ranked once against the bytes those slots accumulated. `submitSlices`
+   posts a prefix of the order, as long as the queue pair's remaining budget
+   (`max_qp_wr`, 256 by default, minus what is already outstanding), and the
+   rest wait for the next tick.
+
+Arbitration never drops, admits or moves a slice to another NIC; it only
+decides the order in which already-selected slices are posted.
+
+### Worked Example: Three Slices
+
+A NIC has 32 MiB posted and not yet completed, and its transmit estimate is
+400 Gb/s (50 GB/s). One worker is about to post three 16 MiB slices on it:
+
+| Slice | Deadline window remaining |
+|---|---|
+| A | 10 ms |
+| B | 2 ms |
+| C | none |
+
+First slot, `bytes_ahead` = 32 MiB. A and B each predict (32 + 16) MiB / 50
+GB/s ≈ 1.0 ms of transfer: A's MLU is 1.0 / 10 = 0.10, B's is 1.0 / 2 = 0.50,
+C's is 0. B takes the slot and its 16 MiB join `bytes_ahead`, now 48 MiB.
+
+Second slot: A now predicts (48 + 16) MiB / 50 GB/s ≈ 1.34 ms, MLU 0.134; C is
+still 0. A takes it. C posts last.
+
+Post order: B, A, C. In arrival order (A, B, C) B would have waited behind A's
+16 MiB, about 0.34 ms of its 2 ms window. The example also shows the two
+rules a reader should expect: a slice with no deadline never overtakes one
+with a deadline, and a slice's urgency rises as the slots ahead of it fill.
+
+## Comparison with Device Selection
+
+The earlier tables compared the two predictors' inputs and the two bandwidth
+series. This one compares the three mechanisms themselves: what each is for,
+where it runs, and what it can and cannot do.
+
+| | Device selection | Admission queue | RDMA arbitration |
+|---|---|---|---|
+| Question | which NIC | whether and when to dispatch | in what order to post on a NIC |
+| Runs | per slice, in the worker | per submit and per poll, in the engine | per post batch, in the worker |
+| Reads | selection EWMA, NUMA tier, inflight charge | transmit estimate (owner's transport), `dispatching_bytes_` | transmit estimate (this NIC), posted bytes |
+| Can | choose, split across NICs | reorder, promote, cancel | reorder within a tier |
+| Cannot | see deadlines | choose a NIC | drop or move a slice |
+| Switch | `enable_smart_scheduling` | `enable_runtime_queue` + `deadline_aware` (+ `mlu_local_threshold`) | `deadline_bw_arbitration` |
+
+Device selection is documented in [Slice Spraying](slice-spraying.md).
+
+## Configuration
+
+### Enabling the Queue
+
+```json
+{
+  "enable_runtime_queue": true
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enable_runtime_queue` | bool | `false` | Route non-staged submits through the admission queue. Everything under `runtime_queue/` is read only when this is on |
+
+### Admission Queue
+
+```json
+{
+  "runtime_queue": {
+    "max_outstanding_owners": 1024,
+    "max_outstanding_bytes": 1073741824,
+    "staging_owner_reserve": 0,
+    "staging_byte_reserve": 0,
+    "max_dispatch_owners": 64,
+    "max_dispatch_bytes": 67108864,
+    "deadline_aware": true,
+    "promotion_slack_ns": 0,
+    "mlu_local_threshold": 1.2,
+    "progress_fallback_interval_us": 50000
+  }
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_outstanding_owners` | int | `1024` | Owners admitted and not yet terminal, queued or dispatched |
+| `max_outstanding_bytes` | int | `1073741824` (1 GiB) | Same bound in bytes |
+| `staging_owner_reserve` | int | `0` | Owners held back from user submits so staging-internal work can always be admitted |
+| `staging_byte_reserve` | int | `0` | Same reserve in bytes |
+| `max_dispatch_owners` | int | `64` | Owners in flight at the transports at once |
+| `max_dispatch_bytes` | int | `67108864` (64 MiB) | Bytes in flight at the transports at once; a single request longer than this is rejected at submit |
+| `deadline_aware` | bool | `false` | Earliest-deadline-first dispatch; owners without a deadline keep FIFO order behind those with one. Required by promotion and drop |
+| `promotion_slack_ns` | int | `0` | Owners with less remaining slack than this move to the front of the queue. `0` disables promotion |
+| `mlu_local_threshold` | float | `0.0` | θ_local. Eligible owners whose predicted MLU reaches this value are canceled instead of dispatched. `0` disables the drop. Values below `1.0` cancel requests predicted to succeed |
+| `progress_fallback_interval_us` | int | `50000` | Timer on which the progress worker refills the dispatch window when no completion wake arrives. `0` disables the timer |
+
+### RDMA Arbitration and the Transmit Estimate
+
+```json
+{
+  "transports": {
+    "rdma": {
+      "deadline_bw_arbitration": true,
+      "transmit_bandwidth_learning_rate": 0.9,
+      "transmit_meter_interval_ns": 10000000,
+      "transmit_meter_max_interval_ns": 50000000
+    }
+  }
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `deadline_bw_arbitration` | bool | `false` | Order slices most-urgent-first before posting on a NIC |
+| `transmit_bandwidth_learning_rate` | float | `0.9` | α for the transmit estimate (`1.0` = never learn, `0.0` = always take the latest sample) |
+| `transmit_meter_interval_ns` | int | `10000000` (10 ms) | Minimum wall-clock span of one meter interval |
+| `transmit_meter_max_interval_ns` | int | `50000000` (50 ms) | An interval longer than this is discarded instead of learned from |
+
+The transmit estimate also inherits the clamp and seed shared with device
+selection: `ewma_min_bandwidth_multiplier`, `ewma_max_bandwidth_multiplier`,
+`default_bandwidth_gbps`, `min_bandwidth_gbps`, `max_bandwidth_gbps`. See the
+[Slice Spraying configuration](slice-spraying.md#configuration).
+
+### Request Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `deadline_ns` | uint64 | `0` | Absolute steady-clock time in nanoseconds by which the transfer should complete. `0` means no deadline |
+| `intent_type` | enum | `INTENT_UNSPEC` | What the transfer is for (foreground get, background prefetch, migration). Used by the transport selector's intent policies; not read by the scheduling described here |
+| `priority` | int | `PRIO_HIGH` | QoS tier. Arbitration reorders only within a tier |
+
+C++:
+
+```cpp
+Request req;
+req.opcode = Request::WRITE;
+req.source = local_buffer;
+req.target_id = remote_segment;
+req.target_offset = 0;
+req.length = 1 << 20;
+req.deadline_ns = now_ns() + 20'000'000;  // 20 ms from now, steady clock
+engine.submitTransfer(batch, {req});
+```
+
+Python:
+
+```python
+req = tent.Request(tent.OpCode.WRITE, src, target_id, 0, length,
+                   deadline_ns=now_ns + 20_000_000)
+```
+
+`now_ns` must come from the same steady clock the engine uses
+(`std::chrono::steady_clock` on the C++ side). A wall-clock timestamp is not
+comparable and will be read as a deadline far in the past or future.
+
+## Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `tent_deadline_mlu_permille` | Histogram | Measured MLU at completion, times 1000: submit-to-completion latency over the window the transfer had at submit. `1000` is the met/missed boundary. Recorded only for transfers that reached `COMPLETED` with a deadline still ahead at submit; this is the measured ratio, not the predictor's estimate |
+| `tent_deadline_infeasible_total` | Counter | Transfers whose deadline was already in the past at submit time. Kept separate from the histogram so they are not read as high-MLU samples |
+
+A dropped owner surfaces as a `CANCELED` task; it produces neither metric,
+because it never ran. See [Metrics](metrics.md) for labels and export.
+
+## Where Each Effect Is Observable
+
+Ordering and promotion are engine-level and apply on any transport. The drop
+acts on RDMA- or UB-routed, non-staged owners whenever a bandwidth provider is
+installed for their transport; the arbitration runs only in the RDMA workers, so
+it stays RDMA-only. On a host with TCP only, `deadline_aware` and
+`promotion_slack_ns` change dispatch order, while `mlu_local_threshold` and
+`deadline_bw_arbitration` do nothing. That is by design, not a
+misconfiguration.
+
+## Known Limits
+
+- **Drop notification.** The engine installs an empty `DegradationHooks`, and
+  there is no public API to register one, so a caller learns of a drop only by
+  observing `CANCELED`. The hook exists for an upper layer to trigger local
+  recompute.
+- **Threshold validation.** `mlu_local_threshold` below `1.0` is accepted and
+  cancels requests the predictor expects to succeed. Treat `1.0` as the floor.
+- **Mixed submits.** A submit that mixes staged and non-staged owners bypasses
+  the queue as a whole, so its RDMA owners do not enter `dispatching_bytes_`
+  and the drop predictor underestimates the queue ahead of later requests.
+- **Quarantined owners.** An owner that is dispatched and then never reaches
+  a terminal status (a batch abandoned by the lazy free path) keeps its bytes
+  in `dispatching_bytes_`, so the drop predictor grows more pessimistic over
+  time in that failure mode.
+- **RDMA completion wake.** RDMA does not yet signal the progress worker on
+  completion, so dispatch-window refill after an RDMA completion waits for the
+  fallback timer.
+- **Failover keeps the RDMA charge.** Eligibility is fixed at admission from
+  the planned route. A request that enters as RDMA, fails there and is
+  recovered over TCP keeps its bytes in `dispatching_bytes_` until it
+  completes, so the drop predictor is pessimistic by one transfer's length for
+  the duration of that recovery.
+- **One provider, one transport.** The only bandwidth provider is the RDMA
+  transport's, and `bytes_ahead` is a single sum, so only RDMA-routed,
+  non-staged requests can be predicted and dropped. Extending the drop to
+  another transport would need a provider per transport and a queue-ahead
+  term per transport, with each owner recording which one predicts it. The
+  structure allows this; nothing implements it.
+
+## References
+
+- RFC #2519: deadline-aware transfers (observe, order, degrade)
+- RFC #2792: deadline-aware NIC bandwidth arbitration
+- [TENT Slice Spraying](slice-spraying.md): device selection and the two bandwidth series
+- [TENT Quality of Service](qos.md): priority tiers the arbitration works within
+- [TENT Metrics](metrics.md)
diff --git a/docs/source/design/tent/failover.md b/docs/source/design/tent/failover.md
index 676b986a4b..c713674f45 100644
--- a/docs/source/design/tent/failover.md
+++ b/docs/source/design/tent/failover.md
@@ -1,3 +1,4 @@
+(tent-failover)=
 # TENT Failover
 
 TENT hides transfer failures from the application by recovering inside the data path.
@@ -89,6 +90,41 @@ Inside `RdmaTransport`, each completion drives the rail monitor:
 
 This produces two independent recovery signals — cooldown expiry and live success — so a flaky rail does not stall forever if no other rail is posted to, and a recovered rail returns to service at the first good completion instead of waiting for the full cooldown.
 
+### UB rail recovery
+
+UB rails have their own monitor, `RailMonitor`, keyed by the physical rail
+(`UbRailKey`: local topology id, remote segment id, remote device id) rather
+than by the endpoint incarnation, so health and learned bandwidth survive an
+endpoint rebuild. Posting paths read it the same way RDMA reads its rail state:
+
+* Bad completion → `recordError` / `recordTimeout`; good completion →
+  `recordSuccess`, which also feeds the EWMA used to rank paths.
+* `error_threshold` (3) errors inside `error_window_ns` (10 s) pause the rail
+  for `cooldown_ns`, which is bound to `transports/ub/endpoint_cooldown_ms`
+  (default 1000 ms).
+* Path selection skips paused rails and ranks the rest by quota availability,
+  topology locality and learned bandwidth *before* resolving endpoints, so a
+  paused or loaded rail is avoided without paying a bootstrap round trip.
+* `recordEndpointRebuild` records at most one rebuild per endpoint generation
+  per rail and is safe to call from converging or retried rebuild paths. The
+  first generation to become ready establishes the rail's baseline, so the
+  initial bootstrap is not counted as a rebuild; only later generation
+  increases advance `endpoint_rebuilds`.
+
+Local device failure is handled separately from rail health. A failed local
+device marks its context unavailable, and the transport then calls
+`EndpointStore::retireLocalDevice`, which unpublishes every endpoint backed by
+that device and quarantines any whose native cleanup has not completed. The
+context only returns to service once every one of them reaches `Destroyed`,
+because reactivating JFC health before that barrier would post onto Jetty sets
+that still lack their flush fence. Quarantined endpoints are retried only when
+the store actually needs a slot, and at most once per sweep interval, so a
+still-failing device cannot turn every posting call into a serialized provider
+call.
+
+When UB cannot resolve or post a slice, the generic submit-stage failover
+described above moves the owner to the remaining candidate transports.
+
 ## Configuration
 
 All knobs live in the top-level `transfer-engine.json`. Defaults are safe for production; tune only if you have evidence.
@@ -135,63 +171,29 @@ The counter is only built when TENT is compiled with `-DTENT_METRICS_ENABLED=ON`
 | `Rail recovered: local_nic=... remote_nic=... (cooldown expired)` | Cooldown elapsed and the rail is back in service. |
 | `Rail recovered: ... (un-paused by successful transfer)` | Live success on a previously paused rail brought it back early. |
 
+(tent-failover-testing)=
 ## Testing
 
-Real hardware faults are hard to stage, so TENT tests the failover machinery with decorator-style fault injection.
-
-### FaultProxyTransport
-
-`FaultProxyTransport` wraps any `Transport` and injects four policy-driven faults:
-
-* `submit_fail_rate` — probability that `submitTransferTasks` returns an error.
-* `status_corrupt_rate` — probability that `getTransferStatus` flips `COMPLETED → FAILED`.
-* `fail_after_n_submits` — deterministic variant: succeed the first N submits, then always fail.
-* `fail_install` — make `install()` fail, simulating a transport that cannot come up.
-
-Because it implements the `Transport` interface, the engine sees an ordinary transport. All failover paths (`submitTransfer`, `getTransferStatus`, `resubmitTransferTask`) run unmodified.
-
-### Test-only injection hook
-
-`TransferEngineImpl::swapTransportForTest` replaces the transport in one slot after `construct()`. This is the only way the end-to-end test can wrap the real transport with `FaultProxyTransport` without bypassing `resolveTransport` or `resubmitTransferTask`. Production code never calls it.
-
-### End-to-end suite
+Real hardware faults are hard to stage, so failover is tested by driving the real `TransferEngineImpl` with FakeTransport backends and a fault-injecting decorator. The engine is unmodified: a completion-stage `FAILED` looks like a WC error or a dropped peer, and `resubmitTransferTask` runs as it would in production.
 
-The end-to-end failover test suite drives the real `TransferEngineImpl` with fake transports (`FakeTransport`) wrapped in `FaultProxyTransport`. It uses a `p2p` metadata backend on `127.0.0.1` so no external services are required — the whole suite is self-contained.
-
-Current cases:
-
-| Test | What it exercises |
-|------|-------------------|
-| `StatusCorruptionTriggersFailoverToSecondary` | Primary reports `FAILED` in `getTransferStatus`; engine must resubmit on the secondary. |
-| `BothTransportsFailExhaustsFailoverBudget` | Both transports fail at the completion stage; task must surface `FAILED` once the budget is drained. |
-| `MixedFaultsAcrossManySubmissions` | 10 one-request batches with 30% completion corruption on RDMA; every task must end `COMPLETED`, and submit-counter math must hold. |
-| `MaxFailoverAttemptsZeroDisablesFailover` | `max_failover_attempts = 0` → the first completion fault is permanent, TCP is never touched. |
-| `MaxFailoverAttemptsOneAllowsSingleFailover` | `max_failover_attempts = 1` → one switch allowed; RDMA fault → TCP success. |
-| `PerTaskFailoverCountsAreIndependent` | A failing task must not consume another task's budget; `failover_count` is strictly per-task. |
-
-A test-local `PerRequestFaultProxy` (in the same file) subclasses `FaultProxyTransport` to take a `std::function` predicate, remembers which sub-task ids it marked as "poisoned" at submit time, and flips only those completions from `COMPLETED` to `FAILED` at status-query time.
-
-### Running manually
-
-The TENT tests are **not** in CI today (the upstream workflow builds with `USE_TENT=OFF`). Run them locally:
-
-```bash
-cmake -S . -B build-tent -DUSE_TENT=ON -DUSE_CUDA=OFF
-cmake --build build-tent --target tent_failover_test tent_engine_failover_e2e_test -j
-./build-tent/mooncake-transfer-engine/tent/tests/tent_failover_test
-./build-tent/mooncake-transfer-engine/tent/tests/tent_engine_failover_e2e_test
-```
+The harness — why a fake `Transport` is enough, how fakes are swapped in, and what this can and cannot prove — is in {ref}`TENT Testing <tent-testing>`. That page is the mechanism; this section only notes what failover uses it for:
 
-Setting `USE_CUDA=OFF` forces `CpuPlatform`, which always reports `MTYPE_CPU`. With `USE_CUDA=ON` on a host without a GPU, `cudaPointerGetAttributes` fails, `getMemoryType` returns `MTYPE_UNKNOWN`, every transport reports unavailable, and `resolveTransport` returns `UNSPEC` before the fault injection ever runs.
+* Completion-stage `FAILED` on the primary must resubmit on the next available transport.
+* Submit-stage failure: a synchronous non-OK from `submitTransferTasks` must fail the owner task over to the remaining candidates (bounded by `max_failover_attempts`) instead of terminal-failing it.
+* Derived (merged) alias tasks must follow their owner's recovered route and must not cause a duplicate physical submission.
+* Exhausting `max_failover_attempts` (including `0` and `1`) must surface `FAILED` and must not touch a transport beyond the budget.
+* `failover_count` is per-task: one failing request must not spend another request's budget.
+* With `enable_auto_failover_on_poll=false`, status polling is observational; `progressBatch` / `waitTransferCompletion` / `transferSync` still recover.
 
-Companion unit tests cover the rail monitor and related building blocks: `tent_rail_monitor_test`, `tent_failover_test`, `tent_fault_proxy_test`.
+Submit-stage recovery is exercised through the same FakeTransport harness with `force_submit_fail` backends (see `SubmitStageFailureFailsOverToSecondary` and friends in `engine_failover_e2e_test.cpp`).
 
 ## Known Gaps
 
-* **Submit-stage failures do not trigger failover.** When `submitTransferTasks` returns non-OK, every task in that call is marked `UNSPEC` and surfaces as `FAILED`. A naive retry loop here is unsafe for two reasons:
-  1. **Merged requests.** When `merge_requests` is enabled (default), `task_id_list[type]` contains both the real merged task and its derived aliases. Resubmitting per task-id re-posts one logical transfer multiple times on the fallback transport, breaking the deduplication the merge pass established.
-  2. **Partial enqueue.** Some transports (for example `ShmTransport::submitTransferTasks`, `NVLinkTransport::submitTransferTasks`) enqueue or start work for earlier requests in `request_list` before returning an error on a later one. The return status alone does not tell us which tasks partially succeeded, so a blanket resubmit would duplicate already-started transfers.
-  A safe submit-stage recovery needs either (a) a transport-level "atomic submit" capability flag plus per-task skip of derived ids, or (b) per-request status returned from `submitTransferTasks`. Neither exists today.
+* **Submit-stage failure recovery is implemented** (previously a gap): a synchronous non-OK from `submitTransferTasks` fails the owner tasks over to the remaining candidate transports (bounded by `max_failover_attempts`), reusing `resubmitTransferTask`. The two hazards that originally made a naive retry unsafe are handled as follows:
+  1. **Merged requests.** Only the owner task of each merged request is resubmitted; derived aliases mirror the owner's recovered route (transport, sub-batch slot, status) instead of being resubmitted themselves, preserving the merge pass's deduplication.
+  2. **Partial enqueue.** `NVLinkTransport::submitTransferTasks` rolls back its half-appended task entries on synchronous failure (no I/O has started at that point). Transports that start per-request work inside the submit loop (e.g. `ShmTransport`, whose copies are synchronous and idempotent) may still cause a duplicate same-content transfer on the fallback; re-posting an identical request is a data-level no-op for KV-cache-style workloads.
+  A failover target whose own synchronous submit also fails is retried within the same budget; a task that exhausts all candidates surfaces `FAILED` attributed to the last attempted transport (never `unspec`).
 * `markRecovered` (and cooldown expiry in `available`) clears the exponential-backoff memory entirely. A rail that flaps repeatedly therefore does not accumulate a growing cooldown across recovery cycles. If this becomes a problem the fix is to decay rather than reset.
 * Cross-transport failover is driven purely by return status; there is no latency-based "this transport is healthy but too slow, try another" signal. That belongs to the scheduler, not this document.
-* TENT tests are not exercised by CI. A follow-up can add a CI job that builds with `-DUSE_TENT=ON -DUSE_CUDA=OFF` and runs the `tent_*` test targets; none of the code in this document changes in that case.
+* Runtime-layer failover is covered by FakeTransport tests in the `tent-ci` `cuda-off` legs. DMA integrity, real WC errors, and staging under NVLink still need hardware runners; see {ref}`TENT Testing <tent-testing>`.
+* UB rail health, endpoint-rebuild telemetry and device-failure cleanup are covered by fake-URMA-adapter tests (`tent_ub_core_test`, `tent_ub_teardown_test`, `tent_ub_native_data_path_test`, `tent_rail_monitor_test`). Real provider errors, bonding-device failover and the bootstrap fan-out of a cold multi-rail peer still need Kunpeng/URMA hardware runners.
diff --git a/docs/source/design/tent/hp-tcp.md b/docs/source/design/tent/hp-tcp.md
new file mode 100644
index 0000000000..cd9558579a
--- /dev/null
+++ b/docs/source/design/tent/hp-tcp.md
@@ -0,0 +1,287 @@
+# TENT High-Performance TCP
+
+`hp_tcp` is a standalone TENT transport for CPU DRAM transfers over
+data-center TCP. Standard `tcp` remains the RPC-based compatibility path.
+The first version intentionally excludes GPU memory, TLS, WRITE striping, rail
+failover, transparent replay after an ambiguous WRITE and dynamic lane
+scheduling.
+
+## Architecture
+
+Each worker owns one `asio::io_context` and one thread. Each peer has a
+configured number of persistent lanes. A separate sequence for each peer
+rotates operations across them, so interleaved traffic to other peers cannot
+pin a peer to one lane. Each sequence starts at that peer's first request ID
+to preserve its initial lane choice. Request IDs remain globally unique.
+A stable hash of peer and lane selects the owner; socket state
+never moves between workers, and operations on a lane are FIFO. ASIO provides
+the event queue; process-wide task and byte admission limits bound all accepted
+work, including callbacks waiting in that queue.
+
+Both ends disable Nagle's algorithm: headers and payloads use separate writes,
+so a delayed ACK must not hold up a short payload on a persistent socket.
+
+The server uses the same worker pool. Accepted sockets are assigned to workers
+and stored in worker-owned session sets. A global connection limit bounds live
+sessions; closing a session removes it immediately rather than retaining one
+thread per historical connection.
+
+```text
+TENT request -> bounded admission -> owner worker -> persistent lane
+             -> versioned TCP protocol -> registered remote buffer
+```
+
+### Static multi-rail routing
+
+`rail_addresses` optionally assigns persistent lanes across an ordered set of
+local and remote TCP addresses. Each entry must be a numeric address assigned
+to the local host. The current implementation accepts IPv4 addresses only.
+When the list is non-empty it supplies the published
+endpoints instead of `advertise_address`. Lane `i` uses rail
+`i % rail_count`, binds its socket to the matching local address, and keeps the
+existing peer-and-lane worker ownership. Both peers must configure the same
+non-zero rail count. A specific listener address must match the sole rail;
+multiple local rails require a wildcard listener.
+
+Routing is deliberately static. Small transfers and all WRITEs stay on one
+persistent lane. A READ large enough to contribute at least one internal I/O
+step per configured rail is split into one contiguous slice per rail. The
+slices reuse the persistent lanes and complete as one TENT task. `hp_tcp` does
+not rebalance traffic or fail over between rails.
+
+The current internal step is 1 MiB: with two rails, READs of at least 2 MiB
+are sliced; smaller READs and single-rail READs are not. Remainder bytes are
+assigned to the first slices, so uneven lengths still cover the request
+exactly. Multiple independent WRITEs can use different rails, but each WRITE
+stays on one lane and waits for its own remote completion ACK.
+
+`connections_per_peer` is the **total** lane budget, not a per-rail multiplier.
+For example, four lanes and two rails give two lanes per rail. Worker count is
+independent of rail count: several lanes may share an owner worker. Increasing
+lanes on a single rail does not split a single READ into multiple streams.
+
+## Protocol and memory safety
+
+Requests contain a version, opcode, request ID, registration ID, remote
+address and length. Responses contain the request ID, status and committed
+byte count. A WRITE completes only after the target has copied the full payload
+and returned an acknowledgement. A READ completes after the full response
+payload arrives.
+
+Every registered buffer has an ID formed from a per-registry random namespace
+and a monotonic sequence, plus a remote permission. This prevents a stale ID
+from a previous server incarnation from becoming valid after restart. The
+target validates the ID, range and permission before access. An operation holds
+a lease until its final I/O callback retires; unregister hides the range from
+new work and waits for existing leases. Stale registration metadata causes one
+bounded metadata refresh and retry on the same transport. Permission and range
+failures are terminal.
+
+If a WRITE request may have reached the peer but no valid acknowledgement is
+received, the remote outcome is unknown. That failure is terminal and is not
+replayed through another transport; otherwise a committed WRITE whose ACK was
+lost could execute twice.
+
+## Timeouts and shutdown
+
+Resolve/connect use `connect_timeout_ms`. Header, payload and response progress
+use `progress_timeout_ms` on both client and server. A newly accepted connection
+must send its first header byte before the deadline, and every partial header
+or payload must continue to make progress. After a valid request completes,
+pure idle time on its persistent connection is not treated as stalled I/O; the
+deadline resumes as soon as the next header begins. A timeout cancels the
+resolver or socket; terminal completion is published only after the
+corresponding callback retires.
+
+A failed READ slice cancels its siblings; the logical task settles only after
+all slice callbacks retire. A stale-registration result can trigger the
+existing bounded metadata refresh/retry, not migration onto another rail.
+Independent peers can continue while a peer is waiting for its progress
+timeout. FIFO sharing within one peer's lanes can still delay small requests
+behind large ones; slicing is not a priority or preemption mechanism.
+
+The client separately closes a pooled socket after
+`idle_connection_timeout_ms` without active or queued work on that lane
+(default 60 seconds). New work before expiry cancels this timer and reuses the
+socket; work after expiry reconnects. This releases receiver connection slots
+held by idle updated clients. The server does not evict established idle sockets:
+it cannot know whether a client has just started another WRITE. Older clients
+that keep sockets open indefinitely still require their own pool cleanup.
+Tasks attempted while the receiver connection limit is full can still fail;
+idle cleanup is not task backpressure or an automatic retry policy.
+
+Shutdown closes admission and the listener, drains queued dispatch callbacks,
+cancels every client lane and server session on its owner, waits for operations
+and leases, then stops and joins worker threads. This makes shutdown bounded
+even when a peer sends only part of a request.
+
+This ordering is a lifecycle invariant, not an incidental destructor detail:
+the client and server are destroyed before the worker contexts they use. In a
+debug build, normal teardown asserts that admission, client operations and
+server sessions have all drained before their owners are destroyed.
+
+An exception escaping an ASIO handler marks the runtime failed and blocks
+further admission. The owner event loop continues only to retire previously
+committed work and process teardown cancellation with the same affinity. Once
+those resources drain, shutdown joins the workers and reports the failure.
+Likewise, admission-release underflow is fail-closed: counters are preserved,
+new work is rejected, and drain returns an error instead of treating live work
+as complete.
+
+## Configuration
+
+The transport is configured under `transports.hp_tcp`:
+
+| Field | Meaning |
+| --- | --- |
+| `enable` | Enable `hp_tcp`; set `transports.tcp.enable` to `false`. The two transports cannot be enabled together because control-plane notification ownership is singular. |
+| `bind_address`, `advertise_address`, `port` | Listener and published endpoint. |
+| `rail_addresses` | Ordered numeric IPv4 source addresses for static lane-to-rail routing. The list must be unique, no longer than `connections_per_peer`, and have the same length on both peers. A non-wildcard `bind_address` must equal the sole rail address; multiple rails require it to be empty or `0.0.0.0`. |
+| `worker_count` | ASIO event-loop threads. |
+| `connections_per_peer` | Persistent lanes per peer. |
+| `max_outstanding_tasks`, `max_outstanding_bytes` | Global admission bounds. |
+| `max_transfer_bytes` | Maximum request size. When HP TCP is enabled, coalescing of HP TCP/UNSPEC requests respects both local and advertised remote limits; an individually oversized request is still rejected. |
+| `connect_timeout_ms`, `progress_timeout_ms` | Connection and I/O deadlines. |
+| `idle_connection_timeout_ms` | Positive client idle-pool retention time; default 60000 ms. Active or queued requests are never expired by this timer. Shorter retention frees receiver slots sooner but requires more reconnections for intermittent traffic. |
+
+### Single-rail and paired-rail examples
+
+For a single rail, put this in the server's `MC_TENT_CONF` JSON file (replace
+the example address with an address assigned to the host):
+
+```json
+{
+  "transports": {
+    "tcp": {"enable": false},
+    "rdma": {"enable": false},
+    "shm": {"enable": false},
+    "hp_tcp": {
+      "enable": true,
+      "bind_address": "",
+      "rail_addresses": ["10.0.0.2"],
+      "worker_count": 4,
+      "connections_per_peer": 4
+    }
+  }
+}
+```
+
+Use the same configuration on the client with its local address `10.0.0.1`.
+For two rails, change only the lists:
+
+| Host | `rail_addresses` |
+| --- | --- |
+| Client | `["10.0.0.1", "10.1.0.1"]` |
+| Server | `["10.0.0.2", "10.1.0.2"]` |
+
+Entries pair by index, and both hosts need working source-address routes for
+those pairs. Reused sockets retain that mapping; failed sockets are closed
+before later requests reconnect.
+
+`MC_TENT_CONF` loads a complete configuration, so include the transport enable
+flags even when using tebench's `--xport_type=hp_tcp`. To check data with the
+existing benchmark, start its target, then run an initiator with its advertised
+segment name:
+
+```bash
+MC_TENT_CONF=client.json tebench --backend=tent --xport_type=hp_tcp \
+  --tent_transport_hint=hp_tcp --target_seg_name=SERVER_SEGMENT \
+  --seg_type=DRAM --op_type=mix --check_consistency=true \
+  --start_block_size=67108864 --max_block_size=67108864 --duration=3
+```
+
+Repeat with both block-size flags set to `4096` for the unsliced path.
+With `--xport_type=hp_tcp --check_consistency=true`, the CPU checker uses
+seed-reproducible, non-constant data and a full byte comparison to detect
+reordered slices. Run throughput separately without this checking overhead.
+Ordinary `mix`, other backends and `write_seed`/`read_verify` retain their
+existing data patterns.
+
+### Checking rail use
+
+Test-local socket relays record the peer/local addresses and completed slice
+ranges. Full-engine tests check payloads, guards, the slicing threshold and
+connection reuse; two-process E2Es also cover unequal transfer-size limits.
+
+On two machines, inspect connections with `ss -tnp`, source-address routes with
+`ip route get REMOTE from LOCAL`, and per-interface byte counters before/after
+a transfer. READ payload moves from server TX to client RX. Compare both
+rails' deltas with successful application bytes; account for protocol overhead
+and unrelated traffic. Two open connections alone do not prove payload use.
+
+Loopback proves routing, not physical NIC use. Check PCI devices and shared
+host/fabric limits. Compare one rail/one lane, one rail/multiple lanes, and two
+rails/the same total lanes: the last two differ in single-READ slicing as well
+as rail placement.
+
+### Tuning concurrent READs
+
+For one peer with `C` outstanding large READs and `R` rails, at most
+`min(connections_per_peer, C * R)` payload streams can be active. This assumes
+the READs are large enough to slice across all rails. Four outstanding READs
+with four total lanes therefore have the same four-stream upper bound with
+one or two rails; adding a rail alone does not increase that bound.
+
+With four rails and four total lanes, each rail has one connection. Eight
+lanes provide two per rail. Each lane processes one operation at a time;
+once those four lanes already have distinct owners, adding workers alone
+cannot increase the number of active lane owners. Compare lane and worker counts separately, recording the counts
+at both endpoints, throughput, tail latency and CPU use. Additional lanes
+sharing the same workers need not increase throughput.
+
+Keep CPU and memory placement fixed during these comparisons; record the
+NICs' NUMA nodes. Use per-thread CPU measurements because Store and tebench
+callers also consume CPU polling for completion. A stream-count upper bound
+does not predict throughput or establish a universal rail/worker default.
+
+### Measured scope
+
+On two Xeon 8457C virtual machines, with four workers and four total lanes,
+three interleaved runs (1-second warmup, 3-second measurement) gave the
+following medians:
+
+| READ workload | Metric | One rail | Two rails |
+| --- | --- | ---: | ---: |
+| 64 MiB, one concurrent task | Throughput (GB/s) | 3.22 | 6.46 |
+| 64 MiB, four concurrent tasks | Throughput (GB/s) | 11.13 | 10.96 |
+| 4 KiB, one concurrent task | Mean latency (microseconds) | 72 | 78 |
+
+Both interfaces carried payload-direction traffic, but their underlying
+resource independence is not guaranteed. In that four-lane/four-worker setup,
+four concurrent READs showed no additional gain. A same-pool 4 KiB/64 MiB
+closed-loop mix still delayed small
+tasks behind large ones: static slicing offers neither latency isolation nor
+universal bandwidth scaling.
+
+A Store `get_into` comparison on two H20 hosts used the unchanged `202ad9c89`
+Release build, 8 MiB host-memory objects and four closed-loop callers (one
+outstanding READ each). Both endpoints used the worker/lane counts below,
+CPU 0-89 and new allocations bound to NUMA node 0. Two rails used eth1/2
+on node 0; four rails also used eth3/4 on node 1. There were three 30-second
+runs per configuration after a 2-second warmup. Each pair of configurations
+was interleaved; the three pairs ran sequentially.
+
+| Rails | Workers / total lanes | Median GB/s [min, max] | Client CPU (core equivalents) |
+| ---: | ---: | ---: | ---: |
+| 2 | 4 / 4 | 10.371 [9.664, 10.747] | 6.84 |
+| 2 | 8 / 8 | 8.022 [7.904, 8.159] | 5.40 |
+| 4 | 4 / 4 | 7.599 [7.440, 7.877] | 6.86 |
+| 4 | 4 / 8 | 8.537 [8.139, 8.624] | 6.93 |
+| 4 | 8 / 4 | 7.339 [7.260, 7.790] | 6.83 |
+| 4 | 8 / 8 | 11.487 [11.343, 11.551] | 7.76 |
+
+For four rails, increasing both counts improved throughput by 51.2% over
+four/four, with client CPU rising from 6.86 to 7.76 cores. Increasing workers
+alone did not help; increasing lanes alone helped less. The four-rail 8/8
+configuration was 10.8% faster than the best measured two-rail configuration
+(4/4), with 13.5% more client CPU. Server-process CPU samples also rose
+from about 2.24 to 3.35 core equivalents. Two rails regressed with 8/8, so
+these results do not justify raising defaults.
+
+Before each of the 18 timing runs, all 32 objects passed bytewise checks.
+Every run used the configured 4 or 8 connections, and per-rail payload byte
+totals matched the static split. Separate stack samples confirmed
+four active receive workers in the four-lane case and were excluded from
+timing results. The experiment changes both endpoints' worker counts; it
+does not isolate client versus server costs or remove NUMA effects. It covers
+Store host-memory READs, not GPU transfers or model-level performance.
diff --git a/docs/source/design/tent/metrics.md b/docs/source/design/tent/metrics.md
index 65055fd74a..1dbe92f28a 100644
--- a/docs/source/design/tent/metrics.md
+++ b/docs/source/design/tent/metrics.md
@@ -258,7 +258,7 @@ enum closed set — no arbitrary transport strings are accepted.
 
 | Label | Values | Description |
 |-------|--------|-------------|
-| `transport` | `unspec`, `rdma`, `mnnvl`, `shm`, `nvlink`, `gds`, `io_uring`, `tcp`, `ascend`, `sunrise_link`, `tpu` | The transport that handled the transfer |
+| `transport` | `unspec`, `rdma`, `mnnvl`, `shm`, `nvlink`, `gds`, `io_uring`, `tcp`, `ascend`, `sunrise_link`, `tpu`, `ub`, `mpcomm`, `hp_tcp`, `xpu` | The transport that handled the transfer |
 | `operation` | `read`, `write` | Attempt operation |
 | `from` | (same set) | Transport that failed before failover |
 | `to` | (same set) | Transport that the failover switched to |
@@ -266,11 +266,25 @@ enum closed set — no arbitrary transport strings are accepted.
 Transport label values come from the shared `transportTypeName()` mapping.
 `unspec` covers transfers that failed before a transport was selected.
 
-**Cardinality**: the `transport` label has 11 values; the failover
-`from`/`to` pair has at most 11x11 = 121 combinations (in practice only a
-few pairs ever occur), and each attempt metric has at most 11x2 = 22
+**Cardinality**: the `transport` label has 15 values; the failover
+`from`/`to` pair has at most 15x15 = 225 combinations (in practice only a
+few pairs ever occur), and each attempt metric has at most 15x2 = 30
 transport/operation combinations. Total series across all metrics is bounded
-at ~1500.
+by this closed set.
+
+### Per-rail load (`getNicLoadStats`)
+
+`TransferEngine::getNicLoadStats()` returns one `NicLoadStats` entry per usable
+rail — `device_name`, `inflight_bytes` and `ewma_bandwidth_bps`. RDMA and UB
+both implement it: RDMA reports one entry per local NIC, UB reports one entry
+per UB device under the same `ub:<name>:<eid>` topology name used in logs and
+metrics. A rail whose context failed to construct, or whose port is down, is
+omitted rather than listed with a meaningless bandwidth.
+
+These are pull-based snapshots, not Prometheus series: UB rail health
+(pauses, errors in window, timeouts, endpoint rebuilds) lives in `RailMonitor`
+and is read through the transport rather than scraped. See {ref}`TENT Failover
+<tent-failover>` for how those counters drive rail selection.
 
 ## Integration with TransferEngine
 
diff --git a/docs/source/design/tent/overview.md b/docs/source/design/tent/overview.md
index 9559622614..6b37df87e7 100644
--- a/docs/source/design/tent/overview.md
+++ b/docs/source/design/tent/overview.md
@@ -93,6 +93,14 @@ metrics
 transport-selector
 :::
 
+## TENT High-Performance TCP
+
+:::{toctree}
+:maxdepth: 1
+
+hp-tcp
+:::
+
 ## TENT Quality of Service
 
 :::{toctree}
@@ -109,6 +117,14 @@ qos
 slice-spraying
 :::
 
+## TENT Deadline Scheduling
+
+:::{toctree}
+:maxdepth: 1
+
+deadline-scheduling
+:::
+
 ## TENT Failover
 
 :::{toctree}
@@ -116,3 +132,11 @@ slice-spraying
 
 failover
 :::
+
+## TENT Testing
+
+:::{toctree}
+:maxdepth: 1
+
+testing
+:::
diff --git a/docs/source/design/tent/slice-spraying.md b/docs/source/design/tent/slice-spraying.md
index 09355e6f19..c139f686fe 100644
--- a/docs/source/design/tent/slice-spraying.md
+++ b/docs/source/design/tent/slice-spraying.md
@@ -81,7 +81,7 @@ The penalty is applied as a multiplier to predicted completion time, making remo
 
 ### EWMA Bandwidth Estimation
 
-Each device maintains an EWMA (Exponentially Weighted Moving Average) of its effective bandwidth:
+Each device maintains a **selection EWMA** (Exponentially Weighted Moving Average) of its effective bandwidth, the series that device selection scores with:
 
 ```
 initial_value = theoretical_bandwidth
@@ -110,6 +110,69 @@ The EWMA provides:
 - **Stability**: Smooths out transient fluctuations
 - **Adaptability**: Tracks gradual changes in link quality
 
+#### Transmit Estimate
+
+Each device also keeps a second series, the **transmit estimate**, for the
+deadline predictors (described end to end in
+[Deadline Scheduling](deadline-scheduling.md)): the admission queue's
+deadline-infeasible drop (`runtime_queue/mlu_local_threshold`, reads the
+transmit estimate of the transport that will carry the owner) and the RDMA
+workers' bandwidth arbitration (`transports/rdma/deadline_bw_arbitration`,
+reads the local NIC's value). Both compute the same predicted MLU from it:
+
+```
+predicted_mlu = ((bytes_ahead + length) / transmit_bandwidth) / remaining_window
+```
+
+`bytes_ahead` is what the request must wait behind before its own bytes move:
+for the admission queue, every drop-eligible owner (RDMA or UB, not staged)
+already dispatched and not yet completed — owners on other transports share the
+queue but not the NIC, and the rate used for the prediction is the one the
+owner's own transport reports. For the arbitration it is the NIC's **posted
+bytes**: what has reached the hardware and not yet completed. That is
+deliberately not the selector's `inflight_bytes`, which is charged when a slice
+is *allocated* and so would include the very slices being ordered as well as
+work still sitting in a worker queue. The order is then built one slot at a
+time — the slice that takes a slot joins `bytes_ahead` for the ones still
+waiting, since the QP posts them in that order (exactly for the first 64 slots;
+the rest are ranked once against the bytes those slots accumulated).
+
+The deadline is absolute, so that wait counts against the window — as an
+additive delay over the wire rate, not as a slower bandwidth (which would
+multiply the wait by the request's slice count).
+
+It uses the same update rule and clamp as the selection EWMA, but it is fed
+from a different measurement because it answers a different question:
+
+| | Selection EWMA | Transmit estimate |
+|---|---|---|
+| Question | Which NIC should the next slice go to? | How fast does this NIC move bytes? |
+| Sample | one successful completion: bytes / (post → completion), so the NIC's own queueing behind earlier work requests is included and a backed-up NIC scores worse | one meter interval: bytes completed / time the NIC spent with work posted |
+| α | `bandwidth_learning_rate` = 0.01 (~99% latest sample) | `transmit_bandwidth_learning_rate` = 0.9 (~10 intervals, ≈100 ms, to follow a change) |
+
+Per-completion timing cannot answer the second question. Up to `max_qp_wr`
+work requests are posted in one call with timestamps that are effectively
+one, and a poll pass timestamps every completion it collects alike, so a
+slice's own "post → completion" grows with the depth of the batch it
+travelled in — deep enough and the estimate would sit on its lower clamp on
+a healthy link. Bytes over the NIC's busy time does not care how the work was
+batched.
+
+Busy time is the time the device has had at least one work request posted:
+a stretch opens when its posted bytes go from zero to non-zero and closes
+when they return to zero, so the gaps of a workload that bursts and waits are
+not charged to the link. A sample is offered only at the last completion of a
+poll pass (every completion in a pass carries the same timestamp), and one
+that spans more than `transmit_meter_max_interval_ns` of wall clock is
+dropped rather than learned from: it describes a link too far in the past. A
+posted slice that ends without moving its bytes — failed, flushed, timed
+out — makes its stretch unusable, so the meter starts its next interval
+fresh. With no usable interval the estimate keeps its last value, or the
+link-speed seed — the optimistic direction, which cannot cause a false drop.
+
+With queueing carried by `bytes_ahead`, the rate itself must exclude
+queueing or the wait would be counted twice.
+
 ### Multi-Path Allocation
 
 For large transfers, TENT distributes slices across multiple devices:
@@ -188,7 +251,8 @@ All slice spraying parameters are configurable via the configuration file:
 {
   "transports": {
     "rdma": {
-      "numa_penalties": [1.0, 5.0, 10.0]
+      "numa_penalties": [1.0, 5.0, 10.0],
+      "strict_local_numa": false
     }
   }
 }
@@ -197,12 +261,44 @@ All slice spraying parameters are configurable via the configuration file:
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `numa_penalties` | array[float] | `[1.0, 5.0, 10.0]` | Penalty multipliers for each NUMA tier |
+| `strict_local_numa` | bool | `false` | Never select a cross-NUMA NIC instead of penalizing it |
 
 **Guidelines**:
 - Higher values = stronger preference for local devices
 - Set all to `1.0` to disable NUMA awareness
 - Increase remote penalties if cross-NUMA latency is high
 
+### Strict Local NUMA
+
+`numa_penalties` makes a remote NIC expensive but still selectable, so a busy
+local NIC eventually loses to a cross-NUMA one. Set `strict_local_numa` (or the
+`MC_STRICT_LOCAL_NUMA` environment variable, which accepts `1`/`0` and
+`true`/`false`) to remove those NICs from selection entirely.
+
+A NIC is only excluded when the memory location and the NIC **both** report a
+NUMA node and the nodes differ. If either side is unknown the NIC keeps its
+`numa_penalties` weight, because discovery reports `-1` in cases where excluding
+everything would break otherwise working hosts:
+
+- virtual machines and some GPUs, where sysfs exposes no `numa_node`
+- bonded NICs such as `mlx5_bond_0`
+- classic priority-matrix topologies (`MC_CUSTOM_TOPO_JSON`,
+  `topology/priority_matrix`), which carry no NUMA information at all
+
+On those hosts the flag has no effect; a warning is logged at startup so this is
+visible rather than silent. A second warning names any location left without a
+same-NUMA NIC, since transfers from it will fail with `DeviceNotFound`.
+
+**Trade-off**: strict mode converts a performance problem into an availability
+one. Without a local NIC an allocation fails instead of degrading, so enable it
+only where every memory location provably has a same-NUMA rail.
+
+**Scope**: the exclusion is enforced on the local NIC for both the first
+selection and the retry path. For the remote NIC it is only a preference — the
+peer publishes its own topology and may not run this policy, so failing a slice
+because another host has no local rail would turn a local setting into a
+cross-node outage.
+
 ### Bandwidth Estimation
 
 ```json
@@ -210,6 +306,9 @@ All slice spraying parameters are configurable via the configuration file:
   "transports": {
     "rdma": {
       "bandwidth_learning_rate": 0.01,
+      "transmit_bandwidth_learning_rate": 0.9,
+      "transmit_meter_interval_ns": 10000000,
+      "transmit_meter_max_interval_ns": 50000000,
       "ewma_min_bandwidth_multiplier": 0.1,
       "ewma_max_bandwidth_multiplier": 10.0
     }
@@ -219,15 +318,20 @@ All slice spraying parameters are configurable via the configuration file:
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `bandwidth_learning_rate` | float | `0.01` | EWMA learning rate (0.0 = full adaptation, 1.0 = no learning) |
+| `bandwidth_learning_rate` | float | `0.01` | Selection EWMA learning rate (0.0 = full adaptation, 1.0 = no learning) |
+| `transmit_bandwidth_learning_rate` | float | `0.9` | Transmit estimate learning rate, same convention; read by the deadline predictors |
+| `transmit_meter_interval_ns` | uint | `10000000` | How often a device's throughput is sampled (10 ms) |
+| `transmit_meter_max_interval_ns` | uint | `50000000` | An interval longer than this is re-baselined instead of learned from |
 | `ewma_min_bandwidth_multiplier` | float | `0.1` | Minimum bandwidth as fraction of theoretical |
 | `ewma_max_bandwidth_multiplier` | float | `10.0` | Maximum bandwidth as fraction of theoretical |
 
 **Guidelines**:
 - Lower α (e.g., 0.001) → faster adaptation, more volatile → responds quickly to changes
 - Higher α (e.g., 0.1) → slower adaptation, more stable → smooths out transient fluctuations
-- Default α = 0.01 provides balanced adaptation
-- Multipliers constrain EWMA to reasonable range [0.1×, 10.0×] of theoretical bandwidth
+- Default α = 0.01 provides balanced adaptation for device selection
+- Keep `transmit_bandwidth_learning_rate` high: it backs an irreversible
+  drop decision, so it should follow sustained change, not single samples
+- Multipliers constrain both series to [0.1×, 10.0×] of theoretical bandwidth
 
 ### Device Selection Scoring
 
@@ -263,14 +367,39 @@ All slice spraying parameters are configurable via the configuration file:
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `default_bandwidth_gbps` | float | `400.0` | Default NIC bandwidth when topology info unavailable |
+| `default_bandwidth_gbps` | float | `400.0` | NIC bandwidth assumed when the port speed is unknown or out of range |
 | `min_bandwidth_gbps` | float | `10.0` | Minimum valid NIC bandwidth (Gbps) |
 | `max_bandwidth_gbps` | float | `800.0` | Maximum valid NIC bandwidth (Gbps) |
 
 **Notes**:
-- These constants define the valid range and default for device bandwidth
-- Used in EWMA calculations and theoretical bandwidth estimation
-- If a device's reported bandwidth is outside [min, max], default_bandwidth is used
+- Each device's bandwidth is read from the speed and width its port
+  negotiated (`ibv_query_port`), so a 100G and a 400G NIC in the same host
+  start from different theoretical rates. Where libibverbs provides
+  `ibv_query_port_speed()` (rdma-core >= 62) the *effective* speed it
+  reports is preferred: for a VF over LAG that is the bandwidth left after
+  a PF drops out of the bond, which the encoded link rate cannot express.
+  The verb is resolved as an optional symbol, so older libraries keep
+  working on the encoded rate. A query *error* keeps the last known
+  effective speed (falling back would briefly restore the higher encoded
+  rate on a degraded LAG); failures are counted per device and logged once
+  per episode
+- The theoretical rate seeds the EWMA and bounds it to
+  `[ewma_min_multiplier, ewma_max_multiplier]` times that rate
+- If a device's port speed cannot be read or is outside [min, max],
+  `default_bandwidth_gbps` is used and a warning is logged
+- A NIC that cannot carry traffic -- its context was never constructed,
+  `construct()` failed, or its port is down -- is marked unavailable: it is
+  excluded from device selection and from the aggregate bandwidth the
+  admission queue's deadline predictor reads. The default speed applies
+  only to a usable NIC whose speed could not be determined. `PORT_ERR`
+  marks a device unavailable and `PORT_ACTIVE` restores it; both are
+  matched against the port the context opened, since a device's async
+  events cover every port of that device
+- The link speed is re-read on `IBV_EVENT_PORT_ACTIVE`, and on
+  `IBV_EVENT_DEVICE_SPEED_CHANGE` where rdma-core (>= 62) provides it. If
+  the speed changed -- a 400G link returning at 100G, or a VF over LAG
+  losing a PF -- the device's EWMA is re-seeded and its clamp re-derived; a
+  link that returns at the same speed keeps its learned estimate
 
 ## Usage Examples
 
diff --git a/docs/source/design/tent/testing.md b/docs/source/design/tent/testing.md
new file mode 100644
index 0000000000..595ac43aec
--- /dev/null
+++ b/docs/source/design/tent/testing.md
@@ -0,0 +1,202 @@
+(tent-testing)=
+# TENT Testing
+
+TENT's runtime does not inspect how a byte moved. It decides from a small
+`Transport` contract: capabilities, a submit `Status`, and a
+`TransferStatus` (`PENDING` / `COMPLETED` / `FAILED`). That is the
+opening for FakeTransport: an in-memory backend that speaks the same
+contract, moves no bytes, and lets tests drive the real
+`TransferEngineImpl` with deterministic faults.
+
+This page is about that mechanism. Individual test names and binaries
+change; the contract does not. Transport-layer tests (RDMA work-request
+errors, NVLink, GPU registration) stay with each real backend and need
+hardware.
+
+## Why a Fake Transport Works
+
+Correctness splits into two layers:
+
+1. **Transport-layer** — how a backend moves bytes and reports hardware
+   faults. Owned by each `Transport`.
+2. **Runtime-layer** — failover, batch lifecycle, progress worker,
+   shutdown. Owned by `TransferEngineImpl` and `ProxyManager`. The
+   runtime never looks at DMA; it only consumes the contract above.
+
+A real transport produces those values as a side effect of moving data.
+A fake that returns the same values at the same times drives
+`submitTransfer`, `getTransferStatus`, `resubmitTransferTask`,
+`progressBatch`, and shutdown identically. Failures that are hard to
+stage on hardware — a completion that never arrives, the Nth submit
+failing, a batch still `PENDING` when memory is freed — become a
+controlled return value.
+
+The production runtime is not stubbed. Tests wrap or replace the
+transport slots, then exercise the engine as an application would.
+
+```
+Test
+  |
+  v
+TransferEngineImpl / ProxyManager     (unmodified production code)
+  |
+  +-- swapTransportForTest(...)
+  |
+  v
+[optional] fault-injecting decorator
+  |
+  v
+FakeTransport                         (programmable Status, no DMA)
+```
+
+## The Transport Contract Tests Actually Use
+
+FakeTransport implements `Transport` with the minimum surface the
+runtime needs:
+
+- **Capabilities.** Advertise `dram_to_dram` so the engine considers the
+  slot available. Leave GPU capability bits off; FakeTransport tests
+  register CPU buffers. The runtime will not route a CUDA request to a
+  CPU-only fake.
+- **Buffer tagging.** `addMemoryBuffer` records the fake's slot on
+  `BufferDesc::transports`. Without that tag, `resolveTransport()` will
+  not pick the swapped-in backend.
+- **Submit.** Record the request and stamp a `TransferStatus`. Submit
+  itself succeeds unless a decorator or subclass fails it.
+- **Poll.** Return the stamped status, or override it from the poll
+  count (for example `PENDING` for N polls, then `COMPLETED`).
+- **Memory.** `malloc` / `free`. No pinning, no GPU registration, no
+  DMA. `warmupMemory` declines so the engine uses its own warmup path.
+
+Two optional hooks cover most status control without subclassing:
+
+- stamp a status at submit time
+- override the status on each `getTransferStatus`, given the poll count
+
+Call counts on install / submit / poll / register are how a test proves
+the runtime took a path (for example primary submitted once, secondary
+submitted after failover) without looking inside the engine.
+
+Copies of FakeTransport live in the test files that need them, not in a
+shared header. Each test can extend its copy; divergence is expected.
+The point of the fake is the contract, not a single implementation.
+
+## Fault Injection Is a Decorator
+
+FakeTransport, by itself, completes successfully. Faults are layered on
+top so the engine still sees an ordinary `Transport`:
+
+| Layer | Role |
+|-------|------|
+| FakeTransport | In-memory success path; programmable completions. |
+| `FaultProxyTransport` | Wraps any `Transport` and injects policy-driven faults: failed submit, `COMPLETED → FAILED` on poll, failed `install()`, optional delay. |
+| Test-local subclass | When the fault is not a policy (poison only some requests; flip an atomic mid-loop). |
+
+The engine's failover and retry paths run unmodified. The decorator is
+what makes a completion-stage `FAILED` look like a WC error or a dropped
+peer, without a verbs layer.
+
+`FaultProxyTransport` lives under
+`mooncake-transfer-engine/tent/transport/fault_proxy/`. Its policy
+fields are the source of truth; this page does not duplicate them.
+
+## Installing Fakes Without Bypassing the Runtime
+
+`TransferEngineImpl::swapTransportForTest` replaces one slot in
+`transport_list_` after `construct()`. That is the only test hook that
+installs a fake (or a wrapped fake) while leaving `resolveTransport()`
+and `resubmitTransferTask()` on the production path. Production code
+never calls it.
+
+A typical setup:
+
+1. Build a config with `p2p` metadata on loopback and **real transports
+   disabled**, so `construct()` does not require Redis, etcd, or an RDMA
+   device.
+2. Construct the engine.
+3. `install()` the fake (or proxy), then `swapTransportForTest` into the
+   slots under test. Swap only replaces the slot; it does not re-run
+   engine availability.
+4. Register memory *after* the swap, so `addMemoryBuffer` tags the
+   buffers.
+5. Submit and poll through the public engine API.
+
+Install two slots when the scenario needs a fallback (typically RDMA +
+TCP). Install one slot when the test wants no failover.
+
+`USE_CUDA=OFF` is required on CPU-only hosts. With CUDA enabled and no
+GPU, pointer queries fail, memory type becomes unknown, every transport
+looks unavailable, and `resolveTransport()` returns `UNSPEC` before any
+injected fault runs.
+
+## What the Mechanism Can Prove
+
+FakeTransport proves how the runtime *reacts* to the transport contract.
+It cannot prove that a backend moved the right bytes.
+
+**In scope.** Cross-transport failover and budget exhaustion; poll vs
+`progressBatch` recovery; progress-worker and `freeBatch` races; queue /
+hint / metrics behavior that only depends on submit and poll results;
+concurrency of runtime maps that FakeTransport can reach.
+
+**Out of scope.** DMA integrity; verbs-level failures (WC error, QP
+failure); GPU registration; NVLink link faults; true async RPC timing
+(in-process callbacks fire synchronously). Those belong to each
+transport's tests, `tebench --check_consistency=true` on real peers, or
+multi-node hardware CI.
+
+(staging-trigger-constraints)=
+
+**Staging is decided before the request reaches a transport.**
+`findStagingPolicy()` inspects which hardware backends are installed and
+what memory types the request uses, then `ProxyManager` runs the staging
+loop. Swapping FakeTransport into RDMA or TCP does not change that
+decision, and every current trigger is gated on NVLink, MNNVL, or TPU —
+none of which a CPU-only fake replaces. A CPU-only host therefore cannot
+exercise `transferEventLoop` with either real transports or fakes.
+Covering that path is a hardware-runner problem, or a product change to
+the staging policy, not a missing FakeTransport feature.
+
+## Running
+
+```bash
+cmake -S . -B build-tent \
+  -DUSE_TENT=ON -DUSE_CUDA=OFF \
+  -DWITH_STORE=OFF -DWITH_STORE_RUST=OFF \
+  -DBUILD_UNIT_TESTS=ON -DCMAKE_BUILD_TYPE=Release
+
+cmake --build build-tent --target mooncake_common -j
+ctest --test-dir build-tent/mooncake-transfer-engine/tent/tests \
+  --output-on-failure
+```
+
+`tent_link_group` links `mooncake_common` by archive path, which does
+not create a CMake build-order dependency — build `mooncake_common`
+first. The `tent-ci` `cuda-off` legs in GitHub Actions run the same
+`ctest` directory. The `cuda-on` leg compiles only: runners have no GPU,
+and CUDA stubs would bypass the fakes.
+
+Concurrency tests that touch shared runtime maps should also be run
+under ThreadSanitizer (`-fsanitize=thread`). Which binaries those are
+belongs in the test sources, not here.
+
+## What belongs in this suite
+
+Tests should call production functions or the public engine API. Do not
+reimplement a state machine in the test file and assert against that
+copy. Enum assignment, `std::atomic` store/load, and `Config::get/set`
+without going through `install()` / `TransferEngineImpl` do not lock
+runtime behavior.
+
+Binaries that are not ctest:
+
+- `tent_metrics_example` — HTTP metrics demo
+- `deadline_promotion_bench` — hot-path microbenchmark
+- `tent/benchmark/hip_bandwidth_bench.cpp` — standalone `hipcc` HIP
+  bandwidth sweep; CMake does not build it
+
+Hardware data-path tests (`tent_rdma_transport_test` roundtrip,
+`tent_nvlink_transport_test`, Sunrise, MPComm) skip or are omitted from
+ctest when the device is missing. That skip is expected; a green
+`cuda-off` run does not mean those paths were exercised. `tent_nvlink_transport_test`
+is built when CUDA is on but is not registered with ctest.
diff --git a/docs/source/design/tent/transport-selector.md b/docs/source/design/tent/transport-selector.md
index e4ba13e2ec..6eef995148 100644
--- a/docs/source/design/tent/transport-selector.md
+++ b/docs/source/design/tent/transport-selector.md
@@ -191,6 +191,25 @@ If no `policy` is configured, TENT falls back to original behavior:
 | File | GDS → IOURING → RDMA |
 | Memory | Uses `buffer_transports` order from buffer registration |
 
+### UB as a selectable transport
+
+UB (`TransportType::UB`) takes part in the same policy machinery as every other
+transport: it can be listed in a policy's `transports` array, pinned with
+`transport_hint`, or reached through `transport_index`. Two places name it
+explicitly instead:
+
+* **Local memory allocation.** When the requested transport is `UNSPEC`,
+  allocation walks `MNNVL → RDMA → UB → TCP → HP_TCP` (with `SHM` taking the
+  host-memory slot ahead of RDMA for CPU and wildcard locations), so an
+  installed UB transport is preferred over the generic TCP paths.
+* **TPU staging.** The TPU staging policy needs a host-DRAM network transport
+  for the host↔host hop and gates on `RDMA`, `UB`, `TCP` or `HP_TCP`.
+
+Once UB is the selected transport, the rail for each slice is chosen inside
+`UbTransport` rather than by this selector; see {ref}`TENT Failover
+<tent-failover>` for UB rail health, path ranking and endpoint rebuild
+behaviour.
+
 ## Complete Example
 
 ```json
diff --git a/docs/source/design/transfer-engine/index.md b/docs/source/design/transfer-engine/index.md
index 93d6d40125..c9b76a9a95 100644
--- a/docs/source/design/transfer-engine/index.md
+++ b/docs/source/design/transfer-engine/index.md
@@ -11,7 +11,7 @@ Mooncake Transfer Engine is a high-performance, zero-copy data transfer library
 
 As shown in the diagram, each specific client corresponds to a `TransferEngine`, which not only includes a RAM Segment but also integrates management for high-speed transfers across multiple threads and network cards. The RAM Segment, in principle, corresponds to the entire virtual address space of this `TransferEngine`, but in reality, only parts of it (known as a `Buffer`) are registered for (GPUDirect) RDMA Read/Write. Each Buffer can have separate permissions (corresponding to RDMA `rkey`, etc.) and network card affinity (e.g., preferred NICs for different types of memory).
 
-Mooncake Transfer Engine provides interfaces through the `TransferEngine` class (located in `mooncake-transfer-engine/include/transfer_engine.h`), where the specific data transfer functions for different backends are implemented by the `Transport` class, currently supporting `TcpTransport`, `RdmaTransport`, `EfaTransport`, `NVMeoFTransport`, `NvlinkTransport`, `IntraNodeNvlinkTransport`, and `HipTransport`.
+Mooncake Transfer Engine provides interfaces through the `TransferEngine` class (located in `mooncake-transfer-engine/include/transfer_engine.h`), where the specific data transfer functions for different backends are implemented by the `Transport` class, currently supporting `TcpTransport`, `RdmaTransport`, `EfaTransport`, `NVMeoFTransport`, `NvlinkTransport`, `IntraNodeNvlinkTransport`, `HipTransport`, and `ShmTransport`.
 
 (segment)=
 ### Segment
@@ -41,6 +41,7 @@ With the help of Transfer Engine, Mooncake Store can achieve local DRAM/VRAM rea
 | NVMe-of          | ✓    | ✓    |
 
 - Local memcpy: If the target Segment is actually in the local DRAM/VRAM, direct data copy interfaces such as memcpy, cudaMemcpy are used.
+- SHM: Same-host DRAM transfers of POSIX shm-backed buffers (`MC_FORCE_SHM=1`). With `-DENABLE_MULTI_PROTOCOL=ON` this installs SHM alongside RDMA/TCP; without it, SHM is the only transport. Objects are `0600` (same UID). Same hostname does not imply a shared `/dev/shm`. In-flight copies pin the cached mmap so prune/cap cannot unmap it.
 - TCP: Supports data transfer between local DRAM and remote DRAM.
 - RDMA: Supports data transfer between local DRAM/VRAM and remote DRAM. It supports multi-network card pooling and retry functions in implementation.
 - HIP: Supports intra-node data transfers between GPU VRAM and GPU VRAM, as well as between GPU VRAM and CPU DRAM, using IPC handles or Shareable handles for ROCm.
@@ -159,7 +160,7 @@ The following video shows a normal run as described above, with the Target on th
 ![transfer-engine-running](../../image/transfer-engine-running.gif)
 
 ## Transfer Engine C/C++ API
-Transfer Engine provides interfaces through the `TransferEngine` class (located in `mooncake-transfer-engine/include/transfer_engine.h`), where the specific data transfer functions for different backends are implemented by the `Transport` class, currently supporting `TcpTransport`, `RdmaTransport`, `EfaTransport` (for AWS EFA), `NVMeoFTransport`, `NvlinkTransport` (for NVIDIA GPUs), `IntraNodeNvlinkTransport` (for NVIDIA GPUs), and `HipTransport` (for AMD GPUs).
+Transfer Engine provides interfaces through the `TransferEngine` class (located in `mooncake-transfer-engine/include/transfer_engine.h`), where the specific data transfer functions for different backends are implemented by the `Transport` class, currently supporting `TcpTransport`, `RdmaTransport`, `EfaTransport` (for AWS EFA), `NVMeoFTransport`, `NvlinkTransport` (for NVIDIA GPUs), `IntraNodeNvlinkTransport` (for NVIDIA GPUs), `HipTransport` (for AMD GPUs), and `ShmTransport` (POSIX shm for same-host DRAM).
 
 For a complete C++ API reference, see [Transfer Engine C++ API Reference](../../api-reference/cpp/transfer-engine.md).
 
@@ -446,7 +447,17 @@ To support the operational needs of P2P Store, Transfer Engine provides a Golang
 When compiling the project, enable the `-DWITH_P2P_STORE=ON` option to compile the P2P Store example program at the same time.
 
 ### Using Rust Interface
-Under `mooncake-transfer-engine/rust`, the Rust interface implementation of TransferEngine is provided, and a Rust version of the benchmark is implemented based on the interface, similar to [transfer_engine_bench.cpp](gh-file:mooncake-transfer-engine/example/transfer_engine_bench.cpp). To compile the rust example, you need to install the Rust SDK and add `-DWITH_RUST_EXAMPLE=ON` in the cmake command.
+`mooncake-transfer-engine/rust` ships `transfer_engine_rust`, a library crate
+that wraps the Transfer Engine C API (`transfer_engine_c.h`). Hot-path types
+(`TransferRequest`, `BufferEntry`, `TransferStatus`) match the C ABI so
+`submit_transfer` is a zero-copy FFI call. A throughput benchmark example
+(`examples/transfer_engine_bench.rs`) mirrors
+[transfer_engine_bench.cpp](gh-file:mooncake-transfer-engine/example/transfer_engine_bench.cpp).
+
+To build the library and example, install a Rust toolchain and libclang, then
+configure CMake with `-DWITH_RUST_EXAMPLE=ON`. See the
+[Transfer Engine Rust API](../../api-reference/rust/transfer-engine.md) for
+signatures and the crate `README.md` for Cargo-only builds.
 
 ## Advanced Runtime Options
 For advanced users, TransferEngine provides the following advanced runtime options, all of which can be passed in through **environment variables**.
@@ -487,18 +498,24 @@ For advanced users, TransferEngine provides the following advanced runtime optio
 - `MC_ENABLE_DEST_DEVICE_AFFINITY` Enable device affinity for RDMA performance optimization. When enabled, Transfer Engine will prioritize communication with remote NICs that have the same name as local NICs to reduce QP count and improve network performance in rail-optimized topologies. The default value is false
 - `MC_TRACK_RDMA_POSTED_SLICES` Enable RDMA posted-slice tracking for timeout diagnostics. When enabled, CQ timeout logs include stuck transfer groups by peer NIC path, slice count, bytes, oldest post age, and sample addresses. This adds synchronization on the RDMA post and poll hot paths, so it is disabled by default and should be enabled only while diagnosing stuck completions.
 - `MC_ENABLE_PARALLEL_REG_MR` Control parallel memory region registration across multiple RDMA NICs. Valid values: -1 (auto, default), 0 (disabled), 1 (enabled). When set to -1, parallel registration is automatically enabled when multiple RNICs exist and memory has been pre-touched. Note: If memory hasn't been touched before registration, parallel registration can be slower than sequential registration
-- `MC_MAX_CONCURRENT_REG_MR` Cap on how many buffers `registerLocalMemoryBatch` registers concurrently (EFA transport). The default 0 means unbounded — one thread per buffer, the historical behavior. Note the cap is **per process**, so a framework running one `TransferEngine` per TP rank multiplies it by the rank count. Capping can cut registration time substantially when a batch holds many large GPU buffers. Registration is CPU-bound, so a reasonable value is `cores / processes-per-node` — on a 192-core node running 8 ranks, around 16. Oversubscribing costs more than undersubscribing, and the result also depends on the order the caller passes buffers in, so a poorly chosen cap can be slower than unbounded — hence opt-in.
+- `MC_MAX_CONCURRENT_REG_MR` Cap how many buffers the EFA and RDMA transports process concurrently in `registerLocalMemoryBatch` and `unregisterLocalMemoryBatch`. The default 0 means unbounded — one thread per buffer, the historical behavior. Note the cap is **per process**, so a framework running one `TransferEngine` per TP rank multiplies it by the rank count. Capping can cut registration time substantially when a batch holds many large GPU buffers. Registration is CPU-bound, so a reasonable value is `cores / processes-per-node` — on a 192-core node running 8 ranks, around 16. Oversubscribing costs more than undersubscribing, and the result also depends on the order the caller passes buffers in, so a poorly chosen cap can be slower than unbounded — hence opt-in.
 - `MC_EFA_NIC_SELECTION` Which NICs the EFA transport registers a buffer on. `all` (the default) registers every buffer on every NIC. `local` restricts **device** memory to the NICs the topology reports as closest to that GPU, which on p5.48xlarge is the 4 EFA devices sharing the GPU's PCIe root complex. Because EFA charges device-memory registration in proportion to the device bytes already registered on the same libfabric domain, narrowing the NIC set cuts registration time by close to the fan-out ratio. Set it when registering many GPU buffers is a startup bottleneck; it is opt-in because fewer NICs can serve a transfer touching that buffer, so a job whose working set sits behind a single GPU is capped at that rail group's bandwidth rather than the node's. Host memory is unaffected. Combine with `MC_MAX_CONCURRENT_REG_MR`, which bounds a different variable: this reduces the cost per registration, that one reduces how many run at once.
 - `MC_EFA_CQ_THREADS` Cap on the number of CQ polling threads in the EFA transport, default value 1 (which already reaches ~99.9% of peak throughput). Pollers busy-wait, so each extra thread costs a full core. Set 0 to lift the cap (one poller per EFA device). Values above the device count are ignored
 - `MC_FORCE_HCA` Force to use RDMA as the active transport, return error if no HCA has been found.
 - `MC_FORCE_MNNVL` Force to use Multi-Node NVLink as the active transport regardless whether RDMA devices are installed.
+- `MC_FORCE_MUSA` (MUSA only) Force the `musa` GPU IPC transport even when RDMA devices are installed. `MC_FORCE_MNNVL` remains accepted as a compatibility alias in MUSA builds.
 - `MC_INTRA_NVLINK` Enable intra-node NVLINK transport, and cannot be used together with MC_FORCE_MNNVL.
-- `MC_FORCE_TCP` Force to use TCP as the active transport regardless whether RDMA devices are installed.
+- `MC_MUSA_IPC_OPEN_DEVICE` (`musa` transport only) Select the device context used to open imported IPC memory. The default `current` preserves the caller's context; `metadata` is an opt-in that uses the runtime-visible logical ordinal advertised by the remote buffer. With `metadata`, every peer must map each logical ordinal to the same physical GPU. `MTHREADS_VISIBLE_DEVICES` is a container-toolkit setting and is not used by Mooncake to infer this mapping.
+- `MC_MUSA_COPY_API` (`musa` transport only) Select `auto` (default), `transfer_batch`, or `default`. On MUSA SDK 5.2 or newer, `auto` uses `muMemoryTransferBatchAsync` when every copy in a batch meets `MC_MUSA_TRANSFER_BATCH_MIN_BYTES`; `default` uses per-slice CUDA-compatible copies.
+- `MC_MUSA_TRANSFER_BATCH_MIN_BYTES` (`musa` transport only) Minimum copy size selected by `MC_MUSA_COPY_API=auto`. The default is 1048576 (1 MiB).
+- `MC_FORCE_TCP` Force to use TCP as the active transport regardless whether RDMA devices are installed. Takes precedence over `MC_FORCE_SHM`.
+- `MC_FORCE_SHM` Opt in to POSIX SHM (or hugetlbfs-backed SHM via `allocateSharedMemory(..., SharedMemoryOptions)`) for same-host DRAM copies of buffers allocated with `allocateSharedMemory`. Default off. With `-DENABLE_MULTI_PROTOCOL=ON`, SHM is installed alongside RDMA/TCP (`rdma,shm` / `tcp,shm`). Without multi-protocol, SHM is the only transport (skip RDMA/TCP auto-install), like `MC_FORCE_TCP`. `MC_FORCE_TCP` is handled first in `init` and returns before SHM install. Alternative: `installTransport("shm")`, which logs a WARNING if it overwrites a non-empty rdma/tcp protocol. Objects are created `0600` (same UID). `freeSharedMemory` unlinks the object; `SIGKILL` leftovers in `/dev/shm` or on the hugetlbfs mount are not reaped (hugetlbfs files continue to reserve hugepages — do not wipe all `mooncake_*` on start). A peer `free`+`allocate` that reuses the same virtual address is remapped after the name disappears; a new address still needs a fresh `BufferDesc` (see `MC_TE_METADATA_REFRESH_INTERVAL_SECONDS`).
 - `MC_MIN_RPC_PORT` Specifies the minimum port number for RPC service. The default value is 15000.
 - `MC_MAX_RPC_PORT` Specifies the maximum port number for RPC service. The default value is 17000.
 - `MC_PATH_ROUNDROBIN` Use round-robin mode in the RDMA path selection. This may be beneficial for transferring large bulks.
 - `MC_TE_FILTERS` Optional comma-separated whitelist of IB device names (e.g. `mlx5_0,mlx5_2`) for legacy Transfer Engine topology discovery. When unset, all available devices are discovered.
-- `WITH_NVIDIA_PEERMEM` When set to `1`, `ON`, or `TRUE`, Mooncake uses `ibv_reg_mr()` directly for GPU memory registration (requires the `nvidia-peermem` kernel module). By default (unset or `0`), Mooncake uses the DMA-BUF path which does not require `nvidia-peermem`.
+- `WITH_NVIDIA_PEERMEM` When unset or set to `1`, `ON`, or `TRUE`, Mooncake uses `ibv_reg_mr()` directly for GPU memory registration (requires the `nvidia-peermem` kernel module). Set to `0` to use the DMA-BUF path without `nvidia-peermem`. `MC_RDMA_DATA_DIRECT=1` takes precedence for the classic RDMA transport.
+- `MC_RDMA_DATA_DIRECT` Set to `1` to enable NVIDIA Data Direct for CUDA device memory in the classic RDMA transport (default: disabled). Overrides `WITH_NVIDIA_PEERMEM`. Requires a [supported platform](https://docs.nvidia.com/multi-node-nvlink-systems/grace-blackwell-cx8-gpudirect-rdma-guide/platform_software_and_configuration.html), compatible runtime `libmlx5`, and compatible NICs selected with `MC_TE_FILTERS` or custom topology. Unsupported configurations fail without fallback.
 - `MC_ENDPOINT_STORE_TYPE` Choose FIFO Endpoint Store (`FIFO`) or Sieve Endpoint Store (`SIEVE`), default is `SIEVE`.
 - `MC_TCP_ENABLE_CONNECTION_POOL` Enable TCP Connection Pool to avoid excessive sockets.
 - `MC_TCP_SLICE_SIZE` The segmentation granularity (in bytes) of TCP transport for splitting large transfers into socket read/write operations. Corresponds to `MC_SLICE_SIZE` for RDMA. Default value 65536 (64KB).
@@ -516,33 +533,6 @@ For the complete C++ API reference, see [Transfer Engine C++ API](../../api-refe
 ../../getting_started/supported-protocols
 :::
 
-## EFA Transport (AWS)
-
-:::{toctree}
-:maxdepth: 1
-
-efa_transport
-:::
-
-## Ascend Transport Component
-
-:::{toctree}
-:maxdepth: 1
-
-ascend_direct_transport
-ascend_transport
-heterogeneous_ascend
-:::
-
-## Sunrise Link Transport Component
-
-:::{toctree}
-:maxdepth: 1
-
-kunpeng_ub_transport
-sunrise_link_transport
-:::
-
 ## Benchmark and Tuning Guide
 
 :::{toctree}
diff --git a/docs/source/design/transfer-engine/ascend_direct_transport.md b/docs/source/design/transfer-engine/transport/ascend_direct_transport.md
similarity index 100%
rename from docs/source/design/transfer-engine/ascend_direct_transport.md
rename to docs/source/design/transfer-engine/transport/ascend_direct_transport.md
diff --git a/docs/source/design/transfer-engine/ascend_transport.md b/docs/source/design/transfer-engine/transport/ascend_transport.md
similarity index 100%
rename from docs/source/design/transfer-engine/ascend_transport.md
rename to docs/source/design/transfer-engine/transport/ascend_transport.md
diff --git a/docs/source/design/transfer-engine/efa_transport.md b/docs/source/design/transfer-engine/transport/efa_transport.md
similarity index 99%
rename from docs/source/design/transfer-engine/efa_transport.md
rename to docs/source/design/transfer-engine/transport/efa_transport.md
index b624485646..3fcd89ddf8 100644
--- a/docs/source/design/transfer-engine/efa_transport.md
+++ b/docs/source/design/transfer-engine/transport/efa_transport.md
@@ -31,7 +31,7 @@ cd Mooncake
 sudo ./dependencies.sh -y
 ```
 
-This installs all system packages, git submodules (including pybind11 and yalantinglibs), and Go.
+This installs all system packages, git submodules (pybind11), and Go.
 
 > **Note:** The EFA driver and libfabric are **not** installed by `dependencies.sh`. They must be pre-installed on the instance (see section 1 above).
 
diff --git a/docs/source/design/transfer-engine/transport/flagcx_transport.md b/docs/source/design/transfer-engine/transport/flagcx_transport.md
new file mode 100644
index 0000000000..0d03b369b0
--- /dev/null
+++ b/docs/source/design/transfer-engine/transport/flagcx_transport.md
@@ -0,0 +1,332 @@
+# FlagOS FlagCX Transport
+
+## Overview
+
+[FlagCX](https://github.com/flagos-ai/FlagCX) is the unified communication library in the FlagOS
+ecosystem for multi-vendor and cross-vendor deployments. Mooncake's FlagCX transport connects the
+classic Transfer Engine to the FlagCX P2P Engine. The integration keeps Mooncake's existing
+segment, memory-registration, batch, and completion APIs and maps them to FlagCX connections and
+P2P read/write requests.
+
+The protocol name used by Mooncake configuration and APIs is `flagcx`. `flagos` is not a protocol
+name.
+
+> **Classic Transfer Engine only.** The FlagCX transport is implemented under
+> `mooncake-transfer-engine/src/transport/` and is not a TENT transport. Build with
+> `USE_FLAGCX=ON`, select `--backend=classic` in `tebench`, and use `flagcx` as a standalone
+> protocol.
+
+### Code Structure
+
+| Unit | Responsibility |
+|------|----------------|
+| `flagcx_transport.{h,cpp}` | Creates the P2P Engine, advertises its endpoint, registers memory, opens peer connections, submits transfers, and polls completion |
+| `flagcx_transport_internal.h` | Overflow-safe registered-range checks and descriptor-length conversion |
+| `mooncake-common/common.cmake` | Locates the external FlagCX headers and library and defines `FlagCX::flagcx` |
+| `multi_transport.cpp` | Instantiates `FlagCxTransport` when the protocol name is `flagcx` |
+
+### Transfer Pipeline
+
+1. **Initialization:** Mooncake creates a FlagCX P2P Engine and starts its RPC server.
+2. **Advertisement:** the transport obtains the FlagCX endpoint and publishes it in the local
+   Mooncake segment descriptor.
+3. **Registration:** `registerLocalMemory()` registers each local range with FlagCX and publishes
+   the corresponding Mooncake buffer descriptor.
+4. **Connection:** the first request to a remote segment reads its published FlagCX endpoint and
+   opens a connection. FlagCX caches the connection for later requests.
+5. **Submission:** Mooncake groups requests with the same target and operation, creates remote
+   descriptors, and calls the FlagCX vector read or write API.
+6. **Completion:** a Mooncake worker polls the returned FlagCX transfer ID and updates the original
+   Mooncake task when the transfer becomes terminal.
+
+---
+
+## Dependencies
+
+Use compatible FlagCX revisions on all nodes. Each node may build the accelerator backend that
+matches its local platform. The prefix passed as `FLAGCX_HOME` must contain:
+
+- `include/flagcx_p2p.h`
+- `lib/libflagcx.so` or `lib64/libflagcx.so`
+- The accelerator runtime, communication library, and network dependencies required by the chosen
+  FlagCX backend
+
+Choose the FlagCX backend that matches each node's local platform; for example, `USE_NVIDIA=1`,
+`USE_METAX=1`, or `USE_MUSA=1`. See the
+[FlagCX getting-started guide](https://github.com/flagos-ai/FlagCX/blob/main/docs/getting_started.md)
+for the current backend list and platform prerequisites.
+
+## Build and Compile
+
+### 1. Build FlagCX
+
+```bash
+git clone https://github.com/flagos-ai/FlagCX.git
+cd FlagCX
+git submodule update --init --recursive
+
+# Replace USE_NVIDIA with the backend for the local platform.
+make USE_NVIDIA=1 -j$(nproc)
+```
+
+The default build output is suitable for an in-tree Mooncake build:
+
+```text
+FlagCX/build/include/flagcx_p2p.h
+FlagCX/build/lib/libflagcx.so
+```
+
+Alternatively, install FlagCX under a dedicated prefix. Installing under `/opt` normally requires
+root privileges:
+
+```bash
+sudo make PREFIX=/opt/flagcx install
+```
+
+### 2. Build Mooncake
+
+From the Mooncake repository root:
+
+```bash
+cmake -S . -B build \
+  -DUSE_FLAGCX=ON \
+  -DFLAGCX_HOME=/path/to/FlagCX/build
+cmake --build build -j$(nproc)
+```
+
+For the installed layout above, use `-DFLAGCX_HOME=/opt/flagcx`. If `FLAGCX_HOME` is not passed to
+CMake, Mooncake first checks the environment variable of the same name, then defaults to
+`$HOME/FlagCX/build`.
+
+Configuration fails early if either `flagcx_p2p.h` or the FlagCX shared library cannot be found.
+A successful configuration includes a message similar to:
+
+```text
+FlagCX transport enabled, include=/path/to/FlagCX/build/include, library=/path/to/FlagCX/build/lib/libflagcx.so
+```
+
+Make the shared library and its backend dependencies visible to the dynamic linker when they are
+not installed in a system search path:
+
+```bash
+export FLAGCX_HOME=/path/to/FlagCX/build
+export LD_LIBRARY_PATH="$FLAGCX_HOME/lib:${LD_LIBRARY_PATH:-}"
+```
+
+If Mooncake also needs to allocate or identify device memory, enable its matching hardware option,
+such as `USE_CUDA`, `USE_MACA`, `USE_MUSA`, `USE_HIP`, `USE_COREX`, `USE_HYGON`, or `USE_MLU`.
+See the [build guide](../../../getting_started/build.md) for the options and SDK requirements.
+
+---
+
+## Enabling the Transport
+
+### Python API
+
+A Mooncake Python extension built from source with `USE_FLAGCX=ON` accepts `flagcx` through the
+existing initialization API:
+
+```python
+engine.initialize(
+    hostname="node1",
+    metadata_server="P2PHANDSHAKE",
+    protocol="flagcx",
+    device_name="",
+)
+```
+
+The Python binding disables automatic RDMA transport discovery for this protocol and installs the
+FlagCX transport explicitly. No new Python API is required.
+
+### C++ API
+
+Applications using the classic C++ Transfer Engine can install the transport by name after engine
+initialization. Keep automatic transport discovery disabled so that `flagcx` remains the standalone
+transport:
+
+```cpp
+mooncake::TransferEngine engine(false);
+if (engine.init("P2PHANDSHAKE", "node1") != 0) {
+    return -1;
+}
+
+auto* transport = engine.installTransport("flagcx", nullptr);
+if (transport == nullptr) {
+    return -1;
+}
+```
+
+Continue to use the standard Transfer Engine APIs for memory registration, segment discovery,
+batch submission, and status queries.
+
+---
+
+## Run and Test
+
+### Connectivity Test with `tebench`
+
+`tebench` can validate registration, endpoint exchange, connection setup, read/write transfers,
+and completion. Both peers must use the classic backend and the `flagcx` transport. An empty
+`--target_seg_name` starts the target; setting it starts the initiator.
+
+Choose a network interface reachable by the other peer on both hosts:
+
+```bash
+export FLAGCX_SOCKET_IFNAME=eth0
+```
+
+Start the target first:
+
+```bash
+./build/mooncake-transfer-engine/benchmark/tebench \
+  --backend=classic \
+  --xport_type=flagcx \
+  --metadata_type=p2p \
+  --seg_type=DRAM \
+  --total_buffer_size=1073741824
+```
+
+The target prints a command containing its segment name. Use that value on the initiator:
+
+```bash
+./build/mooncake-transfer-engine/benchmark/tebench \
+  --backend=classic \
+  --xport_type=flagcx \
+  --metadata_type=p2p \
+  --target_seg_name=<target-segment-name> \
+  --seg_type=DRAM \
+  --total_buffer_size=1073741824 \
+  --op_type=read \
+  --start_block_size=4096 \
+  --max_block_size=67108864 \
+  --start_batch_size=1 \
+  --max_batch_size=1 \
+  --start_num_threads=1 \
+  --max_num_threads=1
+```
+
+Use `--op_type=write` to test the opposite direction. The classic `tebench` VRAM allocator currently
+supports CUDA builds. For that path, add `-DUSE_CUDA=ON` when building Mooncake and run with
+`--seg_type=VRAM`. Other accelerator backends should validate device buffers through their
+application integration until `tebench` provides a matching allocator.
+
+Useful initialization messages include:
+
+```text
+FlagCxTransport: engine up, endpoint=...
+FlagCxTransport: install OK (direct submit)
+tebench: FlagCX transport installed
+```
+
+### Hardware-Free Checks
+
+The internal range and descriptor-boundary test does not require FlagCX hardware:
+
+```bash
+ctest --test-dir build -R '^flagcx_transport_internal_test$' --output-on-failure
+```
+
+The Python source integration check verifies that the binding recognizes and installs `flagcx`:
+
+```bash
+python3 -m unittest mooncake-wheel/tests/test_transfer_engine_flagcx_source.py
+```
+
+---
+
+## Runtime Configuration
+
+FlagCX owns network-device selection and most transport tuning. The variables most relevant to the
+Mooncake integration are:
+
+| Variable | Purpose |
+|----------|---------|
+| `FLAGCX_SOCKET_IFNAME` | Selects the interface used for socket bootstrap and endpoint advertisement; it does not select the RDMA HCA |
+| `FLAGCX_IB_HCA` | Selects the InfiniBand/RoCE HCA or HCA set used by FlagCX |
+| `FLAGCX_P2P_TRANSPORT=accl` | Selects the optional ACCL P2P implementation when the FlagCX build includes it; both peers must set it |
+| `LD_LIBRARY_PATH` | Makes `libflagcx.so` and non-system backend libraries visible at run time |
+
+Set `FLAGCX_SOCKET_IFNAME` and `FLAGCX_IB_HCA` for each node's local interfaces and devices. For
+interface filtering syntax, GID selection, retry settings, and backend-specific tuning, see the
+[FlagCX environment-variable reference](https://github.com/flagos-ai/FlagCX/blob/main/docs/environment_variables.md).
+
+## Important Notes
+
+### Memory Registration Lifecycle
+
+The FlagCX connection handshake exchanges the peer's registered-memory table, and the P2P Engine
+caches established connections. Use the following lifecycle for the current Mooncake integration:
+
+1. Register every buffer that a peer may access.
+2. Establish or use the peer connection only after registration is complete.
+3. Keep those buffers registered while the connection or its transfers are active.
+4. Stop submitting work and allow outstanding work to finish before unregistering or freeing the
+   buffers.
+
+Registering a new remote buffer after a peer has already cached its connection does not refresh the
+connection's memory table. Reconnect both processes before using a changed registration set.
+
+### Deployment Scope
+
+- Use the literal protocol name `flagcx`; do not use `flagos`.
+- Use `flagcx` as a standalone protocol. Multi-protocol selection and routing are outside the
+  current integration scope.
+- The peers may use different accelerator backends, but they must use compatible FlagCX revisions
+  and the same P2P network transport: default IBRC on both peers, or ACCL on both peers.
+- The transport relies on FlagCX's endpoint exchange and completion behavior; it does not add a
+  separate Mooncake cancellation API.
+
+### Security and Trust
+
+Treat the FlagCX endpoint like other RDMA-capable transport endpoints. Only expose it to trusted
+peers, restrict the selected interface with network policy or host firewall rules, and register only
+the memory required by the application. Mooncake segment metadata exposes the endpoint and buffer
+addresses, while the FlagCX handshake exchanges the registered-region table. Do not expose either
+channel to untrusted peers.
+
+## Troubleshooting
+
+### CMake Cannot Find FlagCX
+
+```text
+USE_FLAGCX=ON but flagcx_p2p.h was not found
+```
+
+Check that `FLAGCX_HOME/include/flagcx_p2p.h` exists. If the header remains only in the FlagCX
+source tree, finish the FlagCX build so its public headers are copied to `build/include`, or run its
+install target and point `FLAGCX_HOME` at that prefix.
+
+```text
+USE_FLAGCX=ON but the FlagCX library was not found
+```
+
+Check for `FLAGCX_HOME/lib/libflagcx.so` or `FLAGCX_HOME/lib64/libflagcx.so` and confirm that the
+same prefix is passed during CMake configuration.
+
+### The Executable Cannot Load `libflagcx.so`
+
+If startup reports that `libflagcx.so` or a platform backend library is missing, add their library
+directories to `LD_LIBRARY_PATH` or install them in a configured system loader path. This is a
+run-time linker issue, not a Mooncake protocol-selection issue.
+
+### The FlagCX Engine Advertises the Wrong Interface
+
+Set `FLAGCX_SOCKET_IFNAME` before starting each process. Use an interface whose advertised address
+is reachable from the peer. If InfiniBand/RoCE device selection is also ambiguous, set
+`FLAGCX_IB_HCA` to the appropriate local HCA set on each side.
+
+### `installTransport(flagcx)` Fails
+
+Confirm all of the following:
+
+- Mooncake was configured with `USE_FLAGCX=ON`.
+- The FlagCX shared library and its platform dependencies load successfully.
+- `FLAGCX_SOCKET_IFNAME` resolves to a usable local address.
+- The FlagCX log does not report a P2P Engine or RPC-server initialization error.
+
+### Connection or Remote-Descriptor Creation Fails
+
+Verify that the target process is still running, the endpoint printed in the target log is reachable,
+and both peers selected the same FlagCX P2P network transport. Check host firewall rules on the
+connection path. If the target's registrations changed after the connection was first used, restart
+both processes and register all buffers before reconnecting.
diff --git a/docs/source/design/transfer-engine/heterogeneous_ascend.md b/docs/source/design/transfer-engine/transport/heterogeneous_ascend.md
similarity index 100%
rename from docs/source/design/transfer-engine/heterogeneous_ascend.md
rename to docs/source/design/transfer-engine/transport/heterogeneous_ascend.md
diff --git a/docs/source/design/transfer-engine/kunpeng_ub_transport.md b/docs/source/design/transfer-engine/transport/kunpeng_ub_transport.md
similarity index 97%
rename from docs/source/design/transfer-engine/kunpeng_ub_transport.md
rename to docs/source/design/transfer-engine/transport/kunpeng_ub_transport.md
index a751b9971b..cfd9fcf2c4 100644
--- a/docs/source/design/transfer-engine/kunpeng_ub_transport.md
+++ b/docs/source/design/transfer-engine/transport/kunpeng_ub_transport.md
@@ -58,15 +58,6 @@ sudo apt-get install -y \
     libyaml-cpp-dev \
     pybind11-dev \
     python3-dev
-
-# Install yalantinglibs (required)
-cd /tmp
-git clone https://github.com/alibaba/yalantinglibs.git
-cd yalantinglibs
-mkdir build && cd build
-cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
-make -j$(nproc)
-sudo make install
 ```
 
 ## Building Mooncake with UB Support
diff --git a/docs/source/design/transfer-engine/transport/mpcomm_transport.md b/docs/source/design/transfer-engine/transport/mpcomm_transport.md
new file mode 100644
index 0000000000..ad4017c0ff
--- /dev/null
+++ b/docs/source/design/transfer-engine/transport/mpcomm_transport.md
@@ -0,0 +1,573 @@
+# MPComm Transport
+
+## Overview
+
+UCL-MPComm (Unified Communication Library - Memory Pool Communication) is a high-performance RDMA
+communication library for heterogeneous memory pooling, developed by the Tencent Astral Network
+Team. In Mooncake it is integrated as a transport backend of the TENT transfer framework and
+registered as `MPCOMM`; the library is shortened to MPComm throughout this document.
+
+- Upstream repository: <https://github.com/Tencent/UCL-MPComm>
+
+MPComm drives multiple RDMA NICs concurrently and performs two-level load balancing (across NICs
+and across QPs within a NIC), with NUMA-aware worker placement. It exposes one-sided
+`put`/`get` primitives that the transport maps onto TENT's `WRITE`/`READ` requests.
+
+At runtime, `TransferEngineImpl` loads MPComm Transport when `USE_MPCOMM` is enabled at build time
+and `transports/mpcomm/enable=true` is set in the configuration.
+
+> **TENT only.** This transport is implemented for the TENT runtime
+> (`mooncake-transfer-engine/tent/`) and is not available through the legacy Transfer Engine
+> transport path. Builds must therefore enable `USE_TENT` together with `USE_MPCOMM`, and
+> benchmarks must run with `--backend=tent`.
+
+### Code Structure
+
+The transport is split so that everything reaching MPComm goes through one interface. That keeps the
+provider out of most translation units, which is what makes the TENT-side logic buildable and
+testable without libmpcomm - the same arrangement `TpuPjrtShim` and `UrmaAdapter` use for their
+providers.
+
+| Unit | Responsibility | Needs `mpcomm.h` |
+|------|----------------|:----------------:|
+| `mpcomm_adapter.{h,cpp}` | The MPComm boundary. A thin pass-through: MPComm owns its slicing, NIC/QP selection and worker threads, so there is no scheduling to model here. Compiles to an unavailable stub when `USE_MPCOMM` is off | **yes** (only here) |
+| `mpcomm_peer_registry.{h,cpp}` | Peer cache and endpoint attribute parsing: which peers are connected, whose keys are current, and who may talk to a peer at any moment | no |
+| `mpcomm_task_mapping.{h,cpp}` | Request and completion mapping: WRITE/READ onto put/get, provider outcome onto `TransferStatus`, handle release | no |
+| `mpcomm_transport.{h,cpp}` | What needs the TENT runtime: resolving a `SegmentID` to a peer, reading the endpoint it advertises, driving batches, publishing capabilities | no |
+
+`MpcommTransport` also accepts an adapter through a second constructor, which is how tests
+substitute the provider.
+
+### Transfer Pipeline
+
+1. **Init**: `MPComm::init()` is called with the local segment name as the MPComm host id, the
+   RDMA device list derived from the TENT `Topology`, and a TCP port used for MPComm's own
+   metadata handshake. `startAcceptThread()` then serves incoming handshakes.
+2. **Advertisement**: the transport publishes `v1:<host>:<mpcomm_tcp_port>` into the local segment's
+   `transport_attrs` under the `MPCOMM` key, via `SegmentManager::updateLocal()` followed by
+   `synchronizeLocal()`. Peers read this to learn where to complete the MPComm handshake. The `v1:`
+   prefix makes a later format change detectable instead of silently misparsed; an attribute without
+   a prefix is read as `v1`. Only IPv4 endpoints are accepted.
+3. **Registration**: `addMemoryBuffer()` calls `registerMemory()` and `publishBuffer()` so the
+   buffer's rkeys become visible to peers. NUMA placement is auto-detected by MPComm.
+4. **Connection**: on the first request to a peer, `ensurePeerConnected()` resolves the peer's
+   MPComm endpoint from its `transport_attrs`, calls `connect()`, and then fetches the peer's
+   memory keys with `queryRemoteBuffer()`. Concurrent callers for the same peer wait for the first
+   one rather than starting a second handshake.
+
+   The cache is keyed by **MPComm host id** (the segment name), not by `SegmentID`, because that is
+   what MPComm keys connections by. Closing and reopening a segment yields a fresh `SegmentID` for
+   the same peer, and a second `connect()` to an already connected peer replaces its connection
+   record wholesale - discarding the keys it carries and leaking its queue pairs - so keying on the
+   `SegmentID` would reconnect a peer that is already connected.
+
+   For the same reason the connection and the keys are tracked separately. A connection cannot be
+   closed, so once established it is kept and reused; if only the key query failed, the peer is left
+   in `CONNECTED_NO_KEYS` and the next request retries **the query alone**. A connection that was
+   never established is not cached at all, so the next request retries the full handshake.
+
+   Keys are also refetched when the peer registers memory after they were fetched, which TENT
+   permits at any time. The transport compares the peer's currently published buffer ranges against
+   those the cached keys cover; a range that is not covered triggers a refresh. Unregistered ranges
+   do not, since a key for memory the peer no longer publishes is never used. Because segment
+   descriptors are cached per thread with a TTL, a newly registered buffer becomes visible only
+   after that TTL expires.
+5. **Execution**: `submitTransferTasks()` issues `putAsync()` for `WRITE` and `getAsync()` for
+   `READ`, one MPComm transfer per request. MPComm performs its own slicing and NIC/QP selection
+   internally.
+6. **Completion**: `getTransferStatus()` polls lazily with `isTransferComplete()`, then reads
+   `getTransferResult()` to obtain the error code and a byte count, and releases the handle. The
+   count is of bytes *posted*, which equals the request length once MPComm reports success; a
+   transfer reported as successful but short is demoted to failed rather than trusted.
+
+---
+
+## Additional Dependencies
+
+In addition to Mooncake's base dependencies, MPComm Transport requires the MPComm library:
+
+- **Header**: `${MPCOMM_ROOT}/include/mpcomm.h`
+- **Library**: `${MPCOMM_ROOT}/lib/libmpcomm.so`
+- **Version**: **1.4 or newer, and major version 1.** Configuration reads MPComm's CMake package
+  config and fails with an explicit message if the version is older or the major differs - MPComm
+  declares `SameMajorVersion` compatibility, so a different major is an ABI break by its own
+  definition. Both the standalone install and the wheel ship that config, and the resolved version
+  is printed as `MPComm version: <x.y.z>`. A prefix that has only the headers and the library copied
+  into it reports `unknown` instead, and the version is then not checked.
+
+Both are provided by an MPComm installation, which may come either from a standalone CMake install
+or from the MPComm Python wheel (in which case `MPCOMM_ROOT` is the `mpcomm` package directory
+inside `site-packages`, since the wheel ships `include/` and `lib/` under the package root).
+
+The two routes are not necessarily equivalent: MPComm gates several features behind build options
+that default to `OFF`, notably `USE_CUDA` (device memory support) and `USE_MLNX` (Mellanox-specific
+QP tuning that spreads traffic across ECMP paths, which affects multi-QP throughput). Its own
+`build.sh` turns them on, whereas a plain `pip install` does not. Check how the library you install
+was configured if device memory or multi-QP performance matters.
+
+Make sure `libmpcomm.so` can be found by the dynamic linker at run time, for example via
+`LD_LIBRARY_PATH`.
+
+### Wheel Packaging
+
+The `mooncake-transfer-engine` wheel **deliberately does not bundle MPComm**. `scripts/build_wheel.sh`
+passes `--exclude libmpcomm.so*` to `auditwheel repair`, so `engine.so` keeps its `DT_NEEDED` entry
+on `libmpcomm.so.<N>` and the library stays an external dependency resolved at run time. This keeps
+MPComm independently upgradable: replacing `libmpcomm.so` does not require rebuilding or repackaging
+Mooncake, as long as the MPComm major version (its `SOVERSION`) is unchanged. A major bump does
+require rebuilding Mooncake against the new headers.
+
+Consequently, importing the Python extension without MPComm available fails with:
+
+```
+ImportError: libmpcomm.so.1: cannot open shared object file: No such file or directory
+```
+
+Provide the library through either MPComm installation form, then point the linker at it:
+
+```bash
+# From the MPComm wheel
+export MPCOMM_ROOT=$(python3 -c "import mpcomm, os; print(os.path.dirname(mpcomm.__file__))")
+# ...or from a standalone CMake install, e.g. MPCOMM_ROOT=/opt/mpcomm
+
+export LD_LIBRARY_PATH=$MPCOMM_ROOT/lib:$LD_LIBRARY_PATH
+python3 -c "from mooncake import engine"   # should now import cleanly
+```
+
+---
+
+## Build and Compile
+
+**Prerequisites**
+
+- MPComm is installed, providing both `include/mpcomm.h` and `lib/libmpcomm.so`
+- RDMA devices are available and `libibverbs` is installed
+- Build environment can access Mooncake and its base dependencies
+
+**CMake Configuration**
+
+```bash
+# Clone Mooncake
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+
+# Enable TENT + MPComm. Add -DUSE_CUDA=ON if you need VRAM segments.
+mkdir build && cd build
+cmake .. -DUSE_TENT=ON -DUSE_MPCOMM=ON -DMPCOMM_ROOT=/opt/mpcomm
+
+# Build
+make -j$(nproc)
+```
+
+`MPCOMM_ROOT` is mandatory when `USE_MPCOMM=ON`. Configuration fails early if it is unset, or if
+the expected header and library cannot be found underneath it. On success the configure log
+reports the resolved paths:
+
+```
+-- MPComm transport is enabled
+--   MPComm include: /opt/mpcomm/include
+--   MPComm library: /opt/mpcomm/lib/libmpcomm.so
+```
+
+---
+
+## Enabling the Transport
+
+Loading the transport and selecting it for a transfer are two separate steps.
+
+**1. Load it.** The transport is only instantiated when its config gate is on:
+
+```json
+{ "transports": { "mpcomm": { "enable": true } } }
+```
+
+**2. Select it.** Any of the standard TENT mechanisms work:
+
+- A transport policy (see [Transport Selector](../../tent/transport-selector.md)):
+
+  ```json
+  {
+    "transports": { "mpcomm": { "enable": true } },
+    "policy": [
+      { "name": "mpcomm_memory", "segment_type": "memory", "transports": ["mpcomm"] }
+    ]
+  }
+  ```
+
+- A per-request override, which takes precedence over policies:
+
+  ```cpp
+  Request r{};
+  r.transport_hint = TransportType::MPCOMM;
+  ```
+
+A policy or a hint is effectively **required**. In the default ordering returned by
+`getSupportedTransports()`, `MPCOMM` comes second to last -- only `TPU` follows it -- so leaving
+the choice to the default means MPComm is unlikely to be picked at all.
+
+---
+
+## Run and Test
+
+`tebench` (the TENT benchmark, built at `build/mooncake-transfer-engine/benchmark/tebench`)
+supports `mpcomm` for connectivity and performance validation. The role is determined by
+`--target_seg_name`: empty means target, otherwise initiator.
+
+There is also a unit test, which is built when `USE_MPCOMM=ON` and unit tests are enabled. Its
+functional case needs RDMA devices and MPComm at run time and skips itself otherwise:
+
+```bash
+ctest -R tent_mpcomm_transport_test --output-on-failure
+```
+
+`--xport_type=mpcomm` selects the `MemoryOptions.type` used when registering buffers. It also
+restricts the enabled transports, but setting `MC_TENT_CONF` replaces the configuration wholesale
+and undoes that (see [Important Notes](#important-notes)), so the examples below list the
+`transports` gates explicitly. Keeping them in a shell variable avoids repeating the block:
+
+```bash
+XPORTS='"transports":{"mpcomm":{"enable":true},"rdma":{"enable":false},
+        "tcp":{"enable":false},"shm":{"enable":false},"nvlink":{"enable":false},
+        "mnnvl":{"enable":false},"gds":{"enable":false},"io_uring":{"enable":false}}'
+
+# Terminal 1: target
+MC_TENT_CONF="{\"rpc_server_hostname\":\"10.0.0.1\",$XPORTS}" \
+MPCOMM_TCP_PORT=13579 \
+./tebench --backend=tent --xport_type=mpcomm \
+  --metadata_type=p2p --rpc_server_port=12345 \
+  --seg_type=DRAM --total_buffer_size=2147483648
+
+# Terminal 2: initiator
+MC_TENT_CONF="{\"rpc_server_hostname\":\"10.0.0.2\",$XPORTS}" \
+MPCOMM_TCP_PORT=13579 \
+./tebench --backend=tent --xport_type=mpcomm --tent_transport_hint=mpcomm \
+  --metadata_type=p2p --rpc_server_port=12346 \
+  --target_seg_name=10.0.0.1:12345 \
+  --seg_type=DRAM --total_buffer_size=2147483648 \
+  --op_type=read --start_block_size=262144 --max_block_size=262144 \
+  --start_batch_size=32 --max_batch_size=32 \
+  --start_num_threads=4 --max_num_threads=4 --duration=30
+```
+
+Setting `rpc_server_hostname` is strongly recommended on multi-homed or containerized hosts; see
+[Important Notes](#important-notes). `--seg_name` is deliberately absent: with `metadata_type=p2p`
+TENT derives the local segment name from `rpc_server_hostname` and `rpc_server_port` and ignores
+the flag.
+
+**On a single host** both processes share the port namespace, so give them different handshake
+ports. Avoid the 15000-17000 range, which the TENT RPC server allocates from:
+
+```bash
+MPCOMM_TCP_PORT=13579 ...   # target
+MPCOMM_TCP_PORT=13580 ...   # initiator
+```
+
+To confirm that traffic really went over MPComm, look for these lines:
+
+```
+MpcommTransport: Installed successfully, host_id=10.0.0.2:12346, tcp_port=13579, devices=mlx5_0,mlx5_1
+MpcommTransport: Connected to segment 10.0.0.1:12345
+```
+
+If MPComm fails to start, the engine only logs `Transport mpcomm skipped: ...` and continues with
+the remaining transports. With every other transport disabled the run then fails later and less
+obviously, when buffer registration finds no usable transport.
+
+Add `--check_consistency=true` to verify payload correctness. It writes and reads every block back,
+so it changes the access pattern as well as lowering the reported bandwidth; leave it off when
+measuring throughput.
+
+### Unit Tests
+
+There are two suites, because the data path needs hardware and the logic around it does not.
+
+`tent_mpcomm_boundary_test` drives the transport against an injected `MpcommAdapter`, so it needs
+neither an RDMA device nor libmpcomm and is built in every configuration:
+
+```bash
+cmake .. -DUSE_TENT=ON -DBUILD_UNIT_TESTS=ON   # USE_MPCOMM not required
+make -j tent_mpcomm_boundary_test
+ctest -R tent_mpcomm_boundary_test --output-on-failure
+```
+
+It covers endpoint publication and parsing, single-flight connection under concurrency, key-query
+retry over an existing connection, refreshing keys when a peer registers memory, the WRITE/READ
+mapping, short-transfer and error handling, releasing each handle exactly once, and teardown. It does
+not cover MPComm's own behaviour - slicing, NIC and QP selection, worker scheduling - which is the
+provider's responsibility.
+
+`tent_mpcomm_transport_test` exercises the real data path: it forks a target, drives a WRITE followed
+by a READ over MPComm and verifies the payload. It requires RDMA devices and a working MPComm
+installation, and skips itself when the engine cannot be brought up:
+
+```bash
+cmake .. -DUSE_TENT=ON -DUSE_MPCOMM=ON -DBUILD_UNIT_TESTS=ON -DMPCOMM_ROOT=<prefix>
+make -j tent_mpcomm_transport_test
+ctest -R tent_mpcomm_transport_test --output-on-failure
+```
+
+Parent and child use distinct `MPCOMM_TCP_PORT` values derived from the pid, since MPComm's handshake
+listener would otherwise collide; see the note on port uniqueness above.
+
+---
+
+## Measured Performance
+
+Numbers from a two-node cross-machine run on **AMD Turin CPUs with 8x400 Gbps CX-7 NICs**, two NUMA
+nodes per host, transferring host DRAM. Utilisation is against the line rate of the NICs actually in
+use (400 Gbps = 50 GB/s each).
+
+| Layer | Workload | Bandwidth | NICs in use | Utilisation |
+|-------|----------|-----------|-------------|-------------|
+| Transfer Engine | `tebench`, READ | **392 GB/s** | 8 (2 NUMA) | 98% |
+| Transfer Engine | `tebench`, WRITE | **392 GB/s** | 8 (2 NUMA) | 98% |
+| Mooncake Store | `get_tensor_into` | **190 GB/s** | 4 (1 NUMA) | 95% |
+| Mooncake Store | `put_tensor_from` | **191 GB/s** | 4 (1 NUMA) | 95.5% |
+
+---
+
+## GPU (Device) Memory
+
+MPComm transfers device memory as well as host DRAM, so VRAM segments are supported in all four
+combinations (DRAM to DRAM, DRAM to GPU, GPU to DRAM, GPU to GPU).
+
+Three preconditions must all hold, and only the first one is checked at run time:
+
+1. **`nvidia-peermem` is loaded.** Device memory is registered through the ordinary `ibv_reg_mr`
+   path: the kernel's `get_user_pages()` is intercepted by `nvidia-peermem`
+   (`ib_peer_memory_client`) to pin GPU pages. There is no dma-buf fallback. This is the same
+   dependency `RdmaTransport` has for GPU-Direct.
+2. **MPComm itself was built with `-DUSE_CUDA=ON`.** That option defaults to `OFF`, and its device
+   detection is compiled out entirely when it is off, so device pointers are then registered as
+   host memory and NUMA/PCIe affinity selection silently degrades. The upstream `build.sh` enables
+   it; a plain `pip install` of the MPComm package does not.
+3. **Mooncake was built with `-DUSE_CUDA=ON`**, otherwise `--seg_type=VRAM` is rejected outright.
+
+The transport probes `/proc/modules` during `install()` and advertises the GPU capabilities only
+when `nvidia-peermem` is present. Otherwise it logs
+
+```
+MpcommTransport: nvidia_peermem not detected, GPU memory support is disabled
+```
+
+and reports `dram_to_dram` only, so transport selection will not route device memory to MPComm.
+Setting `transports/mpcomm/disable_gpu_direct_rdma` to `true` forces the same behaviour on a host
+that does have the module, which is reported separately:
+
+```
+MpcommTransport: GPU memory support disabled by transports/mpcomm/disable_gpu_direct_rdma
+```
+
+Note that conditions 2 and 3 are **not** detectable by that probe. If GPU transfers behave oddly
+while the module is loaded, confirm how MPComm was built.
+
+Buffer registration is attempted for every loaded transport irrespective of capabilities, so on a
+host without the module registering a VRAM buffer logs a warning from MPComm. That is harmless:
+the buffer simply does not list `MPCOMM` among its transports, and selection skips it.
+
+To exercise device memory with `tebench`, pass `--seg_type=VRAM` on either or both sides, or
+`--seg_type_mix=dram,vram` to drive both memory types from a single process:
+
+```bash
+./tebench --backend=tent --xport_type=mpcomm --seg_type=VRAM ...
+```
+
+---
+
+## Environment Variables
+
+MPComm reads its own tuning parameters directly from the environment. The transport adds the two
+`*_TCP_PORT` variables.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MPCOMM_TCP_PORT` | Local TCP port for MPComm's metadata handshake. Must be unique per process on a host: MPComm binds it and fails to initialise if it is taken, with no retry. `0` does not mean "pick one". The value is validated, and a non-numeric or out-of-range one fails `install()` rather than being silently treated as `0`. This port hands out remote memory keys - see [Security and Trust Boundary](#security-and-trust-boundary) | `13579` |
+| `MPCOMM_REMOTE_TCP_PORT` | Peer handshake port, used only when the peer published no `transport_attrs`. Without it such a peer is rejected: the attribute is written by `install()`, so its absence means the peer runs no MPComm transport, and guessing a port would point `connect()` at an unrelated process - which, since the handshake has no timeout, can block the submitting thread indefinitely | (none; peer is rejected) |
+| `MPCOMM_GID_INDEX` | RoCE/IB GID index used when creating QPs. Devices whose GID at this index is all zeroes are skipped, which can leave MPComm reporting no usable devices. Use `-1` to pick the first non-zero GID | `3` |
+| `MPCOMM_NIC_FILTER` | Comma-separated list of allowed RDMA device names. When unset, the transport passes the device list derived from the TENT `Topology`; setting this variable overrides that list | (TENT topology) |
+| `MPCOMM_MAX_RDMA_TRANSFER_SIZE` | Maximum bytes per RDMA operation; larger requests are sliced across NICs | `1 GB` |
+| `MPCOMM_QPS_PER_CONNECTION` | Number of QPs per NIC per connection. Values above 16 make initialisation fail | `1` |
+| `MPCOMM_POLL_BATCH_SIZE` | Maximum work completions per `ibv_poll_cq` call | `64` |
+| `MPCOMM_MAX_IDLE_SPINS` | Number of idle polling iterations a worker spins (with a CPU pause hint) before backing off | `10000` |
+| `MPCOMM_MAX_SEND_WR` | QP send queue depth | `512` |
+| `MPCOMM_MAX_OUTSTANDING_PER_QP` | Maximum outstanding work requests per QP | `256` |
+| `MPCOMM_LOG_LEVEL` | `error` / `warn` / `info` / `debug` | `info` |
+| `MPCOMM_TRANSFER_STATS_INTERVAL` | Print statistics every N transfers (requires `debug`) | `0` (every transfer) |
+
+---
+
+## Configuration Options (TENT)
+
+- `transports/mpcomm/enable`: enable or disable the transport (default: `true` once
+  `USE_MPCOMM` is compiled in)
+- `transports/mpcomm/disable_gpu_direct_rdma`: force the GPU capabilities off even when
+  `nvidia-peermem` is loaded (default: `false`). See [GPU (Device) Memory](#gpu-device-memory).
+
+MPComm's own behaviour is tuned through the environment variables above rather than through TENT
+configuration keys.
+
+---
+
+## Important Notes
+
+1. **TENT only.** There is no MPComm backend on the legacy Transfer Engine transport path, so
+   `--backend=classic` and `transfer_engine_bench --protocol=mpcomm` are not supported.
+
+2. **Set `rpc_server_hostname` on multi-homed or containerized hosts.** With
+   `metadata_type=p2p`, TENT overwrites `local_segment_name` with `rpc_server_hostname:port`. When
+   `rpc_server_hostname` is unset it is auto-discovered, which may pick an address that peers
+   cannot route to (for example a container overlay address). Since the published
+   `transport_attrs` are derived from that name, MPComm would then advertise an unreachable
+   endpoint. `tebench` has no command-line flag for it, so pass it through `MC_TENT_CONF`.
+
+3. **`MC_TENT_CONF` replaces the configuration wholesale.** Keys other than the metadata identity
+   (`metadata_type`, `metadata_servers`, `local_segment_name`, `rpc_server_hostname`,
+   `rpc_server_port`) are not preserved across the load. If you set `MC_TENT_CONF` *and* rely on
+   `--xport_type` to disable the other transports, list the `transports` gates explicitly in
+   `MC_TENT_CONF` as well, otherwise they revert to their defaults.
+
+4. **Segment metadata mutation.** The transport publishes its endpoint through
+   `SegmentManager::updateLocal()`. Snapshots returned by `getLocal()` are copy-on-write and must
+   never be written through.
+
+5. **Buffer registration cost.** `registerMemory()` pins and maps memory on every NIC, so
+   registration of large buffers takes noticeable time at startup. Register once and reuse.
+
+6. **Optional transport interfaces are not implemented.** MPComm Transport does not provide
+   cancellation (`supportsCancellation()` returns `false`), notification
+   (`supportNotification()` returns `false`, so `tebench --notifi` is unavailable), bandwidth
+   estimation, or NIC load statistics, and it does not consume the `qp_pool` or
+   progress-notification facilities of `Transport::SubBatch`. Failover and QoS features that
+   depend on those hooks fall back to their defaults.
+
+7. **The first transfer to a peer performs the MPComm handshake inline.** Connection setup happens
+   on the submitting thread the first time a segment is used, so that submission takes noticeably
+   longer than subsequent ones.
+
+---
+
+## Security and Trust Boundary
+
+MPComm's metadata handshake is a plain TCP exchange with **no authentication and no encryption**,
+and what it exchanges is remote memory metadata:
+
+```c++
+struct RemoteBufferEntry {
+    uint64_t addr;
+    uint64_t length;
+    int numa_node;
+    std::vector<uint32_t> rkeys;   // <- remote keys
+};
+```
+
+An address together with its rkey is exactly what an RDMA READ or WRITE needs. Anything that can
+reach `MPCOMM_TCP_PORT` can therefore obtain the means to read and write the process's registered
+memory directly, without going through TENT at all.
+
+**Treat that port as being at the same trust level as the RDMA fabric itself.** In practice:
+
+- Keep it on the same trusted network as the fabric, and do not expose it to untrusted networks or
+  to the internet. Restrict it with host firewall rules if the host also carries untrusted traffic.
+- Registered buffers are reachable by any peer that completes the handshake. There is no per-peer
+  authorisation, and no per-buffer permission model beyond what the fabric enforces.
+- This is the same exposure model as raw RDMA between trusted nodes; MPComm adds no protection of
+  its own and does not weaken the fabric's either.
+
+### Addressing
+
+- **Only IPv4 endpoints are supported.** The handshake sockets are `AF_INET`, and the endpoint
+  attribute is parsed as `<ipv4>:<port>`; an IPv6 literal is rejected at parse time rather than
+  being silently split at the wrong colon.
+- **The listener binds all interfaces** (`INADDR_ANY`) and this is not configurable - it is
+  MPComm's own behaviour. Use firewall rules to restrict which interfaces are actually reachable.
+- **The advertised address follows `rpc_server_hostname`**, since the endpoint attribute is derived
+  from the local segment name. On a multi-homed host this ties the handshake path to whichever
+  address TENT uses for RPC. Setting `rpc_server_hostname` explicitly is therefore the way to
+  control it today; a dedicated setting for advertising an address separate from the RPC one is not
+  implemented yet.
+
+---
+
+## Troubleshooting
+
+### Configuration fails with a missing `MPCOMM_ROOT`
+
+```
+USE_MPCOMM=ON requires MPCOMM_ROOT to point at the MPComm install prefix
+```
+
+Pass `-DMPCOMM_ROOT=<prefix>`. The prefix must contain `include/mpcomm.h` and
+`lib/libmpcomm.so` (`lib64` is searched as well).
+
+### Configuration fails with MPComm not found
+
+```
+MPComm not found under MPCOMM_ROOT=<prefix>
+```
+
+Verify the layout, and remember that CMake caches find results:
+
+```bash
+ls $MPCOMM_ROOT/include/mpcomm.h $MPCOMM_ROOT/lib/libmpcomm.so
+cmake .. -UMPCOMM_LIBRARY -UMPCOMM_INCLUDE_DIR
+```
+
+### `error while loading shared libraries: libmpcomm.so`
+
+The library is resolved by absolute path at link time, but the dynamic linker still needs to find
+it at run time:
+
+```bash
+export LD_LIBRARY_PATH=$MPCOMM_ROOT/lib:$LD_LIBRARY_PATH
+ldd ./tebench | grep -E "mpcomm|not found"
+```
+
+### The peer connects to an unexpected address
+
+Symptom: the initiator logs `MPComm: Connecting to <host_id> at <ip>:<port>` with an address peers
+cannot reach, and stalls, while the segment itself was opened successfully.
+
+The address MPComm uses comes from the peer's segment name and `transport_attrs`, which are
+derived from `rpc_server_hostname`. Set it explicitly on **both** sides, then confirm the target
+advertises the intended address:
+
+```
+MpcommTransport: Installed successfully, host_id=<expected-ip>:<port>, ...
+```
+
+### `MPComm: No RDMA devices found`
+
+MPComm skips any device whose GID at `MPCOMM_GID_INDEX` (default `3`) is all zeroes, which is
+common on InfiniBand and on RoCE setups with a different GID layout. Set `MPCOMM_GID_INDEX=-1` to
+pick the first non-zero GID, or point it at the correct index.
+
+### `Failed to query remote buffers`
+
+```
+MpcommTransport: Failed to query remote buffers from <host>, error=<code>
+```
+
+The connection succeeded but fetching the peer's memory keys did not. Those keys are the only way
+to address the peer's memory, so this is a hard failure and the request fails.
+
+The connection itself is kept - MPComm cannot close one, and reconnecting would replace its
+connection record and leak its queue pairs - so the peer is left in `CONNECTED_NO_KEYS` and the
+next request retries **only the query**, not the handshake.
+
+The usual cause is that the peer had not finished registering its buffers yet, so start the target
+and let it finish registration before starting the initiator. Since the retry is a query, the
+recovery needs no restart on either side.
+
+### Lower than expected bandwidth
+
+- Remove `--check_consistency=true`; it writes and reads every block back.
+- Increase `--duration`; the inline handshake on the first transfer to a peer is included in the
+  measurement.
+- Increase `--start_batch_size` / `--max_batch_size`; with a batch size of 1 there are not enough
+  in-flight requests to fill `MPCOMM_MAX_OUTSTANDING_PER_QP`.
+- Check `MPCOMM_MAX_RDMA_TRANSFER_SIZE` against the block size. Slicing is what spreads a transfer
+  over several NICs, so a request smaller than this limit becomes a single chunk on a single NIC.
+  Lower it to engage more NICs per request.
+- For `--seg_type=DRAM`, `tebench` allocates one buffer of `--total_buffer_size` per NUMA node.
+  Restricting memory to a single node with `numactl --membind` while NICs on another node drive
+  traffic results in cross-socket access.
diff --git a/docs/source/design/transfer-engine/sunrise_link_transport.md b/docs/source/design/transfer-engine/transport/sunrise_link_transport.md
similarity index 100%
rename from docs/source/design/transfer-engine/sunrise_link_transport.md
rename to docs/source/design/transfer-engine/transport/sunrise_link_transport.md
diff --git a/docs/source/design/unified-parallel-tensor-io.md b/docs/source/design/unified-parallel-tensor-io.md
deleted file mode 100644
index ff9f1f3b40..0000000000
--- a/docs/source/design/unified-parallel-tensor-io.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# Unified Parallel Tensor IO
-
-## Goal
-
-This document defines the single source of truth for Mooncake's next-generation tensor IO API. The purpose is to keep implementation aligned around one explicit design and avoid drifting into ad hoc TP/EP/DP/PP-specific interfaces.
-
-The target outcome is:
-
-- one unified write API family
-- one unified read API family
-- one unified upsert API family
-- TP-specific APIs retained only as compatibility wrappers
-- minimal caller-facing inputs, with layout and planning details derived internally
-- one stable abstraction that can cover TP / DP / EP / PP combinations without exploding the public API surface
-
-## Design principles
-
-1. **One API family, not one family per parallelism type.**
-   Public APIs should not branch into separate long-term `*_with_tp`, `*_with_ep`, `*_with_pp`, and `*_with_dp` families.
-2. **Parallelism is modeled as explicit axes.**
-   `mixed` must not be a vague enum value. A shard should be described by the exact axis coordinates that identify it.
-3. **Reads must encode caller intent explicitly.**
-   A read request must say whether the caller wants the stored view, a target shard/view, or the reconstructed full tensor.
-4. **Only require true caller intent.**
-   If Mooncake can derive a field from the input tensor, stored metadata, or planning context, it should not be required in the public API.
-5. **Planner/runtime complexity stays internal.**
-   Byte ranges, payload offsets, reconstruction plans, and lowering to `get_into_ranges(...)` are runtime concerns, not public API concerns.
-6. **Compatibility wrappers stay thin.**
-   Existing TP methods should lower to the same unified implementation path.
-
-## Core model
-
-### Parallelism is an axis list
-
-A tensor object may be identified by one axis or by multiple orthogonal axes.
-
-Examples:
-
-- pure TP shard: `[TP]`
-- DP + TP shard: `[DP, TP]`
-- PP + TP shard: `[PP, TP]`
-- DP + PP + TP shard: `[DP, PP, TP]`
-- DP + PP + EP + TP shard: `[DP, PP, EP, TP]`
-
-So the design should not use:
-
-```python
-kind = "mixed"
-```
-
-Instead it should use:
-
-```python
-class ParallelAxis:
-    kind: Literal["tp", "dp", "ep", "pp"]
-    rank: int
-    size: int
-    split_dim: Optional[int] = None
-    expert_id: Optional[int] = None
-    stage_id: Optional[int] = None
-```
-
-```python
-class TensorParallelism:
-    axes: list[ParallelAxis]
-```
-
-Single-axis cases are just special cases of this model:
-
-- TP only: `axes=[TP(...)]`
-- EP only: `axes=[EP(...)]`
-- PP + TP: `axes=[PP(...), TP(...)]`
-
-## Public API shape
-
-### Write / upsert side
-
-```python
-def put_tensor_with_parallelism(
-    self,
-    key: str,
-    tensor: torch.Tensor,
-    parallelism: TensorParallelism | None = None,
-    replica: ReplicateConfig | None = None,
-) -> int
-```
-
-```python
-def batch_put_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    tensors: list[torch.Tensor],
-    parallelisms: list[TensorParallelism | None] | None = None,
-    replica: ReplicateConfig | None = None,
-) -> list[int]
-```
-
-```python
-def upsert_tensor_with_parallelism(
-    self,
-    key: str,
-    tensor: torch.Tensor,
-    parallelism: TensorParallelism | None = None,
-    replica: ReplicateConfig | None = None,
-) -> int
-```
-
-```python
-def batch_upsert_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    tensors: list[torch.Tensor],
-    parallelisms: list[TensorParallelism | None] | None = None,
-    replica: ReplicateConfig | None = None,
-) -> list[int]
-```
-
-### Read side
-
-Read-side requests need one extra structure because the request must encode not only the target parallel coordinates, but also the materialization mode.
-
-```python
-class ReadTarget:
-    mode: Literal["as_stored", "shard", "full"]
-    parallelism: TensorParallelism | None = None
-```
-
-```python
-def get_tensor_with_parallelism(
-    self,
-    key: str,
-    target: ReadTarget | None = None,
-) -> torch.Tensor
-```
-
-```python
-def batch_get_tensor_with_parallelism(
-    self,
-    keys: list[str],
-    targets: list[ReadTarget | None] | None = None,
-) -> list[torch.Tensor]
-```
-
-Optional zero-copy forms follow the same model:
-
-```python
-def get_tensor_with_parallelism_into(
-    self,
-    key: str,
-    buffer_ptr: int,
-    size: int,
-    target: ReadTarget | None = None,
-) -> torch.Tensor
-```
-
-```python
-def batch_get_tensor_with_parallelism_into(
-    self,
-    keys: list[str],
-    buffer_ptrs: list[int],
-    sizes: list[int],
-    targets: list[ReadTarget | None] | None = None,
-) -> list[torch.Tensor]
-```
-
-## Caller inputs vs internal derived fields
-
-### Caller must provide
-
-These are true caller intent and belong in the public API:
-
-- the tensor itself
-- whether the write target is full or shard-like
-- the shard identity axes when writing a shard object
-- the read target mode: `as_stored`, `shard`, or `full`
-- the target axis coordinates when requesting a target shard/view
-- `ReplicateConfig` when the caller wants replication / publish-like behavior
-
-### Mooncake should derive internally
-
-These should not be mandatory public inputs when they are derivable:
-
-- logical shape
-- local shard shape
-- metadata encoding/version details
-- payload offsets
-- source and destination byte ranges
-- reconstruction plans
-- lowering to `get_into_ranges(...)`
-
-## Why `ReadTarget` is required
-
-`parallelism` alone is not enough to describe a read.
-
-For example, if a tensor is stored as TP shards, a request that carries TP axis coordinates is ambiguous unless it also says whether the caller wants:
-
-- the stored local shard
-- a target shard/view
-- the reconstructed full tensor
-
-So reads must explicitly encode:
-
-```python
-ReadTarget(mode="as_stored")
-ReadTarget(mode="shard", parallelism=...)
-ReadTarget(mode="full")
-```
-
-This distinction must not be guessed from the axis metadata.
-
-## Mixed-parallel scenarios in training and inference
-
-`mixed` is not a mode. It means the shard identity needs more than one axis coordinate to be uniquely described.
-
-### Scenario table
-
-| Scenario | Typical axis list | Meaning |
-|---|---|---|
-| TP training | `[TP]` | one TP slice of a logical tensor |
-| DP + TP training | `[DP, TP]` | one TP slice within one DP replica/group |
-| PP + TP training | `[PP, TP]` | one TP slice owned by one pipeline stage |
-| DP + PP + TP training | `[DP, PP, TP]` | one TP slice in one stage in one DP replica |
-| DP + PP + EP + TP training | `[DP, PP, EP, TP]` | one expert-local TP slice in one stage and one DP replica |
-| TP inference | `[TP]` | one TP slice used by one inference rank |
-| PP + TP inference | `[PP, TP]` | one TP slice owned by one inference pipeline stage |
-| EP inference | `[EP]` or `[EP, TP]` | one expert shard, optionally further TP-sliced |
-| multi-replica serving inference | `[DP, TP]` or `[DP, PP, TP]` | one shard scoped to a serving replica plus model-parallel axes |
-
-### Important distinctions
-
-- TP and EP often affect the tensor's physical layout directly.
-- PP and serving-replica / DP often act more like ownership or scope tags, even when they do not themselves change the byte layout inside the local shard.
-
-## Write-side matrix
-
-The unified write family should be driven by the identity of the object being written, not by method-name proliferation.
-
-| Caller holds | Wants to store | API | Required `parallelism` |
-|---|---|---|---|
-| full tensor | full tensor | `put_tensor_with_parallelism(..., parallelism=None)` | none |
-| full tensor | TP shard | `put_tensor_with_parallelism(...)` | `axes=[TP(rank,size,split_dim)]` |
-| full tensor | DP-scoped shard/replica | `put_tensor_with_parallelism(...)` | `axes=[DP(rank,size)]` plus layout axis if actually sharded |
-| full tensor | EP shard | `put_tensor_with_parallelism(...)` | `axes=[EP(rank,size,expert_id)]` plus `split_dim` if needed |
-| full tensor | PP stage shard | `put_tensor_with_parallelism(...)` | `axes=[PP(rank,size,stage_id)]` |
-| full tensor | combined shard | `put_tensor_with_parallelism(...)` | explicit axis list such as `[PP(...), TP(...)]` |
-| shard tensor | shard object | `put_tensor_with_parallelism(...)` | explicit axis list describing that shard identity |
-
-For TP-containing **multi-axis** layouts, the write semantic is now: the caller may pass the **full source tensor**, and the provided TP rank/layout tells Mooncake which uniform shard to materialize and persist. Callers no longer need to pre-split the tensor themselves for `dp_tp` / `pp_tp` / `ep_tp` style writes.
-
-Single-axis TP compatibility wrappers and the preserved plain-TP `with_parallelism` behavior still accept shard input rather than auto-materializing from a full tensor.
-
-Pure DP still does not invent a split axis on its own. If the stored object is actually sharded, the request must still include the layout axis that defines the shard shape.
-
-The same matrix applies to `upsert_tensor_with_parallelism(...)`.
-
-## Read-side matrix
-
-The unified read family should be driven by `ReadTarget`.
-
-| Stored layout | Caller wants | API | `ReadTarget` |
-|---|---|---|---|
-| full tensor | stored full tensor | `get_tensor_with_parallelism(...)` | `None` or `mode="as_stored"` |
-| TP shard object | stored shard | `get_tensor_with_parallelism(...)` | `mode="as_stored"` |
-| TP shard set | target TP shard | `get_tensor_with_parallelism(...)` | `mode="shard", parallelism=TP(...)` |
-| TP shard set | full tensor | `get_tensor_with_parallelism(...)` | `mode="full"` |
-| EP shard set | target expert shard | `get_tensor_with_parallelism(...)` | `mode="shard", parallelism=EP(...)` |
-| EP shard set | full tensor | `get_tensor_with_parallelism(...)` | `mode="full"` |
-| PP + TP shard set | target PP+TP shard | `get_tensor_with_parallelism(...)` | `mode="shard", parallelism=[PP(...), TP(...)]` |
-| mixed shard set | full tensor | `get_tensor_with_parallelism(...)` | `mode="full"` |
-
-## Source-layout to target-layout matrix
-
-The planner must eventually cover these conversions, but the public API should remain the same across all of them.
-
-| Stored source layout | Requested target layout | Support model |
-|---|---|---|
-| TP | TP | direct shard fetch or shard-local fast path |
-| TP | full | reconstruct full tensor |
-| TP | EP / PP / DP / mixed | planner-driven remap |
-| EP | EP | direct shard fetch or shard-local fast path |
-| EP | full | reconstruct full tensor |
-| EP | TP / PP / DP / mixed | planner-driven remap |
-| PP | PP | direct shard fetch |
-| PP | full | reconstruct full tensor when meaningful |
-| PP | TP / EP / DP / mixed | planner-driven remap |
-| mixed | mixed | direct fetch if exact match, else planner-driven remap |
-| mixed | full | reconstruct full tensor |
-| mixed | TP / EP / PP / DP | planner-driven remap |
-
-The important point is that these combinations must not create public API explosion.
-
-## Compatibility wrappers
-
-Existing TP APIs remain compatibility wrappers.
-
-Conceptually:
-
-```python
-put_tensor_with_tp(key, tensor, tp_rank, tp_size, split_dim)
-```
-
-lowers to:
-
-```python
-put_tensor_with_parallelism(
-    key,
-    tensor,
-    TensorParallelism(axes=[TP(rank=tp_rank, size=tp_size, split_dim=split_dim)]),
-)
-```
-
-and:
-
-```python
-get_tensor_with_tp(key, tp_rank, tp_size, split_dim)
-```
-
-lowers to:
-
-```python
-get_tensor_with_parallelism(
-    key,
-    ReadTarget(
-        mode="shard",
-        parallelism=TensorParallelism(
-            axes=[TP(rank=tp_rank, size=tp_size, split_dim=split_dim)]
-        ),
-    ),
-)
-```
-
-Existing TP behavior stays stable, but implementation should flow through the unified path.
-
-## Runtime lowering direction
-
-Internally, reads should be planner-driven.
-
-When a request can be lowered to explicit:
-
-- key
-- src offset
-- dst offset
-- size
-
-ranges, the runtime should reuse `get_into_ranges(...)` to assemble the result directly into the output buffer.
-
-Otherwise it can fall back to the simpler whole-object path.
-
-This keeps the public interface stable while allowing future planner work to add DP / TP / EP / PP remapping and optimized reconstruction without another API redesign.
-
-## Current implementation status
-
-The current `store_py.cpp` implementation now reflects the main shape of this design:
-
-- unified write APIs are exposed as `put_tensor_with_parallelism(...)` and `batch_put_tensor_with_parallelism(...)`
-- unified read APIs are exposed as `get_tensor_with_parallelism(...)` and `batch_get_tensor_with_parallelism(...)`
-- unified upsert APIs are exposed as `upsert_tensor_with_parallelism(...)` and `batch_upsert_tensor_with_parallelism(...)`
-- zero-copy `_into` and `_from` variants exist for the unified API family
-- TP-specific APIs remain available as compatibility wrappers and should not be treated as the long-term surface area
-
-### Implemented write-side convenience: `writer_partitions`
-
-Batch write and batch upsert paths also support `writer_partitions` as a convenience input for full tensors that should be written as stored shards.
-
-This is intentionally narrower than the full `TensorParallelism` model:
-
-- it is a write-side convenience, not a replacement for `TensorParallelism`
-- it is primarily for batch full-tensor writes where the caller already knows rank / size / split_dim per item
-- it should not change the unified read-side abstraction
-
-`writer_partitions` remains a separate explicit route. The newer TP-containing `parallelism` write semantic now overlaps with it for the common case of “full tensor in, store one requested shard”, but `writer_partitions` is still useful when the caller wants a lighter write-side request shape without constructing `TensorParallelism` objects.
-
-### Implemented read-side behavior
-
-Read-side support includes:
-
-- returning the stored local object (`mode="as_stored"`)
-- returning a target shard (`mode="shard"`)
-- reconstructing the full tensor (`mode="full"`)
-- lowering reconstruction-oriented paths onto existing runtime helpers such as `get_into_ranges(...)` where appropriate
-
-### Compatibility boundary
-
-The project should continue to preserve this boundary:
-
-- keep old TP APIs functional
-- keep them thin
-- do not expand the old TP-specific family as the primary interface
-- document and evolve the unified `*_with_parallelism` family instead
-
-## Scope still intentionally limited
-
-This document describes the stable public API direction, but not every theoretical source-layout to target-layout remap is fully implemented.
-
-In particular, the design should continue to avoid over-promising planner coverage for arbitrary remaps across all DP / TP / EP / PP combinations until those paths are explicitly implemented and tested.
-
-The safe documented contract today is:
-
-1. define the public API structures and signatures clearly
-2. align `store_py.cpp` with `axes + ReadTarget`
-3. keep TP wrappers working by lowering into the unified path
-4. do not introduce a new long-term `kind="mixed"` model
-5. do not push planner internals such as byte ranges and derived shapes into public arguments
-6. do not expand into many parallelism-specific public methods
-7. reuse existing runtime helpers like `get_into_ranges(...)` rather than inventing a parallel reconstruction path from scratch
diff --git a/docs/source/getting_started/build.md b/docs/source/getting_started/build.md
index bab4632376..de9f4a20f7 100644
--- a/docs/source/getting_started/build.md
+++ b/docs/source/getting_started/build.md
@@ -13,7 +13,7 @@ This document describes how to build Mooncake.
 
 Install common build dependencies first. A stable Internet connection is
 required because the script installs system packages, initializes submodules,
-installs Go, and builds/installs yalantinglibs.
+and installs Go.
 
 ```bash
 sudo bash dependencies.sh
@@ -31,11 +31,11 @@ sudo make install
 
 ### Build with VRAM Segment
 
-To enable VRAM Segment, install CUDA toolkit and build Mooncake with 
+To enable VRAM Segment, install CUDA toolkit and build Mooncake with
 `USE_VRAM_SEGMENT` enabled:
 
 ```bash
-sudo bash dependencies.sh 
+sudo bash dependencies.sh
 
 mkdir build
 cd build
@@ -44,7 +44,7 @@ make -j
 sudo make install
 ```
 
-If NVLink is available in your environment, you can also enable it 
+If NVLink is available in your environment, you can also enable it
 with `-DUSE_INTRA_NVLINK=ON`:
 
 ```bash
@@ -75,6 +75,38 @@ sudo make install
 `-DUSE_NOF=ON` builds the NoF registration APIs and deployment tools. Use
 `-DUSE_NOF=OFF` or omit the option when the NVMe-oF SSD pool is not needed.
 
+### RISC-V Build
+
+Mooncake supports native 64-bit RISC-V Linux builds with `USE_RISCV` enabled.
+The option keeps regular Release optimizations but disables interprocedural
+optimization for the Python extensions, avoiding the excessive memory use of
+full GNU LTO on RISC-V build hosts. The build also detects whether 16-byte
+atomic operations require `libatomic` and links it automatically.
+
+The following configuration builds the C++, Python, and Rust components while
+disabling every component that requires Go:
+
+```bash
+mkdir build-riscv
+cd build-riscv
+cmake -G Ninja .. \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DUSE_RISCV=ON \
+  -DWITH_STORE_GO=OFF \
+  -DWITH_P2P_STORE=OFF \
+  -DUSE_ETCD=OFF \
+  -DSTORE_USE_ETCD=OFF \
+  -DSTORE_USE_K8S_LEASE=OFF \
+  -DBUILD_UNIT_TESTS=OFF \
+  -DBUILD_EXAMPLES=OFF \
+  -DBUILD_BENCHMARK=OFF
+cmake --build . --parallel 4
+```
+
+Adjust the parallel job count for the available memory. The example uses four
+jobs because optimized C++ and Python binding translation units can each need
+several gigabytes of memory on RISC-V.
+
 ### Hardware Backend Setup
 
 Run `sudo bash dependencies.sh` before using any of these backend-specific build
@@ -84,7 +116,7 @@ environment setup must be prepared separately.
 | Hardware / backend | Build option | External SDK / setup | Environment and notes |
 | --- | --- | --- | --- |
 | NVIDIA CUDA / GPUDirect | `-DUSE_CUDA=ON` | Install CUDA 12.1+ and enable `nvidia-fs` for cuFile builds. | Add CUDA libraries to `LIBRARY_PATH` and `LD_LIBRARY_PATH`, for example `/usr/local/cuda/lib64`. |
-| NVIDIA NCCL DeviceTransport | `-DUSE_NCCL_DEVICE=ON` | Install NCCL 2.30.4+ with `nccl_device.h`. Requires CUDA. | Set `NCCL_ROOT` when NCCL is outside the standard search paths. NCCL Device API device code must be rebuilt or re-JITed with headers that exactly match the runtime `libnccl`. |
+| NVIDIA NCCL DeviceTransport | `-DUSE_NCCL_DEVICE=ON` | Install NCCL 2.30.4+ with `nccl_device.h`. Requires CUDA. | Disabled by default. Enabling it directly links NCCL into the EP extensions, so importing `mooncake.ep` requires a matching runtime `libnccl` even when the NCCL transport is not selected. Set `NCCL_ROOT` when NCCL is outside the standard search paths. |
 | NVIDIA NCCL host RMA (WRITE only) | `-DUSE_NCCL_HOST=ON` | Install NCCL 2.30.4+. Requires CUDA. | Set `NCCL_ROOT` when NCCL is outside the standard search paths. Install NCCL as the only transport in a `TransferEngine(false)` instance before registering buffers. Peers must register matching buffer sizes in the same order. It has no multi-transport fallback and supports WRITE requests only because NCCL 2.30 has no public host Get operation. |
 | NVIDIA Multi-Node NVLink | `-DUSE_MNNVL=ON` | Requires CUDA. | Also set `-DUSE_CUDA=ON`. Not used with MUSA, HIP, or MACA builds. |
 | Moore Threads MUSA | `-DUSE_MUSA=ON` | Install MUSA SDK and `mthreads-peermem` for GPUDirect RDMA. | Add `/usr/local/musa/lib` to `LIBRARY_PATH` and `LD_LIBRARY_PATH`. |
@@ -94,6 +126,7 @@ environment setup must be prepared separately.
 | Huawei Ascend UBSHMEM | `-DUSE_UBSHMEM=ON` | Install Ascend CANN Toolkit. Requires CANN >= 9.0.0, driver >= 26.0.0, Lingqu >= 1.5. | Source the CANN `set_env.sh` before configuring CMake. |
 | AMD HIP / ROCm | `-DUSE_HIP=ON` | Install ROCm/HIP SDK. | Ensure HIP compiler, headers, and runtime libraries are visible to CMake. |
 | Hygon DCU | `-DUSE_HYGON=ON` | Install DTK SDK. | Set `DTK_HOME`, or pass `-DDTK_ROOT=/path/to/dtk`. Use `-DDTK_INCLUDE_DIR` and `-DDTK_LIB_DIR` for custom layouts. |
+| ScaleFabric SHCA | `-DUSE_SHCA=ON` | Install `shca-tools`. | Supports Transfer Engine/TENT RDMA paths only; Mooncake-EP IBGDA is not supported. `MC_RPC_PROTOCOL=rdma` is not supported on SHCA builds; Store/RPC should use TCP. |
 | Iluvatar CoreX | `-DUSE_COREX=ON` | Install CoreX SDK. | Set `COREX_HOME`, or pass `-DCOREX_ROOT=/path/to/corex`. Use `-DCOREX_INCLUDE_DIR` and `-DCOREX_LIB_DIR` for custom layouts. |
 
 ```{admonition} NCCL host RMA constraints
@@ -197,7 +230,7 @@ The following options can be passed to `cmake ..`.
 | Option | Default | Description |
 | --- | --- | --- |
 | `-DUSE_CUDA=ON/OFF` | `OFF` | Enable GPU memory support, including GPUDirect RDMA, NVMe-oF, and GPU-aware TCP transport. Required when transferring GPU memory, even when using TCP. |
-| `-DUSE_NCCL_DEVICE=ON/OFF` | `OFF` | Enable the experimental NCCL DeviceTransport backend. Requires CUDA and NCCL 2.30.4+; AOT- and JIT-compiled NCCL device code must use headers that exactly match the runtime `libnccl`. |
+| `-DUSE_NCCL_DEVICE=ON/OFF` | `OFF` | Enable the NCCL DeviceTransport backend. Requires CUDA and NCCL 2.30.4+ with `nccl_device.h`. NCCL-enabled EP extensions require a matching runtime `libnccl` at import time, and AOT- and JIT-compiled NCCL device code must use headers that exactly match that runtime. |
 | `-DUSE_NCCL_HOST=ON/OFF` | `OFF` | Enable the experimental, WRITE-only NCCL host RMA transport. Requires CUDA and NCCL 2.30.4+, must be installed before its buffers are registered, and must be the engine's only installed transport. |
 | `-DUSE_MNNVL=ON/OFF` | `OFF` | Enable Multi-Node NVLink transport. Requires `-DUSE_CUDA=ON`; not used with MUSA, HIP, or MACA builds. |
 | `-DUSE_MUSA=ON/OFF` | `OFF` | Enable Moore Threads GPU support via MUSA. |
@@ -206,11 +239,14 @@ The following options can be passed to `cmake ..`.
 | `-DUSE_HYGON=ON/OFF` | `OFF` | Enable Hygon DCU support via DTK SDK. Uses a CUDA-compatible runtime. |
 | `-DUSE_COREX=ON/OFF` | `OFF` | Enable Iluvatar CoreX GPU support. Uses a CUDA-compatible runtime. |
 | `-DUSE_MLU=ON/OFF` | `OFF` | Enable Cambricon MLU memory support via Neuware, including memory detection, topology discovery, and RDMA registration. |
+| `-DUSE_RISCV=ON/OFF` | `OFF` | Enable RISC-V build compatibility settings, including disabling full IPO/LTO for Python extensions. |
+| `-DUSE_SHCA=ON/OFF` | `OFF` | Enable ScaleFabric SHCA InfiniBand support for Transfer Engine/TENT RDMA paths only. Mooncake-EP IBGDA is not supported. `MC_RPC_PROTOCOL=rdma` is not supported on SHCA builds; Store/RPC should use TCP. |
 | `-DUSE_ASCEND_DIRECT=ON/OFF` | `OFF` | Enable Ascend Direct transport and HCCS support via the ADXL engine. Recommended for Ascend builds. |
 | `-DUSE_UBSHMEM=ON/OFF` | `OFF` | Enable Huawei Ascend NPU shared memory transport via CANN VMM APIs. |
 | `-DUSE_INTRA_NVLINK=ON/OFF` | `OFF` | Enable intranode NVLink transport. |
 | `-DUSE_VRAM_SEGMENT=ON/OFF` | `OFF` | Enable create VRAM Segment instead of (default) DRAM Segment. |
 | `-DUSE_CXL=ON/OFF` | `OFF` | Enable CXL support. |
+| `-DUSE_MPCOMM=ON/OFF` | `OFF` | Enable the MPComm transport in TENT (multi-NIC memory pooling over RDMA). Requires `-DUSE_TENT=ON` and `-DMPCOMM_ROOT=<prefix>`. See [MPComm Transport](../design/transfer-engine/transport/mpcomm_transport.md). |
 
 ### Vendor SDK Path Overrides
 
@@ -229,12 +265,13 @@ The following options can be passed to `cmake ..`.
 | `-DNEUWARE_ROOT=/path/to/neuware` | `-DUSE_MLU=ON` | Override the Neuware SDK root. `NEUWARE_HOME` is also honored; default is `/usr/local/neuware`. |
 | `-DMLU_INCLUDE_DIR=/path/to/include` | `-DUSE_MLU=ON` | Override the Neuware include directory. |
 | `-DMLU_LIB_DIR=/path/to/lib64` | `-DUSE_MLU=ON` | Override the Neuware library directory. |
+| `-DMPCOMM_ROOT=/path/to/mpcomm` | `-DUSE_MPCOMM=ON` | **Required.** MPComm install prefix; must contain `include/mpcomm.h` and `lib/libmpcomm.so`. Configuration fails if unset or if either file is missing. |
 
 ### Transport and Metadata Options
 
 | Option | Default | Description |
 | --- | --- | --- |
-| `-DUSE_EFA=ON/OFF` | `OFF` | Enable AWS Elastic Fabric Adapter transport via libfabric. See [EFA Transport](../design/transfer-engine/efa_transport.md). |
+| `-DUSE_EFA=ON/OFF` | `OFF` | Enable AWS Elastic Fabric Adapter transport via libfabric. See [EFA Transport](../design/transfer-engine/transport/efa_transport.md). |
 | `-DUSE_NOF=ON/OFF` | `OFF` | Build Mooncake Store with NVMe-oF SSD pool support. Use `sudo bash dependencies.sh --with-spdk` before enabling it. |
 | `-DUSE_REDIS=ON/OFF` | `OFF` | Enable Redis-based metadata service for Transfer Engine. Requires hiredis. |
 | `-DUSE_HTTP=ON/OFF` | `ON` | Enable HTTP-based metadata service. |
@@ -250,8 +287,9 @@ The following options can be passed to `cmake ..`.
 | `-DWITH_TE=ON/OFF` | `ON` | Build the Mooncake Transfer Engine component and sample code. |
 | `-DWITH_STORE=ON/OFF` | `ON` | Build the Mooncake Store component. |
 | `-DWITH_STORE_GO=ON/OFF` | `OFF` | Build Go bindings for Mooncake Store when `-DWITH_STORE=ON`. |
+| `-DWITH_CONDUCTOR=ON/OFF` | `OFF` | Build the Mooncake Conductor service. |
 | `-DWITH_P2P_STORE=ON/OFF` | `OFF` | Enable Golang support and build the P2P Store component. Requires Go 1.23+. |
-| `-DWITH_RUST_EXAMPLE=ON/OFF` | `OFF` | Build the Transfer Engine Rust interface and sample code. |
+| `-DWITH_RUST_EXAMPLE=ON/OFF` | `OFF` | Build the Transfer Engine Rust library (`transfer_engine_rust`), tests, and sample benchmark. |
 | `-DWITH_STORE_RUST=ON/OFF` | `ON` | Build Mooncake Store Rust bindings and CMake Rust targets. |
 | `-DWITH_EP=ON/OFF` | `OFF` | Build the EP and PG Python extensions for CUDA. Requires CUDA toolkit and PyTorch. Use `-DEP_TORCH_VERSIONS="2.13.0"` to build for specific PyTorch versions, or leave empty to use the currently installed torch. The CUDA version is detected automatically. |
 
diff --git a/docs/source/getting_started/observability.md b/docs/source/getting_started/observability.md
index ffc6b007bb..7b264ef433 100644
--- a/docs/source/getting_started/observability.md
+++ b/docs/source/getting_started/observability.md
@@ -122,6 +122,7 @@ The admin HTTP server runs on `metrics_port` (default: **9003**) and exposes the
 | `GET /metrics` | `text/plain; version=0.0.4` | All metrics in Prometheus exposition format |
 | `GET /metrics/summary` | `text/plain; version=0.0.4` | Human-readable summary (same content as the periodic log) |
 | `GET /health` | `application/json` | Health check with role, HA state, and service readiness |
+| `GET /version` | `application/json` | Master version (`version` for RPC compatibility, `display_version` for release + git hash) |
 | `GET /role` | `text/plain` | Current HA role (`leader` / `standby`) |
 | `GET /ha_status` | `text/plain` | Current HA runtime state (`serving` / `starting` / etc.) |
 
@@ -150,6 +151,9 @@ curl http://<master-host>:9003/metrics/summary
 
 # Check health
 curl http://<master-host>:9003/health
+
+# Check version
+curl http://<master-host>:9003/version
 ```
 
 ### Configuration
@@ -166,6 +170,64 @@ The admin HTTP server is configured in the master config file (`master.json` or
 
 Set `enable_metric_reporting` to `false` to disable the periodic metrics log. HTTP endpoints (`/metrics`, `/health`, etc.) remain available regardless of this setting.
 
+### Process and Allocator Memory Metrics
+
+Both `/metrics` endpoints export the resident set size of the serving process,
+so memory growth can be read from Mooncake itself rather than correlated
+against a container-level metric.
+
+| Metric | Type | Source |
+|--------|------|--------|
+| `mooncake_process_rss_bytes` | gauge | `VmRSS` |
+| `mooncake_process_rss_peak_bytes` | gauge | `VmHWM`, the high-water mark an OOM kill is decided on |
+| `mooncake_process_rss_anon_bytes` / `..._rss_file_bytes` / `..._rss_shmem_bytes` | gauge | `RssAnon` / `RssFile` / `RssShmem` |
+| `mooncake_process_vsize_bytes` | gauge | `VmSize` |
+| `mooncake_process_swap_bytes` | gauge | `VmSwap` |
+
+These come from `/proc/self/status` and are exported whichever allocator the
+binary is linked against, so they stay comparable across an allocator change.
+
+When the binary is built with `-DSTORE_USE_JEMALLOC=ON` (see below),
+`mooncake_jemalloc_enabled` reports `1` and the allocator's own accounting is
+exported alongside: `allocated` / `active` / `metadata` / `resident` /
+`retained` / `mapped` / `dirty` / `muzzy` bytes, arena and background-thread
+counts, the `opt.dirty_decay_ms` and `opt.muzzy_decay_ms` settings, and
+cumulative purge counters (`mooncake_jemalloc_dirty_purge_runs_total`,
+`..._dirty_madvises_total`, and the `muzzy` equivalents). Dirty and muzzy are
+reported separately because jemalloc decays them on separate paths.
+
+`mooncake_jemalloc_resident_bytes / mooncake_jemalloc_allocated_bytes` is the
+ratio to watch: it is how much memory the allocator holds beyond what the
+application asked for. To attribute that ratio to a specific allocation size,
+`mooncake_jemalloc_bin_regs`, `..._bin_slabs`, `..._bin_used_bytes` and
+`..._bin_slab_bytes` break it down per small size class, labelled by
+`size_class`. A slab is returned to the OS only once every region in it is
+free, so a class with low `bin_used_bytes / bin_slab_bytes` occupancy is
+holding pages it cannot release.
+
+Note that `mooncake_jemalloc_resident_bytes` is the allocator's own upper
+estimate over the extents it maps and can exceed `mooncake_process_rss_bytes`;
+compare the two for divergence rather than subtracting them.
+
+When the binary is not built with jemalloc, `mooncake_jemalloc_enabled` reports
+`0`, no `mooncake_jemalloc_*` values or per-size-class series are emitted, and
+the process series above still export.
+
+#### Building with jemalloc
+
+`STORE_USE_JEMALLOC` is **off by default**. It links jemalloc into the
+`mooncake_master` and `mooncake_client` executables only, never into
+`libmooncake_store`, so the Python extension keeps its host process's
+allocator:
+
+```bash
+cmake .. -DSTORE_USE_JEMALLOC=ON
+```
+
+Both executables are stripped at link time, so each logs the jemalloc version,
+`background_thread` state and both decay settings at startup. That line is the
+way to confirm on a release binary that the allocator was actually replaced.
+
 ## Client Metrics Endpoint
 
 Mooncake clients can also expose a client-local HTTP endpoint for health checks
@@ -198,13 +260,66 @@ For `mooncake.mooncake_store_service`, set
 | `GET /health` | `application/json` | Client health check |
 | `GET /metrics` | `text/plain; version=0.0.4` | Prometheus-format client metrics |
 | `GET /metrics/summary` | `text/plain` | Human-readable client metrics summary |
+| `GET /version` | `application/json` | Client version (`version` for RPC compatibility, `display_version` for release + git hash) |
 
 ```bash
 curl http://<client-host>:9300/health
 curl http://<client-host>:9300/metrics
 curl http://<client-host>:9300/metrics/summary
+curl http://<client-host>:9300/version
+```
+
+```json
+{"version":"2.0.0","display_version":"0.3.12.post1 (git: f9e8311f)"}
 ```
 
+`/version` does not depend on client metric collection or on a fully
+initialized client, so it stays available whenever the client HTTP server is
+running.
+
 Set `MC_STORE_CLIENT_METRIC=0` to disable client metric collection. If the
 client HTTP server remains enabled while metrics are disabled, `/metrics` and
 `/metrics/summary` return HTTP 503 with `metrics not available`.
+
+
+### Master heartbeat observations
+
+Clients running the storage heartbeat expose two gauges through `/metrics`:
+
+| Metric | Meaning |
+|--------|---------|
+| `mooncake_client_master_heartbeat_status_ok` | Last observed Ping status: `1` for `OK`, `0` for `NEED_REMOUNT`. |
+| `mooncake_client_master_heartbeat_observation_timestamp_seconds` | Client-side Unix receive time, in seconds, of the same observation. |
+
+Both samples carry the existing client labels. They are absent before the first
+valid heartbeat, after a failed heartbeat or an unsupported status, and while
+reconnecting. Late responses from an older connection cannot restore the
+observation. A successful remount alone does not set the status to `1`; a later
+Ping must return `OK`.
+
+A client without storage may never start this heartbeat. Memory or LocalDisk
+mounts and DFS backend activation start the storage control plane; creating a
+request-only client does not. Missing samples mean **unknown or inapplicable**,
+not `NEED_REMOUNT`. Disabling client metrics also disables these observations.
+
+The timestamp is an observation value, not a Prometheus sample timestamp. An
+in-flight Ping can leave the previous observation visible until it completes,
+so check its age as well as its status. For example, for targets expected to
+run a storage heartbeat, this query selects a recent `NEED_REMOUNT` observation
+using an illustrative 10-second freshness limit:
+
+```promql
+(mooncake_client_master_heartbeat_status_ok == 0)
+and
+((time() - mooncake_client_master_heartbeat_observation_timestamp_seconds) < 10)
+```
+
+Choose the freshness limit for the heartbeat/RPC timeouts and scrape interval
+in your deployment, and account for clock skew. Do not replace missing status
+samples with zero. Prometheus `up` describes the HTTP scrape, not Master Ping
+success; missing or stale observations need separate handling.
+
+This is a sampled control-plane response. `OK` does not prove that every
+segment is mounted, that transfer metadata or SSD recovery is complete, or
+that data RPCs and RDMA transfers are healthy. The existing `/health` check
+can remain healthy when a successful Ping returns `NEED_REMOUNT`.
diff --git a/docs/source/getting_started/plugin-usage/3FS-USRBIO-Plugin.md b/docs/source/getting_started/plugin-usage/3FS-USRBIO-Plugin.md
index 5566bc274b..d933af3782 100644
--- a/docs/source/getting_started/plugin-usage/3FS-USRBIO-Plugin.md
+++ b/docs/source/getting_started/plugin-usage/3FS-USRBIO-Plugin.md
@@ -1,47 +1,92 @@
-# Mooncake HF3FS Plugin (Experimental)
+# Mooncake HF3FS USRBIO Adapter (Experimental)
 
 ```{warning}
-**Experimental / incomplete.** The HF3FS (3FS USRBIO) integration is under development and is not yet considered production-ready. Behavior, build flags, and configuration may change without notice. Use only for evaluation and testing.
+**Work in progress / experimental.** Descriptor-based DFS and its HF3FS (3FS
+USRBIO) adapter are under development and are not production-ready. They are
+not covered by Mooncake Store's general fault-tolerance, HA continuity,
+durability, or multi-tenant guarantees. Behavior, build flags, and
+configuration may change without notice. Use only for evaluation and testing.
 ```
 
-This plugin implements 3FS native API (USRBIO) as a high-performance storage backend for Mooncake.
+This adapter implements the HF3FS native USRBIO data plane for Mooncake Store's
+descriptor-based DFS replicas. The master allocates ranges in shared shard
+files, and clients use USRBIO to access the ranges described by the replica
+metadata.
+
+The adapter is not enabled by the legacy `--root_fs_dir` option. It also does
+not automatically fall back to POSIX I/O; select
+`MOONCAKE_DFS_FS_ADAPTER=posix` explicitly when POSIX behavior is required.
 
 ## Prerequisites
 
-### 1. 3FS Installation
+### 1. HF3FS installation
+
 - Build and install [3FS](https://github.com/deepseek-ai/3FS/)
 - Required library: `libhf3fs_api_shared.so` (Default location: `3FS_PATH/build/src/lib/api`)
   → Install to: `/usr/lib/`
 - Required header: `hf3fs_usrbio.h` (Default location: `3FS_PATH/src/lib/api`)
   → Install to: `/usr/include/`
 
-### 2. Mooncake Configuration
-- Enable 3FS support during CMake configuration:
-```bash
+### 2. Mooncake build
+
+Enable HF3FS support during CMake configuration:
 
+```bash
 cmake -DUSE_3FS=ON ...
 ```
 
-- Build and install Mooncake as usual.
+Then build and install Mooncake as usual.
 
 ## Usage
 
-### Basic Operation
-Start master server and specify the 3FS mount point:
+### Master
+
+Enable descriptor-based DFS and point it at a directory on the shared HF3FS
+mount:
+
 ```bash
+export MOONCAKE_ENABLE_DFS=1
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
 
-./build/mooncake-store/src/mooncake_master \
-    --root_fs_dir=/path/to/3fs_mount_point
+./build/mooncake-store/src/mooncake_master [other master arguments]
 ```
-### Important Notes
-1. The specified directory **must** be a 3FS mount point
-   - If not, the system will automatically fall back to POSIX API
-2. For optimal performance:
-   - Ensure proper permissions on the 3FS mount point
-   - Verify 3FS service is running before execution
-
-### Example
+
+The master creates and preallocates the configured shard files during startup.
+Ensure the mount is available, writable, and has enough capacity before
+starting the process.
+
+### Clients
+
+Every client that may read or write DFS replicas must use the same root,
+adapter, shard count, shard capacity, and alignment. The DFS root must be an
+absolute path and use the same path string in every process. For the standalone
+store service:
+
 ```bash
+export MOONCAKE_OFFLOAD_ENABLED=true
+export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=distributed_storage_backend
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/data/file_storage
+export MOONCAKE_MASTER=127.0.0.1:50051
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
 
-ROLE=prefill MOONCAKE_STORAGE_ROOT_DIR=/mnt/3fs python3 ./stress_cluster_benchmark.py
+python -m mooncake.mooncake_store_service
 ```
+
+`MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` must already be an absolute, writable,
+non-symlink directory. DFS shard data is stored under
+`MOONCAKE_DFS_ROOT_DIR`; the separate FileStorage path is still validated
+during client initialization.
+
+For the complete configuration reference, request example, synchronous write
+semantics, and current recovery limitations, see the {ref}`DFS deployment
+documentation <dfs-storage>`.
diff --git a/docs/source/getting_started/quick-start.md b/docs/source/getting_started/quick-start.md
index 90d17c6f30..c98d57b382 100644
--- a/docs/source/getting_started/quick-start.md
+++ b/docs/source/getting_started/quick-start.md
@@ -1,87 +1,301 @@
 # Quick Start
 
-This document describes how to quickly start using Mooncake Transfer Engine and Mooncake Store.
+Get up and running with Mooncake in minutes.
 
-## Before using Mooncake
+This guide walks you through the entire flow of getting started with Mooncake:
+
+1. **Install** Mooncake
+2. **Start** the Store master and **Send a request** with the Python Store API
+
+Serving-framework users can then connect SGLang, vLLM or other systems.
+
+## Prerequisites
+
+- **Python**: 3.10 or later; a virtual environment is recommended.
+- **RDMA**: an RDMA driver and SDK (for example, Mellanox OFED), if you plan to use RDMA for data transfer. On ScaleFabric SHCA systems, install `shca-tools` and build with `-DUSE_SHCA=ON`.
+- **CUDA**: 12.1 or later. For most CUDA-enabled use cases, such as RDMA-based KV cache transfer between GPUs or between GPU and DRAM, NVIDIA GPUDirect support is also required. You may install CUDA from [the NVIDIA downloads page](https://developer.nvidia.com/cuda-downloads).
+
+```{note}
+The default pip, build and Docker paths target NVIDIA CUDA. For other
+platforms, see [Other Platforms](#other-platforms) below.
+```
 
-Install the following prerequisites before running any Mooncake component:
-- Python 3.10 or later; a virtual environment is recommended.
-- RDMA driver and SDK (for example, Mellanox OFED), if you plan to use RDMA for data transfer.
-- CUDA 12.1 or later, if the package is built with `-DUSE_CUDA` (disabled by default). For most CUDA-enabled use cases, such as RDMA-based KV cache transfer between GPUs or between GPU and DRAM, NVIDIA GPUDirect support is also required. *You may install them from [here](https://developer.nvidia.com/cuda-downloads)*.
-- Cambricon Neuware, if the package is built with `-DUSE_MLU`. By default Mooncake looks for Neuware under `NEUWARE_HOME` or `/usr/local/neuware`.
-- Hygon DTK SDK, if the package is built with `-DUSE_HYGON`. By default Mooncake looks for DTK under `DTK_HOME` or `/opt/dtk`.
-- Iluvatar CoreX SDK, if the package is built with `-DUSE_COREX`. By default Mooncake looks for CoreX under `COREX_HOME` or `/usr/local/corex`.
 
 ## Installation
 
-Install the Mooncake package from PyPI. The same package provides:
+The same package provides:
 
 - Mooncake Store Python bindings for vLLM and SGLang HiCache integrations.
 - Transfer Engine Python bindings and runtime components for direct
   `mooncake.engine.TransferEngine` usage.
 
-**For CUDA-enabled systems:**
+::::{tab-set}
+
+:::{tab-item} pip / uv
+We recommend using **uv** for faster installation:
+
+```bash
+pip install --upgrade pip
+pip install uv
+uv pip install mooncake-transfer-engine
+```
+
+Plain `pip` also works:
 
-- CUDA < 13.0
 ```bash
 pip install mooncake-transfer-engine
 ```
 
-- CUDA >= 13.0
+```{tip}
+The default wheel targets CUDA 12.1–12.9 and includes Mooncake-EP and GPU
+topology detection. For CUDA 13.0/13.1, install
+`mooncake-transfer-engine-cuda13` instead.
+```
+:::
+
+:::{tab-item} From Source
+Clone the repository and build the default configuration:
+
+```bash
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+sudo bash dependencies.sh
+
+mkdir build
+cd build
+cmake ..
+make -j
+sudo make install
+```
+
+For CUDA, VRAM segments, NVMe-oF, and other backend flags, see the
+[Build Guide](build.md).
+:::
+
+:::{tab-item} Docker
+Published images are available on Docker Hub at
+[kvcacheai/mooncake](https://hub.docker.com/r/kvcacheai/mooncake).
+
 ```bash
-pip install mooncake-transfer-engine-cuda13
+docker run --net=host \
+    --ipc=host \
+    --ulimit memlock=-1 \
+    kvcacheai/mooncake:latest \
+    mooncake_master
+```
+
+For details, see
+[Use Mooncake in Docker Containers](build.md#use-mooncake-in-docker-containers).
+:::
+
+::::
+
+```{note}
+If users encounter problems such as missing `lib*.so`, first install the
+corresponding system runtime libraries. If the issue persists, uninstall the
+package and [build the binaries manually](build.md).
 ```
 
-**For non-CUDA systems:**
+## Other Platforms
+
+The default path above targets NVIDIA CUDA. Use the matching wheel or source
+build for other platforms. Install only one variant in an environment.
+
+::::{tab-set}
+
+:::{tab-item} Non-CUDA
+**Prerequisites**
+
+- Python 3.10 or later.
+- Ubuntu runtime libraries: `libcurl4`, `libibverbs1`, `rdma-core`,
+  `librdmacm1`, `libnuma1`, and `liburing2`.
+
+**Installation**
+
 ```bash
+sudo apt-get update && sudo apt-get install -y \
+  libcurl4 libibverbs1 rdma-core librdmacm1 libnuma1 liburing2
 pip install mooncake-transfer-engine-non-cuda
 ```
+:::
+
+:::{tab-item} Ascend NPU
+**Prerequisites**
+
+- Python 3.10 or later.
+- Ascend CANN Toolkit. Source `/usr/local/Ascend/cann/set_env.sh` before
+  running Mooncake. Ascend Direct (ADXL/HIXL) is the recommended path.
+
+**Installation**
 
-**For NPU systems:**
 ```bash
 pip install mooncake-transfer-engine-npu
+source /usr/local/Ascend/cann/set_env.sh
 ```
 
-> **Important**:
-> - The CUDA version (`mooncake-transfer-engine`) includes Mooncake-EP and GPU topology detection, requiring CUDA 12.1+.
-> - The non-CUDA version (`mooncake-transfer-engine-non-cuda`) is for environments without CUDA dependencies, but it still needs system runtime libraries such as `libcurl4`, `libibverbs1`, `rdma-core`, `librdmacm1`, `libnuma1`, and `liburing2` on Ubuntu. In a fresh environment, run `sudo apt-get update` before installing them:
->   ```bash
->   sudo apt-get update && sudo apt-get install -y libcurl4 libibverbs1 rdma-core librdmacm1 libnuma1 liburing2
->   ```
-> - MLU support is currently available through source builds with `-DUSE_MLU=ON`; there is no dedicated prebuilt MLU wheel yet.
-> - If users encounter problems such as missing `lib*.so`, first install the corresponding system runtime libraries. If the issue persists, uninstall the package and build the binaries manually.
+See [Ascend Direct Transport](../design/transfer-engine/transport/ascend_direct_transport.md)
+for the recommended path. The legacy backend is documented in
+[Ascend Transport](../design/transfer-engine/transport/ascend_transport.md).
+For mixed GPU/NPU transfers, see
+[Heterogeneous Ascend Transport](../design/transfer-engine/transport/heterogeneous_ascend.md).
+There are also two detailed Chinese guides:
+[Mooncake KVPool guide](https://gitcode.com/cann/hixl/wiki/Mooncake%20KVPool%E6%8C%87%E5%8D%97.md)
+and
+[Mooncake NPU guide](https://gitcode.com/cann/hixl/wiki/Mooncake%EF%BC%88NPU%20%E7%89%88%EF%BC%89%E5%AE%8C%E6%95%B4%E6%8C%87%E5%8D%97.md).
+:::
 
-## Connect vLLM or SGLang
+:::{tab-item} AMD ROCm
+**Prerequisites**
 
-Choose the integration path that matches your serving deployment.
+- Python 3.10 or later.
+- ROCm / HIP SDK, with `hipcc` and runtime libraries on `PATH` (for example
+  `/opt/rocm`).
 
-### PD Disaggregation
+**Installation**
 
-PD disaggregation paths use Mooncake Transfer Engine for direct KV transfer
-between prefill and decode workers. Configure these paths through the serving
-framework guides, not by calling Transfer Engine APIs directly:
+```bash
+pip install mooncake-transfer-engine-rocm
+```
+:::
 
-- [SGLang Integration Overview](../deployment/integrations/sglang/index.md)
-- [vLLM Integration Overview](../deployment/integrations/vllm/index.md)
+:::{tab-item} Moore Threads MUSA
+**Prerequisites**
 
-### Mooncake Store
+- Python 3.10 or later.
+- MUSA SDK. Add `/usr/local/musa/lib` to `LIBRARY_PATH` and `LD_LIBRARY_PATH`.
+- `mthreads-peermem` for GPUDirect RDMA.
 
-Mooncake Store provides distributed KV cache storage for vLLM and SGLang
-HiCache:
+**Installation**
 
-| Framework | Use case | Setup guide |
-|-----------|----------|-------------|
-| SGLang | HiCache L3 storage backend with Mooncake Store | [SGLang HiCache Quick Start](../deployment/integrations/sglang/hicache-quick-start.md) |
-| vLLM | KV cache storage and sharing with `MooncakeStoreConnector` | [vLLM KV Cache Storage & Sharing](../deployment/integrations/vllm/kv-cache-storage.md) |
+```bash
+pip install mooncake-transfer-engine-musa
+```
+:::
+
+:::{tab-item} AWS EFA
+**Prerequisites**
+
+- An AWS instance with EFA (for example p5 or p6).
+- AWS EFA driver and libfabric. Verify with `fi_info -p efa`, and keep
+  `/opt/amazon/efa/lib` on `LD_LIBRARY_PATH`.
+- CUDA 12.1–12.9 or CUDA 13 if you use the GPU-aware EFA wheels.
+
+**Installation**
+
+```bash
+# GPU memory transfers with CUDA 12
+pip install mooncake-transfer-engine-efa
+
+# GPU memory transfers with CUDA 13
+pip install mooncake-transfer-engine-efa-cuda13
+
+# CPU/DRAM-only transfers
+pip install mooncake-transfer-engine-efa-non-cuda
+```
 
-The serving framework guides include the required Mooncake Store service
-startup and connector configuration for each path.
+See the [EFA transport guide](../design/transfer-engine/transport/efa_transport.md)
+for prerequisites and configuration.
+:::
 
-## Optional Python Smoke Test
+:::{tab-item} Cambricon MLU
+**Prerequisites**
 
-If you want to verify the Store Python API without a serving framework, run this
-single-node `put`/`get` example after starting `mooncake_master`. It uses
-`P2PHANDSHAKE`, so no separate Transfer Engine metadata service is required.
+- Python 3.10 or later.
+- Cambricon Neuware SDK. Set `NEUWARE_HOME`, or use the default
+  `/usr/local/neuware`. There is no dedicated prebuilt MLU wheel yet.
+
+**Installation**
+
+```bash
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+sudo bash dependencies.sh
+mkdir build && cd build
+cmake .. -DUSE_MLU=ON
+make -j
+sudo make install
+```
+:::
+
+:::{tab-item} MetaX MACA
+**Prerequisites**
+
+- Python 3.10 or later.
+- MACA SDK. Set `MACA_HOME`, or use the default `/opt/maca`.
+
+**Installation**
+
+```bash
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+sudo bash dependencies.sh
+mkdir build && cd build
+cmake .. -DUSE_MACA=ON
+make -j
+sudo make install
+```
+:::
+
+:::{tab-item} Hygon DCU
+**Prerequisites**
+
+- Python 3.10 or later.
+- Hygon DTK SDK. Set `DTK_HOME`, or use the default `/opt/dtk`.
+
+**Installation**
+
+```bash
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+sudo bash dependencies.sh
+mkdir build && cd build
+cmake .. -DUSE_HYGON=ON
+make -j
+sudo make install
+```
+:::
+
+:::{tab-item} Iluvatar CoreX
+**Prerequisites**
+
+- Python 3.10 or later.
+- Iluvatar CoreX SDK. Set `COREX_HOME`, or use the default `/usr/local/corex`.
+
+**Installation**
+
+```bash
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+sudo bash dependencies.sh
+mkdir build && cd build
+cmake .. -DUSE_COREX=ON
+make -j
+sudo make install
+```
+:::
+
+::::
+
+## Start Mooncake Store
+
+If you installed with pip or from source, start the master service:
+
+```bash
+mooncake_master
+```
+
+Wait until you see a line like this in the logs:
+
+```
+Master service started on port 50051, max_threads=4, ...
+```
+
+The default RPC port is `50051`. Skip this step if the Docker command above is
+already running `mooncake_master`.
+
+## Send Your First Request
+
+Run this single-node `put`/`get` example after `mooncake_master` is running. This example uses `P2PHANDSHAKE`, so no separate Transfer Engine metadata service is required.
 
 ```python
 from mooncake.store import MooncakeDistributedStore
@@ -105,6 +319,29 @@ print(data.decode())  # Output: Hello, Mooncake Store!
 store.close()
 ```
 
+## Connect vLLM or SGLang
+
+Choose the integration path that matches your serving deployment.
+
+### PD Disaggregation
+
+PD disaggregation paths use Mooncake Transfer Engine for direct KV transfer
+between prefill and decode workers. Configure these paths through the serving
+framework guides, not by calling Transfer Engine APIs directly:
+
+- [SGLang Disaggregated Serving with MooncakeTransferEngine](../deployment/integrations/sglang/pd-disaggregation.md)
+- [Disaggregated Prefill-Decode with MooncakeConnector](../deployment/integrations/vllm/disagg-prefill-decode.md)
+
+### Distributed KV Cache Pooling
+
+Mooncake Store provides distributed KV cache storage for vLLM and SGLang
+HiCache:
+
+| Framework | Use case | Setup guide |
+|-----------|----------|-------------|
+| SGLang | HiCache L3 storage backend with Mooncake Store | [SGLang HiCache Quick Start](../deployment/integrations/sglang/hicache-quick-start.md) |
+| vLLM | KV cache storage and sharing with `MooncakeStoreConnector` | [vLLM KV Cache Storage & Sharing](../deployment/integrations/vllm/kv-cache-storage.md) |
+
 ## AI Coding Assistant Skills
 
 If you use Claude Code or another coding assistant that supports reusable
@@ -133,4 +370,4 @@ allocation strategies, SSD offload, and runtime tuning, continue to the
 [Mooncake Store Deployment & Tuning Guide](../deployment/mooncake-store-deployment-guide.md).
 
 For API details, see the [Mooncake Store Python API](../api-reference/python/mooncake-store.md)
-and [Mooncake Store design](../design/mooncake-store.md).
+and [Mooncake Store design](../design/store/mooncake-store.md).
diff --git a/docs/source/getting_started/supported-protocols.md b/docs/source/getting_started/supported-protocols.md
index baa8a6ebbd..a872910ebd 100644
--- a/docs/source/getting_started/supported-protocols.md
+++ b/docs/source/getting_started/supported-protocols.md
@@ -11,12 +11,16 @@ Mooncake Transfer Engine supports multiple communication protocols for data tran
 | **efa** | AWS EFA-capable instance | High-performance on AWS (libfabric SRD) | ✅ Primary |
 | **nvmeof** | NVMe-oF capable storage | Direct NVMe storage access | ⚠️ Advanced |
 | **nvlink** | NVIDIA MNNVL | Inter-node GPU communication | ⚠️ Advanced |
+| **musa** | Moore Threads GPU + MTLink | Intra-node GPU IPC/P2P | ⚠️ Advanced |
 | **nvlink_intra** | NVIDIA NVLink | Intra-node GPU communication | ⚠️ Advanced |
 | **hip** | AMD ROCm/HIP | AMD GPU communication | ⚠️ Advanced |
 | **barex** | RDMA-capable NIC | Bare-metal RDMA extension | ⚠️ Advanced |
 | **cxl** | CXL-capable hardware | Memory pooling and sharing | ⚠️ Advanced |
+| **shm** | None (POSIX shm, same host) | Same-host DRAM copies without NIC loopback | ⚠️ Advanced |
 | **ascend** | Huawei Ascend NPU | Ascend NPU communication | ⚠️ Advanced |
 | **tpu** | Google TPU (PJRT) | TPU KV-cache transfer via host-DRAM staging | 🧪 Experimental (TENT) |
+| **mpcomm** | RDMA-capable NIC(s) | Multi-NIC memory pooling with NIC/QP load balancing | ⚠️ Advanced (TENT) |
+| **flagcx** | RDMA-capable NIC(s) | Unified P2P transfer through FlagOS FlagCX | ⚠️ Advanced |
 
 ## Commonly Used Protocols (Python API)
 
@@ -164,7 +168,7 @@ cmake .. -DUSE_EFA=ON -DUSE_CUDA=ON
 - Software-emulated RDMA writes (higher CPU overhead than true RDMA)
 - ~88% of RoCE RDMA throughput
 
-**Documentation:** See [EFA Transport](../design/transfer-engine/efa_transport.md) for build instructions, benchmarks, and tuning.
+**Documentation:** See [EFA Transport](../design/transfer-engine/transport/efa_transport.md) for build instructions, benchmarks, and tuning.
 
 ## Advanced Protocols (C++ Transfer Engine)
 
@@ -204,6 +208,70 @@ export MC_FORCE_MNNVL=true
 
 **Note:** When `protocol="rdma"` is set and RDMA NICs exist, you must explicitly set `MC_FORCE_MNNVL=true` to use MNNVL instead of RDMA. If no RDMA HCA is detected, MNNVL will be used automatically.
 
+**Host memory over NVLink (TENT, EGM):** on Grace-Blackwell systems the GPUs of
+an NVLink domain can also address each other's host DRAM (Extended GPU Memory).
+The TENT `mnnvl` transport exports host buffers this way when
+`transports/mnnvl/egm` is enabled (`MC_MNNVL_EGM=1`, off by default), adding the
+`dram_to_dram` and `gpu_to_dram` capabilities so CPU-resident data (weight or
+KV caches) moves over NVLink instead of the NIC:
+
+```bash
+export MC_ENABLE_MNNVL=1   # select the TENT mnnvl transport
+export MC_MNNVL_EGM=1      # transports/mnnvl/egm
+```
+
+Only buffers allocated with `allocateLocalMemory("cpu:<numa>")` (or any
+`cuMemCreate` allocation with a `HOST_NUMA` location and a fabric handle) are
+exported; other host memory keeps the previous `cudaHostRegister` behaviour and
+is reachable through RDMA/TCP as before. Requires an IMEX domain spanning the
+peers and EGM enabled in the driver.
+
+### MUSA Transport (musa)
+
+**Description:** Moore Threads GPU IPC transport for P2P copies over the
+intra-node MTLink path. It reuses the NVLink transport's transfer bookkeeping,
+but opens imported IPC memory and submits copies using MUSA-specific device
+context rules.
+
+**Requirements:**
+- Moore Threads GPUs with peer access (validated on S5000)
+- MUSA SDK/runtime; MUSA 5.2 or newer enables the low-CPU transfer-batch API
+- Compiled with `USE_MUSA=ON`
+
+**Configuration:**
+```bash
+# Use the same runtime-visible logical-device mapping in every peer process.
+export MUSA_VISIBLE_DEVICES=0,1
+export MC_FORCE_MUSA=1
+
+# Safe defaults shown explicitly. Opt in to metadata after checking the
+# visibility contract below; "default" rolls back to per-slice copies.
+export MC_MUSA_IPC_OPEN_DEVICE=current
+export MC_MUSA_COPY_API=auto
+
+# Performance path after both peers use the same logical device mapping.
+export MC_MUSA_IPC_OPEN_DEVICE=metadata
+```
+
+`MTHREADS_VISIBLE_DEVICES` is consumed by mt-container-toolkit when the
+container is created; Mooncake does not use it to infer the MUSA runtime's
+logical device mapping. Buffer metadata uses runtime-visible logical ordinals
+such as `musa:0`. With `metadata`, every peer must map each logical ordinal to
+the same physical GPU. Mooncake validates that the advertised ordinal exists
+locally, but it cannot prove cross-peer identity from environment variables.
+Both peers must run a version that recognizes the `musa` protocol; rolling
+interoperability with an older peer advertising only `nvlink` is not supported.
+`MC_MUSA_IPC_OPEN_DEVICE=current` is the safe default; select `metadata` only
+when peers satisfy the logical mapping contract above. Python bindings that
+register the default wildcard location (`*`) resolve the owning MUSA device
+during registration; an older peer that still advertises `*` falls back to the
+current-device open path.
+
+In `auto` mode, batches whose copies are at least 1 MiB use
+`muMemoryTransferBatchAsync`; set `MC_MUSA_TRANSFER_BATCH_MIN_BYTES` to tune the
+threshold, `MC_MUSA_COPY_API=transfer_batch` to force the API, or
+`MC_MUSA_COPY_API=default` to use the CUDA-compatible per-slice path.
+
 ### Intra-Node NVLink (nvlink_intra)
 
 **Description:** NVIDIA NVLink for GPU-to-GPU communication within a single node.
@@ -214,7 +282,15 @@ export MC_FORCE_MNNVL=true
 
 **Requirements:**
 - NVIDIA NVLink hardware
-- Compiled with `USE_INTRA_NVLINK=ON`
+- Compiled with `USE_INTRA_NVLINK=ON` (enabled in the prebuilt `x86_64` CUDA wheels; other variants must be built from source)
+
+**Configuration:**
+```bash
+# Select the intra-node NVLink transport. Cannot be combined with MC_FORCE_MNNVL.
+export MC_INTRANODE_NVLINK=true
+```
+
+**Note:** On a build without `USE_MNNVL=ON`, leaving `MC_INTRANODE_NVLINK` unset keeps the usual RDMA (or TCP, when no HCA is detected) selection.
 
 ### HIP Transport (hip)
 
@@ -251,6 +327,31 @@ export MC_FORCE_MNNVL=true
 **Requirements:**
 - CXL-capable hardware
 
+### SHM Transport (shm)
+
+**Description:** Same-host DRAM copies over POSIX shared memory. Classic Transfer Engine maps the peer's named shm object, relocates the peer virtual address into the local mapping, and `memcpy`s. This is a first-class transport like HIP, not a replacement for `CxlTransport` (DAX offset addressing).
+
+**Use When:**
+- Two processes on the same machine exchange DRAM buffers
+- You want to avoid RDMA/TCP loopback for that path
+
+**Requirements:**
+- Linux POSIX shm (`/dev/shm`), or a writable hugetlbfs mount when allocating with `SharedMemoryOptions.use_hugepage` (2MB / 512MB / 1GB)
+- Buffers allocated with `TransferEngine::allocateSharedMemory` (ordinary `malloc` cannot be exported)
+- Runtime opt-in: `MC_FORCE_SHM=1`, or `installTransport("shm")`. With `-DENABLE_MULTI_PROTOCOL=ON` this adds SHM next to RDMA/TCP (`rdma,shm` / `tcp,shm`); without it, SHM is the only transport.
+- Same-host SHM **and** cross-host RDMA/TCP in one engine: build with `-DENABLE_MULTI_PROTOCOL=ON` (segment protocol becomes `rdma,shm` or `tcp,shm`)
+
+**Limitations:**
+- Same host only. Without `ENABLE_MULTI_PROTOCOL`, `MC_FORCE_SHM=1` (or `installTransport("shm")` after another transport) sets `segment.protocol` to `shm` and replaces RDMA/TCP routing; `installTransport("shm")` logs a WARNING when it overwrites a non-empty protocol. Coexistence needs `-DENABLE_MULTI_PROTOCOL=ON`.
+- `registerLocalMemory` must use the pointer from `allocateSharedMemory` (a shorter prefix is allowed). A sub-range or overflowing range returns an error instead of silently skipping. Ordinary `malloc` is still skipped so TCP/RDMA can register it.
+- Same-UID only: objects are created `0600`. POSIX names are `/mooncake_<pid>_xxxxxxxx`; hugepage files are `<hugetlbfs-mount>/mooncake_<pid>_xxxxxxxx`. Creator and consumer must share a user; a hostname match does not imply a shared `/dev/shm` or hugetlbfs mount (for example Kubernetes `hostNetwork` pods).
+- Crash or `SIGKILL` can leave POSIX objects in `/dev/shm` and hugetlbfs files on the mount. There is no automatic reaper (wiping `mooncake_*` on start would hit live peers on the same mount). POSIX leftovers waste tmpfs until reboot; **hugetlbfs leftovers keep hugepages reserved** until the file is unlinked or the node reboots. After a crash, delete only `mooncake_<pid>_*` whose pid no longer exists, e.g. `rm /dev/hugepages/mooncake_<dead-pid>_*`.
+- Hugepage allocations do not fall back to tmpfs. `length` must be a multiple of the hugepage size; TE does not round up.
+- After `freeSharedMemory` + `allocateSharedMemory`, a peer that still has a cached mapping probes the object name before memcpy. An unlinked object is dropped and the segment descriptor is refetched once; a changed virtual address still requires the initiator to read the new `BufferDesc.addr` (relocate cannot guess a new offset). Background refresh remains optional via `MC_TE_METADATA_REFRESH_INTERVAL_SECONDS`.
+- Relocate caches at most 32 mmap'd peer objects per target. An in-flight copy pins its mapping so prune/cap cannot `munmap` it until memcpy returns; the cache may briefly exceed 32 while pins are held.
+- Default off because the path is not NUMA-aware
+- Mooncake Store segments are not shm-backed until a follow-up allocator change
+
 ### Ascend Transport (ascend)
 
 **Description:** Huawei Ascend NPU communication using HCCL (Huawei Collective Communication Library) or direct transport.
@@ -264,8 +365,8 @@ export MC_FORCE_MNNVL=true
 - HCCL runtime
 
 **Documentation:**
-- [Heterogeneous Ascend](../design/transfer-engine/heterogeneous_ascend.md)
-- [Ascend Transport](../design/transfer-engine/ascend_transport.md)
+- [Heterogeneous Ascend](../design/transfer-engine/transport/heterogeneous_ascend.md)
+- [Ascend Transport](../design/transfer-engine/transport/ascend_transport.md)
 
 ### TPU Transport (tpu) — Experimental
 
@@ -300,6 +401,84 @@ planned as a follow-up.
 - DMA-mapped (pinned) staging buffers for true async device DMA are a planned
   performance follow-up.
 
+### MPComm Transport (mpcomm)
+
+**Description:** UCL-MPComm (Unified Communication Library - Memory Pool Communication) is an RDMA
+library for heterogeneous memory pooling, integrated as a TENT transport. It drives multiple RDMA
+NICs concurrently with two-level load balancing (across NICs, and across QPs within a NIC) and
+NUMA-aware worker placement, exposing one-sided put/get primitives. It is shortened to MPComm
+below.
+
+**Status:** TENT only. There is no MPComm backend on the legacy Transfer Engine transport path,
+so it cannot be selected through `MOONCAKE_PROTOCOL` or `transfer_engine_bench --protocol=`.
+
+**Use When:**
+- The host has several RDMA NICs and you want them saturated by a single transfer stream
+- Multi-NUMA hosts where NIC-to-NUMA affinity matters
+
+**Requirements:**
+- Built with `-DUSE_TENT=ON -DUSE_MPCOMM=ON -DMPCOMM_ROOT=<prefix>`
+- MPComm installed, providing `include/mpcomm.h` and `lib/libmpcomm.so`
+  (<https://github.com/Tencent/UCL-MPComm>)
+- `libmpcomm.so` reachable by the dynamic linker at run time
+
+**Enable:**
+```json
+{ "transports": { "mpcomm": { "enable": true } } }
+```
+
+See [MPComm Transport](../design/transfer-engine/transport/mpcomm_transport.md) for the full guide,
+including selection via transport policy, tuning environment variables, and troubleshooting.
+
+### FlagOS FlagCX Transport (flagcx)
+
+**Description:** [FlagCX](https://github.com/flagos-ai/FlagCX) is the unified communication library
+in the FlagOS ecosystem for multi-vendor and cross-vendor deployments. Mooncake integrates the
+FlagCX P2P Engine as a classic Transfer Engine transport, allowing the existing Mooncake transfer
+workflow to use the accelerator and network backends provided by the local FlagCX build.
+
+**Use When:**
+- Deploying Mooncake on a platform supported by FlagCX
+- Using FlagCX's P2P Engine for accelerator memory transfers
+- Building a cross-vendor deployment around the FlagOS communication stack
+
+**Build Requirements:**
+```bash
+cmake -S . -B build \
+  -DUSE_FLAGCX=ON \
+  -DFLAGCX_HOME=/path/to/FlagCX/build
+cmake --build build -j
+```
+
+`FLAGCX_HOME` must contain `include/flagcx_p2p.h` and either `lib/libflagcx.so` or
+`lib64/libflagcx.so`. If it is omitted, Mooncake checks `$FLAGCX_HOME` and then
+`$HOME/FlagCX/build`.
+
+**Configuration:**
+```python
+engine.initialize(
+    hostname="node1",
+    metadata_server="P2PHANDSHAKE",
+    protocol="flagcx",
+    device_name=""
+)
+```
+
+```bash
+# Select the interface used for FlagCX bootstrap and endpoint advertisement.
+export FLAGCX_SOCKET_IFNAME="eth0"
+```
+
+**Current Scope:**
+- Available through the classic Transfer Engine; it is not a TENT transport
+- Must be built from source with `USE_FLAGCX=ON`
+- Should be selected as the standalone `flagcx` protocol, not as part of a multi-protocol string
+- Buffers should be registered before the first transfer to a peer and remain registered while
+  that peer connection is active
+
+See [FlagOS FlagCX Transport](../design/transfer-engine/transport/flagcx_transport.md) for dependency,
+build, benchmark, runtime configuration, and troubleshooting details.
+
 ## Configuration Examples
 
 ### Configuration File (JSON)
@@ -360,6 +539,7 @@ export MOONCAKE_LOCAL_HOSTNAME="node1"
 | AMD GPU Clusters | rdma + hip | Use HIP for local GPU communication |
 | Cambricon MLU Clusters | rdma | Build with `-DUSE_MLU=ON`; MLU uses the normal RDMA protocol |
 | Ascend NPU Clusters | rdma + ascend | Use Ascend for NPU-specific operations |
+| Multi-vendor or cross-vendor clusters | flagcx | Build with `-DUSE_FLAGCX=ON`; transfers use the FlagCX P2P Engine over RDMA-capable NICs |
 
 ## Troubleshooting
 
@@ -402,3 +582,17 @@ If a protocol fails to initialize:
 - [Transfer Engine Benchmark](../design/transfer-engine/transfer-engine-bench-tuning.md) - Performance tuning
 - [Python API Reference](../api-reference/python/transfer-engine.md) - API documentation
 - [Deployment Guide](../deployment/mooncake-store-deployment-guide.md) - Production deployment
+
+:::{toctree}
+:maxdepth: 1
+:hidden:
+
+../design/transfer-engine/transport/efa_transport
+../design/transfer-engine/transport/ascend_direct_transport
+../design/transfer-engine/transport/ascend_transport
+../design/transfer-engine/transport/heterogeneous_ascend
+../design/transfer-engine/transport/kunpeng_ub_transport
+../design/transfer-engine/transport/sunrise_link_transport
+../design/transfer-engine/transport/flagcx_transport
+../design/transfer-engine/transport/mpcomm_transport
+:::
diff --git a/docs/source/index.md b/docs/source/index.md
index 4f980bcc30..942820bc25 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -39,15 +39,17 @@ At the center of Mooncake is a KVCache-centric scheduler that balances effective
 
 <h2 id="updates">🔄 Updates</h2>
 
+- **Aug 20, 2026**: Mooncake is integrated into [Miles](https://github.com/radixark/miles) as a rollout data-transfer backend for the fragmented, heterogeneous data moving between rollout and training in disaggregated RL. Blogs: [KVCache.AI](https://kvcache.ai/blog/mooncake-rl-rollout-data-transfer/), [lmsys](https://www.lmsys.org/blog/2026-08-20-miles-mooncake-rollout-data-transfer).
+- **Aug 17, 2026**: Mooncake is integrated into [Speculators](https://github.com/vllm-project/speculators) as a distributed backend for multi-node online training, efficiently moves hidden-state between vLLM inference workers and Speculators trainers through RDMA, eliminating the need for massive hidden-state storage in offline training. [Benchmark on GB300 NVL72](https://x.com/mgoin_/status/2072785822231728363).
 - **May 7, 2026**: 🚀 [vLLM officially features Mooncake Store](https://vllm.ai/blog/mooncake-store) — a deep dive into how Mooncake's distributed KVCache engine supercharges vLLM inference with high-throughput, memory-efficient, cross-instance KV cache sharing!
 - **Apr 29, 2026**: SGLang introduces [RDMA-based P2P weight transfer for large-scale distributed RL](https://lmsys.org/blog/2026-04-29-p2p-update/) using Mooncake TransferEngine, achieving 7x faster weight updates for the 1T-parameter Kimi-K2 model (53s → 7.2s) with zero-copy RDMA transfer across thousands of GPUs.
 - **Mar 19, 2026**: [TorchSpec: Speculative Decoding Training at Scale](https://pytorch.org/blog/torchspec-speculative-decoding-training-at-scale) is [open sourced](https://github.com/torchspec-project/TorchSpec), using Mooncake to decouple inference and training via efficient hidden states management.
-- **Mar 5, 2026**: [LightX2V](https://github.com/ModelTC/LightX2V/pull/893) now supports disaggregated deployment based on Mooncake, enabling encoder/transformer service decoupling with Mooncake Transfer Engine for high-performance cross-device and cross-machine data transfer.
-- **Feb 25, 2026**: [SGLang](https://github.com/sgl-project/sglang) merged [Encoder Global Cache Manager](https://github.com/sgl-project/sglang/pull/16137), introducing a Mooncake-powered global multimodal embedding cache that enables cross-instance sharing of ViT embeddings to avoid redundant GPU computation.
 
 :::{dropdown} More
 :animate: fade-in
 
+- **Mar 5, 2026**: [LightX2V](https://github.com/ModelTC/LightX2V/pull/893) now supports disaggregated deployment based on Mooncake, enabling encoder/transformer service decoupling with Mooncake Transfer Engine for high-performance cross-device and cross-machine data transfer. Details in [blog](https://light-ai.top/LightX2V-BLOG/posts/Disaggregation/).
+- **Feb 25, 2026**: [SGLang](https://github.com/sgl-project/sglang) merged [Encoder Global Cache Manager](https://github.com/sgl-project/sglang/pull/16137), introducing a Mooncake-powered global multimodal embedding cache that enables cross-instance sharing of ViT embeddings to avoid redundant GPU computation.
 - **Feb 24, 2026**: [vLLM-Omni](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/disaggregated_inference/) introduces disaggregated inference connectors with support for both `MooncakeStoreConnector` and `MooncakeTransferEngineConnector` for multi-node omni-modality pipelines.
 - **Feb 12, 2026**: [Mooncake Joins PyTorch Ecosystem](https://pytorch.org/blog/mooncake-joins-pytorch-ecosystem/) We are thrilled to announce that Mooncake has officially joined the PyTorch Ecosystem!
 - **Jan 28, 2026**: [FlexKV](https://github.com/taco-project/FlexKV), a distributed KV store and cache system from Tencent and NVIDIA in collaboration with the community, now supports [distributed KVCache reuse](https://github.com/taco-project/FlexKV/blob/main/docs/dist_reuse/README_en.md) with the Mooncake Transfer Engine.
@@ -87,8 +89,8 @@ At the center of Mooncake is a KVCache-centric scheduler that balances effective
 :caption: Getting Started
 :maxdepth: 1
 
-getting_started/build
 getting_started/quick-start
+getting_started/build
 
 :::
 
@@ -124,19 +126,15 @@ performance/vllm/index
 :maxdepth: 1
 
 design/architecture
-design/mooncake-store
-design/p2p-store
+design/transfer-engine/index
+design/tent/overview
+design/store/mooncake-store
 design/mooncake-backend-pg
 design/mooncake-ep
-design/transfer-engine/index
+design/conductor/index
+design/mooncake-reshard/index
+design/p2p-store
 design/hicache-design
-design/engram
-design/unified-parallel-tensor-io
-design/tent/overview
-design/tent/tebench
-design/conductor/conductor-architecture-design
-design/ssd-offload
-design/ssd-free-ratio-first-allocation
 :::
 
 % API Documentation
diff --git a/docs/source/performance/mooncake/index.md b/docs/source/performance/mooncake/index.md
index d511245f60..6fd7559b26 100644
--- a/docs/source/performance/mooncake/index.md
+++ b/docs/source/performance/mooncake/index.md
@@ -1,6 +1,6 @@
 # Mooncake Performance
 
-Benchmarks evaluating Mooncake Store's core storage, allocation, and cache hierarchy behavior.
+This section collects Mooncake performance evaluations and benchmark results for Mooncake core components.
 
 | Document | Area | Key Findings |
 |----------|------|---------------|
@@ -8,6 +8,7 @@ Benchmarks evaluating Mooncake Store's core storage, allocation, and cache hiera
 | [Allocator Benchmark](allocator-benchmark-result) | Segment allocation | The optimized OffsetAllocator significantly improves utilization for uniform-size LLM KV cache allocation patterns. |
 | [Allocation Strategy Benchmark](allocation-strategy-benchmark-result) | Allocation routing | Compares random and free-ratio-first allocation across segments, replicas, skewed capacity, and DSA-style KV+indexer workloads. |
 | [SSD Offload Benchmark](ssd-offload-benchmark-results) | Cache hierarchy | SSD offload extends the KV cache hierarchy with NVMe, reducing the performance cliff after DRAM cache capacity is exhausted in long multi-turn conversations. |
+| [Guide for tebench](tebench) | Transfer Engine | End-to-end bandwidth and latency benchmarking for classic TE and TENT backends across block size, batch size, and concurrency. |
 
 :::{toctree}
 :maxdepth: 1
@@ -17,4 +18,5 @@ storage-benchmark
 allocator-benchmark-result
 allocation-strategy-benchmark-result
 ssd-offload-benchmark-results
+tebench
 :::
diff --git a/docs/source/design/tent/tebench.md b/docs/source/performance/mooncake/tebench.md
similarity index 72%
rename from docs/source/design/tent/tebench.md
rename to docs/source/performance/mooncake/tebench.md
index 4e9ce606f7..23c517c056 100644
--- a/docs/source/design/tent/tebench.md
+++ b/docs/source/performance/mooncake/tebench.md
@@ -75,6 +75,15 @@ On the initiator machine:
   --duration=5
 ```
 
+### 3.3 Request Pacing
+
+Use `--request_interval_us=<N>` to add a per-thread delay before each
+transfer batch. The value is in microseconds; `0` disables pacing.
+
+When pacing is enabled, `Avg Lat (us)` includes the pacing gap because it is
+computed from wall-clock runtime, while `Avg Tx (us)` and Tx percentiles only
+measure transfer execution time.
+
 ## 4. Output Metrics
 
 Each output row corresponds to one benchmark configuration.
@@ -84,8 +93,9 @@ Each output row corresponds to one benchmark configuration.
 | `BlkSize (B)`  | Block size per request (bytes)                      |
 | `Batch`        | Number of requests per submission                   |
 | `BW (GB/S)`    | Throughput (total bytes / total time)               |
-| `Avg Lat (us)` | Average end-to-end latency (scaled by thread count) |
-| `Avg Tx (us)`  | Average per-transfer execution time                 |
+| `Avg Inst GB/s` | Average per-transfer instantaneous bandwidth       |
+| `Avg Lat (us)` | Average wall-clock per-operation latency, including pacing or scheduling gaps (scaled by thread count) |
+| `Avg Tx (us)`  | Average per-transfer execution time, excluding gaps |
 | `P99 Tx (us)`  | P99 transfer latency                                |
 | `P999 Tx (us)` | P999 transfer latency                               |
 
@@ -187,6 +197,51 @@ computed from each class's actual transfer size.
 `--qos_classes_json`, and the global `--tent_intent_type`. Non-default
 per-class intents and deadlines require the TENT backend.
 
+### 4.3 Per-Target Metrics
+
+Multi-target runs print one `[target-summary]` line per target. Use
+`--result_output_jsonl=<path>` to also append a schema-versioned JSON record for
+each benchmark configuration. The record keeps the aggregate operation, byte,
+and throughput totals plus each target's segment name, assigned thread count,
+completed operations, transferred bytes, throughput, and latency distribution.
+The aggregate throughput uses the pooled average worker duration, matching the
+existing `BW (GB/s)` table calculation.
+
+Targets with no assigned worker are retained with zero-valued metrics. This
+makes an under-provisioned run (`threads < targets`) visible instead of silently
+dropping targets from the result.
+
+### 4.4 Submit/Wait Split Log
+
+`Avg Tx` is submit plus completion wait in one timer. To separate those
+phases, pass `--split_output_jsonl=<path>` on the **initiator**. Default is
+empty: the transfer loop is unchanged, with no extra clocks or I/O.
+
+When set, each completed transfer appends one JSON line:
+
+```json
+{"batch_size":207360,"submit_us":66874,"wait_us":556363,"polls":201}
+```
+
+| Field | Meaning |
+| ----- | ------- |
+| `submit_us` | Time in `submitTransfer` |
+| `wait_us` | Time from submit return until the batch reports COMPLETED |
+| `polls` | Number of status polls in that wait |
+
+The file is opened once as `std::ofstream` and written with stream buffering. Skip the first
+couple of lines when summarizing; they include warmup. This log is for
+control-path analysis. Do not treat `wait_us` or table `BW` as a substitute
+for an application poll interval.
+
+```bash
+./tebench \
+  --target_seg_name=<SEG> \
+  --backend=classic \
+  --op_type=read \
+  --split_output_jsonl=submit-wait.jsonl
+```
+
 ## 5. Runtime Configuration
 
 This section summarizes the key runtime options that control workload behavior,
@@ -250,7 +305,9 @@ Example:
   thus multiple transports — SHM for DRAM, NVLink for VRAM) concurrently.
   Empty falls back to `--seg_type` (single type, existing behavior). See
   Section 5.8 for usage and the multi-transport configuration it requires.
-* `--target_seg_name` : target segment name (empty → Target mode)
+* `--target_seg_name` : target segment name (empty → Target mode).
+  A comma-separated list enables multi-target initiator mode, and worker
+  threads are distributed across all listed target segments.
 
 **Scan ranges**
 
@@ -266,6 +323,54 @@ A test case is skipped when:
 block_size × batch_size × num_threads > total_buffer_size
 ```
 
+**Multi-target initiator**
+
+Use a comma-separated `--target_seg_name` value when one initiator process
+should send traffic to multiple target segments:
+
+```bash
+./tebench \
+  --backend=tent \
+  --metadata_type=p2p \
+  --target_seg_name=<SEG_A>,<SEG_B>,<SEG_C> \
+  --op_type=read \
+  --start_num_threads=3 \
+  --max_num_threads=3
+```
+
+Thread `i` selects target `i % target_count`. Within the selected target, the
+local target-thread index is `i / target_count`, so increasing the thread count
+spreads traffic across targets before advancing to the next buffer slot inside
+each target. `--target_gpu_id` shifts the per-target buffer slot and does not
+change the target selection order.
+
+For multi-node benchmarks, tebench intentionally stays at the endpoint level:
+each process publishes its own segment, and an external launcher decides which
+target segment list each initiator receives. This keeps M-to-N, fan-out,
+incast, and all-to-all topologies as different launch configurations over the
+same comma-separated `--target_seg_name` primitive.
+
+For multiple initiator processes sharing the same target segment, use
+`--target_offset` and `--target_range_size` to partition the remote address
+space. The range size is relative to each initiator; tebench also validates that
+`target_offset + relative_offset + transfer_size` stays inside the actual target
+buffer.
+
+```bash
+# Initiator 0 uses [0, 512MiB)
+./tebench --target_seg_name=<SEG> --target_offset=0 --target_range_size=536870912
+
+# Initiator 1 uses [512MiB, 1GiB)
+./tebench --target_seg_name=<SEG> --target_offset=536870912 --target_range_size=536870912
+```
+
+For read-only verification with multiple readers, first write deterministic data
+using `--op_type=write_seed`, then run readers with `--op_type=read_verify`
+against the same target range. `read_verify` performs pure READs and validates
+the local buffer without modifying the remote data. Do not combine these modes
+with `--check_consistency`; `--check_consistency` remains the existing
+WRITE→READ self-check mode.
+
 ---
 
 ### 5.5 GPU Affinity
@@ -294,6 +399,9 @@ gpu_id + thread_id
   is explicitly enabled or disabled by tebench — the engine reads the
   transport enable list from the `MC_TENT_CONF` config file (see Section
   5.8 for multi-transport scenarios).
+  Classic `--backend=classic --xport_type=shm` also uses this flag: DRAM
+  buffers come from POSIX shm and are `mbind`'d onto the same NUMA node as
+  `numa_alloc_onnode` before registering `cpu:<node>`.
 * `--tent_intent_type` : attach a standard transfer intent to every request,
   such as `foreground_get`, `background_prefetch`, or `checkpoint`. This is
   useful for validating intent-specific transport and QoS policy selection.
@@ -311,6 +419,10 @@ gpu_id + thread_id
 * `--qos_link_capacity_gbps` : measured usable link capacity in decimal GB/s
 * `--qos_output_jsonl` : append one schema-versioned JSON object per benchmark
   configuration
+* `--result_output_jsonl` : append aggregate and per-target metrics for each
+  benchmark configuration
+* `--split_output_jsonl` : initiator-only per-transfer submit/wait JSONL
+  described in Section 4.4; empty disables it
 
 QoS mode intentionally requires a fixed thread count. Sweep offered load by
 running explicit cases with different class thread allocations so every output
diff --git a/docs/source/performance/vllm/vllm-v1-pd-performance.md b/docs/source/performance/vllm/vllm-v1-pd-performance.md
index 8780b3a4e5..f643fbaa2c 100644
--- a/docs/source/performance/vllm/vllm-v1-pd-performance.md
+++ b/docs/source/performance/vllm/vllm-v1-pd-performance.md
@@ -84,6 +84,12 @@ python tests/v1/kv_connector/nixl_integration/toy_proxy_server.py \
   --decoder-host 10.0.28.202 --decoder-port 8020
 ```
 
+> NOTE: These commands reproduce the benchmark on vLLM 0.11.2.dev358, which
+> predates the bootstrap contract
+> ([vllm-project/vllm#31034](https://github.com/vllm-project/vllm/pull/31034)).
+> For current vLLM, see the
+> [PD disaggregation deployment guide](../../deployment/integrations/vllm/disagg-prefill-decode.md).
+
 ### Benchmark Script
 
 We used `vllm bench serve` to generate traffic with varying prompt lengths.
diff --git a/docs/source/troubleshooting/pg-ep-troubleshooting.md b/docs/source/troubleshooting/pg-ep-troubleshooting.md
index 684e08f993..a4cb3ed708 100644
--- a/docs/source/troubleshooting/pg-ep-troubleshooting.md
+++ b/docs/source/troubleshooting/pg-ep-troubleshooting.md
@@ -1,7 +1,7 @@
 # Mooncake PG/EP Troubleshooting
 
 This page covers common setup, import, runtime, and recovery issues for
-Mooncake Backend (PG) and Mooncake EP.
+Mooncake PG and Mooncake EP.
 
 ## Import fails with a PyTorch version error
 
@@ -41,80 +41,25 @@ Fixes:
 3. Make sure the Python environment used at runtime is the same one used for the
    build.
 
-## `activeRanks must be int` or device mismatch
+## `dist.get_world_size()` differs from the number of active ranks
 
-Symptoms:
-
-```text
-activeRanks must be int.
-activeRanks must be on CPU.
-activeRanks must be on GPU.
-activeRanks must be sized to max_world_size when max_world_size is set
-```
-
-Causes and fixes:
-
-- Use `torch.int32`, not `bool`, `int64`, or floating-point types.
-- For `backend="mooncake"`, put `active_ranks` on the accelerator device.
-- For `backend="mooncake-cpu"`, put `active_ranks` on CPU.
-- If `max_world_size` is set, allocate `active_ranks` with length
-  `max_world_size`, even if the initial visible `world_size` is smaller.
-
-Examples:
-
-```python
-# CUDA / accelerator backend
-active_ranks = torch.ones(max_world_size, dtype=torch.int32, device="cuda")
-
-# CPU backend
-active_ranks = torch.ones(max_world_size, dtype=torch.int32)
-```
-
-## `dist.get_world_size()` is smaller than `max_world_size`
-
-This is expected. Mooncake PG distinguishes reserved capacity from visible active
-membership:
+Mooncake PG preserves stable in-group rank slots. Consequently:
 
-- `max_world_size` reserves future rank slots.
-- `dist.get_world_size()` returns the visible active size.
-- Reserved ranks are inactive until `recover_ranks()` activates them.
+- `max_group_size` is the fixed slot capacity;
+- `dist.get_world_size()` is the highest active in-group rank plus one;
+- holes below that extent remain visible in the rank space but are skipped by
+  the active mask.
 
 Use `pg.get_active_ranks(backend)` to inspect the current backend mask.
 
-## `get_peer_state()` or `join_group()` hangs
+## `join_group()` hangs or activation times out
 
 Common causes:
 
-- Healthy ranks are not all calling `get_peer_state()` in the same order.
-- The joining rank did not initialize with `is_extension=True`.
-- `max_world_size` / rank numbering differs between healthy and joining ranks.
-- Subgroups were created in different orders on healthy and joining processes.
-- The joining process has not published peer metadata yet.
-- Network device filters differ across ranks.
-
-Debug checklist:
-
-1. Confirm all ranks use the same rendezvous address and store.
-2. Print rank, visible `world_size`, and `max_world_size` at initialization.
-3. Confirm `active_ranks` length and values on every rank.
-4. Verify healthy ranks poll the same `join_ranks` list.
-5. For subgroup recovery, confirm every rank calls `dist.new_group()` in the same
-   order.
-6. If using RDMA, set the same HCA whitelist on every rank.
-
-## Newly extended ranks participate too early
-
-After `pg.extend_group_size_to(backend, new_size)`, new ranks are reserved but
-inactive. They should not participate in collectives until healthy ranks call
-`pg.recover_ranks(backend, ranks)`.
-
-If a new rank appears to participate early, check whether:
-
-- `active_ranks` was initialized with `1` for future ranks without masking them
-  through the backend protocol;
-- the application called collectives on the joining process before
-  `pg.join_group()` returned;
-- different ranks used inconsistent `max_world_size` or rank IDs.
+- No existing rank submitted `activate_ranks()` / `recover_ranks()` after the
+  joining process entered `join_group()`.
+- The future active set is not mutually connected, so the activation proposal
+  remains pending until timeout.
 
 ## EP dispatch/combine timeout marks a rank inactive
 
@@ -240,7 +185,7 @@ python mooncake-pg/benchmark/pgbench.py \
   --collective all_reduce --backend mooncake --device cuda -g 2 -b 8 -e 1M -f 2
 
 # EP grid test
-python mooncake-ep/tests/test_ep_grid.py
+python python/tests/ep/test_ep_grid.py
 ```
 
 Adapt process counts, device filters, and launchers to the target cluster.
diff --git a/docs/source/zh_archive/build.md b/docs/source/zh_archive/build.md
index 62ff9d2ee4..1287749f71 100644
--- a/docs/source/zh_archive/build.md
+++ b/docs/source/zh_archive/build.md
@@ -71,7 +71,7 @@
                    libnuma-dev \
                    libcurl4-openssl-dev \
                    libhiredis-dev
-    
+
     # For centos/alibaba linux os
     yum install cmake \
                 gflags-devel \
@@ -157,17 +157,7 @@
     make -j
     ```
 
-7. 安装 yalantinglibs
-    ```bash
-    git clone https://github.com/alibaba/yalantinglibs.git
-    cd yalantinglibs
-    mkdir build && cd build
-    cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-    make -j$(nproc)
-    make install
-    ```
-
-8. 进入项目根目录，运行下列命令进行编译
+7. 进入项目根目录，运行下列命令进行编译
    ```bash
    mkdir build
    cd build
@@ -175,7 +165,7 @@
    make -j
    ```
 
-9. 安装 Mooncake python 包和 mooncake_master 可执行文件
+8. 安装 Mooncake python 包和 mooncake_master 可执行文件
    ```bash
    make install
    ```
@@ -193,6 +183,7 @@
 - `-DNEUWARE_ROOT=/path/to/neuware`: 在 `-DUSE_MLU=ON` 时覆盖默认 Neuware SDK 根路径；未设置时使用 `NEUWARE_HOME` 或 `/usr/local/neuware`。
 - `-DMLU_INCLUDE_DIR=/path/to/include` / `-DMLU_LIB_DIR=/path/to/lib64`: 在 `-DUSE_MLU=ON` 时覆盖 Neuware 头文件与库目录。
 - `-DUSE_HIP=[ON|OFF]`: 通过 HIP/ROCm 启用对 AMD GPU 的支持
+- `-DUSE_SHCA=[ON|OFF]`: 启用 ScaleFabric SHCA InfiniBand 支持。默认 OFF；仅支持 Transfer Engine/TENT RDMA 路径，不支持 Mooncake-EP IBGDA；SHCA 构建下不支持 `MC_RPC_PROTOCOL=rdma`。
 - `-DUSE_HYGON=[ON|OFF]`: 通过 DTK SDK 启用对海光 DCU 的支持。默认 OFF；使用 CUDA 兼容运行时。
 - `-DDTK_ROOT=/path/to/dtk`: 在 `-DUSE_HYGON=ON` 时覆盖默认 DTK SDK 根路径；未设置时使用 `DTK_HOME` 或 `/opt/dtk`。
 - `-DDTK_INCLUDE_DIR=/path/to/include` / `-DDTK_LIB_DIR=/path/to/lib64`: 在 `-DUSE_HYGON=ON` 时覆盖 DTK 头文件与库目录。
@@ -253,4 +244,3 @@ cd /app/build/mooncake-transfer-engine/example
 --ulimit memlock=-1 解除内存锁定限制，RDMA 操作需要
 
 --net=host 让容器使用宿主机的网络命名空间
-
diff --git a/docs/source/zh_archive/mooncake-store.md b/docs/source/zh_archive/mooncake-store.md
index aade0b725d..b5cffe90d4 100644
--- a/docs/source/zh_archive/mooncake-store.md
+++ b/docs/source/zh_archive/mooncake-store.md
@@ -103,7 +103,8 @@ tl::expected<void, ErrorCode> Put(const ObjectKey& key,
 ```C++
 struct ReplicateConfig {
     size_t replica_num{1};                    // 对象的总副本数
-    bool with_soft_pin{false};               // 是否为该对象启用软固定机制
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE}; // 软固定状态转换
+    std::optional<uint64_t> soft_pin_ttl_ms{}; // ENABLE 时可覆盖默认 TTL
     std::string preferred_segment{};         // 首选的分配段
 };
 ```
@@ -628,11 +629,15 @@ virtual tl::expected<std::vector<Replica>, ErrorCode> Allocate(
 
 对于重要且频繁使用的对象，例如 system prompt，Mooncake Store 提供了软固定（soft pin）机制。在执行 `Put` 操作时，可以选择为特定的对象开启软固定机制。在执行替换任务时，系统会优先替换未被软固定的对象。仅当内存不足且没有其他对象可以被替换时，才会替换被软固定的对象。
 
-如果某个软固定的对象长时间未被访问，其软固定状态将被解除。而后当该对象再次被访问时，它将自动重新进入软固定状态。
+soft pin 生命周期从首个副本变为可读时开始。deadline 到达后，对象降级为普通 Cache；后续访问只授予普通读租约，不会重新启用 soft pin。后续写入仍可显式重新启用。
 
-`master_service` 中有两个与软固定机制相关的启动参数：
+soft pin 是仅在运行时生效的淘汰优先级状态，不会持久化到快照或 HA OpLog。恢复或 Standby 提升后，恢复出的对象将降级为普通 Cache；快照中的兼容字段仅用于保持格式，恢复时会被忽略。
 
-* `default_kv_soft_pin_ttl`：表示一个被软固定的对象在多长时间（毫秒）未被访问后会自动解除软固定状态。默认值为`30 分钟`。
+`master_service` 中有三个与软固定机制相关的启动参数：
+
+* `default_kv_soft_pin_ttl`：未显式传入 TTL 时使用的固定软固定生命周期。默认值为 `30 分钟`，访问不会续期。
+
+* `max_kv_soft_pin_ttl`：Master 接受的请求级 soft pin TTL 上限。默认值为 `24 小时`。
 
 * `allow_evict_soft_pinned_objects`：是否允许替换已被软固定的对象。默认值为 `true`。
 
@@ -661,7 +666,8 @@ Mooncake Store 提供了**首选段分配**功能，允许用户为对象分配
 ```cpp
 struct ReplicateConfig {
     size_t replica_num{1};                    // 对象的总副本数
-    bool with_soft_pin{false};               // 是否为该对象启用软固定机制
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE}; // 软固定状态转换
+    std::optional<uint64_t> soft_pin_ttl_ms{}; // ENABLE 时可覆盖默认 TTL
     std::string preferred_segment{};         // 首选的分配段
 };
 ```
diff --git a/extern/yalantinglibs b/extern/yalantinglibs
deleted file mode 160000
index 7801bc9ad9..0000000000
--- a/extern/yalantinglibs
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit 7801bc9ad9021781f15217552214e325a1cf7373
diff --git a/monitoring/grafana/dashboards/mooncake.json b/monitoring/grafana/dashboards/mooncake.json
index 77933094f5..31ffa446a8 100644
--- a/monitoring/grafana/dashboards/mooncake.json
+++ b/monitoring/grafana/dashboards/mooncake.json
@@ -196,8 +196,9 @@
       "targets": [
         { "expr": "rate(master_put_start_failures_total[5m])", "legendFormat": "PutStart Fail", "refId": "A" },
         { "expr": "rate(master_put_start_alloc_failures_total[5m])", "legendFormat": "PutStart Alloc Fail", "refId": "B" },
-        { "expr": "rate(master_put_end_failures_total[5m])", "legendFormat": "PutEnd Fail", "refId": "C" },
-        { "expr": "rate(master_put_revoke_failures_total[5m])", "legendFormat": "PutRevoke Fail", "refId": "D" }
+        { "expr": "rate(master_put_start_object_already_exists_total[5m])", "legendFormat": "PutStart Already Exists", "refId": "C" },
+        { "expr": "rate(master_put_end_failures_total[5m])", "legendFormat": "PutEnd Fail", "refId": "D" },
+        { "expr": "rate(master_put_revoke_failures_total[5m])", "legendFormat": "PutRevoke Fail", "refId": "E" }
       ],
       "title": "Put Failure Rates",
       "type": "timeseries"
@@ -864,11 +865,12 @@
       "options": { "legend": { "calcs": ["mean", "lastNotNull"], "displayMode": "table", "placement": "bottom" }, "tooltip": { "mode": "multi", "sort": "desc" } },
       "targets": [
         { "expr": "rate(master_batch_put_start_items_total[5m])", "legendFormat": "BatchPutStart Items", "refId": "A" },
-        { "expr": "rate(master_batch_put_end_items_total[5m])", "legendFormat": "BatchPutEnd Items", "refId": "B" },
-        { "expr": "rate(master_batch_get_replica_list_items_total[5m])", "legendFormat": "BatchGetRL Items", "refId": "C" },
-        { "expr": "rate(master_batch_exist_key_items_total[5m])", "legendFormat": "BatchExistKey Items", "refId": "D" },
-        { "expr": "rate(master_batch_query_ip_items_total[5m])", "legendFormat": "BatchQueryIp Items", "refId": "E" },
-        { "expr": "rate(master_batch_replica_clear_items_total[5m])", "legendFormat": "BatchReplicaClear Items", "refId": "F" }
+        { "expr": "rate(master_batch_put_start_object_already_exists_total[5m])", "legendFormat": "BatchPutStart Already Exists Items", "refId": "B" },
+        { "expr": "rate(master_batch_put_end_items_total[5m])", "legendFormat": "BatchPutEnd Items", "refId": "C" },
+        { "expr": "rate(master_batch_get_replica_list_items_total[5m])", "legendFormat": "BatchGetRL Items", "refId": "D" },
+        { "expr": "rate(master_batch_exist_key_items_total[5m])", "legendFormat": "BatchExistKey Items", "refId": "E" },
+        { "expr": "rate(master_batch_query_ip_items_total[5m])", "legendFormat": "BatchQueryIp Items", "refId": "F" },
+        { "expr": "rate(master_batch_replica_clear_items_total[5m])", "legendFormat": "BatchReplicaClear Items", "refId": "G" }
       ],
       "title": "Batch Operation Item Throughput",
       "type": "timeseries"
diff --git a/mooncake-common/FindGLOG.cmake b/mooncake-common/FindGLOG.cmake
index f7c770c1e4..54fd77d7e9 100644
--- a/mooncake-common/FindGLOG.cmake
+++ b/mooncake-common/FindGLOG.cmake
@@ -1,30 +1,71 @@
 find_package(glog QUIET CONFIG)
 
+# Track the detected glog version so we can decide whether newer public APIs
+# (e.g. google::IsGoogleLoggingInitialized(), added in glog 0.6.0) are
+# available. Different distros ship different glog versions, so relying on that
+# symbol unconditionally breaks builds against glog < 0.6.0.
+set(GLOG_DETECTED_VERSION "")
+
 if(TARGET glog::glog)
+  set(GLOG_FOUND TRUE)
+  set(GLOG_TARGET glog::glog)
+  if(DEFINED glog_VERSION)
+    set(GLOG_DETECTED_VERSION "${glog_VERSION}")
+  endif()
+else()
+  find_package(PkgConfig QUIET)
+  if(PKG_CONFIG_FOUND)
+    pkg_check_modules(PC_GLOG QUIET libglog)
+  endif()
+
+  find_path(
+    GLOG_INCLUDE_DIR glog/logging.h
+    HINTS ${PC_GLOG_INCLUDEDIR} ${PC_GLOG_INCLUDE_DIRS}
+    PATHS /usr/include /usr/local/include)
+
+  find_library(
+    GLOG_LIBRARY glog
+    HINTS ${PC_GLOG_LIBDIR} ${PC_GLOG_LIBRARY_DIRS}
+    PATHS /usr/lib /usr/lib64 /usr/local/lib /usr/local/lib64)
+
+  if(GLOG_INCLUDE_DIR AND GLOG_LIBRARY)
     set(GLOG_FOUND TRUE)
+    add_library(glog::glog INTERFACE IMPORTED)
+    target_include_directories(glog::glog INTERFACE ${GLOG_INCLUDE_DIR})
+    target_link_libraries(glog::glog INTERFACE ${GLOG_LIBRARY})
     set(GLOG_TARGET glog::glog)
-else()
-    find_package(PkgConfig QUIET)
-    if(PKG_CONFIG_FOUND)
-        pkg_check_modules(PC_GLOG QUIET libglog)
-    endif()
-
-    find_path(GLOG_INCLUDE_DIR glog/logging.h
-        HINTS ${PC_GLOG_INCLUDEDIR} ${PC_GLOG_INCLUDE_DIRS}
-        PATHS /usr/include /usr/local/include)
-    
-    find_library(GLOG_LIBRARY glog
-        HINTS ${PC_GLOG_LIBDIR} ${PC_GLOG_LIBRARY_DIRS}
-        PATHS /usr/lib /usr/lib64 /usr/local/lib /usr/local/lib64)
-
-    if(GLOG_INCLUDE_DIR AND GLOG_LIBRARY)
-        set(GLOG_FOUND TRUE)
-        add_library(glog::glog INTERFACE IMPORTED)
-        target_include_directories(glog::glog INTERFACE ${GLOG_INCLUDE_DIR})
-        target_link_libraries(glog::glog INTERFACE ${GLOG_LIBRARY})
-        set(GLOG_TARGET glog::glog)
-    endif()
+  endif()
+
+  if(PC_GLOG_VERSION)
+    set(GLOG_DETECTED_VERSION "${PC_GLOG_VERSION}")
+  endif()
+endif()
+
+# The version comes from CONFIG (glog_VERSION) or pkg-config (PC_GLOG_VERSION)
+# above. A missing version is treated as "old".
+
+# Only enable the newer API when we can positively confirm glog >= 0.6.0. When
+# the version cannot be determined we conservatively assume it is too old and
+# use the internal-symbol fallback declared in config.cpp. Note: on every glog
+# version, an *unconditional* duplicate InitGoogleLogging() trips a CHECK and
+# abort()s at runtime ("You called InitGoogleLogging() twice!"). Both code paths
+# therefore guard with IsGoogleLoggingInitialized() before initializing; the
+# only difference is where that symbol lives (top-level in >= 0.6.0, the
+# internal namespace otherwise).
+if(TARGET glog::glog)
+  if(GLOG_DETECTED_VERSION AND NOT GLOG_DETECTED_VERSION VERSION_LESS "0.6.0")
+    target_compile_definitions(glog::glog
+                               INTERFACE MOONCAKE_GLOG_HAS_IS_INITIALIZED=1)
+    message(STATUS "glog ${GLOG_DETECTED_VERSION}: "
+                   "IsGoogleLoggingInitialized() available")
+  else()
+    target_compile_definitions(glog::glog
+                               INTERFACE MOONCAKE_GLOG_HAS_IS_INITIALIZED=0)
+    message(STATUS "glog version "
+                   "'${GLOG_DETECTED_VERSION}' (< 0.6.0 or unknown): "
+                   "IsGoogleLoggingInitialized() unavailable")
+  endif()
 endif()
 
 include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(GLOG DEFAULT_MSG GLOG_TARGET)
\ No newline at end of file
+find_package_handle_standard_args(GLOG DEFAULT_MSG GLOG_TARGET)
diff --git a/mooncake-common/FindYLT.cmake b/mooncake-common/FindYLT.cmake
new file mode 100644
index 0000000000..e36d4d66da
--- /dev/null
+++ b/mooncake-common/FindYLT.cmake
@@ -0,0 +1,30 @@
+include_guard(GLOBAL)
+
+include(FetchContent)
+
+if(POLICY CMP0135)
+  cmake_policy(SET CMP0135 NEW)
+endif()
+
+set(YLT_ENABLE_IBV ON CACHE BOOL "Enable yalantinglibs ibverbs support")
+
+set(YLT_COMMIT 7801bc9ad9021781f15217552214e325a1cf7373)
+FetchContent_Declare(
+  yalantinglibs
+  URL ${GH_MIRROR}https://github.com/alibaba/yalantinglibs/archive/${YLT_COMMIT}.tar.gz
+  URL_HASH SHA256=2a4b93c256c09fa84e1507bf4d5b33571ee47a4e2c65316ca255680ad3cdfc1e
+)
+
+# Exclude from install for CMake before 3.28
+FetchContent_GetProperties(yalantinglibs)
+FetchContent_Populate(yalantinglibs)
+add_subdirectory(
+  ${yalantinglibs_SOURCE_DIR}
+  ${yalantinglibs_BINARY_DIR}
+  EXCLUDE_FROM_ALL
+)
+
+# Suppress warnings for CMake before 3.25
+get_target_property(YLT_INCL_DIRS yalantinglibs INTERFACE_INCLUDE_DIRECTORIES)
+set_target_properties(yalantinglibs PROPERTIES
+  INTERFACE_SYSTEM_INCLUDE_DIRECTORIES "${YLT_INCL_DIRS}")
diff --git a/mooncake-common/common.cmake b/mooncake-common/common.cmake
index 73c3110811..5e1e9cccaf 100644
--- a/mooncake-common/common.cmake
+++ b/mooncake-common/common.cmake
@@ -55,7 +55,10 @@ include(${CMAKE_CURRENT_LIST_DIR}/limit_jobs.cmake)
 
 option(ENABLE_SCCACHE "Whether to open sccache" OFF)
 if(ENABLE_SCCACHE)
-  find_program(SCCACHE sccache REQUIRED)
+  find_program(SCCACHE sccache)
+  if(NOT SCCACHE)
+    message(FATAL_ERROR "sccache executable not found")
+  endif()
 endif()
 if(SCCACHE AND ENABLE_SCCACHE)
   message(STATUS "Building with SCCACHE enabled")
@@ -74,7 +77,8 @@ if(BUILD_UNIT_TESTS)
 endif()
 option(BUILD_BENCHMARK "Build benchmarks" ON)
 option(USE_CUDA "option for enabling gpu features for NVIDIA GPU" OFF)
-option(USE_NCCL_DEVICE "option for enabling the NCCL DeviceTransport backend" OFF)
+option(USE_NCCL_DEVICE "option for enabling the NCCL DeviceTransport backend"
+       OFF)
 option(USE_NCCL_HOST "option for enabling the NCCL host RMA transport" OFF)
 option(USE_MLU "option for enabling Cambricon MLU features" OFF)
 option(USE_MUSA "option for enabling gpu features for MTHREADS GPU" OFF)
@@ -83,6 +87,20 @@ option(USE_HIP "option for enabling gpu features for AMD GPU" OFF)
 option(USE_HYGON "option for enabling gpu features for Hygon DCU with DTK" OFF)
 option(USE_COREX "option for enabling gpu features for Iluvatar CoreX" OFF)
 option(USE_SUPA "option for enabling gpu features for Biren GPU with SUPA" OFF)
+option(USE_RISCV "Enable RISC-V build compatibility settings" OFF)
+if(USE_RISCV)
+  if(NOT CMAKE_SYSTEM_PROCESSOR MATCHES "^riscv")
+    message(
+      WARNING
+        "USE_RISCV is enabled, but CMAKE_SYSTEM_PROCESSOR is '${CMAKE_SYSTEM_PROCESSOR}'"
+    )
+  endif()
+  # Define this before any pybind11 module is created. Otherwise pybind11 adds
+  # its default full-LTO target, which is prohibitively resource-intensive on
+  # RISC-V build hosts.
+  set(CMAKE_INTERPROCEDURAL_OPTIMIZATION OFF)
+  message(STATUS "RISC-V: IPO disabled for Mooncake Python extensions")
+endif()
 option(USE_NVMEOF "option for using NVMe over Fabric" OFF)
 option(USE_TCP "option for using TCP transport" ON)
 option(USE_BAREX "option for using accl-barex transport" OFF)
@@ -97,10 +115,17 @@ option(USE_EFA "option for using AWS EFA transport" OFF)
 option(USE_UB "option for using UB protocol transport" OFF)
 option(USE_SUNRISE
        "option for enabling gpu features for Sunrise GPU with Tang runtime" OFF)
-option(USE_TPU
-       "option for enabling TPU (PJRT) staging support in TENT; the PJRT adapter is loaded at runtime via dlopen, no build-time SDK required"
-       OFF)
+option(
+  USE_TPU
+  "option for enabling TPU (PJRT) staging support in TENT; the PJRT adapter is loaded at runtime via dlopen, no build-time SDK required"
+  OFF)
+option(
+  USE_XPU
+  "option for enabling Intel XPU (oneAPI SYCL) staging support in TENT; this is a direct-link (native) build that requires USE_TENT and the Intel DPC++ compiler (icpx / IntelLLVM) at build time -- there is no dlopen shim"
+  OFF)
 option(USE_VRAM_SEGMENT "option for vram segment" OFF)
+option(USE_MPCOMM "option for using MPComm transport in TENT" OFF)
+option(USE_SHCA "option for using ScaleFabric SHCA InfiniBand" OFF)
 
 if(USE_UB)
   add_compile_definitions(USE_UB)
@@ -159,7 +184,7 @@ option(USE_ETCD_LEGACY "option for enable etcd based on etcd-cpp-api-v3" OFF)
 option(USE_REDIS "option for enable redis as metadata server" OFF)
 option(USE_HTTP "option for enable http as metadata server" ON)
 option(WITH_RUST_EXAMPLE
-       "build the Rust interface and sample code for the transfer engine" OFF)
+       "build the Transfer Engine Rust library and sample code" OFF)
 option(WITH_METRICS "enable metrics and metrics reporting thread" ON)
 option(USE_3FS "option for using 3FS storage backend" OFF)
 option(USE_EVENT_DRIVEN_COMPLETION
@@ -207,7 +232,7 @@ if(USE_MNNVL)
   message(STATUS "Multi-Node NVLink support is enabled")
 endif()
 
-if (USE_VRAM_SEGMENT)
+if(USE_VRAM_SEGMENT)
   set(USE_CUDA ON)
   add_compile_definitions(USE_VRAM_SEGMENT)
   message(STATUS "VRAM SEGMENT is ON")
@@ -227,8 +252,7 @@ endif()
 
 if(USE_NCCL_DEVICE OR USE_NCCL_HOST)
   if(NOT USE_CUDA)
-    message(FATAL_ERROR
-      "USE_NCCL_DEVICE and USE_NCCL_HOST require USE_CUDA=ON")
+    message(FATAL_ERROR "USE_NCCL_DEVICE and USE_NCCL_HOST require USE_CUDA=ON")
   endif()
   list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR})
   find_package(NCCLDevice 2.30.4 REQUIRED MODULE)
@@ -236,14 +260,15 @@ endif()
 
 if(USE_NCCL_DEVICE)
   add_compile_definitions(USE_NCCL_DEVICE)
-  message(STATUS
-    "NCCL DeviceTransport support is enabled (NCCL ${NCCLDevice_VERSION})")
+  message(
+    STATUS
+      "NCCL DeviceTransport support is enabled (NCCL ${NCCLDevice_VERSION})")
 endif()
 
 if(USE_NCCL_HOST)
   add_compile_definitions(USE_NCCL_HOST)
-  message(STATUS
-    "NCCL host RMA transport is enabled (NCCL ${NCCLDevice_VERSION})")
+  message(
+    STATUS "NCCL host RMA transport is enabled (NCCL ${NCCLDevice_VERSION})")
 endif()
 
 if(USE_SUPA)
@@ -279,6 +304,34 @@ if(USE_TPU)
   message(STATUS "TPU (PJRT) staging support is enabled")
 endif()
 
+if(USE_XPU)
+  # Every XPU source file lives under mooncake-transfer-engine/tent, which is
+  # only added when USE_TENT is ON. Without this guard -DUSE_XPU=ON configures
+  # and builds cleanly while compiling no XPU code at all.
+  if(NOT USE_TENT)
+    message(
+      FATAL_ERROR
+        "USE_XPU=ON requires USE_TENT=ON: all XPU support lives in TENT. Re-run cmake with -DUSE_TENT=ON."
+    )
+  endif()
+  # The XPU platform links oneAPI SYCL directly (native / direct-link): its
+  # translation units include <sycl/sycl.hpp> and are compiled with -fsycl, so
+  # the whole build must use the Intel DPC++ compiler. Configure with icpx, e.g.
+  # CXX=icpx cmake -DUSE_TENT=ON -DUSE_XPU=ON ... (from an intel/oneapi-basekit
+  # or intel/pytorch:xpu image, or after `source /opt/intel/oneapi/setvars.sh`).
+  if(NOT CMAKE_CXX_COMPILER_ID MATCHES "IntelLLVM" AND NOT CMAKE_CXX_COMPILER
+                                                       MATCHES "icpx|icx|dpcpp")
+    message(
+      FATAL_ERROR
+        "USE_XPU=ON requires the Intel DPC++ compiler (icpx): the XPU platform "
+        "links SYCL directly. Re-run cmake with CXX=icpx (detected "
+        "'${CMAKE_CXX_COMPILER_ID}' at ${CMAKE_CXX_COMPILER}).")
+  endif()
+  add_compile_definitions(USE_XPU)
+  message(
+    STATUS "Intel XPU (oneAPI SYCL, direct-link) staging support is enabled")
+endif()
+
 if(NOT DEFINED NEUWARE_ROOT OR NEUWARE_ROOT STREQUAL "")
   if(DEFINED ENV{NEUWARE_HOME} AND NOT "$ENV{NEUWARE_HOME}" STREQUAL "")
     set(NEUWARE_ROOT
@@ -472,6 +525,85 @@ if(USE_CXL)
   message(STATUS "CXL support is enabled")
 endif()
 
+if(USE_MPCOMM)
+  if(NOT DEFINED MPCOMM_ROOT)
+    message(
+      FATAL_ERROR
+        "USE_MPCOMM=ON requires MPCOMM_ROOT to point at the MPComm install prefix, e.g. -DMPCOMM_ROOT=/opt/mpcomm"
+    )
+  endif()
+
+  # Oldest MPComm whose ABI this transport is written against, and the major it
+  # is written for - MPComm's own package config declares SameMajorVersion
+  # compatibility, so a different major is an ABI break by its own definition. A
+  # bare find_library() can express neither, since it accepts whatever
+  # libmpcomm.so happens to be on the prefix.
+  #
+  # Queried without a version so that an install that is present but too old is
+  # reported as such, rather than looking the same as no package config at all.
+  #
+  # find_package() also consults an upper-case <PACKAGENAME>_ROOT variable, and
+  # for this package that name is exactly our own MPCOMM_ROOT, which makes CMake
+  # 3.27+ emit a CMP0144 developer warning. Opting into the new behaviour is
+  # what we want anyway - the prefix really is where the package lives - and the
+  # setting is scoped so that no other find_package() is affected.
+  set(MPCOMM_MINIMUM_VERSION 1.4)
+  set(MPCOMM_SUPPORTED_MAJOR 1)
+  if(POLICY CMP0144)
+    cmake_policy(PUSH)
+    cmake_policy(SET CMP0144 NEW)
+  endif()
+  find_package(mpcomm CONFIG QUIET HINTS ${MPCOMM_ROOT})
+  if(POLICY CMP0144)
+    cmake_policy(POP)
+  endif()
+  if(mpcomm_FOUND)
+    if(mpcomm_VERSION VERSION_LESS MPCOMM_MINIMUM_VERSION)
+      message(
+        FATAL_ERROR
+          "MPComm ${mpcomm_VERSION} found under MPCOMM_ROOT=${MPCOMM_ROOT} is too old; this transport requires >= ${MPCOMM_MINIMUM_VERSION}"
+      )
+    endif()
+    if(NOT mpcomm_VERSION_MAJOR EQUAL MPCOMM_SUPPORTED_MAJOR)
+      message(
+        FATAL_ERROR
+          "MPComm ${mpcomm_VERSION} has major ${mpcomm_VERSION_MAJOR}, but this transport is written against major ${MPCOMM_SUPPORTED_MAJOR}; MPComm declares SameMajorVersion compatibility, so this is an ABI break"
+      )
+    endif()
+  endif()
+
+  find_path(MPCOMM_INCLUDE_DIR mpcomm.h HINTS ${MPCOMM_ROOT}/include)
+  # Resolve to an absolute library path instead of relying on -L/-l. Link
+  # directories are usage requirements and get stripped when a dependency is
+  # consumed through $<LINK_ONLY:...> (mooncake_store links transfer_engine
+  # PRIVATE, so mooncake_master would otherwise see -lmpcomm without the
+  # matching -L). An absolute path survives that stripping.
+  find_library(MPCOMM_LIBRARY mpcomm HINTS ${MPCOMM_ROOT}/lib
+                                           ${MPCOMM_ROOT}/lib64)
+  if(NOT MPCOMM_INCLUDE_DIR OR NOT MPCOMM_LIBRARY)
+    message(
+      FATAL_ERROR
+        "MPComm not found under MPCOMM_ROOT=${MPCOMM_ROOT} (expected ${MPCOMM_ROOT}/include/mpcomm.h and ${MPCOMM_ROOT}/lib/libmpcomm.so)"
+    )
+  endif()
+  add_compile_definitions(USE_MPCOMM)
+  message(STATUS "MPComm transport is enabled")
+  message(STATUS "  MPComm include: ${MPCOMM_INCLUDE_DIR}")
+  message(STATUS "  MPComm library: ${MPCOMM_LIBRARY}")
+  if(mpcomm_FOUND)
+    message(STATUS "  MPComm version: ${mpcomm_VERSION}")
+  else()
+    # No package config under the prefix - for example a tree where only the
+    # headers and the library were copied into place. Say so rather than imply
+    # the version was verified: the transport still builds, but an ABI mismatch
+    # would then only surface at run time.
+    message(
+      STATUS
+        "  MPComm version: unknown (no CMake package config under ${MPCOMM_ROOT}; requires >= ${MPCOMM_MINIMUM_VERSION})"
+    )
+  endif()
+endif()
+
 if(USE_TCP)
   add_compile_definitions(USE_TCP)
 endif()
@@ -581,5 +713,62 @@ if(NOT TARGET gflags::gflags)
     endif()
   endforeach()
 endif()
-find_package(yalantinglibs CONFIG REQUIRED)
-add_compile_definitions(YLT_ENABLE_IBV)
+
+set(GH_MIRROR "")
+if(DEFINED ENV{ASCEND_GITHUB_MIRROR_URLS})
+  set(GH_MIRROR $ENV{ASCEND_GITHUB_MIRROR_URLS})
+endif()
+if(GH_MIRROR)
+  message(STATUS "Using Github mirror: ${GH_MIRROR}")
+endif()
+
+include(${CMAKE_CURRENT_LIST_DIR}/FindYLT.cmake)
+
+option(USE_FLAGCX "option for using FlagCX-backed transport (cross-vendor CCL)"
+       OFF)
+if(USE_FLAGCX)
+  if(NOT FLAGCX_HOME)
+    if(DEFINED ENV{FLAGCX_HOME})
+      set(FLAGCX_HOME $ENV{FLAGCX_HOME})
+    else()
+      set(FLAGCX_HOME "$ENV{HOME}/FlagCX/build")
+    endif()
+  endif()
+  find_path(
+    FLAGCX_INCLUDE_DIR
+    NAMES flagcx_p2p.h
+    HINTS "${FLAGCX_HOME}/include")
+  find_library(
+    FLAGCX_LIBRARY
+    NAMES flagcx
+    HINTS "${FLAGCX_HOME}/lib" "${FLAGCX_HOME}/lib64")
+  if(NOT FLAGCX_INCLUDE_DIR)
+    message(
+      FATAL_ERROR
+        "USE_FLAGCX=ON but flagcx_p2p.h was not found (set -DFLAGCX_HOME=...)")
+  endif()
+  if(NOT FLAGCX_LIBRARY)
+    message(
+      FATAL_ERROR
+        "USE_FLAGCX=ON but the FlagCX library was not found (set -DFLAGCX_HOME=...)"
+    )
+  endif()
+  if(NOT TARGET FlagCX::flagcx)
+    add_library(FlagCX::flagcx UNKNOWN IMPORTED)
+    set_target_properties(
+      FlagCX::flagcx
+      PROPERTIES IMPORTED_LOCATION "${FLAGCX_LIBRARY}"
+                 INTERFACE_INCLUDE_DIRECTORIES "${FLAGCX_INCLUDE_DIR}")
+  endif()
+  add_compile_definitions(USE_FLAGCX)
+  message(
+    STATUS
+      "FlagCX transport enabled, include=${FLAGCX_INCLUDE_DIR}, library=${FLAGCX_LIBRARY}"
+  )
+endif()
+
+if(USE_SHCA)
+  add_compile_definitions(USE_SHCA)
+else()
+  add_compile_definitions(YLT_ENABLE_IBV)
+endif()
diff --git a/mooncake-common/etcd/CMakeLists.txt b/mooncake-common/etcd/CMakeLists.txt
index 570e8bbf17..0e3d8ceb80 100644
--- a/mooncake-common/etcd/CMakeLists.txt
+++ b/mooncake-common/etcd/CMakeLists.txt
@@ -14,6 +14,13 @@ add_custom_target(
     DEPENDS ${ETCD_WRAPPER_LIB}
 )
 
+if(BUILD_UNIT_TESTS)
+  add_test(
+    NAME etcd_wrapper_go_test
+    COMMAND go test ./...
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+endif()
+
 install(
     FILES ${ETCD_WRAPPER_LIB}
     DESTINATION lib
diff --git a/mooncake-common/etcd/etcd_wrapper.go b/mooncake-common/etcd/etcd_wrapper.go
index 4ac718072c..29dc11bb02 100644
--- a/mooncake-common/etcd/etcd_wrapper.go
+++ b/mooncake-common/etcd/etcd_wrapper.go
@@ -35,6 +35,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -42,6 +43,7 @@ import (
 
 	rpctypes "go.etcd.io/etcd/api/v3/v3rpc/rpctypes"
 	clientv3 "go.etcd.io/etcd/client/v3"
+	"go.etcd.io/etcd/client/v3/concurrency"
 )
 
 // prefixWatchInfo stores cancel function and callback context for a prefix watch
@@ -56,6 +58,44 @@ type prefixWatchInfo struct {
 	brokenNotified bool
 }
 
+type maintenanceSession struct {
+	session *concurrency.Session
+	cancel  context.CancelFunc
+}
+
+func (s *maintenanceSession) close() error {
+	err := s.session.Close()
+	s.cancel()
+	return err
+}
+
+var startMaintenanceSession = func(ctx context.Context, cli *clientv3.Client,
+	ttl int) (*concurrency.Session, error) {
+	return concurrency.NewSession(cli, concurrency.WithTTL(ttl), concurrency.WithContext(ctx))
+}
+
+func newMaintenanceSession(cli *clientv3.Client, ttl int,
+	startupTimeout time.Duration) (*maintenanceSession, error) {
+	ctx, cancel := context.WithCancel(context.Background())
+	timer := time.AfterFunc(startupTimeout, cancel)
+	session, err := startMaintenanceSession(ctx, cli, ttl)
+	timedOut := !timer.Stop()
+	if err != nil {
+		cancel()
+		return nil, err
+	}
+	if session == nil {
+		cancel()
+		return nil, errors.New("maintenance session creation returned nil")
+	}
+	if timedOut {
+		_ = session.Close()
+		cancel()
+		return nil, context.DeadlineExceeded
+	}
+	return &maintenanceSession{session: session, cancel: cancel}, nil
+}
+
 // Use different etcd client so they are not affected by each other,
 // and can be configured separately.
 var (
@@ -69,6 +109,10 @@ var (
 	// keep alive contexts for store
 	storeKeepAliveCtx   = make(map[int64]context.CancelFunc)
 	storeKeepAliveMutex sync.Mutex
+	// maintenance sessions own their keepalive and lease lifecycle in Go.
+	storeMaintenanceSessions   = make(map[int64]*maintenanceSession)
+	storeMaintenanceNextHandle int64
+	storeMaintenanceMutex      sync.Mutex
 	// watch contexts for store
 	storeWatchCtx   = make(map[string]context.CancelFunc)
 	storeWatchMutex sync.Mutex
@@ -89,6 +133,7 @@ const (
 const (
 	storeDialKeepAliveTime    = 10 * time.Second
 	storeDialKeepAliveTimeout = 3 * time.Second
+	maintenanceStartupTimeout = 5 * time.Second
 )
 
 func newStoreClientConfig(validEndpoints []string) clientv3.Config {
@@ -279,7 +324,7 @@ func EtcdStoreResetClientWrapper(endpoints *C.char, errMsg **C.char) int {
 		return -1
 	}
 
-	cancelAllStoreKeepAlives()
+	closeAllStoreMaintenanceSessions()
 	cancelAllStoreWatches()
 	cancelAllStorePrefixWatches()
 
@@ -442,6 +487,92 @@ func EtcdStoreCreateWithLeaseWrapper(key *C.char, keySize C.int, value *C.char,
 	}
 }
 
+//export EtcdStoreAcquireMaintenanceSessionWrapper
+func EtcdStoreAcquireMaintenanceSessionWrapper(key *C.char, keySize C.int, ttl int64,
+	sessionHandle *int64, leaseId *int64, createRevision *int64, errMsg **C.char) int {
+	cli := getStoreClient()
+	if cli == nil {
+		*errMsg = C.CString("etcd client not initialized")
+		return -1
+	}
+	if ttl <= 0 {
+		*errMsg = C.CString("maintenance session TTL must be positive")
+		return -1
+	}
+
+	session, err := newMaintenanceSession(cli, int(ttl), maintenanceStartupTimeout)
+	if err != nil {
+		*errMsg = C.CString(err.Error())
+		return -1
+	}
+
+	k := C.GoStringN(key, keySize)
+	id := int64(session.session.Lease())
+	ownerToken := strconv.FormatInt(id, 10)
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	resp, err := cli.Txn(ctx).
+		If(clientv3.Compare(clientv3.CreateRevision(k), "=", 0)).
+		Then(clientv3.OpPut(k, ownerToken, clientv3.WithLease(session.session.Lease()))).
+		Commit()
+	cancel()
+	if err != nil {
+		_ = session.close()
+		*errMsg = C.CString(err.Error())
+		return -1
+	}
+	if !resp.Succeeded {
+		_ = session.close()
+		*errMsg = C.CString("maintenance lock is already held")
+		return -2
+	}
+
+	storeMaintenanceMutex.Lock()
+	storeMaintenanceNextHandle++
+	handle := storeMaintenanceNextHandle
+	storeMaintenanceSessions[handle] = session
+	storeMaintenanceMutex.Unlock()
+
+	*sessionHandle = handle
+	*leaseId = id
+	*createRevision = resp.Header.Revision
+	return 0
+}
+
+//export EtcdStoreCloseMaintenanceSessionWrapper
+func EtcdStoreCloseMaintenanceSessionWrapper(sessionHandle int64, errMsg **C.char) int {
+	storeMaintenanceMutex.Lock()
+	session, exists := storeMaintenanceSessions[sessionHandle]
+	if exists {
+		delete(storeMaintenanceSessions, sessionHandle)
+	}
+	storeMaintenanceMutex.Unlock()
+	if !exists {
+		return 0
+	}
+	if err := session.close(); err != nil && !errors.Is(err, rpctypes.ErrLeaseNotFound) {
+		*errMsg = C.CString(err.Error())
+		return -1
+	}
+	return 0
+}
+
+//export EtcdStoreMaintenanceSessionAliveWrapper
+func EtcdStoreMaintenanceSessionAliveWrapper(sessionHandle int64, errMsg **C.char) int {
+	storeMaintenanceMutex.Lock()
+	session, exists := storeMaintenanceSessions[sessionHandle]
+	storeMaintenanceMutex.Unlock()
+	if !exists {
+		*errMsg = C.CString("maintenance session handle not found")
+		return -1
+	}
+	select {
+	case <-session.session.Done():
+		return 0
+	default:
+		return 1
+	}
+}
+
 /*
 * @brief First cancel the watch context, then delete it from the map.
 *        Cancel must be called before delete in case this is a new context
@@ -461,17 +592,17 @@ func cancelAndDeleteWatch(k string) int {
 	return -1
 }
 
-func cancelAllStoreKeepAlives() {
-	storeKeepAliveMutex.Lock()
-	cancels := make([]context.CancelFunc, 0, len(storeKeepAliveCtx))
-	for leaseId, cancel := range storeKeepAliveCtx {
-		cancels = append(cancels, cancel)
-		delete(storeKeepAliveCtx, leaseId)
+func closeAllStoreMaintenanceSessions() {
+	storeMaintenanceMutex.Lock()
+	sessions := make([]*maintenanceSession, 0, len(storeMaintenanceSessions))
+	for handle, session := range storeMaintenanceSessions {
+		sessions = append(sessions, session)
+		delete(storeMaintenanceSessions, handle)
 	}
-	storeKeepAliveMutex.Unlock()
+	storeMaintenanceMutex.Unlock()
 
-	for _, cancel := range cancels {
-		cancel()
+	for _, session := range sessions {
+		_ = session.close()
 	}
 }
 
@@ -622,11 +753,19 @@ func hasKeepAliveContext(leaseId int64) bool {
 
 //export EtcdStoreKeepAliveWrapper
 func EtcdStoreKeepAliveWrapper(leaseId int64, errMsg **C.char) int {
-	cli := getStoreClient()
-	if cli == nil {
+	storeCli := getStoreClient()
+	if storeCli == nil {
 		*errMsg = C.CString("etcd client not initialized")
 		return -1
 	}
+	// Keep lease traffic separate from Store traffic. A Store client reset or
+	// a busy Store connection must not stop leadership keep-alive.
+	cli, err := clientv3.New(newStoreClientConfig(storeCli.Endpoints()))
+	if err != nil {
+		*errMsg = C.CString(err.Error())
+		return -1
+	}
+	defer cli.Close()
 
 	// Create a context with cancel function
 	ctx, cancel := context.WithCancel(context.Background())
@@ -792,7 +931,7 @@ func EtcdStoreBatchCreateWrapper(keys **C.char, values **C.char, count C.int, er
 }
 
 //export EtcdStoreTxnCompareAndPutWrapper
-func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.int, compareKinds *C.int, compareValues **C.char, compareValueSizes *C.int, compareCount C.int, putKeys **C.char, putKeySizes *C.int, putValues **C.char, putValueSizes *C.int, putCount C.int, errMsg **C.char) int {
+func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.int, compareKinds *C.int, compareValues **C.char, compareValueSizes *C.int, compareRevisions *int64, compareCount C.int, putKeys **C.char, putKeySizes *C.int, putValues **C.char, putValueSizes *C.int, putPreserveLeases *C.int, putCount C.int, errMsg **C.char) int {
 	cli := getStoreClient()
 	if cli == nil {
 		*errMsg = C.CString("etcd client not initialized")
@@ -809,6 +948,7 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 		compareKindList := (*[1 << 28]C.int)(unsafe.Pointer(compareKinds))[:cmpN:cmpN]
 		compareValuePtrs := (*[1 << 28]*C.char)(unsafe.Pointer(compareValues))[:cmpN:cmpN]
 		compareValueSizeList := (*[1 << 28]C.int)(unsafe.Pointer(compareValueSizes))[:cmpN:cmpN]
+		compareRevisionList := (*[1 << 28]int64)(unsafe.Pointer(compareRevisions))[:cmpN:cmpN]
 		for i := 0; i < cmpN; i++ {
 			k := C.GoStringN(compareKeyPtrs[i], compareKeySizeList[i])
 			switch int(compareKindList[i]) {
@@ -817,6 +957,8 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 				cmps = append(cmps, clientv3.Compare(clientv3.Value(k), "=", v))
 			case 1:
 				cmps = append(cmps, clientv3.Compare(clientv3.CreateRevision(k), "=", 0))
+			case 2:
+				cmps = append(cmps, clientv3.Compare(clientv3.CreateRevision(k), "=", compareRevisionList[i]))
 			default:
 				*errMsg = C.CString("unsupported compare kind")
 				return -1
@@ -830,10 +972,15 @@ func EtcdStoreTxnCompareAndPutWrapper(compareKeys **C.char, compareKeySizes *C.i
 		putKeySizeList := (*[1 << 28]C.int)(unsafe.Pointer(putKeySizes))[:putN:putN]
 		putValuePtrs := (*[1 << 28]*C.char)(unsafe.Pointer(putValues))[:putN:putN]
 		putValueSizeList := (*[1 << 28]C.int)(unsafe.Pointer(putValueSizes))[:putN:putN]
+		putPreserveLeaseList := (*[1 << 28]C.int)(unsafe.Pointer(putPreserveLeases))[:putN:putN]
 		for i := 0; i < putN; i++ {
 			k := C.GoStringN(putKeyPtrs[i], putKeySizeList[i])
 			v := C.GoStringN(putValuePtrs[i], putValueSizeList[i])
-			ops = append(ops, clientv3.OpPut(k, v))
+			if putPreserveLeaseList[i] != 0 {
+				ops = append(ops, clientv3.OpPut(k, v, clientv3.WithIgnoreLease()))
+			} else {
+				ops = append(ops, clientv3.OpPut(k, v))
+			}
 		}
 	}
 
diff --git a/mooncake-common/etcd/etcd_wrapper_test.go b/mooncake-common/etcd/etcd_wrapper_test.go
new file mode 100644
index 0000000000..2e4fbc9797
--- /dev/null
+++ b/mooncake-common/etcd/etcd_wrapper_test.go
@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clientv3 "go.etcd.io/etcd/client/v3"
+	"go.etcd.io/etcd/client/v3/concurrency"
+)
+
+func TestNewMaintenanceSessionCancelsStartup(t *testing.T) {
+	original := startMaintenanceSession
+	defer func() { startMaintenanceSession = original }()
+
+	started := make(chan struct{})
+	startMaintenanceSession = func(ctx context.Context, _ *clientv3.Client,
+		_ int) (*concurrency.Session, error) {
+		close(started)
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+
+	result := make(chan error, 1)
+	go func() {
+		_, err := newMaintenanceSession(nil, 30, 10*time.Millisecond)
+		result <- err
+	}()
+	select {
+	case <-started:
+	case <-time.After(time.Second):
+		t.Fatal("maintenance session startup was not attempted")
+	}
+	select {
+	case err := <-result:
+		if err == nil {
+			t.Fatal("expected startup cancellation error")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("maintenance session startup did not cancel")
+	}
+}
diff --git a/mooncake-common/include/default_config.h b/mooncake-common/include/default_config.h
index ae5395ac27..925f5fb02b 100644
--- a/mooncake-common/include/default_config.h
+++ b/mooncake-common/include/default_config.h
@@ -124,6 +124,10 @@ class DefaultConfig {
     void GetString(const std::string& key, std::string* val,
                    const std::string& default_value = "") const;
 
+    [[nodiscard]] bool Contains(const std::string& key) const {
+        return data_.find(key) != data_.end();
+    }
+
     void SetPath(const std::string& path) { path_ = path; }
 
    private:
diff --git a/mooncake-common/include/environ.h b/mooncake-common/include/environ.h
index f6224696dd..4b78a016a1 100644
--- a/mooncake-common/include/environ.h
+++ b/mooncake-common/include/environ.h
@@ -1,8 +1,13 @@
 #pragma once
 
-#include <string>
 #include <cstdint>
 #include <cstdlib>
+#include <iostream>
+#include <optional>
+#include <string>
+
+#include "environment_variable.h"
+#include "environment_value_parser.h"
 
 namespace mooncake {
 
@@ -60,29 +65,10 @@ class Environ {
     bool GetIntraNvlink() const { return intra_nvlink_; }
     bool GetPathRoundrobin() const { return path_roundrobin_; }
     bool GetWithNvidiaPeermem() const { return with_nvidia_peermem_; }
+    bool GetRdmaDataDirect() const { return rdma_data_direct_; }
     int GetEfaCqThreads() const { return efa_cq_threads_; }
     bool GetStoreChecksumEnabled() const { return store_checksum_enabled_; }
 
-    // AWS / S3 client configuration
-    std::string GetAwsRegion() const { return aws_region_; }
-    std::string GetAwsS3Endpoint() const { return aws_s3_endpoint_; }
-    std::string GetAwsBucketName() const { return aws_bucket_name_; }
-    std::string GetAwsAccessKeyId() const { return aws_access_key_id_; }
-    std::string GetAwsSecretAccessKey() const { return aws_secret_access_key_; }
-    bool GetAwsUseVirtualAddressing() const {
-        return aws_use_virtual_addressing_;
-    }
-    bool GetAwsUseHttps() const { return aws_use_https_; }
-    // Empty string means "unset" — s3_helper keeps the AWS SDK default in
-    // that case. Parsing to AWS enums is done by the consumer.
-    std::string GetAwsRequestChecksumCalculation() const {
-        return aws_request_checksum_calculation_;
-    }
-    std::string GetAwsResponseChecksumValidation() const {
-        return aws_response_checksum_validation_;
-    }
-    int64_t GetAwsConnectTimeoutMs() const { return aws_connect_timeout_ms_; }
-    int64_t GetAwsRequestTimeoutMs() const { return aws_request_timeout_ms_; }
     uint32_t GetRpcClientIoThreads() const { return rpc_client_io_threads_; }
     uint32_t GetStoreRpcClientIoThreads() const {
         return store_rpc_client_io_threads_;
@@ -91,11 +77,12 @@ class Environ {
         return transfer_engine_rpc_client_io_threads_;
     }
 
-    // Helper method to get int from env
+    // Helper methods to get numeric values from env
     static int GetInt(const char* name, int default_value);
     static int64_t GetInt64(const char* name, int64_t default_value);
     static uint32_t GetUInt32(const char* name, uint32_t default_value);
     static uint64_t GetUInt64(const char* name, uint64_t default_value);
+    static double GetDouble(const char* name, double default_value);
     // Helper method to get size_t from env
     static size_t GetSizeT(const char* name, size_t default_value);
     // Helper method to get a canonical boolean from env. Invalid values use the
@@ -105,6 +92,35 @@ class Environ {
     static std::string GetString(const char* name,
                                  const std::string& default_value);
 
+    // Read a typed variable definition from the process environment. Missing
+    // or invalid typed values return nullopt; string variables preserve an
+    // explicitly empty value.
+    template <typename T>
+    static std::optional<T> Read(const EnvironmentVariable<T>& variable) {
+        const char* value = std::getenv(variable.name);
+        if (value == nullptr) {
+            return std::nullopt;
+        }
+        return TryParseEnvironmentValue<T>(value);
+    }
+
+    template <typename T>
+    static T ReadOr(const EnvironmentVariable<T>& variable, T default_value) {
+        const char* value = std::getenv(variable.name);
+        if (value == nullptr) {
+            return default_value;
+        }
+
+        const auto parsed = TryParseEnvironmentValue<T>(value);
+        if (parsed.has_value()) {
+            return *parsed;
+        }
+        std::cerr << "[Mooncake] Warning: invalid value '" << value
+                  << "' for env " << variable.name << ", using default "
+                  << default_value << std::endl;
+        return default_value;
+    }
+
    private:
     // Member variables
     int num_cq_per_ctx_;
@@ -143,24 +159,12 @@ class Environ {
     bool intra_nvlink_;
     bool path_roundrobin_;
     bool with_nvidia_peermem_;
+    bool rdma_data_direct_;
     int efa_cq_threads_;
     bool store_checksum_enabled_;
     uint32_t rpc_client_io_threads_;
     uint32_t store_rpc_client_io_threads_;
     uint32_t transfer_engine_rpc_client_io_threads_;
-
-    // AWS / S3 client configuration
-    std::string aws_region_;
-    std::string aws_s3_endpoint_;
-    std::string aws_bucket_name_;
-    std::string aws_access_key_id_;
-    std::string aws_secret_access_key_;
-    bool aws_use_virtual_addressing_;
-    bool aws_use_https_;
-    std::string aws_request_checksum_calculation_;
-    std::string aws_response_checksum_validation_;
-    int64_t aws_connect_timeout_ms_;
-    int64_t aws_request_timeout_ms_;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-common/include/environment_value_parser.h b/mooncake-common/include/environment_value_parser.h
new file mode 100644
index 0000000000..3aab7ea0d5
--- /dev/null
+++ b/mooncake-common/include/environment_value_parser.h
@@ -0,0 +1,70 @@
+#pragma once
+
+#include <cerrno>
+#include <cctype>
+#include <cmath>
+#include <cstdlib>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <type_traits>
+
+#include "bool_parser.h"
+#include "integer_parser.h"
+
+namespace mooncake {
+
+struct EnvironmentDoubleParseOptions {
+    bool allow_trailing_characters{false};
+    bool allow_non_finite{false};
+};
+
+inline std::optional<double> TryParseEnvironmentDouble(
+    std::string_view value, EnvironmentDoubleParseOptions options = {}) {
+    if (value.empty()) {
+        return std::nullopt;
+    }
+
+    const std::string text(value);
+    char* end = nullptr;
+    const int saved_errno = errno;
+    errno = 0;
+    const double parsed = std::strtod(text.c_str(), &end);
+    const int parse_errno = errno;
+    errno = saved_errno;
+    const bool consumed_value = end != text.c_str() && end != nullptr;
+    while (end != nullptr && std::isspace(static_cast<unsigned char>(*end))) {
+        ++end;
+    }
+    const bool consumed_required_input =
+        options.allow_trailing_characters || (consumed_value && *end == '\0');
+    const bool accepted_finiteness =
+        options.allow_non_finite || std::isfinite(parsed);
+    if (consumed_value && consumed_required_input && parse_errno != ERANGE &&
+        accepted_finiteness) {
+        return parsed;
+    }
+    return std::nullopt;
+}
+
+template <typename>
+inline constexpr bool kUnsupportedEnvironmentValueType = false;
+
+template <typename T>
+std::optional<T> TryParseEnvironmentValue(std::string_view value) {
+    if constexpr (std::is_same_v<T, std::string>) {
+        return std::string(value);
+    } else if constexpr (std::is_same_v<T, bool>) {
+        return TryParseBool(value);
+    } else if constexpr (std::is_integral_v<T>) {
+        return TryParseInteger<T>(
+            value, {.trim_ascii_whitespace = true, .allow_leading_plus = true});
+    } else if constexpr (std::is_same_v<T, double>) {
+        return TryParseEnvironmentDouble(value);
+    } else {
+        static_assert(kUnsupportedEnvironmentValueType<T>,
+                      "unsupported environment value type");
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-common/include/environment_variable.h b/mooncake-common/include/environment_variable.h
new file mode 100644
index 0000000000..ac879d6699
--- /dev/null
+++ b/mooncake-common/include/environment_variable.h
@@ -0,0 +1,10 @@
+#pragma once
+
+namespace mooncake {
+
+template <typename T>
+struct EnvironmentVariable {
+    const char* name;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-common/include/environment_variables.h b/mooncake-common/include/environment_variables.h
new file mode 100644
index 0000000000..ae1a5aa08d
--- /dev/null
+++ b/mooncake-common/include/environment_variables.h
@@ -0,0 +1,271 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+#include "environment_variable.h"
+
+namespace mooncake {
+
+#define MC_DEFINE_ENV_VAR(Type, Name) \
+    inline static constexpr EnvironmentVariable<Type> Name { #Name }
+
+struct FileStorageEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFLOAD_FILE_STORAGE_PATH);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES);
+    MC_DEFINE_ENV_VAR(int64_t, MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_SCANMETA_ITERATOR_KEYS_LIMIT);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES);
+    MC_DEFINE_ENV_VAR(uint32_t, MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS);
+    MC_DEFINE_ENV_VAR(uint32_t,
+                      MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS);
+    MC_DEFINE_ENV_VAR(uint64_t, MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS);
+
+    // Keep legacy bool/ratio values as strings so their custom parsing and
+    // silent invalid-value behavior remain unchanged.
+    MC_DEFINE_ENV_VAR(std::string,
+                      MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION);
+    MC_DEFINE_ENV_VAR(std::string,
+                      MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO);
+    MC_DEFINE_ENV_VAR(std::string,
+                      MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFLOAD_USE_URING);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_USE_URING);
+};
+
+struct FilePerKeyEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFLOAD_FSDIR);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_OFFLOAD_ENABLE_EVICTION);
+    MC_DEFINE_ENV_VAR(bool, ENABLE_EVICTION);
+};
+
+struct BucketBackendEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_BUCKET_MAX_TOTAL_SIZE);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_BUCKET_EVICTION_POLICY);
+};
+
+struct ClientAutoPortEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(int, MC_STORE_CLIENT_SETUP_RETRIES);
+    MC_DEFINE_ENV_VAR(int, MC_STORE_CLIENT_MIN_PORT);
+    MC_DEFINE_ENV_VAR(int, MC_STORE_CLIENT_MAX_PORT);
+};
+
+struct CxlSegmentEnvironmentVariables {
+    // Keep the raw string so an unset value remains distinguishable from a
+    // present but invalid value, which the legacy path resolves to zero.
+    MC_DEFINE_ENV_VAR(std::string, MC_CXL_DEV_SIZE);
+};
+
+struct ClientNumaEnvironmentVariables {
+    // Keep the raw string to preserve the legacy strtol syntax and warning
+    // behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_NUMA_SOCKET_ID);
+};
+
+struct RegisteredPinnedMemoryEnvironmentVariables {
+    // Keep the raw string because the legacy parser rejects a leading '+',
+    // unlike the shared typed integer parser.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_PIN_MEMORY_MAX_BYTES);
+};
+
+struct MmapArenaEnvironmentVariables {
+    // Keep these values as strings to preserve the existing byte-size and
+    // canonical-bool parsing, opt-in, fallback, and logging behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_MMAP_ARENA_POOL_SIZE);
+    MC_DEFINE_ENV_VAR(std::string, MC_DISABLE_MMAP_ARENA);
+};
+
+struct HugepageEnvironmentVariables {
+    // Keep these values as strings to preserve presence-based enablement and
+    // the existing byte-size parser, fallback, and logging behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_USE_HUGEPAGE);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_HUGEPAGE_SIZE);
+};
+
+struct LocalHotCacheEnvironmentVariables {
+    // Keep these values as strings to preserve their existing per-setting
+    // parsing, fallback, and logging behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_LOCAL_HOT_CACHE_SIZE);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_LOCAL_HOT_BLOCK_SIZE);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_LOCAL_HOT_CACHE_USE_SHM);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD);
+};
+
+struct ClientMetricEnvironmentVariables {
+    // Keep these values as strings because ClientMetricConfig preserves the
+    // existing per-setting fallback and logging behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_CLIENT_METRIC);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_CLIENT_METRIC_INTERVAL);
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_CLIENT_METRIC_BANDWIDTH);
+};
+
+struct DistributedStorageEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DFS_ROOT_DIR);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DISTRIBUTED_ROOT_DIR);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DFS_FS_ADAPTER);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DISTRIBUTED_FS_TYPE);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_DFS_ALLOCATOR);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_DISTRIBUTED_HEALTH_CHECK);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_DFS_SHARD_COUNT);
+    MC_DEFINE_ENV_VAR(uint64_t, MOONCAKE_DFS_SHARD_CAPACITY);
+    MC_DEFINE_ENV_VAR(uint64_t, MOONCAKE_DFS_BUCKET_CAPACITY);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_DFS_MAX_BUCKET_COUNT);
+    MC_DEFINE_ENV_VAR(uint64_t, MOONCAKE_DFS_ALIGNMENT);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_DFS_SINGLE_TENANT);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_DFS_EVICTION_ENABLED);
+    MC_DEFINE_ENV_VAR(double, MOONCAKE_DFS_EVICTION_HIGH_WATERMARK);
+    MC_DEFINE_ENV_VAR(double, MOONCAKE_DFS_EVICTION_LOW_WATERMARK);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_DFS_DEFERRED_FREE_SECONDS);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_DFS_EVICTION_CHECK_INTERVAL);
+};
+
+struct OssAdapterEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_ENDPOINT);
+    MC_DEFINE_ENV_VAR(std::string, OSS_ENDPOINT);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_BUCKET);
+    MC_DEFINE_ENV_VAR(std::string, OSS_BUCKET);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_REGION);
+    MC_DEFINE_ENV_VAR(std::string, OSS_REGION);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_ACCESS_KEY_ID);
+    MC_DEFINE_ENV_VAR(std::string, OSS_ACCESS_KEY_ID);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_ACCESS_KEY_SECRET);
+    MC_DEFINE_ENV_VAR(std::string, OSS_ACCESS_KEY_SECRET);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OSS_SECURITY_TOKEN);
+    MC_DEFINE_ENV_VAR(std::string, OSS_SESSION_TOKEN);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_OSS_PATH_STYLE);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_OSS_ANONYMOUS);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_OSS_MAX_CONNECTIONS);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_OSS_RECEIVE_BUFFER_SIZE);
+    MC_DEFINE_ENV_VAR(int, MOONCAKE_OSS_UPLOAD_BUFFER_SIZE);
+};
+
+struct OffsetAllocatorBackendEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFSET_EVICTION_POLICY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFSET_HIGH_RATIO);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFSET_LOW_RATIO);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFSET_MAX_CAPACITY_NODES);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_OFFSET_PERSIST_MODE);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_OFFSET_PERSIST_INTERVAL_SECONDS);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_OFFSET_RECORD_CRC);
+};
+
+struct ReplicaSelectionEnvironmentVariables {
+    // Only the exact string "1" enables scoring, unlike canonical bool parsing.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_REPLICA_SCORING);
+};
+
+struct RpcTimeoutEnvironmentVariables {
+    // Preserve atoll parsing: empty/nonnumeric values become zero, and numeric
+    // prefixes are accepted, unlike the shared typed integer parser.
+    MC_DEFINE_ENV_VAR(std::string, MC_RPC_TIMEOUT_MS);
+    MC_DEFINE_ENV_VAR(std::string, MC_RPC_CONNECT_TIMEOUT_MS);
+};
+
+struct RpcProtocolEnvironmentVariables {
+    // Preserve the legacy exact, case-sensitive "rdma" token check.
+    MC_DEFINE_ENV_VAR(std::string, MC_RPC_PROTOCOL);
+};
+
+struct LocalFileSnapshotEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_SNAPSHOT_LOCAL_PATH);
+};
+
+struct HaClusterNamespaceEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_CLUSTER_ID);
+};
+
+struct TransferSubmitterEnvironmentVariables {
+    // Keep the raw string to preserve the legacy token set, whitespace,
+    // invalid-value fallback, and warning behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_STORE_MEMCPY);
+};
+
+struct FilereadWorkerPoolEnvironmentVariables {
+    // Preserve the raw value in invalid-value warnings.
+    MC_DEFINE_ENV_VAR(std::string, MC_FILEREAD_WORKERS);
+};
+
+struct NoFRegisterEnvironmentVariables {
+    // Keep the raw string to preserve case normalization and warning behavior.
+    MC_DEFINE_ENV_VAR(std::string, MC_NOF_TRTYPE);
+};
+
+struct SpdkControllerEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(uint32_t, MC_NVME_NUM_IO_QUEUES);
+    MC_DEFINE_ENV_VAR(uint32_t, MC_NVME_IO_QUEUE_SIZE);
+    MC_DEFINE_ENV_VAR(uint32_t, MC_NVME_IO_QUEUE_REQUESTS);
+    MC_DEFINE_ENV_VAR(uint8_t, MC_NVME_TRANSPORT_ACK_TIMEOUT);
+    MC_DEFINE_ENV_VAR(uint16_t, MC_NVME_ADMIN_QUEUE_SIZE);
+    MC_DEFINE_ENV_VAR(uint64_t, MC_NVME_FABRICS_CONNECT_TIMEOUT_US);
+    MC_DEFINE_ENV_VAR(bool, MC_NVME_HEADER_DIGEST);
+    MC_DEFINE_ENV_VAR(bool, MC_NVME_DATA_DIGEST);
+};
+
+struct NvmeKvConnectorEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_DEVICE_PATH);
+    // Keep numeric values as strings because the existing NVMe parser accepts
+    // base prefixes, a leading plus, and leading whitespace.
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_NSID);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_QUEUE_DEPTH);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_TRANSPORT);
+};
+
+struct RedisConnectionEnvironmentVariables {
+    // Keep the DB index as a string so an explicitly empty value remains
+    // distinguishable from a nonempty malformed value.
+    MC_DEFINE_ENV_VAR(std::string, MC_REDIS_DB_INDEX);
+    MC_DEFINE_ENV_VAR(std::string, MC_REDIS_USERNAME);
+    MC_DEFINE_ENV_VAR(std::string, MC_REDIS_PASSWORD);
+};
+
+struct ClientAutoDiscoveryEnvironmentVariables {
+    // Keep the raw strings to preserve std::stoi prefix acceptance and the
+    // distinction between unset and explicitly empty filter values.
+    MC_DEFINE_ENV_VAR(std::string, MC_MS_AUTO_DISC);
+    MC_DEFINE_ENV_VAR(std::string, MC_MS_FILTERS);
+};
+
+struct ClientHostIdentityEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_HOST_ID);
+};
+
+struct NvmeKvIoConcurrencyEnvironmentVariables {
+    // Keep these values as strings to preserve the existing NVMe unsigned
+    // syntax, zero fallback, and silent invalid-value behavior.
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_IO_CONCURRENCY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_NVME_KV_PREPARE_CONCURRENCY);
+};
+
+struct S3ClientEnvironmentVariables {
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_REGION);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_S3_ENDPOINT);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_BUCKET_NAME);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_ACCESS_KEY_ID);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_SECRET_ACCESS_KEY);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING);
+    MC_DEFINE_ENV_VAR(bool, MOONCAKE_AWS_USE_HTTPS);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION);
+    MC_DEFINE_ENV_VAR(std::string, MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_AWS_CONNECT_TIMEOUT_MS);
+    MC_DEFINE_ENV_VAR(int64_t, MOONCAKE_AWS_REQUEST_TIMEOUT_MS);
+};
+
+#undef MC_DEFINE_ENV_VAR
+
+}  // namespace mooncake
diff --git a/mooncake-common/include/ib_link_speed.h b/mooncake-common/include/ib_link_speed.h
new file mode 100644
index 0000000000..7e9fba9261
--- /dev/null
+++ b/mooncake-common/include/ib_link_speed.h
@@ -0,0 +1,87 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+
+#ifndef MOONCAKE_IB_LINK_SPEED_H_
+#define MOONCAKE_IB_LINK_SPEED_H_
+
+namespace mooncake {
+
+// Per-lane signalling rate for an ibv_port_attr::active_speed encoding
+// (see ibv_query_port(3)). Returns 0 for an encoding that is not known.
+inline double ibLaneSpeedGbps(int active_speed) {
+    switch (active_speed) {
+        case 1:
+            return 2.5;  // SDR
+        case 2:
+            return 5.0;  // DDR
+        case 4:
+            return 10.0;  // QDR
+        case 8:
+            return 10.0;  // FDR10
+        case 16:
+            return 14.0;  // FDR
+        case 32:
+            return 25.0;  // EDR
+        case 64:
+            return 50.0;  // HDR
+        case 128:
+            return 100.0;  // NDR
+        case 256:
+            return 200.0;  // XDR
+        default:
+            return 0.0;
+    }
+}
+
+// Lane count for an ibv_port_attr::active_width encoding. Returns 0 for an
+// encoding that is not known.
+inline int ibLinkWidthLanes(int active_width) {
+    switch (active_width) {
+        case 1:
+            return 1;
+        case 2:
+            return 4;
+        case 4:
+            return 8;
+        case 8:
+            return 12;
+        case 16:
+            return 2;
+        default:
+            return 0;
+    }
+}
+
+// Link speed in Gbps from the raw ibv_port_attr encodings, or 0 when either
+// encoding is unknown so the caller can fall back explicitly rather than
+// scheduling against a guessed rate.
+inline double ibLinkSpeedGbps(int active_speed, int active_width) {
+    return ibLaneSpeedGbps(active_speed) * ibLinkWidthLanes(active_width);
+}
+
+// Port speed in Gbps, preferring the effective speed ibv_query_port_speed()
+// reports (rdma-core >= 62, here in Mb/s) over the encoded link rate.
+// The two differ for a VF over LAG: a PF dropping out of the bond halves
+// the VF's bandwidth while its port stays ACTIVE at the same encoding, and
+// only the effective speed reflects that. 0 for effective_mbps means the
+// verb is unavailable or reported nothing, and the encodings decide.
+inline double ibPortSpeedGbps(unsigned long long effective_mbps,
+                              int active_speed, int active_width) {
+    if (effective_mbps > 0) return effective_mbps / 1000.0;
+    return ibLinkSpeedGbps(active_speed, active_width);
+}
+
+}  // namespace mooncake
+
+#endif  // MOONCAKE_IB_LINK_SPEED_H_
diff --git a/mooncake-common/include/rpc_client_io_context.h b/mooncake-common/include/rpc_client_io_context.h
index b9842f0c99..25373be186 100644
--- a/mooncake-common/include/rpc_client_io_context.h
+++ b/mooncake-common/include/rpc_client_io_context.h
@@ -1,13 +1,17 @@
 #pragma once
 
 #include <cstdint>
+#include <cstdio>
+#include <atomic>
 #include <chrono>
+#include <condition_variable>
 #include <csignal>
 #include <memory>
 #include <mutex>
 #include <shared_mutex>
 #include <string>
 #include <string_view>
+#include <unordered_map>
 #include <utility>
 
 #include <ylt/coro_io/client_pool.hpp>
@@ -19,16 +23,152 @@ namespace mooncake {
 std::shared_ptr<coro_io::io_context_pool> CreateRpcClientIoContextPool(
     uint32_t thread_count);
 
+/**
+ * Teardown guard for RPC entry points that serve out of a shared pool.
+ *
+ * The ylt client pool documents only send_request as thread-safe; closing or
+ * destroying the pool while a request coroutine is suspended leaves the
+ * resumed coroutine touching freed connection state (the teardown segfault in
+ * #3909). Entry points take a ScopedCall; a destructor calls drain_for() so
+ * the pool is only released once nothing is in flight.
+ *
+ * The counters live in a shared State, not in the guard object itself. When a
+ * drain times out the owner tears down anyway, and a ScopedCall still in
+ * flight then outlives the guard; holding the state by shared_ptr keeps its
+ * leave() from touching freed memory (#3943 review).
+ */
+class RpcDrainGuard {
+   private:
+    struct State {
+        std::atomic<bool> stopping{false};
+        std::atomic<int> inflight{0};
+        std::mutex mutex;
+        std::condition_variable cv;
+    };
+
+   public:
+    class ScopedCall {
+       public:
+        explicit ScopedCall(const RpcDrainGuard& guard)
+            : state_(guard.state_), ok_(try_enter(*state_)) {}
+        ~ScopedCall() {
+            if (ok_) leave(*state_);
+        }
+        ScopedCall(const ScopedCall&) = delete;
+        ScopedCall& operator=(const ScopedCall&) = delete;
+        bool ok() const { return ok_; }
+
+       private:
+        static bool try_enter(State& state) {
+            if (state.stopping.load(std::memory_order_acquire)) return false;
+            state.inflight.fetch_add(1, std::memory_order_acq_rel);
+            // a drain that started between the two reads still sees this call
+            if (state.stopping.load(std::memory_order_acquire)) {
+                leave(state);
+                return false;
+            }
+            return true;
+        }
+
+        static void leave(State& state) {
+            if (state.inflight.fetch_sub(1, std::memory_order_acq_rel) == 1) {
+                std::lock_guard lk(state.mutex);
+                state.cv.notify_all();
+            }
+        }
+
+        std::shared_ptr<State> state_;
+        bool ok_;
+    };
+
+    // Bounded wait for in-flight calls; stops admitting new ones first.
+    // Returns false on timeout: the caller must keep the shared pool alive
+    // regardless (the registry already does), and the state itself stays
+    // valid until the last ScopedCall lets go of it.
+    bool drain_for(std::chrono::milliseconds timeout) {
+        state_->stopping.store(true, std::memory_order_release);
+        std::unique_lock lk(state_->mutex);
+        return state_->cv.wait_for(lk, timeout, [&] {
+            return state_->inflight.load(std::memory_order_acquire) == 0;
+        });
+    }
+
+   private:
+    std::shared_ptr<State> state_ = std::make_shared<State>();
+};
+
 template <typename PoolTag>
 coro_io::io_context_pool& GetRpcClientIoContextPool(uint32_t thread_count) {
     static const auto io_pool = CreateRpcClientIoContextPool(thread_count);
     return *io_pool;
 }
 
+namespace detail {
+
+// Process-wide client-pool registry, keyed by address. A ylt client pool owns
+// background reconnect coroutines that hold references into pool storage
+// (client_pool.hpp's reconnect loop), so freeing a pool while they are
+// suspended is a use-after-free regardless of whether any user request is in
+// flight (#3909). Pools are few in practice (one per distinct master address
+// per process), so they are deliberately kept alive for the process lifetime.
+//
+// The registry key is the address plus the pool's behavioral knobs. Two
+// holders for one address with identical configuration share a pool, which is
+// the case the keep-alive exists for. The same address can also legitimately
+// host different policies at once: the foreground master pool is resilient
+// while an HA probe on that address must fast-fail, and keying by address
+// alone would hand the probe the foreground retry budget.
+inline std::shared_ptr<coro_io::client_pool<coro_rpc::coro_rpc_client>>
+SharedPoolRegistryImpl(
+    std::string_view address,
+    coro_io::client_pool<coro_rpc::coro_rpc_client>::pool_config config,
+    coro_io::io_context_pool& io_context_pool) {
+    using Pool = coro_io::client_pool<coro_rpc::coro_rpc_client>;
+    static std::mutex registry_mutex;
+    static std::unordered_map<std::string, std::shared_ptr<Pool>> registry;
+    std::lock_guard<std::mutex> lock(registry_mutex);
+    std::string key;
+    key.reserve(address.size() + 64);
+    key.append(address);
+    auto append_knob = [&key](auto value) {
+        key.push_back('|');
+        key.append(std::to_string(value));
+    };
+    append_knob(config.max_connection);
+    append_knob(config.connect_retry_count);
+    append_knob(config.reconnect_wait_time.count());
+    append_knob(config.client_config.connect_timeout_duration.count());
+    append_knob(config.client_config.request_timeout_duration.count());
+    append_knob(
+        static_cast<size_t>(config.client_config.socket_config.index()));
+    auto& pool = registry[key];
+    if (!pool) {
+        pool = Pool::create(std::string(address), std::move(config),
+                            io_context_pool);
+    }
+    return pool;
+}
+
+// ClientRequester's offload pool collection has the same lifetime hazard: its
+// pools host background reconnect coroutines, so they must outlive the owning
+// RealClient. Collections are few in practice (one per RealClient), so they
+// are parked here for the process lifetime instead of being freed at teardown.
+inline void KeepClientPoolsAlive(
+    std::shared_ptr<coro_io::client_pools<coro_rpc::coro_rpc_client>> pools) {
+    static std::mutex keep_mutex;
+    static std::vector<
+        std::shared_ptr<coro_io::client_pools<coro_rpc::coro_rpc_client>>>
+        keep;
+    std::lock_guard<std::mutex> lock(keep_mutex);
+    keep.push_back(std::move(pools));
+}
+
+}  // namespace detail
+
 /**
  * A replaceable client pool for callers that communicate with one target at a
- * time. Requests retain a shared_ptr to the old pool while they are in flight;
- * after an address switch the old pool is destroyed when those requests end.
+ * time. Pools live in the process-wide registry above; an address switch only
+ * re-points this holder, it never frees a pool.
  */
 class RpcClientPool {
    public:
@@ -46,8 +186,7 @@ class RpcClientPool {
         std::string_view address) {
         std::lock_guard<std::shared_mutex> lock(mutex_);
         if (!client_pool_ || address_ != address) {
-            client_pool_ =
-                ClientPool::create(address, config_, io_context_pool_);
+            client_pool_ = SharedPoolRegistry(address);
             address_ = address;
         }
         return client_pool_;
@@ -59,6 +198,11 @@ class RpcClientPool {
     }
 
    private:
+    std::shared_ptr<ClientPool> SharedPoolRegistry(std::string_view address) {
+        return detail::SharedPoolRegistryImpl(address, config_,
+                                              io_context_pool_);
+    }
+
     mutable std::shared_mutex mutex_;
     coro_io::io_context_pool& io_context_pool_;
     PoolConfig config_;
diff --git a/mooncake-common/src/CMakeLists.txt b/mooncake-common/src/CMakeLists.txt
index 2730485cf1..8a698d3aab 100644
--- a/mooncake-common/src/CMakeLists.txt
+++ b/mooncake-common/src/CMakeLists.txt
@@ -1,4 +1,10 @@
 find_package(yaml-cpp REQUIRED)
+find_path(ASIO_INCLUDE_DIR asio.hpp
+  HINTS ${yalantinglibs_SOURCE_DIR}/include/ylt/thirdparty
+)
+if(NOT ASIO_INCLUDE_DIR)
+  message(FATAL_ERROR "standalone Asio headers not found")
+endif()
 
 set(MOONCAKE_COMMON_SOURCES crc_checksum.cpp default_config.cpp environ.cpp
                             rpc_client_io_context.cpp)
@@ -7,6 +13,7 @@ add_library(asio_shared SHARED asio_impl.cpp)
 
 target_compile_definitions(asio_shared PUBLIC ASIO_SEPARATE_COMPILATION
                                               ASIO_DYN_LINK)
+target_include_directories(asio_shared PUBLIC ${ASIO_INCLUDE_DIR})
 
 set_target_properties(
   asio_shared
@@ -17,6 +24,7 @@ set_target_properties(
              LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/mooncake-common")
 
 target_link_libraries(asio_shared PUBLIC pthread yalantinglibs::yalantinglibs)
+install(TARGETS asio_shared DESTINATION lib)
 
 # Static, PIC twin of asio_shared for consumers that absorb asio into their own
 # shared object instead of taking a DT_NEEDED on libasio.so (see
@@ -39,11 +47,10 @@ target_include_directories(
   PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
          $<INSTALL_INTERFACE:include>)
 
-target_link_libraries(mooncake_common PUBLIC asio_shared yaml-cpp jsoncpp
-                                             yalantinglibs::yalantinglibs)
+target_link_libraries(
+  mooncake_common PUBLIC asio_shared yaml-cpp JsonCpp::JsonCpp
+                         yalantinglibs::yalantinglibs)
 
 if(BUILD_SHARED_LIBS)
   install(TARGETS mooncake_common DESTINATION lib)
 endif()
-
-install(TARGETS asio_shared DESTINATION lib)
diff --git a/mooncake-common/src/crc_checksum.cpp b/mooncake-common/src/crc_checksum.cpp
index 37c330201b..c05dca0f48 100644
--- a/mooncake-common/src/crc_checksum.cpp
+++ b/mooncake-common/src/crc_checksum.cpp
@@ -8,29 +8,85 @@ namespace {
 
 constexpr uint64_t kCrc64EcmaPolynomial = 0x42F0E1EBA9EA3693ULL;
 
-constexpr std::array<uint64_t, 256> MakeCrc64EcmaTable() {
-    std::array<uint64_t, 256> table{};
-    for (size_t i = 0; i < table.size(); ++i) {
+// Advance the register by one byte with a zero input byte. Feeding one message
+// byte is `(crc << 8) ^ table[0][(crc >> 56) ^ byte]`, so composing this
+// function k times yields the table for a byte that still has k more byte
+// positions to travel.
+constexpr uint64_t AdvanceOneByte(uint64_t crc, const uint64_t* base_table) {
+    return (crc << 8) ^ base_table[crc >> 56];
+}
+
+// Slicing-by-8 tables. tables[0] is the classic byte-at-a-time table; tables[k]
+// additionally advances the value by k more bytes. Total size is 16 KiB, which
+// fits comfortably in L1d.
+constexpr std::array<std::array<uint64_t, 256>, 8> MakeCrc64EcmaTables() {
+    std::array<std::array<uint64_t, 256>, 8> tables{};
+    for (size_t i = 0; i < 256; ++i) {
         uint64_t crc = static_cast<uint64_t>(i) << 56;
         for (int bit = 0; bit < 8; ++bit) {
             crc = (crc & (1ULL << 63)) != 0 ? (crc << 1) ^ kCrc64EcmaPolynomial
                                             : crc << 1;
         }
-        table[i] = crc;
+        tables[0][i] = crc;
+    }
+    for (size_t k = 1; k < 8; ++k) {
+        for (size_t i = 0; i < 256; ++i) {
+            tables[k][i] = AdvanceOneByte(tables[k - 1][i], tables[0].data());
+        }
     }
-    return table;
+    return tables;
+}
+
+constexpr auto kCrc64EcmaTables = MakeCrc64EcmaTables();
+constexpr const auto& kCrc64EcmaTable = kCrc64EcmaTables[0];
+
+// CRC-64/ECMA is defined MSB-first, so the first byte of the message must land
+// in the most significant byte of the register. Written as explicit shifts to
+// stay endian-independent; compilers fold this into a load plus a byte swap.
+inline uint64_t LoadBigEndian64(const uint8_t* p) {
+    return (static_cast<uint64_t>(p[0]) << 56) |
+           (static_cast<uint64_t>(p[1]) << 48) |
+           (static_cast<uint64_t>(p[2]) << 40) |
+           (static_cast<uint64_t>(p[3]) << 32) |
+           (static_cast<uint64_t>(p[4]) << 24) |
+           (static_cast<uint64_t>(p[5]) << 16) |
+           (static_cast<uint64_t>(p[6]) << 8) | static_cast<uint64_t>(p[7]);
 }
 
-constexpr auto kCrc64EcmaTable = MakeCrc64EcmaTable();
+inline uint64_t UpdateByteAtATime(uint64_t crc, const uint8_t* bytes,
+                                  size_t size) {
+    for (size_t i = 0; i < size; ++i) {
+        const auto index = static_cast<uint8_t>((crc >> 56) ^ bytes[i]);
+        crc = kCrc64EcmaTable[index] ^ (crc << 8);
+    }
+    return crc;
+}
 
 }  // namespace
 
 void CrcChecksum::Update(const void* data, size_t size) {
     const auto* bytes = static_cast<const uint8_t*>(data);
-    for (size_t i = 0; i < size; ++i) {
-        const auto index = static_cast<uint8_t>((crc_ >> 56) ^ bytes[i]);
-        crc_ = kCrc64EcmaTable[index] ^ (crc_ << 8);
+
+    // The byte-at-a-time loop is latency bound: every table index depends on
+    // the previous iteration's register value. Slicing-by-8 folds eight byte
+    // steps into one, and the eight lookups are independent, so the CPU can
+    // issue them in parallel. Measured ~4.8x on an Ice Lake Xeon (3.13 -> 0.65
+    // ns/byte).
+    uint64_t crc = crc_;
+    while (size >= 8) {
+        crc ^= LoadBigEndian64(bytes);
+        crc = kCrc64EcmaTables[7][crc >> 56] ^
+              kCrc64EcmaTables[6][(crc >> 48) & 0xFF] ^
+              kCrc64EcmaTables[5][(crc >> 40) & 0xFF] ^
+              kCrc64EcmaTables[4][(crc >> 32) & 0xFF] ^
+              kCrc64EcmaTables[3][(crc >> 24) & 0xFF] ^
+              kCrc64EcmaTables[2][(crc >> 16) & 0xFF] ^
+              kCrc64EcmaTables[1][(crc >> 8) & 0xFF] ^
+              kCrc64EcmaTables[0][crc & 0xFF];
+        bytes += 8;
+        size -= 8;
     }
+    crc_ = UpdateByteAtATime(crc, bytes, size);
 }
 
 uint64_t ComputeCrcChecksum(const void* data, size_t size) {
diff --git a/mooncake-common/src/environ.cpp b/mooncake-common/src/environ.cpp
index c736823171..36b5e8ebf3 100644
--- a/mooncake-common/src/environ.cpp
+++ b/mooncake-common/src/environ.cpp
@@ -2,12 +2,8 @@
 
 #include <algorithm>
 #include <iostream>
-#include <string_view>
 #include <thread>
 
-#include "bool_parser.h"
-#include "integer_parser.h"
-
 namespace mooncake {
 
 namespace {
@@ -38,9 +34,7 @@ Integer ReadInteger(const EnvironSource& source, const char* name,
         return default_value;
     }
 
-    const auto parsed = TryParseInteger<Integer>(
-        std::string_view(value),
-        {.trim_ascii_whitespace = true, .allow_leading_plus = true});
+    const auto parsed = TryParseEnvironmentValue<Integer>(value);
     if (parsed.has_value()) {
         return *parsed;
     }
@@ -64,6 +58,23 @@ size_t ReadSizeT(const EnvironSource& source, const char* name,
     return ReadInteger(source, name, default_value);
 }
 
+double ReadDouble(const EnvironSource& source, const char* name,
+                  double default_value) {
+    const char* value = source.Get(name);
+    if (value == nullptr || value[0] == '\0') {
+        return default_value;
+    }
+
+    const auto parsed = TryParseEnvironmentValue<double>(value);
+    if (parsed.has_value()) {
+        return *parsed;
+    }
+
+    std::cerr << "[Mooncake] Warning: invalid value '" << value << "' for env "
+              << name << ", using default " << default_value << std::endl;
+    return default_value;
+}
+
 bool ReadBool(const EnvironSource& source, const char* name,
               bool default_value) {
     const char* value = source.Get(name);
@@ -71,7 +82,7 @@ bool ReadBool(const EnvironSource& source, const char* name,
         return default_value;
     }
 
-    const auto parsed = TryParseBool(value);
+    const auto parsed = TryParseEnvironmentValue<bool>(value);
     if (parsed.has_value()) {
         return *parsed;
     }
@@ -117,6 +128,10 @@ uint64_t Environ::GetUInt64(const char* name, uint64_t default_value) {
     return ReadInteger(GetOsEnvironSource(), name, default_value);
 }
 
+double Environ::GetDouble(const char* name, double default_value) {
+    return ReadDouble(GetOsEnvironSource(), name, default_value);
+}
+
 size_t Environ::GetSizeT(const char* name, size_t default_value) {
     return ReadSizeT(GetOsEnvironSource(), name, default_value);
 }
@@ -184,30 +199,10 @@ Environ::Environ(const EnvironSource& source) {
     intra_nvlink_ = ReadBool(source, "MC_INTRA_NVLINK", false);
     path_roundrobin_ = ReadBool(source, "MC_PATH_ROUNDROBIN", false);
     with_nvidia_peermem_ = ReadBool(source, "WITH_NVIDIA_PEERMEM", true);
+    rdma_data_direct_ = ReadBool(source, "MC_RDMA_DATA_DIRECT", false);
     efa_cq_threads_ = ReadInt(source, "MC_EFA_CQ_THREADS", 1);
     store_checksum_enabled_ =
         ReadBool(source, "MOONCAKE_STORE_CHECKSUM", false);
-
-    // AWS / S3 client configuration (consumed by s3_helper.cpp)
-    aws_region_ = ReadString(source, "MOONCAKE_AWS_REGION", "");
-    aws_s3_endpoint_ = ReadString(source, "MOONCAKE_AWS_S3_ENDPOINT", "");
-    aws_bucket_name_ = ReadString(source, "MOONCAKE_AWS_BUCKET_NAME", "");
-    aws_access_key_id_ = ReadString(source, "MOONCAKE_AWS_ACCESS_KEY_ID", "");
-    aws_secret_access_key_ =
-        ReadString(source, "MOONCAKE_AWS_SECRET_ACCESS_KEY", "");
-    aws_use_virtual_addressing_ =
-        ReadBool(source, "MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING", true);
-    aws_use_https_ = ReadBool(source, "MOONCAKE_AWS_USE_HTTPS", true);
-    // Empty string preserves "unset" semantics — s3_helper keeps the AWS SDK
-    // default in that case rather than forcing a value.
-    aws_request_checksum_calculation_ =
-        ReadString(source, "MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION", "");
-    aws_response_checksum_validation_ =
-        ReadString(source, "MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION", "");
-    aws_connect_timeout_ms_ =
-        ReadInt64(source, "MOONCAKE_AWS_CONNECT_TIMEOUT_MS", 10000);
-    aws_request_timeout_ms_ =
-        ReadInt64(source, "MOONCAKE_AWS_REQUEST_TIMEOUT_MS", 30000);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-common/tests/CMakeLists.txt b/mooncake-common/tests/CMakeLists.txt
index ee2d458547..9a003bf484 100644
--- a/mooncake-common/tests/CMakeLists.txt
+++ b/mooncake-common/tests/CMakeLists.txt
@@ -21,9 +21,20 @@ target_link_libraries(rpc_client_io_context_test PUBLIC mooncake_common gtest
                                                         ibverbs pthread)
 add_test(NAME rpc_client_io_context_test COMMAND rpc_client_io_context_test)
 
-foreach(parser_test ascii_string bool_parser integer_parser)
+add_executable(rpc_drain_guard_test rpc_drain_guard_test.cpp)
+target_link_libraries(rpc_drain_guard_test PUBLIC mooncake_common gtest
+                                                  gtest_main pthread)
+add_test(NAME rpc_drain_guard_test COMMAND rpc_drain_guard_test)
+
+foreach(parser_test ascii_string bool_parser environment_value_parser
+                    integer_parser)
   add_executable(${parser_test}_test ${parser_test}_test.cpp)
   target_link_libraries(${parser_test}_test PUBLIC mooncake_common gtest
                                                    gtest_main pthread)
   add_test(NAME ${parser_test}_test COMMAND ${parser_test}_test)
 endforeach()
+
+add_executable(ib_link_speed_test ib_link_speed_test.cpp)
+target_link_libraries(ib_link_speed_test PUBLIC mooncake_common gtest
+                                                gtest_main pthread)
+add_test(NAME ib_link_speed_test COMMAND ib_link_speed_test)
diff --git a/mooncake-common/tests/crc_checksum_test.cpp b/mooncake-common/tests/crc_checksum_test.cpp
index 69da3a8291..f6463c2633 100644
--- a/mooncake-common/tests/crc_checksum_test.cpp
+++ b/mooncake-common/tests/crc_checksum_test.cpp
@@ -5,8 +5,36 @@
 #include <array>
 #include <cstdint>
 #include <string_view>
+#include <vector>
 
 namespace mooncake {
+namespace {
+
+// Reference implementation: the textbook bit-at-a-time definition of
+// CRC-64/ECMA-182. Deliberately independent of the production tables so that a
+// mistake in the slicing-by-8 tables cannot be masked by a shared bug.
+uint64_t ReferenceCrc64Ecma(const uint8_t* data, size_t size) {
+    constexpr uint64_t kPolynomial = 0x42F0E1EBA9EA3693ULL;
+    uint64_t crc = 0;
+    for (size_t i = 0; i < size; ++i) {
+        crc ^= static_cast<uint64_t>(data[i]) << 56;
+        for (int bit = 0; bit < 8; ++bit) {
+            crc =
+                (crc & (1ULL << 63)) != 0 ? (crc << 1) ^ kPolynomial : crc << 1;
+        }
+    }
+    return crc;
+}
+
+std::vector<uint8_t> MakePattern(size_t size) {
+    std::vector<uint8_t> buffer(size);
+    for (size_t i = 0; i < size; ++i) {
+        buffer[i] = static_cast<uint8_t>(i * 31 + 7);
+    }
+    return buffer;
+}
+
+}  // namespace
 
 TEST(CrcChecksumTest, MatchesCrc64EcmaKnownVector) {
     constexpr std::string_view value = "123456789";
@@ -29,4 +57,41 @@ TEST(CrcChecksumTest, StreamingMatchesContiguousForArbitraryLengths) {
     EXPECT_EQ(ComputeCrcChecksum(nullptr, 0), 0);
 }
 
+// Slicing-by-8 processes whole 8-byte groups and falls back to the
+// byte-at-a-time loop for the remainder, so every length modulo 8 needs
+// coverage, including the sizes just below and above the group width.
+TEST(CrcChecksumTest, MatchesBitwiseReferenceForEveryTailLength) {
+    const std::vector<uint8_t> buffer = MakePattern(129);
+    for (size_t size = 0; size <= buffer.size(); ++size) {
+        EXPECT_EQ(ComputeCrcChecksum(buffer.data(), size),
+                  ReferenceCrc64Ecma(buffer.data(), size))
+            << "size=" << size;
+    }
+}
+
+// A split can leave the register mid-group, which forces the next Update to
+// start with the byte-at-a-time path. The result must still match the
+// contiguous computation for every split point.
+TEST(CrcChecksumTest, StreamingMatchesContiguousForEverySplitPoint) {
+    const std::vector<uint8_t> buffer = MakePattern(64);
+    const uint64_t expected = ReferenceCrc64Ecma(buffer.data(), buffer.size());
+    for (size_t split = 0; split <= buffer.size(); ++split) {
+        CrcChecksum streaming;
+        streaming.Update(buffer.data(), split);
+        streaming.Update(buffer.data() + split, buffer.size() - split);
+        EXPECT_EQ(streaming.Finalize(), expected) << "split=" << split;
+    }
+}
+
+// The 8-byte load must not assume any particular alignment of the input.
+TEST(CrcChecksumTest, MatchesBitwiseReferenceForUnalignedInput) {
+    const std::vector<uint8_t> buffer = MakePattern(80);
+    for (size_t offset = 1; offset < 8; ++offset) {
+        const size_t size = buffer.size() - offset;
+        EXPECT_EQ(ComputeCrcChecksum(buffer.data() + offset, size),
+                  ReferenceCrc64Ecma(buffer.data() + offset, size))
+            << "offset=" << offset;
+    }
+}
+
 }  // namespace mooncake
diff --git a/mooncake-common/tests/environ_test.cpp b/mooncake-common/tests/environ_test.cpp
index 4701f6e78e..c37e63763e 100644
--- a/mooncake-common/tests/environ_test.cpp
+++ b/mooncake-common/tests/environ_test.cpp
@@ -13,11 +13,13 @@
 // limitations under the License.
 
 #include "environ.h"
+#include "environment_variable.h"
 
 #include <gtest/gtest.h>
 
 #include <climits>
 #include <cstdlib>
+#include <optional>
 
 using mooncake::Environ;
 
@@ -32,20 +34,9 @@ class EnvironTest : public ::testing::Test {
         unsetenv("MC_TEST_UINT32");
         unsetenv("MC_TEST_UINT64");
         unsetenv("MC_TEST_SIZET");
+        unsetenv("MC_TEST_DOUBLE");
         unsetenv("MC_TEST_BOOL");
         unsetenv("MC_TEST_STRING");
-        // Make sure AWS vars don't leak in from the test runner's env.
-        unsetenv("MOONCAKE_AWS_REGION");
-        unsetenv("MOONCAKE_AWS_S3_ENDPOINT");
-        unsetenv("MOONCAKE_AWS_BUCKET_NAME");
-        unsetenv("MOONCAKE_AWS_ACCESS_KEY_ID");
-        unsetenv("MOONCAKE_AWS_SECRET_ACCESS_KEY");
-        unsetenv("MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING");
-        unsetenv("MOONCAKE_AWS_USE_HTTPS");
-        unsetenv("MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION");
-        unsetenv("MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION");
-        unsetenv("MOONCAKE_AWS_CONNECT_TIMEOUT_MS");
-        unsetenv("MOONCAKE_AWS_REQUEST_TIMEOUT_MS");
         unsetenv("MOONCAKE_STORE_CHECKSUM");
     }
 };
@@ -139,46 +130,44 @@ TEST_F(EnvironTest, UnsignedGettersUseRequestedDefaultForInvalidValues) {
     EXPECT_EQ(Environ::GetUInt64("MC_TEST_UINT64", 23), 23U);
 }
 
-// --- AWS / S3 fields ---
-//
-// NOTE: Environ is a singleton whose constructor caches every value the
-// first time Get() is called. So all AWS env vars must be set BEFORE the
-// first Environ::Get() in this process. We therefore cover the populate
-// path in a single test that takes the singleton's "first call" for
-// itself; the default-path behavior is implicitly covered by Environ's
-// constructor defaults (any earlier test would lock the cache to defaults
-// and prevent us from observing populated values here).
-
-TEST_F(EnvironTest, AwsFieldsPopulateFromEnv) {
-    setenv("MOONCAKE_AWS_REGION", "us-east-1", 1);
-    setenv("MOONCAKE_AWS_S3_ENDPOINT", "https://s3.example.com", 1);
-    setenv("MOONCAKE_AWS_BUCKET_NAME", "my-bucket", 1);
-    setenv("MOONCAKE_AWS_ACCESS_KEY_ID", "AKIA-test", 1);
-    setenv("MOONCAKE_AWS_SECRET_ACCESS_KEY", "secret", 1);
-    setenv("MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING", "0", 1);
-    setenv("MOONCAKE_AWS_USE_HTTPS", "0", 1);
-    setenv("MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION", "when_required", 1);
-    setenv("MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION", "when_supported", 1);
-    setenv("MOONCAKE_AWS_CONNECT_TIMEOUT_MS", "5000", 1);
-    // Bogus request timeout should fall back to the registered default.
-    setenv("MOONCAKE_AWS_REQUEST_TIMEOUT_MS", "bogus", 1);
+// --- GetDouble ---
+
+TEST_F(EnvironTest, GetDoubleValidValue) {
+    setenv("MC_TEST_DOUBLE", " 0.75 ", 1);
+    EXPECT_DOUBLE_EQ(Environ::GetDouble("MC_TEST_DOUBLE", 0.5), 0.75);
+}
+
+TEST_F(EnvironTest, GetDoubleMissingOrInvalidUsesRequestedDefault) {
+    EXPECT_DOUBLE_EQ(Environ::GetDouble("MC_TEST_DOUBLE", 0.5), 0.5);
+    setenv("MC_TEST_DOUBLE", "0.75garbage", 1);
+    EXPECT_DOUBLE_EQ(Environ::GetDouble("MC_TEST_DOUBLE", 0.5), 0.5);
+    setenv("MC_TEST_DOUBLE", "nan", 1);
+    EXPECT_DOUBLE_EQ(Environ::GetDouble("MC_TEST_DOUBLE", 0.5), 0.5);
+}
+
+TEST_F(EnvironTest, StoreChecksumPopulatesFromEnv) {
     setenv("MOONCAKE_STORE_CHECKSUM", "1", 1);
 
     const auto& e = Environ::Get();
-    EXPECT_EQ(e.GetAwsRegion(), "us-east-1");
-    EXPECT_EQ(e.GetAwsS3Endpoint(), "https://s3.example.com");
-    EXPECT_EQ(e.GetAwsBucketName(), "my-bucket");
-    EXPECT_EQ(e.GetAwsAccessKeyId(), "AKIA-test");
-    EXPECT_EQ(e.GetAwsSecretAccessKey(), "secret");
-    EXPECT_FALSE(e.GetAwsUseVirtualAddressing());
-    EXPECT_FALSE(e.GetAwsUseHttps());
-    EXPECT_EQ(e.GetAwsRequestChecksumCalculation(), "when_required");
-    EXPECT_EQ(e.GetAwsResponseChecksumValidation(), "when_supported");
-    EXPECT_EQ(e.GetAwsConnectTimeoutMs(), 5000);
-    EXPECT_EQ(e.GetAwsRequestTimeoutMs(), 30000);
     EXPECT_TRUE(e.GetStoreChecksumEnabled());
 }
 
+TEST_F(EnvironTest, RdmaDataDirectIsOptIn) {
+    class Source : public mooncake::EnvironSource {
+       public:
+        const char* value = nullptr;
+        const char* Get(const char* name) const override {
+            return std::string(name) == "MC_RDMA_DATA_DIRECT" ? value : nullptr;
+        }
+    } source;
+
+    EXPECT_FALSE(Environ(source).GetRdmaDataDirect());
+    source.value = "1";
+    EXPECT_TRUE(Environ(source).GetRdmaDataDirect());
+    source.value = "0";
+    EXPECT_FALSE(Environ(source).GetRdmaDataDirect());
+}
+
 // --- GetSizeT ---
 
 TEST_F(EnvironTest, GetSizeTValidValue) {
@@ -281,6 +270,36 @@ TEST_F(EnvironTest, GetStringWithSpaces) {
     EXPECT_EQ(Environ::GetString("MC_TEST_STRING", ""), "hello world");
 }
 
+TEST_F(EnvironTest, ReadsTypedEnvironmentVariableDefinitions) {
+    constexpr mooncake::EnvironmentVariable<int64_t> number{"MC_TEST_INT64"};
+    constexpr mooncake::EnvironmentVariable<bool> enabled{"MC_TEST_BOOL"};
+    constexpr mooncake::EnvironmentVariable<std::string> text{"MC_TEST_STRING"};
+
+    EXPECT_FALSE(Environ::Read(number).has_value());
+    EXPECT_EQ(Environ::ReadOr(number, int64_t{17}), 17);
+
+    setenv(number.name, "42", 1);
+    setenv(enabled.name, "off", 1);
+    setenv(text.name, "", 1);
+
+    EXPECT_EQ(Environ::Read(number), 42);
+    EXPECT_EQ(Environ::Read(enabled), false);
+    ASSERT_TRUE(Environ::Read(text).has_value());
+    EXPECT_TRUE(Environ::Read(text)->empty());
+}
+
+TEST_F(EnvironTest, TypedReadOrWarnsAndUsesDefaultForInvalidValues) {
+    constexpr mooncake::EnvironmentVariable<int64_t> number{"MC_TEST_INT64"};
+    setenv(number.name, "invalid", 1);
+
+    testing::internal::CaptureStderr();
+    EXPECT_EQ(Environ::ReadOr(number, int64_t{17}), 17);
+    const std::string logs = testing::internal::GetCapturedStderr();
+
+    EXPECT_NE(logs.find("MC_TEST_INT64"), std::string::npos);
+    EXPECT_NE(logs.find("using default 17"), std::string::npos);
+}
+
 int main(int argc, char** argv) {
     ::testing::InitGoogleTest(&argc, argv);
     return RUN_ALL_TESTS();
diff --git a/mooncake-common/tests/environment_value_parser_test.cpp b/mooncake-common/tests/environment_value_parser_test.cpp
new file mode 100644
index 0000000000..e2b02e6a2d
--- /dev/null
+++ b/mooncake-common/tests/environment_value_parser_test.cpp
@@ -0,0 +1,72 @@
+#include "environment_value_parser.h"
+
+#include <gtest/gtest.h>
+
+#include <cerrno>
+#include <cmath>
+#include <cstdint>
+#include <string>
+
+namespace mooncake::test {
+
+TEST(EnvironmentValueParserTest, ParsesSupportedTypes) {
+    EXPECT_EQ(TryParseEnvironmentValue<int64_t>(" \t+42\r\n"), 42);
+    EXPECT_EQ(TryParseEnvironmentValue<bool>("ON"), true);
+    EXPECT_EQ(TryParseEnvironmentValue<std::string>("value"), "value");
+
+    const auto ratio = TryParseEnvironmentValue<double>("0.75");
+    ASSERT_TRUE(ratio.has_value());
+    EXPECT_DOUBLE_EQ(*ratio, 0.75);
+}
+
+TEST(EnvironmentValueParserTest, RejectsInvalidTypedValues) {
+    EXPECT_FALSE(TryParseEnvironmentValue<int64_t>("").has_value());
+    EXPECT_FALSE(
+        TryParseEnvironmentValue<int64_t>("not-an-integer").has_value());
+    EXPECT_FALSE(TryParseEnvironmentValue<bool>("").has_value());
+    EXPECT_FALSE(TryParseEnvironmentValue<bool>("unknown").has_value());
+    EXPECT_FALSE(TryParseEnvironmentValue<double>("").has_value());
+    EXPECT_FALSE(TryParseEnvironmentValue<double>("not-a-ratio").has_value());
+}
+
+TEST(EnvironmentValueParserTest, RequiresFiniteCompleteDoubleValues) {
+    EXPECT_FALSE(TryParseEnvironmentValue<double>("0.75suffix").has_value());
+    EXPECT_FALSE(TryParseEnvironmentValue<double>("nan").has_value());
+
+    const auto ratio = TryParseEnvironmentValue<double>(" 0.75 ");
+    ASSERT_TRUE(ratio.has_value());
+    EXPECT_DOUBLE_EQ(*ratio, 0.75);
+}
+
+TEST(EnvironmentValueParserTest, SupportsExplicitLenientDoubleParsing) {
+    const EnvironmentDoubleParseOptions options{
+        .allow_trailing_characters = true,
+        .allow_non_finite = true,
+    };
+
+    const auto suffixed = TryParseEnvironmentDouble("0.75suffix", options);
+    ASSERT_TRUE(suffixed.has_value());
+    EXPECT_DOUBLE_EQ(*suffixed, 0.75);
+
+    const auto nan = TryParseEnvironmentDouble("nan", options);
+    ASSERT_TRUE(nan.has_value());
+    EXPECT_TRUE(std::isnan(*nan));
+
+    EXPECT_FALSE(TryParseEnvironmentDouble(" invalid", options).has_value());
+}
+
+TEST(EnvironmentValueParserTest, PreservesEmptyStrings) {
+    const auto empty = TryParseEnvironmentValue<std::string>("");
+    ASSERT_TRUE(empty.has_value());
+    EXPECT_TRUE(empty->empty());
+}
+
+TEST(EnvironmentValueParserTest, PreservesErrno) {
+    for (const char* value : {"0.75", "not-a-ratio", "1e9999"}) {
+        errno = EDOM;
+        static_cast<void>(TryParseEnvironmentValue<double>(value));
+        EXPECT_EQ(errno, EDOM);
+    }
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-common/tests/ib_link_speed_test.cpp b/mooncake-common/tests/ib_link_speed_test.cpp
new file mode 100644
index 0000000000..774dbcf687
--- /dev/null
+++ b/mooncake-common/tests/ib_link_speed_test.cpp
@@ -0,0 +1,81 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+
+#include "ib_link_speed.h"
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+struct LinkSpeedCase {
+    int active_speed;
+    int active_width;
+    double expected_gbps;
+};
+
+// active_speed / active_width are the raw ibv_port_attr encodings from
+// ibv_query_port(3): speed is the per-lane rate, width is the lane count.
+TEST(IbLinkSpeedTest, ConvertsPortAttrEncodingsToGbps) {
+    const LinkSpeedCase cases[] = {
+        {1, 1, 2.5},      // SDR x1
+        {2, 2, 20.0},     // DDR x4
+        {4, 2, 40.0},     // QDR x4
+        {8, 2, 40.0},     // FDR10 x4
+        {16, 2, 56.0},    // FDR x4
+        {32, 2, 100.0},   // EDR x4  (ConnectX-4/5 100G)
+        {64, 2, 200.0},   // HDR x4  (ConnectX-6 200G)
+        {128, 2, 400.0},  // NDR x4 (ConnectX-7 400G)
+        {256, 2, 800.0},  // XDR x4
+        {32, 16, 50.0},   // EDR x2
+        {64, 1, 50.0},    // HDR x1
+        {64, 4, 400.0},   // HDR x8
+        {32, 8, 300.0},   // EDR x12
+    };
+    for (const auto& c : cases) {
+        EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(c.active_speed, c.active_width),
+                         c.expected_gbps)
+            << "speed=" << c.active_speed << " width=" << c.active_width;
+    }
+}
+
+// An encoding the table does not know must not be guessed at: 0 tells the
+// caller the speed is unknown so it can fall back explicitly.
+// ibv_query_port_speed() (rdma-core >= 62) reports the port's *effective*
+// speed in Mb/s: for a VF over LAG that is the bandwidth left
+// after a PF drops out, which the encoded link rate cannot express. When
+// available it wins; otherwise the encodings decide as before.
+TEST(IbLinkSpeedTest, EffectiveSpeedWinsOverEncodedRate) {
+    // 400G link, but the LAG under this VF is down to one 200G PF.
+    EXPECT_DOUBLE_EQ(ibPortSpeedGbps(200'000, 128, 2), 200.0);
+    // Effective speed known, encodings unknown: still usable.
+    EXPECT_DOUBLE_EQ(ibPortSpeedGbps(100'000, 0, 0), 100.0);
+}
+
+TEST(IbLinkSpeedTest, EncodedRateWhenEffectiveSpeedIsUnavailable) {
+    // 0 = the library predates the verb or the driver reported nothing.
+    EXPECT_DOUBLE_EQ(ibPortSpeedGbps(0, 128, 2), 400.0);
+    EXPECT_DOUBLE_EQ(ibPortSpeedGbps(0, 0, 0), 0.0);
+}
+
+TEST(IbLinkSpeedTest, UnknownEncodingsReportZero) {
+    EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(0, 2), 0.0);   // speed unset
+    EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(32, 0), 0.0);  // width unset
+    EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(3, 2), 0.0);   // not a speed bit
+    EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(32, 3), 0.0);  // not a width bit
+    EXPECT_DOUBLE_EQ(ibLinkSpeedGbps(-1, 2), 0.0);  // classic TE default
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-common/tests/rpc_client_io_context_test.cpp b/mooncake-common/tests/rpc_client_io_context_test.cpp
index c3b18c7127..29b69ddc18 100644
--- a/mooncake-common/tests/rpc_client_io_context_test.cpp
+++ b/mooncake-common/tests/rpc_client_io_context_test.cpp
@@ -51,7 +51,11 @@ TEST(RpcClientIoContextPoolTest, ReplacesPoolWhenTargetChanges) {
     auto second = pools.GetOrCreateClientPool("127.0.0.1:10002");
     EXPECT_NE(first, second);
     first.reset();
-    EXPECT_TRUE(old_pool.expired());
+    // Pools live in the process-wide registry by design: a ylt pool owns
+    // background reconnect coroutines that reference pool storage, so freeing
+    // one mid-retry is a use-after-free regardless of request draining
+    // (#3909). Switching address only re-points the holder.
+    EXPECT_FALSE(old_pool.expired());
     EXPECT_EQ(pools.GetClientPool(), second);
 }
 
@@ -94,6 +98,45 @@ TEST(RpcClientIoContextPoolTest, SendsToNewAddressAfterSwitch) {
     second_server.stop();
 }
 
+TEST(RpcClientIoContextPoolTest, RegistrySharesPoolOnlyForIdenticalConfig) {
+    const std::string address = "127.0.0.1:59998";
+    RpcClientPool first(GetFirstTestRpcClientIoContextPool());
+    auto first_pool = first.GetOrCreateClientPool(address);
+
+    // Identical configuration on a second holder shares the pool: that is
+    // the case the keep-alive registry exists for.
+    RpcClientPool same(GetFirstTestRpcClientIoContextPool());
+    EXPECT_EQ(first_pool.get(), same.GetOrCreateClientPool(address).get());
+
+    // A different policy on the same address gets its own pool: the
+    // foreground master pool is resilient while an HA probe on that address
+    // must fast-fail, and collapsing the two hands the probe the foreground
+    // retry budget (#3943 meets the HA policy split from #3743).
+    RpcClientPool::PoolConfig different;
+    different.max_connection = 7;
+    different.client_config.connect_timeout_duration =
+        std::chrono::milliseconds(1234);
+    different.client_config.request_timeout_duration =
+        std::chrono::milliseconds(5678);
+    RpcClientPool second(GetFirstTestRpcClientIoContextPool(), different);
+    EXPECT_NE(first_pool.get(), second.GetOrCreateClientPool(address).get());
+}
+
+TEST(RpcClientIoContextPoolTest, KeepClientPoolsAliveRetainsCollection) {
+    using Pools = coro_io::client_pools<coro_rpc::coro_rpc_client>;
+    std::weak_ptr<Pools> weak;
+    {
+        auto pools = std::make_shared<Pools>(
+            coro_io::client_pool<coro_rpc::coro_rpc_client>::pool_config{},
+            GetFirstTestRpcClientIoContextPool());
+        weak = pools;
+        detail::KeepClientPoolsAlive(std::move(pools));
+    }
+    // The collection must outlive its owner (#3909/#3943): pools inside host
+    // reconnect coroutines that reference pool storage past teardown.
+    EXPECT_FALSE(weak.expired());
+}
+
 }  // namespace
 }  // namespace mooncake
 
diff --git a/mooncake-common/tests/rpc_drain_guard_test.cpp b/mooncake-common/tests/rpc_drain_guard_test.cpp
new file mode 100644
index 0000000000..3b5445c85c
--- /dev/null
+++ b/mooncake-common/tests/rpc_drain_guard_test.cpp
@@ -0,0 +1,96 @@
+// Tests for RpcDrainGuard: the teardown guard that keeps a shared RPC pool
+// from being released under a suspended request coroutine (#3909).
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <memory>
+#include <thread>
+
+#include "rpc_client_io_context.h"
+
+namespace mooncake {
+namespace {
+
+TEST(RpcDrainGuardTest, DrainWaitsForInFlightAndStopsNewCalls) {
+    RpcDrainGuard guard;
+
+    auto slow_call = [&] {
+        RpcDrainGuard::ScopedCall call(guard);
+        if (!call.ok()) return false;
+        std::this_thread::sleep_for(std::chrono::milliseconds(150));
+        return true;
+    };
+
+    bool call_result = false;
+    std::thread worker([&] { call_result = slow_call(); });
+    // let the worker enter the guard before the drain starts
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+
+    const auto started = std::chrono::steady_clock::now();
+    EXPECT_TRUE(guard.drain_for(std::chrono::seconds(5)));
+    const auto waited = std::chrono::steady_clock::now() - started;
+    // the drain actually waited for the in-flight call, not just returned
+    EXPECT_GE(waited, std::chrono::milliseconds(100));
+    worker.join();
+    EXPECT_TRUE(call_result);
+
+    // once drained, new calls are refused
+    EXPECT_FALSE(slow_call());
+}
+
+TEST(RpcDrainGuardTest, DrainWithNothingInFlightReturnsImmediately) {
+    RpcDrainGuard guard;
+    const auto started = std::chrono::steady_clock::now();
+    EXPECT_TRUE(guard.drain_for(std::chrono::seconds(5)));
+    EXPECT_LT(std::chrono::steady_clock::now() - started,
+              std::chrono::milliseconds(500));
+}
+
+TEST(RpcDrainGuardTest, DrainTimeoutReportsFalse) {
+    RpcDrainGuard guard;
+    std::atomic<bool> release{false};
+    std::thread worker([&] {
+        RpcDrainGuard::ScopedCall call(guard);
+        while (!release.load()) std::this_thread::yield();
+    });
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+
+    EXPECT_FALSE(guard.drain_for(std::chrono::milliseconds(50)));
+
+    release.store(true);
+    worker.join();
+}
+
+// A timed-out drain must leave the counters consistent: once the straggler
+// exits, a fresh drain completes.
+TEST(RpcDrainGuardTest, TimedOutDrainThenLateLeaveDrainsCleanly) {
+    RpcDrainGuard guard;
+    std::atomic<bool> release{false};
+    std::thread worker([&] {
+        RpcDrainGuard::ScopedCall call(guard);
+        while (!release.load()) std::this_thread::yield();
+    });
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+
+    EXPECT_FALSE(guard.drain_for(std::chrono::milliseconds(50)));
+
+    release.store(true);
+    worker.join();
+    EXPECT_TRUE(guard.drain_for(std::chrono::seconds(1)));
+}
+
+// Teardown after a timed-out drain destroys the guard while a call is still
+// in flight; the shared state keeps the late leave() safe. Run this under
+// ASAN to give the test its teeth (#3943 review).
+TEST(RpcDrainGuardTest, ScopedCallSurvivesGuard) {
+    auto guard = std::make_unique<RpcDrainGuard>();
+    auto call = std::make_unique<RpcDrainGuard::ScopedCall>(*guard);
+    ASSERT_TRUE(call->ok());
+    guard.reset();
+    call.reset();
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-conductor/CMakeLists.txt b/mooncake-conductor/CMakeLists.txt
new file mode 100644
index 0000000000..d870245e7a
--- /dev/null
+++ b/mooncake-conductor/CMakeLists.txt
@@ -0,0 +1,117 @@
+cmake_minimum_required(VERSION 3.16)
+
+if(NOT GLOBAL_CONFIG)
+  project(mooncake-conductor CXX)
+  set(CMAKE_CXX_STANDARD 20)
+  set(CMAKE_CXX_STANDARD_REQUIRED ON)
+  include(../mooncake-common/FindJsonCpp.cmake)
+  include(../mooncake-common/FindGLOG.cmake)
+  # Match the top-level common.cmake policy: keep debuginfo by default.
+  if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE "RelWithDebInfo")
+  endif()
+endif()
+
+find_package(Threads REQUIRED)
+find_package(OpenSSL REQUIRED COMPONENTS Crypto)
+
+# cppzmq and msgpack-cxx are header-only C++ bindings whose packaging varies:
+# some distributions ship a CMake package config, while Debian and Ubuntu up to
+# 22.04 bundle the headers into libzmq3-dev and libmsgpack-dev with no config at
+# all. Prefer the config when present and otherwise locate the headers directly,
+# so both layouts configure. cppzmq additionally needs the libzmq C library;
+# msgpack-cxx is header-only.
+find_package(cppzmq QUIET)
+if(TARGET cppzmq)
+  set(CONDUCTOR_ZMQ_LIBS cppzmq)
+  message(STATUS "conductor: cppzmq via package config")
+else()
+  find_path(CONDUCTOR_ZMQ_INCLUDE_DIR zmq.hpp)
+  find_library(CONDUCTOR_ZMQ_LIBRARY NAMES zmq libzmq)
+  if(NOT CONDUCTOR_ZMQ_INCLUDE_DIR OR NOT CONDUCTOR_ZMQ_LIBRARY)
+    message(
+      FATAL_ERROR
+        "cppzmq headers (zmq.hpp) or libzmq not found; install cppzmq-dev or libzmq3-dev"
+    )
+  endif()
+  set(CONDUCTOR_ZMQ_LIBS ${CONDUCTOR_ZMQ_LIBRARY})
+  set(CONDUCTOR_ZMQ_INCLUDES ${CONDUCTOR_ZMQ_INCLUDE_DIR})
+  message(
+    STATUS "conductor: cppzmq via headers in ${CONDUCTOR_ZMQ_INCLUDE_DIR}")
+endif()
+
+find_package(msgpack-cxx QUIET)
+if(TARGET msgpack-cxx)
+  set(CONDUCTOR_MSGPACK_LIBS msgpack-cxx)
+  message(STATUS "conductor: msgpack-cxx via package config")
+else()
+  find_path(CONDUCTOR_MSGPACK_INCLUDE_DIR msgpack.hpp)
+  if(NOT CONDUCTOR_MSGPACK_INCLUDE_DIR)
+    message(
+      FATAL_ERROR
+        "msgpack C++ headers (msgpack.hpp) not found; install libmsgpack-cxx-dev or libmsgpack-dev"
+    )
+  endif()
+  set(CONDUCTOR_MSGPACK_INCLUDES ${CONDUCTOR_MSGPACK_INCLUDE_DIR})
+  message(
+    STATUS
+      "conductor: msgpack-cxx via headers in ${CONDUCTOR_MSGPACK_INCLUDE_DIR}")
+endif()
+
+add_library(
+  conductor_cpp_core STATIC
+  src/common/utils.cpp src/prefixindex/hash_strategy.cpp
+  src/prefixindex/prefix_indexer.cpp src/zmq/msg_decoder.cpp
+  src/zmq/zmq_client.cpp src/kvevent/object_key_parser.cpp)
+
+# mooncake-common headers are consumed directly instead of linking
+# mooncake_common: the helpers conductor needs (ascii_string.h,
+# integer_parser.h) are header-only, so this reuses them without taking on that
+# target's asio/yaml-cpp/yalantinglibs dependencies. Keeps the standalone build
+# resolvable against glog/JsonCpp/Threads alone.
+target_include_directories(
+  conductor_cpp_core
+  PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include
+         ${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-common/include
+         ${CONDUCTOR_ZMQ_INCLUDES} ${CONDUCTOR_MSGPACK_INCLUDES})
+
+target_link_libraries(
+  conductor_cpp_core
+  PUBLIC OpenSSL::Crypto ${CONDUCTOR_ZMQ_LIBS} ${CONDUCTOR_MSGPACK_LIBS}
+         glog::glog JsonCpp::JsonCpp Threads::Threads)
+
+# The /query hash chain prefers the low-level SHA256_* API, which hashes through
+# a stack context instead of allocating an EVP context per call. Those
+# declarations are hidden in OpenSSL no-deprecated builds, so probe for them and
+# fall back to the EVP backend when unavailable. FIPS deployments should force
+# the EVP path explicitly with -DCONDUCTOR_FORCE_EVP_SHA256=ON.
+option(CONDUCTOR_FORCE_EVP_SHA256 "Force the EVP SHA-256 backend (e.g. FIPS)"
+       OFF)
+if(NOT CONDUCTOR_FORCE_EVP_SHA256)
+  include(CheckCXXSourceCompiles)
+  set(CMAKE_REQUIRED_INCLUDES ${OPENSSL_INCLUDE_DIR})
+  set(CMAKE_REQUIRED_LIBRARIES OpenSSL::Crypto)
+  check_cxx_source_compiles(
+    "
+    #define OPENSSL_SUPPRESS_DEPRECATED
+    #include <openssl/sha.h>
+    int main() { SHA256_CTX c; return SHA256_Init(&c); }
+  "
+    CONDUCTOR_HAS_LOWLEVEL_SHA256)
+  unset(CMAKE_REQUIRED_INCLUDES)
+  unset(CMAKE_REQUIRED_LIBRARIES)
+endif()
+if(CONDUCTOR_HAS_LOWLEVEL_SHA256)
+  target_compile_definitions(conductor_cpp_core
+                             PRIVATE CONDUCTOR_HAS_LOWLEVEL_SHA256=1)
+  message(STATUS "conductor: SHA-256 backend = low-level SHA256_*")
+else()
+  message(
+    STATUS
+      "conductor: SHA-256 backend = EVP (low-level API unavailable or forced)")
+endif()
+
+if(BUILD_UNIT_TESTS)
+  enable_testing()
+  add_subdirectory(tests)
+endif()
diff --git a/mooncake-conductor/include/conductor/common/types.h b/mooncake-conductor/include/conductor/common/types.h
new file mode 100644
index 0000000000..40f7f6733b
--- /dev/null
+++ b/mooncake-conductor/include/conductor/common/types.h
@@ -0,0 +1,72 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace mooncake::conductor::common {
+
+enum class PublisherKind { kVllm, kMooncake, kSglang };
+
+inline constexpr std::string_view PublisherKindName(PublisherKind kind) {
+    switch (kind) {
+        case PublisherKind::kVllm:
+            return "vLLM";
+        case PublisherKind::kMooncake:
+            return "Mooncake";
+        case PublisherKind::kSglang:
+            return "SGLang";
+    }
+    return "unknown";
+}
+
+inline std::optional<PublisherKind> ParsePublisherKind(std::string_view value) {
+    if (value == "vLLM") {
+        return PublisherKind::kVllm;
+    }
+    if (value == "Mooncake") {
+        return PublisherKind::kMooncake;
+    }
+    if (value == "SGLang") {
+        return PublisherKind::kSglang;
+    }
+    return std::nullopt;
+}
+
+struct HashProfileConfig {
+    std::string strategy;
+    std::string algorithm;
+    std::string python_hash_seed;
+    std::string index_projection;
+
+    bool operator==(const HashProfileConfig&) const = default;
+};
+
+struct ResolvedHashProfile {
+    std::string strategy;
+    std::string algorithm;
+    std::string python_hash_seed;
+    std::string root_digest;
+    std::string index_projection;
+
+    bool operator==(const ResolvedHashProfile&) const = default;
+};
+
+struct ServiceConfig {
+    std::string endpoint;         // kv publisher endpoint
+    std::string replay_endpoint;  // replay publisher endpoint
+    PublisherKind publisher_kind = PublisherKind::kVllm;
+    std::string model_name;  // Model name hosted by the service
+    std::string lora_name;
+    std::string tenant_id;    // (optional), default use 'default'
+    std::string instance_id;  // required
+    int64_t block_size = 0;
+    int dp_rank = 0;
+    std::optional<int64_t> cache_group;
+    ResolvedHashProfile hash_profile;
+
+    bool operator==(const ServiceConfig&) const = default;
+};
+
+}  // namespace mooncake::conductor::common
diff --git a/mooncake-conductor/include/conductor/common/utils.h b/mooncake-conductor/include/conductor/common/utils.h
new file mode 100644
index 0000000000..e46a155aef
--- /dev/null
+++ b/mooncake-conductor/include/conductor/common/utils.h
@@ -0,0 +1,23 @@
+#pragma once
+
+// Conductor-private helpers.
+
+#include <string>
+
+namespace mooncake::conductor::common {
+
+struct LogLevelConfig {
+    int min_severity;
+    int verbosity;
+
+    bool operator==(const LogLevelConfig&) const = default;
+};
+
+LogLevelConfig ParseLogLevel();
+
+std::string LoadEnv(const std::string& env_name,
+                    const std::string& default_env);
+
+int LoadIntEnv(const std::string& env_name, int default_env);
+
+}  // namespace mooncake::conductor::common
diff --git a/mooncake-conductor/include/conductor/kvevent/object_key_parser.h b/mooncake-conductor/include/conductor/kvevent/object_key_parser.h
new file mode 100644
index 0000000000..8e48610259
--- /dev/null
+++ b/mooncake-conductor/include/conductor/kvevent/object_key_parser.h
@@ -0,0 +1,32 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+#include "conductor/prefixindex/types.h"
+
+namespace mooncake::conductor::kvevent {
+
+struct ParsedSglangObjectKey {
+    // The key prefix through the logical hash, excluding physical suffixes
+    // such as _0_k/_0_v or _0_temporal.
+    std::string logical_key;
+    std::string full_hash;
+    std::string namespace_prefix;
+    std::string component_suffix;
+    prefixindex::ProjectedPrefix prefix;
+};
+
+// Parse a SGLang Mooncake object key.  SGLang keys contain a complete
+// lower/upper-case SHA-256 digest followed by an optional physical component
+// suffix.  The projected hash is the first 64 bits of the digest, represented
+// as an unsigned bit pattern.
+std::string ParseSglangObjectKey(const std::string& object_key,
+                                 ParsedSglangObjectKey* result);
+
+// Compatibility parser for vLLM and vLLM-Ascend connector keys when a
+// Mooncake publisher has been configured to forward only the raw key.
+std::string ParseVllmObjectKey(const std::string& object_key,
+                               ParsedSglangObjectKey* result);
+
+}  // namespace mooncake::conductor::kvevent
diff --git a/mooncake-conductor/include/conductor/prefixindex/hash_strategy.h b/mooncake-conductor/include/conductor/prefixindex/hash_strategy.h
new file mode 100644
index 0000000000..d5cb0da217
--- /dev/null
+++ b/mooncake-conductor/include/conductor/prefixindex/hash_strategy.h
@@ -0,0 +1,77 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "conductor/prefixindex/types.h"
+
+namespace mooncake::conductor::prefixindex {
+
+struct HashBlock {
+    std::array<uint8_t, 32> digest{};
+    ProjectedPrefix projected;
+
+    bool operator==(const HashBlock&) const = default;
+};
+
+// A lazily-evaluated block-hash chain. Blocks are hashed on demand: asking
+// for block i hashes (and caches) every block up to i, so a caller that
+// stops early — e.g. a prefix-index walk whose cursors have all stalled —
+// never pays for the untouched tail.
+class HashChain {
+   public:
+    virtual ~HashChain() = default;
+
+    // Number of logical blocks the chain can produce. The SGLang strategies
+    // include their final partial block; vLLM keeps its complete-block rule.
+    virtual size_t BlockCount() const = 0;
+
+    // Number of blocks hashed so far (observability/testing hook).
+    virtual size_t ComputedCount() const = 0;
+
+    // Returns block index, hashing any uncomputed prefix first. Returns
+    // nullptr and sets error on failure; the error is sticky across calls.
+    virtual const HashBlock* At(size_t index, std::string* error) = 0;
+};
+
+class HashStrategy {
+   public:
+    virtual ~HashStrategy() = default;
+
+    // Computes hashes for the blocks defined by the selected engine strategy.
+    // Returns an empty string on success and leaves out empty on failure.
+    virtual std::string Compute(const ContextKey& context,
+                                std::span<const int32_t> token_ids,
+                                std::optional<std::string> cache_salt,
+                                std::vector<HashBlock>* out) const = 0;
+
+    // Creates a lazy hash chain over the same inputs as Compute. The chain
+    // borrows token_ids; the caller must keep it alive for the chain's
+    // lifetime. Returns nullptr and sets error when the inputs are invalid.
+    virtual std::unique_ptr<HashChain> CreateChain(
+        const ContextKey& context, std::span<const int32_t> token_ids,
+        std::optional<std::string> cache_salt, std::string* error) const = 0;
+};
+
+// Resolves a supported source profile and derives its root digest. Returns an
+// empty string on success.
+std::string ResolveHashProfile(const common::HashProfileConfig& config,
+                               HashProfile* out);
+
+// Returns an empty string when the resolved profile is supported, well formed,
+// and its root digest matches a fresh derivation from python_hash_seed.
+std::string ValidateHashProfile(const HashProfile& profile);
+
+// Returns nullptr and sets error when the resolved profile shape is invalid or
+// unsupported. This consumes the derived root without hashing the seed again.
+std::unique_ptr<HashStrategy> CreateHashStrategy(const HashProfile& profile,
+                                                 std::string* error);
+
+std::string DigestToHex(const std::array<uint8_t, 32>& digest);
+
+}  // namespace mooncake::conductor::prefixindex
diff --git a/mooncake-conductor/include/conductor/prefixindex/prefix_indexer.h b/mooncake-conductor/include/conductor/prefixindex/prefix_indexer.h
new file mode 100644
index 0000000000..0559d5c396
--- /dev/null
+++ b/mooncake-conductor/include/conductor/prefixindex/prefix_indexer.h
@@ -0,0 +1,135 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <list>
+#include <map>
+#include <memory>
+#include <optional>
+#include <set>
+#include <shared_mutex>
+#include <span>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "conductor/prefixindex/types.h"
+
+namespace mooncake::conductor::prefixindex {
+
+struct RegistrationResult {
+    bool inserted = false;
+    std::string error;
+};
+
+struct BlockPresence {
+    std::set<EngineOwner> gpu_owners;
+    std::set<SharedObjectOwner> cpu_owners;
+    std::set<SharedObjectOwner> disk_owners;
+
+    bool Empty() const {
+        return gpu_owners.empty() && cpu_owners.empty() && disk_owners.empty();
+    }
+};
+
+// Maximum number of prefixes tracked for each context.
+constexpr size_t kDefaultMaxBlocks = 200000;
+// Target occupancy ratio for a batched capacity eviction.
+constexpr double kEvictTargetRatio = 0.9;
+
+struct ContextState {
+    explicit ContextState(HashProfile registered_profile,
+                          size_t block_limit = kDefaultMaxBlocks)
+        : profile(std::move(registered_profile)), max_blocks(block_limit) {}
+
+    // Lock order is global context-map mutex, then this mutex. Code holding
+    // this mutex must never reacquire the global mutex.
+    mutable std::shared_mutex mutex;
+    const HashProfile profile;
+    std::map<std::string, std::set<int64_t>> instance_ranks;
+    std::unordered_map<ProjectedPrefix, BlockPresence> blocks;
+
+    // Store order: newest prefix at the front, oldest at the back. Query does
+    // not update this order, so read-only queries can keep a shared lock.
+    std::list<ProjectedPrefix> write_order;
+    std::unordered_map<ProjectedPrefix, std::list<ProjectedPrefix>::iterator>
+        order_pos;
+    const size_t max_blocks;
+    // Cumulative number of entries removed by capacity eviction.
+    int64_t evicted_by_capacity = 0;
+};
+
+struct RankCacheHitResult {
+    int64_t gpu = 0;
+    int64_t cpu = 0;
+    int64_t disk = 0;
+
+    bool operator==(const RankCacheHitResult&) const = default;
+};
+
+struct CacheHitResult {
+    int64_t longest_match_tokens = 0;
+    std::map<int64_t, int64_t> dp;
+    std::map<int64_t, RankCacheHitResult> rank_matches;
+    int64_t gpu = 0;
+    int64_t cpu = 0;
+    int64_t disk = 0;
+};
+
+struct ContextView {
+    ContextKey context;
+    HashProfile profile;
+    std::map<std::string, std::set<int64_t>> instance_ranks;
+    size_t prefix_count = 0;
+};
+
+struct GlobalView {
+    int32_t context_count = 0;
+    std::vector<ContextView> contexts;
+};
+
+class PrefixCacheTable {
+   public:
+    PrefixCacheTable() = default;
+    // Per-context block limit; zero disables capacity eviction.
+    explicit PrefixCacheTable(size_t block_limit) : block_limit_(block_limit) {}
+    PrefixCacheTable(const PrefixCacheTable&) = delete;
+    PrefixCacheTable& operator=(const PrefixCacheTable&) = delete;
+
+    static RegistrationResult ValidateRegistration(
+        const EngineRegistration& registration);
+
+    RegistrationResult Register(const EngineRegistration& registration);
+    std::string ValidateProfileBinding(const ContextKey& context,
+                                       const HashProfile& profile) const;
+    std::string Unregister(const ContextKey& context,
+                           const std::string& instance_id, int64_t dp_rank);
+
+    std::string StoreGpu(const GpuMutation& mutation);
+    std::string RemoveGpu(const GpuMutation& mutation);
+    std::string ClearGpu(const GpuClear& clear);
+
+    std::string StoreShared(const SharedMutation& mutation);
+    std::string RemoveShared(const SharedMutation& mutation);
+    std::string ClearShared(const SharedClear& clear);
+
+    std::map<std::string, CacheHitResult> Query(
+        const ContextKey& context, std::span<const int32_t> token_ids,
+        std::optional<std::string> cache_salt = std::nullopt,
+        std::optional<std::string> instance_filter = std::nullopt) const;
+
+    GlobalView GetGlobalView() const;
+
+   private:
+    friend class PrefixCacheTableTestPeer;
+
+    std::shared_ptr<ContextState> LoadContextState(
+        const ContextKey& context) const;
+
+    mutable std::shared_mutex context_map_mutex_;
+    std::unordered_map<ContextKey, std::shared_ptr<ContextState>> contexts_;
+    const size_t block_limit_ = kDefaultMaxBlocks;
+};
+
+}  // namespace mooncake::conductor::prefixindex
diff --git a/mooncake-conductor/include/conductor/prefixindex/types.h b/mooncake-conductor/include/conductor/prefixindex/types.h
new file mode 100644
index 0000000000..589599848d
--- /dev/null
+++ b/mooncake-conductor/include/conductor/prefixindex/types.h
@@ -0,0 +1,114 @@
+#pragma once
+
+#include <compare>
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "conductor/common/types.h"
+
+namespace mooncake::conductor::prefixindex {
+
+struct ContextKey {
+    std::string tenant_id;
+    std::string model_name;
+    std::string lora_name;
+    int64_t block_size = 0;
+
+    bool operator==(const ContextKey&) const = default;
+};
+
+using HashProfile = common::ResolvedHashProfile;
+
+struct ProjectedPrefix {
+    uint64_t value = 0;
+
+    auto operator<=>(const ProjectedPrefix&) const = default;
+};
+
+enum class StorageTier { kGpu, kCpu, kDisk };
+
+struct EngineOwner {
+    std::string source_stream;
+    std::string instance_id;
+    int64_t dp_rank = 0;
+
+    auto operator<=>(const EngineOwner&) const = default;
+};
+
+struct SharedObjectOwner {
+    std::string source_stream;
+    std::string backend_id;
+    std::string object_id;
+
+    auto operator<=>(const SharedObjectOwner&) const = default;
+};
+
+struct EngineRegistration {
+    ContextKey context;
+    HashProfile profile;
+    std::string instance_id;
+    int64_t dp_rank = 0;
+    int64_t effective_block_size = 0;
+    std::optional<int64_t> cache_group;
+};
+
+struct GpuMutation {
+    ContextKey context;
+    std::vector<ProjectedPrefix> prefixes;
+    EngineOwner owner;
+    int64_t effective_block_size = 0;
+    std::optional<int64_t> cache_group;
+};
+
+struct SharedMutation {
+    ContextKey context;
+    std::vector<ProjectedPrefix> prefixes;
+    StorageTier tier = StorageTier::kCpu;
+    SharedObjectOwner owner;
+    int64_t effective_block_size = 0;
+    std::optional<int64_t> cache_group;
+};
+
+struct GpuClear {
+    ContextKey context;
+    EngineOwner owner;
+    int64_t effective_block_size = 0;
+    std::optional<int64_t> cache_group;
+};
+
+struct SharedClear {
+    ContextKey context;
+    SharedObjectOwner owner;
+    std::optional<StorageTier> tier;
+    int64_t effective_block_size = 0;
+    std::optional<int64_t> cache_group;
+};
+
+}  // namespace mooncake::conductor::prefixindex
+
+template <>
+struct std::hash<mooncake::conductor::prefixindex::ContextKey> {
+    size_t operator()(const mooncake::conductor::prefixindex::ContextKey&
+                          context) const noexcept {
+        size_t seed = 0;
+        auto combine = [&seed](size_t value) {
+            seed ^= value + 0x9e3779b97f4a7c15ULL + (seed << 6) + (seed >> 2);
+        };
+        combine(std::hash<std::string>{}(context.tenant_id));
+        combine(std::hash<std::string>{}(context.model_name));
+        combine(std::hash<std::string>{}(context.lora_name));
+        combine(std::hash<int64_t>{}(context.block_size));
+        return seed;
+    }
+};
+
+template <>
+struct std::hash<mooncake::conductor::prefixindex::ProjectedPrefix> {
+    size_t operator()(mooncake::conductor::prefixindex::ProjectedPrefix prefix)
+        const noexcept {
+        return std::hash<uint64_t>{}(prefix.value);
+    }
+};
diff --git a/mooncake-conductor/include/conductor/zmq/event_type.h b/mooncake-conductor/include/conductor/zmq/event_type.h
new file mode 100644
index 0000000000..7118205c14
--- /dev/null
+++ b/mooncake-conductor/include/conductor/zmq/event_type.h
@@ -0,0 +1,147 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <variant>
+#include <vector>
+
+#include "conductor/common/types.h"
+
+namespace mooncake::conductor::zmq {
+
+using ExternalHash = std::variant<uint64_t, std::vector<uint8_t>>;
+
+struct VllmStoredEvent {
+    std::vector<ExternalHash> block_hashes;
+    std::optional<ExternalHash> parent_block_hash;
+    std::optional<std::vector<int32_t>> token_ids;
+    int64_t block_size = 0;
+    std::optional<int64_t> lora_id;
+    std::optional<std::string> medium;
+    std::optional<std::string> lora_name;
+    bool extra_keys_present = false;
+    std::optional<int64_t> group_idx;
+    std::optional<std::string> kv_cache_spec_kind;
+    std::optional<int64_t> kv_cache_spec_sliding_window;
+};
+
+struct VllmRemovedEvent {
+    std::vector<ExternalHash> block_hashes;
+    std::optional<std::string> medium;
+    std::optional<int64_t> group_idx;
+};
+
+struct VllmClearedEvent {};
+
+using VllmEvent =
+    std::variant<VllmStoredEvent, VllmRemovedEvent, VllmClearedEvent>;
+
+// SGLang's native KV-event protocol is msgspec array-like/tagged data.  Keep
+// its signed wire hashes as uint64 bit patterns internally so all index paths
+// use one unsigned representation.
+struct SglangStoredEvent {
+    std::vector<uint64_t> block_hashes;
+    std::optional<uint64_t> parent_block_hash;
+    std::optional<std::vector<int32_t>> token_ids;
+    int64_t block_size = 0;
+    std::optional<int64_t> lora_id;
+    std::optional<std::string> medium;
+    std::optional<std::string> cache_salt;
+};
+
+struct SglangRemovedEvent {
+    std::vector<uint64_t> block_hashes;
+    std::optional<std::string> medium;
+};
+
+struct SglangClearedEvent {};
+
+using SglangEvent =
+    std::variant<SglangStoredEvent, SglangRemovedEvent, SglangClearedEvent>;
+
+struct MooncakeEventFields {
+    uint64_t event_id = 0;
+    int64_t timestamp_milliseconds = 0;
+    std::optional<std::string> model_name;
+    std::optional<int64_t> block_size;
+    std::optional<std::string> additional_salt;
+    std::optional<std::string> lora_name;
+    std::string tenant_id;
+    std::string backend_id;
+    std::optional<std::string> medium;
+    int64_t data_parallel_rank = 0;
+};
+
+struct MooncakeObjectFields {
+    std::optional<std::string> group_id;
+    std::optional<std::string> object_key;
+    std::optional<std::string> connector_block_hash;
+    std::optional<std::string> cache_prefix;
+    std::optional<int64_t> tp_rank;
+    std::optional<int64_t> head_or_tp_rank;
+    std::optional<int64_t> pcp_rank;
+    std::optional<int64_t> dcp_rank;
+    std::optional<int64_t> pp_rank;
+    std::optional<int64_t> layer_id;
+    std::vector<uint64_t> seq_hashes;
+    std::optional<std::vector<uint64_t>> legacy_block_hashes;
+    std::optional<int64_t> base_block_idx;
+};
+
+struct MooncakeStoredEvent {
+    MooncakeEventFields fields;
+    MooncakeObjectFields object;
+    std::optional<uint64_t> parent_hash;
+    std::optional<std::vector<int32_t>> token_ids;
+};
+
+struct MooncakeRemovedEvent {
+    MooncakeEventFields fields;
+    MooncakeObjectFields object;
+};
+
+struct MooncakeClearedEvent {
+    MooncakeEventFields fields;
+};
+
+using MooncakeEvent = std::variant<MooncakeStoredEvent, MooncakeRemovedEvent,
+                                   MooncakeClearedEvent>;
+
+template <typename Event>
+struct DecodedEvent {
+    std::optional<Event> event;
+    std::string error;
+
+    bool ok() const { return event.has_value(); }
+};
+
+struct VllmEventBatch {
+    double timestamp_seconds = 0;
+    std::vector<DecodedEvent<VllmEvent>> events;
+    std::optional<int64_t> data_parallel_rank;
+};
+
+struct MooncakeEventBatch {
+    int64_t timestamp_milliseconds = 0;
+    std::vector<DecodedEvent<MooncakeEvent>> events;
+    std::optional<int64_t> data_parallel_rank;
+};
+
+struct SglangEventBatch {
+    double timestamp_seconds = 0;
+    std::vector<DecodedEvent<SglangEvent>> events;
+    std::optional<int64_t> data_parallel_rank;
+};
+
+using DecodedBatch =
+    std::variant<VllmEventBatch, MooncakeEventBatch, SglangEventBatch>;
+
+struct MessageMetadata {
+    common::PublisherKind publisher_kind = common::PublisherKind::kVllm;
+    std::string endpoint;
+    std::string topic;
+    int64_t sequence = -1;
+};
+
+}  // namespace mooncake::conductor::zmq
diff --git a/mooncake-conductor/include/conductor/zmq/msg_decoder.h b/mooncake-conductor/include/conductor/zmq/msg_decoder.h
new file mode 100644
index 0000000000..26d128a8dd
--- /dev/null
+++ b/mooncake-conductor/include/conductor/zmq/msg_decoder.h
@@ -0,0 +1,29 @@
+#pragma once
+
+// Strict envelope and recognized-field decoding for the independent vLLM and
+// Mooncake map protocols. Event-local failures are materialized in the batch
+// so valid siblings can still be dispatched in source order.
+
+#include <cstddef>
+#include <string>
+
+#include "conductor/zmq/event_type.h"
+
+namespace mooncake::conductor::zmq {
+
+template <typename Batch>
+struct BatchDecodeResult {
+    bool ok = false;
+    Batch batch;
+    std::string error;
+};
+
+using VllmEventBatchResult = BatchDecodeResult<VllmEventBatch>;
+using MooncakeEventBatchResult = BatchDecodeResult<MooncakeEventBatch>;
+using SglangEventBatchResult = BatchDecodeResult<SglangEventBatch>;
+
+VllmEventBatchResult DecodeVllmEventBatch(const char* data, size_t len);
+MooncakeEventBatchResult DecodeMooncakeEventBatch(const char* data, size_t len);
+SglangEventBatchResult DecodeSglangEventBatch(const char* data, size_t len);
+
+}  // namespace mooncake::conductor::zmq
diff --git a/mooncake-conductor/include/conductor/zmq/zmq_client.h b/mooncake-conductor/include/conductor/zmq/zmq_client.h
new file mode 100644
index 0000000000..4538dce960
--- /dev/null
+++ b/mooncake-conductor/include/conductor/zmq/zmq_client.h
@@ -0,0 +1,168 @@
+#pragma once
+
+#include <zmq.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <shared_mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "conductor/zmq/event_type.h"
+
+namespace mooncake::conductor::zmq {
+
+class ZMQClientTestPeer;
+
+// EventHandler processes received KV events.
+class EventHandler {
+   public:
+    virtual ~EventHandler() = default;
+    // Returns empty string on success, error message otherwise.
+    virtual std::string HandleBatch(const DecodedBatch& batch,
+                                    const MessageMetadata& metadata) = 0;
+
+    // Called once when this source can no longer be recovered without risking
+    // out-of-order mutations. Implementations that maintain an index should
+    // stop serving or invalidate entries attributed to this source until a
+    // full resynchronization has completed.
+    virtual void OnSourceStale(const std::string& cache_pool_key,
+                               const MessageMetadata& metadata,
+                               const std::string& reason) = 0;
+};
+
+struct ZMQClientConfig {
+    std::string cache_pool_key;
+    std::string endpoint;
+    std::string replay_endpoint;
+    std::string model_name;
+    common::PublisherKind publisher_kind = common::PublisherKind::kVllm;
+    std::chrono::milliseconds poll_timeout{100};
+    std::chrono::milliseconds replay_timeout{5000};
+    // Total time allowed to close a sequence gap, including retries.
+    std::chrono::milliseconds replay_recovery_timeout{30000};
+    std::chrono::milliseconds reconnect_delay{1000};
+    // Application-level recovery buffer limits. These bound live messages held
+    // behind a gap as well as replay records waiting to be merged with them.
+    size_t max_recovery_buffered_messages = 10000;
+    size_t max_recovery_buffered_bytes = 64 * 1024 * 1024;
+    // SUB receive high-water mark. Zero leaves the ZeroMQ default unchanged.
+    int rcv_hwm = 200000;
+};
+
+// Returns empty string when valid, error message otherwise.
+std::string ValidateConfig(const ZMQClientConfig& config);
+
+class ZMQClient {
+   public:
+    ZMQClient(ZMQClientConfig config, std::shared_ptr<EventHandler> handler);
+    ~ZMQClient();
+    ZMQClient(const ZMQClient&) = delete;
+    ZMQClient& operator=(const ZMQClient&) = delete;
+
+    // Establishes the SUB and DEALER sockets. Returns empty string on
+    // success. Safe to call when already connected (no-op).
+    std::string Connect();
+
+    // Connects and starts the background event loop thread. Returns
+    // empty string on success.
+    std::string Start();
+
+    // Stops the event loop (stop flag + join) and closes all sockets.
+    // Idempotent — stop, wait for the loop to join, then clean up; safe
+    // to invoke repeatedly.
+    void Stop();
+
+    int64_t GetLastSequence() const;
+    bool IsStale() const;
+    std::string GetStaleReason() const;
+
+    // Cumulative counts inferred from transport sequence gaps.
+    int64_t GetDroppedEvents() const { return dropped_events_.load(); }
+    int64_t GetGapCount() const { return gap_count_.load(); }
+
+   private:
+    friend class ZMQClientTestPeer;
+
+    void Loop();
+    void HandleReconnect();
+    bool IsConnected() const;
+    void MarkDisconnected();
+    // The following require holding mu_ (exclusive):
+    void CleanupSocketsLocked();
+
+    std::string Consume();
+    std::string ProcessMessage();
+
+    struct BufferedMessage {
+        std::string topic;
+        int64_t sequence;
+        std::string payload;
+    };
+
+    enum class ReplayFailure {
+        kNone,
+        kRetryable,
+        kUnrecoverable,
+    };
+
+    struct ReplayResult {
+        std::vector<BufferedMessage> messages;
+        std::string error;
+        ReplayFailure failure = ReplayFailure::kNone;
+
+        bool ok() const { return failure == ReplayFailure::kNone; }
+    };
+
+    ReplayResult RequestReplay(
+        int64_t from_seq, std::optional<int64_t> until_seq,
+        std::chrono::steady_clock::time_point recovery_deadline);
+    std::string ResetReplaySocket();
+    std::string DispatchMessage(const std::string& topic, int64_t sequence,
+                                const char* payload, size_t payload_size);
+    void UpdateLastSequence(int64_t sequence);
+    bool BufferMessage(BufferedMessage message, std::string* error);
+    std::string DrainBufferedMessages(bool allow_initial_baseline = false);
+    void StartRecovery(const std::string& reason);
+    std::string AttemptRecovery();
+    void MarkStale(const std::string& reason);
+
+    ZMQClientConfig config_;
+    std::shared_ptr<EventHandler> event_handler_;
+
+    ::zmq::context_t zmq_context_{1};
+    std::unique_ptr<::zmq::socket_t> sub_socket_;
+    std::unique_ptr<::zmq::socket_t> replay_socket_;
+
+    // State management.
+    mutable std::shared_mutex mu_;
+    bool connected_ = false;
+    // Highest sequence applied contiguously. It must never advance across a
+    // gap; buffered_messages_ holds live/replay records beyond such a gap.
+    int64_t last_seq_ = -1;
+    int64_t last_live_seq_ = -1;
+    std::map<int64_t, BufferedMessage> buffered_messages_;
+    size_t buffered_message_bytes_ = 0;
+    bool recovery_in_progress_ = false;
+    std::chrono::steady_clock::time_point recovery_deadline_{};
+    bool stale_ = false;
+    std::string stale_reason_;
+    std::chrono::milliseconds reconnect_delay_;
+    // Counters updated when a transport sequence skips one or more events.
+    std::atomic<int64_t> dropped_events_{0};
+    std::atomic<int64_t> gap_count_{0};
+
+    // Lifecycle.
+    std::atomic<bool> stop_requested_{false};
+    std::thread loop_thread_;
+    std::mutex stop_mu_;  // serialises concurrent Stop() calls
+};
+
+}  // namespace mooncake::conductor::zmq
diff --git a/mooncake-conductor/src/common/utils.cpp b/mooncake-conductor/src/common/utils.cpp
new file mode 100644
index 0000000000..2b9dc0b0c6
--- /dev/null
+++ b/mooncake-conductor/src/common/utils.cpp
@@ -0,0 +1,63 @@
+#include "conductor/common/utils.h"
+
+#include <glog/logging.h>
+
+#include <cstdlib>
+#include <string>
+
+#include "ascii_string.h"
+#include "integer_parser.h"
+
+namespace mooncake::conductor::common {
+
+LogLevelConfig ParseLogLevel() {
+    constexpr LogLevelConfig kInfo{google::GLOG_INFO, 0};
+
+    const char* level_env = std::getenv("CONDUCTOR_LOG_LEVEL");
+    const std::string level_str = level_env ? level_env : "";
+    if (level_str.empty()) {
+        return kInfo;
+    }
+
+    const std::string lower = AsciiToLower(level_str);
+    if (lower == "debug") return {google::GLOG_INFO, 1};
+    if (lower == "info") return kInfo;
+    if (lower == "warn") return {google::GLOG_WARNING, 0};
+    if (lower == "error") return {google::GLOG_ERROR, 0};
+
+    LOG(WARNING) << "Invalid log level specified, defaulting to INFO"
+                 << " level=" << level_str;
+    return kInfo;
+}
+
+std::string LoadEnv(const std::string& env_name,
+                    const std::string& default_env) {
+    const char* value = std::getenv(env_name.c_str());
+    if (value == nullptr || value[0] == '\0') {
+        LOG(WARNING) << "environment variable is not set, using default value"
+                     << " envName=" << env_name
+                     << " defaultValue=" << default_env;
+        return default_env;
+    }
+    return value;
+}
+
+int LoadIntEnv(const std::string& env_name, int default_env) {
+    const char* raw = std::getenv(env_name.c_str());
+    const std::string value = raw ? raw : "";
+    if (!value.empty()) {
+        // Strict on purpose: no surrounding whitespace, no trailing garbage.
+        const auto parsed =
+            TryParseInteger<int>(value, {.allow_leading_plus = true});
+        if (parsed.has_value()) {
+            return *parsed;
+        }
+        LOG(ERROR) << "invalid value for environment variable"
+                   << " envName=" << env_name << " value=" << value;
+    }
+    LOG(WARNING) << "environment variable is not set, using default value"
+                 << " envName=" << env_name << " defaultValue=" << default_env;
+    return default_env;
+}
+
+}  // namespace mooncake::conductor::common
diff --git a/mooncake-conductor/src/kvevent/object_key_parser.cpp b/mooncake-conductor/src/kvevent/object_key_parser.cpp
new file mode 100644
index 0000000000..a800692a22
--- /dev/null
+++ b/mooncake-conductor/src/kvevent/object_key_parser.cpp
@@ -0,0 +1,278 @@
+#include "conductor/kvevent/object_key_parser.h"
+
+#include <charconv>
+#include <string_view>
+#include <vector>
+
+#include "ascii_string.h"
+#include "integer_parser.h"
+
+namespace mooncake::conductor::kvevent {
+namespace {
+
+bool IsHex(char value) {
+    return (value >= '0' && value <= '9') || (value >= 'a' && value <= 'f') ||
+           (value >= 'A' && value <= 'F');
+}
+
+std::vector<std::string_view> SplitAt(std::string_view value, char separator) {
+    std::vector<std::string_view> parts;
+    size_t begin = 0;
+    while (begin <= value.size()) {
+        const size_t end = value.find(separator, begin);
+        if (end == std::string_view::npos) {
+            parts.emplace_back(value.substr(begin));
+            break;
+        }
+        parts.emplace_back(value.substr(begin, end - begin));
+        begin = end + 1;
+    }
+    return parts;
+}
+
+std::string JoinParts(const std::vector<std::string_view>& parts, size_t begin,
+                      size_t end) {
+    std::string result;
+    for (size_t index = begin; index < end; ++index) {
+        if (!result.empty()) result.push_back('@');
+        result.append(parts[index]);
+    }
+    return result;
+}
+
+bool HasLabel(std::string_view value, std::string_view label) {
+    return value.starts_with(label) && value.size() > label.size();
+}
+
+bool IsNonNegativeDecimal(std::string_view value) {
+    // Unsigned target, so a leading sign is rejected; the default options
+    // reject surrounding whitespace and require the whole view to be consumed.
+    return TryParseInteger<uint64_t>(value).has_value();
+}
+
+bool HasDecimalLabel(std::string_view value, std::string_view label) {
+    return value.starts_with(label) &&
+           IsNonNegativeDecimal(value.substr(label.size()));
+}
+
+bool IsHashText(std::string_view value) {
+    if (value.size() < 16 || value.size() % 2 != 0) return false;
+    for (char character : value) {
+        if (!IsHex(character)) return false;
+    }
+    return true;
+}
+
+std::string_view StripOptionalHexPrefix(std::string_view value) {
+    if (value.starts_with("0x") || value.starts_with("0X")) {
+        value.remove_prefix(2);
+    }
+    return value;
+}
+
+bool IsVllmHashText(std::string_view value) {
+    return IsHashText(StripOptionalHexPrefix(value));
+}
+
+std::string FillProjectedHash(std::string_view hash,
+                              ParsedSglangObjectKey* result, bool first_half) {
+    hash = StripOptionalHexPrefix(hash);
+    if (!IsHashText(hash)) return "object key hash is not valid hex";
+    // IsHashText has restricted the input to hex digits, where ASCII lowering
+    // only touches A-F.
+    result->full_hash = AsciiToLower(hash);
+    result->prefix.value = 0;
+    const size_t offset = first_half ? 0 : result->full_hash.size() - 16;
+    for (size_t index = offset; index < offset + 16; ++index) {
+        const char character = result->full_hash[index];
+        const uint64_t nibble =
+            character <= '9' ? static_cast<uint64_t>(character - '0')
+                             : static_cast<uint64_t>(character - 'a' + 10);
+        result->prefix.value = (result->prefix.value << 4) | nibble;
+    }
+    return "";
+}
+
+}  // namespace
+
+std::string ParseSglangObjectKey(const std::string& object_key,
+                                 ParsedSglangObjectKey* result) {
+    if (result == nullptr) {
+        return "result is null";
+    }
+    *result = {};
+    constexpr size_t kSha256HexLength = 64;
+    size_t hash_start = std::string::npos;
+    for (size_t start = 0; start + kSha256HexLength <= object_key.size();
+         ++start) {
+        if (start != 0 && IsHex(object_key[start - 1])) {
+            continue;
+        }
+        bool valid = true;
+        for (size_t index = 0; index < kSha256HexLength; ++index) {
+            if (!IsHex(object_key[start + index])) {
+                valid = false;
+                break;
+            }
+        }
+        if (!valid || (start + kSha256HexLength < object_key.size() &&
+                       IsHex(object_key[start + kSha256HexLength]))) {
+            continue;
+        }
+        hash_start = start;
+        break;
+    }
+    if (hash_start == std::string::npos) {
+        return "SGLang object_key does not contain an isolated 64-hex hash";
+    }
+
+    const size_t hash_end = hash_start + kSha256HexLength;
+    if (hash_start > 0 && object_key[hash_start - 1] != '_') {
+        return "SGLang hash must be separated from its namespace by '_'";
+    }
+    if (hash_end < object_key.size() && object_key[hash_end] != '_') {
+        return "SGLang hash must be followed by a component suffix";
+    }
+
+    // The scan above accepted only hex digits, so lowering touches A-F alone.
+    result->full_hash = AsciiToLower(
+        std::string_view(object_key).substr(hash_start, kSha256HexLength));
+    result->namespace_prefix = object_key.substr(0, hash_start);
+    if (!result->namespace_prefix.empty() &&
+        result->namespace_prefix.back() == '_') {
+        result->namespace_prefix.pop_back();
+    }
+    result->logical_key = object_key.substr(0, hash_end);
+    result->component_suffix = object_key.substr(hash_end);
+
+    // Base 16, so std::from_chars is used directly: TryParseInteger is
+    // decimal-only and would also reject the trailing hex digits left unread.
+    uint64_t projected = 0;
+    const auto [end, error] = std::from_chars(
+        result->full_hash.data(), result->full_hash.data() + 16, projected, 16);
+    if (error != std::errc{} || end != result->full_hash.data() + 16) {
+        return "failed to project SGLang hash";
+    }
+    result->prefix.value = projected;
+    return "";
+}
+
+std::string ParseVllmObjectKey(const std::string& object_key,
+                               ParsedSglangObjectKey* result) {
+    if (result == nullptr) return "result is null";
+    *result = {};
+    const auto parts = SplitAt(object_key, '@');
+
+    // Current vLLM-Ascend layerwise GVA keys use a compact layout without
+    // field labels: model@hash@head_or_tp_rank, or
+    // model@group_id@hash@head_or_tp_rank for multi-group models.
+    // Handle this before the labelled layouts, which have six or more parts.
+    if (parts.size() == 3 || parts.size() == 4) {
+        const size_t hash_index = parts.size() == 3 ? 1 : 2;
+        const size_t rank_index = parts.size() - 1;
+        const bool valid_group =
+            parts.size() == 3 || IsNonNegativeDecimal(parts[1]);
+        if (!parts[0].empty() && valid_group &&
+            IsVllmHashText(parts[hash_index]) &&
+            IsNonNegativeDecimal(parts[rank_index])) {
+            result->logical_key = object_key;
+            result->namespace_prefix = parts.size() == 3
+                                           ? std::string(parts[0])
+                                           : JoinParts(parts, 0, hash_index);
+            return FillProjectedHash(parts[hash_index], result, false);
+        }
+    }
+
+    if (parts.size() < 6) {
+        return "vLLM object_key has too few fields";
+    }
+
+    // vLLM keys put the connector hash last.  Newer connectors may append
+    // cache namespace metadata (group/cache_role/cache_family) before it;
+    // consume those labels when present while retaining the older layout.
+    for (size_t index = 1; index < parts.size(); ++index) {
+        if (!HasDecimalLabel(parts[index], "tp_rank:")) {
+            continue;
+        }
+        const size_t hash_index = parts.size() - 1;
+        if (index + 3 >= hash_index ||
+            !HasDecimalLabel(parts[index + 1], "pcp") ||
+            !HasDecimalLabel(parts[index + 2], "dcp") ||
+            !HasDecimalLabel(parts[index + 3], "pp_rank:")) {
+            continue;
+        }
+        size_t cursor = index + 4;
+        if (cursor < hash_index && HasDecimalLabel(parts[cursor], "group:")) {
+            ++cursor;
+        }
+        if (cursor < hash_index && HasLabel(parts[cursor], "cache_role:")) {
+            ++cursor;
+        }
+        if (cursor < hash_index && HasLabel(parts[cursor], "cache_family:")) {
+            ++cursor;
+        }
+        if (cursor != hash_index || !IsVllmHashText(parts[hash_index])) {
+            continue;
+        }
+        result->logical_key = object_key;
+        result->namespace_prefix =
+            index > 1 ? JoinParts(parts, 0, index - 1) : "";
+        return FillProjectedHash(parts[hash_index], result, false);
+    }
+
+    // vLLM-Ascend keys have pcp/dcp/head_or_tp_rank, followed by optional
+    // pp/group/cache metadata.  Layerwise keys either use the current
+    // `layer_id:N@hash` form or the historical `hash@N` form.
+    for (size_t index = 1; index < parts.size(); ++index) {
+        if (!HasDecimalLabel(parts[index], "pcp") ||
+            index + 2 >= parts.size() ||
+            !HasDecimalLabel(parts[index + 1], "dcp") ||
+            !HasDecimalLabel(parts[index + 2], "head_or_tp_rank:")) {
+            continue;
+        }
+        const size_t final_part = parts.size() - 1;
+        auto matches_layout = [&](size_t hash_index) {
+            if (hash_index <= index + 2 || !IsVllmHashText(parts[hash_index])) {
+                return false;
+            }
+            size_t cursor = index + 3;
+            if (cursor < hash_index &&
+                HasDecimalLabel(parts[cursor], "pp_rank:")) {
+                ++cursor;
+            }
+            if (cursor < hash_index &&
+                HasDecimalLabel(parts[cursor], "group:")) {
+                ++cursor;
+            }
+            if (cursor < hash_index && HasLabel(parts[cursor], "cache_role:")) {
+                ++cursor;
+            }
+            if (cursor < hash_index &&
+                HasLabel(parts[cursor], "cache_family:")) {
+                ++cursor;
+            }
+            if (cursor < hash_index &&
+                HasDecimalLabel(parts[cursor], "layer_id:")) {
+                ++cursor;
+            }
+            return cursor == hash_index;
+        };
+
+        size_t hash_index = final_part;
+        if (!matches_layout(hash_index) && final_part > index + 3 &&
+            IsNonNegativeDecimal(parts[final_part]) &&
+            matches_layout(final_part - 1)) {
+            hash_index = final_part - 1;
+        }
+        if (hash_index == final_part && !matches_layout(hash_index)) {
+            continue;
+        }
+        result->logical_key = object_key;
+        result->namespace_prefix = std::string(parts[0]);
+        return FillProjectedHash(parts[hash_index], result, false);
+    }
+
+    return "unrecognized vLLM/vLLM-Ascend object_key";
+}
+
+}  // namespace mooncake::conductor::kvevent
diff --git a/mooncake-conductor/src/prefixindex/hash_strategy.cpp b/mooncake-conductor/src/prefixindex/hash_strategy.cpp
new file mode 100644
index 0000000000..ebdb5e3c38
--- /dev/null
+++ b/mooncake-conductor/src/prefixindex/hash_strategy.cpp
@@ -0,0 +1,1151 @@
+#include "conductor/prefixindex/hash_strategy.h"
+
+// Two SHA-256 backends, selected by CONDUCTOR_HAS_LOWLEVEL_SHA256 (probed by
+// CMake).  The low-level SHA256_* API hashes through a stack context, so it
+// skips the per-call EVP context allocation and provider lookup; its
+// declarations are hidden in OpenSSL no-deprecated builds and it bypasses the
+// provider framework FIPS requires, hence the EVP fallback.  Both backends
+// dispatch to the same OpenSSL implementation and produce byte-identical
+// digests.
+#if CONDUCTOR_HAS_LOWLEVEL_SHA256
+#define OPENSSL_SUPPRESS_DEPRECATED
+#include <openssl/sha.h>
+#else
+#include <openssl/evp.h>
+#endif
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+#include <string_view>
+#include <utility>
+
+#include "integer_parser.h"
+
+namespace mooncake::conductor::prefixindex {
+
+namespace {
+
+constexpr size_t kSha256DigestSize = 32;
+constexpr uint64_t kMaxPythonHashSeed = std::numeric_limits<uint32_t>::max();
+
+// ---------------------------------------------------------------------------
+// Recipe boundary
+//
+// The vLLM v1 chain (complete-block selection, full-32-byte parent
+// advancement, SHA-256 digesting, and the low64_be projection) is shared by
+// every supported algorithm.  Each algorithm name selects exactly one value
+// codec that owns serialization of the seed root and of each
+// (parent, token tuple, extra keys) block value.  The codec receives the
+// already-computed extra-key ordering (non-empty LoRA on every block,
+// non-empty cache salt after LoRA only on the first block) and never sees
+// value shapes outside the Conductor query contract.
+//
+// Multimodal and prompt-embedding vLLM extra keys are deliberately NOT
+// representable here: the Conductor query API cannot express them, so the
+// codecs reject that shape by construction instead of approximating it.
+// ---------------------------------------------------------------------------
+
+struct VllmBlockValues {
+    std::span<const uint8_t> parent_digest;  // full 32-byte parent digest
+    std::span<const int32_t> token_ids;      // exactly one complete block
+    const std::string* lora_name;            // nullptr when no LoRA extra key
+    const std::string* cache_salt;           // nullptr when no salt extra key
+};
+
+class VllmValueCodec {
+   public:
+    virtual ~VllmValueCodec() = default;
+
+    virtual void EncodeSeed(std::string_view seed,
+                            std::vector<uint8_t>* out) const = 0;
+    virtual void EncodeBlock(const VllmBlockValues& values,
+                             std::vector<uint8_t>* out) const = 0;
+};
+
+// ---------------------------------------------------------------------------
+// Canonical-CBOR codec (sha256_cbor)
+// ---------------------------------------------------------------------------
+
+void AppendTypeAndLength(uint8_t major_type, uint64_t value,
+                         std::vector<uint8_t>* out) {
+    const uint8_t initial = static_cast<uint8_t>(major_type << 5);
+    if (value < 24) {
+        out->push_back(static_cast<uint8_t>(initial | value));
+        return;
+    }
+    if (value <= std::numeric_limits<uint8_t>::max()) {
+        out->push_back(static_cast<uint8_t>(initial | 24));
+        out->push_back(static_cast<uint8_t>(value));
+        return;
+    }
+    if (value <= std::numeric_limits<uint16_t>::max()) {
+        out->push_back(static_cast<uint8_t>(initial | 25));
+        for (int shift = 8; shift >= 0; shift -= 8) {
+            out->push_back(static_cast<uint8_t>(value >> shift));
+        }
+        return;
+    }
+    if (value <= std::numeric_limits<uint32_t>::max()) {
+        out->push_back(static_cast<uint8_t>(initial | 26));
+        for (int shift = 24; shift >= 0; shift -= 8) {
+            out->push_back(static_cast<uint8_t>(value >> shift));
+        }
+        return;
+    }
+
+    out->push_back(static_cast<uint8_t>(initial | 27));
+    for (int shift = 56; shift >= 0; shift -= 8) {
+        out->push_back(static_cast<uint8_t>(value >> shift));
+    }
+}
+
+void AppendArrayHeader(size_t size, std::vector<uint8_t>* out) {
+    AppendTypeAndLength(4, static_cast<uint64_t>(size), out);
+}
+
+void AppendBytes(std::span<const uint8_t> value, std::vector<uint8_t>* out) {
+    AppendTypeAndLength(2, static_cast<uint64_t>(value.size()), out);
+    out->insert(out->end(), value.begin(), value.end());
+}
+
+void AppendText(std::string_view value, std::vector<uint8_t>* out) {
+    AppendTypeAndLength(3, static_cast<uint64_t>(value.size()), out);
+    out->insert(out->end(), value.begin(), value.end());
+}
+
+void AppendSignedInteger(int32_t value, std::vector<uint8_t>* out) {
+    if (value >= 0) {
+        AppendTypeAndLength(0, static_cast<uint64_t>(value), out);
+        return;
+    }
+    const int64_t signed_value = value;
+    AppendTypeAndLength(1, static_cast<uint64_t>(-1 - signed_value), out);
+}
+
+class CborVllmCodec final : public VllmValueCodec {
+   public:
+    void EncodeSeed(std::string_view seed,
+                    std::vector<uint8_t>* out) const override {
+        out->clear();
+        AppendText(seed, out);
+    }
+
+    void EncodeBlock(const VllmBlockValues& values,
+                     std::vector<uint8_t>* out) const override {
+        out->clear();
+        AppendArrayHeader(3, out);
+        AppendBytes(values.parent_digest, out);
+
+        AppendArrayHeader(values.token_ids.size(), out);
+        for (const int32_t token : values.token_ids) {
+            AppendSignedInteger(token, out);
+        }
+
+        const bool has_lora = values.lora_name != nullptr;
+        const bool has_salt = values.cache_salt != nullptr;
+        if (!has_lora && !has_salt) {
+            out->push_back(0xf6U);
+        } else {
+            AppendArrayHeader(
+                static_cast<size_t>(has_lora) + static_cast<size_t>(has_salt),
+                out);
+            if (has_lora) {
+                AppendText(*values.lora_name, out);
+            }
+            if (has_salt) {
+                AppendText(*values.cache_salt, out);
+            }
+        }
+    }
+};
+
+// ---------------------------------------------------------------------------
+// CPython Pickle protocol-5 codec (sha256)
+//
+// Restricted encoder for the value types the Conductor query contract can
+// express: UTF-8 seed strings, full parent bytes, signed int32 token IDs,
+// None, tuple containers, and LoRA/cache-salt strings.  It reproduces the
+// CPython pickler byte-for-byte for those shapes:
+//   * \x80\x05 protocol header and protocol-4+ framing (frames committed at
+//     the start of every object save once the pending frame reaches 64 KiB,
+//     and one final forced frame before/around STOP);
+//   * SHORT_BINUNICODE/BINUNICODE/BINUNICODE8 and SHORT_BINBYTES/BINBYTES/
+//     BINBYTES8 length thresholds;
+//   * BININT1/BININT2/BININT integer thresholds;
+//   * EMPTY_TUPLE/TUPLE1/TUPLE2/TUPLE3/MARK+TUPLE arity opcodes;
+//   * MEMOIZE markers after every non-empty bytes/str/tuple object;
+//   * the \x2e STOP terminator inside the final frame.
+//
+// Values are always emitted fresh (no BINGET back-references).  That matches
+// CPython whenever the memoized objects are distinct, which is the only case
+// the Conductor contract can produce; Python object-identity aliasing between
+// equal strings is an explicitly unsupported shape, as are multimodal and
+// prompt-embedding extra-key object graphs.
+// ---------------------------------------------------------------------------
+
+constexpr uint8_t kPickleMark = 0x28;             // MARK
+constexpr uint8_t kPickleStop = 0x2e;             // STOP
+constexpr uint8_t kPickleEmptyTuple = 0x29;       // EMPTY_TUPLE
+constexpr uint8_t kPickleBinbytes = 0x42;         // BINBYTES
+constexpr uint8_t kPickleShortBinbytes = 0x43;    // SHORT_BINBYTES
+constexpr uint8_t kPickleBinint = 0x4a;           // BININT
+constexpr uint8_t kPickleBinint1 = 0x4b;          // BININT1
+constexpr uint8_t kPickleBinint2 = 0x4d;          // BININT2
+constexpr uint8_t kPickleNone = 0x4e;             // NONE
+constexpr uint8_t kPickleBinunicode = 0x58;       // BINUNICODE
+constexpr uint8_t kPickleTuple = 0x74;            // TUPLE
+constexpr uint8_t kPickleProto = 0x80;            // PROTO
+constexpr uint8_t kPickleTuple1 = 0x85;           // TUPLE1
+constexpr uint8_t kPickleTuple2 = 0x86;           // TUPLE2
+constexpr uint8_t kPickleTuple3 = 0x87;           // TUPLE3
+constexpr uint8_t kPickleShortBinunicode = 0x8c;  // SHORT_BINUNICODE
+constexpr uint8_t kPickleBinunicode8 = 0x8d;      // BINUNICODE8
+constexpr uint8_t kPickleBinbytes8 = 0x8e;        // BINBYTES8
+constexpr uint8_t kPickleMemoize = 0x94;          // MEMOIZE
+constexpr uint8_t kPickleFrame = 0x95;            // FRAME
+constexpr uint8_t kPickleProtocol5 = 0x05;
+
+// CPython _Framer._FRAME_SIZE_TARGET: a pending frame is committed before the
+// next object save once it reaches this size.
+constexpr size_t kPickleFrameTarget = 64 * 1024;
+
+// Emulates CPython's protocol-4+ _Framer: object bytes accumulate in
+// frame_bytes_; Checkpoint() flushes a full frame at the start of each object
+// save, and Finish() emits the final forced frame.
+class PickleStream {
+   public:
+    // Bytes written before framing starts (the protocol header).
+    void WriteRaw(uint8_t value) { out_.push_back(value); }
+
+    void Write(uint8_t value) { frame_.push_back(value); }
+
+    void Write(std::span<const uint8_t> bytes) {
+        frame_.insert(frame_.end(), bytes.begin(), bytes.end());
+    }
+
+    // Mirrors _Framer.commit_frame() at the start of Pickler.save().
+    void Checkpoint() {
+        if (frame_.size() >= kPickleFrameTarget) {
+            FlushFrame();
+        }
+    }
+
+    // Mirrors _Framer.write_large_bytes: the current frame is force-committed
+    // and the large payload is written with its length header but without a
+    // frame opcode.  `header` is the already-packed little-endian length.
+    void WriteLargePayload(uint8_t opcode, std::span<const uint8_t> header,
+                           std::span<const uint8_t> payload) {
+        FlushFrame();
+        out_.push_back(opcode);
+        out_.insert(out_.end(), header.begin(), header.end());
+        out_.insert(out_.end(), payload.begin(), payload.end());
+    }
+
+    // Mirrors _Framer.end_framing(): force-commit whatever remains.
+    void Finish() { FlushFrame(); }
+
+    const std::vector<uint8_t>& bytes() const { return out_; }
+
+   private:
+    void FlushFrame() {
+        if (frame_.empty()) {
+            return;
+        }
+        out_.push_back(kPickleFrame);
+        AppendLittleEndian(static_cast<uint64_t>(frame_.size()), &out_);
+        out_.insert(out_.end(), frame_.begin(), frame_.end());
+        frame_.clear();
+    }
+
+    static void AppendLittleEndian(uint64_t value, std::vector<uint8_t>* out) {
+        for (int shift = 0; shift < 64; shift += 8) {
+            out->push_back(static_cast<uint8_t>(value >> shift));
+        }
+    }
+
+    std::vector<uint8_t> out_;
+    std::vector<uint8_t> frame_;
+};
+
+void PickleAppendLittleEndian(uint64_t value, size_t byte_count,
+                              std::vector<uint8_t>* out) {
+    for (size_t index = 0; index < byte_count; ++index) {
+        out->push_back(static_cast<uint8_t>(value >> (index * 8)));
+    }
+}
+
+void PickleEncodeBytes(std::span<const uint8_t> value, PickleStream* stream) {
+    const uint64_t length = value.size();
+    if (length <= 0xffU) {
+        stream->Write(kPickleShortBinbytes);
+        stream->Write(static_cast<uint8_t>(length));
+        stream->Write(value);
+    } else if (length > std::numeric_limits<uint32_t>::max()) {
+        std::vector<uint8_t> header;
+        PickleAppendLittleEndian(length, 8, &header);
+        stream->WriteLargePayload(kPickleBinbytes8, header, value);
+    } else if (length >= kPickleFrameTarget) {
+        std::vector<uint8_t> header;
+        PickleAppendLittleEndian(length, 4, &header);
+        stream->WriteLargePayload(kPickleBinbytes, header, value);
+    } else {
+        stream->Write(kPickleBinbytes);
+        for (int shift = 0; shift < 32; shift += 8) {
+            stream->Write(static_cast<uint8_t>(length >> shift));
+        }
+        stream->Write(value);
+    }
+    stream->Write(kPickleMemoize);
+}
+
+void PickleEncodeString(std::string_view value, PickleStream* stream) {
+    const auto* bytes = reinterpret_cast<const uint8_t*>(value.data());
+    const std::span<const uint8_t> encoded(bytes, value.size());
+    const uint64_t length = encoded.size();
+    if (length <= 0xffU) {
+        stream->Write(kPickleShortBinunicode);
+        stream->Write(static_cast<uint8_t>(length));
+        stream->Write(encoded);
+    } else if (length > std::numeric_limits<uint32_t>::max()) {
+        std::vector<uint8_t> header;
+        PickleAppendLittleEndian(length, 8, &header);
+        stream->WriteLargePayload(kPickleBinunicode8, header, encoded);
+    } else if (length >= kPickleFrameTarget) {
+        std::vector<uint8_t> header;
+        PickleAppendLittleEndian(length, 4, &header);
+        stream->WriteLargePayload(kPickleBinunicode, header, encoded);
+    } else {
+        stream->Write(kPickleBinunicode);
+        for (int shift = 0; shift < 32; shift += 8) {
+            stream->Write(static_cast<uint8_t>(length >> shift));
+        }
+        stream->Write(encoded);
+    }
+    stream->Write(kPickleMemoize);
+}
+
+void PickleEncodeInt(int32_t value, PickleStream* stream) {
+    if (value >= 0 && value <= 0xff) {
+        stream->Write(kPickleBinint1);
+        stream->Write(static_cast<uint8_t>(value));
+        return;
+    }
+    if (value >= 0 && value <= 0xffff) {
+        stream->Write(kPickleBinint2);
+        const uint16_t narrow = static_cast<uint16_t>(value);
+        stream->Write(static_cast<uint8_t>(narrow));
+        stream->Write(static_cast<uint8_t>(narrow >> 8));
+        return;
+    }
+    stream->Write(kPickleBinint);
+    const uint32_t bits = static_cast<uint32_t>(value);
+    for (int shift = 0; shift < 32; shift += 8) {
+        stream->Write(static_cast<uint8_t>(bits >> shift));
+    }
+}
+
+// Encodes the token tuple: per-element save checkpoints, the CPython tuple
+// arity opcodes, and the trailing MEMOIZE marker for non-empty tuples.
+void PickleEncodeTokenTuple(std::span<const int32_t> tokens,
+                            PickleStream* stream) {
+    if (tokens.empty()) {
+        stream->Write(kPickleEmptyTuple);
+        return;
+    }
+    if (tokens.size() > 3) {
+        stream->Write(kPickleMark);
+    }
+    for (const int32_t token : tokens) {
+        stream->Checkpoint();
+        PickleEncodeInt(token, stream);
+    }
+    switch (tokens.size()) {
+        case 1:
+            stream->Write(kPickleTuple1);
+            break;
+        case 2:
+            stream->Write(kPickleTuple2);
+            break;
+        case 3:
+            stream->Write(kPickleTuple3);
+            break;
+        default:
+            stream->Write(kPickleTuple);
+            break;
+    }
+    stream->Write(kPickleMemoize);
+}
+
+// Encodes the extras slot: Python None when there are no extra keys,
+// otherwise the (LoRA, salt) string tuple in vLLM's ordering.  The caller
+// must have executed the save-entry checkpoint for this value already.
+void PickleEncodeExtras(const VllmBlockValues& values, PickleStream* stream) {
+    const bool has_lora = values.lora_name != nullptr;
+    const bool has_salt = values.cache_salt != nullptr;
+    if (!has_lora && !has_salt) {
+        stream->Write(kPickleNone);
+        return;
+    }
+    if (has_lora) {
+        stream->Checkpoint();
+        PickleEncodeString(*values.lora_name, stream);
+    }
+    if (has_salt) {
+        stream->Checkpoint();
+        PickleEncodeString(*values.cache_salt, stream);
+    }
+    stream->Write(has_lora && has_salt ? kPickleTuple2 : kPickleTuple1);
+    stream->Write(kPickleMemoize);
+}
+
+class PickleVllmCodec final : public VllmValueCodec {
+   public:
+    void EncodeSeed(std::string_view seed,
+                    std::vector<uint8_t>* out) const override {
+        PickleStream stream;
+        stream.WriteRaw(kPickleProto);
+        stream.WriteRaw(kPickleProtocol5);
+        stream.Checkpoint();
+        PickleEncodeString(seed, &stream);
+        stream.Write(kPickleStop);
+        stream.Finish();
+        *out = stream.bytes();
+    }
+
+    void EncodeBlock(const VllmBlockValues& values,
+                     std::vector<uint8_t>* out) const override {
+        PickleStream stream;
+        stream.WriteRaw(kPickleProto);
+        stream.WriteRaw(kPickleProtocol5);
+
+        // Outer (parent, tokens, extras) tuple: TUPLE3.  Each Checkpoint()
+        // mirrors Pickler.save() entry for the corresponding value.
+        stream.Checkpoint();  // save((parent, tokens, extras))
+        stream.Checkpoint();  // save(parent bytes)
+        PickleEncodeBytes(values.parent_digest, &stream);
+        stream.Checkpoint();  // save(token tuple)
+        PickleEncodeTokenTuple(values.token_ids, &stream);
+        stream.Checkpoint();  // save(extras)
+        PickleEncodeExtras(values, &stream);
+        stream.Write(kPickleTuple3);
+        stream.Write(kPickleMemoize);
+
+        stream.Write(kPickleStop);
+        stream.Finish();
+        *out = stream.bytes();
+    }
+};
+
+const VllmValueCodec* CodecForAlgorithm(std::string_view algorithm) {
+    static const CborVllmCodec kCborCodec;
+    static const PickleVllmCodec kPickleCodec;
+    if (algorithm == "sha256_cbor") {
+        return &kCborCodec;
+    }
+    if (algorithm == "sha256") {
+        return &kPickleCodec;
+    }
+    return nullptr;
+}
+
+bool IsContinuationByte(uint8_t value) { return (value & 0xc0U) == 0x80U; }
+
+bool IsValidUtf8(std::string_view value) {
+    const auto* bytes = reinterpret_cast<const uint8_t*>(value.data());
+    size_t index = 0;
+    while (index < value.size()) {
+        const uint8_t first = bytes[index];
+        if (first <= 0x7fU) {
+            ++index;
+            continue;
+        }
+
+        if (first >= 0xc2U && first <= 0xdfU) {
+            if (index + 1 >= value.size() ||
+                !IsContinuationByte(bytes[index + 1])) {
+                return false;
+            }
+            index += 2;
+            continue;
+        }
+
+        if (first >= 0xe0U && first <= 0xefU) {
+            if (index + 2 >= value.size() ||
+                !IsContinuationByte(bytes[index + 1]) ||
+                !IsContinuationByte(bytes[index + 2])) {
+                return false;
+            }
+            if ((first == 0xe0U && bytes[index + 1] < 0xa0U) ||
+                (first == 0xedU && bytes[index + 1] > 0x9fU)) {
+                return false;
+            }
+            index += 3;
+            continue;
+        }
+
+        if (first >= 0xf0U && first <= 0xf4U) {
+            if (index + 3 >= value.size() ||
+                !IsContinuationByte(bytes[index + 1]) ||
+                !IsContinuationByte(bytes[index + 2]) ||
+                !IsContinuationByte(bytes[index + 3])) {
+                return false;
+            }
+            if ((first == 0xf0U && bytes[index + 1] < 0x90U) ||
+                (first == 0xf4U && bytes[index + 1] > 0x8fU)) {
+                return false;
+            }
+            index += 4;
+            continue;
+        }
+
+        return false;
+    }
+    return true;
+}
+
+#if CONDUCTOR_HAS_LOWLEVEL_SHA256
+
+std::string Sha256(std::span<const uint8_t> input,
+                   std::array<uint8_t, kSha256DigestSize>* digest) {
+    SHA256_CTX context;
+    if (SHA256_Init(&context) != 1 ||
+        SHA256_Update(&context, input.data(), input.size()) != 1 ||
+        SHA256_Final(digest->data(), &context) != 1) {
+        return "OpenSSL SHA-256 computation failed";
+    }
+    return "";
+}
+
+#else  // EVP backend: no-deprecated builds and FIPS-forced configurations.
+
+std::string Sha256(std::span<const uint8_t> input,
+                   std::array<uint8_t, kSha256DigestSize>* digest) {
+    using EvpContext = std::unique_ptr<EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>;
+    EvpContext context(EVP_MD_CTX_new(), EVP_MD_CTX_free);
+    if (!context ||
+        EVP_DigestInit_ex(context.get(), EVP_sha256(), nullptr) != 1 ||
+        EVP_DigestUpdate(context.get(), input.data(), input.size()) != 1) {
+        return "OpenSSL EVP SHA-256 initialization failed";
+    }
+
+    unsigned int digest_size = 0;
+    if (EVP_DigestFinal_ex(context.get(), digest->data(), &digest_size) != 1 ||
+        digest_size != digest->size()) {
+        return "OpenSSL EVP SHA-256 finalization failed";
+    }
+    return "";
+}
+
+// Same as Sha256 but reuses a caller-owned context across invocations,
+// avoiding an EVP_MD_CTX allocation per hashed block in long hash chains.
+std::string Sha256Reuse(EVP_MD_CTX* context, std::span<const uint8_t> input,
+                        std::array<uint8_t, kSha256DigestSize>* digest) {
+    if (EVP_MD_CTX_reset(context) != 1 ||
+        EVP_DigestInit_ex(context, EVP_sha256(), nullptr) != 1 ||
+        EVP_DigestUpdate(context, input.data(), input.size()) != 1) {
+        return "OpenSSL EVP SHA-256 initialization failed";
+    }
+
+    unsigned int digest_size = 0;
+    if (EVP_DigestFinal_ex(context, digest->data(), &digest_size) != 1 ||
+        digest_size != digest->size()) {
+        return "OpenSSL EVP SHA-256 finalization failed";
+    }
+    return "";
+}
+
+#endif
+
+int LowerHexValue(char value) {
+    if (value >= '0' && value <= '9') {
+        return value - '0';
+    }
+    if (value >= 'a' && value <= 'f') {
+        return value - 'a' + 10;
+    }
+    return -1;
+}
+
+std::string ValidateProfileSelectors(std::string_view strategy,
+                                     std::string_view algorithm,
+                                     std::string_view index_projection) {
+    if (strategy != "vllm_v1" && strategy != "sglang" &&
+        strategy != "sglang_bigram") {
+        return "unsupported hash strategy: " + std::string(strategy);
+    }
+    if (strategy == "sglang" || strategy == "sglang_bigram") {
+        if (algorithm != "sha256_raw") {
+            return "unsupported SGLang hash algorithm: " +
+                   std::string(algorithm);
+        }
+        if (index_projection != "first64_be") {
+            return "unsupported SGLang index projection: " +
+                   std::string(index_projection);
+        }
+        return "";
+    }
+    if (algorithm != "sha256" && algorithm != "sha256_cbor") {
+        return "unsupported hash algorithm: " + std::string(algorithm);
+    }
+    if (index_projection != "low64_be") {
+        return "unsupported index projection: " + std::string(index_projection);
+    }
+    return "";
+}
+
+std::string ValidatePythonHashSeed(std::string_view seed) {
+    if (!IsValidUtf8(seed)) {
+        return "python_hash_seed must contain valid UTF-8";
+    }
+    if (seed == "random") {
+        return "";
+    }
+    if (seed.empty()) {
+        return "python_hash_seed must be \"random\" or ASCII decimal text in "
+               "0..4294967295";
+    }
+
+    // Accepts only bare ASCII decimal digits: the default options reject a
+    // leading sign, surrounding whitespace, and trailing characters.  Parsing
+    // into uint64 keeps the range check separate from the well-formedness
+    // check, so a numeric seed past the uint32 ceiling reports the range
+    // error.
+    const auto value = TryParseInteger<uint64_t>(seed);
+    if (!value.has_value()) {
+        return "python_hash_seed must be \"random\" or ASCII decimal text in "
+               "0..4294967295";
+    }
+    if (*value > kMaxPythonHashSeed) {
+        return "python_hash_seed must be in range 0..4294967295";
+    }
+    return "";
+}
+
+std::string ValidateRootDigest(std::string_view root_digest) {
+    if (root_digest.size() != kSha256DigestSize * 2) {
+        return "root_digest must contain exactly 64 lowercase hex characters";
+    }
+    for (const char value : root_digest) {
+        if (LowerHexValue(value) < 0) {
+            return "root_digest must contain exactly 64 lowercase hex "
+                   "characters";
+        }
+    }
+    return "";
+}
+
+std::string ValidateResolvedHashProfileShape(const HashProfile& profile) {
+    if (auto error = ValidateProfileSelectors(
+            profile.strategy, profile.algorithm, profile.index_projection);
+        !error.empty()) {
+        return error;
+    }
+    if (profile.strategy == "vllm_v1") {
+        if (auto error = ValidatePythonHashSeed(profile.python_hash_seed);
+            !error.empty()) {
+            return error;
+        }
+    }
+    return ValidateRootDigest(profile.root_digest);
+}
+
+std::array<uint8_t, kSha256DigestSize> DecodeRootDigest(
+    std::string_view root_digest) {
+    std::array<uint8_t, kSha256DigestSize> result{};
+    for (size_t index = 0; index < result.size(); ++index) {
+        const int high = LowerHexValue(root_digest[index * 2]);
+        const int low = LowerHexValue(root_digest[index * 2 + 1]);
+        result[index] = static_cast<uint8_t>((high << 4) | low);
+    }
+    return result;
+}
+
+ProjectedPrefix ProjectDigest(
+    const std::array<uint8_t, kSha256DigestSize>& digest) {
+    uint64_t value = 0;
+    for (size_t index = digest.size() - sizeof(value); index < digest.size();
+         ++index) {
+        value = (value << 8) | digest[index];
+    }
+    return ProjectedPrefix{value};
+}
+
+// Lazily-hashed vLLM v1 block chain. Hashing is incremental: block i is
+// computed only when first requested via At(), and every block up to i is
+// cached, so prefix-index walks that stall early never hash the tail.
+class VllmV1HashChain final : public HashChain {
+   public:
+    VllmV1HashChain(const VllmValueCodec* codec,
+                    std::array<uint8_t, kSha256DigestSize> root_digest,
+                    const ContextKey& context,
+                    std::span<const int32_t> token_ids,
+                    std::optional<std::string> cache_salt)
+        : codec_(codec),
+          parent_(std::move(root_digest)),
+          lora_name_(context.lora_name),
+          cache_salt_(std::move(cache_salt)),
+          token_ids_(token_ids),
+          block_size_(static_cast<size_t>(context.block_size)),
+          block_count_(token_ids.size() / block_size_) {
+        computed_.reserve(block_count_);
+        // Reused across blocks: every codec clears the buffer at the start of
+        // EncodeBlock, so reserving worst-case capacity once keeps the whole
+        // chain on a single allocation instead of one per block.
+        encoded_.reserve(64 + block_size_ * 9);
+    }
+
+    // Validates inputs eagerly (same contract as Compute). Returns an empty
+    // string on success.
+    static std::string ValidateInputs(const ContextKey& context,
+                                      std::optional<std::string> cache_salt) {
+        if (context.block_size <= 0 ||
+            static_cast<uint64_t>(context.block_size) >
+                std::numeric_limits<size_t>::max()) {
+            return "block_size must be a positive size_t value";
+        }
+        if (!IsValidUtf8(context.lora_name)) {
+            return "lora_name must contain valid UTF-8";
+        }
+        if (cache_salt.has_value() && !IsValidUtf8(*cache_salt)) {
+            return "cache_salt must contain valid UTF-8";
+        }
+        return "";
+    }
+
+    size_t BlockCount() const override { return block_count_; }
+
+    size_t ComputedCount() const override { return computed_.size(); }
+
+    const HashBlock* At(size_t index, std::string* error) override {
+        if (index >= block_count_) {
+            if (error != nullptr) {
+                *error = "hash chain index out of range";
+            }
+            return nullptr;
+        }
+        if (!sticky_error_.empty()) {
+            if (error != nullptr) {
+                *error = sticky_error_;
+            }
+            return nullptr;
+        }
+#if !CONDUCTOR_HAS_LOWLEVEL_SHA256
+        if (!EnsureEvp()) {
+            if (error != nullptr) {
+                *error = sticky_error_;
+            }
+            return nullptr;
+        }
+#endif
+        while (computed_.size() <= index) {
+            const size_t block_index = computed_.size();
+            const bool has_lora = !lora_name_.empty();
+            const bool has_salt = block_index == 0 && cache_salt_.has_value() &&
+                                  !cache_salt_->empty();
+            const VllmBlockValues values{
+                .parent_digest = parent_,
+                .token_ids =
+                    token_ids_.subspan(block_index * block_size_, block_size_),
+                .lora_name = has_lora ? &lora_name_ : nullptr,
+                .cache_salt = has_salt ? &*cache_salt_ : nullptr,
+            };
+
+            codec_->EncodeBlock(values, &encoded_);
+
+            HashBlock block;
+#if CONDUCTOR_HAS_LOWLEVEL_SHA256
+            std::string hash_error = Sha256(encoded_, &block.digest);
+#else
+            std::string hash_error =
+                Sha256Reuse(evp_.get(), encoded_, &block.digest);
+#endif
+            if (!hash_error.empty()) {
+                sticky_error_ = std::move(hash_error);
+                if (error != nullptr) {
+                    *error = sticky_error_;
+                }
+                return nullptr;
+            }
+            block.projected = ProjectDigest(block.digest);
+            parent_ = block.digest;
+            computed_.push_back(std::move(block));
+        }
+        return &computed_[index];
+    }
+
+   private:
+#if !CONDUCTOR_HAS_LOWLEVEL_SHA256
+    bool EnsureEvp() {
+        if (evp_) {
+            return true;
+        }
+        evp_ = EvpContext(EVP_MD_CTX_new(), EVP_MD_CTX_free);
+        if (!evp_) {
+            sticky_error_ = "OpenSSL EVP MD context allocation failed";
+            return false;
+        }
+        return true;
+    }
+
+    using EvpContext = std::unique_ptr<EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>;
+#endif
+
+    const VllmValueCodec* codec_;
+    std::array<uint8_t, kSha256DigestSize> parent_;
+    std::string lora_name_;
+    std::optional<std::string> cache_salt_;
+    std::span<const int32_t> token_ids_;
+    size_t block_size_;
+    size_t block_count_;
+    std::vector<HashBlock> computed_;
+    std::vector<uint8_t> encoded_;
+#if !CONDUCTOR_HAS_LOWLEVEL_SHA256
+    EvpContext evp_{nullptr, EVP_MD_CTX_free};
+#endif
+    std::string sticky_error_;
+};
+
+class VllmV1HashStrategy final : public HashStrategy {
+   public:
+    VllmV1HashStrategy(const VllmValueCodec* codec,
+                       std::array<uint8_t, kSha256DigestSize> root_digest)
+        : codec_(codec), root_digest_(std::move(root_digest)) {}
+
+    std::string Compute(const ContextKey& context,
+                        std::span<const int32_t> token_ids,
+                        std::optional<std::string> cache_salt,
+                        std::vector<HashBlock>* out) const override {
+        if (out == nullptr) {
+            return "hash output must not be null";
+        }
+        out->clear();
+
+        std::string error;
+        auto chain =
+            CreateChain(context, token_ids, std::move(cache_salt), &error);
+        if (!chain) {
+            return error;
+        }
+        std::vector<HashBlock> computed;
+        computed.reserve(chain->BlockCount());
+        for (size_t index = 0; index < chain->BlockCount(); ++index) {
+            const HashBlock* block = chain->At(index, &error);
+            if (block == nullptr) {
+                return error;
+            }
+            computed.push_back(*block);
+        }
+
+        *out = std::move(computed);
+        return "";
+    }
+
+    std::unique_ptr<HashChain> CreateChain(
+        const ContextKey& context, std::span<const int32_t> token_ids,
+        std::optional<std::string> cache_salt,
+        std::string* error) const override {
+        if (std::string validation_error =
+                VllmV1HashChain::ValidateInputs(context, cache_salt);
+            !validation_error.empty()) {
+            if (error != nullptr) {
+                *error = std::move(validation_error);
+            }
+            return nullptr;
+        }
+        return std::make_unique<VllmV1HashChain>(
+            codec_, root_digest_, context, token_ids, std::move(cache_salt));
+    }
+
+   private:
+    const VllmValueCodec* codec_;
+    std::array<uint8_t, kSha256DigestSize> root_digest_;
+};
+
+ProjectedPrefix ProjectSglangDigest(
+    const std::array<uint8_t, kSha256DigestSize>& digest) {
+    uint64_t value = 0;
+    for (size_t index = 0; index < sizeof(value); ++index) {
+        value = (value << 8) | digest[index];
+    }
+    return ProjectedPrefix{value};
+}
+
+class SglangHashChain final : public HashChain {
+   public:
+    SglangHashChain(const ContextKey& context,
+                    std::span<const int32_t> token_ids,
+                    std::optional<std::string> cache_salt, bool bigram)
+        : token_ids_(token_ids),
+          block_size_(static_cast<size_t>(context.block_size)),
+          block_count_(
+              bigram ? (token_ids.size() < 2
+                            ? 0
+                            : (token_ids.size() - 1) / block_size_ +
+                                  ((token_ids.size() - 1) % block_size_ != 0))
+                     : token_ids.size() / block_size_ +
+                           (token_ids.size() % block_size_ != 0)),
+          bigram_(bigram),
+          cache_salt_(std::move(cache_salt)) {
+        computed_.reserve(block_count_);
+        encoded_.reserve(block_size_ * sizeof(uint32_t) * (bigram ? 2 : 1));
+        if (cache_salt_.has_value()) {
+            std::vector<uint8_t> root_input;
+            constexpr std::string_view kSaltPrefix("sglang-cache-salt-v1\0",
+                                                   21);
+            root_input.insert(root_input.end(), kSaltPrefix.begin(),
+                              kSaltPrefix.end());
+            root_input.insert(root_input.end(), cache_salt_->begin(),
+                              cache_salt_->end());
+            if (std::string error = Sha256(root_input, &parent_);
+                !error.empty()) {
+                sticky_error_ = std::move(error);
+            } else {
+                has_parent_ = true;
+            }
+        }
+    }
+
+    static std::string ValidateInputs(const ContextKey& context,
+                                      std::optional<std::string> cache_salt,
+                                      std::span<const int32_t> token_ids) {
+        if (context.block_size <= 0 ||
+            static_cast<uint64_t>(context.block_size) >
+                std::numeric_limits<size_t>::max()) {
+            return "block_size must be a positive size_t value";
+        }
+        if (cache_salt.has_value() && !IsValidUtf8(*cache_salt)) {
+            return "cache_salt must contain valid UTF-8";
+        }
+        for (int32_t token : token_ids) {
+            if (token < 0) {
+                return "SGLang token_ids must be non-negative";
+            }
+        }
+        return "";
+    }
+
+    size_t BlockCount() const override { return block_count_; }
+    size_t ComputedCount() const override { return computed_.size(); }
+
+    const HashBlock* At(size_t index, std::string* error) override {
+        if (index >= block_count_) {
+            if (error != nullptr) *error = "hash chain index out of range";
+            return nullptr;
+        }
+        if (!sticky_error_.empty()) {
+            if (error != nullptr) *error = sticky_error_;
+            return nullptr;
+        }
+        while (computed_.size() <= index) {
+            const size_t block_index = computed_.size();
+            encoded_.clear();
+            const size_t logical_length =
+                bigram_ ? token_ids_.size() - 1 : token_ids_.size();
+            const size_t block_begin = block_index * block_size_;
+            const size_t block_end =
+                std::min(block_begin + block_size_, logical_length);
+            for (size_t token_index = block_begin; token_index < block_end;
+                 ++token_index) {
+                const int32_t token = token_ids_[token_index];
+                const uint32_t value = static_cast<uint32_t>(token);
+                encoded_.push_back(static_cast<uint8_t>(value));
+                encoded_.push_back(static_cast<uint8_t>(value >> 8));
+                encoded_.push_back(static_cast<uint8_t>(value >> 16));
+                encoded_.push_back(static_cast<uint8_t>(value >> 24));
+                if (bigram_) {
+                    const uint32_t next_value =
+                        static_cast<uint32_t>(token_ids_[token_index + 1]);
+                    encoded_.push_back(static_cast<uint8_t>(next_value));
+                    encoded_.push_back(static_cast<uint8_t>(next_value >> 8));
+                    encoded_.push_back(static_cast<uint8_t>(next_value >> 16));
+                    encoded_.push_back(static_cast<uint8_t>(next_value >> 24));
+                }
+            }
+            std::vector<uint8_t> input;
+            input.reserve((has_parent_ ? parent_.size() : 0) + encoded_.size());
+            if (has_parent_) {
+                input.insert(input.end(), parent_.begin(), parent_.end());
+            }
+            input.insert(input.end(), encoded_.begin(), encoded_.end());
+
+            HashBlock hashed;
+            if (std::string hash_error = Sha256(input, &hashed.digest);
+                !hash_error.empty()) {
+                sticky_error_ = std::move(hash_error);
+                if (error != nullptr) *error = sticky_error_;
+                return nullptr;
+            }
+            hashed.projected = ProjectSglangDigest(hashed.digest);
+            parent_ = hashed.digest;
+            has_parent_ = true;
+            computed_.push_back(std::move(hashed));
+        }
+        return &computed_[index];
+    }
+
+   private:
+    std::span<const int32_t> token_ids_;
+    size_t block_size_;
+    size_t block_count_;
+    bool bigram_;
+    std::optional<std::string> cache_salt_;
+    std::array<uint8_t, kSha256DigestSize> parent_{};
+    bool has_parent_ = false;
+    std::vector<HashBlock> computed_;
+    std::vector<uint8_t> encoded_;
+    std::string sticky_error_;
+};
+
+class SglangHashStrategy final : public HashStrategy {
+   public:
+    explicit SglangHashStrategy(bool bigram) : bigram_(bigram) {}
+
+    std::string Compute(const ContextKey& context,
+                        std::span<const int32_t> token_ids,
+                        std::optional<std::string> cache_salt,
+                        std::vector<HashBlock>* out) const override {
+        if (out == nullptr) return "hash output must not be null";
+        out->clear();
+        std::string error;
+        auto chain =
+            CreateChain(context, token_ids, std::move(cache_salt), &error);
+        if (!chain) return error;
+        out->reserve(chain->BlockCount());
+        for (size_t index = 0; index < chain->BlockCount(); ++index) {
+            const auto* block = chain->At(index, &error);
+            if (block == nullptr) return error;
+            out->push_back(*block);
+        }
+        return "";
+    }
+
+    std::unique_ptr<HashChain> CreateChain(
+        const ContextKey& context, std::span<const int32_t> token_ids,
+        std::optional<std::string> cache_salt,
+        std::string* error) const override {
+        if (std::string validation =
+                SglangHashChain::ValidateInputs(context, cache_salt, token_ids);
+            !validation.empty()) {
+            if (error != nullptr) *error = std::move(validation);
+            return nullptr;
+        }
+        return std::make_unique<SglangHashChain>(
+            context, token_ids, std::move(cache_salt), bigram_);
+    }
+
+   private:
+    bool bigram_ = false;
+};
+
+}  // namespace
+
+std::string ResolveHashProfile(const common::HashProfileConfig& config,
+                               HashProfile* out) {
+    if (out == nullptr) {
+        return "resolved hash profile output must not be null";
+    }
+    *out = {};
+
+    if (auto error = ValidateProfileSelectors(config.strategy, config.algorithm,
+                                              config.index_projection);
+        !error.empty()) {
+        return error;
+    }
+    if (config.strategy == "sglang" || config.strategy == "sglang_bigram") {
+        // SGLang has no process-level Python seed/root in its token hash
+        // chain.  Keep a deterministic sentinel for the existing profile
+        // registration wire contract; cache_salt, when present, supplies the
+        // actual chain root at query time.
+        *out = {.strategy = config.strategy,
+                .algorithm = config.algorithm,
+                .python_hash_seed = config.python_hash_seed,
+                .root_digest = std::string(64, '0'),
+                .index_projection = config.index_projection};
+        return "";
+    }
+
+    if (auto error = ValidatePythonHashSeed(config.python_hash_seed);
+        !error.empty()) {
+        return error;
+    }
+
+    const VllmValueCodec* codec = CodecForAlgorithm(config.algorithm);
+    if (codec == nullptr) {
+        return "unsupported hash algorithm: " + config.algorithm;
+    }
+
+    std::vector<uint8_t> encoded_seed;
+    codec->EncodeSeed(config.python_hash_seed, &encoded_seed);
+    std::array<uint8_t, kSha256DigestSize> root_digest{};
+    if (auto error = Sha256(encoded_seed, &root_digest); !error.empty()) {
+        return error;
+    }
+
+    *out = {.strategy = config.strategy,
+            .algorithm = config.algorithm,
+            .python_hash_seed = config.python_hash_seed,
+            .root_digest = DigestToHex(root_digest),
+            .index_projection = config.index_projection};
+    return "";
+}
+
+std::string ValidateHashProfile(const HashProfile& profile) {
+    if (auto error = ValidateResolvedHashProfileShape(profile);
+        !error.empty()) {
+        return error;
+    }
+
+    HashProfile expected;
+    const common::HashProfileConfig source{
+        .strategy = profile.strategy,
+        .algorithm = profile.algorithm,
+        .python_hash_seed = profile.python_hash_seed,
+        .index_projection = profile.index_projection,
+    };
+    if (auto error = ResolveHashProfile(source, &expected); !error.empty()) {
+        return error;
+    }
+    if (profile.root_digest != expected.root_digest) {
+        return "root_digest does not match python_hash_seed and hash selectors";
+    }
+    return "";
+}
+
+std::unique_ptr<HashStrategy> CreateHashStrategy(const HashProfile& profile,
+                                                 std::string* error) {
+    const std::string validation_error =
+        ValidateResolvedHashProfileShape(profile);
+    if (error != nullptr) {
+        *error = validation_error;
+    }
+    if (!validation_error.empty()) {
+        return nullptr;
+    }
+    if (profile.strategy == "sglang" || profile.strategy == "sglang_bigram") {
+        return std::make_unique<SglangHashStrategy>(profile.strategy ==
+                                                    "sglang_bigram");
+    }
+    const VllmValueCodec* codec = CodecForAlgorithm(profile.algorithm);
+    if (codec == nullptr) {
+        if (error != nullptr) {
+            *error = "unsupported hash algorithm: " + profile.algorithm;
+        }
+        return nullptr;
+    }
+    return std::make_unique<VllmV1HashStrategy>(
+        codec, DecodeRootDigest(profile.root_digest));
+}
+
+std::string DigestToHex(const std::array<uint8_t, 32>& digest) {
+    static constexpr char kHexDigits[] = "0123456789abcdef";
+    std::string result;
+    result.resize(digest.size() * 2);
+    for (size_t index = 0; index < digest.size(); ++index) {
+        result[index * 2] = kHexDigits[digest[index] >> 4];
+        result[index * 2 + 1] = kHexDigits[digest[index] & 0x0fU];
+    }
+    return result;
+}
+
+}  // namespace mooncake::conductor::prefixindex
diff --git a/mooncake-conductor/src/prefixindex/prefix_indexer.cpp b/mooncake-conductor/src/prefixindex/prefix_indexer.cpp
new file mode 100644
index 0000000000..2a3b914a65
--- /dev/null
+++ b/mooncake-conductor/src/prefixindex/prefix_indexer.cpp
@@ -0,0 +1,641 @@
+#include "conductor/prefixindex/prefix_indexer.h"
+
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <limits>
+#include <mutex>
+#include <utility>
+
+#include "conductor/prefixindex/hash_strategy.h"
+
+namespace mooncake::conductor::prefixindex {
+
+namespace {
+
+std::string ValidateContext(const ContextKey& context) {
+    if (context.tenant_id.empty()) {
+        return "tenant_id is required";
+    }
+    if (context.model_name.empty()) {
+        return "model_name is required";
+    }
+    if (context.block_size <= 0) {
+        return "block_size must be positive";
+    }
+    return "";
+}
+
+std::string ValidateLayout(const ContextKey& context,
+                           int64_t effective_block_size,
+                           std::optional<int64_t> cache_group) {
+    if (auto error = ValidateContext(context); !error.empty()) {
+        return error;
+    }
+    if (effective_block_size <= 0) {
+        return "effective_block_size must be positive";
+    }
+    if (effective_block_size != context.block_size) {
+        return "effective_block_size must equal ContextKey block_size";
+    }
+    if (cache_group.has_value() && *cache_group != 0) {
+        return "only cache group 0 is supported";
+    }
+    return "";
+}
+
+std::string ValidateEngineOwner(const EngineOwner& owner) {
+    if (owner.source_stream.empty()) {
+        return "engine owner source_stream is required";
+    }
+    if (owner.instance_id.empty()) {
+        return "engine owner instance_id is required";
+    }
+    if (owner.dp_rank < 0) {
+        return "engine owner dp_rank must be non-negative";
+    }
+    return "";
+}
+
+std::string ValidateSharedOwner(const SharedObjectOwner& owner) {
+    if (owner.source_stream.empty()) {
+        return "shared owner source_stream is required";
+    }
+    if (owner.backend_id.empty()) {
+        return "shared owner backend_id is required";
+    }
+    if (owner.object_id.empty()) {
+        return "shared owner object_id is required";
+    }
+    return "";
+}
+
+std::string ValidateGpuMutation(const GpuMutation& mutation) {
+    if (auto error =
+            ValidateLayout(mutation.context, mutation.effective_block_size,
+                           mutation.cache_group);
+        !error.empty()) {
+        return error;
+    }
+    return ValidateEngineOwner(mutation.owner);
+}
+
+std::string ValidateGpuClear(const GpuClear& clear) {
+    if (auto error = ValidateLayout(clear.context, clear.effective_block_size,
+                                    clear.cache_group);
+        !error.empty()) {
+        return error;
+    }
+    return ValidateEngineOwner(clear.owner);
+}
+
+bool IsSharedTier(StorageTier tier) {
+    return tier == StorageTier::kCpu || tier == StorageTier::kDisk;
+}
+
+std::string ValidateSharedMutation(const SharedMutation& mutation) {
+    if (auto error =
+            ValidateLayout(mutation.context, mutation.effective_block_size,
+                           mutation.cache_group);
+        !error.empty()) {
+        return error;
+    }
+    if (!IsSharedTier(mutation.tier)) {
+        return "shared mutation tier must be CPU or DISK";
+    }
+    return ValidateSharedOwner(mutation.owner);
+}
+
+std::string ValidateSharedClear(const SharedClear& clear) {
+    if (auto error = ValidateLayout(clear.context, clear.effective_block_size,
+                                    clear.cache_group);
+        !error.empty()) {
+        return error;
+    }
+    if (clear.tier.has_value() && !IsSharedTier(*clear.tier)) {
+        return "shared clear tier must be CPU, DISK, or omitted";
+    }
+    return ValidateSharedOwner(clear.owner);
+}
+
+std::set<SharedObjectOwner>& SharedOwners(BlockPresence& presence,
+                                          StorageTier tier) {
+    return tier == StorageTier::kCpu ? presence.cpu_owners
+                                     : presence.disk_owners;
+}
+
+// Remove empty blocks and their order metadata. The caller holds state.mutex.
+void EraseEmptyBlocks(ContextState& state) {
+    std::erase_if(state.blocks, [&state](const auto& item) {
+        if (!item.second.Empty()) {
+            return false;
+        }
+        auto pos = state.order_pos.find(item.first);
+        if (pos != state.order_pos.end()) {
+            state.write_order.erase(pos->second);
+            state.order_pos.erase(pos);
+        }
+        return true;
+    });
+}
+
+// Remove a prefix from the insertion-order metadata. The caller holds
+// state.mutex.
+void ForgetOrder(ContextState& state, ProjectedPrefix prefix) {
+    auto pos = state.order_pos.find(prefix);
+    if (pos != state.order_pos.end()) {
+        state.write_order.erase(pos->second);
+        state.order_pos.erase(pos);
+    }
+}
+
+// Move a prefix to the front of the insertion-order list, adding it if absent.
+// The caller holds the state write lock.
+void TouchOrder(ContextState& state, ProjectedPrefix prefix) {
+    auto pos = state.order_pos.find(prefix);
+    if (pos != state.order_pos.end()) {
+        state.write_order.splice(state.write_order.begin(), state.write_order,
+                                 pos->second);
+        return;
+    }
+    state.write_order.push_front(prefix);
+    state.order_pos.emplace(prefix, state.write_order.begin());
+}
+
+// Evict oldest entries in batches until the target occupancy is reached. The
+// caller holds the state write lock.
+void EvictIfOverCapacity(ContextState& state) {
+    if (state.max_blocks == 0 || state.blocks.size() <= state.max_blocks) {
+        return;
+    }
+    const size_t target =
+        static_cast<size_t>(state.max_blocks * kEvictTargetRatio);
+    while (state.blocks.size() > target && !state.write_order.empty()) {
+        const ProjectedPrefix oldest = state.write_order.back();
+        state.write_order.pop_back();
+        state.order_pos.erase(oldest);
+        state.blocks.erase(oldest);
+        ++state.evicted_by_capacity;
+    }
+    LOG_EVERY_N(WARNING, 100)
+        << "Prefix index hit the capacity limit; oldest entries dropped."
+        << " limit=" << state.max_blocks << " now=" << state.blocks.size()
+        << " cumulative_evicted=" << state.evicted_by_capacity
+        << " (non-zero means stored/removed events are out of sync)";
+}
+
+int64_t TokensForBlocks(size_t block_count, int64_t block_size) {
+    const uint64_t max_blocks =
+        static_cast<uint64_t>(std::numeric_limits<int64_t>::max() / block_size);
+    if (block_count > max_blocks) {
+        return std::numeric_limits<int64_t>::max();
+    }
+    return static_cast<int64_t>(block_count) * block_size;
+}
+
+// Tokens reusable from a matched run of blocks. The SGLang chains end in a
+// partial block, so a run that reaches the last block covers only the tokens
+// the query actually carries. Reporting a whole block there would hand the
+// router reusable tokens that no indexed block holds, and the engine would
+// then skip recomputing slots whose KV belongs to some other request.
+int64_t MatchedTokens(size_t block_count, int64_t block_size,
+                      size_t queried_tokens) {
+    const int64_t queried =
+        queried_tokens >
+                static_cast<size_t>(std::numeric_limits<int64_t>::max())
+            ? std::numeric_limits<int64_t>::max()
+            : static_cast<int64_t>(queried_tokens);
+    return std::min(TokensForBlocks(block_count, block_size), queried);
+}
+
+}  // namespace
+
+RegistrationResult PrefixCacheTable::ValidateRegistration(
+    const EngineRegistration& registration) {
+    if (auto error = ValidateLayout(registration.context,
+                                    registration.effective_block_size,
+                                    registration.cache_group);
+        !error.empty()) {
+        return {.error = std::move(error)};
+    }
+    if (registration.instance_id.empty()) {
+        return {.error = "instance_id is required"};
+    }
+    if (registration.dp_rank < 0) {
+        return {.error = "dp_rank must be non-negative"};
+    }
+    if (auto error = ValidateHashProfile(registration.profile);
+        !error.empty()) {
+        return {.error = std::move(error)};
+    }
+    return {};
+}
+
+RegistrationResult PrefixCacheTable::Register(
+    const EngineRegistration& registration) {
+    if (auto validation = ValidateRegistration(registration);
+        !validation.error.empty()) {
+        return validation;
+    }
+
+    auto candidate =
+        std::make_shared<ContextState>(registration.profile, block_limit_);
+    candidate->instance_ranks[registration.instance_id].insert(
+        registration.dp_rank);
+
+    std::shared_ptr<ContextState> state;
+    {
+        std::unique_lock map_lock(context_map_mutex_);
+        auto [it, inserted] =
+            contexts_.try_emplace(registration.context, std::move(candidate));
+        if (inserted) {
+            return {.inserted = true, .error = ""};
+        }
+        state = it->second;
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    if (state->profile != registration.profile) {
+        return {.error =
+                    "registration conflicts with the ContextKey hash profile"};
+    }
+    const bool inserted = state->instance_ranks[registration.instance_id]
+                              .insert(registration.dp_rank)
+                              .second;
+    return {.inserted = inserted, .error = ""};
+}
+
+std::shared_ptr<ContextState> PrefixCacheTable::LoadContextState(
+    const ContextKey& context) const {
+    std::shared_lock map_lock(context_map_mutex_);
+    auto it = contexts_.find(context);
+    return it == contexts_.end() ? nullptr : it->second;
+}
+
+std::string PrefixCacheTable::ValidateProfileBinding(
+    const ContextKey& context, const HashProfile& profile) const {
+    if (auto error = ValidateContext(context); !error.empty()) {
+        return error;
+    }
+    if (auto error = ValidateHashProfile(profile); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(context);
+    if (!state) {
+        return "ContextKey is not registered";
+    }
+
+    std::shared_lock state_lock(state->mutex);
+    if (state->profile != profile) {
+        return "hash profile conflicts with the registered ContextKey profile";
+    }
+    return "";
+}
+
+std::string PrefixCacheTable::Unregister(const ContextKey& context,
+                                         const std::string& instance_id,
+                                         int64_t dp_rank) {
+    if (auto error = ValidateContext(context); !error.empty()) {
+        return error;
+    }
+    if (instance_id.empty()) {
+        return "instance_id is required";
+    }
+    if (dp_rank < 0) {
+        return "dp_rank must be non-negative";
+    }
+
+    auto state = LoadContextState(context);
+    if (!state) {
+        return "";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    auto instance = state->instance_ranks.find(instance_id);
+    if (instance != state->instance_ranks.end()) {
+        instance->second.erase(dp_rank);
+        if (instance->second.empty()) {
+            state->instance_ranks.erase(instance);
+        }
+    }
+
+    for (auto& [unused_prefix, presence] : state->blocks) {
+        (void)unused_prefix;
+        std::erase_if(presence.gpu_owners, [&](const EngineOwner& owner) {
+            return owner.instance_id == instance_id && owner.dp_rank == dp_rank;
+        });
+    }
+    EraseEmptyBlocks(*state);
+    return "";
+}
+
+std::string PrefixCacheTable::StoreGpu(const GpuMutation& mutation) {
+    if (auto error = ValidateGpuMutation(mutation); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(mutation.context);
+    if (!state) {
+        return "ContextKey is not registered";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    auto instance = state->instance_ranks.find(mutation.owner.instance_id);
+    if (instance == state->instance_ranks.end() ||
+        !instance->second.contains(mutation.owner.dp_rank)) {
+        return "engine owner instance/rank is not registered";
+    }
+    for (ProjectedPrefix prefix : mutation.prefixes) {
+        state->blocks[prefix].gpu_owners.insert(mutation.owner);
+        TouchOrder(*state, prefix);
+    }
+    EvictIfOverCapacity(*state);
+    return "";
+}
+
+std::string PrefixCacheTable::RemoveGpu(const GpuMutation& mutation) {
+    if (auto error = ValidateGpuMutation(mutation); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(mutation.context);
+    if (!state) {
+        return "";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    // Only prefixes in the mutation can become empty, so avoid a full scan.
+    for (ProjectedPrefix prefix : mutation.prefixes) {
+        auto block = state->blocks.find(prefix);
+        if (block != state->blocks.end()) {
+            block->second.gpu_owners.erase(mutation.owner);
+            if (block->second.Empty()) {
+                state->blocks.erase(block);
+                ForgetOrder(*state, prefix);
+            }
+        }
+    }
+    return "";
+}
+
+std::string PrefixCacheTable::ClearGpu(const GpuClear& clear) {
+    if (auto error = ValidateGpuClear(clear); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(clear.context);
+    if (!state) {
+        return "";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    for (auto& [unused_prefix, presence] : state->blocks) {
+        (void)unused_prefix;
+        presence.gpu_owners.erase(clear.owner);
+    }
+    EraseEmptyBlocks(*state);
+    return "";
+}
+
+std::string PrefixCacheTable::StoreShared(const SharedMutation& mutation) {
+    if (auto error = ValidateSharedMutation(mutation); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(mutation.context);
+    if (!state) {
+        return "ContextKey is not registered";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    for (ProjectedPrefix prefix : mutation.prefixes) {
+        SharedOwners(state->blocks[prefix], mutation.tier)
+            .insert(mutation.owner);
+        TouchOrder(*state, prefix);
+    }
+    EvictIfOverCapacity(*state);
+    return "";
+}
+
+std::string PrefixCacheTable::RemoveShared(const SharedMutation& mutation) {
+    if (auto error = ValidateSharedMutation(mutation); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(mutation.context);
+    if (!state) {
+        return "";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    // Only prefixes in the mutation can become empty, so avoid a full scan.
+    for (ProjectedPrefix prefix : mutation.prefixes) {
+        auto block = state->blocks.find(prefix);
+        if (block != state->blocks.end()) {
+            SharedOwners(block->second, mutation.tier).erase(mutation.owner);
+            if (block->second.Empty()) {
+                state->blocks.erase(block);
+                ForgetOrder(*state, prefix);
+            }
+        }
+    }
+    return "";
+}
+
+std::string PrefixCacheTable::ClearShared(const SharedClear& clear) {
+    if (auto error = ValidateSharedClear(clear); !error.empty()) {
+        return error;
+    }
+    auto state = LoadContextState(clear.context);
+    if (!state) {
+        return "";
+    }
+
+    std::unique_lock state_lock(state->mutex);
+    for (auto& [unused_prefix, presence] : state->blocks) {
+        (void)unused_prefix;
+        if (!clear.tier.has_value() || *clear.tier == StorageTier::kCpu) {
+            presence.cpu_owners.erase(clear.owner);
+        }
+        if (!clear.tier.has_value() || *clear.tier == StorageTier::kDisk) {
+            presence.disk_owners.erase(clear.owner);
+        }
+    }
+    EraseEmptyBlocks(*state);
+    return "";
+}
+
+std::map<std::string, CacheHitResult> PrefixCacheTable::Query(
+    const ContextKey& context, std::span<const int32_t> token_ids,
+    std::optional<std::string> cache_salt,
+    std::optional<std::string> instance_filter) const {
+    std::map<std::string, CacheHitResult> results;
+    auto state = LoadContextState(context);
+    if (!state) {
+        return results;
+    }
+
+    // The profile is immutable, and the shared_ptr keeps state alive while the
+    // hash strategy and chain are built without holding state.mutex.
+    std::string strategy_error;
+    auto strategy = CreateHashStrategy(state->profile, &strategy_error);
+    if (!strategy) {
+        LOG(ERROR) << "Registered hash profile became invalid: "
+                   << strategy_error;
+        return results;
+    }
+
+    std::string chain_error;
+    auto chain = strategy->CreateChain(context, token_ids,
+                                       std::move(cache_salt), &chain_error);
+    if (!chain) {
+        LOG(ERROR) << "Query hash chain setup failed: " << chain_error;
+        return results;
+    }
+    const size_t block_count = chain->BlockCount();
+    // Reusable logical KV positions carried by this query. The bigram chains
+    // hash token pairs, so n raw tokens cover n - 1 positions and the chain is
+    // built over that length. Capping at the raw count there would still let a
+    // full match report one position no indexed block holds.
+    const size_t queried_tokens =
+        (state->profile.strategy == "sglang_bigram" && !token_ids.empty())
+            ? token_ids.size() - 1
+            : token_ids.size();
+
+    // Resolve the optional filter and copy rank sets before probing. The copies
+    // remain valid while the probe releases and reacquires state.mutex.
+    std::map<std::string, std::set<int64_t>> selected_instances;
+    {
+        std::shared_lock select_lock(state->mutex);
+        if (instance_filter.has_value()) {
+            auto instance = state->instance_ranks.find(*instance_filter);
+            if (instance == state->instance_ranks.end()) {
+                return results;
+            }
+            selected_instances.emplace(instance->first, instance->second);
+        } else {
+            selected_instances = state->instance_ranks;
+        }
+    }
+    if (selected_instances.empty()) {
+        return results;
+    }
+
+    // Probe indexed block presence in chunks. Hashing runs outside the lock;
+    // each chunk holds a shared lock only for table lookups.
+    constexpr size_t kProbeChunkMin = 8;
+    constexpr size_t kProbeChunkMax = 512;
+    size_t chunk = kProbeChunkMin;
+    size_t probe_depth = 0;
+    bool probe_stalled = false;
+    while (!probe_stalled && probe_depth < block_count) {
+        const size_t chunk_end = std::min(probe_depth + chunk, block_count);
+        chunk = std::min(chunk * 2, kProbeChunkMax);
+        // Compute hashes without holding state.mutex; retain any error for the
+        // final check below.
+        for (size_t i = probe_depth; i < chunk_end; ++i) {
+            if (chain->At(i, &chain_error) == nullptr) {
+                probe_stalled = true;
+                break;
+            }
+        }
+        std::shared_lock probe_lock(state->mutex);
+        while (probe_depth < chunk_end) {
+            const HashBlock* hashed = chain->At(probe_depth, &chain_error);
+            if (hashed == nullptr ||
+                !state->blocks.contains(hashed->projected)) {
+                probe_stalled = true;
+                break;
+            }
+            ++probe_depth;
+        }
+    }
+
+    std::shared_lock state_lock(state->mutex);
+
+    // Hashes needed by the probe are memoized, so the final read-locked walk
+    // performs only vector access and indexed lookups.
+    auto advance_cursor = [&](size_t& cursor, const auto& present) {
+        while (cursor < block_count) {
+            const HashBlock* hashed = chain->At(cursor, &chain_error);
+            if (hashed == nullptr) {
+                cursor = block_count;  // stall every remaining walk
+                return;
+            }
+            auto block = state->blocks.find(hashed->projected);
+            if (block == state->blocks.end() || !present(block->second)) {
+                break;
+            }
+            ++cursor;
+        }
+    };
+
+    for (const auto& [instance_id, ranks] : selected_instances) {
+        CacheHitResult result;
+
+        for (int64_t rank : ranks) {
+            auto gpu_present = [&](const BlockPresence& block) {
+                return std::any_of(
+                    block.gpu_owners.begin(), block.gpu_owners.end(),
+                    [&](const EngineOwner& owner) {
+                        return owner.instance_id == instance_id &&
+                               owner.dp_rank == rank;
+                    });
+            };
+
+            size_t cursor = 0;
+            advance_cursor(cursor, gpu_present);
+
+            RankCacheHitResult rank_match;
+            rank_match.gpu =
+                MatchedTokens(cursor, context.block_size, queried_tokens);
+
+            advance_cursor(cursor, [](const BlockPresence& block) {
+                return !block.cpu_owners.empty();
+            });
+            rank_match.cpu =
+                MatchedTokens(cursor, context.block_size, queried_tokens);
+
+            advance_cursor(cursor, [](const BlockPresence& block) {
+                return !block.disk_owners.empty();
+            });
+            rank_match.disk =
+                MatchedTokens(cursor, context.block_size, queried_tokens);
+
+            result.dp.emplace(rank, rank_match.gpu);
+            result.rank_matches.emplace(rank, rank_match);
+            result.gpu = std::max(result.gpu, rank_match.gpu);
+            result.cpu = std::max(result.cpu, rank_match.cpu);
+            result.disk = std::max(result.disk, rank_match.disk);
+        }
+        result.longest_match_tokens = result.disk;
+        results.emplace(instance_id, std::move(result));
+    }
+    if (!chain_error.empty()) {
+        LOG(ERROR) << "Query hash computation failed: " << chain_error;
+        return {};
+    }
+    return results;
+}
+
+GlobalView PrefixCacheTable::GetGlobalView() const {
+    GlobalView view;
+    std::vector<std::pair<ContextKey, std::shared_ptr<ContextState>>> contexts;
+    {
+        std::shared_lock map_lock(context_map_mutex_);
+        contexts.reserve(contexts_.size());
+        for (const auto& item : contexts_) {
+            contexts.push_back(item);
+        }
+    }
+
+    view.context_count = static_cast<int32_t>(contexts.size());
+    view.contexts.reserve(contexts.size());
+    for (const auto& [context, state] : contexts) {
+        std::shared_lock state_lock(state->mutex);
+        ContextView context_view;
+        context_view.context = context;
+        context_view.profile = state->profile;
+        context_view.instance_ranks = state->instance_ranks;
+        context_view.prefix_count = state->blocks.size();
+        view.contexts.push_back(std::move(context_view));
+    }
+    return view;
+}
+
+}  // namespace mooncake::conductor::prefixindex
diff --git a/mooncake-conductor/src/zmq/msg_decoder.cpp b/mooncake-conductor/src/zmq/msg_decoder.cpp
new file mode 100644
index 0000000000..1ab75d016a
--- /dev/null
+++ b/mooncake-conductor/src/zmq/msg_decoder.cpp
@@ -0,0 +1,1036 @@
+#include "conductor/zmq/msg_decoder.h"
+
+#include <msgpack.hpp>
+
+#include <cmath>
+#include <cstdint>
+#include <limits>
+#include <map>
+#include <optional>
+#include <set>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace mooncake::conductor::zmq {
+
+namespace {
+
+using msgpack::object;
+using msgpack::type::object_type;
+
+template <typename T>
+struct ValueResult {
+    std::optional<T> value;
+    std::string error;
+
+    static ValueResult Ok(T value) {
+        return {.value = std::move(value), .error = ""};
+    }
+    static ValueResult Err(std::string error) {
+        return {.value = std::nullopt, .error = std::move(error)};
+    }
+};
+
+std::string TypeName(const object& value) {
+    switch (value.type) {
+        case object_type::NIL:
+            return "nil";
+        case object_type::BOOLEAN:
+            return "boolean";
+        case object_type::POSITIVE_INTEGER:
+            return "positive integer";
+        case object_type::NEGATIVE_INTEGER:
+            return "negative integer";
+        case object_type::FLOAT32:
+        case object_type::FLOAT64:
+            return "float";
+        case object_type::STR:
+            return "string";
+        case object_type::BIN:
+            return "binary";
+        case object_type::ARRAY:
+            return "array";
+        case object_type::MAP:
+            return "map";
+        case object_type::EXT:
+            return "extension";
+    }
+    return "unknown";
+}
+
+class MapReader {
+   public:
+    MapReader(const object& value,
+              const std::set<std::string_view>& recognized_fields) {
+        if (value.type != object_type::MAP) {
+            error_ = "expected event map, got " + TypeName(value);
+            return;
+        }
+        for (uint32_t index = 0; index < value.via.map.size; ++index) {
+            const auto& item = value.via.map.ptr[index];
+            if (item.key.type != object_type::STR) {
+                error_ = "event map key at index " + std::to_string(index) +
+                         " must be a string";
+                return;
+            }
+            const std::string key(item.key.via.str.ptr, item.key.via.str.size);
+            if (!recognized_fields.contains(key)) {
+                continue;
+            }
+            if (!fields_.emplace(key, &item.val).second) {
+                error_ = "duplicate recognized key: " + key;
+                return;
+            }
+        }
+    }
+
+    const std::string& error() const { return error_; }
+
+    const object* Get(std::string_view name) const {
+        auto it = fields_.find(std::string(name));
+        return it == fields_.end() ? nullptr : it->second;
+    }
+
+   private:
+    std::map<std::string, const object*> fields_;
+    std::string error_;
+};
+
+ValueResult<std::string> ParseString(const object& value) {
+    if (value.type != object_type::STR) {
+        return ValueResult<std::string>::Err("expected string, got " +
+                                             TypeName(value));
+    }
+    return ValueResult<std::string>::Ok(
+        std::string(value.via.str.ptr, value.via.str.size));
+}
+
+ValueResult<std::optional<std::string>> ParseNullableString(
+    const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<std::string>>::Ok(std::nullopt);
+    }
+    auto parsed = ParseString(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<std::string>>::Err(parsed.error);
+    }
+    return ValueResult<std::optional<std::string>>::Ok(
+        std::move(*parsed.value));
+}
+
+ValueResult<uint64_t> ParseUint64(const object& value) {
+    if (value.type != object_type::POSITIVE_INTEGER) {
+        return ValueResult<uint64_t>::Err("expected unsigned integer, got " +
+                                          TypeName(value));
+    }
+    return ValueResult<uint64_t>::Ok(value.via.u64);
+}
+
+ValueResult<int64_t> ParseInt64(const object& value) {
+    if (value.type == object_type::NEGATIVE_INTEGER) {
+        return ValueResult<int64_t>::Ok(value.via.i64);
+    }
+    if (value.type == object_type::POSITIVE_INTEGER &&
+        value.via.u64 <=
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+        return ValueResult<int64_t>::Ok(static_cast<int64_t>(value.via.u64));
+    }
+    return ValueResult<int64_t>::Err("expected signed 64-bit integer, got " +
+                                     TypeName(value));
+}
+
+ValueResult<std::optional<int64_t>> ParseNullableInt64(const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<int64_t>>::Ok(std::nullopt);
+    }
+    auto parsed = ParseInt64(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<int64_t>>::Err(parsed.error);
+    }
+    return ValueResult<std::optional<int64_t>>::Ok(*parsed.value);
+}
+
+ValueResult<std::optional<uint64_t>> ParseNullableUint64(const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<uint64_t>>::Ok(std::nullopt);
+    }
+    auto parsed = ParseUint64(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<uint64_t>>::Err(parsed.error);
+    }
+    return ValueResult<std::optional<uint64_t>>::Ok(*parsed.value);
+}
+
+// SGLang's event API exposes hashes as signed int64 values.  The Conductor
+// keeps the exact 64-bit bit pattern in uint64_t so high-bit hashes remain
+// compatible with the other event sources.
+ValueResult<uint64_t> ParseSglangHash(const object& value) {
+    if (value.type == object_type::NEGATIVE_INTEGER) {
+        return ValueResult<uint64_t>::Ok(static_cast<uint64_t>(value.via.i64));
+    }
+    if (value.type == object_type::POSITIVE_INTEGER &&
+        value.via.u64 <=
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+        return ValueResult<uint64_t>::Ok(value.via.u64);
+    }
+    return ValueResult<uint64_t>::Err("expected signed 64-bit hash, got " +
+                                      TypeName(value));
+}
+
+ValueResult<std::optional<uint64_t>> ParseNullableSglangHash(
+    const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<uint64_t>>::Ok(std::nullopt);
+    }
+    auto parsed = ParseSglangHash(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<uint64_t>>::Err(parsed.error);
+    }
+    return ValueResult<std::optional<uint64_t>>::Ok(*parsed.value);
+}
+
+ValueResult<ExternalHash> ParseExternalHash(const object& value) {
+    if (value.type == object_type::POSITIVE_INTEGER) {
+        return ValueResult<ExternalHash>::Ok(value.via.u64);
+    }
+    if (value.type == object_type::BIN) {
+        const auto* begin = reinterpret_cast<const uint8_t*>(value.via.bin.ptr);
+        return ValueResult<ExternalHash>::Ok(
+            std::vector<uint8_t>(begin, begin + value.via.bin.size));
+    }
+    return ValueResult<ExternalHash>::Err(
+        "expected unsigned integer or binary hash, got " + TypeName(value));
+}
+
+ValueResult<std::optional<ExternalHash>> ParseNullableExternalHash(
+    const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<ExternalHash>>::Ok(std::nullopt);
+    }
+    auto parsed = ParseExternalHash(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<ExternalHash>>::Err(parsed.error);
+    }
+    return ValueResult<std::optional<ExternalHash>>::Ok(
+        std::move(*parsed.value));
+}
+
+template <typename T, typename Parser>
+ValueResult<std::vector<T>> ParseArray(const object& value, Parser parser) {
+    if (value.type != object_type::ARRAY) {
+        return ValueResult<std::vector<T>>::Err("expected array, got " +
+                                                TypeName(value));
+    }
+    std::vector<T> result;
+    result.reserve(value.via.array.size);
+    for (uint32_t index = 0; index < value.via.array.size; ++index) {
+        auto parsed = parser(value.via.array.ptr[index]);
+        if (!parsed.value.has_value()) {
+            return ValueResult<std::vector<T>>::Err(
+                "element " + std::to_string(index) + ": " + parsed.error);
+        }
+        result.push_back(std::move(*parsed.value));
+    }
+    return ValueResult<std::vector<T>>::Ok(std::move(result));
+}
+
+ValueResult<std::vector<ExternalHash>> ParseExternalHashes(
+    const object& value) {
+    return ParseArray<ExternalHash>(value, ParseExternalHash);
+}
+
+ValueResult<std::vector<uint64_t>> ParseUint64Array(const object& value) {
+    return ParseArray<uint64_t>(value, ParseUint64);
+}
+
+ValueResult<std::vector<int32_t>> ParseInt32Array(const object& value) {
+    return ParseArray<int32_t>(value, [](const object& item) {
+        auto parsed = ParseInt64(item);
+        if (!parsed.value.has_value()) {
+            return ValueResult<int32_t>::Err(parsed.error);
+        }
+        if (*parsed.value < std::numeric_limits<int32_t>::min() ||
+            *parsed.value > std::numeric_limits<int32_t>::max()) {
+            return ValueResult<int32_t>::Err("integer is outside int32 range");
+        }
+        return ValueResult<int32_t>::Ok(static_cast<int32_t>(*parsed.value));
+    });
+}
+
+ValueResult<std::optional<std::vector<int32_t>>> ParseNullableInt32Array(
+    const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<std::vector<int32_t>>>::Ok(
+            std::nullopt);
+    }
+    auto parsed = ParseInt32Array(value);
+    if (!parsed.value.has_value()) {
+        return ValueResult<std::optional<std::vector<int32_t>>>::Err(
+            parsed.error);
+    }
+    return ValueResult<std::optional<std::vector<int32_t>>>::Ok(
+        std::move(*parsed.value));
+}
+
+template <typename T, typename Parser>
+bool ParseRequired(const MapReader& reader, std::string_view field,
+                   Parser parser, T* output, std::string* error) {
+    const object* value = reader.Get(field);
+    if (value == nullptr) {
+        *error = "missing required key: " + std::string(field);
+        return false;
+    }
+    auto parsed = parser(*value);
+    if (!parsed.value.has_value()) {
+        *error = "invalid " + std::string(field) + ": " + parsed.error;
+        return false;
+    }
+    *output = std::move(*parsed.value);
+    return true;
+}
+
+template <typename T, typename Parser>
+bool ParseOptional(const MapReader& reader, std::string_view field,
+                   Parser parser, std::optional<T>* output,
+                   std::string* error) {
+    const object* value = reader.Get(field);
+    if (value == nullptr) {
+        output->reset();
+        return true;
+    }
+    auto parsed = parser(*value);
+    if (!parsed.value.has_value()) {
+        *error = "invalid " + std::string(field) + ": " + parsed.error;
+        return false;
+    }
+    *output = std::move(*parsed.value);
+    return true;
+}
+
+template <typename T, typename Parser>
+bool ParseOptionalNullable(const MapReader& reader, std::string_view field,
+                           Parser parser, std::optional<T>* output,
+                           std::string* error) {
+    const object* value = reader.Get(field);
+    if (value == nullptr) {
+        output->reset();
+        return true;
+    }
+    auto parsed = parser(*value);
+    if (!parsed.value.has_value()) {
+        *error = "invalid " + std::string(field) + ": " + parsed.error;
+        return false;
+    }
+    *output = std::move(*parsed.value);
+    return true;
+}
+
+const std::set<std::string_view> kVllmFields = {
+    "type",      "block_hashes",       "parent_block_hash",
+    "token_ids", "block_size",         "lora_id",
+    "medium",    "lora_name",          "extra_keys",
+    "group_idx", "kv_cache_spec_kind", "kv_cache_spec_sliding_window",
+};
+
+const std::set<std::string_view> kVllmRemovedFields = {"type", "block_hashes",
+                                                       "medium", "group_idx"};
+
+std::string ValidateVllmExtraKeys(const object& value, size_t block_count,
+                                  bool* present) {
+    if (value.type == object_type::NIL) {
+        *present = false;
+        return "";
+    }
+    if (value.type != object_type::ARRAY) {
+        return "expected array or nil, got " + TypeName(value);
+    }
+    if (value.via.array.size != block_count) {
+        return "expected one entry per block hash, got " +
+               std::to_string(value.via.array.size) + " entries for " +
+               std::to_string(block_count) + " block hashes";
+    }
+    for (uint32_t index = 0; index < value.via.array.size; ++index) {
+        const object& item = value.via.array.ptr[index];
+        if (item.type != object_type::NIL && item.type != object_type::ARRAY) {
+            return "element " + std::to_string(index) +
+                   ": expected array or nil, got " + TypeName(item);
+        }
+    }
+    *present = true;
+    return "";
+}
+
+ValueResult<VllmEvent> ParseVllmEvent(const object& raw) {
+    MapReader reader(raw, kVllmFields);
+    if (!reader.error().empty()) {
+        return ValueResult<VllmEvent>::Err(reader.error());
+    }
+
+    std::string error;
+    std::string type;
+    if (!ParseRequired(reader, "type", ParseString, &type, &error)) {
+        return ValueResult<VllmEvent>::Err(error);
+    }
+
+    if (type == "BlockStored") {
+        VllmStoredEvent event;
+        if (!ParseRequired(reader, "block_hashes", ParseExternalHashes,
+                           &event.block_hashes, &error) ||
+            !ParseRequired(reader, "parent_block_hash",
+                           ParseNullableExternalHash, &event.parent_block_hash,
+                           &error) ||
+            !ParseRequired(reader, "token_ids", ParseNullableInt32Array,
+                           &event.token_ids, &error) ||
+            !ParseRequired(reader, "block_size", ParseInt64, &event.block_size,
+                           &error) ||
+            !ParseRequired(reader, "lora_id", ParseNullableInt64,
+                           &event.lora_id, &error) ||
+            !ParseRequired(reader, "medium", ParseNullableString, &event.medium,
+                           &error) ||
+            !ParseRequired(reader, "lora_name", ParseNullableString,
+                           &event.lora_name, &error) ||
+            !ParseOptionalNullable(reader, "group_idx", ParseNullableInt64,
+                                   &event.group_idx, &error) ||
+            !ParseOptionalNullable(reader, "kv_cache_spec_kind",
+                                   ParseNullableString,
+                                   &event.kv_cache_spec_kind, &error) ||
+            !ParseOptionalNullable(
+                reader, "kv_cache_spec_sliding_window", ParseNullableInt64,
+                &event.kv_cache_spec_sliding_window, &error)) {
+            return ValueResult<VllmEvent>::Err(error);
+        }
+        if (const object* extra_keys = reader.Get("extra_keys");
+            extra_keys != nullptr) {
+            if (std::string extra_keys_error = ValidateVllmExtraKeys(
+                    *extra_keys, event.block_hashes.size(),
+                    &event.extra_keys_present);
+                !extra_keys_error.empty()) {
+                return ValueResult<VllmEvent>::Err("invalid extra_keys: " +
+                                                   extra_keys_error);
+            }
+        }
+        return ValueResult<VllmEvent>::Ok(std::move(event));
+    }
+
+    if (type == "BlockRemoved") {
+        for (std::string_view field : kVllmFields) {
+            if (!kVllmRemovedFields.contains(field) &&
+                reader.Get(field) != nullptr) {
+                return ValueResult<VllmEvent>::Err(
+                    "BlockRemoved contains recognized key: " +
+                    std::string(field));
+            }
+        }
+        VllmRemovedEvent event;
+        if (!ParseRequired(reader, "block_hashes", ParseExternalHashes,
+                           &event.block_hashes, &error) ||
+            !ParseRequired(reader, "medium", ParseNullableString, &event.medium,
+                           &error) ||
+            !ParseOptionalNullable(reader, "group_idx", ParseNullableInt64,
+                                   &event.group_idx, &error)) {
+            return ValueResult<VllmEvent>::Err(error);
+        }
+        return ValueResult<VllmEvent>::Ok(std::move(event));
+    }
+
+    if (type == "AllBlocksCleared") {
+        for (std::string_view field : kVllmFields) {
+            if (field != "type" && reader.Get(field) != nullptr) {
+                return ValueResult<VllmEvent>::Err(
+                    "AllBlocksCleared contains recognized key: " +
+                    std::string(field));
+            }
+        }
+        return ValueResult<VllmEvent>::Ok(VllmClearedEvent{});
+    }
+
+    return ValueResult<VllmEvent>::Err("unknown vLLM event tag: " + type);
+}
+
+const std::set<std::string_view> kMooncakeFields = {
+    "event_id",
+    "timestamp",
+    "event_type",
+    "type",
+    "model_name",
+    "block_size",
+    "additional_salt",
+    "lora_name",
+    "tenant_id",
+    "backend_id",
+    "medium",
+    "dp_rank",
+    "group_id",
+    "object_key",
+    "connector_block_hash",
+    "cache_prefix",
+    "tp_rank",
+    "head_or_tp_rank",
+    "pcp_rank",
+    "dcp_rank",
+    "pp_rank",
+    "layer_id",
+    "seq_hashes",
+    "block_hashes",
+    "base_block_idx",
+    "parent_hash",
+    "token_ids",
+    "parent_block_hash",
+};
+
+bool ParseMooncakeCommon(const MapReader& reader, int64_t batch_timestamp,
+                         std::string_view event_type,
+                         MooncakeEventFields* fields, std::string* error) {
+    if (!ParseRequired(reader, "event_id", ParseUint64, &fields->event_id,
+                       error) ||
+        !ParseRequired(reader, "timestamp", ParseInt64,
+                       &fields->timestamp_milliseconds, error) ||
+        !ParseRequired(reader, "model_name", ParseNullableString,
+                       &fields->model_name, error) ||
+        !ParseRequired(reader, "block_size", ParseNullableInt64,
+                       &fields->block_size, error) ||
+        !ParseRequired(reader, "additional_salt", ParseNullableString,
+                       &fields->additional_salt, error) ||
+        !ParseRequired(reader, "lora_name", ParseNullableString,
+                       &fields->lora_name, error) ||
+        !ParseRequired(reader, "tenant_id", ParseString, &fields->tenant_id,
+                       error) ||
+        !ParseRequired(reader, "backend_id", ParseString, &fields->backend_id,
+                       error) ||
+        !ParseRequired(reader, "medium", ParseNullableString, &fields->medium,
+                       error) ||
+        !ParseRequired(reader, "dp_rank", ParseInt64,
+                       &fields->data_parallel_rank, error)) {
+        return false;
+    }
+    if (fields->timestamp_milliseconds != batch_timestamp) {
+        *error = "event timestamp conflicts with batch timestamp";
+        return false;
+    }
+    if (fields->data_parallel_rank < 0) {
+        *error = "event dp_rank must be non-negative";
+        return false;
+    }
+
+    if (const object* legacy_type = reader.Get("type");
+        legacy_type != nullptr) {
+        auto parsed = ParseString(*legacy_type);
+        if (!parsed.value.has_value()) {
+            *error = "invalid type: " + parsed.error;
+            return false;
+        }
+        const std::string_view expected =
+            event_type == "stored"
+                ? "BlockStored"
+                : (event_type == "removed" ? "BlockRemoved"
+                                           : "AllBlocksCleared");
+        if (*parsed.value != expected) {
+            *error = "legacy type conflicts with event_type";
+            return false;
+        }
+    }
+    return true;
+}
+
+bool ParseMooncakeObject(const MapReader& reader, MooncakeObjectFields* object,
+                         std::string* error) {
+    if (!ParseRequired(reader, "group_id", ParseNullableString,
+                       &object->group_id, error) ||
+        !ParseRequired(reader, "seq_hashes", ParseUint64Array,
+                       &object->seq_hashes, error) ||
+        !ParseRequired(reader, "base_block_idx", ParseNullableInt64,
+                       &object->base_block_idx, error) ||
+        !ParseOptional(reader, "object_key", ParseString, &object->object_key,
+                       error) ||
+        !ParseOptional(reader, "connector_block_hash", ParseString,
+                       &object->connector_block_hash, error) ||
+        !ParseOptional(reader, "cache_prefix", ParseString,
+                       &object->cache_prefix, error) ||
+        !ParseOptionalNullable(reader, "tp_rank", ParseNullableInt64,
+                               &object->tp_rank, error) ||
+        !ParseOptionalNullable(reader, "head_or_tp_rank", ParseNullableInt64,
+                               &object->head_or_tp_rank, error) ||
+        !ParseOptionalNullable(reader, "pcp_rank", ParseNullableInt64,
+                               &object->pcp_rank, error) ||
+        !ParseOptionalNullable(reader, "dcp_rank", ParseNullableInt64,
+                               &object->dcp_rank, error) ||
+        !ParseOptionalNullable(reader, "pp_rank", ParseNullableInt64,
+                               &object->pp_rank, error) ||
+        !ParseOptionalNullable(reader, "layer_id", ParseNullableInt64,
+                               &object->layer_id, error) ||
+        !ParseOptional(reader, "block_hashes", ParseUint64Array,
+                       &object->legacy_block_hashes, error)) {
+        return false;
+    }
+    if (object->legacy_block_hashes.has_value() &&
+        *object->legacy_block_hashes != object->seq_hashes) {
+        *error = "legacy block_hashes conflicts with seq_hashes";
+        return false;
+    }
+    return true;
+}
+
+ValueResult<MooncakeEvent> ParseMooncakeEvent(const object& raw,
+                                              int64_t batch_timestamp) {
+    MapReader reader(raw, kMooncakeFields);
+    if (!reader.error().empty()) {
+        return ValueResult<MooncakeEvent>::Err(reader.error());
+    }
+    std::string error;
+    std::string event_type;
+    if (!ParseRequired(reader, "event_type", ParseString, &event_type,
+                       &error)) {
+        return ValueResult<MooncakeEvent>::Err(error);
+    }
+    if (event_type != "stored" && event_type != "removed" &&
+        event_type != "cleared") {
+        return ValueResult<MooncakeEvent>::Err("unknown Mooncake event tag: " +
+                                               event_type);
+    }
+
+    MooncakeEventFields fields;
+    if (!ParseMooncakeCommon(reader, batch_timestamp, event_type, &fields,
+                             &error)) {
+        return ValueResult<MooncakeEvent>::Err(error);
+    }
+
+    if (event_type == "cleared") {
+        static const std::set<std::string_view> kObjectOnlyFields = {
+            "group_id",          "object_key",  "connector_block_hash",
+            "cache_prefix",      "tp_rank",     "head_or_tp_rank",
+            "pcp_rank",          "dcp_rank",    "pp_rank",
+            "layer_id",          "seq_hashes",  "block_hashes",
+            "base_block_idx",    "parent_hash", "token_ids",
+            "parent_block_hash",
+        };
+        for (std::string_view field : kObjectOnlyFields) {
+            if (reader.Get(field) != nullptr) {
+                return ValueResult<MooncakeEvent>::Err(
+                    "cleared event contains recognized object key: " +
+                    std::string(field));
+            }
+        }
+        return ValueResult<MooncakeEvent>::Ok(
+            MooncakeClearedEvent{.fields = std::move(fields)});
+    }
+
+    MooncakeObjectFields object_fields;
+    if (!ParseMooncakeObject(reader, &object_fields, &error)) {
+        return ValueResult<MooncakeEvent>::Err(error);
+    }
+
+    if (event_type == "removed") {
+        if (reader.Get("parent_hash") != nullptr ||
+            reader.Get("token_ids") != nullptr ||
+            reader.Get("parent_block_hash") != nullptr) {
+            return ValueResult<MooncakeEvent>::Err(
+                "removed event contains recognized stored-only key");
+        }
+        return ValueResult<MooncakeEvent>::Ok(MooncakeRemovedEvent{
+            .fields = std::move(fields), .object = std::move(object_fields)});
+    }
+
+    MooncakeStoredEvent event{.fields = std::move(fields),
+                              .object = std::move(object_fields)};
+    if (!ParseRequired(reader, "parent_hash", ParseNullableUint64,
+                       &event.parent_hash, &error) ||
+        !ParseRequired(reader, "token_ids", ParseNullableInt32Array,
+                       &event.token_ids, &error)) {
+        return ValueResult<MooncakeEvent>::Err(error);
+    }
+    if (const object* legacy_parent = reader.Get("parent_block_hash");
+        legacy_parent != nullptr) {
+        auto parsed = ParseNullableUint64(*legacy_parent);
+        if (!parsed.value.has_value()) {
+            return ValueResult<MooncakeEvent>::Err(
+                "invalid parent_block_hash: " + parsed.error);
+        }
+        if (*parsed.value != event.parent_hash) {
+            return ValueResult<MooncakeEvent>::Err(
+                "parent_block_hash conflicts with parent_hash");
+        }
+    }
+    return ValueResult<MooncakeEvent>::Ok(std::move(event));
+}
+
+ValueResult<std::optional<std::vector<int32_t>>> ParseSglangTokenIds(
+    const object& value) {
+    if (value.type == object_type::NIL) {
+        return ValueResult<std::optional<std::vector<int32_t>>>::Ok(
+            std::nullopt);
+    }
+    if (value.type != object_type::ARRAY) {
+        return ValueResult<std::optional<std::vector<int32_t>>>::Err(
+            "expected array or nil, got " + TypeName(value));
+    }
+    std::vector<int32_t> result;
+    for (uint32_t index = 0; index < value.via.array.size; ++index) {
+        const object& item = value.via.array.ptr[index];
+        if (item.type == object_type::ARRAY) {
+            if (item.via.array.size != 2) {
+                return ValueResult<std::optional<std::vector<int32_t>>>::Err(
+                    "token tuple must contain two integers");
+            }
+            for (uint32_t tuple_index = 0; tuple_index < 2; ++tuple_index) {
+                auto parsed = ParseInt64(item.via.array.ptr[tuple_index]);
+                if (!parsed.value.has_value() ||
+                    *parsed.value < std::numeric_limits<int32_t>::min() ||
+                    *parsed.value > std::numeric_limits<int32_t>::max()) {
+                    return ValueResult<std::optional<std::vector<int32_t>>>::
+                        Err("token tuple element is outside int32 range");
+                }
+                result.push_back(static_cast<int32_t>(*parsed.value));
+            }
+            continue;
+        }
+        auto parsed = ParseInt64(item);
+        if (!parsed.value.has_value() ||
+            *parsed.value < std::numeric_limits<int32_t>::min() ||
+            *parsed.value > std::numeric_limits<int32_t>::max()) {
+            return ValueResult<std::optional<std::vector<int32_t>>>::Err(
+                "token id is outside int32 range");
+        }
+        result.push_back(static_cast<int32_t>(*parsed.value));
+    }
+    return ValueResult<std::optional<std::vector<int32_t>>>::Ok(
+        std::move(result));
+}
+
+ValueResult<SglangEvent> ParseSglangEvent(const object& raw) {
+    if (raw.type != object_type::ARRAY || raw.via.array.size == 0) {
+        return ValueResult<SglangEvent>::Err(
+            "expected tagged SGLang event array");
+    }
+    const auto& array = raw.via.array;
+    if (array.ptr[0].type != object_type::STR) {
+        return ValueResult<SglangEvent>::Err(
+            "SGLang event tag must be a string");
+    }
+    const std::string tag(array.ptr[0].via.str.ptr, array.ptr[0].via.str.size);
+
+    if (tag == "AllBlocksCleared") {
+        if (array.size != 1) {
+            return ValueResult<SglangEvent>::Err(
+                "AllBlocksCleared must not contain fields");
+        }
+        return ValueResult<SglangEvent>::Ok(SglangClearedEvent{});
+    }
+
+    if (tag == "BlockRemoved") {
+        if (array.size < 2) {
+            return ValueResult<SglangEvent>::Err(
+                "BlockRemoved has too few fields");
+        }
+        auto hashes = ParseArray<uint64_t>(array.ptr[1], ParseSglangHash);
+        if (!hashes.value.has_value()) {
+            return ValueResult<SglangEvent>::Err(
+                "invalid SGLang block_hashes: " + hashes.error);
+        }
+        auto medium =
+            array.size >= 3
+                ? ParseNullableString(array.ptr[2])
+                : ValueResult<std::optional<std::string>>::Ok(std::nullopt);
+        if (!medium.value.has_value()) {
+            return ValueResult<SglangEvent>::Err("invalid SGLang medium: " +
+                                                 medium.error);
+        }
+        return ValueResult<SglangEvent>::Ok(
+            SglangRemovedEvent{.block_hashes = std::move(*hashes.value),
+                               .medium = std::move(*medium.value)});
+    }
+
+    if (tag == "BlockStored") {
+        // BlockStored's inherited fields are array-like and ordered as in
+        // SGLang's BlockStored struct.  A metadata extension, when present,
+        // is trailing and intentionally ignored by the base decoder.
+        if (array.size < 6) {
+            return ValueResult<SglangEvent>::Err(
+                "BlockStored has too few fields");
+        }
+        auto hashes = ParseArray<uint64_t>(array.ptr[1], ParseSglangHash);
+        if (!hashes.value.has_value()) {
+            return ValueResult<SglangEvent>::Err(
+                "invalid SGLang block_hashes: " + hashes.error);
+        }
+        auto parent = ParseNullableSglangHash(array.ptr[2]);
+        if (!parent.value.has_value()) {
+            return ValueResult<SglangEvent>::Err(
+                "invalid SGLang parent_block_hash: " + parent.error);
+        }
+        auto tokens = ParseSglangTokenIds(array.ptr[3]);
+        if (!tokens.value.has_value()) {
+            return ValueResult<SglangEvent>::Err("invalid SGLang token_ids: " +
+                                                 tokens.error);
+        }
+        auto block_size = ParseInt64(array.ptr[4]);
+        if (!block_size.value.has_value() || *block_size.value <= 0) {
+            return ValueResult<SglangEvent>::Err("invalid SGLang block_size: " +
+                                                 block_size.error);
+        }
+        auto lora_id = ParseNullableInt64(array.ptr[5]);
+        if (!lora_id.value.has_value()) {
+            return ValueResult<SglangEvent>::Err("invalid SGLang lora_id: " +
+                                                 lora_id.error);
+        }
+        auto medium =
+            array.size >= 7
+                ? ParseNullableString(array.ptr[6])
+                : ValueResult<std::optional<std::string>>::Ok(std::nullopt);
+        if (!medium.value.has_value()) {
+            return ValueResult<SglangEvent>::Err("invalid SGLang medium: " +
+                                                 medium.error);
+        }
+
+        std::optional<std::string> cache_salt;
+        if (array.size > 7 && array.ptr[7].type != object_type::NIL) {
+            // BlockStoredWithMetadata currently serializes metadata as a
+            // one-field array-like struct.  Accept a map as well for forward
+            // compatibility with msgspec configuration changes.
+            const auto& metadata = array.ptr[7];
+            if (metadata.type == object_type::ARRAY &&
+                metadata.via.array.size >= 1 &&
+                metadata.via.array.ptr[0].type == object_type::STR) {
+                cache_salt =
+                    std::string(metadata.via.array.ptr[0].via.str.ptr,
+                                metadata.via.array.ptr[0].via.str.size);
+            } else if (metadata.type == object_type::MAP) {
+                for (uint32_t i = 0; i < metadata.via.map.size; ++i) {
+                    const auto& item = metadata.via.map.ptr[i];
+                    if (item.key.type == object_type::STR &&
+                        std::string_view(item.key.via.str.ptr,
+                                         item.key.via.str.size) ==
+                            "cache_salt") {
+                        auto parsed = ParseString(item.val);
+                        if (!parsed.value.has_value()) {
+                            return ValueResult<SglangEvent>::Err(
+                                "invalid SGLang cache_salt: " + parsed.error);
+                        }
+                        cache_salt = std::move(*parsed.value);
+                    }
+                }
+            }
+        }
+        return ValueResult<SglangEvent>::Ok(
+            SglangStoredEvent{.block_hashes = std::move(*hashes.value),
+                              .parent_block_hash = std::move(*parent.value),
+                              .token_ids = std::move(*tokens.value),
+                              .block_size = *block_size.value,
+                              .lora_id = std::move(*lora_id.value),
+                              .medium = std::move(*medium.value),
+                              .cache_salt = std::move(cache_salt)});
+    }
+
+    return ValueResult<SglangEvent>::Err("unknown SGLang event tag: " + tag);
+}
+
+template <typename Batch>
+BatchDecodeResult<Batch> EnvelopeError(std::string error) {
+    return {.ok = false, .batch = {}, .error = std::move(error)};
+}
+
+ValueResult<msgpack::object_handle> UnpackOne(const char* data, size_t len) {
+    if (data == nullptr || len == 0) {
+        return ValueResult<msgpack::object_handle>::Err("empty payload");
+    }
+    try {
+        size_t offset = 0;
+        auto handle = msgpack::unpack(data, len, offset);
+        if (offset != len) {
+            return ValueResult<msgpack::object_handle>::Err(
+                "trailing bytes after MessagePack value");
+        }
+        return ValueResult<msgpack::object_handle>::Ok(std::move(handle));
+    } catch (const std::exception& error) {
+        return ValueResult<msgpack::object_handle>::Err(error.what());
+    }
+}
+
+bool ValidateEnvelopeShape(const object& root, const object** timestamp,
+                           const object** events, const object** dp_rank,
+                           std::string* error) {
+    if (root.type != object_type::ARRAY) {
+        *error = "expected three-element array envelope, got " + TypeName(root);
+        return false;
+    }
+    if (root.via.array.size != 3) {
+        *error = "expected three-element array envelope, got " +
+                 std::to_string(root.via.array.size) + " elements";
+        return false;
+    }
+    *timestamp = &root.via.array.ptr[0];
+    *events = &root.via.array.ptr[1];
+    *dp_rank = &root.via.array.ptr[2];
+    if ((*events)->type != object_type::ARRAY) {
+        *error = "events must be an array, got " + TypeName(**events);
+        return false;
+    }
+    return true;
+}
+
+ValueResult<std::optional<int64_t>> ParseBatchDpRank(const object& value) {
+    auto parsed = ParseNullableInt64(value);
+    if (!parsed.value.has_value()) {
+        return parsed;
+    }
+    if (parsed.value->has_value() && **parsed.value < 0) {
+        return ValueResult<std::optional<int64_t>>::Err(
+            "data_parallel_rank must be non-negative or nil");
+    }
+    return parsed;
+}
+
+}  // namespace
+
+VllmEventBatchResult DecodeVllmEventBatch(const char* data, size_t len) {
+    auto unpacked = UnpackOne(data, len);
+    if (!unpacked.value.has_value()) {
+        return EnvelopeError<VllmEventBatch>(
+            "failed to decode vLLM envelope: " + unpacked.error);
+    }
+    const object* timestamp = nullptr;
+    const object* events = nullptr;
+    const object* dp_rank = nullptr;
+    std::string error;
+    if (!ValidateEnvelopeShape(unpacked.value->get(), &timestamp, &events,
+                               &dp_rank, &error)) {
+        return EnvelopeError<VllmEventBatch>(error);
+    }
+    if (timestamp->type != object_type::FLOAT32 &&
+        timestamp->type != object_type::FLOAT64) {
+        return EnvelopeError<VllmEventBatch>(
+            "vLLM timestamp must be a float, got " + TypeName(*timestamp));
+    }
+    if (!std::isfinite(timestamp->via.f64)) {
+        return EnvelopeError<VllmEventBatch>("vLLM timestamp must be finite");
+    }
+    auto parsed_rank = ParseBatchDpRank(*dp_rank);
+    if (!parsed_rank.value.has_value()) {
+        return EnvelopeError<VllmEventBatch>(
+            "invalid vLLM data_parallel_rank: " + parsed_rank.error);
+    }
+
+    VllmEventBatch batch{.timestamp_seconds = timestamp->via.f64,
+                         .events = {},
+                         .data_parallel_rank = *parsed_rank.value};
+    batch.events.reserve(events->via.array.size);
+    for (uint32_t index = 0; index < events->via.array.size; ++index) {
+        auto parsed = ParseVllmEvent(events->via.array.ptr[index]);
+        if (parsed.value.has_value()) {
+            batch.events.push_back(
+                {.event = std::move(*parsed.value), .error = ""});
+        } else {
+            batch.events.push_back({.event = std::nullopt,
+                                    .error = "event " + std::to_string(index) +
+                                             ": " + parsed.error});
+        }
+    }
+    return {.ok = true, .batch = std::move(batch), .error = ""};
+}
+
+MooncakeEventBatchResult DecodeMooncakeEventBatch(const char* data,
+                                                  size_t len) {
+    auto unpacked = UnpackOne(data, len);
+    if (!unpacked.value.has_value()) {
+        return EnvelopeError<MooncakeEventBatch>(
+            "failed to decode Mooncake envelope: " + unpacked.error);
+    }
+    const object* timestamp = nullptr;
+    const object* events = nullptr;
+    const object* dp_rank = nullptr;
+    std::string error;
+    if (!ValidateEnvelopeShape(unpacked.value->get(), &timestamp, &events,
+                               &dp_rank, &error)) {
+        return EnvelopeError<MooncakeEventBatch>(error);
+    }
+    auto parsed_timestamp = ParseInt64(*timestamp);
+    if (!parsed_timestamp.value.has_value() || *parsed_timestamp.value < 0) {
+        return EnvelopeError<MooncakeEventBatch>(
+            "Mooncake timestamp must be a non-negative integer");
+    }
+    auto parsed_rank = ParseBatchDpRank(*dp_rank);
+    if (!parsed_rank.value.has_value()) {
+        return EnvelopeError<MooncakeEventBatch>(
+            "invalid Mooncake data_parallel_rank: " + parsed_rank.error);
+    }
+
+    MooncakeEventBatch batch{
+        .timestamp_milliseconds = *parsed_timestamp.value,
+        .events = {},
+        .data_parallel_rank = *parsed_rank.value,
+    };
+    batch.events.reserve(events->via.array.size);
+    for (uint32_t index = 0; index < events->via.array.size; ++index) {
+        auto parsed = ParseMooncakeEvent(events->via.array.ptr[index],
+                                         batch.timestamp_milliseconds);
+        if (parsed.value.has_value()) {
+            batch.events.push_back(
+                {.event = std::move(*parsed.value), .error = ""});
+        } else {
+            batch.events.push_back({.event = std::nullopt,
+                                    .error = "event " + std::to_string(index) +
+                                             ": " + parsed.error});
+        }
+    }
+    return {.ok = true, .batch = std::move(batch), .error = ""};
+}
+
+SglangEventBatchResult DecodeSglangEventBatch(const char* data, size_t len) {
+    auto unpacked = UnpackOne(data, len);
+    if (!unpacked.value.has_value()) {
+        return EnvelopeError<SglangEventBatch>(
+            "failed to decode SGLang envelope: " + unpacked.error);
+    }
+    const object* timestamp = nullptr;
+    const object* events = nullptr;
+    const object* dp_rank = nullptr;
+    std::string error;
+    if (!ValidateEnvelopeShape(unpacked.value->get(), &timestamp, &events,
+                               &dp_rank, &error)) {
+        return EnvelopeError<SglangEventBatch>(error);
+    }
+    // A SGLang batch is array-like at both the envelope and event levels.
+    // Treat a map event as a protocol mismatch so ZMQClient can fall back to
+    // the Mooncake map decoder for an SGLang-backed Mooncake Store.  Malformed
+    // array events still remain event-local errors below.
+    for (uint32_t index = 0; index < events->via.array.size; ++index) {
+        if (events->via.array.ptr[index].type != object_type::ARRAY) {
+            return EnvelopeError<SglangEventBatch>(
+                "SGLang event entries must be arrays");
+        }
+    }
+    if (timestamp->type != object_type::FLOAT32 &&
+        timestamp->type != object_type::FLOAT64) {
+        return EnvelopeError<SglangEventBatch>(
+            "SGLang timestamp must be a float");
+    }
+    if (!std::isfinite(timestamp->via.f64)) {
+        return EnvelopeError<SglangEventBatch>(
+            "SGLang timestamp must be finite");
+    }
+    auto parsed_rank = ParseBatchDpRank(*dp_rank);
+    if (!parsed_rank.value.has_value()) {
+        return EnvelopeError<SglangEventBatch>(
+            "invalid SGLang data_parallel_rank: " + parsed_rank.error);
+    }
+
+    SglangEventBatch batch{.timestamp_seconds = timestamp->via.f64,
+                           .events = {},
+                           .data_parallel_rank = *parsed_rank.value};
+    batch.events.reserve(events->via.array.size);
+    for (uint32_t index = 0; index < events->via.array.size; ++index) {
+        auto parsed = ParseSglangEvent(events->via.array.ptr[index]);
+        if (parsed.value.has_value()) {
+            batch.events.push_back(
+                {.event = std::move(*parsed.value), .error = ""});
+        } else {
+            batch.events.push_back({.event = std::nullopt,
+                                    .error = "event " + std::to_string(index) +
+                                             ": " + parsed.error});
+        }
+    }
+    return {.ok = true, .batch = std::move(batch), .error = ""};
+}
+
+}  // namespace mooncake::conductor::zmq
diff --git a/mooncake-conductor/src/zmq/zmq_client.cpp b/mooncake-conductor/src/zmq/zmq_client.cpp
new file mode 100644
index 0000000000..471256d4ea
--- /dev/null
+++ b/mooncake-conductor/src/zmq/zmq_client.cpp
@@ -0,0 +1,875 @@
+#include "conductor/zmq/zmq_client.h"
+
+#include <glog/logging.h>
+#include <zmq_addon.hpp>
+
+#include <algorithm>
+#include <array>
+#include <iterator>
+#include <limits>
+#include <utility>
+#include <vector>
+
+#include "conductor/zmq/msg_decoder.h"
+
+namespace mooncake::conductor::zmq {
+
+namespace {
+
+// 8-byte big-endian sequence number frames.
+uint64_t BigEndianToU64(const unsigned char* b) {
+    uint64_t v = 0;
+    for (int i = 0; i < 8; ++i) {
+        v = (v << 8) | b[i];
+    }
+    return v;
+}
+
+void U64ToBigEndian(uint64_t v, unsigned char* out) {
+    for (int i = 7; i >= 0; --i) {
+        out[i] = static_cast<unsigned char>(v & 0xFF);
+        v >>= 8;
+    }
+}
+
+bool ReplayEnabled(const ZMQClientConfig& config) {
+    return (config.publisher_kind == common::PublisherKind::kVllm ||
+            config.publisher_kind == common::PublisherKind::kSglang) &&
+           !config.replay_endpoint.empty();
+}
+
+}  // namespace
+
+std::string ValidateConfig(const ZMQClientConfig& config) {
+    if (config.endpoint.empty()) {
+        return "endpoint is required";
+    }
+    if (config.replay_timeout <= std::chrono::milliseconds::zero()) {
+        return "replay_timeout must be positive";
+    }
+    if (config.replay_recovery_timeout <= std::chrono::milliseconds::zero()) {
+        return "replay_recovery_timeout must be positive";
+    }
+    if (config.max_recovery_buffered_messages == 0) {
+        return "max_recovery_buffered_messages must be positive";
+    }
+    if (config.max_recovery_buffered_bytes == 0) {
+        return "max_recovery_buffered_bytes must be positive";
+    }
+    return "";
+}
+
+ZMQClient::ZMQClient(ZMQClientConfig config,
+                     std::shared_ptr<EventHandler> handler)
+    : config_(std::move(config)),
+      event_handler_(std::move(handler)),
+      reconnect_delay_(config_.reconnect_delay) {}
+
+ZMQClient::~ZMQClient() { Stop(); }
+
+std::string ZMQClient::Start() {
+    // Attempt initial connection
+    if (auto err = Connect(); !err.empty()) {
+        return "initial connection failed: " + err;
+    }
+
+    loop_thread_ = std::thread([this] { Loop(); });
+
+    LOG(INFO) << "ZMQ client started service=" << config_.cache_pool_key
+              << " endpoint=" << config_.endpoint << " publisher_kind="
+              << common::PublisherKindName(config_.publisher_kind);
+    return "";
+}
+
+void ZMQClient::Stop() {
+    std::lock_guard<std::mutex> stop_lock(stop_mu_);
+    stop_requested_.store(true);
+    if (loop_thread_.joinable()) {
+        loop_thread_.join();
+    }
+
+    {
+        std::unique_lock lock(mu_);
+        CleanupSocketsLocked();
+    }
+
+    LOG(INFO) << "ZMQ client stopped service=" << config_.cache_pool_key;
+}
+
+// Loop is the main background loop handling events and reconnections.
+// Fixed reconnect interval, single loop structure.
+void ZMQClient::Loop() {
+    while (true) {
+        // Check if we should stop
+        if (stop_requested_.load()) {
+            return;
+        }
+
+        // 1. If disconnected, wait for the delay then try to reconnect
+        if (!IsConnected()) {
+            HandleReconnect();
+            continue;
+        }
+
+        // 2. If connected, consume events
+        if (auto err = Consume(); !err.empty()) {
+            LOG(ERROR) << "Consumption error service=" << config_.cache_pool_key
+                       << " error=" << err;
+            MarkDisconnected();
+        }
+    }
+}
+
+void ZMQClient::HandleReconnect() {
+    LOG(INFO) << "Attempting to reconnect to the service. service="
+              << config_.cache_pool_key
+              << " reconnectDelay=" << reconnect_delay_.count() << "ms";
+
+    // Poll the stop flag in slices so Stop() is honored within ~one poll
+    // interval.
+    const auto deadline =
+        std::chrono::steady_clock::now() + config_.reconnect_delay;
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (stop_requested_.load()) {
+            return;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+
+    if (auto err = Connect(); !err.empty()) {
+        LOG(ERROR) << "Reconnect failed service=" << config_.cache_pool_key
+                   << " error=" << err;
+        return;
+    }
+
+    int64_t last_seq;
+    bool stale;
+    {
+        std::shared_lock lock(mu_);
+        last_seq = last_seq_;
+        stale = stale_;
+    }
+    if (ReplayEnabled(config_) && last_seq >= 0 &&
+        last_seq != std::numeric_limits<int64_t>::max() && !stale) {
+        LOG(INFO) << "Reconnected service=" << config_.cache_pool_key
+                  << " resuming_from=" << last_seq + 1;
+        StartRecovery("connection was interrupted");
+        if (auto err = AttemptRecovery(); !err.empty()) {
+            LOG(ERROR) << "Failed to process replay after reconnect service="
+                       << config_.cache_pool_key << " error=" << err;
+        }
+    }
+}
+
+std::string ZMQClient::Connect() {
+    std::unique_lock lock(mu_);
+
+    if (connected_) {
+        return "";
+    }
+
+    // Ensure clean state
+    CleanupSocketsLocked();
+
+    try {
+        auto sock = std::make_unique<::zmq::socket_t>(zmq_context_,
+                                                      ::zmq::socket_type::sub);
+        // Enable IPv6 for dual-stack support
+        sock->set(::zmq::sockopt::ipv6, 1);
+        // Set the receive HWM before connect; ZeroMQ applies it at connection
+        // setup.
+        if (config_.rcv_hwm > 0) {
+            sock->set(::zmq::sockopt::rcvhwm, config_.rcv_hwm);
+        }
+        sock->connect(config_.endpoint);
+        // Important: Subscribe to all topics
+        sock->set(::zmq::sockopt::subscribe, "");
+
+        sub_socket_ = std::move(sock);
+        if (ReplayEnabled(config_)) {
+            auto replay_socket = std::make_unique<::zmq::socket_t>(
+                zmq_context_, ::zmq::socket_type::dealer);
+            replay_socket->set(::zmq::sockopt::ipv6, 1);
+            replay_socket->connect(config_.replay_endpoint);
+            replay_socket_ = std::move(replay_socket);
+        }
+        connected_ = true;
+
+        reconnect_delay_ = config_.reconnect_delay;
+    } catch (const ::zmq::error_t& e) {
+        CleanupSocketsLocked();
+        return std::string("failed to connect to ") + config_.endpoint + ": " +
+               e.what();
+    }
+
+    LOG(INFO) << "Successfully connected to publisher service="
+              << config_.cache_pool_key << " endpoint=" << config_.endpoint
+              << " publisher_kind="
+              << common::PublisherKindName(config_.publisher_kind)
+              << " live_only=" << !ReplayEnabled(config_);
+    if (!config_.replay_endpoint.empty() && !ReplayEnabled(config_)) {
+        LOG(WARNING) << "Ignoring replay_endpoint for publisher kind="
+                     << common::PublisherKindName(config_.publisher_kind)
+                     << "; replay is supported only for vLLM and SGLang";
+    }
+
+    return "";
+}
+
+std::string ZMQClient::Consume() {
+    // Grab the socket pointer under the read lock and poll outside the
+    // lock; the socket is only destroyed by Stop() (after this thread
+    // joins) or by Connect() on this same thread, so that is safe here.
+    ::zmq::socket_t* socket;
+    {
+        std::shared_lock lock(mu_);
+        socket = sub_socket_.get();
+    }
+    if (socket == nullptr) {
+        return "socket is nil";
+    }
+
+    try {
+        ::zmq::pollitem_t items[] = {{socket->handle(), 0, ZMQ_POLLIN, 0}};
+        const int rc = ::zmq::poll(items, 1, config_.poll_timeout);
+        if (rc == 0) {
+            return AttemptRecovery();
+        }
+        if (!(items[0].revents & ZMQ_POLLIN)) {
+            return "";
+        }
+    } catch (const ::zmq::error_t& e) {
+        return std::string("poll error: ") + e.what();
+    }
+
+    if (auto err = ProcessMessage(); !err.empty()) {
+        return "failed to process message: " + err;
+    }
+
+    return "";
+}
+
+std::string ZMQClient::ProcessMessage() {
+    ::zmq::socket_t* socket;
+    {
+        std::shared_lock lock(mu_);
+        socket = sub_socket_.get();
+    }
+    if (socket == nullptr) {
+        return "socket is nil";
+    }
+
+    // Once the first frame is readable, the complete multipart message is
+    // available. Consume it through the final frame so malformed frame counts
+    // cannot block shutdown or leak a tail into the next message.
+    std::vector<::zmq::message_t> frames;
+    try {
+        const auto frame_count = ::zmq::recv_multipart(
+            *socket, std::back_inserter(frames), ::zmq::recv_flags::none);
+        if (!frame_count) {
+            return "failed to receive multipart message";
+        }
+    } catch (const ::zmq::error_t& e) {
+        return std::string("recv error: ") + e.what();
+    }
+
+    if (frames.size() != 3) {
+        return "invalid multipart frame count: expected 3, got " +
+               std::to_string(frames.size());
+    }
+
+    auto& topic_msg = frames[0];
+    auto& seq_msg = frames[1];
+    auto& payload_msg = frames[2];
+
+    if (seq_msg.size() != 8) {
+        return "invalid sequence length";
+    }
+    const uint64_t raw_seq =
+        BigEndianToU64(static_cast<const unsigned char*>(seq_msg.data()));
+    if (raw_seq > static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+        return "sequence exceeds int64 range";
+    }
+    const int64_t seq = static_cast<int64_t>(raw_seq);
+
+    const std::string topic(static_cast<const char*>(topic_msg.data()),
+                            topic_msg.size());
+    int64_t last_live_seq;
+    bool stale;
+    {
+        std::shared_lock lock(mu_);
+        last_live_seq = last_live_seq_;
+        stale = stale_;
+    }
+
+    if (stale) {
+        VLOG(1) << "Dropping event from stale source service="
+                << config_.cache_pool_key << " seq=" << seq;
+        return "";
+    }
+
+    const bool new_gap = last_live_seq != -1 &&
+                         last_live_seq != std::numeric_limits<int64_t>::max() &&
+                         seq > last_live_seq + 1;
+    if (new_gap) {
+        const int64_t missed = seq - last_live_seq - 1;
+        const int64_t total = dropped_events_.fetch_add(missed) + missed;
+        const int64_t gaps = gap_count_.fetch_add(1) + 1;
+        LOG(WARNING) << "Event gap detected service=" << config_.cache_pool_key
+                     << " missed=" << missed << " last=" << last_live_seq
+                     << " current=" << seq << " cumulative_dropped=" << total
+                     << " gaps=" << gaps;
+        if (!ReplayEnabled(config_)) {
+            LOG(WARNING) << "No replay_endpoint configured; " << missed
+                         << " events are permanently lost from the index "
+                            "service="
+                         << config_.cache_pool_key;
+            MarkStale(
+                "sequence gap cannot be recovered without a replay "
+                "endpoint");
+            return "";
+        }
+    }
+    {
+        std::unique_lock lock(mu_);
+        last_live_seq_ = std::max(last_live_seq_, seq);
+    }
+
+    if (!ReplayEnabled(config_)) {
+        if (auto err = DispatchMessage(
+                topic, seq, static_cast<const char*>(payload_msg.data()),
+                payload_msg.size());
+            !err.empty()) {
+            // The handler may have applied only part of the batch.  The
+            // source therefore cannot safely advance or retry this sequence
+            // without a full resynchronization.
+            MarkStale("failed to dispatch live sequence " +
+                      std::to_string(seq) + ": " + err);
+            return "";
+        }
+        UpdateLastSequence(seq);
+        return "";
+    }
+
+    std::string buffer_error;
+    if (!BufferMessage({.topic = topic,
+                        .sequence = seq,
+                        .payload = std::string(
+                            static_cast<const char*>(payload_msg.data()),
+                            payload_msg.size())},
+                       &buffer_error)) {
+        if (!buffer_error.empty()) {
+            MarkStale(buffer_error);
+            return "";
+        }
+        return AttemptRecovery();
+    }
+
+    bool allow_initial_baseline = false;
+    {
+        std::shared_lock lock(mu_);
+        allow_initial_baseline = last_seq_ == -1 && !recovery_in_progress_;
+    }
+    if (auto err = DrainBufferedMessages(allow_initial_baseline);
+        !err.empty()) {
+        return err;
+    }
+
+    bool gap_remains = false;
+    {
+        std::shared_lock lock(mu_);
+        gap_remains = !buffered_messages_.empty() && last_seq_ >= 0 &&
+                      last_seq_ != std::numeric_limits<int64_t>::max() &&
+                      buffered_messages_.begin()->first > last_seq_ + 1;
+    }
+    if (gap_remains) {
+        StartRecovery("live sequence gap detected");
+    }
+    return AttemptRecovery();
+}
+
+std::string ZMQClient::DispatchMessage(const std::string& topic,
+                                       int64_t sequence, const char* payload,
+                                       size_t payload_size) {
+    const MessageMetadata metadata{
+        .publisher_kind = config_.publisher_kind,
+        .endpoint = config_.endpoint,
+        .topic = topic,
+        .sequence = sequence,
+    };
+
+    DecodedBatch batch;
+    std::string decode_error;
+    if (config_.publisher_kind == common::PublisherKind::kMooncake) {
+        auto decoded = DecodeMooncakeEventBatch(payload, payload_size);
+        if (decoded.ok) {
+            batch = std::move(decoded.batch);
+        } else {
+            decode_error = std::move(decoded.error);
+        }
+    } else if (config_.publisher_kind == common::PublisherKind::kSglang) {
+        auto decoded = DecodeSglangEventBatch(payload, payload_size);
+        if (decoded.ok) {
+            batch = std::move(decoded.batch);
+        } else {
+            // A SGLang-backed Mooncake Store still uses the Mooncake map
+            // envelope.  Native SGLang is attempted first; fall back to the
+            // Mooncake decoder for that deployment mode.
+            auto mooncake = DecodeMooncakeEventBatch(payload, payload_size);
+            if (mooncake.ok) {
+                batch = std::move(mooncake.batch);
+            } else {
+                decode_error = "SGLang decode failed: " + decoded.error +
+                               "; Mooncake fallback failed: " + mooncake.error;
+            }
+        }
+    } else {
+        auto decoded = DecodeVllmEventBatch(payload, payload_size);
+        if (decoded.ok) {
+            batch = std::move(decoded.batch);
+        } else {
+            decode_error = std::move(decoded.error);
+        }
+    }
+    if (!decode_error.empty()) {
+        LOG(WARNING) << "Rejected KV event envelope endpoint="
+                     << metadata.endpoint << " topic=" << metadata.topic
+                     << " seq=" << metadata.sequence << " publisher_kind="
+                     << common::PublisherKindName(metadata.publisher_kind)
+                     << " error=" << decode_error;
+        return "";
+    }
+    if (event_handler_ == nullptr) {
+        return "event handler is nil";
+    }
+    if (auto err = event_handler_->HandleBatch(batch, metadata); !err.empty()) {
+        return "event handler failed: " + err;
+    }
+
+    VLOG(1) << "Processed batch service=" << config_.cache_pool_key
+            << " seq=" << sequence << " topic=" << topic;
+    return "";
+}
+
+void ZMQClient::UpdateLastSequence(int64_t sequence) {
+    std::unique_lock lock(mu_);
+    last_seq_ = std::max(last_seq_, sequence);
+}
+
+bool ZMQClient::BufferMessage(BufferedMessage message, std::string* error) {
+    const size_t message_bytes = message.topic.size() + message.payload.size();
+    std::unique_lock lock(mu_);
+    if (stale_ || message.sequence <= last_seq_) {
+        return false;
+    }
+    if (const auto existing = buffered_messages_.find(message.sequence);
+        existing != buffered_messages_.end()) {
+        if (existing->second.payload != message.payload) {
+            *error = "conflicting payloads for sequence " +
+                     std::to_string(message.sequence);
+        }
+        return false;
+    }
+    if (buffered_messages_.size() + 1 >
+        config_.max_recovery_buffered_messages) {
+        *error = "recovery message buffer limit exceeded";
+        return false;
+    }
+    if (message_bytes > config_.max_recovery_buffered_bytes ||
+        buffered_message_bytes_ >
+            config_.max_recovery_buffered_bytes - message_bytes) {
+        *error = "recovery byte buffer limit exceeded";
+        return false;
+    }
+    buffered_message_bytes_ += message_bytes;
+    buffered_messages_.emplace(message.sequence, std::move(message));
+    return true;
+}
+
+std::string ZMQClient::DrainBufferedMessages(bool allow_initial_baseline) {
+    while (true) {
+        BufferedMessage message;
+        {
+            std::unique_lock lock(mu_);
+            if (stale_ || buffered_messages_.empty()) return "";
+
+            auto next = buffered_messages_.end();
+            if (last_seq_ == -1) {
+                if (!allow_initial_baseline) return "";
+                next = buffered_messages_.begin();
+            } else {
+                if (last_seq_ == std::numeric_limits<int64_t>::max()) {
+                    return "";
+                }
+                next = buffered_messages_.find(last_seq_ + 1);
+                if (next == buffered_messages_.end()) return "";
+            }
+
+            message = std::move(next->second);
+            buffered_message_bytes_ -=
+                message.topic.size() + message.payload.size();
+            buffered_messages_.erase(next);
+        }
+
+        if (auto err =
+                DispatchMessage(message.topic, message.sequence,
+                                message.payload.data(), message.payload.size());
+            !err.empty()) {
+            MarkStale("failed to dispatch buffered sequence " +
+                      std::to_string(message.sequence) + ": " + err);
+            return "";
+        }
+        UpdateLastSequence(message.sequence);
+        allow_initial_baseline = false;
+    }
+}
+
+void ZMQClient::StartRecovery(const std::string& reason) {
+    bool started = false;
+    {
+        std::unique_lock lock(mu_);
+        if (!stale_ && !recovery_in_progress_) {
+            recovery_in_progress_ = true;
+            recovery_deadline_ = std::chrono::steady_clock::now() +
+                                 config_.replay_recovery_timeout;
+            started = true;
+        }
+    }
+    if (started) {
+        LOG(WARNING) << "Starting bounded replay recovery service="
+                     << config_.cache_pool_key << " reason=" << reason
+                     << " timeout_ms="
+                     << config_.replay_recovery_timeout.count();
+    }
+}
+
+std::string ZMQClient::AttemptRecovery() {
+    if (!ReplayEnabled(config_)) return "";
+
+    while (true) {
+        int64_t from_seq;
+        std::optional<int64_t> until_seq;
+        std::chrono::steady_clock::time_point deadline;
+        {
+            std::shared_lock lock(mu_);
+            if (stale_ || !recovery_in_progress_) return "";
+            deadline = recovery_deadline_;
+            if (last_seq_ == std::numeric_limits<int64_t>::max()) {
+                lock.unlock();
+                MarkStale("sequence space exhausted during replay recovery");
+                return "";
+            }
+            from_seq = last_seq_ + 1;
+            if (!buffered_messages_.empty()) {
+                until_seq = buffered_messages_.begin()->first;
+            }
+        }
+
+        if (std::chrono::steady_clock::now() >= deadline) {
+            MarkStale("replay recovery deadline exceeded");
+            return "";
+        }
+
+        // A message may have become contiguous after replay records from the
+        // previous iteration were inserted.
+        if (until_seq.has_value() && *until_seq == from_seq) {
+            if (auto err = DrainBufferedMessages(); !err.empty()) return err;
+            continue;
+        }
+
+        auto result = RequestReplay(from_seq, until_seq, deadline);
+        if (!result.ok()) {
+            LOG(WARNING) << "Replay recovery request failed service="
+                         << config_.cache_pool_key << " from=" << from_seq
+                         << (until_seq.has_value()
+                                 ? " until=" + std::to_string(*until_seq)
+                                 : "")
+                         << " error=" << result.error;
+            if (result.failure == ReplayFailure::kUnrecoverable ||
+                std::chrono::steady_clock::now() >= deadline) {
+                MarkStale("unable to recover sequence range starting at " +
+                          std::to_string(from_seq) + ": " + result.error);
+            }
+            return "";
+        }
+
+        const int64_t before = GetLastSequence();
+        for (auto& message : result.messages) {
+            std::string buffer_error;
+            if (!BufferMessage(std::move(message), &buffer_error) &&
+                !buffer_error.empty()) {
+                MarkStale(buffer_error);
+                return "";
+            }
+        }
+        if (auto err = DrainBufferedMessages(); !err.empty()) return err;
+
+        bool gap_remains;
+        {
+            std::unique_lock lock(mu_);
+            if (stale_) return "";
+            gap_remains = !buffered_messages_.empty() && last_seq_ >= 0 &&
+                          last_seq_ != std::numeric_limits<int64_t>::max() &&
+                          buffered_messages_.begin()->first > last_seq_ + 1;
+            if (!gap_remains) {
+                recovery_in_progress_ = false;
+            }
+        }
+        if (!gap_remains) {
+            LOG(INFO) << "Replay recovery completed service="
+                      << config_.cache_pool_key
+                      << " last_sequence=" << GetLastSequence();
+            return "";
+        }
+        if (GetLastSequence() == before) {
+            MarkStale("replay completed without closing the sequence gap");
+            return "";
+        }
+    }
+}
+
+void ZMQClient::MarkStale(const std::string& reason) {
+    MessageMetadata metadata;
+    {
+        std::unique_lock lock(mu_);
+        if (stale_) return;
+        stale_ = true;
+        stale_reason_ = reason;
+        recovery_in_progress_ = false;
+        buffered_messages_.clear();
+        buffered_message_bytes_ = 0;
+        metadata = {
+            .publisher_kind = config_.publisher_kind,
+            .endpoint = config_.endpoint,
+            .topic = "",
+            .sequence = last_seq_,
+        };
+    }
+
+    LOG(ERROR) << "ZMQ event source marked stale service="
+               << config_.cache_pool_key << " endpoint=" << config_.endpoint
+               << " last_sequence=" << metadata.sequence
+               << " reason=" << reason;
+    if (event_handler_ != nullptr) {
+        event_handler_->OnSourceStale(config_.cache_pool_key, metadata, reason);
+    }
+}
+
+ZMQClient::ReplayResult ZMQClient::RequestReplay(
+    int64_t from_seq, std::optional<int64_t> until_seq,
+    std::chrono::steady_clock::time_point recovery_deadline) {
+    ::zmq::socket_t* socket;
+    {
+        std::shared_lock lock(mu_);
+        socket = replay_socket_.get();
+    }
+    if (socket == nullptr) {
+        return {.error = "replay socket is nil",
+                .failure = ReplayFailure::kRetryable};
+    }
+
+    auto fail = [this](std::string error, ReplayFailure failure) {
+        if (auto reset_error = ResetReplaySocket(); !reset_error.empty()) {
+            error += "; failed to reset replay socket: " + reset_error;
+        }
+        return ReplayResult{.error = std::move(error), .failure = failure};
+    };
+
+    unsigned char req[8];
+    U64ToBigEndian(static_cast<uint64_t>(from_seq), req);
+
+    try {
+        // A DEALER must add the empty delimiter that a REQ socket would add
+        // automatically. vLLM's ROUTER expects [identity, empty, from_seq].
+        const std::string empty;
+        const std::array<::zmq::const_buffer, 2> request = {
+            ::zmq::buffer(empty),
+            ::zmq::buffer(req, sizeof(req)),
+        };
+        if (!::zmq::send_multipart(*socket, request)) {
+            return fail("failed to send replay request",
+                        ReplayFailure::kRetryable);
+        }
+
+        size_t existing_messages;
+        size_t existing_bytes;
+        {
+            std::shared_lock lock(mu_);
+            existing_messages = buffered_messages_.size();
+            existing_bytes = buffered_message_bytes_;
+        }
+
+        std::vector<BufferedMessage> messages;
+        size_t replay_bytes = 0;
+        int64_t next_expected = from_seq;
+        while (true) {
+            const auto now = std::chrono::steady_clock::now();
+            if (now >= recovery_deadline) {
+                return fail("replay recovery deadline exceeded",
+                            ReplayFailure::kRetryable);
+            }
+            auto receive_timeout =
+                std::min(config_.replay_timeout,
+                         std::chrono::duration_cast<std::chrono::milliseconds>(
+                             recovery_deadline - now));
+            receive_timeout =
+                std::max(receive_timeout, std::chrono::milliseconds(1));
+            socket->set(
+                ::zmq::sockopt::rcvtimeo,
+                static_cast<int>(std::min<int64_t>(
+                    receive_timeout.count(), std::numeric_limits<int>::max())));
+
+            std::vector<::zmq::message_t> frames;
+            const auto frame_count = ::zmq::recv_multipart(
+                *socket, std::back_inserter(frames), ::zmq::recv_flags::none);
+            if (!frame_count) {
+                return fail("failed to receive replay response: timed out",
+                            ReplayFailure::kRetryable);
+            }
+            // The ROUTER sends [identity, empty, sequence, payload]. The
+            // DEALER strips only the routing identity.
+            if (frames.size() != 3 || !frames[0].empty()) {
+                return fail("invalid replay response frame count or delimiter",
+                            ReplayFailure::kRetryable);
+            }
+
+            auto& seq_msg = frames[1];
+            auto& payload_msg = frames[2];
+            if (seq_msg.size() != 8) {
+                return fail("invalid replay sequence length",
+                            ReplayFailure::kRetryable);
+            }
+            const uint64_t raw_seq = BigEndianToU64(
+                static_cast<const unsigned char*>(seq_msg.data()));
+            if (raw_seq == std::numeric_limits<uint64_t>::max()) {
+                if (!payload_msg.empty()) {
+                    return fail("invalid replay end marker",
+                                ReplayFailure::kRetryable);
+                }
+                if (until_seq.has_value() && next_expected < *until_seq) {
+                    return fail(
+                        "replay buffer did not contain every missing sequence",
+                        ReplayFailure::kUnrecoverable);
+                }
+                LOG(INFO) << "Replay completed service="
+                          << config_.cache_pool_key << " from=" << from_seq
+                          << " replayed=" << messages.size();
+                return {.messages = std::move(messages)};
+            }
+            if (raw_seq >
+                static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+                return fail("replay sequence exceeds int64 range",
+                            ReplayFailure::kRetryable);
+            }
+
+            const int64_t replay_seq = static_cast<int64_t>(raw_seq);
+            if (replay_seq < from_seq ||
+                (until_seq.has_value() && replay_seq >= *until_seq)) {
+                continue;
+            }
+            if (replay_seq < next_expected) {
+                continue;
+            }
+            if (replay_seq > next_expected) {
+                return fail("replay response skipped a sequence",
+                            ReplayFailure::kUnrecoverable);
+            }
+            if (replay_seq == std::numeric_limits<int64_t>::max()) {
+                return fail("replay sequence cannot be incremented",
+                            ReplayFailure::kUnrecoverable);
+            }
+            next_expected = replay_seq + 1;
+
+            const size_t payload_size = payload_msg.size();
+            const bool message_limit_exceeded =
+                existing_messages >= config_.max_recovery_buffered_messages ||
+                messages.size() >=
+                    config_.max_recovery_buffered_messages - existing_messages;
+            const bool byte_limit_exceeded =
+                existing_bytes > config_.max_recovery_buffered_bytes ||
+                replay_bytes >
+                    config_.max_recovery_buffered_bytes - existing_bytes ||
+                payload_size > config_.max_recovery_buffered_bytes -
+                                   existing_bytes - replay_bytes;
+            if (message_limit_exceeded || byte_limit_exceeded) {
+                return fail("replay response exceeds recovery buffer limits",
+                            ReplayFailure::kUnrecoverable);
+            }
+            replay_bytes += payload_size;
+            messages.push_back({.topic = "",
+                                .sequence = replay_seq,
+                                .payload = std::string(static_cast<const char*>(
+                                                           payload_msg.data()),
+                                                       payload_size)});
+        }
+    } catch (const ::zmq::error_t& e) {
+        return fail(std::string("replay request failed: ") + e.what(),
+                    ReplayFailure::kRetryable);
+    }
+}
+
+std::string ZMQClient::ResetReplaySocket() {
+    std::unique_lock lock(mu_);
+    if (replay_socket_) {
+        try {
+            replay_socket_->close();
+        } catch (const ::zmq::error_t& e) {
+            replay_socket_.reset();
+            return e.what();
+        }
+        replay_socket_.reset();
+    }
+    if (!connected_ || !ReplayEnabled(config_)) {
+        return "";
+    }
+
+    try {
+        auto socket = std::make_unique<::zmq::socket_t>(
+            zmq_context_, ::zmq::socket_type::dealer);
+        socket->set(::zmq::sockopt::ipv6, 1);
+        socket->connect(config_.replay_endpoint);
+        replay_socket_ = std::move(socket);
+    } catch (const ::zmq::error_t& e) {
+        return e.what();
+    }
+    return "";
+}
+
+void ZMQClient::CleanupSocketsLocked() {
+    if (sub_socket_) {
+        sub_socket_->close();
+        sub_socket_.reset();
+    }
+    if (replay_socket_) {
+        replay_socket_->close();
+        replay_socket_.reset();
+    }
+    connected_ = false;
+}
+
+void ZMQClient::MarkDisconnected() {
+    std::unique_lock lock(mu_);
+    connected_ = false;
+}
+
+bool ZMQClient::IsConnected() const {
+    std::shared_lock lock(mu_);
+    return connected_;
+}
+
+int64_t ZMQClient::GetLastSequence() const {
+    std::shared_lock lock(mu_);
+    return last_seq_;
+}
+
+bool ZMQClient::IsStale() const {
+    std::shared_lock lock(mu_);
+    return stale_;
+}
+
+std::string ZMQClient::GetStaleReason() const {
+    std::shared_lock lock(mu_);
+    return stale_reason_;
+}
+
+}  // namespace mooncake::conductor::zmq
diff --git a/mooncake-conductor/tests/CMakeLists.txt b/mooncake-conductor/tests/CMakeLists.txt
new file mode 100644
index 0000000000..c66fc50f74
--- /dev/null
+++ b/mooncake-conductor/tests/CMakeLists.txt
@@ -0,0 +1,28 @@
+# Unit tests for mooncake-conductor (gtest, BUILD_UNIT_TESTS).
+
+if(TARGET gtest_main)
+  set(CONDUCTOR_GTEST_LIBS gtest gtest_main)
+else()
+  find_package(GTest REQUIRED)
+  set(CONDUCTOR_GTEST_LIBS GTest::gtest GTest::gtest_main)
+endif()
+
+add_executable(
+  conductor_test
+  common_utils_test.cpp
+  json_uint64_test.cpp
+  model_context_test.cpp
+  compute_hash_test.cpp
+  prefix_indexer_test.cpp
+  msg_decoder_test.cpp
+  zmq_client_test.cpp)
+
+target_link_libraries(conductor_test PRIVATE conductor_cpp_core
+                                             ${CONDUCTOR_GTEST_LIBS})
+
+# Tests load golden vectors relative to this directory.
+target_compile_definitions(
+  conductor_test
+  PRIVATE CONDUCTOR_TEST_FIXTURE_DIR="${CMAKE_CURRENT_SOURCE_DIR}/fixtures")
+
+add_test(NAME conductor_test COMMAND conductor_test)
diff --git a/mooncake-conductor/tests/common_utils_test.cpp b/mooncake-conductor/tests/common_utils_test.cpp
new file mode 100644
index 0000000000..62e5baf71f
--- /dev/null
+++ b/mooncake-conductor/tests/common_utils_test.cpp
@@ -0,0 +1,102 @@
+// Tests for common utility helpers: LoadEnv/LoadIntEnv/ParseLogLevel.
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+
+#include "conductor/common/utils.h"
+
+namespace {
+
+using mooncake::conductor::common::LoadEnv;
+using mooncake::conductor::common::LoadIntEnv;
+using mooncake::conductor::common::LogLevelConfig;
+using mooncake::conductor::common::ParseLogLevel;
+
+constexpr LogLevelConfig kDebug{google::GLOG_INFO, 1};
+constexpr LogLevelConfig kInfo{google::GLOG_INFO, 0};
+constexpr LogLevelConfig kWarn{google::GLOG_WARNING, 0};
+constexpr LogLevelConfig kError{google::GLOG_ERROR, 0};
+
+class EnvGuard {
+   public:
+    explicit EnvGuard(const char* name) : name_(name) { unsetenv(name); }
+    ~EnvGuard() { unsetenv(name_); }
+    void Set(const char* value) { setenv(name_, value, 1); }
+
+   private:
+    const char* name_;
+};
+
+TEST(ParseLogLevel, DefaultsToInfoWhenUnset) {
+    EnvGuard guard("CONDUCTOR_LOG_LEVEL");
+    EXPECT_EQ(ParseLogLevel(), kInfo);
+}
+
+TEST(ParseLogLevel, ParsesAllLevelsCaseInsensitively) {
+    EnvGuard guard("CONDUCTOR_LOG_LEVEL");
+    guard.Set("DEBUG");
+    EXPECT_EQ(ParseLogLevel(), kDebug);
+    guard.Set("debug");
+    EXPECT_EQ(ParseLogLevel(), kDebug);
+    guard.Set("Info");
+    EXPECT_EQ(ParseLogLevel(), kInfo);
+    guard.Set("WARN");
+    EXPECT_EQ(ParseLogLevel(), kWarn);
+    guard.Set("error");
+    EXPECT_EQ(ParseLogLevel(), kError);
+}
+
+TEST(ParseLogLevel, InvalidValueFallsBackToInfo) {
+    EnvGuard guard("CONDUCTOR_LOG_LEVEL");
+    guard.Set("verbose");
+    EXPECT_EQ(ParseLogLevel(), kInfo);
+}
+
+// DEBUG is the one level glog has no direct severity for: it shares INFO and
+// is distinguished by FLAGS_v, so pin that mapping explicitly.
+TEST(ParseLogLevel, DebugSharesInfoSeverityAndRaisesVerbosity) {
+    EnvGuard guard("CONDUCTOR_LOG_LEVEL");
+    guard.Set("DEBUG");
+    const auto debug = ParseLogLevel();
+    guard.Set("INFO");
+    const auto info = ParseLogLevel();
+    EXPECT_EQ(debug.min_severity, info.min_severity);
+    EXPECT_GT(debug.verbosity, info.verbosity);
+}
+
+TEST(LoadEnv, ReturnsValueWhenSet) {
+    EnvGuard guard("CONDUCTOR_TEST_STR");
+    guard.Set("hello");
+    EXPECT_EQ(LoadEnv("CONDUCTOR_TEST_STR", "default"), "hello");
+}
+
+TEST(LoadEnv, ReturnsDefaultWhenUnsetOrEmpty) {
+    EnvGuard guard("CONDUCTOR_TEST_STR");
+    EXPECT_EQ(LoadEnv("CONDUCTOR_TEST_STR", "default"), "default");
+    guard.Set("");
+    EXPECT_EQ(LoadEnv("CONDUCTOR_TEST_STR", "default"), "default");
+}
+
+TEST(LoadIntEnv, ReturnsParsedValue) {
+    EnvGuard guard("CONDUCTOR_TEST_INT");
+    guard.Set("42");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", -1), 42);
+    guard.Set("-7");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", -1), -7);
+}
+
+TEST(LoadIntEnv, ReturnsDefaultOnUnsetOrInvalid) {
+    EnvGuard guard("CONDUCTOR_TEST_INT");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", 13333), 13333);
+    guard.Set("not-a-number");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", 13333), 13333);
+    // Surrounding whitespace is rejected in numeric parsing.
+    guard.Set(" 42");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", 13333), 13333);
+    guard.Set("42x");
+    EXPECT_EQ(LoadIntEnv("CONDUCTOR_TEST_INT", 13333), 13333);
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/compute_hash_test.cpp b/mooncake-conductor/tests/compute_hash_test.cpp
new file mode 100644
index 0000000000..18f7b3d91f
--- /dev/null
+++ b/mooncake-conductor/tests/compute_hash_test.cpp
@@ -0,0 +1,869 @@
+#include <gtest/gtest.h>
+
+#include <openssl/evp.h>
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "conductor/prefixindex/hash_strategy.h"
+#include "test_fixtures.h"
+
+namespace {
+
+using mooncake::conductor::common::HashProfileConfig;
+using mooncake::conductor::prefixindex::ContextKey;
+using mooncake::conductor::prefixindex::CreateHashStrategy;
+using mooncake::conductor::prefixindex::DigestToHex;
+using mooncake::conductor::prefixindex::HashBlock;
+using mooncake::conductor::prefixindex::HashProfile;
+using mooncake::conductor::prefixindex::ResolveHashProfile;
+using mooncake::conductor::prefixindex::ValidateHashProfile;
+using mooncake::conductor::test::LoadJsonFixture;
+using mooncake::conductor::test::ParseU64;
+
+constexpr char kSeedZeroRoot[] =
+    "4e1195df020de59e0d65a33a4279f1183e7ae4e5d980e309f8b55adff2e61c3e";
+constexpr char kPaddedSeedZeroRoot[] =
+    "8d912e4e62b3cc377b1d1c7a14ef61dffbdaa0990237035c05401c29414c4172";
+constexpr char kPickleSeedZeroRoot[] =
+    "1973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c";
+
+HashProfile ProfileFrom(const Json::Value& value) {
+    HashProfile profile;
+    profile.strategy = value["strategy"].asString();
+    profile.algorithm = value["algorithm"].asString();
+    profile.python_hash_seed = value["python_hash_seed"].asString();
+    profile.root_digest = value["root_digest"].asString();
+    profile.index_projection = value["index_projection"].asString();
+    return profile;
+}
+
+HashProfileConfig SourceProfile(std::string python_hash_seed = "0",
+                                std::string algorithm = "sha256_cbor") {
+    return {.strategy = "vllm_v1",
+            .algorithm = std::move(algorithm),
+            .python_hash_seed = std::move(python_hash_seed),
+            .index_projection = "low64_be"};
+}
+
+HashProfile ValidProfile() {
+    return HashProfile{
+        .strategy = "vllm_v1",
+        .algorithm = "sha256_cbor",
+        .python_hash_seed = "0",
+        .root_digest = kSeedZeroRoot,
+        .index_projection = "low64_be",
+    };
+}
+
+HashProfile ValidPickleProfile() {
+    return HashProfile{
+        .strategy = "vllm_v1",
+        .algorithm = "sha256",
+        .python_hash_seed = "0",
+        .root_digest = kPickleSeedZeroRoot,
+        .index_projection = "low64_be",
+    };
+}
+
+HashProfile ResolvedProfile(std::string python_hash_seed,
+                            std::string algorithm = "sha256_cbor") {
+    HashProfile profile;
+    const std::string error = ResolveHashProfile(
+        SourceProfile(std::move(python_hash_seed), std::move(algorithm)),
+        &profile);
+    EXPECT_TRUE(error.empty()) << error;
+    return profile;
+}
+
+std::vector<int32_t> TokensFrom(const Json::Value& values) {
+    std::vector<int32_t> tokens;
+    tokens.reserve(values.size());
+    for (const auto& value : values) {
+        tokens.push_back(static_cast<int32_t>(value.asInt64()));
+    }
+    return tokens;
+}
+
+// Expands the compact repeat encoding used by large fixture cases.
+std::vector<int32_t> CaseTokens(const Json::Value& test_case) {
+    if (test_case.isMember("token_ids_repeat")) {
+        const Json::Value& repeat = test_case["token_ids_repeat"];
+        return std::vector<int32_t>(
+            static_cast<size_t>(repeat["count"].asUInt64()),
+            static_cast<int32_t>(repeat["value"].asInt64()));
+    }
+    return TokensFrom(test_case["token_ids"]);
+}
+
+std::string CaseLora(const Json::Value& test_case) {
+    if (test_case.isMember("lora_name_repeat")) {
+        const Json::Value& repeat = test_case["lora_name_repeat"];
+        return std::string(static_cast<size_t>(repeat["count"].asUInt64()),
+                           repeat["value"].asString().front());
+    }
+    return test_case["lora_name"].asString();
+}
+
+std::optional<std::string> SaltFrom(const Json::Value& value) {
+    if (value.isNull()) {
+        return std::nullopt;
+    }
+    return value.asString();
+}
+
+std::vector<uint8_t> HexToBytes(const std::string& hex) {
+    std::vector<uint8_t> bytes;
+    bytes.reserve(hex.size() / 2);
+    auto nibble = [](char value) -> int {
+        if (value >= '0' && value <= '9') {
+            return value - '0';
+        }
+        if (value >= 'a' && value <= 'f') {
+            return value - 'a' + 10;
+        }
+        return -1;
+    };
+    for (size_t index = 0; index + 1 < hex.size(); index += 2) {
+        const int high = nibble(hex[index]);
+        const int low = nibble(hex[index + 1]);
+        EXPECT_GE(high, 0);
+        EXPECT_GE(low, 0);
+        bytes.push_back(static_cast<uint8_t>((high << 4) | low));
+    }
+    return bytes;
+}
+
+// Recomputes SHA-256 over the fixture's pinned serialized bytes so the test
+// compares serialized bytes as well as digests.
+std::string Sha256Hex(const std::vector<uint8_t>& input) {
+    std::array<uint8_t, 32> digest{};
+    unsigned int digest_size = 0;
+    EVP_MD_CTX* context = EVP_MD_CTX_new();
+    EXPECT_NE(context, nullptr);
+    EXPECT_EQ(EVP_DigestInit_ex(context, EVP_sha256(), nullptr), 1);
+    EXPECT_EQ(EVP_DigestUpdate(context, input.data(), input.size()), 1);
+    EXPECT_EQ(EVP_DigestFinal_ex(context, digest.data(), &digest_size), 1);
+    EVP_MD_CTX_free(context);
+    EXPECT_EQ(digest_size, digest.size());
+    return DigestToHex(digest);
+}
+
+TEST(HashProfileResolver, MatchesSeedRootGoldenVectors) {
+    const Json::Value fixture = LoadJsonFixture("hash_golden_vectors.json");
+    const Json::Value& vectors = fixture["seed_root_vectors"];
+    ASSERT_TRUE(vectors.isArray());
+    ASSERT_GE(vectors.size(), 2u);
+
+    for (const auto& vector : vectors) {
+        const std::string seed = vector["python_hash_seed"].asString();
+        SCOPED_TRACE(seed);
+        HashProfile resolved;
+        const std::string error =
+            ResolveHashProfile(SourceProfile(seed), &resolved);
+        ASSERT_TRUE(error.empty()) << error;
+        EXPECT_EQ(resolved.python_hash_seed, seed);
+        EXPECT_EQ(resolved.root_digest, vector["root_digest"].asString());
+    }
+}
+
+TEST(HashProfileResolver, MatchesPickleSeedRootGoldenVectors) {
+    const Json::Value fixture =
+        LoadJsonFixture("hash_golden_vectors_sha256.json");
+    const Json::Value& vectors = fixture["seed_root_vectors"];
+    ASSERT_TRUE(vectors.isArray());
+    ASSERT_GE(vectors.size(), 4u);
+
+    for (const auto& vector : vectors) {
+        const std::string seed = vector["python_hash_seed"].asString();
+        SCOPED_TRACE(seed);
+        HashProfile resolved;
+        const std::string error =
+            ResolveHashProfile(SourceProfile(seed, "sha256"), &resolved);
+        ASSERT_TRUE(error.empty()) << error;
+        EXPECT_EQ(resolved.algorithm, "sha256");
+        EXPECT_EQ(resolved.python_hash_seed, seed);
+        EXPECT_EQ(resolved.root_digest, vector["root_digest"].asString());
+        // The serialized seed bytes pinned by the fixture must be exactly
+        // what the digest was computed over.
+        EXPECT_EQ(Sha256Hex(HexToBytes(vector["pickle_hex"].asString())),
+                  vector["root_digest"].asString());
+    }
+}
+
+TEST(HashProfileResolver, AcceptsSupportedSeedsAndPreservesExactText) {
+    struct SeedCase {
+        const char* seed;
+        const char* root_digest;
+    };
+    const SeedCase cases[] = {
+        {"0", kSeedZeroRoot},
+        {"00", kPaddedSeedZeroRoot},
+        {"random",
+         "78d6ac7e28de859e492449dcea03e3807377d69998c5af819fed33a6df490cad"},
+        {"4294967295",
+         "177f280a5695322a18f16c96a26dc99d9c03f905940103dfe24a9c646fe446a8"},
+    };
+
+    for (const SeedCase& test_case : cases) {
+        SCOPED_TRACE(test_case.seed);
+        const HashProfile resolved = ResolvedProfile(test_case.seed);
+        EXPECT_EQ(resolved.strategy, "vllm_v1");
+        EXPECT_EQ(resolved.algorithm, "sha256_cbor");
+        EXPECT_EQ(resolved.python_hash_seed, test_case.seed);
+        EXPECT_EQ(resolved.root_digest, test_case.root_digest);
+        EXPECT_EQ(resolved.index_projection, "low64_be");
+        EXPECT_TRUE(ValidateHashProfile(resolved).empty());
+    }
+
+    EXPECT_NE(ResolvedProfile("0"), ResolvedProfile("00"));
+}
+
+TEST(HashProfileResolver, AcceptsPickleSeedsAndPreservesExactText) {
+    const HashProfile resolved = ResolvedProfile("0", "sha256");
+    EXPECT_EQ(resolved.strategy, "vllm_v1");
+    EXPECT_EQ(resolved.algorithm, "sha256");
+    EXPECT_EQ(resolved.python_hash_seed, "0");
+    EXPECT_EQ(resolved.root_digest, kPickleSeedZeroRoot);
+    EXPECT_EQ(resolved.index_projection, "low64_be");
+    EXPECT_TRUE(ValidateHashProfile(resolved).empty());
+
+    // Seed text is never normalized, under either supported algorithm.
+    EXPECT_NE(ResolvedProfile("0", "sha256"), ResolvedProfile("00", "sha256"));
+    // Identical seed text under different algorithms yields different roots.
+    EXPECT_NE(ResolvedProfile("0", "sha256").root_digest,
+              ResolvedProfile("0", "sha256_cbor").root_digest);
+}
+
+TEST(HashProfileResolver, RejectsMalformedSeedTextAndClearsOutput) {
+    const std::vector<std::string> invalid = {
+        "",    "+1",     "-1",      " 0",         "0 ",         "0\n",
+        "1.0", "Random", "random ", "4294967296", "not-a-seed", "\xe9\x9b\xb6",
+    };
+
+    for (const std::string& seed : invalid) {
+        SCOPED_TRACE(seed);
+        for (const std::string& algorithm : {"sha256_cbor", "sha256"}) {
+            HashProfile resolved = ValidProfile();
+            EXPECT_FALSE(
+                ResolveHashProfile(SourceProfile(seed, algorithm), &resolved)
+                    .empty());
+            EXPECT_EQ(resolved, HashProfile{});
+        }
+    }
+
+    EXPECT_FALSE(ResolveHashProfile(SourceProfile(), nullptr).empty());
+}
+
+TEST(HashProfileResolver, RejectsInvalidUtf8AndUnsupportedSelectors) {
+    for (const std::string seed :
+         {std::string("\xc0\xaf", 2), std::string("\xed\xa0\x80", 3)}) {
+        HashProfile resolved;
+        const std::string error =
+            ResolveHashProfile(SourceProfile(seed), &resolved);
+        EXPECT_NE(error.find("valid UTF-8"), std::string::npos);
+    }
+
+    std::vector<HashProfileConfig> unsupported;
+    auto source = SourceProfile();
+    source.strategy = "vllm_v2";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.algorithm = "md5";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.algorithm = "sha512";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.algorithm = "xxhash";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.algorithm = "SHA256";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.algorithm = "";
+    unsupported.push_back(source);
+    source = SourceProfile();
+    source.index_projection = "high64_be";
+    unsupported.push_back(source);
+
+    for (const HashProfileConfig& candidate : unsupported) {
+        HashProfile resolved;
+        EXPECT_FALSE(ResolveHashProfile(candidate, &resolved).empty());
+        EXPECT_EQ(resolved, HashProfile{});
+    }
+}
+
+TEST(HashProfile, AcceptsOnlyTheSupportedResolvedProfile) {
+    for (const HashProfile& profile : {ValidProfile(), ValidPickleProfile()}) {
+        SCOPED_TRACE(profile.algorithm);
+        EXPECT_TRUE(ValidateHashProfile(profile).empty());
+
+        std::string error = "stale error";
+        auto strategy = CreateHashStrategy(profile, &error);
+        EXPECT_NE(strategy, nullptr);
+        EXPECT_TRUE(error.empty());
+        EXPECT_NE(CreateHashStrategy(profile, nullptr), nullptr);
+    }
+}
+
+TEST(HashProfile, RejectsUnsupportedAndMalformedResolvedShapes) {
+    std::vector<std::pair<std::string, HashProfile>> cases;
+
+    HashProfile profile = ValidProfile();
+    profile.strategy = "vllm_v2";
+    cases.emplace_back("strategy", profile);
+
+    profile = ValidProfile();
+    profile.algorithm = "md5";
+    cases.emplace_back("algorithm", profile);
+
+    profile = ValidProfile();
+    profile.index_projection = "high64_be";
+    cases.emplace_back("projection", profile);
+
+    profile = ValidProfile();
+    profile.python_hash_seed.clear();
+    cases.emplace_back("empty seed", profile);
+
+    profile = ValidProfile();
+    profile.root_digest.pop_back();
+    cases.emplace_back("short root", profile);
+
+    profile = ValidProfile();
+    profile.root_digest.push_back('0');
+    cases.emplace_back("long root", profile);
+
+    profile = ValidProfile();
+    profile.root_digest[1] = 'E';
+    cases.emplace_back("uppercase root", profile);
+
+    profile = ValidProfile();
+    profile.root_digest[0] = 'g';
+    cases.emplace_back("non-hex root", profile);
+
+    for (const auto& [name, candidate] : cases) {
+        SCOPED_TRACE(name);
+        const std::string validation_error = ValidateHashProfile(candidate);
+        EXPECT_FALSE(validation_error.empty());
+
+        std::string factory_error;
+        EXPECT_EQ(CreateHashStrategy(candidate, &factory_error), nullptr);
+        EXPECT_EQ(factory_error, validation_error);
+    }
+}
+
+TEST(HashProfile, SemanticValidationRejectsForgedSeedRootPair) {
+    HashProfile forged = ValidProfile();
+    forged.root_digest = kPaddedSeedZeroRoot;
+
+    const std::string validation_error = ValidateHashProfile(forged);
+    EXPECT_NE(validation_error.find("does not match"), std::string::npos);
+
+    std::string factory_error = "stale error";
+    EXPECT_NE(CreateHashStrategy(forged, &factory_error), nullptr);
+    EXPECT_TRUE(factory_error.empty());
+}
+
+TEST(HashProfile, SemanticValidationUsesTheSelectedRecipe) {
+    // A root derived with one recipe must not validate under the other
+    // algorithm even when every other field is well formed.
+    HashProfile mismatched = ValidPickleProfile();
+    mismatched.algorithm = "sha256_cbor";
+    EXPECT_NE(ValidateHashProfile(mismatched).find("does not match"),
+              std::string::npos);
+
+    mismatched = ValidProfile();
+    mismatched.algorithm = "sha256";
+    EXPECT_NE(ValidateHashProfile(mismatched).find("does not match"),
+              std::string::npos);
+}
+
+TEST(HashStrategyGolden, MatchesVllmAndCbor2Vectors) {
+    const Json::Value fixture = LoadJsonFixture("hash_golden_vectors.json");
+    const HashProfile profile = ProfileFrom(fixture["profile"]);
+    ASSERT_TRUE(ValidateHashProfile(profile).empty());
+
+    std::string factory_error;
+    auto strategy = CreateHashStrategy(profile, &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    const Json::Value& cases = fixture["cases"];
+    ASSERT_GT(cases.size(), 0u);
+    for (const auto& test_case : cases) {
+        SCOPED_TRACE(test_case["name"].asString());
+        ContextKey context{
+            .tenant_id = "default",
+            .model_name = "golden-model",
+            .lora_name = test_case["lora_name"].asString(),
+            .block_size = test_case["block_size"].asInt64(),
+        };
+        const std::vector<int32_t> tokens = TokensFrom(test_case["token_ids"]);
+
+        std::vector<HashBlock> blocks;
+        const std::string error = strategy->Compute(
+            context, tokens, SaltFrom(test_case["cache_salt"]), &blocks);
+        ASSERT_TRUE(error.empty()) << error;
+
+        const Json::Value& expected = test_case["expected"];
+        ASSERT_EQ(blocks.size(), expected.size());
+        for (Json::ArrayIndex index = 0; index < expected.size(); ++index) {
+            const std::string digest = DigestToHex(blocks[index].digest);
+            EXPECT_EQ(digest, expected[index]["digest"].asString())
+                << "block=" << index;
+            EXPECT_EQ(digest.substr(48),
+                      expected[index]["projected_hex"].asString())
+                << "block=" << index;
+            EXPECT_EQ(blocks[index].projected.value,
+                      ParseU64(expected[index]["projected_decimal"]))
+                << "block=" << index;
+        }
+    }
+}
+
+TEST(HashStrategyGolden, MatchesVllmPickleVectors) {
+    const Json::Value fixture =
+        LoadJsonFixture("hash_golden_vectors_sha256.json");
+    const HashProfile profile = ProfileFrom(fixture["profile"]);
+    ASSERT_EQ(profile.algorithm, "sha256");
+    ASSERT_TRUE(ValidateHashProfile(profile).empty());
+
+    std::string factory_error;
+    auto strategy = CreateHashStrategy(profile, &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    const Json::Value& cases = fixture["cases"];
+    ASSERT_GT(cases.size(), 0u);
+    for (const auto& test_case : cases) {
+        SCOPED_TRACE(test_case["name"].asString());
+        ContextKey context{
+            .tenant_id = "default",
+            .model_name = "golden-model",
+            .lora_name = CaseLora(test_case),
+            .block_size = test_case["block_size"].asInt64(),
+        };
+        const std::vector<int32_t> tokens = CaseTokens(test_case);
+
+        std::vector<HashBlock> blocks;
+        const std::string error = strategy->Compute(
+            context, tokens, SaltFrom(test_case["cache_salt"]), &blocks);
+        ASSERT_TRUE(error.empty()) << error;
+
+        const Json::Value& expected = test_case["expected"];
+        ASSERT_EQ(blocks.size(), expected.size());
+        for (Json::ArrayIndex index = 0; index < expected.size(); ++index) {
+            const std::string digest = DigestToHex(blocks[index].digest);
+            EXPECT_EQ(digest, expected[index]["digest"].asString())
+                << "block=" << index;
+            EXPECT_EQ(digest.substr(48),
+                      expected[index]["projected_hex"].asString())
+                << "block=" << index;
+            EXPECT_EQ(blocks[index].projected.value,
+                      ParseU64(expected[index]["projected_decimal"]))
+                << "block=" << index;
+            if (expected[index].isMember("pickle_hex")) {
+                // The fixture pins the exact serialized Pickle bytes; their
+                // SHA-256 must reproduce the pinned digest.
+                EXPECT_EQ(Sha256Hex(HexToBytes(
+                              expected[index]["pickle_hex"].asString())),
+                          expected[index]["digest"].asString())
+                    << "block=" << index;
+            }
+        }
+    }
+}
+
+TEST(HashStrategyGolden, PickleMultiBlockChainDoesNotReuseLow64AsParent) {
+    const Json::Value fixture =
+        LoadJsonFixture("hash_golden_vectors_sha256.json");
+    const Json::Value& test_case = fixture["cases"][0];
+    ASSERT_EQ(test_case["name"].asString(), "spec_unsalted");
+
+    std::string factory_error;
+    auto strategy =
+        CreateHashStrategy(ProfileFrom(fixture["profile"]), &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "golden-model",
+        .lora_name = "",
+        .block_size = test_case["block_size"].asInt64(),
+    };
+    const std::vector<int32_t> tokens = CaseTokens(test_case);
+    std::vector<HashBlock> blocks;
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    ASSERT_EQ(blocks.size(), 2u);
+
+    const std::string second_digest = DigestToHex(blocks[1].digest);
+    EXPECT_EQ(second_digest, test_case["expected"][1]["digest"].asString());
+    EXPECT_NE(second_digest,
+              test_case["incorrect_low64_parent_digest"].asString());
+}
+
+TEST(HashStrategyGolden, AlgorithmsProduceDistinctDigestsForIdenticalTokens) {
+    const Json::Value cbor_fixture =
+        LoadJsonFixture("hash_golden_vectors.json");
+    const Json::Value pickle_fixture =
+        LoadJsonFixture("hash_golden_vectors_sha256.json");
+
+    std::string factory_error;
+    auto cbor_strategy = CreateHashStrategy(
+        ProfileFrom(cbor_fixture["profile"]), &factory_error);
+    ASSERT_NE(cbor_strategy, nullptr) << factory_error;
+    auto pickle_strategy = CreateHashStrategy(
+        ProfileFrom(pickle_fixture["profile"]), &factory_error);
+    ASSERT_NE(pickle_strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "golden-model",
+        .lora_name = "",
+        .block_size = 4,
+    };
+    const std::vector<int32_t> tokens{1, 2, 3, 4, 5, 6, 7, 8};
+    std::vector<HashBlock> cbor_blocks;
+    std::vector<HashBlock> pickle_blocks;
+    ASSERT_TRUE(
+        cbor_strategy->Compute(context, tokens, std::nullopt, &cbor_blocks)
+            .empty());
+    ASSERT_TRUE(
+        pickle_strategy->Compute(context, tokens, std::nullopt, &pickle_blocks)
+            .empty());
+    ASSERT_EQ(cbor_blocks.size(), pickle_blocks.size());
+
+    // Identical tokens under the two recipes must produce distinct digests
+    // while each recipe matches its own vLLM reference vectors.
+    for (size_t index = 0; index < cbor_blocks.size(); ++index) {
+        EXPECT_NE(cbor_blocks[index], pickle_blocks[index])
+            << "block=" << index;
+        EXPECT_EQ(DigestToHex(cbor_blocks[index].digest),
+                  cbor_fixture["cases"][0]["expected"]
+                              [static_cast<Json::ArrayIndex>(index)]["digest"]
+                                  .asString());
+        EXPECT_EQ(DigestToHex(pickle_blocks[index].digest),
+                  pickle_fixture["cases"][0]["expected"]
+                                [static_cast<Json::ArrayIndex>(index)]["digest"]
+                                    .asString());
+    }
+}
+
+TEST(HashStrategyGolden, MultiBlockChainDoesNotReuseLow64AsParent) {
+    const Json::Value fixture = LoadJsonFixture("hash_golden_vectors.json");
+    const Json::Value& test_case = fixture["cases"][0];
+    ASSERT_EQ(test_case["name"].asString(), "spec_unsalted");
+
+    std::string factory_error;
+    auto strategy =
+        CreateHashStrategy(ProfileFrom(fixture["profile"]), &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "golden-model",
+        .lora_name = "",
+        .block_size = test_case["block_size"].asInt64(),
+    };
+    const std::vector<int32_t> tokens = TokensFrom(test_case["token_ids"]);
+    std::vector<HashBlock> blocks;
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    ASSERT_EQ(blocks.size(), 2u);
+
+    const std::string second_digest = DigestToHex(blocks[1].digest);
+    EXPECT_EQ(second_digest, test_case["expected"][1]["digest"].asString());
+    EXPECT_NE(second_digest,
+              test_case["incorrect_low64_parent_digest"].asString());
+}
+
+TEST(HashStrategy, EmptySaltHasNoExtraKey) {
+    for (const HashProfile& profile : {ValidProfile(), ValidPickleProfile()}) {
+        SCOPED_TRACE(profile.algorithm);
+        std::string factory_error;
+        auto strategy = CreateHashStrategy(profile, &factory_error);
+        ASSERT_NE(strategy, nullptr) << factory_error;
+
+        ContextKey context{
+            .tenant_id = "default",
+            .model_name = "model",
+            .lora_name = "",
+            .block_size = 4,
+        };
+        const std::vector<int32_t> tokens{1, 2, 3, 4, 5, 6, 7, 8};
+        std::vector<HashBlock> omitted_salt;
+        std::vector<HashBlock> empty_salt;
+        ASSERT_TRUE(
+            strategy->Compute(context, tokens, std::nullopt, &omitted_salt)
+                .empty());
+        ASSERT_TRUE(
+            strategy->Compute(context, tokens, std::string{}, &empty_salt)
+                .empty());
+        EXPECT_EQ(empty_salt, omitted_salt);
+    }
+}
+
+TEST(HashStrategy, RejectsInvalidComputeInputsWithoutPartialOutput) {
+    std::string factory_error;
+    auto strategy = CreateHashStrategy(ValidProfile(), &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "model",
+        .lora_name = "",
+        .block_size = 0,
+    };
+    const std::vector<int32_t> tokens{1, 2, 3, 4};
+    std::vector<HashBlock> blocks(1);
+    EXPECT_FALSE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    EXPECT_TRUE(blocks.empty());
+
+    context.block_size = -4;
+    blocks.resize(1);
+    EXPECT_FALSE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    EXPECT_TRUE(blocks.empty());
+
+    context.block_size = 4;
+    context.lora_name = std::string("\xc0\xaf", 2);
+    blocks.resize(1);
+    EXPECT_FALSE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    EXPECT_TRUE(blocks.empty());
+
+    context.lora_name.clear();
+    const std::string invalid_salt("\xed\xa0\x80", 3);
+    blocks.resize(1);
+    EXPECT_FALSE(
+        strategy->Compute(context, tokens, invalid_salt, &blocks).empty());
+    EXPECT_TRUE(blocks.empty());
+
+    EXPECT_FALSE(
+        strategy->Compute(context, tokens, std::nullopt, nullptr).empty());
+}
+
+TEST(HashStrategy, ResolvedSeedChangesTheChain) {
+    const HashProfile alternate_profile = ResolvedProfile("00");
+
+    std::string factory_error;
+    auto default_strategy = CreateHashStrategy(ValidProfile(), &factory_error);
+    ASSERT_NE(default_strategy, nullptr) << factory_error;
+    auto alternate_strategy =
+        CreateHashStrategy(alternate_profile, &factory_error);
+    ASSERT_NE(alternate_strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "model",
+        .lora_name = "",
+        .block_size = 4,
+    };
+    const std::vector<int32_t> tokens{1, 2, 3, 4};
+    std::vector<HashBlock> default_blocks;
+    std::vector<HashBlock> alternate_blocks;
+    ASSERT_TRUE(default_strategy
+                    ->Compute(context, tokens, std::nullopt, &default_blocks)
+                    .empty());
+    ASSERT_TRUE(alternate_strategy
+                    ->Compute(context, tokens, std::nullopt, &alternate_blocks)
+                    .empty());
+    ASSERT_EQ(default_blocks.size(), 1u);
+    ASSERT_EQ(alternate_blocks.size(), 1u);
+    EXPECT_NE(default_blocks, alternate_blocks);
+}
+
+TEST(HashStrategy, DigestToHexPreservesLeadingZerosAndUsesLowercase) {
+    std::array<uint8_t, 32> digest{};
+    digest[0] = 0x01;
+    digest[30] = 0xcd;
+    digest[31] = 0xef;
+
+    const std::string encoded = DigestToHex(digest);
+    ASSERT_EQ(encoded.size(), 64u);
+    EXPECT_EQ(encoded.substr(0, 4), "0100");
+    EXPECT_EQ(encoded.substr(60), "cdef");
+}
+
+TEST(HashChain, MatchesEagerCompute) {
+    for (const HashProfile& profile : {ValidProfile(), ValidPickleProfile()}) {
+        SCOPED_TRACE(profile.algorithm);
+        std::string factory_error;
+        auto strategy = CreateHashStrategy(profile, &factory_error);
+        ASSERT_NE(strategy, nullptr) << factory_error;
+
+        ContextKey context{
+            .tenant_id = "default",
+            .model_name = "model",
+            .lora_name = "lora-a",
+            .block_size = 4,
+        };
+        const std::vector<int32_t> tokens{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+        const std::string salt = "salty";
+
+        std::vector<HashBlock> eager;
+        ASSERT_TRUE(strategy->Compute(context, tokens, salt, &eager).empty());
+        ASSERT_EQ(eager.size(), 2u);
+
+        std::string chain_error;
+        auto chain = strategy->CreateChain(context, tokens, salt, &chain_error);
+        ASSERT_NE(chain, nullptr) << chain_error;
+        EXPECT_EQ(chain->BlockCount(), eager.size());
+        for (size_t index = 0; index < eager.size(); ++index) {
+            const HashBlock* block = chain->At(index, &chain_error);
+            ASSERT_NE(block, nullptr) << chain_error;
+            EXPECT_EQ(*block, eager[index]) << "block=" << index;
+        }
+    }
+}
+
+TEST(HashChain, ComputesOnlyRequestedPrefix) {
+    std::string factory_error;
+    auto strategy = CreateHashStrategy(ValidProfile(), &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "model",
+        .lora_name = "",
+        .block_size = 4,
+    };
+    const std::vector<int32_t> tokens(400, 7);  // 100 complete blocks
+
+    std::string chain_error;
+    auto chain =
+        strategy->CreateChain(context, tokens, std::nullopt, &chain_error);
+    ASSERT_NE(chain, nullptr) << chain_error;
+    EXPECT_EQ(chain->BlockCount(), 100u);
+    EXPECT_EQ(chain->ComputedCount(), 0u);
+
+    ASSERT_NE(chain->At(0, &chain_error), nullptr) << chain_error;
+    EXPECT_EQ(chain->ComputedCount(), 1u);
+
+    ASSERT_NE(chain->At(2, &chain_error), nullptr) << chain_error;
+    EXPECT_EQ(chain->ComputedCount(), 3u);
+
+    // Already-computed blocks must not be rehashed.
+    ASSERT_NE(chain->At(2, &chain_error), nullptr) << chain_error;
+    EXPECT_EQ(chain->ComputedCount(), 3u);
+
+    EXPECT_EQ(chain->At(100, &chain_error), nullptr);
+    EXPECT_FALSE(chain_error.empty());
+    EXPECT_EQ(chain->ComputedCount(), 3u);
+}
+
+TEST(HashChain, RejectsInvalidInputsAtSetup) {
+    std::string factory_error;
+    auto strategy = CreateHashStrategy(ValidProfile(), &factory_error);
+    ASSERT_NE(strategy, nullptr) << factory_error;
+
+    ContextKey context{
+        .tenant_id = "default",
+        .model_name = "model",
+        .lora_name = "",
+        .block_size = 0,
+    };
+    const std::vector<int32_t> tokens{1, 2, 3, 4};
+
+    std::string chain_error;
+    EXPECT_EQ(
+        strategy->CreateChain(context, tokens, std::nullopt, &chain_error),
+        nullptr);
+    EXPECT_FALSE(chain_error.empty());
+
+    context.block_size = 4;
+    const std::string invalid_salt("\xed\xa0\x80", 3);
+    EXPECT_EQ(
+        strategy->CreateChain(context, tokens, invalid_salt, &chain_error),
+        nullptr);
+}
+
+TEST(SglangHashChain, MatchesNativeSha256TokenChain) {
+    HashProfile profile;
+    const HashProfileConfig source{
+        .strategy = "sglang",
+        .algorithm = "sha256_raw",
+        .python_hash_seed = "0",
+        .index_projection = "first64_be",
+    };
+    ASSERT_TRUE(ResolveHashProfile(source, &profile).empty());
+    ASSERT_TRUE(ValidateHashProfile(profile).empty());
+
+    std::string error;
+    auto strategy = CreateHashStrategy(profile, &error);
+    ASSERT_NE(strategy, nullptr) << error;
+    const ContextKey context{.tenant_id = "default",
+                             .model_name = "model",
+                             .lora_name = "",
+                             .block_size = 4};
+    const std::vector<int32_t> tokens{1, 2, 3, 4};
+    std::vector<HashBlock> blocks;
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    ASSERT_EQ(blocks.size(), 1u);
+    EXPECT_EQ(blocks[0].projected.value, 0xcf97adeedb59e05bULL);
+
+    blocks.clear();
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::string("salty"), &blocks)
+            .empty());
+    ASSERT_EQ(blocks.size(), 1u);
+    EXPECT_EQ(blocks[0].projected.value, 0xd98f7292c18ec8ddULL);
+}
+
+TEST(SglangHashChain, IncludesPartialFinalBlock) {
+    HashProfile profile;
+    const HashProfileConfig source{
+        .strategy = "sglang",
+        .algorithm = "sha256_raw",
+        .python_hash_seed = "0",
+        .index_projection = "first64_be",
+    };
+    ASSERT_TRUE(ResolveHashProfile(source, &profile).empty());
+
+    std::string error;
+    auto strategy = CreateHashStrategy(profile, &error);
+    ASSERT_NE(strategy, nullptr) << error;
+    const ContextKey context{.tenant_id = "default",
+                             .model_name = "model",
+                             .lora_name = "",
+                             .block_size = 2};
+    const std::vector<int32_t> tokens{1, 2, 3};
+    std::vector<HashBlock> blocks;
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    EXPECT_EQ(blocks.size(), 2u);
+}
+
+TEST(SglangHashChain, MatchesBigramGolden) {
+    HashProfile profile;
+    const HashProfileConfig source{
+        .strategy = "sglang_bigram",
+        .algorithm = "sha256_raw",
+        .python_hash_seed = "0",
+        .index_projection = "first64_be",
+    };
+    ASSERT_TRUE(ResolveHashProfile(source, &profile).empty());
+    ASSERT_TRUE(ValidateHashProfile(profile).empty());
+
+    std::string error;
+    auto strategy = CreateHashStrategy(profile, &error);
+    ASSERT_NE(strategy, nullptr) << error;
+    const ContextKey context{.tenant_id = "default",
+                             .model_name = "model",
+                             .lora_name = "",
+                             .block_size = 4};
+    const std::vector<int32_t> tokens{10, 20, 30, 40};
+    std::vector<HashBlock> blocks;
+    ASSERT_TRUE(
+        strategy->Compute(context, tokens, std::nullopt, &blocks).empty());
+    ASSERT_EQ(blocks.size(), 1u);
+    EXPECT_EQ(blocks[0].projected.value, 15710792592378487421ULL);
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/fixtures/generate_hash_golden_vectors.py b/mooncake-conductor/tests/fixtures/generate_hash_golden_vectors.py
new file mode 100644
index 0000000000..fed187c335
--- /dev/null
+++ b/mooncake-conductor/tests/fixtures/generate_hash_golden_vectors.py
@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""Generates hash_golden_vectors_sha256.json from the vLLM `sha256` recipe.
+
+The `sha256` vLLM prefix-cache hash is SHA-256 over
+``pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)``; for the supported
+Python range (3.10-3.14) HIGHEST_PROTOCOL is protocol 5.  This script uses the
+real CPython pickler as the normative oracle and replicates
+vLLM's ``hash_block_tokens`` value shapes:
+
+    root  = sha256(pickle(seed_string))
+    block = sha256(pickle((parent_digest_bytes, tuple(block_token_ids),
+                           extra_keys)))
+
+with ``extra_keys`` equal to None, or the tuple ``(lora_name,)`` /
+``(lora_name, cache_salt)`` (salt only on the first block), matching
+vLLM's ``lora + mm + cache_salt + prompt_embeds`` ordering for the subset the
+Conductor query contract can express.
+
+The checked-in fixture pins the generator environment below.  Regenerate with:
+
+    python3 generate_hash_golden_vectors.py
+
+from this directory and diff the result; only regenerate intentionally.
+"""
+
+import hashlib
+import json
+import pickle
+import platform
+import sys
+from pathlib import Path
+
+PROTOCOL = pickle.HIGHEST_PROTOCOL
+assert PROTOCOL == 5, f"expected Pickle protocol 5, got {PROTOCOL}"
+
+# Pinned reference: vLLM v1 kv_cache_utils.hash_block_tokens +
+# utils/hashing.py sha256, verified against checkout
+# v0.22.1rc0-459-g462ef83d5 (commit 462ef83d58e6fadeb6e216dc583554a6980a0af9).
+VLLM_REFERENCE = (
+    "vLLM v0.22.1rc0-459-g462ef83d5 hash_block_tokens value shapes with "
+    "utils/hashing.py sha256 = SHA256(pickle.dumps(value, protocol=5))"
+)
+
+# Serialized block bytes are recorded in full for every case small enough to
+# keep the fixture reviewable.  Cases that must cross CPython's 64 KiB frame
+# target (frame boundary and large-payload paths) record pickle_len instead;
+# their digest is still the SHA-256 of the exact serialized bytes, so a digest
+# match certifies byte equality.
+PICKLE_HEX_SIZE_LIMIT = 8192
+
+SEEDS = ["0", "00", "random", "4294967295"]
+
+
+def sha256_pickle(value) -> bytes:
+    return hashlib.sha256(pickle.dumps(value, protocol=PROTOCOL)).digest()
+
+
+def extras_for(lora_name: str, cache_salt, block_index: int):
+    keys = []
+    if lora_name:
+        keys.append(lora_name)
+    if block_index == 0 and cache_salt:
+        keys.append(cache_salt)
+    return tuple(keys) if keys else None
+
+
+def block_entry(pickle_bytes: bytes) -> dict:
+    digest = hashlib.sha256(pickle_bytes).digest()
+    entry = {
+        "digest": digest.hex(),
+        "projected_hex": digest[-8:].hex(),
+        "projected_decimal": str(int.from_bytes(digest[-8:], "big")),
+    }
+    if len(pickle_bytes) <= PICKLE_HEX_SIZE_LIMIT:
+        entry["pickle_hex"] = pickle_bytes.hex()
+    else:
+        entry["pickle_len"] = len(pickle_bytes)
+    return entry
+
+
+def expand_tokens(case: dict):
+    if "token_ids_repeat" in case:
+        spec = case["token_ids_repeat"]
+        return [spec["value"]] * spec["count"]
+    return list(case["token_ids"])
+
+
+CASES = [
+    {
+        "name": "spec_unsalted",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+    },
+    {
+        "name": "single_token_tuple",
+        "block_size": 1,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [7],
+    },
+    {
+        "name": "two_token_tuple",
+        "block_size": 2,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [7, 8],
+    },
+    {
+        "name": "three_token_tuple",
+        "block_size": 3,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [7, 8, 9],
+    },
+    {
+        "name": "empty_extras_encode_as_none",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [10, 20, 30, 40],
+    },
+    {
+        "name": "signed_integer_boundaries",
+        "block_size": 8,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [-2147483648, -1, 0, 255, 256, 65535, 65536, 2147483647],
+    },
+    {
+        "name": "utf8_multibyte",
+        "block_size": 4,
+        "lora_name": "模型-适配器",
+        "cache_salt": "盐值-🚀",
+        "token_ids": [1, 2, 3, 4],
+    },
+    {
+        "name": "lora_length_255",
+        "block_size": 4,
+        "lora_name": "a" * 255,
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4],
+    },
+    {
+        "name": "lora_length_256",
+        "block_size": 4,
+        "lora_name": "a" * 256,
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4],
+    },
+    {
+        "name": "salt_length_255",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": "s" * 255,
+        "token_ids": [1, 2, 3, 4],
+    },
+    {
+        "name": "salt_length_256",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": "s" * 256,
+        "token_ids": [1, 2, 3, 4],
+    },
+    {
+        "name": "lora_every_block",
+        "block_size": 4,
+        "lora_name": "adapter-A",
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+    },
+    {
+        "name": "salt_first_block_only",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": "tenant-salt",
+        "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+    },
+    {
+        "name": "lora_then_salt",
+        "block_size": 4,
+        "lora_name": "adapter-A",
+        "cache_salt": "tenant-salt",
+        "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+    },
+    {
+        "name": "multi_block_chain",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": list(range(1, 17)),
+    },
+    {
+        "name": "incomplete_tail",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4, 5, 6],
+    },
+    {
+        "name": "no_complete_block",
+        "block_size": 4,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids": [1, 2, 3],
+    },
+    {
+        # 22000 BININT2 tokens serialize to ~66 KiB inside the token tuple,
+        # forcing CPython's _Framer to commit a frame mid-value.
+        "name": "frame_boundary_token_stream",
+        "block_size": 22000,
+        "lora_name": "",
+        "cache_salt": None,
+        "token_ids_repeat": {"value": 256, "count": 22000},
+    },
+    {
+        # A >= 64 KiB extra-key string takes CPython's write_large_bytes path:
+        # the pending frame is force-committed and the string is written
+        # without a frame opcode.
+        "name": "large_lora_large_payload",
+        "block_size": 4,
+        "lora_name": "a" * 70000,
+        "cache_salt": None,
+        "token_ids": [1, 2, 3, 4],
+    },
+]
+
+
+def main() -> None:
+    seed_root_vectors = []
+    for seed in SEEDS:
+        serialized = pickle.dumps(seed, protocol=PROTOCOL)
+        seed_root_vectors.append(
+            {
+                "python_hash_seed": seed,
+                "pickle_hex": serialized.hex(),
+                "root_digest": hashlib.sha256(serialized).hexdigest(),
+            }
+        )
+
+    root_digest = sha256_pickle("0")
+    cases = []
+    for case in CASES:
+        tokens = expand_tokens(case)
+        block_size = case["block_size"]
+        lora_name = case["lora_name"]
+        cache_salt = case["cache_salt"]
+
+        expected = []
+        parent = root_digest
+        for block_index in range(len(tokens) // block_size):
+            block_tokens = tokens[
+                block_index * block_size : (block_index + 1) * block_size
+            ]
+            value = (
+                parent,
+                tuple(block_tokens),
+                extras_for(lora_name, cache_salt, block_index),
+            )
+            serialized = pickle.dumps(value, protocol=PROTOCOL)
+            expected.append(block_entry(serialized))
+            parent = hashlib.sha256(serialized).digest()
+
+        entry = {
+            "name": case["name"],
+            "block_size": block_size,
+            "lora_name": lora_name if len(lora_name) <= 512 else "",
+            "cache_salt": cache_salt,
+            "expected": expected,
+        }
+        if len(lora_name) > 512:
+            entry["lora_name_repeat"] = {"value": "a", "count": len(lora_name)}
+        if "token_ids_repeat" in case:
+            entry["token_ids_repeat"] = case["token_ids_repeat"]
+        else:
+            entry["token_ids"] = tokens
+
+        if case["name"] == "spec_unsalted":
+            # Digest of the second block when the low-64 projection is
+            # incorrectly reused as the parent instead of the full digest.
+            first_digest = bytes.fromhex(expected[0]["digest"])
+            wrong_value = (
+                first_digest[-8:],
+                tuple(tokens[4:8]),
+                None,
+            )
+            entry["incorrect_low64_parent_digest"] = hashlib.sha256(
+                pickle.dumps(wrong_value, protocol=PROTOCOL)
+            ).hexdigest()
+
+        cases.append(entry)
+
+    fixture = {
+        "description": (
+            "Golden vectors for the supported vLLM v1 sha256 (CPython Pickle "
+            "protocol 5) seed-derived root and block-hash profile.  pickle_hex "
+            "records the exact serialized bytes hashed for small values; large "
+            "frame-boundary values record pickle_len and are certified by "
+            "their digest."
+        ),
+        "generator": VLLM_REFERENCE,
+        "generator_metadata": {
+            "python_version": platform.python_version(),
+            "pickle_protocol": PROTOCOL,
+            "pickle_highest_protocol": pickle.HIGHEST_PROTOCOL,
+        },
+        "profile": {
+            "strategy": "vllm_v1",
+            "algorithm": "sha256",
+            "python_hash_seed": "0",
+            "root_digest": root_digest.hex(),
+            "index_projection": "low64_be",
+        },
+        "seed_root_vectors": seed_root_vectors,
+        "cases": cases,
+    }
+
+    out = Path(__file__).with_name("hash_golden_vectors_sha256.json")
+    # ensure_ascii=False keeps the non-ASCII cache-salt cases readable, so both
+    # the encoding and the line ending are explicit rather than
+    # platform-dependent: the default encoding is not guaranteed to represent
+    # those characters, and LF keeps regeneration byte-identical everywhere so
+    # the "regenerate and diff" check above reports only real changes.
+    out.write_text(
+        json.dumps(fixture, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/mooncake-conductor/tests/fixtures/hash_golden_vectors.json b/mooncake-conductor/tests/fixtures/hash_golden_vectors.json
new file mode 100644
index 0000000000..1acf63937f
--- /dev/null
+++ b/mooncake-conductor/tests/fixtures/hash_golden_vectors.json
@@ -0,0 +1,232 @@
+{
+  "description": "Golden vectors for the supported vLLM v1 sha256_cbor seed-derived root and block-hash profile.",
+  "generator": "vLLM 0.22.0 hash_block_tokens semantics with cbor2 6.1.1 canonical=True",
+  "profile": {
+    "strategy": "vllm_v1",
+    "algorithm": "sha256_cbor",
+    "python_hash_seed": "0",
+    "root_digest": "4e1195df020de59e0d65a33a4279f1183e7ae4e5d980e309f8b55adff2e61c3e",
+    "index_projection": "low64_be"
+  },
+  "seed_root_vectors": [
+    {
+      "python_hash_seed": "0",
+      "canonical_cbor_hex": "6130",
+      "root_digest": "4e1195df020de59e0d65a33a4279f1183e7ae4e5d980e309f8b55adff2e61c3e"
+    },
+    {
+      "python_hash_seed": "00",
+      "canonical_cbor_hex": "623030",
+      "root_digest": "8d912e4e62b3cc377b1d1c7a14ef61dffbdaa0990237035c05401c29414c4172"
+    }
+  ],
+  "cases": [
+    {
+      "name": "spec_unsalted",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+      "expected": [
+        {
+          "digest": "c9d58ba695280d69b243e1e0df813136ca9196b286fb1a021e0b2e028ef071cb",
+          "projected_hex": "1e0b2e028ef071cb",
+          "projected_decimal": "2164874634404590027"
+        },
+        {
+          "digest": "24125b23e68883b5c2141db2959d48433fe6bde2f26bd914efad121d154ab2d6",
+          "projected_hex": "efad121d154ab2d6",
+          "projected_decimal": "17270480062156288726"
+        }
+      ],
+      "incorrect_low64_parent_digest": "067bc227e5aa13cb174be22cd7016b7b21b663eddba6241928d7a7d1ffc0aa1e"
+    },
+    {
+      "name": "lora_every_block",
+      "block_size": 4,
+      "lora_name": "adapter-A",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+      "expected": [
+        {
+          "digest": "1424c0ec536f82188b592f263601d4e48c0255081c5f1e9225163c6d611a5222",
+          "projected_hex": "25163c6d611a5222",
+          "projected_decimal": "2672389869369184802"
+        },
+        {
+          "digest": "4a2ec941640a8f2470869ec2b3cf6bdd90e2be83b21807b628ac9abe9341eea9",
+          "projected_hex": "28ac9abe9341eea9",
+          "projected_decimal": "2930887600816385705"
+        }
+      ]
+    },
+    {
+      "name": "salt_first_block",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": "tenant-salt",
+      "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+      "expected": [
+        {
+          "digest": "3be45574566e2f3c51c9f254d9627cf113382b627aeaefe8b661d66cfa089359",
+          "projected_hex": "b661d66cfa089359",
+          "projected_decimal": "13142020951183496025"
+        },
+        {
+          "digest": "22dea68f80ff7f40243dfb906a33db02571905c78a3b42153a56de5ad08c661a",
+          "projected_hex": "3a56de5ad08c661a",
+          "projected_decimal": "4203791783824221722"
+        }
+      ]
+    },
+    {
+      "name": "lora_then_salt",
+      "block_size": 4,
+      "lora_name": "adapter-A",
+      "cache_salt": "tenant-salt",
+      "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+      "expected": [
+        {
+          "digest": "22977da6c71098507264dbf4161d451c2d98494c5c146717f36787e184b36040",
+          "projected_hex": "f36787e184b36040",
+          "projected_decimal": "17539136676481425472"
+        },
+        {
+          "digest": "6a3cd7de2626c2d2982eb5bc9d4878a49745c3784bde8a2334ffac47286bb866",
+          "projected_hex": "34ffac47286bb866",
+          "projected_decimal": "3818960430654273638"
+        }
+      ]
+    },
+    {
+      "name": "signed_integer_boundaries",
+      "block_size": 12,
+      "lora_name": "",
+      "cache_salt": null,
+      "token_ids": [
+        -2147483648,
+        -257,
+        -256,
+        -25,
+        -24,
+        -1,
+        0,
+        23,
+        24,
+        255,
+        256,
+        2147483647
+      ],
+      "expected": [
+        {
+          "digest": "d4e5cc975a84b5ae7299d36910284bf256ea1eade2689dba6391b08d86e006d7",
+          "projected_hex": "6391b08d86e006d7",
+          "projected_decimal": "7174709803277616855"
+        }
+      ]
+    },
+    {
+      "name": "utf8_length_23",
+      "block_size": 4,
+      "lora_name": "aaaaaaaaaaaaaaaaaaaaaaa",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3, 4],
+      "expected": [
+        {
+          "digest": "3cc96f507898959352d1d123c849d0ab4b11846c8de3c67123d72e78957adb07",
+          "projected_hex": "23d72e78957adb07",
+          "projected_decimal": "2582584006759078663"
+        }
+      ]
+    },
+    {
+      "name": "utf8_length_24",
+      "block_size": 4,
+      "lora_name": "aaaaaaaaaaaaaaaaaaaaaaaa",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3, 4],
+      "expected": [
+        {
+          "digest": "553263ebbf33660ecba67f9fcabea06d20cca3a71c79abf6e1894d39c7fa8ff8",
+          "projected_hex": "e1894d39c7fa8ff8",
+          "projected_decimal": "16251605640906706936"
+        }
+      ]
+    },
+    {
+      "name": "utf8_multibyte",
+      "block_size": 4,
+      "lora_name": "\u6a21\u578b-\u9002\u914d\u5668",
+      "cache_salt": "\u76d0\u503c-\ud83d\ude80",
+      "token_ids": [1, 2, 3, 4],
+      "expected": [
+        {
+          "digest": "69af00b1b180a366c69003a00527c2baf6bbc71880abc3b1d3b60fa2f553cdca",
+          "projected_hex": "d3b60fa2f553cdca",
+          "projected_decimal": "15255397980339162570"
+        }
+      ]
+    },
+    {
+      "name": "definite_array_length_24",
+      "block_size": 24,
+      "lora_name": "",
+      "cache_salt": null,
+      "token_ids": [
+        0,
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8,
+        9,
+        10,
+        11,
+        12,
+        13,
+        14,
+        15,
+        16,
+        17,
+        18,
+        19,
+        20,
+        21,
+        22,
+        23
+      ],
+      "expected": [
+        {
+          "digest": "792917e681c347b21bebfdd57cabcca6b79c865f83ccd2cfbd9cb56ffed2b088",
+          "projected_hex": "bd9cb56ffed2b088",
+          "projected_decimal": "13662994862156460168"
+        }
+      ]
+    },
+    {
+      "name": "incomplete_tail",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3, 4, 5, 6],
+      "expected": [
+        {
+          "digest": "c9d58ba695280d69b243e1e0df813136ca9196b286fb1a021e0b2e028ef071cb",
+          "projected_hex": "1e0b2e028ef071cb",
+          "projected_decimal": "2164874634404590027"
+        }
+      ]
+    },
+    {
+      "name": "no_complete_block",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "token_ids": [1, 2, 3],
+      "expected": []
+    }
+  ]
+}
diff --git a/mooncake-conductor/tests/fixtures/hash_golden_vectors_sha256.json b/mooncake-conductor/tests/fixtures/hash_golden_vectors_sha256.json
new file mode 100644
index 0000000000..06b4e16f96
--- /dev/null
+++ b/mooncake-conductor/tests/fixtures/hash_golden_vectors_sha256.json
@@ -0,0 +1,485 @@
+{
+  "description": "Golden vectors for the supported vLLM v1 sha256 (CPython Pickle protocol 5) seed-derived root and block-hash profile.  pickle_hex records the exact serialized bytes hashed for small values; large frame-boundary values record pickle_len and are certified by their digest.",
+  "generator": "vLLM v0.22.1rc0-459-g462ef83d5 hash_block_tokens value shapes with utils/hashing.py sha256 = SHA256(pickle.dumps(value, protocol=5))",
+  "generator_metadata": {
+    "python_version": "3.12.13",
+    "pickle_protocol": 5,
+    "pickle_highest_protocol": 5
+  },
+  "profile": {
+    "strategy": "vllm_v1",
+    "algorithm": "sha256",
+    "python_hash_seed": "0",
+    "root_digest": "1973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c",
+    "index_projection": "low64_be"
+  },
+  "seed_root_vectors": [
+    {
+      "python_hash_seed": "0",
+      "pickle_hex": "80059505000000000000008c0130942e",
+      "root_digest": "1973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c"
+    },
+    {
+      "python_hash_seed": "00",
+      "pickle_hex": "80059506000000000000008c023030942e",
+      "root_digest": "67c61e0f70ad5d3fc0eacb59744008ac6f2a8bd2edad43540a743eaf0fb4993c"
+    },
+    {
+      "python_hash_seed": "random",
+      "pickle_hex": "8005950a000000000000008c0672616e646f6d942e",
+      "root_digest": "fa1326fc0ad784c54e10f808051a77f999f7b675b12fba49cbef92b3e1a09cb7"
+    },
+    {
+      "python_hash_seed": "4294967295",
+      "pickle_hex": "8005950e000000000000008c0a34323934393637323935942e",
+      "root_digest": "670c2eca46f5f7e11b9dce5c3bd2ff0e9e19567fd45b50c2db5cc0c9aae470d9"
+    }
+  ],
+  "cases": [
+    {
+      "name": "spec_unsalted",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "762b2e7e1520febd3a0aedb7358e8602facf3924440e18538fce057e23bae91d",
+          "projected_hex": "8fce057e23bae91d",
+          "projected_decimal": "10362225831949560093",
+          "pickle_hex": "800595320000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474944e87942e"
+        },
+        {
+          "digest": "9e62b5a7ec298f33cb4c7d9e00b659874bb2432d23ad6879ad1746592a2b036b",
+          "projected_hex": "ad1746592a2b036b",
+          "projected_decimal": "12472515041799373675",
+          "pickle_hex": "80059532000000000000004320762b2e7e1520febd3a0aedb7358e8602facf3924440e18538fce057e23bae91d94284b054b064b074b0874944e87942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8
+      ],
+      "incorrect_low64_parent_digest": "22f70d17411c10aa544ecdac1d2df0fc1d7c7ac2d21efe1aebe32028620638c6"
+    },
+    {
+      "name": "single_token_tuple",
+      "block_size": 1,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "4e7493abc7315520e17ce180ee400439b7dc83e7406fb239462766705eb058c8",
+          "projected_hex": "462766705eb058c8",
+          "projected_decimal": "5055121739557656776",
+          "pickle_hex": "8005952b0000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c944b0785944e87942e"
+        }
+      ],
+      "token_ids": [
+        7
+      ]
+    },
+    {
+      "name": "two_token_tuple",
+      "block_size": 2,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "aa9e79304bb6921235ea2e187b25f9bb43d9044ec232e3d1c07d7e21e51e64ee",
+          "projected_hex": "c07d7e21e51e64ee",
+          "projected_decimal": "13870381111413990638",
+          "pickle_hex": "8005952d0000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c944b074b0886944e87942e"
+        }
+      ],
+      "token_ids": [
+        7,
+        8
+      ]
+    },
+    {
+      "name": "three_token_tuple",
+      "block_size": 3,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "6368e68a46c970c8ec2ebab3eb9d2fe7ddc2730165bb64d698aaed2907396794",
+          "projected_hex": "98aaed2907396794",
+          "projected_decimal": "11000865800276502420",
+          "pickle_hex": "8005952f0000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c944b074b084b0987944e87942e"
+        }
+      ],
+      "token_ids": [
+        7,
+        8,
+        9
+      ]
+    },
+    {
+      "name": "empty_extras_encode_as_none",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "569de0636f6064532b63312eab095a4577e72dc55286dbfb43821ec866309e47",
+          "projected_hex": "43821ec866309e47",
+          "projected_decimal": "4864484393570311751",
+          "pickle_hex": "800595320000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b0a4b144b1e4b2874944e87942e"
+        }
+      ],
+      "token_ids": [
+        10,
+        20,
+        30,
+        40
+      ]
+    },
+    {
+      "name": "signed_integer_boundaries",
+      "block_size": 8,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "6c9e5f944f0a93319b3ba9478115a9447de2f6d4ef1cd1c0b19a7ebd607353e8",
+          "projected_hex": "b19a7ebd607353e8",
+          "projected_decimal": "12797680642958775272",
+          "pickle_hex": "800595480000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284a000000804affffffff4b004bff4d00014dffff4a000001004affffff7f74944e87942e"
+        }
+      ],
+      "token_ids": [
+        -2147483648,
+        -1,
+        0,
+        255,
+        256,
+        65535,
+        65536,
+        2147483647
+      ]
+    },
+    {
+      "name": "utf8_multibyte",
+      "block_size": 4,
+      "lora_name": "模型-适配器",
+      "cache_salt": "盐值-🚀",
+      "expected": [
+        {
+          "digest": "cc1a2ab147f91a34070bb430e35dbc6ca6261a93b490a2307d0b4b31696a247a",
+          "projected_hex": "7d0b4b31696a247a",
+          "projected_decimal": "9010378155078853754",
+          "pickle_hex": "800595540000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948c10e6a8a1e59e8b2de98082e9858de599a8948c0be79b90e580bc2df09f9a8094869487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    },
+    {
+      "name": "lora_length_255",
+      "block_size": 4,
+      "lora_name": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "866b277c9d76457e35bd6a5dd3ec0d5b598faa9e36d108608f6e925149b1524b",
+          "projected_hex": "8f6e925149b1524b",
+          "projected_decimal": "10335359072688230987",
+          "pickle_hex": "800595350100000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948cff61616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616194859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    },
+    {
+      "name": "lora_length_256",
+      "block_size": 4,
+      "lora_name": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "0c934ab8aa543128da871a91a46387ed907ed3ca8b39e5c137da510f80a106df",
+          "projected_hex": "37da510f80a106df",
+          "projected_decimal": "4024618344033355487",
+          "pickle_hex": "800595390100000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b04749458000100006161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616161616194859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    },
+    {
+      "name": "salt_length_255",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": "sssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
+      "expected": [
+        {
+          "digest": "167d69abb219f81883e1fc5e554564bab043051f849914feb058487c8bffc398",
+          "projected_hex": "b058487c8bffc398",
+          "projected_decimal": "12706986048387793816",
+          "pickle_hex": "800595350100000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948cff73737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737394859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    },
+    {
+      "name": "salt_length_256",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": "ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
+      "expected": [
+        {
+          "digest": "0875d6e8c04ec7bb02928dc8f4b9e336aecb8adfae9078a9b6b54fe557b6857d",
+          "projected_hex": "b6b54fe557b6857d",
+          "projected_decimal": "13165516932125197693",
+          "pickle_hex": "800595390100000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b04749458000100007373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737373737394859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    },
+    {
+      "name": "lora_every_block",
+      "block_size": 4,
+      "lora_name": "adapter-A",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "5c5d9e04e03de9f2f4a9f38766c4d0fb0e207ccf5d2fb3b272c50117f336ae0c",
+          "projected_hex": "72c50117f336ae0c",
+          "projected_decimal": "8270017493112106508",
+          "pickle_hex": "8005953f0000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948c09616461707465722d4194859487942e"
+        },
+        {
+          "digest": "bde66cc24757972cc88e0fe62079d85934868c2733874ffa1c54ff679604f61a",
+          "projected_hex": "1c54ff679604f61a",
+          "projected_decimal": "2041537351469299226",
+          "pickle_hex": "8005953f0000000000000043205c5d9e04e03de9f2f4a9f38766c4d0fb0e207ccf5d2fb3b272c50117f336ae0c94284b054b064b074b0874948c09616461707465722d4194859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8
+      ]
+    },
+    {
+      "name": "salt_first_block_only",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": "tenant-salt",
+      "expected": [
+        {
+          "digest": "373c09c29ab08b91b13bf1a67e0a461990572d476016c064b6ba6b75c163ceb1",
+          "projected_hex": "b6ba6b75c163ceb1",
+          "projected_decimal": "13166954614070955697",
+          "pickle_hex": "800595410000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948c0b74656e616e742d73616c7494859487942e"
+        },
+        {
+          "digest": "141900dd6fe59d22764357a125ecf4d670923bb12ad705a520de0e98c7338d5d",
+          "projected_hex": "20de0e98c7338d5d",
+          "projected_decimal": "2368346503383321949",
+          "pickle_hex": "80059532000000000000004320373c09c29ab08b91b13bf1a67e0a461990572d476016c064b6ba6b75c163ceb194284b054b064b074b0874944e87942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8
+      ]
+    },
+    {
+      "name": "lora_then_salt",
+      "block_size": 4,
+      "lora_name": "adapter-A",
+      "cache_salt": "tenant-salt",
+      "expected": [
+        {
+          "digest": "dacd8a5addba8cf4b89589bedab04999b3676299a455ba3e085cc7777be6b328",
+          "projected_hex": "085cc7777be6b328",
+          "projected_decimal": "602575766154556200",
+          "pickle_hex": "8005954d0000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474948c09616461707465722d41948c0b74656e616e742d73616c7494869487942e"
+        },
+        {
+          "digest": "55575bd9b63ced6a3dc36c355afbb5f551599533795c26d27d8b5fc836681618",
+          "projected_hex": "7d8b5fc836681618",
+          "projected_decimal": "9046429590014662168",
+          "pickle_hex": "8005953f000000000000004320dacd8a5addba8cf4b89589bedab04999b3676299a455ba3e085cc7777be6b32894284b054b064b074b0874948c09616461707465722d4194859487942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8
+      ]
+    },
+    {
+      "name": "multi_block_chain",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "762b2e7e1520febd3a0aedb7358e8602facf3924440e18538fce057e23bae91d",
+          "projected_hex": "8fce057e23bae91d",
+          "projected_decimal": "10362225831949560093",
+          "pickle_hex": "800595320000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474944e87942e"
+        },
+        {
+          "digest": "9e62b5a7ec298f33cb4c7d9e00b659874bb2432d23ad6879ad1746592a2b036b",
+          "projected_hex": "ad1746592a2b036b",
+          "projected_decimal": "12472515041799373675",
+          "pickle_hex": "80059532000000000000004320762b2e7e1520febd3a0aedb7358e8602facf3924440e18538fce057e23bae91d94284b054b064b074b0874944e87942e"
+        },
+        {
+          "digest": "fd503875de30430b3c7e35f7ecca2fe995f2d55487bfef31707e09b175f917a0",
+          "projected_hex": "707e09b175f917a0",
+          "projected_decimal": "8105927037106591648",
+          "pickle_hex": "800595320000000000000043209e62b5a7ec298f33cb4c7d9e00b659874bb2432d23ad6879ad1746592a2b036b94284b094b0a4b0b4b0c74944e87942e"
+        },
+        {
+          "digest": "ac30858a66380467632841b758acc6cbe95ff9cfd7b9d226aa33de029248adff",
+          "projected_hex": "aa33de029248adff",
+          "projected_decimal": "12264390312885530111",
+          "pickle_hex": "80059532000000000000004320fd503875de30430b3c7e35f7ecca2fe995f2d55487bfef31707e09b175f917a094284b0d4b0e4b0f4b1074944e87942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8,
+        9,
+        10,
+        11,
+        12,
+        13,
+        14,
+        15,
+        16
+      ]
+    },
+    {
+      "name": "incomplete_tail",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "762b2e7e1520febd3a0aedb7358e8602facf3924440e18538fce057e23bae91d",
+          "projected_hex": "8fce057e23bae91d",
+          "projected_decimal": "10362225831949560093",
+          "pickle_hex": "800595320000000000000043201973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c94284b014b024b034b0474944e87942e"
+        }
+      ],
+      "token_ids": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6
+      ]
+    },
+    {
+      "name": "no_complete_block",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [],
+      "token_ids": [
+        1,
+        2,
+        3
+      ]
+    },
+    {
+      "name": "frame_boundary_token_stream",
+      "block_size": 22000,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "7f245129165bb9ba11747856a9a908740bf7b29c0033da4958281d87b252f469",
+          "projected_hex": "58281d87b252f469",
+          "projected_decimal": "6352359743055656041",
+          "pickle_len": 66062
+        }
+      ],
+      "token_ids_repeat": {
+        "value": 256,
+        "count": 22000
+      }
+    },
+    {
+      "name": "large_lora_large_payload",
+      "block_size": 4,
+      "lora_name": "",
+      "cache_salt": null,
+      "expected": [
+        {
+          "digest": "f30f906062e861807059e2099b689baf2c9484128a0c2fd40a5fdd1e1032f47f",
+          "projected_hex": "0a5fdd1e1032f47f",
+          "projected_decimal": "747559184357323903",
+          "pickle_len": 70077
+        }
+      ],
+      "lora_name_repeat": {
+        "value": "a",
+        "count": 70000
+      },
+      "token_ids": [
+        1,
+        2,
+        3,
+        4
+      ]
+    }
+  ]
+}
diff --git a/mooncake-conductor/tests/fixtures/verify_fixture_against_vllm.py b/mooncake-conductor/tests/fixtures/verify_fixture_against_vllm.py
new file mode 100644
index 0000000000..bba62974ab
--- /dev/null
+++ b/mooncake-conductor/tests/fixtures/verify_fixture_against_vllm.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Verifies hash_golden_vectors_sha256.json against the checked-out vLLM.
+
+Loads ``vllm/utils/hashing.py`` directly from a vLLM source checkout (without
+importing the heavy ``vllm`` package) and uses its ``sha256`` function as the
+normative oracle: SHA-256 over ``pickle.dumps(value, protocol=5)``.  The block
+value shapes mirror ``vllm/v1/core/kv_cache_utils.py::hash_block_tokens``.
+
+Usage:
+
+    python3 verify_fixture_against_vllm.py <path-to-vllm-checkout>
+
+Prints the Python/vLLM/protocol metadata it ran against and exits non-zero on
+any mismatch.
+"""
+
+import importlib.util
+import json
+import pickle
+import platform
+import subprocess
+import sys
+import types
+from pathlib import Path
+
+FIXTURE = Path(__file__).with_name("hash_golden_vectors_sha256.json")
+
+
+def load_vllm_hashing(checkout: Path):
+    hashing_py = checkout / "vllm" / "utils" / "hashing.py"
+    if not hashing_py.is_file():
+        raise SystemExit(f"vLLM hashing.py not found at {hashing_py}")
+    # hashing.py imports cbor2 at module scope; the sha256 recipe under test
+    # never touches it, so a stub is sufficient when cbor2 is absent.
+    if "cbor2" not in sys.modules:
+        try:
+            import cbor2  # noqa: F401
+        except ImportError:
+            sys.modules["cbor2"] = types.ModuleType("cbor2")
+    spec = importlib.util.spec_from_file_location("vllm_hashing", hashing_py)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.sha256
+
+
+def vllm_revision(checkout: Path) -> str:
+    try:
+        return subprocess.run(
+            ["git", "-C", str(checkout), "describe", "--tags", "--always"],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return "unknown"
+
+
+def expand_tokens(case: dict):
+    if "token_ids_repeat" in case:
+        spec = case["token_ids_repeat"]
+        return [spec["value"]] * spec["count"]
+    return list(case["token_ids"])
+
+
+def expand_lora(case: dict) -> str:
+    if "lora_name_repeat" in case:
+        spec = case["lora_name_repeat"]
+        return spec["value"] * spec["count"]
+    return case["lora_name"]
+
+
+def extras_for(lora_name: str, cache_salt, block_index: int):
+    keys = []
+    if lora_name:
+        keys.append(lora_name)
+    if block_index == 0 and cache_salt:
+        keys.append(cache_salt)
+    return tuple(keys) if keys else None
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        raise SystemExit(f"usage: {Path(__file__).name} <path-to-vllm-checkout>")
+    checkout = Path(sys.argv[1])
+    vllm_sha256 = load_vllm_hashing(checkout)
+    # The fixture carries non-ASCII cache salts, so the encoding is explicit
+    # rather than platform-dependent.
+    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
+
+    print(f"python: {platform.python_version()}")
+    print(f"pickle protocol: {pickle.HIGHEST_PROTOCOL}")
+    print(f"vLLM checkout: {checkout} ({vllm_revision(checkout)})")
+
+    failures = 0
+
+    def check(label: str, actual: str, expected: str) -> None:
+        nonlocal failures
+        if actual != expected:
+            failures += 1
+            print(f"MISMATCH {label}:\n  actual   {actual}\n  expected {expected}")
+
+    for vector in fixture["seed_root_vectors"]:
+        seed = vector["python_hash_seed"]
+        check(f"seed root {seed!r}", vllm_sha256(seed).hex(), vector["root_digest"])
+        check(
+            f"seed pickle bytes {seed!r}",
+            pickle.dumps(seed, protocol=5).hex(),
+            vector["pickle_hex"],
+        )
+
+    root = bytes.fromhex(fixture["profile"]["root_digest"])
+    for case in fixture["cases"]:
+        tokens = expand_tokens(case)
+        block_size = case["block_size"]
+        lora_name = expand_lora(case)
+        cache_salt = case["cache_salt"]
+        parent = root
+        for index, entry in enumerate(case["expected"]):
+            block_tokens = tuple(tokens[index * block_size : (index + 1) * block_size])
+            value = (
+                parent,
+                block_tokens,
+                extras_for(lora_name, cache_salt, index),
+            )
+            serialized = pickle.dumps(value, protocol=5)
+            digest = vllm_sha256(value).hex()
+            check(f"{case['name']} block {index}", digest, entry["digest"])
+            if "pickle_hex" in entry:
+                check(
+                    f"{case['name']} block {index} pickle bytes",
+                    serialized.hex(),
+                    entry["pickle_hex"],
+                )
+            else:
+                check(
+                    f"{case['name']} block {index} pickle length",
+                    str(len(serialized)),
+                    str(entry["pickle_len"]),
+                )
+            parent = bytes.fromhex(digest)
+
+    if failures:
+        print(f"{failures} mismatch(es)")
+        return 1
+    print("all seed roots, block digests, and serialized bytes match vLLM")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/mooncake-conductor/tests/json_uint64_test.cpp b/mooncake-conductor/tests/json_uint64_test.cpp
new file mode 100644
index 0000000000..78f25d94cf
--- /dev/null
+++ b/mooncake-conductor/tests/json_uint64_test.cpp
@@ -0,0 +1,62 @@
+// JSON library validation: /global_view serialises uint64 conductor
+// hashes as JSON numbers and must not lose precision above 2^53. This
+// locks in the jsoncpp choice; if this test ever fails after a jsoncpp
+// upgrade, the library must be replaced with one that preserves full
+// 64-bit integer precision.
+
+#include <gtest/gtest.h>
+#include <json/json.h>
+
+#include <cstdint>
+#include <sstream>
+
+namespace {
+
+std::string WriteCompact(const Json::Value& v) {
+    Json::StreamWriterBuilder wb;
+    wb["indentation"] = "";
+    return Json::writeString(wb, v);
+}
+
+Json::Value Parse(const std::string& s) {
+    Json::CharReaderBuilder rb;
+    Json::Value out;
+    std::string errs;
+    std::istringstream iss(s);
+    EXPECT_TRUE(Json::parseFromStream(rb, iss, &out, &errs)) << errs;
+    return out;
+}
+
+TEST(JsonUint64, BoundaryValuesRoundTrip) {
+    const uint64_t cases[] = {
+        0,
+        1,
+        (1ULL << 53) - 1,  // largest double-exact integer
+        (1ULL << 53),
+        (1ULL << 53) + 1,  // first value a double-based library corrupts
+        (1ULL << 63),
+        0xFFFFFFFFFFFFFFFFULL,  // uint64 max boundary value
+    };
+    for (const uint64_t v : cases) {
+        Json::Value doc;
+        doc["h"] = Json::Value::UInt64(v);
+        const std::string text = WriteCompact(doc);
+        const Json::Value back = Parse(text);
+        ASSERT_TRUE(back["h"].isUInt64()) << "value=" << v;
+        EXPECT_EQ(back["h"].asUInt64(), v) << "text=" << text;
+    }
+}
+
+// The /global_view hashmap serialises uint64 values inside objects keyed
+// by decimal strings; verify the exact shape survives a round-trip.
+TEST(JsonUint64, HashmapShapeRoundTrip) {
+    Json::Value mapping(Json::objectValue);
+    mapping["11185915045167517441"] =
+        Json::Value::UInt64(9404987693367201964ULL);
+    const std::string text = WriteCompact(mapping);
+    EXPECT_EQ(text, "{\"11185915045167517441\":9404987693367201964}");
+    const Json::Value back = Parse(text);
+    EXPECT_EQ(back["11185915045167517441"].asUInt64(), 9404987693367201964ULL);
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/model_context_test.cpp b/mooncake-conductor/tests/model_context_test.cpp
new file mode 100644
index 0000000000..785e137b22
--- /dev/null
+++ b/mooncake-conductor/tests/model_context_test.cpp
@@ -0,0 +1,107 @@
+#include <gtest/gtest.h>
+
+#include <concepts>
+#include <functional>
+#include <optional>
+#include <string>
+#include <unordered_map>
+
+#include "conductor/prefixindex/types.h"
+
+namespace {
+
+using mooncake::conductor::common::HashProfileConfig;
+using mooncake::conductor::common::ResolvedHashProfile;
+using mooncake::conductor::prefixindex::ContextKey;
+using mooncake::conductor::prefixindex::EngineRegistration;
+using mooncake::conductor::prefixindex::GpuMutation;
+
+template <typename T>
+concept HasInstanceId = requires(T value) { value.instance_id; };
+
+template <typename T>
+concept HasCacheSalt = requires(T value) { value.cache_salt; };
+
+template <typename T>
+concept HasAdditionalSalt = requires(T value) { value.additional_salt; };
+
+template <typename T>
+concept HasCacheGroups = requires(T value) { value.cache_groups; };
+
+template <typename T>
+concept HasPythonHashSeed = requires(T value) { value.python_hash_seed; };
+
+template <typename T>
+concept HasRootDigest = requires(T value) { value.root_digest; };
+
+static_assert(!HasInstanceId<ContextKey>);
+static_assert(!HasCacheSalt<ContextKey>);
+static_assert(!HasAdditionalSalt<ContextKey>);
+static_assert(!HasPythonHashSeed<ContextKey>);
+static_assert(!HasCacheGroups<EngineRegistration>);
+static_assert(!HasCacheGroups<GpuMutation>);
+static_assert(HasPythonHashSeed<HashProfileConfig>);
+static_assert(!HasRootDigest<HashProfileConfig>);
+static_assert(HasPythonHashSeed<ResolvedHashProfile>);
+static_assert(HasRootDigest<ResolvedHashProfile>);
+static_assert(std::same_as<decltype(EngineRegistration::cache_group),
+                           std::optional<int64_t>>);
+static_assert(
+    std::same_as<decltype(GpuMutation::cache_group), std::optional<int64_t>>);
+
+ContextKey BaseContext() {
+    return {.tenant_id = "tenant-a",
+            .model_name = "model-a",
+            .lora_name = "lora-a",
+            .block_size = 16};
+}
+
+TEST(ContextKey, IdenticalCopiesCompareAndHashEqual) {
+    const ContextKey first = BaseContext();
+    const ContextKey second = first;
+
+    EXPECT_EQ(first, second);
+    EXPECT_EQ(std::hash<ContextKey>{}(first), std::hash<ContextKey>{}(second));
+}
+
+struct FieldCase {
+    const char* name;
+    void (*change)(ContextKey*);
+};
+
+const FieldCase kFields[] = {
+    {"tenant_id", [](ContextKey* context) { context->tenant_id = "tenant-b"; }},
+    {"model_name",
+     [](ContextKey* context) { context->model_name = "model-b"; }},
+    {"lora_name", [](ContextKey* context) { context->lora_name = "lora-b"; }},
+    {"block_size", [](ContextKey* context) { context->block_size = 32; }},
+};
+
+TEST(ContextKey, ExactlyFourFieldsParticipateInEqualityAndLookup) {
+    std::unordered_map<ContextKey, int> contexts;
+    contexts.emplace(BaseContext(), 1);
+
+    for (const FieldCase& field : kFields) {
+        SCOPED_TRACE(field.name);
+        ContextKey changed = BaseContext();
+        field.change(&changed);
+        EXPECT_NE(changed, BaseContext());
+        EXPECT_FALSE(contexts.contains(changed));
+    }
+}
+
+TEST(ContextKey, OwnerAndRequestSaltLiveOutsideTheKey) {
+    ContextKey shared = BaseContext();
+    const std::string first_instance = "instance-a";
+    const std::string second_instance = "instance-b";
+    const std::string first_salt = "salt-a";
+    const std::string second_salt = "salt-b";
+
+    EXPECT_NE(first_instance, second_instance);
+    EXPECT_NE(first_salt, second_salt);
+    EXPECT_EQ(shared, BaseContext());
+    EXPECT_EQ(std::hash<ContextKey>{}(shared),
+              std::hash<ContextKey>{}(BaseContext()));
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/msg_decoder_test.cpp b/mooncake-conductor/tests/msg_decoder_test.cpp
new file mode 100644
index 0000000000..c56a45742a
--- /dev/null
+++ b/mooncake-conductor/tests/msg_decoder_test.cpp
@@ -0,0 +1,1278 @@
+// Tests for the current vLLM msgspec and Mooncake publisher map protocols.
+
+#include <gtest/gtest.h>
+#include <msgpack.hpp>
+
+#include <array>
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <variant>
+#include <vector>
+
+#include "conductor/zmq/msg_decoder.h"
+#include "conductor/kvevent/object_key_parser.h"
+
+namespace {
+
+using mooncake::conductor::kvevent::ParsedSglangObjectKey;
+using mooncake::conductor::kvevent::ParseSglangObjectKey;
+using mooncake::conductor::kvevent::ParseVllmObjectKey;
+using mooncake::conductor::zmq::DecodeMooncakeEventBatch;
+using mooncake::conductor::zmq::DecodeSglangEventBatch;
+using mooncake::conductor::zmq::DecodeVllmEventBatch;
+using mooncake::conductor::zmq::MooncakeClearedEvent;
+using mooncake::conductor::zmq::MooncakeEventFields;
+using mooncake::conductor::zmq::MooncakeRemovedEvent;
+using mooncake::conductor::zmq::MooncakeStoredEvent;
+using mooncake::conductor::zmq::SglangClearedEvent;
+using mooncake::conductor::zmq::SglangEventBatch;
+using mooncake::conductor::zmq::SglangRemovedEvent;
+using mooncake::conductor::zmq::SglangStoredEvent;
+using mooncake::conductor::zmq::VllmClearedEvent;
+using mooncake::conductor::zmq::VllmRemovedEvent;
+using mooncake::conductor::zmq::VllmStoredEvent;
+
+using Packer = msgpack::packer<std::stringstream>;
+
+constexpr int64_t kMooncakeTimestamp = 1700000000123LL;
+constexpr int64_t kMooncakeDpRank = 2;
+constexpr uint64_t kProjectedHash = 0x18191a1b1c1d1e1fULL;
+
+std::string BytesFromHex(std::string_view hex) {
+    if (hex.size() % 2 != 0) {
+        throw std::invalid_argument("hex input must have an even length");
+    }
+    const auto nibble = [](char value) -> uint8_t {
+        if (value >= '0' && value <= '9') {
+            return static_cast<uint8_t>(value - '0');
+        }
+        if (value >= 'a' && value <= 'f') {
+            return static_cast<uint8_t>(value - 'a' + 10);
+        }
+        if (value >= 'A' && value <= 'F') {
+            return static_cast<uint8_t>(value - 'A' + 10);
+        }
+        throw std::invalid_argument("invalid hex digit");
+    };
+
+    std::string bytes;
+    bytes.reserve(hex.size() / 2);
+    for (size_t index = 0; index < hex.size(); index += 2) {
+        bytes.push_back(static_cast<char>((nibble(hex[index]) << 4) |
+                                          nibble(hex[index + 1])));
+    }
+    return bytes;
+}
+
+template <typename PackEvents>
+std::string PackVllmBatch(uint32_t event_count, PackEvents pack_events,
+                          std::optional<int64_t> dp_rank = 3) {
+    std::stringstream buffer;
+    Packer packer(buffer);
+    packer.pack_array(3);
+    packer.pack_double(1.25);
+    packer.pack_array(event_count);
+    pack_events(packer);
+    if (dp_rank.has_value()) {
+        packer.pack(*dp_rank);
+    } else {
+        packer.pack_nil();
+    }
+    return buffer.str();
+}
+
+template <typename PackEvents>
+std::string PackMooncakeBatch(
+    uint32_t event_count, PackEvents pack_events,
+    std::optional<int64_t> dp_rank = kMooncakeDpRank) {
+    std::stringstream buffer;
+    Packer packer(buffer);
+    packer.pack_array(3);
+    packer.pack(kMooncakeTimestamp);
+    packer.pack_array(event_count);
+    pack_events(packer);
+    if (dp_rank.has_value()) {
+        packer.pack(*dp_rank);
+    } else {
+        packer.pack_nil();
+    }
+    return buffer.str();
+}
+
+void PackBinary(Packer& packer, const std::vector<uint8_t>& bytes) {
+    packer.pack_bin(bytes.size());
+    packer.pack_bin_body(reinterpret_cast<const char*>(bytes.data()),
+                         bytes.size());
+}
+
+void PackVllmStored(Packer& packer, bool include_unknown = false) {
+    packer.pack_map(include_unknown ? 9 : 8);
+    packer.pack("type");
+    packer.pack("BlockStored");
+    packer.pack("block_hashes");
+    packer.pack_array(1);
+    packer.pack_uint64(42);
+    packer.pack("parent_block_hash");
+    packer.pack_nil();
+    packer.pack("token_ids");
+    packer.pack_array(2);
+    packer.pack_int32(1);
+    packer.pack_int32(2);
+    packer.pack("block_size");
+    packer.pack_int64(2);
+    packer.pack("lora_id");
+    packer.pack_nil();
+    packer.pack("medium");
+    packer.pack("GPU");
+    packer.pack("lora_name");
+    packer.pack_nil();
+    if (include_unknown) {
+        packer.pack("future_store_metadata");
+        packer.pack_map(1);
+        packer.pack("version");
+        packer.pack_int64(2);
+    }
+}
+
+void PackVllmRemoved(Packer& packer) {
+    packer.pack_map(4);
+    packer.pack("type");
+    packer.pack("BlockRemoved");
+    packer.pack("block_hashes");
+    packer.pack_array(1);
+    packer.pack_uint64(42);
+    packer.pack("medium");
+    packer.pack("GPU");
+    packer.pack("group_idx");
+    packer.pack_int64(0);
+}
+
+void PackVllmCleared(Packer& packer) {
+    packer.pack_map(1);
+    packer.pack("type");
+    packer.pack("AllBlocksCleared");
+}
+
+void PackMooncakeCommon(Packer& packer, uint64_t event_id,
+                        std::string_view event_type,
+                        std::string_view legacy_type, std::string_view medium) {
+    packer.pack("event_id");
+    packer.pack_uint64(event_id);
+    packer.pack("timestamp");
+    packer.pack(kMooncakeTimestamp);
+    packer.pack("event_type");
+    packer.pack(std::string(event_type));
+    packer.pack("type");
+    packer.pack(std::string(legacy_type));
+    packer.pack("model_name");
+    packer.pack("model-a");
+    packer.pack("block_size");
+    packer.pack_int64(16);
+    packer.pack("additional_salt");
+    packer.pack_nil();
+    packer.pack("lora_name");
+    packer.pack_nil();
+    packer.pack("tenant_id");
+    packer.pack("tenant-a");
+    packer.pack("backend_id");
+    packer.pack("backend-a");
+    packer.pack("medium");
+    if (medium.empty()) {
+        packer.pack_nil();
+    } else {
+        packer.pack(std::string(medium));
+    }
+    packer.pack("dp_rank");
+    packer.pack(kMooncakeDpRank);
+}
+
+void PackMooncakeObject(Packer& packer, std::string_view object_key) {
+    packer.pack("group_id");
+    packer.pack("0");
+    packer.pack("object_key");
+    packer.pack(std::string(object_key));
+    packer.pack("connector_block_hash");
+    packer.pack(
+        "000102030405060708090a0b0c0d0e0f"
+        "101112131415161718191a1b1c1d1e1f");
+    packer.pack("cache_prefix");
+    packer.pack("prefix-a");
+    packer.pack("tp_rank");
+    packer.pack_int64(1);
+    packer.pack("head_or_tp_rank");
+    packer.pack_int64(1);
+    packer.pack("pcp_rank");
+    packer.pack_int64(0);
+    packer.pack("dcp_rank");
+    packer.pack_int64(0);
+    packer.pack("pp_rank");
+    packer.pack_int64(3);
+    packer.pack("layer_id");
+    packer.pack_int64(31);
+    packer.pack("seq_hashes");
+    packer.pack_array(1);
+    packer.pack_uint64(kProjectedHash);
+    packer.pack("block_hashes");
+    packer.pack_array(1);
+    packer.pack_uint64(kProjectedHash);
+}
+
+void PackMooncakeStored(Packer& packer, bool include_unknown = false) {
+    // Default publisher configuration emits legacy compatibility fields and
+    // all connector metadata represented by this deterministic context.
+    packer.pack_map(include_unknown ? 29 : 28);
+    PackMooncakeCommon(packer, 7, "stored", "BlockStored", "cpu");
+    PackMooncakeObject(packer, "object-a");
+    packer.pack("base_block_idx");
+    packer.pack_nil();
+    packer.pack("parent_hash");
+    packer.pack_nil();
+    packer.pack("token_ids");
+    packer.pack_nil();
+    packer.pack("parent_block_hash");
+    packer.pack_nil();
+    if (include_unknown) {
+        packer.pack("future_connector_metadata");
+        packer.pack_true();
+    }
+}
+
+void PackMooncakeRemoved(Packer& packer) {
+    packer.pack_map(25);
+    PackMooncakeCommon(packer, 8, "removed", "BlockRemoved", "disk");
+    PackMooncakeObject(packer, "object-a");
+    packer.pack("base_block_idx");
+    packer.pack_nil();
+}
+
+void PackMooncakeCleared(Packer& packer, bool include_unknown = false) {
+    packer.pack_map(include_unknown ? 13 : 12);
+    PackMooncakeCommon(packer, 9, "cleared", "AllBlocksCleared", "");
+    if (include_unknown) {
+        packer.pack("future_clear_metadata");
+        packer.pack("ignored");
+    }
+}
+
+template <typename Event>
+const Event* GetEvent(const mooncake::conductor::zmq::DecodedEvent<
+                      mooncake::conductor::zmq::VllmEvent>& decoded) {
+    if (!decoded.event.has_value()) {
+        return nullptr;
+    }
+    return std::get_if<Event>(&*decoded.event);
+}
+
+template <typename Event>
+const Event* GetEvent(const mooncake::conductor::zmq::DecodedEvent<
+                      mooncake::conductor::zmq::MooncakeEvent>& decoded) {
+    if (!decoded.event.has_value()) {
+        return nullptr;
+    }
+    return std::get_if<Event>(&*decoded.event);
+}
+
+void ExpectMooncakeCommon(const MooncakeEventFields& fields, uint64_t event_id,
+                          std::string_view medium) {
+    EXPECT_EQ(fields.event_id, event_id);
+    EXPECT_EQ(fields.timestamp_milliseconds, kMooncakeTimestamp);
+    ASSERT_TRUE(fields.model_name.has_value());
+    EXPECT_EQ(*fields.model_name, "model-a");
+    ASSERT_TRUE(fields.block_size.has_value());
+    EXPECT_EQ(*fields.block_size, 16);
+    EXPECT_FALSE(fields.additional_salt.has_value());
+    EXPECT_FALSE(fields.lora_name.has_value());
+    EXPECT_EQ(fields.tenant_id, "tenant-a");
+    EXPECT_EQ(fields.backend_id, "backend-a");
+    if (medium.empty()) {
+        EXPECT_FALSE(fields.medium.has_value());
+    } else {
+        ASSERT_TRUE(fields.medium.has_value());
+        EXPECT_EQ(*fields.medium, medium);
+    }
+    EXPECT_EQ(fields.data_parallel_rank, kMooncakeDpRank);
+}
+
+void ExpectErrorContains(const std::string& error, std::string_view expected) {
+    EXPECT_NE(error.find(expected), std::string::npos) << error;
+}
+
+TEST(DecodeVllmEventBatch, DecodesCanonicalMsgspecProducerFixture) {
+    // Captured from vLLM's msgspec encoder in distributed/kv_events.py.
+    const std::string payload = BytesFromHex(
+        "93cb3ff40000000000009389a474797065ab426c6f636b53746f726564ac626c"
+        "6f636b5f686173686573912ab1706172656e745f626c6f636b5f68617368c0a9"
+        "746f6b656e5f696473920102aa626c6f636b5f73697a6502a76c6f72615f6964"
+        "c0a66d656469756da3475055a96c6f72615f6e616d65c0a967726f75705f6964"
+        "780084a474797065ac426c6f636b52656d6f766564ac626c6f636b5f68617368"
+        "6573912aa66d656469756da3475055a967726f75705f6964780081a474797065"
+        "b0416c6c426c6f636b73436c656172656403");
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_DOUBLE_EQ(result.batch.timestamp_seconds, 1.25);
+    ASSERT_TRUE(result.batch.data_parallel_rank.has_value());
+    EXPECT_EQ(*result.batch.data_parallel_rank, 3);
+    ASSERT_EQ(result.batch.events.size(), 3u);
+
+    const auto* stored = GetEvent<VllmStoredEvent>(result.batch.events[0]);
+    ASSERT_NE(stored, nullptr) << result.batch.events[0].error;
+    ASSERT_EQ(stored->block_hashes.size(), 1u);
+    ASSERT_TRUE(std::holds_alternative<uint64_t>(stored->block_hashes[0]));
+    EXPECT_EQ(std::get<uint64_t>(stored->block_hashes[0]), 42u);
+    EXPECT_FALSE(stored->parent_block_hash.has_value());
+    ASSERT_TRUE(stored->token_ids.has_value());
+    EXPECT_EQ(*stored->token_ids, (std::vector<int32_t>{1, 2}));
+    EXPECT_EQ(stored->block_size, 2);
+    EXPECT_FALSE(stored->lora_id.has_value());
+    ASSERT_TRUE(stored->medium.has_value());
+    EXPECT_EQ(*stored->medium, "GPU");
+    EXPECT_FALSE(stored->lora_name.has_value());
+    ASSERT_TRUE(stored->group_idx.has_value());
+    EXPECT_EQ(*stored->group_idx, 0);
+
+    const auto* removed = GetEvent<VllmRemovedEvent>(result.batch.events[1]);
+    ASSERT_NE(removed, nullptr) << result.batch.events[1].error;
+    ASSERT_EQ(removed->block_hashes.size(), 1u);
+    EXPECT_EQ(std::get<uint64_t>(removed->block_hashes[0]), 42u);
+    ASSERT_TRUE(removed->medium.has_value());
+    EXPECT_EQ(*removed->medium, "GPU");
+    ASSERT_TRUE(removed->group_idx.has_value());
+    EXPECT_EQ(*removed->group_idx, 0);
+
+    EXPECT_NE(GetEvent<VllmClearedEvent>(result.batch.events[2]), nullptr)
+        << result.batch.events[2].error;
+}
+
+TEST(DecodeVllmEventBatch, PreservesIntegerAndBinaryHashesAndNullableFields) {
+    std::vector<uint8_t> full_hash(32);
+    for (size_t index = 0; index < full_hash.size(); ++index) {
+        full_hash[index] = static_cast<uint8_t>(index);
+    }
+    const std::string payload = PackVllmBatch(
+        1,
+        [&](Packer& packer) {
+            packer.pack_map(13);
+            packer.pack("type");
+            packer.pack("BlockStored");
+            packer.pack("block_hashes");
+            packer.pack_array(2);
+            packer.pack_uint64(std::numeric_limits<uint64_t>::max());
+            PackBinary(packer, full_hash);
+            packer.pack("parent_block_hash");
+            PackBinary(packer, full_hash);
+            packer.pack("token_ids");
+            packer.pack_nil();
+            packer.pack("block_size");
+            packer.pack_int64(16);
+            packer.pack("lora_id");
+            packer.pack_nil();
+            packer.pack("medium");
+            packer.pack_nil();
+            packer.pack("lora_name");
+            packer.pack_nil();
+            packer.pack("extra_keys");
+            packer.pack_array(2);
+            packer.pack_nil();
+            packer.pack_array(1);
+            packer.pack("future-key");
+            packer.pack("group_idx");
+            packer.pack_nil();
+            packer.pack("kv_cache_spec_kind");
+            packer.pack("full");
+            packer.pack("kv_cache_spec_sliding_window");
+            packer.pack_nil();
+            packer.pack("future_store_metadata");
+            packer.pack_true();
+        },
+        std::nullopt);
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_FALSE(result.batch.data_parallel_rank.has_value());
+    ASSERT_EQ(result.batch.events.size(), 1u);
+    const auto* stored = GetEvent<VllmStoredEvent>(result.batch.events[0]);
+    ASSERT_NE(stored, nullptr) << result.batch.events[0].error;
+    ASSERT_EQ(stored->block_hashes.size(), 2u);
+    EXPECT_EQ(std::get<uint64_t>(stored->block_hashes[0]),
+              std::numeric_limits<uint64_t>::max());
+    EXPECT_EQ(std::get<std::vector<uint8_t>>(stored->block_hashes[1]),
+              full_hash);
+    ASSERT_TRUE(stored->parent_block_hash.has_value());
+    EXPECT_EQ(std::get<std::vector<uint8_t>>(*stored->parent_block_hash),
+              full_hash);
+    EXPECT_FALSE(stored->token_ids.has_value());
+    EXPECT_FALSE(stored->medium.has_value());
+    EXPECT_TRUE(stored->extra_keys_present);
+    EXPECT_FALSE(stored->group_idx.has_value());
+    ASSERT_TRUE(stored->kv_cache_spec_kind.has_value());
+    EXPECT_EQ(*stored->kv_cache_spec_kind, "full");
+    EXPECT_FALSE(stored->kv_cache_spec_sliding_window.has_value());
+}
+
+TEST(DecodeMooncakeEventBatch, DecodesDeterministicPublisherMapFixture) {
+    const std::string payload = PackMooncakeBatch(3, [](Packer& packer) {
+        PackMooncakeStored(packer);
+        PackMooncakeRemoved(packer);
+        PackMooncakeCleared(packer);
+    });
+
+    const auto result =
+        DecodeMooncakeEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_EQ(result.batch.timestamp_milliseconds, kMooncakeTimestamp);
+    ASSERT_TRUE(result.batch.data_parallel_rank.has_value());
+    EXPECT_EQ(*result.batch.data_parallel_rank, kMooncakeDpRank);
+    ASSERT_EQ(result.batch.events.size(), 3u);
+
+    const auto* stored = GetEvent<MooncakeStoredEvent>(result.batch.events[0]);
+    ASSERT_NE(stored, nullptr) << result.batch.events[0].error;
+    ExpectMooncakeCommon(stored->fields, 7, "cpu");
+    ASSERT_TRUE(stored->object.group_id.has_value());
+    EXPECT_EQ(*stored->object.group_id, "0");
+    ASSERT_TRUE(stored->object.object_key.has_value());
+    EXPECT_EQ(*stored->object.object_key, "object-a");
+    ASSERT_TRUE(stored->object.connector_block_hash.has_value());
+    EXPECT_EQ(*stored->object.connector_block_hash,
+              "000102030405060708090a0b0c0d0e0f"
+              "101112131415161718191a1b1c1d1e1f");
+    ASSERT_TRUE(stored->object.cache_prefix.has_value());
+    EXPECT_EQ(*stored->object.cache_prefix, "prefix-a");
+    EXPECT_EQ(stored->object.seq_hashes,
+              (std::vector<uint64_t>{kProjectedHash}));
+    ASSERT_TRUE(stored->object.legacy_block_hashes.has_value());
+    EXPECT_EQ(*stored->object.legacy_block_hashes, stored->object.seq_hashes);
+    ASSERT_TRUE(stored->object.tp_rank.has_value());
+    EXPECT_EQ(*stored->object.tp_rank, 1);
+    ASSERT_TRUE(stored->object.head_or_tp_rank.has_value());
+    EXPECT_EQ(*stored->object.head_or_tp_rank, 1);
+    ASSERT_TRUE(stored->object.pcp_rank.has_value());
+    EXPECT_EQ(*stored->object.pcp_rank, 0);
+    ASSERT_TRUE(stored->object.dcp_rank.has_value());
+    EXPECT_EQ(*stored->object.dcp_rank, 0);
+    ASSERT_TRUE(stored->object.pp_rank.has_value());
+    EXPECT_EQ(*stored->object.pp_rank, 3);
+    ASSERT_TRUE(stored->object.layer_id.has_value());
+    EXPECT_EQ(*stored->object.layer_id, 31);
+    EXPECT_FALSE(stored->object.base_block_idx.has_value());
+    EXPECT_FALSE(stored->parent_hash.has_value());
+    EXPECT_FALSE(stored->token_ids.has_value());
+
+    const auto* removed =
+        GetEvent<MooncakeRemovedEvent>(result.batch.events[1]);
+    ASSERT_NE(removed, nullptr) << result.batch.events[1].error;
+    ExpectMooncakeCommon(removed->fields, 8, "disk");
+    ASSERT_TRUE(removed->object.object_key.has_value());
+    EXPECT_EQ(*removed->object.object_key, "object-a");
+    EXPECT_EQ(removed->object.seq_hashes,
+              (std::vector<uint64_t>{kProjectedHash}));
+    EXPECT_FALSE(removed->object.base_block_idx.has_value());
+
+    const auto* cleared =
+        GetEvent<MooncakeClearedEvent>(result.batch.events[2]);
+    ASSERT_NE(cleared, nullptr) << result.batch.events[2].error;
+    ExpectMooncakeCommon(cleared->fields, 9, "");
+}
+
+TEST(DecodeMooncakeEventBatch, AcceptsUnknownKeysAndNullableBatchDpRank) {
+    const std::string payload = PackMooncakeBatch(
+        2,
+        [](Packer& packer) {
+            PackMooncakeStored(packer, true);
+            PackMooncakeCleared(packer, true);
+        },
+        std::nullopt);
+
+    const auto result =
+        DecodeMooncakeEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_FALSE(result.batch.data_parallel_rank.has_value());
+    ASSERT_EQ(result.batch.events.size(), 2u);
+    EXPECT_NE(GetEvent<MooncakeStoredEvent>(result.batch.events[0]), nullptr)
+        << result.batch.events[0].error;
+    EXPECT_NE(GetEvent<MooncakeClearedEvent>(result.batch.events[1]), nullptr)
+        << result.batch.events[1].error;
+}
+
+TEST(DecodeVllmEventBatch, RejectsMalformedEnvelopeMetadata) {
+    struct Case {
+        std::string name;
+        std::string payload;
+        std::string error;
+    };
+    std::vector<Case> cases;
+
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_map(0);
+        cases.push_back(
+            {"map root", buffer.str(), "three-element array envelope"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(2);
+        packer.pack_double(1.25);
+        packer.pack_array(0);
+        cases.push_back({"two elements", buffer.str(), "three-element"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(4);
+        packer.pack_double(1.25);
+        packer.pack_array(0);
+        packer.pack_nil();
+        packer.pack_nil();
+        cases.push_back({"four elements", buffer.str(), "three-element"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_int64(1);
+        packer.pack_array(0);
+        packer.pack_nil();
+        cases.push_back(
+            {"integer timestamp", buffer.str(), "timestamp must be a float"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_double(std::numeric_limits<double>::infinity());
+        packer.pack_array(0);
+        packer.pack_nil();
+        cases.push_back(
+            {"non-finite timestamp", buffer.str(), "must be finite"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_double(1.25);
+        packer.pack("not-events");
+        packer.pack_nil();
+        cases.push_back(
+            {"events not array", buffer.str(), "events must be an array"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_double(1.25);
+        packer.pack_array(0);
+        packer.pack_int64(-1);
+        cases.push_back({"negative DP", buffer.str(), "non-negative or nil"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_double(1.25);
+        packer.pack_array(0);
+        packer.pack("rank");
+        cases.push_back({"string DP", buffer.str(), "data_parallel_rank"});
+    }
+
+    for (const auto& test : cases) {
+        SCOPED_TRACE(test.name);
+        const auto result =
+            DecodeVllmEventBatch(test.payload.data(), test.payload.size());
+        EXPECT_FALSE(result.ok);
+        ExpectErrorContains(result.error, test.error);
+        EXPECT_TRUE(result.batch.events.empty());
+    }
+}
+
+TEST(DecodeMooncakeEventBatch, RejectsMalformedEnvelopeMetadata) {
+    struct Case {
+        std::string name;
+        std::string payload;
+        std::string error;
+    };
+    std::vector<Case> cases;
+
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack("not-an-envelope");
+        cases.push_back(
+            {"string root", buffer.str(), "three-element array envelope"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(2);
+        packer.pack(kMooncakeTimestamp);
+        packer.pack_array(0);
+        cases.push_back({"two elements", buffer.str(), "three-element"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(4);
+        packer.pack(kMooncakeTimestamp);
+        packer.pack_array(0);
+        packer.pack_nil();
+        packer.pack_nil();
+        cases.push_back({"four elements", buffer.str(), "three-element"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_double(1.25);
+        packer.pack_array(0);
+        packer.pack_nil();
+        cases.push_back({"float timestamp", buffer.str(),
+                         "timestamp must be a non-negative integer"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack_int64(-1);
+        packer.pack_array(0);
+        packer.pack_nil();
+        cases.push_back({"negative timestamp", buffer.str(),
+                         "timestamp must be a non-negative integer"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack(kMooncakeTimestamp);
+        packer.pack_map(0);
+        packer.pack_nil();
+        cases.push_back(
+            {"events not array", buffer.str(), "events must be an array"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack(kMooncakeTimestamp);
+        packer.pack_array(0);
+        packer.pack_int64(-1);
+        cases.push_back({"negative DP", buffer.str(), "non-negative or nil"});
+    }
+    {
+        std::stringstream buffer;
+        Packer packer(buffer);
+        packer.pack_array(3);
+        packer.pack(kMooncakeTimestamp);
+        packer.pack_array(0);
+        packer.pack_false();
+        cases.push_back({"boolean DP", buffer.str(), "data_parallel_rank"});
+    }
+
+    for (const auto& test : cases) {
+        SCOPED_TRACE(test.name);
+        const auto result =
+            DecodeMooncakeEventBatch(test.payload.data(), test.payload.size());
+        EXPECT_FALSE(result.ok);
+        ExpectErrorContains(result.error, test.error);
+        EXPECT_TRUE(result.batch.events.empty());
+    }
+}
+
+TEST(DecodeVllmEventBatch,
+     RejectsPositionalDuplicateMissingWrongTypeAndUnknownTagLocally) {
+    const std::string payload = PackVllmBatch(6, [](Packer& packer) {
+        packer.pack_array(1);
+        packer.pack("BlockStored");
+
+        packer.pack_map(2);
+        packer.pack("type");
+        packer.pack("BlockStored");
+        packer.pack("type");
+        packer.pack("BlockStored");
+
+        packer.pack_map(1);
+        packer.pack("unrecognized_type");
+        packer.pack("BlockStored");
+
+        packer.pack_map(1);
+        packer.pack("type");
+        packer.pack_int64(7);
+
+        packer.pack_map(1);
+        packer.pack("type");
+        packer.pack("BlockUpdated");
+
+        PackVllmCleared(packer);
+    });
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 6u);
+    const std::array<std::string_view, 5> errors = {
+        "expected event map", "duplicate recognized key: type",
+        "missing required key: type", "invalid type: expected string",
+        "unknown vLLM event tag"};
+    for (size_t index = 0; index < errors.size(); ++index) {
+        SCOPED_TRACE(index);
+        EXPECT_FALSE(result.batch.events[index].ok());
+        ExpectErrorContains(result.batch.events[index].error, errors[index]);
+    }
+    EXPECT_NE(GetEvent<VllmClearedEvent>(result.batch.events[5]), nullptr)
+        << result.batch.events[5].error;
+}
+
+TEST(DecodeVllmEventBatch,
+     RejectsStoreOnlyRecognizedFieldsOnRemovedAndAllowsUnknownKeys) {
+    constexpr std::array<std::string_view, 8> kStoreOnlyFields = {
+        "parent_block_hash",  "token_ids",
+        "block_size",         "lora_id",
+        "lora_name",          "extra_keys",
+        "kv_cache_spec_kind", "kv_cache_spec_sliding_window",
+    };
+    const std::string payload =
+        PackVllmBatch(kStoreOnlyFields.size() + 1, [&](Packer& packer) {
+            for (std::string_view field : kStoreOnlyFields) {
+                packer.pack_map(5);
+                packer.pack("type");
+                packer.pack("BlockRemoved");
+                packer.pack("block_hashes");
+                packer.pack_array(1);
+                packer.pack_uint64(42);
+                packer.pack("medium");
+                packer.pack("GPU");
+                packer.pack("group_idx");
+                packer.pack_int64(0);
+                packer.pack(std::string(field));
+                packer.pack_nil();
+            }
+
+            packer.pack_map(5);
+            packer.pack("type");
+            packer.pack("BlockRemoved");
+            packer.pack("block_hashes");
+            packer.pack_array(1);
+            packer.pack_uint64(42);
+            packer.pack("medium");
+            packer.pack("GPU");
+            packer.pack("group_idx");
+            packer.pack_int64(0);
+            packer.pack("future_remove_metadata");
+            packer.pack_map(1);
+            packer.pack("version");
+            packer.pack_int64(2);
+        });
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), kStoreOnlyFields.size() + 1);
+    for (size_t index = 0; index < kStoreOnlyFields.size(); ++index) {
+        SCOPED_TRACE(index);
+        EXPECT_FALSE(result.batch.events[index].ok());
+        ExpectErrorContains(result.batch.events[index].error,
+                            "BlockRemoved contains recognized key: " +
+                                std::string(kStoreOnlyFields[index]));
+    }
+    EXPECT_NE(GetEvent<VllmRemovedEvent>(result.batch.events.back()), nullptr)
+        << result.batch.events.back().error;
+}
+
+TEST(DecodeVllmEventBatch,
+     RejectsInvalidExtraKeysEntriesAndCardinalityLocally) {
+    const std::string payload = PackVllmBatch(3, [](Packer& packer) {
+        const auto pack_stored_prefix = [&](uint32_t block_count) {
+            packer.pack_map(9);
+            packer.pack("type");
+            packer.pack("BlockStored");
+            packer.pack("block_hashes");
+            packer.pack_array(block_count);
+            for (uint32_t index = 0; index < block_count; ++index) {
+                packer.pack_uint64(42 + index);
+            }
+            packer.pack("parent_block_hash");
+            packer.pack_nil();
+            packer.pack("token_ids");
+            packer.pack_nil();
+            packer.pack("block_size");
+            packer.pack_int64(16);
+            packer.pack("lora_id");
+            packer.pack_nil();
+            packer.pack("medium");
+            packer.pack("GPU");
+            packer.pack("lora_name");
+            packer.pack_nil();
+            packer.pack("extra_keys");
+        };
+
+        pack_stored_prefix(1);
+        packer.pack_array(1);
+        packer.pack("not-an-extra-key-tuple");
+
+        pack_stored_prefix(2);
+        packer.pack_array(1);
+        packer.pack_nil();
+
+        PackVllmCleared(packer);
+    });
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 3u);
+    EXPECT_FALSE(result.batch.events[0].ok());
+    ExpectErrorContains(result.batch.events[0].error,
+                        "invalid extra_keys: element 0: expected array or nil");
+    EXPECT_FALSE(result.batch.events[1].ok());
+    ExpectErrorContains(
+        result.batch.events[1].error,
+        "invalid extra_keys: expected one entry per block hash");
+    EXPECT_NE(GetEvent<VllmClearedEvent>(result.batch.events[2]), nullptr)
+        << result.batch.events[2].error;
+}
+
+TEST(DecodeMooncakeEventBatch,
+     RejectsPositionalDuplicateMissingWrongTypeAndUnknownTagLocally) {
+    const std::string payload = PackMooncakeBatch(6, [](Packer& packer) {
+        packer.pack_array(1);
+        packer.pack("BlockStoreEvent");
+
+        packer.pack_map(2);
+        packer.pack("event_type");
+        packer.pack("stored");
+        packer.pack("event_type");
+        packer.pack("stored");
+
+        packer.pack_map(1);
+        packer.pack("unrecognized_event_type");
+        packer.pack("stored");
+
+        packer.pack_map(1);
+        packer.pack("event_type");
+        packer.pack_int64(7);
+
+        packer.pack_map(1);
+        packer.pack("event_type");
+        packer.pack("updated");
+
+        PackMooncakeCleared(packer);
+    });
+
+    const auto result =
+        DecodeMooncakeEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 6u);
+    const std::array<std::string_view, 5> errors = {
+        "expected event map", "duplicate recognized key: event_type",
+        "missing required key: event_type",
+        "invalid event_type: expected string", "unknown Mooncake event tag"};
+    for (size_t index = 0; index < errors.size(); ++index) {
+        SCOPED_TRACE(index);
+        EXPECT_FALSE(result.batch.events[index].ok());
+        ExpectErrorContains(result.batch.events[index].error, errors[index]);
+    }
+    EXPECT_NE(GetEvent<MooncakeClearedEvent>(result.batch.events[5]), nullptr)
+        << result.batch.events[5].error;
+}
+
+TEST(DecodeVllmEventBatch, MalformedMiddleAndFinalEventsRemainIsolated) {
+    const std::string middle = PackVllmBatch(3, [](Packer& packer) {
+        PackVllmStored(packer, true);
+        packer.pack_map(4);
+        packer.pack("type");
+        packer.pack("BlockRemoved");
+        packer.pack("block_hashes");
+        packer.pack_array(1);
+        packer.pack_uint64(42);
+        packer.pack("medium");
+        packer.pack("GPU");
+        packer.pack("medium");
+        packer.pack("CPU");
+        PackVllmRemoved(packer);
+    });
+    const auto middle_result =
+        DecodeVllmEventBatch(middle.data(), middle.size());
+    ASSERT_TRUE(middle_result.ok) << middle_result.error;
+    ASSERT_EQ(middle_result.batch.events.size(), 3u);
+    EXPECT_NE(GetEvent<VllmStoredEvent>(middle_result.batch.events[0]), nullptr)
+        << middle_result.batch.events[0].error;
+    EXPECT_FALSE(middle_result.batch.events[1].ok());
+    ExpectErrorContains(middle_result.batch.events[1].error,
+                        "duplicate recognized key: medium");
+    EXPECT_NE(GetEvent<VllmRemovedEvent>(middle_result.batch.events[2]),
+              nullptr)
+        << middle_result.batch.events[2].error;
+
+    const std::string final = PackVllmBatch(2, [](Packer& packer) {
+        PackVllmStored(packer);
+        packer.pack_map(2);
+        packer.pack("type");
+        packer.pack("BlockRemoved");
+        packer.pack("block_hashes");
+        packer.pack_array(1);
+        packer.pack_uint64(42);
+    });
+    const auto final_result = DecodeVllmEventBatch(final.data(), final.size());
+    ASSERT_TRUE(final_result.ok) << final_result.error;
+    ASSERT_EQ(final_result.batch.events.size(), 2u);
+    EXPECT_NE(GetEvent<VllmStoredEvent>(final_result.batch.events[0]), nullptr)
+        << final_result.batch.events[0].error;
+    EXPECT_FALSE(final_result.batch.events[1].ok());
+    ExpectErrorContains(final_result.batch.events[1].error,
+                        "missing required key: medium");
+}
+
+TEST(DecodeMooncakeEventBatch, MalformedMiddleAndFinalEventsRemainIsolated) {
+    const std::string middle = PackMooncakeBatch(3, [](Packer& packer) {
+        PackMooncakeStored(packer, true);
+        packer.pack_map(2);
+        packer.pack("event_type");
+        packer.pack("removed");
+        packer.pack("event_type");
+        packer.pack("removed");
+        PackMooncakeRemoved(packer);
+    });
+    const auto middle_result =
+        DecodeMooncakeEventBatch(middle.data(), middle.size());
+    ASSERT_TRUE(middle_result.ok) << middle_result.error;
+    ASSERT_EQ(middle_result.batch.events.size(), 3u);
+    EXPECT_NE(GetEvent<MooncakeStoredEvent>(middle_result.batch.events[0]),
+              nullptr)
+        << middle_result.batch.events[0].error;
+    EXPECT_FALSE(middle_result.batch.events[1].ok());
+    ExpectErrorContains(middle_result.batch.events[1].error,
+                        "duplicate recognized key: event_type");
+    EXPECT_NE(GetEvent<MooncakeRemovedEvent>(middle_result.batch.events[2]),
+              nullptr)
+        << middle_result.batch.events[2].error;
+
+    const std::string final = PackMooncakeBatch(2, [](Packer& packer) {
+        PackMooncakeStored(packer);
+        packer.pack_map(1);
+        packer.pack("event_type");
+        packer.pack("stored");
+    });
+    const auto final_result =
+        DecodeMooncakeEventBatch(final.data(), final.size());
+    ASSERT_TRUE(final_result.ok) << final_result.error;
+    ASSERT_EQ(final_result.batch.events.size(), 2u);
+    EXPECT_NE(GetEvent<MooncakeStoredEvent>(final_result.batch.events[0]),
+              nullptr)
+        << final_result.batch.events[0].error;
+    EXPECT_FALSE(final_result.batch.events[1].ok());
+    ExpectErrorContains(final_result.batch.events[1].error,
+                        "missing required key: event_id");
+}
+
+TEST(DecodeVllmEventBatch, RejectsWrongRecognizedHashTypeLocally) {
+    const std::string payload = PackVllmBatch(2, [](Packer& packer) {
+        packer.pack_map(8);
+        packer.pack("type");
+        packer.pack("BlockStored");
+        packer.pack("block_hashes");
+        packer.pack_array(1);
+        packer.pack_int64(-1);
+        packer.pack("parent_block_hash");
+        packer.pack_nil();
+        packer.pack("token_ids");
+        packer.pack_nil();
+        packer.pack("block_size");
+        packer.pack_int64(16);
+        packer.pack("lora_id");
+        packer.pack_nil();
+        packer.pack("medium");
+        packer.pack("GPU");
+        packer.pack("lora_name");
+        packer.pack_nil();
+        PackVllmCleared(packer);
+    });
+
+    const auto result = DecodeVllmEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 2u);
+    EXPECT_FALSE(result.batch.events[0].ok());
+    ExpectErrorContains(result.batch.events[0].error,
+                        "expected unsigned integer or binary hash");
+    EXPECT_NE(GetEvent<VllmClearedEvent>(result.batch.events[1]), nullptr)
+        << result.batch.events[1].error;
+}
+
+TEST(DecodeMooncakeEventBatch, RejectsWrongRecognizedFieldTypeLocally) {
+    const std::string payload = PackMooncakeBatch(2, [](Packer& packer) {
+        packer.pack_map(12);
+        packer.pack("event_id");
+        packer.pack_uint64(9);
+        packer.pack("timestamp");
+        packer.pack(kMooncakeTimestamp);
+        packer.pack("event_type");
+        packer.pack("cleared");
+        packer.pack("type");
+        packer.pack("AllBlocksCleared");
+        packer.pack("model_name");
+        packer.pack("model-a");
+        packer.pack("block_size");
+        packer.pack_int64(16);
+        packer.pack("additional_salt");
+        packer.pack_nil();
+        packer.pack("lora_name");
+        packer.pack_nil();
+        packer.pack("tenant_id");
+        packer.pack("tenant-a");
+        packer.pack("backend_id");
+        packer.pack("backend-a");
+        packer.pack("medium");
+        packer.pack_int64(7);
+        packer.pack("dp_rank");
+        packer.pack(kMooncakeDpRank);
+        PackMooncakeCleared(packer);
+    });
+
+    const auto result =
+        DecodeMooncakeEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 2u);
+    EXPECT_FALSE(result.batch.events[0].ok());
+    ExpectErrorContains(result.batch.events[0].error,
+                        "invalid medium: expected string");
+    EXPECT_NE(GetEvent<MooncakeClearedEvent>(result.batch.events[1]), nullptr)
+        << result.batch.events[1].error;
+}
+
+TEST(MessagePackEnvelope, RejectsEmptyGarbageAndTrailingBytes) {
+    const auto empty_vllm = DecodeVllmEventBatch(nullptr, 0);
+    EXPECT_FALSE(empty_vllm.ok);
+    ExpectErrorContains(empty_vllm.error, "empty payload");
+
+    const char garbage[] = "\xc1not-msgpack";
+    const auto garbage_mooncake =
+        DecodeMooncakeEventBatch(garbage, sizeof(garbage) - 1);
+    EXPECT_FALSE(garbage_mooncake.ok);
+    ExpectErrorContains(garbage_mooncake.error,
+                        "failed to decode Mooncake envelope");
+
+    std::string trailing = PackVllmBatch(0, [](Packer&) {});
+    trailing.push_back('\0');
+    const auto trailing_vllm =
+        DecodeVllmEventBatch(trailing.data(), trailing.size());
+    EXPECT_FALSE(trailing_vllm.ok);
+    ExpectErrorContains(trailing_vllm.error, "trailing bytes");
+}
+
+TEST(DecodeSglangEventBatch, DecodesTaggedArrayAndPreservesHashBits) {
+    std::stringstream buffer;
+    Packer packer(buffer);
+    packer.pack_array(3);
+    packer.pack_double(12.5);
+    packer.pack_array(3);
+
+    // BlockStored(tag, block_hashes, parent, token_ids, block_size, lora_id,
+    // medium).  The first hash is -1 on the wire and must become UINT64_MAX.
+    packer.pack_array(7);
+    packer.pack("BlockStored");
+    packer.pack_array(1);
+    packer.pack_int64(-1);
+    packer.pack_nil();
+    packer.pack_array(2);
+    packer.pack_int32(1);
+    packer.pack_int32(2);
+    packer.pack_int64(2);
+    packer.pack_nil();
+    packer.pack("GPU");
+
+    packer.pack_array(3);
+    packer.pack("BlockRemoved");
+    packer.pack_array(1);
+    packer.pack_int64(-1);
+    packer.pack("GPU");
+
+    packer.pack_array(1);
+    packer.pack("AllBlocksCleared");
+    packer.pack_int64(4);
+
+    const std::string payload = buffer.str();
+    const auto result = DecodeSglangEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 3u);
+    const auto* stored =
+        std::get_if<SglangStoredEvent>(&*result.batch.events[0].event);
+    ASSERT_NE(stored, nullptr) << result.batch.events[0].error;
+    ASSERT_EQ(stored->block_hashes.size(), 1u);
+    EXPECT_EQ(stored->block_hashes[0], std::numeric_limits<uint64_t>::max());
+    const auto* removed =
+        std::get_if<SglangRemovedEvent>(&*result.batch.events[1].event);
+    ASSERT_NE(removed, nullptr) << result.batch.events[1].error;
+    EXPECT_EQ(removed->block_hashes[0], std::numeric_limits<uint64_t>::max());
+    EXPECT_NE(std::get_if<SglangClearedEvent>(&*result.batch.events[2].event),
+              nullptr);
+}
+
+TEST(DecodeSglangEventBatch, AcceptsOmittedMediumAndBigramTokens) {
+    std::stringstream buffer;
+    Packer packer(buffer);
+    packer.pack_array(3);
+    packer.pack_double(1.0);
+    packer.pack_array(2);
+    packer.pack_array(6);
+    packer.pack("BlockStored");
+    packer.pack_array(1);
+    packer.pack_int64(7);
+    packer.pack_nil();
+    packer.pack_array(1);
+    packer.pack_array(2);
+    packer.pack_int32(11);
+    packer.pack_int32(12);
+    packer.pack_int64(2);
+    packer.pack_nil();
+    packer.pack_array(2);
+    packer.pack("BlockRemoved");
+    packer.pack_array(1);
+    packer.pack_int64(7);
+    packer.pack_int64(0);
+
+    const std::string payload = buffer.str();
+    const auto result = DecodeSglangEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_TRUE(result.batch.events[0].ok()) << result.batch.events[0].error;
+    const auto* stored =
+        std::get_if<SglangStoredEvent>(&*result.batch.events[0].event);
+    ASSERT_NE(stored, nullptr);
+    ASSERT_TRUE(stored->token_ids.has_value());
+    EXPECT_EQ(*stored->token_ids, (std::vector<int32_t>{11, 12}));
+    EXPECT_FALSE(stored->medium.has_value());
+    ASSERT_TRUE(result.batch.events[1].ok()) << result.batch.events[1].error;
+    const auto* removed =
+        std::get_if<SglangRemovedEvent>(&*result.batch.events[1].event);
+    ASSERT_NE(removed, nullptr);
+    EXPECT_FALSE(removed->medium.has_value());
+}
+
+TEST(DecodeSglangEventBatch, RejectsMooncakeMapEventsForProtocolFallback) {
+    const std::string payload = PackMooncakeBatch(
+        1, [](Packer& packer) { PackMooncakeStored(packer); });
+
+    const auto result = DecodeSglangEventBatch(payload.data(), payload.size());
+    EXPECT_FALSE(result.ok);
+    ExpectErrorContains(result.error, "event entries must be arrays");
+}
+
+TEST(DecodeSglangEventBatch, RejectsUnsignedHashOutsideSignedWireRange) {
+    std::stringstream buffer;
+    Packer packer(buffer);
+    packer.pack_array(3);
+    packer.pack_double(1.0);
+    packer.pack_array(1);
+    packer.pack_array(3);
+    packer.pack("BlockRemoved");
+    packer.pack_array(1);
+    packer.pack_uint64(std::numeric_limits<uint64_t>::max());
+    packer.pack_nil();
+    packer.pack_nil();
+
+    const std::string payload = buffer.str();
+    const auto result = DecodeSglangEventBatch(payload.data(), payload.size());
+    ASSERT_TRUE(result.ok) << result.error;
+    ASSERT_EQ(result.batch.events.size(), 1u);
+    EXPECT_FALSE(result.batch.events[0].ok());
+    ExpectErrorContains(result.batch.events[0].error,
+                        "expected signed 64-bit hash");
+}
+
+TEST(SglangObjectKeyParser, CanonicalizesPhysicalComponents) {
+    const std::string hash =
+        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    ParsedSglangObjectKey key_k;
+    ParsedSglangObjectKey key_v;
+    ASSERT_TRUE(
+        ParseSglangObjectKey("backend_model_" + hash + "_0_k", &key_k).empty());
+    ASSERT_TRUE(
+        ParseSglangObjectKey("backend_model_" + hash + "_0_v", &key_v).empty());
+    EXPECT_EQ(key_k.logical_key, key_v.logical_key);
+    EXPECT_EQ(key_k.full_hash, hash);
+    EXPECT_EQ(key_k.prefix.value, key_v.prefix.value);
+    EXPECT_EQ(key_k.component_suffix, "_0_k");
+    EXPECT_EQ(key_v.component_suffix, "_0_v");
+}
+
+TEST(VllmObjectKeyParser, AcceptsOptionalHexPrefixAndRejectsMalformedKeys) {
+    const std::string hash = "0123456789abcdef000000000000002a";
+    ParsedSglangObjectKey parsed;
+    ASSERT_TRUE(ParseVllmObjectKey(
+                    "model-a@tp_rank:0@pcp0@dcp0@pp_rank:0@0x" + hash, &parsed)
+                    .empty());
+    EXPECT_EQ(parsed.full_hash, hash);
+    EXPECT_EQ(parsed.prefix.value, 0x000000000000002aULL);
+
+    EXPECT_FALSE(ParseVllmObjectKey("model-a@tp_rank:0@pcp0", &parsed).empty());
+}
+
+TEST(VllmObjectKeyParser, PreservesMultiSegmentCachePrefix) {
+    const std::string hash = "0123456789abcdef000000000000002a";
+    ParsedSglangObjectKey parsed;
+    ASSERT_TRUE(
+        ParseVllmObjectKey(
+            "prefix-a@prefix-b@model-a@tp_rank:0@pcp0@dcp0@pp_rank:0@" + hash,
+            &parsed)
+            .empty());
+    EXPECT_EQ(parsed.namespace_prefix, "prefix-a@prefix-b");
+    EXPECT_EQ(parsed.full_hash, hash);
+}
+
+TEST(VllmObjectKeyParser, AcceptsCurrentAscendCacheMetadataLayouts) {
+    const std::string hash = "0123456789abcdef000000000000002e";
+    ParsedSglangObjectKey parsed;
+
+    ASSERT_TRUE(
+        ParseVllmObjectKey("model-a@pcp1@dcp2@head_or_tp_rank:3@pp_rank:0@"
+                           "group:0@cache_role:kv@cache_family:default@" +
+                               hash,
+                           &parsed)
+            .empty());
+    EXPECT_EQ(parsed.full_hash, hash);
+    EXPECT_EQ(parsed.prefix.value, 0x000000000000002eULL);
+
+    ASSERT_TRUE(
+        ParseVllmObjectKey("model-a@pcp1@dcp2@head_or_tp_rank:3@group:0@"
+                           "cache_role:kv@cache_family:c2@layer_id:7@" +
+                               hash,
+                           &parsed)
+            .empty());
+    EXPECT_EQ(parsed.full_hash, hash);
+    EXPECT_EQ(parsed.prefix.value, 0x000000000000002eULL);
+}
+
+TEST(VllmObjectKeyParser, AcceptsCompactAscendLayerwiseLayouts) {
+    const std::string hash = "0123456789abcdef000000000000002f";
+    ParsedSglangObjectKey parsed;
+
+    ASSERT_TRUE(ParseVllmObjectKey("model-a@" + hash + "@3", &parsed).empty());
+    EXPECT_EQ(parsed.namespace_prefix, "model-a");
+    EXPECT_EQ(parsed.full_hash, hash);
+    EXPECT_EQ(parsed.prefix.value, 0x000000000000002fULL);
+
+    ASSERT_TRUE(
+        ParseVllmObjectKey("model-a@7@" + hash + "@3", &parsed).empty());
+    EXPECT_EQ(parsed.namespace_prefix, "model-a@7");
+    EXPECT_EQ(parsed.full_hash, hash);
+    EXPECT_EQ(parsed.prefix.value, 0x000000000000002fULL);
+}
+
+TEST(VllmObjectKeyParser, RejectsMalformedNumericMetadata) {
+    const std::string hash = "0123456789abcdef000000000000002e";
+    ParsedSglangObjectKey parsed;
+    const std::array<std::string, 6> malformed = {
+        "model-a@pcp-x@dcp0@head_or_tp_rank:0@pp_rank:0@" + hash,
+        "model-a@pcp0@dcp-1@head_or_tp_rank:0@pp_rank:0@" + hash,
+        "model-a@pcp0@dcp0@head_or_tp_rank:x@pp_rank:0@" + hash,
+        "model-a@pcp0@dcp0@head_or_tp_rank:0@pp_rank:-1@" + hash,
+        "model-a@pcp0@dcp0@head_or_tp_rank:0@group:x@" + hash,
+        "model-a@pcp0@dcp0@head_or_tp_rank:0@layer_id:x@" + hash,
+    };
+    for (const auto& key : malformed) {
+        SCOPED_TRACE(key);
+        EXPECT_FALSE(ParseVllmObjectKey(key, &parsed).empty());
+    }
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/prefix_indexer_test.cpp b/mooncake-conductor/tests/prefix_indexer_test.cpp
new file mode 100644
index 0000000000..6c988ba5ef
--- /dev/null
+++ b/mooncake-conductor/tests/prefix_indexer_test.cpp
@@ -0,0 +1,1115 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <map>
+#include <optional>
+#include <set>
+#include <span>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "conductor/prefixindex/hash_strategy.h"
+#include "conductor/prefixindex/prefix_indexer.h"
+#include "prefix_indexer_test_peer.h"
+
+namespace {
+
+using mooncake::conductor::prefixindex::BlockPresenceSnapshot;
+using mooncake::conductor::prefixindex::CacheHitResult;
+using mooncake::conductor::prefixindex::ContextKey;
+using mooncake::conductor::prefixindex::EngineOwner;
+using mooncake::conductor::prefixindex::EngineRegistration;
+using mooncake::conductor::prefixindex::GpuClear;
+using mooncake::conductor::prefixindex::GpuMutation;
+using mooncake::conductor::prefixindex::HashBlock;
+using mooncake::conductor::prefixindex::HashProfile;
+using mooncake::conductor::prefixindex::PrefixCacheTable;
+using mooncake::conductor::prefixindex::PrefixCacheTableSnapshot;
+using mooncake::conductor::prefixindex::PrefixCacheTableTestPeer;
+using mooncake::conductor::prefixindex::ProjectedPrefix;
+using mooncake::conductor::prefixindex::RankCacheHitResult;
+using mooncake::conductor::prefixindex::SharedClear;
+using mooncake::conductor::prefixindex::SharedMutation;
+using mooncake::conductor::prefixindex::SharedObjectOwner;
+using mooncake::conductor::prefixindex::StorageTier;
+
+constexpr char kRootDigest[] =
+    "4e1195df020de59e0d65a33a4279f1183e7ae4e5d980e309f8b55adff2e61c3e";
+constexpr char kPaddedSeedRootDigest[] =
+    "8d912e4e62b3cc377b1d1c7a14ef61dffbdaa0990237035c05401c29414c4172";
+constexpr char kPickleRootDigest[] =
+    "1973e23848344dc43a988a9b478663803cfffe1243480253f9a3cf004b14aa7c";
+
+ContextKey TestContext(int64_t block_size = 16) {
+    return {.tenant_id = "tenant-a",
+            .model_name = "model-a",
+            .lora_name = "",
+            .block_size = block_size};
+}
+
+HashProfile TestProfile() {
+    return {.strategy = "vllm_v1",
+            .algorithm = "sha256_cbor",
+            .python_hash_seed = "0",
+            .root_digest = kRootDigest,
+            .index_projection = "low64_be"};
+}
+
+HashProfile PaddedSeedProfile() {
+    return {.strategy = "vllm_v1",
+            .algorithm = "sha256_cbor",
+            .python_hash_seed = "00",
+            .root_digest = kPaddedSeedRootDigest,
+            .index_projection = "low64_be"};
+}
+
+HashProfile PickleProfile() {
+    return {.strategy = "vllm_v1",
+            .algorithm = "sha256",
+            .python_hash_seed = "0",
+            .root_digest = kPickleRootDigest,
+            .index_projection = "low64_be"};
+}
+
+// SGLang chains carry no Python seed root, so the resolver pins an all-zero
+// sentinel digest for the registration wire contract.
+HashProfile SglangProfile() {
+    return {.strategy = "sglang",
+            .algorithm = "sha256_raw",
+            .python_hash_seed = "0",
+            .root_digest = std::string(64, '0'),
+            .index_projection = "first64_be"};
+}
+
+// The bigram chains hash token pairs, so they carry one fewer logical position
+// than the prompt has tokens.
+HashProfile SglangBigramProfile() {
+    return {.strategy = "sglang_bigram",
+            .algorithm = "sha256_raw",
+            .python_hash_seed = "0",
+            .root_digest = std::string(64, '0'),
+            .index_projection = "first64_be"};
+}
+
+EngineRegistration Registration(const std::string& instance_id = "instance-a",
+                                int64_t dp_rank = 0) {
+    const ContextKey context = TestContext();
+    return {.context = context,
+            .profile = TestProfile(),
+            .instance_id = instance_id,
+            .dp_rank = dp_rank,
+            .effective_block_size = context.block_size,
+            .cache_group = 0};
+}
+
+EngineOwner GpuOwner(const std::string& instance_id = "instance-a",
+                     int64_t dp_rank = 0,
+                     const std::string& stream = "stream-a") {
+    return {.source_stream = stream,
+            .instance_id = instance_id,
+            .dp_rank = dp_rank};
+}
+
+SharedObjectOwner SharedOwner(const std::string& object_id = "object-a",
+                              const std::string& stream = "pool-stream",
+                              const std::string& backend = "backend-a") {
+    return {
+        .source_stream = stream, .backend_id = backend, .object_id = object_id};
+}
+
+ProjectedPrefix Prefix(uint64_t value) { return {.value = value}; }
+
+RankCacheHitResult RankMatch(int64_t gpu, int64_t cpu, int64_t disk) {
+    return {.gpu = gpu, .cpu = cpu, .disk = disk};
+}
+
+GpuMutation Gpu(const std::vector<ProjectedPrefix>& prefixes,
+                EngineOwner owner = GpuOwner()) {
+    const ContextKey context = TestContext();
+    return {.context = context,
+            .prefixes = prefixes,
+            .owner = std::move(owner),
+            .effective_block_size = context.block_size,
+            .cache_group = 0};
+}
+
+SharedMutation Shared(const std::vector<ProjectedPrefix>& prefixes,
+                      StorageTier tier,
+                      SharedObjectOwner owner = SharedOwner()) {
+    const ContextKey context = TestContext();
+    return {.context = context,
+            .prefixes = prefixes,
+            .tier = tier,
+            .owner = std::move(owner),
+            .effective_block_size = context.block_size,
+            .cache_group = 0};
+}
+
+GpuClear ClearFor(EngineOwner owner = GpuOwner()) {
+    const ContextKey context = TestContext();
+    return {.context = context,
+            .owner = std::move(owner),
+            .effective_block_size = context.block_size,
+            .cache_group = 0};
+}
+
+SharedClear ClearFor(SharedObjectOwner owner,
+                     std::optional<StorageTier> tier = std::nullopt) {
+    const ContextKey context = TestContext();
+    return {.context = context,
+            .owner = std::move(owner),
+            .tier = tier,
+            .effective_block_size = context.block_size,
+            .cache_group = 0};
+}
+
+std::vector<int32_t> Tokens(size_t count) {
+    std::vector<int32_t> tokens;
+    tokens.reserve(count);
+    for (size_t i = 0; i < count; ++i) {
+        tokens.push_back(static_cast<int32_t>(i + 1));
+    }
+    return tokens;
+}
+
+std::vector<ProjectedPrefix> Hashes(
+    const std::vector<int32_t>& tokens,
+    std::optional<std::string> cache_salt = std::nullopt) {
+    std::string error;
+    auto strategy = mooncake::conductor::prefixindex::CreateHashStrategy(
+        TestProfile(), &error);
+    EXPECT_TRUE(error.empty()) << error;
+    if (!strategy) {
+        return {};
+    }
+
+    std::vector<HashBlock> blocks;
+    error = strategy->Compute(TestContext(), tokens, std::move(cache_salt),
+                              &blocks);
+    EXPECT_TRUE(error.empty()) << error;
+
+    std::vector<ProjectedPrefix> prefixes;
+    prefixes.reserve(blocks.size());
+    for (const HashBlock& block : blocks) {
+        prefixes.push_back(block.projected);
+    }
+    return prefixes;
+}
+
+std::vector<ProjectedPrefix> SglangHashes(const std::vector<int32_t>& tokens) {
+    std::string error;
+    auto strategy = mooncake::conductor::prefixindex::CreateHashStrategy(
+        SglangProfile(), &error);
+    EXPECT_TRUE(error.empty()) << error;
+    if (!strategy) {
+        return {};
+    }
+
+    std::vector<HashBlock> blocks;
+    error = strategy->Compute(TestContext(), tokens, std::nullopt, &blocks);
+    EXPECT_TRUE(error.empty()) << error;
+
+    std::vector<ProjectedPrefix> prefixes;
+    prefixes.reserve(blocks.size());
+    for (const HashBlock& block : blocks) {
+        prefixes.push_back(block.projected);
+    }
+    return prefixes;
+}
+
+std::vector<ProjectedPrefix> SglangBigramHashes(
+    const std::vector<int32_t>& tokens) {
+    std::string error;
+    auto strategy = mooncake::conductor::prefixindex::CreateHashStrategy(
+        SglangBigramProfile(), &error);
+    EXPECT_TRUE(error.empty()) << error;
+    if (!strategy) {
+        return {};
+    }
+
+    std::vector<HashBlock> blocks;
+    error = strategy->Compute(TestContext(), tokens, std::nullopt, &blocks);
+    EXPECT_TRUE(error.empty()) << error;
+
+    std::vector<ProjectedPrefix> prefixes;
+    prefixes.reserve(blocks.size());
+    for (const HashBlock& block : blocks) {
+        prefixes.push_back(block.projected);
+    }
+    return prefixes;
+}
+
+void RegisterOrFail(PrefixCacheTable& table,
+                    const EngineRegistration& registration) {
+    const auto result = table.Register(registration);
+    ASSERT_TRUE(result.error.empty()) << result.error;
+}
+
+BlockPresenceSnapshot Presence(const PrefixCacheTable& table,
+                               ProjectedPrefix prefix) {
+    const PrefixCacheTableSnapshot table_snapshot =
+        PrefixCacheTableTestPeer::Snapshot(table);
+    return table_snapshot.contexts.at(TestContext()).blocks.at(prefix);
+}
+
+TEST(Registration, InvalidInputsDoNotCreateContextState) {
+    std::vector<EngineRegistration> invalid;
+
+    auto non_positive = Registration();
+    non_positive.context.block_size = 0;
+    non_positive.effective_block_size = 0;
+    invalid.push_back(non_positive);
+
+    auto mismatch = Registration();
+    mismatch.effective_block_size = 8;
+    invalid.push_back(mismatch);
+
+    auto unsupported_group = Registration();
+    unsupported_group.cache_group = 1;
+    invalid.push_back(unsupported_group);
+
+    auto empty_instance = Registration();
+    empty_instance.instance_id.clear();
+    invalid.push_back(empty_instance);
+
+    auto negative_rank = Registration();
+    negative_rank.dp_rank = -1;
+    invalid.push_back(negative_rank);
+
+    auto malformed_profile = Registration();
+    malformed_profile.profile.root_digest = "not-a-digest";
+    invalid.push_back(malformed_profile);
+
+    PrefixCacheTable table;
+    for (const auto& registration : invalid) {
+        SCOPED_TRACE(registration.instance_id);
+        const auto validation =
+            PrefixCacheTable::ValidateRegistration(registration);
+        EXPECT_FALSE(validation.error.empty());
+        const auto result = table.Register(registration);
+        EXPECT_FALSE(result.error.empty());
+        EXPECT_FALSE(result.inserted);
+    }
+    EXPECT_EQ(table.GetGlobalView().context_count, 0);
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table).contexts.empty());
+}
+
+TEST(Registration, ForgedSeedRootPairIsRejectedWithoutMutation) {
+    PrefixCacheTable table;
+    auto forged = Registration();
+    forged.profile.root_digest = kPaddedSeedRootDigest;
+
+    const auto validation = PrefixCacheTable::ValidateRegistration(forged);
+    EXPECT_NE(validation.error.find("does not match"), std::string::npos);
+    const auto rejected = table.Register(forged);
+    EXPECT_NE(rejected.error.find("does not match"), std::string::npos);
+    EXPECT_FALSE(rejected.inserted);
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table).contexts.empty());
+
+    RegisterOrFail(table, Registration());
+    const auto registered = PrefixCacheTableTestPeer::Snapshot(table);
+    EXPECT_NE(table.ValidateProfileBinding(TestContext(), forged.profile)
+                  .find("does not match"),
+              std::string::npos);
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), registered);
+
+    forged.instance_id = "instance-b";
+    const auto conflicting = table.Register(forged);
+    EXPECT_NE(conflicting.error.find("does not match"), std::string::npos);
+    EXPECT_FALSE(conflicting.inserted);
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), registered);
+}
+
+TEST(Registration, TracksEveryInstanceAndRankIdempotently) {
+    PrefixCacheTable table;
+
+    auto first = table.Register(Registration("instance-a", 0));
+    ASSERT_TRUE(first.error.empty()) << first.error;
+    EXPECT_TRUE(first.inserted);
+
+    auto duplicate = table.Register(Registration("instance-a", 0));
+    ASSERT_TRUE(duplicate.error.empty()) << duplicate.error;
+    EXPECT_FALSE(duplicate.inserted);
+
+    auto omitted_group = Registration("instance-a", 0);
+    omitted_group.cache_group.reset();
+    auto omitted_duplicate = table.Register(omitted_group);
+    ASSERT_TRUE(omitted_duplicate.error.empty()) << omitted_duplicate.error;
+    EXPECT_FALSE(omitted_duplicate.inserted);
+
+    auto second_rank = table.Register(Registration("instance-a", 2));
+    ASSERT_TRUE(second_rank.error.empty()) << second_rank.error;
+    EXPECT_TRUE(second_rank.inserted);
+
+    auto second_instance = table.Register(Registration("instance-b", 1));
+    ASSERT_TRUE(second_instance.error.empty()) << second_instance.error;
+    EXPECT_TRUE(second_instance.inserted);
+
+    const auto snapshot = PrefixCacheTableTestPeer::Snapshot(table);
+    ASSERT_EQ(snapshot.contexts.size(), 1u);
+    const auto& state = snapshot.contexts.at(TestContext());
+    EXPECT_EQ(state.profile, TestProfile());
+    EXPECT_EQ(state.instance_ranks.at("instance-a"), (std::set<int64_t>{0, 2}));
+    EXPECT_EQ(state.instance_ranks.at("instance-b"), (std::set<int64_t>{1}));
+    EXPECT_TRUE(state.blocks.empty());
+}
+
+TEST(Registration, ConflictingProfilePreservesCompleteState) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    ASSERT_EQ(table.StoreGpu(Gpu({Prefix(1)})), "");
+    const auto before = PrefixCacheTableTestPeer::Snapshot(table);
+
+    auto conflicting = Registration("instance-b", 1);
+    conflicting.profile = PaddedSeedProfile();
+    const auto result = table.Register(conflicting);
+
+    EXPECT_FALSE(result.error.empty());
+    EXPECT_FALSE(result.inserted);
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+}
+
+TEST(Registration, ProfileBindingValidationIsExactAndLookupOnly) {
+    PrefixCacheTable table;
+    const auto empty_before = PrefixCacheTableTestPeer::Snapshot(table);
+
+    EXPECT_FALSE(
+        table.ValidateProfileBinding(TestContext(), TestProfile()).empty());
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), empty_before);
+
+    RegisterOrFail(table, Registration());
+    const auto registered = PrefixCacheTableTestPeer::Snapshot(table);
+    EXPECT_EQ(table.ValidateProfileBinding(TestContext(), TestProfile()), "");
+
+    const HashProfile conflict = PaddedSeedProfile();
+    EXPECT_FALSE(table.ValidateProfileBinding(TestContext(), conflict).empty());
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), registered);
+}
+
+TEST(Registration, MixedAlgorithmsUnderOneContextAreRejected) {
+    // The resolved profile is immutable per ContextKey: the same seed under
+    // the other supported algorithm is still a conflict, in both orders.
+    {
+        PrefixCacheTable table;
+        RegisterOrFail(table, Registration());
+        const auto before = PrefixCacheTableTestPeer::Snapshot(table);
+
+        auto conflicting = Registration("instance-b", 1);
+        conflicting.profile = PickleProfile();
+        const auto result = table.Register(conflicting);
+        EXPECT_FALSE(result.error.empty());
+        EXPECT_FALSE(result.inserted);
+        EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+
+        EXPECT_FALSE(
+            table.ValidateProfileBinding(TestContext(), PickleProfile())
+                .empty());
+        EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+    }
+    {
+        PrefixCacheTable table;
+        auto pickle_registration = Registration();
+        pickle_registration.profile = PickleProfile();
+        RegisterOrFail(table, pickle_registration);
+        const auto before = PrefixCacheTableTestPeer::Snapshot(table);
+        EXPECT_EQ(table.ValidateProfileBinding(TestContext(), PickleProfile()),
+                  "");
+
+        auto conflicting = Registration("instance-b", 1);
+        const auto result = table.Register(conflicting);
+        EXPECT_FALSE(result.error.empty());
+        EXPECT_FALSE(result.inserted);
+        EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+    }
+}
+
+TEST(Mutations, StoreRequiresKnownContextAndRegisteredGpuRank) {
+    PrefixCacheTable table;
+    const auto gpu = Gpu({Prefix(1)});
+    const auto shared = Shared({Prefix(1)}, StorageTier::kCpu);
+
+    EXPECT_FALSE(table.StoreGpu(gpu).empty());
+    EXPECT_FALSE(table.StoreShared(shared).empty());
+    EXPECT_EQ(table.GetGlobalView().context_count, 0);
+
+    RegisterOrFail(table, Registration("instance-a", 1));
+    EXPECT_FALSE(table.StoreGpu(gpu).empty());
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table)
+                    .contexts.at(TestContext())
+                    .blocks.empty());
+}
+
+TEST(Mutations, InvalidGroupTierAndOwnersPreserveState) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    ASSERT_EQ(table.StoreGpu(Gpu({Prefix(1)})), "");
+    const auto before = PrefixCacheTableTestPeer::Snapshot(table);
+
+    auto bad_group = Gpu({Prefix(2)});
+    bad_group.cache_group = 3;
+    EXPECT_FALSE(table.StoreGpu(bad_group).empty());
+
+    auto bad_owner = Gpu({Prefix(2)});
+    bad_owner.owner.source_stream.clear();
+    EXPECT_FALSE(table.StoreGpu(bad_owner).empty());
+
+    auto bad_tier = Shared({Prefix(2)}, StorageTier::kGpu);
+    EXPECT_FALSE(table.StoreShared(bad_tier).empty());
+
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+}
+
+TEST(Mutations, DuplicateGpuStoreAndRemoveAreIdempotent) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const ProjectedPrefix prefix = Prefix(7);
+    const auto mutation = Gpu({prefix});
+
+    ASSERT_EQ(table.StoreGpu(mutation), "");
+    ASSERT_EQ(table.StoreGpu(mutation), "");
+    EXPECT_EQ(Presence(table, prefix).gpu_owners,
+              (std::set<EngineOwner>{GpuOwner()}));
+
+    auto absent_owner = Gpu({prefix}, GpuOwner("instance-b", 0, "stream-b"));
+    ASSERT_EQ(table.RemoveGpu(absent_owner), "");
+    EXPECT_EQ(Presence(table, prefix).gpu_owners,
+              (std::set<EngineOwner>{GpuOwner()}));
+
+    ASSERT_EQ(table.RemoveGpu(mutation), "");
+    ASSERT_EQ(table.RemoveGpu(mutation), "");
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table)
+                    .contexts.at(TestContext())
+                    .blocks.empty());
+}
+
+TEST(Mutations, CollidingSharedOwnersRemainIndependentlyRemovable) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const ProjectedPrefix collision = Prefix(0x123456789abcdef0ULL);
+    const SharedObjectOwner first = SharedOwner("object-a");
+    const SharedObjectOwner second = SharedOwner("object-b");
+
+    ASSERT_EQ(table.StoreShared(Shared({collision}, StorageTier::kCpu, first)),
+              "");
+    ASSERT_EQ(table.StoreShared(Shared({collision}, StorageTier::kCpu, second)),
+              "");
+    ASSERT_EQ(table.StoreShared(Shared({collision}, StorageTier::kCpu, first)),
+              "");
+    EXPECT_EQ(Presence(table, collision).cpu_owners,
+              (std::set<SharedObjectOwner>{first, second}));
+
+    ASSERT_EQ(table.RemoveShared(Shared({collision}, StorageTier::kCpu, first)),
+              "");
+    EXPECT_EQ(Presence(table, collision).cpu_owners,
+              (std::set<SharedObjectOwner>{second}));
+
+    ASSERT_EQ(
+        table.RemoveShared(Shared({collision}, StorageTier::kCpu, second)), "");
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table)
+                    .contexts.at(TestContext())
+                    .blocks.empty());
+}
+
+TEST(Mutations, BlockLivesUntilEveryTierOwnerSetIsEmpty) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const ProjectedPrefix prefix = Prefix(11);
+    const auto gpu = Gpu({prefix});
+    const auto cpu = Shared({prefix}, StorageTier::kCpu, SharedOwner("cpu"));
+    const auto disk = Shared({prefix}, StorageTier::kDisk, SharedOwner("disk"));
+
+    ASSERT_EQ(table.StoreGpu(gpu), "");
+    ASSERT_EQ(table.StoreShared(cpu), "");
+    ASSERT_EQ(table.StoreShared(disk), "");
+    ASSERT_EQ(table.RemoveGpu(gpu), "");
+    EXPECT_TRUE(Presence(table, prefix).gpu_owners.empty());
+    EXPECT_FALSE(Presence(table, prefix).cpu_owners.empty());
+    EXPECT_FALSE(Presence(table, prefix).disk_owners.empty());
+
+    ASSERT_EQ(table.RemoveShared(cpu), "");
+    EXPECT_TRUE(Presence(table, prefix).cpu_owners.empty());
+    EXPECT_FALSE(Presence(table, prefix).disk_owners.empty());
+
+    ASSERT_EQ(table.RemoveShared(disk), "");
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table)
+                    .contexts.at(TestContext())
+                    .blocks.empty());
+}
+
+TEST(Mutations, GpuAndSharedClearAreExactlyOwnerScoped) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-b", 1));
+    const ProjectedPrefix prefix = Prefix(21);
+    const EngineOwner engine_a = GpuOwner("instance-a", 0, "stream-a");
+    const EngineOwner engine_a_other_stream =
+        GpuOwner("instance-a", 0, "stream-a-other");
+    const EngineOwner engine_b = GpuOwner("instance-b", 1, "stream-b");
+    const SharedObjectOwner shared_a = SharedOwner("object-a");
+    const SharedObjectOwner shared_b = SharedOwner("object-b");
+
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, engine_a)), "");
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, engine_a_other_stream)), "");
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, engine_b)), "");
+    ASSERT_EQ(table.StoreShared(Shared({prefix}, StorageTier::kCpu, shared_a)),
+              "");
+    ASSERT_EQ(table.StoreShared(Shared({prefix}, StorageTier::kDisk, shared_a)),
+              "");
+    ASSERT_EQ(table.StoreShared(Shared({prefix}, StorageTier::kCpu, shared_b)),
+              "");
+
+    ASSERT_EQ(table.ClearGpu(ClearFor(engine_a)), "");
+    EXPECT_EQ(Presence(table, prefix).gpu_owners,
+              (std::set<EngineOwner>{engine_a_other_stream, engine_b}));
+    EXPECT_EQ(Presence(table, prefix).cpu_owners,
+              (std::set<SharedObjectOwner>{shared_a, shared_b}));
+
+    ASSERT_EQ(table.ClearShared(ClearFor(shared_a, StorageTier::kCpu)), "");
+    EXPECT_EQ(Presence(table, prefix).cpu_owners,
+              (std::set<SharedObjectOwner>{shared_b}));
+    EXPECT_EQ(Presence(table, prefix).disk_owners,
+              (std::set<SharedObjectOwner>{shared_a}));
+    EXPECT_EQ(Presence(table, prefix).gpu_owners,
+              (std::set<EngineOwner>{engine_a_other_stream, engine_b}));
+
+    ASSERT_EQ(table.ClearShared(ClearFor(shared_a)), "");
+    EXPECT_TRUE(Presence(table, prefix).disk_owners.empty());
+    EXPECT_EQ(Presence(table, prefix).gpu_owners,
+              (std::set<EngineOwner>{engine_a_other_stream, engine_b}));
+}
+
+TEST(Mutations, UnknownRemoveClearAndUnregisterNeverCreateState) {
+    PrefixCacheTable table;
+    const ContextKey context = TestContext();
+
+    EXPECT_EQ(table.RemoveGpu(Gpu({Prefix(1)})), "");
+    EXPECT_EQ(table.ClearGpu(ClearFor()), "");
+    EXPECT_EQ(table.RemoveShared(Shared({Prefix(1)}, StorageTier::kCpu)), "");
+    EXPECT_EQ(table.ClearShared(ClearFor(SharedOwner())), "");
+    EXPECT_EQ(table.Unregister(context, "instance-a", 0), "");
+
+    EXPECT_FALSE(PrefixCacheTableTestPeer::ContextExists(table, context));
+    EXPECT_TRUE(PrefixCacheTableTestPeer::Snapshot(table).contexts.empty());
+}
+
+TEST(Unregister, RemovesOnlySelectedRankGpuOwners) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-a", 1));
+    RegisterOrFail(table, Registration("instance-b", 0));
+    const ProjectedPrefix prefix = Prefix(31);
+    const EngineOwner a0 = GpuOwner("instance-a", 0, "stream-a0");
+    const EngineOwner a0_second_stream =
+        GpuOwner("instance-a", 0, "stream-a0-second");
+    const EngineOwner a1 = GpuOwner("instance-a", 1, "stream-a1");
+    const EngineOwner b0 = GpuOwner("instance-b", 0, "stream-b0");
+    const SharedObjectOwner shared = SharedOwner();
+
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, a0)), "");
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, a0_second_stream)), "");
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, a1)), "");
+    ASSERT_EQ(table.StoreGpu(Gpu({prefix}, b0)), "");
+    ASSERT_EQ(table.StoreShared(Shared({prefix}, StorageTier::kCpu, shared)),
+              "");
+
+    ASSERT_EQ(table.Unregister(TestContext(), "instance-a", 0), "");
+    auto snapshot = PrefixCacheTableTestPeer::Snapshot(table);
+    const auto& state = snapshot.contexts.at(TestContext());
+    EXPECT_EQ(state.instance_ranks.at("instance-a"), (std::set<int64_t>{1}));
+    EXPECT_EQ(state.instance_ranks.at("instance-b"), (std::set<int64_t>{0}));
+    EXPECT_EQ(state.blocks.at(prefix).gpu_owners,
+              (std::set<EngineOwner>{a1, b0}));
+    EXPECT_EQ(state.blocks.at(prefix).cpu_owners,
+              (std::set<SharedObjectOwner>{shared}));
+
+    ASSERT_EQ(table.Unregister(TestContext(), "instance-a", 1), "");
+    snapshot = PrefixCacheTableTestPeer::Snapshot(table);
+    EXPECT_FALSE(snapshot.contexts.at(TestContext())
+                     .instance_ranks.contains("instance-a"));
+    EXPECT_EQ(snapshot.contexts.at(TestContext()).blocks.at(prefix).gpu_owners,
+              (std::set<EngineOwner>{b0}));
+    EXPECT_EQ(snapshot.contexts.at(TestContext()).blocks.at(prefix).cpu_owners,
+              (std::set<SharedObjectOwner>{shared}));
+}
+
+TEST(Query, ExactTwoInstanceSharedCacheExample) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-1", 0));
+    RegisterOrFail(table, Registration("instance-2", 1));
+    const auto tokens = Tokens(48);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[1]},
+                                 GpuOwner("instance-1", 0, "engine-1"))),
+              "");
+    ASSERT_EQ(table.StoreShared(
+                  Shared(hashes, StorageTier::kCpu, SharedOwner("cpu-object"))),
+              "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kDisk,
+                                       SharedOwner("disk-object"))),
+              "");
+
+    const auto results = table.Query(TestContext(), tokens);
+    ASSERT_EQ(results.size(), 2u);
+
+    const CacheHitResult& first = results.at("instance-1");
+    EXPECT_EQ(first.longest_match_tokens, 48);
+    EXPECT_EQ(first.gpu, 32);
+    EXPECT_EQ(first.dp, (std::map<int64_t, int64_t>{{0, 32}}));
+    EXPECT_EQ(
+        first.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(32, 48, 48)}}));
+    EXPECT_EQ(first.cpu, 48);
+    EXPECT_EQ(first.disk, 48);
+
+    const CacheHitResult& second = results.at("instance-2");
+    EXPECT_EQ(second.longest_match_tokens, 48);
+    EXPECT_EQ(second.gpu, 0);
+    EXPECT_EQ(second.dp, (std::map<int64_t, int64_t>{{1, 0}}));
+    EXPECT_EQ(
+        second.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{1, RankMatch(0, 48, 48)}}));
+    EXPECT_EQ(second.cpu, 48);
+    EXPECT_EQ(second.disk, 48);
+}
+
+TEST(Query, TrailingPartialBlockNeverReportsMoreThanPromptTokens) {
+    PrefixCacheTable table;
+    auto registration = Registration();
+    registration.profile = SglangProfile();
+    RegisterOrFail(table, registration);
+
+    // 40 tokens over a 16-token block size: two whole blocks plus a trailing
+    // block that only covers 8 tokens.
+    const auto tokens = Tokens(40);
+    const auto hashes = SglangHashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[1], hashes[2]})), "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kCpu)), "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kDisk)), "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 40);
+    EXPECT_EQ(result.gpu, 40);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 40}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(40, 40, 40)}}));
+    EXPECT_EQ(result.cpu, 40);
+    EXPECT_EQ(result.disk, 40);
+}
+
+TEST(Query, WholeBlockRunIsUnaffectedByThePromptLengthClamp) {
+    PrefixCacheTable table;
+    auto registration = Registration();
+    registration.profile = SglangProfile();
+    RegisterOrFail(table, registration);
+
+    const auto tokens = Tokens(40);
+    const auto hashes = SglangHashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    // Only the two whole blocks are indexed; the partial tail misses.
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[0], hashes[1]}, StorageTier::kDisk)),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 32);
+    EXPECT_EQ(result.gpu, 0);
+    EXPECT_EQ(result.cpu, 0);
+    EXPECT_EQ(result.disk, 32);
+}
+
+TEST(Query, BigramFullMatchReportsOneFewerPositionThanPromptTokens) {
+    PrefixCacheTable table;
+    auto registration = Registration();
+    registration.profile = SglangBigramProfile();
+    RegisterOrFail(table, registration);
+
+    // 40 raw tokens over a 16-token block size. The bigram chain covers 39
+    // logical positions, so it is two whole blocks plus a trailing block of 7.
+    const auto tokens = Tokens(40);
+    const auto hashes = SglangBigramHashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[1], hashes[2]})), "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kCpu)), "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kDisk)), "");
+
+    // 39, not 40 and not the 48 a whole-block count would report.
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 39);
+    EXPECT_EQ(result.gpu, 39);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 39}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(39, 39, 39)}}));
+    EXPECT_EQ(result.cpu, 39);
+    EXPECT_EQ(result.disk, 39);
+}
+
+TEST(Query, BigramWholeBlockRunIsUnaffectedByTheLogicalLengthClamp) {
+    PrefixCacheTable table;
+    auto registration = Registration();
+    registration.profile = SglangBigramProfile();
+    RegisterOrFail(table, registration);
+
+    const auto tokens = Tokens(40);
+    const auto hashes = SglangBigramHashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    // Only the two whole blocks are indexed; the partial tail misses. The
+    // clamp must not pull this below the 32 positions those blocks hold.
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[0], hashes[1]}, StorageTier::kDisk)),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 32);
+    EXPECT_EQ(result.gpu, 0);
+    EXPECT_EQ(result.cpu, 0);
+    EXPECT_EQ(result.disk, 32);
+}
+
+TEST(Query, GpuCpuAndDiskExtendOneCumulativePrefix) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(64);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 4u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[1]})), "");
+    ASSERT_EQ(table.StoreShared(Shared({hashes[2]}, StorageTier::kCpu)), "");
+    ASSERT_EQ(table.StoreShared(Shared({hashes[3]}, StorageTier::kDisk)), "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 64);
+    EXPECT_EQ(result.gpu, 32);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 32}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(32, 48, 64)}}));
+    EXPECT_EQ(result.cpu, 48);
+    EXPECT_EQ(result.disk, 64);
+}
+
+TEST(Query, EmptyCpuPhaseFallsThroughToDiskAtSameBlock) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(48);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0]})), "");
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[1], hashes[2]}, StorageTier::kDisk)),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 48);
+    EXPECT_EQ(result.gpu, 16);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 16}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(16, 16, 48)}}));
+    EXPECT_EQ(result.cpu, 16);
+    EXPECT_EQ(result.disk, 48);
+}
+
+TEST(Query, CompleteGpuCoverageCarriesThroughLowerTierBoundaries) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(48);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu(hashes)), "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 48);
+    EXPECT_EQ(result.gpu, 48);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 48}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(48, 48, 48)}}));
+    EXPECT_EQ(result.cpu, 48);
+    EXPECT_EQ(result.disk, 48);
+}
+
+TEST(Query, DuplicateTierPresenceIsAttributedOnce) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(48);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 3u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0]})), "");
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[0], hashes[1]}, StorageTier::kCpu)),
+        "");
+    ASSERT_EQ(table.StoreShared(Shared(hashes, StorageTier::kDisk)), "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 48);
+    EXPECT_EQ(result.gpu, 16);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 16}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(16, 32, 48)}}));
+    EXPECT_EQ(result.cpu, 32);
+    EXPECT_EQ(result.disk, 48);
+}
+
+TEST(Query, LowerTierPhaseNeverReturnsToHigherTier) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(64);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 4u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0]})), "");
+    ASSERT_EQ(table.StoreShared(Shared({hashes[2]}, StorageTier::kCpu)), "");
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[1], hashes[3]}, StorageTier::kDisk)),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 32);
+    EXPECT_EQ(result.gpu, 16);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 16}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(16, 16, 32)}}));
+    EXPECT_EQ(result.cpu, 16);
+    EXPECT_EQ(result.disk, 32);
+}
+
+TEST(Query, DiskMissIgnoresAllLaterIsolatedBlocks) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(80);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 5u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[4]})), "");
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[1], hashes[4]}, StorageTier::kCpu)),
+        "");
+    ASSERT_EQ(
+        table.StoreShared(Shared({hashes[3], hashes[4]}, StorageTier::kDisk)),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 32);
+    EXPECT_EQ(result.gpu, 16);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 16}}));
+    EXPECT_EQ(
+        result.rank_matches,
+        (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(16, 32, 32)}}));
+    EXPECT_EQ(result.cpu, 32);
+    EXPECT_EQ(result.disk, 32);
+}
+
+TEST(Query, DifferentRanksNeverFabricateOneGpuPrefix) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-a", 1));
+    const auto tokens = Tokens(32);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 2u);
+
+    ASSERT_EQ(
+        table.StoreGpu(Gpu({hashes[0]}, GpuOwner("instance-a", 0, "rank-0"))),
+        "");
+    ASSERT_EQ(
+        table.StoreGpu(Gpu({hashes[1]}, GpuOwner("instance-a", 1, "rank-1"))),
+        "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 16);
+    EXPECT_EQ(result.gpu, 16);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 16}, {1, 0}}));
+    EXPECT_EQ(result.rank_matches,
+              (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(16, 16, 16)},
+                                                     {1, RankMatch(0, 0, 0)}}));
+    EXPECT_EQ(result.dp.size(), result.rank_matches.size());
+    EXPECT_EQ(result.cpu, 16);
+    EXPECT_EQ(result.disk, 16);
+}
+
+TEST(Query, InstanceSummaryIsRealizedByMaximumGpuRank) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-a", 1));
+    const auto tokens = Tokens(64);
+    const auto hashes = Hashes(tokens);
+    ASSERT_EQ(hashes.size(), 4u);
+
+    ASSERT_EQ(table.StoreGpu(Gpu({hashes[0], hashes[1]},
+                                 GpuOwner("instance-a", 0, "rank-0"))),
+              "");
+    ASSERT_EQ(
+        table.StoreGpu(Gpu({hashes[0]}, GpuOwner("instance-a", 1, "rank-1"))),
+        "");
+    ASSERT_EQ(table.StoreShared(Shared({hashes[2]}, StorageTier::kCpu)), "");
+    ASSERT_EQ(table.StoreShared(Shared({hashes[3]}, StorageTier::kDisk)), "");
+
+    const auto result = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 32}, {1, 16}}));
+    EXPECT_EQ(result.rank_matches,
+              (std::map<int64_t, RankCacheHitResult>{
+                  {0, RankMatch(32, 48, 64)}, {1, RankMatch(16, 16, 16)}}));
+    EXPECT_EQ(result.dp.size(), result.rank_matches.size());
+    for (const auto& [rank, gpu] : result.dp) {
+        ASSERT_TRUE(result.rank_matches.contains(rank));
+        EXPECT_EQ(gpu, result.rank_matches.at(rank).gpu);
+    }
+    EXPECT_EQ(result.gpu, result.rank_matches.at(0).gpu);
+    EXPECT_EQ(result.cpu, result.rank_matches.at(0).cpu);
+    EXPECT_EQ(result.disk, result.rank_matches.at(0).disk);
+    EXPECT_EQ(result.longest_match_tokens, result.rank_matches.at(0).disk);
+}
+
+TEST(Query, RegisteredZeroHitRanksAndIncompleteTailAreRetained) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-a", 2));
+    const auto incomplete_tokens = Tokens(31);
+
+    const auto results = table.Query(TestContext(), incomplete_tokens);
+    ASSERT_EQ(results.size(), 1u);
+    const auto& result = results.at("instance-a");
+    EXPECT_EQ(result.longest_match_tokens, 0);
+    EXPECT_EQ(result.dp, (std::map<int64_t, int64_t>{{0, 0}, {2, 0}}));
+    EXPECT_EQ(result.rank_matches,
+              (std::map<int64_t, RankCacheHitResult>{{0, RankMatch(0, 0, 0)},
+                                                     {2, RankMatch(0, 0, 0)}}));
+    EXPECT_EQ(result.gpu, 0);
+    EXPECT_EQ(result.cpu, 0);
+    EXPECT_EQ(result.disk, 0);
+}
+
+TEST(Query, InstanceFilterAndUnknownContextAreLookupOnly) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-b", 1));
+    const auto before = PrefixCacheTableTestPeer::Snapshot(table);
+
+    const auto filtered =
+        table.Query(TestContext(), Tokens(16), std::nullopt, "instance-b");
+    ASSERT_EQ(filtered.size(), 1u);
+    EXPECT_TRUE(filtered.contains("instance-b"));
+
+    EXPECT_TRUE(
+        table.Query(TestContext(), Tokens(16), std::nullopt, "unknown-instance")
+            .empty());
+    ContextKey unknown = TestContext();
+    unknown.model_name = "missing";
+    EXPECT_TRUE(table.Query(unknown, Tokens(16)).empty());
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table), before);
+}
+
+TEST(Query, CacheSaltChangesHashesWithoutChangingContextIdentity) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration());
+    const auto tokens = Tokens(16);
+    const auto unsalted = Hashes(tokens);
+    ASSERT_EQ(table.StoreGpu(Gpu(unsalted)), "");
+
+    const auto hit = table.Query(TestContext(), tokens).at("instance-a");
+    EXPECT_EQ(hit.longest_match_tokens, 16);
+
+    const auto salted =
+        table.Query(TestContext(), tokens, std::string("request-salt"))
+            .at("instance-a");
+    EXPECT_EQ(salted.longest_match_tokens, 0);
+    EXPECT_EQ(table.GetGlobalView().context_count, 1);
+}
+
+TEST(GlobalView, ReportsProfileRegistrationAndOwnerMapSize) {
+    PrefixCacheTable table;
+    RegisterOrFail(table, Registration("instance-a", 0));
+    RegisterOrFail(table, Registration("instance-b", 1));
+    ASSERT_EQ(table.StoreGpu(Gpu({Prefix(1), Prefix(2)})), "");
+
+    const auto view = table.GetGlobalView();
+    ASSERT_EQ(view.context_count, 1);
+    ASSERT_EQ(view.contexts.size(), 1u);
+    EXPECT_EQ(view.contexts[0].context, TestContext());
+    EXPECT_EQ(view.contexts[0].profile, TestProfile());
+    EXPECT_EQ(view.contexts[0].instance_ranks.at("instance-a"),
+              (std::set<int64_t>{0}));
+    EXPECT_EQ(view.contexts[0].instance_ranks.at("instance-b"),
+              (std::set<int64_t>{1}));
+    EXPECT_EQ(view.contexts[0].prefix_count, 2u);
+}
+
+TEST(Capacity, EvictsOldestWrittenPrefixesWhenOverLimit) {
+    PrefixCacheTable table(10);
+    RegisterOrFail(table, Registration());
+
+    for (uint64_t i = 1; i <= 14; ++i) {
+        ASSERT_EQ(table.StoreGpu(Gpu({Prefix(i)})), "");
+    }
+
+    const auto snapshot = PrefixCacheTableTestPeer::Snapshot(table);
+    const auto& blocks = snapshot.contexts.at(TestContext()).blocks;
+    EXPECT_LE(blocks.size(), 10u);
+    EXPECT_TRUE(blocks.contains(Prefix(14)));
+    EXPECT_FALSE(blocks.contains(Prefix(1)));
+}
+
+TEST(Capacity, UnlimitedWhenBlockLimitIsZero) {
+    PrefixCacheTable table(0);
+    RegisterOrFail(table, Registration());
+    for (uint64_t i = 1; i <= 50; ++i) {
+        ASSERT_EQ(table.StoreGpu(Gpu({Prefix(i)})), "");
+    }
+    EXPECT_EQ(PrefixCacheTableTestPeer::Snapshot(table)
+                  .contexts.at(TestContext())
+                  .blocks.size(),
+              50u);
+}
+
+TEST(Capacity, OrderTrackingStaysInSyncWithBlocks) {
+    PrefixCacheTable table(10);
+    RegisterOrFail(table, Registration());
+    const ContextKey context = TestContext();
+
+    for (uint64_t i = 1; i <= 6; ++i) {
+        ASSERT_EQ(table.StoreGpu(Gpu({Prefix(i)})), "");
+    }
+    auto sizes = PrefixCacheTableTestPeer::Order(table, context);
+    EXPECT_EQ(sizes.blocks, 6u);
+    EXPECT_EQ(sizes.write_order, 6u);
+    EXPECT_EQ(sizes.order_pos, 6u);
+
+    for (uint64_t i = 1; i <= 3; ++i) {
+        ASSERT_EQ(table.RemoveGpu(Gpu({Prefix(i)})), "");
+    }
+    sizes = PrefixCacheTableTestPeer::Order(table, context);
+    EXPECT_EQ(sizes.blocks, 3u);
+    EXPECT_EQ(sizes.write_order, 3u);
+    EXPECT_EQ(sizes.order_pos, 3u);
+
+    ASSERT_EQ(table.ClearGpu(ClearFor()), "");
+    sizes = PrefixCacheTableTestPeer::Order(table, context);
+    EXPECT_EQ(sizes.blocks, 0u);
+    EXPECT_EQ(sizes.write_order, 0u);
+    EXPECT_EQ(sizes.order_pos, 0u);
+
+    for (uint64_t i = 20; i <= 40; ++i) {
+        ASSERT_EQ(table.StoreGpu(Gpu({Prefix(i)})), "");
+    }
+    sizes = PrefixCacheTableTestPeer::Order(table, context);
+    EXPECT_LE(sizes.blocks, 10u);
+    EXPECT_EQ(sizes.write_order, sizes.blocks);
+    EXPECT_EQ(sizes.order_pos, sizes.blocks);
+    EXPECT_GT(sizes.evicted_by_capacity, 0);
+}
+
+}  // namespace
diff --git a/mooncake-conductor/tests/prefix_indexer_test_peer.h b/mooncake-conductor/tests/prefix_indexer_test_peer.h
new file mode 100644
index 0000000000..5903fe7bee
--- /dev/null
+++ b/mooncake-conductor/tests/prefix_indexer_test_peer.h
@@ -0,0 +1,115 @@
+#pragma once
+
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <set>
+#include <shared_mutex>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "conductor/prefixindex/prefix_indexer.h"
+
+namespace mooncake::conductor::prefixindex {
+
+struct BlockPresenceSnapshot {
+    std::set<EngineOwner> gpu_owners;
+    std::set<SharedObjectOwner> cpu_owners;
+    std::set<SharedObjectOwner> disk_owners;
+
+    bool operator==(const BlockPresenceSnapshot&) const = default;
+};
+
+struct ContextStateSnapshot {
+    HashProfile profile;
+    std::map<std::string, std::set<int64_t>> instance_ranks;
+    std::unordered_map<ProjectedPrefix, BlockPresenceSnapshot> blocks;
+
+    bool operator==(const ContextStateSnapshot&) const = default;
+};
+
+struct PrefixCacheTableSnapshot {
+    std::unordered_map<ContextKey, ContextStateSnapshot> contexts;
+
+    bool operator==(const PrefixCacheTableSnapshot&) const = default;
+};
+
+class PrefixCacheTableTestPeer {
+   public:
+    static bool ContextExists(const PrefixCacheTable& table,
+                              const ContextKey& context) {
+        return table.LoadContextState(context) != nullptr;
+    }
+
+    static std::unique_lock<std::shared_mutex> LockContextState(
+        const PrefixCacheTable& table, const ContextKey& context) {
+        auto state = table.LoadContextState(context);
+        if (state == nullptr) return {};
+        return std::unique_lock<std::shared_mutex>(state->mutex);
+    }
+
+    static std::optional<BlockPresenceSnapshot> Presence(
+        const PrefixCacheTable& table, const ContextKey& context,
+        ProjectedPrefix prefix) {
+        auto state = table.LoadContextState(context);
+        if (state == nullptr) return std::nullopt;
+
+        std::shared_lock state_lock(state->mutex);
+        const auto block = state->blocks.find(prefix);
+        if (block == state->blocks.end()) return std::nullopt;
+        return BlockPresenceSnapshot{block->second.gpu_owners,
+                                     block->second.cpu_owners,
+                                     block->second.disk_owners};
+    }
+
+    // Snapshot sizes for validating order metadata invariants.
+    struct OrderSizes {
+        size_t write_order = 0;
+        size_t order_pos = 0;
+        size_t blocks = 0;
+        int64_t evicted_by_capacity = 0;
+    };
+
+    static OrderSizes Order(const PrefixCacheTable& table,
+                            const ContextKey& context) {
+        auto state = table.LoadContextState(context);
+        if (state == nullptr) return {};
+        std::shared_lock state_lock(state->mutex);
+        return {.write_order = state->write_order.size(),
+                .order_pos = state->order_pos.size(),
+                .blocks = state->blocks.size(),
+                .evicted_by_capacity = state->evicted_by_capacity};
+    }
+
+    static PrefixCacheTableSnapshot Snapshot(const PrefixCacheTable& table) {
+        PrefixCacheTableSnapshot snapshot;
+        std::vector<std::pair<ContextKey, std::shared_ptr<ContextState>>>
+            contexts;
+        {
+            std::shared_lock map_lock(table.context_map_mutex_);
+            contexts.reserve(table.contexts_.size());
+            for (const auto& item : table.contexts_) {
+                contexts.push_back(item);
+            }
+        }
+
+        for (const auto& [context, state] : contexts) {
+            std::shared_lock state_lock(state->mutex);
+            ContextStateSnapshot state_snapshot;
+            state_snapshot.profile = state->profile;
+            state_snapshot.instance_ranks = state->instance_ranks;
+            for (const auto& [prefix, presence] : state->blocks) {
+                state_snapshot.blocks.emplace(
+                    prefix, BlockPresenceSnapshot{presence.gpu_owners,
+                                                  presence.cpu_owners,
+                                                  presence.disk_owners});
+            }
+            snapshot.contexts.emplace(context, std::move(state_snapshot));
+        }
+        return snapshot;
+    }
+};
+
+}  // namespace mooncake::conductor::prefixindex
diff --git a/mooncake-conductor/tests/test_fixtures.h b/mooncake-conductor/tests/test_fixtures.h
new file mode 100644
index 0000000000..44c16a47be
--- /dev/null
+++ b/mooncake-conductor/tests/test_fixtures.h
@@ -0,0 +1,43 @@
+#pragma once
+
+// Shared helpers for loading JSON golden-vector fixtures. uint64 values are
+// stored as decimal strings so that values above 2^53 survive JSON
+// round-trips without precision loss.
+
+#include <json/json.h>
+
+#include <cstdint>
+#include <fstream>
+#include <stdexcept>
+#include <string>
+
+#include "integer_parser.h"
+
+namespace mooncake::conductor::test {
+
+inline Json::Value LoadJsonFixture(const std::string& filename) {
+    const std::string path =
+        std::string(CONDUCTOR_TEST_FIXTURE_DIR) + "/" + filename;
+    std::ifstream in(path);
+    if (!in) {
+        throw std::runtime_error("cannot open fixture: " + path);
+    }
+    Json::Value root;
+    Json::CharReaderBuilder builder;
+    std::string errs;
+    if (!Json::parseFromStream(builder, in, &root, &errs)) {
+        throw std::runtime_error("cannot parse fixture " + path + ": " + errs);
+    }
+    return root;
+}
+
+inline uint64_t ParseU64(const Json::Value& v) {
+    const std::string text = v.asString();
+    const auto parsed = TryParseInteger<uint64_t>(text);
+    if (!parsed.has_value()) {
+        throw std::runtime_error("fixture value is not a uint64: " + text);
+    }
+    return *parsed;
+}
+
+}  // namespace mooncake::conductor::test
diff --git a/mooncake-conductor/tests/zmq_client_test.cpp b/mooncake-conductor/tests/zmq_client_test.cpp
new file mode 100644
index 0000000000..1adc878b01
--- /dev/null
+++ b/mooncake-conductor/tests/zmq_client_test.cpp
@@ -0,0 +1,1174 @@
+// Tests for ZMQClient source routing, metadata propagation, lifecycle,
+// sequence tracking, gap handling, and replay-after-reconnect.
+
+#include <gtest/gtest.h>
+#include <msgpack.hpp>
+#include <zmq.hpp>
+#include <zmq_addon.hpp>
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <mutex>
+#include <optional>
+#include <sstream>
+#include <string>
+#include <thread>
+#include <unordered_set>
+#include <utility>
+#include <variant>
+#include <vector>
+
+#include "conductor/zmq/zmq_client.h"
+
+namespace mooncake::conductor::zmq {
+
+class ZMQClientTestPeer {
+   public:
+    static void SetEndpoint(ZMQClient& client, std::string endpoint) {
+        std::unique_lock lock(client.mu_);
+        client.config_.endpoint = std::move(endpoint);
+    }
+
+    static void SetLastSequence(ZMQClient& client, int64_t sequence) {
+        std::unique_lock lock(client.mu_);
+        client.last_seq_ = sequence;
+    }
+
+    static void HandleReconnect(ZMQClient& client) { client.HandleReconnect(); }
+
+    static void MarkDisconnected(ZMQClient& client) {
+        client.MarkDisconnected();
+    }
+
+    static bool IsConnected(ZMQClient& client) { return client.IsConnected(); }
+
+    static bool HasReplaySocket(ZMQClient& client) {
+        std::shared_lock lock(client.mu_);
+        return client.replay_socket_ != nullptr;
+    }
+};
+
+}  // namespace mooncake::conductor::zmq
+
+namespace {
+
+using mooncake::conductor::common::PublisherKind;
+using mooncake::conductor::zmq::DecodedBatch;
+using mooncake::conductor::zmq::EventHandler;
+using mooncake::conductor::zmq::MessageMetadata;
+using mooncake::conductor::zmq::MooncakeEventBatch;
+using mooncake::conductor::zmq::MooncakeStoredEvent;
+using mooncake::conductor::zmq::ValidateConfig;
+using mooncake::conductor::zmq::VllmEventBatch;
+using mooncake::conductor::zmq::VllmRemovedEvent;
+using mooncake::conductor::zmq::VllmStoredEvent;
+using mooncake::conductor::zmq::ZMQClient;
+using mooncake::conductor::zmq::ZMQClientConfig;
+using mooncake::conductor::zmq::ZMQClientTestPeer;
+
+struct HandledBatch {
+    DecodedBatch batch;
+    MessageMetadata metadata;
+};
+
+class MockEventHandler : public EventHandler {
+   public:
+    std::string HandleBatch(const DecodedBatch& batch,
+                            const MessageMetadata& metadata) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!handle_error_.empty()) return handle_error_;
+        batches_.push_back({batch, metadata});
+        if (const auto* vllm = std::get_if<VllmEventBatch>(&batch)) {
+            for (const auto& decoded : vllm->events) {
+                if (!decoded.event.has_value()) continue;
+                if (const auto* stored =
+                        std::get_if<VllmStoredEvent>(&*decoded.event)) {
+                    for (const auto& hash : stored->block_hashes) {
+                        if (const auto* value = std::get_if<uint64_t>(&hash)) {
+                            present_hashes_.insert(*value);
+                        }
+                    }
+                } else if (const auto* removed =
+                               std::get_if<VllmRemovedEvent>(&*decoded.event)) {
+                    for (const auto& hash : removed->block_hashes) {
+                        if (const auto* value = std::get_if<uint64_t>(&hash)) {
+                            present_hashes_.erase(*value);
+                        }
+                    }
+                }
+            }
+        }
+        return "";
+    }
+
+    void SetHandleError(std::string error) {
+        std::lock_guard<std::mutex> lock(mu_);
+        handle_error_ = std::move(error);
+    }
+
+    void OnSourceStale(const std::string& cache_pool_key,
+                       const MessageMetadata& metadata,
+                       const std::string& reason) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        ++stale_notifications_;
+        stale_cache_pool_key_ = cache_pool_key;
+        stale_metadata_ = metadata;
+        stale_reason_ = reason;
+    }
+
+    std::optional<HandledBatch> FindBatch(int64_t sequence,
+                                          const std::string& endpoint) {
+        std::lock_guard<std::mutex> lock(mu_);
+        for (const auto& handled : batches_) {
+            if (handled.metadata.sequence == sequence &&
+                handled.metadata.endpoint == endpoint) {
+                return handled;
+            }
+        }
+        return std::nullopt;
+    }
+
+    bool WaitForBatch(int64_t sequence, const std::string& endpoint,
+                      std::chrono::milliseconds timeout) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (FindBatch(sequence, endpoint).has_value()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        }
+        return FindBatch(sequence, endpoint).has_value();
+    }
+
+    size_t CountBatches(int64_t sequence, const std::string& endpoint) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return static_cast<size_t>(std::count_if(
+            batches_.begin(), batches_.end(), [&](const HandledBatch& handled) {
+                return handled.metadata.sequence == sequence &&
+                       handled.metadata.endpoint == endpoint;
+            }));
+    }
+
+    std::vector<int64_t> Sequences(const std::string& endpoint,
+                                   int64_t minimum = 0) {
+        std::lock_guard<std::mutex> lock(mu_);
+        std::vector<int64_t> sequences;
+        for (const auto& handled : batches_) {
+            if (handled.metadata.endpoint == endpoint &&
+                handled.metadata.sequence >= minimum) {
+                sequences.push_back(handled.metadata.sequence);
+            }
+        }
+        return sequences;
+    }
+
+    bool ContainsHash(uint64_t hash) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return present_hashes_.contains(hash);
+    }
+
+    size_t StaleNotificationCount() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return stale_notifications_;
+    }
+
+    bool WasSourceMarkedStale(const std::string& cache_pool_key,
+                              const std::string& endpoint,
+                              int64_t last_sequence) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return stale_cache_pool_key_ == cache_pool_key &&
+               stale_metadata_.endpoint == endpoint &&
+               stale_metadata_.sequence == last_sequence &&
+               !stale_reason_.empty();
+    }
+
+   private:
+    std::mutex mu_;
+    std::vector<HandledBatch> batches_;
+    std::unordered_set<uint64_t> present_hashes_;
+    std::string handle_error_;
+    size_t stale_notifications_ = 0;
+    std::string stale_cache_pool_key_;
+    MessageMetadata stale_metadata_;
+    std::string stale_reason_;
+};
+
+std::string PackVllmStoredBatch(uint64_t hash, int64_t dp_rank = 3) {
+    std::stringstream buf;
+    msgpack::packer<std::stringstream> pk(buf);
+    pk.pack_array(3);
+    pk.pack_double(1.25);
+    pk.pack_array(1);
+    pk.pack_map(9);
+    pk.pack(std::string("type"));
+    pk.pack(std::string("BlockStored"));
+    pk.pack(std::string("block_hashes"));
+    pk.pack_array(1);
+    pk.pack_uint64(hash);
+    pk.pack(std::string("parent_block_hash"));
+    pk.pack_nil();
+    pk.pack(std::string("token_ids"));
+    pk.pack_array(2);
+    pk.pack_int32(1);
+    pk.pack_int32(2);
+    pk.pack(std::string("block_size"));
+    pk.pack_int64(2);
+    pk.pack(std::string("lora_id"));
+    pk.pack_nil();
+    pk.pack(std::string("medium"));
+    pk.pack(std::string("GPU"));
+    pk.pack(std::string("lora_name"));
+    pk.pack_nil();
+    pk.pack(std::string("group_idx"));
+    pk.pack_int64(0);
+    pk.pack_int64(dp_rank);
+    return buf.str();
+}
+
+std::string PackVllmRemovedBatch(uint64_t hash, int64_t dp_rank = 3) {
+    std::stringstream buf;
+    msgpack::packer<std::stringstream> pk(buf);
+    pk.pack_array(3);
+    pk.pack_double(1.25);
+    pk.pack_array(1);
+    pk.pack_map(4);
+    pk.pack(std::string("type"));
+    pk.pack(std::string("BlockRemoved"));
+    pk.pack(std::string("block_hashes"));
+    pk.pack_array(1);
+    pk.pack_uint64(hash);
+    pk.pack(std::string("medium"));
+    pk.pack(std::string("GPU"));
+    pk.pack(std::string("group_idx"));
+    pk.pack_int64(0);
+    pk.pack_int64(dp_rank);
+    return buf.str();
+}
+
+std::string PackSglangStoredBatch(int64_t hash, int64_t dp_rank = 3) {
+    std::stringstream buf;
+    msgpack::packer<std::stringstream> pk(buf);
+    pk.pack_array(3);
+    pk.pack_double(1.25);
+    pk.pack_array(1);
+    pk.pack_array(7);
+    pk.pack(std::string("BlockStored"));
+    pk.pack_array(1);
+    pk.pack_int64(hash);
+    pk.pack_nil();
+    pk.pack_array(2);
+    pk.pack_int32(1);
+    pk.pack_int32(2);
+    pk.pack_int64(2);
+    pk.pack_nil();
+    pk.pack(std::string("GPU"));
+    pk.pack_int64(dp_rank);
+    return buf.str();
+}
+
+std::string PackMooncakeStoredBatch(uint64_t event_id, uint64_t hash,
+                                    int64_t batch_dp_rank = 7) {
+    constexpr int64_t kTimestampMilliseconds = 1700000000123;
+    std::stringstream buf;
+    msgpack::packer<std::stringstream> pk(buf);
+    pk.pack_array(3);
+    pk.pack_int64(kTimestampMilliseconds);
+    pk.pack_array(1);
+    pk.pack_map(24);
+    pk.pack(std::string("event_id"));
+    pk.pack_uint64(event_id);
+    pk.pack(std::string("timestamp"));
+    pk.pack_int64(kTimestampMilliseconds);
+    pk.pack(std::string("event_type"));
+    pk.pack(std::string("stored"));
+    pk.pack(std::string("type"));
+    pk.pack(std::string("BlockStored"));
+    pk.pack(std::string("model_name"));
+    pk.pack(std::string("test-model"));
+    pk.pack(std::string("block_size"));
+    pk.pack_int64(2);
+    pk.pack(std::string("additional_salt"));
+    pk.pack_nil();
+    pk.pack(std::string("lora_name"));
+    pk.pack_nil();
+    pk.pack(std::string("tenant_id"));
+    pk.pack(std::string("tenant-a"));
+    pk.pack(std::string("backend_id"));
+    pk.pack(std::string("backend-a"));
+    pk.pack(std::string("medium"));
+    pk.pack(std::string("cpu"));
+    pk.pack(std::string("dp_rank"));
+    pk.pack_int64(7);
+    pk.pack(std::string("group_id"));
+    pk.pack_nil();
+    pk.pack(std::string("object_key"));
+    pk.pack(std::string("object-42"));
+    pk.pack(std::string("connector_block_hash"));
+    pk.pack(std::string("0001020304050607000000000000002a"));
+    pk.pack(std::string("cache_prefix"));
+    pk.pack(std::string("prefix"));
+    pk.pack(std::string("tp_rank"));
+    pk.pack_int64(1);
+    pk.pack(std::string("head_or_tp_rank"));
+    pk.pack_nil();
+    pk.pack(std::string("pp_rank"));
+    pk.pack_int64(0);
+    pk.pack(std::string("seq_hashes"));
+    pk.pack_array(1);
+    pk.pack_uint64(hash);
+    pk.pack(std::string("base_block_idx"));
+    pk.pack_int64(0);
+    pk.pack(std::string("parent_hash"));
+    pk.pack_nil();
+    pk.pack(std::string("parent_block_hash"));
+    pk.pack_nil();
+    pk.pack(std::string("token_ids"));
+    pk.pack_nil();
+    pk.pack_int64(batch_dp_rank);
+    return buf.str();
+}
+
+class MockPublisher {
+   public:
+    MockPublisher()
+        : ctx_(1),
+          pub_(ctx_, ::zmq::socket_type::pub),
+          router_(ctx_, ::zmq::socket_type::router) {
+        pub_.set(::zmq::sockopt::ipv6, 1);
+        pub_.bind("tcp://127.0.0.1:*");
+        router_.set(::zmq::sockopt::ipv6, 1);
+        router_.bind("tcp://127.0.0.1:*");
+        replay_thread_ = std::thread([this] { HandleReplay(); });
+        std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    }
+
+    ~MockPublisher() { Close(); }
+
+    void Close() {
+        if (!closed_.exchange(true)) {
+            if (replay_thread_.joinable()) replay_thread_.join();
+            pub_.close();
+            router_.close();
+        }
+    }
+
+    std::string PubEndpoint() {
+        return pub_.get(::zmq::sockopt::last_endpoint);
+    }
+
+    std::string RouterEndpoint() {
+        return router_.get(::zmq::sockopt::last_endpoint);
+    }
+
+    void Publish(const std::string& topic, const std::string& payload,
+                 uint64_t sequence) {
+        unsigned char sequence_bytes[8];
+        for (int index = 7; index >= 0; --index) {
+            sequence_bytes[index] = static_cast<unsigned char>(sequence & 0xFF);
+            sequence >>= 8;
+        }
+        std::array<::zmq::const_buffer, 3> frames = {
+            ::zmq::buffer(topic),
+            ::zmq::buffer(sequence_bytes, sizeof(sequence_bytes)),
+            ::zmq::buffer(payload),
+        };
+        ::zmq::send_multipart(pub_, frames);
+    }
+
+    void PublishFrames(const std::vector<std::string>& frames) {
+        std::vector<::zmq::const_buffer> buffers;
+        buffers.reserve(frames.size());
+        for (const auto& frame : frames) {
+            buffers.push_back(::zmq::buffer(frame));
+        }
+        ::zmq::send_multipart(pub_, buffers);
+    }
+
+    size_t ReplayRequestCount() const { return replay_requests_.load(); }
+
+    size_t ReplayEventCount() const { return replay_events_.load(); }
+
+    void SetReplayEndDelay(std::chrono::milliseconds delay) {
+        replay_end_delay_ms_.store(delay.count());
+    }
+
+    void SetReplayMaxSequence(uint64_t sequence) {
+        replay_max_sequence_.store(sequence);
+    }
+
+    uint64_t LastReplayFromSequence() const {
+        return last_replay_from_sequence_.load();
+    }
+
+    bool WaitForReplayRequests(size_t count,
+                               std::chrono::milliseconds timeout) const {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (ReplayRequestCount() < count &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return ReplayRequestCount() >= count;
+    }
+
+   private:
+    void HandleReplay() {
+        router_.set(::zmq::sockopt::rcvtimeo, 100);
+        while (!closed_.load()) {
+            std::vector<::zmq::message_t> frames;
+            const auto count = ::zmq::recv_multipart(
+                router_, std::back_inserter(frames), ::zmq::recv_flags::none);
+            if (!count) continue;
+            // REQ adds the empty delimiter automatically; Conductor's DEALER
+            // adds it explicitly. ROUTER therefore sees the vLLM shape below.
+            if (frames.size() != 3 || !frames[1].empty() ||
+                frames[2].size() != 8) {
+                continue;
+            }
+
+            const auto* bytes =
+                static_cast<const unsigned char*>(frames[2].data());
+            uint64_t from_sequence = 0;
+            for (int index = 0; index < 8; ++index) {
+                from_sequence = (from_sequence << 8) | bytes[index];
+            }
+            last_replay_from_sequence_.store(from_sequence);
+            replay_requests_.fetch_add(1);
+
+            const std::string empty;
+            const uint64_t max_sequence = replay_max_sequence_.load();
+            for (uint64_t sequence = from_sequence; sequence <= max_sequence;
+                 ++sequence) {
+                std::array<unsigned char, 8> sequence_bytes{};
+                uint64_t value = sequence;
+                for (int index = 7; index >= 0; --index) {
+                    sequence_bytes[index] =
+                        static_cast<unsigned char>(value & 0xFF);
+                    value >>= 8;
+                }
+                const auto payload = PackVllmStoredBatch(sequence);
+                // Match vLLM/SGLang: DEALER receives
+                // [empty, sequence, payload] after ROUTER removes identity.
+                std::array<::zmq::const_buffer, 4> reply = {
+                    ::zmq::buffer(frames[0].data(), frames[0].size()),
+                    ::zmq::buffer(empty),
+                    ::zmq::buffer(sequence_bytes),
+                    ::zmq::buffer(payload),
+                };
+                ::zmq::send_multipart(router_, reply);
+                replay_events_.fetch_add(1);
+            }
+
+            const auto delay = replay_end_delay_ms_.load();
+            if (delay > 0) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(delay));
+            }
+            std::array<unsigned char, 8> end_sequence{};
+            end_sequence.fill(0xFF);
+            std::array<::zmq::const_buffer, 4> end = {
+                ::zmq::buffer(frames[0].data(), frames[0].size()),
+                ::zmq::buffer(empty),
+                ::zmq::buffer(end_sequence),
+                ::zmq::buffer(empty),
+            };
+            ::zmq::send_multipart(router_, end);
+        }
+    }
+
+    ::zmq::context_t ctx_;
+    ::zmq::socket_t pub_;
+    ::zmq::socket_t router_;
+    std::atomic<bool> closed_{false};
+    std::atomic<size_t> replay_requests_{0};
+    std::atomic<size_t> replay_events_{0};
+    std::atomic<int64_t> replay_end_delay_ms_{0};
+    std::atomic<uint64_t> replay_max_sequence_{15};
+    std::atomic<uint64_t> last_replay_from_sequence_{0};
+    std::thread replay_thread_;
+};
+
+ZMQClientConfig TestConfig(MockPublisher& publisher) {
+    ZMQClientConfig config;
+    config.cache_pool_key = "test-pod";
+    config.endpoint = publisher.PubEndpoint();
+    config.replay_endpoint = publisher.RouterEndpoint();
+    config.model_name = "test-model";
+    config.publisher_kind = PublisherKind::kVllm;
+    config.poll_timeout = std::chrono::milliseconds(100);
+    config.replay_timeout = std::chrono::milliseconds(1000);
+    config.reconnect_delay = std::chrono::milliseconds(100);
+    return config;
+}
+
+template <typename Publish>
+bool PublishUntilHandled(MockEventHandler& handler, int64_t sequence,
+                         const std::string& endpoint, Publish publish) {
+    for (int attempt = 0; attempt < 20; ++attempt) {
+        publish();
+        if (handler.WaitForBatch(sequence, endpoint,
+                                 std::chrono::milliseconds(200))) {
+            return true;
+        }
+    }
+    return false;
+}
+
+bool WaitForStale(ZMQClient& client, std::chrono::milliseconds timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (!client.IsStale() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    return client.IsStale();
+}
+
+const VllmStoredEvent* GetVllmStored(const HandledBatch& handled) {
+    const auto* batch = std::get_if<VllmEventBatch>(&handled.batch);
+    if (batch == nullptr || batch->events.size() != 1 ||
+        !batch->events[0].event.has_value()) {
+        return nullptr;
+    }
+    return std::get_if<VllmStoredEvent>(&*batch->events[0].event);
+}
+
+const MooncakeStoredEvent* GetMooncakeStored(const HandledBatch& handled) {
+    const auto* batch = std::get_if<MooncakeEventBatch>(&handled.batch);
+    if (batch == nullptr || batch->events.size() != 1 ||
+        !batch->events[0].event.has_value()) {
+        return nullptr;
+    }
+    return std::get_if<MooncakeStoredEvent>(&*batch->events[0].event);
+}
+
+TEST(ValidateConfig, RequiresOnlyLiveEndpoint) {
+    ZMQClientConfig config;
+    EXPECT_FALSE(ValidateConfig(config).empty());
+    config.endpoint = "tcp://127.0.0.1:5557";
+    config.replay_endpoint.clear();
+    EXPECT_TRUE(ValidateConfig(config).empty());
+}
+
+TEST(ZMQClient, ConnectSuccessWithReplaySocket) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    EXPECT_EQ(client.Connect(), "");
+    EXPECT_TRUE(ZMQClientTestPeer::HasReplaySocket(client));
+    client.Stop();
+}
+
+TEST(ZMQClient, MooncakeIgnoresVllmReplayEndpoint) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.publisher_kind = PublisherKind::kMooncake;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Connect(), "");
+    EXPECT_FALSE(ZMQClientTestPeer::HasReplaySocket(client));
+    client.Stop();
+}
+
+TEST(ZMQClient, SglangEnablesReplaySocket) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.publisher_kind = PublisherKind::kSglang;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Connect(), "");
+    EXPECT_TRUE(ZMQClientTestPeer::HasReplaySocket(client));
+    client.Stop();
+}
+
+TEST(ZMQClient, SglangRoutesNativeAndMooncakeFallbackEnvelopes) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.publisher_kind = PublisherKind::kSglang;
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackSglangStoredBatch(-42), 10);
+    }));
+    const auto native = handler->FindBatch(10, endpoint);
+    ASSERT_TRUE(native.has_value());
+    EXPECT_TRUE(
+        std::holds_alternative<mooncake::conductor::zmq::SglangEventBatch>(
+            native->batch));
+    EXPECT_EQ(native->metadata.publisher_kind, PublisherKind::kSglang);
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 11, endpoint, [&] {
+        publisher.Publish("", PackMooncakeStoredBatch(9001, 42), 11);
+    }));
+    const auto fallback = handler->FindBatch(11, endpoint);
+    ASSERT_TRUE(fallback.has_value());
+    const auto* stored = GetMooncakeStored(*fallback);
+    ASSERT_NE(stored, nullptr);
+    EXPECT_EQ(stored->fields.event_id, 9001u);
+    EXPECT_EQ(fallback->metadata.publisher_kind, PublisherKind::kSglang);
+    client.Stop();
+}
+
+TEST(ZMQClient, ConnectAlreadyConnectedIsNoop) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    EXPECT_EQ(client.Connect(), "");
+    EXPECT_EQ(client.Connect(), "");
+    EXPECT_TRUE(ZMQClientTestPeer::HasReplaySocket(client));
+    client.Stop();
+}
+
+TEST(ZMQClient, StartStopGracefulWithReplayConfigured) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    EXPECT_EQ(client.Start(), "");
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+
+    const auto start = std::chrono::steady_clock::now();
+    client.Stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - start,
+              std::chrono::seconds(2));
+}
+
+TEST(ZMQClient, StopIsIdempotentWithReplayConfigured) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    ASSERT_EQ(client.Start(), "");
+    client.Stop();
+    client.Stop();
+}
+
+TEST(ZMQClient, TruncatedMultipartDoesNotBlockStop) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 76, publisher.PubEndpoint(), [&] {
+        publisher.Publish("", PackVllmStoredBatch(76), 76);
+    }));
+
+    publisher.PublishFrames({"truncated"});
+    std::this_thread::sleep_for(std::chrono::milliseconds(250));
+
+    auto stopped = std::async(std::launch::async, [&] { client.Stop(); });
+    const auto status = stopped.wait_for(std::chrono::milliseconds(500));
+    if (status != std::future_status::ready) {
+        // Release an old three-recv implementation so a regression reports a
+        // failure instead of hanging the entire test process.
+        publisher.PublishFrames({"12345678", "rescue"});
+    }
+    EXPECT_EQ(status, std::future_status::ready);
+    stopped.get();
+}
+
+TEST(ZMQClient, ExtraMultipartFramesAreDrainedBeforeNextMessage) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    ASSERT_EQ(client.Start(), "");
+
+    for (int attempt = 0; attempt < 10; ++attempt) {
+        publisher.PublishFrames({"topic", "12345678", "payload", "extra"});
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    ASSERT_TRUE(PublishUntilHandled(*handler, 77, publisher.PubEndpoint(), [&] {
+        publisher.Publish("", PackVllmStoredBatch(77), 77);
+    }));
+
+    EXPECT_TRUE(handler->FindBatch(77, publisher.PubEndpoint()).has_value());
+    client.Stop();
+}
+
+TEST(ZMQClient, VllmKindRoutesEmptyAndMisleadingTopics) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    const auto config = TestConfig(publisher);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    const auto empty_topic_payload = PackVllmStoredBatch(42);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 41, endpoint, [&] {
+        publisher.Publish("", empty_topic_payload, 41);
+    }));
+    const auto misleading_topic_payload = PackVllmStoredBatch(43);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 42, endpoint, [&] {
+        publisher.Publish("mooncake", misleading_topic_payload, 42);
+    }));
+
+    const auto empty_topic = handler->FindBatch(41, endpoint);
+    ASSERT_TRUE(empty_topic.has_value());
+    EXPECT_EQ(empty_topic->metadata.publisher_kind, PublisherKind::kVllm);
+    EXPECT_EQ(empty_topic->metadata.endpoint, endpoint);
+    EXPECT_EQ(empty_topic->metadata.topic, "");
+    EXPECT_EQ(empty_topic->metadata.sequence, 41);
+    const auto* empty_batch = std::get_if<VllmEventBatch>(&empty_topic->batch);
+    ASSERT_NE(empty_batch, nullptr);
+    EXPECT_DOUBLE_EQ(empty_batch->timestamp_seconds, 1.25);
+    EXPECT_EQ(empty_batch->data_parallel_rank, std::optional<int64_t>(3));
+    const auto* empty_stored = GetVllmStored(*empty_topic);
+    ASSERT_NE(empty_stored, nullptr);
+    ASSERT_EQ(empty_stored->block_hashes.size(), 1u);
+    EXPECT_EQ(std::get<uint64_t>(empty_stored->block_hashes[0]), 42u);
+
+    const auto misleading_topic = handler->FindBatch(42, endpoint);
+    ASSERT_TRUE(misleading_topic.has_value());
+    EXPECT_EQ(misleading_topic->metadata.publisher_kind, PublisherKind::kVllm);
+    EXPECT_EQ(misleading_topic->metadata.endpoint, endpoint);
+    EXPECT_EQ(misleading_topic->metadata.topic, "mooncake");
+    EXPECT_EQ(misleading_topic->metadata.sequence, 42);
+    const auto* misleading_stored = GetVllmStored(*misleading_topic);
+    ASSERT_NE(misleading_stored, nullptr);
+    ASSERT_EQ(misleading_stored->block_hashes.size(), 1u);
+    EXPECT_EQ(std::get<uint64_t>(misleading_stored->block_hashes[0]), 43u);
+    client.Stop();
+}
+
+TEST(ZMQClient, EqualTopicsOnDistinctEndpointsPreserveProvenance) {
+    MockPublisher publisher_a;
+    MockPublisher publisher_b;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config_a = TestConfig(publisher_a);
+    auto config_b = TestConfig(publisher_b);
+    config_a.cache_pool_key = "instance-a";
+    config_b.cache_pool_key = "instance-b";
+    const std::string endpoint_a = config_a.endpoint;
+    const std::string endpoint_b = config_b.endpoint;
+    ASSERT_NE(endpoint_a, endpoint_b);
+    ZMQClient client_a(config_a, handler);
+    ZMQClient client_b(config_b, handler);
+    ASSERT_EQ(client_a.Start(), "");
+    ASSERT_EQ(client_b.Start(), "");
+
+    const auto payload_a = PackVllmStoredBatch(101);
+    const auto payload_b = PackVllmStoredBatch(202);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 77, endpoint_a, [&] {
+        publisher_a.Publish("shared-topic", payload_a, 77);
+    }));
+    ASSERT_TRUE(PublishUntilHandled(*handler, 77, endpoint_b, [&] {
+        publisher_b.Publish("shared-topic", payload_b, 77);
+    }));
+
+    const auto handled_a = handler->FindBatch(77, endpoint_a);
+    const auto handled_b = handler->FindBatch(77, endpoint_b);
+    ASSERT_TRUE(handled_a.has_value());
+    ASSERT_TRUE(handled_b.has_value());
+    EXPECT_EQ(handled_a->metadata.topic, "shared-topic");
+    EXPECT_EQ(handled_b->metadata.topic, "shared-topic");
+    EXPECT_EQ(handled_a->metadata.publisher_kind, PublisherKind::kVllm);
+    EXPECT_EQ(handled_b->metadata.publisher_kind, PublisherKind::kVllm);
+    const auto* stored_a = GetVllmStored(*handled_a);
+    const auto* stored_b = GetVllmStored(*handled_b);
+    ASSERT_NE(stored_a, nullptr);
+    ASSERT_NE(stored_b, nullptr);
+    EXPECT_EQ(std::get<uint64_t>(stored_a->block_hashes[0]), 101u);
+    EXPECT_EQ(std::get<uint64_t>(stored_b->block_hashes[0]), 202u);
+    client_a.Stop();
+    client_b.Stop();
+}
+
+TEST(ZMQClient, MooncakeLiveOnlyConsumesEmptyAndMisleadingTopics) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.publisher_kind = PublisherKind::kMooncake;
+    config.replay_endpoint.clear();
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+    EXPECT_FALSE(ZMQClientTestPeer::HasReplaySocket(client));
+
+    const auto empty_topic_payload = PackMooncakeStoredBatch(9001, 42);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 101, endpoint, [&] {
+        publisher.Publish("", empty_topic_payload, 101);
+    }));
+    const auto misleading_topic_payload = PackMooncakeStoredBatch(9002, 43);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 102, endpoint, [&] {
+        publisher.Publish("vllm", misleading_topic_payload, 102);
+    }));
+
+    const auto empty_topic = handler->FindBatch(101, endpoint);
+    ASSERT_TRUE(empty_topic.has_value());
+    EXPECT_EQ(empty_topic->metadata.publisher_kind, PublisherKind::kMooncake);
+    EXPECT_EQ(empty_topic->metadata.endpoint, endpoint);
+    EXPECT_EQ(empty_topic->metadata.topic, "");
+    EXPECT_EQ(empty_topic->metadata.sequence, 101);
+    const auto* empty_batch =
+        std::get_if<MooncakeEventBatch>(&empty_topic->batch);
+    ASSERT_NE(empty_batch, nullptr);
+    EXPECT_EQ(empty_batch->timestamp_milliseconds, 1700000000123);
+    EXPECT_EQ(empty_batch->data_parallel_rank, std::optional<int64_t>(7));
+    const auto* empty_stored = GetMooncakeStored(*empty_topic);
+    ASSERT_NE(empty_stored, nullptr);
+    EXPECT_EQ(empty_stored->fields.event_id, 9001u);
+    EXPECT_EQ(empty_stored->fields.backend_id, "backend-a");
+    EXPECT_EQ(empty_stored->object.object_key,
+              std::optional<std::string>("object-42"));
+    EXPECT_EQ(empty_stored->object.seq_hashes, (std::vector<uint64_t>{42}));
+    EXPECT_FALSE(empty_stored->parent_hash.has_value());
+    EXPECT_FALSE(empty_stored->token_ids.has_value());
+
+    const auto misleading_topic = handler->FindBatch(102, endpoint);
+    ASSERT_TRUE(misleading_topic.has_value());
+    EXPECT_EQ(misleading_topic->metadata.publisher_kind,
+              PublisherKind::kMooncake);
+    EXPECT_EQ(misleading_topic->metadata.endpoint, endpoint);
+    EXPECT_EQ(misleading_topic->metadata.topic, "vllm");
+    EXPECT_EQ(misleading_topic->metadata.sequence, 102);
+    const auto* misleading_stored = GetMooncakeStored(*misleading_topic);
+    ASSERT_NE(misleading_stored, nullptr);
+    EXPECT_EQ(misleading_stored->fields.event_id, 9002u);
+    EXPECT_EQ(misleading_stored->object.seq_hashes,
+              (std::vector<uint64_t>{43}));
+    EXPECT_EQ(publisher.ReplayRequestCount(), 0u);
+
+    const auto start = std::chrono::steady_clock::now();
+    client.Stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - start,
+              std::chrono::seconds(2));
+    EXPECT_FALSE(ZMQClientTestPeer::HasReplaySocket(client));
+}
+
+TEST(ZMQClient, SequenceTrackingWithReplayConfigured) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    const auto config = TestConfig(publisher);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+    EXPECT_EQ(client.GetLastSequence(), -1);
+
+    const auto first_payload = PackVllmStoredBatch(1);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", first_payload, 10);
+    }));
+    for (uint64_t sequence = 11; sequence <= 14; ++sequence) {
+        publisher.Publish("", PackVllmStoredBatch(sequence), sequence);
+    }
+    ASSERT_TRUE(handler->WaitForBatch(14, endpoint, std::chrono::seconds(2)));
+    EXPECT_EQ(client.GetLastSequence(), 14);
+    EXPECT_EQ(publisher.ReplayRequestCount(), 0u);
+    client.Stop();
+}
+
+TEST(ZMQClient, EventGapReplaysMissingMessagesBeforeLiveMessage) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    const auto config = TestConfig(publisher);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    const auto first_payload = PackVllmStoredBatch(1);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", first_payload, 10);
+    }));
+    EXPECT_EQ(client.GetDroppedEvents(), 0);
+    EXPECT_EQ(client.GetGapCount(), 0);
+
+    publisher.Publish("", PackVllmStoredBatch(2), 15);
+    for (int64_t sequence = 11; sequence <= 14; ++sequence) {
+        ASSERT_TRUE(
+            handler->WaitForBatch(sequence, endpoint, std::chrono::seconds(2)));
+    }
+    ASSERT_TRUE(handler->WaitForBatch(15, endpoint, std::chrono::seconds(2)));
+    EXPECT_EQ(client.GetLastSequence(), 15);
+    EXPECT_EQ(publisher.ReplayRequestCount(), 1u);
+    EXPECT_EQ(publisher.ReplayEventCount(), 5u);
+    EXPECT_EQ(handler->CountBatches(15, endpoint), 1u);
+    EXPECT_EQ(handler->Sequences(endpoint, 11),
+              (std::vector<int64_t>{11, 12, 13, 14, 15}));
+    EXPECT_EQ(client.GetDroppedEvents(), 4);
+    EXPECT_EQ(client.GetGapCount(), 1);
+    client.Stop();
+}
+
+TEST(ZMQClient, ReplayTimeoutBuffersLiveBoundaryAndPreservesOrder) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.replay_timeout = std::chrono::milliseconds(100);
+    config.replay_recovery_timeout = std::chrono::seconds(2);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+    }));
+
+    publisher.SetReplayEndDelay(std::chrono::milliseconds(150));
+    publisher.Publish("", PackVllmRemovedBatch(11), 12);
+    ASSERT_TRUE(publisher.WaitForReplayRequests(1, std::chrono::seconds(1)));
+    EXPECT_FALSE(
+        handler->WaitForBatch(12, endpoint, std::chrono::milliseconds(50)));
+    EXPECT_EQ(client.GetLastSequence(), 10);
+
+    publisher.SetReplayEndDelay(std::chrono::milliseconds(0));
+    ASSERT_TRUE(handler->WaitForBatch(12, endpoint, std::chrono::seconds(2)));
+    EXPECT_EQ(handler->Sequences(endpoint, 11), (std::vector<int64_t>{11, 12}));
+    EXPECT_EQ(handler->CountBatches(11, endpoint), 1u);
+    EXPECT_EQ(handler->CountBatches(12, endpoint), 1u);
+    EXPECT_FALSE(handler->ContainsHash(11));
+    EXPECT_GE(publisher.ReplayRequestCount(), 2u);
+    EXPECT_EQ(client.GetLastSequence(), 12);
+    EXPECT_FALSE(client.IsStale());
+    client.Stop();
+}
+
+TEST(ZMQClient, PendingLiveBoundaryIsRecoveredAcrossReconnect) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.replay_timeout = std::chrono::milliseconds(100);
+    config.replay_recovery_timeout = std::chrono::seconds(2);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+    }));
+
+    publisher.SetReplayEndDelay(std::chrono::milliseconds(150));
+    publisher.Publish("", PackVllmStoredBatch(2), 15);
+    ASSERT_TRUE(publisher.WaitForReplayRequests(1, std::chrono::seconds(1)));
+    EXPECT_FALSE(
+        handler->WaitForBatch(15, endpoint, std::chrono::milliseconds(50)));
+
+    publisher.SetReplayEndDelay(std::chrono::milliseconds(0));
+    publisher.SetReplayMaxSequence(15);
+    ZMQClientTestPeer::MarkDisconnected(client);
+    ASSERT_TRUE(handler->WaitForBatch(15, endpoint, std::chrono::seconds(3)));
+
+    for (int64_t sequence = 11; sequence <= 14; ++sequence) {
+        ASSERT_TRUE(
+            handler->WaitForBatch(sequence, endpoint, std::chrono::seconds(2)));
+    }
+    EXPECT_EQ(handler->CountBatches(15, endpoint), 1u);
+    EXPECT_EQ(handler->Sequences(endpoint, 11),
+              (std::vector<int64_t>{11, 12, 13, 14, 15}));
+    EXPECT_EQ(client.GetLastSequence(), 15);
+    EXPECT_GE(publisher.ReplayRequestCount(), 2u);
+    EXPECT_EQ(publisher.LastReplayFromSequence(), 11u);
+    EXPECT_FALSE(client.IsStale());
+    client.Stop();
+}
+
+TEST(ZMQClient, UnrecoverableGapMarksSourceStaleWithoutApplyingBoundary) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+    }));
+    publisher.SetReplayMaxSequence(10);
+    publisher.Publish("", PackVllmStoredBatch(2), 15);
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!client.IsStale() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    EXPECT_TRUE(client.IsStale());
+    EXPECT_FALSE(client.GetStaleReason().empty());
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_TRUE(handler->WasSourceMarkedStale("test-pod", endpoint, 10));
+    EXPECT_FALSE(handler->FindBatch(15, endpoint).has_value());
+    EXPECT_EQ(client.GetLastSequence(), 10);
+    client.Stop();
+}
+
+TEST(ZMQClient, RecoveryDeadlineMarksSourceStale) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.replay_timeout = std::chrono::milliseconds(50);
+    config.replay_recovery_timeout = std::chrono::milliseconds(150);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+    }));
+    publisher.SetReplayEndDelay(std::chrono::milliseconds(500));
+    publisher.Publish("", PackVllmStoredBatch(2), 15);
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!client.IsStale() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    EXPECT_TRUE(client.IsStale());
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_FALSE(handler->FindBatch(15, endpoint).has_value());
+    EXPECT_EQ(client.GetLastSequence(), 10);
+    client.Stop();
+}
+
+TEST(ZMQClient, RecoveryBufferLimitMarksSourceStale) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.max_recovery_buffered_messages = 3;
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+    }));
+    publisher.Publish("", PackVllmStoredBatch(2), 15);
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!client.IsStale() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    EXPECT_TRUE(client.IsStale());
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_FALSE(handler->FindBatch(15, endpoint).has_value());
+    EXPECT_EQ(client.GetLastSequence(), 10);
+    client.Stop();
+}
+
+TEST(ZMQClient, EventGapMarksSourceStaleWhenReplayUnavailable) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    auto config = TestConfig(publisher);
+    config.replay_endpoint.clear();
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    const auto first_payload = PackVllmStoredBatch(1);
+    ASSERT_TRUE(PublishUntilHandled(*handler, 10, endpoint, [&] {
+        publisher.Publish("", first_payload, 10);
+    }));
+    publisher.Publish("", PackVllmStoredBatch(2), 13);
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!client.IsStale() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    EXPECT_TRUE(client.IsStale());
+    EXPECT_FALSE(handler->FindBatch(13, endpoint).has_value());
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_EQ(client.GetLastSequence(), 10);
+    EXPECT_EQ(publisher.ReplayRequestCount(), 0u);
+    EXPECT_EQ(client.GetDroppedEvents(), 2);
+    EXPECT_EQ(client.GetGapCount(), 1);
+    client.Stop();
+}
+
+TEST(ZMQClient, HandlerFailureMarksLiveOnlySourceStaleWithoutAdvancing) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    handler->SetHandleError("index write failed");
+    auto config = TestConfig(publisher);
+    config.replay_endpoint.clear();
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    for (int attempt = 0; attempt < 20 && !client.IsStale(); ++attempt) {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+        std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    }
+
+    ASSERT_TRUE(WaitForStale(client, std::chrono::seconds(1)));
+    EXPECT_EQ(client.GetLastSequence(), -1);
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_TRUE(handler->WasSourceMarkedStale("test-pod", endpoint, -1));
+    EXPECT_NE(client.GetStaleReason().find(
+                  "event handler failed: index write failed"),
+              std::string::npos);
+    EXPECT_FALSE(handler->FindBatch(10, endpoint).has_value());
+    client.Stop();
+}
+
+TEST(ZMQClient, HandlerFailureMarksReplaySourceStaleWithoutAdvancing) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    handler->SetHandleError("index write failed");
+    auto config = TestConfig(publisher);
+    const std::string endpoint = config.endpoint;
+    ZMQClient client(config, handler);
+    ASSERT_EQ(client.Start(), "");
+
+    for (int attempt = 0; attempt < 20 && !client.IsStale(); ++attempt) {
+        publisher.Publish("", PackVllmStoredBatch(1), 10);
+        std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    }
+
+    ASSERT_TRUE(WaitForStale(client, std::chrono::seconds(1)));
+    EXPECT_EQ(client.GetLastSequence(), -1);
+    EXPECT_EQ(handler->StaleNotificationCount(), 1u);
+    EXPECT_TRUE(handler->WasSourceMarkedStale("test-pod", endpoint, -1));
+    EXPECT_NE(client.GetStaleReason().find(
+                  "event handler failed: index write failed"),
+              std::string::npos);
+    EXPECT_FALSE(handler->FindBatch(10, endpoint).has_value());
+    client.Stop();
+}
+
+TEST(ZMQClient, ReconnectRequestsReplayFromNextSequence) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    ASSERT_EQ(client.Connect(), "");
+    ASSERT_TRUE(ZMQClientTestPeer::HasReplaySocket(client));
+    ZMQClientTestPeer::SetLastSequence(client, 10);
+
+    ZMQClientTestPeer::MarkDisconnected(client);
+    ZMQClientTestPeer::HandleReconnect(client);
+
+    EXPECT_TRUE(ZMQClientTestPeer::IsConnected(client));
+    ASSERT_TRUE(publisher.WaitForReplayRequests(1, std::chrono::seconds(2)));
+    for (int64_t sequence = 11; sequence <= 15; ++sequence) {
+        ASSERT_TRUE(handler->WaitForBatch(sequence, publisher.PubEndpoint(),
+                                          std::chrono::seconds(2)));
+    }
+    EXPECT_EQ(publisher.ReplayRequestCount(), 1u);
+    EXPECT_EQ(publisher.LastReplayFromSequence(), 11u);
+    EXPECT_EQ(publisher.ReplayEventCount(), 5u);
+    EXPECT_EQ(client.GetLastSequence(), 15);
+
+    publisher.Publish("", PackVllmStoredBatch(15), 15);
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(handler->CountBatches(15, publisher.PubEndpoint()), 1u);
+    client.Stop();
+}
+
+TEST(ZMQClient, FailedReconnectDoesNotRequestReplayUntilSuccess) {
+    MockPublisher publisher;
+    auto handler = std::make_shared<MockEventHandler>();
+    ZMQClient client(TestConfig(publisher), handler);
+    ZMQClientTestPeer::SetLastSequence(client, 10);
+
+    ZMQClientTestPeer::SetEndpoint(client, "not-a-valid-zmq-endpoint");
+    ZMQClientTestPeer::HandleReconnect(client);
+    EXPECT_FALSE(ZMQClientTestPeer::IsConnected(client));
+    EXPECT_FALSE(ZMQClientTestPeer::HasReplaySocket(client));
+    EXPECT_EQ(publisher.ReplayRequestCount(), 0u);
+
+    ZMQClientTestPeer::SetEndpoint(client, publisher.PubEndpoint());
+    ZMQClientTestPeer::HandleReconnect(client);
+    EXPECT_TRUE(ZMQClientTestPeer::IsConnected(client));
+    EXPECT_TRUE(ZMQClientTestPeer::HasReplaySocket(client));
+    ASSERT_TRUE(publisher.WaitForReplayRequests(1, std::chrono::seconds(2)));
+    EXPECT_EQ(publisher.ReplayRequestCount(), 1u);
+    EXPECT_EQ(publisher.LastReplayFromSequence(), 11u);
+    client.Stop();
+}
+
+}  // namespace
diff --git a/mooncake-ep/BuildEpExt.cmake b/mooncake-ep/BuildEpExt.cmake
deleted file mode 100644
index 4a5a661ed4..0000000000
--- a/mooncake-ep/BuildEpExt.cmake
+++ /dev/null
@@ -1,110 +0,0 @@
-# BuildEpExt.cmake - Build the Mooncake EP Python extension.
-#
-# Invoked at build time via cmake -P from the root CMakeLists.txt when
-# WITH_EP=ON.  Variables are passed with -D from the custom target:
-#
-#   SOURCE_DIR          - mooncake-ep source directory
-#   EP_CUDA_MAJOR       - CUDA major version (integer)
-#   EP_TORCH_VERSIONS   - pipe-separated (|) PyTorch versions to build for
-#                         (empty = use the currently-installed torch)
-#   TORCH_CUDA_ARCH_LIST - pipe-separated CUDA arch list forwarded to torch
-#   STAGING_DIR         - destination directory for the built .so files
-#   ENGINE_SO_PATH      - absolute path to the built engine.cpython-XYZ.so
-#   EP_USE_MUSA         - set to "1" when building for MUSA (MTLink path)
-#   EP_USE_MACA         - set to "1" when building for MACA (MTLink path)
-
-cmake_minimum_required(VERSION 3.16)
-
-# Include common build utilities.
-include("${SOURCE_DIR}/../mooncake-common/SetupPyTorchEnv.cmake")
-
-# Restore pipe-separated strings back to CMake semicolon-separated lists.
-if(EP_TORCH_VERSIONS)
-  string(REPLACE "|" ";" EP_TORCH_VERSIONS "${EP_TORCH_VERSIONS}")
-endif()
-if(TORCH_CUDA_ARCH_LIST)
-  string(REPLACE "|" ";" TORCH_CUDA_ARCH_LIST "${TORCH_CUDA_ARCH_LIST}")
-endif()
-
-# ---------------------------------------------------------------------------
-# 1. Set up the build environment.
-# ---------------------------------------------------------------------------
-# Clear jobserver variables so that sub-processes started by setup.py do not
-# try to connect to the parent ninja's jobserver pipe FDs, which are not
-# inherited and cause: "ninja: error: Could not initialize jobserver: Invalid
-# file descriptors".
-set(ENV{MAKEFLAGS} "")
-set(ENV{MFLAGS} "")
-set(ENV{TORCH_CUDA_ARCH_LIST} "${TORCH_CUDA_ARCH_LIST}")
-if(EP_USE_MUSA)
-  set(ENV{MOONCAKE_EP_USE_MUSA} "1")
-else()
-  unset(ENV{MOONCAKE_EP_USE_MUSA})
-endif()
-if(EP_USE_MACA)
-  set(ENV{MOONCAKE_EP_USE_MACA} "1")
-  if(DEFINED ENV{MACA_PATH})
-    set(ENV{MACA_HOME} "$ENV{MACA_PATH}")
-  elseif(DEFINED ENV{MACA_HOME})
-    set(ENV{MACA_PATH} "$ENV{MACA_HOME}")
-  endif()
-else()
-  unset(ENV{MOONCAKE_EP_USE_MACA})
-endif()
-
-# ---------------------------------------------------------------------------
-# 2. Ensure engine.so exists in mooncake-wheel/mooncake/ for setup.py linking.
-# ---------------------------------------------------------------------------
-# setup.py links against -l:engine.so in ../mooncake-wheel/mooncake/.
-# During the make phase only the versioned engine.cpython-XYZ.so exists in
-# the build tree; create a bare engine.so symlink so the linker can find it.
-set(_wheel_mooncake_dir "${SOURCE_DIR}/../mooncake-wheel/mooncake")
-set(_engine_symlink "${_wheel_mooncake_dir}/engine.so")
-if(ENGINE_SO_PATH AND NOT EXISTS "${_engine_symlink}")
-  message(STATUS "[EP] Creating engine.so symlink -> ${ENGINE_SO_PATH}")
-  execute_process(
-    COMMAND ${CMAKE_COMMAND} -E create_symlink "${ENGINE_SO_PATH}" "${_engine_symlink}"
-  )
-endif()
-
-# ---------------------------------------------------------------------------
-# 3. Build the EP Python extension.
-# ---------------------------------------------------------------------------
-if("${EP_TORCH_VERSIONS}" STREQUAL "")
-  message(STATUS "[EP] Building with currently-installed PyTorch")
-  execute_process(
-    COMMAND ${Python3_EXECUTABLE} setup.py build_ext --build-lib .
-    WORKING_DIRECTORY "${SOURCE_DIR}"
-    RESULT_VARIABLE _ret
-  )
-  if(NOT _ret EQUAL 0)
-    message(FATAL_ERROR "[EP] Extension build failed (exit code: ${_ret})")
-  endif()
-else()
-  message(STATUS "[EP] Building for PyTorch versions: ${EP_TORCH_VERSIONS}")
-  foreach(_version IN LISTS EP_TORCH_VERSIONS)
-    install_pytorch_wheel("${_version}" "${EP_CUDA_MAJOR}" "${EP_CUDA_MINOR}" "[EP]")
-
-    execute_process(
-      COMMAND ${Python3_EXECUTABLE} setup.py build_ext --build-lib . --force
-      WORKING_DIRECTORY "${SOURCE_DIR}"
-      RESULT_VARIABLE _ret
-    )
-    if(NOT _ret EQUAL 0)
-      message(FATAL_ERROR "[EP] Extension build failed for PyTorch ${_version}")
-    endif()
-  endforeach()
-endif()
-
-# ---------------------------------------------------------------------------
-# 4. Copy the built .so files to the staging directory.
-# ---------------------------------------------------------------------------
-file(MAKE_DIRECTORY "${STAGING_DIR}")
-file(GLOB _so_files "${SOURCE_DIR}/mooncake/*.so")
-foreach(_so IN LISTS _so_files)
-  get_filename_component(_fname "${_so}" NAME)
-  message(STATUS "[EP] Staging ${_fname} -> ${STAGING_DIR}")
-  file(COPY "${_so}" DESTINATION "${STAGING_DIR}" NO_SOURCE_PERMISSIONS)
-endforeach()
-
-message(STATUS "[EP] Mooncake EP extension build complete")
diff --git a/mooncake-ep/CMakeLists.txt b/mooncake-ep/CMakeLists.txt
index 11cf38c1f7..573748c127 100644
--- a/mooncake-ep/CMakeLists.txt
+++ b/mooncake-ep/CMakeLists.txt
@@ -1,33 +1,15 @@
 cmake_minimum_required(VERSION 3.16)
 project(mooncake-ep)
 
-# Find PyTorch's CMake prefix path
-execute_process(
-    COMMAND ${PYTHON_EXECUTABLE} -c "import torch; print(torch.utils.cmake_prefix_path)"
-    OUTPUT_VARIABLE PYTORCH_CMAKE_PATH
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-if(NOT PYTORCH_CMAKE_PATH)
-  message(WARNING "Could not find PyTorch CMake path! Please set Torch_DIR.")
-else ()
-  message(STATUS "Found PyTorch CMake path: ${PYTORCH_CMAKE_PATH}")
-  list(APPEND CMAKE_PREFIX_PATH "${PYTORCH_CMAKE_PATH}/Torch")
+find_package(
+  Python3
+  COMPONENTS Interpreter Development.Module
+  REQUIRED)
+
+if(USE_CUDA)
+  enable_language(CUDA)
+  find_package(CUDAToolkit REQUIRED)
 endif()
 
-set(TORCH_CUDA_ARCH_LIST "8.0;9.0")
-
-find_package(CUDAToolkit REQUIRED)
-# https://discuss.pytorch.org/t/failed-to-find-nvtoolsext/179635/13
-if(NOT TARGET CUDA::nvToolsExt AND TARGET CUDA::nvtx3)
-  add_library(CUDA::nvToolsExt INTERFACE IMPORTED)
-  target_compile_definitions(
-      CUDA::nvToolsExt INTERFACE
-      TORCH_CUDA_USE_NVTX3
-  )
-  target_link_libraries(CUDA::nvToolsExt INTERFACE CUDA::nvtx3)
-endif()
-find_package(Torch REQUIRED)
-include_directories(${TORCH_INCLUDE_DIRS})
-
 include_directories(include)
 add_subdirectory(src)
diff --git a/mooncake-ep/benchmarks/elastic_buffer_perf.py b/mooncake-ep/benchmarks/elastic_buffer_perf.py
index 0bd2d10d13..edac6da8f6 100644
--- a/mooncake-ep/benchmarks/elastic_buffer_perf.py
+++ b/mooncake-ep/benchmarks/elastic_buffer_perf.py
@@ -44,6 +44,12 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--num-sms", type=int, default=24)
     parser.add_argument("--warmup", type=int, default=5)
     parser.add_argument("--iters", type=int, default=20)
+    parser.add_argument(
+        "--transport",
+        choices=("auto", "ibgda", "nccl"),
+        default=os.getenv("MOONCAKE_EP_TRANSPORT", "auto"),
+        help="Device transport; auto prefers NCCL and falls back to IPC + IBGDA.",
+    )
     parser.add_argument(
         "--route",
         choices=("alltoall", "local", "cross"),
@@ -96,7 +102,9 @@ def make_route_plan(
     local_experts = num_experts // world_size
     if local_experts <= 0:
         raise ValueError("num_experts must be at least world_size")
-    expert_offsets = torch.arange(num_topk, device="cuda", dtype=torch.long) % local_experts
+    expert_offsets = (
+        torch.arange(num_topk, device="cuda", dtype=torch.long) % local_experts
+    )
 
     if route == "cross" and buffer.num_scaleout_ranks > 1:
         dst_scaleout = (buffer.scaleout_rank_idx + 1) % buffer.num_scaleout_ranks
@@ -116,7 +124,9 @@ def make_route_plan(
             1,
         )
 
-    dst_ranks = (rank + torch.arange(num_topk, device="cuda", dtype=torch.long)) % world_size
+    dst_ranks = (
+        rank + torch.arange(num_topk, device="cuda", dtype=torch.long)
+    ) % world_size
     choices = dst_ranks * local_experts + expert_offsets
     unique_dst_ranks = int(torch.unique(dst_ranks).numel())
     return RoutePlan(
@@ -162,6 +172,7 @@ def main() -> None:
     if num_experts % world_size != 0:
         raise ValueError("num_experts must be divisible by world_size")
 
+    transport_kwargs = {} if args.transport == "auto" else {"transport": args.transport}
     buffer = ElasticBuffer(
         dist.group.WORLD,
         num_max_tokens_per_rank=max_tokens,
@@ -172,6 +183,7 @@ def main() -> None:
         allow_hybrid_mode=True,
         allow_multiple_reduction=True,
         num_gpu_timeout_secs=10,
+        **transport_kwargs,
     )
     route_plan = make_route_plan(
         rank=rank,
@@ -182,7 +194,9 @@ def main() -> None:
         num_experts=num_experts,
         route=args.route,
     )
-    weights = torch.ones((args.num_tokens, args.num_topk), device="cuda", dtype=torch.float32)
+    weights = torch.ones(
+        (args.num_tokens, args.num_topk), device="cuda", dtype=torch.float32
+    )
 
     def run_one(iteration: int, cached_handle):
         x = make_input(rank, iteration, args.num_tokens, args.hidden)
@@ -208,7 +222,9 @@ def run_one(iteration: int, cached_handle):
 
         actual_recv_tokens = route_plan.expected_recv_tokens
         if args.sync_actual_count:
-            actual_recv_tokens = int(handle.psum_num_recv_tokens_per_scaleup_rank[-1].item())
+            actual_recv_tokens = int(
+                handle.psum_num_recv_tokens_per_scaleup_rank[-1].item()
+            )
             if actual_recv_tokens != route_plan.expected_recv_tokens:
                 raise AssertionError(
                     f"rank={rank}: got {actual_recv_tokens} received tokens, "
@@ -230,8 +246,12 @@ def run_one(iteration: int, cached_handle):
         torch.cuda.synchronize()
 
         if args.check_correctness:
-            expected = (x.float() * route_plan.expected_combine_factor).to(torch.bfloat16)
-            check_output(rank=rank, route=args.route, combined=combined, expected=expected)
+            expected = (x.float() * route_plan.expected_combine_factor).to(
+                torch.bfloat16
+            )
+            check_output(
+                rank=rank, route=args.route, combined=combined, expected=expected
+            )
 
         return (
             handle,
@@ -259,32 +279,45 @@ def run_one(iteration: int, cached_handle):
     dist.barrier()
     wall_seconds = time.time() - wall_start
 
-    stats = torch.tensor(
-        [
-            sum(dispatch_ms) / len(dispatch_ms),
-            sum(combine_ms) / len(combine_ms),
-            min(dispatch_ms),
-            max(dispatch_ms),
-            min(combine_ms),
-            max(combine_ms),
-            sum(recv_tokens) / len(recv_tokens),
-            wall_seconds,
-        ],
+    samples = (
+        torch.tensor(
+            [dispatch_ms, combine_ms, recv_tokens],
+            device="cuda",
+            dtype=torch.float64,
+        )
+        .transpose(0, 1)
+        .contiguous()
+    )
+    gathered = [torch.empty_like(samples) for _ in range(world_size)]
+    dist.all_gather(gathered, samples)
+
+    max_wall_seconds = torch.tensor(
+        wall_seconds,
         device="cuda",
         dtype=torch.float64,
     )
-    gathered = [torch.empty_like(stats) for _ in range(world_size)]
-    dist.all_gather(gathered, stats)
+    dist.all_reduce(max_wall_seconds, op=dist.ReduceOp.MAX)
 
     if rank == 0:
         table = torch.stack(gathered).cpu()
-        payload_bytes = table[:, 6].mean().item() * args.hidden * 2
-        dispatch_avg_ms = table[:, 0].mean().item()
-        combine_avg_ms = table[:, 1].mean().item()
+        dispatch_samples = table[:, :, 0]
+        combine_samples = table[:, :, 1]
+        e2e_samples = dispatch_samples + combine_samples
+        payload_bytes = table[:, :, 2].mean().item() * args.hidden * 2
+        dispatch_avg_ms = dispatch_samples.mean().item()
+        combine_avg_ms = combine_samples.mean().item()
+        e2e_avg_ms = e2e_samples.mean().item()
+        dispatch_critical_samples = dispatch_samples.max(dim=0).values
+        combine_critical_samples = combine_samples.max(dim=0).values
+        dispatch_critical_ms = dispatch_critical_samples.mean().item()
+        combine_critical_ms = combine_critical_samples.mean().item()
+        e2e_critical_ms = e2e_samples.max(dim=0).values.mean().item()
+        wall_ms_per_iter = max_wall_seconds.item() * 1000 / args.iters
         print(
             "MOONCAKE_ELASTIC_PERF_OK",
             f"world={world_size}",
             f"route={args.route}",
+            f"transport={buffer.transport}",
             f"reuse_handle={int(args.reuse_handle)}",
             f"tokens={args.num_tokens}",
             f"hidden={args.hidden}",
@@ -293,13 +326,23 @@ def run_one(iteration: int, cached_handle):
             f"scaleup={buffer.num_scaleup_ranks}",
             f"dispatch_avg_ms={dispatch_avg_ms:.3f}",
             f"combine_avg_ms={combine_avg_ms:.3f}",
-            f"recv_tokens_avg={table[:, 6].mean().item():.1f}",
+            f"e2e_avg_ms={e2e_avg_ms:.3f}",
+            f"dispatch_critical_ms={dispatch_critical_ms:.3f}",
+            f"combine_critical_ms={combine_critical_ms:.3f}",
+            f"e2e_critical_ms={e2e_critical_ms:.3f}",
+            f"wall_ms_per_iter={wall_ms_per_iter:.3f}",
+            f"recv_tokens_avg={table[:, :, 2].mean().item():.1f}",
             f"effective_payload_MB_per_rank={payload_bytes / 1e6:.1f}",
             f"dispatch_effective_GBps={payload_bytes / dispatch_avg_ms / 1e6:.2f}",
             f"combine_effective_GBps={payload_bytes / combine_avg_ms / 1e6:.2f}",
+            "dispatch_critical_effective_GBps="
+            f"{payload_bytes / dispatch_critical_ms / 1e6:.2f}",
+            "combine_critical_effective_GBps="
+            f"{payload_bytes / combine_critical_ms / 1e6:.2f}",
             flush=True,
         )
 
+    buffer.destroy()
     dist.destroy_process_group()
 
 
diff --git a/mooncake-ep/benchmarks/legacy_buffer_perf.cpp b/mooncake-ep/benchmarks/legacy_buffer_perf.cpp
new file mode 100644
index 0000000000..aa7b5776d3
--- /dev/null
+++ b/mooncake-ep/benchmarks/legacy_buffer_perf.cpp
@@ -0,0 +1,199 @@
+#include <cuda_alike.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include <mooncake_ep_buffer.h>
+#include <pybind11/gil.h>
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+namespace mooncake {
+namespace {
+
+struct LegacyBufferPerfTensors {
+    uint64_t x_ptr = 0;
+    uint64_t topk_idx_ptr = 0;
+    uint64_t topk_weights_ptr = 0;
+    uint64_t active_ranks_ptr = 0;
+    uint64_t expert_x_ptr = 0;
+    uint64_t packed_recv_x_ptr = 0;
+    uint64_t packed_recv_count_ptr = 0;
+    uint64_t packed_recv_src_info_ptr = 0;
+    uint64_t packed_recv_layout_range_ptr = 0;
+    uint64_t combined_x_ptr = 0;
+};
+
+struct LegacyBufferPerfConfig {
+    int num_tokens = 0;
+    int hidden = 0;
+    int num_topk = 0;
+    int num_local_experts = 0;
+    int num_max_dispatch_tokens_per_rank = 0;
+    int num_experts = 0;
+    int timeout_us = -1;
+    int warmups = 20;
+    int iterations = 30;
+    uint64_t compute_stream_ptr = 0;
+};
+
+struct LegacyBufferPerfResult {
+    double average_us = 0.0;
+    double min_us = 0.0;
+    double max_us = 0.0;
+};
+
+void cuda_check(cudaError_t status, const char* operation) {
+    if (status != cudaSuccess) {
+        throw std::runtime_error(std::string(operation) + ": " +
+                                 cudaGetErrorString(status));
+    }
+}
+
+void validate(MooncakeEpBuffer& buffer, const LegacyBufferPerfTensors& tensors,
+              const LegacyBufferPerfConfig& config) {
+    if (config.num_tokens <= 0 || config.hidden <= 0 || config.num_topk <= 0 ||
+        config.num_max_dispatch_tokens_per_rank < config.num_tokens ||
+        config.num_experts <= 0 || config.num_local_experts <= 0 ||
+        config.warmups < 0 || config.iterations <= 1) {
+        throw std::invalid_argument(
+            "invalid legacy EP benchmark configuration");
+    }
+    if (buffer.ibgda_disabled() && !buffer.use_fast_path()) {
+        throw std::runtime_error(
+            "legacy EP benchmark requires the native fast path");
+    }
+    if (!tensors.x_ptr || !tensors.topk_idx_ptr || !tensors.topk_weights_ptr ||
+        !tensors.active_ranks_ptr || !tensors.expert_x_ptr ||
+        !tensors.packed_recv_x_ptr || !tensors.packed_recv_count_ptr ||
+        !tensors.packed_recv_src_info_ptr ||
+        !tensors.packed_recv_layout_range_ptr || !tensors.combined_x_ptr) {
+        throw std::invalid_argument(
+            "legacy EP benchmark received a null tensor pointer");
+    }
+}
+
+LegacyBufferPerfResult run_legacy_buffer_perf(
+    MooncakeEpBuffer& buffer, const LegacyBufferPerfTensors& tensors,
+    const LegacyBufferPerfConfig& config) {
+    validate(buffer, tensors, config);
+
+    const int num_local_experts = config.num_local_experts;
+    const auto compute_stream =
+        reinterpret_cast<cudaStream_t>(config.compute_stream_ptr);
+    const size_t recv_count_bytes =
+        static_cast<size_t>(num_local_experts) * sizeof(int);
+
+    auto run_once = [&] {
+        cuda_check(cudaMemsetAsync(
+                       reinterpret_cast<void*>(tensors.packed_recv_count_ptr),
+                       0, recv_count_bytes, compute_stream),
+                   "cudaMemsetAsync(packed_recv_count)");
+        buffer.dispatch(
+            tensors.x_ptr, tensors.topk_idx_ptr, tensors.active_ranks_ptr,
+            config.num_tokens, config.hidden, config.num_topk,
+            config.num_max_dispatch_tokens_per_rank, config.num_experts,
+            config.timeout_us, false, tensors.packed_recv_x_ptr, 0,
+            tensors.packed_recv_count_ptr, tensors.packed_recv_src_info_ptr,
+            tensors.packed_recv_layout_range_ptr, false, false,
+            config.compute_stream_ptr);
+        buffer.combine(
+            tensors.expert_x_ptr, tensors.topk_idx_ptr,
+            tensors.topk_weights_ptr, tensors.packed_recv_src_info_ptr,
+            tensors.packed_recv_layout_range_ptr, tensors.active_ranks_ptr,
+            num_local_experts, config.num_tokens, config.hidden,
+            config.num_topk, config.num_max_dispatch_tokens_per_rank,
+            config.num_experts, config.timeout_us, false,
+            tensors.combined_x_ptr, false, false, config.compute_stream_ptr);
+    };
+
+    for (int i = 0; i < config.warmups; ++i) run_once();
+    cuda_check(cudaStreamSynchronize(compute_stream),
+               "cudaStreamSynchronize(warmup)");
+
+    std::vector<cudaEvent_t> starts(config.iterations);
+    std::vector<cudaEvent_t> ends(config.iterations);
+    for (int i = 0; i < config.iterations; ++i) {
+        cuda_check(cudaEventCreate(&starts[i]), "cudaEventCreate(start)");
+        cuda_check(cudaEventCreate(&ends[i]), "cudaEventCreate(end)");
+        cuda_check(cudaEventRecord(starts[i], compute_stream),
+                   "cudaEventRecord(start)");
+        run_once();
+        cuda_check(cudaEventRecord(ends[i], compute_stream),
+                   "cudaEventRecord(end)");
+    }
+    cuda_check(cudaEventSynchronize(ends.back()), "cudaEventSynchronize(end)");
+
+    std::vector<float> timings_us;
+    timings_us.reserve(config.iterations - 1);
+    for (int i = 1; i < config.iterations; ++i) {
+        float elapsed_ms = 0.0f;
+        cuda_check(cudaEventElapsedTime(&elapsed_ms, starts[i], ends[i]),
+                   "cudaEventElapsedTime");
+        timings_us.push_back(elapsed_ms * 1000.0f);
+    }
+    for (auto event : starts) cudaEventDestroy(event);
+    for (auto event : ends) cudaEventDestroy(event);
+
+    double total_us = 0.0;
+    for (float value : timings_us) total_us += value;
+    const auto [min_it, max_it] =
+        std::minmax_element(timings_us.begin(), timings_us.end());
+    return {total_us / timings_us.size(), *min_it, *max_it};
+}
+
+}  // namespace
+
+void bind_legacy_buffer_perf(py::module_& module) {
+    py::class_<LegacyBufferPerfTensors>(module, "_LegacyBufferPerfTensors")
+        .def(py::init<>())
+        .def_readwrite("x_ptr", &LegacyBufferPerfTensors::x_ptr)
+        .def_readwrite("topk_idx_ptr", &LegacyBufferPerfTensors::topk_idx_ptr)
+        .def_readwrite("topk_weights_ptr",
+                       &LegacyBufferPerfTensors::topk_weights_ptr)
+        .def_readwrite("active_ranks_ptr",
+                       &LegacyBufferPerfTensors::active_ranks_ptr)
+        .def_readwrite("expert_x_ptr", &LegacyBufferPerfTensors::expert_x_ptr)
+        .def_readwrite("packed_recv_x_ptr",
+                       &LegacyBufferPerfTensors::packed_recv_x_ptr)
+        .def_readwrite("packed_recv_count_ptr",
+                       &LegacyBufferPerfTensors::packed_recv_count_ptr)
+        .def_readwrite("packed_recv_src_info_ptr",
+                       &LegacyBufferPerfTensors::packed_recv_src_info_ptr)
+        .def_readwrite("packed_recv_layout_range_ptr",
+                       &LegacyBufferPerfTensors::packed_recv_layout_range_ptr)
+        .def_readwrite("combined_x_ptr",
+                       &LegacyBufferPerfTensors::combined_x_ptr);
+
+    py::class_<LegacyBufferPerfConfig>(module, "_LegacyBufferPerfConfig")
+        .def(py::init<>())
+        .def_readwrite("num_tokens", &LegacyBufferPerfConfig::num_tokens)
+        .def_readwrite("hidden", &LegacyBufferPerfConfig::hidden)
+        .def_readwrite("num_topk", &LegacyBufferPerfConfig::num_topk)
+        .def_readwrite("num_local_experts",
+                       &LegacyBufferPerfConfig::num_local_experts)
+        .def_readwrite(
+            "num_max_dispatch_tokens_per_rank",
+            &LegacyBufferPerfConfig::num_max_dispatch_tokens_per_rank)
+        .def_readwrite("num_experts", &LegacyBufferPerfConfig::num_experts)
+        .def_readwrite("timeout_us", &LegacyBufferPerfConfig::timeout_us)
+        .def_readwrite("warmups", &LegacyBufferPerfConfig::warmups)
+        .def_readwrite("iterations", &LegacyBufferPerfConfig::iterations)
+        .def_readwrite("compute_stream_ptr",
+                       &LegacyBufferPerfConfig::compute_stream_ptr);
+
+    py::class_<LegacyBufferPerfResult>(module, "_LegacyBufferPerfResult")
+        .def_readonly("average_us", &LegacyBufferPerfResult::average_us)
+        .def_readonly("min_us", &LegacyBufferPerfResult::min_us)
+        .def_readonly("max_us", &LegacyBufferPerfResult::max_us);
+
+    module.def("_benchmark_legacy_buffer", &run_legacy_buffer_perf,
+               py::arg("buffer"), py::arg("tensors"), py::arg("config"),
+               py::call_guard<py::gil_scoped_release>());
+}
+
+}  // namespace mooncake
diff --git a/mooncake-ep/benchmarks/legacy_buffer_perf.py b/mooncake-ep/benchmarks/legacy_buffer_perf.py
new file mode 100644
index 0000000000..3a8aac09e4
--- /dev/null
+++ b/mooncake-ep/benchmarks/legacy_buffer_perf.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Native-core legacy EP benchmark with Python distributed bootstrap.
+
+Launch with torchrun. Python initializes the Mooncake process group and owns
+the fixed tensor storage; the timed dispatch/combine loop executes entirely in
+the torch-free C++ EP module.
+"""
+
+import argparse
+import os
+
+import torch
+import torch.distributed as dist
+
+import mooncake._ep as native_ep
+import mooncake.pg  # Registers the Mooncake process-group backend for bootstrap.
+from mooncake.mooncake_ep_buffer import Buffer
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tokens", type=int, default=128)
+    parser.add_argument("--hidden", type=int, default=7168)
+    parser.add_argument("--experts", type=int, default=288)
+    parser.add_argument("--topk", type=int, default=8)
+    parser.add_argument("--warmups", type=int, default=20)
+    parser.add_argument("--iterations", type=int, default=30)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    local_rank = int(os.environ["LOCAL_RANK"])
+    torch.cuda.set_device(local_rank)
+    dist.init_process_group("mooncake")
+    world_size = dist.get_world_size()
+    rank = dist.get_rank()
+    group = dist.new_group(list(range(world_size)))
+
+    if args.experts % world_size:
+        raise ValueError("--experts must be divisible by world size")
+    if args.hidden % 128:
+        raise ValueError("--hidden must be divisible by 128")
+
+    torch.manual_seed(rank)
+    num_local_experts = args.experts // world_size
+    buffer_bytes = Buffer.get_ep_buffer_size_hint(
+        args.tokens, args.hidden, world_size, args.experts
+    )
+    buffer = Buffer(group, num_ep_buffer_bytes=buffer_bytes)
+    if buffer._use_fallback:
+        raise RuntimeError("native-core benchmark requires the EP fast path")
+
+    x = torch.randn(
+        (args.tokens, args.hidden), dtype=torch.bfloat16, device="cuda"
+    )
+    scores = torch.randn(
+        (args.tokens, args.experts), dtype=torch.float32, device="cuda"
+    )
+    topk_idx = torch.topk(scores, args.topk, dim=-1).indices.contiguous()
+    topk_weights = torch.rand(
+        (args.tokens, args.topk), dtype=torch.float32, device="cuda"
+    )
+    active_ranks = torch.ones(world_size, dtype=torch.int32, device="cuda")
+    recv_tokens = world_size * args.tokens
+    expert_x = torch.randn(
+        (num_local_experts, recv_tokens, args.hidden),
+        dtype=torch.bfloat16,
+        device="cuda",
+    )
+    packed_recv_x = torch.empty_like(expert_x)
+    packed_recv_count = torch.empty(
+        num_local_experts, dtype=torch.int32, device="cuda"
+    )
+    packed_recv_src_info = torch.empty(
+        (num_local_experts, recv_tokens), dtype=torch.int32, device="cuda"
+    )
+    packed_recv_layout_range = torch.empty(
+        (num_local_experts, world_size), dtype=torch.int64, device="cuda"
+    )
+    combined_x = torch.empty_like(x)
+    cache_flush = torch.empty(int(256e6 // 4), dtype=torch.int32, device="cuda")
+
+    tensors = native_ep._LegacyBufferPerfTensors()
+    tensors.x_ptr = x.data_ptr()
+    tensors.topk_idx_ptr = topk_idx.data_ptr()
+    tensors.topk_weights_ptr = topk_weights.data_ptr()
+    tensors.active_ranks_ptr = active_ranks.data_ptr()
+    tensors.expert_x_ptr = expert_x.data_ptr()
+    tensors.packed_recv_x_ptr = packed_recv_x.data_ptr()
+    tensors.packed_recv_count_ptr = packed_recv_count.data_ptr()
+    tensors.packed_recv_src_info_ptr = packed_recv_src_info.data_ptr()
+    tensors.packed_recv_layout_range_ptr = packed_recv_layout_range.data_ptr()
+    tensors.combined_x_ptr = combined_x.data_ptr()
+
+    config = native_ep._LegacyBufferPerfConfig()
+    config.num_tokens = args.tokens
+    config.hidden = args.hidden
+    config.num_topk = args.topk
+    config.num_local_experts = num_local_experts
+    config.num_max_dispatch_tokens_per_rank = args.tokens
+    config.num_experts = args.experts
+    config.warmups = args.warmups
+    config.iterations = args.iterations
+    config.compute_stream_ptr = torch.cuda.current_stream().cuda_stream
+
+    dist.barrier(group=group)
+    cache_flush.zero_()
+    result = native_ep._benchmark_legacy_buffer(buffer.runtime, tensors, config)
+    selections = topk_idx.numel()
+    payload_bytes = selections * (args.hidden * 4)
+    bandwidth = payload_bytes / result.average_us / 1e3
+    print(
+        f"[rank {rank}] Native dispatch + combine: {bandwidth:.2f} GB/s, "
+        f"avg_t={result.average_us:.2f} us, min_t={result.min_us:.2f} us, "
+        f"max_t={result.max_us:.2f} us",
+        flush=True,
+    )
+    dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_buffer.h b/mooncake-ep/include/elastic/mooncake_ep_elastic_buffer.h
index 6b5dacdd07..ea3781e9d4 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_buffer.h
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_buffer.h
@@ -5,6 +5,7 @@
 #include <cstdint>
 #include <memory>
 #include <optional>
+#include <string>
 #include <tuple>
 #include <vector>
 
@@ -13,6 +14,9 @@
 namespace mooncake {
 
 struct ElasticLaunchContext;
+struct NcclElasticState;
+
+std::vector<int32_t> create_elastic_nccl_unique_id();
 
 struct ElasticTopology {
     int rank_idx = 0;
@@ -24,6 +28,7 @@ struct ElasticTopology {
     int scaleout_rank_idx = 0;
     int scaleup_rank_idx = 0;
     bool hybrid_enabled = false;
+    bool scaleup_lsa = false;
 };
 
 struct ElasticConfig {
@@ -41,38 +46,6 @@ struct ElasticConfig {
     int num_gpu_timeout_secs = 100;
 };
 
-struct ElasticNativeHandle {
-    bool do_expand = false;
-    int num_experts = 0;
-    int expert_alignment = 1;
-    int num_max_tokens_per_rank = 0;
-    int num_sms = 0;
-    torch::Tensor topk_idx;
-    torch::Tensor psum_num_recv_tokens_per_scaleup_rank;
-    torch::Tensor psum_num_recv_tokens_per_expert;
-    torch::Tensor recv_src_metadata;
-    torch::Tensor recv_layout_range;
-    torch::Tensor dst_buffer_slot_idx;
-    std::optional<torch::Tensor> token_metadata_at_forward;
-    std::optional<torch::Tensor> channel_linked_list;
-    std::vector<int> num_recv_tokens_per_expert_list;
-};
-
-struct ElasticDispatchOutput {
-    torch::Tensor recv_x;
-    std::optional<torch::Tensor> recv_x_scales;
-    std::optional<torch::Tensor> recv_topk_idx;
-    std::optional<torch::Tensor> recv_topk_weights;
-    ElasticNativeHandle handle;
-    std::optional<EventHandle> event;
-};
-
-struct ElasticCombineOutput {
-    torch::Tensor combined_x;
-    std::optional<torch::Tensor> combined_topk_weights;
-    std::optional<EventHandle> event;
-};
-
 class MooncakeElasticBuffer {
    public:
     MooncakeElasticBuffer(int rank, int num_ranks, int64_t num_buffer_bytes,
@@ -84,8 +57,30 @@ class MooncakeElasticBuffer {
                           int num_allocated_qps, int num_cpu_timeout_secs,
                           int num_gpu_timeout_secs);
 
+    MooncakeElasticBuffer(int rank, int num_ranks, int64_t num_buffer_bytes,
+                          int64_t num_max_tokens_per_rank, int64_t hidden,
+                          int64_t num_topk, bool use_fp8_dispatch,
+                          bool deterministic, bool allow_hybrid_mode,
+                          bool allow_multiple_reduction,
+                          bool prefer_overlap_with_compute, int sl_idx,
+                          int num_allocated_qps, int num_cpu_timeout_secs,
+                          int num_gpu_timeout_secs,
+                          const std::string& transport,
+                          const std::vector<int32_t>& nccl_unique_id);
+
     ~MooncakeElasticBuffer();
 
+    // For NCCL, the caller must first quiesce CUDA work and coordinate every
+    // communicator rank. The Python wrapper provides that collective protocol.
+    void destroy();
+    bool using_nccl() const { return nccl_state_ != nullptr; }
+
+    // Replace the NCCL communicator-owned resources while preserving this
+    // buffer's fixed logical rank and configuration. Every rank must join the
+    // matching NCCL setup sequence at a quiescent EP boundary with the same
+    // fresh unique ID; replacement ranks enter it through construction.
+    void reconfigure_nccl(const std::vector<int32_t>& nccl_unique_id);
+
     static int64_t calculate_buffer_size(int num_ranks,
                                          int64_t num_max_tokens_per_rank,
                                          int64_t hidden, int64_t num_topk,
@@ -97,72 +92,76 @@ class MooncakeElasticBuffer {
     std::tuple<int, int> get_logical_domain_size() const;
     int get_theoretical_num_sms(int num_experts, int num_topk) const;
 
-    ElasticDispatchOutput dispatch(
-        const torch::Tensor& x, const std::optional<torch::Tensor>& sf,
-        const torch::Tensor& topk_idx,
-        const std::optional<torch::Tensor>& topk_weights,
-        torch::Tensor& active_ranks, int num_experts,
-        int num_max_tokens_per_rank, int expert_alignment, int num_sms,
-        bool do_expand, bool do_cpu_sync, bool async_with_compute_stream,
-        const std::optional<ElasticNativeHandle>& cached_handle = std::nullopt);
-
-    ElasticCombineOutput combine(
-        const torch::Tensor& x, const ElasticNativeHandle& handle,
-        const std::optional<torch::Tensor>& topk_weights,
-        torch::Tensor& active_ranks, int num_sms,
-        bool async_with_compute_stream,
-        const std::optional<torch::Tensor>& out);
-
-    MooncakeEpBuffer& native_buffer() { return *native_buffer_; }
-
-    bool ibgda_disabled() const { return native_buffer_->ibgda_disabled(); }
-    bool use_fast_path() { return native_buffer_->use_fast_path(); }
-    void update_local_qpns() { native_buffer_->update_local_qpns(); }
-    bool is_roce() const { return native_buffer_->is_roce(); }
+    std::optional<EventHandle> dispatch(
+        uint64_t x_ptr, int x_element_size, uint64_t sf_ptr, int num_tokens,
+        int hidden, int num_sf_packs, int sf_token_stride, int sf_hidden_stride,
+        uint64_t topk_idx_ptr, int num_topk, uint64_t topk_weights_ptr,
+        uint64_t active_ranks_ptr, int num_experts, int num_max_tokens_per_rank,
+        int expert_alignment, int num_sms, bool do_expand,
+        bool async_with_compute_stream, uint64_t compute_stream_ptr,
+        bool cached_mode, int num_recv_tokens,
+        uint64_t psum_num_recv_tokens_per_scaleup_rank_ptr,
+        uint64_t psum_num_recv_tokens_per_expert_ptr,
+        uint64_t dst_buffer_slot_idx_ptr,
+        uint64_t token_metadata_at_forward_ptr,
+        uint64_t channel_linked_list_ptr, uint64_t recv_x_ptr,
+        uint64_t recv_x_scales_ptr, uint64_t recv_topk_idx_ptr,
+        uint64_t recv_topk_weights_ptr, uint64_t recv_src_metadata_ptr);
+
+    std::optional<EventHandle> combine(
+        uint64_t x_ptr, int num_input_tokens, int hidden, uint64_t topk_idx_ptr,
+        int num_combined_tokens, int num_topk, uint64_t topk_weights_ptr,
+        uint64_t psum_num_recv_tokens_per_scaleup_rank_ptr,
+        uint64_t recv_src_metadata_ptr, uint64_t token_metadata_at_forward_ptr,
+        uint64_t channel_linked_list_ptr, uint64_t active_ranks_ptr,
+        int num_experts, int num_max_tokens_per_rank, bool do_expand,
+        int num_sms, bool async_with_compute_stream,
+        uint64_t compute_stream_ptr, uint64_t combined_x_ptr);
+
+    MooncakeEpBuffer& native_buffer();
+
+    bool ibgda_disabled() const;
+    bool use_fast_path();
+    void update_local_qpns();
+    bool is_roce() const;
     void sync_ibgda_peers(const std::vector<int64_t>& remote_addrs,
                           const std::vector<int32_t>& remote_keys,
                           const std::vector<std::vector<int32_t>>& peer_qpns,
                           const std::vector<std::vector<int32_t>>& peer_lids,
                           const std::vector<int64_t>& subnet_prefixes,
                           const std::vector<int64_t>& interface_ids,
-                          const std::vector<int>& active_ranks_mask) {
-        native_buffer_->sync_ibgda_peers(remote_addrs, remote_keys, peer_qpns,
-                                         peer_lids, subnet_prefixes,
-                                         interface_ids, active_ranks_mask);
-    }
-    std::tuple<int64_t, int32_t> get_mr_info() {
-        return native_buffer_->get_mr_info();
-    }
-    std::tuple<int64_t, int64_t> get_gid() { return native_buffer_->get_gid(); }
-    std::vector<int32_t> get_local_qpns() {
-        return native_buffer_->get_local_qpns();
-    }
-    std::vector<int32_t> get_local_lids() {
-        return native_buffer_->get_local_lids();
-    }
-    std::vector<int32_t> get_ipc_handle() {
-        return native_buffer_->get_ipc_handle();
-    }
+                          const std::vector<int>& active_ranks_mask);
+    std::tuple<int64_t, int32_t> get_mr_info();
+    std::tuple<int64_t, int64_t> get_gid();
+    std::vector<int32_t> get_local_qpns();
+    std::vector<int32_t> get_local_lids();
+    std::vector<int32_t> get_ipc_handle();
     void sync_nvlink_ipc_handles(
         const std::vector<std::vector<int32_t>>& remote_handles,
-        const std::vector<int>& active_ranks_mask) {
-        native_buffer_->sync_nvlink_ipc_handles(remote_handles,
-                                                active_ranks_mask);
-    }
+        const std::vector<int>& active_ranks_mask);
 
    private:
     ElasticConfig config_;
     ElasticTopology topology_;
+    std::string transport_;
     std::unique_ptr<MooncakeEpBuffer> native_buffer_;
+    std::unique_ptr<NcclElasticState> nccl_state_;
     int64_t host_workspace_bytes_ = 0;
     void* host_workspace_ = nullptr;
     void* mapped_host_workspace_ = nullptr;
-
-    static ElasticLaunchContext make_launch_context(
-        MooncakeEpBuffer& buffer, const ElasticTopology& topology,
-        void* mapped_host_workspace, int64_t timeout_cycles);
+    std::shared_ptr<void> deterministic_rank_count_buffer_;
+    int64_t deterministic_rank_count_buffer_bytes_ = 0;
+    int device_id_ = -1;
+    int physical_num_sms_ = 0;
+    int device_smem_bytes_ = 0;
+    bool destroyed_ = false;
+
+    ElasticLaunchContext make_launch_context(int64_t timeout_cycles) const;
+    cudaStream_t communication_stream() const;
+    int clock_rate_khz() const;
     static ElasticTopology discover_topology(int rank, int num_ranks,
                                              bool allow_hybrid_mode);
+    std::shared_ptr<void> ensure_deterministic_rank_count_buffer(int num_sms);
 };
 
 }  // namespace mooncake
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_official.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_official.cuh
index 9e36b344f7..44c605fd59 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_official.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_official.cuh
@@ -14,7 +14,7 @@
 
 namespace mooncake::elastic {
 
-template <bool kIsScaleupNVLink, bool kUseExpandedLayout,
+template <typename Ops, bool kIsScaleupNVLink, bool kUseExpandedLayout,
           bool kAllowMultipleReduction, int kNumSMs, int kNumWarps,
           int kNumRanks, int kHidden, int kNumMaxTokensPerRank, int kNumExperts,
           int kNumTopk, int kNumQPs, int64_t kNumTimeoutCycles,
@@ -29,8 +29,8 @@ template <bool kIsScaleupNVLink, bool kUseExpandedLayout,
 __global__ void __launch_bounds__(kNumThreads, 1)
     combine_impl(nv_bfloat16* x, float* topk_weights, int* src_metadata,
                  int* psum_num_recv_tokens_per_scaleup_rank,
-                 const device::CommCtx comm_ctx, void* buffer, void* workspace,
-                 const int rank_idx, int num_reduced_tokens) {
+                 const typename Ops::Context comm_ctx, void* buffer,
+                 void* workspace, const int rank_idx, int num_reduced_tokens) {
     // Utils
     const auto sm_idx = static_cast<int>(blockIdx.x);
     const auto thread_idx = static_cast<int>(threadIdx.x);
@@ -73,13 +73,13 @@ __global__ void __launch_bounds__(kNumThreads, 1)
     // We treat each warp as a "channel"
     const auto [qp_idx, sharing_mode] =
         comm::get_qp_mode<kNumSMs, kNumQPs, kNumWarps>(sm_idx, warp_idx);
-    const auto gin = transport::MooncakeGin(comm_ctx, qp_idx, sharing_mode,
-                                            kNumQPs, 0, 0, 0, kNumRanks);
+    const auto gin =
+        Ops(comm_ctx, qp_idx, sharing_mode, kNumQPs, 0, 0, 0, kNumRanks);
 
     // Full barrier to ensure the remote buffer is available
     const auto workspace_layout =
         layout::WorkspaceLayout(workspace, 1, kNumRanks, kNumExperts);
-    comm::gpu_barrier<kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
+    comm::gpu_barrier<Ops, kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
                       kNumQPs, kNumTimeoutCycles, comm::kCombineTag0, false,
                       false, true>(gin, workspace_layout, 0, rank_idx, sm_idx,
                                    thread_idx);
@@ -102,7 +102,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
         // Directly to the remote or via RDMA
         const bool nvlink_bypass =
-            gin.is_nvlink_accessible<team_t>(src_rank_idx);
+            gin.template is_nvlink_accessible<team_t>(src_rank_idx);
         layout::TokenLayout master_token_buffer = [=]() {
             // NVLink bypass
             if (nvlink_bypass) {
@@ -111,7 +111,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         .get_rank_buffer(kUseRankLayout ? rank_idx
                                                         : src_topk_idx)
                         .get_token_buffer(src_token_idx);
-                token_buffer.set_base_ptr(gin.get_sym_ptr<team_t>(
+                token_buffer.set_base_ptr(gin.template get_sym_ptr<team_t>(
                     token_buffer.get_base_ptr(), src_rank_idx));
                 return token_buffer;
             }
@@ -251,8 +251,8 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                             src_token_idx);
 #ifdef MOONCAKE_EP_USE_MUSA
                     if (nvlink_bypass) {
-                        auto* dst_ptr =
-                            static_cast<combine_vec_t*>(gin.get_sym_ptr<team_t>(
+                        auto* dst_ptr = static_cast<combine_vec_t*>(
+                            gin.template get_sym_ptr<team_t>(
                                 token_buffer.get_base_ptr(), src_rank_idx));
 #pragma unroll 1
                         for (int vec_idx = lane_idx; vec_idx < kHiddenVec;
@@ -274,9 +274,10 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         }
                         __syncwarp();
                         if (ptx::elect_one_sync()) {
-                            gin.put<team_t>(token_buffer.get_base_ptr(),
-                                            send_token_buffer.get_base_ptr(),
-                                            kNumHiddenBytes, src_rank_idx);
+                            gin.template put<team_t>(
+                                token_buffer.get_base_ptr(),
+                                send_token_buffer.get_base_ptr(),
+                                kNumHiddenBytes, src_rank_idx);
                         }
                     }
                     __syncwarp();
@@ -295,7 +296,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         if (nvlink_bypass) {
                             // Write into the same position
                             ptx::tma_store_1d(
-                                gin.get_sym_ptr<team_t>(
+                                gin.template get_sym_ptr<team_t>(
                                     token_buffer.get_base_ptr(), src_rank_idx),
                                 tma_buffer.get_base_ptr(), kNumHiddenBytes);
                             ptx::tma_store_commit();
@@ -312,9 +313,10 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                             ptx::tma_store_wait();
 
                             // Issue RDMA
-                            gin.put<team_t>(token_buffer.get_base_ptr(),
-                                            send_token_buffer.get_base_ptr(),
-                                            kNumHiddenBytes, src_rank_idx);
+                            gin.template put<team_t>(
+                                token_buffer.get_base_ptr(),
+                                send_token_buffer.get_base_ptr(),
+                                kNumHiddenBytes, src_rank_idx);
                         }
                     }
                     __syncwarp();
@@ -349,14 +351,14 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                     .get_rank_buffer(kUseRankLayout ? rank_idx : src_topk_idx)
                     .get_token_buffer(src_token_idx)
                     .get_base_ptr();
-            gin.put<team_t>(dst_ptr, master_token_buffer.get_base_ptr(),
-                            master_token_buffer.get_num_bytes<false>(),
-                            src_rank_idx);
+            gin.template put<team_t>(
+                dst_ptr, master_token_buffer.get_base_ptr(),
+                master_token_buffer.get_num_bytes<false>(), src_rank_idx);
         }
     }
 
     // Final barrier to ensure data arrival
-    comm::gpu_barrier<kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
+    comm::gpu_barrier<Ops, kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
                       kNumQPs, kNumTimeoutCycles, comm::kCombineTag1, true,
                       true, false>(gin, workspace_layout, 0, rank_idx, sm_idx,
                                    thread_idx);
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_reduce_epilogue.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_reduce_epilogue.cuh
index 6e41aebab8..7829e7ecfc 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_reduce_epilogue.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_reduce_epilogue.cuh
@@ -42,8 +42,9 @@ __global__ void __launch_bounds__(kNumThreads, 1)
     // Utils
     const auto sm_idx = static_cast<int>(blockIdx.x);
     const auto warp_idx = ptx::get_warp_idx(), lane_idx = ptx::get_lane_idx();
+    const auto num_sms = kNumSMs == 0 ? static_cast<int>(gridDim.x) : kNumSMs;
     const auto global_warp_idx =
-        warp_idx * kNumSMs +
+        warp_idx * num_sms +
         sm_idx;  // NOTES: Here we prioritize distributing tasks to different
                  // SMs to ensure that the last wave is evenly concentrated on
                  // each SM.
@@ -81,7 +82,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
     // Read from buffers and do reduction
     for (int token_idx = global_warp_idx; token_idx < num_combined_tokens;
-         token_idx += kNumWarps * kNumSMs) {
+         token_idx += kNumWarps * num_sms) {
         // Preprocess all indices
         int stored_dst_rank_idx = -1, stored_dst_expert_idx = -1;
         EP_STATIC_ASSERT(kNumTopk <= 32, "Too many top-k selections");
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_utils.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_utils.cuh
index b2e3623f2a..2201050ce3 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_utils.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_combine_utils.cuh
@@ -37,11 +37,10 @@ template <int kHiddenBytes>
 struct CombineVecTraits {
 #if !defined(MOONCAKE_EP_USE_MUSA) && defined(__CUDA_ARCH__) && \
     (__CUDA_ARCH__ >= 1000)
-    // On SM100+, use longlong4_t (32 bytes) if hidden is aligned, otherwise
-    // fall back to int4 (16 bytes)
-    static constexpr bool kUseLonglong4 =
-        (kHiddenBytes % sizeof(longlong4_t) == 0) and
-        ((kHiddenBytes / sizeof(longlong4_t)) % 32 == 0);
+    // 256-bit longlong4_t accesses regress this reduction on the validated
+    // SM100+ kernel shapes. Keep the faster 128-bit int4 path until a workload
+    // demonstrates that the wider vector is beneficial.
+    static constexpr bool kUseLonglong4 = false;
     using vec_t = std::conditional_t<kUseLonglong4, longlong4_t, int4>;
 #else
     using vec_t = int4;
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_comm.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_comm.cuh
index 886c2f12d8..63872c3d3d 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_comm.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_comm.cuh
@@ -98,10 +98,11 @@ __device__ __forceinline__ std::pair<int, int> get_qp_mode(
     }
 }
 
-template <typename team_t, int kNumRanks, int kNumSMs, int kNumThreads,
-          int64_t kNumTimeoutCycles, int kTag = kDeviceBarrierTag>
+template <typename Ops, typename team_t, int kNumRanks, int kNumSMs,
+          int kNumThreads, int64_t kNumTimeoutCycles,
+          int kTag = kDeviceBarrierTag>
 __forceinline__ __device__ void mooncake_barrier_wo_local_sync(
-    const transport::MooncakeGin& gin, const layout::WorkspaceLayout& workspace,
+    const Ops& gin, const layout::WorkspaceLayout& workspace,
     const int& rank_idx, const int& sm_idx, const int& thread_idx) {
     if (kNumSMs > 1 && sm_idx > 0) return;
 
@@ -111,9 +112,16 @@ __forceinline__ __device__ void mooncake_barrier_wo_local_sync(
     const int sign = status >> 1;
     const int* base_signal = workspace.get_nvl_barrier_signal_ptr(kTag, phase);
 
+    // NCCL LSA atomics can safely converge on one symmetric counter, letting
+    // the waiter issue one acquire load. IBGDA retains one slot per source rank
+    // because its portable remote-atomic protocol must not rely on a shared
+    // remote word.
+    constexpr bool kUseAggregateSignal =
+        Ops::kIsNccl && std::is_same_v<team_t, transport::ScaleupTeam>;
     if (thread_idx < kNumRanks) {
-        auto* dst_ptr = const_cast<int*>(base_signal) + rank_idx;
-        gin.red_add_rel<team_t>(dst_ptr, sign ? -1 : 1, thread_idx);
+        auto* dst_ptr = const_cast<int*>(base_signal) +
+                        (kUseAggregateSignal ? 0 : rank_idx);
+        gin.template red_add_rel<team_t>(dst_ptr, sign ? -1 : 1, thread_idx);
     }
     __syncthreads();
 
@@ -122,63 +130,181 @@ __forceinline__ __device__ void mooncake_barrier_wo_local_sync(
 
     timeout_while<kNumTimeoutCycles>(
         thread_idx == 0, [=](const bool& is_last_check) {
-            int sum = 0;
+            int observed = 0;
+            if constexpr (kUseAggregateSignal) {
+                observed =
+                    ptx::ld_acquire_sys<int>(const_cast<int*>(base_signal));
+            } else {
 #pragma unroll
-            for (int i = 0; i < kNumRanks; ++i) {
-                sum +=
-                    ptx::ld_acquire_sys<int>(const_cast<int*>(base_signal) + i);
+                for (int i = 0; i < kNumRanks; ++i) {
+                    observed += ptx::ld_acquire_sys<int>(
+                        const_cast<int*>(base_signal) + i);
+                }
             }
-            // Mooncake's portable barrier uses one additive slot per source
-            // rank. Each positive phase adds +1 into a zeroed phase slot; the
-            // matching negative phase later adds -1 into the same phase slot.
-            // This matches RDMA atomic-add semantics and avoids relying on a
-            // remote store primitive for non-P2P peers.
             const auto target = sign ? 0 : kNumRanks;
-            if (sum == target) return true;
+            if (observed == target) return true;
             if (is_last_check) {
                 printf(
                     "Mooncake elastic barrier timeout, tag: %d, rank: %d, "
-                    "signal-sum: %d, target: %d\n",
-                    kTag, rank_idx, sum, target);
+                    "signal: %d, target: %d\n",
+                    kTag, rank_idx, observed, target);
             }
             return false;
         });
 }
 
-template <bool kIsScaleupNVLink, int kNumScaleoutRanks, int kNumScaleupRanks,
-          int kNumSMs, int kNumThreads, int kNumQPs, int64_t kNumTimeoutCycles,
-          int kTag = kDeviceBarrierTag, bool kFlushStores = true,
-          bool kSyncAtStart = true, bool kSyncAtEnd = true>
+#ifdef USE_NCCL_DEVICE
+
+// Use one communicator-owned signal per source rank on GIN context 0. Payload
+// contexts are flushed before this function; a single control context is enough
+// to publish barrier arrival and avoids O(team_size * context_count) signals.
+template <typename team_t, int kNumTeamRanks, int kNumThreads,
+          int64_t kNumTimeoutCycles, int kTag = kDeviceBarrierTag>
+__forceinline__ __device__ void nccl_gin_barrier_wo_local_sync(
+    const transport::NcclOps& gin, const layout::WorkspaceLayout& workspace,
+    const int& team_rank_idx, const int& barrier_sm_idx,
+    const int& thread_idx) {
+    if (barrier_sm_idx != 0) return;
+    (void)workspace;
+
+    for (int dst_team_rank = thread_idx; dst_team_rank < kNumTeamRanks;
+         dst_team_rank += kNumThreads) {
+        gin.gin_barrier_signal_inc<team_t>(dst_team_rank, team_rank_idx);
+    }
+
+    for (int src_team_rank = thread_idx; src_team_rank < kNumTeamRanks;
+         src_team_rank += kNumThreads) {
+        const uint64_t target = gin.gin_barrier_advance_shadow(src_team_rank);
+        timeout_while<kNumTimeoutCycles>([=](const bool& is_last_check) {
+            const uint64_t observed =
+                gin.gin_barrier_read_signal(src_team_rank);
+            if (observed >= target) return true;
+            if (is_last_check) {
+                printf(
+                    "Mooncake NCCL GIN barrier timeout, tag: %d, rank: %d, "
+                    "source: %d, signal: %llu, target: %llu\n",
+                    kTag, team_rank_idx, src_team_rank,
+                    static_cast<unsigned long long>(observed),
+                    static_cast<unsigned long long>(target));
+            }
+            return false;
+        });
+    }
+}
+
+#endif  // USE_NCCL_DEVICE
+
+template <typename Ops, bool kIsScaleupNVLink, int kNumScaleoutRanks,
+          int kNumScaleupRanks, int kNumSMs, int kNumThreads, int kNumQPs,
+          int64_t kNumTimeoutCycles, int kTag = kDeviceBarrierTag,
+          bool kFlushStores = true, bool kSyncAtStart = true,
+          bool kSyncAtEnd = true>
 __forceinline__ __device__ void gpu_barrier(
-    const transport::MooncakeGin& gin, const layout::WorkspaceLayout& workspace,
+    const Ops& gin, const layout::WorkspaceLayout& workspace,
     const int& scaleout_rank_idx, const int& scaleup_rank_idx,
     const int& sm_idx, const int& thread_idx, bool do_scaleout = true,
     bool do_scaleup = true) {
-    if constexpr (kFlushStores) gin.flush();
-    if constexpr (kSyncAtStart) {
-        local_grid_sync<kNumSMs, kNumThreads, kNumTimeoutCycles>(workspace,
-                                                                 thread_idx);
+    // Complete TMA stores before publishing any remote arrival. This is also
+    // required for LSA writes because TMA uses a separate async proxy.
+    if constexpr (Ops::kIsNccl && kFlushStores) {
+        ptx::tma_store_commit();
+        ptx::tma_store_wait();
+        __syncwarp();
+    }
+
+    if constexpr (!Ops::kIsNccl) {
+        // Preserve IBGDA's per-thread system fence before the leading grid
+        // synchronization. Every producer must publish before block 0 can
+        // announce the remote barrier.
+        if constexpr (kFlushStores) gin.flush();
+        if constexpr (kSyncAtStart) {
+            local_grid_sync<kNumSMs, kNumThreads, kNumTimeoutCycles>(
+                workspace, thread_idx);
+        }
+    } else {
+        // Quiesce every block before one block flushes the shared NCCL GIN
+        // contexts. Without this ordering, block 0 could flush while another
+        // block is still posting puts and source buffers could be reused early.
+        if constexpr (kSyncAtStart) {
+            local_grid_sync<kNumSMs, kNumThreads, kNumTimeoutCycles>(
+                workspace, thread_idx);
+        } else {
+            static_assert(!kFlushStores || kNumScaleoutRanks == 1,
+                          "GIN flush requires a leading grid synchronization");
+        }
+        if constexpr (kFlushStores && kNumScaleoutRanks > 1) {
+            // Only a participating scale-out barrier needs to flush GIN. A
+            // scale-up-only epilogue has already consumed/acknowledged every
+            // rail put through its strong completion tails.
+            if (do_scaleout) {
+                gin.flush();
+                local_grid_sync<kNumSMs, kNumThreads, kNumTimeoutCycles>(
+                    workspace, thread_idx);
+            }
+        }
     }
 
     do_scaleout &= kNumScaleoutRanks > 1;
     do_scaleup &= kNumScaleupRanks > 1;
-    if (do_scaleup && !do_scaleout) {
-        mooncake_barrier_wo_local_sync<transport::ScaleupTeam, kNumScaleupRanks,
-                                       kNumSMs, kNumThreads, kNumTimeoutCycles,
-                                       kTag>(gin, workspace, scaleup_rank_idx,
-                                             sm_idx, thread_idx);
-    } else if (do_scaleout && !do_scaleup) {
-        mooncake_barrier_wo_local_sync<transport::ScaleoutTeam,
-                                       kNumScaleoutRanks, kNumSMs, kNumThreads,
-                                       kNumTimeoutCycles, kTag>(
-            gin, workspace, scaleout_rank_idx, sm_idx, thread_idx);
-    } else {
-        const int global_rank =
-            scaleout_rank_idx * kNumScaleupRanks + scaleup_rank_idx;
-        mooncake_barrier_wo_local_sync<
-            transport::WorldTeam, kNumScaleoutRanks * kNumScaleupRanks, kNumSMs,
-            kNumThreads, kNumTimeoutCycles, kTag>(gin, workspace, global_rank,
-                                                  sm_idx, thread_idx);
+#ifdef USE_NCCL_DEVICE
+    if constexpr (Ops::kIsNccl) {
+        if (do_scaleup && !do_scaleout) {
+            mooncake_barrier_wo_local_sync<
+                Ops, transport::ScaleupTeam, kNumScaleupRanks, kNumSMs,
+                kNumThreads, kNumTimeoutCycles, kTag>(
+                gin, workspace, scaleup_rank_idx, sm_idx, thread_idx);
+        } else if (do_scaleout && !do_scaleup) {
+            nccl_gin_barrier_wo_local_sync<transport::ScaleoutTeam,
+                                           kNumScaleoutRanks, kNumThreads,
+                                           kNumTimeoutCycles, kTag>(
+                gin, workspace, scaleout_rank_idx, sm_idx, thread_idx);
+        } else if (do_scaleup && do_scaleout) {
+            if constexpr (kNumSMs > 1) {
+                // Separate blocks let LSA and GIN progress concurrently. They
+                // use disjoint signal addresses.
+                mooncake_barrier_wo_local_sync<
+                    Ops, transport::ScaleupTeam, kNumScaleupRanks, kNumSMs,
+                    kNumThreads, kNumTimeoutCycles, kTag>(
+                    gin, workspace, scaleup_rank_idx, sm_idx, thread_idx);
+                nccl_gin_barrier_wo_local_sync<transport::ScaleoutTeam,
+                                               kNumScaleoutRanks, kNumThreads,
+                                               kNumTimeoutCycles, kTag>(
+                    gin, workspace, scaleout_rank_idx, sm_idx - 1, thread_idx);
+            } else {
+                // A one-block launch cannot overlap teams safely. Complete LSA
+                // first and then the GIN rail barrier.
+                mooncake_barrier_wo_local_sync<Ops, transport::ScaleupTeam,
+                                               kNumScaleupRanks, 1, kNumThreads,
+                                               kNumTimeoutCycles, kTag>(
+                    gin, workspace, scaleup_rank_idx, 0, thread_idx);
+                nccl_gin_barrier_wo_local_sync<transport::ScaleoutTeam,
+                                               kNumScaleoutRanks, kNumThreads,
+                                               kNumTimeoutCycles, kTag>(
+                    gin, workspace, scaleout_rank_idx, 0, thread_idx);
+            }
+        }
+    } else
+#endif
+    {
+        // Keep the established IBGDA barrier byte-for-byte in behavior.
+        if (do_scaleup && !do_scaleout) {
+            mooncake_barrier_wo_local_sync<
+                Ops, transport::ScaleupTeam, kNumScaleupRanks, kNumSMs,
+                kNumThreads, kNumTimeoutCycles, kTag>(
+                gin, workspace, scaleup_rank_idx, sm_idx, thread_idx);
+        } else if (do_scaleout && !do_scaleup) {
+            mooncake_barrier_wo_local_sync<
+                Ops, transport::ScaleoutTeam, kNumScaleoutRanks, kNumSMs,
+                kNumThreads, kNumTimeoutCycles, kTag>(
+                gin, workspace, scaleout_rank_idx, sm_idx, thread_idx);
+        } else {
+            const int global_rank =
+                scaleout_rank_idx * kNumScaleupRanks + scaleup_rank_idx;
+            mooncake_barrier_wo_local_sync<
+                Ops, transport::WorldTeam, kNumScaleoutRanks * kNumScaleupRanks,
+                kNumSMs, kNumThreads, kNumTimeoutCycles, kTag>(
+                gin, workspace, global_rank, sm_idx, thread_idx);
+        }
     }
 
     if constexpr (kSyncAtEnd) {
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_compiled.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_compiled.cuh
index 1850361106..e5b277f8f6 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_compiled.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_compiled.cuh
@@ -28,8 +28,7 @@
 #endif
 
 #include <cstdint>
-#include <cuda_bf16.h>
-#include <cuda_runtime.h>
+#include <cuda_alike.h>
 
 #if defined(MOONCAKE_EP_USE_MUSA) && defined(__MCC__) && \
     !defined(MOONCAKE_EP_MUSA_LDG_DEFINED)
@@ -40,7 +39,7 @@ __device__ __forceinline__ dtype_t __ldg(const dtype_t* ptr) {
 }
 #endif
 
-#ifndef DISABLE_SM90_FEATURES
+#if !defined(MOONCAKE_EP_USE_MUSA) && !defined(DISABLE_SM90_FEATURES)
 #include <cuda_fp8.h>
 #elif !defined(MOONCAKE_EP_USE_MUSA)
 // Ampere does not support FP8 features
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_copy_epilogue.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_copy_epilogue.cuh
index 47cfca8401..8c9955d90c 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_copy_epilogue.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_copy_epilogue.cuh
@@ -32,7 +32,8 @@ __global__ void __launch_bounds__(kNumThreads, 1) dispatch_copy_epilogue_impl(
     const auto sm_idx = static_cast<int>(blockIdx.x),
                thread_idx = static_cast<int>(threadIdx.x);
     const auto warp_idx = ptx::get_warp_idx(), lane_idx = ptx::get_lane_idx();
-    const auto global_warp_idx = warp_idx * kNumSMs + sm_idx;
+    const auto num_sms = kNumSMs == 0 ? static_cast<int>(gridDim.x) : kNumSMs;
+    const auto global_warp_idx = warp_idx * num_sms + sm_idx;
 
     // For top-k index transformations
     constexpr int kNumExpertsPerRank = kNumExperts / kNumRanks;
@@ -77,7 +78,7 @@ __global__ void __launch_bounds__(kNumThreads, 1) dispatch_copy_epilogue_impl(
     int current_rank_start = 0, current_rank_end = 0;
 #pragma unroll
     for (int i = global_warp_idx; i < num_recv_tokens;
-         i += kNumWarps * kNumSMs) {
+         i += kNumWarps * num_sms) {
         // Calculate token index in the buffer
         while (i >= current_rank_end) {
             current_rank_idx += 1;
@@ -256,7 +257,7 @@ __global__ void __launch_bounds__(kNumThreads, 1) dispatch_copy_epilogue_impl(
         const auto workspace_layout = layout::WorkspaceLayout(
             workspace, kNumScaleoutRanks, kNumScaleupRanks, kNumExperts);
         for (int i = global_warp_idx; i < kNumChannels;
-             i += kNumSMs * kNumWarps) {
+             i += num_sms * kNumWarps) {
 #pragma unroll
             for (int j = 0; j < kNumScaleupRanksPerLane; ++j) {
                 if (const auto k = j * 32 + lane_idx;
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_official.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_official.cuh
index 761392dde4..98be7026c3 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_official.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_dispatch_official.cuh
@@ -15,11 +15,12 @@
 
 namespace mooncake::elastic {
 
-template <bool kIsScaleupNVLink, bool kDoCPUSync, bool kReuseSlotIndices,
-          int kNumSMs, int kNumNotifyWarps, int kNumDispatchWarps,
-          int kNumRanks, int kNumHiddenBytes, int kNumSFPacks,
-          int kNumMaxTokensPerRank, int kNumExperts, int kNumTopk,
-          int kExpertAlignment, int kNumQPs, int64_t kNumTimeoutCycles,
+template <typename Ops, bool kIsScaleupNVLink, bool kDoCPUSync,
+          bool kReuseSlotIndices, int kNumSMs, int kNumNotifyWarps,
+          int kNumDispatchWarps, int kNumRanks, int kNumHiddenBytes,
+          int kNumSFPacks, int kNumMaxTokensPerRank, int kNumExperts,
+          int kNumTopk, int kExpertAlignment, int kNumQPs,
+          int64_t kNumTimeoutCycles,
           int kNumNotifyThreads = kNumNotifyWarps * 32,
           int kNumDispatchThreads = kNumDispatchWarps * 32,
           int kNumThreads = kNumNotifyThreads + kNumDispatchThreads,
@@ -33,8 +34,9 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                   int* psum_num_recv_tokens_per_expert,
                   int* dst_buffer_slot_idx, const int num_tokens,
                   const int sf_token_stride, const int sf_hidden_stride,
-                  const device::CommCtx comm_ctx, void* buffer, void* workspace,
-                  void* mapped_host_workspace, const int rank_idx) {
+                  const typename Ops::Context comm_ctx, void* buffer,
+                  void* workspace, void* mapped_host_workspace,
+                  const int rank_idx) {
     constexpr int kNumExpertsPerRank = kNumExperts / kNumRanks;
     EP_STATIC_ASSERT(kNumExperts % kNumRanks == 0,
                      "Invalid number of experts or ranks");
@@ -71,11 +73,11 @@ __global__ void __launch_bounds__(kNumThreads, 1)
         comm::get_qp_mode<kNumSMs, kNumQPs, kNumDispatchWarps,
                           (kNumNotifyWarps > 0)>(
             sm_idx, warp_idx - kNumNotifyWarps, warp_idx < kNumNotifyWarps);
-    const auto gin = transport::MooncakeGin(comm_ctx, qp_idx, sharing_mode,
-                                            kNumQPs, 0, 0, 0, kNumRanks);
+    const auto gin =
+        Ops(comm_ctx, qp_idx, sharing_mode, kNumQPs, 0, 0, 0, kNumRanks);
 
     // Barrier without TMA store flush, without prologue grid sync
-    comm::gpu_barrier<kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
+    comm::gpu_barrier<Ops, kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
                       kNumQPs, kNumTimeoutCycles, comm::kDispatchTag0, false,
                       false, true>(gin, workspace_layout, 0, rank_idx, sm_idx,
                                    thread_idx);
@@ -178,9 +180,9 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 const auto dst_rank_counter =
                     workspace_layout.get_scaleup_rank_count_ptr<false>() +
                     rank_idx;
-                gin.put_value<team_t>(dst_rank_counter,
-                                      static_cast<int64_t>(rank_count[i]), i,
-                                      0);
+                gin.template put_value<team_t>(
+                    dst_rank_counter, static_cast<int64_t>(rank_count[i]), i,
+                    0);
             }
             __syncwarp();
 
@@ -193,7 +195,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                      i += kNumNotifyThreads) {
                     const auto idx = kNumExpertsPerRank * rank_idx +
                                      (i % kNumExpertsPerRank);
-                    gin.put_value<team_t>(
+                    gin.template put_value<team_t>(
                         workspace_layout.get_scaleup_expert_count_ptr<false>() +
                             idx,
                         static_cast<int64_t>(expert_count[i]),
@@ -209,8 +211,9 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                     const auto dst_ptr =
                         workspace_layout.get_scaleup_expert_count_ptr<false>() +
                         kNumExpertsPerRank * rank_idx;
-                    gin.put<team_t>(dst_ptr, src_ptr,
-                                    kNumExpertsPerRank * sizeof(int64_t), i);
+                    gin.template put<team_t>(
+                        dst_ptr, src_ptr, kNumExpertsPerRank * sizeof(int64_t),
+                        i);
                 }
             }
 
@@ -461,7 +464,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
             EP_STATIC_ASSERT(kNumTopk <= 32, "Invalid top-k selection");
             const auto dst_ptr =
                 stored_dst_slot_idx >= 0
-                    ? gin.get_sym_ptr<team_t>(
+                    ? gin.template get_sym_ptr<team_t>(
                           recv_buffer.get_token_buffer(stored_dst_slot_idx)
                               .get_base_ptr(),
                           stored_dst_rank_idx)
@@ -480,7 +483,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
                 // NOTES: we should skip the NVLink accessible ranks
                 if (stored_dst_slot_idx >= 0 and dst_ptr == nullptr) {
-                    gin.put<team_t>(
+                    gin.template put<team_t>(
                         recv_buffer.get_token_buffer(stored_dst_slot_idx)
                             .get_base_ptr(),
                         send_buffer_ptr, tma_buffer.get_num_bytes<false>(),
@@ -492,7 +495,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
     }
 
     // Barrier to ensure data arrival
-    comm::gpu_barrier<kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
+    comm::gpu_barrier<Ops, kIsScaleupNVLink, 1, kNumRanks, kNumSMs, kNumThreads,
                       kNumQPs, kNumTimeoutCycles, comm::kDispatchTag1, true,
                       true, false>(gin, workspace_layout, 0, rank_idx, sm_idx,
                                    thread_idx);
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_exception.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_exception.cuh
index 26e1c8b984..371f16ee8f 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_exception.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_exception.cuh
@@ -39,7 +39,7 @@
 #endif
 
 #ifndef EP_UNIFIED_ASSERT
-#ifdef __CUDA_ARCH__
+#if defined(__CUDA_ARCH__) || defined(__MUSA_ARCH__)
 #define EP_UNIFIED_ASSERT(cond) EP_DEVICE_ASSERT(cond)
 #else
 #define EP_UNIFIED_ASSERT(cond) EP_HOST_ASSERT(cond)
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_combine_official.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_combine_official.cuh
index 1689e8f01f..61c3a1bf40 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_combine_official.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_combine_official.cuh
@@ -14,10 +14,11 @@
 namespace mooncake::elastic {
 
 template <
-    bool kUseExpandedLayout, bool kAllowMultipleReduction, int kNumSMs,
-    int kNumScaleupWarps, int kNumForwardWarps, int kNumScaleoutRanks,
-    int kNumScaleupRanks, int kHidden, int kNumMaxTokensPerRank,
-    int kNumExperts, int kNumTopk, int kNumQPs, int64_t kNumTimeoutCycles,
+    typename Ops, bool kUseExpandedLayout, bool kAllowMultipleReduction,
+    int kNumSMs, int kNumScaleupWarps, int kNumForwardWarps,
+    int kNumScaleoutRanks, int kNumScaleupRanks, int kHidden,
+    int kNumMaxTokensPerRank, int kNumExperts, int kNumTopk, int kNumQPs,
+    int64_t kNumTimeoutCycles,
     int kNumScaleupRanksPerLane = math::constexpr_ceil_div(kNumScaleupRanks,
                                                            32),
     int kNumScaleupUpdateInterval = 3, int kNumChannelsPerSM = kNumForwardWarps,
@@ -41,7 +42,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         int* psum_num_recv_tokens_per_scaleup_rank,
                         int* token_metadata_at_forward,
                         int* channel_linked_list,
-                        const device::CommCtx comm_ctx, void* buffer,
+                        const typename Ops::Context comm_ctx, void* buffer,
                         void* workspace, const int scaleout_rank_idx,
                         const int scaleup_rank_idx, int num_reduced_tokens) {
     // Utils
@@ -99,14 +100,14 @@ __global__ void __launch_bounds__(kNumThreads, 1)
     const auto [qp_idx, sharing_mode] =
         comm::get_qp_mode<kNumSMs, kNumQPs, kNumChannelsPerSM>(
             sm_idx, warp_idx % kNumChannelsPerSM);
-    const auto gin = transport::MooncakeGin(
-        comm_ctx, qp_idx, sharing_mode, kNumQPs, scaleout_rank_idx,
-        scaleup_rank_idx, kNumScaleupRanks, kNumRanks);
+    const auto gin =
+        Ops(comm_ctx, qp_idx, sharing_mode, kNumQPs, scaleout_rank_idx,
+            scaleup_rank_idx, kNumScaleupRanks, kNumRanks);
 
     // Global parallel barriers for scale-out subteam and scale-up subteam
     // NOTES: this barrier needs a grid sync, as there are channel scale-up tail
     // cleaning before
-    comm::gpu_barrier<true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
+    comm::gpu_barrier<Ops, true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
                       kNumThreads, kNumQPs, kNumTimeoutCycles,
                       comm::kHybridCombineTag0, false, true, true>(
         gin, workspace_layout, scaleout_rank_idx, scaleup_rank_idx, sm_idx,
@@ -114,10 +115,17 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
     // Adjust register count at certain cases
     // TODO: support more cases, or try to make channel count more aligned
-    // DeepEP's register redistribution uses setmaxnreg, which is not accepted
-    // by ptxas for the SM90 target used by current Mooncake NV validation.
-    // Keep the official role split but disable this SM100-only optimization.
+    // setmaxnreg is rejected by the SM90 build used in Mooncake validation,
+    // but it materially improves the producer/forwarder split on Blackwell.
+#if defined(__CUDA_ARCH__) && __CUDA_ARCH__ >= 1000 && \
+    (defined(__CUDA_ARCH_SPECIFIC__) ||                \
+     defined(__CUDA_ARCH_FAMILY_SPECIFIC__))
+    constexpr bool kAdjustRegisters =
+        (kNumChannelsPerSM == 4 || kNumChannelsPerSM == 8) &&
+        !kUseExpandedLayout;
+#else
     constexpr bool kAdjustRegisters = false;
+#endif
     constexpr int kNumRegistersForScaleupWarps = 40;
     constexpr int kNumRegistersForForwardWarps =
         256 - kNumRegistersForScaleupWarps;
@@ -164,8 +172,8 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         if (stored_num_tokens_sent[i] !=
                             stored_old_num_tokens_sent[i])
                             ptx::st_release_sys(
-                                gin.get_sym_ptr<transport::ScaleupTeam>(
-                                    tail_ptr, j),
+                                gin.template get_sym_ptr<
+                                    transport::ScaleupTeam>(tail_ptr, j),
                                 stored_num_tokens_sent[i]);
                         stored_old_num_tokens_sent[i] =
                             stored_num_tokens_sent[i];
@@ -271,7 +279,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                     }
                 }();
                 token_buffer.set_base_ptr(
-                    gin.get_sym_ptr<transport::ScaleupTeam>(
+                    gin.template get_sym_ptr<transport::ScaleupTeam>(
                         token_buffer.get_base_ptr(), dst_scaleup_rank_idx));
 
                 // Some checks
@@ -377,7 +385,8 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                                                           kNumMaxTokensPerRank +
                                                       src_token_idx);
                             ptx::tma_store_1d(
-                                gin.get_sym_ptr<transport::ScaleupTeam>(
+                                gin.template get_sym_ptr<
+                                    transport::ScaleupTeam>(
                                     dst_token_buffer.get_base_ptr(),
                                     dst_scaleup_rank_idx),
                                 tma_buffer.get_base_ptr(),
@@ -464,11 +473,12 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
                 // Issue only if not local rank
                 if (last_src_scaleout_rank_idx != scaleout_rank_idx) {
-                    gin.put<transport::ScaleoutTeam>(
+                    gin.template put<transport::ScaleoutTeam>(
                         last_recv_token_buffer_ptr, last_send_token_buffer_ptr,
                         token_layout.get_num_bytes<false>(),
                         last_src_scaleout_rank_idx,
-                        last_is_token_last_in_chunk ? 0 : 0);
+                        last_is_token_last_in_chunk ? 0
+                                                    : Ops::kAggregateRequests);
                 }
             }
             __syncwarp();
@@ -615,13 +625,13 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                         // Issue IBGDA
                         topk_valid_mask ^= 1u << k;
                         if (src_scaleout_rank_idx != scaleout_rank_idx) {
-                            gin.put<transport::ScaleoutTeam>(
+                            gin.template put<transport::ScaleoutTeam>(
                                 recv_buffer_ptr, send_buffer_ptr,
                                 token_layout.get_num_bytes<false>(),
                                 src_scaleout_rank_idx,
                                 topk_valid_mask == 0 and is_token_last_in_chunk
                                     ? 0
-                                    : 0);
+                                    : Ops::kAggregateRequests);
                         }
                     }
                 }
@@ -743,26 +753,55 @@ __global__ void __launch_bounds__(kNumThreads, 1)
         }
         __syncwarp();
 
+        // Settle this channel's source buffers before publishing completion.
+        // The matching remote tail signals below acknowledge every preceding
+        // put on this context, so no additional grid-wide flush is needed.
+        if constexpr (Ops::kIsNccl) gin.flush_channel();
+
         // Update, wait and clean
         EP_STATIC_ASSERT(kNumScaleoutRanks <= 32, "Invalid ranks");
+        const auto expected_signal = math::pack2<int, int64_t>(1, 0);
         if (lane_idx < kNumScaleoutRanks) {
             // Update remote tails
-            const auto expected_signal = math::pack2<int, int64_t>(1, 0);
-            gin.red_add_rel<transport::ScaleoutTeam>(
+            auto* remote_tail =
                 workspace_layout.get_scaleout_channel_signaled_tail_ptr(
-                    channel_idx, scaleout_rank_idx),
-                expected_signal, lane_idx);
+                    channel_idx, scaleout_rank_idx);
+            if constexpr (Ops::kIsNccl) {
+                gin.template red_add_rel<transport::ScaleoutTeam>(
+                    remote_tail, expected_signal, lane_idx);
+            } else {
+                gin.template publish_tail<transport::ScaleoutTeam>(
+                    remote_tail, channel_idx, expected_signal, expected_signal,
+                    lane_idx);
+            }
+        }
+        __syncwarp();
 
-            // Wait tail arrival
+        // Wait tail arrival. Keep the NCCL poll independent of `gin` so the
+        // timeout lambda does not capture and spill the full GIN handle.
+        if (lane_idx < kNumScaleoutRanks) {
             const auto wait_ptr =
                 workspace_layout.get_scaleout_channel_signaled_tail_ptr(
                     channel_idx, lane_idx);
             comm::timeout_while<kNumTimeoutCycles>([=](const bool&
                                                            is_last_check) {
-                const auto signal = ptx::ld_acquire_sys<int64_t>(wait_ptr);
+                int64_t signal;
+                if constexpr (Ops::kIsNccl) {
+                    signal = ptx::ld_acquire_sys<int64_t>(wait_ptr);
+                } else {
+                    signal = gin.template read_completion_tail<
+                        transport::ScaleoutTeam>(wait_ptr, channel_idx,
+                                                 lane_idx);
+                }
                 if (signal == expected_signal) {
                     // Clean for next usages
-                    *wait_ptr = 0;
+                    if constexpr (Ops::kIsNccl) {
+                        *wait_ptr = 0;
+                    } else {
+                        gin.template clear_completion_tail<
+                            transport::ScaleoutTeam>(wait_ptr, channel_idx,
+                                                     lane_idx);
+                    }
                     return true;
                 }
 
@@ -780,8 +819,6 @@ __global__ void __launch_bounds__(kNumThreads, 1)
         }
         __syncwarp();
     }
-
-    // No barrier at epilogue
 }
 
 }  // namespace mooncake::elastic
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_dispatch_official.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_dispatch_official.cuh
index 9211911d87..99f83f7e01 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_dispatch_official.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_hybrid_dispatch_official.cuh
@@ -15,10 +15,10 @@
 namespace mooncake::elastic {
 
 template <
-    bool kDoCPUSync, bool kReuseSlotIndices, int kNumSMs, int kNumNotifyWarps,
-    int kNumScaleoutWarps, int kNumForwardWarps, int kNumScaleoutRanks,
-    int kNumScaleupRanks, int kNumHiddenBytes, int kNumSFPacks,
-    int kNumMaxTokensPerRank, int kNumExperts, int kNumTopk,
+    typename Ops, bool kDoCPUSync, bool kReuseSlotIndices, int kNumSMs,
+    int kNumNotifyWarps, int kNumScaleoutWarps, int kNumForwardWarps,
+    int kNumScaleoutRanks, int kNumScaleupRanks, int kNumHiddenBytes,
+    int kNumSFPacks, int kNumMaxTokensPerRank, int kNumExperts, int kNumTopk,
     int kExpertAlignment, int kNumQPs, int64_t kNumTimeoutCycles,
     int kNumScaleupRanksPerLane = math::constexpr_ceil_div(kNumScaleupRanks,
                                                            32),
@@ -26,7 +26,7 @@ template <
     int kNumChannels = kNumScaleoutWarps * kNumSMs,
     int kNumMaxTokensPerChannel = math::constexpr_ceil_div(kNumMaxTokensPerRank,
                                                            kNumChannels),
-    int kScaleoutUpdateInterval = 3,
+    int kScaleoutUpdateInterval = Ops::kScaleoutUpdateInterval,
     int kNumSlotsPerForwardChunk = kScaleoutUpdateInterval,
     int kNumRanks = kNumScaleoutRanks * kNumScaleupRanks,
     int kNumNotifyThreads = kNumNotifyWarps * 32,
@@ -44,7 +44,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                          int* token_metadata_at_forward, const int num_tokens,
                          const int sf_token_stride, const int sf_hidden_stride,
                          // TODO(NCCL): so many params, plans to optimize?
-                         const device::CommCtx comm_ctx, void* buffer,
+                         const typename Ops::Context comm_ctx, void* buffer,
                          void* workspace, void* mapped_host_workspace,
                          const int scaleout_rank_idx,
                          const int scaleup_rank_idx) {
@@ -92,12 +92,12 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                           (kNumNotifyWarps > 0)>(
             sm_idx, (warp_idx - kNumNotifyWarps) % kNumChannelsPerSM,
             warp_idx < kNumNotifyWarps);
-    const auto gin = transport::MooncakeGin(
-        comm_ctx, qp_idx, sharing_mode, kNumQPs, scaleout_rank_idx,
-        scaleup_rank_idx, kNumScaleupRanks, kNumRanks);
+    const auto gin =
+        Ops(comm_ctx, qp_idx, sharing_mode, kNumQPs, scaleout_rank_idx,
+            scaleup_rank_idx, kNumScaleupRanks, kNumRanks);
 
     // Global parallel barriers for scale-out subteam and scale-up subteam
-    comm::gpu_barrier<true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
+    comm::gpu_barrier<Ops, true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
                       kNumThreads, kNumQPs, kNumTimeoutCycles,
                       comm::kHybridDispatchTag0, false, false, true>(
         gin, workspace_layout, scaleout_rank_idx, scaleup_rank_idx, sm_idx,
@@ -226,13 +226,14 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 "kNumScaleoutRanks must be less than kNumNotifyThreads");
             if (thread_idx < kNumScaleoutRanks) {
                 const auto dst_scaleout_rank_idx = thread_idx;
-                gin.put<transport::ScaleoutTeam>(
+                gin.template put<transport::ScaleoutTeam>(
                     workspace_layout.get_scaleout_rank_count_ptr<false>(
                         scaleout_rank_idx),
                     workspace_layout.get_scaleout_rank_count_ptr<true>(
                         dst_scaleout_rank_idx),
-                    kNumScaleupRanks * sizeof(int), dst_scaleout_rank_idx, 0);
-                gin.put<transport::ScaleoutTeam>(
+                    kNumScaleupRanks * sizeof(int), dst_scaleout_rank_idx,
+                    Ops::kAggregateRequests);
+                gin.template put<transport::ScaleoutTeam>(
                     workspace_layout.get_scaleout_expert_count_ptr<false>(
                         scaleout_rank_idx),
                     workspace_layout.get_scaleout_expert_count_ptr<true>(
@@ -294,7 +295,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 // Write into the remote scale-up peer
                 const int64_t counter =
                     (static_cast<int64_t>(kNumScaleupRanks) << 32ll) | count;
-                gin.put_value<transport::ScaleupTeam>(
+                gin.template put_value<transport::ScaleupTeam>(
                     workspace_layout.get_scaleup_rank_count_ptr<false>() +
                         scaleup_rank_idx,
                     counter, i);
@@ -318,7 +319,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 const int64_t counter = (1ll << 32ll) | count;
                 const auto dst_scaleup_rank_idx = i / kNumExpertsPerRank;
                 const auto expert_idx_in_dst_rank = i % kNumExpertsPerRank;
-                gin.red_add_rel<transport::ScaleupTeam>(
+                gin.template red_add_rel<transport::ScaleupTeam>(
                     workspace_layout.get_scaleup_expert_count_ptr<false>() +
                         expert_idx_in_dst_rank,
                     counter, dst_scaleup_rank_idx);
@@ -450,8 +451,9 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 // NOTES: the "release" scope will be `sys` for the local rank
                 // (we may involve NVLink so not `gpu`) For RDMA requests,
                 // "release" is ensured by "atomic"
-                gin.red_add_rel<transport::ScaleoutTeam>(
-                    ptr, signaled_tail - old_signaled_tail, lane_idx,
+                gin.template publish_tail<transport::ScaleoutTeam>(
+                    ptr, channel_idx, signaled_tail,
+                    signaled_tail - old_signaled_tail, lane_idx,
                     transport::kRedAddReleaseLowWordLast);
                 stored_old_scaleout_tail = stored_scaleout_tail;
             }
@@ -585,13 +587,13 @@ __global__ void __launch_bounds__(kNumThreads, 1)
             // Issue IBGDA requests
             if (stored_dst_slot_idx >= 0 and
                 stored_dst_scaleout_rank_idx != scaleout_rank_idx) {
-                gin.put<transport::ScaleoutTeam>(
+                gin.template put<transport::ScaleoutTeam>(
                     scaleout_recv_buffer.get_token_buffer(stored_dst_slot_idx)
                         .get_base_ptr(),
                     scaleout_send_buffer.get_token_buffer(token_idx)
                         .get_base_ptr(),
                     tma_buffer.get_num_bytes<false>(),
-                    stored_dst_scaleout_rank_idx, 0);
+                    stored_dst_scaleout_rank_idx, Ops::kAggregateRequests);
             }
             __syncwarp();
 
@@ -677,9 +679,13 @@ __global__ void __launch_bounds__(kNumThreads, 1)
 
                 // Read new signaled tails
                 if (lane_idx < kNumScaleoutRanks) {
-                    const auto signaled_tail = ptx::ld_acquire_sys<int64_t>(
-                        workspace_layout.get_scaleout_channel_signaled_tail_ptr(
-                            channel_idx, lane_idx));
+                    const auto signaled_tail =
+                        gin.template read_completion_tail<
+                            transport::ScaleoutTeam>(
+                            workspace_layout
+                                .get_scaleout_channel_signaled_tail_ptr(
+                                    channel_idx, lane_idx),
+                            channel_idx, lane_idx);
                     math::unpack2<int, int64_t>(signaled_tail,
                                                 stored_finish_flag,
                                                 stored_scaleout_tail_idx);
@@ -779,7 +785,7 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 // Issue TMAs
                 if (stored_dst_slot_idx >= 0) {
                     const auto dst_ptr =
-                        gin.get_sym_ptr<transport::ScaleupTeam>(
+                        gin.template get_sym_ptr<transport::ScaleupTeam>(
                             scaleup_buffer.get_token_buffer(stored_dst_slot_idx)
                                 .get_base_ptr(),
                             stored_dst_scaleup_rank_idx);
@@ -848,7 +854,8 @@ __global__ void __launch_bounds__(kNumThreads, 1)
                 if (const auto j = i * 32 + lane_idx;
                     i < (kNumScaleupRanksPerLane - 1) or j < kNumScaleupRanks) {
                     ptx::st_relaxed_sys(
-                        gin.get_sym_ptr<transport::ScaleupTeam>(tail_ptr, j),
+                        gin.template get_sym_ptr<transport::ScaleupTeam>(
+                            tail_ptr, j),
                         transform_linked_list_idx(
                             stored_scaleup_send_counters[i]));
                 }
@@ -857,16 +864,19 @@ __global__ void __launch_bounds__(kNumThreads, 1)
         __syncwarp();
 
         // Clean tails for next usages
-        if (lane_idx < kNumScaleoutRanks)
-            *workspace_layout.get_scaleout_channel_signaled_tail_ptr(
-                channel_idx, lane_idx) = 0;
+        if (lane_idx < kNumScaleoutRanks) {
+            gin.template clear_completion_tail<transport::ScaleoutTeam>(
+                workspace_layout.get_scaleout_channel_signaled_tail_ptr(
+                    channel_idx, lane_idx),
+                channel_idx, lane_idx);
+        }
         __syncwarp();
     }
 
     // Scale-up barrier to ensure data arrival
     // As scale-out tokens have already been consumed by forwarders, no need to
     // do scale-out barrier again
-    comm::gpu_barrier<true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
+    comm::gpu_barrier<Ops, true, kNumScaleoutRanks, kNumScaleupRanks, kNumSMs,
                       kNumThreads, kNumQPs, kNumTimeoutCycles,
                       comm::kHybridDispatchTag1, true, true, false>(
         gin, workspace_layout, scaleout_rank_idx, scaleup_rank_idx, sm_idx,
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_launch.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_launch.cuh
index e21c86a170..7b396e42b5 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_launch.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_launch.cuh
@@ -2,12 +2,39 @@
 
 #include <cstdint>
 
-#include <cuda_bf16.h>
-#include <cuda_runtime.h>
+#include <cuda_alike.h>
+
+#ifdef USE_NCCL_DEVICE
+#include <transport/device/nccl_device_transport.h>
+#endif
 
 namespace mooncake {
 
+enum class ElasticTransportBackend : uint8_t {
+    kIbgda = 0,
+    kNccl = 1,
+};
+
+#ifdef USE_NCCL_DEVICE
+namespace elastic::transport {
+
+// Everything the NCCL kernel adapter needs in addition to NCCL's opaque
+// device context. The pointer fields identify offsets in the symmetric NCCL
+// registration; rank/team metadata is kept explicit so hot device paths do
+// not need capability queries.
+struct NcclContext {
+    device::NcclDeviceContext device;
+};
+
+}  // namespace elastic::transport
+#endif
+
 struct ElasticLaunchContext {
+    ElasticTransportBackend backend = ElasticTransportBackend::kIbgda;
+    int device_id = -1;
+#ifdef USE_NCCL_DEVICE
+    elastic::transport::NcclContext nccl;
+#endif
     void* gdr_buffer = nullptr;
     const int32_t* nvlink_available = nullptr;
     void* const* ipc_peer_ptrs = nullptr;
@@ -53,8 +80,8 @@ void launch_mooncake_elastic_dispatch_copy_epilogue(
     float* recv_topk_weights, int* recv_src_metadata, int* channel_linked_list,
     int num_recv_tokens, int num_max_tokens_per_rank, int hidden, int elem_size,
     int num_sf_packs, int recv_sf_token_stride, int recv_sf_hidden_stride,
-    int num_experts, int num_topk, int num_sms, int num_smem_bytes,
-    int num_channels, bool do_expand, bool cached_mode,
+    int num_experts, int num_topk, int num_sms, int num_epilogue_sms,
+    int num_smem_bytes, int num_channels, bool do_expand, bool cached_mode,
     const ElasticLaunchContext& ctx, int* psum_num_recv_tokens_per_scaleup_rank,
     int* psum_num_recv_tokens_per_expert, cudaStream_t stream);
 
@@ -71,8 +98,8 @@ void launch_mooncake_elastic_combine_reduce_epilogue(
     void* combined_x, float* combined_topk_weights, int64_t* combined_topk_idx,
     int num_combined_tokens, int num_max_tokens_per_rank, int hidden,
     int num_experts, int num_topk, void* reduce_buffer, void* bias_0,
-    void* bias_1, int num_sms, int num_smem_bytes, bool use_expanded_layout,
-    bool allow_multiple_reduction, const ElasticLaunchContext& ctx,
-    cudaStream_t stream);
+    void* bias_1, int num_sms, int num_epilogue_sms, int num_smem_bytes,
+    bool use_expanded_layout, bool allow_multiple_reduction,
+    const ElasticLaunchContext& ctx, cudaStream_t stream);
 
 }  // namespace mooncake
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_layout.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_layout.cuh
index f03d5943bb..809c84a81b 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_layout.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_layout.cuh
@@ -3,6 +3,7 @@
 // transport references are replaced with Mooncake Device API adapters.
 #pragma once
 
+#include <mooncake_ep_configs.cuh>
 #include <elastic/mooncake_ep_elastic_compiled.cuh>
 #include <elastic/mooncake_ep_elastic_exception.cuh>
 #include <elastic/mooncake_ep_elastic_math.cuh>
@@ -24,13 +25,10 @@ struct WorkspaceLayout {
     static constexpr int kNumMaxExpertsPerRank = 256;
     static constexpr int kNumMaxInflightAGRS = 32;
 
-    // Mooncake Device API does not rely on NCCL GIN remote RED on a single
-    // symmetric signal word.  Use per-source-rank signal slots for both phases:
-    // each sender atomically updates its own slot with release semantics and
-    // receivers poll the full slot vector.  Keep an independent counter/slot
-    // vector for each logical barrier tag, as hybrid kernels mix world and
-    // scale-up-only barriers in the same workspace and therefore must not share
-    // phase/sign state across tags.
+    // Reserve per-source-rank signal slots for the portable IBGDA barrier.
+    // NCCL LSA barriers aggregate arrivals in the first slot of each phase.
+    // Each logical barrier tag needs independent phase/sign state because
+    // hybrid kernels mix world and scale-up-only barriers in one workspace.
     static constexpr int kNumBarrierTags = 16;
     static constexpr int64_t kNumBarrierBytesPerTag =
         sizeof(unsigned long long) + 2 * kNumMaxRanks * sizeof(int);
@@ -52,8 +50,8 @@ struct WorkspaceLayout {
         EP_UNIFIED_ASSERT(num_experts_per_rank <= kNumMaxExpertsPerRank);
     }
 
-    static int64_t get_num_bytes() {
-        // Pure NVLink scaleup barrier signals
+    __forceinline__ __device__ __host__ static int64_t get_num_bytes() {
+        // Pure NVLink scaleup barrier signals.
         int64_t num_bytes = 0;
         num_bytes += kNumBarrierSignalBytes;
 
@@ -85,7 +83,7 @@ struct WorkspaceLayout {
         // Rank send/recv count, for PP prev/next ranks
         num_bytes += 2 * 2 * sizeof(int64_t);
 
-        // AGRS signals
+        // All-gather/reduce-scatter signals
         num_bytes += (kNumMaxInflightAGRS + 1) * kNumMaxRanks * sizeof(int);
 
         // Ensure LDG.256 work
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_ptx.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_ptx.cuh
index f1fa20650e..c9cfff26ac 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_ptx.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_ptx.cuh
@@ -3,7 +3,7 @@
 // transport references are replaced with Mooncake Device API adapters.
 #pragma once
 
-#include <cuda_bf16.h>
+#include <cuda_alike.h>
 #include <cstdint>
 
 #include <elastic/mooncake_ep_elastic_compiled.cuh>
@@ -22,7 +22,7 @@ using arrival_phase = uint32_t;
 // More than TMA, `longlong4` requires 32 bytes aligned
 static constexpr int kNumTMAAlignBytes = 32;
 
-#ifdef __CUDACC__
+#if defined(__CUDACC__) || defined(__MUSACC__)
 
 /// Exceptions
 __forceinline__ __device__ void trap() {
@@ -521,6 +521,30 @@ __forceinline__ __device__ void red_add_rel_sys(const int64_t* ptr,
 #endif
 }
 
+__forceinline__ __device__ void red_add_rel_gpu(const int* ptr,
+                                                const int& value) {
+#ifdef MOONCAKE_EP_USE_MUSA
+    atomicAdd(const_cast<int*>(ptr), value);
+    __threadfence();
+#else
+    asm volatile("red.release.gpu.global.add.s32 [%0], %1;" ::"l"(ptr),
+                 "r"(value));
+#endif
+}
+
+__forceinline__ __device__ void red_add_rel_gpu(const int64_t* ptr,
+                                                const int64_t& value) {
+#ifdef MOONCAKE_EP_USE_MUSA
+    atomicAdd(const_cast<unsigned long long*>(
+                  reinterpret_cast<const unsigned long long*>(ptr)),
+              static_cast<unsigned long long>(value));
+    __threadfence();
+#else
+    asm volatile("red.release.gpu.global.add.u64 [%0], %1;" ::"l"(ptr),
+                 "l"(value));
+#endif
+}
+
 template <typename dtype_t>
 __forceinline__ __device__ dtype_t ld_acquire_sys(const dtype_t* ptr) {
 #ifdef MOONCAKE_EP_USE_MUSA
diff --git a/mooncake-ep/include/elastic/mooncake_ep_elastic_transport.cuh b/mooncake-ep/include/elastic/mooncake_ep_elastic_transport.cuh
index 7855ce3a63..58df45b2fc 100644
--- a/mooncake-ep/include/elastic/mooncake_ep_elastic_transport.cuh
+++ b/mooncake-ep/include/elastic/mooncake_ep_elastic_transport.cuh
@@ -4,8 +4,13 @@
 #include <type_traits>
 
 #include <mooncake_ep_utils.cuh>
+#include <elastic/mooncake_ep_elastic_launch.cuh>
+#include <elastic/mooncake_ep_elastic_layout.cuh>
 #include <elastic/mooncake_ep_elastic_ptx.cuh>
 #include <transport/device/comm_device.cuh>
+#ifdef USE_NCCL_DEVICE
+#include <transport/device/nccl_device.cuh>
+#endif
 
 namespace mooncake::elastic::transport {
 
@@ -31,7 +36,27 @@ constexpr int kRedAddReleaseLowWordLast = 1 << 0;
 //
 // Team tags are kept as types so official DeepEP template code can remain close
 // to the source while the actual routing is decided by Mooncake CommCtx.
-struct MooncakeGin {
+struct IbgdaOps {
+    using Context = device::CommCtx;
+    static constexpr bool kIsNccl = false;
+    static constexpr int kNumQPs = MAX_QP_COUNT;
+    static constexpr int kAggregateRequests = 0;
+    // Preserve the established IPC + IBGDA tail-publication granularity.
+    static constexpr int kScaleoutUpdateInterval = 3;
+#ifdef MOONCAKE_EP_USE_MUSA
+    static constexpr int kNumDispatchWarps = 4;
+    static constexpr int kNumDispatchEpilogueWarps = 4;
+    static constexpr int kNumCombineWarps = 4;
+    static constexpr int kNumCombineEpilogueWarps = 4;
+#else
+    static constexpr int kNumDispatchWarps = 8;
+    static constexpr int kNumDispatchEpilogueWarps = 8;
+    static constexpr int kNumCombineWarps = 8;
+    static constexpr int kNumCombineEpilogueWarps = 8;
+#endif
+    static constexpr int kNumHybridScaleoutWarps = 4;
+    static constexpr int kNumHybridForwardWarps = 4;
+    static constexpr int kNumHybridScaleupWarps = 4;
     device::CommCtx ctx;
     int qp_idx = 0;
     int sharing_mode = 0;
@@ -40,10 +65,12 @@ struct MooncakeGin {
     int scaleup_rank_idx = 0;
     int num_scaleup_ranks = 0;
 
-    __device__ __forceinline__ MooncakeGin(
-        const device::CommCtx& ctx, int qp_idx, int sharing_mode, int num_qps,
-        int scaleout_rank_idx = 0, int scaleup_rank_idx = 0,
-        int num_scaleup_ranks = 0, int num_ranks = 1)
+    __device__ __forceinline__ IbgdaOps(const device::CommCtx& ctx, int qp_idx,
+                                        int sharing_mode, int num_qps,
+                                        int scaleout_rank_idx = 0,
+                                        int scaleup_rank_idx = 0,
+                                        int num_scaleup_ranks = 0,
+                                        int num_ranks = 1)
         : ctx(ctx),
           qp_idx(qp_idx),
           sharing_mode(sharing_mode),
@@ -255,7 +282,279 @@ struct MooncakeGin {
         }
     }
 
+    template <typename team_t>
+    __device__ __forceinline__ void reset_completion_tail(
+        int /*channel_idx*/, int /*sender_rank*/) const {}
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ value_t read_completion_tail(
+        value_t* ptr, int /*channel_idx*/, int /*sender_rank*/) const {
+        return ptx::ld_acquire_sys<value_t>(ptr);
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void clear_completion_tail(
+        value_t* ptr, int /*channel_idx*/, int /*sender_rank*/) const {
+        *ptr = 0;
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void publish_tail(value_t* dst_ptr,
+                                                 int channel_idx,
+                                                 value_t absolute_value,
+                                                 value_t delta, int dst_rank,
+                                                 int flags = 0) const {
+        (void)channel_idx;
+        (void)absolute_value;
+        red_add_rel<team_t>(dst_ptr, delta, dst_rank, flags);
+    }
+
     __device__ __forceinline__ void flush() const { __threadfence_system(); }
 };
 
+#ifdef USE_NCCL_DEVICE
+
+// NCCL implementation of the same compile-time kernel surface as IbgdaOps.
+// LSA peers use direct symmetric pointers. Hybrid scale-out uses NCCL's rail
+// team, while non-hybrid GIN operations use the full world team.
+struct NcclOps {
+    using Context = NcclContext;
+    static constexpr bool kIsNccl = true;
+    static constexpr int kNumQPs = 65;
+    static constexpr int kAggregateRequests = ncclGinOptFlagsAggregateRequests;
+    // Match current DeepEP v2 NCCL rail tail batching.
+    static constexpr int kScaleoutUpdateInterval = 6;
+    static constexpr int kNumDispatchWarps = 27;
+    static constexpr int kNumDispatchEpilogueWarps = 27;
+    static constexpr int kNumCombineWarps = 28;
+    static constexpr int kNumCombineEpilogueWarps = 28;
+    static constexpr int kNumHybridScaleoutWarps = 8;
+    static constexpr int kNumHybridForwardWarps = 8;
+    static constexpr int kNumHybridScaleupWarps = 8;
+
+    // Keep this adapter compact: it is captured by several kernel lambdas.
+    // Team/rank/window state already lives in the pre-bound handle, so
+    // retaining a second NcclContext here would create per-thread local-memory
+    // spills.
+    device::NcclGinHandle gin;
+
+    __device__ __forceinline__ NcclOps(const Context& ctx, int qp_idx,
+                                       int sharing_mode, int /*num_qps*/,
+                                       int /*scaleout_rank_idx*/ = 0,
+                                       int /*scaleup_rank_idx*/ = 0,
+                                       int /*num_scaleup_ranks*/ = 0,
+                                       int /*num_ranks*/ = 1)
+        : gin(ctx.device, static_cast<unsigned int>(qp_idx),
+              sharing_mode == 0 ? device::NcclGinResourceSharing::kCta
+                                : device::NcclGinResourceSharing::kGpu) {}
+
+    template <typename team_t>
+    __device__ __forceinline__ bool is_nvlink_accessible(int dst_rank) const {
+        if constexpr (std::is_same_v<team_t, ScaleupTeam>) {
+            return true;
+        } else if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+            return gin.railRank() == dst_rank;
+        } else {
+            return gin.worldRankInLsa(dst_rank);
+        }
+    }
+
+    template <typename team_t>
+    __device__ __forceinline__ bool is_gin_peer(int dst_rank) const {
+        return !is_nvlink_accessible<team_t>(dst_rank);
+    }
+
+    template <typename team_t, typename ptr_t>
+    __device__ __forceinline__ ptr_t* get_sym_ptr_impl(ptr_t* ptr,
+                                                       int dst_rank) const {
+        if constexpr (std::is_same_v<team_t, ScaleupTeam>) {
+            return static_cast<ptr_t*>(gin.lsaPeerPointer(dst_rank, ptr));
+        } else if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+            return gin.railRank() == dst_rank ? ptr : nullptr;
+        } else {
+            if (!gin.worldRankInLsa(dst_rank)) return nullptr;
+            return static_cast<ptr_t*>(gin.worldPeerPointer(dst_rank, ptr));
+        }
+    }
+
+    template <typename team_t>
+    __device__ __forceinline__ void* get_sym_ptr(void* ptr,
+                                                 int dst_rank) const {
+        return get_sym_ptr_impl<team_t>(static_cast<uint8_t*>(ptr), dst_rank);
+    }
+
+    template <typename team_t>
+    __device__ __forceinline__ const void* get_sym_ptr(const void* ptr,
+                                                       int dst_rank) const {
+        return get_sym_ptr_impl<team_t>(static_cast<const uint8_t*>(ptr),
+                                        dst_rank);
+    }
+
+    template <typename team_t>
+    __device__ __forceinline__ void put(void* dst_ptr, const void* src_ptr,
+                                        int num_bytes, int dst_rank,
+                                        int flags = 0) const {
+        if constexpr (std::is_same_v<team_t, ScaleupTeam>) {
+            auto* routed =
+                static_cast<uint8_t*>(get_sym_ptr<team_t>(dst_ptr, dst_rank));
+            const auto src_addr = reinterpret_cast<uintptr_t>(src_ptr);
+            const auto dst_addr = reinterpret_cast<uintptr_t>(routed);
+            if (((src_addr | dst_addr | static_cast<uintptr_t>(num_bytes)) &
+                 (sizeof(int4) - 1)) == 0) {
+                const auto* src = reinterpret_cast<const int4*>(src_ptr);
+                auto* dst = reinterpret_cast<int4*>(routed);
+                const int count = num_bytes / static_cast<int>(sizeof(int4));
+                for (int i = 0; i < count; ++i)
+                    dst[i] = device::mc_ld_nc(src + i);
+            } else {
+                const auto* src = static_cast<const uint8_t*>(src_ptr);
+                for (int i = 0; i < num_bytes; ++i) routed[i] = src[i];
+            }
+            __threadfence_system();
+        } else if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+            // Match NCCL's native GIN contract: world/rail puts always use the
+            // selected network context. Callers use get_sym_ptr explicitly
+            // when they want an LSA/local bypass.
+            gin.put<device::NcclGinTeam::kRail>(
+                dst_rank, src_ptr, dst_ptr, static_cast<uint32_t>(num_bytes),
+                static_cast<uint32_t>(flags));
+        } else {
+            gin.put<device::NcclGinTeam::kWorld>(
+                dst_rank, src_ptr, dst_ptr, static_cast<uint32_t>(num_bytes),
+                static_cast<uint32_t>(flags));
+        }
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void put_value(value_t* dst_ptr, value_t value,
+                                              int dst_rank,
+                                              int flags = 0) const {
+        static_assert(
+            std::is_scalar_v<value_t> && std::is_trivially_copyable_v<value_t>,
+            "NCCL EP put_value requires a trivially copyable scalar");
+        static_assert(sizeof(value_t) == sizeof(uint32_t) ||
+                          sizeof(value_t) == sizeof(uint64_t),
+                      "NCCL EP put_value supports only 4- or 8-byte values");
+        auto* routed = get_sym_ptr_impl<team_t>(dst_ptr, dst_rank);
+        if (routed != nullptr) {
+            ptx::st_relaxed_sys(routed, value);
+        } else if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+            gin.putValue<device::NcclGinTeam::kRail>(
+                dst_rank, dst_ptr, value, static_cast<uint32_t>(flags));
+        } else {
+            gin.putValue<device::NcclGinTeam::kWorld>(
+                dst_rank, dst_ptr, value, static_cast<uint32_t>(flags));
+        }
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void red_add_rel(value_t* dst_ptr, value_t value,
+                                                int dst_rank,
+                                                int /*flags*/ = 0) const {
+        auto* routed = get_sym_ptr_impl<team_t>(dst_ptr, dst_rank);
+        if (routed != nullptr) {
+            const bool use_gpu_scope =
+                std::is_same_v<team_t, ScaleoutTeam> || routed == dst_ptr;
+            if constexpr (sizeof(value_t) == sizeof(int32_t)) {
+                if (use_gpu_scope) {
+                    ptx::red_add_rel_gpu(reinterpret_cast<int*>(routed),
+                                         static_cast<int>(value));
+                } else {
+                    ptx::red_add_rel_sys(reinterpret_cast<int*>(routed),
+                                         static_cast<int>(value));
+                }
+            } else if constexpr (sizeof(value_t) == sizeof(uint64_t) ||
+                                 sizeof(value_t) == sizeof(int64_t)) {
+                if (use_gpu_scope) {
+                    ptx::red_add_rel_gpu(reinterpret_cast<int64_t*>(routed),
+                                         static_cast<int64_t>(value));
+                } else {
+                    ptx::red_add_rel_sys(reinterpret_cast<int64_t*>(routed),
+                                         static_cast<int64_t>(value));
+                }
+            }
+        } else if constexpr (sizeof(value_t) == sizeof(uint64_t) ||
+                             sizeof(value_t) == sizeof(int64_t)) {
+            if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+                gin.signalAdd<device::NcclGinTeam::kRail>(
+                    dst_rank, reinterpret_cast<uint64_t*>(dst_ptr),
+                    static_cast<uint64_t>(value));
+            } else {
+                gin.signalAdd<device::NcclGinTeam::kWorld>(
+                    dst_rank, reinterpret_cast<uint64_t*>(dst_ptr),
+                    static_cast<uint64_t>(value));
+            }
+        }
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ value_t read_completion_tail(
+        value_t* direct_ptr, int /*channel_idx*/, int /*sender_rank*/) const {
+        static_assert(sizeof(value_t) == sizeof(uint64_t),
+                      "NCCL completion tails must be 64-bit");
+        // NCCL's VA-signal read path resolves this same local window pointer
+        // and performs an acquire atomic load. Keep that operation explicit so
+        // the compiler does not instantiate unrelated runtime backend paths.
+        return ptx::ld_acquire_sys<value_t>(direct_ptr);
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void clear_completion_tail(
+        value_t* direct_ptr, int /*channel_idx*/, int /*sender_rank*/) const {
+        // Every NCCL backend resets a VA signal by storing zero to its local
+        // window address. The tail protocol guarantees that remote writers are
+        // quiescent before this cleanup.
+        *direct_ptr = 0;
+    }
+
+    template <typename team_t, typename value_t>
+    __device__ __forceinline__ void publish_tail(value_t* dst_ptr,
+                                                 int /*channel_idx*/,
+                                                 value_t absolute_value,
+                                                 value_t delta, int dst_rank,
+                                                 int flags = 0) const {
+        static_assert(sizeof(value_t) == sizeof(uint64_t),
+                      "NCCL completion tails must be 64-bit");
+        (void)absolute_value;
+        red_add_rel<team_t>(dst_ptr, delta, dst_rank, flags);
+    }
+
+    template <typename team_t>
+    __device__ __forceinline__ void gin_barrier_signal_inc(
+        int dst_team_rank, int signal_id) const {
+        if constexpr (std::is_same_v<team_t, ScaleoutTeam>) {
+            gin.signalIncContext0<device::NcclGinTeam::kRail>(dst_team_rank,
+                                                              signal_id);
+        } else {
+            gin.signalIncContext0<device::NcclGinTeam::kWorld>(dst_team_rank,
+                                                               signal_id);
+        }
+    }
+
+    __device__ __forceinline__ uint64_t
+    gin_barrier_advance_shadow(int signal_id) const {
+        return gin.advanceSignalShadowContext0(signal_id);
+    }
+
+    __device__ __forceinline__ uint64_t
+    gin_barrier_read_signal(int signal_id) const {
+        return gin.readSignalContext0(signal_id);
+    }
+
+    __device__ __forceinline__ void flush_channel() const { gin.flushWarp(); }
+
+    __device__ __forceinline__ void flush() const {
+        const int warps_per_block = static_cast<int>(blockDim.x) / warpSize;
+        const int global_warp = static_cast<int>(blockIdx.x) * warps_per_block +
+                                static_cast<int>(threadIdx.x) / warpSize;
+        const int num_warps = static_cast<int>(gridDim.x) * warps_per_block;
+        for (int context_idx = global_warp; context_idx < gin.contextCount();
+             context_idx += num_warps) {
+            gin.flushContextWarp(context_idx);
+        }
+    }
+};
+
+#endif  // USE_NCCL_DEVICE
+
 }  // namespace mooncake::elastic::transport
diff --git a/mooncake-ep/include/mooncake_ep_api.cuh b/mooncake-ep/include/mooncake_ep_api.cuh
index 1a560d1b90..bc747c2f22 100644
--- a/mooncake-ep/include/mooncake_ep_api.cuh
+++ b/mooncake-ep/include/mooncake_ep_api.cuh
@@ -1,6 +1,6 @@
 #pragma once
 
-#include <cuda_runtime.h>
+#include <cuda_alike.h>
 
 namespace mooncake {
 
diff --git a/mooncake-ep/include/mooncake_ep_buffer.h b/mooncake-ep/include/mooncake_ep_buffer.h
index 9307936c80..d2bfa38237 100644
--- a/mooncake-ep/include/mooncake_ep_buffer.h
+++ b/mooncake-ep/include/mooncake_ep_buffer.h
@@ -1,16 +1,17 @@
 #ifndef MOONCAKE_EP_BUFFER_H
 #define MOONCAKE_EP_BUFFER_H
 
-#include <ATen/cuda/CUDAContext.h>
-#include <cuda_bf16.h>
-#include <cuda.h>
-#include <cuda_runtime.h>
+#include <cuda_alike.h>
+#include <functional>
 #include <memory>
+#include <mutex>
+#include <optional>
+#include <unordered_map>
 #include <mooncake_ep_api.cuh>
 #include <mooncake_ep_configs.cuh>
 #include <mooncake_ep_event.h>
 #include <mooncake_ep_exception.cuh>
-#include <torch/torch.h>
+#include <glog/logging.h>
 #include <transport/device/device_transport.h>
 
 namespace mooncake {
@@ -72,9 +73,15 @@ struct MooncakeEpBuffer {
     int rank, num_ranks;
     int clock_rate_khz;
 
-    // GDR buffer — owned by p2p_transport_
+    // GDR buffer — allocated by p2p_transport_; peer mappings are optional.
     int buffer_idx{};
     int phase_epochs[2]{};
+    // TBO owns multiple logical dispatchers but shares one native Buffer.
+    // Keep a private top-k snapshot slot per dispatch metadata tensor so
+    // interleaved subbatches cannot overwrite one another.
+    std::mutex buffer_mutex;
+    std::unordered_map<uint64_t, int> dispatch_shadow_slots;
+    int next_shadow_slot = 0;
     int64_t num_ep_buffer_bytes;
     void* gdr_buffer = nullptr;
 
@@ -90,16 +97,16 @@ struct MooncakeEpBuffer {
     std::unique_ptr<device::RdmaTransport> owned_rdma_transport_;
 
     bool ibgda_disabled_ = false;
+    bool p2p_enabled_ = true;
 
     int USE_QP_COUNT = MAX_QP_COUNT;
-    // Cap on active RoCE QPs per peer: spreading small EP messages across too
-    // many QP/doorbell/progress streams hurts when GPUs share an HCA. Default
-    // 8; override at runtime with MOONCAKE_EP_ACTIVE_QPS_PER_RANK (>= per-rank
-    // QP count disables).
-    int active_qps_cap_ = 8;
+    // Active RoCE QPs per peer. The platform-specific default is selected in
+    // active_qps_per_rank_for_ep(); a positive
+    // MOONCAKE_EP_ACTIVE_QPS_PER_RANK value forces an explicit count.
+    int active_qps_cap_ = 0;
 
     // Stream for communication
-    at::cuda::CUDAStream comm_stream;
+    cudaStream_t comm_stream = nullptr;
 
     // Workspace
     void* workspace = nullptr;
@@ -109,31 +116,32 @@ struct MooncakeEpBuffer {
     // (engine owns the transports).  Otherwise EP creates its own via the
     // factory functions (EP owns them via owned_p2p_transport_ etc.).
     MooncakeEpBuffer(int rank, int num_ranks, int64_t num_ep_buffer_bytes,
+                     bool disable_p2p = false,
                      TransferEngine* engine = nullptr);
 
     ~MooncakeEpBuffer() noexcept(false);
 
-    std::tuple<torch::Tensor, std::optional<torch::Tensor>, torch::Tensor,
-               torch::Tensor, torch::Tensor, std::optional<EventHandle>,
-               std::optional<std::function<void()>>>
-    dispatch(const torch::Tensor& x, const torch::Tensor& topk_idx,
-             torch::Tensor& active_ranks, int num_max_dispatch_tokens_per_rank,
-             int num_experts, int timeout_us, bool use_fp8, bool async,
-             bool return_recv_hook);
-
-    std::tuple<torch::Tensor, std::optional<EventHandle>,
-               std::optional<std::function<void()>>>
-    combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
-            const torch::Tensor& topk_weights, const torch::Tensor& src_info,
-            const torch::Tensor& layout_range, torch::Tensor& active_ranks,
+    std::tuple<std::optional<EventHandle>, std::optional<std::function<void()>>>
+    dispatch(uint64_t x_ptr, uint64_t topk_idx_ptr, uint64_t active_ranks_ptr,
+             int num_tokens, int hidden, int num_topk,
+             int num_max_dispatch_tokens_per_rank, int num_experts,
+             int timeout_us, bool use_fp8, uint64_t packed_recv_x_ptr,
+             uint64_t packed_recv_x_scales_ptr, uint64_t packed_recv_count_ptr,
+             uint64_t packed_recv_src_info_ptr,
+             uint64_t packed_recv_layout_range_ptr, bool async,
+             bool return_recv_hook, uint64_t compute_stream_ptr);
+
+    std::tuple<std::optional<EventHandle>, std::optional<std::function<void()>>>
+    combine(uint64_t x_ptr, uint64_t topk_idx_ptr, uint64_t topk_weights_ptr,
+            uint64_t src_info_ptr, uint64_t layout_range_ptr,
+            uint64_t active_ranks_ptr, int num_local_experts,
+            int num_combined_tokens, int hidden, int num_topk,
             int num_max_dispatch_tokens_per_rank, int num_experts,
-            int timeout_us, bool zero_copy, bool async, bool return_recv_hook,
-            const std::optional<torch::Tensor>& out);
-
-    torch::Tensor get_next_combine_buffer(int num_max_dispatch_tokens_per_rank,
-                                          int hidden, int num_experts);
+            int timeout_us, bool zero_copy, uint64_t combined_x_ptr, bool async,
+            bool return_recv_hook, uint64_t compute_stream_ptr);
 
     bool ibgda_disabled() const { return ibgda_disabled_; }
+    bool p2p_enabled() const { return p2p_enabled_; }
 
     bool is_roce() const {
         return rdma_transport_ && rdma_transport_->isRoce();
diff --git a/mooncake-ep/include/mooncake_ep_configs.cuh b/mooncake-ep/include/mooncake_ep_configs.cuh
index 1e7f0c2149..5d05908f36 100644
--- a/mooncake-ep/include/mooncake_ep_configs.cuh
+++ b/mooncake-ep/include/mooncake_ep_configs.cuh
@@ -39,17 +39,23 @@
 #undef __CUDA_NO_BFLOAT162_OPERATORS__
 #endif
 
+#include <cuda_alike.h>
+#if !defined(MOONCAKE_EP_USE_MUSA) && !defined(MOONCAKE_EP_USE_MACA)
 #include <cuda_bf16.h>
-#ifndef MOONCAKE_EP_USE_MACA
 #include <cuda_fp8.h>
+#endif
+#ifndef MOONCAKE_EP_USE_MACA
 #include <infiniband/mlx5dv.h>
 #endif
-#include <cuda_runtime.h>
 
 #if defined(MOONCAKE_EP_USE_MUSA) || defined(MOONCAKE_EP_USE_MACA)
 #define MOONCAKE_EP_SPLIT_SEND_RECV 1
 #endif
 
+#if defined(MOONCAKE_EP_USE_MACA)
+#define MOONCAKE_EP_PHASE_ACK 1
+#endif
+
 // torchada maps nv_bfloat16 → __mt_bfloat16 which is an incomplete type on
 // MUSA, so sizeof(__mt_bfloat16) fails.  mt_bfloat16 (the complete typedef in
 // musa_bf16.hpp) requires the MUSA device compiler (mcc) and cannot be
diff --git a/mooncake-ep/include/mooncake_ep_device.h b/mooncake-ep/include/mooncake_ep_device.h
index e88417ff7f..0ab7b58f1d 100644
--- a/mooncake-ep/include/mooncake_ep_device.h
+++ b/mooncake-ep/include/mooncake_ep_device.h
@@ -13,14 +13,14 @@
 #include <musa_fp8.h>
 using ep_fp8_storage_t = __mt_fp8_storage_t;
 using ep_fp8x2_storage_t = __mt_fp8x2_storage_t;
-#if defined(__CUDACC__) || defined(__MCC__)
+#if defined(__CUDACC__) || defined(__MCC__) || defined(__MUSACC__)
 __device__ __forceinline__ ep_fp8x2_storage_t ep_cvt_float2_to_fp8x2(float2 x) {
     return __musa_cvt_float2_to_fp8x2(x, __MT_SATFINITE, __MT_E4M3);
 }
 #endif
 
 // -- Device intrinsics (MUSA doesn't have __ldg / __activemask) --------------
-#if (defined(__CUDACC__) || defined(__MCC__)) && \
+#if (defined(__CUDACC__) || defined(__MCC__) || defined(__MUSACC__)) && \
     !defined(MOONCAKE_EP_MUSA_LDG_DEFINED)
 #define MOONCAKE_EP_MUSA_LDG_DEFINED
 template <typename dtype_t>
@@ -32,7 +32,7 @@ __device__ __forceinline__ dtype_t __ldg(const dtype_t* ptr) {
 #define __activemask() (0xffffffff)
 #endif
 
-#if defined(__CUDACC__) || defined(__MCC__)
+#if defined(__CUDACC__) || defined(__MCC__) || defined(__MUSACC__)
 __forceinline__ __device__ int get_lane_id() { return threadIdx.x % 32; }
 #endif
 
@@ -44,15 +44,11 @@ __forceinline__ __device__ int get_lane_id() { return threadIdx.x % 32; }
     dim3 _block(num_threads);                             \
     cudaStream_t _stream = stream
 
-#define LAUNCH_KERNEL(config, kernel, ...)                     \
-    kernel<<<_grid, _block, 0, _stream>>>(__VA_ARGS__);        \
-    {                                                          \
-        auto _err = cudaGetLastError();                        \
-        if (_err != cudaSuccess) {                             \
-            fprintf(stderr, "[EP] kernel launch failed: %s\n", \
-                    cudaGetErrorString(_err));                 \
-        }                                                      \
-    }
+#define LAUNCH_KERNEL(config, kernel, ...)                  \
+    do {                                                    \
+        kernel<<<_grid, _block, 0, _stream>>>(__VA_ARGS__); \
+        CUDA_CHECK(cudaGetLastError());                     \
+    } while (false)
 
 #elif defined(MOONCAKE_EP_USE_MACA)
 
@@ -63,7 +59,7 @@ __forceinline__ __device__ int get_lane_id() { return threadIdx.x % 32; }
 #include <cstdint>
 using ep_fp8_storage_t = uint8_t;
 using ep_fp8x2_storage_t = uint16_t;
-#if defined(__CUDACC__) || defined(__MCC__)
+#if defined(__CUDACC__) || defined(__MCC__) || defined(__MUSACC__)
 __device__ __forceinline__ ep_fp8x2_storage_t ep_cvt_float2_to_fp8x2(float2) {
     return 0;
 }
@@ -74,7 +70,7 @@ __device__ __forceinline__ ep_fp8x2_storage_t ep_cvt_float2_to_fp8x2(float2) {
 #define __activemask() (0xffffffff)
 #endif
 
-#if defined(__CUDACC__) || defined(__MCC__)
+#if defined(__CUDACC__) || defined(__MCC__) || defined(__MUSACC__)
 __forceinline__ __device__ int get_lane_id() { return threadIdx.x % 32; }
 #endif
 
@@ -86,15 +82,11 @@ __forceinline__ __device__ int get_lane_id() { return threadIdx.x % 32; }
     dim3 _block(num_threads);                             \
     cudaStream_t _stream = stream
 
-#define LAUNCH_KERNEL(config, kernel, ...)                     \
-    kernel<<<_grid, _block, 0, _stream>>>(__VA_ARGS__);        \
-    {                                                          \
-        auto _err = cudaGetLastError();                        \
-        if (_err != cudaSuccess) {                             \
-            fprintf(stderr, "[EP] kernel launch failed: %s\n", \
-                    cudaGetErrorString(_err));                 \
-        }                                                      \
-    }
+#define LAUNCH_KERNEL(config, kernel, ...)                  \
+    do {                                                    \
+        kernel<<<_grid, _block, 0, _stream>>>(__VA_ARGS__); \
+        CUDA_CHECK(cudaGetLastError());                     \
+    } while (false)
 
 #else  // !MOONCAKE_EP_USE_MUSA && !MOONCAKE_EP_USE_MACA
 
diff --git a/mooncake-ep/include/mooncake_ep_event.h b/mooncake-ep/include/mooncake_ep_event.h
index 4809704983..c0e8a055e4 100644
--- a/mooncake-ep/include/mooncake_ep_event.h
+++ b/mooncake-ep/include/mooncake_ep_event.h
@@ -1,49 +1,62 @@
 #pragma once
 
-#include <ATen/cuda/CUDAContext.h>
+#include <cuda_alike.h>
 #include <memory>
 #include <mooncake_ep_exception.cuh>
-#include <torch/torch.h>
 
 namespace mooncake {
 
 struct EventHandle {
-    std::shared_ptr<torch::Event> event;
+    std::shared_ptr<cudaEvent_t> event;
+    std::shared_ptr<void> keepalive;
 
     EventHandle() {
-        event = std::make_shared<torch::Event>(torch::kCUDA);
-        event->record(at::cuda::getCurrentCUDAStream());
+        event = std::shared_ptr<cudaEvent_t>(new cudaEvent_t(nullptr),
+                                             [](cudaEvent_t* p) {
+                                                 if (p != nullptr) {
+                                                     if (*p != nullptr)
+                                                         cudaEventDestroy(*p);
+                                                     delete p;
+                                                 }
+                                             });
+        CUDA_CHECK(
+            cudaEventCreateWithFlags(event.get(), cudaEventDisableTiming));
     }
 
-    explicit EventHandle(const at::cuda::CUDAStream& stream) {
-        event = std::make_shared<torch::Event>(torch::kCUDA);
-        event->record(stream);
+    explicit EventHandle(uint64_t stream_ptr,
+                         std::shared_ptr<void> keepalive = nullptr)
+        : EventHandle() {
+        this->keepalive = std::move(keepalive);
+        auto stream = reinterpret_cast<cudaStream_t>(stream_ptr);
+        CUDA_CHECK(cudaEventRecord(*event, stream));
     }
 
     EventHandle(const EventHandle& other) = default;
 
-    void current_stream_wait() const {
-        at::cuda::getCurrentCUDAStream().unwrap().wait(*event);
+    void current_stream_wait(uint64_t stream_ptr) const {
+        auto stream = reinterpret_cast<cudaStream_t>(stream_ptr);
+        CUDA_CHECK(cudaStreamWaitEvent(stream, *event, 0));
     }
 
-    void synchronize() const { event->synchronize(); }
+    void synchronize() const { CUDA_CHECK(cudaEventSynchronize(*event)); }
 };
 
-inline torch::Event create_event(const at::cuda::CUDAStream& s) {
-    auto event = torch::Event(torch::kCUDA);
-    event.record(s);
+inline cudaEvent_t create_event(cudaStream_t stream) {
+    cudaEvent_t event = nullptr;
+    CUDA_CHECK(cudaEventCreateWithFlags(&event, cudaEventDisableTiming));
+    CUDA_CHECK(cudaEventRecord(event, stream));
     return event;
 }
 
-inline void stream_wait(const at::cuda::CUDAStream& s_0,
-                        const at::cuda::CUDAStream& s_1) {
-    EP_HOST_ASSERT(s_0.id() != s_1.id());
-    s_0.unwrap().wait(create_event(s_1));
+inline void stream_wait(cudaStream_t dst_stream, cudaStream_t src_stream) {
+    EP_HOST_ASSERT(dst_stream != src_stream);
+    auto event = create_event(src_stream);
+    CUDA_CHECK(cudaStreamWaitEvent(dst_stream, event, 0));
+    CUDA_CHECK(cudaEventDestroy(event));
 }
 
-inline void stream_wait(const at::cuda::CUDAStream& s,
-                        const EventHandle& event) {
-    s.unwrap().wait(*event.event);
+inline void stream_wait(cudaStream_t s, const EventHandle& event) {
+    CUDA_CHECK(cudaStreamWaitEvent(s, *event.event, 0));
 }
 
 }  // namespace mooncake
diff --git a/mooncake-ep/include/mooncake_ep_launch.cuh b/mooncake-ep/include/mooncake_ep_launch.cuh
index c146c6d72b..7afbd5ec34 100644
--- a/mooncake-ep/include/mooncake_ep_launch.cuh
+++ b/mooncake-ep/include/mooncake_ep_launch.cuh
@@ -71,6 +71,8 @@
             case_macro(2560);                              \
         case 3072:                                         \
             case_macro(3072); /* for gpt-oss */            \
+        case 3584:                                         \
+            case_macro(3584); /* for kimi k3 */            \
         case 4096:                                         \
             case_macro(4096);                              \
         case 5120:                                         \
diff --git a/mooncake-ep/setup.py b/mooncake-ep/setup.py
deleted file mode 100644
index 2a4f388e1c..0000000000
--- a/mooncake-ep/setup.py
+++ /dev/null
@@ -1,138 +0,0 @@
-import os
-import re
-
-from setuptools import setup
-import torch
-
-use_musa = os.getenv("MOONCAKE_EP_USE_MUSA", "").upper() in {"1", "ON", "TRUE", "YES"}
-use_maca = (
-    os.getenv("MOONCAKE_EP_USE_MACA", "").upper() in {"1", "ON", "TRUE", "YES"}
-    or (hasattr(torch.version, "maca") and torch.version.maca is not None)
-)
-if use_musa:
-    try:
-        import importlib
-
-        importlib.import_module("torchada")
-    except ImportError as e:
-        raise ImportError(
-            "torchada is required to build the MUSA EP extension. "
-            "Please install it first using 'pip install torchada'."
-        ) from e
-
-
-from torch.utils.cpp_extension import (  # noqa: E402
-    BuildExtension,
-    CUDAExtension,
-    CUDA_HOME,
-)
-
-
-torch_version = re.match(r"\d+(?:\.\d+)*", torch.__version__).group()
-version_suffix = "_" + torch_version.replace(".", "_")
-module_name = "mooncake.ep" + version_suffix
-
-abi_flag = int(torch._C._GLIBCXX_USE_CXX11_ABI)
-current_dir = os.path.abspath(os.path.dirname(__file__))
-repo_dir = os.path.abspath(os.path.join(current_dir, os.pardir))
-sysroot_dir = os.path.join(repo_dir, ".deps", "sysroot", "usr")
-
-
-def existing_dirs(*paths):
-    return [path for path in paths if os.path.isdir(path)]
-
-
-sysroot_include_dirs = existing_dirs(
-    os.path.join(sysroot_dir, "include"),
-    os.path.join(sysroot_dir, "include", "jsoncpp"),
-    os.path.join(sysroot_dir, "include", "libnl3"),
-)
-sysroot_library_dirs = existing_dirs(
-    os.path.join(sysroot_dir, "lib", "x86_64-linux-gnu"),
-    os.path.join(sysroot_dir, "lib"),
-)
-
-abi_define = f"-D_GLIBCXX_USE_CXX11_ABI={abi_flag}"
-cxx_args = [abi_define, "-std=c++20", "-O3", "-g0"]
-
-cuda_libraries = ["ibverbs", "mlx5"]
-cuda_library_dirs = []
-include_dirs = [
-    os.path.join(current_dir, "include"),
-    os.path.join(current_dir, "../mooncake-transfer-engine/include"),
-]
-
-if use_musa:
-    cuda_libraries = []
-    musa_defines = [
-        "-DUSE_MUSA",
-        "-DMOONCAKE_EP_USE_MUSA=1",
-    ]
-    cxx_args += musa_defines
-    # torchada maps the "nvcc" key to "mcc".
-    device_args = [
-        abi_define,
-        *musa_defines,
-        "-std=c++20",
-        "--cuda-gpu-arch=mp_21",
-        "--cuda-gpu-arch=mp_31",
-        "-O3",
-    ]
-elif use_maca:
-    cuda_libraries = []
-    cuda_library_dirs = sysroot_library_dirs.copy()
-    include_dirs += sysroot_include_dirs
-    maca_defines = ["-DUSE_MACA", "-DMOONCAKE_EP_USE_MACA=1"]
-    cxx_args += maca_defines
-    device_args = [
-        abi_define,
-        *maca_defines,
-        "-std=c++20",
-        "-O3",
-    ]
-else:
-    cxx_args.append("-DUSE_CUDA")
-    device_args = [
-        abi_define,
-        "-std=c++20",
-        "-DUSE_CUDA",
-        "-Xcompiler",
-        "-O3",
-        "-Xcompiler",
-        "-g0",
-    ]
-    # Link against the CUDA driver stub library if available.
-    if CUDA_HOME is not None:
-        cuda_stub_dir = os.path.join(CUDA_HOME, "lib64", "stubs")
-        cuda_stub_lib = os.path.join(cuda_stub_dir, "libcuda.so")
-        if os.path.exists(cuda_stub_lib):
-            cuda_libraries.insert(0, "cuda")
-            cuda_library_dirs.append(cuda_stub_dir)
-
-setup(
-    name=module_name,
-    ext_modules=[
-        CUDAExtension(
-            name=module_name,
-            include_dirs=include_dirs,
-            sources=[
-                "src/ep_py.cpp",
-                "src/mooncake_ep_buffer.cpp",
-                "src/mooncake_ep_elastic_buffer.cpp",
-                "src/mooncake_ep_kernel.cu",
-                "src/mooncake_ep_elastic_kernel.cu",
-            ],
-            extra_compile_args={"cxx": cxx_args, "nvcc": device_args},
-            libraries=cuda_libraries,
-            library_dirs=cuda_library_dirs,
-            extra_link_args=[
-                "-Wl,-rpath,$ORIGIN",
-                "-L" + os.path.join(current_dir, "../mooncake-wheel/mooncake"),
-                "-Wl,--push-state,--no-as-needed",
-                "-l:engine.so",
-                "-Wl,--pop-state",
-            ],
-        )
-    ],
-    cmdclass={"build_ext": BuildExtension},
-)
diff --git a/mooncake-ep/src/CMakeLists.txt b/mooncake-ep/src/CMakeLists.txt
index a102f5011e..dee0b61dd1 100644
--- a/mooncake-ep/src/CMakeLists.txt
+++ b/mooncake-ep/src/CMakeLists.txt
@@ -1,4 +1,127 @@
-add_library(mooncake_ep ep_py.cpp mooncake_ep_buffer.cpp mooncake_ep_elastic_buffer.cpp mooncake_ep_kernel.cu mooncake_ep_elastic_kernel.cu)
+set(MOONCAKE_EP_HOST_SOURCES
+    ep_py.cpp
+    ../benchmarks/legacy_buffer_perf.cpp
+    mooncake_ep_buffer.cpp
+    mooncake_ep_elastic_buffer.cpp)
 
-set_target_properties(mooncake_ep PROPERTIES POSITION_INDEPENDENT_CODE ON)
-target_link_libraries(mooncake_ep PUBLIC ${TORCH_LIBRARIES} transfer_engine ibverbs mlx5)
+set(MOONCAKE_EP_DEVICE_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/mooncake_ep_kernel.cu"
+    "${CMAKE_CURRENT_SOURCE_DIR}/mooncake_ep_elastic_kernel.cu")
+
+if(USE_CUDA)
+  enable_language(CUDA)
+  find_package(CUDAToolkit REQUIRED)
+
+  # Keep CUDA fatbins in a separate library.  The Python host extension can
+  # then pass through auditwheel while this library is injected afterwards.
+  add_library(mooncake_ep_device SHARED ${MOONCAKE_EP_DEVICE_SOURCES})
+  set_target_properties(mooncake_ep_device PROPERTIES
+                        POSITION_INDEPENDENT_CODE ON)
+  if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL "13.0")
+    set_target_properties(mooncake_ep_device PROPERTIES
+                          CUDA_ARCHITECTURES "80;90;103")
+  else()
+    set_target_properties(mooncake_ep_device PROPERTIES
+                          CUDA_ARCHITECTURES "80;90")
+  endif()
+  target_include_directories(
+    mooncake_ep_device PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../include
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include)
+  target_compile_options(
+    mooncake_ep_device PRIVATE
+    $<$<COMPILE_LANGUAGE:CUDA>:-Xcompiler=-O3>
+    $<$<COMPILE_LANGUAGE:CUDA>:-Xcompiler=-g0>
+    $<$<COMPILE_LANGUAGE:CUDA>:--expt-relaxed-constexpr>)
+  target_link_libraries(mooncake_ep_device PRIVATE CUDA::cudart)
+  if(USE_NCCL_DEVICE)
+    target_link_libraries(mooncake_ep_device PRIVATE NCCL::nccl)
+  endif()
+elseif(USE_MUSA)
+  set(MOONCAKE_EP_SOURCES ${MOONCAKE_EP_HOST_SOURCES})
+  if(DEFINED ENV{MUSA_HOME} AND NOT "$ENV{MUSA_HOME}" STREQUAL "")
+    set(_ep_musa_compiler_hint "$ENV{MUSA_HOME}/bin")
+  else()
+    set(_ep_musa_compiler_hint /usr/local/musa/bin)
+  endif()
+  find_program(_ep_musa_compiler NAMES mcc HINTS "${_ep_musa_compiler_hint}")
+  if(NOT _ep_musa_compiler)
+    message(FATAL_ERROR "USE_MUSA=ON requires the MUSA compiler (mcc)")
+  endif()
+  set(_ep_musa_depfile_supported FALSE)
+  if(CMAKE_GENERATOR MATCHES "^Ninja" OR
+     (CMAKE_GENERATOR MATCHES "Makefiles" AND
+      CMAKE_VERSION VERSION_GREATER_EQUAL 3.20))
+    set(_ep_musa_depfile_supported TRUE)
+  endif()
+
+  foreach(_ep_device_source IN LISTS MOONCAKE_EP_DEVICE_SOURCES)
+    get_filename_component(_ep_device_name "${_ep_device_source}" NAME_WE)
+    set(_ep_device_object
+        "${CMAKE_CURRENT_BINARY_DIR}/${_ep_device_name}_musa.o")
+    set(_ep_device_depfile
+        "${CMAKE_CURRENT_BINARY_DIR}/${_ep_device_name}_musa.d")
+    set(_ep_musa_depfile_argument)
+    if(_ep_musa_depfile_supported)
+      set(_ep_musa_depfile_argument DEPFILE "${_ep_device_depfile}")
+    endif()
+    add_custom_command(
+      OUTPUT "${_ep_device_object}"
+      COMMAND "${_ep_musa_compiler}"
+              -x musa
+              -std=c++20
+              -O3
+              -fPIC
+              -DUSE_MUSA
+              -DMOONCAKE_EP_USE_MUSA=1
+              -MMD
+              -MT "${_ep_device_object}"
+              -MF "${_ep_device_depfile}"
+              --cuda-gpu-arch=mp_21
+              --cuda-gpu-arch=mp_31
+              "-I${CMAKE_CURRENT_SOURCE_DIR}/../include"
+              "-I${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include"
+              -c "${_ep_device_source}" -o "${_ep_device_object}"
+      DEPENDS "${_ep_device_source}"
+      ${_ep_musa_depfile_argument}
+      COMMENT "Compiling Mooncake EP MUSA device source ${_ep_device_name}"
+      VERBATIM)
+    set_source_files_properties("${_ep_device_object}"
+                                PROPERTIES GENERATED TRUE EXTERNAL_OBJECT TRUE)
+    list(APPEND MOONCAKE_EP_SOURCES "${_ep_device_object}")
+  endforeach()
+else()
+  set(MOONCAKE_EP_SOURCES ${MOONCAKE_EP_HOST_SOURCES})
+endif()
+
+if(USE_CUDA)
+  pybind11_add_module(_ep MODULE ${MOONCAKE_EP_HOST_SOURCES})
+else()
+  pybind11_add_module(_ep MODULE ${MOONCAKE_EP_SOURCES})
+endif()
+set_target_properties(_ep PROPERTIES POSITION_INDEPENDENT_CODE ON)
+set_target_properties(_ep PROPERTIES INSTALL_RPATH "$ORIGIN")
+if(USE_MUSA)
+  target_compile_definitions(_ep PRIVATE MOONCAKE_EP_USE_MUSA=1)
+endif()
+if(USE_MACA)
+  target_compile_definitions(_ep PRIVATE MOONCAKE_EP_USE_MACA=1)
+endif()
+
+target_include_directories(_ep PRIVATE ${Python3_INCLUDE_DIRS})
+if(USE_CUDA)
+  target_link_libraries(_ep PRIVATE transfer_engine ibverbs mlx5 glog::glog
+                                    gflags::gflags mooncake_ep_device
+                                    CUDA::cudart)
+else()
+  target_link_libraries(_ep PRIVATE transfer_engine ibverbs mlx5 glog::glog
+                                    gflags::gflags)
+endif()
+
+if(USE_CUDA)
+  # The host binding contains no CUDA fatbin; only the device library above
+  # is kept out of auditwheel and injected into the wheel afterwards.
+elseif(USE_MUSA)
+  set_target_properties(_ep PROPERTIES LINKER_LANGUAGE CXX)
+  target_link_libraries(_ep PRIVATE musa musart rt)
+endif()
diff --git a/mooncake-ep/src/ep_py.cpp b/mooncake-ep/src/ep_py.cpp
index 02307c0caf..54951b1a07 100644
--- a/mooncake-ep/src/ep_py.cpp
+++ b/mooncake-ep/src/ep_py.cpp
@@ -4,72 +4,41 @@
 #include <pybind11/stl.h>
 #include <pybind11/chrono.h>
 #include <pybind11/functional.h>
-#include <torch/csrc/utils/pybind.h>
-#include <torch/python.h>
-#include <torch/torch.h>
 
 namespace py = pybind11;
 
 namespace mooncake {
 
-PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
+void bind_legacy_buffer_perf(py::module_& module);
+
+PYBIND11_MODULE(_ep, m) {
     m.def("get_ep_buffer_size_hint", &get_ep_buffer_size_hint);
     m.def("calculate_elastic_buffer_size",
           &MooncakeElasticBuffer::calculate_buffer_size);
+    m.def("create_nccl_unique_id", &create_elastic_nccl_unique_id);
+    m.def("has_nccl_device_support", []() {
+#ifdef USE_NCCL_DEVICE
+        return true;
+#else
+        return false;
+#endif
+    });
 
     py::class_<EventHandle>(m, "EventHandle")
-        .def(py::init<>())
-        .def("current_stream_wait", &EventHandle::current_stream_wait)
+        .def(py::init<uint64_t>(), py::arg("stream_ptr") = 0)
+        .def("current_stream_wait", &EventHandle::current_stream_wait,
+             py::arg("stream_ptr"))
         .def("synchronize", &EventHandle::synchronize);
 
-    py::class_<ElasticNativeHandle>(m, "ElasticNativeHandle")
-        .def(py::init<>())
-        .def_readwrite("do_expand", &ElasticNativeHandle::do_expand)
-        .def_readwrite("num_experts", &ElasticNativeHandle::num_experts)
-        .def_readwrite("expert_alignment",
-                       &ElasticNativeHandle::expert_alignment)
-        .def_readwrite("num_max_tokens_per_rank",
-                       &ElasticNativeHandle::num_max_tokens_per_rank)
-        .def_readwrite("num_sms", &ElasticNativeHandle::num_sms)
-        .def_readwrite("topk_idx", &ElasticNativeHandle::topk_idx)
-        .def_readwrite(
-            "psum_num_recv_tokens_per_scaleup_rank",
-            &ElasticNativeHandle::psum_num_recv_tokens_per_scaleup_rank)
-        .def_readwrite("psum_num_recv_tokens_per_expert",
-                       &ElasticNativeHandle::psum_num_recv_tokens_per_expert)
-        .def_readwrite("recv_src_metadata",
-                       &ElasticNativeHandle::recv_src_metadata)
-        .def_readwrite("recv_layout_range",
-                       &ElasticNativeHandle::recv_layout_range)
-        .def_readwrite("dst_buffer_slot_idx",
-                       &ElasticNativeHandle::dst_buffer_slot_idx)
-        .def_readwrite("token_metadata_at_forward",
-                       &ElasticNativeHandle::token_metadata_at_forward)
-        .def_readwrite("channel_linked_list",
-                       &ElasticNativeHandle::channel_linked_list)
-        .def_readwrite("num_recv_tokens_per_expert_list",
-                       &ElasticNativeHandle::num_recv_tokens_per_expert_list);
-
-    py::class_<ElasticDispatchOutput>(m, "ElasticDispatchOutput")
-        .def_readonly("recv_x", &ElasticDispatchOutput::recv_x)
-        .def_readonly("recv_x_scales", &ElasticDispatchOutput::recv_x_scales)
-        .def_readonly("recv_topk_idx", &ElasticDispatchOutput::recv_topk_idx)
-        .def_readonly("recv_topk_weights",
-                      &ElasticDispatchOutput::recv_topk_weights)
-        .def_readonly("handle", &ElasticDispatchOutput::handle)
-        .def_readonly("event", &ElasticDispatchOutput::event);
-
-    py::class_<ElasticCombineOutput>(m, "ElasticCombineOutput")
-        .def_readonly("combined_x", &ElasticCombineOutput::combined_x)
-        .def_readonly("combined_topk_weights",
-                      &ElasticCombineOutput::combined_topk_weights)
-        .def_readonly("event", &ElasticCombineOutput::event);
-
     m.attr("MAX_QP_COUNT") = pybind11::int_(MAX_QP_COUNT);
+    bind_legacy_buffer_perf(m);
 
     py::class_<MooncakeEpBuffer>(m, "Buffer")
-        .def(py::init<int, int, int64_t>())
+        .def(py::init<int, int, int64_t, bool>(), py::arg("rank"),
+             py::arg("num_ranks"), py::arg("num_ep_buffer_bytes"),
+             py::arg("disable_p2p") = false)
         .def("ibgda_disabled", &MooncakeEpBuffer::ibgda_disabled)
+        .def("p2p_enabled", &MooncakeEpBuffer::p2p_enabled)
         .def("use_fast_path", &MooncakeEpBuffer::use_fast_path)
         .def("update_local_qpns", &MooncakeEpBuffer::update_local_qpns)
         .def("is_roce", &MooncakeEpBuffer::is_roce)
@@ -82,13 +51,12 @@ PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
         .def("sync_nvlink_ipc_handles",
              &MooncakeEpBuffer::sync_nvlink_ipc_handles)
         .def("dispatch", &MooncakeEpBuffer::dispatch)
-        .def("combine", &MooncakeEpBuffer::combine)
-        .def("get_next_combine_buffer",
-             &MooncakeEpBuffer::get_next_combine_buffer);
+        .def("combine", &MooncakeEpBuffer::combine);
 
     py::class_<MooncakeElasticBuffer>(m, "ElasticBuffer")
         .def(py::init<int, int, int64_t, int64_t, int64_t, int64_t, bool, bool,
-                      bool, bool, bool, int, int, int, int>(),
+                      bool, bool, bool, int, int, int, int, std::string,
+                      std::vector<int32_t>>(),
              py::arg("rank"), py::arg("num_ranks"), py::arg("num_buffer_bytes"),
              py::arg("num_max_tokens_per_rank"), py::arg("hidden"),
              py::arg("num_topk"), py::arg("use_fp8_dispatch"),
@@ -96,7 +64,10 @@ PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
              py::arg("allow_multiple_reduction"),
              py::arg("prefer_overlap_with_compute"), py::arg("sl_idx"),
              py::arg("num_allocated_qps"), py::arg("num_cpu_timeout_secs"),
-             py::arg("num_gpu_timeout_secs"))
+             py::arg("num_gpu_timeout_secs"), py::arg("transport") = "ibgda",
+             py::arg("nccl_unique_id") = std::vector<int32_t>{})
+        .def("destroy", &MooncakeElasticBuffer::destroy)
+        .def("using_nccl", &MooncakeElasticBuffer::using_nccl)
         .def_static("calculate_buffer_size",
                     &MooncakeElasticBuffer::calculate_buffer_size)
         .def("get_physical_domain_size",
@@ -107,6 +78,7 @@ PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
              &MooncakeElasticBuffer::get_theoretical_num_sms)
         .def("ibgda_disabled", &MooncakeElasticBuffer::ibgda_disabled)
         .def("use_fast_path", &MooncakeElasticBuffer::use_fast_path)
+        .def("reconfigure_nccl", &MooncakeElasticBuffer::reconfigure_nccl)
         .def("update_local_qpns", &MooncakeElasticBuffer::update_local_qpns)
         .def("is_roce", &MooncakeElasticBuffer::is_roce)
         .def("sync_ibgda_peers", &MooncakeElasticBuffer::sync_ibgda_peers)
@@ -117,18 +89,8 @@ PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) {
         .def("get_ipc_handle", &MooncakeElasticBuffer::get_ipc_handle)
         .def("sync_nvlink_ipc_handles",
              &MooncakeElasticBuffer::sync_nvlink_ipc_handles)
-        .def("dispatch", &MooncakeElasticBuffer::dispatch, py::arg("x"),
-             py::arg("sf"), py::arg("topk_idx"), py::arg("topk_weights"),
-             py::arg("active_ranks"), py::arg("num_experts"),
-             py::arg("num_max_tokens_per_rank"), py::arg("expert_alignment"),
-             py::arg("num_sms"), py::arg("do_expand"), py::arg("do_cpu_sync"),
-             py::arg("async_with_compute_stream"),
-             py::arg("cached_handle") = std::nullopt)
-        .def("combine", &MooncakeElasticBuffer::combine, py::arg("x"),
-             py::arg("handle"), py::arg("topk_weights"),
-             py::arg("active_ranks"), py::arg("num_sms"),
-             py::arg("async_with_compute_stream"),
-             py::arg("out") = std::nullopt);
+        .def("dispatch", &MooncakeElasticBuffer::dispatch)
+        .def("combine", &MooncakeElasticBuffer::combine);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-ep/src/mooncake_ep_buffer.cpp b/mooncake-ep/src/mooncake_ep_buffer.cpp
index b587e29103..56dda8132a 100644
--- a/mooncake-ep/src/mooncake_ep_buffer.cpp
+++ b/mooncake-ep/src/mooncake_ep_buffer.cpp
@@ -9,9 +9,60 @@ namespace mooncake {
 
 namespace {
 
-int active_qps_per_rank_for_ep(int qps_per_rank, bool is_roce, int cap) {
+int active_qps_per_rank_for_ep(int qps_per_rank, bool is_roce, int cap,
+                               int num_local_experts) {
     if (!is_roce) return qps_per_rank;
-    return std::min(qps_per_rank, cap);
+    // CUDA RoCE shares HCAs across local GPUs; spreading small EP messages
+    // over all expert QPs adds doorbell/progress overhead. MUSA keeps the
+    // existing expert-scaled policy until its high-QP path is fully tuned.
+    int target = cap;
+    if (target <= 0) {
+#ifdef MOONCAKE_EP_USE_MUSA
+        target = std::max(8, num_local_experts);
+#else
+        target = 8;
+#endif
+    }
+    return std::min(qps_per_rank, target);
+}
+
+cudaStream_t create_comm_stream() {
+    int least_priority = 0;
+    int greatest_priority = 0;
+    auto status =
+        cudaDeviceGetStreamPriorityRange(&least_priority, &greatest_priority);
+    if (status != cudaSuccess) {
+        cudaGetLastError();
+        least_priority = 0;
+        greatest_priority = 0;
+    }
+
+    cudaStream_t stream = nullptr;
+    CUDA_CHECK(cudaStreamCreateWithPriority(&stream, cudaStreamNonBlocking,
+                                            greatest_priority));
+    return stream;
+}
+
+bool stream_is_capturing(cudaStream_t stream) {
+    cudaStreamCaptureStatus status = cudaStreamCaptureStatusNone;
+    auto error = cudaStreamIsCapturing(stream, &status);
+    if (error != cudaSuccess) {
+        cudaGetLastError();
+        return false;
+    }
+    return status != cudaStreamCaptureStatusNone;
+}
+
+constexpr int kTopkShadowMaxTokens = 1024;
+constexpr int kTopkShadowMaxTopk = 32;
+constexpr int kTopkShadowSlots = 8;
+constexpr size_t kTopkShadowBytes = static_cast<size_t>(kTopkShadowMaxTokens) *
+                                    kTopkShadowMaxTopk * sizeof(int64_t);
+
+int64_t* topk_shadow(void* workspace, int shadow_slot, int num_experts) {
+    auto* base = reinterpret_cast<uint8_t*>(workspace) +
+                 2 * static_cast<size_t>(num_experts) * sizeof(int);
+    return reinterpret_cast<int64_t*>(base + shadow_slot * kTopkShadowBytes);
 }
 
 }  // namespace
@@ -44,16 +95,17 @@ static bool macaHostPhaseFenceCoversPeers() {
 
 MooncakeEpBuffer::MooncakeEpBuffer(int rank, int num_ranks,
                                    int64_t num_ep_buffer_bytes,
-                                   TransferEngine* engine)
+                                   bool disable_p2p, TransferEngine* engine)
     : rank(rank),
       num_ranks(num_ranks),
       num_ep_buffer_bytes(num_ep_buffer_bytes),
-      comm_stream(at::cuda::getStreamFromPool(true)) {
+      p2p_enabled_(!disable_p2p),
+      comm_stream(create_comm_stream()) {
     USE_QP_COUNT = MAX_QP_COUNT / num_ranks * num_ranks;
 
-    // Optional runtime override for the RoCE active-QP cap (default 8).
-    // Set MOONCAKE_EP_ACTIVE_QPS_PER_RANK to a value >= the per-rank QP count
-    // (e.g. 256) to effectively disable the cap.
+    // Optional runtime override for the RoCE active-QP count. Without an
+    // override, CUDA uses eight QPs and MUSA scales up to local experts.
+    active_qps_cap_ = 0;
     if (const char* env = std::getenv("MOONCAKE_EP_ACTIVE_QPS_PER_RANK")) {
         char* end = nullptr;
         long v = std::strtol(env, &end, 10);
@@ -65,14 +117,17 @@ MooncakeEpBuffer::MooncakeEpBuffer(int rank, int num_ranks,
                          << env << "'";
         }
     }
-    LOG(INFO) << "[EP] RoCE active QPs/rank cap = " << active_qps_cap_;
+    LOG(INFO) << "[EP] RoCE active QPs/rank override = "
+              << (active_qps_cap_ > 0 ? std::to_string(active_qps_cap_)
+                                      : "auto");
 
     // Get ranks
     CUDA_CHECK(cudaGetDevice(&device_id));
     CUDA_CHECK(cudaDeviceGetAttribute(&clock_rate_khz, cudaDevAttrClockRate,
                                       device_id));
 
-    // P2P transport — owns GDR buffer allocation and IPC handle exchange.
+    // P2P transport owns GDR buffer allocation. Peer mappings remain disabled
+    // when the EP caller selects RDMA-only operation.
     if (engine) {
         p2p_transport_ = engine->getOrCreateP2pTransport(num_ranks);
     } else {
@@ -92,7 +147,7 @@ MooncakeEpBuffer::MooncakeEpBuffer(int rank, int num_ranks,
         if (rdma_transport_) {
             if (!initRdmaTransport(rdma_transport_, gdr_buffer,
                                    num_ep_buffer_bytes, num_ranks, USE_QP_COUNT,
-                                   comm_stream.stream())) {
+                                   comm_stream)) {
                 rdma_transport_ = nullptr;
                 ibgda_disabled_ = true;
                 LOG(INFO) << "[EP] IBGDA unavailable, using P2P-only path";
@@ -114,7 +169,7 @@ MooncakeEpBuffer::MooncakeEpBuffer(int rank, int num_ranks,
         }
         auto t = device::createIbgdaDeviceTransport(device_filter);
         if (initRdmaTransport(t.get(), gdr_buffer, num_ep_buffer_bytes,
-                              num_ranks, USE_QP_COUNT, comm_stream.stream())) {
+                              num_ranks, USE_QP_COUNT, comm_stream)) {
             owned_rdma_transport_ = std::move(t);
             rdma_transport_ = owned_rdma_transport_.get();
         } else {
@@ -151,35 +206,34 @@ MooncakeEpBuffer::~MooncakeEpBuffer() noexcept(false) {
     p2p_transport_ = nullptr;
 
     if (workspace) cudaFree(workspace);
+    if (comm_stream) {
+        cudaStreamDestroy(comm_stream);
+        comm_stream = nullptr;
+    }
 }
 
-std::tuple<torch::Tensor, std::optional<torch::Tensor>, torch::Tensor,
-           torch::Tensor, torch::Tensor, std::optional<EventHandle>,
-           std::optional<std::function<void()>>>
-MooncakeEpBuffer::dispatch(const torch::Tensor& x,
-                           const torch::Tensor& topk_idx,
-                           torch::Tensor& active_ranks,
-                           int num_max_dispatch_tokens_per_rank,
-                           int num_experts, int timeout_us, bool use_fp8,
-                           bool async, bool return_recv_hook) {
-    // Tensor checks
-    // By default using `ptp128c` FP8 cast
-    EP_HOST_ASSERT(x.dim() == 2 and x.is_contiguous() and
-                   x.scalar_type() == torch::kBFloat16);
-    EP_HOST_ASSERT(x.size(1) % sizeof(int4) == 0 and x.size(1) % 128 == 0);
-    EP_HOST_ASSERT(topk_idx.dim() == 2 and topk_idx.is_contiguous());
-    EP_HOST_ASSERT(x.size(0) == topk_idx.size(0) and
-                   x.size(0) <= num_max_dispatch_tokens_per_rank);
-    EP_HOST_ASSERT(topk_idx.scalar_type() == torch::kInt64);
+std::tuple<std::optional<EventHandle>, std::optional<std::function<void()>>>
+MooncakeEpBuffer::dispatch(
+    uint64_t x_ptr, uint64_t topk_idx_ptr, uint64_t active_ranks_ptr,
+    int num_tokens, int hidden, int num_topk,
+    int num_max_dispatch_tokens_per_rank, int num_experts, int timeout_us,
+    bool use_fp8, uint64_t packed_recv_x_ptr, uint64_t packed_recv_x_scales_ptr,
+    uint64_t packed_recv_count_ptr, uint64_t packed_recv_src_info_ptr,
+    uint64_t packed_recv_layout_range_ptr, bool async, bool return_recv_hook,
+    uint64_t compute_stream_ptr) {
     EP_HOST_ASSERT(num_experts % num_ranks == 0);
     EP_HOST_ASSERT(USE_QP_COUNT % num_ranks == 0);
+    EP_HOST_ASSERT(hidden % static_cast<int>(sizeof(int4)) == 0 &&
+                   hidden % 128 == 0);
+    EP_HOST_ASSERT(num_tokens <= num_max_dispatch_tokens_per_rank);
 
-    auto num_tokens = static_cast<int>(x.size(0)),
-         hidden = static_cast<int>(x.size(1));
-    auto num_scales = hidden / 128,
-         num_topk = static_cast<int>(topk_idx.size(1));
+    auto num_scales = hidden / 128;
     int num_local_experts = num_experts / num_ranks;
 
+    auto compute_stream_raw =
+        reinterpret_cast<cudaStream_t>(compute_stream_ptr);
+    const bool graph_capture = stream_is_capturing(compute_stream_raw);
+
     // Buffer control
     BufferPair layout(gdr_buffer, num_max_dispatch_tokens_per_rank, hidden,
                       num_ranks, num_experts);
@@ -188,42 +242,54 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
     auto buffer = layout.buffers[current_buffer_idx];
     auto next_buffer = layout.buffers[buffer_idx ^= 1];
     int phase_epoch = ++phase_epochs[current_buffer_idx];
+    int shadow_slot;
+    {
+        std::lock_guard<std::mutex> lock(buffer_mutex);
+        auto [it, inserted] = dispatch_shadow_slots.emplace(
+            packed_recv_src_info_ptr, next_shadow_slot);
+        if (inserted)
+            next_shadow_slot = (next_shadow_slot + 1) % kTopkShadowSlots;
+        shadow_slot = it->second;
+    }
 
     // Wait previous tasks to be finished
-    // NOTES: the hook mode will always use the default stream
-    auto compute_stream = at::cuda::getCurrentCUDAStream();
-    auto launch_stream = return_recv_hook ? compute_stream : comm_stream;
+    // NOTES: the hook mode will always use the default stream, whose native
+    // handle is allowed to be nullptr in CUDA/PyTorch.
+    auto launch_stream =
+        (return_recv_hook || graph_capture) ? compute_stream_raw : comm_stream;
     EP_HOST_ASSERT(not(async and return_recv_hook));
-    if (not return_recv_hook) stream_wait(launch_stream, compute_stream);
+    if (not return_recv_hook and not graph_capture)
+        stream_wait(launch_stream, compute_stream_raw);
 
     // Allocate packed tensors
-    auto packed_recv_x = torch::empty(
-        {num_local_experts, num_ranks * num_max_dispatch_tokens_per_rank,
-         hidden},
-        x.options().dtype(use_fp8 ? torch::kFloat8_e4m3fn : torch::kBFloat16));
-    auto packed_recv_src_info = torch::empty(
-        {num_local_experts, num_ranks * num_max_dispatch_tokens_per_rank},
-        torch::dtype(torch::kInt32).device(x.device()));
-    auto packed_recv_layout_range =
-        torch::empty({num_local_experts, num_ranks},
-                     torch::dtype(torch::kInt64).device(x.device()));
-    auto packed_recv_count = torch::zeros(
-        {num_local_experts}, torch::dtype(torch::kInt32).device(x.device()));
-
-    // Allocate column-majored scales
-    auto packed_recv_x_scales = std::optional<torch::Tensor>();
-    float* packed_recv_x_scales_ptr = nullptr;
+    void* x = reinterpret_cast<void*>(x_ptr);
+    auto* topk_idx = reinterpret_cast<int64_t*>(topk_idx_ptr);
+    auto* active_ranks = reinterpret_cast<int32_t*>(active_ranks_ptr);
+    void* packed_recv_x = reinterpret_cast<void*>(packed_recv_x_ptr);
+    auto* packed_recv_x_scales =
+        reinterpret_cast<float*>(packed_recv_x_scales_ptr);
+    auto* packed_recv_count = reinterpret_cast<int*>(packed_recv_count_ptr);
+    auto* packed_recv_src_info =
+        reinterpret_cast<int*>(packed_recv_src_info_ptr);
+    auto* packed_recv_layout_range =
+        reinterpret_cast<int64_t*>(packed_recv_layout_range_ptr);
+    EP_HOST_ASSERT(active_ranks != nullptr);
+    EP_HOST_ASSERT(num_tokens == 0 || (x != nullptr && topk_idx != nullptr));
+    EP_HOST_ASSERT(packed_recv_x != nullptr && packed_recv_count != nullptr);
+    EP_HOST_ASSERT(packed_recv_src_info != nullptr &&
+                   packed_recv_layout_range != nullptr);
     if (use_fp8) {
         EP_HOST_ASSERT((num_ranks * num_max_dispatch_tokens_per_rank) % 4 ==
                            0 and
                        "TMA requires the number of tokens to be multiple of 4");
-        packed_recv_x_scales =
-            torch::empty({num_local_experts, num_scales,
-                          num_ranks * num_max_dispatch_tokens_per_rank},
-                         torch::dtype(torch::kFloat32).device(x.device()));
-        packed_recv_x_scales =
-            torch::transpose(packed_recv_x_scales.value(), 1, 2);
-        packed_recv_x_scales_ptr = packed_recv_x_scales->data_ptr<float>();
+        EP_HOST_ASSERT(packed_recv_x_scales != nullptr);
+    }
+    EP_HOST_ASSERT(num_topk <= kTopkShadowMaxTopk);
+    if (num_tokens > 0) {
+        CUDA_CHECK(cudaMemcpyAsync(
+            topk_shadow(workspace, shadow_slot, num_experts), topk_idx,
+            static_cast<size_t>(num_tokens) * num_topk * sizeof(int64_t),
+            cudaMemcpyDeviceToDevice, launch_stream));
     }
 
     int64_t timeout_ticks =
@@ -238,10 +304,9 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
     void** ipc_ptrs = p2p_transport_->peerPtrsTablePtr();
     int active_qps_per_rank = active_qps_per_rank_for_ep(
         USE_QP_COUNT / num_ranks, rdma_transport_ && rdma_transport_->isRoce(),
-        active_qps_cap_);
-
+        active_qps_cap_, num_experts / num_ranks);
     auto mark_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::mark_phase_ack(gdr_buffer, nvlink_avail, ipc_ptrs,
                                  buffer.rdma_send_signal_buffer, rank,
                                  num_ranks, phase_epoch, launch_stream);
@@ -249,7 +314,7 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
     };
 
     auto wait_peer_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::wait_phase_ack(buffer.rdma_send_signal_buffer, rank,
                                  num_ranks, phase_epoch, launch_stream,
                                  timeout_ticks);
@@ -257,7 +322,7 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
     };
 
     auto mark_and_wait_peer_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::mark_and_wait_phase_ack(
             gdr_buffer, nvlink_avail, ipc_ptrs, buffer.rdma_send_signal_buffer,
             rank, num_ranks, phase_epoch, launch_stream, timeout_ticks);
@@ -266,22 +331,23 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
 
     auto launcher = [=](int phases) {
         mooncake::dispatch(
-            packed_recv_x.data_ptr(), packed_recv_x_scales_ptr,
-            packed_recv_src_info.data_ptr<int>(),
-            packed_recv_layout_range.data_ptr<int64_t>(),
-            packed_recv_count.data_ptr<int>(), active_ranks.data_ptr<int32_t>(),
+            packed_recv_x, packed_recv_x_scales, packed_recv_src_info,
+            packed_recv_layout_range, packed_recv_count, active_ranks,
             gdr_buffer, buffer.rdma_send_signal_buffer,
             buffer.rdma_recv_signal_buffer, buffer.rdma_send_data_buffer,
             buffer.rdma_recv_data_buffer, nullptr, nullptr, raddrs_ptr,
-            rkeys_ptr, qp_devctxs_ptr, nvlink_avail, ipc_ptrs, x.data_ptr(),
-            topk_idx.data_ptr<int64_t>(), next_buffer.rdma_recv_signal_buffer,
-            num_tokens, hidden, num_max_dispatch_tokens_per_rank, num_topk,
-            num_experts, rank, num_ranks, use_fp8, workspace, launch_stream,
-            timeout_ticks, phases, active_qps_per_rank);
+            rkeys_ptr, qp_devctxs_ptr, nvlink_avail, ipc_ptrs, x, topk_idx,
+            next_buffer.rdma_recv_signal_buffer, num_tokens, hidden,
+            num_max_dispatch_tokens_per_rank, num_topk, num_experts, rank,
+            num_ranks, use_fp8, workspace, launch_stream, timeout_ticks, phases,
+            active_qps_per_rank);
     };
-    if (return_recv_hook) {
+    if (return_recv_hook &&
+        (!graph_capture || !macaHostPhaseFenceCoversPeers())) {
         launcher(LOW_LATENCY_SEND_PHASE);
         mark_send_done();
+    } else if (graph_capture) {
+        launcher(LOW_LATENCY_SEND_PHASE | LOW_LATENCY_RECV_PHASE);
     } else {
 #ifdef MOONCAKE_EP_SPLIT_SEND_RECV
         launcher(LOW_LATENCY_SEND_PHASE);
@@ -298,94 +364,84 @@ MooncakeEpBuffer::dispatch(const torch::Tensor& x,
         // NOTES: we must ensure the all tensors will not be deallocated
         // before the stream-wait happens, so in Python API, we must wrap
         // all tensors into the event handle.
-        event = EventHandle(launch_stream);
+        event = EventHandle(reinterpret_cast<uint64_t>(launch_stream));
     } else if (return_recv_hook && macaHostPhaseFenceCoversPeers()) {
-        event = EventHandle(launch_stream);
-    } else if (not return_recv_hook) {
-        stream_wait(compute_stream, launch_stream);
+        event = EventHandle(reinterpret_cast<uint64_t>(launch_stream));
+    } else if (not return_recv_hook and not graph_capture) {
+        stream_wait(compute_stream_raw, launch_stream);
     }
 
     // Receiver callback
     std::optional<std::function<void()>> recv_hook = std::nullopt;
     if (return_recv_hook)
         recv_hook = [=]() {
+            if (graph_capture && macaHostPhaseFenceCoversPeers()) return;
             if (!macaHostPhaseFenceCoversPeers()) wait_peer_send_done();
             launcher(LOW_LATENCY_RECV_PHASE);
         };
 
     // Return values
-    return {packed_recv_x,
-            packed_recv_x_scales,
-            packed_recv_count,
-            packed_recv_src_info,
-            packed_recv_layout_range,
-            event,
-            recv_hook};
+    return {event, recv_hook};
 }
 
-std::tuple<torch::Tensor, std::optional<EventHandle>,
-           std::optional<std::function<void()>>>
-MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
-                          const torch::Tensor& topk_weights,
-                          const torch::Tensor& src_info,
-                          const torch::Tensor& layout_range,
-                          torch::Tensor& active_ranks,
+std::tuple<std::optional<EventHandle>, std::optional<std::function<void()>>>
+MooncakeEpBuffer::combine(uint64_t x_ptr, uint64_t topk_idx_ptr,
+                          uint64_t topk_weights_ptr, uint64_t src_info_ptr,
+                          uint64_t layout_range_ptr, uint64_t active_ranks_ptr,
+                          int num_local_experts, int num_combined_tokens,
+                          int hidden, int num_topk,
                           int num_max_dispatch_tokens_per_rank, int num_experts,
-                          int timeout_us, bool zero_copy, bool async,
-                          bool return_recv_hook,
-                          const std::optional<torch::Tensor>& out) {
-    // Tensor checks
-    EP_HOST_ASSERT(x.dim() == 3 and x.is_contiguous() and
-                   x.scalar_type() == torch::kBFloat16);
-    EP_HOST_ASSERT(x.size(0) == num_experts / num_ranks);
-    EP_HOST_ASSERT(x.size(1) == num_ranks * num_max_dispatch_tokens_per_rank);
-    EP_HOST_ASSERT(x.size(2) % sizeof(int4) == 0 and x.size(2) % 128 == 0);
-    EP_HOST_ASSERT(topk_idx.dim() == 2 and topk_idx.is_contiguous());
-    EP_HOST_ASSERT(topk_idx.size(0) == topk_weights.size(0) and
-                   topk_idx.size(1) == topk_weights.size(1));
-    EP_HOST_ASSERT(topk_idx.scalar_type() == torch::kInt64);
-    EP_HOST_ASSERT(topk_weights.dim() == 2 and topk_weights.is_contiguous());
-    EP_HOST_ASSERT(topk_weights.size(0) <= num_max_dispatch_tokens_per_rank);
-    EP_HOST_ASSERT(topk_weights.scalar_type() == torch::kFloat32);
-    EP_HOST_ASSERT(src_info.dim() == 2 and src_info.is_contiguous());
-    EP_HOST_ASSERT(src_info.scalar_type() == torch::kInt32 and
-                   x.size(0) == src_info.size(0));
-    EP_HOST_ASSERT(layout_range.dim() == 2 and layout_range.is_contiguous());
-    EP_HOST_ASSERT(layout_range.scalar_type() == torch::kInt64);
-    EP_HOST_ASSERT(layout_range.size(0) == num_experts / num_ranks and
-                   layout_range.size(1) == num_ranks);
-    auto hidden = static_cast<int>(x.size(2));
-    auto num_local_experts = num_experts / num_ranks,
-         num_topk = static_cast<int>(topk_weights.size(1));
-    auto num_combined_tokens = static_cast<int>(topk_weights.size(0));
-
-    // Buffer control
+                          int timeout_us, bool zero_copy,
+                          uint64_t combined_x_ptr, bool async,
+                          bool return_recv_hook, uint64_t compute_stream_ptr) {
+    EP_HOST_ASSERT(num_local_experts == num_experts / num_ranks);
+    EP_HOST_ASSERT(hidden % static_cast<int>(sizeof(int4)) == 0 &&
+                   hidden % 128 == 0);
+    EP_HOST_ASSERT(num_combined_tokens <= num_max_dispatch_tokens_per_rank);
+    void* x = reinterpret_cast<void*>(x_ptr);
+    auto* topk_idx = reinterpret_cast<int64_t*>(topk_idx_ptr);
+    auto* topk_weights = reinterpret_cast<float*>(topk_weights_ptr);
+    auto* src_info = reinterpret_cast<int*>(src_info_ptr);
+    auto* layout_range = reinterpret_cast<int64_t*>(layout_range_ptr);
+    auto* active_ranks = reinterpret_cast<int32_t*>(active_ranks_ptr);
+    void* combined_x = reinterpret_cast<void*>(combined_x_ptr);
+    EP_HOST_ASSERT(
+        num_combined_tokens == 0 ||
+        (x != nullptr && topk_idx != nullptr && topk_weights != nullptr));
+    EP_HOST_ASSERT(src_info != nullptr && layout_range != nullptr);
+    EP_HOST_ASSERT(active_ranks != nullptr);
+    EP_HOST_ASSERT(num_combined_tokens == 0 || combined_x != nullptr);
+
+    auto compute_stream_raw =
+        reinterpret_cast<cudaStream_t>(compute_stream_ptr);
+    const bool graph_capture = stream_is_capturing(compute_stream_raw);
+
+    // Buffer control.  The metadata tensor is the opaque handle returned by
+    // dispatch through the Python wrapper, so use it to pair this combine
+    // with the dispatch that produced it.  A process-wide flip is incorrect
+    // when TBO interleaves its two logical dispatchers on one native Buffer.
     BufferPair layout(gdr_buffer, num_max_dispatch_tokens_per_rank, hidden,
                       num_ranks, num_experts);
     EP_HOST_ASSERT(layout.total_bytes <= num_ep_buffer_bytes);
+    int shadow_slot = 0;
+    {
+        std::lock_guard<std::mutex> lock(buffer_mutex);
+        auto it = dispatch_shadow_slots.find(src_info_ptr);
+        if (it != dispatch_shadow_slots.end()) shadow_slot = it->second;
+    }
     int current_buffer_idx = buffer_idx;
     auto buffer = layout.buffers[current_buffer_idx];
     auto next_buffer = layout.buffers[buffer_idx ^= 1];
     int phase_epoch = ++phase_epochs[current_buffer_idx];
 
     // Wait previous tasks to be finished
-    // NOTES: the hook mode will always use the default stream
-    auto compute_stream = at::cuda::getCurrentCUDAStream();
-    auto launch_stream = return_recv_hook ? compute_stream : comm_stream;
+    // NOTES: the hook mode will always use the default stream, whose native
+    // handle is allowed to be nullptr in CUDA/PyTorch.
+    auto launch_stream =
+        (return_recv_hook || graph_capture) ? compute_stream_raw : comm_stream;
     EP_HOST_ASSERT(not(async and return_recv_hook));
-    if (not return_recv_hook) stream_wait(launch_stream, compute_stream);
-
-    // Allocate output tensor
-    torch::Tensor combined_x;
-    if (out.has_value()) {
-        EP_HOST_ASSERT(out->dim() == 2 and out->is_contiguous());
-        EP_HOST_ASSERT(out->size(0) == num_combined_tokens and
-                       out->size(1) == hidden);
-        EP_HOST_ASSERT(out->scalar_type() == x.scalar_type());
-        combined_x = out.value();
-    } else {
-        combined_x = torch::empty({num_combined_tokens, hidden}, x.options());
-    }
+    if (not return_recv_hook and not graph_capture)
+        stream_wait(launch_stream, compute_stream_raw);
 
     int64_t timeout_ticks =
         timeout_us == -1 ? -1
@@ -399,10 +455,10 @@ MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
     void** ipc_ptrs = p2p_transport_->peerPtrsTablePtr();
     int active_qps_per_rank = active_qps_per_rank_for_ep(
         USE_QP_COUNT / num_ranks, rdma_transport_ && rdma_transport_->isRoce(),
-        active_qps_cap_);
+        active_qps_cap_, num_experts / num_ranks);
 
     auto mark_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::mark_phase_ack(gdr_buffer, nvlink_avail, ipc_ptrs,
                                  buffer.rdma_send_signal_buffer, rank,
                                  num_ranks, phase_epoch, launch_stream);
@@ -410,7 +466,7 @@ MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
     };
 
     auto wait_peer_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::wait_phase_ack(buffer.rdma_send_signal_buffer, rank,
                                  num_ranks, phase_epoch, launch_stream,
                                  timeout_ticks);
@@ -418,7 +474,7 @@ MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
     };
 
     auto mark_and_wait_peer_send_done = [=]() {
-#ifdef MOONCAKE_EP_SPLIT_SEND_RECV
+#ifdef MOONCAKE_EP_PHASE_ACK
         mooncake::mark_and_wait_phase_ack(
             gdr_buffer, nvlink_avail, ipc_ptrs, buffer.rdma_send_signal_buffer,
             rank, num_ranks, phase_epoch, launch_stream, timeout_ticks);
@@ -427,22 +483,25 @@ MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
 
     // Kernel launch
     auto launcher = [=](int phases) {
+        auto* kernel_topk_idx =
+            topk_shadow(workspace, shadow_slot, num_experts);
         mooncake::combine(
-            combined_x.data_ptr(), active_ranks.data_ptr<int32_t>(), gdr_buffer,
+            combined_x, active_ranks, gdr_buffer,
             buffer.rdma_send_signal_buffer, buffer.rdma_recv_signal_buffer,
             buffer.rdma_send_data_buffer, buffer.rdma_recv_data_buffer, nullptr,
             nullptr, raddrs_ptr, rkeys_ptr, qp_devctxs_ptr, nvlink_avail,
-            ipc_ptrs, x.data_ptr(), topk_idx.data_ptr<int64_t>(),
-            topk_weights.data_ptr<float>(), src_info.data_ptr<int>(),
-            layout_range.data_ptr<int64_t>(),
+            ipc_ptrs, x, kernel_topk_idx, topk_weights, src_info, layout_range,
             next_buffer.rdma_recv_signal_buffer, num_combined_tokens, hidden,
             num_max_dispatch_tokens_per_rank, num_topk, num_experts, rank,
             num_ranks, workspace, launch_stream, timeout_ticks, phases,
             zero_copy, active_qps_per_rank);
     };
-    if (return_recv_hook) {
+    if (return_recv_hook &&
+        (!graph_capture || !macaHostPhaseFenceCoversPeers())) {
         launcher(LOW_LATENCY_SEND_PHASE);
         mark_send_done();
+    } else if (graph_capture) {
+        launcher(LOW_LATENCY_SEND_PHASE | LOW_LATENCY_RECV_PHASE);
     } else {
 #ifdef MOONCAKE_EP_SPLIT_SEND_RECV
         launcher(LOW_LATENCY_SEND_PHASE);
@@ -459,49 +518,29 @@ MooncakeEpBuffer::combine(const torch::Tensor& x, const torch::Tensor& topk_idx,
         // NOTES: we must ensure the all tensors will not be deallocated
         // before the stream-wait happens, so in Python API, we must wrap
         // all tensors into the event handle.
-        event = EventHandle(launch_stream);
+        event = EventHandle(reinterpret_cast<uint64_t>(launch_stream));
     } else if (return_recv_hook && macaHostPhaseFenceCoversPeers()) {
-        event = EventHandle(launch_stream);
-    } else if (not return_recv_hook) {
-        stream_wait(compute_stream, launch_stream);
+        event = EventHandle(reinterpret_cast<uint64_t>(launch_stream));
+    } else if (not return_recv_hook and not graph_capture) {
+        stream_wait(compute_stream_raw, launch_stream);
     }
 
     // Receiver callback
     std::optional<std::function<void()>> recv_hook = std::nullopt;
     if (return_recv_hook)
         recv_hook = [=]() {
+            if (graph_capture && macaHostPhaseFenceCoversPeers()) return;
             if (!macaHostPhaseFenceCoversPeers()) wait_peer_send_done();
             launcher(LOW_LATENCY_RECV_PHASE);
         };
 
     // Return values
-    return {combined_x, event, recv_hook};
-}
-
-torch::Tensor MooncakeEpBuffer::get_next_combine_buffer(
-    int num_max_dispatch_tokens_per_rank, int hidden, int num_experts) {
-    BufferPair layout(gdr_buffer, num_max_dispatch_tokens_per_rank, hidden,
-                      num_ranks, num_experts);
-
-    auto buffer = layout.buffers[buffer_idx];
-    auto dtype = torch::kBFloat16;
-    size_t num_bytes_per_combine_msg = hidden * EP_BF16_SIZE;
-    auto num_msg_elems =
-        static_cast<int>(num_bytes_per_combine_msg / elementSize(dtype));
-
-    EP_HOST_ASSERT(num_bytes_per_combine_msg % elementSize(dtype) == 0);
-    return torch::from_blob(
-        buffer.rdma_send_data_buffer,
-        {num_experts / num_ranks, num_ranks * num_max_dispatch_tokens_per_rank,
-         hidden},
-        {num_ranks * num_max_dispatch_tokens_per_rank * num_msg_elems,
-         num_msg_elems, 1},
-        torch::TensorOptions().dtype(dtype).device(torch::kCUDA));
+    return {event, recv_hook};
 }
 
 void MooncakeEpBuffer::update_local_qpns() {
     if (!rdma_transport_) return;
-    int ret = rdma_transport_->recreateQueuePairs(comm_stream.stream());
+    int ret = rdma_transport_->recreateQueuePairs(comm_stream);
     if (ret != 0) {
         ibgda_disabled_ = true;
         LOG(ERROR) << "[EP] Failed to recreate QPs";
@@ -542,12 +581,14 @@ void MooncakeEpBuffer::sync_ibgda_peers(
 }
 
 std::vector<int32_t> MooncakeEpBuffer::get_ipc_handle() {
+    if (!p2p_enabled_) return {};
     return p2p_transport_->exportIpcHandle(gdr_buffer);
 }
 
 void MooncakeEpBuffer::sync_nvlink_ipc_handles(
     const std::vector<std::vector<int32_t>>& remote_handles,
     const std::vector<int>& active_ranks_mask) {
+    if (!p2p_enabled_) return;
     p2p_transport_->importPeerHandles(gdr_buffer, rank, num_ranks,
                                       remote_handles, active_ranks_mask);
 }
diff --git a/mooncake-ep/src/mooncake_ep_elastic_buffer.cpp b/mooncake-ep/src/mooncake_ep_elastic_buffer.cpp
index 7d3d0052cf..38c58524fa 100644
--- a/mooncake-ep/src/mooncake_ep_elastic_buffer.cpp
+++ b/mooncake-ep/src/mooncake_ep_elastic_buffer.cpp
@@ -1,19 +1,26 @@
 #include <elastic/mooncake_ep_elastic_buffer.h>
 #include <elastic/mooncake_ep_elastic_launch.cuh>
+#include <elastic/mooncake_ep_elastic_layout.cuh>
 
 #include <algorithm>
 #include <cstdlib>
 #include <cstring>
+#include <exception>
 #include <stdexcept>
 
-#include <cuda_runtime.h>
+#include <cuda_alike.h>
+#include <glog/logging.h>
+#ifdef USE_NCCL_DEVICE
+#include <transport/device/nccl_device_transport.h>
+#endif
 
 namespace mooncake {
 namespace {
 
 int64_t ceil_div_i64(int64_t x, int64_t y) { return (x + y - 1) / y; }
 
-constexpr int kElasticHybridChannelsPerSm = 4;
+constexpr int kIbgdaElasticHybridChannelsPerSm = 4;
+constexpr int kNcclElasticHybridChannelsPerSm = 8;
 
 int64_t align_i64(int64_t x, int64_t alignment) {
     return ceil_div_i64(x, alignment) * alignment;
@@ -25,17 +32,19 @@ int getenv_int(const char* name, int default_value) {
     return std::max(1, std::atoi(value));
 }
 
-int hybrid_num_channels(int num_sms) {
-    return std::max(1, num_sms) * kElasticHybridChannelsPerSm;
+int hybrid_num_channels(int num_sms, int channels_per_sm) {
+    return std::max(1, num_sms) * channels_per_sm;
 }
 
-int hybrid_num_max_tokens_per_channel(int num_max_tokens_per_rank,
-                                      int num_sms) {
+int hybrid_num_max_tokens_per_channel(int num_max_tokens_per_rank, int num_sms,
+                                      int channels_per_sm) {
     return static_cast<int>(
-        ceil_div_i64(num_max_tokens_per_rank, hybrid_num_channels(num_sms)));
+        ceil_div_i64(num_max_tokens_per_rank,
+                     hybrid_num_channels(num_sms, channels_per_sm)));
 }
 
 int64_t elastic_workspace_num_bytes() {
+    // Preserve the established host reservation and payload offset.
     constexpr int64_t kNumMaxRanks = 1024;
     constexpr int64_t kNumMaxExperts = 2048;
     constexpr int64_t kNumMaxChannels = 8 * 160;
@@ -62,68 +71,401 @@ int64_t elastic_atomic_scratch_num_bytes() {
     return elastic_workspace_num_bytes();
 }
 
-int device_smem_bytes() {
-#ifdef MOONCAKE_EP_USE_MUSA
-    return 0;
-#else
-    int device = 0;
-    cudaGetDevice(&device);
-    int value = 0;
-    cudaDeviceGetAttribute(&value, cudaDevAttrMaxSharedMemoryPerBlockOptin,
-                           device);
-    return value > 0 ? value : 98304;
-#endif
+#ifdef USE_NCCL_DEVICE
+class ScopedCudaDevice {
+   public:
+    explicit ScopedCudaDevice(int device) {
+        CUDA_CHECK(cudaGetDevice(&previous_device_));
+        if (previous_device_ != device) {
+            CUDA_CHECK(cudaSetDevice(device));
+            restore_ = true;
+        }
+    }
+
+    ScopedCudaDevice(const ScopedCudaDevice&) = delete;
+    ScopedCudaDevice& operator=(const ScopedCudaDevice&) = delete;
+
+    ~ScopedCudaDevice() {
+        if (!restore_) return;
+        const auto status = cudaSetDevice(previous_device_);
+        if (status != cudaSuccess) {
+            LOG(ERROR)
+                << "failed to restore CUDA device after NCCL ElasticBuffer "
+                   "reconfiguration: "
+                << cudaGetErrorString(status);
+        }
+    }
+
+   private:
+    int previous_device_ = -1;
+    bool restore_ = false;
+};
+
+class NcclCommStream {
+   public:
+    NcclCommStream() {
+        int least_priority = 0;
+        int greatest_priority = 0;
+        auto status = cudaDeviceGetStreamPriorityRange(&least_priority,
+                                                       &greatest_priority);
+        if (status != cudaSuccess) {
+            cudaGetLastError();
+            greatest_priority = 0;
+        }
+        CUDA_CHECK(cudaStreamCreateWithPriority(&stream_, cudaStreamNonBlocking,
+                                                greatest_priority));
+    }
+
+    NcclCommStream(const NcclCommStream&) = delete;
+    NcclCommStream& operator=(const NcclCommStream&) = delete;
+
+    ~NcclCommStream() { reset(); }
+
+    cudaStream_t stream() const { return stream_; }
+
+    cudaError_t reset() {
+        if (stream_ == nullptr) return cudaSuccess;
+        const auto status = cudaStreamDestroy(stream_);
+        stream_ = nullptr;
+        return status;
+    }
+
+   private:
+    cudaStream_t stream_ = nullptr;
+};
+
+int nccl_gin_context_count(int requested_count, bool allow_hybrid_mode) {
+    // Match upstream DeepEP v2: hybrid mode reserves one notify context plus
+    // 64 data contexts; direct mode reserves one notify plus 16 data contexts.
+    const int default_count = allow_hybrid_mode ? 65 : 17;
+    constexpr int kMaxGinContexts = MAX_QP_COUNT;
+    const int count =
+        requested_count > 0
+            ? requested_count
+            : getenv_int("MOONCAKE_EP_NCCL_GIN_CONTEXTS", default_count);
+    if (count > kMaxGinContexts) {
+        throw std::invalid_argument(
+            "NCCL ElasticBuffer GIN context count exceeds MAX_QP_COUNT");
+    }
+    return count;
 }
+#endif
+}  // namespace
+
+struct NcclElasticState {
+#ifdef USE_NCCL_DEVICE
+    std::unique_ptr<device::NcclTransport> transport;
+    device::NcclBufferRegistration registration;
+    device::NcclDeviceContext device_context;
+    device::NcclTransportProperties properties;
+    device::NcclLsaTopology lsa_topology;
+    void* allocation = nullptr;
+    size_t allocation_bytes = 0;
+    int device_id = -1;
+    int gin_context_count = 0;
+    int clock_rate_khz = 0;
+    NcclCommStream comm_stream;
+
+    NcclElasticState(int rank, int num_ranks, size_t bytes,
+                     int requested_gin_context_count, bool use_rail_gin,
+                     int gin_traffic_class,
+                     const std::vector<int32_t>& nccl_unique_id)
+        : transport(device::createNcclDeviceTransport()),
+          allocation_bytes(bytes),
+          gin_context_count(requested_gin_context_count) {
+        if (!transport) {
+            throw std::runtime_error(
+                "failed to create the NCCL device transport");
+        }
+
+        CUDA_CHECK(cudaGetDevice(&device_id));
+        CUDA_CHECK(cudaDeviceGetAttribute(&clock_rate_khz, cudaDevAttrClockRate,
+                                          device_id));
+
+        device::NcclTransportConfig config;
+        config.rank = rank;
+        config.num_ranks = num_ranks;
+        config.enable_gin = num_ranks > 1;
+        config.gin_connection_type = use_rail_gin
+                                         ? device::NcclGinConnectionType::kRail
+                                         : device::NcclGinConnectionType::kFull;
+        config.gin_context_count =
+            config.enable_gin ? requested_gin_context_count : 0;
+        config.gin_exclusive_contexts = config.enable_gin;
+        config.gin_queue_depth = config.enable_gin ? 1024 : 0;
+        config.gin_signal_count = config.enable_gin ? num_ranks + 4 : 0;
+        config.gin_traffic_class = gin_traffic_class;
+        config.lsa_barrier_count = 0;
+        config.require_lsa_multimem = false;
+        if (transport->initialize(config, nccl_unique_id) != 0) {
+            throw std::runtime_error(
+                "failed to initialize the NCCL ElasticBuffer transport");
+        }
+
+        properties = transport->properties();
+        lsa_topology = transport->lsaTopology();
+        if (transport->allocateAndRegisterBuffer(allocation_bytes, &allocation,
+                                                 &registration) != 0) {
+            throw std::runtime_error(
+                "failed to allocate and register the NCCL ElasticBuffer");
+        }
+        device_context = transport->deviceContext(registration);
+        if (!transport->allRanksSucceeded(device_context.valid())) {
+            throw std::runtime_error(
+                "failed to create the NCCL ElasticBuffer device context on "
+                "one or more ranks");
+        }
+    }
+
+    int release() noexcept {
+        if (!transport) return 0;
+
+        int status = 0;
+        int previous_device = -1;
+        if (cudaGetDevice(&previous_device) != cudaSuccess ||
+            cudaSetDevice(device_id) != cudaSuccess) {
+            status = -1;
+        }
+        if (cudaStreamSynchronize(comm_stream.stream()) != cudaSuccess) {
+            status = -1;
+        }
+        if (registration.valid() &&
+            transport->deregisterBuffer(&registration) != 0) {
+            status = -1;
+        }
+        if (allocation != nullptr && !registration.valid()) {
+            if (transport->freeBuffer(allocation) != 0) status = -1;
+        }
+        if (transport->shutdown() != 0) status = -1;
+        if (comm_stream.reset() != cudaSuccess) status = -1;
+
+        allocation = nullptr;
+        device_context = {};
+        transport.reset();
+        if (previous_device >= 0 && previous_device != device_id &&
+            cudaSetDevice(previous_device) != cudaSuccess) {
+            status = -1;
+        }
+        return status;
+    }
+
+    int abort() noexcept {
+        if (!transport) return 0;
+
+        int status = 0;
+        int previous_device = -1;
+        if (cudaGetDevice(&previous_device) != cudaSuccess ||
+            cudaSetDevice(device_id) != cudaSuccess) {
+            status = -1;
+        }
+        if (cudaStreamSynchronize(comm_stream.stream()) != cudaSuccess) {
+            status = -1;
+        }
+        if (transport->abort() != 0) status = -1;
+        if (comm_stream.reset() != cudaSuccess) status = -1;
+
+        allocation = nullptr;
+        registration = {};
+        device_context = {};
+        transport.reset();
+        if (previous_device >= 0 && previous_device != device_id &&
+            cudaSetDevice(previous_device) != cudaSuccess) {
+            status = -1;
+        }
+        return status;
+    }
+#endif
+
+    ~NcclElasticState() {
+#ifdef USE_NCCL_DEVICE
+        release();
+#endif
+    }
+};
+
+#ifdef USE_NCCL_DEVICE
+namespace {
+ElasticTopology make_nccl_topology(NcclElasticState& state, int rank,
+                                   int num_ranks, bool allow_hybrid_mode) {
+    const auto& properties = state.properties;
+    const auto& lsa = state.lsa_topology;
+    const bool local_lsa_topology_valid =
+        properties.rank == rank && properties.num_ranks == num_ranks &&
+        lsa.rank >= 0 && lsa.size > 0 && lsa.first_rank >= 0 &&
+        lsa.first_rank + lsa.rank == rank &&
+        lsa.first_rank + lsa.size <= num_ranks && num_ranks % lsa.size == 0 &&
+        lsa.first_rank == (rank / lsa.size) * lsa.size;
+    if (!state.transport->allRanksSucceeded(local_lsa_topology_valid)) {
+        throw std::runtime_error(
+            "NCCL LSA membership on one or more ranks is not a "
+            "contiguous, equal-sized EP local team; reorder "
+            "process-group ranks by node/device");
+    }
 
+    ElasticTopology topology;
+    topology.rank_idx = rank;
+    topology.num_ranks = num_ranks;
+    topology.num_rdma_ranks = num_ranks / lsa.size;
+    topology.num_nvlink_ranks = lsa.size;
+    const bool local_mode_supported =
+        topology.num_rdma_ranks <= 1 || allow_hybrid_mode;
+    if (!state.transport->allRanksSucceeded(local_mode_supported)) {
+        throw std::runtime_error(
+            "multi-node NCCL ElasticBuffer requires "
+            "allow_hybrid_mode=true; full-world GIN kernels are not part "
+            "of the initial backend");
+    }
+    const bool local_topology_supported =
+        topology.num_rdma_ranks == 1
+            ? (lsa.size == 2 || lsa.size == 8)
+            : ((topology.num_rdma_ranks == 2 &&
+                (lsa.size == 4 || lsa.size == 8)) ||
+               (topology.num_rdma_ranks == 4 && lsa.size == 4));
+    if (!state.transport->allRanksSucceeded(local_topology_supported)) {
+        throw std::runtime_error(
+            "NCCL ElasticBuffer currently supports one LSA team of 2 or 8 "
+            "GPUs, two LSA teams of 4 or 8 GPUs, or four LSA teams of 4 "
+            "GPUs");
+    }
+    if (allow_hybrid_mode && topology.num_rdma_ranks > 1) {
+        topology.num_scaleout_ranks = topology.num_rdma_ranks;
+        topology.num_scaleup_ranks = topology.num_nvlink_ranks;
+        topology.scaleout_rank_idx = lsa.first_rank / lsa.size;
+        topology.scaleup_rank_idx = lsa.rank;
+        topology.hybrid_enabled = true;
+        topology.scaleup_lsa = true;
+    } else {
+        topology.num_scaleout_ranks = 1;
+        topology.num_scaleup_ranks = num_ranks;
+        topology.scaleout_rank_idx = 0;
+        topology.scaleup_rank_idx = rank;
+        topology.hybrid_enabled = false;
+        topology.scaleup_lsa = topology.num_rdma_ranks == 1;
+    }
+    return topology;
+}
 }  // namespace
+#endif
 
 ElasticLaunchContext MooncakeElasticBuffer::make_launch_context(
-    MooncakeEpBuffer& buffer, const ElasticTopology& topology,
-    void* mapped_host_workspace, int64_t timeout_cycles) {
+    int64_t timeout_cycles) const {
     ElasticLaunchContext ctx;
-    auto* rdma = buffer.rdma_transport_;
-    auto* gdr_base = static_cast<char*>(buffer.gdr_buffer);
-    // Mooncake P2P/RDMA Device API translates remote pointers as offsets from
-    // the registered GDR buffer base.  DeepEP elastic writes both `buffer` and
-    // `workspace` pointers to peer ranks through GIN, so both regions must live
-    // inside the same peer-visible registered allocation.  The elastic buffer
-    // size reserves `elastic_workspace_num_bytes()` first; use that prefix as
-    // the workspace.  RDMA atomics also need a separate local response area:
-    // mlx5 atomics write the fetched old value to the WQE local address, so
-    // reusing the remote signal workspace as `local_atomic_base` can corrupt
-    // the barrier/signal slots.  Reserve an equal-sized scratch prefix after
-    // the workspace, then place the communication buffer after both prefixes.
+    ctx.device_id = device_id_;
     const auto workspace_bytes = elastic_workspace_num_bytes();
-    const auto atomic_scratch_bytes = elastic_atomic_scratch_num_bytes();
-    ctx.gdr_buffer = gdr_base;
-    ctx.nvlink_available = buffer.p2p_transport_->availableTablePtr();
-    ctx.ipc_peer_ptrs = buffer.p2p_transport_->peerPtrsTablePtr();
-    ctx.raddrs = rdma ? rdma->raddrsPtr() : nullptr;
-    ctx.rkeys = rdma ? rdma->rkeysPtr() : nullptr;
-    ctx.qp_devctxs = rdma ? rdma->qpDevCtxsPtr() : nullptr;
-    ctx.rdma_send_signal_buffer = gdr_base + workspace_bytes;
-    ctx.rdma_recv_signal_buffer = gdr_base;
-    ctx.workspace = gdr_base;
-    ctx.buffer = gdr_base + workspace_bytes + atomic_scratch_bytes;
-    ctx.mapped_host_workspace = mapped_host_workspace;
-    ctx.rank = topology.rank_idx;
-    ctx.num_ranks = topology.num_ranks;
-    ctx.scaleout_rank_idx = topology.scaleout_rank_idx;
-    ctx.scaleup_rank_idx = topology.scaleup_rank_idx;
-    ctx.num_scaleout_ranks = topology.num_scaleout_ranks;
-    ctx.num_scaleup_ranks = topology.num_scaleup_ranks;
-    ctx.is_scaleup_nvlink = true;
-    ctx.num_qps = buffer.USE_QP_COUNT;
+    const auto scratch_bytes = elastic_atomic_scratch_num_bytes();
+
+    char* local_base = nullptr;
+    if (using_nccl()) {
+#ifdef USE_NCCL_DEVICE
+        local_base = static_cast<char*>(nccl_state_->allocation);
+        ctx.backend = ElasticTransportBackend::kNccl;
+        ctx.nccl.device = nccl_state_->device_context;
+        ctx.num_qps = std::max(1, nccl_state_->properties.gin_context_count);
+#else
+        throw std::logic_error(
+            "NCCL ElasticBuffer state exists in a non-NCCL build");
+#endif
+    } else {
+        if (!native_buffer_) {
+            throw std::logic_error(
+                "ElasticBuffer transport has already been destroyed");
+        }
+        auto& buffer = *native_buffer_;
+        auto* rdma = buffer.rdma_transport_;
+        local_base = static_cast<char*>(buffer.gdr_buffer);
+        ctx.backend = ElasticTransportBackend::kIbgda;
+        ctx.nvlink_available = buffer.p2p_transport_->availableTablePtr();
+        ctx.ipc_peer_ptrs = buffer.p2p_transport_->peerPtrsTablePtr();
+        ctx.raddrs = rdma ? rdma->raddrsPtr() : nullptr;
+        ctx.rkeys = rdma ? rdma->rkeysPtr() : nullptr;
+        ctx.qp_devctxs = rdma ? rdma->qpDevCtxsPtr() : nullptr;
+        ctx.rdma_send_signal_buffer = local_base + workspace_bytes;
+        ctx.rdma_recv_signal_buffer = local_base;
+        ctx.num_qps = buffer.USE_QP_COUNT;
+    }
+
+    // Both backends expose one registered allocation. Keep the established
+    // workspace and IBGDA atomic-response prefix sizes for a common payload
+    // offset; NCCL does not access the second prefix.
+    ctx.gdr_buffer = local_base;
+    ctx.workspace = local_base;
+    ctx.buffer = local_base + workspace_bytes + scratch_bytes;
+    ctx.mapped_host_workspace = mapped_host_workspace_;
+    ctx.rank = topology_.rank_idx;
+    ctx.num_ranks = topology_.num_ranks;
+    ctx.scaleout_rank_idx = topology_.scaleout_rank_idx;
+    ctx.scaleup_rank_idx = topology_.scaleup_rank_idx;
+    ctx.num_scaleout_ranks = topology_.num_scaleout_ranks;
+    ctx.num_scaleup_ranks = topology_.num_scaleup_ranks;
+    ctx.is_scaleup_nvlink = topology_.scaleup_lsa;
     ctx.timeout_cycles = timeout_cycles;
     return ctx;
 }
 
+std::vector<int32_t> create_elastic_nccl_unique_id() {
+#ifdef USE_NCCL_DEVICE
+    auto transport = device::createNcclDeviceTransport();
+    if (!transport) {
+        throw std::runtime_error("failed to create the NCCL device transport");
+    }
+    auto unique_id = transport->createUniqueId();
+    if (unique_id.empty()) {
+        throw std::runtime_error("failed to create an NCCL unique ID");
+    }
+    return unique_id;
+#else
+    throw std::runtime_error(
+        "Mooncake EP was built without NCCL Device API support; rebuild with "
+        "-DUSE_NCCL_DEVICE=ON");
+#endif
+}
+
+MooncakeElasticBuffer::MooncakeElasticBuffer(
+    int rank, int num_ranks, int64_t num_buffer_bytes,
+    int64_t num_max_tokens_per_rank, int64_t hidden, int64_t num_topk,
+    bool use_fp8_dispatch, bool deterministic, bool allow_hybrid_mode,
+    bool allow_multiple_reduction, bool prefer_overlap_with_compute, int sl_idx,
+    int num_allocated_qps, int num_cpu_timeout_secs, int num_gpu_timeout_secs)
+    : MooncakeElasticBuffer(
+          rank, num_ranks, num_buffer_bytes, num_max_tokens_per_rank, hidden,
+          num_topk, use_fp8_dispatch, deterministic, allow_hybrid_mode,
+          allow_multiple_reduction, prefer_overlap_with_compute, sl_idx,
+          num_allocated_qps, num_cpu_timeout_secs, num_gpu_timeout_secs,
+          "ibgda", {}) {}
+
 MooncakeElasticBuffer::MooncakeElasticBuffer(
     int rank, int num_ranks, int64_t num_buffer_bytes,
     int64_t num_max_tokens_per_rank, int64_t hidden, int64_t num_topk,
     bool use_fp8_dispatch, bool deterministic, bool allow_hybrid_mode,
     bool allow_multiple_reduction, bool prefer_overlap_with_compute, int sl_idx,
-    int num_allocated_qps, int num_cpu_timeout_secs, int num_gpu_timeout_secs) {
+    int num_allocated_qps, int num_cpu_timeout_secs, int num_gpu_timeout_secs,
+    const std::string& transport, const std::vector<int32_t>& nccl_unique_id)
+    : transport_(transport) {
+    if (rank < 0 || num_ranks <= 0 || rank >= num_ranks) {
+        throw std::invalid_argument("invalid ElasticBuffer rank or world size");
+    }
+    if (!allow_multiple_reduction) {
+        throw std::runtime_error(
+            "Mooncake ElasticBuffer currently supports only "
+            "allow_multiple_reduction=true");
+    }
+    if (transport_ != "ibgda" && transport_ != "nccl") {
+        throw std::invalid_argument(
+            "ElasticBuffer transport must be either 'ibgda' or 'nccl'");
+    }
+
+    CUDA_CHECK(cudaGetDevice(&device_id_));
+    CUDA_CHECK(cudaDeviceGetAttribute(
+        &physical_num_sms_, cudaDevAttrMultiProcessorCount, device_id_));
+#ifdef MOONCAKE_EP_USE_MUSA
+    device_smem_bytes_ = 0;
+#else
+    CUDA_CHECK(cudaDeviceGetAttribute(&device_smem_bytes_,
+                                      cudaDevAttrMaxSharedMemoryPerBlockOptin,
+                                      device_id_));
+    if (device_smem_bytes_ <= 0) device_smem_bytes_ = 98304;
+#endif
+
     config_.num_max_tokens_per_rank = num_max_tokens_per_rank;
     config_.hidden = hidden;
     config_.num_topk = num_topk;
@@ -137,35 +479,293 @@ MooncakeElasticBuffer::MooncakeElasticBuffer(
     config_.num_cpu_timeout_secs = num_cpu_timeout_secs;
     config_.num_gpu_timeout_secs = num_gpu_timeout_secs;
 
-    topology_ = discover_topology(rank, num_ranks, allow_hybrid_mode);
-    if (!allow_multiple_reduction) {
-        throw std::runtime_error(
-            "Mooncake ElasticBuffer currently supports only "
-            "allow_multiple_reduction=true");
-    }
     if (num_buffer_bytes == 0) {
         num_buffer_bytes = calculate_buffer_size(
             num_ranks, num_max_tokens_per_rank, hidden, num_topk,
             use_fp8_dispatch, allow_hybrid_mode, allow_multiple_reduction);
     }
-    native_buffer_ =
-        std::make_unique<MooncakeEpBuffer>(rank, num_ranks, num_buffer_bytes);
+    if (num_buffer_bytes <= 0) {
+        throw std::invalid_argument("ElasticBuffer size must be positive");
+    }
+
+    if (transport_ == "nccl") {
+#ifdef USE_NCCL_DEVICE
+        const int context_count =
+            nccl_gin_context_count(num_allocated_qps, allow_hybrid_mode);
+        nccl_state_ = std::make_unique<NcclElasticState>(
+            rank, num_ranks, static_cast<size_t>(num_buffer_bytes),
+            context_count, allow_hybrid_mode, sl_idx, nccl_unique_id);
+        topology_ = make_nccl_topology(*nccl_state_, rank, num_ranks,
+                                       allow_hybrid_mode);
+#else
+        (void)nccl_unique_id;
+        throw std::runtime_error(
+            "transport='nccl' requires a Mooncake EP build with "
+            "-DUSE_NCCL_DEVICE=ON");
+#endif
+    } else {
+        if (!nccl_unique_id.empty()) {
+            throw std::invalid_argument(
+                "nccl_unique_id must be empty for transport='ibgda'");
+        }
+        topology_ = discover_topology(rank, num_ranks, allow_hybrid_mode);
+        native_buffer_ = std::make_unique<MooncakeEpBuffer>(rank, num_ranks,
+                                                            num_buffer_bytes);
+    }
+
     host_workspace_bytes_ = elastic_workspace_num_bytes();
-    CUDA_CHECK(cudaHostAlloc(&host_workspace_, host_workspace_bytes_,
-                             cudaHostAllocMapped));
-    CUDA_CHECK(
-        cudaHostGetDevicePointer(&mapped_host_workspace_, host_workspace_, 0));
-    std::memset(host_workspace_, 0, host_workspace_bytes_);
+    if (using_nccl()) {
+#ifdef USE_NCCL_DEVICE
+        const cudaError_t allocation_status = cudaHostAlloc(
+            &host_workspace_, host_workspace_bytes_, cudaHostAllocMapped);
+        cudaError_t mapping_status = cudaSuccess;
+        if (allocation_status == cudaSuccess) {
+            mapping_status = cudaHostGetDevicePointer(&mapped_host_workspace_,
+                                                      host_workspace_, 0);
+        }
+        const bool local_workspace_valid =
+            allocation_status == cudaSuccess && mapping_status == cudaSuccess;
+        if (!nccl_state_->transport->allRanksSucceeded(local_workspace_valid)) {
+            if (host_workspace_ != nullptr) cudaFreeHost(host_workspace_);
+            host_workspace_ = nullptr;
+            mapped_host_workspace_ = nullptr;
+            throw std::runtime_error(
+                "failed to allocate and map the NCCL ElasticBuffer host "
+                "workspace on one or more ranks");
+        }
+        std::memset(host_workspace_, 0, host_workspace_bytes_);
+#else
+        throw std::logic_error(
+            "NCCL ElasticBuffer state exists in a non-NCCL build");
+#endif
+    } else {
+        try {
+            CUDA_CHECK(cudaHostAlloc(&host_workspace_, host_workspace_bytes_,
+                                     cudaHostAllocMapped));
+            CUDA_CHECK(cudaHostGetDevicePointer(&mapped_host_workspace_,
+                                                host_workspace_, 0));
+            std::memset(host_workspace_, 0, host_workspace_bytes_);
+        } catch (...) {
+            if (host_workspace_ != nullptr) cudaFreeHost(host_workspace_);
+            host_workspace_ = nullptr;
+            mapped_host_workspace_ = nullptr;
+            throw;
+        }
+    }
 }
 
 MooncakeElasticBuffer::~MooncakeElasticBuffer() {
+    try {
+        destroy();
+    } catch (const std::exception& error) {
+        LOG(ERROR) << "ElasticBuffer cleanup failed: " << error.what();
+    } catch (...) {
+        LOG(ERROR) << "ElasticBuffer cleanup failed with an unknown error";
+    }
+}
+
+void MooncakeElasticBuffer::destroy() {
+    if (destroyed_) return;
+    destroyed_ = true;
+
+    std::exception_ptr cleanup_error;
+#ifdef USE_NCCL_DEVICE
+    if (nccl_state_) {
+        if (nccl_state_->release() != 0) {
+            cleanup_error = std::make_exception_ptr(
+                std::runtime_error("NCCL ElasticBuffer cleanup failed"));
+        }
+        nccl_state_.reset();
+    }
+#endif
+    if (native_buffer_) {
+        auto* buffer = native_buffer_.release();
+        if (cudaStreamSynchronize(buffer->comm_stream) != cudaSuccess &&
+            !cleanup_error) {
+            cleanup_error = std::make_exception_ptr(std::runtime_error(
+                "failed to synchronize the IBGDA ElasticBuffer stream"));
+        }
+        try {
+            delete buffer;
+        } catch (...) {
+            if (!cleanup_error) cleanup_error = std::current_exception();
+        }
+    }
     if (host_workspace_ != nullptr) {
-        cudaFreeHost(host_workspace_);
+        if (cudaFreeHost(host_workspace_) != cudaSuccess && !cleanup_error) {
+            cleanup_error = std::make_exception_ptr(
+                std::runtime_error("failed to free ElasticBuffer workspace"));
+        }
         host_workspace_ = nullptr;
         mapped_host_workspace_ = nullptr;
     }
+    if (cleanup_error) std::rethrow_exception(cleanup_error);
+}
+
+void MooncakeElasticBuffer::reconfigure_nccl(
+    const std::vector<int32_t>& nccl_unique_id) {
+    if (destroyed_ || !nccl_state_) {
+        throw std::runtime_error(
+            "NCCL ElasticBuffer reconfiguration requires a live NCCL buffer");
+    }
+#ifdef USE_NCCL_DEVICE
+    const ScopedCudaDevice device_guard(device_id_);
+    // update_ep_member() is a quiescent-boundary operation. Synchronizing the
+    // communication stream makes the lifetime boundary explicit even for
+    // direct native callers that do not use the Python wrapper.
+    CUDA_CHECK(cudaStreamSynchronize(nccl_state_->comm_stream.stream()));
+
+    const int rank = topology_.rank_idx;
+    const int num_ranks = topology_.num_ranks;
+    const int context_count = nccl_state_->gin_context_count;
+
+    // Build the complete replacement before publishing it. This intentionally
+    // uses a second allocation: GIN VA-signal storage cannot be cleared with
+    // ordinary CUDA stores while its old NCCL window remains registered.
+    auto candidate = std::make_unique<NcclElasticState>(
+        rank, num_ranks, nccl_state_->allocation_bytes, context_count,
+        config_.allow_hybrid_mode, config_.sl_idx, nccl_unique_id);
+    const auto candidate_topology = make_nccl_topology(
+        *candidate, rank, num_ranks, config_.allow_hybrid_mode);
+
+    // Initial construction performs this same status collective after
+    // creating its host workspace. Reconfiguration participates as well so a
+    // replacement rank constructing a new buffer and surviving ranks updating
+    // an old one execute an identical NCCL setup sequence.
+    const bool local_workspace_valid =
+        host_workspace_ != nullptr && mapped_host_workspace_ != nullptr;
+    if (!candidate->transport->allRanksSucceeded(local_workspace_valid)) {
+        throw std::runtime_error(
+            "NCCL ElasticBuffer host workspace is unavailable on one or more "
+            "recovered ranks");
+    }
+
+    auto previous = std::move(nccl_state_);
+    nccl_state_ = std::move(candidate);
+    topology_ = candidate_topology;
+    std::memset(host_workspace_, 0, host_workspace_bytes_);
+    deterministic_rank_count_buffer_.reset();
+    deterministic_rank_count_buffer_bytes_ = 0;
+
+    // A replacement process never owned the previous communicator, so normal
+    // collective destruction cannot be required here. Retire it locally after
+    // the new generation is already usable.
+    if (previous->abort() != 0) {
+        LOG(WARNING) << "failed to completely release an obsolete NCCL "
+                        "ElasticBuffer generation";
+    }
+#else
+    (void)nccl_unique_id;
+    throw std::runtime_error(
+        "Mooncake EP was built without NCCL Device API support");
+#endif
+}
+
+MooncakeEpBuffer& MooncakeElasticBuffer::native_buffer() {
+    if (!native_buffer_) {
+        throw std::runtime_error(
+            "this ElasticBuffer uses NCCL or has already been destroyed");
+    }
+    return *native_buffer_;
+}
+
+bool MooncakeElasticBuffer::ibgda_disabled() const {
+    if (using_nccl()) return true;
+    if (!native_buffer_) {
+        throw std::runtime_error("ElasticBuffer has already been destroyed");
+    }
+    return native_buffer_->ibgda_disabled();
+}
+
+bool MooncakeElasticBuffer::use_fast_path() {
+    return using_nccl() ? true : native_buffer().use_fast_path();
+}
+
+void MooncakeElasticBuffer::update_local_qpns() {
+    if (using_nccl()) {
+        throw std::runtime_error(
+            "NCCL ElasticBuffer membership is fixed; recreate the buffer "
+            "instead of updating QPs");
+    }
+    native_buffer().update_local_qpns();
 }
 
+bool MooncakeElasticBuffer::is_roce() const {
+    if (using_nccl()) return false;
+    if (!native_buffer_) {
+        throw std::runtime_error("ElasticBuffer has already been destroyed");
+    }
+    return native_buffer_->is_roce();
+}
+
+void MooncakeElasticBuffer::sync_ibgda_peers(
+    const std::vector<int64_t>& remote_addrs,
+    const std::vector<int32_t>& remote_keys,
+    const std::vector<std::vector<int32_t>>& peer_qpns,
+    const std::vector<std::vector<int32_t>>& peer_lids,
+    const std::vector<int64_t>& subnet_prefixes,
+    const std::vector<int64_t>& interface_ids,
+    const std::vector<int>& active_ranks_mask) {
+    native_buffer().sync_ibgda_peers(remote_addrs, remote_keys, peer_qpns,
+                                     peer_lids, subnet_prefixes, interface_ids,
+                                     active_ranks_mask);
+}
+
+std::tuple<int64_t, int32_t> MooncakeElasticBuffer::get_mr_info() {
+    return native_buffer().get_mr_info();
+}
+
+std::tuple<int64_t, int64_t> MooncakeElasticBuffer::get_gid() {
+    return native_buffer().get_gid();
+}
+
+std::vector<int32_t> MooncakeElasticBuffer::get_local_qpns() {
+    return native_buffer().get_local_qpns();
+}
+
+std::vector<int32_t> MooncakeElasticBuffer::get_local_lids() {
+    return native_buffer().get_local_lids();
+}
+
+std::vector<int32_t> MooncakeElasticBuffer::get_ipc_handle() {
+    return native_buffer().get_ipc_handle();
+}
+
+void MooncakeElasticBuffer::sync_nvlink_ipc_handles(
+    const std::vector<std::vector<int32_t>>& remote_handles,
+    const std::vector<int>& active_ranks_mask) {
+    native_buffer().sync_nvlink_ipc_handles(remote_handles, active_ranks_mask);
+}
+
+cudaStream_t MooncakeElasticBuffer::communication_stream() const {
+    if (using_nccl()) {
+#ifdef USE_NCCL_DEVICE
+        return nccl_state_->comm_stream.stream();
+#else
+        throw std::logic_error(
+            "NCCL ElasticBuffer state exists in a non-NCCL build");
+#endif
+    }
+    if (!native_buffer_) {
+        throw std::runtime_error("ElasticBuffer has already been destroyed");
+    }
+    return native_buffer_->comm_stream;
+}
+
+int MooncakeElasticBuffer::clock_rate_khz() const {
+    if (using_nccl()) {
+#ifdef USE_NCCL_DEVICE
+        return nccl_state_->clock_rate_khz;
+#else
+        throw std::logic_error(
+            "NCCL ElasticBuffer state exists in a non-NCCL build");
+#endif
+    }
+    if (!native_buffer_) {
+        throw std::runtime_error("ElasticBuffer has already been destroyed");
+    }
+    return native_buffer_->clock_rate_khz;
+}
 int64_t MooncakeElasticBuffer::calculate_buffer_size(
     int num_ranks, int64_t num_max_tokens_per_rank, int64_t hidden,
     int64_t num_topk, bool use_fp8_dispatch, bool allow_hybrid_mode,
@@ -197,6 +797,23 @@ std::tuple<int, int> MooncakeElasticBuffer::get_logical_domain_size() const {
     return {topology_.num_scaleout_ranks, topology_.num_scaleup_ranks};
 }
 
+std::shared_ptr<void>
+MooncakeElasticBuffer::ensure_deterministic_rank_count_buffer(int num_sms) {
+    const int64_t required_bytes = static_cast<int64_t>(sizeof(int)) * num_sms *
+                                   topology_.num_scaleup_ranks;
+    if (deterministic_rank_count_buffer_ != nullptr &&
+        deterministic_rank_count_buffer_bytes_ >= required_bytes) {
+        return deterministic_rank_count_buffer_;
+    }
+
+    void* buffer_ptr = nullptr;
+    CUDA_CHECK(cudaMalloc(&buffer_ptr, required_bytes));
+    deterministic_rank_count_buffer_ =
+        std::shared_ptr<void>(buffer_ptr, [](void* p) { cudaFree(p); });
+    deterministic_rank_count_buffer_bytes_ = required_bytes;
+    return deterministic_rank_count_buffer_;
+}
+
 int MooncakeElasticBuffer::get_theoretical_num_sms(int num_experts,
                                                    int num_topk) const {
     int device = 0;
@@ -210,142 +827,93 @@ int MooncakeElasticBuffer::get_theoretical_num_sms(int num_experts,
                                  std::max(1, num_experts * num_topk)}));
 }
 
-ElasticDispatchOutput MooncakeElasticBuffer::dispatch(
-    const torch::Tensor& x, const std::optional<torch::Tensor>& sf,
-    const torch::Tensor& topk_idx,
-    const std::optional<torch::Tensor>& topk_weights,
-    torch::Tensor& active_ranks, int num_experts, int num_max_tokens_per_rank,
-    int expert_alignment, int num_sms, bool do_expand, bool do_cpu_sync,
-    bool async_with_compute_stream,
-    const std::optional<ElasticNativeHandle>& cached_handle) {
-    EP_HOST_ASSERT(x.dim() == 2 && x.is_contiguous());
-    const bool use_sf = sf.has_value();
-    if (use_sf) {
-        EP_HOST_ASSERT(x.element_size() == 1);
-        EP_HOST_ASSERT(sf->dim() == 2 && sf->is_cuda());
-        EP_HOST_ASSERT(sf->scalar_type() == torch::kFloat32 ||
-                       sf->scalar_type() == torch::kInt32);
-        EP_HOST_ASSERT(sf->size(0) == x.size(0));
-    } else {
-        EP_HOST_ASSERT(!config_.use_fp8_dispatch);
-        EP_HOST_ASSERT(x.scalar_type() == torch::kBFloat16);
-    }
-    EP_HOST_ASSERT(topk_idx.dim() == 2 && topk_idx.is_contiguous());
-    EP_HOST_ASSERT(topk_idx.scalar_type() == torch::kInt64);
-    EP_HOST_ASSERT(x.size(0) == topk_idx.size(0));
+std::optional<EventHandle> MooncakeElasticBuffer::dispatch(
+    uint64_t x_ptr, int x_element_size, uint64_t sf_ptr, int num_tokens,
+    int hidden, int num_sf_packs, int sf_token_stride, int sf_hidden_stride,
+    uint64_t topk_idx_ptr, int num_topk, uint64_t topk_weights_ptr,
+    uint64_t active_ranks_ptr, int num_experts, int num_max_tokens_per_rank,
+    int expert_alignment, int num_sms, bool do_expand,
+    bool async_with_compute_stream, uint64_t compute_stream_ptr,
+    bool cached_mode, int num_recv_tokens,
+    uint64_t psum_num_recv_tokens_per_scaleup_rank_ptr,
+    uint64_t psum_num_recv_tokens_per_expert_ptr,
+    uint64_t dst_buffer_slot_idx_ptr, uint64_t token_metadata_at_forward_ptr,
+    uint64_t channel_linked_list_ptr, uint64_t recv_x_ptr,
+    uint64_t recv_x_scales_ptr, uint64_t recv_topk_idx_ptr,
+    uint64_t recv_topk_weights_ptr, uint64_t recv_src_metadata_ptr) {
+    const bool use_sf = sf_ptr != 0;
     EP_HOST_ASSERT(num_experts % topology_.num_ranks == 0);
 
-    const int num_tokens = static_cast<int>(x.size(0));
-    const int hidden = static_cast<int>(x.size(1));
-    const int num_topk = static_cast<int>(topk_idx.size(1));
-    const int num_sf_packs = use_sf ? static_cast<int>(sf->size(1)) : 0;
-    const int sf_token_stride = use_sf ? static_cast<int>(sf->stride(0)) : 0;
-    const int sf_hidden_stride = use_sf ? static_cast<int>(sf->stride(1)) : 0;
     const int num_local_experts = num_experts / topology_.num_ranks;
     // The copy epilogue uses `kNumMaxTokensPerRank * kNumRanks` as the
     // no-CPU-sync sentinel and then reads the real local receive count from the
-    // GPU prefix-sum tensor.  In hybrid mode each scale-up peer may receive
+    // GPU prefix-sum tensor. In hybrid mode each scale-up peer may receive
     // tokens forwarded from every scale-out rank, so the conservative output
     // capacity and sentinel must cover the full logical world, not just the
     // intra-node scale-up domain.
-    const int num_recv_tokens = num_max_tokens_per_rank * topology_.num_ranks;
-    const int num_smem_bytes = device_smem_bytes();
+    const int max_num_recv_tokens =
+        num_max_tokens_per_rank * topology_.num_ranks;
+    EP_HOST_ASSERT(num_recv_tokens >= 0 &&
+                   num_recv_tokens <= max_num_recv_tokens);
+    EP_HOST_ASSERT(cached_mode || num_recv_tokens == max_num_recv_tokens);
+    const int num_smem_bytes = device_smem_bytes_;
     const int num_channels_per_sm = 1;
     const int num_channels = num_sms * num_channels_per_sm;
-    const bool cached_mode = cached_handle.has_value();
     const bool use_hybrid = topology_.num_scaleout_ranks != 1;
-    const int hybrid_channels = use_hybrid ? hybrid_num_channels(num_sms) : 0;
+    const int hybrid_channels_per_sm = using_nccl()
+                                           ? kNcclElasticHybridChannelsPerSm
+                                           : kIbgdaElasticHybridChannelsPerSm;
+    const int hybrid_channels =
+        use_hybrid ? hybrid_num_channels(num_sms, hybrid_channels_per_sm) : 0;
     const int hybrid_max_tokens_per_channel =
-        use_hybrid ? hybrid_num_max_tokens_per_channel(num_max_tokens_per_rank,
-                                                       num_sms)
-                   : 0;
-    if (cached_mode) {
-        const auto& handle = cached_handle.value();
-        EP_HOST_ASSERT(!handle.do_expand && !do_expand);
-        EP_HOST_ASSERT(handle.num_experts == num_experts);
-        EP_HOST_ASSERT(handle.expert_alignment == expert_alignment);
-        EP_HOST_ASSERT(handle.num_max_tokens_per_rank ==
-                       num_max_tokens_per_rank);
-        EP_HOST_ASSERT(handle.num_sms == num_sms);
-        if (use_hybrid) {
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.dim() == 4);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(0) ==
-                           hybrid_channels);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(1) ==
-                           topology_.num_scaleout_ranks);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(2) ==
-                           hybrid_max_tokens_per_channel);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(3) == num_topk);
-            EP_HOST_ASSERT(handle.token_metadata_at_forward.has_value());
-            EP_HOST_ASSERT(handle.channel_linked_list.has_value());
-        } else {
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.dim() == 2);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(0) == num_tokens);
-            EP_HOST_ASSERT(handle.dst_buffer_slot_idx.size(1) == num_topk);
-        }
+        use_hybrid
+            ? hybrid_num_max_tokens_per_channel(num_max_tokens_per_rank,
+                                                num_sms, hybrid_channels_per_sm)
+            : 0;
+
+    EP_HOST_ASSERT(x_ptr != 0 && topk_idx_ptr != 0 && active_ranks_ptr != 0);
+    EP_HOST_ASSERT(psum_num_recv_tokens_per_scaleup_rank_ptr != 0);
+    EP_HOST_ASSERT(psum_num_recv_tokens_per_expert_ptr != 0);
+    EP_HOST_ASSERT(dst_buffer_slot_idx_ptr != 0);
+    EP_HOST_ASSERT(recv_x_ptr != 0 && recv_topk_idx_ptr != 0 &&
+                   recv_src_metadata_ptr != 0);
+    if (use_hybrid) {
+        EP_HOST_ASSERT(token_metadata_at_forward_ptr != 0);
+        EP_HOST_ASSERT(channel_linked_list_ptr != 0);
     }
 
-    auto compute_stream = at::cuda::getCurrentCUDAStream();
-    auto launch_stream = native_buffer_->comm_stream;
-    stream_wait(launch_stream, compute_stream);
+    void* x = reinterpret_cast<void*>(x_ptr);
+    void* sf = reinterpret_cast<void*>(sf_ptr);
+    auto* topk_idx = reinterpret_cast<int64_t*>(topk_idx_ptr);
+    auto* topk_weights = reinterpret_cast<float*>(topk_weights_ptr);
+    auto* active_ranks = reinterpret_cast<int*>(active_ranks_ptr);
+    auto* psum_num_recv_tokens_per_scaleup_rank =
+        reinterpret_cast<int*>(psum_num_recv_tokens_per_scaleup_rank_ptr);
+    auto* psum_num_recv_tokens_per_expert =
+        reinterpret_cast<int*>(psum_num_recv_tokens_per_expert_ptr);
+    auto* dst_buffer_slot_idx = reinterpret_cast<int*>(dst_buffer_slot_idx_ptr);
+    auto* token_metadata_at_forward =
+        reinterpret_cast<int*>(token_metadata_at_forward_ptr);
+    auto* channel_linked_list = reinterpret_cast<int*>(channel_linked_list_ptr);
+    void* recv_x = reinterpret_cast<void*>(recv_x_ptr);
+    void* recv_x_scales = reinterpret_cast<void*>(recv_x_scales_ptr);
+    auto* recv_topk_idx = reinterpret_cast<int64_t*>(recv_topk_idx_ptr);
+    auto* recv_topk_weights = reinterpret_cast<float*>(recv_topk_weights_ptr);
+    auto* recv_src_metadata = reinterpret_cast<int*>(recv_src_metadata_ptr);
+
+    auto compute_stream_raw =
+        reinterpret_cast<cudaStream_t>(compute_stream_ptr);
+    auto launch_stream = communication_stream();
+    stream_wait(launch_stream, compute_stream_raw);
 
     const int64_t timeout_cycles =
         config_.num_gpu_timeout_secs < 0
             ? -1
-            : static_cast<int64_t>(native_buffer_->clock_rate_khz) *
+            : static_cast<int64_t>(clock_rate_khz()) *
                   static_cast<int64_t>(config_.num_gpu_timeout_secs) * 1000;
-    auto launch_ctx = make_launch_context(
-        *native_buffer_, topology_, mapped_host_workspace_, timeout_cycles);
-
-    auto psum_num_recv_tokens_per_scaleup_rank =
-        cached_mode ? cached_handle->psum_num_recv_tokens_per_scaleup_rank
-                    : torch::empty({topology_.num_scaleup_ranks},
-                                   torch::TensorOptions()
-                                       .dtype(torch::kInt32)
-                                       .device(x.device()));
-    auto psum_num_recv_tokens_per_expert =
-        cached_mode
-            ? cached_handle->psum_num_recv_tokens_per_expert
-            : torch::empty({num_local_experts + 1}, torch::TensorOptions()
-                                                        .dtype(torch::kInt32)
-                                                        .device(x.device()));
-    auto dst_buffer_slot_idx =
-        cached_mode
-            ? cached_handle->dst_buffer_slot_idx
-            : (use_hybrid ? torch::empty(
-                                {hybrid_channels, topology_.num_scaleout_ranks,
-                                 hybrid_max_tokens_per_channel, num_topk},
-                                torch::TensorOptions()
-                                    .dtype(torch::kInt32)
-                                    .device(x.device()))
-                          : torch::empty({num_tokens, num_topk},
-                                         torch::TensorOptions()
-                                             .dtype(torch::kInt32)
-                                             .device(x.device())));
-    std::optional<torch::Tensor> token_metadata_at_forward = std::nullopt;
-    std::optional<torch::Tensor> channel_linked_list = std::nullopt;
-    if (use_hybrid) {
-        if (cached_mode) {
-            token_metadata_at_forward =
-                cached_handle->token_metadata_at_forward;
-            channel_linked_list = cached_handle->channel_linked_list;
-        } else {
-            const int forward_metadata_dims = 2 + num_topk * 2;
-            token_metadata_at_forward = torch::empty(
-                {hybrid_channels,
-                 topology_.num_scaleout_ranks * hybrid_max_tokens_per_channel +
-                     1,
-                 forward_metadata_dims},
-                torch::TensorOptions().dtype(torch::kInt32).device(x.device()));
-            channel_linked_list = torch::empty(
-                {hybrid_channels,
-                 topology_.num_scaleout_ranks * hybrid_max_tokens_per_channel +
-                     1,
-                 topology_.num_scaleup_ranks},
-                torch::TensorOptions().dtype(torch::kInt32).device(x.device()));
-        }
-    }
-    std::optional<torch::Tensor> deterministic_rank_count_buffer = std::nullopt;
+    auto launch_ctx = make_launch_context(timeout_cycles);
+
+    std::shared_ptr<void> deterministic_rank_count_buffer;
 #ifdef MOONCAKE_EP_USE_MUSA
     // MUSA non-hybrid dispatch always runs
     // launch_musa_elastic_prepare_dispatch(), which assigns slots and publishes
@@ -356,248 +924,117 @@ ElasticDispatchOutput MooncakeElasticBuffer::dispatch(
         config_.deterministic && !cached_mode && !use_hybrid;
 #endif
     if (run_deterministic_prologue) {
-        deterministic_rank_count_buffer = torch::empty(
-            {num_sms, topology_.num_scaleup_ranks},
-            torch::TensorOptions().dtype(torch::kInt32).device(x.device()));
+        deterministic_rank_count_buffer =
+            ensure_deterministic_rank_count_buffer(num_sms);
         launch_elastic_dispatch_deterministic_prologue(
-            topk_idx.data_ptr<int64_t>(),
-            deterministic_rank_count_buffer.value().data_ptr<int>(),
-            dst_buffer_slot_idx.data_ptr<int>(), num_tokens,
-            num_max_tokens_per_rank, num_experts, num_topk,
-            topology_.scaleup_rank_idx, topology_.num_scaleup_ranks, num_sms,
-            num_smem_bytes, launch_stream.stream());
+            topk_idx, static_cast<int*>(deterministic_rank_count_buffer.get()),
+            dst_buffer_slot_idx, num_tokens, num_max_tokens_per_rank,
+            num_experts, num_topk, topology_.scaleup_rank_idx,
+            topology_.num_scaleup_ranks, num_sms, num_smem_bytes,
+            launch_stream);
     }
 
     launch_mooncake_elastic_dispatch(
-        x.data_ptr(), use_sf ? const_cast<void*>(sf->data_ptr()) : nullptr,
-        const_cast<int64_t*>(topk_idx.data_ptr<int64_t>()),
-        topk_weights.has_value()
-            ? const_cast<float*>(topk_weights->data_ptr<float>())
-            : nullptr,
-        nullptr, nullptr, psum_num_recv_tokens_per_scaleup_rank.data_ptr<int>(),
-        psum_num_recv_tokens_per_expert.data_ptr<int>(),
-        dst_buffer_slot_idx.data_ptr<int>(),
-        token_metadata_at_forward.has_value()
-            ? token_metadata_at_forward->data_ptr<int>()
-            : nullptr,
-        num_tokens, num_max_tokens_per_rank, hidden,
-        static_cast<int>(x.element_size()), num_sf_packs, sf_token_stride,
-        sf_hidden_stride, num_experts, num_topk, expert_alignment, num_sms,
-        use_hybrid ? kElasticHybridChannelsPerSm : num_channels_per_sm,
+        x, sf, topk_idx, topk_weights, nullptr, nullptr,
+        psum_num_recv_tokens_per_scaleup_rank, psum_num_recv_tokens_per_expert,
+        dst_buffer_slot_idx, token_metadata_at_forward, num_tokens,
+        num_max_tokens_per_rank, hidden, x_element_size, num_sf_packs,
+        sf_token_stride, sf_hidden_stride, num_experts, num_topk,
+        expert_alignment, num_sms,
+        use_hybrid ? hybrid_channels_per_sm : num_channels_per_sm,
         num_smem_bytes, cached_mode, config_.deterministic, false, launch_ctx,
-        launch_stream.stream());
-
-    const int num_recv_output_capacity =
-        do_expand ? num_recv_tokens * num_topk : num_recv_tokens;
-    auto recv_x = torch::empty({num_recv_output_capacity, hidden}, x.options());
-    auto recv_x_scales = std::optional<torch::Tensor>();
-    void* recv_x_scales_ptr = nullptr;
-    int recv_sf_token_stride = 0;
-    int recv_sf_hidden_stride = 0;
-    if (use_sf) {
-        recv_x_scales = torch::empty({num_recv_output_capacity, num_sf_packs},
-                                     sf->options());
-        recv_x_scales_ptr = recv_x_scales->data_ptr();
-        recv_sf_token_stride = static_cast<int>(recv_x_scales->stride(0));
-        recv_sf_hidden_stride = static_cast<int>(recv_x_scales->stride(1));
-    }
-    auto recv_topk_idx =
-        torch::empty({num_recv_tokens, num_topk}, topk_idx.options());
-    auto recv_topk_weights = std::optional<torch::Tensor>();
-    float* recv_topk_weights_ptr = nullptr;
-    if (topk_weights.has_value()) {
-        recv_topk_weights = do_expand
-                                ? torch::empty({num_recv_output_capacity},
-                                               topk_weights->options())
-                                : torch::empty({num_recv_tokens, num_topk},
-                                               topk_weights->options());
-        recv_topk_weights_ptr = recv_topk_weights->data_ptr<float>();
-    }
-    auto recv_src_metadata = torch::empty(
-        {num_recv_tokens, num_topk + 2},
-        torch::TensorOptions().dtype(torch::kInt32).device(x.device()));
-    auto handle_psum_num_recv_tokens_per_expert =
-        do_expand
-            ? psum_num_recv_tokens_per_expert.slice(0, 0, num_local_experts)
-            : psum_num_recv_tokens_per_expert.slice(0, 1,
-                                                    num_local_experts + 1);
-    auto epilogue_psum_num_recv_tokens_per_expert =
+        launch_stream);
+
+    const int recv_sf_token_stride = num_sf_packs;
+    const int recv_sf_hidden_stride = 1;
+    auto* epilogue_psum_num_recv_tokens_per_expert =
         do_expand ? psum_num_recv_tokens_per_expert
-                  : handle_psum_num_recv_tokens_per_expert;
+                  : psum_num_recv_tokens_per_expert + 1;
 
     launch_mooncake_elastic_dispatch_copy_epilogue(
-        recv_x.data_ptr(), recv_x_scales_ptr, recv_topk_idx.data_ptr<int64_t>(),
-        recv_topk_weights_ptr, recv_src_metadata.data_ptr<int>(),
-        channel_linked_list.has_value() ? channel_linked_list->data_ptr<int>()
-                                        : nullptr,
-        num_recv_tokens, num_max_tokens_per_rank, hidden,
-        static_cast<int>(x.element_size()), num_sf_packs, recv_sf_token_stride,
-        recv_sf_hidden_stride, num_experts, num_topk, num_sms, num_smem_bytes,
+        recv_x, recv_x_scales, recv_topk_idx, recv_topk_weights,
+        recv_src_metadata, channel_linked_list, num_recv_tokens,
+        num_max_tokens_per_rank, hidden, x_element_size, num_sf_packs,
+        recv_sf_token_stride, recv_sf_hidden_stride, num_experts, num_topk,
+        num_sms, physical_num_sms_, num_smem_bytes,
         use_hybrid ? hybrid_channels : num_channels, do_expand, cached_mode,
-        launch_ctx, psum_num_recv_tokens_per_scaleup_rank.data_ptr<int>(),
-        epilogue_psum_num_recv_tokens_per_expert.data_ptr<int>(),
-        launch_stream.stream());
-
-    if (do_cpu_sync || !async_with_compute_stream) {
-        stream_wait(compute_stream, launch_stream);
-    }
-    std::optional<EventHandle> event = std::nullopt;
-    if (async_with_compute_stream) {
-        event = EventHandle(launch_stream);
-    }
-
-    std::vector<int> num_recv_tokens_per_expert_list;
-    int actual_num_recv_tokens = num_recv_tokens;
-    int actual_num_output_tokens = num_recv_tokens;
-    if (do_cpu_sync) {
-        auto scaleup_psum_cpu = psum_num_recv_tokens_per_scaleup_rank.cpu();
-        auto expert_psum_cpu = psum_num_recv_tokens_per_expert.cpu();
-        const auto* scaleup_psum = scaleup_psum_cpu.data_ptr<int>();
-        const auto* expert_psum = expert_psum_cpu.data_ptr<int>();
-        actual_num_recv_tokens = scaleup_psum[topology_.num_scaleup_ranks - 1];
-        EP_HOST_ASSERT(actual_num_recv_tokens >= 0 &&
-                       actual_num_recv_tokens <= num_recv_tokens);
-        actual_num_output_tokens = actual_num_recv_tokens;
-
-        num_recv_tokens_per_expert_list.reserve(num_local_experts);
-        const auto align_count = [expert_alignment](int value) {
-            return ((value + expert_alignment - 1) / expert_alignment) *
-                   expert_alignment;
-        };
-        if (do_expand) {
-            int previous_psum = 0;
-            for (int i = 0; i < num_local_experts; ++i) {
-                const int count = expert_psum[i] - align_count(previous_psum);
-                EP_HOST_ASSERT(count >= 0);
-                num_recv_tokens_per_expert_list.push_back(count);
-                previous_psum = expert_psum[i];
-            }
-            actual_num_output_tokens =
-                num_local_experts == 0 ? 0 : expert_psum[num_local_experts - 1];
-        } else {
-            for (int i = 0; i < num_local_experts; ++i) {
-                const int count = expert_psum[i + 1] - expert_psum[i];
-                EP_HOST_ASSERT(count >= 0);
-                num_recv_tokens_per_expert_list.push_back(count);
-            }
-        }
-        EP_HOST_ASSERT(actual_num_output_tokens >= 0 &&
-                       actual_num_output_tokens <= recv_x.size(0));
+        launch_ctx, psum_num_recv_tokens_per_scaleup_rank,
+        epilogue_psum_num_recv_tokens_per_expert, launch_stream);
 
-        recv_x = recv_x.slice(0, 0, actual_num_output_tokens);
-        if (recv_x_scales.has_value()) {
-            recv_x_scales =
-                recv_x_scales->slice(0, 0, actual_num_output_tokens);
-        }
-        recv_topk_idx = recv_topk_idx.slice(0, 0, actual_num_recv_tokens);
-        if (recv_topk_weights.has_value()) {
-            recv_topk_weights =
-                recv_topk_weights->slice(0, 0, actual_num_output_tokens);
-        }
-        recv_src_metadata =
-            recv_src_metadata.slice(0, 0, actual_num_recv_tokens);
-    }
-
-    ElasticNativeHandle handle;
-    handle.do_expand = do_expand;
-    handle.num_experts = num_experts;
-    handle.expert_alignment = expert_alignment;
-    handle.num_max_tokens_per_rank = num_max_tokens_per_rank;
-    handle.num_sms = num_sms;
-    handle.topk_idx = cached_mode ? cached_handle->topk_idx : topk_idx.clone();
-    handle.psum_num_recv_tokens_per_expert =
-        handle_psum_num_recv_tokens_per_expert;
-    handle.psum_num_recv_tokens_per_scaleup_rank =
-        psum_num_recv_tokens_per_scaleup_rank;
-    handle.recv_src_metadata = recv_src_metadata;
-    handle.recv_layout_range = torch::empty(
-        {0}, torch::TensorOptions().dtype(torch::kInt64).device(x.device()));
-    handle.dst_buffer_slot_idx = dst_buffer_slot_idx;
-    handle.token_metadata_at_forward = token_metadata_at_forward;
-    handle.channel_linked_list = channel_linked_list;
-    handle.num_recv_tokens_per_expert_list = num_recv_tokens_per_expert_list;
-
-    ElasticDispatchOutput output;
-    output.recv_x = recv_x;
-    output.recv_x_scales = recv_x_scales;
-    output.recv_topk_idx = recv_topk_idx;
-    output.recv_topk_weights = recv_topk_weights;
-    output.handle = handle;
-    output.event = event;
-    return output;
-}
-
-ElasticCombineOutput MooncakeElasticBuffer::combine(
-    const torch::Tensor& x, const ElasticNativeHandle& handle,
-    const std::optional<torch::Tensor>& topk_weights,
-    torch::Tensor& active_ranks, int num_sms, bool async_with_compute_stream,
-    const std::optional<torch::Tensor>& out) {
-    EP_HOST_ASSERT(x.dim() == 2 && x.is_contiguous());
-    EP_HOST_ASSERT(x.scalar_type() == torch::kBFloat16);
-    torch::Tensor weights = topk_weights.value_or(torch::Tensor());
-    if (!weights.defined()) {
-        weights = torch::ones(
-            handle.topk_idx.sizes(),
-            torch::TensorOptions().dtype(torch::kFloat32).device(x.device()));
-    }
-    const int hidden = static_cast<int>(x.size(1));
-    const int num_topk = static_cast<int>(handle.topk_idx.size(1));
-    const int num_combined_tokens = static_cast<int>(handle.topk_idx.size(0));
-    const int num_smem_bytes = device_smem_bytes();
+    (void)active_ranks;
+    (void)num_local_experts;
+    (void)hybrid_max_tokens_per_channel;
+    if (!async_with_compute_stream) {
+        stream_wait(compute_stream_raw, launch_stream);
+        return std::nullopt;
+    }
+    return EventHandle(reinterpret_cast<uint64_t>(launch_stream),
+                       deterministic_rank_count_buffer);
+}
+
+std::optional<EventHandle> MooncakeElasticBuffer::combine(
+    uint64_t x_ptr, int num_input_tokens, int hidden, uint64_t topk_idx_ptr,
+    int num_combined_tokens, int num_topk, uint64_t topk_weights_ptr,
+    uint64_t psum_num_recv_tokens_per_scaleup_rank_ptr,
+    uint64_t recv_src_metadata_ptr, uint64_t token_metadata_at_forward_ptr,
+    uint64_t channel_linked_list_ptr, uint64_t active_ranks_ptr,
+    int num_experts, int num_max_tokens_per_rank, bool do_expand, int num_sms,
+    bool async_with_compute_stream, uint64_t compute_stream_ptr,
+    uint64_t combined_x_ptr) {
+    EP_HOST_ASSERT(x_ptr != 0 && topk_idx_ptr != 0 && topk_weights_ptr != 0);
+    EP_HOST_ASSERT(psum_num_recv_tokens_per_scaleup_rank_ptr != 0);
+    EP_HOST_ASSERT(recv_src_metadata_ptr != 0 && active_ranks_ptr != 0);
+    EP_HOST_ASSERT(combined_x_ptr != 0);
+    void* x = reinterpret_cast<void*>(x_ptr);
+    auto* topk_idx = reinterpret_cast<int64_t*>(topk_idx_ptr);
+    auto* topk_weights = reinterpret_cast<float*>(topk_weights_ptr);
+    auto* psum_num_recv_tokens_per_scaleup_rank =
+        reinterpret_cast<int*>(psum_num_recv_tokens_per_scaleup_rank_ptr);
+    auto* recv_src_metadata = reinterpret_cast<int*>(recv_src_metadata_ptr);
+    auto* token_metadata_at_forward =
+        reinterpret_cast<int*>(token_metadata_at_forward_ptr);
+    auto* channel_linked_list = reinterpret_cast<int*>(channel_linked_list_ptr);
+    auto* active_ranks = reinterpret_cast<int*>(active_ranks_ptr);
+    void* combined_x = reinterpret_cast<void*>(combined_x_ptr);
+
+    const int num_smem_bytes = device_smem_bytes_;
     const int num_channels = std::max(1, num_sms);
     const bool use_hybrid = topology_.num_scaleout_ranks != 1;
-    const int hybrid_channels = use_hybrid ? hybrid_num_channels(num_sms) : 0;
-    auto compute_stream = at::cuda::getCurrentCUDAStream();
-    auto launch_stream = native_buffer_->comm_stream;
-    stream_wait(launch_stream, compute_stream);
+    const int hybrid_channels_per_sm = using_nccl()
+                                           ? kNcclElasticHybridChannelsPerSm
+                                           : kIbgdaElasticHybridChannelsPerSm;
+    const int hybrid_channels =
+        use_hybrid ? hybrid_num_channels(num_sms, hybrid_channels_per_sm) : 0;
+    auto compute_stream_raw =
+        reinterpret_cast<cudaStream_t>(compute_stream_ptr);
+    auto launch_stream = communication_stream();
+    stream_wait(launch_stream, compute_stream_raw);
     const int64_t timeout_cycles =
         config_.num_gpu_timeout_secs < 0
             ? -1
-            : static_cast<int64_t>(native_buffer_->clock_rate_khz) *
+            : static_cast<int64_t>(clock_rate_khz()) *
                   static_cast<int64_t>(config_.num_gpu_timeout_secs) * 1000;
-    auto launch_ctx = make_launch_context(
-        *native_buffer_, topology_, mapped_host_workspace_, timeout_cycles);
-    auto psum_num_recv_tokens_per_scaleup_rank =
-        handle.psum_num_recv_tokens_per_scaleup_rank;
+    auto launch_ctx = make_launch_context(timeout_cycles);
     void* reduce_buffer = launch_mooncake_elastic_combine(
-        x.data_ptr(), weights.data_ptr<float>(),
-        const_cast<int*>(handle.recv_src_metadata.data_ptr<int>()),
-        psum_num_recv_tokens_per_scaleup_rank.data_ptr<int>(),
-        handle.token_metadata_at_forward.has_value()
-            ? handle.token_metadata_at_forward->data_ptr<int>()
-            : nullptr,
-        handle.channel_linked_list.has_value()
-            ? handle.channel_linked_list->data_ptr<int>()
-            : nullptr,
-        static_cast<int>(x.size(0)), handle.num_max_tokens_per_rank, hidden,
-        handle.num_experts, num_topk, num_sms, num_smem_bytes,
-        use_hybrid ? hybrid_channels : num_channels, handle.do_expand,
-        config_.allow_multiple_reduction, launch_ctx, launch_stream.stream());
-
-    torch::Tensor combined_x =
-        out.has_value()
-            ? out.value()
-            : torch::empty({num_combined_tokens, hidden}, x.options());
+        x, topk_weights, recv_src_metadata,
+        psum_num_recv_tokens_per_scaleup_rank, token_metadata_at_forward,
+        channel_linked_list, num_input_tokens, num_max_tokens_per_rank, hidden,
+        num_experts, num_topk, num_sms, num_smem_bytes,
+        use_hybrid ? hybrid_channels : num_channels, do_expand,
+        config_.allow_multiple_reduction, launch_ctx, launch_stream);
+
     launch_mooncake_elastic_combine_reduce_epilogue(
-        combined_x.data_ptr(), weights.data_ptr<float>(),
-        const_cast<int64_t*>(handle.topk_idx.data_ptr<int64_t>()),
-        num_combined_tokens, handle.num_max_tokens_per_rank, hidden,
-        handle.num_experts, num_topk, reduce_buffer, nullptr, nullptr, num_sms,
-        num_smem_bytes, handle.do_expand, config_.allow_multiple_reduction,
-        launch_ctx, launch_stream.stream());
+        combined_x, topk_weights, topk_idx, num_combined_tokens,
+        num_max_tokens_per_rank, hidden, num_experts, num_topk, reduce_buffer,
+        nullptr, nullptr, num_sms, physical_num_sms_, num_smem_bytes, do_expand,
+        config_.allow_multiple_reduction, launch_ctx, launch_stream);
 
+    (void)active_ranks;
     if (!async_with_compute_stream) {
-        stream_wait(compute_stream, launch_stream);
+        stream_wait(compute_stream_raw, launch_stream);
+        return std::nullopt;
     }
-    std::optional<EventHandle> event = std::nullopt;
-    if (async_with_compute_stream) event = EventHandle(launch_stream);
-    (void)active_ranks;
-
-    ElasticCombineOutput output;
-    output.combined_x = combined_x;
-    output.combined_topk_weights = std::nullopt;
-    output.event = event;
-    return output;
+    return EventHandle(reinterpret_cast<uint64_t>(launch_stream));
 }
 
 ElasticTopology MooncakeElasticBuffer::discover_topology(
@@ -626,6 +1063,8 @@ ElasticTopology MooncakeElasticBuffer::discover_topology(
     }
     topology.scaleout_rank_idx = rank / topology.num_scaleup_ranks;
     topology.scaleup_rank_idx = rank % topology.num_scaleup_ranks;
+    topology.scaleup_lsa =
+        topology.hybrid_enabled || topology.num_rdma_ranks == 1;
     return topology;
 }
 
diff --git a/mooncake-ep/src/mooncake_ep_elastic_kernel.cu b/mooncake-ep/src/mooncake_ep_elastic_kernel.cu
index a5d3e383ff..5f9c795bc9 100644
--- a/mooncake-ep/src/mooncake_ep_elastic_kernel.cu
+++ b/mooncake-ep/src/mooncake_ep_elastic_kernel.cu
@@ -1,8 +1,10 @@
 // clang-format off
 
 #include <algorithm>
+#include <mutex>
 #include <stdexcept>
 #include <string>
+#include <vector>
 
 #include <mooncake_ep_configs.cuh>
 #include <elastic/mooncake_ep_elastic_api.cuh>
@@ -24,13 +26,13 @@ constexpr int kElasticNumEpilogueWarps = 8;
 constexpr int kElasticNumHybridScaleoutWarps = 4;
 constexpr int kElasticNumHybridForwardWarps = 4;
 constexpr int kElasticNumHybridScaleupWarps = 4;
-constexpr int kElasticNumQPs = MAX_QP_COUNT;
 constexpr int64_t kElasticTimeoutCycles = NUM_TIMEOUT_CYCLES;
 
 inline int ceil_div(int x, int y) { return (x + y - 1) / y; }
 
+template <typename Ops>
 inline int hybrid_num_channels(int num_sms) {
-    return num_sms * kElasticNumHybridForwardWarps;
+    return num_sms * Ops::kNumHybridForwardWarps;
 }
 
 inline void* hybrid_combine_reduce_buffer_ptr(void* buffer, int hidden,
@@ -136,7 +138,7 @@ __global__ void musa_elastic_prepare_clear_barrier_kernel(
     int num_scaleup_ranks, int num_experts, int64_t timeout_cycles) {
     const auto layout = elastic::layout::WorkspaceLayout(
         workspace, 1, num_scaleup_ranks, num_experts);
-    const auto gin = elastic::transport::MooncakeGin(
+    const auto gin = elastic::transport::IbgdaOps(
         comm_ctx, 0, 0, 1, 0, rank_idx, num_scaleup_ranks, num_scaleup_ranks);
     constexpr int kTag = elastic::comm::kDeviceBarrierTag;
     const int status =
@@ -223,7 +225,7 @@ __global__ void musa_elastic_publish_counts_kernel(
     const auto layout = elastic::layout::WorkspaceLayout(
         workspace, 1, num_scaleup_ranks, num_experts);
     const int num_experts_per_rank = num_experts / num_scaleup_ranks;
-    const auto gin = elastic::transport::MooncakeGin(
+    const auto gin = elastic::transport::IbgdaOps(
         comm_ctx, 0, 0, 1, 0, rank_idx, num_scaleup_ranks, num_scaleup_ranks);
     const int tid = blockIdx.x * blockDim.x + threadIdx.x;
     const int stride = blockDim.x * gridDim.x;
@@ -362,12 +364,46 @@ void launch_musa_elastic_prepare_dispatch(
 
 #endif
 
-template <typename Kernel, typename... Args>
-void launch_cooperative(Kernel kernel, int num_sms, int num_threads,
-                        int smem_bytes, cudaStream_t stream, Args... args) {
 #ifndef MOONCAKE_EP_USE_MUSA
+struct ConfiguredKernelAttribute {
+    const void* kernel = nullptr;
+    int device_id = -1;
+    int max_dynamic_smem_bytes = 0;
+};
+
+std::mutex configured_kernel_attributes_mutex;
+std::vector<ConfiguredKernelAttribute> configured_kernel_attributes;
+
+template <typename Kernel>
+void configure_kernel_dynamic_smem_once(Kernel kernel, int device_id,
+                                        int smem_bytes) {
+    const auto* kernel_ptr = reinterpret_cast<const void*>(kernel);
+    std::lock_guard<std::mutex> lock(configured_kernel_attributes_mutex);
+    for (auto& entry : configured_kernel_attributes) {
+        if (entry.kernel == kernel_ptr && entry.device_id == device_id) {
+            if (entry.max_dynamic_smem_bytes >= smem_bytes) return;
+            CUDA_CHECK(cudaFuncSetAttribute(
+                kernel, cudaFuncAttributeMaxDynamicSharedMemorySize,
+                smem_bytes));
+            entry.max_dynamic_smem_bytes = smem_bytes;
+            return;
+        }
+    }
     CUDA_CHECK(cudaFuncSetAttribute(
         kernel, cudaFuncAttributeMaxDynamicSharedMemorySize, smem_bytes));
+    configured_kernel_attributes.push_back(
+        {kernel_ptr, device_id, smem_bytes});
+}
+#endif
+
+template <typename Kernel, typename... Args>
+void launch_cooperative(Kernel kernel, int device_id, int num_sms,
+                        int num_threads, int smem_bytes, cudaStream_t stream,
+                        Args... args) {
+#ifndef MOONCAKE_EP_USE_MUSA
+    configure_kernel_dynamic_smem_once(kernel, device_id, smem_bytes);
+#else
+    (void)device_id;
 #endif
 #ifdef MOONCAKE_EP_USE_MUSA
     kernel<<<num_sms, num_threads, smem_bytes, stream>>>(args...);
@@ -411,12 +447,18 @@ void launch_elastic_dispatch_deterministic_prologue(
     constexpr int kNumThreads = kNumWarps * 32;
     const int smem_bytes = (1 + 2 * kNumWarps) * num_scaleup_ranks * sizeof(int);
     (void)num_smem_bytes;
+#ifdef MOONCAKE_EP_USE_MUSA
+    constexpr int device_id = 0;
+#else
+    int device_id = -1;
+    CUDA_CHECK(cudaGetDevice(&device_id));
+#endif
 
 #define LAUNCH_PROLOGUE(HIDDEN, EXPERTS, TOPK, MAXTOK, SMS, RANKS)             \
     do {                                                                       \
         auto kernel = elastic::dispatch_deterministic_prologue_impl<           \
             SMS, kNumWarps, RANKS, MAXTOK, EXPERTS, TOPK>;                    \
-        launch_cooperative(kernel, SMS, kNumThreads, smem_bytes, stream,       \
+        launch_cooperative(kernel, device_id, SMS, kNumThreads, smem_bytes, stream,       \
                            const_cast<int64_t*>(topk_idx), rank_count_buffer,  \
                            dst_buffer_slot_idx, num_tokens,                    \
                            scaleup_rank_idx);                                  \
@@ -451,7 +493,8 @@ void launch_elastic_dispatch_deterministic_prologue(
                                num_scaleup_ranks);
 }
 
-void launch_mooncake_elastic_dispatch(
+template <typename Ops>
+void launch_mooncake_elastic_dispatch_backend(
     void* x, void* sf, int64_t* topk_idx, float* topk_weights,
     int64_t* copied_topk_idx, int* cumulative_local_expert_recv_stats,
     int* psum_num_recv_tokens_per_scaleup_rank,
@@ -461,7 +504,8 @@ void launch_mooncake_elastic_dispatch(
     int sf_token_stride, int sf_hidden_stride, int num_experts, int num_topk,
     int expert_alignment, int num_sms, int num_channels_per_sm,
     int num_smem_bytes, bool cached_mode, bool deterministic,
-    bool do_cpu_sync, const ElasticLaunchContext& ctx, cudaStream_t stream) {
+    bool do_cpu_sync, const ElasticLaunchContext& ctx,
+    const typename Ops::Context& comm_ctx, cudaStream_t stream) {
 #ifdef MOONCAKE_EP_USE_MUSA
     const bool musa_use_prepared_slots = !cached_mode && ctx.num_scaleout_ranks == 1;
 #else
@@ -469,7 +513,7 @@ void launch_mooncake_elastic_dispatch(
 #endif
     const bool effective_cached_mode = cached_mode || musa_use_prepared_slots;
     const int num_notify_warps = effective_cached_mode ? 0 : kElasticNumNotifyWarps;
-    const int num_dispatch_warps = kElasticNumDispatchWarps;
+    const int num_dispatch_warps = Ops::kNumDispatchWarps;
     const int num_threads = (num_notify_warps + num_dispatch_warps) * 32;
     const int smem_bytes = std::max(
         num_smem_bytes,
@@ -477,7 +521,6 @@ void launch_mooncake_elastic_dispatch(
                             ctx.num_scaleup_ranks, num_experts,
                             num_notify_warps, num_dispatch_warps));
     const bool reuse_slot_indices = effective_cached_mode || deterministic;
-    const auto comm_ctx = make_comm_ctx(ctx);
     (void)num_channels_per_sm;
 
 #ifdef MOONCAKE_EP_USE_MUSA
@@ -494,7 +537,7 @@ void launch_mooncake_elastic_dispatch(
     if (ctx.num_scaleout_ranks != 1) {
         const bool hybrid_reuse_slot_indices = cached_mode;
         const int hybrid_dispatch_warps =
-            kElasticNumHybridScaleoutWarps + kElasticNumHybridForwardWarps;
+            Ops::kNumHybridScaleoutWarps + Ops::kNumHybridForwardWarps;
         const int hybrid_threads =
             (num_notify_warps + hybrid_dispatch_warps) * 32;
         const int hybrid_smem_bytes = std::max(
@@ -509,12 +552,12 @@ void launch_mooncake_elastic_dispatch(
             constexpr int kHiddenBytes = (HB);                                 \
             constexpr int kNumSFPacks = (SFP);                                 \
             if (cached_mode) {                                                 \
-                auto kernel = elastic::hybrid_dispatch_impl<                   \
-                    false, true, S, 0, kElasticNumHybridScaleoutWarps,         \
-                    kElasticNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
-                    kNumSFPacks, M, E, K, 1, kElasticNumQPs,                   \
+                auto kernel = elastic::hybrid_dispatch_impl<Ops,               \
+                    false, true, S, 0, Ops::kNumHybridScaleoutWarps,               \
+                    Ops::kNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
+                    kNumSFPacks, M, E, K, 1, Ops::kNumQPs,                   \
                     kElasticTimeoutCycles>;                                    \
-                launch_cooperative(kernel, S, hybrid_threads,                  \
+                launch_cooperative(kernel, ctx.device_id, S, hybrid_threads,                  \
                                    hybrid_smem_bytes, stream, x,               \
                                    static_cast<sf_pack_t*>(sf), topk_idx,      \
                                    topk_weights, copied_topk_idx,              \
@@ -529,13 +572,13 @@ void launch_mooncake_elastic_dispatch(
                                    ctx.scaleout_rank_idx,                      \
                                    ctx.scaleup_rank_idx);                      \
             } else if (hybrid_reuse_slot_indices) {                            \
-                auto kernel = elastic::hybrid_dispatch_impl<                   \
+                auto kernel = elastic::hybrid_dispatch_impl<Ops,               \
                     false, true, S, kElasticNumNotifyWarps,                    \
-                    kElasticNumHybridScaleoutWarps,                            \
-                    kElasticNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
-                    kNumSFPacks, M, E, K, 1, kElasticNumQPs,                   \
+                    Ops::kNumHybridScaleoutWarps,                              \
+                    Ops::kNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
+                    kNumSFPacks, M, E, K, 1, Ops::kNumQPs,                   \
                     kElasticTimeoutCycles>;                                    \
-                launch_cooperative(kernel, S, hybrid_threads,                  \
+                launch_cooperative(kernel, ctx.device_id, S, hybrid_threads,                  \
                                    hybrid_smem_bytes, stream, x,               \
                                    static_cast<sf_pack_t*>(sf), topk_idx,      \
                                    topk_weights, copied_topk_idx,              \
@@ -550,13 +593,13 @@ void launch_mooncake_elastic_dispatch(
                                    ctx.scaleout_rank_idx,                      \
                                    ctx.scaleup_rank_idx);                      \
             } else {                                                           \
-                auto kernel = elastic::hybrid_dispatch_impl<                   \
+                auto kernel = elastic::hybrid_dispatch_impl<Ops,               \
                     false, false, S, kElasticNumNotifyWarps,                   \
-                    kElasticNumHybridScaleoutWarps,                            \
-                    kElasticNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
-                    kNumSFPacks, M, E, K, 1, kElasticNumQPs,                   \
+                    Ops::kNumHybridScaleoutWarps,                              \
+                    Ops::kNumHybridForwardWarps, SO, SU, kHiddenBytes,       \
+                    kNumSFPacks, M, E, K, 1, Ops::kNumQPs,                   \
                     kElasticTimeoutCycles>;                                    \
-                launch_cooperative(kernel, S, hybrid_threads,                  \
+                launch_cooperative(kernel, ctx.device_id, S, hybrid_threads,                  \
                                    hybrid_smem_bytes, stream, x,               \
                                    static_cast<sf_pack_t*>(sf), topk_idx,      \
                                    topk_weights, copied_topk_idx,              \
@@ -590,7 +633,8 @@ void launch_mooncake_elastic_dispatch(
 
 #define TRY_HYBRID_DISPATCH_SHAPE(H, E, K, M, S)                               \
         TRY_HYBRID_DISPATCH(H, E, K, M, S, 2, 4);                              \
-        TRY_HYBRID_DISPATCH(H, E, K, M, S, 2, 8)
+        TRY_HYBRID_DISPATCH(H, E, K, M, S, 2, 8);                              \
+        TRY_HYBRID_DISPATCH(H, E, K, M, S, 4, 4)
 
         TRY_HYBRID_DISPATCH_SHAPE(4096, 256, 8, 128, 24);
 
@@ -606,11 +650,11 @@ void launch_mooncake_elastic_dispatch(
         constexpr int kHiddenBytes = (HB);                                     \
         constexpr int kNumSFPacks = (SFP);                                     \
         if (effective_cached_mode) {                                           \
-            auto kernel = elastic::dispatch_impl<                              \
-                true, false, true, S, 0, kElasticNumDispatchWarps, R,          \
-                kHiddenBytes, kNumSFPacks, M, E, K, 1, kElasticNumQPs,         \
+            auto kernel = elastic::dispatch_impl<Ops,                          \
+                true, false, true, S, 0, Ops::kNumDispatchWarps, R,          \
+                kHiddenBytes, kNumSFPacks, M, E, K, 1, Ops::kNumQPs,         \
                 kElasticTimeoutCycles>;                                        \
-            launch_cooperative(kernel, S, num_threads, smem_bytes, stream, x,  \
+            launch_cooperative(kernel, ctx.device_id, S, num_threads, smem_bytes, stream, x,  \
                                static_cast<sf_pack_t*>(sf), topk_idx,          \
                                topk_weights, copied_topk_idx,                  \
                                cumulative_local_expert_recv_stats,             \
@@ -621,11 +665,11 @@ void launch_mooncake_elastic_dispatch(
                                ctx.workspace, ctx.mapped_host_workspace,       \
                                ctx.scaleup_rank_idx);                          \
         } else if (reuse_slot_indices) {                                       \
-            auto kernel = elastic::dispatch_impl<                              \
+            auto kernel = elastic::dispatch_impl<Ops,                          \
                 true, false, true, S, kElasticNumNotifyWarps,                  \
-                kElasticNumDispatchWarps, R, kHiddenBytes, kNumSFPacks, M, E, K, 1, \
-                kElasticNumQPs, kElasticTimeoutCycles>;                       \
-            launch_cooperative(kernel, S, num_threads, smem_bytes, stream, x,  \
+                Ops::kNumDispatchWarps, R, kHiddenBytes, kNumSFPacks, M, E, K, 1, \
+                Ops::kNumQPs, kElasticTimeoutCycles>;                       \
+            launch_cooperative(kernel, ctx.device_id, S, num_threads, smem_bytes, stream, x,  \
                                static_cast<sf_pack_t*>(sf), topk_idx,          \
                                topk_weights, copied_topk_idx,                  \
                                cumulative_local_expert_recv_stats,             \
@@ -636,11 +680,11 @@ void launch_mooncake_elastic_dispatch(
                                ctx.workspace, ctx.mapped_host_workspace,       \
                                ctx.scaleup_rank_idx);                          \
         } else {                                                               \
-            auto kernel = elastic::dispatch_impl<                              \
+            auto kernel = elastic::dispatch_impl<Ops,                          \
                 true, false, false, S, kElasticNumNotifyWarps,                 \
-                kElasticNumDispatchWarps, R, kHiddenBytes, kNumSFPacks, M, E, K, 1, \
-                kElasticNumQPs, kElasticTimeoutCycles>;                       \
-            launch_cooperative(kernel, S, num_threads, smem_bytes, stream, x,  \
+                Ops::kNumDispatchWarps, R, kHiddenBytes, kNumSFPacks, M, E, K, 1, \
+                Ops::kNumQPs, kElasticTimeoutCycles>;                       \
+            launch_cooperative(kernel, ctx.device_id, S, num_threads, smem_bytes, stream, x,  \
                                static_cast<sf_pack_t*>(sf), topk_idx,          \
                                topk_weights, copied_topk_idx,                  \
                                cumulative_local_expert_recv_stats,             \
@@ -684,20 +728,64 @@ void launch_mooncake_elastic_dispatch(
                                ctx.num_scaleup_ranks);
 }
 
-void launch_mooncake_elastic_dispatch_copy_epilogue(
+void launch_mooncake_elastic_dispatch(
+    void* x, void* sf, int64_t* topk_idx, float* topk_weights,
+    int64_t* copied_topk_idx, int* cumulative_local_expert_recv_stats,
+    int* psum_num_recv_tokens_per_scaleup_rank,
+    int* psum_num_recv_tokens_per_expert, int* dst_buffer_slot_idx,
+    int* token_metadata_at_forward, int num_tokens,
+    int num_max_tokens_per_rank, int hidden, int elem_size, int num_sf_packs,
+    int sf_token_stride, int sf_hidden_stride, int num_experts, int num_topk,
+    int expert_alignment, int num_sms, int num_channels_per_sm,
+    int num_smem_bytes, bool cached_mode, bool deterministic,
+    bool do_cpu_sync, const ElasticLaunchContext& ctx, cudaStream_t stream) {
+#ifdef USE_NCCL_DEVICE
+    if (ctx.backend == ElasticTransportBackend::kNccl) {
+        launch_mooncake_elastic_dispatch_backend<elastic::transport::NcclOps>(
+            x, sf, topk_idx, topk_weights, copied_topk_idx,
+            cumulative_local_expert_recv_stats,
+            psum_num_recv_tokens_per_scaleup_rank,
+            psum_num_recv_tokens_per_expert, dst_buffer_slot_idx,
+            token_metadata_at_forward, num_tokens, num_max_tokens_per_rank,
+            hidden, elem_size, num_sf_packs, sf_token_stride, sf_hidden_stride,
+            num_experts, num_topk, expert_alignment, num_sms,
+            num_channels_per_sm, num_smem_bytes, cached_mode, deterministic,
+            do_cpu_sync, ctx, ctx.nccl, stream);
+        return;
+    }
+#endif
+    if (ctx.backend != ElasticTransportBackend::kIbgda)
+        throw std::invalid_argument(
+            "Mooncake EP was built without NCCL device backend support");
+    const auto comm_ctx = make_comm_ctx(ctx);
+    launch_mooncake_elastic_dispatch_backend<elastic::transport::IbgdaOps>(
+        x, sf, topk_idx, topk_weights, copied_topk_idx,
+        cumulative_local_expert_recv_stats,
+        psum_num_recv_tokens_per_scaleup_rank,
+        psum_num_recv_tokens_per_expert, dst_buffer_slot_idx,
+        token_metadata_at_forward, num_tokens, num_max_tokens_per_rank, hidden,
+        elem_size, num_sf_packs, sf_token_stride, sf_hidden_stride,
+        num_experts, num_topk, expert_alignment, num_sms, num_channels_per_sm,
+        num_smem_bytes, cached_mode, deterministic, do_cpu_sync, ctx, comm_ctx,
+        stream);
+}
+
+template <int kNumEpilogueWarps>
+void launch_mooncake_elastic_dispatch_copy_epilogue_backend(
     void* recv_x, void* recv_sf, int64_t* recv_topk_idx,
     float* recv_topk_weights, int* recv_src_metadata,
     int* channel_linked_list, int num_recv_tokens, int num_max_tokens_per_rank,
     int hidden, int elem_size, int num_sf_packs, int recv_sf_token_stride,
     int recv_sf_hidden_stride, int num_experts, int num_topk, int num_sms,
-    int num_smem_bytes, int num_channels, bool do_expand, bool cached_mode,
+    int num_epilogue_sms, int num_smem_bytes, int num_channels, bool do_expand,
+    bool cached_mode,
     const ElasticLaunchContext& ctx, int* psum_num_recv_tokens_per_scaleup_rank,
     int* psum_num_recv_tokens_per_expert, cudaStream_t stream) {
-    const int num_threads = kElasticNumEpilogueWarps * 32;
+    const int num_threads = kNumEpilogueWarps * 32;
     const int smem_bytes = std::max(
         num_smem_bytes,
         dispatch_epilogue_smem_bytes(hidden, elem_size, num_sf_packs, num_topk,
-                                     kElasticNumEpilogueWarps));
+                                     kNumEpilogueWarps));
 
 #ifndef MOONCAKE_EP_USE_MUSA
     if (ctx.num_scaleout_ranks != 1) {
@@ -707,16 +795,17 @@ void launch_mooncake_elastic_dispatch_copy_epilogue(
             constexpr int kNumSFPacks = (SFP);                                 \
             auto kernel = do_expand ?                                          \
                 elastic::dispatch_copy_epilogue_impl<                          \
-                    true, false, S, C, kElasticNumEpilogueWarps, SO, SU,       \
+                    true, false, 0, C, kNumEpilogueWarps, SO, SU,       \
                     kHiddenBytes, kNumSFPacks, M, E, K> :                      \
                 (cached_mode ?                                                 \
                     elastic::dispatch_copy_epilogue_impl<                      \
-                        false, true, S, C, kElasticNumEpilogueWarps, SO, SU,   \
+                        false, true, 0, C, kNumEpilogueWarps, SO, SU,   \
                         kHiddenBytes, kNumSFPacks, M, E, K> :                  \
                     elastic::dispatch_copy_epilogue_impl<                      \
-                        false, false, S, C, kElasticNumEpilogueWarps, SO, SU,  \
+                        false, false, 0, C, kNumEpilogueWarps, SO, SU,  \
                         kHiddenBytes, kNumSFPacks, M, E, K>);                  \
-            launch_cooperative(kernel, S, num_threads, smem_bytes, stream,     \
+            launch_cooperative(kernel, ctx.device_id, num_epilogue_sms, num_threads,          \
+                               smem_bytes, stream,                               \
                                ctx.buffer, ctx.workspace,                      \
                                psum_num_recv_tokens_per_scaleup_rank,          \
                                psum_num_recv_tokens_per_expert, recv_x,        \
@@ -728,27 +817,31 @@ void launch_mooncake_elastic_dispatch_copy_epilogue(
                                ctx.scaleup_rank_idx);                          \
         } while (false)
 
-#define TRY_HYBRID_DISPATCH_EPILOGUE_TYPED(H, E, K, M, S, SO, SU, EL, SFP)     \
+#define TRY_HYBRID_DISPATCH_EPILOGUE_TYPED(H, E, K, M, S, SO, SU, EL, SFP, CPS) \
         if (hidden == H && num_experts == E && num_topk == K &&                \
             num_max_tokens_per_rank == M && num_sms == S &&                   \
             ctx.num_scaleout_ranks == SO && ctx.num_scaleup_ranks == SU &&     \
             elem_size == EL && num_sf_packs == SFP &&                          \
-            num_channels == hybrid_num_channels(S)) {                          \
+            num_channels == (S) * (CPS)) {                                     \
             LAUNCH_HYBRID_DISPATCH_EPILOGUE((H) * (EL), SFP, E, K, M, S, SO, SU, \
-                                            (S) * kElasticNumHybridForwardWarps); \
+                                            (S) * (CPS));                       \
             return;                                                            \
         }
 
-#define TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, SO, SU)                    \
+#define TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, SO, SU, CPS)               \
         TRY_HYBRID_DISPATCH_EPILOGUE_TYPED(H, E, K, M, S, SO, SU,              \
-                                           static_cast<int>(sizeof(nv_bfloat16)), 0); \
-        TRY_HYBRID_DISPATCH_EPILOGUE_TYPED(H, E, K, M, S, SO, SU, 1, (H) / 128)
+                                           static_cast<int>(sizeof(nv_bfloat16)), 0, CPS); \
+        TRY_HYBRID_DISPATCH_EPILOGUE_TYPED(H, E, K, M, S, SO, SU, 1, (H) / 128, CPS)
 
-#define TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE(H, E, K, M, S)                      \
-        TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, 2, 4);                     \
-        TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, 2, 8)
+#define TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE(H, E, K, M, S, CPS)                 \
+        TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, 2, 4, CPS);                \
+        TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, 2, 8, CPS);                \
+        TRY_HYBRID_DISPATCH_EPILOGUE(H, E, K, M, S, 4, 4, CPS)
 
-        TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE(4096, 256, 8, 128, 24);
+#ifdef USE_NCCL_DEVICE
+        TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE(4096, 256, 8, 128, 24, 8);
+#endif
+        TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE(4096, 256, 8, 128, 24, 4);
 
 #undef TRY_HYBRID_DISPATCH_EPILOGUE_SHAPE
 #undef TRY_HYBRID_DISPATCH_EPILOGUE
@@ -763,16 +856,17 @@ void launch_mooncake_elastic_dispatch_copy_epilogue(
         constexpr int kNumSFPacks = (SFP);                                     \
         auto kernel = do_expand ?                                              \
             elastic::dispatch_copy_epilogue_impl<                              \
-                true, false, S, 1, kElasticNumEpilogueWarps, 1, R,             \
+                true, false, 0, 1, kNumEpilogueWarps, 1, R,             \
                 kHiddenBytes, kNumSFPacks, M, E, K> :                          \
             (cached_mode ?                                                     \
                 elastic::dispatch_copy_epilogue_impl<                          \
-                    false, true, S, 1, kElasticNumEpilogueWarps, 1, R,         \
+                    false, true, 0, 1, kNumEpilogueWarps, 1, R,         \
                     kHiddenBytes, kNumSFPacks, M, E, K> :                      \
                 elastic::dispatch_copy_epilogue_impl<                          \
-                    false, false, S, 1, kElasticNumEpilogueWarps, 1, R,        \
+                    false, false, 0, 1, kNumEpilogueWarps, 1, R,        \
                     kHiddenBytes, kNumSFPacks, M, E, K>);                      \
-        launch_cooperative(kernel, S, num_threads, smem_bytes, stream,         \
+        launch_cooperative(kernel, ctx.device_id, num_epilogue_sms, num_threads,              \
+                           smem_bytes, stream,                                   \
                            ctx.buffer, ctx.workspace,                          \
                            psum_num_recv_tokens_per_scaleup_rank,              \
                            psum_num_recv_tokens_per_expert, recv_x,            \
@@ -814,25 +908,58 @@ void launch_mooncake_elastic_dispatch_copy_epilogue(
                                ctx.num_scaleup_ranks);
 }
 
-void* launch_mooncake_elastic_combine(
+
+void launch_mooncake_elastic_dispatch_copy_epilogue(
+    void* recv_x, void* recv_sf, int64_t* recv_topk_idx,
+    float* recv_topk_weights, int* recv_src_metadata,
+    int* channel_linked_list, int num_recv_tokens, int num_max_tokens_per_rank,
+    int hidden, int elem_size, int num_sf_packs, int recv_sf_token_stride,
+    int recv_sf_hidden_stride, int num_experts, int num_topk, int num_sms,
+    int num_epilogue_sms, int num_smem_bytes, int num_channels, bool do_expand,
+    bool cached_mode,
+    const ElasticLaunchContext& ctx, int* psum_num_recv_tokens_per_scaleup_rank,
+    int* psum_num_recv_tokens_per_expert, cudaStream_t stream) {
+#define CALL_DISPATCH_EPILOGUE(WARPS)                                          \
+    launch_mooncake_elastic_dispatch_copy_epilogue_backend<WARPS>(             \
+        recv_x, recv_sf, recv_topk_idx, recv_topk_weights, recv_src_metadata,  \
+        channel_linked_list, num_recv_tokens, num_max_tokens_per_rank, hidden, \
+        elem_size, num_sf_packs, recv_sf_token_stride, recv_sf_hidden_stride,  \
+        num_experts, num_topk, num_sms, num_epilogue_sms, num_smem_bytes,      \
+        num_channels,                                                          \
+        do_expand, cached_mode, ctx, psum_num_recv_tokens_per_scaleup_rank,    \
+        psum_num_recv_tokens_per_expert, stream)
+#ifdef USE_NCCL_DEVICE
+    if (ctx.backend == ElasticTransportBackend::kNccl) {
+        CALL_DISPATCH_EPILOGUE(
+            elastic::transport::NcclOps::kNumDispatchEpilogueWarps);
+        return;
+    }
+#endif
+    CALL_DISPATCH_EPILOGUE(
+        elastic::transport::IbgdaOps::kNumDispatchEpilogueWarps);
+#undef CALL_DISPATCH_EPILOGUE
+}
+
+template <typename Ops>
+void* launch_mooncake_elastic_combine_backend(
     void* x, float* topk_weights, int* src_metadata,
     int* psum_num_recv_tokens_per_scaleup_rank,
     int* token_metadata_at_forward, int* channel_linked_list,
     int num_reduced_tokens, int num_max_tokens_per_rank, int hidden,
     int num_experts, int num_topk, int num_sms, int num_smem_bytes,
     int num_channels, bool use_expanded_layout, bool allow_multiple_reduction,
-    const ElasticLaunchContext& ctx, cudaStream_t stream) {
-    const int num_threads = kElasticNumEpilogueWarps * 32;
+    const ElasticLaunchContext& ctx, const typename Ops::Context& comm_ctx,
+    cudaStream_t stream) {
+    const int num_threads = Ops::kNumCombineWarps * 32;
     const int smem_bytes = std::max(
-        num_smem_bytes, combine_smem_bytes(hidden, num_topk, kElasticNumEpilogueWarps));
-    const auto comm_ctx = make_comm_ctx(ctx);
+        num_smem_bytes, combine_smem_bytes(hidden, num_topk, Ops::kNumCombineWarps));
     (void)token_metadata_at_forward;
     (void)channel_linked_list;
 
 #ifndef MOONCAKE_EP_USE_MUSA
     if (ctx.num_scaleout_ranks != 1) {
         const int hybrid_combine_warps =
-            kElasticNumHybridScaleupWarps + kElasticNumHybridForwardWarps;
+            Ops::kNumHybridScaleupWarps + Ops::kNumHybridForwardWarps;
         const int hybrid_threads = hybrid_combine_warps * 32;
         const int hybrid_smem_bytes = std::max(
             num_smem_bytes,
@@ -840,11 +967,11 @@ void* launch_mooncake_elastic_combine(
 
 #define LAUNCH_HYBRID_COMBINE(H, E, K, M, S, SO, SU)                           \
         do {                                                                   \
-            auto kernel = elastic::hybrid_combine_impl<                        \
-                false, true, S, kElasticNumHybridScaleupWarps,                 \
-                kElasticNumHybridForwardWarps, SO, SU, H, M, E, K,             \
-                kElasticNumQPs, kElasticTimeoutCycles>;                        \
-            launch_cooperative(kernel, S, hybrid_threads, hybrid_smem_bytes,   \
+            auto kernel = elastic::hybrid_combine_impl<Ops,                    \
+                false, true, S, Ops::kNumHybridScaleupWarps,                       \
+                Ops::kNumHybridForwardWarps, SO, SU, H, M, E, K,             \
+                Ops::kNumQPs, kElasticTimeoutCycles>;                        \
+            launch_cooperative(kernel, ctx.device_id, S, hybrid_threads, hybrid_smem_bytes,   \
                                stream, static_cast<nv_bfloat16*>(x),           \
                                topk_weights, src_metadata,                     \
                                psum_num_recv_tokens_per_scaleup_rank,          \
@@ -859,7 +986,7 @@ void* launch_mooncake_elastic_combine(
             num_max_tokens_per_rank == M && num_sms == S &&                   \
             ctx.num_scaleout_ranks == SO && ctx.num_scaleup_ranks == SU &&     \
             allow_multiple_reduction && !use_expanded_layout &&                \
-            num_channels == hybrid_num_channels(S) &&                          \
+            num_channels == hybrid_num_channels<Ops>(S) &&                     \
             token_metadata_at_forward != nullptr && channel_linked_list != nullptr) { \
             LAUNCH_HYBRID_COMBINE(H, E, K, M, S, SO, SU);                      \
             return hybrid_combine_reduce_buffer_ptr(                            \
@@ -868,7 +995,8 @@ void* launch_mooncake_elastic_combine(
 
 #define TRY_HYBRID_COMBINE_SHAPE(H, E, K, M, S)                                \
         TRY_HYBRID_COMBINE(H, E, K, M, S, 2, 4);                               \
-        TRY_HYBRID_COMBINE(H, E, K, M, S, 2, 8)
+        TRY_HYBRID_COMBINE(H, E, K, M, S, 2, 8);                               \
+        TRY_HYBRID_COMBINE(H, E, K, M, S, 4, 4)
 
         TRY_HYBRID_COMBINE_SHAPE(4096, 256, 8, 128, 24);
 
@@ -882,10 +1010,10 @@ void* launch_mooncake_elastic_combine(
 
 #define LAUNCH_COMBINE(H, E, K, M, S, R)                                       \
     do {                                                                       \
-        auto kernel = elastic::combine_impl<true, false, true, S,              \
-            kElasticNumEpilogueWarps, R, H, M, E, K, kElasticNumQPs,           \
+        auto kernel = elastic::combine_impl<Ops, true, false, true, S,         \
+            Ops::kNumCombineWarps, R, H, M, E, K, Ops::kNumQPs,           \
             kElasticTimeoutCycles>;                                           \
-        launch_cooperative(kernel, S, num_threads, smem_bytes, stream,         \
+        launch_cooperative(kernel, ctx.device_id, S, num_threads, smem_bytes, stream,         \
                            static_cast<nv_bfloat16*>(x), topk_weights,         \
                            src_metadata, psum_num_recv_tokens_per_scaleup_rank,\
                            comm_ctx, ctx.buffer, ctx.workspace,                \
@@ -916,22 +1044,58 @@ void* launch_mooncake_elastic_combine(
                                ctx.num_scaleup_ranks);
 }
 
-void launch_mooncake_elastic_combine_reduce_epilogue(
+void* launch_mooncake_elastic_combine(
+    void* x, float* topk_weights, int* src_metadata,
+    int* psum_num_recv_tokens_per_scaleup_rank,
+    int* token_metadata_at_forward, int* channel_linked_list,
+    int num_reduced_tokens, int num_max_tokens_per_rank, int hidden,
+    int num_experts, int num_topk, int num_sms, int num_smem_bytes,
+    int num_channels, bool use_expanded_layout, bool allow_multiple_reduction,
+    const ElasticLaunchContext& ctx, cudaStream_t stream) {
+#ifdef USE_NCCL_DEVICE
+    if (ctx.backend == ElasticTransportBackend::kNccl) {
+        return launch_mooncake_elastic_combine_backend<
+            elastic::transport::NcclOps>(
+            x, topk_weights, src_metadata,
+            psum_num_recv_tokens_per_scaleup_rank, token_metadata_at_forward,
+            channel_linked_list, num_reduced_tokens,
+            num_max_tokens_per_rank, hidden, num_experts, num_topk, num_sms,
+            num_smem_bytes, num_channels, use_expanded_layout,
+            allow_multiple_reduction, ctx, ctx.nccl, stream);
+    }
+#endif
+    if (ctx.backend != ElasticTransportBackend::kIbgda)
+        throw std::invalid_argument(
+            "Mooncake EP was built without NCCL device backend support");
+    const auto comm_ctx = make_comm_ctx(ctx);
+    return launch_mooncake_elastic_combine_backend<
+        elastic::transport::IbgdaOps>(
+        x, topk_weights, src_metadata,
+        psum_num_recv_tokens_per_scaleup_rank, token_metadata_at_forward,
+        channel_linked_list, num_reduced_tokens, num_max_tokens_per_rank,
+        hidden, num_experts, num_topk, num_sms, num_smem_bytes, num_channels,
+        use_expanded_layout, allow_multiple_reduction, ctx, comm_ctx, stream);
+}
+
+template <int kNumEpilogueWarps>
+void launch_mooncake_elastic_combine_reduce_epilogue_backend(
     void* combined_x, float* combined_topk_weights, int64_t* combined_topk_idx,
     int num_combined_tokens, int num_max_tokens_per_rank, int hidden,
     int num_experts, int num_topk, void* reduce_buffer, void* bias_0,
-    void* bias_1, int num_sms, int num_smem_bytes, bool use_expanded_layout,
+    void* bias_1, int num_sms, int num_epilogue_sms, int num_smem_bytes,
+    bool use_expanded_layout,
     bool allow_multiple_reduction, const ElasticLaunchContext& ctx,
     cudaStream_t stream) {
-    const int num_threads = kElasticNumEpilogueWarps * 32;
+    const int num_threads = kNumEpilogueWarps * 32;
     const int smem_bytes = std::max(
-        num_smem_bytes, combine_epilogue_smem_bytes(hidden, kElasticNumEpilogueWarps));
+        num_smem_bytes, combine_epilogue_smem_bytes(hidden, kNumEpilogueWarps));
 
 #define LAUNCH_COMBINE_EPILOGUE(H, E, K, M, S, SO, SU)                         \
     do {                                                                       \
         auto kernel = elastic::combine_reduce_epilogue_impl<                   \
-            false, true, S, kElasticNumEpilogueWarps, SO, SU, H, M, E, K>;     \
-        launch_cooperative(kernel, S, num_threads, smem_bytes, stream,         \
+            false, true, 0, kNumEpilogueWarps, SO, SU, H, M, E, K>;     \
+        launch_cooperative(kernel, ctx.device_id, num_epilogue_sms, num_threads,              \
+                           smem_bytes, stream,                                   \
                            static_cast<nv_bfloat16*>(combined_x),              \
                            combined_topk_weights, combined_topk_idx,           \
                            reduce_buffer, bias_0, bias_1, num_combined_tokens, \
@@ -956,7 +1120,8 @@ void launch_mooncake_elastic_combine_reduce_epilogue(
 
 #define TRY_HYBRID_COMBINE_EPILOGUE_SHAPE(H, E, K, M, S)                       \
     TRY_COMBINE_EPILOGUE(H, E, K, M, S, 2, 4);                                 \
-    TRY_COMBINE_EPILOGUE(H, E, K, M, S, 2, 8)
+    TRY_COMBINE_EPILOGUE(H, E, K, M, S, 2, 8);                                 \
+    TRY_COMBINE_EPILOGUE(H, E, K, M, S, 4, 4)
 
     TRY_HYBRID_COMBINE_EPILOGUE_SHAPE(4096, 256, 8, 128, 24);
 #endif
@@ -970,4 +1135,32 @@ void launch_mooncake_elastic_combine_reduce_epilogue(
                                ctx.num_scaleup_ranks);
 }
 
+
+void launch_mooncake_elastic_combine_reduce_epilogue(
+    void* combined_x, float* combined_topk_weights, int64_t* combined_topk_idx,
+    int num_combined_tokens, int num_max_tokens_per_rank, int hidden,
+    int num_experts, int num_topk, void* reduce_buffer, void* bias_0,
+    void* bias_1, int num_sms, int num_epilogue_sms, int num_smem_bytes,
+    bool use_expanded_layout,
+    bool allow_multiple_reduction, const ElasticLaunchContext& ctx,
+    cudaStream_t stream) {
+#define CALL_COMBINE_EPILOGUE(WARPS)                                           \
+    launch_mooncake_elastic_combine_reduce_epilogue_backend<WARPS>(            \
+        combined_x, combined_topk_weights, combined_topk_idx,                  \
+        num_combined_tokens, num_max_tokens_per_rank, hidden, num_experts,     \
+        num_topk, reduce_buffer, bias_0, bias_1, num_sms, num_epilogue_sms,    \
+        num_smem_bytes,                                                        \
+        use_expanded_layout, allow_multiple_reduction, ctx, stream)
+#ifdef USE_NCCL_DEVICE
+    if (ctx.backend == ElasticTransportBackend::kNccl) {
+        CALL_COMBINE_EPILOGUE(
+            elastic::transport::NcclOps::kNumCombineEpilogueWarps);
+        return;
+    }
+#endif
+    CALL_COMBINE_EPILOGUE(
+        elastic::transport::IbgdaOps::kNumCombineEpilogueWarps);
+#undef CALL_COMBINE_EPILOGUE
+}
+
 }  // namespace mooncake
diff --git a/mooncake-ep/src/mooncake_ep_kernel.cu b/mooncake-ep/src/mooncake_ep_kernel.cu
index bc96441181..328e6b124b 100644
--- a/mooncake-ep/src/mooncake_ep_kernel.cu
+++ b/mooncake-ep/src/mooncake_ep_kernel.cu
@@ -162,7 +162,7 @@ dispatch(void* packed_recv_x, float* packed_recv_x_scales,
     const auto warp_group_id = warp_id / kNumWarpsPerGroup;
     const auto sub_warp_id = warp_id % kNumWarpsPerGroup;
     const auto responsible_expert_idx = sm_id * kNumWarpGroups + warp_group_id;
-#ifdef MOONCAKE_EP_USE_MACA
+#if defined(MOONCAKE_EP_USE_MUSA) || defined(MOONCAKE_EP_USE_MACA)
     // C500 reports 64-thread hardware warps. Do not split the last hardware
     // warp by assigning only the final 32-thread pseudo-warp to count work.
     // Reserve one full warp group from the data path, but write counts from a
@@ -211,8 +211,8 @@ dispatch(void* packed_recv_x, float* packed_recv_x_scales,
     // There are 2 kinds of execution lanes in this part:
     // 1. Data lanes for FP8 cast and sending top-k tokens.
     // 2. Count lanes for reading `topk_idx` and per-expert token counts.
-    // MACA reserves a full warp group for the count path; CUDA keeps the
-    // original final 32-thread warp behavior.
+    // Non-CUDA backends reserve a full warp group for the count path. This
+    // keeps the final group out of the data path when MUSA uses five groups.
     if (is_data_warp) {
         constexpr int kNumElemsPerRead = sizeof(int4) / EP_BF16_SIZE;
         EP_DEVICE_ASSERT(kHidden % kNumElemsPerRead == 0);
@@ -310,7 +310,8 @@ dispatch(void* packed_recv_x, float* packed_recv_x_scales,
         // Participate in __syncthreads() barriers from data warps.
         // Each token iteration in the send loop above calls
         // __syncthreads() once; the count path must match.
-        for (int token_idx = sm_id; token_idx < num_tokens; token_idx += num_sms) {
+        for (int token_idx = sm_id; token_idx < num_tokens;
+             token_idx += num_sms) {
             __syncthreads();
         }
 #endif
@@ -481,20 +482,26 @@ void dispatch(void* packed_recv_x, float* packed_recv_x_scales,
               int* next_clean_buffer,
               int num_tokens, int hidden, int num_max_dispatch_tokens_per_rank,
               int num_topk, int num_experts, int rank, int num_ranks, bool use_fp8,
-              void* workspace, cudaStream_t stream, int64_t timeout_ticks,
-              int phases, int active_qps_per_rank) {
-    constexpr int kNumMaxTopK = 11;
+              void* workspace, cudaStream_t stream,
+              int64_t timeout_ticks, int phases, int active_qps_per_rank) {
+    constexpr int kNumMaxTopK = 17;
     constexpr int kNumWarpsPerGroup = 4;
+    int num_warp_groups = 8;
 #ifdef MOONCAKE_EP_USE_MUSA
-    // MT S5000 benefits from slightly more CTAs while keeping enough warps for top-k<=11.
-    constexpr int kNumWarpGroups = 5;
-#else
-    constexpr int kNumWarpGroups = 8;
+    cudaDeviceProp device_prop{};
+    int device = 0;
+    CUDA_CHECK(cudaGetDevice(&device));
+    CUDA_CHECK(cudaGetDeviceProperties(&device_prop, device));
+    num_warp_groups = cell_div(num_experts, device_prop.multiProcessorCount);
+    // MUSA keeps four 32-thread pseudo-warps per group. The range is also
+    // constrained by the count group and the maximum supported CTA shape.
+    num_warp_groups = max(3, min(8, num_warp_groups));
 #endif
-    EP_STATIC_ASSERT(kNumMaxTopK + 1 <= kNumWarpGroups * kNumWarpsPerGroup, "Too many top-k selections");
+    EP_HOST_ASSERT(kNumMaxTopK + 1 <= num_warp_groups * kNumWarpsPerGroup &&
+                   "Too many top-k selections");
 
-    const auto num_warps = kNumWarpGroups * kNumWarpsPerGroup;
-    const auto num_sms = cell_div(num_experts, kNumWarpGroups);
+    const auto num_warps = num_warp_groups * kNumWarpsPerGroup;
+    const auto num_sms = max(2, cell_div(num_experts, num_warp_groups));
     EP_HOST_ASSERT(num_topk <= kNumMaxTopK);
 
     // Workspace checks
@@ -502,7 +509,8 @@ void dispatch(void* packed_recv_x, float* packed_recv_x_scales,
     auto atomic_finish_counter_per_expert = atomic_counter_per_expert + num_experts;
     EP_HOST_ASSERT(num_experts * sizeof(int) * 2 <= NUM_WORKSPACE_BYTES);
 
-#define DISPATCH_LAUNCH_CASE(hidden) { \
+#define DISPATCH_LAUNCH_GROUP(hidden, groups) case groups: { \
+constexpr int kNumWarpGroups = groups; \
 auto dispatch_func = use_fp8 ? dispatch<true, kNumWarpGroups, kNumWarpsPerGroup, hidden> : \
                                dispatch<false, kNumWarpGroups, kNumWarpsPerGroup, hidden>; \
 LAUNCH_KERNEL(&cfg, dispatch_func, \
@@ -519,12 +527,24 @@ LAUNCH_KERNEL(&cfg, dispatch_func, \
               atomic_counter_per_expert, atomic_finish_counter_per_expert, \
               next_clean_buffer, \
               num_tokens, num_max_dispatch_tokens_per_rank, \
-              num_topk, num_experts, rank, num_ranks, timeout_ticks, phases, \
-              active_qps_per_rank); } break
+              num_topk, num_experts, rank, num_ranks, \
+              timeout_ticks, phases, active_qps_per_rank); } break
+
+#define DISPATCH_LAUNCH_CASE(hidden) { \
+switch (num_warp_groups) { \
+DISPATCH_LAUNCH_GROUP(hidden, 3); \
+DISPATCH_LAUNCH_GROUP(hidden, 4); \
+DISPATCH_LAUNCH_GROUP(hidden, 5); \
+DISPATCH_LAUNCH_GROUP(hidden, 6); \
+DISPATCH_LAUNCH_GROUP(hidden, 7); \
+DISPATCH_LAUNCH_GROUP(hidden, 8); \
+default: EP_HOST_ASSERT(false && "Unsupported dispatch warp-group count"); \
+} } break
 
     SETUP_LAUNCH_CONFIG(num_sms, num_warps * 32, stream);
     SWITCH_HIDDEN(DISPATCH_LAUNCH_CASE);
 #undef DISPATCH_LAUNCH_CASE
+#undef DISPATCH_LAUNCH_GROUP
 }
 
 template <int kNumWarpGroups, int kNumWarpsPerGroup, int kHidden, int kNumMaxTopk>
@@ -750,7 +770,7 @@ void combine(void* combined_x, int32_t* active_ranks,
              int active_qps_per_rank) {
     constexpr int kNumWarpsPerGroup = 4;
     constexpr int kNumWarpGroups = 8;
-    constexpr int kNumMaxTopk = 11;
+    constexpr int kNumMaxTopk = 17;
 
     const auto num_warps = kNumWarpGroups * kNumWarpsPerGroup;
     const auto num_sms = cell_div(num_experts, kNumWarpGroups);
diff --git a/mooncake-integration/CMakeLists.txt b/mooncake-integration/CMakeLists.txt
index c7fe22818b..caa1d53e55 100644
--- a/mooncake-integration/CMakeLists.txt
+++ b/mooncake-integration/CMakeLists.txt
@@ -1,13 +1,21 @@
 file(GLOB SOURCES "*.cpp")
-include(${CMAKE_CURRENT_LIST_DIR}/../mooncake-common/SetupPython.cmake)
-execute_process(
-  COMMAND ${PYTHON_EXECUTABLE} -c
-          "import sys; print([s for s in sys.path if 'packages' in s][0])"
-  OUTPUT_VARIABLE PYTHON_SYS_PATH)
-string(STRIP ${PYTHON_SYS_PATH} PYTHON_SYS_PATH)
-
-if("${PYTHON_SYS_PATH}" STREQUAL "")
-  message(FATAL_ERROR "Python path is empty! Please check the python env.")
+set(PYTHON_PACKAGE_NAME "mooncake")
+if(SKBUILD)
+  # scikit-build-core sets CMAKE_INSTALL_PREFIX to its private wheel tree. Keep
+  # every Python artifact relative to that prefix.
+  set(MOONCAKE_PYTHON_INSTALL_DIR "${PYTHON_PACKAGE_NAME}")
+else()
+  include(${CMAKE_CURRENT_LIST_DIR}/../mooncake-common/SetupPython.cmake)
+  execute_process(
+    COMMAND ${PYTHON_EXECUTABLE} -c
+            "import sys; print([s for s in sys.path if 'packages' in s][0])"
+    OUTPUT_VARIABLE PYTHON_SYS_PATH)
+  string(STRIP ${PYTHON_SYS_PATH} PYTHON_SYS_PATH)
+
+  if("${PYTHON_SYS_PATH}" STREQUAL "")
+    message(FATAL_ERROR "Python path is empty! Please check the python env.")
+  endif()
+  set(MOONCAKE_PYTHON_INSTALL_DIR "${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME}")
 endif()
 
 if(WITH_STORE)
@@ -21,7 +29,6 @@ if(WITH_STORE)
     "../mooncake-store/include/cachelib_memory_allocator/fake_include")
 endif()
 
-include_directories("/usr/include/jsoncpp")
 include_directories("./")
 include_directories("../mooncake-transfer-engine/include")
 
@@ -39,13 +46,14 @@ execute_process(
 set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
 set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
 
-message("${PYTHON_SYS_PATH}")
-
-set(PYTHON_PACKAGE_NAME "mooncake")
+message(
+  STATUS "Mooncake Python install directory: ${MOONCAKE_PYTHON_INSTALL_DIR}")
 
 if(WITH_TE)
-  pybind11_add_module(engine ${SOURCES} ${CACHE_ALLOCATOR_SOURCES}
-                      transfer_engine/transfer_engine_py.cpp)
+  pybind11_add_module(
+    engine ${SOURCES} ${CACHE_ALLOCATOR_SOURCES}
+    transfer_engine/transfer_engine_py.cpp
+    transfer_engine/shared_segment_py.cpp)
   set_target_properties(engine PROPERTIES INSTALL_RPATH "$ORIGIN")
 
   # Propagate EFA compile definition to engine target
@@ -76,6 +84,28 @@ if(WITH_TE)
     find_package(CUDAToolkit REQUIRED)
     target_link_libraries(engine PRIVATE CUDA::cudart)
   endif()
+
+  if(BUILD_UNIT_TESTS AND USE_TENT)
+    add_test(
+      NAME tent_python_send_probe_test
+      COMMAND
+        ${CMAKE_COMMAND} -E env MC_USE_TENT=1 MOONCAKE_LOCAL_HOSTNAME=127.0.0.1
+        "MC_TENT_CONF={\"transports\":{\"rdma\":{\"enable\":false},\"tcp\":{\"enable\":true},\"gds\":{\"enable\":false},\"shm\":{\"enable\":false}}}"
+        PYTHONPATH=$<TARGET_FILE_DIR:engine>
+        LD_LIBRARY_PATH=$<TARGET_FILE_DIR:transfer_engine>:$<TARGET_FILE_DIR:tent_metrics>:$<TARGET_FILE_DIR:asio_shared>
+        ${Python3_EXECUTABLE}
+        ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_tent_send_probe.py)
+    add_test(
+      NAME tent_python_first_buffer_test
+      COMMAND
+        ${CMAKE_COMMAND} -E env MC_USE_TENT=1 MOONCAKE_LOCAL_HOSTNAME=127.0.0.1
+        "MC_TENT_CONF={\"transports\":{\"rdma\":{\"enable\":false},\"tcp\":{\"enable\":true},\"gds\":{\"enable\":false},\"shm\":{\"enable\":false}}}"
+        PYTHONPATH=$<TARGET_FILE_DIR:engine>
+        LD_LIBRARY_PATH=$<TARGET_FILE_DIR:transfer_engine>:$<TARGET_FILE_DIR:tent_metrics>:$<TARGET_FILE_DIR:asio_shared>
+        ${Python3_EXECUTABLE}
+        ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_tent_first_buffer.py)
+    set_tests_properties(tent_python_first_buffer_test PROPERTIES TIMEOUT 60)
+  endif()
 endif()
 
 set(ALLOCATOR_SO_PATH
@@ -85,13 +115,23 @@ set(UBSHMEM_ALLOCATOR_SO_PATH
     "${CMAKE_BINARY_DIR}/mooncake-transfer-engine/ubshmem-allocator/ubshmem_fabric_allocator.so"
 )
 
-if(USE_MNNVL)
+set(MOONCAKE_HAS_NVLINK_ALLOCATOR OFF)
+if(USE_CUDA
+   OR USE_HIP
+   OR USE_MUSA
+   OR USE_MACA)
+  set(MOONCAKE_HAS_NVLINK_ALLOCATOR ON)
+endif()
+
+if(MOONCAKE_HAS_NVLINK_ALLOCATOR)
   message(
     STATUS
-      "USE_MNNVL is enabled, nvlink_allocator.so will be installed in the Python package"
+      "GPU IPC support is enabled, nvlink_allocator.so will be installed in the Python package"
   )
-  install(FILES "${ALLOCATOR_SO_PATH}"
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(
+    FILES "${ALLOCATOR_SO_PATH}"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
 endif()
 
 if(USE_UBSHMEM)
@@ -99,8 +139,10 @@ if(USE_UBSHMEM)
     STATUS
       "USE_UBSHMEM is enabled, ubshmem_fabric_allocator.so will be installed in the Python package"
   )
-  install(FILES "${UBSHMEM_ALLOCATOR_SO_PATH}"
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(
+    FILES "${UBSHMEM_ALLOCATOR_SO_PATH}"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
 endif()
 
 if(WITH_STORE)
@@ -124,29 +166,35 @@ if(WITH_STORE)
   endif()
 endif()
 
-message("${PYTHON_SYS_PATH}")
-
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/${PYTHON_PACKAGE_NAME}/__init__.py
-     "# Auto-generated by CMake\n")
+if(NOT SKBUILD)
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/${PYTHON_PACKAGE_NAME}/__init__.py
+       "# Auto-generated by CMake\n")
+endif()
 
-if(USE_MNNVL)
+if(MOONCAKE_HAS_NVLINK_ALLOCATOR)
   message(STATUS "allocator.py will be installed in the Python package")
-  install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/allocator.py"
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(
+    FILES "${CMAKE_CURRENT_SOURCE_DIR}/allocator.py"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
 endif()
 
 if(USE_UBSHMEM)
   message(
     STATUS "allocator_ascend_npu.py will be installed in the Python package")
-  install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/allocator_ascend_npu.py"
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(
+    FILES "${CMAKE_CURRENT_SOURCE_DIR}/allocator_ascend_npu.py"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
 endif()
 
-if(USE_MNNVL OR USE_UBSHMEM)
+if(MOONCAKE_HAS_NVLINK_ALLOCATOR OR USE_UBSHMEM)
   message(
     STATUS "fabric_allocator_utils.py will be installed in the Python package")
-  install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/fabric_allocator_utils.py"
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(
+    FILES "${CMAKE_CURRENT_SOURCE_DIR}/fabric_allocator_utils.py"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
 endif()
 
 if(USE_INTRA_NVLINK)
@@ -154,76 +202,169 @@ if(USE_INTRA_NVLINK)
     STATUS "USE_INTRA_NVLINK is enabled, IntraNode nvlink is now activated")
 endif()
 
-install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/store/async_store.py"
-        DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
-
-# Install Python scripts from mooncake - wheel / mooncake / directory
 install(
-  FILES
-    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/http_metadata_server.py"
-    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/cli_bench.py"
-    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/transfer_engine_topology_dump.py"
-    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_connector_v1.py"
-    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/vllm_v1_proxy_server.py"
-  DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  FILES "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/async_store.py"
+  DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+  COMPONENT python)
 
-if(WITH_STORE)
+if(WITH_TE)
   install(
-    FILES
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_store_service.py"
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_config.py"
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/cli.py"
-    DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+    FILES "${CMAKE_CURRENT_SOURCE_DIR}/shared_segment.py"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
+endif()
 
-  if(USE_NOF)
+# scikit-build-core consumes these legacy modules through python/CMakeLists.txt.
+# Retain the direct CMake install surface only outside PEP 517 builds.
+if(NOT SKBUILD)
+  install(
+    FILES
+      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/http_metadata_server.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/_launcher.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/cli_bench.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/transfer_engine_topology_dump.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_connector_v1.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/vllm_v1_proxy_server.py"
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR})
+
+  if(WITH_STORE)
     install(
       FILES
-        "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_ssd_register.py"
-        "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_ssd_unregister.py"
-        "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/spdk_tgt_create.py"
-      DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+        "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_store_service.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/mooncake_config.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/cli.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/cli_client.py"
+      DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR})
+
+    if(USE_NOF)
+      install(
+        FILES
+          "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/_administration.py"
+          "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/mooncake_ssd_register.py"
+          "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/mooncake_ssd_unregister.py"
+          "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/spdk_tgt_create.py"
+        DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR})
+    endif()
   endif()
-endif()
 
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${PYTHON_PACKAGE_NAME}/
-        DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${PYTHON_PACKAGE_NAME}/
+          DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR})
 
-install(
-  CODE "
-        execute_process(COMMAND chmod 767 \"${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME}\")
-        execute_process(COMMAND chmod 766 \"${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME}/__init__.py\")
-    ")
+  install(
+    CODE "
+          execute_process(COMMAND chmod 767 \"${MOONCAKE_PYTHON_INSTALL_DIR}\")
+          execute_process(COMMAND chmod 766 \"${MOONCAKE_PYTHON_INSTALL_DIR}/__init__.py\")
+      ")
+endif()
 
 if(WITH_STORE)
-  install(TARGETS store DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(TARGETS store LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+                                COMPONENT python)
 endif()
 
 if(WITH_TE)
-  install(TARGETS engine DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
-  install(TARGETS asio_shared
-          DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+  install(TARGETS engine asio_shared
+          LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  # Co-locate libtent_metrics.so with the python C extensions so engine.so and
+  # store.so resolve it via $ORIGIN RPATH. The shared TentMetrics singleton
+  # must be loadable wherever the extensions are installed; otherwise
+  # `import mooncake.engine` / `mooncake.store` fails with a missing library.
+  if(TARGET tent_metrics)
+    install(TARGETS tent_metrics
+            LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+            COMPONENT python)
+  endif()
 endif()
 
 if(WITH_EP)
+  install(TARGETS _ep LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+                              COMPONENT python)
   install(
     DIRECTORY "${EP_PG_STAGING_DIR}/"
-    DESTINATION "${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME}"
+    DESTINATION "${MOONCAKE_PYTHON_INSTALL_DIR}"
+    COMPONENT python
     FILES_MATCHING
     PATTERN "*.so")
   install(
     FILES
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/ep.py"
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_ep_buffer.py"
-      "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/mooncake_elastic_buffer.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/ep.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/mooncake_ep_buffer.py"
+      "${CMAKE_CURRENT_SOURCE_DIR}/../python/mooncake/mooncake_elastic_buffer.py"
       "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/pg.py"
-    DESTINATION ${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME})
+    DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+    COMPONENT python)
   # ep.so / pg.so link against engine.so by that exact bare name. Create a
   # engine.so -> engine<EXT_SUFFIX> symlink so they can find it.
+  if(SKBUILD)
+    set(_mooncake_engine_compat_path
+        "${CMAKE_INSTALL_PREFIX}/${MOONCAKE_PYTHON_INSTALL_DIR}/engine.so")
+  else()
+    set(_mooncake_engine_compat_path "${MOONCAKE_PYTHON_INSTALL_DIR}/engine.so")
+  endif()
   install(
     CODE "
         execute_process(COMMAND ${CMAKE_COMMAND} -E create_symlink
             \"engine${PYTHON_EXT_SUFFIX}\"
-            \"${PYTHON_SYS_PATH}/${PYTHON_PACKAGE_NAME}/engine.so\"
+            \"${_mooncake_engine_compat_path}\"
         )
-    ")
+    "
+    COMPONENT python)
+endif()
+
+if(SKBUILD)
+  if(WITH_STORE)
+    set_target_properties(mooncake_master mooncake_client
+                          PROPERTIES INSTALL_RPATH "$ORIGIN")
+    install(TARGETS mooncake_master mooncake_client
+            RUNTIME DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
+
+  if(WITH_TE AND BUILD_EXAMPLES)
+    set_target_properties(transfer_engine_bench PROPERTIES INSTALL_RPATH
+                                                           "$ORIGIN")
+    install(TARGETS transfer_engine_bench
+            RUNTIME DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
+
+  if(USE_ETCD AND NOT USE_ETCD_LEGACY)
+    install(
+      FILES "${CMAKE_BINARY_DIR}/mooncake-common/etcd/libetcd_wrapper.so"
+      DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+      COMPONENT python)
+  endif()
+
+  if(STORE_USE_K8S_LEASE)
+    install(
+      FILES
+        "${CMAKE_BINARY_DIR}/mooncake-common/k8s-lease/libk8s_lease_wrapper.so"
+      DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}
+      COMPONENT python)
+  endif()
+
+  if(USE_ASCEND_DIRECT OR USE_UBSHMEM)
+    install(TARGETS ascend_transport
+            LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
+
+  if(USE_ASCEND)
+    install(TARGETS ascend_transport_mem
+            LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
+
+  if(WITH_EP)
+    install(TARGETS mooncake_pg
+            LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
+
+  if(BUILD_SHARED_LIBS)
+    set(_mooncake_python_shared_targets mooncake_common)
+    if(WITH_TE)
+      list(APPEND _mooncake_python_shared_targets transfer_engine)
+    endif()
+    if(WITH_STORE)
+      list(APPEND _mooncake_python_shared_targets mooncake_store)
+    endif()
+    install(TARGETS ${_mooncake_python_shared_targets}
+            LIBRARY DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR} COMPONENT python)
+  endif()
 endif()
diff --git a/mooncake-integration/shared_segment.py b/mooncake-integration/shared_segment.py
new file mode 100644
index 0000000000..85acd35f5f
--- /dev/null
+++ b/mooncake-integration/shared_segment.py
@@ -0,0 +1,384 @@
+"""Process-shared host memory for one-writer/many-reader KV offload.
+
+MLA keeps the same KV in every rank of a TP group, so offloading it per rank
+multiplies host memory by the TP size for no benefit. A shared segment allocates
+the pages once, in ``owner_rank``, and maps them into every rank of the group.
+
+Virtual addresses are deliberately not forced to match across ranks: peers agree
+on the byte layout, so the reserved address space equals the segment size rather
+than size x world_size. Layout (which offset holds which tensor) is computed
+here; C++ only shares the raw span.
+
+    from mooncake.shared_segment import create_shared_segment
+
+    seg = create_shared_segment(
+        "vllm_sparse_kv",
+        blocks={
+            "k": dict(count=num_layers, shape=k_shape, dtype=torch.bfloat16),
+            "v": dict(count=num_layers, shape=v_shape, dtype=torch.bfloat16),
+        },
+        world_size=tp_size,
+        rank_id=tp_rank,
+        comm_group=tp_group,
+        mmap=False,  # Ascend VMM; tensors() are NPU views of the SVM VA
+    )
+    k_caches = seg.tensors("k")
+"""
+
+from __future__ import annotations
+
+import ctypes
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import torch
+import torch.distributed as dist
+
+from .engine import SharedSegment as _CppSharedSegment
+
+__all__ = [
+    "SharedSegment",
+    "SharedSegmentError",
+    "create_shared_segment",
+    "shared_segment_supported",
+]
+
+_ALIGN = 4096
+
+
+class SharedSegmentError(RuntimeError):
+    """Raised when a shared segment cannot be created or addressed."""
+
+
+def create_shared_segment(
+    name: str,
+    blocks: Mapping[str, Mapping[str, Any]],
+    world_size: int,
+    rank_id: int,
+    owner_rank: int = 0,
+    device_id: int | None = None,
+    comm_group: Any = None,
+    mmap: bool = True,
+    host_register: bool = False,
+    *,
+    tp_group: Any = None,
+) -> SharedSegment:
+    """Creates a shared host segment and returns it ready to use.
+
+    Every rank of the group must call this with an identical declaration; a
+    disagreement is reported here rather than silently producing wrong reads.
+    ``comm_group`` is the torch process group (or vLLM GroupCoordinator) used
+    to all-gather export blobs; it may be omitted only when ``world_size`` is
+    1. ``tp_group`` is a deprecated alias of ``comm_group``. ``device_id``
+    defaults to the rank's current accelerator.
+
+    ``mmap`` (default True) uses an unnamed memfd and asks the kernel for THP
+    (``MADV_HUGEPAGE``) so the span can be 2MiB pages without a HugeTLB pool;
+    4KiB pages if THP cannot allocate. Ranks share those pages through the
+    memfd. Set ``mmap=False`` for the platform VMM fabric path.
+    ``host_register`` (default False) HostRegister's mmap pages for
+    ``device_id`` so ``tensors().data_ptr()`` is a device VA suitable for TE
+    ``location=\"npu\"`` ROCE D2rH; requires ``mmap=True``. Ascend VMM
+    (``mmap=False``) also exposes NPU tensors: the host SVM VA is already
+    device-accessible after ``MemSetAccess`` (owner ``MallocMem``, peer
+    ``ImportAndMap``), so ``tensors().data_ptr()`` is that same VA.
+    """
+    comm_group = _select_comm_group(comm_group, tp_group)
+    if host_register and not mmap:
+        raise SharedSegmentError("host_register requires mmap=True")
+    if not shared_segment_supported(mmap=mmap, host_register=host_register):
+        if not mmap:
+            raise SharedSegmentError(
+                "This mooncake build has no VMM backend for shared segments"
+            )
+        if host_register:
+            raise SharedSegmentError(
+                "This mooncake build cannot HostRegister shared-segment pages"
+            )
+        raise SharedSegmentError(
+            "This mooncake build has no mmap shared-segment backend"
+        )
+
+    # Sorted names keep the byte layout identical across ranks regardless of
+    # dict iteration order.
+    names = sorted(blocks)
+    specs = {
+        block_name: _parse_block(block_name, blocks[block_name]) for block_name in names
+    }
+    offsets, stride, total = _build_layout(specs, names)
+    # Fold the layout into the name so C++'s fingerprint catches peers that
+    # disagree on count, shape, dtype, or size without exchanging the full
+    # declaration.
+    tag = ";".join(_block_layout_tag(n, specs[n]) for n in names)
+    device = _current_device_index() if device_id is None else device_id
+
+    segment = None
+    blob = b""
+    create_error = ""
+    try:
+        segment, blob = _CppSharedSegment.create(
+            f"{name}|{tag}",
+            total,
+            world_size,
+            rank_id,
+            owner_rank,
+            device,
+            mmap,
+            host_register,
+        )
+    except RuntimeError as exc:
+        create_error = str(exc)
+
+    _raise_if_any_rank_failed(create_error, world_size, rank_id, comm_group, "create")
+    if segment is None:
+        raise SharedSegmentError("Shared segment create returned no segment")
+
+    complete_error = ""
+    try:
+        if world_size == 1:
+            blobs = [blob]
+        else:
+            blobs = _all_gather_blob(blob, world_size, comm_group)
+        segment.complete(blobs)
+    except (RuntimeError, SharedSegmentError) as exc:
+        complete_error = str(exc)
+
+    _raise_if_any_rank_failed(
+        complete_error, world_size, rank_id, comm_group, "complete"
+    )
+    return SharedSegment(segment, specs, offsets, stride, device)
+
+
+class SharedSegment:
+    """Handle to one shared host segment. Alive for as long as the mapping is needed."""
+
+    def __init__(
+        self,
+        segment: Any,
+        specs: dict[str, _BlockSpec],
+        offsets: dict[str, int],
+        stride: int,
+        device_id: int,
+    ) -> None:
+        self._segment = segment
+        self._specs = specs
+        self._offsets = offsets
+        self._stride = stride
+        self._device_id = device_id
+        # Device-accessible VA when present: HostRegister device ptr (mmap), or
+        # the host SVM VA itself after MemSetAccess (Ascend VMM).
+        self._device_base = int(segment.device_addr()) or None
+
+    def tensors(self, block: str) -> list[torch.Tensor]:
+        """Zero-copy views of every entry of ``block``, in index order.
+
+        On Ascend, ``host_register=True`` (mmap) and ``mmap=False`` (VMM) both
+        yield NPU tensors whose ``data_ptr()`` can be registered with Transfer
+        Engine as ``location=\"npu\"`` for ROCE D2rH. mmap without HostRegister
+        yields host CPU tensors. Views share physical pages across the TP
+        group. Each view holds a reference back to this segment.
+        """
+        spec = self._specs.get(block)
+        if spec is None:
+            raise SharedSegmentError(f"Unknown shared segment block {block!r}")
+        host_base = int(self._segment.base_addr())
+        offset = self._offsets[block]
+        views = []
+        for index in range(spec.count):
+            byte_off = offset + index * self._stride
+            if self._device_base is not None:
+                view = _tensor_from_device_ptr(
+                    self._device_base + byte_off,
+                    spec.nbytes,
+                    spec.shape,
+                    spec.dtype,
+                    self._device_id,
+                    self,
+                )
+            else:
+                view = _tensor_from_host_addr(
+                    host_base + byte_off,
+                    spec.nbytes,
+                    spec.shape,
+                    spec.dtype,
+                    self,
+                )
+            views.append(view)
+        return views
+
+    def base_addr(self) -> int:
+        return self._segment.base_addr()
+
+    def total_size(self) -> int:
+        return self._segment.size()
+
+
+def shared_segment_supported(mmap: bool = True, host_register: bool = False) -> bool:
+    return _CppSharedSegment.supported(mmap, host_register)
+
+
+@dataclass(frozen=True)
+class _BlockSpec:
+    count: int
+    shape: tuple[int, ...]
+    dtype: torch.dtype
+    nbytes: int
+
+
+def _block_layout_tag(name: str, spec: _BlockSpec) -> str:
+    shape = "x".join(str(dim) for dim in spec.shape)
+    return f"{name}:{spec.count}:{shape}:{spec.dtype}:{spec.nbytes}"
+
+
+def _align_up(value: int, alignment: int = _ALIGN) -> int:
+    return (value + alignment - 1) // alignment * alignment
+
+
+def _parse_block(name: str, spec: Mapping[str, Any]) -> _BlockSpec:
+    try:
+        count = int(spec["count"])
+        shape = tuple(int(dim) for dim in spec["shape"])
+        dtype = spec["dtype"]
+    except (KeyError, TypeError) as exc:
+        raise SharedSegmentError(
+            f"Block {name!r} needs count, shape and dtype"
+        ) from exc
+    if count <= 0:
+        raise SharedSegmentError(f"Block {name!r} needs a positive count")
+    if not shape or any(dim <= 0 for dim in shape):
+        raise SharedSegmentError(f"Block {name!r} needs a positive shape")
+
+    element_size = torch.empty(0, dtype=dtype).element_size()
+    nbytes = element_size
+    for dim in shape:
+        nbytes *= dim
+    return _BlockSpec(count=count, shape=shape, dtype=dtype, nbytes=nbytes)
+
+
+def _build_layout(
+    specs: dict[str, _BlockSpec], names: Sequence[str]
+) -> tuple[dict[str, int], int, int]:
+    """Returns (offsets_by_name, group_stride, total_size)."""
+    stride = 0
+    offsets: dict[str, int] = {}
+    for name in names:
+        offsets[name] = stride
+        stride += _align_up(specs[name].nbytes)
+    if stride == 0:
+        raise SharedSegmentError("Shared segment needs at least one block")
+    total = stride * max(spec.count for spec in specs.values())
+    return offsets, stride, total
+
+
+def _current_device_index() -> int:
+    """The accelerator this rank runs on, whatever vendor it is."""
+    accelerator = getattr(torch, "accelerator", None)
+    if accelerator is not None:
+        try:
+            return int(accelerator.current_device_index())
+        except (RuntimeError, AttributeError):
+            pass
+    for backend in ("npu",):
+        module = getattr(torch, backend, None)
+        if module is not None and module.is_available():
+            return int(module.current_device())
+    return 0
+
+
+def _select_comm_group(comm_group: Any, tp_group: Any) -> Any:
+    """``tp_group`` is a deprecated alias of ``comm_group``."""
+    if tp_group is None:
+        return comm_group
+    if comm_group is None or comm_group is tp_group:
+        return tp_group
+    raise SharedSegmentError(
+        "pass only comm_group; tp_group is a deprecated alias of comm_group"
+    )
+
+
+def _resolve_cpu_group(comm_group: Any) -> Any:
+    """Accepts a vLLM GroupCoordinator or a plain process group.
+
+    The blobs are exchanged as CPU byte tensors, so a gloo group is required; a
+    coordinator exposes one as ``cpu_group``.
+    """
+    cpu_group = getattr(comm_group, "cpu_group", None)
+    return cpu_group if cpu_group is not None else comm_group
+
+
+def _raise_if_any_rank_failed(
+    local_error: str,
+    world_size: int,
+    rank_id: int,
+    comm_group: Any,
+    phase: str,
+) -> None:
+    """Makes every rank leave a failed collective phase with the same error."""
+    if world_size == 1:
+        if local_error:
+            raise SharedSegmentError(local_error)
+        return
+    if comm_group is None:
+        raise SharedSegmentError("comm_group is required when world_size > 1")
+
+    failures: list[tuple[int, str] | None] = [None] * world_size
+    local_failure = (rank_id, local_error) if local_error else None
+    dist.all_gather_object(
+        failures, local_failure, group=_resolve_cpu_group(comm_group)
+    )
+    errors = [failure for failure in failures if failure is not None]
+    if errors:
+        detail = "; ".join(
+            f"rank {failed_rank}: {message}" for failed_rank, message in errors
+        )
+        raise SharedSegmentError(f"Shared segment {phase} failed: {detail}")
+
+
+def _all_gather_blob(blob: bytes, world_size: int, comm_group: Any) -> list[bytes]:
+    local = torch.frombuffer(bytearray(blob), dtype=torch.uint8)
+    gathered = [torch.empty_like(local) for _ in range(world_size)]
+    dist.all_gather(gathered, local, group=_resolve_cpu_group(comm_group))
+    return [bytes(tensor.numpy()) for tensor in gathered]
+
+
+def _contiguous_strides(shape: Sequence[int]) -> tuple[int, ...]:
+    strides: list[int] = [1] * len(shape)
+    for i in range(len(shape) - 2, -1, -1):
+        strides[i] = strides[i + 1] * shape[i + 1]
+    return tuple(strides)
+
+
+def _tensor_from_device_ptr(
+    device_ptr: int,
+    nbytes: int,
+    shape: tuple[int, ...],
+    dtype: torch.dtype,
+    device_id: int,
+    holder: Any,
+) -> torch.Tensor:
+    """Wrap a device-accessible VA (HostRegister or Ascend VMM) as an NPU tensor."""
+    try:
+        import torch_npu
+    except ImportError as exc:
+        raise SharedSegmentError(
+            "torch_npu is required to expose device-mapped shared-segment tensors"
+        ) from exc
+
+    device = torch.device(f"npu:{device_id}")
+    storage = torch_npu._C._construct_storage_from_data_pointer(
+        int(device_ptr), device, int(nbytes)
+    )
+    view = torch.empty(0, dtype=dtype, device=device)
+    view.set_(storage, 0, shape, _contiguous_strides(shape))
+    view._mooncake_segment = holder
+    return view
+
+
+def _tensor_from_host_addr(
+    host_addr: int, nbytes: int, shape: tuple[int, ...], dtype: torch.dtype, holder: Any
+) -> torch.Tensor:
+    buffer = (ctypes.c_int8 * nbytes).from_address(host_addr)
+    view = torch.frombuffer(buffer, dtype=dtype).view(shape)
+    view._mooncake_segment = holder
+    return view
diff --git a/mooncake-integration/store/engram_store_py.cpp b/mooncake-integration/store/engram_store_py.cpp
index 3f4347362a..47c350eb36 100644
--- a/mooncake-integration/store/engram_store_py.cpp
+++ b/mooncake-integration/store/engram_store_py.cpp
@@ -3,6 +3,7 @@
 #include <pybind11/stl.h>
 
 #include <cstring>
+#include <limits>
 
 #include "engram/engram_store.h"
 #include "engram/engram_store_config.h"
@@ -17,22 +18,6 @@ namespace {
 constexpr char kPyClientCapsuleName[] = "mooncake.PyClient.shared_ptr";
 constexpr char kPyClientCapsuleMethod[] = "_get_pyclient_capsule";
 
-std::vector<std::vector<std::vector<int64_t>>> py_obj_to_vec3d(py::object obj) {
-    std::vector<std::vector<std::vector<int64_t>>> result;
-    for (auto batch_item : obj) {
-        std::vector<std::vector<int64_t>> batch_vec;
-        for (auto token_item : batch_item) {
-            std::vector<int64_t> token_vec;
-            for (auto head_item : token_item) {
-                token_vec.push_back(head_item.cast<int64_t>());
-            }
-            batch_vec.push_back(std::move(token_vec));
-        }
-        result.push_back(std::move(batch_vec));
-    }
-    return result;
-}
-
 std::shared_ptr<PyClient> unwrap_pyclient_capsule(py::object capsule) {
     if (capsule.is_none()) {
         return nullptr;
@@ -87,83 +72,23 @@ std::shared_ptr<PyClient> unwrap_store(py::object store_obj) {
     }
 }
 
-py::array_t<float> require_embedding_buffer(py::handle buf,
-                                            int64_t expected_rows,
-                                            int expected_cols) {
+py::array require_embedding_buffer(py::handle buf, int64_t rows,
+                                   int row_bytes) {
     if (!py::isinstance<py::array>(buf)) {
         throw std::runtime_error("embedding_buffers must be NumPy arrays");
     }
-
-    auto arr =
-        py::array_t<float, py::array::c_style | py::array::forcecast>::ensure(
-            buf);
-    if (!arr) {
-        throw std::runtime_error("embedding_buffers must be float32 arrays");
-    }
-
-    auto req = arr.request();
-    if (req.ndim != 2) {
-        throw std::runtime_error("each embedding buffer must be 2D [N_h, D]");
+    auto arr = py::reinterpret_borrow<py::array>(buf);
+    if (!arr.dtype().is(py::dtype::of<uint8_t>()) ||
+        !(arr.flags() & py::array::c_style)) {
+        throw std::runtime_error("rows must be contiguous uint8 arrays");
     }
-    if (req.shape[0] != expected_rows || req.shape[1] != expected_cols) {
+    if (arr.ndim() != 2 || arr.shape(0) != rows || arr.shape(1) != row_bytes) {
         throw std::runtime_error(
-            "embedding buffer shape does not match "
-            "get_table_vocab_sizes()/get_embedding_dim()");
+            "embedding buffer must match per-head table shape");
     }
     return arr;
 }
 
-py::array_t<float> lookup_to_numpy(
-    EngramStore& self,
-    const std::vector<std::vector<std::vector<int64_t>>>& row_ids) {
-    if (row_ids.empty() || row_ids[0].empty()) {
-        throw std::runtime_error("row_ids must not be empty");
-    }
-
-    const int B = static_cast<int>(row_ids.size());
-    const int L = static_cast<int>(row_ids[0].size());
-    const int H = self.get_num_heads();
-    const int D = self.get_embedding_dim();
-    py::array_t<float> output({B, L, H, D});
-    auto out_buf = output.request();
-
-    int ret =
-        self.lookup_rows(row_ids, out_buf.ptr, out_buf.size * sizeof(float));
-    if (ret != 0) {
-        throw std::runtime_error("EngramStore lookup failed");
-    }
-    return output;
-}
-
-py::array_t<float> lookup_array_to_numpy(
-    EngramStore& self,
-    const py::array_t<int64_t, py::array::c_style | py::array::forcecast>&
-        row_ids) {
-    auto req = row_ids.request();
-    if (req.ndim != 3) {
-        throw std::runtime_error("row_ids array must have shape [B, L, H]");
-    }
-
-    const int B = static_cast<int>(req.shape[0]);
-    const int L = static_cast<int>(req.shape[1]);
-    const int H = static_cast<int>(req.shape[2]);
-    if (H != self.get_num_heads()) {
-        throw std::runtime_error("row_ids last dimension must match num_heads");
-    }
-
-    const int D = self.get_embedding_dim();
-    py::array_t<float> output({B, L, H, D});
-    auto out_buf = output.request();
-
-    int ret =
-        self.lookup_rows_contiguous(static_cast<const int64_t*>(req.ptr), B, L,
-                                    out_buf.ptr, out_buf.size * sizeof(float));
-    if (ret != 0) {
-        throw std::runtime_error("EngramStore lookup failed");
-    }
-    return output;
-}
-
 }  // namespace
 
 namespace mooncake {
@@ -174,64 +99,113 @@ void bind_engram_store(py::module& m) {
         .def(py::init<>())
         .def_readwrite("table_vocab_sizes",
                        &EngramStoreConfig::table_vocab_sizes)
-        .def_readwrite("embedding_dim", &EngramStoreConfig::embedding_dim);
+        .def_readwrite("row_bytes", &EngramStoreConfig::row_bytes);
 
     py::class_<EngramStore>(m, "EngramStore")
+        .def(
+            "bind_local",
+            [](EngramStore& self, int layer_id, py::list buffers) {
+                const auto rows = self.get_table_vocab_sizes(layer_id);
+                if (py::len(buffers) != rows.size())
+                    throw std::runtime_error(
+                        "Local table count must match heads");
+                std::vector<const void*> pointers;
+                std::vector<size_t> sizes;
+                for (size_t h = 0; h < rows.size(); ++h) {
+                    auto arr = require_embedding_buffer(
+                        buffers[h], rows[h], self.get_row_bytes(layer_id));
+                    pointers.push_back(arr.data());
+                    sizes.push_back(arr.nbytes());
+                }
+                if (self.bind_local(layer_id, pointers, sizes) != 0)
+                    throw std::runtime_error(
+                        "bind_local requires an unbound layer and no Store "
+                        "client");
+            },
+            py::arg("layer_id"), py::arg("embedding_buffers"),
+            py::keep_alive<1, 3>(),
+            "Bind immutable uint8 tables before lookup. Retains the arrays "
+            "without "
+            "copying; do not modify, resize or unmap them while bound.")
+        .def("get_layer_ids", &EngramStore::get_layer_ids)
         .def("get_table_vocab_sizes", &EngramStore::get_table_vocab_sizes)
         .def("get_store_keys", &EngramStore::get_store_keys)
         .def("get_num_heads", &EngramStore::get_num_heads)
-        .def("get_embedding_dim", &EngramStore::get_embedding_dim)
+        .def("get_row_bytes", &EngramStore::get_row_bytes)
         .def(
             "remove_from_store",
-            [](EngramStore& self, bool force) {
-                int ret = self.remove_from_store(force);
+            [](EngramStore& self, int layer_id, bool force) {
+                int ret = self.remove_from_store(layer_id, force);
                 if (ret < 0) {
                     throw std::runtime_error("remove_from_store failed, rc=" +
                                              std::to_string(ret));
                 }
                 return ret;
             },
-            py::arg("force") = false,
-            "Remove all Mooncake Store tables owned by this EngramStore layer. "
+            py::arg("layer_id"), py::arg("force") = false,
+            "Remove all Mooncake Store tables for the selected layer. "
             "Returns the number of removed head tables; missing keys are "
             "ignored.")
-        .def(py::init([](int layer_id, const EngramStoreConfig& cfg,
+        .def(py::init([](const std::map<int, EngramStoreConfig>& layers,
                          py::object store_obj) {
                  std::shared_ptr<PyClient> store = unwrap_store(store_obj);
-                 return new EngramStore(layer_id, cfg, store);
+                 return new EngramStore(layers, store);
              }),
-             py::arg("layer_id"), py::arg("config"),
-             py::arg("store") = py::none())
+             py::arg("layers"), py::arg("store") = py::none())
         .def(
-            "lookup",
-            [](EngramStore& self, py::object row_ids_obj) {
-                if (py::isinstance<py::array>(row_ids_obj)) {
-                    auto row_ids_array = py::array_t<
-                        int64_t, py::array::c_style |
-                                     py::array::forcecast>::ensure(row_ids_obj);
-                    if (!row_ids_array) {
-                        throw std::runtime_error(
-                            "row_ids array must be convertible to int64");
-                    }
-                    return lookup_array_to_numpy(self, row_ids_array);
+            "lookup_into",
+            [](EngramStore& self, int layer_id,
+               py::array_t<int64_t, py::array::c_style> ids, py::array output) {
+                const int width = self.get_row_bytes(layer_id);
+                if (ids.ndim() != 3 ||
+                    ids.shape(2) != self.get_num_heads(layer_id) ||
+                    ids.shape(0) > std::numeric_limits<int>::max() ||
+                    ids.shape(1) > std::numeric_limits<int>::max() ||
+                    output.ndim() != 4 || output.shape(0) != ids.shape(0) ||
+                    output.shape(1) != ids.shape(1) ||
+                    output.shape(2) != ids.shape(2) ||
+                    output.shape(3) != width || !output.writeable() ||
+                    !(output.flags() & py::array::c_style) ||
+                    !output.dtype().is(py::dtype::of<uint8_t>())) {
+                    throw std::runtime_error(
+                        "lookup_into requires contiguous IDs [B,L,H] and "
+                        "matching writable uint8 output [B,L,H,row_bytes]");
+                }
+                if (ids.size() == 0) return;
+                auto ids_buf = ids.request();
+                auto out_buf = output.request();
+                const int B = static_cast<int>(ids_buf.shape[0]);
+                const int L = static_cast<int>(ids_buf.shape[1]);
+                int ret;
+                {
+                    py::gil_scoped_release release;
+                    ret = self.lookup_into(
+                        layer_id, static_cast<const int64_t*>(ids_buf.ptr), B,
+                        L, out_buf.ptr, out_buf.size * out_buf.itemsize);
                 }
-                return lookup_to_numpy(self, py_obj_to_vec3d(row_ids_obj));
+                if (ret != 0)
+                    throw std::runtime_error("EngramStore lookup_into failed");
             },
-            py::arg("row_ids"),
-            "Lookup embeddings by precomputed row IDs. Returns [B, L, H, D].")
+            py::arg("layer_id"), py::arg("row_ids").noconvert(),
+            py::arg("output").noconvert(),
+            "Read into caller-owned uint8 memory. The caller must keep the "
+            "output registered with this Store for Store-backed reads. "
+            "Local bound tables do not require output registration. "
+            "This method does not allocate, register, or unregister output.")
         .def(
             "populate",
-            [](EngramStore& self, py::list embedding_buffers) {
+            [](EngramStore& self, int layer_id, py::list embedding_buffers,
+               const ReplicateConfig& config) {
                 const std::vector<int64_t> vocab_sizes =
-                    self.get_table_vocab_sizes();
-                const int embed_dim = self.get_embedding_dim();
+                    self.get_table_vocab_sizes(layer_id);
+                const int row_bytes = self.get_row_bytes(layer_id);
                 if (static_cast<size_t>(py::len(embedding_buffers)) !=
                     vocab_sizes.size()) {
                     throw std::runtime_error(
                         "embedding_buffers size must match num_heads");
                 }
 
-                std::vector<py::array_t<float>> arrays;
+                std::vector<py::array> arrays;
                 std::vector<void*> bufs;
                 std::vector<size_t> sizes;
                 arrays.reserve(vocab_sizes.size());
@@ -239,18 +213,20 @@ void bind_engram_store(py::module& m) {
                 sizes.reserve(vocab_sizes.size());
                 for (size_t i = 0; i < vocab_sizes.size(); ++i) {
                     auto arr = require_embedding_buffer(
-                        embedding_buffers[i], vocab_sizes[i], embed_dim);
+                        embedding_buffers[i], vocab_sizes[i], row_bytes);
                     auto req = arr.request();
                     arrays.push_back(arr);
                     bufs.push_back(req.ptr);
-                    sizes.push_back(req.size * sizeof(float));
+                    sizes.push_back(arr.nbytes());
                 }
-                int ret = self.populate(bufs, sizes);
+                py::gil_scoped_release release;
+                int ret = self.populate(layer_id, bufs, sizes, config);
                 if (ret != 0) {
                     throw std::runtime_error("populate failed");
                 }
             },
-            py::arg("embedding_buffers"));
+            py::arg("layer_id"), py::arg("embedding_buffers"),
+            py::arg("config") = ReplicateConfig{});
 }
 
 }  // namespace engram
diff --git a/mooncake-integration/store/store_py.cpp b/mooncake-integration/store/store_py.cpp
index 166d940c5f..3fed10ade0 100644
--- a/mooncake-integration/store/store_py.cpp
+++ b/mooncake-integration/store/store_py.cpp
@@ -4,6 +4,7 @@
 
 #include <functional>
 #include <limits>
+#include <mutex>
 #include <numeric>
 #include <optional>
 #include <unordered_map>
@@ -82,6 +83,71 @@ struct PyTensorInfo {
     }
 };
 
+// A serialized tensor object is laid out as [metadata][payload].  The raw
+// *_tensor_from APIs accept host, pinned-host, and device addresses.  Reading
+// metadata through a C++ pointer is invalid for device addresses, and a
+// DummyClient cannot dereference a caller's pointer in the RealClient process.
+// Keep the original addresses in the resulting parts. DummyClient and
+// RealClient each perform the appropriate staging/IPC for non-local buffers.
+struct RawTensorObjectParts {
+    uintptr_t metadata_ptr = 0;
+    size_t metadata_size = 0;
+    uintptr_t payload_ptr = 0;
+    size_t payload_size = 0;
+};
+
+std::optional<RawTensorObjectParts> make_raw_tensor_object_parts(
+    uintptr_t buffer_ptr, size_t size, const char *operation_name) {
+    if (buffer_ptr == 0 || size < sizeof(TensorMetadata) ||
+        size > std::numeric_limits<uintptr_t>::max() - buffer_ptr) {
+        LOG(ERROR) << operation_name << ": invalid tensor object buffer";
+        return std::nullopt;
+    }
+
+    const auto &runtime =
+        mooncake::device::GetAcceleratorRegistry().RuntimeAccelerators();
+    TensorMetadata metadata{};
+    if (!runtime.CopyToHost(&metadata,
+                            reinterpret_cast<const void *>(buffer_ptr),
+                            sizeof(metadata))) {
+        LOG(ERROR) << operation_name << ": failed to read tensor metadata";
+        return std::nullopt;
+    }
+    if (metadata.header.data_offset > std::numeric_limits<size_t>::max() ||
+        metadata.header.data_bytes > std::numeric_limits<size_t>::max()) {
+        LOG(ERROR) << operation_name << ": tensor object size overflows";
+        return std::nullopt;
+    }
+    if (!ValidateTensorMetadata(metadata, size)) {
+        LOG(ERROR) << operation_name << ": invalid tensor object metadata";
+        return std::nullopt;
+    }
+    const size_t metadata_size =
+        static_cast<size_t>(metadata.header.data_offset);
+    const size_t payload_size = static_cast<size_t>(metadata.header.data_bytes);
+    if (metadata_size > size || payload_size > size - metadata_size ||
+        metadata_size > std::numeric_limits<uintptr_t>::max() - buffer_ptr) {
+        LOG(ERROR) << operation_name << ": invalid tensor object range";
+        return std::nullopt;
+    }
+
+    RawTensorObjectParts parts;
+    parts.metadata_size = metadata_size;
+    parts.payload_ptr = buffer_ptr + metadata_size;
+    parts.payload_size = payload_size;
+    if (payload_size >
+        std::numeric_limits<uintptr_t>::max() - parts.payload_ptr) {
+        LOG(ERROR) << operation_name << ": tensor payload address overflows";
+        return std::nullopt;
+    }
+    // Keep the caller's original address in the part list. DummyClient uses
+    // the registration table to validate/stage external buffers; replacing a
+    // device metadata pointer with a private host copy would make that
+    // pointer appear unregistered.
+    parts.metadata_ptr = buffer_ptr;
+    return parts;
+}
+
 TensorMetadata build_full_tensor_metadata(const py::handle &tensor,
                                           TensorDtype dtype_enum,
                                           size_t tensor_size);
@@ -164,12 +230,6 @@ py::tuple tensor_shape_tuple(const TensorMetadata &metadata) {
     return py::cast(shape_vec);
 }
 
-void append_tensor_payload_span(std::vector<std::span<const char>> &values,
-                                uintptr_t data_ptr, size_t tensor_size) {
-    if (tensor_size == 0) return;
-    values.emplace_back(reinterpret_cast<const char *>(data_ptr), tensor_size);
-}
-
 pybind11::object buffer_to_tensor(BufferHandle *buffer_handle, char *usr_buffer,
                                   int64_t data_length,
                                   bool own_user_buffer = false) {
@@ -307,6 +367,36 @@ pybind11::object buffer_to_tensor(BufferHandle *buffer_handle, char *usr_buffer,
     }
 }
 
+std::optional<py::object> decode_raw_tensor_object_for_host(
+    uintptr_t buffer_ptr, size_t size, std::vector<char> &host_buffer,
+    const char *operation_name) {
+    if (!make_raw_tensor_object_parts(buffer_ptr, size, operation_name)) {
+        return std::nullopt;
+    }
+
+    char *tensor_buffer = reinterpret_cast<char *>(buffer_ptr);
+    const auto &runtime =
+        mooncake::device::GetAcceleratorRegistry().RuntimeAccelerators();
+    if (runtime.FindDeviceForPointer(reinterpret_cast<void *>(buffer_ptr))) {
+        host_buffer.resize(size);
+        if (!runtime.CopyToHost(host_buffer.data(),
+                                reinterpret_cast<void *>(buffer_ptr), size)) {
+            LOG(ERROR) << operation_name
+                       << ": failed to copy device tensor object to host";
+            return std::nullopt;
+        }
+        tensor_buffer = host_buffer.data();
+    }
+
+    py::object tensor =
+        buffer_to_tensor(nullptr, tensor_buffer, static_cast<int64_t>(size));
+    if (tensor.is_none()) {
+        LOG(ERROR) << operation_name << ": failed to decode tensor object";
+        return std::nullopt;
+    }
+    return tensor;
+}
+
 py::tuple serialize_tensor_metadata(py::object tensor) {
     PyTensorInfo info = extract_tensor_info(tensor);
     if (!info.valid()) {
@@ -340,6 +430,8 @@ bool tensor_destination_matches_metadata(const PyTensorInfo &target,
                                stored.metadata.header.ndim);
 }
 
+// Read tensor payloads directly into caller-owned CUDA buffers.  Metadata is
+// fetched separately so no complete-object host staging buffer is needed.
 template <typename ResultType>
 bool apply_indexed_results(const char *context,
                            const std::vector<ResultType> &op_results,
@@ -402,6 +494,41 @@ inline int to_py_ret(ErrorCode error_code) {
 #include "store_py_internal.h"
 
 }  // namespace
+
+class RangedReadSnapshotPy {
+   public:
+    RangedReadSnapshotPy(std::shared_ptr<PyClient> store,
+                         std::vector<std::string> keys)
+        : store_(std::move(store)), keys_(std::move(keys)) {
+        snapshot_ = store_->prepare_get_into_ranges_snapshot(keys_);
+    }
+
+    bool belongs_to(const std::shared_ptr<PyClient> &store) const {
+        return store_.get() == store.get();
+    }
+
+    std::vector<std::vector<std::vector<int64_t>>> get_into_ranges(
+        const std::vector<void *> &buffers,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (snapshot_.should_refresh()) {
+            store_->refresh_get_into_ranges_snapshot(snapshot_, keys_);
+        }
+        return store_->get_into_ranges_from_snapshot(
+            buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes,
+            snapshot_);
+    }
+
+   private:
+    std::shared_ptr<PyClient> store_;
+    std::vector<std::string> keys_;
+    PyClient::RangedReadSnapshot snapshot_;
+    std::mutex mutex_;
+};
+
 // Python-specific wrapper functions that handle GIL and return pybind11 types
 class MooncakeStorePyWrapper {
    public:
@@ -512,6 +639,16 @@ class MooncakeStorePyWrapper {
                                                   grace_period_seconds);
     }
 
+    int unmount_local_disk_segment(uint64_t grace_period_seconds = 0) {
+        auto real_client = std::dynamic_pointer_cast<RealClient>(store_);
+        if (!real_client) {
+            LOG(ERROR) << "unmount_local_disk_segment requires RealClient";
+            return -1;
+        }
+        py::gil_scoped_release release;
+        return real_client->drainLocalDiskSegment(grace_period_seconds);
+    }
+
     std::string get_tp_key_name(const std::string &base_key, int rank) const {
         return base_key + "_tp_" + std::to_string(rank);
     }
@@ -736,8 +873,10 @@ class MooncakeStorePyWrapper {
     }
 
     std::vector<std::optional<ParsedTensorMetadata>>
-    batch_get_tensor_metadata_prefixes(const std::vector<std::string> &keys,
-                                       const std::string &context) {
+    batch_get_tensor_metadata_prefixes(
+        const std::vector<std::string> &keys, const std::string &context,
+        const PyClient::QueryResultCache *snapshot = nullptr,
+        std::vector<int64_t> *errors = nullptr) {
         std::vector<std::optional<ParsedTensorMetadata>> metadata(keys.size());
         if (keys.empty()) return metadata;
 
@@ -745,6 +884,10 @@ class MooncakeStorePyWrapper {
         auto scratch = store_->allocate_client_buffer(scratch_size);
         if (!scratch) {
             LOG(ERROR) << context << ": failed to allocate metadata buffer";
+            if (errors) {
+                std::fill(errors->begin(), errors->end(),
+                          to_py_ret(ErrorCode::NO_AVAILABLE_HANDLE));
+            }
             return metadata;
         }
 
@@ -764,12 +907,19 @@ class MooncakeStorePyWrapper {
         std::vector<std::vector<std::vector<int64_t>>> results;
         {
             py::gil_scoped_release release_gil;
-            results =
-                store_->get_into_ranges(buffers, all_keys, all_dst_offsets,
-                                        all_src_offsets, all_sizes, nullptr);
+            results = snapshot ? real_client_->get_into_ranges_from_snapshot(
+                                     buffers, all_keys, all_dst_offsets,
+                                     all_src_offsets, all_sizes, *snapshot)
+                               : store_->get_into_ranges(
+                                     buffers, all_keys, all_dst_offsets,
+                                     all_src_offsets, all_sizes, nullptr);
         }
         if (results.size() != 1 || results[0].size() != keys.size()) {
             LOG(ERROR) << context << ": metadata read result size mismatch";
+            if (errors) {
+                std::fill(errors->begin(), errors->end(),
+                          to_py_ret(ErrorCode::INTERNAL_ERROR));
+            }
             return metadata;
         }
 
@@ -778,6 +928,12 @@ class MooncakeStorePyWrapper {
             if (results[0][i].size() != 1 ||
                 results[0][i][0] !=
                     static_cast<int64_t>(sizeof(TensorMetadata))) {
+                if (errors) {
+                    (*errors)[i] =
+                        results[0][i].size() == 1 && results[0][i][0] < 0
+                            ? results[0][i][0]
+                            : to_py_ret(ErrorCode::INTERNAL_ERROR);
+                }
                 continue;
             }
             metadata[i] = parse_tensor_metadata_from_prefix(
@@ -810,8 +966,89 @@ class MooncakeStorePyWrapper {
         }
 
         if (!use_dummy_client_) {
-            LOG(ERROR) << context
-                       << ": CUDA IPC tensor read requires a dummy client";
+            if (keys.empty()) return results;
+            // Keep both reads on one snapshot. Re-querying between the prefix
+            // and payload can select a different version after an upsert.
+            PyClient::QueryResultCache snapshot;
+            {
+                py::gil_scoped_release release_gil;
+                auto queries = store_->batch_query(keys);
+                if (queries.size() != keys.size()) {
+                    return std::vector<int64_t>(
+                        keys.size(), to_py_ret(ErrorCode::INTERNAL_ERROR));
+                }
+                snapshot.reserve(keys.size());
+                for (size_t i = 0; i < keys.size(); ++i) {
+                    snapshot.emplace(keys[i], std::move(queries[i]));
+                }
+            }
+            auto metadata = batch_get_tensor_metadata_prefixes(
+                keys, context, &snapshot, &results);
+            std::vector<void *> buffers;
+            std::vector<std::vector<std::string>> all_keys;
+            std::vector<std::vector<std::vector<size_t>>> all_dst_offsets;
+            std::vector<std::vector<std::vector<size_t>>> all_src_offsets;
+            std::vector<std::vector<std::vector<size_t>>> all_sizes;
+            std::vector<size_t> original_indices;
+            buffers.reserve(keys.size());
+            all_keys.reserve(keys.size());
+            all_dst_offsets.reserve(keys.size());
+            all_src_offsets.reserve(keys.size());
+            all_sizes.reserve(keys.size());
+            original_indices.reserve(keys.size());
+
+            for (size_t i = 0; i < keys.size(); ++i) {
+                PyTensorInfo target = extract_tensor_destination_info(
+                    tensors_list[i].cast<py::object>(), keys[i]);
+                if (!target.valid() || !metadata[i].has_value() ||
+                    !tensor_destination_matches_metadata(target, *metadata[i],
+                                                         keys[i], context)) {
+                    continue;
+                }
+                const auto &stored = *metadata[i];
+                if (stored.data_offset >
+                    std::numeric_limits<size_t>::max() - stored.data_bytes) {
+                    LOG(ERROR)
+                        << context << " : tensor range overflows for key "
+                        << keys[i];
+                    continue;
+                }
+                if (stored.data_bytes == 0) {
+                    results[i] = 0;
+                    continue;
+                }
+
+                buffers.push_back(reinterpret_cast<void *>(target.data_ptr));
+                all_keys.push_back({keys[i]});
+                all_dst_offsets.push_back({{0}});
+                all_src_offsets.push_back({{stored.data_offset}});
+                all_sizes.push_back({{stored.data_bytes}});
+                original_indices.push_back(i);
+            }
+
+            if (buffers.empty()) return results;
+
+            std::vector<std::vector<std::vector<int64_t>>> range_results;
+            {
+                py::gil_scoped_release release_gil;
+                range_results = real_client_->get_into_ranges_from_snapshot(
+                    buffers, all_keys, all_dst_offsets, all_src_offsets,
+                    all_sizes, snapshot);
+            }
+            for (size_t i = 0; i < original_indices.size(); ++i) {
+                const size_t original_index = original_indices[i];
+                results[original_index] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+                if (range_results.size() != original_indices.size() ||
+                    range_results[i].size() != 1 ||
+                    range_results[i][0].size() != 1) {
+                    continue;
+                }
+                const int64_t result = range_results[i][0][0];
+                if (result < 0 || static_cast<size_t>(result) ==
+                                      metadata[original_index]->data_bytes) {
+                    results[original_index] = result;
+                }
+            }
             return results;
         }
 
@@ -919,23 +1156,7 @@ class MooncakeStorePyWrapper {
         // Validation & Metadata extraction (GIL Held)
         auto info = extract_tensor_info(tensor, key);
         if (!info.valid()) return to_py_ret(ErrorCode::INVALID_PARAMS);
-        if (use_dummy_client_) {
-            return put_tensor_info_impl(key, info, config);
-        }
-
-        // Prepare spans
-        std::vector<std::span<const char>> values;
-        values.emplace_back(reinterpret_cast<const char *>(&info.metadata),
-                            sizeof(TensorMetadata));
-        append_tensor_payload_span(values, info.data_ptr, info.tensor_size);
-
-        // Store (GIL Released)
-        py::gil_scoped_release release_gil;
-        int ret = store_->put_parts(key, values, config);
-        if (ret != 0)
-            LOG(ERROR) << "put_parts failed for key " << key << " with code "
-                       << ret;
-        return ret;
+        return put_tensor_info_impl(key, info, config);
     }
 
     int put_tensor(const std::string &key, pybind11::object tensor) {
@@ -1049,11 +1270,44 @@ class MooncakeStorePyWrapper {
         return batch_write_tensor_impl(
             keys, infos, config, "put",
             [this](const std::vector<std::string> &write_keys,
-                   const std::vector<void *> &buffer_ptrs,
-                   const std::vector<size_t> &buffer_sizes,
+                   const std::vector<void *> &buffers,
+                   const std::vector<size_t> &sizes,
+                   const ReplicateConfig &write_config) {
+                return store_->batch_put_from(write_keys, buffers, sizes,
+                                              write_config);
+            },
+            [this](const std::vector<std::string> &write_keys,
+                   const std::vector<std::vector<void *>> &buffers,
+                   const std::vector<std::vector<size_t>> &sizes,
+                   const ReplicateConfig &write_config) {
+                return real_client_->batch_put_from_multi_buffers(
+                    write_keys, buffers, sizes, write_config, true);
+            });
+    }
+
+    std::vector<int> batch_upsert_tensor_infos_impl(
+        const std::vector<std::string> &keys,
+        const std::vector<PyTensorInfo> &infos,
+        const ReplicateConfig &config = ReplicateConfig{}) {
+        if (auto cuda_ipc_results = try_dummy_cuda_ipc_batch_upsert_tensor_impl(
+                keys, infos, config)) {
+            return *cuda_ipc_results;
+        }
+        return batch_write_tensor_impl(
+            keys, infos, config, "upsert",
+            [this](const std::vector<std::string> &write_keys,
+                   const std::vector<void *> &buffers,
+                   const std::vector<size_t> &sizes,
                    const ReplicateConfig &write_config) {
-                return store_->batch_put_from(write_keys, buffer_ptrs,
-                                              buffer_sizes, write_config);
+                return store_->batch_upsert_from(write_keys, buffers, sizes,
+                                                 write_config);
+            },
+            [this](const std::vector<std::string> &write_keys,
+                   const std::vector<std::vector<void *>> &buffers,
+                   const std::vector<std::vector<size_t>> &sizes,
+                   const ReplicateConfig &write_config) {
+                return real_client_->batch_upsert_from_multi_buffers(
+                    write_keys, buffers, sizes, write_config, true);
             });
     }
 
@@ -1061,6 +1315,11 @@ class MooncakeStorePyWrapper {
         const std::vector<std::string> &keys,
         const pybind11::list &tensors_list,
         const ReplicateConfig &config = ReplicateConfig{}) {
+        if (pybind11::len(tensors_list) != keys.size()) {
+            LOG(ERROR) << "batch_put_tensor keys and tensors size mismatch";
+            return std::vector<int>(keys.size(),
+                                    to_py_ret(ErrorCode::INVALID_PARAMS));
+        }
         std::vector<PyTensorInfo> infos(keys.size());
         for (size_t i = 0; i < keys.size(); ++i) {
             infos[i] = extract_tensor_info(tensors_list[i], keys[i]);
@@ -1131,6 +1390,15 @@ class MooncakeStorePyWrapper {
                 MakeRepeatedIndexedConfig(config, processed_indices, tp_size);
             std::vector<int> chunk_results = batch_put_tensor_infos_impl(
                 all_chunk_keys, all_chunk_infos, chunk_config);
+            if (chunk_results.size() != all_chunk_keys.size()) {
+                LOG(ERROR) << "Batch put with TP returned "
+                           << chunk_results.size() << " results, expected "
+                           << all_chunk_keys.size();
+                for (size_t index : processed_indices) {
+                    final_results[index] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+                }
+                return final_results;
+            }
 
             for (size_t i = 0; i < processed_indices.size(); ++i) {
                 size_t original_idx = processed_indices[i];
@@ -1175,29 +1443,26 @@ class MooncakeStorePyWrapper {
                                              tp_size, split_dim);
     }
 
-    // Zero-copy put from pre-allocated buffer (layout: [TensorMetadata][data])
+    // Put from a serialized tensor object (layout: [metadata][payload]).
+    // Split the parts so DummyClient can stage external addresses safely.
     int put_tensor_from(const std::string &key, uintptr_t buffer_ptr,
                         size_t size) {
-        if (buffer_ptr == 0) {
-            LOG(ERROR) << "Buffer pointer cannot be null";
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-        void *buffer = reinterpret_cast<void *>(buffer_ptr);
         if (!is_client_initialized()) {
             LOG(ERROR) << "Client is not initialized";
             return to_py_ret(ErrorCode::INVALID_PARAMS);
         }
-        if (size < sizeof(TensorMetadata)) {
-            LOG(ERROR) << "Buffer size too small for tensor metadata";
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-        if (!ParseTensorMetadata(reinterpret_cast<const char *>(buffer), size)
-                 .has_value()) {
-            LOG(ERROR) << "Invalid tensor metadata";
+        auto parts =
+            make_raw_tensor_object_parts(buffer_ptr, size, "put_tensor_from");
+        if (!parts.has_value()) {
             return to_py_ret(ErrorCode::INVALID_PARAMS);
         }
         py::gil_scoped_release release_gil;
-        return store_->put_from(key, buffer, size, ReplicateConfig{});
+        void *payload = parts->payload_size == 0
+                            ? nullptr
+                            : reinterpret_cast<void *>(parts->payload_ptr);
+        return store_->put_from_with_metadata(
+            key, payload, reinterpret_cast<void *>(parts->metadata_ptr),
+            parts->payload_size, parts->metadata_size, ReplicateConfig{});
     }
 
     std::vector<int> batch_put_tensor_from(
@@ -1218,34 +1483,34 @@ class MooncakeStorePyWrapper {
             return std::vector<int>(keys.size(),
                                     to_py_ret(ErrorCode::INVALID_PARAMS));
         }
+        std::vector<RawTensorObjectParts> parts;
+        parts.reserve(keys.size());
         for (size_t i = 0; i < sizes.size(); ++i) {
-            if (buffer_ptrs[i] == 0) {
-                LOG(ERROR) << "Buffer pointer at index " << i
-                           << " cannot be null";
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
-            }
-            if (sizes[i] < sizeof(TensorMetadata)) {
-                LOG(ERROR) << "Buffer size at index " << i
-                           << " too small for tensor metadata";
+            auto parsed = make_raw_tensor_object_parts(buffer_ptrs[i], sizes[i],
+                                                       "batch_put_tensor_from");
+            if (!parsed.has_value()) {
+                LOG(ERROR) << "Invalid tensor object at index " << i;
                 return std::vector<int>(keys.size(),
                                         to_py_ret(ErrorCode::INVALID_PARAMS));
             }
-            if (!ParseTensorMetadata(
-                     reinterpret_cast<const char *>(buffer_ptrs[i]), sizes[i])
-                     .has_value()) {
-                LOG(ERROR) << "Invalid tensor metadata at index " << i;
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
+            parts.emplace_back(std::move(*parsed));
+        }
+        std::vector<std::vector<void *>> buffers;
+        std::vector<std::vector<size_t>> part_sizes;
+        buffers.reserve(parts.size());
+        part_sizes.reserve(parts.size());
+        for (auto &part : parts) {
+            buffers.push_back({reinterpret_cast<void *>(part.metadata_ptr)});
+            part_sizes.push_back({part.metadata_size});
+            if (part.payload_size > 0) {
+                buffers.back().push_back(
+                    reinterpret_cast<void *>(part.payload_ptr));
+                part_sizes.back().push_back(part.payload_size);
             }
         }
-        std::vector<void *> buffers;
-        buffers.reserve(buffer_ptrs.size());
-        for (uintptr_t ptr : buffer_ptrs) {
-            buffers.push_back(reinterpret_cast<void *>(ptr));
-        }
         py::gil_scoped_release release_gil;
-        return store_->batch_put_from(keys, buffers, sizes, ReplicateConfig{});
+        return store_->batch_put_from_multi_buffers(keys, buffers, part_sizes,
+                                                    ReplicateConfig{});
     }
 
     int put_tensor_info_impl(const std::string &key, const PyTensorInfo &info,
@@ -1258,17 +1523,15 @@ class MooncakeStorePyWrapper {
                                    : results[0];
         }
 
-        std::vector<std::span<const char>> values;
-        values.emplace_back(reinterpret_cast<const char *>(&info.metadata),
-                            info.metadata.header.data_offset);
-        append_tensor_payload_span(values, info.data_ptr, info.tensor_size);
-
-        py::gil_scoped_release release_gil;
-        int ret = store_->put_parts(key, values, config);
-        if (ret != 0)
-            LOG(ERROR) << "put_parts failed for key " << key << " with code "
-                       << ret;
-        return ret;
+        auto results = batch_put_tensor_infos_impl(
+            std::vector<std::string>{key}, std::vector<PyTensorInfo>{info},
+            config);
+        if (results.size() != 1) {
+            LOG(ERROR) << "put returned unexpected result count for key "
+                       << key;
+            return to_py_ret(ErrorCode::RPC_FAIL);
+        }
+        return results[0];
     }
 
     int put_manifest_impl(const std::string &key,
@@ -1310,15 +1573,13 @@ class MooncakeStorePyWrapper {
             return put_tensor_from(key, buffer_ptr, size);
         }
 
-        pybind11::object tensor =
-            buffer_to_tensor(NULL, reinterpret_cast<char *>(buffer_ptr),
-                             static_cast<int64_t>(size));
-        if (tensor.is_none()) {
-            LOG(ERROR) << "Failed to decode full tensor buffer for "
-                          "put_tensor_with_tp_from";
+        std::vector<char> host_buffer;
+        auto tensor = decode_raw_tensor_object_for_host(
+            buffer_ptr, size, host_buffer, "put_tensor_with_tp_from");
+        if (!tensor.has_value()) {
             return to_py_ret(ErrorCode::INVALID_PARAMS);
         }
-        return put_tensor_with_tp_impl(key, tensor, ReplicateConfig{}, tp_rank,
+        return put_tensor_with_tp_impl(key, *tensor, ReplicateConfig{}, tp_rank,
                                        tp_size, split_dim);
     }
 
@@ -1348,31 +1609,17 @@ class MooncakeStorePyWrapper {
         py::list tensors_list;
         std::vector<size_t> processed_indices;
         std::vector<int> final_results(base_keys.size(), 0);
+        std::vector<std::vector<char>> host_buffers(base_keys.size());
 
         for (size_t i = 0; i < base_keys.size(); ++i) {
-            if (buffer_ptrs[i] == 0) {
-                LOG(ERROR) << "Buffer pointer at index " << i
-                           << " cannot be null";
-                final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-                continue;
-            }
-            if (sizes[i] < sizeof(TensorMetadata)) {
-                LOG(ERROR) << "Buffer size at index " << i
-                           << " too small for tensor metadata";
+            auto tensor = decode_raw_tensor_object_for_host(
+                buffer_ptrs[i], sizes[i], host_buffers[i],
+                "batch_put_tensor_with_tp_from");
+            if (!tensor.has_value()) {
                 final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
                 continue;
             }
-
-            py::object tensor =
-                buffer_to_tensor(NULL, reinterpret_cast<char *>(buffer_ptrs[i]),
-                                 static_cast<int64_t>(sizes[i]));
-            if (tensor.is_none()) {
-                LOG(ERROR) << "Failed to decode full tensor buffer at index "
-                           << i;
-                final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-                continue;
-            }
-            tensors_list.append(tensor);
+            tensors_list.append(*tensor);
             processed_indices.push_back(i);
         }
 
@@ -1465,38 +1712,22 @@ class MooncakeStorePyWrapper {
                                    : results[0];
         }
 
-        std::vector<std::span<const char>> values;
-        values.emplace_back(reinterpret_cast<const char *>(&info.metadata),
-                            info.metadata.header.data_offset);
-        append_tensor_payload_span(values, info.data_ptr, info.tensor_size);
-
-        py::gil_scoped_release release_gil;
-        int ret = store_->upsert_parts(key, values, config);
-        if (ret != 0)
-            LOG(ERROR) << "upsert_parts failed for key " << key << " with code "
-                       << ret;
-        return ret;
+        auto results = batch_upsert_tensor_infos_impl(
+            std::vector<std::string>{key}, std::vector<PyTensorInfo>{info},
+            config);
+        if (results.size() != 1) {
+            LOG(ERROR) << "upsert returned unexpected result count for key "
+                       << key;
+            return to_py_ret(ErrorCode::RPC_FAIL);
+        }
+        return results[0];
     }
 
     int upsert_tensor_impl(const std::string &key, pybind11::object tensor,
                            const ReplicateConfig &config) {
         auto info = extract_tensor_info(tensor, key);
         if (!info.valid()) return to_py_ret(ErrorCode::INVALID_PARAMS);
-        if (use_dummy_client_) {
-            return upsert_tensor_info_impl(key, info, config);
-        }
-
-        std::vector<std::span<const char>> values;
-        values.emplace_back(reinterpret_cast<const char *>(&info.metadata),
-                            sizeof(TensorMetadata));
-        append_tensor_payload_span(values, info.data_ptr, info.tensor_size);
-
-        py::gil_scoped_release release_gil;
-        int ret = store_->upsert_parts(key, values, config);
-        if (ret != 0)
-            LOG(ERROR) << "upsert_parts failed for key " << key << " with code "
-                       << ret;
-        return ret;
+        return upsert_tensor_info_impl(key, info, config);
     }
 
     int upsert_tensor(const std::string &key, pybind11::object tensor) {
@@ -1519,9 +1750,19 @@ class MooncakeStorePyWrapper {
                 return to_py_ret(ErrorCode::INVALID_PARAMS);
             }
 
+            std::vector<std::string> tp_keys;
+            tp_keys.reserve(tp_size);
             for (int rank = 0; rank < tp_size; ++rank) {
-                int ret = upsert_tensor_info_impl(get_tp_key_name(key, rank),
-                                                  (*infos)[rank], config);
+                tp_keys.push_back(get_tp_key_name(key, rank));
+            }
+            auto results =
+                batch_upsert_tensor_infos_impl(tp_keys, *infos, config);
+            if (results.size() != tp_keys.size()) {
+                LOG(ERROR) << "Upsert with TP returned " << results.size()
+                           << " results, expected " << tp_keys.size();
+                return to_py_ret(ErrorCode::INTERNAL_ERROR);
+            }
+            for (int ret : results) {
                 if (ret != 0) return ret;
             }
             return 0;
@@ -1550,62 +1791,45 @@ class MooncakeStorePyWrapper {
             return std::vector<int>(keys.size(),
                                     to_py_ret(ErrorCode::INVALID_PARAMS));
         }
+        std::vector<RawTensorObjectParts> parts;
+        parts.reserve(keys.size());
         for (size_t i = 0; i < sizes.size(); ++i) {
-            if (buffer_ptrs[i] == 0) {
-                LOG(ERROR) << "Buffer pointer at index " << i
-                           << " cannot be null";
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
-            }
-            if (sizes[i] < sizeof(TensorMetadata)) {
-                LOG(ERROR) << "Buffer size at index " << i
-                           << " too small for tensor metadata";
+            auto parsed = make_raw_tensor_object_parts(
+                buffer_ptrs[i], sizes[i], "batch_upsert_tensor_from");
+            if (!parsed.has_value()) {
+                LOG(ERROR) << "Invalid tensor object at index " << i;
                 return std::vector<int>(keys.size(),
                                         to_py_ret(ErrorCode::INVALID_PARAMS));
             }
-            if (!ParseTensorMetadata(
-                     reinterpret_cast<const char *>(buffer_ptrs[i]), sizes[i])
-                     .has_value()) {
-                LOG(ERROR) << "Invalid tensor metadata at index " << i;
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
+            parts.emplace_back(std::move(*parsed));
+        }
+        std::vector<std::vector<void *>> buffers;
+        std::vector<std::vector<size_t>> part_sizes;
+        buffers.reserve(parts.size());
+        part_sizes.reserve(parts.size());
+        for (auto &part : parts) {
+            buffers.push_back({reinterpret_cast<void *>(part.metadata_ptr)});
+            part_sizes.push_back({part.metadata_size});
+            if (part.payload_size > 0) {
+                buffers.back().push_back(
+                    reinterpret_cast<void *>(part.payload_ptr));
+                part_sizes.back().push_back(part.payload_size);
             }
         }
-        std::vector<void *> buffers;
-        buffers.reserve(buffer_ptrs.size());
-        for (uintptr_t ptr : buffer_ptrs) {
-            buffers.push_back(reinterpret_cast<void *>(ptr));
-        }
         py::gil_scoped_release release_gil;
-        return store_->batch_upsert_from(keys, buffers, sizes,
-                                         ReplicateConfig{});
-    }
-
-    std::vector<int> batch_upsert_tensor_infos_impl(
-        const std::vector<std::string> &keys,
-        const std::vector<PyTensorInfo> &infos,
-        const ReplicateConfig &config = ReplicateConfig{}) {
-        return batch_write_tensor_impl(
-            keys, infos, config, "upsert",
-            [this](const std::vector<std::string> &write_keys,
-                   const std::vector<void *> &buffer_ptrs,
-                   const std::vector<size_t> &buffer_sizes,
-                   const ReplicateConfig &write_config) {
-                return store_->batch_upsert_from(write_keys, buffer_ptrs,
-                                                 buffer_sizes, write_config);
-            });
+        return store_->batch_upsert_from_multi_buffers(
+            keys, buffers, part_sizes, ReplicateConfig{});
     }
 
     std::vector<int> batch_upsert_tensor_impl(
         const std::vector<std::string> &keys,
         const pybind11::list &tensors_list,
         const ReplicateConfig &config = ReplicateConfig{}) {
-        auto group_ids_error = ValidateGroupIdsForBatchConfig(
-            config, keys.size(), "batch_upsert_tensor");
-        if (!group_ids_error.empty()) {
-            return group_ids_error;
+        if (pybind11::len(tensors_list) != keys.size()) {
+            LOG(ERROR) << "batch_upsert_tensor keys and tensors size mismatch";
+            return std::vector<int>(keys.size(),
+                                    to_py_ret(ErrorCode::INVALID_PARAMS));
         }
-
         std::vector<PyTensorInfo> infos(keys.size());
         for (size_t i = 0; i < keys.size(); ++i) {
             infos[i] = extract_tensor_info(tensors_list[i], keys[i]);
@@ -1630,26 +1854,16 @@ class MooncakeStorePyWrapper {
 
     int upsert_tensor_from(const std::string &key, uintptr_t buffer_ptr,
                            size_t size) {
-        if (buffer_ptr == 0) {
-            LOG(ERROR) << "Buffer pointer cannot be null";
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-        void *buffer = reinterpret_cast<void *>(buffer_ptr);
         if (!is_client_initialized()) {
             LOG(ERROR) << "Client is not initialized";
             return to_py_ret(ErrorCode::INVALID_PARAMS);
         }
-        if (size < sizeof(TensorMetadata)) {
-            LOG(ERROR) << "Buffer size too small for tensor metadata";
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-        if (!ParseTensorMetadata(reinterpret_cast<const char *>(buffer), size)
-                 .has_value()) {
-            LOG(ERROR) << "Invalid tensor metadata";
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
+        auto results = batch_upsert_tensor_from({key}, {buffer_ptr}, {size});
+        if (results.size() != 1) {
+            LOG(ERROR) << "Tensor upsert returned unexpected result count";
+            return to_py_ret(ErrorCode::INTERNAL_ERROR);
         }
-        py::gil_scoped_release release_gil;
-        return store_->upsert_from(key, buffer, size, ReplicateConfig{});
+        return results[0];
     }
 
     int validate_replicate_config(
@@ -1900,6 +2114,10 @@ PYBIND11_MODULE(store, m) {
     m.def("_deserialize_tensor", &deserialize_tensor_from_bytes,
           "Deserialize Mooncake tensor metadata plus payload bytes.");
 
+    py::class_<RangedReadSnapshotPy, std::shared_ptr<RangedReadSnapshotPy>>(
+        m, "RangedReadSnapshot",
+        "Reusable metadata snapshot for repeated ranged reads");
+
     // Object data type classification
     py::enum_<ObjectDataType>(m, "ObjectDataType")
         .value("UNKNOWN", ObjectDataType::UNKNOWN)
@@ -1914,12 +2132,19 @@ PYBIND11_MODULE(store, m) {
         .value("GENERAL", ObjectDataType::GENERAL)
         .export_values();
 
+    py::enum_<SoftPinAction>(m, "SoftPinAction")
+        .value("PRESERVE", SoftPinAction::PRESERVE)
+        .value("ENABLE", SoftPinAction::ENABLE)
+        .value("DISABLE", SoftPinAction::DISABLE);
+
     // Define the ReplicateConfig class
     py::class_<ReplicateConfig>(m, "ReplicateConfig")
         .def(py::init<>())
         .def_readwrite("replica_num", &ReplicateConfig::replica_num)
         .def_readwrite("nof_replica_num", &ReplicateConfig::nof_replica_num)
-        .def_readwrite("with_soft_pin", &ReplicateConfig::with_soft_pin)
+        .def_readwrite("dfs_replica_num", &ReplicateConfig::dfs_replica_num)
+        .def_readwrite("soft_pin_action", &ReplicateConfig::soft_pin_action)
+        .def_readwrite("soft_pin_ttl_ms", &ReplicateConfig::soft_pin_ttl_ms)
         .def_readwrite("with_hard_pin", &ReplicateConfig::with_hard_pin)
         .def_readwrite("preferred_segments",
                        &ReplicateConfig::preferred_segments)
@@ -2081,15 +2306,6 @@ PYBIND11_MODULE(store, m) {
                  return self.shm_helper_->free(reinterpret_cast<void *>(ptr));
              });
 
-    py::class_<ParallelAxisSpec>(m, "ParallelAxis")
-        .def(py::init<>())
-        .def_readwrite("kind", &ParallelAxisSpec::kind)
-        .def_readwrite("rank", &ParallelAxisSpec::rank)
-        .def_readwrite("size", &ParallelAxisSpec::size)
-        .def_readwrite("split_dim", &ParallelAxisSpec::split_dim)
-        .def_readwrite("expert_id", &ParallelAxisSpec::expert_id)
-        .def_readwrite("stage_id", &ParallelAxisSpec::stage_id);
-
     auto make_pyclient_capsule =
         [](const std::shared_ptr<PyClient> &store) -> py::object {
         if (!store) {
@@ -2105,34 +2321,6 @@ PYBIND11_MODULE(store, m) {
         return cap;
     };
 
-    py::class_<TensorParallelismSpec>(m, "TensorParallelism")
-        .def(py::init<>())
-        .def_readwrite("axes", &TensorParallelismSpec::axes);
-
-    py::class_<ReadTargetSpec>(m, "ReadTarget")
-        .def(py::init<>())
-        .def_property(
-            "mode",
-            [](const ReadTargetSpec &self) {
-                switch (self.mode) {
-                    case ReadTargetMode::AS_STORED:
-                        return std::string("as_stored");
-                    case ReadTargetMode::SHARD:
-                        return std::string("shard");
-                    case ReadTargetMode::FULL:
-                        return std::string("full");
-                }
-                return std::string("as_stored");
-            },
-            [](ReadTargetSpec &self, const std::string &mode) {
-                auto parsed = parse_read_target_mode(py::str(mode));
-                if (!parsed.has_value()) {
-                    throw std::runtime_error("Unsupported ReadTarget mode");
-                }
-                self.mode = *parsed;
-            })
-        .def_readwrite("parallelism", &ReadTargetSpec::parallelism);
-
     py::class_<MooncakeDistributedNoFRegisterPyWrapper>(
         m, "MooncakeDistributedNoFRegister")
         .def(py::init<>())
@@ -2187,6 +2375,18 @@ PYBIND11_MODULE(store, m) {
 
     py::class_<MooncakeStorePyWrapper>(m, "MooncakeDistributedStore")
         .def(py::init<>())
+        .def(
+            "begin_weight_snapshot",
+            [](MooncakeStorePyWrapper &self, py::object snapshot,
+               py::object adapter) -> py::object {
+                py::object raw_store =
+                    py::cast(&self, py::return_value_policy::reference);
+                return py::module_::import("mooncake.reshard.weight.store")
+                    .attr("begin_weight_snapshot")(raw_store, snapshot,
+                                                   adapter);
+            },
+            py::arg("snapshot"), py::arg("adapter"),
+            "Open a model-weight snapshot writer backed by this Store")
         .def(
             "_get_pyclient_capsule",
             [make_pyclient_capsule](MooncakeStorePyWrapper &self)
@@ -2215,12 +2415,17 @@ PYBIND11_MODULE(store, m) {
                     transfer_engine =
                         engine.cast<std::shared_ptr<TransferEngine>>();
                 }
-                return real_client->setup_real(
-                    local_hostname, metadata_server, global_segment_size,
-                    local_buffer_size, protocol, rdma_devices,
-                    master_server_addr, transfer_engine, "", enable_ssd_offload,
-                    ssd_offload_path, tenant_id, enable_client_http_server,
-                    client_http_port);
+                int ret;
+                {
+                    py::gil_scoped_release release;
+                    ret = real_client->setup_real(
+                        local_hostname, metadata_server, global_segment_size,
+                        local_buffer_size, protocol, rdma_devices,
+                        master_server_addr, transfer_engine, "",
+                        enable_ssd_offload, ssd_offload_path, tenant_id,
+                        enable_client_http_server, client_http_port);
+                }
+                return ret;
             },
             py::arg("local_hostname"), py::arg("metadata_server"),
             py::arg("global_segment_size"), py::arg("local_buffer_size"),
@@ -2243,9 +2448,14 @@ PYBIND11_MODULE(store, m) {
                     config[key] = value;
                 }
 
-                auto result = real_client->setup_internal(config);
-                return result.has_value() ? 0
-                                          : static_cast<int>(result.error());
+                int ret;
+                {
+                    py::gil_scoped_release release;
+                    auto result = real_client->setup_internal(config);
+                    ret = result.has_value() ? 0
+                                             : static_cast<int>(result.error());
+                }
+                return ret;
             },
             py::arg("config"),
             "Setup the store with a configuration dictionary.\n"
@@ -2301,6 +2511,9 @@ PYBIND11_MODULE(store, m) {
         .def("unmount_and_free_segment",
              &MooncakeStorePyWrapper::unmount_and_free_segment,
              py::arg("segment_ids"), py::arg("grace_period_seconds") = 0)
+        .def("unmount_local_disk_segment",
+             &MooncakeStorePyWrapper::unmount_local_disk_segment,
+             py::arg("grace_period_seconds") = 0)
         .def("alloc_from_mem_pool",
              [](MooncakeStorePyWrapper &self, size_t size) {
                  py::gil_scoped_release release;
@@ -2385,6 +2598,29 @@ PYBIND11_MODULE(store, m) {
             py::arg("keys"),
             "Check if multiple objects exist. Returns list of results: 1 if "
             "exists, 0 if not exists, -1 if error")
+        .def(
+            "probe_key",
+            [](MooncakeStorePyWrapper &self, const std::string &key) {
+                py::gil_scoped_release release;
+                return self.store_->probeKey(key);
+            },
+            py::arg("key"),
+            "Point-in-time existence check that grants no read lease. "
+            "Returns 1 if the object existed at the time of the call, 0 if "
+            "not exists, -1 if error. The object may still be evicted "
+            "before a subsequent get.")
+        .def(
+            "batch_probe_key",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                py::gil_scoped_release release;
+                return self.store_->batchProbeKey(keys);
+            },
+            py::arg("keys"),
+            "Point-in-time existence check for multiple objects that grants "
+            "no read leases. Returns list of results: 1 if existed at the "
+            "time of the call, 0 if not exists, -1 if error. Objects may "
+            "still be evicted before a subsequent get.")
         .def("close",
              [](MooncakeStorePyWrapper &self) {
                  if (!self.store_) return 0;
@@ -2571,91 +2807,6 @@ PYBIND11_MODULE(store, m) {
              py::arg("tensors_list"), py::arg("config") = ReplicateConfig{},
              "Batch upsert PyTorch tensors with configurable replication "
              "settings")
-        .def("get_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::get_tensor_with_parallelism,
-             py::arg("key"), py::arg("target") = py::none(),
-             "Get a PyTorch tensor from the store using a ReadTarget request.")
-        .def("batch_get_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::batch_get_tensor_with_parallelism,
-             py::arg("keys"), py::arg("targets") = py::none(),
-             "Get a batch of PyTorch tensors from the store using ReadTarget "
-             "requests.")
-        .def("get_tensor_with_parallelism_into",
-             &MooncakeStorePyWrapper::get_tensor_with_parallelism_into,
-             py::arg("key"), py::arg("buffer_ptr"), py::arg("size"),
-             py::arg("target") = py::none(),
-             "Get a PyTorch tensor from the store directly into a "
-             "pre-allocated buffer using a ReadTarget request.")
-        .def("batch_get_tensor_with_parallelism_into",
-             &MooncakeStorePyWrapper::batch_get_tensor_with_parallelism_into,
-             py::arg("keys"), py::arg("buffer_ptrs"), py::arg("sizes"),
-             py::arg("targets") = py::none(),
-             "Get a batch of PyTorch tensors into pre-allocated buffers using "
-             "ReadTarget requests.")
-        .def("put_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::put_tensor_with_parallelism,
-             py::arg("key"), py::arg("tensor"),
-             py::arg("parallelism") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partition") = py::none(),
-             "Put a PyTorch tensor into the store using a TensorParallelism "
-             "request or a writer_partition request.")
-        .def("batch_put_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::batch_put_tensor_with_parallelism,
-             py::arg("keys"), py::arg("tensors_list"),
-             py::arg("parallelisms") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partitions") = py::none(),
-             "Put a batch of PyTorch tensors into the store using "
-             "TensorParallelism requests or writer_partition requests.")
-        .def("put_tensor_with_parallelism_from",
-             &MooncakeStorePyWrapper::put_tensor_with_parallelism_from,
-             py::arg("key"), py::arg("buffer_ptr"), py::arg("size"),
-             py::arg("parallelism") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partition") = py::none(),
-             "Put a tensor directly from a pre-allocated buffer using a "
-             "TensorParallelism request or a writer_partition request.")
-        .def("batch_put_tensor_with_parallelism_from",
-             &MooncakeStorePyWrapper::batch_put_tensor_with_parallelism_from,
-             py::arg("keys"), py::arg("buffer_ptrs"), py::arg("sizes"),
-             py::arg("parallelisms") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partitions") = py::none(),
-             "Put a batch of tensors directly from pre-allocated buffers using "
-             "TensorParallelism requests or writer_partition requests.")
-        .def("upsert_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::upsert_tensor_with_parallelism,
-             py::arg("key"), py::arg("tensor"),
-             py::arg("parallelism") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partition") = py::none(),
-             "Upsert a PyTorch tensor into the store using a TensorParallelism "
-             "request or a writer_partition request.")
-        .def("upsert_tensor_with_parallelism_from",
-             &MooncakeStorePyWrapper::upsert_tensor_with_parallelism_from,
-             py::arg("key"), py::arg("buffer_ptr"), py::arg("size"),
-             py::arg("parallelism") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partition") = py::none(),
-             "Upsert a tensor directly from a pre-allocated buffer using a "
-             "TensorParallelism request or a writer_partition request.")
-        .def("batch_upsert_tensor_with_parallelism_from",
-             &MooncakeStorePyWrapper::batch_upsert_tensor_with_parallelism_from,
-             py::arg("keys"), py::arg("buffer_ptrs"), py::arg("sizes"),
-             py::arg("parallelisms") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partitions") = py::none(),
-             "Upsert a batch of tensors directly from pre-allocated buffers "
-             "using TensorParallelism requests or writer_partition requests.")
-        .def("batch_upsert_tensor_with_parallelism",
-             &MooncakeStorePyWrapper::batch_upsert_tensor_with_parallelism,
-             py::arg("keys"), py::arg("tensors_list"),
-             py::arg("parallelisms") = py::none(),
-             py::arg("config") = ReplicateConfig{},
-             py::arg("writer_partitions") = py::none(),
-             "Upsert a batch of PyTorch tensors into the store using "
-             "TensorParallelism requests or writer_partition requests.")
         .def(
             "upsert_from",
             [](MooncakeStorePyWrapper &self, const std::string &key,
@@ -2834,6 +2985,60 @@ PYBIND11_MODULE(store, m) {
             py::arg("all_sizes"),
             "Get multiple byte ranges from multiple objects into multiple "
             "pre-allocated buffers")
+        .def(
+            "prepare_get_into_ranges_snapshot",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                if (!self.is_client_initialized()) {
+                    throw std::runtime_error("Client is not initialized");
+                }
+                std::vector<std::string> unique_keys;
+                unique_keys.reserve(keys.size());
+                std::unordered_set<std::string> seen;
+                seen.reserve(keys.size());
+                for (const auto &key : keys) {
+                    if (seen.insert(key).second) unique_keys.push_back(key);
+                }
+                py::gil_scoped_release release;
+                return std::make_shared<RangedReadSnapshotPy>(
+                    self.store_, std::move(unique_keys));
+            },
+            py::arg("keys"),
+            "Prepare a reusable metadata snapshot for ranged reads")
+        .def(
+            "get_into_ranges_from_snapshot",
+            [](MooncakeStorePyWrapper &self,
+               const std::shared_ptr<RangedReadSnapshotPy> &snapshot,
+               const std::vector<uintptr_t> &buffer_ptrs,
+               const std::vector<std::vector<std::string>> &all_keys,
+               const std::vector<std::vector<std::vector<size_t>>>
+                   &all_dst_offsets,
+               const std::vector<std::vector<std::vector<size_t>>>
+                   &all_src_offsets,
+               const std::vector<std::vector<std::vector<size_t>>> &all_sizes) {
+                if (!self.is_client_initialized()) {
+                    throw std::runtime_error("Client is not initialized");
+                }
+                if (!snapshot || !snapshot->belongs_to(self.store_)) {
+                    throw std::invalid_argument(
+                        "Ranged-read snapshot belongs to another Store");
+                }
+                std::vector<void *> buffers;
+                buffers.reserve(buffer_ptrs.size());
+                for (uintptr_t ptr : buffer_ptrs) {
+                    buffers.push_back(reinterpret_cast<void *>(ptr));
+                }
+                py::gil_scoped_release release;
+                return snapshot->get_into_ranges(buffers, all_keys,
+                                                 all_dst_offsets,
+                                                 all_src_offsets, all_sizes);
+            },
+            py::arg("snapshot"), py::arg("buffer_ptrs"), py::arg("all_keys"),
+            py::arg("all_dst_offsets"), py::arg("all_src_offsets"),
+            py::arg("all_sizes"),
+            "Get byte ranges using a reusable metadata snapshot. The "
+            "snapshot is refreshed at the read-lease midpoint before a new "
+            "transfer is submitted.")
         .def(
             "batch_get_into",
             [](MooncakeStorePyWrapper &self,
@@ -3019,6 +3224,111 @@ PYBIND11_MODULE(store, m) {
             "Get object data directly into multiple pre-allocated buffers for "
             "multiple "
             "keys")
+        .def(
+            "batch_get_session_start",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_get_session_start(keys);
+            },
+            py::arg("keys"),
+            "Start a get session: query replicas once and cache them")
+        .def(
+            "batch_get_into_multi_buffer_ranges",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys,
+               const std::vector<std::vector<uintptr_t>> &all_buffer_ptrs,
+               const std::vector<std::vector<size_t>> &all_sizes,
+               const std::vector<std::vector<size_t>> &all_src_offsets) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_get_into_multi_buffer_ranges(
+                    keys, CastAddrs2Ptrs(all_buffer_ptrs), all_sizes,
+                    all_src_offsets);
+            },
+            py::arg("keys"), py::arg("all_buffer_ptrs"), py::arg("all_sizes"),
+            py::arg("all_src_offsets"),
+            "Ranged get into multiple buffers using a get session")
+        .def(
+            "batch_get_session_end",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return -1;
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_get_session_end(keys);
+            },
+            py::arg("keys"),
+            "End a get session and drop cached replica metadata")
+        .def(
+            "batch_put_session_start",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys,
+               const std::vector<size_t> &sizes,
+               const ReplicateConfig &config = ReplicateConfig{}) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_put_session_start(keys, sizes,
+                                                            config);
+            },
+            py::arg("keys"), py::arg("sizes"),
+            py::arg("config") = ReplicateConfig{},
+            "Start a put session: reserve objects without transfer")
+        .def(
+            "batch_put_from_multi_buffer_ranges",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys,
+               const std::vector<std::vector<uintptr_t>> &all_buffer_ptrs,
+               const std::vector<std::vector<size_t>> &all_sizes,
+               const std::vector<std::vector<size_t>> &all_dst_offsets) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_put_from_multi_buffer_ranges(
+                    keys, CastAddrs2Ptrs(all_buffer_ptrs), all_sizes,
+                    all_dst_offsets);
+            },
+            py::arg("keys"), py::arg("all_buffer_ptrs"), py::arg("all_sizes"),
+            py::arg("all_dst_offsets"),
+            "Ranged put from multiple buffers using a put session")
+        .def(
+            "batch_put_session_end",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_put_session_end(keys);
+            },
+            py::arg("keys"), "Complete a put session and make objects readable")
+        .def(
+            "batch_put_session_revoke",
+            [](MooncakeStorePyWrapper &self,
+               const std::vector<std::string> &keys) {
+                if (!self.is_client_initialized()) {
+                    LOG(ERROR) << "Client is not initialized";
+                    return std::vector<int>{};
+                }
+                py::gil_scoped_release release;
+                return self.store_->batch_put_session_revoke(keys);
+            },
+            py::arg("keys"), "Revoke an incomplete put session")
         .def(
             "get_replica_desc",
             [](MooncakeStorePyWrapper &self, const std::string &key) {
diff --git a/mooncake-integration/store/store_py_internal.h b/mooncake-integration/store/store_py_internal.h
index a7d030a4d7..e43c3df105 100644
--- a/mooncake-integration/store/store_py_internal.h
+++ b/mooncake-integration/store/store_py_internal.h
@@ -861,8 +861,11 @@ bool parallelism_specs_equal_by_kind(const TensorParallelismSpec &lhs,
 }
 
 bool is_default_replicate_config(const ReplicateConfig &config) {
-    return config.replica_num == 1 && !config.with_soft_pin &&
-           !config.with_hard_pin && config.preferred_segments.empty() &&
+    return config.replica_num == 1 && config.nof_replica_num == 0 &&
+           config.dfs_replica_num == 0 &&
+           config.soft_pin_action == SoftPinAction::PRESERVE &&
+           !config.soft_pin_ttl_ms.has_value() && !config.with_hard_pin &&
+           config.preferred_segments.empty() &&
            config.preferred_segment.empty() &&
            !config.prefer_alloc_in_same_node && !config.group_ids.has_value();
 }
diff --git a/mooncake-integration/store/store_py_parallel_read.h b/mooncake-integration/store/store_py_parallel_read.h
index 06207cdf55..14f5084840 100644
--- a/mooncake-integration/store/store_py_parallel_read.h
+++ b/mooncake-integration/store/store_py_parallel_read.h
@@ -44,17 +44,18 @@ std::optional<ParsedTensorMetadata> parse_tensor_metadata_from_prefix(
 
 std::vector<CachedQueryResultResponse> batch_query_for_reuse(
     const std::vector<std::string> &keys) {
-    if (auto real_client = get_real_client()) {
-        return real_client->batch_get_query_results(keys);
-    }
-
-    auto query_results = store_->batch_query(keys);
+    auto snapshot = store_->prepare_get_into_ranges_snapshot(keys);
     std::vector<CachedQueryResultResponse> cached_results;
-    cached_results.reserve(query_results.size());
+    cached_results.reserve(keys.size());
     auto now = std::chrono::steady_clock::now();
-    for (const auto &query_result : query_results) {
+    for (const auto &key : keys) {
+        auto it = snapshot.query_result_cache.find(key);
+        if (it == snapshot.query_result_cache.end()) {
+            cached_results.emplace_back(ErrorCode::INVALID_PARAMS);
+            continue;
+        }
         cached_results.push_back(
-            to_cached_query_result_response(query_result, now));
+            to_cached_query_result_response(it->second, now));
     }
     return cached_results;
 }
@@ -80,6 +81,7 @@ load_reconstructed_shard_sources_batch(const std::vector<std::string> &keys,
         return std::nullopt;
     }
 
+    mooncake::PyClient::RangedReadSnapshot snapshot;
     mooncake::PyClient::QueryResultCache query_result_cache;
     auto now = std::chrono::steady_clock::now();
     std::vector<size_t> metadata_key_indices;
@@ -98,6 +100,7 @@ load_reconstructed_shard_sources_batch(const std::vector<std::string> &keys,
         reusable_query_results[i] = cached_query_results[i];
         metadata_key_indices.push_back(i);
     }
+    snapshot.reset(std::move(query_result_cache), now);
 
     std::vector<std::optional<ParsedTensorMetadata>> prefix_metadata(
         keys.size());
@@ -111,6 +114,11 @@ load_reconstructed_shard_sources_batch(const std::vector<std::string> &keys,
                        << ": failed to register metadata scratch buffer";
             return std::nullopt;
         }
+        struct RegisteredScratchBuffer {
+            decltype(store_) store;
+            char *ptr;
+            ~RegisteredScratchBuffer() { store->unregister_buffer(ptr); }
+        } registered_scratch{store_, scratch_buffer.get()};
 
         char *scratch_base = scratch_buffer.get();
         std::vector<void *> metadata_buffers;
@@ -135,10 +143,9 @@ load_reconstructed_shard_sources_batch(const std::vector<std::string> &keys,
         std::vector<std::vector<std::vector<int64_t>>> metadata_results;
         {
             py::gil_scoped_release release_gil;
-            metadata_results = store_->get_into_ranges(
+            metadata_results = store_->get_into_ranges_from_snapshot(
                 metadata_buffers, metadata_all_keys, metadata_all_dst_offsets,
-                metadata_all_src_offsets, metadata_all_sizes,
-                &query_result_cache);
+                metadata_all_src_offsets, metadata_all_sizes, snapshot);
         }
         for (size_t i = 0;
              i < metadata_results.size() && i < metadata_key_indices.size();
@@ -153,7 +160,6 @@ load_reconstructed_shard_sources_batch(const std::vector<std::string> &keys,
                     keys[key_index]);
             }
         }
-        store_->unregister_buffer(scratch_buffer.get());
     }
 
     std::vector<ReconstructedShardSource> sources;
@@ -512,10 +518,9 @@ pybind11::object get_tensor_with_writer_shard_full(const std::string &key,
         nullptr, 0);
 }
 
-pybind11::object get_tensor_with_tp_full(
-    const std::string &key, int tp_rank, int tp_size, int split_dim,
-    const std::string &context,
-    const std::optional<TensorParallelismSpec> &parallelism = std::nullopt) {
+pybind11::object get_tensor_with_tp_full(const std::string &key, int tp_rank,
+                                         int tp_size, int split_dim,
+                                         const std::string &context) {
     if (!is_client_initialized()) {
         LOG(ERROR) << "Client is not initialized";
         return pybind11::none();
@@ -534,10 +539,7 @@ pybind11::object get_tensor_with_tp_full(
     };
 
     auto reconstruction =
-        parallelism.has_value()
-            ? load_parallelism_full_reconstruction_sources(key, *parallelism,
-                                                           context)
-            : load_tp_full_reconstruction_sources(key, axis, context);
+        load_tp_full_reconstruction_sources(key, axis, context);
     if (!reconstruction.has_value()) {
         return pybind11::none();
     }
@@ -772,516 +774,6 @@ std::optional<TensorIntoPlan> build_writer_shard_full_tensor_into_plan(
         reconstruction->allow_empty_fragments);
 }
 
-std::vector<std::string> build_parallelism_shard_read_keys(
-    const std::string &key, const TensorParallelismSpec &canonical_parallelism,
-    size_t tp_axis_index, int shard_count,
-    std::optional<int> split_dim = std::nullopt) {
-    std::vector<std::string> shard_keys;
-    shard_keys.reserve(shard_count);
-    for (int shard_rank = 0; shard_rank < shard_count; ++shard_rank) {
-        auto shard_parallelism = canonical_parallelism;
-        shard_parallelism.axes[tp_axis_index].rank = shard_rank;
-        shard_parallelism.axes[tp_axis_index].size = shard_count;
-        if (split_dim.has_value()) {
-            shard_parallelism.axes[tp_axis_index].split_dim = *split_dim;
-        }
-        shard_keys.push_back(get_parallelism_key_name(key, shard_parallelism));
-    }
-    return shard_keys;
-}
-
-std::optional<FullTensorReconstructionSources>
-load_parallelism_manifest_reconstruction(
-    const std::string &key, const TensorParallelismSpec &parallelism,
-    const std::string &context) {
-    const ParallelAxisSpec *request_tp_axis =
-        find_axis_spec_by_kind(parallelism, LayoutAxisKind::TP);
-    if (!request_tp_axis) {
-        LOG(ERROR) << context << ": reconstruction requires a TP axis";
-        return std::nullopt;
-    }
-
-    auto parsed_manifest = load_parallelism_manifest(key, context);
-    if (!parsed_manifest.has_value()) {
-        return std::nullopt;
-    }
-
-    const auto &manifest = *parsed_manifest;
-    const auto &global_shape = manifest.global_shape;
-    const int split_dim = manifest.manifest.header.split_dim;
-    const int shard_count = manifest.manifest.header.shard_count;
-    if (split_dim < 0 || split_dim >= static_cast<int>(global_shape.size())) {
-        LOG(ERROR) << context << ": invalid parallelism split_dim";
-        return std::nullopt;
-    }
-    if (request_tp_axis->split_dim.has_value() &&
-        request_tp_axis->split_dim.value() != split_dim) {
-        LOG(ERROR) << context << ": split_dim mismatch";
-        return std::nullopt;
-    }
-    if (!is_uniform_shardable_dim(global_shape[split_dim],
-                                  request_tp_axis->size) ||
-        !is_uniform_shardable_dim(global_shape[split_dim], shard_count)) {
-        LOG(ERROR) << context << ": only uniform sharding is supported";
-        return std::nullopt;
-    }
-    auto canonical_parallelism = canonicalize_parallelism_spec(parallelism);
-    if (!canonical_parallelism.has_value()) {
-        LOG(ERROR) << context << ": failed to canonicalize parallelism";
-        return std::nullopt;
-    }
-    auto tp_axis_index = find_tp_axis_index(canonical_parallelism->axes);
-    if (!tp_axis_index.has_value()) {
-        LOG(ERROR) << context << ": missing TP axis in request";
-        return std::nullopt;
-    }
-
-    auto shard_keys = build_parallelism_shard_read_keys(
-        key, *canonical_parallelism, *tp_axis_index, shard_count);
-
-    auto ordered_sources =
-        load_reconstructed_shard_sources_batch(shard_keys, context);
-    if (!ordered_sources.has_value()) {
-        return std::nullopt;
-    }
-
-    FullTensorReconstructionSources reconstruction;
-    reconstruction.global_shape = global_shape;
-    reconstruction.split_dim = split_dim;
-    reconstruction.dtype = manifest.manifest.header.dtype;
-    reconstruction.sources.reserve(shard_count);
-    for (int shard_rank = 0; shard_rank < shard_count; ++shard_rank) {
-        auto shard_parallelism = *canonical_parallelism;
-        shard_parallelism.axes[*tp_axis_index].rank = shard_rank;
-        shard_parallelism.axes[*tp_axis_index].size = shard_count;
-        auto &source = (*ordered_sources)[shard_rank];
-        auto stored_parallelism =
-            resolve_tp_compatible_parallelism_from_metadata(
-                shard_parallelism, source.metadata.metadata, context);
-        if (!stored_parallelism.has_value() ||
-            !parallelism_specs_equal_by_kind(
-                shard_parallelism, *stored_parallelism,
-                true /* allow_tp_rank_mismatch */)) {
-            LOG(ERROR) << context << ": shard metadata mismatch for TP rank "
-                       << shard_rank;
-            return std::nullopt;
-        }
-        reconstruction.sources.push_back(std::move(source));
-    }
-    return reconstruction;
-}
-
-std::optional<FullTensorReconstructionSources>
-load_parallelism_full_reconstruction_sources(
-    const std::string &key, const TensorParallelismSpec &parallelism,
-    const std::string &context) {
-    if (auto manifest_reconstruction =
-            load_parallelism_manifest_reconstruction(key, parallelism, context);
-        manifest_reconstruction.has_value()) {
-        return manifest_reconstruction;
-    }
-
-    const ParallelAxisSpec *request_tp_axis =
-        find_axis_spec_by_kind(parallelism, LayoutAxisKind::TP);
-    if (!request_tp_axis) {
-        LOG(ERROR) << context << ": full reconstruction requires a TP axis";
-        return std::nullopt;
-    }
-
-    auto canonical_parallelism = canonicalize_parallelism_spec(parallelism);
-    if (!canonical_parallelism.has_value()) {
-        LOG(ERROR) << context << ": failed to canonicalize parallelism";
-        return std::nullopt;
-    }
-
-    auto tp_axis_index = find_tp_axis_index(canonical_parallelism->axes);
-    if (!tp_axis_index.has_value()) {
-        LOG(ERROR) << context << ": missing TP axis in request";
-        return std::nullopt;
-    }
-
-    FullTensorReconstructionSources reconstruction;
-    if (uses_legacy_tp_storage_key(*canonical_parallelism)) {
-        const std::string first_key =
-            resolve_tp_read_key(key, 0, request_tp_axis->size);
-        auto first_metadata = get_tensor_metadata(first_key);
-        if (!first_metadata.has_value()) {
-            LOG(ERROR) << context
-                       << ": no shard matched requested layout for TP rank 0";
-            return std::nullopt;
-        }
-        const LayoutAxis *stored_tp_axis =
-            find_layout_axis(first_metadata->metadata, LayoutAxisKind::TP);
-        if (!is_shard_tensor_metadata(first_metadata->metadata) ||
-            !stored_tp_axis) {
-            LOG(ERROR) << context << ": missing TP axis metadata";
-            return std::nullopt;
-        }
-        reconstruction.split_dim = stored_tp_axis->split_dim;
-        if (request_tp_axis->split_dim.has_value() &&
-            request_tp_axis->split_dim.value() != reconstruction.split_dim) {
-            LOG(ERROR) << context << ": split_dim mismatch";
-            return std::nullopt;
-        }
-        reconstruction.global_shape =
-            TensorShapeToVector(first_metadata->metadata.layout.global_shape,
-                                first_metadata->metadata.header.ndim);
-        if (!is_uniform_shardable_dim(
-                reconstruction.global_shape[reconstruction.split_dim],
-                request_tp_axis->size) ||
-            !is_uniform_shardable_dim(
-                reconstruction.global_shape[reconstruction.split_dim],
-                stored_tp_axis->shard_count)) {
-            LOG(ERROR) << context << ": only uniform sharding is supported";
-            return std::nullopt;
-        }
-        reconstruction.dtype = first_metadata->metadata.header.dtype;
-        std::vector<std::string> shard_keys;
-        shard_keys.reserve(stored_tp_axis->shard_count);
-        for (int shard_rank = 0; shard_rank < stored_tp_axis->shard_count;
-             ++shard_rank) {
-            shard_keys.push_back(resolve_tp_read_key(
-                key, shard_rank, stored_tp_axis->shard_count));
-        }
-        auto ordered_sources =
-            load_reconstructed_shard_sources_batch(shard_keys, context);
-        if (!ordered_sources.has_value()) {
-            return std::nullopt;
-        }
-        reconstruction.sources.reserve(stored_tp_axis->shard_count);
-        for (int shard_rank = 0; shard_rank < stored_tp_axis->shard_count;
-             ++shard_rank) {
-            auto &source = (*ordered_sources)[shard_rank];
-            const LayoutAxis *source_tp_axis =
-                find_layout_axis(source.metadata.metadata, LayoutAxisKind::TP);
-            if (!is_shard_tensor_metadata(source.metadata.metadata) ||
-                !source_tp_axis || source_tp_axis->shard_rank != shard_rank ||
-                source_tp_axis->shard_count != stored_tp_axis->shard_count ||
-                source_tp_axis->split_dim != reconstruction.split_dim) {
-                LOG(ERROR) << context
-                           << ": shard metadata mismatch for TP rank "
-                           << shard_rank;
-                return std::nullopt;
-            }
-            reconstruction.sources.push_back(std::move(source));
-        }
-        return reconstruction;
-    }
-
-    auto shard_keys = build_parallelism_shard_read_keys(
-        key, *canonical_parallelism, *tp_axis_index, request_tp_axis->size);
-    auto ordered_sources =
-        load_reconstructed_shard_sources_batch(shard_keys, context);
-    if (!ordered_sources.has_value()) {
-        return std::nullopt;
-    }
-
-    reconstruction.sources.reserve(request_tp_axis->size);
-    for (int shard_rank = 0; shard_rank < request_tp_axis->size; ++shard_rank) {
-        auto shard_parallelism = *canonical_parallelism;
-        shard_parallelism.axes[*tp_axis_index].rank = shard_rank;
-        auto &source = (*ordered_sources)[shard_rank];
-
-        auto stored_parallelism =
-            resolve_tp_compatible_parallelism_from_metadata(
-                shard_parallelism, source.metadata.metadata, context);
-        if (!stored_parallelism.has_value() ||
-            !parallelism_specs_equal_by_kind(
-                *canonical_parallelism, *stored_parallelism,
-                true /* allow_tp_rank_mismatch */)) {
-            LOG(ERROR) << context << ": shard metadata mismatch for TP rank "
-                       << shard_rank;
-            return std::nullopt;
-        }
-        reconstruction.sources.push_back(std::move(source));
-    }
-
-    const LayoutAxis *stored_tp_axis = find_layout_axis(
-        reconstruction.sources.front().metadata.metadata, LayoutAxisKind::TP);
-    if (!stored_tp_axis) {
-        LOG(ERROR) << context << ": missing TP axis metadata";
-        return std::nullopt;
-    }
-    reconstruction.split_dim = stored_tp_axis->split_dim;
-    if (request_tp_axis->split_dim.has_value() &&
-        request_tp_axis->split_dim.value() != reconstruction.split_dim) {
-        LOG(ERROR) << context << ": split_dim mismatch";
-        return std::nullopt;
-    }
-
-    reconstruction.global_shape = TensorShapeToVector(
-        reconstruction.sources.front().metadata.metadata.layout.global_shape,
-        reconstruction.sources.front().metadata.metadata.header.ndim);
-    if (!is_uniform_shardable_dim(
-            reconstruction.global_shape[reconstruction.split_dim],
-            request_tp_axis->size)) {
-        LOG(ERROR) << context << ": only uniform sharding is supported";
-        return std::nullopt;
-    }
-    reconstruction.dtype =
-        reconstruction.sources.front().metadata.metadata.header.dtype;
-    return reconstruction;
-}
-
-bool validate_regular_full_formula_sources(
-    const std::vector<ReconstructedShardSource> &sources,
-    const std::vector<int64_t> &global_shape, int split_dim, int32_t dtype,
-    int shard_count, const std::string &context) {
-    if (sources.size() != static_cast<size_t>(shard_count)) {
-        return false;
-    }
-    for (int shard_rank = 0; shard_rank < shard_count; ++shard_rank) {
-        const auto &source = sources[shard_rank];
-        if (source.metadata.metadata.header.dtype != dtype) {
-            LOG(ERROR) << context << ": shard dtype mismatch for key "
-                       << source.read_key;
-            return false;
-        }
-        const LayoutAxis *tp_axis =
-            find_layout_axis(source.metadata.metadata, LayoutAxisKind::TP);
-        if (!tp_axis || tp_axis->shard_rank != shard_rank ||
-            tp_axis->shard_count != shard_count ||
-            tp_axis->split_dim != split_dim) {
-            LOG(ERROR) << context << ": shard TP metadata mismatch for key "
-                       << source.read_key;
-            return false;
-        }
-        if (!get_source_shard_range(source, global_shape, split_dim, context)
-                 .has_value()) {
-            return false;
-        }
-    }
-    return true;
-}
-
-std::optional<TensorIntoPlan> build_parallelism_full_tensor_into_formula_plan(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const TensorParallelismSpec &parallelism, const std::string &context) {
-    const ParallelAxisSpec *request_tp_axis =
-        find_axis_spec_by_kind(parallelism, LayoutAxisKind::TP);
-    if (!request_tp_axis) {
-        return std::nullopt;
-    }
-
-    auto manifest = load_parallelism_manifest(key, context);
-    if (!manifest.has_value()) {
-        return std::nullopt;
-    }
-    const auto &global_shape = manifest->global_shape;
-    const int split_dim = manifest->manifest.header.split_dim;
-    const int shard_count = manifest->manifest.header.shard_count;
-    if (split_dim < 0 || split_dim >= static_cast<int>(global_shape.size()) ||
-        shard_count <= 0) {
-        return std::nullopt;
-    }
-    if (request_tp_axis->split_dim.has_value() &&
-        request_tp_axis->split_dim.value() != split_dim) {
-        return std::nullopt;
-    }
-    if (!is_uniform_shardable_dim(global_shape[split_dim],
-                                  request_tp_axis->size) ||
-        !is_uniform_shardable_dim(global_shape[split_dim], shard_count)) {
-        return std::nullopt;
-    }
-    auto element_size = TensorDtypeElementSize(manifest->manifest.header.dtype);
-    if (!element_size.has_value()) {
-        return std::nullopt;
-    }
-
-    auto canonical_parallelism = canonicalize_parallelism_spec(parallelism);
-    if (!canonical_parallelism.has_value()) {
-        return std::nullopt;
-    }
-    auto tp_axis_index = find_tp_axis_index(canonical_parallelism->axes);
-    if (!tp_axis_index.has_value()) {
-        return std::nullopt;
-    }
-
-    size_t tensor_numel = 1;
-    for (auto dim : global_shape) {
-        if (dim < 0) {
-            return std::nullopt;
-        }
-        tensor_numel *= static_cast<size_t>(dim);
-    }
-    const size_t tensor_bytes = tensor_numel * *element_size;
-    const size_t total_length = sizeof(TensorMetadata) + tensor_bytes;
-
-    auto region = resolve_writable_buffer_region(buffer_ptr, size, context);
-    if (!region.has_value()) {
-        return std::nullopt;
-    }
-    if (total_length > size || region->offset + total_length > region->size) {
-        LOG(ERROR) << context << ": buffer too small for reconstructed tensor";
-        return std::nullopt;
-    }
-
-    TensorIntoPlan plan;
-    plan.user_buffer_ptr = buffer_ptr;
-    plan.registered_buffer_ptr = reinterpret_cast<uintptr_t>(region->base);
-    plan.registered_buffer_size = region->size;
-    plan.total_length = total_length;
-    plan.materialized_metadata =
-        BuildTensorMetadata(manifest->manifest.header.dtype, global_shape,
-                            global_shape, TensorLayoutKind::FULL);
-    plan.materialized_metadata->header.data_bytes = tensor_bytes;
-
-    TensorIntoRegularFullFormulaPlan formula;
-    formula.global_shape = global_shape;
-    formula.split_dim = split_dim;
-    formula.element_size = *element_size;
-    formula.data_offset = sizeof(TensorMetadata);
-    formula.read_keys = build_parallelism_shard_read_keys(
-        key, *canonical_parallelism, *tp_axis_index, shard_count, split_dim);
-
-    auto sources =
-        load_reconstructed_shard_sources_batch(formula.read_keys, context);
-    if (!sources.has_value() ||
-        !validate_regular_full_formula_sources(
-            *sources, global_shape, split_dim, manifest->manifest.header.dtype,
-            shard_count, context)) {
-        return std::nullopt;
-    }
-    plan.query_results.reserve(sources->size());
-    for (auto &source : *sources) {
-        if (!source.cached_query_result.has_value()) {
-            return std::nullopt;
-        }
-        plan.query_results.push_back(PlannedQueryResult{
-            source.read_key, std::move(*source.cached_query_result)});
-    }
-
-    plan.regular_full_formula = std::move(formula);
-    return plan;
-}
-
-std::optional<TensorIntoPlan> build_parallelism_full_tensor_into_plan(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const TensorParallelismSpec &parallelism, const std::string &context,
-    bool allow_formula_plan = true) {
-    if (allow_formula_plan) {
-        if (auto formula_plan = build_parallelism_full_tensor_into_formula_plan(
-                key, buffer_ptr, size, parallelism, context);
-            formula_plan.has_value()) {
-            return formula_plan;
-        }
-    }
-
-    auto reconstruction =
-        load_parallelism_full_reconstruction_sources(key, parallelism, context);
-    if (!reconstruction.has_value()) {
-        return std::nullopt;
-    }
-    return build_full_tensor_into_plan_from_sources(
-        buffer_ptr, size, reconstruction->sources, reconstruction->global_shape,
-        reconstruction->split_dim, reconstruction->dtype, context,
-        reconstruction->allow_empty_fragments);
-}
-
-std::optional<TensorIntoPlan> build_parallelism_shard_tensor_into_plan(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const TensorParallelismSpec &parallelism, const std::string &context) {
-    auto reconstruction =
-        load_parallelism_full_reconstruction_sources(key, parallelism, context);
-    if (!reconstruction.has_value()) {
-        return std::nullopt;
-    }
-
-    const ParallelAxisSpec *tp_axis =
-        find_axis_spec_by_kind(parallelism, LayoutAxisKind::TP);
-    if (!tp_axis) {
-        LOG(ERROR) << context << ": shard reconstruction requires a TP axis";
-        return std::nullopt;
-    }
-    const auto [target_start, target_extent] = calculate_shard_range(
-        reconstruction->global_shape[reconstruction->split_dim], tp_axis->rank,
-        tp_axis->size);
-    std::vector<int64_t> target_shape = reconstruction->global_shape;
-    target_shape[reconstruction->split_dim] = target_extent;
-    auto target_metadata = build_shard_metadata_from_shapes(
-        reconstruction->dtype, reconstruction->global_shape, target_shape,
-        parallelism.axes, 0);
-    if (!target_metadata.has_value()) {
-        LOG(ERROR) << context << ": failed to build target shard metadata";
-        return std::nullopt;
-    }
-    return build_reconstructed_tensor_into_plan_from_sources(
-        buffer_ptr, size, std::move(reconstruction->sources),
-        reconstruction->global_shape, reconstruction->split_dim,
-        *target_metadata, target_start, target_extent, context,
-        reconstruction->allow_empty_fragments);
-}
-
-pybind11::object get_tensor_with_parallelism_shard_full_materialized(
-    const std::string &key, const TensorParallelismSpec &parallelism,
-    const std::string &context) {
-    auto reconstruction =
-        load_parallelism_full_reconstruction_sources(key, parallelism, context);
-    if (!reconstruction.has_value()) {
-        return py::none();
-    }
-
-    const ParallelAxisSpec *tp_axis =
-        find_axis_spec_by_kind(parallelism, LayoutAxisKind::TP);
-    if (!tp_axis) {
-        LOG(ERROR) << context << ": shard reconstruction requires a TP axis";
-        return py::none();
-    }
-    const auto [target_start, target_extent] = calculate_shard_range(
-        reconstruction->global_shape[reconstruction->split_dim], tp_axis->rank,
-        tp_axis->size);
-
-    auto element_size =
-        extract_reconstruction_element_size(reconstruction->sources, context);
-    if (!element_size.has_value()) {
-        return py::none();
-    }
-
-    size_t target_tensor_numel = 1;
-    for (size_t dim = 0; dim < reconstruction->global_shape.size(); ++dim) {
-        const int64_t dim_extent =
-            static_cast<int>(dim) == reconstruction->split_dim
-                ? target_extent
-                : reconstruction->global_shape[dim];
-        target_tensor_numel *= static_cast<size_t>(dim_extent);
-    }
-    const size_t total_length =
-        sizeof(TensorMetadata) + target_tensor_numel * *element_size;
-
-    char *owned_buffer = new char[total_length];
-    if (store_->register_buffer(owned_buffer, total_length) != 0) {
-        LOG(ERROR) << context << ": failed to register reconstruction buffer";
-        delete[] owned_buffer;
-        return py::none();
-    }
-
-    auto plan = build_parallelism_shard_tensor_into_plan(
-        key, reinterpret_cast<uintptr_t>(owned_buffer), total_length,
-        parallelism, context);
-    if (!plan.has_value()) {
-        store_->unregister_buffer(owned_buffer);
-        delete[] owned_buffer;
-        return py::none();
-    }
-
-    std::vector<TensorIntoPlan> plans;
-    plans.push_back(std::move(*plan));
-    auto success = execute_tensor_into_plan_transfers(plans);
-    if (success.empty() || !success[0]) {
-        store_->unregister_buffer(owned_buffer);
-        delete[] owned_buffer;
-        return py::none();
-    }
-
-    return buffer_to_tensor(
-        new BufferHandle(owned_buffer, total_length,
-                         [this, owned_buffer]() {
-                             store_->unregister_buffer(owned_buffer);
-                             delete[] owned_buffer;
-                         }),
-        nullptr, 0);
-}
-
 std::vector<bool> execute_tensor_into_plan_transfers(
     std::vector<TensorIntoPlan> &plans) {
     std::vector<bool> success(plans.size(), false);
@@ -1294,13 +786,12 @@ std::vector<bool> execute_tensor_into_plan_transfers(
     std::vector<std::vector<std::vector<size_t>>> all_dst_offsets;
     std::vector<std::vector<std::vector<size_t>>> all_src_offsets;
     std::vector<std::vector<std::vector<size_t>>> all_sizes;
+    std::vector<size_t> transfer_plan_indices;
     buffers.reserve(plans.size());
     all_keys.reserve(plans.size());
     all_dst_offsets.reserve(plans.size());
     all_src_offsets.reserve(plans.size());
     all_sizes.reserve(plans.size());
-
-    std::vector<size_t> transfer_plan_indices;
     transfer_plan_indices.reserve(plans.size());
 
     for (size_t plan_idx = 0; plan_idx < plans.size(); ++plan_idx) {
@@ -1310,86 +801,28 @@ std::vector<bool> execute_tensor_into_plan_transfers(
         std::vector<std::vector<size_t>> dst_offsets;
         std::vector<std::vector<size_t>> src_offsets;
         std::vector<std::vector<size_t>> sizes;
-
-        if (plan.regular_full_formula.has_value()) {
-            const auto &formula = *plan.regular_full_formula;
-            keys = formula.read_keys;
-            dst_offsets.resize(keys.size());
-            src_offsets.resize(keys.size());
-            sizes.resize(keys.size());
-
-            int64_t elements_before = 1;
-            for (int i = 0; i < formula.split_dim; ++i) {
-                elements_before *= formula.global_shape[i];
+        key_to_index.reserve(plan.fragments.size());
+        keys.reserve(plan.fragments.size());
+        dst_offsets.reserve(plan.fragments.size());
+        src_offsets.reserve(plan.fragments.size());
+        sizes.reserve(plan.fragments.size());
+
+        for (const auto &fragment : plan.fragments) {
+            if (fragment.read_key.empty() || fragment.size == 0) {
+                continue;
             }
-            int64_t elements_after = 1;
-            for (size_t i = formula.split_dim + 1;
-                 i < formula.global_shape.size(); ++i) {
-                elements_after *= formula.global_shape[i];
-            }
-            const size_t base_dst_offset =
-                plan.user_buffer_ptr - plan.registered_buffer_ptr;
-            const int64_t split_extent =
-                formula.global_shape[formula.split_dim];
-            for (size_t shard_rank = 0; shard_rank < formula.read_keys.size();
-                 ++shard_rank) {
-                const auto [shard_start, shard_extent] = calculate_shard_range(
-                    split_extent, static_cast<int>(shard_rank),
-                    static_cast<int>(formula.read_keys.size()));
-                if (shard_extent <= 0) {
-                    continue;
-                }
-                const size_t row_bytes = static_cast<size_t>(shard_extent) *
-                                         static_cast<size_t>(elements_after) *
-                                         formula.element_size;
-                if (row_bytes == 0) {
-                    continue;
-                }
-                dst_offsets[shard_rank].reserve(
-                    static_cast<size_t>(elements_before));
-                src_offsets[shard_rank].reserve(
-                    static_cast<size_t>(elements_before));
-                sizes[shard_rank].reserve(static_cast<size_t>(elements_before));
-                for (int64_t slice_idx = 0; slice_idx < elements_before;
-                     ++slice_idx) {
-                    dst_offsets[shard_rank].push_back(
-                        base_dst_offset + sizeof(TensorMetadata) +
-                        static_cast<size_t>(slice_idx * split_extent +
-                                            shard_start) *
-                            static_cast<size_t>(elements_after) *
-                            formula.element_size);
-                    src_offsets[shard_rank].push_back(
-                        formula.data_offset +
-                        static_cast<size_t>(slice_idx * shard_extent) *
-                            static_cast<size_t>(elements_after) *
-                            formula.element_size);
-                    sizes[shard_rank].push_back(row_bytes);
-                }
-            }
-        } else {
-            key_to_index.reserve(plan.fragments.size());
-            keys.reserve(plan.fragments.size());
-            dst_offsets.reserve(plan.fragments.size());
-            src_offsets.reserve(plan.fragments.size());
-            sizes.reserve(plan.fragments.size());
-
-            for (const auto &fragment : plan.fragments) {
-                if (fragment.read_key.empty() || fragment.size == 0) {
-                    continue;
-                }
-                auto [it, inserted] =
-                    key_to_index.emplace(fragment.read_key, keys.size());
-                if (inserted) {
-                    keys.push_back(fragment.read_key);
-                    dst_offsets.emplace_back();
-                    src_offsets.emplace_back();
-                    sizes.emplace_back();
-                }
-                const size_t key_index = it->second;
-                dst_offsets[key_index].push_back(fragment.dst_offset);
-                src_offsets[key_index].push_back(fragment.src_offset);
-                sizes[key_index].push_back(fragment.size);
+            auto [it, inserted] =
+                key_to_index.emplace(fragment.read_key, keys.size());
+            if (inserted) {
+                keys.push_back(fragment.read_key);
+                dst_offsets.emplace_back();
+                src_offsets.emplace_back();
+                sizes.emplace_back();
             }
+            const size_t key_index = it->second;
+            dst_offsets[key_index].push_back(fragment.dst_offset);
+            src_offsets[key_index].push_back(fragment.src_offset);
+            sizes[key_index].push_back(fragment.size);
         }
 
         if (keys.empty()) {
@@ -1417,7 +850,7 @@ std::vector<bool> execute_tensor_into_plan_transfers(
     std::vector<std::vector<std::vector<int64_t>>> range_results;
     {
         py::gil_scoped_release release_gil;
-        mooncake::PyClient::QueryResultCache merged_query_result_cache;
+        mooncake::PyClient::QueryResultCache query_result_cache;
         auto now = std::chrono::steady_clock::now();
         for (auto &plan : plans) {
             for (auto &planned_query_result : plan.query_results) {
@@ -1426,17 +859,22 @@ std::vector<bool> execute_tensor_into_plan_transfers(
                 }
                 auto query_result = from_cached_query_result_response(
                     *planned_query_result.cached_query_result, now);
-                if (!query_result || query_result->IsLeaseExpired(now)) {
-                    continue;
+                if (query_result && !query_result->IsLeaseExpired(now)) {
+                    query_result_cache.emplace(planned_query_result.read_key,
+                                               std::move(query_result));
                 }
-                merged_query_result_cache.emplace(planned_query_result.read_key,
-                                                  std::move(query_result));
             }
         }
-        range_results = store_->get_into_ranges(
-            buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes,
-            merged_query_result_cache.empty() ? nullptr
-                                              : &merged_query_result_cache);
+        if (query_result_cache.empty()) {
+            range_results = store_->get_into_ranges(
+                buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes);
+        } else {
+            mooncake::PyClient::RangedReadSnapshot snapshot;
+            snapshot.reset(std::move(query_result_cache), now);
+            range_results = store_->get_into_ranges_from_snapshot(
+                buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes,
+                snapshot);
+        }
     }
 
     for (size_t i = 0; i < transfer_plan_indices.size(); ++i) {
@@ -1445,7 +883,6 @@ std::vector<bool> execute_tensor_into_plan_transfers(
             range_results[i].size() != all_sizes[i].size()) {
             continue;
         }
-
         success[plan_idx] = true;
         for (size_t key_idx = 0;
              key_idx < all_sizes[i].size() && success[plan_idx]; ++key_idx) {
@@ -1454,19 +891,17 @@ std::vector<bool> execute_tensor_into_plan_transfers(
                 success[plan_idx] = false;
                 break;
             }
-            for (size_t frag_idx = 0; frag_idx < all_sizes[i][key_idx].size();
-                 ++frag_idx) {
-                if (range_results[i][key_idx][frag_idx] !=
-                    static_cast<int64_t>(all_sizes[i][key_idx][frag_idx])) {
+            for (size_t fragment_idx = 0;
+                 fragment_idx < all_sizes[i][key_idx].size(); ++fragment_idx) {
+                if (range_results[i][key_idx][fragment_idx] !=
+                    static_cast<int64_t>(all_sizes[i][key_idx][fragment_idx])) {
                     success[plan_idx] = false;
                     break;
                 }
             }
         }
-        if (!success[plan_idx]) {
-            continue;
-        }
-        if (plans[plan_idx].materialized_metadata.has_value()) {
+        if (success[plan_idx] &&
+            plans[plan_idx].materialized_metadata.has_value()) {
             std::memcpy(
                 reinterpret_cast<void *>(plans[plan_idx].user_buffer_ptr),
                 &*plans[plan_idx].materialized_metadata,
@@ -1475,290 +910,3 @@ std::vector<bool> execute_tensor_into_plan_transfers(
     }
     return success;
 }
-
-py::list execute_tensor_into_plans(std::vector<TensorIntoPlan> plans) {
-    py::list results;
-    for (size_t i = 0; i < plans.size(); ++i) {
-        results.append(py::none());
-    }
-    auto success = execute_tensor_into_plan_transfers(plans);
-    for (size_t i = 0; i < plans.size(); ++i) {
-        if (!success[i]) {
-            continue;
-        }
-        results[i] = buffer_to_tensor(
-            NULL, reinterpret_cast<char *>(plans[i].user_buffer_ptr),
-            static_cast<int64_t>(plans[i].total_length));
-    }
-    return results;
-}
-
-std::optional<TensorIntoPlan> build_tensor_into_plan_for_target(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const py::object &target, const std::string &context,
-    bool allow_formula_plan = true) {
-    auto parsed_target = parse_read_target_spec(target);
-    if (!parsed_target.has_value()) {
-        return std::nullopt;
-    }
-    if (parsed_target->mode == ReadTargetMode::AS_STORED &&
-        !parsed_target->parallelism.has_value()) {
-        return build_tensor_into_plan(key, buffer_ptr, size, context);
-    }
-
-    if (parsed_target->mode == ReadTargetMode::FULL &&
-        !parsed_target->parallelism.has_value()) {
-        return build_writer_shard_full_tensor_into_plan(key, buffer_ptr, size,
-                                                        context);
-    }
-
-    auto parallelism =
-        validate_parallelism_spec(parsed_target->parallelism, context, false);
-    if (!parallelism.has_value()) {
-        return std::nullopt;
-    }
-
-    if (parsed_target->mode == ReadTargetMode::SHARD) {
-        auto resolved = resolve_parallelism_shard_read(
-            [this](const std::string &read_key,
-                   std::shared_ptr<BufferHandle> *buffer_handle_out) {
-                return get_tensor_metadata(read_key, buffer_handle_out);
-            },
-            key, *parallelism);
-        if (resolved.has_value()) {
-            return build_tensor_into_plan(resolved->read_key, buffer_ptr, size,
-                                          context, resolved->metadata);
-        }
-        if (find_axis_spec_by_kind(*parallelism, LayoutAxisKind::TP)) {
-            return build_parallelism_shard_tensor_into_plan(
-                key, buffer_ptr, size, *parallelism, context);
-        }
-        LOG(ERROR) << context << ": parallelism metadata mismatch for key "
-                   << key;
-        return std::nullopt;
-    }
-
-    if (parsed_target->mode == ReadTargetMode::FULL) {
-        return build_parallelism_full_tensor_into_plan(
-            key, buffer_ptr, size, *parallelism, context, allow_formula_plan);
-    }
-
-    LOG(ERROR) << context << ": unsupported ReadTarget mode";
-    return std::nullopt;
-}
-
-pybind11::object get_tensor_with_parallelism(
-    const std::string &key, const py::object &target = py::none()) {
-    auto parsed_target = parse_read_target_spec(target);
-    if (!parsed_target.has_value()) {
-        return py::none();
-    }
-    if (parsed_target->mode == ReadTargetMode::AS_STORED &&
-        !parsed_target->parallelism.has_value()) {
-        return get_tensor(key);
-    }
-    if (parsed_target->mode == ReadTargetMode::FULL &&
-        !parsed_target->parallelism.has_value()) {
-        return get_tensor_with_writer_shard_full(key,
-                                                 "get_tensor_with_parallelism");
-    }
-
-    auto parallelism = validate_parallelism_spec(
-        parsed_target->parallelism, "get_tensor_with_parallelism", false);
-    if (!parallelism.has_value()) {
-        return py::none();
-    }
-
-    if (parsed_target->mode == ReadTargetMode::SHARD) {
-        auto resolved = resolve_parallelism_shard_read(
-            [this](const std::string &read_key,
-                   std::shared_ptr<BufferHandle> *buffer_handle_out) {
-                return get_tensor_metadata(read_key, buffer_handle_out);
-            },
-            key, *parallelism);
-        if (resolved.has_value()) {
-            return buffer_to_tensor(resolved->buffer_handle.get(), nullptr, 0);
-        }
-        if (find_axis_spec_by_kind(*parallelism, LayoutAxisKind::TP)) {
-            auto reconstructed =
-                get_tensor_with_parallelism_shard_full_materialized(
-                    key, *parallelism, "get_tensor_with_parallelism");
-            if (!reconstructed.is_none()) {
-                return reconstructed;
-            }
-        }
-        if (uses_legacy_tp_storage_key(*parallelism)) {
-            const auto *tp_axis =
-                find_axis_spec_by_kind(*parallelism, LayoutAxisKind::TP);
-            if (tp_axis) {
-                return get_tensor(
-                    resolve_tp_read_key(key, tp_axis->rank, tp_axis->size));
-            }
-        }
-        LOG(ERROR) << "get_tensor_with_parallelism"
-                   << ": parallelism metadata mismatch for key " << key;
-        return py::none();
-    }
-
-    if (parsed_target->mode == ReadTargetMode::FULL) {
-        const auto *tp_axis =
-            find_axis_spec_by_kind(*parallelism, LayoutAxisKind::TP);
-        if (!tp_axis) {
-            LOG(ERROR) << "get_tensor_with_parallelism"
-                       << ": full reconstruction requires a TP axis";
-            return py::none();
-        }
-        return get_tensor_with_tp_full(
-            key, tp_axis->rank, tp_axis->size, tp_axis->split_dim.value_or(0),
-            "get_tensor_with_parallelism", *parallelism);
-    }
-
-    LOG(ERROR) << "get_tensor_with_parallelism"
-               << ": unsupported ReadTarget mode";
-    return py::none();
-}
-
-pybind11::list batch_get_tensor_with_parallelism(
-    const std::vector<std::string> &keys,
-    const py::object &targets = py::none()) {
-    if (targets.is_none()) {
-        return batch_get_tensor(keys);
-    }
-
-    auto target_list = validate_batch_request_list(
-        targets, keys.size(), "batch_get_tensor_with_parallelism", "targets");
-    if (!target_list.has_value()) {
-        py::list empty;
-        for (size_t i = 0; i < keys.size(); ++i) {
-            empty.append(py::none());
-        }
-        return empty;
-    }
-
-    py::list results;
-    for (size_t i = 0; i < keys.size(); ++i) {
-        results.append(get_tensor_with_parallelism(
-            keys[i], py::reinterpret_borrow<py::object>((*target_list)[i])));
-    }
-    return results;
-}
-
-pybind11::object get_tensor_with_parallelism_into(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const py::object &target = py::none()) {
-    auto plan = build_tensor_into_plan_for_target(
-        key, buffer_ptr, size, target, "get_tensor_with_parallelism_into");
-    if (!plan.has_value()) {
-        return py::none();
-    }
-    const bool used_formula_plan = plan->regular_full_formula.has_value();
-    auto results = execute_tensor_into_plans({*plan});
-    if (!results.empty() && !results[0].is_none()) {
-        return py::reinterpret_borrow<py::object>(results[0]);
-    }
-
-    if (used_formula_plan) {
-        LOG(WARNING)
-            << "get_tensor_with_parallelism_into"
-            << ": formula plan execution failed, falling back to generic path";
-        auto fallback_plan = build_tensor_into_plan_for_target(
-            key, buffer_ptr, size, target, "get_tensor_with_parallelism_into",
-            false /* allow_formula_plan */);
-        if (!fallback_plan.has_value()) {
-            return py::none();
-        }
-        auto fallback_results = execute_tensor_into_plans({*fallback_plan});
-        if (!fallback_results.empty()) {
-            return py::reinterpret_borrow<py::object>(fallback_results[0]);
-        }
-    }
-    return py::none();
-}
-
-pybind11::list batch_get_tensor_with_parallelism_into(
-    const std::vector<std::string> &keys,
-    const std::vector<uintptr_t> &buffer_ptrs, const std::vector<size_t> &sizes,
-    const py::object &targets = py::none()) {
-    py::list empty;
-    for (size_t i = 0; i < keys.size(); ++i) {
-        empty.append(py::none());
-    }
-    if (keys.size() != buffer_ptrs.size() || keys.size() != sizes.size()) {
-        LOG(ERROR)
-            << "batch_get_tensor_with_parallelism_into"
-            << ": keys, buffer_ptrs, and sizes must have the same length";
-        return empty;
-    }
-
-    std::optional<py::list> target_list = std::nullopt;
-    if (!targets.is_none()) {
-        target_list = validate_batch_request_list(
-            targets, keys.size(), "batch_get_tensor_with_parallelism_into",
-            "targets");
-        if (!target_list.has_value()) {
-            return empty;
-        }
-    }
-
-    std::vector<TensorIntoPlan> plans;
-    plans.reserve(keys.size());
-    std::vector<size_t> plan_indices;
-    plan_indices.reserve(keys.size());
-    std::vector<bool> plan_used_formula;
-    plan_used_formula.reserve(keys.size());
-    for (size_t i = 0; i < keys.size(); ++i) {
-        py::object target =
-            target_list.has_value()
-                ? py::reinterpret_borrow<py::object>((*target_list)[i])
-                : py::none();
-        auto plan = build_tensor_into_plan_for_target(
-            keys[i], buffer_ptrs[i], sizes[i], target,
-            "batch_get_tensor_with_parallelism_into");
-        if (!plan.has_value()) {
-            continue;
-        }
-        plan_indices.push_back(i);
-        plan_used_formula.push_back(plan->regular_full_formula.has_value());
-        plans.push_back(std::move(*plan));
-    }
-
-    auto results = execute_tensor_into_plans(std::move(plans));
-    std::vector<TensorIntoPlan> fallback_plans;
-    std::vector<size_t> fallback_indices;
-    fallback_plans.reserve(plan_indices.size());
-    fallback_indices.reserve(plan_indices.size());
-    for (size_t i = 0; i < plan_indices.size() && i < results.size(); ++i) {
-        if (!results[i].is_none() || !plan_used_formula[i]) {
-            empty[plan_indices[i]] = results[i];
-            continue;
-        }
-
-        const size_t original_index = plan_indices[i];
-        LOG(WARNING) << "batch_get_tensor_with_parallelism_into"
-                     << ": formula plan execution failed for key "
-                     << keys[original_index]
-                     << ", falling back to generic path";
-        py::object target = target_list.has_value()
-                                ? py::reinterpret_borrow<py::object>(
-                                      (*target_list)[original_index])
-                                : py::none();
-        auto fallback_plan = build_tensor_into_plan_for_target(
-            keys[original_index], buffer_ptrs[original_index],
-            sizes[original_index], target,
-            "batch_get_tensor_with_parallelism_into",
-            false /* allow_formula_plan */);
-        if (!fallback_plan.has_value()) {
-            continue;
-        }
-        fallback_indices.push_back(original_index);
-        fallback_plans.push_back(std::move(*fallback_plan));
-    }
-
-    auto fallback_results =
-        execute_tensor_into_plans(std::move(fallback_plans));
-    for (size_t i = 0;
-         i < fallback_indices.size() && i < fallback_results.size(); ++i) {
-        empty[fallback_indices[i]] = fallback_results[i];
-    }
-    return empty;
-}
diff --git a/mooncake-integration/store/store_py_parallel_write.h b/mooncake-integration/store/store_py_parallel_write.h
index 9f23e3d501..f07fc5aaef 100644
--- a/mooncake-integration/store/store_py_parallel_write.h
+++ b/mooncake-integration/store/store_py_parallel_write.h
@@ -14,21 +14,45 @@ int write_manifest_impl(const std::string &key,
     return ret;
 }
 
-std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_put_tensor_impl(
+template <typename CudaIpcBatchWriteFn>
+std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_write_tensor_impl(
     const std::vector<std::string> &keys,
-    const std::vector<PyTensorInfo> &infos, const ReplicateConfig &config) {
+    const std::vector<PyTensorInfo> &infos, const ReplicateConfig &config,
+    const char *operation_name, CudaIpcBatchWriteFn &&write_cuda_ipc) {
     if (!use_dummy_client_ || keys.size() != infos.size()) return std::nullopt;
 
+    struct CudaStreamContext {
+        int32_t device_id;
+        uintptr_t stream_handle;
+    };
+    std::vector<std::optional<CudaStreamContext>> cuda_stream_contexts(
+        infos.size());
+    for (size_t i = 0; i < infos.size(); ++i) {
+        const py::object &owner = infos[i].owner;
+        if (!infos[i].valid() || !owner || owner.is_none()) continue;
+
+        try {
+            if (!owner.attr("is_cuda").cast<bool>()) continue;
+            cuda_stream_contexts[i] = CudaStreamContext{
+                .device_id = owner.attr("get_device")().cast<int32_t>(),
+                .stream_handle =
+                    torch_module()
+                        .attr("cuda")
+                        .attr("current_stream")(owner.attr("device"))
+                        .attr("cuda_stream")
+                        .cast<uintptr_t>(),
+            };
+        } catch (const py::error_already_set &) {
+            PyErr_Clear();
+        } catch (const py::cast_error &) {
+            PyErr_Clear();
+        }
+    }
+
     std::vector<int> results(keys.size(), 0);
     py::gil_scoped_release release_gil;
 
-    std::vector<CudaIpcWriteRequest> write_requests;
-    std::vector<size_t> original_indices;
-    std::vector<std::unique_ptr<BufferHandle>> metadata_allocations;
-    write_requests.reserve(infos.size());
-    original_indices.reserve(infos.size());
-    metadata_allocations.reserve(infos.size());
-
+    std::vector<std::optional<CudaIpcBufferHandle>> ipc_payloads(infos.size());
     for (size_t i = 0; i < infos.size(); ++i) {
         if (!infos[i].valid()) {
             results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
@@ -40,6 +64,39 @@ std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_put_tensor_impl(
             reinterpret_cast<const void *>(infos[i].data_ptr),
             infos[i].tensor_size);
         if (!payload) return std::nullopt;
+        ipc_payloads[i] = std::move(*payload);
+    }
+
+    bool stream_context_invalid = false;
+    for (size_t i = 0; i < infos.size(); ++i) {
+        if (!ipc_payloads[i].has_value()) continue;
+        if (!cuda_stream_contexts[i].has_value() ||
+            cuda_stream_contexts[i]->device_id != ipc_payloads[i]->device_id) {
+            results[i] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+            stream_context_invalid = true;
+        }
+    }
+    if (stream_context_invalid) {
+        LOG(ERROR) << "CUDA IPC tensor stream context validation failed";
+        for (size_t i = 0; i < infos.size(); ++i) {
+            if (ipc_payloads[i].has_value()) {
+                results[i] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+            }
+        }
+        return results;
+    }
+
+    std::vector<CudaIpcWriteRequest> write_requests;
+    std::vector<size_t> original_indices;
+    std::vector<std::unique_ptr<BufferHandle>> metadata_allocations;
+    std::vector<std::pair<int32_t, uintptr_t>> unique_streams;
+    write_requests.reserve(infos.size());
+    original_indices.reserve(infos.size());
+    metadata_allocations.reserve(infos.size());
+    unique_streams.reserve(infos.size());
+
+    for (size_t i = 0; i < infos.size(); ++i) {
+        if (!ipc_payloads[i].has_value()) continue;
 
         size_t metadata_size = infos[i].metadata.header.data_offset;
         auto metadata = store_->allocate_client_buffer(metadata_size);
@@ -56,20 +113,44 @@ std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_put_tensor_impl(
                     .ptr = reinterpret_cast<uint64_t>(metadata->ptr()),
                     .size = static_cast<uint64_t>(metadata_size),
                 },
-            .payload = *payload,
+            .payload = *ipc_payloads[i],
         });
         original_indices.push_back(i);
         metadata_allocations.push_back(
             std::make_unique<BufferHandle>(std::move(*metadata)));
+
+        const CudaStreamContext &stream_context = *cuda_stream_contexts[i];
+        bool stream_is_unique = true;
+        for (const auto &[device_id, stream_handle] : unique_streams) {
+            if (device_id == stream_context.device_id &&
+                stream_handle == stream_context.stream_handle) {
+                stream_is_unique = false;
+                break;
+            }
+        }
+        if (stream_is_unique) {
+            unique_streams.emplace_back(stream_context.device_id,
+                                        stream_context.stream_handle);
+        }
     }
 
     if (!write_requests.empty()) {
         ReplicateConfig write_config =
             MakeIndexedConfig(config, original_indices);
         auto dummy_client = std::static_pointer_cast<DummyClient>(store_);
+        for (const auto &[device_id, stream_handle] : unique_streams) {
+            if (!mooncake::device::SynchronizeCudaStream(device_id,
+                                                         stream_handle)) {
+                LOG(ERROR) << "CUDA IPC tensor stream synchronization failed";
+                for (size_t index : original_indices) {
+                    results[index] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+                }
+                return results;
+            }
+        }
         std::vector<int> op_results =
-            dummy_client->batch_put_from_cuda_ipc(write_requests, write_config);
-        if (!apply_indexed_results("put", op_results, original_indices,
+            write_cuda_ipc(dummy_client, write_requests, write_config);
+        if (!apply_indexed_results(operation_name, op_results, original_indices,
                                    results)) {
             return results;
         }
@@ -77,12 +158,59 @@ std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_put_tensor_impl(
     return results;
 }
 
-template <typename BatchWriteFromFn>
-std::vector<int> batch_write_tensor_impl(const std::vector<std::string> &keys,
-                                         const std::vector<PyTensorInfo> &infos,
-                                         const ReplicateConfig &config,
-                                         const char *operation_name,
-                                         BatchWriteFromFn &&batch_write_from) {
+std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_put_tensor_impl(
+    const std::vector<std::string> &keys,
+    const std::vector<PyTensorInfo> &infos, const ReplicateConfig &config) {
+    return try_dummy_cuda_ipc_batch_write_tensor_impl(
+        keys, infos, config, "put",
+        [](auto dummy_client, const auto &requests, const auto &write_config) {
+            return dummy_client->batch_put_from_cuda_ipc(requests,
+                                                         write_config);
+        });
+}
+
+std::optional<std::vector<int>> try_dummy_cuda_ipc_batch_upsert_tensor_impl(
+    const std::vector<std::string> &keys,
+    const std::vector<PyTensorInfo> &infos, const ReplicateConfig &config) {
+    return try_dummy_cuda_ipc_batch_write_tensor_impl(
+        keys, infos, config, "upsert",
+        [](auto dummy_client, const auto &requests, const auto &write_config) {
+            return dummy_client->batch_upsert_from_cuda_ipc(requests,
+                                                            write_config);
+        });
+}
+
+inline void append_tensor_write_buffers(const PyTensorInfo &info,
+                                        std::vector<void *> &buffers,
+                                        std::vector<size_t> &sizes) {
+    buffers.push_back(const_cast<TensorMetadata *>(&info.metadata));
+    sizes.push_back(info.metadata.header.data_offset);
+    if (info.tensor_size > 0) {
+        buffers.push_back(reinterpret_cast<void *>(info.data_ptr));
+        sizes.push_back(info.tensor_size);
+    }
+}
+
+inline void apply_tensor_batch_results(
+    std::vector<int> &results, const std::vector<size_t> &original_indices,
+    const std::vector<int> &op_results, const char *operation_name) {
+    if (op_results.size() != original_indices.size()) {
+        LOG(ERROR) << operation_name << " returned unexpected result count";
+        for (size_t index : original_indices) {
+            results[index] = to_py_ret(ErrorCode::INTERNAL_ERROR);
+        }
+        return;
+    }
+    for (size_t i = 0; i < op_results.size(); ++i)
+        results[original_indices[i]] = op_results[i];
+}
+
+template <typename StagedBatchWriteFn, typename DirectBatchWriteFn>
+std::vector<int> batch_write_tensor_impl(
+    const std::vector<std::string> &keys,
+    const std::vector<PyTensorInfo> &infos, const ReplicateConfig &config,
+    const char *operation_name, StagedBatchWriteFn &&staged_batch_write,
+    DirectBatchWriteFn &&direct_batch_write) {
     if (keys.size() != infos.size()) {
         LOG(ERROR) << operation_name
                    << ": keys and tensor infos must have the same length";
@@ -97,23 +225,86 @@ std::vector<int> batch_write_tensor_impl(const std::vector<std::string> &keys,
     }
 
     std::vector<int> results(keys.size(), 0);
-
     {
         py::gil_scoped_release release_gil;
-        if (!store_->client_buffer_allocator_ && !use_dummy_client_) {
-            LOG(ERROR) << operation_name
-                       << ": client buffer allocator is not available";
+        std::vector<std::string> valid_keys;
+        std::vector<size_t> original_indices;
+        valid_keys.reserve(infos.size());
+        original_indices.reserve(infos.size());
+
+        auto run_staged_write = [&]() -> std::vector<int> {
+            auto runtime_accelerator =
+                mooncake::device::GetAcceleratorRegistry()
+                    .RuntimeAccelerators();
+            std::vector<void *> buffer_ptrs;
+            std::vector<size_t> buffer_sizes;
+            std::vector<std::unique_ptr<BufferHandle>> temp_allocations;
+            buffer_ptrs.reserve(infos.size());
+            buffer_sizes.reserve(infos.size());
+            temp_allocations.reserve(infos.size());
+
+            for (size_t i = 0; i < infos.size(); ++i) {
+                if (!infos[i].valid()) {
+                    results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
+                    continue;
+                }
+
+                size_t total_size =
+                    infos[i].metadata.header.data_offset + infos[i].tensor_size;
+                auto alloc_result = store_->allocate_client_buffer(total_size);
+                if (!alloc_result) {
+                    LOG(ERROR) << "Failed to allocate buffer for "
+                               << operation_name << " key: " << keys[i];
+                    results[i] = to_py_ret(ErrorCode::NO_AVAILABLE_HANDLE);
+                    continue;
+                }
+
+                char *dst = static_cast<char *>(alloc_result->ptr());
+                std::memcpy(dst, &infos[i].metadata,
+                            infos[i].metadata.header.data_offset);
+                if (infos[i].tensor_size > 0) {
+                    if (!runtime_accelerator.CopyToHost(
+                            dst + infos[i].metadata.header.data_offset,
+                            reinterpret_cast<const void *>(infos[i].data_ptr),
+                            infos[i].tensor_size)) {
+                        LOG(ERROR) << "Failed to copy tensor payload for "
+                                   << operation_name << " key: " << keys[i];
+                        results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
+                        continue;
+                    }
+                }
+
+                valid_keys.push_back(keys[i]);
+                buffer_ptrs.push_back(alloc_result->ptr());
+                buffer_sizes.push_back(total_size);
+                original_indices.push_back(i);
+                temp_allocations.push_back(
+                    std::make_unique<BufferHandle>(std::move(*alloc_result)));
+            }
+
+            if (!valid_keys.empty()) {
+                ReplicateConfig write_config =
+                    MakeIndexedConfig(config, original_indices);
+                std::vector<int> op_results = staged_batch_write(
+                    valid_keys, buffer_ptrs, buffer_sizes, write_config);
+                apply_tensor_batch_results(results, original_indices,
+                                           op_results, operation_name);
+            }
+            return results;
+        };
+
+        if (use_dummy_client_) return run_staged_write();
+
+        if (!real_client_) {
+            LOG(ERROR) << operation_name << ": real client is not available";
             return std::vector<int>(keys.size(),
                                     to_py_ret(ErrorCode::INVALID_PARAMS));
         }
-        auto runtime_accelerator =
-            mooncake::device::GetAcceleratorRegistry().RuntimeAccelerators();
 
-        std::vector<std::string> valid_keys;
-        std::vector<void *> buffer_ptrs;
-        std::vector<size_t> buffer_sizes;
-        std::vector<size_t> original_indices;
-        std::vector<std::unique_ptr<BufferHandle>> temp_allocations;
+        std::vector<std::vector<void *>> all_buffers;
+        std::vector<std::vector<size_t>> all_sizes;
+        all_buffers.reserve(infos.size());
+        all_sizes.reserve(infos.size());
 
         for (size_t i = 0; i < infos.size(); ++i) {
             if (!infos[i].valid()) {
@@ -121,49 +312,21 @@ std::vector<int> batch_write_tensor_impl(const std::vector<std::string> &keys,
                 continue;
             }
 
-            size_t total_size =
-                infos[i].metadata.header.data_offset + infos[i].tensor_size;
-            auto alloc_result = store_->allocate_client_buffer(total_size);
-
-            if (!alloc_result) {
-                LOG(ERROR) << "Failed to allocate buffer for " << operation_name
-                           << " key: " << keys[i];
-                results[i] = to_py_ret(ErrorCode::NO_AVAILABLE_HANDLE);
-                continue;
-            }
-
-            char *dst = static_cast<char *>(alloc_result->ptr());
-            std::memcpy(dst, &infos[i].metadata,
-                        infos[i].metadata.header.data_offset);
-            if (infos[i].tensor_size > 0) {
-                if (!runtime_accelerator.CopyToHost(
-                        dst + infos[i].metadata.header.data_offset,
-                        reinterpret_cast<const void *>(infos[i].data_ptr),
-                        infos[i].tensor_size)) {
-                    LOG(ERROR) << "Failed to copy tensor payload for "
-                               << operation_name << " key: " << keys[i];
-                    results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-                    continue;
-                }
-            }
-
+            all_buffers.emplace_back();
+            all_sizes.emplace_back();
+            append_tensor_write_buffers(infos[i], all_buffers.back(),
+                                        all_sizes.back());
             valid_keys.push_back(keys[i]);
-            buffer_ptrs.push_back(alloc_result->ptr());
-            buffer_sizes.push_back(total_size);
             original_indices.push_back(i);
-            temp_allocations.push_back(
-                std::make_unique<BufferHandle>(std::move(*alloc_result)));
         }
 
         if (!valid_keys.empty()) {
             ReplicateConfig write_config =
                 MakeIndexedConfig(config, original_indices);
-            std::vector<int> op_results = batch_write_from(
-                valid_keys, buffer_ptrs, buffer_sizes, write_config);
-            if (!apply_indexed_results(operation_name, op_results,
-                                       original_indices, results)) {
-                return results;
-            }
+            std::vector<int> op_results = direct_batch_write(
+                valid_keys, all_buffers, all_sizes, write_config);
+            apply_tensor_batch_results(results, original_indices, op_results,
+                                       operation_name);
         }
     }
 
@@ -286,1273 +449,9 @@ std::vector<int> execute_batch_tensor_write_from(
     return batch_write_from_fn(keys, buffers, sizes, config);
 }
 
-template <typename DirectWriteFn, typename ParallelismWriteFn,
-          typename WriterPartitionWriteFn>
-std::vector<int> execute_batch_parallelism_write_requests(
-    const std::vector<std::string> &keys, size_t value_count,
-    const py::object &parallelisms, const py::object &writer_partitions,
-    const char *error_context, DirectWriteFn &&direct_write,
-    ParallelismWriteFn &&parallelism_write,
-    WriterPartitionWriteFn &&writer_partition_write) {
-    if (!parallelisms.is_none() && !writer_partitions.is_none()) {
-        LOG(ERROR)
-            << error_context
-            << ": writer_partitions cannot be combined with parallelisms";
-        return std::vector<int>(keys.size(),
-                                to_py_ret(ErrorCode::INVALID_PARAMS));
-    }
-    if (value_count != keys.size()) {
-        LOG(ERROR) << error_context
-                   << ": values and keys must have the same length";
-        return std::vector<int>(keys.size(),
-                                to_py_ret(ErrorCode::INVALID_PARAMS));
-    }
-    if (parallelisms.is_none() && writer_partitions.is_none()) {
-        return direct_write();
-    }
-
-    std::vector<int> results(keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-    if (!parallelisms.is_none()) {
-        auto parallelism_list = validate_batch_parallelism_list(
-            parallelisms, keys.size(), error_context);
-        if (!parallelism_list.has_value()) {
-            return std::vector<int>(keys.size(),
-                                    to_py_ret(ErrorCode::INVALID_PARAMS));
-        }
-        for (size_t i = 0; i < keys.size(); ++i) {
-            results[i] = parallelism_write(i, (*parallelism_list)[i]);
-        }
-        return results;
-    }
-
-    auto writer_partition_list = validate_batch_writer_partition_list(
-        writer_partitions, keys.size(), error_context);
-    if (!writer_partition_list.has_value()) {
-        return std::vector<int>(keys.size(),
-                                to_py_ret(ErrorCode::INVALID_PARAMS));
-    }
-    for (size_t i = 0; i < keys.size(); ++i) {
-        results[i] = writer_partition_write(i, (*writer_partition_list)[i]);
-    }
-    return results;
-}
-
-template <typename DirectWriteFn, typename WriterShardWriteFn,
-          typename LegacyTpWriteFn, typename TpParallelWriteFn,
-          typename GenericShardWriteFn>
-int execute_parallelism_tensor_write_route(
-    const std::string &key, pybind11::object tensor,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config, const char *error_context,
-    DirectWriteFn &&direct_write, WriterShardWriteFn &&writer_shard_write,
-    LegacyTpWriteFn &&legacy_tp_write, TpParallelWriteFn &&tp_parallel_write,
-    GenericShardWriteFn &&generic_shard_write) {
-    switch (request.route) {
-        case ParallelismWriteStorageRoute::DIRECT_FULL_OBJECT:
-            if (!ensure_tensor_write_supported(error_context)) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            if (int validate_result = validate_replicate_config(config);
-                validate_result) {
-                return validate_result;
-            }
-            return direct_write(key, tensor, config);
-        case ParallelismWriteStorageRoute::WRITER_PARTITION_SHARD:
-            if (!request.writer_partition.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            return writer_shard_write(key, tensor, *request.writer_partition,
-                                      config);
-        case ParallelismWriteStorageRoute::LEGACY_SINGLE_TP:
-        case ParallelismWriteStorageRoute::TP_SHARDED_PARALLELISM:
-        case ParallelismWriteStorageRoute::GENERIC_PARALLELISM_SHARD: {
-            if (!request.parallelism.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            switch (request.route) {
-                case ParallelismWriteStorageRoute::LEGACY_SINGLE_TP: {
-                    const auto &axis = request.parallelism->axes[0];
-                    return legacy_tp_write(key, tensor, config, axis.rank,
-                                           axis.size,
-                                           axis.split_dim.value_or(0));
-                }
-                case ParallelismWriteStorageRoute::TP_SHARDED_PARALLELISM: {
-                    auto tp_axis_index =
-                        find_tp_axis_index(request.parallelism->axes);
-                    if (!tp_axis_index.has_value()) {
-                        return to_py_ret(ErrorCode::INVALID_PARAMS);
-                    }
-                    const auto &axis =
-                        request.parallelism->axes[*tp_axis_index];
-                    return tp_parallel_write(
-                        key, tensor, config, axis.rank, axis.size,
-                        axis.split_dim.value_or(0), request.parallelism->axes);
-                }
-                case ParallelismWriteStorageRoute::GENERIC_PARALLELISM_SHARD:
-                    return generic_shard_write(key, tensor,
-                                               *request.parallelism, config);
-                default:
-                    break;
-            }
-            break;
-        }
-    }
-    return to_py_ret(ErrorCode::INVALID_PARAMS);
-}
-
-template <typename WritePartsFn>
-int execute_tensor_parts_write(const std::string &key,
-                               const std::vector<std::span<const char>> &values,
-                               const ReplicateConfig &config,
-                               const TensorWriteStoreOps &ops,
-                               WritePartsFn &&write_parts) {
-    py::gil_scoped_release release_gil;
-    int ret = write_parts(key, values, config);
-    if (ret != 0) {
-        LOG(ERROR) << ops.parts_operation_name << " failed for key " << key
-                   << " with code " << ret;
-    }
-    return ret;
-}
-
-template <typename DirectWriteFn>
-int execute_parallelism_direct_tensor_write_from(const std::string &key,
-                                                 uintptr_t buffer_ptr,
-                                                 size_t size,
-                                                 const ReplicateConfig &config,
-                                                 const char *operation_name,
-                                                 DirectWriteFn &&direct_write) {
-    if (is_default_replicate_config(config)) {
-        return direct_write(key, buffer_ptr, size);
-    }
-    return execute_single_tensor_write_from(
-        operation_name, key, buffer_ptr, size, config,
-        [&](const std::string &write_key, void *buffer, size_t write_size,
-            const ReplicateConfig &write_config) {
-            return direct_write(write_key, reinterpret_cast<uintptr_t>(buffer),
-                                write_size, write_config);
-        });
-}
-
-pybind11::object decode_tensor_object_buffer(uintptr_t buffer_ptr, size_t size,
-                                             const char *operation_name) {
-    if (!is_valid_tensor_object_buffer(buffer_ptr, size, operation_name)) {
-        return py::none();
-    }
-    pybind11::object tensor = buffer_to_tensor(
-        NULL, reinterpret_cast<char *>(buffer_ptr), static_cast<int64_t>(size));
-    if (tensor.is_none()) {
-        LOG(ERROR) << "Failed to decode tensor buffer for " << operation_name;
-    }
-    return tensor;
-}
-
-std::string get_tp_write_shard_key(const std::string &base_key, int rank,
-                                   const std::vector<ParallelAxisSpec> &axes) {
-    if (axes.empty()) {
-        return get_tp_key_name(base_key, rank);
-    }
-    auto shard_axes = axes;
-    auto tp_axis_index = find_tp_axis_index(shard_axes);
-    if (!tp_axis_index.has_value()) {
-        return std::string();
-    }
-    shard_axes[*tp_axis_index].rank = rank;
-    return get_parallelism_key_name(base_key,
-                                    TensorParallelismSpec{shard_axes});
-}
-
-template <typename WriteShardFn>
-int execute_tp_tensor_write_impl(const std::string &key,
-                                 pybind11::object tensor,
-                                 const ReplicateConfig &config, int tp_size,
-                                 int split_dim,
-                                 const std::vector<ParallelAxisSpec> &axes,
-                                 const char *error_context,
-                                 WriteShardFn &&write_shard) {
-    try {
-        auto shard_infos = build_tp_shard_infos(
-            tensor, tp_size, split_dim,
-            [&](int rank) { return get_tp_write_shard_key(key, rank, axes); },
-            axes);
-        if (!shard_infos.has_value()) {
-            LOG(ERROR) << error_context;
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-
-        for (int rank = 0; rank < tp_size; ++rank) {
-            std::string shard_key = get_tp_write_shard_key(key, rank, axes);
-            if (shard_key.empty()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            int ret = write_shard(shard_key, (*shard_infos)[rank], config);
-            if (ret != 0) return ret;
-        }
-        return 0;
-    } catch (const std::exception &e) {
-        LOG(ERROR) << error_context << ": " << e.what();
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-}
-
-template <typename WritePartsFn>
-int execute_tp_tensor_write_from_impl(const std::string &key,
-                                      uintptr_t buffer_ptr, size_t size,
-                                      const ReplicateConfig &config,
-                                      int tp_size, int split_dim,
-                                      const std::vector<ParallelAxisSpec> &axes,
-                                      const char *error_context,
-                                      WritePartsFn &&write_parts) {
-    auto parsed =
-        parse_tensor_metadata_from_raw_buffer(buffer_ptr, size, error_context);
-    if (!parsed.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    for (int rank = 0; rank < tp_size; ++rank) {
-        std::string shard_key = get_tp_write_shard_key(key, rank, axes);
-        if (shard_key.empty()) {
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-
-        auto plan = build_raw_tensor_shard_write_plan(*parsed, split_dim, rank,
-                                                      tp_size, error_context);
-        if (!plan.has_value()) {
-            return to_py_ret(ErrorCode::INVALID_PARAMS);
-        }
-        const auto global_shape = TensorShapeToVector(
-            parsed->metadata.layout.global_shape, parsed->metadata.header.ndim);
-        const auto local_shape = TensorShapeToVector(
-            plan->metadata.layout.local_shape, plan->metadata.header.ndim);
-        if (axes.empty()) {
-            ParallelAxisSpec axis_spec{"tp",      rank,         tp_size,
-                                       split_dim, std::nullopt, std::nullopt};
-            auto metadata = build_shard_metadata_from_shapes(
-                parsed->metadata.header.dtype, global_shape, local_shape,
-                {axis_spec}, plan->metadata.header.data_bytes);
-            if (!metadata.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            plan->metadata = *metadata;
-        } else {
-            auto shard_axes = axes;
-            auto tp_axis_index = find_tp_axis_index(shard_axes);
-            if (!tp_axis_index.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            shard_axes[*tp_axis_index].rank = rank;
-            const auto local_shape = TensorShapeToVector(
-                plan->metadata.layout.local_shape, plan->metadata.header.ndim);
-            auto metadata = build_shard_metadata_from_shapes(
-                parsed->metadata.header.dtype, global_shape, local_shape,
-                shard_axes, plan->metadata.header.data_bytes);
-            if (!metadata.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            plan->metadata = *metadata;
-        }
-
-        std::vector<std::span<const char>> values;
-        values.emplace_back(reinterpret_cast<const char *>(&plan->metadata),
-                            plan->metadata.header.data_offset);
-        for (const auto &[src_offset, part_size] : plan->data_ranges) {
-            values.emplace_back(
-                reinterpret_cast<const char *>(buffer_ptr + src_offset),
-                part_size);
-        }
-        int ret = write_parts(shard_key, values, config);
-        if (ret != 0) {
-            return ret;
-        }
-    }
-    return 0;
-}
-
-template <typename BatchWriteFn>
-std::vector<int> batch_execute_tp_tensor_write_impl(
-    const std::vector<std::string> &base_keys,
-    const pybind11::list &tensors_list, const ReplicateConfig &config,
-    int tp_size, int split_dim, const char *error_context,
-    BatchWriteFn &&batch_write) {
-    std::vector<std::string> all_chunk_keys;
-    std::vector<PyTensorInfo> all_chunk_infos;
-    std::vector<size_t> processed_indices;
-    std::vector<int> final_results(base_keys.size(),
-                                   to_py_ret(ErrorCode::INVALID_PARAMS));
-    try {
-        for (size_t i = 0; i < base_keys.size(); ++i) {
-            py::object tensor = tensors_list[i];
-            if (tensor.is_none()) {
-                final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-                continue;
-            }
-
-            auto shard_infos = build_tp_shard_infos(
-                tensor, tp_size, split_dim,
-                [&](int rank) { return get_tp_key_name(base_keys[i], rank); });
-            if (!shard_infos.has_value()) {
-                final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-                continue;
-            }
-
-            processed_indices.push_back(i);
-            for (int rank = 0; rank < tp_size; ++rank) {
-                all_chunk_keys.push_back(get_tp_key_name(base_keys[i], rank));
-                all_chunk_infos.push_back((*shard_infos)[rank]);
-            }
-        }
-
-        if (all_chunk_keys.empty()) return final_results;
-
-        std::vector<int> chunk_results =
-            batch_write(all_chunk_keys, all_chunk_infos, config);
-        for (size_t i = 0; i < processed_indices.size(); ++i) {
-            size_t original_idx = processed_indices[i];
-            bool all_ok = true;
-            for (int j = 0; j < tp_size; ++j) {
-                int res = chunk_results[i * tp_size + j];
-                if (res != 0) {
-                    final_results[original_idx] = res;
-                    all_ok = false;
-                    break;
-                }
-            }
-            if (all_ok) {
-                final_results[original_idx] = 0;
-            }
-        }
-    } catch (const std::exception &e) {
-        LOG(ERROR) << error_context << ": " << e.what();
-    }
-
-    return final_results;
-}
-
-template <typename BatchTensorWriteFn>
-std::vector<int> batch_decode_tensor_buffers_and_write(
-    const std::vector<std::string> &keys,
-    const std::vector<uintptr_t> &buffer_ptrs, const std::vector<size_t> &sizes,
-    const char *decode_error_context,
-    BatchTensorWriteFn &&batch_tensor_write_fn) {
-    py::list tensors_list;
-    std::vector<size_t> processed_indices;
-    std::vector<int> final_results(keys.size(), 0);
-
-    for (size_t i = 0; i < keys.size(); ++i) {
-        if (!is_valid_tensor_object_buffer(
-                buffer_ptrs[i], sizes[i],
-                std::string("tensor object buffer at index ") +
-                    std::to_string(i))) {
-            final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-            continue;
-        }
-
-        py::object tensor =
-            buffer_to_tensor(NULL, reinterpret_cast<char *>(buffer_ptrs[i]),
-                             static_cast<int64_t>(sizes[i]));
-        if (tensor.is_none()) {
-            LOG(ERROR) << decode_error_context << " at index " << i;
-            final_results[i] = to_py_ret(ErrorCode::INVALID_PARAMS);
-            continue;
-        }
-        tensors_list.append(tensor);
-        processed_indices.push_back(i);
-    }
-
-    if (processed_indices.empty()) {
-        return final_results;
-    }
-
-    std::vector<std::string> valid_keys;
-    valid_keys.reserve(processed_indices.size());
-    for (size_t idx : processed_indices) {
-        valid_keys.push_back(keys[idx]);
-    }
-
-    std::vector<int> op_results =
-        batch_tensor_write_fn(valid_keys, tensors_list);
-    for (size_t i = 0; i < processed_indices.size(); ++i) {
-        final_results[processed_indices[i]] = op_results[i];
-    }
-    return final_results;
-}
-
-template <typename WriteShardFn>
-int execute_direct_parallelism_shard_write_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const TensorParallelismSpec &parallelism, const ReplicateConfig &config,
-    const char *error_context, const TensorWriteStoreOps &ops,
-    WriteShardFn &&write_shard) {
-    auto parsed =
-        parse_tensor_metadata_from_raw_buffer(buffer_ptr, size, error_context);
-    if (!parsed.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    auto metadata = build_shard_metadata_from_shapes(
-        parsed->metadata.header.dtype,
-        TensorShapeToVector(parsed->metadata.layout.global_shape,
-                            parsed->metadata.header.ndim),
-        TensorShapeToVector(parsed->metadata.layout.local_shape,
-                            parsed->metadata.header.ndim),
-        parallelism.axes, parsed->data_bytes);
-    if (!metadata.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    std::string shard_key = get_parallelism_key_name(key, parallelism);
-    std::vector<std::span<const char>> values;
-    values.emplace_back(reinterpret_cast<const char *>(&*metadata),
-                        metadata->header.data_offset);
-    if (parsed->data_bytes > 0) {
-        values.emplace_back(
-            reinterpret_cast<const char *>(buffer_ptr + parsed->data_offset),
-            parsed->data_bytes);
-    }
-    return execute_tensor_parts_write(shard_key, values, config, ops,
-                                      std::forward<WriteShardFn>(write_shard));
-}
-
-template <typename WritePartsFn, typename WriteManifestFn>
-int execute_writer_partition_shard_write_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const WriterPartitionSpec &writer, const ReplicateConfig &config,
-    const char *error_context, const TensorWriteStoreOps &ops,
-    WritePartsFn &&write_parts, WriteManifestFn &&write_manifest) {
-    auto parsed =
-        parse_tensor_metadata_from_raw_buffer(buffer_ptr, size, error_context);
-    if (!parsed.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    auto plan = build_raw_tensor_shard_write_plan(
-        *parsed, writer.split_dim, writer.rank, writer.size, error_context);
-    if (!plan.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    ParallelAxisSpec axis_spec{"tp",         writer.rank,
-                               writer.size,  writer.split_dim,
-                               std::nullopt, std::nullopt};
-    auto metadata = build_shard_metadata_from_shapes(
-        parsed->metadata.header.dtype,
-        TensorShapeToVector(parsed->metadata.layout.global_shape,
-                            parsed->metadata.header.ndim),
-        TensorShapeToVector(plan->metadata.layout.local_shape,
-                            plan->metadata.header.ndim),
-        {axis_spec}, plan->metadata.header.data_bytes);
-    if (!metadata.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    plan->metadata = *metadata;
-
-    std::vector<std::span<const char>> values;
-    values.emplace_back(reinterpret_cast<const char *>(&plan->metadata),
-                        plan->metadata.header.data_offset);
-    for (const auto &[src_offset, part_size] : plan->data_ranges) {
-        values.emplace_back(
-            reinterpret_cast<const char *>(buffer_ptr + src_offset), part_size);
-    }
-
-    int ret = execute_tensor_parts_write(
-        get_writer_shard_key_name(key, writer), values, config, ops,
-        std::forward<WritePartsFn>(write_parts));
-    if (ret != 0) {
-        return ret;
-    }
-    return write_manifest(
-        get_writer_manifest_key_name(key),
-        build_writer_shard_manifest_from_shape(
-            TensorShapeToVector(parsed->metadata.layout.global_shape,
-                                parsed->metadata.header.ndim),
-            parsed->metadata.header.dtype, writer),
-        config);
-}
-
-template <typename DirectFromWriteFn, typename WriterShardFromWriteFn,
-          typename TpShardFromWriteFn, typename GenericShardFromWriteFn,
-          typename TensorRouteWriteFn>
-int execute_parallelism_tensor_write_from_route(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config, const char *error_context,
-    DirectFromWriteFn &&direct_from_write,
-    WriterShardFromWriteFn &&writer_shard_from_write,
-    TpShardFromWriteFn &&tp_shard_from_write,
-    GenericShardFromWriteFn &&generic_shard_from_write,
-    TensorRouteWriteFn &&tensor_route_write) {
-    switch (request.route) {
-        case ParallelismWriteStorageRoute::DIRECT_FULL_OBJECT:
-            return direct_from_write(key, buffer_ptr, size, config);
-        case ParallelismWriteStorageRoute::WRITER_PARTITION_SHARD:
-            if (!request.writer_partition.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            return writer_shard_from_write(key, buffer_ptr, size,
-                                           *request.writer_partition, config);
-        case ParallelismWriteStorageRoute::LEGACY_SINGLE_TP:
-        case ParallelismWriteStorageRoute::TP_SHARDED_PARALLELISM: {
-            if (!request.parallelism.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            auto tp_axis_index = find_tp_axis_index(request.parallelism->axes);
-            if (!tp_axis_index.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            const auto &axis = request.parallelism->axes[*tp_axis_index];
-            const auto axes =
-                request.route == ParallelismWriteStorageRoute::LEGACY_SINGLE_TP
-                    ? std::vector<ParallelAxisSpec>{}
-                    : request.parallelism->axes;
-            return tp_shard_from_write(key, buffer_ptr, size, axis.size,
-                                       axis.split_dim.value_or(0), axes,
-                                       config);
-        }
-        case ParallelismWriteStorageRoute::GENERIC_PARALLELISM_SHARD:
-            if (!request.parallelism.has_value()) {
-                return to_py_ret(ErrorCode::INVALID_PARAMS);
-            }
-            return generic_shard_from_write(key, buffer_ptr, size,
-                                            *request.parallelism, config);
-    }
-
-    pybind11::object tensor =
-        decode_tensor_object_buffer(buffer_ptr, size, error_context);
-    if (tensor.is_none()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return tensor_route_write(key, tensor, request, config);
-}
-
-int put_tensor_with_writer_shards(
-    const std::string &key, pybind11::object tensor,
-    const WriterPartitionSpec &writer,
-    const ReplicateConfig &config = ReplicateConfig{}) {
-    if (!ensure_tensor_write_supported("put_tensor_with_writer_shards")) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    auto writer_info = build_writer_shard_tensor_info(
-        key, tensor, writer, "put_tensor_with_writer_shards");
-    if (!writer_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    int ret =
-        put_tensor_info_impl(writer_info->shard_key, writer_info->info, config);
-    if (ret != 0) {
-        return ret;
-    }
-    return put_manifest_impl(get_writer_manifest_key_name(key),
-                             writer_info->manifest, config);
-}
-
-int put_tensor_parallelism_tp_impl(const std::string &key,
-                                   pybind11::object tensor,
-                                   const ReplicateConfig &config, int tp_rank,
-                                   int tp_size, int split_dim,
-                                   const std::vector<ParallelAxisSpec> &axes) {
-    std::string shard_key = get_tp_write_shard_key(key, tp_rank, axes);
-    if (shard_key.empty()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    auto shard_info = build_direct_parallelism_shard_info(
-        tensor, axes, shard_key, true /* infer_global_shape */);
-    if (!shard_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    int ret = put_tensor_info_impl(shard_key, shard_info->info, config);
-    if (ret != 0) {
-        return ret;
-    }
-    return put_manifest_impl(get_parallelism_manifest_key_name(key),
-                             shard_info->manifest, config);
-}
-
-int put_requested_parallelism_shard(const std::string &key,
-                                    pybind11::object tensor,
-                                    const TensorParallelismSpec &parallelism,
-                                    const ReplicateConfig &config) {
-    std::string shard_key = get_parallelism_key_name(key, parallelism);
-    auto shard_info = build_requested_parallelism_shard_info(
-        tensor, parallelism, shard_key, "put_tensor_with_parallelism");
-    if (!shard_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    int ret = put_tensor_info_impl(shard_key, shard_info->info, config);
-    if (ret != 0) {
-        return ret;
-    }
-    return put_manifest_impl(get_parallelism_manifest_key_name(key),
-                             shard_info->manifest, config);
-}
-
-int put_direct_parallelism_shard(const std::string &key,
-                                 pybind11::object tensor,
-                                 const TensorParallelismSpec &parallelism,
-                                 const ReplicateConfig &config) {
-    auto tp_axis_index = find_tp_axis_index(parallelism.axes);
-    if (tp_axis_index.has_value() && parallelism.axes.size() > 1) {
-        return put_requested_parallelism_shard(key, tensor, parallelism,
-                                               config);
-    }
-    auto info =
-        build_direct_parallelism_shard_info(tensor, parallelism.axes, key);
-    if (!info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return put_tensor_info_impl(get_parallelism_key_name(key, parallelism),
-                                *info, config);
-}
-
-int put_tensor_with_writer_shards_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const WriterPartitionSpec &writer,
-    const ReplicateConfig &config = ReplicateConfig{}) {
-    return execute_writer_partition_shard_write_from(
-        key, buffer_ptr, size, writer, config,
-        "put_tensor_with_parallelism_from", TensorWriteStoreOps{"put_parts"},
-        [this](const std::string &shard_key,
-               const std::vector<std::span<const char>> &values,
-               const ReplicateConfig &write_config) {
-            return store_->put_parts(shard_key, values, write_config);
-        },
-        [this](const std::string &manifest_key,
-               const WriterShardManifest &manifest,
-               const ReplicateConfig &write_config) {
-            return put_manifest_impl(manifest_key, manifest, write_config);
-        });
-}
-
-int put_direct_parallelism_shard_from(const std::string &key,
-                                      uintptr_t buffer_ptr, size_t size,
-                                      const TensorParallelismSpec &parallelism,
-                                      const ReplicateConfig &config) {
-    return execute_direct_parallelism_shard_write_from(
-        key, buffer_ptr, size, parallelism, config,
-        "put_tensor_with_parallelism_from", TensorWriteStoreOps{"put_parts"},
-        [this](const std::string &shard_key,
-               const std::vector<std::span<const char>> &values,
-               const ReplicateConfig &write_config) {
-            return store_->put_parts(shard_key, values, write_config);
-        });
-}
-
-int execute_put_tensor_with_parallelism_route(
-    const std::string &key, pybind11::object tensor,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config) {
-    return execute_parallelism_tensor_write_route(
-        key, tensor, request, config, "put_tensor_with_parallelism",
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config) {
-            return put_tensor_impl(write_key, write_tensor, write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const WriterPartitionSpec &writer,
-               const ReplicateConfig &write_config) {
-            return put_tensor_with_writer_shards(write_key, write_tensor,
-                                                 writer, write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config, int rank, int size,
-               int split_dim) {
-            return put_tensor_with_tp_impl(write_key, write_tensor,
-                                           write_config, rank, size, split_dim);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config, int rank, int size,
-               int split_dim, const std::vector<ParallelAxisSpec> &axes) {
-            if (axes.size() == 1) {
-                return put_tensor_parallelism_tp_impl(write_key, write_tensor,
-                                                      write_config, rank, size,
-                                                      split_dim, axes);
-            }
-            return put_requested_parallelism_shard(write_key, write_tensor,
-                                                   TensorParallelismSpec{axes},
-                                                   write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const TensorParallelismSpec &parallelism_spec,
-               const ReplicateConfig &write_config) {
-            return put_direct_parallelism_shard(write_key, write_tensor,
-                                                parallelism_spec, write_config);
-        });
-}
-
-int put_tensor_with_parallelism(
-    const std::string &key, pybind11::object tensor,
-    const py::object &parallelism = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partition = py::none()) {
-    auto request = resolve_parallelism_write_request(
-        parallelism, writer_partition, "put_tensor_with_parallelism");
-    if (!request.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return execute_put_tensor_with_parallelism_route(key, tensor, *request,
-                                                     config);
-}
-
-std::vector<int> batch_put_tensor_with_parallelism(
-    const std::vector<std::string> &keys, const pybind11::list &tensors_list,
-    const py::object &parallelisms = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partitions = py::none()) {
-    auto group_ids_error = ValidateGroupIdsForBatchConfig(
-        config, keys.size(), "batch_put_tensor_with_parallelism");
-    if (!group_ids_error.empty()) {
-        return group_ids_error;
-    }
-
-    return execute_batch_parallelism_write_requests(
-        keys, tensors_list.size(), parallelisms, writer_partitions,
-        "batch_put_tensor_with_parallelism",
-        [this, &keys, &tensors_list, &config]() {
-            if (!is_client_initialized()) {
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
-            }
-            int validate_result = validate_replicate_config(config);
-            if (validate_result) {
-                return std::vector<int>(keys.size(), validate_result);
-            }
-            return batch_put_tensor_impl(keys, tensors_list, config);
-        },
-        [this, &keys, &tensors_list, &config](size_t i,
-                                              const py::handle &parallelism) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return put_tensor_with_parallelism(
-                keys[i], tensors_list[i],
-                py::reinterpret_borrow<py::object>(parallelism), key_config);
-        },
-        [this, &keys, &tensors_list, &config](
-            size_t i, const py::handle &writer_partition) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return put_tensor_with_parallelism(
-                keys[i], tensors_list[i], py::none(), key_config,
-                py::reinterpret_borrow<py::object>(writer_partition));
-        });
-}
-
 bool is_valid_tensor_object_buffer(uintptr_t buffer_ptr, size_t size,
                                    const std::string &op_name) {
     return parse_tensor_metadata_from_raw_buffer(buffer_ptr, size,
                                                  op_name.c_str())
         .has_value();
 }
-
-int execute_put_tensor_with_parallelism_from_route(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config) {
-    return execute_parallelism_tensor_write_from_route(
-        key, buffer_ptr, size, request, config,
-        "put_tensor_with_parallelism_from",
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const ReplicateConfig &write_config) {
-            if (!is_default_replicate_config(write_config)) {
-                if (!is_valid_tensor_object_buffer(
-                        write_buffer_ptr, write_size,
-                        "put_tensor_with_parallelism_from")) {
-                    return to_py_ret(ErrorCode::INVALID_PARAMS);
-                }
-                if (!ensure_tensor_write_supported(
-                        "put_tensor_with_parallelism_from")) {
-                    return to_py_ret(ErrorCode::INVALID_PARAMS);
-                }
-                int validate_result = validate_replicate_config(write_config);
-                if (validate_result) return validate_result;
-                py::gil_scoped_release release_gil;
-                return store_->put_from(
-                    write_key, reinterpret_cast<void *>(write_buffer_ptr),
-                    write_size, write_config);
-            }
-            return put_tensor_from(write_key, write_buffer_ptr, write_size);
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const WriterPartitionSpec &writer,
-               const ReplicateConfig &write_config) {
-            return put_tensor_with_writer_shards_from(
-                write_key, write_buffer_ptr, write_size, writer, write_config);
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, int tp_size, int split_dim,
-               const std::vector<ParallelAxisSpec> &axes,
-               const ReplicateConfig &write_config) {
-            return execute_tp_tensor_write_from_impl(
-                write_key, write_buffer_ptr, write_size, write_config, tp_size,
-                split_dim, axes, "put_tensor_with_parallelism_from",
-                [this](const std::string &shard_key,
-                       const std::vector<std::span<const char>> &values,
-                       const ReplicateConfig &parts_config) {
-                    py::gil_scoped_release release_gil;
-                    int ret =
-                        store_->put_parts(shard_key, values, parts_config);
-                    if (ret != 0) {
-                        LOG(ERROR) << "put_parts failed for key " << shard_key
-                                   << " with code " << ret;
-                    }
-                    return ret;
-                });
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const TensorParallelismSpec &parallelism_spec,
-               const ReplicateConfig &write_config) {
-            return put_direct_parallelism_shard_from(
-                write_key, write_buffer_ptr, write_size, parallelism_spec,
-                write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ResolvedParallelismWriteRequest &write_request,
-               const ReplicateConfig &write_config) {
-            return execute_put_tensor_with_parallelism_route(
-                write_key, write_tensor, write_request, write_config);
-        });
-}
-
-int put_tensor_with_parallelism_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const py::object &parallelism = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partition = py::none()) {
-    auto request = resolve_parallelism_write_request(
-        parallelism, writer_partition, "put_tensor_with_parallelism_from");
-    if (!request.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return execute_put_tensor_with_parallelism_from_route(key, buffer_ptr, size,
-                                                          *request, config);
-}
-
-std::vector<int> batch_put_tensor_with_parallelism_from(
-    const std::vector<std::string> &keys,
-    const std::vector<uintptr_t> &buffer_ptrs, const std::vector<size_t> &sizes,
-    const py::object &parallelisms = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partitions = py::none()) {
-    auto group_ids_error = ValidateGroupIdsForBatchConfig(
-        config, keys.size(), "batch_put_tensor_with_parallelism_from");
-    if (!group_ids_error.empty()) {
-        return group_ids_error;
-    }
-
-    return execute_batch_parallelism_write_requests(
-        keys, buffer_ptrs.size(), parallelisms, writer_partitions,
-        "batch_put_tensor_with_parallelism_from",
-        [this, &keys, &buffer_ptrs, &sizes, &config]() {
-            if (!is_default_replicate_config(config)) {
-                if (!is_client_initialized()) {
-                    return std::vector<int>(
-                        keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                }
-                int validate_result = validate_replicate_config(config);
-                if (validate_result) {
-                    return std::vector<int>(keys.size(), validate_result);
-                }
-                if (keys.size() != buffer_ptrs.size() ||
-                    keys.size() != sizes.size()) {
-                    LOG(ERROR) << "Size mismatch: keys, buffer_ptrs, and sizes "
-                                  "must have the same length";
-                    return std::vector<int>(
-                        keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                }
-                for (size_t i = 0; i < sizes.size(); ++i) {
-                    if (!is_valid_tensor_object_buffer(
-                            buffer_ptrs[i], sizes[i],
-                            "tensor object buffer at index " +
-                                std::to_string(i))) {
-                        return std::vector<int>(
-                            keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                    }
-                }
-                std::vector<void *> buffers;
-                buffers.reserve(buffer_ptrs.size());
-                for (uintptr_t ptr : buffer_ptrs) {
-                    buffers.push_back(reinterpret_cast<void *>(ptr));
-                }
-                py::gil_scoped_release release_gil;
-                return store_->batch_put_from(keys, buffers, sizes, config);
-            }
-            return batch_put_tensor_from(keys, buffer_ptrs, sizes);
-        },
-        [this, &keys, &buffer_ptrs, &sizes, &config](
-            size_t i, const py::handle &parallelism) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return put_tensor_with_parallelism_from(
-                keys[i], buffer_ptrs[i], sizes[i],
-                py::reinterpret_borrow<py::object>(parallelism), key_config);
-        },
-        [this, &keys, &buffer_ptrs, &sizes, &config](
-            size_t i, const py::handle &writer_partition) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return put_tensor_with_parallelism_from(
-                keys[i], buffer_ptrs[i], sizes[i], py::none(), key_config,
-                py::reinterpret_borrow<py::object>(writer_partition));
-        });
-}
-
-int upsert_tensor_with_writer_shards(
-    const std::string &key, pybind11::object tensor,
-    const WriterPartitionSpec &writer,
-    const ReplicateConfig &config = ReplicateConfig{}) {
-    if (!ensure_tensor_write_supported("upsert_tensor_with_writer_shards")) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    auto writer_info = build_writer_shard_tensor_info(
-        key, tensor, writer, "upsert_tensor_with_parallelism");
-    if (!writer_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-
-    int ret = upsert_tensor_info_impl(writer_info->shard_key, writer_info->info,
-                                      config);
-    if (ret != 0) {
-        return ret;
-    }
-    return upsert_manifest_impl(get_writer_manifest_key_name(key),
-                                writer_info->manifest, config);
-}
-
-int upsert_tensor_parallelism_tp_impl(
-    const std::string &key, pybind11::object tensor,
-    const ReplicateConfig &config, int tp_rank, int tp_size, int split_dim,
-    const std::vector<ParallelAxisSpec> &axes) {
-    std::string shard_key = get_tp_write_shard_key(key, tp_rank, axes);
-    if (shard_key.empty()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    auto shard_info = build_direct_parallelism_shard_info(
-        tensor, axes, shard_key, true /* infer_global_shape */);
-    if (!shard_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    int ret = upsert_tensor_info_impl(shard_key, shard_info->info, config);
-    if (ret != 0) {
-        return ret;
-    }
-    return upsert_manifest_impl(get_parallelism_manifest_key_name(key),
-                                shard_info->manifest, config);
-}
-
-int upsert_requested_parallelism_shard(const std::string &key,
-                                       pybind11::object tensor,
-                                       const TensorParallelismSpec &parallelism,
-                                       const ReplicateConfig &config) {
-    std::string shard_key = get_parallelism_key_name(key, parallelism);
-    auto shard_info = build_requested_parallelism_shard_info(
-        tensor, parallelism, shard_key, "upsert_tensor_with_parallelism");
-    if (!shard_info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    int ret = upsert_tensor_info_impl(shard_key, shard_info->info, config);
-    if (ret != 0) {
-        return ret;
-    }
-    return upsert_manifest_impl(get_parallelism_manifest_key_name(key),
-                                shard_info->manifest, config);
-}
-
-int upsert_direct_parallelism_shard(const std::string &key,
-                                    pybind11::object tensor,
-                                    const TensorParallelismSpec &parallelism,
-                                    const ReplicateConfig &config) {
-    auto tp_axis_index = find_tp_axis_index(parallelism.axes);
-    if (tp_axis_index.has_value() && parallelism.axes.size() > 1) {
-        return upsert_requested_parallelism_shard(key, tensor, parallelism,
-                                                  config);
-    }
-    auto info =
-        build_direct_parallelism_shard_info(tensor, parallelism.axes, key);
-    if (!info.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return upsert_tensor_info_impl(get_parallelism_key_name(key, parallelism),
-                                   *info, config);
-}
-
-int upsert_tensor_with_writer_shards_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const WriterPartitionSpec &writer,
-    const ReplicateConfig &config = ReplicateConfig{}) {
-    return execute_writer_partition_shard_write_from(
-        key, buffer_ptr, size, writer, config,
-        "upsert_tensor_with_parallelism_from",
-        TensorWriteStoreOps{"upsert_parts"},
-        [this](const std::string &shard_key,
-               const std::vector<std::span<const char>> &values,
-               const ReplicateConfig &write_config) {
-            return store_->upsert_parts(shard_key, values, write_config);
-        },
-        [this](const std::string &manifest_key,
-               const WriterShardManifest &manifest,
-               const ReplicateConfig &write_config) {
-            return upsert_manifest_impl(manifest_key, manifest, write_config);
-        });
-}
-
-int upsert_direct_parallelism_shard_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const TensorParallelismSpec &parallelism, const ReplicateConfig &config) {
-    return execute_direct_parallelism_shard_write_from(
-        key, buffer_ptr, size, parallelism, config,
-        "upsert_tensor_with_parallelism_from",
-        TensorWriteStoreOps{"upsert_parts"},
-        [this](const std::string &shard_key,
-               const std::vector<std::span<const char>> &values,
-               const ReplicateConfig &write_config) {
-            return store_->upsert_parts(shard_key, values, write_config);
-        });
-}
-
-int execute_upsert_tensor_with_parallelism_route(
-    const std::string &key, pybind11::object tensor,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config) {
-    return execute_parallelism_tensor_write_route(
-        key, tensor, request, config, "upsert_tensor_with_parallelism",
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config) {
-            return upsert_tensor_impl(write_key, write_tensor, write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const WriterPartitionSpec &writer,
-               const ReplicateConfig &write_config) {
-            return upsert_tensor_with_writer_shards(write_key, write_tensor,
-                                                    writer, write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config, int rank, int size,
-               int split_dim) {
-            return upsert_tensor_with_tp_impl(write_key, write_tensor,
-                                              write_config, size, split_dim);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ReplicateConfig &write_config, int rank, int size,
-               int split_dim, const std::vector<ParallelAxisSpec> &axes) {
-            if (axes.size() == 1) {
-                return upsert_tensor_parallelism_tp_impl(
-                    write_key, write_tensor, write_config, rank, size,
-                    split_dim, axes);
-            }
-            return upsert_requested_parallelism_shard(
-                write_key, write_tensor, TensorParallelismSpec{axes},
-                write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const TensorParallelismSpec &parallelism_spec,
-               const ReplicateConfig &write_config) {
-            return upsert_direct_parallelism_shard(
-                write_key, write_tensor, parallelism_spec, write_config);
-        });
-}
-
-int upsert_tensor_with_parallelism(
-    const std::string &key, pybind11::object tensor,
-    const py::object &parallelism = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partition = py::none()) {
-    auto request = resolve_parallelism_write_request(
-        parallelism, writer_partition, "upsert_tensor_with_parallelism");
-    if (!request.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return execute_upsert_tensor_with_parallelism_route(key, tensor, *request,
-                                                        config);
-}
-
-int execute_upsert_tensor_with_parallelism_from_route(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const ResolvedParallelismWriteRequest &request,
-    const ReplicateConfig &config) {
-    return execute_parallelism_tensor_write_from_route(
-        key, buffer_ptr, size, request, config,
-        "upsert_tensor_with_parallelism_from",
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const ReplicateConfig &write_config) {
-            if (!is_default_replicate_config(write_config)) {
-                if (!is_valid_tensor_object_buffer(
-                        write_buffer_ptr, write_size,
-                        "upsert_tensor_with_parallelism_from")) {
-                    return to_py_ret(ErrorCode::INVALID_PARAMS);
-                }
-                void *buffer = reinterpret_cast<void *>(write_buffer_ptr);
-                if (!is_client_initialized()) {
-                    LOG(ERROR) << "Client is not initialized";
-                    return to_py_ret(ErrorCode::INVALID_PARAMS);
-                }
-                int validate_result = validate_replicate_config(write_config);
-                if (validate_result) return validate_result;
-                py::gil_scoped_release release_gil;
-                return store_->upsert_from(write_key, buffer, write_size,
-                                           write_config);
-            }
-            return upsert_tensor_from(write_key, write_buffer_ptr, write_size);
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const WriterPartitionSpec &writer,
-               const ReplicateConfig &write_config) {
-            return upsert_tensor_with_writer_shards_from(
-                write_key, write_buffer_ptr, write_size, writer, write_config);
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, int tp_size, int split_dim,
-               const std::vector<ParallelAxisSpec> &axes,
-               const ReplicateConfig &write_config) {
-            return execute_tp_tensor_write_from_impl(
-                write_key, write_buffer_ptr, write_size, write_config, tp_size,
-                split_dim, axes, "upsert_tensor_with_parallelism_from",
-                [this](const std::string &shard_key,
-                       const std::vector<std::span<const char>> &values,
-                       const ReplicateConfig &parts_config) {
-                    py::gil_scoped_release release_gil;
-                    int ret =
-                        store_->upsert_parts(shard_key, values, parts_config);
-                    if (ret != 0) {
-                        LOG(ERROR) << "upsert_parts failed for key "
-                                   << shard_key << " with code " << ret;
-                    }
-                    return ret;
-                });
-        },
-        [this](const std::string &write_key, uintptr_t write_buffer_ptr,
-               size_t write_size, const TensorParallelismSpec &parallelism_spec,
-               const ReplicateConfig &write_config) {
-            return upsert_direct_parallelism_shard_from(
-                write_key, write_buffer_ptr, write_size, parallelism_spec,
-                write_config);
-        },
-        [this](const std::string &write_key, pybind11::object write_tensor,
-               const ResolvedParallelismWriteRequest &write_request,
-               const ReplicateConfig &write_config) {
-            return execute_upsert_tensor_with_parallelism_route(
-                write_key, write_tensor, write_request, write_config);
-        });
-}
-
-int upsert_tensor_with_parallelism_from(
-    const std::string &key, uintptr_t buffer_ptr, size_t size,
-    const py::object &parallelism = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partition = py::none()) {
-    auto request = resolve_parallelism_write_request(
-        parallelism, writer_partition, "upsert_tensor_with_parallelism_from");
-    if (!request.has_value()) {
-        return to_py_ret(ErrorCode::INVALID_PARAMS);
-    }
-    return execute_upsert_tensor_with_parallelism_from_route(
-        key, buffer_ptr, size, *request, config);
-}
-
-std::vector<int> batch_upsert_tensor_with_parallelism(
-    const std::vector<std::string> &keys, const pybind11::list &tensors_list,
-    const py::object &parallelisms = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partitions = py::none()) {
-    auto group_ids_error = ValidateGroupIdsForBatchConfig(
-        config, keys.size(), "batch_upsert_tensor_with_parallelism");
-    if (!group_ids_error.empty()) {
-        return group_ids_error;
-    }
-
-    return execute_batch_parallelism_write_requests(
-        keys, tensors_list.size(), parallelisms, writer_partitions,
-        "batch_upsert_tensor_with_parallelism",
-        [this, &keys, &tensors_list, &config]() {
-            if (!is_client_initialized()) {
-                return std::vector<int>(keys.size(),
-                                        to_py_ret(ErrorCode::INVALID_PARAMS));
-            }
-            int validate_result = validate_replicate_config(config);
-            if (validate_result) {
-                return std::vector<int>(keys.size(), validate_result);
-            }
-            return batch_upsert_tensor_impl(keys, tensors_list, config);
-        },
-        [this, &keys, &tensors_list, &config](size_t i,
-                                              const py::handle &parallelism) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return upsert_tensor_with_parallelism(
-                keys[i], tensors_list[i],
-                py::reinterpret_borrow<py::object>(parallelism), key_config);
-        },
-        [this, &keys, &tensors_list, &config](
-            size_t i, const py::handle &writer_partition) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return upsert_tensor_with_parallelism(
-                keys[i], tensors_list[i], py::none(), key_config,
-                py::reinterpret_borrow<py::object>(writer_partition));
-        });
-}
-
-std::vector<int> batch_upsert_tensor_with_parallelism_from(
-    const std::vector<std::string> &keys,
-    const std::vector<uintptr_t> &buffer_ptrs, const std::vector<size_t> &sizes,
-    const py::object &parallelisms = py::none(),
-    const ReplicateConfig &config = ReplicateConfig{},
-    const py::object &writer_partitions = py::none()) {
-    auto group_ids_error = ValidateGroupIdsForBatchConfig(
-        config, keys.size(), "batch_upsert_tensor_with_parallelism_from");
-    if (!group_ids_error.empty()) {
-        return group_ids_error;
-    }
-
-    return execute_batch_parallelism_write_requests(
-        keys, buffer_ptrs.size(), parallelisms, writer_partitions,
-        "batch_upsert_tensor_with_parallelism_from",
-        [this, &keys, &buffer_ptrs, &sizes, &config]() {
-            if (!is_default_replicate_config(config)) {
-                if (!is_client_initialized()) {
-                    LOG(ERROR) << "Client is not initialized";
-                    return std::vector<int>(
-                        keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                }
-                int validate_result = validate_replicate_config(config);
-                if (validate_result) {
-                    return std::vector<int>(keys.size(), validate_result);
-                }
-                if (keys.empty()) {
-                    return std::vector<int>();
-                }
-                if (keys.size() != buffer_ptrs.size() ||
-                    keys.size() != sizes.size()) {
-                    LOG(ERROR) << "Size mismatch: keys, buffer_ptrs, and sizes "
-                                  "must have the same length";
-                    return std::vector<int>(
-                        keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                }
-                for (size_t i = 0; i < sizes.size(); ++i) {
-                    if (!is_valid_tensor_object_buffer(
-                            buffer_ptrs[i], sizes[i],
-                            "tensor object buffer at index " +
-                                std::to_string(i))) {
-                        return std::vector<int>(
-                            keys.size(), to_py_ret(ErrorCode::INVALID_PARAMS));
-                    }
-                }
-                std::vector<void *> buffers;
-                buffers.reserve(buffer_ptrs.size());
-                for (uintptr_t ptr : buffer_ptrs) {
-                    buffers.push_back(reinterpret_cast<void *>(ptr));
-                }
-                py::gil_scoped_release release_gil;
-                return store_->batch_upsert_from(keys, buffers, sizes, config);
-            }
-            return batch_upsert_tensor_from(keys, buffer_ptrs, sizes);
-        },
-        [this, &keys, &buffer_ptrs, &sizes, &config](
-            size_t i, const py::handle &parallelism) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return upsert_tensor_with_parallelism_from(
-                keys[i], buffer_ptrs[i], sizes[i],
-                py::reinterpret_borrow<py::object>(parallelism), key_config);
-        },
-        [this, &keys, &buffer_ptrs, &sizes, &config](
-            size_t i, const py::handle &writer_partition) {
-            ReplicateConfig key_config = config.ForSingleKey(i);
-            return upsert_tensor_with_parallelism_from(
-                keys[i], buffer_ptrs[i], sizes[i], py::none(), key_config,
-                py::reinterpret_borrow<py::object>(writer_partition));
-        });
-}
diff --git a/mooncake-integration/tests/test_tent_first_buffer.py b/mooncake-integration/tests/test_tent_first_buffer.py
new file mode 100644
index 0000000000..5cc67013f7
--- /dev/null
+++ b/mooncake-integration/tests/test_tent_first_buffer.py
@@ -0,0 +1,42 @@
+import ctypes
+import unittest
+
+import engine
+
+
+class TentFirstBufferTest(unittest.TestCase):
+    def test_local_and_remote_buffer(self):
+        target = engine.TransferEngine()
+        initiator = engine.TransferEngine()
+        for te in (target, initiator):
+            self.assertEqual(te.initialize("127.0.0.1", "P2PHANDSHAKE", "tcp", ""), 0)
+
+        name = f"127.0.0.1:{target.get_rpc_port()}"
+        self.assertEqual(target.get_first_buffer_address(name), 0)
+
+        target_buffer = ctypes.create_string_buffer(128)
+        source_buffer = ctypes.create_string_buffer(b"first buffer regression", 128)
+        target_addr = ctypes.addressof(target_buffer)
+        source_addr = ctypes.addressof(source_buffer)
+        self.assertEqual(target.register_memory(target_addr, 128), 0)
+        self.addCleanup(
+            lambda: target.unregister_memory(ctypes.addressof(target_buffer))
+        )
+        self.assertEqual(initiator.register_memory(source_addr, 128), 0)
+        self.addCleanup(
+            lambda: initiator.unregister_memory(ctypes.addressof(source_buffer))
+        )
+
+        self.assertEqual(target.get_first_buffer_address(name), target_addr)
+        for _ in range(2):
+            # The second query must preserve the handle cached by the first write.
+            self.assertEqual(initiator.get_first_buffer_address(name), target_addr)
+            ctypes.memset(target_addr, 0, 128)
+            self.assertEqual(
+                initiator.transfer_sync_write(name, source_addr, target_addr, 128), 0
+            )
+            self.assertEqual(target_buffer.raw, source_buffer.raw)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-integration/tests/test_tent_send_probe.py b/mooncake-integration/tests/test_tent_send_probe.py
new file mode 100644
index 0000000000..3f498a56b7
--- /dev/null
+++ b/mooncake-integration/tests/test_tent_send_probe.py
@@ -0,0 +1,40 @@
+import unittest
+
+import engine
+
+
+class TentSendProbeTest(unittest.TestCase):
+    def test_probe_preserves_cached_peer_handle(self):
+        target = engine.TransferEngine()
+        initiator = engine.TransferEngine()
+
+        self.assertEqual(target.initialize("", "P2PHANDSHAKE", "tcp", ""), 0)
+        self.assertEqual(initiator.initialize("", "P2PHANDSHAKE", "tcp", ""), 0)
+
+        target_name = f"127.0.0.1:{target.get_rpc_port()}"
+        length = 4096
+        source = initiator.allocate_managed_buffer(length)
+        destination = target.allocate_managed_buffer(length)
+        self.assertNotEqual(source, 0)
+        self.assertNotEqual(destination, 0)
+        self.assertEqual(initiator.send_probe(target_name), 0)
+
+        for payload in (b"before-probe", b"after-probe"):
+            self.assertEqual(
+                initiator.write_bytes_to_buffer(source, payload, len(payload)), 0
+            )
+            self.assertEqual(
+                initiator.transfer_sync_write(
+                    target_name, source, destination, len(payload)
+                ),
+                0,
+            )
+            self.assertEqual(
+                target.read_bytes_from_buffer(destination, len(payload)), payload
+            )
+            if payload == b"before-probe":
+                self.assertEqual(initiator.send_probe(target_name), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-integration/transfer_engine/shared_segment_py.cpp b/mooncake-integration/transfer_engine/shared_segment_py.cpp
new file mode 100644
index 0000000000..f5bc3bc491
--- /dev/null
+++ b/mooncake-integration/transfer_engine/shared_segment_py.cpp
@@ -0,0 +1,89 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#include "shared_segment_py.h"
+
+#include <pybind11/stl.h>
+
+#include <stdexcept>
+#include <utility>
+
+namespace py = pybind11;
+
+namespace mooncake {
+namespace {
+void ThrowIfError(const Status& status) {
+    if (!status.ok()) {
+        throw std::runtime_error(status.ToString());
+    }
+}
+
+// Returns the unfinished segment plus this rank's blob. The caller all-gathers
+// the blob and passes every rank's copy back to Complete.
+// SharedSegmentOptions is an implementation detail and is not exposed to
+// Python; callers pass the fields directly.
+std::pair<std::shared_ptr<SharedSegment>, py::bytes> SegmentCreate(
+    const std::string& name, uint64_t size, uint32_t world_size,
+    uint32_t rank_id, uint32_t owner_rank, int32_t device_id, bool mmap,
+    bool host_register) {
+    SharedSegmentOptions options;
+    options.world_size = world_size;
+    options.rank_id = rank_id;
+    options.owner_rank = owner_rank;
+    options.device_id = device_id;
+    options.mmap = mmap;
+    options.host_register = host_register;
+
+    std::string blob;
+    std::shared_ptr<SharedSegment> segment;
+    Status status = Status::OK();
+    {
+        py::gil_scoped_release release;
+        status = SharedSegment::Create(name, size, options, segment, blob);
+    }
+    ThrowIfError(status);
+    return {std::move(segment), py::bytes(blob)};
+}
+
+void SegmentComplete(const std::shared_ptr<SharedSegment>& segment,
+                     const std::vector<std::string>& blobs) {
+    Status status = Status::OK();
+    {
+        py::gil_scoped_release release;
+        status = segment->Complete(blobs);
+    }
+    ThrowIfError(status);
+}
+}  // namespace
+
+void bind_shared_segment(py::module_& m) {
+    py::class_<SharedSegment, std::shared_ptr<SharedSegment>>(m,
+                                                              "SharedSegment")
+        .def_static("create", &SegmentCreate, py::arg("name"), py::arg("size"),
+                    py::arg("world_size"), py::arg("rank_id"),
+                    py::arg("owner_rank") = 0, py::arg("device_id") = 0,
+                    py::arg("mmap") = true, py::arg("host_register") = false,
+                    "Phase one; returns (segment, blob).")
+        .def_static("supported", &SharedSegment::Supported,
+                    py::arg("mmap") = true, py::arg("host_register") = false,
+                    "Whether this build can share memory across processes.")
+        .def("complete", &SegmentComplete, py::arg("blobs"),
+             "Phase two; blobs are indexed by rank.")
+        .def("ready", &SharedSegment::ready)
+        .def("base_addr", &SharedSegment::base_addr)
+        .def("device_addr", &SharedSegment::device_addr)
+        .def("size", &SharedSegment::size);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-integration/transfer_engine/shared_segment_py.h b/mooncake-integration/transfer_engine/shared_segment_py.h
new file mode 100644
index 0000000000..0934862cd5
--- /dev/null
+++ b/mooncake-integration/transfer_engine/shared_segment_py.h
@@ -0,0 +1,26 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#ifndef SHARED_SEGMENT_PY_H
+#define SHARED_SEGMENT_PY_H
+
+#include <pybind11/pybind11.h>
+
+#include "shared_segment/shared_segment.h"
+
+namespace mooncake {
+void bind_shared_segment(pybind11::module_& m);
+}  // namespace mooncake
+
+#endif  // SHARED_SEGMENT_PY_H
diff --git a/mooncake-integration/transfer_engine/transfer_engine_py.cpp b/mooncake-integration/transfer_engine/transfer_engine_py.cpp
index 39d31b75ba..68c4c6e67f 100644
--- a/mooncake-integration/transfer_engine/transfer_engine_py.cpp
+++ b/mooncake-integration/transfer_engine/transfer_engine_py.cpp
@@ -15,14 +15,18 @@
 #include "transfer_engine_py.h"
 
 #include <cassert>
+#include <cstdlib>
 #include <numeric>
 #include <fstream>
 
 #include <pybind11/stl.h>
+#include "shared_segment_py.h"
 #include "transport/rpc_communicator/rpc_interface.h"
 
 #ifdef USE_TENT
+#include "tent/common/config.h"
 #include "tent/common/types.h"
+#include "tent/transfer_engine.h"
 #endif
 
 #ifdef USE_EFA
@@ -37,6 +41,10 @@
 #include "transport/nvlink_transport/nvlink_transport.h"
 #endif
 
+#ifdef USE_MUSA
+#include "transport/musa_transport/musa_transport.h"
+#endif
+
 #ifdef USE_INTRA_NVLINK
 #include "transport/intranode_nvlink_transport/intranode_nvlink_transport.h"
 #endif
@@ -50,13 +58,13 @@ static void (*freeMemory)(void*) = nullptr;
 static std::string g_protocol;
 
 //  Handle allocateMemory function pointer based on protocol
-void initMemoryAllocator(const char* protocol) {
+static bool initMemoryAllocator(const char* protocol) {
     if (allocateMemory != nullptr) {
         LOG(WARNING) << "Memory allocator already initialized with: "
                      << g_protocol;
-        return;
+        return true;
     }
-    g_protocol = protocol;
+    if (protocol == nullptr) protocol = "";
     if (strcmp(protocol, "nvlink") == 0) {
 #ifdef USE_MNNVL
         allocateMemory = [](size_t s) -> void* {
@@ -68,6 +76,19 @@ void initMemoryAllocator(const char* protocol) {
         LOG(INFO) << "Selected MNNVL (NVLink) memory allocator";
 #else
         LOG(ERROR) << "Protocol 'nvlink' requires -DUSE_MNNVL=ON";
+        return false;
+#endif
+    } else if (strcmp(protocol, "musa") == 0) {
+#ifdef USE_MUSA
+        allocateMemory = [](size_t s) -> void* {
+            return mooncake::MusaTransport::allocatePinnedLocalMemory(s);
+        };
+        freeMemory = [](void* p) {
+            mooncake::MusaTransport::freePinnedLocalMemory(p);
+        };
+        LOG(INFO) << "Selected MUSA memory allocator";
+#else
+        LOG(ERROR) << "Protocol 'musa' requires -DUSE_MUSA=ON";
 #endif
     } else if (strcmp(protocol, "hip") == 0) {
 #ifdef USE_HIP
@@ -80,6 +101,7 @@ void initMemoryAllocator(const char* protocol) {
         LOG(INFO) << "Selected HIP memory allocator";
 #else
         LOG(ERROR) << "Protocol 'hip' requires -DUSE_HIP=ON";
+        return false;
 #endif
     } else if (strcmp(protocol, "nvlink_intra") == 0) {
 #ifdef USE_INTRA_NVLINK
@@ -93,12 +115,26 @@ void initMemoryAllocator(const char* protocol) {
         LOG(INFO) << "Selected Intra-NVLink memory allocator";
 #else
         LOG(ERROR) << "Protocol 'nvlink_intra' requires -DUSE_INTRA_NVLINK=ON";
+        return false;
 #endif
     } else {
-        allocateMemory = malloc;
+        // Ascend SVM (_devmm_mem_remote_map) requires a 64KB page-aligned
+        // src_va. Fallback protocols (rdma/tcp/ascend) use posix_memalign to
+        // guarantee 64KB alignment, otherwise aclrtHostRegister fails with
+        // EINVAL on a misaligned address.
+        allocateMemory = [](size_t s) -> void* {
+            void* p = nullptr;
+            if (posix_memalign(&p, 64 * 1024, s) != 0) {
+                return nullptr;
+            }
+            return p;
+        };
         freeMemory = free;
-        LOG(WARNING) << "Using default malloc/free for protocol: " << protocol;
+        LOG(WARNING) << "Using 64KB-aligned malloc/free for protocol: "
+                     << protocol;
     }
+    g_protocol = protocol;
+    return true;
 }
 
 TransferEnginePy::TransferEnginePy() {
@@ -169,8 +205,6 @@ int TransferEnginePy::initialize(const char* local_hostname,
                                  const char* metadata_server,
                                  const char* protocol,
                                  const char* device_name) {
-    initMemoryAllocator(protocol);
-
     auto conn_string = parseConnectionString(metadata_server);
     return initializeExt(local_hostname, conn_string.second.c_str(), protocol,
                          device_name, conn_string.first.c_str());
@@ -181,17 +215,19 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
                                     const char* protocol,
                                     const char* device_name,
                                     const char* metadata_type) {
-    if (strcmp(protocol, "xgmi") == 0) {
+    if (protocol != nullptr && strcmp(protocol, "xgmi") == 0) {
         LOG(ERROR) << "Protocol 'xgmi' is not exposed in the Python API. "
                    << "Use 'hip' instead.";
         return -1;
     }
+    if (!initMemoryAllocator(protocol)) return -1;
 
     std::string proto = protocol ? std::string(protocol) : "";
     std::string conn_string = buildConnString(metadata_type, metadata_server);
 
     auto device_name_safe = device_name ? std::string(device_name) : "";
     auto device_filter = buildDeviceFilter(device_name_safe);
+    bool use_flagcx = (proto == "flagcx");
 
 #ifdef USE_EFA
     // When using EFA protocol, we still need topology discovery but won't
@@ -218,18 +254,18 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
                   << " devices.";
     }
 #else
-    engine_ = std::make_unique<TransferEngine>(true, device_filter);
+    engine_ = std::make_unique<TransferEngine>(!use_flagcx, device_filter);
 #endif
 
     if (getenv("MC_LEGACY_RPC_PORT_BINDING")) {
         auto hostname_port = parseHostNameWithPort(local_hostname);
-        int ret =
-            engine_->init(conn_string, local_hostname,
-                          hostname_port.first.c_str(), hostname_port.second);
+        int ret = engine_->init(conn_string, local_hostname,
+                                hostname_port.first.c_str(),
+                                hostname_port.second, proto);
         if (ret) return -1;
     } else {
         // the last two params are unused
-        int ret = engine_->init(conn_string, local_hostname, "", 0);
+        int ret = engine_->init(conn_string, local_hostname, "", 0, proto);
         if (ret) return -1;
     }
 
@@ -244,6 +280,15 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
             return -1;
         }
         LOG(INFO) << "EFA transport installed successfully";
+    } else if (use_flagcx) {
+        LOG(INFO)
+            << "Installing FlagCX transport as requested by protocol parameter";
+        auto transport = engine_->installTransport("flagcx", nullptr);
+        if (!transport) {
+            LOG(ERROR) << "Failed to install FlagCX transport";
+            return -1;
+        }
+        LOG(INFO) << "FlagCX transport installed successfully";
     } else {
         // For non-EFA protocols (e.g. TCP), manually install TCP transport
         // since auto_discover is disabled to prevent RDMA installation
@@ -267,6 +312,15 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
             return -1;
         }
         LOG(INFO) << "CXI transport installed successfully";
+    } else if (use_flagcx) {
+        LOG(INFO)
+            << "Installing FlagCX transport as requested by protocol parameter";
+        auto transport = engine_->installTransport("flagcx", nullptr);
+        if (!transport) {
+            LOG(ERROR) << "Failed to install FlagCX transport";
+            return -1;
+        }
+        LOG(INFO) << "FlagCX transport installed successfully";
     } else {
         // For non-EFA protocols (e.g. TCP), manually install TCP transport
         // since auto_discover is disabled to prevent RDMA installation
@@ -280,6 +334,17 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
         }
         LOG(INFO) << "TCP transport installed successfully";
     }
+#else
+    if (use_flagcx) {
+        LOG(INFO)
+            << "Installing FlagCX transport as requested by protocol parameter";
+        auto transport = engine_->installTransport("flagcx", nullptr);
+        if (!transport) {
+            LOG(ERROR) << "Failed to install FlagCX transport";
+            return -1;
+        }
+        LOG(INFO) << "FlagCX transport installed successfully";
+    }
 #endif
 
     free_list_.resize(kSlabSizeKBTabLen);
@@ -289,6 +354,10 @@ int TransferEnginePy::initializeExt(const char* local_hostname,
 int TransferEnginePy::getRpcPort() { return engine_->getRpcPort(); }
 
 char* TransferEnginePy::allocateRawBuffer(size_t capacity) {
+    if (allocateMemory == nullptr || freeMemory == nullptr) {
+        LOG(ERROR) << "Memory allocator is not initialized";
+        return nullptr;
+    }
     auto buffer = allocateMemory(capacity);
     if (!buffer) return nullptr;
     int ret = engine_->registerLocalMemory(buffer, capacity, kWildcardLocation);
@@ -478,6 +547,7 @@ int TransferEnginePy::transferSync(const char* target_hostname,
                       TransferMetadata::NotifyDesc{notify->name, notify->msg})
                 : engine_->submitTransfer(batch_id, {entry});
         if (!s.ok()) {
+            engine_->freeBatchID(batch_id);
             Status segment_status = engine_->CheckSegmentStatus(handle);
             if (!segment_status.ok()) {
                 LOG(WARNING)
@@ -485,14 +555,20 @@ int TransferEnginePy::transferSync(const char* target_hostname,
                     << ", CheckSegmentStatus not ok, ready to closeSegment";
                 std::lock_guard<std::mutex> guard(mutex_);
                 engine_->closeSegment(handle);
-                engine_->getMetadata()->removeSegmentDesc(target_hostname);
+                // Under MC_USE_TENT there is no classic metadata object
+                // (getMetadata() returns nullptr); TENT invalidates its own
+                // segment cache inside closeSegment(). Guard the classic-only
+                // cleanup so evicting a dead peer's handle cannot dereference
+                // a null metadata pointer. Refs #3995 (P0-stale-handle).
+                if (auto metadata = engine_->getMetadata())
+                    metadata->removeSegmentDesc(target_hostname);
                 handle_map_.erase(target_hostname);
             }
             return -1;
         }
 
-        TransferStatus status;
         bool completed = false;
+        TransferStatus status;
         while (!completed) {
             Status s = engine_->getTransferStatus(batch_id, 0, status);
             LOG_ASSERT(s.ok());
@@ -504,8 +580,10 @@ int TransferEnginePy::transferSync(const char* target_hostname,
                 completed = true;
             } else if (status.s == TransferStatusEnum::TIMEOUT) {
                 LOG(INFO) << "Sync data transfer timeout";
+                engine_->freeBatchID(batch_id);
                 completed = true;
             }
+            if (completed) break;
             auto current_ts = getCurrentTimeInNano();
             const int64_t timeout =
                 transfer_timeout_nsec_ + length;  // 1GiB per second
@@ -514,6 +592,7 @@ int TransferEnginePy::transferSync(const char* target_hostname,
                           << current_ts - start_ts << "ns, local buffer "
                           << (void*)buffer << " remote buffer "
                           << (void*)peer_buffer_address << " length " << length;
+                engine_->freeBatchID(batch_id);
                 return -1;
             }
         }
@@ -534,7 +613,11 @@ int TransferEnginePy::batchTransferSync(
             handle = handle_map_[target_hostname];
         } else {
             handle = engine_->openSegment(target_hostname);
-            if (handle == (Transport::SegmentHandle)-1) return -1;
+            if (handle == (Transport::SegmentHandle)-1) {
+                LOG(ERROR) << "batchTransferSync: openSegment failed for "
+                           << target_hostname;
+                return -1;
+            }
             handle_map_[target_hostname] = handle;
         }
     }
@@ -576,6 +659,10 @@ int TransferEnginePy::batchTransferSync(
                       TransferMetadata::NotifyDesc{notify->name, notify->msg})
                 : engine_->submitTransfer(batch_id, entries);
         if (!s.ok()) {
+            LOG(ERROR) << "batchTransferSync: submitTransfer failed for "
+                       << target_hostname << " (batch of " << batch_size
+                       << " requests, " << total_length
+                       << " bytes): " << s.ToString();
             engine_->freeBatchID(batch_id);
             Status segment_status = engine_->CheckSegmentStatus(handle);
             if (!segment_status.ok()) {
@@ -584,15 +671,20 @@ int TransferEnginePy::batchTransferSync(
                     << ", CheckSegmentStatus not ok, ready to closeSegment";
                 std::lock_guard<std::mutex> guard(mutex_);
                 engine_->closeSegment(handle);
-                engine_->getMetadata()->removeSegmentDesc(target_hostname);
+                // Under MC_USE_TENT there is no classic metadata object
+                // (getMetadata() returns nullptr); TENT invalidates its own
+                // segment cache inside closeSegment(). Guard the classic-only
+                // cleanup so evicting a dead peer's handle cannot dereference
+                // a null metadata pointer. Refs #3995 (P0-stale-handle).
+                if (auto metadata = engine_->getMetadata())
+                    metadata->removeSegmentDesc(target_hostname);
                 handle_map_.erase(target_hostname);
             }
             return -1;
         }
 
-        TransferStatus status;
         bool completed = false;
-        bool already_freed = false;
+        TransferStatus status;
         while (!completed) {
             Status s = engine_->getBatchTransferStatus(batch_id, status);
             LOG_ASSERT(s.ok());
@@ -600,13 +692,18 @@ int TransferEnginePy::batchTransferSync(
                 engine_->freeBatchID(batch_id);
                 return 0;
             } else if (status.s == TransferStatusEnum::FAILED) {
+                LOG(ERROR) << "batchTransferSync: transfer FAILED for "
+                           << target_hostname << " (batch of " << batch_size
+                           << " requests, " << total_length
+                           << " bytes) on retry " << retry << "/" << max_retry;
                 engine_->freeBatchID(batch_id);
-                already_freed = true;
                 completed = true;
             } else if (status.s == TransferStatusEnum::TIMEOUT) {
                 LOG(INFO) << "Sync data transfer timeout";
+                engine_->freeBatchID(batch_id);
                 completed = true;
             }
+            if (completed) break;
             auto current_ts = getCurrentTimeInNano();
             const int64_t timeout =
                 transfer_timeout_nsec_ + total_length;  // 1GiB per second
@@ -616,13 +713,14 @@ int TransferEnginePy::batchTransferSync(
                 // TODO: as @doujiang24 mentioned, early free(while there are
                 // still waiting tasks) the batch_id may fail and cause memory
                 // leak(a known issue).
-                if (!already_freed) {
-                    engine_->freeBatchID(batch_id);
-                }
+                engine_->freeBatchID(batch_id);
                 return -1;
             }
         }
     }
+    LOG(ERROR) << "batchTransferSync: all " << max_retry
+               << " retries exhausted for " << target_hostname << " (batch of "
+               << batch_size << " requests, " << total_length << " bytes)";
     return -1;
 }
 
@@ -1055,26 +1153,53 @@ int TransferEnginePy::warmupEfaSegment(const std::string& segment_name) {
 
 uintptr_t TransferEnginePy::getFirstBufferAddress(
     const std::string& segment_name) {
+    pybind11::gil_scoped_release release;
     Transport::SegmentHandle segment_id =
         engine_->openSegment(segment_name.c_str());
-    auto segment_desc = engine_->getMetadata()->getSegmentDescByID(segment_id);
-    if (!segment_desc || segment_desc->buffers.empty()) {
+    if (segment_id ==
+        static_cast<Transport::SegmentHandle>(ERR_INVALID_ARGUMENT))
         return 0;
-    }
-    return segment_desc->buffers[0].addr;
+    std::vector<SegmentBufferInfo> buffers;
+    if (engine_->getSegmentBuffers(segment_id, buffers) != 0 || buffers.empty())
+        return 0;
+    return buffers.front().addr;
 }
 
 std::string TransferEnginePy::getLocalTopology(const char* device_name) {
     pybind11::gil_scoped_release release;
     auto device_name_safe = device_name ? std::string(device_name) : "";
+
+    const bool use_tent =
+        getenv("MC_USE_TENT") != nullptr || getenv("MC_USE_TEV1") != nullptr;
+#ifdef USE_TENT
+    if (use_tent) {
+        // This helper only needs topology, so use the native TENT Config path
+        // directly instead of constructing the classic compatibility shim.
+        // Keep the filter per-instance and avoid the process-global
+        // MC_TE_FILTERS environment variable, which is unsafe for concurrent
+        // callers. Explicit Config values take precedence over environment
+        // defaults inside TransferEngineImpl.
+        auto conf = std::make_shared<mooncake::tent::Config>();
+        conf->set("metadata_type", "p2p");
+        if (!device_name_safe.empty()) {
+            conf->set("topology/rdma_whitelist",
+                      std::vector<std::string>{device_name_safe});
+        }
+        mooncake::tent::TransferEngine tent_engine(conf);
+        return tent_engine.available() ? tent_engine.getLocalTopologyString()
+                                       : "{}";
+    }
+#else
+    (void)use_tent;
+#endif
+
+    // Classic path: device_filter is honored by classic TransferEngineImpl.
     auto device_filter = buildDeviceFilter(device_name_safe);
     std::shared_ptr<TransferEngine> tmp_engine =
         std::make_shared<TransferEngine>(true, device_filter);
-
     std::string metadata_conn_string{"P2PHANDSHAKE"}, local_server_name{};
     tmp_engine->init(metadata_conn_string, local_server_name);
-
-    return tmp_engine->getLocalTopology()->toString();
+    return tmp_engine->getLocalTopologyString();
 }
 
 std::vector<TransferEnginePy::TransferNotify> TransferEnginePy::getNotifies() {
@@ -1098,6 +1223,15 @@ std::vector<TransferEnginePy::TransferNotify> TransferEnginePy::getNotifies() {
 int TransferEnginePy::sendProbe(const std::string& peer_server_name) {
     if (!engine_) return -1;
     pybind11::gil_scoped_release release;
+
+    if (engine_->isUsingTent()) {
+        auto handle = engine_->openSegment(peer_server_name);
+        if (handle == static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT))
+            return -1;
+        auto liveness = engine_->probePeerAliveByID(handle);
+        return static_cast<int>(liveness);
+    }
+
     return engine_->getMetadata()->sendProbe(peer_server_name);
 }
 
@@ -1134,6 +1268,12 @@ PYBIND11_MODULE(engine, m) {
     m.attr("SUPPORT_MNNVL") = false;
 #endif
 
+#ifdef USE_MUSA
+    m.attr("SUPPORT_MUSA") = true;
+#else
+    m.attr("SUPPORT_MUSA") = false;
+#endif
+
 #ifdef USE_INTRA_NVLINK
     m.attr("SUPPORT_INTRA_NVLINK") = true;
 #else
@@ -1273,6 +1413,8 @@ PYBIND11_MODULE(engine, m) {
     py::class_<TransferEngine, std::shared_ptr<TransferEngine>>(
         m, "InnerTransferEngine");
 
+    mooncake::bind_shared_segment(m);
+
     // Bind RpcInterface (this also registers ReceivedData, ReceivedTensor, and
     // factory functions)
     mooncake::bind_rpc_interface(m);
diff --git a/mooncake-p2p-store/src/p2pstore/core.go b/mooncake-p2p-store/src/p2pstore/core.go
index 1119e01a42..d61641841c 100644
--- a/mooncake-p2p-store/src/p2pstore/core.go
+++ b/mooncake-p2p-store/src/p2pstore/core.go
@@ -20,6 +20,7 @@ import (
 	"net"
 	"strconv"
 	"sync"
+	"time"
 )
 
 // When the data size larger than MAX_CHUNK_SIZE bytes, we split them into multiple buffers and registered separately.
@@ -35,8 +36,25 @@ type P2PStore struct {
 	localServerName    string
 	catalog            *Catalog
 	memory             *RegisteredMemory
-	metadata           *Metadata
-	transfer           *TransferEngine
+	metadata           metadataStore
+	transfer           transferEngine
+}
+
+type metadataStore interface {
+	Close() error
+	Create(context.Context, string, *Payload) error
+	Put(context.Context, string, *Payload) error
+	Update(context.Context, string, *Payload, int64) (bool, error)
+	Get(context.Context, string) (*Payload, int64, error)
+	List(context.Context, string) ([]*Payload, error)
+}
+
+type transferEngine interface {
+	batchTransport
+	Close()
+	GetLocalIpAndPort() (string, error)
+	registerLocalMemory(uintptr, uint64, string) error
+	unregisterLocalMemory(uintptr) error
 }
 
 const DEFAULT_PORT int = 12345
@@ -261,13 +279,19 @@ func (store *P2PStore) doGetReplica(ctx context.Context, payload *Payload, addrL
 	var offset uint64 = 0
 	taskID := 0
 	maxShardSize := payload.MaxShardSize
+	var registered []Buffer
 
 	for i := 0; i < len(addrList); i++ {
 		addr, size := addrList[i], sizeList[i]
 		err := store.memory.Add(addr, size, maxShardSize, "cpu:0")
 		if err != nil {
+			// Wait for transfers already started in earlier iterations:
+			// unregistering memory that in-flight transfers still use is unsafe.
+			wg.Wait()
+			store.unregisterBuffers(registered, maxShardSize)
 			return err
 		}
+		registered = append(registered, Buffer{addr: addr, size: size})
 		offset = 0
 		for ; offset < size; offset += maxShardSize {
 			source := addr + uintptr(offset)
@@ -292,6 +316,7 @@ func (store *P2PStore) doGetReplica(ctx context.Context, payload *Payload, addrL
 	select {
 	case err := <-errChan:
 		if err != nil {
+			store.unregisterBuffers(registered, maxShardSize)
 			return err
 		}
 	default:
@@ -299,6 +324,14 @@ func (store *P2PStore) doGetReplica(ctx context.Context, payload *Payload, addrL
 	return nil
 }
 
+func buffersFromLists(addrList []uintptr, sizeList []uint64) []Buffer {
+	buffers := make([]Buffer, 0, len(addrList))
+	for i := range addrList {
+		buffers = append(buffers, Buffer{addr: addrList[i], size: sizeList[i]})
+	}
+	return buffers
+}
+
 func contains(slice []Location, value Location) bool {
 	for _, item := range slice {
 		if item == value {
@@ -327,6 +360,44 @@ func isSubsetOf(old *Payload, new *Payload) bool {
 	return true
 }
 
+func hasSameLayout(old *Payload, new *Payload) bool {
+	if old.Size != new.Size || old.MaxShardSize != new.MaxShardSize ||
+		len(old.SizeList) != len(new.SizeList) || len(old.Shards) != len(new.Shards) {
+		return false
+	}
+	for i := range old.SizeList {
+		if old.SizeList[i] != new.SizeList[i] {
+			return false
+		}
+	}
+	for i := range old.Shards {
+		if old.Shards[i].Length != new.Shards[i].Length {
+			return false
+		}
+	}
+	return true
+}
+
+// reconcilePayloadAfterTransfer decides whether a transfer must be retried
+// after its metadata snapshot changed. A retry is only needed when at least
+// one source used by the completed transfer disappeared.
+func reconcilePayloadAfterTransfer(payload *Payload, revision int64,
+	newPayload *Payload, newRevision int64) (*Payload, int64, bool, error) {
+	if newPayload == nil {
+		return nil, newRevision, false, ErrPayloadNotFound
+	}
+	if revision == newRevision {
+		return payload, revision, false, nil
+	}
+	if !hasSameLayout(payload, newPayload) {
+		return nil, newRevision, false, ErrInvalidArgument
+	}
+	// Carry the latest revision forward even when the completed transfer is
+	// still valid (for example, another replica was added). This avoids
+	// finalizing against a stale CAS revision and preserves concurrent updates.
+	return newPayload, newRevision, !isSubsetOf(payload, newPayload), nil
+}
+
 func (store *P2PStore) GetReplica(ctx context.Context, name string, addrList []uintptr, sizeList []uint64) error {
 	if len(addrList) != len(sizeList) || len(addrList) == 0 {
 		return ErrInvalidArgument
@@ -343,83 +414,179 @@ func (store *P2PStore) GetReplica(ctx context.Context, name string, addrList []u
 	if payload == nil {
 		return ErrPayloadNotFound
 	}
+	replicaBuffers := buffersFromLists(addrList, sizeList)
 	for {
+		registrationMaxShardSize := payload.MaxShardSize
 		err = store.doGetReplica(ctx, payload, addrList, sizeList)
 		if err != nil {
+			// doGetReplica rolls back the current round on failure.
 			return err
 		}
-		newPayload, recheckRevision, err := store.metadata.Get(ctx, name)
+		newPayload, newRevision, err := store.metadata.Get(ctx, name)
 		if err != nil {
+			store.unregisterBuffers(replicaBuffers, registrationMaxShardSize)
 			return err
 		}
-		if revision == recheckRevision {
-			break
+		var retry bool
+		payload, revision, retry, err = reconcilePayloadAfterTransfer(
+			payload, revision, newPayload, newRevision)
+		if err != nil {
+			store.unregisterBuffers(replicaBuffers, registrationMaxShardSize)
+			return err
 		}
-		if isSubsetOf(payload, newPayload) {
+		if !retry {
 			break
 		}
+		// The completed transfer used a source that disappeared. Drop this
+		// round's registration before retrying against the latest snapshot.
+		store.unregisterBuffers(replicaBuffers, registrationMaxShardSize)
+	}
+	err = store.updatePayloadMetadata(ctx, name, addrList, sizeList, payload, revision)
+	if err != nil {
+		store.unregisterBuffers(replicaBuffers, payload.MaxShardSize)
+		return err
 	}
-	return store.updatePayloadMetadata(ctx, name, addrList, sizeList, payload, revision)
+	return nil
 }
 
 func (store *P2PStore) performTransfer(ctx context.Context, source uintptr, shard Shard) error {
 	retryCount := 0
 	maxRetryCount := max(3, shard.Count())
 	for retryCount < maxRetryCount {
-		batchID, err := store.transfer.allocateBatchID(1)
-		if err != nil {
-			return err
-		}
-
 		location := shard.GetLocation(retryCount)
 		if location == nil {
 			break
 		}
 
-		targetID, err := store.transfer.openSegment(location.SegmentName, retryCount == 0)
+		status, err := performTransferOnce(ctx, store.transfer, source, shard.Length, location, retryCount == 0)
 		if err != nil {
 			return err
 		}
 
-		request := TransferRequest{
-			Opcode:       OPCODE_READ,
-			Source:       uint64(source),
-			TargetID:     targetID,
-			TargetOffset: location.Offset,
-			Length:       shard.Length,
+		if status == STATUS_COMPLETED {
+			return nil
 		}
 
-		err = store.transfer.submitTransfer(batchID, []TransferRequest{request})
-		if err != nil {
-			return err
-		}
+		retryCount++
+	}
 
-		var status int
-		for status == STATUS_WAITING || status == STATUS_PENDING {
-			select {
-			case <-ctx.Done():
-				return ctx.Err()
-			default:
-				status, _, err = store.transfer.getTransferStatus(batchID, 0)
-				if err != nil {
-					return err
-				}
+	return ErrTooManyRetries
+}
+
+// batchTransport is the subset of TransferEngine a single transfer attempt
+// needs. It lets the batch lifecycle be exercised without the native engine.
+type batchTransport interface {
+	allocateBatchID(batchSize int) (BatchID, error)
+	openSegment(segmentName string, useCache bool) (int64, error)
+	submitTransfer(batchID BatchID, requests []TransferRequest) error
+	getTransferStatus(batchID BatchID, taskID int) (int, uint64, error)
+	freeBatchID(batchID BatchID) error
+}
+
+func isTransferInFlight(status int) bool {
+	return status == STATUS_WAITING || status == STATUS_PENDING
+}
+
+// performTransferOnce runs a single transfer attempt against the given
+// location. The allocated batch ID is released on every return path.
+//
+// The engine refuses to free a batch while any of its tasks is still in
+// flight (BatchBusy), so on context cancellation the task is drained to a
+// terminal state before the deferred free runs. Cancellation latency is
+// therefore bounded by the engine's own transfer timeout.
+func performTransferOnce(ctx context.Context, transport batchTransport, source uintptr, length uint64, location *Location, useCache bool) (status int, err error) {
+	batchID, err := transport.allocateBatchID(1)
+	if err != nil {
+		return STATUS_FAILED, err
+	}
+	defer func() {
+		freeErr := transport.freeBatchID(batchID)
+		if freeErr != nil {
+			log.Println("cascading error: failed to free batch ID:", freeErr)
+			if err == nil {
+				err = freeErr
 			}
 		}
+	}()
 
-		err = store.transfer.freeBatchID(batchID)
-		if err != nil {
-			return err
-		}
+	targetID, err := transport.openSegment(location.SegmentName, useCache)
+	if err != nil {
+		return STATUS_FAILED, err
+	}
 
-		if status == STATUS_COMPLETED {
-			return nil
-		}
+	request := TransferRequest{
+		Opcode:       OPCODE_READ,
+		Source:       uint64(source),
+		TargetID:     targetID,
+		TargetOffset: location.Offset,
+		Length:       length,
+	}
 
-		retryCount++
+	err = transport.submitTransfer(batchID, []TransferRequest{request})
+	if err != nil {
+		return STATUS_FAILED, err
 	}
 
-	return ErrTooManyRetries
+	status, err = waitTransfer(ctx, transport, batchID)
+	if err != nil {
+		return STATUS_FAILED, err
+	}
+	return status, nil
+}
+
+// Polling schedule for waitTransfer. The first pollSpinBudget polls run
+// back-to-back so short transfers still complete with no added latency;
+// after that the poller backs off exponentially from pollMinInterval to
+// pollMaxInterval. The cap stays small because some transports (for example
+// the NVLink async transport) only advance completion state when polled.
+const (
+	pollSpinBudget  = 128
+	pollMinInterval = 100 * time.Microsecond
+	pollMaxInterval = time.Millisecond
+)
+
+// sleepFn is the sleep used between polls. Tests replace it to observe the
+// backoff schedule without depending on wall-clock timing.
+var sleepFn = time.Sleep
+
+// waitTransfer polls task 0 of batchID until it reaches a terminal state.
+// The task is always driven to a terminal state, even if ctx is cancelled
+// (the engine refuses to free a batch with in-flight tasks). Cancellation
+// is then authoritative: if ctx is done by the time the task is terminal,
+// ctx.Err() is returned regardless of the observed status.
+//
+// doGetReplica starts one goroutine per shard, so for a checkpoint-sized
+// payload hundreds of pollers may be active at once. Spinning them all at
+// full speed for a transfer that takes seconds buys nothing in completion
+// latency and saturates cores; the spin budget plus backoff keeps the
+// fast path for small transfers while bounding CPU on large ones.
+func waitTransfer(ctx context.Context, transport batchTransport, batchID BatchID) (int, error) {
+	status := STATUS_WAITING
+	interval := pollMinInterval
+	for polls := 0; ; polls++ {
+		var err error
+		status, _, err = transport.getTransferStatus(batchID, 0)
+		if err != nil {
+			return STATUS_FAILED, err
+		}
+		if !isTransferInFlight(status) {
+			break
+		}
+		if polls < pollSpinBudget {
+			continue
+		}
+		sleepFn(interval)
+		if interval < pollMaxInterval {
+			interval *= 2
+			if interval > pollMaxInterval {
+				interval = pollMaxInterval
+			}
+		}
+	}
+	if err := ctx.Err(); err != nil {
+		return STATUS_FAILED, err
+	}
+	return status, nil
 }
 
 func (store *P2PStore) updatePayloadMetadata(ctx context.Context, name string, addrList []uintptr, sizeList []uint64, payload *Payload, revision int64) error {
diff --git a/mooncake-p2p-store/src/p2pstore/go.mod b/mooncake-p2p-store/src/p2pstore/go.mod
index 5929721056..924f0a2cb8 100644
--- a/mooncake-p2p-store/src/p2pstore/go.mod
+++ b/mooncake-p2p-store/src/p2pstore/go.mod
@@ -17,8 +17,8 @@ require (
 	golang.org/x/net v0.55.0 // indirect
 	golang.org/x/sys v0.45.0 // indirect
 	golang.org/x/text v0.37.0 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 // indirect
-	google.golang.org/grpc v1.79.3 // indirect
-	google.golang.org/protobuf v1.36.10 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
+	google.golang.org/grpc v1.83.1 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 )
diff --git a/mooncake-p2p-store/src/p2pstore/metadata_recheck_test.go b/mooncake-p2p-store/src/p2pstore/metadata_recheck_test.go
new file mode 100644
index 0000000000..30d29405ca
--- /dev/null
+++ b/mooncake-p2p-store/src/p2pstore/metadata_recheck_test.go
@@ -0,0 +1,242 @@
+// Copyright 2026 KVCache.AI
+//
+// 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 p2pstore
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+)
+
+type metadataResult struct {
+	payload  *Payload
+	revision int64
+	err      error
+}
+
+type scriptedMetadata struct {
+	results     []metadataResult
+	getCalls    int
+	updateCalls int
+}
+
+func (m *scriptedMetadata) Close() error { return nil }
+func (m *scriptedMetadata) Create(context.Context, string, *Payload) error {
+	return nil
+}
+func (m *scriptedMetadata) Put(context.Context, string, *Payload) error { return nil }
+func (m *scriptedMetadata) List(context.Context, string) ([]*Payload, error) {
+	return nil, nil
+}
+func (m *scriptedMetadata) Get(context.Context, string) (*Payload, int64, error) {
+	if m.getCalls >= len(m.results) {
+		return nil, -1, errors.New("unexpected metadata Get")
+	}
+	result := m.results[m.getCalls]
+	m.getCalls++
+	return result.payload, result.revision, result.err
+}
+func (m *scriptedMetadata) Update(context.Context, string, *Payload, int64) (bool, error) {
+	m.updateCalls++
+	return true, nil
+}
+
+type successfulTransferEngine struct {
+	mu     sync.Mutex
+	nextID BatchID
+	freed  int
+	reg    int
+	unreg  int
+	events []string
+}
+
+func (f *successfulTransferEngine) Close() {}
+func (f *successfulTransferEngine) GetLocalIpAndPort() (string, error) {
+	return "test", nil
+}
+func (f *successfulTransferEngine) registerLocalMemory(uintptr, uint64, string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.reg++
+	f.events = append(f.events, "register")
+	return nil
+}
+func (f *successfulTransferEngine) unregisterLocalMemory(uintptr) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.unreg++
+	f.events = append(f.events, "unregister")
+	return nil
+}
+func (f *successfulTransferEngine) allocateBatchID(int) (BatchID, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.nextID++
+	return f.nextID, nil
+}
+func (f *successfulTransferEngine) openSegment(string, bool) (int64, error) {
+	return 1, nil
+}
+func (f *successfulTransferEngine) submitTransfer(BatchID, []TransferRequest) error {
+	return nil
+}
+func (f *successfulTransferEngine) getTransferStatus(BatchID, int) (int, uint64, error) {
+	return STATUS_COMPLETED, 0, nil
+}
+func (f *successfulTransferEngine) freeBatchID(BatchID) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.freed++
+	return nil
+}
+
+func payloadWithLayout(size uint64, sources ...Location) *Payload {
+	shards := make([]Shard, 0, (size+4095)/4096)
+	for remaining := size; remaining > 0; {
+		length := min(remaining, uint64(4096))
+		shards = append(shards, Shard{Length: length, Gold: sources})
+		remaining -= length
+	}
+	return &Payload{
+		Name:         "payload",
+		Size:         size,
+		SizeList:     []uint64{size},
+		MaxShardSize: 4096,
+		Shards:       shards,
+	}
+}
+
+func newMetadataRecheckStore(metadata metadataStore) (*P2PStore, *successfulTransferEngine) {
+	engine := &successfulTransferEngine{}
+	return &P2PStore{
+		localServerName: "replica",
+		catalog:         NewCatalog(),
+		memory: &RegisteredMemory{
+			engine:       engine,
+			maxChunkSize: 4096,
+		},
+		metadata: metadata,
+		transfer: engine,
+	}, engine
+}
+
+func TestReconcilePayloadAfterTransfer(t *testing.T) {
+	sourceA := Location{SegmentName: "source-a", Offset: 0}
+	sourceB := Location{SegmentName: "source-b", Offset: 0}
+	original := payloadWithLayout(4096, sourceA, sourceB)
+
+	t.Run("removed source retries latest snapshot", func(t *testing.T) {
+		latest := payloadWithLayout(4096, sourceB)
+		payload, revision, retry, err := reconcilePayloadAfterTransfer(original, 10, latest, 11)
+		if err != nil {
+			t.Fatalf("reconcile failed: %v", err)
+		}
+		if !retry || payload != latest || revision != 11 {
+			t.Fatalf("retry=%v payload=%p revision=%d, want latest payload at revision 11", retry, payload, revision)
+		}
+	})
+
+	t.Run("added source keeps completed transfer", func(t *testing.T) {
+		latest := payloadWithLayout(4096, sourceA, sourceB,
+			Location{SegmentName: "source-c", Offset: 0})
+		payload, revision, retry, err := reconcilePayloadAfterTransfer(original, 10, latest, 11)
+		if err != nil {
+			t.Fatalf("reconcile failed: %v", err)
+		}
+		if retry || payload != latest || revision != 11 {
+			t.Fatalf("retry=%v payload=%p revision=%d, want completed latest payload at revision 11", retry, payload, revision)
+		}
+	})
+
+	t.Run("deleted payload returns not found", func(t *testing.T) {
+		_, _, retry, err := reconcilePayloadAfterTransfer(original, 10, nil, -1)
+		if !errors.Is(err, ErrPayloadNotFound) || retry {
+			t.Fatalf("retry=%v err=%v, want ErrPayloadNotFound without retry", retry, err)
+		}
+	})
+}
+
+func TestGetReplicaReleasesRegistrationBeforeRetry(t *testing.T) {
+	sourceA := Location{SegmentName: "source-a", Offset: 0}
+	sourceB := Location{SegmentName: "source-b", Offset: 0}
+	original := payloadWithLayout(4096, sourceA, sourceB)
+	latest := payloadWithLayout(4096, sourceB)
+	metadata := &scriptedMetadata{results: []metadataResult{
+		{payload: original, revision: 10},
+		{payload: latest, revision: 11},
+		{payload: latest, revision: 11},
+	}}
+	store, engine := newMetadataRecheckStore(metadata)
+
+	err := store.GetReplica(context.Background(), "payload", []uintptr{0x1000}, []uint64{4096})
+	if err != nil {
+		t.Fatalf("GetReplica failed: %v", err)
+	}
+	if len(store.memory.bufferList) != 1 || store.memory.bufferList[0].refCount != 1 {
+		t.Fatalf("registered memory = %+v, want one catalog-owned reference", store.memory.bufferList)
+	}
+	if engine.reg != 2 || engine.unreg != 1 {
+		t.Fatalf("memory registrations=%d unregistrations=%d, want 2 and 1", engine.reg, engine.unreg)
+	}
+	wantEvents := []string{"register", "unregister", "register"}
+	if len(engine.events) != len(wantEvents) {
+		t.Fatalf("memory events=%v, want %v", engine.events, wantEvents)
+	}
+	for i := range wantEvents {
+		if engine.events[i] != wantEvents[i] {
+			t.Fatalf("memory events=%v, want %v", engine.events, wantEvents)
+		}
+	}
+	if metadata.updateCalls != 1 {
+		t.Fatalf("metadata updates=%d, want 1", metadata.updateCalls)
+	}
+}
+
+func TestGetReplicaRejectsLayoutChangesAndReleasesRegistration(t *testing.T) {
+	source := Location{SegmentName: "source", Offset: 0}
+	tests := []struct {
+		name   string
+		latest *Payload
+	}{
+		{name: "payload growth", latest: payloadWithLayout(8192, source)},
+		{name: "payload shrinkage", latest: payloadWithLayout(2048, source)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			original := payloadWithLayout(4096, source)
+			metadata := &scriptedMetadata{results: []metadataResult{
+				{payload: original, revision: 10},
+				{payload: tt.latest, revision: 11},
+			}}
+			store, engine := newMetadataRecheckStore(metadata)
+
+			err := store.GetReplica(context.Background(), "payload", []uintptr{0x1000}, []uint64{4096})
+			if !errors.Is(err, ErrInvalidArgument) {
+				t.Fatalf("GetReplica error=%v, want ErrInvalidArgument", err)
+			}
+			if len(store.memory.bufferList) != 0 {
+				t.Fatalf("registered memory leaked: %+v", store.memory.bufferList)
+			}
+			if engine.reg != 1 || engine.unreg != 1 {
+				t.Fatalf("memory registrations=%d unregistrations=%d, want 1 and 1", engine.reg, engine.unreg)
+			}
+			if metadata.updateCalls != 0 {
+				t.Fatalf("metadata updates=%d, want 0", metadata.updateCalls)
+			}
+		})
+	}
+}
diff --git a/mooncake-p2p-store/src/p2pstore/perform_transfer_test.go b/mooncake-p2p-store/src/p2pstore/perform_transfer_test.go
new file mode 100644
index 0000000000..446bc820d7
--- /dev/null
+++ b/mooncake-p2p-store/src/p2pstore/perform_transfer_test.go
@@ -0,0 +1,207 @@
+// Copyright 2024 KVCache.AI
+//
+// 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 p2pstore
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+var errBatchBusy = errors.New("BatchID cannot be freed until all tasks are done")
+
+// fakeBatchTransport mirrors the engine's batch lifecycle: a submitted task
+// stays in flight for pollsUntilDone status polls, and freeBatchID refuses
+// with BatchBusy while the task is in flight, as MultiTransport::freeBatchID does.
+type fakeBatchTransport struct {
+	pollsUntilDone int
+	finalStatus    int
+	submitErr      error
+
+	polls          int
+	submitted      bool
+	freed          bool
+	busyRejections int
+}
+
+func (f *fakeBatchTransport) allocateBatchID(int) (BatchID, error) { return BatchID(42), nil }
+
+func (f *fakeBatchTransport) openSegment(string, bool) (int64, error) { return 1, nil }
+
+func (f *fakeBatchTransport) submitTransfer(BatchID, []TransferRequest) error {
+	if f.submitErr != nil {
+		return f.submitErr
+	}
+	f.submitted = true
+	return nil
+}
+
+func (f *fakeBatchTransport) inFlight() bool {
+	return f.submitted && f.polls < f.pollsUntilDone
+}
+
+func (f *fakeBatchTransport) getTransferStatus(BatchID, int) (int, uint64, error) {
+	f.polls++
+	if f.inFlight() {
+		return STATUS_PENDING, 0, nil
+	}
+	return f.finalStatus, 0, nil
+}
+
+func (f *fakeBatchTransport) freeBatchID(BatchID) error {
+	if f.inFlight() {
+		f.busyRejections++
+		return errBatchBusy
+	}
+	f.freed = true
+	return nil
+}
+
+func testLocation() *Location {
+	return &Location{SegmentName: "peer:12345", Offset: 0}
+}
+
+// TestPerformTransferOnceCancellationFreesBatch is the regression for the
+// cancellation leak: with the task still pending, returning on ctx.Done()
+// without draining makes the deferred free hit BatchBusy and leak the batch.
+func TestPerformTransferOnceCancellationFreesBatch(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	fake := &fakeBatchTransport{pollsUntilDone: 3, finalStatus: STATUS_COMPLETED}
+	_, err := performTransferOnce(ctx, fake, 0, 4096, testLocation(), true)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("err = %v, want context.Canceled", err)
+	}
+	if !fake.freed {
+		t.Fatal("batch ID leaked on cancellation")
+	}
+	if fake.busyRejections != 0 {
+		t.Fatalf("free attempted %d time(s) while the task was in flight", fake.busyRejections)
+	}
+}
+
+func TestPerformTransferOnceCompletedFreesBatch(t *testing.T) {
+	fake := &fakeBatchTransport{pollsUntilDone: 2, finalStatus: STATUS_COMPLETED}
+	status, err := performTransferOnce(context.Background(), fake, 0, 4096, testLocation(), true)
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if status != STATUS_COMPLETED {
+		t.Fatalf("status = %d, want STATUS_COMPLETED", status)
+	}
+	if !fake.freed {
+		t.Fatal("batch ID leaked on completion")
+	}
+}
+
+func TestPerformTransferOnceSubmitErrorFreesBatch(t *testing.T) {
+	submitErr := errors.New("submit failed")
+	fake := &fakeBatchTransport{submitErr: submitErr}
+	_, err := performTransferOnce(context.Background(), fake, 0, 4096, testLocation(), true)
+	if !errors.Is(err, submitErr) {
+		t.Fatalf("err = %v, want submit error", err)
+	}
+	if !fake.freed {
+		t.Fatal("batch ID leaked on submit failure")
+	}
+}
+
+// recordSleeps swaps sleepFn for a recorder so tests can assert the exact
+// backoff schedule instead of measuring wall-clock time.
+func recordSleeps(t *testing.T) *[]time.Duration {
+	t.Helper()
+	var slept []time.Duration
+	prev := sleepFn
+	sleepFn = func(d time.Duration) { slept = append(slept, d) }
+	t.Cleanup(func() { sleepFn = prev })
+	return &slept
+}
+
+// TestWaitTransferBacksOffAfterSpinBudget checks the polling schedule: within
+// the spin budget polls are back-to-back, after it every in-flight poll is
+// followed by one sleep, growing 100µs, 200µs, 400µs, 800µs, then capped at 1ms.
+func TestWaitTransferBacksOffAfterSpinBudget(t *testing.T) {
+	const extraPolls = 40
+	slept := recordSleeps(t)
+	fake := &fakeBatchTransport{pollsUntilDone: pollSpinBudget + extraPolls, finalStatus: STATUS_COMPLETED}
+	fake.submitted = true
+
+	status, err := waitTransfer(context.Background(), fake, BatchID(1))
+	if err != nil || status != STATUS_COMPLETED {
+		t.Fatalf("status=%d err=%v", status, err)
+	}
+	// The fake reports terminal state on poll number pollsUntilDone.
+	if fake.polls != pollSpinBudget+extraPolls {
+		t.Fatalf("polls = %d, want %d", fake.polls, pollSpinBudget+extraPolls)
+	}
+
+	var want []time.Duration
+	interval := pollMinInterval
+	for i := 0; i < extraPolls-1; i++ {
+		want = append(want, interval)
+		if interval < pollMaxInterval {
+			interval *= 2
+			if interval > pollMaxInterval {
+				interval = pollMaxInterval
+			}
+		}
+	}
+	if len(*slept) != len(want) {
+		t.Fatalf("sleep count = %d, want %d: %v", len(*slept), len(want), *slept)
+	}
+	for i := range want {
+		if (*slept)[i] != want[i] {
+			t.Fatalf("sleep[%d] = %v, want %v (schedule %v)", i, (*slept)[i], want[i], *slept)
+		}
+	}
+	if (*slept)[len(*slept)-1] != pollMaxInterval {
+		t.Fatalf("backoff did not reach the cap: last sleep %v", (*slept)[len(*slept)-1])
+	}
+}
+
+func TestWaitTransferWithinSpinBudgetDoesNotSleep(t *testing.T) {
+	slept := recordSleeps(t)
+	fake := &fakeBatchTransport{pollsUntilDone: pollSpinBudget / 2, finalStatus: STATUS_COMPLETED}
+	fake.submitted = true
+	if _, err := waitTransfer(context.Background(), fake, BatchID(1)); err != nil {
+		t.Fatal(err)
+	}
+	if len(*slept) != 0 {
+		t.Fatalf("spin-budget path slept %d time(s): %v", len(*slept), *slept)
+	}
+}
+
+// TestWaitTransferCancelledContextWinsOverTerminalStatus pins the edge case
+// where ctx is already cancelled and the very first poll reports a terminal
+// status: cancellation is authoritative and ctx.Err() is returned.
+func TestWaitTransferCancelledContextWinsOverTerminalStatus(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	fake := &fakeBatchTransport{pollsUntilDone: 0, finalStatus: STATUS_COMPLETED}
+	fake.submitted = true
+
+	status, err := waitTransfer(ctx, fake, BatchID(1))
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("err = %v, want context.Canceled", err)
+	}
+	if status != STATUS_FAILED {
+		t.Fatalf("status = %d, want STATUS_FAILED", status)
+	}
+	if fake.polls != 1 {
+		t.Fatalf("polls = %d, want 1 (terminal on first poll)", fake.polls)
+	}
+}
diff --git a/mooncake-p2p-store/src/p2pstore/registered_memory.go b/mooncake-p2p-store/src/p2pstore/registered_memory.go
index 099e3d2e4b..9255129718 100644
--- a/mooncake-p2p-store/src/p2pstore/registered_memory.go
+++ b/mooncake-p2p-store/src/p2pstore/registered_memory.go
@@ -26,12 +26,17 @@ type BufferHandle struct {
 }
 
 type RegisteredMemory struct {
-	engine       *TransferEngine
+	engine       localMemoryTransport
 	bufferList   []BufferHandle
 	mu           sync.Mutex
 	maxChunkSize uint64
 }
 
+type localMemoryTransport interface {
+	registerLocalMemory(uintptr, uint64, string) error
+	unregisterLocalMemory(uintptr) error
+}
+
 func NewRegisteredMemory(transferEngine *TransferEngine, maxChunkSize uint64) *RegisteredMemory {
 	return &RegisteredMemory{engine: transferEngine, maxChunkSize: maxChunkSize}
 }
diff --git a/mooncake-pg/include/mooncake_worker.cuh b/mooncake-pg/include/mooncake_worker.cuh
index 6efdc58389..d971264dd3 100644
--- a/mooncake-pg/include/mooncake_worker.cuh
+++ b/mooncake-pg/include/mooncake_worker.cuh
@@ -1,6 +1,7 @@
 #ifndef MOONCAKE_WORKER_CUH
 #define MOONCAKE_WORKER_CUH
 
+#include <array>
 #include <atomic>
 #include <functional>
 
@@ -31,9 +32,13 @@ class MooncakeCommunicator;
 //   Isolated --(Active view)--> Normal
 //
 // Joining member:
-//   Isolated --(joinGroup: drain preparation collectives)--> Quiescing
+//   Isolated ---------(joinGroup: drain operations)--------> Quiescing
 //            -----------------(Active view)----------------> Normal
 //
+// In-place rejoining member:
+//   Normal + inactive --(joinGroup: drain operations)------> Quiescing
+//                     ---------(Active view)---------------> Normal
+//
 // Isolated admits local-only collectives with an {self} active ranks mask.
 // Quiescing rejects new collectives while waiting for activation. Normal uses
 // the Coordinator's committed membership as active ranks. These are local
@@ -63,6 +68,7 @@ struct TransferGroupMeta {
 
     bool* activeRanks;
     bool* activeRanksDevice;
+    int32_t* activeRanksMirrorDevice = nullptr;
     bool* maybeActivatable;
     RankState rankStates[kMaxNumRanks];  // per GlobalRank
     uint64_t rankEpochs[kMaxNumRanks];
@@ -107,6 +113,8 @@ class MooncakeWorker {
 
     void Start();
 
+    bool hasPendingActiveRanksMirrorUpdate(const TransferGroupMeta* meta) const;
+
     /**
      * @brief Waits for all active collective tasks for the given communicator
      * to complete.
@@ -126,22 +134,26 @@ class MooncakeWorker {
     void waitUntilTasksSubmitted(
         const std::vector<CudaTaskSubmissionToken>& tasks) const;
 
-    static constexpr size_t kNumTasks_ = 4;
+    static constexpr size_t kNumCpuTasks_ = 2;
+    static constexpr size_t kNumCudaTasks_ = 2;
+    static constexpr size_t kCudaTaskOffset_ = kNumCpuTasks_;
+    static constexpr size_t kNumTasks_ = kNumCpuTasks_ + kNumCudaTasks_;
 
     static constexpr size_t kDrainTasksTimeoutMs = 5000;  // 5s
 
     std::atomic<bool> running_{false};
     std::atomic<bool> started_{false};
     int cuda_device_index_;
-    std::optional<GpuStream> enqueue_stream_;
+    std::array<std::optional<GpuStream>, kNumCudaTasks_> enqueue_streams_;
 
     Task *tasks_, *tasks_device_;
     bool hasCallback_[kNumTasks_]{};
     std::function<void()> callbacks_[kNumTasks_]{};
 
     int cpuTaskCount = 0;
-    int cudaTaskCount = 0;
+    size_t cudaOpCount = 0;
     std::atomic<uint64_t> next_cuda_task_sequence_{1};
+    std::atomic<uint64_t> next_active_ranks_mirror_generation_{1};
     std::atomic<uint64_t> submitted_task_sequence_[kNumTasks_]{};
 
     std::thread worker_thread_;
diff --git a/mooncake-pg/include/mooncake_worker_kernels.cuh b/mooncake-pg/include/mooncake_worker_kernels.cuh
index 35b6613f4e..cc29f2e486 100644
--- a/mooncake-pg/include/mooncake_worker_kernels.cuh
+++ b/mooncake-pg/include/mooncake_worker_kernels.cuh
@@ -14,6 +14,10 @@ __global__
 #endif
     struct Task {
     volatile bool active = false;
+    // Host publishes a new request generation; the resident enqueue kernel
+    // publishes the generation only after the device mirror has been updated.
+    uint64_t activeRanksMirrorRequestGeneration = 0;
+    uint64_t activeRanksMirrorAppliedGeneration = 0;
     int opType =
         0;  // c10d::OpType as int, for ABI compatibility with kernel code
     size_t dataSize;  // In bytes
@@ -32,7 +36,9 @@ __global__ void enqueueTaskKernel(int opType, size_t dataSize,
                                   uint64_t submitSequence,
                                   int32_t* failedRanksHint,
                                   bool resetFailedRanksHint, void* meta,
-                                  Task* tasks, size_t taskId);
+                                  bool* activeRanks, int32_t* activeRanksMirror,
+                                  size_t activeRanksCount, Task* tasks,
+                                  size_t taskId);
 
 template <typename scalar_t>
 __global__ void reduceKernel(scalar_t* dst, const scalar_t* src,
@@ -49,7 +55,9 @@ __global__ void reduceKernel(scalar_t* dst, const scalar_t* src,
 void launchEnqueueTaskKernel(int opType, size_t dataSize, int64_t broadcastRoot,
                              int bufferOffset, uint64_t submitSequence,
                              int32_t* failedRanksHint,
-                             bool resetFailedRanksHint, void* meta, Task* tasks,
+                             bool resetFailedRanksHint, void* meta,
+                             bool* activeRanks, int32_t* activeRanksMirror,
+                             size_t activeRanksCount, Task* tasks,
                              size_t taskId, cudaStream_t stream);
 
 void launchReduceKernel_uint8(uint8_t* dst, const uint8_t* src,
diff --git a/mooncake-pg/include/p2p_proxy.h b/mooncake-pg/include/p2p_proxy.h
index 6b17d126cf..8e42f278ed 100644
--- a/mooncake-pg/include/p2p_proxy.h
+++ b/mooncake-pg/include/p2p_proxy.h
@@ -274,7 +274,7 @@ class P2PProxy {
    public:
     friend class P2PDeviceWorker;
 
-    enum class IssueResult : uint8_t { kIssued, kNoCredit, kTimeout };
+    enum class IssueResult : uint8_t { kIssued, kNoCredit, kFailed };
 
     struct Options {
         bool is_cpu = false;
@@ -335,15 +335,6 @@ class P2PProxy {
      */
     void abandonResources();
 
-    // Epoch for fault recovery.  All control slots carry this
-    // value so that stale messages from before a Reset can be detected.
-    uint32_t getEpoch(int peer_rank) const {
-        return peer_epoch_[peer_rank].load(std::memory_order_acquire);
-    }
-    void setEpoch(int peer_rank, uint32_t epoch) {
-        peer_epoch_[peer_rank].store(epoch, std::memory_order_release);
-    }
-
    private:
     // Sender-side per-chunk state machine.
     enum class SendTaskState {
@@ -375,7 +366,7 @@ class P2PProxy {
         SendTransferTask() = default;
         SendTransferTask(uint64_t buffer_offset_in, uint32_t chunk_len_in,
                          void* staging_addr_in, uint64_t remote_addr_in,
-                         uint32_t sequence_in, uint32_t epoch_in);
+                         uint32_t sequence_in);
 
         SendTaskState state_ = SendTaskState::kCopyIn;
         uint64_t buffer_offset_ = 0;  // Offset inside the user buffer.
@@ -383,7 +374,6 @@ class P2PProxy {
         void* staging_addr_ = nullptr;  // Address inside SendPool.
         uint64_t remote_addr_ = 0;      // Address inside REMOTE RecvPool.
         uint32_t sequence_ = 0;         // Sequence number in the control ring.
-        uint32_t epoch_ = 0;            // Epoch for Reset detection.
         std::optional<BatchID> transfer_batch_id_;  // RDMA Write batch id.
         std::optional<BatchID> ack_batch_id_;       // AckSlot write batch id.
         cudaEvent_t copy_ready_event_ = nullptr;  // Signals Copy-In done (GPU).
@@ -408,6 +398,8 @@ class P2PProxy {
         // staging buffers.  When bytes_staged_ == total_bytes_ every chunk
         // has at least entered the Copy-In stage.
         uint64_t bytes_staged_ = 0;
+        // Epoch of the first accepted credit, used for all ACKs.
+        std::optional<uint32_t> credit_epoch_;
         int32_t* failed_ranks_hint_ = nullptr;
 
         std::chrono::steady_clock::time_point last_update_time_;
@@ -420,15 +412,13 @@ class P2PProxy {
     struct RecvTransferTask {
         RecvTransferTask() = default;
         RecvTransferTask(uint64_t buffer_offset_in, uint32_t chunk_len_in,
-                         void* local_addr_in, uint32_t sequence_in,
-                         uint32_t epoch_in);
+                         void* local_addr_in, uint32_t sequence_in);
 
         RecvTaskState state_ = RecvTaskState::kIssueCredit;
         uint64_t buffer_offset_ = 0;  // Offset inside the user buffer.
         uint32_t chunk_len_ = 0;      // Bytes in this chunk.
         void* local_addr_ = nullptr;  // Address inside local RecvPool.
         uint32_t sequence_ = 0;       // Sequence number in the control ring.
-        uint32_t epoch_ = 0;          // Epoch for Reset detection.
         std::optional<BatchID>
             credit_batch_id_;  // CreditSlot RDMA Write batch id.
         cudaEvent_t copy_ready_event_ =
@@ -441,7 +431,7 @@ class P2PProxy {
     // kWaitAck -> kCopyOut -> kFinished).
     struct RecvOpContext {
         RecvOpContext() = default;
-        RecvOpContext(RecvOp&& op_in);
+        RecvOpContext(RecvOp&& op_in, uint32_t credit_epoch);
 
         std::deque<RecvTransferTask> tasks_;
         std::shared_ptr<std::promise<void>> completion_;
@@ -455,6 +445,8 @@ class P2PProxy {
         // CreditSlot has been sent to the peer.  When bytes_credited_ ==
         // total_bytes_ the entire buffer has been offered to the sender.
         uint64_t bytes_credited_ = 0;
+        // Epoch captured at enqueue, used for credits and ACK matching.
+        uint32_t credit_epoch_ = 0;
     };
 
     // Per-peer sender state.  The sender consumes CreditSlots that the
@@ -463,8 +455,11 @@ class P2PProxy {
         std::deque<SendOpContext> pending_send_ops_;
         std::optional<SendOpContext> active_send_op_;
         // Sequence number of the next CreditSlot to consume from this peer.
-        // Monotonically increases; wraps around the ring via modulo.
+        // Increases between resets; indexes the ring modulo its size.
         uint64_t credit_consume_seq_ = 0;
+        // Group epoch observed at the last reset; older credits are rejected.
+        // This cannot distinguish credits across resets within the same epoch.
+        uint32_t minimum_credit_epoch_ = 0;
         std::array<cudaEvent_t, kP2PControlRingSize> copy_ready_events_;
     };
 
@@ -522,7 +517,7 @@ class P2PProxy {
     // Clean up the active op on a lane
     void cleanupFailedSendOp(SendOpContext& op_ctx);
     void cleanupFailedRecvOp(RecvOpContext& op_ctx);
-    // Reset P2P session and push link event to Agent.
+    // Request a lane reset and report the link failure to the Agent.
     void reportPeerFailure(int peer_rank);
     // Clean up, mark kFailed, and report the failure.
     void handleFailedSendOp(SendOpContext& op_ctx);
@@ -591,11 +586,6 @@ class P2PProxy {
     std::atomic<int> active_send_tasks_{0};
     std::atomic<int> active_recv_tasks_{0};
 
-    // Per-peer epoch for fault recovery.  Incremented in resetPeerState
-    // and performSend/RecvReset so that stale messages from a previous epoch
-    // can be detected on a per-peer basis.
-    std::array<std::atomic<uint32_t>, kMaxNumRanks> peer_epoch_;
-
     std::array<SendPeerLane, kMaxNumRanks> send_peer_lanes_;
     std::array<RecvPeerLane, kMaxNumRanks> recv_peer_lanes_;
 };
diff --git a/mooncake-pg/src/CMakeLists.txt b/mooncake-pg/src/CMakeLists.txt
index 3da240c604..28aea3075c 100644
--- a/mooncake-pg/src/CMakeLists.txt
+++ b/mooncake-pg/src/CMakeLists.txt
@@ -1,37 +1,50 @@
 set(_pg_device_source "${CMAKE_CURRENT_SOURCE_DIR}/mooncake_worker.cu")
 if(USE_CUDA)
-  # Preserve the existing sm_80/sm_90 coverage unless the caller selects
-  # architectures through CMake's standard variable or CUDAARCHS environment.
-  if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES AND
-     "$ENV{CUDAARCHS}" STREQUAL "")
-    set(CMAKE_CUDA_ARCHITECTURES 80-real 90-real)
+  # Preserve the existing sm_80/sm_90 coverage on CUDA 12 unless the caller
+  # selects architectures through CMake's standard variable or CUDAARCHS
+  # environment.
+  if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES AND "$ENV{CUDAARCHS}" STREQUAL "")
+    if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL "13.0")
+      set(CMAKE_CUDA_ARCHITECTURES 80-real 90-real 103-real)
+    else()
+      set(CMAKE_CUDA_ARCHITECTURES 80-real 90-real)
+    endif()
   endif()
   enable_language(CUDA)
   set(_pg_device_input "${_pg_device_source}")
 elseif(USE_MUSA OR USE_MACA)
-  set(_pg_device_object
-      "${CMAKE_CURRENT_BINARY_DIR}/mooncake_worker_device.o")
-  set(_pg_device_depfile
-      "${CMAKE_CURRENT_BINARY_DIR}/mooncake_worker_device.d")
+  set(_pg_device_object "${CMAKE_CURRENT_BINARY_DIR}/mooncake_worker_device.o")
+  set(_pg_device_depfile "${CMAKE_CURRENT_BINARY_DIR}/mooncake_worker_device.d")
   set(_pg_device_flags
       -std=c++20
       -O3
       -MMD
-      -MT "${_pg_device_object}"
-      -MF "${_pg_device_depfile}"
+      -MT
+      "${_pg_device_object}"
+      -MF
+      "${_pg_device_depfile}"
       "-I${CMAKE_CURRENT_SOURCE_DIR}/../include"
       "-I${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include")
+  # mcc/mxcc run outside a CMake compile target, so linked target usage
+  # requirements do not reach this custom command automatically.
+  get_target_property(_pg_ylt_include_dirs yalantinglibs
+                      INTERFACE_INCLUDE_DIRECTORIES)
+  foreach(_pg_ylt_include_dir IN LISTS _pg_ylt_include_dirs)
+    list(APPEND _pg_device_flags
+         "$<$<BOOL:${_pg_ylt_include_dir}>:-I${_pg_ylt_include_dir}>")
+  endforeach()
   set(_pg_device_dependencies
       "${_pg_device_source}"
       "${CMAKE_CURRENT_SOURCE_DIR}/../include/mooncake_worker_kernels.cuh"
       "${CMAKE_CURRENT_SOURCE_DIR}/../include/error_types.h"
       "${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include/common.h"
       "${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include/cuda_alike.h"
-      "${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include/transfer_engine.h")
+      "${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-transfer-engine/include/transfer_engine.h"
+  )
   set(_pg_depfile_argument)
-  if(CMAKE_GENERATOR MATCHES "^Ninja" OR
-     (CMAKE_GENERATOR MATCHES "Makefiles" AND
-      CMAKE_VERSION VERSION_GREATER_EQUAL 3.20))
+  if(CMAKE_GENERATOR MATCHES "^Ninja"
+     OR (CMAKE_GENERATOR MATCHES "Makefiles" AND CMAKE_VERSION
+                                                 VERSION_GREATER_EQUAL 3.20))
     set(_pg_depfile_argument DEPFILE "${_pg_device_depfile}")
   endif()
 
@@ -43,11 +56,8 @@ elseif(USE_MUSA OR USE_MACA)
     else()
       set(_pg_device_compiler_hint /usr/local/musa/bin)
     endif()
-    set(_pg_platform_device_flags
-        -x musa
-        -fPIC
-        --cuda-gpu-arch=mp_21
-        --cuda-gpu-arch=mp_31)
+    set(_pg_platform_device_flags -x musa -fPIC --cuda-gpu-arch=mp_21
+                                  --cuda-gpu-arch=mp_31)
   elseif(USE_MACA)
     set(_pg_platform_name MACA)
     set(_pg_device_compiler_name mxcc)
@@ -55,32 +65,32 @@ elseif(USE_MUSA OR USE_MACA)
     set(_pg_platform_device_flags --compiler-options=-fPIC)
   endif()
 
-  find_program(_pg_device_compiler NAMES "${_pg_device_compiler_name}"
-               HINTS "${_pg_device_compiler_hint}")
+  find_program(
+    _pg_device_compiler
+    NAMES "${_pg_device_compiler_name}"
+    HINTS "${_pg_device_compiler_hint}")
   if(NOT _pg_device_compiler)
-    message(FATAL_ERROR
-            "USE_${_pg_platform_name}=ON requires the "
-            "${_pg_platform_name} compiler (${_pg_device_compiler_name})")
+    message(
+      FATAL_ERROR "USE_${_pg_platform_name}=ON requires the "
+                  "${_pg_platform_name} compiler (${_pg_device_compiler_name})")
   endif()
-  list(APPEND _pg_device_flags
-       "-DUSE_${_pg_platform_name}"
-       ${_pg_platform_device_flags})
+  list(APPEND _pg_device_flags "-DUSE_${_pg_platform_name}"
+       "-DMOONCAKE_EP_USE_${_pg_platform_name}=1" ${_pg_platform_device_flags})
 
   add_custom_command(
     OUTPUT "${_pg_device_object}"
-    COMMAND "${_pg_device_compiler}" ${_pg_device_flags}
-            -c "${_pg_device_source}" -o "${_pg_device_object}"
-    DEPENDS ${_pg_device_dependencies}
-    ${_pg_depfile_argument}
+    COMMAND "${_pg_device_compiler}" ${_pg_device_flags} -c
+            "${_pg_device_source}" -o "${_pg_device_object}"
+    DEPENDS ${_pg_device_dependencies} ${_pg_depfile_argument}
     COMMENT "Compiling the Mooncake PG ${_pg_platform_name} worker"
-    COMMAND_EXPAND_LISTS
-    VERBATIM)
+    COMMAND_EXPAND_LISTS VERBATIM)
   set_source_files_properties("${_pg_device_object}"
                               PROPERTIES GENERATED TRUE EXTERNAL_OBJECT TRUE)
   set(_pg_device_input "${_pg_device_object}")
 else()
-  message(FATAL_ERROR
-          "Mooncake PG currently requires one of USE_CUDA, USE_MUSA, or USE_MACA")
+  message(
+    FATAL_ERROR
+      "Mooncake PG currently requires one of USE_CUDA, USE_MUSA, or USE_MACA")
 endif()
 
 # Keep the GPU fatbin out of the host core so auditwheel can safely repair the
@@ -100,8 +110,8 @@ if(USE_CUDA)
                CUDA_STANDARD_REQUIRED ON
                CUDA_EXTENSIONS OFF
                CUDA_RUNTIME_LIBRARY Shared)
-  target_compile_options(
-    mooncake_pg_device PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:-O3>)
+  target_compile_options(mooncake_pg_device
+                         PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:-O3>)
   target_link_libraries(mooncake_pg_device PRIVATE CUDA::cudart)
 elseif(USE_MUSA)
   set_target_properties(mooncake_pg_device PROPERTIES LINKER_LANGUAGE CXX)
@@ -119,31 +129,32 @@ set_target_properties(
   PROPERTIES POSITION_INDEPENDENT_CODE ON
              BUILD_RPATH "$ORIGIN"
              BUILD_RPATH_USE_ORIGIN YES)
+target_link_libraries(mooncake_pg_device PRIVATE yalantinglibs::yalantinglibs)
 
-add_library(mooncake_pg SHARED
-    control_plane/link_manager.cpp
-    control_plane/coordinator.cpp
-    control_plane/coordinator_host.cpp
-    control_plane/agent.cpp
-    control_plane/agent_host.cpp
-    control_plane/rpc_runtime.cpp
-    gpu_runtime.cpp
-    mooncake_communicator.cpp
-    mooncake_pg.cpp
-    mooncake_worker_host.cpp
-    mooncake_worker_thread.cpp
-    p2p_proxy.cpp
-)
+add_library(
+  mooncake_pg SHARED
+  control_plane/link_manager.cpp
+  control_plane/coordinator.cpp
+  control_plane/coordinator_host.cpp
+  control_plane/agent.cpp
+  control_plane/agent_host.cpp
+  control_plane/rpc_runtime.cpp
+  gpu_runtime.cpp
+  mooncake_communicator.cpp
+  mooncake_pg.cpp
+  mooncake_worker_host.cpp
+  mooncake_worker_thread.cpp
+  p2p_proxy.cpp)
 
 target_compile_features(mooncake_pg PRIVATE cxx_std_20)
 target_include_directories(
-  mooncake_pg
-  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
-         $<INSTALL_INTERFACE:include>)
+  mooncake_pg PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
+                     $<INSTALL_INTERFACE:include>)
 target_link_libraries(mooncake_pg PRIVATE transfer_engine mooncake_pg_device)
 
 set_target_properties(
   mooncake_pg
   PROPERTIES POSITION_INDEPENDENT_CODE ON
              BUILD_RPATH "$ORIGIN"
-             BUILD_RPATH_USE_ORIGIN YES)
+             BUILD_RPATH_USE_ORIGIN YES
+             INSTALL_RPATH "$ORIGIN")
diff --git a/mooncake-pg/src/mooncake_communicator.cpp b/mooncake-pg/src/mooncake_communicator.cpp
index 647b7361d0..15b37bc0ec 100644
--- a/mooncake-pg/src/mooncake_communicator.cpp
+++ b/mooncake-pg/src/mooncake_communicator.cpp
@@ -505,6 +505,10 @@ PGResult<void> MooncakeCommunicator::initialize(
     meta_->engine = context_.engine;
     meta_->communicator = this;
     meta_->autoSyncOnFailure = config.auto_sync_on_failure;
+    if (active_ranks_mirror_ && active_ranks_mirror_is_device_ &&
+        active_ranks_mirror_device_index_ == device_index_) {
+        meta_->activeRanksMirrorDevice = active_ranks_mirror_;
+    }
     p2p_proxy_->bindMeta(meta_);
 
     // Active ranks will be filled by applyViewUpdate, so only allocate their
@@ -616,15 +620,16 @@ PGResult<void> MooncakeCommunicator::checkOpState(OpType op) const {
             "rank " + std::to_string(meta_->globalRank) +
                 " is offline and cannot perform operations");
     }
-    // P2P operations don't require the rank to be active in the group.
+    PG_VALIDATE_STATE(mode != CollectiveExtensionState::Quiescing,
+                      "rank is quiescing and cannot issue operations");
+
     const bool is_p2p = op == OpType::Send || op == OpType::Recv;
-    if (!isValidGroup() && is_p2p) {
-        return makePGError(PGErrorCode::NotSupported,
-                           "P2P is unavailable for an invalid Mooncake group");
-    }
-    if (!is_p2p) {
-        PG_VALIDATE_STATE(mode != CollectiveExtensionState::Quiescing,
-                          "rank is quiescing and cannot issue collectives");
+    if (is_p2p) {
+        // P2P operations require an valid group
+        PG_VALIDATE_STATE(isValidGroup(),
+                          "P2P is unavailable for an invalid group");
+    } else {
+        // Collectives in an invalid group remain local-only
         PG_VALIDATE_STATE(mode == CollectiveExtensionState::Isolated ||
                               meta_->activeRanks[rank_],
                           "rank is not active in this group");
@@ -1349,6 +1354,10 @@ void MooncakeCommunicator::syncActiveRanksMirror() const {
     auto active_ranks = getActiveRanks();
     const size_t bytes = max_group_size_ * sizeof(int32_t);
     if (active_ranks_mirror_is_device_) {
+        if (meta_ && meta_->activeRanksMirrorDevice && worker_ &&
+            worker_->hasPendingActiveRanksMirrorUpdate(meta_.get())) {
+            return;
+        }
         const GpuDeviceGuard device_guard(active_ranks_mirror_device_index_);
         PG_ASSERT_CUDA(cudaMemcpyAsync(
             active_ranks_mirror_, active_ranks.data(), bytes,
@@ -1433,19 +1442,32 @@ PGResult<ProposeViewUpdateResponse> MooncakeCommunicator::deactivateRanks(
 PGResult<void> MooncakeCommunicator::joinGroup() {
     PG_TRY(checkValidGroup("joinGroup"));
     auto mode = meta_->extensionMode.load(std::memory_order_acquire);
-    PG_VALIDATE_STATE(
-        mode == CollectiveExtensionState::Isolated,
-        "joinGroup may only be called once on an isolated joining "
-        "communicator");
-    // Stop admitting isolated collectives before advertising readiness.
+    const bool is_initial_join = mode == CollectiveExtensionState::Isolated;
+    const bool is_inplace_rejoin =
+        mode == CollectiveExtensionState::Normal && !meta_->activeRanks[rank_];
+    PG_VALIDATE_STATE(is_initial_join || is_inplace_rejoin,
+                      "joinGroup requires an isolated or inactive rank");
+    // Stop admitting operations before advertising readiness.
     meta_->extensionMode.store(CollectiveExtensionState::Quiescing,
                                std::memory_order_release);
+    if (!p2p_proxy_->drainTasks()) {
+        return makePGError(PGErrorCode::Timeout,
+                           "timed out draining join preparation P2P tasks for "
+                           "rank " +
+                               std::to_string(meta_->globalRank));
+    }
     if (!worker_->drainTasks(meta_.get())) {
         return makePGError(
             PGErrorCode::Timeout,
             "timed out draining join preparation collectives for rank " +
                 std::to_string(meta_->globalRank));
     }
+    // Auto-deactivation removes the old endpoint from the GroupView. The
+    // process and its registered buffers are still alive, so republish the
+    // current endpoint under a fresh endpoint epoch before declaring ready.
+    if (is_inplace_rejoin) {
+        PG_TRY(agent_.publishLocalEndpoint(buildEndpointMetadata()));
+    }
     PG_TRY(agent_.confirmReadyForActivation(meta_->group_id));
     // Block until the Coordinator activates this rank in the group.
     PG_TRY(agent_.waitUntilRankActive(meta_->group_id, meta_->globalRank,
@@ -1582,8 +1604,8 @@ void MooncakeCommunicator::applyViewUpdate(
         meta_->maybeActivatable[i] = activatable[i];
     }
 
-    // Keep the caller-visible active-ranks mirror in sync with the view.
-    // FIXME: potential deadlock?
+    // A failed CUDA task piggybacks same-device mirror update on its
+    // already-resident enqueue kernel. Other updates use a H2D copy.
     syncActiveRanksMirror();
 
     // Publish the rank-space extent after the corresponding data-plane state.
diff --git a/mooncake-pg/src/mooncake_worker.cu b/mooncake-pg/src/mooncake_worker.cu
index 46d18577e9..548b15634a 100644
--- a/mooncake-pg/src/mooncake_worker.cu
+++ b/mooncake-pg/src/mooncake_worker.cu
@@ -4,6 +4,7 @@
 
 #include <algorithm>
 #include <type_traits>
+#include <transport/device/device_ops.cuh>
 
 #ifdef __MUSA__
 #include <musa_bf16.h>
@@ -20,7 +21,9 @@ __global__ void enqueueTaskKernel(int opType, size_t dataSize,
                                   uint64_t submitSequence,
                                   int32_t* failedRanksHint,
                                   bool resetFailedRanksHint, void* meta,
-                                  Task* tasks, size_t taskId) {
+                                  bool* activeRanks, int32_t* activeRanksMirror,
+                                  size_t activeRanksCount, Task* tasks,
+                                  size_t taskId) {
     // Copy task into slot
     tasks[taskId].opType = opType;
     tasks[taskId].dataSize = dataSize;
@@ -39,6 +42,20 @@ __global__ void enqueueTaskKernel(int opType, size_t dataSize,
     while (tasks[taskId].active) {
         __threadfence_system();
     }
+
+    const uint64_t mirrorUpdateGeneration = device::mc_ld_acquire_u64(
+        &tasks[taskId].activeRanksMirrorRequestGeneration);
+    const uint64_t appliedMirrorUpdateGeneration = device::mc_ld_acquire_u64(
+        &tasks[taskId].activeRanksMirrorAppliedGeneration);
+    if (activeRanksMirror &&
+        mirrorUpdateGeneration != appliedMirrorUpdateGeneration) {
+        for (size_t rank = 0; rank < activeRanksCount; ++rank) {
+            activeRanksMirror[rank] = activeRanks[rank] ? 1 : 0;
+        }
+        device::mc_st_release_u64(
+            &tasks[taskId].activeRanksMirrorAppliedGeneration,
+            mirrorUpdateGeneration);
+    }
 }
 
 template <typename scalar_t>
@@ -137,11 +154,14 @@ namespace mooncake {
 void launchEnqueueTaskKernel(int opType, size_t dataSize, int64_t broadcastRoot,
                              int bufferOffset, uint64_t submitSequence,
                              int32_t* failedRanksHint,
-                             bool resetFailedRanksHint, void* meta, Task* tasks,
+                             bool resetFailedRanksHint, void* meta,
+                             bool* activeRanks, int32_t* activeRanksMirror,
+                             size_t activeRanksCount, Task* tasks,
                              size_t taskId, cudaStream_t stream) {
     enqueueTaskKernel<<<1, 1, 0, stream>>>(
         opType, dataSize, broadcastRoot, bufferOffset, submitSequence,
-        failedRanksHint, resetFailedRanksHint, meta, tasks, taskId);
+        failedRanksHint, resetFailedRanksHint, meta, activeRanks,
+        activeRanksMirror, activeRanksCount, tasks, taskId);
 }
 
 #define DEF_LAUNCH_REDUCE(scalar_t, suffix)                                   \
diff --git a/mooncake-pg/src/mooncake_worker_host.cpp b/mooncake-pg/src/mooncake_worker_host.cpp
index 7ae890157f..5ad12894d4 100644
--- a/mooncake-pg/src/mooncake_worker_host.cpp
+++ b/mooncake-pg/src/mooncake_worker_host.cpp
@@ -151,11 +151,15 @@ MooncakeWorker::MooncakeWorker(int cuda_device_index)
     }
 
     if (cuda_device_index_ >= 0) {
-        enqueue_stream_ = GpuStream::createNonBlocking(cuda_device_index_);
+        for (auto& enqueue_stream : enqueue_streams_) {
+            enqueue_stream = GpuStream::createNonBlocking(cuda_device_index_);
+        }
     }
 
     for (size_t i = 0; i < kNumTasks_; ++i) {
         tasks_[i].active = false;
+        tasks_[i].activeRanksMirrorRequestGeneration = 0;
+        tasks_[i].activeRanksMirrorAppliedGeneration = 0;
         tasks_[i].submitSequence = 0;
         tasks_[i].failedRanksHint = nullptr;
         tasks_[i].resetFailedRanksHint = false;
@@ -255,7 +259,17 @@ void MooncakeWorker::putTaskCuda(
     const GpuDeviceGuard guard(cuda_device_index_);
     const auto issue_stream =
         GpuStream::borrow(issueStream, cuda_device_index_);
-    const auto& enq_stream = enqueue_stream_.value();
+    const size_t cudaTaskSlot = cudaOpCount % kNumCudaTasks_;
+    const size_t taskId = kCudaTaskOffset_ + cudaTaskSlot;
+    const auto& enq_stream = enqueue_streams_[cudaTaskSlot].value();
+    ++cudaOpCount;
+
+    cudaStreamCaptureStatus issue_capture = cudaStreamCaptureStatusNone;
+    cudaStreamCaptureStatus enq_capture = cudaStreamCaptureStatusNone;
+    PG_ASSERT_CUDA(cudaStreamIsCapturing(issue_stream.get(), &issue_capture));
+    PG_ASSERT_CUDA(cudaStreamIsCapturing(enq_stream.get(), &enq_capture));
+    const bool is_capturing = issue_capture != cudaStreamCaptureStatusNone ||
+                              enq_capture != cudaStreamCaptureStatusNone;
 
     GpuEvent event_start(issue_stream.deviceIndex());
     event_start.record(issue_stream);
@@ -263,36 +277,42 @@ void MooncakeWorker::putTaskCuda(
 
     std::vector<CudaTaskSubmissionToken> submitted_tasks;
     submitted_tasks.reserve((tensorSize + chunkSize - 1) / chunkSize);
+
+    // Keep every chunk of one collective on the same task slot and enqueue
+    // stream. The next collective rotates to the other CUDA task slot.
     for (size_t pos = 0; pos < tensorSize; pos += chunkSize) {
         size_t realSize = std::min(tensorSize, pos + chunkSize) - pos;
-        int taskId = cudaTaskCount % 2 + 2;
         int bufferOffset = meta->taskCount % 2;
 
         const uint64_t taskSequence =
             next_cuda_task_sequence_.fetch_add(1, std::memory_order_relaxed);
         submitted_tasks.push_back(
-            {.task_id = static_cast<size_t>(taskId), .sequence = taskSequence});
+            {.task_id = taskId, .sequence = taskSequence});
         copyToSendBuffer(
             (void*)meta->segmentInfos[meta->rank].send_buffer[bufferOffset],
             pos, realSize, enq_stream.get());
 
         hasCallback_[taskId] = false;
 
-        launchEnqueueTaskKernel((int)opType, realSize, broadcastRoot,
-                                bufferOffset, taskSequence, failed_ranks_hint,
-                                pos == 0, meta.get(), tasks_device_, taskId,
-                                enq_stream.get());
+        launchEnqueueTaskKernel(
+            (int)opType, realSize, broadcastRoot, bufferOffset, taskSequence,
+            failed_ranks_hint, pos == 0, meta.get(), meta->activeRanksDevice,
+            meta->activeRanksMirrorDevice, meta->maxGroupSize, tasks_device_,
+            taskId, enq_stream.get());
         copyFromRecvBuffer(
             (void*)meta->segmentInfos[meta->rank].recv_buffer[bufferOffset],
             pos, realSize, enq_stream.get());
 
-        ++cudaTaskCount;
         ++meta->taskCount;
     }
 
-    // During CUDA graph capture the kernels are recorded but not executed, so
-    // waiting for the worker thread to observe them would hang.
-    if (!issue_stream.isCapturing()) {
+    // Each CUDA task slot is paired with a dedicated enqueue stream. All chunks
+    // of one collective stay on that pair, and reusing the same slot is
+    // serialized by the stream. In eager mode, finish each chunk's host-worker
+    // submission step before installing the completion wait on issue_stream
+    // below. Captured enqueue kernels have not run yet, so capture skips this
+    // gate.
+    if (!is_capturing) {
         waitUntilTasksSubmitted(submitted_tasks);
     }
 
diff --git a/mooncake-pg/src/mooncake_worker_thread.cpp b/mooncake-pg/src/mooncake_worker_thread.cpp
index 7e21a13195..558da6466d 100644
--- a/mooncake-pg/src/mooncake_worker_thread.cpp
+++ b/mooncake-pg/src/mooncake_worker_thread.cpp
@@ -27,6 +27,30 @@ void MooncakeWorker::Start() {
     }
 }
 
+bool MooncakeWorker::hasPendingActiveRanksMirrorUpdate(
+    const TransferGroupMeta* meta) const {
+    for (size_t i = kCudaTaskOffset_; i < kNumTasks_; ++i) {
+        auto& task = tasks_[i];
+        // The request generation is the publication token for this pending
+        // update. Keep this acquire before reading transferGroupMeta so the
+        // task-to-group association is observed after the request is
+        // published.
+        const uint64_t requested =
+            std::atomic_ref(task.activeRanksMirrorRequestGeneration)
+                .load(std::memory_order_acquire);
+        if (task.transferGroupMeta != meta) {
+            continue;
+        }
+        const uint64_t applied =
+            std::atomic_ref(task.activeRanksMirrorAppliedGeneration)
+                .load(std::memory_order_acquire);
+        if (requested != applied) {
+            return true;
+        }
+    }
+    return false;
+}
+
 bool MooncakeWorker::drainTasks(const TransferGroupMeta* meta) const {
     BackoffWaiter waiter;
     return waiter.wait_for(
@@ -372,6 +396,22 @@ void MooncakeWorker::startWorker() {
                             active_failed_ranks_hint[i] = nullptr;
                         }
 
+                        // Mark the resident-kernel mirror update as pending
+                        // before publishing the link event. The resulting
+                        // ViewUpdate must observe request != applied and skip
+                        // the host H2D path. The kernel consumes this request
+                        // and copies the updated active ranks.
+                        if (task_detected_failure[i] &&
+                            group->autoSyncOnFailure &&
+                            group->activeRanksMirrorDevice) {
+                            const uint64_t generation =
+                                next_active_ranks_mirror_generation_.fetch_add(
+                                    1, std::memory_order_relaxed);
+                            std::atomic_ref(
+                                task.activeRanksMirrorRequestGeneration)
+                                .store(generation, std::memory_order_release);
+                        }
+
                         // Push link event via communicator's Agent.
                         if (group->communicator) {
                             bool has_any_attempted = false;
diff --git a/mooncake-pg/src/p2p_proxy.cpp b/mooncake-pg/src/p2p_proxy.cpp
index 074eb692fe..edd3577ca4 100644
--- a/mooncake-pg/src/p2p_proxy.cpp
+++ b/mooncake-pg/src/p2p_proxy.cpp
@@ -218,10 +218,6 @@ void P2PProxy::allocateResources() {
         resources_.ack_region_[i].reset();
     }
 
-    for (size_t i = 0; i < kMaxNumRanks; ++i) {
-        peer_epoch_[i].store(1, std::memory_order_release);
-    }
-
     for (size_t i = 0; i < kMaxNumRanks; ++i) {
         send_peer_lanes_[i].pending_send_ops_.clear();
         send_peer_lanes_[i].active_send_op_.reset();
@@ -287,12 +283,6 @@ void P2PProxy::resetPeerState(int peer_rank) {
               "ResetPeerState: peer_rank out of range: ", peer_rank,
               " size: ", size_);
 
-    // Epoch update:
-    //   We bump epoch_ so that any slots still in flight from the
-    //   old session (written by the sender/receiver before it learned about
-    //   the Reset) are recognized as stale and skipped.
-    peer_epoch_[peer_rank].fetch_add(1, std::memory_order_acq_rel);
-
     // Request reset
     reset_send_req_[peer_rank].store(true, std::memory_order_release);
     reset_recv_req_[peer_rank].store(true, std::memory_order_release);
@@ -307,6 +297,8 @@ void P2PProxy::resetPeerState(int peer_rank) {
 // Reset sender state for peer_rank.
 void P2PProxy::performSendReset(int peer_rank) {
     resetSendLane(send_peer_lanes_[peer_rank]);
+    send_peer_lanes_[peer_rank].minimum_credit_epoch_ =
+        static_cast<uint32_t>(meta_->epoch.load(std::memory_order_acquire));
     resetPeerAckLanes(peer_rank);
 }
 
@@ -332,22 +324,35 @@ void P2PProxy::cleanupFailedRecvOp(RecvOpContext& op_ctx) {
     active_recv_tasks_.fetch_sub(1, std::memory_order_release);
 }
 
+void P2PProxy::reportPeerFailure(int peer_rank) {
+    // Request a reset of the peer's send and receive lanes.
+    resetPeerState(peer_rank);
+    // link event vector is indexed by GlobalRank.
+    const auto peer_global = meta_->rank_order[peer_rank];
+    const auto target_rank_epoch = meta_->rankEpochs[peer_global];
+    auto* communicator = meta_->communicator;
+    if (!communicator) return;
+
+    LinkEvent event;
+    event.events.assign(kMaxNumRanks, LinkEvent::EventType::None);
+    event.target_rank_epochs.assign(kMaxNumRanks, 0);
+    event.events[peer_global] = LinkEvent::EventType::Failure;
+    event.target_rank_epochs[peer_global] = target_rank_epoch;
+    communicator->getAgent().pushLinkEvent(event);
+
+    if (meta_->autoSyncOnFailure) {
+        auto result = communicator->syncAfterFailure();
+        PG_ASSERT(result.has_value() &&
+                      result.value().status != SyncAfterFailureStatus::Rejected,
+                  "syncAfterFailure failed for rank ", meta_->globalRank);
+    }
+}
+
 void P2PProxy::handleFailedSendOp(SendOpContext& op_ctx) {
     cleanupFailedSendOp(op_ctx);
     op_ctx.failed_ranks_hint_[op_ctx.peer_rank_] = 1;
-    // Reset P2P session state (epoch, lanes).
-    resetPeerState(op_ctx.peer_rank_);
-    // link event vector is indexed by GlobalRank.
+    reportPeerFailure(op_ctx.peer_rank_);
     const auto peer_global = meta_->rank_order[op_ctx.peer_rank_];
-    const auto target_rank_epoch = meta_->rankEpochs[peer_global];
-    if (meta_->communicator) {
-        LinkEvent event;
-        event.events.assign(kMaxNumRanks, LinkEvent::EventType::None);
-        event.target_rank_epochs.assign(kMaxNumRanks, 0);
-        event.events[peer_global] = LinkEvent::EventType::Failure;
-        event.target_rank_epochs[peer_global] = target_rank_epoch;
-        meta_->communicator->getAgent().pushLinkEvent(event);
-    }
     op_ctx.completion_->set_value();
     LOG(ERROR) << "Rank " << meta_->rank << ": P2P SendOp to peer "
                << op_ctx.peer_rank_ << " (global=" << peer_global
@@ -357,19 +362,8 @@ void P2PProxy::handleFailedSendOp(SendOpContext& op_ctx) {
 void P2PProxy::handleFailedRecvOp(RecvOpContext& op_ctx) {
     cleanupFailedRecvOp(op_ctx);
     op_ctx.failed_ranks_hint_[op_ctx.peer_rank_] = 1;
-    // Reset P2P session state (epoch, lanes).
-    resetPeerState(op_ctx.peer_rank_);
-    // link event vector is indexed by GlobalRank.
+    reportPeerFailure(op_ctx.peer_rank_);
     const auto peer_global = meta_->rank_order[op_ctx.peer_rank_];
-    const auto target_rank_epoch = meta_->rankEpochs[peer_global];
-    if (meta_->communicator) {
-        LinkEvent event;
-        event.events.assign(kMaxNumRanks, LinkEvent::EventType::None);
-        event.target_rank_epochs.assign(kMaxNumRanks, 0);
-        event.events[peer_global] = LinkEvent::EventType::Failure;
-        event.target_rank_epochs[peer_global] = target_rank_epoch;
-        meta_->communicator->getAgent().pushLinkEvent(event);
-    }
     op_ctx.completion_->set_value();
     LOG(ERROR) << "Rank " << meta_->rank << ": P2P RecvOp from peer "
                << op_ctx.peer_rank_ << " (global=" << peer_global
@@ -512,21 +506,24 @@ void P2PProxy::enqueueSend(SendOp op) {
 void P2PProxy::enqueueRecv(RecvOp op) {
     {
         std::lock_guard<std::mutex> lock(recv_queue_mutex_);
-        recv_queue_.emplace(std::move(op));
+        recv_queue_.emplace(std::move(op),
+                            static_cast<uint32_t>(
+                                meta_->epoch.load(std::memory_order_acquire)));
     }
     active_recv_tasks_.fetch_add(1, std::memory_order_release);
     if (device_worker_) device_worker_->wakeUpRecv();
 }
 
-P2PProxy::SendTransferTask::SendTransferTask(
-    uint64_t buffer_offset_in, uint32_t chunk_len_in, void* staging_addr_in,
-    uint64_t remote_addr_in, uint32_t sequence_in, uint32_t epoch_in)
+P2PProxy::SendTransferTask::SendTransferTask(uint64_t buffer_offset_in,
+                                             uint32_t chunk_len_in,
+                                             void* staging_addr_in,
+                                             uint64_t remote_addr_in,
+                                             uint32_t sequence_in)
     : buffer_offset_(buffer_offset_in),
       chunk_len_(chunk_len_in),
       staging_addr_(staging_addr_in),
       remote_addr_(remote_addr_in),
-      sequence_(sequence_in),
-      epoch_(epoch_in) {
+      sequence_(sequence_in) {
     last_update_time_ = std::chrono::steady_clock::now();
 }
 
@@ -543,22 +540,21 @@ P2PProxy::SendOpContext::SendOpContext(SendOp&& op_in)
 P2PProxy::RecvTransferTask::RecvTransferTask(uint64_t buffer_offset_in,
                                              uint32_t chunk_len_in,
                                              void* local_addr_in,
-                                             uint32_t sequence_in,
-                                             uint32_t epoch_in)
+                                             uint32_t sequence_in)
     : buffer_offset_(buffer_offset_in),
       chunk_len_(chunk_len_in),
       local_addr_(local_addr_in),
-      sequence_(sequence_in),
-      epoch_(epoch_in) {
+      sequence_(sequence_in) {
     last_update_time_ = std::chrono::steady_clock::now();
 }
 
-P2PProxy::RecvOpContext::RecvOpContext(RecvOp&& op_in)
+P2PProxy::RecvOpContext::RecvOpContext(RecvOp&& op_in, uint32_t credit_epoch)
     : completion_(std::move(op_in.completion_)),
       buffer_(op_in.buffer_),
       peer_rank_(op_in.peer_rank_),
       cuda_stream_(op_in.cuda_stream_),
-      failed_ranks_hint_(op_in.failed_ranks_hint_) {
+      failed_ranks_hint_(op_in.failed_ranks_hint_),
+      credit_epoch_(credit_epoch) {
     total_bytes_ = op_in.size_;
 }
 
@@ -632,15 +628,14 @@ bool P2PProxy::tryIssueRecvTask(RecvOpContext& op_ctx, RecvPeerLane& lane) {
     const uint64_t remote_credit_offset =
         getRemoteCreditSlot(op_ctx.peer_rank_, seq);
 
-    const uint32_t curr_epoch =
-        peer_epoch_[op_ctx.peer_rank_].load(std::memory_order_acquire);
     op_ctx.tasks_.emplace_back(op_ctx.bytes_credited_, chunk_len, local_addr,
-                               seq, curr_epoch);
+                               seq);
     auto& task = op_ctx.tasks_.back();
 
     auto* credit_staging_buf = getLocalCreditStagingBuf(op_ctx.peer_rank_, seq);
-    credit_staging_buf->publish(
-        curr_epoch, seq, reinterpret_cast<uint64_t>(local_addr), chunk_len);
+    credit_staging_buf->publish(op_ctx.credit_epoch_, seq,
+                                reinterpret_cast<uint64_t>(local_addr),
+                                chunk_len);
     const BatchID batch_id = engine_->allocateBatchID(1);
     engine_->submitTransfer(
         batch_id, {TransferRequest{
@@ -733,17 +728,16 @@ bool P2PProxy::stepRecvCopyOut(RecvTransferTask& task) {
 
 // Sender fetches credits.
 //
-// Poll the local CreditLane for the next expected sequence.  If the slot
-// matches our consume cursor we accept the credit: allocate a staging
-// chunk from SendPool, copy the corresponding slice of the user buffer into
-// it, and advance the cursor.  If the pool is full or no credit has
-// arrived we return false immediately (non-blocking).
+// Poll the local CreditLane for the next expected sequence and stage a chunk
+// from the user buffer. Returns kIssued on progress (including stale-slot
+// clearing), kNoCredit when no progress can be made here, and kFailed on
+// timeout or inconsistent credit epochs within the op.
 P2PProxy::IssueResult P2PProxy::tryIssueSendTask(SendOpContext& op_ctx,
                                                  SendPeerLane& lane) {
     // Check for timeout while waiting for the peer's CreditSlot.
     if (isTimeout(op_ctx)) {
         LOG(ERROR) << "P2P wait-for-credit timeout, peer=" << op_ctx.peer_rank_;
-        return IssueResult::kTimeout;
+        return IssueResult::kFailed;
     }
 
     if (op_ctx.bytes_staged_ >= op_ctx.total_bytes_) {
@@ -768,15 +762,10 @@ P2PProxy::IssueResult P2PProxy::tryIssueSendTask(SendOpContext& op_ctx,
         return IssueResult::kNoCredit;
     }
 
-    // Step 2 -- Stale packet: the slot carries data from a previous epoch
-    // (before a Reset).  Clear it so the fresh credit can land safely.
-    const uint32_t curr_epoch =
-        peer_epoch_[op_ctx.peer_rank_].load(std::memory_order_acquire);
-    if (slot_epoch != curr_epoch) {
-        LOG(WARNING) << "[P2PProxy][Send] tryIssueSendTask peer="
-                     << op_ctx.peer_rank_ << " STALE_EPOCH seq=" << seq
-                     << " slot.epoch=" << slot_epoch
-                     << " curr_epoch=" << curr_epoch;
+    // Step 2 -- Discard credits older than the group epoch observed at reset,
+    // since reset reuses sequence numbers. Later view updates leave this
+    // bound unchanged so that credits for ongoing ops remain valid.
+    if (slot_epoch < lane.minimum_credit_epoch_) {
         slot.reset();
         return IssueResult::kIssued;
     }
@@ -786,6 +775,15 @@ P2PProxy::IssueResult P2PProxy::tryIssueSendTask(SendOpContext& op_ctx,
         return IssueResult::kNoCredit;
     }
 
+    // Step 4 -- All chunks in this op must use the first credit's epoch.
+    // The sender and receiver may enqueue under different group views.
+    if (op_ctx.credit_epoch_ && *op_ctx.credit_epoch_ != slot_epoch) {
+        LOG(ERROR) << "P2P credit epoch changed within a send op, peer="
+                   << op_ctx.peer_rank_ << " op_epoch=" << *op_ctx.credit_epoch_
+                   << " credit_epoch=" << slot_epoch;
+        return IssueResult::kFailed;
+    }
+
     void* staging_addr = send_pool_->acquire();
     if (staging_addr == nullptr) {
         return IssueResult::kNoCredit;
@@ -798,7 +796,8 @@ P2PProxy::IssueResult P2PProxy::tryIssueSendTask(SendOpContext& op_ctx,
               "P2P send got invalid chunk_len in credit slot.");
 
     op_ctx.tasks_.emplace_back(op_ctx.bytes_staged_, chunk_len, staging_addr,
-                               recv_addr, seq, slot_epoch);
+                               recv_addr, seq);
+    op_ctx.credit_epoch_ = slot_epoch;
     auto& task = op_ctx.tasks_.back();
 
     slot.reset();
@@ -939,7 +938,8 @@ bool P2PProxy::stepSendAck(SendOpContext& op_ctx, SendTransferTask& task) {
     if (!task.ack_batch_id_.has_value()) {
         auto* ack_staging_buf =
             getLocalAckStagingBuf(op_ctx.peer_rank_, task.sequence_);
-        ack_staging_buf->publish(task.epoch_, task.sequence_, task.chunk_len_);
+        ack_staging_buf->publish(*op_ctx.credit_epoch_, task.sequence_,
+                                 task.chunk_len_);
 
         const BatchID batch_id = engine_->allocateBatchID(1);
         engine_->submitTransfer(
@@ -1055,7 +1055,7 @@ bool P2PProxy::stepSend() {
             did_work |= issue == IssueResult::kIssued;
         } while (issue == IssueResult::kIssued);
 
-        if (issue == IssueResult::kTimeout) {
+        if (issue == IssueResult::kFailed) {
             handleFailedSendOp(op_ctx);
             lane.active_send_op_.reset();
             did_work = true;
@@ -1123,17 +1123,14 @@ bool P2PProxy::pollRecvAckSlot(RecvOpContext& op_ctx, RecvPeerLane& lane,
         return false;
     }
 
-    const uint32_t curr_epoch =
-        peer_epoch_[op_ctx.peer_rank_].load(std::memory_order_acquire);
-
-    // Step 2 -- Stale packet: data from a previous epoch (before Reset).
-    // Clear the slot so the fresh ack can land safely.
-    if (slot_epoch != curr_epoch) {
+    // Step 2 -- Match the ACK against this op's credit epoch. The group view
+    // may have advanced since the credits were issued.
+    if (slot_epoch != op_ctx.credit_epoch_) {
         LOG(WARNING) << "[P2PProxy][Recv] pollRecvAckSlot peer="
                      << op_ctx.peer_rank_
                      << " front-seq=" << head_task.sequence_
                      << " EPOCH_MISMATCH slot.epoch=" << slot_epoch
-                     << " curr_epoch=" << curr_epoch;
+                     << " credit_epoch=" << op_ctx.credit_epoch_;
         slot.reset();
         return true;
     }
diff --git a/mooncake-pg/tests/test_pg_collectives.py b/mooncake-pg/tests/test_pg_collectives.py
index f0804e912c..f0231a7384 100644
--- a/mooncake-pg/tests/test_pg_collectives.py
+++ b/mooncake-pg/tests/test_pg_collectives.py
@@ -2,6 +2,7 @@
 
 import torch
 import torch.distributed as dist
+import torch.multiprocessing as mp
 
 from pg_test_utils import (
     MooncakePGCPUBackendTestCase,
@@ -45,7 +46,9 @@ def _collective_payload(
         return {"value": int(tensor.cpu().item())}
 
     if case_name == "broadcast":
-        tensor = torch.tensor([111 if rank == 0 else -1], dtype=torch.int32, device=device)
+        tensor = torch.tensor(
+            [111 if rank == 0 else -1], dtype=torch.int32, device=device
+        )
         dist.broadcast(tensor, src=0)
         return {"value": int(tensor.cpu().item())}
 
@@ -72,7 +75,9 @@ def _collective_payload(
         if hasattr(dist, "reduce_scatter_tensor"):
             dist.reduce_scatter_tensor(output, input_buf, op=dist.ReduceOp.SUM)
         else:
-            dist.reduce_scatter(output, list(input_buf.chunk(world_size)), op=dist.ReduceOp.SUM)
+            dist.reduce_scatter(
+                output, list(input_buf.chunk(world_size)), op=dist.ReduceOp.SUM
+            )
         return {"value": output.cpu().tolist()}
 
     if case_name == "barrier":
@@ -126,9 +131,47 @@ def _collective_worker(
     ctx.record_result(payload)
 
 
+def _async_ops_on_independent_streams_worker(
+    ctx: MooncakePGWorkerContext,
+    allow_rank_one_to_start,
+) -> None:
+    device = ctx.init_group()
+    stream_a = torch.cuda.Stream(device=device)
+    stream_b = torch.cuda.Stream(device=device)
+
+    rank_zero_submitted_both = True
+    if ctx.rank == 1:
+        rank_zero_submitted_both = allow_rank_one_to_start.wait(timeout=5.0)
+
+    with torch.cuda.stream(stream_a):
+        tensor_a = torch.tensor([ctx.rank + 1], dtype=torch.int32, device=device)
+        work_a = dist.all_reduce(tensor_a, op=dist.ReduceOp.SUM, async_op=True)
+    with torch.cuda.stream(stream_b):
+        tensor_b = torch.tensor([(ctx.rank + 1) * 10], dtype=torch.int32, device=device)
+        work_b = dist.all_reduce(tensor_b, op=dist.ReduceOp.SUM, async_op=True)
+
+    if ctx.rank == 0:
+        # Rank 1 does not submit either operation until both calls on rank 0
+        # return.
+        allow_rank_one_to_start.set()
+
+    work_a.wait()
+    work_b.wait()
+    stream_a.synchronize()
+    stream_b.synchronize()
+    ctx.record_result(
+        {
+            "rank_zero_submitted_both": rank_zero_submitted_both,
+            "values": [int(tensor_a.cpu().item()), int(tensor_b.cpu().item())],
+        }
+    )
+
+
 class _CollectiveTestMixin:
     def test_world_init_without_pg_options(self) -> None:
-        rows = self.spawn_backend_and_collect(_collective_worker, "world_init_without_pg_options")
+        rows = self.spawn_backend_and_collect(
+            _collective_worker, "world_init_without_pg_options"
+        )
         self.assert_all_ok(rows)
 
         expected = sum(range(1, self.world_size + 1))
@@ -156,9 +199,11 @@ def test_allreduce_max(self) -> None:
             self.assertEqual(row["value"], expected)
 
     def test_allreduce_product(self) -> None:
-        rows = self.spawn_backend_and_collect(_collective_worker, "allreduce", "product")
+        rows = self.spawn_backend_and_collect(
+            _collective_worker, "allreduce", "product"
+        )
         self.assert_all_ok(rows)
-        expected = 2 ** self.world_size
+        expected = 2**self.world_size
         for row in rows:
             self.assertEqual(row["value"], expected)
 
@@ -169,7 +214,9 @@ def test_broadcast(self) -> None:
             self.assertEqual(row["value"], 111)
 
     def test_all_gather_into_tensor(self) -> None:
-        rows = self.spawn_backend_and_collect(_collective_worker, "all_gather_into_tensor")
+        rows = self.spawn_backend_and_collect(
+            _collective_worker, "all_gather_into_tensor"
+        )
         self.assert_all_ok(rows)
         expected = list(range(self.world_size))
         for row in rows:
@@ -187,7 +234,9 @@ def test_reduce_scatter_sum(self) -> None:
         self.assert_all_ok(rows)
         for row in rows:
             rank = row["rank"]
-            expected = self.world_size * (self.world_size * (self.world_size - 1) // 2 + rank)
+            expected = self.world_size * (
+                self.world_size * (self.world_size - 1) // 2 + rank
+            )
             self.assertEqual(row["value"], [expected])
 
     def test_barrier(self) -> None:
@@ -222,11 +271,32 @@ class TestMooncakePGCollectivesCPU(_CollectiveTestMixin, MooncakePGCPUBackendTes
     world_size = 4
 
 
-class TestMooncakePGCollectivesCUDA(_CollectiveTestMixin, MooncakePGCUDABackendTestCase):
+class TestMooncakePGCollectivesCUDA(
+    _CollectiveTestMixin, MooncakePGCUDABackendTestCase
+):
     world_size = 2
 
+    def test_async_ops_on_independent_streams(self) -> None:
+        spawn_ctx = mp.get_context("spawn")
+        allow_rank_one_to_start = spawn_ctx.Event()
+        rows = self.spawn_backend_and_collect(
+            _async_ops_on_independent_streams_worker,
+            allow_rank_one_to_start,
+        )
+        self.assert_all_ok(rows)
+        for row in rows:
+            self.assertEqual(row["values"], [3, 30])
+
+        rank_one = next(row for row in rows if row["rank"] == 1)
+        self.assertTrue(
+            rank_one["rank_zero_submitted_both"],
+            "rank 0 blocked before submitting both async operations",
+        )
+
 
-class TestMooncakePGCollectivesMUSA(_CollectiveTestMixin, MooncakePGMUSABackendTestCase):
+class TestMooncakePGCollectivesMUSA(
+    _CollectiveTestMixin, MooncakePGMUSABackendTestCase
+):
     world_size = 2
 
 
diff --git a/mooncake-pg/tests/test_pg_elastic.py b/mooncake-pg/tests/test_pg_elastic.py
index 114bdefc94..320c0f0152 100644
--- a/mooncake-pg/tests/test_pg_elastic.py
+++ b/mooncake-pg/tests/test_pg_elastic.py
@@ -15,6 +15,10 @@
     require_test_device,
     wait_until,
 )
+from transfer_fault_injection import (
+    TransferFault,
+    preload_transfer_fault,
+)
 
 
 BROKEN_RANK = 1
@@ -65,8 +69,9 @@ def _extension_worker(
             description=f"rank {ctx.proc_rank} waiting for joiner ready",
         )
         resp = pg.recover_ranks(backend, join_ranks)
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
 
         # The Coordinator has committed the joiner as active, so the visible
         # rank-space extent now covers the full group.
@@ -77,14 +82,18 @@ def _extension_worker(
         )
 
         # Final collective
-        final_tensor = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
+        final_tensor = torch.tensor(
+            [ctx.proc_rank + 1], dtype=torch.int32, device=device
+        )
         dist.all_reduce(final_tensor, op=dist.ReduceOp.SUM)
 
-        ctx.record_result({
-            "role": "original",
-            "rank": ctx.proc_rank,
-            "baseline": baseline,
-        })
+        ctx.record_result(
+            {
+                "role": "original",
+                "rank": ctx.proc_rank,
+                "baseline": baseline,
+            }
+        )
     else:
         # Extension rank
         if not extend_event.wait(timeout=30.0):
@@ -130,13 +139,17 @@ def _extension_worker(
         )
 
         # Final collective
-        final_tensor = torch.tensor([extension_rank + 1], dtype=torch.int32, device=device)
+        final_tensor = torch.tensor(
+            [extension_rank + 1], dtype=torch.int32, device=device
+        )
         dist.all_reduce(final_tensor, op=dist.ReduceOp.SUM)
 
-        ctx.record_result({
-            "role": "extension",
-            "rank": extension_rank,
-        })
+        ctx.record_result(
+            {
+                "role": "extension",
+                "rank": extension_rank,
+            }
+        )
 
 
 def _extension_p2p_worker(
@@ -170,8 +183,9 @@ def _extension_p2p_worker(
             description=f"rank {ctx.proc_rank} waiting for joiner ready",
         )
         resp = pg.recover_ranks(backend, join_ranks)
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
     else:
         if not extend_event.wait(timeout=30.0):
             raise TimeoutError("timed out waiting for extend_event")
@@ -208,9 +222,7 @@ def _extension_p2p_worker(
 
     numel = 1024
     if ctx.proc_rank == src_rank:
-        send_tensor = torch.full(
-            (numel,), src_rank, dtype=torch.int32, device=device
-        )
+        send_tensor = torch.full((numel,), src_rank, dtype=torch.int32, device=device)
         works = dist.batch_isend_irecv(
             [dist.P2POp(op=dist.isend, tensor=send_tensor, peer=dst_rank)]
         )
@@ -300,8 +312,16 @@ def _extension_worker_with_subgroups(
             backend=ctx.backend_name,
             pg_options=pg.MooncakeBackendOptions(4),
         )
-        a_backend = get_mooncake_backend(group_a, device_type=ctx.device_type) if ctx.proc_rank == 0 else None
-        b_backend = get_mooncake_backend(group_b, device_type=ctx.device_type) if ctx.proc_rank == 1 else None
+        a_backend = (
+            get_mooncake_backend(group_a, device_type=ctx.device_type)
+            if ctx.proc_rank == 0
+            else None
+        )
+        b_backend = (
+            get_mooncake_backend(group_b, device_type=ctx.device_type)
+            if ctx.proc_rank == 1
+            else None
+        )
         c_backend = get_mooncake_backend(group_c, device_type=ctx.device_type)
 
         # Pre-activation: WORLD primary ranks sum to 1+2=3
@@ -327,8 +347,9 @@ def _extension_worker_with_subgroups(
             description=f"rank {ctx.proc_rank} waiting for joiners",
         )
         resp = pg.recover_ranks(world_backend, join_ranks)
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {ctx.proc_rank}: recover_ranks(world) should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {ctx.proc_rank}: recover_ranks(world) should apply, got {resp.status}"
 
         # group_a: rank 0 waits for joiner (local rank 1 = global rank 2)
         if ctx.proc_rank == 0:
@@ -339,8 +360,9 @@ def _extension_worker_with_subgroups(
                 description="rank 0 waiting for group_a joiner",
             )
             resp = pg.recover_ranks(a_backend, [1])
-            assert resp.status == pg.ProposalStatus.Applied, \
-                f"rank 0: recover_ranks(group_a) should apply, got {resp.status}"
+            assert (
+                resp.status == pg.ProposalStatus.Applied
+            ), f"rank 0: recover_ranks(group_a) should apply, got {resp.status}"
 
         # group_b: rank 1 waits for joiner (local rank 1 = global rank 3)
         if ctx.proc_rank == 1:
@@ -351,8 +373,9 @@ def _extension_worker_with_subgroups(
                 description="rank 1 waiting for group_b joiner",
             )
             resp = pg.recover_ranks(b_backend, [1])
-            assert resp.status == pg.ProposalStatus.Applied, \
-                f"rank 1: recover_ranks(group_b) should apply, got {resp.status}"
+            assert (
+                resp.status == pg.ProposalStatus.Applied
+            ), f"rank 1: recover_ranks(group_b) should apply, got {resp.status}"
 
         # group_c: both primaries wait for both joiners (local ranks 2,3)
         wait_until(
@@ -362,8 +385,9 @@ def _extension_worker_with_subgroups(
             description=f"rank {ctx.proc_rank} waiting for group_c joiners",
         )
         resp = pg.recover_ranks(c_backend, [2, 3])
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {ctx.proc_rank}: recover_ranks(group_c) should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {ctx.proc_rank}: recover_ranks(group_c) should apply, got {resp.status}"
 
         # Post-activation: WORLD all 4 ranks → 1+2+3+4=10
         t = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
@@ -376,20 +400,26 @@ def _extension_worker_with_subgroups(
             ta = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
             dist.all_reduce(ta, op=dist.ReduceOp.SUM, group=group_a)
             if int(ta.cpu().item()) != 4:
-                raise AssertionError(f"group_a post: expected 4, got {int(ta.cpu().item())}")
+                raise AssertionError(
+                    f"group_a post: expected 4, got {int(ta.cpu().item())}"
+                )
 
         # group_b: ranks [1,3], values [2,4], sum=6
         if ctx.proc_rank == 1:
             tb = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
             dist.all_reduce(tb, op=dist.ReduceOp.SUM, group=group_b)
             if int(tb.cpu().item()) != 6:
-                raise AssertionError(f"group_b post: expected 6, got {int(tb.cpu().item())}")
+                raise AssertionError(
+                    f"group_b post: expected 6, got {int(tb.cpu().item())}"
+                )
 
         # group_c: all 4 ranks, sum=10
         tc = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
         dist.all_reduce(tc, op=dist.ReduceOp.SUM, group=group_c)
         if int(tc.cpu().item()) != 10:
-            raise AssertionError(f"group_c post: expected 10, got {int(tc.cpu().item())}")
+            raise AssertionError(
+                f"group_c post: expected 10, got {int(tc.cpu().item())}"
+            )
 
         ctx.record_result({"role": "extension_subgroups", "rank": ctx.proc_rank})
     else:
@@ -424,8 +454,16 @@ def _extension_worker_with_subgroups(
             backend=ctx.backend_name,
             pg_options=pg.MooncakeBackendOptions(4, True),
         )
-        a_backend = get_mooncake_backend(group_a, device_type=ctx.device_type) if ctx.proc_rank == 2 else None
-        b_backend = get_mooncake_backend(group_b, device_type=ctx.device_type) if ctx.proc_rank == 3 else None
+        a_backend = (
+            get_mooncake_backend(group_a, device_type=ctx.device_type)
+            if ctx.proc_rank == 2
+            else None
+        )
+        b_backend = (
+            get_mooncake_backend(group_b, device_type=ctx.device_type)
+            if ctx.proc_rank == 3
+            else None
+        )
         c_backend = get_mooncake_backend(group_c, device_type=ctx.device_type)
 
         # Before any join_group call, WORLD collectives are local-only on each
@@ -435,8 +473,7 @@ def _extension_worker_with_subgroups(
         local_value = int(t.cpu().item())
         if local_value != ctx.proc_rank + 1:
             raise AssertionError(
-                f"WORLD local-only: expected {ctx.proc_rank + 1}, "
-                f"got {local_value}"
+                f"WORLD local-only: expected {ctx.proc_rank + 1}, " f"got {local_value}"
             )
 
         # Join groups in same order primaries created them
@@ -458,20 +495,26 @@ def _extension_worker_with_subgroups(
             ta = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
             dist.all_reduce(ta, op=dist.ReduceOp.SUM, group=group_a)
             if int(ta.cpu().item()) != 4:
-                raise AssertionError(f"group_a post: expected 4, got {int(ta.cpu().item())}")
+                raise AssertionError(
+                    f"group_a post: expected 4, got {int(ta.cpu().item())}"
+                )
 
         # group_b: ranks [1,3], sum=6
         if ctx.proc_rank == 3:
             tb = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
             dist.all_reduce(tb, op=dist.ReduceOp.SUM, group=group_b)
             if int(tb.cpu().item()) != 6:
-                raise AssertionError(f"group_b post: expected 6, got {int(tb.cpu().item())}")
+                raise AssertionError(
+                    f"group_b post: expected 6, got {int(tb.cpu().item())}"
+                )
 
         # group_c: all 4 ranks, sum=10
         tc = torch.tensor([ctx.proc_rank + 1], dtype=torch.int32, device=device)
         dist.all_reduce(tc, op=dist.ReduceOp.SUM, group=group_c)
         if int(tc.cpu().item()) != 10:
-            raise AssertionError(f"group_c post: expected 10, got {int(tc.cpu().item())}")
+            raise AssertionError(
+                f"group_c post: expected 10, got {int(tc.cpu().item())}"
+            )
 
         ctx.record_result({"role": "extension_subgroups", "rank": ctx.proc_rank})
 
@@ -566,8 +609,9 @@ def _allgather_reduce_scatter_extension_worker(
             description=f"rank {ctx.proc_rank} waiting for joiner",
         )
         resp = pg.recover_ranks(backend, join_ranks)
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {ctx.proc_rank}: recover_ranks should apply, got {resp.status}"
 
         # Post-activation: all 4 ranks active.
         _run_allgather_reduce_scatter(device, ctx.world_size, ctx.proc_rank)
@@ -598,6 +642,7 @@ def _allgather_reduce_scatter_extension_worker(
 
 def _allgather_reduce_scatter_recovery_worker(
     ctx: MooncakePGWorkerContext,
+    pre_failure_barrier: mp.Barrier,
     broken_exited: mp.Event,
     start_recovery: mp.Event,
 ) -> None:
@@ -615,17 +660,26 @@ def _allgather_reduce_scatter_recovery_worker(
         device = ctx.init_group(rank=logical_rank)
         backend = ctx.get_backend()
 
-        # Pre-failure: all 4 ranks active.
+        # Pre-failure: all 4 ranks active. Wait for every rank's collectives to
+        # return before killing one process so the injected failure cannot race
+        # with completion of the healthy round.
         _run_allgather_reduce_scatter(device, ctx.world_size, logical_rank)
+        ctx.synchronize()
+        pre_failure_barrier.wait(timeout=30.0)
 
         if logical_rank == broken_rank:
             ctx.record_result({"role": "broken"})
             broken_exited.set()
             os._exit(0)
 
-        # Survivors: 3 active ranks, max_group_size=4 → overflow path.
+        # First use the basic collective path to detect and deactivate the
+        # departed rank. The assertions below target the three-rank buffer
+        # layout, not failure detection inside all-gather/reduce-scatter.
         broken_exited.wait()
+        probe = torch.tensor([logical_rank], dtype=torch.int32, device=device)
+        dist.all_reduce(probe, op=dist.ReduceOp.SUM)
 
+        # Survivors: 3 active ranks, max_group_size=4 → overflow path.
         _run_allgather_reduce_scatter(device, ctx.world_size - 1, logical_rank)
 
         if logical_rank == 0:
@@ -638,8 +692,9 @@ def _allgather_reduce_scatter_recovery_worker(
             description=f"rank {logical_rank} waiting for replacement",
         )
         resp = pg.recover_ranks(backend, [broken_rank])
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
 
         # Post-recovery: all 4 ranks active again.
         _run_allgather_reduce_scatter(device, ctx.world_size, logical_rank)
@@ -711,13 +766,14 @@ def _replacement_recovery_worker(
                 # view used by that collective.
                 ctx.synchronize()
                 resp = pg.deactivate_ranks(backend, [logical_rank])
-                assert resp.status == pg.ProposalStatus.Applied, \
-                    "graceful self-deactivation should apply, " \
+                assert resp.status == pg.ProposalStatus.Applied, (
+                    "graceful self-deactivation should apply, "
                     f"got {resp.status}: {resp.reject_reason}"
+                )
 
                 dist.destroy_process_group()
                 ctx.record_result({"role": "gracefully_removed"})
-                # Do not set broken_exited here. The parent sets the event only 
+                # Do not set broken_exited here. The parent sets the event only
                 # after it observes that this process has exited.
                 return
 
@@ -748,8 +804,9 @@ def _replacement_recovery_worker(
 
         # All ranks call recover_ranks to include replacement
         resp = pg.recover_ranks(backend, [BROKEN_RANK])
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
 
         # Final collective with all 4 ranks
         tensor = torch.tensor([logical_rank], dtype=torch.int32, device=device)
@@ -775,6 +832,236 @@ def _replacement_recovery_worker(
         ctx.record_result({"role": "replacement"})
 
 
+def _run_p2p_ping_pong(
+    ctx: MooncakePGWorkerContext,
+    device: torch.device,
+    logical_rank: int,
+) -> None:
+    """Exchange one message in each direction between two logical ranks."""
+    if ctx.world_size != 2:
+        raise AssertionError("recovery P2P test expects exactly two ranks")
+
+    peer = 1 - logical_rank
+    send_tensor = torch.tensor([logical_rank], dtype=torch.int64, device=device)
+    recv_tensor = torch.empty_like(send_tensor)
+    works = dist.batch_isend_irecv(
+        [
+            dist.P2POp(op=dist.isend, tensor=send_tensor, peer=peer),
+            dist.P2POp(op=dist.irecv, tensor=recv_tensor, peer=peer),
+        ]
+    )
+    for work in works:
+        work.wait()
+
+    if not all(pg.get_local_success(work) for work in works):
+        raise AssertionError(f"rank {logical_rank}: P2P with rank {peer} failed")
+    received = int(recv_tensor.cpu().item())
+    if received != peer:
+        raise AssertionError(
+            f"rank {logical_rank}: expected {peer}, received {received}"
+        )
+
+
+def _recovery_p2p_worker(
+    ctx: MooncakePGWorkerContext,
+    broken_exited: mp.Event,
+    start_recovery: mp.Event,
+    graceful_group_destroy: bool,
+) -> None:
+    """Replace logical rank 1, then repeat its P2P exchange with rank 0."""
+    logical_rank = ctx.rank if ctx.proc_rank < ctx.world_size else BROKEN_RANK
+
+    if ctx.proc_rank < ctx.world_size:
+        device = ctx.init_group(rank=logical_rank)
+        backend = ctx.get_backend()
+        _run_p2p_ping_pong(ctx, device, logical_rank)
+
+        if logical_rank == BROKEN_RANK:
+            if graceful_group_destroy:
+                resp = pg.deactivate_ranks(backend, [logical_rank])
+                assert resp.status == pg.ProposalStatus.Applied, (
+                    "graceful self-deactivation should apply, "
+                    f"got {resp.status}: {resp.reject_reason}"
+                )
+
+                dist.destroy_process_group()
+                ctx.record_result({"role": "gracefully_removed"})
+                return
+
+            ctx.record_result({"role": "broken"})
+            broken_exited.set()
+            os._exit(0)
+
+        if not broken_exited.wait(timeout=120.0):
+            raise TimeoutError("timed out waiting for departed rank")
+
+        if not graceful_group_destroy:
+            probe = torch.tensor([logical_rank], device=device)
+            work = dist.isend(probe, dst=BROKEN_RANK)
+            work.wait()
+            if pg.get_local_success(work):
+                raise AssertionError(
+                    "P2P probe to the departed rank unexpectedly succeeded"
+                )
+
+        active_ranks = pg.get_active_ranks(backend).cpu().tolist()
+        assert active_ranks == [1, 0], (
+            "new group view should be applied before p2p completes, "
+            f"got active_ranks={active_ranks}"
+        )
+
+        start_recovery.set()
+
+        wait_until(
+            lambda: pg.get_peer_state(backend, [BROKEN_RANK])[0],
+            timeout_s=30.0,
+            poll_interval_s=0.05,
+            description=f"rank {logical_rank} waiting for replacement",
+        )
+        resp = pg.recover_ranks(backend, [BROKEN_RANK])
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
+
+        role = "survivor"
+    else:
+        if not start_recovery.wait(timeout=60.0):
+            raise TimeoutError("timed out waiting to start replacement")
+
+        device = ctx.init_group(rank=logical_rank, is_extension=True)
+        backend = ctx.get_backend()
+        pg.join_group(backend)
+        role = "replacement"
+
+    _run_p2p_ping_pong(ctx, device, logical_rank)
+    ctx.record_result({"role": role})
+
+
+def _run_rejoin_operation(
+    ctx: MooncakePGWorkerContext,
+    device: torch.device,
+    operation: str,
+    *,
+    verify: bool,
+):
+    if operation == "collective":
+        tensor = torch.tensor([ctx.rank + 1], dtype=torch.int32, device=device)
+        works = [dist.all_reduce(tensor, op=dist.ReduceOp.SUM, async_op=True)]
+        for work in works:
+            work.wait()
+
+        if verify:
+            if not pg.get_local_success(works[0]):
+                raise AssertionError("collective failed locally")
+            expected = ctx.world_size * (ctx.world_size + 1) // 2
+            actual = int(tensor.cpu().item())
+            if actual != expected:
+                raise AssertionError(f"collective expected {expected}, got {actual}")
+        return works
+
+    if operation == "p2p":
+        peer = 1 - ctx.rank
+        send_tensor = torch.tensor([ctx.rank], dtype=torch.int64, device=device)
+        recv_tensor = torch.empty_like(send_tensor)
+        works = dist.batch_isend_irecv(
+            [
+                dist.P2POp(op=dist.isend, tensor=send_tensor, peer=peer),
+                dist.P2POp(op=dist.irecv, tensor=recv_tensor, peer=peer),
+            ]
+        )
+        for work in works:
+            work.wait()
+
+        if verify:
+            if not all(pg.get_local_success(work) for work in works):
+                raise AssertionError(f"P2P with rank {peer} failed locally")
+            actual = int(recv_tensor.cpu().item())
+            if actual != peer:
+                raise AssertionError(f"expected {peer}, received {actual}")
+        return works
+
+    raise ValueError(f"unsupported in-place rejoin operation: {operation}")
+
+
+def _run_fault_round(
+    ctx: MooncakePGWorkerContext,
+    device: torch.device,
+    backend,
+    operation: str,
+    fault_library: str,
+    fault_started: mp.Event,
+) -> None:
+    fault = TransferFault(fault_library, local_rank=ctx.rank)
+    with fault.failing_link(BROKEN_RANK, 0):
+        if ctx.rank != BROKEN_RANK:
+            if not fault_started.wait(timeout=30.0):
+                raise TimeoutError("timed out waiting for fault injection")
+            _run_rejoin_operation(ctx, device, operation, verify=False)
+            return
+
+        fault_started.set()
+        works = _run_rejoin_operation(ctx, device, operation, verify=False)
+
+        if all(pg.get_local_success(work) for work in works):
+            raise AssertionError(f"injected {operation} unexpectedly succeeded")
+        if fault.injected_count == 0:
+            raise AssertionError("transfer fault was not injected")
+
+        active_ranks = pg.get_active_ranks(backend).cpu().tolist()
+        assert active_ranks == [1, 0], (
+            "auto sync should make the transiently failed rank inactive "
+            f"before {operation} completion, got {active_ranks}"
+        )
+
+
+def _inplace_rejoin_worker(
+    ctx: MooncakePGWorkerContext,
+    operation: str,
+    fault_library: str,
+    fault_started: mp.Event,
+) -> None:
+    """Temporarily fail rank 1's data plane, then rejoin the same process."""
+    if ctx.world_size != 2:
+        raise AssertionError("in-place rejoin test expects exactly two ranks")
+
+    device = ctx.init_group()
+    backend = ctx.get_backend()
+
+    # 1. Establish a healthy baseline on the selected data path.
+    _run_rejoin_operation(ctx, device, operation, verify=True)
+    epoch_before_failure = pg.get_current_epoch(backend)
+
+    # 2. Fail rank 1's data plane. Auto sync must make it inactive.
+    _run_fault_round(ctx, device, backend, operation, fault_library, fault_started)
+
+    # 3. At an application-selected safe point, the failed rank declares
+    # itself ready to rejoin.
+    if ctx.rank == BROKEN_RANK:
+        pg.join_group(backend)
+    else:
+        wait_until(
+            lambda: pg.get_current_epoch(backend) > epoch_before_failure,
+            timeout_s=60.0,
+            poll_interval_s=0.05,
+            description="waiting for the post-failure group view",
+        )
+        wait_until(
+            lambda: pg.get_peer_state(backend, [BROKEN_RANK])[0],
+            timeout_s=30.0,
+            poll_interval_s=0.05,
+            description="waiting for the original rank to become activatable",
+        )
+        response = pg.activate_ranks(backend, [BROKEN_RANK])
+        assert response.status == pg.ProposalStatus.Applied, (
+            "in-place activation should apply, "
+            f"got {response.status}: {response.reject_reason}"
+        )
+
+    # 4. Verify the same communicator can use the same data path again.
+    _run_rejoin_operation(ctx, device, operation, verify=True)
+    ctx.record_result({"operation": operation})
+
+
 def _manual_deactivate_recovery_worker(
     ctx: MooncakePGWorkerContext,
     broken_exited: mp.Event,
@@ -803,8 +1090,9 @@ def _manual_deactivate_recovery_worker(
         work = dist.all_reduce(tensor, op=dist.ReduceOp.SUM, async_op=True)
         work.wait()
         assert int(tensor.cpu().item()) == expected_all
-        assert pg.get_local_success(work), \
-            f"rank {ctx.rank}: round 1 should succeed locally"
+        assert pg.get_local_success(
+            work
+        ), f"rank {ctx.rank}: round 1 should succeed locally"
 
         failed_ranks_hint = pg.get_failed_ranks_hint(work)
         assert failed_ranks_hint.tolist() == [0] * ctx.world_size
@@ -826,8 +1114,9 @@ def _manual_deactivate_recovery_worker(
         work = dist.all_reduce(tensor, op=dist.ReduceOp.SUM, async_op=True)
         work.wait()
         assert int(tensor.cpu().item()) == expected_reduced
-        assert not pg.get_local_success(work), \
-            f"rank {ctx.rank}: round 2 should detect broken rank"
+        assert not pg.get_local_success(
+            work
+        ), f"rank {ctx.rank}: round 2 should detect broken rank"
 
         failed_ranks_hint = pg.get_failed_ranks_hint(work)
         expected_failed_ranks_hint = [0] * ctx.world_size
@@ -846,8 +1135,9 @@ def _manual_deactivate_recovery_worker(
             pg.SyncAfterFailureStatus.Reconciled,
             pg.SyncAfterFailureStatus.NoPending,
         ), f"rank {logical_rank}: sync_after_failure failed: {sync_resp.reject_reason}"
-        assert not pg.get_peer_state(backend, [BROKEN_RANK])[0], \
-            f"rank {logical_rank}: failed rank remained locally activatable after sync"
+        assert not pg.get_peer_state(backend, [BROKEN_RANK])[
+            0
+        ], f"rank {logical_rank}: failed rank remained locally activatable after sync"
 
         # Survivors deactivate the dead rank before issuing new collectives.
         resp = pg.deactivate_ranks(backend, [BROKEN_RANK])
@@ -868,8 +1158,9 @@ def _manual_deactivate_recovery_worker(
         work = dist.all_reduce(tensor, op=dist.ReduceOp.SUM, async_op=True)
         work.wait()
         assert int(tensor.cpu().item()) == expected_reduced
-        assert pg.get_local_success(work), \
-            f"rank {ctx.rank}: round 3 should succeed after manual deactivate"
+        assert pg.get_local_success(
+            work
+        ), f"rank {ctx.rank}: round 3 should succeed after manual deactivate"
 
         if logical_rank == 0:
             start_recovery.set()
@@ -882,12 +1173,11 @@ def _manual_deactivate_recovery_worker(
         )
 
         resp = pg.recover_ranks(backend, [BROKEN_RANK])
-        assert resp.status == pg.ProposalStatus.Applied, \
-            f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
+        assert (
+            resp.status == pg.ProposalStatus.Applied
+        ), f"rank {logical_rank}: recover_ranks should apply, got {resp.status}"
 
-        tensor = torch.tensor(
-            [logical_rank + 1], dtype=torch.int32, device=device
-        )
+        tensor = torch.tensor([logical_rank + 1], dtype=torch.int32, device=device)
         dist.all_reduce(tensor, op=dist.ReduceOp.SUM)
 
         assert int(tensor.cpu().item()) == expected_all
@@ -906,9 +1196,7 @@ def _manual_deactivate_recovery_worker(
         backend = ctx.get_backend()
         pg.join_group(backend)
 
-        tensor = torch.tensor(
-            [logical_rank + 1], dtype=torch.int32, device=device
-        )
+        tensor = torch.tensor([logical_rank + 1], dtype=torch.int32, device=device)
         dist.all_reduce(tensor, op=dist.ReduceOp.SUM)
         ctx.record_result({"role": "replacement"})
 
@@ -964,7 +1252,7 @@ def test_recovery(self) -> None:
         self.assertGreaterEqual(len(broken_rows), 1)
 
     def test_recovery_after_graceful_group_destroy(self) -> None:
-        """A rank can destroy its group normally and later be replaced. """
+        """A rank can destroy its group normally and later be replaced."""
         spawn_ctx = mp.get_context("spawn")
         removed_process_exited = spawn_ctx.Event()
         start_recovery = spawn_ctx.Event()
@@ -986,14 +1274,65 @@ def test_recovery_after_graceful_group_destroy(self) -> None:
 
         survivor_rows = [r for r in rows if r.get("role") == "survivor"]
         replacement_rows = [r for r in rows if r.get("role") == "replacement"]
-        removed_rows = [
-            r for r in rows if r.get("role") == "gracefully_removed"
-        ]
+        removed_rows = [r for r in rows if r.get("role") == "gracefully_removed"]
 
         self.assertEqual(len(survivor_rows), self.world_size - 1)
         self.assertEqual(len(replacement_rows), 1)
         self.assertEqual(len(removed_rows), 1)
 
+    def _run_recovery_p2p(self, graceful_group_destroy: bool) -> None:
+        recovery_world_size = 2
+        spawn_ctx = mp.get_context("spawn")
+        broken_exited = spawn_ctx.Event()
+        start_recovery = spawn_ctx.Event()
+
+        rows = self.spawn_backend_and_collect(
+            _recovery_p2p_worker,
+            broken_exited,
+            start_recovery,
+            graceful_group_destroy,
+            world_size=recovery_world_size,
+            nprocs=recovery_world_size + 1,
+            timeout_s=75.0,
+            process_exit_events=(
+                {BROKEN_RANK: broken_exited} if graceful_group_destroy else None
+            ),
+        )
+
+        self.assert_all_ok(rows)
+
+    def test_recovery_p2p(self) -> None:
+        """P2P remains usable after an abruptly failed rank is replaced."""
+        self._run_recovery_p2p(graceful_group_destroy=False)
+
+    def test_recovery_p2p_after_graceful_group_destroy(self) -> None:
+        """P2P remains usable after a gracefully removed rank is replaced."""
+        self._run_recovery_p2p(graceful_group_destroy=True)
+
+    def _run_inplace_rejoin(self, operation: str) -> None:
+        spawn_ctx = mp.get_context("spawn")
+
+        with preload_transfer_fault() as fault_library:
+            fault_started = spawn_ctx.Event()
+            rows = self.spawn_backend_and_collect(
+                _inplace_rejoin_worker,
+                operation,
+                str(fault_library),
+                fault_started,
+                world_size=2,
+                nprocs=2,
+                timeout_s=75.0,
+            )
+            self.assert_all_ok(rows)
+
+    def test_inplace_rejoin_collective(self) -> None:
+        """Collectives recover when the same live process rejoins."""
+        self._run_inplace_rejoin("collective")
+
+    def test_inplace_rejoin_p2p(self) -> None:
+        """P2P recovers when the same live process rejoins."""
+        self._run_inplace_rejoin("p2p")
+
     def test_extension(self) -> None:
         """Test extension mode allows new ranks to join existing group."""
         spawn_ctx = mp.get_context("spawn")
@@ -1102,11 +1441,13 @@ def test_allgather_reduce_scatter_recovery(self) -> None:
         and max_group_size=4, so the buggy code would access slot 3 of a size-3 buffer.
         """
         spawn_ctx = mp.get_context("spawn")
+        pre_failure_barrier = spawn_ctx.Barrier(self.world_size)
         broken_exited = spawn_ctx.Event()
         start_recovery = spawn_ctx.Event()
 
         rows = self.spawn_backend_and_collect(
             _allgather_reduce_scatter_recovery_worker,
+            pre_failure_barrier,
             broken_exited,
             start_recovery,
             nprocs=self.world_size + 1,
@@ -1156,15 +1497,11 @@ def test_manual_evict_recovery(self) -> None:
         self.assertGreaterEqual(len(broken_rows), 1)
 
 
-class TestMooncakePGElasticCPU(
-    _ElasticMixin, MooncakePGCPUBackendTestCase
-):
+class TestMooncakePGElasticCPU(_ElasticMixin, MooncakePGCPUBackendTestCase):
     pass
 
 
-class TestMooncakePGElasticCUDA(
-    _ElasticMixin, MooncakePGCUDABackendTestCase
-):
+class TestMooncakePGElasticCUDA(_ElasticMixin, MooncakePGCUDABackendTestCase):
     @classmethod
     def configure_for_cuda_device_count(cls, device_count: int) -> None:
         if device_count < 2:
diff --git a/mooncake-pg/tests/test_pg_init_functional.py b/mooncake-pg/tests/test_pg_init_functional.py
index bd096ce589..1fbc369fe5 100644
--- a/mooncake-pg/tests/test_pg_init_functional.py
+++ b/mooncake-pg/tests/test_pg_init_functional.py
@@ -2,6 +2,7 @@
 
 import torch
 import torch.distributed as dist
+import torch.multiprocessing as mp
 
 from pg_test_utils import (
     MooncakePGCPUBackendTestCase,
@@ -14,8 +15,10 @@ def _basic_init_worker(ctx: MooncakePGWorkerContext) -> None:
     """Test basic init works and rank/world_size are correct."""
     device = ctx.init_group()
     # Verify rank and world_size are accessible
-    assert dist.get_rank() == ctx.rank, f"rank mismatch: {dist.get_rank()} != {ctx.rank}"
-    assert dist.get_world_size() == ctx.world_size, f"world_size mismatch"
+    assert (
+        dist.get_rank() == ctx.rank
+    ), f"rank mismatch: {dist.get_rank()} != {ctx.rank}"
+    assert dist.get_world_size() == ctx.world_size, "world_size mismatch"
     # Simple collective to verify group works
     tensor = torch.tensor([ctx.rank + 1], dtype=torch.int32, device=device)
     dist.all_reduce(tensor, op=dist.ReduceOp.SUM)
@@ -64,10 +67,12 @@ def _subgroup_create_destroy_worker(ctx: MooncakePGWorkerContext) -> None:
         world_tensor = torch.tensor([1], dtype=torch.int32, device=device)
         dist.all_reduce(world_tensor, op=dist.ReduceOp.SUM)
 
-        ctx.record_result({
-            "subgroup_sum": subgroup_sum,
-            "world_sum": int(world_tensor.cpu().item()),
-        })
+        ctx.record_result(
+            {
+                "subgroup_sum": subgroup_sum,
+                "world_sum": int(world_tensor.cpu().item()),
+            }
+        )
     finally:
         for g in (even_group, odd_group):
             if g is not None:
@@ -77,7 +82,7 @@ def _subgroup_create_destroy_worker(ctx: MooncakePGWorkerContext) -> None:
                     pass
 
 
-def _destroy_and_reinit_worker(ctx: MooncakePGWorkerContext) -> None:
+def _destroy_and_reinit_worker(ctx: MooncakePGWorkerContext, destroyed) -> None:
     """Test destroy and re-init process group."""
     # First init
     device = ctx.init_group()
@@ -86,10 +91,9 @@ def _destroy_and_reinit_worker(ctx: MooncakePGWorkerContext) -> None:
     sum1 = int(tensor1.cpu().item())
 
     # Destroy WORLD group
-    try:
-        dist.destroy_process_group(dist.group.WORLD)
-    except Exception:
-        pass
+    dist.destroy_process_group(dist.group.WORLD)
+    # Reinitialization should start after every old communicator unregisters.
+    destroyed.wait(timeout=10)
 
     # Re-init
     device = ctx.init_group()
@@ -151,7 +155,8 @@ def test_subgroup_create_destroy(self) -> None:
 
     def test_destroy_and_reinit(self) -> None:
         """Test destroy and re-init process group."""
-        rows = self.spawn_backend_and_collect(_destroy_and_reinit_worker)
+        destroyed = mp.get_context("spawn").Barrier(self.world_size)
+        rows = self.spawn_backend_and_collect(_destroy_and_reinit_worker, destroyed)
         self.assert_all_ok(rows)
 
         expected = sum(range(1, self.world_size + 1))
@@ -160,11 +165,15 @@ def test_destroy_and_reinit(self) -> None:
             self.assertEqual(row["sum2"], expected)
 
 
-class TestMooncakePGInitFunctionalCPU(_InitFunctionalMixin, MooncakePGCPUBackendTestCase):
+class TestMooncakePGInitFunctionalCPU(
+    _InitFunctionalMixin, MooncakePGCPUBackendTestCase
+):
     world_size = 4
 
 
-class TestMooncakePGInitFunctionalCUDA(_InitFunctionalMixin, MooncakePGCUDABackendTestCase):
+class TestMooncakePGInitFunctionalCUDA(
+    _InitFunctionalMixin, MooncakePGCUDABackendTestCase
+):
     world_size = 4
 
     @classmethod
diff --git a/mooncake-pg/tests/test_pg_p2p.py b/mooncake-pg/tests/test_pg_p2p.py
index 4fac899dd2..f8b151ca87 100644
--- a/mooncake-pg/tests/test_pg_p2p.py
+++ b/mooncake-pg/tests/test_pg_p2p.py
@@ -151,6 +151,7 @@ def p2p_all_to_all(ctx, device):
         return dist.batch_isend_irecv(ops)
 
     device = ctx.init_group()
+    backend = ctx.get_backend()
 
     # Round 1: all healthy
     works = p2p_all_to_all(ctx, device)
@@ -191,6 +192,14 @@ def p2p_all_to_all(ctx, device):
             assert not pg.get_local_success(w), \
                 f"rank {ctx.rank} round 2: P2P with broken peer should fail locally"
 
+    expected_active_ranks = [1] * ctx.world_size
+    expected_active_ranks[BROKEN_RANK] = 0
+    active_ranks = pg.get_active_ranks(backend).cpu().tolist()
+    assert active_ranks == expected_active_ranks, (
+        "auto_sync_on_failure should apply the group view before "
+        f"failed P2P completion, got active_ranks={active_ranks}"
+    )
+
     ctx.record_result({"role": "survivor"})
 
 
diff --git a/mooncake-pg/tests/transfer_fault_injection.py b/mooncake-pg/tests/transfer_fault_injection.py
new file mode 100644
index 0000000000..907c0e30ab
--- /dev/null
+++ b/mooncake-pg/tests/transfer_fault_injection.py
@@ -0,0 +1,231 @@
+"""Test-only transfer fault injection for Mooncake PG workers."""
+
+import ctypes
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from pathlib import Path
+
+from pg_test_utils import temporary_env
+
+RankPair = tuple[int, int]
+
+
+def _build_preload(output: Path) -> None:
+    source = Path(__file__).with_name("transfer_fault_preload.cpp")
+    repository_root = Path(__file__).resolve().parents[2]
+    transfer_engine_include = (
+        repository_root / "mooncake-transfer-engine" / "include"
+    )
+    process_group_include = repository_root / "mooncake-pg" / "include"
+    command = [
+        os.environ.get("CXX", "c++"),
+        "-std=c++20",
+        "-O2",
+        "-shared",
+        "-fPIC",
+        f"-I{transfer_engine_include}",
+        f"-I{process_group_include}",
+        str(source),
+        "-ldl",
+        "-o",
+        str(output),
+    ]
+    try:
+        subprocess.run(command, check=True, capture_output=True, text=True)
+    except OSError as error:
+        raise unittest.SkipTest(
+            f"transfer fault injection cannot invoke the compiler: {error}"
+        ) from error
+    except subprocess.CalledProcessError as error:
+        reason = (error.stderr or "").strip()
+        raise unittest.SkipTest(
+            "transfer fault injection cannot build its preload shim: "
+            f"{reason or error}"
+        ) from error
+
+
+def _verify_preload(library: Path, preload: str) -> None:
+    """Verify LD_PRELOAD and symbol resolution in a fresh process."""
+    probe = """
+import ctypes
+import sys
+
+from mooncake import pg
+
+library = ctypes.CDLL(sys.argv[1])
+available = library.mooncakePgTestFaultAvailable
+available.argtypes = []
+available.restype = ctypes.c_int
+if not available():
+    print("required fault-injection symbols not found", file=sys.stderr)
+    raise SystemExit(1)
+clear_targets = library.mooncakePgTestClearFailedTargets
+clear_targets.argtypes = []
+clear_targets.restype = None
+add_target = library.mooncakePgTestAddFailedTarget
+add_target.argtypes = [ctypes.c_int]
+add_target.restype = None
+setter = library.mooncakePgTestSetFaultEnabled
+setter.argtypes = [ctypes.c_int]
+setter.restype = None
+reset_counter = library.mooncakePgTestResetFailureCount
+reset_counter.argtypes = []
+reset_counter.restype = None
+counter = library.mooncakePgTestGetFailureCount
+counter.argtypes = []
+counter.restype = ctypes.c_uint64
+setter(0)
+clear_targets()
+add_target(1)
+reset_counter()
+setter(1)
+setter(0)
+clear_targets()
+counter()
+"""
+    environment = os.environ.copy()
+    environment["LD_PRELOAD"] = preload
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c", probe, str(library)],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=30.0,
+            env=environment,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise unittest.SkipTest(
+            f"transfer fault injection is unavailable: {error}"
+        ) from error
+
+    if result.returncode != 0:
+        reason = result.stderr.strip() or result.stdout.strip()
+        if not reason:
+            reason = f"exit code {result.returncode}"
+        raise unittest.SkipTest(
+            f"transfer fault injection is unavailable: {reason}"
+        )
+
+
+@contextmanager
+def preload_transfer_fault() -> Generator[Path, None, None]:
+    """Preload the transfer fault shim into spawned workers."""
+    if not sys.platform.startswith("linux"):
+        raise unittest.SkipTest("LD_PRELOAD fault injection requires Linux")
+
+    with tempfile.TemporaryDirectory(prefix="mooncake-pg-fault-") as temp_dir:
+        library = Path(temp_dir) / "libmooncake_pg_fault.so"
+        _build_preload(library)
+
+        preload_entries = [str(library)]
+        if previous_preload := os.environ.get("LD_PRELOAD"):
+            preload_entries.append(previous_preload)
+
+        preload = os.pathsep.join(preload_entries)
+        _verify_preload(library, preload)
+
+        with temporary_env({"LD_PRELOAD": preload}):
+            yield library
+
+
+class TransferFault:
+    """Coordinate directed link failures across worker processes."""
+
+    def __init__(self, library: str | Path, *, local_rank: int) -> None:
+        self._library = ctypes.CDLL(str(library))
+        is_available = self._library.mooncakePgTestFaultAvailable
+        is_available.argtypes = []
+        is_available.restype = ctypes.c_int
+        if not is_available():
+            raise RuntimeError(
+                "preloaded transfer fault shim cannot resolve its "
+                "required symbols"
+            )
+        self._clear_failed_targets = (
+            self._library.mooncakePgTestClearFailedTargets
+        )
+        self._clear_failed_targets.argtypes = []
+        self._clear_failed_targets.restype = None
+        self._add_failed_target = self._library.mooncakePgTestAddFailedTarget
+        self._add_failed_target.argtypes = [ctypes.c_int]
+        self._add_failed_target.restype = None
+        self._set_enabled = self._library.mooncakePgTestSetFaultEnabled
+        self._set_enabled.argtypes = [ctypes.c_int]
+        self._set_enabled.restype = None
+        self._reset_count = self._library.mooncakePgTestResetFailureCount
+        self._reset_count.argtypes = []
+        self._reset_count.restype = None
+        self._get_count = self._library.mooncakePgTestGetFailureCount
+        self._get_count.argtypes = []
+        self._get_count.restype = ctypes.c_uint64
+        if local_rank < 0:
+            raise ValueError("local rank must be non-negative")
+        self._local_rank = local_rank
+        self._set_enabled(0)
+        self._clear_failed_targets()
+        self._reset_count()
+        self._active = False
+
+    @staticmethod
+    def _normalize_links(
+        links: Iterable[RankPair],
+    ) -> tuple[RankPair, ...]:
+        normalized = tuple(dict.fromkeys(links))
+        if not normalized:
+            raise ValueError("at least one failed link is required")
+        for source_rank, target_rank in normalized:
+            if (
+                source_rank < 0
+                or target_rank < 0
+                or source_rank == target_rank
+            ):
+                raise ValueError(
+                    "failed links require distinct, non-negative ranks"
+                )
+        return normalized
+
+    @contextmanager
+    def failing_links(
+        self, links: Iterable[RankPair]
+    ) -> Generator[None, None, None]:
+        """Fail directed links whose source is this worker's rank."""
+        if self._active:
+            raise RuntimeError("fault scopes cannot be nested")
+        normalized = self._normalize_links(links)
+        local_targets = {
+            target_rank
+            for source_rank, target_rank in normalized
+            if source_rank == self._local_rank
+        }
+
+        self._set_enabled(0)
+        self._clear_failed_targets()
+        for target_rank in local_targets:
+            self._add_failed_target(target_rank)
+        self._reset_count()
+        self._set_enabled(bool(local_targets))
+        self._active = True
+        try:
+            yield
+        finally:
+            self._set_enabled(0)
+            self._clear_failed_targets()
+            self._active = False
+
+    @contextmanager
+    def failing_link(
+        self, source_rank: int, target_rank: int
+    ) -> Generator[None, None, None]:
+        """Fail one directed global-rank link within this scope."""
+        with self.failing_links(((source_rank, target_rank),)):
+            yield
+
+    @property
+    def injected_count(self) -> int:
+        return int(self._get_count())
diff --git a/mooncake-pg/tests/transfer_fault_preload.cpp b/mooncake-pg/tests/transfer_fault_preload.cpp
new file mode 100644
index 0000000000..fe8ae8195e
--- /dev/null
+++ b/mooncake-pg/tests/transfer_fault_preload.cpp
@@ -0,0 +1,189 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <atomic>
+#include <cstdint>
+#include <cstdlib>
+#include <dlfcn.h>
+#include <mutex>
+#include <optional>
+#include <set>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "control_plane/link_manager.h"
+#include "transfer_engine.h"
+
+namespace {
+
+std::atomic<bool> fault_enabled{false};
+std::atomic<uint64_t> injected_failure_count{0};
+
+std::mutex fault_config_mutex;
+std::set<mooncake::GlobalRank> failed_targets;
+
+// Fault rules use global ranks, while transfer requests identify targets by
+// segment ID. Capture both mappings so we can apply rank-level rules to
+// individual transfer tasks.
+std::mutex mapping_mutex;
+std::unordered_map<mooncake::SegmentID, mooncake::GlobalRank>
+    segment_id_to_rank;
+std::unordered_map<mooncake::BatchID, std::vector<mooncake::GlobalRank>>
+    batch_id_to_target_ranks;
+
+constexpr char kGetTransferStatusSymbol[] =
+    "_ZN8mooncake14TransferEngine17getTransferStatusEmmRNS_"
+    "9Transport14TransferStatusE";
+constexpr char kSubmitTransferSymbol[] =
+    "_ZN8mooncake14TransferEngine14submitTransferEmRKSt6vectorINS_"
+    "9Transport15TransferRequestESaIS3_EE";
+constexpr char kResolvePeerSymbol[] =
+    "_ZNK8mooncake11LinkManager11resolvePeerEi";
+
+using GetTransferStatus = mooncake::Status (*)(mooncake::TransferEngine*,
+                                               mooncake::BatchID, size_t,
+                                               mooncake::TransferStatus&);
+using SubmitTransfer =
+    mooncake::Status (*)(mooncake::TransferEngine*, mooncake::BatchID,
+                         const std::vector<mooncake::TransferRequest>&);
+using ResolvePeer = std::optional<mooncake::SegmentID> (*)(
+    const mooncake::LinkManager*, mooncake::GlobalRank);
+
+void* findRealSymbol(const char* name) {
+    if (auto symbol = dlsym(RTLD_NEXT, name)) return symbol;
+
+    // Python loads extension dependencies in a local ELF scope, where
+    // RTLD_NEXT cannot see libmooncake_pg even though interposition still
+    // applies to its PLT calls. Look up the original definition directly
+    // from the already-loaded library in that case.
+    static auto handle = dlopen("libmooncake_pg.so", RTLD_LAZY | RTLD_NOLOAD);
+    return handle ? dlsym(handle, name) : nullptr;
+}
+
+GetTransferStatus findRealGetTransferStatus() {
+    static auto real = reinterpret_cast<GetTransferStatus>(
+        findRealSymbol(kGetTransferStatusSymbol));
+    return real;
+}
+
+SubmitTransfer findRealSubmitTransfer() {
+    static auto real =
+        reinterpret_cast<SubmitTransfer>(findRealSymbol(kSubmitTransferSymbol));
+    return real;
+}
+
+ResolvePeer findRealResolvePeer() {
+    static auto real =
+        reinterpret_cast<ResolvePeer>(findRealSymbol(kResolvePeerSymbol));
+    return real;
+}
+
+bool shouldInjectFailure(mooncake::GlobalRank target_rank) {
+    if (!fault_enabled.load(std::memory_order_acquire)) return false;
+
+    std::lock_guard<std::mutex> lock(fault_config_mutex);
+    return failed_targets.contains(target_rank);
+}
+
+}  // namespace
+
+namespace mooncake {
+
+std::optional<TransferMetadata::SegmentID> LinkManager::resolvePeer(
+    GlobalRank peer) const {
+    auto real = findRealResolvePeer();
+    if (!real) std::abort();
+    auto target_id = real(this, peer);
+    if (target_id.has_value()) {
+        std::lock_guard<std::mutex> lock(mapping_mutex);
+        segment_id_to_rank[*target_id] = peer;
+    }
+    return target_id;
+}
+
+Status TransferEngine::submitTransfer(
+    BatchID batch_id, const std::vector<TransferRequest>& entries) {
+    auto real = findRealSubmitTransfer();
+    if (!real) std::abort();
+    auto result = real(this, batch_id, entries);
+    if (result.ok()) {
+        std::vector<GlobalRank> target_ranks(entries.size(),
+                                             kInvalidGlobalRank);
+        std::lock_guard<std::mutex> lock(mapping_mutex);
+        for (size_t task_id = 0; task_id < entries.size(); ++task_id) {
+            auto rank_it = segment_id_to_rank.find(entries[task_id].target_id);
+            if (rank_it != segment_id_to_rank.end()) {
+                target_ranks[task_id] = rank_it->second;
+            }
+        }
+        batch_id_to_target_ranks.insert_or_assign(batch_id,
+                                                  std::move(target_ranks));
+    }
+    return result;
+}
+
+Status TransferEngine::getTransferStatus(BatchID batch_id, size_t task_id,
+                                         TransferStatus& status) {
+    auto real = findRealGetTransferStatus();
+    if (!real) std::abort();
+    auto result = real(this, batch_id, task_id, status);
+    if (result.ok() && status.s == TransferStatusEnum::COMPLETED &&
+        fault_enabled.load(std::memory_order_acquire)) {
+        GlobalRank target_rank = kInvalidGlobalRank;
+        {
+            std::lock_guard<std::mutex> lock(mapping_mutex);
+            auto batch_it = batch_id_to_target_ranks.find(batch_id);
+            if (batch_it != batch_id_to_target_ranks.end() &&
+                task_id < batch_it->second.size()) {
+                target_rank = batch_it->second[task_id];
+            }
+        }
+        if (shouldInjectFailure(target_rank)) {
+            status.s = TransferStatusEnum::FAILED;
+            injected_failure_count.fetch_add(1, std::memory_order_relaxed);
+        }
+    }
+    return result;
+}
+
+}  // namespace mooncake
+
+extern "C" int mooncakePgTestFaultAvailable() {
+    return findRealGetTransferStatus() != nullptr &&
+           findRealSubmitTransfer() != nullptr &&
+           findRealResolvePeer() != nullptr;
+}
+
+extern "C" void mooncakePgTestClearFailedTargets() {
+    std::lock_guard<std::mutex> lock(fault_config_mutex);
+    failed_targets.clear();
+}
+
+extern "C" void mooncakePgTestAddFailedTarget(int target_rank) {
+    std::lock_guard<std::mutex> lock(fault_config_mutex);
+    failed_targets.insert(target_rank);
+}
+
+extern "C" void mooncakePgTestSetFaultEnabled(int enabled) {
+    fault_enabled.store(enabled != 0, std::memory_order_release);
+}
+
+extern "C" void mooncakePgTestResetFailureCount() {
+    injected_failure_count.store(0, std::memory_order_release);
+}
+
+extern "C" uint64_t mooncakePgTestGetFailureCount() {
+    return injected_failure_count.load(std::memory_order_acquire);
+}
diff --git a/mooncake-pg/torch/BuildPgExt.cmake b/mooncake-pg/torch/BuildPgExt.cmake
index 3332cf36e4..cd3a7cd473 100644
--- a/mooncake-pg/torch/BuildPgExt.cmake
+++ b/mooncake-pg/torch/BuildPgExt.cmake
@@ -3,16 +3,14 @@
 # Invoked at build time via cmake -P from the root CMakeLists.txt when
 # WITH_EP=ON.  Variables are passed with -D from the custom target:
 #
-#   SOURCE_DIR          - mooncake-pg/torch source directory
-#   EP_CUDA_MAJOR       - CUDA major version (integer)
-#   EP_CUDA_MINOR       - CUDA minor version (integer)
-#   EP_TORCH_VERSIONS   - pipe-separated (|) PyTorch versions to build for
-#                         (empty = use the currently-installed torch)
-#   STAGING_DIR         - destination directory for the built .so files
-#   PG_CORE_SO_PATH     - absolute path to the built libmooncake_pg.so
-#   PG_DEVICE_SO_PATH   - absolute path to libmooncake_pg_device.so
-#   EP_USE_MUSA         - set to "1" when building for MUSA (MTLink path)
-#   EP_USE_MACA         - set to "1" when building for MACA (MTLink path)
+# SOURCE_DIR: mooncake-pg/torch source directory. EP_CUDA_MAJOR: CUDA major
+# version. EP_CUDA_MINOR: CUDA minor version. EP_TORCH_VERSIONS: pipe-separated
+# PyTorch versions; empty uses installed Torch. STAGING_DIR: destination for the
+# built shared libraries. BUILD_DIR: backend-owned directory for setuptools
+# build output. PG_CORE_SO_PATH: absolute path to the built libmooncake_pg.so.
+# PG_DEVICE_SO_PATH: absolute path to libmooncake_pg_device.so. EP_USE_MUSA: set
+# to "1" for the MUSA/MTLink path. EP_USE_MACA: set to "1" for the MACA/MTLink
+# path.
 
 cmake_minimum_required(VERSION 3.16)
 
@@ -25,21 +23,27 @@ if(EP_TORCH_VERSIONS)
 endif()
 
 # ---------------------------------------------------------------------------
-# 1. Set up the build environment.
+# Set up the build environment.
 # ---------------------------------------------------------------------------
-# Clear jobserver variables so that sub-processes started by setup.py do not
-# try to connect to the parent ninja's jobserver pipe FDs, which are not
-# inherited and cause: "ninja: error: Could not initialize jobserver: Invalid
-# file descriptors".
+# Clear jobserver variables so that sub-processes started by setup.py do not try
+# to connect to the parent ninja's jobserver pipe FDs, which are not inherited
+# and cause: "ninja: error: Could not initialize jobserver: Invalid file
+# descriptors".
 set(ENV{MAKEFLAGS} "")
 set(ENV{MFLAGS} "")
 if(NOT PG_CORE_SO_PATH OR NOT EXISTS "${PG_CORE_SO_PATH}")
-  message(FATAL_ERROR
-    "[PG] PG_CORE_SO_PATH is missing or does not exist: ${PG_CORE_SO_PATH}")
+  message(
+    FATAL_ERROR
+      "[PG] PG_CORE_SO_PATH is missing or does not exist: ${PG_CORE_SO_PATH}")
 endif()
 if(NOT PG_DEVICE_SO_PATH OR NOT EXISTS "${PG_DEVICE_SO_PATH}")
-  message(FATAL_ERROR
-    "[PG] PG_DEVICE_SO_PATH is missing or does not exist: ${PG_DEVICE_SO_PATH}")
+  message(
+    FATAL_ERROR
+      "[PG] PG_DEVICE_SO_PATH is missing or does not exist: ${PG_DEVICE_SO_PATH}"
+  )
+endif()
+if(NOT BUILD_DIR)
+  message(FATAL_ERROR "[PG] BUILD_DIR is required")
 endif()
 set(ENV{MOONCAKE_PG_CORE_SO_PATH} "${PG_CORE_SO_PATH}")
 if(EP_USE_MUSA)
@@ -59,45 +63,65 @@ else()
 endif()
 
 # ---------------------------------------------------------------------------
-# 2. Build the PG Python extension.
+# Build the PG Python extension.
 # ---------------------------------------------------------------------------
-if("${EP_TORCH_VERSIONS}" STREQUAL "")
-  message(STATUS "[PG] Building with currently-installed PyTorch")
+file(REMOVE_RECURSE "${BUILD_DIR}")
+file(MAKE_DIRECTORY "${BUILD_DIR}" "${STAGING_DIR}")
+
+function(build_pg_extension _build_key)
+  set(_build_lib "${BUILD_DIR}/${_build_key}/lib")
+  set(_build_temp "${BUILD_DIR}/${_build_key}/temp")
+  file(MAKE_DIRECTORY "${_build_lib}" "${_build_temp}")
+
   execute_process(
-    COMMAND ${Python3_EXECUTABLE} setup.py build_ext --build-lib .
+    COMMAND ${Python3_EXECUTABLE} setup.py build_ext --build-lib "${_build_lib}"
+            --build-temp "${_build_temp}" --force
     WORKING_DIRECTORY "${SOURCE_DIR}"
-    RESULT_VARIABLE _ret
-  )
+    RESULT_VARIABLE _ret)
   if(NOT _ret EQUAL 0)
-    message(FATAL_ERROR "[PG] Extension build failed (exit code: ${_ret})")
+    message(FATAL_ERROR "[PG] Extension build failed for ${_build_key}")
+  endif()
+
+  file(GLOB _extension_files "${_build_lib}/mooncake/*.so")
+  if(NOT _extension_files)
+    message(
+      FATAL_ERROR
+        "[PG] Extension build produced no shared library in ${_build_lib}/mooncake"
+    )
   endif()
+  foreach(_extension IN LISTS _extension_files)
+    get_filename_component(_fname "${_extension}" NAME)
+    message(STATUS "[PG] Staging ${_fname} -> ${STAGING_DIR}")
+    file(
+      COPY "${_extension}"
+      DESTINATION "${STAGING_DIR}"
+      NO_SOURCE_PERMISSIONS)
+  endforeach()
+endfunction()
+
+if("${EP_TORCH_VERSIONS}" STREQUAL "")
+  message(STATUS "[PG] Building with currently-installed PyTorch")
+  build_pg_extension("current")
 else()
   message(STATUS "[PG] Building for PyTorch versions: ${EP_TORCH_VERSIONS}")
   foreach(_version IN LISTS EP_TORCH_VERSIONS)
-    install_pytorch_wheel("${_version}" "${EP_CUDA_MAJOR}" "${EP_CUDA_MINOR}" "[PG]")
-
-    execute_process(
-      COMMAND ${Python3_EXECUTABLE} setup.py build_ext --build-lib . --force
-      WORKING_DIRECTORY "${SOURCE_DIR}"
-      RESULT_VARIABLE _ret
-    )
-    if(NOT _ret EQUAL 0)
-      message(FATAL_ERROR "[PG] Extension build failed for PyTorch ${_version}")
-    endif()
+    install_pytorch_wheel("${_version}" "${EP_CUDA_MAJOR}" "${EP_CUDA_MINOR}"
+                          "[PG]")
+    string(REPLACE "." "_" _build_key "torch_${_version}")
+    build_pg_extension("${_build_key}")
   endforeach()
 endif()
 
 # ---------------------------------------------------------------------------
-# 3. Stage only fatbin-bearing device and extension .so files. The host-only
-#    core is packaged before auditwheel so its dependencies are repaired.
+# Stage the device library. Torch ABI extensions were staged from their
+# backend-owned build directories above. The host-only core is installed by
+# CMake's python component.
 # ---------------------------------------------------------------------------
-file(MAKE_DIRECTORY "${STAGING_DIR}")
-file(GLOB _so_files "${SOURCE_DIR}/mooncake/*.so")
-list(APPEND _so_files "${PG_DEVICE_SO_PATH}")
-foreach(_so IN LISTS _so_files)
-  get_filename_component(_fname "${_so}" NAME)
-  message(STATUS "[PG] Staging ${_fname} -> ${STAGING_DIR}")
-  file(COPY "${_so}" DESTINATION "${STAGING_DIR}" NO_SOURCE_PERMISSIONS)
-endforeach()
+get_filename_component(_device_name "${PG_DEVICE_SO_PATH}" NAME)
+message(STATUS "[PG] Staging ${_device_name} -> ${STAGING_DIR}")
+file(
+  COPY "${PG_DEVICE_SO_PATH}"
+  DESTINATION "${STAGING_DIR}"
+  NO_SOURCE_PERMISSIONS)
 
 message(STATUS "[PG] Mooncake PG extension build complete")
diff --git a/mooncake-pg/torch/include/work_handles.h b/mooncake-pg/torch/include/work_handles.h
index 8881ac5263..5a40af2b44 100644
--- a/mooncake-pg/torch/include/work_handles.h
+++ b/mooncake-pg/torch/include/work_handles.h
@@ -8,6 +8,7 @@
 #include <torch/csrc/distributed/c10d/Work.hpp>
 #include <torch/torch.h>
 
+#include <atomic>
 #include <any>
 #include <functional>
 #include <memory>
@@ -46,6 +47,10 @@ class MooncakeWorkTracker final {
     void evictCompleted() noexcept;
     void shutdown() noexcept;
 
+    // Captured CUDA work stays retained while graph capture is active because
+    // querying its event is illegal on a capturing CUDA context.
+    void notifyCapture(bool capturing) noexcept;
+
    private:
     friend class MooncakeWorkCpu;
     friend class MooncakeWorkCuda;
@@ -65,6 +70,7 @@ class MooncakeWorkTracker final {
     std::vector<RetiredResources> retired_;
     std::vector<std::any> retained_until_shutdown_;
     bool is_shutdown_ = false;
+    std::atomic<int> capture_depth_{0};
 };
 
 // Collective Work handles
@@ -94,10 +100,12 @@ class MooncakeWorkCpu : public ::c10d::Work {
 
 class MooncakeWorkCuda : public ::c10d::Work {
    public:
+    // The capture state is supplied by the collective's actual CUDA stream.
     MooncakeWorkCuda(c10d::OpType opType, std::shared_ptr<c10::Event> event,
                      FailedRanksHint failedRanksHint,
                      std::shared_ptr<MooncakeWorkTracker> tracker,
-                     std::vector<at::Tensor> keepAlive = {});
+                     std::vector<at::Tensor> keepAlive = {},
+                     bool is_captured = false);
     ~MooncakeWorkCuda() override;
 
     bool isCompleted() override { return event_->query(); }
diff --git a/mooncake-pg/torch/src/mooncake_backend.cpp b/mooncake-pg/torch/src/mooncake_backend.cpp
index a5fbf6ca0f..aa92ce760a 100644
--- a/mooncake-pg/torch/src/mooncake_backend.cpp
+++ b/mooncake-pg/torch/src/mooncake_backend.cpp
@@ -21,6 +21,12 @@
 namespace mooncake {
 namespace {
 
+#ifdef MOONCAKE_EP_USE_MUSA
+constexpr c10::DeviceType kGpuDeviceType = c10::DeviceType::PrivateUse1;
+#else
+constexpr c10::DeviceType kGpuDeviceType = c10::DeviceType::CUDA;
+#endif
+
 constexpr const char* kSingleTensorError =
     "Expecting one tensor only but got multiple.";
 constexpr const char* kSparseError = "Sparse op not supported.";
@@ -380,8 +386,7 @@ MooncakeBackend::MooncakeBackend(
     // Register a lightweight Backend shim so PyTorch dispatch can find a
     // registered Backend for this ProcessGroup. The shim delegates supported
     // P2P and collective operations back to this backend.
-    const auto device_type =
-        isCpu_ ? c10::DeviceType::CPU : c10::DeviceType::CUDA;
+    const auto device_type = isCpu_ ? c10::DeviceType::CPU : kGpuDeviceType;
     auto shim = c10::make_intrusive<MooncakeBackendShim>(this, max_group_size_);
     setBackend(device_type, BackendType::CUSTOM, shim);
 #ifndef MOONCAKE_EP_USE_MUSA
@@ -430,16 +435,25 @@ c10::intrusive_ptr<c10d::Work> MooncakeBackend::launchCollective(
     checkResult(GpuFn(args..., comm_, convertStream(stream),
                       failed_ranks_hint.data(), failed_ranks_hint_count),
                 operation);
+    // Clear a sticky error before recording the completion event and checking
+    // capture state on the collective's stream.
+    cudaGetLastError();
     if (postCompletion) postCompletion();
-    auto event = std::make_shared<c10::Event>(c10::DeviceType::CUDA);
+    auto event = std::make_shared<c10::Event>(kGpuDeviceType);
     event->record(stream);
-    if (at::cuda::currentStreamCaptureStatus() ==
-        c10::cuda::CaptureStatus::None) {
+    cudaStreamCaptureStatus captureStatus = cudaStreamCaptureStatusNone;
+    cudaStreamIsCapturing(stream.stream(), &captureStatus);
+    const bool is_captured = captureStatus != cudaStreamCaptureStatusNone ||
+                             at::cuda::currentStreamCaptureStatus() !=
+                                 c10::cuda::CaptureStatus::None;
+    if (is_captured) {
+        work_tracker_->notifyCapture(true);
+    } else {
         work_tracker_->evictCompleted();
     }
     return c10::make_intrusive<MooncakeWorkCuda>(
         opType, std::move(event), std::move(failed_ranks_hint), work_tracker_,
-        std::move(keepAlive));
+        std::move(keepAlive), is_captured);
 }
 
 template <auto CpuFn, auto GpuFn, typename... Args>
@@ -549,9 +563,8 @@ c10::intrusive_ptr<c10d::Work> MooncakeBackend::allgather(
 c10::intrusive_ptr<c10d::Work> MooncakeBackend::_allgather_base(
     at::Tensor& outputBuffer, at::Tensor& inputBuffer,
     const c10d::AllgatherOptions&) {
-    validateSingleBufferTensors(
-        outputBuffer, inputBuffer,
-        isCpu_ ? c10::DeviceType::CPU : c10::DeviceType::CUDA);
+    validateSingleBufferTensors(outputBuffer, inputBuffer,
+                                isCpu_ ? c10::DeviceType::CPU : kGpuDeviceType);
 
     return launchCollective<mooncakePgAllGatherCpu, mooncakePgAllGatherGpu>(
         c10d::OpType::_ALLGATHER_BASE, "mooncakePgAllGather", inputBuffer,
@@ -563,9 +576,8 @@ c10::intrusive_ptr<c10d::Work> MooncakeBackend::_allgather_base(
 c10::intrusive_ptr<c10d::Work> MooncakeBackend::_reduce_scatter_base(
     at::Tensor& outputBuffer, at::Tensor& inputBuffer,
     const c10d::ReduceScatterOptions& opts) {
-    validateSingleBufferTensors(
-        outputBuffer, inputBuffer,
-        isCpu_ ? c10::DeviceType::CPU : c10::DeviceType::CUDA);
+    validateSingleBufferTensors(outputBuffer, inputBuffer,
+                                isCpu_ ? c10::DeviceType::CPU : kGpuDeviceType);
 
     return launchCollective<mooncakePgReduceScatterCpu,
                             mooncakePgReduceScatterGpu>(
@@ -622,7 +634,7 @@ c10::intrusive_ptr<c10d::Work> MooncakeBackend::barrier(
         mooncakePgBarrierGpu(comm_, convertStream(stream),
                              failed_ranks_hint.data(), failed_ranks_hint_count),
         "mooncakePgBarrierGpu");
-    auto event = std::make_shared<c10::Event>(c10::DeviceType::CUDA);
+    auto event = std::make_shared<c10::Event>(kGpuDeviceType);
     event->record(stream);
     if (at::cuda::currentStreamCaptureStatus() ==
         c10::cuda::CaptureStatus::None) {
diff --git a/mooncake-pg/torch/src/work_handles.cpp b/mooncake-pg/torch/src/work_handles.cpp
index 23bbb999a9..a114fa49d0 100644
--- a/mooncake-pg/torch/src/work_handles.cpp
+++ b/mooncake-pg/torch/src/work_handles.cpp
@@ -16,6 +16,7 @@
 #include <utility>
 
 namespace mooncake {
+
 namespace {
 
 using CompletionHandle = std::shared_ptr<::mooncakePgCompletion>;
@@ -88,7 +89,17 @@ void MooncakeWorkTracker::retainUntilShutdown(std::any resources) noexcept {
     retained_until_shutdown_.push_back(std::move(resources));
 }
 
+void MooncakeWorkTracker::notifyCapture(bool capturing) noexcept {
+    if (capturing) {
+        capture_depth_.fetch_add(1, std::memory_order_relaxed);
+    } else {
+        capture_depth_.fetch_sub(1, std::memory_order_relaxed);
+    }
+}
+
 void MooncakeWorkTracker::evictCompleted() noexcept {
+    // cudaEventQuery is illegal while any captured work is still live.
+    if (capture_depth_.load(std::memory_order_relaxed) > 0) return;
     std::vector<RetiredResources> candidates;
     {
         std::lock_guard<std::mutex> lock(mutex_);
@@ -204,11 +215,11 @@ MooncakeWorkCuda::MooncakeWorkCuda(c10d::OpType opType,
                                    std::shared_ptr<c10::Event> event,
                                    FailedRanksHint failedRanksHint,
                                    std::shared_ptr<MooncakeWorkTracker> tracker,
-                                   std::vector<at::Tensor> keepAlive)
+                                   std::vector<at::Tensor> keepAlive,
+                                   bool is_captured)
     : Work(-1, opType),
       event_(std::move(event)),
-      is_captured_(at::cuda::currentStreamCaptureStatus() !=
-                   c10::cuda::CaptureStatus::None),
+      is_captured_(is_captured),
       failed_ranks_hint_(std::move(failedRanksHint)),
       tracker_(std::move(tracker)),
       keep_alive_(std::move(keepAlive)) {
@@ -218,6 +229,9 @@ MooncakeWorkCuda::MooncakeWorkCuda(c10d::OpType opType,
 MooncakeWorkCuda::~MooncakeWorkCuda() {
     if (!tracker_) return;
     if (is_captured_) {
+        // Captured graph resources remain valid until the graph has released
+        // its references; the tracker owns them through shutdown.
+        tracker_->notifyCapture(false);
         tracker_->retainUntilShutdown(makeTrackedResources(
             std::move(event_), std::move(failed_ranks_hint_),
             std::move(keep_alive_)));
diff --git a/mooncake-reshard/README.md b/mooncake-reshard/README.md
new file mode 100644
index 0000000000..1530e643e5
--- /dev/null
+++ b/mooncake-reshard/README.md
@@ -0,0 +1,191 @@
+# Mooncake Reshard
+
+`mooncake-reshard` defines framework-neutral contracts, address-free N-D
+logical planning, runtime binding, and Store-backed snapshots for reusable
+runtime resources. Model-weight storage and Transfer Engine execution remain
+separate runtime phases.
+
+Framework-owned adapters inspect framework runtime objects, normalize
+framework-specific values, and construct typed canonical manifests. Mooncake
+core accepts only those typed values; it does not import or inspect framework
+objects or accept alternate field names or duck-typed records.
+
+The public Python API is split by responsibility:
+
+- `mooncake.reshard.contracts` exposes `ResourceManifest`,
+  `PlacementManifest`, and `RuntimeBindingManifest` as structural `Protocol`
+  contracts for resource-neutral identity and lifecycle;
+- `mooncake.reshard.weight` defines model-weight placement, runtime-binding
+  input contracts, and address-free N-D planning.
+- `mooncake.reshard.kv_cache` defines KV-cache topology, placement, runtime
+  binding, serialization, and logical transfer planning.
+
+## Weight Placement Model
+
+`WeightPlacementManifest` describes one complete, address-free global logical
+placement of a model-weight generation. It contains:
+
+- a `ParallelTopology` with TP, PP, EP, and DP sizes plus the selected
+  participants;
+- per-tensor `SplitAxis(kind, dim)`, `ReplicatedAxis(kind)`, and
+  `OwnershipAxis(kind)` entries that distinguish logical sharding, complete
+  replicas, and ownership;
+- canonical `TensorDescriptor` values whose only shard representation is
+  `shard_dims`;
+- one `WeightPlacementPart` for every selected participant;
+- canonical global tensor descriptors and N-D logical fragments;
+- a placement ID and digest computed after the complete part set validates.
+
+`ParallelTopology.world_size` is the selected participant count. It is not
+inferred from `tp_size * pp_size * ep_size * dp_size`: parallel axes may share
+workers, and a placement may select one complete DP replica while retaining the
+runtime's declared `dp_size`. A tensor that declares independent `SplitAxis`
+values must provide the rank combinations needed to prove its axis-to-dimension
+splits.
+
+Framework adapters first construct address-free `WeightPlacementPart` values.
+A collection barrier assembles the complete participant set and validates
+logical tensor coverage. The logical planner does not consume GPU addresses or
+allocation metadata.
+
+An alias group may span placement parts. `WeightPlacementManifest` performs the
+global check after collection: every alias member must be in the complete
+tensor catalog and every fragment for every member must declare the identical
+group.
+
+## Logical Planning
+
+The planner consumes complete source and target placements:
+
+```python
+logical_plan = plan_placement_transfer(source_placement, target_placement)
+```
+
+The result is a backend-neutral `LogicalTransferPlan`. TP and EP use N-D
+logical-box split and merge, PP routes framework-provided ownership, and DP
+selects a complete source replica or follows a declared DP owner. The plan
+contains compact N-D overlap regions but no runtime addresses, endpoints,
+allocation bounds, leases, or backend request.
+
+`plan_stored_transfer_to_target_placement` accepts a committed address-free
+`StoredWeightManifest` as the logical source. The plan retains the manifest's
+canonical identity and selected fragments so a later binding layer can verify
+that it is still using the intended Store snapshot.
+
+`PlanningLimits` bounds both transfer-region creation and later flattened
+segment expansion. A backend must supply an explicit expansion bound; it cannot
+turn a compact N-D plan into an unbounded number of operations.
+
+The logical planner is copy-only. It does not infer model semantics from tensor
+names or transform dtype, quantization, packing, swizzle, or checkpoint format.
+
+## Runtime Binding
+
+`bind_logical_transfer_plan` attaches selected typed
+`WeightRuntimeBindingManifest` values to a `LogicalTransferPlan`. It rechecks
+placement identity and digest, runtime fragment geometry, address/allocation
+bounds, generation, lease, target coverage, and alias scope before returning a
+bound `TransferPlan`.
+
+This plan records runtime evidence but neither submits a copy nor retains the
+underlying allocation. A Transfer Engine executor must acquire allocation
+guards and revalidate bindings atomically with the submission that consumes
+the plan.
+
+## Store Snapshots
+
+`StoredResourceManifest` is the persistent resource base. The concrete
+`StoredWeightManifest` adds revision, weight generation, tensor descriptors,
+stored fragments, and its canonical digest. It contains no GPU address or
+runtime allocation owner.
+
+`MooncakeDistributedStore.begin_weight_snapshot()` returns a
+`WeightStoreWriter` for one immutable snapshot. A framework adapter supplies
+complete placement/binding inventories, resolves each `write_tensor()` call to
+canonical fragment IDs, and provides allocation guards for Store I/O. After
+every required fragment succeeds, `commit()` publishes the single
+`StoredWeightManifest`.
+
+### Public API Migration
+
+This release removes the public `*_with_parallelism` API family and its helper
+types `ParallelAxis`, `TensorParallelism`, and `ReadTarget`. This is a breaking
+change for applications using the former multi-axis tensor API. Weight snapshot
+writers now use the explicit lifecycle:
+
+```python
+writer = WeightStore(store).begin_weight_snapshot(descriptor, adapter)
+writer.write_tensor(tensor_id, tensor)
+manifest = writer.commit()
+```
+
+The snapshot writer stores manifest-managed payload fragments and publishes one
+`StoredWeightManifest`; it does not produce an ordinary Store tensor object.
+Weight snapshot readers use `WeightStore.load_manifest()`, `plan_load()`, and
+`load()` with target placement and runtime binding manifests. The existing
+single-axis TP APIs named `*_with_tp` remain separate compatibility APIs.
+
+If `commit()` reports a manifest publication failure after the Store records
+the commit decision, the writer stays open and preserves its uploaded payloads.
+Retry `commit()` on the same writer to complete publication.
+
+`WeightStore.load_manifest()` and `WeightStore.plan_load()` use the stored
+manifest as the source of truth for restore. The target framework supplies the
+placement, runtime binding, and allocation guards required by `get_into_ranges`.
+
+## Module Responsibilities
+
+- `types.py` defines tensor and logical-fragment contracts.
+- `topology.py` defines parallel sizes and selected participants.
+- `part.py` defines one participant's address-free contribution.
+- `placement.py` assembles and identifies a complete global placement.
+- `runtime.py` defines typed physical-binding input contracts for later phases.
+- `validation.py` validates manifest-level geometry, coverage, aliases, and
+  runtime-binding shape contracts.
+- `_planner/contracts.py` computes N-D logical overlap regions and logical
+  coverage.
+- `_planner/binding.py`, `bound_contracts.py`, and `bound_validation.py` bind
+  a logical plan to typed runtime snapshots and validate physical evidence.
+- `planner.py` exposes both logical planning and runtime-binding APIs.
+- `manifest.py` preserves the public import surface.
+
+## KV Cache Placement Model
+
+`KVCachePlacementManifest` describes an address-free KV-cache placement over a
+selected topology. Each participant contributes a `KVCachePlacementPart`, and
+`KVCacheRuntimeBindingManifest` supplies operation-scoped live buffers. Runtime
+bindings contain no lease or eviction state; the framework owns pinning and
+lifetime. `KVCacheSnapshotDescriptor` independently describes model and token
+semantics. Legacy logical planning permits omission for compatibility; the
+Runtime-to-Runtime executor requires an explicit snapshot and operation ID.
+
+The KV-cache implementation is split by responsibility:
+
+- `snapshot.py` defines content identity;
+- `topology.py`, `part.py`, and `placement.py` define logical placement;
+- `runtime.py` and `binding.py` define and validate live buffer bindings;
+- `planner.py` defines semantically validated logical and prepared plans;
+- `resolved.py` and `transfer.py` validate and lower bounded resolved ranges;
+- `executor.py` and `completion.py` execute TE writes and collect all participants;
+- `runtime_serde.py` serializes resolved bindings, operations, and receipts;
+- `serde.py`, `snapshot_serde.py`, and `plan_serde.py` define strict JSON
+  boundaries.
+
+KV planning is source/target-role agnostic. A placement may expose one or more
+complete DP replicas, and each local-target plan selects exactly one source DP
+replica. Callers may choose that source rank explicitly; otherwise the planner
+maps target DP ranks round-robin over the source placement's available DP ranks.
+
+`weight_placement_to_json` and `weight_placement_from_json` are the explicit
+public JSON APIs. Their wire format contains only canonical fields, and
+deserialization rejects alternate field names rather than translating
+framework-specific input.
+
+Run the reshard tests from the repository root:
+
+```bash
+PYTHONPATH=mooncake-reshard/python \
+python3 -m pytest -q mooncake-reshard/tests
+
+npx --yes pyright --project mooncake-reshard/pyrightconfig.json
+```
diff --git a/mooncake-reshard/benchmarks/ranged_read_snapshot.py b/mooncake-reshard/benchmarks/ranged_read_snapshot.py
new file mode 100644
index 0000000000..12f3e33e5c
--- /dev/null
+++ b/mooncake-reshard/benchmarks/ranged_read_snapshot.py
@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import socket
+import statistics
+import sys
+import time
+
+import numpy as np
+
+
+def send_json(connection, value):
+    connection.sendall((json.dumps(value) + "\n").encode())
+
+
+def recv_json(connection):
+    data = bytearray()
+    while True:
+        byte = connection.recv(1)
+        if not byte:
+            raise RuntimeError("coordination peer closed")
+        if byte == b"\n":
+            return json.loads(data)
+        data.extend(byte)
+
+
+def listen_one(port):
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind(("0.0.0.0", port))
+    server.listen(1)
+    connection, _ = server.accept()
+    server.close()
+    return connection
+
+
+def connect_to(host, port):
+    while True:
+        try:
+            connection = socket.create_connection((host, port), timeout=5)
+            connection.settimeout(None)
+            return connection
+        except OSError:
+            time.sleep(0.2)
+
+
+def import_store():
+    runtime = os.environ["RUNTIME_PY"]
+    if runtime not in sys.path:
+        sys.path.insert(0, runtime)
+    import store
+
+    return store
+
+
+def setup_store(module, args):
+    client = module.MooncakeDistributedStore()
+    result = client.setup(
+        args.local_host,
+        "P2PHANDSHAKE",
+        args.global_segment_bytes,
+        args.local_buffer_bytes,
+        "rdma",
+        args.rdma_device,
+        args.master,
+    )
+    if result != 0:
+        raise RuntimeError(f"Store setup failed: {result}")
+    return client
+
+
+def make_payload(index, nbytes):
+    payload = np.arange(nbytes, dtype=np.uint8)
+    payload += np.uint8((index * 17) & 0xFF)
+    return payload
+
+
+def put_objects(client, args):
+    keys = [f"{args.key_prefix}:{index}" for index in range(args.objects)]
+    payloads = [make_payload(index, args.object_bytes) for index in range(args.objects)]
+    for key, payload in zip(keys, payloads):
+        if client.register_buffer(payload.ctypes.data, payload.nbytes) != 0:
+            raise RuntimeError(f"register writer buffer failed: {key}")
+        result = client.put_from(key, payload.ctypes.data, payload.nbytes)
+        if result != 0:
+            raise RuntimeError(f"put_from failed for {key}: {result}")
+    return keys, payloads
+
+
+def build_workload(keys, payloads, args):
+    if args.range_bytes > args.object_bytes:
+        raise ValueError("range_bytes must not exceed object_bytes")
+    output = np.empty(args.ranges * args.range_bytes, dtype=np.uint8)
+    expected = np.empty_like(output)
+    slots = args.object_bytes // args.range_bytes
+    requests = []
+    for index in range(args.ranges):
+        object_index = (index * 17) % args.objects
+        slot = (index * 1103515245 + object_index * 12345) % slots
+        source_offset = slot * args.range_bytes
+        target_offset = index * args.range_bytes
+        expected[target_offset : target_offset + args.range_bytes] = payloads[
+            object_index
+        ][source_offset : source_offset + args.range_bytes]
+        requests.append((object_index, source_offset, target_offset))
+
+    batches = []
+    for begin in range(0, len(requests), args.batch_ranges):
+        grouped = {}
+        for object_index, source_offset, target_offset in requests[
+            begin : begin + args.batch_ranges
+        ]:
+            group = grouped.setdefault(object_index, ([], [], []))
+            group[0].append(target_offset)
+            group[1].append(source_offset)
+            group[2].append(args.range_bytes)
+        object_indices = list(grouped)
+        batches.append(
+            (
+                [output.ctypes.data],
+                [[keys[index] for index in object_indices]],
+                [[grouped[index][0] for index in object_indices]],
+                [[grouped[index][1] for index in object_indices]],
+                [[grouped[index][2] for index in object_indices]],
+            )
+        )
+    return output, expected, batches
+
+
+def validate_results(results, sizes):
+    if len(results) != 1 or len(results[0]) != len(sizes[0]):
+        raise RuntimeError("ranged-read result shape mismatch")
+    for actual_group, expected_group in zip(results[0], sizes[0]):
+        if list(actual_group) != list(expected_group):
+            raise RuntimeError("ranged-read returned a partial result")
+
+
+def percentile(samples, fraction):
+    ordered = sorted(samples)
+    return ordered[round((len(ordered) - 1) * fraction)]
+
+
+def benchmark(client, keys, payloads, args, location):
+    output, expected, batches = build_workload(keys, payloads, args)
+    if client.register_buffer(output.ctypes.data, output.nbytes) != 0:
+        raise RuntimeError("register destination buffer failed")
+
+    def run_once(mode):
+        start = time.perf_counter_ns()
+        snapshot = None
+        if mode == "snapshot":
+            snapshot = client.prepare_get_into_ranges_snapshot(keys)
+        for addresses, all_keys, dst_offsets, src_offsets, sizes in batches:
+            if snapshot is None:
+                results = client.get_into_ranges(
+                    addresses, all_keys, dst_offsets, src_offsets, sizes
+                )
+            else:
+                results = client.get_into_ranges_from_snapshot(
+                    snapshot, addresses, all_keys, dst_offsets, src_offsets, sizes
+                )
+            validate_results(results, sizes)
+        elapsed_us = (time.perf_counter_ns() - start) / 1000
+        if not np.array_equal(output, expected):
+            raise RuntimeError(f"payload mismatch in {mode} mode")
+        return elapsed_us
+
+    try:
+        for _ in range(args.warmup):
+            run_once("plain")
+            run_once("snapshot")
+        samples = {"plain": [], "snapshot": []}
+        for iteration in range(args.iters):
+            order = (
+                ("plain", "snapshot")
+                if iteration % 2 == 0
+                else (
+                    "snapshot",
+                    "plain",
+                )
+            )
+            for mode in order:
+                samples[mode].append(run_once(mode))
+    finally:
+        client.unregister_buffer(output.ctypes.data)
+
+    summaries = {}
+    for mode, values in samples.items():
+        p50 = statistics.median(values)
+        p95 = percentile(values, 0.95)
+        summaries[mode] = {
+            "p50_us": p50,
+            "p95_us": p95,
+            "useful_gbps_p50": output.nbytes * 8 / p50 / 1000,
+        }
+    result = {
+        "location": location,
+        "objects": args.objects,
+        "object_bytes": args.object_bytes,
+        "ranges": args.ranges,
+        "range_bytes": args.range_bytes,
+        "batch_ranges": args.batch_ranges,
+        "batches": len(batches),
+        "payload_bytes": output.nbytes,
+        "iters": args.iters,
+        "plain": summaries["plain"],
+        "snapshot": summaries["snapshot"],
+        "speedup": summaries["plain"]["p50_us"] / summaries["snapshot"]["p50_us"],
+    }
+    print("RESHARD_RANGE_SUMMARY " + json.dumps(result, sort_keys=True), flush=True)
+    return result
+
+
+def writer(module, args):
+    connection = listen_one(args.coord_port)
+    client = setup_store(module, args)
+    keys, payloads = put_objects(client, args)
+    send_json(connection, keys)
+    if recv_json(connection) != "done":
+        raise RuntimeError("bad reader acknowledgement")
+    for payload in payloads:
+        client.unregister_buffer(payload.ctypes.data)
+    client.close()
+
+
+def reader(module, args):
+    connection = connect_to(args.writer_host, args.coord_port)
+    client = setup_store(module, args)
+    keys = recv_json(connection)
+    payloads = [make_payload(index, args.object_bytes) for index in range(args.objects)]
+    benchmark(client, keys, payloads, args, "remote")
+    send_json(connection, "done")
+    client.close()
+
+
+def local(module, args):
+    client = setup_store(module, args)
+    keys, payloads = put_objects(client, args)
+    benchmark(client, keys, payloads, args, "local")
+    for payload in payloads:
+        client.unregister_buffer(payload.ctypes.data)
+    client.close()
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("role", choices=("writer", "reader", "local"))
+    parser.add_argument("--local-host", required=True)
+    parser.add_argument("--master", required=True)
+    parser.add_argument("--writer-host", default="127.0.0.1")
+    parser.add_argument("--coord-port", type=int, default=56117)
+    parser.add_argument("--rdma-device", default="erdma_0")
+    parser.add_argument("--key-prefix", default="reshard-snapshot-bench")
+    parser.add_argument("--objects", type=int, default=24)
+    parser.add_argument("--object-bytes", type=int, default=2 * 1024 * 1024)
+    parser.add_argument("--ranges", type=int, default=98304)
+    parser.add_argument("--range-bytes", type=int, default=264)
+    parser.add_argument("--batch-ranges", type=int, default=1024)
+    parser.add_argument("--iters", type=int, default=9)
+    parser.add_argument("--warmup", type=int, default=2)
+    parser.add_argument("--global-segment-bytes", type=int, default=512 * 1024 * 1024)
+    parser.add_argument("--local-buffer-bytes", type=int, default=256 * 1024 * 1024)
+    args = parser.parse_args()
+    if (
+        min(
+            args.objects,
+            args.object_bytes,
+            args.ranges,
+            args.range_bytes,
+            args.batch_ranges,
+            args.iters,
+        )
+        <= 0
+    ):
+        parser.error("workload dimensions must be positive")
+    return args
+
+
+def main():
+    args = parse_args()
+    module = import_store()
+    if args.role == "writer":
+        writer(module, args)
+    elif args.role == "reader":
+        reader(module, args)
+    else:
+        local(module, args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/mooncake-reshard/benchmarks/runtime_binding.py b/mooncake-reshard/benchmarks/runtime_binding.py
new file mode 100644
index 0000000000..2d874ebd22
--- /dev/null
+++ b/mooncake-reshard/benchmarks/runtime_binding.py
@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""Measure the CPU contract cost of logical planning and runtime binding.
+
+Run from a source checkout:
+
+    PYTHONPATH=mooncake-reshard/python \
+      python mooncake-reshard/benchmarks/runtime_binding.py
+
+This is deliberately an opt-in metadata benchmark. It creates no GPU tensors,
+does not start Mooncake Store, and does not submit work to Transfer Engine.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, replace
+import json
+from math import prod
+import pickle
+import platform
+import statistics
+import time
+import tracemalloc
+from typing import Callable, TypeVar
+
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+)
+from mooncake.reshard.weight._planner.bound_validation import (
+    _validate_target_physical_ranges,
+)
+from mooncake.reshard.weight._planner.binding import _build_executor_plans
+
+
+Result = TypeVar("Result")
+
+
+@dataclass(frozen=True)
+class RuntimeInputs:
+    placement: WeightPlacementManifest
+    bindings: tuple[WeightRuntimeBindingManifest, ...]
+
+
+def _canonical_strides_bytes(shape: tuple[int, ...], itemsize: int) -> tuple[int, ...]:
+    strides: list[int] = []
+    running = itemsize
+    for extent in reversed(shape):
+        strides.append(running)
+        running *= extent
+    return tuple(reversed(strides))
+
+
+def _runtime_inputs(
+    *,
+    tp: int,
+    dp: int,
+    pp_rank: int,
+    ep_rank: int,
+    address_base: int,
+    label: str,
+) -> RuntimeInputs:
+    global_shape = (4096, 4096)
+    itemsize = 2
+    tensor = TensorDescriptor(
+        tensor_id="layers.2.experts.3.w1",
+        global_shape=global_shape,
+        dtype="bfloat16",
+        itemsize=itemsize,
+        shard_dims=(1,),
+        layer_id=2,
+        expert_id=3,
+        layout_fingerprint="benchmark:qwen3.5:bf16:v1",
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            OwnershipAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+    shard_width = global_shape[1] // tp
+    participants: list[TopologyParticipant] = []
+    fragments: list[PlacementFragment] = []
+    participant_bindings: list[tuple[str, RuntimeBindingFragment]] = []
+    for dp_rank in range(dp):
+        for tp_rank in range(tp):
+            worker_id = f"{label}-d{dp_rank}-t{tp_rank}"
+            rank = ParallelRank(
+                dp=dp_rank,
+                tp=tp_rank,
+                pp=pp_rank,
+                ep=ep_rank,
+            )
+            participant_id = worker_id
+            placement_fragment_id = f"{worker_id}-placement"
+            local_shape = (global_shape[0], shard_width)
+            nbytes = prod(local_shape) * itemsize
+            address = address_base + (dp_rank * tp + tp_rank) * (nbytes + 0x1000)
+            participants.append(TopologyParticipant(participant_id, rank))
+            fragments.append(
+                PlacementFragment(
+                    placement_fragment_id=placement_fragment_id,
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(0, tp_rank * shard_width),
+                    local_shape=local_shape,
+                    nbytes=nbytes,
+                    rank=rank,
+                )
+            )
+            participant_bindings.append(
+                (
+                    participant_id,
+                    RuntimeBindingFragment(
+                        placement_fragment_id=placement_fragment_id,
+                        fragment_id=f"{worker_id}-runtime",
+                        address=address,
+                        nbytes=nbytes,
+                        worker_id=worker_id,
+                        endpoint=f"{worker_id}:12345",
+                        device="cuda:0",
+                        itemsize=itemsize,
+                        local_shape=local_shape,
+                        strides_bytes=_canonical_strides_bytes(local_shape, itemsize),
+                        storage_address=address,
+                        storage_nbytes=nbytes,
+                        storage_offset_bytes=0,
+                    ),
+                )
+            )
+
+    topology = ParallelTopology(
+        tp_size=tp,
+        pp_size=pp_rank + 1,
+        ep_size=ep_rank + 1,
+        dp_size=dp,
+        participants=tuple(participants),
+    )
+    placement = WeightPlacementManifest.from_fragments(
+        resource_id="benchmark-qwen3.5-0.8b",
+        revision="benchmark-step-42",
+        weight_generation=1,
+        placement_set_id=label,
+        topology=topology,
+        tensors=(tensor,),
+        fragments=tuple(fragments),
+    )
+    return RuntimeInputs(
+        placement=placement,
+        bindings=tuple(
+            WeightRuntimeBindingManifest(
+                resource_id=placement.resource_id,
+                revision=placement.revision,
+                placement_id=placement.placement_id,
+                placement_digest=placement.digest,
+                instance_id=participant_id,
+                participant_id=participant_id,
+                generation=1,
+                lease_id=f"{participant_id}-lease",
+                fragments=(binding,),
+            )
+            for participant_id, binding in participant_bindings
+        ),
+    )
+
+
+def _median_ms(
+    action: Callable[[], Result], *, warmup: int, repeats: int
+) -> tuple[float, Result]:
+    for _ in range(warmup):
+        action()
+    samples: list[float] = []
+    result = action()
+    for _ in range(repeats):
+        started = time.perf_counter_ns()
+        result = action()
+        samples.append((time.perf_counter_ns() - started) / 1_000_000)
+    return statistics.median(samples), result
+
+
+def _physical_regions(plan, *, rows: int, count: int):
+    if rows <= 0 or count <= 0:
+        raise ValueError("rows and regions must be positive")
+    operation = plan.operations[0]
+    if (
+        rows > operation.target.local_shape[0]
+        or count > operation.target.local_shape[1]
+    ):
+        raise ValueError("requested physical-region grid exceeds the target fragment")
+    itemsize = operation.target.binding.itemsize
+    source_row_stride = operation.source.local_shape[1] * itemsize
+    target_row_stride = operation.target.local_shape[1] * itemsize
+    return tuple(
+        replace(
+            operation,
+            overlap_offset=(0, column),
+            overlap_shape=(rows, 1),
+            source_base_offset=column * itemsize,
+            target_base_offset=column * itemsize,
+            inner_bytes=itemsize,
+            outer_loop_counts=(rows,),
+            source_strides=(source_row_stride,),
+            target_strides=(target_row_stride,),
+        )
+        for column in range(count)
+    )
+
+
+def _measure_peak_bytes(action: Callable[[], object]) -> int:
+    tracemalloc.start()
+    try:
+        action()
+        _, peak = tracemalloc.get_traced_memory()
+        return peak
+    finally:
+        tracemalloc.stop()
+
+
+def _accepts(action: Callable[[], object]) -> bool:
+    try:
+        action()
+    except ValueError:
+        return False
+    return True
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Measure Mooncake Reshard logical planning and runtime binding"
+    )
+    parser.add_argument("--warmup", type=int, default=5)
+    parser.add_argument("--repeats", type=int, default=31)
+    parser.add_argument("--physical-rows", type=int, default=128)
+    parser.add_argument("--physical-regions", type=int, default=128)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = _parse_args()
+    if args.warmup < 0 or args.repeats <= 0:
+        raise ValueError("warmup must be non-negative and repeats must be positive")
+    source = _runtime_inputs(
+        tp=4,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000000,
+        label="source",
+    )
+    target = _runtime_inputs(
+        tp=8,
+        dp=1,
+        pp_rank=1,
+        ep_rank=1,
+        address_base=0x20000000,
+        label="target",
+    )
+    logical_ms, logical_plan = _median_ms(
+        lambda: plan_placement_transfer(source.placement, target.placement),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+
+    def binding_action():
+        return bind_logical_transfer_plan(
+            logical_plan,
+            target.bindings,
+            source_bindings=source.bindings,
+        )
+
+    binding_ms, transfer_plan = _median_ms(
+        binding_action,
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    transfer_plan_ms, _ = _median_ms(
+        lambda: replace(transfer_plan),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    pickle_dump_ms, encoded = _median_ms(
+        lambda: pickle.dumps(transfer_plan, protocol=pickle.HIGHEST_PROTOCOL),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    pickle_restore_ms, _ = _median_ms(
+        lambda: pickle.loads(encoded),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    physical_regions = _physical_regions(
+        transfer_plan,
+        rows=args.physical_rows,
+        count=args.physical_regions,
+    )
+    physical_ms, _ = _median_ms(
+        lambda: _validate_target_physical_ranges(
+            physical_regions,
+            max_segment_checks=sum(region.segment_count for region in physical_regions),
+        ),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    selected_source_fragment_ids = frozenset(
+        operation.source.fragment_id for operation in transfer_plan.operations
+    )
+    selected_projection_ms, selected_source_projection = _median_ms(
+        lambda: _build_executor_plans(
+            (source.placement,),
+            source.bindings,
+            "source",
+            selected_fragment_ids=selected_source_fragment_ids,
+        ),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    complete_projection_ms, complete_source_projection = _median_ms(
+        lambda: _build_executor_plans(
+            (source.placement,),
+            source.bindings,
+            "source",
+        ),
+        warmup=args.warmup,
+        repeats=args.repeats,
+    )
+    logical_segment_budget = sum(
+        operation.segment_count for operation in logical_plan.operations
+    )
+    accepted_limits = replace(
+        logical_plan.planning_limits,
+        max_total_lowered_segments=logical_segment_budget,
+    )
+    rejected_limits = replace(
+        logical_plan.planning_limits,
+        max_total_lowered_segments=logical_segment_budget - 1,
+    )
+    physical_segment_budget = sum(region.segment_count for region in physical_regions)
+
+    result = {
+        "environment": {
+            "python": platform.python_version(),
+            "platform": platform.platform(),
+            "processor": platform.processor() or "unknown",
+        },
+        "topology": {
+            "source": {"tp": 4, "pp": 1, "ep": 1, "dp": 2},
+            "target": {"tp": 8, "pp": 2, "ep": 2, "dp": 1},
+        },
+        "workload": {
+            "source_fragments": len(source.placement.fragments),
+            "target_fragments": len(target.placement.fragments),
+            "operations": len(transfer_plan.operations),
+            "selected_source_executors": len(transfer_plan.source_executors),
+            "selected_target_executors": len(transfer_plan.target_executors),
+            "complete_source_executors": len(complete_source_projection),
+            "physical_regions": len(physical_regions),
+            "physical_segments": physical_segment_budget,
+            "warmup": args.warmup,
+            "repeats": args.repeats,
+        },
+        "median_ms": {
+            "logical_planning": logical_ms,
+            "runtime_binding": binding_ms,
+            "transfer_plan_revalidation": transfer_plan_ms,
+            "pickle_dump": pickle_dump_ms,
+            "pickle_restore": pickle_restore_ms,
+            "physical_validation": physical_ms,
+            "selected_source_projection": selected_projection_ms,
+            "complete_source_projection": complete_projection_ms,
+        },
+        "peak_bytes": {"runtime_binding": _measure_peak_bytes(binding_action)},
+        "projection": {
+            "selected_source_executors": len(selected_source_projection),
+            "complete_source_executors": len(complete_source_projection),
+            "unselected_source_executors": len(complete_source_projection)
+            - len(selected_source_projection),
+        },
+        "planning_limits": {
+            "logical_required_segments": logical_segment_budget,
+            "accepted_budget": accepted_limits.max_total_lowered_segments,
+            "accepted": _accepts(
+                lambda: bind_logical_transfer_plan(
+                    replace(logical_plan, planning_limits=accepted_limits),
+                    target.bindings,
+                    source_bindings=source.bindings,
+                )
+            ),
+            "rejected_budget": rejected_limits.max_total_lowered_segments,
+            "rejected": not _accepts(
+                lambda: bind_logical_transfer_plan(
+                    replace(logical_plan, planning_limits=rejected_limits),
+                    target.bindings,
+                    source_bindings=source.bindings,
+                )
+            ),
+            "physical_required_segments": physical_segment_budget,
+            "physical_accepted": _accepts(
+                lambda: _validate_target_physical_ranges(
+                    physical_regions,
+                    max_segment_checks=physical_segment_budget,
+                )
+            ),
+            "physical_rejected": not _accepts(
+                lambda: _validate_target_physical_ranges(
+                    physical_regions,
+                    max_segment_checks=physical_segment_budget - 1,
+                )
+            ),
+        },
+    }
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/mooncake-reshard/conftest.py b/mooncake-reshard/conftest.py
new file mode 100644
index 0000000000..872c9f374b
--- /dev/null
+++ b/mooncake-reshard/conftest.py
@@ -0,0 +1,8 @@
+from pathlib import Path
+
+import mooncake
+
+
+RESHARD_PACKAGE = str(Path(__file__).parent / "python" / "mooncake")
+if RESHARD_PACKAGE not in mooncake.__path__:
+    mooncake.__path__.append(RESHARD_PACKAGE)
diff --git a/mooncake-reshard/pyrightconfig.json b/mooncake-reshard/pyrightconfig.json
new file mode 100644
index 0000000000..7e2151b63e
--- /dev/null
+++ b/mooncake-reshard/pyrightconfig.json
@@ -0,0 +1,36 @@
+{
+  "include": [
+    "python/mooncake/reshard/contracts",
+    "python/mooncake/reshard/weight/types.py",
+    "python/mooncake/reshard/weight/topology.py",
+    "python/mooncake/reshard/weight/part.py",
+    "python/mooncake/reshard/weight/placement.py",
+    "python/mooncake/reshard/weight/runtime.py",
+    "python/mooncake/reshard/weight/validation.py",
+    "python/mooncake/reshard/weight/binding.py",
+    "python/mooncake/reshard/weight/serde.py",
+    "python/mooncake/reshard/kv_cache/resolved.py",
+    "python/mooncake/reshard/kv_cache/transfer.py",
+    "python/mooncake/reshard/kv_cache/completion.py",
+    "python/mooncake/reshard/kv_cache/executor.py",
+    "python/mooncake/reshard/kv_cache/runtime_serde.py",
+    "python/mooncake/reshard/kv_cache/snapshot.py",
+    "python/mooncake/reshard/kv_cache/snapshot_serde.py",
+    "python/mooncake/reshard/kv_cache/types.py",
+    "python/mooncake/reshard/kv_cache/topology.py",
+    "python/mooncake/reshard/kv_cache/part.py",
+    "python/mooncake/reshard/kv_cache/placement.py",
+    "python/mooncake/reshard/kv_cache/runtime.py",
+    "python/mooncake/reshard/kv_cache/binding.py",
+    "python/mooncake/reshard/kv_cache/serde.py",
+    "python/mooncake/reshard/kv_cache/planner.py",
+    "python/mooncake/reshard/kv_cache/plan_serde.py",
+    "python/mooncake/reshard/weight/_planner"
+  ],
+  "extraPaths": ["python"],
+  "pythonVersion": "3.10",
+  "typeCheckingMode": "strict",
+  "reportPrivateUsage": "none",
+  "reportUnnecessaryIsInstance": "none",
+  "reportUnusedFunction": "none"
+}
diff --git a/mooncake-reshard/python/mooncake/__init__.py b/mooncake-reshard/python/mooncake/__init__.py
new file mode 100644
index 0000000000..3de8145264
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/__init__.py
@@ -0,0 +1,5 @@
+"""Mooncake split-package namespace for source-tree development."""
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
diff --git a/mooncake-reshard/python/mooncake/reshard/__init__.py b/mooncake-reshard/python/mooncake/reshard/__init__.py
new file mode 100644
index 0000000000..665868acb0
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/__init__.py
@@ -0,0 +1,15 @@
+"""Framework-neutral contracts for reusable model runtime resources."""
+
+from .contracts import (
+    ResourceKind,
+    ResourceManifest,
+    PlacementManifest,
+    RuntimeBindingManifest,
+)
+
+__all__ = [
+    "ResourceKind",
+    "ResourceManifest",
+    "PlacementManifest",
+    "RuntimeBindingManifest",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/_compat.py b/mooncake-reshard/python/mooncake/reshard/_compat.py
new file mode 100644
index 0000000000..c66d2a5475
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/_compat.py
@@ -0,0 +1,53 @@
+"""Compatibility helpers for supported Python runtimes."""
+
+from __future__ import annotations
+
+from itertools import zip_longest
+from typing import Iterable, Iterator, TypeVar, cast, overload
+
+
+_T1 = TypeVar("_T1")
+_T2 = TypeVar("_T2")
+_T3 = TypeVar("_T3")
+_T4 = TypeVar("_T4")
+
+
+@overload
+def _strict_zip(first: Iterable[_T1]) -> Iterator[tuple[_T1]]: ...
+
+
+@overload
+def _strict_zip(
+    first: Iterable[_T1], second: Iterable[_T2]
+) -> Iterator[tuple[_T1, _T2]]: ...
+
+
+@overload
+def _strict_zip(
+    first: Iterable[_T1],
+    second: Iterable[_T2],
+    third: Iterable[_T3],
+) -> Iterator[tuple[_T1, _T2, _T3]]: ...
+
+
+@overload
+def _strict_zip(
+    first: Iterable[_T1],
+    second: Iterable[_T2],
+    third: Iterable[_T3],
+    fourth: Iterable[_T4],
+) -> Iterator[tuple[_T1, _T2, _T3, _T4]]: ...
+
+
+@overload
+def _strict_zip(*iterables: Iterable[object]) -> Iterator[tuple[object, ...]]: ...
+
+
+def _strict_zip(*iterables: Iterable[object]) -> Iterator[tuple[object, ...]]:
+    """Provide ``zip(strict=True)`` semantics on Python 3.9."""
+
+    sentinel = object()
+    for values in zip_longest(*iterables, fillvalue=sentinel):
+        if any(value is sentinel for value in values):
+            raise ValueError("zip() arguments have different lengths")
+        yield cast(tuple[object, ...], values)
diff --git a/mooncake-reshard/python/mooncake/reshard/_typing.py b/mooncake-reshard/python/mooncake/reshard/_typing.py
new file mode 100644
index 0000000000..e4e7952140
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/_typing.py
@@ -0,0 +1,10 @@
+"""Typing compatibility definitions for the supported Python runtimes."""
+
+import sys
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+__all__ = ["TypeAlias"]
diff --git a/mooncake-reshard/python/mooncake/reshard/contracts/__init__.py b/mooncake-reshard/python/mooncake/reshard/contracts/__init__.py
new file mode 100644
index 0000000000..31e5abbd0c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/contracts/__init__.py
@@ -0,0 +1,47 @@
+"""Public resource-neutral contracts for Mooncake resharding."""
+
+from .fragments import RuntimeBindingFragment
+from .ids import (
+    LeaseId,
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    PlacementSetId,
+    ResourceId,
+    RevisionId,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    StoredFragmentSnapshotId,
+    TensorId,
+    TopologyId,
+)
+from .manifest import (
+    PlacementManifest,
+    ResourceKind,
+    ResourceManifest,
+    RuntimeBindingManifest,
+    StoredResourceManifest,
+    validate_resource_binding_identity,
+)
+
+__all__ = [
+    "LeaseId",
+    "ParticipantId",
+    "PlacementFragmentId",
+    "PlacementId",
+    "PlacementManifest",
+    "PlacementSetId",
+    "ResourceId",
+    "ResourceKind",
+    "ResourceManifest",
+    "RevisionId",
+    "RuntimeBindingFragment",
+    "RuntimeBindingManifest",
+    "RuntimeFragmentId",
+    "RuntimeInstanceId",
+    "StoredFragmentSnapshotId",
+    "StoredResourceManifest",
+    "TensorId",
+    "TopologyId",
+    "validate_resource_binding_identity",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/contracts/fragments.py b/mooncake-reshard/python/mooncake/reshard/contracts/fragments.py
new file mode 100644
index 0000000000..7c91713637
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/contracts/fragments.py
@@ -0,0 +1,171 @@
+"""Resource-neutral physical runtime fragments."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Optional, cast
+
+from .ids import PlacementFragmentId, RuntimeFragmentId
+
+
+_MAX_U64 = (1 << 64) - 1
+
+
+@dataclass(frozen=True)
+class RuntimeBindingFragment:
+    """Contiguous physical view bound to one logical placement fragment."""
+
+    placement_fragment_id: PlacementFragmentId
+    fragment_id: RuntimeFragmentId
+    address: int
+    nbytes: int
+    worker_id: str
+    endpoint: str
+    device: str
+    itemsize: int
+    local_shape: tuple[int, ...]
+    strides_bytes: tuple[int, ...]
+    storage_address: int
+    storage_nbytes: int
+    storage_offset_bytes: int
+    owner: Optional[object] = field(default=None, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        for name in (
+            "placement_fragment_id",
+            "fragment_id",
+            "worker_id",
+            "endpoint",
+            "device",
+        ):
+            value = getattr(self, name)
+            if type(value) is not str or not value:
+                raise ValueError(f"{name} must be a non-empty string")
+        _require_address_range(self.address, self.nbytes)
+        _require_integer(self.itemsize, "runtime itemsize", minimum=1)
+        local_shape = _require_integer_tuple(
+            self.local_shape,
+            "runtime local_shape",
+            minimum=1,
+        )
+        strides_bytes = _require_integer_tuple(
+            self.strides_bytes,
+            "runtime strides_bytes",
+            minimum=0,
+        )
+        if len(strides_bytes) != len(local_shape):
+            raise ValueError("runtime stride rank differs from local_shape")
+        if any(
+            extent > 1 and stride == 0
+            for extent, stride in zip(local_shape, strides_bytes)
+        ):
+            raise ValueError(
+                "runtime stride must be positive for non-singleton dimensions"
+            )
+        strides_bytes = _normalize_singleton_strides_bytes(
+            local_shape,
+            strides_bytes,
+            self.itemsize,
+        )
+        object.__setattr__(self, "local_shape", local_shape)
+        object.__setattr__(self, "strides_bytes", strides_bytes)
+        _require_address_range(self.storage_address, self.storage_nbytes)
+        _require_u64(self.storage_offset_bytes, "storage_offset_bytes")
+        if self.storage_offset_bytes > _MAX_U64 - self.storage_address:
+            raise ValueError("normalized runtime address must fit in 64 bits")
+        if self.address != self.storage_address + self.storage_offset_bytes:
+            raise ValueError(
+                "runtime address must equal storage_address plus storage_offset_bytes"
+            )
+        if self.storage_offset_bytes > self.storage_nbytes - self.nbytes:
+            raise ValueError("runtime view exceeds storage allocation bounds")
+
+    def __reduce__(self):
+        """Keep framework-owned allocation references out of process wire state.
+
+        ``owner`` is intentionally process-local. A receiving runtime must obtain
+        a fresh binding under its framework allocation guard before it can submit
+        Store or TE I/O; serializing an arbitrary Python owner would weaken that
+        boundary and is not reliable across processes.
+        """
+
+        return (
+            type(self),
+            (
+                self.placement_fragment_id,
+                self.fragment_id,
+                self.address,
+                self.nbytes,
+                self.worker_id,
+                self.endpoint,
+                self.device,
+                self.itemsize,
+                self.local_shape,
+                self.strides_bytes,
+                self.storage_address,
+                self.storage_nbytes,
+                self.storage_offset_bytes,
+            ),
+        )
+
+
+def _require_integer(value: object, name: str, *, minimum: int = 0) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{name} must be an integer")
+    if value < minimum:
+        raise ValueError(f"{name} must be at least {minimum}")
+    return value
+
+
+def _canonical_strides_bytes(
+    shape: tuple[int, ...],
+    itemsize: int,
+) -> tuple[int, ...]:
+    strides: list[int] = []
+    running = itemsize
+    for extent in reversed(shape):
+        strides.append(running)
+        running *= extent
+    return tuple(reversed(strides))
+
+
+def _normalize_singleton_strides_bytes(
+    shape: tuple[int, ...],
+    strides_bytes: tuple[int, ...],
+    itemsize: int,
+) -> tuple[int, ...]:
+    canonical = _canonical_strides_bytes(shape, itemsize)
+    return tuple(
+        expected if extent == 1 else observed
+        for extent, observed, expected in zip(shape, strides_bytes, canonical)
+    )
+
+
+def _require_integer_tuple(
+    values: object,
+    name: str,
+    *,
+    minimum: int,
+) -> tuple[int, ...]:
+    if type(values) not in (tuple, list):
+        raise ValueError(f"{name} must be a tuple or list")
+    items = cast(Sequence[object], values)
+    return tuple(
+        _require_integer(value, f"{name}[{index}]", minimum=minimum)
+        for index, value in enumerate(items)
+    )
+
+
+def _require_u64(value: object, name: str, *, minimum: int = 0) -> int:
+    integer = _require_integer(value, name, minimum=minimum)
+    if integer > _MAX_U64:
+        raise ValueError(f"{name} must fit in an unsigned 64-bit integer")
+    return integer
+
+
+def _require_address_range(address: object, nbytes: object) -> None:
+    normalized_address = _require_u64(address, "address", minimum=1)
+    normalized_nbytes = _require_u64(nbytes, "nbytes", minimum=1)
+    if normalized_nbytes > _MAX_U64 - normalized_address:
+        raise ValueError("address range must fit in an unsigned 64-bit integer")
diff --git a/mooncake-reshard/python/mooncake/reshard/contracts/ids.py b/mooncake-reshard/python/mooncake/reshard/contracts/ids.py
new file mode 100644
index 0000000000..f6d3d84515
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/contracts/ids.py
@@ -0,0 +1,39 @@
+"""Static identity categories shared by canonical reshard contracts.
+
+``NewType`` preserves the string wire representation while allowing checked
+Python callers to distinguish unrelated resource, placement, and runtime IDs.
+Wire decoders and framework adapters construct these values at their boundary.
+"""
+
+from __future__ import annotations
+
+from typing import NewType
+
+ResourceId = NewType("ResourceId", str)
+PlacementId = NewType("PlacementId", str)
+ParticipantId = NewType("ParticipantId", str)
+PlacementFragmentId = NewType("PlacementFragmentId", str)
+RuntimeFragmentId = NewType("RuntimeFragmentId", str)
+TensorId = NewType("TensorId", str)
+TopologyId = NewType("TopologyId", str)
+PlacementSetId = NewType("PlacementSetId", str)
+RevisionId = NewType("RevisionId", str)
+RuntimeInstanceId = NewType("RuntimeInstanceId", str)
+LeaseId = NewType("LeaseId", str)
+StoredFragmentSnapshotId = NewType("StoredFragmentSnapshotId", str)
+
+
+__all__ = [
+    "LeaseId",
+    "ParticipantId",
+    "PlacementFragmentId",
+    "PlacementId",
+    "PlacementSetId",
+    "ResourceId",
+    "RevisionId",
+    "RuntimeFragmentId",
+    "RuntimeInstanceId",
+    "StoredFragmentSnapshotId",
+    "TensorId",
+    "TopologyId",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/contracts/manifest.py b/mooncake-reshard/python/mooncake/reshard/contracts/manifest.py
new file mode 100644
index 0000000000..c28d4eaa54
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/contracts/manifest.py
@@ -0,0 +1,107 @@
+"""Structural manifest identity and lifecycle contracts."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+from .ids import LeaseId, PlacementId, ResourceId, RuntimeInstanceId
+
+
+class ResourceKind(str, Enum):
+    """Stable discriminator for a reusable runtime resource."""
+
+    MODEL_WEIGHT = "model_weight"
+    KV_CACHE = "kv_cache"
+
+
+class ResourceManifest(Protocol):
+    """Structural contract for a typed reusable resource."""
+
+    @property
+    def resource_id(self) -> ResourceId:
+        """Return the stable canonical resource identity."""
+        ...
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        """Return the stable discriminator for the concrete resource."""
+        ...
+
+
+class PlacementManifest(ResourceManifest, Protocol):
+    """Address-free logical placement shared by reusable resources."""
+
+    @property
+    def placement_id(self) -> PlacementId:
+        """Return the stable logical placement identity."""
+        ...
+
+    @property
+    def digest(self) -> str:
+        """Return the digest that attests the serialized placement."""
+        ...
+
+
+class RuntimeBindingManifest(ResourceManifest, Protocol):
+    """Physical locations and lifetime fences for one placement."""
+
+    @property
+    def placement_id(self) -> PlacementId:
+        """Return the logical placement this runtime state attests."""
+        ...
+
+    @property
+    def placement_digest(self) -> str:
+        """Return the digest of the attested logical placement."""
+        ...
+
+    @property
+    def instance_id(self) -> RuntimeInstanceId:
+        """Return the runtime instance that owns this binding."""
+        ...
+
+    @property
+    def generation(self) -> int:
+        """Return the runtime generation fence."""
+        ...
+
+    @property
+    def lease_id(self) -> LeaseId:
+        """Return the live lease fence."""
+        ...
+
+
+@dataclass(frozen=True)
+class StoredResourceManifest(ABC):
+    """Nominal base for persistent reusable-resource metadata."""
+
+    namespace: str
+    resource_id: ResourceId
+    group_id: str
+    manifest_key: str
+    created_at: str
+
+    @property
+    @abstractmethod
+    def resource_kind(self) -> ResourceKind:
+        """Return the concrete persistent resource discriminator."""
+        ...
+
+
+def validate_resource_binding_identity(
+    placement: PlacementManifest,
+    binding: RuntimeBindingManifest,
+) -> None:
+    """Fence a physical binding to the exact typed logical placement."""
+
+    if placement.resource_kind != binding.resource_kind:
+        raise ValueError("placement and runtime binding resource_kind differ")
+    if placement.resource_id != binding.resource_id:
+        raise ValueError("placement and runtime binding resource_id differ")
+    if placement.placement_id != binding.placement_id:
+        raise ValueError("placement_id and runtime binding placement_id differ")
+    if placement.digest != binding.placement_digest:
+        raise ValueError("placement digest and runtime binding placement digest differ")
diff --git a/mooncake-reshard/python/mooncake/reshard/geometry.py b/mooncake-reshard/python/mooncake/reshard/geometry.py
new file mode 100644
index 0000000000..45c35ae78c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/geometry.py
@@ -0,0 +1,265 @@
+"""Resource-neutral N-D logical-box helpers for reshard planners."""
+
+from __future__ import annotations
+
+import heapq
+from array import array
+from math import prod
+from typing import Iterable, Protocol, Sequence
+
+from ._compat import _strict_zip
+
+
+_MAX_HIGH_DIMENSIONAL_PAIRWISE_COMPARISONS = 1_000_000
+
+
+class LogicalBox(Protocol):
+    """An address-free logical box supplied by a resource-specific adapter."""
+
+    @property
+    def global_offset(self) -> tuple[int, ...]: ...
+
+    @property
+    def local_shape(self) -> tuple[int, ...]: ...
+
+
+class OverlapRegion(Protocol):
+    """The logical overlap portion of a resource-specific transfer region."""
+
+    @property
+    def overlap_offset(self) -> tuple[int, ...]: ...
+
+    @property
+    def overlap_shape(self) -> tuple[int, ...]: ...
+
+
+def box_contains(
+    outer_offset: tuple[int, ...],
+    outer_shape: tuple[int, ...],
+    inner_offset: tuple[int, ...],
+    inner_shape: tuple[int, ...],
+) -> bool:
+    """Return whether one N-D logical box is wholly inside another."""
+
+    return all(
+        outer_begin <= inner_begin
+        and inner_begin + inner_extent <= outer_begin + outer_extent
+        for outer_begin, outer_extent, inner_begin, inner_extent in _strict_zip(
+            outer_offset,
+            outer_shape,
+            inner_offset,
+            inner_shape,
+        )
+    )
+
+
+def boxes_overlap(
+    boxes: Sequence[tuple[tuple[int, ...], tuple[int, ...]]],
+) -> bool:
+    """Return whether any two N-D boxes overlap.
+
+    One-dimensional intervals and two-dimensional rectangles use bounded sweep
+    algorithms. Higher-dimensional boxes retain full intersection semantics but
+    fail closed after an explicit pairwise-comparison budget rather than making
+    unbounded validation work part of the public manifest contract.
+    """
+
+    if len(boxes) < 2:
+        return False
+    ndim = len(boxes[0][0])
+    if ndim == 1:
+        return _one_dimensional_boxes_overlap(boxes)
+    if ndim == 2:
+        return _two_dimensional_boxes_overlap(boxes)
+    return _high_dimensional_boxes_overlap(boxes)
+
+
+def _one_dimensional_boxes_overlap(
+    boxes: Sequence[tuple[tuple[int, ...], tuple[int, ...]]],
+) -> bool:
+    ordered = sorted((offset[0], offset[0] + shape[0]) for offset, shape in boxes)
+    previous_end = ordered[0][1]
+    for begin, end in ordered[1:]:
+        if begin < previous_end:
+            return True
+        previous_end = max(previous_end, end)
+    return False
+
+
+class _RangeMaxTree:
+    """Coordinate-compressed range-add/range-maximum tree for 2-D sweeps."""
+
+    def __init__(self, size: int) -> None:
+        if size <= 0:
+            raise ValueError("range tree size must be positive")
+        capacity = size * 4
+        self._size = size
+        self._maximum = array("i", [0]) * capacity
+        self._lazy = array("i", [0]) * capacity
+
+    def add(self, left: int, right: int, value: int) -> None:
+        self._add(1, 0, self._size - 1, left, right, value)
+
+    def maximum(self, left: int, right: int) -> int:
+        return self._maximum_in(1, 0, self._size - 1, left, right)
+
+    def _add(
+        self,
+        node: int,
+        begin: int,
+        end: int,
+        left: int,
+        right: int,
+        value: int,
+    ) -> None:
+        if left <= begin and end <= right:
+            self._maximum[node] += value
+            self._lazy[node] += value
+            return
+        middle = (begin + end) // 2
+        if left <= middle:
+            self._add(node * 2, begin, middle, left, right, value)
+        if right > middle:
+            self._add(node * 2 + 1, middle + 1, end, left, right, value)
+        self._maximum[node] = self._lazy[node] + max(
+            self._maximum[node * 2], self._maximum[node * 2 + 1]
+        )
+
+    def _maximum_in(
+        self,
+        node: int,
+        begin: int,
+        end: int,
+        left: int,
+        right: int,
+    ) -> int:
+        if left <= begin and end <= right:
+            return self._maximum[node]
+        middle = (begin + end) // 2
+        result = 0
+        if left <= middle:
+            result = self._maximum_in(node * 2, begin, middle, left, right)
+        if right > middle:
+            result = max(
+                result,
+                self._maximum_in(node * 2 + 1, middle + 1, end, left, right),
+            )
+        return self._lazy[node] + result
+
+
+def _two_dimensional_boxes_overlap(
+    boxes: Sequence[tuple[tuple[int, ...], tuple[int, ...]]],
+) -> bool:
+    coordinates = sorted(
+        {
+            coordinate
+            for offset, shape in boxes
+            for coordinate in (offset[1], offset[1] + shape[1])
+        }
+    )
+    coordinate_index = {
+        coordinate: index for index, coordinate in enumerate(coordinates)
+    }
+    tree = _RangeMaxTree(len(coordinates) - 1)
+    events: list[tuple[int, int, int, int]] = []
+    for offset, shape in boxes:
+        x_begin = offset[0]
+        x_end = offset[0] + shape[0]
+        y_begin = coordinate_index[offset[1]]
+        y_end = coordinate_index[offset[1] + shape[1]] - 1
+        events.append((x_end, 0, y_begin, y_end))
+        events.append((x_begin, 1, y_begin, y_end))
+
+    for _, is_start, y_begin, y_end in sorted(events):
+        if not is_start:
+            tree.add(y_begin, y_end, -1)
+            continue
+        if tree.maximum(y_begin, y_end) > 0:
+            return True
+        tree.add(y_begin, y_end, 1)
+    return False
+
+
+def _high_dimensional_boxes_overlap(
+    boxes: Sequence[tuple[tuple[int, ...], tuple[int, ...]]],
+) -> bool:
+    sweep_dim = max(
+        range(len(boxes[0][0])),
+        key=lambda dim: len(
+            {(offset[dim], offset[dim] + shape[dim]) for offset, shape in boxes}
+        ),
+    )
+    ordered = sorted(
+        enumerate(boxes),
+        key=lambda item: item[1][0][sweep_dim],
+    )
+    active: dict[int, tuple[tuple[int, ...], tuple[int, ...]]] = {}
+    expirations: list[tuple[int, int]] = []
+    comparisons = 0
+    for index, (offset, shape) in ordered:
+        begin = offset[sweep_dim]
+        while expirations and expirations[0][0] <= begin:
+            _, expired_index = heapq.heappop(expirations)
+            active.pop(expired_index, None)
+        for candidate_offset, candidate_shape in active.values():
+            if comparisons >= _MAX_HIGH_DIMENSIONAL_PAIRWISE_COMPARISONS:
+                raise ValueError(
+                    "high-dimensional overlap budget exceeded before validation"
+                )
+            comparisons += 1
+            if all(
+                left_begin < right_begin + right_extent
+                and right_begin < left_begin + left_extent
+                for left_begin, left_extent, right_begin, right_extent in _strict_zip(
+                    candidate_offset,
+                    candidate_shape,
+                    offset,
+                    shape,
+                )
+            ):
+                return True
+        active[index] = (offset, shape)
+        heapq.heappush(expirations, (offset[sweep_dim] + shape[sweep_dim], index))
+    return False
+
+
+def boxes_exactly_cover(
+    container_offset: tuple[int, ...],
+    container_shape: tuple[int, ...],
+    boxes: Sequence[tuple[tuple[int, ...], tuple[int, ...]]],
+) -> bool:
+    """Require in-bounds, non-overlapping boxes with exact logical volume."""
+
+    if not boxes:
+        return False
+    if any(
+        not box_contains(container_offset, container_shape, offset, shape)
+        for offset, shape in boxes
+    ):
+        return False
+    if sum(prod(shape) for _, shape in boxes) != prod(container_shape):
+        return False
+    return not boxes_overlap(boxes)
+
+
+def regions_exactly_cover(
+    target: LogicalBox,
+    regions: Iterable[OverlapRegion],
+) -> bool:
+    """Require resource-neutral N-D regions to completely cover one target box."""
+
+    return boxes_exactly_cover(
+        target.global_offset,
+        target.local_shape,
+        tuple((region.overlap_offset, region.overlap_shape) for region in regions),
+    )
+
+
+__all__ = [
+    "LogicalBox",
+    "OverlapRegion",
+    "box_contains",
+    "boxes_exactly_cover",
+    "boxes_overlap",
+    "regions_exactly_cover",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/__init__.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/__init__.py
new file mode 100644
index 0000000000..43b7876327
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/__init__.py
@@ -0,0 +1,124 @@
+"""Framework-neutral KV-cache reshard contracts and planning API."""
+
+from .completion import KVCacheCompletion, KVCacheTargetReceipt, KVCacheWriterReceipt
+from .executor import KVCacheTransferEngineExecutor
+from .manifest import (
+    KVCacheBufferBinding,
+    KVCacheComponent,
+    KVCacheDescriptor,
+    KVCacheLayout,
+    KVCachePlacementManifest,
+    KVCachePlacementPart,
+    KVCacheRank,
+    KVCacheRuntimeBinding,
+    KVCacheRuntimeBindingManifest,
+    KVCacheRuntimeBuffer,
+    KVCacheSnapshotDescriptor,
+    KVCacheTopology,
+    KVCacheTopologyParticipant,
+    SnapshotId,
+    assemble_kv_cache_placement,
+    placement_fragment_id,
+    validate_runtime_binding,
+    validate_runtime_bindings,
+)
+from .plan_serde import (
+    kv_cache_logical_plan_from_json,
+    kv_cache_logical_plan_to_json,
+)
+from .planner import (
+    KVCacheLogicalTransferPlan,
+    KVCachePreparedTransferEdge,
+    KVCachePreparedTransferPlan,
+    KVCacheTransferEdge,
+    plan_kv_cache_transfer_to_local_target,
+    prepare_kv_cache_transfer,
+)
+from .resolved import (
+    KVCacheRegisteredRegion,
+    KVCacheResolvedRange,
+    KVCacheResolvedRuntimeBinding,
+    KVCacheTransferLimits,
+    resolve_contiguous_runtime_binding,
+    validate_resolved_runtime_binding,
+)
+from .runtime_serde import (
+    kv_cache_resolved_binding_from_json,
+    kv_cache_resolved_binding_to_json,
+    kv_cache_runtime_transfer_from_json,
+    kv_cache_runtime_transfer_to_json,
+    kv_cache_target_receipt_from_json,
+    kv_cache_target_receipt_to_json,
+    kv_cache_writer_receipt_from_json,
+    kv_cache_writer_receipt_to_json,
+)
+from .serde import (
+    kv_cache_part_from_json,
+    kv_cache_part_to_json,
+    kv_cache_placement_from_json,
+    kv_cache_placement_to_json,
+    kv_cache_runtime_binding_from_json,
+    kv_cache_runtime_binding_to_json,
+)
+from .snapshot_serde import (
+    kv_cache_snapshot_from_json,
+    kv_cache_snapshot_to_json,
+)
+from .transfer import KVCacheRuntimeTransferPlan, KVCacheWrite
+
+__all__ = [
+    "KVCacheBufferBinding",
+    "KVCacheCompletion",
+    "KVCacheComponent",
+    "KVCacheDescriptor",
+    "KVCacheLayout",
+    "KVCacheLogicalTransferPlan",
+    "KVCachePlacementManifest",
+    "KVCachePlacementPart",
+    "KVCachePreparedTransferEdge",
+    "KVCachePreparedTransferPlan",
+    "KVCacheRank",
+    "KVCacheRegisteredRegion",
+    "KVCacheResolvedRange",
+    "KVCacheResolvedRuntimeBinding",
+    "KVCacheRuntimeBinding",
+    "KVCacheRuntimeBindingManifest",
+    "KVCacheRuntimeBuffer",
+    "KVCacheRuntimeTransferPlan",
+    "KVCacheSnapshotDescriptor",
+    "KVCacheTargetReceipt",
+    "KVCacheTopology",
+    "KVCacheTopologyParticipant",
+    "KVCacheTransferEdge",
+    "KVCacheTransferEngineExecutor",
+    "KVCacheTransferLimits",
+    "KVCacheWrite",
+    "KVCacheWriterReceipt",
+    "SnapshotId",
+    "assemble_kv_cache_placement",
+    "kv_cache_logical_plan_from_json",
+    "kv_cache_logical_plan_to_json",
+    "kv_cache_part_from_json",
+    "kv_cache_part_to_json",
+    "kv_cache_placement_from_json",
+    "kv_cache_placement_to_json",
+    "kv_cache_resolved_binding_from_json",
+    "kv_cache_resolved_binding_to_json",
+    "kv_cache_runtime_binding_from_json",
+    "kv_cache_runtime_binding_to_json",
+    "kv_cache_runtime_transfer_from_json",
+    "kv_cache_runtime_transfer_to_json",
+    "kv_cache_snapshot_from_json",
+    "kv_cache_snapshot_to_json",
+    "kv_cache_target_receipt_from_json",
+    "kv_cache_target_receipt_to_json",
+    "kv_cache_writer_receipt_from_json",
+    "kv_cache_writer_receipt_to_json",
+    "placement_fragment_id",
+    "plan_kv_cache_transfer_to_local_target",
+    "prepare_kv_cache_transfer",
+    "resolve_contiguous_runtime_binding",
+    "validate_resolved_runtime_binding",
+    "validate_runtime_binding",
+    "validate_runtime_bindings",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/binding.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/binding.py
new file mode 100644
index 0000000000..4b057b5374
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/binding.py
@@ -0,0 +1,170 @@
+"""Validate live KV-cache buffers against a complete global placement."""
+
+from __future__ import annotations
+
+from itertools import pairwise
+
+from ..contracts import RuntimeInstanceId
+from .placement import KVCachePlacementManifest
+from .runtime import KVCacheRuntimeBindingManifest
+from .snapshot import KVCacheSnapshotDescriptor
+from .types import (
+    KVCacheComponent,
+    KVCacheRuntimeBuffer,
+    canonical_strides_bytes,
+    placement_fragment_id,
+    require_manifest_items,
+)
+
+
+def validate_runtime_binding(
+    placement: KVCachePlacementManifest,
+    binding: KVCacheRuntimeBindingManifest,
+    *,
+    snapshot: KVCacheSnapshotDescriptor | None = None,
+) -> None:
+    if not isinstance(placement, KVCachePlacementManifest):
+        raise TypeError("placement must be a KVCachePlacementManifest")
+    if not isinstance(binding, KVCacheRuntimeBindingManifest):
+        raise TypeError("binding must be a KVCacheRuntimeBindingManifest")
+    if placement.resource_kind != binding.resource_kind:
+        raise ValueError("placement and runtime binding resource_kind differ")
+    if placement.resource_id != binding.resource_id:
+        raise ValueError("placement and runtime binding resource_id differ")
+    if placement.placement_id != binding.placement_id:
+        raise ValueError("placement_id and runtime binding placement_id differ")
+    if placement.digest != binding.placement_digest:
+        raise ValueError("placement digest and runtime binding placement digest differ")
+    if snapshot is not None:
+        if not isinstance(snapshot, KVCacheSnapshotDescriptor):
+            raise TypeError("snapshot must be a KVCacheSnapshotDescriptor")
+        if binding.snapshot_id != snapshot.snapshot_id:
+            raise ValueError("runtime binding snapshot_id differs")
+        if binding.snapshot_digest != snapshot.digest:
+            raise ValueError("runtime binding snapshot digest differs")
+    if placement.revision != binding.revision:
+        raise ValueError("placement and runtime binding revision differ")
+    part = placement.part(binding.participant_id)
+    expected_keys = {
+        (layer_id, component)
+        for layer_id in part.layer_ids
+        for component in KVCacheComponent
+    }
+    actual_keys = {(item.global_layer_id, item.component) for item in binding.buffers}
+    if expected_keys != actual_keys:
+        missing = sorted(
+            (layer, component.value) for layer, component in expected_keys - actual_keys
+        )
+        unknown = sorted(
+            (layer, component.value) for layer, component in actual_keys - expected_keys
+        )
+        detail = missing[0] if missing else unknown[0]
+        raise ValueError(f"runtime binding buffer membership differs: {detail}")
+
+    descriptor = placement.descriptor
+    for item in binding.buffers:
+        fragment = item.fragment
+        expected_fragment_id = placement_fragment_id(
+            part.participant_id,
+            item.global_layer_id,
+            item.component,
+            head_start=part.head_start,
+            head_count=part.head_count,
+        )
+        if fragment.placement_fragment_id != expected_fragment_id:
+            raise ValueError("runtime binding placement_fragment_id differs")
+        if fragment.itemsize != descriptor.itemsize:
+            raise ValueError("runtime binding itemsize differs from placement")
+        if len(fragment.local_shape) != 3:
+            raise ValueError("NHD runtime buffer must have rank three")
+        expected_dim = (
+            descriptor.key_head_dim
+            if item.component is KVCacheComponent.KEY
+            else descriptor.value_head_dim
+        )
+        if fragment.local_shape[1:] != (part.head_count, expected_dim):
+            raise ValueError("runtime binding local_shape differs from placement")
+        expected_nbytes = (
+            fragment.local_shape[0]
+            * fragment.local_shape[1]
+            * fragment.local_shape[2]
+            * fragment.itemsize
+        )
+        if fragment.nbytes != expected_nbytes:
+            raise ValueError("runtime binding nbytes differs from local_shape")
+        expected_strides = canonical_strides_bytes(
+            fragment.local_shape, fragment.itemsize
+        )
+        if fragment.strides_bytes != expected_strides:
+            raise ValueError("runtime binding is not a contiguous NHD row layout")
+    _validate_address_ranges(binding)
+
+
+def validate_runtime_bindings(
+    placement: KVCachePlacementManifest,
+    bindings: object,
+    *,
+    snapshot: KVCacheSnapshotDescriptor | None = None,
+) -> None:
+    items = require_manifest_items(
+        bindings,
+        "runtime bindings",
+        KVCacheRuntimeBindingManifest,
+    )
+    participant_ids = [item.participant_id for item in items]
+    if len(participant_ids) != len(set(participant_ids)):
+        raise ValueError("duplicate runtime binding participant")
+    for binding in items:
+        validate_runtime_binding(placement, binding, snapshot=snapshot)
+    expected = {part.participant_id for part in placement.parts if part.layer_ids}
+    actual = set(participant_ids)
+    missing = sorted(expected - actual)
+    if missing:
+        raise ValueError(f"missing runtime binding participant: {missing[0]}")
+    unknown = sorted(actual - expected)
+    if unknown:
+        raise ValueError(f"unknown runtime binding participant: {unknown[0]}")
+    _validate_shared_instance_ranges(items)
+
+
+def _validate_address_ranges(binding: KVCacheRuntimeBindingManifest) -> None:
+    _validate_shared_instance_ranges((binding,))
+
+
+def _validate_shared_instance_ranges(
+    bindings: tuple[KVCacheRuntimeBindingManifest, ...],
+) -> None:
+    # Virtual addresses are comparable only within the declared address space.
+    by_space: dict[tuple[RuntimeInstanceId, str, str], list[KVCacheRuntimeBuffer]] = {}
+    for binding in bindings:
+        for item in binding.buffers:
+            fragment = item.fragment
+            key = (binding.instance_id, fragment.worker_id, fragment.device)
+            by_space.setdefault(key, []).append(fragment)
+    for fragments in by_space.values():
+        views = sorted(
+            (fragment.address, fragment.address + fragment.nbytes)
+            for fragment in fragments
+        )
+        for previous, current in pairwise(views):
+            if current[0] < previous[1]:
+                raise ValueError("runtime KV buffers overlap in one address space")
+        # Several disjoint views may share the same complete allocation. Distinct
+        # allocation claims may not overlap, including unequal nested claims.
+        allocations = sorted(
+            {
+                (
+                    fragment.storage_address,
+                    fragment.storage_address + fragment.storage_nbytes,
+                )
+                for fragment in fragments
+            }
+        )
+        for previous, current in pairwise(allocations):
+            if current[0] < previous[1]:
+                raise ValueError(
+                    "runtime KV backing allocations overlap in one address space"
+                )
+
+
+__all__ = ["validate_runtime_binding", "validate_runtime_bindings"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/completion.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/completion.py
new file mode 100644
index 0000000000..0ead519a39
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/completion.py
@@ -0,0 +1,182 @@
+"""Operation-bound receipts and a fail-closed all-participant barrier."""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from dataclasses import dataclass
+
+from .transfer import KVCacheRuntimeTransferPlan
+from .types import require_integer, require_nonempty_string, require_sha256
+
+
+@dataclass(frozen=True)
+class KVCacheWriterReceipt:
+    operation_id: str
+    transfer_digest: str
+    writer_id: str
+    target_id: str
+    success: bool
+    completed_bytes: int
+    quiesced: bool
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("operation_id", "writer_id", "target_id"):
+            require_nonempty_string(getattr(self, name), name)
+        require_sha256(self.transfer_digest, "transfer_digest")
+        require_integer(self.completed_bytes, "completed_bytes")
+        if type(self.success) is not bool or type(self.quiesced) is not bool:
+            raise ValueError("receipt success and quiesced must be booleans")
+        if self.success:
+            if self.error is not None or not self.quiesced:
+                raise ValueError("success requires quiescence and no error")
+        else:
+            require_nonempty_string(self.error, "failure error")
+
+
+@dataclass(frozen=True)
+class KVCacheTargetReceipt:
+    operation_id: str
+    transfer_digest: str
+    target_id: str
+    success: bool
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("operation_id", "target_id"):
+            require_nonempty_string(getattr(self, name), name)
+        require_sha256(self.transfer_digest, "transfer_digest")
+        if type(self.success) is not bool:
+            raise ValueError("receipt success must be a boolean")
+        if self.success and self.error is not None:
+            raise ValueError("success cannot contain an error")
+        if not self.success:
+            require_nonempty_string(self.error, "failure error")
+
+
+class KVCacheCompletion:
+    """Collect authenticated control-plane receipts before runtime activation.
+
+    Frameworks transport receipts and validate target content. Mooncake never
+    activates traffic or releases pins. A failed/expired operation is terminal;
+    retry with a new operation ID after outstanding native work is quiescent.
+    """
+
+    def __init__(
+        self, plan: KVCacheRuntimeTransferPlan, *, timeout_seconds: float = 60.0
+    ) -> None:
+        if not isinstance(plan, KVCacheRuntimeTransferPlan):
+            raise TypeError("plan must be a KVCacheRuntimeTransferPlan")
+        if (
+            isinstance(timeout_seconds, bool)
+            or not isinstance(timeout_seconds, (int, float))
+            or not math.isfinite(timeout_seconds)
+            or timeout_seconds <= 0
+        ):
+            raise ValueError("timeout_seconds must be positive and finite")
+        self.plan = plan
+        self._deadline = time.monotonic() + timeout_seconds
+        self._writers: dict[tuple[str, str], KVCacheWriterReceipt] = {}
+        self._targets: dict[str, KVCacheTargetReceipt] = {}
+        self._error: str | None = None
+        self._lock = threading.RLock()
+
+    def _expire(self) -> None:
+        if (
+            not self._complete()
+            and self._error is None
+            and time.monotonic() >= self._deadline
+        ):
+            self._error = "runtime operation completion deadline expired"
+
+    def _complete(self) -> bool:
+        return (
+            self._error is None
+            and self._writers_ready()
+            and len(self._targets) == len(self.plan.target_bindings)
+        )
+
+    def _writers_ready(self) -> bool:
+        return len(self._writers) == len(self.plan.expected_writers) and all(
+            r.success for r in self._writers.values()
+        )
+
+    @property
+    def state(self) -> str:
+        with self._lock:
+            self._expire()
+            if self._error is not None:
+                return "failed"
+            if self._complete():
+                return "complete"
+            return "writers_done" if self._writers_ready() else "pending"
+
+    @property
+    def error(self) -> str | None:
+        with self._lock:
+            self._expire()
+            return self._error
+
+    @property
+    def can_activate(self) -> bool:
+        return self.state == "complete"
+
+    def fail(self, reason: str) -> None:
+        require_nonempty_string(reason, "failure reason")
+        with self._lock:
+            if self._complete():
+                raise ValueError("completed operation is terminal")
+            self._error = self._error or reason
+
+    def _identity(self, operation_id: str, digest: str) -> None:
+        if operation_id != self.plan.operation_id or digest != self.plan.digest:
+            raise ValueError("receipt belongs to a different operation or transfer")
+        self._expire()
+
+    def record_writer(self, receipt: KVCacheWriterReceipt) -> None:
+        if not isinstance(receipt, KVCacheWriterReceipt):
+            raise TypeError("receipt must be a KVCacheWriterReceipt")
+        with self._lock:
+            self._identity(receipt.operation_id, receipt.transfer_digest)
+            key = (receipt.writer_id, receipt.target_id)
+            if key not in self.plan.expected_writers:
+                raise ValueError("receipt writer/target is not expected")
+            if key in self._writers:
+                if self._writers[key] != receipt:
+                    raise ValueError("conflicting duplicate writer receipt")
+                return
+            if self._error is not None:
+                raise ValueError("failed operation is terminal")
+            expected_bytes = self.plan.writer_bytes(*key)
+            if receipt.completed_bytes > expected_bytes or (
+                receipt.success and receipt.completed_bytes != expected_bytes
+            ):
+                raise ValueError("writer receipt byte count differs from plan")
+            self._writers[key] = receipt
+            if not receipt.success:
+                self._error = receipt.error
+
+    def record_target(self, receipt: KVCacheTargetReceipt) -> None:
+        if not isinstance(receipt, KVCacheTargetReceipt):
+            raise TypeError("receipt must be a KVCacheTargetReceipt")
+        with self._lock:
+            self._identity(receipt.operation_id, receipt.transfer_digest)
+            if receipt.target_id not in {
+                b.participant_id for b in self.plan.target_bindings
+            }:
+                raise ValueError("target participant is not expected")
+            if receipt.target_id in self._targets:
+                if self._targets[receipt.target_id] != receipt:
+                    raise ValueError("conflicting duplicate target receipt")
+                return
+            if self._error is not None:
+                raise ValueError("failed operation is terminal")
+            if not self._writers_ready():
+                raise ValueError(
+                    "all expected writers must finish before target validation"
+                )
+            self._targets[receipt.target_id] = receipt
+            if not receipt.success:
+                self._error = receipt.error
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/executor.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/executor.py
new file mode 100644
index 0000000000..90d9b35c02
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/executor.py
@@ -0,0 +1,213 @@
+"""Generic synchronous TE writes with bounded batches and explicit receipts."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from typing import Protocol
+
+from .completion import KVCacheWriterReceipt
+from .resolved import KVCacheRegisteredRegion, KVCacheResolvedRuntimeBinding
+from .transfer import KVCacheRuntimeTransferPlan, KVCacheWrite
+from .types import require_nonempty_string
+
+
+class KVCacheTransferEngine(Protocol):
+    def register_memory(
+        self, buffer_addr: int, capacity: int, location: str = "*"
+    ) -> int: ...
+    def unregister_memory(self, buffer_addr: int) -> int: ...
+    def send_probe(self, peer_server_name: str) -> int: ...
+    def batch_transfer_sync_write(
+        self,
+        target_hostname: str,
+        buffers: list[int],
+        peer_buffer_addresses: list[int],
+        lengths: list[int],
+    ) -> int: ...
+
+
+class KVCacheTransferEngineExecutor:
+    """Use one runtime-owned TE; registration and submission are serialized.
+
+    The runtime must synchronize producer CUDA streams before execution, and
+    keep all source pins and target reservations alive. Nonzero native results
+    do NOT prove that DMA stopped: failed receipts conservatively mark the
+    writer non-quiescent and this executor refuses unregister/retry afterwards.
+    The runtime must drain or destroy the transport before reclaiming memory.
+    Registration errors also leave the native registration state uncertain.
+    This executor stays blocked after such errors; the runtime must rebuild the
+    transport before replacing the executor. No in-place recovery is provided.
+    """
+
+    def __init__(
+        self, engine: KVCacheTransferEngine, *, instance_id: str, endpoint: str
+    ) -> None:
+        require_nonempty_string(instance_id, "instance_id")
+        require_nonempty_string(endpoint, "endpoint")
+        self.engine = engine
+        self.instance_id = instance_id
+        self.endpoint = endpoint
+        self._regions: dict[str, KVCacheRegisteredRegion] = {}
+        self._results: dict[
+            tuple[str, str], tuple[str, tuple[KVCacheWriterReceipt, ...]]
+        ] = {}
+        self._uncertain = False
+        self._lock = threading.RLock()
+
+    def _require_ready(self) -> None:
+        if self._uncertain:
+            raise RuntimeError(
+                "executor requires transport recovery: native work may still be "
+                "in flight or registration state is uncertain"
+            )
+
+    def register_region(self, region: KVCacheRegisteredRegion) -> None:
+        if not isinstance(region, KVCacheRegisteredRegion):
+            raise TypeError("region must be a KVCacheRegisteredRegion")
+        if region.endpoint != self.endpoint:
+            raise ValueError("region endpoint differs from local executor")
+        with self._lock:
+            self._require_ready()
+            if region.region_id in self._regions:
+                if self._regions[region.region_id] == region:
+                    return
+                raise ValueError("registered region_id is already bound")
+            if any(
+                region.address < r.address + r.nbytes
+                and r.address < region.address + region.nbytes
+                for r in self._regions.values()
+            ):
+                raise ValueError("registered regions overlap")
+            # Enter quarantine before crossing the native boundary. Errors or
+            # interruptions may occur after partial registration side effects.
+            self._uncertain = True
+            code = self.engine.register_memory(region.address, region.nbytes)
+            if type(code) is not int or code != 0:
+                raise RuntimeError(f"TE register_memory failed: {code}")
+            self._regions[region.region_id] = region
+            self._uncertain = False
+
+    def unregister_region(self, region_id: str) -> None:
+        with self._lock:
+            self._require_ready()
+            region = self._regions[region_id]
+            self._uncertain = True
+            code = self.engine.unregister_memory(region.address)
+            if type(code) is not int or code != 0:
+                raise RuntimeError(f"TE unregister_memory failed: {code}")
+            del self._regions[region_id]
+            self._uncertain = False
+
+    def validate_local_binding(self, binding: KVCacheResolvedRuntimeBinding) -> None:
+        """Check local owner registration before publishing a source/target binding."""
+        if not isinstance(binding, KVCacheResolvedRuntimeBinding):
+            raise TypeError("binding must be a KVCacheResolvedRuntimeBinding")
+        with self._lock:
+            self._require_ready()
+            if binding.instance_id != self.instance_id:
+                raise ValueError("binding instance differs from local executor")
+            if any(self._regions.get(r.region_id) != r for r in binding.regions):
+                raise ValueError("binding region is not registered with this executor")
+
+    def execute(
+        self, plan: KVCacheRuntimeTransferPlan, writer_id: str, *, warmup: bool = False
+    ) -> tuple[KVCacheWriterReceipt, ...]:
+        if not isinstance(plan, KVCacheRuntimeTransferPlan):
+            raise TypeError("plan must be a KVCacheRuntimeTransferPlan")
+        require_nonempty_string(writer_id, "writer_id")
+        if type(warmup) is not bool:
+            raise ValueError("warmup must be a boolean")
+        with self._lock:
+            self._require_ready()
+            if any(
+                op == plan.operation_id and digest != plan.digest
+                for (op, _), (digest, _) in self._results.items()
+            ):
+                raise ValueError(
+                    "operation_id was already used with a different transfer"
+                )
+            key = (plan.operation_id, writer_id)
+            if key in self._results:
+                digest, receipts = self._results[key]
+                if digest != plan.digest:
+                    raise ValueError(
+                        "operation_id was already used with a different transfer"
+                    )
+                return receipts
+            bindings = [
+                b for b in plan.source_bindings if b.participant_id == writer_id
+            ]
+            if len(bindings) != 1:
+                raise ValueError("writer is not selected by runtime transfer")
+            binding = bindings[0]
+            self.validate_local_binding(binding)
+            selected = [w for w in plan.writes if w.source_participant_id == writer_id]
+            target_ids = sorted({w.target_participant_id for w in selected})
+            completed = dict.fromkeys(target_ids, 0)
+            error: str | None = None
+            quiesced = True
+            try:
+                if warmup:
+                    for endpoint in sorted({w.endpoint for w in selected}):
+                        code = self.engine.send_probe(endpoint)
+                        if type(code) is not int or code != 0:
+                            raise RuntimeError(f"TE peer warmup failed: {code}")
+                for batch in _batches(
+                    selected,
+                    plan.limits.max_batch_operations,
+                    plan.limits.max_batch_bytes,
+                ):
+                    # Once native submission starts, errors or interrupts cannot
+                    # be interpreted as cancellation or permission to unpin.
+                    quiesced = False
+                    code = self.engine.batch_transfer_sync_write(
+                        batch[0].endpoint,
+                        [w.source_address for w in batch],
+                        [w.target_address for w in batch],
+                        [w.nbytes for w in batch],
+                    )
+                    if type(code) is not int or code != 0:
+                        raise RuntimeError(f"TE batch write failed: {code}")
+                    quiesced = True
+                    for write in batch:
+                        completed[write.target_participant_id] += write.nbytes
+            except Exception as exc:  # noqa: BLE001 - native exceptions become failed receipts
+                error = f"{type(exc).__name__}: {exc}"
+            finally:
+                if not quiesced:
+                    self._uncertain = True
+            receipts = tuple(
+                KVCacheWriterReceipt(
+                    plan.operation_id,
+                    plan.digest,
+                    writer_id,
+                    target,
+                    error is None,
+                    completed[target],
+                    quiesced,
+                    error,
+                )
+                for target in target_ids
+            )
+            self._results[key] = (plan.digest, receipts)
+            return receipts
+
+
+def _batches(
+    writes: list[KVCacheWrite], max_count: int, max_bytes: int
+) -> Iterator[list[KVCacheWrite]]:
+    batch: list[KVCacheWrite] = []
+    size = 0
+    for write in writes:
+        if batch and (
+            write.endpoint != batch[0].endpoint
+            or len(batch) == max_count
+            or size + write.nbytes > max_bytes
+        ):
+            yield batch
+            batch, size = [], 0
+        batch.append(write)
+        size += write.nbytes
+    if batch:
+        yield batch
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/manifest.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/manifest.py
new file mode 100644
index 0000000000..f1b17ceab7
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/manifest.py
@@ -0,0 +1,44 @@
+"""Stable public facade for KV-cache manifest contracts."""
+
+from .binding import validate_runtime_binding, validate_runtime_bindings
+from .part import KVCachePlacementPart
+from .placement import (
+    KVCachePlacementManifest,
+    assemble_kv_cache_placement,
+)
+from .runtime import (
+    KVCacheBufferBinding,
+    KVCacheRuntimeBinding,
+    KVCacheRuntimeBindingManifest,
+)
+from .snapshot import KVCacheSnapshotDescriptor, SnapshotId
+from .topology import KVCacheTopology, KVCacheTopologyParticipant
+from .types import (
+    KVCacheComponent,
+    KVCacheDescriptor,
+    KVCacheLayout,
+    KVCacheRank,
+    KVCacheRuntimeBuffer,
+    placement_fragment_id,
+)
+
+__all__ = [
+    "KVCacheBufferBinding",
+    "KVCacheComponent",
+    "KVCacheDescriptor",
+    "KVCacheLayout",
+    "KVCachePlacementManifest",
+    "KVCachePlacementPart",
+    "KVCacheRank",
+    "KVCacheRuntimeBinding",
+    "KVCacheRuntimeBindingManifest",
+    "KVCacheRuntimeBuffer",
+    "KVCacheSnapshotDescriptor",
+    "KVCacheTopology",
+    "KVCacheTopologyParticipant",
+    "SnapshotId",
+    "assemble_kv_cache_placement",
+    "placement_fragment_id",
+    "validate_runtime_binding",
+    "validate_runtime_bindings",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/part.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/part.py
new file mode 100644
index 0000000000..eb81bfb936
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/part.py
@@ -0,0 +1,71 @@
+"""Per-participant address-free KV-cache placement contribution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..contracts import (
+    ParticipantId,
+    PlacementSetId,
+    ResourceId,
+    RevisionId,
+    TopologyId,
+)
+from .types import (
+    KVCacheDescriptor,
+    KVCacheRank,
+    require_integer,
+    require_integer_tuple,
+    require_nonempty_string,
+)
+
+
+@dataclass(frozen=True)
+class KVCachePlacementPart:
+    """One selected worker's logical layer/head ownership."""
+
+    resource_id: ResourceId
+    revision: RevisionId
+    placement_set_id: PlacementSetId
+    topology_id: TopologyId
+    participant_id: ParticipantId
+    rank: KVCacheRank
+    descriptor: KVCacheDescriptor
+    layer_ids: tuple[int, ...]
+    head_start: int
+    head_count: int
+    replica_ordinal: int = 0
+    replica_count: int = 1
+
+    def __post_init__(self) -> None:
+        for name in (
+            "resource_id",
+            "revision",
+            "placement_set_id",
+            "topology_id",
+            "participant_id",
+        ):
+            require_nonempty_string(getattr(self, name), name)
+        if not isinstance(self.rank, KVCacheRank):
+            raise ValueError("placement part rank must be a KVCacheRank")  # noqa: TRY004
+        if not isinstance(self.descriptor, KVCacheDescriptor):
+            raise ValueError(  # noqa: TRY004
+                "placement part descriptor must be a KVCacheDescriptor"
+            )
+        layers = require_integer_tuple(self.layer_ids, "layer_ids")
+        if len(layers) != len(set(layers)):
+            raise ValueError("layer_ids must be unique")
+        if not set(layers).issubset(self.descriptor.global_layer_ids):
+            raise ValueError("placement part contains an unknown global layer")
+        object.__setattr__(self, "layer_ids", tuple(sorted(layers)))
+        require_integer(self.head_start, "head_start")
+        require_integer(self.head_count, "head_count", minimum=1)
+        require_integer(self.replica_ordinal, "replica_ordinal")
+        require_integer(self.replica_count, "replica_count", minimum=1)
+        if self.head_start + self.head_count > self.descriptor.total_kv_heads:
+            raise ValueError("head interval exceeds total_kv_heads")
+        if self.replica_ordinal >= self.replica_count:
+            raise ValueError("replica_ordinal must be smaller than replica_count")
+
+
+__all__ = ["KVCachePlacementPart"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/placement.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/placement.py
new file mode 100644
index 0000000000..84f4512995
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/placement.py
@@ -0,0 +1,331 @@
+"""Complete address-free KV-cache placement and canonical identity."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass, field
+
+from ..contracts import (
+    ParticipantId,
+    PlacementId,
+    PlacementSetId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+)
+from .part import KVCachePlacementPart
+from .topology import KVCacheTopology, KVCacheTopologyParticipant
+from .types import (
+    KVCacheDescriptor,
+    descriptor_identity,
+    require_manifest_items,
+    require_nonempty_string,
+)
+
+
+@dataclass(frozen=True, init=False)
+class KVCachePlacementManifest:
+    """One complete logical KV-cache buffer placement."""
+
+    resource_id: ResourceId
+    placement_id: PlacementId
+    revision: RevisionId
+    placement_set_id: PlacementSetId
+    topology: KVCacheTopology
+    descriptor: KVCacheDescriptor
+    parts: tuple[KVCachePlacementPart, ...]
+    _digest_cache: str | None = field(init=False, repr=False, compare=False)
+
+    def __init__(
+        self,
+        *,
+        resource_id: ResourceId,
+        revision: RevisionId,
+        placement_set_id: PlacementSetId,
+        topology: KVCacheTopology,
+        descriptor: KVCacheDescriptor,
+        parts: tuple[KVCachePlacementPart, ...],
+        placement_id: PlacementId | None = None,
+    ) -> None:
+        for value, name in (
+            (resource_id, "resource_id"),
+            (revision, "revision"),
+            (placement_set_id, "placement_set_id"),
+        ):
+            require_nonempty_string(value, name)
+        if not isinstance(topology, KVCacheTopology):
+            raise ValueError("topology must be a KVCacheTopology")  # noqa: TRY004
+        if not isinstance(descriptor, KVCacheDescriptor):
+            raise ValueError("descriptor must be a KVCacheDescriptor")  # noqa: TRY004
+        normalized_parts = tuple(
+            sorted(
+                require_manifest_items(
+                    parts,
+                    "KVCachePlacementManifest parts",
+                    KVCachePlacementPart,
+                ),
+                key=lambda item: item.participant_id,
+            )
+        )
+        _validate_parts(
+            normalized_parts,
+            resource_id=resource_id,
+            revision=revision,
+            placement_set_id=placement_set_id,
+            topology=topology,
+            descriptor=descriptor,
+        )
+        _validate_logical_coverage(normalized_parts, topology, descriptor)
+        canonical_id = _logical_placement_id(
+            resource_id=resource_id,
+            revision=revision,
+            placement_set_id=placement_set_id,
+            topology=topology,
+            descriptor=descriptor,
+            parts=normalized_parts,
+        )
+        if placement_id is not None and placement_id != canonical_id:
+            raise ValueError("placement_id does not match canonical logical content")
+        object.__setattr__(self, "resource_id", resource_id)
+        object.__setattr__(self, "placement_id", canonical_id)
+        object.__setattr__(self, "revision", revision)
+        object.__setattr__(self, "placement_set_id", placement_set_id)
+        object.__setattr__(self, "topology", topology)
+        object.__setattr__(self, "descriptor", descriptor)
+        object.__setattr__(self, "parts", normalized_parts)
+        object.__setattr__(self, "_digest_cache", None)
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        return ResourceKind.KV_CACHE
+
+    @property
+    def digest(self) -> str:
+        digest = self._digest_cache
+        if digest is None:
+            content = _placement_content(
+                resource_id=self.resource_id,
+                revision=self.revision,
+                placement_set_id=self.placement_set_id,
+                topology=self.topology,
+                descriptor=self.descriptor,
+                parts=self.parts,
+            )
+            content["placement_id"] = self.placement_id
+            digest = _canonical_json_digest(content)
+            object.__setattr__(self, "_digest_cache", digest)
+        return digest
+
+    @property
+    def dp_ranks(self) -> tuple[int, ...]:
+        return tuple(sorted({part.rank.dp for part in self.parts}))
+
+    def part(self, participant_id: ParticipantId) -> KVCachePlacementPart:
+        for part in self.parts:
+            if part.participant_id == participant_id:
+                return part
+        raise ValueError(f"unknown KV-cache participant: {participant_id}")
+
+
+def assemble_kv_cache_placement(
+    parts: Sequence[KVCachePlacementPart],
+    *,
+    dp_size: int,
+    pp_size: int,
+    tp_size: int,
+) -> KVCachePlacementManifest:
+    """Assemble any server's selected participants into one placement.
+
+    The selected participants may contain one or more complete DP replicas.
+    Source/target and Prefill/Decode roles are deliberately not part of this
+    contract; framework discovery code decides which participants to provide.
+    """
+
+    normalized = require_manifest_items(
+        parts,
+        "KV-cache placement parts",
+        KVCachePlacementPart,
+    )
+    if not normalized:
+        raise ValueError("KV-cache placement must contain at least one part")
+    first = normalized[0]
+    topology = KVCacheTopology(
+        dp_size=dp_size,
+        pp_size=pp_size,
+        tp_size=tp_size,
+        participants=tuple(
+            KVCacheTopologyParticipant(part.participant_id, part.rank)
+            for part in normalized
+        ),
+    )
+    return KVCachePlacementManifest(
+        resource_id=first.resource_id,
+        revision=first.revision,
+        placement_set_id=first.placement_set_id,
+        topology=topology,
+        descriptor=first.descriptor,
+        parts=normalized,
+    )
+
+
+def _validate_parts(
+    parts: tuple[KVCachePlacementPart, ...],
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    placement_set_id: PlacementSetId,
+    topology: KVCacheTopology,
+    descriptor: KVCacheDescriptor,
+) -> None:
+    participant_ids = [part.participant_id for part in parts]
+    if len(participant_ids) != len(set(participant_ids)):
+        raise ValueError("duplicate KV-cache placement participant")
+    expected = {
+        participant.participant_id: participant for participant in topology.participants
+    }
+    actual = set(participant_ids)
+    missing = sorted(set(expected) - actual)
+    if missing:
+        raise ValueError(f"missing topology participant: {missing[0]}")
+    unknown = sorted(actual - set(expected))
+    if unknown:
+        raise ValueError(f"unknown topology participant: {unknown[0]}")
+    for part in parts:
+        checks = {
+            "resource_id": resource_id,
+            "revision": revision,
+            "placement_set_id": placement_set_id,
+            "topology_id": topology.topology_id,
+            "descriptor": descriptor,
+            "rank": expected[part.participant_id].rank,
+        }
+        for name, expected_value in checks.items():
+            if getattr(part, name) != expected_value:
+                raise ValueError(f"placement part {name} differs")
+
+
+def _validate_logical_coverage(
+    parts: tuple[KVCachePlacementPart, ...],
+    topology: KVCacheTopology,
+    descriptor: KVCacheDescriptor,
+) -> None:
+    if len(parts) ** 2 * len(descriptor.global_layer_ids) > 10_000_000:
+        raise ValueError("KV-cache placement validation work limit exceeded")
+    selected_dp_ranks = sorted({item.rank.dp for item in topology.participants})
+    for dp_rank in selected_dp_ranks:
+        dp_parts = tuple(part for part in parts if part.rank.dp == dp_rank)
+        for layer_id in descriptor.global_layer_ids:
+            boundaries = sorted(
+                {0, descriptor.total_kv_heads}
+                | {
+                    boundary
+                    for part in dp_parts
+                    if layer_id in part.layer_ids
+                    for boundary in (part.head_start, part.head_start + part.head_count)
+                }
+            )
+            for head in boundaries[:-1]:
+                owners = [
+                    part
+                    for part in dp_parts
+                    if layer_id in part.layer_ids
+                    and part.head_start <= head < part.head_start + part.head_count
+                ]
+                if not owners:
+                    raise ValueError(
+                        "KV-cache placement misses "
+                        f"dp={dp_rank} layer={layer_id} head={head}"
+                    )
+                if len(owners) > 1:
+                    if (
+                        len({(part.head_start, part.head_count) for part in owners})
+                        != 1
+                    ):
+                        raise ValueError(
+                            "overlapping replica head intervals must match exactly"
+                        )
+                    ordinals = {part.replica_ordinal for part in owners}
+                    counts = {part.replica_count for part in owners}
+                    if counts != {len(owners)} or ordinals != set(range(len(owners))):
+                        raise ValueError(
+                            "overlapping KV heads must be an exact declared replica set"
+                        )
+                elif owners[0].replica_count != 1:
+                    raise ValueError("incomplete declared KV-head replica set")
+
+
+def _placement_content(
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    placement_set_id: PlacementSetId,
+    topology: KVCacheTopology,
+    descriptor: KVCacheDescriptor,
+    parts: tuple[KVCachePlacementPart, ...],
+) -> dict[str, object]:
+    return {
+        "schema": "complete-kv-cache-placement",
+        "resource_kind": ResourceKind.KV_CACHE.value,
+        "resource_id": resource_id,
+        "revision": revision,
+        "placement_set_id": placement_set_id,
+        "topology": {
+            "dp_size": topology.dp_size,
+            "pp_size": topology.pp_size,
+            "tp_size": topology.tp_size,
+            "topology_id": topology.topology_id,
+            "participants": [asdict(item) for item in topology.participants],
+        },
+        "descriptor": descriptor_identity(descriptor),
+        "parts": [
+            {
+                "resource_id": part.resource_id,
+                "revision": part.revision,
+                "placement_set_id": part.placement_set_id,
+                "topology_id": part.topology_id,
+                "participant_id": part.participant_id,
+                "rank": asdict(part.rank),
+                "descriptor": descriptor_identity(part.descriptor),
+                "layer_ids": part.layer_ids,
+                "head_start": part.head_start,
+                "head_count": part.head_count,
+                "replica_ordinal": part.replica_ordinal,
+                "replica_count": part.replica_count,
+            }
+            for part in parts
+        ],
+    }
+
+
+def _canonical_json_digest(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _logical_placement_id(
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    placement_set_id: PlacementSetId,
+    topology: KVCacheTopology,
+    descriptor: KVCacheDescriptor,
+    parts: tuple[KVCachePlacementPart, ...],
+) -> PlacementId:
+    return PlacementId(
+        "sha256:"
+        + _canonical_json_digest(
+            _placement_content(
+                resource_id=resource_id,
+                revision=revision,
+                placement_set_id=placement_set_id,
+                topology=topology,
+                descriptor=descriptor,
+                parts=parts,
+            )
+        )
+    )
+
+
+__all__ = ["KVCachePlacementManifest", "assemble_kv_cache_placement"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/plan_serde.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/plan_serde.py
new file mode 100644
index 0000000000..c1df5bf80d
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/plan_serde.py
@@ -0,0 +1,192 @@
+"""Strict JSON boundary for address-free KV-cache logical plans."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import cast
+
+from ..contracts import ParticipantId
+from .planner import KVCacheLogicalTransferPlan, KVCacheTransferEdge
+from .serde import kv_cache_placement_from_json, kv_cache_placement_to_json
+from .snapshot_serde import kv_cache_snapshot_from_json, kv_cache_snapshot_to_json
+from .types import KVCacheComponent
+
+
+def kv_cache_logical_plan_to_json(plan: KVCacheLogicalTransferPlan) -> str:
+    if not isinstance(plan, KVCacheLogicalTransferPlan):
+        raise ValueError("plan must be a KVCacheLogicalTransferPlan")  # noqa: TRY004
+    return json.dumps(
+        {
+            "source_placement_json": kv_cache_placement_to_json(plan.source_placement),
+            "target_placement_json": kv_cache_placement_to_json(plan.target_placement),
+            "target_participant_id": plan.target_participant_id,
+            "snapshot_json": (
+                kv_cache_snapshot_to_json(plan.snapshot)
+                if plan.snapshot is not None
+                else None
+            ),
+            "plan_id": plan.plan_id,
+            "plan_digest": plan.digest,
+            "edges": [_edge_to_wire(edge) for edge in plan.edges],
+            "expected_writer_ids": list(plan.expected_writer_ids),
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+
+
+def kv_cache_logical_plan_from_json(value: str) -> KVCacheLogicalTransferPlan:
+    payload = _load_json_object(value)
+    expected = {
+        "source_placement_json",
+        "target_placement_json",
+        "target_participant_id",
+        "snapshot_json",
+        "plan_id",
+        "plan_digest",
+        "edges",
+        "expected_writer_ids",
+    }
+    if set(payload) != expected:
+        raise ValueError("KV-cache logical plan fields do not match contract")
+    snapshot_json = _optional_string(payload["snapshot_json"], "snapshot_json")
+    result = KVCacheLogicalTransferPlan(
+        source_placement=kv_cache_placement_from_json(
+            _string(payload["source_placement_json"], "source_placement_json")
+        ),
+        target_placement=kv_cache_placement_from_json(
+            _string(payload["target_placement_json"], "target_placement_json")
+        ),
+        target_participant_id=ParticipantId(
+            _string(payload["target_participant_id"], "target_participant_id")
+        ),
+        edges=tuple(
+            _edge_from_wire(item)
+            for item in _sequence(payload["edges"], "logical plan edges")
+        ),
+        expected_writer_ids=tuple(
+            ParticipantId(_string(item, "expected_writer_id"))
+            for item in _sequence(payload["expected_writer_ids"], "expected_writer_ids")
+        ),
+        snapshot=(
+            kv_cache_snapshot_from_json(snapshot_json)
+            if snapshot_json is not None
+            else None
+        ),
+    )
+    if result.plan_id != _string(payload["plan_id"], "plan_id"):
+        raise ValueError("KV-cache logical plan ID does not match semantic content")
+    if result.digest != _string(payload["plan_digest"], "plan_digest"):
+        raise ValueError("KV-cache logical plan digest does not match content")
+    return result
+
+
+def _load_json_object(value: str) -> Mapping[str, object]:
+    if type(value) is not str or len(value.encode("utf-8")) > 16 * 1024 * 1024:
+        raise ValueError("KV-cache JSON must be text within the 16 MiB wire limit")
+
+    def reject_constant(constant: str) -> None:
+        raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+    def reject_duplicate_fields(
+        pairs: list[tuple[str, object]],
+    ) -> dict[str, object]:
+        result: dict[str, object] = {}
+        for key, item in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON field: {key}")
+            result[key] = item
+        return result
+
+    try:
+        payload = json.loads(
+            value,
+            parse_constant=reject_constant,
+            object_pairs_hook=reject_duplicate_fields,
+        )
+    except (TypeError, json.JSONDecodeError) as error:
+        raise ValueError("KV-cache logical plan is not valid JSON") from error
+    return _mapping(payload, "KV-cache logical plan")
+
+
+def _edge_to_wire(edge: KVCacheTransferEdge) -> dict[str, object]:
+    return {
+        "source_participant_id": edge.source_participant_id,
+        "target_participant_id": edge.target_participant_id,
+        "global_layer_id": edge.global_layer_id,
+        "component": edge.component.value,
+        "global_head_start": edge.global_head_start,
+        "head_count": edge.head_count,
+        "source_head_offset": edge.source_head_offset,
+        "target_head_offset": edge.target_head_offset,
+        "head_dim": edge.head_dim,
+        "itemsize": edge.itemsize,
+    }
+
+
+def _edge_from_wire(value: object) -> KVCacheTransferEdge:
+    edge = _mapping(value, "KV-cache transfer edge")
+    expected = {
+        "source_participant_id",
+        "target_participant_id",
+        "global_layer_id",
+        "component",
+        "global_head_start",
+        "head_count",
+        "source_head_offset",
+        "target_head_offset",
+        "head_dim",
+        "itemsize",
+    }
+    if set(edge) != expected:
+        raise ValueError("KV-cache transfer edge fields do not match contract")
+    return KVCacheTransferEdge(
+        source_participant_id=ParticipantId(
+            _string(edge["source_participant_id"], "source_participant_id")
+        ),
+        target_participant_id=ParticipantId(
+            _string(edge["target_participant_id"], "target_participant_id")
+        ),
+        global_layer_id=_integer(edge["global_layer_id"], "global_layer_id"),
+        component=KVCacheComponent(_string(edge["component"], "component")),
+        global_head_start=_integer(edge["global_head_start"], "global_head_start"),
+        head_count=_integer(edge["head_count"], "head_count"),
+        source_head_offset=_integer(edge["source_head_offset"], "source_head_offset"),
+        target_head_offset=_integer(edge["target_head_offset"], "target_head_offset"),
+        head_dim=_integer(edge["head_dim"], "head_dim"),
+        itemsize=_integer(edge["itemsize"], "itemsize"),
+    )
+
+
+def _mapping(value: object, label: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be an object")  # noqa: TRY004
+    return cast(Mapping[str, object], value)
+
+
+def _sequence(value: object, label: str) -> Sequence[object]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{label} must be a sequence")  # noqa: TRY004
+    return cast(Sequence[object], value)
+
+
+def _string(value: object, label: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def _optional_string(value: object, label: str) -> str | None:
+    if value is None:
+        return None
+    return _string(value, label)
+
+
+def _integer(value: object, label: str) -> int:
+    if type(value) is not int or value < 0:
+        raise ValueError(f"{label} must be a non-negative integer")
+    return value
+
+
+__all__ = ["kv_cache_logical_plan_from_json", "kv_cache_logical_plan_to_json"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/planner.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/planner.py
new file mode 100644
index 0000000000..8f6f0c165c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/planner.py
@@ -0,0 +1,490 @@
+"""Pure KV topology planning followed by late physical preparation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+from ..contracts import ParticipantId, PlacementId
+from .binding import validate_runtime_binding
+from .part import KVCachePlacementPart
+from .placement import KVCachePlacementManifest
+from .runtime import KVCacheRuntimeBindingManifest
+from .snapshot import KVCacheSnapshotDescriptor, SnapshotId
+from .types import (
+    KVCacheComponent,
+    require_integer,
+    require_manifest_items,
+    require_nonempty_string,
+)
+
+
+@dataclass(frozen=True)
+class KVCacheTransferEdge:
+    source_participant_id: ParticipantId
+    target_participant_id: ParticipantId
+    global_layer_id: int
+    component: KVCacheComponent
+    global_head_start: int
+    head_count: int
+    source_head_offset: int
+    target_head_offset: int
+    head_dim: int
+    itemsize: int
+
+    def __post_init__(self) -> None:
+        for name in ("source_participant_id", "target_participant_id"):
+            require_nonempty_string(getattr(self, name), name)
+        for name in (
+            "global_layer_id",
+            "global_head_start",
+            "source_head_offset",
+            "target_head_offset",
+        ):
+            require_integer(getattr(self, name), name)
+        for name in ("head_count", "head_dim", "itemsize"):
+            require_integer(getattr(self, name), name, minimum=1)
+        if not isinstance(self.component, KVCacheComponent):
+            raise ValueError("component must be a KVCacheComponent")  # noqa: TRY004
+        require_integer(self.inner_bytes, "inner_bytes", minimum=1)
+
+    @property
+    def inner_bytes(self) -> int:
+        return self.head_count * self.head_dim * self.itemsize
+
+
+@dataclass(frozen=True)
+class KVCacheLogicalTransferPlan:
+    source_placement: KVCachePlacementManifest = field(repr=False)
+    target_placement: KVCachePlacementManifest = field(repr=False)
+    target_participant_id: ParticipantId
+    edges: tuple[KVCacheTransferEdge, ...]
+    expected_writer_ids: tuple[ParticipantId, ...] = ()
+    snapshot: KVCacheSnapshotDescriptor | None = field(default=None, repr=False)
+    _plan_id_cache: str | None = field(init=False, repr=False, compare=False)
+    _digest_cache: str | None = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.source_placement, KVCachePlacementManifest):
+            raise ValueError("source_placement is invalid")  # noqa: TRY004
+        if not isinstance(self.target_placement, KVCachePlacementManifest):
+            raise ValueError("target_placement is invalid")  # noqa: TRY004
+        self.target_placement.part(self.target_participant_id)
+        if self.snapshot is not None and not isinstance(
+            self.snapshot, KVCacheSnapshotDescriptor
+        ):
+            raise ValueError("snapshot is invalid")
+        _validate_placement_compatibility(
+            self.source_placement, self.target_placement, self.snapshot
+        )
+        object.__setattr__(
+            self,
+            "edges",
+            require_manifest_items(
+                self.edges, "logical plan edges", KVCacheTransferEdge
+            ),
+        )
+        if not self.edges:
+            raise ValueError("logical transfer plan must contain transfer edges")
+        if any(
+            edge.target_participant_id != self.target_participant_id
+            for edge in self.edges
+        ):
+            raise ValueError("logical plan contains a different target participant")
+        edge_writer_ids = tuple(
+            sorted({edge.source_participant_id for edge in self.edges})
+        )
+        expected = tuple(sorted(self.expected_writer_ids or edge_writer_ids))
+        if not set(edge_writer_ids).issubset(expected):
+            raise ValueError("expected_writer_ids omit an edge writer")
+        object.__setattr__(self, "expected_writer_ids", expected)
+
+        source_dp_ranks = {
+            self.source_placement.part(edge.source_participant_id).rank.dp
+            for edge in self.edges
+        }
+        if len(source_dp_ranks) != 1:
+            raise ValueError(
+                "logical transfer plan must select exactly one source DP replica"
+            )
+        _validate_logical_plan_semantics(self)
+        object.__setattr__(self, "_plan_id_cache", None)
+        object.__setattr__(self, "_digest_cache", None)
+
+    @property
+    def plan_id(self) -> str:
+        plan_id = self._plan_id_cache
+        if plan_id is None:
+            plan_id = f"sha256:{_canonical_json_digest(_logical_plan_content(self))}"
+            object.__setattr__(self, "_plan_id_cache", plan_id)
+        return plan_id
+
+    @property
+    def digest(self) -> str:
+        digest = self._digest_cache
+        if digest is None:
+            content = _logical_plan_content(self)
+            content["plan_id"] = self.plan_id
+            content["snapshot_id"] = (
+                self.snapshot.snapshot_id if self.snapshot is not None else None
+            )
+            content["snapshot_digest"] = (
+                self.snapshot.digest if self.snapshot is not None else None
+            )
+            digest = _canonical_json_digest(content)
+            object.__setattr__(self, "_digest_cache", digest)
+        return digest
+
+    @property
+    def source_dp_rank(self) -> int:
+        source_dp_ranks = {
+            self.source_placement.part(edge.source_participant_id).rank.dp
+            for edge in self.edges
+        }
+        if len(source_dp_ranks) != 1:
+            raise ValueError("logical transfer plan source DP replica is ambiguous")
+        return next(iter(source_dp_ranks))
+
+    @property
+    def target_part(self) -> KVCachePlacementPart:
+        return self.target_placement.part(self.target_participant_id)
+
+    @property
+    def source_participant_ids(self) -> tuple[ParticipantId, ...]:
+        return tuple(sorted({edge.source_participant_id for edge in self.edges}))
+
+    def for_source(self, participant_id: ParticipantId) -> KVCacheLogicalTransferPlan:
+        edges = tuple(
+            edge for edge in self.edges if edge.source_participant_id == participant_id
+        )
+        if not edges:
+            raise ValueError(
+                f"source participant has no transfer edges: {participant_id}"
+            )
+        return KVCacheLogicalTransferPlan(
+            source_placement=self.source_placement,
+            target_placement=self.target_placement,
+            target_participant_id=self.target_participant_id,
+            edges=edges,
+            expected_writer_ids=self.expected_writer_ids,
+            snapshot=self.snapshot,
+        )
+
+
+@dataclass(frozen=True)
+class KVCachePreparedTransferEdge:
+    endpoint: str
+    global_layer_id: int
+    component: KVCacheComponent
+    source_base_address: int
+    source_capacity: int
+    target_base_address: int
+    target_capacity: int
+    source_row_stride: int
+    target_row_stride: int
+    source_head_offset_bytes: int
+    target_head_offset_bytes: int
+    nbytes: int
+
+    @property
+    def is_full_row(self) -> bool:
+        return (
+            self.source_head_offset_bytes == 0
+            and self.target_head_offset_bytes == 0
+            and self.nbytes == self.source_row_stride
+            and self.nbytes == self.target_row_stride
+        )
+
+
+@dataclass(frozen=True)
+class KVCachePreparedTransferPlan:
+    source_placement_id: PlacementId
+    source_placement_digest: str
+    target_placement_id: PlacementId
+    target_placement_digest: str
+    snapshot_id: SnapshotId | None
+    snapshot_digest: str | None
+    page_size: int
+    edges: tuple[KVCachePreparedTransferEdge, ...]
+
+
+def _validate_placement_compatibility(
+    source: KVCachePlacementManifest,
+    target: KVCachePlacementManifest,
+    snapshot: KVCacheSnapshotDescriptor | None,
+) -> None:
+    if source.descriptor.page_size != target.descriptor.page_size:
+        raise ValueError(
+            "source and target page_size differ; page-size repacking is unsupported"
+        )
+    if source.descriptor != target.descriptor:
+        raise ValueError("source and target KV-cache descriptors differ")
+    if snapshot is not None:
+        if source.resource_id != snapshot.resource_id:
+            raise ValueError("source placement resource_id differs from snapshot")
+        if target.resource_id != snapshot.resource_id:
+            raise ValueError("target placement resource_id differs from snapshot")
+
+
+def _build_transfer_edges(
+    source_placement: KVCachePlacementManifest,
+    target: KVCachePlacementPart,
+    source_dp_rank: int,
+) -> tuple[KVCacheTransferEdge, ...]:
+    if len(source_placement.parts) ** 2 * len(target.layer_ids) > 10_000_000:
+        raise ValueError("KV-cache logical planning work limit exceeded")
+    descriptor = source_placement.descriptor
+    edges: list[KVCacheTransferEdge] = []
+    for layer_id in target.layer_ids:
+        head = target.head_start
+        target_end = target.head_start + target.head_count
+        while head < target_end:
+            candidates = sorted(
+                (
+                    part
+                    for part in source_placement.parts
+                    if part.rank.dp == source_dp_rank
+                    and layer_id in part.layer_ids
+                    and part.head_start <= head < part.head_start + part.head_count
+                ),
+                key=lambda part: (part.replica_ordinal, part.participant_id),
+            )
+            if not candidates:
+                raise ValueError(
+                    f"source placement misses target layer {layer_id} head {head}"
+                )
+            selected = candidates[target.replica_ordinal % len(candidates)]
+            # Ownership is constant between explicit interval boundaries. Never
+            # iterate across a potentially untrusted total_kv_heads value.
+            run_end = min(
+                [target_end]
+                + [
+                    boundary
+                    for part in source_placement.parts
+                    if part.rank.dp == source_dp_rank and layer_id in part.layer_ids
+                    for boundary in (part.head_start, part.head_start + part.head_count)
+                    if boundary > head
+                ]
+            )
+            if len(edges) + 2 > 100_000:
+                raise ValueError("KV-cache logical plan edge limit exceeded")
+            for component, head_dim in (
+                (KVCacheComponent.KEY, descriptor.key_head_dim),
+                (KVCacheComponent.VALUE, descriptor.value_head_dim),
+            ):
+                edges.append(
+                    KVCacheTransferEdge(
+                        source_participant_id=selected.participant_id,
+                        target_participant_id=target.participant_id,
+                        global_layer_id=layer_id,
+                        component=component,
+                        global_head_start=head,
+                        head_count=run_end - head,
+                        source_head_offset=head - selected.head_start,
+                        target_head_offset=head - target.head_start,
+                        head_dim=head_dim,
+                        itemsize=descriptor.itemsize,
+                    )
+                )
+            head = run_end
+    return tuple(edges)
+
+
+def _validate_logical_plan_semantics(plan: KVCacheLogicalTransferPlan) -> None:
+    canonical_edges = _build_transfer_edges(
+        plan.source_placement,
+        plan.target_part,
+        plan.source_dp_rank,
+    )
+    canonical_writers = tuple(
+        sorted({edge.source_participant_id for edge in canonical_edges})
+    )
+    if plan.expected_writer_ids != canonical_writers:
+        raise ValueError("logical plan expected writers differ from canonical plan")
+    if plan.edges == canonical_edges:
+        return
+    source_ids = plan.source_participant_ids
+    if len(source_ids) != 1:
+        raise ValueError("logical plan edges differ from canonical plan")
+    writer_edges = tuple(
+        edge for edge in canonical_edges if edge.source_participant_id == source_ids[0]
+    )
+    if plan.edges != writer_edges:
+        raise ValueError("writer logical plan edges differ from canonical plan")
+
+
+def _logical_plan_content(plan: KVCacheLogicalTransferPlan) -> dict[str, object]:
+    return {
+        "schema": "kv-cache-logical-plan",
+        "source_placement_id": plan.source_placement.placement_id,
+        "source_placement_digest": plan.source_placement.digest,
+        "target_placement_id": plan.target_placement.placement_id,
+        "target_placement_digest": plan.target_placement.digest,
+        "target_participant_id": plan.target_participant_id,
+        "source_dp_rank": plan.source_dp_rank,
+        "edges": [
+            {
+                "source_participant_id": edge.source_participant_id,
+                "target_participant_id": edge.target_participant_id,
+                "global_layer_id": edge.global_layer_id,
+                "component": edge.component.value,
+                "global_head_start": edge.global_head_start,
+                "head_count": edge.head_count,
+                "source_head_offset": edge.source_head_offset,
+                "target_head_offset": edge.target_head_offset,
+                "head_dim": edge.head_dim,
+                "itemsize": edge.itemsize,
+            }
+            for edge in plan.edges
+        ],
+        "expected_writer_ids": list(plan.expected_writer_ids),
+    }
+
+
+def _canonical_json_digest(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _resolve_source_dp_rank(
+    source_placement: KVCachePlacementManifest,
+    target: KVCachePlacementPart,
+    requested_source_dp_rank: int | None,
+) -> int:
+    available = source_placement.dp_ranks
+    if not available:
+        raise ValueError("source placement contains no DP replica")
+    if requested_source_dp_rank is not None:
+        require_integer(requested_source_dp_rank, "source_dp_rank")
+        if requested_source_dp_rank not in available:
+            raise ValueError(
+                f"source DP rank {requested_source_dp_rank} is absent from placement"
+            )
+        return requested_source_dp_rank
+    # Deterministic balanced default for arbitrary source/target DP sizes.
+    return available[target.rank.dp % len(available)]
+
+
+def plan_kv_cache_transfer_to_local_target(
+    source_placement: KVCachePlacementManifest,
+    target_placement: KVCachePlacementManifest,
+    target_participant_id: ParticipantId,
+    *,
+    source_dp_rank: int | None = None,
+    snapshot: KVCacheSnapshotDescriptor | None = None,
+) -> KVCacheLogicalTransferPlan:
+    """Plan one target participant with optional framework semantic identity."""
+
+    if not isinstance(source_placement, KVCachePlacementManifest):
+        raise TypeError("source_placement must be a KVCachePlacementManifest")
+    if not isinstance(target_placement, KVCachePlacementManifest):
+        raise TypeError("target_placement must be a KVCachePlacementManifest")
+    if snapshot is not None and not isinstance(snapshot, KVCacheSnapshotDescriptor):
+        raise TypeError("snapshot must be a KVCacheSnapshotDescriptor")
+    target = target_placement.part(target_participant_id)
+    _validate_placement_compatibility(source_placement, target_placement, snapshot)
+    selected_source_dp_rank = _resolve_source_dp_rank(
+        source_placement, target, source_dp_rank
+    )
+    return KVCacheLogicalTransferPlan(
+        source_placement=source_placement,
+        target_placement=target_placement,
+        target_participant_id=target.participant_id,
+        edges=_build_transfer_edges(
+            source_placement,
+            target,
+            selected_source_dp_rank,
+        ),
+        snapshot=snapshot,
+    )
+
+
+def prepare_kv_cache_transfer(
+    logical_plan: KVCacheLogicalTransferPlan,
+    source_binding: KVCacheRuntimeBindingManifest,
+    target_binding: KVCacheRuntimeBindingManifest,
+) -> KVCachePreparedTransferPlan:
+    """Validate global placement attestations and compile static edge metadata."""
+
+    if not isinstance(logical_plan, KVCacheLogicalTransferPlan):
+        raise TypeError("logical_plan must be a KVCacheLogicalTransferPlan")
+    source_ids = logical_plan.source_participant_ids
+    if source_ids != (source_binding.participant_id,):
+        raise ValueError("prepare requires a plan restricted to one source participant")
+    if target_binding.participant_id != logical_plan.target_participant_id:
+        raise ValueError("target binding participant differs from logical plan")
+    validate_runtime_binding(
+        logical_plan.source_placement,
+        source_binding,
+        snapshot=logical_plan.snapshot,
+    )
+    validate_runtime_binding(
+        logical_plan.target_placement,
+        target_binding,
+        snapshot=logical_plan.snapshot,
+    )
+
+    source_snapshot = (source_binding.snapshot_id, source_binding.snapshot_digest)
+    target_snapshot = (target_binding.snapshot_id, target_binding.snapshot_digest)
+    if source_snapshot != target_snapshot:
+        raise ValueError("source and target runtime binding snapshot identities differ")
+
+    source_buffers = {
+        (item.global_layer_id, item.component): item.fragment
+        for item in source_binding.buffers
+    }
+    target_buffers = {
+        (item.global_layer_id, item.component): item.fragment
+        for item in target_binding.buffers
+    }
+    endpoint = target_binding.buffers[0].fragment.endpoint
+    prepared_edges: list[KVCachePreparedTransferEdge] = []
+    for edge in logical_plan.edges:
+        key = (edge.global_layer_id, edge.component)
+        source_buffer = source_buffers[key]
+        target_buffer = target_buffers[key]
+        if target_buffer.endpoint != endpoint:
+            raise ValueError("one KV binding must use a single transfer endpoint")
+        prepared_edges.append(
+            KVCachePreparedTransferEdge(
+                endpoint=target_buffer.endpoint,
+                global_layer_id=edge.global_layer_id,
+                component=edge.component,
+                source_base_address=source_buffer.storage_address,
+                source_capacity=source_buffer.storage_nbytes,
+                target_base_address=target_buffer.storage_address,
+                target_capacity=target_buffer.storage_nbytes,
+                source_row_stride=source_buffer.strides_bytes[0],
+                target_row_stride=target_buffer.strides_bytes[0],
+                source_head_offset_bytes=(
+                    source_buffer.storage_offset_bytes
+                    + edge.source_head_offset * source_buffer.strides_bytes[1]
+                ),
+                target_head_offset_bytes=(
+                    target_buffer.storage_offset_bytes
+                    + edge.target_head_offset * target_buffer.strides_bytes[1]
+                ),
+                nbytes=edge.inner_bytes,
+            )
+        )
+    return KVCachePreparedTransferPlan(
+        source_placement_id=logical_plan.source_placement.placement_id,
+        source_placement_digest=logical_plan.source_placement.digest,
+        target_placement_id=logical_plan.target_placement.placement_id,
+        target_placement_digest=logical_plan.target_placement.digest,
+        snapshot_id=source_binding.snapshot_id,
+        snapshot_digest=source_binding.snapshot_digest,
+        page_size=logical_plan.source_placement.descriptor.page_size,
+        edges=tuple(prepared_edges),
+    )
+
+
+__all__ = [
+    "KVCacheLogicalTransferPlan",
+    "KVCachePreparedTransferEdge",
+    "KVCachePreparedTransferPlan",
+    "KVCacheTransferEdge",
+    "plan_kv_cache_transfer_to_local_target",
+    "prepare_kv_cache_transfer",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/resolved.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/resolved.py
new file mode 100644
index 0000000000..ad264dd158
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/resolved.py
@@ -0,0 +1,403 @@
+"""Operation-scoped, framework-neutral logical ranges in registered memory."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from ..contracts import ParticipantId
+from .binding import validate_runtime_binding
+from .placement import KVCachePlacementManifest
+from .runtime import KVCacheRuntimeBindingManifest
+from .snapshot import KVCacheSnapshotDescriptor, _canonical_digest
+from .types import (
+    KVCacheComponent,
+    require_integer,
+    require_manifest_items,
+    require_nonempty_string,
+    require_sha256,
+)
+
+
+@dataclass(frozen=True)
+class KVCacheTransferLimits:
+    max_ranges: int = 100_000
+    max_operations: int = 1_000_000
+    max_bytes: int = 1 << 40
+    max_batch_operations: int = 4096
+    max_batch_bytes: int = 64 << 20
+    max_validation_work: int = 10_000_000
+
+    def __post_init__(self) -> None:
+        for name in self.__dataclass_fields__:
+            require_integer(getattr(self, name), name, minimum=1)
+
+
+DEFAULT_TRANSFER_LIMITS = KVCacheTransferLimits()
+
+
+@dataclass(frozen=True)
+class KVCacheRegisteredRegion:
+    """A runtime attestation of memory registered with the endpoint's TE.
+
+    Registration, pinning and reservation must remain valid until all submitted
+    work is quiescent. This descriptor does not own or register the allocation.
+    """
+
+    region_id: str
+    endpoint: str
+    address: int
+    nbytes: int
+
+    def __post_init__(self) -> None:
+        require_nonempty_string(self.region_id, "region_id")
+        require_nonempty_string(self.endpoint, "endpoint")
+        require_integer(self.address, "region address", minimum=1)
+        require_integer(self.nbytes, "region nbytes", minimum=1)
+        require_integer(self.address + self.nbytes, "region address end")
+
+
+@dataclass(frozen=True)
+class KVCacheResolvedRange:
+    global_layer_id: int
+    component: KVCacheComponent
+    token_start: int
+    token_count: int
+    head_start: int
+    head_count: int
+    region_id: str
+    offset_bytes: int
+    token_stride_bytes: int
+    head_stride_bytes: int
+
+    def __post_init__(self) -> None:
+        for name in ("global_layer_id", "token_start", "head_start", "offset_bytes"):
+            require_integer(getattr(self, name), name)
+        for name in (
+            "token_count",
+            "head_count",
+            "token_stride_bytes",
+            "head_stride_bytes",
+        ):
+            require_integer(getattr(self, name), name, minimum=1)
+        require_integer(self.token_end, "resolved token end")
+        require_integer(self.head_end, "resolved head end")
+        require_nonempty_string(self.region_id, "region_id")
+        if not isinstance(self.component, KVCacheComponent):
+            raise ValueError("component must be a KVCacheComponent")  # noqa: TRY004
+
+    @property
+    def token_end(self) -> int:
+        return self.token_start + self.token_count
+
+    @property
+    def head_end(self) -> int:
+        return self.head_start + self.head_count
+
+    def address(self, region: KVCacheRegisteredRegion, token: int, head: int) -> int:
+        return (
+            region.address
+            + self.offset_bytes
+            + (token - self.token_start) * self.token_stride_bytes
+            + (head - self.head_start) * self.head_stride_bytes
+        )
+
+
+def _range_key(item: KVCacheResolvedRange) -> tuple[int, str, int, int, str, int]:
+    return (
+        item.global_layer_id,
+        item.component.value,
+        item.token_start,
+        item.head_start,
+        item.region_id,
+        item.offset_bytes,
+    )
+
+
+@dataclass(frozen=True)
+class KVCacheResolvedRuntimeBinding:
+    operation_id: str
+    resource_id: str
+    placement_id: str
+    placement_digest: str
+    instance_id: str
+    revision: str
+    participant_id: str
+    snapshot_id: str
+    snapshot_digest: str
+    regions: tuple[KVCacheRegisteredRegion, ...]
+    ranges: tuple[KVCacheResolvedRange, ...]
+
+    def __post_init__(self) -> None:
+        for name in (
+            "operation_id",
+            "resource_id",
+            "placement_id",
+            "instance_id",
+            "revision",
+            "participant_id",
+            "snapshot_id",
+        ):
+            require_nonempty_string(getattr(self, name), name)
+        for name in ("placement_digest", "snapshot_digest"):
+            require_sha256(getattr(self, name), name)
+        regions = require_manifest_items(
+            self.regions, "registered regions", KVCacheRegisteredRegion
+        )
+        ranges = require_manifest_items(
+            self.ranges, "resolved ranges", KVCacheResolvedRange
+        )
+        if not regions or not ranges:
+            raise ValueError("resolved binding must contain regions and ranges")
+        if len({r.region_id for r in regions}) != len(regions):
+            raise ValueError("duplicate registered region_id")
+        if len({r.endpoint for r in regions}) != 1:
+            raise ValueError("one runtime binding must use a single endpoint")
+        object.__setattr__(
+            self, "regions", tuple(sorted(regions, key=lambda r: r.region_id))
+        )
+        object.__setattr__(self, "ranges", tuple(sorted(ranges, key=_range_key)))
+
+    @property
+    def digest(self) -> str:
+        return _canonical_digest(
+            {"schema": "kv-cache-resolved-binding", **asdict(self)}
+        )
+
+
+def _head_bytes(
+    placement: KVCachePlacementManifest, component: KVCacheComponent
+) -> int:
+    d = placement.descriptor
+    return d.itemsize * (
+        d.key_head_dim if component is KVCacheComponent.KEY else d.value_head_dim
+    )
+
+
+def _physical_spans(
+    item: KVCacheResolvedRange,
+    region: KVCacheRegisteredRegion,
+    head_bytes: int,
+    limit: int,
+) -> list[tuple[int, int]]:
+    if limit < 1:
+        raise ValueError("resolved range physical expansion limit exceeded")
+    base = region.address + item.offset_bytes
+    if item.head_stride_bytes == head_bytes:
+        row_bytes = item.head_count * head_bytes
+        if item.token_stride_bytes == row_bytes:
+            return [(base, base + item.token_count * row_bytes)]
+        count = item.token_count
+        width = row_bytes
+    else:
+        count = item.token_count * item.head_count
+        width = head_bytes
+    if count > limit:
+        raise ValueError("resolved range physical expansion limit exceeded")
+    if item.head_stride_bytes == head_bytes:
+        return [
+            (
+                base + t * item.token_stride_bytes,
+                base + t * item.token_stride_bytes + width,
+            )
+            for t in range(item.token_count)
+        ]
+    return [
+        (item.address(region, t, h), item.address(region, t, h) + width)
+        for t in range(item.token_start, item.token_end)
+        for h in range(item.head_start, item.head_end)
+    ]
+
+
+def _check_disjoint(spans: list[tuple[int, int]], label: str) -> None:
+    spans.sort()
+    end = 0
+    for start, stop in spans:
+        if start < end:
+            raise ValueError(f"{label} physical ranges overlap")
+        end = stop
+
+
+def validate_resolved_runtime_binding(
+    placement: KVCachePlacementManifest,
+    snapshot: KVCacheSnapshotDescriptor,
+    binding: KVCacheResolvedRuntimeBinding,
+    *,
+    operation_id: str,
+    limits: KVCacheTransferLimits = DEFAULT_TRANSFER_LIMITS,
+) -> None:
+    """Check identity, exact token/head coverage, strides and registered bounds."""
+    _validated_spans(placement, snapshot, binding, operation_id, limits)
+
+
+def _validated_spans(
+    placement: KVCachePlacementManifest,
+    snapshot: KVCacheSnapshotDescriptor,
+    binding: KVCacheResolvedRuntimeBinding,
+    operation_id: str,
+    limits: KVCacheTransferLimits,
+) -> list[tuple[int, int]]:
+    if not isinstance(binding, KVCacheResolvedRuntimeBinding):
+        raise TypeError("binding must be a KVCacheResolvedRuntimeBinding")
+    if not isinstance(placement, KVCachePlacementManifest):
+        raise TypeError("placement must be a KVCachePlacementManifest")
+    if not isinstance(snapshot, KVCacheSnapshotDescriptor):
+        raise TypeError("snapshot must be a KVCacheSnapshotDescriptor")
+    if not isinstance(limits, KVCacheTransferLimits):
+        raise TypeError("limits must be KVCacheTransferLimits")
+    require_nonempty_string(operation_id, "operation_id")
+    expected = {
+        "operation_id": operation_id,
+        "resource_id": placement.resource_id,
+        "placement_id": placement.placement_id,
+        "placement_digest": placement.digest,
+        "revision": placement.revision,
+        "snapshot_id": snapshot.snapshot_id,
+        "snapshot_digest": snapshot.digest,
+    }
+    for name, value in expected.items():
+        if getattr(binding, name) != value:
+            raise ValueError(f"resolved binding {name} differs")
+    if snapshot.resource_id != placement.resource_id:
+        raise ValueError("snapshot resource_id differs from placement")
+    if len(binding.ranges) > limits.max_ranges:
+        raise ValueError("resolved range count limit exceeded")
+    part = placement.part(ParticipantId(binding.participant_id))
+    regions = {r.region_id: r for r in binding.regions}
+    groups: dict[tuple[int, KVCacheComponent], list[KVCacheResolvedRange]] = {}
+    spans: list[tuple[int, int]] = []
+    for item in binding.ranges:
+        if item.global_layer_id not in part.layer_ids:
+            raise ValueError("resolved range contains an unowned layer")
+        if (
+            not snapshot.token_start
+            <= item.token_start
+            < item.token_end
+            <= snapshot.token_end
+        ):
+            raise ValueError("resolved range is outside snapshot token interval")
+        if (
+            not part.head_start
+            <= item.head_start
+            < item.head_end
+            <= part.head_start + part.head_count
+        ):
+            raise ValueError("resolved range contains unowned heads")
+        if item.region_id not in regions:
+            raise ValueError("resolved range references an unknown registered region")
+        region = regions[item.region_id]
+        head_bytes = _head_bytes(placement, item.component)
+        row_span = (item.head_count - 1) * item.head_stride_bytes + head_bytes
+        if item.head_stride_bytes < head_bytes or item.token_stride_bytes < row_span:
+            raise ValueError("resolved range strides overlap logical values")
+        end = (
+            item.offset_bytes
+            + (item.token_count - 1) * item.token_stride_bytes
+            + row_span
+        )
+        require_integer(end, "resolved byte end")
+        if end > region.nbytes:
+            raise ValueError("resolved range exceeds registered region bounds")
+        if any(
+            v % placement.descriptor.itemsize
+            for v in (
+                region.address + item.offset_bytes,
+                item.token_stride_bytes,
+                item.head_stride_bytes,
+            )
+        ):
+            raise ValueError(
+                "resolved range addresses and strides must be item aligned"
+            )
+        spans.extend(
+            _physical_spans(
+                item, region, head_bytes, limits.max_operations - len(spans)
+            )
+        )
+        groups.setdefault((item.global_layer_id, item.component), []).append(item)
+    _check_disjoint(spans, "binding")
+    expected_keys = {
+        (layer, component) for layer in part.layer_ids for component in KVCacheComponent
+    }
+    if set(groups) != expected_keys:
+        raise ValueError("resolved binding misses layer/component coverage")
+    work = 0
+    for items in groups.values():
+        boundaries = sorted(
+            {snapshot.token_start, snapshot.token_end}
+            | {t for r in items for t in (r.token_start, r.token_end)}
+        )
+        work += len(boundaries) * len(items)
+        if work > limits.max_validation_work:
+            raise ValueError("resolved coverage validation work limit exceeded")
+        for token in boundaries[:-1]:
+            intervals = sorted(
+                (r.head_start, r.head_end)
+                for r in items
+                if r.token_start <= token < r.token_end
+            )
+            head = part.head_start
+            for start, stop in intervals:
+                if start != head:
+                    raise ValueError("resolved logical coverage has a gap or overlap")
+                head = stop
+            if head != part.head_start + part.head_count:
+                raise ValueError("resolved logical coverage is incomplete")
+    return spans
+
+
+def resolve_contiguous_runtime_binding(
+    placement: KVCachePlacementManifest,
+    snapshot: KVCacheSnapshotDescriptor,
+    binding: KVCacheRuntimeBindingManifest,
+    *,
+    operation_id: str,
+    first_token_offset: int = 0,
+) -> KVCacheResolvedRuntimeBinding:
+    """Adapt legacy contiguous buffers; offsets are supplied by the runtime.
+
+    Paged/noncontiguous allocations must export resolved ranges themselves.
+    No framework page IDs or allocation metadata enter Mooncake.
+    """
+    validate_runtime_binding(placement, binding, snapshot=snapshot)
+    require_integer(first_token_offset, "first_token_offset")
+    part = placement.part(ParticipantId(binding.participant_id))
+    regions: list[KVCacheRegisteredRegion] = []
+    ranges: list[KVCacheResolvedRange] = []
+    for item in binding.buffers:
+        f = item.fragment
+        if first_token_offset + snapshot.token_count > f.local_shape[0]:
+            raise ValueError("snapshot exceeds legacy runtime buffer token capacity")
+        regions.append(
+            KVCacheRegisteredRegion(f.fragment_id, f.endpoint, f.address, f.nbytes)
+        )
+        ranges.append(
+            KVCacheResolvedRange(
+                item.global_layer_id,
+                item.component,
+                snapshot.token_start,
+                snapshot.token_count,
+                part.head_start,
+                part.head_count,
+                f.fragment_id,
+                first_token_offset * f.strides_bytes[0],
+                f.strides_bytes[0],
+                f.strides_bytes[1],
+            )
+        )
+    result = KVCacheResolvedRuntimeBinding(
+        operation_id,
+        binding.resource_id,
+        binding.placement_id,
+        binding.placement_digest,
+        binding.instance_id,
+        binding.revision,
+        binding.participant_id,
+        snapshot.snapshot_id,
+        snapshot.digest,
+        tuple(regions),
+        tuple(ranges),
+    )
+    validate_resolved_runtime_binding(
+        placement, snapshot, result, operation_id=operation_id
+    )
+    return result
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime.py
new file mode 100644
index 0000000000..52e182c144
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime.py
@@ -0,0 +1,118 @@
+"""Canonical per-participant KV-cache runtime binding contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..contracts import (
+    ParticipantId,
+    PlacementId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    RuntimeInstanceId,
+)
+from .snapshot import SnapshotId
+from .types import (
+    KVCacheComponent,
+    KVCacheRuntimeBuffer,
+    require_integer,
+    require_manifest_items,
+    require_nonempty_string,
+    require_sha256,
+)
+
+
+@dataclass(frozen=True)
+class KVCacheBufferBinding:
+    global_layer_id: int
+    component: KVCacheComponent
+    fragment: KVCacheRuntimeBuffer
+
+    def __post_init__(self) -> None:
+        require_integer(self.global_layer_id, "global_layer_id")
+        if not isinstance(self.component, KVCacheComponent):
+            raise ValueError("component must be a KVCacheComponent")  # noqa: TRY004
+        if not isinstance(self.fragment, KVCacheRuntimeBuffer):
+            raise ValueError(  # noqa: TRY004
+                "fragment must be a KVCacheRuntimeBuffer"
+            )
+
+
+@dataclass(frozen=True)
+class KVCacheRuntimeBindingManifest:
+    """Operation-scoped physical buffers supplied by their owning runtime."""
+
+    resource_id: ResourceId
+    placement_id: PlacementId
+    placement_digest: str
+    instance_id: RuntimeInstanceId
+    revision: RevisionId
+    participant_id: ParticipantId
+    buffers: tuple[KVCacheBufferBinding, ...]
+    snapshot_id: SnapshotId | None = None
+    snapshot_digest: str | None = None
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        return ResourceKind.KV_CACHE
+
+    def __post_init__(self) -> None:
+        for name in (
+            "resource_id",
+            "placement_id",
+            "instance_id",
+            "revision",
+            "participant_id",
+        ):
+            require_nonempty_string(getattr(self, name), name)
+        require_sha256(self.placement_digest, "placement_digest")
+        if (self.snapshot_id is None) != (self.snapshot_digest is None):
+            raise ValueError(
+                "snapshot_id and snapshot_digest must be provided together"
+            )
+        if self.snapshot_id is not None:
+            require_nonempty_string(self.snapshot_id, "snapshot_id")
+            require_sha256(self.snapshot_digest, "snapshot_digest")
+        buffers = tuple(
+            sorted(
+                require_manifest_items(
+                    self.buffers,
+                    "KVCacheRuntimeBindingManifest buffers",
+                    KVCacheBufferBinding,
+                ),
+                key=lambda item: (item.global_layer_id, item.component.value),
+            )
+        )
+        keys = [(item.global_layer_id, item.component) for item in buffers]
+        if len(keys) != len(set(keys)):
+            raise ValueError("duplicate KV-cache buffer binding")
+        placement_ids = [item.fragment.placement_fragment_id for item in buffers]
+        if len(placement_ids) != len(set(placement_ids)):
+            raise ValueError("duplicate placement fragment in runtime binding")
+        fragment_ids = [item.fragment.fragment_id for item in buffers]
+        if len(fragment_ids) != len(set(fragment_ids)):
+            raise ValueError("duplicate runtime fragment_id in runtime binding")
+        object.__setattr__(self, "buffers", buffers)
+
+    def buffer(
+        self, global_layer_id: int, component: KVCacheComponent
+    ) -> KVCacheBufferBinding:
+        for item in self.buffers:
+            if item.global_layer_id == global_layer_id and item.component is component:
+                return item
+        raise ValueError(
+            f"missing KV-cache buffer: layer={global_layer_id} "
+            f"component={component.value}"
+        )
+
+
+# RFC name; keep the prototype name as a compatibility alias.
+KVCacheRuntimeBinding = KVCacheRuntimeBindingManifest
+
+
+__all__ = [
+    "KVCacheBufferBinding",
+    "KVCacheRuntimeBinding",
+    "KVCacheRuntimeBindingManifest",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime_serde.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime_serde.py
new file mode 100644
index 0000000000..6e4ab0d88b
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/runtime_serde.py
@@ -0,0 +1,179 @@
+"""Strict wire contracts; runtime writes are always reconstructed locally."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, fields
+from typing import Any, TypeVar, cast
+
+from .completion import KVCacheTargetReceipt, KVCacheWriterReceipt
+from .plan_serde import kv_cache_logical_plan_from_json, kv_cache_logical_plan_to_json
+from .resolved import (
+    DEFAULT_TRANSFER_LIMITS,
+    KVCacheRegisteredRegion,
+    KVCacheResolvedRange,
+    KVCacheResolvedRuntimeBinding,
+    KVCacheTransferLimits,
+)
+from .serde import _load_json_object, _require_exact_fields, _sequence, _string
+from .transfer import KVCacheRuntimeTransferPlan
+from .types import KVCacheComponent
+
+_T = TypeVar(
+    "_T",
+    KVCacheRegisteredRegion,
+    KVCacheResolvedRange,
+    KVCacheResolvedRuntimeBinding,
+    KVCacheTransferLimits,
+    KVCacheWriterReceipt,
+    KVCacheTargetReceipt,
+)
+
+
+def _construct(cls: type[_T], value: object) -> _T:
+    data = dict(
+        _require_exact_fields(value, {f.name for f in fields(cls)}, cls.__name__)
+    )
+    if cls is KVCacheResolvedRange:
+        data["component"] = KVCacheComponent(_string(data["component"], "component"))
+    # Field names are allowlisted above; dataclass constructors validate exact
+    # scalar types and nested values. No dynamic class name comes from the wire.
+    return cls(**cast(Any, data))
+
+
+def _dump(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+
+def kv_cache_resolved_binding_to_json(binding: KVCacheResolvedRuntimeBinding) -> str:
+    if not isinstance(binding, KVCacheResolvedRuntimeBinding):
+        raise TypeError("binding must be a KVCacheResolvedRuntimeBinding")
+    return _dump(
+        {
+            "schema": "kv-cache-resolved-binding",
+            "binding": asdict(binding),
+            "digest": binding.digest,
+        }
+    )
+
+
+def kv_cache_resolved_binding_from_json(value: str) -> KVCacheResolvedRuntimeBinding:
+    payload = _require_exact_fields(
+        _load_json_object(value, "resolved binding"),
+        {"schema", "binding", "digest"},
+        "resolved binding",
+    )
+    if payload["schema"] != "kv-cache-resolved-binding":
+        raise ValueError("resolved binding schema differs")
+    data = dict(
+        _require_exact_fields(
+            payload["binding"],
+            {f.name for f in fields(KVCacheResolvedRuntimeBinding)},
+            "resolved binding fields",
+        )
+    )
+    regions = tuple(
+        _construct(KVCacheRegisteredRegion, r)
+        for r in _sequence(data.pop("regions"), "regions")
+    )
+    ranges = tuple(
+        _construct(KVCacheResolvedRange, r)
+        for r in _sequence(data.pop("ranges"), "ranges")
+    )
+    result = KVCacheResolvedRuntimeBinding(
+        **cast(Any, data), regions=regions, ranges=ranges
+    )
+    if result.digest != _string(payload["digest"], "digest"):
+        raise ValueError("resolved binding digest differs")
+    return result
+
+
+def kv_cache_runtime_transfer_to_json(plan: KVCacheRuntimeTransferPlan) -> str:
+    if not isinstance(plan, KVCacheRuntimeTransferPlan):
+        raise TypeError("plan must be a KVCacheRuntimeTransferPlan")
+    return _dump(
+        {
+            "schema": "kv-cache-runtime-transfer",
+            "operation_id": plan.operation_id,
+            "logical_plans": [
+                kv_cache_logical_plan_to_json(p) for p in plan.logical_plans
+            ],
+            "source_bindings": [
+                kv_cache_resolved_binding_to_json(b) for b in plan.source_bindings
+            ],
+            "target_bindings": [
+                kv_cache_resolved_binding_to_json(b) for b in plan.target_bindings
+            ],
+            "limits": asdict(plan.limits),
+            "digest": plan.digest,
+        }
+    )
+
+
+def kv_cache_runtime_transfer_from_json(
+    value: str,
+    *,
+    limits: KVCacheTransferLimits = DEFAULT_TRANSFER_LIMITS,
+) -> KVCacheRuntimeTransferPlan:
+    payload = _require_exact_fields(
+        _load_json_object(value, "runtime transfer"),
+        {
+            "schema",
+            "operation_id",
+            "logical_plans",
+            "source_bindings",
+            "target_bindings",
+            "limits",
+            "digest",
+        },
+        "runtime transfer",
+    )
+    if payload["schema"] != "kv-cache-runtime-transfer":
+        raise ValueError("runtime transfer schema differs")
+    if not isinstance(limits, KVCacheTransferLimits):
+        raise TypeError("limits must be KVCacheTransferLimits")
+    requested_limits = _construct(KVCacheTransferLimits, payload["limits"])
+    if any(
+        getattr(requested_limits, f.name) > getattr(limits, f.name)
+        for f in fields(KVCacheTransferLimits)
+    ):
+        raise ValueError("wire limits exceed receiver policy")
+    result = KVCacheRuntimeTransferPlan(
+        _string(payload["operation_id"], "operation_id"),
+        tuple(
+            kv_cache_logical_plan_from_json(_string(p, "logical plan"))
+            for p in _sequence(payload["logical_plans"], "logical plans")
+        ),
+        tuple(
+            kv_cache_resolved_binding_from_json(_string(b, "source binding"))
+            for b in _sequence(payload["source_bindings"], "source bindings")
+        ),
+        tuple(
+            kv_cache_resolved_binding_from_json(_string(b, "target binding"))
+            for b in _sequence(payload["target_bindings"], "target bindings")
+        ),
+        requested_limits,
+    )
+    if result.digest != _string(payload["digest"], "digest"):
+        raise ValueError("runtime transfer digest differs")
+    return result
+
+
+def kv_cache_writer_receipt_to_json(receipt: KVCacheWriterReceipt) -> str:
+    if not isinstance(receipt, KVCacheWriterReceipt):
+        raise TypeError("receipt must be a KVCacheWriterReceipt")
+    return _dump(asdict(receipt))
+
+
+def kv_cache_writer_receipt_from_json(value: str) -> KVCacheWriterReceipt:
+    return _construct(KVCacheWriterReceipt, _load_json_object(value, "writer receipt"))
+
+
+def kv_cache_target_receipt_to_json(receipt: KVCacheTargetReceipt) -> str:
+    if not isinstance(receipt, KVCacheTargetReceipt):
+        raise TypeError("receipt must be a KVCacheTargetReceipt")
+    return _dump(asdict(receipt))
+
+
+def kv_cache_target_receipt_from_json(value: str) -> KVCacheTargetReceipt:
+    return _construct(KVCacheTargetReceipt, _load_json_object(value, "target receipt"))
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/serde.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/serde.py
new file mode 100644
index 0000000000..a114f5384e
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/serde.py
@@ -0,0 +1,508 @@
+"""Strict JSON boundaries for canonical KV-cache contracts."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+from typing import TypeAlias, cast
+
+from ..contracts import (
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    PlacementSetId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    TopologyId,
+)
+from .part import KVCachePlacementPart
+from .placement import KVCachePlacementManifest
+from .runtime import KVCacheBufferBinding, KVCacheRuntimeBindingManifest
+from .snapshot import SnapshotId
+from .topology import KVCacheTopology, KVCacheTopologyParticipant
+from .types import (
+    KVCacheComponent,
+    KVCacheDescriptor,
+    KVCacheLayout,
+    KVCacheRank,
+    KVCacheRuntimeBuffer,
+)
+
+JsonScalar: TypeAlias = None | bool | int | float | str
+JsonValue: TypeAlias = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = Mapping[str, JsonValue]
+
+
+def kv_cache_part_to_json(part: KVCachePlacementPart) -> str:
+    if not isinstance(part, KVCachePlacementPart):
+        raise ValueError("part must be a KVCachePlacementPart")  # noqa: TRY004
+    return _dump(_part_to_wire(part))
+
+
+def kv_cache_part_from_json(value: str) -> KVCachePlacementPart:
+    return _part_from_wire(_load_json_object(value, "KV-cache placement part"))
+
+
+def kv_cache_placement_to_json(placement: KVCachePlacementManifest) -> str:
+    if not isinstance(placement, KVCachePlacementManifest):
+        raise ValueError(  # noqa: TRY004
+            "placement must be a KVCachePlacementManifest"
+        )
+    return _dump(_placement_to_wire(placement))
+
+
+def kv_cache_placement_from_json(value: str) -> KVCachePlacementManifest:
+    payload = _require_exact_fields(
+        _load_json_object(value, "KV-cache placement"),
+        {
+            "resource_kind",
+            "resource_id",
+            "revision",
+            "placement_set_id",
+            "placement_id",
+            "placement_digest",
+            "topology",
+            "descriptor",
+            "parts",
+        },
+        "KV-cache placement",
+    )
+    _require_resource_kind(payload)
+    topology = _topology_from_wire(payload["topology"])
+    descriptor = _descriptor_from_wire(payload["descriptor"])
+    result = KVCachePlacementManifest(
+        resource_id=ResourceId(_string(payload["resource_id"], "resource_id")),
+        revision=RevisionId(_string(payload["revision"], "revision")),
+        placement_set_id=PlacementSetId(
+            _string(payload["placement_set_id"], "placement_set_id")
+        ),
+        placement_id=PlacementId(_string(payload["placement_id"], "placement_id")),
+        topology=topology,
+        descriptor=descriptor,
+        parts=tuple(
+            _part_from_wire(item)
+            for item in _sequence(payload["parts"], "placement parts")
+        ),
+    )
+    if result.digest != _string(payload["placement_digest"], "placement_digest"):
+        raise ValueError("KV-cache placement digest does not match content")
+    return result
+
+
+def kv_cache_runtime_binding_to_json(
+    binding: KVCacheRuntimeBindingManifest,
+) -> str:
+    if not isinstance(binding, KVCacheRuntimeBindingManifest):
+        raise ValueError(  # noqa: TRY004
+            "binding must be a KVCacheRuntimeBindingManifest"
+        )
+    return _dump(
+        {
+            "resource_kind": binding.resource_kind.value,
+            "resource_id": binding.resource_id,
+            "placement_id": binding.placement_id,
+            "placement_digest": binding.placement_digest,
+            "instance_id": binding.instance_id,
+            "snapshot_id": binding.snapshot_id,
+            "snapshot_digest": binding.snapshot_digest,
+            "revision": binding.revision,
+            "participant_id": binding.participant_id,
+            "buffers": [_buffer_to_wire(item) for item in binding.buffers],
+        }
+    )
+
+
+def kv_cache_runtime_binding_from_json(
+    value: str,
+) -> KVCacheRuntimeBindingManifest:
+    payload = _require_exact_fields(
+        _load_json_object(value, "KV-cache runtime binding"),
+        {
+            "resource_kind",
+            "resource_id",
+            "placement_id",
+            "placement_digest",
+            "instance_id",
+            "snapshot_id",
+            "snapshot_digest",
+            "revision",
+            "participant_id",
+            "buffers",
+        },
+        "KV-cache runtime binding",
+    )
+    _require_resource_kind(payload)
+    return KVCacheRuntimeBindingManifest(
+        resource_id=ResourceId(_string(payload["resource_id"], "resource_id")),
+        placement_id=PlacementId(_string(payload["placement_id"], "placement_id")),
+        placement_digest=_string(payload["placement_digest"], "placement_digest"),
+        instance_id=RuntimeInstanceId(_string(payload["instance_id"], "instance_id")),
+        snapshot_id=_optional_snapshot_id(payload["snapshot_id"]),
+        snapshot_digest=_optional_string(payload["snapshot_digest"], "snapshot_digest"),
+        revision=RevisionId(_string(payload["revision"], "revision")),
+        participant_id=ParticipantId(
+            _string(payload["participant_id"], "participant_id")
+        ),
+        buffers=tuple(
+            _buffer_from_wire(item)
+            for item in _sequence(payload["buffers"], "runtime buffers")
+        ),
+    )
+
+
+def _placement_to_wire(placement: KVCachePlacementManifest) -> dict[str, JsonValue]:
+    return {
+        "resource_kind": placement.resource_kind.value,
+        "resource_id": placement.resource_id,
+        "revision": placement.revision,
+        "placement_set_id": placement.placement_set_id,
+        "placement_id": placement.placement_id,
+        "placement_digest": placement.digest,
+        "topology": _topology_to_wire(placement.topology),
+        "descriptor": _descriptor_to_wire(placement.descriptor),
+        "parts": [_part_to_wire(part) for part in placement.parts],
+    }
+
+
+def _part_to_wire(part: KVCachePlacementPart) -> dict[str, JsonValue]:
+    return {
+        "resource_id": part.resource_id,
+        "revision": part.revision,
+        "placement_set_id": part.placement_set_id,
+        "topology_id": part.topology_id,
+        "participant_id": part.participant_id,
+        "rank": _rank_to_wire(part.rank),
+        "descriptor": _descriptor_to_wire(part.descriptor),
+        "layer_ids": list(part.layer_ids),
+        "head_start": part.head_start,
+        "head_count": part.head_count,
+        "replica_ordinal": part.replica_ordinal,
+        "replica_count": part.replica_count,
+    }
+
+
+def _part_from_wire(value: object) -> KVCachePlacementPart:
+    part = _require_exact_fields(
+        value,
+        {
+            "resource_id",
+            "revision",
+            "placement_set_id",
+            "topology_id",
+            "participant_id",
+            "rank",
+            "descriptor",
+            "layer_ids",
+            "head_start",
+            "head_count",
+            "replica_ordinal",
+            "replica_count",
+        },
+        "KV-cache placement part",
+    )
+    return KVCachePlacementPart(
+        resource_id=ResourceId(_string(part["resource_id"], "resource_id")),
+        revision=RevisionId(_string(part["revision"], "revision")),
+        placement_set_id=PlacementSetId(
+            _string(part["placement_set_id"], "placement_set_id")
+        ),
+        topology_id=TopologyId(_string(part["topology_id"], "topology_id")),
+        participant_id=ParticipantId(_string(part["participant_id"], "participant_id")),
+        rank=_rank_from_wire(part["rank"]),
+        descriptor=_descriptor_from_wire(part["descriptor"]),
+        layer_ids=_integer_tuple(part["layer_ids"], "layer_ids"),
+        head_start=_integer(part["head_start"], "head_start"),
+        head_count=_integer(part["head_count"], "head_count", minimum=1),
+        replica_ordinal=_integer(part["replica_ordinal"], "replica_ordinal"),
+        replica_count=_integer(part["replica_count"], "replica_count", minimum=1),
+    )
+
+
+def _topology_to_wire(topology: KVCacheTopology) -> dict[str, JsonValue]:
+    return {
+        "dp_size": topology.dp_size,
+        "pp_size": topology.pp_size,
+        "tp_size": topology.tp_size,
+        "topology_id": topology.topology_id,
+        "participants": [
+            {
+                "participant_id": item.participant_id,
+                "rank": _rank_to_wire(item.rank),
+            }
+            for item in topology.participants
+        ],
+    }
+
+
+def _topology_from_wire(value: object) -> KVCacheTopology:
+    topology = _require_exact_fields(
+        value,
+        {"dp_size", "pp_size", "tp_size", "topology_id", "participants"},
+        "KV-cache topology",
+    )
+    participants: list[KVCacheTopologyParticipant] = []
+    for item in _sequence(topology["participants"], "topology participants"):
+        participant = _require_exact_fields(
+            item, {"participant_id", "rank"}, "topology participant"
+        )
+        participants.append(
+            KVCacheTopologyParticipant(
+                participant_id=ParticipantId(
+                    _string(participant["participant_id"], "participant_id")
+                ),
+                rank=_rank_from_wire(participant["rank"]),
+            )
+        )
+    return KVCacheTopology(
+        dp_size=_integer(topology["dp_size"], "dp_size", minimum=1),
+        pp_size=_integer(topology["pp_size"], "pp_size", minimum=1),
+        tp_size=_integer(topology["tp_size"], "tp_size", minimum=1),
+        topology_id=TopologyId(_string(topology["topology_id"], "topology_id")),
+        participants=tuple(participants),
+    )
+
+
+def _descriptor_to_wire(descriptor: KVCacheDescriptor) -> dict[str, JsonValue]:
+    return {
+        "global_layer_ids": list(descriptor.global_layer_ids),
+        "dtype": descriptor.dtype,
+        "itemsize": descriptor.itemsize,
+        "page_size": descriptor.page_size,
+        "total_kv_heads": descriptor.total_kv_heads,
+        "key_head_dim": descriptor.key_head_dim,
+        "value_head_dim": descriptor.value_head_dim,
+        "layout": descriptor.layout.value,
+    }
+
+
+def _descriptor_from_wire(value: object) -> KVCacheDescriptor:
+    descriptor = _require_exact_fields(
+        value,
+        {
+            "global_layer_ids",
+            "dtype",
+            "itemsize",
+            "page_size",
+            "total_kv_heads",
+            "key_head_dim",
+            "value_head_dim",
+            "layout",
+        },
+        "KV-cache descriptor",
+    )
+    return KVCacheDescriptor(
+        global_layer_ids=_integer_tuple(
+            descriptor["global_layer_ids"], "global_layer_ids"
+        ),
+        dtype=_string(descriptor["dtype"], "dtype"),
+        itemsize=_integer(descriptor["itemsize"], "itemsize", minimum=1),
+        page_size=_integer(descriptor["page_size"], "page_size", minimum=1),
+        total_kv_heads=_integer(
+            descriptor["total_kv_heads"], "total_kv_heads", minimum=1
+        ),
+        key_head_dim=_integer(descriptor["key_head_dim"], "key_head_dim", minimum=1),
+        value_head_dim=_integer(
+            descriptor["value_head_dim"], "value_head_dim", minimum=1
+        ),
+        layout=KVCacheLayout(_string(descriptor["layout"], "layout")),
+    )
+
+
+def _buffer_to_wire(binding: KVCacheBufferBinding) -> dict[str, JsonValue]:
+    fragment = binding.fragment
+    return {
+        "global_layer_id": binding.global_layer_id,
+        "component": binding.component.value,
+        "fragment": {
+            "placement_fragment_id": fragment.placement_fragment_id,
+            "fragment_id": fragment.fragment_id,
+            "address": fragment.address,
+            "nbytes": fragment.nbytes,
+            "worker_id": fragment.worker_id,
+            "endpoint": fragment.endpoint,
+            "device": fragment.device,
+            "itemsize": fragment.itemsize,
+            "local_shape": list(fragment.local_shape),
+            "strides_bytes": list(fragment.strides_bytes),
+            "storage_address": fragment.storage_address,
+            "storage_nbytes": fragment.storage_nbytes,
+            "storage_offset_bytes": fragment.storage_offset_bytes,
+        },
+    }
+
+
+def _buffer_from_wire(value: object) -> KVCacheBufferBinding:
+    binding = _require_exact_fields(
+        value,
+        {"global_layer_id", "component", "fragment"},
+        "KV-cache buffer binding",
+    )
+    fragment = _require_exact_fields(
+        binding["fragment"],
+        {
+            "placement_fragment_id",
+            "fragment_id",
+            "address",
+            "nbytes",
+            "worker_id",
+            "endpoint",
+            "device",
+            "itemsize",
+            "local_shape",
+            "strides_bytes",
+            "storage_address",
+            "storage_nbytes",
+            "storage_offset_bytes",
+        },
+        "KV-cache runtime buffer",
+    )
+    return KVCacheBufferBinding(
+        global_layer_id=_integer(binding["global_layer_id"], "global_layer_id"),
+        component=KVCacheComponent(_string(binding["component"], "component")),
+        fragment=KVCacheRuntimeBuffer(
+            placement_fragment_id=PlacementFragmentId(
+                _string(fragment["placement_fragment_id"], "placement_fragment_id")
+            ),
+            fragment_id=RuntimeFragmentId(
+                _string(fragment["fragment_id"], "fragment_id")
+            ),
+            address=_integer(fragment["address"], "address", minimum=1),
+            nbytes=_integer(fragment["nbytes"], "nbytes", minimum=1),
+            worker_id=_string(fragment["worker_id"], "worker_id"),
+            endpoint=_string(fragment["endpoint"], "endpoint"),
+            device=_string(fragment["device"], "device"),
+            itemsize=_integer(fragment["itemsize"], "itemsize", minimum=1),
+            local_shape=_integer_tuple(
+                fragment["local_shape"], "local_shape", minimum=1
+            ),
+            strides_bytes=_integer_tuple(fragment["strides_bytes"], "strides_bytes"),
+            storage_address=_integer(
+                fragment["storage_address"], "storage_address", minimum=1
+            ),
+            storage_nbytes=_integer(
+                fragment["storage_nbytes"], "storage_nbytes", minimum=1
+            ),
+            storage_offset_bytes=_integer(
+                fragment["storage_offset_bytes"], "storage_offset_bytes"
+            ),
+        ),
+    )
+
+
+def _rank_to_wire(rank: KVCacheRank) -> dict[str, JsonValue]:
+    return {"dp": rank.dp, "pp": rank.pp, "tp": rank.tp}
+
+
+def _rank_from_wire(value: object) -> KVCacheRank:
+    rank = _require_exact_fields(value, {"dp", "pp", "tp"}, "KV-cache rank")
+    return KVCacheRank(
+        dp=_integer(rank["dp"], "rank dp"),
+        pp=_integer(rank["pp"], "rank pp"),
+        tp=_integer(rank["tp"], "rank tp"),
+    )
+
+
+def _require_resource_kind(payload: JsonObject) -> None:
+    if _string(payload["resource_kind"], "resource_kind") != (
+        ResourceKind.KV_CACHE.value
+    ):
+        raise ValueError("resource_kind must be kv_cache")
+
+
+def _dump(value: JsonValue) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def _load_json_object(value: str, label: str) -> JsonObject:
+    if type(value) is not str or len(value.encode("utf-8")) > 16 * 1024 * 1024:
+        raise ValueError("KV-cache JSON must be text within the 16 MiB wire limit")
+
+    def reject_constant(constant: str) -> None:
+        raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+    def reject_duplicate_fields(
+        pairs: list[tuple[str, object]],
+    ) -> dict[str, JsonValue]:
+        result: dict[str, JsonValue] = {}
+        for key, item in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON field: {key}")
+            result[key] = cast(JsonValue, item)
+        return result
+
+    try:
+        raw = json.loads(
+            value,
+            parse_constant=reject_constant,
+            object_pairs_hook=reject_duplicate_fields,
+        )
+    except (TypeError, json.JSONDecodeError) as error:
+        raise ValueError(f"{label} is not valid JSON") from error
+    return _mapping(cast(object, raw), label)
+
+
+def _mapping(value: object, label: str) -> JsonObject:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be a JSON object")  # noqa: TRY004
+    mapping = cast(Mapping[object, object], value)
+    if any(type(key) is not str for key in mapping):
+        raise ValueError(f"{label} must be a JSON object")
+    return cast(JsonObject, mapping)
+
+
+def _require_exact_fields(
+    value: object, expected: AbstractSet[str], label: str
+) -> JsonObject:
+    mapping = _mapping(value, label)
+    if set(mapping) != set(expected):
+        raise ValueError(f"{label} schema fields do not match contract")
+    return mapping
+
+
+def _sequence(value: object, label: str) -> Sequence[JsonValue]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{label} must be a sequence")  # noqa: TRY004
+    return cast(Sequence[JsonValue], value)
+
+
+def _string(value: object, label: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def _optional_snapshot_id(value: object) -> SnapshotId | None:
+    parsed = _optional_string(value, "snapshot_id")
+    return SnapshotId(parsed) if parsed is not None else None
+
+
+def _optional_string(value: object, label: str) -> str | None:
+    if value is None:
+        return None
+    return _string(value, label)
+
+
+def _integer(value: object, label: str, *, minimum: int = 0) -> int:
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{label} must be an integer at least {minimum}")
+    return value
+
+
+def _integer_tuple(value: object, label: str, *, minimum: int = 0) -> tuple[int, ...]:
+    return tuple(
+        _integer(item, label, minimum=minimum) for item in _sequence(value, label)
+    )
+
+
+__all__ = [
+    "kv_cache_part_from_json",
+    "kv_cache_part_to_json",
+    "kv_cache_placement_from_json",
+    "kv_cache_placement_to_json",
+    "kv_cache_runtime_binding_from_json",
+    "kv_cache_runtime_binding_to_json",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot.py
new file mode 100644
index 0000000000..6109b31824
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot.py
@@ -0,0 +1,138 @@
+"""Framework-provided semantic identity for one KV-cache snapshot."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import NewType
+
+from ..contracts import ResourceId, ResourceKind
+from .types import require_integer, require_nonempty_string, require_sha256
+
+SnapshotId = NewType("SnapshotId", str)
+
+
+@dataclass(frozen=True, init=False)
+class KVCacheSnapshotDescriptor:
+    """Describe what KV content represents, independently of its placement."""
+
+    namespace: str
+    resource_id: ResourceId
+    snapshot_id: SnapshotId
+    model_id: str
+    model_revision: str
+    token_start: int
+    token_count: int
+    token_fingerprint: str
+    semantic_fingerprint: str
+    _digest_cache: str | None = field(init=False, repr=False, compare=False)
+
+    def __init__(
+        self,
+        *,
+        namespace: str,
+        resource_id: ResourceId,
+        model_id: str,
+        model_revision: str,
+        token_start: int,
+        token_count: int,
+        token_fingerprint: str,
+        semantic_fingerprint: str,
+        snapshot_id: SnapshotId | None = None,
+    ) -> None:
+        for value, name in (
+            (namespace, "namespace"),
+            (resource_id, "resource_id"),
+            (model_id, "model_id"),
+            (model_revision, "model_revision"),
+        ):
+            require_nonempty_string(value, name)
+        require_integer(token_start, "token_start")
+        require_integer(token_count, "token_count", minimum=1)
+        require_integer(token_start + token_count, "token_end")
+        require_sha256(token_fingerprint, "token_fingerprint")
+        require_sha256(semantic_fingerprint, "semantic_fingerprint")
+        content = _snapshot_content(
+            namespace=namespace,
+            resource_id=resource_id,
+            model_id=model_id,
+            model_revision=model_revision,
+            token_start=token_start,
+            token_count=token_count,
+            token_fingerprint=token_fingerprint,
+            semantic_fingerprint=semantic_fingerprint,
+        )
+        canonical_id = SnapshotId(f"sha256:{_canonical_digest(content)}")
+        if snapshot_id is not None and snapshot_id != canonical_id:
+            raise ValueError("snapshot_id does not match canonical semantic content")
+        object.__setattr__(self, "namespace", namespace)
+        object.__setattr__(self, "resource_id", resource_id)
+        object.__setattr__(self, "snapshot_id", canonical_id)
+        object.__setattr__(self, "model_id", model_id)
+        object.__setattr__(self, "model_revision", model_revision)
+        object.__setattr__(self, "token_start", token_start)
+        object.__setattr__(self, "token_count", token_count)
+        object.__setattr__(self, "token_fingerprint", token_fingerprint)
+        object.__setattr__(self, "semantic_fingerprint", semantic_fingerprint)
+        object.__setattr__(self, "_digest_cache", None)
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        return ResourceKind.KV_CACHE
+
+    @property
+    def token_end(self) -> int:
+        return self.token_start + self.token_count
+
+    @property
+    def digest(self) -> str:
+        digest = self._digest_cache
+        if digest is None:
+            content = _snapshot_content(
+                namespace=self.namespace,
+                resource_id=self.resource_id,
+                model_id=self.model_id,
+                model_revision=self.model_revision,
+                token_start=self.token_start,
+                token_count=self.token_count,
+                token_fingerprint=self.token_fingerprint,
+                semantic_fingerprint=self.semantic_fingerprint,
+            )
+            content["snapshot_id"] = self.snapshot_id
+            digest = _canonical_digest(content)
+            object.__setattr__(self, "_digest_cache", digest)
+        return digest
+
+
+def _snapshot_content(
+    *,
+    namespace: str,
+    resource_id: ResourceId,
+    model_id: str,
+    model_revision: str,
+    token_start: int,
+    token_count: int,
+    token_fingerprint: str,
+    semantic_fingerprint: str,
+) -> dict[str, object]:
+    return {
+        "schema": "kv-cache-snapshot",
+        "resource_kind": ResourceKind.KV_CACHE.value,
+        "namespace": namespace,
+        "resource_id": resource_id,
+        "model_id": model_id,
+        "model_revision": model_revision,
+        "token_start": token_start,
+        "token_count": token_count,
+        "token_fingerprint": token_fingerprint,
+        "semantic_fingerprint": semantic_fingerprint,
+    }
+
+
+def _canonical_digest(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+__all__ = ["KVCacheSnapshotDescriptor", "SnapshotId"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot_serde.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot_serde.py
new file mode 100644
index 0000000000..59581e2ffa
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/snapshot_serde.py
@@ -0,0 +1,117 @@
+"""Strict JSON boundary for KV-cache snapshot descriptors."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import cast
+
+from ..contracts import ResourceId, ResourceKind
+from .snapshot import KVCacheSnapshotDescriptor, SnapshotId
+
+
+def kv_cache_snapshot_to_json(snapshot: KVCacheSnapshotDescriptor) -> str:
+    if not isinstance(snapshot, KVCacheSnapshotDescriptor):
+        raise ValueError("snapshot must be a KVCacheSnapshotDescriptor")  # noqa: TRY004
+    return json.dumps(
+        {
+            "resource_kind": snapshot.resource_kind.value,
+            "namespace": snapshot.namespace,
+            "resource_id": snapshot.resource_id,
+            "snapshot_id": snapshot.snapshot_id,
+            "snapshot_digest": snapshot.digest,
+            "model_id": snapshot.model_id,
+            "model_revision": snapshot.model_revision,
+            "token_start": snapshot.token_start,
+            "token_count": snapshot.token_count,
+            "token_fingerprint": snapshot.token_fingerprint,
+            "semantic_fingerprint": snapshot.semantic_fingerprint,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+
+
+def kv_cache_snapshot_from_json(value: str) -> KVCacheSnapshotDescriptor:
+    payload = _load_json_object(value)
+    expected = {
+        "resource_kind",
+        "namespace",
+        "resource_id",
+        "snapshot_id",
+        "snapshot_digest",
+        "model_id",
+        "model_revision",
+        "token_start",
+        "token_count",
+        "token_fingerprint",
+        "semantic_fingerprint",
+    }
+    if set(payload) != expected:
+        raise ValueError("KV-cache snapshot fields do not match contract")
+    if (
+        _string(payload["resource_kind"], "resource_kind")
+        != ResourceKind.KV_CACHE.value
+    ):
+        raise ValueError("resource_kind must be kv_cache")
+    snapshot = KVCacheSnapshotDescriptor(
+        namespace=_string(payload["namespace"], "namespace"),
+        resource_id=ResourceId(_string(payload["resource_id"], "resource_id")),
+        snapshot_id=SnapshotId(_string(payload["snapshot_id"], "snapshot_id")),
+        model_id=_string(payload["model_id"], "model_id"),
+        model_revision=_string(payload["model_revision"], "model_revision"),
+        token_start=_integer(payload["token_start"], "token_start"),
+        token_count=_integer(payload["token_count"], "token_count", minimum=1),
+        token_fingerprint=_string(payload["token_fingerprint"], "token_fingerprint"),
+        semantic_fingerprint=_string(
+            payload["semantic_fingerprint"], "semantic_fingerprint"
+        ),
+    )
+    if snapshot.digest != _string(payload["snapshot_digest"], "snapshot_digest"):
+        raise ValueError("KV-cache snapshot digest does not match content")
+    return snapshot
+
+
+def _load_json_object(value: str) -> Mapping[str, object]:
+    if type(value) is not str or len(value.encode("utf-8")) > 16 * 1024 * 1024:
+        raise ValueError("KV-cache JSON must be text within the 16 MiB wire limit")
+
+    def reject_constant(constant: str) -> None:
+        raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+    def reject_duplicate_fields(
+        pairs: list[tuple[str, object]],
+    ) -> dict[str, object]:
+        result: dict[str, object] = {}
+        for key, item in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON field: {key}")
+            result[key] = item
+        return result
+
+    try:
+        payload = json.loads(
+            value,
+            parse_constant=reject_constant,
+            object_pairs_hook=reject_duplicate_fields,
+        )
+    except (TypeError, json.JSONDecodeError) as error:
+        raise ValueError("KV-cache snapshot is not valid JSON") from error
+    if not isinstance(payload, Mapping):
+        raise ValueError("KV-cache snapshot must be an object")  # noqa: TRY004
+    return cast(Mapping[str, object], payload)
+
+
+def _string(value: object, label: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def _integer(value: object, label: str, *, minimum: int = 0) -> int:
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{label} must be an integer of at least {minimum}")
+    return value
+
+
+__all__ = ["kv_cache_snapshot_from_json", "kv_cache_snapshot_to_json"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/topology.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/topology.py
new file mode 100644
index 0000000000..33a66c1bc8
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/topology.py
@@ -0,0 +1,124 @@
+"""Complete participant topology for one KV-cache placement."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+
+from ..contracts import ParticipantId, TopologyId
+from .types import (
+    KVCacheRank,
+    require_integer,
+    require_manifest_items,
+    require_nonempty_string,
+)
+
+
+@dataclass(frozen=True)
+class KVCacheTopologyParticipant:
+    participant_id: ParticipantId
+    rank: KVCacheRank
+
+    def __post_init__(self) -> None:
+        require_nonempty_string(self.participant_id, "participant_id")
+        if not isinstance(self.rank, KVCacheRank):
+            raise ValueError("topology rank must be a KVCacheRank")  # noqa: TRY004
+
+
+@dataclass(frozen=True, init=False)
+class KVCacheTopology:
+    dp_size: int
+    pp_size: int
+    tp_size: int
+    participants: tuple[KVCacheTopologyParticipant, ...]
+    topology_id: TopologyId
+
+    def __init__(
+        self,
+        *,
+        dp_size: int,
+        pp_size: int,
+        tp_size: int,
+        participants: tuple[KVCacheTopologyParticipant, ...],
+        topology_id: TopologyId | None = None,
+    ) -> None:
+        for value, name in (
+            (dp_size, "dp_size"),
+            (pp_size, "pp_size"),
+            (tp_size, "tp_size"),
+        ):
+            require_integer(value, name, minimum=1)
+        normalized = tuple(
+            sorted(
+                require_manifest_items(
+                    participants,
+                    "KVCacheTopology participants",
+                    KVCacheTopologyParticipant,
+                ),
+                key=lambda item: item.participant_id,
+            )
+        )
+        if not normalized:
+            raise ValueError("KV-cache topology participants must not be empty")
+        participant_ids = [item.participant_id for item in normalized]
+        if len(participant_ids) != len(set(participant_ids)):
+            raise ValueError("duplicate topology participant_id")
+        ranks = [item.rank for item in normalized]
+        if len(ranks) != len(set(ranks)):
+            raise ValueError("duplicate topology parallel rank")
+        for participant in normalized:
+            for axis, size in (
+                ("dp", dp_size),
+                ("pp", pp_size),
+                ("tp", tp_size),
+            ):
+                if getattr(participant.rank, axis) >= size:
+                    raise ValueError(
+                        f"{axis} rank is out of range for participant "
+                        f"{participant.participant_id}"
+                    )
+        canonical = _topology_id(
+            dp_size=dp_size,
+            pp_size=pp_size,
+            tp_size=tp_size,
+            participants=normalized,
+        )
+        if topology_id is not None and topology_id != canonical:
+            raise ValueError("topology_id does not match canonical topology")
+        object.__setattr__(self, "dp_size", dp_size)
+        object.__setattr__(self, "pp_size", pp_size)
+        object.__setattr__(self, "tp_size", tp_size)
+        object.__setattr__(self, "participants", normalized)
+        object.__setattr__(self, "topology_id", canonical)
+
+    @property
+    def world_size(self) -> int:
+        return len(self.participants)
+
+    def participant(self, participant_id: ParticipantId) -> KVCacheTopologyParticipant:
+        for participant in self.participants:
+            if participant.participant_id == participant_id:
+                return participant
+        raise ValueError(f"unknown topology participant: {participant_id}")
+
+
+def _topology_id(
+    *,
+    dp_size: int,
+    pp_size: int,
+    tp_size: int,
+    participants: tuple[KVCacheTopologyParticipant, ...],
+) -> TopologyId:
+    content = {
+        "schema": "kv-cache-topology",
+        "dp_size": dp_size,
+        "pp_size": pp_size,
+        "tp_size": tp_size,
+        "participants": [asdict(item) for item in participants],
+    }
+    encoded = json.dumps(content, sort_keys=True, separators=(",", ":")).encode()
+    return TopologyId(f"sha256:{hashlib.sha256(encoded).hexdigest()}")
+
+
+__all__ = ["KVCacheTopology", "KVCacheTopologyParticipant"]
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/transfer.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/transfer.py
new file mode 100644
index 0000000000..5ba7dd2ebe
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/transfer.py
@@ -0,0 +1,309 @@
+"""Bounded lowering of complete runtime-to-runtime operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from .planner import KVCacheLogicalTransferPlan, _build_transfer_edges
+from .resolved import (
+    KVCacheResolvedRuntimeBinding,
+    KVCacheTransferLimits,
+    _check_disjoint,
+    _validated_spans,
+)
+from .snapshot import _canonical_digest
+from .types import require_manifest_items, require_nonempty_string
+
+
+@dataclass(frozen=True)
+class KVCacheWrite:
+    source_participant_id: str
+    target_participant_id: str
+    endpoint: str
+    source_address: int
+    target_address: int
+    nbytes: int
+
+
+@dataclass(frozen=True)
+class KVCacheRuntimeTransferPlan:
+    """One immutable operation covering every nonempty target participant.
+
+    Physical writes are derived here, never accepted from a wire payload.
+    Source bindings contain exactly the selected writers. Target bindings and
+    logical plans contain every nonempty participant of the target placement.
+    """
+
+    operation_id: str
+    logical_plans: tuple[KVCacheLogicalTransferPlan, ...]
+    source_bindings: tuple[KVCacheResolvedRuntimeBinding, ...]
+    target_bindings: tuple[KVCacheResolvedRuntimeBinding, ...]
+    limits: KVCacheTransferLimits = field(default_factory=KVCacheTransferLimits)
+    writes: tuple[KVCacheWrite, ...] = field(init=False)
+    digest: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        require_nonempty_string(self.operation_id, "operation_id")
+        if not isinstance(self.limits, KVCacheTransferLimits):
+            raise TypeError("limits must be KVCacheTransferLimits")
+        plans = require_manifest_items(
+            self.logical_plans, "logical plans", KVCacheLogicalTransferPlan
+        )
+        if not plans:
+            raise ValueError("runtime operation must contain logical plans")
+        # Revalidate every edge at the execution boundary, including in-process
+        # callers. A writer-filtered plan cannot attest complete target coverage.
+        plans = tuple(
+            sorted((replace(p) for p in plans), key=lambda p: p.target_participant_id)
+        )
+        first = plans[0]
+        if first.snapshot is None:
+            raise ValueError("runtime execution requires an explicit snapshot")
+        targets = tuple(p.target_participant_id for p in plans)
+        expected_targets = tuple(
+            sorted(
+                p.participant_id for p in first.target_placement.parts if p.layer_ids
+            )
+        )
+        if targets != expected_targets:
+            raise ValueError(
+                "runtime operation must cover every target participant exactly once"
+            )
+        for plan in plans:
+            if (
+                plan.source_placement.digest != first.source_placement.digest
+                or plan.target_placement.digest != first.target_placement.digest
+                or plan.snapshot != first.snapshot
+            ):
+                raise ValueError(
+                    "runtime operation plans disagree on placement or snapshot"
+                )
+            if plan.edges != _build_transfer_edges(
+                plan.source_placement, plan.target_part, plan.source_dp_rank
+            ):
+                raise ValueError(
+                    "runtime execution requires complete local-target plans"
+                )
+        source_ids: set[str] = {
+            writer for p in plans for writer in p.expected_writer_ids
+        }
+        sources = _bindings(self.source_bindings, source_ids, "source")
+        bindings = _bindings(self.target_bindings, set(targets), "target")
+        all_spans: dict[str, list[tuple[int, int]]] = {}
+        span_count = 0
+        endpoint_instances: dict[str, str] = {}
+        instance_endpoints: dict[str, str] = {}
+        for placement, items in (
+            (first.source_placement, sources),
+            (first.target_placement, bindings),
+        ):
+            for binding in items:
+                if span_count >= self.limits.max_operations:
+                    raise ValueError("runtime validation expansion limit exceeded")
+                spans = _validated_spans(
+                    placement,
+                    first.snapshot,
+                    binding,
+                    self.operation_id,
+                    replace(
+                        self.limits,
+                        max_operations=self.limits.max_operations - span_count,
+                    ),
+                )
+                span_count += len(spans)
+                endpoint = binding.regions[0].endpoint
+                if (
+                    endpoint_instances.setdefault(endpoint, binding.instance_id)
+                    != binding.instance_id
+                ):
+                    raise ValueError(
+                        "one endpoint cannot represent different runtime instances"
+                    )
+                if (
+                    instance_endpoints.setdefault(binding.instance_id, endpoint)
+                    != endpoint
+                ):
+                    raise ValueError("one runtime instance must use one endpoint")
+                current = all_spans.setdefault(binding.instance_id, [])
+                if len(current) + len(spans) > self.limits.max_operations:
+                    raise ValueError(
+                        "shared-instance validation expansion limit exceeded"
+                    )
+                current.extend(spans)
+        for spans in all_spans.values():
+            _check_disjoint(spans, "shared runtime instance")
+        object.__setattr__(self, "logical_plans", plans)
+        object.__setattr__(self, "source_bindings", sources)
+        object.__setattr__(self, "target_bindings", bindings)
+        object.__setattr__(
+            self, "writes", _lower(plans, sources, bindings, self.limits)
+        )
+        object.__setattr__(
+            self,
+            "digest",
+            _canonical_digest(
+                {
+                    "schema": "kv-cache-runtime-transfer",
+                    "operation_id": self.operation_id,
+                    "plans": [p.digest for p in plans],
+                    "sources": [b.digest for b in sources],
+                    "targets": [b.digest for b in bindings],
+                }
+            ),
+        )
+
+    @property
+    def expected_writers(self) -> tuple[tuple[str, str], ...]:
+        return tuple(
+            sorted(
+                (writer, p.target_participant_id)
+                for p in self.logical_plans
+                for writer in p.expected_writer_ids
+            )
+        )
+
+    def writer_bytes(self, writer: str, target: str) -> int:
+        return sum(
+            w.nbytes
+            for w in self.writes
+            if (w.source_participant_id, w.target_participant_id) == (writer, target)
+        )
+
+
+def _bindings(
+    values: object, expected: set[str], label: str
+) -> tuple[KVCacheResolvedRuntimeBinding, ...]:
+    items = require_manifest_items(
+        values, f"{label} bindings", KVCacheResolvedRuntimeBinding
+    )
+    ids = [b.participant_id for b in items]
+    if len(ids) != len(set(ids)) or set(ids) != expected:
+        raise ValueError(f"{label} binding participants differ from selected operation")
+    return tuple(sorted(items, key=lambda b: b.participant_id))
+
+
+def _lower(
+    plans: tuple[KVCacheLogicalTransferPlan, ...],
+    source_bindings: tuple[KVCacheResolvedRuntimeBinding, ...],
+    target_bindings: tuple[KVCacheResolvedRuntimeBinding, ...],
+    limits: KVCacheTransferLimits,
+) -> tuple[KVCacheWrite, ...]:
+    sources = {b.participant_id: b for b in source_bindings}
+    targets = {b.participant_id: b for b in target_bindings}
+    writes: list[KVCacheWrite] = []
+    total_bytes = 0
+    work = 0
+    last_regions: tuple[str, str] | None = None
+
+    def append(
+        writer: str,
+        target: str,
+        endpoint: str,
+        source: int,
+        destination: int,
+        length: int,
+        regions: tuple[str, str],
+    ) -> None:
+        nonlocal total_bytes, last_regions
+        total_bytes += length
+        if total_bytes > limits.max_bytes:
+            raise ValueError("runtime transfer byte limit exceeded")
+        while length:
+            size = min(length, limits.max_batch_bytes)
+            if (
+                writes
+                and last_regions == regions
+                and (
+                    writes[-1].source_participant_id,
+                    writes[-1].target_participant_id,
+                    writes[-1].endpoint,
+                )
+                == (writer, target, endpoint)
+            ):
+                previous = writes[-1]
+                if (
+                    previous.source_address + previous.nbytes == source
+                    and previous.target_address + previous.nbytes == destination
+                    and previous.nbytes + size <= limits.max_batch_bytes
+                ):
+                    writes[-1] = replace(previous, nbytes=previous.nbytes + size)
+                else:
+                    writes.append(
+                        KVCacheWrite(
+                            writer, target, endpoint, source, destination, size
+                        )
+                    )
+            else:
+                writes.append(
+                    KVCacheWrite(writer, target, endpoint, source, destination, size)
+                )
+            if len(writes) > limits.max_operations:
+                raise ValueError("runtime transfer operation limit exceeded")
+            last_regions = regions
+            source += size
+            destination += size
+            length -= size
+
+    for plan in plans:
+        for edge in plan.edges:
+            sb, tb = (
+                sources[edge.source_participant_id],
+                targets[edge.target_participant_id],
+            )
+            sr = {r.region_id: r for r in sb.regions}
+            tr = {r.region_id: r for r in tb.regions}
+            ss = [
+                r
+                for r in sb.ranges
+                if (r.global_layer_id, r.component)
+                == (edge.global_layer_id, edge.component)
+            ]
+            ts = [
+                r
+                for r in tb.ranges
+                if (r.global_layer_id, r.component)
+                == (edge.global_layer_id, edge.component)
+            ]
+            work += len(ss) * len(ts)
+            if work > limits.max_validation_work:
+                raise ValueError("runtime lowering work limit exceeded")
+            for s in ss:
+                for t in ts:
+                    lo = max(s.token_start, t.token_start)
+                    hi = min(s.token_end, t.token_end)
+                    hs = max(s.head_start, t.head_start, edge.global_head_start)
+                    he = min(
+                        s.head_end, t.head_end, edge.global_head_start + edge.head_count
+                    )
+                    if hi <= lo or he <= hs:
+                        continue
+                    width = edge.head_dim * edge.itemsize
+                    contiguous_heads = (
+                        s.head_stride_bytes == t.head_stride_bytes == width
+                    )
+                    if contiguous_heads:
+                        width *= he - hs
+                    contiguous_rows = (
+                        contiguous_heads
+                        and s.token_stride_bytes == t.token_stride_bytes == width
+                    )
+                    count = (
+                        1
+                        if contiguous_rows
+                        else (hi - lo) * (1 if contiguous_heads else he - hs)
+                    )
+                    work += count
+                    if work > limits.max_validation_work:
+                        raise ValueError("runtime lowering expansion limit exceeded")
+                    for token in range(lo, lo + 1 if contiguous_rows else hi):
+                        for head in range(hs, hs + 1 if contiguous_heads else he):
+                            append(
+                                edge.source_participant_id,
+                                edge.target_participant_id,
+                                tr[t.region_id].endpoint,
+                                s.address(sr[s.region_id], token, head),
+                                t.address(tr[t.region_id], token, head),
+                                width * (hi - lo) if contiguous_rows else width,
+                                (s.region_id, t.region_id),
+                            )
+    return tuple(writes)
diff --git a/mooncake-reshard/python/mooncake/reshard/kv_cache/types.py b/mooncake-reshard/python/mooncake/reshard/kv_cache/types.py
new file mode 100644
index 0000000000..7136a4a22c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/kv_cache/types.py
@@ -0,0 +1,190 @@
+"""Canonical KV-cache values shared by placement and runtime contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import TypeVar, cast
+
+from ..contracts import (
+    ParticipantId,
+    PlacementFragmentId,
+    RuntimeBindingFragment,
+)
+
+_MAX_U64 = (1 << 64) - 1
+_T = TypeVar("_T")
+
+
+class KVCacheComponent(str, Enum):
+    KEY = "key"
+    VALUE = "value"
+
+
+class KVCacheLayout(str, Enum):
+    NHD = "nhd"
+
+
+# Preserve the KV-cache public name while sharing the resource-neutral type.
+KVCacheRuntimeBuffer = RuntimeBindingFragment
+
+
+@dataclass(frozen=True)
+class KVCacheRank:
+    """Framework-provided participant coordinates."""
+
+    dp: int = 0
+    pp: int = 0
+    tp: int = 0
+
+    def __post_init__(self) -> None:
+        for name in ("dp", "pp", "tp"):
+            require_integer(getattr(self, name), f"parallel rank {name}")
+
+
+@dataclass(frozen=True)
+class KVCacheDescriptor:
+    """Framework-neutral logical schema shared by one complete placement."""
+
+    global_layer_ids: tuple[int, ...]
+    dtype: str
+    itemsize: int
+    page_size: int
+    total_kv_heads: int
+    key_head_dim: int
+    value_head_dim: int
+    layout: KVCacheLayout = KVCacheLayout.NHD
+
+    def __post_init__(self) -> None:
+        layers = require_integer_tuple(self.global_layer_ids, "global_layer_ids")
+        if not layers:
+            raise ValueError("global_layer_ids must not be empty")
+        if len(layers) != len(set(layers)):
+            raise ValueError("global_layer_ids must be unique")
+        object.__setattr__(self, "global_layer_ids", tuple(sorted(layers)))
+        require_nonempty_string(self.dtype, "dtype")
+        for name in (
+            "itemsize",
+            "page_size",
+            "total_kv_heads",
+            "key_head_dim",
+            "value_head_dim",
+        ):
+            require_integer(getattr(self, name), name, minimum=1)
+        for name in ("key_head_dim", "value_head_dim"):
+            require_integer(
+                getattr(self, name) * self.itemsize, f"{name} byte size", minimum=1
+            )
+        if not isinstance(self.layout, KVCacheLayout):
+            raise ValueError("layout must be a KVCacheLayout")  # noqa: TRY004
+        if self.layout is not KVCacheLayout.NHD:
+            raise ValueError("only NHD KV-cache layout is supported")
+
+
+def placement_fragment_id(
+    participant_id: ParticipantId,
+    global_layer_id: int,
+    component: KVCacheComponent,
+    *,
+    head_start: int,
+    head_count: int,
+) -> PlacementFragmentId:
+    """Derive stable logical buffer identity from canonical placement facts."""
+
+    require_nonempty_string(participant_id, "participant_id")
+    require_integer(global_layer_id, "global_layer_id")
+    require_integer(head_start, "head_start")
+    require_integer(head_count, "head_count", minimum=1)
+    if not isinstance(component, KVCacheComponent):
+        raise ValueError("component must be a KVCacheComponent")  # noqa: TRY004
+    content = {
+        "schema": "kv-cache-placement-fragment",
+        "participant_id": participant_id,
+        "global_layer_id": global_layer_id,
+        "component": component.value,
+        "head_start": head_start,
+        "head_count": head_count,
+    }
+    encoded = json.dumps(content, sort_keys=True, separators=(",", ":")).encode()
+    return PlacementFragmentId(f"sha256:{hashlib.sha256(encoded).hexdigest()}")
+
+
+def canonical_strides_bytes(shape: tuple[int, ...], itemsize: int) -> tuple[int, ...]:
+    strides: list[int] = []
+    running = itemsize
+    for extent in reversed(shape):
+        strides.append(running)
+        running *= extent
+    return tuple(reversed(strides))
+
+
+def require_nonempty_string(value: object, name: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+def require_integer(value: object, name: str, *, minimum: int = 0) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{name} must be an integer")
+    if value < minimum:
+        raise ValueError(f"{name} must be at least {minimum}")
+    if value > _MAX_U64:
+        raise ValueError(f"{name} must fit in an unsigned 64-bit integer")
+    return value
+
+
+def require_integer_tuple(
+    values: object,
+    name: str,
+    *,
+    minimum: int = 0,
+) -> tuple[int, ...]:
+    if isinstance(values, (str, bytes, bytearray)) or not isinstance(values, Sequence):
+        raise ValueError(f"{name} must contain integers")  # noqa: TRY004
+    if len(cast(Sequence[object], values)) > 100_000:
+        raise ValueError(f"{name} exceeds the KV-cache collection limit")
+    items = cast(Sequence[object], values)
+    return tuple(
+        require_integer(value, f"{name}[{index}]", minimum=minimum)
+        for index, value in enumerate(items)
+    )
+
+
+def require_manifest_items(
+    value: object, name: str, item_type: type[_T]
+) -> tuple[_T, ...]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{name} must be a sequence")  # noqa: TRY004
+    if len(cast(Sequence[object], value)) > 100_000:
+        raise ValueError(f"{name} exceeds the KV-cache collection limit")
+    items = tuple(cast(Sequence[object], value))
+    if not all(isinstance(item, item_type) for item in items):
+        raise ValueError(f"{name} must contain {item_type.__name__}")
+    return tuple(cast(_T, item) for item in items)
+
+
+def require_sha256(value: object, name: str) -> str:
+    digest = require_nonempty_string(value, name)
+    if len(digest) != 64 or any(ch not in "0123456789abcdef" for ch in digest):
+        raise ValueError(f"{name} must be a lowercase SHA-256 digest")
+    return digest
+
+
+def descriptor_identity(descriptor: KVCacheDescriptor) -> dict[str, object]:
+    value = asdict(descriptor)
+    value["layout"] = descriptor.layout.value
+    return value
+
+
+__all__ = [
+    "KVCacheComponent",
+    "KVCacheDescriptor",
+    "KVCacheLayout",
+    "KVCacheRank",
+    "KVCacheRuntimeBuffer",
+    "placement_fragment_id",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/lifetime.py b/mooncake-reshard/python/mooncake/reshard/lifetime.py
new file mode 100644
index 0000000000..291efc8c04
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/lifetime.py
@@ -0,0 +1,137 @@
+"""Reusable allocation lifetime contracts.
+
+These objects deliberately stay outside placement manifests and serialized
+plans. Framework adapters own the actual allocator pin; Store and Transfer
+Engine consumers verify the returned fence and release it after completion.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol, Sequence, runtime_checkable
+
+
+class TerminalTransferState(str, Enum):
+    ABORTED = "aborted"
+    COMPLETED = "completed"
+    FAILED_DRAINED = "failed_drained"
+
+
+@dataclass(frozen=True)
+class AllocationFence:
+    """Comparable identity of one framework-pinned runtime allocation scope."""
+
+    resource_id: str
+    revision: str
+    placement_id: str
+    placement_digest: str
+    instance_id: str
+    participant_id: str
+    runtime_lease_id: str
+    runtime_generation: int
+    binding_digest: str
+    fragment_ids: tuple[str, ...]
+    token_id: str
+
+    def __post_init__(self) -> None:
+        for name in (
+            "resource_id",
+            "revision",
+            "placement_id",
+            "placement_digest",
+            "instance_id",
+            "participant_id",
+            "runtime_lease_id",
+            "binding_digest",
+            "token_id",
+        ):
+            value = getattr(self, name)
+            if type(value) is not str or not value:
+                raise ValueError(f"allocation fence {name} must be non-empty")
+        if type(self.runtime_generation) is not int or self.runtime_generation < 0:
+            raise ValueError("allocation fence runtime_generation is invalid")
+        fragment_ids = tuple(self.fragment_ids)
+        if not fragment_ids or any(
+            type(value) is not str or not value for value in fragment_ids
+        ):
+            raise ValueError("allocation fence fragment_ids are invalid")
+        if len(fragment_ids) != len(set(fragment_ids)):
+            raise ValueError("allocation fence fragment_ids contain duplicates")
+        object.__setattr__(self, "fragment_ids", tuple(sorted(fragment_ids)))
+
+
+@runtime_checkable
+class AllocationLifetimeToken(Protocol):
+    """Opaque framework allocation pin retained until a terminal TE outcome."""
+
+    @property
+    def fence(self) -> AllocationFence: ...
+
+    def release_after_terminal(self, terminal_state: TerminalTransferState) -> None: ...
+
+
+@dataclass
+class AllocationTokenSet:
+    """Own a prepared set of allocation pins across normal and pending paths."""
+
+    tokens: tuple[AllocationLifetimeToken, ...]
+    _pending: bool = field(default=False, init=False, repr=False)
+    _released: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self.tokens = tuple(self.tokens)
+        seen_token_ids: set[str] = set()
+        for token in self.tokens:
+            if not isinstance(token, AllocationLifetimeToken):
+                raise ValueError("allocation token has invalid lifetime interface")
+            token_id = token.fence.token_id
+            if token_id in seen_token_ids:
+                raise ValueError("allocation token set contains duplicate token_id")
+            seen_token_ids.add(token_id)
+
+    @property
+    def pending(self) -> bool:
+        return self._pending
+
+    @property
+    def released(self) -> bool:
+        return self._released
+
+    def handoff_to_pending(self) -> tuple[AllocationLifetimeToken, ...]:
+        if self._released:
+            raise RuntimeError("allocation token set was already released")
+        self._pending = True
+        return self.tokens
+
+    def release_after_terminal(self, terminal_state: TerminalTransferState) -> None:
+        if self._pending or self._released:
+            return
+        _release_tokens(self.tokens, terminal_state)
+        self._released = True
+
+
+def release_tokens_after_terminal(
+    tokens: Sequence[AllocationLifetimeToken],
+    terminal_state: TerminalTransferState,
+) -> None:
+    """Release already-acquired pins after registrations are safely cleaned up."""
+
+    _release_tokens(tuple(tokens), terminal_state)
+
+
+def _release_tokens(
+    tokens: Sequence[AllocationLifetimeToken],
+    terminal_state: TerminalTransferState,
+) -> None:
+    for token in reversed(tuple(tokens)):
+        token.release_after_terminal(terminal_state)
+
+
+__all__ = [
+    "AllocationFence",
+    "AllocationLifetimeToken",
+    "AllocationTokenSet",
+    "TerminalTransferState",
+    "release_tokens_after_terminal",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/__init__.py b/mooncake-reshard/python/mooncake/reshard/weight/__init__.py
new file mode 100644
index 0000000000..9ba34aeee8
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/__init__.py
@@ -0,0 +1,109 @@
+"""Public contracts for framework-neutral model-weight resharding."""
+
+from .manifest import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+    validate_runtime_binding,
+    validate_runtime_bindings,
+)
+from .serde import weight_placement_from_json, weight_placement_to_json
+from .planner import (
+    BoundWeightFragment,
+    ExecutableTransferOperation,
+    ExecutorTransferPlan,
+    LiveTransferOperation,
+    LogicalTransferPlan,
+    LogicalTransferOperation,
+    PipelineRouteGroup,
+    PlacementExecutorPlan,
+    PlanningLimits,
+    RuntimeFragmentSnapshot,
+    RuntimeBindingAttestation,
+    RuntimeBindingEvidence,
+    RuntimeTensorOwner,
+    StoredLoadOperation,
+    TransferPlan,
+    TransferRegion,
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+    plan_stored_transfer_to_target_placement,
+    resolve_executor_plan,
+    resolve_executor_plans,
+)
+from .storage_manifest import StoredFragmentSnapshot, StoredWeightManifest
+from ._store import UploadOperation, WeightUploadPlan, plan_weight_upload
+from .store import (
+    StoreRegistrationLease,
+    UploadReceipt,
+    WeightLoadPlan,
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+    WeightStoreWriter,
+    WeightStore,
+    WeightStoreError,
+)
+
+__all__ = [
+    "ParallelRank",
+    "ParallelTopology",
+    "PlacementFragment",
+    "WeightPlacementManifest",
+    "WeightPlacementPart",
+    "RuntimeBindingFragment",
+    "WeightRuntimeBindingManifest",
+    "SplitAxis",
+    "ReplicatedAxis",
+    "OwnershipAxis",
+    "TensorDescriptor",
+    "TopologyParticipant",
+    "validate_runtime_binding",
+    "validate_runtime_bindings",
+    "weight_placement_from_json",
+    "weight_placement_to_json",
+    "StoredFragmentSnapshot",
+    "StoredWeightManifest",
+    "UploadOperation",
+    "UploadReceipt",
+    "StoreRegistrationLease",
+    "WeightLoadPlan",
+    "WeightSnapshotAdapter",
+    "WeightSnapshotDescriptor",
+    "WeightStoreWriter",
+    "WeightStore",
+    "WeightStoreError",
+    "WeightUploadPlan",
+    "plan_weight_upload",
+    "BoundWeightFragment",
+    "ExecutableTransferOperation",
+    "ExecutorTransferPlan",
+    "LiveTransferOperation",
+    "LogicalTransferPlan",
+    "LogicalTransferOperation",
+    "PipelineRouteGroup",
+    "PlacementExecutorPlan",
+    "PlanningLimits",
+    "RuntimeFragmentSnapshot",
+    "RuntimeBindingAttestation",
+    "RuntimeBindingEvidence",
+    "RuntimeTensorOwner",
+    "StoredLoadOperation",
+    "TransferPlan",
+    "TransferRegion",
+    "bind_logical_transfer_plan",
+    "plan_placement_transfer",
+    "plan_placement_transfer_to_local_target",
+    "plan_stored_transfer_to_target_placement",
+    "resolve_executor_plan",
+    "resolve_executor_plans",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_lifetime.py b/mooncake-reshard/python/mooncake/reshard/weight/_lifetime.py
new file mode 100644
index 0000000000..f6fc433e24
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_lifetime.py
@@ -0,0 +1,258 @@
+"""Weight-specific acquisition of framework allocation lifetime guards."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Mapping, Optional, Protocol, Sequence, runtime_checkable
+
+from ..contracts import ParticipantId, RuntimeFragmentId, RuntimeInstanceId
+from ..lifetime import (
+    AllocationFence,
+    AllocationLifetimeToken,
+    AllocationTokenSet,
+    TerminalTransferState,
+)
+from .manifest import RuntimeBindingFragment, WeightRuntimeBindingManifest
+from .planner import TransferPlan
+
+
+@dataclass(frozen=True)
+class AcquiredWeightBinding:
+    """Fresh runtime binding observed while the framework allocation is pinned."""
+
+    binding: WeightRuntimeBindingManifest
+    token: AllocationLifetimeToken
+
+
+@runtime_checkable
+class WeightAllocationGuardProvider(Protocol):
+    """Framework adapter that atomically pins one participant's allocations."""
+
+    def acquire(
+        self,
+        *,
+        transfer_id: str,
+        expected_binding: WeightRuntimeBindingManifest,
+        required_fragment_ids: Sequence[RuntimeFragmentId],
+    ) -> AcquiredWeightBinding: ...
+
+
+GuardProviderKey = tuple[RuntimeInstanceId, ParticipantId]
+WeightAllocationGuardProviders = Mapping[
+    GuardProviderKey, WeightAllocationGuardProvider
+]
+
+
+def acquire_weight_lifetime_tokens(
+    *,
+    transfer_id: str,
+    plan: TransferPlan,
+    bindings: Sequence[WeightRuntimeBindingManifest],
+    side: str,
+    providers: Optional[WeightAllocationGuardProviders],
+) -> tuple[tuple[WeightRuntimeBindingManifest, ...], AllocationTokenSet]:
+    """Acquire pins before using a runtime address or TE registration lease."""
+
+    if side not in ("source", "target"):
+        raise ValueError(f"invalid lifetime side: {side}")
+    if providers is None:
+        raise ValueError(f"{side} allocation guard providers are required")
+    expected_executors = (
+        plan.source_executors if side == "source" else plan.target_executors
+    )
+    required_by_key: dict[GuardProviderKey, tuple[RuntimeFragmentId, ...]] = {}
+    for executor in expected_executors:
+        key = (executor.instance_id, executor.participant_id)
+        existing = required_by_key.get(key, ())
+        required_by_key[key] = tuple(sorted(set((*existing, *executor.fragment_ids))))
+    binding_by_key = {
+        (binding.instance_id, binding.participant_id): binding for binding in bindings
+    }
+    if len(binding_by_key) != len(bindings):
+        raise ValueError(f"duplicate {side} runtime binding participant")
+    if not set(binding_by_key).issubset(required_by_key):
+        raise ValueError(f"{side} runtime binding participants differ from plan")
+
+    acquired_bindings: list[WeightRuntimeBindingManifest] = []
+    tokens: list[AllocationLifetimeToken] = []
+    try:
+        for key in sorted(binding_by_key):
+            provider = providers.get(key)
+            if provider is None or not isinstance(
+                provider, WeightAllocationGuardProvider
+            ):
+                raise ValueError(f"missing {side} allocation guard provider: {key}")
+            expected_binding = binding_by_key[key]
+            required_fragment_ids = required_by_key[key]
+            acquired = provider.acquire(
+                transfer_id=transfer_id,
+                expected_binding=expected_binding,
+                required_fragment_ids=required_fragment_ids,
+            )
+            if not isinstance(acquired, AcquiredWeightBinding):
+                raise ValueError(f"{side} allocation guard returned an invalid binding")
+            fresh_binding = acquired.binding
+            expected_fence = weight_allocation_fence(
+                fresh_binding,
+                required_fragment_ids,
+                token_id=acquired.token.fence.token_id,
+            )
+            if acquired.token.fence != expected_fence:
+                raise ValueError(f"{side} allocation guard fence differs from binding")
+            _validate_acquired_binding(
+                expected_binding, fresh_binding, required_fragment_ids
+            )
+            acquired_bindings.append(fresh_binding)
+            tokens.append(acquired.token)
+    except BaseException:
+        AllocationTokenSet(tuple(tokens)).release_after_terminal(
+            TerminalTransferState.ABORTED
+        )
+        raise
+    return tuple(acquired_bindings), AllocationTokenSet(tuple(tokens))
+
+
+def acquire_weight_binding_token(
+    *,
+    transfer_id: str,
+    expected_binding: WeightRuntimeBindingManifest,
+    required_fragment_ids: Sequence[RuntimeFragmentId],
+    side: str,
+    providers: Optional[WeightAllocationGuardProviders],
+) -> tuple[WeightRuntimeBindingManifest, AllocationTokenSet]:
+    """Acquire one framework pin for synchronous Store or live-TE I/O."""
+
+    if side not in ("source", "target"):
+        raise ValueError(f"invalid lifetime side: {side}")
+    if providers is None:
+        raise ValueError(f"{side} allocation guard providers are required")
+    required = tuple(sorted(set(required_fragment_ids)))
+    if not required:
+        raise ValueError(f"{side} allocation guard requires fragments")
+    key = (expected_binding.instance_id, expected_binding.participant_id)
+    provider = providers.get(key)
+    if provider is None or not isinstance(provider, WeightAllocationGuardProvider):
+        raise ValueError(f"missing {side} allocation guard provider: {key}")
+    acquired = provider.acquire(
+        transfer_id=transfer_id,
+        expected_binding=expected_binding,
+        required_fragment_ids=required,
+    )
+    if not isinstance(acquired, AcquiredWeightBinding):
+        raise ValueError(f"{side} allocation guard returned an invalid binding")
+    try:
+        fresh_binding = acquired.binding
+        expected_fence = weight_allocation_fence(
+            fresh_binding,
+            required,
+            token_id=acquired.token.fence.token_id,
+        )
+        if acquired.token.fence != expected_fence:
+            raise ValueError(f"{side} allocation guard fence differs from binding")
+        _validate_acquired_binding(expected_binding, fresh_binding, required)
+    except BaseException:
+        AllocationTokenSet((acquired.token,)).release_after_terminal(
+            TerminalTransferState.ABORTED
+        )
+        raise
+    return fresh_binding, AllocationTokenSet((acquired.token,))
+
+
+def weight_allocation_fence(
+    binding: WeightRuntimeBindingManifest,
+    required_fragment_ids: Sequence[RuntimeFragmentId],
+    *,
+    token_id: str,
+) -> AllocationFence:
+    fragment_ids = tuple(sorted(required_fragment_ids))
+    fragments_by_id = {fragment.fragment_id: fragment for fragment in binding.fragments}
+    missing = set(fragment_ids) - set(fragments_by_id)
+    if missing:
+        raise ValueError(
+            f"runtime binding is missing guarded fragments: {sorted(missing)}"
+        )
+    return AllocationFence(
+        resource_id=binding.resource_id,
+        revision=binding.revision,
+        placement_id=binding.placement_id,
+        placement_digest=binding.placement_digest,
+        instance_id=binding.instance_id,
+        participant_id=binding.participant_id,
+        runtime_lease_id=binding.lease_id,
+        runtime_generation=binding.generation,
+        binding_digest=_binding_digest(
+            tuple(fragments_by_id[fragment_id] for fragment_id in fragment_ids)
+        ),
+        fragment_ids=fragment_ids,
+        token_id=token_id,
+    )
+
+
+def _validate_acquired_binding(
+    expected: WeightRuntimeBindingManifest,
+    fresh: WeightRuntimeBindingManifest,
+    required_fragment_ids: Sequence[RuntimeFragmentId],
+) -> None:
+    for name in (
+        "resource_id",
+        "revision",
+        "placement_id",
+        "placement_digest",
+        "instance_id",
+        "participant_id",
+        "generation",
+        "lease_id",
+    ):
+        if getattr(expected, name) != getattr(fresh, name):
+            raise ValueError(f"acquired runtime binding {name} differs from plan")
+    expected_by_id = {fragment.fragment_id: fragment for fragment in expected.fragments}
+    fresh_by_id = {fragment.fragment_id: fragment for fragment in fresh.fragments}
+    for fragment_id in required_fragment_ids:
+        expected_fragment = expected_by_id.get(fragment_id)
+        fresh_fragment = fresh_by_id.get(fragment_id)
+        if expected_fragment is None or fresh_fragment is None:
+            raise ValueError("acquired runtime binding fragments differ from plan")
+        if _runtime_fragment_identity(expected_fragment) != _runtime_fragment_identity(
+            fresh_fragment
+        ):
+            raise ValueError("acquired runtime binding address differs from plan")
+
+
+def _binding_digest(fragments: Sequence[RuntimeBindingFragment]) -> str:
+    content = [
+        _runtime_fragment_identity(fragment)
+        for fragment in sorted(fragments, key=lambda item: item.fragment_id)
+    ]
+    return hashlib.sha256(
+        json.dumps(content, separators=(",", ":"), sort_keys=True).encode()
+    ).hexdigest()
+
+
+def _runtime_fragment_identity(fragment: RuntimeBindingFragment) -> dict[str, object]:
+    return {
+        "placement_fragment_id": fragment.placement_fragment_id,
+        "fragment_id": fragment.fragment_id,
+        "address": fragment.address,
+        "nbytes": fragment.nbytes,
+        "worker_id": fragment.worker_id,
+        "endpoint": fragment.endpoint,
+        "device": fragment.device,
+        "itemsize": fragment.itemsize,
+        "local_shape": fragment.local_shape,
+        "strides_bytes": fragment.strides_bytes,
+        "storage_address": fragment.storage_address,
+        "storage_nbytes": fragment.storage_nbytes,
+        "storage_offset_bytes": fragment.storage_offset_bytes,
+    }
+
+
+__all__ = [
+    "AcquiredWeightBinding",
+    "WeightAllocationGuardProvider",
+    "WeightAllocationGuardProviders",
+    "acquire_weight_binding_token",
+    "acquire_weight_lifetime_tokens",
+    "weight_allocation_fence",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/__init__.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/__init__.py
new file mode 100644
index 0000000000..4640b2db6c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/__init__.py
@@ -0,0 +1,55 @@
+from .api import (
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+    plan_stored_transfer_to_target_placement,
+)
+from .binding import (
+    bind_logical_transfer_plan,
+    resolve_executor_plan,
+    resolve_executor_plans,
+)
+from .bound_contracts import ExecutorTransferPlan, RuntimeFragmentSnapshot, TransferPlan
+from .contracts import (
+    BoundWeightFragment,
+    ExecutableTransferOperation,
+    LiveTransferOperation,
+    LogicalTransferPlan,
+    PlanningLimits,
+    LogicalTransferOperation,
+    PipelineRouteGroup,
+    PlacementExecutorPlan,
+    StoredLoadOperation,
+    TransferRegion,
+)
+from .attestation import RuntimeBindingAttestation, RuntimeBindingEvidence
+from .ownership import (
+    complete_parallel_source_replicas,
+    parallel_tensor_owner,
+)
+
+
+__all__ = [
+    "BoundWeightFragment",
+    "ExecutableTransferOperation",
+    "ExecutorTransferPlan",
+    "LiveTransferOperation",
+    "LogicalTransferPlan",
+    "PlanningLimits",
+    "LogicalTransferOperation",
+    "PipelineRouteGroup",
+    "PlacementExecutorPlan",
+    "RuntimeFragmentSnapshot",
+    "RuntimeBindingAttestation",
+    "RuntimeBindingEvidence",
+    "StoredLoadOperation",
+    "TransferPlan",
+    "TransferRegion",
+    "bind_logical_transfer_plan",
+    "complete_parallel_source_replicas",
+    "parallel_tensor_owner",
+    "plan_placement_transfer",
+    "plan_placement_transfer_to_local_target",
+    "plan_stored_transfer_to_target_placement",
+    "resolve_executor_plan",
+    "resolve_executor_plans",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/api.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/api.py
new file mode 100644
index 0000000000..cfe227c3cc
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/api.py
@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ...contracts import ParticipantId
+from ..manifest import WeightPlacementManifest
+from ..storage_manifest import StoredWeightManifest
+from .contracts import LogicalTransferPlan, PlanningLimits
+from .core import (
+    _collect_placements,
+    _logical_transfer_plan,
+    _plan_transfer,
+)
+
+
+def plan_placement_transfer(
+    source_placement: WeightPlacementManifest,
+    target_placement: WeightPlacementManifest,
+    *,
+    planning_limits: Optional[PlanningLimits] = None,
+) -> LogicalTransferPlan:
+    """Plan a reshard between two complete address-free placements."""
+
+    source_tensors, source_fragments = _collect_placements(
+        (source_placement,),
+        "source",
+    )
+    target_tensors, target_fragments = _collect_placements(
+        (target_placement,),
+        "target",
+    )
+    source = source_placement
+    target = target_placement
+    if source.resource_id != target.resource_id:
+        raise ValueError("source and target resource_id differ")
+    if source.revision != target.revision:
+        raise ValueError("source and target revision differ")
+    if source.weight_generation != target.weight_generation:
+        raise ValueError("source and target weight_generation differ")
+    transfer = _plan_transfer(
+        source.resource_id,
+        source.revision,
+        source_tensors,
+        source_fragments,
+        target_tensors,
+        target_fragments,
+        planning_limits=planning_limits,
+    )
+    return _logical_transfer_plan(
+        transfer,
+        source_tensors=source_tensors,
+        target_tensors=target_tensors,
+        source_placement=source_placement,
+        source_manifest=None,
+        target_placement=target_placement,
+    )
+
+
+def plan_placement_transfer_to_local_target(
+    source_placement: WeightPlacementManifest,
+    target_placement: WeightPlacementManifest,
+    target_participant_id: Optional[ParticipantId] = None,
+    *,
+    planning_limits: Optional[PlanningLimits] = None,
+) -> LogicalTransferPlan:
+    """Plan one target executor using address-free source and target layouts."""
+
+    source_tensors, source_fragments = _collect_placements(
+        (source_placement,),
+        "source",
+    )
+    if target_participant_id is None:
+        if target_placement.topology.world_size != 1:
+            raise ValueError(
+                "target_participant_id is required for a multi-participant target"
+            )
+        target_participant_id = target_placement.parts[0].participant_id
+    try:
+        target_part = next(
+            part
+            for part in target_placement.parts
+            if part.participant_id == target_participant_id
+        )
+    except StopIteration as error:
+        raise ValueError(
+            f"unknown target participant: {target_participant_id}"
+        ) from error
+    target_tensors = {tensor.tensor_id: tensor for tensor in target_part.tensors}
+    target_fragments = list(target_part.fragments)
+    source = source_placement
+    if source.resource_id != target_placement.resource_id:
+        raise ValueError("source and target resource_id differ")
+    if source.revision != target_placement.revision:
+        raise ValueError("source and target revision differ")
+    if source.weight_generation != target_placement.weight_generation:
+        raise ValueError("source and target weight_generation differ")
+    transfer = _plan_transfer(
+        source.resource_id,
+        source.revision,
+        source_tensors,
+        source_fragments,
+        target_tensors,
+        target_fragments,
+        local_target=True,
+        planning_limits=planning_limits,
+    )
+    result = _logical_transfer_plan(
+        transfer,
+        source_tensors=source_tensors,
+        target_tensors=target_tensors,
+        source_placement=source_placement,
+        source_manifest=None,
+        target_placement=target_placement,
+        target_participant_ids=frozenset({target_participant_id}),
+    )
+    if len(result.target_executors) != 1:
+        raise ValueError("local target placement must describe exactly one executor")
+    return result
+
+
+def plan_stored_transfer_to_target_placement(
+    source_manifest: StoredWeightManifest,
+    target_placement: WeightPlacementManifest,
+    *,
+    planning_limits: Optional[PlanningLimits] = None,
+) -> LogicalTransferPlan:
+    """Plan a Store-backed transfer into address-free target placements."""
+
+    target_tensors, target_fragments = _collect_placements(
+        (target_placement,),
+        "target",
+    )
+    target = target_placement
+    if source_manifest.resource_id != target.resource_id:
+        raise ValueError("source and target resource_id differ")
+    if source_manifest.revision != target.revision:
+        raise ValueError("source and target revision differ")
+    if source_manifest.weight_generation != target.weight_generation:
+        raise ValueError("source and target weight_generation differ")
+    source_tensors = {tensor.tensor_id: tensor for tensor in source_manifest.tensors}
+    transfer = _plan_transfer(
+        source_manifest.resource_id,
+        source_manifest.revision,
+        source_tensors,
+        source_manifest.fragments,
+        target_tensors,
+        target_fragments,
+        planning_limits=planning_limits,
+    )
+    return _logical_transfer_plan(
+        transfer,
+        source_tensors=source_tensors,
+        target_tensors=target_tensors,
+        source_placement=None,
+        source_manifest=source_manifest,
+        target_placement=target_placement,
+    )
+
+
+__all__ = [
+    "plan_placement_transfer",
+    "plan_placement_transfer_to_local_target",
+    "plan_stored_transfer_to_target_placement",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/attestation.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/attestation.py
new file mode 100644
index 0000000000..8aa71ea65e
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/attestation.py
@@ -0,0 +1,188 @@
+"""Validated runtime-binding provenance for executable reshard plans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from types import MappingProxyType
+from typing import Mapping
+
+from ...contracts import (
+    LeaseId,
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    ResourceId,
+    RevisionId,
+    RuntimeInstanceId,
+)
+from ..binding import validate_runtime_binding
+from ..manifest import (
+    PlacementFragment,
+    RuntimeBindingFragment,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+
+
+@dataclass(frozen=True)
+class RuntimeBindingEvidence:
+    """Allocation-owner-free physical evidence for one runtime binding."""
+
+    resource_id: ResourceId
+    revision: RevisionId
+    placement_id: PlacementId
+    placement_digest: str
+    instance_id: RuntimeInstanceId
+    participant_id: ParticipantId
+    generation: int
+    lease_id: LeaseId
+    fragments: tuple[RuntimeBindingFragment, ...]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "fragments", tuple(self.fragments))
+        if any(fragment.owner is not None for fragment in self.fragments):
+            raise ValueError(
+                "runtime binding evidence must not retain allocation owners"
+            )
+        binding = self.to_binding()
+        object.__setattr__(self, "fragments", binding.fragments)
+
+    @classmethod
+    def from_binding(
+        cls,
+        binding: WeightRuntimeBindingManifest,
+    ) -> RuntimeBindingEvidence:
+        return cls(
+            resource_id=binding.resource_id,
+            revision=binding.revision,
+            placement_id=binding.placement_id,
+            placement_digest=binding.placement_digest,
+            instance_id=binding.instance_id,
+            participant_id=binding.participant_id,
+            generation=binding.generation,
+            lease_id=binding.lease_id,
+            fragments=tuple(
+                replace(fragment, owner=None) for fragment in binding.fragments
+            ),
+        )
+
+    def to_binding(self) -> WeightRuntimeBindingManifest:
+        return WeightRuntimeBindingManifest(
+            resource_id=self.resource_id,
+            revision=self.revision,
+            placement_id=self.placement_id,
+            placement_digest=self.placement_digest,
+            instance_id=self.instance_id,
+            participant_id=self.participant_id,
+            generation=self.generation,
+            lease_id=self.lease_id,
+            fragments=self.fragments,
+        )
+
+
+@dataclass(frozen=True, init=False)
+class RuntimeBindingAttestation:
+    """One validated, allocation-owner-free binding evidence snapshot."""
+
+    placement: WeightPlacementManifest
+    evidence: RuntimeBindingEvidence
+    _placement_by_id: Mapping[PlacementFragmentId, PlacementFragment]
+    _binding_by_id: Mapping[PlacementFragmentId, RuntimeBindingFragment]
+
+    def __init__(
+        self,
+        placement: WeightPlacementManifest,
+        binding: WeightRuntimeBindingManifest,
+    ) -> None:
+        if not isinstance(binding, WeightRuntimeBindingManifest):
+            raise ValueError("runtime attestation binding is invalid")
+        self._set_validated_state(
+            placement,
+            RuntimeBindingEvidence.from_binding(binding),
+        )
+
+    def _set_validated_state(
+        self,
+        placement: WeightPlacementManifest,
+        evidence: RuntimeBindingEvidence,
+    ) -> None:
+        if not isinstance(placement, WeightPlacementManifest):
+            raise ValueError("runtime attestation placement is invalid")
+        if not isinstance(evidence, RuntimeBindingEvidence):
+            raise ValueError("runtime attestation evidence is invalid")
+        if any(fragment.owner is not None for fragment in evidence.fragments):
+            raise ValueError(
+                "runtime binding evidence must not retain allocation owners"
+            )
+        binding = evidence.to_binding()
+        validate_runtime_binding(placement, binding)
+        placement_part = next(
+            part
+            for part in placement.parts
+            if part.participant_id == evidence.participant_id
+        )
+        object.__setattr__(self, "placement", placement)
+        object.__setattr__(self, "evidence", evidence)
+        object.__setattr__(
+            self,
+            "_placement_by_id",
+            MappingProxyType(
+                {item.placement_fragment_id: item for item in placement_part.fragments}
+            ),
+        )
+        object.__setattr__(
+            self,
+            "_binding_by_id",
+            MappingProxyType(
+                {item.placement_fragment_id: item for item in evidence.fragments}
+            ),
+        )
+
+    def validates(
+        self,
+        placement: PlacementFragment,
+        binding: RuntimeBindingFragment,
+    ) -> bool:
+        """Return whether one bound fragment belongs to this exact attestation."""
+
+        placement_id = placement.placement_fragment_id
+        return (
+            self._placement_by_id.get(placement_id) == placement
+            and self._binding_by_id.get(placement_id) == binding
+        )
+
+    def __getstate__(
+        self,
+    ) -> tuple[WeightPlacementManifest, RuntimeBindingEvidence]:
+        """Serialize only canonical inputs; indexes are derived state."""
+
+        return self.placement, self.evidence
+
+    def __setstate__(
+        self,
+        state: tuple[WeightPlacementManifest, RuntimeBindingEvidence],
+    ) -> None:
+        """Revalidate canonical inputs while rebuilding derived indexes."""
+
+        placement, evidence = state
+        self._set_validated_state(placement, evidence)
+
+    def worker_fragment_pairs(
+        self,
+        worker_id: str,
+    ) -> tuple[tuple[PlacementFragment, RuntimeBindingFragment], ...]:
+        """Return the canonical placement/runtime pairs for one worker."""
+
+        return tuple(
+            (self._placement_by_id[item.placement_fragment_id], item)
+            for item in self.evidence.fragments
+            if item.worker_id == worker_id
+        )
+
+    def binding_fragment(
+        self,
+        placement_fragment_id: PlacementFragmentId,
+    ) -> RuntimeBindingFragment:
+        """Return the canonical owner-free evidence for one placement fragment."""
+
+        return self._binding_by_id[placement_fragment_id]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/binding.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/binding.py
new file mode 100644
index 0000000000..f20129ab27
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/binding.py
@@ -0,0 +1,631 @@
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from ...contracts import (
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    RuntimeFragmentId,
+    TensorId,
+)
+from ..binding import _validate_runtime_binding_subset, validate_runtime_binding
+from ..manifest import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+from ..storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredWeightManifest,
+    validate_weight_manifest_snapshot,
+)
+from .bound_contracts import ExecutorTransferPlan, RuntimeFragmentSnapshot, TransferPlan
+from .bound_validation import _validate_target_physical_ranges
+from .contracts import (
+    BoundWeightFragment,
+    ExecutableTransferOperation,
+    LogicalTransferOperation,
+    LogicalTransferPlan,
+    PlacementExecutorPlan,
+    TransferRegion,
+)
+from .core import _collect_placements
+from .attestation import RuntimeBindingAttestation
+from .validation import _validate_logical_target_coverage
+
+
+def _validated_bindings_by_placement_id(
+    placements: Sequence[WeightPlacementManifest],
+    bindings: Sequence[WeightRuntimeBindingManifest],
+    label: str,
+    required_participants: dict[PlacementId, frozenset[ParticipantId]],
+    *,
+    retain_unselected: bool = False,
+) -> dict[tuple[PlacementId, ParticipantId], WeightRuntimeBindingManifest]:
+    if not placements:
+        if bindings:
+            raise ValueError(f"logical plan has no {label} placements")
+        return {}
+    if not bindings:
+        raise ValueError(f"logical plan requires {label} runtime bindings")
+
+    placement_by_id = {placement.placement_id: placement for placement in placements}
+    binding_by_id: dict[
+        tuple[PlacementId, ParticipantId], WeightRuntimeBindingManifest
+    ] = {}
+    runtime_fragment_ids: set[RuntimeFragmentId] = set()
+    for binding in bindings:
+        if not isinstance(binding, WeightRuntimeBindingManifest):
+            raise ValueError(f"invalid {label} runtime binding input")
+        key = (binding.placement_id, binding.participant_id)
+        if key in binding_by_id:
+            raise ValueError(
+                f"duplicate {label} runtime binding participant: "
+                f"{binding.participant_id}"
+            )
+        binding_by_id[key] = binding
+        for fragment in binding.fragments:
+            if fragment.fragment_id in runtime_fragment_ids:
+                raise ValueError(
+                    f"duplicate {label} runtime fragment_id: {fragment.fragment_id}"
+                )
+            runtime_fragment_ids.add(fragment.fragment_id)
+
+    unknown_placements = sorted(
+        {placement_id for placement_id, _ in binding_by_id} - set(placement_by_id)
+    )
+    if unknown_placements:
+        raise ValueError(f"logical plan and {label} placement IDs differ")
+    for placement_id, placement in placement_by_id.items():
+        placement_bindings = tuple(
+            binding
+            for (binding_placement_id, _), binding in binding_by_id.items()
+            if binding_placement_id == placement_id
+        )
+        required = required_participants.get(placement_id, frozenset())
+        actual = {binding.participant_id for binding in placement_bindings}
+        all_participants = {
+            part.participant_id for part in placement.parts if part.fragments
+        }
+        if not required.issubset(actual) or not actual.issubset(all_participants):
+            raise ValueError(
+                f"logical plan and {label} runtime binding participants differ"
+            )
+        _validate_runtime_binding_subset(placement, placement_bindings)
+    if retain_unselected:
+        return binding_by_id
+    return {
+        key: binding
+        for key, binding in binding_by_id.items()
+        if key[1] in required_participants.get(key[0], frozenset())
+    }
+
+
+def _bound_fragment(
+    placement: PlacementFragment,
+    binding: RuntimeBindingFragment,
+    attestation: RuntimeBindingAttestation,
+) -> BoundWeightFragment:
+    evidence = attestation.binding_fragment(placement.placement_fragment_id)
+    return BoundWeightFragment(
+        placement=placement,
+        binding=evidence,
+        instance_id=attestation.evidence.instance_id,
+        runtime_lease_id=attestation.evidence.lease_id,
+        lease_generation=attestation.evidence.generation,
+        owner=None,
+        attestation=attestation,
+    )
+
+
+def _bound_fragments_by_placement_fragment_id(
+    placements: Sequence[WeightPlacementManifest],
+    binding_by_placement_id: dict[
+        tuple[PlacementId, ParticipantId], WeightRuntimeBindingManifest
+    ],
+    label: str,
+) -> dict[PlacementFragmentId, BoundWeightFragment]:
+    result: dict[PlacementFragmentId, BoundWeightFragment] = {}
+    for placement in placements:
+        for part in placement.parts:
+            binding = binding_by_placement_id.get(
+                (placement.placement_id, part.participant_id)
+            )
+            if binding is None:
+                continue
+            attestation = RuntimeBindingAttestation(placement, binding)
+            runtime_by_id = {
+                fragment.placement_fragment_id: fragment
+                for fragment in binding.fragments
+            }
+            for placement_fragment in part.fragments:
+                placement_fragment_id = placement_fragment.placement_fragment_id
+                if placement_fragment_id in result:
+                    raise ValueError(
+                        f"duplicate bound {label} placement fragment: "
+                        f"{placement_fragment_id}"
+                    )
+                result[placement_fragment_id] = _bound_fragment(
+                    placement_fragment,
+                    runtime_by_id[placement_fragment_id],
+                    attestation,
+                )
+    return result
+
+
+def _tensor_map(
+    tensors: Sequence[TensorDescriptor],
+) -> dict[TensorId, TensorDescriptor]:
+    result = {tensor.tensor_id: tensor for tensor in tensors}
+    if len(result) != len(tensors):
+        raise ValueError("logical transfer plan has duplicate tensor descriptors")
+    return result
+
+
+def _validated_store_source_manifest(
+    logical_plan: LogicalTransferPlan,
+    source_manifest: StoredWeightManifest | None,
+) -> StoredWeightManifest | None:
+    if logical_plan.source_manifest is None:
+        if source_manifest is not None:
+            raise ValueError("runtime source plan must not receive a source manifest")
+        return None
+    if source_manifest is None:
+        raise ValueError("stored source plan requires a source manifest")
+    authoritative_manifest = validate_weight_manifest_snapshot(source_manifest)
+    if (
+        logical_plan.source_manifest_identity
+        != authoritative_manifest.manifest_identity
+    ):
+        raise ValueError("logical plan source manifest identity differs")
+    return authoritative_manifest
+
+
+def _validate_logical_tensor_snapshots(
+    logical_plan: LogicalTransferPlan,
+    source_manifest: StoredWeightManifest | None,
+) -> None:
+    source_tensors = _tensor_map(logical_plan.source_tensors)
+    target_tensors = _tensor_map(logical_plan.target_tensors)
+    if logical_plan.source_placement is not None:
+        current_source_tensors, _ = _collect_placements(
+            (logical_plan.source_placement,),
+            "source",
+        )
+        if current_source_tensors != source_tensors:
+            raise ValueError(
+                "logical plan and source placement tensor descriptors differ"
+            )
+    elif source_manifest is not None:
+        current_source_tensors = {
+            tensor.tensor_id: tensor for tensor in source_manifest.tensors
+        }
+        if current_source_tensors != source_tensors:
+            raise ValueError(
+                "logical plan and source manifest tensor descriptors differ"
+            )
+    current_target_tensors, _ = _collect_placements(
+        (logical_plan.target_placement,),
+        "target",
+    )
+    target_participant_ids = {
+        executor.participant_id for executor in logical_plan.target_executors
+    }
+    if target_participant_ids:
+        current_target_tensors = {
+            tensor.tensor_id: tensor
+            for part in logical_plan.target_placement.parts
+            if part.participant_id in target_participant_ids
+            for tensor in part.tensors
+        }
+    if current_target_tensors != target_tensors:
+        raise ValueError("logical plan and target placement tensor descriptors differ")
+
+
+def _validate_logical_fragment_snapshots(
+    logical_plan: LogicalTransferPlan,
+    source_manifest: StoredWeightManifest | None,
+) -> None:
+    logical_plan.validate_source_manifest_snapshot()
+    target_by_id = {
+        fragment.placement_fragment_id: fragment
+        for fragment in logical_plan.target_placement.fragments
+    }
+    source_by_id = (
+        {
+            fragment.placement_fragment_id: fragment
+            for fragment in logical_plan.source_placement.fragments
+        }
+        if logical_plan.source_placement is not None
+        else {}
+    )
+    stored_source_by_id = (
+        {fragment.fragment_id: fragment for fragment in source_manifest.fragments}
+        if source_manifest is not None
+        else {}
+    )
+    for operation in logical_plan.operations:
+        target = operation.target
+        if (
+            not isinstance(target, PlacementFragment)
+            or target_by_id.get(target.placement_fragment_id) != target
+        ):
+            raise ValueError(
+                "logical plan and target placement fragment snapshots differ"
+            )
+        source = operation.source
+        if logical_plan.source_placement is not None and (
+            not isinstance(source, PlacementFragment)
+            or source_by_id.get(source.placement_fragment_id) != source
+        ):
+            raise ValueError(
+                "logical plan and source placement fragment snapshots differ"
+            )
+        if logical_plan.source_manifest is not None and (
+            not isinstance(source, StoredFragmentSnapshot)
+            or stored_source_by_id.get(source.fragment_id) != source
+        ):
+            raise ValueError(
+                "logical plan and source manifest fragment snapshots differ"
+            )
+
+
+def _required_participants(
+    executors: Sequence[PlacementExecutorPlan],
+) -> dict[PlacementId, frozenset[ParticipantId]]:
+    participants: dict[PlacementId, set[ParticipantId]] = {}
+    for executor in executors:
+        participants.setdefault(executor.placement_id, set()).add(
+            executor.participant_id
+        )
+    return {
+        placement_id: frozenset(values) for placement_id, values in participants.items()
+    }
+
+
+def _bind_operation(
+    operation: LogicalTransferOperation,
+    source: Union[BoundWeightFragment, StoredFragmentSnapshot],
+    target: BoundWeightFragment,
+) -> ExecutableTransferOperation:
+    """Rebuild a logical value object with the bound execution fragments."""
+
+    if isinstance(operation, TransferRegion):
+        return TransferRegion(
+            tensor_id=operation.tensor_id,
+            source=source,
+            target=target,
+            overlap_offset=operation.overlap_offset,
+            overlap_shape=operation.overlap_shape,
+            source_base_offset=operation.source_base_offset,
+            target_base_offset=operation.target_base_offset,
+            inner_bytes=operation.inner_bytes,
+            outer_loop_counts=operation.outer_loop_counts,
+            source_strides=operation.source_strides,
+            target_strides=operation.target_strides,
+        )
+    raise ValueError("logical transfer operation is not canonical")
+
+
+def _build_executor_plans(
+    placements: Sequence[WeightPlacementManifest],
+    bindings: Sequence[WeightRuntimeBindingManifest],
+    side: str,
+    *,
+    selected_fragment_ids: frozenset[RuntimeFragmentId] | None = None,
+) -> tuple[ExecutorTransferPlan, ...]:
+    if side not in ("source", "target"):
+        raise ValueError(f"invalid executor side: {side}")
+    binding_by_participant = {
+        (binding.placement_id, binding.participant_id): binding for binding in bindings
+    }
+    if len(binding_by_participant) != len(bindings):
+        raise ValueError(f"duplicate {side} runtime binding participant")
+
+    result: list[ExecutorTransferPlan] = []
+    executor_keys: set[tuple[ParallelRank, str]] = set()
+    observed_selected_fragment_ids: set[RuntimeFragmentId] = set()
+    for placement in placements:
+        for part in placement.parts:
+            binding = binding_by_participant.get(
+                (placement.placement_id, part.participant_id)
+            )
+            if binding is None:
+                continue
+            validate_runtime_binding(placement, binding)
+            attestation = RuntimeBindingAttestation(placement, binding)
+            if not part.fragments:
+                continue
+            runtime_by_placement_fragment_id = {
+                fragment.placement_fragment_id: fragment
+                for fragment in binding.fragments
+            }
+            fragments = [
+                BoundWeightFragment(
+                    placement=placement_fragment,
+                    binding=runtime_by_placement_fragment_id[
+                        placement_fragment.placement_fragment_id
+                    ],
+                    instance_id=binding.instance_id,
+                    runtime_lease_id=binding.lease_id,
+                    lease_generation=binding.generation,
+                    owner=runtime_by_placement_fragment_id[
+                        placement_fragment.placement_fragment_id
+                    ].owner,
+                    attestation=attestation,
+                )
+                for placement_fragment in part.fragments
+                if selected_fragment_ids is None
+                or runtime_by_placement_fragment_id[
+                    placement_fragment.placement_fragment_id
+                ].fragment_id
+                in selected_fragment_ids
+            ]
+            fragments_by_worker: dict[str, list[BoundWeightFragment]] = {}
+            for fragment in fragments:
+                fragments_by_worker.setdefault(fragment.worker_id, []).append(fragment)
+            for worker_id, worker_fragments in sorted(fragments_by_worker.items()):
+                ordered_fragments = sorted(
+                    worker_fragments,
+                    key=lambda fragment: fragment.fragment_id,
+                )
+                executor_key = (part.rank, worker_id)
+                if executor_key in executor_keys:
+                    raise ValueError(
+                        f"duplicate {side} executor rank and worker: {executor_key}"
+                    )
+                executor_keys.add(executor_key)
+                fragment_ids = tuple(
+                    fragment.fragment_id for fragment in ordered_fragments
+                )
+                observed_selected_fragment_ids.update(fragment_ids)
+                result.append(
+                    ExecutorTransferPlan(
+                        instance_id=binding.instance_id,
+                        placement_id=placement.placement_id,
+                        participant_id=part.participant_id,
+                        placement_digest=placement.digest,
+                        runtime_lease_id=binding.lease_id,
+                        worker_id=worker_id,
+                        rank=part.rank,
+                        fragment_ids=fragment_ids,
+                        fragment_snapshots=tuple(
+                            RuntimeFragmentSnapshot.from_fragment(fragment)
+                            for fragment in ordered_fragments
+                        ),
+                        attestation=attestation,
+                    )
+                )
+    result.sort(
+        key=lambda item: (item.rank.dp, item.rank.pp, item.rank.ep, item.rank.tp)
+    )
+    if selected_fragment_ids is not None and observed_selected_fragment_ids != set(
+        selected_fragment_ids
+    ):
+        raise ValueError(f"missing selected {side} runtime fragment")
+    return tuple(result)
+
+
+def _selected_runtime_fragment_ids(
+    operations: Sequence[ExecutableTransferOperation],
+    side: str,
+) -> frozenset[RuntimeFragmentId]:
+    if side not in ("source", "target"):
+        raise ValueError(f"invalid executor side: {side}")
+    selected: set[RuntimeFragmentId] = set()
+    for operation in operations:
+        fragment = operation.source if side == "source" else operation.target
+        if isinstance(fragment, BoundWeightFragment):
+            selected.add(fragment.fragment_id)
+    return frozenset(selected)
+
+
+def bind_logical_transfer_plan(
+    logical_plan: LogicalTransferPlan,
+    target_bindings: Sequence[WeightRuntimeBindingManifest],
+    *,
+    source_bindings: Sequence[WeightRuntimeBindingManifest] = (),
+    source_manifest: StoredWeightManifest | None = None,
+) -> TransferPlan:
+    """Bind an address-free logical plan to validated runtime locations."""
+
+    if not isinstance(logical_plan, LogicalTransferPlan):
+        raise ValueError("logical_plan must be a LogicalTransferPlan")
+    # Re-check the immutable plan contract at the public binding boundary. This
+    # protects deserialized or otherwise reconstructed plan values as well.
+    _validate_logical_target_coverage(logical_plan)
+    authoritative_source_manifest = _validated_store_source_manifest(
+        logical_plan,
+        source_manifest,
+    )
+    _validate_logical_tensor_snapshots(logical_plan, authoritative_source_manifest)
+    _validate_logical_fragment_snapshots(logical_plan, authoritative_source_manifest)
+    target_required = _required_participants(logical_plan.target_executors)
+    source_required = _required_participants(logical_plan.source_executors)
+    target_binding_by_id = _validated_bindings_by_placement_id(
+        (logical_plan.target_placement,),
+        target_bindings,
+        "target",
+        target_required,
+    )
+    source_binding_by_id = _validated_bindings_by_placement_id(
+        (
+            (logical_plan.source_placement,)
+            if logical_plan.source_placement is not None
+            else ()
+        ),
+        source_bindings,
+        "source",
+        source_required,
+    )
+    runtime_targets = _bound_fragments_by_placement_fragment_id(
+        (logical_plan.target_placement,),
+        target_binding_by_id,
+        "target",
+    )
+    runtime_sources = (
+        _bound_fragments_by_placement_fragment_id(
+            (
+                (logical_plan.source_placement,)
+                if logical_plan.source_placement is not None
+                else ()
+            ),
+            source_binding_by_id,
+            "source",
+        )
+        if source_binding_by_id
+        else {}
+    )
+
+    operations: list[ExecutableTransferOperation] = []
+    for operation in logical_plan.operations:
+        placement_source = operation.source
+        placement_target = operation.target
+        if not isinstance(placement_target, PlacementFragment):
+            raise ValueError("logical transfer operation target is runtime-bound")
+        runtime_target = runtime_targets.get(placement_target.placement_fragment_id)
+        if runtime_target is None:
+            raise ValueError(
+                "missing runtime binding for placement fragment: "
+                f"{placement_target.placement_fragment_id}"
+            )
+        if isinstance(placement_source, PlacementFragment):
+            runtime_source = runtime_sources.get(placement_source.placement_fragment_id)
+            if runtime_source is None:
+                raise ValueError(
+                    "missing source runtime binding for placement fragment: "
+                    f"{placement_source.placement_fragment_id}"
+                )
+        elif isinstance(placement_source, StoredFragmentSnapshot):
+            runtime_source = placement_source
+        else:
+            raise ValueError("logical transfer operation source is runtime-bound")
+        operations.append(_bind_operation(operation, runtime_source, runtime_target))
+
+    # Each logical tensor remains an explicit operation. A physical alias may
+    # share an allocation only after the target-range validator proves the same
+    # complete alias group and attested lease scope.
+    bound_operations = tuple(operations)
+    _validate_target_physical_ranges(
+        bound_operations,
+        max_segment_checks=logical_plan.planning_limits.max_total_lowered_segments,
+    )
+    target_binding_values = tuple(target_binding_by_id.values())
+    source_binding_values = tuple(source_binding_by_id.values())
+    source_placements: tuple[WeightPlacementManifest, ...] = ()
+    if source_binding_values:
+        source_placement = logical_plan.source_placement
+        if source_placement is None:
+            raise ValueError("source runtime bindings require a source placement")
+        source_placements = (source_placement,)
+
+    return TransferPlan(
+        resource_id=logical_plan.resource_id,
+        revision=logical_plan.revision,
+        weight_generation=logical_plan.target_placement.weight_generation,
+        target_placement=logical_plan.target_placement,
+        operations=bound_operations,
+        planning_limits=logical_plan.planning_limits,
+        source_manifest=authoritative_source_manifest,
+        source_manifest_identity=logical_plan.source_manifest_identity,
+        source_executors=(
+            _build_executor_plans(
+                source_placements,
+                source_binding_values,
+                "source",
+                selected_fragment_ids=_selected_runtime_fragment_ids(
+                    bound_operations,
+                    "source",
+                ),
+            )
+            if source_binding_values
+            else ()
+        ),
+        target_executors=_build_executor_plans(
+            (logical_plan.target_placement,),
+            target_binding_values,
+            "target",
+            selected_fragment_ids=_selected_runtime_fragment_ids(
+                bound_operations,
+                "target",
+            ),
+        ),
+    )
+
+
+def resolve_executor_plans(
+    plan: TransferPlan,
+    placement: WeightPlacementManifest,
+    binding: WeightRuntimeBindingManifest,
+    side: str,
+) -> tuple[ExecutorTransferPlan, ...]:
+    if side == "source":
+        executors = plan.source_executors
+    elif side == "target":
+        executors = plan.target_executors
+    else:
+        raise ValueError(f"invalid executor side: {side}")
+    if not executors:
+        raise ValueError(f"transfer plan has no {side} executor metadata")
+    if (
+        plan.resource_id != placement.resource_id
+        or plan.revision != placement.revision
+        or plan.weight_generation != placement.weight_generation
+    ):
+        raise ValueError(f"transfer plan identity differs from {side} placement")
+    validate_runtime_binding(placement, binding)
+    expected_executors = tuple(
+        executor
+        for executor in executors
+        if executor.instance_id == binding.instance_id
+        and executor.participant_id == binding.participant_id
+    )
+    if not expected_executors:
+        raise ValueError(f"{side} executor snapshot mismatch: unknown instance")
+    expected_fragment_ids = frozenset(
+        fragment_id
+        for executor in expected_executors
+        for fragment_id in executor.fragment_ids
+    )
+    try:
+        current_executors = _build_executor_plans(
+            (placement,),
+            (binding,),
+            side,
+            selected_fragment_ids=expected_fragment_ids,
+        )
+    except ValueError as error:
+        if str(error) == f"missing selected {side} runtime fragment":
+            raise ValueError(f"{side} executor snapshot mismatch") from error
+        raise
+    executor_keys = [
+        (executor.rank, executor.worker_id) for executor in expected_executors
+    ]
+    if len(executor_keys) != len(set(executor_keys)):
+        raise ValueError(f"{side} executor snapshot has duplicate rank and worker")
+    if current_executors != expected_executors:
+        raise ValueError(f"{side} executor snapshot mismatch")
+    return expected_executors
+
+
+def resolve_executor_plan(
+    plan: TransferPlan,
+    placement: WeightPlacementManifest,
+    binding: WeightRuntimeBindingManifest,
+    side: str,
+) -> ExecutorTransferPlan:
+    executors = resolve_executor_plans(plan, placement, binding, side)
+    if len(executors) != 1:
+        raise ValueError(f"{side} executor snapshot contains multiple ranks")
+    return executors[0]
+
+
+__all__ = [
+    "bind_logical_transfer_plan",
+    "resolve_executor_plan",
+    "resolve_executor_plans",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_contracts.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_contracts.py
new file mode 100644
index 0000000000..1dd99f7d3a
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_contracts.py
@@ -0,0 +1,650 @@
+"""Runtime-bound transfer plan contracts checked against live bindings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar, Optional, cast
+
+from ..._typing import TypeAlias
+from ...contracts import (
+    LeaseId,
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    ResourceId,
+    RevisionId,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    StoredFragmentSnapshotId,
+    TensorId,
+)
+from ..manifest import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    WeightPlacementManifest,
+)
+from ..storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredManifestIdentity,
+    StoredWeightManifest,
+    validate_weight_manifest_snapshot,
+)
+from . import contracts as _contracts
+from .attestation import RuntimeBindingAttestation
+from .contracts import (
+    ExecutableTransferOperation,
+    PlanningLimits,
+    PipelineRouteGroup,
+    _is_canonical_operation,
+    _OperationViews,
+)
+from .fragments import BoundWeightFragment
+
+
+@dataclass(frozen=True)
+class RuntimeFragmentSnapshot:
+    placement_fragment_id: PlacementFragmentId
+    fragment_id: RuntimeFragmentId
+    tensor_id: TensorId
+    global_offset: tuple[int, ...]
+    local_shape: tuple[int, ...]
+    address: int
+    nbytes: int
+    worker_id: str
+    endpoint: str
+    device: str
+    itemsize: int
+    strides_bytes: tuple[int, ...]
+    storage_address: int
+    storage_nbytes: int
+    storage_offset_bytes: int
+    lease_generation: int
+
+    @classmethod
+    def from_fragment(cls, fragment: BoundWeightFragment) -> RuntimeFragmentSnapshot:
+        return cls(
+            placement_fragment_id=fragment.placement_fragment_id,
+            fragment_id=fragment.fragment_id,
+            tensor_id=fragment.tensor_id,
+            global_offset=fragment.global_offset,
+            local_shape=fragment.local_shape,
+            address=fragment.address,
+            nbytes=fragment.nbytes,
+            worker_id=fragment.worker_id,
+            endpoint=fragment.endpoint,
+            device=fragment.device,
+            itemsize=fragment.binding.itemsize,
+            strides_bytes=fragment.binding.strides_bytes,
+            storage_address=fragment.storage_address,
+            storage_nbytes=fragment.storage_nbytes,
+            storage_offset_bytes=fragment.storage_offset_bytes,
+            lease_generation=fragment.lease_generation,
+        )
+
+    @classmethod
+    def from_attested_pair(
+        cls,
+        placement_fragment: PlacementFragment,
+        runtime_fragment: RuntimeBindingFragment,
+        *,
+        lease_generation: int,
+    ) -> RuntimeFragmentSnapshot:
+        return cls(
+            placement_fragment_id=placement_fragment.placement_fragment_id,
+            fragment_id=runtime_fragment.fragment_id,
+            tensor_id=placement_fragment.tensor_id,
+            global_offset=placement_fragment.global_offset,
+            local_shape=placement_fragment.local_shape,
+            address=runtime_fragment.address,
+            nbytes=runtime_fragment.nbytes,
+            worker_id=runtime_fragment.worker_id,
+            endpoint=runtime_fragment.endpoint,
+            device=runtime_fragment.device,
+            itemsize=runtime_fragment.itemsize,
+            strides_bytes=runtime_fragment.strides_bytes,
+            storage_address=runtime_fragment.storage_address,
+            storage_nbytes=runtime_fragment.storage_nbytes,
+            storage_offset_bytes=runtime_fragment.storage_offset_bytes,
+            lease_generation=lease_generation,
+        )
+
+
+@dataclass(frozen=True)
+class ExecutorTransferPlan:
+    instance_id: RuntimeInstanceId
+    placement_id: PlacementId
+    participant_id: ParticipantId
+    placement_digest: str
+    runtime_lease_id: Optional[LeaseId]
+    worker_id: str
+    rank: ParallelRank
+    fragment_ids: tuple[RuntimeFragmentId, ...]
+    fragment_snapshots: tuple[RuntimeFragmentSnapshot, ...]
+    attestation: Optional[RuntimeBindingAttestation] = field(
+        default=None,
+        compare=False,
+        repr=False,
+    )
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "fragment_ids", tuple(self.fragment_ids))
+        object.__setattr__(self, "fragment_snapshots", tuple(self.fragment_snapshots))
+        if (
+            not self.instance_id
+            or not self.placement_id
+            or not self.participant_id
+            or not self.worker_id
+            or not self.fragment_ids
+        ):
+            raise ValueError("executor plan identifiers must not be empty")
+        if len(self.placement_digest) != 64 or any(
+            character not in "0123456789abcdef" for character in self.placement_digest
+        ):
+            raise ValueError("executor plan placement digest must be SHA-256")
+        if self.runtime_lease_id is not None and (
+            type(self.runtime_lease_id) is not str or not self.runtime_lease_id
+        ):
+            raise ValueError("executor plan runtime lease ID must be non-empty")
+        if len(self.fragment_ids) != len(set(self.fragment_ids)):
+            raise ValueError("executor plan has duplicate fragment IDs")
+        if not all(
+            isinstance(snapshot, RuntimeFragmentSnapshot)
+            for snapshot in self.fragment_snapshots
+        ):
+            raise ValueError("executor plan has invalid runtime fragment snapshots")
+        if (
+            tuple(snapshot.fragment_id for snapshot in self.fragment_snapshots)
+            != self.fragment_ids
+        ):
+            raise ValueError("executor plan fragment snapshot IDs do not match")
+        if self.attestation is not None and not isinstance(
+            self.attestation, RuntimeBindingAttestation
+        ):
+            raise ValueError("executor plan runtime attestation is invalid")
+
+
+ExecutorKey: TypeAlias = tuple[
+    RuntimeInstanceId,
+    PlacementId,
+    ParticipantId,
+    str,
+    LeaseId,
+    str,
+    ParallelRank,
+]
+
+
+def _validate_executable_operation(value: object) -> None:
+    if not _is_canonical_operation(value):
+        raise ValueError("transfer plan requires a canonical transfer operation")
+    operation = cast(ExecutableTransferOperation, value)
+    if not isinstance(operation.target, BoundWeightFragment):
+        raise ValueError("executable transfer plan target must be runtime-bound")
+    if not isinstance(operation.source, (BoundWeightFragment, StoredFragmentSnapshot)):
+        raise ValueError("executable transfer plan source must be runtime-bound")
+    operation.validate_bounds()
+
+
+def _validate_source_target_allocations_do_not_overlap(
+    operations: tuple[ExecutableTransferOperation, ...],
+) -> None:
+    source_allocations: dict[
+        tuple[RuntimeInstanceId, str, str], set[tuple[int, int]]
+    ] = {}
+    target_allocations: dict[
+        tuple[RuntimeInstanceId, str, str], set[tuple[int, int]]
+    ] = {}
+    for operation in operations:
+        if isinstance(operation.source, BoundWeightFragment):
+            source_allocations.setdefault(
+                (
+                    operation.source.instance_id,
+                    operation.source.worker_id,
+                    operation.source.device,
+                ),
+                set(),
+            ).add(
+                (
+                    operation.source.binding.storage_address,
+                    operation.source.binding.storage_nbytes,
+                )
+            )
+        if isinstance(operation.target, BoundWeightFragment):
+            target_allocations.setdefault(
+                (
+                    operation.target.instance_id,
+                    operation.target.worker_id,
+                    operation.target.device,
+                ),
+                set(),
+            ).add(
+                (
+                    operation.target.binding.storage_address,
+                    operation.target.binding.storage_nbytes,
+                )
+            )
+
+    for address_space in sorted(set(source_allocations) & set(target_allocations)):
+        sources = sorted(source_allocations[address_space])
+        targets = sorted(target_allocations[address_space])
+        source_index = 0
+        target_index = 0
+        while source_index < len(sources) and target_index < len(targets):
+            source_start, source_size = sources[source_index]
+            target_start, target_size = targets[target_index]
+            source_end = source_start + source_size
+            target_end = target_start + target_size
+            if source_start < target_end and target_start < source_end:
+                raise ValueError(
+                    "source and target runtime storage allocations overlap in "
+                    f"address space {address_space}; in-place reshard is unsupported"
+                )
+            if source_end <= target_end:
+                source_index += 1
+            else:
+                target_index += 1
+
+
+def _validate_execution_provenance(
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    weight_generation: int,
+    operations: tuple[ExecutableTransferOperation, ...],
+) -> None:
+    """Require live execution fragments to come from verified bindings."""
+
+    for operation in operations:
+        fragments: tuple[tuple[str, BoundWeightFragment], ...] = (
+            ("target", operation.target),
+        )
+        if isinstance(operation.source, BoundWeightFragment):
+            fragments = (("source", operation.source), *fragments)
+        for side, fragment in fragments:
+            if fragment.owner is not None or fragment.binding.owner is not None:
+                raise ValueError(
+                    f"transfer plan {side} fragment retains runtime allocation owner"
+                )
+            attestation = fragment.attestation
+            if not isinstance(attestation, RuntimeBindingAttestation):
+                raise ValueError(
+                    f"transfer plan {side} fragment lacks an attested runtime binding"
+                )
+            placement = attestation.placement
+            if (
+                placement.resource_id != resource_id
+                or placement.revision != revision
+                or placement.weight_generation != weight_generation
+            ):
+                raise ValueError(
+                    f"transfer plan identity differs from {side} placement"
+                )
+            if not attestation.validates(fragment.placement, fragment.binding):
+                raise ValueError(
+                    f"transfer plan {side} fragment differs from attested runtime binding"
+                )
+
+
+def _validate_executor_provenance(
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    weight_generation: int,
+    operations: tuple[ExecutableTransferOperation, ...],
+    executors: tuple[ExecutorTransferPlan, ...],
+    operation_views: _OperationViews,
+    side: str,
+) -> None:
+    """Validate live executor routing against attested operation fragments."""
+
+    fragments = tuple(
+        operation.source if side == "source" else operation.target
+        for operation in operations
+    )
+    if not fragments:
+        return
+    has_stored_source = any(
+        isinstance(fragment, StoredFragmentSnapshot) for fragment in fragments
+    )
+    if has_stored_source:
+        if side != "source" or not all(
+            isinstance(fragment, StoredFragmentSnapshot) for fragment in fragments
+        ):
+            raise ValueError("transfer plan mixes stored and live source fragments")
+        if executors:
+            raise ValueError("stored source must not have live executor provenance")
+        return
+    live_fragments = tuple(
+        fragment for fragment in fragments if isinstance(fragment, BoundWeightFragment)
+    )
+    if len(live_fragments) != len(fragments):
+        raise ValueError(f"transfer plan {side} fragment is not runtime-bound")
+    if not executors:
+        raise ValueError(f"live {side} requires executor provenance")
+
+    expected_indices: dict[ExecutorKey, list[int]] = {}
+    for index, fragment in enumerate(live_fragments):
+        attestation = fragment.attestation
+        if not isinstance(attestation, RuntimeBindingAttestation):
+            raise ValueError(f"transfer plan {side} fragment lacks runtime attestation")
+        binding = attestation.evidence
+        placement = attestation.placement
+        key: ExecutorKey = (
+            binding.instance_id,
+            placement.placement_id,
+            binding.participant_id,
+            placement.digest,
+            binding.lease_id,
+            fragment.worker_id,
+            fragment.rank,
+        )
+        expected_indices.setdefault(key, []).append(index)
+
+    active_placement_ids = {
+        fragment.attestation.placement.placement_id
+        for fragment in live_fragments
+        if isinstance(fragment.attestation, RuntimeBindingAttestation)
+    }
+    actual_indices: dict[ExecutorKey, list[int]] = {}
+    executor_snapshots_by_fragment_id: dict[
+        RuntimeFragmentId, RuntimeFragmentSnapshot
+    ] = {}
+    for executor in executors:
+        if executor.runtime_lease_id is None:
+            raise ValueError(f"{side} executor is missing runtime lease provenance")
+        key: ExecutorKey = (
+            executor.instance_id,
+            executor.placement_id,
+            executor.participant_id,
+            executor.placement_digest,
+            executor.runtime_lease_id,
+            executor.worker_id,
+            executor.rank,
+        )
+        if key in actual_indices:
+            raise ValueError(f"transfer plan has duplicate {side} executor provenance")
+        attestation = executor.attestation
+        if not isinstance(attestation, RuntimeBindingAttestation):
+            raise ValueError(f"{side} executor lacks runtime attestation")
+        placement = attestation.placement
+        binding = attestation.evidence
+        if (
+            placement.resource_id != resource_id
+            or placement.revision != revision
+            or placement.weight_generation != weight_generation
+            or placement.placement_id not in active_placement_ids
+        ):
+            raise ValueError(f"{side} executor attestation identity differs")
+        expected_key: ExecutorKey = (
+            binding.instance_id,
+            placement.placement_id,
+            binding.participant_id,
+            placement.digest,
+            binding.lease_id,
+            executor.worker_id,
+            executor.rank,
+        )
+        if key != expected_key:
+            raise ValueError(f"{side} executor provenance differs from attestation")
+        actual_indices[key] = list(
+            operation_views.operation_indices_for(executor, side)
+        )
+        expected_fragment_snapshots = tuple(
+            sorted(
+                (
+                    RuntimeFragmentSnapshot.from_attested_pair(
+                        placement_fragment,
+                        runtime,
+                        lease_generation=binding.generation,
+                    )
+                    for placement_fragment, runtime in attestation.worker_fragment_pairs(
+                        executor.worker_id
+                    )
+                    if runtime.fragment_id in executor.fragment_ids
+                ),
+                key=lambda item: item.fragment_id,
+            )
+        )
+        if executor.fragment_snapshots != expected_fragment_snapshots:
+            raise ValueError(f"{side} executor fragment provenance differs")
+        for snapshot in executor.fragment_snapshots:
+            if snapshot.fragment_id in executor_snapshots_by_fragment_id:
+                raise ValueError(f"{side} executor has duplicate fragment provenance")
+            executor_snapshots_by_fragment_id[snapshot.fragment_id] = snapshot
+
+    for key, actual in actual_indices.items():
+        expected = expected_indices.get(key)
+        if expected is None:
+            if actual:
+                raise ValueError(f"{side} executor provenance differs from operations")
+            continue
+        if sorted(actual) != sorted(expected):
+            raise ValueError(f"{side} executor provenance differs from operations")
+    if set(expected_indices) - set(actual_indices):
+        raise ValueError(f"{side} executor provenance differs from operations")
+    operation_fragment_ids = {fragment.fragment_id for fragment in live_fragments}
+    if set(executor_snapshots_by_fragment_id) != operation_fragment_ids:
+        raise ValueError(f"{side} executor fragment provenance differs from operations")
+    for fragment in live_fragments:
+        if executor_snapshots_by_fragment_id.get(fragment.fragment_id) != (
+            RuntimeFragmentSnapshot.from_fragment(fragment)
+        ):
+            raise ValueError(f"{side} executor fragment provenance differs")
+
+
+def _validated_stored_source_fragment_snapshots(
+    operations: tuple[ExecutableTransferOperation, ...],
+    source_manifest: StoredWeightManifest,
+) -> tuple[StoredFragmentSnapshot, ...]:
+    """Derive selected Store ranges from the committed manifest snapshot."""
+
+    snapshots_by_id: dict[StoredFragmentSnapshotId, StoredFragmentSnapshot] = {}
+    for fragment in source_manifest.fragments:
+        snapshots_by_id[fragment.fragment_id] = fragment
+
+    operation_ids: set[StoredFragmentSnapshotId] = set()
+    for operation in operations:
+        source = operation.source
+        if not isinstance(source, StoredFragmentSnapshot):
+            raise ValueError("transfer plan mixes stored and live source fragments")
+        if snapshots_by_id.get(source.fragment_id) != source:
+            raise ValueError(
+                "transfer plan stored source fragment differs from committed manifest"
+            )
+        operation_ids.add(source.fragment_id)
+    return tuple(snapshots_by_id[fragment_id] for fragment_id in sorted(operation_ids))
+
+
+@dataclass(frozen=True)
+class TransferPlan:
+    _operation_views: ClassVar[_OperationViews]
+
+    resource_id: ResourceId
+    revision: RevisionId
+    weight_generation: int
+    target_placement: WeightPlacementManifest
+    operations: tuple[ExecutableTransferOperation, ...]
+    planning_limits: PlanningLimits = field(default_factory=PlanningLimits)
+    source_executors: tuple[ExecutorTransferPlan, ...] = ()
+    target_executors: tuple[ExecutorTransferPlan, ...] = ()
+    source_manifest: Optional[StoredWeightManifest] = None
+    source_manifest_identity: Optional[StoredManifestIdentity] = None
+    source_stored_fragment_snapshots: tuple[StoredFragmentSnapshot, ...] = field(
+        init=False
+    )
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "operations", tuple(self.operations))
+        object.__setattr__(self, "source_executors", tuple(self.source_executors))
+        object.__setattr__(self, "target_executors", tuple(self.target_executors))
+        if not self.resource_id or not self.revision:
+            raise ValueError("transfer plan identifiers must not be empty")
+        if type(self.weight_generation) is not int or self.weight_generation < 0:
+            raise ValueError("transfer plan weight_generation must be non-negative")
+        if not isinstance(self.planning_limits, PlanningLimits):
+            raise ValueError("transfer plan planning_limits is invalid")
+        if self.source_manifest_identity is not None and not isinstance(
+            self.source_manifest_identity,
+            StoredManifestIdentity,
+        ):
+            raise ValueError("transfer plan source manifest identity is invalid")
+        if self.source_manifest is not None and not isinstance(
+            self.source_manifest,
+            StoredWeightManifest,
+        ):
+            raise ValueError("transfer plan source manifest is invalid")
+        if len(self.operations) > self.planning_limits.max_transfer_regions:
+            raise ValueError("transfer plan exceeds max_transfer_regions")
+        total_lowered_segments = 0
+        for operation in self.operations:
+            _validate_executable_operation(operation)
+            if operation.segment_count > self.planning_limits.max_segments_per_region:
+                raise ValueError("transfer plan exceeds max_segments_per_region")
+            total_lowered_segments += operation.segment_count
+            if total_lowered_segments > self.planning_limits.max_total_lowered_segments:
+                raise ValueError("transfer plan exceeds max_total_lowered_segments")
+        has_stored_source = any(
+            isinstance(operation.source, StoredFragmentSnapshot)
+            for operation in self.operations
+        )
+        if has_stored_source:
+            if self.source_manifest is None:
+                raise ValueError("stored transfer plan requires a source manifest")
+            source_manifest = validate_weight_manifest_snapshot(self.source_manifest)
+            object.__setattr__(self, "source_manifest", source_manifest)
+            if self.source_manifest_identity is None:
+                raise ValueError(
+                    "stored transfer plan requires a source manifest identity"
+                )
+            if (
+                self.source_manifest_identity.resource_id != self.resource_id
+                or self.source_manifest_identity.revision != self.revision
+                or self.source_manifest_identity.weight_generation
+                != self.weight_generation
+            ):
+                raise ValueError("transfer plan source manifest identity differs")
+            if source_manifest.manifest_identity != self.source_manifest_identity:
+                raise ValueError("transfer plan source manifest commitment differs")
+            object.__setattr__(
+                self,
+                "source_stored_fragment_snapshots",
+                _validated_stored_source_fragment_snapshots(
+                    self.operations,
+                    source_manifest,
+                ),
+            )
+        elif self.source_manifest is not None:
+            raise ValueError("runtime transfer plan must not have a source manifest")
+        elif self.source_manifest_identity is not None:
+            raise ValueError(
+                "runtime transfer plan must not have a source manifest identity"
+            )
+        else:
+            object.__setattr__(self, "source_stored_fragment_snapshots", ())
+        if not all(
+            isinstance(executor, ExecutorTransferPlan)
+            for executor in (*self.source_executors, *self.target_executors)
+        ):
+            raise ValueError("transfer plan has invalid canonical executor metadata")
+        # Resolve the shared view builder through the logical contracts module
+        # so its canonical definition remains the single patch point for both
+        # plan types.
+        object.__setattr__(
+            self,
+            "_operation_views",
+            _contracts._build_operation_views(
+                self.operations,
+                self.source_executors,
+                self.target_executors,
+            ),
+        )
+        _validate_execution_provenance(
+            resource_id=self.resource_id,
+            revision=self.revision,
+            weight_generation=self.weight_generation,
+            operations=self.operations,
+        )
+        if not isinstance(self.target_placement, WeightPlacementManifest):
+            raise ValueError("transfer plan target placement is invalid")
+        if (
+            self.target_placement.resource_id != self.resource_id
+            or self.target_placement.revision != self.revision
+            or self.target_placement.weight_generation != self.weight_generation
+        ):
+            raise ValueError("transfer plan target placement identity differs")
+        _validate_executor_provenance(
+            resource_id=self.resource_id,
+            revision=self.revision,
+            weight_generation=self.weight_generation,
+            operations=self.operations,
+            executors=self.source_executors,
+            operation_views=self._operation_views,
+            side="source",
+        )
+        _validate_executor_provenance(
+            resource_id=self.resource_id,
+            revision=self.revision,
+            weight_generation=self.weight_generation,
+            operations=self.operations,
+            executors=self.target_executors,
+            operation_views=self._operation_views,
+            side="target",
+        )
+        _validate_source_target_allocations_do_not_overlap(self.operations)
+        # Re-check the complete target placement at the public executable-plan
+        # boundary. Binding output can be serialized or reconstructed, so the
+        # executor snapshot alone cannot be trusted as a coverage proof.
+        from .bound_validation import (
+            _validate_bound_target_coverage,
+            _validate_target_physical_ranges,
+        )
+
+        _validate_target_physical_ranges(
+            self.operations,
+            max_segment_checks=self.planning_limits.max_total_lowered_segments,
+        )
+        _validate_bound_target_coverage(self)
+
+    @property
+    def total_bytes(self) -> int:
+        return sum(operation.total_bytes for operation in self.operations)
+
+    @property
+    def regions(self) -> tuple[ExecutableTransferOperation, ...]:
+        return self.operations
+
+    @property
+    def pipeline_routes(self) -> tuple[PipelineRouteGroup, ...]:
+        return self._operation_views.pipeline_routes
+
+    def operation_indices_for_executor(
+        self,
+        executor: ExecutorTransferPlan,
+        side: str,
+    ) -> tuple[int, ...]:
+        executors = self.source_executors if side == "source" else self.target_executors
+        if side not in ("source", "target"):
+            raise ValueError(f"invalid executor side: {side}")
+        if executor not in executors:
+            raise ValueError(f"{side} executor is not part of this transfer plan")
+        return self._operation_views.operation_indices_for(executor, side)
+
+    def __getstate__(self) -> dict[str, object]:
+        return {
+            name: value
+            for name, value in self.__dict__.items()
+            if name != "_operation_views"
+        }
+
+    def __setstate__(self, state: dict[str, object]) -> None:
+        for name, value in state.items():
+            object.__setattr__(self, name, value)
+        self.__post_init__()
+
+
+__all__ = [
+    "ExecutorTransferPlan",
+    "RuntimeFragmentSnapshot",
+    "TransferPlan",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_validation.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_validation.py
new file mode 100644
index 0000000000..1ccb781fac
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/bound_validation.py
@@ -0,0 +1,333 @@
+"""Runtime-bound plan validation over attested physical locations."""
+
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass
+from typing import Iterable, Optional, Sequence, Union
+
+from ..._typing import TypeAlias
+
+from ..._compat import _strict_zip
+from ...contracts import ParticipantId, PlacementFragmentId
+from ...geometry import regions_exactly_cover
+from ..manifest import PlacementFragment
+from ..storage_manifest import StoredFragmentSnapshot
+from .attestation import RuntimeBindingAttestation
+from .bound_contracts import TransferPlan
+from .contracts import ExecutableTransferOperation
+from .fragments import BoundWeightFragment
+
+
+IdentityKey: TypeAlias = tuple[object, ...]
+TargetAddressSpace: TypeAlias = tuple[str, str, str]
+
+
+def _validate_bound_target_coverage(plan: TransferPlan) -> None:
+    """Require every selected target participant to be fully covered again."""
+
+    target_placement = plan.target_placement
+    target_parts = {part.participant_id: part for part in target_placement.parts}
+    participant_by_fragment = {
+        fragment.placement_fragment_id: part.participant_id
+        for part in target_placement.parts
+        for fragment in part.fragments
+    }
+    operations_by_fragment: dict[
+        PlacementFragmentId, list[ExecutableTransferOperation]
+    ] = {}
+    operation_participants: set[ParticipantId] = set()
+    for operation in plan.operations:
+        target = operation.target
+        attestation = target.attestation
+        if (
+            not isinstance(attestation, RuntimeBindingAttestation)
+            or attestation.placement != target_placement
+            or not attestation.validates(target.placement, target.binding)
+        ):
+            raise ValueError("bound target fragment differs from target placement")
+        participant_id = participant_by_fragment.get(target.placement_fragment_id)
+        if participant_id is None or not any(
+            fragment == target.placement
+            for fragment in target_parts[participant_id].fragments
+        ):
+            raise ValueError("bound target fragment differs from target placement")
+        operations_by_fragment.setdefault(target.placement_fragment_id, []).append(
+            operation
+        )
+        operation_participants.add(participant_id)
+
+    if not plan.target_executors:
+        raise ValueError("bound plan has no target executor metadata")
+
+    seen_executor_keys: set[tuple[ParticipantId, str]] = set()
+    selected_participants: set[ParticipantId] = set()
+    selected_fragments: dict[PlacementFragmentId, PlacementFragment] = {}
+    for executor in plan.target_executors:
+        executor_key = (executor.participant_id, executor.worker_id)
+        if executor_key in seen_executor_keys:
+            raise ValueError("bound plan has duplicate target executor")
+        seen_executor_keys.add(executor_key)
+        part = target_parts.get(executor.participant_id)
+        attestation = executor.attestation
+        if (
+            part is None
+            or executor.rank != part.rank
+            or executor.placement_id != target_placement.placement_id
+            or executor.placement_digest != target_placement.digest
+            or not isinstance(attestation, RuntimeBindingAttestation)
+            or attestation.placement != target_placement
+            or attestation.evidence.participant_id != executor.participant_id
+            or attestation.evidence.instance_id != executor.instance_id
+            or attestation.evidence.lease_id != executor.runtime_lease_id
+        ):
+            raise ValueError("bound target executor differs from target placement")
+        selected_pairs = tuple(
+            (fragment, runtime)
+            for fragment, runtime in attestation.worker_fragment_pairs(
+                executor.worker_id
+            )
+            if runtime.fragment_id in executor.fragment_ids
+        )
+        expected_fragment_ids = tuple(
+            sorted(runtime.fragment_id for _, runtime in selected_pairs)
+        )
+        if executor.fragment_ids != expected_fragment_ids:
+            raise ValueError(
+                "bound target executor fragments differ from target placement"
+            )
+        if not plan.operation_indices_for_executor(executor, "target"):
+            raise ValueError(
+                "bound target executor operations differ from target placement"
+            )
+        selected_participants.add(executor.participant_id)
+        selected_fragments.update(
+            {fragment.placement_fragment_id: fragment for fragment, _ in selected_pairs}
+        )
+
+    if selected_participants != operation_participants:
+        raise ValueError("bound target executors differ from planned operations")
+
+    for fragment_id, target in selected_fragments.items():
+        operations = operations_by_fragment.get(fragment_id, ())
+        if not regions_exactly_cover(target, operations):
+            raise ValueError(
+                f"bound target fragment is not fully covered: {fragment_id}"
+            )
+
+
+def _is_complete_alias_group(
+    fragment: Union[BoundWeightFragment, StoredFragmentSnapshot],
+) -> bool:
+    return len(fragment.aliases) > 1 and fragment.tensor_id in fragment.aliases
+
+
+def _is_safe_declared_alias_overlap(
+    left: ExecutableTransferOperation,
+    right: ExecutableTransferOperation,
+) -> bool:
+    """Allow one exact write only for one complete, attested alias lifetime."""
+
+    left_target = left.target
+    right_target = right.target
+    left_attestation = left_target.attestation
+    right_attestation = right_target.attestation
+    if (
+        left.tensor_id == right.tensor_id
+        or not _is_complete_alias_group(left.source)
+        or not _is_complete_alias_group(right.source)
+        or not _is_complete_alias_group(left_target)
+        or not _is_complete_alias_group(right_target)
+        or left.source.aliases != right.source.aliases
+        or left_target.aliases != right_target.aliases
+        or left.source.aliases != left_target.aliases
+        or left.source.global_offset != right.source.global_offset
+        or left.source.local_shape != right.source.local_shape
+        or left.source_offset != right.source_offset
+        or left.target_offset != right.target_offset
+        or left.nbytes != right.nbytes
+        or left.outer_loop_counts != right.outer_loop_counts
+        or left.source_strides != right.source_strides
+        or left.target_strides != right.target_strides
+        or left_target.global_offset != right_target.global_offset
+        or left_target.local_shape != right_target.local_shape
+        or left_target.address != right_target.address
+        or left_target.nbytes != right_target.nbytes
+        or left_target.owner != right_target.owner
+        or left_target.instance_id != right_target.instance_id
+        or left_target.runtime_lease_id != right_target.runtime_lease_id
+        or left_target.lease_generation != right_target.lease_generation
+        or not isinstance(left_attestation, RuntimeBindingAttestation)
+        or not isinstance(right_attestation, RuntimeBindingAttestation)
+        or left_attestation.placement != right_attestation.placement
+        or left_attestation.evidence != right_attestation.evidence
+        or left.overlap_offset != right.overlap_offset
+        or left.overlap_shape != right.overlap_shape
+    ):
+        return False
+    return True
+
+
+def _target_physical_bounds(operation: ExecutableTransferOperation) -> tuple[int, int]:
+    begin = operation.target.address + operation.target_offset
+    end = (
+        begin
+        + sum(
+            (count - 1) * stride
+            for count, stride in _strict_zip(
+                operation.outer_loop_counts,
+                operation.target_strides,
+            )
+        )
+        + operation.nbytes
+    )
+    return begin, end
+
+
+@dataclass
+class _SegmentScanBudget:
+    limit: int
+    checked: int = 0
+
+    def consume(self) -> None:
+        self.checked += 1
+        if self.checked > self.limit:
+            raise ValueError("target physical segment scan budget exceeded")
+
+
+def _absolute_target_segments(
+    operation: ExecutableTransferOperation,
+    *,
+    max_segments: int,
+) -> Iterable[tuple[int, int]]:
+    for _, target_offset, nbytes in operation.iter_segments(max_segments=max_segments):
+        begin = operation.target.address + target_offset
+        yield begin, begin + nbytes
+
+
+def _budgeted_target_segments(
+    operation_index: int,
+    operation: ExecutableTransferOperation,
+    budget: _SegmentScanBudget,
+) -> Iterable[tuple[int, int, int]]:
+    for begin, end in _absolute_target_segments(
+        operation,
+        # The plan constructor already enforces its per-region bound. This
+        # scanner owns a separate aggregate budget and must account segments
+        # incrementally so its public error remains deterministic.
+        max_segments=operation.segment_count,
+    ):
+        budget.consume()
+        yield begin, end, operation_index
+
+
+def _target_fragment_scan_key(
+    operation: ExecutableTransferOperation,
+) -> IdentityKey:
+    target = operation.target
+    return (
+        target.fragment_id,
+        target.tensor_id,
+        target.instance_id,
+        target.worker_id,
+        target.device,
+        target.lease_generation,
+        target.address,
+        target.nbytes,
+        target.global_offset,
+        target.local_shape,
+    )
+
+
+def _complete_target_fragment_segment(
+    indexed_operations: Sequence[tuple[int, ExecutableTransferOperation]],
+) -> Optional[tuple[int, int, int]]:
+    if not indexed_operations:
+        return None
+    target = indexed_operations[0][1].target
+    if not regions_exactly_cover(
+        target,
+        tuple(operation for _, operation in indexed_operations),
+    ):
+        return None
+    return target.address, target.address + target.nbytes, indexed_operations[0][0]
+
+
+def _validate_target_physical_ranges(
+    operations: Sequence[ExecutableTransferOperation],
+    *,
+    max_segment_checks: int = 1_000_000,
+) -> None:
+    if type(max_segment_checks) is not int or max_segment_checks <= 0:
+        raise ValueError("max_segment_checks must be a positive integer")
+    by_address_space: dict[TargetAddressSpace, list[ExecutableTransferOperation]] = {}
+    for operation in operations:
+        by_address_space.setdefault(
+            (
+                operation.target.instance_id,
+                operation.target.worker_id,
+                operation.target.device,
+            ),
+            [],
+        ).append(operation)
+
+    for scoped_operations in by_address_space.values():
+        by_fragment: dict[
+            IdentityKey, list[tuple[int, ExecutableTransferOperation]]
+        ] = {}
+        for index, operation in enumerate(scoped_operations):
+            by_fragment.setdefault(_target_fragment_scan_key(operation), []).append(
+                (index, operation)
+            )
+
+        complete_segments: list[tuple[int, int, int]] = []
+        incomplete_operation_indices: set[int] = set()
+        for indexed_operations in by_fragment.values():
+            complete_segment = _complete_target_fragment_segment(indexed_operations)
+            if complete_segment is None:
+                incomplete_operation_indices.update(
+                    index for index, _ in indexed_operations
+                )
+            else:
+                complete_segments.append(complete_segment)
+        complete_segments.sort()
+
+        budget = _SegmentScanBudget(max_segment_checks)
+        segment_streams: list[Iterable[tuple[int, int, int]]] = []
+        if complete_segments:
+            segment_streams.append(iter(complete_segments))
+        segment_streams.extend(
+            (
+                _budgeted_target_segments(index, operation, budget)
+                for index, operation in enumerate(scoped_operations)
+                if index in incomplete_operation_indices
+            )
+        )
+        ordered_segments = heapq.merge(*segment_streams)
+        previous_begin = -1
+        previous_end = -1
+        previous_operation_index: Optional[int] = None
+        for begin, end, operation_index in ordered_segments:
+            if begin < previous_end:
+                if previous_operation_index is None:
+                    raise AssertionError(
+                        "target physical range scan lost its predecessor"
+                    )
+                previous_operation = scoped_operations[previous_operation_index]
+                current_operation = scoped_operations[operation_index]
+                if (
+                    begin == previous_begin
+                    and end == previous_end
+                    and _is_safe_declared_alias_overlap(
+                        previous_operation,
+                        current_operation,
+                    )
+                ):
+                    continue
+                raise ValueError(
+                    "conflicting target physical range: "
+                    f"{scoped_operations[operation_index].target.fragment_id}"
+                )
+            previous_begin = begin
+            previous_end = max(previous_end, end)
+            previous_operation_index = operation_index
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/contracts.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/contracts.py
new file mode 100644
index 0000000000..551c09b56b
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/contracts.py
@@ -0,0 +1,818 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from math import prod
+from types import MappingProxyType
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Generic,
+    Iterable,
+    Mapping,
+    Optional,
+    Sequence,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from ..._compat import _strict_zip
+from ..._typing import TypeAlias
+from ...contracts import (
+    LeaseId,
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    ResourceId,
+    RevisionId,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    TensorId,
+)
+from ...geometry import box_contains as _box_contains
+from ..manifest import (
+    ParallelRank,
+    PlacementFragment,
+    TensorDescriptor,
+    WeightPlacementManifest,
+)
+from ..storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredManifestIdentity,
+    StoredWeightManifest,
+    validate_weight_manifest_snapshot,
+)
+from .geometry import (
+    _derive_region_geometry,
+    _fragment_itemsize,
+    _validate_outer_strides,
+)
+from .fragments import (
+    BoundWeightFragment,
+    ExecutableSourceFragment,
+    ExecutableTargetFragment,
+    GeometryFragment,
+    LogicalSourceFragment,
+    LogicalTargetFragment,
+)
+
+if TYPE_CHECKING:
+    from .bound_contracts import ExecutorTransferPlan
+
+
+RuntimeTensorOwner = tuple[tuple[str, int], ...]
+_SourceFragmentT = TypeVar("_SourceFragmentT", bound=GeometryFragment)
+_TargetFragmentT = TypeVar("_TargetFragmentT", bound=GeometryFragment)
+
+
+@dataclass(frozen=True)
+class PipelineRouteGroup:
+    source_pp: Optional[int]
+    source_pipeline_stage_id: Optional[int]
+    target_pp: int
+    target_pipeline_stage_id: Optional[int]
+    operation_indices: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "operation_indices", tuple(self.operation_indices))
+        if self.source_pp is not None and (
+            type(self.source_pp) is not int or self.source_pp < 0
+        ):
+            raise ValueError("pipeline route source_pp must be non-negative")
+        if type(self.target_pp) is not int or self.target_pp < 0:
+            raise ValueError("pipeline route target_pp must be non-negative")
+        for name in (
+            "source_pipeline_stage_id",
+            "target_pipeline_stage_id",
+        ):
+            value = getattr(self, name)
+            if value is not None and (type(value) is not int or value < 0):
+                raise ValueError(f"pipeline route {name} must be non-negative")
+        if any(type(index) is not int or index < 0 for index in self.operation_indices):
+            raise ValueError("pipeline route indices must be non-negative integers")
+        if len(self.operation_indices) != len(set(self.operation_indices)):
+            raise ValueError("pipeline route has duplicate operation indices")
+
+
+@dataclass(frozen=True)
+class PlanningLimits:
+    """Fail-closed limits for canonical N-D planning and lowering."""
+
+    max_transfer_regions: int = 1_000_000
+    max_segments_per_region: int = 1_000_000
+    max_total_lowered_segments: int = 10_000_000
+
+    def __post_init__(self) -> None:
+        for name in (
+            "max_transfer_regions",
+            "max_segments_per_region",
+            "max_total_lowered_segments",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ValueError(f"planning limit {name} must be a positive integer")
+
+
+@dataclass(frozen=True)
+class TransferRegion(Generic[_SourceFragmentT, _TargetFragmentT]):
+    tensor_id: TensorId
+    source: _SourceFragmentT
+    target: _TargetFragmentT
+    overlap_offset: tuple[int, ...]
+    overlap_shape: tuple[int, ...]
+    source_base_offset: int
+    target_base_offset: int
+    inner_bytes: int
+    outer_loop_counts: tuple[int, ...]
+    source_strides: tuple[int, ...]
+    target_strides: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        for name in (
+            "overlap_offset",
+            "overlap_shape",
+            "outer_loop_counts",
+            "source_strides",
+            "target_strides",
+        ):
+            value = getattr(self, name)
+            if isinstance(value, (str, bytes, bytearray)):
+                raise ValueError(f"transfer region {name} must contain integers")
+            try:
+                normalized = tuple(value)
+            except TypeError as error:
+                raise ValueError(
+                    f"transfer region {name} must contain integers"
+                ) from error
+            if any(type(item) is not int for item in normalized):
+                raise ValueError(f"transfer region {name} must contain integers")
+            object.__setattr__(self, name, normalized)
+
+        if not self.tensor_id:
+            raise ValueError("transfer region tensor_id must not be empty")
+        if (
+            self.source.tensor_id != self.tensor_id
+            or self.target.tensor_id != self.tensor_id
+        ):
+            raise ValueError("transfer region tensor mismatch")
+        ndim = len(self.overlap_offset)
+        if (
+            ndim == 0
+            or len(self.overlap_shape) != ndim
+            or len(self.source.global_offset) != ndim
+            or len(self.target.global_offset) != ndim
+        ):
+            raise ValueError("transfer region logical rank mismatch")
+        if any(offset < 0 for offset in self.overlap_offset) or any(
+            extent <= 0 for extent in self.overlap_shape
+        ):
+            raise ValueError("transfer region logical box is invalid")
+        if not _box_contains(
+            self.source.global_offset,
+            self.source.local_shape,
+            self.overlap_offset,
+            self.overlap_shape,
+        ):
+            raise ValueError("transfer region exceeds source logical fragment")
+        if not _box_contains(
+            self.target.global_offset,
+            self.target.local_shape,
+            self.overlap_offset,
+            self.overlap_shape,
+        ):
+            raise ValueError("transfer region exceeds target logical fragment")
+
+        for name in ("source_base_offset", "target_base_offset", "inner_bytes"):
+            value = getattr(self, name)
+            if type(value) is not int:
+                raise ValueError(f"transfer region {name} must be an integer")
+        if self.source_base_offset < 0 or self.target_base_offset < 0:
+            raise ValueError("transfer region base offsets must be non-negative")
+        if self.inner_bytes <= 0:
+            raise ValueError("transfer region inner_bytes must be positive")
+        if not (
+            len(self.outer_loop_counts)
+            == len(self.source_strides)
+            == len(self.target_strides)
+        ):
+            raise ValueError("transfer region outer loop rank mismatch")
+        if any(count <= 0 for count in self.outer_loop_counts):
+            raise ValueError("transfer region outer loop counts must be positive")
+        if any(stride < 0 for stride in self.source_strides) or any(
+            stride < 0 for stride in self.target_strides
+        ):
+            raise ValueError("transfer region strides must be non-negative")
+
+        source_itemsize = _fragment_itemsize(self.source)
+        target_itemsize = _fragment_itemsize(self.target)
+        if source_itemsize != target_itemsize:
+            raise ValueError("transfer region source and target itemsize differ")
+        (
+            expected_source_offset,
+            expected_target_offset,
+            expected_inner_bytes,
+            expected_outer_loop_counts,
+            expected_source_strides,
+            expected_target_strides,
+        ) = _derive_region_geometry(
+            self.source,
+            self.target,
+            self.overlap_offset,
+            self.overlap_shape,
+        )
+        expected_bytes = prod(self.overlap_shape) * source_itemsize
+        if self.total_bytes != expected_bytes:
+            raise ValueError("transfer region loop geometry does not match overlap")
+        if self.source_base_offset != expected_source_offset:
+            raise ValueError("transfer region source base offset is inconsistent")
+        if self.target_base_offset != expected_target_offset:
+            raise ValueError("transfer region target base offset is inconsistent")
+        if (
+            self.inner_bytes,
+            self.outer_loop_counts,
+            self.source_strides,
+            self.target_strides,
+        ) != (
+            expected_inner_bytes,
+            expected_outer_loop_counts,
+            expected_source_strides,
+            expected_target_strides,
+        ):
+            raise ValueError("transfer region loop geometry is not canonical")
+
+        _validate_outer_strides(
+            self.outer_loop_counts,
+            self.source_strides,
+            self.inner_bytes,
+            "source",
+        )
+        _validate_outer_strides(
+            self.outer_loop_counts,
+            self.target_strides,
+            self.inner_bytes,
+            "target",
+        )
+        self.validate_bounds()
+
+    @property
+    def segment_count(self) -> int:
+        return prod(self.outer_loop_counts)
+
+    @property
+    def total_bytes(self) -> int:
+        return self.inner_bytes * self.segment_count
+
+    @property
+    def source_offset(self) -> int:
+        return self.source_base_offset
+
+    @property
+    def target_offset(self) -> int:
+        return self.target_base_offset
+
+    @property
+    def nbytes(self) -> int:
+        return self.inner_bytes
+
+    @property
+    def repeat(self) -> int:
+        return self.segment_count
+
+    @property
+    def source_stride(self) -> int:
+        if not self.source_strides:
+            return 0
+        if len(self.source_strides) == 1:
+            return self.source_strides[0]
+        raise ValueError("N-D transfer region has multiple source strides")
+
+    @property
+    def target_stride(self) -> int:
+        if not self.target_strides:
+            return 0
+        if len(self.target_strides) == 1:
+            return self.target_strides[0]
+        raise ValueError("N-D transfer region has multiple target strides")
+
+    def validate_bounds(self) -> None:
+        source_end = (
+            self.source_base_offset
+            + sum(
+                (count - 1) * stride
+                for count, stride in _strict_zip(
+                    self.outer_loop_counts, self.source_strides
+                )
+            )
+            + self.inner_bytes
+        )
+        if source_end > self.source.nbytes:
+            raise ValueError("transfer region exceeds source fragment")
+        target_end = (
+            self.target_base_offset
+            + sum(
+                (count - 1) * stride
+                for count, stride in _strict_zip(
+                    self.outer_loop_counts, self.target_strides
+                )
+            )
+            + self.inner_bytes
+        )
+        if target_end > self.target.nbytes:
+            raise ValueError("transfer region exceeds target fragment")
+
+    def iter_segments(self, *, max_segments: int) -> Iterable[tuple[int, int, int]]:
+        if type(max_segments) is not int or max_segments <= 0:
+            raise ValueError("max_segments must be a positive integer")
+        if self.segment_count > max_segments:
+            raise ValueError(
+                "transfer region exceeds max_segments: "
+                f"{self.segment_count} > {max_segments}"
+            )
+        if not self.outer_loop_counts:
+            yield self.source_base_offset, self.target_base_offset, self.inner_bytes
+            return
+        indices = [0] * len(self.outer_loop_counts)
+        while True:
+            yield (
+                self.source_base_offset
+                + sum(
+                    index * stride
+                    for index, stride in _strict_zip(indices, self.source_strides)
+                ),
+                self.target_base_offset
+                + sum(
+                    index * stride
+                    for index, stride in _strict_zip(indices, self.target_strides)
+                ),
+                self.inner_bytes,
+            )
+            for dim in range(len(indices) - 1, -1, -1):
+                indices[dim] += 1
+                if indices[dim] < self.outer_loop_counts[dim]:
+                    break
+                indices[dim] = 0
+            else:
+                return
+
+
+LogicalTransferRegion: TypeAlias = TransferRegion[
+    LogicalSourceFragment,
+    LogicalTargetFragment,
+]
+LogicalTransferOperation: TypeAlias = LogicalTransferRegion
+
+ExecutableTransferRegion: TypeAlias = TransferRegion[
+    ExecutableSourceFragment,
+    ExecutableTargetFragment,
+]
+ExecutableTransferOperation: TypeAlias = ExecutableTransferRegion
+
+LiveTransferOperation: TypeAlias = TransferRegion[
+    BoundWeightFragment, BoundWeightFragment
+]
+StoredLoadOperation: TypeAlias = TransferRegion[
+    StoredFragmentSnapshot, BoundWeightFragment
+]
+
+
+def _is_canonical_operation(value: object) -> bool:
+    return isinstance(value, TransferRegion)
+
+
+def _validate_logical_operation(
+    value: object,
+    source_has_placement: bool,
+) -> None:
+    if not _is_canonical_operation(value):
+        raise ValueError(
+            "logical transfer plan requires a canonical transfer operation"
+        )
+    operation = cast(LogicalTransferOperation, value)
+    if not isinstance(operation.target, PlacementFragment):
+        raise ValueError("logical transfer plan target must be a placement")
+    if source_has_placement:
+        if not isinstance(operation.source, PlacementFragment):
+            raise ValueError("logical transfer plan source must be a placement")
+    elif not isinstance(operation.source, StoredFragmentSnapshot):
+        raise ValueError("logical transfer plan source has no placement")
+    operation.validate_bounds()
+
+
+@dataclass(frozen=True)
+class PlacementExecutorPlan:
+    placement_id: PlacementId
+    participant_id: ParticipantId
+    rank: ParallelRank
+    placement_fragment_ids: tuple[PlacementFragmentId, ...]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "placement_fragment_ids", tuple(self.placement_fragment_ids)
+        )
+        if (
+            not self.placement_id
+            or not self.participant_id
+            or not self.placement_fragment_ids
+        ):
+            raise ValueError("placement executor identifiers must not be empty")
+        if len(self.placement_fragment_ids) != len(set(self.placement_fragment_ids)):
+            raise ValueError("placement executor has duplicate fragment IDs")
+
+
+RuntimeExecutorProjectionKey: TypeAlias = tuple[
+    RuntimeInstanceId,
+    PlacementId,
+    ParticipantId,
+    str,
+    Optional[LeaseId],
+    str,
+    ParallelRank,
+    tuple[RuntimeFragmentId, ...],
+]
+PlacementExecutorProjectionKey: TypeAlias = tuple[
+    PlacementId,
+    ParticipantId,
+    ParallelRank,
+    tuple[PlacementFragmentId, ...],
+]
+ExecutorProjectionKey: TypeAlias = Union[
+    RuntimeExecutorProjectionKey,
+    PlacementExecutorProjectionKey,
+]
+FragmentProjectionKey: TypeAlias = tuple[str, str]
+
+
+@dataclass(frozen=True)
+class _OperationViews:
+    source_indices: Mapping[ExecutorProjectionKey, tuple[int, ...]]
+    target_indices: Mapping[ExecutorProjectionKey, tuple[int, ...]]
+    pipeline_routes: tuple[PipelineRouteGroup, ...]
+
+    def operation_indices_for(
+        self,
+        executor: Union[ExecutorTransferPlan, PlacementExecutorPlan],
+        side: str,
+    ) -> tuple[int, ...]:
+        if side == "source":
+            return self.source_indices.get(_executor_projection_key(executor), ())
+        if side == "target":
+            return self.target_indices.get(_executor_projection_key(executor), ())
+        raise ValueError(f"invalid executor side: {side}")
+
+
+@dataclass(frozen=True)
+class LogicalTransferPlan:
+    _operation_views: ClassVar[_OperationViews]
+
+    resource_id: ResourceId
+    revision: RevisionId
+    source_placement: Optional[WeightPlacementManifest]
+    target_placement: WeightPlacementManifest
+    source_tensors: tuple[TensorDescriptor, ...]
+    target_tensors: tuple[TensorDescriptor, ...]
+    operations: tuple[LogicalTransferOperation, ...]
+    source_manifest: Optional[StoredWeightManifest] = None
+    planning_limits: PlanningLimits = field(default_factory=PlanningLimits)
+    source_executors: tuple[PlacementExecutorPlan, ...] = ()
+    target_executors: tuple[PlacementExecutorPlan, ...] = ()
+    source_manifest_identity: Optional[StoredManifestIdentity] = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "source_tensors", tuple(self.source_tensors))
+        object.__setattr__(self, "target_tensors", tuple(self.target_tensors))
+        object.__setattr__(self, "operations", tuple(self.operations))
+        object.__setattr__(self, "source_executors", tuple(self.source_executors))
+        object.__setattr__(self, "target_executors", tuple(self.target_executors))
+        if not self.resource_id or not self.revision:
+            raise ValueError("logical transfer plan identifiers must not be empty")
+        if not isinstance(self.target_placement, WeightPlacementManifest):
+            raise ValueError("logical transfer plan target placement is invalid")
+        if not isinstance(self.planning_limits, PlanningLimits):
+            raise ValueError("logical transfer plan planning_limits is invalid")
+        if len(self.operations) > self.planning_limits.max_transfer_regions:
+            raise ValueError("logical transfer plan exceeds max_transfer_regions")
+        total_lowered_segments = 0
+        if self.source_placement is not None and not isinstance(
+            self.source_placement, WeightPlacementManifest
+        ):
+            raise ValueError("logical transfer plan source placement is invalid")
+        if self.source_manifest is not None and not isinstance(
+            self.source_manifest, StoredWeightManifest
+        ):
+            raise ValueError("logical transfer plan source manifest is invalid")
+        if (self.source_placement is None) == (self.source_manifest is None):
+            raise ValueError(
+                "logical transfer plan requires exactly one source provenance"
+            )
+        if self.source_manifest is not None:
+            source_manifest = validate_weight_manifest_snapshot(self.source_manifest)
+            object.__setattr__(self, "source_manifest", source_manifest)
+            object.__setattr__(
+                self,
+                "source_manifest_identity",
+                source_manifest.manifest_identity,
+            )
+        else:
+            object.__setattr__(self, "source_manifest_identity", None)
+        for side, placement in (
+            ("source", self.source_placement),
+            ("target", self.target_placement),
+        ):
+            if placement is not None and (
+                placement.resource_id != self.resource_id
+                or placement.revision != self.revision
+            ):
+                raise ValueError(
+                    f"logical transfer plan {side} placement identity differs"
+                )
+        if self.source_placement is not None and (
+            self.source_placement.weight_generation
+            != self.target_placement.weight_generation
+        ):
+            raise ValueError(
+                "logical transfer plan source and target weight_generation differs"
+            )
+        if self.source_manifest is not None and (
+            self.source_manifest.resource_id != self.resource_id
+            or self.source_manifest.revision != self.revision
+            or self.source_manifest.weight_generation
+            != self.target_placement.weight_generation
+        ):
+            raise ValueError("logical transfer plan source manifest identity differs")
+        for operation in self.operations:
+            _validate_logical_operation(operation, self.source_placement is not None)
+            if operation.segment_count > self.planning_limits.max_segments_per_region:
+                raise ValueError(
+                    "logical transfer plan exceeds max_segments_per_region"
+                )
+            total_lowered_segments += operation.segment_count
+            if total_lowered_segments > self.planning_limits.max_total_lowered_segments:
+                raise ValueError(
+                    "logical transfer plan exceeds max_total_lowered_segments"
+                )
+        if not all(
+            isinstance(executor, PlacementExecutorPlan)
+            for executor in (*self.source_executors, *self.target_executors)
+        ):
+            raise ValueError(
+                "logical transfer plan has invalid canonical executor metadata"
+            )
+        self.validate_source_manifest_snapshot()
+        object.__setattr__(
+            self,
+            "_operation_views",
+            _build_operation_views(
+                self.operations,
+                self.source_executors,
+                self.target_executors,
+            ),
+        )
+        # Keep construction strict without making the data-contract module own
+        # planner geometry validation.
+        from .validation import _validate_logical_target_coverage
+
+        _validate_logical_target_coverage(self)
+        self.validate_source_placement_snapshot()
+
+    @property
+    def total_bytes(self) -> int:
+        return sum(operation.total_bytes for operation in self.operations)
+
+    @property
+    def source_placement_id(self) -> Optional[PlacementId]:
+        return (
+            self.source_placement.placement_id
+            if self.source_placement is not None
+            else None
+        )
+
+    @property
+    def target_placement_id(self) -> PlacementId:
+        return self.target_placement.placement_id
+
+    def validate_source_manifest_snapshot(self) -> None:
+        """Fail closed if a stored source no longer matches its plan snapshot."""
+
+        if self.source_manifest is None:
+            if self.source_manifest_identity is not None:
+                raise ValueError("logical plan has unexpected source manifest identity")
+            return
+        source_manifest = validate_weight_manifest_snapshot(self.source_manifest)
+        if self.source_manifest_identity != source_manifest.manifest_identity:
+            raise ValueError("logical plan source manifest identity differs")
+        if self.source_tensors != _canonical_tensor_catalog(source_manifest.tensors):
+            raise ValueError("logical plan source tensor catalog differs")
+        source_by_id = {
+            fragment.fragment_id: fragment for fragment in source_manifest.fragments
+        }
+        for operation in self.operations:
+            source = operation.source
+            if (
+                not isinstance(source, StoredFragmentSnapshot)
+                or source_by_id.get(source.fragment_id) != source
+            ):
+                raise ValueError(
+                    "logical plan and source manifest fragment snapshots differ"
+                )
+
+    def validate_source_placement_snapshot(self) -> None:
+        """Fail closed if a placement source no longer matches its plan snapshot."""
+
+        if self.source_placement is None:
+            return
+
+        from .validation import _validate_logical_source_placement
+
+        _validate_logical_source_placement(self)
+
+    @property
+    def pipeline_routes(self) -> tuple[PipelineRouteGroup, ...]:
+        return self._operation_views.pipeline_routes
+
+    def operation_indices_for_executor(
+        self,
+        executor: PlacementExecutorPlan,
+        side: str,
+    ) -> tuple[int, ...]:
+        executors = self.source_executors if side == "source" else self.target_executors
+        if side not in ("source", "target"):
+            raise ValueError(f"invalid executor side: {side}")
+        if executor not in executors:
+            raise ValueError(f"{side} executor is not part of this logical plan")
+        return self._operation_views.operation_indices_for(executor, side)
+
+    def __getstate__(self) -> dict[str, object]:
+        return {
+            name: value
+            for name, value in self.__dict__.items()
+            if name != "_operation_views"
+        }
+
+    def __setstate__(self, state: dict[str, object]) -> None:
+        for name, value in state.items():
+            object.__setattr__(self, name, value)
+        self.__post_init__()
+
+
+def _canonical_tensor_catalog(
+    tensors: Sequence[TensorDescriptor],
+) -> tuple[TensorDescriptor, ...]:
+    """Compare tensor catalogs by canonical identity, not exporter order."""
+
+    return tuple(sorted(tensors, key=lambda item: item.tensor_id))
+
+
+def _executor_projection_key(
+    executor: Union[ExecutorTransferPlan, PlacementExecutorPlan],
+) -> ExecutorProjectionKey:
+    if isinstance(executor, PlacementExecutorPlan):
+        return (
+            executor.placement_id,
+            executor.participant_id,
+            executor.rank,
+            executor.placement_fragment_ids,
+        )
+    return (
+        executor.instance_id,
+        executor.placement_id,
+        executor.participant_id,
+        executor.placement_digest,
+        executor.runtime_lease_id,
+        executor.worker_id,
+        executor.rank,
+        executor.fragment_ids,
+    )
+
+
+def _fragment_projection_key(
+    fragment: GeometryFragment,
+) -> Optional[FragmentProjectionKey]:
+    if isinstance(fragment, BoundWeightFragment):
+        return "runtime", fragment.fragment_id
+    if isinstance(fragment, PlacementFragment):
+        return "placement", fragment.placement_fragment_id
+    return None
+
+
+def _index_executors_by_fragment(
+    executors: Sequence[Union[ExecutorTransferPlan, PlacementExecutorPlan]],
+) -> tuple[
+    dict[ExecutorProjectionKey, list[int]],
+    dict[FragmentProjectionKey, list[ExecutorProjectionKey]],
+]:
+    indices_by_executor: dict[ExecutorProjectionKey, list[int]] = {}
+    executors_by_fragment: dict[FragmentProjectionKey, list[ExecutorProjectionKey]] = {}
+    for executor in executors:
+        executor_key = _executor_projection_key(executor)
+        if executor_key in indices_by_executor:
+            raise ValueError("transfer plan has duplicate executor projection key")
+        indices_by_executor[executor_key] = []
+        fragment_ids: Sequence[str]
+        fragment_kind: str
+        if isinstance(executor, PlacementExecutorPlan):
+            fragment_ids = executor.placement_fragment_ids
+            fragment_kind = "placement"
+        else:
+            fragment_ids = executor.fragment_ids
+            fragment_kind = "runtime"
+        for fragment_id in fragment_ids:
+            executors_by_fragment.setdefault((fragment_kind, fragment_id), []).append(
+                executor_key
+            )
+    return indices_by_executor, executors_by_fragment
+
+
+def _build_operation_views(
+    operations: Sequence[Union[LogicalTransferOperation, ExecutableTransferOperation]],
+    source_executors: Sequence[Union[ExecutorTransferPlan, PlacementExecutorPlan]],
+    target_executors: Sequence[Union[ExecutorTransferPlan, PlacementExecutorPlan]],
+) -> _OperationViews:
+    source_indices, source_by_fragment = _index_executors_by_fragment(source_executors)
+    target_indices, target_by_fragment = _index_executors_by_fragment(target_executors)
+    for index, operation in enumerate(operations):
+        source_key = _fragment_projection_key(operation.source)
+        if source_key is not None:
+            for executor_key in source_by_fragment.get(source_key, ()):
+                source_indices[executor_key].append(index)
+        target_key = _fragment_projection_key(operation.target)
+        if target_key is not None:
+            for executor_key in target_by_fragment.get(target_key, ()):
+                target_indices[executor_key].append(index)
+    return _OperationViews(
+        source_indices=MappingProxyType(
+            {key: tuple(indices) for key, indices in source_indices.items()}
+        ),
+        target_indices=MappingProxyType(
+            {key: tuple(indices) for key, indices in target_indices.items()}
+        ),
+        pipeline_routes=_pipeline_routes(operations),
+    )
+
+
+def _pipeline_routes(
+    operations: Sequence[Union[LogicalTransferOperation, ExecutableTransferOperation]],
+) -> tuple[PipelineRouteGroup, ...]:
+    indices_by_route: dict[
+        tuple[Optional[int], Optional[int], int, Optional[int]],
+        list[int],
+    ] = {}
+    for index, operation in enumerate(operations):
+        source_pp = (
+            operation.source.rank.pp
+            if isinstance(operation.source, (BoundWeightFragment, PlacementFragment))
+            else None
+        )
+        source_pipeline_stage_id = (
+            operation.source.pipeline_stage_id
+            if isinstance(operation.source, (BoundWeightFragment, PlacementFragment))
+            else None
+        )
+        indices_by_route.setdefault(
+            (
+                source_pp,
+                source_pipeline_stage_id,
+                operation.target.rank.pp,
+                operation.target.pipeline_stage_id,
+            ),
+            [],
+        ).append(index)
+    return tuple(
+        PipelineRouteGroup(
+            source_pp=source_pp,
+            source_pipeline_stage_id=source_pipeline_stage_id,
+            target_pp=target_pp,
+            target_pipeline_stage_id=target_pipeline_stage_id,
+            operation_indices=tuple(indices),
+        )
+        for (
+            source_pp,
+            source_pipeline_stage_id,
+            target_pp,
+            target_pipeline_stage_id,
+        ), indices in sorted(
+            indices_by_route.items(),
+            key=lambda item: (
+                -1 if item[0][0] is None else item[0][0],
+                -1 if item[0][1] is None else item[0][1],
+                item[0][2],
+                -1 if item[0][3] is None else item[0][3],
+            ),
+        )
+    )
+
+
+__all__ = [
+    "BoundWeightFragment",
+    "LogicalTransferPlan",
+    "PlanningLimits",
+    "PipelineRouteGroup",
+    "PlacementExecutorPlan",
+    "RuntimeTensorOwner",
+    "ExecutableTransferOperation",
+    "ExecutableTransferRegion",
+    "LiveTransferOperation",
+    "LogicalTransferOperation",
+    "LogicalTransferRegion",
+    "StoredLoadOperation",
+    "TransferRegion",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/core.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/core.py
new file mode 100644
index 0000000000..d5798ebcde
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/core.py
@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from ...contracts import (
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    ResourceId,
+    RevisionId,
+    TensorId,
+)
+from ...geometry import boxes_exactly_cover
+from ..placement import WeightPlacementManifest
+from ..storage_manifest import StoredFragmentSnapshot, StoredWeightManifest
+from ..types import ParallelRank, PlacementFragment, TensorDescriptor
+from . import geometry
+from .contracts import (
+    LogicalTransferPlan,
+    LogicalTransferOperation,
+    PlacementExecutorPlan,
+    PlanningLimits,
+    TransferRegion,
+)
+from .fragments import LogicalSourceFragment, LogicalTargetFragment
+from .ownership import (
+    _validate_local_target_inventory,
+    _validate_target_coverage,
+    complete_dp_owned_source_owners,
+    complete_parallel_source_replicas,
+    has_dp_ownership,
+    parallel_tensor_owner,
+)
+from .validation import (
+    _validate_tensor_compatibility,
+    _validate_tensor_sets,
+    _validate_tensor_subset,
+)
+
+
+@dataclass(frozen=True)
+class _PlannedTransfer:
+    resource_id: ResourceId
+    revision: RevisionId
+    operations: tuple[LogicalTransferOperation, ...]
+    planning_limits: PlanningLimits
+
+
+def _collect_placements(
+    manifests: Sequence[WeightPlacementManifest],
+    label: str,
+) -> tuple[dict[TensorId, TensorDescriptor], list[PlacementFragment]]:
+    if not manifests:
+        raise ValueError(f"{label} placement manifests must not be empty")
+    if len(manifests) != 1:
+        raise ValueError(f"{label} requires one complete WeightPlacementManifest")
+    if any(not isinstance(manifest, WeightPlacementManifest) for manifest in manifests):
+        raise ValueError(f"{label} placement manifests must be WeightPlacementManifest")
+    resource_id = manifests[0].resource_id
+    revision = manifests[0].revision
+    placement_ids: set[PlacementId] = set()
+    fragment_ids: set[PlacementFragmentId] = set()
+    tensors: dict[TensorId, TensorDescriptor] = {}
+    fragments: list[PlacementFragment] = []
+    for manifest in manifests:
+        if manifest.resource_id != resource_id or manifest.revision != revision:
+            raise ValueError(
+                f"{label} placement manifests describe different revisions"
+            )
+        if manifest.placement_id in placement_ids:
+            raise ValueError(f"duplicate {label} placement_id: {manifest.placement_id}")
+        placement_ids.add(manifest.placement_id)
+        for tensor in manifest.tensors:
+            previous = tensors.setdefault(tensor.tensor_id, tensor)
+            if previous != tensor:
+                raise ValueError(
+                    f"{label} placement tensor descriptor mismatch: {tensor.tensor_id}"
+                )
+        for fragment in manifest.fragments:
+            if fragment.placement_fragment_id in fragment_ids:
+                raise ValueError(
+                    f"duplicate {label} placement fragment: "
+                    f"{fragment.placement_fragment_id}"
+                )
+            fragment_ids.add(fragment.placement_fragment_id)
+            fragments.append(fragment)
+    return tensors, fragments
+
+
+def _build_placement_executor_plans(
+    manifests: Sequence[WeightPlacementManifest],
+    operations: Sequence[LogicalTransferOperation],
+    side: str,
+    participant_ids: Optional[frozenset[ParticipantId]] = None,
+) -> tuple[PlacementExecutorPlan, ...]:
+    if side not in ("source", "target"):
+        raise ValueError(f"invalid placement executor side: {side}")
+    operation_indices_by_fragment: dict[PlacementFragmentId, list[int]] = {}
+    for index, operation in enumerate(operations):
+        fragment = operation.source if side == "source" else operation.target
+        if not isinstance(fragment, PlacementFragment):
+            raise ValueError(f"placement executor operation {side} is not a placement")
+        operation_indices_by_fragment.setdefault(
+            fragment.placement_fragment_id, []
+        ).append(index)
+
+    result: list[PlacementExecutorPlan] = []
+    ranks: set[ParallelRank] = set()
+    for manifest in manifests:
+        for part in manifest.parts:
+            if (
+                participant_ids is not None
+                and part.participant_id not in participant_ids
+            ):
+                continue
+            fragments = part.fragments
+            if not fragments:
+                continue
+            rank = part.rank
+            if rank in ranks:
+                raise ValueError(f"duplicate {side} placement executor rank: {rank}")
+            ranks.add(rank)
+            fragment_ids = tuple(
+                sorted(fragment.placement_fragment_id for fragment in fragments)
+            )
+            if not any(
+                fragment_id in operation_indices_by_fragment
+                for fragment_id in fragment_ids
+            ):
+                continue
+            result.append(
+                PlacementExecutorPlan(
+                    placement_id=manifest.placement_id,
+                    participant_id=part.participant_id,
+                    rank=rank,
+                    placement_fragment_ids=fragment_ids,
+                )
+            )
+    result.sort(
+        key=lambda item: (item.rank.dp, item.rank.pp, item.rank.ep, item.rank.tp)
+    )
+    return tuple(result)
+
+
+def _plan_transfer(
+    resource_id: ResourceId,
+    revision: RevisionId,
+    source_tensors: dict[TensorId, TensorDescriptor],
+    source_fragments: Sequence[LogicalSourceFragment],
+    target_tensors: dict[TensorId, TensorDescriptor],
+    target_fragments: Sequence[LogicalTargetFragment],
+    *,
+    local_target: bool = False,
+    planning_limits: Optional[PlanningLimits] = None,
+) -> _PlannedTransfer:
+    planning_limits = planning_limits or PlanningLimits()
+    if local_target:
+        _validate_tensor_subset(source_tensors, target_tensors)
+        _validate_local_target_inventory(target_tensors, target_fragments)
+    else:
+        _validate_tensor_sets(source_tensors, target_tensors)
+        _validate_target_coverage(target_tensors, target_fragments)
+    placement_source_fragments = tuple(
+        fragment
+        for fragment in source_fragments
+        if isinstance(fragment, PlacementFragment)
+    )
+    stored_source_fragments = tuple(
+        fragment
+        for fragment in source_fragments
+        if isinstance(fragment, StoredFragmentSnapshot)
+    )
+    if (
+        len(placement_source_fragments) + len(stored_source_fragments)
+        != len(source_fragments)
+        or not source_fragments
+    ):
+        raise ValueError("source fragments mix placement and stored locations")
+    if placement_source_fragments and stored_source_fragments:
+        raise ValueError("source fragments mix placement and stored locations")
+    parallel_sources = bool(placement_source_fragments)
+    source_replicas = (
+        complete_parallel_source_replicas(source_tensors, placement_source_fragments)
+        if parallel_sources
+        else {}
+    )
+    source_dp_owners = (
+        complete_dp_owned_source_owners(source_tensors, placement_source_fragments)
+        if parallel_sources
+        else {}
+    )
+    source_dp_ranks = sorted(source_replicas)
+    source_dp_by_target_dp = (
+        {
+            target_dp: source_dp_ranks[target_dp % len(source_dp_ranks)]
+            for target_dp in {fragment.rank.dp for fragment in target_fragments}
+        }
+        if parallel_sources and source_dp_ranks
+        else {}
+    )
+    candidates: dict[
+        TensorId,
+        dict[geometry.GeometryKey, list[LogicalSourceFragment]],
+    ] = {}
+    for fragment in source_fragments:
+        candidates.setdefault(fragment.tensor_id, {}).setdefault(
+            geometry._geometry_key(fragment), []
+        ).append(fragment)
+    for tensor_candidates in candidates.values():
+        for group in tensor_candidates.values():
+            group.sort(key=geometry._source_sort_key)
+    candidate_indexes = {
+        tensor_id: geometry._CandidateBoxIndex.build(
+            tuple(tuple(group) for group in tensor_candidates.values())
+        )
+        for tensor_id, tensor_candidates in candidates.items()
+    }
+
+    operations: list[TransferRegion[LogicalSourceFragment, LogicalTargetFragment]] = []
+    total_lowered_segments = 0
+    for target in sorted(target_fragments, key=lambda item: item.fragment_id):
+        target_tensor = target_tensors[target.tensor_id]
+        source_tensor = source_tensors.get(target.tensor_id)
+        if source_tensor is None:
+            raise ValueError(f"missing source tensor: {target.tensor_id}")
+        _validate_tensor_compatibility(source_tensor, target_tensor)
+
+        overlaps: list[
+            tuple[tuple[int, ...], tuple[int, ...], LogicalSourceFragment]
+        ] = []
+        candidate_index = candidate_indexes.get(target.tensor_id)
+        candidate_groups = (
+            candidate_index.query(target) if candidate_index is not None else ()
+        )
+        for group in candidate_groups:
+            if parallel_sources:
+                if has_dp_ownership(source_tensor):
+                    source_owner = source_dp_owners[target.tensor_id]
+                    eligible = [
+                        fragment
+                        for fragment in group
+                        if isinstance(fragment, PlacementFragment)
+                        and parallel_tensor_owner(source_tensor, fragment)
+                        == source_owner
+                    ]
+                else:
+                    source_dp = source_dp_by_target_dp[target.rank.dp]
+                    source_owner = source_replicas[source_dp][target.tensor_id]
+                    eligible = [
+                        fragment
+                        for fragment in group
+                        if isinstance(fragment, PlacementFragment)
+                        and fragment.rank.dp == source_dp
+                        and parallel_tensor_owner(source_tensor, fragment)
+                        == source_owner
+                    ]
+                if not eligible:
+                    continue
+                representative = eligible[0]
+                selected = representative
+            else:
+                representative = group[0]
+                selected = representative
+            overlap = geometry._overlap_box(representative, target)
+            if overlap is None:
+                continue
+            if (
+                len(operations) + len(overlaps) + 1
+                > planning_limits.max_transfer_regions
+            ):
+                raise ValueError(
+                    "logical transfer plan exceeds max_transfer_regions: "
+                    f"{planning_limits.max_transfer_regions}"
+                )
+            overlaps.append((*overlap, selected))
+        overlaps.sort(key=lambda item: (item[0], item[1], item[2].fragment_id))
+
+        if not boxes_exactly_cover(
+            target.global_offset,
+            target.local_shape,
+            tuple((offset, shape) for offset, shape, _ in overlaps),
+        ):
+            raise ValueError(
+                f"target fragment is not fully covered: {target.fragment_id}"
+            )
+        for overlap_offset, overlap_shape, source in overlaps:
+            region = geometry._transfer_region(
+                target_tensor,
+                source,
+                target,
+                overlap_offset,
+                overlap_shape,
+            )
+            if region.segment_count > planning_limits.max_segments_per_region:
+                raise ValueError(
+                    "logical transfer region exceeds max_segments_per_region: "
+                    f"{region.segment_count} > "
+                    f"{planning_limits.max_segments_per_region}"
+                )
+            next_total_lowered_segments = total_lowered_segments + region.segment_count
+            if next_total_lowered_segments > planning_limits.max_total_lowered_segments:
+                raise ValueError(
+                    "logical transfer plan exceeds max_total_lowered_segments: "
+                    f"{next_total_lowered_segments} > "
+                    f"{planning_limits.max_total_lowered_segments}"
+                )
+            operations.append(region)
+            total_lowered_segments = next_total_lowered_segments
+
+    operations.sort(
+        key=lambda item: (
+            item.target.fragment_id,
+            item.target_base_offset,
+            item.source.fragment_id,
+            item.source_base_offset,
+        )
+    )
+    return _PlannedTransfer(
+        resource_id=resource_id,
+        revision=revision,
+        operations=tuple(operations),
+        planning_limits=planning_limits,
+    )
+
+
+def _logical_transfer_plan(
+    transfer: _PlannedTransfer,
+    *,
+    source_tensors: dict[TensorId, TensorDescriptor],
+    target_tensors: dict[TensorId, TensorDescriptor],
+    source_placement: Optional[WeightPlacementManifest],
+    source_manifest: Optional[StoredWeightManifest],
+    target_placement: WeightPlacementManifest,
+    source_participant_ids: Optional[frozenset[ParticipantId]] = None,
+    target_participant_ids: Optional[frozenset[ParticipantId]] = None,
+) -> LogicalTransferPlan:
+    operations = transfer.operations
+    return LogicalTransferPlan(
+        resource_id=transfer.resource_id,
+        revision=transfer.revision,
+        source_placement=source_placement,
+        target_placement=target_placement,
+        source_tensors=tuple(
+            sorted(source_tensors.values(), key=lambda item: item.tensor_id)
+        ),
+        target_tensors=tuple(
+            sorted(target_tensors.values(), key=lambda item: item.tensor_id)
+        ),
+        operations=operations,
+        source_manifest=source_manifest,
+        planning_limits=transfer.planning_limits,
+        source_executors=(
+            _build_placement_executor_plans(
+                (source_placement,),
+                operations,
+                "source",
+                source_participant_ids,
+            )
+            if source_placement is not None
+            else ()
+        ),
+        target_executors=_build_placement_executor_plans(
+            (target_placement,),
+            operations,
+            "target",
+            target_participant_ids,
+        ),
+    )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/fragments.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/fragments.py
new file mode 100644
index 0000000000..d7e9f0fa32
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/fragments.py
@@ -0,0 +1,191 @@
+"""Nominal fragment types for each weight-transfer planning stage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Union
+
+from ..._typing import TypeAlias
+
+from ...contracts import (
+    LeaseId,
+    PlacementFragmentId,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    TensorId,
+)
+from ..manifest import ParallelRank, PlacementFragment, RuntimeBindingFragment
+from ..storage_manifest import StoredFragmentSnapshot
+from .attestation import RuntimeBindingAttestation
+
+
+_MAX_U64 = (1 << 64) - 1
+
+
+@dataclass(frozen=True)
+class BoundWeightFragment:
+    """A placement fragment bound to a live runtime allocation and lease."""
+
+    placement: PlacementFragment
+    binding: RuntimeBindingFragment
+    instance_id: RuntimeInstanceId
+    runtime_lease_id: LeaseId
+    lease_generation: int
+    owner: Optional[object] = field(default=None, compare=False, repr=False)
+    attestation: Optional[RuntimeBindingAttestation] = field(
+        default=None,
+        compare=False,
+        repr=False,
+    )
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.placement, PlacementFragment):
+            raise ValueError("bound fragment placement is invalid")
+        if not isinstance(self.binding, RuntimeBindingFragment):
+            raise ValueError("bound fragment runtime binding is invalid")
+        if self.placement.placement_fragment_id != self.binding.placement_fragment_id:
+            raise ValueError("bound fragment placement identity differs")
+        if self.placement.nbytes != self.binding.nbytes:
+            raise ValueError("bound fragment byte size differs")
+        if type(self.instance_id) is not str or not self.instance_id:
+            raise ValueError("bound fragment instance_id must be non-empty")
+        if type(self.runtime_lease_id) is not str or not self.runtime_lease_id:
+            raise ValueError("bound fragment runtime_lease_id must be non-empty")
+        if (
+            type(self.lease_generation) is not int
+            or self.lease_generation < 0
+            or self.lease_generation > _MAX_U64
+        ):
+            raise ValueError(
+                "bound fragment lease_generation must fit in an unsigned 64-bit integer"
+            )
+        if self.owner is not self.binding.owner:
+            raise ValueError("bound fragment owner differs from runtime binding")
+        if self.attestation is not None:
+            if not isinstance(self.attestation, RuntimeBindingAttestation):
+                raise ValueError("bound fragment runtime attestation is invalid")
+            if not self.attestation.validates(self.placement, self.binding):
+                raise ValueError(
+                    "bound fragment does not match its runtime binding attestation"
+                )
+            if (
+                self.instance_id != self.attestation.evidence.instance_id
+                or self.runtime_lease_id != self.attestation.evidence.lease_id
+                or self.lease_generation != self.attestation.evidence.generation
+            ):
+                raise ValueError(
+                    "bound fragment runtime fence differs from attestation"
+                )
+
+    def __reduce__(self):
+        """Serialize attested runtime evidence without a local allocation owner."""
+
+        return (
+            type(self),
+            (
+                self.placement,
+                self.binding,
+                self.instance_id,
+                self.runtime_lease_id,
+                self.lease_generation,
+                None,
+                self.attestation,
+            ),
+        )
+
+    @property
+    def placement_fragment_id(self) -> PlacementFragmentId:
+        return self.placement.placement_fragment_id
+
+    @property
+    def fragment_id(self) -> RuntimeFragmentId:
+        return self.binding.fragment_id
+
+    @property
+    def tensor_id(self) -> TensorId:
+        return self.placement.tensor_id
+
+    @property
+    def global_offset(self) -> tuple[int, ...]:
+        return self.placement.global_offset
+
+    @property
+    def local_shape(self) -> tuple[int, ...]:
+        return self.placement.local_shape
+
+    @property
+    def nbytes(self) -> int:
+        return self.binding.nbytes
+
+    @property
+    def rank(self) -> ParallelRank:
+        return self.placement.rank
+
+    @property
+    def pipeline_stage_id(self) -> Optional[int]:
+        return self.placement.pipeline_stage_id
+
+    @property
+    def aliases(self) -> tuple[TensorId, ...]:
+        return self.placement.aliases
+
+    @property
+    def address(self) -> int:
+        return self.binding.address
+
+    @property
+    def worker_id(self) -> str:
+        return self.binding.worker_id
+
+    @property
+    def endpoint(self) -> str:
+        return self.binding.endpoint
+
+    @property
+    def device(self) -> str:
+        return self.binding.device
+
+    @property
+    def storage_address(self) -> int:
+        return self.binding.storage_address
+
+    @property
+    def storage_nbytes(self) -> int:
+        return self.binding.storage_nbytes
+
+    @property
+    def storage_offset_bytes(self) -> int:
+        return self.binding.storage_offset_bytes
+
+
+# These aliases are intentionally stage-specific. A placement is immutable and
+# address-free; a bound fragment carries runtime lease/address state; a stored
+# fragment is a Store object range. Executors may only see the last two kinds.
+LogicalSourceFragment: TypeAlias = Union[PlacementFragment, StoredFragmentSnapshot]
+LogicalTargetFragment: TypeAlias = PlacementFragment
+ExecutableSourceFragment: TypeAlias = Union[BoundWeightFragment, StoredFragmentSnapshot]
+ExecutableTargetFragment: TypeAlias = BoundWeightFragment
+LiveSourceFragment: TypeAlias = BoundWeightFragment
+LiveTargetFragment: TypeAlias = BoundWeightFragment
+StoredLoadSourceFragment: TypeAlias = StoredFragmentSnapshot
+StoredLoadTargetFragment: TypeAlias = BoundWeightFragment
+GeometryFragment: TypeAlias = Union[
+    PlacementFragment,
+    StoredFragmentSnapshot,
+    BoundWeightFragment,
+]
+
+
+__all__ = [
+    "BoundWeightFragment",
+    "ExecutableSourceFragment",
+    "ExecutableTargetFragment",
+    "GeometryFragment",
+    "LiveSourceFragment",
+    "LiveTargetFragment",
+    "LogicalSourceFragment",
+    "LogicalTargetFragment",
+    "RuntimeBindingAttestation",
+    "StoredLoadSourceFragment",
+    "StoredLoadTargetFragment",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/geometry.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/geometry.py
new file mode 100644
index 0000000000..0dc252414d
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/geometry.py
@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import prod
+from typing import TYPE_CHECKING, Optional, Sequence, Union
+
+from ..._typing import TypeAlias
+
+from ..._compat import _strict_zip
+from ...contracts import TensorId
+from ..types import TensorDescriptor
+from ..storage_manifest import StoredFragmentSnapshot
+from .fragments import (
+    GeometryFragment,
+    LogicalSourceFragment,
+    LogicalTargetFragment,
+)
+
+if TYPE_CHECKING:
+    from .contracts import TransferRegion
+
+
+def _fragment_itemsize(fragment: GeometryFragment) -> int:
+    elements = prod(fragment.local_shape)
+    if elements <= 0 or fragment.nbytes % elements != 0:
+        raise ValueError("transfer region fragment byte size is invalid")
+    itemsize = fragment.nbytes // elements
+    if itemsize <= 0:
+        raise ValueError("transfer region fragment itemsize is invalid")
+    return itemsize
+
+
+def _logical_byte_offset(
+    fragment: GeometryFragment,
+    overlap_offset: tuple[int, ...],
+    itemsize: int,
+) -> int:
+    linear_offset = 0
+    stride = 1
+    for global_begin, local_begin, extent in _strict_zip(
+        reversed(overlap_offset),
+        reversed(fragment.global_offset),
+        reversed(fragment.local_shape),
+    ):
+        linear_offset += (global_begin - local_begin) * stride
+        stride *= extent
+    return linear_offset * itemsize
+
+
+def _validate_outer_strides(
+    counts: tuple[int, ...],
+    strides: tuple[int, ...],
+    inner_bytes: int,
+    side: str,
+) -> None:
+    span = inner_bytes
+    for count, stride in _strict_zip(reversed(counts), reversed(strides)):
+        if count > 1 and stride < span:
+            raise ValueError(f"transfer region {side} strides overlap")
+        span += (count - 1) * stride
+
+
+GeometryKey: TypeAlias = tuple[TensorId, tuple[int, ...], tuple[int, ...]]
+SourceSortKey: TypeAlias = Union[
+    tuple[int, int, int, int, str],
+    tuple[
+        int,
+        int,
+        int,
+        int,
+        str,
+        str,
+    ],
+]
+
+
+def _geometry_key(fragment: LogicalSourceFragment) -> GeometryKey:
+    return fragment.tensor_id, fragment.global_offset, fragment.local_shape
+
+
+def _source_sort_key(fragment: LogicalSourceFragment) -> SourceSortKey:
+    if isinstance(fragment, StoredFragmentSnapshot):
+        return (0, 0, 0, 0, fragment.object_key, fragment.fragment_id)
+    return (
+        fragment.rank.dp,
+        fragment.rank.pp,
+        fragment.rank.ep,
+        fragment.rank.tp,
+        fragment.fragment_id,
+    )
+
+
+@dataclass(frozen=True)
+class _CandidateInterval:
+    begin: int
+    end: int
+    group: tuple[LogicalSourceFragment, ...]
+
+
+@dataclass(frozen=True)
+class _CandidateIntervalNode:
+    center: int
+    crossing_by_begin: tuple[_CandidateInterval, ...]
+    crossing_by_end: tuple[_CandidateInterval, ...]
+    left: Optional[_CandidateIntervalNode] = None
+    right: Optional[_CandidateIntervalNode] = None
+
+    @classmethod
+    def build(
+        cls, intervals: Sequence[_CandidateInterval]
+    ) -> Optional[_CandidateIntervalNode]:
+        if not intervals:
+            return None
+        center = sorted((interval.begin + interval.end) // 2 for interval in intervals)[
+            len(intervals) // 2
+        ]
+        left: list[_CandidateInterval] = []
+        right: list[_CandidateInterval] = []
+        crossing: list[_CandidateInterval] = []
+        for interval in intervals:
+            if interval.end <= center:
+                left.append(interval)
+            elif interval.begin > center:
+                right.append(interval)
+            else:
+                crossing.append(interval)
+        return cls(
+            center=center,
+            crossing_by_begin=tuple(
+                sorted(crossing, key=lambda item: (item.begin, item.end))
+            ),
+            crossing_by_end=tuple(
+                sorted(crossing, key=lambda item: (item.end, item.begin))
+            ),
+            left=cls.build(left),
+            right=cls.build(right),
+        )
+
+    def query(
+        self,
+        begin: int,
+        end: int,
+        result: list[tuple[LogicalSourceFragment, ...]],
+    ) -> None:
+        if end <= self.center:
+            for interval in self.crossing_by_begin:
+                if interval.begin >= end:
+                    break
+                result.append(interval.group)
+            if self.left is not None:
+                self.left.query(begin, end, result)
+            return
+        if begin > self.center:
+            for interval in reversed(self.crossing_by_end):
+                if interval.end <= begin:
+                    break
+                result.append(interval.group)
+            if self.right is not None:
+                self.right.query(begin, end, result)
+            return
+
+        result.extend(interval.group for interval in self.crossing_by_begin)
+        if begin < self.center and self.left is not None:
+            self.left.query(begin, end, result)
+        if self.right is not None:
+            self.right.query(begin, end, result)
+
+
+@dataclass(frozen=True)
+class _CandidateBoxIndex:
+    dimension: int
+    root: _CandidateIntervalNode
+
+    @classmethod
+    def build(
+        cls, groups: Sequence[tuple[LogicalSourceFragment, ...]]
+    ) -> _CandidateBoxIndex:
+        if not groups:
+            raise ValueError("candidate box index requires source fragments")
+        ndim = len(groups[0][0].global_offset)
+        dimension = max(
+            range(ndim),
+            key=lambda dim: (
+                len(
+                    {
+                        (
+                            group[0].global_offset[dim],
+                            group[0].global_offset[dim] + group[0].local_shape[dim],
+                        )
+                        for group in groups
+                    }
+                ),
+                -dim,
+            ),
+        )
+        root = _CandidateIntervalNode.build(
+            tuple(
+                _CandidateInterval(
+                    begin=group[0].global_offset[dimension],
+                    end=(
+                        group[0].global_offset[dimension]
+                        + group[0].local_shape[dimension]
+                    ),
+                    group=group,
+                )
+                for group in groups
+            )
+        )
+        assert root is not None
+        return cls(dimension=dimension, root=root)
+
+    def query(
+        self, target: LogicalTargetFragment
+    ) -> tuple[tuple[LogicalSourceFragment, ...], ...]:
+        begin = target.global_offset[self.dimension]
+        result: list[tuple[LogicalSourceFragment, ...]] = []
+        self.root.query(
+            begin,
+            begin + target.local_shape[self.dimension],
+            result,
+        )
+        return tuple(result)
+
+
+def _overlap_box(
+    source: GeometryFragment,
+    target: GeometryFragment,
+) -> Optional[tuple[tuple[int, ...], tuple[int, ...]]]:
+    overlap_offset = tuple(
+        max(source_begin, target_begin)
+        for source_begin, target_begin in _strict_zip(
+            source.global_offset, target.global_offset
+        )
+    )
+    overlap_end = tuple(
+        min(
+            source_begin + source_extent,
+            target_begin + target_extent,
+        )
+        for source_begin, source_extent, target_begin, target_extent in _strict_zip(
+            source.global_offset,
+            source.local_shape,
+            target.global_offset,
+            target.local_shape,
+        )
+    )
+    overlap_shape = tuple(
+        end - begin for begin, end in _strict_zip(overlap_offset, overlap_end)
+    )
+    if any(extent <= 0 for extent in overlap_shape):
+        return None
+    return overlap_offset, overlap_shape
+
+
+def _canonical_byte_strides(shape: tuple[int, ...], itemsize: int) -> tuple[int, ...]:
+    result: list[int] = []
+    running = itemsize
+    for extent in reversed(shape):
+        result.append(running)
+        running *= extent
+    return tuple(reversed(result))
+
+
+def _derive_region_geometry(
+    source: GeometryFragment,
+    target: GeometryFragment,
+    overlap_offset: tuple[int, ...],
+    overlap_shape: tuple[int, ...],
+) -> tuple[
+    int,
+    int,
+    int,
+    tuple[int, ...],
+    tuple[int, ...],
+    tuple[int, ...],
+]:
+    source_itemsize = _fragment_itemsize(source)
+    target_itemsize = _fragment_itemsize(target)
+    if source_itemsize != target_itemsize:
+        raise ValueError("transfer region source and target itemsize differ")
+
+    source_byte_strides = _canonical_byte_strides(source.local_shape, source_itemsize)
+    target_byte_strides = _canonical_byte_strides(target.local_shape, target_itemsize)
+    source_base_offset = sum(
+        (overlap_begin - fragment_begin) * stride
+        for overlap_begin, fragment_begin, stride in _strict_zip(
+            overlap_offset,
+            source.global_offset,
+            source_byte_strides,
+        )
+    )
+    target_base_offset = sum(
+        (overlap_begin - fragment_begin) * stride
+        for overlap_begin, fragment_begin, stride in _strict_zip(
+            overlap_offset,
+            target.global_offset,
+            target_byte_strides,
+        )
+    )
+
+    suffix_begin = len(overlap_shape) - 1
+    inner_bytes = overlap_shape[-1] * source_itemsize
+    for dim in range(len(overlap_shape) - 2, -1, -1):
+        if (
+            source_byte_strides[dim] != inner_bytes
+            or target_byte_strides[dim] != inner_bytes
+        ):
+            break
+        inner_bytes *= overlap_shape[dim]
+        suffix_begin = dim
+
+    return (
+        source_base_offset,
+        target_base_offset,
+        inner_bytes,
+        overlap_shape[:suffix_begin],
+        source_byte_strides[:suffix_begin],
+        target_byte_strides[:suffix_begin],
+    )
+
+
+def _transfer_region(
+    tensor: TensorDescriptor,
+    source: LogicalSourceFragment,
+    target: LogicalTargetFragment,
+    overlap_offset: tuple[int, ...],
+    overlap_shape: tuple[int, ...],
+) -> "TransferRegion[LogicalSourceFragment, LogicalTargetFragment]":
+    from .contracts import TransferRegion as transfer_region
+
+    if (
+        _fragment_itemsize(source) != tensor.itemsize
+        or _fragment_itemsize(target) != tensor.itemsize
+    ):
+        raise ValueError("transfer region fragment itemsize differs from descriptor")
+    (
+        source_base_offset,
+        target_base_offset,
+        inner_bytes,
+        outer_loop_counts,
+        source_strides,
+        target_strides,
+    ) = _derive_region_geometry(source, target, overlap_offset, overlap_shape)
+
+    return transfer_region(
+        tensor_id=tensor.tensor_id,
+        source=source,
+        target=target,
+        overlap_offset=overlap_offset,
+        overlap_shape=overlap_shape,
+        source_base_offset=source_base_offset,
+        target_base_offset=target_base_offset,
+        inner_bytes=inner_bytes,
+        outer_loop_counts=outer_loop_counts,
+        source_strides=source_strides,
+        target_strides=target_strides,
+    )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/ownership.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/ownership.py
new file mode 100644
index 0000000000..40bbef4ad3
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/ownership.py
@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from ...contracts import TensorId
+from ...geometry import boxes_exactly_cover
+from ..manifest import OwnershipAxis, PlacementFragment, TensorDescriptor
+from .contracts import (
+    RuntimeTensorOwner,
+)
+from .fragments import LogicalSourceFragment, LogicalTargetFragment
+
+
+def _fragments_fully_cover_tensor(
+    tensor: TensorDescriptor,
+    fragments: Sequence[LogicalSourceFragment],
+) -> bool:
+    geometries = {
+        (fragment.global_offset, fragment.local_shape): fragment
+        for fragment in fragments
+        if fragment.tensor_id == tensor.tensor_id
+    }
+    boxes = tuple(geometries)
+    return boxes_exactly_cover(
+        (0,) * len(tensor.global_shape), tensor.global_shape, boxes
+    )
+
+
+def parallel_tensor_owner(
+    tensor: TensorDescriptor, fragment: PlacementFragment
+) -> RuntimeTensorOwner:
+    return tuple(
+        (axis.kind, getattr(fragment.rank, axis.kind))
+        for axis in tensor.parallel_axes
+        if isinstance(axis, OwnershipAxis)
+    )
+
+
+def has_dp_ownership(tensor: TensorDescriptor) -> bool:
+    """Return whether DP names tensor ownership instead of replica identity."""
+
+    return any(
+        isinstance(axis, OwnershipAxis) and axis.kind == "dp"
+        for axis in tensor.parallel_axes
+    )
+
+
+def complete_dp_owned_source_owners(
+    source_tensors: dict[TensorId, TensorDescriptor],
+    source_fragments: Sequence[PlacementFragment],
+) -> dict[TensorId, RuntimeTensorOwner]:
+    """Return the complete declared source owner for each DP-owned tensor.
+
+    Unlike a replicated DP tensor, an ``OwnershipAxis("dp")`` tensor is not
+    expected to exist on every DP rank. Its placement fragments name the owner
+    directly. A logical tensor may have exactly one complete owner; a partial
+    or duplicate owner declaration is ambiguous and rejected before planning.
+    """
+
+    owned_tensors = tuple(
+        tensor for tensor in source_tensors.values() if has_dp_ownership(tensor)
+    )
+    if not owned_tensors:
+        return {}
+
+    fragments_by_tensor: dict[TensorId, list[PlacementFragment]] = {}
+    for fragment in source_fragments:
+        fragments_by_tensor.setdefault(fragment.tensor_id, []).append(fragment)
+
+    owners: dict[TensorId, RuntimeTensorOwner] = {}
+    for tensor in owned_tensors:
+        fragments_by_owner: dict[RuntimeTensorOwner, list[PlacementFragment]] = {}
+        for fragment in fragments_by_tensor.get(tensor.tensor_id, ()):
+            fragments_by_owner.setdefault(
+                parallel_tensor_owner(tensor, fragment), []
+            ).append(fragment)
+        complete_owners = sorted(
+            owner
+            for owner, fragments in fragments_by_owner.items()
+            if _fragments_fully_cover_tensor(tensor, fragments)
+        )
+        if len(complete_owners) != 1 or len(complete_owners) != len(fragments_by_owner):
+            if not complete_owners:
+                raise ValueError(
+                    "DP-owned source tensor has no complete declared owner: "
+                    f"{tensor.tensor_id}"
+                )
+            raise ValueError(
+                "DP-owned source tensor has ambiguous declared owners: "
+                f"{tensor.tensor_id}"
+            )
+        owners[tensor.tensor_id] = complete_owners[0]
+    return owners
+
+
+def _validate_target_coverage(
+    target_tensors: dict[TensorId, TensorDescriptor],
+    target_fragments: Sequence[LogicalTargetFragment],
+) -> None:
+    if not target_fragments:
+        raise ValueError("target manifests have no fragments")
+    fragments_by_dp_and_tensor: dict[
+        int, dict[TensorId, list[LogicalTargetFragment]]
+    ] = {}
+    for fragment in target_fragments:
+        fragments_by_dp_and_tensor.setdefault(fragment.rank.dp, {}).setdefault(
+            fragment.tensor_id, []
+        ).append(fragment)
+    for tensor in target_tensors.values():
+        if has_dp_ownership(tensor):
+            fragments_by_owner: dict[
+                RuntimeTensorOwner, list[LogicalTargetFragment]
+            ] = {}
+            for by_tensor in fragments_by_dp_and_tensor.values():
+                for fragment in by_tensor.get(tensor.tensor_id, ()):
+                    fragments_by_owner.setdefault(
+                        parallel_tensor_owner(tensor, fragment), []
+                    ).append(fragment)
+            if not fragments_by_owner or any(
+                not _fragments_fully_cover_tensor(tensor, fragments)
+                for fragments in fragments_by_owner.values()
+            ):
+                raise ValueError(
+                    f"target tensor is not fully covered by its DP owner: "
+                    f"{tensor.tensor_id}"
+                )
+            continue
+        for dp_rank in sorted(fragments_by_dp_and_tensor):
+            fragments_by_owner: dict[
+                RuntimeTensorOwner, list[LogicalTargetFragment]
+            ] = {}
+            for fragment in fragments_by_dp_and_tensor[dp_rank].get(
+                tensor.tensor_id, ()
+            ):
+                fragments_by_owner.setdefault(
+                    parallel_tensor_owner(tensor, fragment), []
+                ).append(fragment)
+            if not fragments_by_owner or any(
+                not _fragments_fully_cover_tensor(tensor, fragments)
+                for fragments in fragments_by_owner.values()
+            ):
+                raise ValueError(
+                    f"target tensor is not fully covered: {tensor.tensor_id}: "
+                    f"dp={dp_rank}"
+                )
+
+
+def complete_parallel_source_replicas(
+    source_tensors: dict[TensorId, TensorDescriptor],
+    source_fragments: Sequence[PlacementFragment],
+) -> dict[int, dict[TensorId, RuntimeTensorOwner]]:
+    replicas: dict[int, dict[TensorId, RuntimeTensorOwner]] = {}
+    fragments_by_dp_and_tensor: dict[int, dict[TensorId, list[PlacementFragment]]] = {}
+    for fragment in source_fragments:
+        dp_rank = fragment.rank.dp
+        fragments_by_dp_and_tensor.setdefault(dp_rank, {}).setdefault(
+            fragment.tensor_id, []
+        ).append(fragment)
+    replica_tensors = tuple(
+        tensor for tensor in source_tensors.values() if not has_dp_ownership(tensor)
+    )
+    if not replica_tensors:
+        return {}
+    for dp_rank in sorted(fragments_by_dp_and_tensor):
+        owner_by_tensor: dict[TensorId, RuntimeTensorOwner] = {}
+        complete = True
+        for tensor in replica_tensors:
+            fragments_by_owner: dict[RuntimeTensorOwner, list[PlacementFragment]] = {}
+            for fragment in fragments_by_dp_and_tensor[dp_rank].get(
+                tensor.tensor_id, ()
+            ):
+                fragments_by_owner.setdefault(
+                    parallel_tensor_owner(tensor, fragment), []
+                ).append(fragment)
+            complete_owners = [
+                owner
+                for owner, fragments in fragments_by_owner.items()
+                if _fragments_fully_cover_tensor(tensor, fragments)
+            ]
+            if not fragments_by_owner or len(complete_owners) != len(
+                fragments_by_owner
+            ):
+                complete = False
+                break
+            owner_by_tensor[tensor.tensor_id] = min(complete_owners)
+        if complete:
+            replicas[dp_rank] = owner_by_tensor
+    if not replicas:
+        raise ValueError(
+            "source manifests have no complete DP replica; tensors are not fully covered"
+        )
+    return replicas
+
+
+def _validate_local_target_inventory(
+    target_tensors: dict[TensorId, TensorDescriptor],
+    target_fragments: Sequence[LogicalTargetFragment],
+) -> None:
+    if not target_fragments:
+        raise ValueError("local target manifest has no fragments")
+    ranks = {fragment.rank for fragment in target_fragments}
+    if len(ranks) != 1:
+        raise ValueError("local target manifest must describe exactly one executor")
+    missing = sorted(
+        set(target_tensors) - {item.tensor_id for item in target_fragments}
+    )
+    if missing:
+        raise ValueError(
+            f"local target manifest is missing fragments: {', '.join(missing)}"
+        )
+
+
+__all__ = [
+    "complete_dp_owned_source_owners",
+    "complete_parallel_source_replicas",
+    "has_dp_ownership",
+    "parallel_tensor_owner",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_planner/validation.py b/mooncake-reshard/python/mooncake/reshard/weight/_planner/validation.py
new file mode 100644
index 0000000000..47cd91b997
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_planner/validation.py
@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from ...contracts import ParticipantId, PlacementFragmentId, TensorId
+from ...geometry import regions_exactly_cover
+from ..manifest import (
+    PlacementFragment,
+    TensorDescriptor,
+)
+from .contracts import (
+    LogicalTransferOperation,
+    LogicalTransferPlan,
+)
+
+
+def _validate_logical_target_coverage(logical_plan: LogicalTransferPlan) -> None:
+    """Reject plans that would leave a selected target fragment unwritten."""
+
+    target_parts = {
+        part.participant_id: part for part in logical_plan.target_placement.parts
+    }
+    participant_by_fragment = {
+        fragment.placement_fragment_id: part.participant_id
+        for part in logical_plan.target_placement.parts
+        for fragment in part.fragments
+    }
+    operation_participants: set[ParticipantId] = set()
+    operations_by_fragment: dict[
+        PlacementFragmentId, list[LogicalTransferOperation]
+    ] = {}
+
+    for operation in logical_plan.operations:
+        target = operation.target
+        if not isinstance(target, PlacementFragment):
+            raise ValueError("logical transfer operation target must be a placement")
+        target_participant_id = participant_by_fragment.get(
+            target.placement_fragment_id
+        )
+        if target_participant_id is None or not any(
+            fragment == target
+            for fragment in target_parts[target_participant_id].fragments
+        ):
+            raise ValueError(
+                "logical plan and target placement fragment snapshots differ"
+            )
+        operations_by_fragment.setdefault(target.placement_fragment_id, []).append(
+            operation
+        )
+        operation_participants.add(target_participant_id)
+
+    if not logical_plan.target_executors:
+        raise ValueError("logical plan has no target executor metadata")
+
+    seen_participants: set[ParticipantId] = set()
+    selected_fragments: dict[PlacementFragmentId, PlacementFragment] = {}
+    selected_tensors: dict[TensorId, TensorDescriptor] = {}
+    for executor in logical_plan.target_executors:
+        if executor.placement_id != logical_plan.target_placement.placement_id:
+            raise ValueError("logical target executor placement differs from target")
+        if executor.participant_id in seen_participants:
+            raise ValueError("logical plan has duplicate target executor participant")
+        seen_participants.add(executor.participant_id)
+        part = target_parts.get(executor.participant_id)
+        if part is None or executor.rank != part.rank:
+            raise ValueError("logical target executor differs from target placement")
+        expected_fragment_ids = tuple(
+            sorted(fragment.placement_fragment_id for fragment in part.fragments)
+        )
+        if executor.placement_fragment_ids != expected_fragment_ids:
+            raise ValueError(
+                "logical target executor fragments differ from target placement"
+            )
+        if not logical_plan.operation_indices_for_executor(executor, "target"):
+            raise ValueError(
+                "logical target executor operations differ from target placement"
+            )
+        selected_fragments.update(
+            {fragment.placement_fragment_id: fragment for fragment in part.fragments}
+        )
+        for tensor in part.tensors:
+            previous = selected_tensors.setdefault(tensor.tensor_id, tensor)
+            if previous != tensor:
+                raise ValueError("logical target tensor catalog differs from placement")
+
+    if seen_participants != operation_participants:
+        raise ValueError("logical target executors differ from planned operations")
+    if logical_plan.target_tensors != tuple(
+        sorted(selected_tensors.values(), key=lambda item: item.tensor_id)
+    ):
+        raise ValueError("logical target tensor catalog differs from placement")
+
+    for fragment_id, target in selected_fragments.items():
+        operations = operations_by_fragment.get(fragment_id, ())
+        if not regions_exactly_cover(target, operations):
+            raise ValueError(
+                f"logical target fragment is not fully covered: {fragment_id}"
+            )
+
+
+def _validate_logical_source_placement(logical_plan: LogicalTransferPlan) -> None:
+    """Reject placement-source plans whose public projections contradict the source."""
+
+    source_placement = logical_plan.source_placement
+    if source_placement is None:
+        return
+    if logical_plan.source_tensors != source_placement.tensors:
+        raise ValueError("logical plan source tensor catalog differs from placement")
+    if not logical_plan.source_executors:
+        raise ValueError("logical plan has no source executor metadata")
+
+    source_parts = {part.participant_id: part for part in source_placement.parts}
+    participant_by_fragment = {
+        fragment.placement_fragment_id: part.participant_id
+        for part in source_placement.parts
+        for fragment in part.fragments
+    }
+    operation_participants: set[ParticipantId] = set()
+    for operation in logical_plan.operations:
+        source = operation.source
+        if not isinstance(source, PlacementFragment):
+            raise ValueError("logical transfer operation source must be a placement")
+        source_participant_id = participant_by_fragment.get(
+            source.placement_fragment_id
+        )
+        if source_participant_id is None or not any(
+            fragment == source
+            for fragment in source_parts[source_participant_id].fragments
+        ):
+            raise ValueError(
+                "logical plan and source placement fragment snapshots differ"
+            )
+        operation_participants.add(source_participant_id)
+
+    seen_participants: set[ParticipantId] = set()
+    for executor in logical_plan.source_executors:
+        if executor.placement_id != source_placement.placement_id:
+            raise ValueError("logical source executor placement differs from source")
+        if executor.participant_id in seen_participants:
+            raise ValueError("logical plan has duplicate source executor participant")
+        seen_participants.add(executor.participant_id)
+        part = source_parts.get(executor.participant_id)
+        if part is None or executor.rank != part.rank:
+            raise ValueError("logical source executor differs from source placement")
+        expected_fragment_ids = tuple(
+            sorted(fragment.placement_fragment_id for fragment in part.fragments)
+        )
+        if executor.placement_fragment_ids != expected_fragment_ids:
+            raise ValueError(
+                "logical source executor fragments differ from source placement"
+            )
+        if not logical_plan.operation_indices_for_executor(executor, "source"):
+            raise ValueError(
+                "logical source executor operations differ from source placement"
+            )
+
+    if seen_participants != operation_participants:
+        raise ValueError("logical source executors differ from planned operations")
+
+
+def _validate_tensor_compatibility(
+    source: TensorDescriptor, target: TensorDescriptor
+) -> None:
+    if source.layout_fingerprint != target.layout_fingerprint:
+        raise ValueError(f"layout mismatch for tensor {source.tensor_id}")
+    if (
+        source.global_shape != target.global_shape
+        or source.dtype != target.dtype
+        or source.itemsize != target.itemsize
+        or source.layer_id != target.layer_id
+        or source.expert_id != target.expert_id
+    ):
+        raise ValueError(f"tensor descriptor mismatch: {source.tensor_id}")
+
+
+def _validate_tensor_sets(
+    source_tensors: dict[TensorId, TensorDescriptor],
+    target_tensors: dict[TensorId, TensorDescriptor],
+) -> None:
+    source_ids = set(source_tensors)
+    target_ids = set(target_tensors)
+    missing = sorted(source_ids - target_ids)
+    if missing:
+        raise ValueError(f"target manifests are missing tensors: {', '.join(missing)}")
+    unexpected = sorted(target_ids - source_ids)
+    if unexpected:
+        raise ValueError(
+            f"target manifests contain unknown tensors: {', '.join(unexpected)}"
+        )
+
+
+def _validate_tensor_subset(
+    source_tensors: dict[TensorId, TensorDescriptor],
+    target_tensors: dict[TensorId, TensorDescriptor],
+) -> None:
+    unexpected = sorted(set(target_tensors) - set(source_tensors))
+    if unexpected:
+        raise ValueError(
+            f"target manifests contain unknown tensors: {', '.join(unexpected)}"
+        )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/__init__.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/__init__.py
new file mode 100644
index 0000000000..7bc49b7a16
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/__init__.py
@@ -0,0 +1,37 @@
+from .store import WeightStore, WeightStoreError
+from .registration import StoreRegistrationLease
+from .contracts import (
+    UploadOperation,
+    UploadReceipt,
+    WeightLoadPlan,
+    WeightUploadPlan,
+)
+from .payload import PayloadStoreOperations
+from .transaction import WeightUploadTransaction
+from .snapshot import (
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+)
+from .writer import (
+    WeightStoreWriter,
+)
+from .entrypoint import begin_weight_snapshot
+from .upload import WeightUploadService, plan_weight_upload
+
+__all__ = [
+    "PayloadStoreOperations",
+    "UploadOperation",
+    "UploadReceipt",
+    "WeightLoadPlan",
+    "WeightStore",
+    "WeightStoreError",
+    "WeightSnapshotAdapter",
+    "WeightSnapshotDescriptor",
+    "WeightStoreWriter",
+    "begin_weight_snapshot",
+    "StoreRegistrationLease",
+    "WeightUploadService",
+    "WeightUploadTransaction",
+    "WeightUploadPlan",
+    "plan_weight_upload",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/backend.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/backend.py
new file mode 100644
index 0000000000..89efe37fac
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/backend.py
@@ -0,0 +1,258 @@
+"""Fail-closed adapter for the native Mooncake Store object boundary."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from importlib import import_module
+from typing import Literal, Optional, Protocol, cast
+
+from ..._typing import TypeAlias
+
+from .errors import WeightStoreError
+
+
+StoreRecordType: TypeAlias = Literal["payload", "metadata"]
+StoreConfigFactory: TypeAlias = Callable[[Sequence[str], StoreRecordType], object]
+RangeResults: TypeAlias = tuple[tuple[tuple[int, ...], ...], ...]
+RangedReadSnapshot: TypeAlias = object
+
+
+class _NativeReplicateConfig(Protocol):
+    group_ids: list[str]
+    with_hard_pin: bool
+    data_type: object
+
+
+def default_config_factory(
+    group_ids: Sequence[str], record_type: StoreRecordType
+) -> object:
+    """Build a native replication config without importing it in canonical code."""
+
+    try:
+        module = import_module("mooncake.store")
+        replicate_config_type = getattr(module, "ReplicateConfig")
+        object_data_type = getattr(module, "ObjectDataType")
+    except (ImportError, AttributeError) as error:
+        raise WeightStoreError(
+            "native Mooncake Store configuration is unavailable"
+        ) from error
+    if not callable(replicate_config_type):
+        raise WeightStoreError("native ReplicateConfig constructor is invalid")
+    try:
+        config = cast(_NativeReplicateConfig, replicate_config_type())
+        config.group_ids = list(group_ids)
+    except AttributeError as error:
+        raise WeightStoreError(
+            "native Mooncake Store must expose ReplicateConfig.group_ids"
+        ) from error
+    try:
+        config.with_hard_pin = True
+        if record_type == "payload":
+            config.data_type = object_data_type.WEIGHT
+        else:
+            config.data_type = object_data_type.METADATA
+    except (AttributeError, TypeError, ValueError) as error:
+        raise WeightStoreError(
+            "native Mooncake Store configuration is invalid"
+        ) from error
+    return config
+
+
+class StoreBackend:
+    """Normalize the raw Store API to checked operations used by weight flows."""
+
+    def __init__(self, raw: object) -> None:
+        self._raw = raw
+
+    def get(self, key: str) -> bytes:
+        result = self._call("get", key)
+        if isinstance(result, bytearray):
+            return bytes(result)
+        if isinstance(result, bytes):
+            return result
+        raise WeightStoreError(f"get returned invalid payload for {key}")
+
+    def put(self, key: str, value: bytes, config: object) -> int:
+        return self._status("put", key, value, config)
+
+    def remove(self, key: str, *, force: bool) -> int:
+        return self._status("remove", key, force=force)
+
+    def is_exist(self, key: str) -> int:
+        result = self._call("is_exist", key)
+        if type(result) is not int:
+            raise WeightStoreError(f"is_exist returned invalid status for {key}")
+        return result
+
+    def batch_is_exist(self, keys: Sequence[str]) -> Optional[tuple[int, ...]]:
+        candidate = self._optional_method("batch_is_exist")
+        if candidate is None:
+            return None
+        result = self._invoke(candidate, list(keys), operation="batch_is_exist")
+        if type(result) is int:
+            raise WeightStoreError(f"existence check failed: {result}")
+        return self._int_sequence(result, "batch_is_exist")
+
+    def batch_put_from(
+        self,
+        keys: Sequence[str],
+        addresses: Sequence[int],
+        sizes: Sequence[int],
+        config: object,
+    ) -> tuple[int, ...]:
+        result = self._call(
+            "batch_put_from",
+            list(keys),
+            list(addresses),
+            list(sizes),
+            config,
+        )
+        return self._int_sequence(result, "batch_put_from")
+
+    def register_buffer(self, address: int, nbytes: int) -> int:
+        return self._status("register_buffer", address, nbytes)
+
+    def unregister_buffer(self, address: int) -> int:
+        return self._status("unregister_buffer", address)
+
+    def prepare_get_into_ranges_snapshot(
+        self, keys: Sequence[str]
+    ) -> Optional[RangedReadSnapshot]:
+        prepare = self._optional_method("prepare_get_into_ranges_snapshot")
+        read = self._optional_method("get_into_ranges_from_snapshot")
+        if prepare is None and read is None:
+            return None
+        if prepare is None or read is None:
+            raise WeightStoreError(
+                "Store backend must expose both ranged-read snapshot methods"
+            )
+        unique_keys = list(dict.fromkeys(keys))
+        snapshot = self._invoke(
+            prepare,
+            unique_keys,
+            operation="prepare_get_into_ranges_snapshot",
+        )
+        if snapshot is None:
+            raise WeightStoreError("Store returned an invalid ranged-read snapshot")
+        return snapshot
+
+    def get_into_ranges(
+        self,
+        addresses: Sequence[int],
+        all_keys: Sequence[Sequence[str]],
+        all_target_offsets: Sequence[Sequence[Sequence[int]]],
+        all_source_offsets: Sequence[Sequence[Sequence[int]]],
+        all_sizes: Sequence[Sequence[Sequence[int]]],
+        *,
+        snapshot: Optional[RangedReadSnapshot] = None,
+    ) -> RangeResults:
+        if snapshot is None:
+            method = self._required_method("get_into_ranges")
+            args: tuple[object, ...] = ()
+            operation = "get_into_ranges"
+        else:
+            method = self._required_method("get_into_ranges_from_snapshot")
+            args = (snapshot,)
+            operation = "get_into_ranges_from_snapshot"
+        result = self._invoke(
+            method,
+            *args,
+            list(addresses),
+            [list(keys) for keys in all_keys],
+            [[list(offsets) for offsets in groups] for groups in all_target_offsets],
+            [[list(offsets) for offsets in groups] for groups in all_source_offsets],
+            [[list(sizes) for sizes in groups] for groups in all_sizes],
+            operation=operation,
+        )
+        return self._range_results(result)
+
+    def _status(self, method_name: str, *args: object, **kwargs: object) -> int:
+        result = self._call(method_name, *args, **kwargs)
+        if type(result) is not int:
+            raise WeightStoreError(f"{method_name} returned an invalid status")
+        return result
+
+    def _call(self, method_name: str, *args: object, **kwargs: object) -> object:
+        method = self._required_method(method_name)
+        return self._invoke(method, *args, operation=method_name, **kwargs)
+
+    def _required_method(self, method_name: str) -> Callable[..., object]:
+        method = self._optional_method(method_name)
+        if method is None:
+            raise WeightStoreError(f"Store backend does not implement {method_name}")
+        return method
+
+    def _optional_method(
+        self,
+        method_name: str,
+    ) -> Optional[Callable[..., object]]:
+        try:
+            candidate = getattr(self._raw, method_name, None)
+        except Exception as error:
+            raise WeightStoreError(
+                f"failed to access Store method {method_name}"
+            ) from error
+        if candidate is None:
+            return None
+        if not callable(candidate):
+            raise WeightStoreError(f"Store attribute {method_name} is not callable")
+        return candidate
+
+    @staticmethod
+    def _invoke(
+        method: Callable[..., object],
+        *args: object,
+        operation: str,
+        **kwargs: object,
+    ) -> object:
+        try:
+            return method(*args, **kwargs)
+        except Exception as error:
+            raise WeightStoreError(f"{operation} failed: {error}") from error
+
+    @staticmethod
+    def _int_sequence(value: object, operation: str) -> tuple[int, ...]:
+        if type(value) is int:
+            raise WeightStoreError(f"{operation} failed: {value}")
+        if isinstance(value, (str, bytes, bytearray)) or not isinstance(
+            value, Sequence
+        ):
+            raise WeightStoreError(f"{operation} returned invalid result sequence")
+        values = tuple(cast(Sequence[object], value))
+        if any(type(item) is not int for item in values):
+            raise WeightStoreError(f"{operation} returned non-integer status")
+        return cast(tuple[int, ...], values)
+
+    @classmethod
+    def _range_results(cls, value: object) -> RangeResults:
+        if type(value) is int:
+            raise WeightStoreError(f"get_into_ranges failed: {value}")
+        if isinstance(value, (str, bytes, bytearray)) or not isinstance(
+            value, Sequence
+        ):
+            raise WeightStoreError("get_into_ranges returned invalid buffer result")
+        buffers: list[tuple[tuple[int, ...], ...]] = []
+        for buffer_result in cast(Sequence[object], value):
+            buffers.append(cls._range_buffer_result(buffer_result))
+        return tuple(buffers)
+
+    @staticmethod
+    def _range_buffer_result(value: object) -> tuple[tuple[int, ...], ...]:
+        if isinstance(value, (str, bytes, bytearray)) or not isinstance(
+            value, Sequence
+        ):
+            raise WeightStoreError("get_into_ranges returned invalid object result")
+        groups: list[tuple[int, ...]] = []
+        for group in cast(Sequence[object], value):
+            groups.append(StoreBackend._int_sequence(group, "get_into_ranges"))
+        return tuple(groups)
+
+
+__all__ = [
+    "RangeResults",
+    "RangedReadSnapshot",
+    "StoreBackend",
+    "StoreConfigFactory",
+    "StoreRecordType",
+    "default_config_factory",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/contracts.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/contracts.py
new file mode 100644
index 0000000000..d7ee79d179
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/contracts.py
@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import cast
+
+from ...contracts import (
+    LeaseId,
+    ParticipantId,
+    PlacementId,
+    RuntimeInstanceId,
+    StoredFragmentSnapshotId,
+)
+from ..manifest import PlacementFragment
+from ..planner import (
+    BoundWeightFragment,
+    ExecutableTransferOperation,
+    RuntimeFragmentSnapshot,
+    StoredLoadOperation,
+    TransferPlan,
+)
+from ..storage_manifest import StoredFragmentSnapshot, StoredWeightManifest
+
+
+_MAX_U64 = (1 << 64) - 1
+
+
+def _require_nonempty_string(value: object, name: str) -> None:
+    if type(value) is not str or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+
+
+def _require_u64(value: object, name: str) -> None:
+    if type(value) is not int or value < 0 or value > _MAX_U64:
+        raise ValueError(f"{name} must fit in an unsigned 64-bit integer")
+
+
+@dataclass(frozen=True)
+class UploadOperation:
+    source_placement: PlacementFragment
+    source_snapshot: RuntimeFragmentSnapshot
+    source_participant_id: ParticipantId
+    source_instance_id: RuntimeInstanceId
+    target: StoredFragmentSnapshot
+    source_generation: int
+    source_lease_id: LeaseId
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.source_placement, PlacementFragment):
+            raise ValueError("upload source placement is invalid")
+        if not isinstance(self.source_snapshot, RuntimeFragmentSnapshot):
+            raise ValueError("upload source snapshot is invalid")
+        if not isinstance(self.target, StoredFragmentSnapshot):
+            raise ValueError("upload target is invalid")
+        for name in (
+            "source_participant_id",
+            "source_instance_id",
+            "source_lease_id",
+        ):
+            _require_nonempty_string(getattr(self, name), name)
+        _require_u64(self.source_generation, "source_generation")
+        if (
+            self.source_snapshot.placement_fragment_id
+            != self.source_placement.placement_fragment_id
+        ):
+            raise ValueError("upload source placement and binding differ")
+        if (
+            self.source_snapshot.nbytes != self.source_placement.nbytes
+            or self.source_snapshot.local_shape != self.source_placement.local_shape
+            or self.source_snapshot.tensor_id != self.source_placement.tensor_id
+            or self.source_snapshot.global_offset != self.source_placement.global_offset
+        ):
+            raise ValueError("upload source geometry differs")
+        if (
+            self.target.tensor_id != self.source_placement.tensor_id
+            or self.target.global_offset != self.source_placement.global_offset
+            or self.target.local_shape != self.source_placement.local_shape
+            or self.target.nbytes != self.source_placement.nbytes
+            or self.target.aliases != self.source_placement.aliases
+        ):
+            raise ValueError("upload source and target geometry differ")
+        if self.target.object_offset != 0:
+            raise ValueError("upload target object_offset must be zero")
+        if self.source_snapshot.lease_generation != self.source_generation:
+            raise ValueError("upload source snapshot generation differs")
+
+
+@dataclass(frozen=True)
+class WeightUploadPlan:
+    manifest: StoredWeightManifest
+    source_placement_id: PlacementId
+    source_placement_digest: str
+    transaction_group_id: str
+    control_key: str
+    operations: tuple[UploadOperation, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.manifest, StoredWeightManifest):
+            raise ValueError("upload plan manifest is invalid")
+        _require_nonempty_string(self.source_placement_id, "source_placement_id")
+        _require_nonempty_string(
+            self.source_placement_digest, "source_placement_digest"
+        )
+        _require_nonempty_string(self.transaction_group_id, "transaction_group_id")
+        _require_nonempty_string(self.control_key, "control_key")
+        operations = tuple(self.operations)
+        if not operations or not all(
+            isinstance(operation, UploadOperation) for operation in operations
+        ):
+            raise ValueError("upload plan operations are invalid")
+        object.__setattr__(self, "operations", operations)
+        transaction_prefix = f"{self.manifest.group_id}/transactions/"
+        if not self.transaction_group_id.startswith(transaction_prefix):
+            raise ValueError(
+                "upload transaction group does not belong to manifest group"
+            )
+        transaction_id = self.transaction_group_id[len(transaction_prefix) :]
+        if not transaction_id or "/" in transaction_id:
+            raise ValueError("upload transaction group has an invalid upload ID")
+        if self.control_key != f"{self.transaction_group_id}/decision":
+            raise ValueError("upload control key does not belong to transaction group")
+        operation_targets = tuple(
+            sorted(
+                (operation.target for operation in operations),
+                key=lambda fragment: fragment.fragment_id,
+            )
+        )
+        manifest_fragments = tuple(
+            sorted(
+                self.manifest.fragments,
+                key=lambda fragment: fragment.fragment_id,
+            )
+        )
+        if operation_targets != manifest_fragments:
+            raise ValueError("upload plan operations and manifest differ")
+        payload_prefix = f"{self.manifest.group_id}/payload/"
+        if any(
+            operation.target.object_key[len(payload_prefix) :].split("/", 1)[0]
+            != transaction_id
+            for operation in operations
+        ):
+            raise ValueError("upload transaction does not own payload members")
+
+
+@dataclass(frozen=True)
+class UploadReceipt:
+    fragment_id: StoredFragmentSnapshotId
+    object_key: str
+    worker_id: str
+
+    def __post_init__(self) -> None:
+        for name in ("fragment_id", "object_key", "worker_id"):
+            _require_nonempty_string(getattr(self, name), name)
+
+
+@dataclass(frozen=True)
+class WeightLoadPlan:
+    manifest: StoredWeightManifest
+    transfer: TransferPlan
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.manifest, StoredWeightManifest):
+            raise ValueError("load plan manifest is invalid")
+        if not isinstance(self.transfer, TransferPlan):
+            raise ValueError("load plan transfer is invalid")
+        if (
+            self.transfer.resource_id != self.manifest.resource_id
+            or self.transfer.revision != self.manifest.revision
+            or self.transfer.weight_generation != self.manifest.weight_generation
+        ):
+            raise ValueError("load plan transfer and manifest identity differ")
+        if self.transfer.source_manifest_identity != self.manifest.manifest_identity:
+            raise ValueError("load plan transfer source manifest differs")
+        if not self.transfer.operations:
+            raise ValueError("load plan must transfer stored fragments to runtime")
+        stored_operations = tuple(
+            _require_stored_load_operation(operation)
+            for operation in self.transfer.operations
+        )
+        manifest_fragments = {
+            fragment.fragment_id: fragment for fragment in self.manifest.fragments
+        }
+        planned_sources: dict[StoredFragmentSnapshotId, StoredFragmentSnapshot] = {}
+        for operation in stored_operations:
+            source = operation.source
+            previous = planned_sources.setdefault(source.fragment_id, source)
+            if previous != source:
+                raise ValueError("load plan contains conflicting stored fragments")
+        for fragment_id, planned in planned_sources.items():
+            if manifest_fragments.get(fragment_id) != planned:
+                raise ValueError("load plan sources and manifest differ")
+
+
+__all__ = [
+    "UploadOperation",
+    "UploadReceipt",
+    "WeightLoadPlan",
+    "WeightUploadPlan",
+]
+
+
+def _require_stored_load_operation(
+    operation: ExecutableTransferOperation,
+) -> StoredLoadOperation:
+    if not isinstance(operation.source, StoredFragmentSnapshot) or not isinstance(
+        operation.target, BoundWeightFragment
+    ):
+        raise ValueError("load plan must transfer stored fragments to runtime")
+    return cast(StoredLoadOperation, operation)
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/entrypoint.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/entrypoint.py
new file mode 100644
index 0000000000..b154134e84
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/entrypoint.py
@@ -0,0 +1,25 @@
+"""Native Store entry point for manifest-backed model-weight snapshots."""
+
+from __future__ import annotations
+
+from .store import WeightStore
+from .snapshot import (
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+)
+from .writer import (
+    WeightStoreWriter,
+)
+
+
+def begin_weight_snapshot(
+    store: object,
+    snapshot: WeightSnapshotDescriptor,
+    adapter: WeightSnapshotAdapter,
+) -> WeightStoreWriter:
+    """Open an explicit manifest-backed model-weight snapshot writer."""
+
+    return WeightStore(store).begin_weight_snapshot(snapshot, adapter)
+
+
+__all__ = ["begin_weight_snapshot"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/errors.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/errors.py
new file mode 100644
index 0000000000..f750f0001b
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/errors.py
@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class WeightStoreError(RuntimeError):
+    pass
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/load.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/load.py
new file mode 100644
index 0000000000..fbe4a9325a
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/load.py
@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Sequence
+from uuid import uuid4
+
+from ..._typing import TypeAlias
+
+from ...contracts import RuntimeFragmentId
+from ...lifetime import AllocationTokenSet, TerminalTransferState
+from ..lifetime import (
+    WeightAllocationGuardProviders,
+    acquire_weight_binding_token,
+)
+from ..manifest import (
+    RuntimeBindingFragment,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+from ..planner import (
+    StoredLoadOperation,
+    bind_logical_transfer_plan,
+    plan_stored_transfer_to_target_placement,
+    resolve_executor_plans,
+)
+from ..storage_manifest import StoredWeightManifest
+from .backend import RangedReadSnapshot, RangeResults
+from .contracts import WeightLoadPlan, _require_stored_load_operation
+from .errors import WeightStoreError
+from .registration import StoreRegistrationLease
+from .validation import (
+    pair_manifests,
+    runtime_binding_fragment,
+    same_runtime_snapshot,
+    validate_manifest_pair,
+)
+
+if TYPE_CHECKING:
+    from .store import WeightStore
+
+
+RangeRequest: TypeAlias = tuple[RuntimeBindingFragment, str, int, int, int]
+
+
+class WeightLoadService:
+    def __init__(self, client: WeightStore) -> None:
+        self.client = client
+
+    def load_manifest(self, manifest_key: str) -> StoredWeightManifest:
+        try:
+            raw = self.client.store.get(manifest_key)
+        except Exception as error:
+            raise WeightStoreError(f"manifest get failed: {manifest_key}") from error
+        try:
+            manifest = StoredWeightManifest.from_json(raw)
+        except Exception as error:
+            raise WeightStoreError(
+                f"invalid weight manifest: {manifest_key}"
+            ) from error
+        if manifest.manifest_key != manifest_key:
+            raise WeightStoreError(
+                f"manifest key mismatch: expected {manifest_key}, "
+                f"got {manifest.manifest_key}"
+            )
+        return manifest
+
+    def plan_load(
+        self,
+        manifest: StoredWeightManifest,
+        target_placement: WeightPlacementManifest,
+        target_bindings: Sequence[WeightRuntimeBindingManifest],
+    ) -> WeightLoadPlan:
+        target_pairs = pair_manifests(
+            target_placement,
+            target_bindings,
+            "target",
+        )
+        if any(
+            placement.resource_id != manifest.resource_id
+            or placement.revision != manifest.revision
+            or placement.weight_generation != manifest.weight_generation
+            for placement, _ in target_pairs
+        ):
+            raise WeightStoreError("target placement revision mismatch")
+
+        logical_plan = plan_stored_transfer_to_target_placement(
+            manifest,
+            target_placement,
+        )
+        return WeightLoadPlan(
+            manifest=manifest,
+            transfer=bind_logical_transfer_plan(
+                logical_plan,
+                target_bindings=target_bindings,
+                source_manifest=manifest,
+            ),
+        )
+
+    def load(
+        self,
+        plan: WeightLoadPlan,
+        target_placement: WeightPlacementManifest,
+        target_binding: WeightRuntimeBindingManifest,
+        *,
+        target_worker_id: Optional[str] = None,
+        target_allocation_guards: Optional[WeightAllocationGuardProviders] = None,
+        registration_lease: Optional[StoreRegistrationLease] = None,
+        transfer_id: Optional[str] = None,
+    ) -> None:
+        validate_manifest_pair(target_placement, target_binding, "target")
+        if (
+            target_placement.resource_id != plan.manifest.resource_id
+            or target_placement.revision != plan.manifest.revision
+            or target_placement.weight_generation != plan.manifest.weight_generation
+        ):
+            raise WeightStoreError("target placement revision mismatch")
+        try:
+            executors = resolve_executor_plans(
+                plan.transfer,
+                target_placement,
+                target_binding,
+                "target",
+            )
+        except ValueError as error:
+            raise WeightStoreError(str(error)) from error
+        available_workers = sorted({executor.worker_id for executor in executors})
+        if target_worker_id is None:
+            if len(available_workers) != 1:
+                raise WeightStoreError(
+                    "target worker selector is required for a multi-worker binding"
+                )
+            target_worker_id = available_workers[0]
+        elif type(target_worker_id) is not str or not target_worker_id:
+            raise WeightStoreError("target_worker_id must be a non-empty string")
+        elif target_worker_id not in available_workers:
+            raise WeightStoreError(f"unknown target worker: {target_worker_id}")
+        executors = tuple(
+            executor for executor in executors if executor.worker_id == target_worker_id
+        )
+
+        try:
+            committed_manifest = self.load_manifest(plan.manifest.manifest_key)
+        except WeightStoreError as error:
+            raise WeightStoreError("weight manifest is not committed") from error
+        if committed_manifest != plan.manifest:
+            raise WeightStoreError("committed weight manifest differs from load plan")
+
+        local = {
+            fragment.fragment_id: fragment for fragment in target_binding.fragments
+        }
+        operations_by_target: dict[RuntimeFragmentId, list[StoredLoadOperation]] = {}
+        operation_indices = sorted(
+            index
+            for executor in executors
+            for index in plan.transfer.operation_indices_for_executor(
+                executor, "target"
+            )
+        )
+        for index in operation_indices:
+            operation = _require_stored_load_operation(plan.transfer.operations[index])
+            planned_target = runtime_binding_fragment(operation.target)
+            current = local.get(planned_target.fragment_id)
+            if current is None or not same_runtime_snapshot(current, planned_target):
+                raise WeightStoreError(
+                    f"stale target fragment: {planned_target.fragment_id}"
+                )
+            try:
+                operation.validate_bounds()
+            except ValueError as error:
+                raise WeightStoreError(
+                    f"invalid transfer region for {operation.tensor_id}: {error}"
+                ) from error
+            if operation.repeat > self.client.max_region_segments:
+                raise WeightStoreError(
+                    f"transfer region exceeds max_region_segments: "
+                    f"{operation.tensor_id}: {operation.repeat} > "
+                    f"{self.client.max_region_segments}"
+                )
+            operations_by_target.setdefault(planned_target.fragment_id, []).append(
+                operation
+            )
+        if not operations_by_target:
+            return
+
+        planned_targets = [
+            local[fragment_id] for fragment_id in sorted(operations_by_target)
+        ]
+        required_fragment_ids = tuple(
+            sorted(fragment.fragment_id for fragment in planned_targets)
+        )
+        lifetime_tokens: Optional[AllocationTokenSet] = None
+        if registration_lease is None:
+            try:
+                fresh_binding, lifetime_tokens = acquire_weight_binding_token(
+                    transfer_id=transfer_id or uuid4().hex,
+                    expected_binding=target_binding,
+                    required_fragment_ids=required_fragment_ids,
+                    side="target",
+                    providers=target_allocation_guards,
+                )
+            except ValueError as error:
+                raise WeightStoreError(str(error)) from error
+        else:
+            fresh_binding = registration_lease.binding
+            registration_lease.validate(target_binding, planned_targets)
+
+        fresh_targets = {
+            fragment.fragment_id: fragment for fragment in fresh_binding.fragments
+        }
+        targets: list[RuntimeBindingFragment] = []
+        for planned_target in planned_targets:
+            current = fresh_targets.get(planned_target.fragment_id)
+            if current is None or not same_runtime_snapshot(current, planned_target):
+                raise WeightStoreError(
+                    f"stale target fragment: {planned_target.fragment_id}"
+                )
+            targets.append(current)
+
+        store_io_started = False
+        terminal_state = TerminalTransferState.ABORTED
+        try:
+            with self.client.registration.registered(
+                targets,
+                pre_registered_lease=registration_lease,
+                lifetime_tokens=lifetime_tokens,
+            ):
+                snapshot_keys = sorted(
+                    {
+                        operation.source.object_key
+                        for operations in operations_by_target.values()
+                        for operation in operations
+                    }
+                )
+                snapshot = self.client.store.prepare_get_into_ranges_snapshot(
+                    snapshot_keys
+                )
+                batch: list[RangeRequest] = []
+                for target in targets:
+                    operations = sorted(
+                        operations_by_target[target.fragment_id],
+                        key=lambda item: (
+                            item.target_offset,
+                            item.source.object_key,
+                            item.source_offset,
+                        ),
+                    )
+                    for operation in operations:
+                        for (
+                            source_offset,
+                            target_offset,
+                            nbytes,
+                        ) in operation.iter_segments(
+                            max_segments=self.client.max_region_segments
+                        ):
+                            for chunk_offset in range(
+                                0, nbytes, self.client.max_range_bytes
+                            ):
+                                chunk_size = min(
+                                    self.client.max_range_bytes,
+                                    nbytes - chunk_offset,
+                                )
+                                batch.append(
+                                    (
+                                        target,
+                                        operation.source.object_key,
+                                        target_offset + chunk_offset,
+                                        operation.source.object_offset
+                                        + source_offset
+                                        + chunk_offset,
+                                        chunk_size,
+                                    )
+                                )
+                                if len(batch) == self.client.max_ranges_per_request:
+                                    store_io_started = True
+                                    self._load_range_batch(batch, snapshot=snapshot)
+                                    batch = []
+                if batch:
+                    store_io_started = True
+                    self._load_range_batch(batch, snapshot=snapshot)
+            terminal_state = TerminalTransferState.COMPLETED
+        except BaseException:
+            if store_io_started:
+                terminal_state = TerminalTransferState.FAILED_DRAINED
+            raise
+        finally:
+            if lifetime_tokens is not None:
+                lifetime_tokens.release_after_terminal(terminal_state)
+
+    def _load_range_batch(
+        self,
+        ranges: Sequence[tuple[RuntimeBindingFragment, str, int, int, int]],
+        *,
+        snapshot: Optional[RangedReadSnapshot],
+    ) -> None:
+        grouped: dict[
+            str,
+            tuple[
+                RuntimeBindingFragment,
+                dict[str, tuple[list[int], list[int], list[int]]],
+            ],
+        ] = {}
+        for target, key, target_offset, source_offset, nbytes in ranges:
+            current, object_ranges = grouped.setdefault(
+                target.fragment_id, (target, {})
+            )
+            if current != target:
+                raise WeightStoreError(
+                    f"target fragment changed in range batch: {target.fragment_id}"
+                )
+            target_offsets, source_offsets, sizes = object_ranges.setdefault(
+                key, ([], [], [])
+            )
+            target_offsets.append(target_offset)
+            source_offsets.append(source_offset)
+            sizes.append(nbytes)
+
+        addresses: list[int] = []
+        all_keys: list[list[str]] = []
+        all_target_offsets: list[list[list[int]]] = []
+        all_source_offsets: list[list[list[int]]] = []
+        all_sizes: list[list[list[int]]] = []
+        for target, object_ranges in grouped.values():
+            addresses.append(target.address)
+            all_keys.append(list(object_ranges))
+            all_target_offsets.append([group[0] for group in object_ranges.values()])
+            all_source_offsets.append([group[1] for group in object_ranges.values()])
+            all_sizes.append([group[2] for group in object_ranges.values()])
+        results = self.client.store.get_into_ranges(
+            addresses,
+            all_keys,
+            all_target_offsets,
+            all_source_offsets,
+            all_sizes,
+            snapshot=snapshot,
+        )
+        self._validate_range_results(all_keys, all_sizes, results)
+
+    @staticmethod
+    def _validate_range_results(
+        all_keys: Sequence[Sequence[str]],
+        all_sizes: Sequence[Sequence[Sequence[int]]],
+        results: RangeResults,
+    ) -> None:
+        if len(results) != len(all_keys):
+            raise WeightStoreError("get_into_ranges returned invalid buffer count")
+        for keys, expected_groups, actual_groups in zip(all_keys, all_sizes, results):
+            if len(actual_groups) != len(keys):
+                raise WeightStoreError("get_into_ranges returned invalid object count")
+            for key, expected, actual in zip(keys, expected_groups, actual_groups):
+                if list(actual) != list(expected):
+                    raise WeightStoreError(
+                        f"get_into_ranges failed for {key}: "
+                        f"expected {list(expected)}, got {list(actual)}"
+                    )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/payload.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/payload.py
new file mode 100644
index 0000000000..018bbb5e4f
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/payload.py
@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence, Union
+
+from ..storage_manifest import StoredWeightManifest
+from .contracts import UploadReceipt, WeightUploadPlan
+from .errors import WeightStoreError
+
+if TYPE_CHECKING:
+    from .store import WeightStore
+
+
+OBJECT_NOT_FOUND = -704
+
+
+class PayloadStoreOperations:
+    def __init__(self, client: WeightStore) -> None:
+        self.client = client
+
+    def require_complete_payloads(self, keys: Sequence[str]) -> None:
+        if not keys:
+            return
+        batch_is_exist = self.client.store.batch_is_exist
+        incomplete: list[str] = []
+        for begin in range(0, len(keys), self.client.max_ranges_per_request):
+            chunk = list(keys[begin : begin + self.client.max_ranges_per_request])
+            results = batch_is_exist(chunk)
+            if results is None:
+                results = [self.client.store.is_exist(key) for key in chunk]
+            if len(results) != len(chunk):
+                raise WeightStoreError("payload existence check returned invalid count")
+            for key, result in zip(chunk, results):
+                if result == 1:
+                    continue
+                if result == 0:
+                    incomplete.append(key)
+                    continue
+                raise WeightStoreError(
+                    f"payload existence check failed for {key}: {result}"
+                )
+        if incomplete:
+            raise WeightStoreError(
+                f"payload is not complete: {', '.join(sorted(incomplete))}"
+            )
+
+    @staticmethod
+    def validate_receipts(
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+        *,
+        require_complete: bool,
+    ) -> None:
+        receipt_ids = [receipt.fragment_id for receipt in receipts]
+        if len(receipt_ids) != len(set(receipt_ids)):
+            raise WeightStoreError("duplicate upload receipt")
+
+        expected = {
+            operation.target.fragment_id: operation for operation in plan.operations
+        }
+        completed = set(receipt_ids)
+        unexpected = completed - set(expected)
+        if unexpected:
+            raise WeightStoreError(
+                f"unexpected upload receipts: {', '.join(sorted(unexpected))}"
+            )
+        for receipt in receipts:
+            operation = expected[receipt.fragment_id]
+            if (
+                receipt.object_key != operation.target.object_key
+                or receipt.worker_id != operation.source_snapshot.worker_id
+            ):
+                raise WeightStoreError(f"invalid upload receipt: {receipt.fragment_id}")
+        if require_complete:
+            missing = set(expected) - completed
+            if missing:
+                raise WeightStoreError(
+                    f"missing upload receipts: {', '.join(sorted(missing))}"
+                )
+
+    @staticmethod
+    def unreferenced_plan_payload_keys(
+        plan: WeightUploadPlan,
+        persisted: StoredWeightManifest,
+    ) -> list[str]:
+        persisted_keys = {fragment.object_key for fragment in persisted.fragments}
+        return [
+            operation.target.object_key
+            for operation in plan.operations
+            if operation.target.object_key not in persisted_keys
+        ]
+
+    def remove_keys(self, keys: Sequence[str]) -> list[tuple[str, Union[str, int]]]:
+        failures: list[tuple[str, Union[str, int]]] = []
+        for key in keys:
+            try:
+                result = self.client.store.remove(key, force=True)
+            except Exception as error:
+                failures.append((key, repr(error)))
+                continue
+            if result not in (0, OBJECT_NOT_FOUND):
+                failures.append((key, result))
+        return failures
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/registration.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/registration.py
new file mode 100644
index 0000000000..8e2af5cdf9
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/registration.py
@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Generator, Iterable, Optional, Sequence, Union
+from uuid import uuid4
+
+from ...lifetime import (
+    AllocationTokenSet,
+    AllocationLifetimeToken,
+    TerminalTransferState,
+    release_tokens_after_terminal,
+)
+from ..manifest import RuntimeBindingFragment, WeightRuntimeBindingManifest
+from .backend import StoreBackend
+from .errors import WeightStoreError
+
+
+@dataclass
+class _PendingStoreRegistration:
+    addresses: set[int]
+    tokens: tuple[AllocationLifetimeToken, ...]
+    terminal_state: TerminalTransferState
+
+
+@dataclass
+class StoreRegistrationLease:
+    """Own long-lived Store registrations and their framework allocation pins."""
+
+    _owner: "StoreBufferRegistration" = field(repr=False)
+    binding: WeightRuntimeBindingManifest
+    fragment_ids: tuple[str, ...]
+    addresses: tuple[tuple[int, int], ...]
+    _tokens: AllocationTokenSet = field(repr=False)
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    @property
+    def closed(self) -> bool:
+        """Whether this lease can no longer authorize Store I/O."""
+
+        return self._closed
+
+    def validate(
+        self,
+        binding: WeightRuntimeBindingManifest,
+        fragments: Sequence[RuntimeBindingFragment],
+    ) -> None:
+        if self._closed:
+            raise WeightStoreError("Store registration lease is closed")
+        if binding != self.binding:
+            raise WeightStoreError("Store registration lease binding differs")
+        if (
+            tuple(sorted(fragment.fragment_id for fragment in fragments))
+            != self.fragment_ids
+        ):
+            raise WeightStoreError("Store registration lease fragments differ")
+        if _registration_requests(fragments) != dict(self.addresses):
+            raise WeightStoreError("Store registration lease address bounds differ")
+
+    def close(
+        self,
+        terminal_state: TerminalTransferState = TerminalTransferState.COMPLETED,
+    ) -> None:
+        self._owner._close_lease(self, terminal_state)
+
+
+class StoreBufferRegistration:
+    """Own synchronous Store registrations and quarantine failed cleanup."""
+
+    def __init__(self, store: StoreBackend) -> None:
+        self.store = store
+        self._lock = Lock()
+        self._pending: dict[str, _PendingStoreRegistration] = {}
+
+    def pending_registration_ids(self) -> tuple[str, ...]:
+        with self._lock:
+            return tuple(sorted(self._pending))
+
+    def drain_pending_registration(self, pending_registration_id: str) -> None:
+        with self._lock:
+            pending = self._pending.get(pending_registration_id)
+            if pending is None:
+                raise WeightStoreError(
+                    f"pending Store registration does not exist: {pending_registration_id}"
+                )
+            addresses = tuple(sorted(pending.addresses, reverse=True))
+        failures = _unregister_addresses(self.store, addresses)
+        if failures:
+            with self._lock:
+                current = self._pending.get(pending_registration_id)
+                if current is not None:
+                    current.addresses = {address for address, _ in failures}
+            raise WeightStoreError(
+                f"pending Store registration cleanup failed: {failures}"
+            )
+        with self._lock:
+            current = self._pending.get(pending_registration_id)
+            if current is None:
+                raise WeightStoreError(
+                    f"pending Store registration does not exist: {pending_registration_id}"
+                )
+            tokens = current.tokens
+            terminal_state = current.terminal_state
+            current.tokens = ()
+        try:
+            release_tokens_after_terminal(tokens, terminal_state)
+        except Exception as error:
+            with self._lock:
+                current = self._pending.get(pending_registration_id)
+                if current is not None:
+                    current.tokens = tokens
+            raise WeightStoreError(
+                f"pending Store allocation lifetime release failed: {error}"
+            ) from error
+        with self._lock:
+            self._pending.pop(pending_registration_id, None)
+
+    def acquire_lease(
+        self,
+        binding: WeightRuntimeBindingManifest,
+        fragments: Sequence[RuntimeBindingFragment],
+        tokens: AllocationTokenSet,
+    ) -> StoreRegistrationLease:
+        self._require_submission_allowed()
+        requests = _registration_requests(fragments)
+        owned: list[int] = []
+        try:
+            for address, nbytes in requests.items():
+                result = self.store.register_buffer(address, nbytes)
+                if result != 0:
+                    raise WeightStoreError(
+                        f"register_buffer failed for {address}: {result}"
+                    )
+                owned.append(address)
+        except BaseException as error:
+            failures = _unregister_addresses(self.store, reversed(owned))
+            if failures:
+                pending_id = self._quarantine(
+                    {address for address, _ in failures},
+                    tokens,
+                    TerminalTransferState.ABORTED,
+                )
+                raise WeightStoreError(
+                    f"{error}; unregister_buffer failed: {failures}; "
+                    f"allocation lifetime is quarantined as {pending_id}"
+                ) from error
+            tokens.release_after_terminal(TerminalTransferState.ABORTED)
+            raise
+        return StoreRegistrationLease(
+            _owner=self,
+            binding=binding,
+            fragment_ids=tuple(sorted(fragment.fragment_id for fragment in fragments)),
+            addresses=tuple(sorted(requests.items())),
+            _tokens=tokens,
+        )
+
+    @contextmanager
+    def registered(
+        self,
+        fragments: Sequence[RuntimeBindingFragment],
+        *,
+        pre_registered_lease: Optional[StoreRegistrationLease] = None,
+        lifetime_tokens: Optional[AllocationTokenSet] = None,
+    ) -> Generator[None, None, None]:
+        self._require_submission_allowed()
+        if pre_registered_lease is not None:
+            pre_registered_lease.validate(pre_registered_lease.binding, fragments)
+            yield
+            return
+        if lifetime_tokens is None:
+            raise WeightStoreError(
+                "Store registration requires allocation lifetime tokens"
+            )
+
+        requests = _registration_requests(fragments)
+        owned: list[int] = []
+        body_entered = False
+        primary_error: Optional[BaseException] = None
+        try:
+            for address, nbytes in requests.items():
+                result = self.store.register_buffer(address, nbytes)
+                if result != 0:
+                    raise WeightStoreError(
+                        f"register_buffer failed for {address}: {result}"
+                    )
+                owned.append(address)
+            body_entered = True
+            yield
+        except BaseException as error:
+            primary_error = error
+
+        failures = _unregister_addresses(self.store, reversed(owned))
+        if failures:
+            terminal_state = (
+                TerminalTransferState.COMPLETED
+                if primary_error is None
+                else (
+                    TerminalTransferState.FAILED_DRAINED
+                    if body_entered
+                    else TerminalTransferState.ABORTED
+                )
+            )
+            pending_id = self._quarantine(
+                {address for address, _ in failures},
+                lifetime_tokens,
+                terminal_state,
+            )
+            detail = (
+                f"unregister_buffer failed: {failures}; allocation lifetime is "
+                f"quarantined as {pending_id}"
+            )
+            if primary_error is not None:
+                raise WeightStoreError(f"{primary_error}; {detail}") from primary_error
+            raise WeightStoreError(detail)
+        if primary_error is not None:
+            raise primary_error
+
+    def _close_lease(
+        self,
+        lease: StoreRegistrationLease,
+        terminal_state: TerminalTransferState,
+    ) -> None:
+        if lease._closed:
+            return
+        failures = _unregister_addresses(
+            self.store,
+            (address for address, _ in reversed(lease.addresses)),
+        )
+        if failures:
+            pending_id = self._quarantine(
+                {address for address, _ in failures},
+                lease._tokens,
+                terminal_state,
+            )
+            # The token has moved to Store-owned pending cleanup. The lease is
+            # no longer a usable registration, even if the caller retries close.
+            lease._closed = True
+            raise WeightStoreError(
+                f"unregister_buffer failed: {failures}; allocation lifetime is "
+                f"quarantined as {pending_id}"
+            )
+        lease._tokens.release_after_terminal(terminal_state)
+        lease._closed = True
+
+    def _require_submission_allowed(self) -> None:
+        with self._lock:
+            if self._pending:
+                pending_id = min(self._pending)
+                raise WeightStoreError(
+                    "Store weight I/O is blocked by pending registration cleanup: "
+                    f"{pending_id}"
+                )
+
+    def _quarantine(
+        self,
+        addresses: set[int],
+        tokens: AllocationTokenSet,
+        terminal_state: TerminalTransferState,
+    ) -> str:
+        pending_id = uuid4().hex
+        raw_tokens = tokens.handoff_to_pending()
+        with self._lock:
+            self._pending[pending_id] = _PendingStoreRegistration(
+                addresses=addresses,
+                tokens=raw_tokens,
+                terminal_state=terminal_state,
+            )
+        return pending_id
+
+
+def _registration_requests(
+    fragments: Sequence[RuntimeBindingFragment],
+) -> dict[int, int]:
+    requests: dict[int, int] = {}
+    for fragment in fragments:
+        previous = requests.get(fragment.address)
+        if previous is not None and previous != fragment.nbytes:
+            raise WeightStoreError(
+                f"Store registration address capacity mismatch: {fragment.address}"
+            )
+        requests[fragment.address] = fragment.nbytes
+    return requests
+
+
+def _unregister_addresses(
+    store: StoreBackend,
+    addresses: Iterable[int],
+) -> list[tuple[int, Union[str, int]]]:
+    failures: list[tuple[int, Union[str, int]]] = []
+    for address in addresses:
+        try:
+            result = store.unregister_buffer(address)
+        except Exception as error:
+            failures.append((address, repr(error)))
+            continue
+        if result != 0:
+            failures.append((address, result))
+    return failures
+
+
+__all__ = ["StoreBufferRegistration", "StoreRegistrationLease"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/snapshot.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/snapshot.py
new file mode 100644
index 0000000000..50d6b8bea4
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/snapshot.py
@@ -0,0 +1,73 @@
+"""Source contracts for one immutable model-weight snapshot."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, Sequence
+
+from ...contracts import PlacementFragmentId, ResourceId, RevisionId
+from ..manifest import WeightPlacementManifest, WeightRuntimeBindingManifest
+
+if TYPE_CHECKING:
+    from ..lifetime import WeightAllocationGuardProviders
+
+
+def _require_nonempty_string(value: object, name: str) -> None:
+    if type(value) is not str or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+
+
+def _require_u64(value: object, name: str) -> None:
+    if type(value) is not int or value < 0 or value >= (1 << 64):
+        raise ValueError(f"{name} must fit in an unsigned 64-bit integer")
+
+
+@dataclass(frozen=True)
+class WeightSnapshotDescriptor:
+    """Immutable identity supplied before a complete model snapshot is written."""
+
+    resource_id: ResourceId
+    revision: RevisionId
+    weight_generation: int
+    namespace: str = "default"
+
+    def __post_init__(self) -> None:
+        _require_nonempty_string(self.resource_id, "resource_id")
+        _require_nonempty_string(self.revision, "revision")
+        _require_nonempty_string(self.namespace, "namespace")
+        _require_u64(self.weight_generation, "weight_generation")
+
+
+class WeightSnapshotSource(Protocol):
+    """Complete source inventory used to prepare one Store upload plan."""
+
+    placement: WeightPlacementManifest
+    bindings: Sequence[WeightRuntimeBindingManifest]
+
+
+class WeightSnapshotAdapter(Protocol):
+    """Framework-owned bridge from a tensor to canonical source fragments."""
+
+    def export_source(self, snapshot: WeightSnapshotDescriptor) -> WeightSnapshotSource:
+        """Return the complete source placement and live bindings for this snapshot."""
+        ...
+
+    def resolve_fragment_ids(
+        self,
+        *,
+        tensor_id: str,
+        tensor: object,
+        source: WeightSnapshotSource,
+    ) -> Sequence[PlacementFragmentId]:
+        """Validate one tensor and return its canonical placement fragments."""
+        ...
+
+    def source_allocation_guards(
+        self,
+        binding: WeightRuntimeBindingManifest,
+    ) -> WeightAllocationGuardProviders | None:
+        """Return framework lifetime guards for a source binding."""
+        ...
+
+
+__all__ = ["WeightSnapshotAdapter", "WeightSnapshotDescriptor"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/store.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/store.py
new file mode 100644
index 0000000000..b80ebc07b6
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/store.py
@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Callable, Optional
+from uuid import uuid4
+
+from ..manifest import (
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+from ...contracts import RuntimeFragmentId
+from ..storage_manifest import StoredWeightManifest
+from ...lifetime import TerminalTransferState
+from ..lifetime import (
+    WeightAllocationGuardProviders,
+    acquire_weight_binding_token,
+)
+from .contracts import UploadReceipt, WeightLoadPlan, WeightUploadPlan
+from .errors import WeightStoreError
+from .backend import (
+    StoreBackend,
+    StoreConfigFactory,
+    default_config_factory,
+)
+from .load import WeightLoadService
+from .payload import PayloadStoreOperations
+from .registration import StoreBufferRegistration, StoreRegistrationLease
+from .transaction import WeightUploadTransaction
+from .snapshot import (
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+)
+from .writer import (
+    WeightStoreWriter,
+)
+from .upload import WeightUploadService
+
+
+def _require_upload_plan(plan: WeightUploadPlan) -> None:
+    if not isinstance(plan, WeightUploadPlan):
+        raise WeightStoreError("plan must be a WeightUploadPlan")
+
+
+def _require_load_plan(plan: WeightLoadPlan) -> None:
+    if not isinstance(plan, WeightLoadPlan):
+        raise WeightStoreError("plan must be a WeightLoadPlan")
+
+
+class WeightStore:
+    def __init__(
+        self,
+        store: object,
+        *,
+        key_prefix: str = "weights",
+        config_factory: Optional[StoreConfigFactory] = None,
+        max_range_bytes: int = 64 * 1024 * 1024,
+        max_ranges_per_request: int = 1024,
+        max_region_segments: int = 1_000_000,
+    ) -> None:
+        if (
+            max_range_bytes <= 0
+            or max_ranges_per_request <= 0
+            or max_region_segments <= 0
+        ):
+            raise ValueError("range limits must be positive")
+        self.store = StoreBackend(store)
+        self.key_prefix = key_prefix.strip("/")
+        self.config_factory = config_factory or default_config_factory
+        self.max_range_bytes = max_range_bytes
+        self.max_ranges_per_request = max_ranges_per_request
+        self.max_region_segments = max_region_segments
+        self.registration = StoreBufferRegistration(self.store)
+        self._payloads = PayloadStoreOperations(self)
+        self._transaction = WeightUploadTransaction(self, self._payloads)
+        self._upload = WeightUploadService(self, self._payloads, self._transaction)
+        self._load = WeightLoadService(self)
+
+    def plan_upload(
+        self,
+        source_placement: WeightPlacementManifest,
+        source_bindings: Sequence[WeightRuntimeBindingManifest],
+        *,
+        namespace: str = "default",
+    ) -> WeightUploadPlan:
+        return self._upload.plan_upload(
+            source_placement,
+            source_bindings,
+            namespace=namespace,
+        )
+
+    def begin_weight_snapshot(
+        self,
+        snapshot: WeightSnapshotDescriptor,
+        adapter: WeightSnapshotAdapter,
+    ) -> WeightStoreWriter:
+        """Create a manifest-backed writer for one immutable model snapshot."""
+
+        return WeightStoreWriter(self, snapshot, adapter)
+
+    def upload(
+        self,
+        plan: WeightUploadPlan,
+        source_placement: WeightPlacementManifest,
+        source_binding: WeightRuntimeBindingManifest,
+        *,
+        source_worker_id: Optional[str] = None,
+        source_allocation_guards: Optional[WeightAllocationGuardProviders] = None,
+        registration_lease: Optional[StoreRegistrationLease] = None,
+        transfer_id: Optional[str] = None,
+    ) -> tuple[UploadReceipt, ...]:
+        _require_upload_plan(plan)
+        return self._upload.upload(
+            plan,
+            source_placement,
+            source_binding,
+            source_worker_id=source_worker_id,
+            source_allocation_guards=source_allocation_guards,
+            registration_lease=registration_lease,
+            transfer_id=transfer_id,
+        )
+
+    def abort_upload(
+        self,
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+    ) -> None:
+        _require_upload_plan(plan)
+        self._transaction.abort_upload(plan, receipts)
+
+    def finalize_upload_transaction(self, plan: WeightUploadPlan) -> None:
+        _require_upload_plan(plan)
+        self._transaction.finalize_upload_transaction(plan)
+
+    def commit_upload(
+        self,
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+    ) -> StoredWeightManifest:
+        _require_upload_plan(plan)
+        return self._transaction.commit(plan, receipts)
+
+    def _commit_upload_from_writer(
+        self,
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+        *,
+        on_commit_decision_may_exist: Callable[[], None],
+    ) -> StoredWeightManifest:
+        _require_upload_plan(plan)
+        return self._transaction.commit(
+            plan,
+            receipts,
+            on_commit_decision_may_exist=on_commit_decision_may_exist,
+        )
+
+    def load_manifest(self, manifest_key: str) -> StoredWeightManifest:
+        return self._load.load_manifest(manifest_key)
+
+    def plan_load(
+        self,
+        manifest: StoredWeightManifest,
+        target_placement: WeightPlacementManifest,
+        target_bindings: Sequence[WeightRuntimeBindingManifest],
+    ) -> WeightLoadPlan:
+        return self._load.plan_load(manifest, target_placement, target_bindings)
+
+    def load(
+        self,
+        plan: WeightLoadPlan,
+        target_placement: WeightPlacementManifest,
+        target_binding: WeightRuntimeBindingManifest,
+        *,
+        target_worker_id: Optional[str] = None,
+        target_allocation_guards: Optional[WeightAllocationGuardProviders] = None,
+        registration_lease: Optional[StoreRegistrationLease] = None,
+        transfer_id: Optional[str] = None,
+    ) -> None:
+        _require_load_plan(plan)
+        self._load.load(
+            plan,
+            target_placement,
+            target_binding,
+            target_worker_id=target_worker_id,
+            target_allocation_guards=target_allocation_guards,
+            registration_lease=registration_lease,
+            transfer_id=transfer_id,
+        )
+
+    def register_weight_buffers(
+        self,
+        binding: WeightRuntimeBindingManifest,
+        *,
+        fragment_ids: Sequence[RuntimeFragmentId],
+        allocation_guards: Optional[WeightAllocationGuardProviders],
+        side: str,
+        transfer_id: Optional[str] = None,
+    ) -> StoreRegistrationLease:
+        """Create a typed long-lived Store registration under a framework pin."""
+
+        if not isinstance(binding, WeightRuntimeBindingManifest):
+            raise WeightStoreError("binding must be a WeightRuntimeBindingManifest")
+        requested_ids = tuple(sorted(set(fragment_ids)))
+        if not requested_ids:
+            raise WeightStoreError("Store registration lease requires fragments")
+        try:
+            fresh_binding, tokens = acquire_weight_binding_token(
+                transfer_id=transfer_id or uuid4().hex,
+                expected_binding=binding,
+                required_fragment_ids=requested_ids,
+                side=side,
+                providers=allocation_guards,
+            )
+        except ValueError as error:
+            raise WeightStoreError(str(error)) from error
+        fragments_by_id = {
+            fragment.fragment_id: fragment for fragment in fresh_binding.fragments
+        }
+        try:
+            fragments = tuple(
+                fragments_by_id[fragment_id] for fragment_id in requested_ids
+            )
+        except KeyError as error:
+            tokens.release_after_terminal(TerminalTransferState.ABORTED)
+            raise WeightStoreError(
+                f"Store registration fragment is missing: {error.args[0]}"
+            ) from error
+        return self.registration.acquire_lease(fresh_binding, fragments, tokens)
+
+    def pending_registration_ids(self) -> tuple[str, ...]:
+        return self.registration.pending_registration_ids()
+
+    def drain_pending_registration(self, pending_registration_id: str) -> None:
+        self.registration.drain_pending_registration(pending_registration_id)
+
+
+__all__ = ["WeightStore", "WeightStoreError"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/transaction.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/transaction.py
new file mode 100644
index 0000000000..83c6f3a181
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/transaction.py
@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Mapping,
+    Optional,
+    Sequence,
+    Union,
+    cast,
+)
+
+from ..storage_manifest import StoredWeightManifest
+from .contracts import UploadReceipt, WeightUploadPlan
+from .errors import WeightStoreError
+from .payload import PayloadStoreOperations
+
+if TYPE_CHECKING:
+    from .store import WeightStore
+
+
+@dataclass(frozen=True)
+class _UploadDecision:
+    plan_digest: str
+    decision: str
+
+
+def _plan_digest(manifest: StoredWeightManifest) -> str:
+    return hashlib.sha256(manifest.to_json().encode()).hexdigest()
+
+
+def _decision_payload(plan: WeightUploadPlan, decision: str) -> bytes:
+    return json.dumps(
+        {
+            "decision": decision,
+            "plan_digest": _plan_digest(plan.manifest),
+            "record_type": "weight-upload-decision",
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode()
+
+
+def _decode_decision(value: Union[bytes, bytearray, str]) -> _UploadDecision:
+    def reject_constant(constant: str) -> None:
+        raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+    def reject_duplicate_fields(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, item in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON field: {key}")
+            result[key] = item
+        return result
+
+    parsed: object = json.loads(
+        value,
+        parse_constant=reject_constant,
+        object_pairs_hook=reject_duplicate_fields,
+    )
+    expected = {
+        "decision",
+        "plan_digest",
+        "record_type",
+    }
+    if not isinstance(parsed, Mapping):
+        raise ValueError("upload decision schema fields do not match contract")
+    raw = cast(Mapping[object, object], parsed)
+    if {key for key in raw if type(key) is str} != expected or any(
+        type(key) is not str for key in raw
+    ):
+        raise ValueError("upload decision schema fields do not match contract")
+    raw = cast(Mapping[str, object], raw)
+    if raw["record_type"] != "weight-upload-decision":
+        raise ValueError("invalid upload decision record_type")
+    if raw["decision"] not in ("abort", "commit"):
+        raise ValueError("invalid upload decision")
+    digest = raw["plan_digest"]
+    if (
+        type(digest) is not str
+        or len(digest) != 64
+        or any(character not in "0123456789abcdef" for character in digest)
+    ):
+        raise ValueError("invalid upload decision plan_digest")
+    return _UploadDecision(plan_digest=digest, decision=raw["decision"])
+
+
+class WeightUploadTransaction:
+    def __init__(
+        self,
+        client: WeightStore,
+        payloads: PayloadStoreOperations,
+    ) -> None:
+        self.client = client
+        self.payloads = payloads
+
+    def abort_upload(
+        self,
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+    ) -> None:
+        self.payloads.validate_receipts(plan, receipts, require_complete=False)
+        persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+        if persisted == plan.manifest:
+            raise WeightStoreError("cannot abort a published weight revision")
+        self._claim_upload(plan, "abort")
+        persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+        if persisted == plan.manifest:
+            raise WeightStoreError("cannot abort a published weight revision")
+        keys = (
+            [operation.target.object_key for operation in plan.operations]
+            if persisted is None
+            else self.payloads.unreferenced_plan_payload_keys(plan, persisted)
+        )
+        failures = self.payloads.remove_keys(keys)
+        if failures:
+            raise WeightStoreError(f"upload cleanup failed: {failures}")
+
+    def finalize_upload_transaction(self, plan: WeightUploadPlan) -> None:
+        decision = self._load_decision_if_present(plan.control_key)
+        if decision is None:
+            persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+            if persisted == plan.manifest:
+                self._claim_upload(plan, "commit")
+                decision = self._load_decision_if_present(plan.control_key)
+            else:
+                raise WeightStoreError("upload transaction has no terminal decision")
+        if decision is None:
+            raise WeightStoreError("upload transaction terminal decision is incomplete")
+        self._validate_decision_owner(plan, decision)
+        if decision.decision == "commit":
+            persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+            if persisted is None:
+                raise WeightStoreError("committed upload transaction has no manifest")
+            if persisted != plan.manifest:
+                failures = self.payloads.remove_keys(
+                    self.payloads.unreferenced_plan_payload_keys(plan, persisted)
+                )
+                if failures:
+                    raise WeightStoreError(
+                        f"conflicting upload cleanup failed: {failures}"
+                    )
+        else:
+            persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+            if persisted == plan.manifest:
+                raise WeightStoreError("aborted upload has a published manifest")
+            keys = (
+                [operation.target.object_key for operation in plan.operations]
+                if persisted is None
+                else self.payloads.unreferenced_plan_payload_keys(plan, persisted)
+            )
+            failures = self.payloads.remove_keys(keys)
+            if failures:
+                raise WeightStoreError(f"upload cleanup failed: {failures}")
+
+    def commit(
+        self,
+        plan: WeightUploadPlan,
+        receipts: Sequence[UploadReceipt],
+        *,
+        on_commit_decision_may_exist: Callable[[], None] | None = None,
+    ) -> StoredWeightManifest:
+        self.payloads.validate_receipts(plan, receipts, require_complete=True)
+        payload_keys = [receipt.object_key for receipt in receipts]
+        if self._current_upload_decision(plan) is None:
+            self.payloads.require_complete_payloads(payload_keys)
+        if on_commit_decision_may_exist is not None:
+            # A Store put may commit before its response becomes unavailable.
+            # From this point, a caller must preserve the transaction for retry.
+            on_commit_decision_may_exist()
+        self._claim_upload(plan, "commit")
+        self.payloads.require_complete_payloads(payload_keys)
+        existing = self._load_manifest_if_present(plan.manifest.manifest_key)
+        if existing is not None:
+            return self._resolve_manifest_commit(plan, existing, payload_keys)
+
+        put_error: Optional[Exception] = None
+        result: Optional[int] = None
+        try:
+            result = self.client.store.put(
+                plan.manifest.manifest_key,
+                plan.manifest.to_json().encode(),
+                self.client.config_factory([plan.manifest.group_id], "metadata"),
+            )
+        except Exception as error:
+            put_error = error
+
+        persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+        if persisted is not None:
+            return self._resolve_manifest_commit(plan, persisted, payload_keys)
+
+        detail = f"manifest put failed: {result}"
+        if put_error is not None:
+            detail = f"manifest put failed: {put_error}"
+        raise WeightStoreError(detail) from put_error
+
+    def require_writable(
+        self,
+        plan: WeightUploadPlan,
+        *,
+        cleanup_keys: Sequence[str] = (),
+    ) -> None:
+        decision = self._current_upload_decision(plan)
+        if decision is None:
+            return
+        persisted = self._load_manifest_if_present(plan.manifest.manifest_key)
+        if decision == "commit" and (persisted is None or persisted == plan.manifest):
+            return
+        protected_keys: set[str] = (
+            set()
+            if persisted is None
+            else {fragment.object_key for fragment in persisted.fragments}
+        )
+        failures = self.payloads.remove_keys(
+            [key for key in cleanup_keys if key not in protected_keys]
+        )
+        detail = (
+            "weight upload already chose abort"
+            if decision == "abort"
+            else "weight upload lost to a conflicting revision"
+        )
+        if failures:
+            detail += f"; cleanup failed: {failures}"
+        raise WeightStoreError(detail)
+
+    def _claim_upload(self, plan: WeightUploadPlan, decision: str) -> None:
+        put_error: Optional[Exception] = None
+        result: Optional[int] = None
+        try:
+            result = self.client.store.put(
+                plan.control_key,
+                _decision_payload(plan, decision),
+                self.client.config_factory([plan.transaction_group_id], "metadata"),
+            )
+        except Exception as error:
+            put_error = error
+
+        persisted = self._load_decision_if_present(plan.control_key)
+        if persisted is None:
+            detail = f"upload decision is not complete; retry: {result}"
+            if put_error is not None:
+                detail = f"upload decision is not complete; retry: {put_error}"
+            raise WeightStoreError(detail) from put_error
+        self._validate_decision_owner(plan, persisted)
+        if persisted.decision != decision:
+            raise WeightStoreError(f"weight upload already chose {persisted.decision}")
+
+    def _current_upload_decision(self, plan: WeightUploadPlan) -> Optional[str]:
+        persisted = self._load_decision_if_present(plan.control_key)
+        if persisted is None:
+            return None
+        self._validate_decision_owner(plan, persisted)
+        return persisted.decision
+
+    @staticmethod
+    def _validate_decision_owner(
+        plan: WeightUploadPlan, persisted: _UploadDecision
+    ) -> None:
+        if persisted.plan_digest != _plan_digest(plan.manifest):
+            raise WeightStoreError("upload decision belongs to another plan")
+
+    def _load_decision_if_present(
+        self,
+        control_key: str,
+    ) -> Optional[_UploadDecision]:
+        exists = self.client.store.is_exist(control_key)
+        if exists == 0:
+            return None
+        if exists != 1:
+            raise WeightStoreError(
+                f"upload decision existence check failed: {control_key}: {exists}"
+            )
+        try:
+            return _decode_decision(self.client.store.get(control_key))
+        except Exception as error:
+            raise WeightStoreError(f"invalid upload decision: {control_key}") from error
+
+    def _load_manifest_if_present(
+        self,
+        manifest_key: str,
+    ) -> Optional[StoredWeightManifest]:
+        exists = self.client.store.is_exist(manifest_key)
+        if exists == 0:
+            return None
+        if exists != 1:
+            raise WeightStoreError(
+                f"manifest existence check failed: {manifest_key}: {exists}"
+            )
+        return self.client.load_manifest(manifest_key)
+
+    def _resolve_manifest_commit(
+        self,
+        plan: WeightUploadPlan,
+        persisted: StoredWeightManifest,
+        payload_keys: Sequence[str],
+    ) -> StoredWeightManifest:
+        if persisted == plan.manifest:
+            return persisted
+        persisted_keys = {fragment.object_key for fragment in persisted.fragments}
+        cleanup_failures = self.payloads.remove_keys(
+            [key for key in payload_keys if key not in persisted_keys]
+        )
+        detail = f"conflicting weight revision: {plan.manifest.manifest_key}"
+        if cleanup_failures:
+            detail += f"; cleanup failed: {cleanup_failures}"
+        raise WeightStoreError(detail)
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/upload.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/upload.py
new file mode 100644
index 0000000000..527f4f64f7
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/upload.py
@@ -0,0 +1,500 @@
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional, Sequence
+
+from ..._typing import TypeAlias
+from urllib.parse import quote
+from uuid import uuid4
+
+from .._planner.ownership import (
+    complete_parallel_source_replicas,
+    has_dp_ownership,
+    parallel_tensor_owner,
+)
+from ...contracts import (
+    ResourceId,
+    RevisionId,
+    RuntimeFragmentId,
+    StoredFragmentSnapshotId,
+    TensorId,
+)
+from ..manifest import (
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+from ..storage_manifest import StoredFragmentSnapshot, StoredWeightManifest
+from ..planner import RuntimeFragmentSnapshot
+from ...lifetime import AllocationTokenSet, TerminalTransferState
+from ..lifetime import (
+    WeightAllocationGuardProviders,
+    acquire_weight_binding_token,
+)
+from .contracts import UploadOperation, UploadReceipt, WeightUploadPlan
+from .errors import WeightStoreError
+from .payload import PayloadStoreOperations
+from .transaction import WeightUploadTransaction
+from .registration import StoreRegistrationLease
+from .validation import (
+    pair_manifests,
+    same_runtime_snapshot,
+    validate_manifest_pair,
+)
+
+if TYPE_CHECKING:
+    from .store import WeightStore
+
+
+UploadSource = tuple[
+    PlacementFragment,
+    RuntimeBindingFragment,
+    WeightRuntimeBindingManifest,
+]
+UploadGeometryKey: TypeAlias = tuple[TensorId, tuple[int, ...], tuple[int, ...]]
+UploadSortKey: TypeAlias = tuple[int, int, int, int, str, str]
+
+
+def _runtime_sort_key(source: UploadSource) -> UploadSortKey:
+    placement, binding, _ = source
+    return (
+        placement.rank.dp,
+        placement.rank.pp,
+        placement.rank.ep,
+        placement.rank.tp,
+        binding.worker_id,
+        binding.fragment_id,
+    )
+
+
+def _geometry_key(fragment: PlacementFragment) -> UploadGeometryKey:
+    return fragment.tensor_id, fragment.global_offset, fragment.local_shape
+
+
+def _collect_upload_sources(
+    placement: WeightPlacementManifest,
+    bindings: Sequence[WeightRuntimeBindingManifest],
+) -> tuple[
+    ResourceId,
+    RevisionId,
+    int,
+    tuple[TensorDescriptor, ...],
+    list[UploadSource],
+]:
+    pairs = pair_manifests(placement, tuple(bindings), "source")
+    resource_id = pairs[0][0].resource_id
+    revision = pairs[0][0].revision
+    weight_generation = pairs[0][0].weight_generation
+    tensor_by_id: dict[TensorId, TensorDescriptor] = {
+        tensor.tensor_id: tensor for tensor in placement.tensors
+    }
+    if any(has_dp_ownership(tensor) for tensor in tensor_by_id.values()):
+        raise ValueError(
+            "Weight Store upload requires replicated DP source tensors; "
+            "DP-owned tensor snapshots are not supported"
+        )
+    sources: list[UploadSource] = []
+    runtime_fragment_ids: set[RuntimeFragmentId] = set()
+    for placement, binding in pairs:
+        part = next(
+            item
+            for item in placement.parts
+            if item.participant_id == binding.participant_id
+        )
+        for tensor in part.tensors:
+            previous = tensor_by_id.setdefault(tensor.tensor_id, tensor)
+            if previous != tensor:
+                raise ValueError(f"tensor descriptor mismatch: {tensor.tensor_id}")
+        runtime_by_placement_id = {
+            fragment.placement_fragment_id: fragment for fragment in binding.fragments
+        }
+        for fragment in part.fragments:
+            runtime_fragment = runtime_by_placement_id[fragment.placement_fragment_id]
+            if runtime_fragment.fragment_id in runtime_fragment_ids:
+                raise ValueError(
+                    f"duplicate source fragment_id: {runtime_fragment.fragment_id}"
+                )
+            runtime_fragment_ids.add(runtime_fragment.fragment_id)
+            sources.append((fragment, runtime_fragment, binding))
+
+    tensors = tuple(sorted(tensor_by_id.values(), key=lambda item: item.tensor_id))
+    try:
+        complete_replicas = complete_parallel_source_replicas(
+            tensor_by_id,
+            [placement_fragment for placement_fragment, _, _ in sources],
+        )
+    except ValueError as error:
+        if str(error) == (
+            "source manifests have no complete DP replica; "
+            "tensors are not fully covered"
+        ):
+            raise ValueError(
+                "source manifests have no complete generation-consistent DP replica"
+            ) from error
+        raise
+
+    generations_by_dp: dict[int, int] = {}
+    for dp_rank, replica_owners in complete_replicas.items():
+        generations = {
+            binding_manifest.generation
+            for placement_fragment, _, binding_manifest in sources
+            if placement_fragment.rank.dp == dp_rank
+            and parallel_tensor_owner(
+                tensor_by_id[placement_fragment.tensor_id], placement_fragment
+            )
+            == replica_owners[placement_fragment.tensor_id]
+        }
+        if len(generations) == 1:
+            generations_by_dp[dp_rank] = next(iter(generations))
+    if not generations_by_dp:
+        raise ValueError(
+            "source manifests have no complete generation-consistent DP replica"
+        )
+    if len(set(generations_by_dp.values())) != 1:
+        raise ValueError(
+            "complete source DP replicas have inconsistent lease generations"
+        )
+
+    selected_dp = min(generations_by_dp)
+    owner_by_tensor = complete_replicas[selected_dp]
+    candidates: dict[UploadGeometryKey, list[UploadSource]] = {}
+    for source in sources:
+        placement_fragment, _, binding_manifest = source
+        tensor = tensor_by_id[placement_fragment.tensor_id]
+        if (
+            placement_fragment.rank.dp != selected_dp
+            or binding_manifest.generation != generations_by_dp[selected_dp]
+            or parallel_tensor_owner(tensor, placement_fragment)
+            != owner_by_tensor[placement_fragment.tensor_id]
+        ):
+            continue
+        candidates.setdefault(_geometry_key(placement_fragment), []).append(source)
+
+    selected: list[UploadSource] = []
+    for group in candidates.values():
+        group.sort(key=_runtime_sort_key)
+        selected.append(group[0])
+    selected.sort(
+        key=lambda source: (
+            source[0].tensor_id,
+            source[0].global_offset,
+            source[0].local_shape,
+        )
+    )
+    return resource_id, revision, weight_generation, tensors, selected
+
+
+def _safe_segment(value: str) -> str:
+    return quote(value, safe="._-")
+
+
+def _fragment_digest(fragment: PlacementFragment) -> StoredFragmentSnapshotId:
+    value = (
+        f"{fragment.tensor_id}|{fragment.global_offset}|{fragment.local_shape}"
+    ).encode()
+    return StoredFragmentSnapshotId(hashlib.sha256(value).hexdigest()[:24])
+
+
+def plan_weight_upload(
+    source_placement: WeightPlacementManifest,
+    source_bindings: Sequence[WeightRuntimeBindingManifest],
+    *,
+    namespace: str = "default",
+    key_prefix: str = "weights",
+) -> WeightUploadPlan:
+    """Build an address-free Store upload plan from complete source manifests."""
+
+    if type(namespace) is not str or not namespace:
+        raise ValueError("namespace must be a non-empty string")
+    if type(key_prefix) is not str or not key_prefix.strip("/"):
+        raise ValueError("key_prefix must contain a non-empty path segment")
+    resource_id, revision, weight_generation, tensors, sources = (
+        _collect_upload_sources(
+            source_placement,
+            source_bindings,
+        )
+    )
+    base_key = "/".join(
+        (
+            key_prefix.strip("/"),
+            _safe_segment(namespace),
+            _safe_segment(resource_id),
+            _safe_segment(revision),
+            str(weight_generation),
+        )
+    )
+    transaction_id = uuid4().hex
+    stored_fragments: list[StoredFragmentSnapshot] = []
+    operations: list[UploadOperation] = []
+    for placement_fragment, source_binding, binding_manifest in sources:
+        fragment_id = _fragment_digest(placement_fragment)
+        target = StoredFragmentSnapshot(
+            fragment_id=fragment_id,
+            tensor_id=placement_fragment.tensor_id,
+            global_offset=placement_fragment.global_offset,
+            local_shape=placement_fragment.local_shape,
+            object_key=f"{base_key}/payload/{transaction_id}/{fragment_id}",
+            object_offset=0,
+            nbytes=placement_fragment.nbytes,
+            aliases=placement_fragment.aliases,
+        )
+        stored_fragments.append(target)
+        operations.append(
+            UploadOperation(
+                source_placement=placement_fragment,
+                source_snapshot=RuntimeFragmentSnapshot.from_attested_pair(
+                    placement_fragment,
+                    source_binding,
+                    lease_generation=binding_manifest.generation,
+                ),
+                source_participant_id=binding_manifest.participant_id,
+                source_instance_id=binding_manifest.instance_id,
+                target=target,
+                source_generation=binding_manifest.generation,
+                source_lease_id=binding_manifest.lease_id,
+            )
+        )
+    manifest = StoredWeightManifest(
+        namespace=namespace,
+        resource_id=resource_id,
+        revision=revision,
+        weight_generation=weight_generation,
+        group_id=base_key,
+        manifest_key=f"{base_key}/manifest",
+        tensors=tensors,
+        fragments=tuple(stored_fragments),
+        created_at=datetime.now(timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z"),
+    )
+    return WeightUploadPlan(
+        manifest=manifest,
+        source_placement_id=source_placement.placement_id,
+        source_placement_digest=source_placement.digest,
+        transaction_group_id=f"{base_key}/transactions/{transaction_id}",
+        control_key=f"{base_key}/transactions/{transaction_id}/decision",
+        operations=tuple(operations),
+    )
+
+
+class WeightUploadService:
+    def __init__(
+        self,
+        client: WeightStore,
+        payloads: PayloadStoreOperations,
+        transaction: WeightUploadTransaction,
+    ) -> None:
+        self.client = client
+        self.payloads = payloads
+        self.transaction = transaction
+
+    def plan_upload(
+        self,
+        source_placement: WeightPlacementManifest,
+        source_bindings: Sequence[WeightRuntimeBindingManifest],
+        *,
+        namespace: str = "default",
+    ) -> WeightUploadPlan:
+        return plan_weight_upload(
+            source_placement,
+            source_bindings,
+            namespace=namespace,
+            key_prefix=self.client.key_prefix,
+        )
+
+    def upload(
+        self,
+        plan: WeightUploadPlan,
+        source_placement: WeightPlacementManifest,
+        source_binding: WeightRuntimeBindingManifest,
+        *,
+        source_worker_id: Optional[str] = None,
+        source_allocation_guards: Optional[WeightAllocationGuardProviders] = None,
+        registration_lease: Optional[StoreRegistrationLease] = None,
+        transfer_id: Optional[str] = None,
+    ) -> tuple[UploadReceipt, ...]:
+        validate_manifest_pair(source_placement, source_binding, "source")
+        if source_placement.resource_id != plan.manifest.resource_id or (
+            source_placement.revision != plan.manifest.revision
+        ):
+            raise WeightStoreError("source placement revision mismatch")
+        if source_placement.weight_generation != plan.manifest.weight_generation:
+            raise WeightStoreError("source placement weight generation mismatch")
+        if (
+            source_placement.placement_id != plan.source_placement_id
+            or source_placement.digest != plan.source_placement_digest
+        ):
+            raise WeightStoreError("source placement identity mismatch")
+        local = {
+            fragment.fragment_id: fragment for fragment in source_binding.fragments
+        }
+        source_part = next(
+            part
+            for part in source_placement.parts
+            if part.participant_id == source_binding.participant_id
+        )
+        local_placements = {
+            fragment.placement_fragment_id: fragment
+            for fragment in source_part.fragments
+        }
+        expected_operations = [
+            operation
+            for operation in plan.operations
+            if operation.source_participant_id == source_binding.participant_id
+        ]
+        if not expected_operations:
+            return ()
+        available_workers = sorted(
+            {operation.source_snapshot.worker_id for operation in expected_operations}
+        )
+        if source_worker_id is None:
+            if len(available_workers) != 1:
+                raise WeightStoreError(
+                    "source worker selector is required for a multi-worker binding"
+                )
+            source_worker_id = available_workers[0]
+        elif type(source_worker_id) is not str or not source_worker_id:
+            raise WeightStoreError("source_worker_id must be a non-empty string")
+        elif source_worker_id not in available_workers:
+            raise WeightStoreError(f"unknown source worker: {source_worker_id}")
+        expected_operations = [
+            operation
+            for operation in expected_operations
+            if operation.source_snapshot.worker_id == source_worker_id
+        ]
+        if any(
+            operation.source_instance_id != source_binding.instance_id
+            for operation in expected_operations
+        ):
+            raise WeightStoreError(
+                f"stale source instance: {source_binding.participant_id}"
+            )
+        missing = {
+            operation.source_snapshot.fragment_id
+            for operation in expected_operations
+            if operation.source_snapshot.fragment_id not in local
+        }
+        if missing:
+            raise WeightStoreError(
+                f"missing planned source fragment: {', '.join(sorted(missing))}"
+            )
+        local_operations: list[tuple[UploadOperation, RuntimeBindingFragment]] = []
+        for operation in expected_operations:
+            current = local.get(operation.source_snapshot.fragment_id)
+            if current is None:
+                raise AssertionError("planned source fragment was not resolved")
+            current_placement = local_placements.get(
+                operation.source_placement.placement_fragment_id
+            )
+            if current_placement != operation.source_placement:
+                raise WeightStoreError(
+                    "stale source placement: "
+                    f"{operation.source_placement.placement_fragment_id}"
+                )
+            if (
+                source_binding.lease_id != operation.source_lease_id
+                or source_binding.generation != operation.source_generation
+            ):
+                raise WeightStoreError(
+                    f"stale source lease: {operation.source_snapshot.fragment_id}"
+                )
+            if not same_runtime_snapshot(current, operation.source_snapshot):
+                raise WeightStoreError(
+                    f"stale source fragment: {operation.source_snapshot.fragment_id}"
+                )
+            local_operations.append((operation, current))
+        self.transaction.require_writable(plan)
+        required_fragment_ids = tuple(
+            sorted(
+                {
+                    operation.source_snapshot.fragment_id
+                    for operation, _ in local_operations
+                }
+            )
+        )
+        lifetime_tokens: Optional[AllocationTokenSet] = None
+        if registration_lease is None:
+            try:
+                fresh_binding, lifetime_tokens = acquire_weight_binding_token(
+                    transfer_id=transfer_id or uuid4().hex,
+                    expected_binding=source_binding,
+                    required_fragment_ids=required_fragment_ids,
+                    side="source",
+                    providers=source_allocation_guards,
+                )
+            except ValueError as error:
+                raise WeightStoreError(str(error)) from error
+        else:
+            fresh_binding = registration_lease.binding
+            registration_lease.validate(
+                source_binding,
+                tuple(current for _, current in local_operations),
+            )
+
+        fresh_local = {
+            fragment.fragment_id: fragment for fragment in fresh_binding.fragments
+        }
+        refreshed_operations: list[tuple[UploadOperation, RuntimeBindingFragment]] = []
+        for operation, _ in local_operations:
+            current = fresh_local.get(operation.source_snapshot.fragment_id)
+            if current is None or not same_runtime_snapshot(
+                current,
+                operation.source_snapshot,
+            ):
+                raise WeightStoreError(
+                    f"stale source fragment: {operation.source_snapshot.fragment_id}"
+                )
+            refreshed_operations.append((operation, current))
+
+        sources = [current for _, current in refreshed_operations]
+        object_keys = [
+            operation.target.object_key for operation, _ in refreshed_operations
+        ]
+        store_io_started = False
+        terminal_state = TerminalTransferState.ABORTED
+        try:
+            with self.client.registration.registered(
+                sources,
+                pre_registered_lease=registration_lease,
+                lifetime_tokens=lifetime_tokens,
+            ):
+                for begin in range(
+                    0, len(refreshed_operations), self.client.max_ranges_per_request
+                ):
+                    batch = refreshed_operations[
+                        begin : begin + self.client.max_ranges_per_request
+                    ]
+                    store_io_started = True
+                    results = self.client.store.batch_put_from(
+                        [operation.target.object_key for operation, _ in batch],
+                        [current.address for _, current in batch],
+                        [current.nbytes for _, current in batch],
+                        self.client.config_factory(
+                            [plan.manifest.group_id] * len(batch), "payload"
+                        ),
+                    )
+                    if len(results) != len(batch) or any(
+                        result != 0 for result in results
+                    ):
+                        raise WeightStoreError(f"batch_put_from failed: {results}")
+                self.payloads.require_complete_payloads(object_keys)
+            terminal_state = TerminalTransferState.COMPLETED
+        except BaseException:
+            if store_io_started:
+                terminal_state = TerminalTransferState.FAILED_DRAINED
+            raise
+        finally:
+            if lifetime_tokens is not None:
+                lifetime_tokens.release_after_terminal(terminal_state)
+        self.transaction.require_writable(plan, cleanup_keys=object_keys)
+        return tuple(
+            UploadReceipt(
+                fragment_id=operation.target.fragment_id,
+                object_key=operation.target.object_key,
+                worker_id=current.worker_id,
+            )
+            for operation, current in refreshed_operations
+        )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/validation.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/validation.py
new file mode 100644
index 0000000000..5723dae0b5
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/validation.py
@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from ..manifest import (
+    RuntimeBindingFragment,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+    validate_runtime_bindings,
+    validate_runtime_binding,
+)
+from ..planner import BoundWeightFragment, RuntimeFragmentSnapshot
+from .errors import WeightStoreError
+
+
+def same_runtime_snapshot(
+    current: RuntimeBindingFragment,
+    planned: Union[RuntimeBindingFragment, RuntimeFragmentSnapshot],
+) -> bool:
+    if isinstance(planned, RuntimeBindingFragment):
+        return current == planned
+    return (
+        current.placement_fragment_id == planned.placement_fragment_id
+        and current.fragment_id == planned.fragment_id
+        and current.address == planned.address
+        and current.nbytes == planned.nbytes
+        and current.worker_id == planned.worker_id
+        and current.endpoint == planned.endpoint
+        and current.device == planned.device
+        and current.itemsize == planned.itemsize
+        and current.local_shape == planned.local_shape
+        and current.strides_bytes == planned.strides_bytes
+        and current.storage_address == planned.storage_address
+        and current.storage_nbytes == planned.storage_nbytes
+        and current.storage_offset_bytes == planned.storage_offset_bytes
+    )
+
+
+def validate_manifest_pair(
+    placement: WeightPlacementManifest,
+    binding: WeightRuntimeBindingManifest,
+    label: str,
+) -> None:
+    try:
+        validate_runtime_binding(placement, binding)
+    except ValueError as error:
+        raise WeightStoreError(f"invalid {label} runtime binding: {error}") from error
+
+
+def validate_manifest_set(
+    placement: WeightPlacementManifest,
+    bindings: Sequence[WeightRuntimeBindingManifest],
+    label: str,
+) -> None:
+    try:
+        validate_runtime_bindings(placement, bindings)
+    except (TypeError, ValueError) as error:
+        raise WeightStoreError(f"invalid {label} runtime bindings: {error}") from error
+
+
+def pair_manifests(
+    placement: WeightPlacementManifest,
+    bindings: Sequence[WeightRuntimeBindingManifest],
+    label: str,
+) -> tuple[tuple[WeightPlacementManifest, WeightRuntimeBindingManifest], ...]:
+    if not isinstance(placement, WeightPlacementManifest):
+        raise ValueError(f"{label} placement must be a WeightPlacementManifest")
+    items = tuple(bindings)
+    if not items:
+        raise WeightStoreError(f"{label} runtime bindings must not be empty")
+    if not all(isinstance(item, WeightRuntimeBindingManifest) for item in items):
+        raise WeightStoreError(
+            f"{label} runtime bindings must contain WeightRuntimeBindingManifest"
+        )
+    participant_ids = [item.participant_id for item in items]
+    if len(participant_ids) != len(set(participant_ids)):
+        raise WeightStoreError(f"duplicate {label} runtime binding participant")
+    for binding in items:
+        validate_manifest_pair(placement, binding, label)
+    return tuple((placement, binding) for binding in items)
+
+
+def runtime_binding_fragment(
+    fragment: Union[RuntimeBindingFragment, BoundWeightFragment],
+) -> RuntimeBindingFragment:
+    if isinstance(fragment, RuntimeBindingFragment):
+        return fragment
+    if isinstance(fragment, BoundWeightFragment):
+        return fragment.binding
+    raise WeightStoreError(
+        "transfer plan physical fragment must be a RuntimeBindingFragment "
+        "or expose one as .binding"
+    )
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/_store/writer.py b/mooncake-reshard/python/mooncake/reshard/weight/_store/writer.py
new file mode 100644
index 0000000000..ffd790cae8
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/_store/writer.py
@@ -0,0 +1,229 @@
+"""Stateful writer for one manifest-backed model-weight snapshot."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+from ...contracts import ParticipantId, PlacementFragmentId
+from ..storage_manifest import StoredWeightManifest
+from .contracts import UploadReceipt, WeightUploadPlan
+from .errors import WeightStoreError
+from .snapshot import (
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+    _require_nonempty_string,
+)
+
+if TYPE_CHECKING:
+    from .store import WeightStore
+
+
+class WeightStoreWriter:
+    """Accumulate canonical tensor fragments into one immutable model snapshot."""
+
+    def __init__(
+        self,
+        weight_store: WeightStore,
+        snapshot: WeightSnapshotDescriptor,
+        adapter: WeightSnapshotAdapter,
+    ) -> None:
+        self._weight_store = weight_store
+        self.snapshot = snapshot
+        self._adapter = adapter
+        self._source = adapter.export_source(snapshot)
+        self._placement = self._source.placement
+        self._bindings = tuple(self._source.bindings)
+        self._validate_source_identity()
+        self._plan = weight_store.plan_upload(
+            self._placement,
+            self._bindings,
+            namespace=snapshot.namespace,
+        )
+        self._binding_by_participant = {
+            binding.participant_id: binding for binding in self._bindings
+        }
+        self._operation_by_placement_id = {
+            operation.source_placement.placement_fragment_id: operation
+            for operation in self._plan.operations
+        }
+        if len(self._operation_by_placement_id) != len(self._plan.operations):
+            raise WeightStoreError("snapshot plan has duplicate placement fragments")
+        self._required_by_participant: dict[
+            ParticipantId, set[PlacementFragmentId]
+        ] = {}
+        for operation in self._plan.operations:
+            self._required_by_participant.setdefault(
+                operation.source_participant_id, set()
+            ).add(operation.source_placement.placement_fragment_id)
+        self._seen_by_participant: dict[ParticipantId, set[PlacementFragmentId]] = {
+            participant_id: set() for participant_id in self._required_by_participant
+        }
+        self._flushed_participants: set[ParticipantId] = set()
+        self._receipts: list[UploadReceipt] = []
+        self._closed = False
+        self._committed = False
+        self._commit_decision_may_exist = False
+
+    @property
+    def plan(self) -> WeightUploadPlan:
+        """Return the immutable upload plan owned by this writer."""
+
+        return self._plan
+
+    def write_tensor(
+        self,
+        tensor_id: str,
+        tensor: object,
+    ) -> tuple[UploadReceipt, ...]:
+        """Validate and write a framework-owned tensor fragment."""
+
+        self._require_open()
+        _require_nonempty_string(tensor_id, "tensor_id")
+        resolved = tuple(
+            self._adapter.resolve_fragment_ids(
+                tensor_id=tensor_id,
+                tensor=tensor,
+                source=self._source,
+            )
+        )
+        if not resolved:
+            raise WeightStoreError("weight snapshot tensor resolved no fragments")
+        if len(set(resolved)) != len(resolved):
+            raise WeightStoreError(
+                "weight snapshot tensor resolved duplicate fragments"
+            )
+
+        flushed: list[UploadReceipt] = []
+        try:
+            for placement_fragment_id in resolved:
+                operation = self._operation_by_placement_id.get(placement_fragment_id)
+                if operation is None:
+                    raise WeightStoreError(
+                        "weight snapshot tensor resolved a fragment outside this snapshot: "
+                        f"{placement_fragment_id}"
+                    )
+                if operation.source_placement.tensor_id != tensor_id:
+                    raise WeightStoreError(
+                        "weight snapshot tensor resolved a fragment for another tensor: "
+                        f"{placement_fragment_id}"
+                    )
+                participant_id = operation.source_participant_id
+                seen = self._seen_by_participant[participant_id]
+                if placement_fragment_id in seen:
+                    raise WeightStoreError(
+                        "weight snapshot tensor submitted a duplicate fragment: "
+                        f"{placement_fragment_id}"
+                    )
+                seen.add(placement_fragment_id)
+                if (
+                    seen == self._required_by_participant[participant_id]
+                    and participant_id not in self._flushed_participants
+                ):
+                    flushed.extend(self._flush_participant(participant_id))
+        except BaseException:
+            self.abort()
+            raise
+        return tuple(flushed)
+
+    def commit(self) -> StoredWeightManifest:
+        """Publish the manifest only after every selected fragment is written."""
+
+        self._require_open()
+        missing = tuple(
+            sorted(
+                placement_fragment_id
+                for participant_id, required in self._required_by_participant.items()
+                for placement_fragment_id in required
+                if placement_fragment_id
+                not in self._seen_by_participant[participant_id]
+            )
+        )
+        if missing:
+            self.abort()
+            raise WeightStoreError(
+                "Weight snapshot is missing required fragments: " + ", ".join(missing)
+            )
+        if set(self._required_by_participant) != self._flushed_participants:
+            self.abort()
+            raise WeightStoreError("Weight snapshot has unflushed participants")
+        manifest = self._weight_store._commit_upload_from_writer(
+            self._plan,
+            self._receipts,
+            on_commit_decision_may_exist=self._mark_commit_decision_may_exist,
+        )
+        self._closed = True
+        self._committed = True
+        return manifest
+
+    def abort(self) -> None:
+        """Remove uploaded payloads unless this writer has already committed."""
+
+        if self._closed:
+            return
+        if self._commit_decision_may_exist:
+            raise WeightStoreError(
+                "Weight snapshot commit decision may exist; retry commit instead"
+            )
+        self._closed = True
+        if self._receipts:
+            self._weight_store.abort_upload(self._plan, self._receipts)
+
+    def _mark_commit_decision_may_exist(self) -> None:
+        self._commit_decision_may_exist = True
+
+    def _validate_source_identity(self) -> None:
+        placement = self._placement
+        if (
+            placement.resource_id != self.snapshot.resource_id
+            or placement.revision != self.snapshot.revision
+            or placement.weight_generation != self.snapshot.weight_generation
+        ):
+            raise WeightStoreError("snapshot identity differs from source placement")
+
+    def _flush_participant(
+        self,
+        participant_id: ParticipantId,
+    ) -> tuple[UploadReceipt, ...]:
+        binding = self._binding_by_participant.get(participant_id)
+        if binding is None:
+            raise WeightStoreError(
+                f"snapshot source binding is missing: {participant_id}"
+            )
+        receipts = self._weight_store.upload(
+            self._plan,
+            self._placement,
+            binding,
+            source_allocation_guards=self._adapter.source_allocation_guards(binding),
+        )
+        self._receipts.extend(receipts)
+        self._flushed_participants.add(participant_id)
+        return receipts
+
+    def _require_open(self) -> None:
+        if self._committed:
+            raise WeightStoreError("Weight snapshot has already committed")
+        if self._closed:
+            raise WeightStoreError("Weight snapshot is closed")
+
+    def __enter__(self) -> WeightStoreWriter:
+        self._require_open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        if exc_type is None:
+            if not self._committed:
+                self.commit()
+        elif not self._commit_decision_may_exist:
+            self.abort()
+        return False
+
+
+__all__ = [
+    "WeightStoreWriter",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/binding.py b/mooncake-reshard/python/mooncake/reshard/weight/binding.py
new file mode 100644
index 0000000000..0d270461fa
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/binding.py
@@ -0,0 +1,154 @@
+"""Validation between logical weight placement and runtime locations."""
+
+from __future__ import annotations
+
+from ..contracts import (
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+    validate_resource_binding_identity,
+)
+from .placement import WeightPlacementManifest
+from .runtime import WeightRuntimeBindingManifest
+from .types import canonical_strides_bytes, require_manifest_items
+from .validation import _validate_runtime_binding_address_ranges
+
+
+def validate_runtime_binding(
+    placement: WeightPlacementManifest,
+    binding: WeightRuntimeBindingManifest,
+) -> None:
+    """Validate an ephemeral binding against one exact logical placement."""
+
+    if not isinstance(placement, WeightPlacementManifest):
+        raise ValueError("placement must be a WeightPlacementManifest")  # noqa: TRY004
+    if not isinstance(binding, WeightRuntimeBindingManifest):
+        raise ValueError("binding must be a WeightRuntimeBindingManifest")  # noqa: TRY004
+    validate_resource_binding_identity(placement, binding)
+    if placement.revision != binding.revision:
+        raise ValueError("placement and runtime binding revision differ")
+
+    try:
+        placement_part = next(
+            part
+            for part in placement.parts
+            if part.participant_id == binding.participant_id
+        )
+    except StopIteration as error:
+        raise ValueError(
+            f"unknown runtime binding participant: {binding.participant_id}"
+        ) from error
+
+    placement_by_id = {
+        fragment.placement_fragment_id: fragment
+        for fragment in placement_part.fragments
+    }
+    binding_by_id = {
+        fragment.placement_fragment_id: fragment for fragment in binding.fragments
+    }
+    tensor_by_id = {tensor.tensor_id: tensor for tensor in placement.tensors}
+    unknown = sorted(binding_by_id.keys() - placement_by_id.keys())
+    if unknown:
+        raise ValueError(f"unknown placement fragment in runtime binding: {unknown[0]}")
+    missing = sorted(placement_by_id.keys() - binding_by_id.keys())
+    if missing:
+        raise ValueError(f"missing placement fragment in runtime binding: {missing[0]}")
+
+    for placement_fragment in placement_part.fragments:
+        runtime_fragment = binding_by_id[placement_fragment.placement_fragment_id]
+        if runtime_fragment.nbytes != placement_fragment.nbytes:
+            raise ValueError(
+                "runtime binding byte size does not match placement: "
+                f"{placement_fragment.placement_fragment_id}"
+            )
+        if runtime_fragment.local_shape != placement_fragment.local_shape:
+            raise ValueError(
+                "runtime binding local_shape does not match placement: "
+                f"{placement_fragment.placement_fragment_id}"
+            )
+        tensor = tensor_by_id[placement_fragment.tensor_id]
+        if runtime_fragment.itemsize != tensor.itemsize:
+            raise ValueError(
+                "runtime binding itemsize does not match placement: "
+                f"{placement_fragment.placement_fragment_id}"
+            )
+        expected_strides_bytes = canonical_strides_bytes(
+            placement_fragment.local_shape,
+            tensor.itemsize,
+        )
+        if runtime_fragment.strides_bytes != expected_strides_bytes:
+            raise ValueError(
+                "runtime binding stride does not describe a canonical "
+                "contiguous view: "
+                f"{placement_fragment.placement_fragment_id}"
+            )
+
+    _validate_runtime_binding_address_ranges(
+        instance_id=binding.instance_id,
+        tensors=placement.tensors,
+        placements=placement_part.fragments,
+        bindings=binding.fragments,
+    )
+
+
+def _validate_runtime_binding_subset(
+    placement: WeightPlacementManifest,
+    bindings: object,
+) -> tuple[WeightRuntimeBindingManifest, ...]:
+    """Validate one or more participants and their shared address spaces."""
+
+    items = require_manifest_items(
+        bindings,
+        "runtime bindings",
+        WeightRuntimeBindingManifest,
+    )
+    participant_ids = [item.participant_id for item in items]
+    if len(participant_ids) != len(set(participant_ids)):
+        raise ValueError("duplicate runtime binding participant")
+    runtime_fragment_ids: set[RuntimeFragmentId] = set()
+    for binding in items:
+        validate_runtime_binding(placement, binding)
+        for fragment in binding.fragments:
+            if fragment.fragment_id in runtime_fragment_ids:
+                raise ValueError(
+                    f"duplicate runtime fragment_id across participants: "
+                    f"{fragment.fragment_id}"
+                )
+            runtime_fragment_ids.add(fragment.fragment_id)
+
+    part_by_participant = {part.participant_id: part for part in placement.parts}
+    by_instance: dict[RuntimeInstanceId, list[WeightRuntimeBindingManifest]] = {}
+    for binding in items:
+        by_instance.setdefault(binding.instance_id, []).append(binding)
+    for instance_id, instance_bindings in by_instance.items():
+        _validate_runtime_binding_address_ranges(
+            instance_id=instance_id,
+            tensors=placement.tensors,
+            placements=tuple(
+                fragment
+                for binding in instance_bindings
+                for fragment in part_by_participant[binding.participant_id].fragments
+            ),
+            bindings=tuple(
+                fragment
+                for binding in instance_bindings
+                for fragment in binding.fragments
+            ),
+        )
+    return items
+
+
+def validate_runtime_bindings(
+    placement: WeightPlacementManifest,
+    bindings: object,
+) -> None:
+    """Validate the exact runtime binding set for a complete placement."""
+
+    items = _validate_runtime_binding_subset(placement, bindings)
+    expected = {part.participant_id for part in placement.parts if part.fragments}
+    actual = {item.participant_id for item in items}
+    missing = sorted(expected - actual)
+    if missing:
+        raise ValueError(f"missing runtime binding participant: {missing[0]}")
+    unknown = sorted(actual - expected)
+    if unknown:
+        raise ValueError(f"unknown runtime binding participant: {unknown[0]}")
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/lifetime.py b/mooncake-reshard/python/mooncake/reshard/weight/lifetime.py
new file mode 100644
index 0000000000..698ef63267
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/lifetime.py
@@ -0,0 +1,19 @@
+"""Framework allocation-lifetime contracts shared by weight executors and Store."""
+
+from ._lifetime import (
+    AcquiredWeightBinding,
+    WeightAllocationGuardProvider,
+    WeightAllocationGuardProviders,
+    acquire_weight_binding_token,
+    acquire_weight_lifetime_tokens,
+    weight_allocation_fence,
+)
+
+__all__ = [
+    "AcquiredWeightBinding",
+    "WeightAllocationGuardProvider",
+    "WeightAllocationGuardProviders",
+    "acquire_weight_binding_token",
+    "acquire_weight_lifetime_tokens",
+    "weight_allocation_fence",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/manifest.py b/mooncake-reshard/python/mooncake/reshard/weight/manifest.py
new file mode 100644
index 0000000000..673e2b23a1
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/manifest.py
@@ -0,0 +1,34 @@
+"""Stable public facade for model-weight manifest contracts."""
+
+from .binding import validate_runtime_binding, validate_runtime_bindings
+from .part import WeightPlacementPart
+from .placement import WeightPlacementManifest
+from .runtime import WeightRuntimeBindingManifest
+from .topology import ParallelTopology, TopologyParticipant
+from .types import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+)
+
+
+__all__ = [
+    "ParallelRank",
+    "ParallelTopology",
+    "PlacementFragment",
+    "TopologyParticipant",
+    "WeightPlacementManifest",
+    "WeightPlacementPart",
+    "RuntimeBindingFragment",
+    "WeightRuntimeBindingManifest",
+    "SplitAxis",
+    "ReplicatedAxis",
+    "OwnershipAxis",
+    "TensorDescriptor",
+    "validate_runtime_binding",
+    "validate_runtime_bindings",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/part.py b/mooncake-reshard/python/mooncake/reshard/weight/part.py
new file mode 100644
index 0000000000..c7cb5947dc
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/part.py
@@ -0,0 +1,86 @@
+"""Per-participant logical weight placement contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..contracts import (
+    ParticipantId,
+    PlacementSetId,
+    ResourceId,
+    RevisionId,
+    TopologyId,
+)
+from .types import (
+    ParallelRank,
+    PlacementFragment,
+    TensorDescriptor,
+    _require_nonempty_string,
+    _require_u64,
+    require_manifest_items,
+)
+from .validation import _validate_fragments
+
+
+@dataclass(frozen=True)
+class WeightPlacementPart:
+    """One participant's address-free contribution to a global placement."""
+
+    resource_id: ResourceId
+    revision: RevisionId
+    weight_generation: int
+    placement_set_id: PlacementSetId
+    topology_id: TopologyId
+    participant_id: ParticipantId
+    rank: ParallelRank
+    tensors: tuple[TensorDescriptor, ...]
+    fragments: tuple[PlacementFragment, ...]
+
+    def __post_init__(self) -> None:
+        for name in (
+            "resource_id",
+            "revision",
+            "placement_set_id",
+            "topology_id",
+            "participant_id",
+        ):
+            _require_nonempty_string(getattr(self, name), name)
+        _require_u64(self.weight_generation, "weight_generation")
+        if not isinstance(self.rank, ParallelRank):
+            raise ValueError("placement part rank must be a ParallelRank")  # noqa: TRY004
+
+        tensors = require_manifest_items(
+            self.tensors,
+            "WeightPlacementPart tensors",
+            TensorDescriptor,
+        )
+        fragments = require_manifest_items(
+            self.fragments,
+            "WeightPlacementPart fragments",
+            PlacementFragment,
+        )
+        if any(fragment.rank != self.rank for fragment in fragments):
+            raise ValueError("placement part fragment rank differs from part rank")
+        referenced_tensor_ids = {fragment.tensor_id for fragment in fragments}
+        unreferenced_tensor_ids = sorted(
+            {tensor.tensor_id for tensor in tensors} - referenced_tensor_ids
+        )
+        if unreferenced_tensor_ids:
+            raise ValueError(
+                "placement part contains an unreferenced tensor: "
+                f"{unreferenced_tensor_ids[0]}"
+            )
+        object.__setattr__(
+            self,
+            "tensors",
+            tuple(sorted(tensors, key=lambda item: item.tensor_id)),
+        )
+        object.__setattr__(
+            self,
+            "fragments",
+            tuple(sorted(fragments, key=lambda item: item.placement_fragment_id)),
+        )
+        _validate_fragments(self.tensors, self.fragments)
+
+
+__all__ = ["WeightPlacementPart"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/placement.py b/mooncake-reshard/python/mooncake/reshard/weight/placement.py
new file mode 100644
index 0000000000..aefe6199d5
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/placement.py
@@ -0,0 +1,363 @@
+"""Complete logical weight placement and canonical identity."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+from ..contracts import (
+    ParticipantId,
+    PlacementId,
+    PlacementSetId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    TensorId,
+)
+from .part import WeightPlacementPart
+from .topology import ParallelTopology
+from .types import (
+    OwnershipAxis,
+    PlacementFragment,
+    ReplicatedAxis,
+    SplitAxis,
+    TensorDescriptor,
+    _require_nonempty_string,
+    _require_u64,
+    require_manifest_items,
+)
+from .validation import (
+    _validate_complete_weight_placement,
+    _validate_fragments,
+)
+
+
+@dataclass(frozen=True, init=False)
+class WeightPlacementManifest:
+    """One complete address-free placement of a model-weight generation."""
+
+    resource_id: ResourceId
+    placement_id: PlacementId
+    revision: RevisionId
+    weight_generation: int
+    placement_set_id: PlacementSetId
+    topology: ParallelTopology
+    parts: tuple[WeightPlacementPart, ...]
+    tensors: tuple[TensorDescriptor, ...]
+    fragments: tuple[PlacementFragment, ...]
+    _digest_cache: Optional[str] = field(init=False, repr=False, compare=False)
+
+    def __init__(
+        self,
+        *,
+        resource_id: ResourceId,
+        revision: RevisionId,
+        weight_generation: int,
+        placement_set_id: PlacementSetId,
+        topology: ParallelTopology,
+        parts: tuple[WeightPlacementPart, ...],
+        placement_id: Optional[PlacementId] = None,
+    ) -> None:
+        _require_nonempty_string(resource_id, "resource_id")
+        _require_nonempty_string(revision, "revision")
+        _require_u64(weight_generation, "weight_generation")
+        _require_nonempty_string(placement_set_id, "placement_set_id")
+        if not isinstance(topology, ParallelTopology):
+            raise ValueError("topology must be a ParallelTopology")  # noqa: TRY004
+        if placement_id is not None:
+            _require_nonempty_string(placement_id, "placement_id")
+
+        normalized_parts = tuple(
+            sorted(
+                require_manifest_items(
+                    parts,
+                    "WeightPlacementManifest parts",
+                    WeightPlacementPart,
+                ),
+                key=lambda item: item.participant_id,
+            )
+        )
+        _validate_parts(
+            normalized_parts,
+            topology=topology,
+            resource_id=resource_id,
+            revision=revision,
+            weight_generation=weight_generation,
+            placement_set_id=placement_set_id,
+        )
+
+        tensors_by_id: dict[TensorId, TensorDescriptor] = {}
+        collected_fragments: list[PlacementFragment] = []
+        for part in normalized_parts:
+            for tensor in part.tensors:
+                previous = tensors_by_id.setdefault(tensor.tensor_id, tensor)
+                if previous != tensor:
+                    raise ValueError(
+                        f"placement part tensor descriptor mismatch: {tensor.tensor_id}"
+                    )
+            collected_fragments.extend(part.fragments)
+        tensors = tuple(sorted(tensors_by_id.values(), key=lambda item: item.tensor_id))
+        fragments = tuple(
+            sorted(collected_fragments, key=lambda item: item.placement_fragment_id)
+        )
+        _validate_fragments(
+            tensors,
+            fragments,
+            require_complete_alias_groups=True,
+        )
+        _validate_complete_weight_placement(
+            tensors,
+            fragments,
+            topology=topology,
+        )
+        canonical_placement_id = _logical_placement_id(
+            resource_id=resource_id,
+            revision=revision,
+            weight_generation=weight_generation,
+            placement_set_id=placement_set_id,
+            topology=topology,
+            tensors=tensors,
+            parts=normalized_parts,
+        )
+        if placement_id is not None and placement_id != canonical_placement_id:
+            raise ValueError("placement_id does not match canonical logical content")
+
+        object.__setattr__(self, "resource_id", resource_id)
+        object.__setattr__(self, "placement_id", canonical_placement_id)
+        object.__setattr__(self, "revision", revision)
+        object.__setattr__(self, "weight_generation", weight_generation)
+        object.__setattr__(self, "placement_set_id", placement_set_id)
+        object.__setattr__(self, "topology", topology)
+        object.__setattr__(self, "parts", normalized_parts)
+        object.__setattr__(self, "tensors", tensors)
+        object.__setattr__(self, "fragments", fragments)
+        object.__setattr__(self, "_digest_cache", None)
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        """Identify this placement as model weight data."""
+
+        return ResourceKind.MODEL_WEIGHT
+
+    @property
+    def digest(self) -> str:
+        """Return the stable SHA-256 digest of the canonical JSON form."""
+
+        digest = self._digest_cache
+        if digest is None:
+            from .serde import weight_placement_to_json
+
+            digest = hashlib.sha256(weight_placement_to_json(self).encode()).hexdigest()
+            object.__setattr__(self, "_digest_cache", digest)
+        return digest
+
+    @classmethod
+    def from_fragments(
+        cls,
+        *,
+        resource_id: ResourceId,
+        revision: RevisionId,
+        weight_generation: int,
+        placement_set_id: PlacementSetId,
+        topology: ParallelTopology,
+        tensors: Sequence[TensorDescriptor],
+        fragments: Sequence[PlacementFragment],
+        placement_id: Optional[PlacementId] = None,
+    ) -> WeightPlacementManifest:
+        """Group a complete flat fragment inventory by topology participant."""
+
+        tensor_items = require_manifest_items(
+            tensors, "placement tensors", TensorDescriptor
+        )
+        fragment_items = require_manifest_items(
+            fragments, "placement fragments", PlacementFragment
+        )
+        tensor_by_id = {tensor.tensor_id: tensor for tensor in tensor_items}
+        if len(tensor_by_id) != len(tensor_items):
+            raise ValueError("duplicate tensor_id in placement tensors")
+        referenced_tensor_ids = {fragment.tensor_id for fragment in fragment_items}
+        unknown_tensor_ids = sorted(referenced_tensor_ids - set(tensor_by_id))
+        if unknown_tensor_ids:
+            raise ValueError(f"unknown tensor_id: {unknown_tensor_ids[0]}")
+        unreferenced_tensor_ids = sorted(set(tensor_by_id) - referenced_tensor_ids)
+        if unreferenced_tensor_ids:
+            raise ValueError(
+                "global placement contains an unreferenced tensor: "
+                f"{unreferenced_tensor_ids[0]}"
+            )
+        participant_by_rank = {
+            participant.rank: participant for participant in topology.participants
+        }
+        fragments_by_participant: dict[ParticipantId, list[PlacementFragment]] = {
+            participant.participant_id: [] for participant in topology.participants
+        }
+        for fragment in fragment_items:
+            participant = participant_by_rank.get(fragment.rank)
+            if participant is None:
+                raise ValueError(
+                    "placement fragment rank has no topology participant: "
+                    f"{fragment.fragment_id}"
+                )
+            fragments_by_participant[participant.participant_id].append(fragment)
+
+        parts: list[WeightPlacementPart] = []
+        for participant in topology.participants:
+            local_fragments = tuple(
+                fragments_by_participant[participant.participant_id]
+            )
+            local_tensor_ids = {fragment.tensor_id for fragment in local_fragments}
+            parts.append(
+                WeightPlacementPart(
+                    resource_id=resource_id,
+                    revision=revision,
+                    weight_generation=weight_generation,
+                    placement_set_id=placement_set_id,
+                    topology_id=topology.topology_id,
+                    participant_id=participant.participant_id,
+                    rank=participant.rank,
+                    tensors=tuple(
+                        tensor_by_id[tensor_id]
+                        for tensor_id in sorted(local_tensor_ids)
+                    ),
+                    fragments=local_fragments,
+                )
+            )
+        return cls(
+            resource_id=resource_id,
+            revision=revision,
+            weight_generation=weight_generation,
+            placement_set_id=placement_set_id,
+            topology=topology,
+            parts=tuple(parts),
+            placement_id=placement_id,
+        )
+
+
+def _validate_parts(
+    parts: tuple[WeightPlacementPart, ...],
+    *,
+    topology: ParallelTopology,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    weight_generation: int,
+    placement_set_id: PlacementSetId,
+) -> None:
+    participant_ids = [part.participant_id for part in parts]
+    if len(participant_ids) != len(set(participant_ids)):
+        raise ValueError("duplicate placement participant")
+
+    expected = {
+        participant.participant_id: participant for participant in topology.participants
+    }
+    actual = set(participant_ids)
+    missing = sorted(set(expected) - actual)
+    if missing:
+        raise ValueError(f"missing topology participant: {missing[0]}")
+    unknown = sorted(actual - set(expected))
+    if unknown:
+        raise ValueError(f"unknown topology participant: {unknown[0]}")
+
+    for part in parts:
+        if part.resource_id != resource_id:
+            raise ValueError("placement part resource_id differs")
+        if part.revision != revision:
+            raise ValueError("placement part revision differs")
+        if part.weight_generation != weight_generation:
+            raise ValueError("placement part weight_generation differs")
+        if part.placement_set_id != placement_set_id:
+            raise ValueError("placement part placement_set_id differs")
+        if part.topology_id != topology.topology_id:
+            raise ValueError("placement part topology_id differs")
+        if part.rank != expected[part.participant_id].rank:
+            raise ValueError("placement part rank differs from topology")
+
+
+def _canonical_json_digest(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _logical_placement_id(
+    *,
+    resource_id: ResourceId,
+    revision: RevisionId,
+    weight_generation: int,
+    placement_set_id: PlacementSetId,
+    topology: ParallelTopology,
+    tensors: Sequence[TensorDescriptor],
+    parts: Sequence[WeightPlacementPart],
+) -> PlacementId:
+    content = {
+        "schema": "complete-weight-placement",
+        "resource_id": resource_id,
+        "revision": revision,
+        "weight_generation": weight_generation,
+        "placement_set_id": placement_set_id,
+        "topology": {
+            "tp_size": topology.tp_size,
+            "pp_size": topology.pp_size,
+            "ep_size": topology.ep_size,
+            "dp_size": topology.dp_size,
+            "topology_id": topology.topology_id,
+            "participants": [asdict(item) for item in topology.participants],
+        },
+        "tensors": [
+            {
+                "tensor_id": tensor.tensor_id,
+                "global_shape": tensor.global_shape,
+                "dtype": tensor.dtype,
+                "itemsize": tensor.itemsize,
+                "shard_dims": tensor.shard_dims,
+                "layout_fingerprint": tensor.layout_fingerprint,
+                "parallel_axes": [
+                    _parallel_axis_identity(axis) for axis in tensor.parallel_axes
+                ],
+                "layer_id": tensor.layer_id,
+                "expert_id": tensor.expert_id,
+            }
+            for tensor in tensors
+        ],
+        "parts": [
+            {
+                "participant_id": part.participant_id,
+                "rank": asdict(part.rank),
+                "fragments": [
+                    _placement_fragment_identity(fragment)
+                    for fragment in part.fragments
+                ],
+            }
+            for part in parts
+        ],
+    }
+    return PlacementId(f"sha256:{_canonical_json_digest(content)}")
+
+
+def _parallel_axis_identity(axis: object) -> dict[str, object]:
+    if isinstance(axis, SplitAxis):
+        return {"semantics": "split", "kind": axis.kind, "dim": axis.dim}
+    if isinstance(axis, ReplicatedAxis):
+        return {"semantics": "replicated", "kind": axis.kind}
+    if isinstance(axis, OwnershipAxis):
+        return {"semantics": "ownership", "kind": axis.kind}
+    raise ValueError("unsupported parallel axis value")
+
+
+def _placement_fragment_identity(fragment: PlacementFragment) -> dict[str, object]:
+    identity: dict[str, object] = {
+        "placement_fragment_id": fragment.placement_fragment_id,
+        "tensor_id": fragment.tensor_id,
+        "global_offset": fragment.global_offset,
+        "local_shape": fragment.local_shape,
+        "nbytes": fragment.nbytes,
+        "rank": asdict(fragment.rank),
+        "aliases": fragment.aliases,
+    }
+    # Keep the pre-virtual-stage canonical payload byte-for-byte stable. A
+    # stage participates in identity only when a framework explicitly assigns
+    # one, so legacy placements keep their existing placement IDs.
+    if fragment.pipeline_stage_id is not None:
+        identity["pipeline_stage_id"] = fragment.pipeline_stage_id
+    return identity
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/planner.py b/mooncake-reshard/python/mooncake/reshard/weight/planner.py
new file mode 100644
index 0000000000..12504c248a
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/planner.py
@@ -0,0 +1,57 @@
+"""Stable public facade for model-weight transfer planning."""
+
+from ._planner.api import (
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+    plan_stored_transfer_to_target_placement,
+)
+from ._planner.binding import (
+    bind_logical_transfer_plan,
+    resolve_executor_plan,
+    resolve_executor_plans,
+)
+from ._planner.bound_contracts import (
+    ExecutorTransferPlan,
+    RuntimeFragmentSnapshot,
+    TransferPlan,
+)
+from ._planner.contracts import (
+    BoundWeightFragment,
+    ExecutableTransferOperation,
+    LiveTransferOperation,
+    LogicalTransferPlan,
+    PlanningLimits,
+    LogicalTransferOperation,
+    PipelineRouteGroup,
+    PlacementExecutorPlan,
+    RuntimeTensorOwner,
+    StoredLoadOperation,
+    TransferRegion,
+)
+from ._planner.attestation import RuntimeBindingAttestation, RuntimeBindingEvidence
+
+
+__all__ = [
+    "BoundWeightFragment",
+    "ExecutableTransferOperation",
+    "ExecutorTransferPlan",
+    "LiveTransferOperation",
+    "LogicalTransferPlan",
+    "PlanningLimits",
+    "LogicalTransferOperation",
+    "PipelineRouteGroup",
+    "PlacementExecutorPlan",
+    "RuntimeFragmentSnapshot",
+    "RuntimeBindingAttestation",
+    "RuntimeBindingEvidence",
+    "RuntimeTensorOwner",
+    "StoredLoadOperation",
+    "TransferPlan",
+    "TransferRegion",
+    "bind_logical_transfer_plan",
+    "plan_placement_transfer",
+    "plan_placement_transfer_to_local_target",
+    "plan_stored_transfer_to_target_placement",
+    "resolve_executor_plan",
+    "resolve_executor_plans",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/runtime.py b/mooncake-reshard/python/mooncake/reshard/weight/runtime.py
new file mode 100644
index 0000000000..19920960c4
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/runtime.py
@@ -0,0 +1,80 @@
+"""Canonical ephemeral runtime binding contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..contracts import (
+    LeaseId,
+    ParticipantId,
+    PlacementId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    RuntimeBindingFragment,
+    RuntimeInstanceId,
+)
+from .types import (
+    _require_nonempty_string,
+    _require_u64,
+    require_manifest_items,
+    require_sha256_digest,
+)
+
+
+@dataclass(frozen=True)
+class WeightRuntimeBindingManifest:
+    """Ephemeral physical locations and lifetime fence for one placement."""
+
+    resource_id: ResourceId
+    placement_id: PlacementId
+    placement_digest: str
+    instance_id: RuntimeInstanceId
+    generation: int
+    lease_id: LeaseId
+    revision: RevisionId
+    participant_id: ParticipantId
+    fragments: tuple[RuntimeBindingFragment, ...]
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        """Identify this binding as model weight data."""
+
+        return ResourceKind.MODEL_WEIGHT
+
+    def __post_init__(self) -> None:
+        for name in (
+            "resource_id",
+            "placement_id",
+            "instance_id",
+            "lease_id",
+            "revision",
+            "participant_id",
+        ):
+            _require_nonempty_string(getattr(self, name), name)
+        require_sha256_digest(self.placement_digest, "placement_digest")
+        _require_u64(self.generation, "generation")
+        fragments = require_manifest_items(
+            self.fragments,
+            "WeightRuntimeBindingManifest fragments",
+            RuntimeBindingFragment,
+        )
+        object.__setattr__(
+            self,
+            "fragments",
+            tuple(
+                sorted(
+                    fragments,
+                    key=lambda item: item.placement_fragment_id,
+                )
+            ),
+        )
+        placement_ids = [item.placement_fragment_id for item in self.fragments]
+        if len(placement_ids) != len(set(placement_ids)):
+            raise ValueError("duplicate placement fragment in runtime binding")
+        fragment_ids = [item.fragment_id for item in self.fragments]
+        if len(fragment_ids) != len(set(fragment_ids)):
+            raise ValueError("duplicate runtime fragment_id in runtime binding")
+
+
+__all__ = ["WeightRuntimeBindingManifest"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/serde.py b/mooncake-reshard/python/mooncake/reshard/weight/serde.py
new file mode 100644
index 0000000000..06e662f14c
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/serde.py
@@ -0,0 +1,497 @@
+"""Canonical JSON serialization for model-weight placement manifests.
+
+This is the only untyped wire boundary in the manifest package. It accepts JSON
+values, rejects unknown or malformed fields, and returns only canonical typed
+domain values. Framework runtime objects are deliberately not accepted here.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+from typing import Optional, Union, cast
+
+from .._typing import TypeAlias
+
+from ..contracts import (
+    ParticipantId,
+    PlacementFragmentId,
+    PlacementId,
+    PlacementSetId,
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    TensorId,
+    TopologyId,
+)
+from .part import WeightPlacementPart
+from .placement import WeightPlacementManifest
+from .topology import ParallelTopology, TopologyParticipant
+from .types import (
+    OwnershipAxis,
+    ParallelAxis,
+    ParallelAxisKind,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    SplitAxis,
+    SplitAxisKind,
+    TensorDescriptor,
+)
+
+JsonScalar: TypeAlias = Union[None, bool, int, float, str]
+JsonValue: TypeAlias = Union[JsonScalar, list["JsonValue"], dict[str, "JsonValue"]]
+JsonObject: TypeAlias = Mapping[str, JsonValue]
+
+
+def weight_placement_to_json(placement: WeightPlacementManifest) -> str:
+    """Serialize one typed placement using the canonical wire schema."""
+
+    if not isinstance(placement, WeightPlacementManifest):
+        raise ValueError("placement must be a WeightPlacementManifest")  # noqa: TRY004
+    payload: dict[str, JsonValue] = {
+        "resource_kind": placement.resource_kind.value,
+        "resource_id": placement.resource_id,
+        "revision": placement.revision,
+        "weight_generation": placement.weight_generation,
+        "placement_set_id": placement.placement_set_id,
+        "placement_id": placement.placement_id,
+        "topology": _topology_to_wire(placement.topology),
+        "tensors": [_tensor_to_wire(tensor) for tensor in placement.tensors],
+        "parts": [_part_to_wire(part) for part in placement.parts],
+    }
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def weight_placement_from_json(value: str) -> WeightPlacementManifest:
+    """Parse only the canonical model-weight placement wire schema."""
+
+    manifest = _require_exact_fields(
+        _load_json_object(value, "placement manifest"),
+        {
+            "resource_kind",
+            "resource_id",
+            "revision",
+            "weight_generation",
+            "placement_set_id",
+            "placement_id",
+            "topology",
+            "tensors",
+            "parts",
+        },
+        "placement manifest",
+    )
+    if _require_nonempty_string(manifest["resource_kind"], "resource_kind") != (
+        ResourceKind.MODEL_WEIGHT.value
+    ):
+        raise ValueError("placement manifest resource_kind must be model_weight")
+
+    resource_id = ResourceId(
+        _require_nonempty_string(manifest["resource_id"], "resource_id")
+    )
+    revision = RevisionId(_require_nonempty_string(manifest["revision"], "revision"))
+    weight_generation = _require_integer(
+        manifest["weight_generation"], "weight_generation", minimum=0
+    )
+    placement_set_id = PlacementSetId(
+        _require_nonempty_string(manifest["placement_set_id"], "placement_set_id")
+    )
+    placement_id = PlacementId(
+        _require_nonempty_string(manifest["placement_id"], "placement_id")
+    )
+    topology = _topology_from_wire(manifest["topology"])
+    tensors = tuple(
+        _tensor_from_wire(item, index)
+        for index, item in enumerate(
+            _require_sequence(manifest["tensors"], "placement tensors")
+        )
+    )
+    tensor_by_id = {tensor.tensor_id: tensor for tensor in tensors}
+    if len(tensor_by_id) != len(tensors):
+        raise ValueError("duplicate tensor_id in placement JSON")
+
+    parts: list[WeightPlacementPart] = []
+    referenced_tensor_ids: set[TensorId] = set()
+    for index, item in enumerate(
+        _require_sequence(manifest["parts"], "placement parts")
+    ):
+        part = _require_exact_fields(
+            item,
+            {"participant_id", "rank", "fragments"},
+            f"placement part {index}",
+        )
+        participant_id = ParticipantId(
+            _require_nonempty_string(part["participant_id"], "participant_id")
+        )
+        rank = _rank_from_wire(part["rank"], f"placement part rank {index}")
+        fragments = tuple(
+            _fragment_from_wire(fragment, fragment_index)
+            for fragment_index, fragment in enumerate(
+                _require_sequence(part["fragments"], "placement part fragments")
+            )
+        )
+        local_tensor_ids = {fragment.tensor_id for fragment in fragments}
+        referenced_tensor_ids.update(local_tensor_ids)
+        unknown = sorted(local_tensor_ids - set(tensor_by_id))
+        if unknown:
+            raise ValueError(f"unknown tensor_id in placement part: {unknown[0]}")
+        parts.append(
+            WeightPlacementPart(
+                resource_id=resource_id,
+                revision=revision,
+                weight_generation=weight_generation,
+                placement_set_id=placement_set_id,
+                topology_id=topology.topology_id,
+                participant_id=participant_id,
+                rank=rank,
+                tensors=tuple(
+                    tensor_by_id[tensor_id] for tensor_id in sorted(local_tensor_ids)
+                ),
+                fragments=fragments,
+            )
+        )
+
+    unreferenced_tensor_ids = sorted(set(tensor_by_id) - referenced_tensor_ids)
+    if unreferenced_tensor_ids:
+        raise ValueError(
+            "placement JSON contains an unreferenced tensor: "
+            f"{unreferenced_tensor_ids[0]}"
+        )
+    return WeightPlacementManifest(
+        resource_id=resource_id,
+        revision=revision,
+        weight_generation=weight_generation,
+        placement_set_id=placement_set_id,
+        placement_id=placement_id,
+        topology=topology,
+        parts=tuple(parts),
+    )
+
+
+def _part_to_wire(part: WeightPlacementPart) -> dict[str, JsonValue]:
+    return {
+        "participant_id": part.participant_id,
+        "rank": _rank_to_wire(part.rank),
+        "fragments": [_fragment_to_wire(fragment) for fragment in part.fragments],
+    }
+
+
+def _topology_to_wire(topology: ParallelTopology) -> dict[str, JsonValue]:
+    return {
+        "tp_size": topology.tp_size,
+        "pp_size": topology.pp_size,
+        "ep_size": topology.ep_size,
+        "dp_size": topology.dp_size,
+        "topology_id": topology.topology_id,
+        "participants": [
+            {
+                "participant_id": participant.participant_id,
+                "rank": _rank_to_wire(participant.rank),
+            }
+            for participant in topology.participants
+        ],
+    }
+
+
+def _topology_from_wire(value: object) -> ParallelTopology:
+    topology = _require_exact_fields(
+        value,
+        {"tp_size", "pp_size", "ep_size", "dp_size", "topology_id", "participants"},
+        "parallel topology",
+    )
+    participants: list[TopologyParticipant] = []
+    for index, item in enumerate(
+        _require_sequence(topology["participants"], "parallel topology participants")
+    ):
+        participant = _require_exact_fields(
+            item,
+            {"participant_id", "rank"},
+            f"parallel topology participant {index}",
+        )
+        participants.append(
+            TopologyParticipant(
+                participant_id=ParticipantId(
+                    _require_nonempty_string(
+                        participant["participant_id"], "participant_id"
+                    )
+                ),
+                rank=_rank_from_wire(
+                    participant["rank"], f"parallel topology rank {index}"
+                ),
+            )
+        )
+    return ParallelTopology(
+        tp_size=_require_integer(topology["tp_size"], "tp_size", minimum=1),
+        pp_size=_require_integer(topology["pp_size"], "pp_size", minimum=1),
+        ep_size=_require_integer(topology["ep_size"], "ep_size", minimum=1),
+        dp_size=_require_integer(topology["dp_size"], "dp_size", minimum=1),
+        participants=tuple(participants),
+        topology_id=TopologyId(
+            _require_nonempty_string(topology["topology_id"], "topology_id")
+        ),
+    )
+
+
+def _tensor_to_wire(tensor: TensorDescriptor) -> dict[str, JsonValue]:
+    return {
+        "tensor_id": tensor.tensor_id,
+        "global_shape": list(tensor.global_shape),
+        "dtype": tensor.dtype,
+        "itemsize": tensor.itemsize,
+        "shard_dims": list(tensor.shard_dims),
+        "layout_fingerprint": tensor.layout_fingerprint,
+        "parallel_axes": [_axis_to_wire(axis) for axis in tensor.parallel_axes],
+        "layer_id": tensor.layer_id,
+        "expert_id": tensor.expert_id,
+    }
+
+
+def _tensor_from_wire(value: object, index: int) -> TensorDescriptor:
+    tensor = _require_exact_fields(
+        value,
+        {
+            "tensor_id",
+            "global_shape",
+            "dtype",
+            "itemsize",
+            "shard_dims",
+            "layout_fingerprint",
+            "parallel_axes",
+            "layer_id",
+            "expert_id",
+        },
+        f"placement tensor {index}",
+    )
+    return TensorDescriptor(
+        tensor_id=TensorId(_require_nonempty_string(tensor["tensor_id"], "tensor_id")),
+        global_shape=_integer_tuple(tensor["global_shape"], "global_shape", minimum=1),
+        dtype=_require_nonempty_string(tensor["dtype"], "dtype"),
+        itemsize=_require_integer(tensor["itemsize"], "itemsize", minimum=1),
+        shard_dims=_integer_tuple(tensor["shard_dims"], "shard_dims", minimum=0),
+        layout_fingerprint=_require_nonempty_string(
+            tensor["layout_fingerprint"], "layout_fingerprint"
+        ),
+        parallel_axes=tuple(
+            _axis_from_wire(axis, axis_index)
+            for axis_index, axis in enumerate(
+                _require_sequence(
+                    tensor["parallel_axes"], "placement tensor parallel_axes"
+                )
+            )
+        ),
+        layer_id=_optional_integer(tensor["layer_id"], "layer_id", minimum=0),
+        expert_id=_optional_integer(tensor["expert_id"], "expert_id", minimum=0),
+    )
+
+
+def _axis_to_wire(axis: ParallelAxis) -> dict[str, JsonValue]:
+    if isinstance(axis, SplitAxis):
+        return {"semantics": "split", "kind": axis.kind, "dim": axis.dim}
+    if isinstance(axis, ReplicatedAxis):
+        return {"semantics": "replicated", "kind": axis.kind}
+    if isinstance(axis, OwnershipAxis):
+        return {"semantics": "ownership", "kind": axis.kind}
+    raise ValueError("unsupported parallel axis value")
+
+
+def _axis_from_wire(value: object, index: int) -> ParallelAxis:
+    axis = _require_mapping(value, f"placement tensor parallel axis {index}")
+    semantics = _require_nonempty_string(axis.get("semantics"), "axis semantics")
+    if semantics == "split":
+        split = _require_exact_fields(
+            axis,
+            {"semantics", "kind", "dim"},
+            f"placement tensor parallel axis {index}",
+        )
+        return SplitAxis(
+            kind=_split_axis_kind(split["kind"]),
+            dim=_require_integer(split["dim"], "split axis dim", minimum=0),
+        )
+    if semantics == "replicated":
+        replicated = _require_exact_fields(
+            axis,
+            {"semantics", "kind"},
+            f"placement tensor parallel axis {index}",
+        )
+        return ReplicatedAxis(kind=_parallel_axis_kind(replicated["kind"]))
+    if semantics == "ownership":
+        ownership = _require_exact_fields(
+            axis,
+            {"semantics", "kind"},
+            f"placement tensor parallel axis {index}",
+        )
+        return OwnershipAxis(kind=_parallel_axis_kind(ownership["kind"]))
+    raise ValueError(f"unsupported parallel axis semantics: {semantics}")
+
+
+def _fragment_to_wire(fragment: PlacementFragment) -> dict[str, JsonValue]:
+    result: dict[str, JsonValue] = {
+        "placement_fragment_id": fragment.placement_fragment_id,
+        "tensor_id": fragment.tensor_id,
+        "global_offset": list(fragment.global_offset),
+        "local_shape": list(fragment.local_shape),
+        "nbytes": fragment.nbytes,
+        "rank": _rank_to_wire(fragment.rank),
+        "aliases": list(fragment.aliases),
+    }
+    if fragment.pipeline_stage_id is not None:
+        result["pipeline_stage_id"] = fragment.pipeline_stage_id
+    return result
+
+
+def _fragment_from_wire(value: object, index: int) -> PlacementFragment:
+    fragment = _require_mapping(value, f"placement fragment {index}")
+    expected_fields = {
+        "placement_fragment_id",
+        "tensor_id",
+        "global_offset",
+        "local_shape",
+        "nbytes",
+        "rank",
+        "pipeline_stage_id",
+        "aliases",
+    }
+    legacy_fields = expected_fields - {"pipeline_stage_id"}
+    fragment_fields = set(fragment)
+    if fragment_fields != expected_fields and fragment_fields != legacy_fields:
+        raise ValueError(f"placement fragment {index} has an invalid schema")
+    return PlacementFragment(
+        placement_fragment_id=PlacementFragmentId(
+            _require_nonempty_string(
+                fragment["placement_fragment_id"], "placement_fragment_id"
+            )
+        ),
+        tensor_id=TensorId(
+            _require_nonempty_string(fragment["tensor_id"], "tensor_id")
+        ),
+        global_offset=_integer_tuple(
+            fragment["global_offset"], "global_offset", minimum=0
+        ),
+        local_shape=_integer_tuple(fragment["local_shape"], "local_shape", minimum=1),
+        nbytes=_require_integer(fragment["nbytes"], "nbytes", minimum=1),
+        rank=_rank_from_wire(fragment["rank"], f"placement rank {index}"),
+        pipeline_stage_id=_optional_integer(
+            fragment.get("pipeline_stage_id"),
+            "pipeline_stage_id",
+            minimum=0,
+        ),
+        aliases=tuple(
+            TensorId(_require_nonempty_string(alias, "alias"))
+            for alias in _require_sequence(fragment["aliases"], "aliases")
+        ),
+    )
+
+
+def _rank_to_wire(rank: ParallelRank) -> dict[str, JsonValue]:
+    return {"dp": rank.dp, "tp": rank.tp, "pp": rank.pp, "ep": rank.ep}
+
+
+def _rank_from_wire(value: object, label: str) -> ParallelRank:
+    rank = _require_exact_fields(value, {"dp", "tp", "pp", "ep"}, label)
+    return ParallelRank(
+        dp=_require_integer(rank["dp"], "rank dp", minimum=0),
+        tp=_require_integer(rank["tp"], "rank tp", minimum=0),
+        pp=_require_integer(rank["pp"], "rank pp", minimum=0),
+        ep=_require_integer(rank["ep"], "rank ep", minimum=0),
+    )
+
+
+def _load_json_object(value: str, label: str) -> JsonObject:
+    def reject_constant(constant: str) -> None:
+        raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+    def reject_duplicate_fields(
+        pairs: list[tuple[str, object]],
+    ) -> dict[str, JsonValue]:
+        result: dict[str, JsonValue] = {}
+        for key, item in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON field: {key}")
+            result[key] = cast(JsonValue, item)
+        return result
+
+    try:
+        raw = json.loads(
+            value,
+            parse_constant=reject_constant,
+            object_pairs_hook=reject_duplicate_fields,
+        )
+    except (TypeError, json.JSONDecodeError) as error:
+        raise ValueError(f"{label} is not valid JSON") from error
+    return _require_mapping(cast(object, raw), label)
+
+
+def _require_mapping(value: object, label: str) -> JsonObject:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be a JSON object")  # noqa: TRY004
+    mapping = cast(Mapping[object, object], value)
+    if any(type(key) is not str for key in mapping):
+        raise ValueError(f"{label} must be a JSON object")
+    return cast(JsonObject, mapping)
+
+
+def _require_exact_fields(
+    value: object,
+    expected: AbstractSet[str],
+    label: str,
+) -> JsonObject:
+    mapping = _require_mapping(value, label)
+    if set(mapping) != set(expected):
+        raise ValueError(f"{label} schema fields do not match contract")
+    return mapping
+
+
+def _require_sequence(value: object, label: str) -> Sequence[JsonValue]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{label} must be a sequence")  # noqa: TRY004
+    return cast(Sequence[JsonValue], value)
+
+
+def _require_nonempty_string(value: object, label: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{label} must be a non-empty string")
+    return value
+
+
+def _require_integer(value: object, label: str, *, minimum: int) -> int:
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{label} must be an integer at least {minimum}")
+    return value
+
+
+def _optional_integer(
+    value: object,
+    label: str,
+    *,
+    minimum: int,
+) -> Optional[int]:
+    if value is None:
+        return None
+    return _require_integer(value, label, minimum=minimum)
+
+
+def _integer_tuple(
+    value: object,
+    label: str,
+    *,
+    minimum: int,
+) -> tuple[int, ...]:
+    return tuple(
+        _require_integer(item, label, minimum=minimum)
+        for item in _require_sequence(value, label)
+    )
+
+
+def _parallel_axis_kind(value: object) -> ParallelAxisKind:
+    kind = _require_nonempty_string(value, "parallel axis kind")
+    if kind not in {"dp", "pp", "ep", "tp"}:
+        raise ValueError(f"unsupported parallel axis kind: {kind}")
+    return cast(ParallelAxisKind, kind)
+
+
+def _split_axis_kind(value: object) -> SplitAxisKind:
+    kind = _parallel_axis_kind(value)
+    if kind not in {"ep", "tp"}:
+        raise ValueError(f"{kind} cannot use split semantics")
+    return cast(SplitAxisKind, kind)
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/storage_manifest.py b/mooncake-reshard/python/mooncake/reshard/weight/storage_manifest.py
new file mode 100644
index 0000000000..8bec73c52f
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/storage_manifest.py
@@ -0,0 +1,675 @@
+"""Persisted model-weight fragments and manifest contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from math import prod
+from collections.abc import Mapping, Sequence
+from typing import Optional, Union, cast
+
+from .._typing import TypeAlias
+
+from .._compat import _strict_zip
+from ..contracts import (
+    ResourceId,
+    ResourceKind,
+    RevisionId,
+    StoredFragmentSnapshotId,
+    StoredResourceManifest,
+    TensorId,
+)
+from .serde import _axis_from_wire, _axis_to_wire
+from .types import (
+    TensorDescriptor,
+    ParallelAxis,
+    _normalize_aliases,
+    _require_integer,
+    _require_integer_tuple,
+    _require_manifest_items,
+    _require_nonempty_string,
+    _require_sequence,
+    _require_u64,
+    validate_fragment_geometry,
+)
+
+
+StoredGeometryKey: TypeAlias = tuple[TensorId, tuple[int, ...], tuple[int, ...]]
+StoredAliasDescriptorKey: TypeAlias = tuple[
+    tuple[int, ...],
+    str,
+    int,
+    tuple[int, ...],
+    tuple[ParallelAxis, ...],
+    Optional[int],
+    Optional[int],
+    str,
+]
+StoredAliasGeometryKey: TypeAlias = tuple[
+    tuple[TensorId, ...],
+    tuple[int, ...],
+    tuple[int, ...],
+    int,
+]
+
+
+@dataclass(frozen=True)
+class StoredManifestIdentity:
+    """Stable identity for a committed Store manifest snapshot."""
+
+    namespace: str
+    resource_id: ResourceId
+    revision: RevisionId
+    weight_generation: int
+    group_id: str
+    manifest_key: str
+    content_sha256: str
+
+    def __post_init__(self) -> None:
+        for name in (
+            "namespace",
+            "resource_id",
+            "revision",
+            "group_id",
+            "manifest_key",
+            "content_sha256",
+        ):
+            _require_nonempty_string(getattr(self, name), name)
+        _require_u64(self.weight_generation, "weight_generation")
+        if len(self.content_sha256) != 64 or any(
+            character not in "0123456789abcdef" for character in self.content_sha256
+        ):
+            raise ValueError("content_sha256 must be a SHA-256 hex digest")
+
+
+@dataclass(frozen=True)
+class StoredFragmentSnapshot:
+    fragment_id: StoredFragmentSnapshotId
+    tensor_id: TensorId
+    global_offset: tuple[int, ...]
+    local_shape: tuple[int, ...]
+    object_key: str
+    object_offset: int
+    nbytes: int
+    aliases: tuple[TensorId, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "global_offset",
+            _require_integer_tuple(self.global_offset, "global_offset", minimum=0),
+        )
+        object.__setattr__(
+            self,
+            "local_shape",
+            _require_integer_tuple(self.local_shape, "local_shape", minimum=1),
+        )
+        for name in ("fragment_id", "tensor_id", "object_key"):
+            _require_nonempty_string(getattr(self, name), name)
+        _require_integer(self.object_offset, "object_offset", minimum=0)
+        _require_integer(self.nbytes, "nbytes", minimum=1)
+        object.__setattr__(self, "aliases", _normalize_aliases(self.aliases))
+        if self.aliases:
+            if len(self.aliases) < 2:
+                raise ValueError("alias group must contain at least two tensor IDs")
+            if self.tensor_id not in self.aliases:
+                raise ValueError("alias group must contain the fragment tensor_id")
+
+
+@dataclass(frozen=True)
+class StoredWeightManifest(StoredResourceManifest):
+    revision: RevisionId
+    weight_generation: int
+    tensors: tuple[TensorDescriptor, ...]
+    fragments: tuple[StoredFragmentSnapshot, ...]
+    manifest_digest: str = field(init=False)
+
+    @property
+    def resource_kind(self) -> ResourceKind:
+        return ResourceKind.MODEL_WEIGHT
+
+    def __post_init__(self) -> None:
+        for name in (
+            "namespace",
+            "resource_id",
+            "revision",
+            "group_id",
+            "manifest_key",
+            "created_at",
+        ):
+            _require_nonempty_string(getattr(self, name), name)
+        object.__setattr__(
+            self,
+            "tensors",
+            _require_manifest_items(
+                self.tensors,
+                "StoredWeightManifest tensors",
+                TensorDescriptor,
+            ),
+        )
+        object.__setattr__(
+            self,
+            "fragments",
+            _require_manifest_items(
+                self.fragments,
+                "StoredWeightManifest fragments",
+                StoredFragmentSnapshot,
+            ),
+        )
+        _require_u64(self.weight_generation, "weight_generation")
+        if self.manifest_key != f"{self.group_id}/manifest":
+            raise ValueError("manifest_key does not belong to manifest group")
+        payload_prefix = f"{self.group_id}/payload/"
+        if any(
+            not fragment.object_key.startswith(payload_prefix)
+            for fragment in self.fragments
+        ):
+            raise ValueError("payload object_key does not belong to manifest group")
+        _validate_stored_fragments(self.tensors, self.fragments)
+        _validate_stored_aliases(self.tensors, self.fragments)
+        _validate_stored_coverage(self.tensors, self.fragments)
+        _validate_stored_object_ranges(self.fragments)
+        object.__setattr__(
+            self,
+            "manifest_digest",
+            hashlib.sha256(self.to_json().encode("utf-8")).hexdigest(),
+        )
+
+    def __getstate__(self) -> tuple[object, ...]:
+        """Serialize logical state and recompute the digest on restore."""
+
+        return (
+            self.namespace,
+            self.resource_id,
+            self.revision,
+            self.weight_generation,
+            self.group_id,
+            self.manifest_key,
+            self.tensors,
+            self.fragments,
+            self.created_at,
+        )
+
+    def __setstate__(self, state: tuple[object, ...]) -> None:
+        """Restore only a fully validated persisted manifest state."""
+
+        if not isinstance(state, tuple) or len(state) != 9:
+            raise ValueError("StoredWeightManifest pickle state is invalid")
+        for name, value in zip(
+            (
+                "namespace",
+                "resource_id",
+                "revision",
+                "weight_generation",
+                "group_id",
+                "manifest_key",
+                "tensors",
+                "fragments",
+                "created_at",
+            ),
+            state,
+        ):
+            object.__setattr__(self, name, value)
+        self.__post_init__()
+
+    @property
+    def manifest_identity(self) -> StoredManifestIdentity:
+        """Return the Store location plus a canonical content digest."""
+
+        return StoredManifestIdentity(
+            namespace=self.namespace,
+            resource_id=self.resource_id,
+            revision=self.revision,
+            weight_generation=self.weight_generation,
+            group_id=self.group_id,
+            manifest_key=self.manifest_key,
+            content_sha256=self.manifest_digest,
+        )
+
+    def to_json(self) -> str:
+        tensors: list[dict[str, object]] = []
+        for tensor in self.tensors:
+            tensors.append(
+                {
+                    "tensor_id": tensor.tensor_id,
+                    "global_shape": tensor.global_shape,
+                    "dtype": tensor.dtype,
+                    "itemsize": tensor.itemsize,
+                    "layer_id": tensor.layer_id,
+                    "expert_id": tensor.expert_id,
+                    "layout_fingerprint": tensor.layout_fingerprint,
+                    "shard_dims": tensor.shard_dims,
+                    "parallel_axes": [
+                        _axis_to_wire(axis) for axis in tensor.parallel_axes
+                    ],
+                }
+            )
+        raw: dict[str, object] = {
+            "resource_kind": self.resource_kind.value,
+            "namespace": self.namespace,
+            "resource_id": self.resource_id,
+            "revision": self.revision,
+            "weight_generation": self.weight_generation,
+            "group_id": self.group_id,
+            "manifest_key": self.manifest_key,
+            "tensors": tensors,
+            "fragments": [asdict(fragment) for fragment in self.fragments],
+            "created_at": self.created_at,
+        }
+        return json.dumps(
+            raw,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+
+    @classmethod
+    def from_json(
+        cls,
+        value: Union[str, bytes, bytearray],
+    ) -> StoredWeightManifest:
+        def reject_constant(constant: str) -> None:
+            raise ValueError(f"non-finite JSON number is unsupported: {constant}")
+
+        def reject_duplicate_fields(
+            pairs: list[tuple[str, object]],
+        ) -> dict[str, object]:
+            result: dict[str, object] = {}
+            for key, item in pairs:
+                if key in result:
+                    raise ValueError(f"duplicate JSON field: {key}")
+                result[key] = item
+            return result
+
+        try:
+            raw = json.loads(
+                value,
+                parse_constant=reject_constant,
+                object_pairs_hook=reject_duplicate_fields,
+            )
+        except (TypeError, json.JSONDecodeError) as error:
+            raise ValueError("weight manifest is not valid JSON") from error
+        return cls.from_dict(_require_mapping(cast(object, raw), "weight manifest"))
+
+    @classmethod
+    def from_dict(cls, raw: Mapping[str, object]) -> StoredWeightManifest:
+        raw = _require_exact_fields(
+            raw,
+            frozenset(
+                {
+                    "resource_kind",
+                    "namespace",
+                    "resource_id",
+                    "revision",
+                    "weight_generation",
+                    "group_id",
+                    "manifest_key",
+                    "tensors",
+                    "fragments",
+                    "created_at",
+                }
+            ),
+            "weight manifest",
+        )
+        tensor_fields = frozenset(
+            {
+                "tensor_id",
+                "global_shape",
+                "dtype",
+                "itemsize",
+                "layer_id",
+                "expert_id",
+                "layout_fingerprint",
+                "shard_dims",
+                "parallel_axes",
+            }
+        )
+        fragment_fields = frozenset(
+            {
+                "fragment_id",
+                "tensor_id",
+                "global_offset",
+                "local_shape",
+                "object_key",
+                "object_offset",
+                "nbytes",
+                "aliases",
+            }
+        )
+        tensors: list[TensorDescriptor] = []
+        if raw["resource_kind"] != ResourceKind.MODEL_WEIGHT.value:
+            raise ValueError("weight manifest resource_kind must be model_weight")
+        for index, item in enumerate(
+            _require_sequence(raw["tensors"], "StoredWeightManifest tensors")
+        ):
+            tensor_values: dict[str, object] = dict(
+                _require_exact_fields(item, tensor_fields, "tensor descriptor")
+            )
+            parallel_axes = tuple(
+                _axis_from_wire(axis, axis_index)
+                for axis_index, axis in enumerate(
+                    _require_sequence(
+                        tensor_values["parallel_axes"],
+                        f"stored tensor parallel_axes {index}",
+                    )
+                )
+            )
+            tensors.append(
+                TensorDescriptor(
+                    tensor_id=TensorId(
+                        _require_nonempty_string(
+                            tensor_values["tensor_id"],
+                            "stored tensor tensor_id",
+                        )
+                    ),
+                    global_shape=_require_integer_tuple(
+                        tensor_values["global_shape"],
+                        "stored tensor global_shape",
+                        minimum=1,
+                    ),
+                    dtype=_require_nonempty_string(
+                        tensor_values["dtype"], "stored tensor dtype"
+                    ),
+                    itemsize=_require_integer(
+                        tensor_values["itemsize"], "stored tensor itemsize", minimum=1
+                    ),
+                    layer_id=_optional_integer(
+                        tensor_values["layer_id"], "stored tensor layer_id", minimum=0
+                    ),
+                    expert_id=_optional_integer(
+                        tensor_values["expert_id"], "stored tensor expert_id", minimum=0
+                    ),
+                    layout_fingerprint=_require_nonempty_string(
+                        tensor_values["layout_fingerprint"],
+                        "stored tensor layout_fingerprint",
+                    ),
+                    shard_dims=_require_integer_tuple(
+                        tensor_values["shard_dims"],
+                        "stored tensor shard_dims",
+                        minimum=0,
+                    ),
+                    parallel_axes=parallel_axes,
+                )
+            )
+        fragments: tuple[StoredFragmentSnapshot, ...] = tuple(
+            _stored_fragment_from_wire(item, fragment_fields)
+            for item in _require_sequence(
+                raw["fragments"],
+                "StoredWeightManifest fragments",
+            )
+        )
+        return cls(
+            namespace=_require_nonempty_string(raw["namespace"], "namespace"),
+            resource_id=ResourceId(
+                _require_nonempty_string(raw["resource_id"], "resource_id")
+            ),
+            revision=RevisionId(_require_nonempty_string(raw["revision"], "revision")),
+            weight_generation=_require_u64(
+                raw["weight_generation"], "weight_generation"
+            ),
+            group_id=_require_nonempty_string(raw["group_id"], "group_id"),
+            manifest_key=_require_nonempty_string(raw["manifest_key"], "manifest_key"),
+            tensors=tuple(tensors),
+            fragments=fragments,
+            created_at=_require_nonempty_string(raw["created_at"], "created_at"),
+        )
+
+
+def validate_weight_manifest_snapshot(
+    manifest: StoredWeightManifest,
+) -> StoredWeightManifest:
+    """Rebuild a typed manifest before it is trusted at a plan boundary."""
+
+    if not isinstance(manifest, StoredWeightManifest):
+        raise ValueError("weight manifest snapshot is invalid")
+    try:
+        return StoredWeightManifest(
+            namespace=manifest.namespace,
+            resource_id=manifest.resource_id,
+            revision=manifest.revision,
+            weight_generation=manifest.weight_generation,
+            group_id=manifest.group_id,
+            manifest_key=manifest.manifest_key,
+            tensors=manifest.tensors,
+            fragments=manifest.fragments,
+            created_at=manifest.created_at,
+        )
+    except (AttributeError, TypeError) as error:
+        raise ValueError("weight manifest snapshot is invalid") from error
+
+
+def _require_exact_fields(
+    value: object,
+    expected: frozenset[str],
+    label: str,
+) -> Mapping[str, object]:
+    mapping = _require_mapping(value, label)
+    if frozenset(mapping) != expected:
+        raise ValueError(f"{label} schema fields do not match contract")
+    return mapping
+
+
+def _require_mapping(value: object, label: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be a JSON object")
+    raw = cast(Mapping[object, object], value)
+    if any(type(key) is not str for key in raw):
+        raise ValueError(f"{label} must be a JSON object")
+    return {cast(str, key): item for key, item in raw.items()}
+
+
+def _optional_integer(
+    value: object,
+    label: str,
+    *,
+    minimum: int,
+) -> Optional[int]:
+    if value is None:
+        return None
+    return _require_integer(value, label, minimum=minimum)
+
+
+def _stored_fragment_from_wire(
+    value: object,
+    fragment_fields: frozenset[str],
+) -> StoredFragmentSnapshot:
+    fragment = _require_exact_fields(value, fragment_fields, "stored fragment")
+    return StoredFragmentSnapshot(
+        fragment_id=StoredFragmentSnapshotId(
+            _require_nonempty_string(
+                fragment["fragment_id"], "stored fragment fragment_id"
+            )
+        ),
+        tensor_id=TensorId(
+            _require_nonempty_string(fragment["tensor_id"], "stored fragment tensor_id")
+        ),
+        global_offset=_require_integer_tuple(
+            fragment["global_offset"], "stored fragment global_offset", minimum=0
+        ),
+        local_shape=_require_integer_tuple(
+            fragment["local_shape"], "stored fragment local_shape", minimum=1
+        ),
+        object_key=_require_nonempty_string(
+            fragment["object_key"], "stored fragment object_key"
+        ),
+        object_offset=_require_integer(
+            fragment["object_offset"], "stored fragment object_offset", minimum=0
+        ),
+        nbytes=_require_integer(
+            fragment["nbytes"], "stored fragment nbytes", minimum=1
+        ),
+        aliases=tuple(
+            TensorId(_require_nonempty_string(alias, "stored fragment alias"))
+            for alias in _require_sequence(
+                fragment["aliases"], "stored fragment aliases"
+            )
+        ),
+    )
+
+
+def _validate_stored_fragments(
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[StoredFragmentSnapshot],
+) -> None:
+    tensor_by_id: dict[TensorId, TensorDescriptor] = {}
+    for tensor in tensors:
+        if tensor.tensor_id in tensor_by_id:
+            raise ValueError(f"duplicate tensor_id: {tensor.tensor_id}")
+        tensor_by_id[tensor.tensor_id] = tensor
+
+    fragment_ids: set[StoredFragmentSnapshotId] = set()
+    for fragment in fragments:
+        if fragment.fragment_id in fragment_ids:
+            raise ValueError(f"duplicate fragment_id: {fragment.fragment_id}")
+        fragment_ids.add(fragment.fragment_id)
+        tensor = tensor_by_id.get(fragment.tensor_id)
+        if tensor is None:
+            raise ValueError(f"unknown tensor_id: {fragment.tensor_id}")
+        validate_fragment_geometry(
+            tensor,
+            fragment_id=fragment.fragment_id,
+            global_offset=fragment.global_offset,
+            local_shape=fragment.local_shape,
+            nbytes=fragment.nbytes,
+        )
+
+
+def _validate_stored_coverage(
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[StoredFragmentSnapshot],
+) -> None:
+    by_tensor: dict[TensorId, list[StoredFragmentSnapshot]] = {}
+    geometries: set[StoredGeometryKey] = set()
+    for fragment in fragments:
+        geometry = (
+            fragment.tensor_id,
+            fragment.global_offset,
+            fragment.local_shape,
+        )
+        if geometry in geometries:
+            raise ValueError(f"duplicate fragment geometry: {fragment.tensor_id}")
+        geometries.add(geometry)
+        by_tensor.setdefault(fragment.tensor_id, []).append(fragment)
+
+    for tensor in tensors:
+        tensor_fragments = by_tensor.get(tensor.tensor_id, [])
+        covered_volume = sum(
+            prod(fragment.local_shape) for fragment in tensor_fragments
+        )
+        if covered_volume != prod(tensor.global_shape) or _has_overlapping_boxes(
+            tensor_fragments
+        ):
+            raise ValueError(f"tensor is not fully covered: {tensor.tensor_id}")
+
+
+def _stored_alias_descriptor_key(
+    tensor: TensorDescriptor,
+) -> StoredAliasDescriptorKey:
+    return (
+        tensor.global_shape,
+        tensor.dtype,
+        tensor.itemsize,
+        tensor.shard_dims,
+        tensor.parallel_axes,
+        tensor.layer_id,
+        tensor.expert_id,
+        tensor.layout_fingerprint,
+    )
+
+
+def _validate_stored_aliases(
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[StoredFragmentSnapshot],
+) -> None:
+    tensor_by_id: dict[TensorId, TensorDescriptor] = {
+        tensor.tensor_id: tensor for tensor in tensors
+    }
+    by_group_and_geometry: dict[
+        StoredAliasGeometryKey, list[StoredFragmentSnapshot]
+    ] = {}
+    for fragment in fragments:
+        if not fragment.aliases:
+            continue
+        unknown = sorted(set(fragment.aliases) - set(tensor_by_id))
+        if unknown:
+            raise ValueError(f"stored alias references unknown tensor: {unknown[0]}")
+        key = (
+            fragment.aliases,
+            fragment.global_offset,
+            fragment.local_shape,
+            fragment.nbytes,
+        )
+        by_group_and_geometry.setdefault(key, []).append(fragment)
+
+    for (aliases, *_), alias_fragments in by_group_and_geometry.items():
+        tensor_ids = {fragment.tensor_id for fragment in alias_fragments}
+        if tensor_ids != set(aliases):
+            raise ValueError("stored alias group is incomplete for fragment geometry")
+        descriptor_keys = {
+            _stored_alias_descriptor_key(tensor_by_id[tensor_id])
+            for tensor_id in tensor_ids
+        }
+        if len(descriptor_keys) != 1:
+            raise ValueError("stored alias tensor descriptors differ")
+
+
+def _validate_stored_object_ranges(
+    fragments: Sequence[StoredFragmentSnapshot],
+) -> None:
+    by_object: dict[str, list[StoredFragmentSnapshot]] = {}
+    for fragment in fragments:
+        by_object.setdefault(fragment.object_key, []).append(fragment)
+
+    for object_key, object_fragments in by_object.items():
+        ordered = sorted(object_fragments, key=lambda item: item.object_offset)
+        for previous, current in zip(ordered, ordered[1:]):
+            if current.object_offset < previous.object_offset + previous.nbytes:
+                raise ValueError(
+                    "stored fragment object ranges overlap: "
+                    f"{previous.fragment_id} and {current.fragment_id} "
+                    f"in {object_key}"
+                )
+
+
+def _has_overlapping_boxes(fragments: Sequence[StoredFragmentSnapshot]) -> bool:
+    if len(fragments) < 2:
+        return False
+
+    ndim = len(fragments[0].global_offset)
+    sweep_dim = max(
+        range(ndim),
+        key=lambda dim: len(
+            {
+                (
+                    fragment.global_offset[dim],
+                    fragment.global_offset[dim] + fragment.local_shape[dim],
+                )
+                for fragment in fragments
+            }
+        ),
+    )
+    ordered = sorted(fragments, key=lambda item: item.global_offset[sweep_dim])
+    active: list[StoredFragmentSnapshot] = []
+    for fragment in ordered:
+        begin = fragment.global_offset[sweep_dim]
+        active = [
+            candidate
+            for candidate in active
+            if candidate.global_offset[sweep_dim] + candidate.local_shape[sweep_dim]
+            > begin
+        ]
+        for candidate in active:
+            if all(
+                left_offset < right_offset + right_extent
+                and right_offset < left_offset + left_extent
+                for left_offset, left_extent, right_offset, right_extent in _strict_zip(
+                    candidate.global_offset,
+                    candidate.local_shape,
+                    fragment.global_offset,
+                    fragment.local_shape,
+                )
+            ):
+                return True
+        active.append(fragment)
+    return False
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/store.py b/mooncake-reshard/python/mooncake/reshard/weight/store.py
new file mode 100644
index 0000000000..857d561fab
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/store.py
@@ -0,0 +1,31 @@
+"""Stable public facade for model weight Store operations."""
+
+from ._store import (
+    UploadOperation,
+    UploadReceipt,
+    StoreRegistrationLease,
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+    WeightStoreWriter,
+    WeightLoadPlan,
+    WeightStore,
+    WeightStoreError,
+    WeightUploadPlan,
+    begin_weight_snapshot,
+    plan_weight_upload,
+)
+
+__all__ = [
+    "UploadOperation",
+    "UploadReceipt",
+    "StoreRegistrationLease",
+    "WeightSnapshotAdapter",
+    "WeightSnapshotDescriptor",
+    "WeightStoreWriter",
+    "WeightLoadPlan",
+    "WeightStore",
+    "WeightStoreError",
+    "WeightUploadPlan",
+    "begin_weight_snapshot",
+    "plan_weight_upload",
+]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/topology.py b/mooncake-reshard/python/mooncake/reshard/weight/topology.py
new file mode 100644
index 0000000000..2f99048b27
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/topology.py
@@ -0,0 +1,152 @@
+"""Global parallel topology for one model-weight placement."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+from ..contracts import ParticipantId, TopologyId
+from .types import (
+    ParallelRank,
+    _require_integer,
+    _require_nonempty_string,
+    require_manifest_items,
+)
+
+
+@dataclass(frozen=True)
+class TopologyParticipant:
+    """One runtime participant and its framework-defined parallel coordinates."""
+
+    participant_id: ParticipantId
+    rank: ParallelRank
+
+    def __post_init__(self) -> None:
+        _require_nonempty_string(self.participant_id, "participant_id")
+        if not isinstance(self.rank, ParallelRank):
+            raise ValueError(  # noqa: TRY004
+                "topology participant rank must be a ParallelRank"
+            )
+
+
+@dataclass(frozen=True, init=False)
+class ParallelTopology:
+    """Complete TP/PP/EP/DP dimensions and selected participant mapping.
+
+    ``world_size`` is the number of explicit participants. It is deliberately
+    not inferred from the product of the four axis sizes because frameworks may
+    map TP and EP onto the same workers, and a placement may select one DP
+    replica while retaining the source runtime's declared ``dp_size``.
+    """
+
+    tp_size: int
+    pp_size: int
+    ep_size: int
+    dp_size: int
+    participants: tuple[TopologyParticipant, ...]
+    topology_id: TopologyId
+
+    def __init__(
+        self,
+        *,
+        tp_size: int,
+        pp_size: int,
+        ep_size: int,
+        dp_size: int,
+        participants: tuple[TopologyParticipant, ...],
+        topology_id: Optional[TopologyId] = None,
+    ) -> None:
+        for value, name in (
+            (tp_size, "tp_size"),
+            (pp_size, "pp_size"),
+            (ep_size, "ep_size"),
+            (dp_size, "dp_size"),
+        ):
+            _require_integer(value, name, minimum=1)
+        normalized_participants = require_manifest_items(
+            participants,
+            "ParallelTopology participants",
+            TopologyParticipant,
+        )
+        if not normalized_participants:
+            raise ValueError("parallel topology participants must not be empty")
+        normalized_participants = tuple(
+            sorted(normalized_participants, key=lambda item: item.participant_id)
+        )
+
+        participant_ids = [item.participant_id for item in normalized_participants]
+        if len(participant_ids) != len(set(participant_ids)):
+            raise ValueError("duplicate topology participant_id")
+        ranks = [item.rank for item in normalized_participants]
+        if len(ranks) != len(set(ranks)):
+            raise ValueError("duplicate topology parallel rank")
+
+        axis_sizes = {
+            "tp": tp_size,
+            "pp": pp_size,
+            "ep": ep_size,
+            "dp": dp_size,
+        }
+        for participant in normalized_participants:
+            for axis, size in axis_sizes.items():
+                value = getattr(participant.rank, axis)
+                if value >= size:
+                    raise ValueError(
+                        f"{axis} rank is out of range for participant "
+                        f"{participant.participant_id}"
+                    )
+
+        canonical_id = _topology_id(
+            tp_size=tp_size,
+            pp_size=pp_size,
+            ep_size=ep_size,
+            dp_size=dp_size,
+            participants=normalized_participants,
+        )
+        if topology_id is not None and topology_id != canonical_id:
+            raise ValueError("topology_id does not match canonical topology")
+        object.__setattr__(self, "tp_size", tp_size)
+        object.__setattr__(self, "pp_size", pp_size)
+        object.__setattr__(self, "ep_size", ep_size)
+        object.__setattr__(self, "dp_size", dp_size)
+        object.__setattr__(self, "participants", normalized_participants)
+        object.__setattr__(self, "topology_id", canonical_id)
+
+    @property
+    def world_size(self) -> int:
+        """Return the number of actual runtime participants."""
+
+        return len(self.participants)
+
+    def participant(self, participant_id: ParticipantId) -> TopologyParticipant:
+        """Return one declared participant or reject an unknown identifier."""
+
+        for participant in self.participants:
+            if participant.participant_id == participant_id:
+                return participant
+        raise ValueError(f"unknown topology participant: {participant_id}")
+
+
+def _topology_id(
+    *,
+    tp_size: int,
+    pp_size: int,
+    ep_size: int,
+    dp_size: int,
+    participants: tuple[TopologyParticipant, ...],
+) -> TopologyId:
+    content = {
+        "schema": "weight-parallel-topology",
+        "tp_size": tp_size,
+        "pp_size": pp_size,
+        "ep_size": ep_size,
+        "dp_size": dp_size,
+        "participants": [asdict(item) for item in participants],
+    }
+    encoded = json.dumps(content, sort_keys=True, separators=(",", ":")).encode()
+    return TopologyId(f"sha256:{hashlib.sha256(encoded).hexdigest()}")
+
+
+__all__ = ["ParallelTopology", "TopologyParticipant"]
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/types.py b/mooncake-reshard/python/mooncake/reshard/weight/types.py
new file mode 100644
index 0000000000..7cae945907
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/types.py
@@ -0,0 +1,389 @@
+"""Public model-weight tensor and fragment contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass
+from math import prod
+from typing import Literal, Optional, TypeVar, Union, cast
+
+from ..contracts import PlacementFragmentId, TensorId
+from ..contracts import RuntimeBindingFragment as _RuntimeBindingFragment
+
+# Preserve the existing weight.types import surface while keeping the canonical
+# runtime fragment definition resource-neutral in mooncake.reshard.contracts.
+RuntimeBindingFragment = _RuntimeBindingFragment
+
+_MAX_U64 = (1 << 64) - 1
+ParallelAxisKind = Literal["dp", "pp", "ep", "tp"]
+SplitAxisKind = Literal["ep", "tp"]
+_PARALLEL_AXIS_ORDER: dict[ParallelAxisKind, int] = {
+    "dp": 0,
+    "pp": 1,
+    "ep": 2,
+    "tp": 3,
+}
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True)
+class ParallelRank:
+    """Framework-provided owner coordinates used only for routing.
+
+    Logical sharding is defined by ``global_offset``, ``local_shape``, and
+    ``shard_dims``. This coordinate is not a replacement for the topology and
+    axis metadata used to synthesize a target placement.
+    """
+
+    dp: int = 0
+    tp: int = 0
+    pp: int = 0
+    ep: int = 0
+
+    def __post_init__(self) -> None:
+        for name in ("dp", "tp", "pp", "ep"):
+            _require_integer(getattr(self, name), f"parallel rank {name}", minimum=0)
+
+
+@dataclass(frozen=True)
+class SplitAxis:
+    """An axis whose ranks collectively partition one logical tensor."""
+
+    kind: SplitAxisKind
+    dim: int
+
+    def __post_init__(self) -> None:
+        _validate_parallel_axis_kind(self.kind)
+        if self.kind not in {"ep", "tp"}:
+            raise ValueError(f"{self.kind} cannot use split semantics")
+        _require_integer(self.dim, "split axis dim", minimum=0)
+        if self.kind == "ep" and self.dim != 0:
+            raise ValueError("EP must split the leading logical expert dimension")
+
+
+@dataclass(frozen=True)
+class ReplicatedAxis:
+    """An axis whose ranks each contain an independent complete tensor."""
+
+    kind: ParallelAxisKind
+
+    def __post_init__(self) -> None:
+        _validate_parallel_axis_kind(self.kind)
+
+
+@dataclass(frozen=True)
+class OwnershipAxis:
+    """An axis where only explicitly declared owner ranks contain the tensor."""
+
+    kind: ParallelAxisKind
+
+    def __post_init__(self) -> None:
+        _validate_parallel_axis_kind(self.kind)
+
+
+ParallelAxis = Union[SplitAxis, ReplicatedAxis, OwnershipAxis]
+
+
+@dataclass(frozen=True)
+class TensorDescriptor:
+    """Logical tensor identity, shape, dtype, and framework-supplied semantics."""
+
+    tensor_id: TensorId
+    global_shape: tuple[int, ...]
+    dtype: str
+    itemsize: int
+    shard_dims: tuple[int, ...]
+    layout_fingerprint: str
+    parallel_axes: tuple[ParallelAxis, ...]
+    layer_id: Optional[int] = None
+    expert_id: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        shape = _require_integer_tuple(self.global_shape, "global_shape", minimum=1)
+        if not shape:
+            raise ValueError("global_shape must not be empty")
+        object.__setattr__(self, "global_shape", shape)
+        _require_nonempty_string(self.tensor_id, "tensor_id")
+        _require_nonempty_string(self.dtype, "dtype")
+        _require_integer(self.itemsize, "itemsize", minimum=1)
+        shard_dims = _require_integer_tuple(self.shard_dims, "shard_dims", minimum=0)
+        if len(shard_dims) != len(set(shard_dims)):
+            raise ValueError("shard_dims must not contain duplicates")
+        if tuple(sorted(shard_dims)) != shard_dims:
+            raise ValueError("shard_dims must be sorted")
+        if any(dim >= len(shape) for dim in shard_dims):
+            raise ValueError("shard_dims contains an out-of-range dimension")
+        object.__setattr__(self, "shard_dims", shard_dims)
+        raw_axes = _require_sequence(
+            self.parallel_axes,
+            "TensorDescriptor parallel_axes",
+        )
+        if not all(
+            isinstance(axis, (SplitAxis, ReplicatedAxis, OwnershipAxis))
+            for axis in raw_axes
+        ):
+            raise ValueError(
+                "TensorDescriptor parallel_axes must contain explicit axis values"
+            )
+        parallel_axes: tuple[ParallelAxis, ...] = tuple(
+            cast(ParallelAxis, axis) for axis in raw_axes
+        )
+        parallel_axes = tuple(
+            sorted(parallel_axes, key=lambda axis: _PARALLEL_AXIS_ORDER[axis.kind])
+        )
+        axis_kinds = tuple(axis.kind for axis in parallel_axes)
+        if len(axis_kinds) != len(set(axis_kinds)):
+            raise ValueError("parallel_axes must not contain duplicate kinds")
+        split_dims = tuple(
+            axis.dim for axis in parallel_axes if isinstance(axis, SplitAxis)
+        )
+        if len(split_dims) != len(set(split_dims)):
+            raise ValueError("split axes must not share a dimension")
+        if any(dim >= len(shape) for dim in split_dims):
+            raise ValueError("split axis dimension is out of range")
+        if tuple(sorted(split_dims)) != shard_dims:
+            raise ValueError("parallel axis split dimensions conflict with shard_dims")
+        object.__setattr__(self, "parallel_axes", parallel_axes)
+        for name in ("layer_id", "expert_id"):
+            value = getattr(self, name)
+            if value is not None:
+                _require_integer(value, name, minimum=0)
+        if self.expert_id is not None and any(
+            axis.kind == "ep" and isinstance(axis, SplitAxis) for axis in parallel_axes
+        ):
+            raise ValueError(
+                "an individually allocated expert requires explicit EP ownership"
+            )
+        _require_nonempty_string(self.layout_fingerprint, "layout_fingerprint")
+
+
+def validate_fragment_geometry(
+    tensor: TensorDescriptor,
+    *,
+    fragment_id: str,
+    global_offset: tuple[int, ...],
+    local_shape: tuple[int, ...],
+    nbytes: int,
+) -> None:
+    """Validate shared local geometry without requiring complete tensor coverage."""
+
+    ndim = len(tensor.global_shape)
+    if len(global_offset) != ndim or len(local_shape) != ndim:
+        raise ValueError(f"fragment rank mismatch: {fragment_id}")
+    for offset, extent, total in zip(
+        global_offset,
+        local_shape,
+        tensor.global_shape,
+    ):
+        if offset + extent > total:
+            raise ValueError(f"fragment is out of bounds: {fragment_id}")
+
+    expected_nbytes = prod(local_shape) * tensor.itemsize
+    if nbytes != expected_nbytes:
+        raise ValueError(
+            f"fragment byte size mismatch: {fragment_id}: "
+            f"expected {expected_nbytes}, got {nbytes}"
+        )
+
+
+def canonical_strides_bytes(
+    shape: tuple[int, ...],
+    itemsize: int,
+) -> tuple[int, ...]:
+    strides: list[int] = []
+    running = itemsize
+    for extent in reversed(shape):
+        strides.append(running)
+        running *= extent
+    return tuple(reversed(strides))
+
+
+@dataclass(frozen=True, init=False)
+class PlacementFragment:
+    """An address-free logical tensor box assigned to one parallel rank."""
+
+    tensor_id: TensorId
+    global_offset: tuple[int, ...]
+    local_shape: tuple[int, ...]
+    nbytes: int
+    rank: ParallelRank
+    pipeline_stage_id: Optional[int]
+    aliases: tuple[TensorId, ...]
+    placement_fragment_id: PlacementFragmentId
+
+    def __init__(
+        self,
+        tensor_id: TensorId,
+        global_offset: tuple[int, ...],
+        local_shape: tuple[int, ...],
+        nbytes: int,
+        rank: ParallelRank,
+        pipeline_stage_id: Optional[int] = None,
+        aliases: tuple[TensorId, ...] = (),
+        placement_fragment_id: Optional[PlacementFragmentId] = None,
+    ) -> None:
+        normalized_offset = _require_integer_tuple(
+            global_offset,
+            "global_offset",
+            minimum=0,
+        )
+        normalized_shape = _require_integer_tuple(
+            local_shape,
+            "local_shape",
+            minimum=1,
+        )
+        _require_nonempty_string(tensor_id, "tensor_id")
+        _require_u64(nbytes, "nbytes", minimum=1)
+        if not isinstance(rank, ParallelRank):
+            raise ValueError("rank must be a ParallelRank")  # noqa: TRY004
+        if pipeline_stage_id is not None:
+            _require_integer(pipeline_stage_id, "pipeline_stage_id", minimum=0)
+        normalized_aliases = _normalize_aliases(aliases)
+        if normalized_aliases:
+            if len(normalized_aliases) < 2:
+                raise ValueError("alias group must contain at least two tensor IDs")
+            if tensor_id not in normalized_aliases:
+                raise ValueError("alias group must contain the fragment tensor_id")
+        if placement_fragment_id is not None:
+            _require_nonempty_string(
+                placement_fragment_id,
+                "placement_fragment_id",
+            )
+            resolved_fragment_id = placement_fragment_id
+        else:
+            resolved_fragment_id = _canonical_placement_fragment_id(
+                tensor_id=tensor_id,
+                global_offset=normalized_offset,
+                local_shape=normalized_shape,
+                nbytes=nbytes,
+                rank=rank,
+                pipeline_stage_id=pipeline_stage_id,
+                aliases=normalized_aliases,
+            )
+        object.__setattr__(self, "tensor_id", tensor_id)
+        object.__setattr__(self, "global_offset", normalized_offset)
+        object.__setattr__(self, "local_shape", normalized_shape)
+        object.__setattr__(self, "nbytes", nbytes)
+        object.__setattr__(self, "rank", rank)
+        object.__setattr__(self, "pipeline_stage_id", pipeline_stage_id)
+        object.__setattr__(self, "aliases", normalized_aliases)
+        object.__setattr__(self, "placement_fragment_id", resolved_fragment_id)
+
+    @property
+    def fragment_id(self) -> PlacementFragmentId:
+        """Expose the common fragment identifier used by future planners."""
+
+        return self.placement_fragment_id
+
+
+def _require_nonempty_string(value: object, name: str) -> str:
+    if type(value) is not str or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+def _require_integer(
+    value: object,
+    name: str,
+    *,
+    minimum: Optional[int] = None,
+) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{name} must be an integer")
+    if minimum is not None and value < minimum:
+        raise ValueError(f"{name} must be at least {minimum}")
+    return value
+
+
+def _require_u64(value: object, name: str, *, minimum: int = 0) -> int:
+    integer = _require_integer(value, name, minimum=minimum)
+    if integer > _MAX_U64:
+        raise ValueError(f"{name} must fit in an unsigned 64-bit integer")
+    return integer
+
+
+def require_sha256_digest(value: object, name: str) -> None:
+    digest = _require_nonempty_string(value, name)
+    if len(digest) != 64 or any(
+        character not in "0123456789abcdef" for character in digest
+    ):
+        raise ValueError(f"{name} must be a lowercase SHA-256 digest")
+
+
+def _require_integer_tuple(
+    value: object,
+    name: str,
+    *,
+    minimum: int,
+) -> tuple[int, ...]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{name} must contain integers")  # noqa: TRY004
+    items = cast(Sequence[object], value)
+    return tuple(_require_integer(item, name, minimum=minimum) for item in items)
+
+
+def _require_sequence(value: object, name: str) -> Sequence[object]:
+    if isinstance(value, (str, bytes, bytearray)) or not isinstance(value, Sequence):
+        raise ValueError(f"{name} must be a sequence")  # noqa: TRY004
+    return cast(Sequence[object], value)
+
+
+def require_manifest_items(
+    value: object,
+    name: str,
+    item_type: type[_T],
+) -> tuple[_T, ...]:
+    items = tuple(_require_sequence(value, name))
+    if not all(isinstance(item, item_type) for item in items):
+        raise ValueError(f"{name} must contain {item_type.__name__}")
+    return tuple(cast(_T, item) for item in items)
+
+
+def _normalize_aliases(value: object) -> tuple[TensorId, ...]:
+    aliases = tuple(_require_sequence(value, "aliases"))
+    if any(type(alias) is not str or not alias for alias in aliases):
+        raise ValueError("aliases must contain non-empty strings")
+    normalized_aliases = tuple(cast(str, alias) for alias in aliases)
+    if len(normalized_aliases) != len(set(normalized_aliases)):
+        raise ValueError("aliases must not contain duplicates")
+    return tuple(TensorId(alias) for alias in sorted(normalized_aliases))
+
+
+def _canonical_placement_fragment_id(
+    *,
+    tensor_id: TensorId,
+    global_offset: tuple[int, ...],
+    local_shape: tuple[int, ...],
+    nbytes: int,
+    rank: ParallelRank,
+    pipeline_stage_id: Optional[int],
+    aliases: tuple[TensorId, ...],
+) -> PlacementFragmentId:
+    content = {
+        "schema": "weight-placement-fragment",
+        "tensor_id": tensor_id,
+        "global_offset": global_offset,
+        "local_shape": local_shape,
+        "nbytes": nbytes,
+        "rank": asdict(rank),
+        "aliases": aliases,
+    }
+    if pipeline_stage_id is not None:
+        content["pipeline_stage_id"] = pipeline_stage_id
+    encoded = json.dumps(content, sort_keys=True, separators=(",", ":")).encode()
+    return PlacementFragmentId(f"sha256:{hashlib.sha256(encoded).hexdigest()}")
+
+
+def _validate_parallel_axis_kind(kind: ParallelAxisKind) -> None:
+    _require_nonempty_string(kind, "parallel axis kind")
+    if kind not in _PARALLEL_AXIS_ORDER:
+        raise ValueError(f"unsupported parallel axis kind: {kind}")
+
+
+# Retain internal imports used by this first-stage contract package. These
+# aliases do not widen the public wire or runtime contract.
+_canonical_strides_bytes = canonical_strides_bytes
+_require_manifest_items = require_manifest_items
+_require_sha256_digest = require_sha256_digest
diff --git a/mooncake-reshard/python/mooncake/reshard/weight/validation.py b/mooncake-reshard/python/mooncake/reshard/weight/validation.py
new file mode 100644
index 0000000000..0077817e70
--- /dev/null
+++ b/mooncake-reshard/python/mooncake/reshard/weight/validation.py
@@ -0,0 +1,503 @@
+"""Cross-fragment logical and physical validation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from itertools import product as cartesian_product
+
+from ..contracts import RuntimeBindingFragment, RuntimeInstanceId, TensorId
+from ..geometry import boxes_exactly_cover, boxes_overlap
+from .topology import ParallelTopology
+from .types import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    SplitAxis,
+    TensorDescriptor,
+    validate_fragment_geometry,
+)
+
+
+def _validate_fragments(
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[PlacementFragment],
+    *,
+    require_complete_alias_groups: bool = False,
+) -> None:
+    tensor_by_id: dict[TensorId, TensorDescriptor] = {}
+    for tensor in tensors:
+        if tensor.tensor_id in tensor_by_id:
+            raise ValueError(f"duplicate tensor_id: {tensor.tensor_id}")
+        tensor_by_id[tensor.tensor_id] = tensor
+
+    fragment_ids: set[str] = set()
+    logical_fragments: set[
+        tuple[TensorId, ParallelRank, tuple[int, ...], tuple[int, ...]]
+    ] = set()
+    for fragment in fragments:
+        if fragment.fragment_id in fragment_ids:
+            raise ValueError(f"duplicate fragment_id: {fragment.fragment_id}")
+        fragment_ids.add(fragment.fragment_id)
+        logical_fragment = (
+            fragment.tensor_id,
+            fragment.rank,
+            fragment.global_offset,
+            fragment.local_shape,
+        )
+        if logical_fragment in logical_fragments:
+            raise ValueError(
+                "duplicate logical fragment for tensor and parallel rank: "
+                f"{fragment.fragment_id}"
+            )
+        logical_fragments.add(logical_fragment)
+        tensor = tensor_by_id.get(fragment.tensor_id)
+        if tensor is None:
+            raise ValueError(f"unknown tensor_id: {fragment.tensor_id}")
+        _validate_fragment_geometry(tensor, fragment)
+    if require_complete_alias_groups:
+        _validate_complete_alias_groups(tensor_by_id, fragments)
+    _validate_logical_fragment_overlaps(fragments)
+
+
+def _validate_complete_alias_groups(
+    tensors_by_id: Mapping[TensorId, TensorDescriptor],
+    fragments: Sequence[PlacementFragment],
+) -> None:
+    """Validate alias authorization only after all placement parts are assembled.
+
+    A placement part can legitimately name an alias member owned by another
+    participant. The complete placement is the first layer with the full tensor
+    set, so it alone can prove that every declared member exists and declares
+    the same group.
+    """
+
+    fragments_by_tensor: dict[TensorId, list[PlacementFragment]] = {}
+    alias_groups: set[tuple[TensorId, ...]] = set()
+    for fragment in fragments:
+        fragments_by_tensor.setdefault(fragment.tensor_id, []).append(fragment)
+        if fragment.aliases:
+            alias_groups.add(fragment.aliases)
+
+    known_tensor_ids = set(tensors_by_id)
+    for aliases in alias_groups:
+        unknown_tensor_ids = sorted(set(aliases) - known_tensor_ids)
+        if unknown_tensor_ids:
+            raise ValueError(
+                f"alias group references unknown tensor: {unknown_tensor_ids[0]}"
+            )
+        for tensor_id in aliases:
+            member_groups = {
+                fragment.aliases for fragment in fragments_by_tensor[tensor_id]
+            }
+            if member_groups != {aliases}:
+                raise ValueError(
+                    f"alias group is not declared consistently for tensor: {tensor_id}"
+                )
+
+
+def _validate_complete_weight_placement(
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[PlacementFragment],
+    *,
+    topology: ParallelTopology,
+) -> None:
+    """Validate explicit split, replication, and ownership semantics."""
+
+    if not tensors:
+        raise ValueError("global weight placement must contain tensors")
+    if not fragments:
+        raise ValueError("global weight placement must contain fragments")
+
+    by_tensor: dict[TensorId, list[PlacementFragment]] = {}
+    for fragment in fragments:
+        by_tensor.setdefault(fragment.tensor_id, []).append(fragment)
+
+    for tensor in tensors:
+        tensor_fragments = by_tensor.get(tensor.tensor_id, [])
+        if not tensor_fragments:
+            raise ValueError(
+                f"global placement tensor is not fully covered: {tensor.tensor_id}"
+            )
+        _validate_tensor_axis_covers(tensor, tensor_fragments, topology=topology)
+
+
+def _split_axis_kinds(tensor: TensorDescriptor) -> tuple[str, ...]:
+    return tuple(
+        axis.kind for axis in tensor.parallel_axes if isinstance(axis, SplitAxis)
+    )
+
+
+def _replicated_axis_kinds(tensor: TensorDescriptor) -> tuple[str, ...]:
+    return tuple(
+        axis.kind for axis in tensor.parallel_axes if isinstance(axis, ReplicatedAxis)
+    )
+
+
+def _ownership_axis_kinds(tensor: TensorDescriptor) -> tuple[str, ...]:
+    return tuple(
+        axis.kind for axis in tensor.parallel_axes if isinstance(axis, OwnershipAxis)
+    )
+
+
+def _axis_rank(rank: ParallelRank, kinds: Sequence[str]) -> tuple[tuple[str, int], ...]:
+    return tuple((kind, getattr(rank, kind)) for kind in kinds)
+
+
+def _rank_matches(rank: ParallelRank, coordinates: tuple[tuple[str, int], ...]) -> bool:
+    return all(getattr(rank, kind) == value for kind, value in coordinates)
+
+
+def _validate_tensor_axis_covers(
+    tensor: TensorDescriptor,
+    fragments: Sequence[PlacementFragment],
+    *,
+    topology: ParallelTopology,
+) -> None:
+    _validate_undeclared_axis_dependencies(tensor, fragments, topology=topology)
+
+    ownership_kinds = _ownership_axis_kinds(tensor)
+    replicated_kinds = _replicated_axis_kinds(tensor)
+    declared_owners = {
+        _axis_rank(fragment.rank, ownership_kinds) for fragment in fragments
+    }
+
+    for owner in sorted(declared_owners):
+        owner_fragments = [
+            fragment
+            for fragment in fragments
+            if _axis_rank(fragment.rank, ownership_kinds) == owner
+        ]
+        expected_replicas = {
+            _axis_rank(participant.rank, replicated_kinds)
+            for participant in topology.participants
+            if _rank_matches(participant.rank, owner)
+        }
+        actual_replicas = {
+            _axis_rank(fragment.rank, replicated_kinds) for fragment in owner_fragments
+        }
+        if actual_replicas != expected_replicas:
+            raise ValueError(
+                "global placement tensor is not fully covered: missing or "
+                "unexpected replicated-axis participant for "
+                f"{tensor.tensor_id}"
+            )
+
+        for replica in sorted(expected_replicas):
+            cover = [
+                fragment
+                for fragment in owner_fragments
+                if _axis_rank(fragment.rank, replicated_kinds) == replica
+            ]
+            if not _fragments_exactly_cover_tensor(tensor, cover):
+                raise ValueError(
+                    f"global placement tensor is not fully covered: {tensor.tensor_id}"
+                )
+            _validate_split_axis_participation(
+                tensor,
+                cover,
+                topology=topology,
+                fixed_coordinates=owner + replica,
+            )
+            _validate_split_axis_geometry(tensor, cover)
+
+
+def _validate_undeclared_axis_dependencies(
+    tensor: TensorDescriptor,
+    fragments: Sequence[PlacementFragment],
+    *,
+    topology: ParallelTopology,
+) -> None:
+    """Reject implicit ownership while allowing explicitly coupled TP/EP ranks."""
+
+    declared_axis_kinds = tuple(axis.kind for axis in tensor.parallel_axes)
+    varying_declared_axis_kinds = tuple(
+        kind
+        for kind in declared_axis_kinds
+        if len({getattr(fragment.rank, kind) for fragment in fragments}) > 1
+    )
+    for kind in ("dp", "pp", "ep", "tp"):
+        if kind in declared_axis_kinds or getattr(topology, f"{kind}_size") == 1:
+            continue
+        coordinates = {getattr(fragment.rank, kind) for fragment in fragments}
+        if kind in {"dp", "pp"} or len(coordinates) <= 1:
+            raise ValueError(
+                "global placement tensor requires explicit parallel semantics "
+                f"for active undeclared {kind} axis: {tensor.tensor_id}"
+            )
+        if not varying_declared_axis_kinds:
+            raise ValueError(
+                "global placement tensor varies across undeclared "
+                f"{kind} axis: {tensor.tensor_id}"
+            )
+
+        coordinate_by_declared_rank: dict[tuple[tuple[str, int], ...], int] = {}
+        for fragment in fragments:
+            declared_rank = _axis_rank(fragment.rank, varying_declared_axis_kinds)
+            coordinate = getattr(fragment.rank, kind)
+            previous = coordinate_by_declared_rank.setdefault(
+                declared_rank,
+                coordinate,
+            )
+            if previous != coordinate:
+                raise ValueError(
+                    "global placement tensor varies independently across undeclared "
+                    f"{kind} axis: {tensor.tensor_id}"
+                )
+
+
+def _validate_split_axis_geometry(
+    tensor: TensorDescriptor,
+    fragments: Sequence[PlacementFragment],
+) -> None:
+    """Validate that every declared split rank owns its logical dimension."""
+
+    split_axes = tuple(
+        axis for axis in tensor.parallel_axes if isinstance(axis, SplitAxis)
+    )
+    if not split_axes:
+        return
+    coordinate_values = tuple(
+        tuple(sorted({getattr(fragment.rank, axis.kind) for fragment in fragments}))
+        for axis in split_axes
+    )
+    observed_coordinates = {
+        tuple(getattr(fragment.rank, axis.kind) for axis in split_axes)
+        for fragment in fragments
+    }
+    expected_coordinates = set(cartesian_product(*coordinate_values))
+    if observed_coordinates != expected_coordinates:
+        raise ValueError(
+            "non-Cartesian split-axis participant mapping cannot prove "
+            f"rank-to-dimension ownership: {tensor.tensor_id}"
+        )
+
+    for axis in split_axes:
+        intervals_by_rank: dict[int, list[tuple[int, int]]] = {}
+        for fragment in fragments:
+            begin = fragment.global_offset[axis.dim]
+            end = begin + fragment.local_shape[axis.dim]
+            intervals_by_rank.setdefault(getattr(fragment.rank, axis.kind), []).append(
+                (begin, end)
+            )
+
+        owned_intervals = sorted(
+            (begin, end, rank)
+            for rank, intervals in intervals_by_rank.items()
+            for begin, end in _merge_intervals(intervals)
+        )
+        cursor = 0
+        for begin, end, _ in owned_intervals:
+            if begin != cursor:
+                raise ValueError(
+                    "split-axis rank geometry conflicts with declared dimension: "
+                    f"{tensor.tensor_id}: {axis.kind} -> dim {axis.dim}"
+                )
+            cursor = end
+        if cursor != tensor.global_shape[axis.dim]:
+            raise ValueError(
+                "split-axis rank geometry conflicts with declared dimension: "
+                f"{tensor.tensor_id}: {axis.kind} -> dim {axis.dim}"
+            )
+
+
+def _merge_intervals(
+    intervals: Sequence[tuple[int, int]],
+) -> tuple[tuple[int, int], ...]:
+    merged: list[list[int]] = []
+    for begin, end in sorted(set(intervals)):
+        if not merged or begin > merged[-1][1]:
+            merged.append([begin, end])
+        else:
+            merged[-1][1] = max(merged[-1][1], end)
+    return tuple((begin, end) for begin, end in merged)
+
+
+def _parallel_split_rank(
+    tensor: TensorDescriptor,
+    rank: ParallelRank,
+) -> tuple[tuple[str, int], ...]:
+    return _axis_rank(rank, _split_axis_kinds(tensor))
+
+
+def _validate_split_axis_participation(
+    tensor: TensorDescriptor,
+    fragments: Sequence[PlacementFragment],
+    *,
+    topology: ParallelTopology,
+    fixed_coordinates: tuple[tuple[str, int], ...],
+) -> None:
+    split_axis_kinds = _split_axis_kinds(tensor)
+    if not split_axis_kinds:
+        return
+
+    expected = {
+        _parallel_split_rank(tensor, participant.rank)
+        for participant in topology.participants
+        if _rank_matches(participant.rank, fixed_coordinates)
+    }
+    actual = {_parallel_split_rank(tensor, fragment.rank) for fragment in fragments}
+    complete_axis_ranges = all(
+        {dict(split_rank)[kind] for split_rank in expected}
+        == set(range(getattr(topology, f"{kind}_size")))
+        for kind in split_axis_kinds
+    )
+    if not complete_axis_ranges or actual != expected:
+        raise ValueError(
+            "global placement tensor is not fully covered: missing or unexpected "
+            f"split-axis participant for {tensor.tensor_id}"
+        )
+
+
+def _fragments_exactly_cover_tensor(
+    tensor: TensorDescriptor,
+    fragments: Sequence[PlacementFragment],
+) -> bool:
+    boxes = tuple(
+        (fragment.global_offset, fragment.local_shape) for fragment in fragments
+    )
+    return boxes_exactly_cover(
+        (0,) * len(tensor.global_shape), tensor.global_shape, boxes
+    )
+
+
+def _validate_logical_fragment_overlaps(
+    fragments: Sequence[PlacementFragment],
+) -> None:
+    by_tensor_and_rank: dict[tuple[str, ParallelRank], list[PlacementFragment]] = {}
+    for fragment in fragments:
+        by_tensor_and_rank.setdefault((fragment.tensor_id, fragment.rank), []).append(
+            fragment
+        )
+
+    for owner_fragments in by_tensor_and_rank.values():
+        if len(owner_fragments) < 2:
+            continue
+        boxes = tuple(
+            (fragment.global_offset, fragment.local_shape)
+            for fragment in owner_fragments
+        )
+        if boxes_overlap(boxes):
+            raise ValueError(
+                "logical fragment boxes overlap for tensor and parallel rank"
+            )
+
+
+def _validate_fragment_geometry(
+    tensor: TensorDescriptor,
+    fragment: PlacementFragment,
+) -> None:
+    validate_fragment_geometry(
+        tensor,
+        fragment_id=fragment.fragment_id,
+        global_offset=fragment.global_offset,
+        local_shape=fragment.local_shape,
+        nbytes=fragment.nbytes,
+    )
+
+
+def _runtime_alias_descriptor_key(tensor: TensorDescriptor) -> tuple[object, ...]:
+    return (
+        tensor.global_shape,
+        tensor.dtype,
+        tensor.itemsize,
+        tensor.shard_dims,
+        tensor.parallel_axes,
+        tensor.layer_id,
+        tensor.expert_id,
+        tensor.layout_fingerprint,
+    )
+
+
+def _is_exact_declared_runtime_alias(
+    left_placement: PlacementFragment,
+    left_binding: RuntimeBindingFragment,
+    right_placement: PlacementFragment,
+    right_binding: RuntimeBindingFragment,
+    tensors: Mapping[TensorId, TensorDescriptor],
+) -> bool:
+    return (
+        left_binding.address == right_binding.address
+        and left_binding.nbytes == right_binding.nbytes
+        and len(left_placement.aliases) >= 2
+        and left_placement.aliases == right_placement.aliases
+        and left_placement.tensor_id in left_placement.aliases
+        and right_placement.tensor_id in left_placement.aliases
+        and left_placement.global_offset == right_placement.global_offset
+        and left_placement.local_shape == right_placement.local_shape
+        and _runtime_alias_descriptor_key(tensors[left_placement.tensor_id])
+        == _runtime_alias_descriptor_key(tensors[right_placement.tensor_id])
+    )
+
+
+def _validate_runtime_binding_address_ranges(
+    *,
+    instance_id: RuntimeInstanceId,
+    tensors: Sequence[TensorDescriptor],
+    placements: Sequence[PlacementFragment],
+    bindings: Sequence[RuntimeBindingFragment],
+) -> None:
+    tensor_by_id = {tensor.tensor_id: tensor for tensor in tensors}
+    placement_by_id = {
+        fragment.placement_fragment_id: fragment for fragment in placements
+    }
+    by_address_space: dict[
+        tuple[str, str, str],
+        list[tuple[PlacementFragment, RuntimeBindingFragment]],
+    ] = {}
+    for binding in bindings:
+        placement = placement_by_id[binding.placement_fragment_id]
+        address_space = (instance_id, binding.worker_id, binding.device)
+        by_address_space.setdefault(address_space, []).append((placement, binding))
+
+    for address_space, fragments in by_address_space.items():
+        ordered = sorted(fragments, key=lambda item: item[1].address)
+        active: list[tuple[PlacementFragment, RuntimeBindingFragment]] = []
+        for current_placement, current_binding in ordered:
+            active = [
+                (previous_placement, previous_binding)
+                for previous_placement, previous_binding in active
+                if previous_binding.address + previous_binding.nbytes
+                > current_binding.address
+            ]
+            for previous_placement, previous_binding in active:
+                if _is_exact_declared_runtime_alias(
+                    previous_placement,
+                    previous_binding,
+                    current_placement,
+                    current_binding,
+                    tensor_by_id,
+                ):
+                    continue
+                raise ValueError(
+                    "runtime binding address ranges overlap: "
+                    f"{previous_binding.fragment_id} and "
+                    f"{current_binding.fragment_id} "
+                    f"in {address_space}"
+                )
+            active.append((current_placement, current_binding))
+
+        allocation_order = sorted(
+            (binding for _, binding in fragments),
+            key=lambda binding: binding.storage_address,
+        )
+        active_allocations: list[RuntimeBindingFragment] = []
+        for current in allocation_order:
+            active_allocations = [
+                previous
+                for previous in active_allocations
+                if previous.storage_address + previous.storage_nbytes
+                > current.storage_address
+            ]
+            for previous in active_allocations:
+                if (
+                    previous.storage_address == current.storage_address
+                    and previous.storage_nbytes == current.storage_nbytes
+                ):
+                    continue
+                raise ValueError(
+                    "runtime binding storage allocation ranges overlap: "
+                    f"{previous.fragment_id} and {current.fragment_id} "
+                    f"in {address_space}"
+                )
+            active_allocations.append(current)
diff --git a/mooncake-reshard/tests/kv_cache/test_kv_cache_reshard.py b/mooncake-reshard/tests/kv_cache/test_kv_cache_reshard.py
new file mode 100644
index 0000000000..c83be26f22
--- /dev/null
+++ b/mooncake-reshard/tests/kv_cache/test_kv_cache_reshard.py
@@ -0,0 +1,860 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import replace
+from math import prod
+
+import pytest
+from mooncake.reshard.contracts import (
+    ParticipantId,
+    PlacementSetId,
+    ResourceId,
+    RevisionId,
+    RuntimeBindingFragment,
+    RuntimeFragmentId,
+    RuntimeInstanceId,
+)
+from mooncake.reshard.kv_cache import (
+    KVCacheBufferBinding,
+    KVCacheComponent,
+    KVCacheDescriptor,
+    KVCacheLogicalTransferPlan,
+    KVCachePlacementManifest,
+    KVCachePlacementPart,
+    KVCacheRank,
+    KVCacheRuntimeBindingManifest,
+    KVCacheRuntimeBuffer,
+    KVCacheSnapshotDescriptor,
+    KVCacheTopology,
+    KVCacheTopologyParticipant,
+    KVCacheTransferEdge,
+    assemble_kv_cache_placement,
+    kv_cache_logical_plan_from_json,
+    kv_cache_logical_plan_to_json,
+    kv_cache_part_from_json,
+    kv_cache_part_to_json,
+    kv_cache_placement_from_json,
+    kv_cache_placement_to_json,
+    kv_cache_runtime_binding_from_json,
+    kv_cache_runtime_binding_to_json,
+    kv_cache_snapshot_from_json,
+    kv_cache_snapshot_to_json,
+    placement_fragment_id,
+    plan_kv_cache_transfer_to_local_target,
+    prepare_kv_cache_transfer,
+    validate_runtime_binding,
+    validate_runtime_bindings,
+)
+
+
+_MAX_U64 = (1 << 64) - 1
+
+
+def _placement(
+    prefix: str,
+    layer_partitions: tuple[tuple[int, ...], ...],
+    tp_size: int,
+    *,
+    total_kv_heads: int = 4,
+    page_size: int = 16,
+    dp_size: int = 1,
+    resource_id: str = "kv:qwen-test",
+    revision: str = "qwen-test-revision",
+) -> KVCachePlacementManifest:
+    descriptor = KVCacheDescriptor(
+        global_layer_ids=tuple(
+            sorted(layer for partition in layer_partitions for layer in partition)
+        ),
+        dtype="float16",
+        itemsize=2,
+        page_size=page_size,
+        total_kv_heads=total_kv_heads,
+        key_head_dim=8,
+        value_head_dim=8,
+    )
+    participants = tuple(
+        KVCacheTopologyParticipant(
+            participant_id=ParticipantId(
+                f"{prefix}-d{dp_rank}-p{pp_rank}-t{tp_rank}"
+                if dp_size > 1
+                else f"{prefix}-p{pp_rank}-t{tp_rank}"
+            ),
+            rank=KVCacheRank(dp=dp_rank, pp=pp_rank, tp=tp_rank),
+        )
+        for dp_rank in range(dp_size)
+        for pp_rank in range(len(layer_partitions))
+        for tp_rank in range(tp_size)
+    )
+    topology = KVCacheTopology(
+        dp_size=dp_size,
+        pp_size=len(layer_partitions),
+        tp_size=tp_size,
+        participants=participants,
+    )
+    parts = []
+    for participant in topology.participants:
+        pp_rank = participant.rank.pp
+        tp_rank = participant.rank.tp
+        if total_kv_heads >= tp_size and total_kv_heads % tp_size == 0:
+            head_count = total_kv_heads // tp_size
+            head_start = tp_rank * head_count
+            replica_count = 1
+            replica_ordinal = 0
+        elif tp_size > total_kv_heads and tp_size % total_kv_heads == 0:
+            replica_count = tp_size // total_kv_heads
+            head_count = 1
+            head_start = tp_rank // replica_count
+            replica_ordinal = tp_rank % replica_count
+        else:
+            raise ValueError("test topology has an unsupported TP/head ratio")
+        parts.append(
+            KVCachePlacementPart(
+                resource_id=ResourceId(resource_id),
+                revision=RevisionId(revision),
+                placement_set_id=PlacementSetId(f"{prefix}-placement"),
+                topology_id=topology.topology_id,
+                participant_id=participant.participant_id,
+                rank=participant.rank,
+                descriptor=descriptor,
+                layer_ids=layer_partitions[pp_rank],
+                head_start=head_start,
+                head_count=head_count,
+                replica_ordinal=replica_ordinal,
+                replica_count=replica_count,
+            )
+        )
+    return KVCachePlacementManifest(
+        resource_id=ResourceId(resource_id),
+        revision=RevisionId(revision),
+        placement_set_id=PlacementSetId(f"{prefix}-placement"),
+        topology=topology,
+        descriptor=descriptor,
+        parts=tuple(parts),
+    )
+
+
+def _fingerprint(value: str) -> str:
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def _snapshot(
+    *,
+    resource_id: str = "kv:qwen-test",
+    token_start: int = 0,
+    token_count: int = 8,
+) -> KVCacheSnapshotDescriptor:
+    return KVCacheSnapshotDescriptor(
+        namespace="tenant-a",
+        resource_id=ResourceId(resource_id),
+        model_id="Qwen/Qwen2.5-1.5B-Instruct",
+        model_revision="main",
+        token_start=token_start,
+        token_count=token_count,
+        token_fingerprint=_fingerprint("token-ids"),
+        semantic_fingerprint=_fingerprint("model-and-adapter"),
+    )
+
+
+def _binding(
+    placement: KVCachePlacementManifest,
+    participant_id: str,
+    *,
+    base_address: int,
+    snapshot: KVCacheSnapshotDescriptor | None = None,
+    capacity_tokens: int = 256,
+) -> KVCacheRuntimeBindingManifest:
+    typed_participant_id = ParticipantId(participant_id)
+    part = placement.part(typed_participant_id)
+    buffers = []
+    for buffer_index, (layer_id, component) in enumerate(
+        (layer_id, component)
+        for layer_id in part.layer_ids
+        for component in KVCacheComponent
+    ):
+        head_dim = (
+            placement.descriptor.key_head_dim
+            if component is KVCacheComponent.KEY
+            else placement.descriptor.value_head_dim
+        )
+        shape = (capacity_tokens, part.head_count, head_dim)
+        nbytes = prod(shape) * placement.descriptor.itemsize
+        address = base_address + buffer_index * 1_000_000
+        fragment = KVCacheRuntimeBuffer(
+            placement_fragment_id=placement_fragment_id(
+                typed_participant_id,
+                layer_id,
+                component,
+                head_start=part.head_start,
+                head_count=part.head_count,
+            ),
+            fragment_id=RuntimeFragmentId(
+                f"runtime:{participant_id}:{layer_id}:{component.value}"
+            ),
+            address=address,
+            nbytes=nbytes,
+            worker_id=participant_id,
+            endpoint=f"{participant_id}:12345",
+            device="cuda:0",
+            itemsize=placement.descriptor.itemsize,
+            local_shape=shape,
+            strides_bytes=(
+                part.head_count * head_dim * placement.descriptor.itemsize,
+                head_dim * placement.descriptor.itemsize,
+                placement.descriptor.itemsize,
+            ),
+            storage_address=address,
+            storage_nbytes=nbytes,
+            storage_offset_bytes=0,
+        )
+        buffers.append(KVCacheBufferBinding(layer_id, component, fragment))
+    return KVCacheRuntimeBindingManifest(
+        resource_id=placement.resource_id,
+        placement_id=placement.placement_id,
+        placement_digest=placement.digest,
+        instance_id=RuntimeInstanceId(f"instance:{participant_id}"),
+        snapshot_id=snapshot.snapshot_id if snapshot is not None else None,
+        snapshot_digest=snapshot.digest if snapshot is not None else None,
+        revision=placement.revision,
+        participant_id=typed_participant_id,
+        buffers=tuple(buffers),
+    )
+
+
+def _binding_with_address_space(
+    binding, *, instance="shared", worker="worker", device="cuda:0"
+):
+    return replace(
+        binding,
+        instance_id=RuntimeInstanceId(instance),
+        buffers=tuple(
+            replace(
+                item, fragment=replace(item.fragment, worker_id=worker, device=device)
+            )
+            for item in binding.buffers
+        ),
+    )
+
+
+def _buffer_with_storage(item, address, storage_address, storage_nbytes):
+    return replace(
+        item,
+        fragment=replace(
+            item.fragment,
+            address=address,
+            storage_address=storage_address,
+            storage_nbytes=storage_nbytes,
+            storage_offset_bytes=address - storage_address,
+        ),
+    )
+
+
+def _plan(
+    source: KVCachePlacementManifest,
+    target: KVCachePlacementManifest,
+    participant_id: str,
+    *,
+    source_dp_rank: int | None = None,
+    snapshot: KVCacheSnapshotDescriptor | None = None,
+) -> KVCacheLogicalTransferPlan:
+    return plan_kv_cache_transfer_to_local_target(
+        source,
+        target,
+        ParticipantId(participant_id),
+        source_dp_rank=source_dp_rank,
+        snapshot=snapshot,
+    )
+
+
+def test_placement_part_and_binding_round_trip_are_canonical() -> None:
+    placement = _placement("source", ((0, 1), (2, 3)), 2)
+    binding = _binding(placement, "source-p0-t0", base_address=1_000_000_000)
+    restored = kv_cache_placement_from_json(kv_cache_placement_to_json(placement))
+    restored_part = kv_cache_part_from_json(kv_cache_part_to_json(placement.parts[0]))
+    restored_binding = kv_cache_runtime_binding_from_json(
+        kv_cache_runtime_binding_to_json(binding)
+    )
+
+    assert KVCacheRuntimeBuffer is RuntimeBindingFragment
+    assert restored == placement
+    assert restored_part == placement.parts[0]
+    assert restored_binding == binding
+    part_payload = json.loads(kv_cache_part_to_json(placement.parts[0]))
+    assert "placement_id" not in part_payload
+    assert "instance_id" not in part_payload
+    assert "address" not in json.dumps(part_payload)
+
+
+@pytest.mark.parametrize(
+    "heads,dim,itemsize,accepted",
+    [
+        (1, 1 << 63, 2, False),
+        (2, 1 << 62, 2, False),
+        (_MAX_U64, 1, 1, True),
+        (1, _MAX_U64, 1, True),
+        (1, (1 << 63) - 1, 2, True),
+    ],
+)
+def test_transfer_edge_byte_size_boundary(heads, dim, itemsize, accepted):
+    args = dict(
+        source_participant_id="s",
+        target_participant_id="t",
+        global_layer_id=0,
+        component=KVCacheComponent.KEY,
+        global_head_start=0,
+        head_count=heads,
+        source_head_offset=0,
+        target_head_offset=0,
+        head_dim=dim,
+        itemsize=itemsize,
+    )
+    if accepted:
+        assert KVCacheTransferEdge(**args).inner_bytes == heads * dim * itemsize
+    else:
+        with pytest.raises(ValueError, match="inner_bytes"):
+            KVCacheTransferEdge(**args)
+
+
+@pytest.mark.parametrize("component", ["key_head_dim", "value_head_dim"])
+def test_descriptor_rejects_overflowing_head_bytes(component):
+    descriptor = _placement("source", ((0,),), 1).descriptor
+    with pytest.raises(ValueError, match="byte size"):
+        replace(descriptor, **{component: 1 << 63})
+
+
+def test_descriptor_keeps_distributed_global_size_separate_from_local_size():
+    descriptor = KVCacheDescriptor(
+        global_layer_ids=(0,),
+        dtype="uint8",
+        itemsize=1,
+        page_size=1,
+        total_kv_heads=2,
+        key_head_dim=_MAX_U64,
+        value_head_dim=1,
+    )
+    assert descriptor.total_kv_heads * descriptor.key_head_dim > _MAX_U64
+
+
+@pytest.mark.parametrize(
+    ("source_tp", "target_tp", "target_rank", "expected_intervals"),
+    [
+        (1, 2, 1, ((2, 2),)),
+        (2, 1, 0, ((0, 2), (2, 2))),
+        (1, 4, 3, ((3, 1),)),
+        (4, 1, 0, ((0, 1), (1, 1), (2, 1), (3, 1))),
+    ],
+)
+def test_tp_scatter_and_gather(
+    source_tp: int,
+    target_tp: int,
+    target_rank: int,
+    expected_intervals: tuple[tuple[int, int], ...],
+) -> None:
+    source = _placement("source", ((0,),), source_tp)
+    target = _placement("target", ((0,),), target_tp)
+    plan = _plan(source, target, f"target-p0-t{target_rank}")
+
+    key_intervals = tuple(
+        (edge.global_head_start, edge.head_count)
+        for edge in plan.edges
+        if edge.component is KVCacheComponent.KEY
+    )
+    assert key_intervals == expected_intervals
+
+
+def test_huge_head_count_plans_by_intervals():
+    source = _placement("source", ((0,),), 1, total_kv_heads=1 << 40)
+    target = _placement("target", ((0,),), 2, total_kv_heads=1 << 40)
+    plan = plan_kv_cache_transfer_to_local_target(
+        source, target, target.parts[0].participant_id
+    )
+    assert len(plan.edges) == 2
+
+
+def test_gqa_replica_ordinal_selects_one_source_writer() -> None:
+    source = _placement("source", ((0,),), 4, total_kv_heads=2)
+    target = _placement("target", ((0,),), 4, total_kv_heads=2)
+    plan = _plan(source, target, "target-p0-t3")
+
+    assert plan.source_participant_ids == (ParticipantId("source-p0-t3"),)
+    assert {edge.global_head_start for edge in plan.edges} == {1}
+
+
+def test_prepare_attests_both_complete_global_placements() -> None:
+    source = _placement("source", ((0,),), 2)
+    target = _placement("target", ((0,),), 1)
+    full_plan = _plan(source, target, "target-p0-t0")
+    source_id = full_plan.source_participant_ids[0]
+    plan = full_plan.for_source(source_id)
+    source_binding = _binding(source, source_id, base_address=1_000_000_000)
+    target_binding = _binding(target, "target-p0-t0", base_address=2_000_000_000)
+
+    prepared = prepare_kv_cache_transfer(plan, source_binding, target_binding)
+
+    assert prepared.source_placement_id == source.placement_id
+    assert prepared.target_placement_id == target.placement_id
+    assert prepared.source_placement_digest == source.digest
+    assert prepared.target_placement_digest == target.digest
+
+    stale = replace(target_binding, placement_id=source.placement_id)
+    with pytest.raises(ValueError, match="placement_id"):
+        prepare_kv_cache_transfer(plan, source_binding, stale)
+
+
+def test_arbitrary_pp_intersections_choose_exact_participants() -> None:
+    source = _placement("source", (tuple(range(14)), tuple(range(14, 28))), 1)
+    target = _placement(
+        "target", (tuple(range(10)), tuple(range(10, 19)), tuple(range(19, 28))), 1
+    )
+    plan = _plan(source, target, "target-p1-t0")
+
+    assert plan.source_participant_ids == (
+        ParticipantId("source-p0-t0"),
+        ParticipantId("source-p1-t0"),
+    )
+    assert len(plan.edges) == 18
+
+
+def test_arbitrary_dp_pp_tp_topologies_select_one_source_replica() -> None:
+    source = _placement(
+        "source",
+        ((0, 1), (2, 3), (4, 5)),
+        2,
+        dp_size=2,
+    )
+    target = _placement(
+        "target",
+        ((0, 1, 2), (3, 4, 5)),
+        4,
+        dp_size=4,
+    )
+
+    for target_dp_rank in range(4):
+        participant_id = f"target-d{target_dp_rank}-p0-t3"
+        plan = _plan(source, target, participant_id)
+        assert plan.source_dp_rank == target_dp_rank % 2
+        assert {
+            source.part(participant_id).rank.dp
+            for participant_id in plan.source_participant_ids
+        } == {target_dp_rank % 2}
+
+    explicit = _plan(
+        source,
+        target,
+        "target-d3-p0-t3",
+        source_dp_rank=0,
+    )
+    assert explicit.source_dp_rank == 0
+    assert explicit.source_participant_ids == (
+        ParticipantId("source-d0-p0-t1"),
+        ParticipantId("source-d0-p1-t1"),
+    )
+
+    with pytest.raises(ValueError, match="source DP rank 9"):
+        _plan(
+            source,
+            target,
+            "target-d0-p0-t0",
+            source_dp_rank=9,
+        )
+
+
+def test_role_agnostic_placement_assembly_supports_multiple_dp_replicas() -> None:
+    placement = _placement("server-a", ((0,), (1,)), 2, dp_size=3)
+    assembled = assemble_kv_cache_placement(
+        placement.parts,
+        dp_size=3,
+        pp_size=2,
+        tp_size=2,
+    )
+    assert assembled == placement
+    assert assembled.dp_ranks == (0, 1, 2)
+
+
+def test_complete_placement_rejects_missing_participant_and_coverage() -> None:
+    complete = _placement("source", ((0,),), 2)
+    with pytest.raises(ValueError, match="missing topology participant"):
+        KVCachePlacementManifest(
+            resource_id=complete.resource_id,
+            revision=complete.revision,
+            placement_set_id=complete.placement_set_id,
+            topology=complete.topology,
+            descriptor=complete.descriptor,
+            parts=complete.parts[:1],
+        )
+
+    malformed = replace(complete.parts[1], head_start=1, head_count=1)
+    with pytest.raises(ValueError, match="overlapping|misses"):
+        KVCachePlacementManifest(
+            resource_id=complete.resource_id,
+            revision=complete.revision,
+            placement_set_id=complete.placement_set_id,
+            topology=complete.topology,
+            descriptor=complete.descriptor,
+            parts=(complete.parts[0], malformed),
+        )
+
+
+def test_binding_requires_exact_participant_membership_and_global_digest() -> None:
+    placement = _placement("source", ((0,),), 2)
+    bindings = tuple(
+        _binding(
+            placement, part.participant_id, base_address=1_000_000_000 + i * 10_000_000
+        )
+        for i, part in enumerate(placement.parts)
+    )
+    validate_runtime_bindings(placement, bindings)
+    validate_runtime_binding(placement, bindings[0])
+
+    with pytest.raises(ValueError, match="missing runtime binding participant"):
+        validate_runtime_bindings(placement, bindings[:1])
+    with pytest.raises(ValueError, match="digest"):
+        validate_runtime_binding(
+            placement,
+            replace(bindings[0], placement_digest="0" * 64),
+        )
+
+
+@pytest.mark.parametrize("different", ["worker", "device", "instance", None])
+def test_identical_virtual_addresses_respect_address_space(different):
+    placement = _placement("source", ((0,),), 2)
+    first = _binding_with_address_space(
+        _binding(
+            placement,
+            placement.parts[0].participant_id,
+            base_address=1_000_000,
+            capacity_tokens=1,
+        )
+    )
+    second = _binding_with_address_space(
+        _binding(
+            placement,
+            placement.parts[1].participant_id,
+            base_address=1_000_000,
+            capacity_tokens=1,
+        ),
+        **({different: "other"} if different else {}),
+    )
+    if different:
+        validate_runtime_bindings(placement, (first, second))
+    else:
+        with pytest.raises(ValueError, match="overlap"):
+            validate_runtime_bindings(placement, (first, second))
+
+
+def test_per_participant_views_also_respect_device_address_space():
+    placement = _placement("source", ((0,),), 1)
+    binding = _binding(
+        placement,
+        placement.parts[0].participant_id,
+        base_address=1_000_000,
+        capacity_tokens=1,
+    )
+    first, second = binding.buffers
+    second = replace(
+        second,
+        fragment=replace(
+            second.fragment,
+            address=first.fragment.address,
+            storage_address=first.fragment.storage_address,
+            device="cuda:1",
+        ),
+    )
+    validate_runtime_binding(placement, replace(binding, buffers=(first, second)))
+
+
+@pytest.mark.parametrize(
+    "allocations,accepted",
+    [
+        (((1024, 256), (1152, 256)), False),
+        (((1024, 512), (1024, 512)), True),
+        (((1024, 256), (1280, 256)), True),
+        (((1024, 256), (1024, 512)), False),
+    ],
+)
+def test_backing_allocations_with_disjoint_views(allocations, accepted):
+    placement = _placement("source", ((0,),), 1)
+    binding = _binding(
+        placement,
+        placement.parts[0].participant_id,
+        base_address=1_000_000,
+        capacity_tokens=1,
+    )
+    buffers = tuple(
+        _buffer_with_storage(item, address, *allocation)
+        for item, address, allocation in zip(binding.buffers, (1024, 1280), allocations)
+    )
+    binding = replace(binding, buffers=buffers)
+    if accepted:
+        validate_runtime_binding(placement, binding)
+    else:
+        with pytest.raises(ValueError, match="backing allocation.*overlap"):
+            validate_runtime_binding(placement, binding)
+
+
+@pytest.mark.parametrize("same_allocation", [True, False])
+def test_backing_allocations_across_participants(same_allocation):
+    placement = _placement("source", ((0,),), 2)
+    first = _binding_with_address_space(
+        _binding(
+            placement,
+            placement.parts[0].participant_id,
+            base_address=1_000_000,
+            capacity_tokens=1,
+        )
+    )
+    second = _binding_with_address_space(
+        _binding(
+            placement,
+            placement.parts[1].participant_id,
+            base_address=3_000_000,
+            capacity_tokens=1,
+        )
+    )
+    first = replace(
+        first,
+        buffers=(
+            _buffer_with_storage(
+                first.buffers[0], 1024, 1024, 512 if same_allocation else 256
+            ),
+            first.buffers[1],
+        ),
+    )
+    second = replace(
+        second,
+        buffers=(
+            _buffer_with_storage(
+                second.buffers[0],
+                1280,
+                1024 if same_allocation else 1152,
+                512 if same_allocation else 256,
+            ),
+            second.buffers[1],
+        ),
+    )
+    if same_allocation:
+        validate_runtime_bindings(placement, (first, second))
+    else:
+        with pytest.raises(ValueError, match="backing allocation.*overlap"):
+            validate_runtime_bindings(placement, (first, second))
+
+
+def test_shared_backing_allocation_does_not_allow_overlapping_views():
+    placement = _placement("source", ((0,),), 1)
+    binding = _binding(
+        placement,
+        placement.parts[0].participant_id,
+        base_address=1_000_000,
+        capacity_tokens=1,
+    )
+    binding = replace(
+        binding,
+        buffers=tuple(
+            _buffer_with_storage(item, 1024, 1024, 512) for item in binding.buffers
+        ),
+    )
+    with pytest.raises(ValueError, match="buffers overlap"):
+        validate_runtime_binding(placement, binding)
+
+
+def test_singleton_stride_is_normalized_before_binding_validation() -> None:
+    placement = _placement("source", ((0,),), 4)
+    binding = _binding(placement, "source-p0-t0", base_address=1_000_000_000)
+    first = binding.buffers[0]
+    fragment = first.fragment
+    assert fragment.local_shape[1] == 1
+    noncanonical = replace(
+        fragment,
+        strides_bytes=(fragment.strides_bytes[0], 999_999, fragment.strides_bytes[2]),
+    )
+    normalized = replace(
+        binding,
+        buffers=(
+            replace(first, fragment=noncanonical),
+            *binding.buffers[1:],
+        ),
+    )
+    validate_runtime_binding(placement, normalized)
+
+
+def test_logical_plan_round_trip_preserves_both_global_placements() -> None:
+    source = _placement("source", ((0,),), 2)
+    target = _placement("target", ((0,),), 1)
+    plan = _plan(source, target, "target-p0-t0").for_source(
+        ParticipantId("source-p0-t0")
+    )
+
+    restored = kv_cache_logical_plan_from_json(kv_cache_logical_plan_to_json(plan))
+
+    assert restored == plan
+    assert restored.source_placement.placement_id == source.placement_id
+    assert restored.target_placement.placement_id == target.placement_id
+
+    duplicate = kv_cache_logical_plan_to_json(plan).replace(
+        '"expected_writer_ids":',
+        '"expected_writer_ids":[],"expected_writer_ids":',
+        1,
+    )
+    with pytest.raises(ValueError, match="duplicate JSON field"):
+        kv_cache_logical_plan_from_json(duplicate)
+
+
+def test_snapshot_contract_is_canonical_and_optional_for_pd() -> None:
+    snapshot = _snapshot(token_start=4, token_count=6)
+    restored = kv_cache_snapshot_from_json(kv_cache_snapshot_to_json(snapshot))
+
+    assert restored == snapshot
+    assert restored.token_end == 10
+
+    source = _placement("source", ((0,),), 1)
+    semantic_target = _placement("semantic-target", ((0,),), 1)
+    plain = _plan(source, semantic_target, "semantic-target-p0-t0")
+    semantic = _plan(
+        source,
+        semantic_target,
+        "semantic-target-p0-t0",
+        snapshot=snapshot,
+    )
+    assert plain.plan_id == semantic.plan_id
+    assert plain.digest != semantic.digest
+
+    target = _placement(
+        "target",
+        ((0,),),
+        1,
+        resource_id="kv:framework-owned-target",
+        revision="different-framework-revision",
+    )
+    plan = _plan(source, target, "target-p0-t0")
+    assert plan.snapshot is None
+
+    with pytest.raises(ValueError, match="target placement resource_id"):
+        _plan(source, target, "target-p0-t0", snapshot=snapshot)
+
+
+@pytest.mark.parametrize(
+    "start,count,accepted",
+    [(_MAX_U64, 1, False), (_MAX_U64 - 1, 1, True), (0, _MAX_U64, True)],
+)
+def test_snapshot_token_end_boundary(start, count, accepted):
+    if accepted:
+        assert (
+            _snapshot(token_start=start, token_count=count).token_end == start + count
+        )
+    else:
+        with pytest.raises(ValueError, match="token_end"):
+            _snapshot(token_start=start, token_count=count)
+
+
+def test_page_size_repacking_is_rejected_explicitly() -> None:
+    source = _placement("source", ((0,),), 1, page_size=16)
+    target = _placement("target", ((0,),), 1, page_size=32)
+
+    with pytest.raises(ValueError, match="page_size.*unsupported"):
+        _plan(source, target, "target-p0-t0")
+
+
+def test_logical_plan_identity_and_edges_are_semantically_verified() -> None:
+    source = _placement("source", ((0,),), 2)
+    target = _placement("target", ((0,),), 1)
+    plan = _plan(source, target, "target-p0-t0")
+    restored = kv_cache_logical_plan_from_json(kv_cache_logical_plan_to_json(plan))
+
+    assert restored.plan_id == plan.plan_id
+    assert restored.digest == plan.digest
+
+    malformed_edge = replace(plan.edges[0], head_count=plan.edges[0].head_count + 1)
+    with pytest.raises(ValueError, match="canonical plan"):
+        KVCacheLogicalTransferPlan(
+            source_placement=source,
+            target_placement=target,
+            target_participant_id=plan.target_participant_id,
+            edges=(malformed_edge, *plan.edges[1:]),
+            expected_writer_ids=plan.expected_writer_ids,
+        )
+
+
+def test_snapshot_bound_runtime_bindings_are_checked_at_prepare() -> None:
+    snapshot = _snapshot()
+    source = _placement("source", ((0,),), 2)
+    target = _placement("target", ((0,),), 1)
+    full_plan = _plan(source, target, "target-p0-t0", snapshot=snapshot)
+    source_id = full_plan.source_participant_ids[0]
+    plan = full_plan.for_source(source_id)
+    source_binding = _binding(
+        source,
+        source_id,
+        base_address=1_000_000_000,
+        snapshot=snapshot,
+    )
+    target_binding = _binding(
+        target,
+        "target-p0-t0",
+        base_address=2_000_000_000,
+        snapshot=snapshot,
+    )
+
+    prepared = prepare_kv_cache_transfer(plan, source_binding, target_binding)
+    assert prepared.snapshot_id == snapshot.snapshot_id
+    assert prepared.snapshot_digest == snapshot.digest
+
+    binding_payload = json.loads(kv_cache_runtime_binding_to_json(source_binding))
+    assert "generation" not in binding_payload
+    assert "lease_id" not in binding_payload
+
+    stale = replace(target_binding, snapshot_digest="0" * 64)
+    with pytest.raises(ValueError, match="snapshot digest"):
+        prepare_kv_cache_transfer(plan, source_binding, stale)
+
+
+@pytest.mark.parametrize(
+    "source_snapshot,target_snapshot,explicit_plan,mismatched_digest,accepted",
+    [
+        (None, None, False, False, True),
+        (0, 0, False, False, True),
+        (0, 8, False, False, False),
+        (0, None, False, False, False),
+        (None, 0, False, False, False),
+        (0, 0, True, False, True),
+        (0, 8, True, False, False),
+        (None, None, True, False, False),
+        (0, 0, False, True, False),
+    ],
+)
+def test_prepare_snapshot_identity(
+    source_snapshot, target_snapshot, explicit_plan, mismatched_digest, accepted
+):
+    source = _placement("source", ((0,),), 1)
+    target = _placement("target", ((0,),), 1)
+    snapshot = _snapshot()
+    sb = _binding(
+        source,
+        source.parts[0].participant_id,
+        base_address=1_000_000,
+        snapshot=_snapshot(token_start=source_snapshot)
+        if source_snapshot is not None
+        else None,
+    )
+    tb = _binding(
+        target,
+        target.parts[0].participant_id,
+        base_address=3_000_000,
+        snapshot=_snapshot(token_start=target_snapshot)
+        if target_snapshot is not None
+        else None,
+    )
+    if mismatched_digest:
+        tb = replace(tb, snapshot_digest="0" * 64)
+    plan = _plan(
+        source,
+        target,
+        target.parts[0].participant_id,
+        snapshot=snapshot if explicit_plan else None,
+    )
+    if not accepted:
+        with pytest.raises(ValueError, match="snapshot"):
+            prepare_kv_cache_transfer(plan, sb, tb)
+    else:
+        prepared = prepare_kv_cache_transfer(plan, sb, tb)
+        assert prepared.snapshot_id == sb.snapshot_id
+        assert prepared.snapshot_digest == sb.snapshot_digest
diff --git a/mooncake-reshard/tests/kv_cache/test_runtime_transfer.py b/mooncake-reshard/tests/kv_cache/test_runtime_transfer.py
new file mode 100644
index 0000000000..34c25c3bee
--- /dev/null
+++ b/mooncake-reshard/tests/kv_cache/test_runtime_transfer.py
@@ -0,0 +1,757 @@
+from __future__ import annotations
+
+import ctypes
+import json
+import struct
+from dataclasses import replace
+
+import pytest
+from mooncake.reshard.kv_cache import (
+    KVCacheCompletion,
+    KVCacheComponent,
+    KVCacheRegisteredRegion,
+    KVCacheResolvedRange,
+    KVCacheResolvedRuntimeBinding,
+    KVCacheRuntimeTransferPlan,
+    KVCacheTargetReceipt,
+    KVCacheTransferEngineExecutor,
+    KVCacheTransferLimits,
+    kv_cache_resolved_binding_from_json,
+    kv_cache_resolved_binding_to_json,
+    kv_cache_runtime_transfer_from_json,
+    kv_cache_runtime_transfer_to_json,
+    kv_cache_target_receipt_from_json,
+    kv_cache_target_receipt_to_json,
+    kv_cache_writer_receipt_from_json,
+    kv_cache_writer_receipt_to_json,
+    plan_kv_cache_transfer_to_local_target,
+    resolve_contiguous_runtime_binding,
+    validate_resolved_runtime_binding,
+)
+from test_kv_cache_reshard import _binding, _placement, _snapshot
+
+
+def content(layer, component, token, head, dim):
+    return (
+        layer * 7001
+        + (11003 if component is KVCacheComponent.VALUE else 0)
+        + token * 137
+        + head * 31
+        + dim
+    ) % 65536
+
+
+def memory_binding(
+    placement,
+    participant_id,
+    snapshot,
+    operation_id="operation-1",
+    *,
+    source=False,
+    reverse=False,
+    padding=0,
+    endpoint=None,
+):
+    part = placement.part(participant_id)
+    endpoint = endpoint or f"{participant_id}:12345"
+    regions, ranges, buffers = [], [], []
+    for layer in part.layer_ids:
+        for component in KVCacheComponent:
+            dim = (
+                placement.descriptor.key_head_dim
+                if component is KVCacheComponent.KEY
+                else placement.descriptor.value_head_dim
+            )
+            head_stride = dim * 2 + padding
+            row_stride = part.head_count * head_stride + padding
+            buffer = ctypes.create_string_buffer(snapshot.token_count * row_stride)
+            ctypes.memset(ctypes.addressof(buffer), 0xA5, len(buffer))
+            region = KVCacheRegisteredRegion(
+                f"{layer}-{component.value}",
+                endpoint,
+                ctypes.addressof(buffer),
+                len(buffer),
+            )
+            regions.append(region)
+            buffers.append(buffer)
+            for token in range(snapshot.token_start, snapshot.token_end):
+                slot = token - snapshot.token_start
+                if reverse:
+                    slot = snapshot.token_count - slot - 1
+                ranges.append(
+                    KVCacheResolvedRange(
+                        layer,
+                        component,
+                        token,
+                        1,
+                        part.head_start,
+                        part.head_count,
+                        region.region_id,
+                        slot * row_stride,
+                        row_stride,
+                        head_stride,
+                    )
+                )
+                if source:
+                    for head in range(
+                        part.head_start, part.head_start + part.head_count
+                    ):
+                        for d in range(dim):
+                            struct.pack_into(
+                                "<H",
+                                buffer,
+                                slot * row_stride
+                                + (head - part.head_start) * head_stride
+                                + d * 2,
+                                content(layer, component, token, head, d),
+                            )
+    binding = KVCacheResolvedRuntimeBinding(
+        operation_id,
+        placement.resource_id,
+        placement.placement_id,
+        placement.digest,
+        f"instance:{participant_id}",
+        placement.revision,
+        participant_id,
+        snapshot.snapshot_id,
+        snapshot.digest,
+        tuple(regions),
+        tuple(ranges),
+    )
+    return binding, buffers
+
+
+def assert_content(placement, binding):
+    regions = {r.region_id: r for r in binding.regions}
+    touched = set()
+    for item in binding.ranges:
+        dim = (
+            placement.descriptor.key_head_dim
+            if item.component is KVCacheComponent.KEY
+            else placement.descriptor.value_head_dim
+        )
+        for token in range(item.token_start, item.token_end):
+            for head in range(item.head_start, item.head_end):
+                address = item.address(regions[item.region_id], token, head)
+                for d in range(dim):
+                    assert ctypes.c_uint16.from_address(
+                        address + d * 2
+                    ).value == content(
+                        item.global_layer_id, item.component, token, head, d
+                    )
+                    touched.update((address + d * 2, address + d * 2 + 1))
+    for region in binding.regions:
+        for address in range(region.address, region.address + region.nbytes):
+            if address not in touched:
+                assert ctypes.c_ubyte.from_address(address).value == 0xA5
+
+
+class MemoryEngine:
+    def __init__(self, fail_at=None, probe_result=0):
+        self.calls = []
+        self.fail_at = fail_at
+        self.probe_result = probe_result
+        self.probes = []
+
+    def register_memory(self, address, nbytes):
+        return 0
+
+    def unregister_memory(self, address):
+        return 0
+
+    def send_probe(self, endpoint):
+        self.probes.append(endpoint)
+        return self.probe_result
+
+    def batch_transfer_sync_write(self, endpoint, sources, targets, lengths):
+        self.calls.append((endpoint, sources, targets, lengths))
+        if len(self.calls) == self.fail_at:
+            return -1
+        for source, target, length in zip(sources, targets, lengths):
+            ctypes.memmove(target, source, length)
+        return 0
+
+
+def make_operation(source, target, *, limits=None, reverse=True, padding=4):
+    limits = limits or KVCacheTransferLimits()
+    snapshot = _snapshot(token_start=13, token_count=5)
+    plans = tuple(
+        plan_kv_cache_transfer_to_local_target(
+            source, target, p.participant_id, snapshot=snapshot
+        )
+        for p in target.parts
+        if p.layer_ids
+    )
+    selected = {w for p in plans for w in p.expected_writer_ids}
+    sb, tb, keepalive = [], [], []
+    for placement, selected_parts, output, is_source in (
+        (source, selected, sb, True),
+        (target, {p.target_participant_id for p in plans}, tb, False),
+    ):
+        for part in placement.parts:
+            if part.participant_id in selected_parts:
+                binding, buffers = memory_binding(
+                    placement,
+                    part.participant_id,
+                    snapshot,
+                    source=is_source,
+                    reverse=reverse and is_source,
+                    padding=padding,
+                )
+                output.append(binding)
+                keepalive.extend(buffers)
+    return KVCacheRuntimeTransferPlan(
+        "operation-1", plans, tuple(sb), tuple(tb), limits
+    ), keepalive
+
+
+def execute_all(plan, *, engine_factory=MemoryEngine):
+    receipts, engines, executors = [], [], []
+    for binding in plan.source_bindings:
+        engine = engine_factory()
+        executor = KVCacheTransferEngineExecutor(
+            engine,
+            instance_id=binding.instance_id,
+            endpoint=binding.regions[0].endpoint,
+        )
+        for region in binding.regions:
+            executor.register_region(region)
+        receipts.extend(executor.execute(plan, binding.participant_id, warmup=True))
+        engines.append(engine)
+        executors.append(executor)
+    return receipts, engines, executors
+
+
+@pytest.mark.parametrize(
+    "source_pp,target_pp,source_tp,target_tp,heads,source_dp,target_dp",
+    [
+        (((0, 1),), ((0, 1),), 1, 2, 4, 1, 1),
+        (((0, 1),), ((0, 1),), 2, 1, 4, 1, 1),
+        (((0,), (1,)), ((1,), (0,)), 2, 1, 4, 1, 1),
+        (((0, 1),), ((0,), (1,)), 1, 2, 4, 2, 3),
+        (((0,),), ((0,),), 4, 1, 2, 1, 1),
+        (((0,),), ((0,),), 4, 2, 1, 1, 1),
+    ],
+)
+def test_content_topologies_and_completion(
+    source_pp, target_pp, source_tp, target_tp, heads, source_dp, target_dp
+):
+    source = _placement(
+        "source", source_pp, source_tp, total_kv_heads=heads, dp_size=source_dp
+    )
+    target = _placement(
+        "target", target_pp, target_tp, total_kv_heads=heads, dp_size=target_dp
+    )
+    plan, _keepalive = make_operation(
+        source,
+        target,
+        limits=KVCacheTransferLimits(max_batch_operations=3, max_batch_bytes=48),
+    )
+    restored = kv_cache_runtime_transfer_from_json(
+        kv_cache_runtime_transfer_to_json(plan)
+    )
+    assert restored == plan
+    receipts, engines, executors = execute_all(restored)
+    barrier = KVCacheCompletion(plan)
+    for receipt in reversed(receipts):
+        barrier.record_writer(
+            kv_cache_writer_receipt_from_json(kv_cache_writer_receipt_to_json(receipt))
+        )
+        barrier.record_writer(receipt)
+    assert barrier.state == "writers_done"
+    assert not barrier.can_activate
+    for binding in plan.target_bindings:
+        assert_content(target, binding)
+        receipt = KVCacheTargetReceipt(
+            plan.operation_id, plan.digest, binding.participant_id, True
+        )
+        barrier.record_target(
+            kv_cache_target_receipt_from_json(kv_cache_target_receipt_to_json(receipt))
+        )
+        barrier.record_target(receipt)
+    assert barrier.can_activate
+    for binding, executor, engine in zip(plan.source_bindings, executors, engines):
+        before = len(engine.calls)
+        assert executor.execute(plan, binding.participant_id)
+        assert len(engine.calls) == before
+        assert len(engine.probes) == len(set(engine.probes))
+        for _, sources, _, lengths in engine.calls:
+            assert len(sources) <= 3
+            assert sum(lengths) <= 48
+
+
+@pytest.fixture
+def small_operation():
+    return make_operation(
+        _placement("source", ((0,),), 2), _placement("target", ((0,),), 1)
+    )
+
+
+@pytest.mark.parametrize(
+    "change,match",
+    [
+        ({"operation_id": "stale"}, "operation_id"),
+        ({"snapshot_digest": "0" * 64}, "snapshot_digest"),
+        ({"placement_digest": "0" * 64}, "placement_digest"),
+        ({"revision": "stale"}, "revision"),
+    ],
+)
+def test_binding_identity(small_operation, change, match):
+    plan, _ = small_operation
+    with pytest.raises(ValueError, match=match):
+        replace(plan, target_bindings=(replace(plan.target_bindings[0], **change),))
+
+
+@pytest.mark.parametrize(
+    "change,match",
+    [
+        ({"token_start": 12}, "token interval"),
+        ({"head_start": 1}, "unowned heads"),
+        ({"region_id": "absent"}, "unknown registered"),
+        ({"offset_bytes": 1 << 40}, "bounds"),
+        ({"offset_bytes": 1}, "aligned"),
+        ({"token_stride_bytes": 1}, "strides"),
+        ({"head_stride_bytes": 1}, "strides"),
+    ],
+)
+def test_range_geometry(small_operation, change, match):
+    plan, _ = small_operation
+    b = plan.target_bindings[0]
+    with pytest.raises(ValueError, match=match):
+        bad = replace(b, ranges=(replace(b.ranges[0], **change), *b.ranges[1:]))
+        replace(plan, target_bindings=(bad,))
+
+
+def test_coverage_overlap_aliasing_and_participants(small_operation):
+    plan, _ = small_operation
+    b = plan.target_bindings[0]
+    for ranges in (b.ranges[1:], b.ranges + (b.ranges[0],)):
+        with pytest.raises(ValueError, match="coverage|overlap"):
+            replace(plan, target_bindings=(replace(b, ranges=ranges),))
+    with pytest.raises(ValueError, match="source binding participants"):
+        replace(plan, source_bindings=plan.source_bindings[:1])
+    with pytest.raises(ValueError, match="every target"):
+        replace(plan, logical_plans=plan.logical_plans * 2)
+    with pytest.raises(ValueError, match="complete local-target"):
+        replace(
+            plan,
+            logical_plans=(
+                plan.logical_plans[0].for_source(
+                    plan.source_bindings[0].participant_id
+                ),
+            ),
+        )
+    with pytest.raises(ValueError, match="expansion limit|operation limit"):
+        replace(plan, limits=KVCacheTransferLimits(max_operations=1))
+    with pytest.raises(ValueError, match="byte limit"):
+        replace(plan, limits=KVCacheTransferLimits(max_bytes=1))
+    with pytest.raises(ValueError, match="work limit"):
+        replace(plan, limits=KVCacheTransferLimits(max_validation_work=1))
+    with pytest.raises(ValueError, match="range count"):
+        replace(plan, limits=KVCacheTransferLimits(max_ranges=1))
+
+
+def test_failure_is_terminal_and_retains_registration(small_operation):
+    plan, _ = small_operation
+    receipts, _, executors = execute_all(
+        plan, engine_factory=lambda: MemoryEngine(fail_at=1)
+    )
+    assert all(not r.success and not r.quiesced for r in receipts)
+    barrier = KVCacheCompletion(plan)
+    barrier.record_writer(receipts[0])
+    assert barrier.state == "failed"
+    assert not barrier.can_activate
+    with pytest.raises(ValueError, match="terminal"):
+        barrier.record_target(
+            KVCacheTargetReceipt(
+                plan.operation_id,
+                plan.digest,
+                plan.target_bindings[0].participant_id,
+                True,
+            )
+        )
+    with pytest.raises(RuntimeError, match="in flight"):
+        executors[0].unregister_region(plan.source_bindings[0].regions[0].region_id)
+
+
+def test_probe_failure_does_not_submit_and_is_quiescent(small_operation):
+    plan, _ = small_operation
+    receipts, engines, executors = execute_all(
+        plan, engine_factory=lambda: MemoryEngine(probe_result=-1)
+    )
+    assert all(not r.success and r.quiesced for r in receipts)
+    assert not any(e.calls for e in engines)
+    executors[0].unregister_region(plan.source_bindings[0].regions[0].region_id)
+
+
+def test_receipt_validation_and_timeout(small_operation, monkeypatch):
+    plan, _ = small_operation
+    receipts, _, _ = execute_all(plan)
+    barrier = KVCacheCompletion(plan)
+    with pytest.raises(ValueError, match="all expected writers"):
+        barrier.record_target(
+            KVCacheTargetReceipt(
+                plan.operation_id,
+                plan.digest,
+                plan.target_bindings[0].participant_id,
+                True,
+            )
+        )
+    for bad in (
+        replace(receipts[0], operation_id="stale"),
+        replace(receipts[0], transfer_digest="0" * 64),
+        replace(receipts[0], writer_id="unknown"),
+        replace(receipts[0], completed_bytes=0),
+    ):
+        with pytest.raises(ValueError):
+            barrier.record_writer(bad)
+    barrier.record_writer(receipts[0])
+    with pytest.raises(ValueError, match="conflicting"):
+        barrier.record_writer(replace(receipts[0], success=False, error="failed"))
+    from mooncake.reshard.kv_cache import completion
+
+    monkeypatch.setattr(completion.time, "monotonic", lambda: float("inf"))
+    assert barrier.state == "failed"
+    assert "deadline" in barrier.error
+
+
+def test_target_failure_blocks_activation(small_operation):
+    plan, _ = small_operation
+    receipts, _, _ = execute_all(plan)
+    barrier = KVCacheCompletion(plan)
+    for receipt in receipts:
+        barrier.record_writer(receipt)
+    barrier.record_target(
+        KVCacheTargetReceipt(
+            plan.operation_id,
+            plan.digest,
+            plan.target_bindings[0].participant_id,
+            False,
+            "content mismatch",
+        )
+    )
+    assert barrier.state == "failed"
+
+
+def test_strict_wire_and_overflow(small_operation):
+    plan, _ = small_operation
+    b = plan.source_bindings[0]
+    wire = kv_cache_resolved_binding_to_json(b)
+    assert kv_cache_resolved_binding_from_json(wire) == b
+    for bad in (
+        wire.replace('"schema":', '"schema":"duplicate","schema":', 1),
+        wire[:-1] + ',"unknown":1}',
+        wire.replace('"token_count":1', '"token_count":true', 1),
+        wire.replace('"offset_bytes":0', '"offset_bytes":NaN', 1),
+    ):
+        with pytest.raises(ValueError):
+            kv_cache_resolved_binding_from_json(bad)
+    payload = json.loads(kv_cache_runtime_transfer_to_json(plan))
+    payload["digest"] = "0" * 64
+    with pytest.raises(ValueError, match="digest"):
+        kv_cache_runtime_transfer_from_json(json.dumps(payload))
+    with pytest.raises(ValueError, match="region address end"):
+        KVCacheRegisteredRegion("r", "peer", (1 << 64) - 1, 8)
+    with pytest.raises(ValueError, match="wire limit"):
+        kv_cache_resolved_binding_from_json(" " * (16 * 1024 * 1024 + 1))
+
+
+def test_contiguous_compatibility_and_missing_snapshot():
+    source = _placement("source", ((0,),), 1)
+    target = _placement("target", ((0,),), 1)
+    snapshot = _snapshot(token_start=37, token_count=8)
+    b = _binding(source, "source-p0-t0", base_address=1000000, snapshot=snapshot)
+    resolved = resolve_contiguous_runtime_binding(
+        source, snapshot, b, operation_id="op", first_token_offset=3
+    )
+    validate_resolved_runtime_binding(source, snapshot, resolved, operation_id="op")
+    assert all(
+        r.token_start == 37 and r.offset_bytes == 3 * r.token_stride_bytes
+        for r in resolved.ranges
+    )
+    with pytest.raises(ValueError, match="capacity"):
+        resolve_contiguous_runtime_binding(
+            source, snapshot, b, operation_id="op", first_token_offset=255
+        )
+    logical = plan_kv_cache_transfer_to_local_target(
+        source, target, target.parts[0].participant_id
+    )
+    with pytest.raises(ValueError, match="explicit snapshot"):
+        KVCacheRuntimeTransferPlan("op", (logical,), (resolved,), (resolved,))
+
+
+def test_receiver_limits_cannot_be_raised_by_wire(small_operation):
+    plan, _ = small_operation
+    payload = json.loads(kv_cache_runtime_transfer_to_json(plan))
+    payload["limits"]["max_operations"] = (1 << 64) - 1
+    with pytest.raises(ValueError, match="receiver policy"):
+        kv_cache_runtime_transfer_from_json(json.dumps(payload))
+    with pytest.raises(ValueError, match="receiver policy"):
+        kv_cache_runtime_transfer_from_json(
+            kv_cache_runtime_transfer_to_json(plan),
+            limits=KVCacheTransferLimits(max_bytes=1),
+        )
+
+
+def test_local_registration_and_operation_reuse(small_operation):
+    plan, _ = small_operation
+    b = plan.source_bindings[0]
+    engine = MemoryEngine()
+    executor = KVCacheTransferEngineExecutor(
+        engine, instance_id=b.instance_id, endpoint=b.regions[0].endpoint
+    )
+    with pytest.raises(ValueError, match="not registered"):
+        executor.validate_local_binding(b)
+    with pytest.raises(ValueError, match="not registered"):
+        executor.execute(plan, b.participant_id)
+    assert not engine.calls
+    for region in b.regions:
+        executor.register_region(region)
+        executor.register_region(region)
+    executor.validate_local_binding(b)
+    executor.execute(plan, b.participant_id)
+    with pytest.raises(ValueError, match="different transfer"):
+        changed = replace(
+            plan,
+            target_bindings=(
+                replace(plan.target_bindings[0], instance_id="new-instance"),
+            ),
+        )
+        executor.execute(changed, b.participant_id)
+
+
+@pytest.mark.parametrize("operation", ["register", "unregister"])
+@pytest.mark.parametrize("failure", [-7, False, RuntimeError, KeyboardInterrupt])
+def test_registration_failure_blocks_further_operations(
+    small_operation, monkeypatch, operation, failure
+):
+    plan, _keepalive = small_operation
+    binding = plan.source_bindings[0]
+    engine = MemoryEngine()
+    executor = KVCacheTransferEngineExecutor(
+        engine, instance_id=binding.instance_id, endpoint=binding.regions[0].endpoint
+    )
+    for region in binding.regions:
+        executor.register_region(region)
+    # Also exercise the cached-success path after a later registration error.
+    assert all(r.success for r in executor.execute(plan, binding.participant_id))
+    submissions = len(engine.calls)
+    additional = KVCacheRegisteredRegion(
+        "additional",
+        binding.regions[0].endpoint,
+        max(r.address + r.nbytes for r in binding.regions) + 4096,
+        64,
+    )
+    method = "register_memory" if operation == "register" else "unregister_memory"
+    original = getattr(engine, method)
+    registration_calls = []
+
+    def fail(*args):
+        registration_calls.append(args)
+        if isinstance(failure, type):
+            raise failure("ambiguous registration state")
+        return failure
+
+    monkeypatch.setattr(engine, method, fail)
+    with pytest.raises(failure if isinstance(failure, type) else RuntimeError):
+        if operation == "register":
+            executor.register_region(additional)
+        else:
+            executor.unregister_region(binding.regions[0].region_id)
+    fresh = replace(
+        plan,
+        operation_id="retry",
+        source_bindings=tuple(
+            replace(b, operation_id="retry") for b in plan.source_bindings
+        ),
+        target_bindings=tuple(
+            replace(b, operation_id="retry") for b in plan.target_bindings
+        ),
+    )
+    for action in (
+        lambda: executor.execute(plan, binding.participant_id),
+        lambda: executor.execute(fresh, binding.participant_id),
+        lambda: executor.register_region(additional),
+        lambda: executor.register_region(binding.regions[0]),
+        lambda: executor.unregister_region(binding.regions[0].region_id),
+        lambda: executor.validate_local_binding(binding),
+    ):
+        with pytest.raises(RuntimeError, match="recovery"):
+            action()
+    assert len(registration_calls) == 1
+    assert len(engine.calls) == submissions
+    # A transient error disappearing does not prove that partial side effects
+    # have been recovered; the original executor must stay quarantined.
+    monkeypatch.setattr(engine, method, original)
+    with pytest.raises(RuntimeError, match="recovery"):
+        executor.execute(plan, binding.participant_id)
+
+
+def test_registration_preflight_errors_leave_executor_usable(small_operation):
+    plan, _keepalive = small_operation
+    binding = plan.source_bindings[0]
+    executor = KVCacheTransferEngineExecutor(
+        MemoryEngine(),
+        instance_id=binding.instance_id,
+        endpoint=binding.regions[0].endpoint,
+    )
+    for region in binding.regions:
+        executor.register_region(region)
+    region = binding.regions[0]
+    for invalid in (
+        replace(region, endpoint="other"),
+        replace(region, nbytes=region.nbytes + 1),
+        replace(region, region_id="overlap"),
+    ):
+        with pytest.raises(ValueError):
+            executor.register_region(invalid)
+    with pytest.raises(KeyError):
+        executor.unregister_region("unknown")
+    executor.unregister_region(region.region_id)
+    executor.register_region(region)
+    executor.validate_local_binding(binding)
+    assert all(r.success for r in executor.execute(plan, binding.participant_id))
+
+
+def test_disjoint_bytes_do_not_hide_duplicate_logical_ranges(small_operation):
+    plan, _ = small_operation
+    b = plan.target_bindings[0]
+    ranges = list(b.ranges)
+    ranges[1] = replace(ranges[1], token_start=ranges[0].token_start)
+    with pytest.raises(ValueError, match="logical coverage"):
+        replace(plan, target_bindings=(replace(b, ranges=tuple(ranges)),))
+
+
+def test_shared_instance_source_target_alias_is_rejected(small_operation):
+    plan, _ = small_operation
+    source, target = plan.source_bindings[0], plan.target_bindings[0]
+    regions = tuple(
+        replace(
+            r,
+            endpoint=source.regions[0].endpoint,
+            address=source.regions[0].address if i == 0 else r.address,
+        )
+        for i, r in enumerate(target.regions)
+    )
+    with pytest.raises(ValueError, match="overlap"):
+        replace(
+            plan,
+            target_bindings=(
+                replace(target, instance_id=source.instance_id, regions=regions),
+            ),
+        )
+
+
+def test_partial_batch_failure_does_not_activate(small_operation):
+    plan, _ = small_operation
+    plan = replace(
+        plan, limits=KVCacheTransferLimits(max_batch_operations=1, max_batch_bytes=32)
+    )
+    receipts, engines, executors = execute_all(
+        plan, engine_factory=lambda: MemoryEngine(fail_at=2)
+    )
+    assert all(len(e.calls) == 2 for e in engines)
+    assert all(
+        not r.success and not r.quiesced and r.completed_bytes == 16 for r in receipts
+    )
+    barrier = KVCacheCompletion(plan)
+    barrier.record_writer(receipts[0])
+    assert not barrier.can_activate
+    with pytest.raises(RuntimeError, match="recovery"):
+        fresh = replace(
+            plan,
+            operation_id="retry",
+            source_bindings=tuple(
+                replace(b, operation_id="retry") for b in plan.source_bindings
+            ),
+            target_bindings=tuple(
+                replace(b, operation_id="retry") for b in plan.target_bindings
+            ),
+        )
+        executors[0].execute(fresh, fresh.source_bindings[0].participant_id)
+
+
+def test_failure_retry_uses_new_operation_and_transport(small_operation):
+    plan, _ = small_operation
+    failed, _, _ = execute_all(plan, engine_factory=lambda: MemoryEngine(fail_at=1))
+    assert not failed[0].success
+    fresh = replace(
+        plan,
+        operation_id="retry",
+        source_bindings=tuple(
+            replace(b, operation_id="retry") for b in plan.source_bindings
+        ),
+        target_bindings=tuple(
+            replace(b, operation_id="retry") for b in plan.target_bindings
+        ),
+    )
+    receipts, _, _ = execute_all(fresh)
+    barrier = KVCacheCompletion(fresh)
+    for receipt in receipts:
+        barrier.record_writer(receipt)
+    for b in fresh.target_bindings:
+        assert_content(fresh.logical_plans[0].target_placement, b)
+        barrier.record_target(
+            KVCacheTargetReceipt(
+                fresh.operation_id, fresh.digest, b.participant_id, True
+            )
+        )
+    assert barrier.can_activate
+
+
+def test_invalid_native_return_is_not_success(small_operation):
+    plan, _ = small_operation
+
+    class InvalidEngine(MemoryEngine):
+        def batch_transfer_sync_write(self, *args):
+            return False  # bool compares equal to 0, but is not the native ABI
+
+    receipts, _, _ = execute_all(plan, engine_factory=InvalidEngine)
+    assert all(not r.success and not r.quiesced for r in receipts)
+
+
+def test_adjacent_registered_regions_must_not_be_coalesced():
+    source = _placement("source", ((0,),), 1)
+    target = _placement("target", ((0,),), 1)
+    snapshot = _snapshot(token_start=0, token_count=5)
+    bindings, _allocations = [], []
+    for placement in (source, target):
+        part = placement.parts[0]
+        allocation = ctypes.create_string_buffer(640)
+        _allocations.append(allocation)
+        regions = tuple(
+            KVCacheRegisteredRegion(
+                component.value,
+                f"{part.participant_id}:12345",
+                ctypes.addressof(allocation) + index * 320,
+                320,
+            )
+            for index, component in enumerate(KVCacheComponent)
+        )
+        ranges = tuple(
+            KVCacheResolvedRange(0, component, 0, 5, 0, 4, component.value, 0, 64, 16)
+            for component in KVCacheComponent
+        )
+        bindings.append(
+            KVCacheResolvedRuntimeBinding(
+                "adjacent",
+                placement.resource_id,
+                placement.placement_id,
+                placement.digest,
+                f"instance:{part.participant_id}",
+                placement.revision,
+                part.participant_id,
+                snapshot.snapshot_id,
+                snapshot.digest,
+                regions,
+                ranges,
+            )
+        )
+    logical = plan_kv_cache_transfer_to_local_target(
+        source, target, target.parts[0].participant_id, snapshot=snapshot
+    )
+    plan = KVCacheRuntimeTransferPlan(
+        "adjacent", (logical,), (bindings[0],), (bindings[1],)
+    )
+    assert len(plan.writes) == 2
+    assert [w.nbytes for w in plan.writes] == [320, 320]
diff --git a/mooncake-reshard/tests/kv_cache/test_runtime_transfer_native.py b/mooncake-reshard/tests/kv_cache/test_runtime_transfer_native.py
new file mode 100644
index 0000000000..5db4a18fcd
--- /dev/null
+++ b/mooncake-reshard/tests/kv_cache/test_runtime_transfer_native.py
@@ -0,0 +1,214 @@
+"""Opt-in real TE conformance across independently registered worker processes.
+
+MC_R2R_NATIVE=1 python -m pytest mooncake-reshard/tests/kv_cache/test_runtime_transfer_native.py -v
+MC_R2R_PROTOCOL=tcp|rdma selects a transport; MC_R2R_CUDA=1 selects GPU memory.
+The same worker protocol can be launched on separate hosts by a runtime's
+control plane. This harness exercises process boundaries on one physical host.
+"""
+
+from __future__ import annotations
+
+import multiprocessing as mp
+import os
+import traceback
+from dataclasses import replace
+
+import pytest
+from mooncake.reshard.kv_cache import (
+    KVCacheCompletion,
+    KVCacheRuntimeTransferPlan,
+    KVCacheTargetReceipt,
+    KVCacheTransferEngineExecutor,
+    KVCacheTransferLimits,
+    kv_cache_resolved_binding_from_json,
+    kv_cache_resolved_binding_to_json,
+    kv_cache_runtime_transfer_from_json,
+    kv_cache_runtime_transfer_to_json,
+    kv_cache_writer_receipt_from_json,
+    kv_cache_writer_receipt_to_json,
+    plan_kv_cache_transfer_to_local_target,
+)
+from test_kv_cache_reshard import _placement, _snapshot
+from test_runtime_transfer import assert_content, memory_binding
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("MC_R2R_NATIVE") != "1",
+    reason="set MC_R2R_NATIVE=1 for real TE tests",
+)
+
+
+def _worker(connection, role, tp, rank, protocol, use_cuda):
+    try:
+        from mooncake.engine import TransferEngine
+
+        placement = _placement(role, ((0, 1),), tp)
+        part = placement.parts[rank]
+        snapshot = _snapshot(token_start=13, token_count=5)
+        engine = TransferEngine()
+        host = os.environ.get("MC_R2R_HOST", "127.0.0.1")
+        result = engine.initialize(
+            host,
+            "P2PHANDSHAKE",
+            protocol,
+            os.environ.get("MC_R2R_DEVICE", "") if protocol == "rdma" else "",
+        )
+        if result != 0:
+            raise RuntimeError(f"TE initialize failed: {result}")
+        endpoint = f"{host}:{engine.get_rpc_port()}"
+        binding, buffers = memory_binding(
+            placement,
+            part.participant_id,
+            snapshot,
+            source=role == "source",
+            reverse=role == "source",
+            padding=4,
+            endpoint=endpoint,
+        )
+        gpu_buffers = []
+        if use_cuda:
+            import torch
+
+            device = (rank + (0 if role == "source" else 2)) % torch.cuda.device_count()
+            torch.cuda.set_device(device)
+            for buffer in buffers:
+                gpu_buffers.append(
+                    torch.frombuffer(buffer, dtype=torch.uint8)
+                    .clone()
+                    .to(f"cuda:{device}")
+                )
+            torch.cuda.synchronize()
+            binding = replace(
+                binding,
+                regions=tuple(
+                    replace(r, address=t.data_ptr())
+                    for r, t in zip(binding.regions, gpu_buffers)
+                ),
+            )
+        executor = KVCacheTransferEngineExecutor(
+            engine, instance_id=binding.instance_id, endpoint=endpoint
+        )
+        for region in binding.regions:
+            executor.register_region(region)
+        executor.validate_local_binding(binding)
+        connection.send(("binding", kv_cache_resolved_binding_to_json(binding)))
+        message = connection.recv()
+        if role == "source":
+            plan = kv_cache_runtime_transfer_from_json(message)
+            receipts = executor.execute(plan, part.participant_id, warmup=False)
+            connection.send(
+                ("receipts", [kv_cache_writer_receipt_to_json(r) for r in receipts])
+            )
+        else:
+            if message != "verify":
+                raise ValueError("unexpected target command")
+            if use_cuda:
+                cpu_buffers = [t.cpu() for t in gpu_buffers]
+                binding = replace(
+                    binding,
+                    regions=tuple(
+                        replace(r, address=t.data_ptr())
+                        for r, t in zip(binding.regions, cpu_buffers)
+                    ),
+                )
+            assert_content(placement, binding)
+            connection.send(("verified", part.participant_id))
+        connection.recv()  # coordinator keeps registrations/pins until barrier
+    except BaseException:  # noqa: BLE001 - forward worker diagnostics to parent
+        connection.send(("error", traceback.format_exc()))
+    finally:
+        connection.close()
+
+
+def _receive(connection, expected, timeout=90):
+    assert connection.poll(timeout), f"worker timed out waiting for {expected}"
+    kind, payload = connection.recv()
+    assert kind == expected, payload
+    return payload
+
+
+@pytest.mark.parametrize(
+    "source_tp,target_tp,kill_peer", [(2, 1, False), (1, 2, False), (1, 1, True)]
+)
+def test_native_content_and_peer_failure(source_tp, target_tp, kill_peer):
+    protocol = os.environ.get("MC_R2R_PROTOCOL", "tcp")
+    use_cuda = os.environ.get("MC_R2R_CUDA") == "1"
+    context = mp.get_context("spawn")
+    source = _placement("source", ((0, 1),), source_tp)
+    target = _placement("target", ((0, 1),), target_tp)
+    snapshot = _snapshot(token_start=13, token_count=5)
+    processes, sources, targets = [], [], []
+    try:
+        for role, tp, output in (
+            ("source", source_tp, sources),
+            ("target", target_tp, targets),
+        ):
+            for rank in range(tp):
+                parent, child = context.Pipe()
+                process = context.Process(
+                    target=_worker, args=(child, role, tp, rank, protocol, use_cuda)
+                )
+                process.start()
+                child.close()
+                processes.append((process, parent))
+                output.append(
+                    (
+                        process,
+                        parent,
+                        kv_cache_resolved_binding_from_json(
+                            _receive(parent, "binding")
+                        ),
+                    )
+                )
+        logical = tuple(
+            plan_kv_cache_transfer_to_local_target(
+                source, target, p.participant_id, snapshot=snapshot
+            )
+            for p in target.parts
+        )
+        plan = KVCacheRuntimeTransferPlan(
+            "operation-1",
+            logical,
+            tuple(b for _, _, b in sources),
+            tuple(b for _, _, b in targets),
+            KVCacheTransferLimits(max_batch_operations=3, max_batch_bytes=96),
+        )
+        barrier = KVCacheCompletion(plan, timeout_seconds=180)
+        if kill_peer:
+            targets[0][0].terminate()
+            targets[0][0].join(10)
+        for _, connection, _ in sources:
+            connection.send(kv_cache_runtime_transfer_to_json(plan))
+        receipts = [
+            kv_cache_writer_receipt_from_json(r)
+            for _, c, _ in sources
+            for r in _receive(c, "receipts")
+        ]
+        if kill_peer:
+            assert any(not r.success for r in receipts)
+            barrier.record_writer(next(r for r in receipts if not r.success))
+            assert not barrier.can_activate
+            assert barrier.state == "failed"
+            return
+        for receipt in receipts:
+            assert receipt.success, receipt.error
+            barrier.record_writer(receipt)
+        for _, connection, _ in targets:
+            connection.send("verify")
+        for _, connection, _ in targets:
+            participant = _receive(connection, "verified")
+            barrier.record_target(
+                KVCacheTargetReceipt(plan.operation_id, plan.digest, participant, True)
+            )
+        assert barrier.can_activate
+    finally:
+        for process, connection in processes:
+            if process.is_alive():
+                try:
+                    connection.send("close")
+                except (BrokenPipeError, EOFError):
+                    pass
+                process.join(5)
+            if process.is_alive():
+                process.terminate()
+                process.join(10)
+            connection.close()
diff --git a/mooncake-reshard/tests/model_weight_nd_planner/__init__.py b/mooncake-reshard/tests/model_weight_nd_planner/__init__.py
new file mode 100644
index 0000000000..a2ee29ca4f
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_nd_planner/__init__.py
@@ -0,0 +1 @@
+"""N-D planner tests organized by parallel-axis and serialization coverage."""
diff --git a/mooncake-reshard/tests/model_weight_nd_planner/helpers.py b/mooncake-reshard/tests/model_weight_nd_planner/helpers.py
new file mode 100644
index 0000000000..7f067aea73
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_nd_planner/helpers.py
@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from itertools import product
+from math import prod
+
+from mooncake.reshard._compat import _strict_zip
+from mooncake.reshard.weight.manifest import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+)
+
+from model_weight_planner.helpers import (
+    RuntimeInputs,
+    _canonical_strides_bytes,
+    plan_transfer as plan_transfer,
+    runtime_inputs_from_groups,
+)
+
+
+MODEL_ID = "qwen-family-moe"
+REVISION = "step-42"
+
+
+def tensor_descriptor(
+    tensor_id: str,
+    *,
+    global_shape: tuple[int, ...],
+    shard_dims: tuple[int, ...],
+    layer_id: int | None = 0,
+    parallel_axes: tuple[SplitAxis | ReplicatedAxis | OwnershipAxis, ...] | None = None,
+) -> TensorDescriptor:
+    if parallel_axes is None:
+        if not shard_dims:
+            parallel_axes = (
+                ReplicatedAxis(kind="dp"),
+                OwnershipAxis(kind="pp"),
+            )
+        elif len(shard_dims) == 1:
+            parallel_axes = (
+                ReplicatedAxis(kind="dp"),
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="tp", dim=shard_dims[0]),
+            )
+        else:
+            parallel_axes = (
+                ReplicatedAxis(kind="dp"),
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="ep", dim=shard_dims[0]),
+                SplitAxis(kind="tp", dim=shard_dims[1]),
+            )
+    return TensorDescriptor(
+        tensor_id=tensor_id,
+        global_shape=global_shape,
+        dtype="bfloat16",
+        itemsize=2,
+        layer_id=layer_id,
+        expert_id=None,
+        layout_fingerprint="framework:logical-contiguous:v2",
+        shard_dims=shard_dims,
+        parallel_axes=parallel_axes,
+    )
+
+
+def build_manifests(
+    side: str,
+    placements: list[
+        tuple[
+            TensorDescriptor,
+            ParallelRank,
+            tuple[int, ...],
+            tuple[int, ...],
+        ]
+    ],
+    *,
+    address_base: int,
+) -> RuntimeInputs:
+    grouped: dict[
+        ParallelRank,
+        list[tuple[TensorDescriptor, tuple[int, ...], tuple[int, ...]]],
+    ] = {}
+    for tensor, rank, offset, shape in placements:
+        grouped.setdefault(rank, []).append((tensor, offset, shape))
+
+    groups = []
+    address = address_base
+    for rank in sorted(grouped, key=lambda item: (item.dp, item.pp, item.ep, item.tp)):
+        worker_id = f"{side}-d{rank.dp}-p{rank.pp}-e{rank.ep}-t{rank.tp}"
+        placement_fragments = []
+        binding_fragments = []
+        tensors: dict[str, TensorDescriptor] = {}
+        for tensor, offset, shape in sorted(
+            grouped[rank], key=lambda item: item[0].tensor_id
+        ):
+            nbytes = prod(shape) * tensor.itemsize
+            placement_fragment_id = f"{worker_id}-{tensor.tensor_id}-placement"
+            placement_fragments.append(
+                PlacementFragment(
+                    placement_fragment_id=placement_fragment_id,
+                    tensor_id=tensor.tensor_id,
+                    global_offset=offset,
+                    local_shape=shape,
+                    nbytes=nbytes,
+                    rank=rank,
+                )
+            )
+            binding_fragments.append(
+                RuntimeBindingFragment(
+                    placement_fragment_id=placement_fragment_id,
+                    fragment_id=f"{worker_id}-{tensor.tensor_id}",
+                    address=address,
+                    nbytes=nbytes,
+                    worker_id=worker_id,
+                    endpoint=f"{worker_id}:12345",
+                    device="cuda:0",
+                    itemsize=tensor.itemsize,
+                    local_shape=shape,
+                    strides_bytes=_canonical_strides_bytes(shape, tensor.itemsize),
+                    storage_address=address,
+                    storage_nbytes=nbytes,
+                    storage_offset_bytes=0,
+                )
+            )
+            address += nbytes + 4096
+            tensors[tensor.tensor_id] = tensor
+        groups.append((worker_id, tuple(placement_fragments), tuple(binding_fragments)))
+    return runtime_inputs_from_groups(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id=side,
+        tensors=tuple(
+            sorted(
+                {tensor.tensor_id: tensor for tensor, _, _, _ in placements}.values(),
+                key=lambda item: item.tensor_id,
+            )
+        ),
+        groups=groups,
+    )
+
+
+def ep_tp_placements(
+    tensors: tuple[TensorDescriptor, ...],
+    *,
+    dp: int,
+    pp_owner: dict[str, int],
+    ep: int,
+    tp: int,
+    tp_dim: int,
+) -> list[tuple[TensorDescriptor, ParallelRank, tuple[int, ...], tuple[int, ...]]]:
+    placements = []
+    for tensor in tensors:
+        assert tensor.global_shape[0] % ep == 0
+        assert tensor.global_shape[tp_dim] % tp == 0
+        expert_extent = tensor.global_shape[0] // ep
+        tp_extent = tensor.global_shape[tp_dim] // tp
+        for dp_rank, ep_rank, tp_rank in product(range(dp), range(ep), range(tp)):
+            shape = list(tensor.global_shape)
+            offset = [0] * len(shape)
+            shape[0] = expert_extent
+            offset[0] = ep_rank * expert_extent
+            shape[tp_dim] = tp_extent
+            offset[tp_dim] = tp_rank * tp_extent
+            placements.append(
+                (
+                    tensor,
+                    ParallelRank(
+                        dp=dp_rank,
+                        pp=pp_owner[tensor.tensor_id],
+                        ep=ep_rank,
+                        tp=tp_rank,
+                    ),
+                    tuple(offset),
+                    tuple(shape),
+                )
+            )
+    return placements
+
+
+def fragment_payload(descriptor: TensorDescriptor, fragment) -> bytearray:
+    global_strides = []
+    running = 1
+    for extent in reversed(descriptor.global_shape):
+        global_strides.append(running)
+        running *= extent
+    global_strides.reverse()
+    payload = bytearray()
+    for local_coordinate in product(
+        *(range(extent) for extent in fragment.local_shape)
+    ):
+        global_coordinate = tuple(
+            begin + local
+            for begin, local in _strict_zip(fragment.global_offset, local_coordinate)
+        )
+        value = 1 + sum(
+            coordinate * stride
+            for coordinate, stride in _strict_zip(global_coordinate, global_strides)
+        )
+        mask = (1 << (descriptor.itemsize * 8)) - 1
+        payload.extend((value & mask).to_bytes(descriptor.itemsize, "little"))
+    return payload
+
+
+def assert_plan_copies_logical_contents(
+    plan,
+    source_manifests: RuntimeInputs,
+    target_manifests: RuntimeInputs,
+) -> None:
+    descriptors = {
+        tensor.tensor_id: tensor for tensor in source_manifests.placement.tensors
+    }
+    source_payloads = {}
+    source_parts = {
+        part.participant_id: part for part in source_manifests.placement.parts
+    }
+    for binding in source_manifests.bindings:
+        part = source_parts[binding.participant_id]
+        placement_by_id = {
+            fragment.placement_fragment_id: fragment for fragment in part.fragments
+        }
+        for runtime_fragment in binding.fragments:
+            placement_fragment = placement_by_id[runtime_fragment.placement_fragment_id]
+            source_payloads[placement_fragment.placement_fragment_id] = (
+                fragment_payload(
+                    descriptors[placement_fragment.tensor_id], placement_fragment
+                )
+            )
+
+    target_payloads = {}
+    target_placements_by_fragment_id = {}
+    target_parts = {
+        part.participant_id: part for part in target_manifests.placement.parts
+    }
+    for binding in target_manifests.bindings:
+        part = target_parts[binding.participant_id]
+        placement_by_id = {
+            fragment.placement_fragment_id: fragment for fragment in part.fragments
+        }
+        for runtime_fragment in binding.fragments:
+            placement_fragment = placement_by_id[runtime_fragment.placement_fragment_id]
+            target_payloads[placement_fragment.placement_fragment_id] = bytearray(
+                runtime_fragment.nbytes
+            )
+            target_placements_by_fragment_id[
+                placement_fragment.placement_fragment_id
+            ] = placement_fragment
+
+    for operation in plan.operations:
+        source = source_payloads[operation.source.placement_fragment_id]
+        target = target_payloads[operation.target.placement_fragment_id]
+        for source_offset, target_offset, nbytes in operation.iter_segments(
+            max_segments=operation.segment_count
+        ):
+            target[target_offset : target_offset + nbytes] = source[
+                source_offset : source_offset + nbytes
+            ]
+
+    for fragment_id, placement_fragment in target_placements_by_fragment_id.items():
+        assert target_payloads[fragment_id] == fragment_payload(
+            descriptors[placement_fragment.tensor_id], placement_fragment
+        )
+
+
+def pp_placements(
+    tensors: tuple[TensorDescriptor, ...],
+    owners: dict[str, int],
+) -> list[tuple[TensorDescriptor, ParallelRank, tuple[int, ...], tuple[int, ...]]]:
+    return [
+        (
+            tensor,
+            ParallelRank(pp=owners[tensor.tensor_id]),
+            (0,),
+            tensor.global_shape,
+        )
+        for tensor in tensors
+    ]
diff --git a/mooncake-reshard/tests/model_weight_nd_planner/test_all_axis_operation_count.py b/mooncake-reshard/tests/model_weight_nd_planner/test_all_axis_operation_count.py
new file mode 100644
index 0000000000..532a694f8b
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_nd_planner/test_all_axis_operation_count.py
@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.weight.manifest import ParallelRank, SplitAxis
+from mooncake.reshard.weight.planner import (
+    PlanningLimits,
+    TransferRegion,
+    plan_placement_transfer,
+)
+
+from .helpers import (
+    assert_plan_copies_logical_contents,
+    build_manifests,
+    ep_tp_placements,
+    plan_transfer,
+    tensor_descriptor,
+)
+
+
+def test_four_axis_reshard_has_complete_content_and_routes() -> None:
+    source_tensors = tuple(
+        tensor_descriptor(
+            f"layers.{layer}.experts.w1",
+            global_shape=(8, 8, 2),
+            shard_dims=(0, 1),
+            layer_id=layer,
+        )
+        for layer in range(4)
+    )
+    target_tensors = tuple(
+        tensor_descriptor(
+            tensor.tensor_id,
+            global_shape=tensor.global_shape,
+            shard_dims=(0, 1),
+            layer_id=tensor.layer_id,
+        )
+        for tensor in source_tensors
+    )
+    source_owners = {
+        tensor.tensor_id: tensor.layer_id // 2 for tensor in source_tensors
+    }
+    target_owners = {tensor.tensor_id: tensor.layer_id for tensor in target_tensors}
+    sources = build_manifests(
+        "source",
+        ep_tp_placements(
+            source_tensors,
+            dp=2,
+            pp_owner=source_owners,
+            ep=8,
+            tp=4,
+            tp_dim=1,
+        ),
+        address_base=0x10000000,
+    )
+    targets = build_manifests(
+        "target",
+        ep_tp_placements(
+            target_tensors,
+            dp=4,
+            pp_owner=target_owners,
+            ep=2,
+            tp=8,
+            tp_dim=1,
+        ),
+        address_base=0x20000000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert plan.total_bytes == 4 * 8 * 8 * 2 * 2 * 4
+    assert {operation.source.rank.dp for operation in plan.operations} == {0, 1}
+    assert {operation.target.rank.dp for operation in plan.operations} == {
+        0,
+        1,
+        2,
+        3,
+    }
+    assert {operation.source.rank.tp for operation in plan.operations} == set(range(4))
+    assert {operation.target.rank.tp for operation in plan.operations} == set(range(8))
+    assert {operation.source.rank.ep for operation in plan.operations} == set(range(8))
+    assert {operation.target.rank.ep for operation in plan.operations} == {0, 1}
+    assert {(route.source_pp, route.target_pp) for route in plan.pipeline_routes} == {
+        (0, 0),
+        (0, 1),
+        (1, 2),
+        (1, 3),
+    }
+    assert_plan_copies_logical_contents(plan, sources, targets)
+
+
+def test_cross_dim_planner_keeps_operation_count_at_region_granularity() -> None:
+    source_tensor = tensor_descriptor(
+        "layers.0.experts.w1",
+        global_shape=(8, 8192, 8192),
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    target_tensor = tensor_descriptor(
+        source_tensor.tensor_id,
+        global_shape=source_tensor.global_shape,
+        shard_dims=(2,),
+    )
+    source_placements = [
+        (
+            source_tensor,
+            ParallelRank(ep=rank),
+            (rank, 0, 0),
+            (1, 8192, 8192),
+        )
+        for rank in range(8)
+    ]
+    target_placements = [
+        (
+            target_tensor,
+            ParallelRank(tp=rank),
+            (0, 0, rank * 1024),
+            (8, 8192, 1024),
+        )
+        for rank in range(8)
+    ]
+    sources = build_manifests("source", source_placements, address_base=0x100000000)
+    targets = build_manifests("target", target_placements, address_base=0x300000000)
+
+    plan = plan_transfer(sources, targets)
+
+    assert len(plan.operations) == 64
+    assert {operation.segment_count for operation in plan.operations} == {8192}
+    assert all(isinstance(operation, TransferRegion) for operation in plan.operations)
+
+
+def test_cross_dim_planner_rejects_total_region_budget_before_materialization() -> None:
+    source_tensor = tensor_descriptor(
+        "layers.0.experts.w1",
+        global_shape=(8, 8, 8),
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    target_tensor = tensor_descriptor(
+        source_tensor.tensor_id,
+        global_shape=source_tensor.global_shape,
+        shard_dims=(2,),
+    )
+    sources = build_manifests(
+        "source-budget",
+        [
+            (source_tensor, ParallelRank(ep=rank), (rank, 0, 0), (1, 8, 8))
+            for rank in range(8)
+        ],
+        address_base=0x100000000,
+    )
+    targets = build_manifests(
+        "target-budget",
+        [
+            (target_tensor, ParallelRank(tp=rank), (0, 0, rank), (8, 8, 1))
+            for rank in range(8)
+        ],
+        address_base=0x300000000,
+    )
+
+    with pytest.raises(ValueError, match="max_transfer_regions"):
+        plan_placement_transfer(
+            sources.placement,
+            targets.placement,
+            planning_limits=PlanningLimits(max_transfer_regions=63),
+        )
diff --git a/mooncake-reshard/tests/model_weight_nd_planner/test_pp_ep_cross_dim.py b/mooncake-reshard/tests/model_weight_nd_planner/test_pp_ep_cross_dim.py
new file mode 100644
index 0000000000..0dd6830ba3
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_nd_planner/test_pp_ep_cross_dim.py
@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.weight.manifest import ParallelRank, SplitAxis
+from mooncake.reshard.weight.planner import TransferRegion
+
+from .helpers import (
+    assert_plan_copies_logical_contents,
+    build_manifests,
+    ep_tp_placements,
+    plan_transfer,
+    pp_placements,
+    tensor_descriptor,
+)
+
+
+@pytest.mark.parametrize(
+    ("source_owners", "target_owners", "expected_routes"),
+    [
+        (
+            {f"layers.{layer}.weight": layer // 2 for layer in range(4)},
+            {f"layers.{layer}.weight": layer for layer in range(4)},
+            {(0, 0), (0, 1), (1, 2), (1, 3)},
+        ),
+        (
+            {f"layers.{layer}.weight": layer for layer in range(4)},
+            {f"layers.{layer}.weight": layer // 2 for layer in range(4)},
+            {(0, 0), (1, 0), (2, 1), (3, 1)},
+        ),
+    ],
+)
+def test_pp_ownership_routes_are_manifest_derived(
+    source_owners: dict[str, int],
+    target_owners: dict[str, int],
+    expected_routes: set[tuple[int, int]],
+) -> None:
+    tensors = tuple(
+        tensor_descriptor(
+            f"layers.{layer}.weight",
+            global_shape=(8,),
+            shard_dims=(),
+            layer_id=layer,
+        )
+        for layer in range(4)
+    )
+    sources = build_manifests(
+        "source",
+        pp_placements(tensors, source_owners),
+        address_base=0x100000,
+    )
+    targets = build_manifests(
+        "target",
+        pp_placements(tensors, target_owners),
+        address_base=0x200000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert {
+        (route.source_pp, route.target_pp) for route in plan.pipeline_routes
+    } == expected_routes
+    assert sorted(
+        index for route in plan.pipeline_routes for index in route.operation_indices
+    ) == list(range(len(plan.operations)))
+    assert_plan_copies_logical_contents(plan, sources, targets)
+
+
+@pytest.mark.parametrize(("source_ep", "target_ep"), [(8, 2), (2, 8)])
+def test_ep_reshard_uses_leading_expert_coordinate(
+    source_ep: int, target_ep: int
+) -> None:
+    source_tensor = tensor_descriptor(
+        "layers.0.experts.w1",
+        global_shape=(8, 4, 2),
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    target_tensor = tensor_descriptor(
+        source_tensor.tensor_id,
+        global_shape=source_tensor.global_shape,
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    sources = build_manifests(
+        "source",
+        ep_tp_placements(
+            (source_tensor,),
+            dp=1,
+            pp_owner={source_tensor.tensor_id: 0},
+            ep=source_ep,
+            tp=1,
+            tp_dim=1,
+        ),
+        address_base=0x100000,
+    )
+    targets = build_manifests(
+        "target",
+        ep_tp_placements(
+            (target_tensor,),
+            dp=1,
+            pp_owner={target_tensor.tensor_id: 0},
+            ep=target_ep,
+            tp=1,
+            tp_dim=1,
+        ),
+        address_base=0x200000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert all(operation.overlap_shape[0] > 0 for operation in plan.operations)
+    assert {operation.source.rank.ep for operation in plan.operations} == set(
+        range(source_ep)
+    )
+    assert {operation.target.rank.ep for operation in plan.operations} == set(
+        range(target_ep)
+    )
+    assert_plan_copies_logical_contents(plan, sources, targets)
+
+
+@pytest.mark.parametrize("target_dim", [1, 2])
+def test_ep_tp_cross_dim_reshard(target_dim: int) -> None:
+    source_tensor = tensor_descriptor(
+        "layers.0.experts.w1",
+        global_shape=(4, 6, 8),
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    target_tensor = tensor_descriptor(
+        source_tensor.tensor_id,
+        global_shape=source_tensor.global_shape,
+        shard_dims=(target_dim,),
+    )
+    source_placements = []
+    for ep_rank in range(2):
+        source_placements.append(
+            (
+                source_tensor,
+                ParallelRank(ep=ep_rank),
+                (ep_rank * 2, 0, 0),
+                (2, 6, 8),
+            )
+        )
+    target_placements = []
+    for tp_rank in range(2):
+        shape = list(target_tensor.global_shape)
+        offset = [0, 0, 0]
+        shape[target_dim] //= 2
+        offset[target_dim] = tp_rank * shape[target_dim]
+        target_placements.append(
+            (
+                target_tensor,
+                ParallelRank(tp=tp_rank),
+                tuple(offset),
+                tuple(shape),
+            )
+        )
+    sources = build_manifests("source", source_placements, address_base=0x100000)
+    targets = build_manifests("target", target_placements, address_base=0x200000)
+
+    plan = plan_transfer(sources, targets)
+
+    assert len(plan.operations) == 4
+    assert all(isinstance(operation, TransferRegion) for operation in plan.operations)
+    selected = next(
+        operation
+        for operation in plan.operations
+        if operation.source.rank.ep == 0 and operation.target.rank.tp == 1
+    )
+    if target_dim == 1:
+        assert selected.overlap_offset == (0, 3, 0)
+        assert selected.overlap_shape == (2, 3, 8)
+        assert selected.source_base_offset == 48
+        assert selected.target_base_offset == 0
+        assert selected.inner_bytes == 48
+        assert selected.outer_loop_counts == (2,)
+        assert selected.source_strides == (96,)
+        assert selected.target_strides == (48,)
+    else:
+        assert selected.overlap_offset == (0, 0, 4)
+        assert selected.overlap_shape == (2, 6, 4)
+        assert selected.source_base_offset == 8
+        assert selected.target_base_offset == 0
+        assert selected.inner_bytes == 8
+        assert selected.outer_loop_counts == (2, 6)
+        assert selected.source_strides == (96, 16)
+        assert selected.target_strides == (48, 8)
+    assert_plan_copies_logical_contents(plan, sources, targets)
diff --git a/mooncake-reshard/tests/model_weight_nd_planner/test_tp_serialized_fp8.py b/mooncake-reshard/tests/model_weight_nd_planner/test_tp_serialized_fp8.py
new file mode 100644
index 0000000000..256c223048
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_nd_planner/test_tp_serialized_fp8.py
@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+from itertools import product
+from math import prod
+
+import pytest
+
+from mooncake.reshard.weight.manifest import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    SplitAxis,
+)
+
+from .helpers import (
+    MODEL_ID,
+    REVISION,
+    assert_plan_copies_logical_contents,
+    build_manifests,
+    ep_tp_placements,
+    plan_transfer,
+    tensor_descriptor,
+)
+from model_weight_planner.helpers import (
+    RuntimeInputs,
+    _canonical_strides_bytes,
+    runtime_inputs_from_groups,
+)
+
+
+@pytest.mark.parametrize(("source_tp", "target_tp"), [(4, 8), (8, 4)])
+def test_tp_split_and_merge_preserve_logical_bytes(
+    source_tp: int,
+    target_tp: int,
+) -> None:
+    tensor = tensor_descriptor(
+        "layers.0.mlp.down_proj.weight",
+        global_shape=(64, 16),
+        shard_dims=(0,),
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    owner = {tensor.tensor_id: 0}
+    sources = build_manifests(
+        "source",
+        ep_tp_placements(
+            (tensor,),
+            dp=1,
+            pp_owner=owner,
+            ep=1,
+            tp=source_tp,
+            tp_dim=0,
+        ),
+        address_base=0x100000,
+    )
+    targets = build_manifests(
+        "target",
+        ep_tp_placements(
+            (tensor,),
+            dp=1,
+            pp_owner=owner,
+            ep=1,
+            tp=target_tp,
+            tp_dim=0,
+        ),
+        address_base=0x200000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert plan.total_bytes == prod(tensor.global_shape) * tensor.itemsize
+    assert_plan_copies_logical_contents(plan, sources, targets)
+
+
+def test_serialized_block_fp8_weight_and_scale_reshard_together() -> None:
+    weight = TensorDescriptor(
+        tensor_id="layers.1.mlp.gate_proj.weight",
+        global_shape=(1024, 128),
+        dtype="float8_e4m3fn",
+        itemsize=1,
+        shard_dims=(0,),
+        layer_id=1,
+        expert_id=None,
+        layout_fingerprint=(
+            "sglang:qwen3.5:gate-up:v1|serialized-block-fp8:e4m3fn:128x128:weight:v1"
+        ),
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    scale = TensorDescriptor(
+        tensor_id="layers.1.mlp.gate_proj.weight_scale_inv",
+        global_shape=(8, 1),
+        dtype="float32",
+        itemsize=4,
+        shard_dims=(0,),
+        layer_id=1,
+        expert_id=None,
+        layout_fingerprint=(
+            "sglang:qwen3.5:gate-up:v1|serialized-block-fp8:"
+            "fp32-inverse-scale:128x128:v1"
+        ),
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    tensors = (weight, scale)
+    owners = {tensor.tensor_id: 0 for tensor in tensors}
+    sources = build_manifests(
+        "source",
+        ep_tp_placements(
+            tensors,
+            dp=1,
+            pp_owner=owners,
+            ep=1,
+            tp=4,
+            tp_dim=0,
+        ),
+        address_base=0x100000,
+    )
+    targets = build_manifests(
+        "target",
+        ep_tp_placements(
+            tensors,
+            dp=1,
+            pp_owner=owners,
+            ep=1,
+            tp=8,
+            tp_dim=0,
+        ),
+        address_base=0x200000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert {operation.tensor_id for operation in plan.operations} == {
+        weight.tensor_id,
+        scale.tensor_id,
+    }
+    assert plan.total_bytes == sum(
+        fragment.nbytes for manifest in targets for fragment in manifest.fragments
+    )
+    assert_plan_copies_logical_contents(plan, sources, targets)
+
+
+def fused_moe_fp8_manifests(
+    side: str,
+    *,
+    ep: int,
+    tp: int,
+    pp: int,
+    up_first: bool,
+    address_base: int,
+) -> RuntimeInputs:
+    weight_shape = (4, 256, 128)
+    scale_shape = (4, 2, 1)
+    descriptors = {}
+    for component in ("gate_proj", "up_proj"):
+        descriptors[f"{component}.weight"] = TensorDescriptor(
+            tensor_id=f"layers.0.mlp.experts.{component}.weight",
+            global_shape=weight_shape,
+            dtype="float8_e4m3fn",
+            itemsize=1,
+            layer_id=0,
+            layout_fingerprint=(
+                "sglang:qwen3.5:moe-w13:v1|serialized-block-fp8:"
+                "e4m3fn:128x128:weight:v1"
+            ),
+            shard_dims=(0, 1),
+            parallel_axes=(
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="ep", dim=0),
+                SplitAxis(kind="tp", dim=1),
+            ),
+        )
+        descriptors[f"{component}.scale"] = TensorDescriptor(
+            tensor_id=f"layers.0.mlp.experts.{component}.weight_scale_inv",
+            global_shape=scale_shape,
+            dtype="float32",
+            itemsize=4,
+            layer_id=0,
+            layout_fingerprint=(
+                "sglang:qwen3.5:moe-w13:v1|serialized-block-fp8:"
+                "fp32-inverse-scale:128x128:v1"
+            ),
+            shard_dims=(0, 1),
+            parallel_axes=(
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="ep", dim=0),
+                SplitAxis(kind="tp", dim=1),
+            ),
+        )
+
+    local_experts = weight_shape[0] // ep
+    local_intermediate = weight_shape[1] // tp
+    local_scale_intermediate = scale_shape[1] // tp
+    component_order = (
+        ("up_proj", "gate_proj")
+        if up_first
+        else (
+            "gate_proj",
+            "up_proj",
+        )
+    )
+    groups = []
+    for ep_rank, tp_rank in product(range(ep), range(tp)):
+        rank = ParallelRank(pp=pp, ep=ep_rank, tp=tp_rank)
+        worker_id = f"{side}-p{pp}-e{ep_rank}-t{tp_rank}"
+        rank_index = ep_rank * tp + tp_rank
+        weight_base = address_base + rank_index * 0x1000000
+        scale_base = weight_base + 0x800000
+        weight_component_bytes = local_intermediate * weight_shape[2]
+        scale_component_bytes = local_scale_intermediate * scale_shape[2] * 4
+        placement_fragments = []
+        binding_fragments = []
+        for local_expert in range(local_experts):
+            expert_id = ep_rank * local_experts + local_expert
+            for component_index, component in enumerate(component_order):
+                weight = descriptors[f"{component}.weight"]
+                scale = descriptors[f"{component}.scale"]
+                physical_component = (
+                    local_expert * len(component_order) + component_index
+                )
+                weight_fragment_id = f"{worker_id}-expert{expert_id}-{component}-weight"
+                scale_fragment_id = f"{worker_id}-expert{expert_id}-{component}-scale"
+                placement_fragments.extend(
+                    (
+                        PlacementFragment(
+                            placement_fragment_id=f"{weight_fragment_id}-placement",
+                            tensor_id=weight.tensor_id,
+                            global_offset=(
+                                expert_id,
+                                tp_rank * local_intermediate,
+                                0,
+                            ),
+                            local_shape=(1, local_intermediate, weight_shape[2]),
+                            nbytes=weight_component_bytes,
+                            rank=rank,
+                        ),
+                        PlacementFragment(
+                            placement_fragment_id=f"{scale_fragment_id}-placement",
+                            tensor_id=scale.tensor_id,
+                            global_offset=(
+                                expert_id,
+                                tp_rank * local_scale_intermediate,
+                                0,
+                            ),
+                            local_shape=(
+                                1,
+                                local_scale_intermediate,
+                                scale_shape[2],
+                            ),
+                            nbytes=scale_component_bytes,
+                            rank=rank,
+                        ),
+                    )
+                )
+                binding_fragments.extend(
+                    (
+                        RuntimeBindingFragment(
+                            placement_fragment_id=f"{weight_fragment_id}-placement",
+                            fragment_id=weight_fragment_id,
+                            address=(
+                                weight_base
+                                + physical_component * weight_component_bytes
+                            ),
+                            nbytes=weight_component_bytes,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=weight.itemsize,
+                            local_shape=(
+                                1,
+                                local_intermediate,
+                                weight_shape[2],
+                            ),
+                            strides_bytes=_canonical_strides_bytes(
+                                (1, local_intermediate, weight_shape[2]),
+                                weight.itemsize,
+                            ),
+                            storage_address=(
+                                weight_base
+                                + physical_component * weight_component_bytes
+                            ),
+                            storage_nbytes=weight_component_bytes,
+                            storage_offset_bytes=0,
+                        ),
+                        RuntimeBindingFragment(
+                            placement_fragment_id=f"{scale_fragment_id}-placement",
+                            fragment_id=scale_fragment_id,
+                            address=(
+                                scale_base + physical_component * scale_component_bytes
+                            ),
+                            nbytes=scale_component_bytes,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=scale.itemsize,
+                            local_shape=(
+                                1,
+                                local_scale_intermediate,
+                                scale_shape[2],
+                            ),
+                            strides_bytes=_canonical_strides_bytes(
+                                (1, local_scale_intermediate, scale_shape[2]),
+                                scale.itemsize,
+                            ),
+                            storage_address=(
+                                scale_base + physical_component * scale_component_bytes
+                            ),
+                            storage_nbytes=scale_component_bytes,
+                            storage_offset_bytes=0,
+                        ),
+                    )
+                )
+        groups.append((worker_id, tuple(placement_fragments), tuple(binding_fragments)))
+    return runtime_inputs_from_groups(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id=side,
+        tensors=tuple(descriptors.values()),
+        groups=groups,
+    )
+
+
+def test_fp8_w31_to_w13_reshard_preserves_component_identity_and_bytes() -> None:
+    sources = fused_moe_fp8_manifests(
+        "source",
+        ep=2,
+        tp=2,
+        pp=0,
+        up_first=True,
+        address_base=0x10000000,
+    )
+    targets = fused_moe_fp8_manifests(
+        "target",
+        ep=4,
+        tp=1,
+        pp=1,
+        up_first=False,
+        address_base=0x40000000,
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    source_fragments = {
+        fragment.fragment_id: fragment
+        for binding in sources.bindings
+        for fragment in binding.fragments
+    }
+    target_fragments = {
+        fragment.fragment_id: fragment
+        for binding in targets.bindings
+        for fragment in binding.fragments
+    }
+    assert (
+        source_fragments["source-p0-e0-t0-expert0-up_proj-weight"].address
+        < source_fragments["source-p0-e0-t0-expert0-gate_proj-weight"].address
+    )
+    assert (
+        target_fragments["target-p1-e0-t0-expert0-gate_proj-weight"].address
+        < target_fragments["target-p1-e0-t0-expert0-up_proj-weight"].address
+    )
+    assert (
+        source_fragments["source-p0-e0-t0-expert0-up_proj-scale"].address
+        < source_fragments["source-p0-e0-t0-expert0-gate_proj-scale"].address
+    )
+    assert (
+        target_fragments["target-p1-e0-t0-expert0-gate_proj-scale"].address
+        < target_fragments["target-p1-e0-t0-expert0-up_proj-scale"].address
+    )
+    assert {operation.tensor_id for operation in plan.operations} == {
+        "layers.0.mlp.experts.gate_proj.weight",
+        "layers.0.mlp.experts.gate_proj.weight_scale_inv",
+        "layers.0.mlp.experts.up_proj.weight",
+        "layers.0.mlp.experts.up_proj.weight_scale_inv",
+    }
+    assert {(route.source_pp, route.target_pp) for route in plan.pipeline_routes} == {
+        (0, 1)
+    }
+    assert plan.total_bytes == sum(
+        fragment.nbytes for manifest in targets for fragment in manifest.fragments
+    )
+    assert len(plan.operations) == 32
+    assert (
+        sum(
+            1
+            for operation in plan.operations
+            for _ in operation.iter_segments(max_segments=operation.segment_count)
+        )
+        == 32
+    )
+    assert_plan_copies_logical_contents(plan, sources, targets)
diff --git a/mooncake-reshard/tests/model_weight_placement_binding/__init__.py b/mooncake-reshard/tests/model_weight_placement_binding/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/mooncake-reshard/tests/model_weight_placement_binding/helpers.py b/mooncake-reshard/tests/model_weight_placement_binding/helpers.py
new file mode 100644
index 0000000000..abb626f75f
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_placement_binding/helpers.py
@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    SplitAxis,
+    RuntimeBindingFragment,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+    TensorDescriptor,
+)
+from model_weight_planner.helpers import global_placement_from_fragments
+
+
+MODEL_ID = "model"
+REVISION = "revision"
+TARGET_PARTICIPANT_ID = "target-tp1"
+
+
+def descriptor(
+    *,
+    tensor_id: str = "layers.0.weight",
+    global_shape: tuple[int, ...] = (8,),
+    shard_dims: tuple[int, ...] = (0,),
+    layer_id: int | None = 0,
+    expert_id: int | None = None,
+) -> TensorDescriptor:
+    parallel_axes = tuple(
+        [ReplicatedAxis(kind="dp"), OwnershipAxis(kind="pp")]
+        + ([OwnershipAxis(kind="ep")] if expert_id is not None else [])
+        + [SplitAxis(kind="tp", dim=dim) for dim in shard_dims]
+    )
+    return TensorDescriptor(
+        tensor_id=tensor_id,
+        global_shape=global_shape,
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=shard_dims,
+        layer_id=layer_id,
+        expert_id=expert_id,
+        layout_fingerprint="test:logical-box:v2",
+        parallel_axes=parallel_axes,
+    )
+
+
+def source_placement(
+    *,
+    fragment_id: str = "source-placement-fragment",
+) -> WeightPlacementManifest:
+    tensor = descriptor()
+    fragment = PlacementFragment(
+        placement_fragment_id=fragment_id,
+        tensor_id=tensor.tensor_id,
+        global_offset=(0,),
+        local_shape=(8,),
+        nbytes=8,
+        rank=ParallelRank(),
+    )
+    return global_placement_from_fragments(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id="source",
+        tensors=(tensor,),
+        fragments=(fragment,),
+        participant_ids={fragment.rank: "source-dp0"},
+    )
+
+
+def replicated_source_placement() -> WeightPlacementManifest:
+    tensor = descriptor()
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"source-dp{dp}-fragment",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=(8,),
+            nbytes=8,
+            rank=ParallelRank(dp=dp),
+        )
+        for dp in range(2)
+    )
+    return global_placement_from_fragments(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id="source-replicated",
+        tensors=(tensor,),
+        fragments=fragments,
+        participant_ids={
+            fragment.rank: f"source-dp{fragment.rank.dp}" for fragment in fragments
+        },
+    )
+
+
+def source_binding(
+    *,
+    placement: WeightPlacementManifest | None = None,
+    placement_id: str | None = None,
+    placement_fragment_id: str = "source-placement-fragment",
+    instance_id: str = "source-instance",
+    generation: int = 3,
+    lease_id: str = "source-lease",
+    address: int = 0x1000,
+    nbytes: int = 8,
+    worker_id: str = "source-worker",
+    endpoint: str = "source-endpoint",
+) -> WeightRuntimeBindingManifest:
+    placement = placement or source_placement(
+        fragment_id=placement_fragment_id,
+    )
+    participant_id = next(
+        part.participant_id
+        for part in placement.parts
+        if any(
+            fragment.placement_fragment_id == placement_fragment_id
+            for fragment in part.fragments
+        )
+    )
+    return WeightRuntimeBindingManifest(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_id=placement_id or placement.placement_id,
+        placement_digest=placement.digest,
+        instance_id=instance_id,
+        participant_id=participant_id,
+        generation=generation,
+        lease_id=lease_id,
+        fragments=(
+            RuntimeBindingFragment(
+                placement_fragment_id=placement_fragment_id,
+                fragment_id=f"{instance_id}-fragment",
+                address=address,
+                nbytes=nbytes,
+                worker_id=worker_id,
+                endpoint=endpoint,
+                device="cuda:0",
+                itemsize=1,
+                local_shape=next(
+                    fragment.local_shape
+                    for fragment in placement.fragments
+                    if fragment.placement_fragment_id == placement_fragment_id
+                ),
+                strides_bytes=(1,),
+                storage_address=address,
+                storage_nbytes=nbytes,
+                storage_offset_bytes=0,
+            ),
+        ),
+    )
+
+
+def target_placement(
+    *,
+    fragment_id: str = "placement-fragment",
+) -> WeightPlacementManifest:
+    tensor = descriptor()
+    fragments = (
+        PlacementFragment(
+            placement_fragment_id="target-complement-fragment",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=ParallelRank(tp=0),
+        ),
+        PlacementFragment(
+            placement_fragment_id=fragment_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(4,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=ParallelRank(tp=1),
+        ),
+    )
+    return global_placement_from_fragments(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id="target",
+        tensors=(tensor,),
+        fragments=fragments,
+        participant_ids={
+            ParallelRank(tp=0): "target-tp0",
+            ParallelRank(tp=1): TARGET_PARTICIPANT_ID,
+        },
+    )
+
+
+def target_binding(
+    *,
+    placement: WeightPlacementManifest | None = None,
+    placement_id: str | None = None,
+    placement_fragment_id: str = "placement-fragment",
+    nbytes: int = 4,
+) -> WeightRuntimeBindingManifest:
+    placement = placement or target_placement(fragment_id=placement_fragment_id)
+    return WeightRuntimeBindingManifest(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_id=placement_id or placement.placement_id,
+        placement_digest=placement.digest,
+        instance_id="target-instance",
+        participant_id=TARGET_PARTICIPANT_ID,
+        generation=7,
+        lease_id="target-lease",
+        fragments=(
+            RuntimeBindingFragment(
+                placement_fragment_id=placement_fragment_id,
+                fragment_id="target-runtime-fragment",
+                address=0x9000,
+                nbytes=nbytes,
+                worker_id="target-worker",
+                endpoint="target-endpoint",
+                device="cuda:0",
+                itemsize=1,
+                local_shape=(4,),
+                strides_bytes=(1,),
+                storage_address=0x9000,
+                storage_nbytes=nbytes,
+                storage_offset_bytes=0,
+            ),
+        ),
+    )
+
+
+def split_target_placement() -> WeightPlacementManifest:
+    tensor = descriptor()
+    fragments = (
+        PlacementFragment(
+            placement_fragment_id="placement-left",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=ParallelRank(),
+        ),
+        PlacementFragment(
+            placement_fragment_id="placement-right",
+            tensor_id=tensor.tensor_id,
+            global_offset=(4,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=ParallelRank(),
+        ),
+    )
+    return global_placement_from_fragments(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_set_id="target-split",
+        tensors=(tensor,),
+        fragments=fragments,
+        participant_ids={ParallelRank(): "target-split"},
+    )
+
+
+def split_target_binding(
+    *,
+    right_address: int,
+    right_worker_id: str = "target-worker",
+    right_endpoint: str = "target-endpoint",
+) -> WeightRuntimeBindingManifest:
+    placement = split_target_placement()
+    return WeightRuntimeBindingManifest(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        placement_id=placement.placement_id,
+        placement_digest=placement.digest,
+        instance_id="target-instance",
+        participant_id="target-split",
+        generation=7,
+        lease_id="target-lease",
+        fragments=(
+            RuntimeBindingFragment(
+                placement_fragment_id="placement-left",
+                fragment_id="runtime-left",
+                address=0x9000,
+                nbytes=4,
+                worker_id="target-worker",
+                endpoint="target-endpoint",
+                device="cuda:0",
+                itemsize=1,
+                local_shape=(4,),
+                strides_bytes=(1,),
+                storage_address=0x9000,
+                storage_nbytes=4,
+                storage_offset_bytes=0,
+            ),
+            RuntimeBindingFragment(
+                placement_fragment_id="placement-right",
+                fragment_id="runtime-right",
+                address=right_address,
+                nbytes=4,
+                worker_id=right_worker_id,
+                endpoint=right_endpoint,
+                device="cuda:0",
+                itemsize=1,
+                local_shape=(4,),
+                strides_bytes=(1,),
+                storage_address=right_address,
+                storage_nbytes=4,
+                storage_offset_bytes=0,
+            ),
+        ),
+    )
diff --git a/mooncake-reshard/tests/model_weight_placement_binding/test_global_planner_api.py b/mooncake-reshard/tests/model_weight_placement_binding/test_global_planner_api.py
new file mode 100644
index 0000000000..b5e55d2f3f
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_placement_binding/test_global_planner_api.py
@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    TensorDescriptor,
+    SplitAxis,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    plan_placement_transfer,
+    plan_stored_transfer_to_target_placement,
+)
+from mooncake.reshard.weight.storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredWeightManifest,
+)
+
+
+def _placement(
+    tp_size: int,
+    placement_set_id: str,
+    *,
+    canonical_fragment_ids: bool = False,
+) -> WeightPlacementManifest:
+    participants = tuple(
+        TopologyParticipant(f"{placement_set_id}-worker-{rank}", ParallelRank(tp=rank))
+        for rank in range(tp_size)
+    )
+    topology = ParallelTopology(
+        tp_size=tp_size,
+        pp_size=1,
+        ep_size=1,
+        dp_size=1,
+        participants=participants,
+    )
+    tensor = TensorDescriptor(
+        tensor_id="layers.0.weight",
+        global_shape=(8,),
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=(0,),
+        layout_fingerprint="global-planner:uint8:v1",
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    extent = 8 // tp_size
+    parts = tuple(
+        WeightPlacementPart(
+            resource_id="model",
+            revision="revision",
+            weight_generation=9,
+            placement_set_id=placement_set_id,
+            topology_id=topology.topology_id,
+            participant_id=participant.participant_id,
+            rank=participant.rank,
+            tensors=(tensor,),
+            fragments=(
+                PlacementFragment(
+                    placement_fragment_id=(
+                        None
+                        if canonical_fragment_ids
+                        else f"{placement_set_id}-fragment-{participant.rank.tp}"
+                    ),
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(participant.rank.tp * extent,),
+                    local_shape=(extent,),
+                    nbytes=extent,
+                    rank=participant.rank,
+                ),
+            ),
+        )
+        for participant in participants
+    )
+    return WeightPlacementManifest(
+        resource_id="model",
+        revision="revision",
+        weight_generation=9,
+        placement_set_id=placement_set_id,
+        topology=topology,
+        parts=parts,
+    )
+
+
+def test_planner_accepts_one_complete_source_and_target_manifest() -> None:
+    source = _placement(4, "source")
+    target = _placement(8, "target")
+
+    plan = plan_placement_transfer(source, target)
+
+    assert len(plan.operations) == 8
+    assert {item.placement_id for item in plan.source_executors} == {
+        source.placement_id
+    }
+    assert {item.placement_id for item in plan.target_executors} == {
+        target.placement_id
+    }
+
+
+def test_planner_accepts_canonical_fragment_ids_generated_by_manifest() -> None:
+    source = _placement(4, "source", canonical_fragment_ids=True)
+    target = _placement(8, "target", canonical_fragment_ids=True)
+
+    plan = plan_placement_transfer(source, target)
+
+    assert len(plan.operations) == 8
+    assert all(
+        fragment.placement_fragment_id.startswith("sha256:")
+        for fragment in source.fragments + target.fragments
+    )
+
+
+def test_logical_plan_rejects_forged_placement_source_provenance() -> None:
+    source = _placement(2, "source")
+    target = _placement(1, "target")
+    plan = plan_placement_transfer(source, target)
+
+    forged_source = replace(plan.operations[0].source, rank=ParallelRank(pp=99))
+    forged_operation = replace(plan.operations[0], source=forged_source)
+
+    with pytest.raises(
+        ValueError,
+        match="source placement fragment snapshots differ",
+    ):
+        replace(plan, operations=(forged_operation, *plan.operations[1:]))
+
+    with pytest.raises(ValueError, match="no source executor metadata"):
+        replace(plan, source_executors=())
+
+    with pytest.raises(ValueError, match="source tensor catalog differs"):
+        replace(plan, source_tensors=())
+
+    with pytest.raises(ValueError, match="target tensor catalog differs"):
+        replace(plan, target_tensors=())
+
+
+def _stored_source(tensor: TensorDescriptor) -> StoredWeightManifest:
+    group_id = "weights/default/model/revision/9"
+    return StoredWeightManifest(
+        namespace="default",
+        resource_id="model",
+        revision="revision",
+        weight_generation=9,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        created_at="2026-08-19T00:00:00Z",
+        tensors=(tensor,),
+        fragments=(
+            StoredFragmentSnapshot(
+                fragment_id="store-source-full",
+                tensor_id=tensor.tensor_id,
+                global_offset=(0,),
+                local_shape=tensor.global_shape,
+                object_key=f"{group_id}/payload/0",
+                object_offset=0,
+                nbytes=8,
+            ),
+        ),
+    )
+
+
+def _two_tensor_placement(placement_set_id: str) -> WeightPlacementManifest:
+    participant = TopologyParticipant(f"{placement_set_id}-worker-0", ParallelRank())
+    topology = ParallelTopology(
+        tp_size=1,
+        pp_size=1,
+        ep_size=1,
+        dp_size=1,
+        participants=(participant,),
+    )
+    tensors = tuple(
+        TensorDescriptor(
+            tensor_id=tensor_id,
+            global_shape=(8,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(0,),
+            layout_fingerprint="global-planner:uint8:v1",
+            parallel_axes=(SplitAxis(kind="tp", dim=0),),
+        )
+        for tensor_id in ("layers.a.weight", "layers.b.weight")
+    )
+    return WeightPlacementManifest(
+        resource_id="model",
+        revision="revision",
+        weight_generation=9,
+        placement_set_id=placement_set_id,
+        topology=topology,
+        parts=(
+            WeightPlacementPart(
+                resource_id="model",
+                revision="revision",
+                weight_generation=9,
+                placement_set_id=placement_set_id,
+                topology_id=topology.topology_id,
+                participant_id=participant.participant_id,
+                rank=participant.rank,
+                tensors=tensors,
+                fragments=tuple(
+                    PlacementFragment(
+                        placement_fragment_id=f"{placement_set_id}-{tensor.tensor_id}",
+                        tensor_id=tensor.tensor_id,
+                        global_offset=(0,),
+                        local_shape=tensor.global_shape,
+                        nbytes=8,
+                        rank=participant.rank,
+                    )
+                    for tensor in tensors
+                ),
+            ),
+        ),
+    )
+
+
+def test_store_backed_planner_attests_selected_source_fragments() -> None:
+    target = _placement(8, "target")
+    source = _stored_source(target.tensors[0])
+
+    plan = plan_stored_transfer_to_target_placement(source, target)
+
+    assert len(plan.operations) == 8
+    assert plan.source_manifest == source
+    assert plan.source_manifest_identity == source.manifest_identity
+    assert {operation.source for operation in plan.operations} == {source.fragments[0]}
+
+    forged_fragment = replace(
+        source.fragments[0],
+        object_key="another-tenant/private-object",
+    )
+    forged_operation = replace(plan.operations[0], source=forged_fragment)
+    with pytest.raises(
+        ValueError,
+        match="source manifest fragment snapshots differ",
+    ):
+        replace(plan, operations=(forged_operation, *plan.operations[1:]))
+
+    with pytest.raises(ValueError, match="weight_generation differ"):
+        plan_stored_transfer_to_target_placement(
+            replace(source, weight_generation=10),
+            target,
+        )
+
+
+def test_store_backed_planner_accepts_reordered_tensor_catalog() -> None:
+    target = _two_tensor_placement("target")
+    tensors = target.tensors
+    group_id = "weights/default/model/revision/9"
+    source = StoredWeightManifest(
+        namespace="default",
+        resource_id="model",
+        revision="revision",
+        weight_generation=9,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        created_at="2026-08-20T00:00:00Z",
+        tensors=(tensors[1], tensors[0]),
+        fragments=tuple(
+            StoredFragmentSnapshot(
+                fragment_id=f"store-{tensor.tensor_id}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(0,),
+                local_shape=tensor.global_shape,
+                object_key=f"{group_id}/payload/{index}",
+                object_offset=0,
+                nbytes=8,
+            )
+            for index, tensor in enumerate((tensors[1], tensors[0]))
+        ),
+    )
+
+    plan = plan_stored_transfer_to_target_placement(source, target)
+
+    assert plan.source_manifest == source
+    assert plan.source_tensors == target.tensors
+    assert len(plan.operations) == 2
diff --git a/mooncake-reshard/tests/model_weight_placement_binding/test_planner_binding.py b/mooncake-reshard/tests/model_weight_placement_binding/test_planner_binding.py
new file mode 100644
index 0000000000..d13469944d
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_placement_binding/test_planner_binding.py
@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import json
+import unittest
+from dataclasses import asdict, replace
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+)
+
+from model_weight_planner.helpers import global_placement_from_fragments
+
+from .helpers import (
+    TARGET_PARTICIPANT_ID,
+    replicated_source_placement,
+    source_binding,
+    source_placement,
+    target_binding,
+    target_placement,
+)
+
+
+class PlacementPlannerTest(unittest.TestCase):
+    def test_plans_without_addresses_then_binds_both_sides(self) -> None:
+        source = source_placement()
+        target = target_placement()
+
+        logical = plan_placement_transfer_to_local_target(
+            source,
+            target,
+            TARGET_PARTICIPANT_ID,
+        )
+
+        encoded = json.dumps(asdict(logical), sort_keys=True)
+        self.assertEqual(logical.source_placement_id, source.placement_id)
+        self.assertEqual(logical.target_placement_id, target.placement_id)
+        self.assertIsInstance(logical.operations[0].source, PlacementFragment)
+        self.assertIsInstance(logical.operations[0].target, PlacementFragment)
+        for physical_field in (
+            "address",
+            "endpoint",
+            "worker_id",
+            "instance_id",
+            "lease",
+            "owner",
+        ):
+            self.assertNotIn(physical_field, encoded)
+
+        bound = bind_logical_transfer_plan(
+            logical,
+            (target_binding(),),
+            source_bindings=(source_binding(),),
+        )
+
+        self.assertEqual(bound.operations[0].source.address, 0x1000)
+        self.assertEqual(bound.operations[0].target.address, 0x9000)
+        self.assertEqual(bound.operations[0].source.rank.tp, 0)
+        self.assertEqual(bound.operations[0].target.rank.tp, 1)
+        self.assertEqual(
+            bound.source_executors[0].fragment_snapshots[0].lease_generation,
+            3,
+        )
+
+    def test_source_binding_is_required_and_validated_fail_closed(self) -> None:
+        logical = plan_placement_transfer_to_local_target(
+            source_placement(),
+            target_placement(),
+            TARGET_PARTICIPANT_ID,
+        )
+
+        with self.assertRaisesRegex(ValueError, "requires source runtime bindings"):
+            bind_logical_transfer_plan(logical, (target_binding(),))
+        with self.assertRaisesRegex(ValueError, "source placement IDs differ"):
+            bind_logical_transfer_plan(
+                logical,
+                (target_binding(),),
+                source_bindings=(target_binding(),),
+            )
+        with self.assertRaisesRegex(ValueError, "byte size"):
+            bind_logical_transfer_plan(
+                logical,
+                (target_binding(),),
+                source_bindings=(source_binding(nbytes=4),),
+            )
+
+    def test_bind_rejects_runtime_stride_evidence_that_differs_from_placement(
+        self,
+    ) -> None:
+        logical = plan_placement_transfer_to_local_target(
+            source_placement(),
+            target_placement(),
+            TARGET_PARTICIPANT_ID,
+        )
+        binding = target_binding()
+        invalid = replace(
+            binding,
+            fragments=(replace(binding.fragments[0], strides_bytes=(2,)),),
+        )
+
+        with self.assertRaisesRegex(ValueError, "canonical contiguous view"):
+            bind_logical_transfer_plan(
+                logical,
+                (invalid,),
+                source_bindings=(source_binding(),),
+            )
+
+    def test_bind_rejects_runtime_binding_for_empty_participant(self) -> None:
+        base = target_placement()
+        topology = ParallelTopology(
+            tp_size=2,
+            pp_size=2,
+            ep_size=1,
+            dp_size=1,
+            participants=base.topology.participants
+            + (
+                TopologyParticipant(
+                    participant_id="target-empty-pp1",
+                    rank=ParallelRank(pp=1),
+                ),
+            ),
+        )
+        target = WeightPlacementManifest.from_fragments(
+            resource_id=base.resource_id,
+            revision=base.revision,
+            weight_generation=base.weight_generation,
+            placement_set_id=base.placement_set_id,
+            topology=topology,
+            tensors=base.tensors,
+            fragments=base.fragments,
+        )
+        logical = plan_placement_transfer_to_local_target(
+            source_placement(),
+            target,
+            TARGET_PARTICIPANT_ID,
+        )
+        empty_binding = WeightRuntimeBindingManifest(
+            resource_id=target.resource_id,
+            revision=target.revision,
+            placement_id=target.placement_id,
+            placement_digest=target.digest,
+            instance_id="target-empty-instance",
+            participant_id="target-empty-pp1",
+            generation=7,
+            lease_id="target-empty-lease",
+            fragments=(),
+        )
+
+        with self.assertRaisesRegex(
+            ValueError,
+            "target runtime binding participants differ",
+        ):
+            bind_logical_transfer_plan(
+                logical,
+                (target_binding(placement=target), empty_binding),
+                source_bindings=(source_binding(),),
+            )
+
+    def test_source_binding_tracks_independent_dp_participants(self) -> None:
+        source = replicated_source_placement()
+        logical = plan_placement_transfer_to_local_target(
+            source,
+            target_placement(),
+            TARGET_PARTICIPANT_ID,
+        )
+
+        selected = source_binding(
+            placement=source,
+            placement_fragment_id="source-dp0-fragment",
+            instance_id="source-dp0-instance",
+            generation=3,
+            address=0x1000,
+        )
+        unselected = source_binding(
+            placement=source,
+            placement_fragment_id="source-dp1-fragment",
+            instance_id="source-dp1-instance",
+            generation=4,
+            address=0x2000,
+        )
+
+        plan = bind_logical_transfer_plan(
+            logical,
+            (target_binding(),),
+            source_bindings=(selected, unselected),
+        )
+        self.assertEqual(
+            {
+                executor.instance_id: executor.fragment_snapshots[0].lease_generation
+                for executor in plan.source_executors
+            },
+            {"source-dp0-instance": 3},
+        )
+
+    def test_partial_source_bindings_reject_cross_participant_overlap(self) -> None:
+        tensor = source_placement().tensors[0]
+        source_fragments = tuple(
+            PlacementFragment(
+                placement_fragment_id=f"source-dp{dp}-tp{tp}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(tp * 4,),
+                local_shape=(4,),
+                nbytes=4,
+                rank=ParallelRank(dp=dp, tp=tp),
+            )
+            for dp in range(2)
+            for tp in range(2)
+        )
+        source = global_placement_from_fragments(
+            resource_id=source_placement().resource_id,
+            revision=source_placement().revision,
+            placement_set_id="source-two-dp-two-tp",
+            tensors=(tensor,),
+            fragments=source_fragments,
+            participant_ids={
+                fragment.rank: (f"source-dp{fragment.rank.dp}-tp{fragment.rank.tp}")
+                for fragment in source_fragments
+            },
+        )
+        target = target_placement()
+        logical = plan_placement_transfer(source, target)
+        selected_source_ids = {
+            executor.participant_id for executor in logical.source_executors
+        }
+        self.assertEqual(selected_source_ids, {"source-dp0-tp0", "source-dp0-tp1"})
+        source_bindings = []
+        for tp in range(2):
+            binding = source_binding(
+                placement=source,
+                placement_fragment_id=f"source-dp0-tp{tp}",
+                instance_id="shared-source-instance",
+                lease_id=f"source-tp{tp}-lease",
+                address=0x1000,
+                nbytes=4,
+                worker_id="shared-source-worker",
+                endpoint="shared-source-endpoint",
+            )
+            source_bindings.append(
+                replace(
+                    binding,
+                    fragments=(
+                        replace(
+                            binding.fragments[0],
+                            fragment_id=f"source-runtime-tp{tp}",
+                        ),
+                    ),
+                )
+            )
+        target_bindings = (
+            source_binding(
+                placement=target,
+                placement_fragment_id="target-complement-fragment",
+                instance_id="target-tp0-instance",
+                lease_id="target-tp0-lease",
+                address=0x8000,
+                nbytes=4,
+            ),
+            target_binding(placement=target),
+        )
+
+        with self.assertRaisesRegex(ValueError, "address ranges overlap"):
+            bind_logical_transfer_plan(
+                logical,
+                target_bindings,
+                source_bindings=tuple(source_bindings),
+            )
+
+    def test_source_address_rebinds_without_replanning(self) -> None:
+        logical = plan_placement_transfer_to_local_target(
+            source_placement(),
+            target_placement(),
+            TARGET_PARTICIPANT_ID,
+        )
+
+        first = bind_logical_transfer_plan(
+            logical,
+            (target_binding(),),
+            source_bindings=(source_binding(address=0x1000),),
+        )
+        second = bind_logical_transfer_plan(
+            logical,
+            (target_binding(),),
+            source_bindings=(
+                source_binding(
+                    instance_id="source-instance-2",
+                    generation=4,
+                    lease_id="source-lease-2",
+                    address=0x2000,
+                    worker_id="source-worker-2",
+                    endpoint="source-endpoint-2",
+                ),
+            ),
+        )
+
+        self.assertEqual(first.operations[0].source.address, 0x1000)
+        self.assertEqual(second.operations[0].source.address, 0x2000)
+        self.assertEqual(second.source_executors[0].instance_id, "source-instance-2")
+        self.assertEqual(second.source_executors[0].worker_id, "source-worker-2")
+        self.assertEqual(
+            first.operations[0].overlap_offset,
+            second.operations[0].overlap_offset,
+        )
+        self.assertEqual(
+            first.operations[0].overlap_shape,
+            second.operations[0].overlap_shape,
+        )
+
+    def test_rejects_binding_from_another_target_placement(self) -> None:
+        logical = plan_placement_transfer_to_local_target(
+            source_placement(),
+            target_placement(),
+            TARGET_PARTICIPANT_ID,
+        )
+        other_placement = target_placement(fragment_id="other-fragment")
+        other_binding = target_binding(
+            placement=other_placement,
+            placement_fragment_id="other-fragment",
+        )
+
+        with self.assertRaisesRegex(ValueError, "placement"):
+            bind_logical_transfer_plan(
+                logical,
+                (other_binding,),
+                source_bindings=(source_binding(),),
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-reshard/tests/model_weight_placement_binding/test_target_placement.py b/mooncake-reshard/tests/model_weight_placement_binding/test_target_placement.py
new file mode 100644
index 0000000000..85639cdd88
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_placement_binding/test_target_placement.py
@@ -0,0 +1,565 @@
+from __future__ import annotations
+
+import json
+import unittest
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    WeightRuntimeBindingManifest,
+    TensorDescriptor,
+    OwnershipAxis,
+    SplitAxis,
+    validate_runtime_binding,
+    weight_placement_from_json,
+    weight_placement_to_json,
+)
+from model_weight_planner.helpers import (
+    global_placement_from_fragments,
+)
+
+from .helpers import (
+    MODEL_ID,
+    REVISION,
+    descriptor,
+    split_target_binding,
+    split_target_placement,
+    target_binding,
+    target_placement,
+)
+
+
+def _contains_json_key(value, key: str) -> bool:
+    if isinstance(value, dict):
+        return key in value or any(
+            _contains_json_key(item, key) for item in value.values()
+        )
+    if isinstance(value, list):
+        return any(_contains_json_key(item, key) for item in value)
+    return False
+
+
+class TargetPlacementManifestTest(unittest.TestCase):
+    def test_json_round_trip_is_stable_and_contains_no_runtime_location(self) -> None:
+        placement = target_placement()
+
+        encoded = weight_placement_to_json(placement)
+        payload = json.loads(encoded)
+
+        self.assertEqual(weight_placement_from_json(encoded), placement)
+        self.assertEqual(
+            weight_placement_from_json(encoded).digest,
+            placement.digest,
+        )
+        self.assertNotIn("address", encoded)
+        self.assertNotIn("endpoint", encoded)
+        self.assertNotIn("worker_id", encoded)
+        self.assertNotIn("instance_id", encoded)
+        self.assertNotIn('"generation":', encoded)
+        self.assertNotIn("lease", encoded)
+        self.assertFalse(_contains_json_key(payload, "owner"))
+        self.assertNotIn("fragment_snapshots", encoded)
+        self.assertEqual(payload["placement_id"], placement.placement_id)
+
+    def test_json_round_trip_accepts_canonical_split_descriptor(self) -> None:
+        tensor = TensorDescriptor(
+            tensor_id="layers.0.single_axis.weight",
+            global_shape=(8,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(0,),
+            layout_fingerprint="test:partition-dim",
+            parallel_axes=(SplitAxis(kind="tp", dim=0),),
+        )
+        fragments = tuple(
+            PlacementFragment(
+                placement_fragment_id=f"single-axis-part-{tp}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(tp * 4,),
+                local_shape=(4,),
+                nbytes=4,
+                rank=ParallelRank(tp=tp),
+            )
+            for tp in range(2)
+        )
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="single-axis",
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+        self.assertEqual(
+            weight_placement_from_json(weight_placement_to_json(placement)),
+            placement,
+        )
+
+    def test_complete_placement_accepts_canonical_split_descriptor(self) -> None:
+        participants = tuple(
+            (f"runtime-tp{tp}", ParallelRank(tp=tp)) for tp in range(2)
+        )
+        tensor = TensorDescriptor(
+            tensor_id="layers.0.single_axis.weight",
+            global_shape=(8,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(0,),
+            layout_fingerprint="test:canonical-split",
+            parallel_axes=(SplitAxis(kind="tp", dim=0),),
+        )
+        fragments = tuple(
+            PlacementFragment(
+                placement_fragment_id=f"single-axis-runtime-{rank.tp}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(rank.tp * 4,),
+                local_shape=(4,),
+                nbytes=4,
+                rank=rank,
+            )
+            for _, rank in participants
+        )
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="runtime-single-axis",
+            tensors=(tensor,),
+            fragments=fragments,
+            participant_ids={
+                rank: participant_id for participant_id, rank in participants
+            },
+        )
+
+        self.assertEqual(placement.tensors[0].shard_dims, (0,))
+        self.assertEqual(
+            placement.tensors[0].parallel_axes,
+            (SplitAxis(kind="tp", dim=0),),
+        )
+
+    def test_binding_validates_without_combining_logical_and_physical_state(
+        self,
+    ) -> None:
+        placement = target_placement()
+        binding = target_binding()
+
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(binding.resource_id, MODEL_ID)
+        self.assertEqual(binding.revision, REVISION)
+        self.assertEqual(binding.instance_id, "target-instance")
+        self.assertEqual(binding.lease_id, "target-lease")
+        self.assertEqual(binding.placement_id, placement.placement_id)
+        self.assertEqual(binding.fragments[0].address, 0x9000)
+        self.assertEqual(binding.generation, 7)
+        self.assertEqual(
+            binding.fragments[0].placement_fragment_id,
+            "placement-fragment",
+        )
+        self.assertEqual(placement.fragments[0].rank, ParallelRank(tp=1))
+        self.assertEqual(placement.fragments[0].global_offset, (4,))
+        self.assertEqual(placement.fragments[0].aliases, ())
+        self.assertEqual(len(binding.fragments), 1)
+
+    def test_binding_rejects_overlapping_independent_runtime_ranges(self) -> None:
+        placement = split_target_placement()
+
+        for right_address in (0x9000, 0x9002):
+            with self.subTest(right_address=right_address):
+                with self.assertRaisesRegex(
+                    ValueError, "runtime (binding|manifest) address ranges overlap"
+                ):
+                    validate_runtime_binding(
+                        placement,
+                        split_target_binding(right_address=right_address),
+                    )
+
+    def test_binding_allows_exact_runtime_alias_ranges_declared_by_placement(
+        self,
+    ) -> None:
+        aliases = ("lm_head.weight", "model.embed_tokens.weight")
+        tensors = (
+            TensorDescriptor(
+                tensor_id=tensor_id,
+                global_shape=(4,),
+                dtype="uint8",
+                itemsize=1,
+                shard_dims=(),
+                layout_fingerprint="test:contiguous:v1",
+                parallel_axes=(),
+            )
+            for tensor_id in aliases
+        )
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="target-alias",
+            tensors=tuple(tensors),
+            fragments=tuple(
+                PlacementFragment(
+                    placement_fragment_id=f"placement-{tensor_id}",
+                    tensor_id=tensor_id,
+                    global_offset=(0,),
+                    local_shape=(4,),
+                    nbytes=4,
+                    rank=ParallelRank(),
+                    aliases=aliases,
+                )
+                for tensor_id in aliases
+            ),
+            participant_ids={ParallelRank(): "target-alias"},
+        )
+        binding = WeightRuntimeBindingManifest(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id="target-instance",
+            participant_id="target-alias",
+            generation=7,
+            lease_id="target-lease",
+            fragments=tuple(
+                RuntimeBindingFragment(
+                    placement_fragment_id=fragment.placement_fragment_id,
+                    fragment_id=f"runtime-{fragment.tensor_id}",
+                    address=0x9000,
+                    nbytes=4,
+                    worker_id="target-worker",
+                    endpoint="target-endpoint",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0x9000,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                )
+                for fragment in placement.fragments
+            ),
+        )
+
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(
+            tuple(fragment.address for fragment in binding.fragments),
+            (0x9000, 0x9000),
+        )
+        self.assertTrue(
+            all(fragment.aliases == aliases for fragment in placement.fragments)
+        )
+
+    def test_binding_rejects_partial_runtime_alias_overlap(self) -> None:
+        aliases = ("alias.a", "alias.b")
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="target-partial-alias",
+            tensors=tuple(
+                TensorDescriptor(
+                    tensor_id=tensor_id,
+                    global_shape=(4,),
+                    dtype="uint8",
+                    itemsize=1,
+                    shard_dims=(),
+                    layout_fingerprint="test:contiguous:v1",
+                    parallel_axes=(),
+                )
+                for tensor_id in aliases
+            ),
+            fragments=tuple(
+                PlacementFragment(
+                    placement_fragment_id=f"placement-{tensor_id}",
+                    tensor_id=tensor_id,
+                    global_offset=(0,),
+                    local_shape=(4,),
+                    nbytes=4,
+                    rank=ParallelRank(),
+                    aliases=aliases,
+                )
+                for tensor_id in aliases
+            ),
+            participant_ids={ParallelRank(): "target-partial-alias"},
+        )
+        binding = WeightRuntimeBindingManifest(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id="target-instance",
+            participant_id="target-partial-alias",
+            generation=7,
+            lease_id="target-lease",
+            fragments=(
+                RuntimeBindingFragment(
+                    placement_fragment_id="placement-alias.a",
+                    fragment_id="runtime-alias.a",
+                    address=0x9000,
+                    nbytes=4,
+                    worker_id="target-worker",
+                    endpoint="target-endpoint",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0x9000,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                ),
+                RuntimeBindingFragment(
+                    placement_fragment_id="placement-alias.b",
+                    fragment_id="runtime-alias.b",
+                    address=0x9002,
+                    nbytes=4,
+                    worker_id="target-worker",
+                    endpoint="target-endpoint",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0x9002,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                ),
+            ),
+        )
+
+        with self.assertRaisesRegex(
+            ValueError, "runtime (binding|manifest) address ranges overlap"
+        ):
+            validate_runtime_binding(placement, binding)
+
+    def test_binding_allows_adjacent_runtime_ranges(self) -> None:
+        placement = split_target_placement()
+        binding = split_target_binding(right_address=0x9004)
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(
+            tuple(fragment.address for fragment in binding.fragments),
+            (0x9000, 0x9004),
+        )
+
+    def test_binding_allows_same_address_on_different_workers(self) -> None:
+        placement = split_target_placement()
+        binding = split_target_binding(
+            right_address=0x9000,
+            right_worker_id="target-worker-1",
+        )
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(
+            tuple(fragment.address for fragment in binding.fragments),
+            (0x9000, 0x9000),
+        )
+
+    def test_binding_rejects_wrong_identity_and_fragment_sets(self) -> None:
+        placement = target_placement()
+
+        with self.assertRaisesRegex(ValueError, "placement_id"):
+            validate_runtime_binding(
+                placement,
+                target_binding(placement_id="different-placement"),
+            )
+        with self.assertRaisesRegex(ValueError, "unknown placement fragment"):
+            validate_runtime_binding(
+                placement,
+                target_binding(
+                    placement=placement,
+                    placement_fragment_id="unknown-fragment",
+                ),
+            )
+        with self.assertRaisesRegex(ValueError, "byte size"):
+            validate_runtime_binding(placement, target_binding(nbytes=8))
+
+    def test_binding_rejects_missing_or_duplicate_fragments(self) -> None:
+        placement = target_placement()
+        empty = WeightRuntimeBindingManifest(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id="target-instance",
+            participant_id="target-tp1",
+            generation=7,
+            lease_id="target-lease",
+            fragments=(),
+        )
+
+        with self.assertRaisesRegex(ValueError, "missing placement fragment"):
+            validate_runtime_binding(placement, empty)
+
+        fragment = target_binding().fragments[0]
+        with self.assertRaisesRegex(ValueError, "duplicate placement fragment"):
+            WeightRuntimeBindingManifest(
+                resource_id=MODEL_ID,
+                revision=REVISION,
+                placement_id=placement.placement_id,
+                placement_digest=placement.digest,
+                instance_id="target-instance",
+                participant_id="target-tp1",
+                generation=7,
+                lease_id="target-lease",
+                fragments=(fragment, fragment),
+            )
+
+    def test_binding_allows_one_rank_spanning_multiple_runtime_locations(self) -> None:
+        tensor = descriptor()
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="target-multi-location",
+            tensors=(tensor,),
+            fragments=(
+                PlacementFragment(
+                    placement_fragment_id="placement-left",
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(0,),
+                    local_shape=(4,),
+                    nbytes=4,
+                    rank=ParallelRank(tp=0),
+                ),
+                PlacementFragment(
+                    placement_fragment_id="placement-right",
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(4,),
+                    local_shape=(4,),
+                    nbytes=4,
+                    rank=ParallelRank(tp=0),
+                ),
+            ),
+            participant_ids={ParallelRank(): "target-multi-location"},
+        )
+        binding = WeightRuntimeBindingManifest(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id="target-instance",
+            participant_id="target-multi-location",
+            generation=7,
+            lease_id="target-lease",
+            fragments=(
+                RuntimeBindingFragment(
+                    placement_fragment_id="placement-left",
+                    fragment_id="runtime-left",
+                    address=0x9000,
+                    nbytes=4,
+                    worker_id="target-worker-0",
+                    endpoint="target-endpoint-0",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0x9000,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                ),
+                RuntimeBindingFragment(
+                    placement_fragment_id="placement-right",
+                    fragment_id="runtime-right",
+                    address=0xA000,
+                    nbytes=4,
+                    worker_id="target-worker-1",
+                    endpoint="target-endpoint-1",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0xA000,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                ),
+            ),
+        )
+
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(
+            tuple(fragment.worker_id for fragment in binding.fragments),
+            ("target-worker-0", "target-worker-1"),
+        )
+
+    def test_accepts_framework_adapted_canonical_split_manifests(self) -> None:
+        target_rank = ParallelRank(tp=1, pp=2, ep=3)
+        complement_rank = ParallelRank(tp=0, pp=2, ep=3)
+        tensor = TensorDescriptor(
+            tensor_id="layers.0.weight",
+            global_shape=(8,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(0,),
+            layer_id=0,
+            layout_fingerprint="test:logical-box:v2",
+            parallel_axes=(
+                OwnershipAxis(kind="pp"),
+                OwnershipAxis(kind="ep"),
+                SplitAxis(kind="tp", dim=0),
+            ),
+        )
+        target_fragment = PlacementFragment(
+            placement_fragment_id="sglang-placement-fragment",
+            tensor_id=tensor.tensor_id,
+            global_offset=(4,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=target_rank,
+        )
+        complement_fragment = PlacementFragment(
+            placement_fragment_id="sglang-complement-fragment",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=(4,),
+            nbytes=4,
+            rank=complement_rank,
+        )
+        placement = global_placement_from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_set_id="sglang-placement",
+            tensors=(tensor,),
+            fragments=(target_fragment, complement_fragment),
+            participant_ids={
+                target_rank: "sglang-target",
+                complement_rank: "sglang-complement",
+            },
+        )
+        binding = WeightRuntimeBindingManifest(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id="sglang-target",
+            participant_id="sglang-target",
+            generation=11,
+            lease_id="sglang-lease",
+            fragments=(
+                RuntimeBindingFragment(
+                    placement_fragment_id=target_fragment.placement_fragment_id,
+                    fragment_id="sglang-runtime-fragment",
+                    address=0xA000,
+                    nbytes=4,
+                    worker_id="sglang-worker",
+                    endpoint="sglang-endpoint",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=0xA000,
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                ),
+            ),
+        )
+        validate_runtime_binding(placement, binding)
+
+        self.assertEqual(binding.fragments[0].address, 0xA000)
+        actual_target_fragment = next(
+            fragment
+            for fragment in placement.fragments
+            if fragment.placement_fragment_id == "sglang-placement-fragment"
+        )
+        self.assertEqual(actual_target_fragment.rank, target_rank)
+        self.assertEqual(binding.generation, 11)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-reshard/tests/model_weight_planner/__init__.py b/mooncake-reshard/tests/model_weight_planner/__init__.py
new file mode 100644
index 0000000000..a8b9a010f1
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/__init__.py
@@ -0,0 +1 @@
+"""Model-weight planner tests organized by responsibility."""
diff --git a/mooncake-reshard/tests/model_weight_planner/helpers.py b/mooncake-reshard/tests/model_weight_planner/helpers.py
new file mode 100644
index 0000000000..6dee16b381
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/helpers.py
@@ -0,0 +1,567 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, replace
+from itertools import product
+from math import prod
+
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+)
+from mooncake.reshard.weight._planner.contracts import BoundWeightFragment
+
+
+@dataclass(frozen=True)
+class RuntimeInputs(Sequence[WeightPlacementPart]):
+    """One complete placement plus its per-participant runtime bindings."""
+
+    placement: WeightPlacementManifest
+    bindings: tuple[WeightRuntimeBindingManifest, ...]
+
+    def __len__(self) -> int:
+        return len(self.nonempty_parts)
+
+    def __iter__(self) -> Iterator[WeightPlacementPart]:
+        return iter(self.nonempty_parts)
+
+    def __getitem__(self, index):
+        return self.nonempty_parts[index]
+
+    @property
+    def nonempty_parts(self) -> tuple[WeightPlacementPart, ...]:
+        return tuple(part for part in self.placement.parts if part.fragments)
+
+    @property
+    def fragments(self) -> tuple[PlacementFragment, ...]:
+        return self.placement.fragments
+
+    @property
+    def binding(self) -> WeightRuntimeBindingManifest:
+        if len(self.bindings) != 1:
+            raise ValueError("runtime inputs do not identify one binding")
+        return self.bindings[0]
+
+
+def _canonical_strides_bytes(shape: tuple[int, ...], itemsize: int) -> tuple[int, ...]:
+    strides = []
+    running = itemsize
+    for extent in reversed(shape):
+        strides.append(running)
+        running *= extent
+    return tuple(reversed(strides))
+
+
+def bound_fragment(
+    *,
+    fragment_id: str,
+    tensor_id: str,
+    global_offset: tuple[int, ...],
+    local_shape: tuple[int, ...],
+    address: int,
+    nbytes: int,
+    worker_id: str,
+    endpoint: str,
+    device: str = "cuda:0",
+    rank: ParallelRank = ParallelRank(),
+    lease_generation: int = 1,
+    aliases: tuple[str, ...] = (),
+    placement_fragment_id: str | None = None,
+    instance_id: str | None = None,
+    runtime_lease_id: str | None = None,
+    owner=None,
+) -> BoundWeightFragment:
+    placement_id = placement_fragment_id or f"{fragment_id}-placement"
+    placement = PlacementFragment(
+        placement_fragment_id=placement_id,
+        tensor_id=tensor_id,
+        global_offset=global_offset,
+        local_shape=local_shape,
+        nbytes=nbytes,
+        rank=rank,
+        aliases=aliases,
+    )
+    binding = RuntimeBindingFragment(
+        placement_fragment_id=placement_id,
+        fragment_id=fragment_id,
+        address=address,
+        nbytes=nbytes,
+        worker_id=worker_id,
+        endpoint=endpoint,
+        device=device,
+        itemsize=nbytes // prod(local_shape),
+        local_shape=local_shape,
+        strides_bytes=_canonical_strides_bytes(
+            local_shape,
+            nbytes // prod(local_shape),
+        ),
+        storage_address=address,
+        storage_nbytes=nbytes,
+        storage_offset_bytes=0,
+        owner=owner,
+    )
+    return BoundWeightFragment(
+        placement=placement,
+        binding=binding,
+        instance_id=instance_id or worker_id,
+        runtime_lease_id=runtime_lease_id or f"{worker_id}-lease",
+        lease_generation=lease_generation,
+        owner=owner,
+    )
+
+
+def bound_fragments(inputs: RuntimeInputs) -> tuple[BoundWeightFragment, ...]:
+    result = []
+    parts_by_participant = {
+        part.participant_id: part for part in inputs.placement.parts
+    }
+    for binding in inputs.bindings:
+        part = parts_by_participant[binding.participant_id]
+        runtime_by_id = {
+            fragment.placement_fragment_id: fragment for fragment in binding.fragments
+        }
+        for placement_fragment in part.fragments:
+            runtime_fragment = runtime_by_id[placement_fragment.placement_fragment_id]
+            result.append(
+                BoundWeightFragment(
+                    placement=placement_fragment,
+                    binding=runtime_fragment,
+                    instance_id=binding.instance_id,
+                    runtime_lease_id=binding.lease_id,
+                    lease_generation=binding.generation,
+                    owner=runtime_fragment.owner,
+                )
+            )
+    return tuple(result)
+
+
+def topology_for_participants(
+    participants: Sequence[tuple[str, ParallelRank]],
+) -> ParallelTopology:
+    """Build a complete topology while keeping fixture-only participants minimal."""
+
+    if not participants:
+        raise ValueError("test topology requires at least one participant")
+    participant_by_rank: dict[ParallelRank, str] = {}
+    for participant_id, rank in participants:
+        participant_by_rank.setdefault(rank, participant_id)
+
+    sizes = {
+        axis: max(getattr(rank, axis) for rank in participant_by_rank) + 1
+        for axis in ("tp", "pp", "ep", "dp")
+    }
+    observed = {
+        axis: {getattr(rank, axis) for rank in participant_by_rank} for axis in sizes
+    }
+    missing = {
+        axis: sorted(set(range(size)) - observed[axis]) for axis, size in sizes.items()
+    }
+    placeholder_count = max((len(values) for values in missing.values()), default=0)
+    defaults = {axis: min(observed[axis]) for axis in sizes}
+    for index in range(placeholder_count):
+        coordinates = {
+            axis: values[index] if index < len(values) else defaults[axis]
+            for axis, values in missing.items()
+        }
+        rank = ParallelRank(**coordinates)
+        participant_by_rank.setdefault(
+            rank,
+            f"fixture-empty-d{rank.dp}-t{rank.tp}-p{rank.pp}-e{rank.ep}",
+        )
+
+    return ParallelTopology(
+        tp_size=sizes["tp"],
+        pp_size=sizes["pp"],
+        ep_size=sizes["ep"],
+        dp_size=sizes["dp"],
+        participants=tuple(
+            TopologyParticipant(participant_id, rank)
+            for rank, participant_id in sorted(
+                participant_by_rank.items(),
+                key=lambda item: (
+                    item[0].dp,
+                    item[0].pp,
+                    item[0].ep,
+                    item[0].tp,
+                ),
+            )
+        ),
+    )
+
+
+def global_placement_from_fragments(
+    *,
+    resource_id: str,
+    revision: str,
+    placement_set_id: str,
+    tensors: Sequence[TensorDescriptor],
+    fragments: Sequence[PlacementFragment],
+    participant_ids: dict[ParallelRank, str] | None = None,
+    weight_generation: int = 1,
+) -> WeightPlacementManifest:
+    fragment_items = tuple(fragments)
+    participant_ids = participant_ids or {
+        rank: (f"{placement_set_id}-d{rank.dp}-t{rank.tp}-p{rank.pp}-e{rank.ep}")
+        for rank in {fragment.rank for fragment in fragment_items}
+    }
+    topology = topology_for_participants(
+        tuple(
+            (participant_id, rank) for rank, participant_id in participant_ids.items()
+        )
+    )
+    return WeightPlacementManifest.from_fragments(
+        resource_id=resource_id,
+        revision=revision,
+        weight_generation=weight_generation,
+        placement_set_id=placement_set_id,
+        topology=topology,
+        tensors=tuple(tensors),
+        fragments=fragment_items,
+    )
+
+
+def rebuild_placement(
+    placement: WeightPlacementManifest,
+    *,
+    tensors: Sequence[TensorDescriptor] | None = None,
+    fragments: Sequence[PlacementFragment] | None = None,
+) -> WeightPlacementManifest:
+    """Re-run the global collection barrier with selected logical content."""
+
+    return WeightPlacementManifest.from_fragments(
+        resource_id=placement.resource_id,
+        revision=placement.revision,
+        weight_generation=placement.weight_generation,
+        placement_set_id=placement.placement_set_id,
+        topology=placement.topology,
+        tensors=tuple(tensors if tensors is not None else placement.tensors),
+        fragments=tuple(fragments if fragments is not None else placement.fragments),
+    )
+
+
+def runtime_inputs_from_groups(
+    *,
+    resource_id: str,
+    revision: str,
+    placement_set_id: str,
+    tensors: Sequence[TensorDescriptor],
+    groups: Sequence[
+        tuple[
+            str,
+            Sequence[PlacementFragment],
+            Sequence[RuntimeBindingFragment],
+        ]
+    ],
+    weight_generation: int = 1,
+) -> RuntimeInputs:
+    """Aggregate participant parts, then bind each non-empty participant."""
+
+    grouped: dict[
+        ParallelRank,
+        tuple[str, list[PlacementFragment], list[RuntimeBindingFragment]],
+    ] = {}
+    for participant_id, placement_fragments, binding_fragments in groups:
+        placement_items = tuple(placement_fragments)
+        if not placement_items:
+            raise ValueError("runtime fixture participant must contain fragments")
+        ranks = {fragment.rank for fragment in placement_items}
+        if len(ranks) != 1:
+            raise ValueError("runtime fixture participant spans parallel ranks")
+        rank = next(iter(ranks))
+        if rank not in grouped:
+            grouped[rank] = (participant_id, [], [])
+        _, grouped_placements, grouped_bindings = grouped[rank]
+        grouped_placements.extend(placement_items)
+        grouped_bindings.extend(binding_fragments)
+
+    participant_ids = {
+        rank: participant_id for rank, (participant_id, _, _) in grouped.items()
+    }
+    placement = global_placement_from_fragments(
+        resource_id=resource_id,
+        revision=revision,
+        weight_generation=weight_generation,
+        placement_set_id=placement_set_id,
+        tensors=tensors,
+        fragments=tuple(
+            fragment
+            for _, placement_fragments, _ in grouped.values()
+            for fragment in placement_fragments
+        ),
+        participant_ids=participant_ids,
+    )
+    bindings = tuple(
+        WeightRuntimeBindingManifest(
+            resource_id=resource_id,
+            revision=revision,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id=participant_id,
+            participant_id=participant_id,
+            generation=1,
+            lease_id=f"{participant_id}-lease",
+            fragments=tuple(binding_fragments),
+        )
+        for participant_id, _, binding_fragments in grouped.values()
+    )
+    return RuntimeInputs(placement, bindings)
+
+
+def descriptor(
+    *,
+    global_shape: tuple[int, ...] = (8, 4),
+    shard_dim: int = 0,
+    fingerprint: str = "sglang:qwen3.5:bf16:v1",
+) -> TensorDescriptor:
+    return TensorDescriptor(
+        tensor_id="layers.2.experts.3.w1",
+        global_shape=global_shape,
+        dtype="bfloat16",
+        itemsize=2,
+        shard_dims=(shard_dim,),
+        layer_id=2,
+        expert_id=3,
+        layout_fingerprint=fingerprint,
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            OwnershipAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=shard_dim),
+        ),
+    )
+
+
+def tp_manifests(
+    *,
+    tp: int,
+    dp: int = 1,
+    pp_rank: int,
+    ep_rank: int,
+    address_base: int,
+    worker_prefix: str,
+    tensor: TensorDescriptor | None = None,
+) -> RuntimeInputs:
+    tensor = tensor or descriptor()
+    (dim,) = tensor.shard_dims
+    assert tensor.global_shape[dim] % tp == 0
+    extent = tensor.global_shape[dim] // tp
+    groups = []
+    for dp_rank, tp_rank in product(range(dp), range(tp)):
+        local_shape = list(tensor.global_shape)
+        local_shape[dim] = extent
+        global_offset = [0] * len(tensor.global_shape)
+        global_offset[dim] = tp_rank * extent
+        worker_id = f"{worker_prefix}-d{dp_rank}-t{tp_rank}"
+        placement_fragment_id = f"{worker_id}-placement"
+        nbytes = prod(local_shape) * tensor.itemsize
+        placement_fragment = PlacementFragment(
+            placement_fragment_id=placement_fragment_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=tuple(global_offset),
+            local_shape=tuple(local_shape),
+            nbytes=nbytes,
+            rank=ParallelRank(
+                dp=dp_rank,
+                tp=tp_rank,
+                pp=pp_rank,
+                ep=ep_rank,
+            ),
+        )
+        groups.append(
+            (
+                worker_id,
+                (placement_fragment,),
+                (
+                    RuntimeBindingFragment(
+                        placement_fragment_id=placement_fragment_id,
+                        fragment_id=f"{worker_id}-fragment",
+                        address=address_base + (dp_rank * tp + tp_rank) * 0x1000,
+                        nbytes=nbytes,
+                        worker_id=worker_id,
+                        endpoint=f"{worker_id}:12345",
+                        device="cuda:0",
+                        itemsize=tensor.itemsize,
+                        local_shape=tuple(local_shape),
+                        strides_bytes=_canonical_strides_bytes(
+                            tuple(local_shape), tensor.itemsize
+                        ),
+                        storage_address=(
+                            address_base + (dp_rank * tp + tp_rank) * 0x1000
+                        ),
+                        storage_nbytes=nbytes,
+                        storage_offset_bytes=0,
+                    ),
+                ),
+            )
+        )
+    return runtime_inputs_from_groups(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id=worker_prefix,
+        tensors=(tensor,),
+        groups=groups,
+    )
+
+
+def plan_transfer(source: RuntimeInputs, target: RuntimeInputs):
+    logical = plan_placement_transfer(source.placement, target.placement)
+    source_participants = {
+        executor.participant_id for executor in logical.source_executors
+    }
+    target_participants = {
+        executor.participant_id for executor in logical.target_executors
+    }
+    return bind_logical_transfer_plan(
+        logical,
+        tuple(
+            binding
+            for binding in target.bindings
+            if binding.participant_id in target_participants
+        ),
+        source_bindings=tuple(
+            binding
+            for binding in source.bindings
+            if binding.participant_id in source_participants
+        ),
+    )
+
+
+def plan_transfer_to_local_target(
+    source: RuntimeInputs,
+    target: RuntimeInputs,
+    *,
+    target_index: int = 0,
+):
+    target_binding = target.bindings[target_index]
+    logical = plan_placement_transfer_to_local_target(
+        source.placement,
+        target.placement,
+        target_binding.participant_id,
+    )
+    source_participants = {
+        executor.participant_id for executor in logical.source_executors
+    }
+    return bind_logical_transfer_plan(
+        logical,
+        (target_binding,),
+        source_bindings=tuple(
+            binding
+            for binding in source.bindings
+            if binding.participant_id in source_participants
+        ),
+    )
+
+
+def combine_runtime_inputs(*inputs: RuntimeInputs) -> RuntimeInputs:
+    if not inputs:
+        raise ValueError("runtime input collection must not be empty")
+    first = inputs[0].placement
+    groups = []
+    tensors: dict[str, TensorDescriptor] = {}
+    for item in inputs:
+        placement = item.placement
+        if (
+            placement.resource_id != first.resource_id
+            or placement.revision != first.revision
+            or placement.weight_generation != first.weight_generation
+        ):
+            raise ValueError("runtime input identities differ")
+        tensors.update({tensor.tensor_id: tensor for tensor in placement.tensors})
+        parts = {part.participant_id: part for part in placement.parts}
+        groups.extend(
+            (
+                binding.participant_id,
+                parts[binding.participant_id].fragments,
+                binding.fragments,
+            )
+            for binding in item.bindings
+        )
+    return runtime_inputs_from_groups(
+        resource_id=first.resource_id,
+        revision=first.revision,
+        weight_generation=first.weight_generation,
+        placement_set_id=f"combined-{first.placement_set_id}",
+        tensors=tuple(tensors.values()),
+        groups=groups,
+    )
+
+
+def replace_placement_fragment(
+    inputs: RuntimeInputs,
+    index: int,
+    fragment: PlacementFragment,
+) -> RuntimeInputs:
+    current_fragment = inputs.fragments[index]
+    parts = {part.participant_id: part for part in inputs.placement.parts}
+    groups = []
+    for binding in inputs.bindings:
+        placement_fragments = tuple(
+            fragment if item == current_fragment else item
+            for item in parts[binding.participant_id].fragments
+        )
+        groups.append((binding.participant_id, placement_fragments, binding.fragments))
+    return runtime_inputs_from_groups(
+        resource_id=inputs.placement.resource_id,
+        revision=inputs.placement.revision,
+        weight_generation=inputs.placement.weight_generation,
+        placement_set_id=inputs.placement.placement_set_id,
+        tensors=inputs.placement.tensors,
+        groups=groups,
+    )
+
+
+def operation_for_target(plan, tp_rank: int, dp_rank: int = 0):
+    return [
+        operation
+        for operation in plan.operations
+        if operation.target.rank.tp == tp_rank and operation.target.rank.dp == dp_rank
+    ]
+
+
+def distribute_tp_shards_across_ep_ranks(manifests: RuntimeInputs) -> RuntimeInputs:
+    parts = {part.participant_id: part for part in manifests.placement.parts}
+    groups = []
+    for binding in manifests.bindings:
+        fragments = tuple(
+            replace(
+                fragment,
+                rank=replace(fragment.rank, ep=fragment.rank.tp),
+            )
+            for fragment in parts[binding.participant_id].fragments
+        )
+        groups.append((binding.participant_id, fragments, binding.fragments))
+    return runtime_inputs_from_groups(
+        resource_id=manifests.placement.resource_id,
+        revision=manifests.placement.revision,
+        weight_generation=manifests.placement.weight_generation,
+        placement_set_id=manifests.placement.placement_set_id,
+        tensors=manifests.placement.tensors,
+        groups=groups,
+    )
+
+
+class CountingFragment:
+    def __init__(self, fragment: PlacementFragment, accesses: list[int]) -> None:
+        self._fragment = fragment
+        self._accesses = accesses
+
+    @property
+    def tensor_id(self) -> str:
+        self._accesses[0] += 1
+        return self._fragment.tensor_id
+
+    def __getattr__(self, name: str):
+        return getattr(self._fragment, name)
diff --git a/mooncake-reshard/tests/model_weight_planner/test_alias_dedup.py b/mooncake-reshard/tests/model_weight_planner/test_alias_dedup.py
new file mode 100644
index 0000000000..ed209fbf15
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_alias_dedup.py
@@ -0,0 +1,462 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from math import prod
+
+import pytest
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    OwnershipAxis,
+    SplitAxis,
+)
+from mooncake.reshard.weight._planner.bound_contracts import RuntimeFragmentSnapshot
+
+from .helpers import (
+    RuntimeInputs,
+    _canonical_strides_bytes,
+    descriptor,
+    plan_transfer,
+    runtime_inputs_from_groups,
+)
+
+
+def _runtime_inputs(
+    *,
+    resource_id: str,
+    tensors: tuple[TensorDescriptor, ...],
+    groups: tuple[tuple[str, tuple[tuple[PlacementFragment, int], ...]], ...],
+) -> RuntimeInputs:
+    return runtime_inputs_from_groups(
+        resource_id=resource_id,
+        revision="step-42",
+        placement_set_id=groups[0][0],
+        tensors=tensors,
+        groups=tuple(
+            (
+                worker_id,
+                tuple(fragment for fragment, _ in fragments),
+                tuple(
+                    RuntimeBindingFragment(
+                        placement_fragment_id=fragment.placement_fragment_id,
+                        fragment_id=(
+                            f"{worker_id}-{fragment.placement_fragment_id}-runtime"
+                        ),
+                        address=address,
+                        nbytes=fragment.nbytes,
+                        worker_id=worker_id,
+                        endpoint=f"{worker_id}:12345",
+                        device="cuda:0",
+                        itemsize=(fragment.nbytes // prod(fragment.local_shape)),
+                        local_shape=fragment.local_shape,
+                        strides_bytes=_canonical_strides_bytes(
+                            fragment.local_shape,
+                            fragment.nbytes // prod(fragment.local_shape),
+                        ),
+                        storage_address=address,
+                        storage_nbytes=fragment.nbytes,
+                        storage_offset_bytes=0,
+                    )
+                    for fragment, address in fragments
+                ),
+            )
+            for worker_id, fragments in groups
+        ),
+    )
+
+
+def _alias_tensors() -> tuple[TensorDescriptor, ...]:
+    return tuple(
+        replace(
+            descriptor(),
+            tensor_id=tensor_id,
+            global_shape=(32,),
+            shard_dims=(),
+            layer_id=None,
+            expert_id=None,
+            layout_fingerprint="sglang:qwen3.5:vocab-parallel:v1",
+            parallel_axes=(OwnershipAxis(kind="pp"),),
+        )
+        for tensor_id in ("embed_tokens.weight", "lm_head.weight")
+    )
+
+
+def _flat_fragment(
+    tensor_id: str,
+    *,
+    prefix: str,
+    aliases: tuple[str, ...],
+    pp: int = 0,
+) -> PlacementFragment:
+    return PlacementFragment(
+        placement_fragment_id=f"{prefix}-{tensor_id}-placement",
+        tensor_id=tensor_id,
+        global_offset=(0,),
+        local_shape=(32,),
+        nbytes=64,
+        rank=ParallelRank(pp=pp),
+        aliases=aliases,
+    )
+
+
+def test_plan_preserves_identical_physical_alias_copies() -> None:
+    aliases = ("embed_tokens.weight", "lm_head.weight")
+    tensors = _alias_tensors()
+    source = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "source",
+                tuple(
+                    (
+                        _flat_fragment(t.tensor_id, prefix="source", aliases=aliases),
+                        0x10000,
+                    )
+                    for t in tensors
+                ),
+            ),
+        ),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "target",
+                tuple(
+                    (
+                        _flat_fragment(t.tensor_id, prefix="target", aliases=aliases),
+                        0x20000,
+                    )
+                    for t in tensors
+                ),
+            ),
+        ),
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 2
+    assert plan.total_bytes == 128
+
+
+def test_plan_rejects_target_aliases_with_distinct_source_storage() -> None:
+    aliases = ("embed_tokens.weight", "lm_head.weight")
+    tensors = _alias_tensors()
+    source = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "source",
+                tuple(
+                    (
+                        _flat_fragment(t.tensor_id, prefix="source", aliases=()),
+                        0x10000 + index * 0x1000,
+                    )
+                    for index, t in enumerate(tensors)
+                ),
+            ),
+        ),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "target",
+                tuple(
+                    (
+                        _flat_fragment(t.tensor_id, prefix="target", aliases=aliases),
+                        0x20000,
+                    )
+                    for t in tensors
+                ),
+            ),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        plan_transfer(source, target)
+
+
+def test_plan_preserves_declared_target_aliases_across_pp_sources() -> None:
+    aliases = ("embed_tokens.weight", "lm_head.weight")
+    tensors = _alias_tensors()
+    source = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=tuple(
+            (
+                f"source-pp{pp}",
+                (
+                    (
+                        _flat_fragment(
+                            tensor.tensor_id,
+                            prefix=f"source-pp{pp}",
+                            aliases=aliases,
+                            pp=pp,
+                        ),
+                        0x10000 + pp * 0x1000,
+                    ),
+                ),
+            )
+            for pp, tensor in enumerate(tensors)
+        ),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "target",
+                tuple(
+                    (
+                        _flat_fragment(t.tensor_id, prefix="target", aliases=aliases),
+                        0x20000,
+                    )
+                    for t in tensors
+                ),
+            ),
+        ),
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 2
+    assert {operation.tensor_id for operation in plan.operations} == {
+        "embed_tokens.weight",
+        "lm_head.weight",
+    }
+    assert {operation.source.worker_id for operation in plan.operations} == {
+        "source-pp0",
+        "source-pp1",
+    }
+
+
+def test_plan_preserves_cross_dim_declared_aliases() -> None:
+    tensor_ids = ("alias.a", "alias.b")
+    aliases = tensor_ids
+    source_tensors = tuple(
+        TensorDescriptor(
+            tensor_id=tensor_id,
+            global_shape=(2, 2),
+            dtype="bfloat16",
+            itemsize=2,
+            layer_id=None,
+            expert_id=None,
+            layout_fingerprint="framework:tied-weight:v2",
+            shard_dims=(0,),
+            parallel_axes=(
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="tp", dim=0),
+            ),
+        )
+        for tensor_id in tensor_ids
+    )
+    target_tensors = tuple(
+        replace(
+            tensor,
+            shard_dims=(1,),
+            parallel_axes=(
+                OwnershipAxis(kind="pp"),
+                SplitAxis(kind="tp", dim=1),
+            ),
+        )
+        for tensor in source_tensors
+    )
+    source_fragments = tuple(
+        (
+            PlacementFragment(
+                placement_fragment_id=f"source-{tensor.tensor_id}-row{row}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(row, 0),
+                local_shape=(1, 2),
+                nbytes=4,
+                rank=ParallelRank(pp=0),
+                aliases=aliases,
+            ),
+            0x10000 + tensor_index * 0x100 + row * 4,
+        )
+        for tensor_index, tensor in enumerate(source_tensors)
+        for row in range(2)
+    )
+    target_fragments = tuple(
+        (
+            PlacementFragment(
+                placement_fragment_id=f"target-{tensor.tensor_id}-column{column}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(0, column),
+                local_shape=(2, 1),
+                nbytes=4,
+                rank=ParallelRank(pp=1),
+                aliases=aliases,
+            ),
+            0x20000 + column * 0x100,
+        )
+        for tensor in target_tensors
+        for column in range(2)
+    )
+    source = _runtime_inputs(
+        resource_id="qwen-family",
+        tensors=source_tensors,
+        groups=(("source", source_fragments),),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen-family",
+        tensors=target_tensors,
+        groups=(("target", target_fragments),),
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 8
+    assert {operation.tensor_id for operation in plan.operations} == {
+        "alias.a",
+        "alias.b",
+    }
+    assert plan.pipeline_routes[0].source_pp == 0
+    assert plan.pipeline_routes[0].target_pp == 1
+
+
+def test_plan_rejects_alias_targets_with_distinct_runtime_lease_scopes() -> None:
+    """A physical target range cannot span independently fenced bindings."""
+
+    aliases = ("embed_tokens.weight", "lm_head.weight")
+    tensors = _alias_tensors()
+    source = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=tuple(
+            (
+                f"source-pp{pp}",
+                (
+                    (
+                        _flat_fragment(
+                            tensor.tensor_id,
+                            prefix=f"source-pp{pp}",
+                            aliases=aliases,
+                            pp=pp,
+                        ),
+                        0x10000 + pp * 0x1000,
+                    ),
+                ),
+            )
+            for pp, tensor in enumerate(tensors)
+        ),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=tuple(
+            (
+                f"target-pp{pp}",
+                (
+                    (
+                        _flat_fragment(
+                            tensor.tensor_id,
+                            prefix=f"target-pp{pp}",
+                            aliases=aliases,
+                            pp=pp,
+                        ),
+                        0x20000,
+                    ),
+                ),
+            )
+            for pp, tensor in enumerate(tensors)
+        ),
+    )
+    target = RuntimeInputs(
+        target.placement,
+        tuple(
+            replace(
+                binding,
+                instance_id="shared-target-instance",
+                lease_id=f"target-lease-{index}",
+                fragments=(
+                    replace(
+                        binding.fragments[0],
+                        worker_id="shared-target-worker",
+                        endpoint="shared-target-worker:12345",
+                        address=0x20000,
+                        storage_address=0x20000,
+                        owner=f"target-owner-{index}",
+                    ),
+                ),
+            )
+            for index, binding in enumerate(target.bindings)
+        ),
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        plan_transfer(source, target)
+
+
+def test_bound_participant_lease_collection_is_linear(monkeypatch) -> None:
+    """Executor provenance must not use repeated list-membership scans."""
+
+    fragment_count = 32
+    tensors = tuple(
+        replace(
+            descriptor(),
+            tensor_id=f"layers.{index}.mlp.down_proj.weight",
+            global_shape=(32,),
+            shard_dims=(),
+            layer_id=None,
+            expert_id=None,
+            layout_fingerprint="sglang:qwen3.5:linear-lease-scan:v1",
+            parallel_axes=(OwnershipAxis(kind="pp"),),
+        )
+        for index in range(fragment_count)
+    )
+    source = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "source",
+                tuple(
+                    (
+                        _flat_fragment(tensor.tensor_id, prefix="source", aliases=()),
+                        0x10000 + index * 0x1000,
+                    )
+                    for index, tensor in enumerate(tensors)
+                ),
+            ),
+        ),
+    )
+    target = _runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        tensors=tensors,
+        groups=(
+            (
+                "target",
+                tuple(
+                    (
+                        _flat_fragment(tensor.tensor_id, prefix="target", aliases=()),
+                        0x40000 + index * 0x1000,
+                    )
+                    for index, tensor in enumerate(tensors)
+                ),
+            ),
+        ),
+    )
+
+    comparisons = 0
+    original_eq = RuntimeFragmentSnapshot.__eq__
+
+    def counting_eq(self, other):
+        nonlocal comparisons
+        comparisons += 1
+        return original_eq(self, other)
+
+    monkeypatch.setattr(RuntimeFragmentSnapshot, "__eq__", counting_eq)
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == fragment_count
+    assert comparisons < fragment_count * 8
diff --git a/mooncake-reshard/tests/model_weight_planner/test_bound_executor_snapshots.py b/mooncake-reshard/tests/model_weight_planner/test_bound_executor_snapshots.py
new file mode 100644
index 0000000000..1042f1b0aa
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_bound_executor_snapshots.py
@@ -0,0 +1,1097 @@
+from __future__ import annotations
+
+from copy import copy
+from dataclasses import replace
+import gc
+import inspect
+import pickle
+from types import SimpleNamespace
+import weakref
+
+import pytest
+
+from mooncake.reshard.contracts import ResourceId, RevisionId
+import mooncake.reshard.weight._planner.contracts as planner_contracts
+from mooncake.reshard.weight import (
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+    plan_placement_transfer_to_local_target,
+    plan_stored_transfer_to_target_placement,
+)
+from mooncake.reshard.weight._planner.binding import resolve_executor_plans
+from mooncake.reshard.weight._planner.bound_contracts import (
+    ExecutorTransferPlan,
+    TransferPlan,
+)
+from mooncake.reshard.weight._planner.contracts import (
+    LogicalTransferPlan,
+    PlanningLimits,
+    PlacementExecutorPlan,
+    TransferRegion,
+)
+from mooncake.reshard.weight.storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredWeightManifest,
+)
+
+from .helpers import RuntimeInputs, plan_transfer, rebuild_placement, tp_manifests
+
+
+def _replace_bindings(inputs: RuntimeInputs, bindings) -> RuntimeInputs:
+    return RuntimeInputs(inputs.placement, tuple(bindings))
+
+
+_RUNTIME_ATTESTED_FIELDS = (
+    "fragment_id",
+    "address",
+    "nbytes",
+    "worker_id",
+    "endpoint",
+    "device",
+    "strides_bytes",
+    "storage_address",
+    "storage_nbytes",
+    "storage_offset_bytes",
+    "lease_generation",
+)
+
+
+def _tampered_value(value: object) -> object:
+    if type(value) is str:
+        return f"forged-{value}"
+    if type(value) is int:
+        return value + 1
+    if type(value) is tuple and value and all(type(item) is int for item in value):
+        return (value[0] + 1, *value[1:])
+    raise AssertionError(f"unsupported attested value: {value!r}")
+
+
+def _forge_operation_fragment(fragment, field: str):
+    forged = copy(fragment)
+    if field == "lease_generation":
+        object.__setattr__(
+            forged,
+            field,
+            _tampered_value(getattr(fragment, field)),
+        )
+        return forged
+    forged_binding = copy(fragment.binding)
+    object.__setattr__(
+        forged_binding,
+        field,
+        _tampered_value(getattr(forged_binding, field)),
+    )
+    object.__setattr__(forged, "binding", forged_binding)
+    return forged
+
+
+def _forge_executor_snapshot(snapshot, field: str):
+    forged = copy(snapshot)
+    object.__setattr__(
+        forged,
+        field,
+        _tampered_value(getattr(snapshot, field)),
+    )
+    return forged
+
+
+def test_execution_views_derive_operation_indices_and_pipeline_routes() -> None:
+    assert "operation_indices" not in inspect.signature(ExecutorTransferPlan).parameters
+    assert (
+        "operation_indices" not in inspect.signature(PlacementExecutorPlan).parameters
+    )
+    assert "pipeline_routes" not in inspect.signature(LogicalTransferPlan).parameters
+    assert "pipeline_routes" not in inspect.signature(TransferPlan).parameters
+
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+
+    assert plan.operation_indices_for_executor(
+        plan.source_executors[0], "source"
+    ) == tuple(range(len(plan.operations)))
+    assert plan.operation_indices_for_executor(
+        plan.target_executors[0], "target"
+    ) == tuple(range(len(plan.operations)))
+    assert [(route.source_pp, route.target_pp) for route in plan.pipeline_routes] == [
+        (0, 1)
+    ]
+
+
+def test_bound_plan_is_not_an_execution_or_lifetime_token() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert isinstance(plan, TransferPlan)
+    assert not hasattr(plan, "execute")
+    assert not hasattr(plan, "submit")
+
+
+def test_bound_plan_materializes_private_operation_views_once(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls = 0
+    original = planner_contracts._build_operation_views
+
+    def counted(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        return original(*args, **kwargs)
+
+    monkeypatch.setattr(planner_contracts, "_build_operation_views", counted)
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=4,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+
+    assert calls == 2
+    for _ in range(3):
+        for executor in plan.source_executors:
+            assert plan.operation_indices_for_executor(executor, "source")
+        for executor in plan.target_executors:
+            assert plan.operation_indices_for_executor(executor, "target")
+        assert plan.pipeline_routes
+    assert calls == 2
+    assert "_operation_views" not in plan.__getstate__()
+
+    restored = pickle.loads(pickle.dumps(plan))
+    assert restored.operation_indices_for_executor(
+        restored.target_executors[0], "target"
+    )
+
+
+def test_bound_plan_snapshots_only_the_selected_source_dp_replica() -> None:
+    sources = tp_manifests(
+        tp=2,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=4,
+        dp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(sources, targets)
+    assert len(plan.source_executors) == 2
+    assert len(plan.target_executors) == len(targets)
+    assert {executor.rank.dp for executor in plan.source_executors} == {0}
+
+
+def test_public_transfer_plan_rejects_live_source_without_executor() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+
+    with pytest.raises(ValueError, match="live source requires executor provenance"):
+        replace(plan, source_executors=())
+
+
+def test_transfer_plan_does_not_retain_runtime_allocation_owner() -> None:
+    class AllocationOwner:
+        pass
+
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    owner = AllocationOwner()
+    owner_ref = weakref.ref(owner)
+    source = _replace_bindings(
+        source,
+        (
+            replace(
+                source.bindings[0],
+                fragments=(replace(source.bindings[0].fragments[0], owner=owner),),
+            ),
+        ),
+    )
+
+    plan = plan_transfer(source, target)
+
+    live_fragments = (
+        *(operation.source for operation in plan.operations),
+        *(operation.target for operation in plan.operations),
+    )
+    assert all(fragment.owner is None for fragment in live_fragments)
+    assert all(fragment.binding.owner is None for fragment in live_fragments)
+    assert all(
+        fragment.owner is None
+        for executor in (*plan.source_executors, *plan.target_executors)
+        for fragment in executor.attestation.evidence.fragments
+    )
+    del owner
+    del source
+    gc.collect()
+    assert owner_ref() is None
+
+
+def test_transfer_plan_rejects_owner_forged_into_attestation_during_restore() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    fragment = plan.operations[0].source
+    assert fragment.attestation is not None
+    forged_evidence = copy(fragment.attestation.evidence)
+    object.__setattr__(
+        forged_evidence,
+        "fragments",
+        (
+            replace(
+                fragment.attestation.evidence.fragments[0],
+                owner=SimpleNamespace(name="forged-owner"),
+            ),
+        ),
+    )
+    restored_attestation = object.__new__(type(fragment.attestation))
+
+    with pytest.raises(
+        ValueError, match="runtime binding evidence must not retain allocation owners"
+    ):
+        restored_attestation.__setstate__(
+            (fragment.attestation.placement, forged_evidence)
+        )
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+@pytest.mark.parametrize("field", _RUNTIME_ATTESTED_FIELDS)
+def test_transfer_plan_rejects_every_operation_attested_field(
+    side: str,
+    field: str,
+) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    fragment = (
+        plan.operations[0].source if side == "source" else plan.operations[0].target
+    )
+    with pytest.raises(ValueError):
+        forged_operation = replace(
+            plan.operations[0],
+            **{side: _forge_operation_fragment(fragment, field)},
+        )
+        forged = copy(plan)
+        object.__setattr__(forged, "operations", (forged_operation,))
+        pickle.loads(pickle.dumps(forged))
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+@pytest.mark.parametrize("field", _RUNTIME_ATTESTED_FIELDS)
+def test_transfer_plan_rejects_every_executor_attested_field(
+    side: str,
+    field: str,
+) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    executor = (
+        plan.source_executors[0] if side == "source" else plan.target_executors[0]
+    )
+    forged_executor = copy(executor)
+    object.__setattr__(
+        forged_executor,
+        "fragment_snapshots",
+        (_forge_executor_snapshot(executor.fragment_snapshots[0], field),),
+    )
+    forged = copy(plan)
+    object.__setattr__(forged, f"{side}_executors", (forged_executor,))
+
+    with pytest.raises(ValueError):
+        pickle.loads(pickle.dumps(forged))
+
+
+def test_runtime_binding_uses_the_plan_segment_budget(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = replace(
+        plan_placement_transfer(source.placement, target.placement),
+        planning_limits=PlanningLimits(
+            max_transfer_regions=7,
+            max_segments_per_region=7,
+            max_total_lowered_segments=7,
+        ),
+    )
+
+    import mooncake.reshard.weight._planner.binding as binding_module
+
+    observed: list[int] = []
+    original = binding_module._validate_target_physical_ranges
+
+    def capture(operations, *, max_segment_checks: int) -> None:
+        observed.append(max_segment_checks)
+        original(operations, max_segment_checks=max_segment_checks)
+
+    monkeypatch.setattr(binding_module, "_validate_target_physical_ranges", capture)
+    plan = bind_logical_transfer_plan(
+        logical,
+        target.bindings,
+        source_bindings=source.bindings,
+    )
+
+    assert observed == [logical.planning_limits.max_total_lowered_segments]
+    assert plan.planning_limits == logical.planning_limits
+
+
+def test_bound_stored_plan_rejects_coordinated_fragment_forgery_after_pickle() -> None:
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    group_id = "weights/default/qwen3.5-0.8b/step-42/1"
+    source_manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id=target.placement.resource_id,
+        revision=target.placement.revision,
+        weight_generation=target.placement.weight_generation,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        tensors=target.placement.tensors,
+        fragments=(
+            StoredFragmentSnapshot(
+                fragment_id="stored-source",
+                tensor_id=target.placement.tensors[0].tensor_id,
+                global_offset=(0, 0),
+                local_shape=target.placement.tensors[0].global_shape,
+                object_key=f"{group_id}/payload/0",
+                object_offset=0,
+                nbytes=target.placement.tensors[0].itemsize * 32,
+            ),
+        ),
+        created_at="2026-08-26T00:00:00Z",
+    )
+    logical = plan_stored_transfer_to_target_placement(
+        source_manifest,
+        target.placement,
+    )
+    plan = bind_logical_transfer_plan(
+        logical,
+        target.bindings,
+        source_manifest=source_manifest,
+    )
+    forged_source = replace(
+        plan.operations[0].source,
+        object_key=f"{group_id}/payload/forged",
+    )
+
+    forged = copy(plan)
+    object.__setattr__(
+        forged,
+        "operations",
+        (replace(plan.operations[0], source=forged_source),),
+    )
+    object.__setattr__(
+        forged,
+        "source_stored_fragment_snapshots",
+        (forged_source,),
+    )
+
+    with pytest.raises(ValueError, match="differs from committed manifest"):
+        pickle.loads(pickle.dumps(forged))
+
+
+def test_bind_accepts_participant_local_source_generations() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+    mixed_sources = (
+        sources.bindings[0],
+        replace(sources.bindings[1], generation=sources.bindings[0].generation + 1),
+    )
+
+    plan = bind_logical_transfer_plan(
+        logical,
+        targets.bindings,
+        source_bindings=mixed_sources,
+    )
+
+    assert {
+        executor.participant_id: executor.fragment_snapshots[0].lease_generation
+        for executor in plan.source_executors
+    } == {
+        mixed_sources[0].participant_id: mixed_sources[0].generation,
+        mixed_sources[1].participant_id: mixed_sources[1].generation,
+    }
+
+
+def test_binding_preserves_n_dim_region_geometry() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+    plan = bind_logical_transfer_plan(
+        logical,
+        targets.bindings,
+        source_bindings=sources.bindings,
+    )
+
+    assert len(plan.operations) == len(logical.operations)
+    for logical_operation, live_operation in zip(logical.operations, plan.operations):
+        assert live_operation.tensor_id == logical_operation.tensor_id
+        assert live_operation.source_offset == logical_operation.source_offset
+        assert live_operation.target_offset == logical_operation.target_offset
+        assert live_operation.nbytes == logical_operation.nbytes
+        assert live_operation.repeat == logical_operation.repeat
+        assert live_operation.source_stride == logical_operation.source_stride
+        assert live_operation.target_stride == logical_operation.target_stride
+        assert isinstance(logical_operation, TransferRegion)
+        assert isinstance(live_operation, TransferRegion)
+        assert live_operation.overlap_offset == logical_operation.overlap_offset
+        assert live_operation.overlap_shape == logical_operation.overlap_shape
+        assert live_operation.source_base_offset == logical_operation.source_base_offset
+        assert live_operation.target_base_offset == logical_operation.target_base_offset
+        assert live_operation.inner_bytes == logical_operation.inner_bytes
+        assert live_operation.outer_loop_counts == logical_operation.outer_loop_counts
+        assert live_operation.source_strides == logical_operation.source_strides
+        assert live_operation.target_strides == logical_operation.target_strides
+
+
+def test_bind_rejects_logical_plan_with_target_coverage_gap() -> None:
+    """A forged logical plan must not leave a target shard partially written."""
+
+    sources = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+
+    # Every TP2 target shard normally receives two source overlaps.  Drop one
+    # target-TP0 overlap, then keep every executor and PP-route index coherent.
+    kept_indices = tuple(
+        index
+        for index, operation in enumerate(logical.operations)
+        if not (operation.target.rank.tp == 0 and operation.source.rank.tp == 0)
+    )
+    truncated_values = {
+        "operations": tuple(logical.operations[index] for index in kept_indices),
+    }
+
+    with pytest.raises(ValueError, match="target fragment is not fully covered"):
+        replace(logical, **truncated_values)
+
+    # Binding must independently reject a deserialized/reconstructed immutable
+    # value that bypassed constructor validation.
+    reconstructed = copy(logical)
+    for name, value in truncated_values.items():
+        object.__setattr__(reconstructed, name, value)
+
+    with pytest.raises(ValueError, match="target fragment is not fully covered"):
+        bind_logical_transfer_plan(
+            reconstructed,
+            targets.bindings,
+            source_bindings=sources.bindings,
+        )
+
+
+def test_public_transfer_plan_rejects_bound_target_coverage_gap() -> None:
+    """The public executable-plan boundary must re-check target coverage."""
+
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(sources, targets)
+    kept_indices = tuple(
+        index
+        for index, operation in enumerate(plan.operations)
+        if operation.source.rank.tp == 1
+    )
+    kept_source_fragment_ids = {
+        plan.operations[index].source.fragment_id for index in kept_indices
+    }
+    with pytest.raises(ValueError, match="bound target fragment is not fully covered"):
+        replace(
+            plan,
+            operations=tuple(plan.operations[index] for index in kept_indices),
+            source_executors=tuple(
+                executor
+                for executor in plan.source_executors
+                if set(executor.fragment_ids) <= kept_source_fragment_ids
+            ),
+        )
+
+
+def test_public_transfer_plan_rejects_empty_target_selection() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+
+    with pytest.raises(ValueError, match="bound plan has no target executor metadata"):
+        replace(
+            plan,
+            operations=(),
+            source_executors=(),
+            target_executors=(),
+        )
+
+
+def test_bind_accepts_a_complete_local_target_plan() -> None:
+    sources = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    target_binding = targets.bindings[0]
+    logical = plan_placement_transfer_to_local_target(
+        sources.placement,
+        targets.placement,
+        target_binding.participant_id,
+    )
+
+    plan = bind_logical_transfer_plan(
+        logical,
+        (target_binding,),
+        source_bindings=sources.bindings,
+    )
+
+    assert {operation.target.rank.tp for operation in plan.operations} == {0}
+
+
+def test_bind_rejects_duck_typed_logical_plan() -> None:
+    sources = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+    duck_plan = SimpleNamespace(**vars(logical))
+
+    with pytest.raises(ValueError, match="LogicalTransferPlan"):
+        bind_logical_transfer_plan(
+            duck_plan,
+            targets.bindings,
+            source_bindings=sources.bindings,
+        )
+
+
+def test_bind_rejects_duck_typed_runtime_binding() -> None:
+    sources = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+    duck_binding = SimpleNamespace(**vars(sources.bindings[0]))
+
+    with pytest.raises(ValueError, match="invalid source runtime binding input"):
+        bind_logical_transfer_plan(
+            logical,
+            targets.bindings,
+            source_bindings=(duck_binding,),
+        )
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+def test_bound_plan_records_binding_lease_id_in_executor_snapshot(side: str) -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    sources = _replace_bindings(
+        sources,
+        (
+            replace(binding, lease_id=f"source-lease-{index}")
+            for index, binding in enumerate(sources.bindings)
+        ),
+    )
+    targets = _replace_bindings(
+        targets,
+        (
+            replace(binding, lease_id=f"target-lease-{index}")
+            for index, binding in enumerate(targets.bindings)
+        ),
+    )
+
+    plan = plan_transfer(sources, targets)
+    bindings = sources.bindings if side == "source" else targets.bindings
+    executors = plan.source_executors if side == "source" else plan.target_executors
+
+    assert [executor.runtime_lease_id for executor in executors] == [
+        binding.lease_id for binding in bindings
+    ]
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+def test_executor_snapshot_rejects_binding_lease_id_change(side: str) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    current = source if side == "source" else target
+    binding = replace(
+        current.bindings[0],
+        lease_id=f"rotated-{side}-lease",
+    )
+
+    with pytest.raises(ValueError, match=f"{side} executor snapshot mismatch"):
+        resolve_executor_plans(plan, current.placement, binding, side)
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+def test_executor_snapshot_rejects_device_change(side: str) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    current = source if side == "source" else target
+    binding = replace(
+        current.bindings[0],
+        fragments=(replace(current.bindings[0].fragments[0], device="cuda:1"),),
+    )
+
+    with pytest.raises(ValueError, match=f"{side} executor snapshot mismatch"):
+        resolve_executor_plans(plan, current.placement, binding, side)
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+def test_executor_snapshot_rejects_replaced_placement(side: str) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    current = source if side == "source" else target
+    original = current.placement
+    replacement = rebuild_placement(
+        original,
+        tensors=(
+            replace(
+                original.tensors[0],
+                layout_fingerprint="changed:logical-layout",
+            ),
+        ),
+    )
+    binding = replace(
+        current.bindings[0],
+        placement_id=replacement.placement_id,
+        placement_digest=replacement.digest,
+    )
+
+    with pytest.raises(ValueError, match=f"{side} executor snapshot mismatch"):
+        resolve_executor_plans(plan, replacement, binding, side)
+
+
+def test_executor_snapshot_accepts_the_exact_placement_and_binding() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+
+    assert resolve_executor_plans(
+        plan,
+        source.placement,
+        source.bindings[0],
+        "source",
+    )
+    assert resolve_executor_plans(
+        plan,
+        target.placement,
+        target.bindings[0],
+        "target",
+    )
+
+
+def test_public_transfer_plan_rejects_forged_identity() -> None:
+    """An executable plan must attest the resource and revision it targets."""
+
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    with pytest.raises(ValueError, match="transfer plan identity differs"):
+        replace(
+            plan_transfer(source, target),
+            resource_id=ResourceId("different-resource"),
+            revision=RevisionId("different-revision"),
+        )
+
+
+@pytest.mark.parametrize("side", ["source", "target"])
+def test_public_transfer_plan_rejects_forged_executor_provenance(side: str) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    executor = (
+        plan.source_executors[0] if side == "source" else plan.target_executors[0]
+    )
+
+    with pytest.raises(ValueError, match=f"{side} executor .*provenance"):
+        replace(
+            plan,
+            **{
+                f"{side}_executors": (
+                    replace(executor, worker_id=f"forged-{side}-worker"),
+                )
+            },
+        )
+
+
+def test_public_transfer_plan_rejects_unattested_runtime_view() -> None:
+    """Live fragment geometry must come from a fully validated binding."""
+
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    operation = plan.operations[0]
+    malformed_source = replace(
+        operation.source,
+        binding=replace(
+            operation.source.binding,
+            strides_bytes=(
+                operation.source.binding.strides_bytes[0],
+                operation.source.binding.strides_bytes[1] * 2,
+            ),
+        ),
+        attestation=None,
+    )
+
+    with pytest.raises(ValueError, match="attested runtime binding"):
+        TransferPlan(
+            resource_id=plan.resource_id,
+            revision=plan.revision,
+            weight_generation=plan.weight_generation,
+            target_placement=target.placement,
+            operations=(replace(operation, source=malformed_source),),
+        )
+
+
+def test_public_transfer_plan_rejects_attested_overlapping_target_ranges() -> None:
+    """Attestation does not waive physical target-range validation."""
+
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = plan_transfer(source, target)
+    operation = plan.operations[0]
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        TransferPlan(
+            resource_id=plan.resource_id,
+            revision=plan.revision,
+            weight_generation=plan.weight_generation,
+            target_placement=target.placement,
+            operations=(operation, operation),
+            source_executors=plan.source_executors,
+            target_executors=plan.target_executors,
+        )
+
+
+def test_runtime_attestation_revalidates_after_pickle_round_trip() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    plan = pickle.loads(pickle.dumps(plan_transfer(source, target)))
+
+    assert resolve_executor_plans(
+        plan,
+        source.placement,
+        source.bindings[0],
+        "source",
+    )
diff --git a/mooncake-reshard/tests/model_weight_planner/test_bound_physical_validation.py b/mooncake-reshard/tests/model_weight_planner/test_bound_physical_validation.py
new file mode 100644
index 0000000000..04358abcea
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_bound_physical_validation.py
@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+from math import prod
+from types import SimpleNamespace
+
+import pytest
+
+from mooncake.reshard.weight._planner.bound_contracts import TransferPlan
+from mooncake.reshard.weight._planner.bound_validation import (
+    _validate_target_physical_ranges,
+)
+from mooncake.reshard.weight._planner.contracts import TransferRegion
+from mooncake.reshard.weight.manifest import ParallelRank
+
+from .helpers import bound_fragment, tp_manifests
+
+
+class MutableOperation:
+    """Deliberately non-canonical operation used to prove the public boundary."""
+
+    def __init__(self, source: object, target: object) -> None:
+        self.source = source
+        self.target = target
+
+    def iter_segments(self) -> tuple[tuple[int, int, int], ...]:
+        return ((0, 0, 2),)
+
+    def validate_bounds(self) -> None:
+        return None
+
+
+def strided_column_region(
+    *,
+    tensor_id: str,
+    fragment_suffix: str,
+    target_fragment_id: str,
+    target_address: int,
+    column: int,
+    rows: int = 4,
+    columns: int = 2,
+    target_instance_id: str = "target-instance",
+    target_endpoint: str = "target-worker:12345",
+    target_device: str = "cuda:0",
+) -> TransferRegion:
+    shape = (rows, columns)
+    source = bound_fragment(
+        fragment_id=f"source-{fragment_suffix}",
+        tensor_id=tensor_id,
+        global_offset=(0, 0),
+        local_shape=shape,
+        address=0x30000 + len(fragment_suffix) * 0x100,
+        nbytes=prod(shape) * 2,
+        worker_id=f"source-{fragment_suffix}",
+        endpoint=f"source-{fragment_suffix}:12345",
+        device="cuda:0",
+        rank=ParallelRank(),
+    )
+    target = bound_fragment(
+        fragment_id=target_fragment_id,
+        tensor_id=tensor_id,
+        global_offset=(0, 0),
+        local_shape=shape,
+        address=target_address,
+        nbytes=prod(shape) * 2,
+        worker_id="target-worker",
+        endpoint=target_endpoint,
+        device=target_device,
+        instance_id=target_instance_id,
+        rank=ParallelRank(),
+    )
+    return TransferRegion(
+        tensor_id=tensor_id,
+        source=source,
+        target=target,
+        overlap_offset=(0, column),
+        overlap_shape=(rows, 1),
+        source_base_offset=column * 2,
+        target_base_offset=column * 2,
+        inner_bytes=2,
+        outer_loop_counts=(rows,),
+        source_strides=(columns * 2,),
+        target_strides=(columns * 2,),
+    )
+
+
+def test_physical_overlap_is_detected_for_logically_disjoint_regions() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="shared-fragment",
+        target_address=0x40000,
+        column=0,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="shared-fragment",
+        target_address=0x40000 - 2,
+        column=1,
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        _validate_target_physical_ranges((left, right))
+
+
+def test_public_transfer_plan_rejects_conflicting_target_physical_ranges() -> None:
+    """The public executable-plan boundary must not rely on binder-only checks."""
+
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="shared-fragment",
+        target_address=0x40000,
+        column=0,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="shared-fragment",
+        target_address=0x40000 - 2,
+        column=1,
+    )
+
+    with pytest.raises(ValueError, match="lacks an attested runtime binding"):
+        TransferPlan(
+            resource_id="resource",
+            revision="revision",
+            weight_generation=1,
+            target_placement=tp_manifests(
+                tp=1,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x40000,
+                worker_prefix="target-placement",
+            ).placement,
+            operations=(left, right),
+        )
+
+
+def test_public_transfer_plan_accepts_disjoint_target_physical_ranges() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000,
+        column=1,
+    )
+
+    with pytest.raises(ValueError, match="lacks an attested runtime binding"):
+        TransferPlan(
+            resource_id="resource",
+            revision="revision",
+            weight_generation=1,
+            target_placement=tp_manifests(
+                tp=1,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x40000,
+                worker_prefix="target-placement",
+            ).placement,
+            operations=(left, right),
+        )
+
+
+def test_public_transfer_plan_rejects_mutable_duck_typed_operation() -> None:
+    source = bound_fragment(
+        fragment_id="source-fake",
+        tensor_id="fake",
+        global_offset=(0,),
+        local_shape=(4,),
+        address=0x30000,
+        nbytes=8,
+        worker_id="source-worker",
+        endpoint="source-worker:12345",
+        device="cuda:0",
+        rank=ParallelRank(),
+    )
+    target = bound_fragment(
+        fragment_id="target-fake",
+        tensor_id="fake",
+        global_offset=(0,),
+        local_shape=(4,),
+        address=0x40000,
+        nbytes=8,
+        worker_id="target-worker",
+        endpoint="target-worker:12345",
+        device="cuda:0",
+        instance_id="target-instance",
+        rank=ParallelRank(),
+    )
+
+    with pytest.raises(ValueError, match="canonical transfer operation"):
+        TransferPlan(
+            resource_id="resource",
+            revision="revision",
+            weight_generation=1,
+            target_placement=tp_manifests(
+                tp=1,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x40000,
+                worker_prefix="target-placement",
+            ).placement,
+            operations=(MutableOperation(source, target),),  # type: ignore[arg-type]
+        )
+
+
+def test_public_transfer_plan_rejects_duck_typed_executor_metadata() -> None:
+    region = strided_column_region(
+        tensor_id="tensor",
+        fragment_suffix="executor",
+        target_fragment_id="target-executor",
+        target_address=0x40000,
+        column=0,
+    )
+    fake_executor = SimpleNamespace()
+
+    with pytest.raises(ValueError, match="canonical executor metadata"):
+        TransferPlan(
+            resource_id="resource",
+            revision="revision",
+            weight_generation=1,
+            target_placement=tp_manifests(
+                tp=1,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x40000,
+                worker_prefix="target-placement",
+            ).placement,
+            operations=(region,),
+            source_executors=(fake_executor,),  # type: ignore[arg-type]
+        )
+
+
+def test_interleaved_disjoint_target_segments_are_accepted() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000,
+        column=1,
+    )
+
+    _validate_target_physical_ranges((left, right))
+
+
+def test_same_virtual_address_on_different_devices_is_accepted() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+        target_device="cuda:0",
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000 - 2,
+        column=1,
+        target_device="cuda:1",
+    )
+
+    _validate_target_physical_ranges((left, right))
+
+
+def test_endpoint_change_does_not_create_a_new_address_space() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+        target_endpoint="target-route-a:12345",
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000 - 2,
+        column=1,
+        target_endpoint="target-route-b:12345",
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        _validate_target_physical_ranges((left, right))
+
+
+def test_last_mixed_radix_target_segment_overlap_is_rejected() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000 + 10,
+        column=1,
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        _validate_target_physical_ranges((left, right))
+
+
+def test_target_segment_overlap_scan_budget_fails_closed() -> None:
+    left = strided_column_region(
+        tensor_id="left",
+        fragment_suffix="left",
+        target_fragment_id="target-left",
+        target_address=0x40000,
+        column=0,
+        rows=8,
+    )
+    right = strided_column_region(
+        tensor_id="right",
+        fragment_suffix="right",
+        target_fragment_id="target-right",
+        target_address=0x40000,
+        column=1,
+        rows=8,
+    )
+
+    with pytest.raises(ValueError, match="segment scan budget"):
+        _validate_target_physical_ranges((left, right), max_segment_checks=3)
+
+
+def test_target_physical_scan_visits_each_emitted_segment_once() -> None:
+    rows = 16
+    columns = 32
+    regions = tuple(
+        strided_column_region(
+            tensor_id=f"column-{column}",
+            fragment_suffix=f"column-{column}",
+            target_fragment_id=f"target-column-{column}",
+            target_address=0x40000,
+            column=column,
+            rows=rows,
+            columns=columns,
+        )
+        for column in range(columns)
+    )
+
+    _validate_target_physical_ranges(
+        regions,
+        max_segment_checks=rows * columns,
+    )
+
+
+def test_complete_target_fragment_is_not_rejected_by_global_segment_budget() -> None:
+    rows = 500_001
+    regions = tuple(
+        strided_column_region(
+            tensor_id="shared-tensor",
+            fragment_suffix=f"column-{column}",
+            target_fragment_id="shared-target",
+            target_address=0x40000,
+            column=column,
+            rows=rows,
+            columns=2,
+        )
+        for column in range(2)
+    )
+
+    assert sum(region.segment_count for region in regions) > 1_000_000
+    _validate_target_physical_ranges(regions)
+
+
+def test_complete_fragment_and_fallback_region_overlap_is_rejected() -> None:
+    complete_regions = tuple(
+        strided_column_region(
+            tensor_id="complete-tensor",
+            fragment_suffix=f"complete-column-{column}",
+            target_fragment_id="complete-target",
+            target_address=0x40000,
+            column=column,
+            rows=8,
+            columns=2,
+        )
+        for column in range(2)
+    )
+    fallback_region = strided_column_region(
+        tensor_id="fallback-tensor",
+        fragment_suffix="fallback",
+        target_fragment_id="fallback-target",
+        target_address=0x40000 - 2,
+        column=1,
+        rows=8,
+        columns=2,
+    )
+
+    with pytest.raises(ValueError, match="conflicting target physical range"):
+        _validate_target_physical_ranges((*complete_regions, fallback_region))
diff --git a/mooncake-reshard/tests/model_weight_planner/test_candidate_index.py b/mooncake-reshard/tests/model_weight_planner/test_candidate_index.py
new file mode 100644
index 0000000000..a935a46317
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_candidate_index.py
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+import mooncake.reshard.weight._planner.geometry as geometry_module
+from mooncake.reshard.weight._planner.api import plan_placement_transfer_to_local_target
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    PlacementFragment,
+    SplitAxis,
+)
+
+from .helpers import descriptor, global_placement_from_fragments
+
+
+def test_expert_box_index_avoids_scanning_every_source_expert(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    expert_count = 256
+    tensor = replace(
+        descriptor(),
+        tensor_id="layers.2.experts.w1",
+        global_shape=(expert_count, 4, 4),
+        shard_dims=(0,),
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    source_fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"source-e{expert_id}-placement",
+            tensor_id=tensor.tensor_id,
+            global_offset=(expert_id, 0, 0),
+            local_shape=(1, 4, 4),
+            nbytes=32,
+            rank=ParallelRank(ep=expert_id),
+        )
+        for expert_id in range(expert_count)
+    )
+    sources = global_placement_from_fragments(
+        resource_id="qwen-moe",
+        revision="step-42",
+        placement_set_id="source",
+        tensors=(tensor,),
+        fragments=source_fragments,
+    )
+    target_expert = 127
+    target_fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"target-e{expert_id}-placement",
+            tensor_id=tensor.tensor_id,
+            global_offset=(expert_id, 0, 0),
+            local_shape=(1, 4, 4),
+            nbytes=32,
+            rank=ParallelRank(ep=expert_id),
+        )
+        for expert_id in range(expert_count)
+    )
+    target = global_placement_from_fragments(
+        resource_id="qwen-moe",
+        revision="step-42",
+        placement_set_id="target",
+        tensors=(tensor,),
+        fragments=target_fragments,
+    )
+    overlap_calls = 0
+    original_overlap_box = geometry_module._overlap_box
+
+    def counted_overlap_box(source, target):
+        nonlocal overlap_calls
+        overlap_calls += 1
+        return original_overlap_box(source, target)
+
+    monkeypatch.setattr(geometry_module, "_overlap_box", counted_overlap_box)
+
+    plan = plan_placement_transfer_to_local_target(
+        sources,
+        target,
+        f"target-d0-t0-p0-e{target_expert}",
+    )
+
+    assert len(plan.operations) == 1
+    assert plan.operations[0].source.global_offset == (target_expert, 0, 0)
+    assert overlap_calls <= 4
diff --git a/mooncake-reshard/tests/model_weight_planner/test_contracts_geometry.py b/mooncake-reshard/tests/model_weight_planner/test_contracts_geometry.py
new file mode 100644
index 0000000000..9c2a0004f6
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_contracts_geometry.py
@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from math import prod
+
+import pytest
+
+import mooncake.reshard.weight._planner.contracts as planner_contracts
+from mooncake.reshard.weight._planner.contracts import (
+    BoundWeightFragment,
+    TransferRegion,
+)
+from mooncake.reshard.weight.manifest import ParallelRank
+
+from .helpers import bound_fragment
+
+
+def test_canonical_contract_exposes_only_n_dim_transfer_regions() -> None:
+    assert not hasattr(planner_contracts, "CopyRange")
+
+
+def n_dim_fragment(
+    *,
+    fragment_id: str,
+    global_offset: tuple[int, ...],
+    local_shape: tuple[int, ...],
+    address: int,
+) -> BoundWeightFragment:
+    return bound_fragment(
+        fragment_id=fragment_id,
+        tensor_id="layers.2.experts.w1",
+        global_offset=global_offset,
+        local_shape=local_shape,
+        address=address,
+        nbytes=2 * prod(local_shape),
+        worker_id=fragment_id,
+        endpoint=f"{fragment_id}:12345",
+        device="cuda:0",
+        rank=ParallelRank(),
+    )
+
+
+@pytest.mark.parametrize(
+    (
+        "target_offset",
+        "target_shape",
+        "overlap_offset",
+        "overlap_shape",
+        "source_base_offset",
+        "target_base_offset",
+        "outer_loop_counts",
+        "source_strides",
+        "target_strides",
+        "inner_bytes",
+    ),
+    [
+        (
+            (0, 2, 0),
+            (4, 3, 8),
+            (1, 2, 0),
+            (2, 3, 8),
+            32,
+            48,
+            (2,),
+            (96,),
+            (48,),
+            48,
+        ),
+        (
+            (0, 0, 4),
+            (4, 6, 4),
+            (1, 0, 4),
+            (2, 6, 4),
+            8,
+            48,
+            (2, 6),
+            (96, 16),
+            (48, 8),
+            8,
+        ),
+    ],
+)
+def test_transfer_region_describes_cross_dim_logical_overlap(
+    target_offset: tuple[int, ...],
+    target_shape: tuple[int, ...],
+    overlap_offset: tuple[int, ...],
+    overlap_shape: tuple[int, ...],
+    source_base_offset: int,
+    target_base_offset: int,
+    outer_loop_counts: tuple[int, ...],
+    source_strides: tuple[int, ...],
+    target_strides: tuple[int, ...],
+    inner_bytes: int,
+) -> None:
+    source = n_dim_fragment(
+        fragment_id="source",
+        global_offset=(1, 0, 0),
+        local_shape=(2, 6, 8),
+        address=0x10000,
+    )
+    target = n_dim_fragment(
+        fragment_id="target",
+        global_offset=target_offset,
+        local_shape=target_shape,
+        address=0x20000,
+    )
+
+    region = TransferRegion(
+        tensor_id=source.tensor_id,
+        source=source,
+        target=target,
+        overlap_offset=overlap_offset,
+        overlap_shape=overlap_shape,
+        source_base_offset=source_base_offset,
+        target_base_offset=target_base_offset,
+        inner_bytes=inner_bytes,
+        outer_loop_counts=outer_loop_counts,
+        source_strides=source_strides,
+        target_strides=target_strides,
+    )
+
+    assert region.overlap_offset == overlap_offset
+    assert region.overlap_shape == overlap_shape
+    assert region.source_base_offset == source_base_offset
+    assert region.target_base_offset == target_base_offset
+    assert region.inner_bytes == inner_bytes
+    assert region.outer_loop_counts == outer_loop_counts
+    assert region.source_strides == source_strides
+    assert region.target_strides == target_strides
+    assert region.segment_count == prod(outer_loop_counts)
+    assert region.total_bytes == prod(overlap_shape) * 2
+    assert (
+        len(tuple(region.iter_segments(max_segments=region.segment_count)))
+        == region.segment_count
+    )
+    with pytest.raises(ValueError, match="exceeds max_segments"):
+        tuple(region.iter_segments(max_segments=region.segment_count - 1))
+
+    # TransferPlan is the live, runtime-attested boundary. This test only
+    # exercises address-free N-D region geometry.
+
+
+def test_transfer_region_mixed_radix_iteration_and_n_dim_bounds() -> None:
+    source = n_dim_fragment(
+        fragment_id="source",
+        global_offset=(1, 0, 0),
+        local_shape=(2, 6, 8),
+        address=0x10000,
+    )
+    target = n_dim_fragment(
+        fragment_id="target",
+        global_offset=(0, 2, 0),
+        local_shape=(4, 3, 8),
+        address=0x20000,
+    )
+    region = TransferRegion(
+        tensor_id=source.tensor_id,
+        source=source,
+        target=target,
+        overlap_offset=(1, 2, 0),
+        overlap_shape=(2, 3, 8),
+        source_base_offset=32,
+        target_base_offset=48,
+        inner_bytes=48,
+        outer_loop_counts=(2,),
+        source_strides=(96,),
+        target_strides=(48,),
+    )
+
+    assert tuple(region.iter_segments(max_segments=region.segment_count)) == (
+        (32, 48, 48),
+        (128, 96, 48),
+    )
+
+    with pytest.raises(ValueError, match="canonical"):
+        replace(region, source_strides=(193,))
+
+
+def test_transfer_region_rejects_noncanonical_same_volume_geometry() -> None:
+    source = n_dim_fragment(
+        fragment_id="source",
+        global_offset=(1, 0, 0),
+        local_shape=(2, 6, 8),
+        address=0x10000,
+    )
+    target = n_dim_fragment(
+        fragment_id="target",
+        global_offset=(0, 2, 0),
+        local_shape=(4, 3, 8),
+        address=0x20000,
+    )
+
+    with pytest.raises(ValueError, match="canonical"):
+        TransferRegion(
+            tensor_id=source.tensor_id,
+            source=source,
+            target=target,
+            overlap_offset=(1, 2, 0),
+            overlap_shape=(2, 3, 8),
+            source_base_offset=32,
+            target_base_offset=48,
+            inner_bytes=16,
+            outer_loop_counts=(2, 3),
+            source_strides=(96, 16),
+            target_strides=(80, 16),
+        )
diff --git a/mooncake-reshard/tests/model_weight_planner/test_coverage.py b/mooncake-reshard/tests/model_weight_planner/test_coverage.py
new file mode 100644
index 0000000000..06b720aa43
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_coverage.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight import plan_placement_transfer
+
+from .helpers import (
+    combine_runtime_inputs,
+    descriptor,
+    rebuild_placement,
+    tp_manifests,
+)
+
+
+def test_logical_plan_rejects_target_omitting_a_source_tensor() -> None:
+    primary = descriptor()
+    secondary = replace(
+        primary,
+        tensor_id="layers.3.experts.4.w1",
+        layer_id=3,
+        expert_id=4,
+    )
+    source = combine_runtime_inputs(
+        tp_manifests(
+            tp=1,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x10000,
+            worker_prefix="source-primary",
+            tensor=primary,
+        ),
+        tp_manifests(
+            tp=1,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x20000,
+            worker_prefix="source-secondary",
+            tensor=secondary,
+        ),
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x30000,
+        worker_prefix="target",
+        tensor=primary,
+    )
+
+    with pytest.raises(ValueError, match="target manifests are missing tensors"):
+        plan_placement_transfer(source.placement, target.placement)
+
+
+def test_global_manifest_barrier_rejects_tensor_missing_from_one_dp_replica() -> None:
+    primary = descriptor()
+    secondary = replace(
+        primary,
+        tensor_id="layers.3.experts.4.w1",
+        layer_id=3,
+        expert_id=4,
+    )
+    complete = combine_runtime_inputs(
+        tp_manifests(
+            tp=1,
+            dp=2,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x10000,
+            worker_prefix="target-primary",
+            tensor=primary,
+        ),
+        tp_manifests(
+            tp=1,
+            dp=2,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x50000,
+            worker_prefix="target-secondary",
+            tensor=secondary,
+        ),
+    )
+    incomplete_fragments = tuple(
+        fragment
+        for fragment in complete.fragments
+        if not (fragment.tensor_id == secondary.tensor_id and fragment.rank.dp == 1)
+    )
+
+    with pytest.raises(
+        ValueError,
+        match=("global placement tensor is not fully covered:.*layers.3.experts.4.w1"),
+    ):
+        rebuild_placement(complete.placement, fragments=incomplete_fragments)
+
+
+def test_global_manifest_barrier_rejects_target_tp_gap() -> None:
+    target = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x30000,
+        worker_prefix="target",
+    )
+
+    with pytest.raises(
+        ValueError, match="global placement tensor is not fully covered"
+    ):
+        rebuild_placement(target.placement, fragments=target.fragments[:1])
+
+
+def test_global_manifest_barrier_rejects_missing_source_coverage() -> None:
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+
+    with pytest.raises(
+        ValueError, match="global placement tensor is not fully covered"
+    ):
+        rebuild_placement(source.placement, fragments=source.fragments[:1])
diff --git a/mooncake-reshard/tests/model_weight_planner/test_executor_snapshots.py b/mooncake-reshard/tests/model_weight_planner/test_executor_snapshots.py
new file mode 100644
index 0000000000..a98c9e037b
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_executor_snapshots.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight import plan_placement_transfer
+
+from .helpers import tp_manifests
+
+
+def test_logical_plan_rejects_regions_that_do_not_cover_target() -> None:
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    logical = plan_placement_transfer(source.placement, target.placement)
+    with pytest.raises(ValueError, match="target fragment is not fully covered"):
+        replace(logical, operations=(logical.operations[0],))
diff --git a/mooncake-reshard/tests/model_weight_planner/test_ownership.py b/mooncake-reshard/tests/model_weight_planner/test_ownership.py
new file mode 100644
index 0000000000..104da76375
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_ownership.py
@@ -0,0 +1,590 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from itertools import product
+
+import pytest
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    OwnershipAxis,
+    ReplicatedAxis,
+    SplitAxis,
+    plan_placement_transfer,
+)
+from mooncake.reshard.weight._planner.ownership import (
+    complete_parallel_source_replicas,
+    parallel_tensor_owner,
+)
+
+from .helpers import (
+    _canonical_strides_bytes,
+    CountingFragment,
+    combine_runtime_inputs,
+    descriptor,
+    distribute_tp_shards_across_ep_ranks,
+    global_placement_from_fragments,
+    operation_for_target,
+    plan_transfer,
+    plan_transfer_to_local_target,
+    replace_placement_fragment,
+    runtime_inputs_from_groups,
+    tp_manifests,
+)
+
+
+def test_target_dp_replicas_on_distinct_devices_are_not_deduplicated() -> None:
+    source = tp_manifests(
+        tp=1,
+        dp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    tensor = source.placement.tensors[0]
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"target-dp{dp}-placement",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor.global_shape,
+            nbytes=source.placement.fragments[0].nbytes,
+            rank=ParallelRank(dp=dp),
+        )
+        for dp in range(2)
+    )
+    target = runtime_inputs_from_groups(
+        resource_id=source.placement.resource_id,
+        revision=source.placement.revision,
+        placement_set_id="target",
+        tensors=(tensor,),
+        groups=tuple(
+            (
+                f"target-dp{dp}",
+                (fragment,),
+                (
+                    RuntimeBindingFragment(
+                        placement_fragment_id=fragment.placement_fragment_id,
+                        fragment_id=f"target-dp{dp}-runtime",
+                        address=0x40000,
+                        nbytes=fragment.nbytes,
+                        worker_id="target-worker",
+                        endpoint="target-worker:12345",
+                        device=f"cuda:{dp}",
+                        itemsize=tensor.itemsize,
+                        local_shape=fragment.local_shape,
+                        strides_bytes=_canonical_strides_bytes(
+                            fragment.local_shape, tensor.itemsize
+                        ),
+                        storage_address=0x40000,
+                        storage_nbytes=fragment.nbytes,
+                        storage_offset_bytes=0,
+                    ),
+                ),
+            )
+            for dp, fragment in enumerate(fragments)
+        ),
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 2
+    assert {operation.target.device for operation in plan.operations} == {
+        "cuda:0",
+        "cuda:1",
+    }
+    assert all(
+        plan.operation_indices_for_executor(executor, "target")
+        for executor in plan.target_executors
+    )
+
+
+def test_ep_ownership_is_derived_from_parallel_axis_semantics() -> None:
+    ownership_tensor = replace(
+        descriptor(),
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="ep"),),
+    )
+    split_tensor = replace(
+        descriptor(),
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    fragment = PlacementFragment(
+        tensor_id=ownership_tensor.tensor_id,
+        global_offset=(0, 0),
+        local_shape=ownership_tensor.global_shape,
+        nbytes=64,
+        rank=ParallelRank(ep=3),
+    )
+
+    assert parallel_tensor_owner(ownership_tensor, fragment) == (("ep", 3),)
+    assert parallel_tensor_owner(split_tensor, fragment) == ()
+
+
+def test_dp_ownership_routes_each_tensor_through_its_declared_owner() -> None:
+    tensor_a = replace(
+        descriptor(),
+        tensor_id="layers.0.weight",
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="dp"),),
+    )
+    tensor_b = replace(
+        descriptor(),
+        tensor_id="layers.1.weight",
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="dp"),),
+    )
+
+    def fragment(tensor, dp_rank: int, prefix: str) -> PlacementFragment:
+        return PlacementFragment(
+            placement_fragment_id=f"{prefix}-{tensor.tensor_id}-dp{dp_rank}",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor.global_shape,
+            nbytes=64,
+            rank=ParallelRank(dp=dp_rank),
+        )
+
+    source_fragments = (
+        fragment(tensor_a, 0, "source"),
+        fragment(tensor_b, 1, "source"),
+    )
+    target_fragments = (
+        fragment(tensor_a, 0, "target"),
+        fragment(tensor_b, 1, "target"),
+    )
+    source = global_placement_from_fragments(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="source-dp-owners",
+        tensors=(tensor_a, tensor_b),
+        fragments=source_fragments,
+    )
+    target = global_placement_from_fragments(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="target-dp-owners",
+        tensors=(tensor_a, tensor_b),
+        fragments=target_fragments,
+    )
+
+    plan = plan_placement_transfer(source, target)
+
+    assert len(plan.operations) == 2
+    assert {
+        (operation.source.tensor_id, operation.source.rank.dp)
+        for operation in plan.operations
+    } == {
+        (tensor_a.tensor_id, 0),
+        (tensor_b.tensor_id, 1),
+    }
+    assert {
+        (operation.target.tensor_id, operation.target.rank.dp)
+        for operation in plan.operations
+    } == {
+        (tensor_a.tensor_id, 0),
+        (tensor_b.tensor_id, 1),
+    }
+
+
+def test_dp_ownership_rejects_ambiguous_complete_source_owners() -> None:
+    tensor = replace(
+        descriptor(),
+        tensor_id="layers.0.weight",
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="dp"),),
+    )
+
+    def fragment(dp_rank: int, prefix: str) -> PlacementFragment:
+        return PlacementFragment(
+            placement_fragment_id=f"{prefix}-dp{dp_rank}",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor.global_shape,
+            nbytes=64,
+            rank=ParallelRank(dp=dp_rank),
+        )
+
+    source = global_placement_from_fragments(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="source-ambiguous-dp-owners",
+        tensors=(tensor,),
+        fragments=(fragment(0, "source"), fragment(1, "source")),
+    )
+    target = global_placement_from_fragments(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="target-dp-owner",
+        tensors=(tensor,),
+        fragments=(fragment(0, "target"),),
+    )
+
+    with pytest.raises(ValueError, match="ambiguous declared owners"):
+        plan_placement_transfer(source, target)
+
+
+def test_pipeline_routes_keep_distinct_virtual_stages_on_one_pp_rank() -> None:
+    tensor_a = replace(
+        descriptor(),
+        tensor_id="layers.0.weight",
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="pp"),),
+    )
+    tensor_b = replace(
+        descriptor(),
+        tensor_id="layers.1.weight",
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="pp"),),
+    )
+    source_fragments = (
+        PlacementFragment(
+            placement_fragment_id="source-stage-0",
+            tensor_id=tensor_a.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor_a.global_shape,
+            nbytes=64,
+            rank=ParallelRank(pp=0),
+            pipeline_stage_id=0,
+        ),
+        PlacementFragment(
+            placement_fragment_id="source-stage-1",
+            tensor_id=tensor_b.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor_b.global_shape,
+            nbytes=64,
+            rank=ParallelRank(pp=0),
+            pipeline_stage_id=1,
+        ),
+    )
+    target_fragments = (
+        PlacementFragment(
+            placement_fragment_id="target-stage-2",
+            tensor_id=tensor_a.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor_a.global_shape,
+            nbytes=64,
+            rank=ParallelRank(pp=0),
+            pipeline_stage_id=2,
+        ),
+        PlacementFragment(
+            placement_fragment_id="target-stage-3",
+            tensor_id=tensor_b.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor_b.global_shape,
+            nbytes=64,
+            rank=ParallelRank(pp=0),
+            pipeline_stage_id=3,
+        ),
+    )
+    source = runtime_inputs_from_groups(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="source-pipeline-stages",
+        tensors=(tensor_a, tensor_b),
+        groups=(("source", source_fragments, ()),),
+    )
+    target = runtime_inputs_from_groups(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        placement_set_id="target-pipeline-stages",
+        tensors=(tensor_a, tensor_b),
+        groups=(("target", target_fragments, ()),),
+    )
+
+    logical = plan_placement_transfer(source.placement, target.placement)
+
+    assert {
+        (
+            route.source_pp,
+            route.source_pipeline_stage_id,
+            route.target_pp,
+            route.target_pipeline_stage_id,
+        )
+        for route in logical.pipeline_routes
+    } == {
+        (0, 0, 0, 2),
+        (0, 1, 0, 3),
+    }
+
+
+def test_all_parallel_axes_change_in_one_plan() -> None:
+    source = tp_manifests(
+        tp=2,
+        dp=2,
+        pp_rank=1,
+        ep_rank=1,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=4,
+        dp=3,
+        pp_rank=2,
+        ep_rank=3,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 12
+    assert {op.target.rank.dp for op in plan.operations} == {0, 1, 2}
+    assert {op.target.rank.pp for op in plan.operations} == {2}
+    assert {op.target.rank.ep for op in plan.operations} == {3}
+    assert {op.source.rank.pp for op in plan.operations} == {1}
+    assert {op.source.rank.ep for op in plan.operations} == {1}
+    assert {op.source.rank.dp for op in operation_for_target(plan, 0, 0)} == {0}
+    assert {op.source.rank.dp for op in operation_for_target(plan, 0, 1)} == {1}
+    assert {op.source.rank.dp for op in operation_for_target(plan, 0, 2)} == {0}
+
+
+def test_dense_source_tp_coverage_cannot_span_ep_replicas() -> None:
+    tensor = replace(
+        descriptor(),
+        tensor_id="layers.2.self_attn.q_proj.weight",
+        expert_id=None,
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            ReplicatedAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    with pytest.raises(
+        ValueError, match="global placement tensor is not fully covered"
+    ):
+        distribute_tp_shards_across_ep_ranks(
+            tp_manifests(
+                tp=4,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x10000,
+                worker_prefix="source",
+                tensor=tensor,
+            )
+        )
+
+
+def test_source_replica_validation_indexes_fragments_by_tensor_once() -> None:
+    tensor_count = 64
+    tensors = tuple(
+        replace(
+            descriptor(),
+            tensor_id=f"layers.{index}.self_attn.q_proj.weight",
+            layer_id=index,
+            expert_id=None,
+            parallel_axes=(SplitAxis(kind="tp", dim=0),),
+        )
+        for index in range(tensor_count)
+    )
+    fragments = tuple(
+        tp_manifests(
+            tp=1,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x10000 + index * 0x1000,
+            worker_prefix=f"source-{index}",
+            tensor=tensor,
+        )[0].fragments[0]
+        for index, tensor in enumerate(tensors)
+    )
+    accesses = [0]
+
+    replicas = complete_parallel_source_replicas(
+        {tensor.tensor_id: tensor for tensor in tensors},
+        tuple(CountingFragment(fragment, accesses) for fragment in fragments),
+    )
+
+    assert set(replicas) == {0}
+    assert accesses[0] <= tensor_count * 3
+
+
+def test_dense_target_tp_coverage_cannot_span_ep_replicas() -> None:
+    tensor = replace(
+        descriptor(),
+        tensor_id="layers.2.self_attn.q_proj.weight",
+        expert_id=None,
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            ReplicatedAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    with pytest.raises(
+        ValueError, match="global placement tensor is not fully covered"
+    ):
+        distribute_tp_shards_across_ep_ranks(
+            tp_manifests(
+                tp=2,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x40000,
+                worker_prefix="target",
+                tensor=tensor,
+            )
+        )
+
+
+def test_global_manifest_barrier_rejects_expert_tp_spanning_ep_owners() -> None:
+    with pytest.raises(
+        ValueError,
+        match="global placement tensor is not fully covered",
+    ):
+        distribute_tp_shards_across_ep_ranks(
+            tp_manifests(
+                tp=2,
+                pp_rank=0,
+                ep_rank=0,
+                address_base=0x10000,
+                worker_prefix="source",
+            )
+        )
+
+
+def test_local_plan_uses_one_complete_source_dp_replica() -> None:
+    sources = tp_manifests(
+        tp=2,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer_to_local_target(sources, target, target_index=1)
+
+    assert {operation.source.rank.dp for operation in plan.operations} == {1}
+
+
+def test_global_manifest_barrier_rejects_tp_coverage_split_across_pp_owners() -> None:
+    targets = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    moved = replace(
+        targets[1].fragments[0],
+        rank=replace(targets[1].fragments[0].rank, pp=1),
+    )
+    with pytest.raises(
+        ValueError, match="global placement tensor is not fully covered"
+    ):
+        replace_placement_fragment(targets, 1, moved)
+
+
+def test_complete_tensor_replicas_across_pp_owners_are_each_transferred() -> None:
+    tensor = replace(
+        descriptor(),
+        tensor_id="lm_head.weight",
+        layer_id=None,
+        expert_id=None,
+        parallel_axes=(
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+        tensor=tensor,
+    )
+    target = combine_runtime_inputs(
+        tp_manifests(
+            tp=1,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x40000,
+            worker_prefix="target-pp0",
+            tensor=tensor,
+        ),
+        tp_manifests(
+            tp=1,
+            pp_rank=1,
+            ep_rank=0,
+            address_base=0x50000,
+            worker_prefix="target-pp1",
+            tensor=tensor,
+        ),
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert {operation.target.rank.pp for operation in plan.operations} == {0, 1}
+    assert len(plan.operations) == 4
+
+
+def test_multiple_layers_and_experts_move_pp_ep_tp_dp_ownership_together() -> None:
+    source_inputs = []
+    target_inputs = []
+    for layer_id, expert_id in product(range(2), range(2)):
+        tensor = replace(
+            descriptor(),
+            tensor_id=f"layers.{layer_id}.experts.{expert_id}.w1",
+            layer_id=layer_id,
+            expert_id=expert_id,
+        )
+        source_inputs.append(
+            tp_manifests(
+                tp=2,
+                dp=2,
+                pp_rank=layer_id,
+                ep_rank=expert_id,
+                address_base=0x100000 + (layer_id * 2 + expert_id) * 0x10000,
+                worker_prefix=f"source-l{layer_id}-e{expert_id}",
+                tensor=tensor,
+            )
+        )
+        target_inputs.append(
+            tp_manifests(
+                tp=4,
+                dp=3,
+                pp_rank=1 - layer_id,
+                ep_rank=1 - expert_id,
+                address_base=0x400000 + (layer_id * 2 + expert_id) * 0x10000,
+                worker_prefix=f"target-l{layer_id}-e{expert_id}",
+                tensor=tensor,
+            )
+        )
+
+    plan = plan_transfer(
+        combine_runtime_inputs(*source_inputs),
+        combine_runtime_inputs(*target_inputs),
+    )
+
+    assert plan.resource_id == "qwen3.5-0.8b"
+    assert plan.revision == "step-42"
+    assert plan.total_bytes == 4 * 3 * 8 * 4 * 2
+    assert len(plan.operations) == 4 * 3 * 4
+    for operation in plan.operations:
+        layer_id = operation.target.tensor_id.split(".")[1]
+        expert_id = operation.target.tensor_id.split(".")[3]
+        assert operation.source.tensor_id == operation.target.tensor_id
+        assert operation.source.rank.pp == int(layer_id)
+        assert operation.target.rank.pp == 1 - int(layer_id)
+        assert operation.source.rank.ep == int(expert_id)
+        assert operation.target.rank.ep == 1 - int(expert_id)
diff --git a/mooncake-reshard/tests/model_weight_planner/test_physical_validation.py b/mooncake-reshard/tests/model_weight_planner/test_physical_validation.py
new file mode 100644
index 0000000000..e4fe84bdf0
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_physical_validation.py
@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.weight._planner.contracts import LogicalTransferPlan
+from mooncake.reshard.weight.manifest import ParallelRank
+
+from .helpers import bound_fragment, tp_manifests
+
+
+class MutableOperation:
+    """Deliberately non-canonical operation used to prove the public boundary."""
+
+    def __init__(self, source: object, target: object) -> None:
+        self.source = source
+        self.target = target
+
+    def iter_segments(self) -> tuple[tuple[int, int, int], ...]:
+        return ((0, 0, 2),)
+
+    def validate_bounds(self) -> None:
+        return None
+
+
+def test_public_logical_plan_rejects_mutable_duck_typed_operation() -> None:
+    source_placement = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source-placement",
+    ).placement
+    target_placement = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target-placement",
+    ).placement
+    source = bound_fragment(
+        fragment_id="source-logical-fake",
+        tensor_id="fake",
+        global_offset=(0,),
+        local_shape=(4,),
+        address=0x30000,
+        nbytes=8,
+        worker_id="source-worker",
+        endpoint="source-worker:12345",
+        device="cuda:0",
+        rank=ParallelRank(),
+    )
+    target = bound_fragment(
+        fragment_id="target-logical-fake",
+        tensor_id="fake",
+        global_offset=(0,),
+        local_shape=(4,),
+        address=0x40000,
+        nbytes=8,
+        worker_id="target-worker",
+        endpoint="target-worker:12345",
+        device="cuda:0",
+        instance_id="target-instance",
+        rank=ParallelRank(),
+    )
+
+    with pytest.raises(ValueError, match="canonical transfer operation"):
+        LogicalTransferPlan(
+            resource_id=source_placement.resource_id,
+            revision=source_placement.revision,
+            source_placement=source_placement,
+            target_placement=target_placement,
+            source_tensors=(),
+            target_tensors=(),
+            operations=(MutableOperation(source, target),),  # type: ignore[arg-type]
+        )
diff --git a/mooncake-reshard/tests/model_weight_planner/test_runtime_api_validation.py b/mooncake-reshard/tests/model_weight_planner/test_runtime_api_validation.py
new file mode 100644
index 0000000000..b54a6d6393
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_runtime_api_validation.py
@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight._planner.api import plan_placement_transfer_to_local_target
+
+from .helpers import (
+    combine_runtime_inputs,
+    descriptor,
+    plan_transfer,
+    plan_transfer_to_local_target,
+    tp_manifests,
+)
+
+
+def test_planner_rejects_incompatible_layout() -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target",
+        tensor=descriptor(fingerprint="sglang:qwen3.5:fp8:v1"),
+    )
+
+    with pytest.raises(ValueError, match="layout mismatch"):
+        plan_transfer(source, target)
+
+
+@pytest.mark.parametrize("field", ["layer_id", "expert_id"])
+def test_planner_rejects_incompatible_tensor_semantics(field: str) -> None:
+    source = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target_tensor = replace(descriptor(), **{field: 99})
+    target = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target",
+        tensor=target_tensor,
+    )
+
+    with pytest.raises(ValueError, match="tensor descriptor mismatch"):
+        plan_transfer(source, target)
+
+
+def test_local_target_plan_supports_independent_tp_rank_startup() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=4,
+        pp_rank=2,
+        ep_rank=3,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer_to_local_target(sources, targets, target_index=1)
+
+    assert len(plan.target_executors) == 1
+    assert plan.target_executors[0].rank == targets[1].fragments[0].rank
+    assert len(plan.operations) == 1
+    operation = plan.operations[0]
+    assert operation.source.rank.tp == 0
+    assert operation.target.rank.tp == 1
+    assert operation.source_offset == 2 * 4 * 2
+    assert operation.target_offset == 0
+    assert operation.nbytes == 2 * 4 * 2
+    assert len(plan.source_executors) == 1
+    assert plan.source_executors[0].rank.tp == 0
+
+
+def test_local_target_plan_allows_explicit_pp_ep_tensor_subset() -> None:
+    first = descriptor()
+    second = replace(
+        first,
+        tensor_id="layers.7.experts.5.w1",
+        layer_id=7,
+        expert_id=5,
+    )
+    sources = combine_runtime_inputs(
+        tp_manifests(
+            tp=2,
+            pp_rank=0,
+            ep_rank=0,
+            address_base=0x10000,
+            worker_prefix="source-first",
+            tensor=first,
+        ),
+        tp_manifests(
+            tp=2,
+            pp_rank=1,
+            ep_rank=1,
+            address_base=0x30000,
+            worker_prefix="source-second",
+            tensor=second,
+        ),
+    )
+    local_targets = tp_manifests(
+        tp=4,
+        pp_rank=3,
+        ep_rank=2,
+        address_base=0x50000,
+        worker_prefix="target",
+        tensor=second,
+    )
+
+    plan = plan_transfer_to_local_target(sources, local_targets, target_index=2)
+
+    assert {operation.tensor_id for operation in plan.operations} == {second.tensor_id}
+    assert {operation.source.rank.pp for operation in plan.operations} == {1}
+    assert {operation.source.rank.ep for operation in plan.operations} == {1}
+    assert {operation.target.rank.pp for operation in plan.operations} == {3}
+    assert {operation.target.rank.ep for operation in plan.operations} == {2}
+
+
+def test_local_target_plan_rejects_unknown_target_tensor() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+        tensor=replace(descriptor(), tensor_id="unknown.weight"),
+    )
+
+    with pytest.raises(ValueError, match="unknown tensors"):
+        plan_transfer_to_local_target(sources, targets)
+
+
+def test_local_target_plan_rejects_tensor_without_local_fragment() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=4,
+        pp_rank=1,
+        ep_rank=0,
+        address_base=0x40000,
+        worker_prefix="target",
+    )
+    empty_part = next(part for part in targets.placement.parts if not part.fragments)
+
+    with pytest.raises(ValueError, match="no fragments"):
+        plan_placement_transfer_to_local_target(
+            sources.placement,
+            targets.placement,
+            empty_part.participant_id,
+        )
diff --git a/mooncake-reshard/tests/model_weight_planner/test_runtime_reshard.py b/mooncake-reshard/tests/model_weight_planner/test_runtime_reshard.py
new file mode 100644
index 0000000000..6b5c82d53a
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_planner/test_runtime_reshard.py
@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import pytest
+
+from .helpers import descriptor, operation_for_target, plan_transfer, tp_manifests
+
+
+def test_tp2_to_tp4_splits_source_fragments_without_full_tensor() -> None:
+    source = tp_manifests(
+        tp=2,
+        pp_rank=1,
+        ep_rank=1,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=4,
+        pp_rank=2,
+        ep_rank=3,
+        address_base=0x20000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 4
+    assert [
+        (op.source_offset, op.target_offset, op.nbytes)
+        for op in operation_for_target(plan, 0)
+    ] == [(0, 0, 16)]
+    assert [
+        (op.source_offset, op.target_offset, op.nbytes)
+        for op in operation_for_target(plan, 1)
+    ] == [(16, 0, 16)]
+    assert operation_for_target(plan, 0)[0].source.rank.pp == 1
+    assert operation_for_target(plan, 0)[0].target.rank.pp == 2
+    assert operation_for_target(plan, 0)[0].source.rank.ep == 1
+    assert operation_for_target(plan, 0)[0].target.rank.ep == 3
+
+
+def test_tp4_to_tp2_merges_into_non_overlapping_target_offsets() -> None:
+    source = tp_manifests(
+        tp=4,
+        pp_rank=2,
+        ep_rank=3,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    target = tp_manifests(
+        tp=2,
+        pp_rank=1,
+        ep_rank=1,
+        address_base=0x20000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert [
+        (op.source_offset, op.target_offset, op.nbytes)
+        for op in operation_for_target(plan, 0)
+    ] == [
+        (0, 0, 16),
+        (0, 16, 16),
+    ]
+
+
+@pytest.mark.parametrize(("source_tp", "target_tp"), [(4, 8), (8, 4)])
+def test_single_axis_manifest_tp4_tp8_same_dim_reshard(
+    source_tp: int, target_tp: int
+) -> None:
+    sources = tp_manifests(
+        tp=source_tp,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    targets = tp_manifests(
+        tp=target_tp,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target",
+    )
+
+    plan = plan_transfer(sources, targets)
+
+    assert len(plan.operations) == 8
+    assert all(operation.segment_count == 1 for operation in plan.operations)
+    for target in targets:
+        fragment = target.fragments[0]
+        operations = sorted(
+            operation_for_target(plan, fragment.rank.tp),
+            key=lambda operation: operation.target_offset,
+        )
+        cursor = 0
+        for operation in operations:
+            assert operation.target_offset == cursor
+            cursor += operation.nbytes
+        assert cursor == fragment.nbytes
+
+
+def test_shard_dim_one_generates_row_ranges() -> None:
+    tensor = descriptor(global_shape=(2, 8), shard_dim=1)
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+        tensor=tensor,
+    )
+    target = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target",
+        tensor=tensor,
+    )
+
+    plan = plan_transfer(source, target)
+
+    operations = operation_for_target(plan, 0)
+    assert len(operations) == 1
+    assert operations[0].repeat == 2
+    assert operations[0].source_stride == 8
+    assert operations[0].target_stride == 4
+    assert list(
+        operations[0].iter_segments(max_segments=operations[0].segment_count)
+    ) == [
+        (0, 0, 4),
+        (8, 4, 4),
+    ]
+
+
+def test_large_inner_axis_partition_uses_compact_strided_ranges() -> None:
+    tensor = descriptor(global_shape=(8192, 8192), shard_dim=1)
+    source = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+        tensor=tensor,
+    )
+    target = tp_manifests(
+        tp=4,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="target",
+        tensor=tensor,
+    )
+
+    plan = plan_transfer(source, target)
+
+    assert len(plan.operations) == 4
+    assert {operation.repeat for operation in plan.operations} == {8192}
+    assert plan.total_bytes == 8192 * 8192 * 2
diff --git a/mooncake-reshard/tests/model_weight_store/__init__.py b/mooncake-reshard/tests/model_weight_store/__init__.py
new file mode 100644
index 0000000000..30fd76d5e8
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/__init__.py
@@ -0,0 +1 @@
+"""Tests for the model weight Store facade and responsibility modules."""
diff --git a/mooncake-reshard/tests/model_weight_store/helpers.py b/mooncake-reshard/tests/model_weight_store/helpers.py
new file mode 100644
index 0000000000..4b938c3689
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/helpers.py
@@ -0,0 +1,852 @@
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass, replace
+from itertools import product
+from math import prod
+
+from mooncake.reshard._compat import _strict_zip
+from mooncake.reshard.weight.manifest import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+)
+from mooncake.reshard.weight.planner import (
+    BoundWeightFragment,
+    bind_logical_transfer_plan,
+    plan_placement_transfer,
+)
+from mooncake.reshard.weight.lifetime import (
+    AcquiredWeightBinding,
+    weight_allocation_fence,
+)
+from mooncake.reshard.weight.store import WeightStore
+from mooncake.reshard.lifetime import TerminalTransferState
+
+
+@dataclass(frozen=True)
+class RuntimeParticipant:
+    participant_id: str
+    rank: ParallelRank
+    placement_fragments: tuple[PlacementFragment, ...]
+    binding_fragments: tuple[RuntimeBindingFragment, ...]
+    instance_id: str
+    generation: int = 1
+    lease_id: str | None = None
+
+
+@dataclass(frozen=True)
+class RuntimeInputs:
+    placement: WeightPlacementManifest
+    bindings: tuple[WeightRuntimeBindingManifest, ...]
+
+    @property
+    def binding(self) -> WeightRuntimeBindingManifest:
+        if len(self.bindings) != 1:
+            raise ValueError("runtime input does not contain exactly one binding")
+        return self.bindings[0]
+
+    def __len__(self) -> int:
+        return len(self.bindings)
+
+    def __getitem__(self, index: int) -> RuntimeInputs:
+        return RuntimeInputs(self.placement, (self.bindings[index],))
+
+
+class _TestAllocationToken:
+    def __init__(self, fence) -> None:
+        self._fence = fence
+        self.released_states = []
+
+    @property
+    def fence(self):
+        return self._fence
+
+    def release_after_terminal(self, terminal_state: TerminalTransferState) -> None:
+        self.released_states.append(terminal_state)
+
+
+class _TestAllocationGuard:
+    def __init__(self, binding: WeightRuntimeBindingManifest) -> None:
+        self.binding = binding
+        self.tokens: list[_TestAllocationToken] = []
+
+    def acquire(
+        self,
+        *,
+        transfer_id: str,
+        expected_binding: WeightRuntimeBindingManifest,
+        required_fragment_ids: tuple[str, ...],
+    ) -> AcquiredWeightBinding:
+        assert transfer_id
+        assert expected_binding == self.binding
+        token = _TestAllocationToken(
+            weight_allocation_fence(
+                self.binding,
+                required_fragment_ids,
+                token_id=(
+                    f"{self.binding.instance_id}-{self.binding.participant_id}-"
+                    f"{','.join(sorted(required_fragment_ids))}"
+                ),
+            )
+        )
+        self.tokens.append(token)
+        return AcquiredWeightBinding(binding=self.binding, token=token)
+
+
+def allocation_guards_for_bindings(
+    bindings: tuple[WeightRuntimeBindingManifest, ...],
+) -> dict[tuple[str, str], _TestAllocationGuard]:
+    return {
+        (binding.instance_id, binding.participant_id): _TestAllocationGuard(binding)
+        for binding in bindings
+    }
+
+
+class GuardedWeightStore(WeightStore):
+    """Test-only caller adapter that explicitly supplies framework pins."""
+
+    def upload(self, plan, source_placement, source_binding, **kwargs):
+        kwargs.setdefault(
+            "source_allocation_guards",
+            allocation_guards_for_bindings((source_binding,)),
+        )
+        return super().upload(plan, source_placement, source_binding, **kwargs)
+
+    def load(self, plan, target_placement, target_binding, **kwargs):
+        kwargs.setdefault(
+            "target_allocation_guards",
+            allocation_guards_for_bindings((target_binding,)),
+        )
+        return super().load(plan, target_placement, target_binding, **kwargs)
+
+
+def with_empty_participant(
+    inputs: RuntimeInputs,
+    *,
+    participant_id: str,
+    rank: ParallelRank,
+) -> RuntimeInputs:
+    """Add a topology participant that owns no tensors and needs no binding."""
+
+    topology = ParallelTopology(
+        tp_size=max(inputs.placement.topology.tp_size, rank.tp + 1),
+        pp_size=max(inputs.placement.topology.pp_size, rank.pp + 1),
+        ep_size=max(inputs.placement.topology.ep_size, rank.ep + 1),
+        dp_size=max(inputs.placement.topology.dp_size, rank.dp + 1),
+        participants=(
+            *inputs.placement.topology.participants,
+            TopologyParticipant(participant_id=participant_id, rank=rank),
+        ),
+    )
+    placement = WeightPlacementManifest(
+        resource_id=inputs.placement.resource_id,
+        revision=inputs.placement.revision,
+        weight_generation=inputs.placement.weight_generation,
+        placement_set_id=inputs.placement.placement_set_id,
+        topology=topology,
+        parts=(
+            *(
+                WeightPlacementPart(
+                    resource_id=part.resource_id,
+                    revision=part.revision,
+                    weight_generation=part.weight_generation,
+                    placement_set_id=part.placement_set_id,
+                    topology_id=topology.topology_id,
+                    participant_id=part.participant_id,
+                    rank=part.rank,
+                    tensors=part.tensors,
+                    fragments=part.fragments,
+                )
+                for part in inputs.placement.parts
+            ),
+            WeightPlacementPart(
+                resource_id=inputs.placement.resource_id,
+                revision=inputs.placement.revision,
+                weight_generation=inputs.placement.weight_generation,
+                placement_set_id=inputs.placement.placement_set_id,
+                topology_id=topology.topology_id,
+                participant_id=participant_id,
+                rank=rank,
+                tensors=(),
+                fragments=(),
+            ),
+        ),
+    )
+    bindings = tuple(
+        replace(
+            binding,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+        )
+        for binding in inputs.bindings
+    )
+    return RuntimeInputs(placement, bindings)
+
+
+def make_runtime_inputs(
+    *,
+    resource_id: str,
+    revision: str,
+    tensors: tuple[TensorDescriptor, ...],
+    participants: tuple[RuntimeParticipant, ...],
+    weight_generation: int = 1,
+    placement_set_id: str,
+) -> RuntimeInputs:
+    topology = ParallelTopology(
+        tp_size=max(participant.rank.tp for participant in participants) + 1,
+        pp_size=max(participant.rank.pp for participant in participants) + 1,
+        ep_size=max(participant.rank.ep for participant in participants) + 1,
+        dp_size=max(participant.rank.dp for participant in participants) + 1,
+        participants=tuple(
+            TopologyParticipant(
+                participant_id=participant.participant_id,
+                rank=participant.rank,
+            )
+            for participant in participants
+        ),
+    )
+    placement = WeightPlacementManifest.from_fragments(
+        resource_id=resource_id,
+        revision=revision,
+        weight_generation=weight_generation,
+        placement_set_id=placement_set_id,
+        topology=topology,
+        tensors=tensors,
+        fragments=tuple(
+            fragment
+            for participant in participants
+            for fragment in participant.placement_fragments
+        ),
+    )
+    bindings = tuple(
+        WeightRuntimeBindingManifest(
+            resource_id=placement.resource_id,
+            revision=placement.revision,
+            placement_id=placement.placement_id,
+            placement_digest=placement.digest,
+            instance_id=participant.instance_id,
+            participant_id=participant.participant_id,
+            generation=participant.generation,
+            lease_id=participant.lease_id or f"{participant.instance_id}-lease",
+            fragments=participant.binding_fragments,
+        )
+        for participant in participants
+    )
+    return RuntimeInputs(placement, bindings)
+
+
+def bound_fragments(inputs: RuntimeInputs) -> tuple[BoundWeightFragment, ...]:
+    result = []
+    for binding in inputs.bindings:
+        part = next(
+            item
+            for item in inputs.placement.parts
+            if item.participant_id == binding.participant_id
+        )
+        runtime_by_placement_id = {
+            fragment.placement_fragment_id: fragment for fragment in binding.fragments
+        }
+        result.extend(
+            BoundWeightFragment(
+                placement=fragment,
+                binding=runtime_by_placement_id[fragment.placement_fragment_id],
+                instance_id=binding.instance_id,
+                runtime_lease_id=binding.lease_id,
+                lease_generation=binding.generation,
+                owner=runtime_by_placement_id[fragment.placement_fragment_id].owner,
+            )
+            for fragment in part.fragments
+        )
+    return tuple(result)
+
+
+def plan_transfer(sources: RuntimeInputs, targets: RuntimeInputs):
+    logical = plan_placement_transfer(sources.placement, targets.placement)
+    source_participants = {
+        executor.participant_id for executor in logical.source_executors
+    }
+    target_participants = {
+        executor.participant_id for executor in logical.target_executors
+    }
+    return bind_logical_transfer_plan(
+        logical,
+        source_bindings=tuple(
+            binding
+            for binding in sources.bindings
+            if binding.participant_id in source_participants
+        ),
+        target_bindings=tuple(
+            binding
+            for binding in targets.bindings
+            if binding.participant_id in target_participants
+        ),
+    )
+
+
+@dataclass
+class FakeReplicateConfig:
+    group_ids: list[str]
+    data_type: str
+    with_hard_pin: bool
+
+
+class InMemoryStore:
+    def __init__(self) -> None:
+        self.objects: dict[str, bytes] = {}
+        self.group_ids: dict[str, str] = {}
+        self.configs: dict[str, tuple[str, bool]] = {}
+        self.calls: list[str] = []
+        self.put_batches: list[tuple[str, ...]] = []
+        self.registered: set[int] = set()
+        self.register_calls = 0
+        self.register_args: list[tuple[int, int]] = []
+        self.unregister_calls = 0
+        self.unregister_addresses: list[int] = []
+        self.fail_key: str | None = None
+        self.processing_keys: set[str] = set()
+        self.range_get_calls = 0
+        self.range_sizes: list[int] = []
+        self.range_batch_sizes: list[int] = []
+        self.snapshot_prepare_calls = 0
+        self.snapshot_get_calls = 0
+        self.snapshot_key_sets: list[tuple[str, ...]] = []
+        self.exist_batch_sizes: list[int] = []
+        self.register_result = 0
+        self.removed_keys: list[str] = []
+        self.remove_forces: list[bool] = []
+        self.unregister_results: dict[int, int] = {}
+        self.unregister_exceptions: dict[int, Exception] = {}
+        self.fail_after_write_key: str | None = None
+        self.manifest_race_value: bytes | None = None
+        self.manifest_race_key: str | None = None
+        self.after_batch_is_exist = None
+
+    def register_buffer(self, address: int, nbytes: int) -> int:
+        self.calls.append("register_buffer")
+        self.register_calls += 1
+        self.register_args.append((address, nbytes))
+        if self.register_result != 0:
+            return self.register_result
+        self.registered.add(address)
+        return 0
+
+    def unregister_buffer(self, address: int) -> int:
+        self.calls.append("unregister_buffer")
+        self.unregister_calls += 1
+        self.unregister_addresses.append(address)
+        if address in self.unregister_exceptions:
+            raise self.unregister_exceptions[address]
+        result = self.unregister_results.get(address, 0)
+        if result == 0:
+            self.registered.remove(address)
+        return result
+
+    def batch_put_from(
+        self,
+        keys: list[str],
+        addresses: list[int],
+        sizes: list[int],
+        config: FakeReplicateConfig,
+    ) -> list[int]:
+        self.calls.append("batch_put_from")
+        self.put_batches.append(tuple(keys))
+        results = []
+        for key, address, size, group_id in zip(
+            keys, addresses, sizes, config.group_ids
+        ):
+            if key == self.fail_key:
+                results.append(-1)
+                continue
+            if key in self.processing_keys:
+                results.append(0)
+                continue
+            self.objects[key] = ctypes.string_at(address, size)
+            self.group_ids[key] = group_id
+            self.configs[key] = (config.data_type, config.with_hard_pin)
+            results.append(0)
+        return results
+
+    def put(self, key: str, value, config: FakeReplicateConfig) -> int:
+        self.calls.append("put")
+        if self.manifest_race_value is not None and key == self.manifest_race_key:
+            self.objects[key] = self.manifest_race_value
+            self.group_ids[key] = config.group_ids[0]
+            self.configs[key] = (config.data_type, config.with_hard_pin)
+            self.manifest_race_value = None
+            return 0
+        if key == self.fail_key:
+            return -1
+        if key in self.processing_keys:
+            return 0
+        if key in self.objects:
+            return 0
+        self.objects[key] = bytes(value)
+        self.group_ids[key] = config.group_ids[0]
+        self.configs[key] = (config.data_type, config.with_hard_pin)
+        if key == self.fail_after_write_key:
+            return -1
+        return 0
+
+    def get(self, key: str) -> bytes:
+        self.calls.append("get")
+        return self.objects[key]
+
+    def is_exist(self, key: str) -> int:
+        self.calls.append("is_exist")
+        return int(key in self.objects)
+
+    def batch_is_exist(self, keys: list[str]) -> list[int]:
+        self.calls.append("batch_is_exist")
+        self.exist_batch_sizes.append(len(keys))
+        results = [self.is_exist(key) for key in keys]
+        callback = self.after_batch_is_exist
+        self.after_batch_is_exist = None
+        if callback is not None:
+            callback()
+        return results
+
+    def remove(self, key: str, force: bool = False) -> int:
+        self.calls.append("remove")
+        self.removed_keys.append(key)
+        self.remove_forces.append(force)
+        self.objects.pop(key, None)
+        self.processing_keys.discard(key)
+        self.group_ids.pop(key, None)
+        return 0
+
+    def prepare_get_into_ranges_snapshot(self, keys: list[str]) -> tuple[str, ...]:
+        self.calls.append("prepare_get_into_ranges_snapshot")
+        self.snapshot_prepare_calls += 1
+        snapshot = tuple(keys)
+        self.snapshot_key_sets.append(snapshot)
+        return snapshot
+
+    def get_into_ranges_from_snapshot(
+        self,
+        snapshot: tuple[str, ...],
+        addresses: list[int],
+        all_keys: list[list[str]],
+        all_dst_offsets: list[list[list[int]]],
+        all_src_offsets: list[list[list[int]]],
+        all_sizes: list[list[list[int]]],
+    ) -> list[list[list[int]]]:
+        self.calls.append("get_into_ranges_from_snapshot")
+        self.snapshot_get_calls += 1
+        assert all(key in snapshot for keys in all_keys for key in keys)
+        return self.get_into_ranges(
+            addresses, all_keys, all_dst_offsets, all_src_offsets, all_sizes
+        )
+
+    def get_into_ranges(
+        self,
+        addresses: list[int],
+        all_keys: list[list[str]],
+        all_dst_offsets: list[list[list[int]]],
+        all_src_offsets: list[list[list[int]]],
+        all_sizes: list[list[list[int]]],
+    ) -> list[list[list[int]]]:
+        self.calls.append("get_into_ranges")
+        self.range_get_calls += 1
+        self.range_batch_sizes.append(
+            sum(len(sizes) for buffer in all_sizes for sizes in buffer)
+        )
+        results = []
+        for address, keys, dst_offsets, src_offsets, sizes in zip(
+            addresses,
+            all_keys,
+            all_dst_offsets,
+            all_src_offsets,
+            all_sizes,
+        ):
+            buffer_results = []
+            for key, dst_group, src_group, size_group in zip(
+                keys, dst_offsets, src_offsets, sizes
+            ):
+                object_data = self.objects[key]
+                range_results = []
+                for dst, src, size in zip(dst_group, src_group, size_group):
+                    self.range_sizes.append(size)
+                    ctypes.memmove(address + dst, object_data[src : src + size], size)
+                    range_results.append(size)
+                buffer_results.append(range_results)
+            results.append(buffer_results)
+        return results
+
+
+def tensor_descriptor() -> TensorDescriptor:
+    return TensorDescriptor(
+        tensor_id="layers.2.experts.3.w1",
+        global_shape=(8,),
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=(0,),
+        layer_id=2,
+        expert_id=3,
+        layout_fingerprint="sglang:qwen3.5:uint8:test",
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            OwnershipAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+
+
+def source_manifests(
+    dp: int = 2,
+    tp: int = 2,
+    *,
+    weight_generation: int = 1,
+) -> RuntimeInputs:
+    tensor = tensor_descriptor()
+    extent = tensor.global_shape[0] // tp
+    participants = []
+    for dp_rank in range(dp):
+        for tp_rank in range(tp):
+            start = tp_rank * extent
+            owner = (ctypes.c_ubyte * extent)(*range(start, start + extent))
+            worker_id = f"source-d{dp_rank}-t{tp_rank}"
+            placement_fragment_id = f"{worker_id}-placement"
+            rank = ParallelRank(dp=dp_rank, tp=tp_rank)
+            participants.append(
+                RuntimeParticipant(
+                    participant_id=worker_id,
+                    rank=rank,
+                    instance_id=worker_id,
+                    placement_fragments=(
+                        PlacementFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            tensor_id=tensor.tensor_id,
+                            global_offset=(start,),
+                            local_shape=(extent,),
+                            nbytes=extent,
+                            rank=rank,
+                        ),
+                    ),
+                    binding_fragments=(
+                        RuntimeBindingFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            fragment_id=f"{worker_id}-fragment",
+                            address=ctypes.addressof(owner),
+                            nbytes=extent,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=1,
+                            local_shape=(extent,),
+                            strides_bytes=(1,),
+                            storage_address=ctypes.addressof(owner),
+                            storage_nbytes=extent,
+                            storage_offset_bytes=0,
+                            owner=owner,
+                        ),
+                    ),
+                )
+            )
+    return make_runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        weight_generation=weight_generation,
+        placement_set_id=f"source-dp{dp}-tp{tp}",
+        tensors=(tensor,),
+        participants=tuple(participants),
+    )
+
+
+def target_manifests(
+    dp: int = 3,
+    tp: int = 4,
+    *,
+    weight_generation: int = 1,
+) -> RuntimeInputs:
+    tensor = tensor_descriptor()
+    extent = tensor.global_shape[0] // tp
+    participants = []
+    for dp_rank in range(dp):
+        for tp_rank in range(tp):
+            owner = (ctypes.c_ubyte * extent)(*[255] * extent)
+            worker_id = f"target-d{dp_rank}-t{tp_rank}"
+            placement_fragment_id = f"{worker_id}-placement"
+            rank = ParallelRank(dp=dp_rank, tp=tp_rank)
+            participants.append(
+                RuntimeParticipant(
+                    participant_id=worker_id,
+                    rank=rank,
+                    instance_id=worker_id,
+                    placement_fragments=(
+                        PlacementFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            tensor_id=tensor.tensor_id,
+                            global_offset=(tp_rank * extent,),
+                            local_shape=(extent,),
+                            nbytes=extent,
+                            rank=rank,
+                        ),
+                    ),
+                    binding_fragments=(
+                        RuntimeBindingFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            fragment_id=f"{worker_id}-fragment",
+                            address=ctypes.addressof(owner),
+                            nbytes=extent,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=1,
+                            local_shape=(extent,),
+                            strides_bytes=(1,),
+                            storage_address=ctypes.addressof(owner),
+                            storage_nbytes=extent,
+                            storage_offset_bytes=0,
+                            owner=owner,
+                        ),
+                    ),
+                )
+            )
+    return make_runtime_inputs(
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        weight_generation=weight_generation,
+        placement_set_id=f"target-dp{dp}-tp{tp}",
+        tensors=(tensor,),
+        participants=tuple(participants),
+    )
+
+
+def multi_dim_store_manifests(
+    prefix: str,
+    *,
+    source: bool,
+    target_dim: int = 2,
+) -> RuntimeInputs:
+    tensor = TensorDescriptor(
+        tensor_id="layers.0.experts.w1",
+        global_shape=(4, 6, 8),
+        dtype="uint8",
+        itemsize=1,
+        layer_id=0,
+        expert_id=None,
+        layout_fingerprint="framework:logical-contiguous:v2",
+        shard_dims=(0,) if source else (target_dim,),
+        parallel_axes=(
+            SplitAxis(
+                kind="ep" if source else "tp",
+                dim=0 if source else target_dim,
+            ),
+        ),
+    )
+    participants = []
+    rank_count = 4 if source else 2
+    for rank in range(rank_count):
+        if source:
+            offset = (rank, 0, 0)
+            shape = (1, 6, 8)
+            parallel_rank = ParallelRank(ep=rank)
+        else:
+            shape_list = list(tensor.global_shape)
+            shape_list[target_dim] //= rank_count
+            offset_list = [0, 0, 0]
+            offset_list[target_dim] = rank * shape_list[target_dim]
+            offset = tuple(offset_list)
+            shape = tuple(shape_list)
+            parallel_rank = ParallelRank(tp=rank)
+        values = []
+        for coordinate in product(*(range(extent) for extent in shape)):
+            global_coordinate = tuple(
+                begin + local for begin, local in _strict_zip(offset, coordinate)
+            )
+            values.append(
+                global_coordinate[0] * 48
+                + global_coordinate[1] * 8
+                + global_coordinate[2]
+                if source
+                else 255
+            )
+        owner = (ctypes.c_ubyte * prod(shape))(*values)
+        worker_id = f"{prefix}-{rank}"
+        placement_fragment_id = f"{worker_id}-placement"
+        participants.append(
+            RuntimeParticipant(
+                participant_id=worker_id,
+                rank=parallel_rank,
+                instance_id=worker_id,
+                placement_fragments=(
+                    PlacementFragment(
+                        placement_fragment_id=placement_fragment_id,
+                        tensor_id=tensor.tensor_id,
+                        global_offset=offset,
+                        local_shape=shape,
+                        nbytes=prod(shape),
+                        rank=parallel_rank,
+                    ),
+                ),
+                binding_fragments=(
+                    RuntimeBindingFragment(
+                        placement_fragment_id=placement_fragment_id,
+                        fragment_id=f"{worker_id}-fragment",
+                        address=ctypes.addressof(owner),
+                        nbytes=prod(shape),
+                        worker_id=worker_id,
+                        endpoint=f"{worker_id}:12345",
+                        device="cuda:0",
+                        itemsize=1,
+                        local_shape=shape,
+                        strides_bytes=(shape[1] * shape[2], shape[2], 1),
+                        storage_address=ctypes.addressof(owner),
+                        storage_nbytes=prod(shape),
+                        storage_offset_bytes=0,
+                        owner=owner,
+                    ),
+                ),
+            )
+        )
+    return make_runtime_inputs(
+        resource_id="qwen-family-moe",
+        revision="step-42",
+        placement_set_id=f"{prefix}-multi-dim-{target_dim}",
+        tensors=(tensor,),
+        participants=tuple(participants),
+    )
+
+
+def expected_multi_dim_fragment(fragment: PlacementFragment) -> bytes:
+    values = []
+    for coordinate in product(*(range(extent) for extent in fragment.local_shape)):
+        global_coordinate = tuple(
+            begin + local
+            for begin, local in _strict_zip(fragment.global_offset, coordinate)
+        )
+        values.append(
+            global_coordinate[0] * 48 + global_coordinate[1] * 8 + global_coordinate[2]
+        )
+    return bytes(values)
+
+
+def make_weight_store(
+    store: InMemoryStore | None = None,
+    *,
+    max_range_bytes: int = 64 * 1024 * 1024,
+    max_ranges_per_request: int = 1024,
+    max_region_segments: int = 1_000_000,
+):
+    current = store or InMemoryStore()
+    return current, GuardedWeightStore(
+        current,
+        config_factory=lambda group_ids, record_type: FakeReplicateConfig(
+            list(group_ids),
+            data_type=("WEIGHT" if record_type == "payload" else "METADATA"),
+            with_hard_pin=True,
+        ),
+        max_range_bytes=max_range_bytes,
+        max_ranges_per_request=max_ranges_per_request,
+        max_region_segments=max_region_segments,
+    )
+
+
+def rebuild_runtime_inputs(
+    inputs: RuntimeInputs,
+    *,
+    tensors: tuple[TensorDescriptor, ...] | None = None,
+    placement_fragments: dict[str, tuple[PlacementFragment, ...]] | None = None,
+    binding_fragments: dict[str, tuple[RuntimeBindingFragment, ...]] | None = None,
+) -> RuntimeInputs:
+    placement_updates = placement_fragments or {}
+    binding_updates = binding_fragments or {}
+    participants = []
+    for binding in inputs.bindings:
+        part = next(
+            item
+            for item in inputs.placement.parts
+            if item.participant_id == binding.participant_id
+        )
+        current_placements = placement_updates.get(
+            binding.participant_id, part.fragments
+        )
+        participants.append(
+            RuntimeParticipant(
+                participant_id=binding.participant_id,
+                rank=(current_placements[0].rank if current_placements else part.rank),
+                placement_fragments=current_placements,
+                binding_fragments=binding_updates.get(
+                    binding.participant_id, binding.fragments
+                ),
+                instance_id=binding.instance_id,
+                generation=binding.generation,
+                lease_id=binding.lease_id,
+            )
+        )
+    return make_runtime_inputs(
+        resource_id=inputs.placement.resource_id,
+        revision=inputs.placement.revision,
+        weight_generation=inputs.placement.weight_generation,
+        placement_set_id=inputs.placement.placement_set_id,
+        tensors=tensors if tensors is not None else inputs.placement.tensors,
+        participants=tuple(participants),
+    )
+
+
+def coalesce_runtime_inputs(
+    inputs: RuntimeInputs,
+    *,
+    instance_id: str,
+    worker_id: str | None = None,
+) -> RuntimeInputs:
+    if not inputs.bindings:
+        raise ValueError("runtime inputs must not be empty")
+    runtime_worker = worker_id or instance_id
+    placement_fragments = tuple(
+        replace(fragment, rank=ParallelRank())
+        for fragment in inputs.placement.fragments
+    )
+    binding_fragments = tuple(
+        replace(fragment, worker_id=runtime_worker)
+        for binding in inputs.bindings
+        for fragment in binding.fragments
+    )
+    generations = {binding.generation for binding in inputs.bindings}
+    if len(generations) != 1:
+        raise ValueError("runtime inputs have different generations")
+    return make_runtime_inputs(
+        resource_id=inputs.placement.resource_id,
+        revision=inputs.placement.revision,
+        weight_generation=inputs.placement.weight_generation,
+        placement_set_id=f"{inputs.placement.placement_set_id}-coalesced",
+        tensors=inputs.placement.tensors,
+        participants=(
+            RuntimeParticipant(
+                participant_id=instance_id,
+                rank=ParallelRank(),
+                placement_fragments=placement_fragments,
+                binding_fragments=binding_fragments,
+                instance_id=instance_id,
+                generation=generations.pop(),
+                lease_id=f"{instance_id}-lease",
+            ),
+        ),
+    )
+
+
+def upload_all(weight_store: WeightStore, plan, manifests: RuntimeInputs):
+    receipts = []
+    try:
+        for binding in manifests.bindings:
+            receipts.extend(weight_store.upload(plan, manifests.placement, binding))
+    except Exception:
+        weight_store.abort_upload(plan, receipts)
+        raise
+    return receipts
+
+
+def load_all(weight_store: WeightStore, plan, manifests: RuntimeInputs) -> None:
+    for binding in manifests.bindings:
+        weight_store.load(plan, manifests.placement, binding)
diff --git a/mooncake-reshard/tests/model_weight_store/test_contracts_and_planning.py b/mooncake-reshard/tests/model_weight_store/test_contracts_and_planning.py
new file mode 100644
index 0000000000..392f053b8a
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_contracts_and_planning.py
@@ -0,0 +1,377 @@
+from __future__ import annotations
+
+import json
+import pickle
+import weakref
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.contracts import StoredResourceManifest
+from mooncake.reshard.weight.manifest import OwnershipAxis, ParallelRank
+from mooncake.reshard.weight.storage_manifest import StoredWeightManifest
+
+from .helpers import (
+    RuntimeInputs,
+    make_weight_store,
+    plan_transfer,
+    rebuild_runtime_inputs,
+    source_manifests,
+    target_manifests,
+    tensor_descriptor,
+    upload_all,
+    with_empty_participant,
+)
+
+
+def test_upload_deduplicates_dp_and_commits_manifest_last() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests()
+
+    plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    receipts = upload_all(weight_store, plan, sources)
+
+    assert len(plan.operations) == 2
+    assert len(receipts) == 2
+    assert plan.manifest.manifest_key not in store.objects
+    assert len(store.objects) == 2
+
+    manifest = weight_store.commit_upload(plan, receipts)
+
+    assert (
+        StoredWeightManifest.from_json(store.objects[manifest.manifest_key]) == manifest
+    )
+    assert len(store.objects) == 4
+    revision_keys = {
+        manifest.manifest_key,
+        *(operation.target.object_key for operation in plan.operations),
+    }
+    assert {store.group_ids[key] for key in revision_keys} == {manifest.group_id}
+    assert store.group_ids[plan.control_key] == plan.transaction_group_id
+    assert plan.transaction_group_id != manifest.group_id
+    assert store.register_calls == 2
+    assert store.unregister_calls == 2
+    assert store.registered == set()
+
+
+def test_store_manifest_json_round_trip_persists_weight_generation() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2, weight_generation=17)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    persisted = weight_store.commit_upload(
+        plan,
+        upload_all(weight_store, plan, sources),
+    )
+    raw = store.objects[persisted.manifest_key]
+    decoded = StoredWeightManifest.from_json(raw)
+
+    assert json.loads(raw)["weight_generation"] == 17
+    assert decoded.weight_generation == 17
+    assert decoded == persisted == plan.manifest
+
+
+def test_stored_weight_manifest_implements_stored_resource_contract() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    stored: StoredResourceManifest = weight_store.commit_upload(
+        plan,
+        upload_all(weight_store, plan, sources),
+    )
+
+    assert isinstance(stored, StoredResourceManifest)
+    assert stored.resource_id == sources.placement.resource_id
+    assert stored.resource_kind.value == "model_weight"
+    assert stored.manifest_key == plan.manifest.manifest_key
+
+
+def test_stored_resource_manifest_requires_a_concrete_resource_kind() -> None:
+    with pytest.raises(TypeError, match="abstract"):
+        StoredResourceManifest(
+            namespace="test",
+            resource_id="model",
+            group_id="weights/test/model/revision",
+            manifest_key="weights/test/model/revision/manifest",
+            created_at="2026-08-29T00:00:00Z",
+        )
+
+
+def test_stored_weight_manifest_pickle_restores_validated_snapshot() -> None:
+    _store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(source.placement, source.bindings)
+
+    restored = pickle.loads(pickle.dumps(plan.manifest))
+
+    assert restored == plan.manifest
+    assert restored.manifest_digest == plan.manifest.manifest_digest
+
+
+def test_plan_upload_does_not_require_binding_for_empty_participant() -> None:
+    _store, weight_store = make_weight_store()
+    sources = with_empty_participant(
+        source_manifests(dp=1, tp=1),
+        participant_id="inactive-pp1",
+        rank=ParallelRank(pp=1),
+    )
+
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    assert len(plan.operations) == 1
+
+
+def test_plan_upload_keeps_owner_free_runtime_evidence() -> None:
+    class AllocationOwner:
+        pass
+
+    sources = source_manifests(dp=1, tp=1)
+    owner = AllocationOwner()
+    owner_ref = weakref.ref(owner)
+    sources = RuntimeInputs(
+        sources.placement,
+        (
+            replace(
+                sources.bindings[0],
+                fragments=(replace(sources.bindings[0].fragments[0], owner=owner),),
+            ),
+        ),
+    )
+    _store, weight_store = make_weight_store()
+
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    assert not hasattr(plan.operations[0].source_snapshot, "owner")
+    del owner
+    del sources
+    assert owner_ref() is None
+
+
+def test_plan_upload_explicitly_rejects_dp_owned_source_tensors() -> None:
+    """Store snapshots still require one complete replicated DP source."""
+
+    sources = source_manifests(dp=1, tp=1)
+    tensor = replace(
+        tensor_descriptor(),
+        shard_dims=(),
+        parallel_axes=(
+            OwnershipAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            OwnershipAxis(kind="ep"),
+        ),
+    )
+    sources = rebuild_runtime_inputs(sources, tensors=(tensor,))
+    _store, weight_store = make_weight_store()
+
+    with pytest.raises(ValueError, match="requires replicated DP source tensors"):
+        weight_store.plan_upload(sources.placement, sources.bindings)
+
+
+def test_plan_upload_rejects_missing_nonempty_participant_binding() -> None:
+    sources = source_manifests(dp=1, tp=2)
+    tensors = (
+        replace(
+            tensor_descriptor(),
+            tensor_id="layers.0.mlp.weight",
+            global_shape=(4,),
+            expert_id=None,
+        ),
+        replace(
+            tensor_descriptor(),
+            tensor_id="layers.1.mlp.weight",
+            global_shape=(4,),
+            expert_id=None,
+        ),
+    )
+    fragments = {}
+    for index, part in enumerate(sources.placement.parts):
+        fragments[part.participant_id] = (
+            replace(
+                part.fragments[0],
+                tensor_id=tensors[index].tensor_id,
+                global_offset=(0,),
+                local_shape=(4,),
+                rank=ParallelRank(pp=index),
+            ),
+        )
+    sources = rebuild_runtime_inputs(
+        sources,
+        tensors=tensors,
+        placement_fragments=fragments,
+    )
+    _store, weight_store = make_weight_store()
+
+    with pytest.raises(
+        ValueError, match="no complete generation-consistent DP replica"
+    ):
+        weight_store.plan_upload(
+            sources.placement,
+            (sources.bindings[0],),
+        )
+
+
+def test_same_revision_different_generations_have_disjoint_store_identity() -> None:
+    store, weight_store = make_weight_store()
+    generation_17 = source_manifests(dp=1, tp=2, weight_generation=17)
+    generation_18 = source_manifests(dp=1, tp=2, weight_generation=18)
+
+    plan_17 = weight_store.plan_upload(
+        generation_17.placement,
+        generation_17.bindings,
+    )
+    plan_18 = weight_store.plan_upload(
+        generation_18.placement,
+        generation_18.bindings,
+    )
+
+    assert generation_17.placement.revision == generation_18.placement.revision
+    assert generation_17.placement.placement_id != generation_18.placement.placement_id
+    assert generation_17.placement.digest != generation_18.placement.digest
+    assert plan_17.manifest.group_id.endswith("/17")
+    assert plan_18.manifest.group_id.endswith("/18")
+    assert plan_17.manifest.group_id != plan_18.manifest.group_id
+    assert plan_17.manifest.manifest_key != plan_18.manifest.manifest_key
+    assert {operation.target.object_key for operation in plan_17.operations}.isdisjoint(
+        operation.target.object_key for operation in plan_18.operations
+    )
+    assert all(
+        operation.target.object_key.startswith(f"{plan_17.manifest.group_id}/")
+        for operation in plan_17.operations
+    )
+    assert all(
+        operation.target.object_key.startswith(f"{plan_18.manifest.group_id}/")
+        for operation in plan_18.operations
+    )
+
+    manifest_17 = weight_store.commit_upload(
+        plan_17,
+        upload_all(weight_store, plan_17, generation_17),
+    )
+    manifest_18 = weight_store.commit_upload(
+        plan_18,
+        upload_all(weight_store, plan_18, generation_18),
+    )
+
+    assert weight_store.load_manifest(manifest_17.manifest_key) == manifest_17
+    assert weight_store.load_manifest(manifest_18.manifest_key) == manifest_18
+    assert manifest_17 != manifest_18
+
+
+def test_plan_upload_selects_one_complete_generation_consistent_dp_replica() -> None:
+    sources = source_manifests(dp=2, tp=2)
+    rank_by_participant = {
+        part.participant_id: part.rank for part in sources.placement.parts
+    }
+    sources = RuntimeInputs(
+        sources.placement,
+        tuple(
+            replace(
+                binding,
+                generation=(
+                    3
+                    if rank_by_participant[binding.participant_id].dp == 1
+                    and rank_by_participant[binding.participant_id].tp == 1
+                    else 2
+                ),
+            )
+            for binding in sources.bindings
+        ),
+    )
+
+    _, weight_store = make_weight_store()
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    assert {operation.source_placement.rank.dp for operation in plan.operations} == {0}
+    assert {operation.source_generation for operation in plan.operations} == {2}
+
+
+def test_plan_upload_rejects_complete_dp_replicas_at_different_generations() -> None:
+    sources = source_manifests(dp=2, tp=2)
+    rank_by_participant = {
+        part.participant_id: part.rank for part in sources.placement.parts
+    }
+    sources = RuntimeInputs(
+        sources.placement,
+        tuple(
+            replace(
+                binding,
+                generation=rank_by_participant[binding.participant_id].dp + 1,
+            )
+            for binding in sources.bindings
+        ),
+    )
+    _, weight_store = make_weight_store()
+
+    with pytest.raises(ValueError, match="inconsistent lease generations"):
+        weight_store.plan_upload(sources.placement, sources.bindings)
+
+
+def test_plan_upload_rejects_mixed_generations_within_one_dp_replica() -> None:
+    sources = source_manifests(dp=1, tp=2)
+    sources = RuntimeInputs(
+        sources.placement,
+        (sources.bindings[0], replace(sources.bindings[1], generation=2)),
+    )
+    _, weight_store = make_weight_store()
+
+    with pytest.raises(ValueError, match="generation-consistent DP replica"):
+        weight_store.plan_upload(sources.placement, sources.bindings)
+
+
+def test_plan_upload_matches_te_planner_dp_replica_selection() -> None:
+    sources = source_manifests(dp=2, tp=2)
+    targets = target_manifests(dp=1, tp=1)
+    _, weight_store = make_weight_store()
+
+    te_plan = plan_transfer(sources, targets)
+    store_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    assert {operation.source.rank.dp for operation in te_plan.operations} == {0}
+    assert {
+        operation.source_placement.rank.dp for operation in store_plan.operations
+    } == {0}
+
+
+def test_global_placement_rejects_cross_owner_coverage_before_store() -> None:
+    sources = source_manifests(dp=1, tp=2)
+    fragments = {}
+    for part in sources.placement.parts:
+        fragments[part.participant_id] = tuple(
+            replace(
+                fragment,
+                rank=replace(fragment.rank, pp=fragment.rank.tp, ep=fragment.rank.tp),
+            )
+            for fragment in part.fragments
+        )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        rebuild_runtime_inputs(sources, placement_fragments=fragments)
+
+
+def test_plan_upload_rejects_dense_tp_shards_across_ep_replicas() -> None:
+    tensor = replace(
+        tensor_descriptor(),
+        tensor_id="layers.2.self_attn.q_proj.weight",
+        expert_id=None,
+    )
+    sources = source_manifests(dp=1, tp=2)
+    fragments = {
+        part.participant_id: tuple(
+            replace(
+                fragment,
+                tensor_id=tensor.tensor_id,
+                rank=replace(fragment.rank, ep=fragment.rank.tp),
+            )
+            for fragment in part.fragments
+        )
+        for part in sources.placement.parts
+    }
+    with pytest.raises(ValueError, match="not fully covered"):
+        rebuild_runtime_inputs(
+            sources,
+            tensors=(tensor,),
+            placement_fragments=fragments,
+        )
diff --git a/mooncake-reshard/tests/model_weight_store/test_lifetime_guards.py b/mooncake-reshard/tests/model_weight_store/test_lifetime_guards.py
new file mode 100644
index 0000000000..0879028e79
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_lifetime_guards.py
@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.lifetime import TerminalTransferState
+from mooncake.reshard.weight.store import WeightStore, WeightStoreError
+
+from .helpers import (
+    FakeReplicateConfig,
+    InMemoryStore,
+    allocation_guards_for_bindings,
+    make_weight_store,
+    source_manifests,
+    target_manifests,
+    upload_all,
+)
+
+
+def _raw_store(store: InMemoryStore) -> WeightStore:
+    return WeightStore(
+        store,
+        config_factory=lambda group_ids, record_type: FakeReplicateConfig(
+            list(group_ids),
+            data_type=("WEIGHT" if record_type == "payload" else "METADATA"),
+            with_hard_pin=True,
+        ),
+    )
+
+
+def test_store_rejects_raw_gpu_addresses_without_allocation_guards() -> None:
+    store = InMemoryStore()
+    weight_store = _raw_store(store)
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    with pytest.raises(WeightStoreError, match="source allocation guard providers"):
+        weight_store.upload(plan, sources.placement, sources.binding)
+
+    assert store.register_calls == 0
+    assert store.put_batches == []
+
+
+def test_store_upload_releases_pin_after_sync_completion() -> None:
+    store = InMemoryStore()
+    weight_store = _raw_store(store)
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    guards = allocation_guards_for_bindings((sources.binding,))
+
+    weight_store.upload(
+        plan,
+        sources.placement,
+        sources.binding,
+        source_allocation_guards=guards,
+    )
+
+    token = next(iter(guards.values())).tokens[0]
+    assert token.released_states == [TerminalTransferState.COMPLETED]
+    assert store.registered == set()
+
+
+def test_store_quarantines_pin_until_unregister_cleanup_succeeds() -> None:
+    store = InMemoryStore()
+    weight_store = _raw_store(store)
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    guards = allocation_guards_for_bindings((sources.binding,))
+    address = sources.binding.fragments[0].address
+    store.unregister_results[address] = -9
+
+    with pytest.raises(WeightStoreError, match="allocation lifetime is quarantined"):
+        weight_store.upload(
+            plan,
+            sources.placement,
+            sources.binding,
+            source_allocation_guards=guards,
+        )
+
+    token = next(iter(guards.values())).tokens[0]
+    assert token.released_states == []
+    (pending_id,) = weight_store.pending_registration_ids()
+    with pytest.raises(WeightStoreError, match="blocked by pending registration"):
+        weight_store.upload(
+            plan,
+            sources.placement,
+            sources.binding,
+            source_allocation_guards=allocation_guards_for_bindings((sources.binding,)),
+        )
+
+    store.unregister_results.pop(address)
+    weight_store.drain_pending_registration(pending_id)
+
+    assert token.released_states == [TerminalTransferState.COMPLETED]
+    assert weight_store.pending_registration_ids() == ()
+    assert store.registered == set()
+
+
+def test_store_load_holds_target_pin_through_sync_ranged_read() -> None:
+    store, staging_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    upload_plan = staging_store.plan_upload(sources.placement, sources.bindings)
+    manifest = staging_store.commit_upload(
+        upload_plan,
+        upload_all(staging_store, upload_plan, sources),
+    )
+    target = target_manifests(dp=1, tp=1)[0]
+    raw_store = _raw_store(store)
+    load_plan = raw_store.plan_load(manifest, target.placement, target.bindings)
+    guards = allocation_guards_for_bindings((target.binding,))
+
+    raw_store.load(
+        load_plan,
+        target.placement,
+        target.binding,
+        target_allocation_guards=guards,
+    )
+
+    token = next(iter(guards.values())).tokens[0]
+    assert token.released_states == [TerminalTransferState.COMPLETED]
+    assert store.registered == set()
+
+
+def test_typed_pre_registered_lease_retains_pin_until_explicit_close() -> None:
+    store = InMemoryStore()
+    weight_store = _raw_store(store)
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    guards = allocation_guards_for_bindings((sources.binding,))
+    lease = weight_store.register_weight_buffers(
+        sources.binding,
+        fragment_ids=tuple(
+            operation.source_snapshot.fragment_id for operation in plan.operations
+        ),
+        allocation_guards=guards,
+        side="source",
+    )
+
+    weight_store.upload(
+        plan,
+        sources.placement,
+        sources.binding,
+        registration_lease=lease,
+    )
+
+    token = next(iter(guards.values())).tokens[0]
+    assert token.released_states == []
+    assert store.registered == {sources.binding.fragments[0].address}
+
+    lease.close()
+
+    assert token.released_states == [TerminalTransferState.COMPLETED]
+    assert store.registered == set()
+
+
+def test_typed_lease_cleanup_failure_quarantines_and_closes_lease() -> None:
+    store = InMemoryStore()
+    weight_store = _raw_store(store)
+    sources = source_manifests(dp=1, tp=1)
+    guards = allocation_guards_for_bindings((sources.binding,))
+    address = sources.binding.fragments[0].address
+    lease = weight_store.register_weight_buffers(
+        sources.binding,
+        fragment_ids=(sources.binding.fragments[0].fragment_id,),
+        allocation_guards=guards,
+        side="source",
+    )
+    token = next(iter(guards.values())).tokens[0]
+    store.unregister_results[address] = -9
+
+    with pytest.raises(WeightStoreError, match="allocation lifetime is quarantined"):
+        lease.close()
+
+    assert token.released_states == []
+    (pending_id,) = weight_store.pending_registration_ids()
+    assert lease.closed is True
+
+    store.unregister_results.pop(address)
+    weight_store.drain_pending_registration(pending_id)
+
+    assert token.released_states == [TerminalTransferState.COMPLETED]
+    lease.close()
+    assert store.registered == set()
diff --git a/mooncake-reshard/tests/model_weight_store/test_load_and_ranged_read.py b/mooncake-reshard/tests/model_weight_store/test_load_and_ranged_read.py
new file mode 100644
index 0000000000..31b505621b
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_load_and_ranged_read.py
@@ -0,0 +1,840 @@
+from __future__ import annotations
+
+import ctypes
+import copy
+from dataclasses import replace
+from itertools import product
+from math import prod
+
+import pytest
+
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    OwnershipAxis,
+    ReplicatedAxis,
+    SplitAxis,
+)
+from mooncake.reshard.weight.store import WeightStoreError
+from mooncake.reshard.weight.store import WeightStore
+from mooncake.reshard.weight._store.contracts import WeightLoadPlan
+from mooncake.reshard.weight._store.validation import same_runtime_snapshot
+
+from .helpers import (
+    RuntimeInputs,
+    RuntimeParticipant,
+    allocation_guards_for_bindings,
+    bound_fragments,
+    coalesce_runtime_inputs,
+    expected_multi_dim_fragment,
+    load_all,
+    make_runtime_inputs,
+    make_weight_store,
+    multi_dim_store_manifests,
+    rebuild_runtime_inputs,
+    source_manifests,
+    target_manifests,
+    upload_all,
+    with_empty_participant,
+)
+
+
+def runtime_fragment_for_snapshot(**overrides) -> RuntimeBindingFragment:
+    values = {
+        "placement_fragment_id": "placement-0",
+        "fragment_id": "runtime-0",
+        "address": 0x1000,
+        "nbytes": 8,
+        "worker_id": "worker-0",
+        "endpoint": "worker-0:12345",
+        "device": "cuda:0",
+        "itemsize": 2,
+        "local_shape": (2, 2),
+        "strides_bytes": (4, 2),
+        "storage_address": 0x0FF0,
+        "storage_nbytes": 32,
+        "storage_offset_bytes": 16,
+    }
+    values.update(overrides)
+    return RuntimeBindingFragment(**values)
+
+
+@pytest.mark.parametrize(
+    ("field", "different_value"),
+    [
+        ("placement_fragment_id", "placement-1"),
+        ("fragment_id", "runtime-1"),
+        ("address", 0x1001),
+        ("nbytes", 4),
+        ("worker_id", "worker-1"),
+        ("endpoint", "worker-1:12345"),
+        ("device", "cuda:1"),
+        ("itemsize", 1),
+        ("local_shape", (1, 4)),
+        ("strides_bytes", (8, 2)),
+        ("storage_address", 0x0FE0),
+        ("storage_nbytes", 64),
+        ("storage_offset_bytes", 8),
+    ],
+)
+def test_same_runtime_snapshot_compares_all_physical_evidence(
+    field: str,
+    different_value: object,
+) -> None:
+    current = runtime_fragment_for_snapshot()
+    planned = copy.copy(current)
+    object.__setattr__(planned, field, different_value)
+
+    assert not same_runtime_snapshot(current, planned)
+
+
+def test_same_runtime_snapshot_ignores_owner() -> None:
+    current = runtime_fragment_for_snapshot(owner=object())
+    planned = replace(current, owner=object())
+
+    assert same_runtime_snapshot(current, planned)
+
+
+@pytest.mark.parametrize("target_dim", [1, 2])
+def test_store_preserves_expert_boxes_and_loads_cross_dim(
+    target_dim: int,
+) -> None:
+    store, weight_store = make_weight_store(max_ranges_per_request=5)
+    sources = multi_dim_store_manifests("source", source=True)
+    targets = multi_dim_store_manifests("target", source=False, target_dim=target_dim)
+
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+
+    assert upload_plan.manifest.tensors[0].shard_dims == (0,)
+    assert len(upload_plan.operations) == 4
+    assert len({item.target.object_key for item in upload_plan.operations}) == 4
+    assert {item.target.global_offset for item in upload_plan.operations} == {
+        (rank, 0, 0) for rank in range(4)
+    }
+
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    loaded = weight_store.load_manifest(manifest.manifest_key)
+    load_plan = weight_store.plan_load(loaded, targets.placement, targets.bindings)
+    load_all(weight_store, load_plan, targets)
+
+    assert loaded == manifest
+    assert all(route.source_pp is None for route in load_plan.transfer.pipeline_routes)
+    assert max(store.range_batch_sizes) <= 5
+    for target in bound_fragments(targets):
+        assert bytes(target.owner) == expected_multi_dim_fragment(target.placement)
+
+
+class _ManifestOnlyReader:
+    def __init__(self, store) -> None:
+        self._store = store
+
+    def get(self, key: str) -> bytes:
+        return self._store.get(key)
+
+    def is_exist(self, key: str) -> int:
+        return self._store.is_exist(key)
+
+    def register_buffer(self, address: int, nbytes: int) -> int:
+        return self._store.register_buffer(address, nbytes)
+
+    def unregister_buffer(self, address: int) -> int:
+        return self._store.unregister_buffer(address)
+
+    def get_into_ranges(self, *args):
+        return self._store.get_into_ranges(*args)
+
+    def __getattr__(self, name: str):
+        if name in {
+            "prepare_get_into_ranges_snapshot",
+            "get_into_ranges_from_snapshot",
+        }:
+            raise AttributeError(name)
+        raise AssertionError(f"manifest restore accessed legacy Store API: {name}")
+
+
+def test_restore_reconstructs_from_stored_manifest_without_legacy_tensor_metadata() -> (
+    None
+):
+    store, writer = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    targets = target_manifests(dp=1, tp=4)
+    upload_plan = writer.plan_upload(sources.placement, sources.bindings)
+    manifest = writer.commit_upload(
+        upload_plan, upload_all(writer, upload_plan, sources)
+    )
+    reader = WeightStore(_ManifestOnlyReader(store))
+
+    loaded = reader.load_manifest(manifest.manifest_key)
+    load_plan = reader.plan_load(loaded, targets.placement, targets.bindings)
+    for binding in targets.bindings:
+        reader.load(
+            load_plan,
+            targets.placement,
+            binding,
+            target_allocation_guards=allocation_guards_for_bindings((binding,)),
+        )
+
+    assert loaded == manifest
+    for fragment in bound_fragments(targets):
+        start = fragment.global_offset[0]
+        assert bytes(fragment.owner) == bytes(range(start, start + fragment.nbytes))
+
+
+def test_store_commit_preserves_mixed_single_axis_descriptor() -> None:
+    single_axis = TensorDescriptor(
+        tensor_id="layers.0.attn.qkv",
+        global_shape=(4,),
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=(0,),
+        layer_id=0,
+        expert_id=None,
+        layout_fingerprint="framework:single-axis-contiguous",
+        parallel_axes=(SplitAxis(kind="ep", dim=0),),
+    )
+    sources = multi_dim_store_manifests("source", source=True)
+    placement_updates = {}
+    binding_updates = {}
+    for rank, binding in enumerate(sources.bindings):
+        part = next(
+            item
+            for item in sources.placement.parts
+            if item.participant_id == binding.participant_id
+        )
+        owner = (ctypes.c_ubyte * 1)(rank)
+        placement_fragment_id = f"source-{rank}-single-axis-placement"
+        single_axis_placement = PlacementFragment(
+            placement_fragment_id=placement_fragment_id,
+            tensor_id=single_axis.tensor_id,
+            global_offset=(rank,),
+            local_shape=(1,),
+            nbytes=1,
+            rank=part.rank,
+        )
+        single_axis_binding = RuntimeBindingFragment(
+            placement_fragment_id=placement_fragment_id,
+            fragment_id=f"source-{rank}-single-axis",
+            address=ctypes.addressof(owner),
+            nbytes=1,
+            worker_id=binding.fragments[0].worker_id,
+            endpoint=binding.fragments[0].endpoint,
+            device="cuda:0",
+            itemsize=1,
+            local_shape=(1,),
+            strides_bytes=(1,),
+            storage_address=ctypes.addressof(owner),
+            storage_nbytes=1,
+            storage_offset_bytes=0,
+            owner=owner,
+        )
+        placement_updates[part.participant_id] = (
+            *part.fragments,
+            single_axis_placement,
+        )
+        binding_updates[binding.participant_id] = (
+            *binding.fragments,
+            single_axis_binding,
+        )
+    sources = rebuild_runtime_inputs(
+        sources,
+        tensors=(*sources.placement.tensors, single_axis),
+        placement_fragments=placement_updates,
+        binding_fragments=binding_updates,
+    )
+
+    _store, weight_store = make_weight_store()
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    persisted = weight_store.commit_upload(
+        upload_plan,
+        upload_all(weight_store, upload_plan, sources),
+    )
+    loaded = weight_store.load_manifest(persisted.manifest_key)
+
+    assert loaded == persisted == upload_plan.manifest
+    loaded_single_axis = next(
+        tensor for tensor in loaded.tensors if tensor.tensor_id == single_axis.tensor_id
+    )
+    assert loaded_single_axis.shard_dims == (0,)
+
+
+def test_load_rejects_payloads_without_committed_manifest() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    targets = target_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    upload_all(weight_store, upload_plan, sources)
+    load_plan = weight_store.plan_load(
+        upload_plan.manifest,
+        targets.placement,
+        targets.bindings,
+    )
+    register_calls = store.register_calls
+    range_get_calls = store.range_get_calls
+
+    with pytest.raises(WeightStoreError, match="manifest is not committed"):
+        weight_store.load(load_plan, targets[0].placement, targets[0].binding)
+
+    assert store.register_calls == register_calls
+    assert store.range_get_calls == range_get_calls
+
+
+def test_store_multi_dim_lowering_limit_fails_before_registration_or_read() -> None:
+    store, weight_store = make_weight_store(max_region_segments=5)
+    sources = multi_dim_store_manifests("source", source=True)
+    targets = multi_dim_store_manifests("target", source=False, target_dim=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    register_calls = store.register_calls
+    range_get_calls = store.range_get_calls
+
+    with pytest.raises(WeightStoreError, match="max_region_segments"):
+        weight_store.load(load_plan, targets[0].placement, targets[0].binding)
+
+    assert store.register_calls == register_calls
+    assert store.range_get_calls == range_get_calls
+
+
+def test_load_reshards_tp_and_fans_out_dp_across_target_participants() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=2, tp=2)
+    upload_plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=3, tp=4)
+
+    loaded_manifest = weight_store.load_manifest(manifest.manifest_key)
+    load_plan = weight_store.plan_load(
+        loaded_manifest, targets.placement, targets.bindings
+    )
+    load_all(weight_store, load_plan, targets)
+
+    assert load_plan.transfer.total_bytes == 3 * 8
+    assert store.range_get_calls == len(targets)
+    for fragment in bound_fragments(targets):
+        start = fragment.global_offset[0]
+        assert bytes(fragment.owner) == bytes(range(start, start + fragment.nbytes))
+    assert store.register_calls == 2 + len(targets)
+    assert store.unregister_calls == 2 + len(targets)
+    assert store.registered == set()
+
+
+def test_store_round_trip_moves_layers_and_experts_across_all_parallel_axes() -> None:
+    def make_manifests(*, dp: int, tp: int, source: bool):
+        tensors = {}
+        participants = []
+        for layer_id, expert_id, dp_rank, tp_rank in product(
+            range(2), range(2), range(dp), range(tp)
+        ):
+            tensor_index = layer_id * 2 + expert_id
+            tensor = TensorDescriptor(
+                tensor_id=f"layers.{layer_id}.experts.{expert_id}.w1",
+                global_shape=(8,),
+                dtype="uint8",
+                itemsize=1,
+                shard_dims=(0,),
+                layer_id=layer_id,
+                expert_id=expert_id,
+                layout_fingerprint="sglang:qwen3.5:uint8:test",
+                parallel_axes=(
+                    ReplicatedAxis(kind="dp"),
+                    OwnershipAxis(kind="pp"),
+                    OwnershipAxis(kind="ep"),
+                    SplitAxis(kind="tp", dim=0),
+                ),
+            )
+            tensors[tensor.tensor_id] = tensor
+            extent = 8 // tp
+            offset = tp_rank * extent
+            values = (
+                range(tensor_index * 16 + offset, tensor_index * 16 + offset + extent)
+                if source
+                else [255] * extent
+            )
+            owner = (ctypes.c_ubyte * extent)(*values)
+            prefix = "source" if source else "target"
+            worker_id = f"{prefix}-l{layer_id}-e{expert_id}-d{dp_rank}-t{tp_rank}"
+            placement_fragment_id = f"{worker_id}-placement"
+            rank = ParallelRank(
+                dp=dp_rank,
+                tp=tp_rank,
+                pp=layer_id if source else 1 - layer_id,
+                ep=expert_id if source else 1 - expert_id,
+            )
+            participants.append(
+                RuntimeParticipant(
+                    participant_id=worker_id,
+                    rank=rank,
+                    instance_id=worker_id,
+                    placement_fragments=(
+                        PlacementFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            tensor_id=tensor.tensor_id,
+                            global_offset=(offset,),
+                            local_shape=(extent,),
+                            nbytes=extent,
+                            rank=rank,
+                        ),
+                    ),
+                    binding_fragments=(
+                        RuntimeBindingFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            fragment_id=f"{worker_id}-fragment",
+                            address=ctypes.addressof(owner),
+                            nbytes=extent,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=1,
+                            local_shape=(extent,),
+                            strides_bytes=(1,),
+                            storage_address=ctypes.addressof(owner),
+                            storage_nbytes=extent,
+                            storage_offset_bytes=0,
+                            owner=owner,
+                        ),
+                    ),
+                )
+            )
+        return make_runtime_inputs(
+            resource_id="qwen3.5-moe",
+            revision="step-42",
+            placement_set_id=f"{prefix}-all-axes-dp{dp}-tp{tp}",
+            tensors=tuple(tensors.values()),
+            participants=tuple(participants),
+        )
+
+    sources = make_manifests(dp=2, tp=2, source=True)
+    targets = make_manifests(dp=3, tp=4, source=False)
+    store, weight_store = make_weight_store()
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+
+    load_all(weight_store, load_plan, targets)
+
+    assert len(upload_plan.operations) == 4 * 2
+    assert load_plan.transfer.total_bytes == 4 * 3 * 8
+    for fragment in bound_fragments(targets):
+        tensor = next(
+            item
+            for item in targets.placement.tensors
+            if item.tensor_id == fragment.tensor_id
+        )
+        tensor_index = tensor.layer_id * 2 + tensor.expert_id
+        begin = tensor_index * 16 + fragment.global_offset[0]
+        assert bytes(fragment.owner) == bytes(range(begin, begin + fragment.nbytes))
+
+
+def test_load_merges_store_fragments_for_larger_target_shards() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=4)
+    upload_plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=2)
+
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    load_all(weight_store, load_plan, targets)
+
+    assert len(load_plan.transfer.operations) == 4
+    target_fragments = bound_fragments(targets)
+    assert bytes(target_fragments[0].owner) == bytes(range(4))
+    assert bytes(target_fragments[1].owner) == bytes(range(4, 8))
+
+
+def test_load_rejects_partial_range_result() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=4)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    original = store.get_into_ranges
+
+    def partial(*args, **kwargs):
+        results = original(*args, **kwargs)
+        results[0][0][0] -= 1
+        return results
+
+    store.get_into_ranges = partial
+    with pytest.raises(WeightStoreError, match="get_into_ranges failed"):
+        weight_store.load(load_plan, targets[0].placement, targets[0].binding)
+
+
+def test_load_surfaces_scalar_get_into_ranges_error() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=4)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    store.get_into_ranges = lambda *args, **kwargs: -19
+
+    with pytest.raises(WeightStoreError, match="get_into_ranges failed: -19"):
+        weight_store.load(load_plan, targets[0].placement, targets[0].binding)
+
+
+def test_plan_load_rejects_different_target_weight_generation() -> None:
+    _store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2, weight_generation=7)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan,
+        upload_all(weight_store, upload_plan, sources),
+    )
+    targets = target_manifests(dp=1, tp=4, weight_generation=8)
+
+    with pytest.raises(WeightStoreError, match="target placement revision mismatch"):
+        weight_store.plan_load(manifest, targets.placement, targets.bindings)
+
+
+def test_load_plan_rejects_transfer_weight_generation_mismatch() -> None:
+    _store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2, weight_generation=7)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan,
+        upload_all(weight_store, upload_plan, sources),
+    )
+    targets = target_manifests(dp=1, tp=4, weight_generation=7)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+
+    # WeightLoadPlan remains fail-closed if a decoded/foreign plan has bypassed
+    # TransferPlan construction. A normal replacement fails even earlier at the
+    # live target attestation boundary.
+    object.__setattr__(
+        load_plan.transfer,
+        "weight_generation",
+        manifest.weight_generation + 1,
+    )
+
+    with pytest.raises(ValueError, match="load plan transfer and manifest identity"):
+        WeightLoadPlan(
+            manifest=manifest,
+            transfer=load_plan.transfer,
+        )
+
+
+def test_plan_load_does_not_require_binding_for_empty_participant() -> None:
+    _store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan,
+        upload_all(weight_store, upload_plan, sources),
+    )
+    targets = with_empty_participant(
+        target_manifests(dp=1, tp=1),
+        participant_id="inactive-pp1",
+        rank=ParallelRank(pp=1),
+    )
+
+    load_plan = weight_store.plan_load(
+        manifest,
+        targets.placement,
+        targets.bindings,
+    )
+
+    assert len(load_plan.transfer.operations) == 1
+
+
+def test_load_rejects_stale_target_generation() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=4)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    stale_binding = replace(targets.bindings[0], generation=2)
+
+    with pytest.raises(WeightStoreError, match="target executor snapshot mismatch"):
+        weight_store.load(load_plan, targets.placement, stale_binding)
+
+
+def test_load_rejects_generation_scoped_target_id_rollover() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=4)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    replacement = replace(
+        targets.bindings[0].fragments[0],
+        fragment_id="replacement-target-fragment",
+    )
+    current = replace(
+        targets.bindings[0],
+        generation=2,
+        fragments=(replacement,),
+    )
+
+    with pytest.raises(WeightStoreError, match="target executor snapshot mismatch"):
+        weight_store.load(load_plan, targets.placement, current)
+
+
+def test_load_rejects_worker_and_generation_rollover_instead_of_succeeding_noop() -> (
+    None
+):
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=4)
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    replacement = replace(
+        targets.bindings[0].fragments[0],
+        fragment_id="replacement-target-fragment",
+        worker_id="replacement-target-worker",
+    )
+    current = replace(
+        targets.bindings[0],
+        instance_id="replacement-target-instance",
+        generation=2,
+        fragments=(replacement,),
+    )
+
+    with pytest.raises(WeightStoreError, match="target executor snapshot mismatch"):
+        weight_store.load(load_plan, targets.placement, current)
+
+
+def test_load_chunks_large_ranges_to_bound_host_staging() -> None:
+    """GPU range GET uses a host temporary per range, so each range is capped."""
+    store, weight_store = make_weight_store(max_range_bytes=2, max_ranges_per_request=2)
+    sources = source_manifests(dp=1, tp=1)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    targets = target_manifests(dp=1, tp=1)
+
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+    weight_store.load(load_plan, targets[0].placement, targets[0].binding)
+
+    assert store.range_sizes == [2, 2, 2, 2]
+    assert bytes(bound_fragments(targets)[0].owner) == bytes(range(8))
+    assert store.range_get_calls == 2
+    assert store.snapshot_prepare_calls == 1
+    assert store.snapshot_get_calls == 2
+
+
+def test_load_expands_strided_ranges_in_bounded_requests() -> None:
+    tensor = TensorDescriptor(
+        tensor_id="layers.0.mlp.down_proj.weight",
+        global_shape=(5, 8),
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=(1,),
+        layer_id=0,
+        layout_fingerprint="sglang:qwen3.5:uint8:test",
+        parallel_axes=(SplitAxis(kind="tp", dim=1),),
+    )
+
+    def make_manifests(tp: int, prefix: str, *, source: bool):
+        participants = []
+        extent = tensor.global_shape[1] // tp
+        for tp_rank in range(tp):
+            values = []
+            for row in range(tensor.global_shape[0]):
+                begin = row * tensor.global_shape[1] + tp_rank * extent
+                values.extend(range(begin, begin + extent))
+            if not source:
+                values = [255] * len(values)
+            owner = (ctypes.c_ubyte * len(values))(*values)
+            worker_id = f"{prefix}-t{tp_rank}"
+            placement_fragment_id = f"{worker_id}-placement"
+            nbytes = prod((tensor.global_shape[0], extent))
+            rank = ParallelRank(tp=tp_rank)
+            participants.append(
+                RuntimeParticipant(
+                    participant_id=worker_id,
+                    rank=rank,
+                    instance_id=worker_id,
+                    placement_fragments=(
+                        PlacementFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            tensor_id=tensor.tensor_id,
+                            global_offset=(0, tp_rank * extent),
+                            local_shape=(tensor.global_shape[0], extent),
+                            nbytes=nbytes,
+                            rank=rank,
+                        ),
+                    ),
+                    binding_fragments=(
+                        RuntimeBindingFragment(
+                            placement_fragment_id=placement_fragment_id,
+                            fragment_id=f"{worker_id}-fragment",
+                            address=ctypes.addressof(owner),
+                            nbytes=nbytes,
+                            worker_id=worker_id,
+                            endpoint=f"{worker_id}:12345",
+                            device="cuda:0",
+                            itemsize=1,
+                            local_shape=(tensor.global_shape[0], extent),
+                            strides_bytes=(extent, 1),
+                            storage_address=ctypes.addressof(owner),
+                            storage_nbytes=nbytes,
+                            storage_offset_bytes=0,
+                            owner=owner,
+                        ),
+                    ),
+                )
+            )
+        return make_runtime_inputs(
+            resource_id="qwen3.5-0.8b",
+            revision="step-42",
+            placement_set_id=f"{prefix}-strided-tp{tp}",
+            tensors=(tensor,),
+            participants=tuple(participants),
+        )
+
+    sources = make_manifests(2, "source", source=True)
+    targets = make_manifests(4, "target", source=False)
+    store, weight_store = make_weight_store(max_ranges_per_request=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    load_plan = weight_store.plan_load(manifest, targets.placement, targets.bindings)
+
+    load_all(weight_store, load_plan, targets)
+
+    for tp_rank, target in enumerate(bound_fragments(targets)):
+        expected = []
+        for row in range(tensor.global_shape[0]):
+            begin = row * tensor.global_shape[1] + tp_rank * 2
+            expected.extend(range(begin, begin + 2))
+        assert bytes(target.owner) == bytes(expected)
+    assert max(store.range_batch_sizes) <= 2
+    assert store.range_get_calls == 12
+
+
+def test_load_batches_multiple_local_target_buffers_in_one_request() -> None:
+    tensors = tuple(
+        TensorDescriptor(
+            tensor_id=f"layers.{index}.norm.weight",
+            global_shape=(4,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(),
+            layer_id=index,
+            layout_fingerprint="sglang:qwen3.5:uint8:test",
+            parallel_axes=(),
+        )
+        for index in range(4)
+    )
+
+    def make_manifest(prefix: str, *, source: bool) -> RuntimeInputs:
+        placement_fragments = []
+        binding_fragments = []
+        for index, tensor in enumerate(tensors):
+            values = range(index * 4, index * 4 + 4) if source else [255] * 4
+            owner = (ctypes.c_ubyte * 4)(*values)
+            placement_fragment_id = f"{prefix}-{index}-placement"
+            placement_fragments.append(
+                PlacementFragment(
+                    placement_fragment_id=placement_fragment_id,
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(0,),
+                    local_shape=(4,),
+                    nbytes=4,
+                    rank=ParallelRank(),
+                )
+            )
+            binding_fragments.append(
+                RuntimeBindingFragment(
+                    placement_fragment_id=placement_fragment_id,
+                    fragment_id=f"{prefix}-{index}",
+                    address=ctypes.addressof(owner),
+                    nbytes=4,
+                    worker_id=prefix,
+                    endpoint=f"{prefix}:12345",
+                    device="cuda:0",
+                    itemsize=1,
+                    local_shape=(4,),
+                    strides_bytes=(1,),
+                    storage_address=ctypes.addressof(owner),
+                    storage_nbytes=4,
+                    storage_offset_bytes=0,
+                    owner=owner,
+                )
+            )
+        return make_runtime_inputs(
+            resource_id="qwen3.5-0.8b",
+            revision="step-42",
+            placement_set_id=f"{prefix}-multi-buffer",
+            tensors=tensors,
+            participants=(
+                RuntimeParticipant(
+                    participant_id=prefix,
+                    rank=ParallelRank(),
+                    placement_fragments=tuple(placement_fragments),
+                    binding_fragments=tuple(binding_fragments),
+                    instance_id=prefix,
+                ),
+            ),
+        )
+
+    source = make_manifest("source", source=True)
+    target = make_manifest("target", source=False)
+    store, weight_store = make_weight_store()
+    upload_plan = weight_store.plan_upload(source.placement, source.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, source)
+    )
+    load_plan = weight_store.plan_load(manifest, target.placement, target.bindings)
+
+    weight_store.load(load_plan, target.placement, target.binding)
+
+    assert store.range_get_calls == 1
+    assert store.range_batch_sizes == [4]
+    for index, fragment in enumerate(bound_fragments(target)):
+        assert bytes(fragment.owner) == bytes(range(index * 4, index * 4 + 4))
+
+
+def test_one_participant_binding_can_execute_multiple_fragments() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    upload_plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    manifest = weight_store.commit_upload(
+        upload_plan, upload_all(weight_store, upload_plan, sources)
+    )
+    target_ranks = target_manifests(dp=1, tp=2)
+    target = coalesce_runtime_inputs(
+        target_ranks,
+        instance_id="combined-target",
+        worker_id="combined-target",
+    )
+
+    load_plan = weight_store.plan_load(manifest, target.placement, target.bindings)
+    weight_store.load(load_plan, target.placement, target.binding)
+
+    assert store.range_get_calls == 1
+    assert [bytes(fragment.owner) for fragment in bound_fragments(target)] == [
+        bytes(range(4)),
+        bytes(range(4, 8)),
+    ]
diff --git a/mooncake-reshard/tests/model_weight_store/test_registration_and_recovery.py b/mooncake-reshard/tests/model_weight_store/test_registration_and_recovery.py
new file mode 100644
index 0000000000..82837cd3ab
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_registration_and_recovery.py
@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import ctypes
+
+import pytest
+
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+)
+from mooncake.reshard.weight.store import WeightStoreError
+
+from .helpers import (
+    RuntimeParticipant,
+    coalesce_runtime_inputs,
+    make_runtime_inputs,
+    make_weight_store,
+    source_manifests,
+    upload_all,
+)
+
+
+def test_register_invalid_params_is_not_treated_as_already_registered() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    store.register_result = -600
+
+    with pytest.raises(WeightStoreError, match="register_buffer failed"):
+        weight_store.upload(plan, sources[0].placement, sources[0].binding)
+
+
+def test_registration_deduplicates_exact_aliases_with_same_address() -> None:
+    aliases = ("a.weight", "b.weight")
+    tensors = tuple(
+        TensorDescriptor(
+            tensor_id=tensor_id,
+            global_shape=(8,),
+            dtype="uint8",
+            itemsize=1,
+            shard_dims=(),
+            layout_fingerprint="test:contiguous:v1",
+            parallel_axes=(),
+        )
+        for tensor_id in aliases
+    )
+    owner = (ctypes.c_ubyte * 8)(*range(8))
+    address = ctypes.addressof(owner)
+    placement_fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"placement-{tensor.tensor_id}",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=tensor.global_shape,
+            nbytes=8,
+            rank=ParallelRank(),
+            aliases=aliases,
+        )
+        for tensor in tensors
+    )
+    source = make_runtime_inputs(
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=1,
+        placement_set_id="alias-source",
+        tensors=tensors,
+        participants=(
+            RuntimeParticipant(
+                participant_id="source",
+                rank=ParallelRank(),
+                placement_fragments=placement_fragments,
+                binding_fragments=tuple(
+                    RuntimeBindingFragment(
+                        placement_fragment_id=fragment.placement_fragment_id,
+                        fragment_id=f"fragment-{fragment.tensor_id}",
+                        address=address,
+                        nbytes=8,
+                        worker_id="source",
+                        endpoint="source:12345",
+                        device="cuda:0",
+                        itemsize=1,
+                        local_shape=(8,),
+                        strides_bytes=(1,),
+                        storage_address=address,
+                        storage_nbytes=8,
+                        storage_offset_bytes=0,
+                        owner=owner,
+                    )
+                    for fragment in placement_fragments
+                ),
+                instance_id="source",
+            ),
+        ),
+    )
+    store, weight_store = make_weight_store()
+    plan = weight_store.plan_upload(source.placement, source.bindings)
+
+    weight_store.upload(plan, source.placement, source.binding)
+
+    assert store.register_args == [(address, 8)]
+
+
+def test_manifest_put_failure_keeps_payloads_for_an_idempotent_retry() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.fail_key = plan.manifest.manifest_key
+
+    with pytest.raises(WeightStoreError, match="manifest put failed"):
+        weight_store.commit_upload(plan, receipts)
+
+    assert all(receipt.object_key in store.objects for receipt in receipts)
+    store.fail_key = None
+    assert weight_store.commit_upload(plan, receipts) == plan.manifest
+
+
+def test_commit_recovers_when_manifest_response_is_lost_after_write() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.fail_after_write_key = plan.manifest.manifest_key
+
+    assert weight_store.commit_upload(plan, receipts) == plan.manifest
+    assert weight_store.load_manifest(plan.manifest.manifest_key) == plan.manifest
+    assert all(receipt.object_key in store.objects for receipt in receipts)
+
+
+def test_upload_unregisters_every_buffer_without_deleting_unowned_payloads() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    combined = coalesce_runtime_inputs(
+        sources,
+        instance_id="combined-source",
+    )
+    plan = weight_store.plan_upload(combined.placement, combined.bindings)
+    first_address = combined.binding.fragments[0].address
+    store.unregister_results[first_address] = -9
+
+    with pytest.raises(WeightStoreError, match="unregister_buffer failed"):
+        weight_store.upload(plan, combined.placement, combined.binding)
+
+    assert store.unregister_calls == 2
+    assert all(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+    assert store.remove_forces == []
+
+
+def test_unregister_failure_does_not_mask_payload_transfer_failure() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    combined = coalesce_runtime_inputs(
+        sources,
+        instance_id="combined-source",
+    )
+    plan = weight_store.plan_upload(combined.placement, combined.bindings)
+    store.fail_key = plan.operations[1].target.object_key
+    store.unregister_results[combined.binding.fragments[0].address] = -9
+
+    with pytest.raises(WeightStoreError) as error:
+        weight_store.upload(plan, combined.placement, combined.binding)
+
+    assert "batch_put_from failed" in str(error.value)
+    assert "unregister_buffer failed" in str(error.value)
+    assert store.unregister_calls == 2
+    assert plan.operations[0].target.object_key in store.objects
+    assert store.remove_forces == []
+
+
+def test_unregister_attempts_every_buffer_when_cleanup_raises() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    combined = coalesce_runtime_inputs(
+        sources,
+        instance_id="combined-source",
+    )
+    plan = weight_store.plan_upload(combined.placement, combined.bindings)
+    first, second = combined.binding.fragments
+    store.fail_key = plan.operations[1].target.object_key
+    store.unregister_exceptions[first.address] = RuntimeError("unregister exploded")
+    store.unregister_results[second.address] = -9
+
+    with pytest.raises(WeightStoreError) as error:
+        weight_store.upload(plan, combined.placement, combined.binding)
+
+    assert "batch_put_from failed" in str(error.value)
+    assert "unregister exploded" in str(error.value)
+    assert "-9" in str(error.value)
+    assert store.unregister_addresses == [second.address, first.address]
diff --git a/mooncake-reshard/tests/model_weight_store/test_snapshot_writer.py b/mooncake-reshard/tests/model_weight_store/test_snapshot_writer.py
new file mode 100644
index 0000000000..f30c478404
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_snapshot_writer.py
@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.weight.store import (
+    WeightSnapshotDescriptor,
+    WeightStoreError,
+)
+from mooncake.reshard.weight.storage_manifest import StoredWeightManifest
+
+from .helpers import (
+    RuntimeInputs,
+    allocation_guards_for_bindings,
+    make_weight_store,
+    source_manifests,
+)
+
+
+class _SnapshotAdapter:
+    def __init__(self, source: RuntimeInputs) -> None:
+        self.source = source
+
+    def export_source(self, snapshot: WeightSnapshotDescriptor) -> RuntimeInputs:
+        assert snapshot.resource_id == self.source.placement.resource_id
+        assert snapshot.revision == self.source.placement.revision
+        assert snapshot.weight_generation == self.source.placement.weight_generation
+        return self.source
+
+    def resolve_fragment_ids(
+        self,
+        *,
+        tensor_id: str,
+        tensor: object,
+        source: RuntimeInputs,
+    ) -> tuple[str, ...]:
+        assert tensor_id == source.placement.tensors[0].tensor_id
+        assert isinstance(tensor, str)
+        return (tensor,)
+
+    def source_allocation_guards(self, binding):
+        return allocation_guards_for_bindings((binding,))
+
+
+class _MismatchedTensorAdapter(_SnapshotAdapter):
+    def resolve_fragment_ids(
+        self,
+        *,
+        tensor_id: str,
+        tensor: object,
+        source: RuntimeInputs,
+    ) -> tuple[str, ...]:
+        return (source.bindings[0].fragments[0].placement_fragment_id,)
+
+
+def _snapshot_descriptor(source: RuntimeInputs) -> WeightSnapshotDescriptor:
+    return WeightSnapshotDescriptor(
+        resource_id=source.placement.resource_id,
+        revision=source.placement.revision,
+        weight_generation=source.placement.weight_generation,
+        namespace="production",
+    )
+
+
+def test_snapshot_writer_commits_one_stored_weight_manifest() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2, weight_generation=7)
+    writer = weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    )
+
+    for binding in source.bindings:
+        fragment = binding.fragments[0]
+        writer.write_tensor(
+            source.placement.tensors[0].tensor_id,
+            fragment.placement_fragment_id,
+        )
+
+    manifest = writer.commit()
+
+    assert isinstance(manifest, StoredWeightManifest)
+    assert manifest.namespace == "production"
+    assert manifest.weight_generation == 7
+    persisted = store.objects[manifest.manifest_key].decode("utf-8")
+    assert "address" not in persisted
+    assert "lease_id" not in persisted
+    assert "instance_id" not in persisted
+
+
+def test_snapshot_writer_retries_manifest_publish_after_commit_decision() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2)
+    writer = weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    )
+
+    for binding in source.bindings:
+        fragment = binding.fragments[0]
+        writer.write_tensor(
+            source.placement.tensors[0].tensor_id,
+            fragment.placement_fragment_id,
+        )
+
+    store.fail_key = writer.plan.manifest.manifest_key
+    with pytest.raises(WeightStoreError, match="manifest put failed"):
+        writer.commit()
+
+    assert writer.plan.control_key in store.objects
+    assert writer.plan.manifest.manifest_key not in store.objects
+    assert all(
+        operation.target.object_key in store.objects
+        for operation in writer.plan.operations
+    )
+
+    store.fail_key = None
+    assert writer.commit() == writer.plan.manifest
+
+
+def test_snapshot_writer_context_preserves_manifest_publish_retry() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2)
+    writer = weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    )
+
+    store.fail_key = writer.plan.manifest.manifest_key
+    with pytest.raises(WeightStoreError, match="manifest put failed"):
+        with writer:
+            for binding in source.bindings:
+                fragment = binding.fragments[0]
+                writer.write_tensor(
+                    source.placement.tensors[0].tensor_id,
+                    fragment.placement_fragment_id,
+                )
+            writer.commit()
+
+    assert writer.plan.control_key in store.objects
+    assert writer.plan.manifest.manifest_key not in store.objects
+    with pytest.raises(WeightStoreError, match="retry commit instead"):
+        writer.abort()
+
+    store.fail_key = None
+    assert writer.commit() == writer.plan.manifest
+
+
+def test_snapshot_writer_rejects_commit_with_missing_fragment() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2)
+    writer = weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    )
+    fragment = source.bindings[0].fragments[0]
+    writer.write_tensor(
+        source.placement.tensors[0].tensor_id,
+        fragment.placement_fragment_id,
+    )
+
+    with pytest.raises(WeightStoreError, match="missing required fragments"):
+        writer.commit()
+
+    assert writer.plan.manifest.manifest_key not in store.objects
+    assert not any(
+        key.startswith(f"{writer.plan.manifest.group_id}/payload/")
+        for key in store.objects
+    )
+    assert store.objects[writer.plan.control_key]
+
+
+def test_snapshot_writer_rejects_fragment_for_another_tensor() -> None:
+    _, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2)
+    writer = weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _MismatchedTensorAdapter(source),
+    )
+
+    with pytest.raises(WeightStoreError, match="another tensor"):
+        writer.write_tensor("wrong-tensor", object())
+
+
+def test_snapshot_writer_context_commits() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=2, weight_generation=7)
+
+    with weight_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    ) as writer:
+        for binding in source.bindings:
+            fragment = binding.fragments[0]
+            writer.write_tensor(
+                source.placement.tensors[0].tensor_id,
+                fragment.placement_fragment_id,
+            )
+
+    assert writer.plan.manifest.manifest_key in store.objects
+
+
+def test_native_store_exposes_explicit_snapshot_writer_only() -> None:
+    native_store = pytest.importorskip("mooncake.store")
+    source = source_manifests(dp=1, tp=2, weight_generation=7)
+    raw_store = native_store.MooncakeDistributedStore()
+    writer = raw_store.begin_weight_snapshot(
+        _snapshot_descriptor(source),
+        _SnapshotAdapter(source),
+    )
+
+    assert hasattr(writer, "write_tensor")
+    for name in (
+        "get_tensor_with_parallelism",
+        "batch_get_tensor_with_parallelism",
+        "get_tensor_with_parallelism_into",
+        "batch_get_tensor_with_parallelism_into",
+        "put_tensor_with_parallelism",
+        "batch_put_tensor_with_parallelism",
+        "put_tensor_with_parallelism_from",
+        "batch_put_tensor_with_parallelism_from",
+        "upsert_tensor_with_parallelism",
+        "upsert_tensor_with_parallelism_from",
+        "batch_upsert_tensor_with_parallelism",
+        "batch_upsert_tensor_with_parallelism_from",
+    ):
+        assert not hasattr(raw_store, name)
+    for name in ("ParallelAxis", "TensorParallelism", "ReadTarget"):
+        assert not hasattr(native_store, name)
diff --git a/mooncake-reshard/tests/model_weight_store/test_transaction_decisions.py b/mooncake-reshard/tests/model_weight_store/test_transaction_decisions.py
new file mode 100644
index 0000000000..51256179e8
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_transaction_decisions.py
@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight.store import UploadReceipt, WeightStoreError
+
+from .helpers import make_weight_store, source_manifests, upload_all
+
+
+def test_finalize_upload_transaction_keeps_committed_revision() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    manifest = weight_store.commit_upload(plan, receipts)
+
+    weight_store.finalize_upload_transaction(plan)
+    weight_store.finalize_upload_transaction(plan)
+
+    assert plan.control_key in store.objects
+    assert manifest.manifest_key in store.objects
+    assert all(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+
+
+def test_commit_rejects_incomplete_receipts() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests()
+    plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    receipts = upload_all(weight_store, plan, sources)
+
+    with pytest.raises(WeightStoreError, match="missing upload receipts"):
+        weight_store.commit_upload(plan, receipts[:-1])
+
+    assert plan.manifest.manifest_key not in store.objects
+
+
+def test_commit_rechecks_every_payload_after_receipts_are_issued() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.objects.pop(receipts[0].object_key)
+
+    with pytest.raises(WeightStoreError, match="payload is not complete"):
+        weight_store.commit_upload(plan, receipts)
+
+    assert plan.manifest.manifest_key not in store.objects
+
+
+def test_incomplete_payload_does_not_lock_upload_into_commit_decision() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.objects.pop(receipts[0].object_key)
+
+    with pytest.raises(WeightStoreError, match="payload is not complete"):
+        weight_store.commit_upload(plan, receipts)
+
+    weight_store.abort_upload(plan, receipts)
+    assert all(
+        operation.target.object_key not in store.objects
+        for operation in plan.operations
+    )
+
+
+def test_abort_cleans_the_whole_plan_when_a_receipt_was_lost() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+
+    weight_store.abort_upload(plan, receipts[:-1])
+
+    assert not any(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+    assert set(store.removed_keys) == {
+        operation.target.object_key for operation in plan.operations
+    }
+
+
+def test_abort_does_not_delete_payload_while_manifest_commit_is_processing() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.processing_keys.add(plan.control_key)
+
+    with pytest.raises(WeightStoreError, match="not complete"):
+        weight_store.abort_upload(plan, receipts)
+
+    assert all(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+    assert store.removed_keys == []
+
+
+def test_abort_loses_after_commit_claims_plan_while_manifest_is_processing() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.processing_keys.add(plan.manifest.manifest_key)
+
+    with pytest.raises(WeightStoreError, match="manifest put failed"):
+        weight_store.commit_upload(plan, receipts)
+    with pytest.raises(WeightStoreError, match="already chose commit"):
+        weight_store.abort_upload(plan, receipts)
+
+    assert all(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+    assert store.removed_keys == []
+
+
+def test_upload_fails_and_cleans_up_when_abort_wins_after_complete_check() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=1)[0]
+    plan = weight_store.plan_upload(source.placement, source.bindings)
+    store.after_batch_is_exist = lambda: weight_store.abort_upload(plan, ())
+
+    with pytest.raises(WeightStoreError, match="already chose abort"):
+        weight_store.upload(plan, source.placement, source.binding)
+
+    assert all(
+        operation.target.object_key not in store.objects
+        for operation in plan.operations
+    )
+
+
+def test_commit_is_idempotent_for_the_same_upload_plan() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests()
+    plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    receipts = upload_all(weight_store, plan, sources)
+    first = weight_store.commit_upload(plan, receipts)
+
+    assert weight_store.commit_upload(plan, receipts) == first
+    assert all(
+        operation.target.object_key in store.objects for operation in plan.operations
+    )
+
+
+def test_commit_conflict_keeps_winner_and_force_cleans_loser_payloads() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    winner = weight_store.plan_upload(sources.placement, sources.bindings)
+    winner_receipts = upload_all(weight_store, winner, sources)
+    weight_store.commit_upload(winner, winner_receipts)
+    loser = weight_store.plan_upload(sources.placement, sources.bindings)
+    loser_receipts = upload_all(weight_store, loser, sources)
+
+    with pytest.raises(WeightStoreError, match="conflicting weight revision"):
+        weight_store.commit_upload(loser, loser_receipts)
+
+    assert weight_store.load_manifest(winner.manifest.manifest_key) == winner.manifest
+    assert all(
+        operation.target.object_key not in store.objects
+        for operation in loser.operations
+    )
+    assert store.remove_forces[-len(loser.operations) :] == [True] * len(
+        loser.operations
+    )
+
+
+def test_finalize_conflicting_commit_keeps_terminal_decision() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    winner = weight_store.plan_upload(sources.placement, sources.bindings)
+    winner_receipts = upload_all(weight_store, winner, sources)
+    winner_manifest = weight_store.commit_upload(winner, winner_receipts)
+    loser = weight_store.plan_upload(sources.placement, sources.bindings)
+    loser_receipts = upload_all(weight_store, loser, sources)
+
+    with pytest.raises(WeightStoreError, match="conflicting weight revision"):
+        weight_store.commit_upload(loser, loser_receipts)
+    assert loser.control_key in store.objects
+
+    weight_store.finalize_upload_transaction(loser)
+
+    assert loser.control_key in store.objects
+    assert weight_store.load_manifest(winner_manifest.manifest_key) == winner_manifest
+    assert all(
+        fragment.object_key in store.objects for fragment in winner_manifest.fragments
+    )
+
+
+def test_conflict_cleanup_preserves_payloads_referenced_by_winner() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    winner = replace(plan.manifest, created_at="2026-07-19T00:00:00Z")
+    store.objects[plan.manifest.manifest_key] = winner.to_json().encode()
+
+    with pytest.raises(WeightStoreError, match="conflicting weight revision"):
+        weight_store.commit_upload(plan, receipts)
+    weight_store.finalize_upload_transaction(plan)
+
+    assert all(fragment.object_key in store.objects for fragment in winner.fragments)
+    assert plan.control_key in store.objects
+
+
+def test_commit_finalize_rejects_late_abort_and_preserves_ready_revision() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    manifest = weight_store.commit_upload(plan, receipts)
+    weight_store.finalize_upload_transaction(plan)
+
+    with pytest.raises(WeightStoreError, match="published weight revision"):
+        weight_store.abort_upload(plan, receipts)
+
+    assert weight_store.load_manifest(manifest.manifest_key) == manifest
+    assert all(fragment.object_key in store.objects for fragment in manifest.fragments)
+    assert plan.control_key in store.objects
+
+
+def test_abort_finalize_rejects_late_upload_and_commit() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    weight_store.abort_upload(plan, receipts)
+    weight_store.finalize_upload_transaction(plan)
+
+    with pytest.raises(WeightStoreError, match="already chose abort"):
+        weight_store.upload(plan, sources[0].placement, sources[0].binding)
+    with pytest.raises(WeightStoreError, match="already chose abort"):
+        weight_store.commit_upload(plan, receipts)
+
+    assert plan.manifest.manifest_key not in store.objects
+    assert all(
+        operation.target.object_key not in store.objects
+        for operation in plan.operations
+    )
+    assert plan.control_key in store.objects
+
+
+def test_abort_checks_ready_manifest_when_commit_tombstone_was_lost() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    manifest = weight_store.commit_upload(plan, receipts)
+    store.objects.pop(plan.control_key)
+
+    with pytest.raises(WeightStoreError, match="published weight revision"):
+        weight_store.abort_upload(plan, receipts)
+
+    assert weight_store.load_manifest(manifest.manifest_key) == manifest
+    assert all(fragment.object_key in store.objects for fragment in manifest.fragments)
+
+
+def test_commit_detects_a_concurrent_winner_after_manifest_preflight() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    winner = weight_store.plan_upload(sources.placement, sources.bindings)
+    loser = weight_store.plan_upload(sources.placement, sources.bindings)
+    winner_receipts = upload_all(weight_store, winner, sources)
+    loser_receipts = upload_all(weight_store, loser, sources)
+    assert len(winner_receipts) == len(loser_receipts)
+    store.manifest_race_key = loser.manifest.manifest_key
+    store.manifest_race_value = winner.manifest.to_json().encode()
+
+    with pytest.raises(WeightStoreError, match="conflicting weight revision"):
+        weight_store.commit_upload(loser, loser_receipts)
+
+    assert weight_store.load_manifest(winner.manifest.manifest_key) == winner.manifest
+    assert all(
+        operation.target.object_key in store.objects for operation in winner.operations
+    )
+    assert all(
+        operation.target.object_key not in store.objects
+        for operation in loser.operations
+    )
+
+
+def test_commit_rejects_duplicate_or_forged_receipts() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+
+    with pytest.raises(WeightStoreError, match="duplicate upload receipt"):
+        weight_store.commit_upload(plan, [*receipts, receipts[0]])
+
+    forged = UploadReceipt(
+        fragment_id=receipts[0].fragment_id,
+        object_key="forged",
+        worker_id=receipts[0].worker_id,
+    )
+    with pytest.raises(WeightStoreError, match="invalid upload receipt"):
+        weight_store.commit_upload(plan, [forged, receipts[1]])
diff --git a/mooncake-reshard/tests/model_weight_store/test_upload_payload.py b/mooncake-reshard/tests/model_weight_store/test_upload_payload.py
new file mode 100644
index 0000000000..388568b097
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_upload_payload.py
@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from mooncake.reshard.weight.manifest import WeightPlacementManifest
+from mooncake.reshard.weight.store import WeightStoreError
+
+from .helpers import (
+    RuntimeInputs,
+    coalesce_runtime_inputs,
+    make_weight_store,
+    source_manifests,
+    upload_all,
+)
+
+
+def test_weight_group_objects_are_hard_pinned_and_typed() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    weight_store.commit_upload(plan, receipts)
+
+    payload_keys = {operation.target.object_key for operation in plan.operations}
+    assert {store.configs[key] for key in payload_keys} == {("WEIGHT", True)}
+    assert store.configs[plan.control_key] == ("METADATA", True)
+    assert store.configs[plan.manifest.manifest_key] == ("METADATA", True)
+
+
+def test_upload_waits_for_complete_payload_before_returning_receipt() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    key = plan.operations[0].target.object_key
+    store.processing_keys.add(key)
+
+    with pytest.raises(WeightStoreError, match="payload is not complete"):
+        weight_store.upload(plan, sources[0].placement, sources[0].binding)
+
+    assert key in store.processing_keys
+    assert store.removed_keys == []
+
+
+def test_payload_completion_queries_are_bounded() -> None:
+    store, weight_store = make_weight_store(max_ranges_per_request=1)
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    receipts = upload_all(weight_store, plan, sources)
+    store.exist_batch_sizes.clear()
+
+    weight_store.commit_upload(plan, receipts)
+
+    assert store.exist_batch_sizes == [1, 1, 1, 1]
+
+
+def test_upload_batches_payload_puts_by_range_limit() -> None:
+    store, weight_store = make_weight_store(max_ranges_per_request=2)
+    sources = source_manifests(dp=1, tp=4)
+    combined = coalesce_runtime_inputs(
+        sources,
+        instance_id="combined-source",
+    )
+    plan = weight_store.plan_upload(combined.placement, combined.bindings)
+
+    receipts = weight_store.upload(plan, combined.placement, combined.binding)
+
+    expected_keys = [operation.target.object_key for operation in plan.operations]
+    assert max(map(len, store.put_batches)) <= 2
+    assert [key for batch in store.put_batches for key in batch] == expected_keys
+    assert [receipt.object_key for receipt in receipts] == expected_keys
+
+
+def test_upload_routes_shared_worker_operations_by_participant() -> None:
+    _store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    shared = RuntimeInputs(
+        sources.placement,
+        tuple(
+            replace(
+                binding,
+                instance_id="shared-source-instance",
+                fragments=tuple(
+                    replace(
+                        fragment,
+                        worker_id="shared-source-worker",
+                        endpoint="shared-source-endpoint",
+                    )
+                    for fragment in binding.fragments
+                ),
+            )
+            for binding in sources.bindings
+        ),
+    )
+    plan = weight_store.plan_upload(shared.placement, shared.bindings)
+
+    receipts = upload_all(weight_store, plan, shared)
+
+    assert len(receipts) == len(plan.operations) == 2
+    assert {receipt.fragment_id for receipt in receipts} == {
+        operation.target.fragment_id for operation in plan.operations
+    }
+
+
+def test_payload_failure_does_not_publish_manifest() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests()
+    plan = weight_store.plan_upload(
+        sources.placement, sources.bindings, namespace="default"
+    )
+    store.fail_key = plan.operations[1].target.object_key
+
+    with pytest.raises(WeightStoreError, match="batch_put_from"):
+        upload_all(weight_store, plan, sources)
+
+    assert plan.manifest.manifest_key not in store.objects
+    assert not any("/payload/" in key for key in store.objects)
+    assert set(store.removed_keys) == {
+        operation.target.object_key for operation in plan.operations
+    }
+    assert all(store.remove_forces)
+
+
+def test_upload_surfaces_scalar_batch_put_from_error() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    store.batch_put_from = lambda *args, **kwargs: -17
+
+    with pytest.raises(WeightStoreError, match="batch_put_from failed: -17"):
+        upload_all(weight_store, plan, sources)
+
+
+def test_upload_surfaces_scalar_batch_is_exist_error() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=1)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    store.batch_is_exist = lambda *args, **kwargs: -18
+
+    with pytest.raises(WeightStoreError, match="existence check failed: -18"):
+        upload_all(weight_store, plan, sources)
+
+
+def test_upload_rejects_stale_runtime_binding_fragment() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    stale_binding = replace(
+        sources.bindings[0],
+        fragments=(
+            replace(
+                sources.bindings[0].fragments[0],
+                address=sources.bindings[0].fragments[0].address + 1,
+                storage_address=(sources.bindings[0].fragments[0].storage_address + 1),
+            ),
+        ),
+    )
+
+    with pytest.raises(WeightStoreError, match="stale source fragment"):
+        weight_store.upload(plan, sources.placement, stale_binding)
+
+
+def test_upload_rejects_weight_generation_rollover_before_store_io() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=1, weight_generation=7)[0]
+    plan = weight_store.plan_upload(source.placement, source.bindings)
+    current_placement = WeightPlacementManifest(
+        resource_id=source.placement.resource_id,
+        revision=source.placement.revision,
+        weight_generation=8,
+        placement_set_id=source.placement.placement_set_id,
+        topology=source.placement.topology,
+        parts=tuple(
+            replace(part, weight_generation=8) for part in source.placement.parts
+        ),
+    )
+    current_binding = replace(
+        source.binding,
+        placement_id=current_placement.placement_id,
+        placement_digest=current_placement.digest,
+    )
+    store.calls.clear()
+
+    with pytest.raises(WeightStoreError, match="weight generation mismatch"):
+        weight_store.upload(plan, current_placement, current_binding)
+
+    assert store.calls == []
+
+
+def test_upload_rejects_manifest_lease_rollover_before_store_io() -> None:
+    store, weight_store = make_weight_store()
+    source = source_manifests(dp=1, tp=1)[0]
+    source = RuntimeInputs(
+        source.placement,
+        (replace(source.binding, lease_id="source-lease-1"),),
+    )
+    plan = weight_store.plan_upload(source.placement, source.bindings)
+    current = replace(source.binding, lease_id="source-lease-2")
+    store.calls.clear()
+
+    with pytest.raises(WeightStoreError, match="stale source lease"):
+        weight_store.upload(plan, source.placement, current)
+
+    assert store.calls == []
+
+
+def test_upload_rejects_generation_scoped_fragment_id_rollover() -> None:
+    store, weight_store = make_weight_store()
+    sources = source_manifests(dp=1, tp=2)
+    plan = weight_store.plan_upload(sources.placement, sources.bindings)
+    replacement = replace(
+        sources.bindings[0].fragments[0],
+        fragment_id="replacement-fragment",
+    )
+    current = replace(
+        sources.bindings[0],
+        generation=2,
+        fragments=(replacement,),
+    )
+
+    with pytest.raises(WeightStoreError, match="missing planned source fragment"):
+        weight_store.upload(plan, sources.placement, current)
diff --git a/mooncake-reshard/tests/model_weight_store/test_upload_planning.py b/mooncake-reshard/tests/model_weight_store/test_upload_planning.py
new file mode 100644
index 0000000000..407e99ac03
--- /dev/null
+++ b/mooncake-reshard/tests/model_weight_store/test_upload_planning.py
@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from dataclasses import replace
+import gc
+import weakref
+
+import pytest
+
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    WeightPlacementManifest,
+    WeightUploadPlan,
+    plan_weight_upload,
+)
+
+from model_weight_planner.helpers import RuntimeInputs, descriptor, tp_manifests
+
+
+def _rebuild_inputs(
+    inputs: RuntimeInputs,
+    *,
+    tensors=None,
+    weight_generation: int | None = None,
+) -> RuntimeInputs:
+    placement = WeightPlacementManifest.from_fragments(
+        resource_id=inputs.placement.resource_id,
+        revision=inputs.placement.revision,
+        weight_generation=(
+            inputs.placement.weight_generation
+            if weight_generation is None
+            else weight_generation
+        ),
+        placement_set_id=inputs.placement.placement_set_id,
+        topology=inputs.placement.topology,
+        tensors=tuple(tensors if tensors is not None else inputs.placement.tensors),
+        fragments=inputs.placement.fragments,
+    )
+    return RuntimeInputs(
+        placement,
+        tuple(
+            replace(
+                binding,
+                placement_id=placement.placement_id,
+                placement_digest=placement.digest,
+            )
+            for binding in inputs.bindings
+        ),
+    )
+
+
+def test_upload_plan_selects_one_complete_generation_consistent_dp_replica() -> None:
+    sources = tp_manifests(
+        tp=2,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    rank_by_participant = {
+        part.participant_id: part.rank for part in sources.placement.parts
+    }
+    sources = RuntimeInputs(
+        sources.placement,
+        tuple(
+            replace(
+                binding,
+                generation=(
+                    3
+                    if rank_by_participant[binding.participant_id].dp == 1
+                    and rank_by_participant[binding.participant_id].tp == 1
+                    else 2
+                ),
+            )
+            for binding in sources.bindings
+        ),
+    )
+
+    plan = plan_weight_upload(sources.placement, sources.bindings)
+
+    assert {operation.source_placement.rank.dp for operation in plan.operations} == {0}
+    assert {operation.source_generation for operation in plan.operations} == {2}
+    assert {operation.target for operation in plan.operations} == set(
+        plan.manifest.fragments
+    )
+    assert plan.manifest.group_id.endswith("/1")
+    assert plan.control_key == f"{plan.transaction_group_id}/decision"
+
+
+def test_upload_plan_rejects_complete_dp_replicas_at_different_generations() -> None:
+    sources = tp_manifests(
+        tp=2,
+        dp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    rank_by_participant = {
+        part.participant_id: part.rank for part in sources.placement.parts
+    }
+    bindings = tuple(
+        replace(
+            binding,
+            generation=rank_by_participant[binding.participant_id].dp + 1,
+        )
+        for binding in sources.bindings
+    )
+
+    with pytest.raises(ValueError, match="inconsistent lease generations"):
+        plan_weight_upload(sources.placement, bindings)
+
+
+def test_upload_plan_rejects_incomplete_dp_replica() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+
+    with pytest.raises(ValueError, match="generation-consistent DP replica"):
+        plan_weight_upload(sources.placement, sources.bindings[:1])
+
+
+def test_upload_plan_rejects_dp_owned_source_tensor() -> None:
+    sources = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    tensor = replace(
+        descriptor(),
+        shard_dims=(),
+        parallel_axes=(
+            OwnershipAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            OwnershipAxis(kind="ep"),
+        ),
+    )
+    sources = _rebuild_inputs(sources, tensors=(tensor,))
+
+    with pytest.raises(ValueError, match="requires replicated DP source tensors"):
+        plan_weight_upload(sources.placement, sources.bindings)
+
+
+def test_upload_plan_uses_generation_scoped_store_identity() -> None:
+    generation_17 = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source-17",
+    )
+    generation_18 = tp_manifests(
+        tp=2,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x20000,
+        worker_prefix="source-18",
+    )
+    generation_17 = _rebuild_inputs(generation_17, weight_generation=17)
+    generation_18 = _rebuild_inputs(generation_18, weight_generation=18)
+
+    plan_17 = plan_weight_upload(generation_17.placement, generation_17.bindings)
+    plan_18 = plan_weight_upload(generation_18.placement, generation_18.bindings)
+
+    assert plan_17.manifest.group_id.endswith("/17")
+    assert plan_18.manifest.group_id.endswith("/18")
+    assert plan_17.manifest.group_id != plan_18.manifest.group_id
+    assert {operation.target.object_key for operation in plan_17.operations}.isdisjoint(
+        operation.target.object_key for operation in plan_18.operations
+    )
+
+
+def test_upload_plan_preserves_tp_pp_and_ep_fragment_ownership() -> None:
+    sources = tp_manifests(
+        tp=2,
+        pp_rank=3,
+        ep_rank=2,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+
+    plan = plan_weight_upload(sources.placement, sources.bindings)
+
+    assert len(plan.operations) == 2
+    assert {operation.source_placement.rank.tp for operation in plan.operations} == {
+        0,
+        1,
+    }
+    assert {operation.source_placement.rank.pp for operation in plan.operations} == {3}
+    assert {operation.source_placement.rank.ep for operation in plan.operations} == {2}
+
+
+def test_upload_plan_does_not_retain_framework_allocation_owners() -> None:
+    class AllocationOwner:
+        pass
+
+    sources = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    owner = AllocationOwner()
+    owner_ref = weakref.ref(owner)
+    sources = RuntimeInputs(
+        sources.placement,
+        (
+            replace(
+                sources.bindings[0],
+                fragments=(replace(sources.bindings[0].fragments[0], owner=owner),),
+            ),
+        ),
+    )
+
+    plan = plan_weight_upload(sources.placement, sources.bindings)
+
+    assert not hasattr(plan.operations[0].source_snapshot, "owner")
+    del owner
+    del sources
+    gc.collect()
+    assert owner_ref() is None
+
+
+def test_upload_plan_rejects_payload_outside_its_upload_transaction() -> None:
+    sources = tp_manifests(
+        tp=1,
+        pp_rank=0,
+        ep_rank=0,
+        address_base=0x10000,
+        worker_prefix="source",
+    )
+    plan = plan_weight_upload(sources.placement, sources.bindings)
+    target = replace(
+        plan.operations[0].target,
+        object_key=f"{plan.manifest.group_id}/payload/other-transaction/fragment",
+    )
+    manifest = replace(plan.manifest, fragments=(target,))
+    operation = replace(plan.operations[0], target=target)
+
+    with pytest.raises(ValueError, match="does not own payload members"):
+        WeightUploadPlan(
+            manifest=manifest,
+            source_placement_id=plan.source_placement_id,
+            source_placement_digest=plan.source_placement_digest,
+            transaction_group_id=plan.transaction_group_id,
+            control_key=plan.control_key,
+            operations=(operation,),
+        )
diff --git a/mooncake-reshard/tests/test_python_compat.py b/mooncake-reshard/tests/test_python_compat.py
new file mode 100644
index 0000000000..ad1c818d97
--- /dev/null
+++ b/mooncake-reshard/tests/test_python_compat.py
@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard._compat import _strict_zip
+
+
+def test_strict_zip_preserves_equal_length_values() -> None:
+    assert tuple(_strict_zip((1, 2), (3, 4))) == ((1, 3), (2, 4))
+
+
+def test_strict_zip_rejects_different_lengths() -> None:
+    with pytest.raises(ValueError, match="different lengths"):
+        tuple(_strict_zip((1,), (2, 3)))
diff --git a/mooncake-reshard/tests/test_reshard_geometry.py b/mooncake-reshard/tests/test_reshard_geometry.py
new file mode 100644
index 0000000000..725d832da5
--- /dev/null
+++ b/mooncake-reshard/tests/test_reshard_geometry.py
@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter
+
+from hypothesis import given, settings, strategies as st
+import pytest
+
+import mooncake.reshard.geometry as geometry
+from mooncake.reshard.geometry import (
+    LogicalBox,
+    OverlapRegion,
+    boxes_exactly_cover,
+    regions_exactly_cover,
+)
+
+
+@dataclass(frozen=True)
+class _Box:
+    global_offset: tuple[int, ...]
+    local_shape: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class _Region:
+    overlap_offset: tuple[int, ...]
+    overlap_shape: tuple[int, ...]
+
+
+def test_geometry_contract_is_structural_and_resource_agnostic() -> None:
+    target: LogicalBox = _Box(global_offset=(8, 4), local_shape=(2, 6))
+    regions: tuple[OverlapRegion, ...] = (
+        _Region(overlap_offset=(8, 4), overlap_shape=(1, 6)),
+        _Region(overlap_offset=(9, 4), overlap_shape=(1, 6)),
+    )
+
+    assert regions_exactly_cover(target, regions)
+    assert boxes_exactly_cover(
+        target.global_offset,
+        target.local_shape,
+        tuple((region.overlap_offset, region.overlap_shape) for region in regions),
+    )
+    assert not regions_exactly_cover(target, (regions[0], regions[0], regions[1]))
+
+
+def _row_split_exact_cover(
+    row_count: int,
+    *,
+    ndim: int = 2,
+) -> tuple[
+    tuple[int, ...],
+    tuple[int, ...],
+    tuple[tuple[tuple[int, ...], tuple[int, ...]], ...],
+]:
+    if ndim < 2:
+        raise ValueError("row split requires at least two dimensions")
+    container_offset = (0,) * ndim
+    container_shape = (row_count + 1, row_count, *((1,) * (ndim - 2)))
+    boxes = []
+    for row in range(row_count):
+        split = row + 1
+        left_offset = (0, row, *((0,) * (ndim - 2)))
+        right_offset = (split, row, *((0,) * (ndim - 2)))
+        left_shape = (split, 1, *((1,) * (ndim - 2)))
+        right_shape = (row_count + 1 - split, 1, *((1,) * (ndim - 2)))
+        boxes.extend(((left_offset, left_shape), (right_offset, right_shape)))
+    return container_offset, container_shape, tuple(boxes)
+
+
+def test_boxes_exactly_cover_row_split_layout_within_two_dimensional_budget() -> None:
+    container_offset, container_shape, boxes = _row_split_exact_cover(4096)
+
+    started_at = perf_counter()
+    assert boxes_exactly_cover(container_offset, container_shape, boxes)
+    assert perf_counter() - started_at < 2.0
+
+
+def test_high_dimensional_overlap_fails_closed_after_comparison_budget(
+    monkeypatch,
+) -> None:
+    _, _, boxes = _row_split_exact_cover(3, ndim=3)
+    monkeypatch.setattr(
+        geometry,
+        "_MAX_HIGH_DIMENSIONAL_PAIRWISE_COMPARISONS",
+        0,
+        raising=False,
+    )
+
+    with pytest.raises(ValueError, match="high-dimensional overlap budget"):
+        geometry.boxes_overlap(boxes)
+
+
+@st.composite
+def _small_boxes(draw) -> tuple[tuple[tuple[int, ...], tuple[int, ...]], ...]:
+    ndim = draw(st.integers(min_value=1, max_value=3))
+    count = draw(st.integers(min_value=0, max_value=8))
+    boxes = []
+    for _ in range(count):
+        boxes.append(
+            (
+                tuple(draw(st.integers(min_value=0, max_value=6)) for _ in range(ndim)),
+                tuple(draw(st.integers(min_value=1, max_value=4)) for _ in range(ndim)),
+            )
+        )
+    return tuple(boxes)
+
+
+def _brute_boxes_overlap(
+    boxes: tuple[tuple[tuple[int, ...], tuple[int, ...]], ...],
+) -> bool:
+    return any(
+        all(
+            left_begin < right_begin + right_extent
+            and right_begin < left_begin + left_extent
+            for left_begin, left_extent, right_begin, right_extent in zip(
+                left_offset,
+                left_shape,
+                right_offset,
+                right_shape,
+            )
+        )
+        for index, (left_offset, left_shape) in enumerate(boxes)
+        for right_offset, right_shape in boxes[index + 1 :]
+    )
+
+
+@settings(max_examples=200, deadline=None)
+@given(_small_boxes())
+def test_boxes_overlap_matches_brute_force_for_small_inputs(boxes) -> None:
+    assert geometry.boxes_overlap(boxes) is _brute_boxes_overlap(boxes)
+
+
+@st.composite
+def _tiled_target_and_regions(draw) -> tuple[_Box, tuple[_Region, ...]]:
+    ndim = draw(st.integers(min_value=1, max_value=3))
+    split_dim = draw(st.integers(min_value=0, max_value=ndim - 1))
+    origin = tuple(draw(st.integers(min_value=0, max_value=8)) for _ in range(ndim))
+    shape = tuple(
+        draw(st.integers(min_value=2 if dim == split_dim else 1, max_value=6))
+        for dim in range(ndim)
+    )
+    split = draw(st.integers(min_value=1, max_value=shape[split_dim] - 1))
+    left_shape = tuple(
+        split if dim == split_dim else extent for dim, extent in enumerate(shape)
+    )
+    right_offset = tuple(
+        origin[dim] + split if dim == split_dim else origin[dim] for dim in range(ndim)
+    )
+    right_shape = tuple(
+        extent - split if dim == split_dim else extent
+        for dim, extent in enumerate(shape)
+    )
+    return _Box(origin, shape), (
+        _Region(origin, left_shape),
+        _Region(right_offset, right_shape),
+    )
+
+
+@settings(max_examples=80, deadline=None)
+@given(_tiled_target_and_regions())
+def test_regions_exactly_cover_random_n_dim_tilings(
+    tiled: tuple[_Box, tuple[_Region, ...]],
+) -> None:
+    target, regions = tiled
+
+    assert regions_exactly_cover(target, regions)
+    assert not regions_exactly_cover(target, regions[:1])
diff --git a/mooncake-reshard/tests/test_reshard_manifest_contracts.py b/mooncake-reshard/tests/test_reshard_manifest_contracts.py
new file mode 100644
index 0000000000..ba490dc6ef
--- /dev/null
+++ b/mooncake-reshard/tests/test_reshard_manifest_contracts.py
@@ -0,0 +1,113 @@
+import json
+from dataclasses import fields
+from importlib.util import find_spec
+from typing import Protocol
+
+import mooncake.reshard.weight.placement as weight_placement
+import pytest
+from mooncake import reshard
+from mooncake.reshard import weight
+from mooncake.reshard.contracts import (
+    PlacementManifest,
+    ResourceKind,
+    ResourceManifest,
+    RuntimeBindingManifest,
+)
+from mooncake.reshard.weight import (
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+    weight_placement_from_json,
+    weight_placement_to_json,
+)
+from weight_manifest.helpers import (
+    binding_manifest,
+    placement_manifest,
+)
+
+
+def test_reshard_public_api_is_resource_neutral():
+    assert reshard.__all__ == [
+        "ResourceKind",
+        "ResourceManifest",
+        "PlacementManifest",
+        "RuntimeBindingManifest",
+    ]
+
+
+def test_common_manifest_contracts_are_structural_protocols():
+    assert issubclass(ResourceManifest, Protocol)
+    assert issubclass(PlacementManifest, Protocol)
+    assert issubclass(RuntimeBindingManifest, Protocol)
+    assert PlacementManifest not in WeightPlacementManifest.__mro__
+    assert RuntimeBindingManifest not in WeightRuntimeBindingManifest.__mro__
+
+
+def test_weight_api_has_no_combined_runtime_manifest():
+    assert not hasattr(weight, "WeightRuntimeManifest")
+
+
+def test_weight_placement_has_one_canonical_contract_without_side_aliases():
+    assert not hasattr(weight_placement, "SourcePlacementManifest")
+    assert not hasattr(weight_placement, "TargetPlacementManifest")
+
+
+def test_concrete_weight_manifests_own_and_validate_common_fields():
+    assert [field.name for field in fields(WeightPlacementManifest)][:2] == [
+        "resource_id",
+        "placement_id",
+    ]
+    assert [field.name for field in fields(WeightRuntimeBindingManifest)][:6] == [
+        "resource_id",
+        "placement_id",
+        "placement_digest",
+        "instance_id",
+        "generation",
+        "lease_id",
+    ]
+
+
+def test_weight_manifests_expose_common_resource_fields():
+    placement = placement_manifest()
+    manifests = (
+        placement,
+        binding_manifest(placement=placement),
+    )
+
+    for manifest in manifests:
+        assert not hasattr(manifest, "model_id")
+        assert manifest.resource_id == "model"
+        assert manifest.resource_kind is ResourceKind.MODEL_WEIGHT
+
+
+def test_legacy_model_weight_namespace_is_not_installed():
+    assert find_spec("mooncake.model_weight") is None
+
+
+def test_kv_cache_specialization_is_installed_under_reshard():
+    assert ResourceKind.KV_CACHE.value == "kv_cache"
+    assert find_spec("mooncake.reshard.kv_cache") is not None
+
+
+def test_weight_placement_json_has_a_strict_resource_kind():
+    placement = placement_manifest()
+    payload = json.loads(weight_placement_to_json(placement))
+
+    assert payload["resource_kind"] == "model_weight"
+    payload["resource_kind"] = "kv_cache"
+
+    with pytest.raises(ValueError, match="resource_kind"):
+        weight_placement_from_json(json.dumps(payload))
+
+
+@pytest.mark.parametrize("resource_kind", [None, "unknown"])
+def test_weight_placement_json_rejects_missing_or_unknown_resource_kind(
+    resource_kind,
+):
+    payload = json.loads(weight_placement_to_json(placement_manifest()))
+    if resource_kind is None:
+        del payload["resource_kind"]
+    else:
+        payload["resource_kind"] = resource_kind
+
+    with pytest.raises(ValueError):
+        weight_placement_from_json(json.dumps(payload))
diff --git a/mooncake-reshard/tests/test_reshard_weight_module_layout.py b/mooncake-reshard/tests/test_reshard_weight_module_layout.py
new file mode 100644
index 0000000000..950732a645
--- /dev/null
+++ b/mooncake-reshard/tests/test_reshard_weight_module_layout.py
@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import importlib.util
+
+import mooncake.reshard.weight as model_weight
+import mooncake.reshard.weight._planner.contracts as planner_contracts
+from mooncake.reshard.weight._planner.bound_contracts import (
+    TransferPlan as BoundTransferPlan,
+)
+from mooncake.reshard.weight.binding import (
+    validate_runtime_binding,
+    validate_runtime_bindings,
+)
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+)
+from mooncake.reshard.weight.part import WeightPlacementPart as PlacementPartContract
+from mooncake.reshard.weight.placement import (
+    WeightPlacementManifest as PlacementContract,
+)
+from mooncake.reshard.weight.runtime import (
+    WeightRuntimeBindingManifest as RuntimeBindingContract,
+)
+from mooncake.reshard.weight.types import (
+    ParallelRank as ParallelRankContract,
+)
+from mooncake.reshard.weight.types import (
+    PlacementFragment as PlacementFragmentContract,
+)
+from mooncake.reshard.weight.types import (
+    RuntimeBindingFragment as RuntimeBindingFragmentContract,
+)
+from mooncake.reshard.weight.types import TensorDescriptor as TensorContract
+from mooncake.reshard.weight.topology import (
+    ParallelTopology as ParallelTopologyContract,
+)
+from mooncake.reshard.weight.topology import (
+    TopologyParticipant as TopologyParticipantContract,
+)
+
+
+def test_responsibility_modules_preserve_public_contract_identity() -> None:
+    assert model_weight.ParallelRank is ParallelRank is ParallelRankContract
+    assert model_weight.ParallelTopology is ParallelTopology is ParallelTopologyContract
+    assert (
+        model_weight.TopologyParticipant
+        is TopologyParticipant
+        is TopologyParticipantContract
+    )
+    assert model_weight.TensorDescriptor is TensorDescriptor is TensorContract
+    assert (
+        model_weight.PlacementFragment is PlacementFragment is PlacementFragmentContract
+    )
+    assert (
+        model_weight.RuntimeBindingFragment
+        is RuntimeBindingFragment
+        is RuntimeBindingFragmentContract
+    )
+    assert (
+        model_weight.WeightPlacementManifest
+        is WeightPlacementManifest
+        is PlacementContract
+    )
+    assert (
+        model_weight.WeightPlacementPart is WeightPlacementPart is PlacementPartContract
+    )
+    assert (
+        model_weight.WeightRuntimeBindingManifest
+        is WeightRuntimeBindingManifest
+        is RuntimeBindingContract
+    )
+    assert model_weight.validate_runtime_binding is validate_runtime_binding
+    assert model_weight.validate_runtime_bindings is validate_runtime_bindings
+
+
+def test_runtime_binding_phase_exports_bound_contracts() -> None:
+    assert model_weight.bind_logical_transfer_plan is not None
+    assert hasattr(planner_contracts, "BoundWeightFragment")
+    assert model_weight.TransferPlan is BoundTransferPlan
+    assert (
+        importlib.util.find_spec("mooncake.reshard.weight._planner.attestation")
+        is not None
+    )
diff --git a/mooncake-reshard/tests/test_source_package_import.py b/mooncake-reshard/tests/test_source_package_import.py
new file mode 100644
index 0000000000..22ca7327a6
--- /dev/null
+++ b/mooncake-reshard/tests/test_source_package_import.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+def test_source_tree_package_coexists_with_installed_mooncake() -> None:
+    repo_root = Path(__file__).resolve().parents[2]
+    source_root = repo_root / "mooncake-reshard" / "python"
+    wheel_root = repo_root / "mooncake-wheel"
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join((str(source_root), str(wheel_root)))
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            (
+                "import mooncake; import mooncake.reshard; "
+                "assert len(tuple(mooncake.__path__)) >= 2"
+            ),
+        ],
+        cwd=repo_root,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stderr
diff --git a/mooncake-reshard/tests/test_store_module_layout.py b/mooncake-reshard/tests/test_store_module_layout.py
new file mode 100644
index 0000000000..eb2c694dbd
--- /dev/null
+++ b/mooncake-reshard/tests/test_store_module_layout.py
@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from inspect import signature
+from types import SimpleNamespace
+
+import pytest
+
+from mooncake.reshard.weight import store
+from mooncake.reshard.weight._store import (
+    PayloadStoreOperations as ExportedPayloadStoreOperations,
+)
+from mooncake.reshard.weight._store import (
+    WeightUploadService as ExportedWeightUploadService,
+)
+from mooncake.reshard.weight._store import (
+    WeightUploadTransaction as ExportedWeightUploadTransaction,
+)
+from mooncake.reshard.weight._store.entrypoint import begin_weight_snapshot
+from mooncake.reshard.weight._store.store import WeightStore, WeightStoreError
+from mooncake.reshard.weight._store.snapshot import (
+    WeightSnapshotAdapter,
+    WeightSnapshotDescriptor,
+)
+from mooncake.reshard.weight._store.writer import WeightStoreWriter
+from mooncake.reshard.weight._store.backend import default_config_factory
+from mooncake.reshard.weight._store.contracts import (
+    UploadOperation,
+    UploadReceipt,
+    WeightLoadPlan,
+    WeightUploadPlan,
+)
+from mooncake.reshard.weight._store.payload import PayloadStoreOperations
+from mooncake.reshard.weight._store.transaction import WeightUploadTransaction
+from mooncake.reshard.weight._store.upload import WeightUploadService
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    SplitAxis,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightRuntimeBindingManifest,
+)
+
+
+def manifest_pair():
+    tensor = TensorDescriptor(
+        tensor_id="layers.0.weight",
+        global_shape=(4,),
+        dtype="uint8",
+        itemsize=1,
+        shard_dims=(0,),
+        layout_fingerprint="test:contiguous:v1",
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    rank = ParallelRank()
+    placement = WeightPlacementManifest.from_fragments(
+        resource_id="qwen",
+        revision="step-1",
+        weight_generation=3,
+        placement_set_id="module-layout-test",
+        topology=ParallelTopology(
+            tp_size=1,
+            pp_size=1,
+            ep_size=1,
+            dp_size=1,
+            participants=(TopologyParticipant(participant_id="worker-0", rank=rank),),
+        ),
+        tensors=(tensor,),
+        fragments=(
+            PlacementFragment(
+                placement_fragment_id="placement-0",
+                tensor_id=tensor.tensor_id,
+                global_offset=(0,),
+                local_shape=(4,),
+                nbytes=4,
+                rank=rank,
+            ),
+        ),
+    )
+    binding = WeightRuntimeBindingManifest(
+        resource_id=placement.resource_id,
+        revision=placement.revision,
+        placement_id=placement.placement_id,
+        placement_digest=placement.digest,
+        instance_id="worker-0",
+        participant_id="worker-0",
+        generation=7,
+        lease_id="lease-7",
+        fragments=(
+            RuntimeBindingFragment(
+                placement_fragment_id="placement-0",
+                fragment_id="runtime-0",
+                address=0x1000,
+                nbytes=4,
+                worker_id="worker-0",
+                endpoint="worker-0:12345",
+                device="cuda:0",
+                itemsize=1,
+                local_shape=(4,),
+                strides_bytes=(1,),
+                storage_address=0x1000,
+                storage_nbytes=4,
+                storage_offset_bytes=0,
+            ),
+        ),
+    )
+    return placement, binding
+
+
+def test_store_responsibility_modules_preserve_public_identity() -> None:
+    assert store.WeightStore is WeightStore
+    assert store.WeightStoreError is WeightStoreError
+    assert store.UploadOperation is UploadOperation
+    assert store.UploadReceipt is UploadReceipt
+    assert store.WeightLoadPlan is WeightLoadPlan
+    assert store.WeightUploadPlan is WeightUploadPlan
+
+
+def test_store_internal_modules_match_their_responsibilities() -> None:
+    assert WeightStore.__module__.endswith("._store.store")
+    assert WeightSnapshotDescriptor.__module__.endswith("._store.snapshot")
+    assert WeightSnapshotAdapter.__module__.endswith("._store.snapshot")
+    assert WeightStoreWriter.__module__.endswith("._store.writer")
+    assert begin_weight_snapshot.__module__.endswith("._store.entrypoint")
+
+
+def test_store_internal_services_have_one_definition() -> None:
+    assert ExportedPayloadStoreOperations is PayloadStoreOperations
+    assert ExportedWeightUploadTransaction is WeightUploadTransaction
+    assert ExportedWeightUploadService is WeightUploadService
+
+
+def test_store_contract_uses_explicit_placement_and_binding() -> None:
+    for name in (
+        "plan_upload",
+        "upload",
+        "commit_upload",
+        "abort_upload",
+        "finalize_upload_transaction",
+        "plan_load",
+        "load",
+    ):
+        assert callable(getattr(WeightStore, name))
+    for legacy_name in (
+        "prepare_upload",
+        "commit",
+        "finalize_upload_session",
+    ):
+        assert not hasattr(WeightStore, legacy_name)
+
+    plan_parameters = tuple(signature(WeightStore.plan_upload).parameters)
+    assert plan_parameters[:4] == (
+        "self",
+        "source_placement",
+        "source_bindings",
+        "namespace",
+    )
+
+    upload_parameters = tuple(signature(WeightStore.upload).parameters)
+    assert upload_parameters[:7] == (
+        "self",
+        "plan",
+        "source_placement",
+        "source_binding",
+        "source_worker_id",
+        "source_allocation_guards",
+        "registration_lease",
+    )
+
+    plan_load_parameters = tuple(signature(WeightStore.plan_load).parameters)
+    assert plan_load_parameters[:4] == (
+        "self",
+        "manifest",
+        "target_placement",
+        "target_bindings",
+    )
+
+    load_parameters = tuple(signature(WeightStore.load).parameters)
+    assert load_parameters[:7] == (
+        "self",
+        "plan",
+        "target_placement",
+        "target_binding",
+        "target_worker_id",
+        "target_allocation_guards",
+        "registration_lease",
+    )
+
+
+def test_store_rejects_binding_for_different_placement_digest() -> None:
+    placement, binding = manifest_pair()
+
+    with pytest.raises(WeightStoreError, match="placement digest"):
+        WeightStore(object()).plan_upload(
+            placement,
+            (replace(binding, placement_digest="0" * 64),),
+        )
+
+
+def test_native_store_requires_group_semantics_binding(monkeypatch) -> None:
+    class ReplicateConfigWithoutGroups:
+        __slots__ = ("with_hard_pin", "data_type")
+
+        def __init__(self) -> None:
+            self.with_hard_pin = False
+            self.data_type = None
+
+    class ObjectDataType:
+        WEIGHT = "weight"
+        METADATA = "metadata"
+
+    native_store_module = SimpleNamespace(
+        ReplicateConfig=ReplicateConfigWithoutGroups,
+        ObjectDataType=ObjectDataType,
+    )
+
+    monkeypatch.setattr(
+        "mooncake.reshard.weight._store.backend.import_module",
+        lambda _: native_store_module,
+    )
+
+    with pytest.raises(WeightStoreError, match="ReplicateConfig.group_ids"):
+        default_config_factory(("weight-group",), "payload")
diff --git a/mooncake-reshard/tests/weight_manifest/__init__.py b/mooncake-reshard/tests/weight_manifest/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/mooncake-reshard/tests/weight_manifest/helpers.py b/mooncake-reshard/tests/weight_manifest/helpers.py
new file mode 100644
index 0000000000..aa6ca28c89
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/helpers.py
@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+)
+
+
+MODEL_ID = "model"
+REVISION = "revision"
+WEIGHT_GENERATION = 7
+PLACEMENT_SET_ID = "placement-set-7"
+PARTICIPANT_ID = "worker-0"
+
+
+def parallel_topology(
+    *,
+    participants: tuple[TopologyParticipant, ...] | None = None,
+    **overrides,
+) -> ParallelTopology:
+    participants = participants or (
+        TopologyParticipant(PARTICIPANT_ID, ParallelRank()),
+    )
+    values = {
+        "tp_size": max(item.rank.tp for item in participants) + 1,
+        "pp_size": max(item.rank.pp for item in participants) + 1,
+        "ep_size": max(item.rank.ep for item in participants) + 1,
+        "dp_size": max(item.rank.dp for item in participants) + 1,
+        "participants": participants,
+    }
+    values.update(overrides)
+    return ParallelTopology(**values)
+
+
+def descriptor(**overrides) -> TensorDescriptor:
+    values = {
+        "tensor_id": "layers.2.experts.3.w1",
+        "global_shape": (4, 4),
+        "dtype": "bfloat16",
+        "itemsize": 2,
+        "shard_dims": (0,),
+        "layer_id": 2,
+        "expert_id": 3,
+        "layout_fingerprint": "test:qwen:bf16:v1",
+        "parallel_axes": (SplitAxis(kind="tp", dim=0),),
+    }
+    values.update(overrides)
+    return TensorDescriptor(**values)
+
+
+def placement_fragment(**overrides) -> PlacementFragment:
+    values = {
+        "placement_fragment_id": "placement-0",
+        "tensor_id": "layers.2.experts.3.w1",
+        "global_offset": (0, 0),
+        "local_shape": (4, 4),
+        "nbytes": 32,
+        "rank": ParallelRank(),
+    }
+    values.update(overrides)
+    return PlacementFragment(**values)
+
+
+def placement_part(
+    *,
+    topology: ParallelTopology | None = None,
+    participant_id: str = PARTICIPANT_ID,
+    rank: ParallelRank | None = None,
+    tensors: tuple[TensorDescriptor, ...] = (),
+    fragments: tuple[PlacementFragment, ...] = (),
+    **overrides,
+) -> WeightPlacementPart:
+    topology = topology or parallel_topology()
+    rank = rank or topology.participant(participant_id).rank
+    values = {
+        "resource_id": MODEL_ID,
+        "revision": REVISION,
+        "weight_generation": WEIGHT_GENERATION,
+        "placement_set_id": PLACEMENT_SET_ID,
+        "topology_id": topology.topology_id,
+        "participant_id": participant_id,
+        "rank": rank,
+        "tensors": tensors,
+        "fragments": fragments,
+    }
+    values.update(overrides)
+    return WeightPlacementPart(**values)
+
+
+def placement_manifest(**overrides) -> WeightPlacementManifest:
+    values = {
+        "resource_id": MODEL_ID,
+        "revision": REVISION,
+        "weight_generation": WEIGHT_GENERATION,
+        "placement_set_id": PLACEMENT_SET_ID,
+        "placement_id": None,
+    }
+    for field in tuple(values):
+        if field in overrides:
+            values[field] = overrides.pop(field)
+
+    tensors = overrides.pop("tensors", (descriptor(),))
+    fragments = overrides.pop("fragments", (placement_fragment(),))
+    topology = overrides.pop("topology", None)
+    parts = overrides.pop("parts", None)
+    if overrides:
+        values.update(overrides)
+
+    fragments_are_valid = isinstance(fragments, tuple) and all(
+        isinstance(item, PlacementFragment) for item in fragments
+    )
+    tensors_are_valid = isinstance(tensors, tuple) and all(
+        isinstance(item, TensorDescriptor) for item in tensors
+    )
+    if topology is None:
+        ranks = (
+            tuple(sorted({item.rank for item in fragments}, key=_rank_key))
+            if fragments_are_valid and fragments
+            else (ParallelRank(),)
+        )
+        topology = parallel_topology(
+            participants=tuple(
+                TopologyParticipant(f"worker-{index}", rank)
+                for index, rank in enumerate(ranks)
+            )
+        )
+
+    if parts is None and fragments_are_valid and tensors_are_valid:
+        tensor_by_id = {item.tensor_id: item for item in tensors}
+        generated_parts = []
+        for index, participant in enumerate(topology.participants):
+            local_fragments = tuple(
+                item for item in fragments if item.rank == participant.rank
+            )
+            local_tensor_ids = {item.tensor_id for item in local_fragments}
+            local_tensors = tuple(
+                tensor_by_id[tensor_id]
+                for tensor_id in sorted(local_tensor_ids)
+                if tensor_id in tensor_by_id
+            )
+            if not fragments and index == 0:
+                local_tensors = tensors
+            generated_parts.append(
+                placement_part(
+                    topology=topology,
+                    participant_id=participant.participant_id,
+                    rank=participant.rank,
+                    tensors=local_tensors,
+                    fragments=local_fragments,
+                    resource_id=values["resource_id"],
+                    revision=values["revision"],
+                    weight_generation=values["weight_generation"],
+                    placement_set_id=values["placement_set_id"],
+                )
+            )
+        parts = tuple(generated_parts)
+    elif parts is None:
+        participant = topology.participants[0]
+        parts = (
+            placement_part(
+                topology=topology,
+                participant_id=participant.participant_id,
+                rank=participant.rank,
+                tensors=tensors,
+                fragments=fragments,
+                resource_id=values["resource_id"],
+                revision=values["revision"],
+                weight_generation=values["weight_generation"],
+                placement_set_id=values["placement_set_id"],
+            ),
+        )
+
+    return WeightPlacementManifest(topology=topology, parts=parts, **values)
+
+
+def _rank_key(rank: ParallelRank) -> tuple[int, int, int, int]:
+    return (rank.dp, rank.tp, rank.pp, rank.ep)
+
+
+def binding_fragment(**overrides) -> RuntimeBindingFragment:
+    values = {
+        "placement_fragment_id": "placement-0",
+        "fragment_id": "runtime-0",
+        "address": 0x1000,
+        "nbytes": 32,
+        "worker_id": "worker-0",
+        "endpoint": "worker-0:12345",
+        "device": "cuda:0",
+        "itemsize": 2,
+        "local_shape": (4, 4),
+        "strides_bytes": (8, 2),
+        "storage_address": 0x1000,
+        "storage_nbytes": 32,
+        "storage_offset_bytes": 0,
+    }
+    if "address" in overrides and "storage_address" not in overrides:
+        values["storage_address"] = overrides["address"]
+    if "nbytes" in overrides and "storage_nbytes" not in overrides:
+        values["storage_nbytes"] = overrides["nbytes"]
+    values.update(overrides)
+    return RuntimeBindingFragment(**values)
+
+
+def binding_manifest(
+    *,
+    placement: WeightPlacementManifest | None = None,
+    **overrides,
+) -> WeightRuntimeBindingManifest:
+    logical = placement or placement_manifest()
+    participant_id = overrides.pop(
+        "participant_id",
+        logical.parts[0].participant_id,
+    )
+    placement_part = next(
+        (item for item in logical.parts if item.participant_id == participant_id),
+        None,
+    )
+    tensor_by_id = {tensor.tensor_id: tensor for tensor in logical.tensors}
+    default_fragments = (
+        tuple(
+            binding_fragment(
+                placement_fragment_id=fragment.placement_fragment_id,
+                fragment_id=f"runtime-{index}",
+                address=0x1000 + index * 0x100,
+                nbytes=fragment.nbytes,
+                itemsize=tensor_by_id[fragment.tensor_id].itemsize,
+                local_shape=fragment.local_shape,
+                strides_bytes=_contiguous_strides_bytes(
+                    fragment.local_shape,
+                    tensor_by_id[fragment.tensor_id].itemsize,
+                ),
+            )
+            for index, fragment in enumerate(placement_part.fragments)
+        )
+        if placement_part is not None
+        else ()
+    )
+    values = {
+        "resource_id": logical.resource_id,
+        "revision": logical.revision,
+        "placement_id": logical.placement_id,
+        "placement_digest": logical.digest,
+        "participant_id": participant_id,
+        "instance_id": "instance",
+        "generation": 7,
+        "lease_id": "lease-7",
+        "fragments": default_fragments,
+    }
+    values.update(overrides)
+    return WeightRuntimeBindingManifest(**values)
+
+
+def _contiguous_strides_bytes(shape: tuple[int, ...], itemsize: int) -> tuple[int, ...]:
+    result = []
+    running = itemsize
+    for extent in reversed(shape):
+        result.append(running)
+        running *= extent
+    return tuple(reversed(result))
diff --git a/mooncake-reshard/tests/weight_manifest/test_api_and_types.py b/mooncake-reshard/tests/weight_manifest/test_api_and_types.py
new file mode 100644
index 0000000000..636c8e0ff9
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_api_and_types.py
@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import inspect
+import typing
+
+import pytest
+
+import mooncake.reshard.weight.manifest as model_weight
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    PlacementFragment,
+    ReplicatedAxis,
+    SplitAxis,
+    TensorDescriptor,
+)
+
+from .helpers import descriptor
+
+
+def test_public_api_is_minimal_and_explicit() -> None:
+    assert model_weight.__all__ == [
+        "ParallelRank",
+        "ParallelTopology",
+        "PlacementFragment",
+        "TopologyParticipant",
+        "WeightPlacementManifest",
+        "WeightPlacementPart",
+        "RuntimeBindingFragment",
+        "WeightRuntimeBindingManifest",
+        "SplitAxis",
+        "ReplicatedAxis",
+        "OwnershipAxis",
+        "TensorDescriptor",
+        "validate_runtime_binding",
+        "validate_runtime_bindings",
+    ]
+
+
+def test_public_type_hints_resolve() -> None:
+    for name in model_weight.__all__:
+        value = getattr(model_weight, name)
+        targets = (value, value.__init__) if inspect.isclass(value) else (value,)
+        for target in targets:
+            typing.get_type_hints(target)
+
+
+def test_tensor_descriptor_uses_canonical_shard_dims() -> None:
+    single_axis = descriptor()
+    multidim = descriptor(
+        shard_dims=(0, 1),
+        global_shape=(8, 16, 32),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+
+    assert single_axis.shard_dims == (0,)
+    assert multidim.shard_dims == (0, 1)
+
+
+def test_tensor_descriptor_carries_explicit_parallel_axis_semantics() -> None:
+    value = descriptor(
+        global_shape=(8, 16, 32),
+        shard_dims=(0, 2),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="tp", dim=2),
+            SplitAxis(kind="ep", dim=0),
+            OwnershipAxis(kind="pp"),
+            ReplicatedAxis(kind="dp"),
+        ),
+    )
+
+    assert tuple(axis.kind for axis in value.parallel_axes) == (
+        "dp",
+        "pp",
+        "ep",
+        "tp",
+    )
+    assert tuple(
+        axis.dim for axis in value.parallel_axes if isinstance(axis, SplitAxis)
+    ) == (0, 2)
+
+
+@pytest.mark.parametrize(
+    ("parallel_axes", "shard_dims", "message"),
+    [
+        ((SplitAxis(kind="tp", dim=1),), (0,), "shard_dims"),
+        (
+            (SplitAxis(kind="tp", dim=0), ReplicatedAxis(kind="tp")),
+            (0,),
+            "duplicate",
+        ),
+        (
+            (SplitAxis(kind="tp", dim=0), SplitAxis(kind="ep", dim=0)),
+            (0,),
+            "share a dimension",
+        ),
+    ],
+)
+def test_tensor_descriptor_rejects_ambiguous_parallel_axis_semantics(
+    parallel_axes: tuple[object, ...],
+    shard_dims: tuple[int, ...],
+    message: str,
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        descriptor(
+            global_shape=(8, 8),
+            shard_dims=shard_dims,
+            parallel_axes=parallel_axes,
+        )
+
+
+def test_individually_allocated_expert_rejects_ep_split_semantics() -> None:
+    with pytest.raises(ValueError, match="individually allocated expert"):
+        descriptor(
+            expert_id=3,
+            parallel_axes=(SplitAxis(kind="ep", dim=0),),
+        )
+
+    assert descriptor(
+        expert_id=3,
+        shard_dims=(),
+        parallel_axes=(OwnershipAxis(kind="ep"),),
+    )
+
+
+@pytest.mark.parametrize(
+    ("factory", "message"),
+    [
+        (lambda: SplitAxis(kind="unknown", dim=0), "kind"),
+        (lambda: SplitAxis(kind="tp", dim=-1), "at least"),
+        (lambda: SplitAxis(kind="tp", dim=True), "integer"),
+        (lambda: SplitAxis(kind="pp", dim=0), "split semantics"),
+        (lambda: SplitAxis(kind="dp", dim=0), "split semantics"),
+        (lambda: SplitAxis(kind="ep", dim=1), "leading"),
+        (lambda: ReplicatedAxis(kind="unknown"), "kind"),
+        (lambda: OwnershipAxis(kind="unknown"), "kind"),
+    ],
+)
+def test_explicit_parallel_axis_rejects_invalid_schema(factory, message: str) -> None:
+    with pytest.raises(ValueError, match=message):
+        factory()
+
+
+@pytest.mark.parametrize(
+    ("overrides", "message"),
+    [
+        ({"global_shape": ()}, "global_shape"),
+        ({"global_shape": (8.0, 4)}, "integer"),
+        ({"itemsize": True}, "integer"),
+        ({"shard_dims": (0, 0)}, "duplicates"),
+        ({"shard_dims": (1, 0)}, "sorted"),
+        ({"shard_dims": (2,)}, "out-of-range"),
+        ({"shard_dims": (True,)}, "integer"),
+        ({"layout_fingerprint": ""}, "layout_fingerprint"),
+        ({"parallel_axes": (object(),)}, "explicit axis"),
+    ],
+)
+def test_tensor_descriptor_rejects_invalid_schema(
+    overrides: dict, message: str
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        descriptor(**overrides)
+
+
+@pytest.mark.parametrize(
+    "shape",
+    [
+        {8: None, 4: None},
+        {8, 4},
+        frozenset((8, 4)),
+        (extent for extent in (8, 4)),
+    ],
+)
+def test_tensor_descriptor_rejects_unordered_or_one_shot_shape(shape) -> None:
+    with pytest.raises(ValueError, match="global_shape must contain integers"):
+        descriptor(global_shape=shape)
+
+
+def test_tensor_descriptor_accepts_ordered_shape_sequence() -> None:
+    assert descriptor(global_shape=[8, 4]).global_shape == (8, 4)
+
+
+def test_tensor_descriptor_requires_explicit_layout_fingerprint() -> None:
+    values = {
+        "tensor_id": "weight",
+        "global_shape": (4, 4),
+        "dtype": "bfloat16",
+        "itemsize": 2,
+        "shard_dims": (0,),
+        "parallel_axes": (SplitAxis(kind="tp", dim=0),),
+    }
+
+    with pytest.raises(TypeError, match="layout_fingerprint"):
+        TensorDescriptor(**values)
+
+
+def test_placement_fragment_derives_stable_id_from_logical_content() -> None:
+    values = {
+        "tensor_id": "weight",
+        "global_offset": (0, 0),
+        "local_shape": (4, 4),
+        "nbytes": 32,
+        "rank": ParallelRank(tp=1),
+    }
+
+    first = PlacementFragment(**values)
+    second = PlacementFragment(**values)
+
+    assert first.placement_fragment_id == second.placement_fragment_id
+    assert first.placement_fragment_id.startswith("sha256:")
diff --git a/mooncake-reshard/tests/weight_manifest/test_binding.py b/mooncake-reshard/tests/weight_manifest/test_binding.py
new file mode 100644
index 0000000000..048ffa8b62
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_binding.py
@@ -0,0 +1,598 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from math import prod
+from types import SimpleNamespace
+
+import pytest
+
+from mooncake.reshard.weight import (
+    SplitAxis,
+    validate_runtime_binding,
+)
+
+from .helpers import (
+    binding_fragment,
+    binding_manifest,
+    descriptor,
+    placement_fragment,
+    placement_manifest,
+)
+
+
+def test_runtime_binding_fragment_retains_owner() -> None:
+    owner = object()
+
+    fragment = binding_fragment(owner=owner)
+
+    assert fragment.owner is owner
+    assert fragment.device == "cuda:0"
+
+
+def test_runtime_binding_rejects_duck_typed_manifests() -> None:
+    placement = placement_manifest()
+    binding = binding_manifest(placement=placement)
+    placement_fields = dict(vars(placement))
+    placement_fields.update(
+        resource_kind=placement.resource_kind,
+        digest=placement.digest,
+    )
+    duck_placement = SimpleNamespace(**placement_fields)
+    duck_binding = SimpleNamespace(
+        **vars(binding),
+        resource_kind=binding.resource_kind,
+    )
+
+    with pytest.raises(ValueError, match="WeightPlacementManifest"):
+        validate_runtime_binding(duck_placement, binding)
+    with pytest.raises(ValueError, match="WeightRuntimeBindingManifest"):
+        validate_runtime_binding(placement, duck_binding)
+
+
+def test_runtime_binding_rejects_noncanonical_stride() -> None:
+    placement = placement_manifest()
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(binding_fragment(strides_bytes=(2, 8)),),
+    )
+
+    with pytest.raises(ValueError, match="stride"):
+        validate_runtime_binding(placement, binding)
+
+
+@pytest.mark.parametrize(
+    ("shape", "strides_bytes", "canonical_strides_bytes"),
+    [
+        ((1, 4), (200, 2), (8, 2)),
+        ((4, 1), (2, 200), (2, 2)),
+        ((2, 1, 4), (8, 0, 2), (8, 8, 2)),
+        ((1,), (0,), (2,)),
+    ],
+)
+def test_binding_normalizes_stride_on_singleton_dimensions(
+    shape: tuple[int, ...],
+    strides_bytes: tuple[int, ...],
+    canonical_strides_bytes: tuple[int, ...],
+) -> None:
+    nbytes = prod(shape) * 2
+    tensor = descriptor(
+        global_shape=shape,
+        shard_dims=(),
+        parallel_axes=(),
+        expert_id=None,
+    )
+    placement = placement_manifest(
+        tensors=(tensor,),
+        fragments=(
+            placement_fragment(
+                global_offset=(0,) * len(shape),
+                local_shape=shape,
+                nbytes=nbytes,
+            ),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(
+                nbytes=nbytes,
+                local_shape=shape,
+                strides_bytes=strides_bytes,
+            ),
+        ),
+    )
+
+    assert binding.fragments[0].strides_bytes == canonical_strides_bytes
+    assert validate_runtime_binding(placement, binding) is None
+
+
+def test_runtime_binding_does_not_trust_runtime_itemsize() -> None:
+    placement = placement_manifest()
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(binding_fragment(itemsize=1),),
+    )
+
+    with pytest.raises(ValueError, match="itemsize"):
+        validate_runtime_binding(placement, binding)
+
+
+@pytest.mark.parametrize(
+    ("overrides", "message"),
+    [
+        ({"storage_offset_bytes": -1}, "storage_offset_bytes"),
+        ({"device": ""}, "device"),
+        (
+            {
+                "address": 0x1000,
+                "storage_address": 0x1000,
+                "storage_nbytes": 64,
+                "storage_offset_bytes": 8,
+            },
+            "storage_address plus",
+        ),
+        (
+            {
+                "address": 0x1010,
+                "storage_address": 0x1000,
+                "storage_nbytes": 40,
+                "storage_offset_bytes": 16,
+            },
+            "storage allocation",
+        ),
+    ],
+)
+def test_runtime_binding_fragment_rejects_unsafe_views(
+    overrides: dict, message: str
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        binding_fragment(**overrides)
+
+
+@pytest.mark.parametrize(
+    ("overrides", "message"),
+    [
+        ({"placement_digest": ""}, "placement_digest"),
+        ({"placement_digest": "g" * 64}, "SHA-256"),
+        ({"placement_digest": "a" * 63}, "SHA-256"),
+    ],
+)
+def test_runtime_binding_requires_content_attestation(
+    overrides: dict, message: str
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        binding_manifest(**overrides)
+
+
+@pytest.mark.parametrize(
+    "overrides, message",
+    [
+        ({"resource_id": "other"}, "resource_id"),
+        ({"revision": "other"}, "revision"),
+        ({"placement_id": "other"}, "placement_id"),
+    ],
+)
+def test_binding_rejects_identity_mismatch(overrides: dict, message: str) -> None:
+    with pytest.raises(ValueError, match=message):
+        validate_runtime_binding(placement_manifest(), binding_manifest(**overrides))
+
+
+def test_binding_requires_exact_fragment_set_and_size() -> None:
+    placement = placement_manifest()
+
+    with pytest.raises(ValueError, match="missing placement fragment"):
+        validate_runtime_binding(
+            placement,
+            binding_manifest(placement=placement, fragments=()),
+        )
+    with pytest.raises(ValueError, match="unknown placement fragment"):
+        validate_runtime_binding(
+            placement,
+            binding_manifest(
+                placement=placement,
+                fragments=(binding_fragment(placement_fragment_id="unknown"),),
+            ),
+        )
+    with pytest.raises(ValueError, match="byte size"):
+        validate_runtime_binding(
+            placement,
+            binding_manifest(
+                placement=placement,
+                fragments=(binding_fragment(nbytes=64),),
+            ),
+        )
+
+    with pytest.raises(ValueError, match="local_shape"):
+        validate_runtime_binding(
+            placement,
+            binding_manifest(
+                placement=placement,
+                fragments=(
+                    binding_fragment(
+                        local_shape=(2, 8),
+                        strides_bytes=(16, 2),
+                    ),
+                ),
+            ),
+        )
+
+
+def test_binding_rejects_duplicate_fragment_ids() -> None:
+    fragment = binding_fragment()
+
+    with pytest.raises(ValueError, match="duplicate placement fragment"):
+        binding_manifest(fragments=(fragment, replace(fragment, fragment_id="other")))
+    with pytest.raises(ValueError, match="duplicate runtime fragment_id"):
+        binding_manifest(
+            fragments=(
+                fragment,
+                replace(
+                    fragment,
+                    placement_fragment_id="placement-other",
+                ),
+            )
+        )
+
+
+def test_binding_allows_one_rank_to_span_runtime_locations() -> None:
+    placement = placement_manifest(
+        tensors=(descriptor(global_shape=(8, 4)),),
+        fragments=(
+            placement_fragment(placement_fragment_id="left"),
+            placement_fragment(
+                placement_fragment_id="right",
+                global_offset=(4, 0),
+            ),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(placement_fragment_id="left"),
+            binding_fragment(
+                placement_fragment_id="right",
+                fragment_id="runtime-right",
+                address=0x2000,
+                worker_id="worker-1",
+                endpoint="worker-1:12345",
+            ),
+        ),
+    )
+
+    assert validate_runtime_binding(placement, binding) is None
+
+
+@pytest.mark.parametrize("right_address", [0x1000, 0x1010])
+def test_binding_rejects_overlapping_runtime_ranges(right_address: int) -> None:
+    placement = placement_manifest(
+        tensors=(
+            descriptor(tensor_id="a.weight"),
+            descriptor(tensor_id="b.weight"),
+        ),
+        fragments=(
+            placement_fragment(
+                placement_fragment_id="a",
+                tensor_id="a.weight",
+            ),
+            placement_fragment(
+                placement_fragment_id="b",
+                tensor_id="b.weight",
+            ),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(placement_fragment_id="a", fragment_id="runtime-a"),
+            binding_fragment(
+                placement_fragment_id="b",
+                fragment_id="runtime-b",
+                address=right_address,
+                endpoint="worker-0:54321",
+            ),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="address ranges overlap"):
+        validate_runtime_binding(placement, binding)
+
+
+def test_binding_rejects_partially_overlapping_storage_allocations() -> None:
+    placement = placement_manifest(
+        tensors=(
+            descriptor(tensor_id="a.weight"),
+            descriptor(tensor_id="b.weight"),
+        ),
+        fragments=(
+            placement_fragment(placement_fragment_id="a", tensor_id="a.weight"),
+            placement_fragment(placement_fragment_id="b", tensor_id="b.weight"),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(
+                placement_fragment_id="a",
+                fragment_id="runtime-a",
+                address=0x1100,
+                storage_address=0x1000,
+                storage_nbytes=0x1000,
+                storage_offset_bytes=0x100,
+            ),
+            binding_fragment(
+                placement_fragment_id="b",
+                fragment_id="runtime-b",
+                address=0x2100,
+                storage_address=0x1800,
+                storage_nbytes=0x1000,
+                storage_offset_bytes=0x900,
+            ),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="storage allocation ranges overlap"):
+        validate_runtime_binding(placement, binding)
+
+
+def test_binding_allows_disjoint_views_of_same_storage_allocation() -> None:
+    placement = placement_manifest(
+        tensors=(
+            descriptor(tensor_id="a.weight"),
+            descriptor(tensor_id="b.weight"),
+        ),
+        fragments=(
+            placement_fragment(placement_fragment_id="a", tensor_id="a.weight"),
+            placement_fragment(placement_fragment_id="b", tensor_id="b.weight"),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(
+                placement_fragment_id="a",
+                fragment_id="runtime-a",
+                address=0x1000,
+                storage_address=0x1000,
+                storage_nbytes=0x100,
+                storage_offset_bytes=0,
+            ),
+            binding_fragment(
+                placement_fragment_id="b",
+                fragment_id="runtime-b",
+                address=0x1080,
+                storage_address=0x1000,
+                storage_nbytes=0x100,
+                storage_offset_bytes=0x80,
+            ),
+        ),
+    )
+
+    assert validate_runtime_binding(placement, binding) is None
+
+
+def test_binding_treats_endpoint_as_routing_not_address_space() -> None:
+    placement = placement_manifest(
+        tensors=(
+            descriptor(tensor_id="a.weight"),
+            descriptor(tensor_id="b.weight"),
+        ),
+        fragments=(
+            placement_fragment(placement_fragment_id="a", tensor_id="a.weight"),
+            placement_fragment(placement_fragment_id="b", tensor_id="b.weight"),
+        ),
+    )
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(placement_fragment_id="a", fragment_id="runtime-a"),
+            binding_fragment(
+                placement_fragment_id="b",
+                fragment_id="runtime-b",
+                endpoint="worker-0:54321",
+            ),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="address ranges overlap"):
+        validate_runtime_binding(placement, binding)
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [("worker_id", "worker-1"), ("device", "cuda:1")],
+)
+def test_binding_separates_worker_and_device_address_spaces(
+    field: str,
+    value: str,
+) -> None:
+    placement = placement_manifest(
+        tensors=(
+            descriptor(tensor_id="a.weight"),
+            descriptor(tensor_id="b.weight"),
+        ),
+        fragments=(
+            placement_fragment(placement_fragment_id="a", tensor_id="a.weight"),
+            placement_fragment(placement_fragment_id="b", tensor_id="b.weight"),
+        ),
+    )
+    second_overrides = {
+        "placement_fragment_id": "b",
+        "fragment_id": "runtime-b",
+        field: value,
+    }
+    if field == "worker_id":
+        second_overrides["endpoint"] = "worker-1:12345"
+    binding = binding_manifest(
+        placement=placement,
+        fragments=(
+            binding_fragment(placement_fragment_id="a", fragment_id="runtime-a"),
+            binding_fragment(**second_overrides),
+        ),
+    )
+
+    assert validate_runtime_binding(placement, binding) is None
+
+
+def test_binding_allows_only_exact_compatible_declared_aliases() -> None:
+    aliases = ("embed.weight", "head.weight")
+    tensors = (
+        descriptor(tensor_id="embed.weight", expert_id=None),
+        descriptor(tensor_id="head.weight", expert_id=None),
+    )
+    fragments = (
+        placement_fragment(
+            placement_fragment_id="embed",
+            tensor_id="embed.weight",
+            aliases=aliases,
+        ),
+        placement_fragment(
+            placement_fragment_id="head",
+            tensor_id="head.weight",
+            aliases=aliases,
+        ),
+    )
+    placement = placement_manifest(tensors=tensors, fragments=fragments)
+    binding_fragments = (
+        binding_fragment(
+            placement_fragment_id="embed",
+            fragment_id="runtime-embed",
+        ),
+        binding_fragment(
+            placement_fragment_id="head",
+            fragment_id="runtime-head",
+        ),
+    )
+
+    assert (
+        validate_runtime_binding(
+            placement,
+            binding_manifest(placement=placement, fragments=binding_fragments),
+        )
+        is None
+    )
+
+    incompatible = placement_manifest(
+        tensors=(
+            tensors[0],
+            replace(tensors[1], layout_fingerprint="different"),
+        ),
+        fragments=fragments,
+    )
+    with pytest.raises(ValueError, match="address ranges overlap"):
+        validate_runtime_binding(
+            incompatible,
+            binding_manifest(
+                placement=incompatible,
+                fragments=binding_fragments,
+            ),
+        )
+
+    incompatible_axes = placement_manifest(
+        tensors=(
+            tensors[0],
+            replace(
+                tensors[1],
+                parallel_axes=(SplitAxis(kind="ep", dim=0),),
+            ),
+        ),
+        fragments=fragments,
+    )
+    with pytest.raises(ValueError, match="address ranges overlap"):
+        validate_runtime_binding(
+            incompatible_axes,
+            binding_manifest(
+                placement=incompatible_axes,
+                fragments=binding_fragments,
+            ),
+        )
+
+
+def test_binding_rejects_alias_group_without_tensor_members() -> None:
+    aliases = ("unrelated-x", "unrelated-y")
+
+    with pytest.raises(ValueError, match="alias"):
+        placement_manifest(
+            tensors=(
+                descriptor(tensor_id="a.weight"),
+                descriptor(tensor_id="b.weight"),
+            ),
+            fragments=(
+                placement_fragment(
+                    placement_fragment_id="a",
+                    tensor_id="a.weight",
+                    aliases=aliases,
+                ),
+                placement_fragment(
+                    placement_fragment_id="b",
+                    tensor_id="b.weight",
+                    aliases=aliases,
+                ),
+            ),
+        )
+
+
+def test_binding_validation_preserves_logical_and_physical_halves() -> None:
+    placement = placement_manifest()
+    binding = binding_manifest(placement=placement)
+
+    assert validate_runtime_binding(placement, binding) is None
+    assert placement.fragments[0].global_offset == (0, 0)
+    assert binding.fragments[0].address == 0x1000
+
+
+def test_binding_validation_is_order_independent() -> None:
+    tensors = (
+        descriptor(tensor_id="a.weight"),
+        descriptor(tensor_id="b.weight"),
+    )
+    fragments = (
+        placement_fragment(
+            placement_fragment_id="a",
+            tensor_id="a.weight",
+        ),
+        placement_fragment(
+            placement_fragment_id="b",
+            tensor_id="b.weight",
+        ),
+    )
+    placement = placement_manifest(tensors=tensors, fragments=fragments)
+    bindings = (
+        binding_fragment(
+            placement_fragment_id="a",
+            fragment_id="runtime-a",
+            address=0x1000,
+        ),
+        binding_fragment(
+            placement_fragment_id="b",
+            fragment_id="runtime-b",
+            address=0x2000,
+        ),
+    )
+
+    first = validate_runtime_binding(
+        placement,
+        binding_manifest(placement=placement, fragments=bindings),
+    )
+    second = validate_runtime_binding(
+        placement,
+        binding_manifest(
+            placement=placement,
+            fragments=tuple(reversed(bindings)),
+        ),
+    )
+
+    assert first == second
+
+
+@pytest.mark.parametrize(
+    ("overrides", "message"),
+    [
+        ({"tensors": (), "fragments": ()}, "must contain tensors"),
+    ],
+)
+def test_global_placement_must_not_be_empty(
+    overrides: dict,
+    message: str,
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        placement_manifest(**overrides)
diff --git a/mooncake-reshard/tests/weight_manifest/test_canonical_boundary.py b/mooncake-reshard/tests/weight_manifest/test_canonical_boundary.py
new file mode 100644
index 0000000000..6c2553fa11
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_canonical_boundary.py
@@ -0,0 +1,233 @@
+"""Contract tests for the canonical framework/core boundary."""
+
+import json
+from dataclasses import fields
+from typing import Any, Protocol, get_type_hints
+
+import pytest
+
+from mooncake.reshard.contracts import (
+    PlacementManifest,
+    ResourceManifest,
+    RuntimeBindingManifest,
+)
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TensorDescriptor,
+    TopologyParticipant,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+    weight_placement_from_json,
+    weight_placement_to_json,
+)
+
+from .helpers import descriptor, placement_fragment, placement_manifest
+
+
+def test_resource_contracts_are_structural_protocols() -> None:
+    assert issubclass(ResourceManifest, Protocol)
+    assert issubclass(PlacementManifest, Protocol)
+    assert issubclass(RuntimeBindingManifest, Protocol)
+
+
+def test_core_exposes_only_typed_manifest_constructors() -> None:
+    assert not hasattr(WeightPlacementPart, "from_runtime_inventory")
+    assert not hasattr(WeightRuntimeBindingManifest, "from_runtime_inventory")
+    assert get_type_hints(RuntimeBindingFragment)["owner"] != Any
+
+
+def test_tensor_descriptor_has_one_canonical_shard_representation() -> None:
+    assert "partition_dim" not in {field.name for field in fields(TensorDescriptor)}
+
+    descriptor = TensorDescriptor(
+        tensor_id="decoder.layer.0.mlp.weight",
+        global_shape=(8, 16),
+        dtype="float16",
+        itemsize=2,
+        shard_dims=(0,),
+        layout_fingerprint="row-major",
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+
+    assert descriptor.shard_dims == (0,)
+
+
+def test_parallel_axis_semantics_are_explicit() -> None:
+    assert SplitAxis(kind="tp", dim=1).dim == 1
+    assert ReplicatedAxis(kind="dp").kind == "dp"
+    assert OwnershipAxis(kind="pp").kind == "pp"
+
+    with pytest.raises(ValueError, match="EP must split"):
+        SplitAxis(kind="ep", dim=1)
+
+
+def test_weight_placement_serde_accepts_only_canonical_wire_fields() -> None:
+    placement = placement_manifest()
+    encoded = weight_placement_to_json(placement)
+
+    assert weight_placement_from_json(encoded) == placement
+    assert "partition_dim" not in encoded
+
+
+@pytest.mark.parametrize("alias", ["model_id", "partition_dim", "split_dim"])
+def test_weight_placement_serde_rejects_framework_and_legacy_aliases(
+    alias: str,
+) -> None:
+    payload = json.loads(weight_placement_to_json(placement_manifest()))
+    if alias == "model_id":
+        payload[alias] = payload.pop("resource_id")
+    elif alias == "partition_dim":
+        payload["tensors"][0][alias] = payload["tensors"][0]["shard_dims"][0]
+    else:
+        axis = payload["tensors"][0]["parallel_axes"][0]
+        axis[alias] = axis.pop("dim")
+
+    with pytest.raises(ValueError, match="schema fields"):
+        weight_placement_from_json(json.dumps(payload))
+
+
+def test_split_axis_collectively_covers_once_with_all_split_ranks() -> None:
+    topology = _two_rank_topology("tp")
+    tensor = descriptor(
+        global_shape=(8, 4),
+        shard_dims=(0,),
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=(
+            placement_fragment(
+                placement_fragment_id="tp-0",
+                local_shape=(4, 4),
+                nbytes=32,
+                rank=ParallelRank(tp=0),
+            ),
+            placement_fragment(
+                placement_fragment_id="tp-1",
+                global_offset=(4, 0),
+                local_shape=(4, 4),
+                nbytes=32,
+                rank=ParallelRank(tp=1),
+            ),
+        ),
+    )
+
+    assert len(placement.fragments) == 2
+
+
+def test_replicated_axis_requires_an_independent_cover_for_every_rank() -> None:
+    topology = _two_rank_topology("tp")
+    tensor = descriptor(
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(ReplicatedAxis(kind="tp"),),
+    )
+
+    with pytest.raises(ValueError, match="replicated-axis participant"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=(placement_fragment(rank=ParallelRank(tp=0)),),
+        )
+
+
+def test_replicated_axis_accepts_independent_complete_covers() -> None:
+    topology = _two_rank_topology("tp")
+    tensor = descriptor(
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(ReplicatedAxis(kind="tp"),),
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=(
+            placement_fragment(
+                placement_fragment_id="replica-0",
+                rank=ParallelRank(tp=0),
+            ),
+            placement_fragment(
+                placement_fragment_id="replica-1",
+                rank=ParallelRank(tp=1),
+            ),
+        ),
+    )
+
+    assert len(placement.fragments) == 2
+
+
+def test_ownership_axis_requires_only_declared_owners() -> None:
+    topology = _two_rank_topology("pp")
+    tensor = descriptor(
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(OwnershipAxis(kind="pp"),),
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=(placement_fragment(rank=ParallelRank(pp=0)),),
+    )
+
+    assert {fragment.rank.pp for fragment in placement.fragments} == {0}
+
+
+def test_ownership_axis_rejects_cover_split_across_declared_owners() -> None:
+    topology = _two_rank_topology("pp")
+    tensor = descriptor(
+        global_shape=(8, 4),
+        shard_dims=(0,),
+        expert_id=None,
+        parallel_axes=(
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=(
+                placement_fragment(
+                    placement_fragment_id="owner-0",
+                    local_shape=(4, 4),
+                    nbytes=32,
+                    rank=ParallelRank(pp=0),
+                ),
+                placement_fragment(
+                    placement_fragment_id="owner-1",
+                    global_offset=(4, 0),
+                    local_shape=(4, 4),
+                    nbytes=32,
+                    rank=ParallelRank(pp=1),
+                ),
+            ),
+        )
+
+
+def _two_rank_topology(kind: str) -> ParallelTopology:
+    first = ParallelRank()
+    second_values = {"dp": 0, "tp": 0, "pp": 0, "ep": 0}
+    second_values[kind] = 1
+    second = ParallelRank(**second_values)
+    return ParallelTopology(
+        tp_size=2 if kind == "tp" else 1,
+        pp_size=2 if kind == "pp" else 1,
+        ep_size=2 if kind == "ep" else 1,
+        dp_size=2 if kind == "dp" else 1,
+        participants=(
+            TopologyParticipant("worker-0", first),
+            TopologyParticipant("worker-1", second),
+        ),
+    )
diff --git a/mooncake-reshard/tests/weight_manifest/test_global_placement.py b/mooncake-reshard/tests/weight_manifest/test_global_placement.py
new file mode 100644
index 0000000000..b39dd0d460
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_global_placement.py
@@ -0,0 +1,983 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+import mooncake.reshard.weight.serde as weight_serde
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    ParallelTopology,
+    PlacementFragment,
+    ReplicatedAxis,
+    RuntimeBindingFragment,
+    SplitAxis,
+    TopologyParticipant,
+    WeightPlacementManifest,
+    WeightPlacementPart,
+    WeightRuntimeBindingManifest,
+    validate_runtime_binding,
+    validate_runtime_bindings,
+    weight_placement_from_json,
+    weight_placement_to_json,
+)
+
+from .helpers import (
+    MODEL_ID,
+    PLACEMENT_SET_ID,
+    REVISION,
+    WEIGHT_GENERATION,
+    _contiguous_strides_bytes,
+    descriptor,
+    parallel_topology,
+    placement_manifest,
+    placement_part,
+)
+
+
+def _topology() -> ParallelTopology:
+    return parallel_topology(
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(tp=0)),
+            TopologyParticipant("worker-1", ParallelRank(tp=1)),
+        ),
+    )
+
+
+def _part(
+    participant_id: str,
+    rank: ParallelRank,
+    offset: int,
+    *,
+    placement_set_id: str = "placement-set-7",
+    weight_generation: int = 7,
+    topology_id: str | None = None,
+) -> WeightPlacementPart:
+    topology = _topology()
+    tensor = descriptor(
+        global_shape=(8, 4),
+        parallel_axes=(
+            ReplicatedAxis(kind="dp"),
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    return placement_part(
+        topology=topology,
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        weight_generation=weight_generation,
+        placement_set_id=placement_set_id,
+        topology_id=topology_id or topology.topology_id,
+        participant_id=participant_id,
+        rank=rank,
+        tensors=(tensor,),
+        fragments=(
+            PlacementFragment(
+                placement_fragment_id=f"fragment-{participant_id}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(offset, 0),
+                local_shape=(4, 4),
+                nbytes=32,
+                rank=rank,
+            ),
+        ),
+    )
+
+
+def _manifest(
+    *,
+    topology: ParallelTopology | None = None,
+    parts: tuple[WeightPlacementPart, ...] | None = None,
+) -> WeightPlacementManifest:
+    topology = topology or _topology()
+    selected_parts = (
+        parts
+        if parts is not None
+        else (
+            _part("worker-0", ParallelRank(tp=0), 0),
+            _part("worker-1", ParallelRank(tp=1), 4),
+        )
+    )
+    return placement_manifest(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        weight_generation=WEIGHT_GENERATION,
+        placement_set_id=PLACEMENT_SET_ID,
+        topology=topology,
+        parts=selected_parts,
+    )
+
+
+def test_weight_placement_manifest_is_one_complete_global_placement() -> None:
+    placement = _manifest()
+
+    assert placement.topology.world_size == 2
+    assert len(placement.parts) == 2
+    assert len(placement.tensors) == 1
+    assert len(placement.fragments) == 2
+    assert weight_placement_from_json(weight_placement_to_json(placement)) == placement
+
+
+def test_placement_part_rejects_unreferenced_tensor_descriptors() -> None:
+    with pytest.raises(ValueError, match="unreferenced tensor"):
+        placement_part(tensors=(descriptor(),), fragments=())
+
+
+def test_flat_placement_rejects_unreferenced_tensor_descriptors() -> None:
+    topology = parallel_topology()
+    referenced = descriptor(tensor_id="referenced.weight")
+    unreferenced = descriptor(tensor_id="unreferenced.weight")
+    fragment = PlacementFragment(
+        placement_fragment_id="referenced-fragment",
+        tensor_id=referenced.tensor_id,
+        global_offset=(0, 0),
+        local_shape=(4, 4),
+        nbytes=32,
+        rank=ParallelRank(),
+    )
+
+    with pytest.raises(ValueError, match="unreferenced tensor"):
+        WeightPlacementManifest.from_fragments(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            weight_generation=WEIGHT_GENERATION,
+            placement_set_id=PLACEMENT_SET_ID,
+            topology=topology,
+            tensors=(referenced, unreferenced),
+            fragments=(fragment,),
+        )
+
+
+def test_global_placement_rejects_alias_member_missing_from_tensor_inventory() -> None:
+    tensor = descriptor(tensor_id="tied.embedding")
+    fragment = PlacementFragment(
+        placement_fragment_id="tied-embedding",
+        tensor_id=tensor.tensor_id,
+        global_offset=(0, 0),
+        local_shape=(4, 4),
+        nbytes=32,
+        rank=ParallelRank(),
+        aliases=("tied.embedding", "tied.output"),
+    )
+
+    with pytest.raises(ValueError, match="alias group references unknown tensor"):
+        placement_manifest(tensors=(tensor,), fragments=(fragment,))
+
+
+def test_global_placement_requires_every_alias_member_to_declare_the_group() -> None:
+    embedding = descriptor(tensor_id="tied.embedding")
+    output = descriptor(tensor_id="tied.output")
+    aliases = (embedding.tensor_id, output.tensor_id)
+    fragments = (
+        PlacementFragment(
+            placement_fragment_id="tied-embedding",
+            tensor_id=embedding.tensor_id,
+            global_offset=(0, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=ParallelRank(),
+            aliases=aliases,
+        ),
+        PlacementFragment(
+            placement_fragment_id="tied-output",
+            tensor_id=output.tensor_id,
+            global_offset=(0, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=ParallelRank(),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="alias group is not declared consistently"):
+        placement_manifest(
+            tensors=(embedding, output),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_caches_digest_for_all_participant_bindings(
+    monkeypatch,
+) -> None:
+    placement = _manifest()
+    original = weight_serde.weight_placement_to_json
+    calls = 0
+
+    def counted_to_json(value):
+        nonlocal calls
+        calls += 1
+        return original(value)
+
+    monkeypatch.setattr(weight_serde, "weight_placement_to_json", counted_to_json)
+
+    assert placement.digest == placement.digest
+    assert calls == 1
+
+
+def test_topology_uses_explicit_participants_instead_of_axis_product() -> None:
+    topology = ParallelTopology(
+        tp_size=2,
+        pp_size=1,
+        ep_size=2,
+        dp_size=1,
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(tp=0, ep=0)),
+            TopologyParticipant("worker-1", ParallelRank(tp=1, ep=1)),
+        ),
+    )
+
+    assert topology.world_size == 2
+    assert topology.world_size != topology.tp_size * topology.ep_size
+
+
+def test_global_placement_may_select_one_complete_dp_replica() -> None:
+    topology = ParallelTopology(
+        tp_size=2,
+        pp_size=4,
+        ep_size=1,
+        dp_size=2,
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(dp=0, tp=0, pp=1)),
+            TopologyParticipant("worker-1", ParallelRank(dp=0, tp=1, pp=1)),
+        ),
+    )
+    placement = _manifest(
+        topology=topology,
+        parts=(
+            _part(
+                "worker-0",
+                ParallelRank(dp=0, tp=0, pp=1),
+                0,
+                topology_id=topology.topology_id,
+            ),
+            _part(
+                "worker-1",
+                ParallelRank(dp=0, tp=1, pp=1),
+                4,
+                topology_id=topology.topology_id,
+            ),
+        ),
+    )
+
+    assert placement.topology.dp_size == 2
+    assert {part.rank.dp for part in placement.parts} == {0}
+
+
+def test_global_placement_rejects_an_empty_selected_dp_replica() -> None:
+    topology = ParallelTopology(
+        tp_size=2,
+        pp_size=1,
+        ep_size=1,
+        dp_size=2,
+        participants=(
+            TopologyParticipant("dp0-tp0", ParallelRank(dp=0, tp=0)),
+            TopologyParticipant("dp0-tp1", ParallelRank(dp=0, tp=1)),
+            TopologyParticipant("dp1-tp0", ParallelRank(dp=1, tp=0)),
+            TopologyParticipant("dp1-tp1", ParallelRank(dp=1, tp=1)),
+        ),
+    )
+    complete_parts = (
+        _part(
+            "dp0-tp0",
+            ParallelRank(dp=0, tp=0),
+            0,
+            topology_id=topology.topology_id,
+        ),
+        _part(
+            "dp0-tp1",
+            ParallelRank(dp=0, tp=1),
+            4,
+            topology_id=topology.topology_id,
+        ),
+    )
+    empty_parts = tuple(
+        WeightPlacementPart(
+            resource_id=MODEL_ID,
+            revision=REVISION,
+            weight_generation=WEIGHT_GENERATION,
+            placement_set_id=PLACEMENT_SET_ID,
+            topology_id=topology.topology_id,
+            participant_id=f"dp1-tp{tp}",
+            rank=ParallelRank(dp=1, tp=tp),
+            tensors=(),
+            fragments=(),
+        )
+        for tp in range(2)
+    )
+
+    with pytest.raises(ValueError, match="replicated-axis participant"):
+        _manifest(topology=topology, parts=complete_parts + empty_parts)
+
+
+def test_global_placement_rejects_missing_or_duplicate_participants() -> None:
+    left = _part("worker-0", ParallelRank(tp=0), 0)
+    right = _part("worker-1", ParallelRank(tp=1), 4)
+
+    with pytest.raises(ValueError, match="missing topology participant"):
+        _manifest(parts=(left,))
+    with pytest.raises(ValueError, match="duplicate placement participant"):
+        _manifest(parts=(left, replace(right, participant_id="worker-0")))
+
+
+@pytest.mark.parametrize(
+    ("replacement", "message"),
+    [
+        ({"resource_id": "other-model"}, "resource_id"),
+        ({"revision": "other-revision"}, "revision"),
+        ({"placement_set_id": "other-set"}, "placement_set_id"),
+        ({"weight_generation": 8}, "weight_generation"),
+        ({"topology_id": "sha256:" + "0" * 64}, "topology_id"),
+    ],
+)
+def test_global_placement_rejects_parts_from_another_collection(
+    replacement: dict[str, object], message: str
+) -> None:
+    left = _part("worker-0", ParallelRank(tp=0), 0)
+    right = replace(_part("worker-1", ParallelRank(tp=1), 4), **replacement)
+
+    with pytest.raises(ValueError, match=message):
+        _manifest(parts=(left, right))
+
+
+def test_global_placement_rejects_incomplete_tensor_coverage() -> None:
+    left = _part("worker-0", ParallelRank(tp=0), 0)
+    right = _part("worker-1", ParallelRank(tp=1), 4)
+    incomplete = replace(
+        right,
+        fragments=(
+            replace(
+                right.fragments[0],
+                local_shape=(2, 4),
+                nbytes=16,
+            ),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        _manifest(parts=(left, incomplete))
+
+
+def test_global_placement_requires_every_split_axis_participant() -> None:
+    topology = _topology()
+    present = _part("worker-0", ParallelRank(tp=0), 0)
+    present = replace(
+        present,
+        fragments=(
+            replace(
+                present.fragments[0],
+                local_shape=(8, 4),
+                nbytes=64,
+            ),
+        ),
+    )
+    missing = WeightPlacementPart(
+        resource_id=MODEL_ID,
+        revision=REVISION,
+        weight_generation=WEIGHT_GENERATION,
+        placement_set_id=PLACEMENT_SET_ID,
+        topology_id=topology.topology_id,
+        participant_id="worker-1",
+        rank=ParallelRank(tp=1),
+        tensors=(),
+        fragments=(),
+    )
+
+    with pytest.raises(ValueError, match="split-axis participant"):
+        _manifest(topology=topology, parts=(present, missing))
+
+
+def test_global_placement_rejects_full_shard_on_each_split_rank() -> None:
+    tensor = descriptor(
+        tensor_id="model.layers.0.mlp.weight",
+        global_shape=(8, 4),
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    topology = _topology()
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"tp{tp_rank}-full",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0, 0),
+            local_shape=tensor.global_shape,
+            nbytes=64,
+            rank=ParallelRank(tp=tp_rank),
+        )
+        for tp_rank in range(2)
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_rejects_missing_declared_split_rank() -> None:
+    topology = parallel_topology(tp_size=2)
+
+    with pytest.raises(ValueError, match="split-axis participant"):
+        placement_manifest(topology=topology)
+
+
+def test_global_placement_accepts_independent_tp_replicas() -> None:
+    tensor = descriptor(
+        tensor_id="model.norm.weight",
+        global_shape=(4,),
+        shard_dims=(),
+        parallel_axes=(ReplicatedAxis(kind="tp"),),
+        layer_id=None,
+        expert_id=None,
+    )
+    topology = _topology()
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"replica-{tp_rank}",
+            tensor_id=tensor.tensor_id,
+            global_offset=(0,),
+            local_shape=(4,),
+            nbytes=8,
+            rank=ParallelRank(tp=tp_rank),
+        )
+        for tp_rank in range(2)
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=fragments,
+    )
+
+    assert len(placement.fragments) == 2
+
+
+def test_global_placement_accepts_complete_replicas_on_multiple_pp_owners() -> None:
+    tensor = descriptor(
+        tensor_id="lm_head.weight",
+        global_shape=(8, 4),
+        layer_id=None,
+        expert_id=None,
+        parallel_axes=(
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    participants = tuple(
+        TopologyParticipant(
+            f"pp{pp_rank}-tp{tp_rank}",
+            ParallelRank(tp=tp_rank, pp=pp_rank),
+        )
+        for pp_rank in range(2)
+        for tp_rank in range(2)
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=f"pp{pp_rank}-tp{tp_rank}",
+            tensor_id=tensor.tensor_id,
+            global_offset=(tp_rank * 4, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=ParallelRank(tp=tp_rank, pp=pp_rank),
+        )
+        for pp_rank in range(2)
+        for tp_rank in range(2)
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=fragments,
+    )
+
+    assert {fragment.rank.pp for fragment in placement.fragments} == {0, 1}
+
+
+def test_global_placement_rejects_coverage_split_across_pp_owners() -> None:
+    tensor = descriptor(
+        tensor_id="lm_head.weight",
+        global_shape=(8, 4),
+        layer_id=None,
+        expert_id=None,
+        parallel_axes=(
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    participants = (
+        TopologyParticipant("pp0-tp0", ParallelRank(tp=0, pp=0)),
+        TopologyParticipant("pp1-tp1", ParallelRank(tp=1, pp=1)),
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(participant.rank.tp * 4, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+@pytest.mark.parametrize("undeclared_kind", ["pp", "dp"])
+def test_global_placement_rejects_coverage_across_undeclared_axis(
+    undeclared_kind: str,
+) -> None:
+    tensor = descriptor(
+        tensor_id="lm_head.weight",
+        global_shape=(8, 4),
+        layer_id=None,
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    rank_overrides = (
+        {"tp": 0, undeclared_kind: 0},
+        {"tp": 1, undeclared_kind: 1},
+    )
+    participants = tuple(
+        TopologyParticipant(
+            f"worker-{index}",
+            ParallelRank(**coordinates),
+        )
+        for index, coordinates in enumerate(rank_overrides)
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(participant.rank.tp * 4, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match=f"undeclared {undeclared_kind} axis"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_rejects_implicit_pp_owner() -> None:
+    tensor = descriptor(
+        tensor_id="lm_head.weight",
+        global_shape=(4, 4),
+        shard_dims=(),
+        layer_id=None,
+        expert_id=None,
+        parallel_axes=(),
+    )
+    topology = parallel_topology(
+        participants=(
+            TopologyParticipant("pp-0", ParallelRank(pp=0)),
+            TopologyParticipant("pp-1", ParallelRank(pp=1)),
+        )
+    )
+
+    with pytest.raises(ValueError, match="active undeclared pp axis"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=(
+                PlacementFragment(
+                    placement_fragment_id="pp-1-fragment",
+                    tensor_id=tensor.tensor_id,
+                    global_offset=(0, 0),
+                    local_shape=(4, 4),
+                    nbytes=32,
+                    rank=ParallelRank(pp=1),
+                ),
+            ),
+        )
+
+
+def test_global_placement_rejects_swapped_cartesian_ep_tp_geometry() -> None:
+    tensor = descriptor(
+        tensor_id="experts.weight",
+        global_shape=(4, 4),
+        shard_dims=(0, 1),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+    participants = tuple(
+        TopologyParticipant(
+            f"ep{ep_rank}-tp{tp_rank}",
+            ParallelRank(ep=ep_rank, tp=tp_rank),
+        )
+        for ep_rank in range(2)
+        for tp_rank in range(2)
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            # Deliberately assign TP to dim0 and EP to dim1.
+            global_offset=(participant.rank.tp * 2, participant.rank.ep * 2),
+            local_shape=(2, 2),
+            nbytes=8,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match="split-axis rank geometry"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_rejects_non_cartesian_multi_split_geometry() -> None:
+    tensor = descriptor(
+        tensor_id="experts.weight",
+        global_shape=(4, 4),
+        shard_dims=(0, 1),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+    participants = (
+        TopologyParticipant("ep0-tp0", ParallelRank(ep=0, tp=0)),
+        TopologyParticipant("ep1-tp1", ParallelRank(ep=1, tp=1)),
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            # The boxes cover the tensor only along EP/dim0. TP/dim1 is not split.
+            global_offset=(participant.rank.ep * 2, 0),
+            local_shape=(2, 4),
+            nbytes=16,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match="non-Cartesian split-axis"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_accepts_ep_rank_derived_from_tp_rank() -> None:
+    tensor = descriptor(
+        tensor_id="dense.weight",
+        global_shape=(8, 4),
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    participants = tuple(
+        TopologyParticipant(
+            f"tp-{tp_rank}",
+            ParallelRank(tp=tp_rank, ep=tp_rank // 2),
+        )
+        for tp_rank in range(4)
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(participant.rank.tp * 2, 0),
+            local_shape=(2, 4),
+            nbytes=16,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=fragments,
+    )
+
+    assert len(placement.fragments) == 4
+
+
+def test_global_placement_rejects_independent_undeclared_ep_rank() -> None:
+    tensor = descriptor(
+        tensor_id="dense.weight",
+        global_shape=(8, 4),
+        expert_id=None,
+        parallel_axes=(SplitAxis(kind="tp", dim=0),),
+    )
+    participants = tuple(
+        TopologyParticipant(
+            f"ep{ep_rank}-tp{tp_rank}",
+            ParallelRank(ep=ep_rank, tp=tp_rank),
+        )
+        for ep_rank in range(2)
+        for tp_rank in range(2)
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(participant.rank.tp * 4, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match="independently.*undeclared ep axis"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_global_placement_rejects_coverage_split_across_ep_owners() -> None:
+    tensor = descriptor(
+        tensor_id="experts.weight",
+        global_shape=(8, 4),
+        expert_id=None,
+        parallel_axes=(
+            OwnershipAxis(kind="ep"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    participants = (
+        TopologyParticipant("ep0-tp0", ParallelRank(ep=0, tp=0)),
+        TopologyParticipant("ep1-tp1", ParallelRank(ep=1, tp=1)),
+    )
+    topology = parallel_topology(participants=participants)
+    fragments = tuple(
+        PlacementFragment(
+            placement_fragment_id=participant.participant_id,
+            tensor_id=tensor.tensor_id,
+            global_offset=(participant.rank.tp * 4, 0),
+            local_shape=(4, 4),
+            nbytes=32,
+            rank=participant.rank,
+        )
+        for participant in participants
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_topology_rejects_out_of_range_rank_coordinates() -> None:
+    with pytest.raises(ValueError, match="tp rank"):
+        ParallelTopology(
+            tp_size=2,
+            pp_size=1,
+            ep_size=1,
+            dp_size=1,
+            participants=(TopologyParticipant("worker-0", ParallelRank(tp=2)),),
+        )
+
+
+def _binding(
+    placement: WeightPlacementManifest,
+    participant_id: str,
+    *,
+    instance_id: str,
+) -> WeightRuntimeBindingManifest:
+    part = next(
+        item for item in placement.parts if item.participant_id == participant_id
+    )
+    tensor_by_id = {tensor.tensor_id: tensor for tensor in placement.tensors}
+    return WeightRuntimeBindingManifest(
+        resource_id=placement.resource_id,
+        revision=placement.revision,
+        placement_id=placement.placement_id,
+        placement_digest=placement.digest,
+        participant_id=participant_id,
+        instance_id=instance_id,
+        generation=3,
+        lease_id=f"lease-{participant_id}",
+        fragments=tuple(
+            RuntimeBindingFragment(
+                placement_fragment_id=fragment.placement_fragment_id,
+                fragment_id=f"runtime-{fragment.placement_fragment_id}",
+                address=0x1000 + index * 0x100,
+                nbytes=fragment.nbytes,
+                worker_id=participant_id,
+                endpoint=f"{participant_id}:12345",
+                device="cuda:0",
+                itemsize=tensor_by_id[fragment.tensor_id].itemsize,
+                local_shape=fragment.local_shape,
+                strides_bytes=_contiguous_strides_bytes(
+                    fragment.local_shape,
+                    tensor_by_id[fragment.tensor_id].itemsize,
+                ),
+                storage_address=0x1000 + index * 0x100,
+                storage_nbytes=fragment.nbytes,
+                storage_offset_bytes=0,
+            )
+            for index, fragment in enumerate(part.fragments)
+        ),
+    )
+
+
+def test_runtime_bindings_bind_each_part_of_one_global_placement() -> None:
+    placement = _manifest()
+    bindings = (
+        _binding(placement, "worker-0", instance_id="source-0"),
+        _binding(placement, "worker-1", instance_id="source-1"),
+    )
+
+    assert validate_runtime_binding(placement, bindings[0]) is None
+    assert validate_runtime_bindings(placement, bindings) is None
+
+
+def test_runtime_binding_set_rejects_cross_participant_address_overlap() -> None:
+    placement = _manifest()
+    left = _binding(placement, "worker-0", instance_id="shared-instance")
+    right = _binding(placement, "worker-1", instance_id="shared-instance")
+    left_fragment = left.fragments[0]
+    right_fragment = replace(
+        right.fragments[0],
+        address=left_fragment.address,
+        worker_id=left_fragment.worker_id,
+        endpoint=left_fragment.endpoint,
+        device=left_fragment.device,
+        storage_address=left_fragment.storage_address,
+        storage_nbytes=left_fragment.storage_nbytes,
+        storage_offset_bytes=left_fragment.storage_offset_bytes,
+    )
+
+    with pytest.raises(ValueError, match="address ranges overlap"):
+        validate_runtime_bindings(
+            placement,
+            (left, replace(right, fragments=(right_fragment,))),
+        )
+
+
+def test_runtime_binding_set_rejects_cross_participant_fragment_id_duplicate() -> None:
+    placement = _manifest()
+    left = _binding(placement, "worker-0", instance_id="source-0")
+    right = _binding(placement, "worker-1", instance_id="source-1")
+    duplicate = replace(
+        right.fragments[0],
+        fragment_id=left.fragments[0].fragment_id,
+    )
+
+    with pytest.raises(
+        ValueError, match="duplicate runtime fragment_id across participants"
+    ):
+        validate_runtime_bindings(
+            placement,
+            (left, replace(right, fragments=(duplicate,))),
+        )
+
+
+def test_runtime_binding_set_requires_every_global_part_exactly_once() -> None:
+    placement = _manifest()
+    left = _binding(placement, "worker-0", instance_id="source-0")
+    right = _binding(placement, "worker-1", instance_id="source-1")
+
+    with pytest.raises(ValueError, match="missing runtime binding participant"):
+        validate_runtime_bindings(placement, (left,))
+    with pytest.raises(ValueError, match="duplicate runtime binding participant"):
+        validate_runtime_bindings(
+            placement,
+            (left, replace(right, participant_id="worker-0")),
+        )
+    with pytest.raises(ValueError, match="unknown runtime binding participant"):
+        validate_runtime_bindings(
+            placement,
+            (left, right, replace(right, participant_id="worker-unknown")),
+        )
+
+
+def test_runtime_binding_set_does_not_require_empty_participants() -> None:
+    topology = ParallelTopology(
+        tp_size=2,
+        pp_size=2,
+        ep_size=1,
+        dp_size=1,
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(tp=0, pp=0)),
+            TopologyParticipant("worker-1", ParallelRank(tp=1, pp=0)),
+            TopologyParticipant("worker-empty", ParallelRank(tp=0, pp=1)),
+        ),
+    )
+    placement = _manifest(
+        topology=topology,
+        parts=(
+            _part(
+                "worker-0",
+                ParallelRank(tp=0, pp=0),
+                0,
+                topology_id=topology.topology_id,
+            ),
+            _part(
+                "worker-1",
+                ParallelRank(tp=1, pp=0),
+                4,
+                topology_id=topology.topology_id,
+            ),
+            WeightPlacementPart(
+                resource_id=MODEL_ID,
+                revision=REVISION,
+                weight_generation=WEIGHT_GENERATION,
+                placement_set_id=PLACEMENT_SET_ID,
+                topology_id=topology.topology_id,
+                participant_id="worker-empty",
+                rank=ParallelRank(tp=0, pp=1),
+                tensors=(),
+                fragments=(),
+            ),
+        ),
+    )
+    bindings = (
+        _binding(placement, "worker-0", instance_id="source-0"),
+        _binding(placement, "worker-1", instance_id="source-1"),
+    )
+
+    assert weight_placement_from_json(weight_placement_to_json(placement)) == placement
+    assert validate_runtime_bindings(placement, bindings) is None
+
+
+def test_runtime_binding_can_only_bind_its_declared_part() -> None:
+    placement = _manifest()
+    left = _binding(placement, "worker-0", instance_id="source-0")
+    right_part = next(
+        item for item in placement.parts if item.participant_id == "worker-1"
+    )
+    wrong_fragment = replace(
+        left.fragments[0],
+        placement_fragment_id=right_part.fragments[0].placement_fragment_id,
+    )
+
+    with pytest.raises(ValueError, match="unknown placement fragment"):
+        validate_runtime_binding(
+            placement,
+            replace(left, fragments=(wrong_fragment,)),
+        )
diff --git a/mooncake-reshard/tests/weight_manifest/test_placement.py b/mooncake-reshard/tests/weight_manifest/test_placement.py
new file mode 100644
index 0000000000..82d55833c1
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_placement.py
@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import json
+import pytest
+
+from mooncake.reshard.weight import (
+    OwnershipAxis,
+    ParallelRank,
+    ReplicatedAxis,
+    SplitAxis,
+    weight_placement_from_json,
+    weight_placement_to_json,
+)
+
+from .helpers import (
+    descriptor,
+    parallel_topology,
+    placement_fragment,
+    placement_manifest,
+)
+
+
+def test_placement_round_trip_is_stable_and_address_free() -> None:
+    placement = placement_manifest()
+
+    encoded = weight_placement_to_json(placement)
+    decoded = weight_placement_from_json(encoded)
+
+    assert decoded == placement
+    assert decoded.digest == placement.digest
+    assert placement.placement_id == (
+        "sha256:618f22d9994d8d327a7afd97f3cfcf1f6680a337d71ea3a8162a7827ed0346db"
+    )
+    assert placement.digest == (
+        "a2ade0db5b17691e6a7c16d589d0498a64359eef91589addc870590899512d98"
+    )
+    assert encoded == weight_placement_to_json(placement)
+    for forbidden in (
+        "address",
+        "endpoint",
+        "worker_id",
+        "instance_id",
+        '"generation":',
+        "lease_id",
+        "owner",
+    ):
+        assert forbidden not in encoded
+
+
+def test_explicit_pipeline_stage_is_canonical_and_round_trips() -> None:
+    legacy = placement_manifest()
+    staged = placement_manifest(
+        fragments=(placement_fragment(pipeline_stage_id=3),),
+    )
+
+    encoded = weight_placement_to_json(staged)
+
+    assert '"pipeline_stage_id":3' in encoded
+    assert weight_placement_from_json(encoded) == staged
+    assert staged.placement_id != legacy.placement_id
+
+
+def test_placement_digest_is_independent_of_inventory_order() -> None:
+    tensors = (
+        descriptor(
+            tensor_id="b.weight",
+            shard_dims=(),
+            parallel_axes=(OwnershipAxis(kind="tp"),),
+            expert_id=None,
+        ),
+        descriptor(
+            tensor_id="a.weight",
+            shard_dims=(),
+            parallel_axes=(OwnershipAxis(kind="tp"),),
+            expert_id=None,
+        ),
+    )
+    fragments = (
+        placement_fragment(
+            placement_fragment_id="b",
+            tensor_id="b.weight",
+            rank=ParallelRank(tp=1),
+        ),
+        placement_fragment(
+            placement_fragment_id="a",
+            tensor_id="a.weight",
+            rank=ParallelRank(tp=0),
+        ),
+    )
+
+    first = placement_manifest(tensors=tensors, fragments=fragments)
+    second = placement_manifest(
+        tensors=tuple(reversed(tensors)),
+        fragments=tuple(reversed(fragments)),
+    )
+
+    assert first == second
+    assert weight_placement_to_json(first) == weight_placement_to_json(second)
+    assert first.digest == second.digest
+
+
+def test_weight_generation_changes_canonical_placement_identity() -> None:
+    generation_1 = placement_manifest(weight_generation=1)
+    generation_2 = placement_manifest(weight_generation=2)
+
+    assert generation_1.revision == generation_2.revision
+    assert generation_1.placement_id != generation_2.placement_id
+    assert generation_1.digest != generation_2.digest
+    assert (
+        weight_placement_from_json(
+            weight_placement_to_json(generation_2)
+        ).weight_generation
+        == 2
+    )
+
+
+def test_placement_uses_one_canonical_shard_representation() -> None:
+    placement = placement_manifest(tensors=(descriptor(shard_dims=(0,)),))
+
+    assert placement.tensors[0].shard_dims == (0,)
+    assert "partition_dim" not in weight_placement_to_json(placement)
+
+
+@pytest.mark.parametrize("mutation", ["missing", "unknown", "nan"])
+def test_placement_json_requires_strict_schema(mutation: str) -> None:
+    raw = json.loads(weight_placement_to_json(placement_manifest()))
+    if mutation == "missing":
+        del raw["revision"]
+    elif mutation == "unknown":
+        raw["future_semantics"] = "required"
+    else:
+        raw["resource_id"] = float("nan")
+
+    with pytest.raises(ValueError):
+        weight_placement_from_json(json.dumps(raw))
+
+
+@pytest.mark.parametrize(
+    ("path", "mutation"),
+    [
+        (("tensors", 0), ("pop", "dtype")),
+        (("tensors", 0), ("set", "future_semantics")),
+        (("topology",), ("pop", "tp_size")),
+        (("topology",), ("set", "future_semantics")),
+        (("topology", "participants", 0), ("pop", "participant_id")),
+        (("topology", "participants", 0), ("set", "future_semantics")),
+        (("topology", "participants", 0, "rank"), ("pop", "tp")),
+        (("tensors", 0, "parallel_axes", 0), ("pop", "kind")),
+        (
+            ("tensors", 0, "parallel_axes", 0),
+            ("set", "future_semantics"),
+        ),
+        (("parts", 0), ("pop", "participant_id")),
+        (("parts", 0), ("set", "future_semantics")),
+        (("parts", 0, "rank"), ("set", "future_semantics")),
+        (("parts", 0, "fragments", 0), ("pop", "nbytes")),
+        (("parts", 0, "fragments", 0), ("set", "future_semantics")),
+        (("parts", 0, "fragments", 0, "rank"), ("pop", "tp")),
+        (
+            ("parts", 0, "fragments", 0, "rank"),
+            ("set", "future_semantics"),
+        ),
+    ],
+)
+def test_placement_json_requires_strict_nested_schema(
+    path: tuple, mutation: tuple[str, str]
+) -> None:
+    raw = json.loads(weight_placement_to_json(placement_manifest()))
+    target = raw
+    for component in path:
+        target = target[component]
+    operation, field = mutation
+    if operation == "pop":
+        target.pop(field)
+    else:
+        target[field] = "unsupported"
+
+    with pytest.raises(ValueError, match="schema"):
+        weight_placement_from_json(json.dumps(raw))
+
+
+@pytest.mark.parametrize("value", ["not-json", "[]", '"placement"'])
+def test_placement_json_rejects_invalid_document(value: str) -> None:
+    with pytest.raises(ValueError):
+        weight_placement_from_json(value)
+
+
+def test_placement_json_rejects_duplicate_object_keys() -> None:
+    encoded = weight_placement_to_json(placement_manifest())
+    duplicated = encoded.replace(
+        '"resource_id":"model"',
+        '"resource_id":"model","resource_id":"other"',
+        1,
+    )
+
+    with pytest.raises(ValueError, match="duplicate JSON field"):
+        weight_placement_from_json(duplicated)
+
+
+def test_placement_json_rejects_unreferenced_tensor_descriptors() -> None:
+    raw = json.loads(weight_placement_to_json(placement_manifest()))
+    orphan = dict(raw["tensors"][0])
+    orphan["tensor_id"] = "orphan.weight"
+    raw["tensors"].append(orphan)
+
+    with pytest.raises(ValueError, match="unreferenced tensor"):
+        weight_placement_from_json(json.dumps(raw))
+
+
+@pytest.mark.parametrize("aliases", ["alias", {"alias": 1}, ["alias", "alias"]])
+def test_placement_json_rejects_invalid_aliases(aliases) -> None:
+    raw = json.loads(weight_placement_to_json(placement_manifest()))
+    raw["parts"][0]["fragments"][0]["aliases"] = aliases
+
+    with pytest.raises(ValueError, match="aliases"):
+        weight_placement_from_json(json.dumps(raw))
+
+
+@pytest.mark.parametrize(
+    ("path", "value"),
+    [
+        (("tensors",), {}),
+        (("topology", "participants"), {}),
+        (("parts",), 1),
+        (("parts", 0, "fragments"), 1),
+        (("tensors", 0, "global_shape"), 8),
+        (("tensors", 0, "shard_dims"), "0"),
+        (("tensors", 0, "parallel_axes"), {}),
+        (("parts", 0, "fragments", 0, "global_offset"), 0),
+        (("parts", 0, "fragments", 0, "local_shape"), None),
+        (("parts", 0, "fragments", 0, "rank"), []),
+    ],
+)
+def test_placement_json_rejects_wrong_container_types(
+    path: tuple, value: object
+) -> None:
+    raw = json.loads(weight_placement_to_json(placement_manifest()))
+    target = raw
+    for component in path[:-1]:
+        target = target[component]
+    target[path[-1]] = value
+
+    with pytest.raises(ValueError):
+        weight_placement_from_json(json.dumps(raw))
+
+
+def test_placement_id_must_match_canonical_logical_content() -> None:
+    with pytest.raises(ValueError, match="canonical logical content"):
+        placement_manifest(placement_id="opaque-placement-id")
+
+
+def test_parallel_axis_semantics_participate_in_placement_identity() -> None:
+    tp = placement_manifest(
+        tensors=(
+            descriptor(
+                expert_id=None,
+                parallel_axes=(SplitAxis(kind="tp", dim=0),),
+            ),
+        ),
+    )
+    ep = placement_manifest(
+        tensors=(
+            descriptor(
+                expert_id=None,
+                parallel_axes=(SplitAxis(kind="ep", dim=0),),
+            ),
+        ),
+    )
+
+    assert tp.placement_id != ep.placement_id
+    assert tp.digest != ep.digest
+
+
+def test_declared_parallel_axis_sizes_participate_in_placement_identity() -> None:
+    tensor = descriptor(
+        shard_dims=(),
+        parallel_axes=(ReplicatedAxis(kind="tp"),),
+        expert_id=None,
+    )
+    base = placement_manifest(tensors=(tensor,))
+    expanded_topology = parallel_topology(tp_size=2)
+    expanded = placement_manifest(topology=expanded_topology, tensors=(tensor,))
+
+    assert base.topology.participants == expanded.topology.participants
+    assert base.placement_id != expanded.placement_id
+    assert base.digest != expanded.digest
+
+
+def test_axis_semantic_kind_participates_in_placement_identity() -> None:
+    replicated = placement_manifest(
+        tensors=(
+            descriptor(
+                shard_dims=(),
+                expert_id=None,
+                parallel_axes=(ReplicatedAxis(kind="tp"),),
+            ),
+        ),
+    )
+    ownership = placement_manifest(
+        tensors=(
+            descriptor(
+                shard_dims=(),
+                expert_id=None,
+                parallel_axes=(OwnershipAxis(kind="tp"),),
+            ),
+        ),
+    )
+
+    assert replicated.placement_id != ownership.placement_id
+    assert replicated.digest != ownership.digest
diff --git a/mooncake-reshard/tests/weight_manifest/test_storage.py b/mooncake-reshard/tests/weight_manifest/test_storage.py
new file mode 100644
index 0000000000..63dfeb28f2
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_storage.py
@@ -0,0 +1,497 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from mooncake.reshard.weight.manifest import (
+    ParallelRank,
+    RuntimeBindingFragment,
+    TensorDescriptor,
+    OwnershipAxis,
+    SplitAxis,
+)
+from mooncake.reshard.weight.storage_manifest import (
+    StoredFragmentSnapshot,
+    StoredWeightManifest,
+)
+
+
+def tensor_descriptor(**overrides) -> TensorDescriptor:
+    values = {
+        "tensor_id": "layers.2.experts.3.w1",
+        "global_shape": (8, 4),
+        "dtype": "bfloat16",
+        "itemsize": 2,
+        "shard_dims": (0,),
+        "layer_id": 2,
+        "expert_id": 3,
+        "layout_fingerprint": "sglang:qwen3.5:bf16:v1",
+        "parallel_axes": (SplitAxis(kind="tp", dim=0),),
+    }
+    values.update(overrides)
+    return TensorDescriptor(**values)
+
+
+def runtime_binding_fragment(**overrides) -> RuntimeBindingFragment:
+    values = {
+        "placement_fragment_id": "placement-0",
+        "fragment_id": "runtime-0",
+        "address": 0x1000,
+        "nbytes": 32,
+        "worker_id": "source-0",
+        "endpoint": "source-0:12345",
+        "device": "cuda:0",
+        "itemsize": 2,
+        "local_shape": (4, 4),
+        "strides_bytes": (8, 2),
+        "storage_address": 0x1000,
+        "storage_nbytes": 32,
+        "storage_offset_bytes": 0,
+    }
+    if "address" in overrides and "storage_address" not in overrides:
+        values["storage_address"] = overrides["address"]
+    if "nbytes" in overrides and "storage_nbytes" not in overrides:
+        values["storage_nbytes"] = overrides["nbytes"]
+    values.update(overrides)
+    return RuntimeBindingFragment(**values)
+
+
+def stored_fragment(**overrides) -> StoredFragmentSnapshot:
+    values = {
+        "fragment_id": "stored-0",
+        "tensor_id": "layers.2.experts.3.w1",
+        "global_offset": (0, 0),
+        "local_shape": (8, 4),
+        "object_key": "weights/default/qwen/rev/payload/0",
+        "object_offset": 0,
+        "nbytes": 64,
+    }
+    values.update(overrides)
+    return StoredFragmentSnapshot(**values)
+
+
+def test_weight_manifest_round_trip_is_stable_and_has_no_runtime_address() -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen3.5-0.8b",
+        revision="step-42",
+        weight_generation=42,
+        group_id="weights/default/qwen3.5-0.8b/step-42",
+        manifest_key="weights/default/qwen3.5-0.8b/step-42/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(
+            stored_fragment(
+                object_key=("weights/default/qwen3.5-0.8b/step-42/payload/0")
+            ),
+        ),
+        created_at="2026-07-17T00:00:00Z",
+    )
+
+    encoded = manifest.to_json()
+
+    assert StoredWeightManifest.from_json(encoded) == manifest
+    assert encoded == manifest.to_json()
+    assert "4096" not in encoded
+    assert "address" not in json.loads(encoded)["fragments"][0]
+
+
+def test_weight_manifest_round_trip_preserves_shard_dims() -> None:
+    tensor = tensor_descriptor(
+        tensor_id="layers.2.experts.w1",
+        global_shape=(2, 8, 4),
+        shard_dims=(0, 1),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+    group_id = "weights/default/qwen/rev"
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        tensors=(tensor,),
+        fragments=tuple(
+            StoredFragmentSnapshot(
+                fragment_id=f"stored-e{expert}-o{out_shard}",
+                tensor_id=tensor.tensor_id,
+                global_offset=(expert, out_shard * 4, 0),
+                local_shape=(1, 4, 4),
+                object_key=f"{group_id}/payload/e{expert}-o{out_shard}",
+                object_offset=0,
+                nbytes=32,
+            )
+            for expert in range(2)
+            for out_shard in range(2)
+        ),
+        created_at="2026-07-22T00:00:00Z",
+    )
+
+    encoded = manifest.to_json()
+    decoded = StoredWeightManifest.from_json(encoded)
+
+    assert decoded == manifest
+    assert json.loads(encoded)["tensors"][0]["shard_dims"] == [0, 1]
+
+
+def test_weight_manifest_round_trip_preserves_single_and_multi_axis_shards() -> None:
+    single_axis = tensor_descriptor(tensor_id="layers.0.attn.qkv", expert_id=None)
+    multi_axis_tensor = tensor_descriptor(
+        tensor_id="layers.2.experts.w1",
+        global_shape=(2, 8, 4),
+        shard_dims=(0, 1),
+        expert_id=None,
+        parallel_axes=(
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    )
+    group_id = "weights/default/qwen/rev"
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        tensors=(single_axis, multi_axis_tensor),
+        fragments=(
+            StoredFragmentSnapshot(
+                fragment_id="single-axis",
+                tensor_id=single_axis.tensor_id,
+                global_offset=(0, 0),
+                local_shape=single_axis.global_shape,
+                object_key=f"{group_id}/payload/single-axis",
+                object_offset=0,
+                nbytes=64,
+            ),
+            *(
+                StoredFragmentSnapshot(
+                    fragment_id=f"multi-e{expert}-o{out_shard}",
+                    tensor_id=multi_axis_tensor.tensor_id,
+                    global_offset=(expert, out_shard * 4, 0),
+                    local_shape=(1, 4, 4),
+                    object_key=(f"{group_id}/payload/multi-e{expert}-o{out_shard}"),
+                    object_offset=0,
+                    nbytes=32,
+                )
+                for expert in range(2)
+                for out_shard in range(2)
+            ),
+        ),
+        created_at="2026-07-22T00:00:00Z",
+    )
+
+    encoded = manifest.to_json()
+    decoded = StoredWeightManifest.from_json(encoded)
+
+    assert decoded == manifest
+    raw_single_axis = next(
+        tensor
+        for tensor in json.loads(encoded)["tensors"]
+        if tensor["tensor_id"] == single_axis.tensor_id
+    )
+    assert raw_single_axis["shard_dims"] == [0]
+
+
+def test_weight_manifest_round_trip_preserves_parallel_axes() -> None:
+    tensor = tensor_descriptor(
+        parallel_axes=(
+            OwnershipAxis(kind="pp"),
+            SplitAxis(kind="tp", dim=0),
+        ),
+    )
+    group_id = "weights/default/qwen/rev"
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id=group_id,
+        manifest_key=f"{group_id}/manifest",
+        tensors=(tensor,),
+        fragments=(stored_fragment(object_key=f"{group_id}/payload/0"),),
+        created_at="2026-07-22T00:00:00Z",
+    )
+
+    encoded = manifest.to_json()
+
+    assert StoredWeightManifest.from_json(encoded) == manifest
+    assert json.loads(encoded)["tensors"][0]["parallel_axes"] == [
+        {"kind": "pp", "semantics": "ownership"},
+        {"kind": "tp", "semantics": "split", "dim": 0},
+    ]
+
+
+def test_weight_manifest_json_emits_single_axis_shard_dims_field() -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id="weights/default/qwen/rev",
+        manifest_key="weights/default/qwen/rev/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(stored_fragment(),),
+        created_at="2026-07-17T00:00:00Z",
+    )
+
+    raw = json.loads(manifest.to_json())
+
+    assert raw["tensors"][0]["shard_dims"] == [0]
+
+
+@pytest.mark.parametrize(
+    "fragment",
+    [
+        stored_fragment(tensor_id="missing"),
+        stored_fragment(global_offset=(6, 0), local_shape=(4, 4)),
+        stored_fragment(nbytes=31),
+    ],
+)
+def test_weight_manifest_rejects_invalid_fragment(
+    fragment: StoredFragmentSnapshot,
+) -> None:
+    with pytest.raises(ValueError):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key="weights/default/qwen/rev/manifest",
+            tensors=(tensor_descriptor(),),
+            fragments=(fragment,),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+def test_weight_manifest_rejects_missing_tensor_coverage() -> None:
+    with pytest.raises(ValueError, match="not fully covered"):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key="weights/default/qwen/rev/manifest",
+            tensors=(tensor_descriptor(),),
+            fragments=(stored_fragment(local_shape=(4, 4), nbytes=32),),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+def test_weight_manifest_rejects_duplicate_fragment_geometry() -> None:
+    with pytest.raises(ValueError, match="duplicate fragment geometry"):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key="weights/default/qwen/rev/manifest",
+            tensors=(tensor_descriptor(),),
+            fragments=(
+                stored_fragment(),
+                stored_fragment(
+                    fragment_id="stored-1",
+                    object_key="weights/default/qwen/rev/payload/1",
+                ),
+            ),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+@pytest.mark.parametrize("second_offset", [0, 16])
+def test_weight_manifest_rejects_overlapping_object_ranges(
+    second_offset: int,
+) -> None:
+    with pytest.raises(ValueError, match="object ranges overlap"):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key="weights/default/qwen/rev/manifest",
+            tensors=(tensor_descriptor(),),
+            fragments=(
+                stored_fragment(local_shape=(4, 4), nbytes=32),
+                stored_fragment(
+                    fragment_id="stored-1",
+                    global_offset=(4, 0),
+                    local_shape=(4, 4),
+                    object_offset=second_offset,
+                    nbytes=32,
+                ),
+            ),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+def test_weight_manifest_allows_adjacent_object_ranges() -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id="weights/default/qwen/rev",
+        manifest_key="weights/default/qwen/rev/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(
+            stored_fragment(local_shape=(4, 4), nbytes=32),
+            stored_fragment(
+                fragment_id="stored-1",
+                global_offset=(4, 0),
+                local_shape=(4, 4),
+                object_offset=32,
+                nbytes=32,
+            ),
+        ),
+        created_at="2026-07-17T00:00:00Z",
+    )
+
+    assert tuple(fragment.object_offset for fragment in manifest.fragments) == (0, 32)
+
+
+def test_weight_manifest_allows_same_offset_for_different_objects() -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id="weights/default/qwen/rev",
+        manifest_key="weights/default/qwen/rev/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(
+            stored_fragment(local_shape=(4, 4), nbytes=32),
+            stored_fragment(
+                fragment_id="stored-1",
+                global_offset=(4, 0),
+                local_shape=(4, 4),
+                object_key="weights/default/qwen/rev/payload/1",
+                nbytes=32,
+            ),
+        ),
+        created_at="2026-07-17T00:00:00Z",
+    )
+
+    assert tuple(fragment.object_offset for fragment in manifest.fragments) == (0, 0)
+
+
+def test_manifest_types_cannot_cross_the_runtime_storage_boundary() -> None:
+    with pytest.raises(ValueError, match="StoredWeightManifest fragments"):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key="weights/default/qwen/rev/manifest",
+            tensors=(tensor_descriptor(),),
+            fragments=(runtime_binding_fragment(),),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+@pytest.mark.parametrize(
+    "factory",
+    [
+        lambda: ParallelRank(dp=True),
+        lambda: tensor_descriptor(global_shape=(8.0, 4)),
+        lambda: tensor_descriptor(itemsize=2.0),
+        lambda: tensor_descriptor(shard_dims=(0.0,)),
+        lambda: runtime_binding_fragment(address=4096.0),
+        lambda: runtime_binding_fragment(nbytes=False),
+        lambda: stored_fragment(object_offset=0.0),
+        lambda: stored_fragment(nbytes=64.0),
+    ],
+)
+def test_manifest_schema_rejects_non_integer_numeric_fields(factory) -> None:
+    with pytest.raises(ValueError, match="integer"):
+        factory()
+
+
+def test_weight_manifest_json_rejects_non_finite_and_non_mapping_values() -> None:
+    with pytest.raises(ValueError, match="non-finite"):
+        StoredWeightManifest.from_json('{"model_id":NaN}')
+
+    with pytest.raises(ValueError, match="JSON object"):
+        StoredWeightManifest.from_json("[]")
+
+
+def test_weight_manifest_json_rejects_float_geometry() -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id="weights/default/qwen/rev",
+        manifest_key="weights/default/qwen/rev/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(stored_fragment(),),
+        created_at="2026-07-17T00:00:00Z",
+    )
+    raw = json.loads(manifest.to_json())
+    raw["tensors"][0]["global_shape"][0] = 8.0
+
+    with pytest.raises(ValueError, match="integer"):
+        StoredWeightManifest.from_json(json.dumps(raw))
+
+
+@pytest.mark.parametrize(
+    "manifest_key, object_key",
+    [
+        (
+            "weights/default/other/rev/manifest",
+            "weights/default/qwen/rev/payload/0",
+        ),
+        (
+            "weights/default/qwen/rev/manifest",
+            "weights/default/other/rev/payload/0",
+        ),
+    ],
+)
+def test_weight_manifest_binds_manifest_and_payload_keys_to_group(
+    manifest_key: str, object_key: str
+) -> None:
+    with pytest.raises(ValueError, match="group"):
+        StoredWeightManifest(
+            namespace="default",
+            resource_id="qwen",
+            revision="rev",
+            weight_generation=7,
+            group_id="weights/default/qwen/rev",
+            manifest_key=manifest_key,
+            tensors=(tensor_descriptor(),),
+            fragments=(stored_fragment(object_key=object_key),),
+            created_at="2026-07-17T00:00:00Z",
+        )
+
+
+@pytest.mark.parametrize("mutation", ["missing-field", "unknown-field"])
+def test_weight_manifest_json_requires_exact_top_level_schema(mutation: str) -> None:
+    manifest = StoredWeightManifest(
+        namespace="default",
+        resource_id="qwen",
+        revision="rev",
+        weight_generation=7,
+        group_id="weights/default/qwen/rev",
+        manifest_key="weights/default/qwen/rev/manifest",
+        tensors=(tensor_descriptor(),),
+        fragments=(stored_fragment(),),
+        created_at="2026-07-17T00:00:00Z",
+    )
+    raw = json.loads(manifest.to_json())
+    if mutation == "missing-field":
+        del raw["revision"]
+    else:
+        raw["future_semantics"] = "required"
+
+    with pytest.raises(ValueError, match="schema"):
+        StoredWeightManifest.from_json(json.dumps(raw))
diff --git a/mooncake-reshard/tests/weight_manifest/test_validation.py b/mooncake-reshard/tests/weight_manifest/test_validation.py
new file mode 100644
index 0000000000..47a577537c
--- /dev/null
+++ b/mooncake-reshard/tests/weight_manifest/test_validation.py
@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import pytest
+
+from mooncake.reshard.weight import (
+    ParallelRank,
+    ReplicatedAxis,
+    SplitAxis,
+    TopologyParticipant,
+)
+
+from .helpers import (
+    binding_fragment,
+    binding_manifest,
+    descriptor,
+    parallel_topology,
+    placement_fragment,
+    placement_manifest,
+    placement_part,
+)
+
+
+@pytest.mark.parametrize(
+    "factory",
+    [
+        lambda: ParallelRank(dp=True),
+        lambda: binding_fragment(address=4096.0),
+        lambda: binding_fragment(nbytes=32.0),
+        lambda: binding_manifest(generation=True),
+    ],
+)
+def test_contract_rejects_bool_and_float_integer_fields(factory) -> None:
+    with pytest.raises(ValueError, match="integer"):
+        factory()
+
+
+@pytest.mark.parametrize(
+    ("factory", "message"),
+    [
+        (lambda: placement_manifest(tensors=(object(),)), "tensors"),
+        (lambda: placement_manifest(fragments=(object(),)), "fragments"),
+        (lambda: binding_manifest(fragments=(object(),)), "fragments"),
+    ],
+)
+def test_manifest_collections_reject_wrong_element_types(factory, message: str) -> None:
+    with pytest.raises(ValueError, match=message):
+        factory()
+
+
+@pytest.mark.parametrize(
+    ("factory", "message"),
+    [
+        (lambda: placement_manifest(tensors=None), "tensors"),
+        (lambda: placement_manifest(fragments=None), "fragments"),
+        (lambda: binding_manifest(fragments=None), "fragments"),
+    ],
+)
+def test_manifest_collections_reject_wrong_container_types(
+    factory, message: str
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        factory()
+
+
+@pytest.mark.parametrize(
+    "factory",
+    [
+        lambda: binding_fragment(address=2**64),
+        lambda: binding_fragment(address=2**64 - 16, nbytes=32),
+        lambda: binding_fragment(nbytes=2**64),
+        lambda: binding_manifest(generation=2**64),
+    ],
+)
+def test_physical_contract_rejects_values_outside_u64_abi(factory) -> None:
+    with pytest.raises(ValueError, match="64-bit"):
+        factory()
+
+
+def test_physical_contract_rejects_unrepresentable_exclusive_end() -> None:
+    with pytest.raises(ValueError, match="64-bit"):
+        binding_fragment(address=2**64 - 4, nbytes=4)
+
+
+def _n_dim_descriptor(**overrides):
+    values = {
+        "global_shape": (8, 8),
+        "shard_dims": (0, 1),
+        "expert_id": None,
+        "parallel_axes": (
+            SplitAxis(kind="ep", dim=0),
+            SplitAxis(kind="tp", dim=1),
+        ),
+    }
+    values.update(overrides)
+    return descriptor(**values)
+
+
+def test_logical_validation_rejects_same_owner_n_dim_overlap() -> None:
+    tensor = _n_dim_descriptor()
+
+    with pytest.raises(ValueError, match="logical fragment boxes overlap"):
+        placement_part(
+            tensors=(tensor,),
+            fragments=(
+                placement_fragment(
+                    placement_fragment_id="left",
+                    local_shape=(6, 8),
+                    nbytes=96,
+                ),
+                placement_fragment(
+                    placement_fragment_id="right",
+                    global_offset=(4, 0),
+                    local_shape=(4, 8),
+                    nbytes=64,
+                ),
+            ),
+        )
+
+
+def test_logical_validation_accepts_adjacent_n_dim_boxes() -> None:
+    tensor = _n_dim_descriptor()
+    fragments = tuple(
+        placement_fragment(
+            placement_fragment_id=f"box-{row}-{column}",
+            global_offset=(row, column),
+            local_shape=(4, 4),
+            nbytes=32,
+        )
+        for row in (0, 4)
+        for column in (0, 4)
+    )
+
+    placement = placement_manifest(tensors=(tensor,), fragments=fragments)
+
+    assert len(placement.fragments) == 4
+
+
+def test_complete_placement_validation_is_python_39_compatible() -> None:
+    placement = placement_manifest()
+
+    assert placement.fragments
+
+
+@pytest.mark.parametrize(
+    ("tensor", "fragment", "message"),
+    [
+        (
+            _n_dim_descriptor(),
+            placement_fragment(
+                global_offset=(7, 0),
+                local_shape=(2, 8),
+                nbytes=32,
+            ),
+            "out of bounds",
+        ),
+        (
+            descriptor(),
+            placement_fragment(nbytes=31),
+            "byte size mismatch",
+        ),
+    ],
+)
+def test_logical_validation_rejects_invalid_fragment_geometry(
+    tensor, fragment, message: str
+) -> None:
+    with pytest.raises(ValueError, match=message):
+        placement_part(tensors=(tensor,), fragments=(fragment,))
+
+
+def test_replicated_tensor_accepts_multiple_physical_fragments() -> None:
+    tensor = descriptor(
+        global_shape=(2, 4),
+        shard_dims=(),
+        expert_id=None,
+        parallel_axes=(ReplicatedAxis(kind="tp"),),
+    )
+    fragments = (
+        placement_fragment(
+            placement_fragment_id="row-0",
+            global_offset=(0, 0),
+            local_shape=(1, 4),
+            nbytes=8,
+        ),
+        placement_fragment(
+            placement_fragment_id="row-1",
+            global_offset=(1, 0),
+            local_shape=(1, 4),
+            nbytes=8,
+        ),
+    )
+
+    placement = placement_manifest(tensors=(tensor,), fragments=fragments)
+
+    assert placement.fragments == fragments
+
+
+def test_split_tensor_accepts_storage_segmentation_on_non_split_axis() -> None:
+    tensor = descriptor(global_shape=(4, 4))
+    topology = parallel_topology(
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(tp=0)),
+            TopologyParticipant("worker-1", ParallelRank(tp=1)),
+        ),
+    )
+    fragments = tuple(
+        placement_fragment(
+            placement_fragment_id=f"tp-{tp_rank}-column-{column}",
+            global_offset=(tp_rank * 2, column),
+            local_shape=(2, 2),
+            nbytes=8,
+            rank=ParallelRank(tp=tp_rank),
+        )
+        for tp_rank in range(2)
+        for column in (0, 2)
+    )
+
+    placement = placement_manifest(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=fragments,
+    )
+
+    assert placement.fragments == fragments
+
+
+def test_global_placement_rejects_split_axis_cross_rank_overlap() -> None:
+    tensor = descriptor(global_shape=(8, 4))
+    topology = parallel_topology(
+        participants=(
+            TopologyParticipant("worker-0", ParallelRank(tp=0)),
+            TopologyParticipant("worker-1", ParallelRank(tp=1)),
+        ),
+    )
+    fragments = (
+        placement_fragment(
+            placement_fragment_id="rank-0",
+            local_shape=(8, 4),
+            nbytes=64,
+            rank=ParallelRank(tp=0),
+        ),
+        placement_fragment(
+            placement_fragment_id="rank-1",
+            local_shape=(8, 4),
+            nbytes=64,
+            rank=ParallelRank(tp=1),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(
+            topology=topology,
+            tensors=(tensor,),
+            fragments=fragments,
+        )
+
+
+def test_partial_part_is_allowed_but_global_placement_is_rejected() -> None:
+    topology = parallel_topology()
+    tensor = descriptor(global_shape=(8, 4))
+    part = placement_part(
+        topology=topology,
+        tensors=(tensor,),
+        fragments=(
+            placement_fragment(
+                local_shape=(4, 4),
+                nbytes=32,
+            ),
+        ),
+    )
+
+    assert part.fragments[0].local_shape == (4, 4)
+    with pytest.raises(ValueError, match="not fully covered"):
+        placement_manifest(topology=topology, parts=(part,))
diff --git a/mooncake-reshard/typecheck/negative/invalid_contract_usage.py b/mooncake-reshard/typecheck/negative/invalid_contract_usage.py
new file mode 100644
index 0000000000..a9640175ca
--- /dev/null
+++ b/mooncake-reshard/typecheck/negative/invalid_contract_usage.py
@@ -0,0 +1,13 @@
+"""Negative static checks for canonical reshard contract categories.
+
+This file is intentionally invalid. The type-check script requires pyright to
+reject it after the production contract has passed strict checking.
+"""
+
+from mooncake.reshard.contracts import ParticipantId, PlacementId
+from mooncake.reshard.weight.types import SplitAxis
+
+
+participant_id = ParticipantId("participant-0")
+placement_id: PlacementId = participant_id
+SplitAxis(kind="pp", dim=0)
diff --git a/mooncake-reshard/typecheck/negative/pyrightconfig.json b/mooncake-reshard/typecheck/negative/pyrightconfig.json
new file mode 100644
index 0000000000..f3c7a4df7d
--- /dev/null
+++ b/mooncake-reshard/typecheck/negative/pyrightconfig.json
@@ -0,0 +1,6 @@
+{
+  "include": ["invalid_contract_usage.py"],
+  "extraPaths": ["../../python"],
+  "pythonVersion": "3.10",
+  "typeCheckingMode": "strict"
+}
diff --git a/mooncake-store/AGENTS.md b/mooncake-store/AGENTS.md
index 7e2480637e..2bf0ba0444 100644
--- a/mooncake-store/AGENTS.md
+++ b/mooncake-store/AGENTS.md
@@ -11,3 +11,12 @@
 - Do not migrate `src/cachelib_memory_allocator/` unless explicitly requested.
 - The shared engine is not cryptographically secure; do not use it for secrets
   or authentication tokens.
+
+## Local-first Host Identity
+
+- Keep the placement host ID separate from the routable transfer endpoint.
+- `MOONCAKE_HOST_ID` takes priority after ASCII whitespace trimming. Unset,
+  empty, or whitespace-only values fall back to the existing `local_hostname`
+  behavior.
+- Normalize endpoint-shaped host IDs before rejecting loopback or wildcard
+  identities.
diff --git a/mooncake-store/CMakeLists.txt b/mooncake-store/CMakeLists.txt
index c913e5d731..37dd2f9190 100644
--- a/mooncake-store/CMakeLists.txt
+++ b/mooncake-store/CMakeLists.txt
@@ -1,7 +1,6 @@
 project(MooncakeStore VERSION 2.0.0)
 
-option(ENABLE_KV_EVENTS
-       "Build master KV events ZMQ publisher (requires libzmq when ON)" OFF)
+set(MOONCAKE_STORE_INCLUDE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/include")
 
 # Extract version components for C++ usage
 set(MOONCAKE_STORE_VERSION ${PROJECT_VERSION})
@@ -46,28 +45,20 @@ if (STORE_USE_K8S_LEASE)
     set(K8S_LEASE_WRAPPER_LIB ${CMAKE_CURRENT_BINARY_DIR}/../mooncake-common/k8s-lease/libk8s_lease_wrapper.so)
 endif()
 
-if (STORE_USE_REDIS)
-    find_path(MOONCAKE_STORE_HIREDIS_INCLUDE_DIR hiredis/hiredis.h REQUIRED)
-    find_library(MOONCAKE_STORE_HIREDIS_LIBRARY hiredis REQUIRED)
-    message(STATUS "Redis HA backend: Enabled")
+if(TARGET Mooncake::liburing)
+  message(STATUS "io_uring: Enabled for mooncake_store")
+else()
+  message(STATUS "io_uring: Disabled (liburing not found)")
+endif()
+
+if(STORE_USE_REDIS)
+  message(STATUS "Redis HA backend: Enabled")
 endif()
 
 if (NOT STORE_USE_ETCD AND NOT STORE_USE_REDIS AND NOT STORE_USE_K8S_LEASE)
     message(STATUS "Store HA backends are disabled")
 endif()
 
-# Add include directories
-include_directories(
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/cachelib_memory_allocator/include
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/cachelib_memory_allocator/fake_include
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/cachelib_memory_allocator/
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/mooncake-store/proto/
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/
-    ${CMAKE_CURRENT_BINARY_DIR}/include/
-    ${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-transfer-engine/include
-    ${ETCD_WRAPPER_INCLUDE}
-)
-
 # Add subdirectories
 add_subdirectory(src)
 
@@ -75,6 +66,20 @@ if (STORE_USE_ETCD)
     add_subdirectory(tools)
 endif()
 
+# Test-only private access support, also used by the eviction benchmark. Never
+# link this library into the production master service.
+if(BUILD_UNIT_TESTS OR BUILD_BENCHMARK)
+  add_library(master_service_test_peer STATIC
+              tests/master_service/master_service_test_peer.cpp)
+  target_include_directories(master_service_test_peer
+                             PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+  target_link_libraries(master_service_test_peer PUBLIC mooncake_store)
+  if(USE_NOF)
+    target_include_directories(master_service_test_peer
+                               PRIVATE ${SPDK_INCLUDE_DIR} ${DPDK_INCLUDE_DIR})
+  endif()
+endif()
+
 if (BUILD_UNIT_TESTS)
     add_subdirectory(tests)
 endif()
diff --git a/mooncake-store/benchmarks/CMakeLists.txt b/mooncake-store/benchmarks/CMakeLists.txt
index c1e5e2b810..7b947d9a9b 100644
--- a/mooncake-store/benchmarks/CMakeLists.txt
+++ b/mooncake-store/benchmarks/CMakeLists.txt
@@ -49,12 +49,19 @@ endif()
 # Add BatchEvict benchmark executable
 add_executable(batch_evict_bench batch_evict_bench.cpp)
 target_link_libraries(
-  batch_evict_bench PRIVATE mooncake_store cachelib_memory_allocator
+  batch_evict_bench PRIVATE master_service_test_peer cachelib_memory_allocator
                             gflags::gflags glog::glog pthread)
 
+add_executable(batch_oplog_promotion_bench batch_oplog_promotion_bench.cpp)
+target_link_libraries(batch_oplog_promotion_bench PRIVATE mooncake_store
+                                                          gflags::gflags)
+
 if(STORE_USE_ETCD)
   add_executable(oplog_batch_bench oplog_batch_bench.cpp)
   target_link_libraries(
     oplog_batch_bench PRIVATE mooncake_store glog::glog gflags::gflags
                               JsonCpp::JsonCpp)
 endif()
+
+add_executable(uring_batch_read_bench uring_batch_read_bench.cpp)
+target_link_libraries(uring_batch_read_bench PRIVATE mooncake_store)
diff --git a/mooncake-store/benchmarks/allocation_strategy_bench.cpp b/mooncake-store/benchmarks/allocation_strategy_bench.cpp
index adf8facb6f..c7d24e6a28 100644
--- a/mooncake-store/benchmarks/allocation_strategy_bench.cpp
+++ b/mooncake-store/benchmarks/allocation_strategy_bench.cpp
@@ -18,6 +18,7 @@
 #include "offset_allocator/offset_allocator.h"
 #include "allocator.h"
 #include "allocation_strategy.h"
+#include "local_ssd/manager.h"
 
 // --- gflags definitions ---
 DEFINE_int64(segment_capacity, 1024,
@@ -381,7 +382,8 @@ static double computeAverageUtilAll(const AllocatorManager& manager) {
     for (const auto& name : names) {
         const auto* allocators = manager.getAllocators(name);
         if (!allocators || allocators->empty()) continue;
-        for (const auto& alloc : *allocators) {
+        for (const auto& registration : *allocators) {
+            const auto alloc = registration->GetAllocator();
             double cap = static_cast<double>(alloc->capacity());
             if (cap == 0) continue;
             sum += static_cast<double>(alloc->size()) / cap;
@@ -396,8 +398,8 @@ static size_t computeTotalCapacity(const AllocatorManager& manager) {
     for (const auto& name : manager.getNames()) {
         const auto* allocs = manager.getAllocators(name);
         if (!allocs) continue;
-        for (const auto& alloc : *allocs) {
-            total += alloc->capacity();
+        for (const auto& registration : *allocs) {
+            total += registration->GetAllocator()->capacity();
         }
     }
     return total;
@@ -416,7 +418,8 @@ static double computeUtilizationStdDev(const AllocatorManager& manager) {
     for (const auto& name : names) {
         const auto* allocators = manager.getAllocators(name);
         if (!allocators || allocators->empty()) continue;
-        for (const auto& alloc : *allocators) {
+        for (const auto& registration : *allocators) {
+            const auto alloc = registration->GetAllocator();
             double cap = static_cast<double>(alloc->capacity());
             if (cap == 0) continue;
             double used = static_cast<double>(alloc->size());
@@ -507,9 +510,10 @@ static FragmentationSnapshot computeFragmentationSnapshot(
         const auto* allocs = manager.getAllocators(name);
         if (!allocs) continue;
 
-        for (const auto& alloc : *allocs) {
+        for (const auto& registration : *allocs) {
             auto offset_alloc =
-                std::dynamic_pointer_cast<OffsetBufferAllocator>(alloc);
+                std::dynamic_pointer_cast<OffsetBufferAllocator>(
+                    registration->GetAllocator());
             if (!offset_alloc) continue;
 
             auto allocator = offset_alloc->getOffsetAllocator();
@@ -669,7 +673,8 @@ static void computeLatencyStats(std::vector<double>& latencies, double total_us,
 static FillUpResult runFillUpBenchmark(const BenchConfig& cfg) {
     AllocatorManager manager =
         createCluster(cfg.num_segments, cfg.segment_capacity, cfg.skewed);
-    auto strategy = CreateAllocationStrategy(cfg.strategy_type);
+    LocalSsdManager local_ssd;
+    auto strategy = CreateAllocationStrategy(cfg.strategy_type, local_ssd);
 
     std::vector<double> latencies;
     latencies.reserve(cfg.num_allocations);
@@ -788,7 +793,8 @@ static FillUpResult runFillUpBenchmark(const BenchConfig& cfg) {
 static ScaleOutResult runScaleOutBenchmark(const BenchConfig& cfg) {
     AllocatorManager manager =
         createCluster(cfg.num_segments, cfg.segment_capacity, cfg.skewed);
-    auto strategy = CreateAllocationStrategy(cfg.strategy_type);
+    LocalSsdManager local_ssd;
+    auto strategy = CreateAllocationStrategy(cfg.strategy_type, local_ssd);
 
     const double convergence_threshold = FLAGS_convergence_threshold;
 
@@ -1113,7 +1119,8 @@ static SizeClassPrefillStats prefillSizeClassChurn(
 static FillUpResult runDsaBenchmark(const BenchConfig& cfg) {
     AllocatorManager manager =
         createCluster(cfg.num_segments, cfg.segment_capacity, cfg.skewed);
-    auto strategy = CreateAllocationStrategy(cfg.strategy_type);
+    LocalSsdManager local_ssd;
+    auto strategy = CreateAllocationStrategy(cfg.strategy_type, local_ssd);
 
     const size_t total_capacity = computeTotalCapacity(manager);
     const size_t avg_obj_size =
@@ -1236,7 +1243,8 @@ static FillUpResult runDsaBenchmark(const BenchConfig& cfg) {
 static SizeClassChurnResult runSizeClassChurnBenchmark(const BenchConfig& cfg) {
     AllocatorManager manager =
         createCluster(cfg.num_segments, cfg.segment_capacity, cfg.skewed);
-    auto strategy = CreateAllocationStrategy(cfg.strategy_type);
+    LocalSsdManager local_ssd;
+    auto strategy = CreateAllocationStrategy(cfg.strategy_type, local_ssd);
     auto specs = getSizeClassSpecs(cfg.size_class_pattern);
 
     std::vector<SizeClassStat> per_class_stats;
diff --git a/mooncake-store/benchmarks/batch_evict_bench.cpp b/mooncake-store/benchmarks/batch_evict_bench.cpp
index dd44a22c61..e6f1f2ff80 100644
--- a/mooncake-store/benchmarks/batch_evict_bench.cpp
+++ b/mooncake-store/benchmarks/batch_evict_bench.cpp
@@ -1,4 +1,5 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <algorithm>
 #include <chrono>
@@ -25,6 +26,8 @@ DEFINE_double(evict_ratio_lowerbound, 0.25,
 
 namespace mooncake::benchmarks {
 
+using mooncake::test::MasterServiceTestPeer;
+
 class BatchEvictBench {
    public:
     static bool RunRealBatchEvictScales() {
@@ -169,9 +172,10 @@ class BatchEvictBench {
         const auto base_expiration = now - std::chrono::hours(1);
         size_t ordinal = 0;
 
-        for (size_t shard_idx = 0; shard_idx < MasterService::kNumShards;
-             ++shard_idx) {
-            MasterService::MetadataShardAccessorRW shard(&service, shard_idx);
+        for (size_t shard_idx = 0;
+             shard_idx < MasterServiceTestPeer::kNumShards; ++shard_idx) {
+            MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                                 shard_idx);
             for (auto& [tenant_id, tenant_state] : shard->tenants) {
                 if (tenant_id != TenantId::Default()) {
                     continue;
@@ -179,9 +183,9 @@ class BatchEvictBench {
                 for (auto& [key, metadata] : tenant_state.metadata) {
                     {
                         SpinLocker locker(&metadata.lock);
-                        metadata.lease_timeout =
+                        metadata.lease_->SetDeadline(
                             base_expiration +
-                            std::chrono::nanoseconds(ordinal++);
+                            std::chrono::nanoseconds(ordinal++));
                     }
 
                     ++stats.object_count;
@@ -271,7 +275,8 @@ class BatchEvictBench {
         const auto wait_start = std::chrono::steady_clock::now();
         uint64_t wait_us = 0;
         {
-            std::unique_lock<std::shared_mutex> lock(service.snapshot_mutex_);
+            std::unique_lock<std::shared_mutex> lock(
+                MasterServiceTestPeer::SnapshotMutex(service));
             const auto wait_end = std::chrono::steady_clock::now();
             wait_us = std::chrono::duration_cast<std::chrono::microseconds>(
                           wait_end - wait_start)
@@ -345,8 +350,8 @@ class BatchEvictBench {
         }
 
         const auto evict_start = std::chrono::steady_clock::now();
-        service.BatchEvict(FLAGS_evict_ratio_target,
-                           FLAGS_evict_ratio_lowerbound);
+        MasterServiceTestPeer(service).RunBatchEvictForTesting(
+            FLAGS_evict_ratio_target, FLAGS_evict_ratio_lowerbound);
         const auto total_us =
             std::chrono::duration_cast<std::chrono::microseconds>(
                 std::chrono::steady_clock::now() - evict_start)
@@ -401,8 +406,8 @@ class BatchEvictBench {
         });
 
         const auto evict_start = std::chrono::steady_clock::now();
-        service.BatchEvict(FLAGS_evict_ratio_target,
-                           FLAGS_evict_ratio_lowerbound);
+        MasterServiceTestPeer(service).RunBatchEvictForTesting(
+            FLAGS_evict_ratio_target, FLAGS_evict_ratio_lowerbound);
         const auto batch_evict_total_us =
             std::chrono::duration_cast<std::chrono::microseconds>(
                 std::chrono::steady_clock::now() - evict_start)
diff --git a/mooncake-store/benchmarks/batch_oplog_promotion_bench.cpp b/mooncake-store/benchmarks/batch_oplog_promotion_bench.cpp
new file mode 100644
index 0000000000..c0f568f6bf
--- /dev/null
+++ b/mooncake-store/benchmarks/batch_oplog_promotion_bench.cpp
@@ -0,0 +1,84 @@
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+
+#include <chrono>
+#include <fstream>
+#include <iostream>
+#include <limits>
+#include <string>
+
+#include "ha/snapshot/batch_oplog/promotion.h"
+#include "master_service.h"
+
+DEFINE_uint64(objects, 100000, "Synthetic standby object count");
+DEFINE_uint64(chunk_objects, 1000, "Objects drained per chunk");
+
+namespace {
+
+size_t PeakRssBytes() {
+    std::ifstream status("/proc/self/status");
+    std::string name;
+    size_t rss_kib = 0;
+    while (status >> name) {
+        if (name == "VmHWM:") {
+            status >> rss_kib;
+            break;
+        }
+        status.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+    }
+    return rss_kib * 1024;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    google::InitGoogleLogging(argv[0]);
+    FLAGS_logtostderr = true;
+    gflags::ParseCommandLineFlags(&argc, &argv, true);
+    if (FLAGS_objects == 0 || FLAGS_chunk_objects == 0 ||
+        FLAGS_objects == std::numeric_limits<uint64_t>::max() ||
+        FLAGS_chunk_objects > std::numeric_limits<size_t>::max()) {
+        std::cerr << "objects and chunk_objects must be non-zero\n";
+        return 1;
+    }
+
+    auto source_store = std::make_unique<mooncake::StandbyMetadataStore>();
+    for (uint64_t i = 0; i < FLAGS_objects; ++i) {
+        mooncake::StandbyObjectMetadata metadata;
+        metadata.size = 1;
+        mooncake::Replica::Descriptor replica;
+        replica.id = i + 1;
+        replica.status = mooncake::ReplicaStatus::COMPLETE;
+        replica.descriptor_variant = mooncake::DiskDescriptor{"bench", 1};
+        metadata.replicas.push_back(std::move(replica));
+        if (!source_store->PutMetadata("default", "bench-" + std::to_string(i),
+                                       metadata)) {
+            return 1;
+        }
+    }
+
+    mooncake::BatchOpLogPromotionHandoff handoff;
+    handoff.metadata_store = std::move(source_store);
+    handoff.applied_cursor = {.batch_id = 1, .last_seq = 1};
+    handoff.max_replica_id = FLAGS_objects;
+    mooncake::MasterService primary(
+        mooncake::MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const auto started = std::chrono::steady_clock::now();
+    auto restored = primary.RestoreFromBatchOpLogPromotion(
+        std::move(handoff), static_cast<size_t>(FLAGS_chunk_objects));
+    if (!restored) {
+        std::cerr << "restore failed: " << static_cast<int>(restored.error())
+                  << '\n';
+        return 1;
+    }
+    const auto elapsed = std::chrono::duration_cast<std::chrono::microseconds>(
+        std::chrono::steady_clock::now() - started);
+
+    std::cout << "objects=" << FLAGS_objects
+              << " source_store=StandbyMetadataStore"
+              << " chunk_objects=" << FLAGS_chunk_objects
+              << " restore_us=" << elapsed.count()
+              << " peak_rss_bytes=" << PeakRssBytes() << '\n';
+    return 0;
+}
diff --git a/mooncake-store/benchmarks/nof_worker_pool_bench.cpp b/mooncake-store/benchmarks/nof_worker_pool_bench.cpp
index be127cb1b1..6fbf27ef26 100644
--- a/mooncake-store/benchmarks/nof_worker_pool_bench.cpp
+++ b/mooncake-store/benchmarks/nof_worker_pool_bench.cpp
@@ -25,8 +25,6 @@
 #include "spdk/spdk_wrapper.h"
 #include "transfer_task.h"
 
-namespace {
-
 constexpr uint64_t KiB = 1024;
 constexpr uint64_t MiB = 1024 * KiB;
 constexpr uint64_t GiB = 1024 * MiB;
@@ -96,6 +94,8 @@ DEFINE_int32(socket_id, -1,
 DEFINE_bool(fill_on_write, true,
             "Fill buffers with a deterministic pattern for write/mixed ops.");
 
+namespace {
+
 using Clock = std::chrono::steady_clock;
 using TimePoint = Clock::time_point;
 
diff --git a/mooncake-store/benchmarks/store_kv_bench.md b/mooncake-store/benchmarks/store_kv_bench.md
index 4d8f85a5e1..ca2ff33e6c 100644
--- a/mooncake-store/benchmarks/store_kv_bench.md
+++ b/mooncake-store/benchmarks/store_kv_bench.md
@@ -202,3 +202,8 @@ Each phase prints:
 - aggregated error counts
 
 An overall summary is printed after all phases complete.
+
+If a worker raises an exception, the benchmark waits for all workers to finish,
+reports the failed phase and lane, and exits with code `1`. This error path does
+not write a new summary or journal; any output files from an earlier run remain
+unchanged.
diff --git a/mooncake-store/benchmarks/store_kv_bench.py b/mooncake-store/benchmarks/store_kv_bench.py
index f09151cfb8..b03123ef20 100644
--- a/mooncake-store/benchmarks/store_kv_bench.py
+++ b/mooncake-store/benchmarks/store_kv_bench.py
@@ -24,17 +24,6 @@
 MooncakeDistributedStore = _store_module.MooncakeDistributedStore
 ReplicateConfig = _store_module.ReplicateConfig
 
-try:
-    get_alloc_func_addr = _store_module.get_alloc_func_addr
-    get_free_func_addr = _store_module.get_free_func_addr
-except AttributeError:
-
-    def get_alloc_func_addr():
-        return None
-
-    def get_free_func_addr():
-        return None
-
 
 LOG = logging.getLogger("store_kv_bench")
 
@@ -592,61 +581,41 @@ def _get_lengths_zcopy(self, keys: List[str], slot_count: int) -> List[int]:
 
 
 class ZcopyBufferPool:
-    def __init__(self, store_obj, value_size: int, slots: int):
+    def __init__(self, store_obj, value_size: int, slots: int, local_buffer_size: int):
         self.store = store_obj
         self.value_size = value_size
         self.slots = slots
         self.total_size = self.value_size * self.slots
-        self._alloc_fn = None
-        self._free_fn = None
-        self._registered = False
+        self._pool = None
+        self._lease = None
         self.base_ptr = 0
 
-        alloc_addr = get_alloc_func_addr()
-        free_addr = get_free_func_addr()
-        if alloc_addr is None or free_addr is None:
-            raise RuntimeError(
-                "store module does not expose hugepage alloc/free helpers"
+        if self.total_size > local_buffer_size:
+            raise ValueError(
+                "zcopy pool requires "
+                f"{self.total_size} bytes, but --local-buffer-size is "
+                f"{local_buffer_size}; increase --local-buffer-size"
             )
 
-        self._alloc_fn = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_size_t)(
-            get_alloc_func_addr()
+        self._pool = _store_module.BufferPool(
+            self.store, max_bytes=local_buffer_size, max_regions=1
         )
-        self._free_fn = ctypes.CFUNCTYPE(None, ctypes.c_void_p)(get_free_func_addr())
-
-        raw_ptr = self._alloc_fn(self.total_size)
-        self.base_ptr = ctypes.cast(raw_ptr, ctypes.c_void_p).value or 0
-        if self.base_ptr == 0:
-            raise RuntimeError(
-                f"direct hugepage alloc failed for zcopy pool: size={self.total_size}"
-            )
-        ret = self.store.register_buffer(self.base_ptr, self.total_size)
-        if ret != 0:
-            failed_ptr = self.base_ptr
-            self._free_fn(ctypes.c_void_p(self.base_ptr))
-            self.base_ptr = 0
-            raise RuntimeError(
-                f"register_buffer failed for direct zcopy pool ptr={failed_ptr}: {ret}"
-            )
-        self._registered = True
-        self._buffer = (ctypes.c_ubyte * self.total_size).from_address(self.base_ptr)
+        try:
+            self._lease = self._pool.acquire(self.total_size, block=False)
+        except Exception:
+            self._pool.close()
+            self._pool = None
+            raise
+        self.base_ptr = self._lease.ptr
 
     def close(self) -> None:
-        self._buffer = None
-        if self.base_ptr:
-            if self._registered:
-                try:
-                    self.store.unregister_buffer(self.base_ptr)
-                except Exception:
-                    LOG.debug(
-                        "unregister_buffer failed for direct zcopy pool ptr=%s",
-                        self.base_ptr,
-                        exc_info=True,
-                    )
-                self._registered = False
-            if self._free_fn is not None:
-                self._free_fn(ctypes.c_void_p(self.base_ptr))
-            self.base_ptr = 0
+        self.base_ptr = 0
+        if self._lease is not None:
+            self._lease.release()
+            self._lease = None
+        if self._pool is not None:
+            self._pool.close()
+            self._pool = None
 
     def slot_ptr(self, slot: int) -> int:
         if slot < 0 or slot >= self.slots:
@@ -714,7 +683,9 @@ def __init__(self, args: argparse.Namespace, lane_count: int):
         self.zcopy_pool: Optional[ZcopyBufferPool] = None
         if args.io_api == "zcopy":
             slots = max(1, args.batch_size) * lane_count
-            self.zcopy_pool = ZcopyBufferPool(self.store, args.value_size, slots)
+            self.zcopy_pool = ZcopyBufferPool(
+                self.store, args.value_size, slots, args.local_buffer_size
+            )
 
     def make_session(
         self,
@@ -994,11 +965,16 @@ def _run_threads(
         sessions = self._make_sessions()
         per_lane_stats: List[Optional[PhaseStats]] = [None] * self.lane_count
         threads: List[threading.Thread] = []
+        errors: List[Optional[BaseException]] = [None] * self.lane_count
 
         def runner(index: int, session: StoreSession) -> None:
             stats = PhaseStats(name=f"{phase_name}/lane{index}")
             stats.start_time = time.perf_counter()
-            worker_builder(session, index)(stats)
+            try:
+                worker_builder(session, index)(stats)
+            except BaseException as exc:
+                errors[index] = exc
+                return
             stats.end_time = time.perf_counter()
             per_lane_stats[index] = stats
 
@@ -1014,6 +990,11 @@ def runner(index: int, session: StoreSession) -> None:
         for thread in threads:
             thread.join()
 
+        # Join every lane before allowing the caller to release shared buffers.
+        for lane_id, error in enumerate(errors):
+            if error is not None:
+                raise RuntimeError(f"{phase_name} lane {lane_id} failed") from error
+
         merged = merge_stats(phase_name, [s for s in per_lane_stats if s is not None])
         log_phase_stats(merged)
         return merged
diff --git a/mooncake-store/benchmarks/test_store_kv_bench.py b/mooncake-store/benchmarks/test_store_kv_bench.py
index 2ede5f94f4..756f4a60f1 100644
--- a/mooncake-store/benchmarks/test_store_kv_bench.py
+++ b/mooncake-store/benchmarks/test_store_kv_bench.py
@@ -1,18 +1,53 @@
+import ctypes
 import importlib.util
 import json
 import os
 import sys
+import threading
 import types
 import unittest
 from pathlib import Path
+from tempfile import TemporaryDirectory
 from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+
+class FakeBufferLease:
+    def __init__(self, size):
+        self._buffer = (ctypes.c_ubyte * size)()
+        self.ptr = ctypes.addressof(self._buffer)
+        self.released = False
+
+    def release(self):
+        self.released = True
+
+
+class FakeBufferPool:
+    instances = []
+    acquire_error = None
+
+    def __init__(self, store, **kwargs):
+        self.store = store
+        self.kwargs = kwargs
+        self.lease = None
+        self.closed = False
+        self.instances.append(self)
+
+    def acquire(self, size, block=True):
+        if self.acquire_error is not None:
+            raise self.acquire_error
+        self.lease = FakeBufferLease(size)
+        self.acquire_args = (size, block)
+        return self.lease
+
+    def close(self):
+        self.closed = True
 
 
 store_module = types.ModuleType("mooncake.store")
 store_module.MooncakeDistributedStore = object
 store_module.ReplicateConfig = type("ReplicateConfig", (), {})
-store_module.get_alloc_func_addr = lambda: None
-store_module.get_free_func_addr = lambda: None
+store_module.BufferPool = FakeBufferPool
 sys.modules.setdefault("mooncake", types.ModuleType("mooncake"))
 sys.modules["mooncake.store"] = store_module
 
@@ -23,6 +58,20 @@
 SPEC.loader.exec_module(bench)
 
 
+class StoreModuleCompatibilityTest(unittest.TestCase):
+    def test_import_does_not_require_buffer_pool(self):
+        del store_module.BufferPool
+        module_name = "store_kv_bench_without_buffer_pool"
+        spec = importlib.util.spec_from_file_location(module_name, MODULE_PATH)
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+        finally:
+            store_module.BufferPool = FakeBufferPool
+            sys.modules.pop(module_name, None)
+
+
 class MetadataWorkloadModelTest(unittest.TestCase):
     def test_percentages_and_lane_choices_are_deterministic(self):
         weights = {"put": 40, "get": 30, "exist": 20, "remove": 10}
@@ -170,5 +219,152 @@ def remove(self, key):
         self.assertEqual(summary["journal_records"], 5)
 
 
+class WorkerFailureTest(unittest.TestCase):
+    def setUp(self):
+        args = bench.build_parser().parse_args(["--scenario=metadata_smoke"])
+        self.runner = bench.BenchmarkRunner(args)
+        self.runner._sessions = [Mock()]
+        hook = patch.object(threading, "excepthook")
+        hook.start()
+        self.addCleanup(hook.stop)
+
+    def test_worker_and_builder_errors_reach_caller(self):
+        for during_build in (False, True):
+            for error in (ValueError("store failed"), SystemExit(0)):
+                with self.subTest(during_build=during_build, error=type(error)):
+
+                    def build(session, lane):
+                        if during_build:
+                            raise error
+
+                        def work(stats):
+                            raise error
+
+                        return work
+
+                    with self.assertRaisesRegex(
+                        RuntimeError, "probe.*lane 0"
+                    ) as caught:
+                        self.runner._run_threads("probe", build)
+                    self.assertIs(caught.exception.__cause__, error)
+
+    def test_failure_joins_every_lane_before_returning(self):
+        self.runner.lane_count = 2
+        self.runner._sessions = [Mock(), Mock()]
+        joined = []
+        finished = threading.Event()
+        original_join = threading.Thread.join
+
+        def join(thread, *args, **kwargs):
+            original_join(thread, *args, **kwargs)
+            joined.append(thread.name)
+
+        def build(session, lane):
+            def work(stats):
+                if lane == 0:
+                    raise RuntimeError("first lane failed")
+                finished.set()
+                stats.requests = 1
+
+            return work
+
+        with patch.object(threading.Thread, "join", join):
+            with self.assertRaises(RuntimeError):
+                self.runner._run_threads("probe", build)
+        self.assertEqual(joined, ["probe-lane0", "probe-lane1"])
+        self.assertTrue(finished.is_set())
+
+    def test_healthy_lanes_keep_their_statistics(self):
+        self.runner.lane_count = 2
+        self.runner._sessions = [Mock(), Mock()]
+
+        def build(session, lane):
+            def work(stats):
+                stats.requests = lane + 1
+                stats.successful_requests = lane + 1
+
+            return work
+
+        stats = self.runner._run_threads("probe", build)
+        self.assertEqual(stats.requests, 3)
+        self.assertEqual(stats.successful_requests, 3)
+        self.assertEqual(stats.failed_requests, 0)
+
+    def test_cli_fails_without_writing_success_and_closes_store(self):
+        for scenario, operation in (("metadata_smoke", "put"), ("verify_write", "get")):
+            with self.subTest(scenario=scenario), TemporaryDirectory() as directory:
+                store = Mock()
+                store.setup.return_value = 0
+                store.put.return_value = 0
+                getattr(store, operation).side_effect = RuntimeError("store failed")
+                argv = [
+                    "store_kv_bench.py",
+                    "--scenario",
+                    scenario,
+                    "--nr-objects=1",
+                    "--output-dir",
+                    directory,
+                ]
+                with (
+                    patch.object(bench, "MooncakeDistributedStore", return_value=store),
+                    patch.object(sys, "argv", argv),
+                    patch.object(bench.LOG, "exception") as log_error,
+                ):
+                    self.assertEqual(bench.main(), 1)
+                log_error.assert_called_once()
+                store.close.assert_called_once()
+                self.assertFalse((Path(directory) / "summary.json").exists())
+
+
+class ZcopyBufferPoolTest(unittest.TestCase):
+    def setUp(self):
+        FakeBufferPool.instances.clear()
+        FakeBufferPool.acquire_error = None
+
+    def test_uses_native_buffer_pool_without_nof_allocators(self):
+        store = object()
+        pool = bench.ZcopyBufferPool(
+            store, value_size=16, slots=2, local_buffer_size=64
+        )
+        native_pool = FakeBufferPool.instances[0]
+
+        self.assertIs(native_pool.store, store)
+        self.assertEqual(native_pool.kwargs, {"max_bytes": 64, "max_regions": 1})
+        self.assertEqual(native_pool.acquire_args, (32, False))
+        self.assertEqual(pool.slot_ptr(1), pool.base_ptr + 16)
+
+        view = bench.ZcopyBufferView(pool, slot_offset=0, slots=2)
+        self.assertEqual(view.fill_write_buffers([b"abc"]), [pool.base_ptr])
+        self.assertEqual(view.read_bytes(0, 3), b"abc")
+
+        lease = native_pool.lease
+        pool.close()
+        self.assertTrue(lease.released)
+        self.assertTrue(native_pool.closed)
+        self.assertEqual(pool.base_ptr, 0)
+
+        pool.close()
+        self.assertTrue(lease.released)
+        self.assertTrue(native_pool.closed)
+
+    def test_rejects_pool_larger_than_store_local_buffer(self):
+        with self.assertRaisesRegex(ValueError, "increase --local-buffer-size"):
+            bench.ZcopyBufferPool(
+                object(), value_size=32, slots=3, local_buffer_size=64
+            )
+        self.assertEqual(FakeBufferPool.instances, [])
+
+    def test_closes_native_pool_when_acquire_fails(self):
+        FakeBufferPool.acquire_error = RuntimeError("buffer pool is exhausted")
+
+        with self.assertRaisesRegex(RuntimeError, "buffer pool is exhausted"):
+            bench.ZcopyBufferPool(
+                object(), value_size=16, slots=2, local_buffer_size=64
+            )
+
+        self.assertEqual(len(FakeBufferPool.instances), 1)
+        self.assertTrue(FakeBufferPool.instances[0].closed)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/mooncake-store/benchmarks/uring_batch_read_bench.cpp b/mooncake-store/benchmarks/uring_batch_read_bench.cpp
new file mode 100644
index 0000000000..8e896947d2
--- /dev/null
+++ b/mooncake-store/benchmarks/uring_batch_read_bench.cpp
@@ -0,0 +1,236 @@
+#include <fcntl.h>
+#include <unistd.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <iomanip>
+#include <iostream>
+#include <memory>
+#include <random>
+#include <string>
+#include <vector>
+
+#include "file_interface.h"
+
+#ifdef USE_URING
+namespace {
+
+constexpr size_t kAlignment = 4096;
+
+struct FreeDeleter {
+    void operator()(void* pointer) const { std::free(pointer); }
+};
+
+using AlignedBuffer = std::unique_ptr<void, FreeDeleter>;
+
+AlignedBuffer AllocateAligned(size_t size) {
+    void* pointer = nullptr;
+    if (posix_memalign(&pointer, kAlignment, size) != 0) return nullptr;
+    return AlignedBuffer(pointer);
+}
+
+bool PrepareFile(const std::string& path, size_t size) {
+    int fd = open(path.c_str(), O_CREAT | O_RDWR | O_TRUNC | O_CLOEXEC, 0644);
+    if (fd < 0) {
+        perror("open");
+        return false;
+    }
+
+    constexpr size_t kWriteSize = 4 * 1024 * 1024;
+    auto buffer = AllocateAligned(kWriteSize);
+    if (!buffer) {
+        close(fd);
+        return false;
+    }
+    std::memset(buffer.get(), 0x5a, kWriteSize);
+
+    size_t written = 0;
+    while (written < size) {
+        size_t length = std::min(kWriteSize, size - written);
+        ssize_t result = pwrite(fd, buffer.get(), length, written);
+        if (result != static_cast<ssize_t>(length)) {
+            perror("pwrite");
+            close(fd);
+            return false;
+        }
+        written += length;
+    }
+
+    bool ok = fdatasync(fd) == 0;
+    if (!ok) perror("fdatasync");
+    close(fd);
+    return ok;
+}
+
+struct Result {
+    double seconds;
+    uint64_t operations;
+    uint64_t bytes;
+};
+
+Result RunSequential(mooncake::UringFile& file,
+                     std::vector<mooncake::UringFile::ReadDesc>& descs,
+                     const std::vector<std::vector<off_t>>& offsets) {
+    auto start = std::chrono::steady_clock::now();
+    uint64_t operations = 0;
+    uint64_t bytes = 0;
+    for (const auto& iteration_offsets : offsets) {
+        for (size_t i = 0; i < descs.size(); ++i) {
+            auto result = file.read_aligned(descs[i].buf, descs[i].len,
+                                            iteration_offsets[i]);
+            if (!result || result.value() != descs[i].len) {
+                std::cerr << "sequential read failed at request " << i << '\n';
+                std::exit(2);
+            }
+            ++operations;
+            bytes += result.value();
+        }
+    }
+    auto end = std::chrono::steady_clock::now();
+    return {std::chrono::duration<double>(end - start).count(), operations,
+            bytes};
+}
+
+Result RunBatch(mooncake::UringFile& file,
+                std::vector<mooncake::UringFile::ReadDesc>& descs,
+                const std::vector<std::vector<off_t>>& offsets) {
+    auto start = std::chrono::steady_clock::now();
+    uint64_t operations = 0;
+    uint64_t bytes = 0;
+    for (const auto& iteration_offsets : offsets) {
+        for (size_t i = 0; i < descs.size(); ++i) {
+            descs[i].off = iteration_offsets[i];
+        }
+        auto result = file.batch_read(descs.data(), descs.size());
+        if (!result) {
+            std::cerr << "batch read failed\n";
+            std::exit(3);
+        }
+        for (const auto& desc : descs) {
+            if (!desc.completed || desc.error != mooncake::ErrorCode::OK ||
+                desc.bytes_read != desc.len) {
+                std::cerr << "batch read returned an invalid result\n";
+                std::exit(4);
+            }
+            ++operations;
+            bytes += desc.bytes_read;
+        }
+    }
+    auto end = std::chrono::steady_clock::now();
+    return {std::chrono::duration<double>(end - start).count(), operations,
+            bytes};
+}
+
+void PrintResult(const std::string& name, const Result& result) {
+    double iops = static_cast<double>(result.operations) / result.seconds;
+    double mib_per_second =
+        static_cast<double>(result.bytes) / (1024.0 * 1024.0) / result.seconds;
+    double latency_us = result.seconds * 1e6 / result.operations;
+    std::cout << std::fixed << std::setprecision(2) << name
+              << ": seconds=" << result.seconds << " iops=" << iops
+              << " MiB/s=" << mib_per_second
+              << " average_us_per_request=" << latency_us << '\n';
+}
+
+size_t ParseSize(const char* value, size_t fallback) {
+    if (value == nullptr) return fallback;
+    char* end = nullptr;
+    unsigned long long parsed = std::strtoull(value, &end, 10);
+    return end != value && *end == '\0' ? static_cast<size_t>(parsed)
+                                        : fallback;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    std::string path = argc > 1 ? argv[1] : "/tmp/uring_batch_read_bench.dat";
+    size_t file_size_mib = ParseSize(argc > 2 ? argv[2] : nullptr, 1024);
+    size_t request_count = ParseSize(argc > 3 ? argv[3] : nullptr, 32);
+    size_t block_size = ParseSize(argc > 4 ? argv[4] : nullptr, 4096);
+    size_t iterations = ParseSize(argc > 5 ? argv[5] : nullptr, 10000);
+    size_t rounds = ParseSize(argc > 6 ? argv[6] : nullptr, 4);
+
+    if (request_count == 0 || block_size == 0 || iterations == 0 ||
+        block_size % kAlignment != 0) {
+        std::cerr << "invalid benchmark parameters\n";
+        return 1;
+    }
+
+    size_t file_size = file_size_mib * 1024 * 1024;
+    file_size -= file_size % block_size;
+    std::cout << "preparing " << file_size_mib << " MiB file at " << path
+              << '\n';
+    if (!PrepareFile(path, file_size)) return 1;
+
+    int fd = open(path.c_str(), O_RDONLY | O_DIRECT | O_CLOEXEC);
+    if (fd < 0) {
+        perror("open O_DIRECT");
+        return 1;
+    }
+    mooncake::UringFile file(path, fd, 32, true);
+
+    auto buffer = AllocateAligned(request_count * block_size);
+    if (!buffer) return 1;
+    mooncake::UringFile::register_global_buffer(buffer.get(),
+                                                request_count * block_size);
+
+    std::vector<mooncake::UringFile::ReadDesc> descs;
+    descs.reserve(request_count);
+    for (size_t i = 0; i < request_count; ++i) {
+        descs.push_back(mooncake::UringFile::ReadDesc{
+            static_cast<char*>(buffer.get()) + i * block_size, block_size, 0});
+    }
+
+    std::mt19937_64 generator(20260817);
+    std::uniform_int_distribution<uint64_t> distribution(
+        0, file_size / block_size - 1);
+    std::vector<std::vector<off_t>> offsets(iterations,
+                                            std::vector<off_t>(request_count));
+    for (auto& iteration_offsets : offsets) {
+        for (auto& offset : iteration_offsets) {
+            offset = static_cast<off_t>(distribution(generator) * block_size);
+        }
+    }
+
+    RunSequential(file, descs, {offsets.front()});
+    RunBatch(file, descs, {offsets.front()});
+
+    double sequential_seconds = 0;
+    double batch_seconds = 0;
+    uint64_t operations = 0;
+    uint64_t bytes = 0;
+    for (size_t round = 0; round < rounds; ++round) {
+        Result sequential;
+        Result batch;
+        if (round % 2 == 0) {
+            sequential = RunSequential(file, descs, offsets);
+            batch = RunBatch(file, descs, offsets);
+        } else {
+            batch = RunBatch(file, descs, offsets);
+            sequential = RunSequential(file, descs, offsets);
+        }
+        PrintResult("sequential round " + std::to_string(round), sequential);
+        PrintResult("batch round " + std::to_string(round), batch);
+        sequential_seconds += sequential.seconds;
+        batch_seconds += batch.seconds;
+        operations += sequential.operations;
+        bytes += sequential.bytes;
+    }
+
+    Result sequential_total{sequential_seconds, operations, bytes};
+    Result batch_total{batch_seconds, operations, bytes};
+    PrintResult("sequential total", sequential_total);
+    PrintResult("batch total", batch_total);
+    std::cout << "speedup=" << sequential_seconds / batch_seconds << "x\n";
+
+    mooncake::UringFile::unregister_global_buffer();
+    unlink(path.c_str());
+    return 0;
+}
+#else
+int main() {
+    std::cerr << "io_uring support is not enabled\n";
+    return 1;
+}
+#endif
diff --git a/mooncake-store/conf/master.json b/mooncake-store/conf/master.json
index f55bdaf2b2..e1fa59483f 100644
--- a/mooncake-store/conf/master.json
+++ b/mooncake-store/conf/master.json
@@ -9,16 +9,23 @@
   "rpc_enable_tcp_no_delay": true,
   "default_kv_lease_ttl": 10000,
   "default_kv_soft_pin_ttl": 1800000,
+  "max_kv_soft_pin_ttl": 86400000,
   "allow_evict_soft_pinned_objects": true,
   "eviction_ratio": 0.1,
   "eviction_high_watermark_ratio": 1.0,
+  "tenant_eviction_high_watermark_ratio": 0.9,
+  "dynamic_replication_mode": "off",
+  "dynamic_replication_heat_window_seconds": 10,
+  "dynamic_replication_admission_qps_threshold": 0.8,
+  "dynamic_replication_max_memory_replicas": 2,
   "enable_ha": false,
   "enable_oplog": false,
   "etcd_endpoints": "http://localhost:2379",
   "root_fs_dir": "",
   "cluster_id": "mooncake_cluster",
   "memory_allocator": "offset",
-  "client_live_ttl_sec": 60,
+  "client_active_ttl_sec": 60,
+  "client_suspicion_ttl_sec": 60,
   "enable_http_metadata_server": false,
   "http_metadata_server_host": "0.0.0.0",
   "http_metadata_server_port": 8080,
@@ -27,7 +34,11 @@
   "kv_events_model_name": "",
   "kv_events_backend_id": "",
   "kv_events_tenant_id": "default",
+  "kv_events_additional_salt": "",
+  "kv_events_lora_name": "",
   "kv_events_block_size": 0,
   "kv_events_dp_rank": 0,
-  "kv_events_emit_object_key": true
+  "kv_events_emit_object_key": true,
+  "kv_events_emit_legacy_compat": true,
+  "kv_events_queue_capacity": 65536
 }
diff --git a/mooncake-store/conf/master.yaml b/mooncake-store/conf/master.yaml
index 545807008f..5a659fd5aa 100644
--- a/mooncake-store/conf/master.yaml
+++ b/mooncake-store/conf/master.yaml
@@ -9,12 +9,36 @@ rpc_enable_tcp_no_delay: true
 
 default_kv_lease_ttl: 10000
 default_kv_soft_pin_ttl: 1800000
+max_kv_soft_pin_ttl: 86400000
 allow_evict_soft_pinned_objects: true
 eviction_ratio: 0.1
 # Overrides the 0.90 code default. A value of 1.0 disables proactive
 # usage-ratio eviction; allocation-failure-triggered eviction remains enabled.
 eviction_high_watermark_ratio: 1.0
 
+# Per-tenant eviction watermark, as a fraction of each tenant's OWN effective
+# quota. Defaults to 0.9 in code, mirroring eviction_high_watermark_ratio; set
+# 0.0 to disable the pass and keep the historical behaviour.
+#
+# Only relevant with enable_multi_tenants. This pass is the only mechanism that
+# frees space for a tenant -- admission never evicts, it rejects with
+# TENANT_QUOTA_EXCEEDED and lets this pass build the headroom for the retry.
+#
+# Because effective quotas sum to exactly the pool capacity, at most one
+# tenant's share can exceed eviction_high_watermark_ratio; every other tenant
+# reaches its own ceiling before the pool crosses the pool-wide watermark, so
+# without this nothing ever reclaims on its behalf.
+tenant_eviction_high_watermark_ratio: 0.9
+
+# Dynamic MEMORY replica fanout is disabled by default. Replica removal is
+# driven by the existing memory eviction/reclaim path; when a dynamic replica
+# is evicted, Master records a short recreate cooldown so hot-read admission
+# does not immediately add the same capacity back.
+dynamic_replication_mode: "off"
+dynamic_replication_heat_window_seconds: 10
+dynamic_replication_admission_qps_threshold: 0.8
+dynamic_replication_max_memory_replicas: 2
+
 enable_multi_tenants: false
 tenant_quota_connector_type: "file"
 tenant_quota_connector_uri: ""
@@ -24,10 +48,14 @@ etcd_endpoints: "http://localhost:2379"
 root_fs_dir: ""
 cluster_id: "mooncake_cluster"
 memory_allocator: "offset"
-client_live_ttl_sec: 60
+client_active_ttl_sec: 60
+client_suspicion_ttl_sec: 60
 
 # OpLog store configuration for HA hot-standby replication
 enable_oplog: false
+enable_oplog_snapshot: false
+# Maximum objects per standby batch OpLog snapshot chunk
+snapshot_chunk_object_count: 1000000
 # Batch standby base polling/retry delay in milliseconds
 oplog_poll_interval_ms: 1000
 # Maximum consecutive retryable batch-standby failure window in seconds
diff --git a/mooncake-store/go/build.sh b/mooncake-store/go/build.sh
index df9a9d6dd7..43be8ad39c 100755
--- a/mooncake-store/go/build.sh
+++ b/mooncake-store/go/build.sh
@@ -35,16 +35,28 @@ CGO_CFLAGS="-I${REPO_ROOT}/mooncake-store/include"
 CGO_CFLAGS+=" -I${REPO_ROOT}/mooncake-transfer-engine/include"
 
 # CGo linker flags — link against mooncake_store, transfer_engine, and deps
+# master_service.cpp (inside libmooncake_store.a) calls into LocalSsdManager,
+# which lives in its own static archive under local_ssd/. It is built
+# unconditionally and is a required dependency of mooncake_store, so link it
+# inside the group where cyclic references resolve.
 CGO_LDFLAGS="-L${BUILD_DIR}/mooncake-store/src"
 CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-store/src/cachelib_memory_allocator"
+CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-store/src/local_ssd"
 CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-transfer-engine/src"
 CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-transfer-engine/src/common/base"
 CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-common"
 CGO_LDFLAGS+=" -L${BUILD_DIR}/mooncake-common/src"
-CGO_LDFLAGS+=" -Wl,--start-group -lmooncake_store -lcachelib_memory_allocator -ltransfer_engine -lbase -lmooncake_common -Wl,--end-group"
+CGO_LDFLAGS+=" -Wl,--start-group -lmooncake_store -lmooncake_local_ssd -lcachelib_memory_allocator -ltransfer_engine -lbase -lmooncake_common -Wl,--end-group"
 CGO_LDFLAGS+=" -lasio -lxxhash -lyaml-cpp"
 CGO_LDFLAGS+=" -lstdc++ -lnuma -lglog -lgflags -libverbs -lmlx5 -ljsoncpp -lzstd -lcurl -lm"
 
+# OSS adapter request signing uses OpenSSL HMAC (EVP_sha256). Static archives
+# carry no transitive deps, so the Go link needs libcrypto explicitly when the
+# adapter was compiled in (CURL + OpenSSL found at CMake time).
+if grep -q '^MOONCAKE_OSS_ADAPTER_ENABLED:INTERNAL=TRUE$' "${BUILD_DIR}/CMakeCache.txt" 2>/dev/null; then
+    CGO_LDFLAGS+=" -lcrypto"
+fi
+
 if [ -d "/usr/local/cuda/lib64" ]; then
     CGO_LDFLAGS+=" -L/usr/local/cuda/lib64 -lcudart"
 fi
diff --git a/mooncake-store/go/mooncakestore/config.go b/mooncake-store/go/mooncakestore/config.go
index 83a7bbd5c0..1f48416df2 100644
--- a/mooncake-store/go/mooncakestore/config.go
+++ b/mooncake-store/go/mooncakestore/config.go
@@ -14,10 +14,30 @@
 
 package mooncakestore
 
+// SoftPinAction selects the soft-pin intent of a put operation. A soft pin
+// guards an object from eviction until a deadline fixed at write time;
+// reads never extend it.
+type SoftPinAction int
+
+const (
+	// SoftPinPreserve keeps an existing unexpired soft-pin deadline. It is
+	// the zero value, so plain puts commit ordinary cache.
+	SoftPinPreserve SoftPinAction = iota
+	// SoftPinEnable commits a new soft-pin lifetime when the write
+	// becomes readable.
+	SoftPinEnable
+	// SoftPinDisable removes an existing soft pin when the write
+	// becomes readable.
+	SoftPinDisable
+)
+
 // ReplicateConfig controls replica placement for put operations.
 type ReplicateConfig struct {
-	ReplicaNum        int
-	WithSoftPin       bool
+	ReplicaNum    int
+	SoftPinAction SoftPinAction
+	// SoftPinTTLMs overrides the master's default soft-pin TTL in
+	// milliseconds. Only valid with SoftPinEnable.
+	SoftPinTTLMs      *uint64
 	WithHardPin       bool
 	PreferredSegments []string
 }
@@ -26,7 +46,6 @@ type ReplicateConfig struct {
 func DefaultReplicateConfig() ReplicateConfig {
 	return ReplicateConfig{
 		ReplicaNum:  1,
-		WithSoftPin: false,
 		WithHardPin: false,
 	}
 }
diff --git a/mooncake-store/go/mooncakestore/store.go b/mooncake-store/go/mooncakestore/store.go
index 1465bfa9c0..600cbf9714 100644
--- a/mooncake-store/go/mooncakestore/store.go
+++ b/mooncake-store/go/mooncakestore/store.go
@@ -136,9 +136,18 @@ func (s *Store) toCConfig(cfg *ReplicateConfig) (C.mooncake_replicate_config_t,
 		return cc, nil, ErrInvalidArgument
 	}
 
+	if cfg.SoftPinAction < SoftPinPreserve || cfg.SoftPinAction > SoftPinDisable {
+		return cc, nil, ErrInvalidArgument
+	}
+	if cfg.SoftPinTTLMs != nil && cfg.SoftPinAction != SoftPinEnable {
+		return cc, nil, ErrInvalidArgument
+	}
+
 	cc.replica_num = C.size_t(cfg.ReplicaNum)
-	if cfg.WithSoftPin {
-		cc.with_soft_pin = 1
+	cc.soft_pin_action = C.int(cfg.SoftPinAction)
+	if cfg.SoftPinTTLMs != nil {
+		cc.has_soft_pin_ttl = 1
+		cc.soft_pin_ttl_ms = C.uint64_t(*cfg.SoftPinTTLMs)
 	}
 	if cfg.WithHardPin {
 		cc.with_hard_pin = 1
diff --git a/mooncake-store/go/tests/integration_test.go b/mooncake-store/go/tests/integration_test.go
index d6d9a4cca4..00278a7d98 100644
--- a/mooncake-store/go/tests/integration_test.go
+++ b/mooncake-store/go/tests/integration_test.go
@@ -15,6 +15,7 @@
 package tests
 
 import (
+	"os"
 	"testing"
 
 	store "github.com/kvcache-ai/Mooncake/mooncake-store/go/mooncakestore"
@@ -25,6 +26,18 @@ import (
 // To run:
 //   mooncake_master --enable_http_metadata_server=true
 //   go test -v ./tests/...
+//
+// The endpoints default to a master with its embedded HTTP metadata server
+// on the standard ports and can be overridden for other environments:
+//   MC_METADATA_SERVER (default "http://localhost:8080/metadata")
+//   MOONCAKE_MASTER    (default "localhost:50051")
+
+func envOrDefault(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
 
 func setupStore(t *testing.T) *store.Store {
 	t.Helper()
@@ -34,12 +47,12 @@ func setupStore(t *testing.T) *store.Store {
 	}
 	err = s.Setup(
 		"localhost",
-		"http://localhost:8080/metadata",
+		envOrDefault("MC_METADATA_SERVER", "http://localhost:8080/metadata"),
 		512*1024*1024, // 512 MB global segment
 		128*1024*1024, // 128 MB local buffer
 		"tcp",
 		"",
-		"localhost:50051",
+		envOrDefault("MOONCAKE_MASTER", "localhost:50051"),
 	)
 	if err != nil {
 		s.Close()
@@ -167,8 +180,8 @@ func TestReplicateConfig(t *testing.T) {
 	defer s.Close()
 
 	cfg := &store.ReplicateConfig{
-		ReplicaNum:  2,
-		WithSoftPin: true,
+		ReplicaNum:    2,
+		SoftPinAction: store.SoftPinEnable,
 	}
 
 	key := "test_go_replicated"
@@ -186,3 +199,46 @@ func TestReplicateConfig(t *testing.T) {
 
 	_ = s.Remove(key, true)
 }
+
+func TestReplicateConfigSoftPinTTL(t *testing.T) {
+	s := setupStore(t)
+	defer s.Close()
+
+	ttl := uint64(60000)
+	cfg := &store.ReplicateConfig{
+		ReplicaNum:    1,
+		SoftPinAction: store.SoftPinEnable,
+		SoftPinTTLMs:  &ttl,
+	}
+
+	key := "test_go_softpin_ttl"
+	if err := s.Put(key, []byte("pinned data"), cfg); err != nil {
+		t.Fatalf("Put with soft pin TTL failed: %v", err)
+	}
+
+	exists, err := s.Exists(key)
+	if err != nil {
+		t.Fatalf("Exists() failed: %v", err)
+	}
+	if !exists {
+		t.Fatal("expected soft-pinned key to exist")
+	}
+
+	_ = s.Remove(key, true)
+}
+
+func TestReplicateConfigSoftPinValidation(t *testing.T) {
+	s := setupStore(t)
+	defer s.Close()
+
+	ttl := uint64(60000)
+	invalidConfigs := []store.ReplicateConfig{
+		{ReplicaNum: 1, SoftPinAction: store.SoftPinDisable, SoftPinTTLMs: &ttl},
+		{ReplicaNum: 1, SoftPinAction: store.SoftPinAction(7)},
+	}
+	for i, cfg := range invalidConfigs {
+		if err := s.Put("test_go_softpin_invalid", []byte("v"), &cfg); err != store.ErrInvalidArgument {
+			t.Fatalf("config %d: expected ErrInvalidArgument, got %v", i, err)
+		}
+	}
+}
diff --git a/mooncake-store/include/allocation_strategy.h b/mooncake-store/include/allocation_strategy.h
index 93f4dcaf68..762dff87a7 100644
--- a/mooncake-store/include/allocation_strategy.h
+++ b/mooncake-store/include/allocation_strategy.h
@@ -2,20 +2,27 @@
 
 #include <algorithm>
 #include <memory>
-#include <string>
+#include <optional>
 #include <set>
+#include <string>
 #include <unordered_map>
+#include <utility>
+#include <vector>
 #include <iterator>
 #include <time.h>
 #include <ylt/util/tl/expected.hpp>
 
-#include "allocator.h"  // Contains BufferAllocator declaration
+#include "segment_allocator_registration.h"
 #include "replica.h"
 #include "types.h"
 #include "random.h"
 
 namespace mooncake {
 
+class LocalSsdManager;
+class ScopedAllocatorAccess;
+class ScopedSegmentAccess;
+
 /**
  * @brief A container for managing valid allocators.
  *
@@ -41,12 +48,21 @@ class AllocatorManager {
      * @param name the name of the segment
      * @param allocator the buffer allocator to add for the segment
      */
-    void addAllocator(const std::string& name,
-                      const std::shared_ptr<BufferAllocatorBase>& allocator) {
-        if (!allocators_.contains(name)) {
-            names_.push_back(name);
-        }
-        allocators_[name].push_back(allocator);
+    std::shared_ptr<SegmentAllocatorRegistration> addAllocator(
+        const std::string& name,
+        const std::shared_ptr<BufferAllocatorBase>& allocator) {
+        return addAllocator(name, allocator, nullptr);
+    }
+
+    std::shared_ptr<SegmentAllocatorRegistration> addAllocator(
+        const std::string& name,
+        const std::shared_ptr<BufferAllocatorBase>& allocator,
+        std::shared_ptr<ClientLivenessRecord> client_liveness) {
+        auto registration = std::shared_ptr<SegmentAllocatorRegistration>(
+            new SegmentAllocatorRegistration(allocator,
+                                             std::move(client_liveness)));
+        addRegistration(name, registration);
+        return registration;
     }
 
     /**
@@ -54,29 +70,26 @@ class AllocatorManager {
      *        also removes the name if there are no allocators after the
      *        removal.
      * @param name the name of the segment
-     * @param allocator the buffer allocator to remove from the segment
-     * @return true if the allocator is removed, false if the allocator does
-     *         not exist
+     * @param registration the allocator registration to remove
+     * @return true if the registration is removed, false if it does not exist
      */
     bool removeAllocator(
         const std::string& name,
-        const std::shared_ptr<BufferAllocatorBase>& allocator) {
+        const std::shared_ptr<SegmentAllocatorRegistration>& registration) {
         auto it = allocators_.find(name);
         if (it == allocators_.end()) {
             return false;
         }
 
-        // Try removing the allocator.
-        bool allocator_removed = false;
-        auto alloc_it =
-            std::find(it->second.begin(), it->second.end(), allocator);
-        if (alloc_it != it->second.end()) {
-            it->second.erase(alloc_it);
-            allocator_removed = true;
+        bool registration_removed = false;
+        auto registration_it =
+            std::find(it->second.begin(), it->second.end(), registration);
+        if (registration_it != it->second.end()) {
+            it->second.erase(registration_it);
+            registration_removed = true;
         }
 
         if (it->second.empty()) {
-            // If there is no allocator left, remove the name too.
             allocators_.erase(name);
             auto name_it = std::find(names_.begin(), names_.end(), name);
             if (name_it != names_.end()) {
@@ -85,7 +98,7 @@ class AllocatorManager {
             }
         }
 
-        return allocator_removed;
+        return registration_removed;
     }
 
     struct Replacement {
@@ -102,19 +115,41 @@ class AllocatorManager {
             if (it == allocators_.end() || !replacement.replacement) {
                 return false;
             }
-            auto target = std::find(it->second.begin(), it->second.end(),
-                                    replacement.expected);
+            auto target = std::find_if(
+                it->second.begin(), it->second.end(),
+                [&replacement](const auto& registration) {
+                    return registration->GetAllocator() == replacement.expected;
+                });
             if (target == it->second.end()) {
                 return false;
             }
             targets.push_back(target);
         }
         for (size_t i = 0; i < replacements.size(); ++i) {
-            *targets[i] = replacements[i].replacement;
+            (*targets[i])->BindAllocator(replacements[i].replacement);
         }
         return true;
     }
 
+    AllocatorManager Snapshot(
+        const std::unordered_map<std::string, UUID>* owners = nullptr) const {
+        AllocatorManager snapshot;
+        snapshot.names_ = names_;
+        snapshot.allocators_ = allocators_;
+        if (owners) {
+            snapshot.owner_by_name_ = *owners;
+        }
+        return snapshot;
+    }
+
+    [[nodiscard]] std::optional<UUID> GetOwnerClientId(
+        const std::string& name) const {
+        const auto owner = owner_by_name_.find(name);
+        return owner == owner_by_name_.end()
+                   ? std::nullopt
+                   : std::optional<UUID>(owner->second);
+    }
+
     /**
      * @brief Get the names of all segments. This returns a vector of the
      *        names so that we can randomly pick a segment without traversing.
@@ -122,12 +157,27 @@ class AllocatorManager {
      */
     const std::vector<std::string>& getNames() const { return names_; }
 
+    [[nodiscard]] std::vector<std::string> getServingNames() const {
+        std::vector<std::string> serving_names;
+        serving_names.reserve(names_.size());
+        for (const auto& name : names_) {
+            const auto& registrations = allocators_.at(name);
+            if (std::any_of(registrations.begin(), registrations.end(),
+                            [](const auto& registration) {
+                                return registration->IsServing();
+                            })) {
+                serving_names.push_back(name);
+            }
+        }
+        return serving_names;
+    }
+
     /**
-     * @brief Get allocators belongs to the given segment name.
-     * @return a vector of allocators belongs to the given segment name
+     * @brief Get allocator registrations belonging to the given segment name.
+     * @return a vector of registrations belonging to the segment name
      */
-    const std::vector<std::shared_ptr<BufferAllocatorBase>>* getAllocators(
-        const std::string& name) const {
+    const std::vector<std::shared_ptr<SegmentAllocatorRegistration>>*
+    getAllocators(const std::string& name) const {
         auto it = allocators_.find(name);
         if (it != allocators_.end()) {
             return &it->second;
@@ -137,21 +187,24 @@ class AllocatorManager {
     }
 
    private:
+    void addRegistration(
+        const std::string& name,
+        const std::shared_ptr<SegmentAllocatorRegistration>& registration) {
+        if (!allocators_.contains(name)) {
+            names_.push_back(name);
+        }
+        allocators_[name].push_back(registration);
+    }
+
     // Name array for randomly picking allocators.
     std::vector<std::string> names_;
-    // Segment name to allocators mapping.
-    std::unordered_map<std::string,
-                       std::vector<std::shared_ptr<BufferAllocatorBase>>>
+    // Segment name to allocator registrations mapping.
+    std::unordered_map<
+        std::string, std::vector<std::shared_ptr<SegmentAllocatorRegistration>>>
         allocators_;
-    friend class SegmentSerializer;  // for fork serialize
-};
-
-class SsdMetricsProvider {
-   public:
-    virtual ~SsdMetricsProvider() = default;
-    virtual int64_t getSsdTotalCapacity(
-        const std::string& segment_name) const = 0;
-    virtual int64_t getSsdUsedBytes(const std::string& segment_name) const = 0;
+    std::unordered_map<std::string, UUID> owner_by_name_;
+    friend class ScopedSegmentAccess;
+    friend class SegmentSerializer;
 };
 
 /**
@@ -202,16 +255,13 @@ class AllocationStrategy {
         const ReplicaType replica_type = ReplicaType::MEMORY) = 0;
 
     virtual tl::expected<std::vector<Replica>, ErrorCode> Allocate(
-        const AllocatorManager& allocator_manager, const size_t slice_length,
-        const size_t replica_num,
-        const std::vector<std::string>& preferred_segments,
-        const std::set<std::string>& excluded_segments,
-        const ReplicaType replica_type,
-        const SsdMetricsProvider* ssd_provider) {
-        (void)ssd_provider;
-        return Allocate(allocator_manager, slice_length, replica_num,
-                        preferred_segments, excluded_segments, replica_type);
-    }
+        const ScopedAllocatorAccess& placement, const size_t slice_length,
+        const size_t replica_num = 1,
+        const std::vector<std::string>& preferred_segments =
+            std::vector<std::string>(),
+        const std::set<std::string>& excluded_segments =
+            std::set<std::string>(),
+        const ReplicaType replica_type = ReplicaType::MEMORY);
 
     /**
      * @brief Allocate one replica from the specified segment.
@@ -264,7 +314,7 @@ class RandomAllocationStrategy : public AllocationStrategy {
         }
 
         // Check available segments.
-        const auto& names = allocator_manager.getNames();
+        const auto names = allocator_manager.getServingNames();
         if (names.empty()) {
             return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
         }
@@ -381,7 +431,7 @@ class RandomAllocationStrategy : public AllocationStrategy {
         const auto num_segs = allocators->size();
         if (num_segs == 1) {
             // Fast path for single segment
-            return (*allocators)[0]->allocate(slice_length);
+            return (*allocators)[0]->Allocate(slice_length);
         }
 
         // Randomly select a start point to distribute
@@ -389,8 +439,9 @@ class RandomAllocationStrategy : public AllocationStrategy {
         // Select a start segment to place the replica.
         size_t seg_offset = randomIndex(num_segs);
         for (size_t i = 0; i < num_segs; i++) {  // only allocate one replica
-            auto& allocator = (*allocators)[(i + seg_offset) % num_segs];
-            if (auto buffer = allocator->allocate(slice_length)) {
+            const auto& registration =
+                (*allocators)[(i + seg_offset) % num_segs];
+            if (auto buffer = registration->Allocate(slice_length)) {
                 return buffer;
             }
         }
@@ -403,38 +454,24 @@ class RandomAllocationStrategy : public AllocationStrategy {
 };
 
 /**
- * @brief Free-ratio-first allocation strategy.
- *
- * For each allocation of N replicas:
- * 1. Randomly sample min(2N, total) candidate segments from the eligible pool
- * 2. Query each candidate's free space, sort descending, pick the top N
- * 3. Try to allocate from these top-N segments
- * 4. If insufficient replicas are allocated, fallback to the base Random
- *    strategy for the remaining replicas
+ * @brief Shared sampled-and-ranked placement algorithm.
  *
- * This achieves near-optimal load balancing with low overhead:
- * - Sampling 2N is O(N), sorting 2N is O(N log N) — both small since N
- *   (replica count) is typically 1–3.
- * - New empty segments naturally win the comparison, getting filled quickly.
- * - Thread-safe: uses thread_local state for sampling, no shared mutable data.
+ * Derived strategies provide only the score for each candidate segment.
  */
-class FreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
-   public:
-    FreeRatioFirstAllocationStrategy() = default;
-
-    tl::expected<std::vector<Replica>, ErrorCode> Allocate(
+class RankedAllocationStrategy : public RandomAllocationStrategy {
+   protected:
+    template <typename ScoreFn>
+    tl::expected<std::vector<Replica>, ErrorCode> AllocateRanked(
         const AllocatorManager& allocator_manager, const size_t slice_length,
-        const size_t replica_num = 1,
-        const std::vector<std::string>& preferred_segments =
-            std::vector<std::string>(),
-        const std::set<std::string>& excluded_segments =
-            std::set<std::string>(),
-        const ReplicaType replica_type = ReplicaType::MEMORY) override {
+        const size_t replica_num,
+        const std::vector<std::string>& preferred_segments,
+        const std::set<std::string>& excluded_segments,
+        const ReplicaType replica_type, ScoreFn&& score) {
         if (slice_length == 0 || replica_num == 0) {
             return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
         }
 
-        const auto& names = allocator_manager.getNames();
+        const auto names = allocator_manager.getServingNames();
         if (names.empty()) {
             return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
         }
@@ -443,13 +480,11 @@ class FreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
         replicas.reserve(replica_num);
         std::set<std::string> used_segments;
 
-        // --- Handle preferred segments first (same as Random) ---
         for (const auto& preferred_segment : preferred_segments) {
             if (excluded_segments.contains(preferred_segment) ||
                 used_segments.contains(preferred_segment)) {
                 continue;
             }
-
             auto buffer = allocateSingle(allocator_manager, preferred_segment,
                                          slice_length);
             if (buffer) {
@@ -463,48 +498,35 @@ class FreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
         }
 
         const size_t remaining = replica_num - replicas.size();
-
-        // --- Sample candidates: pick a random start, take 6*remaining
-        // consecutive segments, then sort by free space ---
-        size_t sample_count =
+        const size_t sample_count =
             std::min(kCandidateMultiplier * remaining, names.size());
-
-        size_t start_idx = randomIndex(names.size());
+        const size_t start_idx = randomIndex(names.size());
 
         struct Candidate {
             size_t name_idx;
-            double free_ratio;  // free_bytes / capacity
+            double score;
         };
         std::vector<Candidate> candidates;
         candidates.reserve(sample_count);
-
         for (size_t i = 0; i < sample_count; ++i) {
-            size_t idx = (start_idx + i) % names.size();
-            double free_ratio =
-                getSegmentFreeRatio(allocator_manager, names[idx]);
-            candidates.push_back({idx, free_ratio});
+            const size_t idx = (start_idx + i) % names.size();
+            const auto& name = names[idx];
+            if (excluded_segments.contains(name) ||
+                used_segments.contains(name)) {
+                continue;
+            }
+            candidates.push_back({idx, score(name)});
         }
 
-        // Sort by free space ratio descending
         std::sort(candidates.begin(), candidates.end(),
-                  [](const Candidate& a, const Candidate& b) {
-                      return a.free_ratio > b.free_ratio;
+                  [](const Candidate& lhs, const Candidate& rhs) {
+                      return lhs.score > rhs.score;
                   });
-
-        // Try to allocate from top candidates, skip excluded/used segments
         for (const auto& candidate : candidates) {
             if (replicas.size() >= replica_num) {
                 break;
             }
-
             const auto& name = names[candidate.name_idx];
-
-            // Skip excluded and used segments
-            if (excluded_segments.contains(name) ||
-                used_segments.contains(name)) {
-                continue;
-            }
-
             auto buffer = allocateSingle(allocator_manager, name, slice_length);
             if (buffer) {
                 replicas.emplace_back(std::move(buffer),
@@ -517,28 +539,23 @@ class FreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
             return replicas;
         }
 
-        // --- Fallback: Random allocation for any remaining replicas ---
         size_t fallback_idx = randomIndex(names.size());
         const size_t max_retry = std::min(kMaxRetryLimit, names.size());
         size_t try_count = 0;
-
         while (replicas.size() < replica_num && try_count < max_retry) {
-            auto index = fallback_idx % names.size();
-            fallback_idx++;
-            try_count++;
-
-            // Skip excluded and used segments
-            if (excluded_segments.contains(names[index]) ||
-                used_segments.contains(names[index])) {
+            const size_t index = fallback_idx % names.size();
+            ++fallback_idx;
+            ++try_count;
+            const auto& name = names[index];
+            if (excluded_segments.contains(name) ||
+                used_segments.contains(name)) {
                 continue;
             }
-
-            auto buffer =
-                allocateSingle(allocator_manager, names[index], slice_length);
+            auto buffer = allocateSingle(allocator_manager, name, slice_length);
             if (buffer) {
                 replicas.emplace_back(std::move(buffer),
                                       ReplicaStatus::PROCESSING, replica_type);
-                used_segments.insert(names[index]);
+                used_segments.insert(name);
             }
         }
 
@@ -551,168 +568,81 @@ class FreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
    private:
     static constexpr size_t kMaxRetryLimit = 100;
     static constexpr size_t kCandidateMultiplier = 6;
-
-    double getSegmentFreeRatio(const AllocatorManager& allocator_manager,
-                               const std::string& name) {
-        auto allocators = allocator_manager.getAllocators(name);
-        if (!allocators || allocators->empty()) return 0.0;
-
-        uint64_t total_capacity = 0;
-        uint64_t total_free = 0;
-        for (const auto& alloc : *allocators) {
-            if (!alloc) continue;
-            auto cap = static_cast<uint64_t>(alloc->capacity());
-            total_capacity += cap;
-            total_free += cap - static_cast<uint64_t>(alloc->size());
-        }
-
-        if (total_capacity == 0) return 0.0;
-        return static_cast<double>(total_free) /
-               static_cast<double>(total_capacity);
-    }
 };
 
-class SsdFreeRatioFirstAllocationStrategy : public RandomAllocationStrategy {
+class FreeRatioFirstAllocationStrategy final : public RankedAllocationStrategy {
    public:
-    SsdFreeRatioFirstAllocationStrategy() = default;
-
     tl::expected<std::vector<Replica>, ErrorCode> Allocate(
         const AllocatorManager& allocator_manager, const size_t slice_length,
-        const size_t replica_num,
-        const std::vector<std::string>& preferred_segments,
-        const std::set<std::string>& excluded_segments,
-        const ReplicaType replica_type,
-        const SsdMetricsProvider* ssd_provider) override {
-        if (slice_length == 0 || replica_num == 0) {
-            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
-        }
-
-        const auto& names = allocator_manager.getNames();
-        if (names.empty()) {
-            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
-        }
-
-        std::vector<Replica> replicas;
-        replicas.reserve(replica_num);
-        std::set<std::string> used_segments;
-
-        // Handle preferred segments first
-        for (const auto& preferred_segment : preferred_segments) {
-            if (excluded_segments.contains(preferred_segment) ||
-                used_segments.contains(preferred_segment)) {
-                continue;
-            }
+        const size_t replica_num = 1,
+        const std::vector<std::string>& preferred_segments =
+            std::vector<std::string>(),
+        const std::set<std::string>& excluded_segments =
+            std::set<std::string>(),
+        const ReplicaType replica_type = ReplicaType::MEMORY) override {
+        return AllocateRanked(
+            allocator_manager, slice_length, replica_num, preferred_segments,
+            excluded_segments, replica_type, [&](const std::string& name) {
+                return GetSegmentFreeRatio(allocator_manager, name);
+            });
+    }
 
-            auto buffer = allocateSingle(allocator_manager, preferred_segment,
-                                         slice_length);
-            if (buffer) {
-                replicas.emplace_back(std::move(buffer),
-                                      ReplicaStatus::PROCESSING, replica_type);
-                used_segments.insert(preferred_segment);
-                if (replicas.size() == replica_num) {
-                    return replicas;
-                }
-            }
+   private:
+    static double GetSegmentFreeRatio(const AllocatorManager& allocator_manager,
+                                      const std::string& name) {
+        const auto* allocators = allocator_manager.getAllocators(name);
+        if (!allocators || allocators->empty()) {
+            return 0.0;
         }
 
-        const size_t remaining = replica_num - replicas.size();
-
-        // Sample candidates and sort by SSD free ratio
-        size_t sample_count =
-            std::min(kCandidateMultiplier * remaining, names.size());
-
-        size_t start_idx = randomIndex(names.size());
-
-        struct Candidate {
-            size_t name_idx;
-            double ssd_free_ratio;
-        };
-        std::vector<Candidate> candidates;
-        candidates.reserve(sample_count);
-
-        for (size_t i = 0; i < sample_count; ++i) {
-            size_t idx = (start_idx + i) % names.size();
-            const auto& name = names[idx];
-
-            if (excluded_segments.contains(name) ||
-                used_segments.contains(name)) {
+        uint64_t total_capacity = 0;
+        uint64_t total_free = 0;
+        for (const auto& registration : *allocators) {
+            if (!registration->IsServing()) {
                 continue;
             }
-
-            double ssd_free_ratio = getSegmentSsdFreeRatio(name, ssd_provider);
-            candidates.push_back({idx, ssd_free_ratio});
+            const auto buffer_allocator = registration->GetAllocator();
+            const auto capacity =
+                static_cast<uint64_t>(buffer_allocator->capacity());
+            total_capacity += capacity;
+            total_free +=
+                capacity - static_cast<uint64_t>(buffer_allocator->size());
         }
-
-        std::sort(candidates.begin(), candidates.end(),
-                  [](const Candidate& a, const Candidate& b) {
-                      return a.ssd_free_ratio > b.ssd_free_ratio;
-                  });
-
-        for (const auto& candidate : candidates) {
-            if (replicas.size() >= replica_num) {
-                break;
-            }
-
-            const auto& name = names[candidate.name_idx];
-            auto buffer = allocateSingle(allocator_manager, name, slice_length);
-            if (buffer) {
-                replicas.emplace_back(std::move(buffer),
-                                      ReplicaStatus::PROCESSING, replica_type);
-                used_segments.insert(name);
-            }
+        if (total_capacity == 0) {
+            return 0.0;
         }
+        return static_cast<double>(total_free) /
+               static_cast<double>(total_capacity);
+    }
+};
 
-        if (replicas.size() >= replica_num) {
-            return replicas;
-        }
-
-        // Fallback: Random allocation for remaining replicas
-        size_t fallback_idx = randomIndex(names.size());
-        const size_t max_retry = std::min(kMaxRetryLimit, names.size());
-        size_t try_count = 0;
-
-        while (replicas.size() < replica_num && try_count < max_retry) {
-            auto index = fallback_idx % names.size();
-            fallback_idx++;
-            try_count++;
-
-            const auto& name = names[index];
-
-            if (excluded_segments.contains(name) ||
-                used_segments.contains(name)) {
-                continue;
-            }
-
-            auto buffer = allocateSingle(allocator_manager, name, slice_length);
-            if (buffer) {
-                replicas.emplace_back(std::move(buffer),
-                                      ReplicaStatus::PROCESSING, replica_type);
-                used_segments.insert(name);
-            }
-        }
+class SsdFreeRatioFirstAllocationStrategy final
+    : public RankedAllocationStrategy {
+   public:
+    explicit SsdFreeRatioFirstAllocationStrategy(
+        const LocalSsdManager& local_ssd)
+        : local_ssd_(local_ssd) {}
 
-        if (replicas.empty()) {
-            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
-        }
-        return replicas;
-    }
+    tl::expected<std::vector<Replica>, ErrorCode> Allocate(
+        const ScopedAllocatorAccess& placement, const size_t slice_length,
+        const size_t replica_num = 1,
+        const std::vector<std::string>& preferred_segments =
+            std::vector<std::string>(),
+        const std::set<std::string>& excluded_segments =
+            std::set<std::string>(),
+        const ReplicaType replica_type = ReplicaType::MEMORY) override;
 
-    using AllocationStrategy::Allocate;
+    tl::expected<std::vector<Replica>, ErrorCode> Allocate(
+        const AllocatorManager& allocator_manager, const size_t slice_length,
+        const size_t replica_num = 1,
+        const std::vector<std::string>& preferred_segments =
+            std::vector<std::string>(),
+        const std::set<std::string>& excluded_segments =
+            std::set<std::string>(),
+        const ReplicaType replica_type = ReplicaType::MEMORY) override;
 
    private:
-    static constexpr size_t kMaxRetryLimit = 100;
-    static constexpr size_t kCandidateMultiplier = 6;
-
-    double getSegmentSsdFreeRatio(
-        const std::string& name, const SsdMetricsProvider* ssd_provider) const {
-        if (!ssd_provider) return 1.0;
-        int64_t total = ssd_provider->getSsdTotalCapacity(name);
-        if (total <= 0) return 1.0;
-        int64_t used = ssd_provider->getSsdUsedBytes(name);
-        used = std::clamp<int64_t>(used, 0, total);
-        int64_t free_bytes = total - used;
-        return static_cast<double>(free_bytes) / static_cast<double>(total);
-    }
+    const LocalSsdManager& local_ssd_;
 };
 
 class CxlAllocationStrategy : public AllocationStrategy {
@@ -745,17 +675,18 @@ class CxlAllocationStrategy : public AllocationStrategy {
         if (cxl_allocators == nullptr || cxl_allocators->size() == 0) {
             return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
         }
-        std::shared_ptr<BufferAllocatorBase> cxl_allocator =
-            (*cxl_allocators)[0];
-        if (!cxl_allocator) {
-            LOG(ERROR) << "No CXL allocator in preferred_segment";
-            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
-        }
-
         std::vector<Replica> replicas;
         replicas.reserve(replica_num);
 
-        auto buffer = cxl_allocator->allocate(slice_length);
+        std::unique_ptr<AllocatedBuffer> buffer;
+        for (const auto& registration : *cxl_allocators) {
+            if (registration->IsServing()) {
+                buffer = registration->Allocate(slice_length);
+                if (buffer) {
+                    break;
+                }
+            }
+        }
         if (!buffer) {
             return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
         }
@@ -780,7 +711,7 @@ class CxlAllocationStrategy : public AllocationStrategy {
  * @brief Factory function to create allocation strategy based on type
  */
 inline std::shared_ptr<AllocationStrategy> CreateAllocationStrategy(
-    AllocationStrategyType type) {
+    AllocationStrategyType type, const LocalSsdManager& local_ssd) {
     switch (type) {
         case AllocationStrategyType::RANDOM:
             return std::make_shared<RandomAllocationStrategy>();
@@ -789,7 +720,8 @@ inline std::shared_ptr<AllocationStrategy> CreateAllocationStrategy(
         case AllocationStrategyType::CXL:
             return std::make_shared<CxlAllocationStrategy>();
         case AllocationStrategyType::SSD_FREE_RATIO_FIRST:
-            return std::make_shared<SsdFreeRatioFirstAllocationStrategy>();
+            return std::make_shared<SsdFreeRatioFirstAllocationStrategy>(
+                local_ssd);
         case AllocationStrategyType::LOCAL_FIRST:
             return std::make_shared<RandomAllocationStrategy>();
         default:
diff --git a/mooncake-store/include/allocator.h b/mooncake-store/include/allocator.h
index e0321f5c6f..a231841596 100644
--- a/mooncake-store/include/allocator.h
+++ b/mooncake-store/include/allocator.h
@@ -2,13 +2,18 @@
 #define BUFFER_ALLOCATOR_H
 
 #include <atomic>
+#include <cstdint>
 #include <limits>
 #include <memory>
 #include <string>
 #include <vector>
 
+#include <ylt/util/tl/expected.hpp>
+
 #include "cachelib_memory_allocator/MemoryAllocator.h"
+#include "client_liveness.h"
 #include "offset_allocator/offset_allocator.h"
+#include "storage_usage.h"
 #include "types.h"
 
 using facebook::cachelib::MemoryAllocator;
@@ -20,11 +25,17 @@ namespace mooncake {
  * @brief Type of buffer allocator used in the system
  */
 enum class ReplicaType {
-    MEMORY,      // Memory replica
-    DISK,        // Disk replica
-    LOCAL_DISK,  // Local disk replica
-    NOF_SSD,     // Nvme-oF SSD replica
-    ALL,         // All memory and NoF replicas in put finalize path
+    MEMORY = 0,      // Memory replica
+    DISK = 1,        // Disk replica
+    LOCAL_DISK = 2,  // Local disk replica
+    NOF_SSD = 3,     // Nvme-oF SSD replica
+    ALL = 4,         // All synchronous replicas in put finalize path
+    DFS = 100,       // Distributed filesystem page-offset replica
+};
+
+struct LiveAllocation {
+    uint64_t offset_from_base{0};
+    uint64_t requested_size{0};
 };
 
 // Constant for unknown free space in allocators that don't track it precisely
@@ -33,6 +44,28 @@ static constexpr size_t kAllocatorUnknownFreeSpace =
 
 // Forward declarations
 class BufferAllocatorBase;
+class Replica;
+class SegmentAllocatorRegistration;
+
+class SegmentLifetime {
+   public:
+    SegmentLifetime() : available_(std::make_shared<std::atomic<bool>>(true)) {}
+
+    [[nodiscard]] bool isAvailable() const {
+        return available_->load(std::memory_order_acquire);
+    }
+
+    void setAvailable(bool available) const {
+        available_->store(available, std::memory_order_release);
+    }
+
+    [[nodiscard]] bool operator==(const SegmentLifetime& other) const {
+        return available_ == other.available_;
+    }
+
+   private:
+    std::shared_ptr<std::atomic<bool>> available_;
+};
 
 class AllocatedBuffer {
    public:
@@ -65,7 +98,37 @@ class AllocatedBuffer {
     [[nodiscard]] std::size_t size() const noexcept { return this->size_; }
 
     [[nodiscard]] bool isAllocatorValid() const {
-        return !allocator_.expired();
+        return !allocator_.expired() && segment_lifetime_.isAvailable();
+    }
+
+    [[nodiscard]] std::shared_ptr<BufferAllocatorBase> getAllocator() const {
+        return allocator_.lock();
+    }
+
+    [[nodiscard]] bool isAvailable() const {
+        if (!isAllocatorValid()) {
+            return false;
+        }
+        const auto record = std::atomic_load_explicit(
+            &client_liveness_, std::memory_order_acquire);
+        return !record || record->IsServing();
+    }
+
+    void bindClientLiveness(
+        std::shared_ptr<ClientLivenessRecord> client_liveness) {
+        std::atomic_store_explicit(&client_liveness_,
+                                   std::move(client_liveness),
+                                   std::memory_order_release);
+    }
+
+    void bindSegmentLifetime(SegmentLifetime lifetime) {
+        segment_lifetime_ = std::move(lifetime);
+    }
+
+    [[nodiscard]] std::shared_ptr<ClientLivenessRecord> getClientLiveness()
+        const {
+        return std::atomic_load_explicit(&client_liveness_,
+                                         std::memory_order_acquire);
     }
 
     // Serialize the buffer into a descriptor for transfer
@@ -91,7 +154,11 @@ class AllocatedBuffer {
     void* get_vaddr_from_cxl();
 
    private:
+    bool copyTransferProtocolFrom(const AllocatedBuffer& source);
+
     std::weak_ptr<BufferAllocatorBase> allocator_;
+    SegmentLifetime segment_lifetime_;
+    std::shared_ptr<ClientLivenessRecord> client_liveness_;
     std::string segment_name_;
     void* buffer_ptr_{nullptr};
     std::size_t size_{0};
@@ -101,6 +168,8 @@ class AllocatedBuffer {
         std::nullopt};
 
     friend class Serializer<AllocatedBuffer>;
+    friend class Replica;
+    friend class SegmentAllocatorRegistration;
 };
 
 /**
@@ -115,6 +184,7 @@ class BufferAllocatorBase {
     virtual void deallocate(AllocatedBuffer* handle) = 0;
     virtual size_t capacity() const = 0;
     virtual size_t size() const = 0;
+    virtual uintptr_t base() const = 0;
     virtual std::string getSegmentName() const = 0;
     virtual std::string getTransportEndpoint() const = 0;
 
@@ -128,6 +198,28 @@ class BufferAllocatorBase {
      * allocation may still fail due to race conditions or fragmentation.
      */
     virtual size_t getLargestFreeRegion() const = 0;
+
+    /**
+     * Attach this allocator to a domain usage tracker exactly once, before it
+     * is published. Registration is immutable afterward and is released by
+     * RAII when the last shared_ptr to the allocator is dropped.
+     */
+    void AttachUsageTracker(
+        const std::shared_ptr<StorageUsageTracker>& usage_tracker);
+
+   protected:
+    [[nodiscard]] size_t GetUsageBytes() const noexcept {
+        return cur_size_.load(std::memory_order_relaxed);
+    }
+    void RecordAllocation(size_t bytes) noexcept;
+    void RecordDeallocation(size_t bytes) noexcept;
+    void SetUsageBytesForRestore(size_t bytes) noexcept {
+        cur_size_.store(bytes, std::memory_order_relaxed);
+    }
+
+   private:
+    std::atomic_size_t cur_size_{0};
+    std::unique_ptr<StorageUsageRegistration> usage_registration_;
 };
 
 /**
@@ -151,6 +243,7 @@ class DummyBufferAllocator final : public BufferAllocatorBase {
         return kAllocatorUnknownFreeSpace;
     }
     size_t size() const override { return 0; }
+    uintptr_t base() const override { return 0; }
     std::string getSegmentName() const override { return segment_name_; }
     std::string getTransportEndpoint() const override {
         return transport_endpoint_;
@@ -165,12 +258,7 @@ class DummyBufferAllocator final : public BufferAllocatorBase {
  * CachelibBufferAllocator manages memory allocation using CacheLib's slab
  * allocation strategy.
  *
- * Important alignment requirements:
- * 1. Base address must be at least 8-byte aligned (CacheLib requirement)
- * 2. Base address should be 4MB aligned since the total size must be a multiple
- * of 4MB
- * 3. Use sufficiently high base addresses (e.g., 0x100000000 for 4GB) to avoid
- * memory conflicts
+ * The base address and size must both be aligned to CacheLib's slab size.
  *
  * Example usage:
  * ```cpp
@@ -178,7 +266,7 @@ class DummyBufferAllocator final : public BufferAllocatorBase {
  * const size_t base = 0x100000000;  // 4GB aligned
  * const size_t base = 0x200000000;  // 8GB aligned
  *
- * // Bad - will likely crash
+ * // Bad - Create() returns ErrorCode::INVALID_PARAMS
  * const size_t base = 0x1234;       // Too low, unaligned
  * const size_t base = 0x100000001;  // Not 4MB aligned
  * ```
@@ -187,9 +275,10 @@ class CachelibBufferAllocator
     : public BufferAllocatorBase,
       public std::enable_shared_from_this<CachelibBufferAllocator> {
    public:
-    CachelibBufferAllocator(std::string segment_name, size_t base, size_t size,
-                            std::string transport_endpoint,
-                            ReplicaType replica_type = ReplicaType::MEMORY);
+    static tl::expected<std::shared_ptr<CachelibBufferAllocator>, ErrorCode>
+    Create(std::string segment_name, size_t base, size_t size,
+           std::string transport_endpoint,
+           ReplicaType replica_type = ReplicaType::MEMORY);
 
     ~CachelibBufferAllocator() override;
 
@@ -198,7 +287,8 @@ class CachelibBufferAllocator
     void deallocate(AllocatedBuffer* handle) override;
 
     size_t capacity() const override { return total_size_; }
-    size_t size() const override { return cur_size_.load(); }
+    size_t size() const override { return GetUsageBytes(); }
+    uintptr_t base() const override { return base_; }
     std::string getSegmentName() const override { return segment_name_; }
     std::string getTransportEndpoint() const override {
         return transport_endpoint_;
@@ -214,13 +304,16 @@ class CachelibBufferAllocator
     }
 
    private:
+    CachelibBufferAllocator(std::string segment_name, size_t base, size_t size,
+                            std::string transport_endpoint,
+                            ReplicaType replica_type);
+
     std::unique_ptr<AllocatedBuffer> adoptImportedBuffer(
-        const AllocatedBuffer::Descriptor& descriptor);
+        const LiveAllocation& allocation);
     // metadata
     const std::string segment_name_;
     const size_t base_;
     const size_t total_size_;
-    std::atomic_size_t cur_size_;
     const std::string transport_endpoint_;
     const ReplicaType replica_type_;
 
@@ -234,10 +327,10 @@ class CachelibBufferAllocator
 
     friend struct RestoredCachelibBufferAllocator;
     friend std::optional<struct RestoredCachelibBufferAllocator>
-    RestoreCachelibBufferAllocator(
+    ImportCachelibBufferAllocator(
         std::string segment_name, size_t base, size_t size,
         std::string transport_endpoint,
-        const std::vector<AllocatedBuffer::Descriptor>& descriptors,
+        const std::vector<LiveAllocation>& allocations,
         ReplicaType replica_type);
 };
 
@@ -246,12 +339,32 @@ struct RestoredCachelibBufferAllocator {
     std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
 };
 
-std::optional<RestoredCachelibBufferAllocator> RestoreCachelibBufferAllocator(
+std::optional<RestoredCachelibBufferAllocator> ImportCachelibBufferAllocator(
     std::string segment_name, size_t base, size_t size,
     std::string transport_endpoint,
-    const std::vector<AllocatedBuffer::Descriptor>& descriptors,
+    const std::vector<LiveAllocation>& allocations,
     ReplicaType replica_type = ReplicaType::MEMORY);
 
+// A detached capture of host-memory allocator metadata; owns no live allocator
+// and contributes neither usage nor capacity metrics.
+struct OffsetBufferAllocatorSnapshot {
+    std::string segment_name;
+    size_t base;
+    size_t capacity;
+    size_t used_bytes;
+    std::string transport_endpoint;
+    offset_allocator::OffsetAllocatorSnapshot allocation_state;
+
+    // Validate the detached snapshot without publishing resources or metrics.
+    [[nodiscard]] tl::expected<void, std::string> Validate() const;
+
+   private:
+    tl::expected<void, std::string> ValidateMetadata() const;
+    // Restore composes this cheap outer check with OffsetAllocator::Restore's
+    // mandatory layout validation, avoiding two graph scans in one factory.
+    friend class OffsetBufferAllocator;
+};
+
 /**
  * OffsetBufferAllocator manages memory allocation using the OffsetAllocator
  * strategy, which provides efficient memory allocation with bin-based
@@ -267,12 +380,25 @@ class OffsetBufferAllocator
 
     ~OffsetBufferAllocator() override;
 
+    // Restore an unpublished allocator from decoded state. Installs the
+    // allocation layout and accounts usage before returning a runtime-ready
+    // object; capacity accounting remains the owning pool's responsibility.
+    // Consumes the snapshot and rejects inconsistent state with
+    // ErrorCode::INVALID_PARAMS.
+    static tl::expected<std::shared_ptr<OffsetBufferAllocator>, ErrorCode>
+    Restore(OffsetBufferAllocatorSnapshot snapshot);
+
+    // Requires a forked snapshot child or externally quiesced state. Does not
+    // acquire inherited runtime locks; copies all state needed by the codec.
+    OffsetBufferAllocatorSnapshot CaptureSnapshot() const;
+
     std::unique_ptr<AllocatedBuffer> allocate(size_t size) override;
 
     void deallocate(AllocatedBuffer* handle) override;
 
     size_t capacity() const override { return total_size_; }
-    size_t size() const override { return cur_size_.load(); }
+    size_t size() const override { return GetUsageBytes(); }
+    uintptr_t base() const override { return base_; }
     std::string getSegmentName() const override { return segment_name_; }
     std::string getTransportEndpoint() const override {
         return transport_endpoint_;
@@ -290,28 +416,19 @@ class OffsetBufferAllocator
     }
 
    private:
+    OffsetBufferAllocator(
+        OffsetBufferAllocatorSnapshot snapshot,
+        std::shared_ptr<offset_allocator::OffsetAllocator> offset_allocator);
+
     // metadata
     const std::string segment_name_;
     const size_t base_;
     const size_t total_size_;
-    std::atomic_size_t cur_size_;
     const std::string transport_endpoint_;
     const ReplicaType replica_type_;
 
     // offset allocator implementation
     std::shared_ptr<offset_allocator::OffsetAllocator> offset_allocator_;
-
-    // Keeps address gaps occupied after descriptor-based reconstruction.
-    std::vector<std::unique_ptr<AllocatedBuffer>> restored_gap_buffers_;
-
-    friend class Serializer<OffsetBufferAllocator>;
-    friend struct RestoredOffsetBufferAllocator;
-    friend std::optional<struct RestoredOffsetBufferAllocator>
-    RestoreOffsetBufferAllocator(
-        std::string segment_name, size_t base, size_t size,
-        std::string transport_endpoint,
-        const std::vector<AllocatedBuffer::Descriptor>& descriptors,
-        ReplicaType replica_type);
 };
 
 struct RestoredOffsetBufferAllocator {
@@ -319,15 +436,21 @@ struct RestoredOffsetBufferAllocator {
     std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
 };
 
-// Reconstructs an empty OffsetBufferAllocator from final live descriptors.
-// The returned buffers follow descriptor input order. No state is exposed on
+// Reconstructs an empty OffsetBufferAllocator from final live allocations.
+// The returned buffers follow allocation input order. No state is exposed on
 // validation or allocation failure.
-std::optional<RestoredOffsetBufferAllocator> RestoreOffsetBufferAllocator(
+std::optional<RestoredOffsetBufferAllocator> ImportOffsetBufferAllocator(
     std::string segment_name, size_t base, size_t size,
     std::string transport_endpoint,
-    const std::vector<AllocatedBuffer::Descriptor>& descriptors,
+    const std::vector<LiveAllocation>& allocations,
     ReplicaType replica_type = ReplicaType::MEMORY);
 
+tl::expected<std::shared_ptr<BufferAllocatorBase>, ErrorCode>
+CreateBufferAllocator(BufferAllocatorType allocator_type,
+                      std::string segment_name, size_t base, size_t size,
+                      std::string transport_endpoint,
+                      ReplicaType replica_type = ReplicaType::MEMORY);
+
 // The main difference is that it allocates real memory and returns it, while
 // BufferAllocator allocates an address
 class SimpleAllocator {
diff --git a/mooncake-store/include/allocator_metric.h b/mooncake-store/include/allocator_metric.h
new file mode 100644
index 0000000000..06e6681e63
--- /dev/null
+++ b/mooncake-store/include/allocator_metric.h
@@ -0,0 +1,210 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <map>
+#include <mutex>
+#include <string>
+#include <vector>
+
+#include "hybrid_metric.h"
+#include "ylt/metric/counter.hpp"
+#include "ylt/metric/gauge.hpp"
+
+namespace mooncake {
+
+/**
+ * @brief Allocator counters sampled from jemalloc, in a library-friendly form.
+ *
+ * The struct deliberately names no jemalloc type: libmooncake_store never links
+ * the allocator, so the fields are filled by a collector installed from an
+ * executable that does. Page counts are converted to bytes by the collector,
+ * which is the side that knows the runtime page size.
+ */
+/**
+ * @brief One jemalloc small size class, as reported by the merged arena view.
+ *
+ * Occupancy is regs / (slabs * regs_per_slab): a slab is only returned to the
+ * OS once every region in it is free, so a class sitting at low occupancy is
+ * holding slab_bytes while only using used_bytes.
+ */
+struct JemallocBinStats {
+    uint64_t size = 0;
+    uint64_t regs_per_slab = 0;
+    uint64_t regs = 0;
+    uint64_t slabs = 0;
+};
+
+struct JemallocSnapshot {
+    // Instantaneous.
+    uint64_t allocated = 0;
+    uint64_t active = 0;
+    uint64_t metadata = 0;
+    uint64_t resident = 0;
+    uint64_t retained = 0;
+    uint64_t mapped = 0;
+    uint64_t small_allocated = 0;
+    uint64_t large_allocated = 0;
+    uint64_t dirty_bytes = 0;
+    uint64_t muzzy_bytes = 0;
+    uint64_t arenas = 0;
+    uint64_t background_threads = 0;
+    int64_t opt_dirty_decay_ms = 0;
+    int64_t opt_muzzy_decay_ms = 0;
+
+    // Cumulative since process start.
+    uint64_t dirty_purged_pages = 0;
+    uint64_t muzzy_purged_pages = 0;
+    uint64_t dirty_purge_runs = 0;
+    uint64_t muzzy_purge_runs = 0;
+    uint64_t dirty_madvises = 0;
+    uint64_t muzzy_madvises = 0;
+    uint64_t small_allocations = 0;
+    uint64_t small_deallocations = 0;
+
+    // One entry per small size class, in jemalloc's bin order.
+    std::vector<JemallocBinStats> bins;
+};
+
+using JemallocStatsCollector = bool (*)(JemallocSnapshot&);
+
+/**
+ * @brief Install the process-wide jemalloc stats collector.
+ *
+ * Called from the main() of a binary that links jemalloc, next to
+ * LogAllocatorStatus(). Without it the jemalloc series stay at zero and
+ * mooncake_jemalloc_enabled reports 0, which is the correct answer for a
+ * process running the system allocator, the Python extension included.
+ * Thread-safe; intended to be called once before worker threads start.
+ *
+ * @param collector Fills a JemallocSnapshot and returns whether it succeeded.
+ *                  Passing nullptr uninstalls the current collector.
+ */
+void SetJemallocStatsCollector(JemallocStatsCollector collector);
+
+// Forward declaration for cross-namespace friend access (test-only).
+namespace test {
+class AllocatorMetricTest;
+}  // namespace test
+
+/**
+ * @brief Process memory and allocator metrics, shared by master and client.
+ *
+ * Process figures come from /proc/self/status and are reported whichever
+ * allocator is linked, so the series stay comparable across a glibc/jemalloc
+ * switch. They are the ground truth the allocator series are read against:
+ * mooncake_jemalloc_resident_bytes is jemalloc's own upper estimate over the
+ * extents it maps and can exceed the resident size the kernel reports, so the
+ * two are compared for divergence rather than subtracted.
+ */
+class AllocatorMetric {
+   public:
+    /**
+     * @param labels Static labels applied to every series, matching the
+     *               convention of the sibling client metric structs.
+     */
+    explicit AllocatorMetric(
+        const std::map<std::string, std::string>& labels = {});
+
+    /**
+     * @brief Re-sample the process and, when installed, the collector.
+     *
+     * Advancing the jemalloc epoch takes a lock shared with allocating threads,
+     * so samples closer together than kMinRefreshInterval reuse the values
+     * already published rather than let an unauthenticated /metrics endpoint
+     * drive the rate.
+     * Thread-safe: concurrent scrapes serialize, and only one of them advances
+     * the cumulative counters.
+     */
+    void Refresh();
+
+    /**
+     * @brief Append the metrics in Prometheus text format.
+     *
+     * Does not sample; call Refresh() first. Named to match the sibling metric
+     * structs, whose serialize() chains this one is spliced into.
+     */
+    void serialize(std::string& str);
+
+    /**
+     * @brief Render a short human-readable digest for /metrics/summary.
+     */
+    std::string summary_metrics();
+
+   private:
+    friend class ::mooncake::test::AllocatorMetricTest;
+
+    // A scrape interval is 15s in every deployment, so this only bounds the
+    // cost of a hand-driven or looping scraper.
+    static constexpr std::chrono::milliseconds kMinRefreshInterval{1000};
+
+    // ylt drops a metric that still holds its untouched zero, so every series
+    // is marked once here or it is missing from a fresh process.
+    void MarkAllForZeroOutput();
+
+    void RefreshLocked();
+    void RefreshProcess();
+    void RefreshJemalloc();
+
+    // jemalloc publishes cumulative totals while a ylt counter only accepts
+    // increments, so every counter advances by the difference from the previous
+    // sample. Guarded by refresh_mutex_.
+    void AdvanceCounter(ylt::metric::counter_t& counter, uint64_t total,
+                        uint64_t& previous);
+
+    std::mutex refresh_mutex_;
+    // Left at the clock epoch so that the first Refresh() is never throttled.
+    std::chrono::steady_clock::time_point last_refresh_{};
+
+    ylt::metric::gauge_t process_rss_;
+    ylt::metric::gauge_t process_rss_peak_;
+    ylt::metric::gauge_t process_rss_anon_;
+    ylt::metric::gauge_t process_rss_file_;
+    ylt::metric::gauge_t process_rss_shmem_;
+    ylt::metric::gauge_t process_vsize_;
+    ylt::metric::gauge_t process_swap_;
+
+    ylt::metric::gauge_t jemalloc_enabled_;
+    ylt::metric::gauge_t jemalloc_allocated_;
+    ylt::metric::gauge_t jemalloc_active_;
+    ylt::metric::gauge_t jemalloc_metadata_;
+    ylt::metric::gauge_t jemalloc_resident_;
+    ylt::metric::gauge_t jemalloc_retained_;
+    ylt::metric::gauge_t jemalloc_mapped_;
+    ylt::metric::gauge_t jemalloc_small_allocated_;
+    ylt::metric::gauge_t jemalloc_large_allocated_;
+    ylt::metric::gauge_t jemalloc_dirty_;
+    ylt::metric::gauge_t jemalloc_muzzy_;
+    ylt::metric::gauge_t jemalloc_arenas_;
+    ylt::metric::gauge_t jemalloc_background_threads_;
+    ylt::metric::gauge_t jemalloc_opt_dirty_decay_ms_;
+    ylt::metric::gauge_t jemalloc_opt_muzzy_decay_ms_;
+
+    ylt::metric::counter_t jemalloc_dirty_purged_pages_;
+    ylt::metric::counter_t jemalloc_muzzy_purged_pages_;
+    ylt::metric::counter_t jemalloc_dirty_purge_runs_;
+    ylt::metric::counter_t jemalloc_muzzy_purge_runs_;
+    ylt::metric::counter_t jemalloc_dirty_madvises_;
+    ylt::metric::counter_t jemalloc_muzzy_madvises_;
+    ylt::metric::counter_t jemalloc_small_allocations_;
+    ylt::metric::counter_t jemalloc_small_deallocations_;
+
+    uint64_t prev_dirty_purged_pages_ = 0;
+    uint64_t prev_muzzy_purged_pages_ = 0;
+    uint64_t prev_dirty_purge_runs_ = 0;
+    uint64_t prev_muzzy_purge_runs_ = 0;
+    uint64_t prev_dirty_madvises_ = 0;
+    uint64_t prev_muzzy_madvises_ = 0;
+    uint64_t prev_small_allocations_ = 0;
+    uint64_t prev_small_deallocations_ = 0;
+
+    // Unlike the scalar series these carry a label, so they cannot be marked
+    // for zero output ahead of the first sample: a labelled metric has no
+    // values until one is written.
+    ylt::metric::hybrid_gauge_1t jemalloc_bin_regs_;
+    ylt::metric::hybrid_gauge_1t jemalloc_bin_slabs_;
+    ylt::metric::hybrid_gauge_1t jemalloc_bin_used_bytes_;
+    ylt::metric::hybrid_gauge_1t jemalloc_bin_slab_bytes_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/allocator_status.h b/mooncake-store/include/allocator_status.h
new file mode 100644
index 0000000000..c0c258361d
--- /dev/null
+++ b/mooncake-store/include/allocator_status.h
@@ -0,0 +1,232 @@
+#pragma once
+
+#include <glog/logging.h>
+
+#include "allocator_metric.h"
+
+#ifdef STORE_USE_JEMALLOC
+#include <jemalloc/jemalloc.h>
+#include <sys/types.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#endif
+
+namespace mooncake {
+
+#ifdef STORE_USE_JEMALLOC
+
+template <typename T>
+inline bool ReadJemallocKnob(const char* name, T& value) {
+    size_t size = sizeof(value);
+    return mallctl(name, &value, &size, nullptr, 0) == 0;
+}
+
+/**
+ * @brief Log the jemalloc version and decay tuning once at process startup.
+ *
+ * The release binaries are stripped, so this line is the only evidence that
+ * jemalloc actually replaced the system allocator: mallctl resolves only when
+ * jemalloc is linked in, and glibc exposes no equivalent knob.
+ * The thread count comes from stats rather than opt.background_thread so that
+ * a background thread that failed to spawn is distinguishable from one that
+ * was merely requested.
+ * Not thread-safe with respect to other allocator tuning; call before spawning
+ * worker threads.
+ */
+inline void LogAllocatorStatus() {
+    const char* version = "unknown";
+    ReadJemallocKnob("version", version);
+
+    bool background_thread = false;
+    ReadJemallocKnob("background_thread", background_thread);
+
+    // stats.* report the snapshot published by the last epoch advance, so a
+    // read without this write would return the counters from process start.
+    uint64_t epoch = 1;
+    mallctl("epoch", nullptr, nullptr, &epoch, sizeof(epoch));
+
+    size_t background_threads = 0;
+    ReadJemallocKnob("stats.background_thread.num_threads", background_threads);
+
+    // Decay knobs are signed: -1 means the arena never purges.
+    ssize_t dirty_decay_ms = 0;
+    ReadJemallocKnob("opt.dirty_decay_ms", dirty_decay_ms);
+    ssize_t muzzy_decay_ms = 0;
+    ReadJemallocKnob("opt.muzzy_decay_ms", muzzy_decay_ms);
+
+    LOG(INFO) << "Allocator: jemalloc " << version
+              << ", background_thread=" << (background_thread ? "on" : "off")
+              << ", background_threads=" << background_threads
+              << ", dirty_decay_ms=" << dirty_decay_ms
+              << ", muzzy_decay_ms=" << muzzy_decay_ms;
+}
+
+/**
+ * @brief Read one knob of the arena-merged statistics view.
+ *
+ * jemalloc reserves the arena index MALLCTL_ARENAS_ALL for a merged view, so a
+ * single read replaces a loop over arenas.narenas.
+ */
+template <typename T>
+inline bool ReadMergedArenaKnob(const char* suffix, T& value) {
+    const std::string name =
+        "stats.arenas." + std::to_string(MALLCTL_ARENAS_ALL) + "." + suffix;
+    return ReadJemallocKnob(name.c_str(), value);
+}
+
+/**
+ * @brief Fill a JemallocSnapshot from mallctl, for SetJemallocStatsCollector.
+ *
+ * Every stats.* knob returns the values published by the last epoch advance, so
+ * the epoch is written first. Collection fails as a whole rather than partially
+ * when the allocator cannot answer, because a partial snapshot is indis-
+ * tinguishable on a dashboard from a healthy one that happens to read zero.
+ * Not thread-safe against allocator tuning, and the epoch advance takes a lock
+ * shared with allocating threads, so callers must rate-limit.
+ *
+ * @param snapshot Overwritten field by field on success, including its bin
+ *                 vector, so the same instance can be sampled repeatedly. Left
+ *                 untouched when the epoch write fails.
+ * @return false when the epoch could not be advanced.
+ */
+inline bool CollectJemallocStats(JemallocSnapshot& snapshot) {
+    // A build without --enable-stats still answers the epoch write, so without
+    // this check every stats.* read would fail and the whole snapshot would
+    // report a plausible-looking zero.
+    bool stats_enabled = false;
+    if (!ReadJemallocKnob("config.stats", stats_enabled) || !stats_enabled) {
+        return false;
+    }
+
+    uint64_t epoch = 1;
+    if (mallctl("epoch", nullptr, nullptr, &epoch, sizeof(epoch)) != 0) {
+        return false;
+    }
+
+    // Dirty and muzzy are reported in pages, so a missing page size would turn
+    // both into a silent zero that reads as "nothing awaiting decay".
+    size_t page_size = 0;
+    if (!ReadJemallocKnob("arenas.page", page_size) || page_size == 0) {
+        return false;
+    }
+
+    // Every size is read into the width jemalloc declares for it; mallctl
+    // rejects a mismatched width outright rather than converting.
+    auto read_size = [](const char* name, uint64_t& out) {
+        size_t value = 0;
+        if (ReadJemallocKnob(name, value)) {
+            out = value;
+        }
+    };
+    auto read_merged_size = [](const char* suffix, uint64_t& out) {
+        size_t value = 0;
+        if (ReadMergedArenaKnob(suffix, value)) {
+            out = value;
+        }
+    };
+    auto read_merged_u64 = [](const char* suffix, uint64_t& out) {
+        uint64_t value = 0;
+        if (ReadMergedArenaKnob(suffix, value)) {
+            out = value;
+        }
+    };
+
+    read_size("stats.allocated", snapshot.allocated);
+    read_size("stats.active", snapshot.active);
+    read_size("stats.metadata", snapshot.metadata);
+    read_size("stats.resident", snapshot.resident);
+    read_size("stats.retained", snapshot.retained);
+    read_size("stats.mapped", snapshot.mapped);
+    read_size("stats.background_thread.num_threads",
+              snapshot.background_threads);
+
+    read_merged_size("small.allocated", snapshot.small_allocated);
+    read_merged_size("large.allocated", snapshot.large_allocated);
+
+    size_t dirty_pages = 0;
+    size_t muzzy_pages = 0;
+    ReadMergedArenaKnob("pdirty", dirty_pages);
+    ReadMergedArenaKnob("pmuzzy", muzzy_pages);
+    snapshot.dirty_bytes = uint64_t{dirty_pages} * page_size;
+    snapshot.muzzy_bytes = uint64_t{muzzy_pages} * page_size;
+
+    // jemalloc 5 keeps the two decay paths apart and exposes no combined
+    // counter, so both halves are reported rather than summed away.
+    read_merged_u64("dirty_purged", snapshot.dirty_purged_pages);
+    read_merged_u64("muzzy_purged", snapshot.muzzy_purged_pages);
+    read_merged_u64("dirty_npurge", snapshot.dirty_purge_runs);
+    read_merged_u64("muzzy_npurge", snapshot.muzzy_purge_runs);
+    read_merged_u64("dirty_nmadvise", snapshot.dirty_madvises);
+    read_merged_u64("muzzy_nmadvise", snapshot.muzzy_madvises);
+    read_merged_u64("small.nmalloc", snapshot.small_allocations);
+    read_merged_u64("small.ndalloc", snapshot.small_deallocations);
+
+    unsigned arenas = 0;
+    if (ReadJemallocKnob("arenas.narenas", arenas)) {
+        snapshot.arenas = arenas;
+    }
+
+    // Every small size class is reported, drained ones included, so that a
+    // class whose slabs are all released keeps its series at zero instead of
+    // going stale.
+    unsigned nbins = 0;
+    snapshot.bins.clear();
+    if (ReadJemallocKnob("arenas.nbins", nbins)) {
+        snapshot.bins.reserve(nbins);
+        for (unsigned i = 0; i < nbins; ++i) {
+            const std::string index = std::to_string(i);
+            JemallocBinStats bin;
+            size_t bin_size = 0;
+            uint32_t regs_per_slab = 0;
+            if (!ReadJemallocKnob(("arenas.bin." + index + ".size").c_str(),
+                                  bin_size) ||
+                !ReadJemallocKnob(("arenas.bin." + index + ".nregs").c_str(),
+                                  regs_per_slab)) {
+                continue;
+            }
+            bin.size = bin_size;
+            bin.regs_per_slab = regs_per_slab;
+
+            size_t regs = 0;
+            size_t slabs = 0;
+            ReadMergedArenaKnob(("bins." + index + ".curregs").c_str(), regs);
+            ReadMergedArenaKnob(("bins." + index + ".curslabs").c_str(), slabs);
+            bin.regs = regs;
+            bin.slabs = slabs;
+            snapshot.bins.push_back(bin);
+        }
+    }
+
+    // A decay of -1 means the arena never purges, so the signed width has to be
+    // preserved all the way into the gauge.
+    ssize_t dirty_decay_ms = 0;
+    ssize_t muzzy_decay_ms = 0;
+    ReadJemallocKnob("opt.dirty_decay_ms", dirty_decay_ms);
+    ReadJemallocKnob("opt.muzzy_decay_ms", muzzy_decay_ms);
+    snapshot.opt_dirty_decay_ms = dirty_decay_ms;
+    snapshot.opt_muzzy_decay_ms = muzzy_decay_ms;
+
+    return true;
+}
+
+/**
+ * @brief Publish CollectJemallocStats so that /metrics reports the allocator.
+ *
+ * A no-op in a binary that does not link jemalloc, which keeps the call site in
+ * main() free of preprocessor branches.
+ */
+inline void InstallAllocatorStatsCollector() {
+    SetJemallocStatsCollector(&CollectJemallocStats);
+}
+
+#else
+
+inline void LogAllocatorStatus() {}
+
+inline void InstallAllocatorStatsCollector() {}
+
+#endif  // STORE_USE_JEMALLOC
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/background_worker.h b/mooncake-store/include/background_worker.h
new file mode 100644
index 0000000000..95858e887c
--- /dev/null
+++ b/mooncake-store/include/background_worker.h
@@ -0,0 +1,86 @@
+#pragma once
+
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+#include <thread>
+#include <utility>
+
+namespace mooncake {
+
+// Runs a callback on a dedicated thread when scheduled. Multiple Schedule()
+// calls made before the worker consumes the pending request are coalesced into
+// one callback invocation. Start() and Stop() must be called serially by the
+// owner; Schedule() may be called concurrently from other threads.
+class BackgroundWorker {
+   public:
+    using Callback = std::function<void()>;
+
+    explicit BackgroundWorker(Callback callback)
+        : callback_(std::move(callback)) {}
+
+    ~BackgroundWorker() { Stop(); }
+
+    BackgroundWorker(const BackgroundWorker&) = delete;
+    BackgroundWorker& operator=(const BackgroundWorker&) = delete;
+
+    void Start() {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (running_) {
+            return;
+        }
+        running_ = true;
+        requested_ = false;
+        thread_ = std::thread(&BackgroundWorker::ThreadFunc, this);
+    }
+
+    void Stop() {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (!running_ && !thread_.joinable()) {
+                return;
+            }
+            running_ = false;
+            requested_ = false;
+        }
+        cv_.notify_all();
+        if (thread_.joinable()) {
+            thread_.join();
+        }
+    }
+
+    void Schedule() {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (!running_) {
+                return;
+            }
+            requested_ = true;
+        }
+        cv_.notify_one();
+    }
+
+   private:
+    void ThreadFunc() {
+        while (true) {
+            {
+                std::unique_lock<std::mutex> lock(mutex_);
+                cv_.wait(lock, [this] { return !running_ || requested_; });
+                if (!running_) {
+                    return;
+                }
+                requested_ = false;
+            }
+            callback_();
+        }
+    }
+
+    Callback callback_;
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::thread thread_;
+    bool running_{false};
+    bool requested_{false};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/batch_read_fanout.h b/mooncake-store/include/batch_read_fanout.h
new file mode 100644
index 0000000000..1b7ed1ea7d
--- /dev/null
+++ b/mooncake-store/include/batch_read_fanout.h
@@ -0,0 +1,160 @@
+// Duplicate-key handling for batch reads.
+//
+// The transfer batch structures are keyed by string, so a batch that names
+// the same key more than once would collapse every occurrence onto one
+// destination. These helpers give every read path the same contract instead:
+// transfer each unique key exactly once (first occurrence is the primary),
+// then fan the verified bytes out to each duplicate's own destination with a
+// device-aware copy, and mirror the primary's result (success or error).
+//
+// PlanDuplicateKeys decides who transfers, FanOutDuplicates propagates
+// results, and CopyMaybeDevice / CopySlicesMaybeDevice move the bytes for
+// contiguous and scatter-gather destinations that may live on host or device.
+
+#pragma once
+
+#include <glog/logging.h>
+#include <ylt/util/tl/expected.hpp>
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "device/accelerator_registry.h"
+#include "types.h"
+
+namespace mooncake {
+
+// Which ops transfer (unique keys, in first-occurrence order) and which wait
+// for a local fan-out copy, as (duplicate op, primary op) pairs.
+struct DuplicateKeyPlan {
+    std::vector<size_t> primaries;
+    std::vector<std::pair<size_t, size_t>> duplicates;
+};
+
+// Op must have a `.key` string member.
+template <typename Op>
+DuplicateKeyPlan PlanDuplicateKeys(const std::vector<Op> &ops) {
+    DuplicateKeyPlan plan;
+    std::unordered_map<std::string, size_t> first_op_by_key;
+    for (size_t i = 0; i < ops.size(); ++i) {
+        auto [it, inserted] = first_op_by_key.emplace(ops[i].key, i);
+        if (inserted) {
+            plan.primaries.push_back(i);
+        } else {
+            plan.duplicates.emplace_back(i, it->second);
+        }
+    }
+    return plan;
+}
+
+// Contiguous copy between buffers that may each be host or device resident.
+inline tl::expected<void, ErrorCode> CopyMaybeDevice(
+    void *dst, const void *src, size_t size, const std::string &context) {
+    auto runtime_accelerator =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
+    if (!runtime_accelerator.CopyAuto(dst, src, size)) {
+        LOG(ERROR) << "copy failed: " << context;
+        return tl::make_unexpected(ErrorCode::TRANSFER_FAIL);
+    }
+    return {};
+}
+
+// Copy total_size bytes between two slice lists whose chunking may differ
+// (e.g. two callers carved the same object into different per-buffer
+// layouts). Single-slice lists are the contiguous case.
+inline tl::expected<void, ErrorCode> CopySlicesMaybeDevice(
+    const std::vector<Slice> &dst, const std::vector<Slice> &src,
+    uint64_t total_size, const std::string &context) {
+    size_t src_idx = 0, dst_idx = 0, src_off = 0, dst_off = 0;
+    uint64_t remaining = total_size;
+    while (remaining > 0) {
+        while (src_idx < src.size() && src_off == src[src_idx].size) {
+            ++src_idx;
+            src_off = 0;
+        }
+        while (dst_idx < dst.size() && dst_off == dst[dst_idx].size) {
+            ++dst_idx;
+            dst_off = 0;
+        }
+        if (src_idx >= src.size() || dst_idx >= dst.size()) {
+            LOG(ERROR) << "slice lists underflow at "
+                       << (total_size - remaining) << "/" << total_size
+                       << " bytes: " << context;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        const size_t chunk =
+            std::min({src[src_idx].size - src_off, dst[dst_idx].size - dst_off,
+                      static_cast<size_t>(remaining)});
+        if (auto r = CopyMaybeDevice(
+                static_cast<char *>(dst[dst_idx].ptr) + dst_off,
+                static_cast<const char *>(src[src_idx].ptr) + src_off, chunk,
+                context);
+            !r) {
+            return r;
+        }
+        src_off += chunk;
+        dst_off += chunk;
+        remaining -= chunk;
+    }
+    return {};
+}
+
+// One duplicate fan-out: move the primary's verified bytes into the
+// duplicate's destination, then mirror the primary's result slot.
+struct DuplicateFanOutJob {
+    size_t dup_result_index;
+    size_t primary_result_index;
+    std::string key;
+    uint64_t dup_bytes;
+    uint64_t primary_bytes;
+    std::function<tl::expected<void, ErrorCode>()> copy;
+};
+
+// Zip parallel buffer/size lists into slices.
+inline std::vector<Slice> SlicesFromBuffers(const std::vector<void *> &buffers,
+                                            const std::vector<size_t> &sizes) {
+    std::vector<Slice> slices;
+    slices.reserve(buffers.size());
+    for (size_t j = 0; j < buffers.size(); ++j) {
+        slices.push_back(Slice{buffers[j], sizes[j]});
+    }
+    return slices;
+}
+
+// A duplicate whose primary failed inherits the primary's error rather than
+// a pre-set success; a size mismatch between same-key destinations fails the
+// duplicate loudly instead of copying.
+inline void FanOutDuplicates(
+    const std::vector<DuplicateFanOutJob> &jobs,
+    std::vector<tl::expected<int64_t, ErrorCode>> &results) {
+    for (const auto &job : jobs) {
+        const auto &primary_result = results[job.primary_result_index];
+        if (!primary_result) {
+            LOG(ERROR) << "Read failed for key '" << job.key
+                       << "': primary read for the same key failed";
+            results[job.dup_result_index] =
+                tl::make_unexpected(primary_result.error());
+            continue;
+        }
+        if (job.dup_bytes != job.primary_bytes) {
+            LOG(ERROR) << "Size mismatch for duplicate key '" << job.key
+                       << "': " << job.dup_bytes << " vs " << job.primary_bytes;
+            results[job.dup_result_index] =
+                tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            continue;
+        }
+        if (auto r = job.copy(); !r) {
+            results[job.dup_result_index] = tl::make_unexpected(r.error());
+            continue;
+        }
+        results[job.dup_result_index] = *primary_result;
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/client_auto_port_config.h b/mooncake-store/include/client_auto_port_config.h
new file mode 100644
index 0000000000..1bbc44cdc5
--- /dev/null
+++ b/mooncake-store/include/client_auto_port_config.h
@@ -0,0 +1,13 @@
+#pragma once
+
+namespace mooncake {
+
+struct ClientAutoPortConfig {
+    int max_retries = 20;
+    int min_port = 12300;
+    int max_port = 14300;
+
+    static ClientAutoPortConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/client_liveness.h b/mooncake-store/include/client_liveness.h
new file mode 100644
index 0000000000..c9206cf3ef
--- /dev/null
+++ b/mooncake-store/include/client_liveness.h
@@ -0,0 +1,194 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <mutex>
+#include <optional>
+#include <utility>
+
+namespace mooncake {
+
+enum class ClientLivenessState {
+    ACTIVE,
+    SUSPECTED,
+    OFFLINE,
+};
+
+enum class ClientLivenessTransition {
+    NONE,
+    BECAME_SUSPECTED,
+    BECAME_OFFLINE,
+};
+
+enum class ClientLivenessObservation {
+    REFRESHED_ACTIVE,
+    RECOVERED_ACTIVE,
+    REJECTED_OFFLINE,
+    // The wrapped operation failed its success predicate, so state and the
+    // observation timestamp were left unchanged.
+    OBSERVATION_WITHHELD,
+};
+
+class ClientLivenessRecord {
+   public:
+    using Clock = std::chrono::steady_clock;
+    using TimePoint = Clock::time_point;
+
+    explicit ClientLivenessRecord(TimePoint initial_observation)
+        : last_liveness_at_(initial_observation) {}
+
+    class ServingGuard {
+       public:
+        ServingGuard(const ServingGuard&) = delete;
+        ServingGuard& operator=(const ServingGuard&) = delete;
+        ServingGuard(ServingGuard&&) noexcept = default;
+        ServingGuard& operator=(ServingGuard&&) noexcept = default;
+
+       private:
+        friend class ClientLivenessRecord;
+        explicit ServingGuard(std::unique_lock<std::mutex>&& lock)
+            : lock_(std::move(lock)) {}
+
+        std::unique_lock<std::mutex> lock_;
+    };
+
+    class RetainingGuard {
+       public:
+        RetainingGuard(const RetainingGuard&) = delete;
+        RetainingGuard& operator=(const RetainingGuard&) = delete;
+        RetainingGuard(RetainingGuard&&) noexcept = default;
+        RetainingGuard& operator=(RetainingGuard&&) noexcept = default;
+
+       private:
+        friend class ClientLivenessRecord;
+        explicit RetainingGuard(std::unique_lock<std::mutex>&& lock)
+            : lock_(std::move(lock)) {}
+
+        std::unique_lock<std::mutex> lock_;
+    };
+
+    [[nodiscard]] ClientLivenessState state() const {
+        return state_.load(std::memory_order_acquire);
+    }
+
+    [[nodiscard]] bool IsServing() const {
+        return state() == ClientLivenessState::ACTIVE;
+    }
+
+    [[nodiscard]] bool ShouldRetainResources() const {
+        return state() != ClientLivenessState::OFFLINE;
+    }
+
+    [[nodiscard]] std::optional<ServingGuard> TryAcquireServingGuard() {
+        std::unique_lock<std::mutex> lock(transition_mutex_);
+        if (state_.load(std::memory_order_relaxed) !=
+            ClientLivenessState::ACTIVE) {
+            return std::nullopt;
+        }
+        return ServingGuard(std::move(lock));
+    }
+
+    [[nodiscard]] std::optional<RetainingGuard> TryAcquireRetainingGuard() {
+        std::unique_lock<std::mutex> lock(transition_mutex_);
+        if (state_.load(std::memory_order_relaxed) ==
+            ClientLivenessState::OFFLINE) {
+            return std::nullopt;
+        }
+        return RetainingGuard(std::move(lock));
+    }
+
+    [[nodiscard]] ClientLivenessObservation Observe(TimePoint now) {
+        return ObserveAndRun(now, [] { return true; });
+    }
+
+    template <typename Operation>
+    [[nodiscard]] ClientLivenessObservation ObserveAndRun(
+        TimePoint now, Operation&& operation) {
+        std::lock_guard<std::mutex> lock(transition_mutex_);
+        const auto current_state = state_.load(std::memory_order_relaxed);
+        if (current_state == ClientLivenessState::OFFLINE) {
+            return ClientLivenessObservation::REJECTED_OFFLINE;
+        }
+
+        const bool should_commit = std::forward<Operation>(operation)();
+        if (!should_commit) {
+            return ClientLivenessObservation::OBSERVATION_WITHHELD;
+        }
+
+        return CommitObservationLocked(now, current_state);
+    }
+
+    [[nodiscard]] ClientLivenessTransition Evaluate(
+        TimePoint now, Clock::duration active_ttl,
+        Clock::duration suspicion_ttl) {
+        return EvaluateAndRetire(now, active_ttl, suspicion_ttl, [] {});
+    }
+
+    template <typename RetireOperation>
+    [[nodiscard]] ClientLivenessTransition EvaluateAndRetire(
+        TimePoint now, Clock::duration active_ttl,
+        Clock::duration suspicion_ttl, RetireOperation&& retire_operation) {
+        return EvaluateAndRetire(
+            now, active_ttl, suspicion_ttl, [] {},
+            std::forward<RetireOperation>(retire_operation));
+    }
+
+    template <typename ReserveRetirement, typename RetireOperation>
+    [[nodiscard]] ClientLivenessTransition EvaluateAndRetire(
+        TimePoint now, Clock::duration active_ttl,
+        Clock::duration suspicion_ttl, ReserveRetirement&& reserve_retirement,
+        RetireOperation&& retire_operation) {
+        ClientLivenessTransition transition = ClientLivenessTransition::NONE;
+        {
+            std::lock_guard<std::mutex> lock(transition_mutex_);
+            switch (state_.load(std::memory_order_relaxed)) {
+                case ClientLivenessState::ACTIVE:
+                    if (now - last_liveness_at_ >= active_ttl) {
+                        suspected_since_ = now;
+                        state_.store(ClientLivenessState::SUSPECTED,
+                                     std::memory_order_release);
+                        transition = ClientLivenessTransition::BECAME_SUSPECTED;
+                    }
+                    break;
+                case ClientLivenessState::SUSPECTED:
+                    if (now - suspected_since_ >= suspicion_ttl) {
+                        // Publish the external barrier before OFFLINE so a
+                        // concurrent snapshot cannot miss terminal work.
+                        std::forward<ReserveRetirement>(reserve_retirement)();
+                        state_.store(ClientLivenessState::OFFLINE,
+                                     std::memory_order_release);
+                        transition = ClientLivenessTransition::BECAME_OFFLINE;
+                    }
+                    break;
+                case ClientLivenessState::OFFLINE:
+                    break;
+            }
+        }
+        // OFFLINE is already visible and no new guard can enter. Run the
+        // one-shot retirement work without nesting this mutex under Segment,
+        // metadata, or snapshot locks acquired by the callback.
+        if (transition == ClientLivenessTransition::BECAME_OFFLINE) {
+            std::forward<RetireOperation>(retire_operation)();
+        }
+        return transition;
+    }
+
+   private:
+    [[nodiscard]] ClientLivenessObservation CommitObservationLocked(
+        TimePoint now, ClientLivenessState current_state) {
+        last_liveness_at_ = now;
+        if (current_state == ClientLivenessState::SUSPECTED) {
+            state_.store(ClientLivenessState::ACTIVE,
+                         std::memory_order_release);
+            return ClientLivenessObservation::RECOVERED_ACTIVE;
+        }
+        return ClientLivenessObservation::REFRESHED_ACTIVE;
+    }
+
+    std::atomic<ClientLivenessState> state_{ClientLivenessState::ACTIVE};
+    std::mutex transition_mutex_;
+    TimePoint last_liveness_at_;
+    TimePoint suspected_since_{};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/client_metric.h b/mooncake-store/include/client_metric.h
index 87247f1770..d34bab6db0 100644
--- a/mooncake-store/include/client_metric.h
+++ b/mooncake-store/include/client_metric.h
@@ -14,9 +14,11 @@
 #include <ylt/metric/counter.hpp>
 #include <ylt/metric/histogram.hpp>
 #include <ylt/metric/summary.hpp>
+#include "allocator_metric.h"
 #include "environ.h"
 #include "hybrid_metric.h"
-#include "utils.h"
+#include "master_heartbeat_metric.h"
+#include "common/byte_size.h"
 
 namespace mooncake {
 
@@ -653,11 +655,248 @@ struct SsdMetric {
     }
 };
 
+// DFS metrics. The DFS data plane is descriptor-addressed BatchWrite/BatchRead
+// against preallocated shard files and never passes through FileStorage, so
+// SsdMetric does not observe any of it; these counters are recorded in Client
+// instead. kSsdLatencyBucket is reused because DFS is 3fs/nfs backed and shares
+// the same 50us-30s latency envelope as the SSD offload path.
+struct DfsMetric {
+    // Failures are dimensioned by ErrorCode name so a scrape can tell
+    // DFS_SERVICE_UNAVAILABLE apart from FILE_WRITE_FAIL without log digging.
+    std::array<std::string, 1> error_label_names = {"error"};
+
+    explicit DfsMetric(std::map<std::string, std::string> labels = {})
+        : dfs_read_bytes("mooncake_dfs_read_bytes_total",
+                         "Total bytes read from DFS", labels),
+          dfs_write_bytes("mooncake_dfs_write_bytes_total",
+                          "Total bytes written to DFS", labels),
+          dfs_read_ops("mooncake_dfs_read_ops_total",
+                       "Total number of DFS read operations (key count)",
+                       labels),
+          dfs_write_ops("mooncake_dfs_write_ops_total",
+                        "Total number of DFS write operations (key count)",
+                        labels),
+          dfs_read_latency_us("mooncake_dfs_read_latency_us",
+                              "DFS BatchRead latency per batch (us)",
+                              kSsdLatencyBucket, labels),
+          dfs_write_latency_us(
+              "mooncake_dfs_write_latency_us",
+              "DFS BatchWrite latency per batch (us), excluding D2H staging",
+              kSsdLatencyBucket, labels),
+          dfs_write_staging_latency_us(
+              "mooncake_dfs_write_staging_latency_us",
+              "DFS device-to-host staging latency per batch (us)",
+              kSsdLatencyBucket, labels),
+          dfs_read_latency_summary("mooncake_dfs_read_latency_summary_us",
+                                   "DFS read latency quantiles (us)",
+                                   {0.5, 0.9, 0.99}, labels),
+          dfs_write_latency_summary("mooncake_dfs_write_latency_summary_us",
+                                    "DFS write latency quantiles (us)",
+                                    {0.5, 0.9, 0.99}, labels),
+          dfs_read_errors("mooncake_dfs_read_errors_total",
+                          "DFS read failures by error code (key count)", labels,
+                          error_label_names),
+          dfs_write_errors("mooncake_dfs_write_errors_total",
+                           "DFS write failures by error code (key count)",
+                           labels, error_label_names),
+          dfs_writes_skipped(
+              "mooncake_dfs_writes_skipped_total",
+              "DFS writes skipped without being attempted because a non-DFS "
+              "replica transfer failed first (key count)",
+              labels),
+          start_time_(std::chrono::steady_clock::now()) {}
+
+    ylt::metric::counter_t dfs_read_bytes;
+    ylt::metric::counter_t dfs_write_bytes;
+    ylt::metric::counter_t dfs_read_ops;
+    ylt::metric::counter_t dfs_write_ops;
+    ylt::metric::histogram_t dfs_read_latency_us;
+    ylt::metric::histogram_t dfs_write_latency_us;
+    ylt::metric::histogram_t dfs_write_staging_latency_us;
+    ylt::metric::summary_t dfs_read_latency_summary;
+    ylt::metric::summary_t dfs_write_latency_summary;
+    ylt::metric::hybrid_counter_1t dfs_read_errors;
+    ylt::metric::hybrid_counter_1t dfs_write_errors;
+    ylt::metric::counter_t dfs_writes_skipped;
+    std::chrono::steady_clock::time_point start_time_;
+
+    // One op is one key, matching the SsdMetric convention. Only successful
+    // keys are counted here; failures go to RecordReadErrors instead, so
+    // ops/bytes stay a clean measure of delivered work.
+    void ObserveRead(int64_t key_count, int64_t bytes, uint64_t latency_us) {
+        dfs_read_ops.inc(key_count);
+        dfs_read_bytes.inc(bytes);
+        dfs_read_latency_us.observe(latency_us);
+        dfs_read_latency_summary.observe(latency_us);
+    }
+
+    void ObserveWrite(int64_t key_count, int64_t bytes, uint64_t latency_us) {
+        dfs_write_ops.inc(key_count);
+        dfs_write_bytes.inc(bytes);
+        dfs_write_latency_us.observe(latency_us);
+        dfs_write_latency_summary.observe(latency_us);
+    }
+
+    // Staging is the GPU->host copy that precedes a DFS write. It is observed
+    // separately because it is neither DFS I/O nor attributable to the DFS
+    // backend, yet it sits inside the same put latency window.
+    void ObserveWriteStaging(uint64_t latency_us) {
+        dfs_write_staging_latency_us.observe(latency_us);
+    }
+
+    // error_name is the ErrorCode spelling from toString(); keeping it a string
+    // avoids pulling types.h into the metric header.
+    void RecordReadErrors(const std::string& error_name, int64_t count = 1) {
+        const std::array<std::string, 1> error_label = {error_name};
+        {
+            std::lock_guard<std::mutex> lock(observed_errors_mutex_);
+            observed_read_errors_.insert(error_name);
+        }
+        dfs_read_errors.inc(error_label, count);
+    }
+
+    void RecordWriteErrors(const std::string& error_name, int64_t count = 1) {
+        const std::array<std::string, 1> error_label = {error_name};
+        {
+            std::lock_guard<std::mutex> lock(observed_errors_mutex_);
+            observed_write_errors_.insert(error_name);
+        }
+        dfs_write_errors.inc(error_label, count);
+    }
+
+    void RecordSkippedWrites(int64_t count) { dfs_writes_skipped.inc(count); }
+
+    void serialize(std::string& str) {
+        dfs_read_bytes.serialize(str);
+        dfs_write_bytes.serialize(str);
+        dfs_read_ops.serialize(str);
+        dfs_write_ops.serialize(str);
+        dfs_read_latency_us.serialize(str);
+        dfs_write_latency_us.serialize(str);
+        dfs_write_staging_latency_us.serialize(str);
+        dfs_read_latency_summary.serialize(str);
+        dfs_write_latency_summary.serialize(str);
+        dfs_read_errors.serialize(str);
+        dfs_write_errors.serialize(str);
+        dfs_writes_skipped.serialize(str);
+    }
+
+    std::string summary_metrics() {
+        std::stringstream ss;
+        ss << "=== DFS Metrics Summary ===" << "\n";
+
+        const auto read_bytes = dfs_read_bytes.value();
+        const auto write_bytes = dfs_write_bytes.value();
+        const auto read_ops = dfs_read_ops.value();
+        const auto write_ops = dfs_write_ops.value();
+        const auto elapsed_s =
+            std::chrono::duration<double>(std::chrono::steady_clock::now() -
+                                          start_time_)
+                .count();
+
+        ss << format_io_line("DFS Read", read_bytes, read_ops, elapsed_s);
+        ss << format_io_line("DFS Write", write_bytes, write_ops, elapsed_s);
+        ss << "DFS Writes Skipped: " << dfs_writes_skipped.value() << "\n";
+        ss << format_error_line("DFS Read Errors", observed_read_errors_,
+                                dfs_read_errors);
+        ss << format_error_line("DFS Write Errors", observed_write_errors_,
+                                dfs_write_errors);
+
+        ss << "\n" << "=== DFS Latency Summary (microseconds) ===" << "\n";
+        ss << "Read: " << format_percentiles(dfs_read_latency_summary) << "\n";
+        ss << "Write: " << format_percentiles(dfs_write_latency_summary)
+           << "\n";
+
+        return ss.str();
+    }
+
+   private:
+    std::mutex observed_errors_mutex_;
+    std::unordered_set<std::string> observed_read_errors_;
+    std::unordered_set<std::string> observed_write_errors_;
+
+    // Reads the label values seen so far so the text summary can enumerate the
+    // hybrid counter, mirroring TransferOperationMetric::snapshot_operations.
+    std::string format_error_line(
+        const std::string& label,
+        const std::unordered_set<std::string>& observed,
+        ylt::metric::hybrid_counter_1t& counter) {
+        std::vector<std::string> names;
+        {
+            std::lock_guard<std::mutex> lock(observed_errors_mutex_);
+            names.assign(observed.begin(), observed.end());
+        }
+        if (names.empty()) {
+            return "";
+        }
+        std::sort(names.begin(), names.end());
+
+        std::stringstream ss;
+        ss << label << ":";
+        for (const auto& name : names) {
+            const std::array<std::string, 1> error_label = {name};
+            ss << " " << name << "=" << counter.value(error_label);
+        }
+        ss << "\n";
+        return ss.str();
+    }
+
+    std::string format_io_line(const std::string& label, int64_t bytes,
+                               int64_t ops, double elapsed_s) {
+        std::stringstream ss;
+        ss << label << ": " << byte_size_to_string(bytes) << ", ops=" << ops;
+        if (elapsed_s > 0 && bytes > 0) {
+            ss << ", throughput="
+               << byte_size_to_string(static_cast<int64_t>(bytes / elapsed_s))
+               << "/s";
+            ss << ", IOPS=" << std::fixed << std::setprecision(1)
+               << (ops / elapsed_s);
+        }
+        ss << "\n";
+        return ss.str();
+    }
+
+    std::string format_percentiles(ylt::metric::summary_t& summary) {
+        double sum = 0;
+        uint64_t count = 0;
+        auto rates = summary.get_rates(sum, count);
+        if (count == 0) {
+            return "No data";
+        }
+
+        std::stringstream ss;
+        ss << std::fixed << std::setprecision(1);
+        ss << "count=" << count;
+        if (rates.size() >= 1) ss << ", p50=" << rates[0] << "us";
+        if (rates.size() >= 2) ss << ", p90=" << rates[1] << "us";
+        if (rates.size() >= 3) ss << ", p99=" << rates[2] << "us";
+        ss << ", avg=" << (sum / count) << "us";
+        return ss.str();
+    }
+};
+
+struct ClientMetricConfig {
+    bool enabled = true;
+    std::chrono::milliseconds reporting_interval{0};
+    bool bandwidth_reporting_enabled = true;
+
+    static ClientMetricConfig FromEnvironment();
+};
+
 struct ClientMetric {
     TransferMetric transfer_metric;
     MasterClientMetric master_client_metric;
     TransferOperationMetric transfer_operation_metric;
     SsdMetric ssd_metric;
+    DfsMetric dfs_metric;
+    AllocatorMetric allocator_metric;
+    // Prometheus "info" pattern: the value carries no meaning and is always 1,
+    // the version strings ride along as static labels next to any caller
+    // supplied labels so a scrape can attribute samples to a concrete build.
+    // Shares the `mooncake_build_info` name with the master-side metric; the
+    // two are told apart by the scrape target's job/instance labels.
+    ylt::metric::gauge_t build_info;
+    MasterHeartbeatMetric master_heartbeat_metric;
 
     /**
      * @brief Creates a ClientMetric instance based on environment variables
diff --git a/mooncake-store/include/client_offboarding.h b/mooncake-store/include/client_offboarding.h
new file mode 100644
index 0000000000..6aad5347ab
--- /dev/null
+++ b/mooncake-store/include/client_offboarding.h
@@ -0,0 +1,94 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstddef>
+#include <deque>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "client_liveness.h"
+#include "types.h"
+
+namespace mooncake {
+
+class MasterService;
+namespace test {
+class MasterServiceTest;
+}
+
+struct PendingSegmentOffboarding {
+    UUID segment_id;
+    std::string segment_name;
+    std::string transport_endpoint;
+};
+
+struct PreparedSegmentOffboarding {
+    UUID segment_id;
+    std::string segment_name;
+    std::string transport_endpoint;
+    size_t metrics_dec_capacity{0};
+};
+
+// Process-local residual work for one terminal Client incarnation. The job is
+// intentionally not serializable: snapshots stay behind the pending-work
+// barrier until the residual work converges.
+struct ClientOffboardingJob {
+    UUID client_id;
+    std::shared_ptr<ClientLivenessRecord> liveness;
+    std::vector<PendingSegmentOffboarding> pending_prepare_segments;
+    std::vector<PreparedSegmentOffboarding> prepared_segments;
+    bool metadata_cleanup_accepted{false};
+    bool local_ssd_unregistered{false};
+    uint64_t retry_count{0};
+    std::chrono::steady_clock::time_point next_attempt_at{
+        std::chrono::steady_clock::now()};
+    std::chrono::steady_clock::time_point enqueued_at{
+        std::chrono::steady_clock::now()};
+};
+
+class ClientOffboardingWorker {
+   public:
+    explicit ClientOffboardingWorker(MasterService* service)
+        : service_(service) {}
+    ~ClientOffboardingWorker();
+
+    ClientOffboardingWorker(const ClientOffboardingWorker&) = delete;
+    ClientOffboardingWorker& operator=(const ClientOffboardingWorker&) = delete;
+
+    void Start();
+    void Stop();
+    [[nodiscard]] bool HasPending() const {
+        return pending_jobs_.load(std::memory_order_acquire) != 0;
+    }
+
+   private:
+    friend class MasterService;
+    friend class test::MasterServiceTest;
+
+    void ReserveJob();
+    void ScheduleReserved(ClientOffboardingJob job);
+    void ThreadFunc();
+    void CompleteJob(const ClientOffboardingJob& job);
+    void DropJob(const ClientOffboardingJob& job, const char* reason);
+    static std::chrono::seconds RetryDelay(uint64_t retry_count);
+    static bool ShouldAlert(uint64_t retry_count) {
+        return retry_count >= kAlertRetryThreshold;
+    }
+
+    static constexpr uint64_t kAlertRetryThreshold = 10;
+
+    MasterService* service_;
+    std::thread thread_;
+    bool running_{false};
+    std::deque<ClientOffboardingJob> jobs_;
+    mutable std::mutex mutex_;
+    std::condition_variable cv_;
+    std::atomic<size_t> pending_jobs_{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/client_service.h b/mooncake-store/include/client_service.h
index e89f911e6f..95b4246652 100644
--- a/mooncake-store/include/client_service.h
+++ b/mooncake-store/include/client_service.h
@@ -31,6 +31,11 @@
 namespace mooncake {
 
 class PutOperation;
+class DistributedStorageBackend;
+class RealClient;
+
+std::optional<size_t> GetTransportRegistrationLimit(
+    const std::string& protocol);
 
 /**
  * @brief Result of a query operation containing replica information and lease
@@ -68,6 +73,10 @@ class Client {
    public:
     virtual ~Client();
 
+    using WriteBufferStager =
+        std::function<tl::expected<std::vector<Slice>, ErrorCode>(
+            const std::vector<Slice>&)>;
+
     const UUID& getClientId() const { return client_id_; }
     const std::string& tenant_id() const { return master_client_.tenant_id(); }
 
@@ -225,6 +234,41 @@ class Client {
         const std::vector<ObjectKey>& keys,
         std::vector<std::vector<Slice>>& batched_slices,
         const ReplicateConfig& config);
+    std::vector<tl::expected<void, ErrorCode>> BatchPut(
+        const std::vector<ObjectKey>& keys,
+        std::vector<std::vector<Slice>>& batched_slices,
+        const ReplicateConfig& config, const WriteBufferStager& stager);
+
+    /**
+     * @brief Write slices into a memory replica at an object-byte offset.
+     */
+    ErrorCode TransferWriteRange(const Replica::Descriptor& replica_descriptor,
+                                 std::vector<Slice>& slices,
+                                 uint64_t dst_offset);
+
+    /**
+     * @brief Batch ranged read against cached replicas. Fragments from all
+     * entries are issued as one scatter transfer so the transport can coalesce
+     * everything bound for the same segment, then awaited together. Requires
+     * memory replicas. Returns per-entry total bytes transferred or an
+     * ErrorCode. Used by RealClient get sessions. No Master RPC.
+     */
+    std::vector<tl::expected<int64_t, ErrorCode>> BatchTransferReadRanges(
+        const std::vector<Replica::Descriptor>& replicas,
+        const std::vector<std::vector<Slice>>& slices,
+        const std::vector<std::vector<uint64_t>>& src_offsets);
+
+    /**
+     * @brief Batch ranged write into cached replicas (replication). Fragments
+     * from all entries and all memory replicas are issued as one scatter
+     * transfer, then awaited together. Returns per-entry logical bytes
+     * transferred (counted once, not per replica) or an ErrorCode. Used by
+     * RealClient put sessions.
+     */
+    std::vector<tl::expected<int64_t, ErrorCode>> BatchTransferWriteRanges(
+        const std::vector<std::vector<Replica::Descriptor>>& replicas_per_entry,
+        const std::vector<std::vector<Slice>>& slices,
+        const std::vector<std::vector<uint64_t>>& dst_offsets);
 
     /**
      * @brief Upserts data: inserts if key doesn't exist, updates if it does
@@ -247,6 +291,10 @@ class Client {
         const std::vector<ObjectKey>& keys,
         std::vector<std::vector<Slice>>& batched_slices,
         const ReplicateConfig& config);
+    std::vector<tl::expected<void, ErrorCode>> BatchUpsert(
+        const std::vector<ObjectKey>& keys,
+        std::vector<std::vector<Slice>>& batched_slices,
+        const ReplicateConfig& config, const WriteBufferStager& stager);
 
     /**
      * @brief Removes an object and all its replicas
@@ -366,6 +414,15 @@ class Client {
      */
     tl::expected<bool, ErrorCode> IsExist(const std::string& key);
 
+    /**
+     * @brief Point-in-time existence check that grants no read lease.
+     *        A `true` result only means the object existed at the time of
+     *        the call; it may be evicted before a subsequent Get.
+     * @param key Key to check
+     * @return Vector of existence results for each key
+     */
+    tl::expected<bool, ErrorCode> ProbeKey(const std::string& key);
+
     /**
      * @brief Checks if multiple objects exist
      * @param keys Vector of keys to check
@@ -374,6 +431,15 @@ class Client {
     std::vector<tl::expected<bool, ErrorCode>> BatchIsExist(
         const std::vector<std::string>& keys);
 
+    /**
+     * @brief Point-in-time existence check for multiple objects, granting no
+     *        read leases
+     * @param keys Vector of keys to check
+     * @return Vector of existence results for each key
+     */
+    std::vector<tl::expected<bool, ErrorCode>> BatchProbeKey(
+        const std::vector<std::string>& keys);
+
     /**
      * @brief Create a copy task to copy an object's replicas to target segments
      * @param key Object key
@@ -424,6 +490,25 @@ class Client {
      */
     tl::expected<void, ErrorCode> MountLocalDiskSegment(bool enable_offloading);
 
+    /**
+     * @brief Deregisters this client's local disk segment from the master.
+     * Idempotent. The master drops the LOCAL_DISK replicas this client owns, so
+     * readers stop being handed a disk whose owner is about to stop serving.
+     * Callers must stop offloading first, otherwise the storage heartbeat
+     * re-mounts the segment on its next tick.
+     */
+    tl::expected<void, ErrorCode> UnmountLocalDiskSegment();
+
+    /**
+     * @brief Installs the existence probe used by the dangling-replica heal.
+     * The probe lives outside this class because the offload file storage is
+     * owned by the caller (RealClient), not by Client.
+     */
+    void SetLocalDiskProbe(
+        std::function<std::optional<bool>(const std::string& key)> probe) {
+        local_disk_probe_fn_ = std::move(probe);
+    }
+
     /**
      * @brief Heartbeat call to collect object-level statistics and retrieve the
      * set of non-offloaded objects.
@@ -495,13 +580,6 @@ class Client {
     /**
      * @brief Performs a batched read of multiple objects using a
      * high-throughput Transfer Engine.
-     * @param transfer_engine_addr Address of the Transfer Engine service (e.g.,
-     * "ip:port").
-     * @param keys List of keys identifying the data objects to be transferred
-     * @param pointers Array of destination memory addresses on the remote node
-     *                         where data will be written (one per key)
-     * @param batch_slices Map from object key to its data slice
-     * (`mooncake::Slice`), containing raw bytes to be written.
      */
     tl::expected<void, ErrorCode> BatchGetOffloadObject(
         const std::string& transfer_engine_addr,
@@ -510,6 +588,13 @@ class Client {
         const std::unordered_map<std::string, std::vector<Slice>>&
             batch_slices);
 
+    tl::expected<void, ErrorCode> BatchGetOffloadObject(
+        const std::string& transfer_engine_addr,
+        const std::vector<std::string>& keys,
+        const std::vector<uintptr_t>& pointers,
+        const std::unordered_map<std::string, std::vector<Slice>>& batch_slices,
+        OffloadBufferAccess buffer_access);
+
     /**
      * @brief Notifies the master that offloading of specified objects has
      * succeeded.
@@ -524,6 +609,8 @@ class Client {
     tl::expected<void, ErrorCode> NotifyOffloadSuccess(
         const std::vector<OffloadTaskItem>& tasks,
         const std::vector<StorageObjectMetadata>& metadatas);
+    void SetDfsStorageBackend(
+        std::shared_ptr<DistributedStorageBackend> backend);
 
     /**
      * @brief Fetch tasks assigned to a client
@@ -578,12 +665,21 @@ class Client {
         return metrics_ ? &metrics_->ssd_metric : nullptr;
     }
 
+    DfsMetric* GetDfsMetricPtr() {
+        return metrics_ ? &metrics_->dfs_metric : nullptr;
+    }
+
     [[nodiscard]] std::string GetTransportEndpoint() {
         return transfer_engine_->getLocalIpAndPort();
     }
 
     [[nodiscard]] const std::string& GetProtocol() const { return protocol_; }
 
+    [[nodiscard]] bool CanUseLocalMemcpy(const std::string& endpoint) const {
+        return transfer_submitter_ != nullptr &&
+               transfer_submitter_->canUseLocalMemcpy(endpoint);
+    }
+
     /**
      * @brief Get the endpoint address for segment operations.
      * @return For P2PHANDSHAKE mode, returns the actual RPC endpoint (IP:Port).
@@ -610,6 +706,12 @@ class Client {
         return endpoints;
     }
 
+    bool CanUseLocalMemcpy(const Replica::Descriptor& replica) const {
+        if (!replica.is_memory_replica()) return false;
+        return CanUseLocalMemcpy(replica.get_memory_descriptor()
+                                     .buffer_descriptor.transport_endpoint_);
+    }
+
     /**
      * @brief Check if local hot cache is enabled
      * @return true if hot cache is enabled, false otherwise
@@ -662,6 +764,23 @@ class Client {
 
     bool IsReplicaOnLocalMemory(const Replica::Descriptor& replica);
 
+    // First half of BatchPut only (size-only slices → StartBatchPut).
+    // Used by RealClient put sessions; not a Master API facade.
+    std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
+    StartBatchPutForSizes(const std::vector<std::string>& keys,
+                          const std::vector<uint64_t>& object_sizes,
+                          const ReplicateConfig& config);
+
+    // Finalize/revoke a put session for a batch of keys. Thin wrappers over
+    // the master client, exposed so RealClient put sessions can end/revoke
+    // without touching Client internals. Same RPC path as FinalizeBatchPut.
+    std::vector<tl::expected<void, ErrorCode>> BatchPutEnd(
+        const std::vector<ObjectMeta>& object_metas,
+        ReplicaType replica_type = ReplicaType::ALL);
+    std::vector<tl::expected<void, ErrorCode>> BatchPutRevoke(
+        const std::vector<std::string>& keys,
+        ReplicaType replica_type = ReplicaType::ALL);
+
    protected:
     /**
      * @brief Constructor exposed to subclasses for testing only; production
@@ -688,6 +807,26 @@ class Client {
      * @brief Internal helper functions for initialization and data transfer
      */
     ErrorCode ConnectToMaster(const std::string& master_server_entry);
+    // When PutStart reports OBJECT_ALREADY_EXISTS, check whether every
+    // completed replica is a LOCAL_DISK replica owned by this client, and ask
+    // the installed probe (FileStorage::Exists over the offload files) whether
+    // the backing file is gone (issue #3709). Only then evict the dangling
+    // replica so the Put can be retried; any other outcome keeps the old
+    // idempotent path. Returns true only when a replica was actually evicted.
+    bool healDanglingLocalDiskReplica(const ObjectKey& key);
+    // The BatchPutStart counterpart: heals the OBJECT_ALREADY_EXISTS subset
+    // with one batched replica-list query and one batched evict, then retries
+    // PutStart for just the evicted keys and splices the responses back, so a
+    // healthy idempotent batch pays one extra RPC and no evictions.
+    void healDanglingLocalDiskBatchStarts(
+        std::vector<PutOperation>& ops,
+        const std::vector<size_t>& active_indices,
+        const std::vector<size_t>& already_exists,
+        const std::vector<std::string>& keys,
+        const std::vector<std::vector<uint64_t>>& slice_lengths,
+        const ReplicateConfig& config);
+
+    void EnterHaRuntimeMode();
     ErrorCode InitTransferEngine(
         const std::string& local_hostname,
         const std::string& metadata_connstring, const std::string& protocol,
@@ -699,6 +838,15 @@ class Client {
     ErrorCode TransferReadInternal(
         const Replica::Descriptor& replica_descriptor,
         std::vector<Slice>& slices, uint64_t src_offset);
+    // Internal async range submission helpers (return the transfer future).
+    // Used by the synchronous TransferReadRange/WriteRange and the batch
+    // range transfer methods; not part of the public API.
+    std::optional<TransferFuture> SubmitRangeRead(
+        const Replica::Descriptor& replica_descriptor,
+        std::vector<Slice>& slices, uint64_t src_offset);
+    std::optional<TransferFuture> SubmitRangeWrite(
+        const Replica::Descriptor& replica_descriptor,
+        std::vector<Slice>& slices, uint64_t dst_offset);
     ErrorCode TransferWrite(const Replica::Descriptor& replica_descriptor,
                             std::vector<Slice>& slices);
     ErrorCode TransferRead(const Replica::Descriptor& replica_descriptor,
@@ -706,6 +854,9 @@ class Client {
     ErrorCode TransferReadRange(const Replica::Descriptor& replica_descriptor,
                                 std::vector<Slice>& slices,
                                 uint64_t src_offset);
+    ErrorCode ReadDfsReplica(const std::string& key,
+                             const Replica::Descriptor& replica_descriptor,
+                             std::vector<Slice>& slices);
     tl::expected<uint64_t, ErrorCode> ComputeObjectChecksumForSlices(
         const std::string& object_key, const std::vector<Slice>& slices,
         size_t object_size);
@@ -715,8 +866,8 @@ class Client {
                         const DiskDescriptor& disk_descriptor);
     /**
      * @brief Initialize local hot cache
-     * @return ErrorCode::OK if use local hot cache,
-     * ErrorCode::INVALID_PARAMS if invalid MC_STORE_LOCAL_HOT_CACHE_SIZE config
+     * @return ErrorCode::OK if disabled or initialized successfully;
+     * ErrorCode::INVALID_PARAMS if cache allocation or registration fails
      */
     ErrorCode InitLocalHotCache();
 
@@ -725,21 +876,6 @@ class Client {
      */
     void UnregisterLocalHotCacheMemory();
 
-    /**
-     * @brief Read MC_STORE_LOCAL_HOT_CACHE_SIZE from environment variable
-     * @return Cache size in bytes, or 0 if not set or invalid
-     */
-    size_t GetLocalHotCacheSizeFromEnv();
-
-    /**
-     * @brief Read MC_STORE_LOCAL_HOT_BLOCK_SIZE from environment variable
-     * @param default_value Default block size to use if env var is not set or
-     * invalid
-     * @return Parsed block size from environment, or default_value if not
-     * set/invalid
-     */
-    size_t GetLocalHotBlockSizeFromEnv(size_t default_value);
-
     /**
      * @brief Redirect replica descriptor to local hot cache if cache hit
      * @param key Object key
@@ -781,8 +917,11 @@ class Client {
     void StartBatchPut(std::vector<PutOperation>& ops,
                        const ReplicateConfig& config);
     void ComputeBatchObjectChecksums(std::vector<PutOperation>& ops);
+    void StageWriteBuffersForRemoteReplicas(std::vector<PutOperation>& ops,
+                                            const WriteBufferStager& stager);
     void SubmitTransfers(std::vector<PutOperation>& ops);
     void WaitForTransfers(std::vector<PutOperation>& ops);
+    void SubmitDfsWrites(std::vector<PutOperation>& ops);
     void FinalizeBatchPut(std::vector<PutOperation>& ops);
     void StartBatchUpsert(std::vector<PutOperation>& ops,
                           const ReplicateConfig& config);
@@ -790,8 +929,13 @@ class Client {
     std::vector<tl::expected<void, ErrorCode>> CollectResults(
         const std::vector<PutOperation>& ops);
 
-    std::vector<tl::expected<void, ErrorCode>> BatchPutWhenPreferSameNode(
-        std::vector<PutOperation>& ops);
+    std::vector<ErrorCode> WriteDfsReplicas(
+        const std::vector<std::string>& keys,
+        const std::vector<const std::vector<Slice>*>& slice_lists,
+        const std::vector<DistributedFSDescriptor>& descriptors);
+
+    std::vector<tl::expected<void, ErrorCode>> BatchWriteWhenPreferSameNode(
+        std::vector<PutOperation>& ops, bool is_upsert);
     std::vector<tl::expected<void, ErrorCode>> BatchGetWhenPreferSameNode(
         const std::vector<std::string>& object_keys,
         const std::vector<QueryResult>& query_results,
@@ -849,6 +993,15 @@ class Client {
     std::unique_ptr<PinnedBufferPool> pinned_buffer_pool_;
     ThreadPool write_thread_pool_;
     std::shared_ptr<StorageBackend> storage_backend_;
+    std::shared_ptr<DistributedStorageBackend> dfs_storage_backend_;
+
+    // Probe used by healDanglingLocalDiskReplica to prove a completed
+    // LOCAL_DISK replica's backing file is gone. Installed by the owner of
+    // the offload file storage (RealClient); unset means no local-disk
+    // offload is active and the heal stays inert. true: file is gone,
+    // false: file present, nullopt: unknown (keep the old path).
+    std::function<std::optional<bool>(const std::string& key)>
+        local_disk_probe_fn_;
 
     // For high availability
     std::unique_ptr<ha::LeaderCoordinator> leader_coordinator_;
@@ -864,6 +1017,7 @@ class Client {
     std::atomic<bool> last_ping_success_{false};
     std::atomic<bool> segment_desc_publish_pending_{false};
     std::atomic<bool> rpc_meta_publish_pending_{false};
+    ErrorCode ConnectMasterEndpoint(const std::string& address);
     ErrorCode SwitchLeader(const ha::MasterView& target_view);
     void LeaderMonitorThreadMain();
     void StorageHeartbeatThreadMain();
@@ -904,6 +1058,11 @@ class Client {
                                        const std::string& tenant_id,
                                        const std::string& source,
                                        const std::vector<std::string>& targets);
+    tl::expected<void, ErrorCode> Copy(
+        const std::string& key, const std::string& tenant_id,
+        const std::string& source, const std::vector<std::string>& targets,
+        const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
 
     /**
      * @brief Move an object's replica from source segment to target segment
diff --git a/mooncake-store/include/utils/base64.h b/mooncake-store/include/common/base64.h
similarity index 100%
rename from mooncake-store/include/utils/base64.h
rename to mooncake-store/include/common/base64.h
diff --git a/mooncake-store/include/common/byte_size.h b/mooncake-store/include/common/byte_size.h
new file mode 100644
index 0000000000..e11814d362
--- /dev/null
+++ b/mooncake-store/include/common/byte_size.h
@@ -0,0 +1,101 @@
+#pragma once
+
+#include <algorithm>
+#include <cctype>
+#include <cstdint>
+#include <exception>
+#include <iomanip>
+#include <limits>
+#include <optional>
+#include <sstream>
+#include <string>
+
+namespace mooncake {
+
+[[nodiscard]] inline std::string byte_size_to_string(uint64_t bytes) {
+    constexpr double kKiB = 1024.0;
+    constexpr double kMiB = kKiB * 1024.0;
+    constexpr double kGiB = kMiB * 1024.0;
+    constexpr double kTiB = kGiB * 1024.0;
+
+    std::ostringstream oss;
+    oss << std::fixed << std::setprecision(2);
+    if (static_cast<int64_t>(bytes) == std::numeric_limits<int64_t>::max()) {
+        oss << "infinite";
+    } else if (bytes >= static_cast<uint64_t>(kTiB)) {
+        oss << bytes / kTiB << " TB";
+    } else if (bytes >= static_cast<uint64_t>(kGiB)) {
+        oss << bytes / kGiB << " GB";
+    } else if (bytes >= static_cast<uint64_t>(kMiB)) {
+        oss << bytes / kMiB << " MB";
+    } else if (bytes >= static_cast<uint64_t>(kKiB)) {
+        oss << bytes / kKiB << " KB";
+    } else {
+        oss.unsetf(std::ios::fixed);
+        oss << bytes << " B";
+    }
+    return oss.str();
+}
+
+[[nodiscard]] inline std::optional<uint64_t> try_string_to_byte_size(
+    const std::string& str) {
+    if (str.empty()) {
+        return std::nullopt;
+    }
+
+    std::string value_string = str;
+    value_string.erase(0, value_string.find_first_not_of(" \t\r\n"));
+    value_string.erase(value_string.find_last_not_of(" \t\r\n") + 1);
+    if (value_string.empty()) {
+        return std::nullopt;
+    }
+    if (value_string == "infinite") {
+        return std::numeric_limits<uint64_t>::max();
+    }
+
+    size_t unit_offset = 0;
+    double value = 0;
+    try {
+        value = std::stod(value_string, &unit_offset);
+    } catch (const std::exception&) {
+        return std::nullopt;
+    }
+    if (value < 0) {
+        return std::nullopt;
+    }
+    if (unit_offset >= value_string.length()) {
+        return static_cast<uint64_t>(value);
+    }
+
+    std::string unit = value_string.substr(unit_offset);
+    unit.erase(0, unit.find_first_not_of(" \t\r\n"));
+    std::transform(unit.begin(), unit.end(), unit.begin(),
+                   [](unsigned char c) -> char { return std::toupper(c); });
+
+    constexpr double kKiB = 1024.0;
+    constexpr double kMiB = kKiB * 1024.0;
+    constexpr double kGiB = kMiB * 1024.0;
+    constexpr double kTiB = kGiB * 1024.0;
+    if (unit == "KB" || unit == "K") {
+        return static_cast<uint64_t>(value * kKiB);
+    }
+    if (unit == "MB" || unit == "M") {
+        return static_cast<uint64_t>(value * kMiB);
+    }
+    if (unit == "GB" || unit == "G") {
+        return static_cast<uint64_t>(value * kGiB);
+    }
+    if (unit == "TB" || unit == "T") {
+        return static_cast<uint64_t>(value * kTiB);
+    }
+    if (unit == "B" || unit.empty()) {
+        return static_cast<uint64_t>(value);
+    }
+    return std::nullopt;
+}
+
+[[nodiscard]] inline uint64_t string_to_byte_size(const std::string& str) {
+    return try_string_to_byte_size(str).value_or(0);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/common/client_buffer_allocation.h b/mooncake-store/include/common/client_buffer_allocation.h
new file mode 100644
index 0000000000..9b038137e9
--- /dev/null
+++ b/mooncake-store/include/common/client_buffer_allocation.h
@@ -0,0 +1,63 @@
+#pragma once
+
+#include <cstddef>
+#include <linux/memfd.h>
+#include <linux/mman.h>
+#include <string>
+#include <vector>
+
+#include <Slab.h>
+
+namespace mooncake {
+
+constexpr size_t SZ_2MB = 2 * 1024 * 1024;
+constexpr size_t SZ_512MB = 512 * 1024 * 1024;
+
+// 512MiB hugepages on arm64 kernels with 64K base pages may not be
+// defined by older glibc/kernel headers.
+#ifndef MAP_HUGE_512MB
+#define MAP_HUGE_512MB (29 << 26)  // MAP_HUGE_SHIFT = 26
+#endif
+#ifndef MFD_HUGE_512MB
+#define MFD_HUGE_512MB (29 << 26)  // MFD_HUGE_SHIFT = 26
+#endif
+constexpr size_t SZ_1GB = 1024 * 1024 * 1024;
+constexpr double BYTES_PER_GIB = static_cast<double>(SZ_1GB);
+
+void* allocate_buffer_allocator_memory(
+    size_t total_size, const std::string& protocol = "",
+    size_t alignment = facebook::cachelib::Slab::kSize,
+    bool use_spdk_dma = false);
+
+void free_memory(const std::string& protocol, void* ptr,
+                 bool use_spdk_dma = false);
+
+inline size_t align_up(size_t size, size_t alignment) {
+    if (alignment == 0) {
+        return size;
+    }
+    return ((size + alignment - 1) / alignment) * alignment;
+}
+
+[[nodiscard]] size_t get_hugepage_size_from_env(
+    unsigned int* out_flags = nullptr, bool use_memfd = false);
+
+void populate_hugetlb_mapping(void* ptr, size_t total_size);
+
+void populate_hugetlb_numa_mapping(void* ptr, size_t total_size,
+                                   const std::vector<int>& numa_nodes);
+
+void* allocate_buffer_mmap_memory(size_t total_size, size_t alignment);
+
+void* allocate_buffer_mmap_memory(size_t total_size, size_t alignment,
+                                  bool defer_hugetlb_population);
+
+[[nodiscard]] bool is_mmap_arena_allocation(const void* ptr);
+
+void free_buffer_mmap_memory(void* ptr, size_t total_size);
+
+void* allocate_buffer_numa_segments(size_t total_size,
+                                    const std::vector<int>& numa_nodes,
+                                    size_t page_size = 0);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/utils/file_util.h b/mooncake-store/include/common/file_util.h
similarity index 85%
rename from mooncake-store/include/utils/file_util.h
rename to mooncake-store/include/common/file_util.h
index a79e42b912..67388d640a 100644
--- a/mooncake-store/include/utils/file_util.h
+++ b/mooncake-store/include/common/file_util.h
@@ -12,6 +12,10 @@ namespace fs = std::filesystem;
 
 class FileUtil {
    public:
+    static std::string ResolvePathFromKey(const std::string& key,
+                                          const std::string& root_dir,
+                                          const std::string& fsdir);
+
     /**
      * @brief Save string content to file
      * @param content Content to save
diff --git a/mooncake-store/include/common/mmap_aligned.h b/mooncake-store/include/common/mmap_aligned.h
new file mode 100644
index 0000000000..e5b564a475
--- /dev/null
+++ b/mooncake-store/include/common/mmap_aligned.h
@@ -0,0 +1,71 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <sys/mman.h>
+
+#include "common/client_buffer_allocation.h"
+
+namespace mooncake {
+
+/**
+ * @brief Place a memfd mapping at a 2MB-aligned address while keeping the file
+ * offset at 0, so the returned base matches what a peer process mapping the fd
+ * at offset 0 sees (cross-process fd sharing is unchanged).
+ *
+ * SPDK before 26.09 (e.g. the v23.01.1 pinned by dependencies.sh) rejects
+ * spdk_mem_register() unless both the start and the length are 2MB-aligned;
+ * plain mmap only guarantees 4KB alignment. Reserve a PROT_NONE region large
+ * enough to contain a 2MB-aligned window, then MAP_FIXED the memfd into it
+ * (which only replaces the reservation, never live mappings), and release the
+ * unaligned head/tail. `size` should be a multiple of 2MB (callers align it).
+ *
+ * NOTE: virtual 2MB alignment is NECESSARY but NOT sufficient on the pinned
+ * SPDK: in iova=pa mode spdk_mem_register additionally checks each segment's
+ * PHYSICAL address (vtophys pagemap path, `paddr & MASK_2MB`), so the memory
+ * must also be hugepage-backed or registration fails with -EINVAL. HugeTLB
+ * mappings are automatically 2MB/1GB-aligned, so this helper is only needed
+ * where the source cannot be hugepage-backed; today it is used solely by the
+ * receiver (RealClient::map_shm_internal_with_device) for the shared fd
+ * (1GB-hugepage fds whose MAP_FIXED here fails fall back to a plain mmap). The
+ * sender (ShmHelper::allocate) always maps hugepages under
+ * MC_STORE_REGISTER_SPDK=1 and needs no aligned base. SPDK >= 26.09 (commit
+ * d6dc356ff) relaxes the API check to 4KB, but iova=pa still needs hugepages,
+ * so a plain mmap remains insufficient for SPDK registration regardless of
+ * version.
+ *
+ * @param size Mapping length; must be a multiple of 2MB for a clean head/tail.
+ * @param fd memfd to map at offset 0.
+ * @return The 2MB-aligned base, or MAP_FAILED on error.
+ */
+inline void* mmap_shm_2mb_aligned(size_t size, int fd) {
+    const size_t reserve_size = size + SZ_2MB;
+    void* hint = mmap(nullptr, reserve_size, PROT_NONE,
+                      MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    if (hint == MAP_FAILED) {
+        return MAP_FAILED;
+    }
+    const uintptr_t hint_addr = reinterpret_cast<uintptr_t>(hint);
+    const uintptr_t target = static_cast<uintptr_t>(
+        align_up(static_cast<size_t>(hint_addr), SZ_2MB));
+    void* base =
+        mmap(reinterpret_cast<void*>(target), size, PROT_READ | PROT_WRITE,
+             MAP_SHARED | MAP_FIXED | MAP_POPULATE, fd, 0);
+    if (base == MAP_FAILED) {
+        munmap(hint, reserve_size);
+        return MAP_FAILED;
+    }
+    // Release the unaligned head and tail of the reservation.
+    const uintptr_t base_addr = reinterpret_cast<uintptr_t>(base);
+    if (base_addr > hint_addr) {
+        munmap(hint, base_addr - hint_addr);
+    }
+    const uintptr_t reserve_end = hint_addr + reserve_size;
+    const uintptr_t tail = base_addr + size;
+    if (tail < reserve_end) {
+        munmap(reinterpret_cast<void*>(tail), reserve_end - tail);
+    }
+    return base;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/common/network.h b/mooncake-store/include/common/network.h
new file mode 100644
index 0000000000..75d24b88a7
--- /dev/null
+++ b/mooncake-store/include/common/network.h
@@ -0,0 +1,38 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+namespace mooncake {
+
+bool isPortAvailable(int port);
+
+class AutoPortBinder {
+   public:
+    AutoPortBinder(int min_port = 12300, int max_port = 14300);
+    ~AutoPortBinder();
+
+    AutoPortBinder(const AutoPortBinder&) = delete;
+    AutoPortBinder& operator=(const AutoPortBinder&) = delete;
+    AutoPortBinder(AutoPortBinder&&) = delete;
+    AutoPortBinder& operator=(AutoPortBinder&&) = delete;
+
+    int getPort() const { return port_; }
+
+   private:
+    int socket_fd_;
+    int port_;
+};
+
+tl::expected<std::string, int> httpGet(const std::string& url);
+
+tl::expected<std::string, std::string> GetInterfaceIPv4Address(
+    const std::string& interface_name);
+
+int getFreeTcpPort();
+
+std::vector<int> getFreeTcpPorts(int count);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/common/result.h b/mooncake-store/include/common/result.h
new file mode 100644
index 0000000000..e1e3e23b1e
--- /dev/null
+++ b/mooncake-store/include/common/result.h
@@ -0,0 +1,131 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <ostream>
+#include <sstream>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "rpc_types.h"
+#include "types.h"
+
+namespace mooncake {
+
+template <class T>
+constexpr bool is_supported_return_type_v =
+    std::is_void_v<T> || std::is_integral_v<T>;
+
+template <class T>
+    requires is_supported_return_type_v<T>
+int64_t to_py_ret(const tl::expected<T, ErrorCode>& exp) noexcept {
+    if (!exp) {
+        return static_cast<int64_t>(toInt(exp.error()));
+    }
+    if constexpr (std::is_void_v<T>) {
+        return 0;
+    } else {
+        return static_cast<int64_t>(exp.value());
+    }
+}
+
+template <typename T>
+void to_stream(std::ostream& os, const T& value);
+
+template <typename T>
+void to_stream(std::ostream& os, const std::vector<T>& vec);
+
+template <typename T1, typename T2>
+void to_stream(std::ostream& os, const std::pair<T1, T2>& p);
+
+template <typename T>
+void to_stream(std::ostream& os, const T& value) {
+    if constexpr (std::is_same_v<T, bool>) {
+        os << (value ? "true" : "false");
+    } else if constexpr (std::is_arithmetic_v<T>) {
+        os << value;
+    } else if constexpr (std::is_convertible_v<T, std::string_view>) {
+        os << "\"" << value << "\"";
+    } else if constexpr (ylt::reflection::is_ylt_refl_v<T>) {
+        std::string str;
+        struct_json::to_json(value, str);
+        os << str;
+    } else {
+        os << value;
+    }
+}
+
+template <typename T>
+void to_stream(std::ostream& os, const std::vector<T>& vec) {
+    os << "[";
+    for (size_t i = 0; i < vec.size(); ++i) {
+        to_stream(os, vec[i]);
+        if (i + 1 < vec.size()) {
+            os << ",";
+        }
+    }
+    os << "]";
+}
+
+template <typename K, typename V, typename H>
+void to_stream(std::ostream& os, const std::unordered_map<K, V, H>& map) {
+    os << "{";
+    auto it = map.begin();
+    while (it != map.end()) {
+        to_stream(os, it->first);
+        os << ": ";
+        to_stream(os, it->second);
+        if (++it != map.end()) {
+            os << ", ";
+        }
+    }
+    os << "}";
+}
+
+template <typename K, typename V>
+void to_stream(std::ostream& os, const std::unordered_map<K, V>& map) {
+    to_stream<K, V, std::hash<K>>(os, map);
+}
+
+template <typename T1, typename T2>
+void to_stream(std::ostream& os, const std::pair<T1, T2>& p) {
+    os << "{\"first\":";
+    to_stream(os, p.first);
+    os << ",\"second\":";
+    to_stream(os, p.second);
+    os << "}";
+}
+
+template <typename T>
+void to_stream(std::ostream& os, const std::optional<T>& opt) {
+    if (opt.has_value()) {
+        to_stream(os, opt.value());
+    } else {
+        os << "nullopt";
+    }
+}
+
+template <typename T>
+std::string expected_to_str(const tl::expected<T, ErrorCode>& expected) {
+    std::ostringstream oss;
+    if (expected.has_value()) {
+        oss << "status=success, value=";
+        if constexpr (std::is_same_v<T, void>) {
+            oss << "void";
+        } else {
+            to_stream(oss, expected.value());
+        }
+    } else {
+        oss << "status=failed, error=" << toString(expected.error());
+    }
+    return oss.str();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/utils/s3_helper.h b/mooncake-store/include/common/s3_helper.h
similarity index 93%
rename from mooncake-store/include/utils/s3_helper.h
rename to mooncake-store/include/common/s3_helper.h
index 5887291823..b5649c61bf 100644
--- a/mooncake-store/include/utils/s3_helper.h
+++ b/mooncake-store/include/common/s3_helper.h
@@ -7,6 +7,8 @@
 
 #include <aws/core/Aws.h>
 #include <aws/s3/S3Client.h>
+#include <cstdint>
+#include <optional>
 #include <string>
 #include <vector>
 #include <ylt/util/tl/expected.hpp>
@@ -74,6 +76,10 @@ class S3Helper {
     tl::expected<void, std::string> DeleteObjectsWithPrefix(
         const std::string &prefix);
 
+    tl::expected<void, std::string> InspectObject(
+        const std::string &key, uint64_t &stored_size,
+        std::optional<uint32_t> &crc32c);
+
    private:
     Aws::S3::S3Client s3_client_;
     std::string bucket_;
diff --git a/mooncake-store/include/utils/scoped_vlog_timer.h b/mooncake-store/include/common/scoped_vlog_timer.h
similarity index 98%
rename from mooncake-store/include/utils/scoped_vlog_timer.h
rename to mooncake-store/include/common/scoped_vlog_timer.h
index 6565acbf1a..2580b8ef09 100644
--- a/mooncake-store/include/utils/scoped_vlog_timer.h
+++ b/mooncake-store/include/common/scoped_vlog_timer.h
@@ -10,7 +10,7 @@
 #include <utility>
 
 #include "types.h"
-#include "utils.h"
+#include "common/result.h"
 #include "ylt/struct_json/json_reader.h"
 #include "ylt/struct_json/json_writer.h"
 #include "ylt/util/tl/expected.hpp"
@@ -131,4 +131,4 @@ class ScopedVLogTimer {
     bool logged_response_ = false;
 };
 
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-store/include/common/timestamp.h b/mooncake-store/include/common/timestamp.h
new file mode 100644
index 0000000000..a5668c4925
--- /dev/null
+++ b/mooncake-store/include/common/timestamp.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+
+namespace mooncake {
+
+inline int64_t time_gen() {
+    return std::chrono::duration_cast<std::chrono::seconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/common/transparent_string_hash.h b/mooncake-store/include/common/transparent_string_hash.h
new file mode 100644
index 0000000000..857b3d1f1c
--- /dev/null
+++ b/mooncake-store/include/common/transparent_string_hash.h
@@ -0,0 +1,23 @@
+#pragma once
+
+#include <functional>
+#include <string>
+#include <string_view>
+
+namespace mooncake {
+
+struct TransparentStringHash final {
+    using is_transparent = void;
+
+    size_t operator()(std::string_view value) const noexcept {
+        return std::hash<std::string_view>{}(value);
+    }
+    size_t operator()(const std::string& value) const noexcept {
+        return (*this)(std::string_view(value));
+    }
+    size_t operator()(const char* value) const noexcept {
+        return (*this)(std::string_view(value));
+    }
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/utils/zstd_util.h b/mooncake-store/include/common/zstd_util.h
similarity index 100%
rename from mooncake-store/include/utils/zstd_util.h
rename to mooncake-store/include/common/zstd_util.h
diff --git a/mooncake-store/include/config/bucket_backend_config.h b/mooncake-store/include/config/bucket_backend_config.h
new file mode 100644
index 0000000000..17f04d7d5b
--- /dev/null
+++ b/mooncake-store/include/config/bucket_backend_config.h
@@ -0,0 +1,70 @@
+#pragma once
+
+#include <cstdint>
+#include <ostream>
+
+namespace mooncake {
+
+enum class BucketEvictionPolicy {
+    NONE,  // No eviction (default)
+    FIFO,  // Evict oldest bucket first (by creation order)
+    LRU,   // Evict least recently read bucket first
+};
+
+inline std::ostream& operator<<(std::ostream& os,
+                                const BucketEvictionPolicy& policy) {
+    switch (policy) {
+        case BucketEvictionPolicy::NONE:
+            return os << "none";
+        case BucketEvictionPolicy::FIFO:
+            return os << "fifo";
+        case BucketEvictionPolicy::LRU:
+            return os << "lru";
+        default:
+            return os << "unknown";
+    }
+}
+
+struct BucketBackendConfig {
+    int64_t bucket_size_limit =
+        256LL * 1024 * 1024;  // Max total size of a single bucket (256 MB)
+
+    int64_t bucket_keys_limit = 500;  // Max number of keys allowed in a single
+                                      // bucket, required by bucket backend only
+
+    BucketEvictionPolicy eviction_policy =
+        BucketEvictionPolicy::NONE;  // Eviction strategy
+
+    int64_t max_total_size = 0;  // 0 = unlimited; evict when total_size_
+                                 // exceeds this threshold (bytes)
+
+    // Hard cap on *actual on-disk* bytes of the offload directory, measured by
+    // scanning real file allocation (stat st_blocks), NOT the in-memory
+    // total_size_. 0 = disabled.
+    //
+    // Why a separate, disk-measured cap: total_size_ is decremented per object
+    // on eviction/delete, but a 256 MB bucket file is only removed once *all*
+    // its objects are gone — so total_size_ (and any sum over the in-memory
+    // bucket map) reads well below real disk usage under per-object eviction
+    // (cf. unreliable bucket GC, kvcache-ai/Mooncake#3220/#3221). The other
+    // physical guard, std::filesystem::space(), reports the *host* filesystem
+    // under a cgroup / K8s emptyDir sizeLimit rather than the enforced quota,
+    // so it never fires either. This cap scans the actual directory (the same
+    // st_blocks basis kubelet's emptyDir accounting uses), so it matches what
+    // actually triggers pod eviction. Set it to the real quota minus headroom.
+    int64_t max_physical_bytes = 0;
+
+    // How long ActualDiskBytesUsedLocked() caches its directory-scan result
+    // (milliseconds). Bounds scan cost under a high offload rate; larger =
+    // cheaper but a staler physical bound (disk may momentarily exceed the cap
+    // by roughly one interval's worth of writes), smaller = tighter but scans
+    // more often. <=0 disables caching (scan every check). Only relevant when
+    // max_physical_bytes > 0.
+    int64_t disk_scan_cache_ms = 500;
+
+    bool Validate() const;
+
+    static BucketBackendConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/distributed_storage_config.h b/mooncake-store/include/config/distributed_storage_config.h
new file mode 100644
index 0000000000..3c39f68661
--- /dev/null
+++ b/mooncake-store/include/config/distributed_storage_config.h
@@ -0,0 +1,32 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <string>
+
+namespace mooncake {
+
+struct DistributedStorageConfig {
+    std::string fsdir = "/mnt/3fs/mooncake";
+    std::string fs_adapter_type = "hf3fs";
+    std::string allocator_type = "shard";
+    bool enable_health_check = false;
+    int shard_count = 64;
+    uint64_t shard_capacity = 4ULL * 1024 * 1024 * 1024;
+    uint64_t bucket_capacity = 1ULL * 1024 * 1024 * 1024;
+    int64_t max_bucket_count = 64;
+    uint64_t alignment = 4096;
+    bool single_tenant = true;
+    bool eviction_enabled = true;
+    double eviction_high_watermark = 0.9;
+    double eviction_low_watermark = 0.7;
+    std::chrono::seconds deferred_free_duration{30};
+    std::chrono::seconds eviction_check_interval{5};
+
+    bool Validate() const;
+    bool ValidateForAllocator() const;
+    static DistributedStorageConfig FromEnvironment();
+    std::string FormatStr() const;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/file_per_key_config.h b/mooncake-store/include/config/file_per_key_config.h
new file mode 100644
index 0000000000..8f3bc6bce6
--- /dev/null
+++ b/mooncake-store/include/config/file_per_key_config.h
@@ -0,0 +1,17 @@
+#pragma once
+
+#include <string>
+
+namespace mooncake {
+
+struct FilePerKeyConfig {
+    std::string fsdir = "file_per_key_dir";  // Subdirectory name
+
+    bool enable_eviction = true;  // Enable eviction for storage
+
+    bool Validate() const;
+
+    static FilePerKeyConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/offset_allocator_backend_config.h b/mooncake-store/include/config/offset_allocator_backend_config.h
new file mode 100644
index 0000000000..ed48f0eabb
--- /dev/null
+++ b/mooncake-store/include/config/offset_allocator_backend_config.h
@@ -0,0 +1,66 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace mooncake {
+
+enum class OffsetEvictionPolicy {
+    NONE,  // No eviction
+    FIFO,  // Evict oldest key first (by insertion order)
+    LRU,   // Approximate LRU via cross-shard sampling (phase 2)
+};
+
+enum class OffsetPersistMode {
+    kDisabled,  // No persistence (default)
+    kRelaxed,   // Periodic checkpoint
+    kStrict,    // Every BatchOffload is durable
+};
+
+struct OffsetAllocatorBackendConfig {
+    OffsetEvictionPolicy eviction_policy = OffsetEvictionPolicy::NONE;
+
+    // Watermark thresholds: eviction triggers when total_size_ exceeds high,
+    // drives down to low. 0 = auto-resolved in Init() from ratios.
+    int64_t high_watermark_bytes = 0;
+    int64_t low_watermark_bytes = 0;
+    double high_ratio = 0.90;
+    double low_ratio = 0.80;
+
+    // Key-count watermarks (symmetric with byte watermarks).
+    // high triggers eviction, drives down to low.
+    int64_t high_watermark_keys = 0;
+    int64_t low_watermark_keys = 0;
+    double keys_high_ratio = 0.95;
+    double keys_low_ratio = 0.90;
+
+    // Eviction caps
+    size_t max_evict_per_offload = 4096;
+    size_t fallback_evict_batch = 16;
+
+    // Allocator node capacity override.
+    // 0 = auto-derived from capacity_ / kMinObjectSize (capped at RAM budget).
+    // Must be <= UINT32_MAX (OffsetAllocator::create takes uint32
+    // max_capacity).
+    int64_t max_capacity_nodes = 0;
+
+    bool Validate() const;
+
+    static OffsetAllocatorBackendConfig FromEnvironment();
+
+    // ---- Persistence settings ----
+    OffsetPersistMode persist_mode = OffsetPersistMode::kDisabled;
+    int64_t persist_interval_seconds = 60;
+
+    // ---- Record integrity ----
+    // When true (default), every written record carries a CRC-32C over
+    // header-prefix + key + value (RecordHeader::kFlagHasCrc), verified
+    // once on recovery.  Disable only when torn writes are otherwise
+    // impossible (kStrict mode on storage that honors fsync ordering,
+    // e.g. power-loss-protected NVMe) or when values never pass through
+    // the CPU (future DMA/GDS writers): unchecksummed records are then
+    // validated by checkpoint ordering (seq guard) alone.
+    bool enable_record_crc = true;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/replica_selection_config.h b/mooncake-store/include/config/replica_selection_config.h
new file mode 100644
index 0000000000..2dff392b6e
--- /dev/null
+++ b/mooncake-store/include/config/replica_selection_config.h
@@ -0,0 +1,11 @@
+#pragma once
+
+namespace mooncake {
+
+struct ReplicaSelectionConfig {
+    bool remote_scoring_enabled = false;
+
+    static ReplicaSelectionConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/rpc_protocol_config.h b/mooncake-store/include/config/rpc_protocol_config.h
new file mode 100644
index 0000000000..be8894c492
--- /dev/null
+++ b/mooncake-store/include/config/rpc_protocol_config.h
@@ -0,0 +1,11 @@
+#pragma once
+
+namespace mooncake {
+
+struct RpcProtocolConfig {
+    bool use_rdma{false};
+
+    static RpcProtocolConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config/rpc_timeout_config.h b/mooncake-store/include/config/rpc_timeout_config.h
new file mode 100644
index 0000000000..3b20496cce
--- /dev/null
+++ b/mooncake-store/include/config/rpc_timeout_config.h
@@ -0,0 +1,16 @@
+#pragma once
+
+#include <chrono>
+#include <optional>
+
+namespace mooncake {
+
+struct RpcTimeoutConfig {
+    // An absent override leaves the caller's connection policy unchanged.
+    std::optional<std::chrono::milliseconds> request_timeout;
+    std::optional<std::chrono::milliseconds> connect_timeout;
+
+    static RpcTimeoutConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/config_helper.h b/mooncake-store/include/config_helper.h
index 86b9ec3518..7b5a06e912 100644
--- a/mooncake-store/include/config_helper.h
+++ b/mooncake-store/include/config_helper.h
@@ -20,14 +20,8 @@ class RequiredParam {
     RequiredParam() : name_(nullptr) {}
     RequiredParam(const char* name) : name_(name) {}
 
-    // Add copy constructor
-    RequiredParam(const RequiredParam& other) { value_ = other.value_; }
-
-    // Add copy assignment operator
-    RequiredParam& operator=(const RequiredParam& other) {
-        value_ = other.value_;
-        return *this;
-    }
+    RequiredParam(const RequiredParam&) = default;
+    RequiredParam& operator=(const RequiredParam&) = default;
 
     /**
      * @brief Assignment operator to set the value
@@ -95,4 +89,4 @@ class RequiredParam {
     const char* name_;
 };
 
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-store/include/device/cuda_ipc_buffer.h b/mooncake-store/include/device/cuda_ipc_buffer.h
index 3a6821482f..4a53c7fa16 100644
--- a/mooncake-store/include/device/cuda_ipc_buffer.h
+++ b/mooncake-store/include/device/cuda_ipc_buffer.h
@@ -11,6 +11,9 @@ namespace device {
 tl::expected<CudaIpcBufferHandle, ErrorCode> ExportCudaIpcBuffer(
     const void *ptr, size_t size);
 
+tl::expected<void, ErrorCode> SynchronizeCudaStream(int32_t device_id,
+                                                    uintptr_t stream_handle);
+
 class CudaIpcBufferMapping {
    public:
     CudaIpcBufferMapping() = default;
diff --git a/mooncake-store/include/device/runtime_accelerator.h b/mooncake-store/include/device/runtime_accelerator.h
index 90ba28466a..e668b2721a 100644
--- a/mooncake-store/include/device/runtime_accelerator.h
+++ b/mooncake-store/include/device/runtime_accelerator.h
@@ -23,6 +23,10 @@ class RuntimeAccelerator {
 
     bool CopyFromHost(void* dst, const void* src, size_t size) const;
 
+    // Copy between two pointers that may each be host or device resident;
+    // falls back to memcpy when neither side is on a known accelerator.
+    bool CopyAuto(void* dst, const void* src, size_t size) const;
+
    private:
     std::vector<const AcceleratorDevice*> devices_;
 };
diff --git a/mooncake-store/include/dummy_client.h b/mooncake-store/include/dummy_client.h
index 7c642e91e8..5a4777a030 100644
--- a/mooncake-store/include/dummy_client.h
+++ b/mooncake-store/include/dummy_client.h
@@ -1,5 +1,7 @@
 #pragma once
 
+#include "common/result.h"
+
 #include <atomic>
 #include <csignal>
 #include <mutex>
@@ -19,6 +21,7 @@ namespace mooncake {
 class DummyClient : public PyClient {
    public:
     DummyClient();
+    // Drains in-flight RPCs before the pool member is released (#3909).
     ~DummyClient();
 
     int64_t unregister_shm();
@@ -68,6 +71,15 @@ class DummyClient : public PyClient {
         const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
         const QueryResultCache *query_result_cache = nullptr) override;
 
+    std::vector<std::vector<std::vector<int64_t>>>
+    get_into_ranges_from_snapshot(
+        const std::vector<void *> &buffers,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const QueryResultCache &query_result_cache) override;
+
     std::vector<tl::expected<QueryResult, ErrorCode>> batch_query(
         const std::vector<std::string> &keys) override;
 
@@ -107,6 +119,15 @@ class DummyClient : public PyClient {
         const std::vector<CudaIpcWriteRequest> &requests,
         const ReplicateConfig &config = ReplicateConfig{});
 
+    std::vector<int> batch_upsert_from_cuda_ipc(
+        const std::vector<CudaIpcWriteRequest> &requests,
+        const ReplicateConfig &config = ReplicateConfig{});
+
+    std::vector<int> batch_upsert_from_multi_buffers(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config = ReplicateConfig{}) override;
     std::shared_ptr<BufferHandle> get_buffer(const std::string &key);
 
     std::vector<std::shared_ptr<BufferHandle>> batch_get_buffer(
@@ -162,6 +183,10 @@ class DummyClient : public PyClient {
 
     std::vector<int> batchIsExist(const std::vector<std::string> &keys);
 
+    int probeKey(const std::string &key);
+
+    std::vector<int> batchProbeKey(const std::vector<std::string> &keys);
+
     int64_t getSize(const std::string &key);
 
     std::map<std::string, std::vector<Replica::Descriptor>>
@@ -190,6 +215,57 @@ class DummyClient : public PyClient {
     std::optional<BufferHandle> allocate_client_buffer(size_t size) override;
 
    private:
+    struct PreparedBuffer {
+        void *original = nullptr;
+        void *dummy = nullptr;
+        size_t size = 0;
+        std::unique_ptr<BufferHandle> staging;
+        bool copy_back = false;
+    };
+
+    bool is_device_buffer(void *buffer) const;
+    bool is_dummy_shm_buffer(void *buffer, size_t size) const;
+    std::optional<size_t> external_buffer_remaining(void *buffer) const;
+    bool is_registered_buffer(void *buffer, size_t size) const;
+    int register_external_buffer(void *buffer, size_t size);
+    int unregister_external_buffer(void *buffer);
+#if defined(USE_ASCEND_DIRECT)
+    std::optional<size_t> registered_ascend_buffer_remaining(
+        void *buffer) const;
+#endif
+    std::optional<PreparedBuffer> prepare_buffer(void *buffer, size_t size,
+                                                 bool copy_to_staging,
+                                                 bool copy_back = false);
+    std::optional<PreparedBuffer> prepare_ranged_read_buffer(
+        void *buffer, std::vector<std::vector<size_t>> &dst_offsets,
+        const std::vector<std::vector<size_t>> &sizes);
+    bool copy_from_staging(const PreparedBuffer &buffer, size_t size,
+                           size_t offset = 0, size_t staging_offset = 0) const;
+
+    struct PreparedMultiBuffers {
+        std::vector<PreparedBuffer> buffers;
+        std::vector<std::vector<uint64_t>> dummy_buffers;
+    };
+    std::optional<PreparedMultiBuffers> prepare_multi_buffers(
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        bool copy_to_staging = true, bool copy_back = false);
+
+    struct ExternalBufferRegistration {
+        size_t size = 0;
+        size_t references = 0;
+    };
+    using BufferRegistrationMap =
+        std::unordered_map<uintptr_t, ExternalBufferRegistration>;
+    enum class BufferRegistrationAction { kReject, kFirst, kRetained };
+    enum class BufferReleaseAction { kReject, kFinal, kRetained };
+    static BufferRegistrationAction retain_buffer_registration(
+        BufferRegistrationMap &registrations, uintptr_t base, size_t size);
+    static BufferReleaseAction release_buffer_registration(
+        BufferRegistrationMap &registrations, uintptr_t base);
+    mutable std::mutex registered_external_buffers_mutex_;
+    BufferRegistrationMap registered_external_buffers_;
+
     ErrorCode connect(const std::string &server_address);
 
     int register_ascend_shm(const ShmHelper::ShmSegment *shm,
@@ -203,8 +279,9 @@ class DummyClient : public PyClient {
 
     int unregister_device_buffer_for_reconnect(void *buffer);
 
-    [[nodiscard]] std::vector<ShmHelper::ShmSegment>
-    get_registered_device_buffers() const;
+    int reregister_fabric_buffers();
+
+    int reregister_device_buffers();
 #endif
 
     /**
@@ -249,6 +326,7 @@ class DummyClient : public PyClient {
     }
 
     RpcClientPool client_accessor_;
+    RpcDrainGuard rpc_drain_;
 
     // The client identification.
     const UUID client_id_;
@@ -278,8 +356,10 @@ class DummyClient : public PyClient {
     std::atomic<bool> connected_{false};
 
 #if defined(USE_ASCEND_DIRECT)
+    mutable std::mutex external_fabric_registration_mutex_;
     mutable std::mutex registered_device_buffers_mutex_;
-    std::unordered_map<uint64_t, size_t> registered_device_buffers_;
+    // Tracks directly mapped Ascend device and Fabric host buffers.
+    BufferRegistrationMap registered_device_buffers_;
 #endif
 
     // Ascend physical device id for dummy-real RPC to real, set in setup_dummy
diff --git a/mooncake-store/include/dynamic_replication_lease_table.h b/mooncake-store/include/dynamic_replication_lease_table.h
new file mode 100644
index 0000000000..1f35d4f948
--- /dev/null
+++ b/mooncake-store/include/dynamic_replication_lease_table.h
@@ -0,0 +1,156 @@
+#pragma once
+
+// The in-flight replica-action leases for one tenant, keyed by proposal id.
+//
+// A proposal is not an object: the client asks for a replica to be added or
+// removed, the master answers with a lease that the client must act inside, and
+// the lease expires if it does not. Several proposals may be in flight for the
+// same object key, so the table cannot fold into a per-object entry, and an
+// object teardown has to retract whatever is still in flight for its key.
+//
+// Three indexes share one lock so that no query scans the table: the proposal
+// id finds a lease, the object key finds the proposals in flight for it, and a
+// deadline heap orders the expiry sweep.
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <optional>
+#include <queue>
+#include <shared_mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include <boost/functional/hash.hpp>
+
+#include "common/transparent_string_hash.h"
+#include "rpc_types.h"
+#include "types.h"
+
+namespace mooncake {
+
+class DynamicReplicationLeaseTable {
+   public:
+    // std::nullopt when no lease is recorded for the proposal.
+    [[nodiscard]] std::optional<ReplicaActionLease> Find(
+        const UUID& proposal_id) const {
+        std::shared_lock<std::shared_mutex> lock(mutex_);
+        const auto it = leases_.find(proposal_id);
+        return it == leases_.end()
+                   ? std::nullopt
+                   : std::make_optional<ReplicaActionLease>(it->second);
+    }
+
+    // Record the lease, replacing any lease already held for the proposal.
+    void Put(const UUID& proposal_id, ReplicaActionLease lease) {
+        std::unique_lock<std::shared_mutex> lock(mutex_);
+        const auto it = leases_.find(proposal_id);
+        if (it == leases_.end()) {
+            by_key_[lease.key].insert(proposal_id);
+        } else if (it->second.key != lease.key) {
+            Unindex(it->second.key, proposal_id);
+            by_key_[lease.key].insert(proposal_id);
+        }
+        const int64_t expire_at = lease.expire_at_ms_epoch;
+        leases_.insert_or_assign(proposal_id, std::move(lease));
+        // The deadline this replaces stays in the heap and is dropped when it
+        // surfaces: a node only erases the lease it still names with the same
+        // deadline, and a lease carrying that deadline is expired anyway.
+        deadlines_.push(Deadline{expire_at, proposal_id});
+    }
+
+    // True when a lease was recorded for the proposal.
+    [[nodiscard]] bool Remove(const UUID& proposal_id) {
+        std::unique_lock<std::shared_mutex> lock(mutex_);
+        const auto it = leases_.find(proposal_id);
+        if (it == leases_.end()) {
+            return false;
+        }
+        Unindex(it->second.key, proposal_id);
+        leases_.erase(it);
+        return true;
+    }
+
+    // Retract every lease for an object key, for a teardown that must not leave
+    // a client acting on a key that is gone.
+    void EraseForObject(std::string_view key) {
+        std::unique_lock<std::shared_mutex> lock(mutex_);
+        const auto it = by_key_.find(key);
+        if (it == by_key_.end()) {
+            return;
+        }
+        for (const UUID& proposal_id : it->second) {
+            leases_.erase(proposal_id);
+        }
+        by_key_.erase(it);
+    }
+
+    // Drop the leases whose deadline has passed.
+    void EraseExpired(std::chrono::system_clock::time_point now) {
+        const int64_t now_ms =
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                now.time_since_epoch())
+                .count();
+        std::unique_lock<std::shared_mutex> lock(mutex_);
+        while (!deadlines_.empty()) {
+            const Deadline& next = deadlines_.top();
+            if (next.expire_at_ms_epoch >= now_ms) {
+                break;
+            }
+            const Deadline expired = next;
+            deadlines_.pop();
+            const auto it = leases_.find(expired.proposal_id);
+            if (it == leases_.end() ||
+                it->second.expire_at_ms_epoch != expired.expire_at_ms_epoch) {
+                continue;  // already gone, or superseded by a later deadline
+            }
+            Unindex(it->second.key, expired.proposal_id);
+            leases_.erase(it);
+        }
+    }
+
+    // True when no lease is in flight.
+    [[nodiscard]] bool Empty() const {
+        std::shared_lock<std::shared_mutex> lock(mutex_);
+        return leases_.empty();
+    }
+
+   private:
+    // Earliest deadline first.
+    struct Deadline {
+        int64_t expire_at_ms_epoch;
+        UUID proposal_id;
+
+        bool operator>(const Deadline& other) const {
+            return expire_at_ms_epoch > other.expire_at_ms_epoch;
+        }
+    };
+
+    void Unindex(std::string_view key, const UUID& proposal_id) {
+        const auto it = by_key_.find(key);
+        if (it == by_key_.end()) {
+            return;
+        }
+        it->second.erase(proposal_id);
+        if (it->second.empty()) {
+            by_key_.erase(it);
+        }
+    }
+
+    mutable std::shared_mutex mutex_;
+    std::unordered_map<UUID, ReplicaActionLease, boost::hash<UUID>> leases_;
+    // The proposals in flight per object key, so a teardown does not scan.
+    std::unordered_map<std::string, std::unordered_set<UUID, boost::hash<UUID>>,
+                       TransparentStringHash, std::equal_to<>>
+        by_key_;
+    // One node per Put, so a repeat leaves a superseded node behind.
+    std::priority_queue<Deadline, std::vector<Deadline>, std::greater<>>
+        deadlines_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/engram/engram_store.h b/mooncake-store/include/engram/engram_store.h
index b655bd60ac..b0a3041359 100644
--- a/mooncake-store/include/engram/engram_store.h
+++ b/mooncake-store/include/engram/engram_store.h
@@ -1,11 +1,14 @@
 #pragma once
 
 #include <cstdint>
+#include <map>
 #include <memory>
+#include <mutex>
 #include <string>
 #include <vector>
 
 #include "engram/engram_store_config.h"
+#include "replica.h"
 
 namespace mooncake {
 
@@ -14,7 +17,7 @@ class PyClient;
 namespace engram {
 
 /**
- * Mooncake backend for Engram embedding tables.
+ * Mooncake backend for all layers of a model's Engram embedding tables.
  *
  * This class intentionally owns only storage-side concerns:
  * - per-head table naming/layout in Mooncake Store
@@ -26,57 +29,66 @@ namespace engram {
  */
 class EngramStore {
    public:
-    EngramStore(int layer_id, const EngramStoreConfig& config,
+    EngramStore(const std::map<int, EngramStoreConfig>& layers,
                 std::shared_ptr<PyClient> store = nullptr);
 
     ~EngramStore() = default;
 
+    // Bind immutable caller-owned tables before lookup, without a Store client.
+    // The caller must keep these buffers alive until this EngramStore is
+    // destroyed.
+    int bind_local(int layer_id, const std::vector<const void*>& buffers,
+                   const std::vector<size_t>& sizes);
+
     /**
      * Lookup embedding rows for a batch of precomputed row IDs.
      * @param row_ids [B, L, H] precomputed row IDs, where H == num_heads
-     * @param output [B, L, H, D] output buffer
+     * Store-backed lookup requires registered output; local lookup does not.
+     * @param output [B, L, H, row_bytes] contiguous byte output buffer
      * @param output_size Size of output buffer in bytes
      * @return 0 on success, negative on error
      */
-    int lookup_rows(
-        const std::vector<std::vector<std::vector<int64_t>>>& row_ids,
-        void* output, size_t output_size) const;
+    int lookup_into(int layer_id, const int64_t* row_ids, int B, int L,
+                    void* output, size_t output_size) const;
 
-    /**
-     * Fast path for contiguous row-id buffers with shape [B, L, H].
-     */
-    int lookup_rows_contiguous(const int64_t* row_ids, int B, int L,
-                               void* output, size_t output_size) const;
-
-    std::vector<int64_t> get_table_vocab_sizes() const;
-    std::vector<std::string> get_store_keys() const;
-    int get_num_heads() const;
-    int get_embedding_dim() const;
+    std::vector<int> get_layer_ids() const;
+    std::vector<int64_t> get_table_vocab_sizes(int layer_id) const;
+    std::vector<std::string> get_store_keys(int layer_id) const;
+    int get_num_heads(int layer_id) const;
+    int get_row_bytes(int layer_id) const;
 
     /**
-     * Remove all head tables owned by this EngramStore layer from Mooncake
+     * Remove all head tables owned by the selected layer from Mooncake
      * Store. Missing keys are ignored. Returns the number of removed tables on
      * success, or a negative error code on failure.
      */
-    int remove_from_store(bool force = false);
+    int remove_from_store(int layer_id, bool force = false);
 
     /**
      * Populate Store with per-head embedding tensors.
-     * @param embedding_buffers Buffers for each head [N_h, D]
+     * @param embedding_buffers Byte buffers for each head [N_h, row_bytes]
      * @param buffer_sizes Size in bytes for each buffer
      * @return 0 on success, negative on error
      */
-    int populate(const std::vector<void*>& embedding_buffers,
-                 const std::vector<size_t>& buffer_sizes);
+    int populate(int layer_id, const std::vector<void*>& embedding_buffers,
+                 const std::vector<size_t>& buffer_sizes,
+                 const ReplicateConfig& config = ReplicateConfig{});
 
    private:
-    int lookup_rows_flat(const int64_t* row_ids, int B, int L, void* output,
-                         size_t output_size) const;
-
     std::shared_ptr<PyClient> store_;
-    std::vector<int64_t> table_vocab_sizes_;
-    int embedding_dim_;
-    std::vector<std::string> embed_keys_;
+    struct QueryCacheEntry;
+    struct Layer {
+        EngramStoreConfig config;
+        std::vector<std::string> keys;
+        std::vector<const void*> local_tables;
+    };
+    const Layer& get_layer(int layer_id) const;
+    std::shared_ptr<const QueryCacheEntry> get_query_cache(
+        int layer_id, const std::vector<std::string>& keys) const;
+    void invalidate_query_cache(int layer_id) const;
+    std::map<int, Layer> layers_;
+    mutable std::mutex query_cache_mutex_;
+    mutable std::map<int, std::shared_ptr<QueryCacheEntry>> query_cache_;
 };
 
 }  // namespace engram
diff --git a/mooncake-store/include/engram/engram_store_config.h b/mooncake-store/include/engram/engram_store_config.h
index 09578d4ddd..6f9887a455 100644
--- a/mooncake-store/include/engram/engram_store_config.h
+++ b/mooncake-store/include/engram/engram_store_config.h
@@ -15,7 +15,8 @@ namespace engram {
  */
 struct EngramStoreConfig {
     std::vector<int64_t> table_vocab_sizes = {1024};
-    int embedding_dim = 64;
+    // Required positive width of an opaque byte row; no dtype interpretation.
+    int row_bytes = 0;
 };
 
 }  // namespace engram
diff --git a/mooncake-store/include/etcd_helper.h b/mooncake-store/include/etcd_helper.h
index b0d851c5b6..f3ff11df5e 100644
--- a/mooncake-store/include/etcd_helper.h
+++ b/mooncake-store/include/etcd_helper.h
@@ -1,7 +1,10 @@
 #pragma once
 
 #include <glog/logging.h>
+#include <ylt/util/tl/expected.hpp>
+
 #include <string>
+#include <string_view>
 #include <vector>
 
 #include "types.h"
@@ -28,8 +31,9 @@ class EtcdHelper {
 
     /*
      * @brief Reset the global store etcd client and reconnect to the given
-     *        endpoints. This cancels active store watches/keepalives in the Go
-     *        wrapper and creates a fresh clientv3.Client.
+     *        endpoints. This cancels active store watches and maintenance
+     *        sessions. Each lease keep-alive uses an independent client and
+     *        continues.
      * @param etcd_endpoints: The endpoints of the etcd store client.
      * @return: Error code.
      */
@@ -61,6 +65,15 @@ class EtcdHelper {
                                      EtcdLeaseId lease_id,
                                      EtcdRevisionId& revision_id);
 
+    static ErrorCode AcquireMaintenanceSession(std::string_view key,
+                                               int64_t lease_ttl,
+                                               int64_t& session_handle,
+                                               EtcdLeaseId& lease_id,
+                                               EtcdRevisionId& create_revision);
+    static ErrorCode CloseMaintenanceSession(int64_t session_handle);
+    static tl::expected<bool, ErrorCode> MaintenanceSessionAlive(
+        int64_t session_handle);
+
     /*
      * @brief Batch create key-value pairs in a single transaction.
      *        Fails if any key already exists.
@@ -74,17 +87,22 @@ class EtcdHelper {
     enum class TxnCompareKind {
         kValueEquals = 0,
         kKeyNotExists = 1,
+        // Compare the key's creation revision to expected_revision.
+        kCreateRevisionEquals = 2,
     };
 
     struct TxnCompare {
         std::string key;
         TxnCompareKind kind{TxnCompareKind::kValueEquals};
         std::string expected_value;
+        // Used only by kCreateRevisionEquals.
+        EtcdRevisionId expected_revision{0};
     };
 
     struct TxnPut {
         std::string key;
         std::string value;
+        bool preserve_lease{false};
     };
 
     /*
diff --git a/mooncake-store/include/file_interface.h b/mooncake-store/include/file_interface.h
index 52c267451d..44f5c3d421 100644
--- a/mooncake-store/include/file_interface.h
+++ b/mooncake-store/include/file_interface.h
@@ -184,12 +184,11 @@ class PosixFile : public StorageFile {
 #ifdef USE_URING
 /**
  * @class UringFile
- * @brief StorageFile backed by a process-wide shared io_uring ring.
+ * @brief StorageFile backed by a thread-local io_uring ring.
  *
- * All UringFile instances share a single SharedUringRing singleton, so
- * construction and destruction only register/unregister an fd slot — no
- * per-file io_uring_queue_init / io_uring_queue_exit (no mmap/munmap,
- * no TLB shootdown).
+ * UringFile instances used by the same thread share one ring. Each thread
+ * lazily creates its own ring, avoiding cross-thread submission locks and
+ * per-file io_uring_queue_init / io_uring_queue_exit.
  */
 class UringFile : public StorageFile {
    public:
@@ -222,8 +221,11 @@ class UringFile : public StorageFile {
         void *buf;
         size_t len;
         off_t off;
+        size_t bytes_read = 0;
+        ErrorCode error = ErrorCode::OK;
+        bool completed = false;
     };
-    tl::expected<size_t, ErrorCode> batch_read(const ReadDesc *descs, int cnt);
+    tl::expected<void, ErrorCode> batch_read(ReadDesc *descs, int cnt);
 
     // Flush data to stable storage via IORING_FSYNC_DATASYNC.
     // Must be called after write_aligned and before writing dependent metadata.
diff --git a/mooncake-store/include/file_storage.h b/mooncake-store/include/file_storage.h
index 501a80c66f..cc61574dcc 100644
--- a/mooncake-store/include/file_storage.h
+++ b/mooncake-store/include/file_storage.h
@@ -20,6 +20,30 @@ class FileStorage {
 
     void RemoveAll();
 
+    /**
+     * @brief Deregisters this store's disk tier from the master, then waits out
+     * a grace period so offload reads already in flight can finish.
+     *
+     * Meant for a shutdown hook that runs before the process is signalled. Once
+     * this returns, the master no longer names this store as the owner of any
+     * offloaded key, so a reader gets a clean miss instead of a peer that is
+     * about to disappear. Unlike a memory replica, which the NIC serves without
+     * the process, a disk replica is read and pushed by this process -- hence
+     * the grace period rather than an immediate exit.
+     *
+     * Latches offloading off first: the heartbeat re-mounts the segment
+     * whenever the master answers SEGMENT_NOT_FOUND, which would otherwise
+     * undo this within one heartbeat interval. The latch and the
+     * deregistration happen under offloading_mutex_, the lock the heartbeat
+     * holds across its master RPCs, so a tick that read the latch before it
+     * was set cannot resume after the deregistration and re-mount: it either
+     * finished before the drain latched, or it re-checks the latch when it
+     * acquires the lock. The latch is not reversible on success; the process
+     * is expected to exit.
+     */
+    tl::expected<void, ErrorCode> DrainLocalDiskSegment(
+        uint64_t grace_period_ms);
+
     /**
      * @brief Result of BatchGet operation containing batch_id and buffer
      * pointers.
@@ -29,6 +53,14 @@ class FileStorage {
         std::vector<uint64_t> pointers;
     };
 
+    struct LocalBatchResult {
+        std::vector<uint64_t> pointers;
+
+       private:
+        friend class FileStorage;
+        std::shared_ptr<void> owner;
+    };
+
     /**
      * @brief Reads multiple key-value (KV) entries from local storage and
      * forwards them to a remote node.
@@ -41,6 +73,33 @@ class FileStorage {
         const std::vector<std::string>& keys,
         const std::vector<int64_t>& sizes);
 
+    tl::expected<LocalBatchResult, ErrorCode> BatchGetLocal(
+        const std::vector<std::string>& keys,
+        const std::vector<int64_t>& sizes);
+
+    [[nodiscard]] bool HasPinnedRestoreArena() const {
+        return pinned_restore_arena_allocator_ != nullptr;
+    }
+
+    // Allocate request-scoped staging from the fixed-capacity accelerator-
+    // pinned restore arena. The returned handle releases its sub-allocation
+    // back to the arena; FileStorage retains ownership of the backing memory.
+    [[nodiscard]] std::optional<BufferHandle> AllocatePinnedStagingBuffer(
+        size_t size) {
+        if (!pinned_restore_arena_allocator_) return std::nullopt;
+        return pinned_restore_arena_allocator_->allocate(size);
+    }
+
+    /**
+     * @brief Reports whether the backend still holds an entry for the key.
+     *
+     * Answers existence only, without allocating read buffers. After a
+     * physical wipe the per-key backend's filesystem lookup and the bucket
+     * backend's in-memory index both report false, which is exactly the
+     * divergence a dangling-replica probe needs to detect.
+     */
+    tl::expected<bool, ErrorCode> Exists(const std::string& key);
+
     FileStorageConfig config_;
 
     /**
@@ -54,6 +113,14 @@ class FileStorage {
    private:
     friend class FileStorageTest;
     friend class FileStoragePromotionTest;
+    // TEST_F bodies are generated subclasses and do not inherit the fixture's
+    // friendship, so the dangling-replica tests are friended by their
+    // generated class names (plain friend, no gtest include in a production
+    // header).
+    friend class
+        FileStorageTest_PutAfterPhysicalWipeHealsDanglingLocalDiskReplica_Test;
+    friend class
+        FileStorageTest_PutAfterPhysicalWipeHealsDanglingLocalDiskReplicaOnBucket_Test;
     struct AllocatedBatch {
         uint64_t batch_id;
         std::vector<BufferHandle> handles;
@@ -142,8 +209,12 @@ class FileStorage {
     tl::expected<void, ErrorCode> RegisterLocalMemory();
 
     tl::expected<std::shared_ptr<AllocatedBatch>, ErrorCode> AllocateBatch(
-        const std::vector<std::string>& keys,
-        const std::vector<int64_t>& sizes);
+        const std::vector<std::string>& keys, const std::vector<int64_t>& sizes,
+        ClientBufferAllocator& allocator);
+
+    tl::expected<std::shared_ptr<AllocatedBatch>, ErrorCode> LoadBatch(
+        const std::vector<std::string>& keys, const std::vector<int64_t>& sizes,
+        bool prefer_pinned);
 
     void ClientBufferGCThreadFunc();
 
@@ -157,8 +228,10 @@ class FileStorage {
     std::shared_ptr<Client> client_;
     SsdMetric* ssd_metric_{nullptr};
     std::string local_rpc_addr_;
-    // Pinned host memory pool for GPU D2H staging in OffloadObjects
+    // Pinned memory for GPU staging and SSD-to-GPU restores.
     std::unique_ptr<PinnedBufferPool> pinned_buffer_pool_;
+    PinnedBufferPool::Buffer pinned_restore_arena_;
+    std::shared_ptr<ClientBufferAllocator> pinned_restore_arena_allocator_;
     std::shared_ptr<StorageBackendInterface> storage_backend_;
     std::shared_ptr<ClientBufferAllocator> client_buffer_allocator_;
     mutable Mutex client_buffer_mutex_;
@@ -174,6 +247,13 @@ class FileStorage {
     std::thread client_buffer_gc_thread_;
     std::future<void> rescan_future_;
     std::atomic<bool> metadata_resync_pending_{false};
+    // Set by DrainLocalDiskSegment under offloading_mutex_. Stops the
+    // heartbeat -- which would otherwise re-mount the segment the drain just
+    // deregistered -- and aborts an in-flight metadata rescan. Checked at
+    // Heartbeat entry (fast path, also guards the rescan-retry block) and
+    // again under offloading_mutex_ before the heartbeat RPC, because a tick
+    // parked on that lock passed the entry check before the drain latched.
+    std::atomic<bool> draining_{false};
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/group_index.h b/mooncake-store/include/group_index.h
new file mode 100644
index 0000000000..af11643725
--- /dev/null
+++ b/mooncake-store/include/group_index.h
@@ -0,0 +1,140 @@
+#pragma once
+
+#include <array>
+#include <atomic>
+#include <cstddef>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include "common/transparent_string_hash.h"
+#include "lease.h"
+
+namespace mooncake {
+
+// GroupIndex: group_id -> {shared Lease, member keys}. A group is not a
+// container of objects: it is a membership table plus one shared Lease, and
+// that lease is the all-or-none unit eviction reads (every member's
+// ObjectMetadata points at it). The read path extends it on a member hit
+// without touching this index. A group is dropped with its last member, and a
+// later AddMember starts a fresh group rather than reviving the old one.
+//
+// The table is striped so that writes to distinct groups do not serialize on
+// one lock; every operation on a group hashes to the same stripe. A stripe is
+// a map plus a lock and every tenant holds one table, so the count trades
+// tenant memory for write concurrency and is a template parameter rather than
+// a constant.
+template <size_t StripeCount>
+class StripedGroupIndex {
+   public:
+    // Materialize the group on demand, register the member and return the
+    // group's single shared Lease under one lock section, so a lease and its
+    // membership cannot disagree. Every member of a group shares that one
+    // lease, and the metadata that receives it is what keeps it alive: the
+    // group itself is dropped with its last member.
+    //
+    // Re-registering a member returns the same lease, because membership is a
+    // set and a repeat is not an error. An empty group_id is the ungrouped
+    // case: it joins no group and gets no lease, so no ungrouped object is ever
+    // registered here.
+    [[nodiscard]] std::shared_ptr<Lease> AddMember(
+        std::string_view group_id, std::string_view member_key) {
+        if (group_id.empty()) {
+            return nullptr;
+        }
+        auto& stripe = StripeFor(group_id);
+        std::unique_lock<std::shared_mutex> lock(stripe.mutex);
+        auto [it, inserted] = stripe.groups.try_emplace(std::string(group_id));
+        if (inserted) {
+            it->second.lease = std::make_shared<Lease>();
+            group_count_.fetch_add(1, std::memory_order_relaxed);
+        }
+        it->second.member_keys.insert(std::string(member_key));
+        return it->second.lease;
+    }
+
+    [[nodiscard]] bool RemoveMember(std::string_view group_id,
+                                    std::string_view member_key) {
+        auto& stripe = StripeFor(group_id);
+        std::unique_lock<std::shared_mutex> lock(stripe.mutex);
+        auto it = stripe.groups.find(group_id);
+        if (it == stripe.groups.end()) {
+            return false;
+        }
+        // Heterogeneous lookup, then erase by iterator: the container has no
+        // heterogeneous erase of its own.
+        const auto member = it->second.member_keys.find(member_key);
+        if (member == it->second.member_keys.end()) {
+            return false;
+        }
+        it->second.member_keys.erase(member);
+        if (it->second.Empty()) {
+            stripe.groups.erase(it);
+            group_count_.fetch_sub(1, std::memory_order_relaxed);
+        }
+        return true;
+    }
+
+    [[nodiscard]] std::vector<std::string> Members(
+        std::string_view group_id) const {
+        const auto& stripe = StripeFor(group_id);
+        std::shared_lock<std::shared_mutex> lock(stripe.mutex);
+        auto it = stripe.groups.find(group_id);
+        if (it == stripe.groups.end()) {
+            return {};
+        }
+        return {it->second.member_keys.begin(), it->second.member_keys.end()};
+    }
+
+    // Materialized groups, counted as they are created and dropped, so this
+    // does not take one lock per stripe.
+    [[nodiscard]] bool Empty() const {
+        return group_count_.load(std::memory_order_relaxed) == 0;
+    }
+
+   private:
+    struct GroupState {
+        std::unordered_set<std::string, TransparentStringHash, std::equal_to<>>
+            member_keys;
+        std::shared_ptr<Lease> lease;
+
+        bool Empty() const { return member_keys.empty(); }
+    };
+
+    struct Stripe {
+        mutable std::shared_mutex mutex;
+        std::unordered_map<std::string, GroupState, TransparentStringHash,
+                           std::equal_to<>>
+            groups;
+    };
+
+    Stripe& StripeFor(std::string_view group_id) {
+        return stripes_[StripeIndex(group_id)];
+    }
+    const Stripe& StripeFor(std::string_view group_id) const {
+        return stripes_[StripeIndex(group_id)];
+    }
+    // The same hash the tables use, so a group lands in one stripe no matter
+    // whether the caller holds a string or a view.
+    static size_t StripeIndex(std::string_view group_id) {
+        return TransparentStringHash{}(group_id) % StripeCount;
+    }
+
+    std::array<Stripe, StripeCount> stripes_;
+    // Groups materialized across every stripe. A count rather than a flag: the
+    // stripes that are not being written cannot tell whether they are the last
+    // group, so only a count can be lowered again.
+    std::atomic<size_t> group_count_{0};
+};
+
+// 64 stripes: the shipped default. A grouping-heavy workload can raise it by
+// instantiating the template with a larger count.
+using GroupIndex = StripedGroupIndex<64>;
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/kv/etcd_ha_kv_backend.h b/mooncake-store/include/ha/kv/etcd_ha_kv_backend.h
index ae58b5f93e..5e7d5d570d 100644
--- a/mooncake-store/include/ha/kv/etcd_ha_kv_backend.h
+++ b/mooncake-store/include/ha/kv/etcd_ha_kv_backend.h
@@ -10,6 +10,8 @@ class EtcdHaKvBackend : public HaKvBackend {
     ErrorCode Put(std::string_view key, std::string_view value) override;
     ErrorCode Range(std::string_view begin_key, std::string_view end_key,
                     size_t limit, std::vector<KvPair>& kvs) override;
+    ErrorCode DeleteRange(std::string_view begin_key,
+                          std::string_view end_key) override;
     bool SupportsTxn() const override;
     ErrorCode Txn(const KvTxn& txn) override;
 };
diff --git a/mooncake-store/include/ha/kv/ha_kv_backend.h b/mooncake-store/include/ha/kv/ha_kv_backend.h
index e48583774a..f5ef6b9b9d 100644
--- a/mooncake-store/include/ha/kv/ha_kv_backend.h
+++ b/mooncake-store/include/ha/kv/ha_kv_backend.h
@@ -16,12 +16,15 @@ struct KvPair {
 enum class KvCompareKind {
     kValueEquals,
     kKeyNotExists,
+    kCreateRevisionEquals,
 };
 
 struct KvCompare {
     std::string key;
     KvCompareKind kind{KvCompareKind::kValueEquals};
     std::string expected_value;
+    // Used only by kCreateRevisionEquals.
+    EtcdRevisionId expected_revision{0};
 };
 
 struct KvTxn {
@@ -38,6 +41,11 @@ class HaKvBackend {
     virtual ErrorCode Range(std::string_view begin_key,
                             std::string_view end_key, size_t limit,
                             std::vector<KvPair>& kvs) = 0;
+    // Delete [begin_key, end_key). Both bounds must be nonempty and finite.
+    // Equal bounds are a no-op for backends supporting deletion.
+    // Unsupported backends must return INVALID_PARAMS.
+    virtual ErrorCode DeleteRange(std::string_view begin_key,
+                                  std::string_view end_key) = 0;
     virtual bool SupportsTxn() const = 0;
     virtual ErrorCode Txn(const KvTxn& txn) = 0;
 };
diff --git a/mooncake-store/include/ha/leadership/backends/etcd/etcd_leader_coordinator.h b/mooncake-store/include/ha/leadership/backends/etcd/etcd_leader_coordinator.h
index 30e5c8e0b7..b59a5718a8 100644
--- a/mooncake-store/include/ha/leadership/backends/etcd/etcd_leader_coordinator.h
+++ b/mooncake-store/include/ha/leadership/backends/etcd/etcd_leader_coordinator.h
@@ -26,6 +26,8 @@ class EtcdLeaderCoordinator final : public LeaderCoordinator {
     tl::expected<AcquireLeadershipResult, ErrorCode> TryAcquireLeadership(
         const std::string& leader_address) override;
 
+    ErrorCode PublishServiceReady(const LeadershipSession& session) override;
+
     tl::expected<bool, ErrorCode> RenewLeadership(
         const LeadershipSession& session) override;
 
diff --git a/mooncake-store/include/ha/leadership/leader_coordinator.h b/mooncake-store/include/ha/leadership/leader_coordinator.h
index 923ca55ee0..c624d59154 100644
--- a/mooncake-store/include/ha/leadership/leader_coordinator.h
+++ b/mooncake-store/include/ha/leadership/leader_coordinator.h
@@ -28,6 +28,15 @@ class LeaderCoordinator {
     virtual tl::expected<AcquireLeadershipResult, ErrorCode>
     TryAcquireLeadership(const std::string& leader_address) = 0;
 
+    // Backends that advertise a service endpoint separately from election
+    // ownership override this after the RPC listener is ready. The default
+    // keeps the existing behavior for backends whose election record already
+    // is their service endpoint.
+    virtual ErrorCode PublishServiceReady(
+        const LeadershipSession& /*session*/) {
+        return ErrorCode::OK;
+    }
+
     virtual tl::expected<bool, ErrorCode> RenewLeadership(
         const LeadershipSession& session) = 0;
 
@@ -42,5 +51,20 @@ class LeaderCoordinator {
     virtual ErrorCode ReleaseLeadership(const LeadershipSession& session) = 0;
 };
 
+inline tl::expected<std::optional<MasterView>, ErrorCode>
+ReadCurrentViewOrWaitForReady(LeaderCoordinator& coordinator,
+                              std::chrono::milliseconds timeout) {
+    auto current_view = coordinator.ReadCurrentView();
+    if (!current_view || current_view->has_value()) {
+        return current_view;
+    }
+
+    auto ready_view = coordinator.WaitForViewChange(std::nullopt, timeout);
+    if (!ready_view) {
+        return tl::make_unexpected(ready_view.error());
+    }
+    return ready_view->current_view;
+}
+
 }  // namespace ha
 }  // namespace mooncake
diff --git a/mooncake-store/include/ha/leadership/master_service_supervisor.h b/mooncake-store/include/ha/leadership/master_service_supervisor.h
index f6538bf8da..dfdac3d67a 100644
--- a/mooncake-store/include/ha/leadership/master_service_supervisor.h
+++ b/mooncake-store/include/ha/leadership/master_service_supervisor.h
@@ -1,10 +1,51 @@
 #pragma once
 
+#include <atomic>
+#include <mutex>
+#include <utility>
+
 #include "master_config.h"
 
 namespace mooncake {
 namespace ha {
 
+namespace detail {
+
+class ServingStateGate {
+   public:
+    template <typename Action>
+    bool RunIfActive(Action&& action) {
+        std::lock_guard<std::mutex> lock(transition_mutex_);
+        if (shutdown_requested_.load(std::memory_order_acquire)) {
+            return false;
+        }
+        std::forward<Action>(action)();
+        return true;
+    }
+
+    template <typename Action>
+    bool RequestShutdown(Action&& action) {
+        std::lock_guard<std::mutex> lock(transition_mutex_);
+        const bool first_request =
+            !shutdown_requested_.exchange(true, std::memory_order_acq_rel);
+        if (!first_request) {
+            return false;
+        }
+        std::forward<Action>(action)();
+        return true;
+    }
+
+    bool IsActive() const {
+        return !shutdown_requested_.load(std::memory_order_acquire);
+    }
+
+   private:
+    std::atomic<bool> shutdown_requested_{false};
+    std::mutex transition_mutex_;
+};
+
+}  // namespace detail
+
 class MasterServiceSupervisor {
    public:
     explicit MasterServiceSupervisor(
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h b/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
index 94277049c2..2c72a6c5cf 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_standby_reader.h
@@ -16,6 +16,7 @@ class OpLogApplier;
 enum class OpLogBatchStandbyPollDisposition {
     OK,
     RETRYABLE,
+    REBOOTSTRAP_REQUIRED,
     FATAL,
 };
 
@@ -25,7 +26,10 @@ struct OpLogBatchStandbyPollResult {
     ErrorCode error{ErrorCode::OK};
     bool durable_prefix_present{false};
     size_t applied_entries{0};
+    // Complete batches processed in this poll, including before a later error.
+    size_t applied_batches{0};
     DurablePrefix durable_prefix{};
+    uint64_t compaction_floor{0};
 };
 
 class OpLogBatchStandbyReader {
@@ -34,14 +38,26 @@ class OpLogBatchStandbyReader {
                             OpLogApplier& applier);
 
     OpLogBatchStandbyPollResult PollOnce(size_t max_batches = 1024);
+    // Seed the reader after a materialized snapshot. The next poll starts at
+    // cursor.batch_id + 1 and validates the complete suffix.
+    ErrorCode SetBaselineCursor(const DurablePrefix& cursor);
+    ErrorCode ReadProducerView(ViewVersionId& producer_view_version) const {
+        return storage_.ReadProducerView(producer_view_version);
+    }
+    std::optional<DurablePrefix> GetLastAppliedDurablePrefix() const {
+        return last_applied_durable_prefix_;
+    }
 
    private:
+    OpLogBatchStandbyPollResult PollBatches(size_t max_batches, uint64_t floor);
     OpLogBatchStorage storage_;
     OpLogApplier& applier_;
     bool batch_format_seen_{false};
     std::optional<DurablePrefix> last_observed_prefix_;
+    std::optional<DurablePrefix> last_applied_durable_prefix_;
     std::optional<uint64_t> last_scanned_batch_last_seq_;
     uint64_t last_applied_batch_id_{0};
+    bool require_complete_history_{false};
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_storage.h b/mooncake-store/include/ha/oplog/oplog_batch_storage.h
index eade16b397..adc2f33f0e 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_storage.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_storage.h
@@ -14,15 +14,29 @@ class OpLogBatchStorage {
     OpLogBatchStorage(std::string cluster_id, HaKvBackend& backend);
 
     ErrorCode InitDurablePrefix(DurablePrefix& prefix);
+    ErrorCode ClaimProducerView(ViewVersionId producer_view_version);
+    ErrorCode ValidateProducerView(ViewVersionId producer_view_version) const;
+    ErrorCode ReadProducerView(ViewVersionId& producer_view_version) const;
+    ErrorCode ReadCompactionFloor(uint64_t& floor) const;
     ErrorCode ReadDurablePrefix(DurablePrefix& prefix);
     ErrorCode WriteBatchAndAdvancePrefix(const OpLogBatchRecord& batch,
                                          const DurablePrefix& expected_prefix);
+    ErrorCode WriteBatchAndAdvancePrefix(const OpLogBatchRecord& batch,
+                                         const DurablePrefix& expected_prefix,
+                                         ViewVersionId producer_view_version);
     ErrorCode ReadBatch(uint64_t batch_id, OpLogBatchRecord& batch);
     ErrorCode ReadBatchesAfter(uint64_t after_batch_id, size_t limit,
                                std::vector<OpLogBatchRecord>& batches);
+    // Idempotently delete records with id <= batch_id in this cluster only.
+    // Caller must first publish a reader-visible compaction floor covering
+    // this cutoff. Does not choose/validate the cutoff or retry backend errors.
+    ErrorCode DeleteBatchesThrough(uint64_t batch_id);
 
    private:
     bool IsValidClusterId() const;
+    ErrorCode WriteBatchAndAdvancePrefixImpl(
+        const OpLogBatchRecord& batch, const DurablePrefix& expected_prefix,
+        const ViewVersionId* producer_view_version);
     ErrorCode RejectLegacyLayout() const;
     ErrorCode ValidateDurablePrefixAtStartup(const DurablePrefix& prefix);
 
diff --git a/mooncake-store/include/ha/oplog/oplog_batch_types.h b/mooncake-store/include/ha/oplog/oplog_batch_types.h
index 4e315383c1..93cf35dd7b 100644
--- a/mooncake-store/include/ha/oplog/oplog_batch_types.h
+++ b/mooncake-store/include/ha/oplog/oplog_batch_types.h
@@ -15,6 +15,9 @@ static constexpr int kOpLogBatchIdWidth = 20;
 struct DurablePrefix {
     uint64_t batch_id{0};
     uint64_t last_seq{0};
+
+    friend bool operator==(const DurablePrefix&,
+                           const DurablePrefix&) = default;
 };
 
 struct BatchRecordRange {
@@ -44,6 +47,7 @@ std::string FormatOpLogBatchId(uint64_t batch_id);
 std::string BuildBatchRecordKey(const std::string& cluster_id,
                                 uint64_t batch_id);
 std::string BuildDurablePrefixKey(const std::string& cluster_id);
+std::string BuildProducerViewKey(const std::string& cluster_id);
 BatchRecordRange BuildBatchRecordRange(const std::string& cluster_id,
                                        uint64_t after_batch_id);
 
diff --git a/mooncake-store/include/ha/oplog/ordered_oplog_writer.h b/mooncake-store/include/ha/oplog/ordered_oplog_writer.h
index 1d4387d51a..1aa25b99e4 100644
--- a/mooncake-store/include/ha/oplog/ordered_oplog_writer.h
+++ b/mooncake-store/include/ha/oplog/ordered_oplog_writer.h
@@ -1,10 +1,14 @@
 #pragma once
 
+#include <chrono>
 #include <cstddef>
 #include <cstdint>
 #include <functional>
 #include <memory>
+#include <optional>
 
+#include <async_simple/Future.h>
+#include <async_simple/Promise.h>
 #include <ylt/util/tl/expected.hpp>
 
 #include "ha/oplog/oplog_batch_types.h"
@@ -15,11 +19,27 @@ namespace mooncake {
 struct OrderedOpLogWriterConfig {
     size_t max_entries_per_batch{1024};
     DurablePrefix initial_durable_prefix{};
+    std::chrono::milliseconds retry_timeout{0};
+};
+
+enum class OrderedOpLogWriterTerminalReason {
+    kRetryTimeout,
+    kFenced,
+    kNonRetryableWriteError,
+};
+
+struct OrderedOpLogWriterTerminalState {
+    ErrorCode error;
+    OrderedOpLogWriterTerminalReason reason;
+    DurablePrefix durable_prefix;
+    uint64_t occurred_at_ms;
 };
 
 class OrderedOpLogWriter {
    public:
     using DurableCallback = std::function<void(const OpLogEntry&)>;
+    using TerminalCallback =
+        std::function<void(const OrderedOpLogWriterTerminalState&)>;
     using WriteBatchFn =
         std::function<ErrorCode(const OpLogBatchRecord&, const DurablePrefix&)>;
 
@@ -53,19 +73,33 @@ class OrderedOpLogWriter {
     };
 
     OrderedOpLogWriter(OrderedOpLogWriterConfig config,
-                       WriteBatchFn write_batch);
-    ~OrderedOpLogWriter();
+                       WriteBatchFn write_batch,
+                       TerminalCallback terminal_callback = {});
+    virtual ~OrderedOpLogWriter();
 
     tl::expected<Reservation, ErrorCode> Reserve();
-    tl::expected<PendingHandle, ErrorCode> Commit(Reservation&& reservation,
-                                                  OpLogEntry entry,
-                                                  DurableCallback callback);
+    virtual tl::expected<PendingHandle, ErrorCode> Commit(
+        Reservation&& reservation, OpLogEntry entry, DurableCallback callback);
     void Abort(Reservation&& reservation);
 
+    // Return a future for durability, independently of callback completion,
+    // without blocking the calling thread. An already-covered sequence is
+    // immediately ready with OK, even after terminal failure or Stop().
+    // Otherwise, terminal failure completes it with the terminal error, and
+    // Stop() completes it with UNAVAILABLE_IN_CURRENT_STATUS. Promises are
+    // fulfilled outside the writer mutex. Callers can co_await the future and
+    // use via(executor) to select the continuation's execution context.
+    async_simple::Future<ErrorCode> AwaitDurable(uint64_t sequence);
+
     bool IsAccepting() const;
     ErrorCode LastError() const;
+    std::optional<OrderedOpLogWriterTerminalState> GetTerminalState() const;
+    void SetTerminalCallback(TerminalCallback callback);
+    // Called by the service only after installing this writer. Older writers
+    // can no longer publish runtime metrics after this handoff.
+    void ActivateRuntimeMetrics();
     void Start();
-    void Stop();
+    virtual void Stop();
 
    private:
     struct Impl;
diff --git a/mooncake-store/include/ha/snapshot/allocator_snapshot_codec.h b/mooncake-store/include/ha/snapshot/allocator_snapshot_codec.h
new file mode 100644
index 0000000000..ae5e298da9
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/allocator_snapshot_codec.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#include <msgpack.hpp>
+#include <ylt/util/tl/expected.hpp>
+
+#include "allocator.h"
+#include "serialize/serializer.h"
+
+namespace mooncake::ha {
+
+// Owns the snapshot representation of concrete physical allocators. Driver and
+// SegmentPool lifecycle code remain unaware of serialization details.
+class AllocatorSnapshotCodec final {
+   public:
+    static tl::expected<void, SerializationError> Encode(
+        const OffsetBufferAllocatorSnapshot& snapshot, MsgpackPacker& packer);
+
+    static tl::expected<OffsetBufferAllocatorSnapshot, SerializationError>
+    Decode(const msgpack::object& object);
+};
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h
new file mode 100644
index 0000000000..a45670798b
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h
@@ -0,0 +1,34 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+#include "types.h"
+
+namespace mooncake {
+
+class HaKvBackend;
+class SnapshotObjectStore;
+class SnapshotMaintenanceLease;
+
+// Runs only after snapshot publication, under the same maintenance lease.
+// The reader-visible floor always precedes batch deletion. Errors retain data
+// and must not change the outcome of the already successful publication.
+class BatchOpLogPruningCoordinator {
+   public:
+    BatchOpLogPruningCoordinator(HaKvBackend& backend,
+                                 SnapshotObjectStore& object_store,
+                                 std::string cluster_id,
+                                 std::string snapshot_root);
+
+    ErrorCode Run(const SnapshotMaintenanceLease& lease,
+                  const std::function<bool()>& cancelled = {});
+
+   private:
+    HaKvBackend& backend_;
+    SnapshotObjectStore& object_store_;
+    std::string cluster_id_;
+    std::string snapshot_root_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h
new file mode 100644
index 0000000000..f8f7b4f95b
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h
@@ -0,0 +1,126 @@
+#pragma once
+
+#include <chrono>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+
+#include "ha/oplog/oplog_batch_types.h"
+#include "types.h"
+
+namespace mooncake {
+
+inline constexpr uint64_t kDefaultBatchOpLogSnapshotIntervalSeconds = 600;
+
+class HaKvBackend;
+class HotStandbyService;
+class SnapshotMaintenanceLease;
+class SnapshotObjectStore;
+
+struct BatchOpLogSnapshotCoordinatorConfig {
+    uint64_t snapshot_interval_seconds{
+        kDefaultBatchOpLogSnapshotIntervalSeconds};
+    size_t chunk_object_count{1000000};
+    std::string snapshot_root;
+    std::function<std::chrono::steady_clock::time_point()> clock;
+};
+
+struct BatchOpLogSnapshotCoordinatorStatus {
+    bool running{false};
+    bool attempt_in_flight{false};
+    bool promotion_requested{false};
+    uint64_t attempts{0};
+    ErrorCode last_error{ErrorCode::OK};
+    std::optional<DurablePrefix> catch_up_target;
+};
+
+// Coordinates the opt-in batch-OpLog snapshot path. Construction alone does
+// not start a worker or change HotStandbyService behavior.
+class BatchOpLogSnapshotCoordinator final {
+   public:
+    using LeaseFactory =
+        std::function<std::unique_ptr<SnapshotMaintenanceLease>()>;
+
+    BatchOpLogSnapshotCoordinator(HotStandbyService& standby,
+                                  HaKvBackend& backend,
+                                  SnapshotObjectStore& object_store,
+                                  std::string cluster_id,
+                                  BatchOpLogSnapshotCoordinatorConfig config,
+                                  LeaseFactory lease_factory = {});
+    BatchOpLogSnapshotCoordinator(HotStandbyService& standby,
+                                  HaKvBackend& backend,
+                                  SnapshotObjectStore& object_store,
+                                  std::string cluster_id,
+                                  std::string snapshot_root,
+                                  uint64_t snapshot_interval_seconds =
+                                      kDefaultBatchOpLogSnapshotIntervalSeconds,
+                                  size_t chunk_object_count = 1000000);
+    ~BatchOpLogSnapshotCoordinator();
+
+    BatchOpLogSnapshotCoordinator(const BatchOpLogSnapshotCoordinator&) =
+        delete;
+    BatchOpLogSnapshotCoordinator& operator=(
+        const BatchOpLogSnapshotCoordinator&) = delete;
+
+    // Starts periodic scheduling. RunOnce() remains available for
+    // deterministic tests and callers that own the scheduling loop.
+    void Start();
+    void Stop();
+
+    // Executes at most one attempt. An ineligible cycle returns OK and leaves
+    // the standby OpLog apply loop untouched.
+    ErrorCode RunOnce();
+    ErrorCode PollOnce() { return RunOnce(); }
+
+    // Called by HotStandbyService before promotion/stop. Promotion keeps a
+    // fully uploaded candidate eligible for the background publish step.
+    void NotifyPromotion();
+    void OnPromotion() { NotifyPromotion(); }
+
+    BatchOpLogSnapshotCoordinatorStatus GetStatus() const;
+    bool IsRunning() const;
+    bool IsAttemptInFlight() const;
+    ErrorCode last_error() const;
+
+   private:
+    using Clock = std::chrono::steady_clock;
+
+    void SchedulerLoop();
+    ErrorCode RunAttempt();
+    std::optional<uint64_t> ReadLatestBatchId(ErrorCode& error) const;
+    bool CatchUpComplete(const DurablePrefix& target) const;
+    void FinishAttempt(ErrorCode error, bool count_attempt);
+    Clock::time_point Now() const;
+    void OnCaptureReleased();
+    std::optional<DurablePrefix> ReadDurablePrefix() const;
+    void RequestStop();
+
+    HotStandbyService& standby_;
+    HaKvBackend& backend_;
+    SnapshotObjectStore& object_store_;
+    std::string cluster_id_;
+    BatchOpLogSnapshotCoordinatorConfig config_;
+    LeaseFactory lease_factory_;
+
+    mutable std::mutex mutex_;
+    std::condition_variable cv_;
+    std::thread worker_;
+    bool running_{false};
+    bool stop_requested_{false};
+    bool attempt_in_flight_{false};
+    bool capture_active_{false};
+    bool promotion_requested_{false};
+    uint64_t attempts_{0};
+    ErrorCode last_error_{ErrorCode::OK};
+    std::optional<Clock::time_point> last_attempt_complete_;
+    std::optional<DurablePrefix> capture_cursor_;
+    std::optional<DurablePrefix> catch_up_target_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h
new file mode 100644
index 0000000000..832c3f6122
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h
@@ -0,0 +1,26 @@
+#pragma once
+#include <string>
+#include <string_view>
+#include <optional>
+#include <functional>
+#include "types.h"
+namespace mooncake {
+class HaKvBackend;
+class SnapshotObjectStore;
+class SnapshotMaintenanceLease;
+class BatchOpLogSnapshotGc {
+   public:
+    BatchOpLogSnapshotGc(HaKvBackend&, SnapshotObjectStore&, std::string,
+                         std::string);
+    ErrorCode Run(const SnapshotMaintenanceLease&, std::string_view published,
+                  const std::optional<std::string>& expected_fallback);
+    ErrorCode Run(const SnapshotMaintenanceLease&, std::string_view,
+                  const std::optional<std::string>&,
+                  const std::function<bool()>& cancelled);
+
+   private:
+    HaKvBackend& backend_;
+    SnapshotObjectStore& store_;
+    std::string cluster_, root_;
+};
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h
new file mode 100644
index 0000000000..f600b8fc5e
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h
@@ -0,0 +1,47 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "ha/standby_metadata_store.h"
+#include "types.h"
+
+namespace mooncake {
+
+class HaKvBackend;
+class OpLogApplier;
+class SnapshotObjectStore;
+
+struct BatchOpLogSnapshotRestoreResult {
+    uint64_t last_included_seq{0};
+    uint64_t last_included_batch_id{0};
+    uint64_t last_applied_seq{0};
+    uint64_t last_applied_batch_id{0};
+    ViewVersionId producer_view_version{0};
+    ReplicaID max_replica_id{0};
+};
+
+// Restores the new batch-OpLog snapshot format into caller-owned temporary
+// state. Legacy catalog snapshots intentionally do not use this provider.
+class BatchOpLogSnapshotProvider final {
+   public:
+    BatchOpLogSnapshotProvider(std::string cluster_id, HaKvBackend& backend,
+                               SnapshotObjectStore& object_store,
+                               std::string snapshot_root);
+
+    tl::expected<BatchOpLogSnapshotRestoreResult, ErrorCode> RestoreBaseline(
+        StandbyMetadataStore& metadata, StandbySegmentRegistry& registry,
+        OpLogApplier* applier = nullptr, uint64_t minimum_snapshot_batch = 0,
+        std::function<bool()> cancelled = {});
+
+   private:
+    std::string cluster_id_;
+    HaKvBackend& backend_;
+    SnapshotObjectStore& object_store_;
+    std::string snapshot_root_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h
new file mode 100644
index 0000000000..b6180a69b9
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h
@@ -0,0 +1,32 @@
+#pragma once
+
+#include <string>
+#include <string_view>
+#include <optional>
+
+#include "types.h"
+
+namespace mooncake {
+
+class HaKvBackend;
+class SnapshotMaintenanceLease;
+
+class BatchOpLogSnapshotPublisher {
+   public:
+    BatchOpLogSnapshotPublisher(HaKvBackend& backend, std::string cluster_id);
+
+    ErrorCode Publish(const SnapshotMaintenanceLease& lease,
+                      std::string_view descriptor_json,
+                      std::optional<std::string>* expected_fallback = nullptr);
+
+   private:
+    ErrorCode PublishImpl(std::string_view owner_token,
+                          std::string_view descriptor_json,
+                          const SnapshotMaintenanceLease& lease,
+                          std::optional<std::string>* expected_fallback);
+
+    HaKvBackend& backend_;
+    std::string cluster_id_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/capture.h b/mooncake-store/include/ha/snapshot/batch_oplog/capture.h
new file mode 100644
index 0000000000..937dfcc3e7
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/capture.h
@@ -0,0 +1,95 @@
+#pragma once
+
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <utility>
+#include <vector>
+
+#include "ha/standby_metadata_store.h"
+
+namespace mooncake {
+
+class HotStandbyService;
+
+class BatchOpLogSnapshotCapture {
+   public:
+    BatchOpLogSnapshotCapture(BatchOpLogSnapshotCapture&& other) noexcept
+        : last_included_seq(other.last_included_seq),
+          last_included_batch_id(other.last_included_batch_id),
+          producer_view_version(other.producer_view_version),
+          segments(std::move(other.segments)),
+          cursor_(std::move(other.cursor_)),
+          generation_(std::exchange(other.generation_, 0)),
+          lease_state_(std::move(other.lease_state_)) {}
+    BatchOpLogSnapshotCapture& operator=(
+        BatchOpLogSnapshotCapture&& other) noexcept {
+        if (this != &other) {
+            Release();
+            last_included_seq = other.last_included_seq;
+            last_included_batch_id = other.last_included_batch_id;
+            producer_view_version = other.producer_view_version;
+            segments = std::move(other.segments);
+            cursor_ = std::move(other.cursor_);
+            generation_ = std::exchange(other.generation_, 0);
+            lease_state_ = std::move(other.lease_state_);
+        }
+        return *this;
+    }
+    BatchOpLogSnapshotCapture(const BatchOpLogSnapshotCapture&) = delete;
+    BatchOpLogSnapshotCapture& operator=(const BatchOpLogSnapshotCapture&) =
+        delete;
+    ~BatchOpLogSnapshotCapture() { Release(); }
+
+    bool done() const { return !lease_state_ || cursor_.done(); }
+
+    uint64_t last_included_seq;
+    uint64_t last_included_batch_id;
+    ViewVersionId producer_view_version;
+    std::vector<StandbySegmentInfo> segments;
+
+   private:
+    friend class HotStandbyService;
+
+    struct LeaseState {
+        std::condition_variable cv;
+        std::mutex mutex;
+        bool requested{false};
+        bool active{false};
+        uint64_t generation{0};
+    };
+
+    BatchOpLogSnapshotCapture(uint64_t last_seq, uint64_t last_batch_id,
+                              ViewVersionId producer_view,
+                              std::vector<StandbySegmentInfo> captured_segments,
+                              StandbyMetadataStore::SnapshotCursor cursor,
+                              uint64_t generation,
+                              std::shared_ptr<LeaseState> lease_state)
+        : last_included_seq(last_seq),
+          last_included_batch_id(last_batch_id),
+          producer_view_version(producer_view),
+          segments(std::move(captured_segments)),
+          cursor_(std::move(cursor)),
+          generation_(generation),
+          lease_state_(std::move(lease_state)) {}
+
+    void Release() noexcept {
+        auto lease_state = std::move(lease_state_);
+        if (!lease_state) {
+            return;
+        }
+        std::lock_guard<std::mutex> lock(lease_state->mutex);
+        if (lease_state->active && generation_ == lease_state->generation) {
+            lease_state->active = false;
+            lease_state->cv.notify_all();
+        }
+        generation_ = 0;
+    }
+
+    StandbyMetadataStore::SnapshotCursor cursor_;
+    uint64_t generation_;
+    std::shared_ptr<LeaseState> lease_state_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/codec.h b/mooncake-store/include/ha/snapshot/batch_oplog/codec.h
new file mode 100644
index 0000000000..d43a713c50
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/codec.h
@@ -0,0 +1,32 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "metadata_store.h"
+
+namespace mooncake {
+
+struct BatchOpLogSnapshotObjectChunk {
+    uint64_t chunk_index{0};
+    std::vector<StandbyObjectEntry> objects;
+
+    YLT_REFL(BatchOpLogSnapshotObjectChunk, chunk_index, objects);
+};
+
+std::vector<uint8_t> EncodeBatchOpLogSnapshotSegments(
+    const std::vector<StandbySegmentInfo>& segments);
+tl::expected<std::vector<StandbySegmentInfo>, std::string>
+DecodeBatchOpLogSnapshotSegments(const std::vector<uint8_t>& encoded);
+
+std::vector<uint8_t> EncodeBatchOpLogSnapshotObjectChunk(
+    uint64_t chunk_index, std::vector<StandbyObjectEntry> objects);
+tl::expected<BatchOpLogSnapshotObjectChunk, std::string>
+DecodeBatchOpLogSnapshotObjectChunk(const std::vector<uint8_t>& encoded,
+                                    uint64_t expected_chunk_index,
+                                    uint64_t expected_object_count);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/config.h b/mooncake-store/include/ha/snapshot/batch_oplog/config.h
new file mode 100644
index 0000000000..2934340ce1
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/config.h
@@ -0,0 +1,37 @@
+#pragma once
+
+#include <optional>
+#include <string>
+
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "master_config.h"
+
+namespace mooncake {
+
+inline std::optional<std::string> ValidateBatchOpLogSnapshotConfig(
+    const MasterConfig& config) {
+    if (!config.enable_oplog_snapshot) {
+        return std::nullopt;
+    }
+    if (!config.enable_oplog) {
+        return "enable_oplog_snapshot requires enable_oplog=true";
+    }
+    if (!config.enable_ha || config.ha_backend_type != "etcd") {
+        return "enable_oplog_snapshot requires HA with ha_backend_type=etcd";
+    }
+    if (config.snapshot_chunk_object_count == 0) {
+        return "snapshot_chunk_object_count must be greater than 0";
+    }
+    if (ha::BuildBatchOpLogSnapshotRoot(config.cluster_id).empty()) {
+        return "enable_oplog_snapshot requires a valid cluster_id";
+    }
+    try {
+        ParseSnapshotObjectStoreType(config.snapshot_object_store_type);
+    } catch (const std::exception& error) {
+        return error.what();
+    }
+    return std::nullopt;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/metadata.h b/mooncake-store/include/ha/snapshot/batch_oplog/metadata.h
new file mode 100644
index 0000000000..6236f0d587
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/metadata.h
@@ -0,0 +1,89 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake::ha {
+
+inline constexpr uint32_t kBatchOpLogSnapshotSchemaVersion = 1;
+inline constexpr char kBatchOpLogSnapshotFormat[] =
+    "standby-oplog-materialized/v1";
+
+struct BatchOpLogSnapshotDescriptor {
+    uint32_t schema_version{kBatchOpLogSnapshotSchemaVersion};
+    std::string snapshot_format{kBatchOpLogSnapshotFormat};
+    std::string snapshot_id;
+    uint64_t last_included_seq{0};
+    uint64_t last_included_batch_id{0};
+    ViewVersionId producer_view_version{0};
+    std::string manifest_key;
+    uint64_t manifest_size{0};
+    uint32_t manifest_crc32c{0};
+    int64_t created_at_ms{0};
+};
+
+struct BatchOpLogSnapshotObjectDescriptor {
+    std::string key;
+    uint64_t stored_size{0};
+    uint32_t crc32c{0};
+};
+
+struct BatchOpLogSnapshotChunkDescriptor {
+    uint64_t chunk_index{0};
+    std::string key;
+    uint64_t object_count{0};
+    uint64_t stored_size{0};
+    uint32_t crc32c{0};
+};
+
+struct BatchOpLogSnapshotManifest {
+    uint32_t schema_version{kBatchOpLogSnapshotSchemaVersion};
+    std::string snapshot_format{kBatchOpLogSnapshotFormat};
+    std::string snapshot_id;
+    uint64_t last_included_seq{0};
+    uint64_t last_included_batch_id{0};
+    ViewVersionId producer_view_version{0};
+    BatchOpLogSnapshotObjectDescriptor segments;
+    std::vector<BatchOpLogSnapshotChunkDescriptor> object_chunks;
+};
+
+std::string EncodeBatchOpLogSnapshotDescriptor(
+    const BatchOpLogSnapshotDescriptor& descriptor);
+tl::expected<BatchOpLogSnapshotDescriptor, std::string>
+DecodeBatchOpLogSnapshotDescriptor(std::string_view value);
+
+std::string EncodeBatchOpLogSnapshotManifest(
+    const BatchOpLogSnapshotManifest& manifest);
+tl::expected<BatchOpLogSnapshotManifest, std::string>
+DecodeBatchOpLogSnapshotManifest(std::string_view value);
+
+std::string BuildBatchOpLogSnapshotId(uint64_t last_included_batch_id,
+                                      int64_t maintenance_lease_id);
+std::string BuildBatchOpLogSnapshotRoot(const std::string& cluster_id);
+
+std::string BuildBatchOpLogSnapshotMaintenanceKey(
+    const std::string& cluster_id);
+std::string BuildBatchOpLogSnapshotLatestKey(const std::string& cluster_id);
+std::string BuildBatchOpLogSnapshotFallbackKey(const std::string& cluster_id);
+std::string BuildBatchOpLogSnapshotCompactionFloorKey(
+    const std::string& cluster_id);
+
+std::string BuildBatchOpLogSnapshotArtifactPrefix(
+    const std::string& snapshot_root, std::string_view snapshot_id);
+std::string BuildBatchOpLogSnapshotDescriptorKey(
+    const std::string& snapshot_root, std::string_view snapshot_id);
+std::string BuildBatchOpLogSnapshotManifestKey(const std::string& snapshot_root,
+                                               std::string_view snapshot_id);
+std::string BuildBatchOpLogSnapshotSegmentsKey(const std::string& snapshot_root,
+                                               std::string_view snapshot_id);
+std::string BuildBatchOpLogSnapshotObjectChunkKey(
+    const std::string& snapshot_root, std::string_view snapshot_id,
+    uint64_t chunk_index);
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/promotion.h b/mooncake-store/include/ha/snapshot/batch_oplog/promotion.h
new file mode 100644
index 0000000000..cf0d8dee72
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/promotion.h
@@ -0,0 +1,25 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/standby_metadata_store.h"
+#include "metadata_store.h"
+#include "types.h"
+
+namespace mooncake {
+
+inline constexpr size_t kDefaultBatchOpLogPromotionChunkObjects = 1'000'000;
+
+struct BatchOpLogPromotionHandoff {
+    std::unique_ptr<StandbyMetadataStore> metadata_store;
+    std::vector<StandbySegmentInfo> segments;
+    DurablePrefix applied_cursor;
+    ViewVersionId producer_view_version{0};
+    ReplicaID max_replica_id{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog/writer.h b/mooncake-store/include/ha/snapshot/batch_oplog/writer.h
new file mode 100644
index 0000000000..d5220fbacc
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog/writer.h
@@ -0,0 +1,29 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+namespace mooncake {
+
+class BatchOpLogSnapshotCapture;
+class HotStandbyService;
+class SnapshotObjectStore;
+
+class BatchOpLogSnapshotWriter {
+   public:
+    explicit BatchOpLogSnapshotWriter(SnapshotObjectStore& object_store)
+        : object_store_(object_store) {}
+
+    tl::expected<std::string, std::string> Write(
+        HotStandbyService& standby, BatchOpLogSnapshotCapture& capture,
+        const std::string& snapshot_root, const std::string& snapshot_id,
+        size_t chunk_object_count, int64_t created_at_ms);
+
+   private:
+    SnapshotObjectStore& object_store_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_coordinator.h b/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_coordinator.h
new file mode 100644
index 0000000000..428289d413
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_coordinator.h
@@ -0,0 +1,5 @@
+#pragma once
+
+// Compatibility include; the batch-OpLog implementation lives in the
+// batch_oplog-specific directory.
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h"
diff --git a/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_publisher.h b/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_publisher.h
new file mode 100644
index 0000000000..c139e88ad2
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/batch_oplog_snapshot_publisher.h
@@ -0,0 +1,5 @@
+#pragma once
+
+// Compatibility include for the design-file path. Implementation stays in
+// the batch_oplog-specific directory.
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h"
diff --git a/mooncake-store/include/ha/snapshot/local_ssd_codec.h b/mooncake-store/include/ha/snapshot/local_ssd_codec.h
new file mode 100644
index 0000000000..70336d9e2f
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/local_ssd_codec.h
@@ -0,0 +1,20 @@
+#pragma once
+
+#include <msgpack.hpp>
+#include <ylt/util/tl/expected.hpp>
+
+#include "local_ssd/persisted_state.h"
+#include "serialize/serializer.h"
+
+namespace mooncake::ha {
+
+class LocalSsdCodec {
+   public:
+    static tl::expected<void, SerializationError> Encode(
+        const LocalSsdPersistedState& state, MsgpackPacker& packer);
+
+    static tl::expected<LocalSsdPersistedState, SerializationError> Decode(
+        const msgpack::object* ld_value);
+};
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/include/ha/snapshot/master_snapshot_codec.h b/mooncake-store/include/ha/snapshot/master_snapshot_codec.h
index 2fb533902a..6a429f37c1 100644
--- a/mooncake-store/include/ha/snapshot/master_snapshot_codec.h
+++ b/mooncake-store/include/ha/snapshot/master_snapshot_codec.h
@@ -13,6 +13,7 @@ namespace mooncake {
 // Forward declarations
 class MasterService;
 class SegmentManager;
+class LocalSsdManager;
 class NoFSegmentManager;
 class ClientTaskManager;
 
@@ -28,13 +29,16 @@ namespace ha {
 struct MasterSnapshotStateView {
     MasterService& master_service;
     SegmentManager& segment_manager;
+    LocalSsdManager& local_ssd_manager;
     NoFSegmentManager& nof_segment_manager;
     ClientTaskManager& task_manager;
 
     MasterSnapshotStateView(MasterService& ms, SegmentManager& sm,
-                            NoFSegmentManager& nsm, ClientTaskManager& tm)
+                            LocalSsdManager& lsm, NoFSegmentManager& nsm,
+                            ClientTaskManager& tm)
         : master_service(ms),
           segment_manager(sm),
+          local_ssd_manager(lsm),
           nof_segment_manager(nsm),
           task_manager(tm) {}
 };
@@ -137,7 +141,7 @@ class MasterSnapshotCodec {
 
     // Segment encoding/decoding
     tl::expected<std::vector<uint8_t>, SerializationError> EncodeSegments(
-        SegmentManager& segment_manager,
+        SegmentManager& segment_manager, LocalSsdManager& local_ssd_manager,
         NoFSegmentManager& nof_segment_manager) const;
     tl::expected<void, SerializationError> DecodeSegments(
         MasterService* master_service, const std::vector<uint8_t>& data) const;
diff --git a/mooncake-store/include/ha/snapshot/object/backends/local/local_file_snapshot_object_store.h b/mooncake-store/include/ha/snapshot/object/backends/local/local_file_snapshot_object_store.h
index 1c51fbe0b4..f8e5af0827 100644
--- a/mooncake-store/include/ha/snapshot/object/backends/local/local_file_snapshot_object_store.h
+++ b/mooncake-store/include/ha/snapshot/object/backends/local/local_file_snapshot_object_store.h
@@ -45,6 +45,9 @@ class LocalFileSnapshotObjectStore final : public SnapshotObjectStore {
         const std::string& prefix,
         std::vector<std::string>& object_keys) override;
 
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override;
+
     bool IsNotFoundError(const std::string& error) const override;
 
     std::string GetConnectionInfo() const override;
diff --git a/mooncake-store/include/ha/snapshot/object/backends/s3/s3_snapshot_object_store.h b/mooncake-store/include/ha/snapshot/object/backends/s3/s3_snapshot_object_store.h
index 5473c3fa1a..17fc8cc76a 100644
--- a/mooncake-store/include/ha/snapshot/object/backends/s3/s3_snapshot_object_store.h
+++ b/mooncake-store/include/ha/snapshot/object/backends/s3/s3_snapshot_object_store.h
@@ -41,6 +41,9 @@ class S3SnapshotObjectStore final : public SnapshotObjectStore {
         const std::string& prefix,
         std::vector<std::string>& object_keys) override;
 
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override;
+
     bool IsNotFoundError(const std::string& error) const override;
     std::string GetConnectionInfo() const override;
 
diff --git a/mooncake-store/include/ha/snapshot/object/snapshot_object_store.h b/mooncake-store/include/ha/snapshot/object/snapshot_object_store.h
index b64ae887b8..2e9664c722 100644
--- a/mooncake-store/include/ha/snapshot/object/snapshot_object_store.h
+++ b/mooncake-store/include/ha/snapshot/object/snapshot_object_store.h
@@ -1,6 +1,8 @@
 #pragma once
 
+#include <cstdint>
 #include <memory>
+#include <optional>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -15,6 +17,11 @@ enum class SnapshotObjectStoreType {
     S3 = 1           // S3 storage
 };
 
+struct SnapshotObjectInspection {
+    uint64_t stored_size{0};
+    std::optional<uint32_t> crc32c;
+};
+
 // Convert string to SnapshotObjectStoreType
 inline SnapshotObjectStoreType ParseSnapshotObjectStoreType(
     const std::string& type_str) {
@@ -116,6 +123,15 @@ class SnapshotObjectStore {
     virtual tl::expected<void, std::string> ListObjectsWithPrefix(
         const std::string& prefix, std::vector<std::string>& object_keys) = 0;
 
+    /**
+     * @brief Read stored size and an optional backend-verified CRC32C
+     */
+    virtual tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) {
+        return tl::make_unexpected("Object inspection is not supported: " +
+                                   key);
+    }
+
     /**
      * @brief Tell whether an error means the target object is missing
      * @param error Store-specific error string
diff --git a/mooncake-store/include/ha/snapshot/snapshot_maintenance_lease.h b/mooncake-store/include/ha/snapshot/snapshot_maintenance_lease.h
new file mode 100644
index 0000000000..96940a725b
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/snapshot_maintenance_lease.h
@@ -0,0 +1,51 @@
+#pragma once
+
+#include <memory>
+#include <mutex>
+#include <string>
+
+#include "types.h"
+
+namespace mooncake {
+
+class SnapshotMaintenanceLease {
+   public:
+    static constexpr int64_t kTtlSeconds = 30;
+
+    explicit SnapshotMaintenanceLease(std::string cluster_id);
+    ~SnapshotMaintenanceLease();
+
+    SnapshotMaintenanceLease(const SnapshotMaintenanceLease&) = delete;
+    SnapshotMaintenanceLease& operator=(const SnapshotMaintenanceLease&) =
+        delete;
+
+    ErrorCode Acquire();
+    ErrorCode Release();
+
+    bool IsHeld() const;
+    EtcdLeaseId lease_id() const;
+    EtcdRevisionId lock_create_revision() const;
+    std::string owner_token() const;
+    const std::string& lock_key() const { return lock_key_; }
+
+    // Keeps publisher transaction tests independent of a live etcd process.
+    static std::unique_ptr<SnapshotMaintenanceLease> MakeForTesting(
+        std::string cluster_id, std::string owner_token,
+        EtcdRevisionId lock_create_revision = 1);
+
+   private:
+    SnapshotMaintenanceLease(std::string cluster_id, std::string owner_token,
+                             bool testing, EtcdRevisionId create_revision);
+
+    std::string cluster_id_;
+    std::string lock_key_;
+    std::string owner_token_;
+    int64_t session_handle_{0};
+    EtcdLeaseId lease_id_{0};
+    EtcdRevisionId lock_create_revision_{0};
+    mutable std::mutex mutex_;
+    bool testing_{false};
+    bool lock_created_{false};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha/snapshot/store_resource_snapshot_codec.h b/mooncake-store/include/ha/snapshot/store_resource_snapshot_codec.h
new file mode 100644
index 0000000000..af491d5931
--- /dev/null
+++ b/mooncake-store/include/ha/snapshot/store_resource_snapshot_codec.h
@@ -0,0 +1,39 @@
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "local_ssd/persisted_state.h"
+#include "segment/snapshot.h"
+#include "types.h"
+
+namespace mooncake {
+struct SerializationError;
+}  // namespace mooncake
+
+namespace mooncake::ha {
+
+struct StoreResourceSnapshot {
+    SegmentPoolSnapshot segment_pool;
+    LocalSsdPersistedState local_ssd;
+};
+
+// Codec for the existing ma/an/ms/cs/ld store-resource snapshot payload.
+// Runtime components remain unaware of serialization.
+class StoreResourceSnapshotCodec final {
+   public:
+    // Reads only owned snapshot data, independent of the source pool's
+    // lifetime. Preserves SegmentSerializer's wire format (OFFSET host memory,
+    // not CXL).
+    static tl::expected<std::vector<uint8_t>, SerializationError> Encode(
+        const SegmentPoolSnapshot& snapshot,
+        const LocalSsdPersistedState& local_ssd_state);
+
+    // Decodes detached state without publishing resources or updating metrics.
+    static tl::expected<StoreResourceSnapshot, SerializationError> Decode(
+        const std::vector<uint8_t>& data);
+};
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/include/ha/standby_controller.h b/mooncake-store/include/ha/standby_controller.h
index f6b738a713..dc09729738 100644
--- a/mooncake-store/include/ha/standby_controller.h
+++ b/mooncake-store/include/ha/standby_controller.h
@@ -8,6 +8,7 @@
 #include <ylt/util/tl/expected.hpp>
 
 #include "ha/ha_types.h"
+#include "ha/snapshot/batch_oplog/promotion.h"
 #include "master_config.h"
 #include "metadata_store.h"
 #include "types.h"
@@ -20,9 +21,19 @@ namespace ha {
  * Contains everything needed to restore primary's state.
  */
 struct PromotionContext {
+    PromotionContext() = default;
+    PromotionContext(PromotionContext&&) = default;
+    PromotionContext& operator=(PromotionContext&&) = default;
+    PromotionContext(const PromotionContext&) = delete;
+    PromotionContext& operator=(const PromotionContext&) = delete;
+
     uint64_t applied_seq_id{0};
     std::vector<StandbyObjectEntry> objects;
     std::vector<StandbySegmentInfo> segments;
+    std::unique_ptr<StandbyMetadataStore> metadata_store;
+    DurablePrefix applied_cursor;
+    ViewVersionId producer_view_version{0};
+    ReplicaID max_replica_id{0};
 };
 
 class StandbyController {
diff --git a/mooncake-store/include/ha/standby_metadata_store.h b/mooncake-store/include/ha/standby_metadata_store.h
new file mode 100644
index 0000000000..cc1017f0f4
--- /dev/null
+++ b/mooncake-store/include/ha/standby_metadata_store.h
@@ -0,0 +1,81 @@
+#pragma once
+
+#include <cstddef>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "metadata_store.h"
+
+namespace mooncake {
+
+class StandbyMetadataStore final : public MetadataStore {
+    using ObjectStore = std::unordered_map<std::string, StandbyObjectMetadata>;
+    using TenantStore = std::unordered_map<std::string, ObjectStore>;
+
+   public:
+    class SnapshotCursor {
+       public:
+        SnapshotCursor(SnapshotCursor&&) = default;
+        SnapshotCursor& operator=(SnapshotCursor&&) = default;
+        SnapshotCursor(const SnapshotCursor&) = delete;
+        SnapshotCursor& operator=(const SnapshotCursor&) = delete;
+
+        bool done() const { return done_; }
+
+       private:
+        friend class StandbyMetadataStore;
+
+        SnapshotCursor(const StandbyMetadataStore* store,
+                       TenantStore::const_iterator tenant,
+                       TenantStore::const_iterator tenant_end,
+                       ObjectStore::const_iterator object, bool done)
+            : store_(store),
+              tenant_(tenant),
+              tenant_end_(tenant_end),
+              object_(object),
+              done_(done) {}
+
+        const StandbyMetadataStore* store_;
+        TenantStore::const_iterator tenant_;
+        TenantStore::const_iterator tenant_end_;
+        ObjectStore::const_iterator object_;
+        bool done_;
+    };
+
+    using MetadataStore::Exists;
+    using MetadataStore::GetMetadata;
+    using MetadataStore::PutMetadata;
+    using MetadataStore::Remove;
+
+    bool PutMetadata(const std::string& tenant_id, const std::string& key,
+                     const StandbyObjectMetadata& metadata) override;
+    bool RestoreMetadata(const std::string& tenant_id, const std::string& key,
+                         const StandbyObjectMetadata& metadata);
+    bool Put(const std::string& key,
+             const std::string& payload = std::string()) override;
+    std::optional<StandbyObjectMetadata> GetMetadata(
+        const std::string& tenant_id, const std::string& key) const override;
+    bool Remove(const std::string& tenant_id, const std::string& key) override;
+    bool Exists(const std::string& tenant_id,
+                const std::string& key) const override;
+    size_t GetKeyCountForTenant(const std::string& tenant_id) const override;
+    size_t GetKeyCount() const override;
+    void Clear();
+
+    void Snapshot(std::vector<StandbyObjectEntry>& out) const;
+    bool ValidateReplicaIds(ReplicaID& max_replica_id) const;
+    bool DrainChunk(size_t count, std::vector<StandbyObjectEntry>& out);
+    // Mutations must remain frozen for the lifetime of the returned cursor.
+    SnapshotCursor BeginSnapshotTraversal() const;
+    bool CopyNextSnapshotChunk(size_t count, SnapshotCursor& cursor,
+                               std::vector<StandbyObjectEntry>& out) const;
+
+   private:
+    mutable std::mutex mutex_;
+    TenantStore store_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/ha_metric_manager.h b/mooncake-store/include/ha_metric_manager.h
index 59fc897970..13545d2c4a 100644
--- a/mooncake-store/include/ha_metric_manager.h
+++ b/mooncake-store/include/ha_metric_manager.h
@@ -1,9 +1,12 @@
 #pragma once
 
+#include <array>
 #include <atomic>
 #include <chrono>
 #include <mutex>
+#include <optional>
 #include <string>
+#include <utility>
 
 #include "ylt/metric/counter.hpp"
 #include "ylt/metric/gauge.hpp"
@@ -24,6 +27,123 @@ namespace mooncake {
  */
 class HAMetricManager {
    public:
+    enum class SnapshotOperation {
+        Schedule,
+        Upload,
+        Bootstrap,
+        Replay,
+        Publish,
+        Gc,
+        Prune,
+        Rebootstrap,
+        Count
+    };
+    enum class SnapshotSkipReason {
+        None,
+        Disabled,
+        Interval,
+        InFlight,
+        Stopped,
+        Promotion,
+        NoNewBatch,
+        CatchUp,
+        LeaseBusy,
+        CaptureUnavailable,
+        NoFallback,
+        InvalidPair,
+        FloorAhead,
+        Count
+    };
+    // Records failed/throwing operations too. Set error to zero only after
+    // successful completion; the default denotes an exception/incomplete call.
+    class SnapshotOperationTimer {
+       public:
+        explicit SnapshotOperationTimer(SnapshotOperation operation)
+            : operation_(operation) {}
+        ~SnapshotOperationTimer() {
+            HAMetricManager::instance().record_snapshot_operation(
+                operation_, error, start_);
+        }
+        SnapshotOperationTimer(const SnapshotOperationTimer&) = delete;
+        SnapshotOperationTimer& operator=(const SnapshotOperationTimer&) =
+            delete;
+        template <typename Result>
+        Result Success(Result result) {
+            error = 0;
+            return result;
+        }
+        int64_t error{-1};
+
+       private:
+        SnapshotOperation operation_;
+        std::chrono::steady_clock::time_point start_{
+            std::chrono::steady_clock::now()};
+    };
+    struct SnapshotRuntime {
+        bool enabled{false};
+        // Absent means unknown/missing. Timestamps are Unix milliseconds.
+        std::optional<int64_t> latest_created_at_ms;
+        std::optional<int64_t> fallback_created_at_ms;
+        uint64_t snapshot_bytes{0};
+        uint64_t chunk_bytes{0};
+        uint64_t chunk_count{0};
+        uint64_t capture_pause_us{0};
+        uint64_t suffix_batches{0};
+        uint64_t catch_up_target_batch{0};
+        uint64_t catch_up_target_sequence{0};
+        uint64_t durable_batch{0};
+        uint64_t applied_batch{0};
+        uint64_t latest_batch{0};
+        uint64_t fallback_batch{0};
+        uint64_t compaction_floor{0};
+        uint64_t candidate_floor{0};
+        uint64_t floor_advances_total{0};
+        uint64_t gc_orphan_prefixes{0};
+        uint64_t gc_deleted_prefixes{0};
+        uint64_t lease_lost_total{0};
+        SnapshotSkipReason skip_reason{SnapshotSkipReason::Disabled};
+    };
+    struct SnapshotOperationStats {
+        uint64_t total{0};
+        uint64_t errors{0};
+        uint64_t elapsed_us{0};
+    };
+    void reset_snapshot_runtime(bool enabled);
+    SnapshotRuntime get_snapshot_runtime() const;
+    SnapshotOperationStats get_snapshot_operation(
+        SnapshotOperation operation) const;
+    // Updates are restricted to observed state transitions; never perform I/O
+    // or call back into a service while holding this lock.
+    template <typename Update>
+    void update_snapshot_runtime(Update&& update) {
+        std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+        if (snapshot_runtime_.enabled) update(snapshot_runtime_);
+    }
+    void record_snapshot_skip(SnapshotSkipReason reason);
+    void record_snapshot_operation(SnapshotOperation operation, int64_t error,
+                                   std::chrono::steady_clock::time_point start);
+
+    struct WriterRuntimeSnapshot {
+        bool accepting{false};
+        uint64_t retry_count{0};
+        uint64_t retry_delay_ms{0};
+        uint64_t waiting_slots{0};
+        uint64_t committed_queue_depth{0};
+        uint64_t callback_queue_depth{0};
+        uint64_t durable_batch_id{0};
+        uint64_t durable_sequence{0};
+        int64_t last_error{0};
+        std::string terminal_reason;
+        std::optional<std::pair<uint64_t, uint64_t>> stuck_range;
+    };
+
+    // Activation replaces the observed writer and invalidates earlier owners.
+    // Snapshot retry_count is per writer on input, process cumulative on
+    // output.
+    uint64_t activate_writer_runtime(const WriterRuntimeSnapshot& snapshot);
+    void update_writer_runtime(uint64_t owner,
+                               const WriterRuntimeSnapshot& snapshot);
+    WriterRuntimeSnapshot get_writer_runtime() const;
     // --- Singleton Access ---
     static HAMetricManager& instance();
 
@@ -247,6 +367,19 @@ class HAMetricManager {
     // State Machine
     ylt::metric::gauge_t standby_state_;
     ylt::metric::counter_t state_transitions_total_;
+
+    mutable std::mutex snapshot_runtime_mutex_;
+    SnapshotRuntime snapshot_runtime_;
+    std::array<SnapshotOperationStats,
+               static_cast<size_t>(SnapshotOperation::Count)>
+        snapshot_operations_{};
+    std::array<uint64_t, static_cast<size_t>(SnapshotSkipReason::Count)>
+        snapshot_skips_{};
+
+    mutable std::mutex writer_runtime_mutex_;
+    WriterRuntimeSnapshot writer_runtime_;
+    uint64_t writer_runtime_owner_{0};
+    uint64_t writer_retry_base_{0};
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/hf3fs/hf3fs.h b/mooncake-store/include/hf3fs/hf3fs.h
index b624d15623..feebaab516 100644
--- a/mooncake-store/include/hf3fs/hf3fs.h
+++ b/mooncake-store/include/hf3fs/hf3fs.h
@@ -5,12 +5,12 @@
 #include <mutex>
 #include <thread>
 #include <hf3fs_usrbio.h>
+
+#include "file_interface.h"
 #include "types.h"
 
 namespace mooncake {
 
-class StorageFile;
-
 // Forward declaration of USRBIOResourceManager
 struct Hf3fsConfig {
     // 3FS cluster related parameters
@@ -103,4 +103,4 @@ class ThreeFSFile : public StorageFile {
     USRBIOResourceManager *resource_manager_;
 };
 
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-store/include/hot_standby_service.h b/mooncake-store/include/hot_standby_service.h
index f89bd76c0f..7e6f6d5b25 100644
--- a/mooncake-store/include/hot_standby_service.h
+++ b/mooncake-store/include/hot_standby_service.h
@@ -7,16 +7,19 @@
 #include <functional>
 #include <memory>
 #include <mutex>
+#include <optional>
 #include <string>
 #include <thread>
-#include <unordered_map>
-#include <utility>
 #include <vector>
 
-#include "metadata_store.h"
 #include "ha/oplog/oplog_applier.h"
+#include "ha/oplog/oplog_batch_types.h"
 #include "ha/oplog/oplog_types.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
+#include "ha/snapshot/batch_oplog/capture.h"
+#include "ha/snapshot/batch_oplog/promotion.h"
 #include "ha/snapshot/snapshot_provider.h"
+#include "ha/standby_metadata_store.h"
 #include "standby_state_machine.h"
 #include "types.h"
 
@@ -27,6 +30,7 @@ class MasterService;
 class HaKvBackend;
 class OpLogBatchStandbyReader;
 enum class OpLogBatchStandbyPollDisposition;
+struct OpLogBatchStandbyPollResult;
 
 /**
  * @brief Configuration for HotStandbyService
@@ -62,6 +66,7 @@ struct StandbySyncStatus {
     std::chrono::milliseconds lag_time{0};
     bool is_syncing{false};
     bool is_connected{false};
+    bool is_recovering{false};
     StandbyState state{StandbyState::STOPPED};
     std::chrono::milliseconds time_in_state{0};
     ErrorCode last_error{ErrorCode::OK};
@@ -138,6 +143,10 @@ class HotStandbyService {
      */
     ErrorCode PromoteAndExportSnapshot(StandbySnapshot& out);
 
+    bool IsBatchOpLogSnapshotMode() const;
+    tl::expected<BatchOpLogPromotionHandoff, ErrorCode>
+    PromoteAndDetachBatchOpLogStore();
+
     /**
      * @brief Get the number of metadata entries in the local store
      */
@@ -169,16 +178,39 @@ class HotStandbyService {
      */
     bool ExportStandbySnapshot(StandbySnapshot& out) const;
 
+    std::optional<BatchOpLogSnapshotCapture> BeginBatchOpLogSnapshotCapture();
+    bool CopyNextBatchOpLogSnapshotChunk(size_t count,
+                                         BatchOpLogSnapshotCapture& capture,
+                                         std::vector<StandbyObjectEntry>& out);
+    void EndBatchOpLogSnapshotCapture(BatchOpLogSnapshotCapture& capture);
+
+    // N06 coordinator seams. These stay inert unless a coordinator is
+    // explicitly constructed by the caller.
+    std::optional<DurablePrefix> GetLastAppliedBatchOpLogSnapshotPrefix() const;
+    void CancelBatchOpLogSnapshotCapture();
+    using SnapshotLifecycleCallback = std::function<void()>;
+    void SetBatchOpLogSnapshotCaptureReleasedCallback(
+        SnapshotLifecycleCallback callback);
+    void SetBatchOpLogSnapshotPromotionCallback(
+        SnapshotLifecycleCallback callback);
+    void SetBatchOpLogSnapshotStopCallback(SnapshotLifecycleCallback callback);
+
     // Inject a snapshot provider (from external snapshot implementation).
     void SetSnapshotProvider(std::unique_ptr<SnapshotProvider> provider);
 
+    // Inject the new batch-OpLog bootstrap path. It owns no running state;
+    // Start() gives it temporary stores and installs them only on success.
+    void SetBatchOpLogSnapshotProvider(
+        std::unique_ptr<BatchOpLogSnapshotProvider> provider);
+
     // Notify callers when standby sync status changes. The callback is invoked
     // from existing standby worker threads; no extra monitor thread is created.
     void SetSyncStatusCallback(SyncStatusCallback callback);
 
     /**
-     * @brief Test seam: when set, promotion final catch-up first tries
-     *        batch-record durable prefix/batches from this backend.
+     * @brief Test seam: inject a HaKvBackend used for Start()/replication and
+     *        promotion catch-up. When set, Start() skips live etcd connection
+     *        (and works even when STORE_USE_ETCD is OFF).
      */
     void SetCatchUpBatchKvBackendForTesting(
         std::shared_ptr<HaKvBackend> backend);
@@ -196,20 +228,31 @@ class HotStandbyService {
     }
 
    private:
+    enum class PromotionCatchUpPolicy {
+        kLegacyTotalDeadline,
+        kBoundedNoProgress,
+    };
+
     ErrorCode PrepareBootstrapBaselineLocked(uint64_t& baseline_seq_id);
     ErrorCode LoadSnapshotBaselineLocked(uint64_t& baseline_seq_id);
+    ErrorCode LoadBatchOpLogSnapshotBaselineLocked(uint64_t& baseline_seq_id);
     ErrorCode StartOplogFollowingLocked(uint64_t baseline_seq_id);
     void ActivateSnapshotOnlyStandbyLocked(uint64_t baseline_seq_id);
     uint64_t GetLocalLastAppliedSequenceIdLocked() const;
-    ErrorCode FinalCatchUpForPromotionLocked(uint64_t current_applied_seq_id);
-    ErrorCode FinalCatchUpBatchRecordsLocked(HaKvBackend& backend);
+    ErrorCode FinalCatchUpForPromotionLocked(uint64_t current_applied_seq_id,
+                                             PromotionCatchUpPolicy policy);
+    ErrorCode FinalCatchUpBatchRecordsLocked(HaKvBackend& backend,
+                                             PromotionCatchUpPolicy policy);
     void StopReplicationLoop();
+    void HandleSnapshotCaptureRequest(
+        const OpLogBatchStandbyPollResult& result);
+    void CancelSnapshotCapture();
+    void NotifySnapshotPromotion();
+    void NotifySnapshotStop();
 
-    // Shared body for Promote() and PromoteAndExportSnapshot(): runs the
-    // promotion sequence machine transitions + gap resolution + final
-    // catch-up + post catch-up gap check + success transition. Returns
-    // ErrorCode::OK on success or any fail-closed error code.
-    ErrorCode PromoteLockedInternal(uint64_t current_applied_seq_id);
+    ErrorCode PreparePromotionLocked(uint64_t current_applied_seq_id,
+                                     PromotionCatchUpPolicy policy);
+    ErrorCode CompletePromotionLocked();
 
     void NotifySyncStatus();
 
@@ -217,6 +260,7 @@ class HotStandbyService {
      * @brief Main replication loop (runs in background thread)
      */
     void ReplicationLoop();
+    ErrorCode RebootstrapBatchOpLog(uint64_t floor);
 
     /**
      * @brief Verification loop (runs in background thread)
@@ -225,42 +269,17 @@ class HotStandbyService {
 
     HotStandbyConfig config_;
 
-    // Simple in-memory metadata store implementation
-    class StandbyMetadataStore : public MetadataStore {
-       public:
-        bool PutMetadata(const std::string& tenant_id, const std::string& key,
-                         const StandbyObjectMetadata& metadata) override;
-        bool Put(const std::string& key,
-                 const std::string& payload = std::string()) override;
-        std::optional<StandbyObjectMetadata> GetMetadata(
-            const std::string& tenant_id,
-            const std::string& key) const override;
-        bool Remove(const std::string& tenant_id,
-                    const std::string& key) override;
-        bool Exists(const std::string& tenant_id,
-                    const std::string& key) const override;
-        size_t GetKeyCountForTenant(
-            const std::string& tenant_id) const override;
-        size_t GetKeyCount() const override;
-        void Clear();
-
-        // Snapshot for promotion/restore.
-        void Snapshot(std::vector<StandbyObjectEntry>& out) const;
-
-       private:
-        mutable std::mutex mutex_;
-        std::unordered_map<
-            std::string, std::unordered_map<std::string, StandbyObjectMetadata>>
-            store_;
-    };
     std::unique_ptr<StandbyMetadataStore> metadata_store_;
     std::unique_ptr<SnapshotProvider> snapshot_provider_{
         std::make_unique<NoopSnapshotProvider>()};
+    std::shared_ptr<BatchOpLogSnapshotProvider> batch_oplog_snapshot_provider_;
 
     // OpLog replication components
     std::unique_ptr<OpLogApplier> oplog_applier_;
     std::shared_ptr<HaKvBackend> batch_standby_kv_backend_;
     std::unique_ptr<OpLogBatchStandbyReader> batch_standby_reader_;
+    std::optional<DurablePrefix> batch_snapshot_baseline_;
+    ViewVersionId batch_snapshot_producer_view_version_{0};
 
     std::shared_ptr<HaKvBackend> catch_up_batch_kv_backend_for_testing_;
 
@@ -272,6 +291,7 @@ class HotStandbyService {
     std::atomic<uint64_t> applied_seq_id_{0};
     std::atomic<uint64_t> primary_seq_id_{0};
     std::atomic<ErrorCode> last_error_{ErrorCode::OK};
+    std::atomic<bool> recovering_{false};
 
     // State machine for managing service lifecycle
     StandbyStateMachine state_machine_;
@@ -286,11 +306,22 @@ class HotStandbyService {
     std::atomic<bool> replication_loop_running_{false};
     std::mutex replication_loop_mutex_;
     std::condition_variable replication_loop_cv_;
+    mutable std::mutex batch_snapshot_cursor_mutex_;
+    std::optional<DurablePrefix> last_applied_batch_snapshot_prefix_;
+
+    std::shared_ptr<BatchOpLogSnapshotCapture::LeaseState>
+        snapshot_capture_state_{
+            std::make_shared<BatchOpLogSnapshotCapture::LeaseState>()};
+    std::optional<BatchOpLogSnapshotCapture> ready_snapshot_capture_;
 
     // Synchronization
     mutable std::mutex mutex_;
     mutable std::mutex sync_status_callback_mutex_;
+    mutable std::mutex snapshot_lifecycle_callback_mutex_;
     SyncStatusCallback sync_status_callback_;
+    SnapshotLifecycleCallback snapshot_capture_released_callback_;
+    SnapshotLifecycleCallback snapshot_promotion_callback_;
+    SnapshotLifecycleCallback snapshot_stop_callback_;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/hybrid_metric.h b/mooncake-store/include/hybrid_metric.h
index d2ecad1b5f..d9b7dcfe62 100644
--- a/mooncake-store/include/hybrid_metric.h
+++ b/mooncake-store/include/hybrid_metric.h
@@ -17,13 +17,9 @@ class basic_hybrid_counter
     basic_hybrid_counter(std::string name, std::string help,
                          std::map<std::string, std::string> static_labels,
                          std::array<std::string, N> labels_name)
-        : Base(MetricType::Counter, std::move(name), std::move(help),
-               std::move(labels_name)),
-          static_labels_(static_labels) {
-        for (auto& [k, v] : static_labels) {
-            static_labels_str_.append(k).append("=\"").append(v).append("\",");
-        }
-    }
+        : basic_hybrid_counter(MetricType::Counter, std::move(name),
+                               std::move(help), std::move(static_labels),
+                               std::move(labels_name)) {}
     using label_key_type = const std::array<std::string, N>&;
     void inc(label_key_type labels_value, value_type value = 1) {
         detail::inc_impl(Base::try_emplace(labels_value).first->value, value);
@@ -167,6 +163,18 @@ class basic_hybrid_counter
 #endif
 
    protected:
+    // Lets a derived metric reuse this implementation while announcing its own
+    // MetricType, which is what the "# TYPE" line is rendered from.
+    basic_hybrid_counter(MetricType type, std::string name, std::string help,
+                         std::map<std::string, std::string> static_labels,
+                         std::array<std::string, N> labels_name)
+        : Base(type, std::move(name), std::move(help), std::move(labels_name)),
+          static_labels_(static_labels) {
+        for (auto& [k, v] : static_labels) {
+            static_labels_str_.append(k).append("=\"").append(v).append("\",");
+        }
+    }
+
     template <typename T>
     void serialize_map(T& value_map, std::string& str) {
         for (auto& e : value_map) {
@@ -210,6 +218,23 @@ class basic_hybrid_counter
     std::map<std::string, std::string> static_labels_;
 };
 
+// A gauge shares the hybrid counter's storage and serialization; only the
+// declared MetricType differs, so that Prometheus is not told a value that can
+// fall is monotonic.
+template <typename value_type, uint8_t N>
+class basic_hybrid_gauge : public basic_hybrid_counter<value_type, N> {
+    using Base = basic_hybrid_counter<value_type, N>;
+
+   public:
+    basic_hybrid_gauge(std::string name, std::string help,
+                       std::map<std::string, std::string> static_labels,
+                       std::array<std::string, N> labels_name)
+        : Base(MetricType::Gauge, std::move(name), std::move(help),
+               std::move(static_labels), std::move(labels_name)) {}
+};
+
+using hybrid_gauge_1t = basic_hybrid_gauge<int64_t, 1>;
+
 using hybrid_counter_1t = basic_hybrid_counter<int64_t, 1>;
 using hybrid_counter_1d = basic_hybrid_counter<double, 1>;
 
@@ -289,8 +314,10 @@ class basic_hybrid_histogram : public dynamic_metric {
             return;
         }
 
+        const auto initial_size = str.size();
         serialize_head(str);
 
+        bool emitted_any = false;
         std::string value_str;
         auto bucket_counts = get_bucket_counts();
         for (auto& e : value_map) {
@@ -300,6 +327,7 @@ class basic_hybrid_histogram : public dynamic_metric {
                 continue;
             }
 
+            value_str.clear();
             value_type count = 0;
             for (size_t i = 0; i < bucket_counts.size(); i++) {
                 auto counter = bucket_counts[i];
@@ -324,6 +352,7 @@ class basic_hybrid_histogram : public dynamic_metric {
             }
 
             str.append(value_str);
+            emitted_any = true;
 
             std::string labels_str;
             build_label_string_with_static(labels_str, sum_->labels_name(),
@@ -341,8 +370,8 @@ class basic_hybrid_histogram : public dynamic_metric {
             str.append(std::to_string(count));
             str.append("\n");
         }
-        if (value_str.empty()) {
-            str.clear();
+        if (!emitted_any) {
+            str.resize(initial_size);
         }
     }
 
diff --git a/mooncake-store/include/kv_event/key_util.h b/mooncake-store/include/kv_event/key_util.h
deleted file mode 100644
index 6c90900ae8..0000000000
--- a/mooncake-store/include/kv_event/key_util.h
+++ /dev/null
@@ -1,36 +0,0 @@
-#pragma once
-
-#include <cstdint>
-#include <optional>
-#include <string>
-
-namespace mooncake {
-
-// Parses object keys encoded as decimal or 0x-prefixed hex u64 hashes.
-inline std::optional<uint64_t> ParseSeqHashFromObjectKey(
-    const std::string& object_key) {
-    if (object_key.empty()) {
-        return std::nullopt;
-    }
-    try {
-        size_t idx = 0;
-        if (object_key.size() >= 2 &&
-            (object_key[0] == '0' &&
-             (object_key[1] == 'x' || object_key[1] == 'X'))) {
-            uint64_t value = std::stoull(object_key, &idx, 16);
-            if (idx == object_key.size()) {
-                return value;
-            }
-            return std::nullopt;
-        }
-        uint64_t value = std::stoull(object_key, &idx, 10);
-        if (idx == object_key.size()) {
-            return value;
-        }
-    } catch (const std::exception&) {
-        return std::nullopt;
-    }
-    return std::nullopt;
-}
-
-}  // namespace mooncake
diff --git a/mooncake-store/include/kv_event/kv_event_config.h b/mooncake-store/include/kv_event/kv_event_config.h
index 794019f1ba..448e821c0f 100644
--- a/mooncake-store/include/kv_event/kv_event_config.h
+++ b/mooncake-store/include/kv_event/kv_event_config.h
@@ -5,10 +5,10 @@
 
 namespace mooncake {
 
-// Publisher transport/identity for the optional KV Events ZMQ socket (RFC
-// #1527). Semantic block fields (model_name, block_size, lora_name,
-// parent_hash, token_ids, dp_rank) belong on each event payload, not here — see
-// https://docs.nvidia.com/dynamo/kv-managers/kv-events-for-custom-engines
+// Publisher transport, identity, and fixed model context for the optional KV
+// Events ZMQ socket (RFC #1527). One publisher serves one model/block-size/
+// LoRA/DP context. Per-object fields such as tenant_id, parent_hash, and
+// token_ids are not interpreted by the storage publisher.
 struct KvEventConfig {
     bool enabled{false};
     // ZMQ PUB bind address, e.g. "tcp://0.0.0.0:5557".
@@ -23,12 +23,15 @@ struct KvEventConfig {
     // full.
     uint32_t queue_capacity{65536};
 
-    // Deprecated: not stamped on events. Indexer registration supplies model,
-    // block_size, dp_rank, and hash namespace for the Mooncake publisher.
+    // Fixed publisher context supplied by the Master configuration.
     std::string model_name;
+    // Retained for config compatibility. Published tenant_id comes from each
+    // object operation so one publisher can preserve tenant isolation.
     std::string tenant_id{"default"};
     std::string additional_salt;
+    // Empty means the base model.
     std::string lora_name;
+    // Zero means unknown and is emitted as nil.
     uint32_t block_size{0};
     uint32_t dp_rank{0};
 };
diff --git a/mooncake-store/include/kv_event/kv_event_publisher.h b/mooncake-store/include/kv_event/kv_event_publisher.h
index 1db093dad5..9e72c03e13 100644
--- a/mooncake-store/include/kv_event/kv_event_publisher.h
+++ b/mooncake-store/include/kv_event/kv_event_publisher.h
@@ -6,13 +6,12 @@
 #include <deque>
 #include <memory>
 #include <mutex>
-#include <optional>
 #include <string>
 #include <thread>
+#include <utility>
 #include <vector>
 
 #include "kv_event/kv_event_config.h"
-#include "kv_event/key_util.h"
 #include "tenant_id.h"
 
 namespace mooncake {
@@ -31,39 +30,74 @@ class KvEventPublisher {
     bool enabled() const { return config_.enabled; }
 
     // Non-blocking enqueue into a bounded queue; drops oldest when full.
+    // The string overloads keep the wire format independent of Store's
+    // TenantId wrapper; the TenantId overloads preserve the existing API.
     void PublishStored(const std::string& object_key, const std::string& medium,
-                       const TenantId& tenant_id = TenantId::Default(),
+                       const std::string& tenant_id = "",
                        const std::string& group_id = "");
+    void PublishStored(const std::string& object_key, const std::string& medium,
+                       const TenantId& tenant_id,
+                       const std::string& group_id = "") {
+        PublishStored(object_key, medium, tenant_id.value(), group_id);
+    }
     void PublishRemoved(const std::string& object_key,
                         const std::string& medium,
-                        const TenantId& tenant_id = TenantId::Default(),
+                        const std::string& tenant_id = "",
                         const std::string& group_id = "");
+    void PublishRemoved(const std::string& object_key,
+                        const std::string& medium, const TenantId& tenant_id,
+                        const std::string& group_id = "") {
+        PublishRemoved(object_key, medium, tenant_id.value(), group_id);
+    }
+    void PublishCleared(const std::string& tenant_id = "");
+
+    // The publisher keeps no per-object state: every delta below is computed
+    // from the arguments alone. Callers already snapshot the medium set before
+    // mutating metadata, so they are the authoritative source for it.
+
+    // Publish a successful Put/Upsert commit. Every currently available medium
+    // receives a stored event. A commit is always announced, even when the
+    // medium set is unchanged, because the object contents may have changed.
+    void PublishCommitted(const std::string& object_key,
+                          const std::vector<std::string>& current_media,
+                          const std::string& tenant_id = "",
+                          const std::string& group_id = "");
+
+    // Synchronize replica availability after an internal metadata mutation.
+    // previous_media is the medium set captured before the mutation; media that
+    // disappeared get a removed event and media that appeared get a stored one.
+    void SyncObjectState(const std::string& object_key,
+                         const std::vector<std::string>& current_media,
+                         const std::string& tenant_id = "",
+                         const std::string& group_id = "",
+                         const std::vector<std::string>& previous_media = {});
+
+    // Publish removal of every medium the object had before deletion.
+    void PublishObjectRemoved(
+        const std::string& object_key, const std::string& tenant_id = "",
+        const std::string& group_id = "",
+        const std::vector<std::string>& previous_media = {});
 
     struct Stats {
         uint64_t published_batches{0};
         uint64_t published_events{0};
         uint64_t dropped_events{0};
-        uint64_t skipped_unparsed_keys{0};
+        uint64_t skipped_keyless_events{0};
     };
     Stats GetStats() const;
 
-    static std::optional<uint64_t> ParseSeqHashFromObjectKey(
-        const std::string& object_key) {
-        return mooncake::ParseSeqHashFromObjectKey(object_key);
-    }
-
    private:
-    enum class EventKind { kStored, kRemoved };
+    enum class EventKind { kStored, kRemoved, kCleared };
 
     struct PendingEvent {
         EventKind kind;
         std::string object_key;
         std::string medium;
-        TenantId tenant_id;
+        std::string tenant_id;
         std::string group_id;
     };
 
-    void Enqueue(PendingEvent event);
+    void EnqueueBatch(std::vector<PendingEvent> events);
     void WorkerLoop();
     void PublishBatch(const std::vector<PendingEvent>& batch);
     void DrainRemainingQueue(std::vector<PendingEvent>& batch);
@@ -84,7 +118,7 @@ class KvEventPublisher {
     std::atomic<uint64_t> published_batches_{0};
     std::atomic<uint64_t> published_events_{0};
     std::atomic<uint64_t> dropped_events_{0};
-    std::atomic<uint64_t> skipped_unparsed_keys_{0};
+    std::atomic<uint64_t> skipped_keyless_events_{0};
 };
 
 #else
@@ -98,25 +132,31 @@ class KvEventPublisher {
     bool enabled() const { return false; }
 
     void PublishStored(const std::string&, const std::string&,
-                       const TenantId& = TenantId::Default(),
+                       const std::string& = "", const std::string& = "") {}
+    void PublishStored(const std::string&, const std::string&, const TenantId&,
                        const std::string& = "") {}
     void PublishRemoved(const std::string&, const std::string&,
-                        const TenantId& = TenantId::Default(),
+                        const std::string& = "", const std::string& = "") {}
+    void PublishRemoved(const std::string&, const std::string&, const TenantId&,
                         const std::string& = "") {}
+    void PublishCleared(const std::string& = "") {}
+    void PublishCommitted(const std::string&, const std::vector<std::string>&,
+                          const std::string& = "", const std::string& = "") {}
+    void SyncObjectState(const std::string&, const std::vector<std::string>&,
+                         const std::string& = "", const std::string& = "",
+                         const std::vector<std::string>& = {}) {}
+    void PublishObjectRemoved(const std::string&, const std::string& = "",
+                              const std::string& = "",
+                              const std::vector<std::string>& = {}) {}
 
     struct Stats {
         uint64_t published_batches{0};
         uint64_t published_events{0};
         uint64_t dropped_events{0};
-        uint64_t skipped_unparsed_keys{0};
+        uint64_t skipped_keyless_events{0};
     };
     Stats GetStats() const { return {}; }
 
-    static std::optional<uint64_t> ParseSeqHashFromObjectKey(
-        const std::string& object_key) {
-        return mooncake::ParseSeqHashFromObjectKey(object_key);
-    }
-
    private:
     KvEventConfig config_;
 };
diff --git a/mooncake-store/include/lease.h b/mooncake-store/include/lease.h
new file mode 100644
index 0000000000..f06ed11b21
--- /dev/null
+++ b/mooncake-store/include/lease.h
@@ -0,0 +1,76 @@
+// lease.h
+//
+// Lock-free shared deadline for a group: every member holds a shared_ptr to the
+// same Lease (CAS monotonic-max), so a read of any member extends one TTL.
+
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+
+namespace mooncake {
+
+class Lease {
+   public:
+    // Extend the deadline (monotonic max) to now + ttl. The read path
+    // advertises the full ttl to clients, so the server must honor now + ttl
+    // rather than keeping an earlier existing deadline (which would let the
+    // server evict before the client-held lease expires).
+    void GrantReadLease(std::chrono::milliseconds ttl) {
+        const auto ttl_ns =
+            std::chrono::duration_cast<std::chrono::nanoseconds>(ttl).count();
+        const int64_t now = NowNs();
+        const int64_t new_deadline = now + ttl_ns;
+        int64_t cur = deadline_ns_.load(std::memory_order_relaxed);
+        while (cur < new_deadline &&
+               !deadline_ns_.compare_exchange_weak(cur, new_deadline,
+                                                   std::memory_order_relaxed)) {
+        }
+    }
+
+    // Merge an externally-derived deadline (used when rebuilding a group's
+    // lease from a snapshot so the group TTL is the max of member deadlines).
+    void ExtendTo(const std::chrono::system_clock::time_point deadline) {
+        const int64_t d = std::chrono::duration_cast<std::chrono::nanoseconds>(
+                              deadline.time_since_epoch())
+                              .count();
+        int64_t cur = deadline_ns_.load(std::memory_order_relaxed);
+        while (cur < d && !deadline_ns_.compare_exchange_weak(
+                              cur, d, std::memory_order_relaxed)) {
+        }
+    }
+
+    // Overwrite the deadline with an exact value (may lower it). Unlike
+    // GrantReadLease/ExtendTo (monotonic max), this lets test scaffolding
+    // (e.g. the scenario DSL) force a lease to a precise expiry.
+    void SetDeadline(const std::chrono::system_clock::time_point deadline) {
+        deadline_ns_.store(NowNs(deadline), std::memory_order_relaxed);
+    }
+
+    // True when the group has not been read within the TTL at `now`.
+    bool IsExpired(const std::chrono::system_clock::time_point now) const {
+        return NowNs(now) >= deadline_ns_.load(std::memory_order_relaxed);
+    }
+
+    std::chrono::system_clock::time_point ExpiresAt() const {
+        return std::chrono::system_clock::time_point(std::chrono::nanoseconds(
+            deadline_ns_.load(std::memory_order_relaxed)));
+    }
+
+   private:
+    static int64_t NowNs() {
+        return std::chrono::duration_cast<std::chrono::nanoseconds>(
+                   std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    }
+    static int64_t NowNs(std::chrono::system_clock::time_point t) {
+        return std::chrono::duration_cast<std::chrono::nanoseconds>(
+                   t.time_since_epoch())
+            .count();
+    }
+
+    std::atomic<int64_t> deadline_ns_{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/local_hot_cache.h b/mooncake-store/include/local_hot_cache.h
index 3fa827f331..4ecd6bd953 100644
--- a/mooncake-store/include/local_hot_cache.h
+++ b/mooncake-store/include/local_hot_cache.h
@@ -19,6 +19,15 @@
 
 namespace mooncake {
 
+struct LocalHotCacheConfig {
+    size_t total_size_bytes = 0;
+    size_t block_size_bytes = 16 * 1024 * 1024;
+    bool use_shm = false;
+    uint8_t admission_threshold = 2;
+
+    static LocalHotCacheConfig FromEnvironment();
+};
+
 /**
  * @brief Token captured at async hot cache fill submission time.
  * Invalidated when RemoveHotKey, BumpKeyGeneration, or Clear bumps
diff --git a/mooncake-store/include/local_ssd/manager.h b/mooncake-store/include/local_ssd/manager.h
new file mode 100644
index 0000000000..2a55075850
--- /dev/null
+++ b/mooncake-store/include/local_ssd/manager.h
@@ -0,0 +1,153 @@
+#pragma once
+
+#include <atomic>
+#include <boost/functional/hash.hpp>
+#include <memory>
+#include <optional>
+#include <shared_mutex>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+#include <ylt/util/tl/expected.hpp>
+
+#include "local_ssd/persisted_state.h"
+#include "mutex.h"
+#include "tenant_id.h"
+#include "types.h"
+
+namespace mooncake {
+
+class LocalSsdTaskMailbox {
+   public:
+    explicit LocalSsdTaskMailbox(bool enable_offloading);
+
+    ErrorCode EnqueueOffload(OffloadTaskItem task, size_t limit);
+    std::vector<OffloadTaskItem> SetOffloadingAndTakePending(bool enabled);
+    bool RemoveOffload(const TenantId& tenant_id, std::string_view key);
+
+    ErrorCode EnqueuePromotion(PromotionTaskItem task);
+    std::vector<PromotionTaskItem> TakePromotions(size_t max_items);
+    bool RemovePromotion(const TenantId& tenant_id, std::string_view key);
+    // Re-mark a queued promotion as most-recently-touched. No-op (returns
+    // false) when the key is not queued, e.g. already taken by a heartbeat.
+    bool TouchPromotion(const TenantId& tenant_id, std::string_view key);
+
+    void RequestRemoveAll();
+    bool ConsumeRemoveAll();
+
+   private:
+    mutable Mutex mutex_;
+    bool enable_offloading_ GUARDED_BY(mutex_);
+    std::unordered_map<std::string, OffloadTaskItem> pending_offloads_
+        GUARDED_BY(mutex_);
+    // Dedup map + recency order. seq is monotone; enqueue, a duplicate
+    // enqueue, and TouchPromotion all re-mark the entry with a fresh seq, so
+    // TakePromotions can deliver the most-recently-touched key first instead
+    // of an arbitrary (hash-order) one.
+    struct PromotionEntry {
+        PromotionTaskItem task;
+        uint64_t seq;
+    };
+    std::unordered_map<std::string, PromotionEntry> pending_promotions_
+        GUARDED_BY(mutex_);
+    uint64_t promotion_seq_ GUARDED_BY(mutex_){0};
+    bool pending_remove_all_ GUARDED_BY(mutex_){false};
+
+    friend class LocalSsdManager;
+};
+
+class LocalSsdManager {
+   public:
+    struct CapacityChange {
+        int64_t previous_bytes;
+        int64_t current_bytes;
+    };
+
+    struct Usage {
+        int64_t total_capacity_bytes;
+        int64_t used_bytes;
+    };
+
+    ErrorCode RegisterClient(const UUID& client_id, bool enable_offloading);
+    std::optional<int64_t> UnregisterClient(const UUID& client_id);
+
+    // UUIDs of all registered LocalSSD clients. Used to rebuild client
+    // liveness records after an HA snapshot restore.
+    std::vector<UUID> GetClientIds() const;
+
+    tl::expected<CapacityChange, ErrorCode> ReportCapacity(
+        const UUID& client_id, int64_t bytes);
+
+    std::optional<Usage> GetUsage(const UUID& client_id) const;
+    bool AdjustUsedBytes(const UUID& client_id, int64_t delta);
+
+    ErrorCode EnqueueOffload(const UUID& client_id, OffloadTaskItem task,
+                             size_t limit);
+    tl::expected<std::vector<OffloadTaskItem>, ErrorCode>
+    SetOffloadingAndTakePending(const UUID& client_id, bool enabled);
+    bool RemoveOffload(const UUID& client_id, const TenantId& tenant_id,
+                       std::string_view key);
+    size_t RemoveOffloadFromAll(const TenantId& tenant_id,
+                                std::string_view key);
+    bool CancelOffloadsIfAllPending(const std::vector<UUID>& client_ids,
+                                    const TenantId& tenant_id,
+                                    std::string_view key);
+
+    ErrorCode EnqueuePromotion(const UUID& client_id, PromotionTaskItem task);
+    tl::expected<std::vector<PromotionTaskItem>, ErrorCode> TakePromotions(
+        const UUID& client_id, size_t max_items);
+    bool RemovePromotion(const UUID& client_id, const TenantId& tenant_id,
+                         std::string_view key);
+    bool TouchPromotion(const UUID& client_id, const TenantId& tenant_id,
+                        std::string_view key);
+
+    void RequestRemoveAll();
+    void RequestRemoveAll(const std::vector<UUID>& clients);
+    tl::expected<bool, ErrorCode> ConsumeRemoveAll(const UUID& client_id);
+
+    LocalSsdPersistedState ExportPersistedState() const;
+    void RestorePersistedState(LocalSsdPersistedState state);
+    void Clear();
+
+   private:
+    struct ClientRecord {
+        explicit ClientRecord(bool enable_offloading)
+            : mailbox(enable_offloading) {}
+
+        // Unregistration removes the record from clients_ first, then takes
+        // this lock exclusively to wait for operations that already found it.
+        mutable std::shared_mutex lifecycle_mutex;
+        mutable Mutex stats_mutex;
+        int64_t total_capacity_bytes GUARDED_BY(stats_mutex){0};
+        std::atomic<int64_t> used_bytes{0};
+        LocalSsdTaskMailbox mailbox;
+    };
+
+    struct ClientAccess {
+        ClientAccess(UUID id, std::shared_ptr<ClientRecord> client)
+            : client_id(id),
+              record(std::move(client)),
+              lifecycle_lock(record->lifecycle_mutex) {}
+        ClientAccess(ClientAccess&&) noexcept = default;
+        ClientAccess& operator=(ClientAccess&&) noexcept = default;
+        ClientAccess(const ClientAccess&) = delete;
+        ClientAccess& operator=(const ClientAccess&) = delete;
+
+        UUID client_id;
+        std::shared_ptr<ClientRecord> record;
+        std::shared_lock<std::shared_mutex> lifecycle_lock;
+    };
+
+    using ClientMap = std::unordered_map<UUID, std::shared_ptr<ClientRecord>,
+                                         boost::hash<UUID>>;
+
+    std::optional<ClientAccess> FindClient(const UUID& client_id) const;
+    std::vector<ClientAccess> SnapshotClients() const;
+    static void WaitForOperations(const ClientMap& clients);
+
+    mutable std::shared_mutex mutex_;
+    ClientMap clients_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/local_ssd/persisted_state.h b/mooncake-store/include/local_ssd/persisted_state.h
new file mode 100644
index 0000000000..861e568a26
--- /dev/null
+++ b/mooncake-store/include/local_ssd/persisted_state.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#include <map>
+#include <string>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct LocalSsdPersistedClient {
+    bool enable_offloading{false};
+    int64_t total_capacity_bytes{0};
+
+    // The codec iterates this map directly, so ordering by the legacy encoded
+    // key makes the snapshot bytes deterministic without rewriting that key.
+    std::map<std::string, OffloadTaskItem> pending_offloads;
+};
+
+// UUID ordering likewise makes client encoding deterministic.
+using LocalSsdPersistedState = std::map<UUID, LocalSsdPersistedClient>;
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/master_admin_service.h b/mooncake-store/include/master_admin_service.h
index 9d7dd60cb5..0403e55ae1 100644
--- a/mooncake-store/include/master_admin_service.h
+++ b/mooncake-store/include/master_admin_service.h
@@ -23,7 +23,8 @@ class WrappedMasterService;
 
 class MasterAdminServer {
    public:
-    MasterAdminServer(uint16_t http_port, bool enable_metric_reporting);
+    MasterAdminServer(uint16_t http_port, bool enable_metric_reporting,
+                      std::string http_host = "0.0.0.0");
 
     ~MasterAdminServer();
 
@@ -67,6 +68,8 @@ class MasterAdminServer {
                               coro_http::coro_http_response& resp);
     void HandleHealth(coro_http::coro_http_request& req,
                       coro_http::coro_http_response& resp);
+    void HandleVersion(coro_http::coro_http_request& req,
+                       coro_http::coro_http_response& resp);
     void HandleRole(coro_http::coro_http_request& req,
                     coro_http::coro_http_response& resp);
     void HandleHaStatus(coro_http::coro_http_request& req,
@@ -83,6 +86,10 @@ class MasterAdminServer {
                                  coro_http::coro_http_response& resp);
     void HandleQuerySegment(coro_http::coro_http_request& req,
                             coro_http::coro_http_response& resp);
+    void HandleGetDfsShardCount(coro_http::coro_http_request& req,
+                                coro_http::coro_http_response& resp);
+    async_simple::coro::Lazy<void> HandleExpandDfsShards(
+        coro_http::coro_http_request& req, coro_http::coro_http_response& resp);
     void HandleCreateDrainJob(coro_http::coro_http_request& req,
                               coro_http::coro_http_response& resp);
     void HandleQueryDrainJob(coro_http::coro_http_request& req,
@@ -105,14 +112,23 @@ class MasterAdminServer {
                          coro_http::coro_http_response& resp);
 
     void RegisterHandler();
+    void RefreshStorageMetrics() const;
 
     uint16_t http_port_;
+    std::string http_host_;
     bool enable_metric_reporting_ = false;
     coro_http::coro_http_server http_server_;
     std::thread metric_report_thread_;
     std::atomic<bool> metric_report_running_{false};
     std::binary_semaphore metric_report_stop_sem_{0};
     std::atomic<bool> started_{false};
+    // Retained by each handler across its blocking operation and completion.
+    // Only one admin expansion may be pending, including disconnected requests.
+    std::shared_ptr<std::atomic<bool>> dfs_expansion_running_{
+        std::make_shared<std::atomic<bool>>(false)};
+    // Serializes storage projection with service-plane handoff so a refresh
+    // that sampled the old leader cannot publish after it becomes unavailable.
+    mutable std::mutex storage_metrics_refresh_mutex_;
     mutable std::mutex state_mutex_;
     ha::MasterRuntimeState state_{ha::MasterRuntimeState::kStarting};
     std::optional<ha::MasterView> leader_view_;
diff --git a/mooncake-store/include/master_client.h b/mooncake-store/include/master_client.h
index 0955bb4e99..04784b65f9 100644
--- a/mooncake-store/include/master_client.h
+++ b/mooncake-store/include/master_client.h
@@ -1,18 +1,22 @@
 #pragma once
 
+#include <atomic>
 #include <csignal>
 #include <memory>
 #include <string>
 #include <type_traits>
 #include <vector>
 #include <variant>
-#include <cstdlib>
 #include <boost/functional/hash.hpp>
 #include <ylt/coro_rpc/coro_rpc_client.hpp>
 #include <ylt/coro_io/client_pool.hpp>
+#ifdef YLT_ENABLE_IBV
 #include <ylt/coro_io/ibverbs/ib_socket.hpp>
+#endif
 
 #include "client_metric.h"
+#include "config/rpc_protocol_config.h"
+#include "config/rpc_timeout_config.h"
 #include "replica.h"
 #include "segment.h"
 #include "types.h"
@@ -40,29 +44,47 @@ inline constexpr bool variant_contains_v =
 
 template <typename SocketConfigVariant>
 inline void MaybeEnableRdmaSocketConfig(SocketConfigVariant& socket_config) {
+#ifdef YLT_ENABLE_IBV
     if constexpr (variant_contains_v<SocketConfigVariant,
                                      coro_io::ib_socket_t::config_t>) {
         socket_config = coro_io::ib_socket_t::config_t{};
     }
+#endif
 }
 
-inline RpcClientPool::PoolConfig MakeMasterRpcClientPoolConfig() {
-    RpcClientPool::PoolConfig config;
-    const char* value = std::getenv("MC_RPC_PROTOCOL");
-    if (value && std::string_view(value) == "rdma") {
-        MaybeEnableRdmaSocketConfig(config.client_config.socket_config);
+// Applies the RPC timeout overrides to any mooncake-store RPC client config.
+// Shared by the client->master pool and the store->store offload pool so the
+// two cannot drift. Absent overrides leave the caller's defaults in place.
+// A negative request timeout disables the per-request timer.
+template <typename ClientConfig>
+inline void ApplyRpcTimeoutOverrides(ClientConfig& client_config,
+                                     const RpcTimeoutConfig& config) {
+    if (config.request_timeout.has_value()) {
+        client_config.request_timeout_duration = *config.request_timeout;
     }
+    if (config.connect_timeout.has_value()) {
+        client_config.connect_timeout_duration = *config.connect_timeout;
+    }
+}
 
-    // Default request and connect timeouts remain coro_rpc's built-in 30s.
-    // A negative request timeout disables the per-request timer.
-    if (const char* timeout_ms = std::getenv("MC_RPC_TIMEOUT_MS")) {
-        config.client_config.request_timeout_duration =
-            std::chrono::milliseconds(std::atoll(timeout_ms));
+inline RpcClientPool::PoolConfig MakeMasterRpcClientPoolConfig(
+    bool ha_enabled = false) {
+    RpcClientPool::PoolConfig config;
+    if (ha_enabled) {
+        // HA monitor and heartbeat loops own the retry schedule. Keep each
+        // attempt bounded so a deleted pod IP that silently drops SYNs cannot
+        // block failover on YLT's default 4 x 30-second retry budget.
+        config.connect_retry_count = 0;
+        config.reconnect_wait_time = std::chrono::milliseconds{0};
+        config.client_config.connect_timeout_duration = std::chrono::seconds{1};
     }
-    if (const char* connect_ms = std::getenv("MC_RPC_CONNECT_TIMEOUT_MS")) {
-        config.client_config.connect_timeout_duration =
-            std::chrono::milliseconds(std::atoll(connect_ms));
+
+    if (RpcProtocolConfig::FromEnvironment().use_rdma) {
+        MaybeEnableRdmaSocketConfig(config.client_config.socket_config);
     }
+
+    ApplyRpcTimeoutOverrides(config.client_config,
+                             RpcTimeoutConfig::FromEnvironment());
     return config;
 }
 
@@ -77,11 +99,20 @@ class MasterClient {
                  std::string tenant_id = "default")
         : client_accessor_(GetStoreRpcClientIoContextPool(),
                            detail::MakeMasterRpcClientPoolConfig()),
+          ha_control_client_accessor_(
+              GetStoreRpcClientIoContextPool(),
+              detail::MakeMasterRpcClientPoolConfig(/*ha_enabled=*/true)),
+          ha_probe_client_accessor_(
+              GetStoreRpcClientIoContextPool(),
+              detail::MakeMasterRpcClientPoolConfig(/*ha_enabled=*/true)),
           client_id_(client_id),
           tenant_id_(std::move(tenant_id)),
           metrics_(metrics) {}
+    // Drains in-flight RPCs before the pool member is released (#3909).
     ~MasterClient();
 
+    void EnableHaConnectionPolicy();
+
     const std::string& tenant_id() const { return tenant_id_.value(); }
 
     MasterClient(const MasterClient&) = delete;
@@ -103,6 +134,15 @@ class MasterClient {
     [[nodiscard]] tl::expected<bool, ErrorCode> ExistKey(
         const std::string& object_key);
 
+    /**
+     * @brief Point-in-time existence check that grants no read lease
+     * @param object_key Key to query
+     * @return tl::expected<bool, ErrorCode> indicating exist or not at the
+     * time of the call; the object may still be evicted afterwards
+     */
+    [[nodiscard]] tl::expected<bool, ErrorCode> ProbeKey(
+        const std::string& object_key);
+
     /**
      * @brief Checks if multiple objects exist
      * @param object_keys Vector of keys to query
@@ -111,6 +151,15 @@ class MasterClient {
     [[nodiscard]] std::vector<tl::expected<bool, ErrorCode>> BatchExistKey(
         const std::vector<std::string>& object_keys);
 
+    /**
+     * @brief Point-in-time existence check for multiple objects, granting no
+     * read leases
+     * @param object_keys Vector of keys to query
+     * @return Vector containing existence status for each key
+     */
+    [[nodiscard]] std::vector<tl::expected<bool, ErrorCode>> BatchProbeKey(
+        const std::vector<std::string>& object_keys);
+
     /**
      * @brief Calculate Store-observed cache reuse metrics
      * @param object_keys None
@@ -413,6 +462,13 @@ class MasterClient {
     [[nodiscard]] tl::expected<void, ErrorCode> MountLocalDiskSegment(
         const UUID& client_id, bool enable_offloading);
 
+    /**
+     * @brief Deregisters this client's local disk segment from the master,
+     * dropping the LOCAL_DISK replicas it owns. Idempotent.
+     */
+    [[nodiscard]] tl::expected<void, ErrorCode> UnmountLocalDiskSegment(
+        const UUID& client_id);
+
     /**
      * @brief Heartbeat call to collect object-level statistics and retrieve the
      * set of non-persisted objects.
@@ -504,6 +560,13 @@ class MasterClient {
         const std::string& key, const std::string& tenant_id,
         const std::string& src_segment,
         const std::vector<std::string>& tgt_segments);
+    [[nodiscard]] tl::expected<CopyStartResponse, ErrorCode>
+    DynamicReplicaCopyStart(const std::string& key,
+                            const std::string& tenant_id,
+                            const std::string& src_segment,
+                            const std::vector<std::string>& tgt_segments,
+                            const UUID& dynamic_replication_lease_id,
+                            uint64_t dynamic_replication_version_epoch);
 
     /**
      * @brief End a copy operation
@@ -513,6 +576,10 @@ class MasterClient {
     [[nodiscard]] tl::expected<void, ErrorCode> CopyEnd(const std::string& key);
     [[nodiscard]] tl::expected<void, ErrorCode> CopyEnd(
         const std::string& key, const std::string& tenant_id);
+    [[nodiscard]] tl::expected<void, ErrorCode> DynamicReplicaCopyEnd(
+        const std::string& key, const std::string& tenant_id,
+        const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
 
     /**
      * @brief Revoke a copy operation
@@ -523,6 +590,10 @@ class MasterClient {
         const std::string& key);
     [[nodiscard]] tl::expected<void, ErrorCode> CopyRevoke(
         const std::string& key, const std::string& tenant_id);
+    [[nodiscard]] tl::expected<void, ErrorCode> DynamicReplicaCopyRevoke(
+        const std::string& key, const std::string& tenant_id,
+        const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
 
     /**
      * @brief Start a move operation
@@ -653,6 +724,16 @@ class MasterClient {
     [[nodiscard]] tl::expected<ReturnType, ErrorCode> invoke_rpc(
         Args&&... args);
 
+    template <auto ServiceMethod, typename ReturnType, typename... Args>
+    [[nodiscard]] tl::expected<ReturnType, ErrorCode> invoke_rpc_with_pool(
+        RpcClientPool& client_accessor, Args&&... args);
+
+    template <auto ServiceMethod, typename ReturnType, typename... Args>
+    [[nodiscard]] tl::expected<ReturnType, ErrorCode>
+    invoke_rpc_with_client_pool(
+        const std::shared_ptr<RpcClientPool::ClientPool>& client_pool,
+        Args&&... args);
+
     /**
      * @brief Generic RPC invocation helper for batch operations
      * @tparam ServiceMethod Pointer to WrappedMasterService member function
@@ -667,6 +748,9 @@ class MasterClient {
     invoke_batch_rpc(size_t input_size, Args&&... args);
 
     RpcClientPool client_accessor_;
+    RpcClientPool ha_control_client_accessor_;
+    RpcClientPool ha_probe_client_accessor_;
+    RpcDrainGuard rpc_drain_;
 
     // The client identification.
     const UUID client_id_;
@@ -680,6 +764,7 @@ class MasterClient {
     mutable Mutex connect_mutex_;
     // The address which is passed to the coro_rpc_client
     std::string client_addr_param_ GUARDED_BY(connect_mutex_);
+    std::atomic<bool> ha_connection_policy_enabled_{false};
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/master_config.h b/mooncake-store/include/master_config.h
index 2940d0e59d..18d11cccfe 100644
--- a/mooncake-store/include/master_config.h
+++ b/mooncake-store/include/master_config.h
@@ -11,6 +11,70 @@
 
 namespace mooncake {
 
+struct ClientLivenessConfigSource {
+    std::optional<int64_t> active_ttl_sec;
+    std::optional<int64_t> legacy_ttl_sec;
+    std::optional<int64_t> suspicion_ttl_sec;
+};
+
+struct ResolvedClientLivenessConfig {
+    int64_t active_ttl_sec;
+    int64_t suspicion_ttl_sec;
+    bool config_active_conflict;
+    bool command_line_active_conflict;
+};
+
+inline ResolvedClientLivenessConfig ResolveClientLivenessConfig(
+    const ClientLivenessConfigSource& config_file,
+    const ClientLivenessConfigSource& command_line,
+    int64_t default_active_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC,
+    int64_t default_suspicion_ttl_sec = DEFAULT_CLIENT_SUSPICION_TTL_SEC) {
+    const auto validate_source = [](const ClientLivenessConfigSource& source) {
+        for (const auto value : {source.active_ttl_sec, source.legacy_ttl_sec,
+                                 source.suspicion_ttl_sec}) {
+            if (value.has_value() && *value <= 0) {
+                throw std::invalid_argument(
+                    "Client liveness TTLs must be positive");
+            }
+        }
+    };
+    validate_source(config_file);
+    validate_source(command_line);
+    if (default_active_ttl_sec <= 0 || default_suspicion_ttl_sec <= 0) {
+        throw std::invalid_argument(
+            "Default Client liveness TTLs must be positive");
+    }
+
+    const bool config_conflict =
+        config_file.active_ttl_sec.has_value() &&
+        config_file.legacy_ttl_sec.has_value() &&
+        config_file.active_ttl_sec != config_file.legacy_ttl_sec;
+    const bool command_line_conflict =
+        command_line.active_ttl_sec.has_value() &&
+        command_line.legacy_ttl_sec.has_value() &&
+        command_line.active_ttl_sec != command_line.legacy_ttl_sec;
+
+    const int64_t config_active = config_file.active_ttl_sec.value_or(
+        config_file.legacy_ttl_sec.value_or(default_active_ttl_sec));
+    const int64_t active = command_line.active_ttl_sec.value_or(
+        command_line.legacy_ttl_sec.value_or(config_active));
+    const bool active_explicitly_configured =
+        command_line.active_ttl_sec.has_value() ||
+        command_line.legacy_ttl_sec.has_value() ||
+        config_file.active_ttl_sec.has_value() ||
+        config_file.legacy_ttl_sec.has_value();
+    const int64_t suspicion = command_line.suspicion_ttl_sec.value_or(
+        config_file.suspicion_ttl_sec.value_or(
+            active_explicitly_configured ? active : default_suspicion_ttl_sec));
+
+    return {
+        .active_ttl_sec = active,
+        .suspicion_ttl_sec = suspicion,
+        .config_active_conflict = config_conflict,
+        .command_line_active_conflict = command_line_conflict,
+    };
+}
+
 // Forwarded to the HA serve phase via MasterServiceSupervisorConfig.
 class HttpMetadataServer;
 
@@ -30,6 +94,7 @@ inline std::string ResolveConfiguredHABackendConnstring(
 struct MasterConfig {
     bool enable_metric_reporting;
     uint32_t metrics_port;
+    std::string metrics_host;
     uint32_t rpc_port;
     uint32_t rpc_thread_num;
     std::string rpc_address;
@@ -39,12 +104,15 @@ struct MasterConfig {
 
     uint64_t default_kv_lease_ttl;
     uint64_t default_kv_soft_pin_ttl;
+    uint64_t max_kv_soft_pin_ttl = DEFAULT_MAX_KV_SOFT_PIN_TTL_MS;
     bool allow_evict_soft_pinned_objects;
     double eviction_ratio;
     double eviction_high_watermark_ratio;
+    double tenant_eviction_high_watermark_ratio;
     double nof_eviction_ratio;
     double nof_eviction_high_watermark_ratio;
-    int64_t client_live_ttl_sec;
+    int64_t client_active_ttl_sec;
+    int64_t client_suspicion_ttl_sec;
     int64_t nof_heartbeat_interval_sec;
     uint32_t nof_heartbeat_probe_timeout_ms;
     uint32_t nof_heartbeat_failures_threshold;
@@ -57,6 +125,8 @@ struct MasterConfig {
 
     // OpLog store configuration
     bool enable_oplog = false;
+    bool enable_oplog_snapshot = false;
+    uint64_t snapshot_chunk_object_count = 1000000;
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     uint32_t batch_oplog_retry_timeout_sec = 180;
@@ -139,6 +209,13 @@ struct MasterConfig {
     // rich clusters may safely raise it.
     uint32_t promotion_max_per_heartbeat = 1;
 
+    // Dynamic MEMORY replica fanout for hot read-only objects.
+    // Kept intentionally small: mode + frequency window + max replicas.
+    std::string dynamic_replication_mode = "off";
+    uint32_t dynamic_replication_heat_window_seconds = 10;
+    double dynamic_replication_admission_qps_threshold = 0.8;
+    size_t dynamic_replication_max_memory_replicas = 2;
+
     // KV Events publisher (RFC #1527) for cache-aware indexers.
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
@@ -169,7 +246,8 @@ class MasterServiceSupervisorConfig {
     RequiredParam<double> nof_eviction_ratio{"nof_eviction_ratio"};
     RequiredParam<double> nof_eviction_high_watermark_ratio{
         "nof_eviction_high_watermark_ratio"};
-    RequiredParam<int64_t> client_live_ttl_sec{"client_live_ttl_sec"};
+    RequiredParam<int64_t> client_active_ttl_sec{"client_active_ttl_sec"};
+    RequiredParam<int64_t> client_suspicion_ttl_sec{"client_suspicion_ttl_sec"};
     RequiredParam<int64_t> nof_heartbeat_interval_sec{
         "nof_heartbeat_interval_sec"};
     RequiredParam<uint32_t> nof_heartbeat_probe_timeout_ms{
@@ -181,7 +259,11 @@ class MasterServiceSupervisorConfig {
     RequiredParam<size_t> rpc_thread_num{"rpc_thread_num"};
 
     // Parameters with default values (optional parameters)
+    double tenant_eviction_high_watermark_ratio =
+        DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO;
+    uint64_t max_kv_soft_pin_ttl = DEFAULT_MAX_KV_SOFT_PIN_TTL_MS;
     std::string rpc_address = "0.0.0.0";
+    std::string metrics_host = "0.0.0.0";
     std::chrono::steady_clock::duration rpc_conn_timeout = std::chrono::seconds(
         0);  // Client connection timeout. 0 = no timeout (infinite)
     bool rpc_enable_tcp_no_delay = true;
@@ -190,6 +272,8 @@ class MasterServiceSupervisorConfig {
     std::string etcd_endpoints = "0.0.0.0:2379";
     // OpLog store configuration
     bool enable_oplog = false;
+    bool enable_oplog_snapshot = false;
+    uint64_t snapshot_chunk_object_count = 1000000;
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     uint32_t batch_oplog_retry_timeout_sec = 180;
@@ -238,6 +322,10 @@ class MasterServiceSupervisorConfig {
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
     uint32_t promotion_max_per_heartbeat = 1;
+    std::string dynamic_replication_mode = "off";
+    uint32_t dynamic_replication_heat_window_seconds = 10;
+    double dynamic_replication_admission_qps_threshold = 0.8;
+    size_t dynamic_replication_max_memory_replicas = 2;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
     std::string kv_events_model_name;
@@ -269,16 +357,21 @@ class MasterServiceSupervisorConfig {
         // Set required parameters using RequiredParam
         enable_metric_reporting = config.enable_metric_reporting;
         metrics_port = static_cast<int>(config.metrics_port);
+        metrics_host = config.metrics_host;
         default_kv_lease_ttl = config.default_kv_lease_ttl;
         default_kv_soft_pin_ttl = config.default_kv_soft_pin_ttl;
+        max_kv_soft_pin_ttl = config.max_kv_soft_pin_ttl;
         allow_evict_soft_pinned_objects =
             config.allow_evict_soft_pinned_objects;
         eviction_ratio = config.eviction_ratio;
         eviction_high_watermark_ratio = config.eviction_high_watermark_ratio;
+        tenant_eviction_high_watermark_ratio =
+            config.tenant_eviction_high_watermark_ratio;
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
-        client_live_ttl_sec = config.client_live_ttl_sec;
+        client_active_ttl_sec = config.client_active_ttl_sec;
+        client_suspicion_ttl_sec = config.client_suspicion_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
         nof_heartbeat_probe_timeout_ms = config.nof_heartbeat_probe_timeout_ms;
         nof_heartbeat_failures_threshold =
@@ -292,6 +385,13 @@ class MasterServiceSupervisorConfig {
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
+        dynamic_replication_mode = config.dynamic_replication_mode;
+        dynamic_replication_heat_window_seconds =
+            config.dynamic_replication_heat_window_seconds;
+        dynamic_replication_admission_qps_threshold =
+            config.dynamic_replication_admission_qps_threshold;
+        dynamic_replication_max_memory_replicas =
+            config.dynamic_replication_max_memory_replicas;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
         kv_events_model_name = config.kv_events_model_name;
@@ -317,6 +417,8 @@ class MasterServiceSupervisorConfig {
         ha_backend_connstring = ResolveConfiguredHABackendConnstring(
             ha_backend_type, config.ha_backend_connstring, etcd_endpoints);
         enable_oplog = config.enable_oplog;
+        enable_oplog_snapshot = config.enable_oplog_snapshot;
+        snapshot_chunk_object_count = config.snapshot_chunk_object_count;
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         batch_oplog_retry_timeout_sec = config.batch_oplog_retry_timeout_sec;
@@ -423,8 +525,11 @@ class MasterServiceSupervisorConfig {
             throw std::runtime_error(
                 "nof_eviction_high_watermark_ratio is not set");
         }
-        if (!client_live_ttl_sec.IsSet()) {
-            throw std::runtime_error("client_live_ttl_sec is not set");
+        if (!client_active_ttl_sec.IsSet()) {
+            throw std::runtime_error("client_active_ttl_sec is not set");
+        }
+        if (!client_suspicion_ttl_sec.IsSet()) {
+            throw std::runtime_error("client_suspicion_ttl_sec is not set");
         }
         if (!nof_heartbeat_interval_sec.IsSet()) {
             throw std::runtime_error("nof_heartbeat_interval_sec is not set");
@@ -453,6 +558,7 @@ class WrappedMasterServiceConfig {
 
     // Optional parameters (with default values)
     uint64_t default_kv_soft_pin_ttl = DEFAULT_KV_SOFT_PIN_TTL_MS;
+    uint64_t max_kv_soft_pin_ttl = DEFAULT_MAX_KV_SOFT_PIN_TTL_MS;
     bool allow_evict_soft_pinned_objects =
         DEFAULT_ALLOW_EVICT_SOFT_PINNED_OBJECTS;
     bool enable_metric_reporting = true;
@@ -460,11 +566,14 @@ class WrappedMasterServiceConfig {
     double eviction_ratio = DEFAULT_EVICTION_RATIO;
     double eviction_high_watermark_ratio =
         DEFAULT_EVICTION_HIGH_WATERMARK_RATIO;
+    double tenant_eviction_high_watermark_ratio =
+        DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO;
     double nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
     double nof_eviction_high_watermark_ratio =
         DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
     ViewVersionId view_version = 0;
-    int64_t client_live_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    int64_t client_active_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    int64_t client_suspicion_ttl_sec = DEFAULT_CLIENT_SUSPICION_TTL_SEC;
     int64_t nof_heartbeat_interval_sec = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
     uint32_t nof_heartbeat_probe_timeout_ms =
         DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS;
@@ -480,6 +589,10 @@ class WrappedMasterServiceConfig {
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
     uint32_t promotion_max_per_heartbeat = 1;
+    std::string dynamic_replication_mode = "off";
+    uint32_t dynamic_replication_heat_window_seconds = 10;
+    double dynamic_replication_admission_qps_threshold = 0.8;
+    size_t dynamic_replication_max_memory_replicas = 2;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
     std::string kv_events_model_name;
@@ -496,6 +609,8 @@ class WrappedMasterServiceConfig {
     std::string ha_backend_connstring;
     // OpLog store configuration
     bool enable_oplog = false;
+    bool enable_oplog_snapshot = false;
+    uint64_t snapshot_chunk_object_count = 1000000;
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     std::string cluster_id = DEFAULT_CLUSTER_ID;
@@ -544,17 +659,21 @@ class WrappedMasterServiceConfig {
 
         // Set optional parameters (these have default values)
         default_kv_soft_pin_ttl = config.default_kv_soft_pin_ttl;
+        max_kv_soft_pin_ttl = config.max_kv_soft_pin_ttl;
         allow_evict_soft_pinned_objects =
             config.allow_evict_soft_pinned_objects;
         enable_metric_reporting = config.enable_metric_reporting;
         http_port = static_cast<uint16_t>(config.metrics_port);
         eviction_ratio = config.eviction_ratio;
         eviction_high_watermark_ratio = config.eviction_high_watermark_ratio;
+        tenant_eviction_high_watermark_ratio =
+            config.tenant_eviction_high_watermark_ratio;
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
         view_version = view_version_param;
-        client_live_ttl_sec = config.client_live_ttl_sec;
+        client_active_ttl_sec = config.client_active_ttl_sec;
+        client_suspicion_ttl_sec = config.client_suspicion_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
         nof_heartbeat_probe_timeout_ms = config.nof_heartbeat_probe_timeout_ms;
         nof_heartbeat_failures_threshold =
@@ -569,6 +688,13 @@ class WrappedMasterServiceConfig {
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
+        dynamic_replication_mode = config.dynamic_replication_mode;
+        dynamic_replication_heat_window_seconds =
+            config.dynamic_replication_heat_window_seconds;
+        dynamic_replication_admission_qps_threshold =
+            config.dynamic_replication_admission_qps_threshold;
+        dynamic_replication_max_memory_replicas =
+            config.dynamic_replication_max_memory_replicas;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
         kv_events_model_name = config.kv_events_model_name;
@@ -586,6 +712,8 @@ class WrappedMasterServiceConfig {
             ha_backend_type, config.ha_backend_connstring,
             config.etcd_endpoints);
         enable_oplog = config.enable_oplog;
+        enable_oplog_snapshot = config.enable_oplog_snapshot;
+        snapshot_chunk_object_count = config.snapshot_chunk_object_count;
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
@@ -659,17 +787,21 @@ class WrappedMasterServiceConfig {
 
         // Set optional parameters (these have default values)
         default_kv_soft_pin_ttl = config.default_kv_soft_pin_ttl;
+        max_kv_soft_pin_ttl = config.max_kv_soft_pin_ttl;
         allow_evict_soft_pinned_objects =
             config.allow_evict_soft_pinned_objects;
         enable_metric_reporting = config.enable_metric_reporting;
         http_port = static_cast<uint16_t>(config.metrics_port);
         eviction_ratio = config.eviction_ratio;
         eviction_high_watermark_ratio = config.eviction_high_watermark_ratio;
+        tenant_eviction_high_watermark_ratio =
+            config.tenant_eviction_high_watermark_ratio;
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
         view_version = view_version_param;
-        client_live_ttl_sec = config.client_live_ttl_sec;
+        client_active_ttl_sec = config.client_active_ttl_sec;
+        client_suspicion_ttl_sec = config.client_suspicion_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
         nof_heartbeat_probe_timeout_ms = config.nof_heartbeat_probe_timeout_ms;
         nof_heartbeat_failures_threshold =
@@ -685,6 +817,13 @@ class WrappedMasterServiceConfig {
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
+        dynamic_replication_mode = config.dynamic_replication_mode;
+        dynamic_replication_heat_window_seconds =
+            config.dynamic_replication_heat_window_seconds;
+        dynamic_replication_admission_qps_threshold =
+            config.dynamic_replication_admission_qps_threshold;
+        dynamic_replication_max_memory_replicas =
+            config.dynamic_replication_max_memory_replicas;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
         kv_events_model_name = config.kv_events_model_name;
@@ -702,6 +841,8 @@ class WrappedMasterServiceConfig {
             ha_backend_type, config.ha_backend_connstring,
             config.etcd_endpoints);
         enable_oplog = config.enable_oplog;
+        enable_oplog_snapshot = config.enable_oplog_snapshot;
+        snapshot_chunk_object_count = config.snapshot_chunk_object_count;
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
@@ -748,16 +889,21 @@ class MasterServiceConfigBuilder {
    private:
     uint64_t default_kv_lease_ttl_ = DEFAULT_DEFAULT_KV_LEASE_TTL;
     uint64_t default_kv_soft_pin_ttl_ = DEFAULT_KV_SOFT_PIN_TTL_MS;
+    uint64_t max_kv_soft_pin_ttl_ = DEFAULT_MAX_KV_SOFT_PIN_TTL_MS;
     bool allow_evict_soft_pinned_objects_ =
         DEFAULT_ALLOW_EVICT_SOFT_PINNED_OBJECTS;
     double eviction_ratio_ = DEFAULT_EVICTION_RATIO;
     double eviction_high_watermark_ratio_ =
         DEFAULT_EVICTION_HIGH_WATERMARK_RATIO;
+    double tenant_eviction_high_watermark_ratio_ =
+        DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO;
     double nof_eviction_ratio_ = DEFAULT_NOF_EVICTION_RATIO;
     double nof_eviction_high_watermark_ratio_ =
         DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
     ViewVersionId view_version_ = 0;
-    int64_t client_live_ttl_sec_ = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    int64_t client_active_ttl_sec_ = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    bool client_active_ttl_explicitly_set_ = false;
+    std::optional<int64_t> client_suspicion_ttl_sec_;
     int64_t nof_heartbeat_interval_sec_ = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
     uint32_t nof_heartbeat_probe_timeout_ms_ =
         DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS;
@@ -769,6 +915,8 @@ class MasterServiceConfigBuilder {
     std::string ha_backend_connstring_;
     // OpLog store configuration
     bool enable_oplog_ = false;
+    bool enable_oplog_snapshot_ = false;
+    uint64_t snapshot_chunk_object_count_ = 1000000;
     int oplog_poll_interval_ms_ = 1000;
     uint32_t oplog_batch_max_entries_ = 1024;
     std::string cluster_id_ = DEFAULT_CLUSTER_ID;
@@ -818,6 +966,11 @@ class MasterServiceConfigBuilder {
         return *this;
     }
 
+    MasterServiceConfigBuilder& set_max_kv_soft_pin_ttl(uint64_t ttl) {
+        max_kv_soft_pin_ttl_ = ttl;
+        return *this;
+    }
+
     MasterServiceConfigBuilder& set_allow_evict_soft_pinned_objects(
         bool allow) {
         allow_evict_soft_pinned_objects_ = allow;
@@ -835,6 +988,12 @@ class MasterServiceConfigBuilder {
         return *this;
     }
 
+    MasterServiceConfigBuilder& set_tenant_eviction_high_watermark_ratio(
+        double ratio) {
+        tenant_eviction_high_watermark_ratio_ = ratio;
+        return *this;
+    }
+
     MasterServiceConfigBuilder& set_nof_eviction_ratio(double ratio) {
         nof_eviction_ratio_ = ratio;
         return *this;
@@ -852,7 +1011,19 @@ class MasterServiceConfigBuilder {
     }
 
     MasterServiceConfigBuilder& set_client_live_ttl_sec(int64_t ttl) {
-        client_live_ttl_sec_ = ttl;
+        client_active_ttl_sec_ = ttl;
+        client_active_ttl_explicitly_set_ = true;
+        return *this;
+    }
+
+    MasterServiceConfigBuilder& set_client_active_ttl_sec(int64_t ttl) {
+        client_active_ttl_sec_ = ttl;
+        client_active_ttl_explicitly_set_ = true;
+        return *this;
+    }
+
+    MasterServiceConfigBuilder& set_client_suspicion_ttl_sec(int64_t ttl) {
+        client_suspicion_ttl_sec_ = ttl;
         return *this;
     }
 
@@ -900,6 +1071,17 @@ class MasterServiceConfigBuilder {
         return *this;
     }
 
+    MasterServiceConfigBuilder& set_enable_oplog_snapshot(bool enable) {
+        enable_oplog_snapshot_ = enable;
+        return *this;
+    }
+
+    MasterServiceConfigBuilder& set_snapshot_chunk_object_count(
+        uint64_t count) {
+        snapshot_chunk_object_count_ = count;
+        return *this;
+    }
+
     MasterServiceConfigBuilder& set_oplog_poll_interval_ms(int interval_ms) {
         oplog_poll_interval_ms_ = interval_ms;
         return *this;
@@ -1105,16 +1287,22 @@ class MasterServiceConfig {
    public:
     uint64_t default_kv_lease_ttl = DEFAULT_DEFAULT_KV_LEASE_TTL;
     uint64_t default_kv_soft_pin_ttl = DEFAULT_KV_SOFT_PIN_TTL_MS;
+    uint64_t max_kv_soft_pin_ttl = DEFAULT_MAX_KV_SOFT_PIN_TTL_MS;
     bool allow_evict_soft_pinned_objects =
         DEFAULT_ALLOW_EVICT_SOFT_PINNED_OBJECTS;
     double eviction_ratio = DEFAULT_EVICTION_RATIO;
     double eviction_high_watermark_ratio =
         DEFAULT_EVICTION_HIGH_WATERMARK_RATIO;
+    double tenant_eviction_high_watermark_ratio =
+        DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO;
     double nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
     double nof_eviction_high_watermark_ratio =
         DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
+    // Zero denotes a directly constructed, supervisor-unmanaged service;
+    // HA supervisor serving paths always inject the acquired non-zero view.
     ViewVersionId view_version = 0;
-    int64_t client_live_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    int64_t client_active_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    int64_t client_suspicion_ttl_sec = DEFAULT_CLIENT_SUSPICION_TTL_SEC;
     int64_t nof_heartbeat_interval_sec = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
     uint32_t nof_heartbeat_probe_timeout_ms =
         DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS;
@@ -1130,6 +1318,10 @@ class MasterServiceConfig {
     uint32_t promotion_admission_threshold = 2;
     uint32_t promotion_queue_limit = 50000;
     uint32_t promotion_max_per_heartbeat = 1;
+    std::string dynamic_replication_mode = "off";
+    uint32_t dynamic_replication_heat_window_seconds = 10;
+    double dynamic_replication_admission_qps_threshold = 0.8;
+    size_t dynamic_replication_max_memory_replicas = 2;
     bool enable_kv_events = false;
     std::string kv_events_bind_endpoint;
     std::string kv_events_model_name;
@@ -1146,6 +1338,8 @@ class MasterServiceConfig {
     std::string ha_backend_connstring;
     // OpLog store configuration
     bool enable_oplog = false;
+    bool enable_oplog_snapshot = false;
+    uint64_t snapshot_chunk_object_count = 1000000;
     int oplog_poll_interval_ms = 1000;
     uint32_t oplog_batch_max_entries = 1024;
     std::string cluster_id = DEFAULT_CLUSTER_ID;
@@ -1192,15 +1386,19 @@ class MasterServiceConfig {
 
         default_kv_lease_ttl = config.default_kv_lease_ttl;
         default_kv_soft_pin_ttl = config.default_kv_soft_pin_ttl;
+        max_kv_soft_pin_ttl = config.max_kv_soft_pin_ttl;
         allow_evict_soft_pinned_objects =
             config.allow_evict_soft_pinned_objects;
         eviction_ratio = config.eviction_ratio;
         eviction_high_watermark_ratio = config.eviction_high_watermark_ratio;
+        tenant_eviction_high_watermark_ratio =
+            config.tenant_eviction_high_watermark_ratio;
         nof_eviction_ratio = config.nof_eviction_ratio;
         nof_eviction_high_watermark_ratio =
             config.nof_eviction_high_watermark_ratio;
         view_version = config.view_version;
-        client_live_ttl_sec = config.client_live_ttl_sec;
+        client_active_ttl_sec = config.client_active_ttl_sec;
+        client_suspicion_ttl_sec = config.client_suspicion_ttl_sec;
         nof_heartbeat_interval_sec = config.nof_heartbeat_interval_sec;
         nof_heartbeat_probe_timeout_ms = config.nof_heartbeat_probe_timeout_ms;
         nof_heartbeat_failures_threshold =
@@ -1215,6 +1413,13 @@ class MasterServiceConfig {
         promotion_admission_threshold = config.promotion_admission_threshold;
         promotion_queue_limit = config.promotion_queue_limit;
         promotion_max_per_heartbeat = config.promotion_max_per_heartbeat;
+        dynamic_replication_mode = config.dynamic_replication_mode;
+        dynamic_replication_heat_window_seconds =
+            config.dynamic_replication_heat_window_seconds;
+        dynamic_replication_admission_qps_threshold =
+            config.dynamic_replication_admission_qps_threshold;
+        dynamic_replication_max_memory_replicas =
+            config.dynamic_replication_max_memory_replicas;
         enable_kv_events = config.enable_kv_events;
         kv_events_bind_endpoint = config.kv_events_bind_endpoint;
         kv_events_model_name = config.kv_events_model_name;
@@ -1230,6 +1435,8 @@ class MasterServiceConfig {
         ha_backend_type = config.ha_backend_type;
         ha_backend_connstring = config.ha_backend_connstring;
         enable_oplog = config.enable_oplog;
+        enable_oplog_snapshot = config.enable_oplog_snapshot;
+        snapshot_chunk_object_count = config.snapshot_chunk_object_count;
         oplog_poll_interval_ms = config.oplog_poll_interval_ms;
         oplog_batch_max_entries = config.oplog_batch_max_entries;
         cluster_id = config.cluster_id;
@@ -1279,17 +1486,28 @@ class MasterServiceConfig {
 
 // Implementation of MasterServiceConfigBuilder::build()
 inline MasterServiceConfig MasterServiceConfigBuilder::build() const {
+    const int64_t suspicion_ttl = client_suspicion_ttl_sec_.value_or(
+        client_active_ttl_explicitly_set_ ? client_active_ttl_sec_
+                                          : DEFAULT_CLIENT_SUSPICION_TTL_SEC);
+    if (client_active_ttl_sec_ <= 0 || suspicion_ttl <= 0) {
+        throw std::invalid_argument("Client liveness TTLs must be positive");
+    }
+
     MasterServiceConfig config;
     config.default_kv_lease_ttl = default_kv_lease_ttl_;
     config.default_kv_soft_pin_ttl = default_kv_soft_pin_ttl_;
+    config.max_kv_soft_pin_ttl = max_kv_soft_pin_ttl_;
     config.allow_evict_soft_pinned_objects = allow_evict_soft_pinned_objects_;
     config.eviction_ratio = eviction_ratio_;
     config.eviction_high_watermark_ratio = eviction_high_watermark_ratio_;
+    config.tenant_eviction_high_watermark_ratio =
+        tenant_eviction_high_watermark_ratio_;
     config.nof_eviction_ratio = nof_eviction_ratio_;
     config.nof_eviction_high_watermark_ratio =
         nof_eviction_high_watermark_ratio_;
     config.view_version = view_version_;
-    config.client_live_ttl_sec = client_live_ttl_sec_;
+    config.client_active_ttl_sec = client_active_ttl_sec_;
+    config.client_suspicion_ttl_sec = suspicion_ttl;
     config.nof_heartbeat_interval_sec = nof_heartbeat_interval_sec_;
     config.nof_heartbeat_probe_timeout_ms = nof_heartbeat_probe_timeout_ms_;
     config.nof_heartbeat_failures_threshold = nof_heartbeat_failures_threshold_;
@@ -1298,6 +1516,8 @@ inline MasterServiceConfig MasterServiceConfigBuilder::build() const {
     config.ha_backend_type = ha_backend_type_;
     config.ha_backend_connstring = ha_backend_connstring_;
     config.enable_oplog = enable_oplog_;
+    config.enable_oplog_snapshot = enable_oplog_snapshot_;
+    config.snapshot_chunk_object_count = snapshot_chunk_object_count_;
     config.oplog_poll_interval_ms = oplog_poll_interval_ms_;
     config.oplog_batch_max_entries = oplog_batch_max_entries_;
     config.cluster_id = cluster_id_;
diff --git a/mooncake-store/include/master_heartbeat_metric.h b/mooncake-store/include/master_heartbeat_metric.h
new file mode 100644
index 0000000000..a08e4c100a
--- /dev/null
+++ b/mooncake-store/include/master_heartbeat_metric.h
@@ -0,0 +1,135 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <utility>
+#include <ylt/metric/gauge.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+// A sampled Ping response, not segment completeness or data-plane health.
+// Connection generations prevent a late response from reviving an observation
+// after reconnect. No metric lock is held across a network operation.
+class MasterHeartbeatMetric {
+   public:
+    explicit MasterHeartbeatMetric(
+        const std::map<std::string, std::string>& labels = {})
+        : status_ok_("mooncake_client_master_heartbeat_status_ok",
+                     "Last observed Master Ping status: 1 for OK, 0 for "
+                     "NEED_REMOUNT; absent when unknown",
+                     EscapeLabels(labels)),
+          timestamp_seconds_(
+              "mooncake_client_master_heartbeat_observation_timestamp_seconds",
+              "Client Unix receive time of the same Master Ping observation "
+              "in seconds; absent when unknown",
+              EscapeLabels(labels)) {}
+
+    template <typename Fn>
+    ErrorCode ObserveConnect(Fn&& connect) {
+        const auto generation = BeginConnection();
+        const auto result = std::forward<Fn>(connect)();
+        EndConnection(generation, result == ErrorCode::OK);
+        return result;
+    }
+
+    template <typename Fn>
+    auto ObservePing(Fn&& ping) {
+        // Capture the generation before the RPC so reconnects invalidate late
+        // successes and failures. The callback runs without holding mutex_.
+        const auto generation = BeginObservation();
+        auto result = std::forward<Fn>(ping)();
+        std::optional<bool> status_ok;
+        double timestamp_seconds = 0;
+        if (result) {
+            switch (result->client_status) {
+                case ClientStatus::OK:
+                    status_ok = true;
+                    break;
+                case ClientStatus::NEED_REMOUNT:
+                    status_ok = false;
+                    break;
+                default:
+                    break;
+            }
+            timestamp_seconds =
+                std::chrono::duration<double>(
+                    std::chrono::system_clock::now().time_since_epoch())
+                    .count();
+        }
+        Observe(generation, status_ok, timestamp_seconds);
+        return result;
+    }
+
+    uint64_t BeginConnection() {
+        std::lock_guard<std::mutex> lock(mutex_);
+        connected_ = false;
+        known_ = false;
+        return ++generation_;
+    }
+
+    void EndConnection(uint64_t generation, bool connected) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (generation == generation_) connected_ = connected;
+    }
+
+    std::optional<uint64_t> BeginObservation() const {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!connected_) return std::nullopt;
+        return generation_;
+    }
+
+    // nullopt represents a failed Ping or an unsupported status, never a
+    // negative registration verdict. A missing generation means the Ping
+    // overlapped a connection attempt and cannot be attributed safely.
+    void Observe(std::optional<uint64_t> generation,
+                 std::optional<bool> status_ok, double timestamp_seconds) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!connected_ || !generation || *generation != generation_) return;
+        known_ = status_ok.has_value();
+        if (known_) {
+            status_ok_.update(*status_ok ? 1 : 0);
+            timestamp_seconds_.update(timestamp_seconds);
+        }
+    }
+
+    void serialize(std::string& str) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!known_) return;
+        status_ok_.serialize(str);
+        timestamp_seconds_.serialize(str);
+    }
+
+   private:
+    // The pinned YLT static-gauge serializer writes label values verbatim.
+    static std::map<std::string, std::string> EscapeLabels(
+        std::map<std::string, std::string> labels) {
+        for (auto& [name, value] : labels) {
+            std::string escaped;
+            for (char ch : value) {
+                if (ch == '\\' || ch == '"') escaped += '\\';
+                if (ch == '\n') {
+                    escaped += "\\n";
+                } else {
+                    escaped += ch;
+                }
+            }
+            value = std::move(escaped);
+        }
+        return labels;
+    }
+
+    mutable std::mutex mutex_;
+    uint64_t generation_ = 0;
+    bool connected_ = false;
+    bool known_ = false;
+    ylt::metric::gauge_t status_ok_;
+    ylt::metric::gauge_d timestamp_seconds_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/master_metric_manager.h b/mooncake-store/include/master_metric_manager.h
index 07e565d542..10279e9232 100644
--- a/mooncake-store/include/master_metric_manager.h
+++ b/mooncake-store/include/master_metric_manager.h
@@ -3,15 +3,21 @@
 #include <atomic>
 #include <chrono>
 #include <mutex>
+#include <set>
 #include <string>
 #include <unordered_map>
 
+#include "allocator_metric.h"
 #include "ylt/metric/counter.hpp"
 #include "ylt/metric/gauge.hpp"
 #include "ylt/metric/histogram.hpp"
 
+#include "client_liveness.h"
+
 namespace mooncake {
 
+struct TieredStorageUsageSnapshot;
+
 class MasterMetricManager {
    public:
     // --- Singleton Access ---
@@ -29,7 +35,6 @@ class MasterMetricManager {
     void inc_total_mem_capacity(const std::string& segment, int64_t val = 1);
     void dec_total_mem_capacity(const std::string& segment, int64_t val = 1);
     void reset_total_mem_capacity();
-    double get_global_mem_used_ratio(void);
 
     void inc_mem_cache_hit_nums(int64_t val = 1);
     void inc_file_cache_hit_nums(int64_t val = 1);
@@ -55,7 +60,14 @@ class MasterMetricManager {
     void inc_total_nof_capacity(const std::string& segment, int64_t val = 1);
     void dec_total_nof_capacity(const std::string& segment, int64_t val = 1);
     void reset_total_nof_capacity();
-    double get_global_nof_used_ratio(void);
+
+    /**
+     * @brief Refresh storage gauges from authoritative allocator snapshots.
+     *
+     * This is an observability projection. Business code must use the domain
+     * snapshots directly and must not read the resulting gauges.
+     */
+    void project_storage_usage(const TieredStorageUsageSnapshot& snapshot);
 
     enum class CacheHitStat {
         MEMORY_HITS,
@@ -81,28 +93,27 @@ class MasterMetricManager {
     CacheHitStatDict calculate_cache_stats();
 
     // Memory Storage Metrics
-    void inc_allocated_mem_size(int64_t val = 1);
-    void dec_allocated_mem_size(int64_t val = 1);
-    void inc_total_mem_capacity(int64_t val = 1);
-    void dec_total_mem_capacity(int64_t val = 1);
     int64_t get_allocated_mem_size();
     int64_t get_total_mem_capacity();
-    double get_segment_mem_used_ratio(const std::string& segment);
     void reset_segment_allocated_mem_size(const std::string& segment);
     void reset_segment_total_mem_capacity(const std::string& segment);
     int64_t get_segment_allocated_mem_size(const std::string& segment);
     int64_t get_segment_total_mem_capacity(const std::string& segment);
 
+    // Remove per-segment memory labels only when both usage and capacity are
+    // zero. Allocator destruction and capacity release retry cleanup when
+    // retained resources are released. Cleanup is best-effort: the zero check
+    // and removal are not atomic with concurrent updates, avoiding a global
+    // lock on the allocation hot path.
+    void remove_segment_metrics(const std::string& segment);
+
     // NoF segment Metrics
-    void inc_allocated_nof_size(int64_t val = 1);
-    void dec_allocated_nof_size(int64_t val = 1);
-    void inc_total_nof_capacity(int64_t val = 1);
-    void dec_total_nof_capacity(int64_t val = 1);
     int64_t get_allocated_nof_size();
     int64_t get_total_nof_capacity();
-    double get_segment_nof_used_ratio(const std::string& segment);
     int64_t get_segment_allocated_nof_size(const std::string& segment);
     int64_t get_segment_total_nof_capacity(const std::string& segment);
+    // Remove all per-segment NoF metric labels for the given segment.
+    void remove_nof_segment_metrics(const std::string& segment);
 
     // File Storage Metrics
     void inc_allocated_file_size(int64_t val = 1);
@@ -130,6 +141,17 @@ class MasterMetricManager {
     void inc_active_clients(int64_t val = 1);
     void dec_active_clients(int64_t val = 1);
     int64_t get_active_clients();
+    void client_liveness_record_created();
+    void client_liveness_became_suspected();
+    void client_liveness_recovered();
+    void client_liveness_became_offline();
+    void on_client_liveness_record_removed(ClientLivenessState state);
+    void reset_client_liveness_metrics(int64_t active_records = 0);
+    void inc_client_offboarding_queue_depth(int64_t jobs = 1);
+    void dec_client_offboarding_queue_depth(int64_t jobs = 1);
+    void inc_client_offboarding_retry();
+    void inc_client_offboarding_alert();
+    void observe_client_offboarding_duration_ms(int64_t duration_ms);
 
     // Snapshot Metrics
     void set_snapshot_duration_ms(int64_t size);
@@ -139,6 +161,7 @@ class MasterMetricManager {
     // Operation Statistics (Counters)
     void inc_put_start_requests(int64_t val = 1);
     void inc_put_start_failures(int64_t val = 1);
+    void inc_put_start_object_already_exists(int64_t val = 1);
     void inc_put_start_alloc_failures(int64_t val = 1);
     void inc_put_start_partial_allocations(int64_t val = 1);
     void inc_put_end_requests(int64_t val = 1);
@@ -192,6 +215,7 @@ class MasterMetricManager {
     void inc_batch_get_replica_list_partial_success(int64_t failed_items);
     void inc_batch_put_start_requests(int64_t items);
     void inc_batch_put_start_failures(int64_t failed_items);
+    void inc_batch_put_start_object_already_exists(int64_t items);
     void inc_batch_put_start_partial_success(int64_t failed_items);
     void inc_batch_put_end_requests(int64_t items);
     void inc_batch_put_end_failures(int64_t failed_items);
@@ -203,6 +227,7 @@ class MasterMetricManager {
     // Operation Statistics Getters
     int64_t get_put_start_requests();
     int64_t get_put_start_failures();
+    int64_t get_put_start_object_already_exists();
     int64_t get_put_start_alloc_failures();
     int64_t get_put_start_partial_allocations();
     int64_t get_put_end_requests();
@@ -253,6 +278,7 @@ class MasterMetricManager {
     int64_t get_batch_get_replica_list_failed_items();
     int64_t get_batch_put_start_requests();
     int64_t get_batch_put_start_failures();
+    int64_t get_batch_put_start_object_already_exists();
     int64_t get_batch_put_start_partial_successes();
     int64_t get_batch_put_start_items();
     int64_t get_batch_put_start_failed_items();
@@ -312,6 +338,7 @@ class MasterMetricManager {
     void inc_promotion_completed_bytes(int64_t bytes);
     void inc_promotion_expired(int64_t val = 1);
     void inc_promotion_failed(int64_t val = 1);
+    void inc_promotion_execution_gave_up(int64_t val = 1);
     void inc_promotion_cancelled(int64_t val = 1);
     void inc_promotion_rejected_frequency(int64_t val = 1);
     void inc_promotion_rejected_watermark(int64_t val = 1);
@@ -330,6 +357,14 @@ class MasterMetricManager {
     void inc_promotion_candidate_expired_unevaluated(int64_t val = 1);
     void inc_promotion_candidate_dropped_limit(int64_t val = 1);
 
+    // SSD Offload Task Metrics (per store worker via client_id label)
+    void inc_offload_enqueued(const std::string& client_id, int64_t val = 1);
+    void inc_offload_completed(const std::string& client_id, int64_t val = 1);
+    void inc_offload_failed(const std::string& client_id, int64_t val = 1);
+    void inc_offload_cancelled(const std::string& client_id, int64_t val = 1);
+    void inc_offload_enqueue_rejected(const std::string& client_id,
+                                      int64_t val = 1);
+
     // Promotion-on-hit Metrics Getters
     int64_t get_promotion_in_flight();
     int64_t get_promotion_admitted();
@@ -337,6 +372,7 @@ class MasterMetricManager {
     int64_t get_promotion_completed_bytes();
     int64_t get_promotion_expired();
     int64_t get_promotion_failed();
+    int64_t get_promotion_execution_gave_up();
     int64_t get_promotion_cancelled();
     int64_t get_promotion_rejected_frequency();
     int64_t get_promotion_rejected_watermark();
@@ -530,6 +566,12 @@ class MasterMetricManager {
     std::mutex summary_snapshot_mutex_;
     SummarySnapshot summary_snapshot_;
 
+    std::mutex storage_projection_mutex_;
+    std::set<std::string> projected_mem_segments_;
+    std::set<std::string> projected_nof_segments_;
+
+    AllocatorMetric allocator_metric_;
+
     // Memory Storage Metrics
     ylt::metric::gauge_t
         mem_allocated_size_;  // Overall memory usage update for gauge
@@ -566,10 +608,21 @@ class MasterMetricManager {
 
     // Cluster Metrics
     ylt::metric::gauge_t active_clients_;
+    ylt::metric::gauge_t client_liveness_active_clients_;
+    ylt::metric::gauge_t client_liveness_suspected_clients_;
+    ylt::metric::gauge_t client_liveness_offline_clients_;
+    ylt::metric::counter_t client_liveness_suspected_transitions_;
+    ylt::metric::counter_t client_liveness_recoveries_;
+    ylt::metric::counter_t client_liveness_offline_transitions_;
+    ylt::metric::gauge_t pending_client_offboarding_jobs_metric_;
+    ylt::metric::histogram_t client_offboarding_duration_ms_;
+    ylt::metric::counter_t client_offboarding_retries_;
+    ylt::metric::counter_t client_offboarding_alerts_;
 
     // Operation Statistics
     ylt::metric::counter_t put_start_requests_;
     ylt::metric::counter_t put_start_failures_;
+    ylt::metric::counter_t put_start_object_already_exists_;
     ylt::metric::counter_t put_start_alloc_failures_;
     ylt::metric::counter_t put_start_partial_allocations_;
     ylt::metric::counter_t put_end_requests_;
@@ -631,6 +684,7 @@ class MasterMetricManager {
     ylt::metric::counter_t batch_get_replica_list_failed_items_;
     ylt::metric::counter_t batch_put_start_requests_;
     ylt::metric::counter_t batch_put_start_failures_;
+    ylt::metric::counter_t batch_put_start_object_already_exists_;
     ylt::metric::counter_t batch_put_start_partial_successes_;
     ylt::metric::counter_t batch_put_start_items_;
     ylt::metric::counter_t batch_put_start_failed_items_;
@@ -696,6 +750,7 @@ class MasterMetricManager {
     ylt::metric::counter_t promotion_completed_bytes_;
     ylt::metric::counter_t promotion_expired_;
     ylt::metric::counter_t promotion_failed_;
+    ylt::metric::counter_t promotion_execution_gave_up_;
     ylt::metric::counter_t promotion_cancelled_;
     ylt::metric::counter_t promotion_rejected_frequency_;
     ylt::metric::counter_t promotion_rejected_watermark_;
@@ -711,6 +766,13 @@ class MasterMetricManager {
     ylt::metric::dynamic_counter_2t tenant_quota_reject_total_;
     ylt::metric::dynamic_counter_1t tenant_evict_bytes_total_;
 
+    // SSD Offload Task Metrics
+    ylt::metric::dynamic_counter_1t offload_enqueued_total_;
+    ylt::metric::dynamic_counter_1t offload_completed_total_;
+    ylt::metric::dynamic_counter_1t offload_failed_total_;
+    ylt::metric::dynamic_counter_1t offload_cancelled_total_;
+    ylt::metric::dynamic_counter_1t offload_enqueue_rejected_total_;
+
     // Snapshot Metrics
     ylt::metric::histogram_t snapshot_duration_ms_;
     ylt::metric::counter_t snapshot_success_;
@@ -742,6 +804,16 @@ class MasterMetricManager {
     ylt::metric::counter_t fetch_tasks_failures_;
     ylt::metric::counter_t mark_task_to_complete_requests_;
     ylt::metric::counter_t mark_task_to_complete_failures_;
+
+    // Build Info Metric
+    // Prometheus "info" pattern: the value carries no meaning and is always 1,
+    // the version strings are exposed as labels so dashboards and alerts can
+    // group or filter by the running build. The label values are compile-time
+    // constants, so this is a single-series gauge with static labels rather
+    // than a dynamic-label metric.
+    // Shares the `mooncake_build_info` name with the client-side metric; the
+    // two are told apart by the scrape target's job/instance labels.
+    ylt::metric::gauge_t build_info_;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/master_service.h b/mooncake-store/include/master_service.h
index 2988f21ba6..cbdd060991 100644
--- a/mooncake-store/include/master_service.h
+++ b/mooncake-store/include/master_service.h
@@ -1,17 +1,20 @@
 #pragma once
 
+#include <algorithm>
 #include <array>
 #include <atomic>
 #include <boost/functional/hash.hpp>
-#include <boost/lockfree/queue.hpp>
 #include <chrono>
 #include <condition_variable>
 #include <cstdint>
+#include <deque>
 #include <functional>
 #include <list>
+#include <limits>
 #include <memory>
 #include <mutex>
 #include <optional>
+#include <queue>
 #include <shared_mutex>
 #include <string>
 #include <string_view>
@@ -24,19 +27,28 @@
 #include <ylt/util/tl/expected.hpp>
 
 #include "allocation_strategy.h"
+#include "background_worker.h"
+#include "client_liveness.h"
+#include "client_offboarding.h"
 #include "count_min_sketch.h"
 #include "deadline_scheduler.h"
+#include "lease.h"
 #include "master_metric_manager.h"
 #include "mutex.h"
 #include "segment.h"
+#include "local_ssd/manager.h"
+#include "tenant_quota_ledger.h"
 #include "tenant_quota_sharded.h"
 #include "tenant_quota_policy_store.h"
 #include "types.h"
 #include "master_config.h"
+#include "object_metadata.h"
+#include "object_runtime_state.h"
 #include "rpc_types.h"
 #include "replica.h"
 #include "ha/ha_types.h"
 #include "ha/snapshot/object/snapshot_object_store.h"
+#include "ha/snapshot/batch_oplog/promotion.h"
 #include "task_manager.h"
 #include "kv_event/kv_event_publisher.h"
 #include "ha/oplog/oplog_types.h"
@@ -54,9 +66,13 @@ namespace ha {
 class SnapshotCatalogStore;
 class MasterSnapshotCodec;
 struct MasterSnapshotPayloads;
-class MasterSnapshotCodecTest;  // test fixture, needs private state access
 }  // namespace ha
 
+class EtcdOpLogStore;
+class DfsGlobalAllocator;
+class DfsAllocatorInterface;
+class ImmutableBucketAllocator;
+
 // Forward declarations
 class AllocationStrategy;
 class EvictionStrategy;
@@ -66,30 +82,28 @@ class OpLogBatchStorage;
 class OrderedOpLogWriter;
 struct MetadataStoragePlugin;
 
-// Forward declarations for test classes
 namespace test {
-class MasterServiceSnapshotTestBase;
-class SnapshotChildProcessTest;
-// Friended so the promotion-on-hit tests can drive a serialize/reset/
-// deserialize cycle directly via the otherwise-private
-// MetadataSerializer, and inspect private clamp fields. This avoids
-// standing up a full snapshot catalog + child-process harness, and
-// exposing test-only accessors on MasterService itself.
-class PromotionOnHitTest;
-class MasterServiceTenantQuotaTest;
-// Friended so the BatchEvict correctness tests can invoke the private
-// BatchEvict entry point and seed lease timestamps directly, instead of
-// relying on segment pressure plus the background eviction thread.
-class BatchEvictTest;
-class MasterServiceHATest;
-// Friended so the processing_keys double-erase reproduction test can
-// invalidate a segment allocator via PrepareUnmountSegment WITHOUT the
-// ClearInvalidHandles sweep that MasterService::UnmountSegment performs.
-class MasterServiceProcessingKeyDoubleEraseTest;
+class MasterServiceTestPeer;
 }  // namespace test
-namespace benchmarks {
-class BatchEvictBench;
-}  // namespace benchmarks
+
+// std::unordered_map/set never shrink their bucket array on erase, so a
+// container that once held millions of entries keeps its high-water bucket
+// memory (8 bytes per bucket) forever. ShrinkBucketsIfSparse rehashes a
+// container down to roughly twice its live size once the bucket array is
+// both large enough to matter and less than a quarter full. The bucket
+// floor avoids rehash churn on small containers; the 2x headroom keeps a
+// freshly shrunk container from growing again right away.
+// Rehashing invalidates iterators: callers must hold the lock guarding the
+// container and must not be iterating it.
+inline constexpr size_t kShrinkMinBucketCount = 1024;
+
+template <typename UnorderedContainer>
+void ShrinkBucketsIfSparse(UnorderedContainer& container) {
+    if (container.bucket_count() > kShrinkMinBucketCount &&
+        container.size() < container.bucket_count() / 4) {
+        container.rehash(container.size() * 2);
+    }
+}
 
 /*
  * @brief MasterService is the main class for the master server.
@@ -100,6 +114,7 @@ class BatchEvictBench;
  * 4. metadata_shards_[shard_idx_].mutex
  * 5. tenant_quota_recompute_mutex_
  * 6. ShardedTenantQuotaTable internal mutex or segment_mutex_
+ * 7. soft_pin_deadline_index_ mutex
  *
  * Strict tenant admission and policy mutation paths that need both
  * tenant_quota_policy_mutex_ and snapshot_mutex_ must acquire the tenant
@@ -108,38 +123,29 @@ class BatchEvictBench;
  * corresponding quota-table update. The segment mutex is released before
  * entering ShardedTenantQuotaTable, so these two locks are never nested.
  */
+
 class MasterService {
-    // Test friend class for snapshot/restore testing
-    friend class test::MasterServiceSnapshotTestBase;
-    friend class test::SnapshotChildProcessTest;
-    friend class test::PromotionOnHitTest;
-    friend class benchmarks::BatchEvictBench;
-    friend class test::MasterServiceTenantQuotaTest;
-    friend class test::BatchEvictTest;
-    // double-erase processing_keys UAF repro (2026-08-03 prod segfault)
-    friend class test::MasterServiceProcessingKeyDoubleEraseTest;
+    friend class test::MasterServiceTestPeer;
     friend class MasterSnapshotManager;    // Allow access to internal state for
                                            // snapshot
+    friend class ClientOffboardingWorker;
     friend class ha::MasterSnapshotCodec;  // Allow codec to access private
                                            // members
-    friend class ha::MasterSnapshotCodecTest;  // codec round-trip unit test
-    friend class test::MasterServiceHATest;
 
    public:
     using NoFProbeFn =
         std::function<bool(const std::string&, uint32_t, std::string*)>;
     using DurableFinalizeCallback =
         std::function<void(const OpLogEntry& durable_entry)>;
+    using BatchOpLogWriterFactory =
+        std::function<std::unique_ptr<OrderedOpLogWriter>(
+            OrderedOpLogWriterConfig, OrderedOpLogWriter::WriteBatchFn)>;
 
     MasterService();
     MasterService(const MasterServiceConfig& config);
     ~MasterService();
 
-    void SetNoFProbeFnForTesting(NoFProbeFn fn);
-    size_t GetMountedNoFSegmentCountForTesting();
-    bool IsNoFSegmentMountedForTesting(const UUID& segment_id);
-    std::optional<uint32_t> GetNoFHeartbeatFailureCountForTesting(
-        const UUID& segment_id);
+    [[nodiscard]] TieredStorageUsageSnapshot GetStorageUsageSnapshot() const;
     bool IsTenantQuotaEnabled() const;
     std::vector<TenantQuotaSnapshot> ListTenantQuotaSnapshots() const;
     std::optional<TenantQuotaSnapshot> GetTenantQuotaSnapshot(
@@ -150,18 +156,9 @@ class MasterService {
     DeleteTenantQuotaPolicy(const TenantId& tenant_id);
     uint64_t GetTenantQuotaAllocatableCapacityBytes();
 
-    ErrorCode SetBatchOpLogBackendForTesting(
-        std::shared_ptr<HaKvBackend> backend);
-
-    /**
-     * @brief Test-only wrapper around BatchEvict / NoFBatchEvict so that
-     *        unit tests can drive a single eviction cycle synchronously
-     *        without standing up the periodic eviction thread.
-     */
-    void RunBatchEvictForTesting(double evict_ratio_target,
-                                 double evict_ratio_lowerbound);
-    void RunNoFBatchEvictForTesting(double evict_ratio_target,
-                                    double evict_ratio_lowerbound);
+    void SetBatchOpLogTerminalCallback(
+        OrderedOpLogWriter::TerminalCallback callback);
+    void StopBatchOpLogWriter();
 
     /**
      * @brief Mount a memory segment for buffer allocation. This function is
@@ -248,6 +245,18 @@ class MasterService {
     std::vector<tl::expected<bool, ErrorCode>> BatchExistKey(
         const std::vector<std::string>& keys, const TenantId& tenant_id);
 
+    /**
+     * @brief Point-in-time existence check that grants no read lease.
+     *        A `true` result only means the object existed at the time of
+     *        the call; it may be evicted before a subsequent Get.
+     * @return ErrorCode::OK if exists, otherwise return other ErrorCode
+     */
+    auto ProbeKey(const std::string& key, const TenantId& tenant_id)
+        -> tl::expected<bool, ErrorCode>;
+
+    std::vector<tl::expected<bool, ErrorCode>> BatchProbeKey(
+        const std::vector<std::string>& keys, const TenantId& tenant_id);
+
     /**
      * @brief Fetch all keys for a single tenant.
      * @return ErrorCode::OK if exists
@@ -570,15 +579,21 @@ class MasterService {
     tl::expected<CopyStartResponse, ErrorCode> CopyStart(
         const UUID& client_id, const std::string& key,
         const TenantId& tenant_id, const std::string& src_segment,
-        const std::vector<std::string>& tgt_segments);
+        const std::vector<std::string>& tgt_segments,
+        const UUID& dynamic_replication_lease_id = UUID{},
+        uint64_t dynamic_replication_version_epoch = 0);
 
-    tl::expected<void, ErrorCode> CopyEnd(const UUID& client_id,
-                                          const std::string& key,
-                                          const TenantId& tenant_id);
+    tl::expected<void, ErrorCode> CopyEnd(
+        const UUID& client_id, const std::string& key,
+        const TenantId& tenant_id,
+        const UUID& dynamic_replication_lease_id = UUID{},
+        uint64_t dynamic_replication_version_epoch = 0);
 
-    tl::expected<void, ErrorCode> CopyRevoke(const UUID& client_id,
-                                             const std::string& key,
-                                             const TenantId& tenant_id);
+    tl::expected<void, ErrorCode> CopyRevoke(
+        const UUID& client_id, const std::string& key,
+        const TenantId& tenant_id,
+        const UUID& dynamic_replication_lease_id = UUID{},
+        uint64_t dynamic_replication_version_epoch = 0);
 
     /**
      * @brief Start a move operation
@@ -687,6 +702,30 @@ class MasterService {
     auto MountLocalDiskSegment(const UUID& client_id, bool enable_offloading)
         -> tl::expected<void, ErrorCode>;
 
+    /**
+     * @brief Deregisters a client's file storage segment from the master. This
+     * function is idempotent.
+     *
+     * Drops the client's LOCAL_DISK registration and then its LOCAL_DISK
+     * replicas -- the outcome the client-expiry branch of ClientMonitorFunc
+     * reaches after one client_ttl. Exposing it as an operation lets a store
+     * that is shutting down deregister while it can still serve, instead of
+     * leaving the master advertising it as an owner until the TTL elapses.
+     * Object metadata whose last replica was on that disk is erased, exactly
+     * as on expiry; a store that comes back re-adopts its files through the
+     * MountLocalDiskSegment/NotifyOffloadSuccess path, which recreates them.
+     *
+     * The replica sweep targets exactly this owner (see
+     * ClearLocalDiskHandlesOwnedBy), and the deregistration runs under the
+     * exclusive snapshot_mutex_ so no registration admitted against the old
+     * one can land after the sweep: NotifyOffloadSuccess checks the
+     * registration and writes the replica inside one shared-lock section,
+     * which therefore falls entirely before the deregistration (registered,
+     * then swept) or entirely after (refused with SEGMENT_NOT_FOUND).
+     */
+    auto UnmountLocalDiskSegment(const UUID& client_id)
+        -> tl::expected<void, ErrorCode>;
+
     /**
      * @brief Heartbeat call to collect object-level statistics and retrieve the
      * set of non-offloaded objects.
@@ -787,6 +826,13 @@ class MasterService {
         const std::string& key, const TenantId& tenant_id,
         const std::vector<std::string>& targets);
 
+    /**
+     * @brief Submit a dynamic replica action proposal after Master-side
+     * hotness admission.
+     */
+    tl::expected<ReplicaActionLease, ErrorCode> SubmitReplicaActionProposal(
+        const ReplicaActionProposal& proposal);
+
     /**
      * @brief Create a move task to move an object's replica from source segment
      * to target segment
@@ -797,6 +843,11 @@ class MasterService {
                                                  const std::string& source,
                                                  const std::string& target);
 
+    // Admin-only, grow-only DFS capacity management. Existing placements remain
+    // valid.
+    tl::expected<int, ErrorCode> GetDfsShardCount() const;
+    tl::expected<int, ErrorCode> ExpandDfsShards(int shard_count);
+
     /**
      * @brief Create a drain job to gracefully evacuate one or more segments.
      */
@@ -829,10 +880,13 @@ class MasterService {
      * @brief Restore primary state from standby promotion context.
      * Called once at promotion time before serving requests.
      */
-    void RestoreFromStandbySnapshot(
+    tl::expected<void, ErrorCode> RestoreFromStandbySnapshot(
         const std::vector<StandbyObjectEntry>& objects,
         uint64_t initial_oplog_sequence_id,
         const std::vector<StandbySegmentInfo>& segments);
+    tl::expected<void, ErrorCode> RestoreFromBatchOpLogPromotion(
+        BatchOpLogPromotionHandoff handoff,
+        size_t chunk_object_count = kDefaultBatchOpLogPromotionChunkObjects);
 
     /**
      * @brief Query the status of a task
@@ -875,11 +929,31 @@ class MasterService {
     void setHttpMetadataRemoteUrl(const std::string& metadata_connstring);
 
    private:
-    std::unique_ptr<ha::SnapshotCatalogStore> CreateSnapshotCatalogStore();
+    tl::expected<void, ErrorCode> RestoreFromStandbyState(
+        const std::vector<StandbyObjectEntry>* legacy_objects,
+        std::unique_ptr<StandbyMetadataStore> metadata_store,
+        uint64_t initial_oplog_sequence_id,
+        const std::vector<StandbySegmentInfo>& segments,
+        size_t chunk_object_count,
+        std::optional<ReplicaID> expected_max_replica_id);
+
+    std::unique_ptr<ha::SnapshotCatalogStore> CreateSnapshotCatalogStore(
+        const MasterServiceConfig& config);
+
+    // Shared lookup path for ExistKey/ProbeKey (and their batch variants).
+    // When grant_lease is false, the check acquires no read lease and is a
+    // point-in-time existence probe only.
+    auto ExistKeyImpl(const std::string& key, const TenantId& tenant_id,
+                      bool grant_lease) -> tl::expected<bool, ErrorCode>;
+    std::vector<tl::expected<bool, ErrorCode>> BatchExistKeyImpl(
+        const std::vector<std::string>& keys, const TenantId& tenant_id,
+        bool grant_lease);
 
     // Restore master state
     void RestoreState();
     void ResetStateAfterFailedRestoreAttempt();
+    tl::expected<void, SerializationError>
+    RebuildClientLivenessAfterSnapshotRestore();
 
     /**
      * @brief Apply decoded snapshot state to running master service
@@ -908,16 +982,50 @@ class MasterService {
     TenantQuotaEvictionResult EvictTenantMemoryForQuota(
         const TenantId& tenant_id, uint64_t target_bytes);
 
-    // Helper to get a snapshot of alive clients (under client_mutex_ shared
-    // lock)
-    std::unordered_set<UUID, boost::hash<UUID>> getAliveClientsSnapshot() const;
+    // Background pass: evict any tenant that is over its own watermark down to
+    // (watermark - eviction_ratio) of its effective quota. Called from
+    // EvictionThreadFunc, and a no-op unless multi-tenancy and
+    // tenant_eviction_high_watermark_ratio are both enabled.
+    void EvictTenantsOverWatermark();
+
+    std::shared_ptr<ClientLivenessRecord> FindClientRecord(
+        const UUID& client_id) const;
+    // Caller holds the Replica owner's retaining guard.
+    auto AddReplicaForRetainedClient(const UUID& client_id,
+                                     const std::string& key,
+                                     const TenantId& tenant_id,
+                                     Replica& replica)
+        -> tl::expected<bool, ErrorCode>;
+    // Caller must hold client_mutex_.
+    std::unordered_set<UUID, boost::hash<UUID>> GetRetainingClientIdsLocked()
+        const;
     void UpdateClientHostId(const UUID& client_id, const std::string& host_id);
     std::string GetClientHostId(const UUID& client_id) const;
 
-    // Clear invalid handles in all shards
     void ClearInvalidHandles();
+    // Caller owns snapshot_mutex_ (shared) while metadata is swept.
     void ClearInvalidHandles(
-        const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients);
+        const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients);
+    // Clear completed LOCAL_DISK replicas owned by exactly this client, in
+    // all shards. Owner-targeted on purpose: a liveness-complement sweep
+    // classifies by absence from a point-in-time set, so an owner that
+    // mounts and registers between taking that set and the sweep reaching
+    // its shard would be swept as stale. A predicate on the owner id cannot
+    // misclassify a concurrent mount, whatever the interleaving.
+    void ClearLocalDiskHandlesOwnedBy(const UUID& owner);
+    // Shard walk shared by the two sweeps above; removes completed replicas
+    // matching is_stale, erasing a key when no valid replica remains. Each
+    // shard is first scanned under its shared lock to pick the keys that
+    // match, and only those are cleaned, in bounded batches under the write
+    // lock: a mass client expiry marks handles stale table-wide, and walking
+    // a whole shard while holding it exclusively blocked every RPC for that
+    // shard until the sweep moved on.
+    tl::expected<void, ErrorCode> ClearStaleHandles(
+        const std::function<bool(const Replica&)>& is_stale);
+    bool ProcessClientOffboardingJob(ClientOffboardingJob& job);
+    bool ShouldSkipSnapshotForClientOffboarding() const {
+        return client_offboarding_worker_.HasPending();
+    }
 
     std::string FormatTimestamp(
         const std::chrono::system_clock::time_point& tp);
@@ -925,6 +1033,7 @@ class MasterService {
     // And also we can add some task ttl mechanism in the future
     void TaskCleanupThreadFunc();
     void JobDispatchThreadFunc();
+    void DynamicReplicationAdmissionThreadFunc();
 
     // Internal data structures
     struct ObjectIdentity {
@@ -932,410 +1041,32 @@ class MasterService {
         std::string user_key;
     };
 
-    struct ObjectMetadata {
-        // RAII-style metric management
-        ~ObjectMetadata() {
-            MasterMetricManager::instance().dec_key_count(1);
-            if (soft_pin_timeout) {
-                MasterMetricManager::instance().dec_soft_pin_key_count(1);
-            }
-        }
-
-        ObjectMetadata() = delete;
-
-        ObjectMetadata(
-            const UUID& client_id_,
-            const std::chrono::system_clock::time_point put_start_time_,
-            size_t value_length, std::vector<Replica>&& reps,
-            bool enable_soft_pin, bool enable_hard_pin = false,
-            ObjectDataType data_type_ = ObjectDataType::UNKNOWN,
-            std::string group_id_ = "", TenantId tenant_id_ = TenantId(),
-            std::string user_key_ = {})
-            : client_id(client_id_),
-              put_start_time(put_start_time_),
-              size(value_length),
-              data_type(data_type_),
-              group_id(std::move(group_id_)),
-              tenant_id(std::move(tenant_id_)),
-              user_key(std::move(user_key_)),
-              lease_timeout(),
-              soft_pin_timeout(std::nullopt),
-              hard_pinned(enable_hard_pin),
-              replicas_(std::move(reps)) {
-            MasterMetricManager::instance().inc_key_count(1);
-            if (enable_soft_pin) {
-                soft_pin_timeout.emplace();
-                MasterMetricManager::instance().inc_soft_pin_key_count(1);
-            }
-            MasterMetricManager::instance().observe_value_size(value_length);
-        }
-
-        ObjectMetadata(const ObjectMetadata&) = delete;
-        ObjectMetadata& operator=(const ObjectMetadata&) = delete;
-        ObjectMetadata(ObjectMetadata&&) = delete;
-        ObjectMetadata& operator=(ObjectMetadata&&) = delete;
-
-        // Updated by UpsertStart (Case B) to reflect the new writer.
-        UUID client_id;
-        // Updated by UpsertStart (Case B) to reset the discard timeout.
-        std::chrono::system_clock::time_point put_start_time;
-        const size_t size;
-        std::optional<uint64_t> object_checksum;
-        const ObjectDataType data_type{ObjectDataType::UNKNOWN};
-        const std::string group_id;
-        const TenantId tenant_id;
-        const std::string user_key;
-
-        mutable SpinLock lock;
-        // Default constructor, creates a time_point representing
-        // the Clock's epoch (i.e., time_since_epoch() is zero).
-        mutable std::chrono::system_clock::time_point lease_timeout
-            GUARDED_BY(lock);  // hard lease
-        mutable std::optional<std::chrono::system_clock::time_point>
-            soft_pin_timeout GUARDED_BY(lock);  // optional soft pin, only
-                                                // set for vip objects
-        const bool hard_pinned{false};          // immutable, set at creation
-        bool memory_cache_total_accounted{false};
-        bool disk_cache_total_accounted{false};
-        uint64_t reserved_quota_charge_bytes{0};
-        uint64_t committed_quota_charge_bytes{0};
-        uint64_t pending_replaced_quota_charge_bytes{0};
-
-        void AddReplicas(std::vector<Replica>&& replicas) {
-            replicas_.insert(replicas_.end(),
-                             std::move_iterator(replicas.begin()),
-                             std::move_iterator(replicas.end()));
-        }
-
-        std::vector<Replica> PopReplicas(
-            const std::function<bool(const Replica&)>& pred_fn) {
-            auto partition_point =
-                std::partition(replicas_.begin(), replicas_.end(),
-                               [pred_fn](const Replica& replica) {
-                                   return !pred_fn(replica);
-                               });
-
-            std::vector<Replica> popped_replicas;
-            if (partition_point != replicas_.end()) {
-                popped_replicas.reserve(
-                    std::distance(partition_point, replicas_.end()));
-                std::move(partition_point, replicas_.end(),
-                          std::back_inserter(popped_replicas));
-                replicas_.erase(partition_point, replicas_.end());
-            }
-
-            return popped_replicas;
-        }
-
-        std::vector<Replica> PopReplicas() { return std::move(replicas_); }
-
-        size_t EraseReplicas(
-            const std::function<bool(const Replica&)>& pred_fn) {
-            auto erased_replicas = PopReplicas(pred_fn);
-            return erased_replicas.size();
-        }
-
-        size_t EraseReplicas() {
-            auto erased_replicas = PopReplicas();
-            return erased_replicas.size();
-        }
-
-        size_t VisitReplicas(const std::function<bool(const Replica&)>& pred_fn,
-                             const std::function<void(Replica&)>& visit_fn) {
-            size_t num_visited = 0;
-
-            for (auto& replica : replicas_) {
-                if (pred_fn(replica)) {
-                    visit_fn(replica);
-                    num_visited++;
-                }
-            }
-
-            return num_visited;
-        }
-
-        size_t VisitReplicas(
-            const std::function<bool(const Replica&)>& pred_fn,
-            const std::function<void(const Replica&)>& visit_fn) const {
-            size_t num_visited = 0;
-
-            for (auto& replica : replicas_) {
-                if (pred_fn(replica)) {
-                    visit_fn(replica);
-                    num_visited++;
-                }
-            }
-
-            return num_visited;
-        }
-
-        bool HasReplica(
-            const std::function<bool(const Replica&)>& pred_fn) const {
-            return std::any_of(replicas_.begin(), replicas_.end(), pred_fn);
-        }
-
-        bool AllReplicas(
-            const std::function<bool(const Replica&)>& pred_fn) const {
-            return std::all_of(replicas_.begin(), replicas_.end(), pred_fn);
-        }
-
-        size_t CountReplicas(
-            const std::function<bool(const Replica&)>& pred_fn) const {
-            return std::count_if(replicas_.begin(), replicas_.end(), pred_fn);
-        }
-
-        size_t CountReplicas() const { return replicas_.size(); }
-
-        const std::vector<Replica>& GetAllReplicas() const { return replicas_; }
-
-        std::optional<ReplicaStatus> HasDiffRepStatus(
-            ReplicaStatus status) const {
-            for (const auto& replica : replicas_) {
-                if (replica.status() != status) {
-                    return replica.status();
-                }
-            }
-            return {};
-        }
-
-        Replica* GetFirstReplica(
-            const std::function<bool(const Replica&)>& pred_fn) {
-            const auto it =
-                std::find_if(replicas_.begin(), replicas_.end(), pred_fn);
-            return it != replicas_.end() ? &(*it) : nullptr;
-        }
-
-        Replica* GetReplicaByID(const ReplicaID& id) {
-            return GetFirstReplica(
-                [&id](const Replica& replica) { return replica.id() == id; });
-        }
-
-        bool EraseReplicaByID(const ReplicaID& id) {
-            auto num_erased = EraseReplicas(
-                [&id](const Replica& replica) { return replica.id() == id; });
-            return num_erased > 0;
-        }
-
-        size_t EraseReplica(ReplicaType replica_type) {
-            return EraseReplicas([replica_type](const Replica& replica) {
-                if (replica_type == ReplicaType::ALL) {
-                    return replica.is_memory_replica() ||
-                           replica.is_nof_replica();
-                }
-                return replica.type() == replica_type;
-            });
-        }
-
-        bool HasMemReplica() const {
-            return HasReplica(&Replica::fn_is_memory_replica);
-        }
-
-        bool HasNoFReplica() const {
-            return HasReplica(&Replica::fn_is_nof_replica);
-        }
-
-        size_t GetMemReplicaCount() const {
-            return CountReplicas(&Replica::fn_is_memory_replica);
-        }
-
-        size_t GetNoFReplicaCount() const {
-            return CountReplicas(&Replica::fn_is_nof_replica);
-        }
-
-        Replica* GetReplicaBySegmentName(const std::string& segment_name) {
-            return GetFirstReplica([&segment_name](const Replica& replica) {
-                auto names = replica.get_segment_names();
-                for (auto& name_opt : names) {
-                    if (name_opt == segment_name) {
-                        return true;
-                    }
-                }
-                return false;
-            });
-        }
-
-        // Grant a lease with timeout as now() + ttl, only update if the new
-        // timeout is larger
-        void GrantLease(const uint64_t ttl, const uint64_t soft_ttl) const {
-            SpinLocker locker(&lock);
-            std::chrono::system_clock::time_point now =
-                std::chrono::system_clock::now();
-            lease_timeout =
-                std::max(lease_timeout, now + std::chrono::milliseconds(ttl));
-            if (soft_pin_timeout) {
-                soft_pin_timeout =
-                    std::max(*soft_pin_timeout,
-                             now + std::chrono::milliseconds(soft_ttl));
-            }
-        }
-
-        bool NeedsLeaseRefresh(const uint64_t ttl,
-                               const uint64_t soft_ttl) const {
-            SpinLocker locker(&lock);
-            const auto now = std::chrono::system_clock::now();
-            if (lease_timeout <= now + std::chrono::milliseconds(ttl / 2)) {
-                return true;
-            }
-            return soft_pin_timeout &&
-                   *soft_pin_timeout <=
-                       now + std::chrono::milliseconds(soft_ttl / 2);
-        }
-
-        // Check if the lease has expired
-        bool IsLeaseExpired() const {
-            SpinLocker locker(&lock);
-            return std::chrono::system_clock::now() >= lease_timeout;
-        }
-
-        // Check if the lease has expired
-        bool IsLeaseExpired(std::chrono::system_clock::time_point& now) const {
-            SpinLocker locker(&lock);
-            return now >= lease_timeout;
-        }
-
-        // Check if is in soft pin status
-        bool IsSoftPinned() const {
-            SpinLocker locker(&lock);
-            return soft_pin_timeout &&
-                   std::chrono::system_clock::now() < *soft_pin_timeout;
-        }
-
-        // Check if is in soft pin status
-        bool IsSoftPinned(std::chrono::system_clock::time_point& now) const {
-            SpinLocker locker(&lock);
-            return soft_pin_timeout && now < *soft_pin_timeout;
-        }
-
-        bool IsHardPinned() const { return hard_pinned; }
-
-        bool IsGrouped() const { return !group_id.empty(); }
-
-        // Check if the metadata is valid
-        // Valid means it has at least one valid replica and size is greater
-        // than 0
-        bool IsValid() const {
-            return size > 0 && HasReplica([](const Replica& replica) {
-                       return !replica.is_memory_replica() ||
-                              !replica.has_invalid_mem_handle();
-                   });
-        }
-
-        std::vector<std::string> GetReplicaSegmentNames() const {
-            std::vector<std::string> segment_names;
-            for (const auto& replica : replicas_) {
-                const auto& segment_name_options = replica.get_segment_names();
-                for (const auto& segment_name_opt : segment_name_options) {
-                    if (segment_name_opt.has_value()) {
-                        segment_names.push_back(segment_name_opt.value());
-                    }
-                }
-            }
-            return segment_names;
-        }
-
-       private:
-        // Use the accessors to visit and modify the replicas.
-        std::vector<Replica> replicas_;
-    };
-
-    struct ReplicationTask {
-        UUID client_id;
-        std::chrono::system_clock::time_point start_time;
-        enum class Type {
-            COPY,
-            MOVE,
-        } type;
-        ReplicaID source_id;
-        std::vector<ReplicaID> replica_ids;
-        uint64_t reserved_quota_charge_bytes{0};
-    };
-
-    struct OffloadingTask {
-        ReplicaID source_id;
-        std::chrono::system_clock::time_point start_time;
-    };
-
-    // Tracks an in-flight LOCAL_DISK -> MEMORY copy. The source
-    // LOCAL_DISK replica is refcnt-pinned for the duration of the task
-    // so it cannot be evicted.
-    //
-    // alloc_id pins down which staged PROCESSING MEMORY replica
-    enum class PromotionQueueResult {
-        kQueued,
-        kDisabled,
-        kFrequencyRejected,
-        kWatermarkRejected,
-        kQueueCapRejected,
-        kAlreadyInFlight,
-        kMemoryReplicaPresent,
-        kNoLocalDiskSource,
-        kNotFound,
-        kPushFailed,
-    };
-
-    enum class PromotionCandidateReason {
-        kWatermark,
-        kQueueCap,
-        kPushFailed,
-    };
-
-    struct PromotionCandidate {
-        uint8_t sketch_score{0};
-        std::chrono::steady_clock::time_point first_seen;
-        std::chrono::steady_clock::time_point last_seen;
-        std::chrono::steady_clock::time_point retry_after;
-        PromotionCandidateReason last_reason{
-            PromotionCandidateReason::kQueueCap};
-        ErrorCode last_error{ErrorCode::OK};
-        uint32_t retry_count{0};
-    };
-
-    // NotifyPromotionSuccess should commit, so a concurrent Put on the
-    // same key cannot be confused with ours. 0 until
-    // PromotionAllocStart records the new replica.
-    //
-    // start_time is the reaper deadline anchor. Set at task admission
-    // and reset at PromotionAllocStart so each phase (queue-wait and
-    // active-transfer) gets its own full put_start_release_timeout_sec_
-    // window. Without the reset a backlogged task could enter active
-    // transfer with little TTL left, and the reaper could free the
-    // staged replica via EraseReplicaByID mid-RDMA-write.
-    //
-    // holder_id is the client owning the source LOCAL_DISK segment and
-    // the only one authorized to commit (NotifyPromotionSuccess) or
-    // abort (NotifyPromotionFailure) the task. Without it, any client
-    // knowing the key could flip the staged PROCESSING replica to
-    // COMPLETE before the holder's RDMA write landed, exposing torn
-    // data to readers.
-    struct PromotionTask {
-        ReplicaID source_id;    // the LOCAL_DISK replica being promoted
-        ReplicaID alloc_id{0};  // the new MEMORY replica staged by AllocStart
-        uint64_t object_size;
-        uint64_t reserved_quota_charge_bytes{0};
-        std::chrono::system_clock::time_point start_time;
-        UUID holder_id;  // owner of source LOCAL_DISK; only Notifier allowed
-    };
-
     static constexpr size_t kNumShards = 1024;  // Number of metadata shards
 
     struct TenantState {
+        TenantQuotaHandle quota_account{nullptr};
         std::unordered_map<std::string, ObjectMetadata> metadata;
         std::unordered_set<std::string> processing_keys;
-        std::unordered_map<std::string, const ReplicationTask>
-            replication_tasks;
+        std::unordered_map<std::string, ReplicationTask> replication_tasks;
         std::unordered_map<std::string, const OffloadingTask> offloading_tasks;
         std::unordered_map<std::string, PromotionTask> promotion_tasks;
         std::unordered_map<std::string, PromotionCandidate>
             promotion_candidates;
 
-        std::unordered_map<std::string, std::unordered_set<std::string>>
-            group_members;  // group_id → set of keys
+        std::unordered_map<std::string, DynamicReplicaPending>
+            dynamic_replication_pending;
+        std::unordered_map<UUID, ReplicaActionLease, boost::hash<UUID>>
+            dynamic_replication_leases;
+        std::unordered_map<std::string, std::chrono::steady_clock::time_point>
+            dynamic_replication_cooldowns;
 
         bool Empty() const {
             return metadata.empty() && processing_keys.empty() &&
                    replication_tasks.empty() && offloading_tasks.empty() &&
                    promotion_tasks.empty() && promotion_candidates.empty() &&
-                   group_members.empty();
+                   dynamic_replication_pending.empty() &&
+                   dynamic_replication_leases.empty() &&
+                   dynamic_replication_cooldowns.empty();
         }
     };
 
@@ -1351,6 +1082,70 @@ class MasterService {
     };
     std::array<MetadataShard, kNumShards> metadata_shards_;
 
+    // Group domain: all groups in one shard. Routing stays hash(tenant, key);
+    // group state is just member keys + one shared lease, consulted at eviction
+    // (all-or-none) — the read path never touches this table.
+    struct GroupState {
+        std::unordered_set<std::string> member_keys;
+        std::shared_ptr<Lease> lease;
+
+        bool Empty() const { return member_keys.empty(); }
+    };
+
+    // Small and low-frequency (put/register + eviction), so one lock is enough.
+    struct GroupDomain {
+        mutable SharedMutex mutex;
+        // key: tenant_id.MakeScopedKey(group_id)
+        std::unordered_map<std::string, GroupState> groups GUARDED_BY(mutex);
+    };
+    GroupDomain group_domain_;
+
+    class SoftPinDeadlineIndex {
+        friend class test::MasterServiceTestPeer;
+
+       public:
+        using TimePoint = std::chrono::system_clock::time_point;
+
+        struct Entry {
+            TimePoint deadline;
+            size_t shard_idx;
+            std::string scoped_key;
+        };
+
+        void Upsert(std::string scoped_key, size_t shard_idx,
+                    const TimePoint& deadline);
+        void Remove(const std::string& scoped_key);
+        void RemoveIfMatches(const std::string& scoped_key, size_t shard_idx,
+                             const TimePoint& deadline);
+        std::vector<Entry> PopExpired(const TimePoint& now);
+        void Clear();
+
+       private:
+        struct Registration {
+            TimePoint deadline;
+            size_t shard_idx;
+        };
+
+        struct EarlierDeadline {
+            bool operator()(const Entry& lhs, const Entry& rhs) const {
+                return lhs.deadline > rhs.deadline;
+            }
+        };
+
+        static constexpr size_t kMinCompactionThreshold = 4096;
+        static constexpr size_t kCompactionRatio = 2;
+
+        void MaybeCompactLocked() REQUIRES(mutex_);
+
+        mutable std::mutex mutex_;
+        std::priority_queue<Entry, std::vector<Entry>, EarlierDeadline> heap_
+            GUARDED_BY(mutex_);
+        std::unordered_map<std::string, Registration> registrations_
+            GUARDED_BY(mutex_);
+    };
+
+    mutable SoftPinDeadlineIndex soft_pin_deadline_index_;
+
     static bool HasCompletedMemoryCacheReplica(const ObjectMetadata& metadata);
     static bool HasCompletedDiskCacheReplica(const ObjectMetadata& metadata);
     static void SyncCacheTotalAccounting(ObjectMetadata& metadata);
@@ -1361,17 +1156,13 @@ class MasterService {
         const std::function<bool(const Replica&)>& pred_fn);
     std::vector<Replica> PopReplicasWithCacheTotalAccounting(
         ObjectMetadata& metadata);
+    size_t RecordDynamicReplicaRemoval(
+        ObjectMetadata& metadata, const std::vector<ReplicaID>& replica_ids);
     size_t EraseReplicasWithCacheTotalAccounting(
         ObjectMetadata& metadata,
         const std::function<bool(const Replica&)>& pred_fn,
         std::vector<ReplicaID>* erased_replica_ids = nullptr);
 
-    std::unordered_map<std::string, std::string> object_group_ids_
-        GUARDED_BY(group_routing_mutex_);
-    mutable std::unordered_set<std::string> groups_needing_lease_refresh_
-        GUARDED_BY(group_routing_mutex_);
-    mutable std::shared_mutex group_routing_mutex_;
-
     static constexpr size_t kObjectOperationLockStripes = 4096;
 
     struct ObjectOperationLock {
@@ -1449,6 +1240,41 @@ class MasterService {
         SharedMutexLocker lock_;
     };
 
+    // For accessing the group domain with read-write permission
+    class GroupDomainAccessorRW {
+       public:
+        explicit GroupDomainAccessorRW(MasterService* master_service)
+            : shard_(master_service->group_domain_), lock_(&shard_.mutex) {}
+
+        GroupDomain* operator->() { return &shard_; }
+
+        const GroupDomain* operator->() const { return &shard_; }
+
+        GroupDomain& get() { return shard_; }
+
+        const GroupDomain& get() const { return shard_; }
+
+       private:
+        GroupDomain& shard_;
+        SharedMutexLocker lock_;
+    };
+
+    // For accessing the group domain with read-only permission
+    class GroupDomainAccessorRO {
+       public:
+        explicit GroupDomainAccessorRO(const MasterService* master_service)
+            : shard_(master_service->group_domain_),
+              lock_(&shard_.mutex, shared_lock) {}
+
+        const GroupDomain* operator->() const { return &shard_; }
+
+        const GroupDomain& get() const { return shard_; }
+
+       private:
+        const GroupDomain& shard_;
+        SharedMutexLocker lock_;
+    };
+
     static ObjectIdentity MakeObjectIdentity(const std::string& user_key,
                                              TenantId tenant_id) {
         return {std::move(tenant_id), user_key};
@@ -1479,17 +1305,62 @@ class MasterService {
         return std::hash<std::string>{}(key) % kNumShards;
     }
 
-    size_t getMetadataShardIndex(const TenantId& tenant_id,
-                                 const std::string& key) const;
-    std::optional<std::string> GetGroupRoute(const TenantId& tenant_id,
-                                             const std::string& key) const;
-    void RegisterGroupMember(TenantState& tenant_state,
-                             const TenantId& tenant_id, const std::string& key,
-                             const std::string& group_id);
-    void UnregisterGroupMember(TenantState& tenant_state,
-                               const TenantId& tenant_id,
+    // Registers a member key under a group and returns the group's shared
+    // Lease (creating the group/lease on first member). Callers wire the
+    // returned lease into the object metadata so the read path can extend the
+    // group TTL without touching this table. Returns nullptr for empty
+    // group_id.
+    std::shared_ptr<Lease> RegisterGroupMember(const TenantId& tenant_id,
+                                               const std::string& key,
+                                               const std::string& group_id);
+    void UnregisterGroupMember(const TenantId& tenant_id,
                                const std::string& key,
                                const std::string& group_id);
+    // Reads the member keys registered for `group_id`; empty if unregistered.
+    std::vector<std::string> GetGroupMemberKeys(
+        const TenantId& tenant_id, const std::string& group_id) const;
+
+    // A single group member's eviction outcome, fed back by the
+    // EvictGroupOrObject callback.
+    struct EvictMemberOutcome {
+        uint64_t freed_bytes{0};
+        long evicted_objects{0};
+        bool stop_scan{false};
+        ErrorCode error{ErrorCode::OK};
+    };
+    // Aggregated outcome of a group eviction.
+    struct GroupEvictionResult {
+        uint64_t freed_bytes{0};
+        long evicted_objects{0};
+        bool stop_scan{false};
+        ErrorCode error{ErrorCode::OK};
+    };
+
+    // Evicts every member of `group_id` across its metadata shards. MUST be
+    // called WITHOUT holding any metadata shard lock: the caller releases the
+    // trigger shard lock first, so a caller-held trigger lock is never held
+    // while other shard locks are acquired (that ordering is the AB/BA
+    // cross-shard deadlock this function exists to remove). It acquires each
+    // member shard lock itself in canonical ascending shard order, so any two
+    // concurrent group evictions that touch the same shards acquire them in the
+    // same global order and cannot deadlock.
+    //
+    // Each member is re-looked-up and re-validated under its own lock (lease,
+    // hard/soft pin, evictable replica — all against `now`) because state may
+    // have changed since the caller's snapshot; members that no longer qualify
+    // are skipped without invoking the callback. `evict_one_member` therefore
+    // performs only the path-specific member eviction (oplog persist, offload,
+    // quota charge, publish) and may erase members other than `key`; the
+    // trigger `key` itself is left to the caller. Each call returns that
+    // member's contribution. Returns the aggregated outcome.
+    GroupEvictionResult EvictGroupOrObject(
+        const TenantId& tenant_id, const std::string& key,
+        const std::string& group_id, bool allow_soft_pinned,
+        std::chrono::system_clock::time_point now,
+        const std::function<EvictMemberOutcome(
+            const std::string&, ObjectMetadata&, TenantState&,
+            MetadataShardAccessorRW&)>& evict_one_member);
+
     std::unordered_map<std::string, ObjectMetadata>::iterator EraseMetadata(
         TenantState& tenant_state,
         std::unordered_map<std::string, ObjectMetadata>::iterator it,
@@ -1504,21 +1375,18 @@ class MasterService {
         TenantState& tenant_state,
         std::unordered_map<std::string, ObjectMetadata>::iterator it,
         const TenantId& tenant_id, QuotaEraseMode quota_mode);
+    tl::expected<void, ErrorCode> SettlePrimaryWriteQuotaIfReady(
+        TenantState& tenant_state, ObjectMetadata& metadata);
     uint64_t CompletedMemoryQuotaCharge(const ObjectMetadata& metadata) const;
     uint64_t RequestedMemoryQuotaCharge(uint64_t value_length,
                                         const ReplicateConfig& config) const;
-    bool ShouldProtectZeroChargeMetadataCreate(
-        uint64_t requested_quota_charge) const;
-    tl::expected<void, ErrorCode> ReserveTenantQuota(const TenantId& tenant_id,
-                                                     uint64_t bytes);
-    void CommitTenantQuota(const TenantId& tenant_id, uint64_t bytes);
-    void AbortTenantQuota(const TenantId& tenant_id, uint64_t bytes);
-    void ReleaseTenantQuota(const TenantId& tenant_id, uint64_t bytes);
-    void ReleaseTenantQuotaPartial(const TenantId& tenant_id, uint64_t bytes);
-    void CommitAdditionalTenantQuota(const TenantId& tenant_id, uint64_t bytes);
-    void IncrementTenantMetadataObjectCount(const TenantId& tenant_id);
-    void DecrementTenantMetadataObjectCount(const TenantId& tenant_id);
-    void ReleaseCommittedQuotaCharge(ObjectMetadata& metadata, uint64_t bytes);
+    TenantState& GetOrCreateTenantState(MetadataShard& shard,
+                                        const TenantId& tenant_id);
+    TenantQuotaHandle GetBoundTenantQuotaHandle(
+        const TenantState& tenant_state) const;
+    tl::expected<void, ErrorCode> ChargeTenantQuota(TenantQuotaHandle account,
+                                                    uint64_t bytes);
+    void ReleaseTenantQuota(TenantQuotaHandle account, uint64_t bytes);
     void RecomputeTenantEffectiveQuotas();
     void RebuildTenantQuotaUsageFromMetadata();
     void LoadTenantQuotaPoliciesFromStoreOrThrow();
@@ -1528,10 +1396,12 @@ class MasterService {
         TenantState& tenant_state,
         std::unordered_map<std::string, ObjectMetadata>::iterator it,
         const TenantId& tenant_id, QuotaEraseMode quota_mode,
-        MetadataShardAccessorRW* shard);
+        MetadataShardAccessorRW* shard,
+        const std::vector<std::string>& previous_media_hint = {});
     void FinalizeRemovedReplicasAfterDurable(
         const OpLogEntry& durable_entry,
-        const std::vector<ReplicaID>& replica_ids, QuotaEraseMode quota_mode);
+        const std::vector<ReplicaID>& replica_ids, QuotaEraseMode quota_mode,
+        const std::vector<std::string>& previous_media_hint = {});
     void FinalizeMetadataEraseAfterDurable(const OpLogEntry& durable_entry,
                                            QuotaEraseMode quota_mode);
     void FinalizeExpiredProcessingReplicasAfterDurable(
@@ -1540,6 +1410,8 @@ class MasterService {
     void FinalizeExpiredReplicationTaskAfterDurable(
         const OpLogEntry& durable_entry, ReplicaID source_id,
         const std::vector<ReplicaID>& target_ids,
+        const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch,
         const std::chrono::system_clock::time_point& ttl);
     struct StaleHandleCleanupPlan {
         std::vector<ReplicaID> removed_ids;
@@ -1548,31 +1420,91 @@ class MasterService {
     };
     StaleHandleCleanupPlan BuildStaleHandleCleanupPlan(
         const ObjectMetadata& metadata,
-        const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients) const;
+        const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients)
+        const;
+    StaleHandleCleanupPlan BuildStaleHandleCleanupPlan(
+        const ObjectMetadata& metadata,
+        const std::function<bool(const Replica&)>& is_stale) const;
     tl::expected<void, ErrorCode> PersistStaleHandleCleanupForHA(
         const std::string& why, const TenantId& tenant_id,
         const std::string& key, ObjectMetadata& metadata,
         const StaleHandleCleanupPlan& plan);
-    void RebuildGroupRoutingIndex();
-    void GrantLeaseForGroup(const TenantState& tenant_state,
-                            const std::string& key,
-                            const ObjectMetadata& metadata) const;
+    void RebuildGroupState();
+    // Post-restore migration: re-route every object to its hash(tenant, key)
+    // shard, fixing snapshots that placed grouped objects on hash(group_id)
+    // shards. No-op for correctly-routed snapshots.
+    void ReRouteRestoredObjectsByKey();
+    static void ApplySoftPinMetricDelta(int metric_delta);
+    size_t GetMetadataShardIndex(const ObjectMetadata& metadata) const;
+    void ApplySoftPinEvaluation(
+        const ObjectMetadata& metadata,
+        const ObjectMetadata::SoftPinEvaluation& result) const;
+    bool IsSoftPinActive(
+        const ObjectMetadata& metadata,
+        const std::chrono::system_clock::time_point& now) const;
+    void CleanupExpiredSoftPins(
+        const std::chrono::system_clock::time_point& now);
+    auto ResolveSoftPinRequest(const ReplicateConfig& config) const
+        -> tl::expected<ResolvedSoftPinRequest, ErrorCode>;
 
     // Helper to clean up stale handles pointing to unmounted segments
-    // or local_disk replicas whose owner client is no longer alive.
+    // or local_disk replicas whose owner client no longer retains resources.
     bool CleanupStaleHandles(
+        const std::string& key, const TenantId& tenant_id,
         TenantState& tenant_state, ObjectMetadata& metadata,
-        const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients,
+        const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients,
+        MetadataShardAccessorRW* shard = nullptr);
+    // Predicate form, so the owner-targeted LOCAL_DISK sweep can reuse the
+    // accounting (quota release, promotion-task cancellation, disk-replica
+    // shard bookkeeping) instead of duplicating it.
+    bool CleanupStaleHandles(
+        const std::string& key, const TenantId& tenant_id,
+        TenantState& tenant_state, ObjectMetadata& metadata,
+        const std::function<bool(const Replica&)>& is_stale,
         MetadataShardAccessorRW* shard = nullptr);
 
+    // True when client_id currently has a LOCAL_DISK registration.
+    // Momentarily takes the LocalSsdManager registry lock, so callers must not
+    // hold it; call before taking a metadata shard lock. Callers that need the
+    // answer to stay true across a later metadata write must hold
+    // snapshot_mutex_ (shared) across both -- UnmountLocalDiskSegment
+    // deregisters the client under the exclusive lock, so the check and the
+    // write cannot straddle a deregistration.
+    bool HasMountedLocalDiskSegment(const UUID& client_id);
+
+    // Allocate the physical replicas without changing object metadata.  This
+    // is used by leased upserts to prove that replacement storage is available
+    // before the old metadata is removed.
+    auto AllocateReplicas(const std::string& key, uint64_t value_length,
+                          const ReplicateConfig& config,
+                          const std::string& writer_host_id,
+                          bool* dfs_allocation_failed = nullptr)
+        -> tl::expected<std::vector<Replica>, ErrorCode>;
+
+    auto InsertMetadata(MetadataShardAccessorRW& shard, const UUID& client_id,
+                        const std::string& key, uint64_t value_length,
+                        const ReplicateConfig& config,
+                        const std::string& group_id, const TenantId& tenant_id,
+                        const std::chrono::system_clock::time_point& now,
+                        const ResolvedSoftPinRequest& soft_pin_request,
+                        std::vector<Replica>&& replicas,
+                        uint64_t pending_quota_charge,
+                        std::optional<std::chrono::system_clock::time_point>
+                            committed_soft_pin_timeout = std::nullopt)
+        -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode>;
+
     // Helper: allocate replicas, create ObjectMetadata, insert into shard,
     // and return descriptor list.  Shared by PutStart and UpsertStart.
     auto AllocateAndInsertMetadata(
         MetadataShardAccessorRW& shard, const UUID& client_id,
         const std::string& key, uint64_t value_length,
-        const ReplicateConfig& config, const std::string& group_id,
-        const TenantId& tenant_id,
-        const std::chrono::system_clock::time_point& now)
+        const ReplicateConfig& config, const std::string& writer_host_id,
+        const std::string& group_id, const TenantId& tenant_id,
+        const std::chrono::system_clock::time_point& now,
+        const ResolvedSoftPinRequest& soft_pin_request,
+        std::optional<std::chrono::system_clock::time_point>
+            committed_soft_pin_timeout = std::nullopt,
+        bool* dfs_allocation_failed = nullptr)
         -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode>;
 
     /**
@@ -1581,7 +1513,14 @@ class MasterService {
     void DiscardExpiredProcessingReplicas(
         MetadataShardAccessorRW& shard,
         const std::chrono::system_clock::time_point& now);
-
+    void FreeDfsReplicas(const std::string& key,
+                         const std::vector<Replica>& replicas);
+    void RunDfsEviction();
+    void RunShardDfsEviction();
+    void RunBucketDfsEviction();
+    bool RunBucketDfsEvictionInternal(bool force_one);
+    bool TryRecoverDfsSpaceAfterAllocationFailure();
+    void InitDfsAllocatorFromEnvironment(const MasterServiceConfig& config);
     /**
      * @brief Helper to release space of expired discarded replicas.
      * @return Number of released objects that have memory replicas
@@ -1598,8 +1537,20 @@ class MasterService {
     bool ProbeNoFSegment(const std::string& te_endpoint,
                          std::string* error_reason);
 
+    // Pushes an offload mirror for `replica` onto its host client's LocalSSD
+    // mailbox. When `mirror_clients` is non-null, the destination client is
+    // appended to it on success.
     tl::expected<void, ErrorCode> PushOffloadingQueue(
-        const ObjectIdentity& object_id, Replica& replica);
+        const ObjectIdentity& object_id, Replica& replica,
+        std::vector<UUID>* mirror_clients = nullptr);
+
+    // Cancels the offload task on `object_id`, releasing the source refcnt
+    // and dropping the task marker along with its mirrors. Returns false
+    // without touching the task if any mirror has already been drained by a
+    // store worker.
+    bool CancelQueuedOffloadTask(TenantState& tenant_state,
+                                 ObjectMetadata& metadata,
+                                 const ObjectIdentity& object_id);
 
     struct GracefulUnmountDeadlineRecord {
         UUID segment_id;
@@ -1608,10 +1559,12 @@ class MasterService {
 
     DeadlineScheduler<GracefulUnmountDeadlineRecord>
         graceful_unmount_scheduler_;
+    BackgroundWorker replica_cleanup_worker_;
+    const bool enable_async_segment_cleanup_;
 
     /**
      * @brief Mirror of PushOffloadingQueue for promotion-on-hit. Inserts an
-     * entry into the holder client's LocalDiskSegment::promotion_objects map.
+     * task into the holder client's LocalSSD mailbox.
      * Caller is responsible for refcnt-pinning the source replica and
      * recording the task in the shard's promotion_tasks map.
      */
@@ -1622,8 +1575,8 @@ class MasterService {
      * @brief Helper invoked from GetReplicaList when an only-LOCAL_DISK key is
      * observed. Applies the gating chain (frequency / watermark / dedup /
      * cap), refcnt-pins the source LOCAL_DISK replica, records a
-     * PromotionTask, and pushes onto the holder client's promotion_objects
-     * map. Acquires its own RW shard accessor; safe to call after
+     * PromotionTask, and pushes onto the holder client's LocalSSD mailbox.
+     * Acquires its own RW shard accessor; safe to call after
      * GetReplicaList's RO accessor has been released.
      */
     PromotionQueueResult TryPushPromotionQueue(const ObjectIdentity& object_id,
@@ -1631,7 +1584,8 @@ class MasterService {
     void RecordOrUpdateCandidate(TenantState& tenant_state,
                                  const std::string& key, uint8_t sketch_score,
                                  PromotionCandidateReason reason,
-                                 ErrorCode last_error);
+                                 ErrorCode last_error,
+                                 uint32_t execution_failures = 0);
     void EraseCandidate(TenantState& tenant_state, const std::string& key);
     void EraseCandidate(const ObjectIdentity& object_id);
     void DecrementCandidateCount();
@@ -1642,20 +1596,18 @@ class MasterService {
     bool IsTransientResult(PromotionQueueResult result) const;
     size_t RunPromotionCandidateRetry(size_t max_shards_to_scan);
     size_t RunPromotionCandidateRetry();
-    size_t RunPromotionCandidateRetryForTesting();
-    size_t CountCandidatesForTesting(const TenantId& tenant_id);
-    void ResetCandidateBackoffsForTesting();
-
-    // Erase any in-flight PromotionTask for `key`, abort any staged promotion
-    // quota reservation, and decrement the cluster-wide in-flight counter. Safe
-    // no-op if no task exists.
-    void ErasePromotionTaskIfPresent(
-        TenantState& tenant_state, const std::string& key,
-        const TenantId& tenant_id) NO_THREAD_SAFETY_ANALYSIS {
+
+    // Erase any in-flight PromotionTask for `key`, refund its pending charge,
+    // and decrement the cluster-wide in-flight counter. Safe no-op if no task
+    // exists.
+    void ErasePromotionTaskIfPresent(TenantState& tenant_state,
+                                     const std::string& key)
+        NO_THREAD_SAFETY_ANALYSIS {
         auto task_it = tenant_state.promotion_tasks.find(key);
         if (task_it != tenant_state.promotion_tasks.end()) {
-            AbortTenantQuota(tenant_id,
-                             task_it->second.reserved_quota_charge_bytes);
+            ReleaseTenantQuota(
+                GetBoundTenantQuotaHandle(tenant_state),
+                std::exchange(task_it->second.pending_quota_charge_bytes, 0));
             tenant_state.promotion_tasks.erase(task_it);
             promotion_in_flight_.fetch_sub(1, std::memory_order_relaxed);
             MasterMetricManager::instance().dec_promotion_in_flight();
@@ -1670,6 +1622,7 @@ class MasterService {
     // Lease related members
     const uint64_t default_kv_lease_ttl_;     // in milliseconds
     const uint64_t default_kv_soft_pin_ttl_;  // in milliseconds
+    const uint64_t max_kv_soft_pin_ttl_;      // in milliseconds
     const bool allow_evict_soft_pinned_objects_;
 
     // Eviction related members
@@ -1679,6 +1632,11 @@ class MasterService {
         false};  // Set to trigger NoF eviction when allocation fails
     const double eviction_ratio_;                     // in range [0.0, 1.0]
     const double eviction_high_watermark_ratio_;      // in range [0.0, 1.0]
+    // Per-tenant watermark as a fraction of each tenant's OWN effective quota.
+    // Defaults to the same 0.90 as the pool-wide ratio above; 0.0 disables the
+    // pass. See EvictTenantsOverWatermark for why the pool-wide ratio is not
+    // sufficient once quotas partition the pool.
+    const double tenant_eviction_high_watermark_ratio_;  // in range [0.0, 1.0]
     const double nof_eviction_ratio_;                 // in range [0.0, 1.0]
     const double nof_eviction_high_watermark_ratio_;  // in range [0.0, 1.0]
 
@@ -1687,6 +1645,12 @@ class MasterService {
     std::atomic<bool> eviction_running_{false};
     static constexpr uint64_t kEvictionThreadSleepMs =
         10;  // 10 ms sleep between eviction checks
+    // The eviction thread wakes every 10 ms, but the tenant pass has to walk
+    // every registered tenant and lock every quota shard, so it is throttled
+    // rather than run on each tick. Quota pressure builds over seconds, not
+    // milliseconds, and admission still has its own synchronous fallback in
+    // between.
+    static constexpr uint64_t kTenantEvictionCheckIntervalMs = 1000;
 
     // Snapshot manager handles snapshot lifecycle orchestration
     std::unique_ptr<MasterSnapshotManager> snapshot_manager_;
@@ -1707,8 +1671,8 @@ class MasterService {
         MetadataAccessorRW(MasterService* service, ObjectIdentity object_id)
             : service_(service),
               object_id_(std::move(object_id)),
-              shard_idx_(service_->getMetadataShardIndex(object_id_.tenant_id,
-                                                         object_id_.user_key)),
+              shard_idx_(service_->getShardIndex(object_id_.tenant_id,
+                                                 object_id_.user_key)),
               shard_guard_(service_, shard_idx_),
               tenant_it_(shard_guard_->tenants.find(object_id_.tenant_id)),
               tenant_state_(tenant_it_ == shard_guard_->tenants.end()
@@ -1725,6 +1689,9 @@ class MasterService {
                                        ? ReplicationTaskIterator{}
                                        : tenant_state_->replication_tasks.find(
                                              object_id_.user_key)) {
+            if (tenant_state_ != nullptr) {
+                service_->GetBoundTenantQuotaHandle(*tenant_state_);
+            }
             // Automatically clean up invalid handles (memory replicas only).
             // Note: We only check memory replicas here to avoid lock order
             // violation (client_mutex_ must be acquired before metadata shard).
@@ -1733,6 +1700,12 @@ class MasterService {
             if (!(service_->enable_ha_ && service_->enable_oplog_) &&
                 tenant_state_ != nullptr &&
                 it_ != tenant_state_->metadata.end()) {
+                // Gate the snapshot on the publisher being live: this runs on
+                // every read-write metadata access, and the VisitReplicas walk
+                // plus vector allocation is pure overhead when KV events are
+                // off (the default).
+                const auto previous_kv_media =
+                    service_->KvMediaSnapshot(it_->second);
                 // Erase invalid memory replicas (those with unmounted
                 // segments). No client_mutex_ needed since we only check memory
                 // replicas.
@@ -1749,10 +1722,23 @@ class MasterService {
                     *tenant_state_, it_->second, removed_replica_ids);
                 const uint64_t after_charge =
                     service_->CompletedMemoryQuotaCharge(it_->second);
-                if (before_charge > after_charge) {
-                    service_->ReleaseCommittedQuotaCharge(
-                        it_->second, before_charge - after_charge);
+                if (service_->enable_multi_tenants_ &&
+                    before_charge > after_charge) {
+                    auto release_result =
+                        it_->second.quota_ledger.ReleaseCommitted(
+                            service_->GetBoundTenantQuotaHandle(*tenant_state_),
+                            before_charge - after_charge);
+                    if (!release_result) {
+                        LOG(ERROR)
+                            << "tenant quota committed release mismatch tenant="
+                            << object_id_.tenant_id.value()
+                            << ", key=" << object_id_.user_key
+                            << ", bytes=" << before_charge - after_charge;
+                    }
                 }
+                service_->SyncKvObjectState(object_id_.user_key, it_->second,
+                                            object_id_.tenant_id,
+                                            previous_kv_media);
                 // If no valid replicas remain, delete the whole object.
                 if (!it_->second.IsValid()) {
                     // NOTE: Erase() -> EraseMetadata() already removes the key
@@ -1763,8 +1749,7 @@ class MasterService {
                     this->Erase();
                     if (tenant_state_ != nullptr) {
                         service_->ErasePromotionTaskIfPresent(
-                            *tenant_state_, object_id_.user_key,
-                            object_id_.tenant_id);
+                            *tenant_state_, object_id_.user_key);
                         MaybeEraseEmptyTenant();
                     }
                 }
@@ -1801,14 +1786,16 @@ class MasterService {
         // Get metadata (only call when Exists() is true)
         ObjectMetadata& Get() NO_THREAD_SAFETY_ANALYSIS { return it_->second; }
 
-        const ReplicationTask& GetReplicationTask() NO_THREAD_SAFETY_ANALYSIS {
+        ReplicationTask& GetReplicationTask() NO_THREAD_SAFETY_ANALYSIS {
             return replication_task_it_->second;
         }
 
         // Delete current metadata (for PutRevoke or Remove operations)
-        void Erase() NO_THREAD_SAFETY_ANALYSIS {
+        void Erase(const std::vector<std::string>& previous_media_hint = {})
+            NO_THREAD_SAFETY_ANALYSIS {
             service_->EraseMetadata(*tenant_state_, it_, object_id_.tenant_id,
-                                    QuotaEraseMode::kFull, &shard_guard_);
+                                    QuotaEraseMode::kFull, &shard_guard_,
+                                    previous_media_hint);
             it_ = tenant_state_->metadata.end();
             MaybeEraseEmptyTenant();
         }
@@ -1826,8 +1813,7 @@ class MasterService {
         }
 
         void Create(const UUID& client_id, uint64_t total_length,
-                    std::vector<Replica> replicas, bool enable_soft_pin,
-                    bool enable_hard_pin = false,
+                    std::vector<Replica> replicas, bool enable_hard_pin = false,
                     ObjectDataType data_type = ObjectDataType::UNKNOWN,
                     std::string group_id = "") {
             if (Exists()) {
@@ -1840,13 +1826,9 @@ class MasterService {
                 std::forward_as_tuple(object_id_.user_key),
                 std::forward_as_tuple(
                     client_id, now, total_length, std::move(replicas),
-                    enable_soft_pin, enable_hard_pin, data_type, group_id,
+                    std::nullopt, enable_hard_pin, data_type, group_id,
                     object_id_.tenant_id, object_id_.user_key));
             it_ = result.first;
-            if (result.second) {
-                service_->IncrementTenantMetadataObjectCount(
-                    object_id_.tenant_id);
-            }
         }
 
        private:
@@ -1854,16 +1836,15 @@ class MasterService {
             std::unordered_map<std::string, ObjectMetadata>::iterator;
         using ProcessingIterator = std::unordered_set<std::string>::iterator;
         using ReplicationTaskIterator =
-            std::unordered_map<std::string, const ReplicationTask>::iterator;
+            std::unordered_map<std::string, ReplicationTask>::iterator;
 
         void EnsureTenantState() NO_THREAD_SAFETY_ANALYSIS {
             if (tenant_state_ != nullptr) {
                 return;
             }
-            auto result =
-                shard_guard_->tenants.try_emplace(object_id_.tenant_id);
-            tenant_it_ = result.first;
-            tenant_state_ = &tenant_it_->second;
+            tenant_state_ = &service_->GetOrCreateTenantState(
+                shard_guard_.get(), object_id_.tenant_id);
+            tenant_it_ = shard_guard_->tenants.find(object_id_.tenant_id);
             it_ = tenant_state_->metadata.end();
             processing_it_ = tenant_state_->processing_keys.end();
             replication_task_it_ = tenant_state_->replication_tasks.end();
@@ -1937,8 +1918,8 @@ class MasterService {
                            ObjectIdentity object_id)
             : service_(service),
               object_id_(std::move(object_id)),
-              shard_idx_(service_->getMetadataShardIndex(object_id_.tenant_id,
-                                                         object_id_.user_key)),
+              shard_idx_(service_->getShardIndex(object_id_.tenant_id,
+                                                 object_id_.user_key)),
               shard_guard_(service_, shard_idx_),
               tenant_it_(shard_guard_->tenants.find(object_id_.tenant_id)),
               tenant_state_(tenant_it_ == shard_guard_->tenants.end()
@@ -2001,23 +1982,20 @@ class MasterService {
 
     // Client related members
     mutable std::shared_mutex client_mutex_;
+    std::unordered_map<UUID, std::shared_ptr<ClientLivenessRecord>,
+                       boost::hash<UUID>>
+        client_liveness_records_;
     std::unordered_set<UUID, boost::hash<UUID>>
         ok_client_;  // client with ok status
     std::unordered_map<UUID, std::string, boost::hash<UUID>> client_host_id_;
+    ClientOffboardingWorker client_offboarding_worker_{this};
     void ClientMonitorFunc();
     std::thread client_monitor_thread_;
     std::atomic<bool> client_monitor_running_{false};
     static constexpr uint64_t kClientMonitorSleepMs =
         1000;  // 1000 ms sleep between client monitor checks
-    // boost lockfree queue requires trivial assignment operator
-    struct PodUUID {
-        uint64_t first;
-        uint64_t second;
-    };
-    static constexpr size_t kClientPingQueueSize =
-        128 * 1024;  // Size of the client ping queue
-    boost::lockfree::queue<PodUUID> client_ping_queue_{kClientPingQueueSize};
-    const int64_t client_live_ttl_sec_;
+    const int64_t client_active_ttl_sec_;
+    const int64_t client_suspicion_ttl_sec_;
     const std::chrono::seconds nof_heartbeat_interval_sec_;
     const std::chrono::milliseconds nof_heartbeat_probe_timeout_ms_;
     const uint32_t nof_heartbeat_failures_threshold_;
@@ -2071,23 +2049,120 @@ class MasterService {
     std::atomic<uint64_t> promotion_candidate_count_{0};
     std::atomic<size_t> promotion_retry_cursor_{0};
     static constexpr size_t kPromotionCandidateLimit = 50000;
-    static constexpr uint32_t kPromotionCandidateMaxRetries = 8;
+    // Retry budget is sized to the condition it waits on: the watermark /
+    // queue-cap / push-failure gates clear on the client's offload heartbeat
+    // (10s-scale), not in milliseconds. The old budget (8 retries ≈ 2.3s)
+    // expired candidates long before their condition could clear, silently
+    // killing promotions whose only trigger was a one-off read. 64 retries
+    // with a 5s backoff cap spans ~5 minutes (≈ 30 heartbeat ticks); the TTL
+    // bounds how long an unread key can keep a slot.
+    static constexpr uint32_t kPromotionCandidateMaxRetries = 64;
     static constexpr size_t kPromotionRetryBatchSize = 128;
     static constexpr size_t kPromotionRetryShardBatch = 64;
-    static constexpr std::chrono::milliseconds kPromotionCandidateTtl{60000};
+    static constexpr std::chrono::milliseconds kPromotionCandidateTtl{300000};
     static constexpr std::chrono::milliseconds
         kPromotionCandidateInitialBackoff{10};
     static constexpr std::chrono::milliseconds kPromotionCandidateMaxBackoff{
-        1000};
+        5000};
+    // Bound on self-sustaining execution-failure cycles: a key whose
+    // promotion keeps failing at execution time (AllocStart under DRAM
+    // pressure, TE-write flake, SSD error) is re-recorded at most this many
+    // times. Bounds a persistently-failing ("poison") key to this many
+    // delivery slots (~this many heartbeat ticks, ~30s at the 10s default)
+    // before it stops re-queueing itself; genuine reads can still re-admit
+    // it afterwards with a fresh count.
+    static constexpr uint32_t kMaxPromotionExecutionFailures = 3;
 
     // Master-side frequency sketch. Constructed only when promotion_on_hit_ is
     // true. CountMinSketch is mutex-protected internally so we can call into it
     // from any GetReplicaList caller without additional locking.
     std::unique_ptr<CountMinSketch> promotion_sketch_;
 
-    const std::string ha_backend_type_;
+    enum class DynamicReplicationMode { kOff, kObserve, kEnforce };
+    struct DynamicReplicationWindow {
+        std::chrono::steady_clock::time_point window_start{};
+        uint32_t hits{0};
+    };
+    struct DynamicReplicaPlan {
+        std::string source_segment;
+        std::string target_segment;
+        std::string target_domain;
+        std::shared_ptr<ClientLivenessRecord> source_liveness;
+    };
+
+    DynamicReplicationMode dynamic_replication_mode_{
+        DynamicReplicationMode::kOff};
+    uint32_t dynamic_replication_heat_window_seconds_{10};
+    double dynamic_replication_admission_qps_threshold_{0.8};
+    size_t dynamic_replication_max_memory_replicas_{2};
+    std::mutex dynamic_replication_mutex_;
+    std::unordered_map<std::string, DynamicReplicationWindow>
+        dynamic_replication_windows_;
+    std::deque<std::string> dynamic_replication_window_order_;
+    std::chrono::steady_clock::time_point
+        dynamic_replication_next_window_cleanup_{};
+    std::mutex dynamic_replication_admission_mutex_;
+    std::condition_variable dynamic_replication_admission_cv_;
+    std::queue<ObjectIdentity> dynamic_replication_admission_queue_;
+    std::unordered_set<std::string> dynamic_replication_admission_queued_;
+    std::thread dynamic_replication_admission_thread_;
+    std::atomic<bool> dynamic_replication_admission_running_{false};
+    static constexpr std::chrono::milliseconds
+        kDynamicReplicationActionCooldown{30000};
+    static constexpr std::chrono::milliseconds kDynamicReplicationLeaseTtl{
+        30000};
+    static constexpr std::chrono::milliseconds
+        kDynamicReplicationRecreateCooldown{60000};
+    static constexpr std::chrono::milliseconds
+        kDynamicReplicationWindowCleanupInterval{1000};
+    static constexpr uint64_t kDynamicReplicationAdmissionThreadSleepMs = 100;
+    static constexpr size_t kDynamicReplicationWindowEntryLimit = 50000;
+    static constexpr size_t kDynamicReplicationWindowCleanupBudget = 256;
+    static constexpr size_t kDynamicReplicationAdmissionQueueLimit = 50000;
+    static constexpr size_t kDynamicReplicationAdmissionBatchSize = 64;
+    static constexpr double kDynamicReplicationTargetHighWatermark = 0.85;
+
+    bool DynamicReplicationEnabled() const;
+    static uint64_t DynamicReplicationStableScore(const std::string& key,
+                                                  const std::string& segment);
+    bool DynamicReplicationEnforce() const;
+    uint32_t DynamicReplicationAdmissionMinHits() const;
+    void CleanupDynamicReplicationWindowsLocked(
+        std::chrono::steady_clock::time_point now, std::chrono::seconds window);
+    bool ObserveDynamicReplicationAccess(const ObjectIdentity& object_id);
+    bool DynamicReplicationHeatAdmitted(const ObjectIdentity& object_id);
+    void MaybeQueueDynamicReplicaProposal(const ObjectIdentity& object_id);
+    void EnqueueDynamicReplicaProposal(const ObjectIdentity& object_id);
+    void TrySubmitDynamicReplicaProposal(const ObjectIdentity& object_id);
+    tl::expected<ReplicaActionLease, ErrorCode>
+    SubmitReplicaActionProposalLocked(const ReplicaActionProposal& proposal);
+    uint64_t DynamicReplicationVersionEpoch(
+        const ObjectMetadata& metadata) const;
+    void ClearDynamicReplicationStateForKey(TenantState& tenant_state,
+                                            const std::string& key);
+    void CleanupExpiredDynamicReplicationState();
+    bool HasDynamicReplicationPending(TenantState& tenant_state,
+                                      const std::string& key);
+    std::optional<DynamicReplicaPlan> SelectDynamicReplicaPlan(
+        const ObjectMetadata& metadata,
+        const std::optional<std::string>& preferred_target_segment,
+        std::string target_domain);
+    tl::expected<UUID, ErrorCode> SubmitDynamicReplicaCopyTask(
+        const ObjectIdentity& object_id, const DynamicReplicaPlan& plan,
+        const UUID& lease_id, uint64_t version_epoch);
+    tl::expected<void, ErrorCode> ValidateDynamicReplicaPendingForCopyStart(
+        TenantState& tenant_state, const std::string& key,
+        const UUID& dynamic_replication_lease_id, const UUID& client_id,
+        const std::string& source_segment, uint64_t current_version_epoch,
+        uint64_t dynamic_replication_version_epoch,
+        const std::vector<std::string>& target_segments);
+    void RegisterDynamicReplicaStart(
+        TenantState& tenant_state, ObjectMetadata& metadata,
+        const std::string& key, const std::string& source_segment,
+        uint64_t version_epoch, const std::vector<std::string>& target_segments,
+        const std::vector<ReplicaID>& replica_ids);
+    static int64_t DynamicReplicationNowMs();
 
-    const std::string ha_backend_connstring_;
     const bool enable_oplog_;
     const uint32_t oplog_batch_max_entries_;
 
@@ -2095,14 +2170,10 @@ class MasterService {
     const std::string cluster_id_;
     // root filesystem directory for persistent storage
     const std::string root_fs_dir_;
-    // global 3fs/nfs segment size
-    int64_t global_file_segment_size_;
     // storage backend eviction configuration
     const bool enable_disk_eviction_;
     const uint64_t quota_bytes_;
     const bool enable_multi_tenants_;
-    const std::string tenant_quota_connector_type_;
-    const std::string tenant_quota_connector_uri_;
     std::unique_ptr<TenantQuotaPolicyStore> tenant_quota_policy_store_;
     mutable std::mutex tenant_quota_policy_mutex_;
     mutable std::mutex tenant_quota_recompute_mutex_;
@@ -2135,25 +2206,23 @@ class MasterService {
     void cleanupHttpMetadata(const std::string& segment_name);
 
     bool use_disk_replica_{false};
+    bool enable_dfs_{false};
+    std::unique_ptr<DfsAllocatorInterface> dfs_allocator_;
+    DfsGlobalAllocator* shard_allocator_{nullptr};
+    ImmutableBucketAllocator* bucket_allocator_{nullptr};
+    // Serializes allocation-failure recovery so concurrent writers can reuse
+    // capacity made available by the first recovery instead of each evicting
+    // a different frozen bucket.
+    std::mutex dfs_bucket_recovery_mutex_;
 
     // Segment management
     SegmentManager segment_manager_;
+    LocalSsdManager local_ssd_manager_;
     NoFSegmentManager nof_segment_manager_;
     BufferAllocatorType memory_allocator_type_;
     const AllocationStrategyType allocation_strategy_type_;
     std::shared_ptr<AllocationStrategy> allocation_strategy_;
 
-    bool enable_snapshot_restore_ = false;
-
-    bool enable_snapshot_ = false;
-    std::string snapshot_backup_dir_;
-    bool use_snapshot_backup_dir_{false};
-    uint64_t snapshot_interval_seconds_ = DEFAULT_SNAPSHOT_INTERVAL_SEC;
-    uint64_t snapshot_child_timeout_seconds_ =
-        DEFAULT_SNAPSHOT_CHILD_TIMEOUT_SEC;
-    uint32_t snapshot_retention_count_ = DEFAULT_SNAPSHOT_RETENTION_COUNT;
-    std::string snapshot_catalog_store_type_{};
-    std::string snapshot_catalog_store_connstring_;
     std::unique_ptr<SnapshotObjectStore> snapshot_object_store_;
     std::unique_ptr<ha::SnapshotCatalogStore> snapshot_catalog_store_;
     std::unique_ptr<MasterSnapshotRepository> snapshot_repository_;
@@ -2163,10 +2232,6 @@ class MasterService {
     // Discarded replicas management
     const std::chrono::seconds put_start_discard_timeout_sec_;
     const std::chrono::seconds put_start_release_timeout_sec_;
-    const std::string cxl_path_;
-    const size_t cxl_size_;
-    bool enable_cxl_;
-
     class DiscardedReplicas {
        public:
         DiscardedReplicas() = delete;
@@ -2266,39 +2331,125 @@ class MasterService {
 
     std::unique_ptr<KvEventPublisher> kv_event_publisher_;
 
+    // RemoveAll releases each shard lock before moving to the next one, so a
+    // concurrent commit can land in an already-scanned shard. Publishing
+    // `cleared` from the scan's own bookkeeping would then order it after that
+    // commit's `stored` and tell subscribers to drop a live object. Every
+    // announcement of a newly available object bumps its tenant's epoch, and a
+    // clear is published only if the epoch still matches the value read before
+    // the scan began. A racing commit therefore suppresses the
+    // clear instead of superseding it; subscribers fall back to the per-object
+    // `removed` stream, which is what they saw before `cleared` existed.
+    //
+    // Slots are a fixed hashed array rather than a per-tenant map so the
+    // structure cannot grow with tenant churn. A hash collision makes two
+    // tenants share an epoch, which can only suppress a clear that was safe to
+    // send — never publish one that was not.
+    static constexpr size_t kKvTenantEpochSlots = 1024;
+    mutable std::mutex kv_tenant_epoch_mutex_;
+    std::array<uint64_t, kKvTenantEpochSlots> kv_tenant_epochs_
+        GUARDED_BY(kv_tenant_epoch_mutex_) = {};
+    // Set from KvEventsEnabled() at construction. Kept separate so tests can
+    // exercise the ordering rule without a live ZMQ publisher.
+    bool kv_track_tenant_epochs_{false};
+    std::atomic<uint64_t> kv_cleared_published_{0};
+    std::atomic<uint64_t> kv_cleared_suppressed_by_epoch_{0};
+    // Fires after each shard's lock is released during a RemoveAll scan, which
+    // is the only point where a test can commit into an already-scanned shard.
+    std::function<void(size_t)> kv_remove_all_shard_hook_;
+
+    static size_t KvTenantEpochSlot(const std::string& tenant) {
+        return std::hash<std::string>{}(tenant) % kKvTenantEpochSlots;
+    }
+    // Called while the object's shard lock is held, before the `stored` is
+    // enqueued, so any clear that observes the old epoch has not yet published.
+    void BumpKvTenantEpoch(const std::string& tenant) {
+        if (!kv_track_tenant_epochs_) {
+            return;
+        }
+        std::lock_guard<std::mutex> lock(kv_tenant_epoch_mutex_);
+        ++kv_tenant_epochs_[KvTenantEpochSlot(tenant)];
+    }
+    uint64_t ReadKvTenantEpoch(const std::string& tenant) {
+        if (!kv_track_tenant_epochs_) {
+            return 0;
+        }
+        std::lock_guard<std::mutex> lock(kv_tenant_epoch_mutex_);
+        return kv_tenant_epochs_[KvTenantEpochSlot(tenant)];
+    }
+    // A whole-array copy taken before a scan begins. The global RemoveAll does
+    // not know which tenants it will meet, and reading a tenant's epoch only
+    // once the scan reaches it is too late — see the call site.
+    std::array<uint64_t, kKvTenantEpochSlots> SnapshotKvTenantEpochs(
+        bool needed) {
+        if (!needed || !kv_track_tenant_epochs_) {
+            return {};
+        }
+        std::lock_guard<std::mutex> lock(kv_tenant_epoch_mutex_);
+        return kv_tenant_epochs_;
+    }
+    // Re-reads the epoch and publishes under the same lock that guards the
+    // bump, so a commit cannot slip between the check and the enqueue.
+    void PublishKvClearedIfEpochUnchanged(const TenantId& tenant_id,
+                                          uint64_t expected_epoch);
+
+    // Gated snapshots for the call sites that capture a pre-mutation medium
+    // set. They run on hot metadata paths, so skip the VisitReplicas walk
+    // entirely when no publisher is listening.
+    std::vector<std::string> KvMediaSnapshot(const ObjectMetadata& metadata) {
+        return KvEventsEnabled() ? KvMediaForMetadata(metadata)
+                                 : std::vector<std::string>{};
+    }
+    std::vector<std::string> KvRemovalSnapshot(const ObjectMetadata& metadata) {
+        return KvEventsEnabled() ? KvMediaForRemoval(metadata)
+                                 : std::vector<std::string>{};
+    }
+
     static KvEventConfig BuildKvEventConfig(const MasterServiceConfig& config);
-    static std::string MediumForReplicaType(ReplicaType replica_type);
-    static std::string MediumForMetadata(const ObjectMetadata& metadata);
-    void PublishKvStored(const std::string& key, ReplicaType replica_type,
-                         const ObjectMetadata& metadata,
+    static std::vector<std::string> KvMediaForMetadata(
+        const ObjectMetadata& metadata);
+    // Removal paths may run after replicas have transitioned to PROCESSING or
+    // REMOVED. Keep their former medium visible as a conservative hint even
+    // though only COMPLETE replicas count as currently available media.
+    static std::vector<std::string> KvMediaForRemoval(
+        const ObjectMetadata& metadata);
+    // The medium is derived from the object's full replica set, not from the
+    // replica type that triggered the commit, so no replica type is taken.
+    void PublishKvStored(const std::string& key, const ObjectMetadata& metadata,
                          const TenantId& tenant_id);
-    void PublishKvRemoved(const std::string& key,
-                          const ObjectMetadata& metadata,
-                          const TenantId& tenant_id);
-    void PublishKvRemoved(const std::string& key, const std::string& medium,
-                          const TenantId& tenant_id,
-                          const std::string& group_id);
+    void SyncKvObjectState(
+        const std::string& key, const ObjectMetadata& metadata,
+        const TenantId& tenant_id,
+        const std::vector<std::string>& previous_media_hint = {});
+    void PublishKvRemoved(
+        const std::string& key, const ObjectMetadata& metadata,
+        const TenantId& tenant_id,
+        const std::vector<std::string>& previous_media_hint = {});
+    // evicted_replica_count is the number of replicas the caller actually
+    // dropped. It is deliberately not a byte count: a zero-length object still
+    // needs its removal announced.
     void PublishKvRemovedAfterEvict(const std::string& key,
-                                    uint64_t freed_bytes,
+                                    size_t evicted_replica_count,
                                     const std::string& medium,
                                     const ObjectMetadata& metadata,
                                     const TenantId& tenant_id);
+    void PublishKvCleared(const TenantId& tenant_id);
 
     // OpLog publishing
     std::shared_ptr<HaKvBackend> batch_oplog_kv_backend_;
     std::unique_ptr<OpLogBatchStorage> batch_oplog_storage_;
     std::unique_ptr<OrderedOpLogWriter> ordered_oplog_writer_;
+    BatchOpLogWriterFactory batch_oplog_writer_factory_;
 
     // OpLog publishing helpers
     std::string SerializeMetadataForOpLog(const ObjectMetadata& metadata) const;
     std::string SerializeMetadataForOpLogWithoutMemReplicas(
         const ObjectMetadata& metadata) const;
     std::string SerializeMetadataForOpLogFromReplicaDescriptors(
-        const UUID& client_id, uint64_t size,
-        const std::vector<Replica::Descriptor>& replicas,
-        const std::string& group_id = "",
-        ObjectDataType data_type = ObjectDataType::UNKNOWN) const;
-    ErrorCode InitializeBatchOpLogWriter(std::shared_ptr<HaKvBackend> backend);
+        const ObjectMetadata& metadata,
+        const std::vector<Replica::Descriptor>& replicas) const;
+    ErrorCode InitializeBatchOpLogWriter(std::shared_ptr<HaKvBackend> backend,
+                                         bool require_fenced_writer);
     tl::expected<uint64_t, ErrorCode> AppendOpLogVisibleBeforeDurable(
         OpType type, const std::string& tenant_id, const std::string& key,
         const std::string& payload);
@@ -2312,7 +2463,8 @@ class MasterService {
         const std::string& tenant_id, const std::string& key,
         const std::string& payload, DurableFinalizeCallback callback);
 
-    // Invalid endpoints from standby that don't exist locally
+    // Standby-restored memory endpoints remain unreadable until the owning
+    // Client has successfully remounted them.
     std::unordered_set<std::string> invalid_replica_endpoints_;
 
     // Keep DummyBufferAllocator alive after standby restore.
@@ -2324,7 +2476,13 @@ class MasterService {
 
     ErrorCode ValidateStandbyRemountSegment(const Segment& segment) const;
 
+    bool TryGetReadableReplicaDescriptor(const Replica& replica,
+                                         Replica::Descriptor& descriptor) const;
+    std::vector<Replica::Descriptor> GetReadableReplicaDescriptors(
+        const ObjectMetadata& metadata) const;
     bool IsReplicaReadable(const Replica& replica) const;
+    bool HasReadableReplica(const ObjectMetadata& metadata) const;
+    bool IsEvictableMemoryReplica(const Replica& replica) const;
 
     /**
      * Segment lifecycle persist helper. Tries to durably persist the
diff --git a/mooncake-store/include/master_snapshot_manager.h b/mooncake-store/include/master_snapshot_manager.h
index bd5c04249e..60df9cea99 100644
--- a/mooncake-store/include/master_snapshot_manager.h
+++ b/mooncake-store/include/master_snapshot_manager.h
@@ -31,18 +31,11 @@ class SnapshotChildProcessTest;
 }  // namespace test
 
 struct MasterSnapshotManagerOptions {
-    bool enable_snapshot{false};
     uint64_t snapshot_interval_seconds{0};
     uint64_t snapshot_child_timeout_seconds{0};
     uint32_t snapshot_retention_count{0};
     std::string snapshot_backup_dir;
     bool use_snapshot_backup_dir{false};
-    std::string snapshot_catalog_store_type;
-    std::string snapshot_catalog_store_connstring;
-    std::string ha_backend_type;
-    std::string ha_backend_connstring;
-    std::string cluster_id;
-    bool enable_ha{false};
 };
 
 /**
diff --git a/mooncake-store/include/metadata_store.h b/mooncake-store/include/metadata_store.h
index 97c886ddf7..e4187473c3 100644
--- a/mooncake-store/include/metadata_store.h
+++ b/mooncake-store/include/metadata_store.h
@@ -31,14 +31,18 @@ struct StandbyObjectMetadata {
     // 1. Standby does not perform eviction, so lease info is not used
     // 2. After promotion, new Primary should grant fresh leases, not restore
     // old ones
-    uint64_t last_sequence_id{
-        0};                // Last OpLog sequence ID that modified this key
+    // Soft pin is also omitted because it is runtime-only eviction-priority
+    // state; promoted objects resume as ordinary cache.
     std::string group_id;  // Tenant group identifier
     ObjectDataType data_type{
-        ObjectDataType::UNKNOWN};  // Data type classification
+        ObjectDataType::UNKNOWN};                  // Data type classification
+    struct_pack::compatible<bool, 1> hard_pinned;  // Eviction protection
 
     StandbyObjectMetadata() = default;
 
+    YLT_REFL(StandbyObjectMetadata, client_id, size, replicas, group_id,
+             data_type, hard_pinned);
+
     // Check if this metadata has valid replicas
     bool HasReplicas() const { return !replicas.empty(); }
 };
@@ -97,18 +101,20 @@ struct MetadataPayload {
     std::vector<Replica::Descriptor> replicas;
     struct_pack::compatible<std::string, 1> group_id;      // Tenant group
     struct_pack::compatible<ObjectDataType, 1> data_type;  // Data type
+    struct_pack::compatible<bool, 1> hard_pinned;          // Hard pin state
 
-    YLT_REFL(MetadataPayload, client_id, size, replicas, group_id, data_type);
+    YLT_REFL(MetadataPayload, client_id, size, replicas, group_id, data_type,
+             hard_pinned);
 
     // Convert to StandbyObjectMetadata
-    StandbyObjectMetadata ToStandbyMetadata(uint64_t sequence_id) const {
+    StandbyObjectMetadata ToStandbyMetadata() const {
         StandbyObjectMetadata meta;
         meta.client_id = client_id;
         meta.size = size;
         meta.replicas = replicas;
-        meta.last_sequence_id = sequence_id;
         meta.group_id = group_id.value_or("");
         meta.data_type = data_type.value_or(ObjectDataType::UNKNOWN);
+        meta.hard_pinned = hard_pinned.value_or(false);
         return meta;
     }
 };
diff --git a/mooncake-store/include/nvme_kv/backend.h b/mooncake-store/include/nvme_kv/backend.h
new file mode 100644
index 0000000000..49aadb40f5
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/backend.h
@@ -0,0 +1,99 @@
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <shared_mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "nvme_kv/connector.h"
+#include "nvme_kv/key_codec.h"
+#include "nvme_kv/key_conflict_policy.h"
+#include "nvme_kv/object_layout.h"
+#include "rpc_types.h"
+#include "storage_backend.h"
+#include "thread_pool.h"
+
+namespace mooncake {
+
+class NvmeKvStorageBackend : public StorageBackendInterface {
+   public:
+    explicit NvmeKvStorageBackend(
+        const FileStorageConfig &file_storage_config_);
+
+    tl::expected<void, ErrorCode> Init() override;
+
+    tl::expected<int64_t, ErrorCode> BatchOffload(
+        const std::unordered_map<std::string, std::vector<Slice>> &batch_object,
+        std::function<ErrorCode(const std::vector<std::string> &keys,
+                                std::vector<StorageObjectMetadata> &metadatas)>
+            complete_handler,
+        EvictionHandler eviction_handler = nullptr) override;
+
+    tl::expected<void, ErrorCode> BatchLoad(
+        std::unordered_map<std::string, Slice> &batched_slices) override;
+
+    tl::expected<bool, ErrorCode> IsExist(const std::string &key) override;
+    tl::expected<bool, ErrorCode> IsEnableOffloading() override;
+
+    tl::expected<void, ErrorCode> ScanMeta(
+        const std::function<ErrorCode(
+            const std::vector<std::string> &keys,
+            std::vector<StorageObjectMetadata> &metadatas)> &handler) override;
+
+   private:
+    using PhysicalKey = NvmeKvPhysicalKey;
+
+    struct OffloadResult {
+        bool stored = false;
+        bool inserted = false;
+    };
+
+    struct CachedManifest {
+        uint32_t resolved_slot = 0;
+        uint32_t payload_size = 0;
+        std::vector<NvmeKvManifestChunkRecord> chunk_records;
+        std::vector<size_t> chunk_offsets;
+    };
+
+    tl::expected<void, ErrorCode> InitDevice();
+    tl::expected<OffloadResult, ErrorCode> OffloadOne(
+        const std::string &key, const std::vector<Slice> &slices,
+        size_t payload_size);
+    void StoreBatchParallel(
+        std::vector<NvmeKvCommandExecutor::StoreRequest> &requests);
+    void RunParallelIo(size_t item_count,
+                       const std::function<void(size_t)> &task,
+                       size_t max_inflight = 0);
+    void RunPipelinedIo(size_t item_count,
+                        const std::function<void(size_t)> &io_task,
+                        const std::function<void(size_t)> &completion_task);
+    std::shared_ptr<const CachedManifest> FindCachedManifest(
+        const std::string &key, size_t payload_size) const;
+    std::shared_ptr<const CachedManifest> CacheManifest(
+        const std::string &key, size_t payload_size, uint32_t resolved_slot,
+        const std::vector<NvmeKvManifestChunkRecord> &chunk_records);
+    void CacheManifestAfterWrite(
+        const std::string &key, size_t payload_size, uint32_t resolved_slot,
+        const std::vector<NvmeKvManifestChunkRecord> &chunk_records) noexcept;
+    void InitIoWorkers();
+
+    std::atomic<bool> initialized_{false};
+    mutable std::shared_mutex manifest_cache_mutex_;
+    std::unordered_map<std::string, std::shared_ptr<const CachedManifest>>
+        manifest_cache_;
+    std::shared_ptr<NvmeKvConnector> connector_;
+    std::atomic<int64_t> total_size_{0};
+    std::atomic<int64_t> total_keys_{0};
+    size_t io_parallelism_ = 1;
+    size_t prepare_concurrency_ = 1;
+    size_t batch_submit_concurrency_ = 1;
+    size_t root_submit_concurrency_ = 1;
+    std::unique_ptr<ThreadPool> io_workers_;
+    std::unique_ptr<ThreadPool> submit_workers_;
+    std::unique_ptr<ThreadPool> root_submit_workers_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/connector.h b/mooncake-store/include/nvme_kv/connector.h
new file mode 100644
index 0000000000..b3c8c9cb31
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/connector.h
@@ -0,0 +1,44 @@
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "nvme_kv/executor.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct FileStorageConfig;
+
+class NvmeKvConnector {
+   public:
+    using PhysicalKey = NvmeKvCommandExecutor::PhysicalKey;
+    using Capabilities = NvmeKvCommandExecutor::Capabilities;
+
+    explicit NvmeKvConnector(const FileStorageConfig &file_storage_config);
+
+    tl::expected<void, ErrorCode> Init();
+    tl::expected<void, ErrorCode> Store(const PhysicalKey &key,
+                                        std::string value);
+    void StoreBatch(std::vector<NvmeKvCommandExecutor::StoreRequest> &requests);
+    tl::expected<std::string, ErrorCode> Retrieve(const PhysicalKey &key,
+                                                  uint32_t size_hint = 0) const;
+    void RetrieveBufferBatch(
+        std::vector<NvmeKvCommandExecutor::RetrieveBufferRequest> &requests)
+        const;
+    void RetrieveIntoBatch(
+        std::vector<NvmeKvCommandExecutor::RetrieveIntoRequest> &requests)
+        const;
+    tl::expected<void, ErrorCode> Delete(const PhysicalKey &key);
+    const Capabilities &GetCapabilities() const;
+
+   private:
+    tl::expected<void, ErrorCode> InitRealExecutor();
+    std::string storage_path_;
+    std::unique_ptr<NvmeKvCommandExecutor> executor_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/executor.h b/mooncake-store/include/nvme_kv/executor.h
new file mode 100644
index 0000000000..2233155f51
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/executor.h
@@ -0,0 +1,136 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct FileStorageConfig;
+
+class NvmeKvCommandExecutor {
+   public:
+    using PhysicalKey = std::array<uint8_t, 16>;
+
+    struct StoreRequest {
+        PhysicalKey key;
+        std::string_view value;
+        tl::expected<void, ErrorCode> result =
+            tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    };
+
+    struct RetrievedBuffer {
+        std::shared_ptr<void> owner;
+        const char *data = nullptr;
+        uint32_t size = 0;
+
+        std::string ToString() const {
+            return data == nullptr ? std::string()
+                                   : std::string(data, data + size);
+        }
+    };
+
+    struct RetrieveBufferRequest {
+        PhysicalKey key;
+        uint32_t size_hint = 0;
+        tl::expected<RetrievedBuffer, ErrorCode> result =
+            tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    };
+
+    struct RetrieveIntoRequest {
+        PhysicalKey key;
+        char *data = nullptr;
+        uint32_t size = 0;
+        tl::expected<uint32_t, ErrorCode> result =
+            tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    };
+
+    struct Capabilities {
+        uint32_t effective_max_value_size = UINT32_MAX;
+        uint32_t queue_depth = 1;
+    };
+
+    virtual ~NvmeKvCommandExecutor() = default;
+
+    virtual tl::expected<void, ErrorCode> Store(const PhysicalKey &key,
+                                                std::string value) = 0;
+    // Batch calls are synchronous: implementations must finish accessing all
+    // request-owned buffers and populate every result before returning.
+    virtual void StoreBatch(std::vector<StoreRequest> &requests) {
+        for (auto &request : requests) {
+            request.result = Store(request.key, std::string(request.value));
+        }
+    }
+    virtual tl::expected<std::string, ErrorCode> Retrieve(
+        const PhysicalKey &key, uint32_t size_hint = 0) const = 0;
+    virtual void RetrieveBufferBatch(
+        std::vector<RetrieveBufferRequest> &requests) const {
+        for (auto &request : requests) {
+            auto result = Retrieve(request.key, request.size_hint);
+            if (!result) {
+                request.result = tl::make_unexpected(result.error());
+                continue;
+            }
+            auto owner =
+                std::make_shared<std::string>(std::move(result.value()));
+            RetrievedBuffer buffer;
+            buffer.owner = owner;
+            buffer.data = owner->data();
+            buffer.size = static_cast<uint32_t>(owner->size());
+            request.result = std::move(buffer);
+        }
+    }
+    virtual void RetrieveIntoBatch(
+        std::vector<RetrieveIntoRequest> &requests) const {
+        std::vector<RetrieveBufferRequest> buffer_requests;
+        buffer_requests.reserve(requests.size());
+        for (const auto &request : requests) {
+            RetrieveBufferRequest buffer_request;
+            buffer_request.key = request.key;
+            buffer_request.size_hint = request.size;
+            buffer_requests.push_back(std::move(buffer_request));
+        }
+        RetrieveBufferBatch(buffer_requests);
+        for (size_t index = 0; index < requests.size(); ++index) {
+            const auto &buffer_result = buffer_requests[index].result;
+            if (!buffer_result) {
+                requests[index].result =
+                    tl::make_unexpected(buffer_result.error());
+                continue;
+            }
+            const auto &buffer = buffer_result.value();
+            if (requests[index].data == nullptr ||
+                buffer.size != requests[index].size) {
+                requests[index].result =
+                    tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                continue;
+            }
+            std::memcpy(requests[index].data, buffer.data, buffer.size);
+            requests[index].result = buffer.size;
+        }
+    }
+    virtual tl::expected<void, ErrorCode> Delete(const PhysicalKey &key) = 0;
+    virtual const Capabilities &GetCapabilities() const = 0;
+};
+
+using NvmeKvExecutorResult =
+    tl::expected<std::unique_ptr<NvmeKvCommandExecutor>, ErrorCode>;
+
+NvmeKvExecutorResult CreateNvmeKvIoUringExecutor(
+    std::string device_path, uint32_t nsid, uint32_t queue_depth,
+    uint32_t runtime_transfer_limit);
+
+NvmeKvExecutorResult CreateNvmeKvIoctlExecutor(std::string device_path,
+                                               uint32_t nsid,
+                                               uint32_t queue_depth,
+                                               uint32_t runtime_transfer_limit);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/executor_util.h b/mooncake-store/include/nvme_kv/executor_util.h
new file mode 100644
index 0000000000..872b8462e3
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/executor_util.h
@@ -0,0 +1,124 @@
+#pragma once
+
+#include <cstdint>
+#include <cstdlib>
+#include <memory>
+#include <string>
+
+#include "nvme_kv/executor.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct NvmeKvPackedKeyFields {
+    uint32_t cdw2 = 0;
+    uint32_t cdw3 = 0;
+    uint32_t cdw14 = 0;
+    uint32_t cdw15 = 0;
+};
+
+constexpr uint32_t kDefaultNvmeKvQueueDepth = 256;
+constexpr uint32_t kDefaultNvmeKvRuntimeTransferLimit = 270336;
+constexpr uint32_t kDefaultNvmeKvProtocolMaxValueSize = 512 * 1024;
+constexpr uint32_t kDefaultNvmeKvTransferAlignmentBytes = 4096;
+constexpr uint32_t kDefaultNvmeKvValueBlockUnitBytes = 512;
+constexpr uint32_t kNvmeKvMaxKeySizeBytes = 16;
+constexpr uint32_t kNvmeKvCommandTimeoutMs = 30000;
+constexpr uint32_t kNvmeKvStoreIfNotExistsOption = 0x2;
+constexpr uint8_t kNvmeKvCommandSetIdentifier = 0x01;
+constexpr uint8_t kNvmeKvStoreOpcode = 0x01;
+constexpr uint8_t kNvmeKvRetrieveOpcode = 0x02;
+constexpr uint8_t kNvmeKvDeleteOpcode = 0x10;
+
+struct NvmeKvFreeDeleter {
+    void operator()(void *ptr) const { std::free(ptr); }
+};
+
+using NvmeKvAlignedBuffer = std::unique_ptr<char, NvmeKvFreeDeleter>;
+
+uint32_t ParseNvmeKvU32EnvOr(const char *name, uint32_t fallback);
+NvmeKvAlignedBuffer AllocateNvmeKvAlignedBuffer(size_t size);
+uint32_t NvmeKvTransferAlignmentBytes();
+uint32_t NvmeKvValueBlockUnitBytes();
+uint32_t RoundUpToNvmeKvTransferBytes(uint32_t bytes);
+uint32_t RoundDownToNvmeKvTransferBytes(uint32_t bytes);
+uint32_t ComputeNvmeKvValueBlockCountMinusOne(uint32_t bytes);
+uint32_t ResolveNvmeKvStoreSubmissionBytes(uint32_t logical_bytes);
+uint32_t ResolveNvmeKvInitialRetrieveBytes(uint32_t size_hint,
+                                           uint32_t effective_max_value_size);
+uint32_t ResolveNvmeKvRetrievedValueSize(const char *buffer,
+                                         uint32_t returned_size,
+                                         uint32_t max_size, uint32_t size_hint);
+bool ShouldRetryNvmeKvRetrieveWithMaxBuffer(ErrorCode error, uint32_t size_hint,
+                                            uint32_t request_bytes,
+                                            uint32_t effective_max_value_size);
+NvmeKvCommandExecutor::Capabilities BuildNvmeKvCapabilities(
+    uint32_t default_queue_depth, uint32_t queue_depth,
+    uint32_t runtime_transfer_limit);
+std::string NvmeKvPhysicalKeyToHex(
+    const NvmeKvCommandExecutor::PhysicalKey &key);
+NvmeKvPackedKeyFields PackNvmeKvPhysicalKey(
+    const NvmeKvCommandExecutor::PhysicalKey &key);
+ErrorCode MapNvmeKvStatus(uint32_t status, bool is_write);
+ErrorCode MapNvmeKvTransportError(int err, bool is_write);
+bool IsNvmeKvControlFlowError(ErrorCode error);
+
+inline uint32_t BuildNvmeKvKeyLengthField(size_t key_length) {
+    return static_cast<uint32_t>(key_length) & 0xFFu;
+}
+
+template <typename Command>
+void EncodeNvmeKvKey(const NvmeKvCommandExecutor::PhysicalKey &key,
+                     Command &cmd) {
+    const auto fields = PackNvmeKvPhysicalKey(key);
+    cmd.cdw2 = fields.cdw2;
+    cmd.cdw3 = fields.cdw3;
+    cmd.cdw14 = fields.cdw14;
+    cmd.cdw15 = fields.cdw15;
+}
+
+template <typename Command>
+void BuildNvmeKvStoreCommand(Command &cmd, uint32_t nsid,
+                             const NvmeKvCommandExecutor::PhysicalKey &key,
+                             const void *data, uint32_t transfer_bytes) {
+    cmd = {};
+    cmd.opcode = kNvmeKvStoreOpcode;
+    cmd.nsid = nsid;
+    cmd.addr = reinterpret_cast<uint64_t>(data);
+    cmd.data_len = transfer_bytes;
+    cmd.cdw10 = transfer_bytes;
+    cmd.cdw11 = (kNvmeKvStoreIfNotExistsOption << 8) |
+                BuildNvmeKvKeyLengthField(key.size());
+    cmd.cdw12 = ComputeNvmeKvValueBlockCountMinusOne(transfer_bytes);
+    cmd.timeout_ms = kNvmeKvCommandTimeoutMs;
+    EncodeNvmeKvKey(key, cmd);
+}
+
+template <typename Command>
+void BuildNvmeKvRetrieveCommand(Command &cmd, uint32_t nsid,
+                                const NvmeKvCommandExecutor::PhysicalKey &key,
+                                void *data, uint32_t transfer_bytes) {
+    cmd = {};
+    cmd.opcode = kNvmeKvRetrieveOpcode;
+    cmd.nsid = nsid;
+    cmd.addr = reinterpret_cast<uint64_t>(data);
+    cmd.data_len = transfer_bytes;
+    cmd.cdw10 = transfer_bytes;
+    cmd.cdw11 = BuildNvmeKvKeyLengthField(key.size());
+    cmd.cdw12 = ComputeNvmeKvValueBlockCountMinusOne(transfer_bytes);
+    cmd.timeout_ms = kNvmeKvCommandTimeoutMs;
+    EncodeNvmeKvKey(key, cmd);
+}
+
+template <typename Command>
+void BuildNvmeKvDeleteCommand(Command &cmd, uint32_t nsid,
+                              const NvmeKvCommandExecutor::PhysicalKey &key) {
+    cmd = {};
+    cmd.opcode = kNvmeKvDeleteOpcode;
+    cmd.nsid = nsid;
+    cmd.cdw11 = BuildNvmeKvKeyLengthField(key.size());
+    cmd.timeout_ms = kNvmeKvCommandTimeoutMs;
+    EncodeNvmeKvKey(key, cmd);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/key_codec.h b/mooncake-store/include/nvme_kv/key_codec.h
new file mode 100644
index 0000000000..9291800477
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/key_codec.h
@@ -0,0 +1,33 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+#include <string_view>
+
+namespace mooncake {
+
+using NvmeKvPhysicalKey = std::array<uint8_t, 16>;
+
+struct NvmeKvObjectIdentity {
+    std::string logical_key;
+};
+
+constexpr uint32_t kNvmeKvMaxPhysicalKeySlots = 64;
+
+uint32_t ComputeNvmeKvChecksum(std::span<const uint8_t> data);
+std::string SerializeNvmeKvCanonicalIdentity(
+    const NvmeKvObjectIdentity& identity);
+bool ParseNvmeKvCanonicalIdentity(std::string_view encoded_identity,
+                                  NvmeKvObjectIdentity& identity);
+std::array<uint8_t, 32> ComputeNvmeKvVerifyHash(
+    const NvmeKvObjectIdentity& identity);
+NvmeKvPhysicalKey EncodeNvmeKvPhysicalKey(const NvmeKvObjectIdentity& identity,
+                                          uint32_t slot = 0);
+NvmeKvPhysicalKey EncodeNvmeKvChunkPhysicalKey(
+    const NvmeKvObjectIdentity& identity, uint32_t chunk_index,
+    uint32_t slot = 0);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/key_conflict_policy.h b/mooncake-store/include/nvme_kv/key_conflict_policy.h
new file mode 100644
index 0000000000..8a772ca453
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/key_conflict_policy.h
@@ -0,0 +1,49 @@
+#pragma once
+
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "nvme_kv/connector.h"
+#include "nvme_kv/key_codec.h"
+#include "nvme_kv/object_layout.h"
+#include "types.h"
+
+namespace mooncake {
+
+class NvmeKvKeyConflictPolicy {
+   public:
+    using PhysicalKey = NvmeKvPhysicalKey;
+
+    enum class ExistingObjectDecision {
+        kNotFound,
+        kSameObject,
+        kDifferentObject,
+    };
+
+    struct WritePlan {
+        NvmeKvObjectIdentity identity;
+        PhysicalKey root_key{};
+        bool store_inline = false;
+        std::string root_blob;
+        std::vector<std::pair<PhysicalKey, std::string_view>> chunk_values;
+        std::vector<NvmeKvManifestChunkRecord> manifest_records;
+    };
+
+    static bool ValidateResolvedRootPlacement(
+        const NvmeKvObjectIdentity& identity,
+        const NvmeKvStoredIdentityView& stored_view,
+        const NvmeKvPhysicalKey& observed_physical_key);
+    static tl::expected<WritePlan, ErrorCode> BuildWritePlan(
+        const NvmeKvObjectIdentity& identity, std::string_view payload,
+        uint32_t slot, uint32_t max_value_size);
+    static tl::expected<ExistingObjectDecision, ErrorCode>
+    ResolveExistingObject(NvmeKvConnector& connector,
+                          const PhysicalKey& physical_key,
+                          std::string_view expected_blob);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/nvme_kv/object_layout.h b/mooncake-store/include/nvme_kv/object_layout.h
new file mode 100644
index 0000000000..13f4e7e219
--- /dev/null
+++ b/mooncake-store/include/nvme_kv/object_layout.h
@@ -0,0 +1,86 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "nvme_kv/key_codec.h"
+
+namespace mooncake {
+
+enum class NvmeKvObjectType : uint32_t {
+    kInline = 1,
+    kManifest = 2,
+};
+
+struct NvmeKvObjectHeader {
+    uint32_t magic;
+    uint32_t object_type;
+    uint32_t payload_size;
+    std::array<uint8_t, 32> verify_hash;
+    uint32_t payload_checksum;
+    uint32_t header_checksum;
+    uint32_t identity_metadata_size;
+
+    static constexpr uint32_t kMagic = 0x4e564b56;
+};
+
+struct NvmeKvStoredIdentityMetadata {
+    NvmeKvPhysicalKey resolved_physical_key{};
+    uint32_t resolved_slot = 0;
+};
+
+struct NvmeKvStoredIdentityView {
+    std::string logical_key;
+    NvmeKvPhysicalKey resolved_physical_key{};
+    uint32_t resolved_slot = 0;
+};
+
+struct NvmeKvManifestMetadata {
+    uint32_t logical_payload_size;
+    uint32_t chunk_count;
+};
+
+struct NvmeKvManifestChunkRecord {
+    NvmeKvPhysicalKey physical_key;
+    uint32_t payload_size;
+    uint32_t payload_checksum;
+};
+
+uint32_t ComputeNvmeKvPayloadChecksum(std::string_view payload);
+uint32_t ComputeNvmeKvHeaderChecksum(const NvmeKvObjectHeader& header);
+uint32_t ComputeNvmeKvStoredIdentityMetadataSize(
+    const NvmeKvObjectIdentity& identity);
+NvmeKvStoredIdentityMetadata BuildNvmeKvStoredIdentityMetadata(
+    const NvmeKvPhysicalKey& physical_key, uint32_t slot);
+std::string SerializeNvmeKvStoredIdentity(
+    const NvmeKvObjectIdentity& identity,
+    const NvmeKvStoredIdentityMetadata& metadata);
+bool ParseNvmeKvStoredIdentity(std::string_view encoded_identity,
+                               NvmeKvStoredIdentityView& identity_view);
+bool ValidateNvmeKvHeader(const NvmeKvObjectHeader& header,
+                          const NvmeKvObjectIdentity& identity,
+                          uint32_t expected_identity_size,
+                          uint32_t expected_size,
+                          NvmeKvObjectType expected_type);
+std::string BuildNvmeKvObjectBlob(const NvmeKvObjectHeader& header,
+                                  std::string_view identity_metadata,
+                                  std::string_view payload);
+bool ParseNvmeKvObjectBlob(std::string_view object_blob,
+                           NvmeKvObjectHeader& header,
+                           std::string_view& identity_metadata_view,
+                           std::string_view& payload_view);
+uint32_t ResolveNvmeKvObjectBlobSizeFromPrefix(const char* buffer,
+                                               uint32_t prefix_size);
+uint32_t ResolveNvmeKvObjectBlobSize(const char* buffer, uint32_t returned_size,
+                                     uint32_t max_size);
+std::string SerializeNvmeKvManifest(
+    const NvmeKvManifestMetadata& metadata,
+    const std::vector<NvmeKvManifestChunkRecord>& chunk_records);
+bool ParseNvmeKvManifest(std::string_view manifest_payload,
+                         NvmeKvManifestMetadata& metadata,
+                         std::vector<NvmeKvManifestChunkRecord>& chunk_records);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/object_entry.h b/mooncake-store/include/object_entry.h
new file mode 100644
index 0000000000..1fb12a030f
--- /dev/null
+++ b/mooncake-store/include/object_entry.h
@@ -0,0 +1,98 @@
+#pragma once
+
+// ObjectEntry: the per-object runtime shell. The ObjectMetadata envelope is
+// the single source of identity (user_key, group_id) and group-lease wiring;
+// the entry adds the per-key runtime state and owns the lock guarding both.
+//
+// The lock never leaves the class: everything below the identity is reachable
+// only through WithExclusiveAccess or WithSharedAccess, which hold it for the
+// callback, so a caller cannot act on half of a compound operation.
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <shared_mutex>
+#include <string>
+#include <utility>
+
+#include "object_metadata.h"
+#include "object_runtime_state.h"
+
+namespace mooncake {
+
+class ObjectEntry {
+   public:
+    // What the entry adds to the envelope: the per-key task state, at most one
+    // in-flight task per entry, and the lifecycle claims over it.
+    struct State {
+        // A primary write or a background task is in flight for this key.
+        bool is_processing{false};
+        // Teardown-once claim: a second eraser of the same entry bails out
+        // instead of double-releasing its refcounts, quota charges and KV
+        // removal events.
+        bool is_torn_down{false};
+        std::optional<ReplicationTask> replication_task;
+        std::optional<OffloadingTask> offloading_task;
+        std::optional<PromotionTask> promotion_task;
+        std::optional<PromotionCandidate> promotion_candidate;
+        std::optional<DynamicReplicaPending> dynamic_replication_pending;
+        std::chrono::steady_clock::time_point dynamic_replication_cooldown{};
+    };
+
+    // Takes ownership of a non-null metadata envelope; the envelope carries the
+    // object's identity (user_key, group_id).
+    explicit ObjectEntry(std::unique_ptr<ObjectMetadata> metadata)
+        : metadata_(std::move(metadata)) {}
+
+    // Not copyable/movable: it owns per-object state and a per-object lock.
+    ObjectEntry(const ObjectEntry&) = delete;
+    ObjectEntry& operator=(const ObjectEntry&) = delete;
+    ObjectEntry(ObjectEntry&&) = delete;
+    ObjectEntry& operator=(ObjectEntry&&) = delete;
+
+    // Identity lives in the envelope, which holds both as const members, so
+    // these read without taking `mutex_`.
+    const std::string& key() const noexcept { return metadata_->user_key; }
+    const std::string& group_id() const noexcept { return metadata_->group_id; }
+
+    // Monotonic generation assigned by ObjectIndex at route publication
+    // (0 = never published). Lets a holder distinguish the entry it holds from
+    // a later replacement of the same key.
+    [[nodiscard]] uint64_t generation() const noexcept {
+        return generation_.load(std::memory_order_relaxed);
+    }
+
+    // Runs `fn(envelope, state)` with the entry held exclusively and returns
+    // whatever `fn` returns. Lock order: entry → route → metadata spin lock,
+    // never the reverse for any pair. Both references last only for the call.
+    template <typename Fn>
+    decltype(auto) WithExclusiveAccess(Fn&& fn) {
+        std::unique_lock<std::shared_mutex> lock(mutex_);
+        return std::forward<Fn>(fn)(*metadata_, state_);
+    }
+
+    // The same for readers: `fn` sees both halves but may not mutate them.
+    template <typename Fn>
+    decltype(auto) WithSharedAccess(Fn&& fn) const {
+        std::shared_lock<std::shared_mutex> lock(mutex_);
+        return std::forward<Fn>(fn)(std::as_const(*metadata_),
+                                    std::as_const(state_));
+    }
+
+   private:
+    friend class ObjectIndex;  // assigns generation_ at route publication
+
+    std::unique_ptr<ObjectMetadata> metadata_;
+    // Atomic because publication writes it under the route lock while a holder
+    // reads it without any lock. Relaxed: the number is only compared, it
+    // carries no other state.
+    std::atomic<uint64_t> generation_{0};
+    // Mutable so a const entry can still be read under the shared lock.
+    mutable std::shared_mutex mutex_;
+    State state_ GUARDED_BY(mutex_);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/object_index.h b/mooncake-store/include/object_index.h
new file mode 100644
index 0000000000..0de028a74d
--- /dev/null
+++ b/mooncake-store/include/object_index.h
@@ -0,0 +1,119 @@
+#pragma once
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "common/transparent_string_hash.h"
+#include "object_entry.h"
+
+namespace mooncake {
+
+// The object route for one tenant: a flat map from object key to a strong
+// ObjectEntry handle.
+//
+// A strong handle keeps the entry alive, not current: Get returns it under the
+// shared route lock and releases that lock before the caller takes the entry's
+// own mutex, so a caller that needs the published instance compares its
+// generation under that lock, and a teardown erases with the identity-checked
+// EraseIf.
+class ObjectIndex {
+   public:
+    // nullptr when the key is absent. The returned handle is strong, so it
+    // keeps the entry alive after the route lock is released.
+    [[nodiscard]] std::shared_ptr<ObjectEntry> Get(std::string_view key) const {
+        std::shared_lock<std::shared_mutex> lock(route_lock_);
+        auto it = route_.find(key);
+        return it == route_.end() ? nullptr : it->second;
+    }
+
+    // Publish `entry` under its own key. Returns false when the key is
+    // already routed, in which case `entry` is left untouched and the caller
+    // re-looks-up instead.
+    //
+    // The route key is the entry's own key, so the slot it lands in and the
+    // key every lookup, revalidation and erase uses cannot disagree.
+    [[nodiscard]] bool Insert(std::shared_ptr<ObjectEntry> entry) {
+        assert(entry != nullptr);
+        std::unique_lock<std::shared_mutex> lock(route_lock_);
+        const auto [it, inserted] =
+            route_.try_emplace(entry->key(), std::move(entry));
+        if (!inserted) {
+            return false;
+        }
+        it->second->generation_.store(++generation_counter_,
+                                      std::memory_order_relaxed);
+        return true;
+    }
+
+    // Erase the route slot for `key` only when it still resolves to
+    // `expected`, so a teardown that holds an entry cannot drop the
+    // replacement a concurrent remove and re-create published under the same
+    // key. The handle is an argument rather than a raw pointer because the
+    // caller's own handle is what keeps the entry alive across the call; a
+    // null one never matches.
+    [[nodiscard]] bool EraseIf(std::string_view key,
+                               const std::shared_ptr<ObjectEntry>& expected) {
+        std::unique_lock<std::shared_mutex> lock(route_lock_);
+        const auto it = route_.find(key);
+        if (it == route_.end() || it->second != expected) {
+            return false;
+        }
+        route_.erase(it);
+        return true;
+    }
+
+    [[nodiscard]] bool Contains(std::string_view key) const {
+        std::shared_lock<std::shared_mutex> lock(route_lock_);
+        return route_.contains(key);
+    }
+
+    [[nodiscard]] size_t ObjectCount() const {
+        std::shared_lock<std::shared_mutex> lock(route_lock_);
+        return route_.size();
+    }
+
+    // True when no object is currently routed.
+    [[nodiscard]] bool Empty() const {
+        std::shared_lock<std::shared_mutex> lock(route_lock_);
+        return route_.empty();
+    }
+
+    // Collect strong handles to every object currently routed. The route lock
+    // is released before returning, so a caller can take each entry's own
+    // mutex without holding the route lock.
+    [[nodiscard]] std::vector<std::shared_ptr<ObjectEntry>> SnapshotObjects()
+        const {
+        std::shared_lock<std::shared_mutex> lock(route_lock_);
+        std::vector<std::shared_ptr<ObjectEntry>> entries;
+        entries.reserve(route_.size());
+        for (const auto& entry : route_) {
+            entries.push_back(entry.second);
+        }
+        return entries;
+    }
+
+   private:
+    // Object route: the strong entry handles keyed by object key, guarded by a
+    // single shared_mutex. Mutating one object's state is finer-grained: each
+    // entry guards its own.
+    mutable std::shared_mutex route_lock_;
+    // Transparent lookup: every accessor takes a view, so a caller that already
+    // has one does not build a string to find the entry.
+    std::unordered_map<std::string, std::shared_ptr<ObjectEntry>,
+                       TransparentStringHash, std::equal_to<>>
+        route_;
+    // Monotonic publication counter backing ObjectEntry::generation(). Only
+    // read and bumped while route_lock_ is held for writing.
+    uint64_t generation_counter_{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/object_metadata.h b/mooncake-store/include/object_metadata.h
new file mode 100644
index 0000000000..ff0185e274
--- /dev/null
+++ b/mooncake-store/include/object_metadata.h
@@ -0,0 +1,520 @@
+#pragma once
+
+// ObjectMetadata: the per-object metadata envelope.
+//
+// Moved out of MasterService so the service and the per-object metadata
+// module share one definition. The envelope owns the object identity, the
+// authoritative read lease, the replica list, the soft-pin state and the
+// tenant quota ledger.
+//
+// It has no ownership lock: whoever owns the envelope decides how the
+// envelope as a whole is guarded. The `lock` member below is internal and
+// narrower — it protects only `lease_` and `soft_pin_timeout`, so a holder of
+// the envelope can read either without them tearing.
+
+#include <algorithm>
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <iterator>
+#include <memory>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include "lease.h"
+#include "master_metric_manager.h"
+#include "mutex.h"
+#include "replica.h"
+#include "tenant_id.h"
+#include "tenant_quota_ledger.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct ResolvedSoftPinRequest {
+    SoftPinAction action{SoftPinAction::PRESERVE};
+    std::chrono::milliseconds ttl{0};
+};
+
+struct ObjectMetadata {
+    struct SoftPinEvaluation {
+        bool active{false};
+        int metric_delta{0};
+        std::optional<std::chrono::system_clock::time_point> removed_deadline;
+        std::optional<std::chrono::system_clock::time_point> deadline_to_index;
+    };
+
+    struct PendingSoftPinAction {
+        SoftPinAction action{SoftPinAction::PRESERVE};
+        std::chrono::milliseconds ttl{0};
+        std::unordered_set<ReplicaID> eligible_replica_ids;
+    };
+
+    // RAII-style metric management
+    ~ObjectMetadata() {
+        MasterMetricManager::instance().dec_key_count(1);
+        if (soft_pin_timeout) {
+            MasterMetricManager::instance().dec_soft_pin_key_count(1);
+        }
+    }
+
+    ObjectMetadata() = delete;
+
+    ObjectMetadata(const UUID& client_id_,
+                   const std::chrono::system_clock::time_point put_start_time_,
+                   size_t value_length, std::vector<Replica>&& reps,
+                   std::optional<std::chrono::system_clock::time_point>
+                       committed_soft_pin_timeout = std::nullopt,
+                   bool enable_hard_pin = false,
+                   ObjectDataType data_type_ = ObjectDataType::UNKNOWN,
+                   std::string group_id_ = "", TenantId tenant_id_ = TenantId(),
+                   std::string user_key_ = {})
+        : client_id(client_id_),
+          put_start_time(put_start_time_),
+          size(value_length),
+          data_type(data_type_),
+          group_id(std::move(group_id_)),
+          tenant_id(std::move(tenant_id_)),
+          user_key(std::move(user_key_)),
+          soft_pin_timeout(std::move(committed_soft_pin_timeout)),
+          hard_pinned(enable_hard_pin),
+          replicas_(std::move(reps)) {
+        MasterMetricManager::instance().inc_key_count(1);
+        if (soft_pin_timeout) {
+            MasterMetricManager::instance().inc_soft_pin_key_count(1);
+        }
+        MasterMetricManager::instance().observe_value_size(value_length);
+    }
+
+    ObjectMetadata(const ObjectMetadata&) = delete;
+    ObjectMetadata& operator=(const ObjectMetadata&) = delete;
+    ObjectMetadata(ObjectMetadata&&) = delete;
+    ObjectMetadata& operator=(ObjectMetadata&&) = delete;
+
+    // Updated by UpsertStart (Case B) to reflect the new writer.
+    UUID client_id;
+    // Updated by UpsertStart (Case B) to reset the discard timeout.
+    std::chrono::system_clock::time_point put_start_time;
+    const size_t size;
+    std::optional<uint64_t> object_checksum;
+    const ObjectDataType data_type{ObjectDataType::UNKNOWN};
+    const std::string group_id;
+    const TenantId tenant_id;
+    const std::string user_key;
+
+    mutable SpinLock lock;
+    // Authoritative lease: ungrouped objects own one; grouped objects share
+    // the group's. Never null after construction.
+    mutable std::shared_ptr<Lease> lease_ GUARDED_BY(lock) =
+        std::make_shared<Lease>();
+    mutable std::optional<std::chrono::system_clock::time_point>
+        soft_pin_timeout GUARDED_BY(lock);  // committed object soft-pin
+                                            // deadline
+    // Replica IDs scope this action to the current write. PutEnd does not
+    // carry a generation token, so a stale End from the same client cannot
+    // otherwise be distinguished from the current write.
+    std::optional<PendingSoftPinAction> pending_soft_pin_action;
+    const bool hard_pinned{false};  // immutable, set at creation
+    bool memory_cache_total_accounted{false};
+    bool disk_cache_total_accounted{false};
+    TenantQuotaLedger quota_ledger;
+
+    struct DynamicReplicaRecord {
+        std::chrono::system_clock::time_point created_at;
+        std::string source_segment;
+        std::string target_segment;
+        std::string target_domain;
+        bool complete{false};
+    };
+
+    std::unordered_map<ReplicaID, DynamicReplicaRecord> dynamic_replicas;
+    std::chrono::steady_clock::time_point dynamic_replication_recreate_after{};
+
+    void MarkDynamicReplica(ReplicaID replica_id, DynamicReplicaRecord record) {
+        dynamic_replicas[replica_id] = std::move(record);
+    }
+
+    void MarkDynamicReplicasComplete(
+        const std::vector<ReplicaID>& replica_ids) {
+        for (const auto& replica_id : replica_ids) {
+            auto it = dynamic_replicas.find(replica_id);
+            if (it != dynamic_replicas.end()) {
+                it->second.complete = true;
+            }
+        }
+    }
+
+    size_t ForgetDynamicReplicas(const std::vector<ReplicaID>& replica_ids) {
+        size_t forgotten = 0;
+        for (const auto& replica_id : replica_ids) {
+            forgotten += dynamic_replicas.erase(replica_id);
+        }
+        return forgotten;
+    }
+
+    size_t DynamicReplicaCount() const { return dynamic_replicas.size(); }
+
+    bool DynamicReplicationRecreateBlocked(
+        std::chrono::steady_clock::time_point now) const {
+        return now < dynamic_replication_recreate_after;
+    }
+
+    void SetDynamicReplicationRecreateAfter(
+        std::chrono::steady_clock::time_point deadline) {
+        dynamic_replication_recreate_after =
+            std::max(dynamic_replication_recreate_after, deadline);
+    }
+
+    void AddReplicas(std::vector<Replica>&& replicas) {
+        replicas_.insert(replicas_.end(), std::move_iterator(replicas.begin()),
+                         std::move_iterator(replicas.end()));
+    }
+
+    std::vector<Replica> PopReplicas(
+        const std::function<bool(const Replica&)>& pred_fn) {
+        auto partition_point = std::partition(
+            replicas_.begin(), replicas_.end(),
+            [pred_fn](const Replica& replica) { return !pred_fn(replica); });
+
+        std::vector<Replica> popped_replicas;
+        if (partition_point != replicas_.end()) {
+            popped_replicas.reserve(
+                std::distance(partition_point, replicas_.end()));
+            std::move(partition_point, replicas_.end(),
+                      std::back_inserter(popped_replicas));
+            replicas_.erase(partition_point, replicas_.end());
+        }
+
+        return popped_replicas;
+    }
+
+    std::vector<Replica> PopReplicas() { return std::move(replicas_); }
+
+    size_t EraseReplicas(const std::function<bool(const Replica&)>& pred_fn) {
+        auto erased_replicas = PopReplicas(pred_fn);
+        return erased_replicas.size();
+    }
+
+    size_t EraseReplicas() {
+        auto erased_replicas = PopReplicas();
+        return erased_replicas.size();
+    }
+
+    size_t VisitReplicas(const std::function<bool(const Replica&)>& pred_fn,
+                         const std::function<void(Replica&)>& visit_fn) {
+        size_t num_visited = 0;
+
+        for (auto& replica : replicas_) {
+            if (pred_fn(replica)) {
+                visit_fn(replica);
+                num_visited++;
+            }
+        }
+
+        return num_visited;
+    }
+
+    size_t VisitReplicas(
+        const std::function<bool(const Replica&)>& pred_fn,
+        const std::function<void(const Replica&)>& visit_fn) const {
+        size_t num_visited = 0;
+
+        for (auto& replica : replicas_) {
+            if (pred_fn(replica)) {
+                visit_fn(replica);
+                num_visited++;
+            }
+        }
+
+        return num_visited;
+    }
+
+    bool HasReplica(const std::function<bool(const Replica&)>& pred_fn) const {
+        return std::any_of(replicas_.begin(), replicas_.end(), pred_fn);
+    }
+
+    bool AllReplicas(const std::function<bool(const Replica&)>& pred_fn) const {
+        return std::all_of(replicas_.begin(), replicas_.end(), pred_fn);
+    }
+
+    size_t CountReplicas(
+        const std::function<bool(const Replica&)>& pred_fn) const {
+        return std::count_if(replicas_.begin(), replicas_.end(), pred_fn);
+    }
+
+    size_t CountReplicas() const { return replicas_.size(); }
+
+    const std::vector<Replica>& GetAllReplicas() const { return replicas_; }
+
+    std::optional<ReplicaStatus> HasDiffRepStatus(ReplicaStatus status) const {
+        for (const auto& replica : replicas_) {
+            if (replica.status() != status) {
+                return replica.status();
+            }
+        }
+        return {};
+    }
+
+    Replica* GetFirstReplica(
+        const std::function<bool(const Replica&)>& pred_fn) {
+        const auto it =
+            std::find_if(replicas_.begin(), replicas_.end(), pred_fn);
+        return it != replicas_.end() ? &(*it) : nullptr;
+    }
+
+    Replica* GetReplicaByID(const ReplicaID& id) {
+        return GetFirstReplica(
+            [&id](const Replica& replica) { return replica.id() == id; });
+    }
+
+    bool EraseReplicaByID(const ReplicaID& id) {
+        auto num_erased = EraseReplicas(
+            [&id](const Replica& replica) { return replica.id() == id; });
+        return num_erased > 0;
+    }
+
+    size_t EraseReplica(ReplicaType replica_type) {
+        return EraseReplicas([replica_type](const Replica& replica) {
+            if (replica_type == ReplicaType::ALL) {
+                return replica.is_memory_replica() ||
+                       replica.is_nof_replica() || replica.is_dfs_replica();
+            }
+            return replica.type() == replica_type;
+        });
+    }
+
+    bool HasMemReplica() const {
+        return HasReplica(&Replica::fn_is_memory_replica);
+    }
+
+    bool HasNoFReplica() const {
+        return HasReplica(&Replica::fn_is_nof_replica);
+    }
+
+    size_t GetMemReplicaCount() const {
+        return CountReplicas(&Replica::fn_is_memory_replica);
+    }
+
+    size_t GetNoFReplicaCount() const {
+        return CountReplicas(&Replica::fn_is_nof_replica);
+    }
+
+    Replica* GetReplicaBySegmentName(const std::string& segment_name) {
+        return GetFirstReplica([&segment_name](const Replica& replica) {
+            auto names = replica.get_segment_names();
+            for (auto& name_opt : names) {
+                if (name_opt == segment_name) {
+                    return true;
+                }
+            }
+            return false;
+        });
+    }
+
+    // Grant a read lease at now() + ttl. Grouped objects extend the shared
+    // group TTL; a zero ttl is a no-op on a live lease (PutEnd cannot
+    // expire a live group).
+    void GrantReadLease(std::chrono::milliseconds ttl) const {
+        SpinLocker locker(&lock);
+        lease_->GrantReadLease(ttl);
+    }
+
+    // Whether the authoritative lease needs a refresh.
+    bool NeedsReadLeaseRefresh(std::chrono::milliseconds ttl) const {
+        SpinLocker locker(&lock);
+        const auto now = std::chrono::system_clock::now();
+        return lease_->ExpiresAt() <= now + ttl / 2;
+    }
+
+    // Whether the authoritative lease is expired.
+    bool IsLeaseExpired() const {
+        SpinLocker locker(&lock);
+        return lease_->IsExpired(std::chrono::system_clock::now());
+    }
+
+    bool IsLeaseExpired(std::chrono::system_clock::time_point& now) const {
+        SpinLocker locker(&lock);
+        return lease_->IsExpired(now);
+    }
+
+    // Lease deadline for the eviction census.
+    std::chrono::system_clock::time_point EvictionDeadline() const {
+        return lease_->ExpiresAt();
+    }
+
+    SoftPinEvaluation EvaluateSoftPin(
+        const std::chrono::system_clock::time_point& now) const {
+        SpinLocker locker(&lock);
+        if (soft_pin_timeout && now >= *soft_pin_timeout) {
+            const auto removed_deadline = *soft_pin_timeout;
+            soft_pin_timeout.reset();
+            return {.active = false,
+                    .metric_delta = -1,
+                    .removed_deadline = removed_deadline,
+                    .deadline_to_index = std::nullopt};
+        }
+        return {.active = soft_pin_timeout.has_value(),
+                .metric_delta = 0,
+                .removed_deadline = std::nullopt,
+                .deadline_to_index = std::nullopt};
+    }
+
+    bool ExpireSoftPinIfDeadlineMatches(
+        const std::chrono::system_clock::time_point& expected_deadline,
+        const std::chrono::system_clock::time_point& now) const {
+        SpinLocker locker(&lock);
+        if (!soft_pin_timeout || *soft_pin_timeout != expected_deadline ||
+            now < expected_deadline) {
+            return false;
+        }
+        soft_pin_timeout.reset();
+        return true;
+    }
+
+    // Saturates at the clock's maximum rather than overflowing when the TTL
+    // reaches past it. The comparison is done in milliseconds because
+    // converting a huge TTL up to the clock's finer period would overflow.
+    static std::chrono::system_clock::time_point ComputeSoftPinDeadline(
+        const std::chrono::system_clock::time_point& now,
+        std::chrono::milliseconds ttl) {
+        const auto max_time = std::chrono::system_clock::time_point::max();
+        const auto headroom = max_time - now;
+        const auto remaining =
+            std::chrono::duration_cast<std::chrono::milliseconds>(headroom);
+        return ttl > remaining ? max_time : now + ttl;
+    }
+
+    std::optional<std::chrono::system_clock::time_point>
+    GetCommittedSoftPinTimeout() const {
+        SpinLocker locker(&lock);
+        return soft_pin_timeout;
+    }
+
+    void BeginSoftPinAction(
+        const ResolvedSoftPinRequest& request,
+        std::unordered_set<ReplicaID> eligible_replica_ids) {
+        pending_soft_pin_action = PendingSoftPinAction{
+            request.action, request.ttl, std::move(eligible_replica_ids)};
+    }
+
+    bool PendingSoftPinOwnsReplica(ReplicaID replica_id) const {
+        if (!pending_soft_pin_action) {
+            return false;
+        }
+        return pending_soft_pin_action->eligible_replica_ids.contains(
+            replica_id);
+    }
+
+    void ClearPendingSoftPinAction() { pending_soft_pin_action.reset(); }
+
+    SoftPinEvaluation CommitPendingSoftPin(
+        const std::chrono::system_clock::time_point& now) {
+        if (!pending_soft_pin_action) {
+            return EvaluateSoftPin(now);
+        }
+
+        const PendingSoftPinAction pending =
+            std::move(*pending_soft_pin_action);
+        pending_soft_pin_action.reset();
+
+        SpinLocker locker(&lock);
+        int metric_delta = 0;
+        std::optional<std::chrono::system_clock::time_point> removed_deadline;
+        std::optional<std::chrono::system_clock::time_point> deadline_to_index;
+        if (soft_pin_timeout && now >= *soft_pin_timeout) {
+            removed_deadline = *soft_pin_timeout;
+            soft_pin_timeout.reset();
+            --metric_delta;
+        }
+
+        switch (pending.action) {
+            case SoftPinAction::PRESERVE:
+                break;
+            case SoftPinAction::ENABLE:
+                if (pending.ttl == std::chrono::milliseconds::zero()) {
+                    if (soft_pin_timeout) {
+                        removed_deadline = *soft_pin_timeout;
+                        soft_pin_timeout.reset();
+                        --metric_delta;
+                    }
+                } else {
+                    if (!soft_pin_timeout) {
+                        ++metric_delta;
+                    }
+                    soft_pin_timeout = ComputeSoftPinDeadline(now, pending.ttl);
+                    deadline_to_index = soft_pin_timeout;
+                    // Upserting the latest registration supersedes any
+                    // expired or previously active deadline.
+                    removed_deadline.reset();
+                }
+                break;
+            case SoftPinAction::DISABLE:
+                if (soft_pin_timeout) {
+                    removed_deadline = *soft_pin_timeout;
+                    soft_pin_timeout.reset();
+                    --metric_delta;
+                }
+                break;
+        }
+        return {.active = soft_pin_timeout.has_value(),
+                .metric_delta = metric_delta,
+                .removed_deadline = removed_deadline,
+                .deadline_to_index = deadline_to_index};
+    }
+
+    void ClearPendingSoftPinIfNoViableReplica() {
+        if (!pending_soft_pin_action) {
+            return;
+        }
+        const auto& eligible = pending_soft_pin_action->eligible_replica_ids;
+        const bool has_viable_replica = std::any_of(
+            replicas_.begin(), replicas_.end(),
+            [&eligible](const Replica& replica) {
+                const bool belongs_to_write = eligible.contains(replica.id());
+                const bool valid_handle = !replica.has_invalid_mem_handle() &&
+                                          !replica.has_invalid_nof_handle();
+                return belongs_to_write && replica.is_processing() &&
+                       valid_handle;
+            });
+        if (!has_viable_replica) {
+            pending_soft_pin_action.reset();
+        }
+    }
+
+    bool IsHardPinned() const { return hard_pinned; }
+
+    bool IsGrouped() const { return !group_id.empty(); }
+
+    // Check if the metadata is valid
+    // Valid means it has at least one valid replica and size is greater
+    // than 0
+    bool IsValid() const {
+        return size > 0 && HasReplica([](const Replica& replica) {
+                   return !replica.is_memory_replica() ||
+                          !replica.has_invalid_mem_handle();
+               });
+    }
+
+    std::vector<std::string> GetReplicaSegmentNames() const {
+        std::vector<std::string> segment_names;
+        for (const auto& replica : replicas_) {
+            const auto& segment_name_options = replica.get_segment_names();
+            for (const auto& segment_name_opt : segment_name_options) {
+                if (segment_name_opt.has_value()) {
+                    segment_names.push_back(segment_name_opt.value());
+                }
+            }
+        }
+        return segment_names;
+    }
+
+   private:
+    // Use the accessors to visit and modify the replicas.
+    std::vector<Replica> replicas_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/object_runtime_state.h b/mooncake-store/include/object_runtime_state.h
new file mode 100644
index 0000000000..8912bb416d
--- /dev/null
+++ b/mooncake-store/include/object_runtime_state.h
@@ -0,0 +1,127 @@
+#pragma once
+
+// Per-key runtime state records: the in-flight replication, offloading and
+// promotion bookkeeping that belongs to one object key. Moved out of
+// MasterService unchanged; each record is small state, not a container.
+
+#include <chrono>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "replica.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct DynamicReplicaPending {
+    UUID proposal_id{};
+    UUID lease_id{};
+    std::string source_segment;
+    std::string target_segment;
+    std::string target_domain;
+    uint64_t version_epoch{0};
+    int64_t expire_at_ms_epoch{0};
+    UUID task_id{};
+};
+
+struct ReplicationTask {
+    UUID client_id;
+    std::chrono::system_clock::time_point start_time;
+    enum class Type {
+        COPY,
+        MOVE,
+    } type;
+    ReplicaID source_id;
+    std::vector<ReplicaID> replica_ids;
+    uint64_t pending_quota_charge_bytes{0};
+    UUID dynamic_replication_lease_id{};
+    uint64_t dynamic_replication_version_epoch{0};
+    bool durable_cleanup_pending{false};
+};
+
+struct OffloadingTask {
+    ReplicaID source_id;
+    std::chrono::system_clock::time_point start_time;
+    // Clients whose LocalDiskSegment::offloading_objects hold a mirror
+    // for this key. One marker can cover several mirrors, since the
+    // offload is pushed once per completed MEMORY replica and those
+    // replicas may live on different clients.
+    std::vector<UUID> mirror_clients;
+};
+
+// Tracks an in-flight LOCAL_DISK -> MEMORY copy. The source
+// LOCAL_DISK replica is refcnt-pinned for the duration of the task
+// so it cannot be evicted.
+//
+// alloc_id pins down which staged PROCESSING MEMORY replica
+enum class PromotionQueueResult {
+    kQueued,
+    kDisabled,
+    kFrequencyRejected,
+    kWatermarkRejected,
+    kQueueCapRejected,
+    kAlreadyInFlight,
+    kMemoryReplicaPresent,
+    kNoLocalDiskSource,
+    kNotFound,
+    kPushFailed,
+};
+
+enum class PromotionCandidateReason {
+    kWatermark,
+    kQueueCap,
+    kPushFailed,
+    kExecutionFailed,
+};
+
+struct PromotionCandidate {
+    uint8_t sketch_score{0};
+    std::chrono::steady_clock::time_point first_seen;
+    std::chrono::steady_clock::time_point last_seen;
+    std::chrono::steady_clock::time_point retry_after;
+    PromotionCandidateReason last_reason{PromotionCandidateReason::kQueueCap};
+    ErrorCode last_error{ErrorCode::OK};
+    uint32_t retry_count{0};
+    // Execution failures in this admission chain (AllocStart / TE-write /
+    // SSD failures reported via NotifyPromotionFailure). Propagated into
+    // PromotionTask at admission so the bound survives the candidate's
+    // consumption; reset only when a genuinely new chain starts (fresh
+    // insert with 0, e.g. after a give-up or a success).
+    uint32_t execution_failures{0};
+};
+
+// NotifyPromotionSuccess should commit, so a concurrent Put on the
+// same key cannot be confused with ours. 0 until
+// PromotionAllocStart records the new replica.
+//
+// start_time is the reaper deadline anchor. Set at task admission
+// and reset at PromotionAllocStart so each phase (queue-wait and
+// active-transfer) gets its own full put_start_release_timeout_sec_
+// window. Without the reset a backlogged task could enter active
+// transfer with little TTL left, and the reaper could free the
+// staged replica via EraseReplicaByID mid-RDMA-write.
+//
+// holder_id is the client owning the source LOCAL_DISK segment and
+// the only one authorized to commit (NotifyPromotionSuccess) or
+// abort (NotifyPromotionFailure) the task. Without it, any client
+// knowing the key could flip the staged PROCESSING replica to
+// COMPLETE before the holder's RDMA write landed, exposing torn
+// data to readers.
+struct PromotionTask {
+    ReplicaID source_id;    // the LOCAL_DISK replica being promoted
+    ReplicaID alloc_id{0};  // the new MEMORY replica staged by AllocStart
+    uint64_t object_size;
+    uint64_t pending_quota_charge_bytes{0};
+    std::chrono::system_clock::time_point start_time;
+    UUID holder_id;  // owner of source LOCAL_DISK; only Notifier allowed
+    // Execution failures so far in this admission chain. Read by
+    // NotifyPromotionFailure before the task is erased and re-recorded as
+    // execution_failures+1 until kMaxPromotionExecutionFailures. Note the
+    // asymmetry with PromotionCandidate::execution_failures: admission
+    // copies candidate -> task verbatim, failure re-record writes
+    // task+1 -> candidate.
+    uint32_t execution_failures{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/offset_allocator/offset_allocator.h b/mooncake-store/include/offset_allocator/offset_allocator.h
index d6740119e9..1225bf782e 100644
--- a/mooncake-store/include/offset_allocator/offset_allocator.h
+++ b/mooncake-store/include/offset_allocator/offset_allocator.h
@@ -5,9 +5,12 @@
 #include <atomic>
 #include <memory>
 #include <optional>
+#include <string>
+#include <type_traits>
 #include <vector>
 #include <algorithm>
 #include <glog/logging.h>
+#include <ylt/util/tl/expected.hpp>
 
 #include "mutex.h"
 #include "serialize/serializer.h"
@@ -21,6 +24,7 @@ using NodeIndex = uint32;
 // Forward declarations
 class OffsetAllocator;
 class __Allocator;
+struct OffsetAllocatorSnapshot;
 
 static constexpr uint32 NUM_TOP_BINS = 32;
 static constexpr uint32 BINS_PER_LEAF = 8;
@@ -191,6 +195,15 @@ class OffsetAllocator : public std::enable_shared_from_this<OffsetAllocator> {
     [[nodiscard]]
     OffsetAllocatorMetrics get_metrics() const;
 
+    // Deep-copy persisted layout without locking. Only for a forked snapshot
+    // child or externally quiesced state; the result owns no live resources.
+    OffsetAllocatorSnapshot CaptureSnapshot() const;
+
+    // Consumes a captured snapshot and rebuilds the allocator from its layout.
+    // Validates before installing any state; returns a diagnostic on failure.
+    static tl::expected<std::shared_ptr<OffsetAllocator>, std::string> Restore(
+        OffsetAllocatorSnapshot snapshot);
+
     // Serialize the allocator with serializer.
     template <typename T>
     void serialize_to(T& serializer) const;
@@ -245,7 +258,10 @@ class OffsetAllocator : public std::enable_shared_from_this<OffsetAllocator> {
 class __Allocator {
    public:
     __Allocator(uint32 size, uint32 init_capacity, uint32 max_capacity);
+    // Excludes __Allocator itself, so copy construction never resolves to this
+    // serializer overload instead of the copy constructor.
     template <typename T>
+        requires(!std::is_same_v<std::remove_cvref_t<T>, __Allocator>)
     __Allocator(T& serializer) noexcept(false);
     __Allocator(__Allocator&& other);
     ~__Allocator() = default;
@@ -265,6 +281,9 @@ class __Allocator {
     void serialize_to(T& serializer) const;
 
    private:
+    // Detaches the bin/node state for OffsetAllocator::CaptureSnapshot().
+    __Allocator(const __Allocator&) = default;
+
     uint32 insertNodeIntoBin(uint32 size, uint32 dataOffset);
     void removeNodeFromBin(uint32 nodeIndex);
 
@@ -295,9 +314,58 @@ class __Allocator {
 
     friend class OffsetAllocatorTest;  // for unit tests
     friend class mooncake::Serializer<__Allocator>;
+    friend struct OffsetAllocatorSnapshot;
     friend class OffsetAllocator;  // for visit_used_nodes / createHandleAtNode
 };
 
+// Owned allocation metadata. No runtime allocator, handles or mutex are
+// retained. The internal bin/node layout is deeply copied during capture.
+struct OffsetAllocatorSnapshot {
+    uint64_t base;
+    uint64_t multiplier_bits;
+    uint64_t capacity;
+    uint64_t allocated_size;
+    uint64_t allocated_num;
+    std::unique_ptr<__Allocator> layout;
+
+    // The host-memory allocator supports up to 64Mi metadata nodes. This is
+    // independent of the smaller limit used by the storage backend's byte
+    // serializer, and must allow snapshots of large memory segments.
+    static constexpr uint32_t kMaxNodes = 1u << 26;
+
+    // Used by the wire decoder before allocating/decompressing node storage.
+    static tl::expected<void, std::string> ValidateNodeCapacity(
+        uint32_t size, uint32_t current_capacity, uint32_t max_capacity,
+        uint32_t free_offset);
+
+    // Pure validation: no runtime allocator, metrics, logging or mutation.
+    // Checks headers before shifts, then layout topology and usage accounting.
+    // Requested sizes are not persisted per node, so allocated_size must lie
+    // within the range permitted by bin/unit rounding, not equal occupied
+    // bytes.
+    [[nodiscard]] tl::expected<void, std::string> Validate() const;
+
+   private:
+    enum class NodeState : uint8_t { kUnclassified, kUsed, kFree, kSpare };
+    struct LayoutUsage {
+        uint64_t used_nodes = 0;
+        uint64_t min_used_bytes = 0;
+        uint64_t max_used_bytes = 0;
+    };
+
+    tl::expected<void, std::string> ValidateHeader() const;
+    tl::expected<LayoutUsage, std::string> ValidateUsedNodes(
+        std::vector<NodeState>& state) const;
+    tl::expected<uint32_t, std::string> ValidateBins(
+        std::vector<NodeState>& state) const;
+    tl::expected<void, std::string> ValidateFreeStack(
+        std::vector<NodeState>& state, uint32_t live_nodes) const;
+    tl::expected<void, std::string> ValidateNeighborChain(
+        const std::vector<NodeState>& state, uint32_t live_nodes) const;
+    tl::expected<void, std::string> ValidateAccounting(
+        const LayoutUsage& usage) const;
+};
+
 // Template method implementations
 template <typename T>
 void OffsetAllocator::serialize_to(T& serializer) const {
@@ -381,6 +449,7 @@ void __Allocator::serialize_to(T& serializer) const {
 }
 
 template <typename T>
+    requires(!std::is_same_v<std::remove_cvref_t<T>, __Allocator>)
 __Allocator::__Allocator(T& serializer) {
     // serializer.read() will throw an exception if the buffer is corrupted.
     try {
diff --git a/mooncake-store/include/pinned_buffer_pool.h b/mooncake-store/include/pinned_buffer_pool.h
index 25461f7d1f..5f50dde1d5 100644
--- a/mooncake-store/include/pinned_buffer_pool.h
+++ b/mooncake-store/include/pinned_buffer_pool.h
@@ -80,7 +80,6 @@ class PinnedBufferPool {
             for (size_t i = 0; i < pool_.size(); ++i) {
                 if (pool_[i].capacity >= size) {
                     Buffer buf = std::move(pool_[i]);
-                    // O(1) erase: swap with back then pop
                     if (i != pool_.size() - 1) {
                         pool_[i] = std::move(pool_.back());
                     }
@@ -92,6 +91,17 @@ class PinnedBufferPool {
         return AllocNew(size);
     }
 
+    // Never falls back to pageable memory.
+    static Buffer AllocatePinned(size_t size) {
+        auto accelerators =
+            device::GetAcceleratorRegistry().RuntimeAccelerators();
+        for (auto* accelerator : accelerators.Devices()) {
+            auto host = accelerator->AllocatePinnedHost(size);
+            if (host.addr) return Buffer(std::move(host));
+        }
+        return {};
+    }
+
     void Release(Buffer buf) {
         std::lock_guard<std::mutex> lk(mutex_);
         if (pool_.size() < max_pool_size_) {
@@ -112,12 +122,8 @@ class PinnedBufferPool {
 
    private:
     static Buffer AllocNew(size_t size) {
-        const auto& registry = device::GetAcceleratorRegistry();
-        auto runtime_accelerator = registry.RuntimeAccelerators();
-        for (auto* accelerator : runtime_accelerator.Devices()) {
-            auto host = accelerator->AllocatePinnedHost(size);
-            if (host.addr) return Buffer(std::move(host));
-        }
+        auto pinned = AllocatePinned(size);
+        if (pinned.data) return pinned;
         return Buffer::Pageable(size);
     }
 
diff --git a/mooncake-store/include/placement/candidate.h b/mooncake-store/include/placement/candidate.h
new file mode 100644
index 0000000000..90d23a70c9
--- /dev/null
+++ b/mooncake-store/include/placement/candidate.h
@@ -0,0 +1,46 @@
+#pragma once
+
+#include <cstddef>
+#include <memory>
+#include <utility>
+
+#include "allocator.h"
+
+namespace mooncake {
+
+enum class AllocationCandidateKind {
+    NATIVE = 0,
+    CXL,
+};
+
+inline constexpr size_t kAllocationCandidateKindCount =
+    static_cast<size_t>(AllocationCandidateKind::CXL) + 1;
+
+// A stable allocation endpoint published to PlacementIndex. RegionResource
+// owns the candidate and must outlive every placement reference to it.
+class AllocationCandidate {
+   public:
+    virtual ~AllocationCandidate() = default;
+
+    virtual std::unique_ptr<AllocatedBuffer> Allocate(size_t size) const = 0;
+    virtual AllocationCandidateKind Kind() const noexcept = 0;
+
+    size_t Capacity() const { return allocator_->capacity(); }
+    size_t Used() const { return allocator_->size(); }
+
+    const std::shared_ptr<BufferAllocatorBase>& allocator_handle()
+        const noexcept {
+        return allocator_;
+    }
+
+   protected:
+    explicit AllocationCandidate(std::shared_ptr<BufferAllocatorBase> allocator)
+        : allocator_(std::move(allocator)) {}
+
+    BufferAllocatorBase& allocator() const noexcept { return *allocator_; }
+
+   private:
+    std::shared_ptr<BufferAllocatorBase> allocator_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/placement/index.h b/mooncake-store/include/placement/index.h
new file mode 100644
index 0000000000..2b72a68d7a
--- /dev/null
+++ b/mooncake-store/include/placement/index.h
@@ -0,0 +1,133 @@
+#pragma once
+
+#include <array>
+#include <boost/container/flat_set.hpp>
+#include <boost/container/flat_map.hpp>
+#include <cassert>
+#include <cstddef>
+#include <functional>
+#include <map>
+#include <memory>
+#include <optional>
+#include <set>
+#include <shared_mutex>
+#include <span>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+#include "placement/candidate.h"
+#include "types.h"
+#include "common/transparent_string_hash.h"
+
+namespace mooncake {
+
+class PlacementIndex final {
+   public:
+    // One (segment_name, kind) entry. Candidates are interchangeable for one
+    // allocation; multi-replica placement uses each entry at most once.
+    struct Entry final {
+        std::string segment_name;
+        const AllocationCandidateKind kind;
+        boost::container::flat_set<const AllocationCandidate*> candidates;
+    };
+
+    PlacementIndex() = default;
+    PlacementIndex(PlacementIndex&&) = default;
+    PlacementIndex& operator=(PlacementIndex&&) = default;
+    PlacementIndex(const PlacementIndex&) = delete;
+    PlacementIndex& operator=(const PlacementIndex&) = delete;
+
+    // A candidate keeps the same segment name and host identity until removed.
+    bool AddCandidate(std::string_view segment_name,
+                      const AllocationCandidate& candidate,
+                      std::string_view host_id);
+    bool RemoveCandidate(std::string_view segment_name,
+                         const AllocationCandidate& candidate,
+                         std::string_view host_id);
+    bool ReplaceCandidate(std::string_view segment_name,
+                          const AllocationCandidate& expected,
+                          const AllocationCandidate& replacement,
+                          std::string_view host_id);
+    void Clear();
+
+    // Visit unique names in host/key order under the read lock. Returning
+    // true stops traversal. Borrowed names remain valid only under this lock.
+    void VisitHostOrderedSegmentNames(
+        std::string_view writer_host_id, std::string_view key,
+        const std::function<bool(std::string_view)>& visit) const;
+    const Entry* Find(std::string_view segment_name,
+                      AllocationCandidateKind kind) const;
+    bool Contains(std::string_view segment_name,
+                  AllocationCandidateKind kind) const {
+        return Find(segment_name, kind) != nullptr;
+    }
+    void GetActiveSegmentNames(AllocationCandidateKind kind,
+                               std::vector<std::string>& names) const;
+    std::span<const Entry* const> active_entries(
+        AllocationCandidateKind kind) const {
+        return entries_by_kind_[KindIndex(kind)].ActiveEntries();
+    }
+
+   private:
+    static constexpr size_t KindIndex(AllocationCandidateKind kind) noexcept {
+        const auto index = static_cast<size_t>(kind);
+        assert(index < kAllocationCandidateKindCount);
+        return index;
+    }
+
+    void AddHostMember(std::string_view host_id, std::string_view segment_name);
+    void RemoveHostMember(std::string_view host_id,
+                          std::string_view segment_name);
+
+    // Counts span kinds and regions. A name remains until its last active
+    // candidate on this host is removed. flat_map provides indexed name access.
+    using HostSegments =
+        boost::container::flat_map<std::string, size_t, std::less<>>;
+    std::map<std::string, HostSegments, std::less<>> segments_by_host_;
+
+    // Both views contain the same active entries; inactive regions live in
+    // RegionCatalog. EntryMap owns their lifetime and keeps the views in sync.
+    class EntryMap final {
+       public:
+        Entry* Find(std::string_view name);
+        const Entry* Find(std::string_view name) const;
+        void Insert(std::unique_ptr<Entry> entry) noexcept;
+        void Erase(const Entry& entry);
+        void Clear();
+        std::span<const Entry* const> ActiveEntries() const { return active_; }
+
+       private:
+        std::unordered_map<std::string, std::unique_ptr<Entry>,
+                           TransparentStringHash, std::equal_to<>>
+            by_name_;
+        std::vector<const Entry*> active_;
+    };
+    std::array<EntryMap, kAllocationCandidateKindCount> entries_by_kind_;
+};
+
+class RegionCatalog;
+
+// Borrows the indexes and holds their shared lock. The owner of the indexes
+// and mutex must outlive this access object.
+class ScopedPlacementReadAccess final {
+   public:
+    ScopedPlacementReadAccess(const PlacementIndex& placement,
+                              const RegionCatalog& catalog,
+                              std::shared_mutex& mutex)
+        : placement_(placement), catalog_(catalog), lock_(mutex) {}
+
+    // The view and entries borrowed from it must only be used while this
+    // access object retains its lock.
+    const PlacementIndex& GetView() const { return placement_; }
+
+    std::optional<UUID> GetOwnerClientId(std::string_view segment_name) const;
+
+   private:
+    const PlacementIndex& placement_;
+    const RegionCatalog& catalog_;
+    std::shared_lock<std::shared_mutex> lock_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/placement/replica_allocator.h b/mooncake-store/include/placement/replica_allocator.h
new file mode 100644
index 0000000000..f2bc9521c2
--- /dev/null
+++ b/mooncake-store/include/placement/replica_allocator.h
@@ -0,0 +1,128 @@
+#pragma once
+
+#include <concepts>
+#include <cstddef>
+#include <optional>
+#include <span>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "placement/candidate.h"
+#include "replica.h"
+#include "types.h"
+
+namespace mooncake {
+
+class LocalSsdManager;
+class ScopedPlacementReadAccess;
+
+class LocalSSDMetricsView final {
+   public:
+    explicit LocalSSDMetricsView(const LocalSsdManager& local_ssd)
+        : local_ssd_(local_ssd) {}
+
+    std::optional<double> GetFreeRatio(const UUID& client_id) const;
+
+   private:
+    const LocalSsdManager& local_ssd_;
+};
+
+struct ReplicaRequirements final {
+    size_t size{0};
+    size_t count{1};
+    ReplicaType type{ReplicaType::MEMORY};
+};
+
+struct PlacementConstraints final {
+    std::string_view preferred_segment_name;
+    std::span<const std::string> preferred_segment_names;
+    std::span<const std::string> excluded_segment_names;
+};
+
+struct HostAffinity final {
+    std::string_view writer_host_id;
+    std::string_view object_key;
+};
+
+struct ReplicaAllocationRequest final {
+    ReplicaRequirements replicas;
+    PlacementConstraints placement;
+    HostAffinity host_affinity;
+};
+
+struct PlacementDiagnostics final {
+    bool has_sufficient_active_entry_count{false};
+};
+
+struct RandomPlacementPolicy final {};
+struct FreeRatioFirstPlacementPolicy final {};
+struct LocalFirstPlacementPolicy final {};
+
+struct PreferredOnlyPlacementPolicy final {
+    explicit PreferredOnlyPlacementPolicy(AllocationCandidateKind required_kind)
+        : required_kind(required_kind) {}
+
+    AllocationCandidateKind required_kind;
+};
+
+struct SsdFreeRatioFirstPlacementPolicy final {
+    explicit SsdFreeRatioFirstPlacementPolicy(LocalSSDMetricsView metrics_view)
+        : metrics(std::move(metrics_view)) {}
+
+    LocalSSDMetricsView metrics;
+};
+
+template <typename Policy>
+concept ReplicaPlacementPolicy =
+    std::same_as<Policy, RandomPlacementPolicy> ||
+    std::same_as<Policy, FreeRatioFirstPlacementPolicy> ||
+    std::same_as<Policy, SsdFreeRatioFirstPlacementPolicy> ||
+    std::same_as<Policy, LocalFirstPlacementPolicy> ||
+    std::same_as<Policy, PreferredOnlyPlacementPolicy>;
+
+template <ReplicaPlacementPolicy Policy>
+class ReplicaAllocator final {
+   public:
+    explicit ReplicaAllocator(Policy policy) : policy_(std::move(policy)) {}
+
+    tl::expected<std::vector<Replica>, ErrorCode> Allocate(
+        ScopedPlacementReadAccess& placement,
+        const ReplicaAllocationRequest& request,
+        PlacementDiagnostics* diagnostics = nullptr) const;
+
+    // Allocates only in the named segment. PreferredOnly uses its required
+    // kind; other policies use native memory. No segment or kind fallback.
+    tl::expected<Replica, ErrorCode> AllocateFrom(
+        ScopedPlacementReadAccess& placement, size_t size,
+        std::string_view segment_name,
+        ReplicaType replica_type = ReplicaType::MEMORY) const;
+
+    static constexpr bool UsesHostAffinity() noexcept {
+        return std::same_as<Policy, LocalFirstPlacementPolicy>;
+    }
+
+   private:
+    Policy policy_;
+};
+
+extern template class ReplicaAllocator<RandomPlacementPolicy>;
+extern template class ReplicaAllocator<FreeRatioFirstPlacementPolicy>;
+extern template class ReplicaAllocator<SsdFreeRatioFirstPlacementPolicy>;
+extern template class ReplicaAllocator<LocalFirstPlacementPolicy>;
+extern template class ReplicaAllocator<PreferredOnlyPlacementPolicy>;
+
+inline RandomPlacementPolicy MakeNoFPlacementPolicy(
+    const SsdFreeRatioFirstPlacementPolicy&) {
+    return {};
+}
+
+template <ReplicaPlacementPolicy Policy>
+Policy MakeNoFPlacementPolicy(const Policy& memory_policy) {
+    return memory_policy;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/pyclient.h b/mooncake-store/include/pyclient.h
index 4219ae6202..08f9aa54b1 100644
--- a/mooncake-store/include/pyclient.h
+++ b/mooncake-store/include/pyclient.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#include <algorithm>
 #include <atomic>
 #include <chrono>
 #include <csignal>
@@ -14,7 +15,7 @@
 #include "client_service.h"
 #include "client_buffer.h"
 #include "mutex.h"
-#include "utils.h"
+#include "common/result.h"
 #include "file_storage.h"
 
 namespace mooncake {
@@ -143,6 +144,10 @@ class ClientRequester {
    public:
     ClientRequester();
 
+    // Drains in-flight offload RPCs before the pools member is released
+    // (#3909).
+    ~ClientRequester();
+
     /**
      * @brief Retrieves multiple objects from a remote Transfer Engine (TE)
      * @param client_addr Network address (e.g., "ip:port") of the remote
@@ -194,6 +199,7 @@ class ClientRequester {
     mutable std::shared_mutex client_pool_mutex_;
     std::shared_ptr<coro_io::client_pools<coro_rpc::coro_rpc_client>>
         client_pools_;
+    RpcDrainGuard rpc_drain_;
 
     /**
      * @brief Generic RPC invocation helper for single-result operations
@@ -217,6 +223,78 @@ class PyClient {
     using QueryResultCache =
         std::unordered_map<std::string, tl::expected<QueryResult, ErrorCode>>;
 
+    // A caller-owned metadata snapshot for repeated ranged reads against the
+    // same key set. It is reusable until refresh_at; after that, callers should
+    // refresh it before submitting more transfers.
+    struct RangedReadSnapshot {
+        QueryResultCache query_result_cache;
+        std::chrono::steady_clock::time_point refresh_at{};
+
+        bool reset(QueryResultCache cache,
+                   std::chrono::steady_clock::time_point now =
+                       std::chrono::steady_clock::now()) {
+            query_result_cache = std::move(cache);
+            refresh_at = now;
+            if (query_result_cache.empty()) return false;
+
+            auto earliest_lease = std::chrono::steady_clock::time_point::max();
+            bool all_fresh = true;
+            for (const auto &[key, query_result] : query_result_cache) {
+                (void)key;
+                if (query_result && !query_result->IsLeaseExpired(now)) {
+                    earliest_lease =
+                        std::min(earliest_lease, query_result->lease_timeout);
+                } else {
+                    all_fresh = false;
+                }
+            }
+            if (all_fresh && earliest_lease > now) {
+                refresh_at = now + (earliest_lease - now) / 2;
+            }
+            return all_fresh;
+        }
+
+        bool reset(
+            const std::vector<std::string> &keys,
+            std::vector<tl::expected<QueryResult, ErrorCode>> query_results,
+            std::chrono::steady_clock::time_point now =
+                std::chrono::steady_clock::now()) {
+            query_result_cache.clear();
+            refresh_at = now;
+            if (query_results.size() != keys.size()) return false;
+
+            query_result_cache.reserve(keys.size());
+            auto earliest_lease = std::chrono::steady_clock::time_point::max();
+            bool all_fresh = true;
+            for (size_t i = 0; i < keys.size(); ++i) {
+                if (query_results[i] &&
+                    !query_results[i]->IsLeaseExpired(now)) {
+                    earliest_lease = std::min(earliest_lease,
+                                              query_results[i]->lease_timeout);
+                } else {
+                    all_fresh = false;
+                }
+                query_result_cache.emplace(keys[i],
+                                           std::move(query_results[i]));
+            }
+
+            if (all_fresh && earliest_lease > now) {
+                refresh_at = now + (earliest_lease - now) / 2;
+            }
+            return all_fresh;
+        }
+
+        bool reusable(std::chrono::steady_clock::time_point now =
+                          std::chrono::steady_clock::now()) const {
+            return !query_result_cache.empty() && now < refresh_at;
+        }
+
+        bool should_refresh(std::chrono::steady_clock::time_point now =
+                                std::chrono::steady_clock::now()) const {
+            return !reusable(now);
+        }
+    };
+
     virtual ~PyClient() = 0;
     virtual int setup_real(
         const std::string &local_hostname, const std::string &metadata_server,
@@ -261,9 +339,46 @@ class PyClient {
         const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
         const QueryResultCache *query_result_cache = nullptr) = 0;
 
+    // Read only from the supplied query-result snapshot. Implementations must
+    // not re-query keys or renew leases; an expired snapshot fails.
+    virtual std::vector<std::vector<std::vector<int64_t>>>
+    get_into_ranges_from_snapshot(
+        const std::vector<void *> &buffers,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const QueryResultCache &query_result_cache) = 0;
+
+    std::vector<std::vector<std::vector<int64_t>>>
+    get_into_ranges_from_snapshot(
+        const std::vector<void *> &buffers,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const RangedReadSnapshot &snapshot) {
+        return get_into_ranges_from_snapshot(buffers, all_keys, all_dst_offsets,
+                                             all_src_offsets, all_sizes,
+                                             snapshot.query_result_cache);
+    }
+
     virtual std::vector<tl::expected<QueryResult, ErrorCode>> batch_query(
         const std::vector<std::string> &keys) = 0;
 
+    RangedReadSnapshot prepare_get_into_ranges_snapshot(
+        const std::vector<std::string> &keys) {
+        RangedReadSnapshot snapshot;
+        refresh_get_into_ranges_snapshot(snapshot, keys);
+        return snapshot;
+    }
+
+    bool refresh_get_into_ranges_snapshot(
+        RangedReadSnapshot &snapshot, const std::vector<std::string> &keys) {
+        auto query_results = batch_query(keys);
+        return snapshot.reset(keys, std::move(query_results));
+    }
+
     virtual std::vector<int64_t> batch_get_into(
         const std::vector<std::string> &keys,
         const std::vector<void *> &buffers,
@@ -294,6 +409,57 @@ class PyClient {
         const std::vector<std::vector<size_t>> &all_sizes,
         const ReplicateConfig &config = ReplicateConfig{}) = 0;
 
+    // Put/get sessions. Default stubs keep DummyClient unchanged; RealClient
+    // overrides with the real implementations.
+    virtual std::vector<int> batch_get_session_start(
+        const std::vector<std::string> &keys) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    virtual std::vector<int> batch_get_into_multi_buffer_ranges(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> & /*all_buffers*/,
+        const std::vector<std::vector<size_t>> & /*all_sizes*/,
+        const std::vector<std::vector<size_t>> & /*all_src_offsets*/) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    virtual int batch_get_session_end(
+        const std::vector<std::string> & /*keys*/) {
+        return static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+    }
+
+    virtual std::vector<int> batch_put_session_start(
+        const std::vector<std::string> &keys,
+        const std::vector<size_t> & /*sizes*/,
+        const ReplicateConfig & /*config*/ = ReplicateConfig{}) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    virtual std::vector<int> batch_put_from_multi_buffer_ranges(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> & /*all_buffers*/,
+        const std::vector<std::vector<size_t>> & /*all_sizes*/,
+        const std::vector<std::vector<size_t>> & /*all_dst_offsets*/) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    virtual std::vector<int> batch_put_session_end(
+        const std::vector<std::string> &keys) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    virtual std::vector<int> batch_put_session_revoke(
+        const std::vector<std::string> &keys) {
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
     virtual std::shared_ptr<BufferHandle> get_buffer(
         const std::string &key) = 0;
 
@@ -321,6 +487,12 @@ class PyClient {
         const std::vector<void *> &buffers, const std::vector<size_t> &sizes,
         const ReplicateConfig &config = ReplicateConfig{}) = 0;
 
+    virtual std::vector<int> batch_upsert_from_multi_buffers(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config = ReplicateConfig{}) = 0;
+
     virtual int upsert_parts(
         const std::string &key, std::vector<std::span<const char>> values,
         const ReplicateConfig &config = ReplicateConfig{}) = 0;
@@ -346,6 +518,14 @@ class PyClient {
     virtual std::vector<int> batchIsExist(
         const std::vector<std::string> &keys) = 0;
 
+    // Point-in-time existence check that grants no read lease: 1 if the
+    // object existed at the time of the call, 0 if not, negative on error.
+    // The object may still be evicted before a subsequent get.
+    virtual int probeKey(const std::string &key) = 0;
+
+    virtual std::vector<int> batchProbeKey(
+        const std::vector<std::string> &keys) = 0;
+
     virtual int64_t getSize(const std::string &key) = 0;
 
     virtual std::map<std::string, std::vector<Replica::Descriptor>>
@@ -418,7 +598,8 @@ inline tl::expected<QueryResult, ErrorCode> from_cached_query_result_response(
     if (!cached_result.success) {
         return tl::make_unexpected(cached_result.error);
     }
-    return QueryResult(
+    return tl::expected<QueryResult, ErrorCode>(
+        tl::in_place,
         std::vector<Replica::Descriptor>(cached_result.value.replicas.begin(),
                                          cached_result.value.replicas.end()),
         now + std::chrono::milliseconds(cached_result.value.lease_ttl_ms),
diff --git a/mooncake-store/include/real_client.h b/mooncake-store/include/real_client.h
index 89bf4a4c4e..d9417dfefc 100644
--- a/mooncake-store/include/real_client.h
+++ b/mooncake-store/include/real_client.h
@@ -2,7 +2,10 @@
 
 #include <atomic>
 #include <boost/lockfree/queue.hpp>
+#include <chrono>
+#include <condition_variable>
 #include <csignal>
+#include <functional>
 #include <map>
 #include <memory>
 #include <shared_mutex>
@@ -12,12 +15,13 @@
 #include <unordered_set>
 #include <vector>
 
-#include "pyclient.h"
-#include "client_service.h"
+#include "common/client_buffer_allocation.h"
 #include "client_buffer.h"
+#include "client_service.h"
 #include "device/cuda_ipc_buffer_handle.h"
 #include "mutex.h"
-#include "utils.h"
+#include "common/network.h"
+#include "pyclient.h"
 #include "rpc_types.h"
 #if defined(USE_SUNRISE)
 #include "sunrise_allocator.h"
@@ -143,6 +147,17 @@ class RealClient : public PyClient {
         const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
         const QueryResultCache *query_result_cache = nullptr) override;
 
+    // Read only from the supplied snapshot. Never re-query a key or renew a
+    // lease: an expired snapshot fails with LEASE_EXPIRED.
+    std::vector<std::vector<std::vector<int64_t>>>
+    get_into_ranges_from_snapshot(
+        const std::vector<void *> &buffers,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const QueryResultCache &query_result_cache) override;
+
     /**
      * @brief Batch query object placement/lease metadata for later read reuse
      * @param keys Vector of keys to query
@@ -243,6 +258,38 @@ class RealClient : public PyClient {
         const std::vector<std::vector<void *>> &all_buffers,
         const std::vector<std::vector<size_t>> &all_sizes,
         const ReplicateConfig &config = ReplicateConfig{});
+    std::vector<int> batch_put_from_multi_buffers(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config, bool stage_nonlocal);
+
+    std::vector<int> batch_get_session_start(
+        const std::vector<std::string> &keys) override;
+
+    std::vector<int> batch_get_into_multi_buffer_ranges(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const std::vector<std::vector<size_t>> &all_src_offsets) override;
+
+    int batch_get_session_end(const std::vector<std::string> &keys) override;
+
+    std::vector<int> batch_put_session_start(
+        const std::vector<std::string> &keys, const std::vector<size_t> &sizes,
+        const ReplicateConfig &config = ReplicateConfig{}) override;
+
+    std::vector<int> batch_put_from_multi_buffer_ranges(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const std::vector<std::vector<size_t>> &all_dst_offsets) override;
+
+    std::vector<int> batch_put_session_end(
+        const std::vector<std::string> &keys) override;
+
+    std::vector<int> batch_put_session_revoke(
+        const std::vector<std::string> &keys) override;
 
     int put_parts(const std::string &key,
                   std::vector<std::span<const char>> values,
@@ -257,12 +304,22 @@ class RealClient : public PyClient {
 
     int upsert_from(const std::string &key, void *buffer, size_t size,
                     const ReplicateConfig &config = ReplicateConfig{});
-
     std::vector<int> batch_upsert_from(
         const std::vector<std::string> &keys,
         const std::vector<void *> &buffers, const std::vector<size_t> &sizes,
         const ReplicateConfig &config = ReplicateConfig{});
 
+    std::vector<int> batch_upsert_from_multi_buffers(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config = ReplicateConfig{});
+    std::vector<int> batch_upsert_from_multi_buffers(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config, bool stage_nonlocal);
+
     int upsert_parts(const std::string &key,
                      std::vector<std::span<const char>> values,
                      const ReplicateConfig &config = ReplicateConfig{});
@@ -318,6 +375,23 @@ class RealClient : public PyClient {
      */
     std::vector<int> batchIsExist(const std::vector<std::string> &keys);
 
+    /**
+     * @brief Point-in-time existence check that grants no read lease
+     * @param key Key to check
+     * @return 1 if exists, 0 if not exists, -1 if error. The object may
+     * still be evicted before a subsequent get.
+     */
+    int probeKey(const std::string &key);
+
+    /**
+     * @brief Point-in-time existence check for multiple objects, granting
+     * no read leases
+     * @param keys Vector of keys to check
+     * @return Vector of existence results: 1 if exists, 0 if not exists, -1
+     * if error
+     */
+    std::vector<int> batchProbeKey(const std::vector<std::string> &keys);
+
     /**
      * @brief Get the size of an object
      * @param key Key of the object
@@ -454,10 +528,23 @@ class RealClient : public PyClient {
         const std::vector<CudaIpcWriteRequest> &requests,
         const ReplicateConfig &config, const UUID &client_id);
 
+    std::vector<tl::expected<void, ErrorCode>>
+    batch_upsert_from_cuda_ipc_dummy_helper(
+        const std::vector<CudaIpcWriteRequest> &requests,
+        const ReplicateConfig &config, const UUID &client_id);
+
     std::vector<tl::expected<int64_t, ErrorCode>>
     batch_get_into_cuda_ipc_dummy_helper(
         const std::vector<CudaIpcReadRequest> &requests, const UUID &client_id);
 
+    std::vector<tl::expected<void, ErrorCode>>
+    batch_upsert_from_multi_buffers_dummy_helper(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<uint64_t>> &dummy_all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config, int32_t device_id,
+        const UUID &client_id);
+
     std::vector<tl::expected<int64_t, ErrorCode>>
     batch_get_into_multi_buffers_dummy_helper(
         const std::vector<std::string> &keys,
@@ -482,6 +569,18 @@ class RealClient : public PyClient {
             &cached_query_results,
         int32_t device_id, const UUID &client_id);
 
+    std::vector<std::vector<std::vector<tl::expected<int64_t, ErrorCode>>>>
+    get_into_ranges_staged_shm_helper(
+        const std::vector<uint64_t> &dummy_buffers,
+        const std::vector<size_t> &dummy_buffer_sizes,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const std::map<std::string, CachedQueryResultResponse>
+            &cached_query_results,
+        int32_t device_id, const UUID &client_id);
+
     // Share mem management for dummy client
     // Modified: map_shm_internal now takes fd instead of just name
     tl::expected<void, ErrorCode> map_shm_internal(int fd,
@@ -563,7 +662,8 @@ class RealClient : public PyClient {
 
     tl::expected<RangedReadMetadata, ErrorCode> resolve_ranged_read_metadata(
         const std::string &key,
-        const QueryResultCache *query_result_cache = nullptr);
+        const QueryResultCache *query_result_cache = nullptr,
+        bool allow_query_refresh = true);
 
     tl::expected<int64_t, ErrorCode> execute_ranged_read(
         const std::string &key, void *buffer, size_t dst_offset,
@@ -583,12 +683,26 @@ class RealClient : public PyClient {
         const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
         const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
         const std::vector<size_t> *buffer_capacities = nullptr,
-        const QueryResultCache *query_result_cache = nullptr);
+        const QueryResultCache *query_result_cache = nullptr,
+        bool allow_query_refresh = true);
 
     std::vector<tl::expected<int64_t, ErrorCode>> batch_get_into_internal(
         const std::vector<std::string> &keys,
         const std::vector<void *> &buffers, const std::vector<size_t> &sizes);
 
+    using LocalDiskOffloadObjects =
+        std::unordered_map<std::string, std::vector<Slice>>;
+    using LocalDiskOffloadReader = std::function<tl::expected<void, ErrorCode>(
+        const std::string &, LocalDiskOffloadObjects &)>;
+
+    // Dependency-injected overload used to verify routing decisions without
+    // requiring multiple live SSD offload servers.
+    std::vector<tl::expected<int64_t, ErrorCode>> batch_get_into_internal(
+        const std::vector<std::string> &keys,
+        const std::vector<void *> &buffers, const std::vector<size_t> &sizes,
+        const std::vector<tl::expected<QueryResult, ErrorCode>> &query_results,
+        const LocalDiskOffloadReader &local_disk_reader);
+
     std::vector<tl::expected<int64_t, ErrorCode>>
     batch_get_into_multi_buffers_internal(
         const std::vector<std::string> &keys,
@@ -609,12 +723,19 @@ class RealClient : public PyClient {
     tl::expected<void, ErrorCode> upsert_from_internal(
         const std::string &key, void *buffer, size_t size,
         const ReplicateConfig &config = ReplicateConfig{});
-
     std::vector<tl::expected<void, ErrorCode>> batch_upsert_from_internal(
         const std::vector<std::string> &keys,
         const std::vector<void *> &buffers, const std::vector<size_t> &sizes,
         const ReplicateConfig &config = ReplicateConfig{});
 
+    std::vector<tl::expected<void, ErrorCode>>
+    batch_upsert_from_multi_buffers_internal(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const ReplicateConfig &config = ReplicateConfig{},
+        bool stage_nonlocal = false);
+
     tl::expected<void, ErrorCode> upsert_parts_internal(
         const std::string &key, std::vector<std::span<const char>> values,
         const ReplicateConfig &config = ReplicateConfig{},
@@ -638,7 +759,8 @@ class RealClient : public PyClient {
         const std::vector<std::string> &keys,
         const std::vector<std::vector<void *>> &all_buffers,
         const std::vector<std::vector<size_t>> &all_sizes,
-        const ReplicateConfig &config = ReplicateConfig{});
+        const ReplicateConfig &config = ReplicateConfig{},
+        bool stage_nonlocal = false);
 
     tl::expected<void, ErrorCode> put_parts_internal(
         const std::string &key,
@@ -672,6 +794,11 @@ class RealClient : public PyClient {
     std::vector<tl::expected<bool, ErrorCode>> batchIsExist_internal(
         const std::vector<std::string> &keys);
 
+    tl::expected<bool, ErrorCode> probeKey_internal(const std::string &key);
+
+    std::vector<tl::expected<bool, ErrorCode>> batchProbeKey_internal(
+        const std::vector<std::string> &keys);
+
     tl::expected<int64_t, ErrorCode> getSize_internal(const std::string &key);
 
     std::shared_ptr<BufferHandle> get_buffer_internal(
@@ -715,9 +842,20 @@ class RealClient : public PyClient {
      "ip:port").
 
      */
+    struct OffloadReadRange {
+        uint64_t source_offset;
+        int64_t restore_size;
+    };
+
     tl::expected<void, ErrorCode> batch_get_into_offload_object_internal(
         const std::string &target_rpc_service_addr,
-        std::unordered_map<std::string, std::vector<Slice>> &objects);
+        std::unordered_map<std::string, std::vector<Slice>> &objects,
+        const OffloadReadRange *read_range = nullptr);
+
+    bool can_use_pinned_restore_arena(
+        const std::string &target_rpc_service_addr,
+        const std::unordered_map<std::string, std::vector<Slice>> &objects)
+        const;
 
     int64_t get_offload_rpc_read_count() const {
         return offload_rpc_read_count_.load(std::memory_order_relaxed);
@@ -725,9 +863,9 @@ class RealClient : public PyClient {
 
     /**
      * @brief Mount a shared memory file region and return segment ids.
-     *        If size > max_mr_size, it will be split into multiple chunks
-     *        and mounted separately. RealClient will open(path) + mmap
-     *        internally for each chunk.
+     *        Protocols with a registration limit split larger regions into
+     *        multiple chunks. RealClient will open(path) + mmap internally
+     *        for each chunk.
      */
     int mountSegment(const std::string &path, size_t offset, size_t size,
                      const std::string &protocol, const std::string &location,
@@ -742,7 +880,7 @@ class RealClient : public PyClient {
 
     /**
      * @brief Allocate memory internally and mount segments to master.
-     *        If size > max_mr_size, it will be split into multiple chunks.
+     *        Protocols with a registration limit split larger regions.
      *        Memory is allocated via allocate_buffer_allocator_memory.
      *        The actual allocated size (aligned up to Slab::kSize) is written
      *        to out_allocated_size if non-null.
@@ -759,6 +897,14 @@ class RealClient : public PyClient {
     int unmountAndFreeSegment(const std::vector<std::string> &segment_ids,
                               uint64_t grace_period_seconds = 0);
 
+    /**
+     * @brief Deregister this store's disk tier from the master and wait out a
+     * grace period, so a planned shutdown stops being advertised as an owner
+     * of offloaded keys before it stops serving them. No-op when SSD offload
+     * is not enabled on this client.
+     */
+    int drainLocalDiskSegment(uint64_t grace_period_seconds = 0);
+
     struct MountedSegmentRecord {
         void *mmap_base = nullptr;
         size_t size = 0;
@@ -774,6 +920,11 @@ class RealClient : public PyClient {
 
     void FreeAllocatedStoreSegment(AllocatedSegmentRecord &record);
 
+    std::vector<tl::expected<void, ErrorCode>>
+    batch_write_from_cuda_ipc_dummy_helper(
+        const std::vector<CudaIpcWriteRequest> &requests,
+        const ReplicateConfig &config, const UUID &client_id, bool is_upsert);
+
     std::unique_ptr<AutoPortBinder> port_binder_ = nullptr;
 
     struct SegmentDeleter {
@@ -863,6 +1014,17 @@ class RealClient : public PyClient {
         void *shm_buffer = nullptr;
         size_t shm_size = 0;
         uintptr_t dummy_base_addr = 0;
+        // Whether this receiver-side mapping was registered with SPDK for NoF
+        // zero-copy (see RealClient::map_shm_internal_with_device). Must be
+        // unregistered before munmap on every teardown path.
+        bool spdk_registered = false;
+        // Set when the transfer engine's unregisterLocalMemory() failed during
+        // teardown: TE still holds this region (RdmaTransport does not
+        // deregister the MR when the metadata update fails, and
+        // TransferEngineImpl keeps its region record), so the mapping must not
+        // be munmapped until a later retry releases it (see
+        // RetryQuarantinedShmsLocked).
+        bool te_unregister_pending = false;
         bool is_ascend = false;
         bool is_ipc = false;
         // Ascend physical device id from dummy (dummy-real RPC).
@@ -887,6 +1049,24 @@ class RealClient : public PyClient {
     std::unordered_map<void *, size_t> registered_buffer_sizes_;
     std::optional<WritableBufferRegion> local_buffer_region_;
 
+    // KV transfer sessions (process-local; not shared with DummyClient).
+    // get_sessions_ stores a FilterQueryResult'd QueryResult (single complete
+    // supported replica + lease); ranges only compare lease locally (no
+    // Master).
+    // Put sessions track writable + inflight so end/revoke can seal the
+    // session and wait for outstanding range writes before finalize/free.
+    struct PutSessionEntry {
+        std::vector<Replica::Descriptor> replicas;
+        uint64_t object_size{0};
+        ReplicaWriteMode write_mode{ReplicaWriteMode::SINGLE_REPLICA};
+        bool writable{true};
+        size_t inflight_transfers{0};
+    };
+    mutable std::mutex session_mutex_;
+    std::condition_variable session_cv_;
+    std::unordered_map<std::string, QueryResult> get_sessions_;
+    std::unordered_map<std::string, PutSessionEntry> put_sessions_;
+
     // Dummy VA -> real VA using mapped_shms; last_hit_shm caches locality.
     bool map_dummy_range_in_shm(const MappedShm &shm, uint64_t dummy_addr,
                                 size_t offset, size_t size,
@@ -902,6 +1082,19 @@ class RealClient : public PyClient {
                                         uint64_t dummy_addr, size_t dst_offset,
                                         size_t size, void *&out_real) const;
 
+    std::vector<std::vector<std::vector<tl::expected<int64_t, ErrorCode>>>>
+    get_into_ranges_shm_helper_impl(
+        const std::vector<uint64_t> &dummy_buffers,
+        const std::vector<size_t> &dummy_buffer_sizes,
+        const std::vector<size_t> *buffer_capacities,
+        const std::vector<std::vector<std::string>> &all_keys,
+        const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+        const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+        const std::map<std::string, CachedQueryResultResponse>
+            &cached_query_results,
+        int32_t device_id, const UUID &client_id);
+
     tl::expected<std::vector<void *>, ErrorCode> map_dummy_addrs_to_real_ptrs(
         const ShmContext &context, const std::vector<uint64_t> &dummy_addrs,
         const std::vector<size_t> &sizes, const UUID &client_id,
@@ -958,6 +1151,82 @@ class RealClient : public PyClient {
         size_t local_buffer_size);
 
    private:
+    struct SessionRangeReadRequest {
+        std::string object_key;
+        size_t result_index;
+        Replica::Descriptor selected_replica;
+        QueryResult cached_query_result;
+        std::vector<void *> destination_buffers;
+        std::vector<size_t> range_sizes;
+        std::vector<size_t> source_offsets;
+        size_t transferred_bytes;
+        std::chrono::steady_clock::time_point lease_deadline;
+    };
+
+    struct SessionRangeReadPlan {
+        std::vector<SessionRangeReadRequest> memory_requests;
+        std::vector<SessionRangeReadRequest> dfs_requests;
+    };
+
+    struct DfsSessionStagingArena {
+        std::shared_ptr<BufferHandle> staging_buffer;
+        std::unordered_map<std::string, size_t> object_offsets;
+        std::vector<std::string> object_keys;
+        std::vector<QueryResult> cached_query_results;
+        std::unordered_map<std::string, std::vector<Slice>> object_slices;
+    };
+
+    bool validate_session_range_batch_arguments(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const std::vector<std::vector<size_t>> &all_src_offsets) const;
+
+    std::vector<SessionRangeReadRequest> prepare_session_range_read_requests(
+        const std::vector<std::string> &keys,
+        const std::vector<std::vector<void *>> &all_buffers,
+        const std::vector<std::vector<size_t>> &all_sizes,
+        const std::vector<std::vector<size_t>> &all_src_offsets,
+        std::vector<int> &results);
+
+    SessionRangeReadPlan classify_session_range_read_requests(
+        std::vector<SessionRangeReadRequest> requests,
+        std::vector<int> &results);
+
+    void execute_session_memory_range_reads(
+        const std::vector<SessionRangeReadRequest> &requests,
+        std::vector<int> &results);
+
+    DfsSessionStagingArena build_dfs_session_staging_arena(
+        const std::vector<SessionRangeReadRequest> &requests,
+        std::vector<int> &results);
+
+    bool session_range_requests_target_device(
+        const std::vector<SessionRangeReadRequest> &requests) const;
+
+    void execute_session_dfs_range_reads(
+        const std::vector<SessionRangeReadRequest> &requests,
+        std::vector<int> &results);
+
+    tl::expected<void, ErrorCode> scatter_session_range_read(
+        const SessionRangeReadRequest &request,
+        const void *staging_buffer) const;
+
+    void complete_staged_session_range_read(
+        const SessionRangeReadRequest &request, const void *staging_buffer,
+        std::vector<int> &results);
+
+    bool invalidate_expired_get_session(const SessionRangeReadRequest &request,
+                                        std::vector<int> &results);
+
+    void mark_get_session_lease_expired_locked(
+        const SessionRangeReadRequest &request, std::vector<int> &results);
+
+    static void fail_file_backed_requests_for_key(
+        const std::vector<SessionRangeReadRequest> &requests,
+        const std::string &object_key, ErrorCode error,
+        std::vector<int> &results);
+
     std::unordered_map<std::string, MountedSegmentRecord>
         mounted_segment_records_;
     std::mutex mounted_segment_records_mutex_;
@@ -970,6 +1239,18 @@ class RealClient : public PyClient {
     void ReleaseAllMountedSegmentRecords();
     void ReleaseAllocatedSegmentRecord(const std::string &segment_id);
     void ReleaseAllAllocatedSegmentRecords();
+
+    // MappedShm whose spdk_mem_unregister() (spdk_registered) or transfer
+    // engine unregisterLocalMemory() (te_unregister_pending) failed during
+    // teardown. The mapping is deliberately retained (never munmapped) so
+    // neither SPDK nor the transfer engine keeps a registration to a
+    // freed/reused VA; retried on later teardown entry points. Guarded by
+    // dummy_client_mutex_.
+    std::vector<MappedShm> quarantine_shms_;
+
+    // Re-attempt TE + SPDK unregister and munmap of quarantine_shms_. Caller
+    // must hold dummy_client_mutex_. Failures stay quarantined.
+    void RetryQuarantinedShmsLocked();
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/replica.h b/mooncake-store/include/replica.h
index 3aa42ecf98..f5b645c4eb 100644
--- a/mooncake-store/include/replica.h
+++ b/mooncake-store/include/replica.h
@@ -37,7 +37,8 @@ inline std::ostream& operator<<(std::ostream& os,
                              {ReplicaType::DISK, "DISK"},
                              {ReplicaType::LOCAL_DISK, "LOCAL_DISK"},
                              {ReplicaType::NOF_SSD, "NOF_SSD"},
-                             {ReplicaType::ALL, "ALL"}};
+                             {ReplicaType::ALL, "ALL"},
+                             {ReplicaType::DFS, "DFS"}};
 
     os << (replica_type_strings.count(replicaType)
                ? replica_type_strings.at(replicaType)
@@ -57,6 +58,28 @@ enum class ReplicaStatus {
     FAILED,         // Failed state (can be used for reassignment)
 };
 
+/**
+ * @brief Requested soft-pin transition for a Put or Upsert operation.
+ */
+enum class SoftPinAction : uint8_t {
+    PRESERVE = 0,
+    ENABLE = 1,
+    DISABLE = 2,
+};
+
+inline std::ostream& operator<<(std::ostream& os,
+                                const SoftPinAction& action) noexcept {
+    switch (action) {
+        case SoftPinAction::PRESERVE:
+            return os << "PRESERVE";
+        case SoftPinAction::ENABLE:
+            return os << "ENABLE";
+        case SoftPinAction::DISABLE:
+            return os << "DISABLE";
+    }
+    return os << "UNKNOWN";
+}
+
 /**
  * @brief Stream operator for ReplicaStatus
  */
@@ -81,7 +104,11 @@ inline std::ostream& operator<<(std::ostream& os,
 struct ReplicateConfig {
     size_t replica_num{1};
     size_t nof_replica_num{0};
-    bool with_soft_pin{false};
+    size_t dfs_replica_num{0};
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE};
+    // Optional request-level override. When omitted, ENABLE uses the
+    // master's default soft-pin TTL.
+    std::optional<uint64_t> soft_pin_ttl_ms{};
     bool with_hard_pin{false};  // Hard pin: object cannot be evicted
     std::vector<std::string>
         preferred_segments{};         // Preferred segments for allocation
@@ -92,9 +119,10 @@ struct ReplicateConfig {
     bool prefer_alloc_in_same_node{false};
     ObjectDataType data_type{ObjectDataType::UNKNOWN};
     std::string host_id{};
-    // Optional per-key routing group IDs. Empty string keeps that key
-    // ungrouped. Grouped keys share metadata routing, coalesced lease refresh,
-    // and memory eviction behavior.
+    // Optional per-key group IDs. Empty string keeps that key
+    // ungrouped. Group IDs tie keys into a lifecycle group: the background
+    // eviction treats the group as a unit (all-or-none). Object routing is
+    // always hash(tenant, key) and is decoupled from groups.
     std::optional<std::vector<std::string>> group_ids{};
 
     ReplicateConfig ForSingleKey(size_t key_index) const {
@@ -110,8 +138,15 @@ struct ReplicateConfig {
                                     const ReplicateConfig& config) noexcept {
         os << "ReplicateConfig: { replica_num: " << config.replica_num
            << ", nof_replica_num: " << config.nof_replica_num
-           << ", with_soft_pin: " << config.with_soft_pin
-           << ", with_hard_pin: " << config.with_hard_pin
+           << ", dfs_replica_num: " << config.dfs_replica_num
+           << ", soft_pin_action: " << config.soft_pin_action
+           << ", soft_pin_ttl_ms: ";
+        if (config.soft_pin_ttl_ms.has_value()) {
+            os << *config.soft_pin_ttl_ms;
+        } else {
+            os << "default";
+        }
+        os << ", with_hard_pin: " << config.with_hard_pin
            << ", preferred_segments: [";
         for (size_t i = 0; i < config.preferred_segments.size(); ++i) {
             os << config.preferred_segments[i];
@@ -155,10 +190,12 @@ enum class ReplicaWriteMode {
 
 inline ReplicaWriteMode DetermineReplicaWriteMode(
     const ReplicateConfig& config) {
-    if (config.replica_num == 1 && config.nof_replica_num == 1) {
+    if (config.dfs_replica_num == 0 && config.replica_num == 1 &&
+        config.nof_replica_num == 1) {
         return ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA;
     }
-    if (config.replica_num > 1 || config.nof_replica_num > 1) {
+    if (config.replica_num > 1 || config.nof_replica_num > 1 ||
+        config.dfs_replica_num > 0) {
         return ReplicaWriteMode::RELIABLE_MULTI_REPLICA;
     }
     return ReplicaWriteMode::SINGLE_REPLICA;
@@ -181,6 +218,23 @@ struct LocalDiskReplicaData {
     UUID client_id;
     uint64_t object_size = 0;
     std::string transport_endpoint;
+    // Process-local affiliation with the exact Client incarnation. This is
+    // rebuilt after restore and deliberately excluded from descriptors.
+    std::shared_ptr<ClientLivenessRecord> client_liveness;
+};
+
+struct DistributedFSDescriptor {
+    std::string file_path;
+    uint64_t offset = 0;
+    uint64_t object_size = 0;
+    uint64_t aligned_size = 0;
+    int shard_idx = 0;
+    YLT_REFL(DistributedFSDescriptor, file_path, offset, object_size,
+             aligned_size, shard_idx);
+};
+
+struct DfsReplicaData {
+    DistributedFSDescriptor descriptor;
 };
 
 struct MemoryDescriptor {
@@ -212,44 +266,30 @@ class Replica {
 
     // memory replica constructor
     Replica(std::unique_ptr<AllocatedBuffer> buffer, ReplicaStatus status)
-        : id_(next_id_.fetch_add(1)),
-          data_(MemoryReplicaData{std::move(buffer)}),
-          status_(status),
-          refcnt_(0) {}
+        : Replica(next_id_.fetch_add(1), std::move(buffer), status) {}
 
     // nof ssd replica constructor
     Replica(std::unique_ptr<AllocatedBuffer> buffer, ReplicaStatus status,
             ReplicaType replica_type)
-        : id_(next_id_.fetch_add(1)), status_(status), refcnt_(0) {
-        if (replica_type == ReplicaType::MEMORY) {
-            data_ = MemoryReplicaData{std::move(buffer)};
-        } else if (replica_type == ReplicaType::NOF_SSD) {
-            data_ = NoFReplicaData{std::move(buffer)};
-        } else {
-            LOG(ERROR) << "Invalid buffered replica type: " << replica_type;
-        }
-    }
+        : Replica(next_id_.fetch_add(1), std::move(buffer), status,
+                  replica_type) {}
 
     // disk replica constructor
     Replica(std::string file_path, uint64_t object_size, ReplicaStatus status)
-        : id_(next_id_.fetch_add(1)),
-          data_(DiskReplicaData{std::move(file_path), object_size}),
-          status_(status),
-          refcnt_(0) {
-        // Automatic update allocated_file_size via RAII
-        MasterMetricManager::instance().inc_allocated_file_size(object_size);
-    }
+        : Replica(next_id_.fetch_add(1), std::move(file_path), object_size,
+                  status) {}
 
     // local disk replica constructor
     Replica(UUID client_id, uint64_t object_size,
-            std::string transport_endpoint, ReplicaStatus status)
-        : id_(next_id_.fetch_add(1)),
-          data_(LocalDiskReplicaData{client_id, object_size,
-                                     std::move(transport_endpoint)}),
-          status_(status),
-          refcnt_(0) {
-        MasterMetricManager::instance().inc_allocated_file_size(object_size);
-    }
+            std::string transport_endpoint, ReplicaStatus status,
+            std::shared_ptr<ClientLivenessRecord> client_liveness = nullptr)
+        : Replica(next_id_.fetch_add(1), client_id, object_size,
+                  std::move(transport_endpoint), status,
+                  std::move(client_liveness)) {}
+
+    // dfs replica constructor
+    Replica(DistributedFSDescriptor descriptor, ReplicaStatus status)
+        : Replica(next_id_.fetch_add(1), std::move(descriptor), status) {}
 
     ~Replica() {
         if (status_ == ReplicaStatus::UNDEFINED) return;
@@ -306,6 +346,41 @@ class Replica {
 
     [[nodiscard]] Descriptor get_descriptor() const;
 
+    [[nodiscard]] bool getDescriptorIfAvailable(Descriptor& descriptor) const {
+        if (is_memory_replica()) {
+            const auto& data = std::get<MemoryReplicaData>(data_);
+            if (!data.buffer || !data.buffer->isAvailable()) {
+                return false;
+            }
+        } else if (is_nof_replica()) {
+            const auto& data = std::get<NoFReplicaData>(data_);
+            if (!data.buffer || !data.buffer->isAvailable()) {
+                return false;
+            }
+        } else if (is_local_disk_replica()) {
+            const auto& data = std::get<LocalDiskReplicaData>(data_);
+            const auto record = std::atomic_load_explicit(
+                &data.client_liveness, std::memory_order_acquire);
+            if (!record || !record->IsServing()) {
+                return false;
+            }
+        }
+        descriptor = get_descriptor();
+        if (is_memory_replica()) {
+            return std::get<MemoryReplicaData>(data_).buffer->isAvailable();
+        }
+        if (is_nof_replica()) {
+            return std::get<NoFReplicaData>(data_).buffer->isAvailable();
+        }
+        if (is_local_disk_replica()) {
+            const auto& data = std::get<LocalDiskReplicaData>(data_);
+            const auto record = std::atomic_load_explicit(
+                &data.client_liveness, std::memory_order_acquire);
+            return record && record->IsServing();
+        }
+        return true;
+    }
+
     [[nodiscard]] ReplicaID id() const { return id_; }
 
     [[nodiscard]] ReplicaStatus status() const { return status_; }
@@ -368,6 +443,22 @@ class Replica {
         return replica.is_local_disk_replica();
     }
 
+    [[nodiscard]] bool is_dfs_replica() const {
+        return std::holds_alternative<DfsReplicaData>(data_);
+    }
+
+    [[nodiscard]] static bool fn_is_dfs_replica(const Replica& replica) {
+        return replica.is_dfs_replica();
+    }
+
+    [[nodiscard]] const DistributedFSDescriptor& get_dfs_descriptor() const {
+        return std::get<DfsReplicaData>(data_).descriptor;
+    }
+
+    [[nodiscard]] DistributedFSDescriptor& get_dfs_descriptor() {
+        return std::get<DfsReplicaData>(data_).descriptor;
+    }
+
     [[nodiscard]] bool has_invalid_mem_handle() const {
         if (is_memory_replica()) {
             const auto& mem_data = std::get<MemoryReplicaData>(data_);
@@ -380,7 +471,14 @@ class Replica {
         if (!buffer || !is_memory_replica()) {
             return false;
         }
-        std::get<MemoryReplicaData>(data_).buffer = std::move(buffer);
+        auto& memory = std::get<MemoryReplicaData>(data_);
+        if (!memory.buffer ||
+            !buffer->copyTransferProtocolFrom(*memory.buffer)) {
+            return false;
+        }
+        // Allocator import rebuilds address ownership; the replica keeps the
+        // transfer protocol advertised before remount.
+        memory.buffer = std::move(buffer);
         return true;
     }
 
@@ -393,18 +491,19 @@ class Replica {
     }
 
     /**
-     * @brief Check if a local_disk replica's owner client is still alive.
+     * @brief Check if a local_disk replica's owner still retains resources.
      * Used by CleanupStaleHandles to remove replicas belonging to expired
      * clients. For non-local_disk replicas, always returns false.
-     * @param alive_clients Set of currently alive client IDs.
-     * @return true if this is a local_disk replica whose client is not alive.
+     * @param retaining_clients Clients whose resources must be retained.
+     * @return true if this replica's owner no longer retains resources.
      */
     [[nodiscard]] bool has_stale_local_disk_client(
-        const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients)
+        const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients)
         const {
         auto client_id = get_local_disk_client_id();
         if (client_id.has_value()) {
-            return alive_clients.find(client_id.value()) == alive_clients.end();
+            return retaining_clients.find(client_id.value()) ==
+                   retaining_clients.end();
         }
         return false;
     }
@@ -422,6 +521,51 @@ class Replica {
         return std::nullopt;
     }
 
+    void bindClientLiveness(
+        std::shared_ptr<ClientLivenessRecord> client_liveness) {
+        if (is_memory_replica()) {
+            auto& data = std::get<MemoryReplicaData>(data_);
+            if (data.buffer) {
+                data.buffer->bindClientLiveness(std::move(client_liveness));
+            }
+        } else if (is_local_disk_replica()) {
+            auto& record =
+                std::get<LocalDiskReplicaData>(data_).client_liveness;
+            std::atomic_store_explicit(&record, std::move(client_liveness),
+                                       std::memory_order_release);
+        }
+    }
+
+    [[nodiscard]] std::shared_ptr<ClientLivenessRecord> getClientLiveness()
+        const {
+        if (is_memory_replica()) {
+            const auto& data = std::get<MemoryReplicaData>(data_);
+            return data.buffer ? data.buffer->getClientLiveness() : nullptr;
+        }
+        if (is_local_disk_replica()) {
+            const auto& data = std::get<LocalDiskReplicaData>(data_);
+            return std::atomic_load_explicit(&data.client_liveness,
+                                             std::memory_order_acquire);
+        }
+        return nullptr;
+    }
+
+    [[nodiscard]] bool isAffiliatedWith(
+        const std::shared_ptr<ClientLivenessRecord>& client_liveness) const {
+        if (is_memory_replica()) {
+            const auto& data = std::get<MemoryReplicaData>(data_);
+            return data.buffer &&
+                   data.buffer->getClientLiveness() == client_liveness;
+        }
+        if (is_local_disk_replica()) {
+            const auto& data = std::get<LocalDiskReplicaData>(data_);
+            return std::atomic_load_explicit(&data.client_liveness,
+                                             std::memory_order_acquire) ==
+                   client_liveness;
+        }
+        return false;
+    }
+
     [[nodiscard]] size_t get_memory_buffer_size() const {
         if (is_memory_replica()) {
             const auto& mem_data = std::get<MemoryReplicaData>(data_);
@@ -464,6 +608,14 @@ class Replica {
         }
     }
 
+    void cancel_remove() {
+        if (status_ == ReplicaStatus::REMOVED) {
+            status_ = ReplicaStatus::COMPLETE;
+        } else {
+            LOG(ERROR) << "Cannot cancel_remove from status: " << status_;
+        }
+    }
+
     void inc_refcnt() { refcnt_.fetch_add(1); }
 
     void dec_refcnt() { refcnt_.fetch_sub(1); }
@@ -485,12 +637,15 @@ class Replica {
         ReplicaType operator()(const LocalDiskReplicaData&) const {
             return ReplicaType::LOCAL_DISK;
         }
+        ReplicaType operator()(const DfsReplicaData&) const {
+            return ReplicaType::DFS;
+        }
     };
 
     struct Descriptor {
-        ReplicaID id;
+        ReplicaID id{0};
         std::variant<MemoryDescriptor, NoFDescriptor, DiskDescriptor,
-                     LocalDiskDescriptor>
+                     LocalDiskDescriptor, DistributedFSDescriptor>
             descriptor_variant;
         ReplicaStatus status;
         YLT_REFL(Descriptor, id, descriptor_variant, status);
@@ -530,6 +685,16 @@ class Replica {
                 descriptor_variant);
         }
 
+        bool is_dfs_replica() noexcept {
+            return std::holds_alternative<DistributedFSDescriptor>(
+                descriptor_variant);
+        }
+
+        bool is_dfs_replica() const noexcept {
+            return std::holds_alternative<DistributedFSDescriptor>(
+                descriptor_variant);
+        }
+
         MemoryDescriptor& get_memory_descriptor() {
             if (auto* desc =
                     std::get_if<MemoryDescriptor>(&descriptor_variant)) {
@@ -560,6 +725,14 @@ class Replica {
             throw std::runtime_error("Expected LocalDiskDescriptor");
         }
 
+        DistributedFSDescriptor& get_dfs_descriptor() {
+            if (auto* desc =
+                    std::get_if<DistributedFSDescriptor>(&descriptor_variant)) {
+                return *desc;
+            }
+            throw std::runtime_error("Expected DistributedFSDescriptor");
+        }
+
         const MemoryDescriptor& get_memory_descriptor() const {
             if (auto* desc =
                     std::get_if<MemoryDescriptor>(&descriptor_variant)) {
@@ -589,14 +762,70 @@ class Replica {
             }
             throw std::runtime_error("Expected LocalDiskDescriptor");
         }
+
+        const DistributedFSDescriptor& get_dfs_descriptor() const {
+            if (auto* desc =
+                    std::get_if<DistributedFSDescriptor>(&descriptor_variant)) {
+                return *desc;
+            }
+            throw std::runtime_error("Expected DistributedFSDescriptor");
+        }
     };
 
    private:
+    // Restore-only constructors preserve IDs without consuming next_id_.
+    Replica(ReplicaID id, std::unique_ptr<AllocatedBuffer> buffer,
+            ReplicaStatus status)
+        : id_(id),
+          data_(MemoryReplicaData{std::move(buffer)}),
+          status_(status),
+          refcnt_(0) {}
+
+    Replica(ReplicaID id, std::unique_ptr<AllocatedBuffer> buffer,
+            ReplicaStatus status, ReplicaType replica_type)
+        : id_(id), status_(status), refcnt_(0) {
+        if (replica_type == ReplicaType::MEMORY) {
+            data_ = MemoryReplicaData{std::move(buffer)};
+        } else if (replica_type == ReplicaType::NOF_SSD) {
+            data_ = NoFReplicaData{std::move(buffer)};
+        } else {
+            LOG(ERROR) << "Invalid buffered replica type: " << replica_type;
+        }
+    }
+
+    Replica(ReplicaID id, std::string file_path, uint64_t object_size,
+            ReplicaStatus status)
+        : id_(id),
+          data_(DiskReplicaData{std::move(file_path), object_size}),
+          status_(status),
+          refcnt_(0) {
+        MasterMetricManager::instance().inc_allocated_file_size(object_size);
+    }
+
+    Replica(ReplicaID id, UUID client_id, uint64_t object_size,
+            std::string transport_endpoint, ReplicaStatus status,
+            std::shared_ptr<ClientLivenessRecord> client_liveness = nullptr)
+        : id_(id),
+          data_(LocalDiskReplicaData{client_id, object_size,
+                                     std::move(transport_endpoint),
+                                     std::move(client_liveness)}),
+          status_(status),
+          refcnt_(0) {
+        MasterMetricManager::instance().inc_allocated_file_size(object_size);
+    }
+
+    Replica(ReplicaID id, DistributedFSDescriptor descriptor,
+            ReplicaStatus status)
+        : id_(id),
+          data_(DfsReplicaData{std::move(descriptor)}),
+          status_(status),
+          refcnt_(0) {}
+
     inline static std::atomic<ReplicaID> next_id_{1};
 
     ReplicaID id_;
     std::variant<MemoryReplicaData, NoFReplicaData, DiskReplicaData,
-                 LocalDiskReplicaData>
+                 LocalDiskReplicaData, DfsReplicaData>
         data_;
     ReplicaStatus status_{ReplicaStatus::UNDEFINED};
 
@@ -647,6 +876,8 @@ inline Replica::Descriptor Replica::get_descriptor() const {
         local_disk_desc.object_size = disk_data.object_size;
         local_disk_desc.transport_endpoint = disk_data.transport_endpoint;
         desc.descriptor_variant = std::move(local_disk_desc);
+    } else if (is_dfs_replica()) {
+        desc.descriptor_variant = std::get<DfsReplicaData>(data_).descriptor;
     }
 
     return desc;
@@ -698,6 +929,18 @@ inline std::ostream& operator<<(std::ostream& os, const Replica& replica) {
         const auto& disk_data = std::get<DiskReplicaData>(replica.data_);
         os << "type: DISK, file_path: " << disk_data.file_path
            << ", object_size: " << disk_data.object_size;
+    } else if (replica.is_local_disk_replica()) {
+        const auto& disk_data = std::get<LocalDiskReplicaData>(replica.data_);
+        os << "type: LOCAL_DISK, client_id: " << disk_data.client_id
+           << ", object_size: " << disk_data.object_size
+           << ", transport_endpoint: " << disk_data.transport_endpoint;
+    } else if (replica.is_dfs_replica()) {
+        const auto& dfs_data = std::get<DfsReplicaData>(replica.data_);
+        os << "type: DFS, file_path: " << dfs_data.descriptor.file_path
+           << ", offset: " << dfs_data.descriptor.offset
+           << ", object_size: " << dfs_data.descriptor.object_size
+           << ", aligned_size: " << dfs_data.descriptor.aligned_size
+           << ", shard_idx: " << dfs_data.descriptor.shard_idx;
     }
 
     os << ", refcnt: " << replica.refcnt_.load() << " }";
diff --git a/mooncake-store/include/replica_selection.h b/mooncake-store/include/replica_selection.h
index ed7a49c2af..475020d042 100644
--- a/mooncake-store/include/replica_selection.h
+++ b/mooncake-store/include/replica_selection.h
@@ -21,7 +21,6 @@
 
 #pragma once
 
-#include <cstdlib>
 #include <functional>
 #include <limits>
 #include <mutex>
@@ -30,6 +29,7 @@
 #include <unordered_set>
 #include <vector>
 
+#include "config/replica_selection_config.h"
 #include "replica.h"
 
 namespace mooncake {
@@ -82,11 +82,8 @@ inline double BuiltinRemoteReplicaScore(const Replica::Descriptor &r) {
 // scorer has been injected. Env is read once; the injected-scorer check is
 // live so tests / late injection take effect.
 inline bool RemoteReplicaScoringEnabled() {
-    static const bool env_enabled = [] {
-        const char *env = std::getenv("MC_STORE_REPLICA_SCORING");
-        return env && std::string(env) == "1";
-    }();
-    if (env_enabled) return true;
+    static const auto config = ReplicaSelectionConfig::FromEnvironment();
+    if (config.remote_scoring_enabled) return true;
     std::shared_lock lk(detail::ScorerMutex());
     return static_cast<bool>(detail::ScorerStorage());
 }
@@ -115,13 +112,18 @@ inline const Replica::Descriptor *PickBestRemoteMemory(
     return best;
 }
 
-// Select the best replica from a list: prefer local MEMORY, then any MEMORY,
-// then LOCAL_DISK, then DISK. Master may return replicas in any order, so we
-// always scan. When scoring is enabled and there are multiple remote MEMORY
-// replicas, the best-scoring one is chosen instead of the first encountered.
+// Select the best replica from a list: prefer local MEMORY, local NOF_SSD,
+// remote MEMORY, remote NOF_SSD, LOCAL_DISK, DFS, then DISK. Master may return
+// replicas in any order, so we always scan all replicas before deciding — this
+// ensures local MEMORY is always preferred over local NOF regardless of the
+// order replicas appear in the list. When scoring is enabled and there are
+// multiple remote MEMORY replicas, the best-scoring one is chosen instead of
+// the first encountered.
 inline const Replica::Descriptor *SelectBestReplica(
     const std::vector<Replica::Descriptor> &replicas,
     const std::unordered_set<std::string> &local_endpoints) {
+    const Replica::Descriptor *local_memory = nullptr;
+    const Replica::Descriptor *local_nof = nullptr;
     const Replica::Descriptor *first_memory = nullptr;
     const Replica::Descriptor *first_nof = nullptr;
     for (const auto &r : replicas) {
@@ -130,18 +132,23 @@ inline const Replica::Descriptor *SelectBestReplica(
             if (local_endpoints.count(
                     r.get_memory_descriptor()
                         .buffer_descriptor.transport_endpoint_)) {
-                return &r;  // local MEMORY — best case
+                if (!local_memory) local_memory = &r;
+            } else {
+                if (!first_memory) first_memory = &r;
             }
-            if (!first_memory) first_memory = &r;
         } else if (r.is_nof_replica()) {
             if (local_endpoints.count(
                     r.get_nof_descriptor()
                         .buffer_descriptor.transport_endpoint_)) {
-                return &r;  // local NOF_SSD — also good
+                if (!local_nof) local_nof = &r;
+            } else {
+                if (!first_nof) first_nof = &r;
             }
-            if (!first_nof) first_nof = &r;
         }
     }
+    // Local MEMORY always beats local NOF regardless of list order.
+    if (local_memory) return local_memory;
+    if (local_nof) return local_nof;
     // No local replica. Among remote MEMORY replicas, optionally pick the
     // best-scoring one instead of the first encountered (issue #2516).
     if (first_memory && RemoteReplicaScoringEnabled()) {
@@ -157,7 +164,9 @@ inline const Replica::Descriptor *SelectBestReplica(
     for (const auto &r : replicas) {
         if (r.status != ReplicaStatus::COMPLETE) continue;
         if (r.is_local_disk_replica()) {
-            best = &r;  // LOCAL_DISK always overrides DISK
+            best = &r;  // LOCAL_DISK always overrides DFS and DISK
+        } else if (r.is_dfs_replica()) {
+            if (!best || !best->is_local_disk_replica()) best = &r;
         } else if (r.is_disk_replica() && !best) {
             best = &r;
         }
diff --git a/mooncake-store/include/rpc_helper.h b/mooncake-store/include/rpc_helper.h
index 27f43f55b9..91534b9dec 100644
--- a/mooncake-store/include/rpc_helper.h
+++ b/mooncake-store/include/rpc_helper.h
@@ -8,7 +8,7 @@
 #include <ylt/util/tl/expected.hpp>
 
 #include "types.h"
-#include "utils/scoped_vlog_timer.h"
+#include "common/scoped_vlog_timer.h"
 
 namespace mooncake {
 
diff --git a/mooncake-store/include/rpc_service.h b/mooncake-store/include/rpc_service.h
index 53e7212452..a98f207be0 100644
--- a/mooncake-store/include/rpc_service.h
+++ b/mooncake-store/include/rpc_service.h
@@ -21,6 +21,9 @@ namespace mooncake {
 class HttpMetadataServer;
 class WrappedMasterService {
    public:
+    void SetBatchOpLogTerminalCallback(
+        OrderedOpLogWriter::TerminalCallback callback);
+    void StopBatchOpLogWriter();
     // Constructor with optional metadata-cleanup-on-timeout configuration.
     // - http_metadata_server: in-process pointer used when the HTTP metadata
     //   server is co-located in the master process (nullptr = not co-located).
@@ -37,6 +40,12 @@ class WrappedMasterService {
     tl::expected<bool, ErrorCode> ExistKey(
         const std::string& key, const std::string& tenant_id = "default");
 
+    // Point-in-time existence check: shares the ExistKey lookup path but
+    // grants no read lease, so a `true` result does not protect the object
+    // from eviction.
+    tl::expected<bool, ErrorCode> ProbeKey(
+        const std::string& key, const std::string& tenant_id = "default");
+
     tl::expected<MasterMetricManager::CacheHitStatDict, ErrorCode>
     CalcCacheStats();
 
@@ -44,6 +53,10 @@ class WrappedMasterService {
         const std::vector<std::string>& keys,
         const std::string& tenant_id = "default");
 
+    std::vector<tl::expected<bool, ErrorCode>> BatchProbeKey(
+        const std::vector<std::string>& keys,
+        const std::string& tenant_id = "default");
+
     tl::expected<
         std::unordered_map<UUID, std::vector<std::string>, boost::hash<UUID>>,
         ErrorCode>
@@ -51,7 +64,8 @@ class WrappedMasterService {
 
     tl::expected<std::vector<std::string>, ErrorCode> BatchReplicaClear(
         const std::vector<std::string>& object_keys, const UUID& client_id,
-        const std::string& segment_name);
+        const std::string& segment_name,
+        const std::string& tenant_id = "default");
 
     tl::expected<
         std::unordered_map<std::string, std::vector<Replica::Descriptor>>,
@@ -187,6 +201,8 @@ class WrappedMasterService {
 
     tl::expected<std::string, ErrorCode> ServiceReady();
 
+    [[nodiscard]] TieredStorageUsageSnapshot GetStorageUsageSnapshot() const;
+
     tl::expected<std::vector<TenantQuotaSnapshot>, ErrorCode>
     ListTenantQuotaSnapshots();
     tl::expected<TenantQuotaSnapshot, ErrorCode> GetTenantQuotaSnapshot(
@@ -210,6 +226,9 @@ class WrappedMasterService {
     tl::expected<void, ErrorCode> MountLocalDiskSegment(const UUID& client_id,
                                                         bool enable_offloading);
 
+    tl::expected<void, ErrorCode> UnmountLocalDiskSegment(
+        const UUID& client_id);
+
     tl::expected<std::vector<OffloadTaskItem>, ErrorCode>
     OffloadObjectHeartbeat(const UUID& client_id, bool enable_offloading);
 
@@ -239,6 +258,11 @@ class WrappedMasterService {
         const UUID& client_id, const std::string& key,
         const std::string& tenant_id);
 
+    // Admin-only, grow-only DFS capacity management. Existing placements remain
+    // valid.
+    tl::expected<int, ErrorCode> GetDfsShardCount() const;
+    tl::expected<int, ErrorCode> ExpandDfsShards(int shard_count);
+
     tl::expected<UUID, ErrorCode> CreateDrainJob(
         const CreateDrainJobRequest& request);
 
@@ -253,9 +277,13 @@ class WrappedMasterService {
 
     // Internal method called by supervisor during promotion; NOT an RPC
     // endpoint.
-    void RestoreFromStandby(const std::vector<StandbyObjectEntry>& objects,
-                            uint64_t initial_oplog_sequence_id,
-                            const std::vector<StandbySegmentInfo>& segments);
+    tl::expected<void, ErrorCode> RestoreFromStandby(
+        const std::vector<StandbyObjectEntry>& objects,
+        uint64_t initial_oplog_sequence_id,
+        const std::vector<StandbySegmentInfo>& segments);
+    tl::expected<void, ErrorCode> RestoreFromBatchOpLogPromotion(
+        BatchOpLogPromotionHandoff handoff,
+        size_t chunk_object_count = kDefaultBatchOpLogPromotionChunkObjects);
 
     tl::expected<UUID, ErrorCode> CreateCopyTask(
         const std::string& key, const std::string& tenant_id,
@@ -279,13 +307,28 @@ class WrappedMasterService {
         const std::string& tenant_id, const std::string& src_segment,
         const std::vector<std::string>& tgt_segments);
 
+    tl::expected<CopyStartResponse, ErrorCode> DynamicReplicaCopyStart(
+        const UUID& client_id, const std::string& key,
+        const std::string& tenant_id, const std::string& src_segment,
+        const std::vector<std::string>& tgt_segments,
+        const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
+
     tl::expected<void, ErrorCode> CopyEnd(const UUID& client_id,
                                           const std::string& key,
                                           const std::string& tenant_id);
+    tl::expected<void, ErrorCode> DynamicReplicaCopyEnd(
+        const UUID& client_id, const std::string& key,
+        const std::string& tenant_id, const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
 
     tl::expected<void, ErrorCode> CopyRevoke(const UUID& client_id,
                                              const std::string& key,
                                              const std::string& tenant_id);
+    tl::expected<void, ErrorCode> DynamicReplicaCopyRevoke(
+        const UUID& client_id, const std::string& key,
+        const std::string& tenant_id, const UUID& dynamic_replication_lease_id,
+        uint64_t dynamic_replication_version_epoch);
 
     tl::expected<MoveStartResponse, ErrorCode> MoveStart(
         const UUID& client_id, const std::string& key,
diff --git a/mooncake-store/include/rpc_types.h b/mooncake-store/include/rpc_types.h
index 242cc0edfd..ef922f09a3 100644
--- a/mooncake-store/include/rpc_types.h
+++ b/mooncake-store/include/rpc_types.h
@@ -14,6 +14,43 @@ struct ObjectMeta {
 };
 YLT_REFL(ObjectMeta, key, object_checksum);
 
+enum class ReplicaActionType {
+    ADD = 0,
+};
+
+struct ReplicaActionProposal {
+    ReplicaActionType action{ReplicaActionType::ADD};
+    UUID proposal_id{};
+    std::string tenant_id{"default"};
+    std::string key;
+    std::string requester_domain;
+    uint64_t observed_version_epoch{0};
+    uint64_t object_size_bytes{0};
+    std::string target_domain;
+    std::optional<std::string> preferred_target_segment;
+    int64_t expire_at_ms_epoch{0};
+};
+YLT_REFL(ReplicaActionProposal, action, proposal_id, tenant_id, key,
+         requester_domain, observed_version_epoch, object_size_bytes,
+         target_domain, preferred_target_segment, expire_at_ms_epoch);
+
+struct ReplicaActionLease {
+    UUID proposal_id{};
+    UUID lease_id{};
+    ReplicaActionType action{ReplicaActionType::ADD};
+    std::string tenant_id{"default"};
+    std::string key;
+    std::string source_segment;
+    std::string target_segment;
+    std::string target_domain;
+    uint64_t version_epoch{0};
+    int64_t expire_at_ms_epoch{0};
+    UUID task_id{};
+};
+YLT_REFL(ReplicaActionLease, proposal_id, lease_id, action, tenant_id, key,
+         source_segment, target_segment, target_domain, version_epoch,
+         expire_at_ms_epoch, task_id);
+
 /**
  * @brief Response structure for Ping operation
  */
diff --git a/mooncake-store/include/segment.h b/mooncake-store/include/segment.h
index b0085ab9e2..1fa97b109d 100644
--- a/mooncake-store/include/segment.h
+++ b/mooncake-store/include/segment.h
@@ -4,6 +4,7 @@
 #include <chrono>
 #include <map>
 #include <ostream>
+#include <optional>
 #include <set>
 #include <shared_mutex>
 #include <string>
@@ -13,48 +14,22 @@
 
 #include "allocation_strategy.h"
 #include "allocator.h"
+#include "local_ssd/persisted_state.h"
 #include "rpc_types.h"
+#include "segment/status.h"
+#include "segment/usage.h"
+#include "storage_usage.h"
 #include "types.h"
 
 namespace mooncake {
 using HostSegmentIndex =
     std::map<std::string, std::map<std::string, std::set<UUID>>>;
 
-/**
- * @brief Status of a mounted segment in master
- */
-enum class SegmentStatus {
-    UNDEFINED = 0,  // Uninitialized
-    OK,             // Segment is mounted and available for allocation
-    DRAINING,       // Segment remains readable but accepts no new allocations
-    DRAINED,        // Segment has been drained and awaits unmount
-    GRACEFULLY_UNMOUNTING,  // Readable, no new allocations, timer running
-    UNMOUNTING,             // Segment is under unmounting
-};
-
-/**
- * @brief Stream operator for SegmentStatus
- */
-inline std::ostream& operator<<(std::ostream& os,
-                                const SegmentStatus& status) noexcept {
-    static const std::unordered_map<SegmentStatus, std::string_view>
-        status_strings{
-            {SegmentStatus::UNDEFINED, "UNDEFINED"},
-            {SegmentStatus::OK, "OK"},
-            {SegmentStatus::DRAINING, "DRAINING"},
-            {SegmentStatus::DRAINED, "DRAINED"},
-            {SegmentStatus::GRACEFULLY_UNMOUNTING, "GRACEFULLY_UNMOUNTING"},
-            {SegmentStatus::UNMOUNTING, "UNMOUNTING"}};
-
-    os << (status_strings.count(status) ? status_strings.at(status)
-                                        : "UNKNOWN");
-    return os;
-}
-
 struct MountedSegment {
     Segment segment;
     SegmentStatus status;
     std::shared_ptr<BufferAllocatorBase> buf_allocator;
+    std::shared_ptr<SegmentAllocatorRegistration> allocator_registration;
 };
 
 struct MountedNoFSegment {
@@ -62,6 +37,7 @@ struct MountedNoFSegment {
     UUID client_id;
     SegmentStatus status;
     std::shared_ptr<BufferAllocatorBase> buf_allocator;
+    std::shared_ptr<SegmentAllocatorRegistration> allocator_registration;
 };
 
 struct MountedNoFSegmentSnapshot {
@@ -87,34 +63,6 @@ inline std::ostream& operator<<(
     return os;
 }
 
-struct LocalDiskSegment {
-    mutable Mutex offloading_mutex_;
-    bool enable_offloading;
-    int64_t ssd_total_capacity_bytes = 0;  // last reported by client heartbeat
-    std::atomic<int64_t> ssd_used_bytes{0};
-    std::unordered_map<std::string, OffloadTaskItem> GUARDED_BY(
-        offloading_mutex_) offloading_objects;
-    // Promotion-on-hit pending work for this client. Populated by master's
-    // TryPushPromotionQueue when a Get hits a LOCAL_DISK-only key on this
-    // client. Drained by PromotionObjectHeartbeat. Same locking as
-    // offloading_objects (offloading_mutex_).
-    std::unordered_map<std::string, PromotionTaskItem> GUARDED_BY(
-        offloading_mutex_) promotion_objects;
-    // Set by master's RemoveAll. When the client sees this flag via
-    // PollRemoveAll, it calls FileStorage::RemoveAll() to physically
-    // delete all SSD files. Same locking as offloading_objects
-    // (offloading_mutex_).
-    bool GUARDED_BY(offloading_mutex_) pending_remove_all = false;
-    explicit LocalDiskSegment(bool enable_offloading)
-        : enable_offloading(enable_offloading) {}
-
-    LocalDiskSegment(const LocalDiskSegment&) = delete;
-    LocalDiskSegment& operator=(const LocalDiskSegment&) = delete;
-
-    LocalDiskSegment(LocalDiskSegment&&) = delete;
-    LocalDiskSegment& operator=(LocalDiskSegment&&) = delete;
-};
-
 // Forward declarations
 class SegmentManager;
 
@@ -134,10 +82,9 @@ class ScopedSegmentAccess {
     /**
      * @brief Mount a segment
      */
-    ErrorCode MountSegment(const Segment& segment, const UUID& client_id);
-
-    ErrorCode MountLocalDiskSegment(const UUID& client_id,
-                                    bool enable_offloading);
+    ErrorCode MountSegment(
+        const Segment& segment, const UUID& client_id,
+        std::shared_ptr<ClientLivenessRecord> client_liveness);
 
     /**
      * @brief Re-mount a segment. To avoid infinite remount trying, only the
@@ -145,8 +92,9 @@ class ScopedSegmentAccess {
      * errors. When encounters unsolvable errors, the segment will not be
      * mounted while the return value will be OK.
      */
-    ErrorCode ReMountSegment(const std::vector<Segment>& segments,
-                             const UUID& client_id);
+    ErrorCode ReMountSegment(
+        const std::vector<Segment>& segments, const UUID& client_id,
+        std::shared_ptr<ClientLivenessRecord> client_liveness);
 
     ErrorCode ValidateRemountSegment(const Segment& segment,
                                      const UUID& client_id) const;
@@ -181,7 +129,11 @@ class ScopedSegmentAccess {
      */
     ErrorCode CommitUnmountSegment(const UUID& segment_id,
                                    const UUID& client_id,
-                                   const size_t& metrics_dec_capacity);
+                                   const size_t& metrics_dec_capacity,
+                                   bool retain_name_registration = false);
+
+    void ReleaseUnmountedSegmentName(const UUID& segment_id,
+                                     const std::string& segment_name);
 
     /**
      * @brief Get all the segments of a client
@@ -189,6 +141,17 @@ class ScopedSegmentAccess {
     ErrorCode GetClientSegments(const UUID& client_id,
                                 std::vector<Segment>& segments) const;
 
+    /**
+     * @brief Rebind restored client-owned segment resources to a fresh
+     *        liveness record. Segment snapshots intentionally do not persist
+     *        record implementation state.
+     */
+    void BindClientLiveness(
+        const UUID& client_id,
+        const std::shared_ptr<ClientLivenessRecord>& client_liveness);
+    void BindBufferToSegment(const UUID& segment_id, AllocatedBuffer& buffer);
+    [[nodiscard]] bool RebindBufferToOwningSegment(AllocatedBuffer& buffer);
+
     /**
      * @brief Get the names of all the segments
      */
@@ -254,13 +217,10 @@ class ScopedSegmentAccess {
     ErrorCode SetSegmentStatusByName(const std::string& segment_name,
                                      SegmentStatus status);
 
-    /**
-     * @brief Remove the local disk segment entry for a client.
-     * Called when a client expires to clean up its local disk segment.
-     */
-    void UnmountLocalDiskSegment(const UUID& client_id);
-
    private:
+    void ReindexSegmentNameAfterRemoval(const UUID& removed_segment_id,
+                                        const std::string& segment_name);
+
     SegmentManager* segment_manager_;
     std::unique_lock<std::shared_mutex> lock_;
 };
@@ -346,57 +306,33 @@ class ScopedAllocatorAccess {
                                    std::shared_mutex& mutex)
         : allocator_manager_(allocator_manager), lock_(mutex) {}
 
-    explicit ScopedAllocatorAccess(const AllocatorManager& allocator_manager,
-                                   const HostSegmentIndex& segments_by_host,
-                                   std::shared_mutex& mutex)
+    explicit ScopedAllocatorAccess(
+        const AllocatorManager& allocator_manager,
+        const HostSegmentIndex& segments_by_host,
+        const std::unordered_map<std::string, UUID>& client_by_name,
+        std::shared_mutex& mutex)
         : allocator_manager_(allocator_manager),
           segments_by_host_(&segments_by_host),
+          client_by_name_(&client_by_name),
           lock_(mutex) {}
 
-    const AllocatorManager& getAllocatorManager() { return allocator_manager_; }
+    const AllocatorManager& getAllocatorManager() const {
+        return allocator_manager_;
+    }
+
+    AllocatorManager SnapshotAllocatorManager() const {
+        return allocator_manager_.Snapshot(client_by_name_);
+    }
 
     std::vector<std::string> GetHostOrderedSegments(
         const std::string& writer_host_id, const std::string& key) const;
 
+    std::optional<UUID> GetOwnerClientId(const std::string& segment_name) const;
+
    private:
     const AllocatorManager& allocator_manager_;
     const HostSegmentIndex* segments_by_host_{nullptr};
-    std::shared_lock<std::shared_mutex> lock_;
-};
-
-/**
- * @brief RAII-style access to LocalDiskOffloadingQueues for thread-safe
- * LocalDiskOffloadingQueue usage
- */
-class ScopedLocalDiskSegmentAccess : public SsdMetricsProvider {
-   public:
-    explicit ScopedLocalDiskSegmentAccess(
-        std::unordered_map<std::string, UUID>& client_by_name,
-        std::unordered_map<UUID, std::shared_ptr<LocalDiskSegment>,
-                           boost::hash<UUID>>& client_local_disk_segment,
-        std::shared_mutex& mutex)
-        : client_by_name_(client_by_name),
-          client_local_disk_segment_(client_local_disk_segment),
-          lock_(mutex) {}
-
-    const std::unordered_map<std::string, UUID>& getClientByName() {
-        return client_by_name_;
-    }
-
-    std::unordered_map<UUID, std::shared_ptr<LocalDiskSegment>,
-                       boost::hash<UUID>>&
-    getClientLocalDiskSegment() {
-        return client_local_disk_segment_;
-    }
-
-    int64_t getSsdTotalCapacity(const std::string& segment_name) const override;
-    int64_t getSsdUsedBytes(const std::string& segment_name) const override;
-
-   private:
-    const std::unordered_map<std::string, UUID>&
-        client_by_name_;  // segment name -> client_id
-    std::unordered_map<UUID, std::shared_ptr<LocalDiskSegment>,
-                       boost::hash<UUID>>& client_local_disk_segment_;
+    const std::unordered_map<std::string, UUID>* client_by_name_{nullptr};
     std::shared_lock<std::shared_mutex> lock_;
 };
 
@@ -429,9 +365,10 @@ class SegmentSerializer {
     explicit SegmentSerializer(SegmentManager* segment_manager)
         : segment_manager_(segment_manager) {}
 
-    tl::expected<std::vector<uint8_t>, SerializationError> Serialize();
+    tl::expected<std::vector<uint8_t>, SerializationError> Serialize(
+        const LocalSsdPersistedState& local_ssd_state);
 
-    tl::expected<void, SerializationError> Deserialize(
+    tl::expected<LocalSsdPersistedState, SerializationError> Deserialize(
         const std::vector<uint8_t>& data);
 
     void Reset();
@@ -477,18 +414,33 @@ class SegmentManager {
      */
     ScopedAllocatorAccess getAllocatorAccess() {
         return ScopedAllocatorAccess(allocator_manager_, segments_by_host_,
-                                     segment_mutex_);
-    }
-
-    ScopedLocalDiskSegmentAccess getLocalDiskSegmentAccess() {
-        return ScopedLocalDiskSegmentAccess(
-            client_by_name_, client_local_disk_segment_, segment_mutex_);
+                                     client_by_name_, segment_mutex_);
     }
 
     SegmentView getView() const { return SegmentView(this); }
 
-    void initializeCxlAllocator(const std::string& cxl_path,
-                                const size_t cxl_size);
+    /**
+     * @brief Return current DRAM usage derived from mounted allocators.
+     *
+     * Shared allocators (for example the global CXL allocator) are counted
+     * once even when they are referenced by multiple mounted segments.
+     */
+    [[nodiscard]] StorageUsageSnapshot GetMemoryUsageSnapshot() const;
+
+    /**
+     * @brief Return aggregate DRAM usage in O(1) without segment_mutex_.
+     *
+     * Best-effort: used/capacity may tear briefly across mount/unmount,
+     * matching the previous metric-gauge watermark reads. An unmounted
+     * allocator may remain in the aggregate until in-flight allocate or
+     * deallocate calls drain and the last shared_ptr is dropped.
+     */
+    [[nodiscard]] StorageUsage GetMemoryUsage() const noexcept {
+        return usage_tracker_->GetUsage();
+    }
+
+    ErrorCode initializeCxlAllocator(const std::string& cxl_path,
+                                     size_t cxl_size);
 
     // Endpoint-based segment queries (for standby restore)
     bool HasSegmentByEndpoint(const std::string& endpoint) const;
@@ -496,6 +448,10 @@ class SegmentManager {
                              std::string& te_endpoint) const;
 
    private:
+    void AttachMountedUsageTrackers();
+
+    std::shared_ptr<StorageUsageTracker> usage_tracker_ =
+        std::make_shared<StorageUsageTracker>();
     mutable std::shared_mutex segment_mutex_;
     std::shared_ptr<AllocationStrategy> allocation_strategy_;
     const BufferAllocatorType
@@ -516,10 +472,6 @@ class SegmentManager {
         segment_id_by_name_;             // segment name -> segment_id
     HostSegmentIndex segments_by_host_;  // host_id -> segment name -> segment
                                          // ids for allocatable segments
-    std::unordered_map<UUID, std::shared_ptr<LocalDiskSegment>,
-                       boost::hash<UUID>>
-        client_local_disk_segment_;  // client_id -> local_disk_segment
-
     friend class ScopedSegmentAccess;
     friend class SegmentTest;        // for unit tests
     friend class SegmentView;        // for fork serialize
@@ -564,6 +516,23 @@ class NoFSegmentManager {
     void GetMountedSegmentsSnapshot(
         std::vector<MountedNoFSegmentSnapshot>& segments) const;
 
+    /**
+     * @brief Return current NoF usage derived from mounted allocators.
+     */
+    [[nodiscard]] StorageUsageSnapshot GetUsageSnapshot() const;
+
+    /**
+     * @brief Return aggregate NoF usage in O(1) without segment_mutex_.
+     *
+     * Best-effort: used/capacity may tear briefly across mount/unmount,
+     * matching the previous metric-gauge watermark reads. An unmounted
+     * allocator may remain in the aggregate until in-flight allocate or
+     * deallocate calls drain and the last shared_ptr is dropped.
+     */
+    [[nodiscard]] StorageUsage GetUsage() const noexcept {
+        return usage_tracker_->GetUsage();
+    }
+
     tl::expected<std::vector<NoFSegmentOwnerInfo>, ErrorCode> GetSegmentsByName(
         const std::string& segment_name) const {
         std::shared_lock<std::shared_mutex> lock(segment_mutex_);
@@ -580,6 +549,8 @@ class NoFSegmentManager {
     }
 
    private:
+    std::shared_ptr<StorageUsageTracker> usage_tracker_ =
+        std::make_shared<StorageUsageTracker>();
     mutable std::shared_mutex segment_mutex_;
     std::shared_ptr<AllocationStrategy> allocation_strategy_;
     const BufferAllocatorType
diff --git a/mooncake-store/include/segment/catalog.h b/mooncake-store/include/segment/catalog.h
new file mode 100644
index 0000000000..93f601a2e7
--- /dev/null
+++ b/mooncake-store/include/segment/catalog.h
@@ -0,0 +1,58 @@
+#pragma once
+
+#include <boost/functional/hash.hpp>
+#include <boost/multi_index_container.hpp>
+#include <boost/multi_index/hashed_index.hpp>
+#include <optional>
+#include <ranges>
+#include <string_view>
+
+#include "segment/mounted_region.h"
+#include "common/transparent_string_hash.h"
+
+namespace mooncake {
+
+class RegionCatalog final {
+    struct SegmentId {
+        using result_type = const UUID&;
+        result_type operator()(const MountedRegion& r) const {
+            return r.segment.id;
+        }
+    };
+    struct SegmentName {
+        using result_type = const std::string&;
+        result_type operator()(const MountedRegion& r) const {
+            return r.segment.name;
+        }
+    };
+    using Records = boost::multi_index_container<
+        MountedRegion,
+        boost::multi_index::indexed_by<
+            boost::multi_index::hashed_unique<SegmentId, boost::hash<UUID>>,
+            boost::multi_index::hashed_non_unique<
+                SegmentName, TransparentStringHash, std::equal_to<>>>>;
+
+   public:
+    // Borrowed records and ranges must not outlive the owner's Pool lock.
+    const MountedRegion* Find(const UUID& segment_id) const;
+    auto Regions() const { return std::views::all(records_); }
+    auto RegionIds(std::string_view name) const {
+        auto [first, last] = records_.get<1>().equal_range(name);
+        return std::ranges::subrange(first, last, std::distance(first, last)) |
+               std::views::transform([](const MountedRegion& r) -> const UUID& {
+                   return r.segment.id;
+               });
+    }
+    ErrorCode Register(const MountedRegion& mounted);
+    bool Erase(const UUID& segment_id);
+    bool SetStatus(const UUID& segment_id, SegmentStatus status);
+    void Clear();
+    std::optional<UUID> FindOwnerClientId(std::string_view name) const;
+
+   private:
+    Records records_;
+    // Never reset by Clear: outstanding transactions may outlive the records.
+    uint64_t next_generation_{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/mounted_region.h b/mooncake-store/include/segment/mounted_region.h
new file mode 100644
index 0000000000..b5ccf1c8ad
--- /dev/null
+++ b/mooncake-store/include/segment/mounted_region.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include <cstdint>
+
+#include "segment/region.h"
+#include "segment/status.h"
+
+namespace mooncake {
+
+struct MountedRegion {
+    Segment segment;
+    UUID client_id{0, 0};
+    SegmentStatus status{SegmentStatus::UNDEFINED};
+    RegionKind kind{RegionKind::HOST_MEMORY};
+    // Assigned by Catalog on registration and each lifecycle transition.
+    uint64_t generation{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/pool.h b/mooncake-store/include/segment/pool.h
new file mode 100644
index 0000000000..a4a15aa339
--- /dev/null
+++ b/mooncake-store/include/segment/pool.h
@@ -0,0 +1,81 @@
+#pragma once
+
+#include <shared_mutex>
+#include <unordered_set>
+#include <utility>
+
+#include "placement/index.h"
+#include "placement/replica_allocator.h"
+#include "segment/catalog.h"
+#include "segment/region_driver.h"
+#include "segment/snapshot.h"
+#include "segment/usage.h"
+#include "storage_usage.h"
+
+namespace mooncake {
+
+class SegmentPool final {
+    struct AccessKey {
+        explicit AccessKey() = default;
+    };
+
+   public:
+    class WriteAccess;
+    class ReadAccess;
+
+    explicit SegmentPool(RegionDriverRegistry region_drivers)
+        : region_drivers_(std::move(region_drivers)) {}
+    ~SegmentPool();
+
+    WriteAccess AcquireWriteAccess();
+    ReadAccess AcquireReadAccess() const;
+
+    // Capture detached data without acquiring pool/allocator locks. Only call
+    // in a forked snapshot child or with all relevant state externally
+    // quiesced. After capture, the result is independent of this pool's
+    // lifetime/mutations.
+    tl::expected<SegmentPoolSnapshot, ErrorCode> CaptureSnapshot() const;
+
+    // Consumes the snapshot, staging all resources before replacing the pool.
+    // Preparation failure leaves published state unchanged. Temporary readers
+    // may omit capacity accounting.
+    tl::expected<void, ErrorCode> RestoreSnapshot(
+        SegmentPoolSnapshot snapshot, bool account_capacity_metrics);
+
+    // Holds the Pool read lock through candidate selection and allocation.
+    template <ReplicaPlacementPolicy Policy = RandomPlacementPolicy>
+    tl::expected<std::vector<Replica>, ErrorCode> AllocateReplicas(
+        const ReplicaAllocationRequest& request, Policy policy = {},
+        PlacementDiagnostics* diagnostics = nullptr) const {
+        auto access = AcquirePlacementAccess();
+        return ReplicaAllocator<Policy>(std::move(policy))
+            .Allocate(access, request, diagnostics);
+    }
+    // Allocates one replica under the read lock, with no segment/kind fallback.
+    tl::expected<Replica, ErrorCode> AllocateInSegment(
+        std::string_view segment_name, AllocationCandidateKind kind,
+        size_t size, ReplicaType replica_type = ReplicaType::MEMORY) const;
+
+    [[nodiscard]] StorageUsageSnapshot GetMemoryUsageSnapshot() const;
+    [[nodiscard]] StorageUsage GetMemoryUsage() const noexcept {
+        return usage_tracker_->GetUsage();
+    }
+
+   private:
+    ScopedPlacementReadAccess AcquirePlacementAccess() const;
+    void ReleaseCapacityMetrics();
+    RegionDriver* GetDriver(RegionKind kind);
+    const RegionDriver* GetDriver(RegionKind kind) const;
+    RegionResource* GetResource(const MountedRegion& mounted);
+    const RegionResource* GetResource(const MountedRegion& mounted) const;
+
+    mutable std::shared_mutex pool_mutex_;
+    PlacementIndex placement_index_;
+    RegionDriverRegistry region_drivers_;
+    RegionCatalog catalog_;
+    std::unordered_set<UUID, boost::hash<UUID>> capacity_accounted_region_ids_;
+    std::shared_ptr<StorageUsageTracker> usage_tracker_ =
+        std::make_shared<StorageUsageTracker>();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/pool_read_access.h b/mooncake-store/include/segment/pool_read_access.h
new file mode 100644
index 0000000000..1acd6d5e98
--- /dev/null
+++ b/mooncake-store/include/segment/pool_read_access.h
@@ -0,0 +1,43 @@
+#pragma once
+
+#include <shared_mutex>
+
+#include "segment/pool.h"
+#include "placement/index.h"
+#include "segment/catalog.h"
+#include "segment/region_driver.h"
+
+namespace mooncake {
+
+class SegmentPool::ReadAccess final {
+   public:
+    ReadAccess(ReadAccess&&) noexcept = default;
+    ReadAccess& operator=(ReadAccess&&) noexcept = delete;
+    ReadAccess(const ReadAccess&) = delete;
+    ReadAccess& operator=(const ReadAccess&) = delete;
+
+    const RegionCatalog& Catalog() const;
+    const PlacementIndex& Placement() const;
+
+    std::shared_ptr<BufferAllocatorBase> GetAllocator(
+        const UUID& region_id) const;
+    // Usage of active placement candidates for this segment name and kind.
+    ErrorCode QueryAllocationCandidates(std::string_view name,
+                                        AllocationCandidateKind kind,
+                                        size_t& used, size_t& capacity) const;
+    bool IsInactive(const std::shared_ptr<BufferAllocatorBase>& allocator,
+                    std::string_view allocation_binding) const;
+
+    ReadAccess(AccessKey, const SegmentPool& segment_pool);
+
+   private:
+    const RegionDriver* GetDriver(RegionKind kind) const;
+    const RegionResource* GetResource(const MountedRegion& mounted) const;
+
+    std::shared_lock<std::shared_mutex> lock_;
+    const RegionCatalog& catalog_;
+    const RegionDriverRegistry& drivers_;
+    const PlacementIndex& placement_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/pool_write_access.h b/mooncake-store/include/segment/pool_write_access.h
new file mode 100644
index 0000000000..4cd1fabb2c
--- /dev/null
+++ b/mooncake-store/include/segment/pool_write_access.h
@@ -0,0 +1,88 @@
+#pragma once
+
+#include <memory>
+#include <shared_mutex>
+#include <span>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "segment/catalog.h"
+#include "segment/pool.h"
+
+namespace mooncake {
+
+class SegmentPool::WriteAccess final {
+    struct TransactionKey {
+        explicit TransactionKey() = default;
+    };
+
+   public:
+    class RegionMountTxn;
+    class RegionUnmountTxn;
+    class RegionGracefulUnmountTxn;
+
+    enum class AdoptMode { Insert, ReplacePool };
+
+    WriteAccess(AccessKey, SegmentPool& segment_pool);
+
+    ErrorCode MountSegment(const Segment& segment, const UUID& client_id);
+    tl::expected<RegionMountTxn, ErrorCode> PrepareMount(const Segment& segment,
+                                                         const UUID& client_id);
+    // Descriptors must use the canonical transport endpoint. The recovery
+    // caller resolves segment-name aliases before entering the Pool.
+    tl::expected<RegionMountTxn, ErrorCode> PrepareRestore(
+        const Segment& segment, const UUID& client_id,
+        std::span<const AllocatedBuffer::Descriptor> descriptors);
+    // ReplacePool ignores conflicts with the old catalog. The caller must
+    // validate the replacement and Clear() before committing transactions.
+    tl::expected<RegionMountTxn, ErrorCode> PrepareAdopt(
+        MountedRegion mounted, std::shared_ptr<BufferAllocatorBase> allocator,
+        bool account_capacity_metrics, AdoptMode mode = AdoptMode::Insert);
+    void Clear() noexcept;
+
+    tl::expected<RegionUnmountTxn, ErrorCode> PrepareUnmount(
+        const UUID& segment_id, const UUID& client_id);
+    tl::expected<RegionGracefulUnmountTxn, ErrorCode> PrepareGracefulUnmount(
+        const UUID& segment_id, const UUID& client_id);
+
+    const RegionCatalog& Catalog() const;
+    ErrorCode SetSegmentStatusByName(std::string_view segment_name,
+                                     SegmentStatus status);
+
+   private:
+    ErrorCode PublishMount(
+        const MountedRegion& mounted, bool existed,
+        bool account_capacity_metrics, PreparedRegionResource& prepared,
+        const std::weak_ptr<BufferAllocatorBase>& previous_allocator) noexcept;
+    ErrorCode RestoreUnmountedRegion(const UUID& segment_id,
+                                     const UUID& client_id,
+                                     SegmentStatus previous_status,
+                                     uint64_t generation);
+    tl::expected<RegionMountTxn, ErrorCode> PrepareWithLiveAllocations(
+        const Segment& segment, const UUID& client_id,
+        const std::vector<LiveAllocation>& live_allocations,
+        uint64_t imported_requested_bytes);
+    ErrorCode EraseUnmountedRegion(const UUID& segment_id,
+                                   const UUID& client_id,
+                                   SegmentStatus expected_status,
+                                   uint64_t generation);
+
+    ErrorCode TransitionRegion(const MountedRegion& mounted,
+                               RegionResource& resource, SegmentStatus status);
+
+    SegmentPool& segment_pool_;
+    std::unique_lock<std::shared_mutex> lock_;
+    RegionCatalog& catalog_;
+};
+
+using RegionMountTxn = SegmentPool::WriteAccess::RegionMountTxn;
+using RegionUnmountTxn = SegmentPool::WriteAccess::RegionUnmountTxn;
+using RegionGracefulUnmountTxn =
+    SegmentPool::WriteAccess::RegionGracefulUnmountTxn;
+
+}  // namespace mooncake
+
+#include "segment/transaction.h"
diff --git a/mooncake-store/include/segment/region.h b/mooncake-store/include/segment/region.h
new file mode 100644
index 0000000000..b1680f21f2
--- /dev/null
+++ b/mooncake-store/include/segment/region.h
@@ -0,0 +1,24 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+#include "types.h"
+
+namespace mooncake {
+
+enum class RegionKind {
+    HOST_MEMORY = 0,
+    CXL,
+};
+
+struct RegionResourceSpec {
+    UUID id{0, 0};
+    std::string name;
+    uintptr_t base{0};
+    size_t size{0};
+    std::string transport_endpoint;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/region_driver.h b/mooncake-store/include/segment/region_driver.h
new file mode 100644
index 0000000000..41a7048beb
--- /dev/null
+++ b/mooncake-store/include/segment/region_driver.h
@@ -0,0 +1,132 @@
+#pragma once
+
+#include <map>
+#include <memory>
+#include <optional>
+#include <span>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "allocator.h"
+#include "placement/candidate.h"
+#include "segment/region.h"
+
+namespace mooncake {
+
+struct RegionResource final {
+    explicit RegionResource(
+        std::unique_ptr<AllocationCandidate> allocation_candidate);
+
+    // Resource inspection is separate from the placement-only candidate API.
+    const std::shared_ptr<BufferAllocatorBase>& allocator() const noexcept {
+        return candidate->allocator_handle();
+    }
+
+    std::unique_ptr<AllocationCandidate> candidate;
+    bool active{false};
+};
+
+class RegionDriver {
+   public:
+    class PreparedRegionResource;
+    virtual ~RegionDriver() = default;
+
+    std::optional<BufferAllocatorType> allocator_type() const noexcept {
+        return allocator_type_;
+    }
+
+    virtual tl::expected<PreparedRegionResource, ErrorCode> PrepareOpen(
+        const RegionResourceSpec& spec,
+        const std::vector<LiveAllocation>& live_allocations) = 0;
+    virtual tl::expected<PreparedRegionResource, ErrorCode> PrepareAdopt(
+        const RegionResourceSpec& spec,
+        std::shared_ptr<BufferAllocatorBase> allocator) = 0;
+
+    RegionResource* GetResource(const UUID& id);
+    const RegionResource* GetResource(const UUID& id) const;
+    bool Deactivate(const UUID& id);
+    bool Reactivate(const UUID& id);
+    bool Erase(const UUID& id);
+
+   protected:
+    struct StageKey {
+        explicit StageKey() = default;
+    };
+
+    explicit RegionDriver(
+        std::optional<BufferAllocatorType> allocator_type = std::nullopt)
+        : allocator_type_(allocator_type) {}
+
+    PreparedRegionResource Stage(
+        const UUID& id, std::unique_ptr<RegionResource> resource,
+        std::vector<std::unique_ptr<AllocatedBuffer>> imported_buffers = {});
+
+   private:
+    using ResourceMap = std::map<UUID, std::unique_ptr<RegionResource>>;
+
+    // The caller retains the replaced resource until its indexes are updated.
+    std::unique_ptr<RegionResource> CommitPrepared(
+        ResourceMap::node_type& resource) noexcept;
+
+    const std::optional<BufferAllocatorType> allocator_type_;
+
+    ResourceMap resources_;
+};
+
+class RegionDriver::PreparedRegionResource final {
+   public:
+    ~PreparedRegionResource();
+
+    PreparedRegionResource(PreparedRegionResource&& other) noexcept;
+    PreparedRegionResource& operator=(PreparedRegionResource&& other) noexcept;
+    PreparedRegionResource(const PreparedRegionResource&) = delete;
+    PreparedRegionResource& operator=(const PreparedRegionResource&) = delete;
+
+    // The staged resource remains valid until Commit() or a move.
+    RegionResource& resource() const noexcept;
+    const std::vector<std::unique_ptr<AllocatedBuffer>>& imported_buffers()
+        const noexcept;
+    std::vector<std::unique_ptr<AllocatedBuffer>> TakeImportedBuffers();
+
+    void Commit() noexcept;
+
+    PreparedRegionResource(
+        StageKey, RegionDriver& driver, const UUID& id,
+        std::unique_ptr<RegionResource> resource,
+        std::vector<std::unique_ptr<AllocatedBuffer>> imported_buffers);
+
+   private:
+    struct State;
+    std::unique_ptr<State> state_;
+};
+
+using PreparedRegionResource = RegionDriver::PreparedRegionResource;
+
+using RegionDriverRegistry =
+    std::unordered_map<RegionKind, std::unique_ptr<RegionDriver>>;
+
+struct CxlRegionDriverConfig {
+    std::string path;
+    size_t size{0};
+};
+
+struct RegionDriverConfig {
+    BufferAllocatorType memory_allocator{BufferAllocatorType::CACHELIB};
+    std::optional<CxlRegionDriverConfig> cxl;
+};
+
+tl::expected<RegionDriverRegistry, ErrorCode> CreateRegionDrivers(
+    const RegionDriverConfig& config);
+
+// Converts descriptors that have already been canonicalized to
+// spec.transport_endpoint. Segment-name aliases must be resolved by the
+// recovery layer that owns the segment/catalog context before calling this
+// helper.
+tl::expected<std::vector<LiveAllocation>, ErrorCode> BuildRegionLiveAllocations(
+    const RegionResourceSpec& spec,
+    std::span<const AllocatedBuffer::Descriptor> descriptors);
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/snapshot.h b/mooncake-store/include/segment/snapshot.h
new file mode 100644
index 0000000000..32040e8297
--- /dev/null
+++ b/mooncake-store/include/segment/snapshot.h
@@ -0,0 +1,26 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "allocator.h"
+#include "segment/mounted_region.h"
+
+namespace mooncake {
+
+struct RegionSnapshot {
+    MountedRegion mounted;
+    OffsetBufferAllocatorSnapshot allocator;
+};
+
+// Detached, owning snapshot of the resources in the legacy host-memory format.
+// All metadata, including allocator bins/nodes, is copied. Encoding and
+// destroying this value never accesses a SegmentPool or changes runtime
+// capacity/usage.
+struct SegmentPoolSnapshot {
+    BufferAllocatorType memory_allocator_type = BufferAllocatorType::OFFSET;
+    std::vector<std::string> active_names;
+    std::vector<RegionSnapshot> regions;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/status.h b/mooncake-store/include/segment/status.h
new file mode 100644
index 0000000000..a7f41bfdef
--- /dev/null
+++ b/mooncake-store/include/segment/status.h
@@ -0,0 +1,67 @@
+#pragma once
+
+#include <ostream>
+
+namespace mooncake {
+
+enum class SegmentStatus {
+    UNDEFINED = 0,
+    OK,
+    DRAINING,
+    DRAINED,
+    GRACEFULLY_UNMOUNTING,
+    UNMOUNTING,
+};
+
+// Rejects raw integer values that do not map to a declared status.
+constexpr bool IsKnownSegmentStatus(SegmentStatus status) noexcept {
+    switch (status) {
+        case SegmentStatus::UNDEFINED:
+        case SegmentStatus::OK:
+        case SegmentStatus::DRAINING:
+        case SegmentStatus::DRAINED:
+        case SegmentStatus::GRACEFULLY_UNMOUNTING:
+        case SegmentStatus::UNMOUNTING:
+            return true;
+    }
+    return false;
+}
+
+constexpr int SegmentStatusAvailabilityRank(SegmentStatus status) noexcept {
+    switch (status) {
+        case SegmentStatus::OK:
+            return 0;
+        case SegmentStatus::DRAINING:
+            return 1;
+        case SegmentStatus::DRAINED:
+            return 2;
+        case SegmentStatus::GRACEFULLY_UNMOUNTING:
+            return 3;
+        case SegmentStatus::UNMOUNTING:
+            return 4;
+        case SegmentStatus::UNDEFINED:
+            return 5;
+    }
+    return 5;
+}
+
+inline std::ostream& operator<<(std::ostream& os,
+                                SegmentStatus status) noexcept {
+    switch (status) {
+        case SegmentStatus::UNDEFINED:
+            return os << "UNDEFINED";
+        case SegmentStatus::OK:
+            return os << "OK";
+        case SegmentStatus::DRAINING:
+            return os << "DRAINING";
+        case SegmentStatus::DRAINED:
+            return os << "DRAINED";
+        case SegmentStatus::GRACEFULLY_UNMOUNTING:
+            return os << "GRACEFULLY_UNMOUNTING";
+        case SegmentStatus::UNMOUNTING:
+            return os << "UNMOUNTING";
+    }
+    return os << "UNKNOWN";
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/transaction.h b/mooncake-store/include/segment/transaction.h
new file mode 100644
index 0000000000..f6e3e8eed0
--- /dev/null
+++ b/mooncake-store/include/segment/transaction.h
@@ -0,0 +1,117 @@
+#pragma once
+
+#include <memory>
+#include <utility>
+#include <vector>
+
+#include "segment/pool_write_access.h"
+#include "segment/mounted_region.h"
+#include "segment/region_driver.h"
+
+namespace mooncake {
+
+class PlacementIndex;
+
+// A prepared mount that has not yet been published to the catalog or
+// placement index. Destroying an uncommitted transaction releases the staged
+// driver resource.
+class SegmentPool::WriteAccess::RegionMountTxn final {
+   public:
+    RegionMountTxn(RegionMountTxn&&) noexcept = default;
+    RegionMountTxn& operator=(RegionMountTxn&&) noexcept = default;
+    RegionMountTxn(const RegionMountTxn&) = delete;
+    RegionMountTxn& operator=(const RegionMountTxn&) = delete;
+
+    // Commit with the write access that prepared this transaction, before
+    // releasing its lock. A conflicting catalog/resource change is rejected
+    // before the staged resource is published.
+    [[nodiscard]] ErrorCode Commit(SegmentPool::WriteAccess& access) noexcept;
+
+    const std::vector<std::unique_ptr<AllocatedBuffer>>& imported_buffers()
+        const noexcept {
+        return resource_.imported_buffers();
+    }
+    std::vector<std::unique_ptr<AllocatedBuffer>> TakeImportedBuffers() {
+        return resource_.TakeImportedBuffers();
+    }
+    uint64_t imported_requested_bytes() const noexcept {
+        return imported_requested_bytes_;
+    }
+
+    RegionMountTxn(TransactionKey, MountedRegion mounted, bool existed,
+                   bool account_capacity_metrics,
+                   PreparedRegionResource resource,
+                   uint64_t imported_requested_bytes = 0,
+                   std::weak_ptr<BufferAllocatorBase> previous_allocator = {})
+        : mounted_(std::move(mounted)),
+          existed_(existed),
+          account_capacity_metrics_(account_capacity_metrics),
+          resource_(std::move(resource)),
+          imported_requested_bytes_(imported_requested_bytes),
+          previous_allocator_(std::move(previous_allocator)) {}
+
+   private:
+    MountedRegion mounted_;
+    bool existed_;
+    bool account_capacity_metrics_;
+    PreparedRegionResource resource_;
+    uint64_t imported_requested_bytes_;
+    std::weak_ptr<BufferAllocatorBase> previous_allocator_;
+    bool committed_{false};
+};
+
+// Immediate unmount spans metadata cleanup while the Pool lock is released.
+// It therefore requires an explicit commit or rollback instead of destructor
+// rollback.
+class SegmentPool::WriteAccess::RegionUnmountTxn final {
+   public:
+    RegionUnmountTxn(RegionUnmountTxn&& other) noexcept;
+    RegionUnmountTxn& operator=(RegionUnmountTxn&&) = delete;
+    RegionUnmountTxn(const RegionUnmountTxn&) = delete;
+    RegionUnmountTxn& operator=(const RegionUnmountTxn&) = delete;
+
+    // Requires write access to the originating Pool; it may be reacquired
+    // after metadata cleanup. Each call consumes the transaction, including
+    // on failure; the moved-from transaction cannot be used again.
+    ErrorCode Commit(SegmentPool::WriteAccess& access) &&;
+    ErrorCode Rollback(SegmentPool::WriteAccess& access) &&;
+
+    const Segment& segment() const noexcept { return segment_; }
+
+    RegionUnmountTxn(TransactionKey, SegmentPool::WriteAccess& access,
+                     const MountedRegion& mounted, RegionResource& resource);
+
+   private:
+    Segment segment_;
+    UUID client_id_;
+    SegmentStatus previous_status_;
+    uint64_t generation_;
+    bool finished_{false};
+};
+
+// Stops new placement while existing replicas remain readable. Destruction
+// leaves the region draining; callers may prepare again to resume finalization.
+class SegmentPool::WriteAccess::RegionGracefulUnmountTxn final {
+   public:
+    RegionGracefulUnmountTxn(RegionGracefulUnmountTxn&& other) noexcept;
+    RegionGracefulUnmountTxn& operator=(RegionGracefulUnmountTxn&&) = delete;
+    RegionGracefulUnmountTxn(const RegionGracefulUnmountTxn&) = delete;
+    RegionGracefulUnmountTxn& operator=(const RegionGracefulUnmountTxn&) =
+        delete;
+
+    // Reacquire write access to the originating Pool after draining replicas.
+    // Finalize consumes the transaction, including on failure.
+    [[nodiscard]] ErrorCode Finalize(SegmentPool::WriteAccess& access) &&;
+
+    RegionGracefulUnmountTxn(TransactionKey, SegmentPool::WriteAccess& access,
+                             const MountedRegion& mounted,
+                             RegionResource& resource);
+
+   private:
+    UUID segment_id_;
+    UUID client_id_;
+    uint64_t generation_;
+    bool finished_{false};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment/usage.h b/mooncake-store/include/segment/usage.h
new file mode 100644
index 0000000000..42e89b9b93
--- /dev/null
+++ b/mooncake-store/include/segment/usage.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include <map>
+#include <string>
+
+#include "storage_usage.h"
+
+namespace mooncake {
+
+struct StorageUsageSnapshot : StorageUsage {
+    std::map<std::string, StorageUsage> segments;
+};
+
+struct TieredStorageUsageSnapshot {
+    StorageUsageSnapshot memory;
+    StorageUsageSnapshot nof;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/segment_allocator_registration.h b/mooncake-store/include/segment_allocator_registration.h
new file mode 100644
index 0000000000..fbdca4c318
--- /dev/null
+++ b/mooncake-store/include/segment_allocator_registration.h
@@ -0,0 +1,42 @@
+#pragma once
+
+#include <memory>
+
+#include "allocator.h"
+
+namespace mooncake {
+
+class ScopedNoFSegmentAccess;
+class ScopedSegmentAccess;
+class SegmentSerializer;
+template <typename T>
+class Serializer;
+class SegmentAllocatorRegistration {
+   public:
+    [[nodiscard]] bool IsServing() const;
+    [[nodiscard]] std::unique_ptr<AllocatedBuffer> Allocate(size_t size) const;
+    [[nodiscard]] std::shared_ptr<BufferAllocatorBase> GetAllocator() const;
+
+   private:
+    SegmentAllocatorRegistration(
+        std::shared_ptr<BufferAllocatorBase> allocator,
+        std::shared_ptr<ClientLivenessRecord> client_liveness);
+
+    void BindAllocator(std::shared_ptr<BufferAllocatorBase> replacement);
+    void BindClientLiveness(std::shared_ptr<ClientLivenessRecord> record);
+    void BindBuffer(AllocatedBuffer& buffer) const;
+    [[nodiscard]] bool OwnsBuffer(const AllocatedBuffer& buffer) const;
+    void SetAllocatable(bool allocatable);
+    void Invalidate();
+    std::shared_ptr<BufferAllocatorBase> allocator_;
+    SegmentLifetime allocation_lifetime_;
+    SegmentLifetime buffer_lifetime_;
+    std::shared_ptr<ClientLivenessRecord> client_liveness_;
+    friend class AllocatorManager;
+    friend class ScopedNoFSegmentAccess;
+    friend class ScopedSegmentAccess;
+    friend class SegmentSerializer;
+    friend class Serializer<AllocatedBuffer>;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/serialize/serializer.h b/mooncake-store/include/serialize/serializer.h
index 135e345ee4..88ab09e266 100644
--- a/mooncake-store/include/serialize/serializer.h
+++ b/mooncake-store/include/serialize/serializer.h
@@ -1,5 +1,8 @@
 #pragma once
 
+#include <cstdint>
+#include <vector>
+
 #include <ylt/util/expected.hpp>
 #include <ylt/util/tl/expected.hpp>
 #include <msgpack.hpp>
@@ -33,6 +36,9 @@ class Serializer<offset_allocator::__Allocator> {
    public:
     using PointerType = std::unique_ptr<offset_allocator::__Allocator>;
 
+    // Layout validation lives with the snapshot so every restore path shares
+    // one checker (OffsetAllocatorSnapshot::Validate); this codec only bounds
+    // the scalar capacities before decompressing node payloads.
     static tl::expected<void, SerializationError> serialize(
         const offset_allocator::__Allocator &allocator, MsgpackPacker &packer);
 
diff --git a/mooncake-store/include/shm_helper.h b/mooncake-store/include/shm_helper.h
index b7069ee056..e3fbac0aee 100644
--- a/mooncake-store/include/shm_helper.h
+++ b/mooncake-store/include/shm_helper.h
@@ -23,9 +23,18 @@ class ShmHelper {
     struct ShmSegment {
         int fd = -1;
         void *base_addr = nullptr;
+        // Size of the actual mapping; may be padded up to the hugepage/2MB
+        // boundary when SPDK registration is enabled
+        // (MC_STORE_REGISTER_SPDK=1).
         size_t size = 0;
+        // Size the caller requested in allocate(); == size unless padded.
+        // Callers that must match the original request (e.g.
+        // DummyClient::register_buffer) compare against this, not size, so they
+        // don't re-derive the alignment.
+        size_t requested_size = 0;
         std::string name;
         bool registered = false;
+        bool spdk_registered = false;
         bool is_local = false;
     };
 
@@ -45,6 +54,12 @@ class ShmHelper {
 
     bool is_hugepage() const { return use_hugepage_; }
 
+    // Whether the MC_STORE_REGISTER_SPDK feature is enabled (env == "1").
+    // Single source of truth for the env semantics, shared by ShmHelper's
+    // constructor and the RealClient-side (receiver) registration so both sides
+    // of the dummy/real split gate identically.
+    static bool is_register_spdk_enabled();
+
     ShmHelper(const ShmHelper &) = delete;
     ShmHelper &operator=(const ShmHelper &) = delete;
 
@@ -55,6 +70,7 @@ class ShmHelper {
     std::vector<std::shared_ptr<ShmSegment>> shms_;
     static std::mutex shm_mutex_;
     bool use_hugepage_ = false;
+    bool register_spdk_ = false;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/spdk/spdk_wrapper.h b/mooncake-store/include/spdk/spdk_wrapper.h
index 3dbb621fbb..e0ca16ab82 100644
--- a/mooncake-store/include/spdk/spdk_wrapper.h
+++ b/mooncake-store/include/spdk/spdk_wrapper.h
@@ -53,6 +53,52 @@ class SpdkWrapper {
     bool ProbeNofSegment(const std::string &tr_str, uint32_t timeout_ms,
                          std::string *error_reason = nullptr);
 
+    /** @brief Register external memory with SPDK for NoF zero-copy transfers.
+     *
+     * Memory returned by Alloc() is already registered with SPDK; use this to
+     * register memory allocated outside of SPDK (e.g. mmap'd shared memory) so
+     * that NoF RDMA transfers can DMA to/from it directly
+     * (spdk_rdma_get_translation).
+     *
+     * The pinned SPDK (v23.01.1) requires BOTH addr and size to be 2MB-aligned
+     * (MASK_2MB), and in iova=pa mode (the typical libibverbs NoF setup) the
+     * PHYSICAL pages must be 2MB-aligned too, which only HugeTLB pages satisfy.
+     * 4KB page-aligned memory always fails with -EINVAL. Callers must pass
+     * 2MB-aligned, hugepage-backed memory (ShmHelper forces this under
+     * MC_STORE_REGISTER_SPDK=1) and check IsRegistrableRange() first: a failure
+     * past that check may leave SPDK's g_mem_reg_map marked, so callers must
+     * attempt UnregisterMemory() and keep the mapping unless it returns 0.
+     *
+     * @param addr Start of the region; must be 2MB-aligned (hugepage-backed).
+     * @param size Region length; must be a multiple of 2MB.
+     * @return 0 on success, non-zero on failure.
+     */
+    int RegisterMemory(void *addr, size_t size);
+
+    /** @brief Unregister memory previously registered via RegisterMemory().
+     *
+     * Only a 0 return proves the range is clean. A non-zero return does NOT
+     * prove that nothing was ever registered: -EINVAL is also what SPDK
+     * returns for a half-registered range, so callers must keep the mapping
+     * alive (and retry) unless this returns 0. See the definition.
+     *
+     * @return 0 on success, non-zero on failure.
+     */
+    int UnregisterMemory(void *addr, size_t size);
+
+    /** @brief Whether RegisterMemory() can be attempted for this range at all.
+     *
+     * spdk_mem_register() rejects a range it cannot represent or that is not
+     * 2MB-aligned before it has marked anything (SPDK v23.01.1,
+     * lib/env_dpdk/memory.c:339-348), so a caller that skips the registration
+     * for such a range still munmaps normally. Any failure past this check may
+     * have left translation state behind and must be treated as such, with one
+     * exception the caller handles separately: -EBUSY means another owner
+     * already holds the range, so nothing new was marked and rolling back would
+     * clear their registration instead.
+     */
+    static bool IsRegistrableRange(void *addr, size_t size);
+
    private:
     struct ProbeBuffer {
         void *ptr{nullptr};
diff --git a/mooncake-store/include/storage/distributed/bucket_entry_layout.h b/mooncake-store/include/storage/distributed/bucket_entry_layout.h
new file mode 100644
index 0000000000..4a87f05f8a
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/bucket_entry_layout.h
@@ -0,0 +1,67 @@
+#pragma once
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "replica.h"
+
+namespace mooncake {
+
+/** Canonical bucket entry layout: [value bytes][zero padding]. */
+struct BucketEntryLayout {
+    uint64_t offset = 0;
+    uint64_t object_size = 0;
+    uint64_t aligned_size = 0;
+
+    uint64_t end() const { return offset + aligned_size; }
+};
+
+inline bool IsValidBucketAlignment(uint64_t alignment) {
+    return alignment != 0 && (alignment & (alignment - 1)) == 0;
+}
+
+inline std::optional<uint64_t> CheckedAlignUp(uint64_t value,
+                                              uint64_t alignment) {
+    if (!IsValidBucketAlignment(alignment) ||
+        value > std::numeric_limits<uint64_t>::max() - (alignment - 1)) {
+        return std::nullopt;
+    }
+    return (value + alignment - 1) & ~(alignment - 1);
+}
+
+inline std::optional<BucketEntryLayout> ComputeBucketEntryLayout(
+    uint64_t cursor, uint64_t value_size, uint64_t alignment) {
+    if (value_size == 0) return std::nullopt;
+    const auto offset = CheckedAlignUp(cursor, alignment);
+    const auto aligned_size = CheckedAlignUp(value_size, alignment);
+    if (!offset || !aligned_size ||
+        *aligned_size > std::numeric_limits<uint64_t>::max() - *offset) {
+        return std::nullopt;
+    }
+    return BucketEntryLayout{*offset, value_size, *aligned_size};
+}
+
+inline std::optional<BucketEntryLayout> RebuildBucketEntryLayout(
+    uint64_t offset, uint64_t object_size, uint64_t alignment) {
+    if (!IsValidBucketAlignment(alignment) || offset % alignment != 0) {
+        return std::nullopt;
+    }
+    const auto layout =
+        ComputeBucketEntryLayout(offset, object_size, alignment);
+    if (!layout || layout->offset != offset) return std::nullopt;
+    return layout;
+}
+
+inline DistributedFSDescriptor MakeBucketDescriptor(
+    std::string data_path, const BucketEntryLayout& layout, int64_t bucket_id) {
+    return DistributedFSDescriptor{std::move(data_path), layout.offset,
+                                   layout.object_size, layout.aligned_size,
+                                   static_cast<int>(bucket_id)};
+}
+
+inline constexpr int64_t kMaxBucketId =
+    static_cast<int64_t>(std::numeric_limits<int32_t>::max());
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/dfs_allocator_interface.h b/mooncake-store/include/storage/distributed/dfs_allocator_interface.h
new file mode 100644
index 0000000000..d25403326e
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/dfs_allocator_interface.h
@@ -0,0 +1,77 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "replica.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct DistributedStorageConfig;
+
+enum class DfsAllocatorType {
+    SHARD,
+    BUCKET,
+};
+
+std::optional<DfsAllocatorType> ParseDfsAllocatorType(std::string_view name);
+const char* ToString(DfsAllocatorType type);
+
+struct BatchAllocateRequest {
+    std::string key;
+    uint64_t size = 0;
+};
+
+struct BatchAllocateResult {
+    std::string key;
+    DistributedFSDescriptor descriptor;
+    bool success = false;
+    ErrorCode error = ErrorCode::OK;
+};
+
+/**
+ * Common interface for DFS space allocators.
+ *
+ * DistributedFSDescriptor remains wire-compatible. In bucket mode its
+ * shard_idx member carries the bucket id.
+ */
+class DfsAllocatorInterface {
+   public:
+    struct EvictionCandidate {
+        std::string key;
+        int shard_idx = 0;
+        uint64_t offset = 0;
+        DistributedFSDescriptor descriptor;
+    };
+
+    virtual ~DfsAllocatorInterface() = default;
+
+    virtual DfsAllocatorType Type() const = 0;
+    virtual tl::expected<void, ErrorCode> Init(
+        const DistributedStorageConfig& config) = 0;
+    virtual bool IsInitialized() const = 0;
+
+    virtual tl::expected<DistributedFSDescriptor, ErrorCode> Allocate(
+        const std::string& key, uint64_t size) = 0;
+    virtual std::vector<BatchAllocateResult> BatchAllocate(
+        const std::vector<BatchAllocateRequest>& requests) = 0;
+
+    virtual void Free(const std::string& key,
+                      const DistributedFSDescriptor& descriptor) = 0;
+    virtual void UpdateAccess(const std::string& key,
+                              const DistributedFSDescriptor& descriptor) = 0;
+
+    virtual bool IsEvictionEnabled() const = 0;
+    virtual std::chrono::seconds GetEvictionCheckInterval() const = 0;
+    virtual uint64_t GetUsedBytes() const = 0;
+    virtual uint64_t GetTotalCapacity() const = 0;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/dfs_global_allocator.h b/mooncake-store/include/storage/distributed/dfs_global_allocator.h
new file mode 100644
index 0000000000..4b500875b4
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/dfs_global_allocator.h
@@ -0,0 +1,193 @@
+#pragma once
+
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <deque>
+#include <list>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "offset_allocator/offset_allocator.h"
+#include "replica.h"
+#include "storage/distributed/fs_adapter.h"
+#include "storage/distributed/dfs_allocator_interface.h"
+#include "types.h"
+
+namespace mooncake {
+
+struct DistributedStorageConfig;
+
+class DfsGlobalAllocator final : public DfsAllocatorInterface {
+   public:
+    struct EvictionCandidate {
+        std::string key;
+        int shard_idx;
+        uint64_t offset;
+    };
+
+    // Keeps selected allocations pinned while the master decides which
+    // candidates can be evicted. An unresolved transaction is aborted on
+    // destruction so candidates cannot get stuck outside the LRU.
+    class PendingEviction {
+       public:
+        PendingEviction() = default;
+        ~PendingEviction();
+
+        PendingEviction(const PendingEviction&) = delete;
+        PendingEviction& operator=(const PendingEviction&) = delete;
+        PendingEviction(PendingEviction&& other) noexcept;
+        PendingEviction& operator=(PendingEviction&&) = delete;
+
+        bool Empty() const { return candidates_.empty(); }
+        const std::vector<EvictionCandidate>& Candidates() const {
+            return candidates_;
+        }
+
+       private:
+        friend class DfsGlobalAllocator;
+
+        struct PreparedAllocation {
+            EvictionCandidate candidate;
+            std::shared_ptr<offset_allocator::OffsetAllocationHandle> handle;
+            uint64_t bytes = 0;
+        };
+
+        explicit PendingEviction(DfsGlobalAllocator* owner) : owner_(owner) {}
+
+        DfsGlobalAllocator* owner_ = nullptr;
+        std::vector<EvictionCandidate> candidates_;
+        std::vector<PreparedAllocation> prepared_;
+    };
+
+    DfsGlobalAllocator() = default;
+    ~DfsGlobalAllocator() override;
+
+    DfsGlobalAllocator(const DfsGlobalAllocator&) = delete;
+    DfsGlobalAllocator& operator=(const DfsGlobalAllocator&) = delete;
+
+    DfsAllocatorType Type() const override { return DfsAllocatorType::SHARD; }
+
+    tl::expected<void, ErrorCode> Init(
+        const DistributedStorageConfig& config) override;
+    bool IsInitialized() const override {
+        return initialized_.load(std::memory_order_acquire);
+    }
+
+    // Append shards without moving existing allocations. Equal counts are
+    // idempotent; shrinking is not supported. The returned count is ready for
+    // allocation only after every new shard has been initialized.
+    tl::expected<int, ErrorCode> ExpandShards(int target_count);
+    int GetShardCount() const;
+
+    tl::expected<DistributedFSDescriptor, ErrorCode> Allocate(
+        const std::string& key, uint64_t size) override;
+    std::vector<BatchAllocateResult> BatchAllocate(
+        const std::vector<BatchAllocateRequest>& requests) override;
+    void Free(const std::string& key,
+              const DistributedFSDescriptor& descriptor) override;
+    void UpdateAccess(const std::string& key,
+                      const DistributedFSDescriptor& descriptor) override;
+    void Free(uint64_t offset, uint64_t aligned_size, int shard_idx,
+              const std::string& key);
+    void UpdateAccess(const std::string& key, int shard_idx, uint64_t offset);
+    PendingEviction PrepareEviction();
+    void CommitPreparedEviction(PendingEviction&& pending);
+    void RestorePreparedEviction(PendingEviction&& pending);
+    void ResolvePreparedEviction(PendingEviction&& pending,
+                                 const std::vector<bool>& accepted);
+
+    bool IsEvictionEnabled() const override { return eviction_enabled_; }
+    std::chrono::seconds GetEvictionCheckInterval() const override {
+        return eviction_check_interval_;
+    }
+    uint64_t GetUsedBytes() const override;
+    uint64_t GetTotalCapacity() const override;
+
+    static std::string FormatShardIdx(int idx, int shard_count);
+
+   private:
+    using OffsetAllocator = offset_allocator::OffsetAllocator;
+    using OffsetAllocationHandle = offset_allocator::OffsetAllocationHandle;
+
+    struct ShardState {
+        std::string path;
+        uint64_t capacity = 0;
+        std::shared_ptr<OffsetAllocator> allocator;
+
+        struct AllocationRecord {
+            std::string key;
+            std::shared_ptr<OffsetAllocationHandle> handle;
+            uint64_t bytes = 0;
+            bool eviction_prepared = false;
+        };
+
+        std::shared_mutex handle_mutex;
+        std::unordered_map<uint64_t, AllocationRecord> offset_to_handle;
+
+        std::mutex lru_mutex;
+        std::list<std::pair<std::string, uint64_t>> lru_list;
+        std::unordered_map<std::string, decltype(lru_list)::iterator> lru_index;
+        // Once the high watermark is crossed, keep selecting candidates until
+        // effective usage falls below the low watermark. Protected candidates
+        // may make that span multiple prepare/resolve rounds.
+        bool eviction_active = false;
+
+        struct PendingFree {
+            std::shared_ptr<OffsetAllocationHandle> handle;
+            uint64_t bytes = 0;
+            std::chrono::steady_clock::time_point when;
+        };
+        std::mutex pending_mutex;
+        std::deque<PendingFree> pending_free;
+        uint64_t pending_free_bytes = 0;
+    };
+
+    using ShardList = std::vector<std::shared_ptr<ShardState>>;
+
+    tl::expected<std::shared_ptr<ShardState>, ErrorCode> CreateShard(
+        const std::string& path, std::vector<std::string>& created_files);
+    void CleanupCreatedFiles(const std::vector<std::string>& created_files);
+
+    static constexpr size_t kNumKeyStripes = 65536;
+
+    std::unique_lock<std::mutex> LockKey(const std::string& key) {
+        return std::unique_lock<std::mutex>(
+            key_stripes_[std::hash<std::string>{}(key) % kNumKeyStripes]);
+    }
+
+    void QueuePendingFree(ShardState& shard,
+                          const std::shared_ptr<OffsetAllocationHandle>& handle,
+                          uint64_t bytes,
+                          std::chrono::steady_clock::time_point when);
+    void CleanupExpiredPendingFrees(ShardState& shard,
+                                    std::chrono::steady_clock::time_point now);
+    double EffectiveUsage(ShardState& shard);
+    void PrepareEvictionFromShard(ShardState& shard, int shard_idx,
+                                  PendingEviction& pending);
+    uint64_t AlignSize(uint64_t size) const;
+
+    std::string mount_path_;
+    uint64_t shard_capacity_ = 0;
+    uint64_t alignment_ = 4096;
+    // Readers retain an immutable topology snapshot. Expansion shares existing
+    // ShardState objects and publishes the complete new topology in one step.
+    std::shared_ptr<const ShardList> shards_;
+    std::mutex expansion_mutex_;
+    std::unique_ptr<FileSystemAdapter> fs_adapter_;
+    bool eviction_enabled_ = true;
+    double eviction_high_watermark_ = 0.9;
+    double eviction_low_watermark_ = 0.7;
+    std::chrono::seconds deferred_free_duration_{30};
+    std::chrono::seconds eviction_check_interval_{5};
+    std::atomic<bool> initialized_{false};
+    std::array<std::mutex, kNumKeyStripes> key_stripes_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/distributed_storage_backend.h b/mooncake-store/include/storage/distributed/distributed_storage_backend.h
index fe733b7fde..b220ca277e 100644
--- a/mooncake-store/include/storage/distributed/distributed_storage_backend.h
+++ b/mooncake-store/include/storage/distributed/distributed_storage_backend.h
@@ -1,27 +1,45 @@
 #pragma once
 
+#include <cstdint>
 #include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
 
+#include "config/distributed_storage_config.h"
 #include "fs_adapter.h"
+#include "replica.h"
+#include "storage/distributed/object_storage_adapter.h"
 #include "storage_backend.h"
 
 namespace mooncake {
 
-struct DistributedStorageConfig {
-    std::string fsdir = "distributed_dir";
-    std::string fs_adapter_type = "hf3fs";
-    bool enable_health_check = false;
-    int hash_bucket_count = 256;
+// Filesystem mode is the descriptor-based shard/offset DFS data path. Object
+// storage remains a separate, logical-key-oriented I/O mode.
+enum class DistributedStorageMode {
+    kFileSystem,
+    kObjectStorage,
+};
+
+struct DfsWriteRequest {
+    std::string key;
+    DistributedFSDescriptor descriptor;
+    std::vector<Slice> slices;
+};
 
-    bool Validate() const;
-    static DistributedStorageConfig FromEnvironment();
+struct DfsReadRequest {
+    std::string key;
+    DistributedFSDescriptor descriptor;
+    std::vector<Slice> slices;
 };
 
 /**
- * @brief Distributed filesystem storage backend.
+ * @brief Distributed filesystem and object storage backend.
  *
- * Implements StorageBackendInterface, delegating I/O to a FileSystemAdapter.
- * Does not handle eviction (DFS manages its own space).
+ * Uses a FileSystemAdapter for descriptor-based DFS reads and writes, or an
+ * ObjectStorageAdapter for whole-object offload operations. Does not handle
+ * eviction.
  */
 class DistributedStorageBackend : public StorageBackendInterface {
    public:
@@ -29,6 +47,20 @@ class DistributedStorageBackend : public StorageBackendInterface {
         const FileStorageConfig& file_storage_config,
         const DistributedStorageConfig& distributed_config,
         std::unique_ptr<FileSystemAdapter> fs_adapter);
+    ~DistributedStorageBackend() override;
+
+    // Exactly one adapter must be non-null.
+    DistributedStorageBackend(
+        const FileStorageConfig& file_storage_config,
+        const DistributedStorageConfig& distributed_config,
+        std::unique_ptr<FileSystemAdapter> fs_adapter,
+        std::unique_ptr<ObjectStorageAdapter> object_storage_adapter);
+
+    DistributedStorageMode GetStorageMode() const { return storage_mode_; }
+
+    bool UsesObjectStorage() const {
+        return storage_mode_ == DistributedStorageMode::kObjectStorage;
+    }
 
     tl::expected<void, ErrorCode> Init() override;
 
@@ -39,6 +71,14 @@ class DistributedStorageBackend : public StorageBackendInterface {
             complete_handler,
         EvictionHandler eviction_handler = nullptr) override;
 
+    std::vector<tl::expected<void, ErrorCode>> BatchWrite(
+        const std::vector<DfsWriteRequest>& requests);
+
+    std::vector<tl::expected<void, ErrorCode>> BatchRead(
+        const std::vector<DfsReadRequest>& requests);
+
+    // Key-only storage backend operations cannot safely address DFS objects;
+    // callers must use BatchRead/BatchWrite with request-scoped descriptors.
     tl::expected<void, ErrorCode> BatchLoad(
         std::unordered_map<std::string, Slice>& batched_slices) override;
 
@@ -52,14 +92,30 @@ class DistributedStorageBackend : public StorageBackendInterface {
             std::vector<StorageObjectMetadata>& metadatas)>& handler) override;
 
    private:
-    std::string GetObjectPath(const std::string& key) const;
-    static std::string EscapeFilename(const std::string& key);
-    static std::string UnescapeFilename(const std::string& name);
+    struct ShardFile {
+        std::string path;
+        int fd = -1;
+        std::mutex mutex;
+    };
+
+    tl::expected<ShardFile*, ErrorCode> GetOrOpenShard(
+        const DistributedFSDescriptor& descriptor);
+    tl::expected<int, ErrorCode> OpenBucket(
+        const DistributedFSDescriptor& descriptor);
+    bool UsesBucketAllocator() const;
 
     std::unique_ptr<FileSystemAdapter> fs_adapter_;
+    std::unique_ptr<ObjectStorageAdapter> object_storage_adapter_;
     DistributedStorageConfig distributed_config_;
     std::string root_dir_;
-    int hash_bucket_count_;
+    // Create shard entries only from descriptors published by the master.
+    // The cache lock protects lookup/insertion; each shard's mutex protects
+    // initialization (fd stays -1 until opening succeeds) and positional I/O.
+    // Entries are never erased while the backend is running, so callers can
+    // retain a ShardFile pointer after releasing the cache lock.
+    std::mutex shard_files_mutex_;
+    std::unordered_map<int, std::unique_ptr<ShardFile>> shard_files_;
+    DistributedStorageMode storage_mode_ = DistributedStorageMode::kFileSystem;
     bool initialized_ = false;
 };
 
diff --git a/mooncake-store/include/storage/distributed/fs_adapter.h b/mooncake-store/include/storage/distributed/fs_adapter.h
index defda61647..ee2bf9999a 100644
--- a/mooncake-store/include/storage/distributed/fs_adapter.h
+++ b/mooncake-store/include/storage/distributed/fs_adapter.h
@@ -97,6 +97,41 @@ class FileSystemAdapter {
         return result;
     }
 
+    // === fd-based I/O for shard-offset DFS mode ===
+
+    virtual tl::expected<int, ErrorCode> OpenFile(const std::string& /*path*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
+    // Open a file that must already exist. Implementations must not use
+    // O_CREAT: bucket descriptors can arrive after whole-bucket eviction.
+    virtual tl::expected<int, ErrorCode> OpenExistingFile(
+        const std::string& /*path*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
+    virtual tl::expected<void, ErrorCode> CloseFile(int /*fd*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
+    virtual tl::expected<void, ErrorCode> PreallocateFile(
+        const std::string& /*path*/, uint64_t /*size*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
+    virtual tl::expected<size_t, ErrorCode> WriteAt(int /*fd*/,
+                                                    const iovec* /*iov*/,
+                                                    int /*iovcnt*/,
+                                                    int64_t /*offset*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
+    virtual tl::expected<size_t, ErrorCode> ReadAt(int /*fd*/, iovec* /*iov*/,
+                                                   int /*iovcnt*/,
+                                                   int64_t /*offset*/) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+
     // === Lifecycle ===
 
     virtual tl::expected<void, ErrorCode> Init(
diff --git a/mooncake-store/include/storage/distributed/hf3fs_adapter.h b/mooncake-store/include/storage/distributed/hf3fs_adapter.h
index 4b0fa05f8f..6a713e7457 100644
--- a/mooncake-store/include/storage/distributed/hf3fs_adapter.h
+++ b/mooncake-store/include/storage/distributed/hf3fs_adapter.h
@@ -38,6 +38,23 @@ class Hf3fsAdapter : public FileSystemAdapter {
     tl::expected<std::vector<std::string>, ErrorCode> ListFiles(
         const std::string& dir) override;
 
+    tl::expected<int, ErrorCode> OpenFile(const std::string& path) override;
+
+    tl::expected<int, ErrorCode> OpenExistingFile(
+        const std::string& path) override;
+
+    tl::expected<void, ErrorCode> CloseFile(int fd) override;
+
+    tl::expected<void, ErrorCode> PreallocateFile(const std::string& path,
+                                                  uint64_t size) override;
+
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override;
+
+    tl::expected<size_t, ErrorCode> ReadAt(int fd, iovec* iov, int iovcnt,
+                                           int64_t offset) override;
+
     tl::expected<void, ErrorCode> Init(const std::string& mount_path) override;
 
     tl::expected<void, ErrorCode> Shutdown() override;
diff --git a/mooncake-store/include/storage/distributed/immutable_bucket_allocator.h b/mooncake-store/include/storage/distributed/immutable_bucket_allocator.h
new file mode 100644
index 0000000000..db2e1db711
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/immutable_bucket_allocator.h
@@ -0,0 +1,191 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <list>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "storage/distributed/bucket_entry_layout.h"
+#include "storage/distributed/fs_adapter.h"
+#include "storage/distributed/dfs_allocator_interface.h"
+
+namespace mooncake {
+
+struct DistributedStorageConfig;
+
+enum class BucketEntryState : int32_t {
+    PENDING = 0,    // Reserved while the client write is in progress.
+    COMMITTED = 1,  // Finalized and eligible for whole-bucket eviction.
+    TOMBSTONE = 2,  // Released without making its append range reusable.
+};
+
+enum class BucketLifecycle : int32_t {
+    ACTIVE = 0,    // Current append target.
+    SEALED = 1,    // Closed to appends and eligible for LRU selection.
+    FROZEN = 2,    // Reserved by the validation phase of eviction.
+    EVICTING = 3,  // Being deleted or waiting for deletion retry.
+    RETIRED = 4,   // Deleted and ready to leave runtime state.
+};
+
+/**
+ * Runtime-only append allocator for immutable DFS bucket files.
+ *
+ * No allocator metadata is persisted. Init therefore rejects a DFS root that
+ * already contains a bucket data or metadata file instead of guessing whether
+ * it belongs to this process. MarkCommitted records only runtime state.
+ */
+class ImmutableBucketAllocator final : public DfsAllocatorInterface {
+   public:
+    ImmutableBucketAllocator() = default;
+    ~ImmutableBucketAllocator() override;
+
+    ImmutableBucketAllocator(const ImmutableBucketAllocator&) = delete;
+    ImmutableBucketAllocator& operator=(const ImmutableBucketAllocator&) =
+        delete;
+
+    DfsAllocatorType Type() const override { return DfsAllocatorType::BUCKET; }
+    tl::expected<void, ErrorCode> Init(
+        const DistributedStorageConfig& config) override;
+    bool IsInitialized() const override {
+        return initialized_.load(std::memory_order_acquire);
+    }
+
+    tl::expected<DistributedFSDescriptor, ErrorCode> Allocate(
+        const std::string& key, uint64_t size) override;
+    std::vector<BatchAllocateResult> BatchAllocate(
+        const std::vector<BatchAllocateRequest>& requests) override;
+    void Free(const std::string& key,
+              const DistributedFSDescriptor& descriptor) override;
+    void UpdateAccess(const std::string& key,
+                      const DistributedFSDescriptor& descriptor) override;
+
+    bool IsEvictionEnabled() const override { return eviction_enabled_; }
+    std::chrono::seconds GetEvictionCheckInterval() const override {
+        return eviction_check_interval_;
+    }
+    uint64_t GetUsedBytes() const override;
+    uint64_t GetTotalCapacity() const override;
+
+    bool MarkCommitted(const std::string& key,
+                       const DistributedFSDescriptor& descriptor);
+
+    class PendingEviction {
+       public:
+        PendingEviction() = default;
+        ~PendingEviction();
+        PendingEviction(const PendingEviction&) = delete;
+        PendingEviction& operator=(const PendingEviction&) = delete;
+        PendingEviction(PendingEviction&& other) noexcept;
+        PendingEviction& operator=(PendingEviction&& other) noexcept;
+
+        bool Empty() const { return owner_ == nullptr; }
+        int64_t bucket_id() const { return bucket_id_; }
+        const std::vector<EvictionCandidate>& Candidates() const {
+            return candidates_;
+        }
+
+       private:
+        friend class ImmutableBucketAllocator;
+        ImmutableBucketAllocator* owner_ = nullptr;
+        int64_t bucket_id_ = -1;
+        std::shared_ptr<void> identity_;
+        std::vector<EvictionCandidate> candidates_;
+    };
+
+    class EvictedBucket {
+       public:
+        EvictedBucket() = default;
+        EvictedBucket(const EvictedBucket&) = delete;
+        EvictedBucket& operator=(const EvictedBucket&) = delete;
+        EvictedBucket(EvictedBucket&& other) noexcept;
+        EvictedBucket& operator=(EvictedBucket&& other) noexcept;
+
+        bool Empty() const { return bucket_id_ < 0; }
+        int64_t bucket_id() const { return bucket_id_; }
+
+       private:
+        friend class ImmutableBucketAllocator;
+        int64_t bucket_id_ = -1;
+        std::shared_ptr<void> identity_;
+    };
+
+    PendingEviction PrepareEviction();
+    PendingEviction PrepareEvictionForAllocationFailure();
+    // Callers coordinating external metadata must commit the allocator state
+    // while holding the same metadata locks, then delete the file after those
+    // locks are released.
+    tl::expected<EvictedBucket, ErrorCode> CommitEvictionLogical(
+        PendingEviction&& pending);
+    tl::expected<void, ErrorCode> DeleteEvictedBucket(EvictedBucket&& bucket);
+    void AbortEviction(PendingEviction&& pending);
+    size_t RetryFailedEvictions();
+
+    size_t GetBucketCount() const;
+    std::optional<int64_t> GetBucketIdForKey(const std::string& key) const;
+    static std::string FormatBucketId(int64_t bucket_id);
+
+   private:
+    friend class PendingEviction;
+
+    struct BucketEntry {
+        BucketEntryLayout layout;
+        BucketEntryState state = BucketEntryState::PENDING;
+    };
+
+    struct BucketState {
+        int64_t id = -1;
+        uint64_t capacity = 0;
+        uint64_t append_offset = 0;
+        uint64_t pending_entries = 0;
+        BucketLifecycle lifecycle = BucketLifecycle::ACTIVE;
+        std::unordered_map<std::string, BucketEntry> entries;
+    };
+    using BucketPtr = std::shared_ptr<BucketState>;
+
+    std::string BucketDataPath(int64_t bucket_id) const;
+    tl::expected<BucketPtr, ErrorCode> EnsureActiveBucketLocked(
+        uint64_t required);
+    tl::expected<DistributedFSDescriptor, ErrorCode> ReserveInBucketLocked(
+        BucketState& bucket, const std::string& key, uint64_t size);
+    BucketEntry* FindMatchingEntryLocked(
+        const std::string& key, const DistributedFSDescriptor& descriptor,
+        BucketPtr* bucket);
+    void TombstoneLocked(const std::string& key, BucketState& bucket,
+                         BucketEntry& entry);
+    void TouchLruLocked(int64_t bucket_id);
+    void AbortEvictionLocked(PendingEviction& pending, bool warm);
+    PendingEviction PrepareEvictionLocked(bool force_one);
+    uint64_t UsedBytesLocked() const;
+
+    std::string fsdir_;
+    std::unique_ptr<FileSystemAdapter> fs_adapter_;
+    uint64_t bucket_capacity_ = 0;
+    uint64_t alignment_ = 4096;
+    int64_t max_bucket_count_ = 0;
+    bool eviction_enabled_ = true;
+    double eviction_high_watermark_ = 0.9;
+    double eviction_low_watermark_ = 0.7;
+    std::chrono::seconds eviction_check_interval_{5};
+
+    mutable std::mutex mutex_;
+    std::unordered_map<int64_t, BucketPtr> buckets_;
+    std::unordered_map<std::string, int64_t> key_index_;
+    std::list<int64_t> lru_;
+    std::unordered_map<int64_t, std::list<int64_t>::iterator> lru_index_;
+    std::unordered_set<int64_t> failed_deletions_;
+    int64_t active_bucket_id_ = -1;
+    int64_t next_bucket_id_ = 0;
+    bool eviction_active_ = false;
+    std::atomic<bool> initialized_{false};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/object_storage_adapter.h b/mooncake-store/include/storage/distributed/object_storage_adapter.h
new file mode 100644
index 0000000000..7d2c824033
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/object_storage_adapter.h
@@ -0,0 +1,106 @@
+#pragma once
+
+#include <sys/uio.h>
+
+#include <span>
+#include <string>
+#include <vector>
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct KeyInfo {
+    // Decoded Mooncake logical key, not a provider-specific physical key.
+    std::string logical_key;
+    size_t size = 0;
+};
+
+struct ObjectPutRequest {
+    std::string logical_key;
+    const iovec* iov = nullptr;
+    int iovcnt = 0;
+};
+
+struct ObjectGetRequest {
+    std::string logical_key;
+    void* buffer = nullptr;
+    size_t size = 0;
+};
+
+/**
+ * @brief Adapts object storage services to the distributed backend's
+ * key-value I/O contract.
+ *
+ * All key parameters are opaque Mooncake logical keys and may contain
+ * arbitrary bytes. Implementations own the reversible mapping between logical
+ * keys and their configured physical object namespace, including prefixing,
+ * encoding, and provider-specific validation.
+ */
+class ObjectStorageAdapter {
+   public:
+    virtual ~ObjectStorageAdapter() = default;
+
+    virtual tl::expected<void, ErrorCode> Put(const std::string& logical_key,
+                                              std::span<const char> data) = 0;
+
+    // Atomic multi-region write: one commit and one result.
+    virtual tl::expected<void, ErrorCode> PutV(const std::string& logical_key,
+                                               const iovec* iov,
+                                               int iovcnt) = 0;
+
+    virtual tl::expected<size_t, ErrorCode> Get(const std::string& logical_key,
+                                                void* buf, size_t len) = 0;
+
+    // Batch methods may be overridden by concurrent adapters. The default
+    // implementation preserves compatibility by executing requests serially.
+    // Return exactly one result per request, in the same order. Referenced
+    // buffers and iovec arrays must remain valid until the synchronous batch
+    // call returns. Upload descriptors and payloads must remain unchanged.
+    virtual std::vector<tl::expected<void, ErrorCode>> PutBatch(
+        const std::vector<ObjectPutRequest>& requests) {
+        std::vector<tl::expected<void, ErrorCode>> results;
+        results.reserve(requests.size());
+        for (const auto& request : requests) {
+            results.emplace_back(
+                PutV(request.logical_key, request.iov, request.iovcnt));
+        }
+        return results;
+    }
+
+    virtual std::vector<tl::expected<size_t, ErrorCode>> GetBatch(
+        const std::vector<ObjectGetRequest>& requests) {
+        std::vector<tl::expected<size_t, ErrorCode>> results;
+        results.reserve(requests.size());
+        for (const auto& request : requests) {
+            results.emplace_back(
+                Get(request.logical_key, request.buffer, request.size));
+        }
+        return results;
+    }
+
+    virtual tl::expected<bool, ErrorCode> Exists(
+        const std::string& logical_key) = 0;
+
+    virtual tl::expected<void, ErrorCode> Delete(
+        const std::string& logical_key) = 0;
+
+    // Pagination is an implementation detail. Returns decoded logical keys
+    // from the adapter's configured physical namespace.
+    virtual tl::expected<std::vector<KeyInfo>, ErrorCode> ListKeys() = 0;
+
+    virtual tl::expected<void, ErrorCode> Init() = 0;
+
+    // Performs an end-to-end service check after Init(). Implementations may
+    // create a temporary object but must make a best effort to clean it up.
+    // Optional for source compatibility. Enabling health checks on an adapter
+    // without an override fails explicitly instead of reporting a false
+    // success.
+    virtual tl::expected<void, ErrorCode> CheckHealth() {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
+    virtual const char* GetName() const = 0;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/oss_adapter.h b/mooncake-store/include/storage/distributed/oss_adapter.h
new file mode 100644
index 0000000000..2ed845f866
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/oss_adapter.h
@@ -0,0 +1,110 @@
+#pragma once
+
+#include <map>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "storage/distributed/object_storage_adapter.h"
+
+namespace mooncake {
+
+/**
+ * Alibaba Cloud OSS implementation of ObjectStorageAdapter.
+ *
+ * Configuration is read by Init() from MOONCAKE_OSS_* environment variables.
+ * Logical keys are encoded beneath the configured physical key prefix.
+ */
+class OssObjectStorageAdapter : public ObjectStorageAdapter {
+   public:
+    explicit OssObjectStorageAdapter(std::string key_prefix);
+    ~OssObjectStorageAdapter() override = default;
+
+    tl::expected<void, ErrorCode> Put(const std::string& logical_key,
+                                      std::span<const char> data) override;
+    tl::expected<void, ErrorCode> PutV(const std::string& logical_key,
+                                       const iovec* iov, int iovcnt) override;
+    tl::expected<size_t, ErrorCode> Get(const std::string& logical_key,
+                                        void* buf, size_t len) override;
+    std::vector<tl::expected<void, ErrorCode>> PutBatch(
+        const std::vector<ObjectPutRequest>& requests) override;
+    std::vector<tl::expected<size_t, ErrorCode>> GetBatch(
+        const std::vector<ObjectGetRequest>& requests) override;
+    tl::expected<bool, ErrorCode> Exists(
+        const std::string& logical_key) override;
+    tl::expected<std::vector<KeyInfo>, ErrorCode> ListKeys() override;
+
+    tl::expected<void, ErrorCode> Init() override;
+    tl::expected<void, ErrorCode> CheckHealth() override;
+    const char* GetName() const override { return "oss"; }
+
+    // OSS-specific operations that are intentionally not part of the common
+    // ObjectStorageAdapter contract.
+    tl::expected<size_t, ErrorCode> GetRange(const std::string& logical_key,
+                                             void* buf, size_t len,
+                                             off_t offset);
+    tl::expected<size_t, ErrorCode> GetV(const std::string& logical_key,
+                                         const iovec* iov, int iovcnt,
+                                         off_t offset);
+    tl::expected<void, ErrorCode> Delete(const std::string& logical_key);
+    tl::expected<size_t, ErrorCode> GetSize(const std::string& logical_key);
+
+   private:
+    struct Response {
+        long status = 0;
+        size_t transferred = 0;
+        std::string body;
+        std::map<std::string, std::string> headers;
+    };
+
+    struct BatchRequest;
+    struct RequestContext;
+    tl::expected<void, ErrorCode> PrepareRequest(
+        RequestContext& context, const std::string& method,
+        const std::string& physical_key,
+        const std::map<std::string, std::string>& query, const char* body,
+        size_t body_size, const std::string& range, const iovec* upload_iov,
+        int upload_iovcnt, void* download_buffer,
+        size_t download_capacity) const;
+
+    tl::expected<Response, ErrorCode> Request(
+        const std::string& method, const std::string& physical_key,
+        const std::map<std::string, std::string>& query = {},
+        const char* body = nullptr, size_t body_size = 0,
+        const std::string& range = "", const iovec* upload_iov = nullptr,
+        int upload_iovcnt = 0, void* download_buffer = nullptr,
+        size_t download_capacity = 0) const;
+
+    std::vector<tl::expected<size_t, ErrorCode>> RequestBatch(
+        const std::vector<BatchRequest>& requests);
+
+    std::string LogicalToPhysicalKey(const std::string& logical_key) const;
+    tl::expected<std::string, ErrorCode> PhysicalToLogicalKey(
+        const std::string& physical_key) const;
+    std::string PhysicalPrefix() const;
+    std::string BuildUrl(const std::string& physical_key,
+                         const std::map<std::string, std::string>& query) const;
+    std::string BuildAuthorization(
+        const std::string& method, const std::string& physical_key,
+        const std::map<std::string, std::string>& query,
+        const std::string& timestamp,
+        const std::map<std::string, std::string>& oss_headers) const;
+
+    std::string endpoint_;
+    std::string bucket_;
+    std::string region_;
+    std::string access_key_id_;
+    std::string access_key_secret_;
+    std::string security_token_;
+    std::string key_prefix_;
+    bool path_style_ = false;
+    bool anonymous_ = false;
+    bool initialized_ = false;
+    // Each synchronous batch owns its connection pool and applies this limit
+    // independently. Concurrent batches do not share a CURLM or an I/O lock.
+    long max_connections_ = 64;
+    long receive_buffer_size_ = 1024 * 1024;
+    long upload_buffer_size_ = 1024 * 1024;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage/distributed/posix_fs_adapter.h b/mooncake-store/include/storage/distributed/posix_fs_adapter.h
new file mode 100644
index 0000000000..4cb4b987f9
--- /dev/null
+++ b/mooncake-store/include/storage/distributed/posix_fs_adapter.h
@@ -0,0 +1,58 @@
+#pragma once
+
+#include "storage/distributed/fs_adapter.h"
+
+namespace mooncake {
+
+class PosixFsAdapter : public FileSystemAdapter {
+   public:
+    tl::expected<size_t, ErrorCode> WriteFile(
+        const std::string& path, std::span<const char> data) override;
+
+    tl::expected<size_t, ErrorCode> ReadFile(const std::string& path, void* buf,
+                                             size_t len) override;
+
+    tl::expected<size_t, ErrorCode> VectorWriteFile(const std::string& path,
+                                                    const iovec* iov,
+                                                    int iovcnt,
+                                                    off_t offset) override;
+
+    tl::expected<size_t, ErrorCode> VectorReadFile(const std::string& path,
+                                                   const iovec* iov, int iovcnt,
+                                                   off_t offset) override;
+
+    tl::expected<void, ErrorCode> DeleteFile(const std::string& path) override;
+
+    tl::expected<bool, ErrorCode> FileExists(const std::string& path) override;
+
+    tl::expected<std::vector<std::string>, ErrorCode> ListFiles(
+        const std::string& dir) override;
+
+    tl::expected<int, ErrorCode> OpenFile(const std::string& path) override;
+
+    tl::expected<int, ErrorCode> OpenExistingFile(
+        const std::string& path) override;
+
+    tl::expected<void, ErrorCode> CloseFile(int fd) override;
+
+    tl::expected<void, ErrorCode> PreallocateFile(const std::string& path,
+                                                  uint64_t size) override;
+
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override;
+
+    tl::expected<size_t, ErrorCode> ReadAt(int fd, iovec* iov, int iovcnt,
+                                           int64_t offset) override;
+
+    tl::expected<void, ErrorCode> Init(const std::string& mount_path) override;
+
+    tl::expected<void, ErrorCode> Shutdown() override;
+
+    const char* GetName() const override { return "posix"; }
+
+   private:
+    std::string mount_path_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/storage_backend.h b/mooncake-store/include/storage_backend.h
index 83afc3c700..f1cf19fce3 100644
--- a/mooncake-store/include/storage_backend.h
+++ b/mooncake-store/include/storage_backend.h
@@ -15,6 +15,9 @@
 #include <unordered_set>
 #include <vector>
 
+#include "config/bucket_backend_config.h"
+#include "config/file_per_key_config.h"
+#include "config/offset_allocator_backend_config.h"
 #include "file_interface.h"
 #include "mutex.h"
 #include "offset_allocator/offset_allocator.h"
@@ -163,105 +166,14 @@ enum class StorageBackendType {
     kFilePerKey,
     kBucket,
     kOffsetAllocator,
-    kDistributed
+    kDistributed,
+    kNvmeKv
 };
 
 static constexpr size_t kKB = 1024;
 static constexpr size_t kMB = kKB * 1024;
 static constexpr size_t kGB = kMB * 1024;
 
-struct FilePerKeyConfig {
-    std::string fsdir = "file_per_key_dir";  // Subdirectory name
-
-    bool enable_eviction = true;  // Enable eviction for storage
-
-    bool Validate() const;
-
-    static FilePerKeyConfig FromEnvironment();
-};
-
-enum class BucketEvictionPolicy {
-    NONE,  // No eviction (default)
-    FIFO,  // Evict oldest bucket first (by creation order)
-    LRU,   // Evict least recently read bucket first
-};
-
-struct BucketBackendConfig {
-    int64_t bucket_size_limit =
-        256 * kMB;  // Max total size of a single bucket (256 MB)
-
-    int64_t bucket_keys_limit = 500;  // Max number of keys allowed in a single
-                                      // bucket, required by bucket backend only
-
-    BucketEvictionPolicy eviction_policy =
-        BucketEvictionPolicy::NONE;  // Eviction strategy
-
-    int64_t max_total_size = 0;  // 0 = unlimited; evict when total_size_
-                                 // exceeds this threshold (bytes)
-
-    bool Validate() const;
-
-    static BucketBackendConfig FromEnvironment();
-};
-
-enum class OffsetEvictionPolicy {
-    NONE,  // No eviction
-    FIFO,  // Evict oldest key first (by insertion order)
-    LRU,   // Approximate LRU via cross-shard sampling (phase 2)
-};
-
-enum class OffsetPersistMode {
-    kDisabled,  // No persistence (default)
-    kRelaxed,   // Periodic checkpoint
-    kStrict,    // Every BatchOffload is durable
-};
-
-struct OffsetAllocatorBackendConfig {
-    OffsetEvictionPolicy eviction_policy = OffsetEvictionPolicy::NONE;
-
-    // Watermark thresholds: eviction triggers when total_size_ exceeds high,
-    // drives down to low. 0 = auto-resolved in Init() from ratios.
-    int64_t high_watermark_bytes = 0;
-    int64_t low_watermark_bytes = 0;
-    double high_ratio = 0.90;
-    double low_ratio = 0.80;
-
-    // Key-count watermarks (symmetric with byte watermarks).
-    // high triggers eviction, drives down to low.
-    int64_t high_watermark_keys = 0;
-    int64_t low_watermark_keys = 0;
-    double keys_high_ratio = 0.95;
-    double keys_low_ratio = 0.90;
-
-    // Eviction caps
-    size_t max_evict_per_offload = 4096;
-    size_t fallback_evict_batch = 16;
-
-    // Allocator node capacity override.
-    // 0 = auto-derived from capacity_ / kMinObjectSize (capped at RAM budget).
-    // Must be <= UINT32_MAX (OffsetAllocator::create takes uint32
-    // max_capacity).
-    int64_t max_capacity_nodes = 0;
-
-    bool Validate() const;
-
-    static OffsetAllocatorBackendConfig FromEnvironment();
-
-    // ---- Persistence settings ----
-    OffsetPersistMode persist_mode = OffsetPersistMode::kDisabled;
-    int64_t persist_interval_seconds = 60;
-
-    // ---- Record integrity ----
-    // When true (default), every written record carries a CRC-32C over
-    // header-prefix + key + value (RecordHeader::kFlagHasCrc), verified
-    // once on recovery.  Disable only when torn writes are otherwise
-    // impossible (kStrict mode on storage that honors fsync ordering,
-    // e.g. power-loss-protected NVMe) or when values never pass through
-    // the CPU (future DMA/GDS writers): unchecksummed records are then
-    // validated by checkpoint ordering (seq guard) alone.
-    bool enable_record_crc = true;
-};
-
 // ===== Persistence metadata structures =====
 
 struct PersistedFifoEntry {
@@ -300,6 +212,8 @@ struct FileStorageConfig {
     // Size of the local client-side buffer (used for caching or batching)
     int64_t local_buffer_size = 1280 * kMB;  // ~1.2 GB
 
+    int64_t pinned_restore_arena_size = 0;
+
     // Limits for scanning and iteration operations
     int64_t scanmeta_iterator_keys_limit =
         20000;  // Max number of keys returned per Scan call, required by bucket
@@ -319,6 +233,9 @@ struct FileStorageConfig {
     // Use io_uring for file I/O instead of POSIX pread/pwrite
     bool use_uring = false;
 
+    // DFS page-offset mode. Enabled for filesystem-mode distributed storage;
+    // object storage uses the regular offload control plane.
+    bool enable_dfs = false;
     // Proactively evict local disk objects from the heartbeat thread once
     // backend usage crosses the high watermark.
     bool enable_disk_watermark_eviction = true;
@@ -344,7 +261,9 @@ struct FileStorageConfig {
 
 class StorageBackendInterface {
    public:
-    StorageBackendInterface(const FileStorageConfig& file_storage_config);
+    explicit StorageBackendInterface(const FileStorageConfig& config)
+        : file_storage_config_(config) {}
+    virtual ~StorageBackendInterface() = default;
 
     using EvictionHandler = std::function<tl::expected<void, ErrorCode>(
         const std::vector<std::string>& evicted_keys)>;
@@ -1046,10 +965,16 @@ class BucketStorageBackend : public StorageBackendInterface {
     // FinalizeEviction removes persisted metadata, waits for in-flight reads,
     // and then deletes the data files.
     struct PendingEviction {
-        std::vector<std::string> keys;  // All keys in evicted buckets
+        std::vector<std::string> keys;  // Keys the eviction removed from the
+                                        // index (matched set; skipped
+                                        // duplicates are never re-pointed)
         std::vector<std::pair<int64_t, std::shared_ptr<BucketMetadata>>>
             buckets;  // (bucket_id, metadata) for file deletion
         std::vector<std::string> write_keys;
+        // Duplicates bypassed instead of failing the batch: already
+        // persisted, or being persisted by a concurrent offload. The
+        // commit phase must skip these (idempotent Put semantics).
+        std::vector<std::string> skipped_keys;
         int64_t evicted_size = 0;
         int64_t write_size = 0;
     };
@@ -1084,6 +1009,24 @@ class BucketStorageBackend : public StorageBackendInterface {
     std::map<int64_t, std::shared_ptr<BucketMetadata>>::iterator
     SelectEvictionCandidate();
 
+    /**
+     * @brief Actual on-disk bytes of the offload directory, measured by
+     *        summing real file allocation (stat st_blocks * 512) over every
+     *        file under storage_path_.
+     *
+     * This is ground truth — the same block-based accounting kubelet uses for
+     * emptyDir sizeLimit — so it captures bucket files that linger after their
+     * objects are logically evicted (which the in-memory total_size_ misses).
+     * Result is cached for bucket_backend_config_.disk_scan_cache_ms to bound
+     * the scan cost regardless of offload rate. Caller must hold mutex_.
+     */
+    int64_t ActualDiskBytesUsedLocked() const;
+
+    // Cached result of ActualDiskBytesUsedLocked() and when it was taken.
+    mutable int64_t cached_disk_bytes_ GUARDED_BY(mutex_) = -1;
+    mutable std::chrono::steady_clock::time_point cached_disk_bytes_at_
+        GUARDED_BY(mutex_);
+
     /**
      * @brief Phase 2 of eviction: delete persisted metadata for each evicted
      * bucket, wait for in-flight reads to drain, then delete the data file.
@@ -1105,7 +1048,21 @@ class BucketStorageBackend : public StorageBackendInterface {
     tl::expected<std::shared_ptr<StorageFile>, ErrorCode> GetFileInstance()
         const;
 
+    // Test-only: number of entries in the LRU eviction index.
+    size_t GetLruIndexSizeForTest() const {
+        SharedMutexLocker lock(&mutex_, shared_lock);
+        return lru_index_.size();
+    }
+
+    // Test-only: inject datasync failure in WriteBucket to verify orphan
+    // cleanup. SetDatasyncFailureForTest(true) makes WriteBucket fail its
+    // datasync call and immediately call CleanupOrphanedBucket.
+    void SetDatasyncFailureForTest(bool enabled) {
+        test_datasync_failure_.store(enabled, std::memory_order_relaxed);
+    }
+
    private:
+    std::atomic<bool> test_datasync_failure_{false};
     // Alignment helper functions for O_DIRECT I/O
     static constexpr size_t kDirectIOAlignment = 4096;
 
diff --git a/mooncake-store/include/storage_usage.h b/mooncake-store/include/storage_usage.h
new file mode 100644
index 0000000000..fb8fd1f656
--- /dev/null
+++ b/mooncake-store/include/storage_usage.h
@@ -0,0 +1,104 @@
+#pragma once
+
+#include <atomic>
+#include <cstddef>
+#include <memory>
+#include <utility>
+
+namespace mooncake {
+
+struct StorageUsage {
+    size_t used_bytes{0};
+    size_t capacity_bytes{0};
+
+    [[nodiscard]] double used_ratio() const noexcept {
+        if (capacity_bytes == 0) {
+            return 0.0;
+        }
+        return static_cast<double>(used_bytes) /
+               static_cast<double>(capacity_bytes);
+    }
+};
+
+/**
+ * Maintains aggregate usage for one storage domain.
+ *
+ * Mirrors the old metric-gauge model: allocation updates and reads are plain
+ * atomics. Mount/unmount briefly updates used and capacity independently, so
+ * readers may observe a best-effort torn pair during topology changes—the same
+ * class of race the previous metric-based watermark path accepted.
+ */
+class StorageUsageTracker {
+   public:
+    [[nodiscard]] StorageUsage GetUsage() const noexcept {
+        return StorageUsage{
+            .used_bytes = used_bytes_.load(std::memory_order_relaxed),
+            .capacity_bytes = capacity_bytes_.load(std::memory_order_relaxed),
+        };
+    }
+
+    void AddUsedBytes(size_t bytes) noexcept {
+        used_bytes_.fetch_add(bytes, std::memory_order_relaxed);
+    }
+
+    void RemoveUsedBytes(size_t bytes) noexcept {
+        used_bytes_.fetch_sub(bytes, std::memory_order_relaxed);
+    }
+
+    void AttachAllocator(size_t used_bytes, size_t capacity_bytes) noexcept {
+        used_bytes_.fetch_add(used_bytes, std::memory_order_relaxed);
+        capacity_bytes_.fetch_add(capacity_bytes, std::memory_order_relaxed);
+    }
+
+    void DetachAllocator(size_t used_bytes, size_t capacity_bytes) noexcept {
+        used_bytes_.fetch_sub(used_bytes, std::memory_order_relaxed);
+        capacity_bytes_.fetch_sub(capacity_bytes, std::memory_order_relaxed);
+    }
+
+   private:
+    std::atomic_size_t used_bytes_{0};
+    std::atomic_size_t capacity_bytes_{0};
+};
+
+/**
+ * RAII registration of one allocator into a StorageUsageTracker.
+ *
+ * Attach once before the allocator is published. The registration stays
+ * immutable for the allocator's lifetime and detaches from the destructor,
+ * after in-flight allocate/deallocate calls have dropped their local
+ * shared_ptr and the allocator can be destroyed.
+ */
+class StorageUsageRegistration {
+   public:
+    StorageUsageRegistration(std::shared_ptr<StorageUsageTracker> tracker,
+                             std::atomic_size_t& used_bytes,
+                             size_t capacity_bytes) noexcept
+        : tracker_(std::move(tracker)),
+          used_bytes_(used_bytes),
+          capacity_bytes_(capacity_bytes) {
+        tracker_->AttachAllocator(used_bytes_.load(std::memory_order_relaxed),
+                                  capacity_bytes_);
+    }
+
+    ~StorageUsageRegistration() {
+        tracker_->DetachAllocator(used_bytes_.load(std::memory_order_relaxed),
+                                  capacity_bytes_);
+    }
+
+    StorageUsageRegistration(const StorageUsageRegistration&) = delete;
+    StorageUsageRegistration& operator=(const StorageUsageRegistration&) =
+        delete;
+
+    void AddUsedBytes(size_t bytes) noexcept { tracker_->AddUsedBytes(bytes); }
+
+    void RemoveUsedBytes(size_t bytes) noexcept {
+        tracker_->RemoveUsedBytes(bytes);
+    }
+
+   private:
+    std::shared_ptr<StorageUsageTracker> tracker_;
+    std::atomic_size_t& used_bytes_;
+    size_t capacity_bytes_;
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/store_c.h b/mooncake-store/include/store_c.h
index b5646cd10f..f58caa5532 100644
--- a/mooncake-store/include/store_c.h
+++ b/mooncake-store/include/store_c.h
@@ -24,12 +24,32 @@ extern "C" {
 
 typedef void *mooncake_store_t;
 
+/*
+ * Soft-pin intent for mooncake_replicate_config_t::soft_pin_action.
+ * A soft pin guards an object from eviction until a deadline fixed at
+ * write time; reads never extend it. Zero-initialized configs default
+ * to MOONCAKE_SOFT_PIN_PRESERVE without a TTL.
+ */
+enum mooncake_soft_pin_action {
+    MOONCAKE_SOFT_PIN_PRESERVE = 0, /* keep an existing unexpired deadline */
+    MOONCAKE_SOFT_PIN_ENABLE = 1,   /* commit a new soft pin on publish */
+    MOONCAKE_SOFT_PIN_DISABLE = 2   /* remove an existing soft pin */
+};
+
 struct mooncake_replicate_config {
     size_t replica_num;
-    int with_soft_pin;
     int with_hard_pin;
     const char **preferred_segments;
     size_t preferred_segments_count;
+    /* One of enum mooncake_soft_pin_action; put functions return -1
+     * for any other value. */
+    int soft_pin_action;
+    /* TTL override in milliseconds; meaningful only with
+     * MOONCAKE_SOFT_PIN_ENABLE. When unset, the master default TTL
+     * applies. The master rejects TTLs on other actions and values
+     * above its configured maximum. */
+    int has_soft_pin_ttl;
+    uint64_t soft_pin_ttl_ms;
 };
 typedef struct mooncake_replicate_config mooncake_replicate_config_t;
 
diff --git a/mooncake-store/include/task_manager.h b/mooncake-store/include/task_manager.h
index 8f4578ce39..b5cf8c69ba 100644
--- a/mooncake-store/include/task_manager.h
+++ b/mooncake-store/include/task_manager.h
@@ -96,8 +96,13 @@ struct ReplicaCopyPayload {
     std::string key;
     std::string source;
     std::vector<std::string> targets;
+    uint64_t dynamic_replication_lease_id_high{0};
+    uint64_t dynamic_replication_lease_id_low{0};
+    uint64_t dynamic_replication_version_epoch{0};
 };
-YLT_REFL(ReplicaCopyPayload, tenant_id, key, source, targets);
+YLT_REFL(ReplicaCopyPayload, tenant_id, key, source, targets,
+         dynamic_replication_lease_id_high, dynamic_replication_lease_id_low,
+         dynamic_replication_version_epoch);
 
 struct ReplicaMovePayload {
     std::string tenant_id = "default";
@@ -178,6 +183,9 @@ class ScopedTaskWriteAccess {
 
     void restore_task(Task&& task);
 
+    ErrorCode fail_task_if_pending(const UUID& task_id,
+                                   const std::string& message);
+
     void clear_all();
 
     void prune_finished_tasks();
diff --git a/mooncake-store/include/tenant_quota.h b/mooncake-store/include/tenant_quota.h
index 6621e54974..3e89542c75 100644
--- a/mooncake-store/include/tenant_quota.h
+++ b/mooncake-store/include/tenant_quota.h
@@ -1,8 +1,10 @@
 #pragma once
 
+#include <atomic>
 #include <cstddef>
 #include <cstdint>
 #include <map>
+#include <memory>
 #include <optional>
 #include <string>
 #include <unordered_map>
@@ -18,23 +20,15 @@ struct TenantQuotaSnapshot {
     TenantId tenant_id;
     uint64_t requested_quota_bytes = 0;
     uint64_t effective_quota_bytes = 0;
-    uint64_t used_bytes = 0;
-    uint64_t reserved_bytes = 0;
-    uint64_t committed_count = 0;
-    uint64_t metadata_object_count = 0;
+    uint64_t charged_bytes = 0;
+    bool admission_closed = true;
     bool has_explicit_policy = false;
     bool over_quota = false;
 };
 
-struct TenantQuotaUsage {
-    uint64_t used_bytes = 0;
-    uint64_t committed_count = 0;
-    uint64_t metadata_object_count = 0;
-};
-
 using TenantQuotaPolicyMap = std::map<TenantId, uint64_t>;
 using TenantQuotaUsageMap =
-    std::unordered_map<TenantId, TenantQuotaUsage, TenantIdHash>;
+    std::unordered_map<TenantId, uint64_t, TenantIdHash>;
 
 enum class TenantQuotaError {
     kQuotaExceeded,
@@ -45,74 +39,93 @@ enum class TenantQuotaError {
     kTenantNotFound,
 };
 
+struct TenantQuotaChargeFailure {
+    TenantQuotaError error;
+    uint64_t deficit_bytes = 0;
+};
+
 using TenantQuotaResult = tl::expected<void, TenantQuotaError>;
-using TenantQuotaPolicyResult = tl::expected<uint64_t, TenantQuotaError>;
+using TenantQuotaChargeResult = tl::expected<void, TenantQuotaChargeFailure>;
+
+class TenantQuotaAccount {
+   public:
+    static constexpr uint64_t kAdmissionClosed = 1ULL << 63;
+    static constexpr uint64_t kChargedBytesMask = kAdmissionClosed - 1;
+    static constexpr uint64_t kMaxChargedBytes = kChargedBytesMask;
+
+    TenantQuotaChargeResult TryCharge(uint64_t bytes);
+    TenantQuotaResult Release(uint64_t bytes);
+
+    uint64_t ChargedBytes() const;
+    uint64_t EffectiveQuotaBytes() const;
+    bool AdmissionClosed() const;
+
+   private:
+    friend class TenantQuotaTable;
+
+    void BeginPolicyUpdate();
+    void EndPolicyUpdate();
+    void SetAdmissionClosed(bool closed);
+    void ApplyEffectiveQuota(uint64_t effective_quota_bytes);
+    void SetChargedBytesForRebuild(uint64_t charged_bytes);
+
+    // Bit 63 closes admission; bits 0..62 contain charged bytes.
+    alignas(64) std::atomic<uint64_t> charged_state_{kAdmissionClosed};
+
+    // Keep control-plane writes off the charged-state cache line.
+    alignas(64) std::atomic<uint64_t> effective_quota_bytes_{0};
+    std::atomic<uint64_t> policy_sequence_{0};
+
+    // Accessed only under external control-plane synchronization.
+    uint64_t requested_quota_bytes_{0};
+    bool has_explicit_policy_{false};
+};
+
+using TenantQuotaHandle = TenantQuotaAccount*;
 
 template <size_t NumShards>
 class ShardedTenantQuotaTable;
 
-// Single-threaded tenant quota state machine. This class owns quota rules and
-// accounting invariants, but deliberately contains no locking or sharding.
+// Control-plane registry for stable quota accounts. Callers must provide
+// external synchronization. Charge and release bypass this table and operate
+// directly on TenantQuotaHandle.
 class TenantQuotaTable {
    public:
     TenantQuotaResult UpsertTenantPolicy(const TenantId& tenant_id,
                                          uint64_t requested_quota_bytes);
-    TenantQuotaPolicyResult DisableTenantPolicyIfEmpty(
-        const TenantId& tenant_id);
-    void ApplyTenantPolicies(const TenantQuotaPolicyMap& policies);
+    TenantQuotaResult DisableTenantPolicyIfEmpty(const TenantId& tenant_id);
+    TenantQuotaResult ApplyTenantPolicies(const TenantQuotaPolicyMap& policies);
     TenantQuotaPolicyMap GetTenantPolicies() const;
 
     void RecomputeEffectiveQuotas(uint64_t allocatable_capacity_bytes);
 
     bool IsTenantRegistered(const TenantId& tenant_id) const;
+    // May create a stable closed tombstone for a previously unseen tenant.
+    TenantQuotaHandle GetOrCreateTenantHandle(const TenantId& tenant_id);
     std::optional<TenantQuotaSnapshot> GetTenantSnapshot(
         const TenantId& tenant_id) const;
     std::vector<TenantQuotaSnapshot> ListTenantSnapshots() const;
-    uint64_t ComputeDeficit(const TenantId& tenant_id,
-                            uint64_t incoming_bytes) const;
 
-    TenantQuotaResult Reserve(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult Commit(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult CommitAdditional(const TenantId& tenant_id,
-                                       uint64_t bytes);
-    TenantQuotaResult Abort(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult Release(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult ReleasePartial(const TenantId& tenant_id, uint64_t bytes);
-
-    void IncrementMetadataObjectCount(const TenantId& tenant_id);
-    TenantQuotaResult DecrementMetadataObjectCount(const TenantId& tenant_id);
-    void RebuildUsage(const TenantQuotaUsageMap& usage);
+    // Rebuild overwrites runtime accounting and must only run while data-plane
+    // charge/release operations are quiescent.
+    TenantQuotaResult RebuildUsage(const TenantQuotaUsageMap& usage);
 
    private:
     template <size_t>
     friend class ShardedTenantQuotaTable;
 
-    struct TenantQuotaState {
-        uint64_t requested_quota_bytes = 0;
-        uint64_t effective_quota_bytes = 0;
-        uint64_t used_bytes = 0;
-        uint64_t reserved_bytes = 0;
-        uint64_t committed_count = 0;
-        uint64_t metadata_object_count = 0;
-        bool has_explicit_policy = false;
-        bool over_quota = false;
-    };
-
-    using StateMap = std::map<TenantId, TenantQuotaState>;
+    using AccountMap = std::map<TenantId, std::unique_ptr<TenantQuotaAccount>>;
 
-    TenantQuotaState& GetOrCreateState(const TenantId& tenant_id);
+    TenantQuotaAccount& GetOrCreateAccount(const TenantId& tenant_id);
     TenantQuotaSnapshot MakeSnapshot(const TenantId& tenant_id,
-                                     const TenantQuotaState& state) const;
-    static bool IsLazyEmptyTenant(const TenantQuotaState& state);
-    static void RefreshOverQuota(TenantQuotaState* state);
+                                     const TenantQuotaAccount& account) const;
     static std::map<TenantId, uint64_t> BuildEffectiveQuotaAssignments(
         const std::vector<TenantQuotaSnapshot>& tenants,
         uint64_t allocatable_capacity_bytes);
     void ApplyEffectiveQuotas(
         const std::map<TenantId, uint64_t>& effective_quotas);
-    void EraseIfLazyEmpty(StateMap::iterator it);
 
-    StateMap tenants_;
+    AccountMap accounts_;
 };
 
 }  // namespace mooncake
diff --git a/mooncake-store/include/tenant_quota_ledger.h b/mooncake-store/include/tenant_quota_ledger.h
new file mode 100644
index 0000000000..78416e8dac
--- /dev/null
+++ b/mooncake-store/include/tenant_quota_ledger.h
@@ -0,0 +1,65 @@
+#pragma once
+
+#include <cstdint>
+
+#include "tenant_quota.h"
+
+namespace mooncake {
+
+// Per-object accounting state for quota bytes already charged to a stable
+// TenantQuotaAccount. The ledger never owns the account and never releases
+// quota implicitly; every mutation receives the account handle explicitly.
+class TenantQuotaLedger {
+   public:
+    TenantQuotaLedger() = default;
+    TenantQuotaLedger(const TenantQuotaLedger&) = delete;
+    TenantQuotaLedger& operator=(const TenantQuotaLedger&) = delete;
+    TenantQuotaLedger(TenantQuotaLedger&&) = delete;
+    TenantQuotaLedger& operator=(TenantQuotaLedger&&) = delete;
+    ~TenantQuotaLedger() = default;
+
+    // Records bytes that the caller has already charged with TryCharge().
+    TenantQuotaResult AdoptPendingCharge(TenantQuotaHandle account,
+                                         uint64_t bytes);
+
+    // Completes a primary Put/Upsert lifecycle. The replacement bucket is
+    // always released; pending/committed bytes are reconciled to
+    // actual_committed_bytes. Validation and the account release complete
+    // before any local field is changed.
+    TenantQuotaResult SettlePrimaryWrite(TenantQuotaHandle account,
+                                         uint64_t actual_committed_bytes);
+
+    // Settles a temporary task charge into this object's committed bytes. The
+    // caller erases or clears the task field only after this succeeds.
+    TenantQuotaResult SettleAdditional(TenantQuotaHandle account,
+                                       uint64_t pending_bytes,
+                                       uint64_t actual_bytes);
+
+    TenantQuotaResult RefundPending(TenantQuotaHandle account);
+    TenantQuotaResult ReleaseCommitted(TenantQuotaHandle account,
+                                       uint64_t bytes);
+
+    // Transfers this ledger's committed/replacement contribution into the
+    // destination's replacement bucket without changing global charged bytes.
+    TenantQuotaResult TransferReplacementCharge(TenantQuotaHandle account,
+                                                TenantQuotaLedger& destination);
+    TenantQuotaResult ReleaseReplacement(TenantQuotaHandle account);
+    TenantQuotaResult ReleaseAll(TenantQuotaHandle account);
+
+    // Rebuild is only valid while data-plane charge/release is quiescent. It
+    // changes local state only; the caller rebuilds the account separately.
+    TenantQuotaResult Rebuild(TenantQuotaHandle account,
+                              uint64_t committed_bytes);
+
+    uint64_t PendingBytes() const { return pending_bytes_; }
+    uint64_t CommittedBytes() const { return committed_bytes_; }
+    uint64_t ReplacedBytes() const { return replaced_bytes_; }
+    uint64_t TotalChargedBytes() const;
+
+   private:
+    uint64_t pending_bytes_{0};
+    uint64_t committed_bytes_{0};
+    uint64_t replaced_bytes_{0};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/tenant_quota_sharded.h b/mooncake-store/include/tenant_quota_sharded.h
index afe0e47e06..29f294c1ce 100644
--- a/mooncake-store/include/tenant_quota_sharded.h
+++ b/mooncake-store/include/tenant_quota_sharded.h
@@ -20,33 +20,24 @@ class ShardedTenantQuotaTable {
     TenantQuotaResult UpsertTenantPolicy(const TenantId& tenant_id,
                                          uint64_t requested_quota_bytes,
                                          uint64_t allocatable_capacity_bytes);
-    TenantQuotaPolicyResult DisableTenantPolicyIfEmpty(
-        const TenantId& tenant_id);
-    void ApplyTenantPolicies(const TenantQuotaPolicyMap& policies,
-                             uint64_t allocatable_capacity_bytes);
+    TenantQuotaResult DisableTenantPolicyIfEmpty(const TenantId& tenant_id);
+    TenantQuotaResult ApplyTenantPolicies(const TenantQuotaPolicyMap& policies,
+                                          uint64_t allocatable_capacity_bytes);
     TenantQuotaPolicyMap GetTenantPolicies() const;
 
     void RecomputeEffectiveQuotas(uint64_t allocatable_capacity_bytes);
 
     bool IsTenantRegistered(const TenantId& tenant_id) const;
+    // May create a stable closed tombstone for a previously unseen tenant.
+    TenantQuotaHandle GetOrCreateTenantHandle(const TenantId& tenant_id);
     std::optional<TenantQuotaSnapshot> GetTenantSnapshot(
         const TenantId& tenant_id) const;
     std::vector<TenantQuotaSnapshot> ListTenantSnapshots() const;
-    uint64_t ComputeDeficit(const TenantId& tenant_id,
-                            uint64_t incoming_bytes) const;
 
-    TenantQuotaResult Reserve(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult Commit(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult CommitAdditional(const TenantId& tenant_id,
-                                       uint64_t bytes);
-    TenantQuotaResult Abort(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult Release(const TenantId& tenant_id, uint64_t bytes);
-    TenantQuotaResult ReleasePartial(const TenantId& tenant_id, uint64_t bytes);
-
-    void IncrementMetadataObjectCount(const TenantId& tenant_id);
-    TenantQuotaResult DecrementMetadataObjectCount(const TenantId& tenant_id);
-    void RebuildUsage(const TenantQuotaUsageMap& usage,
-                      uint64_t allocatable_capacity_bytes);
+    // Rebuild overwrites runtime accounting and must only run while data-plane
+    // charge/release operations are quiescent.
+    TenantQuotaResult RebuildUsage(const TenantQuotaUsageMap& usage,
+                                   uint64_t allocatable_capacity_bytes);
 
    private:
     struct Shard {
diff --git a/mooncake-store/include/tenant_quota_sharded_impl.h b/mooncake-store/include/tenant_quota_sharded_impl.h
index d74c272a4d..2b938d3ea3 100644
--- a/mooncake-store/include/tenant_quota_sharded_impl.h
+++ b/mooncake-store/include/tenant_quota_sharded_impl.h
@@ -25,7 +25,7 @@ TenantQuotaResult ShardedTenantQuotaTable<NumShards>::UpsertTenantPolicy(
 }
 
 template <size_t NumShards>
-TenantQuotaPolicyResult
+TenantQuotaResult
 ShardedTenantQuotaTable<NumShards>::DisableTenantPolicyIfEmpty(
     const TenantId& tenant_id) {
     std::lock_guard<std::mutex> recompute_lock(recompute_mutex_);
@@ -35,8 +35,15 @@ ShardedTenantQuotaTable<NumShards>::DisableTenantPolicyIfEmpty(
 }
 
 template <size_t NumShards>
-void ShardedTenantQuotaTable<NumShards>::ApplyTenantPolicies(
+TenantQuotaResult ShardedTenantQuotaTable<NumShards>::ApplyTenantPolicies(
     const TenantQuotaPolicyMap& policies, uint64_t allocatable_capacity_bytes) {
+    for (const auto& [_, requested_quota_bytes] : policies) {
+        if (requested_quota_bytes == 0 ||
+            requested_quota_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+            return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
+        }
+    }
+
     std::lock_guard<std::mutex> recompute_lock(recompute_mutex_);
     std::array<TenantQuotaPolicyMap, kNumShards> grouped_policies;
     for (const auto& [tenant_id, requested_quota_bytes] : policies) {
@@ -47,9 +54,13 @@ void ShardedTenantQuotaTable<NumShards>::ApplyTenantPolicies(
     for (size_t i = 0; i < kNumShards; ++i) {
         auto& shard = shards_[i];
         std::lock_guard<std::mutex> lock(shard.mutex);
-        shard.table.ApplyTenantPolicies(grouped_policies[i]);
+        auto result = shard.table.ApplyTenantPolicies(grouped_policies[i]);
+        if (!result) {
+            return result;
+        }
     }
     RecomputeEffectiveQuotasLocked(allocatable_capacity_bytes);
+    return {};
 }
 
 template <size_t NumShards>
@@ -79,6 +90,14 @@ bool ShardedTenantQuotaTable<NumShards>::IsTenantRegistered(
     return shard.table.IsTenantRegistered(tenant_id);
 }
 
+template <size_t NumShards>
+TenantQuotaHandle ShardedTenantQuotaTable<NumShards>::GetOrCreateTenantHandle(
+    const TenantId& tenant_id) {
+    auto& shard = GetShard(tenant_id);
+    std::lock_guard<std::mutex> lock(shard.mutex);
+    return shard.table.GetOrCreateTenantHandle(tenant_id);
+}
+
 template <size_t NumShards>
 std::optional<TenantQuotaSnapshot>
 ShardedTenantQuotaTable<NumShards>::GetTenantSnapshot(
@@ -106,94 +125,31 @@ ShardedTenantQuotaTable<NumShards>::ListTenantSnapshots() const {
 }
 
 template <size_t NumShards>
-uint64_t ShardedTenantQuotaTable<NumShards>::ComputeDeficit(
-    const TenantId& tenant_id, uint64_t incoming_bytes) const {
-    const auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.ComputeDeficit(tenant_id, incoming_bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::Reserve(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.Reserve(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::Commit(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.Commit(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::CommitAdditional(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.CommitAdditional(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::Abort(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.Abort(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::Release(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.Release(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-TenantQuotaResult ShardedTenantQuotaTable<NumShards>::ReleasePartial(
-    const TenantId& tenant_id, uint64_t bytes) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.ReleasePartial(tenant_id, bytes);
-}
-
-template <size_t NumShards>
-void ShardedTenantQuotaTable<NumShards>::IncrementMetadataObjectCount(
-    const TenantId& tenant_id) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    shard.table.IncrementMetadataObjectCount(tenant_id);
-}
-
-template <size_t NumShards>
-TenantQuotaResult
-ShardedTenantQuotaTable<NumShards>::DecrementMetadataObjectCount(
-    const TenantId& tenant_id) {
-    auto& shard = GetShard(tenant_id);
-    std::lock_guard<std::mutex> lock(shard.mutex);
-    return shard.table.DecrementMetadataObjectCount(tenant_id);
-}
-
-template <size_t NumShards>
-void ShardedTenantQuotaTable<NumShards>::RebuildUsage(
+TenantQuotaResult ShardedTenantQuotaTable<NumShards>::RebuildUsage(
     const TenantQuotaUsageMap& usage, uint64_t allocatable_capacity_bytes) {
+    for (const auto& [_, charged_bytes] : usage) {
+        if (charged_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+            return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
+        }
+    }
+
     std::lock_guard<std::mutex> recompute_lock(recompute_mutex_);
     std::array<TenantQuotaUsageMap, kNumShards> grouped_usage;
-    for (const auto& [tenant_id, tenant_usage] : usage) {
+    for (const auto& [tenant_id, charged_bytes] : usage) {
         grouped_usage[GetShardIndex(tenant_id)].emplace(tenant_id,
-                                                        tenant_usage);
+                                                        charged_bytes);
     }
 
     for (size_t i = 0; i < kNumShards; ++i) {
         auto& shard = shards_[i];
         std::lock_guard<std::mutex> lock(shard.mutex);
-        shard.table.RebuildUsage(grouped_usage[i]);
+        auto result = shard.table.RebuildUsage(grouped_usage[i]);
+        if (!result) {
+            return result;
+        }
     }
     RecomputeEffectiveQuotasLocked(allocatable_capacity_bytes);
+    return {};
 }
 
 template <size_t NumShards>
diff --git a/mooncake-store/include/transfer_task.h b/mooncake-store/include/transfer_task.h
index 5fe938e09e..9349e847a5 100644
--- a/mooncake-store/include/transfer_task.h
+++ b/mooncake-store/include/transfer_task.h
@@ -37,6 +37,11 @@ enum class TransferStrategy {
     SPDK_NVMF = 4  // Spdk nvmf operation
 };
 
+enum class OffloadBufferAccess {
+    kTransferEngine,
+    kLocalAddress,
+};
+
 /**
  * @brief Stream operator for TransferStrategy
  */
@@ -509,6 +514,8 @@ class FilereadWorkerPool {
     void submitTask(FilereadTask task);
 
    private:
+    friend class FilereadWorkerPoolTestPeer;
+
     void workerThread();
 
     std::vector<std::thread> workers_;
@@ -560,6 +567,10 @@ class TransferSubmitter {
         const Replica::Descriptor& replica, std::vector<Slice>& slices,
         uint64_t src_offset);
 
+    std::optional<TransferFuture> submitRangeWrite(
+        const Replica::Descriptor& replica, std::vector<Slice>& slices,
+        uint64_t dst_offset);
+
     TransferEngine::ScatterTransferOperation submitScatter(
         const std::vector<TransferEngine::ScatterTransferRange>& transfers);
 
@@ -573,7 +584,10 @@ class TransferSubmitter {
         const std::vector<std::string>& keys,
         const std::vector<uint64_t>& pointers,
         const std::unordered_map<std::string, std::vector<Slice>>&
-            batched_slices);
+            batched_slices,
+        OffloadBufferAccess buffer_access);
+
+    [[nodiscard]] bool canUseLocalMemcpy(const std::string& endpoint) const;
 
     /**
      * @brief Pure comparison helper: returns true iff both endpoints are
@@ -608,17 +622,18 @@ class TransferSubmitter {
     TransferStrategy selectStrategy(const AllocatedBuffer::Descriptor& handle,
                                     const std::vector<Slice>& slices) const;
 
-    /**
-     * @brief Check if all handles refer to local segments
-     */
-    bool isLocalTransfer(const AllocatedBuffer::Descriptor& handle) const;
-
     /**
      * @brief Validate transfer parameters
      */
     bool validateTransferParams(const AllocatedBuffer::Descriptor& handle,
                                 const std::vector<Slice>& slices) const;
 
+    void appendMemcpyOperations(const AllocatedBuffer::Descriptor& handle,
+                                const std::vector<Slice>& slices,
+                                TransferRequest::OpCode op_code,
+                                uint64_t buffer_offset,
+                                std::vector<MemcpyOperation>& operations);
+
     /**
      * @brief Submit memcpy operation asynchronously
      */
@@ -627,6 +642,9 @@ class TransferSubmitter {
         const std::vector<Slice>& slices, const TransferRequest::OpCode op_code,
         uint64_t src_offset = 0);
 
+    std::optional<TransferFuture> submitMemcpyOperations(
+        std::vector<MemcpyOperation> operations);
+
 #ifdef USE_NOF
     /**
      * @brief Submit SPDK NVMe-oF operation asynchronously
@@ -649,6 +667,10 @@ class TransferSubmitter {
         const AllocatedBuffer::Descriptor& handle,
         const std::vector<Slice>& slices, uint64_t src_offset);
 
+    std::optional<TransferFuture> submitMemoryWriteOperation(
+        const AllocatedBuffer::Descriptor& handle,
+        const std::vector<Slice>& slices, uint64_t dst_offset);
+
     std::optional<TransferFuture> submitFileReadOperation(
         const Replica::Descriptor& replica, std::vector<Slice>& slices,
         TransferRequest::OpCode op_code);
diff --git a/mooncake-store/include/types.h b/mooncake-store/include/types.h
index c85eb8288c..7525946826 100644
--- a/mooncake-store/include/types.h
+++ b/mooncake-store/include/types.h
@@ -18,9 +18,6 @@
 #include "ylt/struct_json/json_writer.h"
 #include "ylt/struct_pack.hpp"
 
-#ifdef STORE_USE_ETCD
-#include "libetcd_wrapper.h"
-#endif
 namespace mooncake {
 
 // Constants
@@ -88,13 +85,22 @@ static constexpr uint64_t DEFAULT_DEFAULT_KV_LEASE_TTL =
     10000;  // in milliseconds
 static constexpr uint64_t DEFAULT_KV_SOFT_PIN_TTL_MS =
     30 * 60 * 1000;  // 30 minutes
+static constexpr uint64_t DEFAULT_MAX_KV_SOFT_PIN_TTL_MS =
+    24 * 60 * 60 * 1000;  // 24 hours
 static constexpr bool DEFAULT_ALLOW_EVICT_SOFT_PINNED_OBJECTS = true;
 static constexpr double DEFAULT_EVICTION_RATIO = 0.05;
 static constexpr double DEFAULT_EVICTION_HIGH_WATERMARK_RATIO = 0.90;
+// Per-tenant eviction watermark, as a fraction of a tenant's own effective
+// quota. Mirrors the pool-wide default above so that a tenant gets the same
+// evict-to-make-room contract the pool has; 0.0 disables the pass and restores
+// the pre-existing behaviour, where only the pool-wide watermark can trigger
+// background eviction. Inert unless enable_multi_tenants is set.
+static constexpr double DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO = 0.90;
 static constexpr double DEFAULT_NOF_EVICTION_RATIO = 0.05;
 static constexpr double DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO = 0.90;
 static constexpr int64_t DEFAULT_MASTER_VIEW_LEASE_TTL_SEC = 5;  // in seconds
 static constexpr int64_t DEFAULT_CLIENT_LIVE_TTL_SEC = 10;       // in seconds
+static constexpr int64_t DEFAULT_CLIENT_SUSPICION_TTL_SEC = 20;  // in seconds
 static constexpr int64_t DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC = 10;
 static constexpr uint32_t DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS = 1000;
 static constexpr uint32_t DEFAULT_NOF_HEARTBEAT_FAILURES_THRESHOLD = 3;
@@ -188,16 +194,11 @@ using BufHandleList = std::vector<std::shared_ptr<AllocatedBuffer>>;
 using ReplicaList = std::unordered_map<uint32_t, Replica>;
 using BufferResources =
     std::map<SegmentId, std::vector<std::shared_ptr<BufferAllocatorBase>>>;
-// Mapping between c++ and go types
-#ifdef STORE_USE_ETCD
-using EtcdRevisionId = GoInt64;
-using ViewVersionId = EtcdRevisionId;
-using EtcdLeaseId = GoInt64;
-#else
+// Keep store-facing IDs independent from the generated Go C ABI header.
+// EtcdHelper performs the conversion to GoInt64 at the wrapper boundary.
 using EtcdRevisionId = int64_t;
-using ViewVersionId = int64_t;
+using ViewVersionId = EtcdRevisionId;
 using EtcdLeaseId = int64_t;
-#endif
 
 using UUID = std::pair<uint64_t, uint64_t>;
 
@@ -359,7 +360,8 @@ enum class ErrorCode : int32_t {
     UNAVAILABLE_IN_CURRENT_STATUS =
         -1010,  ///< Request cannot be done in current status.
     UNAVAILABLE_IN_CURRENT_MODE =
-        -1011,  ///< Request cannot be done in current mode.
+        -1011,              ///< Request cannot be done in current mode.
+    NOT_SUPPORTED = -1012,  ///< Operation is not supported in current mode.
 
     // FILE errors (Range: -1100 to -1199)
     FILE_NOT_FOUND = -1100,       ///< File not found.
@@ -445,6 +447,7 @@ struct Segment {
     std::string protocol;
     std::string host_id{};
     Segment() = default;
+    bool operator==(const Segment&) const = default;
 };
 YLT_REFL(Segment, id, name, base, size, te_endpoint, protocol, host_id);
 
diff --git a/mooncake-store/include/utils.h b/mooncake-store/include/utils.h
deleted file mode 100644
index 41d6e3d205..0000000000
--- a/mooncake-store/include/utils.h
+++ /dev/null
@@ -1,483 +0,0 @@
-#pragma once
-
-#include <algorithm>
-#include <cctype>
-#include <cstddef>
-#include <cstdlib>
-#include <optional>
-#include <linux/memfd.h>
-#include <linux/mman.h>
-#include <string>
-#include <limits>
-#include <ylt/util/tl/expected.hpp>
-
-#include "rpc_types.h"
-#include "types.h"
-
-namespace mooncake {
-
-// Convert ErrorCode to integer for Python bindings
-template <class T>
-constexpr bool is_supported_return_type_v =
-    std::is_void_v<T> || std::is_integral_v<T>;
-
-template <class T>
-    requires is_supported_return_type_v<T>
-int64_t to_py_ret(const tl::expected<T, ErrorCode>& exp) noexcept {
-    if (!exp) {
-        return static_cast<int64_t>(toInt(exp.error()));
-    }
-
-    if constexpr (std::is_void_v<T>) {
-        return 0;
-    } else if constexpr (std::is_integral_v<T>) {
-        return static_cast<int64_t>(exp.value());
-    } else {
-        static_assert(!sizeof(T), "Unsupported payload type in to_py_ret()");
-    }
-}
-
-// Forward declarations
-template <typename T>
-void to_stream(std::ostream& os, const T& value);
-
-template <typename T>
-void to_stream(std::ostream& os, const std::vector<T>& vec);
-
-template <typename T1, typename T2>
-void to_stream(std::ostream& os, const std::pair<T1, T2>& p);
-
-// Implementation of the base template
-template <typename T>
-void to_stream(std::ostream& os, const T& value) {
-    if constexpr (std::is_same_v<T, bool>) {
-        os << (value ? "true" : "false");
-    } else if constexpr (std::is_arithmetic_v<T>) {
-        os << value;
-    } else if constexpr (std::is_convertible_v<T, std::string_view>) {
-        os << "\"" << value << "\"";
-    } else if constexpr (ylt::reflection::is_ylt_refl_v<T>) {
-        std::string str;
-        struct_json::to_json(value, str);
-        os << str;
-    } else {
-        os << value;
-    }
-}
-
-// Specialization for std::vector
-template <typename T>
-void to_stream(std::ostream& os, const std::vector<T>& vec) {
-    os << "[";
-    for (size_t i = 0; i < vec.size(); ++i) {
-        to_stream(os, vec[i]);
-        if (i < vec.size() - 1) {
-            os << ",";
-        }
-    }
-    os << "]";
-}
-
-template <typename K, typename V>
-void to_stream(std::ostream& os, const std::unordered_map<K, V>& map) {
-    to_stream<K, V, std::hash<K>>(os, map);
-}
-
-template <typename K, typename V, typename H>
-void to_stream(std::ostream& os, const std::unordered_map<K, V, H>& map) {
-    os << "{";
-    auto it = map.begin();
-    while (it != map.end()) {
-        to_stream(os, it->first);
-        os << ": ";
-        to_stream(os, it->second);
-        ++it;
-        if (it != map.end()) {
-            os << ", ";
-        }
-    }
-    os << "}";
-}
-
-// Specialization for std::pair
-template <typename T1, typename T2>
-void to_stream(std::ostream& os, const std::pair<T1, T2>& p) {
-    os << "{\"first\":";
-    to_stream(os, p.first);
-    os << ",\"second\":";
-    to_stream(os, p.second);
-    os << "}";
-}
-
-// Specialization for std::optional
-template <typename T>
-void to_stream(std::ostream& os, const std::optional<T>& opt) {
-    if (opt.has_value()) {
-        to_stream(os, opt.value());
-    } else {
-        os << "nullopt";
-    }
-}
-
-template <typename T>
-std::string expected_to_str(const tl::expected<T, ErrorCode>& expected) {
-    std::ostringstream oss;
-    if (expected.has_value()) {
-        oss << "status=success, value=";
-        if constexpr (std::is_same_v<T, void>) {
-            oss << "void";
-        } else {
-            to_stream(oss, expected.value());
-        }
-    } else {
-        oss << "status=failed, error=" << toString(expected.error());
-    }
-    return oss.str();
-}
-
-// String utility functions
-
-/**
- * @brief Convert a byte size to a human-readable string
- * @param bytes Number of bytes
- * @return std::string Human-readable string representation of size
- */
-[[nodiscard]] inline std::string byte_size_to_string(uint64_t bytes) {
-    const double KB = 1024.0;
-    const double MB = KB * 1024.0;
-    const double GB = MB * 1024.0;
-    const double TB = GB * 1024.0;
-
-    std::ostringstream oss;
-    oss << std::fixed << std::setprecision(2);
-    if (static_cast<int64_t>(bytes) == std::numeric_limits<int64_t>::max()) {
-        oss << "infinite";
-    } else if (bytes >= static_cast<uint64_t>(TB)) {
-        oss << bytes / TB << " TB";
-    } else if (bytes >= static_cast<uint64_t>(GB)) {
-        oss << bytes / GB << " GB";
-    } else if (bytes >= static_cast<uint64_t>(MB)) {
-        oss << bytes / MB << " MB";
-    } else if (bytes >= static_cast<uint64_t>(KB)) {
-        oss << bytes / KB << " KB";
-    } else {
-        // Less than 1 KB, don't use fixed point
-        oss.unsetf(std::ios::fixed);
-        oss << bytes << " B";
-        return oss.str();
-    }
-
-    return oss.str();
-}
-
-/**
- * @brief Parse a string representation of size to bytes
- * @param str String representation of size (e.g., "1.5 GB", "1024 MB",
- * "1048576")
- * @return Parsed byte size, or std::nullopt if parsing fails
- */
-[[nodiscard]] inline std::optional<uint64_t> try_string_to_byte_size(
-    const std::string& str) {
-    if (str.empty()) {
-        return std::nullopt;
-    }
-
-    // Create a copy for manipulation
-    std::string s = str;
-
-    // Remove leading/trailing whitespace
-    s.erase(0, s.find_first_not_of(" \t\r\n"));
-    s.erase(s.find_last_not_of(" \t\r\n") + 1);
-
-    if (s.empty()) {
-        return std::nullopt;
-    }
-
-    // Handle special case for "infinite"
-    if (s == "infinite") {
-        return std::numeric_limits<uint64_t>::max();
-    }
-
-    // Parse the numeric part
-    size_t pos = 0;
-    double value = 0;
-
-    try {
-        value = std::stod(s, &pos);
-    } catch (const std::exception&) {
-        return std::nullopt;  // Failed to parse number
-    }
-    if (value < 0) {
-        return std::nullopt;
-    }
-
-    if (pos >= s.length()) {
-        // No unit specified, assume bytes
-        return static_cast<uint64_t>(value);
-    }
-
-    // Extract unit (remaining part of the string)
-    std::string unit = s.substr(pos);
-    // Remove leading whitespace from unit
-    unit.erase(0, unit.find_first_not_of(" \t\r\n"));
-
-    // Convert to uppercase for comparison
-    std::transform(unit.begin(), unit.end(), unit.begin(),
-                   [](unsigned char c) -> char { return std::toupper(c); });
-
-    // Apply unit multiplier
-    const double KB = 1024.0;
-    const double MB = KB * 1024.0;
-    const double GB = MB * 1024.0;
-    const double TB = GB * 1024.0;
-
-    if (unit == "KB" || unit == "K") {
-        return static_cast<uint64_t>(value * KB);
-    } else if (unit == "MB" || unit == "M") {
-        return static_cast<uint64_t>(value * MB);
-    } else if (unit == "GB" || unit == "G") {
-        return static_cast<uint64_t>(value * GB);
-    } else if (unit == "TB" || unit == "T") {
-        return static_cast<uint64_t>(value * TB);
-    } else if (unit == "B" || unit.empty()) {
-        return static_cast<uint64_t>(value);
-    } else {
-        // Unknown unit
-        return std::nullopt;
-    }
-}
-
-/**
- * @brief Convert a string representation of size to bytes
- * @param str String representation of size (e.g., "1.5 GB", "1024 MB",
- * "1048576")
- * @return uint64_t Number of bytes, or 0 if parsing fails
- */
-[[nodiscard]] inline uint64_t string_to_byte_size(const std::string& str) {
-    auto parsed = try_string_to_byte_size(str);
-    return parsed.value_or(0);
-}
-
-// Buffer allocator functions
-
-constexpr size_t SZ_2MB = 2 * 1024 * 1024;
-constexpr size_t SZ_1GB = 1024 * 1024 * 1024;
-constexpr double BYTES_PER_GIB = static_cast<double>(SZ_1GB);
-
-/**
- * @brief Allocates memory for the `BufferAllocator` class.
- * @param total_size The total size of the memory to allocate.
- * @return A pointer to the allocated memory.
- */
-void* allocate_buffer_allocator_memory(
-    size_t total_size, const std::string& protocol = "",
-    size_t alignment = facebook::cachelib::Slab::kSize,
-    bool use_spdk_dma = false);
-
-inline size_t align_up(size_t size, size_t alignment) {
-    if (alignment == 0) {
-        return size;
-    }
-    return ((size + alignment - 1) / alignment) * alignment;
-}
-
-/**
- * @brief Get hugepage size from env and optionally set the corresponding memfd
- * flags.
- * * @param out_flags Optional pointer to an int. If provided,
- * MAP_HUGETLB and MAP_HUGE_2MB/1GB will be OR-ed into it.
- * @return size_t Hugepage size in bytes, or 0 if disabled.
- */
-[[nodiscard]] inline size_t get_hugepage_size_from_env(
-    unsigned int* out_flags = nullptr, bool use_memfd = false) {
-    const char* use_hp_env = std::getenv("MC_STORE_USE_HUGEPAGE");
-    if (use_hp_env == nullptr) {
-        return 0;
-    }
-
-    size_t size = SZ_2MB;  // Default to 2MB
-
-    const char* size_env = std::getenv("MC_STORE_HUGEPAGE_SIZE");
-    if (size_env != nullptr) {
-        size_t parsed_size = string_to_byte_size(size_env);
-
-        if (parsed_size == SZ_2MB || parsed_size == SZ_1GB) {
-            size = parsed_size;
-        } else {
-            LOG(WARNING) << "Invalid MC_STORE_HUGEPAGE_SIZE='" << size_env
-                         << "'. Supported: 2MB, 1GB. Fallback to 2MB.";
-            size = SZ_2MB;
-        }
-    }
-
-    if (out_flags != nullptr) {
-        if (use_memfd) {
-            *out_flags |= MFD_HUGETLB;
-        } else {
-            *out_flags |= MAP_HUGETLB;
-        }
-
-        // Add size specific flag
-        if (size == SZ_2MB) {
-            if (use_memfd) {
-                *out_flags |= MFD_HUGE_2MB;
-            } else {
-                *out_flags |= MAP_HUGE_2MB;
-            }
-        } else if (size == SZ_1GB) {
-            if (use_memfd) {
-                *out_flags |= MFD_HUGE_1GB;
-            } else {
-                *out_flags |= MAP_HUGE_1GB;
-            }
-        }
-        LOG(INFO) << "Using hugepage size: "
-                  << (size == SZ_2MB ? "2MB" : "1GB");
-    }
-
-    return size;
-}
-
-/**
- * @brief Fault in a fresh HugeTLB mapping with parallel CPU writes.
- *
- * Touches one byte per configured hugepage. Call this only for a newly
- * allocated mapping whose contents may be zeroed.
- */
-void populate_hugetlb_mapping(void* ptr, size_t total_size);
-
-/**
- * @brief Fault in an mbind-partitioned HugeTLB mapping with NUMA-local workers.
- *
- * The mapping is divided into equal regions in the same order as numa_nodes.
- * Workers are scheduled on the corresponding node before touching that
- * region.
- */
-void populate_hugetlb_numa_mapping(void* ptr, size_t total_size,
-                                   const std::vector<int>& numa_nodes);
-
-/**
- * Allocate mmap-backed buffer memory for host KV / transfer buffers.
- *
- * When the global mmap arena is enabled, this function serves allocations
- * from the arena and still honors the caller's requested alignment.
- * Arena-owned allocations remain owned by the arena until process shutdown.
- *
- * When the arena is disabled or unavailable, this falls back to a direct
- * mmap() allocation and returns a pointer aligned to at least the system page
- * size (or the configured hugepage size when available).
- *
- * @param total_size Total buffer size in bytes.
- * @param alignment Minimum alignment requested by the caller.
- * @return Pointer to the allocation, or nullptr on failure.
- */
-void* allocate_buffer_mmap_memory(size_t total_size, size_t alignment);
-
-/**
- * Allocate mmap-backed memory, optionally deferring direct HugeTLB population.
- *
- * When defer_hugetlb_population is true, a direct HugeTLB mmap omits
- * MAP_POPULATE so the caller can populate the mapping later. Arena allocations
- * retain their existing eager-population behavior.
- */
-void* allocate_buffer_mmap_memory(size_t total_size, size_t alignment,
-                                  bool defer_hugetlb_population);
-
-/**
- * @brief Return whether ptr is backed by the global mmap arena.
- *
- * Intended for callers that need to distinguish an eagerly populated arena
- * allocation from a direct mmap fallback.
- */
-[[nodiscard]] bool is_mmap_arena_allocation(const void* ptr);
-
-/**
- * Release memory previously returned by allocate_buffer_mmap_memory().
- *
- * Direct-mmap allocations are unmapped immediately. Arena-owned pointers are
- * intentionally not unmapped individually; in that case this function is a
- * no-op and the arena releases the backing pool during process teardown.
- *
- * @param ptr Pointer previously returned by allocate_buffer_mmap_memory().
- * @param total_size Original allocation size in bytes.
- */
-void free_buffer_mmap_memory(void* ptr, size_t total_size);
-
-/**
- * @brief Allocate a contiguous buffer with per-NUMA-region binding.
- *
- * Reserves a single VMA via mmap, divides it into N equal regions,
- * binds each region to the corresponding NUMA node via mbind(MPOL_BIND).
- * The mapping remains lazy after allocation. The caller may populate it with
- * NUMA-local workers or let ibv_reg_mr() fault and pin pages while respecting
- * the mbind policy.
- *
- * @param total_size  Total buffer size in bytes
- * @param numa_nodes  NUMA node IDs to bind regions to (e.g., {1,3,5,7})
- * @param page_size   Page size for alignment (0 = auto-detect via
- * getpagesize())
- * @return Pointer to the allocated buffer, or nullptr on failure
- */
-void* allocate_buffer_numa_segments(size_t total_size,
-                                    const std::vector<int>& numa_nodes,
-                                    size_t page_size = 0);
-
-void free_memory(const std::string& protocol, void* ptr,
-                 bool use_spdk_dma = false);
-
-// Network utility functions
-
-/**
- * @brief Check if a TCP port is available for binding
- * @param port The port number to check
- * @return true if port is available, false otherwise
- */
-bool isPortAvailable(int port);
-
-// Simple RAII class for automatically binding to an available port
-// The socket is bound during construction and released during destruction
-class AutoPortBinder {
-   public:
-    // Constructs binder and attempts to bind to an available port in range
-    // [min_port, max_port] After successful construction, the port is bound and
-    // reserved until destruction
-    AutoPortBinder(int min_port = 12300, int max_port = 14300);
-    ~AutoPortBinder();
-
-    // Non-copyable, non-movable
-    AutoPortBinder(const AutoPortBinder&) = delete;
-    AutoPortBinder& operator=(const AutoPortBinder&) = delete;
-    AutoPortBinder(AutoPortBinder&&) = delete;
-    AutoPortBinder& operator=(AutoPortBinder&&) = delete;
-
-    int getPort() const { return port_; }
-
-   private:
-    int socket_fd_;
-    int port_;
-};
-
-// HTTP utility: simple GET, returns body on 200, otherwise error code
-tl::expected<std::string, int> httpGet(const std::string& url);
-
-// Network utility: resolve an active interface name to its IPv4 address
-tl::expected<std::string, std::string> GetInterfaceIPv4Address(
-    const std::string& interface_name);
-
-// Network utility: obtain an available TCP port on loopback by binding to 0
-int getFreeTcpPort();
-
-// Obtain multiple unique available TCP ports atomically.
-// All ports are bound simultaneously before any are released, preventing
-// duplicate port assignments that can occur with repeated getFreeTcpPort()
-// calls.
-std::vector<int> getFreeTcpPorts(int count);
-
-int64_t time_gen();
-
-std::string ResolveMooncakeHostId(const std::string& local_hostname);
-
-std::string ResolvePathFromKey(const std::string& key,
-                               const std::string& root_dir,
-                               const std::string& fsdir);
-}  // namespace mooncake
diff --git a/mooncake-store/include/weight_management.h b/mooncake-store/include/weight_management.h
new file mode 100644
index 0000000000..52e23f2e62
--- /dev/null
+++ b/mooncake-store/include/weight_management.h
@@ -0,0 +1,477 @@
+#pragma once
+
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <tuple>
+#include <utility>
+#include <vector>
+
+#include "tenant_id.h"
+#include "ylt/struct_pack.hpp"
+
+namespace mooncake {
+
+enum class WeightAvailabilityState : uint8_t {
+    IMPORTING = 0,
+    READY = 1,
+    DEGRADED = 2,
+    DELETING = 3,
+    DELETED = 4,
+};
+
+enum class WeightResidencyState : uint8_t {
+    UNKNOWN = 0,
+    HOT = 1,
+    COLD = 2,
+    MIXED = 3,
+    ABSENT = 4,
+};
+
+enum class WeightOperationState : uint8_t {
+    NONE = 0,
+    EVICTING = 1,
+    REHYDRATING = 2,
+    REPAIRING = 3,
+};
+
+inline constexpr bool IsValidWeightAvailabilityState(
+    WeightAvailabilityState state) {
+    return state == WeightAvailabilityState::IMPORTING ||
+           state == WeightAvailabilityState::READY ||
+           state == WeightAvailabilityState::DEGRADED ||
+           state == WeightAvailabilityState::DELETING ||
+           state == WeightAvailabilityState::DELETED;
+}
+
+inline constexpr bool IsValidWeightResidencyState(WeightResidencyState state) {
+    return state == WeightResidencyState::UNKNOWN ||
+           state == WeightResidencyState::HOT ||
+           state == WeightResidencyState::COLD ||
+           state == WeightResidencyState::MIXED ||
+           state == WeightResidencyState::ABSENT;
+}
+
+inline constexpr bool IsValidWeightOperationState(WeightOperationState state) {
+    return state == WeightOperationState::NONE ||
+           state == WeightOperationState::EVICTING ||
+           state == WeightOperationState::REHYDRATING ||
+           state == WeightOperationState::REPAIRING;
+}
+
+enum class WeightManagementError : uint8_t {
+    INVALID_ARGUMENT = 1,
+    NOT_FOUND = 2,
+    CONFLICT = 3,
+    STALE_GENERATION = 4,
+    NOT_READY = 5,
+    BUSY = 6,
+    LEASE_EXPIRED = 7,
+    GENERATION_EXHAUSTED = 8,
+    DURABILITY_FAILED = 9,
+};
+
+struct WeightRevisionIdentity {
+    std::string tenant_id{"default"};
+    std::string name_space;
+    std::string resource_id;
+    std::string revision;
+    uint64_t weight_generation{0};
+
+    friend bool operator==(const WeightRevisionIdentity&,
+                           const WeightRevisionIdentity&) = default;
+    friend bool operator<(const WeightRevisionIdentity& lhs,
+                          const WeightRevisionIdentity& rhs) {
+        return std::tie(lhs.tenant_id, lhs.name_space, lhs.resource_id,
+                        lhs.revision, lhs.weight_generation) <
+               std::tie(rhs.tenant_id, rhs.name_space, rhs.resource_id,
+                        rhs.revision, rhs.weight_generation);
+    }
+};
+YLT_REFL(WeightRevisionIdentity, tenant_id, name_space, resource_id, revision,
+         weight_generation);
+
+struct WeightManifestReference {
+    std::string manifest_key;
+    std::string manifest_sha256;
+    std::string payload_group_id;
+    std::string payload_keys_sha256;
+    uint64_t payload_count{0};
+    uint64_t logical_bytes{0};
+
+    friend bool operator==(const WeightManifestReference&,
+                           const WeightManifestReference&) = default;
+};
+YLT_REFL(WeightManifestReference, manifest_key, manifest_sha256,
+         payload_group_id, payload_keys_sha256, payload_count, logical_bytes);
+
+struct WeightRevisionMetadata {
+    WeightRevisionIdentity identity;
+    WeightManifestReference manifest;
+    WeightAvailabilityState availability{WeightAvailabilityState::IMPORTING};
+    WeightResidencyState residency{WeightResidencyState::UNKNOWN};
+    WeightOperationState operation{WeightOperationState::NONE};
+    uint64_t operation_id{0};
+    uint64_t metadata_generation{1};
+    uint64_t created_at_ms{0};
+    uint64_t updated_at_ms{0};
+
+    friend bool operator==(const WeightRevisionMetadata&,
+                           const WeightRevisionMetadata&) = default;
+};
+YLT_REFL(WeightRevisionMetadata, identity, manifest, availability, residency,
+         operation, operation_id, metadata_generation, created_at_ms,
+         updated_at_ms);
+
+struct WeightRevisionLease {
+    uint64_t lease_id{0};
+    WeightRevisionIdentity identity;
+    std::string holder;
+    uint64_t expires_at_ms{0};
+    uint64_t fenced_metadata_generation{0};
+
+    friend bool operator==(const WeightRevisionLease&,
+                           const WeightRevisionLease&) = default;
+};
+YLT_REFL(WeightRevisionLease, lease_id, identity, holder, expires_at_ms,
+         fenced_metadata_generation);
+
+struct WeightResidencyOperation {
+    uint64_t operation_id{0};
+    WeightRevisionIdentity identity;
+    WeightOperationState operation{WeightOperationState::NONE};
+    WeightResidencyState target_residency{WeightResidencyState::UNKNOWN};
+    uint64_t fenced_metadata_generation{0};
+    uint64_t started_at_ms{0};
+    uint64_t updated_at_ms{0};
+    uint64_t processed_members{0};
+    uint64_t total_members{0};
+    std::string cursor;
+    std::string message;
+
+    friend bool operator==(const WeightResidencyOperation&,
+                           const WeightResidencyOperation&) = default;
+};
+YLT_REFL(WeightResidencyOperation, operation_id, identity, operation,
+         target_residency, fenced_metadata_generation, started_at_ms,
+         updated_at_ms, processed_members, total_members, cursor, message);
+
+struct WeightRevisionView {
+    WeightRevisionMetadata metadata;
+    uint64_t active_lease_count{0};
+    std::optional<uint64_t> nearest_lease_expiry_ms;
+};
+YLT_REFL(WeightRevisionView, metadata, active_lease_count,
+         nearest_lease_expiry_ms);
+
+struct BeginWeightImportRequest {
+    WeightRevisionIdentity identity;
+    std::string payload_group_id;
+    uint64_t expected_payload_count{0};
+    uint64_t expected_logical_bytes{0};
+};
+YLT_REFL(BeginWeightImportRequest, identity, payload_group_id,
+         expected_payload_count, expected_logical_bytes);
+
+struct CommitWeightImportRequest {
+    WeightRevisionIdentity identity;
+    uint64_t expected_metadata_generation{0};
+    WeightManifestReference manifest;
+};
+YLT_REFL(CommitWeightImportRequest, identity, expected_metadata_generation,
+         manifest);
+
+struct AbortWeightImportRequest {
+    WeightRevisionIdentity identity;
+    uint64_t expected_metadata_generation{0};
+};
+YLT_REFL(AbortWeightImportRequest, identity, expected_metadata_generation);
+
+struct GetWeightRevisionRequest {
+    WeightRevisionIdentity identity;
+};
+YLT_REFL(GetWeightRevisionRequest, identity);
+
+struct ListWeightRevisionsRequest {
+    std::string tenant_id{"default"};
+    std::string name_space;
+    std::string resource_id;
+    std::string page_token;
+    uint32_t limit{100};
+};
+YLT_REFL(ListWeightRevisionsRequest, tenant_id, name_space, resource_id,
+         page_token, limit);
+
+struct ListWeightRevisionsResponse {
+    std::vector<WeightRevisionView> revisions;
+    std::string next_page_token;
+};
+YLT_REFL(ListWeightRevisionsResponse, revisions, next_page_token);
+
+struct AcquireWeightRevisionLeaseRequest {
+    WeightRevisionIdentity identity;
+    uint64_t expected_metadata_generation{0};
+    std::string holder;
+    uint64_t ttl_ms{0};
+};
+YLT_REFL(AcquireWeightRevisionLeaseRequest, identity,
+         expected_metadata_generation, holder, ttl_ms);
+
+struct RenewWeightRevisionLeaseRequest {
+    std::string tenant_id{"default"};
+    uint64_t lease_id{0};
+    uint64_t ttl_ms{0};
+};
+YLT_REFL(RenewWeightRevisionLeaseRequest, tenant_id, lease_id, ttl_ms);
+
+struct ReleaseWeightRevisionLeaseRequest {
+    std::string tenant_id{"default"};
+    uint64_t lease_id{0};
+};
+YLT_REFL(ReleaseWeightRevisionLeaseRequest, tenant_id, lease_id);
+
+struct StartWeightResidencyOperationRequest {
+    WeightRevisionIdentity identity;
+    uint64_t expected_metadata_generation{0};
+    WeightResidencyState target_residency{WeightResidencyState::UNKNOWN};
+};
+YLT_REFL(StartWeightResidencyOperationRequest, identity,
+         expected_metadata_generation, target_residency);
+
+struct QueryWeightOperationRequest {
+    std::string tenant_id{"default"};
+    uint64_t operation_id{0};
+};
+YLT_REFL(QueryWeightOperationRequest, tenant_id, operation_id);
+
+struct ReconcileWeightRevisionRequest {
+    WeightRevisionIdentity identity;
+};
+YLT_REFL(ReconcileWeightRevisionRequest, identity);
+
+struct DeleteWeightRevisionRequest {
+    WeightRevisionIdentity identity;
+    uint64_t expected_metadata_generation{0};
+};
+YLT_REFL(DeleteWeightRevisionRequest, identity, expected_metadata_generation);
+
+std::string ComputeWeightPayloadKeysSha256(
+    const std::vector<std::string>& payload_keys);
+std::string MakeWeightPayloadGroupId(const WeightRevisionIdentity& identity);
+std::string MakeWeightRevisionMetadataKey(
+    const WeightRevisionIdentity& identity);
+std::string MakeWeightLeaseMetadataKey(uint64_t lease_id);
+
+class WeightValidationResult {
+   public:
+    static WeightValidationResult Success() { return WeightValidationResult(); }
+
+    static WeightValidationResult Failure(std::string message) {
+        return WeightValidationResult(std::move(message));
+    }
+
+    bool ok() const noexcept { return message_.empty(); }
+    const std::string& message() const noexcept { return message_; }
+
+   private:
+    WeightValidationResult() = default;
+    explicit WeightValidationResult(std::string message)
+        : message_(std::move(message)) {}
+
+    std::string message_;
+};
+
+inline bool IsValidWeightComponent(std::string_view value) {
+    if (value.empty() || value.size() > 1024) {
+        return false;
+    }
+    for (const unsigned char c : value) {
+        if (c < 0x20 || c == 0x7f) {
+            return false;
+        }
+    }
+    return true;
+}
+
+inline std::string EncodeWeightPathSegment(std::string_view value) {
+    constexpr char kHex[] = "0123456789ABCDEF";
+    std::string encoded;
+    encoded.reserve(value.size());
+    for (const unsigned char c : value) {
+        const bool safe = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
+                          (c >= '0' && c <= '9') || c == '-' || c == '_' ||
+                          c == '.' || c == '~';
+        if (safe) {
+            encoded.push_back(static_cast<char>(c));
+        } else {
+            encoded.push_back('%');
+            encoded.push_back(kHex[c >> 4]);
+            encoded.push_back(kHex[c & 0x0f]);
+        }
+    }
+    return encoded;
+}
+
+inline std::string MakeWeightManifestKey(
+    const WeightRevisionIdentity& identity) {
+    return "weights/" + EncodeWeightPathSegment(identity.name_space) + "/" +
+           EncodeWeightPathSegment(identity.resource_id) + "/" +
+           EncodeWeightPathSegment(identity.revision) + "/" +
+           std::to_string(identity.weight_generation) + "/manifest";
+}
+
+inline bool IsValidSha256(std::string_view digest) {
+    if (digest.size() != 64) {
+        return false;
+    }
+    for (const char c : digest) {
+        if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f'))) {
+            return false;
+        }
+    }
+    return true;
+}
+
+inline WeightValidationResult ValidateWeightRevisionIdentity(
+    const WeightRevisionIdentity& identity) {
+    if (identity.tenant_id.empty() || !TenantId(identity.tenant_id).IsValid()) {
+        return WeightValidationResult::Failure("invalid tenant_id");
+    }
+    if (!IsValidWeightComponent(identity.name_space)) {
+        return WeightValidationResult::Failure("invalid namespace");
+    }
+    if (!IsValidWeightComponent(identity.resource_id)) {
+        return WeightValidationResult::Failure("invalid resource_id");
+    }
+    if (!IsValidWeightComponent(identity.revision)) {
+        return WeightValidationResult::Failure("invalid revision");
+    }
+    if (identity.weight_generation == 0) {
+        return WeightValidationResult::Failure("invalid weight_generation");
+    }
+    return WeightValidationResult::Success();
+}
+
+inline WeightValidationResult ValidateWeightManifestReference(
+    const WeightManifestReference& manifest) {
+    if (!IsValidWeightComponent(manifest.manifest_key)) {
+        return WeightValidationResult::Failure("invalid manifest_key");
+    }
+    if (!IsValidSha256(manifest.manifest_sha256)) {
+        return WeightValidationResult::Failure("invalid manifest_sha256");
+    }
+    if (!IsValidWeightComponent(manifest.payload_group_id)) {
+        return WeightValidationResult::Failure("invalid payload_group_id");
+    }
+    if (!IsValidSha256(manifest.payload_keys_sha256)) {
+        return WeightValidationResult::Failure("invalid payload_keys_sha256");
+    }
+    if (manifest.payload_count == 0) {
+        return WeightValidationResult::Failure("payload_count must be nonzero");
+    }
+    if (manifest.logical_bytes == 0) {
+        return WeightValidationResult::Failure("logical_bytes must be nonzero");
+    }
+    return WeightValidationResult::Success();
+}
+
+inline bool IsValidWeightAvailabilityTransition(WeightAvailabilityState from,
+                                                WeightAvailabilityState to) {
+    switch (from) {
+        case WeightAvailabilityState::IMPORTING:
+            return to == WeightAvailabilityState::READY ||
+                   to == WeightAvailabilityState::DELETING;
+        case WeightAvailabilityState::READY:
+            return to == WeightAvailabilityState::DEGRADED ||
+                   to == WeightAvailabilityState::DELETING;
+        case WeightAvailabilityState::DEGRADED:
+            return to == WeightAvailabilityState::READY ||
+                   to == WeightAvailabilityState::DELETING;
+        case WeightAvailabilityState::DELETING:
+            return to == WeightAvailabilityState::DELETED;
+        case WeightAvailabilityState::DELETED:
+            return false;
+    }
+    return false;
+}
+
+inline WeightValidationResult ValidateWeightRevisionMetadata(
+    const WeightRevisionMetadata& metadata) {
+    if (!IsValidWeightAvailabilityState(metadata.availability) ||
+        !IsValidWeightResidencyState(metadata.residency) ||
+        !IsValidWeightOperationState(metadata.operation)) {
+        return WeightValidationResult::Failure("invalid weight state");
+    }
+    auto identity_result = ValidateWeightRevisionIdentity(metadata.identity);
+    if (!identity_result.ok()) {
+        return identity_result;
+    }
+    if (metadata.manifest.payload_group_id !=
+        MakeWeightPayloadGroupId(metadata.identity)) {
+        return WeightValidationResult::Failure(
+            "payload_group_id is not canonical");
+    }
+    if (!metadata.manifest.manifest_key.empty() &&
+        metadata.manifest.manifest_key !=
+            MakeWeightManifestKey(metadata.identity)) {
+        return WeightValidationResult::Failure("manifest_key is not canonical");
+    }
+    if (metadata.metadata_generation == 0 ||
+        metadata.metadata_generation == std::numeric_limits<uint64_t>::max()) {
+        return WeightValidationResult::Failure("invalid metadata_generation");
+    }
+    if (metadata.updated_at_ms < metadata.created_at_ms) {
+        return WeightValidationResult::Failure("timestamps are not monotonic");
+    }
+    if ((metadata.operation == WeightOperationState::NONE) !=
+        (metadata.operation_id == 0)) {
+        return WeightValidationResult::Failure(
+            "operation and operation_id disagree");
+    }
+    if (metadata.operation != WeightOperationState::NONE &&
+        metadata.availability != WeightAvailabilityState::READY &&
+        metadata.availability != WeightAvailabilityState::DEGRADED) {
+        return WeightValidationResult::Failure(
+            "active operation requires a published revision");
+    }
+    if (metadata.availability == WeightAvailabilityState::IMPORTING &&
+        metadata.residency != WeightResidencyState::UNKNOWN) {
+        return WeightValidationResult::Failure(
+            "importing revision must have unknown residency");
+    }
+    if (metadata.availability == WeightAvailabilityState::READY ||
+        metadata.availability == WeightAvailabilityState::DEGRADED) {
+        auto manifest_result =
+            ValidateWeightManifestReference(metadata.manifest);
+        if (!manifest_result.ok()) {
+            return manifest_result;
+        }
+    }
+    if ((metadata.availability == WeightAvailabilityState::READY ||
+         metadata.availability == WeightAvailabilityState::DEGRADED) &&
+        metadata.residency == WeightResidencyState::UNKNOWN) {
+        return WeightValidationResult::Failure(
+            "published revision must have observed residency");
+    }
+    if (metadata.availability == WeightAvailabilityState::READY &&
+        metadata.residency == WeightResidencyState::ABSENT) {
+        return WeightValidationResult::Failure(
+            "ready revision must have readable residency");
+    }
+    if (metadata.availability == WeightAvailabilityState::DELETED &&
+        (metadata.residency != WeightResidencyState::ABSENT ||
+         metadata.operation != WeightOperationState::NONE)) {
+        return WeightValidationResult::Failure(
+            "deleted revision must be absent and idle");
+    }
+    return WeightValidationResult::Success();
+}
+
+inline bool CanAdvanceWeightMetadataGeneration(uint64_t generation) {
+    return generation > 0 &&
+           generation < std::numeric_limits<uint64_t>::max() - 1;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/include/weight_metadata_store.h b/mooncake-store/include/weight_metadata_store.h
new file mode 100644
index 0000000000..47470f4aa5
--- /dev/null
+++ b/mooncake-store/include/weight_metadata_store.h
@@ -0,0 +1,138 @@
+#pragma once
+
+#include <map>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "weight_management.h"
+
+namespace mooncake {
+
+enum class WeightMetadataMutationKind : uint8_t {
+    UPSERT = 0,
+    ERASE = 1,
+};
+
+struct WeightMetadataMutation {
+    WeightMetadataMutationKind kind{WeightMetadataMutationKind::UPSERT};
+    WeightRevisionIdentity identity;
+    std::optional<WeightRevisionMetadata> previous;
+    std::optional<WeightRevisionMetadata> next;
+    bool no_op{false};
+};
+
+struct WeightLeaseMutation {
+    WeightMetadataMutationKind kind{WeightMetadataMutationKind::UPSERT};
+    uint64_t lease_id{0};
+    std::optional<WeightRevisionLease> previous;
+    std::optional<WeightRevisionLease> next;
+    bool no_op{false};
+};
+
+struct WeightOperationMutation {
+    WeightMetadataMutation metadata;
+    std::optional<WeightResidencyOperation> previous;
+    std::optional<WeightResidencyOperation> next;
+    bool no_op{false};
+};
+
+struct WeightMetadataSnapshot {
+    uint32_t schema_version{1};
+    std::vector<WeightRevisionMetadata> metadata;
+    std::vector<WeightRevisionLease> leases;
+    std::vector<WeightResidencyOperation> operations;
+    uint64_t next_lease_id{1};
+    uint64_t next_operation_id{1};
+
+    friend bool operator==(const WeightMetadataSnapshot&,
+                           const WeightMetadataSnapshot&) = default;
+};
+YLT_REFL(WeightMetadataSnapshot, schema_version, metadata, leases, operations,
+         next_lease_id, next_operation_id);
+
+class WeightMetadataStore {
+   public:
+    template <typename T>
+    using Result = tl::expected<T, WeightManagementError>;
+
+    Result<WeightMetadataMutation> PrepareBeginImport(
+        const BeginWeightImportRequest& request, uint64_t now_ms) const;
+    Result<WeightMetadataMutation> PrepareCommitImport(
+        const CommitWeightImportRequest& request, uint64_t now_ms) const;
+    Result<WeightMetadataMutation> PrepareAbortImport(
+        const AbortWeightImportRequest& request, uint64_t now_ms) const;
+    Result<WeightRevisionMetadata> Publish(
+        const WeightMetadataMutation& mutation);
+
+    Result<WeightRevisionView> Get(const WeightRevisionIdentity& identity,
+                                   uint64_t now_ms) const;
+    Result<ListWeightRevisionsResponse> List(
+        const ListWeightRevisionsRequest& request, uint64_t now_ms) const;
+
+    Result<WeightLeaseMutation> PrepareAcquireLease(
+        const AcquireWeightRevisionLeaseRequest& request, uint64_t now_ms);
+    Result<WeightLeaseMutation> PrepareRenewLease(
+        const RenewWeightRevisionLeaseRequest& request, uint64_t now_ms) const;
+    Result<WeightLeaseMutation> PrepareReleaseLease(
+        const ReleaseWeightRevisionLeaseRequest& request) const;
+    std::vector<WeightLeaseMutation> PrepareExpireLeases(uint64_t now_ms) const;
+    Result<WeightRevisionLease> Publish(const WeightLeaseMutation& mutation);
+    bool HasActiveLease(const WeightRevisionIdentity& identity,
+                        uint64_t metadata_generation, uint64_t now_ms) const;
+
+    Result<WeightOperationMutation> PrepareStartOperation(
+        const StartWeightResidencyOperationRequest& request, uint64_t now_ms);
+    Result<WeightOperationMutation> PrepareFinishOperation(
+        uint64_t operation_id, WeightResidencyState observed_residency,
+        uint64_t now_ms) const;
+    Result<WeightOperationMutation> PrepareUpdateOperationProgress(
+        uint64_t operation_id, uint64_t processed_members,
+        uint64_t total_members, std::string cursor, uint64_t now_ms) const;
+    Result<WeightResidencyOperation> Publish(
+        const WeightOperationMutation& mutation);
+    Result<WeightResidencyOperation> QueryOperation(
+        uint64_t operation_id) const;
+
+    Result<WeightMetadataMutation> PrepareDelete(
+        const DeleteWeightRevisionRequest& request, uint64_t now_ms) const;
+    Result<WeightMetadataMutation> PrepareFinishDelete(
+        const WeightRevisionIdentity& identity,
+        uint64_t expected_metadata_generation, uint64_t now_ms) const;
+    Result<WeightMetadataMutation> PrepareReconcile(
+        const WeightRevisionIdentity& identity,
+        uint64_t expected_metadata_generation,
+        WeightAvailabilityState availability, WeightResidencyState residency,
+        uint64_t now_ms) const;
+
+    bool IsManagedGroup(const std::string& payload_group_id) const;
+    bool AllowsGroupMemberMutation(const std::string& payload_group_id) const;
+    WeightMetadataSnapshot ExportSnapshot() const;
+    Result<void> RestoreSnapshot(const WeightMetadataSnapshot& snapshot);
+    void Clear();
+
+   private:
+    static std::string MakePageToken(const WeightRevisionIdentity& identity);
+    static Result<std::pair<std::string, uint64_t>> ParsePageToken(
+        const std::string& page_token);
+    static uint64_t AddTtl(uint64_t now_ms, uint64_t ttl_ms);
+    static WeightOperationState OperationForTarget(WeightResidencyState target);
+
+    uint64_t CountActiveLeasesLocked(const WeightRevisionMetadata& metadata,
+                                     uint64_t now_ms,
+                                     std::optional<uint64_t>* nearest) const;
+
+    mutable std::mutex mutex_;
+    std::map<WeightRevisionIdentity, WeightRevisionMetadata> revisions_;
+    std::map<std::string, WeightRevisionIdentity> group_index_;
+    std::unordered_map<uint64_t, WeightRevisionLease> leases_;
+    std::unordered_map<uint64_t, WeightResidencyOperation> operations_;
+    uint64_t next_lease_id_{1};
+    uint64_t next_operation_id_{1};
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/rust/build.rs b/mooncake-store/rust/build.rs
index df77b0b1a7..58840f1865 100644
--- a/mooncake-store/rust/build.rs
+++ b/mooncake-store/rust/build.rs
@@ -95,6 +95,22 @@ fn has_library(search_dirs: &[PathBuf], candidates: &[&str]) -> bool {
     })
 }
 
+fn oss_adapter_enabled(build_dir: &std::path::Path) -> Option<bool> {
+    let cache_path = build_dir.join("CMakeCache.txt");
+    println!("cargo:rerun-if-changed={}", cache_path.display());
+    fs::read_to_string(cache_path)
+        .ok()?
+        .lines()
+        .find_map(|line| {
+            line.strip_prefix("MOONCAKE_OSS_ADAPTER_ENABLED:INTERNAL=")
+                .and_then(|value| match value {
+                    "TRUE" => Some(true),
+                    "FALSE" => Some(false),
+                    _ => None,
+                })
+        })
+}
+
 fn emit_link_searches(search_dirs: &[PathBuf]) {
     for dir in search_dirs {
         println!("cargo:rustc-link-search=native={}", dir.display());
@@ -237,7 +253,14 @@ fn main() {
             .display()
     );
 
+    // LocalSsdManager is built as a separate static library.
+    println!(
+        "cargo:rustc-link-search=native={}",
+        lib_path.join("local_ssd").display()
+    );
+
     println!("cargo:rustc-link-lib=mooncake_store");
+    println!("cargo:rustc-link-lib=mooncake_local_ssd");
 
     // Dependencies of mooncake_store that must be satisfied at link time.
     // The list mirrors what mooncake-store/src/CMakeLists.txt links against.
@@ -274,6 +297,7 @@ fn main() {
         push_cmake_cache_library_dirs(&mut search_dirs, &build_dir);
         for dir in [
             build_dir.join("mooncake-store/src"),
+            build_dir.join("mooncake-store/src/local_ssd"),
             build_dir.join("mooncake-store/src/cachelib_memory_allocator"),
             build_dir.join("mooncake-transfer-engine/src"),
             build_dir.join("mooncake-transfer-engine/src/common/base"),
@@ -288,6 +312,7 @@ fn main() {
     push_cmake_cache_library_dirs(&mut search_dirs, &default_build_dir);
     for dir in [
         default_build_dir.join("mooncake-store/src"),
+        default_build_dir.join("mooncake-store/src/local_ssd"),
         default_build_dir.join("mooncake-store/src/cachelib_memory_allocator"),
         default_build_dir.join("mooncake-transfer-engine/src"),
         default_build_dir.join("mooncake-transfer-engine/src/common/base"),
@@ -348,6 +373,7 @@ fn main() {
 
     for library in [
         "mooncake_store",
+        "mooncake_local_ssd",
         "cachelib_memory_allocator",
         "transfer_engine",
         "base",
@@ -382,6 +408,17 @@ fn main() {
         }
     }
 
+    // Static C++ dependencies do not propagate from CMake into Cargo. Honor
+    // CMake's actual OSS state; installed libraries without a build cache use
+    // the same library-discovery fallback as the other optional dependencies.
+    let oss_build_dir = env::var_os("MOONCAKE_BUILD_DIR")
+        .map(PathBuf::from)
+        .unwrap_or(build_dir);
+    if oss_adapter_enabled(&oss_build_dir).unwrap_or_else(|| has_library(&search_dirs, &["crypto"]))
+    {
+        println!("cargo:rustc-link-lib=crypto");
+    }
+
     if has_gcov_runtime || has_library(&search_dirs, &["gcov"]) {
         println!("cargo:rustc-link-lib=gcov");
     }
diff --git a/mooncake-store/rust/examples/basic_usage.rs b/mooncake-store/rust/examples/basic_usage.rs
index c6f2e1b442..4070021b62 100644
--- a/mooncake-store/rust/examples/basic_usage.rs
+++ b/mooncake-store/rust/examples/basic_usage.rs
@@ -45,7 +45,7 @@
 //! cargo run --example basic_usage
 //! ```
 
-use mooncake_store::{MooncakeStore, ReplicateConfig, StoreError};
+use mooncake_store::{MooncakeStore, ReplicateConfig, SoftPinAction, StoreError};
 
 fn main() {
     println!("=== Mooncake Store Rust Bindings — Basic Usage ===\n");
@@ -128,7 +128,8 @@ fn main() {
     // Step 7: Put with explicit replication config.
     let config = ReplicateConfig {
         replica_num: 2,
-        with_soft_pin: true,
+        soft_pin_action: SoftPinAction::Enable,
+        soft_pin_ttl_ms: None,
         with_hard_pin: false,
         preferred_segments: vec!["seg-0".to_string()],
     };
@@ -136,7 +137,9 @@ fn main() {
     if let Err(e) = store.put("replicated-key", b"replicated value", Some(&config)) {
         eprintln!("[FAIL] put() with ReplicateConfig failed: {e}");
     } else {
-        println!("[OK] put(\"replicated-key\") with replica_num=2, soft_pin=true, hard_pin=false");
+        println!(
+            "[OK] put(\"replicated-key\") with replica_num=2, soft_pin=enable, hard_pin=false"
+        );
     }
 
     // Step 8: Remove the keys.
diff --git a/mooncake-store/rust/src/generated/ffi_dlopen_bindings.rs b/mooncake-store/rust/src/generated/ffi_dlopen_bindings.rs
index 94d08f062b..d1ced991d5 100644
--- a/mooncake-store/rust/src/generated/ffi_dlopen_bindings.rs
+++ b/mooncake-store/rust/src/generated/ffi_dlopen_bindings.rs
@@ -4,31 +4,41 @@
 // Do not edit by hand; see mooncake-store/rust/README.md to regenerate.
 
 pub type mooncake_store_t = *mut ::std::os::raw::c_void;
+pub const mooncake_soft_pin_action_MOONCAKE_SOFT_PIN_PRESERVE: mooncake_soft_pin_action = 0;
+pub const mooncake_soft_pin_action_MOONCAKE_SOFT_PIN_ENABLE: mooncake_soft_pin_action = 1;
+pub const mooncake_soft_pin_action_MOONCAKE_SOFT_PIN_DISABLE: mooncake_soft_pin_action = 2;
+pub type mooncake_soft_pin_action = ::std::os::raw::c_uint;
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
 pub struct mooncake_replicate_config {
     pub replica_num: usize,
-    pub with_soft_pin: ::std::os::raw::c_int,
     pub with_hard_pin: ::std::os::raw::c_int,
     pub preferred_segments: *mut *const ::std::os::raw::c_char,
     pub preferred_segments_count: usize,
+    pub soft_pin_action: ::std::os::raw::c_int,
+    pub has_soft_pin_ttl: ::std::os::raw::c_int,
+    pub soft_pin_ttl_ms: u64,
 }
 #[allow(clippy::unnecessary_operation, clippy::identity_op)]
 const _: () = {
     ["Size of mooncake_replicate_config"]
-        [::std::mem::size_of::<mooncake_replicate_config>() - 32usize];
+        [::std::mem::size_of::<mooncake_replicate_config>() - 48usize];
     ["Alignment of mooncake_replicate_config"]
         [::std::mem::align_of::<mooncake_replicate_config>() - 8usize];
     ["Offset of field: mooncake_replicate_config::replica_num"]
         [::std::mem::offset_of!(mooncake_replicate_config, replica_num) - 0usize];
-    ["Offset of field: mooncake_replicate_config::with_soft_pin"]
-        [::std::mem::offset_of!(mooncake_replicate_config, with_soft_pin) - 8usize];
     ["Offset of field: mooncake_replicate_config::with_hard_pin"]
-        [::std::mem::offset_of!(mooncake_replicate_config, with_hard_pin) - 12usize];
+        [::std::mem::offset_of!(mooncake_replicate_config, with_hard_pin) - 8usize];
     ["Offset of field: mooncake_replicate_config::preferred_segments"]
         [::std::mem::offset_of!(mooncake_replicate_config, preferred_segments) - 16usize];
     ["Offset of field: mooncake_replicate_config::preferred_segments_count"]
         [::std::mem::offset_of!(mooncake_replicate_config, preferred_segments_count) - 24usize];
+    ["Offset of field: mooncake_replicate_config::soft_pin_action"]
+        [::std::mem::offset_of!(mooncake_replicate_config, soft_pin_action) - 32usize];
+    ["Offset of field: mooncake_replicate_config::has_soft_pin_ttl"]
+        [::std::mem::offset_of!(mooncake_replicate_config, has_soft_pin_ttl) - 36usize];
+    ["Offset of field: mooncake_replicate_config::soft_pin_ttl_ms"]
+        [::std::mem::offset_of!(mooncake_replicate_config, soft_pin_ttl_ms) - 40usize];
 };
 pub type mooncake_replicate_config_t = mooncake_replicate_config;
 pub struct MooncakeStoreLib {
diff --git a/mooncake-store/rust/src/lib.rs b/mooncake-store/rust/src/lib.rs
index 70177dacb3..a4b47cab52 100644
--- a/mooncake-store/rust/src/lib.rs
+++ b/mooncake-store/rust/src/lib.rs
@@ -63,7 +63,7 @@ pub mod store;
 mod ffi_dlopen;
 
 pub use error::StoreError;
-pub use store::{MooncakeStore, ReplicateConfig};
+pub use store::{MooncakeStore, ReplicateConfig, SoftPinAction};
 
 #[cfg(all(feature = "dlopen", not(feature = "link")))]
 pub use ffi_dlopen::load_library;
diff --git a/mooncake-store/rust/src/store.rs b/mooncake-store/rust/src/store.rs
index 6c54952eb6..27cdc9d1cf 100644
--- a/mooncake-store/rust/src/store.rs
+++ b/mooncake-store/rust/src/store.rs
@@ -41,6 +41,22 @@ use crate::ffi_dlopen as ffi;
 // ReplicateConfig
 // ---------------------------------------------------------------------------
 
+/// Soft-pin intent of a put operation.
+///
+/// A soft pin guards an object from eviction until a deadline fixed at write
+/// time; reads never extend it.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum SoftPinAction {
+    /// Keep an existing unexpired soft-pin deadline. The default, so plain
+    /// puts commit ordinary cache.
+    #[default]
+    Preserve = 0,
+    /// Commit a new soft-pin lifetime when the write becomes readable.
+    Enable = 1,
+    /// Remove an existing soft pin when the write becomes readable.
+    Disable = 2,
+}
+
 /// Replication settings for a put operation.
 ///
 /// This is the Rust counterpart of `mooncake_replicate_config_t` from
@@ -49,8 +65,11 @@ use crate::ffi_dlopen as ffi;
 pub struct ReplicateConfig {
     /// Number of replicas to create (0 means use the server default).
     pub replica_num: usize,
-    /// Prefer a replica on the same NUMA node / host ("soft pin").
-    pub with_soft_pin: bool,
+    /// Soft-pin intent for this write.
+    pub soft_pin_action: SoftPinAction,
+    /// Soft-pin TTL override in milliseconds. Only valid with
+    /// [`SoftPinAction::Enable`]; `None` uses the master's default TTL.
+    pub soft_pin_ttl_ms: Option<u64>,
     /// Declare whether the object will never be evicted.
     pub with_hard_pin: bool,
     /// Whitelist of segment names that should host a replica.
@@ -73,6 +92,12 @@ impl ReplicateConfig {
         ),
         StoreError,
     > {
+        if self.soft_pin_ttl_ms.is_some() && self.soft_pin_action != SoftPinAction::Enable {
+            return Err(StoreError::InvalidArgument(
+                "soft_pin_ttl_ms is only valid with SoftPinAction::Enable".to_string(),
+            ));
+        }
+
         let strings: Vec<CString> = self
             .preferred_segments
             .iter()
@@ -83,7 +108,9 @@ impl ReplicateConfig {
 
         let c_config = ffi::mooncake_replicate_config_t {
             replica_num: self.replica_num,
-            with_soft_pin: i32::from(self.with_soft_pin),
+            soft_pin_action: self.soft_pin_action as i32,
+            has_soft_pin_ttl: i32::from(self.soft_pin_ttl_ms.is_some()),
+            soft_pin_ttl_ms: self.soft_pin_ttl_ms.unwrap_or(0),
             with_hard_pin: i32::from(self.with_hard_pin),
             preferred_segments: if ptrs.is_empty() {
                 std::ptr::null_mut()
@@ -626,14 +653,17 @@ mod tests {
     fn replicate_config_to_ffi_empty_segments() {
         let config = ReplicateConfig {
             replica_num: 2,
-            with_soft_pin: true,
+            soft_pin_action: SoftPinAction::Enable,
+            soft_pin_ttl_ms: Some(30000),
             with_hard_pin: false,
             preferred_segments: Vec::new(),
         };
 
         let (ffi_cfg, strings, ptrs) = config.to_ffi().expect("to_ffi should succeed");
         assert_eq!(ffi_cfg.replica_num, 2);
-        assert_eq!(ffi_cfg.with_soft_pin, 1);
+        assert_eq!(ffi_cfg.soft_pin_action, SoftPinAction::Enable as i32);
+        assert_eq!(ffi_cfg.has_soft_pin_ttl, 1);
+        assert_eq!(ffi_cfg.soft_pin_ttl_ms, 30000);
         assert_eq!(ffi_cfg.with_hard_pin, 0);
         assert!(ffi_cfg.preferred_segments.is_null());
         assert_eq!(ffi_cfg.preferred_segments_count, 0);
@@ -645,14 +675,17 @@ mod tests {
     fn replicate_config_to_ffi_with_segments() {
         let config = ReplicateConfig {
             replica_num: 3,
-            with_soft_pin: false,
+            soft_pin_action: SoftPinAction::Preserve,
+            soft_pin_ttl_ms: None,
             with_hard_pin: false,
             preferred_segments: vec!["seg-a".to_string(), "seg-b".to_string()],
         };
 
         let (ffi_cfg, strings, ptrs) = config.to_ffi().expect("to_ffi should succeed");
         assert_eq!(ffi_cfg.replica_num, 3);
-        assert_eq!(ffi_cfg.with_soft_pin, 0);
+        assert_eq!(ffi_cfg.soft_pin_action, SoftPinAction::Preserve as i32);
+        assert_eq!(ffi_cfg.has_soft_pin_ttl, 0);
+        assert_eq!(ffi_cfg.soft_pin_ttl_ms, 0);
         assert_eq!(ffi_cfg.with_hard_pin, 0);
         assert!(!ffi_cfg.preferred_segments.is_null());
         assert_eq!(ffi_cfg.preferred_segments_count, 2);
@@ -665,11 +698,28 @@ mod tests {
         assert_eq!(seg1.to_str().unwrap(), "seg-b");
     }
 
+    #[test]
+    fn replicate_config_to_ffi_rejects_ttl_without_enable() {
+        let config = ReplicateConfig {
+            replica_num: 1,
+            soft_pin_action: SoftPinAction::Disable,
+            soft_pin_ttl_ms: Some(1000),
+            with_hard_pin: false,
+            preferred_segments: Vec::new(),
+        };
+
+        assert!(matches!(
+            config.to_ffi(),
+            Err(StoreError::InvalidArgument(_))
+        ));
+    }
+
     #[test]
     fn replicate_config_to_ffi_rejects_interior_nul() {
         let config = ReplicateConfig {
             replica_num: 1,
-            with_soft_pin: false,
+            soft_pin_action: SoftPinAction::Preserve,
+            soft_pin_ttl_ms: None,
             with_hard_pin: false,
             preferred_segments: vec!["bad\0segment".to_string()],
         };
@@ -690,7 +740,8 @@ mod tests {
     fn prepare_config_some_preserves_storage_and_values() {
         let config = ReplicateConfig {
             replica_num: 4,
-            with_soft_pin: true,
+            soft_pin_action: SoftPinAction::Enable,
+            soft_pin_ttl_ms: None,
             with_hard_pin: false,
             preferred_segments: vec!["x".to_string(), "y".to_string()],
         };
@@ -699,7 +750,9 @@ mod tests {
             MooncakeStore::prepare_config(Some(&config)).expect("prepare should succeed");
         let cfg_ref = c_cfg.as_ref().expect("expected Some config");
         assert_eq!(cfg_ref.replica_num, 4);
-        assert_eq!(cfg_ref.with_soft_pin, 1);
+        assert_eq!(cfg_ref.soft_pin_action, SoftPinAction::Enable as i32);
+        assert_eq!(cfg_ref.has_soft_pin_ttl, 0);
+        assert_eq!(cfg_ref.soft_pin_ttl_ms, 0);
         assert_eq!(cfg_ref.with_hard_pin, 0);
         assert_eq!(cfg_ref.preferred_segments_count, 2);
         assert_eq!(strings.len(), 2);
diff --git a/mooncake-store/src/CMakeLists.txt b/mooncake-store/src/CMakeLists.txt
index f20c7cbf7d..14f7fe7d83 100644
--- a/mooncake-store/src/CMakeLists.txt
+++ b/mooncake-store/src/CMakeLists.txt
@@ -1,48 +1,57 @@
-# Find Python package
+find_package(OpenSSL REQUIRED COMPONENTS Crypto)
+
 add_subdirectory(cachelib_memory_allocator)
+add_subdirectory(local_ssd)
+
+set(MOONCAKE_STORE_SHARED_SOURCES
+    allocator_metric.cpp
+    types.cpp
+    common/network.cpp
+    thread_pool.cpp
+    etcd_helper.cpp
+    uds_transport.cpp
+    config/distributed_storage_config.cpp
+    config/rpc_protocol_config.cpp
+    storage/distributed/distributed_storage_backend.cpp
+    storage/distributed/posix_fs_adapter.cpp
+    common/file_util.cpp)
 
-set(MOONCAKE_STORE_SOURCES
+set(MOONCAKE_STORE_MASTER_SOURCES
+    allocation_strategy.cpp
     allocator.cpp
+    config/ha_cluster_namespace_config.cpp
+    config/local_file_snapshot_config.cpp
+    config/redis_connection_config.cpp
+    config/s3_client_config.cpp
+    segment_allocator_registration.cpp
+    client_offboarding.cpp
     master_service.cpp
     master_snapshot_manager.cpp
     master_snapshot_repository.cpp
-    client_service.cpp
-    client_metric.cpp
-    types.cpp
-    master_client.cpp
-    utils.cpp
-    mmap_arena.cpp
     master_metric_manager.cpp
-    storage_backend.cpp
-    thread_pool.cpp
-    etcd_helper.cpp
+    segment/region_driver.cpp
+    placement/index.cpp
+    placement/replica_allocator.cpp
+    segment/catalog.cpp
+    segment/pool.cpp
+    segment/pool_mount.cpp
+    segment/snapshot.cpp
+    ha/snapshot/allocator_snapshot_codec.cpp
+    ha/snapshot/store_resource_snapshot_codec.cpp
+    segment/pool_write_access.cpp
+    segment/pool_read_access.cpp
     segment.cpp
-    transfer_task.cpp
     tenant_quota.cpp
+    tenant_quota_ledger.cpp
     tenant_quota_policy_store.cpp
+    weight_metadata_store.cpp
     rpc_service.cpp
     master_admin_service.cpp
     offset_allocator.cpp
-    posix_file.cpp
-    client_buffer.cpp
-    aligned_client_buffer.cpp
-    real_client.cpp
-    registered_pinned_memory.cpp
-    dummy_client.cpp
-    uds_transport.cpp
-    shm_helper.cpp
     http_metadata_server.cpp
-    file_storage.cpp
     serialize/serializer.cpp
-    storage/distributed/distributed_storage_backend.cpp
-    device/accelerator_device.cpp
-    device/accelerator_registry.cpp
-    device/runtime_accelerator.cpp
-    device/cuda_like_accelerator_device.cpp
-    device/cuda_ipc_buffer.cpp
-    device/hip_accelerator_device.cpp
-    device/ascend_accelerator_device.cpp
-    device/sunrise_accelerator_device.cpp
+    storage/distributed/dfs_global_allocator.cpp
+    storage/distributed/immutable_bucket_allocator.cpp
     ha/leadership/leader_coordinator_factory.cpp
     ha/leadership/backends/etcd/etcd_leader_coordinator.cpp
     ha/common/redis/redis_connection.cpp
@@ -50,16 +59,25 @@ set(MOONCAKE_STORE_SOURCES
     ha/leadership/master_service_supervisor.cpp
     ha/kv/etcd_ha_kv_backend.cpp
     ha/standby_controller.cpp
+    ha/standby_metadata_store.cpp
     ha/snapshot/catalog_backed_snapshot_provider.cpp
+    ha/snapshot/batch_oplog/codec.cpp
+    ha/snapshot/batch_oplog/metadata.cpp
+    ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.cpp
+    ha/snapshot/batch_oplog/writer.cpp
+    ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.cpp
+    ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.cpp
+    ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.cpp
+    ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.cpp
+    ha/snapshot/snapshot_maintenance_lease.cpp
     ha/snapshot/master_snapshot_codec.cpp
+    ha/snapshot/local_ssd_codec.cpp
     ha/snapshot/object/snapshot_object_store.cpp
     ha/snapshot/object/backends/local/local_file_snapshot_object_store.cpp
     ha/snapshot/object/backends/s3/s3_snapshot_object_store.cpp
     ha/snapshot/catalog/backends/embedded/embedded_snapshot_catalog_store.cpp
     ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.cpp
-    utils/file_util.cpp
     task_manager.cpp
-    local_hot_cache.cpp
     ha/oplog/oplog_types.cpp
     ha/oplog/oplog_batch_codec.cpp
     ha/oplog/oplog_batch_storage.cpp
@@ -71,35 +89,146 @@ set(MOONCAKE_STORE_SOURCES
     hot_standby_service.cpp
     metadata_store.cpp
     standby_state_machine.cpp
-    ha_metric_manager.cpp
+    ha_metric_manager.cpp)
+
+set(MOONCAKE_STORE_CLIENT_SOURCES
+    common/client_buffer_allocation.cpp
+    mmap_arena.cpp
+    config/hugepage_config.cpp
+    config/mmap_arena_config.cpp
+    common/mmap_buffer.cpp
+    client_service.cpp
+    client_metric.cpp
+    master_client.cpp
+    storage_backend.cpp
+    nvme_kv/backend.cpp
+    nvme_kv/connector.cpp
+    nvme_kv/config/connector_config.cpp
+    nvme_kv/config/io_concurrency_config.cpp
+    nvme_kv/config/u32_parser.cpp
+    nvme_kv/executor_io_uring.cpp
+    nvme_kv/executor_ioctl.cpp
+    nvme_kv/executor_util.cpp
+    nvme_kv/key_codec.cpp
+    nvme_kv/key_conflict_policy.cpp
+    nvme_kv/object_layout.cpp
+    transfer_task.cpp
+    config/fileread_worker_pool_config.cpp
+    posix_file.cpp
+    client_buffer.cpp
+    aligned_client_buffer.cpp
+    real_client.cpp
+    config/registered_pinned_memory_config.cpp
+    registered_pinned_memory.cpp
+    dummy_client.cpp
+    shm_helper.cpp
+    file_storage.cpp
+    config/client_host_identity_config.cpp
+    config/client_metric_config.cpp
+    config/file_storage_config.cpp
+    config/bucket_backend_config.cpp
+    config/file_per_key_config.cpp
+    config/client_auto_port_config.cpp
+    config/client_auto_discovery_config.cpp
+    config/cxl_segment_config.cpp
+    config/client_numa_config.cpp
+    config/local_hot_cache_config.cpp
+    config/nof_register_config.cpp
+    config/offset_allocator_backend_config.cpp
+    config/replica_selection_config.cpp
+    config/rpc_timeout_config.cpp
+    config/spdk_controller_config.cpp
+    config/transfer_submitter_config.cpp
+    device/accelerator_device.cpp
+    device/accelerator_registry.cpp
+    device/runtime_accelerator.cpp
+    device/cuda_like_accelerator_device.cpp
+    device/cuda_ipc_buffer.cpp
+    device/hip_accelerator_device.cpp
+    device/ascend_accelerator_device.cpp
+    device/sunrise_accelerator_device.cpp
+    local_hot_cache.cpp
     store_c.cpp
     memory_alloc.cpp
     ssd_register_client.cpp
     engram/engram_store.cpp)
 
+if(BUILD_UNIT_TESTS)
+  list(APPEND MOONCAKE_STORE_CLIENT_SOURCES nvme_kv/executor_stub.cpp)
+endif()
 set(EXTRA_LIBS "")
 set(SPDK_STATIC_LIBS "")
 
+# RISC-V toolchains may implement 16-byte atomic operations in libatomic rather
+# than emitting native instructions. Boost.Lockfree uses these operations in the
+# Store master, so detect and propagate the runtime library in RISC-V mode.
+if(USE_RISCV)
+  include(CheckCXXSourceCompiles)
+  check_cxx_source_compiles(
+    "
+alignas(16) volatile unsigned __int128 value = 0;
+int main(int argc, char**) {
+  __atomic_store_n(&value, static_cast<unsigned __int128>(argc),
+                   __ATOMIC_SEQ_CST);
+  return static_cast<int>(__atomic_load_n(&value, __ATOMIC_SEQ_CST));
+}
+"
+    MOONCAKE_HAS_NATIVE_16BYTE_ATOMICS)
+  if(NOT MOONCAKE_HAS_NATIVE_16BYTE_ATOMICS)
+    set(CMAKE_REQUIRED_LIBRARIES_SAVE ${CMAKE_REQUIRED_LIBRARIES})
+    set(CMAKE_REQUIRED_LIBRARIES atomic)
+    check_cxx_source_compiles(
+      "
+alignas(16) volatile unsigned __int128 value = 0;
+int main(int argc, char**) {
+  __atomic_store_n(&value, static_cast<unsigned __int128>(argc),
+                   __ATOMIC_SEQ_CST);
+  return static_cast<int>(__atomic_load_n(&value, __ATOMIC_SEQ_CST));
+}
+"
+      MOONCAKE_HAS_LIBATOMIC_16BYTE_ATOMICS)
+    set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES_SAVE})
+    if(MOONCAKE_HAS_LIBATOMIC_16BYTE_ATOMICS)
+      list(APPEND EXTRA_LIBS atomic)
+      message(STATUS "16-byte atomics: using libatomic")
+    else()
+      message(FATAL_ERROR "16-byte atomic operations are not supported")
+    endif()
+  endif()
+endif()
+
+# Alibaba Cloud OSS adapter (REST API with OSS V4 signing).
+find_package(CURL QUIET)
+find_package(OpenSSL QUIET)
+if(CURL_FOUND AND OpenSSL_FOUND)
+  message(STATUS "Alibaba Cloud OSS adapter: Enabled")
+  set(MOONCAKE_OSS_ADAPTER_ENABLED
+      TRUE
+      CACHE INTERNAL "Whether the Alibaba Cloud OSS adapter is built")
+  list(APPEND MOONCAKE_STORE_CLIENT_SOURCES config/oss_adapter_config.cpp
+       storage/distributed/oss_adapter.cpp)
+  list(APPEND EXTRA_LIBS CURL::libcurl OpenSSL::Crypto)
+  add_definitions(-DHAVE_OSS_ADAPTER)
+else()
+  message(
+    STATUS "Alibaba Cloud OSS adapter: Disabled (requires CURL and OpenSSL)")
+  set(MOONCAKE_OSS_ADAPTER_ENABLED
+      FALSE
+      CACHE INTERNAL "Whether the Alibaba Cloud OSS adapter is built")
+endif()
+
 # Find AWS SDK
 find_package(AWSSDK QUIET COMPONENTS s3)
 if(AWSSDK_FOUND)
   message(STATUS "AWS SDK found: ${AWSSDK_VERSION}")
   set(HAVE_AWS_SDK TRUE)
   # Add S3 related source files
-  list(APPEND MOONCAKE_STORE_SOURCES utils/s3_helper.cpp)
+  list(APPEND MOONCAKE_STORE_MASTER_SOURCES common/s3_helper.cpp)
 else()
   message(STATUS "AWS SDK not found, S3 functionality will be disabled")
   set(HAVE_AWS_SDK FALSE)
 endif()
 
-# Find zstd library
-find_library(ZSTD_LIBRARY NAMES zstd)
-if(NOT ZSTD_LIBRARY)
-  message(FATAL_ERROR "zstd library not found")
-endif()
-
-set(EXTRA_LIBS ${ZSTD_LIBRARY})
-
 # If AWS SDK is found, add it to EXTRA_LIBS
 if(HAVE_AWS_SDK)
   list(APPEND EXTRA_LIBS ${AWSSDK_LINK_LIBRARIES})
@@ -110,55 +239,17 @@ if(HAVE_AWS_SDK)
   endif()
 endif()
 
-# Find xxHash (required for ComputeChecksum)
-find_path(
-  XXHASH_INCLUDE_DIR
-  NAMES xxhash.h
-  PATHS /usr/include /usr/local/include)
-find_library(
-  XXHASH_LIBRARY
-  NAMES xxhash libxxhash
-  PATHS /usr/lib /usr/local/lib /usr/lib64)
 set(KV_EVENTS_ZMQ_FOUND FALSE)
 if(ENABLE_KV_EVENTS)
-  find_library(
-    ZMQ_LIBRARY
-    NAMES zmq libzmq
-    PATHS /usr/lib /usr/local/lib /usr/lib64)
-  find_path(
-    ZMQ_INCLUDE_DIR
-    NAMES zmq.h
-    PATHS /usr/include /usr/local/include)
-  if(ZMQ_INCLUDE_DIR AND ZMQ_LIBRARY)
-    message(STATUS "Found ZMQ: include=${ZMQ_INCLUDE_DIR} lib=${ZMQ_LIBRARY}")
-    list(APPEND MASTER_EXTRA_INCS ${ZMQ_INCLUDE_DIR})
-    list(APPEND EXTRA_LIBS ${ZMQ_LIBRARY})
-    list(APPEND MOONCAKE_STORE_SOURCES kv_event/kv_event_publisher.cpp)
-    set(KV_EVENTS_ZMQ_FOUND TRUE)
-  else()
-    message(
-      FATAL_ERROR
-        "ENABLE_KV_EVENTS is ON but libzmq was not found. "
-        "Install libzmq3-dev or pass -DENABLE_KV_EVENTS=OFF to configure without ZMQ."
-    )
-  endif()
-endif()
-
-if(XXHASH_INCLUDE_DIR AND XXHASH_LIBRARY)
-  message(
-    STATUS "Found xxHash: include=${XXHASH_INCLUDE_DIR} lib=${XXHASH_LIBRARY}")
-  list(APPEND MASTER_EXTRA_INCS ${XXHASH_INCLUDE_DIR})
-else()
-  message(
-    FATAL_ERROR
-      "xxHash library/header not found. Please install xxhash (development headers) and try again."
-  )
+  list(APPEND MOONCAKE_STORE_MASTER_SOURCES kv_event/kv_event_publisher.cpp)
+  set(KV_EVENTS_ZMQ_FOUND TRUE)
 endif()
 
 if(USE_3FS)
   add_subdirectory(hf3fs)
-  list(APPEND MOONCAKE_STORE_SOURCES ${HF3FS_SOURCES})
-  list(APPEND MOONCAKE_STORE_SOURCES storage/distributed/hf3fs_adapter.cpp)
+  list(APPEND MOONCAKE_STORE_SHARED_SOURCES ${HF3FS_SOURCES})
+  list(APPEND MOONCAKE_STORE_SHARED_SOURCES
+       storage/distributed/hf3fs_adapter.cpp)
   find_library(
     HF3FS_API_LIB hf3fs_api_shared
     PATHS /usr/lib
@@ -169,25 +260,46 @@ if(USE_3FS)
   list(APPEND EXTRA_LIBS ${HF3FS_API_LIB})
 endif()
 
-# io_uring support (auto-detected)
-find_library(URING_LIB uring PATHS /usr/lib /usr/lib64 /usr/local/lib
-                                   /usr/local/lib64)
-find_path(URING_INCLUDE liburing.h PATHS /usr/include /usr/local/include)
-if(URING_LIB AND URING_INCLUDE)
-  message(STATUS "io_uring: Enabled for mooncake_store")
-  list(APPEND MOONCAKE_STORE_SOURCES uring_file.cpp)
-  list(APPEND EXTRA_LIBS ${URING_LIB})
-else()
-  message(STATUS "io_uring: Disabled (liburing not found)")
-endif()
-
-if(STORE_USE_REDIS)
-  list(APPEND EXTRA_LIBS ${MOONCAKE_STORE_HIREDIS_LIBRARY})
+set(MOONCAKE_HAVE_NVME_URING_CMD OFF)
+if(TARGET Mooncake::liburing)
+  list(APPEND MOONCAKE_STORE_CLIENT_SOURCES uring_file.cpp)
+
+  include(CheckCXXSourceCompiles)
+  get_target_property(MOONCAKE_LIBURING_INCLUDE_DIRS Mooncake::liburing
+                      INTERFACE_INCLUDE_DIRECTORIES)
+  set(CMAKE_REQUIRED_INCLUDES_SAVE ${CMAKE_REQUIRED_INCLUDES})
+  set(CMAKE_REQUIRED_INCLUDES ${MOONCAKE_LIBURING_INCLUDE_DIRS})
+  check_cxx_source_compiles(
+    "
+#include <liburing.h>
+#include <linux/nvme_ioctl.h>
+int main() {
+    struct nvme_uring_cmd cmd{};
+    io_uring_sqe sqe{};
+    sqe.cmd_op = NVME_URING_CMD_IO;
+    (void)sqe.cmd;
+    io_uring_cqe cqe{};
+    (void)cqe.big_cqe;
+    unsigned flags = IORING_OP_URING_CMD | IORING_SETUP_CQE32;
+    return static_cast<int>(flags) + cmd.opcode;
+}
+"
+    MOONCAKE_NVME_URING_CMD_COMPILES)
+  set(CMAKE_REQUIRED_INCLUDES ${CMAKE_REQUIRED_INCLUDES_SAVE})
+  if(MOONCAKE_NVME_URING_CMD_COMPILES)
+    set(MOONCAKE_HAVE_NVME_URING_CMD ON)
+    message(STATUS "io_uring: NVMe uring command support enabled")
+  else()
+    message(
+      STATUS
+        "io_uring: NVMe uring command support unavailable, NVMe KV io_uring executor disabled"
+    )
+  endif()
 endif()
 
-list(APPEND MOONCAKE_STORE_SOURCES k8s_lease_helper.cpp)
+list(APPEND MOONCAKE_STORE_MASTER_SOURCES k8s_lease_helper.cpp)
 if(STORE_USE_K8S_LEASE)
-  list(APPEND MOONCAKE_STORE_SOURCES
+  list(APPEND MOONCAKE_STORE_MASTER_SOURCES
        ha/leadership/backends/k8s/k8s_leader_coordinator.cpp)
   list(APPEND EXTRA_LIBS ${K8S_LEASE_WRAPPER_LIB})
   set_source_files_properties(
@@ -199,7 +311,11 @@ endif()
 
 if(USE_NOF)
   add_subdirectory(spdk)
-  list(APPEND MOONCAKE_STORE_SOURCES ${SPDK_WRAPPER_SOURCES})
+  list(APPEND MOONCAKE_STORE_CLIENT_SOURCES ${SPDK_WRAPPER_SOURCES})
+
+  # The master's NoF heartbeat probe also goes through SpdkWrapper.
+  list(APPEND MOONCAKE_STORE_MASTER_SOURCES ${SPDK_WRAPPER_SOURCES}
+       config/spdk_controller_config.cpp)
 
   set(SPDK_INCLUDE_DIR
       "/usr/local/include"
@@ -214,6 +330,16 @@ if(USE_NOF)
       "/usr/local/lib"
       CACHE PATH "DPDK static library directory")
 
+  set(SPDK_ISA_L_LIB_DIR
+      "${CMAKE_SOURCE_DIR}/extern/spdk/isa-l/.libs"
+      CACHE PATH "isa-l static library directory")
+  if(NOT EXISTS "${SPDK_ISA_L_LIB_DIR}/libisal.a")
+    message(
+      FATAL_ERROR
+        "isa-l not found at ${SPDK_ISA_L_LIB_DIR}/libisal.a. Run "
+        "`sudo bash dependencies.sh --with-spdk`, or set -DSPDK_ISA_L_LIB_DIR.")
+  endif()
+
   set(SPDK_STATIC_LIBS
       -Wl,--whole-archive
       ${SPDK_LIB_DIR}/libspdk_event.a
@@ -266,6 +392,7 @@ if(USE_NOF)
       crypto
       aio
       z
+      -L${SPDK_ISA_L_LIB_DIR}
       isal
       elf
       ibverbs
@@ -274,91 +401,284 @@ if(USE_NOF)
       bsd)
 endif()
 
-# The cache_allocator library
-include_directories(${Python3_INCLUDE_DIRS})
-add_library(mooncake_store ${MOONCAKE_STORE_SOURCES})
+# Resolve target-independent configuration before defining the Store targets.
+set(MOONCAKE_STORE_INCLUDE_DIRS
+    ${MOONCAKE_STORE_INCLUDE_ROOT}/mooncake-store/proto
+    ${MOONCAKE_STORE_INCLUDE_ROOT} ${CMAKE_CURRENT_BINARY_DIR}/../include
+    ${ETCD_WRAPPER_INCLUDE})
+
+# jemalloc replaces the process allocator, so it is linked into the executables
+# rather than into libmooncake_store, which is also consumed by the Python
+# extension and must not force an allocator on its host process.
+#
+# The results are copied into ALLOCATOR_* rather than used through the
+# JEMALLOC_* names directly: pkg_check_modules writes those into the CMake
+# cache, so a build directory reconfigured back to STORE_USE_JEMALLOC=OFF would
+# keep linking the allocator while the compile definition is gone, leaving the
+# binary running on jemalloc but reporting mooncake_jemalloc_enabled 0. These
+# four are plain variables, so clearing them here takes effect every configure.
+set(ALLOCATOR_DEFS)
+set(ALLOCATOR_INCS)
+set(ALLOCATOR_LIB_DIRS)
+set(ALLOCATOR_LIBS)
+if(STORE_USE_JEMALLOC)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(JEMALLOC REQUIRED jemalloc)
+  set(ALLOCATOR_DEFS STORE_USE_JEMALLOC)
+  set(ALLOCATOR_INCS ${JEMALLOC_INCLUDE_DIRS})
+  set(ALLOCATOR_LIB_DIRS ${JEMALLOC_LIBRARY_DIRS})
+  set(ALLOCATOR_LIBS ${JEMALLOC_STATIC_LIBRARIES})
+endif()
+
+include(CheckPIESupported)
+check_pie_supported(LANGUAGES CXX)
+
+string(TOUPPER "${CMAKE_BUILD_TYPE}" CMAKE_BUILD_TYPE_UPPER)
+
+# Store Client accelerator staging follows the explicitly selected build
+# backend. In particular, non-CUDA wheels are built in a CUDA toolchain image,
+# so SDK presence must not enable CUDA support by itself.
+if(USE_CUDA)
+  find_package(CUDAToolkit REQUIRED)
+elseif(USE_HIP)
+  find_package(hip REQUIRED)
+endif()
+
+# Sources used by both the Master and Client sides of Store.
+add_library(mooncake_store_shared_objects OBJECT
+            ${MOONCAKE_STORE_SHARED_SOURCES})
+set_target_properties(mooncake_store_shared_objects
+                      PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(mooncake_store_shared_objects
+                           PRIVATE ${MOONCAKE_STORE_INCLUDE_DIRS})
+target_link_libraries(
+  mooncake_store_shared_objects
+  PRIVATE cachelib_memory_allocator
+          transfer_metadata_plugin
+          glog::glog
+          gflags::gflags
+          mooncake_common
+          numa
+          asio_shared
+          yalantinglibs::yalantinglibs)
+if(STORE_USE_ETCD)
+  add_dependencies(mooncake_store_shared_objects build_etcd_wrapper)
+endif()
+if(USE_UB)
+  target_link_libraries(mooncake_store_shared_objects PRIVATE ub_allocator)
+endif()
+
+# Sources used by mooncake_master and the complete mooncake_store library.
+add_library(mooncake_store_master_objects OBJECT
+            ${MOONCAKE_STORE_MASTER_SOURCES})
+set_target_properties(mooncake_store_master_objects
+                      PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(
+  mooncake_store_master_objects PRIVATE ${MOONCAKE_STORE_INCLUDE_DIRS}
+                                        ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(
+  mooncake_store_master_objects
+  PRIVATE mooncake_store_shared_objects
+          mooncake_local_ssd
+          transfer_metadata_plugin
+          cachelib_memory_allocator
+          glog::glog
+          gflags::gflags
+          JsonCpp::JsonCpp
+          yaml-cpp
+          mooncake_common
+          Mooncake::zstd
+          Mooncake::xxhash
+          OpenSSL::Crypto
+          asio_shared
+          yalantinglibs::yalantinglibs)
 if(KV_EVENTS_ZMQ_FOUND)
-  target_compile_definitions(mooncake_store PRIVATE MOONCAKE_ENABLE_KV_EVENTS=1)
+  target_compile_definitions(mooncake_store_master_objects
+                             PRIVATE MOONCAKE_ENABLE_KV_EVENTS=1)
+  target_link_libraries(mooncake_store_master_objects PRIVATE Mooncake::libzmq)
 endif()
 if(MOONCAKE_ENABLE_OPLOG_PERF_METRICS)
-  target_compile_definitions(mooncake_store
+  target_compile_definitions(mooncake_store_master_objects
                              PRIVATE MOONCAKE_ENABLE_OPLOG_PERF_METRICS)
 endif()
-target_include_directories(mooncake_store PUBLIC ${XXHASH_INCLUDE_DIR})
+if(STORE_USE_REDIS)
+  target_link_libraries(mooncake_store_master_objects PRIVATE Mooncake::hiredis)
+endif()
+if(STORE_USE_ETCD)
+  add_dependencies(mooncake_store_master_objects build_etcd_wrapper)
+endif()
+if(STORE_USE_K8S_LEASE)
+  add_dependencies(mooncake_store_master_objects build_k8s_lease_wrapper)
+endif()
+
+# Sources used only by Store clients and the complete mooncake_store library.
+add_library(mooncake_store_client_objects OBJECT
+            ${MOONCAKE_STORE_CLIENT_SOURCES})
+set_target_properties(mooncake_store_client_objects
+                      PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(
+  mooncake_store_client_objects PRIVATE ${MOONCAKE_STORE_INCLUDE_DIRS}
+                                        ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(
+  mooncake_store_client_objects
+  PRIVATE mooncake_store_shared_objects
+          transfer_engine
+          cachelib_memory_allocator
+          glog::glog
+          gflags::gflags
+          JsonCpp::JsonCpp
+          yaml-cpp
+          Mooncake::xxhash
+          mooncake_common
+          numa
+          asio_shared
+          yalantinglibs::yalantinglibs)
+if(BUILD_UNIT_TESTS)
+  target_compile_definitions(mooncake_store_client_objects
+                             PRIVATE MOONCAKE_ENABLE_NVME_KV_TEST_STUB=1)
+endif()
 if(USE_NOF)
-  target_include_directories(mooncake_store PRIVATE ${SPDK_INCLUDE_DIR}
-                                                    ${DPDK_INCLUDE_DIR})
+  target_include_directories(mooncake_store_client_objects
+                             PRIVATE ${SPDK_INCLUDE_DIR} ${DPDK_INCLUDE_DIR})
+endif()
+if(TARGET Mooncake::liburing)
+  target_compile_definitions(mooncake_store_client_objects PRIVATE USE_URING)
+  target_link_libraries(mooncake_store_client_objects
+                        PRIVATE Mooncake::liburing)
+  if(MOONCAKE_HAVE_NVME_URING_CMD)
+    target_compile_definitions(mooncake_store_client_objects
+                               PRIVATE MOONCAKE_HAVE_NVME_URING_CMD=1)
+  endif()
+endif()
+if(STORE_USE_ETCD)
+  add_dependencies(mooncake_store_client_objects build_etcd_wrapper)
+endif()
+if(USE_CUDA)
+  message(STATUS "mooncake_store: CUDA enabled, enabling D2H staging")
+  target_compile_definitions(mooncake_store_client_objects PRIVATE USE_CUDA)
+  target_include_directories(mooncake_store_client_objects
+                             PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
+elseif(USE_HIP)
+  message(STATUS "mooncake_store: HIP enabled, enabling D2H staging")
+  target_compile_definitions(mooncake_store_client_objects PRIVATE USE_HIP)
+endif()
+if(USE_ASCEND
+   OR USE_ASCEND_DIRECT
+   OR USE_UBSHMEM)
+  target_include_directories(mooncake_store_client_objects
+                             PRIVATE $ENV{ASCEND_PATH}/include)
+endif()
+
+# Reduced Store library linked by mooncake_master.
+add_library(
+  mooncake_store_master STATIC $<TARGET_OBJECTS:mooncake_store_shared_objects>
+                               $<TARGET_OBJECTS:mooncake_store_master_objects>)
+target_include_directories(mooncake_store_master
+                           PUBLIC ${MOONCAKE_STORE_INCLUDE_DIRS})
+if(USE_NOF)
+  target_include_directories(mooncake_store_master_objects
+                             PRIVATE ${SPDK_INCLUDE_DIR} ${DPDK_INCLUDE_DIR})
+endif()
+target_link_libraries(
+  mooncake_store_master
+  PRIVATE ${SPDK_STATIC_LIBS}
+          mooncake_local_ssd
+          cachelib_memory_allocator
+          ${ETCD_WRAPPER_LIB}
+          glog::glog
+          ${EXTRA_LIBS}
+          mooncake_common
+          Mooncake::zstd
+          asio_shared
+          yalantinglibs::yalantinglibs
+          transfer_metadata_plugin
+          gflags::gflags
+          JsonCpp::JsonCpp
+          yaml-cpp
+          Mooncake::xxhash
+          OpenSSL::Crypto
+          numa)
+if(KV_EVENTS_ZMQ_FOUND)
+  target_link_libraries(mooncake_store_master PRIVATE Mooncake::libzmq)
 endif()
-target_link_libraries(mooncake_store PUBLIC ${XXHASH_LIBRARY})
 if(STORE_USE_REDIS)
-  target_include_directories(mooncake_store
-                             PRIVATE ${MOONCAKE_STORE_HIREDIS_INCLUDE_DIR})
+  target_link_libraries(mooncake_store_master PRIVATE Mooncake::hiredis)
+endif()
+if(USE_UB)
+  target_link_libraries(mooncake_store_master PRIVATE ub_allocator)
 endif()
-# Note: transfer_engine is PRIVATE to avoid propagating its dependencies (e.g.,
-# vendor-specific hardware) to targets that don't need it (e.g.,
-# mooncake_master). Targets that need transfer_engine should link it explicitly.
+
+# Complete public Store library.
+add_library(
+  mooncake_store
+  $<TARGET_OBJECTS:mooncake_store_shared_objects>
+  $<TARGET_OBJECTS:mooncake_store_master_objects>
+  $<TARGET_OBJECTS:mooncake_store_client_objects>)
+target_include_directories(mooncake_store PUBLIC ${MOONCAKE_STORE_INCLUDE_DIRS})
 target_link_libraries(
   mooncake_store
-  PUBLIC cachelib_memory_allocator
+  PUBLIC mooncake_local_ssd
+         cachelib_memory_allocator
          ${ETCD_WRAPPER_LIB}
          glog::glog
-         gflags::gflags
          ${EXTRA_LIBS}
          ${SPDK_STATIC_LIBS}
          mooncake_common
-         yaml-cpp
+         Mooncake::zstd
          asio_shared
-         mooncake_common
+         transfer_engine
          yalantinglibs::yalantinglibs
-  PRIVATE transfer_engine JsonCpp::JsonCpp)
-if(STORE_USE_ETCD)
-  add_dependencies(mooncake_store build_etcd_wrapper)
+  PRIVATE gflags::gflags JsonCpp::JsonCpp yaml-cpp Mooncake::xxhash
+          OpenSSL::Crypto numa)
+if(KV_EVENTS_ZMQ_FOUND)
+  target_link_libraries(mooncake_store PRIVATE Mooncake::libzmq)
 endif()
-if(STORE_USE_K8S_LEASE)
-  add_dependencies(mooncake_store build_k8s_lease_wrapper)
+if(STORE_USE_REDIS)
+  target_link_libraries(mooncake_store PRIVATE Mooncake::hiredis)
 endif()
-
-if(URING_LIB AND URING_INCLUDE)
+if(TARGET Mooncake::liburing)
   target_compile_definitions(mooncake_store PUBLIC USE_URING)
-  target_include_directories(mooncake_store PRIVATE ${URING_INCLUDE})
+  target_link_libraries(mooncake_store PUBLIC Mooncake::liburing)
+endif()
+if(USE_CUDA)
+  target_link_libraries(mooncake_store PRIVATE CUDA::cudart)
+elseif(USE_HIP)
+  target_link_libraries(mooncake_store PRIVATE hip::host)
+endif()
+if(USE_ASCEND
+   OR USE_ASCEND_DIRECT
+   OR USE_UBSHMEM)
+  target_link_libraries(mooncake_store PRIVATE ascendcl)
+endif()
+if(USE_SUNRISE)
+  target_link_libraries(
+    mooncake_store PRIVATE ${MC_TANGRT_ROOT}/lib/libtangrt_shared.so
+                           ${MC_TANGRT_ROOT}/lib/libptml_shared.so dl)
 endif()
-
 if(BUILD_SHARED_LIBS)
   install(TARGETS mooncake_store DESTINATION lib)
 endif()
 
-# Master binary
-include(CheckPIESupported)
-check_pie_supported(LANGUAGES CXX)
-
+# Store Master executable.
 add_executable(mooncake_master master.cpp)
-
-set(MASTER_EXTRA_INCS)
-set(MASTER_EXTRA_LIBS)
-
-if(STORE_USE_JEMALLOC)
-  find_package(PkgConfig REQUIRED)
-  pkg_check_modules(JEMALLOC REQUIRED jemalloc)
-  list(APPEND MASTER_EXTRA_INCS ${JEMALLOC_INCLUDE_DIRS})
-  list(APPEND MASTER_EXTRA_LIBS ${JEMALLOC_STATIC_LIBRARIES})
-endif()
-
-target_include_directories(mooncake_master PRIVATE ${MASTER_EXTRA_INCS})
+set_target_properties(mooncake_master PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(mooncake_master PRIVATE ${ALLOCATOR_INCS})
+target_compile_definitions(mooncake_master PRIVATE ${ALLOCATOR_DEFS})
+target_link_directories(mooncake_master PRIVATE ${ALLOCATOR_LIB_DIRS})
 target_link_libraries(
   mooncake_master
-  PRIVATE mooncake_store
+  PRIVATE mooncake_store_master
           cachelib_memory_allocator
           pthread
           ibverbs
           mooncake_common
+          glog::glog
+          gflags::gflags
           JsonCpp::JsonCpp
+          yalantinglibs::yalantinglibs
           ${ETCD_WRAPPER_LIB}
-          ${MASTER_EXTRA_LIBS}
+          ${ALLOCATOR_LIBS}
           asio_shared)
-# mooncake_store is static and propagates optional runtime dependencies to its
-# consumers. The metadata-only master does not use accelerator staging, so drop
-# those dependencies when they do not satisfy any symbols in the final binary.
-target_link_options(mooncake_master PRIVATE "LINKER:--as-needed")
 if(USE_SUNRISE)
   target_link_directories(mooncake_master PRIVATE ${MC_TANGRT_ROOT}/lib)
 endif()
@@ -366,85 +686,51 @@ endif()
 if(STORE_USE_ETCD)
   add_dependencies(mooncake_master build_etcd_wrapper)
 endif()
-
-# Client server binary
-add_executable(mooncake_client real_client_main.cpp)
-# Client needs transfer_engine for data transfer operations
-target_link_libraries(mooncake_client PRIVATE mooncake_store transfer_engine
-                                              asio_shared)
-set_target_properties(mooncake_master mooncake_client
-                      PROPERTIES POSITION_INDEPENDENT_CODE ON)
-
-# Optimize binary sizes only in Release mode
-string(TOUPPER "${CMAKE_BUILD_TYPE}" CMAKE_BUILD_TYPE_UPPER)
 if(CMAKE_BUILD_TYPE_UPPER STREQUAL "RELEASE")
   target_compile_options(mooncake_master PRIVATE -Os)
   target_link_options(mooncake_master PRIVATE -Os -s)
-  target_compile_options(mooncake_client PRIVATE -Os)
-  target_link_options(mooncake_client PRIVATE -Os -s)
 endif()
+install(TARGETS mooncake_master DESTINATION bin)
 
-# GPU runtime library for D2H staging in PutToLocalFile / OffloadObjects.
-# transfer_engine is PRIVATE-linked, so its CUDA/HIP/Ascend dependencies are not
-# propagated; we must detect and link them independently.
-#
-# Auto-detect each toolkit regardless of global USE_CUDA/USE_HIP flags, because
-# USE_CUDA may be OFF even when GPU pointers are present (e.g.
-# WITH_NVIDIA_PEERMEM env var uses nvidia-peermem for RDMA without cudart). Each
-# detected toolkit gets both link libraries AND compile definitions, so that
-# AcceleratorDevice implementations and pinned_buffer_pool.h pick the correct
-# backend.
-#
-# NOTE: mooncake_store is a static library (.a). External consumers (Go CGo,
-# Python pybind) that link it must also link the GPU runtime (e.g. -lcudart).
-# Go's build.sh already does this; CI workflows must do the same.
-
-find_package(CUDAToolkit QUIET)
-if(CUDAToolkit_FOUND)
-  message(STATUS "mooncake_store: CUDAToolkit detected, enabling D2H staging")
-  target_compile_definitions(mooncake_store PRIVATE USE_CUDA)
+# Store Client executable.
+add_executable(mooncake_client real_client_main.cpp)
+set_target_properties(mooncake_client PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(mooncake_client PRIVATE ${ALLOCATOR_INCS})
+target_compile_definitions(mooncake_client PRIVATE ${ALLOCATOR_DEFS})
+target_link_directories(mooncake_client PRIVATE ${ALLOCATOR_LIB_DIRS})
+target_link_libraries(
+  mooncake_client
+  PRIVATE mooncake_store transfer_engine asio_shared gflags::gflags
+          yalantinglibs::yalantinglibs ${ALLOCATOR_LIBS})
+if(USE_CUDA)
   target_compile_definitions(mooncake_client PRIVATE USE_CUDA)
-  target_include_directories(mooncake_store PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
   target_include_directories(mooncake_client
                              PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
-  target_link_libraries(mooncake_store PRIVATE CUDA::cudart)
   target_link_libraries(mooncake_client PRIVATE CUDA::cudart)
+elseif(USE_HIP)
+  target_compile_definitions(mooncake_client PRIVATE USE_HIP)
+  target_link_libraries(mooncake_client PRIVATE hip::host)
 endif()
-
-if(NOT CUDAToolkit_FOUND)
-  find_package(hip QUIET)
-  if(hip_FOUND)
-    message(STATUS "mooncake_store: HIP detected, enabling D2H staging")
-    target_compile_definitions(mooncake_store PRIVATE USE_HIP)
-    target_compile_definitions(mooncake_client PRIVATE USE_HIP)
-    target_link_libraries(mooncake_store PRIVATE hip::host)
-    target_link_libraries(mooncake_client PRIVATE hip::host)
-  endif()
-endif()
-
 if(USE_ASCEND
    OR USE_ASCEND_DIRECT
    OR USE_UBSHMEM)
-  target_include_directories(mooncake_store PRIVATE $ENV{ASCEND_PATH}/include)
-  target_link_libraries(mooncake_store PRIVATE ascendcl)
   target_include_directories(mooncake_client PRIVATE $ENV{ASCEND_PATH}/include)
   target_link_libraries(mooncake_client PRIVATE ascendcl)
 endif()
-
 if(USE_SUNRISE)
-  target_link_libraries(
-    mooncake_store PRIVATE ${MC_TANGRT_ROOT}/lib/libtangrt_shared.so
-                           ${MC_TANGRT_ROOT}/lib/libptml_shared.so dl)
   target_link_libraries(
     mooncake_client PRIVATE ${MC_TANGRT_ROOT}/lib/libtangrt_shared.so
                             ${MC_TANGRT_ROOT}/lib/libptml_shared.so dl)
 endif()
-
-install(TARGETS mooncake_master mooncake_client DESTINATION bin)
+if(CMAKE_BUILD_TYPE_UPPER STREQUAL "RELEASE")
+  target_compile_options(mooncake_client PRIVATE -Os)
+  target_link_options(mooncake_client PRIVATE -Os -s)
+endif()
+install(TARGETS mooncake_client DESTINATION bin)
 
 # ---------------------------------------------------------------------------
-# Optional: a self-contained libmooncake_store.so exporting only the store_c.h
-# C ABI, for consumers that dlopen the store (e.g. the Rust crate's `dlopen`
+# Optional: a self-contained libmooncake_store.so exporting only the store_c.h C
+# ABI, for consumers that dlopen the store (e.g. the Rust crate's `dlopen`
 # feature). Whole-archives the static mooncake_store + asio_static (objects are
 # -fPIC, see mooncake-common/common.cmake) and localizes everything else via the
 # version script; only system/toolkit libs (and the Go etcd/k8s backends when
@@ -454,15 +740,13 @@ if(WITH_STORE_C_SHARED)
   # ELF/GNU-ld features (--whole-archive, --as-needed, version script, $ORIGIN);
   # supported by GNU ld, gold, and lld. Linux only.
   if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
-    message(
-      FATAL_ERROR
-        "WITH_STORE_C_SHARED currently supports Linux/ELF only "
-        "(got CMAKE_SYSTEM_NAME=${CMAKE_SYSTEM_NAME}).")
+    message(FATAL_ERROR "WITH_STORE_C_SHARED currently supports Linux/ELF only "
+                        "(got CMAKE_SYSTEM_NAME=${CMAKE_SYSTEM_NAME}).")
   endif()
 
-  # We whole-archive mooncake_store and reuse its name, so require it to be static
-  # (add_library(mooncake_store) follows BUILD_SHARED_LIBS, which some backends
-  # force ON).
+  # We whole-archive mooncake_store and reuse its name, so require it to be
+  # static (add_library(mooncake_store) follows BUILD_SHARED_LIBS, which some
+  # backends force ON).
   get_target_property(_mooncake_store_type mooncake_store TYPE)
   if(NOT _mooncake_store_type STREQUAL "STATIC_LIBRARY")
     message(
diff --git a/mooncake-store/src/aligned_client_buffer.cpp b/mooncake-store/src/aligned_client_buffer.cpp
index 7569868e42..82f9eca21b 100644
--- a/mooncake-store/src/aligned_client_buffer.cpp
+++ b/mooncake-store/src/aligned_client_buffer.cpp
@@ -6,7 +6,7 @@
 #include <cstring>
 #include <string_view>
 
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 
 #if defined(USE_SUNRISE)
 #include "sunrise_allocator.h"
diff --git a/mooncake-store/src/allocation_strategy.cpp b/mooncake-store/src/allocation_strategy.cpp
new file mode 100644
index 0000000000..f7e93e9e29
--- /dev/null
+++ b/mooncake-store/src/allocation_strategy.cpp
@@ -0,0 +1,69 @@
+#include "allocation_strategy.h"
+
+#include "local_ssd/manager.h"
+#include "segment.h"
+
+namespace mooncake {
+
+tl::expected<std::vector<Replica>, ErrorCode> AllocationStrategy::Allocate(
+    const ScopedAllocatorAccess& placement, const size_t slice_length,
+    const size_t replica_num,
+    const std::vector<std::string>& preferred_segments,
+    const std::set<std::string>& excluded_segments,
+    const ReplicaType replica_type) {
+    return Allocate(placement.getAllocatorManager(), slice_length, replica_num,
+                    preferred_segments, excluded_segments, replica_type);
+}
+
+tl::expected<std::vector<Replica>, ErrorCode>
+SsdFreeRatioFirstAllocationStrategy::Allocate(
+    const ScopedAllocatorAccess& placement, const size_t slice_length,
+    const size_t replica_num,
+    const std::vector<std::string>& preferred_segments,
+    const std::set<std::string>& excluded_segments,
+    const ReplicaType replica_type) {
+    const auto& allocator_manager = placement.getAllocatorManager();
+    return AllocateRanked(
+        allocator_manager, slice_length, replica_num, preferred_segments,
+        excluded_segments, replica_type, [&](const std::string& name) {
+            auto client_id = placement.GetOwnerClientId(name);
+            if (!client_id) {
+                return 1.0;
+            }
+            auto usage = local_ssd_.GetUsage(*client_id);
+            if (!usage || usage->total_capacity_bytes <= 0) {
+                return 1.0;
+            }
+            const int64_t used = std::clamp<int64_t>(
+                usage->used_bytes, 0, usage->total_capacity_bytes);
+            return static_cast<double>(usage->total_capacity_bytes - used) /
+                   static_cast<double>(usage->total_capacity_bytes);
+        });
+}
+
+tl::expected<std::vector<Replica>, ErrorCode>
+SsdFreeRatioFirstAllocationStrategy::Allocate(
+    const AllocatorManager& allocator_manager, const size_t slice_length,
+    const size_t replica_num,
+    const std::vector<std::string>& preferred_segments,
+    const std::set<std::string>& excluded_segments,
+    const ReplicaType replica_type) {
+    return AllocateRanked(
+        allocator_manager, slice_length, replica_num, preferred_segments,
+        excluded_segments, replica_type, [&](const std::string& name) {
+            auto client_id = allocator_manager.GetOwnerClientId(name);
+            if (!client_id) {
+                return 1.0;
+            }
+            auto usage = local_ssd_.GetUsage(*client_id);
+            if (!usage || usage->total_capacity_bytes <= 0) {
+                return 1.0;
+            }
+            const int64_t used = std::clamp<int64_t>(
+                usage->used_bytes, 0, usage->total_capacity_bytes);
+            return static_cast<double>(usage->total_capacity_bytes - used) /
+                   static_cast<double>(usage->total_capacity_bytes);
+        });
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/allocator.cpp b/mooncake-store/src/allocator.cpp
index 6af07242ea..bdf64f9b32 100644
--- a/mooncake-store/src/allocator.cpp
+++ b/mooncake-store/src/allocator.cpp
@@ -4,12 +4,56 @@
 #include <glog/logging.h>
 
 #include <algorithm>
+#include <limits>
 #include <memory>
 #include <numeric>
+#include <stdexcept>
 
 #include "master_metric_manager.h"
 
 namespace mooncake {
+namespace {
+
+bool IsValidCachelibLayout(size_t base, size_t size) noexcept {
+    const size_t slab_count = size / sizeof(facebook::cachelib::Slab);
+    return base != 0 && base % facebook::cachelib::Slab::kSize == 0 &&
+           size >= facebook::cachelib::Slab::kSize &&
+           size % facebook::cachelib::Slab::kSize == 0 &&
+           slab_count <= std::numeric_limits<unsigned int>::max() &&
+           base <= std::numeric_limits<size_t>::max() - size;
+}
+
+bool IsValidAllocation(const LiveAllocation& allocation,
+                       size_t capacity) noexcept {
+    return allocation.requested_size != 0 &&
+           allocation.offset_from_base < capacity &&
+           allocation.requested_size <= capacity - allocation.offset_from_base;
+}
+
+}  // namespace
+
+void BufferAllocatorBase::AttachUsageTracker(
+    const std::shared_ptr<StorageUsageTracker>& usage_tracker) {
+    if (!usage_tracker || usage_registration_) {
+        return;
+    }
+    usage_registration_ = std::make_unique<StorageUsageRegistration>(
+        usage_tracker, cur_size_, capacity());
+}
+
+void BufferAllocatorBase::RecordAllocation(size_t bytes) noexcept {
+    cur_size_.fetch_add(bytes, std::memory_order_relaxed);
+    if (usage_registration_) {
+        usage_registration_->AddUsedBytes(bytes);
+    }
+}
+
+void BufferAllocatorBase::RecordDeallocation(size_t bytes) noexcept {
+    cur_size_.fetch_sub(bytes, std::memory_order_relaxed);
+    if (usage_registration_) {
+        usage_registration_->RemoveUsedBytes(bytes);
+    }
+}
 
 std::string AllocatedBuffer::getSegmentName() const noexcept {
     auto alloc = allocator_.lock();
@@ -41,6 +85,14 @@ AllocatedBuffer::AllocatedBuffer(std::shared_ptr<BufferAllocatorBase> allocator,
     }
 }
 
+bool AllocatedBuffer::copyTransferProtocolFrom(const AllocatedBuffer& source) {
+    if (protocol == "cxl" || source.protocol == "cxl") {
+        return false;
+    }
+    protocol = source.protocol;
+    return true;
+}
+
 // Implementation of get_descriptor
 AllocatedBuffer::Descriptor AllocatedBuffer::get_descriptor() const {
     auto alloc = allocator_.lock();
@@ -83,7 +135,49 @@ std::ostream& operator<<(std::ostream& os, const AllocatedBuffer& buffer) {
               << "buffer_ptr: " << static_cast<void*>(buffer.data()) << " }";
 }
 
-// Removed allocated_bytes parameter and member initialization
+tl::expected<std::shared_ptr<CachelibBufferAllocator>, ErrorCode>
+CachelibBufferAllocator::Create(std::string segment_name, size_t base,
+                                size_t size, std::string transport_endpoint,
+                                ReplicaType replica_type) {
+    if (!IsValidCachelibLayout(base, size)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    // CacheLib's parameter-dependent constructor failures are covered by the
+    // layout validation above. Do not catch allocation failures here: metadata
+    // exhaustion follows the process-level fail-fast policy.
+    return std::shared_ptr<CachelibBufferAllocator>(new CachelibBufferAllocator(
+        std::move(segment_name), base, size, std::move(transport_endpoint),
+        replica_type));
+}
+
+tl::expected<std::shared_ptr<BufferAllocatorBase>, ErrorCode>
+CreateBufferAllocator(BufferAllocatorType allocator_type,
+                      std::string segment_name, size_t base, size_t size,
+                      std::string transport_endpoint,
+                      ReplicaType replica_type) {
+    switch (allocator_type) {
+        case BufferAllocatorType::CACHELIB: {
+            auto allocator = CachelibBufferAllocator::Create(
+                std::move(segment_name), base, size,
+                std::move(transport_endpoint), replica_type);
+            if (!allocator) {
+                return tl::make_unexpected(allocator.error());
+            }
+            return std::shared_ptr<BufferAllocatorBase>(std::move(*allocator));
+        }
+        case BufferAllocatorType::OFFSET:
+            // Offset construction has no parameter-dependent throwing path;
+            // metadata allocation failures intentionally follow fail-fast.
+            return std::shared_ptr<BufferAllocatorBase>(
+                std::make_shared<OffsetBufferAllocator>(
+                    std::move(segment_name), base, size,
+                    std::move(transport_endpoint), replica_type));
+        default:
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+}
+
 CachelibBufferAllocator::CachelibBufferAllocator(std::string segment_name,
                                                  size_t base, size_t size,
                                                  std::string transport_endpoint,
@@ -91,7 +185,6 @@ CachelibBufferAllocator::CachelibBufferAllocator(std::string segment_name,
     : segment_name_(segment_name),
       base_(base),
       total_size_(size),
-      cur_size_(0),
       transport_endpoint_(std::move(transport_endpoint)),
       replica_type_(replica_type) {
     VLOG(1) << "initializing_buffer_allocator segment_name=" << segment_name
@@ -127,10 +220,11 @@ CachelibBufferAllocator::CachelibBufferAllocator(std::string segment_name,
 CachelibBufferAllocator::~CachelibBufferAllocator() {
     if (replica_type_ == ReplicaType::MEMORY) {
         MasterMetricManager::instance().dec_allocated_mem_size(segment_name_,
-                                                               cur_size_);
+                                                               size());
+        MasterMetricManager::instance().remove_segment_metrics(segment_name_);
     } else if (replica_type_ == ReplicaType::NOF_SSD) {
         MasterMetricManager::instance().dec_allocated_nof_size(segment_name_,
-                                                               cur_size_);
+                                                               size());
     }
 };
 
@@ -144,7 +238,7 @@ std::unique_ptr<AllocatedBuffer> CachelibBufferAllocator::allocate(
         if (!buffer) {
             VLOG(1) << "allocation_failed size=" << size
                     << " segment=" << segment_name_
-                    << " current_size=" << cur_size_;
+                    << " current_size=" << GetUsageBytes();
             return nullptr;
         }
     } catch (const std::exception& e) {
@@ -156,7 +250,7 @@ std::unique_ptr<AllocatedBuffer> CachelibBufferAllocator::allocate(
     }
     VLOG(1) << "allocation_succeeded size=" << size
             << " segment=" << segment_name_ << " address=" << buffer;
-    cur_size_.fetch_add(size);
+    RecordAllocation(size);
     if (replica_type_ == ReplicaType::MEMORY) {
         MasterMetricManager::instance().inc_allocated_mem_size(segment_name_,
                                                                size);
@@ -176,7 +270,7 @@ void CachelibBufferAllocator::deallocate(AllocatedBuffer* handle) {
         memory_allocator_->free(buffer);
         size_t freed_size =
             handle->size_;  // Store size before handle might become invalid
-        cur_size_.fetch_sub(freed_size);
+        RecordDeallocation(freed_size);
         if (replica_type_ == ReplicaType::MEMORY) {
             MasterMetricManager::instance().dec_allocated_mem_size(
                 segment_name_, freed_size);
@@ -194,58 +288,57 @@ void CachelibBufferAllocator::deallocate(AllocatedBuffer* handle) {
 }
 
 std::unique_ptr<AllocatedBuffer> CachelibBufferAllocator::adoptImportedBuffer(
-    const AllocatedBuffer::Descriptor& descriptor) {
-    cur_size_.fetch_add(descriptor.size_);
+    const LiveAllocation& allocation) {
+    RecordAllocation(allocation.requested_size);
     if (replica_type_ == ReplicaType::MEMORY) {
         MasterMetricManager::instance().inc_allocated_mem_size(
-            segment_name_, descriptor.size_);
+            segment_name_, allocation.requested_size);
     } else if (replica_type_ == ReplicaType::NOF_SSD) {
         MasterMetricManager::instance().inc_allocated_nof_size(
-            segment_name_, descriptor.size_);
+            segment_name_, allocation.requested_size);
     }
-    return std::make_unique<AllocatedBuffer>(shared_from_this(), descriptor);
+    return std::make_unique<AllocatedBuffer>(
+        shared_from_this(),
+        reinterpret_cast<void*>(base_ + allocation.offset_from_base),
+        allocation.requested_size);
 }
 
-std::optional<RestoredCachelibBufferAllocator> RestoreCachelibBufferAllocator(
+std::optional<RestoredCachelibBufferAllocator> ImportCachelibBufferAllocator(
     std::string segment_name, size_t base, size_t size,
     std::string transport_endpoint,
-    const std::vector<AllocatedBuffer::Descriptor>& descriptors,
-    ReplicaType replica_type) {
+    const std::vector<LiveAllocation>& allocations, ReplicaType replica_type) {
     if (replica_type != ReplicaType::MEMORY ||
-        base % facebook::cachelib::Slab::kSize != 0 ||
-        size < facebook::cachelib::Slab::kSize ||
-        size % facebook::cachelib::Slab::kSize != 0 ||
-        base > std::numeric_limits<size_t>::max() - size) {
+        !IsValidCachelibLayout(base, size)) {
         return std::nullopt;
     }
-    const size_t end = base + size;
     std::vector<MemoryAllocator::ImportedAllocation> imports;
-    imports.reserve(descriptors.size());
-    for (const auto& descriptor : descriptors) {
-        if (descriptor.protocol_ == "cxl" ||
-            descriptor.transport_endpoint_ != transport_endpoint ||
-            descriptor.size_ == 0 || descriptor.size_ > UINT32_MAX ||
-            descriptor.buffer_address_ < base ||
-            descriptor.buffer_address_ >= end ||
-            descriptor.size_ > end - descriptor.buffer_address_) {
+    imports.reserve(allocations.size());
+    for (const auto& allocation : allocations) {
+        if (!IsValidAllocation(allocation, size) ||
+            allocation.requested_size > UINT32_MAX) {
             return std::nullopt;
         }
-        imports.push_back({reinterpret_cast<void*>(descriptor.buffer_address_),
-                           static_cast<uint32_t>(std::max<uint64_t>(
-                               descriptor.size_, kMinSliceSize))});
+        imports.push_back(
+            {reinterpret_cast<void*>(base + allocation.offset_from_base),
+             static_cast<uint32_t>(std::max<uint64_t>(allocation.requested_size,
+                                                      kMinSliceSize))});
     }
 
-    auto allocator = std::make_shared<CachelibBufferAllocator>(
+    auto created = CachelibBufferAllocator::Create(
         std::move(segment_name), base, size, transport_endpoint, replica_type);
+    if (!created) {
+        return std::nullopt;
+    }
+    auto allocator = std::move(*created);
     if (!allocator->memory_allocator_->importAllocations(allocator->pool_id_,
                                                          imports)) {
         return std::nullopt;
     }
 
     std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
-    buffers.reserve(descriptors.size());
-    for (const auto& descriptor : descriptors) {
-        buffers.push_back(allocator->adoptImportedBuffer(descriptor));
+    buffers.reserve(allocations.size());
+    for (const auto& allocation : allocations) {
+        buffers.push_back(allocator->adoptImportedBuffer(allocation));
     }
     return RestoredCachelibBufferAllocator{std::move(allocator),
                                            std::move(buffers)};
@@ -259,7 +352,6 @@ OffsetBufferAllocator::OffsetBufferAllocator(std::string segment_name,
     : segment_name_(segment_name),
       base_(base),
       total_size_(size),
-      cur_size_(0),
       transport_endpoint_(std::move(transport_endpoint)),
       replica_type_(replica_type) {
     VLOG(1) << "initializing_offset_buffer_allocator segment_name="
@@ -277,7 +369,9 @@ OffsetBufferAllocator::OffsetBufferAllocator(std::string segment_name,
         max_capacity =
             std::max(max_capacity, static_cast<uint64_t>(1024 * 1024));
         max_capacity =
-            std::min(max_capacity, static_cast<uint64_t>(64 * 1024 * 1024));
+            std::min(max_capacity,
+                     static_cast<uint64_t>(
+                         offset_allocator::OffsetAllocatorSnapshot::kMaxNodes));
         // Create the offset allocator
         offset_allocator_ = offset_allocator::OffsetAllocator::create(
             base, size, static_cast<uint32_t>(init_capacity),
@@ -295,13 +389,87 @@ OffsetBufferAllocator::OffsetBufferAllocator(std::string segment_name,
     }
 }
 
+OffsetBufferAllocator::OffsetBufferAllocator(
+    OffsetBufferAllocatorSnapshot snapshot,
+    std::shared_ptr<offset_allocator::OffsetAllocator> offset_allocator)
+    : segment_name_(std::move(snapshot.segment_name)),
+      base_(snapshot.base),
+      total_size_(snapshot.capacity),
+      transport_endpoint_(std::move(snapshot.transport_endpoint)),
+      replica_type_(ReplicaType::MEMORY),
+      offset_allocator_(std::move(offset_allocator)) {}
+
+tl::expected<void, std::string>
+OffsetBufferAllocatorSnapshot::ValidateMetadata() const {
+    if (allocation_state.base != base ||
+        allocation_state.capacity != capacity) {
+        return tl::make_unexpected(fmt::format(
+            "allocator bounds mismatch: outer base={}, capacity={}; inner "
+            "base={}, capacity={}",
+            base, capacity, allocation_state.base, allocation_state.capacity));
+    }
+    if (used_bytes > capacity ||
+        used_bytes >
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+        return tl::make_unexpected(
+            fmt::format("invalid usage {} for capacity {} or signed metrics",
+                        used_bytes, capacity));
+    }
+    if (used_bytes != allocation_state.allocated_size) {
+        return tl::make_unexpected(
+            fmt::format("used_bytes {} does not match allocated_size {}",
+                        used_bytes, allocation_state.allocated_size));
+    }
+    return {};
+}
+
+tl::expected<void, std::string> OffsetBufferAllocatorSnapshot::Validate()
+    const {
+    if (auto valid = ValidateMetadata(); !valid) return valid;
+    return allocation_state.Validate();
+}
+
+tl::expected<std::shared_ptr<OffsetBufferAllocator>, ErrorCode>
+OffsetBufferAllocator::Restore(OffsetBufferAllocatorSnapshot snapshot) {
+    const auto used_bytes = snapshot.used_bytes;
+    if (auto valid = snapshot.ValidateMetadata(); !valid) {
+        LOG(ERROR) << "OffsetBufferAllocator::Restore rejected snapshot for "
+                   << snapshot.segment_name << ": " << valid.error();
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    // The inner factory validates its complete snapshot and logs the specific
+    // failure before constructing an allocator. No metrics are published yet.
+    auto offset_allocator = offset_allocator::OffsetAllocator::Restore(
+        std::move(snapshot.allocation_state));
+    if (!offset_allocator) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    auto allocator =
+        std::shared_ptr<OffsetBufferAllocator>(new OffsetBufferAllocator(
+            std::move(snapshot), std::move(*offset_allocator)));
+    // No allocation handles exist yet. Pair restored usage with the same
+    // accounting that allocate()/destruction use, before publishing the object.
+    MasterMetricManager::instance().inc_allocated_mem_size(
+        allocator->segment_name_, static_cast<int64_t>(used_bytes));
+    allocator->SetUsageBytesForRestore(used_bytes);
+    return allocator;
+}
+
+OffsetBufferAllocatorSnapshot OffsetBufferAllocator::CaptureSnapshot() const {
+    return {segment_name_,       base_,
+            total_size_,         size(),
+            transport_endpoint_, offset_allocator_->CaptureSnapshot()};
+}
+
 OffsetBufferAllocator::~OffsetBufferAllocator() {
     if (replica_type_ == ReplicaType::MEMORY) {
         MasterMetricManager::instance().dec_allocated_mem_size(segment_name_,
-                                                               cur_size_);
+                                                               size());
+        MasterMetricManager::instance().remove_segment_metrics(segment_name_);
     } else if (replica_type_ == ReplicaType::NOF_SSD) {
         MasterMetricManager::instance().dec_allocated_nof_size(segment_name_,
-                                                               cur_size_);
+                                                               size());
     }
 };
 
@@ -318,7 +486,7 @@ std::unique_ptr<AllocatedBuffer> OffsetBufferAllocator::allocate(size_t size) {
         if (!allocation_handle) {
             VLOG(1) << "allocation_failed size=" << size
                     << " segment=" << segment_name_
-                    << " current_size=" << cur_size_;
+                    << " current_size=" << GetUsageBytes();
             return nullptr;
         }
 
@@ -339,7 +507,7 @@ std::unique_ptr<AllocatedBuffer> OffsetBufferAllocator::allocate(size_t size) {
         return nullptr;
     }
 
-    cur_size_.fetch_add(size);
+    RecordAllocation(size);
     if (replica_type_ == ReplicaType::MEMORY) {
         MasterMetricManager::instance().inc_allocated_mem_size(segment_name_,
                                                                size);
@@ -356,7 +524,7 @@ void OffsetBufferAllocator::deallocate(AllocatedBuffer* handle) {
         // when the OffsetAllocationHandle goes out of scope
         size_t freed_size = handle->size();
         handle->offset_handle_.reset();
-        cur_size_.fetch_sub(freed_size);
+        RecordDeallocation(freed_size);
         if (replica_type_ == ReplicaType::MEMORY) {
             MasterMetricManager::instance().dec_allocated_mem_size(
                 segment_name_, freed_size);
@@ -392,11 +560,10 @@ size_t OffsetBufferAllocator::getLargestFreeRegion() const {
     }
 }
 
-std::optional<RestoredOffsetBufferAllocator> RestoreOffsetBufferAllocator(
+std::optional<RestoredOffsetBufferAllocator> ImportOffsetBufferAllocator(
     std::string segment_name, size_t base, size_t size,
     std::string transport_endpoint,
-    const std::vector<AllocatedBuffer::Descriptor>& descriptors,
-    ReplicaType replica_type) {
+    const std::vector<LiveAllocation>& allocations, ReplicaType replica_type) {
     if (base > std::numeric_limits<size_t>::max() - size) {
         return std::nullopt;
     }
@@ -405,14 +572,14 @@ std::optional<RestoredOffsetBufferAllocator> RestoreOffsetBufferAllocator(
         std::move(segment_name), base, size, transport_endpoint, replica_type);
     const auto offset_allocator = allocator->getOffsetAllocator();
 
-    std::vector<size_t> order(descriptors.size());
+    std::vector<size_t> order(allocations.size());
     std::iota(order.begin(), order.end(), 0);
     std::sort(order.begin(), order.end(), [&](size_t lhs, size_t rhs) {
-        return descriptors[lhs].buffer_address_ <
-               descriptors[rhs].buffer_address_;
+        return allocations[lhs].offset_from_base <
+               allocations[rhs].offset_from_base;
     });
 
-    std::vector<std::unique_ptr<AllocatedBuffer>> buffers(descriptors.size());
+    std::vector<std::unique_ptr<AllocatedBuffer>> buffers(allocations.size());
     std::vector<std::unique_ptr<AllocatedBuffer>> gaps;
     size_t cursor = base;
 
@@ -452,30 +619,29 @@ std::optional<RestoredOffsetBufferAllocator> RestoreOffsetBufferAllocator(
     };
 
     for (const size_t index : order) {
-        const auto& descriptor = descriptors[index];
-        if (descriptor.transport_endpoint_ != transport_endpoint ||
-            descriptor.size_ == 0 || descriptor.buffer_address_ < cursor ||
-            descriptor.buffer_address_ < base ||
-            descriptor.buffer_address_ >= end ||
-            descriptor.size_ > end - descriptor.buffer_address_) {
+        const auto& allocation = allocations[index];
+        if (!IsValidAllocation(allocation, size)) {
+            return std::nullopt;
+        }
+        const size_t address = base + allocation.offset_from_base;
+        if (address < cursor) {
             return std::nullopt;
         }
-        const uint64_t occupied =
-            offset_allocator->normalizedAllocationSize(descriptor.size_);
-        if (occupied == 0 || occupied > end - descriptor.buffer_address_ ||
-            !fill_gap(descriptor.buffer_address_ - cursor)) {
+        const uint64_t occupied = offset_allocator->normalizedAllocationSize(
+            allocation.requested_size);
+        if (occupied == 0 || occupied > end - address ||
+            !fill_gap(address - cursor)) {
             return std::nullopt;
         }
-        auto buffer = allocator->allocate(descriptor.size_);
-        if (!buffer || reinterpret_cast<size_t>(buffer->data()) !=
-                           descriptor.buffer_address_) {
+        auto buffer = allocator->allocate(allocation.requested_size);
+        if (!buffer || reinterpret_cast<size_t>(buffer->data()) != address) {
             return std::nullopt;
         }
-        cursor = descriptor.buffer_address_ + occupied;
+        cursor = address + occupied;
         buffers[index] = std::move(buffer);
     }
 
-    allocator->restored_gap_buffers_ = std::move(gaps);
+    gaps.clear();
     return RestoredOffsetBufferAllocator{std::move(allocator),
                                          std::move(buffers)};
 }
diff --git a/mooncake-store/src/allocator_metric.cpp b/mooncake-store/src/allocator_metric.cpp
new file mode 100644
index 0000000000..50cb3e9dbc
--- /dev/null
+++ b/mooncake-store/src/allocator_metric.cpp
@@ -0,0 +1,342 @@
+#include "allocator_metric.h"
+
+#include <glog/logging.h>
+
+#include <array>
+#include <atomic>
+#include <cstdio>
+#include <fstream>
+#include <sstream>
+#include <string_view>
+
+namespace mooncake {
+
+namespace {
+
+std::atomic<JemallocStatsCollector> g_jemalloc_collector{nullptr};
+
+constexpr int64_t kKibiBytes = 1024;
+
+// The only label on the per-bin series; its value is the size class in bytes.
+const std::array<std::string, 1> kBinSizeLabel = {"size"};
+
+// /proc/self/status reports sizes as "VmRSS:\t  123456 kB". Takes the line by
+// reference to a std::string so that the sscanf below sees a terminated buffer.
+bool ParseStatusKib(const std::string& line, std::string_view key,
+                    int64_t& bytes) {
+    if (line.size() <= key.size() || line.compare(0, key.size(), key) != 0) {
+        return false;
+    }
+    long long value = 0;
+    if (std::sscanf(line.data() + key.size(), " %lld kB", &value) != 1) {
+        return false;
+    }
+    bytes = static_cast<int64_t>(value) * kKibiBytes;
+    return true;
+}
+
+}  // namespace
+
+void SetJemallocStatsCollector(JemallocStatsCollector collector) {
+    g_jemalloc_collector.store(collector, std::memory_order_release);
+}
+
+AllocatorMetric::AllocatorMetric(
+    const std::map<std::string, std::string>& labels)
+    : process_rss_("mooncake_process_rss_bytes",
+                   "Resident set size of the process", labels),
+      process_rss_peak_("mooncake_process_rss_peak_bytes",
+                        "Peak resident set size since process start", labels),
+      process_rss_anon_("mooncake_process_rss_anon_bytes",
+                        "Resident anonymous memory of the process", labels),
+      process_rss_file_("mooncake_process_rss_file_bytes",
+                        "Resident file-backed memory of the process", labels),
+      process_rss_shmem_("mooncake_process_rss_shmem_bytes",
+                         "Resident shared memory of the process", labels),
+      process_vsize_("mooncake_process_vsize_bytes",
+                     "Virtual address space size of the process", labels),
+      process_swap_("mooncake_process_swap_bytes",
+                    "Swapped-out memory of the process", labels),
+      jemalloc_enabled_("mooncake_jemalloc_enabled",
+                        "1 when jemalloc statistics are being collected",
+                        labels),
+      jemalloc_allocated_(
+          "mooncake_jemalloc_allocated_bytes",
+          "Bytes allocated by the application and not yet freed", labels),
+      jemalloc_active_("mooncake_jemalloc_active_bytes",
+                       "Bytes in pages backing active allocations", labels),
+      jemalloc_metadata_("mooncake_jemalloc_metadata_bytes",
+                         "Bytes used by allocator metadata", labels),
+      jemalloc_resident_("mooncake_jemalloc_resident_bytes",
+                         "Bytes in physically resident pages", labels),
+      jemalloc_retained_("mooncake_jemalloc_retained_bytes",
+                         "Bytes of address space retained but not resident",
+                         labels),
+      jemalloc_mapped_("mooncake_jemalloc_mapped_bytes",
+                       "Bytes in extents mapped by the allocator", labels),
+      jemalloc_small_allocated_("mooncake_jemalloc_small_allocated_bytes",
+                                "Allocated bytes served by small size classes",
+                                labels),
+      jemalloc_large_allocated_("mooncake_jemalloc_large_allocated_bytes",
+                                "Allocated bytes served by large size classes",
+                                labels),
+      jemalloc_dirty_("mooncake_jemalloc_dirty_bytes",
+                      "Bytes in dirty pages awaiting decay", labels),
+      jemalloc_muzzy_("mooncake_jemalloc_muzzy_bytes",
+                      "Bytes in muzzy pages awaiting decay", labels),
+      jemalloc_arenas_("mooncake_jemalloc_arenas",
+                       "Number of arenas the allocator maintains", labels),
+      jemalloc_background_threads_("mooncake_jemalloc_background_threads",
+                                   "Background decay threads actually running",
+                                   labels),
+      jemalloc_opt_dirty_decay_ms_(
+          "mooncake_jemalloc_opt_dirty_decay_ms",
+          "Configured dirty page decay in ms; -1 never purges", labels),
+      jemalloc_opt_muzzy_decay_ms_(
+          "mooncake_jemalloc_opt_muzzy_decay_ms",
+          "Configured muzzy page decay in ms; -1 never purges", labels),
+      jemalloc_dirty_purged_pages_("mooncake_jemalloc_dirty_purged_pages_total",
+                                   "Dirty pages purged since process start",
+                                   labels),
+      jemalloc_muzzy_purged_pages_("mooncake_jemalloc_muzzy_purged_pages_total",
+                                   "Muzzy pages purged since process start",
+                                   labels),
+      jemalloc_dirty_purge_runs_("mooncake_jemalloc_dirty_purge_runs_total",
+                                 "Dirty decay purge runs since process start",
+                                 labels),
+      jemalloc_muzzy_purge_runs_("mooncake_jemalloc_muzzy_purge_runs_total",
+                                 "Muzzy decay purge runs since process start",
+                                 labels),
+      jemalloc_dirty_madvises_(
+          "mooncake_jemalloc_dirty_madvises_total",
+          "madvise calls issued by dirty decay since process start", labels),
+      jemalloc_muzzy_madvises_(
+          "mooncake_jemalloc_muzzy_madvises_total",
+          "madvise calls issued by muzzy decay since process start", labels),
+      jemalloc_small_allocations_(
+          "mooncake_jemalloc_small_allocations_total",
+          "Small allocation requests since process start", labels),
+      jemalloc_small_deallocations_(
+          "mooncake_jemalloc_small_deallocations_total",
+          "Small deallocation requests since process start", labels),
+      jemalloc_bin_regs_("mooncake_jemalloc_bin_regs",
+                         "Live regions in a small size class", labels,
+                         kBinSizeLabel),
+      jemalloc_bin_slabs_("mooncake_jemalloc_bin_slabs",
+                          "Slabs held by a small size class", labels,
+                          kBinSizeLabel),
+      jemalloc_bin_used_bytes_("mooncake_jemalloc_bin_used_bytes",
+                               "Bytes live in a small size class", labels,
+                               kBinSizeLabel),
+      jemalloc_bin_slab_bytes_(
+          "mooncake_jemalloc_bin_slab_bytes",
+          "Bytes the slabs of a small size class hold from the OS", labels,
+          kBinSizeLabel) {
+    MarkAllForZeroOutput();
+}
+
+void AllocatorMetric::MarkAllForZeroOutput() {
+    process_rss_.update(0);
+    process_rss_peak_.update(0);
+    process_rss_anon_.update(0);
+    process_rss_file_.update(0);
+    process_rss_shmem_.update(0);
+    process_vsize_.update(0);
+    process_swap_.update(0);
+
+    jemalloc_enabled_.update(0);
+    jemalloc_allocated_.update(0);
+    jemalloc_active_.update(0);
+    jemalloc_metadata_.update(0);
+    jemalloc_resident_.update(0);
+    jemalloc_retained_.update(0);
+    jemalloc_mapped_.update(0);
+    jemalloc_small_allocated_.update(0);
+    jemalloc_large_allocated_.update(0);
+    jemalloc_dirty_.update(0);
+    jemalloc_muzzy_.update(0);
+    jemalloc_arenas_.update(0);
+    jemalloc_background_threads_.update(0);
+    jemalloc_opt_dirty_decay_ms_.update(0);
+    jemalloc_opt_muzzy_decay_ms_.update(0);
+
+    jemalloc_dirty_purged_pages_.inc(0);
+    jemalloc_muzzy_purged_pages_.inc(0);
+    jemalloc_dirty_purge_runs_.inc(0);
+    jemalloc_muzzy_purge_runs_.inc(0);
+    jemalloc_dirty_madvises_.inc(0);
+    jemalloc_muzzy_madvises_.inc(0);
+    jemalloc_small_allocations_.inc(0);
+    jemalloc_small_deallocations_.inc(0);
+}
+
+void AllocatorMetric::Refresh() {
+    const auto now = std::chrono::steady_clock::now();
+    std::lock_guard<std::mutex> guard(refresh_mutex_);
+    if (now - last_refresh_ < kMinRefreshInterval) {
+        return;
+    }
+    last_refresh_ = now;
+    RefreshLocked();
+}
+
+void AllocatorMetric::RefreshLocked() {
+    RefreshProcess();
+    RefreshJemalloc();
+}
+
+void AllocatorMetric::RefreshProcess() {
+    std::ifstream status("/proc/self/status");
+    if (!status.is_open()) {
+        // Only reachable on a kernel without procfs, where every process gauge
+        // simply keeps its previous value.
+        return;
+    }
+
+    std::string line;
+    while (std::getline(status, line)) {
+        int64_t bytes = 0;
+        if (ParseStatusKib(line, "VmRSS:", bytes)) {
+            process_rss_.update(bytes);
+        } else if (ParseStatusKib(line, "VmHWM:", bytes)) {
+            process_rss_peak_.update(bytes);
+        } else if (ParseStatusKib(line, "RssAnon:", bytes)) {
+            process_rss_anon_.update(bytes);
+        } else if (ParseStatusKib(line, "RssFile:", bytes)) {
+            process_rss_file_.update(bytes);
+        } else if (ParseStatusKib(line, "RssShmem:", bytes)) {
+            process_rss_shmem_.update(bytes);
+        } else if (ParseStatusKib(line, "VmSize:", bytes)) {
+            process_vsize_.update(bytes);
+        } else if (ParseStatusKib(line, "VmSwap:", bytes)) {
+            process_swap_.update(bytes);
+        }
+    }
+}
+
+void AllocatorMetric::RefreshJemalloc() {
+    const JemallocStatsCollector collector =
+        g_jemalloc_collector.load(std::memory_order_acquire);
+    JemallocSnapshot snapshot;
+    if (collector == nullptr || !collector(snapshot)) {
+        jemalloc_enabled_.update(0);
+        return;
+    }
+
+    jemalloc_enabled_.update(1);
+    jemalloc_allocated_.update(static_cast<int64_t>(snapshot.allocated));
+    jemalloc_active_.update(static_cast<int64_t>(snapshot.active));
+    jemalloc_metadata_.update(static_cast<int64_t>(snapshot.metadata));
+    jemalloc_resident_.update(static_cast<int64_t>(snapshot.resident));
+    jemalloc_retained_.update(static_cast<int64_t>(snapshot.retained));
+    jemalloc_mapped_.update(static_cast<int64_t>(snapshot.mapped));
+    jemalloc_small_allocated_.update(
+        static_cast<int64_t>(snapshot.small_allocated));
+    jemalloc_large_allocated_.update(
+        static_cast<int64_t>(snapshot.large_allocated));
+    jemalloc_dirty_.update(static_cast<int64_t>(snapshot.dirty_bytes));
+    jemalloc_muzzy_.update(static_cast<int64_t>(snapshot.muzzy_bytes));
+    jemalloc_arenas_.update(static_cast<int64_t>(snapshot.arenas));
+    jemalloc_background_threads_.update(
+        static_cast<int64_t>(snapshot.background_threads));
+    jemalloc_opt_dirty_decay_ms_.update(snapshot.opt_dirty_decay_ms);
+    jemalloc_opt_muzzy_decay_ms_.update(snapshot.opt_muzzy_decay_ms);
+
+    AdvanceCounter(jemalloc_dirty_purged_pages_, snapshot.dirty_purged_pages,
+                   prev_dirty_purged_pages_);
+    AdvanceCounter(jemalloc_muzzy_purged_pages_, snapshot.muzzy_purged_pages,
+                   prev_muzzy_purged_pages_);
+    AdvanceCounter(jemalloc_dirty_purge_runs_, snapshot.dirty_purge_runs,
+                   prev_dirty_purge_runs_);
+    AdvanceCounter(jemalloc_muzzy_purge_runs_, snapshot.muzzy_purge_runs,
+                   prev_muzzy_purge_runs_);
+    AdvanceCounter(jemalloc_dirty_madvises_, snapshot.dirty_madvises,
+                   prev_dirty_madvises_);
+    AdvanceCounter(jemalloc_muzzy_madvises_, snapshot.muzzy_madvises,
+                   prev_muzzy_madvises_);
+    AdvanceCounter(jemalloc_small_allocations_, snapshot.small_allocations,
+                   prev_small_allocations_);
+    AdvanceCounter(jemalloc_small_deallocations_, snapshot.small_deallocations,
+                   prev_small_deallocations_);
+
+    for (const auto& bin : snapshot.bins) {
+        const std::array<std::string, 1> label = {std::to_string(bin.size)};
+        jemalloc_bin_regs_.update(label, static_cast<int64_t>(bin.regs));
+        jemalloc_bin_slabs_.update(label, static_cast<int64_t>(bin.slabs));
+        jemalloc_bin_used_bytes_.update(
+            label, static_cast<int64_t>(bin.regs * bin.size));
+        jemalloc_bin_slab_bytes_.update(
+            label,
+            static_cast<int64_t>(bin.slabs * bin.regs_per_slab * bin.size));
+    }
+}
+
+void AllocatorMetric::AdvanceCounter(ylt::metric::counter_t& counter,
+                                     uint64_t total, uint64_t& previous) {
+    if (total < previous) {
+        // jemalloc totals only grow within one process, so a regression means
+        // the sample is untrustworthy; holding the series keeps it monotonic.
+        return;
+    }
+    counter.inc(static_cast<int64_t>(total - previous));
+    previous = total;
+}
+
+void AllocatorMetric::serialize(std::string& str) {
+    process_rss_.serialize(str);
+    process_rss_peak_.serialize(str);
+    process_rss_anon_.serialize(str);
+    process_rss_file_.serialize(str);
+    process_rss_shmem_.serialize(str);
+    process_vsize_.serialize(str);
+    process_swap_.serialize(str);
+
+    jemalloc_enabled_.serialize(str);
+    jemalloc_allocated_.serialize(str);
+    jemalloc_active_.serialize(str);
+    jemalloc_metadata_.serialize(str);
+    jemalloc_resident_.serialize(str);
+    jemalloc_retained_.serialize(str);
+    jemalloc_mapped_.serialize(str);
+    jemalloc_small_allocated_.serialize(str);
+    jemalloc_large_allocated_.serialize(str);
+    jemalloc_dirty_.serialize(str);
+    jemalloc_muzzy_.serialize(str);
+    jemalloc_arenas_.serialize(str);
+    jemalloc_background_threads_.serialize(str);
+    jemalloc_opt_dirty_decay_ms_.serialize(str);
+    jemalloc_opt_muzzy_decay_ms_.serialize(str);
+
+    jemalloc_dirty_purged_pages_.serialize(str);
+    jemalloc_muzzy_purged_pages_.serialize(str);
+    jemalloc_dirty_purge_runs_.serialize(str);
+    jemalloc_muzzy_purge_runs_.serialize(str);
+    jemalloc_dirty_madvises_.serialize(str);
+    jemalloc_muzzy_madvises_.serialize(str);
+    jemalloc_small_allocations_.serialize(str);
+    jemalloc_small_deallocations_.serialize(str);
+
+    jemalloc_bin_regs_.serialize(str);
+    jemalloc_bin_slabs_.serialize(str);
+    jemalloc_bin_used_bytes_.serialize(str);
+    jemalloc_bin_slab_bytes_.serialize(str);
+}
+
+std::string AllocatorMetric::summary_metrics() {
+    std::stringstream ss;
+    ss << "=== Allocator Metrics Summary ===\n";
+    ss << "Process RSS: " << process_rss_.value()
+       << " B, peak: " << process_rss_peak_.value() << " B\n";
+    if (jemalloc_enabled_.value() == 0) {
+        ss << "jemalloc: not linked\n";
+        return ss.str();
+    }
+    ss << "jemalloc allocated: " << jemalloc_allocated_.value()
+       << " B, resident: " << jemalloc_resident_.value()
+       << " B, retained: " << jemalloc_retained_.value() << " B\n";
+    ss << "jemalloc dirty: " << jemalloc_dirty_.value()
+       << " B, muzzy: " << jemalloc_muzzy_.value() << " B\n";
+    return ss.str();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/cachelib_memory_allocator/CMakeLists.txt b/mooncake-store/src/cachelib_memory_allocator/CMakeLists.txt
index 4dcf2eaa6d..c9b2aae4d8 100644
--- a/mooncake-store/src/cachelib_memory_allocator/CMakeLists.txt
+++ b/mooncake-store/src/cachelib_memory_allocator/CMakeLists.txt
@@ -2,18 +2,12 @@ project(cachelib_memory_allocator)
 
 set(CMAKE_CXX_STANDARD 17)
 
-include_directories("include")
-include_directories("fake_include")
-
-include_directories("cachelib_memory_allocator/include")
-include_directories("cachelib_memory_allocator/fake_include")
-
-add_library (cachelib_memory_allocator
-        STATIC
-        AllocationClass.cpp
-        MemoryAllocator.cpp
-        MemoryPool.cpp
-        MemoryPoolManager.cpp
-        Slab.cpp
-        SlabAllocator.cpp
-)
+add_library(
+  cachelib_memory_allocator STATIC
+  AllocationClass.cpp MemoryAllocator.cpp MemoryPool.cpp MemoryPoolManager.cpp
+  Slab.cpp SlabAllocator.cpp)
+target_include_directories(
+  cachelib_memory_allocator
+  PUBLIC ${MOONCAKE_STORE_INCLUDE_ROOT}/cachelib_memory_allocator
+         ${MOONCAKE_STORE_INCLUDE_ROOT}/cachelib_memory_allocator/include
+         ${MOONCAKE_STORE_INCLUDE_ROOT}/cachelib_memory_allocator/fake_include)
diff --git a/mooncake-store/src/client_buffer.cpp b/mooncake-store/src/client_buffer.cpp
index 7ac1dc9212..dd84ab1533 100644
--- a/mooncake-store/src/client_buffer.cpp
+++ b/mooncake-store/src/client_buffer.cpp
@@ -8,7 +8,7 @@
 #include <fcntl.h>     // For O_CREAT, O_RDWR
 #include <unistd.h>    // For ftruncate, close, shm_unlink
 
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 
 #if defined(USE_SUNRISE)
 #include "sunrise_allocator.h"
@@ -149,6 +149,8 @@ uint64_t calculate_total_size(const Replica::Descriptor& replica) {
         total_length = disk_descriptor.object_size;
     } else if (replica.is_local_disk_replica()) {
         total_length = replica.get_local_disk_descriptor().object_size;
+    } else if (replica.is_dfs_replica()) {
+        total_length = replica.get_dfs_descriptor().object_size;
     } else if (replica.is_nof_replica()) {
         total_length = replica.get_nof_descriptor().buffer_descriptor.size_;
     } else {
@@ -172,6 +174,9 @@ int allocateSlices(std::vector<Slice>& slices,
     } else if (replica.is_local_disk_replica()) {
         slices.emplace_back(
             Slice{buffer_ptr, replica.get_local_disk_descriptor().object_size});
+    } else if (replica.is_dfs_replica()) {
+        slices.emplace_back(
+            Slice{buffer_ptr, replica.get_dfs_descriptor().object_size});
     } else if (replica.is_nof_replica()) {
         auto& handle = replica.get_nof_descriptor().buffer_descriptor;
         void* chunk_ptr = buffer_ptr;
diff --git a/mooncake-store/src/client_metric.cpp b/mooncake-store/src/client_metric.cpp
index 4fbaef026f..78f33255b7 100644
--- a/mooncake-store/src/client_metric.cpp
+++ b/mooncake-store/src/client_metric.cpp
@@ -2,63 +2,22 @@
 
 #include <glog/logging.h>
 #include <chrono>
-#include <cstdlib>
 #include <thread>
 
-#include "bool_parser.h"
-#include "integer_parser.h"
+#include "common/byte_size.h"
+#include "version.h"
 
 namespace mooncake {
 
 namespace {
 
-bool parseMetricsEnabled() {
-    const char* metric_env = std::getenv("MC_STORE_CLIENT_METRIC");
-    if (!metric_env) {
-        return true;
-    }
-    return TryParseBool(metric_env).value_or(false);
-}
-
-bool parseBoolEnv(const char* env_name, bool default_value) {
-    const char* env_value = std::getenv(env_name);
-    if (!env_value) {
-        return default_value;
-    }
-
-    const auto parsed = TryParseBool(env_value);
-    if (parsed.has_value()) {
-        return *parsed;
-    }
-
-    LOG(WARNING) << "Failed to parse " << env_name << ": " << env_value
-                 << ", fallback to default=" << default_value;
-    return default_value;
-}
-
-uint64_t parseMetricsInterval() {
-    const char* interval_env = std::getenv("MC_STORE_CLIENT_METRIC_INTERVAL");
-    if (!interval_env) {
-        // Default to disabled
-        return 0;
-    }
-
-    const auto interval = TryParseInteger<uint64_t>(
-        interval_env,
-        {.trim_ascii_whitespace = true, .allow_leading_plus = true});
-    if (!interval.has_value()) {
-        LOG(WARNING) << "Failed to parse MC_STORE_CLIENT_METRIC_INTERVAL: "
-                     << interval_env << ", disabling metrics reporting";
-        return 0;
-    }
-    if (*interval == 0) {
-        LOG(INFO) << "Client metrics reporting disabled (interval=0) via "
-                     "MC_STORE_CLIENT_METRIC_INTERVAL";
-    } else {
-        LOG(INFO) << "Client metrics interval set to " << *interval
-                  << "s via MC_STORE_CLIENT_METRIC_INTERVAL";
-    }
-    return *interval;
+// Build info is exposed as an info-style metric, so the version strings live in
+// labels. Caller supplied labels are preserved to keep instance identification.
+std::map<std::string, std::string> WithBuildInfoLabels(
+    std::map<std::string, std::string> labels) {
+    labels["version"] = GetMooncakeStoreVersion();
+    labels["display_version"] = MOONCAKE_DISPLAY_VERSION;
+    return labels;
 }
 
 }  // anonymous namespace
@@ -71,10 +30,19 @@ ClientMetric::ClientMetric(uint64_t interval_seconds,
       master_client_metric(labels),
       transfer_operation_metric(labels),
       ssd_metric(labels),
+      dfs_metric(labels),
+      allocator_metric(labels),
+      build_info("mooncake_build_info",
+                 "Build version of the running client; the value is always 1 "
+                 "and the version strings are carried by the labels",
+                 WithBuildInfoLabels(labels)),
+      master_heartbeat_metric(labels),
       should_stop_metrics_thread_(false),
       metrics_interval_seconds_(interval_seconds),
       bandwidth_reporting_enabled_(bandwidth_reporting_enabled),
       master_rpc_metrics_enabled_(master_rpc_metrics_enabled) {
+    // Set once: the compiled-in version never changes at runtime.
+    build_info.update(1);
     last_report_snapshot_ = TransferSnapshot{
         static_cast<uint64_t>(transfer_metric.total_read_bytes.value()),
         static_cast<uint64_t>(transfer_metric.total_write_bytes.value()),
@@ -89,24 +57,23 @@ ClientMetric::~ClientMetric() { StopMetricsReportingThread(); }
 std::unique_ptr<ClientMetric> ClientMetric::Create(
     const std::map<std::string, std::string>& labels,
     bool master_rpc_metrics_enabled) {
-    if (!parseMetricsEnabled()) {
+    const auto config = ClientMetricConfig::FromEnvironment();
+    if (!config.enabled) {
         LOG(INFO) << "Client metrics disabled (set MC_STORE_CLIENT_METRIC=0 to "
                      "disable)";
         return nullptr;
     }
 
-    uint64_t interval = parseMetricsInterval();
-    bool bandwidth_reporting_enabled =
-        parseBoolEnv("MC_STORE_CLIENT_METRIC_BANDWIDTH", true);
-
     LOG(INFO) << "Client metrics enabled (default enabled)";
     LOG(INFO) << "Client bandwidth summary "
-              << (bandwidth_reporting_enabled ? "enabled" : "disabled")
+              << (config.bandwidth_reporting_enabled ? "enabled" : "disabled")
               << " via MC_STORE_CLIENT_METRIC_BANDWIDTH";
 
-    return std::make_unique<ClientMetric>(interval, labels,
-                                          bandwidth_reporting_enabled,
-                                          master_rpc_metrics_enabled);
+    return std::make_unique<ClientMetric>(
+        std::chrono::duration_cast<std::chrono::seconds>(
+            config.reporting_interval)
+            .count(),
+        labels, config.bandwidth_reporting_enabled, master_rpc_metrics_enabled);
 }
 
 void ClientMetric::serialize(std::string& str) {
@@ -116,11 +83,20 @@ void ClientMetric::serialize(std::string& str) {
     }
     transfer_operation_metric.serialize(str);
     ssd_metric.serialize(str);
+    dfs_metric.serialize(str);
+    allocator_metric.Refresh();
+    allocator_metric.serialize(str);
+    build_info.serialize(str);
+    master_heartbeat_metric.serialize(str);
 }
 
 std::string ClientMetric::summary_metrics() {
     std::stringstream ss;
     ss << "Client Metrics Summary\n";
+    // Identify the build inline so one /metrics/summary request is enough to
+    // tell which binary produced the numbers below.
+    ss << "Version: " << GetMooncakeStoreVersion() << " ("
+       << MOONCAKE_DISPLAY_VERSION << ")\n";
     ss << transfer_metric.summary_metrics(bandwidth_reporting_enabled_);
     ss << "\n";
     if (master_rpc_metrics_enabled_) {
@@ -130,6 +106,11 @@ std::string ClientMetric::summary_metrics() {
     ss << transfer_operation_metric.summary_metrics();
     ss << "\n";
     ss << ssd_metric.summary_metrics();
+    ss << "\n";
+    ss << dfs_metric.summary_metrics();
+    ss << "\n";
+    allocator_metric.Refresh();
+    ss << allocator_metric.summary_metrics();
     return ss.str();
 }
 
diff --git a/mooncake-store/src/client_offboarding.cpp b/mooncake-store/src/client_offboarding.cpp
new file mode 100644
index 0000000000..95533f87d0
--- /dev/null
+++ b/mooncake-store/src/client_offboarding.cpp
@@ -0,0 +1,166 @@
+#include "client_offboarding.h"
+
+#include <algorithm>
+#include <iterator>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "master_metric_manager.h"
+#include "master_service.h"
+
+namespace mooncake {
+
+ClientOffboardingWorker::~ClientOffboardingWorker() { Stop(); }
+
+void ClientOffboardingWorker::Start() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (running_) {
+        return;
+    }
+    running_ = true;
+    try {
+        thread_ = std::thread(&ClientOffboardingWorker::ThreadFunc, this);
+    } catch (...) {
+        running_ = false;
+        throw;
+    }
+}
+
+void ClientOffboardingWorker::Stop() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!running_ && !thread_.joinable()) {
+            return;
+        }
+        running_ = false;
+    }
+    cv_.notify_all();
+    if (thread_.joinable()) {
+        thread_.join();
+    }
+}
+
+void ClientOffboardingWorker::ReserveJob() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        CHECK(running_);
+        pending_jobs_.fetch_add(1, std::memory_order_release);
+        MasterMetricManager::instance().inc_client_offboarding_queue_depth();
+    }
+}
+
+void ClientOffboardingWorker::ScheduleReserved(ClientOffboardingJob job) {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        CHECK(running_);
+        jobs_.push_back(std::move(job));
+    }
+    cv_.notify_one();
+}
+
+std::chrono::seconds ClientOffboardingWorker::RetryDelay(uint64_t retry_count) {
+    constexpr uint64_t kBackoffs[] = {1, 2, 4, 8, 16, 30};
+    const size_t index = static_cast<size_t>(
+        std::min<uint64_t>(retry_count - 1, std::size(kBackoffs) - 1));
+    return std::chrono::seconds(kBackoffs[index]);
+}
+
+void ClientOffboardingWorker::CompleteJob(const ClientOffboardingJob& job) {
+    pending_jobs_.fetch_sub(1, std::memory_order_acq_rel);
+    MasterMetricManager::instance().dec_client_offboarding_queue_depth();
+    const auto duration_ms =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::steady_clock::now() - job.enqueued_at)
+            .count();
+    MasterMetricManager::instance().observe_client_offboarding_duration_ms(
+        duration_ms);
+    LOG(INFO) << "client_id=" << job.client_id
+              << ", action=client_offboarding_complete"
+              << ", retries=" << job.retry_count
+              << ", duration_ms=" << duration_ms;
+}
+
+void ClientOffboardingWorker::DropJob(const ClientOffboardingJob& job,
+                                      const char* reason) {
+    pending_jobs_.fetch_sub(1, std::memory_order_acq_rel);
+    MasterMetricManager::instance().dec_client_offboarding_queue_depth();
+    LOG(ERROR) << "client_id=" << job.client_id
+               << ", action=client_offboarding_dropped"
+               << ", reason=" << reason << ", retry_count=" << job.retry_count;
+}
+
+void ClientOffboardingWorker::ThreadFunc() {
+    LOG(INFO) << "Client offboarding worker started";
+    while (true) {
+        ClientOffboardingJob job;
+        {
+            std::unique_lock<std::mutex> lock(mutex_);
+            while (running_ && jobs_.empty()) {
+                cv_.wait(lock);
+            }
+            if (!running_) {
+                auto dropped = std::move(jobs_);
+                jobs_.clear();
+                lock.unlock();
+                for (const auto& queued : dropped) {
+                    DropJob(queued, "master_stopping");
+                }
+                break;
+            }
+
+            const auto next = std::min_element(
+                jobs_.begin(), jobs_.end(),
+                [](const auto& lhs, const auto& rhs) {
+                    return lhs.next_attempt_at < rhs.next_attempt_at;
+                });
+            const auto now = std::chrono::steady_clock::now();
+            if (next->next_attempt_at > now) {
+                cv_.wait_until(lock, next->next_attempt_at);
+                continue;
+            }
+            job = std::move(*next);
+            jobs_.erase(next);
+        }
+
+        if (service_->ProcessClientOffboardingJob(job)) {
+            CompleteJob(job);
+            continue;
+        }
+
+        ++job.retry_count;
+        MasterMetricManager::instance().inc_client_offboarding_retry();
+        const bool alert = ShouldAlert(job.retry_count);
+        if (alert) {
+            MasterMetricManager::instance().inc_client_offboarding_alert();
+        }
+        LOG(ERROR) << "client_id=" << job.client_id
+                   << ", action=client_offboarding_retry"
+                   << ", retry_count=" << job.retry_count
+                   << ", alert=" << (alert ? "true" : "false")
+                   << ", pending_prepare_segments="
+                   << job.pending_prepare_segments.size()
+                   << ", prepared_segments=" << job.prepared_segments.size()
+                   << ", metadata_cleanup_accepted="
+                   << (job.metadata_cleanup_accepted ? "true" : "false");
+
+        bool requeued = false;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (running_) {
+                job.next_attempt_at = std::chrono::steady_clock::now() +
+                                      RetryDelay(job.retry_count);
+                jobs_.push_back(std::move(job));
+                requeued = true;
+            }
+        }
+        if (requeued) {
+            cv_.notify_one();
+        } else {
+            DropJob(job, "master_stopping_after_attempt");
+        }
+    }
+    LOG(INFO) << "Client offboarding worker stopped";
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/client_service.cpp b/mooncake-store/src/client_service.cpp
index 137d4b434c..7e70705361 100644
--- a/mooncake-store/src/client_service.cpp
+++ b/mooncake-store/src/client_service.cpp
@@ -38,21 +38,37 @@
 #include "ha/leadership/leader_coordinator_factory.h"
 #include "types.h"
 #include "client_buffer.h"
-#include "utils.h"
+#include "common/network.h"
+#include "config/client_host_identity_config.h"
 #include "rpc_types.h"
 #include "local_hot_cache.h"
+#include "config/client_auto_discovery_config.h"
 #include "device/accelerator_registry.h"
 #ifdef USE_INTRA_NVLINK
 #include "gpu_vendor/intra_nvlink.h"
 #endif
 #include "crc_checksum.h"
 #include "environ.h"
+#include "config/client_numa_config.h"
+#include "storage/distributed/distributed_storage_backend.h"
 
 namespace mooncake {
 
+std::optional<size_t> GetTransportRegistrationLimit(
+    const std::string& protocol) {
+    if (protocol == "efa" || protocol == "cxi") {
+        return globalConfig().max_mr_size;
+    }
+    if (protocol == "ub") {
+        return globalConfig().max_seg_size;
+    }
+    return std::nullopt;
+}
+
 namespace {
 
 constexpr size_t kObjectChecksumD2HChunkSize = 8 * 1024 * 1024;
+constexpr auto kInitialLeaderReadyTimeout = std::chrono::seconds(30);
 
 class ScopedObjectChecksumBuffer {
    public:
@@ -69,26 +85,6 @@ class ScopedObjectChecksumBuffer {
 };
 
 #ifdef USE_NOF
-std::optional<int> GetConfiguredNumaSocketId() {
-    const char* raw_value = std::getenv("MC_STORE_NUMA_SOCKET_ID");
-    if (!raw_value || raw_value[0] == '\0') {
-        return std::nullopt;
-    }
-
-    char* end_ptr = nullptr;
-    errno = 0;
-    long parsed = std::strtol(raw_value, &end_ptr, 10);
-    if (errno != 0 || end_ptr == raw_value ||
-        (end_ptr != nullptr && *end_ptr != '\0') || parsed < 0 ||
-        parsed > std::numeric_limits<int>::max()) {
-        LOG(WARNING) << "Invalid MC_STORE_NUMA_SOCKET_ID=" << raw_value
-                     << ", falling back to auto-detect";
-        return std::nullopt;
-    }
-
-    return static_cast<int>(parsed);
-}
-
 int GetCurrentNumaSocketId() {
     if (numa_available() < 0) {
         return 0;
@@ -149,13 +145,81 @@ std::optional<ContiguousSliceRange> GetContiguousSliceRange(
                                 .size = total_size};
 }
 
+ErrorCode ScatterFragmentError(const Status& status) {
+    return status.IsInvalidArgument() ? ErrorCode::INVALID_PARAMS
+                                      : ErrorCode::TRANSFER_FAIL;
+}
+
+// Collects the fragments of many ranged entries into a single scatter submit.
+//
+// One submit per entry would hand the transport one tiny transfer per key per
+// layer; batching them lets the transport coalesce every fragment bound for the
+// same segment into one transfer, which is what keeps layer-wise sessions at
+// full bandwidth.
+//
+// ScatterTransferRange holds non-owning spans, so the offset/length storage
+// lives here and must outlive the submit. Both vectors are reserved to the
+// exact fragment count up front so pushes never reallocate under a live span.
+class ScatterRangeBuilder {
+   public:
+    explicit ScatterRangeBuilder(size_t fragment_count)
+        : zero_offsets_(fragment_count, 0) {
+        remote_offsets_.reserve(fragment_count);
+        lengths_.reserve(fragment_count);
+        ranges_.reserve(fragment_count);
+    }
+
+    // `error_slot` is shared by every fragment of one entry and keeps the first
+    // failure. Callbacks run on the waiting thread, so no locking is needed.
+    void Add(TransferRequest::OpCode opcode,
+             const AllocatedBuffer::Descriptor& handle, const Slice& slice,
+             uint64_t remote_offset, std::optional<ErrorCode>* error_slot) {
+        const size_t index = remote_offsets_.size();
+        remote_offsets_.push_back(static_cast<size_t>(remote_offset));
+        lengths_.push_back(slice.size);
+        ranges_.push_back(TransferEngine::ScatterTransferRange{
+            .opcode = opcode,
+            .remote_segment = handle.transport_endpoint_,
+            .remote_base_offset = handle.buffer_address_,
+            .remote_size = static_cast<size_t>(handle.size_),
+            .local_buffer = slice.ptr,
+            .local_capacity = slice.size,
+            .local_offsets = std::span<const size_t>(&zero_offsets_[index], 1),
+            .remote_offsets =
+                std::span<const size_t>(&remote_offsets_[index], 1),
+            .lengths = std::span<const size_t>(&lengths_[index], 1),
+            .on_fragment_complete =
+                [error_slot](size_t, const Status& status) {
+                    if (!status.ok() && !error_slot->has_value()) {
+                        *error_slot = ScatterFragmentError(status);
+                    }
+                },
+        });
+    }
+
+    bool empty() const { return ranges_.empty(); }
+
+    const std::vector<TransferEngine::ScatterTransferRange>& ranges() const {
+        return ranges_;
+    }
+
+   private:
+    std::vector<size_t> zero_offsets_;
+    std::vector<size_t> remote_offsets_;
+    std::vector<size_t> lengths_;
+    std::vector<TransferEngine::ScatterTransferRange> ranges_;
+};
+
 struct ReplicaTransferSummary {
     size_t allocated_memory_replicas = 0;
     size_t allocated_nof_replicas = 0;
+    size_t allocated_dfs_replicas = 0;
     size_t successful_memory_transfers = 0;
     size_t successful_nof_transfers = 0;
+    size_t successful_dfs_transfers = 0;
     size_t failed_memory_transfers = 0;
     size_t failed_nof_transfers = 0;
+    size_t failed_dfs_transfers = 0;
     ErrorCode first_error = ErrorCode::OK;
 
     void RecordAllocatedReplica(const Replica::Descriptor& replica) {
@@ -163,6 +227,8 @@ struct ReplicaTransferSummary {
             ++allocated_memory_replicas;
         } else if (replica.is_nof_replica()) {
             ++allocated_nof_replicas;
+        } else if (replica.is_dfs_replica()) {
+            ++allocated_dfs_replicas;
         }
     }
 
@@ -171,6 +237,8 @@ struct ReplicaTransferSummary {
             ++successful_memory_transfers;
         } else if (replica_type == ReplicaType::NOF_SSD) {
             ++successful_nof_transfers;
+        } else if (replica_type == ReplicaType::DFS) {
+            ++successful_dfs_transfers;
         }
     }
 
@@ -179,6 +247,8 @@ struct ReplicaTransferSummary {
             ++failed_memory_transfers;
         } else if (replica_type == ReplicaType::NOF_SSD) {
             ++failed_nof_transfers;
+        } else if (replica_type == ReplicaType::DFS) {
+            ++failed_dfs_transfers;
         }
         if (first_error == ErrorCode::OK) {
             first_error = error;
@@ -186,9 +256,23 @@ struct ReplicaTransferSummary {
     }
 };
 
+bool NonDfsTransfersSucceeded(const ReplicaTransferSummary& summary) {
+    return summary.successful_memory_transfers ==
+               summary.allocated_memory_replicas &&
+           summary.successful_nof_transfers == summary.allocated_nof_replicas &&
+           summary.failed_memory_transfers == 0 &&
+           summary.failed_nof_transfers == 0;
+}
+
+bool AllAllocatedTransfersSucceeded(const ReplicaTransferSummary& summary) {
+    return NonDfsTransfersSucceeded(summary) &&
+           summary.successful_dfs_transfers == summary.allocated_dfs_replicas &&
+           summary.failed_dfs_transfers == 0;
+}
+
 bool HasExpectedReplicaAllocation(const ReplicateConfig& config,
                                   const ReplicaTransferSummary& summary) {
-    if (config.nof_replica_num == 0) {
+    if (config.nof_replica_num == 0 && config.dfs_replica_num == 0) {
         return summary.allocated_memory_replicas > 0;
     }
     if (DetermineReplicaWriteMode(config) ==
@@ -198,7 +282,24 @@ bool HasExpectedReplicaAllocation(const ReplicateConfig& config,
                0;
     }
     return summary.allocated_memory_replicas == config.replica_num &&
-           summary.allocated_nof_replicas == config.nof_replica_num;
+           summary.allocated_nof_replicas == config.nof_replica_num &&
+           summary.allocated_dfs_replicas == config.dfs_replica_num;
+}
+
+std::optional<ErrorCode> ValidatePreferSameNodeWriteConfig(
+    const ReplicateConfig& config) {
+    if (config.nof_replica_num > 0) {
+        LOG(ERROR) << "prefer_alloc_in_same_node is not supported with "
+                      "NoF replicas";
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (config.replica_num != 1) {
+        LOG(ERROR) << "prefer_alloc_in_same_node is not supported with "
+                      "replica_num != 1";
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    return std::nullopt;
 }
 
 // success describes whether the overall put should succeed. Reliable modes
@@ -220,12 +321,7 @@ FinalizeDecision DetermineFinalizeDecision(
 
     if (write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
         const bool all_transfers_succeeded =
-            summary.successful_memory_transfers ==
-                summary.allocated_memory_replicas &&
-            summary.successful_nof_transfers ==
-                summary.allocated_nof_replicas &&
-            summary.failed_memory_transfers == 0 &&
-            summary.failed_nof_transfers == 0;
+            AllAllocatedTransfersSucceeded(summary);
         if (allocation_satisfied && all_transfers_succeeded) {
             return {.end_type = ReplicaType::ALL,
                     .revoke_type = std::nullopt,
@@ -301,7 +397,8 @@ Client::Client(const std::string& local_hostname,
                      metrics_ ? &metrics_->master_client_metric : nullptr,
                      tenant_id),
       local_hostname_(local_hostname),
-      host_id_(ResolveMooncakeHostId(local_hostname)),
+      host_id_(
+          ClientHostIdentityConfig::FromEnvironment(local_hostname).host_id),
       metadata_connstring_(metadata_connstring),
       protocol_(protocol),
       object_checksum_enabled_(Environ::Get().GetStoreChecksumEnabled()),
@@ -427,46 +524,6 @@ ReplicateConfig Client::AttachHostId(const ReplicateConfig& config) const {
     return client_cfg;
 }
 
-static std::optional<bool> get_auto_discover() {
-    const char* ev_ad = std::getenv("MC_MS_AUTO_DISC");
-    if (ev_ad) {
-        try {
-            int iv = std::stoi(ev_ad);
-            if (iv == 1) {
-                LOG(INFO) << "auto discovery set by env MC_MS_AUTO_DISC";
-                return true;
-            } else if (iv == 0) {
-                LOG(INFO) << "auto discovery not set by env MC_MS_AUTO_DISC";
-                return false;
-            }
-        } catch (const std::exception&) {
-            // A non-numeric or out-of-range value makes std::stoi throw; fall
-            // through to the warning below and use the default instead of
-            // letting the exception abort client initialization.
-        }
-        LOG(WARNING)
-            << "invalid MC_MS_AUTO_DISC value: " << ev_ad
-            << ", should be 0 or 1, using default: auto discovery not set";
-    }
-    return std::nullopt;
-}
-
-static std::vector<std::string> get_auto_discover_filters() {
-    const char* raw_filters = std::getenv("MC_MS_FILTERS");
-    if (raw_filters == nullptr) {
-        return {};
-    }
-
-    LOG(INFO) << "whitelist filters: " << raw_filters;
-    std::vector<std::string> filters;
-    boost::split(filters, std::string(raw_filters), boost::is_any_of(","),
-                 boost::token_compress_off);
-    for (auto& filter : filters) {
-        filter = std::string(TrimAsciiWhitespace(filter));
-    }
-    return filters;
-}
-
 static std::vector<std::string> ParseDeviceNames(std::string_view value) {
     std::vector<std::string> devices;
     boost::split(devices, std::string(value), boost::is_any_of(","),
@@ -502,8 +559,8 @@ tl::expected<std::optional<ha::HABackendSpec>, ErrorCode> ParseHABackendSpec(
     }};
 }
 
-tl::expected<void, ErrorCode> CheckRegisterMemoryParams(const void* addr,
-                                                        size_t length) {
+tl::expected<void, ErrorCode> CheckRegisterMemoryParams(
+    const void* addr, size_t length, const std::string& protocol) {
     if (addr == nullptr) {
         LOG(ERROR) << "addr is nullptr";
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
@@ -512,11 +569,10 @@ tl::expected<void, ErrorCode> CheckRegisterMemoryParams(const void* addr,
         LOG(ERROR) << "length is 0";
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
-    // Tcp is not limited by max_mr_size, but we ignore it for now.
-    auto max_mr_size = globalConfig().max_mr_size;  // Max segment size
-    if (length > max_mr_size) {
-        LOG(ERROR) << "length " << length
-                   << " is larger than max_mr_size: " << max_mr_size;
+    if (auto limit = GetTransportRegistrationLimit(protocol);
+        limit.has_value() && length > *limit) {
+        LOG(ERROR) << "length " << length << " exceeds registration limit "
+                   << *limit << " for protocol " << protocol;
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
     return {};
@@ -538,19 +594,22 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
             return coordinator.error();
         }
 
-        auto current_view = coordinator.value()->ReadCurrentView();
-        if (!current_view) {
-            LOG(ERROR) << "Failed to read current master view: "
-                       << toString(current_view.error());
-            return current_view.error();
+        auto master_view = ha::ReadCurrentViewOrWaitForReady(
+            *coordinator.value(), kInitialLeaderReadyTimeout);
+        if (!master_view) {
+            LOG(ERROR) << "Failed to discover a ready master view: "
+                       << toString(master_view.error());
+            return master_view.error();
         }
-        if (!current_view.value().has_value()) {
-            LOG(ERROR) << "No master is available in HA backend";
+        if (!master_view->has_value()) {
+            // An absent ready view can mean either no elected leader or an
+            // elected leader whose endpoint is still hidden during recovery.
+            LOG(ERROR) << "No master became ready within "
+                       << kInitialLeaderReadyTimeout.count() << " seconds";
             return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
         }
 
-        const auto& master_view = current_view.value().value();
-        auto err = SwitchLeader(master_view);
+        auto err = SwitchLeader(master_view->value());
         if (err != ErrorCode::OK) {
             LOG(ERROR) << "Failed to connect to master";
             return err;
@@ -558,14 +617,13 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
 
         leader_coordinator_ = std::move(coordinator.value());
         direct_master_address_.clear();
-
-        leader_monitor_running_ = true;
-        leader_monitor_thread_ =
-            std::thread([this]() { this->LeaderMonitorThreadMain(); });
-
+        if (!leader_monitor_running_.exchange(true)) {
+            leader_monitor_thread_ =
+                std::thread([this]() { this->LeaderMonitorThreadMain(); });
+        }
         return ErrorCode::OK;
     } else {
-        auto err = master_client_.Connect(master_server_entry);
+        auto err = ConnectMasterEndpoint(master_server_entry);
         if (err != ErrorCode::OK) {
             return err;
         }
@@ -579,6 +637,24 @@ ErrorCode Client::ConnectToMaster(const std::string& master_server_entry) {
     }
 }
 
+void Client::EnterHaRuntimeMode() {
+    if (!leader_coordinator_) {
+        return;
+    }
+
+    // Foreground RPCs keep their normal retry policy. Only the HA heartbeat
+    // and leader-readiness probes use the separately configured fast-fail
+    // control pool once initialization has completed.
+    master_client_.EnableHaConnectionPolicy();
+}
+
+ErrorCode Client::ConnectMasterEndpoint(const std::string& address) {
+    if (!metrics_) return master_client_.Connect(address);
+
+    return metrics_->master_heartbeat_metric.ObserveConnect(
+        [this, &address] { return master_client_.Connect(address); });
+}
+
 ErrorCode Client::SwitchLeader(const ha::MasterView& target_view) {
     std::lock_guard<std::mutex> lock(leader_switch_mutex_);
 
@@ -595,7 +671,7 @@ ErrorCode Client::SwitchLeader(const ha::MasterView& target_view) {
         }
     }
 
-    auto err = master_client_.Connect(target_view.leader_address);
+    auto err = ConnectMasterEndpoint(target_view.leader_address);
     if (err != ErrorCode::OK) {
         last_ping_success_.store(false);
         return err;
@@ -636,6 +712,25 @@ void Client::LeaderMonitorThreadMain() {
         }
 
         if (!view_change->changed || !view_change->current_view.has_value()) {
+            // A warming leader owns master_view without exposing a routable
+            // endpoint. Acknowledge the empty observation so the next wait
+            // blocks on the ready-value update instead of spinning on the old
+            // view version.
+            if (view_change->changed &&
+                !view_change->current_view.has_value()) {
+                std::lock_guard<std::mutex> lock(leader_switch_mutex_);
+                // Do not let a stale empty watch result erase a newer view
+                // installed concurrently by the heartbeat recovery path.
+                const bool still_on_observed_view =
+                    known_version.has_value()
+                        ? current_master_view_.has_value() &&
+                              current_master_view_->view_version ==
+                                  known_version.value()
+                        : !current_master_view_.has_value();
+                if (still_on_observed_view) {
+                    current_master_view_.reset();
+                }
+            }
             continue;
         }
 
@@ -685,20 +780,9 @@ ErrorCode Client::InitTransferEngine(
 
     bool auto_discover = false;
     if (!use_tent) {
-        // Get auto_discover and filters from env (non-TENT only)
-        std::optional<bool> env_auto_discover = get_auto_discover();
-        if (env_auto_discover.has_value()) {
-            // Use user-specified auto-discover setting
-            auto_discover = env_auto_discover.value();
-        } else {
-            // Enable auto-discover for RDMA/EFA if no devices are specified
-            if ((protocol == "rdma" || protocol == "efa") &&
-                !device_names.has_value()) {
-                LOG(INFO) << "Set auto discovery ON by default for " << protocol
-                          << " protocol, since no device names provided";
-                auto_discover = true;
-            }
-        }
+        auto config = ClientAutoDiscoveryConfig::FromEnvironment(
+            protocol, device_names.has_value());
+        auto_discover = config.enabled;
         transfer_engine_->setAutoDiscover(
             {.enabled = auto_discover, .protocol = protocol});
 
@@ -707,15 +791,11 @@ ErrorCode Client::InitTransferEngine(
             LOG(INFO)
                 << "Transfer engine auto discovery is enabled for protocol: "
                 << protocol;
-            auto filters = get_auto_discover_filters();
-            transfer_engine_->setWhitelistFilters(std::move(filters));
-        } else {
-            const char* env_filters = std::getenv("MC_MS_FILTERS");
-            if (env_filters && *env_filters != '\0') {
-                LOG(WARNING)
-                    << "MC_MS_FILTERS is set but auto discovery is disabled; "
-                    << "ignoring whitelist: " << env_filters;
-            }
+        }
+
+        config.LoadFiltersFromEnvironment();
+        if (auto_discover) {
+            transfer_engine_->setWhitelistFilters(std::move(config.filters));
         }
     }
 
@@ -899,8 +979,9 @@ void Client::InitTransferSubmitter() {
     // Keep using logical local_hostname for name-based behaviors; endpoint is
     // used separately where needed.
 #ifdef USE_NOF
-    int numa_socket_id =
-        GetConfiguredNumaSocketId().value_or(GetCurrentNumaSocketId());
+    const int numa_socket_id =
+        ClientNumaConfig::FromEnvironment().socket_id.value_or(
+            GetCurrentNumaSocketId());
     transfer_submitter_ = std::make_unique<TransferSubmitter>(
         *transfer_engine_, storage_backend_, local_hostname_,
         metrics_ ? &metrics_->transfer_metric : nullptr, numa_socket_id);
@@ -994,6 +1075,8 @@ std::optional<std::shared_ptr<Client>> Client::Create(
         }
     }
 
+    client->EnterHaRuntimeMode();
+
     // this only performs RPC calls
     if (protocol == "rpc_only") {
         LOG(INFO) << "Use rpc only. Skip initializing transfer engine.";
@@ -1105,8 +1188,8 @@ tl::expected<QueryResult, ErrorCode> Client::Query(
     if (!result) {
         return tl::unexpected(result.error());
     }
-    return QueryResult(
-        std::move(result.value().replicas),
+    return tl::expected<QueryResult, ErrorCode>(
+        tl::in_place, std::move(result.value().replicas),
         start_time + std::chrono::milliseconds(result.value().lease_ttl_ms),
         result.value().object_checksum);
 }
@@ -1138,11 +1221,11 @@ std::vector<tl::expected<QueryResult, ErrorCode>> Client::BatchQuery(
     results.reserve(response.size());
     for (size_t i = 0; i < response.size(); ++i) {
         if (response[i]) {
-            results.emplace_back(QueryResult(
-                std::move(response[i].value().replicas),
+            results.emplace_back(
+                tl::in_place, std::move(response[i].value().replicas),
                 start_time +
                     std::chrono::milliseconds(response[i].value().lease_ttl_ms),
-                response[i].value().object_checksum));
+                response[i].value().object_checksum);
         } else {
             results.emplace_back(tl::unexpected(response[i].error()));
         }
@@ -1258,7 +1341,11 @@ tl::expected<void, ErrorCode> Client::Get(const std::string& object_key,
     }
 
     auto t0_get = std::chrono::steady_clock::now();
-    err = TransferRead(replica, slices);
+    if (replica.is_dfs_replica()) {
+        err = ReadDfsReplica(object_key, replica, slices);
+    } else {
+        err = TransferRead(replica, slices);
+    }
 
     // Release the cache block after transfer completes (memcpy is done)
     if (hot_cache_ && cache_used) {
@@ -1281,6 +1368,11 @@ tl::expected<void, ErrorCode> Client::Get(const std::string& object_key,
         VerifyObjectChecksum(object_key, slices, calculate_total_size(replica),
                              query_result.object_checksum);
     if (!checksum_result) {
+        // add checksum err for single-key
+        auto* dfs_metric = GetDfsMetricPtr();
+        if (replica.is_dfs_replica() && dfs_metric) {
+            dfs_metric->RecordReadErrors(toString(checksum_result.error()));
+        }
         return tl::unexpected(checksum_result.error());
     }
 
@@ -1485,6 +1577,17 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchGetWhenPreferSameNode(
             }
         }
     }
+    // A successful transfer is only valid while its read lease is live.
+    // Check once all segment batches have completed, as in the regular
+    // BatchGet path, and preserve errors from validation or transfer.
+    auto now = std::chrono::steady_clock::now();
+    for (size_t i = 0; i < object_keys.size(); ++i) {
+        if (results[i].has_value() && query_results[i].IsLeaseExpired(now)) {
+            LOG(WARNING) << "lease_expired_before_data_transfer_completed key="
+                         << object_keys[i];
+            results[i] = tl::unexpected(ErrorCode::LEASE_EXPIRED);
+        }
+    }
     return results;
 }
 
@@ -1524,6 +1627,8 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchGet(
     std::vector<std::tuple<size_t, std::string, TransferFuture,
                            Replica::Descriptor, bool>>
         pending_transfers;
+    std::vector<DfsReadRequest> dfs_read_requests;
+    std::vector<size_t> dfs_read_indices;
     std::vector<tl::expected<void, ErrorCode>> results(object_keys.size());
     // Record batch get transfer latency (Submit + Wait)
     auto t0_batch_get = std::chrono::steady_clock::now();
@@ -1565,7 +1670,22 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchGet(
 
         // Submit transfer operation asynchronously
         std::optional<TransferFuture> future;
-        if (replica.is_nof_replica()) {
+        if (replica.is_dfs_replica()) {
+            if (!dfs_storage_backend_) {
+                LOG(ERROR) << "DFS backend is not initialized";
+                if (auto* dfs_metric = GetDfsMetricPtr()) {
+                    dfs_metric->RecordReadErrors(
+                        toString(ErrorCode::DFS_SERVICE_UNAVAILABLE));
+                }
+                results[i] = tl::unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+                continue;
+            }
+            const auto& desc = replica.get_dfs_descriptor();
+            dfs_read_requests.push_back(
+                DfsReadRequest{key, desc, slices_it->second});
+            dfs_read_indices.push_back(i);
+            continue;
+        } else if (replica.is_nof_replica()) {
             auto contiguous_range = GetContiguousSliceRange(slices_it->second);
             if (!contiguous_range.has_value()) {
                 LOG(ERROR) << "NoF transfer requires contiguous slices";
@@ -1597,6 +1717,74 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchGet(
                                        cache_used);
     }
 
+    if (!dfs_read_requests.empty()) {
+        auto* dfs_metric = GetDfsMetricPtr();
+        const auto dfs_read_start = std::chrono::steady_clock::now();
+        auto dfs_results = dfs_storage_backend_->BatchRead(dfs_read_requests);
+        const auto dfs_read_latency_us = elapsed_us_since(dfs_read_start);
+        int64_t dfs_success_keys = 0;
+        uint64_t dfs_success_bytes = 0;
+        if (dfs_results.size() != dfs_read_requests.size()) {
+            LOG(ERROR) << "DFS BatchRead response size mismatch: expected "
+                       << dfs_read_requests.size() << ", got "
+                       << dfs_results.size();
+            for (size_t index : dfs_read_indices) {
+                results[index] = tl::unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+            if (dfs_metric) {
+                dfs_metric->RecordReadErrors(
+                    toString(ErrorCode::INTERNAL_ERROR),
+                    static_cast<int64_t>(dfs_read_indices.size()));
+            }
+        } else {
+            for (size_t i = 0; i < dfs_results.size(); ++i) {
+                const size_t index = dfs_read_indices[i];
+                const auto& request = dfs_read_requests[i];
+                if (!dfs_results[i]) {
+                    LOG(WARNING) << "DFS read failed, action=batch_read, key="
+                                 << request.key
+                                 << ", offset=" << request.descriptor.offset
+                                 << ", size=" << request.descriptor.object_size
+                                 << ", error=" << dfs_results[i].error();
+                    if (dfs_metric) {
+                        dfs_metric->RecordReadErrors(
+                            toString(dfs_results[i].error()));
+                    }
+                    results[index] = tl::unexpected(dfs_results[i].error());
+                    continue;
+                }
+                // The I/O itself delivered these bytes, so they count even if
+                // the checksum below rejects the payload; a checksum mismatch
+                // is additionally recorded as an error so the two are
+                // distinguishable.
+                ++dfs_success_keys;
+                dfs_success_bytes += request.descriptor.object_size;
+                auto checksum_result = VerifyObjectChecksum(
+                    request.key, request.slices, request.descriptor.object_size,
+                    query_results[index].object_checksum);
+                if (!checksum_result) {
+                    if (dfs_metric) {
+                        dfs_metric->RecordReadErrors(
+                            toString(checksum_result.error()));
+                    }
+                    results[index] = tl::unexpected(checksum_result.error());
+                    continue;
+                }
+                results[index] = {};
+            }
+        }
+        if (dfs_metric && dfs_success_keys > 0) {
+            dfs_metric->ObserveRead(dfs_success_keys,
+                                    static_cast<int64_t>(dfs_success_bytes),
+                                    dfs_read_latency_us);
+        }
+        VLOG(1) << "DFS batch read finished, action=batch_read, requested="
+                << dfs_read_requests.size()
+                << ", succeeded=" << dfs_success_keys
+                << ", bytes=" << dfs_success_bytes
+                << ", latency_us=" << dfs_read_latency_us;
+    }
+
     // Wait for all transfers to complete
     for (auto& [index, key, future, stored_replica, cache_used] :
          pending_transfers) {
@@ -1723,6 +1911,11 @@ tl::expected<void, ErrorCode> Client::Put(const ObjectKey& key,
 
     // Start put operation
     auto start_result = master_client_.PutStart(key, slice_lengths, client_cfg);
+    if (!start_result &&
+        start_result.error() == ErrorCode::OBJECT_ALREADY_EXISTS &&
+        healDanglingLocalDiskReplica(key)) {
+        start_result = master_client_.PutStart(key, slice_lengths, client_cfg);
+    }
     if (!start_result) {
         ErrorCode err = start_result.error();
         if (err == ErrorCode::OBJECT_ALREADY_EXISTS) {
@@ -1777,6 +1970,39 @@ tl::expected<void, ErrorCode> Client::Put(const ObjectKey& key,
         }
     }
 
+    if (transfer_summary.allocated_dfs_replicas > 0 &&
+        NonDfsTransfersSucceeded(transfer_summary)) {
+        std::vector<std::string> dfs_keys;
+        std::vector<const std::vector<Slice>*> dfs_slices;
+        std::vector<DistributedFSDescriptor> dfs_descriptors;
+        for (const auto& replica : start_result.value()) {
+            if (!replica.is_dfs_replica()) {
+                continue;
+            }
+            dfs_keys.push_back(key);
+            dfs_slices.push_back(&slices);
+            dfs_descriptors.push_back(replica.get_dfs_descriptor());
+        }
+        for (auto dfs_result :
+             WriteDfsReplicas(dfs_keys, dfs_slices, dfs_descriptors)) {
+            if (dfs_result == ErrorCode::OK) {
+                transfer_summary.RecordSuccess(ReplicaType::DFS);
+            } else {
+                transfer_summary.RecordFailure(ReplicaType::DFS, dfs_result);
+            }
+        }
+    } else if (transfer_summary.allocated_dfs_replicas > 0) {
+        // A DFS replica was allocated but is abandoned because a peer replica
+        // failed first. Without this counter the write simply disappears: no
+        // error is recorded against DFS and no I/O is attempted. Counted per
+        // key, matching SubmitDfsWrites.
+        VLOG(1) << "Skipping DFS write, action=skip, key=" << key
+                << ", reason=non_dfs_transfer_failed";
+        if (auto* dfs_metric = GetDfsMetricPtr()) {
+            dfs_metric->RecordSkippedWrites(1);
+        }
+    }
+
     auto us_put = std::chrono::duration_cast<std::chrono::microseconds>(
                       std::chrono::steady_clock::now() - t0_put)
                       .count();
@@ -1813,6 +2039,61 @@ tl::expected<void, ErrorCode> Client::Put(const ObjectKey& key,
     return {};
 }
 
+namespace {
+
+// Every COMPLETE replica in the list is a LOCAL_DISK replica owned by this
+// client, so nothing else can serve reads for the key.
+bool HasOnlyClientLocalDiskReplicas(
+    const std::vector<Replica::Descriptor>& replicas, const UUID& client_id) {
+    bool has_local_disk = false;
+    for (const auto& replica : replicas) {
+        if (replica.status != ReplicaStatus::COMPLETE) {
+            continue;
+        }
+        if (replica.is_local_disk_replica() &&
+            replica.get_local_disk_descriptor().client_id == client_id) {
+            has_local_disk = true;
+            continue;
+        }
+        // A completed replica owned elsewhere (memory, remote disk, DFS) can
+        // still serve reads, so there is nothing for this client to heal.
+        return false;
+    }
+    return has_local_disk;
+}
+
+}  // namespace
+
+bool Client::healDanglingLocalDiskReplica(const ObjectKey& key) {
+    auto replicas = master_client_.GetReplicaList(key);
+    if (!replicas ||
+        !HasOnlyClientLocalDiskReplicas(replicas->replicas, client_id_) ||
+        !local_disk_probe_fn_) {
+        return false;
+    }
+    // RemoveAll wipes client SSD files while master keeps the metadata
+    // (issue #3709), leaving a completed entry whose backing file is gone.
+    // Reporting success for a Put on top of it would store nothing. Ask the
+    // installed probe (the offload file storage owned by RealClient) whether
+    // the file is still there. Only a proven-gone answer evicts; present or
+    // unknown (transport/config trouble) keeps the old idempotent path, so a
+    // healthy replica can never be evicted by mistake.
+    const std::optional<bool> file_gone = local_disk_probe_fn_(key);
+    if (file_gone != true) {
+        return false;
+    }
+    auto evicted =
+        master_client_.EvictDiskReplica(key, ReplicaType::LOCAL_DISK);
+    if (!evicted) {
+        LOG(WARNING) << "Failed to evict dangling LOCAL_DISK replica for key="
+                     << key << ": " << toString(evicted.error());
+        return false;
+    }
+    LOG(WARNING) << "Evicted dangling LOCAL_DISK replica for key=" << key
+                 << " (backing file already gone)";
+    return true;
+}
+
 tl::expected<void, ErrorCode> Client::Upsert(const ObjectKey& key,
                                              std::vector<Slice>& slices,
                                              const ReplicateConfig& config) {
@@ -1856,6 +2137,11 @@ tl::expected<void, ErrorCode> Client::Upsert(const ObjectKey& key,
         return tl::unexpected(err);
     }
 
+    ReplicaTransferSummary transfer_summary;
+    for (const auto& replica : start_result.value()) {
+        transfer_summary.RecordAllocatedReplica(replica);
+    }
+
     // Record transfer latency
     auto t0 = std::chrono::steady_clock::now();
 
@@ -1872,20 +2158,51 @@ tl::expected<void, ErrorCode> Client::Upsert(const ObjectKey& key,
         }
     }
 
-    // Transfer to memory replicas
+    // Transfer to memory and NoF replicas first.
     for (const auto& replica : start_result.value()) {
-        if (replica.is_memory_replica()) {
+        if (replica.is_memory_replica() || replica.is_nof_replica()) {
+            const auto replica_type = replica.is_memory_replica()
+                                          ? ReplicaType::MEMORY
+                                          : ReplicaType::NOF_SSD;
             ErrorCode transfer_err = TransferWrite(replica, slices);
             if (transfer_err != ErrorCode::OK) {
-                auto revoke_result =
-                    master_client_.UpsertRevoke(key, ReplicaType::MEMORY);
-                if (!revoke_result) {
-                    LOG(ERROR) << "Failed to revoke upsert operation";
-                    return tl::unexpected(revoke_result.error());
-                }
-                return tl::unexpected(transfer_err);
+                transfer_summary.RecordFailure(replica_type, transfer_err);
+                continue;
+            }
+            transfer_summary.RecordSuccess(replica_type);
+        }
+    }
+
+    if (transfer_summary.allocated_dfs_replicas > 0 &&
+        NonDfsTransfersSucceeded(transfer_summary)) {
+        std::vector<std::string> dfs_keys;
+        std::vector<const std::vector<Slice>*> dfs_slices;
+        std::vector<DistributedFSDescriptor> dfs_descriptors;
+        for (const auto& replica : start_result.value()) {
+            if (!replica.is_dfs_replica()) {
+                continue;
+            }
+            dfs_keys.push_back(key);
+            dfs_slices.push_back(&slices);
+            dfs_descriptors.push_back(replica.get_dfs_descriptor());
+        }
+        for (auto dfs_result :
+             WriteDfsReplicas(dfs_keys, dfs_slices, dfs_descriptors)) {
+            if (dfs_result == ErrorCode::OK) {
+                transfer_summary.RecordSuccess(ReplicaType::DFS);
+            } else {
+                transfer_summary.RecordFailure(ReplicaType::DFS, dfs_result);
             }
         }
+    } else if (transfer_summary.allocated_dfs_replicas > 0) {
+        // Same abandoned-write case as in Put: the DFS replica was allocated
+        // but a peer replica failed first, so no I/O is attempted and no DFS
+        // error is recorded. Counted per key, matching SubmitDfsWrites.
+        VLOG(1) << "Skipping DFS write, action=skip, key=" << key
+                << ", reason=non_dfs_transfer_failed";
+        if (auto* dfs_metric = GetDfsMetricPtr()) {
+            dfs_metric->RecordSkippedWrites(1);
+        }
     }
 
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
@@ -1895,13 +2212,27 @@ tl::expected<void, ErrorCode> Client::Upsert(const ObjectKey& key,
         metrics_->transfer_metric.put_latency_us.observe(us);
     }
 
-    // End upsert operation
-    auto end_result = master_client_.UpsertEnd(ObjectMeta{key, object_checksum},
-                                               ReplicaType::MEMORY);
-    if (!end_result) {
-        ErrorCode err = end_result.error();
-        LOG(ERROR) << "Failed to end upsert operation: " << err;
-        return tl::unexpected(err);
+    const auto finalize_decision =
+        DetermineFinalizeDecision(config, transfer_summary);
+    if (finalize_decision.end_type.has_value()) {
+        auto end_result = master_client_.UpsertEnd(
+            ObjectMeta{key, object_checksum}, *finalize_decision.end_type);
+        if (!end_result) {
+            ErrorCode err = end_result.error();
+            LOG(ERROR) << "Failed to end upsert operation: " << err;
+            return tl::unexpected(err);
+        }
+    }
+    if (finalize_decision.revoke_type.has_value()) {
+        auto revoke_result =
+            master_client_.UpsertRevoke(key, *finalize_decision.revoke_type);
+        if (!revoke_result) {
+            LOG(ERROR) << "Failed to revoke upsert operation";
+            return tl::unexpected(revoke_result.error());
+        }
+    }
+    if (!finalize_decision.success) {
+        return tl::unexpected(finalize_decision.error);
     }
 
     // Success-side invalidation: a concurrent read between the pre-upsert
@@ -1919,23 +2250,35 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchUpsert(
     const std::vector<ObjectKey>& keys,
     std::vector<std::vector<Slice>>& batched_slices,
     const ReplicateConfig& config) {
+    return BatchUpsert(keys, batched_slices, config, {});
+}
+
+std::vector<tl::expected<void, ErrorCode>> Client::BatchUpsert(
+    const std::vector<ObjectKey>& keys,
+    std::vector<std::vector<Slice>>& batched_slices,
+    const ReplicateConfig& config, const WriteBufferStager& stager) {
     ReplicateConfig client_cfg = AttachHostId(config);
     if (protocol_ == "cxl") {
         client_cfg.preferred_segment = local_hostname_;
     }
+    std::vector<PutOperation> ops = CreatePutOperations(keys, batched_slices);
+    ComputeBatchObjectChecksums(ops);
     if (client_cfg.prefer_alloc_in_same_node) {
-        LOG(ERROR) << "prefer_alloc_in_same_node is not supported for upsert";
-        return std::vector<tl::expected<void, ErrorCode>>(
-            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+        if (auto err = ValidatePreferSameNodeWriteConfig(client_cfg)) {
+            return std::vector<tl::expected<void, ErrorCode>>(
+                keys.size(), tl::unexpected(*err));
+        }
+        StartBatchUpsert(ops, client_cfg);
+        StageWriteBuffersForRemoteReplicas(ops, stager);
+        return BatchWriteWhenPreferSameNode(ops, true);
     }
 
-    std::vector<PutOperation> ops = CreatePutOperations(keys, batched_slices);
-    ComputeBatchObjectChecksums(ops);
     StartBatchUpsert(ops, client_cfg);
-
+    StageWriteBuffersForRemoteReplicas(ops, stager);
     auto t0 = std::chrono::steady_clock::now();
     SubmitTransfers(ops);
     WaitForTransfers(ops);
+    SubmitDfsWrites(ops);
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
                   std::chrono::steady_clock::now() - t0)
                   .count();
@@ -1986,6 +2329,7 @@ class PutOperation {
 
     size_t requested_memory_replicas = 0;
     size_t requested_nof_replicas = 0;
+    size_t requested_dfs_replicas = 0;
     ReplicaTransferSummary transfer_summary;
 
     // Error context for debugging
@@ -2038,12 +2382,14 @@ class PutOperation {
     void InitializeRequestedReplicas(const ReplicateConfig& config) {
         requested_memory_replicas = config.replica_num;
         requested_nof_replicas = config.nof_replica_num;
+        requested_dfs_replicas = config.dfs_replica_num;
     }
 
     ReplicateConfig ToReplicateConfig() const {
         ReplicateConfig config;
         config.replica_num = requested_memory_replicas;
         config.nof_replica_num = requested_nof_replicas;
+        config.dfs_replica_num = requested_dfs_replicas;
         return config;
     }
 
@@ -2089,6 +2435,99 @@ void Client::ComputeBatchObjectChecksums(std::vector<PutOperation>& ops) {
     }
 }
 
+void Client::healDanglingLocalDiskBatchStarts(
+    std::vector<PutOperation>& ops, const std::vector<size_t>& active_indices,
+    const std::vector<size_t>& already_exists,
+    const std::vector<std::string>& keys,
+    const std::vector<std::vector<uint64_t>>& slice_lengths,
+    const ReplicateConfig& config) {
+    if (already_exists.empty() || !local_disk_probe_fn_) {
+        return;
+    }
+    std::vector<std::string> candidate_keys;
+    candidate_keys.reserve(already_exists.size());
+    for (size_t i : already_exists) {
+        candidate_keys.emplace_back(keys[i]);
+    }
+    // One round trip for the whole subset: a healthy idempotent batch pays a
+    // single batched query and no evictions, and the per-key work left over
+    // is a local filesystem probe.
+    auto replica_lists = master_client_.BatchGetReplicaList(candidate_keys);
+    if (replica_lists.size() != candidate_keys.size()) {
+        return;
+    }
+    std::vector<std::string> evict_keys;
+    std::vector<size_t> evict_positions;
+    for (size_t j = 0; j < candidate_keys.size(); ++j) {
+        if (!replica_lists[j] || !HasOnlyClientLocalDiskReplicas(
+                                     replica_lists[j]->replicas, client_id_)) {
+            continue;
+        }
+        const std::optional<bool> file_gone =
+            local_disk_probe_fn_(candidate_keys[j]);
+        if (file_gone != true) {
+            continue;
+        }
+        evict_keys.emplace_back(candidate_keys[j]);
+        evict_positions.emplace_back(j);
+    }
+    if (evict_keys.empty()) {
+        return;
+    }
+    auto evicted = master_client_.BatchEvictDiskReplica(
+        evict_keys, ReplicaType::LOCAL_DISK);
+    if (evicted.size() != evict_keys.size()) {
+        return;
+    }
+    std::vector<std::string> retry_keys;
+    std::vector<std::vector<uint64_t>> retry_slices;
+    std::vector<size_t> retry_positions;
+    for (size_t j = 0; j < evict_keys.size(); ++j) {
+        if (!evicted[j]) {
+            LOG(WARNING) << "Failed to evict dangling LOCAL_DISK replica for "
+                         << "key=" << evict_keys[j] << ": "
+                         << toString(evicted[j].error());
+            continue;
+        }
+        LOG(WARNING) << "Evicted dangling LOCAL_DISK replica for key="
+                     << evict_keys[j] << " (backing file already gone)";
+        retry_positions.emplace_back(evict_positions[j]);
+        retry_keys.emplace_back(keys[already_exists[evict_positions[j]]]);
+        retry_slices.emplace_back(
+            slice_lengths[already_exists[evict_positions[j]]]);
+    }
+    if (retry_keys.empty()) {
+        return;
+    }
+    auto retry_responses =
+        master_client_.BatchPutStart(retry_keys, retry_slices, config);
+    if (retry_responses.size() != retry_keys.size()) {
+        return;
+    }
+    for (size_t r = 0; r < retry_keys.size(); ++r) {
+        auto& op = ops[active_indices[already_exists[retry_positions[r]]]];
+        if (!retry_responses[r]) {
+            // OBJECT_ALREADY_EXISTS again means another writer won the race;
+            // the idempotent skip applies. Any other error is reported as is.
+            if (retry_responses[r].error() !=
+                ErrorCode::OBJECT_ALREADY_EXISTS) {
+                op.SetTerminalError(retry_responses[r].error(),
+                                    PutOperationState::MASTER_FAILED,
+                                    "Master failed to start put operation");
+            }
+            continue;
+        }
+        op.replicas = std::move(retry_responses[r].value());
+        op.RecordAllocatedReplicas();
+        if (!HasExpectedReplicaAllocation(config, op.transfer_summary)) {
+            op.SetTerminalError(ErrorCode::NO_AVAILABLE_HANDLE,
+                                PutOperationState::MASTER_FAILED,
+                                "Allocated replicas do not satisfy "
+                                "requested replica policy");
+        }
+    }
+}
+
 void Client::StartBatchPut(std::vector<PutOperation>& ops,
                            const ReplicateConfig& config) {
     std::vector<std::string> keys;
@@ -2143,15 +2582,24 @@ void Client::StartBatchPut(std::vector<PutOperation>& ops,
     }
 
     // Process individual responses with robust error handling
+    std::vector<size_t> already_exists;
     for (size_t i = 0; i < active_indices.size(); ++i) {
         auto& op = ops[active_indices[i]];
         op.InitializeRequestedReplicas(config);
         if (!start_responses[i]) {
+            if (start_responses[i].error() ==
+                ErrorCode::OBJECT_ALREADY_EXISTS) {
+                // Decided after the heal pass below: retried when the
+                // replica proves dangling, or the idempotent skip that
+                // CollectResults already grants.
+                already_exists.emplace_back(i);
+                continue;
+            }
             op.SetTerminalError(start_responses[i].error(),
                                 PutOperationState::MASTER_FAILED,
                                 "Master failed to start put operation");
         } else {
-            op.replicas = start_responses[i].value();
+            op.replicas = std::move(start_responses[i].value());
             op.RecordAllocatedReplicas();
             if (!HasExpectedReplicaAllocation(config, op.transfer_summary)) {
                 op.SetTerminalError(ErrorCode::NO_AVAILABLE_HANDLE,
@@ -2166,6 +2614,17 @@ void Client::StartBatchPut(std::vector<PutOperation>& ops,
                     << op.replicas.size() << " replicas";
         }
     }
+
+    healDanglingLocalDiskBatchStarts(ops, active_indices, already_exists, keys,
+                                     slice_lengths, config);
+    for (size_t i : already_exists) {
+        auto& op = ops[active_indices[i]];
+        if (!op.IsResolved() && op.replicas.empty()) {
+            op.SetTerminalError(ErrorCode::OBJECT_ALREADY_EXISTS,
+                                PutOperationState::MASTER_FAILED,
+                                "Master failed to start put operation");
+        }
+    }
 }
 
 void Client::StartBatchUpsert(std::vector<PutOperation>& ops,
@@ -2224,11 +2683,21 @@ void Client::StartBatchUpsert(std::vector<PutOperation>& ops,
     // Process individual responses with robust error handling
     for (size_t i = 0; i < active_indices.size(); ++i) {
         auto& op = ops[active_indices[i]];
+        op.InitializeRequestedReplicas(config);
         if (!start_responses[i]) {
-            op.SetError(start_responses[i].error(),
-                        "Master failed to start upsert operation");
+            op.SetTerminalError(start_responses[i].error(),
+                                PutOperationState::MASTER_FAILED,
+                                "Master failed to start upsert operation");
         } else {
-            op.replicas = start_responses[i].value();
+            op.replicas = std::move(start_responses[i].value());
+            op.RecordAllocatedReplicas();
+            if (!HasExpectedReplicaAllocation(config, op.transfer_summary)) {
+                op.SetTerminalError(ErrorCode::NO_AVAILABLE_HANDLE,
+                                    PutOperationState::MASTER_FAILED,
+                                    "Allocated replicas do not satisfy "
+                                    "requested replica policy");
+                continue;
+            }
             VLOG(1) << "Successfully started upsert for key " << op.key
                     << " with " << op.replicas.size() << " replicas";
         }
@@ -2359,18 +2828,229 @@ void Client::WaitForTransfers(std::vector<PutOperation>& ops) {
     }
 }
 
-void Client::FinalizeBatchPut(std::vector<PutOperation>& ops) {
-    struct BatchFinalizeGroup {
-        std::vector<std::string> keys;
-        std::vector<size_t> indices;
-    };
-
-    BatchFinalizeGroup end_all_group;
-    BatchFinalizeGroup end_memory_group;
-    BatchFinalizeGroup end_nof_group;
-    BatchFinalizeGroup revoke_all_group;
-    BatchFinalizeGroup revoke_memory_group;
-    BatchFinalizeGroup revoke_nof_group;
+std::vector<ErrorCode> Client::WriteDfsReplicas(
+    const std::vector<std::string>& keys,
+    const std::vector<const std::vector<Slice>*>& slice_lists,
+    const std::vector<DistributedFSDescriptor>& descriptors) {
+    if (keys.size() != slice_lists.size() ||
+        keys.size() != descriptors.size()) {
+        return std::vector<ErrorCode>(keys.size(), ErrorCode::INVALID_PARAMS);
+    }
+    if (keys.empty()) {
+        return {};
+    }
+    if (!dfs_storage_backend_) {
+        LOG(ERROR) << "DFS backend is unavailable for synchronous write";
+        if (auto* dfs_metric = GetDfsMetricPtr()) {
+            dfs_metric->RecordWriteErrors(
+                toString(ErrorCode::DFS_SERVICE_UNAVAILABLE),
+                static_cast<int64_t>(keys.size()));
+        }
+        return std::vector<ErrorCode>(keys.size(),
+                                      ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+
+    auto* dfs_metric = GetDfsMetricPtr();
+    std::vector<ErrorCode> results(keys.size(), ErrorCode::OK);
+    std::vector<DfsWriteRequest> requests;
+    std::vector<size_t> request_indices;
+    // Bytes per request, so the success accounting after BatchWrite does not
+    // have to walk the slice lists a second time.
+    std::vector<uint64_t> request_bytes;
+    std::vector<PinnedBufferPool::Buffer> staging_buffers;
+    requests.reserve(keys.size());
+    request_indices.reserve(keys.size());
+    request_bytes.reserve(keys.size());
+
+    // Staging is the device-to-host copy below; it is timed separately from the
+    // BatchWrite call so a slow put can be attributed to the right side of the
+    // boundary between them.
+    const auto staging_start = std::chrono::steady_clock::now();
+    bool staging_performed = false;
+    auto runtime_accelerator =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
+    for (size_t i = 0; i < keys.size(); ++i) {
+        if (slice_lists[i] == nullptr) {
+            results[i] = ErrorCode::INVALID_PARAMS;
+            if (dfs_metric) {
+                dfs_metric->RecordWriteErrors(
+                    toString(ErrorCode::INVALID_PARAMS));
+            }
+            continue;
+        }
+
+        std::vector<Slice> host_slices;
+        host_slices.reserve(slice_lists[i]->size());
+        uint64_t key_bytes = 0;
+        bool staging_succeeded = true;
+        for (const auto& slice : *slice_lists[i]) {
+            device::PointerInfo info{};
+            auto* device = slice.ptr == nullptr
+                               ? nullptr
+                               : runtime_accelerator.FindDeviceForPointer(
+                                     slice.ptr, &info);
+            if (device == nullptr) {
+                key_bytes += slice.size;
+                host_slices.push_back(slice);
+                continue;
+            }
+
+            staging_performed = true;
+            device->SetContext(info.device_id);
+            auto buffer = pinned_buffer_pool_->Acquire(slice.size);
+            if (!device->Copy(buffer.data, slice.ptr, slice.size,
+                              device::CopyDirection::kDeviceToHost)) {
+                LOG(ERROR) << "DFS D2H staging failed, action=stage, key="
+                           << keys[i] << ", size=" << slice.size
+                           << ", device_id=" << info.device_id;
+                pinned_buffer_pool_->Release(std::move(buffer));
+                results[i] = ErrorCode::TRANSFER_FAIL;
+                staging_succeeded = false;
+                break;
+            }
+            key_bytes += slice.size;
+            host_slices.emplace_back(Slice{buffer.data, slice.size});
+            staging_buffers.push_back(std::move(buffer));
+        }
+        if (!staging_succeeded) {
+            // Counted as a DFS write failure: the key was destined for DFS and
+            // never got there, even though the backend was never reached.
+            if (dfs_metric) {
+                dfs_metric->RecordWriteErrors(
+                    toString(ErrorCode::TRANSFER_FAIL));
+            }
+            continue;
+        }
+
+        requests.push_back(
+            DfsWriteRequest{keys[i], descriptors[i], std::move(host_slices)});
+        request_indices.push_back(i);
+        request_bytes.push_back(key_bytes);
+    }
+    if (dfs_metric && staging_performed) {
+        dfs_metric->ObserveWriteStaging(elapsed_us_since(staging_start));
+    }
+
+    const auto write_start = std::chrono::steady_clock::now();
+    auto write_results = dfs_storage_backend_->BatchWrite(requests);
+    const auto write_latency_us = elapsed_us_since(write_start);
+    int64_t success_keys = 0;
+    uint64_t success_bytes = 0;
+    if (write_results.size() != requests.size()) {
+        LOG(ERROR) << "DFS BatchWrite response size mismatch: expected "
+                   << requests.size() << ", got " << write_results.size();
+        for (size_t index : request_indices) {
+            results[index] = ErrorCode::INTERNAL_ERROR;
+        }
+        if (dfs_metric && !request_indices.empty()) {
+            dfs_metric->RecordWriteErrors(
+                toString(ErrorCode::INTERNAL_ERROR),
+                static_cast<int64_t>(request_indices.size()));
+        }
+    } else {
+        for (size_t i = 0; i < write_results.size(); ++i) {
+            results[request_indices[i]] =
+                write_results[i] ? ErrorCode::OK : write_results[i].error();
+            if (write_results[i]) {
+                ++success_keys;
+                success_bytes += request_bytes[i];
+            } else if (dfs_metric) {
+                dfs_metric->RecordWriteErrors(
+                    toString(write_results[i].error()));
+            }
+        }
+    }
+    // Latency is per batch, so it is only observed when the batch delivered
+    // something; a fully failed batch would otherwise pollute the histogram
+    // with error-path timings.
+    if (dfs_metric && success_keys > 0) {
+        dfs_metric->ObserveWrite(success_keys,
+                                 static_cast<int64_t>(success_bytes),
+                                 write_latency_us);
+    }
+    VLOG(1) << "DFS batch write finished, action=write, requested="
+            << requests.size() << ", succeeded=" << success_keys
+            << ", bytes=" << success_bytes
+            << ", latency_us=" << write_latency_us;
+
+    for (auto& buffer : staging_buffers) {
+        pinned_buffer_pool_->Release(std::move(buffer));
+    }
+    return results;
+}
+
+void Client::SubmitDfsWrites(std::vector<PutOperation>& ops) {
+    std::vector<std::string> keys;
+    std::vector<const std::vector<Slice>*> slice_lists;
+    std::vector<DistributedFSDescriptor> descriptors;
+    std::vector<size_t> op_indices;
+    auto* dfs_metric = GetDfsMetricPtr();
+    int64_t skipped_writes = 0;
+
+    for (size_t i = 0; i < ops.size(); ++i) {
+        auto& op = ops[i];
+        if (op.IsResolved() ||
+            op.transfer_summary.allocated_dfs_replicas == 0) {
+            continue;
+        }
+        // A DFS replica was allocated but is abandoned because a peer replica
+        // failed first. Without this counter the write simply disappears: no
+        // error is recorded against DFS and no I/O is attempted.
+        if (!NonDfsTransfersSucceeded(op.transfer_summary)) {
+            ++skipped_writes;
+            VLOG(1) << "Skipping DFS write, action=skip, key=" << op.key
+                    << ", reason=non_dfs_transfer_failed";
+            continue;
+        }
+
+        auto dfs_it = std::find_if(op.replicas.begin(), op.replicas.end(),
+                                   [](const Replica::Descriptor& replica) {
+                                       return replica.is_dfs_replica();
+                                   });
+        if (dfs_it == op.replicas.end()) {
+            op.transfer_summary.RecordFailure(ReplicaType::DFS,
+                                              ErrorCode::INVALID_REPLICA);
+            op.AppendFailureContext("Allocated DFS replica has no descriptor");
+            if (dfs_metric) {
+                dfs_metric->RecordWriteErrors(
+                    toString(ErrorCode::INVALID_REPLICA));
+            }
+            continue;
+        }
+        keys.push_back(op.key);
+        slice_lists.push_back(&op.slices);
+        descriptors.push_back(dfs_it->get_dfs_descriptor());
+        op_indices.push_back(i);
+    }
+    if (dfs_metric && skipped_writes > 0) {
+        dfs_metric->RecordSkippedWrites(skipped_writes);
+    }
+
+    auto results = WriteDfsReplicas(keys, slice_lists, descriptors);
+    for (size_t i = 0; i < results.size(); ++i) {
+        auto& op = ops[op_indices[i]];
+        if (results[i] == ErrorCode::OK) {
+            op.transfer_summary.RecordSuccess(ReplicaType::DFS);
+        } else {
+            op.transfer_summary.RecordFailure(ReplicaType::DFS, results[i]);
+            op.AppendFailureContext("Synchronous DFS write failed: " +
+                                    toString(results[i]));
+        }
+    }
+}
+
+void Client::FinalizeBatchPut(std::vector<PutOperation>& ops) {
+    struct BatchFinalizeGroup {
+        std::vector<std::string> keys;
+        std::vector<size_t> indices;
+    };
+
+    BatchFinalizeGroup end_all_group;
+    BatchFinalizeGroup end_memory_group;
+    BatchFinalizeGroup end_nof_group;
+    BatchFinalizeGroup revoke_all_group;
+    BatchFinalizeGroup revoke_memory_group;
+    BatchFinalizeGroup revoke_nof_group;
 
     std::vector<size_t> pending_finalize_actions(ops.size(), 0);
     std::vector<bool> should_succeed(ops.size(), false);
@@ -2575,14 +3255,26 @@ void Client::FinalizeBatchUpsert(std::vector<PutOperation>& ops) {
 
     for (size_t i = 0; i < ops.size(); ++i) {
         auto& op = ops[i];
-
         if (!op.IsResolved() && !op.replicas.empty() &&
-            !op.pending_transfers.empty()) {
+            HasExpectedReplicaAllocation(op.ToReplicateConfig(),
+                                         op.transfer_summary) &&
+            AllAllocatedTransfersSucceeded(op.transfer_summary)) {
             successful_object_metas.emplace_back(
                 ObjectMeta{op.key, op.object_checksum});
             successful_indices.emplace_back(i);
-        } else if (op.state != PutOperationState::PENDING &&
-                   !op.replicas.empty()) {
+            continue;
+        }
+
+        if (!op.IsResolved() && !op.replicas.empty()) {
+            const auto error = op.transfer_summary.first_error == ErrorCode::OK
+                                   ? ErrorCode::TRANSFER_FAIL
+                                   : op.transfer_summary.first_error;
+            op.SetTerminalError(
+                error, PutOperationState::TRANSFER_FAILED,
+                op.failure_context.value_or(
+                    "Replica transfer failed before upsert finalize"));
+        }
+        if (!op.IsSuccessful() && !op.replicas.empty()) {
             failed_keys.emplace_back(op.key);
             failed_indices.emplace_back(i);
         }
@@ -2712,8 +3404,31 @@ std::vector<tl::expected<void, ErrorCode>> Client::CollectResults(
     return results;
 }
 
-std::vector<tl::expected<void, ErrorCode>> Client::BatchPutWhenPreferSameNode(
-    std::vector<PutOperation>& ops) {
+void Client::StageWriteBuffersForRemoteReplicas(
+    std::vector<PutOperation>& ops, const WriteBufferStager& stager) {
+    if (!stager) return;
+
+    for (auto& op : ops) {
+        if (op.IsResolved() || op.replicas.empty() ||
+            std::all_of(op.replicas.begin(), op.replicas.end(),
+                        [this](const Replica::Descriptor& replica) {
+                            return CanUseLocalMemcpy(replica);
+                        })) {
+            continue;
+        }
+        auto staged_slices = stager(op.slices);
+        if (!staged_slices) {
+            op.SetError(staged_slices.error(),
+                        "Failed to stage non-local write buffers");
+            continue;
+        }
+        op.slices = std::move(*staged_slices);
+        VLOG(1) << "Staged write buffers for non-local replica, key=" << op.key;
+    }
+}
+
+std::vector<tl::expected<void, ErrorCode>> Client::BatchWriteWhenPreferSameNode(
+    std::vector<PutOperation>& ops, bool is_upsert) {
     auto t0 = std::chrono::steady_clock::now();
     std::unordered_map<std::string, PutOperation> seg_to_ops{};
     for (auto& op : ops) {
@@ -2802,13 +3517,18 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchPutWhenPreferSameNode(
             seg_to_ops.at(seg).transfer_summary.first_error;
         op.failure_context = seg_to_ops.at(seg).failure_context;
     }
+    SubmitDfsWrites(ops);
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
                   std::chrono::steady_clock::now() - t0)
                   .count();
     if (metrics_) {
         metrics_->transfer_metric.batch_put_latency_us.observe(us);
     }
-    FinalizeBatchPut(ops);
+    if (is_upsert) {
+        FinalizeBatchUpsert(ops);
+    } else {
+        FinalizeBatchPut(ops);
+    }
     return CollectResults(ops);
 }
 
@@ -2816,6 +3536,13 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchPut(
     const std::vector<ObjectKey>& keys,
     std::vector<std::vector<Slice>>& batched_slices,
     const ReplicateConfig& config) {
+    return BatchPut(keys, batched_slices, config, {});
+}
+
+std::vector<tl::expected<void, ErrorCode>> Client::BatchPut(
+    const std::vector<ObjectKey>& keys,
+    std::vector<std::vector<Slice>>& batched_slices,
+    const ReplicateConfig& config, const WriteBufferStager& stager) {
     ReplicateConfig client_cfg = AttachHostId(config);
     if (protocol_ == "cxl") {
         client_cfg.preferred_segment = local_hostname_;
@@ -2823,26 +3550,21 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchPut(
     std::vector<PutOperation> ops = CreatePutOperations(keys, batched_slices);
     ComputeBatchObjectChecksums(ops);
     if (client_cfg.prefer_alloc_in_same_node) {
-        if (client_cfg.nof_replica_num > 0) {
-            LOG(ERROR) << "prefer_alloc_in_same_node is not supported with "
-                          "NoF replicas";
+        if (auto err = ValidatePreferSameNodeWriteConfig(client_cfg)) {
             return std::vector<tl::expected<void, ErrorCode>>(
-                keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
-        }
-        if (client_cfg.replica_num != 1) {
-            LOG(ERROR) << "prefer_alloc_in_same_node is not supported with "
-                          "replica_num != 1";
-            return std::vector<tl::expected<void, ErrorCode>>(
-                keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+                keys.size(), tl::unexpected(*err));
         }
         StartBatchPut(ops, client_cfg);
-        return BatchPutWhenPreferSameNode(ops);
+        StageWriteBuffersForRemoteReplicas(ops, stager);
+        return BatchWriteWhenPreferSameNode(ops, false);
     }
     StartBatchPut(ops, client_cfg);
+    StageWriteBuffersForRemoteReplicas(ops, stager);
 
     auto t0 = std::chrono::steady_clock::now();
     SubmitTransfers(ops);
     WaitForTransfers(ops);
+    SubmitDfsWrites(ops);
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
                   std::chrono::steady_clock::now() - t0)
                   .count();
@@ -2854,6 +3576,50 @@ std::vector<tl::expected<void, ErrorCode>> Client::BatchPut(
     return CollectResults(ops);
 }
 
+std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
+Client::StartBatchPutForSizes(const std::vector<std::string>& keys,
+                              const std::vector<uint64_t>& object_sizes,
+                              const ReplicateConfig& config) {
+    std::vector<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
+        results(keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    if (keys.size() != object_sizes.size()) {
+        LOG(ERROR) << "StartBatchPutForSizes size mismatch: keys="
+                   << keys.size() << ", sizes=" << object_sizes.size();
+        return results;
+    }
+
+    ReplicateConfig client_cfg = AttachHostId(config);
+    if (protocol_ == "cxl") {
+        client_cfg.preferred_segment = local_hostname_;
+    }
+
+    std::vector<std::vector<Slice>> batched_slices(keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        batched_slices[i] = {Slice{nullptr, object_sizes[i]}};
+    }
+    std::vector<PutOperation> ops = CreatePutOperations(keys, batched_slices);
+    StartBatchPut(ops, client_cfg);
+
+    for (size_t i = 0; i < ops.size(); ++i) {
+        if (ops[i].IsResolved()) {
+            results[i] = tl::unexpected(ops[i].result.error());
+            continue;
+        }
+        results[i] = std::move(ops[i].replicas);
+    }
+    return results;
+}
+
+std::vector<tl::expected<void, ErrorCode>> Client::BatchPutEnd(
+    const std::vector<ObjectMeta>& object_metas, ReplicaType replica_type) {
+    return master_client_.BatchPutEnd(object_metas, replica_type);
+}
+
+std::vector<tl::expected<void, ErrorCode>> Client::BatchPutRevoke(
+    const std::vector<std::string>& keys, ReplicaType replica_type) {
+    return master_client_.BatchPutRevoke(keys, replica_type);
+}
+
 tl::expected<void, ErrorCode> Client::Remove(const ObjectKey& key, bool force) {
     if (hot_cache_) {
         hot_cache_->BumpKeyGeneration(key);
@@ -2866,7 +3632,6 @@ tl::expected<void, ErrorCode> Client::Remove(const ObjectKey& key, bool force) {
     if (!result) {
         return tl::unexpected(result.error());
     }
-
     if (hot_cache_) {
         hot_cache_->RemoveHotKey(key);
     }
@@ -3031,7 +3796,7 @@ tl::expected<void, ErrorCode> Client::UnmountSegment(const void* buffer,
 tl::expected<UUID, ErrorCode> Client::MountSegmentAndGetId(
     const void* buffer, size_t size, const std::string& protocol,
     const std::string& location) {
-    auto check_result = CheckRegisterMemoryParams(buffer, size);
+    auto check_result = CheckRegisterMemoryParams(buffer, size, protocol);
     if (!check_result) {
         return tl::unexpected(check_result.error());
     }
@@ -3216,7 +3981,7 @@ void Client::OnGracefulUnmountTimer(const UUID& segment_id, int retry_left) {
 tl::expected<void, ErrorCode> Client::RegisterLocalMemory(
     void* addr, size_t length, const std::string& location,
     bool remote_accessible, bool update_metadata) {
-    auto check_result = CheckRegisterMemoryParams(addr, length);
+    auto check_result = CheckRegisterMemoryParams(addr, length, protocol_);
     if (!check_result) {
         return tl::unexpected(check_result.error());
     }
@@ -3241,6 +4006,11 @@ tl::expected<bool, ErrorCode> Client::IsExist(const std::string& key) {
     return result;
 }
 
+tl::expected<bool, ErrorCode> Client::ProbeKey(const std::string& key) {
+    auto result = master_client_.ProbeKey(key);
+    return result;
+}
+
 std::vector<tl::expected<bool, ErrorCode>> Client::BatchIsExist(
     const std::vector<std::string>& keys) {
     auto response = master_client_.BatchExistKey(keys);
@@ -3263,6 +4033,26 @@ std::vector<tl::expected<bool, ErrorCode>> Client::BatchIsExist(
     return response;
 }
 
+std::vector<tl::expected<bool, ErrorCode>> Client::BatchProbeKey(
+    const std::vector<std::string>& keys) {
+    auto response = master_client_.BatchProbeKey(keys);
+
+    // Check if we got the expected number of responses
+    if (response.size() != keys.size()) {
+        LOG(ERROR) << "BatchProbeKey response size mismatch. Expected: "
+                   << keys.size() << ", Got: " << response.size();
+        // Return vector of RPC_FAIL errors
+        std::vector<tl::expected<bool, ErrorCode>> results;
+        results.reserve(keys.size());
+        for (size_t i = 0; i < keys.size(); ++i) {
+            results.emplace_back(tl::unexpected(ErrorCode::RPC_FAIL));
+        }
+        return results;
+    }
+
+    return response;
+}
+
 void* Client::GetBaseAddr() { return transfer_engine_->getBaseAddr(); }
 
 tl::expected<void, ErrorCode> Client::MountLocalDiskSegment(
@@ -3280,6 +4070,15 @@ tl::expected<void, ErrorCode> Client::MountLocalDiskSegment(
     return response;
 }
 
+tl::expected<void, ErrorCode> Client::UnmountLocalDiskSegment() {
+    auto response = master_client_.UnmountLocalDiskSegment(client_id_);
+    if (!response) {
+        LOG(ERROR) << "UnmountLocalDiskSegment failed, error code is "
+                   << response.error();
+    }
+    return response;
+}
+
 tl::expected<void, ErrorCode> Client::OffloadObjectHeartbeat(
     bool enable_offloading, std::vector<OffloadTaskItem>& offloading_objects) {
     auto response =
@@ -3314,8 +4113,19 @@ tl::expected<void, ErrorCode> Client::BatchGetOffloadObject(
     const std::vector<std::string>& keys,
     const std::vector<uintptr_t>& pointers,
     const std::unordered_map<std::string, std::vector<Slice>>& batch_slices) {
+    return BatchGetOffloadObject(transfer_engine_addr, keys, pointers,
+                                 batch_slices,
+                                 OffloadBufferAccess::kTransferEngine);
+}
+
+tl::expected<void, ErrorCode> Client::BatchGetOffloadObject(
+    const std::string& transfer_engine_addr,
+    const std::vector<std::string>& keys,
+    const std::vector<uintptr_t>& pointers,
+    const std::unordered_map<std::string, std::vector<Slice>>& batch_slices,
+    OffloadBufferAccess buffer_access) {
     auto future = transfer_submitter_->submit_batch_get_offload_object(
-        transfer_engine_addr, keys, pointers, batch_slices);
+        transfer_engine_addr, keys, pointers, batch_slices, buffer_access);
     if (!future) {
         LOG(ERROR) << "Failed to submit transfer operation";
         return tl::make_unexpected(ErrorCode::TRANSFER_FAIL);
@@ -3343,6 +4153,12 @@ tl::expected<void, ErrorCode> Client::NotifyOffloadSuccess(
     return master_client_.NotifyOffloadSuccess(client_id_, tasks, metadatas);
 }
 
+void Client::SetDfsStorageBackend(
+    std::shared_ptr<DistributedStorageBackend> backend) {
+    dfs_storage_backend_ = std::move(backend);
+    EnsureStorageControlPlaneStarted();
+}
+
 tl::expected<void, ErrorCode> Client::PromotionObjectHeartbeat(
     std::vector<PromotionTaskItem>& promotion_objects) {
     auto response = master_client_.PromotionObjectHeartbeat(client_id_);
@@ -3483,14 +4299,33 @@ tl::expected<void, ErrorCode> Client::Copy(
 tl::expected<void, ErrorCode> Client::Copy(
     const std::string& key, const std::string& tenant_id,
     const std::string& source, const std::vector<std::string>& targets) {
+    return Copy(key, tenant_id, source, targets, UUID{}, 0);
+}
+
+tl::expected<void, ErrorCode> Client::Copy(
+    const std::string& key, const std::string& tenant_id,
+    const std::string& source, const std::vector<std::string>& targets,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
     LOG(INFO) << "action=replica_copy_start" << ", key=" << key
               << ", targets_count=" << targets.size();
 
     // Call CopyStart first - it validates existence and allocates replicas
     auto start_result =
-        master_client_.CopyStart(key, tenant_id, source, targets);
+        dynamic_replication_lease_id == UUID{}
+            ? master_client_.CopyStart(key, tenant_id, source, targets)
+            : master_client_.DynamicReplicaCopyStart(
+                  key, tenant_id, source, targets, dynamic_replication_lease_id,
+                  dynamic_replication_version_epoch);
     if (!start_result.has_value()) {
         ErrorCode error = start_result.error();
+        if (dynamic_replication_lease_id != UUID{} &&
+            error == ErrorCode::OBJECT_ALREADY_EXISTS) {
+            LOG(INFO) << "action=replica_copy_skipped"
+                      << ", key=" << key
+                      << ", info=target_replicas_already_exist";
+            return {};
+        }
         LOG(ERROR) << "action=replica_copy_failed" << ", key=" << key
                    << ", source=" << source << ", error=copy_start_failed"
                    << ", error_code=" << error;
@@ -3502,7 +4337,12 @@ tl::expected<void, ErrorCode> Client::Copy(
         LOG(INFO) << "action=replica_copy_skipped" << ", key=" << key
                   << ", info=target_replicas_already_exist";
         // Target replicas already exist, consider it success
-        auto copy_end_result = master_client_.CopyEnd(key, tenant_id);
+        auto copy_end_result =
+            dynamic_replication_lease_id == UUID{}
+                ? master_client_.CopyEnd(key, tenant_id)
+                : master_client_.DynamicReplicaCopyEnd(
+                      key, tenant_id, dynamic_replication_lease_id,
+                      dynamic_replication_version_epoch);
         if (!copy_end_result.has_value()) {
             ErrorCode error = copy_end_result.error();
             LOG(ERROR) << "action=replica_copy_failed" << ", key=" << key
@@ -3512,10 +4352,22 @@ tl::expected<void, ErrorCode> Client::Copy(
         return {};
     }
 
-    auto result = ExecuteReplicaTransfer(
-        key, "copy", [&]() { return master_client_.CopyEnd(key, tenant_id); },
-        [&]() { return master_client_.CopyRevoke(key, tenant_id); },
-        response.source, response.targets);
+    auto copy_end = [&]() {
+        return dynamic_replication_lease_id == UUID{}
+                   ? master_client_.CopyEnd(key, tenant_id)
+                   : master_client_.DynamicReplicaCopyEnd(
+                         key, tenant_id, dynamic_replication_lease_id,
+                         dynamic_replication_version_epoch);
+    };
+    auto copy_revoke = [&]() {
+        return dynamic_replication_lease_id == UUID{}
+                   ? master_client_.CopyRevoke(key, tenant_id)
+                   : master_client_.DynamicReplicaCopyRevoke(
+                         key, tenant_id, dynamic_replication_lease_id,
+                         dynamic_replication_version_epoch);
+    };
+    auto result = ExecuteReplicaTransfer(key, "copy", copy_end, copy_revoke,
+                                         response.source, response.targets);
 
     if (result.has_value()) {
         LOG(INFO) << "action=replica_copy_success" << ", key=" << key
@@ -3755,16 +4607,193 @@ ErrorCode Client::TransferData(const Replica::Descriptor& replica_descriptor,
     return future->get();
 }
 
-ErrorCode Client::TransferReadInternal(
+std::optional<TransferFuture> Client::SubmitRangeRead(
     const Replica::Descriptor& replica_descriptor, std::vector<Slice>& slices,
     uint64_t src_offset) {
     if (!transfer_submitter_) {
         LOG(ERROR) << "TransferSubmitter not initialized";
-        return ErrorCode::INVALID_PARAMS;
+        return std::nullopt;
+    }
+    return transfer_submitter_->submitRangeRead(replica_descriptor, slices,
+                                                src_offset);
+}
+
+std::optional<TransferFuture> Client::SubmitRangeWrite(
+    const Replica::Descriptor& replica_descriptor, std::vector<Slice>& slices,
+    uint64_t dst_offset) {
+    if (!transfer_submitter_) {
+        LOG(ERROR) << "TransferSubmitter not initialized";
+        return std::nullopt;
+    }
+    return transfer_submitter_->submitRangeWrite(replica_descriptor, slices,
+                                                 dst_offset);
+}
+
+std::vector<tl::expected<int64_t, ErrorCode>> Client::BatchTransferReadRanges(
+    const std::vector<Replica::Descriptor>& replicas,
+    const std::vector<std::vector<Slice>>& slices,
+    const std::vector<std::vector<uint64_t>>& src_offsets) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(
+        replicas.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    if (replicas.size() != slices.size() ||
+        replicas.size() != src_offsets.size()) {
+        LOG(ERROR) << "BatchTransferReadRanges size mismatch: replicas="
+                   << replicas.size() << ", slices=" << slices.size()
+                   << ", offsets=" << src_offsets.size();
+        return results;
+    }
+
+    size_t fragment_count = 0;
+    for (const auto& entry : slices) {
+        fragment_count += entry.size();
+    }
+
+    // Every fragment of every entry goes into one scatter submit so the
+    // transport sees the whole layer at once instead of one transfer per key.
+    ScatterRangeBuilder builder(fragment_count);
+    std::vector<std::optional<ErrorCode>> entry_errors(replicas.size());
+    for (size_t i = 0; i < replicas.size(); ++i) {
+        if (slices[i].size() != src_offsets[i].size()) {
+            LOG(ERROR) << "BatchTransferReadRanges fragment count mismatch, "
+                       << "entry=" << i << ", slices=" << slices[i].size()
+                       << ", offsets=" << src_offsets[i].size();
+            continue;  // results[i] stays INVALID_PARAMS
+        }
+        if (!replicas[i].is_memory_replica()) {
+            LOG(ERROR) << "Range read requires a memory replica, entry=" << i;
+            continue;
+        }
+
+        const auto& handle =
+            replicas[i].get_memory_descriptor().buffer_descriptor;
+        int64_t transferred = 0;
+        for (size_t j = 0; j < slices[i].size(); ++j) {
+            builder.Add(TransferRequest::READ, handle, slices[i][j],
+                        src_offsets[i][j], &entry_errors[i]);
+            transferred += static_cast<int64_t>(slices[i][j].size);
+        }
+        results[i] = transferred;  // optimistic; corrected on await
+    }
+
+    if (builder.empty()) {
+        return results;
+    }
+
+    auto operation = SubmitScatter(builder.ranges());
+    if (!operation) {
+        LOG(ERROR) << "Failed to submit batch range read";
+        for (auto& result : results) {
+            if (result.has_value()) {
+                result = tl::unexpected(ErrorCode::TRANSFER_FAIL);
+            }
+        }
+        return results;
+    }
+    (void)operation->wait();
+
+    for (size_t i = 0; i < results.size(); ++i) {
+        if (!results[i].has_value() || !entry_errors[i].has_value()) {
+            continue;
+        }
+        LOG(ERROR) << "Range read failed, entry=" << i
+                   << ", error=" << static_cast<int>(entry_errors[i].value());
+        results[i] = tl::unexpected(entry_errors[i].value());
+    }
+    return results;
+}
+
+std::vector<tl::expected<int64_t, ErrorCode>> Client::BatchTransferWriteRanges(
+    const std::vector<std::vector<Replica::Descriptor>>& replicas_per_entry,
+    const std::vector<std::vector<Slice>>& slices,
+    const std::vector<std::vector<uint64_t>>& dst_offsets) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(
+        replicas_per_entry.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    if (replicas_per_entry.size() != slices.size() ||
+        replicas_per_entry.size() != dst_offsets.size()) {
+        LOG(ERROR) << "BatchTransferWriteRanges size mismatch: entries="
+                   << replicas_per_entry.size() << ", slices=" << slices.size()
+                   << ", offsets=" << dst_offsets.size();
+        return results;
+    }
+
+    size_t fragment_count = 0;
+    for (size_t i = 0; i < replicas_per_entry.size(); ++i) {
+        for (const auto& replica : replicas_per_entry[i]) {
+            if (replica.is_memory_replica()) {
+                fragment_count += slices[i].size();
+            }
+        }
+    }
+
+    // One scatter submit covers every replica of every entry, so replication
+    // fans out inside a single transfer instead of one submit per fragment.
+    ScatterRangeBuilder builder(fragment_count);
+    std::vector<std::optional<ErrorCode>> entry_errors(
+        replicas_per_entry.size());
+    for (size_t i = 0; i < replicas_per_entry.size(); ++i) {
+        if (slices[i].size() != dst_offsets[i].size()) {
+            LOG(ERROR) << "BatchTransferWriteRanges fragment count mismatch, "
+                       << "entry=" << i << ", slices=" << slices[i].size()
+                       << ", offsets=" << dst_offsets[i].size();
+            continue;  // results[i] stays INVALID_PARAMS
+        }
+
+        // Logical bytes: counted once per fragment, not per replica.
+        int64_t transferred = 0;
+        for (const auto& slice : slices[i]) {
+            transferred += static_cast<int64_t>(slice.size);
+        }
+        bool submitted = false;
+        for (const auto& replica : replicas_per_entry[i]) {
+            if (!replica.is_memory_replica()) {
+                continue;
+            }
+            const auto& handle =
+                replica.get_memory_descriptor().buffer_descriptor;
+            for (size_t j = 0; j < slices[i].size(); ++j) {
+                builder.Add(TransferRequest::WRITE, handle, slices[i][j],
+                            dst_offsets[i][j], &entry_errors[i]);
+                submitted = true;
+            }
+        }
+        if (!submitted) {
+            results[i] = tl::unexpected(ErrorCode::INVALID_REPLICA);
+            continue;
+        }
+        results[i] = transferred;  // optimistic; corrected on await
+    }
+
+    if (builder.empty()) {
+        return results;
+    }
+
+    auto operation = SubmitScatter(builder.ranges());
+    if (!operation) {
+        LOG(ERROR) << "Failed to submit batch range write";
+        for (auto& result : results) {
+            if (result.has_value()) {
+                result = tl::unexpected(ErrorCode::TRANSFER_FAIL);
+            }
+        }
+        return results;
     }
+    (void)operation->wait();
 
-    auto future = transfer_submitter_->submitRangeRead(replica_descriptor,
-                                                       slices, src_offset);
+    for (size_t i = 0; i < results.size(); ++i) {
+        if (!results[i].has_value() || !entry_errors[i].has_value()) {
+            continue;
+        }
+        LOG(ERROR) << "Range write failed, entry=" << i
+                   << ", error=" << static_cast<int>(entry_errors[i].value());
+        results[i] = tl::unexpected(entry_errors[i].value());
+    }
+    return results;
+}
+
+ErrorCode Client::TransferReadInternal(
+    const Replica::Descriptor& replica_descriptor, std::vector<Slice>& slices,
+    uint64_t src_offset) {
+    auto future = SubmitRangeRead(replica_descriptor, slices, src_offset);
     if (!future) {
         LOG(ERROR) << "Failed to submit range read operation";
         return ErrorCode::TRANSFER_FAIL;
@@ -3780,6 +4809,19 @@ ErrorCode Client::TransferWrite(const Replica::Descriptor& replica_descriptor,
     return TransferData(replica_descriptor, slices, TransferRequest::WRITE);
 }
 
+ErrorCode Client::TransferWriteRange(
+    const Replica::Descriptor& replica_descriptor, std::vector<Slice>& slices,
+    uint64_t dst_offset) {
+    auto future = SubmitRangeWrite(replica_descriptor, slices, dst_offset);
+    if (!future) {
+        LOG(ERROR) << "Failed to submit range write operation";
+        return ErrorCode::TRANSFER_FAIL;
+    }
+
+    VLOG(1) << "Using transfer strategy: " << future->strategy();
+    return future->get();
+}
+
 ErrorCode Client::TransferRead(const Replica::Descriptor& replica_descriptor,
                                std::vector<Slice>& slices) {
     size_t total_size = 0;
@@ -3795,6 +4837,8 @@ ErrorCode Client::TransferRead(const Replica::Descriptor& replica_descriptor,
     } else if (replica_descriptor.is_local_disk_replica()) {
         auto& disk_desc = replica_descriptor.get_local_disk_descriptor();
         total_size = disk_desc.object_size;
+    } else if (replica_descriptor.is_dfs_replica()) {
+        total_size = replica_descriptor.get_dfs_descriptor().object_size;
     }
 
     size_t slices_size = CalculateSliceSize(slices);
@@ -3804,9 +4848,63 @@ ErrorCode Client::TransferRead(const Replica::Descriptor& replica_descriptor,
         return ErrorCode::INVALID_PARAMS;
     }
 
+    if (replica_descriptor.is_dfs_replica()) {
+        LOG(ERROR) << "DFS reads require object key context";
+        return ErrorCode::INVALID_REPLICA;
+    }
+
     return TransferData(replica_descriptor, slices, TransferRequest::READ);
 }
 
+ErrorCode Client::ReadDfsReplica(const std::string& key,
+                                 const Replica::Descriptor& replica_descriptor,
+                                 std::vector<Slice>& slices) {
+    if (!replica_descriptor.is_dfs_replica()) {
+        return ErrorCode::INVALID_REPLICA;
+    }
+    if (!dfs_storage_backend_) {
+        LOG(ERROR) << "DFS backend is not initialized";
+        if (auto* dfs_metric = GetDfsMetricPtr()) {
+            dfs_metric->RecordReadErrors(
+                toString(ErrorCode::DFS_SERVICE_UNAVAILABLE));
+        }
+        return ErrorCode::DFS_SERVICE_UNAVAILABLE;
+    }
+
+    auto* dfs_metric = GetDfsMetricPtr();
+    const auto& desc = replica_descriptor.get_dfs_descriptor();
+    std::vector<DfsReadRequest> requests{DfsReadRequest{key, desc, slices}};
+    const auto read_start = std::chrono::steady_clock::now();
+    auto results = dfs_storage_backend_->BatchRead(requests);
+    const auto read_latency_us = elapsed_us_since(read_start);
+    if (results.size() != 1) {
+        LOG(ERROR) << "DFS BatchRead response size mismatch for key " << key;
+        if (dfs_metric) {
+            dfs_metric->RecordReadErrors(toString(ErrorCode::INTERNAL_ERROR));
+        }
+        return ErrorCode::INTERNAL_ERROR;
+    }
+    if (!results[0]) {
+        LOG(ERROR) << "DFS read failed, action=read, key=" << key
+                   << ", offset=" << desc.offset
+                   << ", size=" << desc.object_size
+                   << ", latency_us=" << read_latency_us
+                   << ", error=" << results[0].error();
+        if (dfs_metric) {
+            dfs_metric->RecordReadErrors(toString(results[0].error()));
+        }
+        return results[0].error();
+    }
+    if (dfs_metric) {
+        dfs_metric->ObserveRead(1, static_cast<int64_t>(desc.object_size),
+                                read_latency_us);
+    }
+    VLOG(1) << "DFS read finished, action=read, key=" << key
+            << ", offset=" << desc.offset << ", size=" << desc.object_size
+            << ", latency_us=" << read_latency_us;
+    return ErrorCode::OK;
+}
+
 ErrorCode Client::TransferReadRange(
     const Replica::Descriptor& replica_descriptor, std::vector<Slice>& slices,
     uint64_t src_offset) {
@@ -3871,8 +4969,13 @@ void Client::ExecuteTask(const ClientTask& client_task) {
             case TaskType::REPLICA_COPY: {
                 ReplicaCopyPayload payload;
                 struct_json::from_json(payload, assignment.payload);
-                auto copy_result = Copy(payload.key, payload.tenant_id,
-                                        payload.source, payload.targets);
+                const UUID dynamic_lease_id{
+                    payload.dynamic_replication_lease_id_high,
+                    payload.dynamic_replication_lease_id_low};
+                auto copy_result =
+                    Copy(payload.key, payload.tenant_id, payload.source,
+                         payload.targets, dynamic_lease_id,
+                         payload.dynamic_replication_version_epoch);
                 if (copy_result.has_value()) {
                     result = ErrorCode::OK;
                 } else {
@@ -4045,8 +5148,10 @@ void Client::StorageHeartbeatThreadMain() {
             remount_segment_future = std::future<void>();
         }
 
-        // Ping master
-        auto ping_result = master_client_.Ping();
+        auto ping_result = metrics_
+                               ? metrics_->master_heartbeat_metric.ObservePing(
+                                     [this] { return master_client_.Ping(); })
+                               : master_client_.Ping();
         if (ping_result) {
             // Reset ping failure count
             ping_fail_count = 0;
@@ -4145,7 +5250,7 @@ void Client::StorageHeartbeatThreadMain() {
             LOG(ERROR) << "Failed to ping master for " << ping_fail_count
                        << " times (non-HA); reconnecting to "
                        << current_master_address;
-            auto err = master_client_.Connect(current_master_address);
+            auto err = ConnectMasterEndpoint(current_master_address);
             if (err != ErrorCode::OK) {
                 LOG(ERROR) << "Reconnect failed to " << current_master_address
                            << ": " << toString(err);
@@ -4223,60 +5328,6 @@ tl::expected<Replica::Descriptor, ErrorCode> Client::GetPreferredReplica(
     return replica_list[0];
 }
 
-size_t Client::GetLocalHotCacheSizeFromEnv() {
-    if (const char* ev_size = std::getenv("MC_STORE_LOCAL_HOT_CACHE_SIZE")) {
-        std::string ev_size_str(ev_size);
-        std::string error_msg = "Invalid MC_STORE_LOCAL_HOT_CACHE_SIZE='" +
-                                ev_size_str + "', disable local hot cache";
-        // Check for negative values
-        if (!ev_size_str.empty() && ev_size_str[0] == '-') {
-            LOG(WARNING) << error_msg;
-            return 0;
-        }
-        try {
-            unsigned long long v = std::stoull(ev_size_str, nullptr, 10);
-            if (v > 0) {
-                return static_cast<size_t>(v);
-            } else {
-                LOG(WARNING) << error_msg;
-                return 0;
-            }
-        } catch (const std::exception&) {
-            LOG(WARNING) << error_msg;
-            return 0;
-        }
-    }
-    return 0;
-}
-
-size_t Client::GetLocalHotBlockSizeFromEnv(size_t default_value) {
-    if (const char* ev_block_size =
-            std::getenv("MC_STORE_LOCAL_HOT_BLOCK_SIZE")) {
-        std::string ev_block_size_str(ev_block_size);
-        std::string error_msg = "Invalid MC_STORE_LOCAL_HOT_BLOCK_SIZE='" +
-                                ev_block_size_str +
-                                "', using default block size";
-        // Check for negative values
-        if (!ev_block_size_str.empty() && ev_block_size_str[0] == '-') {
-            LOG(WARNING) << error_msg;
-            return default_value;
-        }
-        try {
-            unsigned long long v = std::stoull(ev_block_size_str, nullptr, 10);
-            if (v > 0) {
-                return static_cast<size_t>(v);
-            } else {
-                LOG(WARNING) << error_msg;
-                return default_value;
-            }
-        } catch (const std::exception&) {
-            LOG(WARNING) << error_msg;
-            return default_value;
-        }
-    }
-    return default_value;
-}
-
 ErrorCode Client::InitLocalHotCache() {
     hot_cache_handler_.reset();
     UnregisterLocalHotCacheMemory();
@@ -4287,38 +5338,22 @@ ErrorCode Client::InitLocalHotCache() {
         return ErrorCode::OK;
     }
 
-    // Defaults: hot cache is disabled unless MC_STORE_LOCAL_HOT_CACHE_SIZE is
-    // set to a positive value; when enabled, default block size is 16MB and
-    // thread_num is 2.
-    size_t block_size = 16 * 1024 * 1024;  // 16MB default block size
-    size_t thread_num = 2;
-
-    // Read MC_STORE_LOCAL_HOT_CACHE_SIZE from environment
-    size_t total_cache = GetLocalHotCacheSizeFromEnv();
-    if (total_cache == 0) {
-        // Environment variable not set or invalid, disable cache
+    const auto config = LocalHotCacheConfig::FromEnvironment();
+    if (config.total_size_bytes == 0) {
         return ErrorCode::OK;
     }
 
-    // Read MC_STORE_LOCAL_HOT_BLOCK_SIZE from environment
-    block_size = GetLocalHotBlockSizeFromEnv(block_size);
-
-    // MC_STORE_LOCAL_HOT_CACHE_USE_SHM: "1" enables memfd-backed shm (default
-    // off). When enabled, hot cache is shareable with dummy clients via IPC.
-    bool use_shm = false;
-    if (const char* ev = std::getenv("MC_STORE_LOCAL_HOT_CACHE_USE_SHM")) {
-        use_shm = (std::string(ev) == "1");
-    }
+    size_t thread_num = 2;
 
     // Enable hot cache
     {
-        hot_cache_ =
-            std::make_shared<LocalHotCache>(total_cache, block_size, use_shm);
+        hot_cache_ = std::make_shared<LocalHotCache>(
+            config.total_size_bytes, config.block_size_bytes, config.use_shm);
         // Check if cache initialization was successful
         if (hot_cache_->GetCacheSize() == 0) {
             LOG(ERROR)
                 << "Local hot cache creation failed: no blocks allocated. "
-                << "total_cache=" << total_cache;
+                << "total_cache=" << config.total_size_bytes;
             hot_cache_.reset();
             hot_cache_handler_.reset();
             admission_sketch_.reset();
@@ -4342,35 +5377,17 @@ ErrorCode Client::InitLocalHotCache() {
         }
         hot_cache_memory_registered_ = true;
 
-        LOG(INFO) << "Local hot cache enabled with cache size=" << total_cache
-                  << ", block size=" << block_size
+        LOG(INFO) << "Local hot cache enabled with cache size="
+                  << config.total_size_bytes
+                  << ", block size=" << config.block_size_bytes
                   << ", block amount=" << hot_cache_->GetCacheSize()
-                  << ", shm=" << (use_shm ? "on" : "off")
+                  << ", shm=" << (config.use_shm ? "on" : "off")
                   << ", transfer engine registered=on";
         // Create async handler with 2 worker threads
         hot_cache_handler_ =
             std::make_unique<LocalHotCacheHandler>(hot_cache_, thread_num);
         admission_sketch_ = std::make_unique<CountMinSketch>();
-
-        // MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD: minimum CMS count before a
-        // key is admitted to hot cache (default 2).
-        if (const char* ev =
-                std::getenv("MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD")) {
-            std::string ev_str(ev);
-            std::string error_msg =
-                "Invalid MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD='" + ev_str +
-                "', using default";
-            try {
-                unsigned long long v = std::stoull(ev_str, nullptr, 10);
-                if (v > 0 && v <= 255) {
-                    admission_threshold_ = static_cast<uint8_t>(v);
-                } else {
-                    LOG(WARNING) << error_msg;
-                }
-            } catch (const std::exception&) {
-                LOG(WARNING) << error_msg;
-            }
-        }
+        admission_threshold_ = config.admission_threshold;
     }
     return ErrorCode::OK;
 }
diff --git a/mooncake-store/src/common/client_buffer_allocation.cpp b/mooncake-store/src/common/client_buffer_allocation.cpp
new file mode 100644
index 0000000000..9b87c4562f
--- /dev/null
+++ b/mooncake-store/src/common/client_buffer_allocation.cpp
@@ -0,0 +1,170 @@
+#include "common/client_buffer_allocation.h"
+
+#include "config.h"
+#include "config/hugepage_config.h"
+#include "ub_allocator.h"
+
+#include <cstdlib>
+#include <glog/logging.h>
+
+#ifdef USE_CUDA
+#include <cuda_runtime.h>
+#endif
+#ifdef USE_INTRA_NVLINK
+#include "gpu_vendor/intra_nvlink.h"
+#endif
+#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
+#include "ascend_allocator.h"
+#endif
+#if defined(USE_SUNRISE)
+#include "sunrise_allocator.h"
+#endif
+#ifdef USE_NOF
+#include "spdk/spdk_wrapper.h"
+#endif
+
+namespace mooncake {
+namespace {
+
+#ifdef USE_VRAM_SEGMENT
+tl::expected<void *, std::string> allocate_vram_memory(
+    size_t total_size, const std::string &protocol) {
+    cudaError_t res;
+    int device;
+    void *ptr = nullptr;
+    res = cudaGetDevice(&device);
+    if (res != cudaSuccess) {
+        LOG(ERROR) << "VRAM Segment cudaGetDevice failed.";
+        return tl::make_unexpected("VRAM Segment cudaGetDevice failed.");
+    }
+    if (protocol == "nvlink_intra") {
+#ifdef USE_INTRA_NVLINK
+        ptr = allocateFabricMemory_intra(total_size);
+        return ptr;
+#else
+        LOG(ERROR) << "Protocol nvlink_intra need USE_INTRA_NVLINK=ON. Please "
+                      "rebuild mooncake from source.";
+        return tl::make_unexpected("Protocol not supported");
+#endif
+    }
+    res = cudaMalloc((void **)&ptr, total_size);
+    if (res != cudaSuccess) {
+        LOG(ERROR) << "VRAM Segment cudaMalloc failed.";
+        return tl::make_unexpected("VRAM Segment cudaMalloc failed.");
+    }
+    return ptr;
+}
+#endif
+
+}  // namespace
+
+size_t get_hugepage_size_from_env(unsigned int *out_flags, bool use_memfd) {
+    const HugepageConfig config = HugepageConfig::FromEnvironment();
+    if (!config.enabled) {
+        return 0;
+    }
+
+    const size_t size = config.page_size;
+    if (out_flags == nullptr) {
+        return size;
+    }
+    if (use_memfd) {
+        *out_flags |= MFD_HUGETLB;
+        *out_flags |= size == SZ_2MB     ? MFD_HUGE_2MB
+                      : size == SZ_512MB ? MFD_HUGE_512MB
+                                         : MFD_HUGE_1GB;
+    } else {
+        *out_flags |= MAP_HUGETLB;
+        *out_flags |= size == SZ_2MB     ? MAP_HUGE_2MB
+                      : size == SZ_512MB ? MAP_HUGE_512MB
+                                         : MAP_HUGE_1GB;
+    }
+    LOG(INFO) << "Using hugepage size: "
+              << (size == SZ_2MB     ? "2MB"
+                  : size == SZ_512MB ? "512MB"
+                                     : "1GB");
+    return size;
+}
+
+void *allocate_buffer_allocator_memory(size_t total_size,
+                                       const std::string &protocol,
+                                       size_t alignment, bool use_spdk_dma) {
+    const size_t default_alignment = facebook::cachelib::Slab::kSize;
+    // Ensure total_size is a multiple of alignment
+    if (alignment == default_alignment && total_size < alignment) {
+        LOG(ERROR) << "Total size must be at least " << alignment;
+        return nullptr;
+    }
+#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
+    if (protocol == "ascend" || protocol == "ubshmem") {
+        return ascend_allocate_memory(total_size, protocol);
+    }
+#endif
+#if defined(USE_SUNRISE)
+    if (protocol == "sunrise_link") {
+        return sunrise_allocate_memory(
+            total_size, alignment,
+            mooncake::globalConfig().sunrise_use_device_mem);
+    }
+#endif
+#if defined(USE_UB)
+    if (protocol == "ub") {
+        return mooncake::ub_allocate_memory(alignment, total_size);
+    }
+#endif
+#ifdef USE_NOF
+    if (use_spdk_dma && total_size > 0) {
+        return mooncake::SpdkWrapper::GetInstance().Alloc(total_size, alignment,
+                                                          -1);
+    }
+#endif
+#ifdef USE_VRAM_SEGMENT
+    auto ret = allocate_vram_memory(total_size, protocol);
+    if (!ret) {
+        LOG(ERROR) << ret.error();
+        return nullptr;
+    }
+    return *ret;
+#endif
+    // Allocate aligned memory
+    return aligned_alloc(alignment, total_size);
+}
+
+void free_memory(const std::string &protocol, void *ptr, bool use_spdk_dma) {
+#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
+    if (protocol == "ascend" || protocol == "ubshmem") {
+        return ascend_free_memory(protocol, ptr);
+    }
+#endif
+#if defined(USE_SUNRISE)
+    if (protocol == "sunrise_link") {
+        return sunrise_free_memory(ptr);
+    }
+#endif
+#if defined(USE_UB)
+    if (protocol == "ub") {
+        mooncake::ub_free_memory(ptr);
+        return;
+    }
+#endif
+#ifdef USE_NOF
+    // Mirror allocate_buffer_allocator_memory(): a buffer taken from the SPDK
+    // hugepage pool (spdk_zmalloc) must be released with spdk_free, not glibc
+    // free(), which would abort with "free(): invalid pointer".
+    if (use_spdk_dma) {
+        mooncake::SpdkWrapper::GetInstance().Free(ptr);
+        return;
+    }
+#endif
+#ifdef USE_VRAM_SEGMENT
+#ifdef USE_INTRA_NVLINK
+    freeFabricMemory_intra(ptr);
+#else
+    cudaFree(ptr);
+#endif
+    return;
+#endif
+    free(ptr);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/utils/file_util.cpp b/mooncake-store/src/common/file_util.cpp
similarity index 79%
rename from mooncake-store/src/utils/file_util.cpp
rename to mooncake-store/src/common/file_util.cpp
index 019a2c5618..be10319982 100644
--- a/mooncake-store/src/utils/file_util.cpp
+++ b/mooncake-store/src/common/file_util.cpp
@@ -1,12 +1,26 @@
-#include "utils/file_util.h"
+#include "common/file_util.h"
 #include <algorithm>
 #include <filesystem>
 #include <fstream>
+#include <functional>
 #include <limits>
+#include <string_view>
 
 namespace mooncake {
 namespace {
 
+std::string SanitizeKey(const std::string &key) {
+    constexpr std::string_view kInvalidChars = "/\\:*?\"<>|";
+    std::string sanitized_key;
+    sanitized_key.reserve(key.size());
+    for (char c : key) {
+        const bool invalid =
+            c == '\0' || kInvalidChars.find(c) != std::string_view::npos;
+        sanitized_key.push_back(invalid ? '_' : c);
+    }
+    return sanitized_key;
+}
+
 constexpr std::size_t kDefaultChunkSize = 64ull * 1024 * 1024;  // 64 MB
 
 tl::expected<void, std::string> PrepareOutputFile(const std::string &file_path,
@@ -51,6 +65,20 @@ tl::expected<void, std::string> WriteChunks(std::ofstream &file,
 
 }  // namespace
 
+std::string FileUtil::ResolvePathFromKey(const std::string &key,
+                                         const std::string &root_dir,
+                                         const std::string &fsdir) {
+    const size_t hash = std::hash<std::string>{}(key);
+    const char dir1 = static_cast<char>('a' + (hash & 0x0F));
+    const char dir2 = static_cast<char>('a' + ((hash >> 4) & 0x0F));
+    const std::filesystem::path dir_path =
+        std::filesystem::path(std::string(1, dir1)) / std::string(1, dir2);
+    return (std::filesystem::path(root_dir) / fsdir / dir_path /
+            SanitizeKey(key))
+        .lexically_normal()
+        .string();
+}
+
 tl::expected<void, std::string> FileUtil::SaveStringToFile(
     const std::string &content, const std::string &file_path) {
     try {
diff --git a/mooncake-store/src/common/mmap_buffer.cpp b/mooncake-store/src/common/mmap_buffer.cpp
new file mode 100644
index 0000000000..56df25ffa1
--- /dev/null
+++ b/mooncake-store/src/common/mmap_buffer.cpp
@@ -0,0 +1,368 @@
+#include "common/client_buffer_allocation.h"
+
+#include "config/hugepage_config.h"
+#include "config/mmap_arena_config.h"
+#include "mmap_arena.h"
+
+#include <algorithm>
+#include <atomic>
+#include <cerrno>
+#include <cstring>
+#include <memory>
+#include <mutex>
+#include <numa.h>
+#include <numaif.h>
+#include <sys/mman.h>
+#include <thread>
+#include <unistd.h>
+#include <vector>
+
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+
+DEFINE_bool(use_mmap_arena_allocator, false,
+            "Enable the lock-free mmap arena allocator for mmap buffers");
+DEFINE_uint64(mmap_arena_pool_size, 8ULL * 1024 * 1024 * 1024,
+              "Arena allocator pool size in bytes");
+
+namespace mooncake {
+
+// Global arena instance (lazy initialization)
+static std::unique_ptr<MmapArena> g_mmap_arena;
+static std::once_flag g_arena_init_flag;
+static std::atomic<uint64_t> g_arena_oom_fallback_count{0};
+static std::atomic<uint64_t> g_arena_noop_free_count{0};
+
+static void initializeGlobalArena() {
+    const MmapArenaConfig config = MmapArenaConfig::FromEnvironment(
+        FLAGS_use_mmap_arena_allocator, FLAGS_mmap_arena_pool_size);
+    if (!config.enabled) {
+        return;
+    }
+
+    g_mmap_arena = std::make_unique<MmapArena>();
+
+    bool success =
+        g_mmap_arena->initialize(config.pool_size, MmapArena::kMinAlignment,
+                                 !config.hugepages_explicitly_requested);
+
+    if (success) {
+        auto stats = g_mmap_arena->getStats();
+        LOG(INFO) << "=== ARENA ALLOCATOR ENABLED ===";
+        LOG(INFO) << "Arena pool size: " << (stats.pool_size / BYTES_PER_GIB)
+                  << " GiB";
+        LOG(INFO) << "Using lock-free atomic bump allocation";
+    } else {
+        LOG(ERROR) << "=== ARENA INITIALIZATION FAILED ===";
+        LOG(ERROR) << "Falling back to traditional mmap()";
+        if (config.hugepages_explicitly_requested) {
+            LOG(ERROR) << "MC_STORE_USE_HUGEPAGE is set, so the fallback path "
+                          "will also require hugepages";
+        }
+        LOG(ERROR) << "Arena initialization is only attempted once per "
+                      "process; restart after fixing the environment if you "
+                      "want to retry arena bring-up";
+        g_mmap_arena.reset();
+    }
+}
+
+// Compute the mmap/munmap size for the fallback (non-arena) path.
+// Used by both allocate_buffer_mmap_memory and free_buffer_mmap_memory
+// so they agree on the mapping size.
+static inline size_t mmap_map_size(size_t total_size, size_t hugepage_size) {
+    const size_t page_size =
+        hugepage_size > 0 ? hugepage_size : static_cast<size_t>(getpagesize());
+    return align_up(total_size, page_size);
+}
+
+namespace {
+
+size_t touch_thread_count(size_t page_count) {
+    const unsigned int hardware_threads = std::thread::hardware_concurrency();
+    const size_t available_threads =
+        hardware_threads == 0 ? 1 : std::min<size_t>(hardware_threads, 16);
+    return std::min(available_threads, page_count);
+}
+
+void touch_page_range(volatile char *data, size_t page_size, size_t begin_page,
+                      size_t end_page, int numa_node) {
+    if (numa_node >= 0 && numa_run_on_node(numa_node) != 0) {
+        LOG(WARNING) << "Failed to bind HugeTLB population worker to NUMA node "
+                     << numa_node << ": " << std::strerror(errno);
+    }
+    for (size_t page = begin_page; page < end_page; ++page) {
+        data[page * page_size] = 0;
+    }
+}
+
+void touch_mmap_pages(void *ptr, size_t map_size, size_t page_size) {
+    if (ptr == nullptr || map_size == 0 || page_size == 0) {
+        return;
+    }
+
+    const size_t page_count = (map_size + page_size - 1) / page_size;
+    const size_t num_threads = touch_thread_count(page_count);
+
+    auto *data = static_cast<volatile char *>(ptr);
+    if (num_threads <= 1) {
+        touch_page_range(data, page_size, 0, page_count, -1);
+        return;
+    }
+
+    std::vector<std::jthread> threads;
+    threads.reserve(num_threads);
+    const size_t pages_per_thread =
+        (page_count + num_threads - 1) / num_threads;
+    for (size_t thread_index = 0; thread_index < num_threads; ++thread_index) {
+        const size_t begin_page = thread_index * pages_per_thread;
+        const size_t end_page =
+            std::min(begin_page + pages_per_thread, page_count);
+        if (begin_page >= end_page) {
+            break;
+        }
+        threads.emplace_back(touch_page_range, data, page_size, begin_page,
+                             end_page, -1);
+    }
+}
+
+void touch_numa_mmap_pages(void *ptr, size_t map_size, size_t page_size,
+                           const std::vector<int> &numa_nodes) {
+    if (ptr == nullptr || map_size == 0 || page_size == 0 ||
+        numa_nodes.empty()) {
+        return;
+    }
+
+    const size_t node_count = numa_nodes.size();
+    if (map_size % node_count != 0 ||
+        (map_size / node_count) % page_size != 0) {
+        LOG(ERROR) << "Invalid NUMA HugeTLB mapping layout: size=" << map_size
+                   << ", page_size=" << page_size << ", nodes=" << node_count;
+        return;
+    }
+
+    const size_t region_size = map_size / node_count;
+    const size_t pages_per_region = region_size / page_size;
+    const size_t page_count = pages_per_region * node_count;
+    const size_t num_threads =
+        std::max(node_count, touch_thread_count(page_count));
+    const size_t base_threads_per_node = num_threads / node_count;
+    const size_t extra_threads = num_threads % node_count;
+
+    auto *data = static_cast<volatile char *>(ptr);
+    std::vector<std::jthread> threads;
+    threads.reserve(num_threads);
+    for (size_t node_index = 0; node_index < node_count; ++node_index) {
+        const size_t node_threads =
+            base_threads_per_node + (node_index < extra_threads ? 1 : 0);
+        const size_t pages_per_thread =
+            (pages_per_region + node_threads - 1) / node_threads;
+        const size_t region_begin_page = node_index * pages_per_region;
+        for (size_t thread_index = 0; thread_index < node_threads;
+             ++thread_index) {
+            const size_t begin_page =
+                region_begin_page + thread_index * pages_per_thread;
+            const size_t end_page =
+                std::min(begin_page + pages_per_thread,
+                         region_begin_page + pages_per_region);
+            if (begin_page >= end_page) {
+                continue;
+            }
+            threads.emplace_back(touch_page_range, data, page_size, begin_page,
+                                 end_page, numa_nodes[node_index]);
+        }
+    }
+}
+
+}  // namespace
+
+void populate_hugetlb_mapping(void *ptr, size_t total_size) {
+    const size_t hugepage_size = get_hugepage_size_from_env();
+    if (ptr == nullptr || total_size == 0 || hugepage_size == 0) {
+        return;
+    }
+
+    touch_mmap_pages(ptr, mmap_map_size(total_size, hugepage_size),
+                     hugepage_size);
+}
+
+void populate_hugetlb_numa_mapping(void *ptr, size_t total_size,
+                                   const std::vector<int> &numa_nodes) {
+    const size_t hugepage_size = get_hugepage_size_from_env();
+    if (ptr == nullptr || total_size == 0 || hugepage_size == 0 ||
+        numa_nodes.empty()) {
+        return;
+    }
+
+    touch_numa_mmap_pages(ptr, total_size, hugepage_size, numa_nodes);
+}
+
+void *allocate_buffer_mmap_memory(size_t total_size, size_t alignment) {
+    return allocate_buffer_mmap_memory(total_size, alignment, false);
+}
+
+void *allocate_buffer_mmap_memory(size_t total_size, size_t alignment,
+                                  bool defer_hugetlb_population) {
+    if (total_size == 0) {
+        LOG(ERROR) << "Total size must be greater than 0 for mmap";
+        return nullptr;
+    }
+
+    // Initialize arena on first call
+    std::call_once(g_arena_init_flag, initializeGlobalArena);
+
+    // Try arena allocation first (if enabled).
+    // Forward caller's alignment so the arena honors the contract.
+    if (g_mmap_arena && g_mmap_arena->isInitialized()) {
+        void *ptr = g_mmap_arena->allocate(total_size, alignment);
+        if (ptr != nullptr) {
+            VLOG(1) << "Allocated " << total_size << " bytes from arena at "
+                    << ptr;
+            return ptr;
+        }
+        // Arena OOM, fall through to traditional mmap
+        const uint64_t fallback_count =
+            g_arena_oom_fallback_count.fetch_add(1, std::memory_order_relaxed) +
+            1;
+        LOG_FIRST_N(WARNING, 3)
+            << "Arena OOM, falling back to mmap() for size=" << total_size
+            << " (count=" << fallback_count << ")"
+            << " (further warnings suppressed)";
+    }
+
+    // Traditional mmap allocation (fallback or arena disabled).
+    const bool defer_direct_population =
+        defer_hugetlb_population && HugepageConfig::FromEnvironment().enabled;
+    unsigned int flags = MAP_PRIVATE | MAP_ANONYMOUS;
+    if (!defer_direct_population) {
+        flags |= MAP_POPULATE;
+    }
+    const size_t hugepage_size = get_hugepage_size_from_env(&flags);
+    const size_t map_size = mmap_map_size(total_size, hugepage_size);
+    const size_t guaranteed_alignment =
+        hugepage_size > 0 ? hugepage_size : static_cast<size_t>(getpagesize());
+    if (alignment > guaranteed_alignment) {
+        LOG_FIRST_N(WARNING, 3)
+            << "Fallback mmap cannot honor alignment=" << alignment
+            << " (guaranteed=" << guaranteed_alignment
+            << "); pointer may be under-aligned"
+            << " (further warnings suppressed)";
+    }
+
+    void *ptr = mmap(nullptr, map_size, PROT_READ | PROT_WRITE, flags, -1, 0);
+    if (ptr == MAP_FAILED) {
+        LOG(ERROR) << "mmap failed, size=" << map_size << ", errno=" << errno
+                   << " (" << strerror(errno) << ")";
+        return nullptr;
+    }
+
+    VLOG(1) << "Allocated " << total_size << " bytes via mmap() at " << ptr;
+    return ptr;
+}
+
+bool is_mmap_arena_allocation(const void *ptr) {
+    return ptr != nullptr && g_mmap_arena && g_mmap_arena->isInitialized() &&
+           g_mmap_arena->owns(ptr);
+}
+
+void free_buffer_mmap_memory(void *ptr, size_t total_size) {
+    if (!ptr || total_size == 0) {
+        return;
+    }
+
+    // Check if pointer belongs to global arena
+    std::call_once(g_arena_init_flag, initializeGlobalArena);
+
+    if (g_mmap_arena && g_mmap_arena->owns(ptr)) {
+        const uint64_t noop_free_count =
+            g_arena_noop_free_count.fetch_add(1, std::memory_order_relaxed) + 1;
+        LOG_FIRST_N(WARNING, 3)
+            << "free_buffer_mmap_memory() does not individually release "
+               "arena-owned pointer "
+            << ptr << "; the global arena releases its pool at process shutdown"
+            << " (count=" << noop_free_count << ")"
+            << " (further warnings suppressed)";
+        return;
+    }
+
+    // Direct mmap allocation - safe to unmap
+    const size_t map_size =
+        mmap_map_size(total_size, get_hugepage_size_from_env());
+    if (munmap(ptr, map_size) != 0) {
+        LOG(ERROR) << "munmap hugepage failed, size=" << map_size
+                   << ", errno=" << errno << " (" << strerror(errno) << ")";
+    } else {
+        VLOG(1) << "Freed direct mmap allocation at " << ptr
+                << ", size=" << map_size;
+    }
+}
+
+// NUMA-segmented buffer allocation
+void *allocate_buffer_numa_segments(size_t total_size,
+                                    const std::vector<int> &numa_nodes,
+                                    size_t page_size) {
+    if (total_size == 0 || numa_nodes.empty()) {
+        LOG(ERROR) << "Invalid params: total_size=" << total_size
+                   << " numa_nodes.size=" << numa_nodes.size();
+        return nullptr;
+    }
+
+    if (page_size == 0) page_size = getpagesize();
+    size_t n = numa_nodes.size();
+    size_t region_size = align_up(total_size / n, page_size);
+    size_t map_size = region_size * n;
+
+    // reserve contiguous VMA; use hugepages if page_size indicates so
+    unsigned int flags = MAP_PRIVATE | MAP_ANONYMOUS;
+    if (page_size == SZ_2MB) {
+        flags |= MAP_HUGETLB | MAP_HUGE_2MB;
+    } else if (page_size == SZ_512MB) {
+        flags |= MAP_HUGETLB | MAP_HUGE_512MB;
+    } else if (page_size == SZ_1GB) {
+        flags |= MAP_HUGETLB | MAP_HUGE_1GB;
+    } else if (page_size != static_cast<size_t>(getpagesize())) {
+        flags |= MAP_HUGETLB;
+    }
+    void *ptr = mmap(nullptr, map_size, PROT_READ | PROT_WRITE, flags, -1, 0);
+    if (ptr == MAP_FAILED) {
+        LOG(ERROR) << "mmap failed (hugepage="
+                   << ((flags & MAP_HUGETLB) ? "yes" : "no")
+                   << "), size=" << map_size << ", errno=" << errno << " ("
+                   << strerror(errno) << ")";
+        return nullptr;
+    }
+
+    // bind each region to its NUMA node
+    int max_node = numa_num_possible_nodes();
+    for (size_t i = 0; i < n; ++i) {
+        struct bitmask *mask = numa_bitmask_alloc(max_node);
+        numa_bitmask_setbit(mask, numa_nodes[i]);
+        char *region = static_cast<char *>(ptr) + i * region_size;
+        long rc =
+            mbind(region, region_size, MPOL_BIND, mask->maskp, mask->size, 0);
+        numa_bitmask_free(mask);
+        if (rc != 0) {
+            LOG(ERROR) << "mbind failed for NUMA " << numa_nodes[i]
+                       << ", errno=" << errno << " (" << strerror(errno) << ")";
+            munmap(ptr, map_size);
+            return nullptr;
+        }
+    }
+
+    // Leave the mapping lazy. The caller may explicitly populate it with
+    // NUMA-local workers before registration; otherwise ibv_reg_mr() calls
+    // get_user_pages(), whose faults respect the mbind policy.
+
+    LOG(INFO) << "Allocated NUMA-segmented buffer: " << map_size << " bytes, "
+              << n << " regions, page_size=" << page_size << ", nodes=[" <<
+        [&]() {
+            std::string s;
+            for (size_t i = 0; i < n; ++i) {
+                if (i) s += ",";
+                s += std::to_string(numa_nodes[i]);
+            }
+            return s;
+        }() << "]";
+    return ptr;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/common/network.cpp b/mooncake-store/src/common/network.cpp
new file mode 100644
index 0000000000..10483b1501
--- /dev/null
+++ b/mooncake-store/src/common/network.cpp
@@ -0,0 +1,187 @@
+#include "common/network.h"
+
+#include "random.h"
+
+#include <cerrno>
+#include <cstring>
+#include <ifaddrs.h>
+#include <memory>
+#include <net/if.h>
+#include <netdb.h>
+#include <netinet/in.h>
+#include <sys/socket.h>
+#include <unistd.h>
+#include <vector>
+
+#include <ylt/coro_http/coro_http_client.hpp>
+
+namespace mooncake {
+
+bool isPortAvailable(int port) {
+    int sock = socket(AF_INET, SOCK_STREAM, 0);
+    if (sock < 0) return false;
+
+    int opt = 1;
+    setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
+
+    struct sockaddr_in addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = INADDR_ANY;
+    addr.sin_port = htons(port);
+
+    bool available = (bind(sock, (struct sockaddr *)&addr, sizeof(addr)) == 0);
+    close(sock);
+    return available;
+}
+
+// AutoPortBinder implementation
+AutoPortBinder::AutoPortBinder(int min_port, int max_port)
+    : socket_fd_(-1), port_(-1) {
+    for (int attempt = 0; attempt < 20; ++attempt) {
+        int port = randomUniform(min_port, max_port);
+
+        socket_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (socket_fd_ < 0) continue;
+
+        sockaddr_in addr = {};
+        addr.sin_family = AF_INET;
+        addr.sin_addr.s_addr = INADDR_ANY;
+        addr.sin_port = htons(port);
+
+        if (bind(socket_fd_, (sockaddr *)&addr, sizeof(addr)) == 0) {
+            port_ = port;
+            break;
+        } else {
+            close(socket_fd_);
+            socket_fd_ = -1;
+        }
+    }
+}
+
+AutoPortBinder::~AutoPortBinder() {
+    if (socket_fd_ >= 0) {
+        close(socket_fd_);
+    }
+}
+
+tl::expected<std::string, int> httpGet(const std::string &url) {
+    coro_http::coro_http_client client;
+    auto res = client.get(url);
+    if (res.status == 200) {
+        return std::string(res.resp_body);
+    }
+    return tl::unexpected(res.status);
+}
+
+tl::expected<std::string, std::string> GetInterfaceIPv4Address(
+    const std::string &interface_name) {
+    if (interface_name.empty()) {
+        return tl::unexpected(std::string("network interface name is empty"));
+    }
+
+    struct ifaddrs *interfaces = nullptr;
+    if (getifaddrs(&interfaces) != 0) {
+        return tl::unexpected("getifaddrs failed: " +
+                              std::string(strerror(errno)));
+    }
+    std::unique_ptr<struct ifaddrs, decltype(&freeifaddrs)> interface_guard(
+        interfaces, freeifaddrs);
+
+    bool found_interface = false;
+    bool interface_is_up = false;
+    for (auto *current = interfaces; current != nullptr;
+         current = current->ifa_next) {
+        if (current->ifa_name == nullptr ||
+            interface_name != current->ifa_name) {
+            continue;
+        }
+
+        found_interface = true;
+        if ((current->ifa_flags & IFF_UP) == 0) {
+            continue;
+        }
+        interface_is_up = true;
+
+        if (current->ifa_addr == nullptr ||
+            current->ifa_addr->sa_family != AF_INET) {
+            continue;
+        }
+
+        char host[NI_MAXHOST] = {};
+        auto *ipv4_addr = reinterpret_cast<sockaddr_in *>(current->ifa_addr);
+        if (getnameinfo(reinterpret_cast<sockaddr *>(ipv4_addr),
+                        sizeof(*ipv4_addr), host, sizeof(host), nullptr, 0,
+                        NI_NUMERICHOST) == 0) {
+            return std::string(host);
+        }
+    }
+
+    if (!found_interface) {
+        return tl::unexpected("network interface '" + interface_name +
+                              "' was not found");
+    }
+    if (!interface_is_up) {
+        return tl::unexpected("network interface '" + interface_name +
+                              "' is down");
+    }
+    return tl::unexpected("network interface '" + interface_name +
+                          "' has no IPv4 address");
+}
+
+int getFreeTcpPort() {
+    int sock = ::socket(AF_INET, SOCK_STREAM, 0);
+    if (sock < 0) return -1;
+    sockaddr_in addr{};
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    addr.sin_port = htons(0);
+    if (::bind(sock, reinterpret_cast<sockaddr *>(&addr), sizeof(addr)) != 0) {
+        ::close(sock);
+        return -1;
+    }
+    socklen_t len = sizeof(addr);
+    if (::getsockname(sock, reinterpret_cast<sockaddr *>(&addr), &len) != 0) {
+        ::close(sock);
+        return -1;
+    }
+    int port = ntohs(addr.sin_port);
+    ::close(sock);
+    return port;
+}
+
+std::vector<int> getFreeTcpPorts(int count) {
+    std::vector<int> ports;
+    std::vector<int> sockets;
+    ports.reserve(count);
+    sockets.reserve(count);
+
+    for (int i = 0; i < count; ++i) {
+        int sock = ::socket(AF_INET, SOCK_STREAM, 0);
+        if (sock < 0) break;
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        addr.sin_port = htons(0);
+        if (::bind(sock, reinterpret_cast<sockaddr *>(&addr), sizeof(addr)) !=
+            0) {
+            ::close(sock);
+            break;
+        }
+        socklen_t len = sizeof(addr);
+        if (::getsockname(sock, reinterpret_cast<sockaddr *>(&addr), &len) !=
+            0) {
+            ::close(sock);
+            break;
+        }
+        ports.push_back(ntohs(addr.sin_port));
+        sockets.push_back(sock);
+    }
+
+    for (int sock : sockets) {
+        ::close(sock);
+    }
+    return ports;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/utils/s3_helper.cpp b/mooncake-store/src/common/s3_helper.cpp
similarity index 87%
rename from mooncake-store/src/utils/s3_helper.cpp
rename to mooncake-store/src/common/s3_helper.cpp
index fd2f9ead24..642d9a48ce 100644
--- a/mooncake-store/src/utils/s3_helper.cpp
+++ b/mooncake-store/src/common/s3_helper.cpp
@@ -1,4 +1,4 @@
-#include "utils/s3_helper.h"
+#include "common/s3_helper.h"
 
 #include <aws/s3/model/PutObjectRequest.h>
 #include <aws/s3/model/GetObjectRequest.h>
@@ -26,15 +26,24 @@
 #include <aws/s3/model/CreateMultipartUploadRequest.h>
 #include <aws/s3/model/CompleteMultipartUploadRequest.h>
 #include <aws/s3/model/AbortMultipartUploadRequest.h>
+#include <aws/s3/model/ChecksumAlgorithm.h>
+#include <aws/s3/model/ChecksumType.h>
 #include <aws/s3/model/UploadPartRequest.h>
 #include <aws/core/client/ClientConfiguration.h>
-#include "environ.h"
+#include "crc32c.h"
 #include "fmt/format.h"
+#include "common/base64.h"
+#include "config/s3_client_config.h"
 
 namespace mooncake {
 
 namespace {
 
+const S3ClientConfig &GetS3ClientConfig() {
+    static const S3ClientConfig config = S3ClientConfig::FromEnvironment();
+    return config;
+}
+
 // Parse a checksum-mode string ("when_supported" | "when_required") into the
 // AWS SDK enum. Returns std::nullopt when the value is unset or invalid — the
 // caller should then leave the AWS SDK's default in place. This is purely
@@ -53,6 +62,15 @@ std::optional<T> ParseChecksumMode(const std::string &value) {
     return std::nullopt;
 }
 
+std::string EncodeCrc32c(uint32_t checksum) {
+    std::string bytes(sizeof(checksum), '\0');
+    bytes[0] = static_cast<char>(checksum >> 24);
+    bytes[1] = static_cast<char>(checksum >> 16);
+    bytes[2] = static_cast<char>(checksum >> 8);
+    bytes[3] = static_cast<char>(checksum);
+    return base64::Encode(bytes);
+}
+
 }  // namespace
 
 bool S3Helper::aws_initialized = false;
@@ -63,10 +81,8 @@ void S3Helper::InitAPI() {
     Aws::InitAPI(options_);
     aws_initialized = true;
 
-    // Force Environ initialization so all MOONCAKE_AWS_* env vars are read
-    // once during startup, matching the previous "read once at InitAPI"
-    // behavior.
-    (void)Environ::Get();
+    // Cache all MOONCAKE_AWS_* settings once during startup.
+    (void)GetS3ClientConfig();
 }
 
 void S3Helper::ShutdownAPI() {
@@ -78,43 +94,43 @@ void S3Helper::ShutdownAPI() {
 
 S3Helper::S3Helper(const std::string &endpoint, const std::string &bucket,
                    const std::string &region) {
-    const auto &env = Environ::Get();
+    const auto &env = GetS3ClientConfig();
     Aws::Client::ClientConfiguration config(true);
 
-    config.connectTimeoutMs = env.GetAwsConnectTimeoutMs();
-    config.requestTimeoutMs = env.GetAwsRequestTimeoutMs();
-    config.scheme = env.GetAwsUseHttps() ? Aws::Http::Scheme::HTTPS
-                                         : Aws::Http::Scheme::HTTP;
+    config.connectTimeoutMs = static_cast<long>(env.connect_timeout.count());
+    config.requestTimeoutMs = static_cast<long>(env.request_timeout.count());
+    config.scheme =
+        env.use_https ? Aws::Http::Scheme::HTTPS : Aws::Http::Scheme::HTTP;
     if (auto request_checksum =
             ParseChecksumMode<Aws::Client::RequestChecksumCalculation>(
-                env.GetAwsRequestChecksumCalculation())) {
+                env.request_checksum_calculation)) {
         config.checksumConfig.requestChecksumCalculation = *request_checksum;
     }
     if (auto response_checksum =
             ParseChecksumMode<Aws::Client::ResponseChecksumValidation>(
-                env.GetAwsResponseChecksumValidation())) {
+                env.response_checksum_validation)) {
         config.checksumConfig.responseChecksumValidation = *response_checksum;
     }
 
     if (!region.empty()) {
         config.region = region;
     } else {
-        config.region = env.GetAwsRegion();
+        config.region = env.region;
     }
 
     if (!endpoint.empty()) {
         config.endpointOverride = endpoint;
     } else {
-        config.endpointOverride = env.GetAwsS3Endpoint();
+        config.endpointOverride = env.s3_endpoint;
     }
 
-    bucket_ = env.GetAwsBucketName();
+    bucket_ = env.bucket_name;
     if (!bucket.empty()) {
         bucket_ = bucket;
     }
 
-    Aws::Auth::AWSCredentials credentials(env.GetAwsAccessKeyId(),
-                                          env.GetAwsSecretAccessKey());
+    Aws::Auth::AWSCredentials credentials(env.access_key_id,
+                                          env.secret_access_key);
 
     // Concatenate log information into member variable connection_info_
     connection_info_ = fmt::format(
@@ -132,14 +148,14 @@ S3Helper::S3Helper(const std::string &endpoint, const std::string &bucket,
         bucket_.empty() ? "unset" : bucket_, config.connectTimeoutMs,
         config.requestTimeoutMs,
         config.scheme == Aws::Http::Scheme::HTTPS ? "HTTPS" : "HTTP",
-        !env.GetAwsAccessKeyId().empty() ? "set" : "unset",
-        !env.GetAwsSecretAccessKey().empty() ? "set" : "unset",
-        env.GetAwsUseVirtualAddressing() ? "true" : "false");
+        !env.access_key_id.empty() ? "set" : "unset",
+        !env.secret_access_key.empty() ? "set" : "unset",
+        env.use_virtual_addressing ? "true" : "false");
 
     s3_client_ = Aws::S3::S3Client(
         credentials, config,
         Aws::Client::AWSAuthV4Signer::PayloadSigningPolicy::Never,
-        env.GetAwsUseVirtualAddressing());
+        env.use_virtual_addressing);
 }
 
 S3Helper::~S3Helper() = default;
@@ -157,6 +173,8 @@ tl::expected<void, std::string> S3Helper::UploadBuffer(
 
     // Set ContentLength correctly (using long long type)
     request.SetContentLength(static_cast<long long>(buffer.size()));
+    request.SetChecksumCRC32C(
+        EncodeCrc32c(Crc32cValue(buffer.data(), buffer.size())));
     const auto buffer_size = static_cast<std::streamsize>(buffer.size());
 
     // Create and write to stream
@@ -178,6 +196,8 @@ tl::expected<void, std::string> S3Helper::UploadString(
     request.SetBucket(bucket_.c_str());
     request.SetKey(key.c_str());
     request.SetContentLength(static_cast<long long>(data.size()));
+    request.SetChecksumCRC32C(
+        EncodeCrc32c(Crc32cValue(data.data(), data.size())));
 
     auto stream = Aws::MakeShared<Aws::StringStream>("UploadString");
     stream->write(data.data(), data.size());
@@ -191,6 +211,50 @@ tl::expected<void, std::string> S3Helper::UploadString(
     return {};
 }
 
+tl::expected<void, std::string> S3Helper::InspectObject(
+    const std::string &key, uint64_t &stored_size,
+    std::optional<uint32_t> &crc32c) {
+    Aws::S3::Model::HeadObjectRequest request;
+    request.SetBucket(bucket_.c_str());
+    request.SetKey(key.c_str());
+    request.SetChecksumMode(Aws::S3::Model::ChecksumMode::ENABLED);
+
+    auto outcome = s3_client_.HeadObject(request);
+    if (!outcome.IsSuccess()) {
+        return tl::make_unexpected(fmt::format(
+            "HeadObject failed: {}", outcome.GetError().GetMessage()));
+    }
+    const auto content_length = outcome.GetResult().GetContentLength();
+    if (content_length < 0) {
+        return tl::make_unexpected(
+            fmt::format("Invalid content length: {}", content_length));
+    }
+    stored_size = static_cast<uint64_t>(content_length);
+    crc32c.reset();
+
+    if (outcome.GetResult().GetChecksumType() !=
+        Aws::S3::Model::ChecksumType::FULL_OBJECT) {
+        return {};
+    }
+
+    const std::string encoded = outcome.GetResult().GetChecksumCRC32C();
+    const std::string decoded = base64::Decode(encoded);
+    if (!encoded.empty()) {
+        if (decoded.size() != sizeof(uint32_t) ||
+            base64::Encode(decoded) != encoded) {
+            return tl::make_unexpected("Invalid full-object CRC32C metadata");
+        }
+        crc32c = (static_cast<uint32_t>(static_cast<unsigned char>(decoded[0]))
+                  << 24) |
+                 (static_cast<uint32_t>(static_cast<unsigned char>(decoded[1]))
+                  << 16) |
+                 (static_cast<uint32_t>(static_cast<unsigned char>(decoded[2]))
+                  << 8) |
+                 static_cast<uint32_t>(static_cast<unsigned char>(decoded[3]));
+    }
+    return {};
+}
+
 tl::expected<void, std::string> S3Helper::DownloadBuffer(
     const std::string &key, std::vector<uint8_t> &buffer) {
     Aws::S3::Model::GetObjectRequest request;
@@ -444,6 +508,9 @@ tl::expected<void, std::string> S3Helper::UploadBufferMultipart(
     Aws::S3::Model::CreateMultipartUploadRequest create_request;
     create_request.SetBucket(bucket_.c_str());
     create_request.SetKey(key.c_str());
+    create_request.SetChecksumAlgorithm(
+        Aws::S3::Model::ChecksumAlgorithm::CRC32C);
+    create_request.SetChecksumType(Aws::S3::Model::ChecksumType::FULL_OBJECT);
 
     auto create_outcome = s3_client_.CreateMultipartUpload(create_request);
     if (!create_outcome.IsSuccess()) {
@@ -489,6 +556,8 @@ tl::expected<void, std::string> S3Helper::UploadBufferMultipart(
 
                 // Use original buffer pointer directly, avoid copying
                 const uint8_t *part_data = buffer.data() + offset;
+                const std::string part_crc32c =
+                    EncodeCrc32c(Crc32cValue(part_data, current_part_size));
 
                 // Add retry logic
                 const int max_retries = 2;
@@ -503,6 +572,7 @@ tl::expected<void, std::string> S3Helper::UploadBufferMultipart(
                     part_request.SetPartNumber(static_cast<int>(part_num));
                     part_request.SetContentLength(
                         static_cast<long long>(current_part_size));
+                    part_request.SetChecksumCRC32C(part_crc32c);
 
                     // Use temporary stream
                     auto stream =
@@ -598,6 +668,10 @@ tl::expected<void, std::string> S3Helper::UploadBufferMultipart(
     complete_request.SetBucket(bucket_.c_str());
     complete_request.SetKey(key.c_str());
     complete_request.SetUploadId(upload_id);
+    complete_request.SetChecksumCRC32C(
+        EncodeCrc32c(Crc32cValue(buffer.data(), buffer.size())));
+    complete_request.SetChecksumType(Aws::S3::Model::ChecksumType::FULL_OBJECT);
+    complete_request.SetMpuObjectSize(static_cast<long long>(total_size));
 
     Aws::S3::Model::CompletedMultipartUpload completed_upload;
 
diff --git a/mooncake-store/src/config/bucket_backend_config.cpp b/mooncake-store/src/config/bucket_backend_config.cpp
new file mode 100644
index 0000000000..4417d596fc
--- /dev/null
+++ b/mooncake-store/src/config/bucket_backend_config.cpp
@@ -0,0 +1,64 @@
+#include "config/bucket_backend_config.h"
+
+#include <glog/logging.h>
+
+#include <string>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+bool BucketBackendConfig::Validate() const {
+    if (bucket_keys_limit <= 0) {
+        LOG(ERROR) << "BucketBackendConfig: bucket_keys_limit must > 0";
+        return false;
+    }
+    if (bucket_size_limit <= 0) {
+        LOG(ERROR) << "BucketBackendConfig: bucket_size_limit must > 0";
+        return false;
+    }
+    return true;
+}
+
+BucketBackendConfig BucketBackendConfig::FromEnvironment() {
+    BucketBackendConfig config;
+    using Variables = BucketBackendEnvironmentVariables;
+
+    config.bucket_keys_limit =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT,
+                        config.bucket_keys_limit);
+
+    config.bucket_size_limit =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES,
+                        config.bucket_size_limit);
+
+    config.max_total_size = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE,
+        Environ::ReadOr(Variables::MOONCAKE_BUCKET_MAX_TOTAL_SIZE,
+                        config.max_total_size));
+
+    config.max_physical_bytes =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES,
+                        config.max_physical_bytes);
+
+    config.disk_scan_cache_ms =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS,
+                        config.disk_scan_cache_ms);
+
+    const std::string policy = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY,
+        Environ::ReadOr(Variables::MOONCAKE_BUCKET_EVICTION_POLICY,
+                        std::string{"fifo"}));
+    if (policy == "fifo") {
+        config.eviction_policy = BucketEvictionPolicy::FIFO;
+    } else if (policy == "lru") {
+        config.eviction_policy = BucketEvictionPolicy::LRU;
+    } else {
+        config.eviction_policy = BucketEvictionPolicy::NONE;
+    }
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_auto_discovery_config.cpp b/mooncake-store/src/config/client_auto_discovery_config.cpp
new file mode 100644
index 0000000000..f1fb3bb33b
--- /dev/null
+++ b/mooncake-store/src/config/client_auto_discovery_config.cpp
@@ -0,0 +1,80 @@
+#include "client_auto_discovery_config.h"
+
+#include <optional>
+
+#include <boost/algorithm/string.hpp>
+#include <glog/logging.h>
+
+#include "ascii_string.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+ClientAutoDiscoveryConfig ClientAutoDiscoveryConfig::FromEnvironment(
+    std::string_view protocol, bool device_names_configured) {
+    using Variables = ClientAutoDiscoveryEnvironmentVariables;
+    ClientAutoDiscoveryConfig config;
+
+    const auto raw_auto_discover = Environ::Read(Variables::MC_MS_AUTO_DISC);
+    std::optional<bool> configured_auto_discover;
+    if (raw_auto_discover) {
+        try {
+            const int value = std::stoi(*raw_auto_discover);
+            if (value == 1) {
+                LOG(INFO) << "auto discovery set by env "
+                          << Variables::MC_MS_AUTO_DISC.name;
+                configured_auto_discover = true;
+            } else if (value == 0) {
+                LOG(INFO) << "auto discovery not set by env "
+                          << Variables::MC_MS_AUTO_DISC.name;
+                configured_auto_discover = false;
+            }
+        } catch (const std::exception&) {
+            // Preserve the legacy fallback for malformed and out-of-range
+            // values instead of propagating std::stoi failures.
+        }
+        if (!configured_auto_discover.has_value()) {
+            LOG(WARNING) << "invalid " << Variables::MC_MS_AUTO_DISC.name
+                         << " value: " << *raw_auto_discover
+                         << ", should be 0 or 1, using default: auto discovery "
+                            "not set";
+        }
+    }
+
+    if (configured_auto_discover.has_value()) {
+        config.enabled = *configured_auto_discover;
+    } else {
+        config.enabled = (protocol == "rdma" || protocol == "efa") &&
+                         !device_names_configured;
+        if (config.enabled) {
+            LOG(INFO) << "Set auto discovery ON by default for " << protocol
+                      << " protocol, since no device names provided";
+        }
+    }
+
+    return config;
+}
+
+void ClientAutoDiscoveryConfig::LoadFiltersFromEnvironment() {
+    using Variables = ClientAutoDiscoveryEnvironmentVariables;
+
+    const auto raw_filters = Environ::Read(Variables::MC_MS_FILTERS);
+    if (enabled) {
+        if (raw_filters) {
+            LOG(INFO) << "whitelist filters: " << *raw_filters;
+            boost::split(filters, *raw_filters, boost::is_any_of(","),
+                         boost::token_compress_off);
+            for (auto& filter : filters) {
+                filter = std::string(TrimAsciiWhitespace(filter));
+            }
+        }
+    } else if (raw_filters && !raw_filters->empty()) {
+        LOG(WARNING) << Variables::MC_MS_FILTERS.name
+                     << " is set but auto discovery is disabled; ignoring "
+                        "whitelist: "
+                     << *raw_filters;
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_auto_discovery_config.h b/mooncake-store/src/config/client_auto_discovery_config.h
new file mode 100644
index 0000000000..5331fa42a0
--- /dev/null
+++ b/mooncake-store/src/config/client_auto_discovery_config.h
@@ -0,0 +1,21 @@
+#pragma once
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace mooncake {
+
+struct ClientAutoDiscoveryConfig {
+    bool enabled = false;
+    std::vector<std::string> filters;
+
+    static ClientAutoDiscoveryConfig FromEnvironment(
+        std::string_view protocol, bool device_names_configured);
+
+    // Filters are loaded after the enabled state is applied so the existing
+    // environment-read and diagnostic order remains unchanged.
+    void LoadFiltersFromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_auto_port_config.cpp b/mooncake-store/src/config/client_auto_port_config.cpp
new file mode 100644
index 0000000000..00f2dc3bab
--- /dev/null
+++ b/mooncake-store/src/config/client_auto_port_config.cpp
@@ -0,0 +1,27 @@
+#include "client_auto_port_config.h"
+
+#include "config.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+ClientAutoPortConfig ClientAutoPortConfig::FromEnvironment() {
+    ClientAutoPortConfig config;
+    using Variables = ClientAutoPortEnvironmentVariables;
+
+    config.max_retries = Environ::ReadOr(
+        Variables::MC_STORE_CLIENT_SETUP_RETRIES, config.max_retries);
+    const int raw_min_port =
+        Environ::ReadOr(Variables::MC_STORE_CLIENT_MIN_PORT, config.min_port);
+    const int raw_max_port =
+        Environ::ReadOr(Variables::MC_STORE_CLIENT_MAX_PORT, config.max_port);
+
+    const auto [min_port, max_port] = ValidatePortRange(
+        raw_min_port, raw_max_port, config.min_port, config.max_port);
+    config.min_port = min_port;
+    config.max_port = max_port;
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_host_identity_config.cpp b/mooncake-store/src/config/client_host_identity_config.cpp
new file mode 100644
index 0000000000..f07277a2c7
--- /dev/null
+++ b/mooncake-store/src/config/client_host_identity_config.cpp
@@ -0,0 +1,41 @@
+#include "client_host_identity_config.h"
+
+#include <string_view>
+
+#include "ascii_string.h"
+#include "common.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+bool IsUsableHostId(std::string_view host_id) {
+    return !host_id.empty() &&
+           !AsciiCaseInsensitiveEquals(host_id, "localhost") &&
+           host_id != "127.0.0.1" && host_id != "0.0.0.0" && host_id != "::1" &&
+           host_id != "[::1]" && host_id != "::" && host_id != "[::]";
+}
+
+std::string NormalizeHostId(std::string_view value) {
+    const std::string hostname(TrimAsciiWhitespace(value));
+    const std::string host_id = (hostname == "::1" || hostname == "::")
+                                    ? hostname
+                                    : std::string(TrimAsciiWhitespace(
+                                          getHostNameWithoutPort(hostname)));
+    return IsUsableHostId(host_id) ? host_id : "";
+}
+
+}  // namespace
+
+ClientHostIdentityConfig ClientHostIdentityConfig::FromEnvironment(
+    const std::string& local_hostname) {
+    const std::string configured_host_id(TrimAsciiWhitespace(
+        Environ::Read(ClientHostIdentityEnvironmentVariables::MOONCAKE_HOST_ID)
+            .value_or("")));
+    return {.host_id = NormalizeHostId(configured_host_id.empty()
+                                           ? local_hostname
+                                           : configured_host_id)};
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_host_identity_config.h b/mooncake-store/src/config/client_host_identity_config.h
new file mode 100644
index 0000000000..c38047171a
--- /dev/null
+++ b/mooncake-store/src/config/client_host_identity_config.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#include <string>
+
+namespace mooncake {
+
+struct ClientHostIdentityConfig {
+    std::string host_id;
+
+    static ClientHostIdentityConfig FromEnvironment(
+        const std::string& local_hostname);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_metric_config.cpp b/mooncake-store/src/config/client_metric_config.cpp
new file mode 100644
index 0000000000..b63d970d67
--- /dev/null
+++ b/mooncake-store/src/config/client_metric_config.cpp
@@ -0,0 +1,67 @@
+#include "client_metric.h"
+
+#include <glog/logging.h>
+#include <chrono>
+
+#include "bool_parser.h"
+#include "environ.h"
+#include "environment_variables.h"
+#include "integer_parser.h"
+
+namespace mooncake {
+
+ClientMetricConfig ClientMetricConfig::FromEnvironment() {
+    ClientMetricConfig config;
+    using Variables = ClientMetricEnvironmentVariables;
+
+    const auto enabled = Environ::Read(Variables::MC_STORE_CLIENT_METRIC);
+    if (enabled.has_value()) {
+        config.enabled = TryParseBool(*enabled).value_or(false);
+    }
+    if (!config.enabled) {
+        return config;
+    }
+
+    const auto interval =
+        Environ::Read(Variables::MC_STORE_CLIENT_METRIC_INTERVAL);
+    if (interval.has_value()) {
+        const auto parsed = TryParseInteger<uint64_t>(
+            *interval,
+            {.trim_ascii_whitespace = true, .allow_leading_plus = true});
+        if (!parsed.has_value()) {
+            LOG(WARNING) << "Failed to parse "
+                         << Variables::MC_STORE_CLIENT_METRIC_INTERVAL.name
+                         << ": " << *interval
+                         << ", disabling metrics reporting";
+        } else {
+            config.reporting_interval = std::chrono::seconds(*parsed);
+            if (*parsed == 0) {
+                LOG(INFO)
+                    << "Client metrics reporting disabled (interval=0) via "
+                    << Variables::MC_STORE_CLIENT_METRIC_INTERVAL.name;
+            } else {
+                LOG(INFO) << "Client metrics interval set to " << *parsed
+                          << "s via "
+                          << Variables::MC_STORE_CLIENT_METRIC_INTERVAL.name;
+            }
+        }
+    }
+
+    const auto bandwidth =
+        Environ::Read(Variables::MC_STORE_CLIENT_METRIC_BANDWIDTH);
+    if (bandwidth.has_value()) {
+        const auto parsed = TryParseBool(*bandwidth);
+        if (parsed.has_value()) {
+            config.bandwidth_reporting_enabled = *parsed;
+        } else {
+            LOG(WARNING) << "Failed to parse "
+                         << Variables::MC_STORE_CLIENT_METRIC_BANDWIDTH.name
+                         << ": " << *bandwidth << ", fallback to default="
+                         << config.bandwidth_reporting_enabled;
+        }
+    }
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_numa_config.cpp b/mooncake-store/src/config/client_numa_config.cpp
new file mode 100644
index 0000000000..901394fff3
--- /dev/null
+++ b/mooncake-store/src/config/client_numa_config.cpp
@@ -0,0 +1,38 @@
+#include "client_numa_config.h"
+
+#include <cerrno>
+#include <cstdlib>
+#include <limits>
+
+#include <glog/logging.h>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+ClientNumaConfig ClientNumaConfig::FromEnvironment() {
+    ClientNumaConfig config;
+    using Variables = ClientNumaEnvironmentVariables;
+
+    const auto raw_value = Environ::Read(Variables::MC_STORE_NUMA_SOCKET_ID);
+    if (!raw_value.has_value() || raw_value->empty()) {
+        return config;
+    }
+
+    char* end_ptr = nullptr;
+    errno = 0;
+    const long parsed = std::strtol(raw_value->c_str(), &end_ptr, 10);
+    if (errno != 0 || end_ptr == raw_value->c_str() ||
+        (end_ptr != nullptr && *end_ptr != '\0') || parsed < 0 ||
+        parsed > std::numeric_limits<int>::max()) {
+        LOG(WARNING) << "Invalid MC_STORE_NUMA_SOCKET_ID=" << *raw_value
+                     << ", falling back to auto-detect";
+        return config;
+    }
+
+    config.socket_id = static_cast<int>(parsed);
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/client_numa_config.h b/mooncake-store/src/config/client_numa_config.h
new file mode 100644
index 0000000000..b1ed79f4ca
--- /dev/null
+++ b/mooncake-store/src/config/client_numa_config.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include <optional>
+
+namespace mooncake {
+
+struct ClientNumaConfig {
+    std::optional<int> socket_id;
+
+    static ClientNumaConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/cxl_segment_config.cpp b/mooncake-store/src/config/cxl_segment_config.cpp
new file mode 100644
index 0000000000..c291fed830
--- /dev/null
+++ b/mooncake-store/src/config/cxl_segment_config.cpp
@@ -0,0 +1,25 @@
+#include "cxl_segment_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+#include "integer_parser.h"
+
+namespace mooncake {
+
+CxlSegmentConfig CxlSegmentConfig::FromEnvironment() {
+    CxlSegmentConfig config;
+    using Variables = CxlSegmentEnvironmentVariables;
+
+    const auto raw_value = Environ::Read(Variables::MC_CXL_DEV_SIZE);
+    if (!raw_value.has_value()) {
+        return config;
+    }
+
+    config.device_size =
+        TryParseInteger<size_t>(*raw_value, {.trim_ascii_whitespace = true,
+                                             .allow_leading_plus = true})
+            .value_or(0);
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/cxl_segment_config.h b/mooncake-store/src/config/cxl_segment_config.h
new file mode 100644
index 0000000000..bb4293be21
--- /dev/null
+++ b/mooncake-store/src/config/cxl_segment_config.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#include <cstddef>
+#include <optional>
+
+namespace mooncake {
+
+struct CxlSegmentConfig {
+    std::optional<size_t> device_size;
+
+    static CxlSegmentConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/distributed_storage_config.cpp b/mooncake-store/src/config/distributed_storage_config.cpp
new file mode 100644
index 0000000000..add5ceb9b3
--- /dev/null
+++ b/mooncake-store/src/config/distributed_storage_config.cpp
@@ -0,0 +1,200 @@
+#include "config/distributed_storage_config.h"
+
+#include <glog/logging.h>
+#include <chrono>
+#include <filesystem>
+#include <limits>
+#include <sstream>
+#include <string_view>
+
+#include "environ.h"
+#include "environment_variables.h"
+#include "storage/distributed/dfs_allocator_interface.h"
+
+namespace mooncake {
+
+std::optional<DfsAllocatorType> ParseDfsAllocatorType(std::string_view name) {
+    if (name == "shard") return DfsAllocatorType::SHARD;
+    if (name == "bucket") return DfsAllocatorType::BUCKET;
+    return std::nullopt;
+}
+
+const char* ToString(DfsAllocatorType type) {
+    switch (type) {
+        case DfsAllocatorType::SHARD:
+            return "shard";
+        case DfsAllocatorType::BUCKET:
+            return "bucket";
+    }
+    return "unknown";
+}
+
+bool DistributedStorageConfig::Validate() const {
+    if (fsdir.empty()) {
+        LOG(ERROR) << "DistributedStorageConfig: fsdir is empty";
+        return false;
+    }
+    if (!std::filesystem::path(fsdir).is_absolute()) {
+        LOG(ERROR)
+            << "DistributedStorageConfig: fsdir must be an absolute path: "
+            << fsdir;
+        return false;
+    }
+    if (fs_adapter_type != "hf3fs" && fs_adapter_type != "posix" &&
+        fs_adapter_type != "oss") {
+        LOG(ERROR) << "DistributedStorageConfig: unsupported fs_adapter_type: "
+                   << fs_adapter_type;
+        return false;
+    }
+    if (fs_adapter_type == "oss") {
+        return true;
+    }
+    const auto parsed_allocator = ParseDfsAllocatorType(allocator_type);
+    if (!parsed_allocator) {
+        LOG(ERROR) << "DistributedStorageConfig: unsupported allocator_type: "
+                   << allocator_type;
+        return false;
+    }
+    // alignment is shared by both allocators.
+    if (alignment == 0 || (alignment & (alignment - 1)) != 0) {
+        LOG(ERROR) << "DistributedStorageConfig: alignment must be power of 2";
+        return false;
+    }
+    if (*parsed_allocator == DfsAllocatorType::SHARD) {
+        if (shard_count <= 0) {
+            LOG(ERROR) << "DistributedStorageConfig: shard_count must > 0";
+            return false;
+        }
+        if (shard_capacity == 0) {
+            LOG(ERROR) << "DistributedStorageConfig: shard_capacity must > 0";
+            return false;
+        }
+        if (shard_capacity % alignment != 0) {
+            LOG(ERROR) << "DistributedStorageConfig: shard_capacity must align";
+            return false;
+        }
+    }
+    if (*parsed_allocator == DfsAllocatorType::BUCKET &&
+        (bucket_capacity == 0 || bucket_capacity % alignment != 0 ||
+         bucket_capacity >
+             static_cast<uint64_t>(std::numeric_limits<int64_t>::max()) ||
+         max_bucket_count <= 0 ||
+         bucket_capacity > std::numeric_limits<uint64_t>::max() /
+                               static_cast<uint64_t>(max_bucket_count))) {
+        LOG(ERROR) << "DistributedStorageConfig: invalid bucket capacity/count";
+        return false;
+    }
+    if (!single_tenant) {
+        LOG(ERROR) << "DistributedStorageConfig: Currently, DFS requires "
+                      "single_tenant=true";
+        return false;
+    }
+    return true;
+}
+
+bool DistributedStorageConfig::ValidateForAllocator() const {
+    if (!Validate()) return false;
+    if (fs_adapter_type == "oss") {
+        LOG(ERROR) << "DistributedStorageConfig: DFS allocator requires a "
+                      "filesystem adapter";
+        return false;
+    }
+
+    if (eviction_low_watermark < 0.0 || eviction_low_watermark > 1.0 ||
+        eviction_high_watermark < 0.0 || eviction_high_watermark > 1.0 ||
+        eviction_low_watermark >= eviction_high_watermark) {
+        LOG(ERROR) << "DistributedStorageConfig: eviction watermarks must "
+                      "satisfy 0 <= low < high <= 1, low="
+                   << eviction_low_watermark
+                   << ", high=" << eviction_high_watermark;
+        return false;
+    }
+    if (deferred_free_duration.count() < 0) {
+        LOG(ERROR) << "DistributedStorageConfig: deferred_free_duration must "
+                      "be non-negative, seconds="
+                   << deferred_free_duration.count();
+        return false;
+    }
+    if (eviction_enabled && eviction_check_interval.count() <= 0) {
+        LOG(ERROR) << "DistributedStorageConfig: eviction_check_interval must "
+                      "be positive when eviction is enabled, seconds="
+                   << eviction_check_interval.count();
+        return false;
+    }
+    return true;
+}
+
+DistributedStorageConfig DistributedStorageConfig::FromEnvironment() {
+    DistributedStorageConfig config;
+    using Variables = DistributedStorageEnvironmentVariables;
+
+    const auto legacy_root_dir =
+        Environ::ReadOr(Variables::MOONCAKE_DISTRIBUTED_ROOT_DIR, config.fsdir);
+    config.fsdir =
+        Environ::ReadOr(Variables::MOONCAKE_DFS_ROOT_DIR, legacy_root_dir);
+    if (!std::filesystem::path(config.fsdir).is_absolute()) {
+        config.fsdir = std::filesystem::absolute(config.fsdir).string();
+    }
+
+    const auto legacy_fs_adapter = Environ::ReadOr(
+        Variables::MOONCAKE_DISTRIBUTED_FS_TYPE, config.fs_adapter_type);
+    config.fs_adapter_type =
+        Environ::ReadOr(Variables::MOONCAKE_DFS_FS_ADAPTER, legacy_fs_adapter);
+    config.allocator_type = Environ::ReadOr(Variables::MOONCAKE_DFS_ALLOCATOR,
+                                            config.allocator_type);
+    config.enable_health_check =
+        Environ::ReadOr(Variables::MOONCAKE_DISTRIBUTED_HEALTH_CHECK,
+                        config.enable_health_check);
+    config.shard_count = Environ::ReadOr(Variables::MOONCAKE_DFS_SHARD_COUNT,
+                                         config.shard_count);
+    config.shard_capacity = Environ::ReadOr(
+        Variables::MOONCAKE_DFS_SHARD_CAPACITY, config.shard_capacity);
+    config.bucket_capacity = Environ::ReadOr(
+        Variables::MOONCAKE_DFS_BUCKET_CAPACITY, config.bucket_capacity);
+    config.max_bucket_count = Environ::ReadOr(
+        Variables::MOONCAKE_DFS_MAX_BUCKET_COUNT, config.max_bucket_count);
+    config.alignment =
+        Environ::ReadOr(Variables::MOONCAKE_DFS_ALIGNMENT, config.alignment);
+    config.single_tenant = Environ::ReadOr(
+        Variables::MOONCAKE_DFS_SINGLE_TENANT, config.single_tenant);
+    config.eviction_enabled = Environ::ReadOr(
+        Variables::MOONCAKE_DFS_EVICTION_ENABLED, config.eviction_enabled);
+
+    // GetDouble silently falls back for an empty value; ReadOr<double> emits a
+    // warning. Keep the existing diagnostics while this refactor is
+    // behavior-preserving.
+    config.eviction_high_watermark =
+        Environ::GetDouble(Variables::MOONCAKE_DFS_EVICTION_HIGH_WATERMARK.name,
+                           config.eviction_high_watermark);
+    config.eviction_low_watermark =
+        Environ::GetDouble(Variables::MOONCAKE_DFS_EVICTION_LOW_WATERMARK.name,
+                           config.eviction_low_watermark);
+    config.deferred_free_duration = std::chrono::seconds(Environ::ReadOr(
+        Variables::MOONCAKE_DFS_DEFERRED_FREE_SECONDS,
+        static_cast<int>(config.deferred_free_duration.count())));
+    config.eviction_check_interval = std::chrono::seconds(Environ::ReadOr(
+        Variables::MOONCAKE_DFS_EVICTION_CHECK_INTERVAL,
+        static_cast<int>(config.eviction_check_interval.count())));
+    return config;
+}
+
+std::string DistributedStorageConfig::FormatStr() const {
+    std::ostringstream oss;
+    oss << "fsdir=" << fsdir << ", fs_adapter_type=" << fs_adapter_type
+        << ", allocator_type=" << allocator_type
+        << ", enable_health_check=" << enable_health_check
+        << ", shard_count=" << shard_count
+        << ", shard_capacity=" << shard_capacity
+        << ", bucket_capacity=" << bucket_capacity
+        << ", max_bucket_count=" << max_bucket_count
+        << ", alignment=" << alignment << ", single_tenant=" << single_tenant
+        << ", eviction_enabled=" << eviction_enabled
+        << ", eviction_high_watermark=" << eviction_high_watermark
+        << ", eviction_low_watermark=" << eviction_low_watermark
+        << ", deferred_free_seconds=" << deferred_free_duration.count()
+        << ", eviction_check_interval_seconds="
+        << eviction_check_interval.count();
+    return oss.str();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/file_per_key_config.cpp b/mooncake-store/src/config/file_per_key_config.cpp
new file mode 100644
index 0000000000..eee8aac094
--- /dev/null
+++ b/mooncake-store/src/config/file_per_key_config.cpp
@@ -0,0 +1,32 @@
+#include "config/file_per_key_config.h"
+
+#include <glog/logging.h>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+bool FilePerKeyConfig::Validate() const {
+    if (fsdir.empty()) {
+        LOG(ERROR) << "FilePerKeyConfig: fsdir is invalid";
+        return false;
+    }
+    return true;
+}
+
+FilePerKeyConfig FilePerKeyConfig::FromEnvironment() {
+    FilePerKeyConfig config;
+    using Variables = FilePerKeyEnvironmentVariables;
+
+    config.fsdir =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_FSDIR, config.fsdir);
+
+    config.enable_eviction = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_ENABLE_EVICTION,
+        Environ::ReadOr(Variables::ENABLE_EVICTION, config.enable_eviction));
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/file_storage_config.cpp b/mooncake-store/src/config/file_storage_config.cpp
new file mode 100644
index 0000000000..f035257627
--- /dev/null
+++ b/mooncake-store/src/config/file_storage_config.cpp
@@ -0,0 +1,250 @@
+#include "storage_backend.h"
+
+#include <cmath>
+#include <filesystem>
+#include <locale>
+#include <sstream>
+#include <string>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include "bool_parser.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+namespace {
+
+double ParseDiskEvictionRatioOr(const std::string& raw_value,
+                                double default_value) {
+    if (raw_value.empty()) {
+        return default_value;
+    }
+
+    std::istringstream stream(raw_value);
+    stream.imbue(std::locale::classic());
+
+    double value = 0.0;
+    stream >> value;
+    if (stream.fail()) {
+        return default_value;
+    }
+    if (!stream.eof() || !std::isfinite(value) || value <= 0.0 || value > 1.0) {
+        return default_value;
+    }
+    return value;
+}
+
+bool ParseStrictBoolOr(const std::string& raw_value, bool default_value) {
+    return TryParseBool(raw_value, {.token_set = BoolTokenSet::kTrueFalse,
+                                    .trim_ascii_whitespace = false})
+        .value_or(default_value);
+}
+
+}  // namespace
+
+FileStorageConfig FileStorageConfig::FromEnvironment() {
+    FileStorageConfig config;
+    using Variables = FileStorageEnvironmentVariables;
+
+    const auto storage_backend_descriptor =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR,
+                        std::string{"bucket_storage_backend"});
+
+    if (storage_backend_descriptor == "bucket_storage_backend") {
+        config.storage_backend_type = StorageBackendType::kBucket;
+    } else if (storage_backend_descriptor == "file_per_key_storage_backend") {
+        config.storage_backend_type = StorageBackendType::kFilePerKey;
+    } else if (storage_backend_descriptor ==
+               "offset_allocator_storage_backend") {
+        config.storage_backend_type = StorageBackendType::kOffsetAllocator;
+    } else if (storage_backend_descriptor == "distributed_storage_backend") {
+        config.storage_backend_type = StorageBackendType::kDistributed;
+    } else if (storage_backend_descriptor == "nvme_kv_storage_backend") {
+        config.storage_backend_type = StorageBackendType::kNvmeKv;
+    } else {
+        LOG(ERROR) << "Unknown storage backend.";
+    }
+
+    config.storage_filepath = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_FILE_STORAGE_PATH, config.storage_filepath);
+
+    config.local_buffer_size =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES,
+                        config.local_buffer_size);
+
+    config.pinned_restore_arena_size =
+        Environ::ReadOr(Variables::MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES,
+                        config.pinned_restore_arena_size);
+
+    const auto legacy_scanmeta_iterator_keys_limit =
+        Environ::ReadOr(Variables::MOONCAKE_SCANMETA_ITERATOR_KEYS_LIMIT,
+                        config.scanmeta_iterator_keys_limit);
+    config.scanmeta_iterator_keys_limit = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT,
+        legacy_scanmeta_iterator_keys_limit);
+
+    config.total_keys_limit = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT, config.total_keys_limit);
+
+    config.total_size_limit =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES,
+                        config.total_size_limit);
+
+    config.heartbeat_interval_seconds =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS,
+                        config.heartbeat_interval_seconds);
+    config.client_buffer_gc_interval_seconds = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS,
+        config.client_buffer_gc_interval_seconds);
+
+    config.client_buffer_gc_ttl_ms =
+        Environ::ReadOr(Variables::MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS,
+                        config.client_buffer_gc_ttl_ms);
+
+    const auto enable_disk_watermark_eviction = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION,
+        std::string{config.enable_disk_watermark_eviction ? "true" : "false"});
+    config.enable_disk_watermark_eviction = ParseStrictBoolOr(
+        enable_disk_watermark_eviction, config.enable_disk_watermark_eviction);
+
+    const auto high_watermark_ratio = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO,
+        std::string{});
+    const auto high_watermark_ratio_or_alias =
+        high_watermark_ratio.empty()
+            ? Environ::ReadOr(
+                  Variables::MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO,
+                  std::string{})
+            : high_watermark_ratio;
+    config.disk_eviction_high_watermark_ratio =
+        ParseDiskEvictionRatioOr(high_watermark_ratio_or_alias,
+                                 config.disk_eviction_high_watermark_ratio);
+
+    const auto low_watermark_ratio = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO,
+        std::string{});
+    const auto low_watermark_ratio_or_alias =
+        low_watermark_ratio.empty()
+            ? Environ::ReadOr(
+                  Variables::MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO,
+                  std::string{})
+            : low_watermark_ratio;
+    config.disk_eviction_low_watermark_ratio = ParseDiskEvictionRatioOr(
+        low_watermark_ratio_or_alias, config.disk_eviction_low_watermark_ratio);
+
+    const auto legacy_use_uring =
+        Environ::ReadOr(Variables::MOONCAKE_USE_URING, std::string{"false"});
+    const auto use_uring = Environ::ReadOr(
+        Variables::MOONCAKE_OFFLOAD_USE_URING, legacy_use_uring);
+    config.use_uring = ParseStrictBoolOr(use_uring, false);
+
+    return config;
+}
+
+bool FileStorageConfig::ValidatePath(std::string path) const {
+    if (path.empty()) {
+        LOG(ERROR) << "FileStorageConfig: storage_filepath is invalid";
+        return false;
+    }
+    namespace fs = std::filesystem;
+    // 1. Must be an absolute path
+    if (!fs::path(path).is_absolute()) {
+        LOG(ERROR)
+            << "FileStorageConfig: storage_filepath must be an absolute path: "
+            << path;
+        return false;
+    }
+
+    // 2. Check if the path contains ".." components that could lead to path
+    // traversal (static check)
+    fs::path p(path);
+    for (const auto& component : p) {
+        if (component == "..") {
+            LOG(ERROR) << "FileStorageConfig: path traversal is not allowed: "
+                       << path;
+            return false;
+        }
+    }
+
+    struct stat stat_buf;
+
+    // 3. Use stat() to check if the path exists
+    if (::stat(path.c_str(), &stat_buf) != 0) {
+        LOG(ERROR) << "FileStorageConfig: storage_filepath does not exist: "
+                   << path;
+        return false;
+    }
+    // Path exists — check if it is a directory
+    if (!S_ISDIR(stat_buf.st_mode)) {
+        LOG(ERROR) << "FileStorageConfig: storage_filepath is not a directory: "
+                   << path;
+        return false;
+    }
+
+    // (Optional) Check write permission
+    if (::access(path.c_str(), W_OK) != 0) {
+        LOG(ERROR) << "FileStorageConfig: no write permission on directory: "
+                   << path;
+        return false;
+    }
+
+    // 4. Additional security: prevent symlink bypass (optional)
+    // Use lstat to avoid automatic dereferencing of symbolic links
+    struct stat lstat_buf;
+    if (::lstat(path.c_str(), &lstat_buf) == 0) {
+        if (S_ISLNK(lstat_buf.st_mode)) {
+            LOG(ERROR) << "FileStorageConfig: symbolic link is not allowed: "
+                       << path;
+            return false;
+        }
+    }
+
+    return true;
+}
+
+bool FileStorageConfig::Validate() const {
+    if (!ValidatePath(storage_filepath)) {
+        return false;
+    }
+    if (total_keys_limit <= 0) {
+        LOG(ERROR) << "FileStorageConfig: total_keys_limit must > 0";
+        return false;
+    }
+    if (total_size_limit == 0) {
+        LOG(ERROR) << "FileStorageConfig: total_size_limit should not be zero";
+        return false;
+    }
+    if (pinned_restore_arena_size < 0) {
+        LOG(ERROR) << "FileStorageConfig: pinned_restore_arena_size must be "
+                      "non-negative";
+        return false;
+    }
+    if (heartbeat_interval_seconds <= 0) {
+        LOG(ERROR) << "FileStorageConfig: heartbeat_interval_seconds must > 0";
+        return false;
+    }
+    if (disk_eviction_low_watermark_ratio <= 0.0 ||
+        disk_eviction_low_watermark_ratio > 1.0) {
+        LOG(ERROR) << "FileStorageConfig: "
+                   << "disk_eviction_low_watermark_ratio must be in (0, 1]";
+        return false;
+    }
+    if (disk_eviction_high_watermark_ratio <= 0.0 ||
+        disk_eviction_high_watermark_ratio > 1.0) {
+        LOG(ERROR) << "FileStorageConfig: "
+                   << "disk_eviction_high_watermark_ratio must be in (0, 1]";
+        return false;
+    }
+    if (disk_eviction_low_watermark_ratio >=
+        disk_eviction_high_watermark_ratio) {
+        LOG(ERROR) << "FileStorageConfig: "
+                   << "disk_eviction_low_watermark_ratio must be lower than "
+                   << "disk_eviction_high_watermark_ratio";
+        return false;
+    }
+    return true;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/fileread_worker_pool_config.cpp b/mooncake-store/src/config/fileread_worker_pool_config.cpp
new file mode 100644
index 0000000000..d6bdf7f6f8
--- /dev/null
+++ b/mooncake-store/src/config/fileread_worker_pool_config.cpp
@@ -0,0 +1,29 @@
+#include "fileread_worker_pool_config.h"
+
+#include <glog/logging.h>
+
+#include "environ.h"
+#include "environment_value_parser.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+FilereadWorkerPoolConfig FilereadWorkerPoolConfig::FromEnvironment() {
+    FilereadWorkerPoolConfig config;
+    const auto raw = Environ::Read(
+        FilereadWorkerPoolEnvironmentVariables::MC_FILEREAD_WORKERS);
+    if (!raw || raw->empty()) {
+        return config;
+    }
+
+    const auto value = TryParseEnvironmentValue<int>(*raw);
+    if (value && *value > 0) {
+        config.worker_count = *value;
+    } else {
+        LOG(WARNING) << "Invalid value for MC_FILEREAD_WORKERS: " << *raw
+                     << ", using default " << config.worker_count;
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/fileread_worker_pool_config.h b/mooncake-store/src/config/fileread_worker_pool_config.h
new file mode 100644
index 0000000000..ba7b485806
--- /dev/null
+++ b/mooncake-store/src/config/fileread_worker_pool_config.h
@@ -0,0 +1,11 @@
+#pragma once
+
+namespace mooncake {
+
+struct FilereadWorkerPoolConfig {
+    int worker_count = 10;
+
+    static FilereadWorkerPoolConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/ha_cluster_namespace_config.cpp b/mooncake-store/src/config/ha_cluster_namespace_config.cpp
new file mode 100644
index 0000000000..8bd6716490
--- /dev/null
+++ b/mooncake-store/src/config/ha_cluster_namespace_config.cpp
@@ -0,0 +1,18 @@
+#include "ha_cluster_namespace_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+HaClusterNamespaceConfig HaClusterNamespaceConfig::FromEnvironment() {
+    HaClusterNamespaceConfig config;
+    const auto value = Environ::Read(
+        HaClusterNamespaceEnvironmentVariables::MC_STORE_CLUSTER_ID);
+    if (value && !value->empty()) {
+        config.cluster_namespace = *value;
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/ha_cluster_namespace_config.h b/mooncake-store/src/config/ha_cluster_namespace_config.h
new file mode 100644
index 0000000000..c33aa74c45
--- /dev/null
+++ b/mooncake-store/src/config/ha_cluster_namespace_config.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#include <string>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct HaClusterNamespaceConfig {
+    std::string cluster_namespace = DEFAULT_CLUSTER_ID;
+
+    static HaClusterNamespaceConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/hugepage_config.cpp b/mooncake-store/src/config/hugepage_config.cpp
new file mode 100644
index 0000000000..d3a99f2367
--- /dev/null
+++ b/mooncake-store/src/config/hugepage_config.cpp
@@ -0,0 +1,51 @@
+#include "hugepage_config.h"
+
+#include <string>
+
+#include <glog/logging.h>
+
+#include "common/byte_size.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+constexpr size_t kSize2Mb = 2ULL * 1024 * 1024;
+constexpr size_t kSize512Mb = 512ULL * 1024 * 1024;
+constexpr size_t kSize1Gb = 1024ULL * 1024 * 1024;
+
+}  // namespace
+
+bool HugepageConfig::IsEnabledFromEnvironment() {
+    using Variables = HugepageEnvironmentVariables;
+    return Environ::Read(Variables::MC_STORE_USE_HUGEPAGE).has_value();
+}
+
+HugepageConfig HugepageConfig::FromEnvironment() {
+    HugepageConfig config;
+    if (!IsEnabledFromEnvironment()) {
+        return config;
+    }
+
+    config.enabled = true;
+    config.page_size = kSize2Mb;
+
+    using Variables = HugepageEnvironmentVariables;
+    const auto raw_size = Environ::Read(Variables::MC_STORE_HUGEPAGE_SIZE);
+    if (!raw_size.has_value()) {
+        return config;
+    }
+
+    const size_t parsed_size = string_to_byte_size(*raw_size);
+    if (parsed_size == kSize2Mb || parsed_size == kSize512Mb ||
+        parsed_size == kSize1Gb) {
+        config.page_size = parsed_size;
+    } else {
+        LOG(WARNING) << "Invalid MC_STORE_HUGEPAGE_SIZE='" << *raw_size
+                     << "'. Supported: 2MB, 512MB, 1GB. Fallback to 2MB.";
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/hugepage_config.h b/mooncake-store/src/config/hugepage_config.h
new file mode 100644
index 0000000000..799885c7b4
--- /dev/null
+++ b/mooncake-store/src/config/hugepage_config.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#include <cstddef>
+
+namespace mooncake {
+
+struct HugepageConfig {
+    bool enabled = false;
+    size_t page_size = 0;
+
+    static bool IsEnabledFromEnvironment();
+    static HugepageConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/local_file_snapshot_config.cpp b/mooncake-store/src/config/local_file_snapshot_config.cpp
new file mode 100644
index 0000000000..2747daf541
--- /dev/null
+++ b/mooncake-store/src/config/local_file_snapshot_config.cpp
@@ -0,0 +1,23 @@
+#include "local_file_snapshot_config.h"
+
+#include <stdexcept>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+LocalFileSnapshotConfig LocalFileSnapshotConfig::FromEnvironment() {
+    const auto value = Environ::Read(
+        LocalFileSnapshotEnvironmentVariables::MOONCAKE_SNAPSHOT_LOCAL_PATH);
+    if (!value || value->empty()) {
+        throw std::runtime_error(
+            "MOONCAKE_SNAPSHOT_LOCAL_PATH environment variable is not set. "
+            "Please set it to a persistent directory path for snapshot "
+            "storage. Example: export "
+            "MOONCAKE_SNAPSHOT_LOCAL_PATH=/data/mooncake_snapshots");
+    }
+    return LocalFileSnapshotConfig{.base_path = *value};
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/local_file_snapshot_config.h b/mooncake-store/src/config/local_file_snapshot_config.h
new file mode 100644
index 0000000000..bc6945f656
--- /dev/null
+++ b/mooncake-store/src/config/local_file_snapshot_config.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include <string>
+
+namespace mooncake {
+
+struct LocalFileSnapshotConfig {
+    std::string base_path;
+
+    static LocalFileSnapshotConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/local_hot_cache_config.cpp b/mooncake-store/src/config/local_hot_cache_config.cpp
new file mode 100644
index 0000000000..ab77f00332
--- /dev/null
+++ b/mooncake-store/src/config/local_hot_cache_config.cpp
@@ -0,0 +1,92 @@
+#include "local_hot_cache.h"
+
+#include <glog/logging.h>
+
+#include <exception>
+#include <optional>
+#include <string>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+size_t ParseLegacyPositiveSizeOr(const std::optional<std::string>& raw_value,
+                                 size_t default_value,
+                                 const char* variable_name,
+                                 const char* fallback_message) {
+    if (!raw_value.has_value()) {
+        return default_value;
+    }
+    const std::string error_message = "Invalid " + std::string(variable_name) +
+                                      "='" + *raw_value + "'" +
+                                      fallback_message;
+    if (!raw_value->empty() && raw_value->front() == '-') {
+        LOG(WARNING) << error_message;
+        return default_value;
+    }
+
+    try {
+        // Keep the legacy numeric-prefix behavior of std::stoull.
+        const unsigned long long value = std::stoull(*raw_value, nullptr, 10);
+        if (value > 0) {
+            return static_cast<size_t>(value);
+        }
+    } catch (const std::exception&) {
+    }
+
+    LOG(WARNING) << error_message;
+    return default_value;
+}
+
+}  // namespace
+
+LocalHotCacheConfig LocalHotCacheConfig::FromEnvironment() {
+    LocalHotCacheConfig config;
+    using Variables = LocalHotCacheEnvironmentVariables;
+
+    const auto total_size =
+        Environ::Read(Variables::MC_STORE_LOCAL_HOT_CACHE_SIZE);
+    config.total_size_bytes = ParseLegacyPositiveSizeOr(
+        total_size, 0, Variables::MC_STORE_LOCAL_HOT_CACHE_SIZE.name,
+        ", disable local hot cache");
+    if (config.total_size_bytes == 0) {
+        return config;
+    }
+
+    const auto block_size =
+        Environ::Read(Variables::MC_STORE_LOCAL_HOT_BLOCK_SIZE);
+    config.block_size_bytes =
+        ParseLegacyPositiveSizeOr(block_size, config.block_size_bytes,
+                                  Variables::MC_STORE_LOCAL_HOT_BLOCK_SIZE.name,
+                                  ", using default block size");
+
+    config.use_shm = Environ::Read(Variables::MC_STORE_LOCAL_HOT_CACHE_USE_SHM)
+                         .value_or(std::string{}) == "1";
+
+    const auto admission_threshold =
+        Environ::Read(Variables::MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD);
+    if (admission_threshold.has_value()) {
+        const std::string error_message =
+            "Invalid " +
+            std::string(
+                Variables::MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD.name) +
+            "='" + *admission_threshold + "', using default";
+        try {
+            const unsigned long long value =
+                std::stoull(*admission_threshold, nullptr, 10);
+            if (value > 0 && value <= 255) {
+                config.admission_threshold = static_cast<uint8_t>(value);
+            } else {
+                LOG(WARNING) << error_message;
+            }
+        } catch (const std::exception&) {
+            LOG(WARNING) << error_message;
+        }
+    }
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/mmap_arena_config.cpp b/mooncake-store/src/config/mmap_arena_config.cpp
new file mode 100644
index 0000000000..eb0a3a3ac9
--- /dev/null
+++ b/mooncake-store/src/config/mmap_arena_config.cpp
@@ -0,0 +1,78 @@
+#include "mmap_arena_config.h"
+
+#include <optional>
+#include <string>
+
+#include <glog/logging.h>
+
+#include "bool_parser.h"
+#include "common/byte_size.h"
+#include "environ.h"
+#include "environment_variables.h"
+#include "hugepage_config.h"
+
+namespace mooncake {
+
+MmapArenaConfig MmapArenaConfig::FromEnvironment(bool enabled_by_flag,
+                                                 uint64_t flag_pool_size) {
+    MmapArenaConfig config{.enabled = enabled_by_flag,
+                           .pool_size = flag_pool_size};
+    using Variables = MmapArenaEnvironmentVariables;
+
+    const std::string env_pool_size =
+        Environ::ReadOr(Variables::MC_MMAP_ARENA_POOL_SIZE, std::string{});
+    // An explicit pool-size env var is treated as an opt-in because pybind11
+    // users cannot easily pass gflags.
+    const std::string env_disable =
+        Environ::ReadOr(Variables::MC_DISABLE_MMAP_ARENA, std::string{});
+    const std::optional<bool> disable_override = TryParseBool(env_disable);
+    if (!env_disable.empty() && !disable_override.has_value()) {
+        LOG(WARNING) << "Ignoring invalid MC_DISABLE_MMAP_ARENA='"
+                     << env_disable
+                     << "'; accepted values: 1/0, true/false, yes/no, on/off";
+    }
+
+    const bool arena_requested = enabled_by_flag || !env_pool_size.empty();
+    const bool arena_disabled = disable_override.value_or(false);
+    if (!arena_requested || arena_disabled) {
+        config.enabled = false;
+        LOG(INFO) << "=== ARENA ALLOCATOR DISABLED ===";
+        if (arena_disabled) {
+            LOG(INFO) << "MC_DISABLE_MMAP_ARENA=" << env_disable
+                      << " forces direct mmap()";
+        } else {
+            LOG(INFO) << "Arena is opt-in; set --use_mmap_arena_allocator or "
+                         "MC_MMAP_ARENA_POOL_SIZE to enable it";
+        }
+        return config;
+    }
+
+    config.enabled = true;
+    // Keep arena init consistent with the direct-mmap path:
+    //   MC_STORE_USE_HUGEPAGE=1  -> strict: hard fail if hugepage mmap fails
+    //   unset                    -> permissive: try hugepages, retry on
+    //                               regular pages if HugeTLB is unavailable
+    // This preserves both pre-existing contracts and avoids surprising
+    // operators with a silent hugepage downgrade.
+    config.hugepages_explicitly_requested =
+        HugepageConfig::FromEnvironment().enabled;
+
+    // Supports human-readable sizes via string_to_byte_size(): "20gb", "16GB",
+    // etc.
+    if (!env_pool_size.empty()) {
+        const uint64_t parsed = string_to_byte_size(env_pool_size);
+        if (parsed > 0) {
+            config.pool_size = parsed;
+            LOG(INFO) << "MC_MMAP_ARENA_POOL_SIZE override: " << env_pool_size
+                      << " (" << byte_size_to_string(config.pool_size) << ")";
+        } else {
+            LOG(WARNING) << "Invalid MC_MMAP_ARENA_POOL_SIZE='" << env_pool_size
+                         << "', using default "
+                         << byte_size_to_string(flag_pool_size);
+        }
+    }
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/mmap_arena_config.h b/mooncake-store/src/config/mmap_arena_config.h
new file mode 100644
index 0000000000..07a9eae262
--- /dev/null
+++ b/mooncake-store/src/config/mmap_arena_config.h
@@ -0,0 +1,16 @@
+#pragma once
+
+#include <cstdint>
+
+namespace mooncake {
+
+struct MmapArenaConfig {
+    bool enabled = false;
+    uint64_t pool_size = 0;
+    bool hugepages_explicitly_requested = false;
+
+    static MmapArenaConfig FromEnvironment(bool enabled_by_flag,
+                                           uint64_t flag_pool_size);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/nof_register_config.cpp b/mooncake-store/src/config/nof_register_config.cpp
new file mode 100644
index 0000000000..284298e6b5
--- /dev/null
+++ b/mooncake-store/src/config/nof_register_config.cpp
@@ -0,0 +1,30 @@
+#include "nof_register_config.h"
+
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <cctype>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+NoFRegisterConfig NoFRegisterConfig::FromEnvironment() {
+    NoFRegisterConfig config;
+    config.transport_type =
+        Environ::Read(NoFRegisterEnvironmentVariables::MC_NOF_TRTYPE)
+            .value_or("RDMA");
+    std::transform(config.transport_type.begin(), config.transport_type.end(),
+                   config.transport_type.begin(), [](unsigned char c) {
+                       return static_cast<char>(std::toupper(c));
+                   });
+    if (config.transport_type != "RDMA" && config.transport_type != "TCP") {
+        LOG(WARNING) << "Invalid MC_NOF_TRTYPE=" << config.transport_type
+                     << ", fallback to RDMA";
+        config.transport_type = "RDMA";
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/nof_register_config.h b/mooncake-store/src/config/nof_register_config.h
new file mode 100644
index 0000000000..93758ac0fb
--- /dev/null
+++ b/mooncake-store/src/config/nof_register_config.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include <string>
+
+namespace mooncake {
+
+struct NoFRegisterConfig {
+    std::string transport_type = "RDMA";
+
+    static NoFRegisterConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/offset_allocator_backend_config.cpp b/mooncake-store/src/config/offset_allocator_backend_config.cpp
new file mode 100644
index 0000000000..41e6be5323
--- /dev/null
+++ b/mooncake-store/src/config/offset_allocator_backend_config.cpp
@@ -0,0 +1,137 @@
+#include "config/offset_allocator_backend_config.h"
+
+#include <glog/logging.h>
+
+#include <string>
+
+#include "ascii_string.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+bool OffsetAllocatorBackendConfig::Validate() const {
+    if (persist_mode == OffsetPersistMode::kRelaxed) {
+        if (persist_interval_seconds < 5) {
+            LOG(ERROR) << "OffsetAllocatorBackendConfig: "
+                          "persist_interval_seconds must be >= 5 for "
+                          "kRelaxed mode";
+            return false;
+        }
+    }
+    if (high_ratio <= 0.0 || high_ratio > 1.0) {
+        LOG(ERROR)
+            << "OffsetAllocatorBackendConfig: high_ratio must be in (0,1]";
+        return false;
+    }
+    if (low_ratio <= 0.0 || low_ratio >= high_ratio) {
+        LOG(ERROR) << "OffsetAllocatorBackendConfig: low_ratio must be in (0, "
+                      "high_ratio)";
+        return false;
+    }
+    if (keys_high_ratio <= 0.0 || keys_high_ratio > 1.0) {
+        LOG(ERROR)
+            << "OffsetAllocatorBackendConfig: keys_high_ratio must be in (0,1]";
+        return false;
+    }
+    if (keys_low_ratio <= 0.0 || keys_low_ratio >= keys_high_ratio) {
+        LOG(ERROR) << "OffsetAllocatorBackendConfig: keys_low_ratio must be in "
+                      "(0, keys_high_ratio)";
+        return false;
+    }
+    if (max_evict_per_offload == 0) {
+        LOG(ERROR) << "OffsetAllocatorBackendConfig: max_evict_per_offload "
+                      "must be > 0";
+        return false;
+    }
+    if (fallback_evict_batch == 0) {
+        LOG(ERROR)
+            << "OffsetAllocatorBackendConfig: fallback_evict_batch must be > 0";
+        return false;
+    }
+    if (max_capacity_nodes < 0) {
+        LOG(ERROR)
+            << "OffsetAllocatorBackendConfig: max_capacity_nodes must be >= 0";
+        return false;
+    }
+    return true;
+}
+
+OffsetAllocatorBackendConfig OffsetAllocatorBackendConfig::FromEnvironment() {
+    OffsetAllocatorBackendConfig cfg;
+    using Variables = OffsetAllocatorBackendEnvironmentVariables;
+
+    const auto policy =
+        Environ::Read(Variables::MOONCAKE_OFFSET_EVICTION_POLICY);
+    if (policy.has_value()) {
+        if (AsciiCaseInsensitiveEquals(*policy, "fifo")) {
+            cfg.eviction_policy = OffsetEvictionPolicy::FIFO;
+        }
+        // NONE is default; LRU reserved for phase 2
+    }
+
+    constexpr EnvironmentDoubleParseOptions kLegacyRatioParsing{
+        .allow_trailing_characters = true,
+        .allow_non_finite = true,
+    };
+    if (const auto value =
+            Environ::Read(Variables::MOONCAKE_OFFSET_HIGH_RATIO)) {
+        cfg.high_ratio = TryParseEnvironmentDouble(*value, kLegacyRatioParsing)
+                             .value_or(cfg.high_ratio);
+    }
+    if (const auto value =
+            Environ::Read(Variables::MOONCAKE_OFFSET_LOW_RATIO)) {
+        cfg.low_ratio = TryParseEnvironmentDouble(*value, kLegacyRatioParsing)
+                            .value_or(cfg.low_ratio);
+    }
+    // Both byte and key watermarks derive from the same ratio pair.
+    cfg.keys_high_ratio = cfg.high_ratio;
+    cfg.keys_low_ratio = cfg.low_ratio;
+
+    cfg.max_capacity_nodes = Environ::ReadOr(
+        Variables::MOONCAKE_OFFSET_MAX_CAPACITY_NODES, cfg.max_capacity_nodes);
+
+    // Read eviction cap as int64_t to guard against negative env values
+    // which would wrap to SIZE_MAX with an unsigned parser.
+    auto max_evict_raw =
+        Environ::ReadOr(Variables::MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD,
+                        static_cast<int64_t>(cfg.max_evict_per_offload));
+    if (max_evict_raw > 0) {
+        cfg.max_evict_per_offload = static_cast<size_t>(max_evict_raw);
+    } else if (max_evict_raw <= 0) {
+        LOG(WARNING) << "MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD="
+                     << max_evict_raw << " is non-positive; using default "
+                     << cfg.max_evict_per_offload;
+    }
+
+    // Persistence mode
+    const auto persist = Environ::Read(Variables::MOONCAKE_OFFSET_PERSIST_MODE);
+    if (persist.has_value()) {
+        const std::string& s = *persist;
+        if (AsciiCaseInsensitiveEquals(s, "disabled")) {
+            cfg.persist_mode = OffsetPersistMode::kDisabled;
+        } else if (AsciiCaseInsensitiveEquals(s, "relaxed")) {
+            cfg.persist_mode = OffsetPersistMode::kRelaxed;
+        } else if (AsciiCaseInsensitiveEquals(s, "strict")) {
+            cfg.persist_mode = OffsetPersistMode::kStrict;
+        } else {
+            LOG(WARNING) << "Unknown MOONCAKE_OFFSET_PERSIST_MODE=" << s
+                         << "; using default (disabled)";
+        }
+    }
+
+    cfg.persist_interval_seconds =
+        Environ::ReadOr(Variables::MOONCAKE_OFFSET_PERSIST_INTERVAL_SECONDS,
+                        cfg.persist_interval_seconds);
+
+    // Record CRC-32C: "0"/"false"/"off" disables per-record checksums.
+    if (const auto record_crc =
+            Environ::Read(Variables::MOONCAKE_OFFSET_RECORD_CRC);
+        record_crc.has_value() && !*record_crc) {
+        cfg.enable_record_crc = false;
+    }
+
+    return cfg;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/oss_adapter_config.cpp b/mooncake-store/src/config/oss_adapter_config.cpp
new file mode 100644
index 0000000000..49adbdb446
--- /dev/null
+++ b/mooncake-store/src/config/oss_adapter_config.cpp
@@ -0,0 +1,76 @@
+#include "oss_adapter_config.h"
+
+#include <algorithm>
+#include <boost/algorithm/string.hpp>
+#include <glog/logging.h>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+std::string ReadPrimaryOrAlias(const EnvironmentVariable<std::string>& primary,
+                               const EnvironmentVariable<std::string>& alias) {
+    const auto alias_value = Environ::Read(alias);
+    return Environ::Read(primary).value_or(alias_value.value_or(""));
+}
+
+}  // namespace
+
+tl::expected<OssAdapterConfig, ErrorCode> OssAdapterConfig::FromEnvironment() {
+    using Variables = OssAdapterEnvironmentVariables;
+    OssAdapterConfig config;
+
+    config.endpoint = ReadPrimaryOrAlias(Variables::MOONCAKE_OSS_ENDPOINT,
+                                         Variables::OSS_ENDPOINT);
+    config.bucket = ReadPrimaryOrAlias(Variables::MOONCAKE_OSS_BUCKET,
+                                       Variables::OSS_BUCKET);
+    config.region = ReadPrimaryOrAlias(Variables::MOONCAKE_OSS_REGION,
+                                       Variables::OSS_REGION);
+    config.access_key_id = ReadPrimaryOrAlias(
+        Variables::MOONCAKE_OSS_ACCESS_KEY_ID, Variables::OSS_ACCESS_KEY_ID);
+    config.access_key_secret =
+        ReadPrimaryOrAlias(Variables::MOONCAKE_OSS_ACCESS_KEY_SECRET,
+                           Variables::OSS_ACCESS_KEY_SECRET);
+    config.security_token = ReadPrimaryOrAlias(
+        Variables::MOONCAKE_OSS_SECURITY_TOKEN, Variables::OSS_SESSION_TOKEN);
+    boost::algorithm::trim(config.security_token);
+    config.path_style =
+        Environ::ReadOr(Variables::MOONCAKE_OSS_PATH_STYLE, false);
+    config.anonymous =
+        Environ::ReadOr(Variables::MOONCAKE_OSS_ANONYMOUS, false);
+    config.max_connections =
+        std::max(1, Environ::ReadOr(Variables::MOONCAKE_OSS_MAX_CONNECTIONS,
+                                    config.max_connections));
+    config.receive_buffer_size =
+        std::clamp(Environ::ReadOr(Variables::MOONCAKE_OSS_RECEIVE_BUFFER_SIZE,
+                                   config.receive_buffer_size),
+                   16 * 1024, 10 * 1024 * 1024);
+    config.upload_buffer_size =
+        std::clamp(Environ::ReadOr(Variables::MOONCAKE_OSS_UPLOAD_BUFFER_SIZE,
+                                   config.upload_buffer_size),
+                   16 * 1024, 2 * 1024 * 1024);
+
+    while (!config.endpoint.empty() && config.endpoint.back() == '/') {
+        config.endpoint.pop_back();
+    }
+
+    if (config.endpoint.empty() || config.bucket.empty() ||
+        config.region.empty()) {
+        LOG(ERROR) << "OSS requires MOONCAKE_OSS_ENDPOINT, "
+                      "MOONCAKE_OSS_BUCKET and MOONCAKE_OSS_REGION";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (!config.anonymous &&
+        (config.access_key_id.empty() || config.access_key_secret.empty())) {
+        LOG(ERROR)
+            << "OSS credentials are missing; set MOONCAKE_OSS_ACCESS_KEY_ID "
+               "and MOONCAKE_OSS_ACCESS_KEY_SECRET";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/oss_adapter_config.h b/mooncake-store/src/config/oss_adapter_config.h
new file mode 100644
index 0000000000..aae0ef9859
--- /dev/null
+++ b/mooncake-store/src/config/oss_adapter_config.h
@@ -0,0 +1,27 @@
+#pragma once
+
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct OssAdapterConfig {
+    std::string endpoint;
+    std::string bucket;
+    std::string region;
+    std::string access_key_id;
+    std::string access_key_secret;
+    std::string security_token;
+    bool path_style = false;
+    bool anonymous = false;
+    int max_connections = 64;
+    int receive_buffer_size = 1024 * 1024;
+    int upload_buffer_size = 1024 * 1024;
+
+    static tl::expected<OssAdapterConfig, ErrorCode> FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/redis_connection_config.cpp b/mooncake-store/src/config/redis_connection_config.cpp
new file mode 100644
index 0000000000..245bd9a382
--- /dev/null
+++ b/mooncake-store/src/config/redis_connection_config.cpp
@@ -0,0 +1,31 @@
+#include "redis_connection_config.h"
+
+#include "environ.h"
+#include "environment_value_parser.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+tl::expected<RedisConnectionConfig, ErrorCode>
+RedisConnectionConfig::FromEnvironment() {
+    RedisConnectionConfig config;
+    const auto raw_db_index =
+        Environ::Read(RedisConnectionEnvironmentVariables::MC_REDIS_DB_INDEX)
+            .value_or("");
+    if (!raw_db_index.empty()) {
+        const auto db_index = TryParseEnvironmentValue<int>(raw_db_index);
+        if (!db_index.has_value() || *db_index < 0 || *db_index > 255) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        config.db_index = *db_index;
+    }
+    config.username =
+        Environ::Read(RedisConnectionEnvironmentVariables::MC_REDIS_USERNAME)
+            .value_or("");
+    config.password =
+        Environ::Read(RedisConnectionEnvironmentVariables::MC_REDIS_PASSWORD)
+            .value_or("");
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/redis_connection_config.h b/mooncake-store/src/config/redis_connection_config.h
new file mode 100644
index 0000000000..ec38d7faf0
--- /dev/null
+++ b/mooncake-store/src/config/redis_connection_config.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+struct RedisConnectionConfig {
+    int db_index = 0;
+    std::string username;
+    std::string password;
+
+    static tl::expected<RedisConnectionConfig, ErrorCode> FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/registered_pinned_memory_config.cpp b/mooncake-store/src/config/registered_pinned_memory_config.cpp
new file mode 100644
index 0000000000..304ca2bbd6
--- /dev/null
+++ b/mooncake-store/src/config/registered_pinned_memory_config.cpp
@@ -0,0 +1,34 @@
+#include "registered_pinned_memory_config.h"
+
+#include <glog/logging.h>
+
+#include "ascii_string.h"
+#include "environ.h"
+#include "environment_variables.h"
+#include "integer_parser.h"
+
+namespace mooncake {
+
+RegisteredPinnedMemoryConfig RegisteredPinnedMemoryConfig::FromEnvironment() {
+    RegisteredPinnedMemoryConfig config;
+    using Variables = RegisteredPinnedMemoryEnvironmentVariables;
+
+    const auto raw_value =
+        Environ::Read(Variables::MC_STORE_PIN_MEMORY_MAX_BYTES);
+    if (!raw_value.has_value() || raw_value->empty()) {
+        return config;
+    }
+
+    const auto limit =
+        TryParseInteger<uint64_t>(TrimAsciiWhitespace(*raw_value));
+    if (!limit.has_value()) {
+        LOG(WARNING) << "Invalid MC_STORE_PIN_MEMORY_MAX_BYTES='" << *raw_value
+                     << "', disabling Store segment pinning";
+        return config;
+    }
+
+    config.max_bytes = *limit;
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/registered_pinned_memory_config.h b/mooncake-store/src/config/registered_pinned_memory_config.h
new file mode 100644
index 0000000000..f13fafb536
--- /dev/null
+++ b/mooncake-store/src/config/registered_pinned_memory_config.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include <cstdint>
+
+namespace mooncake {
+
+struct RegisteredPinnedMemoryConfig {
+    uint64_t max_bytes = 0;
+
+    static RegisteredPinnedMemoryConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/replica_selection_config.cpp b/mooncake-store/src/config/replica_selection_config.cpp
new file mode 100644
index 0000000000..8bd3bbcae8
--- /dev/null
+++ b/mooncake-store/src/config/replica_selection_config.cpp
@@ -0,0 +1,16 @@
+#include "config/replica_selection_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+ReplicaSelectionConfig ReplicaSelectionConfig::FromEnvironment() {
+    ReplicaSelectionConfig config;
+    const auto value = Environ::Read(
+        ReplicaSelectionEnvironmentVariables::MC_STORE_REPLICA_SCORING);
+    config.remote_scoring_enabled = value.has_value() && *value == "1";
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/rpc_protocol_config.cpp b/mooncake-store/src/config/rpc_protocol_config.cpp
new file mode 100644
index 0000000000..9c3b421a62
--- /dev/null
+++ b/mooncake-store/src/config/rpc_protocol_config.cpp
@@ -0,0 +1,14 @@
+#include "config/rpc_protocol_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+RpcProtocolConfig RpcProtocolConfig::FromEnvironment() {
+    using Variables = RpcProtocolEnvironmentVariables;
+    const auto value = Environ::Read(Variables::MC_RPC_PROTOCOL);
+    return RpcProtocolConfig{.use_rdma = value && *value == "rdma"};
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/rpc_timeout_config.cpp b/mooncake-store/src/config/rpc_timeout_config.cpp
new file mode 100644
index 0000000000..65777301be
--- /dev/null
+++ b/mooncake-store/src/config/rpc_timeout_config.cpp
@@ -0,0 +1,25 @@
+#include "config/rpc_timeout_config.h"
+
+#include <cstdlib>
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+RpcTimeoutConfig RpcTimeoutConfig::FromEnvironment() {
+    RpcTimeoutConfig config;
+    using Variables = RpcTimeoutEnvironmentVariables;
+    if (const auto value = Environ::Read(Variables::MC_RPC_TIMEOUT_MS)) {
+        config.request_timeout =
+            std::chrono::milliseconds{std::atoll(value->c_str())};
+    }
+    if (const auto value =
+            Environ::Read(Variables::MC_RPC_CONNECT_TIMEOUT_MS)) {
+        config.connect_timeout =
+            std::chrono::milliseconds{std::atoll(value->c_str())};
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/s3_client_config.cpp b/mooncake-store/src/config/s3_client_config.cpp
new file mode 100644
index 0000000000..1dafb3d1bb
--- /dev/null
+++ b/mooncake-store/src/config/s3_client_config.cpp
@@ -0,0 +1,44 @@
+#include "s3_client_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+S3ClientConfig S3ClientConfig::FromEnvironment() {
+    S3ClientConfig config;
+    config.region = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_REGION, config.region);
+    config.s3_endpoint =
+        Environ::ReadOr(S3ClientEnvironmentVariables::MOONCAKE_AWS_S3_ENDPOINT,
+                        config.s3_endpoint);
+    config.bucket_name =
+        Environ::ReadOr(S3ClientEnvironmentVariables::MOONCAKE_AWS_BUCKET_NAME,
+                        config.bucket_name);
+    config.access_key_id = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_ACCESS_KEY_ID,
+        config.access_key_id);
+    config.secret_access_key = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_SECRET_ACCESS_KEY,
+        config.secret_access_key);
+    config.use_virtual_addressing = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING,
+        config.use_virtual_addressing);
+    config.use_https = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_USE_HTTPS, config.use_https);
+    config.request_checksum_calculation = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION,
+        config.request_checksum_calculation);
+    config.response_checksum_validation = Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION,
+        config.response_checksum_validation);
+    config.connect_timeout = std::chrono::milliseconds(Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_CONNECT_TIMEOUT_MS,
+        config.connect_timeout.count()));
+    config.request_timeout = std::chrono::milliseconds(Environ::ReadOr(
+        S3ClientEnvironmentVariables::MOONCAKE_AWS_REQUEST_TIMEOUT_MS,
+        config.request_timeout.count()));
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/s3_client_config.h b/mooncake-store/src/config/s3_client_config.h
new file mode 100644
index 0000000000..178eb637df
--- /dev/null
+++ b/mooncake-store/src/config/s3_client_config.h
@@ -0,0 +1,24 @@
+#pragma once
+
+#include <chrono>
+#include <string>
+
+namespace mooncake {
+
+struct S3ClientConfig {
+    std::string region;
+    std::string s3_endpoint;
+    std::string bucket_name;
+    std::string access_key_id;
+    std::string secret_access_key;
+    bool use_virtual_addressing = true;
+    bool use_https = true;
+    std::string request_checksum_calculation;
+    std::string response_checksum_validation;
+    std::chrono::milliseconds connect_timeout{10000};
+    std::chrono::milliseconds request_timeout{30000};
+
+    static S3ClientConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/spdk_controller_config.cpp b/mooncake-store/src/config/spdk_controller_config.cpp
new file mode 100644
index 0000000000..b9bddd4982
--- /dev/null
+++ b/mooncake-store/src/config/spdk_controller_config.cpp
@@ -0,0 +1,26 @@
+#include "spdk_controller_config.h"
+
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+SpdkControllerConfig SpdkControllerConfig::FromEnvironment() {
+    SpdkControllerConfig config;
+    using Variables = SpdkControllerEnvironmentVariables;
+    config.num_io_queues = Environ::Read(Variables::MC_NVME_NUM_IO_QUEUES);
+    config.io_queue_size = Environ::Read(Variables::MC_NVME_IO_QUEUE_SIZE);
+    config.io_queue_requests =
+        Environ::Read(Variables::MC_NVME_IO_QUEUE_REQUESTS);
+    config.transport_ack_timeout =
+        Environ::Read(Variables::MC_NVME_TRANSPORT_ACK_TIMEOUT);
+    config.admin_queue_size =
+        Environ::Read(Variables::MC_NVME_ADMIN_QUEUE_SIZE);
+    config.fabrics_connect_timeout_us =
+        Environ::Read(Variables::MC_NVME_FABRICS_CONNECT_TIMEOUT_US);
+    config.header_digest = Environ::Read(Variables::MC_NVME_HEADER_DIGEST);
+    config.data_digest = Environ::Read(Variables::MC_NVME_DATA_DIGEST);
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/spdk_controller_config.h b/mooncake-store/src/config/spdk_controller_config.h
new file mode 100644
index 0000000000..be0a26ce2e
--- /dev/null
+++ b/mooncake-store/src/config/spdk_controller_config.h
@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+
+namespace mooncake {
+
+struct SpdkControllerConfig {
+    std::optional<uint32_t> num_io_queues;
+    std::optional<uint32_t> io_queue_size;
+    std::optional<uint32_t> io_queue_requests;
+    std::optional<uint8_t> transport_ack_timeout;
+    std::optional<uint16_t> admin_queue_size;
+    std::optional<uint64_t> fabrics_connect_timeout_us;
+    std::optional<bool> header_digest;
+    std::optional<bool> data_digest;
+
+    static SpdkControllerConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/transfer_submitter_config.cpp b/mooncake-store/src/config/transfer_submitter_config.cpp
new file mode 100644
index 0000000000..314419e61d
--- /dev/null
+++ b/mooncake-store/src/config/transfer_submitter_config.cpp
@@ -0,0 +1,36 @@
+#include "transfer_submitter_config.h"
+
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <cctype>
+
+#include "bool_parser.h"
+#include "environ.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+
+TransferSubmitterConfig TransferSubmitterConfig::FromEnvironment() {
+    TransferSubmitterConfig config;
+    auto value =
+        Environ::Read(TransferSubmitterEnvironmentVariables::MC_STORE_MEMCPY);
+    if (!value.has_value()) {
+        return config;
+    }
+
+    std::transform(value->begin(), value->end(), value->begin(),
+                   [](unsigned char c) { return std::tolower(c); });
+    const auto parsed = TryParseBool(*value, {.trim_ascii_whitespace = false});
+    // Reject enable/disable, which only the shared parser accepts.
+    if (parsed.has_value() && *value != "enable" && *value != "disable") {
+        config.memcpy_enabled_override = *parsed;
+    } else {
+        LOG(WARNING) << "Invalid value for MC_STORE_MEMCPY: " << *value
+                     << ", defaulting to enabled";
+        config.memcpy_enabled_override = true;
+    }
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/config/transfer_submitter_config.h b/mooncake-store/src/config/transfer_submitter_config.h
new file mode 100644
index 0000000000..e52e2b602a
--- /dev/null
+++ b/mooncake-store/src/config/transfer_submitter_config.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#include <optional>
+
+namespace mooncake {
+
+struct TransferSubmitterConfig {
+    // Unset leaves transport-dependent automatic selection to the submitter.
+    std::optional<bool> memcpy_enabled_override;
+
+    static TransferSubmitterConfig FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/device/cuda_ipc_buffer.cpp b/mooncake-store/src/device/cuda_ipc_buffer.cpp
index 5953ff57d4..317dcc040e 100644
--- a/mooncake-store/src/device/cuda_ipc_buffer.cpp
+++ b/mooncake-store/src/device/cuda_ipc_buffer.cpp
@@ -122,6 +122,37 @@ tl::expected<CudaIpcBufferHandle, ErrorCode> ExportCudaIpcBuffer(
 #endif
 }
 
+tl::expected<void, ErrorCode> SynchronizeCudaStream(int32_t device_id,
+                                                    uintptr_t stream_handle) {
+#if defined(USE_CUDA)
+    int current_device = -1;
+    if (cudaGetDevice(&current_device) != cudaSuccess) {
+        ClearCudaError();
+        return tl::unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+
+    cudaError_t operation_status = cudaSetDevice(device_id);
+    if (operation_status == cudaSuccess) {
+        const cudaStream_t stream =
+            stream_handle == 0 ? nullptr
+                               : reinterpret_cast<cudaStream_t>(stream_handle);
+        operation_status = cudaStreamSynchronize(stream);
+    }
+    if (operation_status != cudaSuccess) ClearCudaError();
+
+    const cudaError_t restore_status = cudaSetDevice(current_device);
+    if (restore_status != cudaSuccess) ClearCudaError();
+    if (operation_status != cudaSuccess || restore_status != cudaSuccess) {
+        return tl::unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return {};
+#else
+    (void)device_id;
+    (void)stream_handle;
+    return tl::unexpected(ErrorCode::INVALID_PARAMS);
+#endif
+}
+
 CudaIpcBufferMapping::~CudaIpcBufferMapping() { Close(); }
 
 CudaIpcBufferMapping::CudaIpcBufferMapping(
diff --git a/mooncake-store/src/device/runtime_accelerator.cpp b/mooncake-store/src/device/runtime_accelerator.cpp
index 7161fd469d..82acc0653c 100644
--- a/mooncake-store/src/device/runtime_accelerator.cpp
+++ b/mooncake-store/src/device/runtime_accelerator.cpp
@@ -51,5 +51,25 @@ bool RuntimeAccelerator::CopyFromHost(void* dst, const void* src,
     return accelerator->Copy(dst, src, size, CopyDirection::kHostToDevice);
 }
 
+bool RuntimeAccelerator::CopyAuto(void* dst, const void* src,
+                                  size_t size) const {
+    PointerInfo src_info, dst_info;
+    auto* src_device = FindDeviceForPointer(src, &src_info);
+    auto* dst_device = FindDeviceForPointer(dst, &dst_info);
+    if (!src_device && !dst_device) {
+        std::memcpy(dst, src, size);
+        return true;
+    }
+    // Two different accelerator runtimes cannot serve the same copy (same
+    // guard the MemcpyWorkerPool worker applies to its memcpy ops).
+    if (src_device && dst_device && src_device != dst_device) {
+        return false;
+    }
+    auto* accelerator = dst_device ? dst_device : src_device;
+    const auto& info = dst_device ? dst_info : src_info;
+    accelerator->SetContext(info.device_id);
+    return accelerator->Copy(dst, src, size, CopyDirection::kAuto);
+}
+
 }  // namespace device
 }  // namespace mooncake
diff --git a/mooncake-store/src/dummy_client.cpp b/mooncake-store/src/dummy_client.cpp
index bc726515d2..e17d4e4901 100644
--- a/mooncake-store/src/dummy_client.cpp
+++ b/mooncake-store/src/dummy_client.cpp
@@ -9,17 +9,21 @@
 #include <unistd.h>    // For ftruncate, close, shm_unlink
 #include <chrono>
 #include <cstdlib>
+#include <algorithm>
+#include <limits>
 
 #include "real_client.h"
 #include "dummy_client.h"
+#include "common/client_buffer_allocation.h"
 #include "uds_transport.h"
-#include "utils.h"
-#include "utils/scoped_vlog_timer.h"
+#include "common/result.h"
+#include "common/scoped_vlog_timer.h"
 #include "rpc_types.h"
 #include "types.h"
 #include "default_config.h"
 #include "config.h"
 #include "device/cuda_ipc_buffer.h"
+#include "device/accelerator_registry.h"
 #ifdef USE_ASCEND_DIRECT
 #include "acl/acl_rt.h"
 #include "ascend_allocator.h"
@@ -179,6 +183,10 @@ constexpr bool can_invoke_when_disconnected() {
 
 template <auto ServiceMethod, typename ReturnType, typename... Args>
 tl::expected<ReturnType, ErrorCode> DummyClient::invoke_rpc(Args&&... args) {
+    RpcDrainGuard::ScopedCall inflight(rpc_drain_);
+    if (!inflight.ok()) {
+        return tl::make_unexpected(ErrorCode::RPC_FAIL);
+    }
     auto pool = client_accessor_.GetClientPool();
 
     if constexpr (!can_invoke_when_disconnected<ServiceMethod>()) {
@@ -212,6 +220,11 @@ tl::expected<ReturnType, ErrorCode> DummyClient::invoke_rpc(Args&&... args) {
 template <auto ServiceMethod, typename ResultType, typename... Args>
 std::vector<tl::expected<ResultType, ErrorCode>> DummyClient::invoke_batch_rpc(
     size_t input_size, Args&&... args) {
+    RpcDrainGuard::ScopedCall inflight(rpc_drain_);
+    if (!inflight.ok()) {
+        return std::vector<tl::expected<ResultType, ErrorCode>>(
+            input_size, tl::make_unexpected(ErrorCode::RPC_FAIL));
+    }
     auto pool = client_accessor_.GetClientPool();
     if (!connected_.load()) {
         LOG(ERROR) << "Dummy Client not connected";
@@ -262,7 +275,28 @@ DummyClient::DummyClient()
     mooncake::init_ylt_log_level();
 }
 
-DummyClient::~DummyClient() { tearDownAll(); }
+DummyClient::~DummyClient() {
+    // Teardown-order invariant (review #3943): an in-flight RPC never touches
+    // the members tearDownAll() resets. The RPC path holds a ScopedCall
+    // across the whole round trip and otherwise touches only the client pool
+    // (kept alive process-wide by the registry), atomic flags like
+    // connected_, by-value arguments, and the drain's shared State.
+    // shm_helper_, the registered-buffer tables, the local/hot-cache mappings
+    // and the ping thread are only ever accessed synchronously on caller
+    // threads, outside the drain's scope; a caller racing ~DummyClient is a
+    // usage-level data race no teardown order can fix.
+    //
+    // The reverse order is impossible: unregister_shm() is itself an RPC and
+    // the ping thread is only joined inside tearDownAll(), so draining first
+    // would reject the unmap and spin the reconnection loop for the whole
+    // wait (#3943 review).
+    tearDownAll();
+    // Never release the pool under a suspended request coroutine (#3909).
+    if (!rpc_drain_.drain_for(std::chrono::seconds(30))) {
+        LOG(ERROR) << "DummyClient teardown: RPCs still in flight after 30s "
+                      "drain; releasing the pool regardless";
+    }
+}
 
 void DummyClient::ObserveTransferMetric(TransferOperationKind kind,
                                         const char* op_name, size_t bytes,
@@ -574,6 +608,8 @@ int DummyClient::tearDownAll() {
     }
     connected_.store(false);
     last_ping_healthy_.store(false);
+    std::lock_guard<std::mutex> lock(registered_external_buffers_mutex_);
+    registered_external_buffers_.clear();
 #if defined(USE_ASCEND_DIRECT)
     {
         std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
@@ -600,6 +636,267 @@ std::optional<BufferHandle> DummyClient::allocate_client_buffer(size_t size) {
                                             std::move(release));
 }
 
+bool DummyClient::is_dummy_shm_buffer(void* buffer, size_t size) const {
+    if (buffer == nullptr || shm_helper_ == nullptr) return false;
+    auto shm = shm_helper_->get_shm(buffer);
+    if (!shm) return false;
+    const uintptr_t base = reinterpret_cast<uintptr_t>(shm->base_addr);
+    const uintptr_t address = reinterpret_cast<uintptr_t>(buffer);
+    if (address < base || address - base > shm->size) return false;
+    return size <= shm->size - (address - base);
+}
+
+bool DummyClient::is_device_buffer(void* buffer) const {
+    return device::GetAcceleratorRegistry()
+               .RuntimeAccelerators()
+               .FindDeviceForPointer(buffer) != nullptr;
+}
+
+std::optional<size_t> DummyClient::external_buffer_remaining(
+    void* buffer) const {
+    const uintptr_t address = reinterpret_cast<uintptr_t>(buffer);
+    {
+        std::lock_guard<std::mutex> lock(registered_external_buffers_mutex_);
+        for (const auto& [base, registration] : registered_external_buffers_) {
+            if (address >= base && address - base <= registration.size) {
+                return registration.size - (address - base);
+            }
+        }
+    }
+
+#if defined(USE_ASCEND_DIRECT)
+    // Ascend device allocations are registered through register_ascend_shm()
+    // and tracked separately so they can be restored after reconnect.  Treat
+    // those mappings as registered external buffers for all transfer paths.
+    {
+        std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
+        for (const auto& [base, registration] : registered_device_buffers_) {
+            if (address >= base && address - base <= registration.size) {
+                return registration.size - (address - base);
+            }
+        }
+    }
+#endif
+
+    return std::nullopt;
+}
+
+bool DummyClient::is_registered_buffer(void* buffer, size_t size) const {
+    if (buffer == nullptr) return size == 0;
+    auto remaining = external_buffer_remaining(buffer);
+    return remaining.has_value() && size <= *remaining;
+}
+
+DummyClient::BufferRegistrationAction DummyClient::retain_buffer_registration(
+    BufferRegistrationMap& registrations, uintptr_t base, size_t size) {
+    const uintptr_t end = base + size;
+    for (const auto& [other_base, registration] : registrations) {
+        const uintptr_t other_end = other_base + registration.size;
+        if (base < other_end && other_base < end &&
+            (base != other_base || size != registration.size)) {
+            return BufferRegistrationAction::kReject;
+        }
+    }
+
+    auto [it, inserted] =
+        registrations.emplace(base, ExternalBufferRegistration{size, 1});
+    if (inserted) return BufferRegistrationAction::kFirst;
+    if (it->second.references == std::numeric_limits<size_t>::max()) {
+        return BufferRegistrationAction::kReject;
+    }
+    ++it->second.references;
+    return BufferRegistrationAction::kRetained;
+}
+
+DummyClient::BufferReleaseAction DummyClient::release_buffer_registration(
+    BufferRegistrationMap& registrations, uintptr_t base) {
+    auto it = registrations.find(base);
+    if (it == registrations.end()) return BufferReleaseAction::kReject;
+    if (it->second.references == 1) return BufferReleaseAction::kFinal;
+    --it->second.references;
+    return BufferReleaseAction::kRetained;
+}
+
+int DummyClient::register_external_buffer(void* buffer, size_t size) {
+    if (buffer == nullptr || size == 0) return -1;
+
+    const uintptr_t base = reinterpret_cast<uintptr_t>(buffer);
+    if (size > std::numeric_limits<uintptr_t>::max() - base) return -1;
+
+    std::lock_guard<std::mutex> lock(registered_external_buffers_mutex_);
+    if (retain_buffer_registration(registered_external_buffers_, base, size) ==
+        BufferRegistrationAction::kReject) {
+        LOG(ERROR) << "Invalid or overlapping external buffer registration";
+        return -1;
+    }
+    return 0;
+}
+
+int DummyClient::unregister_external_buffer(void* buffer) {
+    if (buffer == nullptr) return -1;
+
+    std::lock_guard<std::mutex> lock(registered_external_buffers_mutex_);
+    const uintptr_t base = reinterpret_cast<uintptr_t>(buffer);
+    const auto action =
+        release_buffer_registration(registered_external_buffers_, base);
+    if (action == BufferReleaseAction::kReject) return -1;
+    if (action == BufferReleaseAction::kFinal)
+        registered_external_buffers_.erase(base);
+    return 0;
+}
+
+#if defined(USE_ASCEND_DIRECT)
+std::optional<size_t> DummyClient::registered_ascend_buffer_remaining(
+    void* buffer) const {
+    const uintptr_t address = reinterpret_cast<uintptr_t>(buffer);
+    std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
+    for (const auto& [base, registration] : registered_device_buffers_) {
+        if (address >= base && address - base <= registration.size) {
+            return registration.size - (address - base);
+        }
+    }
+    return std::nullopt;
+}
+#endif
+
+std::optional<DummyClient::PreparedBuffer> DummyClient::prepare_buffer(
+    void* buffer, size_t size, bool copy_to_staging, bool copy_back) {
+    if (buffer == nullptr && size != 0) return std::nullopt;
+    if (buffer == nullptr) {
+        return PreparedBuffer{nullptr, nullptr, 0, nullptr, false};
+    }
+#if defined(USE_ASCEND_DIRECT)
+    if (auto remaining = registered_ascend_buffer_remaining(buffer)) {
+        if (size > *remaining) return std::nullopt;
+        return PreparedBuffer{buffer, buffer, size, nullptr, false};
+    }
+#endif
+    if (shm_helper_ != nullptr) {
+        auto shm = shm_helper_->get_shm(buffer);
+        if (shm != nullptr && !is_device_buffer(buffer)) {
+            if (!is_dummy_shm_buffer(buffer, size)) {
+                return std::nullopt;
+            } else {
+                return PreparedBuffer{buffer, buffer, size, nullptr, false};
+            }
+        }
+    }
+    auto remaining = external_buffer_remaining(buffer);
+    if (!remaining.has_value() || size > *remaining) return std::nullopt;
+
+    auto allocation = allocate_client_buffer(std::max<size_t>(size, 1));
+    if (!allocation) return std::nullopt;
+    auto staging = std::make_unique<BufferHandle>(std::move(*allocation));
+    if (copy_to_staging) {
+        const auto& runtime =
+            device::GetAcceleratorRegistry().RuntimeAccelerators();
+        if (!runtime.CopyToHost(staging->ptr(), buffer, size))
+            return std::nullopt;
+    }
+    return PreparedBuffer{buffer, staging->ptr(), size, std::move(staging),
+                          copy_back || !copy_to_staging};
+}
+
+std::optional<DummyClient::PreparedBuffer>
+DummyClient::prepare_ranged_read_buffer(
+    void* buffer, std::vector<std::vector<size_t>>& dst_offsets,
+    const std::vector<std::vector<size_t>>& sizes) {
+    if (buffer == nullptr) {
+        return PreparedBuffer{nullptr, nullptr, 0, nullptr, false};
+    }
+#if defined(USE_ASCEND_DIRECT)
+    if (auto remaining = registered_ascend_buffer_remaining(buffer)) {
+        return prepare_buffer(buffer, *remaining, false, true);
+    }
+#endif
+    if (auto remaining = external_buffer_remaining(buffer)) {
+        const size_t capacity = *remaining;
+        size_t staging_size = 0;
+        const size_t row_count = std::min(dst_offsets.size(), sizes.size());
+        for (size_t i = 0; i < row_count; ++i) {
+            const size_t fragment_count =
+                std::min(dst_offsets[i].size(), sizes[i].size());
+            for (size_t j = 0; j < fragment_count; ++j) {
+                const size_t offset = dst_offsets[i][j];
+                const size_t fragment_size = sizes[i][j];
+                if (offset > capacity || fragment_size > capacity - offset) {
+                    // Keep invalid destinations invalid after compaction, even
+                    // for zero-length fragments. RealClient reports each error.
+                    dst_offsets[i][j] = std::numeric_limits<size_t>::max();
+                    continue;
+                }
+                if (fragment_size >
+                    std::numeric_limits<size_t>::max() - staging_size) {
+                    return std::nullopt;
+                }
+                dst_offsets[i][j] = staging_size;
+                staging_size += fragment_size;
+            }
+        }
+        // Reserve only fragment bytes, not the unused prefix or sparse gaps.
+        // The original destination capacity remains the copy-back bound.
+        auto allocation =
+            allocate_client_buffer(std::max<size_t>(staging_size, 1));
+        if (!allocation) return std::nullopt;
+        auto staging = std::make_unique<BufferHandle>(std::move(*allocation));
+        return PreparedBuffer{buffer, staging->ptr(), capacity,
+                              std::move(staging), true};
+    }
+    if (shm_helper_ == nullptr) return std::nullopt;
+    auto shm = shm_helper_->get_shm(buffer);
+    if (shm == nullptr) return std::nullopt;
+
+    const uintptr_t base = reinterpret_cast<uintptr_t>(shm->base_addr);
+    const uintptr_t address = reinterpret_cast<uintptr_t>(buffer);
+    if (address < base || address - base > shm->size) return std::nullopt;
+    return prepare_buffer(buffer, shm->size - (address - base), false, true);
+}
+
+bool DummyClient::copy_from_staging(const PreparedBuffer& buffer, size_t size,
+                                    size_t offset,
+                                    size_t staging_offset) const {
+    if (!buffer.copy_back || buffer.staging == nullptr || size == 0)
+        return true;
+    if (offset > buffer.size || size > buffer.size - offset ||
+        staging_offset > buffer.staging->size() ||
+        size > buffer.staging->size() - staging_offset)
+        return false;
+    const auto& runtime =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
+    auto* destination = static_cast<uint8_t*>(buffer.original) + offset;
+    auto* source =
+        static_cast<uint8_t*>(buffer.staging->ptr()) + staging_offset;
+    return runtime.CopyFromHost(destination, source, size);
+}
+
+std::optional<DummyClient::PreparedMultiBuffers>
+DummyClient::prepare_multi_buffers(
+    const std::vector<std::vector<void*>>& all_buffers,
+    const std::vector<std::vector<size_t>>& all_sizes, bool copy_to_staging,
+    bool copy_back) {
+    if (all_buffers.size() != all_sizes.size()) return std::nullopt;
+
+    PreparedMultiBuffers prepared;
+    prepared.dummy_buffers = void_ptr_rows_to_u64_nested(all_buffers);
+    size_t total_buffers = 0;
+    for (const auto& buffers : all_buffers) total_buffers += buffers.size();
+    prepared.buffers.reserve(total_buffers);
+    for (size_t i = 0; i < all_buffers.size(); ++i) {
+        if (all_buffers[i].size() != all_sizes[i].size()) {
+            return std::nullopt;
+        }
+        for (size_t j = 0; j < all_buffers[i].size(); ++j) {
+            auto buffer = prepare_buffer(all_buffers[i][j], all_sizes[i][j],
+                                         copy_to_staging, copy_back);
+            if (!buffer) return std::nullopt;
+            prepared.dummy_buffers[i][j] =
+                reinterpret_cast<uint64_t>(buffer->dummy);
+            prepared.buffers.emplace_back(std::move(*buffer));
+        }
+    }
+    return prepared;
+}
+
 int64_t DummyClient::unregister_shm() {
     LOG(INFO) << "[unregister_shm] client_id=" << client_id_;
 #if defined(USE_ASCEND_DIRECT)
@@ -616,72 +913,92 @@ int64_t DummyClient::unregister_shm() {
 #if defined(USE_ASCEND_DIRECT)
 int DummyClient::register_device_buffer_for_reconnect(void* buffer,
                                                       size_t size) {
-    const auto buffer_addr = reinterpret_cast<uint64_t>(buffer);
-    {
-        std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
-        auto it = registered_device_buffers_.find(buffer_addr);
-        if (it != registered_device_buffers_.end() && it->second != size) {
-            LOG(ERROR) << "Device buffer size mismatch for tracked buffer, "
-                       << "buffer=" << buffer << ", size=" << size
-                       << ", tracked_size=" << it->second;
-            return -1;
-        }
+    const auto buffer_addr = reinterpret_cast<uintptr_t>(buffer);
+    if (size == 0 ||
+        size > std::numeric_limits<uintptr_t>::max() - buffer_addr) {
+        LOG(ERROR) << "Device buffer registration overflows address range";
+        return -1;
+    }
+
+    std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
+    const auto action = retain_buffer_registration(registered_device_buffers_,
+                                                   buffer_addr, size);
+    if (action == BufferRegistrationAction::kReject) {
+        LOG(ERROR) << "Invalid or overlapping device buffer registration, "
+                   << "buffer=" << buffer << ", size=" << size;
+        return -1;
     }
+    if (action == BufferRegistrationAction::kRetained) return 0;
 
     ShmHelper::ShmSegment shm{};
     shm.base_addr = buffer;
     shm.size = size;
     if (register_ascend_shm(&shm, false) != 0) {
+        registered_device_buffers_.erase(buffer_addr);
         LOG(ERROR) << "Failed to register device buffer, buffer=" << buffer
                    << ", size=" << size;
         return -1;
     }
 
-    {
-        std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
-        registered_device_buffers_[buffer_addr] = size;
-    }
     return 0;
 }
 
 int DummyClient::unregister_device_buffer_for_reconnect(void* buffer) {
-    const auto buffer_addr = reinterpret_cast<uint64_t>(buffer);
-    {
-        std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
-        if (registered_device_buffers_.find(buffer_addr) ==
-            registered_device_buffers_.end()) {
-            LOG(ERROR) << "Device buffer is not registered with RealClient";
-            return -1;
-        }
+    const auto buffer_addr = reinterpret_cast<uintptr_t>(buffer);
+    std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
+    const auto action =
+        release_buffer_registration(registered_device_buffers_, buffer_addr);
+    if (action == BufferReleaseAction::kReject) {
+        LOG(ERROR) << "Device buffer is not registered with RealClient";
+        return -1;
     }
+    if (action == BufferReleaseAction::kRetained) return 0;
 
     auto ret = invoke_rpc<&RealClient::unregister_shm_buffer_internal, void>(
-        buffer_addr, client_id_);
-    if (ret.has_value()) {
-        std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
+        static_cast<uint64_t>(buffer_addr), client_id_);
+    // Same contract as unregister_buffer: the receiver removes the mapping on
+    // INTERNAL_ERROR too (unmapped, or quarantined when the SPDK or transfer
+    // engine unregister fails), and INVALID_PARAMS means the server has no such
+    // mapping, so drop the local bookkeeping then; keep it on RPC_FAIL /
+    // RPC_TIMEOUT where the server may not have run (see unregister_buffer).
+    // No extra locking here: the function-scope lock above is already held.
+    if (ret.has_value() ||
+        (!ret.has_value() && (ret.error() == ErrorCode::INTERNAL_ERROR ||
+                              ret.error() == ErrorCode::INVALID_PARAMS))) {
         registered_device_buffers_.erase(buffer_addr);
     }
     return to_py_ret(ret);
 }
 
-std::vector<ShmHelper::ShmSegment> DummyClient::get_registered_device_buffers()
-    const {
-    std::vector<ShmHelper::ShmSegment> device_buffers;
+int DummyClient::reregister_fabric_buffers() {
+    std::lock_guard<std::mutex> registration_lock(
+        external_fabric_registration_mutex_);
+    std::lock_guard<std::mutex> lock(registered_external_buffers_mutex_);
+    for (const auto& [buffer_addr, registration] :
+         registered_external_buffers_) {
+        ShmHelper::ShmSegment shm{};
+        shm.base_addr = reinterpret_cast<void*>(buffer_addr);
+        shm.size = registration.size;
+        if (register_ascend_shm(&shm, false) != 0) return -1;
+    }
+    return 0;
+}
+
+int DummyClient::reregister_device_buffers() {
     std::lock_guard<std::mutex> lock(registered_device_buffers_mutex_);
-    device_buffers.reserve(registered_device_buffers_.size());
-    for (const auto& [buffer_addr, size] : registered_device_buffers_) {
+    for (const auto& [buffer_addr, registration] : registered_device_buffers_) {
         ShmHelper::ShmSegment shm{};
         shm.base_addr = reinterpret_cast<void*>(buffer_addr);
-        shm.size = size;
-        device_buffers.push_back(std::move(shm));
+        shm.size = registration.size;
+        if (register_ascend_shm(&shm, false) != 0) return -1;
     }
-    return device_buffers;
+    return 0;
 }
 #endif
 
 // Dummy only register buffer within the shared memory region
 int DummyClient::register_buffer(void* buffer, size_t size) {
-    if (buffer == nullptr) {
+    if (buffer == nullptr || size == 0) {
         LOG(ERROR) << "Invalid buffer pointer";
         return -1;
     }
@@ -697,10 +1014,23 @@ int DummyClient::register_buffer(void* buffer, size_t size) {
             return register_device_buffer_for_reconnect(buffer, size);
         }
         if (globalConfig().ascend_use_fabric_mem) {
+            std::lock_guard<std::mutex> registration_lock(
+                external_fabric_registration_mutex_);
             auto shm = std::make_shared<ShmHelper::ShmSegment>();
             shm->base_addr = buffer;
             shm->size = size;
+
+            // Fabric host buffers are mapped by register_ascend_shm(), but
+            // unlike Dummy SHM they are not discoverable through ShmHelper.
+            // Track the range locally so put/get/ranged-read validation can
+            // accept the same subranges after registration.
+            if (register_external_buffer(buffer, size) != 0) {
+                LOG(ERROR) << "Invalid or overlapping Fabric buffer"
+                           << ", buffer=" << buffer << ", size=" << size;
+                return -1;
+            }
             if (register_ascend_shm(shm.get(), false) != 0) {
+                (void)unregister_external_buffer(buffer);
                 LOG(ERROR) << "Failed to register buffer, buffer=" << buffer
                            << ", size=" << size;
                 return -1;
@@ -710,23 +1040,35 @@ int DummyClient::register_buffer(void* buffer, size_t size) {
         // non-Fabric Host: same rules as shm
     }
 #endif
-    // Find which shm this buffer belongs to
+    if (shm_helper_ == nullptr) return -1;
     auto shm = shm_helper_->get_shm(buffer);
+    if (shm && is_device_buffer(buffer)) shm = nullptr;
     if (!shm) {
-        LOG(ERROR) << "Buffer is not in any registered shared memory";
-        return -1;
+        return register_external_buffer(buffer, size);
     }
     if (shm_helper_->is_hugepage()) {
-        size = align_up(size, get_hugepage_size_from_env());
+        const size_t alignment = get_hugepage_size_from_env();
+        if (alignment != 0 &&
+            size > std::numeric_limits<size_t>::max() - (alignment - 1)) {
+            LOG(ERROR) << "Buffer size overflows hugepage alignment";
+            return -1;
+        }
+        size = align_up(size, alignment);
     }
-    // Check bounds
+    // Check bounds. The buffer must be the segment base and the size must match
+    // either the caller's original request (ShmSegment::requested_size) or the
+    // padded mapping size (shm->size, aligned up to the hugepage/2MB boundary
+    // for SPDK registration). Both are valid: IPC always sends shm->size, and
+    // legacy callers may pass the padded size directly.
     if (reinterpret_cast<uint8_t*>(buffer) !=
             reinterpret_cast<uint8_t*>(shm->base_addr) ||
-        size != shm->size) {
+        (size != shm->requested_size && size != shm->size)) {
         LOG(ERROR) << "Invalid buffer address or size for registration: "
                       "Buffer addr: "
                    << buffer << ", need addr: " << shm->base_addr
-                   << ", buffer size: " << size << ", need size: " << shm->size;
+                   << ", buffer size: " << size
+                   << ", need size: " << shm->requested_size
+                   << " (padded: " << shm->size << ")";
         return -1;
     }
 
@@ -750,19 +1092,44 @@ int DummyClient::unregister_buffer(void* buffer) {
 
 #if defined(USE_ASCEND_DIRECT)
     if (globalConfig().ascend_agent_mode) {
+        if (globalConfig().ascend_use_fabric_mem) {
+            std::lock_guard<std::mutex> registration_lock(
+                external_fabric_registration_mutex_);
+            const auto address = reinterpret_cast<uintptr_t>(buffer);
+            std::lock_guard<std::mutex> lock(
+                registered_external_buffers_mutex_);
+            const auto action = release_buffer_registration(
+                registered_external_buffers_, address);
+            if (action != BufferReleaseAction::kReject) {
+                if (action == BufferReleaseAction::kRetained) return 0;
+
+                // Keep the local registration until the real-side mapping is
+                // removed successfully.  This makes a failed unregister
+                // retryable instead of silently losing the range.
+                auto ret =
+                    invoke_rpc<&RealClient::unregister_shm_buffer_internal,
+                               void>(static_cast<uint64_t>(address),
+                                     client_id_);
+                if (ret.has_value())
+                    registered_external_buffers_.erase(address);
+                return to_py_ret(ret);
+            }
+        }
         aclrtPtrAttributes attributes{};
         auto acl_ret = aclrtPointerGetAttributes(buffer, &attributes);
         if (acl_ret == ACL_ERROR_NONE &&
-            attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
+            (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE ||
+             globalConfig().ascend_use_fabric_mem)) {
             return unregister_device_buffer_for_reconnect(buffer);
         }
     }
 #endif
 
+    if (shm_helper_ == nullptr) return -1;
     auto shm = shm_helper_->get_shm(buffer);
+    if (shm && is_device_buffer(buffer)) shm = nullptr;
     if (!shm) {
-        LOG(ERROR) << "Buffer is not in any registered shared memory";
-        return -1;
+        return unregister_external_buffer(buffer);
     }
     if (!shm->registered) {
         LOG(ERROR) << "Buffer is not registered with RealClient";
@@ -775,7 +1142,20 @@ int DummyClient::unregister_buffer(void* buffer) {
     }
     auto ret = invoke_rpc<&RealClient::unregister_shm_buffer_internal, void>(
         reinterpret_cast<uint64_t>(buffer), client_id_);
-    if (ret.has_value()) {
+    // INTERNAL_ERROR means the receiver still executed the teardown and removed
+    // the segment from its active mappings: it unmaps normally, or -- when the
+    // SPDK or transfer engine unregister fails -- quarantines the mapping
+    // (retained, never reused for new registrations). Either way the old
+    // mapping is no longer usable on the receiver, so drop the local flag for
+    // INTERNAL_ERROR and for INVALID_PARAMS (server has no such mapping). Keep
+    // it on RPC_FAIL / RPC_TIMEOUT: the RPC may never have reached the server,
+    // or the receiver may have refused before touching anything (Ascend context
+    // setup failure in unregister_shm_buffer_internal returns RPC_FAIL for
+    // exactly that reason), so the mapping can still be alive and a retry must
+    // reach the receiver.
+    if (ret.has_value() ||
+        (!ret.has_value() && (ret.error() == ErrorCode::INTERNAL_ERROR ||
+                              ret.error() == ErrorCode::INVALID_PARAMS))) {
         shm->registered = false;
     }
     return to_py_ret(ret);
@@ -823,7 +1203,9 @@ int DummyClient::upsert(const std::string& key, std::span<const char> value,
 
 int DummyClient::upsert_from(const std::string& key, void* buffer, size_t size,
                              const ReplicateConfig& config) {
-    uint64_t dummy_addr = reinterpret_cast<uint64_t>(buffer);
+    auto prepared = prepare_buffer(buffer, size, true);
+    if (!prepared) return toInt(ErrorCode::INVALID_PARAMS);
+    const uint64_t dummy_addr = reinterpret_cast<uint64_t>(prepared->dummy);
     return invoke_observed_void_rpc<&RealClient::upsert_from_dummy_helper>(
         TransferOperationKind::kWrite, "upsert_from", size, false, key,
         dummy_addr, size, config, client_id_);
@@ -832,9 +1214,21 @@ int DummyClient::upsert_from(const std::string& key, void* buffer, size_t size,
 std::vector<int> DummyClient::batch_upsert_from(
     const std::vector<std::string>& keys, const std::vector<void*>& buffer_ptrs,
     const std::vector<size_t>& sizes, const ReplicateConfig& config) {
+    if (keys.size() != buffer_ptrs.size() || keys.size() != sizes.size()) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    std::vector<PreparedBuffer> prepared;
     std::vector<uint64_t> buffers;
-    for (auto ptr : buffer_ptrs) {
-        buffers.push_back(reinterpret_cast<uint64_t>(ptr));
+    prepared.reserve(keys.size());
+    buffers.reserve(keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        auto item = prepare_buffer(buffer_ptrs[i], sizes[i], true);
+        if (!item) {
+            return std::vector<int>(keys.size(),
+                                    toInt(ErrorCode::INVALID_PARAMS));
+        }
+        buffers.push_back(reinterpret_cast<uint64_t>(item->dummy));
+        prepared.push_back(std::move(*item));
     }
     const auto start_time = std::chrono::steady_clock::now();
     auto internal_results =
@@ -928,6 +1322,36 @@ std::vector<int> DummyClient::batchIsExist(
     return results;
 }
 
+int DummyClient::probeKey(const std::string& key) {
+    auto result = invoke_rpc<&RealClient::probeKey_internal, bool>(key);
+
+    if (result.has_value()) {
+        return *result ? 1 : 0;  // 1 if exists, 0 if not
+    } else {
+        return toInt(result.error());
+    }
+}
+
+std::vector<int> DummyClient::batchProbeKey(
+    const std::vector<std::string>& keys) {
+    auto internal_results =
+        invoke_batch_rpc<&RealClient::batchProbeKey_internal, bool>(keys.size(),
+                                                                    keys);
+    std::vector<int> results;
+    results.reserve(internal_results.size());
+
+    for (const auto& result : internal_results) {
+        if (result.has_value()) {
+            results.push_back(result.value() ? 1 : 0);
+        } else {
+            LOG(ERROR) << "Batch probeKey failed: " << toString(result.error());
+            results.push_back(-1);
+        }
+    }
+
+    return results;
+}
+
 int64_t DummyClient::getSize(const std::string& key) {
     return to_py_ret(invoke_rpc<&RealClient::getSize_internal, int64_t>(key));
 }
@@ -1056,29 +1480,36 @@ std::vector<std::shared_ptr<BufferHandle>> DummyClient::batch_get_buffer(
 
 int64_t DummyClient::get_into(const std::string& key, void* buffer,
                               size_t size) {
-    if (auto dst_buffer = try_export_cuda_ipc_buffers({buffer}, {size})) {
-        std::vector<CudaIpcReadRequest> requests{
-            CudaIpcReadRequest{
-                .key = key,
-                .destination = (*dst_buffer)[0],
-                .source_offset = 0,
-                .size = static_cast<uint64_t>(size),
-            },
-        };
-        auto results = batch_get_into_cuda_ipc(requests);
-        return results.empty() ? toInt(ErrorCode::INVALID_PARAMS) : results[0];
+    if (is_registered_buffer(buffer, size)) {
+        if (auto dst_buffer = try_export_cuda_ipc_buffers({buffer}, {size})) {
+            std::vector<CudaIpcReadRequest> requests{
+                CudaIpcReadRequest{
+                    .key = key,
+                    .destination = (*dst_buffer)[0],
+                    .source_offset = 0,
+                    .size = static_cast<uint64_t>(size),
+                },
+            };
+            auto results = batch_get_into_cuda_ipc(requests);
+            return results.empty() ? toInt(ErrorCode::INVALID_PARAMS)
+                                   : results[0];
+        }
     }
 
-    uint64_t buf_addr = reinterpret_cast<uint64_t>(buffer);
+    auto prepared = prepare_buffer(buffer, size, false, true);
+    if (!prepared) return toInt(ErrorCode::INVALID_PARAMS);
+    const uint64_t dummy_addr = reinterpret_cast<uint64_t>(prepared->dummy);
     const auto start_time = std::chrono::steady_clock::now();
     auto result = invoke_rpc<&RealClient::get_into_range_shm_helper,
                              tl::expected<int64_t, ErrorCode>>(
-        key, buf_addr, 0, 0, size, true, true, client_id_);
-    if (!result) {
-        return static_cast<int64_t>(toInt(result.error()));
-    }
+        key, dummy_addr, 0, 0, size, true, true, client_id_);
+    if (!result) return static_cast<int64_t>(toInt(result.error()));
+
     const int64_t bytes_read = to_py_ret(*result);
     if (bytes_read >= 0) {
+        if (!copy_from_staging(*prepared, static_cast<size_t>(bytes_read))) {
+            return toInt(ErrorCode::INTERNAL_ERROR);
+        }
         ObserveTransferMetric(TransferOperationKind::kRead, "get_into",
                               static_cast<size_t>(bytes_read),
                               elapsed_us_since(start_time), false);
@@ -1093,16 +1524,69 @@ std::vector<std::vector<std::vector<int64_t>>> DummyClient::get_into_ranges(
     const std::vector<std::vector<std::vector<size_t>>>& all_src_offsets,
     const std::vector<std::vector<std::vector<size_t>>>& all_sizes,
     const QueryResultCache* query_result_cache) {
+    if (buffers.size() != all_keys.size() ||
+        buffers.size() != all_dst_offsets.size() ||
+        buffers.size() != all_src_offsets.size() ||
+        buffers.size() != all_sizes.size()) {
+        return build_ranged_read_error_results(buffers.size(), all_keys,
+                                               all_dst_offsets,
+                                               ErrorCode::INVALID_PARAMS);
+    }
+
+    std::vector<PreparedBuffer> prepared;
     std::vector<uint64_t> dummy_buffers = void_ptrs_to_u64(buffers);
+    std::vector<size_t> dummy_buffer_sizes;
+    auto dummy_dst_offsets = all_dst_offsets;
+    bool requires_staging = false;
+    prepared.reserve(buffers.size());
+    dummy_buffer_sizes.reserve(buffers.size());
+    for (size_t i = 0; i < buffers.size(); ++i) {
+        if (all_keys[i].size() != all_dst_offsets[i].size() ||
+            all_keys[i].size() != all_src_offsets[i].size() ||
+            all_keys[i].size() != all_sizes[i].size()) {
+            return build_ranged_read_error_results(buffers.size(), all_keys,
+                                                   all_dst_offsets,
+                                                   ErrorCode::INVALID_PARAMS);
+        }
+        for (size_t j = 0; j < all_dst_offsets[i].size(); ++j) {
+            if (all_dst_offsets[i][j].size() != all_src_offsets[i][j].size() ||
+                all_dst_offsets[i][j].size() != all_sizes[i][j].size()) {
+                return build_ranged_read_error_results(
+                    buffers.size(), all_keys, all_dst_offsets,
+                    ErrorCode::INVALID_PARAMS);
+            }
+        }
+
+        auto item = prepare_ranged_read_buffer(buffers[i], dummy_dst_offsets[i],
+                                               all_sizes[i]);
+        if (!item) {
+            return build_ranged_read_error_results(buffers.size(), all_keys,
+                                                   all_dst_offsets,
+                                                   ErrorCode::INVALID_PARAMS);
+        }
+        dummy_buffers[i] = reinterpret_cast<uint64_t>(item->dummy);
+        dummy_buffer_sizes.push_back(item->staging ? item->staging->size()
+                                                   : item->size);
+        requires_staging |= item->staging != nullptr;
+        prepared.push_back(std::move(*item));
+    }
+
     auto cached_query_results =
         build_cached_query_results_from_query_result_cache(query_result_cache);
     const auto start_time = std::chrono::steady_clock::now();
+    using RangedReadResults =
+        std::vector<std::vector<std::vector<tl::expected<int64_t, ErrorCode>>>>;
     auto internal_results =
-        invoke_rpc<&RealClient::get_into_ranges_shm_helper,
-                   std::vector<std::vector<
-                       std::vector<tl::expected<int64_t, ErrorCode>>>>>(
-            dummy_buffers, all_keys, all_dst_offsets, all_src_offsets,
-            all_sizes, cached_query_results, device_id_, client_id_);
+        requires_staging
+            ? invoke_rpc<&RealClient::get_into_ranges_staged_shm_helper,
+                         RangedReadResults>(
+                  dummy_buffers, dummy_buffer_sizes, all_keys,
+                  dummy_dst_offsets, all_src_offsets, all_sizes,
+                  cached_query_results, device_id_, client_id_)
+            : invoke_rpc<&RealClient::get_into_ranges_shm_helper,
+                         RangedReadResults>(
+                  dummy_buffers, all_keys, all_dst_offsets, all_src_offsets,
+                  all_sizes, cached_query_results, device_id_, client_id_);
 
     if (!internal_results) {
         LOG(ERROR) << "get_into_ranges RPC failed";
@@ -1111,6 +1595,50 @@ std::vector<std::vector<std::vector<int64_t>>> DummyClient::get_into_ranges(
                                                internal_results.error());
     }
     auto results = convert_ranged_read_results(internal_results.value());
+    if (results.size() != prepared.size()) {
+        LOG(ERROR) << "get_into_ranges response size mismatch: expected "
+                   << prepared.size() << ", got " << results.size();
+        return build_ranged_read_error_results(buffers.size(), all_keys,
+                                               all_dst_offsets,
+                                               ErrorCode::INTERNAL_ERROR);
+    }
+    for (size_t i = 0; i < results.size(); ++i) {
+        if (results[i].size() != all_keys[i].size()) {
+            LOG(ERROR) << "get_into_ranges response key count mismatch at " << i
+                       << ": expected " << all_keys[i].size() << ", got "
+                       << results[i].size();
+            return build_ranged_read_error_results(buffers.size(), all_keys,
+                                                   all_dst_offsets,
+                                                   ErrorCode::INTERNAL_ERROR);
+        }
+        for (size_t j = 0; j < results[i].size(); ++j) {
+            if (results[i][j].size() != all_sizes[i][j].size()) {
+                LOG(ERROR)
+                    << "get_into_ranges response fragment count mismatch at ["
+                    << i << "][" << j << "]: expected "
+                    << all_sizes[i][j].size() << ", got "
+                    << results[i][j].size();
+                return build_ranged_read_error_results(
+                    buffers.size(), all_keys, all_dst_offsets,
+                    ErrorCode::INTERNAL_ERROR);
+            }
+        }
+    }
+
+    for (size_t i = 0; i < results.size(); ++i) {
+        for (size_t j = 0; j < results[i].size(); ++j) {
+            for (size_t k = 0; k < results[i][j].size(); ++k) {
+                auto& result = results[i][j][k];
+                if (result < 0) continue;
+                if (static_cast<uint64_t>(result) > all_sizes[i][j][k] ||
+                    !copy_from_staging(prepared[i], static_cast<size_t>(result),
+                                       all_dst_offsets[i][j][k],
+                                       dummy_dst_offsets[i][j][k])) {
+                    result = toInt(ErrorCode::INTERNAL_ERROR);
+                }
+            }
+        }
+    }
     const size_t total_bytes = sum_positive_ranges(results);
     if (total_bytes > 0) {
         ObserveTransferMetric(TransferOperationKind::kRead, "get_into_ranges",
@@ -1119,6 +1647,18 @@ std::vector<std::vector<std::vector<int64_t>>> DummyClient::get_into_ranges(
     return results;
 }
 
+std::vector<std::vector<std::vector<int64_t>>>
+DummyClient::get_into_ranges_from_snapshot(
+    const std::vector<void*>& buffers,
+    const std::vector<std::vector<std::string>>& all_keys,
+    const std::vector<std::vector<std::vector<size_t>>>& all_dst_offsets,
+    const std::vector<std::vector<std::vector<size_t>>>& all_src_offsets,
+    const std::vector<std::vector<std::vector<size_t>>>& all_sizes,
+    const QueryResultCache& query_result_cache) {
+    return get_into_ranges(buffers, all_keys, all_dst_offsets, all_src_offsets,
+                           all_sizes, &query_result_cache);
+}
+
 std::vector<tl::expected<QueryResult, ErrorCode>> DummyClient::batch_query(
     const std::vector<std::string>& keys) {
     auto cached_results =
@@ -1153,21 +1693,49 @@ std::string DummyClient::get_hostname() const {
 std::vector<int> DummyClient::batch_put_from(
     const std::vector<std::string>& keys, const std::vector<void*>& buffer_ptrs,
     const std::vector<size_t>& sizes, const ReplicateConfig& config) {
-    if (auto payloads = try_export_cuda_ipc_buffers(buffer_ptrs, sizes);
-        payloads && keys.size() == payloads->size()) {
-        std::vector<CudaIpcWriteRequest> requests;
-        requests.reserve(keys.size());
-        for (size_t i = 0; i < keys.size(); ++i) {
-            requests.push_back(CudaIpcWriteRequest{
-                .key = keys[i],
-                .metadata = CudaIpcShmBufferRef{},
-                .payload = (*payloads)[i],
-            });
+    if (keys.size() != buffer_ptrs.size() || keys.size() != sizes.size()) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    // CUDA IPC requests carry a process-local allocation handle.  Only export
+    // buffers that are currently registered with the Dummy client; otherwise
+    // an unregistered allocation (or a stale pointer after unregister) would
+    // bypass prepare_buffer()'s bounds and lifetime checks.
+    bool all_buffers_registered = true;
+    for (size_t i = 0; i < buffer_ptrs.size(); ++i) {
+        if (!is_registered_buffer(buffer_ptrs[i], sizes[i])) {
+            all_buffers_registered = false;
+            break;
+        }
+    }
+    if (all_buffers_registered) {
+        if (auto payloads = try_export_cuda_ipc_buffers(buffer_ptrs, sizes);
+            payloads && keys.size() == payloads->size()) {
+            std::vector<CudaIpcWriteRequest> requests;
+            requests.reserve(keys.size());
+            for (size_t i = 0; i < keys.size(); ++i) {
+                requests.push_back(CudaIpcWriteRequest{
+                    .key = keys[i],
+                    .metadata = CudaIpcShmBufferRef{},
+                    .payload = (*payloads)[i],
+                });
+            }
+            return batch_put_from_cuda_ipc(requests, config);
         }
-        return batch_put_from_cuda_ipc(requests, config);
     }
 
-    std::vector<uint64_t> buffers = void_ptrs_to_u64(buffer_ptrs);
+    std::vector<PreparedBuffer> prepared;
+    std::vector<uint64_t> buffers;
+    prepared.reserve(keys.size());
+    buffers.reserve(keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        auto item = prepare_buffer(buffer_ptrs[i], sizes[i], true);
+        if (!item) {
+            return std::vector<int>(keys.size(),
+                                    toInt(ErrorCode::INVALID_PARAMS));
+        }
+        buffers.push_back(reinterpret_cast<uint64_t>(item->dummy));
+        prepared.push_back(std::move(*item));
+    }
     const auto start_time = std::chrono::steady_clock::now();
     auto internal_results =
         invoke_batch_rpc<&RealClient::batch_put_from_dummy_helper, void>(
@@ -1198,28 +1766,62 @@ int DummyClient::put_from(const std::string& key, void* buffer, size_t size,
 std::vector<int64_t> DummyClient::batch_get_into(
     const std::vector<std::string>& keys, const std::vector<void*>& buffer_ptrs,
     const std::vector<size_t>& sizes) {
-    if (auto dst_buffers = try_export_cuda_ipc_buffers(buffer_ptrs, sizes);
-        dst_buffers && keys.size() == dst_buffers->size()) {
-        std::vector<CudaIpcReadRequest> requests;
-        requests.reserve(keys.size());
-        for (size_t i = 0; i < keys.size(); ++i) {
-            requests.push_back(CudaIpcReadRequest{
-                .key = keys[i],
-                .destination = (*dst_buffers)[i],
-                .source_offset = 0,
-                .size = static_cast<uint64_t>(sizes[i]),
-            });
+    if (keys.size() != buffer_ptrs.size() || keys.size() != sizes.size()) {
+        return std::vector<int64_t>(keys.size(),
+                                    toInt(ErrorCode::INVALID_PARAMS));
+    }
+    // Keep the CUDA IPC fast path subject to the same registration and range
+    // checks as the staging path below.
+    bool all_buffers_registered = true;
+    for (size_t i = 0; i < buffer_ptrs.size(); ++i) {
+        if (!is_registered_buffer(buffer_ptrs[i], sizes[i])) {
+            all_buffers_registered = false;
+            break;
+        }
+    }
+    if (all_buffers_registered) {
+        if (auto dst_buffers = try_export_cuda_ipc_buffers(buffer_ptrs, sizes);
+            dst_buffers && keys.size() == dst_buffers->size()) {
+            std::vector<CudaIpcReadRequest> requests;
+            requests.reserve(keys.size());
+            for (size_t i = 0; i < keys.size(); ++i) {
+                requests.push_back(CudaIpcReadRequest{
+                    .key = keys[i],
+                    .destination = (*dst_buffers)[i],
+                    .source_offset = 0,
+                    .size = static_cast<uint64_t>(sizes[i]),
+                });
+            }
+            return batch_get_into_cuda_ipc(requests);
         }
-        return batch_get_into_cuda_ipc(requests);
     }
 
-    std::vector<uint64_t> buffers = void_ptrs_to_u64(buffer_ptrs);
+    std::vector<PreparedBuffer> prepared;
+    std::vector<uint64_t> buffers;
+    prepared.reserve(keys.size());
+    buffers.reserve(keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        auto item = prepare_buffer(buffer_ptrs[i], sizes[i], false, true);
+        if (!item) {
+            return std::vector<int64_t>(keys.size(),
+                                        toInt(ErrorCode::INVALID_PARAMS));
+        }
+        buffers.push_back(reinterpret_cast<uint64_t>(item->dummy));
+        prepared.push_back(std::move(*item));
+    }
     const auto start_time = std::chrono::steady_clock::now();
     auto internal_results =
         invoke_batch_rpc<&RealClient::batch_get_into_dummy_helper, int64_t>(
             keys.size(), keys, buffers, sizes, device_id_, client_id_);
     auto results = expected_results_to_py(internal_results);
 
+    for (size_t i = 0; i < results.size() && i < prepared.size(); ++i) {
+        if (results[i] >= 0 &&
+            !copy_from_staging(prepared[i], static_cast<size_t>(results[i]))) {
+            results[i] = toInt(ErrorCode::INTERNAL_ERROR);
+        }
+    }
+
     const size_t total_bytes = sum_positive_results(results);
     if (total_bytes > 0) {
         ObserveTransferMetric(TransferOperationKind::kRead, "batch_get_into",
@@ -1251,8 +1853,13 @@ int DummyClient::put_from_with_metadata(const std::string& key, void* buffer,
                                         void* metadata_buffer, size_t size,
                                         size_t metadata_size,
                                         const ReplicateConfig& config) {
-    auto results = batch_put_from_multi_buffers(
-        {key}, {{metadata_buffer, buffer}}, {{metadata_size, size}}, config);
+    std::vector<std::vector<void*>> buffers = {{metadata_buffer}};
+    std::vector<std::vector<size_t>> sizes = {{metadata_size}};
+    if (size > 0) {
+        buffers[0].push_back(buffer);
+        sizes[0].push_back(size);
+    }
+    auto results = batch_put_from_multi_buffers({key}, buffers, sizes, config);
     return results.empty() ? -1 : results[0];
 }
 
@@ -1261,13 +1868,19 @@ std::vector<int> DummyClient::batch_put_from_multi_buffers(
     const std::vector<std::vector<void*>>& all_buffer_ptrs,
     const std::vector<std::vector<size_t>>& all_sizes,
     const ReplicateConfig& config) {
-    std::vector<std::vector<uint64_t>> dummy_nested =
-        void_ptr_rows_to_u64_nested(all_buffer_ptrs);
+    if (keys.size() != all_buffer_ptrs.size() ||
+        keys.size() != all_sizes.size()) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    auto prepared = prepare_multi_buffers(all_buffer_ptrs, all_sizes);
+    if (!prepared) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
     const auto start_time = std::chrono::steady_clock::now();
     auto internal_results =
         invoke_batch_rpc<&RealClient::batch_put_from_multi_buffers_dummy_helper,
-                         void>(keys.size(), keys, dummy_nested, all_sizes,
-                               config, device_id_, client_id_);
+                         void>(keys.size(), keys, prepared->dummy_buffers,
+                               all_sizes, config, device_id_, client_id_);
     auto results = expected_results_to_py<int>(internal_results);
     const size_t successful_bytes =
         sum_successful_nested_sizes(results, all_sizes);
@@ -1297,24 +1910,114 @@ std::vector<int> DummyClient::batch_put_from_cuda_ipc(
     return results;
 }
 
+std::vector<int> DummyClient::batch_upsert_from_cuda_ipc(
+    const std::vector<mooncake::CudaIpcWriteRequest>& requests,
+    const ReplicateConfig& config) {
+    const auto start_time = std::chrono::steady_clock::now();
+    auto internal_results =
+        invoke_batch_rpc<&RealClient::batch_upsert_from_cuda_ipc_dummy_helper,
+                         void>(requests.size(), requests, config, client_id_);
+    auto results = expected_results_to_py<int>(internal_results);
+    const size_t successful_bytes =
+        sum_successful_cuda_ipc_sizes(results, requests);
+    if (successful_bytes > 0) {
+        ObserveTransferMetric(TransferOperationKind::kWrite,
+                              "batch_upsert_from_cuda_ipc", successful_bytes,
+                              elapsed_us_since(start_time), true);
+    }
+    return results;
+}
+
+std::vector<int> DummyClient::batch_upsert_from_multi_buffers(
+    const std::vector<std::string>& keys,
+    const std::vector<std::vector<void*>>& all_buffer_ptrs,
+    const std::vector<std::vector<size_t>>& all_sizes,
+    const ReplicateConfig& config) {
+    if (keys.size() != all_buffer_ptrs.size() ||
+        keys.size() != all_sizes.size()) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    auto prepared = prepare_multi_buffers(all_buffer_ptrs, all_sizes);
+    if (!prepared) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    const auto start_time = std::chrono::steady_clock::now();
+    auto internal_results = invoke_batch_rpc<
+        &RealClient::batch_upsert_from_multi_buffers_dummy_helper, void>(
+        keys.size(), keys, prepared->dummy_buffers, all_sizes, config,
+        device_id_, client_id_);
+    std::vector<int> results;
+    results.reserve(internal_results.size());
+    for (const auto& result : internal_results) {
+        results.push_back(to_py_ret(result));
+    }
+    const size_t successful_bytes =
+        sum_successful_nested_sizes(results, all_sizes);
+    if (successful_bytes > 0) {
+        ObserveTransferMetric(
+            TransferOperationKind::kWrite, "batch_upsert_from_multi_buffers",
+            successful_bytes, elapsed_us_since(start_time), true);
+    }
+    return results;
+}
+
 std::vector<int> DummyClient::batch_get_into_multi_buffers(
     const std::vector<std::string>& keys,
     const std::vector<std::vector<void*>>& all_buffer_ptrs,
     const std::vector<std::vector<size_t>>& all_sizes,
     bool prefer_alloc_in_same_node) {
-    std::vector<std::vector<uint64_t>> dummy_nested =
-        void_ptr_rows_to_u64_nested(all_buffer_ptrs);
+    if (keys.size() != all_buffer_ptrs.size() ||
+        keys.size() != all_sizes.size()) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
+    auto prepared =
+        prepare_multi_buffers(all_buffer_ptrs, all_sizes, false, true);
+    if (!prepared) {
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INVALID_PARAMS));
+    }
     const auto start_time = std::chrono::steady_clock::now();
     auto internal_results =
         invoke_batch_rpc<&RealClient::batch_get_into_multi_buffers_dummy_helper,
-                         int64_t>(keys.size(), keys, dummy_nested, all_sizes,
-                                  prefer_alloc_in_same_node, device_id_,
-                                  client_id_);
+                         int64_t>(keys.size(), keys, prepared->dummy_buffers,
+                                  all_sizes, prefer_alloc_in_same_node,
+                                  device_id_, client_id_);
     std::vector<int> results;
     results.reserve(internal_results.size());
     for (const auto& result : internal_results) {
         results.push_back(to_py_ret(result));
     }
+
+    if (internal_results.size() != all_sizes.size()) {
+        LOG(ERROR) << "batch_get_into_multi_buffers response size mismatch: "
+                   << "expected " << all_sizes.size() << ", got "
+                   << internal_results.size();
+        return std::vector<int>(keys.size(), toInt(ErrorCode::INTERNAL_ERROR));
+    }
+
+    size_t prepared_index = 0;
+    for (size_t i = 0; i < all_sizes.size(); ++i) {
+        size_t remaining = 0;
+        const bool has_result = internal_results[i].has_value();
+        bool copy_succeeded = false;
+        if (has_result && internal_results[i].value() >= 0 &&
+            static_cast<uint64_t>(internal_results[i].value()) <=
+                std::numeric_limits<size_t>::max()) {
+            remaining = static_cast<size_t>(internal_results[i].value());
+            copy_succeeded = true;
+        }
+        for (size_t size : all_sizes[i]) {
+            const size_t copy_size = std::min(size, remaining);
+            if (!copy_from_staging(prepared->buffers[prepared_index],
+                                   copy_size)) {
+                copy_succeeded = false;
+            }
+            remaining -= copy_size;
+            ++prepared_index;
+        }
+        if (has_result && (!copy_succeeded || remaining != 0)) {
+            results[i] = toInt(ErrorCode::INTERNAL_ERROR);
+        }
+    }
     const size_t total_bytes = sum_positive_results(results);
     if (total_bytes > 0) {
         ObserveTransferMetric(TransferOperationKind::kRead,
@@ -1431,17 +2134,16 @@ void DummyClient::ping_thread_main() {
 
 #if defined(USE_ASCEND_DIRECT)
                 if (all_registered && globalConfig().ascend_agent_mode) {
-                    auto device_buffers = get_registered_device_buffers();
-                    for (const auto& device_buffer : device_buffers) {
-                        if (register_ascend_shm(&device_buffer, false) != 0) {
-                            LOG(WARNING)
-                                << "Failed to re-register device buffer "
-                                   "during reconnection, buffer="
-                                << device_buffer.base_addr
-                                << ", size=" << device_buffer.size;
-                            all_registered = false;
-                            break;
-                        }
+                    if (globalConfig().ascend_use_fabric_mem &&
+                        reregister_fabric_buffers() != 0) {
+                        LOG(WARNING) << "Failed to re-register Fabric buffers "
+                                        "during reconnection";
+                        all_registered = false;
+                    }
+                    if (all_registered && reregister_device_buffers() != 0) {
+                        LOG(WARNING) << "Failed to re-register device buffers "
+                                        "during reconnection";
+                        all_registered = false;
                     }
                 }
 #endif
diff --git a/mooncake-store/src/engram/engram_store.cpp b/mooncake-store/src/engram/engram_store.cpp
index 7c6def080e..c6767b5bdd 100644
--- a/mooncake-store/src/engram/engram_store.cpp
+++ b/mooncake-store/src/engram/engram_store.cpp
@@ -1,6 +1,7 @@
 #include "engram/engram_store.h"
 
 #include <cstring>
+#include <chrono>
 #include <limits>
 #include <sstream>
 #include <stdexcept>
@@ -11,46 +12,105 @@
 namespace mooncake {
 namespace engram {
 
-EngramStore::EngramStore(int layer_id, const EngramStoreConfig& config,
+struct EngramStore::QueryCacheEntry {
+    mooncake::PyClient::RangedReadSnapshot snapshot;
+};
+
+EngramStore::EngramStore(const std::map<int, EngramStoreConfig>& layers,
                          std::shared_ptr<PyClient> store)
-    : store_(std::move(store)),
-      table_vocab_sizes_(config.table_vocab_sizes),
-      embedding_dim_(config.embedding_dim) {
-    if (table_vocab_sizes_.empty()) {
-        throw std::invalid_argument(
-            "EngramStoreConfig.table_vocab_sizes must not be empty");
-    }
-    if (embedding_dim_ <= 0) {
-        throw std::invalid_argument(
-            "EngramStoreConfig.embedding_dim must be positive");
+    : store_(std::move(store)) {
+    if (layers.empty()) {
+        throw std::invalid_argument("EngramStore requires at least one layer");
     }
-    for (int64_t vocab_size : table_vocab_sizes_) {
-        if (vocab_size <= 0) {
+    for (const auto& [layer_id, config] : layers) {
+        if (layer_id < 0 || config.row_bytes <= 0 ||
+            config.table_vocab_sizes.empty()) {
             throw std::invalid_argument(
-                "EngramStoreConfig.table_vocab_sizes must contain only "
-                "positive values");
+                "EngramStore requires nonnegative layer IDs, positive "
+                "row_bytes and nonempty tables");
+        }
+        Layer layer{config, {}, {}};
+        for (size_t h = 0; h < config.table_vocab_sizes.size(); ++h) {
+            const int64_t vocab_size = config.table_vocab_sizes[h];
+            if (vocab_size <= 0 ||
+                static_cast<uint64_t>(vocab_size) >
+                    std::numeric_limits<size_t>::max() / config.row_bytes) {
+                throw std::invalid_argument("Invalid Engram table size");
+            }
+            std::ostringstream key;
+            key << "engram:l" << layer_id << ":h" << h;
+            layer.keys.push_back(key.str());
+        }
+        layers_.emplace(layer_id, std::move(layer));
+    }
+}
+
+const EngramStore::Layer& EngramStore::get_layer(int layer_id) const {
+    auto it = layers_.find(layer_id);
+    if (it == layers_.end()) {
+        throw std::invalid_argument("Unknown Engram layer: " +
+                                    std::to_string(layer_id));
+    }
+    return it->second;
+}
+
+std::shared_ptr<const EngramStore::QueryCacheEntry>
+EngramStore::get_query_cache(int layer_id,
+                             const std::vector<std::string>& keys) const {
+    const auto now = std::chrono::steady_clock::now();
+    {
+        std::lock_guard<std::mutex> lock(query_cache_mutex_);
+        auto it = query_cache_.find(layer_id);
+        if (it != query_cache_.end() && it->second &&
+            it->second->snapshot.reusable(now)) {
+            return it->second;
         }
     }
 
-    embed_keys_.reserve(table_vocab_sizes_.size());
-    for (size_t h = 0; h < table_vocab_sizes_.size(); ++h) {
-        std::ostringstream oss;
-        oss << "engram:l" << layer_id << ":h" << h;
-        embed_keys_.push_back(oss.str());
+    auto entry = std::make_shared<QueryCacheEntry>();
+    entry->snapshot = store_->prepare_get_into_ranges_snapshot(keys);
+    if (!entry->snapshot.reusable(now)) return nullptr;
+
+    std::lock_guard<std::mutex> lock(query_cache_mutex_);
+    query_cache_[layer_id] = entry;
+    return entry;
+}
+
+void EngramStore::invalidate_query_cache(int layer_id) const {
+    std::lock_guard<std::mutex> lock(query_cache_mutex_);
+    query_cache_.erase(layer_id);
+}
+
+int EngramStore::bind_local(int layer_id,
+                            const std::vector<const void*>& buffers,
+                            const std::vector<size_t>& sizes) {
+    const auto& layer = get_layer(layer_id);
+    if (store_ || !layer.local_tables.empty() ||
+        buffers.size() != layer.keys.size() || sizes.size() != buffers.size()) {
+        return -1;
+    }
+    for (size_t h = 0; h < buffers.size(); ++h) {
+        if (!buffers[h] ||
+            sizes[h] != static_cast<size_t>(layer.config.table_vocab_sizes[h]) *
+                            layer.config.row_bytes)
+            return -1;
     }
+    layers_.at(layer_id).local_tables = buffers;
+    return 0;
 }
 
-int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
-                                  void* output_buffer,
-                                  size_t output_size) const {
-    if (store_ == nullptr || row_ids == nullptr || output_buffer == nullptr ||
-        B <= 0 || L <= 0) {
+int EngramStore::lookup_into(int layer_id, const int64_t* row_ids, int B, int L,
+                             void* output_buffer, size_t output_size) const {
+    const auto& layer = get_layer(layer_id);
+    const auto& table_vocab_sizes = layer.config.table_vocab_sizes;
+    const auto& embed_keys = layer.keys;
+    if ((!store_ && layer.local_tables.empty()) || row_ids == nullptr ||
+        output_buffer == nullptr || B <= 0 || L <= 0) {
         return -1;
     }
 
-    const int num_heads = static_cast<int>(table_vocab_sizes_.size());
-    const size_t row_bytes =
-        static_cast<size_t>(embedding_dim_) * sizeof(float);
+    const int num_heads = static_cast<int>(table_vocab_sizes.size());
+    const size_t row_bytes = layer.config.row_bytes;
     const size_t max_size = std::numeric_limits<size_t>::max();
     if (static_cast<size_t>(B) > max_size / static_cast<size_t>(L)) {
         return -1;
@@ -71,6 +131,30 @@ int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
         return -1;
     };
 
+    if (!layer.local_tables.empty()) {
+        // Validate all IDs before touching output. No metadata or transfer
+        // work.
+        for (size_t t = 0; t < token_count; ++t) {
+            for (int h = 0; h < num_heads; ++h) {
+                const auto id = row_ids[t * num_heads + h];
+                if (id < 0 || id >= table_vocab_sizes[h]) return fail_lookup();
+            }
+        }
+        auto* dst = static_cast<char*>(output_buffer);
+        for (size_t t = 0; t < token_count; ++t) {
+            for (int h = 0; h < num_heads; ++h) {
+                const size_t index = t * num_heads + h;
+                const auto* src =
+                    static_cast<const char*>(layer.local_tables[h]);
+                std::memcpy(
+                    dst + index * row_bytes,
+                    src + static_cast<size_t>(row_ids[index]) * row_bytes,
+                    row_bytes);
+            }
+        }
+        return 0;
+    }
+
     std::vector<void*> buffers{output_buffer};
     std::vector<std::vector<std::string>> all_keys(1);
     std::vector<std::vector<std::vector<size_t>>> all_dst_offsets(1);
@@ -83,7 +167,7 @@ int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
     all_sizes[0].reserve(static_cast<size_t>(num_heads));
 
     for (int h = 0; h < num_heads; ++h) {
-        all_keys[0].push_back(embed_keys_[h]);
+        all_keys[0].push_back(embed_keys[h]);
         all_dst_offsets[0].emplace_back();
         all_src_offsets[0].emplace_back();
         all_sizes[0].emplace_back();
@@ -100,7 +184,7 @@ int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
             for (int h = 0; h < num_heads; ++h) {
                 const int64_t idx =
                     row_ids[row_offset + static_cast<size_t>(h)];
-                if (idx < 0 || idx >= table_vocab_sizes_[h]) {
+                if (idx < 0 || idx >= table_vocab_sizes[h]) {
                     return fail_lookup();
                 }
                 all_dst_offsets[0][h].push_back(
@@ -112,30 +196,12 @@ int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
         }
     }
 
-    const int register_ret =
-        store_->register_buffer(output_buffer, expected_size);
-    if (register_ret != 0) {
-        return fail_lookup();
-    }
-
-    mooncake::PyClient::QueryResultCache query_result_cache;
-    auto query_results = store_->batch_query(embed_keys_);
-    if (query_results.size() != embed_keys_.size()) {
-        store_->unregister_buffer(output_buffer);
-        return fail_lookup();
-    }
-    query_result_cache.reserve(embed_keys_.size());
-    for (size_t i = 0; i < embed_keys_.size(); ++i) {
-        query_result_cache.emplace(embed_keys_[i], query_results[i]);
-    }
+    auto query_cache = get_query_cache(layer_id, embed_keys);
+    if (!query_cache) return fail_lookup();
 
-    auto results = store_->get_into_ranges(buffers, all_keys, all_dst_offsets,
-                                           all_src_offsets, all_sizes,
-                                           &query_result_cache);
-    const int unregister_ret = store_->unregister_buffer(output_buffer);
-    if (unregister_ret != 0) {
-        return fail_lookup();
-    }
+    auto results = store_->get_into_ranges_from_snapshot(
+        buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes,
+        query_cache->snapshot);
     if (results.size() != 1 ||
         results[0].size() != static_cast<size_t>(num_heads)) {
         return fail_lookup();
@@ -154,57 +220,30 @@ int EngramStore::lookup_rows_flat(const int64_t* row_ids, int B, int L,
     return 0;
 }
 
-int EngramStore::lookup_rows_contiguous(const int64_t* row_ids, int B, int L,
-                                        void* output_buffer,
-                                        size_t output_size) const {
-    return lookup_rows_flat(row_ids, B, L, output_buffer, output_size);
+std::vector<int> EngramStore::get_layer_ids() const {
+    std::vector<int> ids;
+    for (const auto& [id, layer] : layers_) ids.push_back(id);
+    return ids;
 }
 
-int EngramStore::lookup_rows(
-    const std::vector<std::vector<std::vector<int64_t>>>& row_ids,
-    void* output_buffer, size_t output_size) const {
-    if (store_ == nullptr || output_buffer == nullptr || row_ids.empty() ||
-        row_ids[0].empty()) {
-        return -1;
-    }
-
-    const int B = static_cast<int>(row_ids.size());
-    const int L = static_cast<int>(row_ids[0].size());
-    const int num_heads = static_cast<int>(table_vocab_sizes_.size());
-    std::vector<int64_t> flat_row_ids;
-    flat_row_ids.reserve(static_cast<size_t>(B) * L * num_heads);
-    for (int b = 0; b < B; ++b) {
-        if (static_cast<int>(row_ids[b].size()) != L) {
-            return -1;
-        }
-        for (int l = 0; l < L; ++l) {
-            if (static_cast<int>(row_ids[b][l].size()) != num_heads) {
-                return -1;
-            }
-            flat_row_ids.insert(flat_row_ids.end(), row_ids[b][l].begin(),
-                                row_ids[b][l].end());
-        }
-    }
-
-    return lookup_rows_flat(flat_row_ids.data(), B, L, output_buffer,
-                            output_size);
+std::vector<int64_t> EngramStore::get_table_vocab_sizes(int layer_id) const {
+    return get_layer(layer_id).config.table_vocab_sizes;
 }
 
-std::vector<int64_t> EngramStore::get_table_vocab_sizes() const {
-    return table_vocab_sizes_;
+std::vector<std::string> EngramStore::get_store_keys(int layer_id) const {
+    return get_layer(layer_id).keys;
 }
 
-std::vector<std::string> EngramStore::get_store_keys() const {
-    return embed_keys_;
+int EngramStore::get_num_heads(int layer_id) const {
+    return static_cast<int>(get_layer(layer_id).keys.size());
 }
 
-int EngramStore::get_num_heads() const {
-    return static_cast<int>(table_vocab_sizes_.size());
+int EngramStore::get_row_bytes(int layer_id) const {
+    return get_layer(layer_id).config.row_bytes;
 }
 
-int EngramStore::get_embedding_dim() const { return embedding_dim_; }
-
-int EngramStore::remove_from_store(bool force) {
+int EngramStore::remove_from_store(int layer_id, bool force) {
+    const auto& embed_keys = get_layer(layer_id).keys;
     if (store_ == nullptr) {
         return static_cast<int>(ErrorCode::INVALID_PARAMS);
     }
@@ -214,7 +253,7 @@ int EngramStore::remove_from_store(bool force) {
     int removed = 0;
     int first_error = 0;
 
-    for (const auto& key : embed_keys_) {
+    for (const auto& key : embed_keys) {
         int rc = store_->remove(key, force);
         if (rc == 0) {
             ++removed;
@@ -228,43 +267,49 @@ int EngramStore::remove_from_store(bool force) {
         }
     }
 
+    if (first_error == 0 && removed > 0) invalidate_query_cache(layer_id);
     return first_error != 0 ? first_error : removed;
 }
 
-int EngramStore::populate(const std::vector<void*>& embedding_buffers,
-                          const std::vector<size_t>& buffer_sizes) {
+int EngramStore::populate(int layer_id,
+                          const std::vector<void*>& embedding_buffers,
+                          const std::vector<size_t>& buffer_sizes,
+                          const ReplicateConfig& config) {
+    const auto& layer = get_layer(layer_id);
+    const auto& table_vocab_sizes = layer.config.table_vocab_sizes;
+    const auto& embed_keys = layer.keys;
     if (store_ == nullptr) {
         return -1;
     }
-    if (embedding_buffers.size() != embed_keys_.size() ||
-        buffer_sizes.size() != embed_keys_.size()) {
+    if (embedding_buffers.size() != embed_keys.size() ||
+        buffer_sizes.size() != embed_keys.size()) {
         return -1;
     }
 
     for (size_t i = 0; i < buffer_sizes.size(); ++i) {
-        const size_t expected = static_cast<size_t>(table_vocab_sizes_[i]) *
-                                embedding_dim_ * sizeof(float);
+        const size_t expected =
+            static_cast<size_t>(table_vocab_sizes[i]) * layer.config.row_bytes;
         if (embedding_buffers[i] == nullptr || buffer_sizes[i] != expected) {
             return -1;
         }
     }
 
-    std::vector<int> exists_results = store_->batchIsExist(embed_keys_);
-    if (exists_results.size() != embed_keys_.size()) {
+    std::vector<int> exists_results = store_->batchIsExist(embed_keys);
+    if (exists_results.size() != embed_keys.size()) {
         LOG(ERROR) << "Failed to preflight EngramStore populate key existence";
         return -1;
     }
     for (size_t i = 0; i < exists_results.size(); ++i) {
         const int exists = exists_results[i];
         if (exists < 0) {
-            LOG(ERROR) << "Failed to query EngramStore key '" << embed_keys_[i]
+            LOG(ERROR) << "Failed to query EngramStore key '" << embed_keys[i]
                        << "' before populate, rc=" << exists;
             return -1;
         }
         if (exists != 0) {
             LOG(ERROR)
                 << "EngramStore populate requires empty destination key '"
-                << embed_keys_[i] << "'. Remove the existing layer first.";
+                << embed_keys[i] << "'. Remove the existing layer first.";
             return -1;
         }
     }
@@ -294,10 +339,10 @@ int EngramStore::populate(const std::vector<void*>& embedding_buffers,
         }
     }
 
-    std::vector<int> put_results =
-        store_->batch_put_from(embed_keys_, embedding_buffers, buffer_sizes);
+    std::vector<int> put_results = store_->batch_put_from(
+        embed_keys, embedding_buffers, buffer_sizes, config);
     const bool put_succeeded =
-        put_results.size() == embed_keys_.size() &&
+        put_results.size() == embed_keys.size() &&
         std::all_of(put_results.begin(), put_results.end(),
                     [](int result) { return result == 0; });
 
@@ -306,17 +351,17 @@ int EngramStore::populate(const std::vector<void*>& embedding_buffers,
 
     if (!put_succeeded || unregister_failed) {
         const bool put_results_complete =
-            put_results.size() == embed_keys_.size();
-        for (size_t i = 0; i < embed_keys_.size(); ++i) {
+            put_results.size() == embed_keys.size();
+        for (size_t i = 0; i < embed_keys.size(); ++i) {
             if (put_results_complete && put_results[i] != 0) {
                 continue;
             }
-            int rc = store_->remove(embed_keys_[i], true);
+            int rc = store_->remove(embed_keys[i], true);
             if (rc != 0 &&
                 rc != static_cast<int>(ErrorCode::OBJECT_NOT_FOUND)) {
                 LOG(ERROR)
                     << "Failed to roll back partially populated EngramStore "
-                    << "key '" << embed_keys_[i] << "', rc=" << rc;
+                    << "key '" << embed_keys[i] << "', rc=" << rc;
             }
         }
         if (unregister_failed) {
@@ -327,6 +372,7 @@ int EngramStore::populate(const std::vector<void*>& embedding_buffers,
         return -1;
     }
 
+    invalidate_query_cache(layer_id);
     return 0;
 }
 
diff --git a/mooncake-store/src/etcd_helper.cpp b/mooncake-store/src/etcd_helper.cpp
index 69cd19ad7a..34bd3c5d1a 100644
--- a/mooncake-store/src/etcd_helper.cpp
+++ b/mooncake-store/src/etcd_helper.cpp
@@ -67,9 +67,10 @@ ErrorCode EtcdHelper::Get(const char* key, const size_t key_size,
     char* err_msg = nullptr;
     char* value_ptr = nullptr;
     int value_size = 0;
+    GoInt64 go_revision_id = 0;
     int ret =
         EtcdStoreGetWrapper(const_cast<char*>(key), (int)key_size, &value_ptr,
-                            &value_size, &revision_id, &err_msg);
+                            &value_size, &go_revision_id, &err_msg);
     if (ret == -2) {
         LOG(ERROR) << "key=" << std::string(key, key_size)
                    << ", error=" << err_msg;
@@ -83,6 +84,7 @@ ErrorCode EtcdHelper::Get(const char* key, const size_t key_size,
         return ErrorCode::ETCD_OPERATION_ERROR;
     }
     value = std::string(value_ptr, value_size);
+    revision_id = static_cast<EtcdRevisionId>(go_revision_id);
     free(value_ptr);
     return ErrorCode::OK;
 }
@@ -93,9 +95,11 @@ ErrorCode EtcdHelper::CreateWithLease(const char* key, const size_t key_size,
                                       EtcdLeaseId lease_id,
                                       EtcdRevisionId& revision_id) {
     char* err_msg = nullptr;
+    GoInt64 go_revision_id = 0;
     int ret = EtcdStoreCreateWithLeaseWrapper(
         const_cast<char*>(key), (int)key_size, const_cast<char*>(value),
-        (int)value_size, lease_id, &revision_id, &err_msg);
+        (int)value_size, static_cast<GoInt64>(lease_id), &go_revision_id,
+        &err_msg);
     if (ret == -2) {
         VLOG(1) << "key=" << std::string(key, key_size)
                 << ", lease_id=" << lease_id << ", error=" << err_msg;
@@ -107,10 +111,73 @@ ErrorCode EtcdHelper::CreateWithLease(const char* key, const size_t key_size,
         free(err_msg);
         return ErrorCode::ETCD_OPERATION_ERROR;
     } else {
+        revision_id = static_cast<EtcdRevisionId>(go_revision_id);
         return ErrorCode::OK;
     }
 }
 
+ErrorCode EtcdHelper::AcquireMaintenanceSession(
+    std::string_view key, int64_t lease_ttl, int64_t& session_handle,
+    EtcdLeaseId& lease_id, EtcdRevisionId& create_revision) {
+    char* err_msg = nullptr;
+    GoInt64 go_session_handle = 0;
+    GoInt64 go_lease_id = 0;
+    GoInt64 go_create_revision = 0;
+    int ret = EtcdStoreAcquireMaintenanceSessionWrapper(
+        const_cast<char*>(key.data()), static_cast<int>(key.size()),
+        static_cast<GoInt64>(lease_ttl), &go_session_handle, &go_lease_id,
+        &go_create_revision, &err_msg);
+    if (ret == -2) {
+        if (err_msg != nullptr) {
+            free(err_msg);
+        }
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+    if (ret != 0) {
+        LOG(ERROR) << "Failed to acquire maintenance session: "
+                   << (err_msg == nullptr ? "" : err_msg);
+        if (err_msg != nullptr) {
+            free(err_msg);
+        }
+        return ErrorCode::ETCD_OPERATION_ERROR;
+    }
+    session_handle = static_cast<int64_t>(go_session_handle);
+    lease_id = static_cast<EtcdLeaseId>(go_lease_id);
+    create_revision = static_cast<EtcdRevisionId>(go_create_revision);
+    return ErrorCode::OK;
+}
+
+ErrorCode EtcdHelper::CloseMaintenanceSession(int64_t session_handle) {
+    char* err_msg = nullptr;
+    int ret = EtcdStoreCloseMaintenanceSessionWrapper(
+        static_cast<GoInt64>(session_handle), &err_msg);
+    if (ret != 0) {
+        LOG(ERROR) << "Failed to close maintenance session: "
+                   << (err_msg == nullptr ? "" : err_msg);
+        if (err_msg != nullptr) {
+            free(err_msg);
+        }
+        return ErrorCode::ETCD_OPERATION_ERROR;
+    }
+    return ErrorCode::OK;
+}
+
+tl::expected<bool, ErrorCode> EtcdHelper::MaintenanceSessionAlive(
+    int64_t session_handle) {
+    char* err_msg = nullptr;
+    int ret = EtcdStoreMaintenanceSessionAliveWrapper(
+        static_cast<GoInt64>(session_handle), &err_msg);
+    if (ret < 0) {
+        LOG(ERROR) << "Failed to check maintenance session: "
+                   << (err_msg == nullptr ? "" : err_msg);
+        if (err_msg != nullptr) {
+            free(err_msg);
+        }
+        return tl::make_unexpected(ErrorCode::ETCD_OPERATION_ERROR);
+    }
+    return ret == 1;
+}
+
 ErrorCode EtcdHelper::BatchCreate(const std::vector<std::string>& keys,
                                   const std::vector<std::string>& values) {
     if (keys.size() != values.size()) {
@@ -158,11 +225,13 @@ ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
     std::vector<int> compare_kinds;
     std::vector<char*> compare_values;
     std::vector<int> compare_value_sizes;
+    std::vector<GoInt64> compare_revisions;
     compare_keys.reserve(compares.size());
     compare_key_sizes.reserve(compares.size());
     compare_kinds.reserve(compares.size());
     compare_values.reserve(compares.size());
     compare_value_sizes.reserve(compares.size());
+    compare_revisions.reserve(compares.size());
     for (const auto& compare : compares) {
         compare_keys.push_back(const_cast<char*>(compare.key.data()));
         compare_key_sizes.push_back(static_cast<int>(compare.key.size()));
@@ -171,29 +240,35 @@ ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
             const_cast<char*>(compare.expected_value.data()));
         compare_value_sizes.push_back(
             static_cast<int>(compare.expected_value.size()));
+        compare_revisions.push_back(
+            static_cast<GoInt64>(compare.expected_revision));
     }
 
     std::vector<char*> put_keys;
     std::vector<int> put_key_sizes;
     std::vector<char*> put_values;
     std::vector<int> put_value_sizes;
+    std::vector<int> put_preserve_leases;
     put_keys.reserve(puts.size());
     put_key_sizes.reserve(puts.size());
     put_values.reserve(puts.size());
     put_value_sizes.reserve(puts.size());
+    put_preserve_leases.reserve(puts.size());
     for (const auto& put : puts) {
         put_keys.push_back(const_cast<char*>(put.key.data()));
         put_key_sizes.push_back(static_cast<int>(put.key.size()));
         put_values.push_back(const_cast<char*>(put.value.data()));
         put_value_sizes.push_back(static_cast<int>(put.value.size()));
+        put_preserve_leases.push_back(put.preserve_lease ? 1 : 0);
     }
 
     char* err_msg = nullptr;
     int ret = EtcdStoreTxnCompareAndPutWrapper(
         compare_keys.data(), compare_key_sizes.data(), compare_kinds.data(),
         compare_values.data(), compare_value_sizes.data(),
-        static_cast<int>(compares.size()), put_keys.data(),
-        put_key_sizes.data(), put_values.data(), put_value_sizes.data(),
+        compare_revisions.data(), static_cast<int>(compares.size()),
+        put_keys.data(), put_key_sizes.data(), put_values.data(),
+        put_value_sizes.data(), put_preserve_leases.data(),
         static_cast<int>(puts.size()), &err_msg);
     if (ret == -2) {
         if (err_msg != nullptr) {
@@ -214,17 +289,21 @@ ErrorCode EtcdHelper::TxnCompareAndPut(const std::vector<TxnCompare>& compares,
 
 ErrorCode EtcdHelper::GrantLease(int64_t lease_ttl, EtcdLeaseId& lease_id) {
     char* err_msg = nullptr;
-    if (0 != EtcdStoreGrantLeaseWrapper(lease_ttl, &lease_id, &err_msg)) {
+    GoInt64 go_lease_id = 0;
+    if (0 != EtcdStoreGrantLeaseWrapper(static_cast<GoInt64>(lease_ttl),
+                                        &go_lease_id, &err_msg)) {
         LOG(ERROR) << "lease_ttl=" << lease_ttl << ", error=" << err_msg;
         free(err_msg);
         return ErrorCode::ETCD_OPERATION_ERROR;
     }
+    lease_id = static_cast<EtcdLeaseId>(go_lease_id);
     return ErrorCode::OK;
 }
 
 ErrorCode EtcdHelper::RevokeLease(EtcdLeaseId lease_id) {
     char* err_msg = nullptr;
-    if (0 != EtcdStoreRevokeLeaseWrapper(lease_id, &err_msg)) {
+    if (0 !=
+        EtcdStoreRevokeLeaseWrapper(static_cast<GoInt64>(lease_id), &err_msg)) {
         LOG(ERROR) << "lease_id=" << lease_id << ", error=" << err_msg;
         free(err_msg);
         return ErrorCode::ETCD_OPERATION_ERROR;
@@ -264,7 +343,8 @@ ErrorCode EtcdHelper::CancelWatch(const char* key, const size_t key_size) {
 
 ErrorCode EtcdHelper::KeepAlive(EtcdLeaseId lease_id) {
     char* err_msg = nullptr;
-    int err_code = EtcdStoreKeepAliveWrapper(lease_id, &err_msg);
+    int err_code =
+        EtcdStoreKeepAliveWrapper(static_cast<GoInt64>(lease_id), &err_msg);
     if (err_code != 0) {
         LOG(ERROR) << "lease_id=" << lease_id << ", error=" << err_msg;
         free(err_msg);
@@ -279,7 +359,8 @@ ErrorCode EtcdHelper::KeepAlive(EtcdLeaseId lease_id) {
 
 ErrorCode EtcdHelper::CancelKeepAlive(EtcdLeaseId lease_id) {
     char* err_msg = nullptr;
-    if (0 != EtcdStoreCancelKeepAliveWrapper(lease_id, &err_msg)) {
+    if (0 != EtcdStoreCancelKeepAliveWrapper(static_cast<GoInt64>(lease_id),
+                                             &err_msg)) {
         LOG(ERROR) << "Failed to cancel keep lease: " << err_msg;
         free(err_msg);
         return ErrorCode::ETCD_OPERATION_ERROR;
@@ -289,8 +370,8 @@ ErrorCode EtcdHelper::CancelKeepAlive(EtcdLeaseId lease_id) {
 
 ErrorCode EtcdHelper::WaitKeepAliveReady(EtcdLeaseId lease_id, int timeout_ms) {
     char* err_msg = nullptr;
-    if (0 !=
-        EtcdStoreWaitKeepAliveReadyWrapper(lease_id, timeout_ms, &err_msg)) {
+    if (0 != EtcdStoreWaitKeepAliveReadyWrapper(static_cast<GoInt64>(lease_id),
+                                                timeout_ms, &err_msg)) {
         LOG(ERROR) << "lease_id=" << lease_id << ", error=" << err_msg;
         free(err_msg);
         return ErrorCode::ETCD_OPERATION_ERROR;
@@ -341,11 +422,12 @@ ErrorCode EtcdHelper::GetRangeAsJson(const char* start_key,
     char* err_msg = nullptr;
     char* json_ptr = nullptr;
     int json_size = 0;
+    GoInt64 go_revision_id = 0;
     // Go wrapper takes int limit.
     int ret = EtcdStoreGetRangeAsJsonWrapper(
         const_cast<char*>(start_key), (int)start_key_size,
         const_cast<char*>(end_key), (int)end_key_size, (int)limit, &json_ptr,
-        &json_size, (GoInt64*)&revision_id, &err_msg);
+        &json_size, &go_revision_id, &err_msg);
     if (ret != 0) {
         LOG(ERROR) << "start_key=" << std::string(start_key, start_key_size)
                    << ", end_key=" << std::string(end_key, end_key_size)
@@ -354,6 +436,7 @@ ErrorCode EtcdHelper::GetRangeAsJson(const char* start_key,
         return ErrorCode::ETCD_OPERATION_ERROR;
     }
     json = std::string(json_ptr, json_size);
+    revision_id = static_cast<EtcdRevisionId>(go_revision_id);
     free(json_ptr);
     return ErrorCode::OK;
 }
@@ -432,8 +515,9 @@ ErrorCode EtcdHelper::WatchWithPrefixFromRevision(
     char* err_msg = nullptr;
     void* callback_func_ptr = reinterpret_cast<void*>(callback_func);
     int ret = EtcdStoreWatchWithPrefixFromRevisionWrapper(
-        const_cast<char*>(prefix), (int)prefix_size, (GoInt64)start_revision,
-        callback_context, callback_func_ptr, &err_msg);
+        const_cast<char*>(prefix), (int)prefix_size,
+        static_cast<GoInt64>(start_revision), callback_context,
+        callback_func_ptr, &err_msg);
     if (ret != 0) {
         LOG(ERROR) << "prefix=" << std::string(prefix, prefix_size)
                    << ", start_revision=" << (int64_t)start_revision
@@ -483,6 +567,31 @@ ErrorCode EtcdHelper::ConnectToEtcdStoreClient(
     return ErrorCode::ETCD_OPERATION_ERROR;
 }
 
+ErrorCode EtcdHelper::AcquireMaintenanceSession(
+    std::string_view key, int64_t lease_ttl, int64_t& session_handle,
+    EtcdLeaseId& lease_id, EtcdRevisionId& create_revision) {
+    (void)key;
+    (void)lease_ttl;
+    (void)session_handle;
+    (void)lease_id;
+    (void)create_revision;
+    LOG(FATAL) << "Etcd is not enabled in compilation";
+    return ErrorCode::ETCD_OPERATION_ERROR;
+}
+
+ErrorCode EtcdHelper::CloseMaintenanceSession(int64_t session_handle) {
+    (void)session_handle;
+    LOG(FATAL) << "Etcd is not enabled in compilation";
+    return ErrorCode::ETCD_OPERATION_ERROR;
+}
+
+tl::expected<bool, ErrorCode> EtcdHelper::MaintenanceSessionAlive(
+    int64_t session_handle) {
+    (void)session_handle;
+    LOG(FATAL) << "Etcd is not enabled in compilation";
+    return tl::make_unexpected(ErrorCode::ETCD_OPERATION_ERROR);
+}
+
 ErrorCode EtcdHelper::ResetEtcdStoreClient(const std::string& etcd_endpoints) {
     (void)etcd_endpoints;
     return ErrorCode::UNAVAILABLE_IN_CURRENT_MODE;
diff --git a/mooncake-store/src/file_storage.cpp b/mooncake-store/src/file_storage.cpp
index f4ccfbc0a0..739e2b1bdc 100644
--- a/mooncake-store/src/file_storage.cpp
+++ b/mooncake-store/src/file_storage.cpp
@@ -1,19 +1,16 @@
 #include "file_storage.h"
 
-#include <cmath>
-#include <locale>
+#include <algorithm>
 #include <memory>
 #include <optional>
-#include <sstream>
 #include <utility>
 #include <vector>
 
 #include "aligned_client_buffer.h"
-#include "bool_parser.h"
-#include "environ.h"
 #include "storage_backend.h"
+#include "storage/distributed/distributed_storage_backend.h"
 #include "client_metric.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 #include "device/accelerator_registry.h"
 #ifdef USE_URING
 #include "file_interface.h"
@@ -23,47 +20,6 @@ namespace mooncake {
 
 namespace {
 
-double ParseEnvRatioOr(const std::string& raw_value, double default_value) {
-    if (raw_value.empty()) {
-        return default_value;
-    }
-
-    std::istringstream stream(raw_value);
-    stream.imbue(std::locale::classic());
-
-    double value = 0.0;
-    stream >> value;
-    if (stream.fail()) {
-        return default_value;
-    }
-    if (!stream.eof() || !std::isfinite(value) || value <= 0.0 || value > 1.0) {
-        return default_value;
-    }
-    return value;
-}
-
-double GetEnvRatioOr(const char* name, double default_value) {
-    const auto raw_value = Environ::GetString(name, "");
-    return ParseEnvRatioOr(raw_value, default_value);
-}
-
-double GetEnvRatioOr(const char* preferred_name, const char* fallback_name,
-                     double default_value) {
-    const auto preferred_value = Environ::GetString(preferred_name, "");
-    if (!preferred_value.empty()) {
-        return ParseEnvRatioOr(preferred_value, default_value);
-    }
-    return GetEnvRatioOr(fallback_name, default_value);
-}
-
-bool GetEnvBoolStringOr(const char* name, bool default_value) {
-    const auto raw_value =
-        Environ::GetString(name, default_value ? "true" : "false");
-    return TryParseBool(raw_value, {.token_set = BoolTokenSet::kTrueFalse,
-                                    .trim_ascii_whitespace = false})
-        .value_or(default_value);
-}
-
 std::vector<OffloadTaskItem> BuildOffloadTasksFromStorageKeys(
     const std::vector<std::string>& storage_keys,
     const std::vector<StorageObjectMetadata>& metadatas) {
@@ -82,176 +38,6 @@ std::vector<OffloadTaskItem> BuildOffloadTasksFromStorageKeys(
 
 }  // namespace
 
-FileStorageConfig FileStorageConfig::FromEnvironment() {
-    FileStorageConfig config;
-
-    auto storage_backend_descriptor =
-        Environ::GetString("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR",
-                           "bucket_storage_backend");
-
-    if (storage_backend_descriptor == "bucket_storage_backend") {
-        config.storage_backend_type = StorageBackendType::kBucket;
-    } else if (storage_backend_descriptor == "file_per_key_storage_backend") {
-        config.storage_backend_type = StorageBackendType::kFilePerKey;
-    } else if (storage_backend_descriptor ==
-               "offset_allocator_storage_backend") {
-        config.storage_backend_type = StorageBackendType::kOffsetAllocator;
-    } else if (storage_backend_descriptor == "distributed_storage_backend") {
-        config.storage_backend_type = StorageBackendType::kDistributed;
-    } else {
-        LOG(ERROR) << "Unknown storage backend.";
-    }
-
-    config.storage_filepath = Environ::GetString(
-        "MOONCAKE_OFFLOAD_FILE_STORAGE_PATH", config.storage_filepath);
-
-    config.local_buffer_size = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES", config.local_buffer_size);
-
-    config.scanmeta_iterator_keys_limit = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT",
-        Environ::GetInt64("MOONCAKE_SCANMETA_ITERATOR_KEYS_LIMIT",
-                          config.scanmeta_iterator_keys_limit));
-
-    config.total_keys_limit = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT", config.total_keys_limit);
-
-    config.total_size_limit = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES", config.total_size_limit);
-
-    config.heartbeat_interval_seconds =
-        Environ::GetUInt32("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS",
-                           config.heartbeat_interval_seconds);
-    config.client_buffer_gc_interval_seconds =
-        Environ::GetUInt32("MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS",
-                           config.client_buffer_gc_interval_seconds);
-
-    config.client_buffer_gc_ttl_ms =
-        Environ::GetUInt64("MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS",
-                           config.client_buffer_gc_ttl_ms);
-
-    config.enable_disk_watermark_eviction =
-        GetEnvBoolStringOr("MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION",
-                           config.enable_disk_watermark_eviction);
-    config.disk_eviction_high_watermark_ratio =
-        GetEnvRatioOr("MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO",
-                      "MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO",
-                      config.disk_eviction_high_watermark_ratio);
-    config.disk_eviction_low_watermark_ratio =
-        GetEnvRatioOr("MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO",
-                      "MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO",
-                      config.disk_eviction_low_watermark_ratio);
-
-    const auto use_uring_str =
-        Environ::GetString("MOONCAKE_OFFLOAD_USE_URING",
-                           Environ::GetString("MOONCAKE_USE_URING", "false"));
-    config.use_uring =
-        TryParseBool(use_uring_str, {.token_set = BoolTokenSet::kTrueFalse,
-                                     .trim_ascii_whitespace = false})
-            .value_or(false);
-
-    return config;
-}
-
-bool FileStorageConfig::ValidatePath(std::string path) const {
-    if (path.empty()) {
-        LOG(ERROR) << "FileStorageConfig: storage_filepath is invalid";
-        return false;
-    }
-    namespace fs = std::filesystem;
-    // 1. Must be an absolute path
-    if (!fs::path(path).is_absolute()) {
-        LOG(ERROR)
-            << "FileStorageConfig: storage_filepath must be an absolute path: "
-            << path;
-        return false;
-    }
-
-    // 2. Check if the path contains ".." components that could lead to path
-    // traversal (static check)
-    fs::path p(path);
-    for (const auto& component : p) {
-        if (component == "..") {
-            LOG(ERROR) << "FileStorageConfig: path traversal is not allowed: "
-                       << path;
-            return false;
-        }
-    }
-
-    struct stat stat_buf;
-
-    // 3. Use stat() to check if the path exists
-    if (::stat(path.c_str(), &stat_buf) != 0) {
-        LOG(ERROR) << "FileStorageConfig: storage_filepath does not exist: "
-                   << path;
-        return false;
-    }
-    // Path exists — check if it is a directory
-    if (!S_ISDIR(stat_buf.st_mode)) {
-        LOG(ERROR) << "FileStorageConfig: storage_filepath is not a directory: "
-                   << path;
-        return false;
-    }
-
-    // (Optional) Check write permission
-    if (::access(path.c_str(), W_OK) != 0) {
-        LOG(ERROR) << "FileStorageConfig: no write permission on directory: "
-                   << path;
-        return false;
-    }
-
-    // 4. Additional security: prevent symlink bypass (optional)
-    // Use lstat to avoid automatic dereferencing of symbolic links
-    struct stat lstat_buf;
-    if (::lstat(path.c_str(), &lstat_buf) == 0) {
-        if (S_ISLNK(lstat_buf.st_mode)) {
-            LOG(ERROR) << "FileStorageConfig: symbolic link is not allowed: "
-                       << path;
-            return false;
-        }
-    }
-
-    return true;
-}
-
-bool FileStorageConfig::Validate() const {
-    if (!ValidatePath(storage_filepath)) {
-        return false;
-    }
-    if (total_keys_limit <= 0) {
-        LOG(ERROR) << "FileStorageConfig: total_keys_limit must > 0";
-        return false;
-    }
-    if (total_size_limit == 0) {
-        LOG(ERROR) << "FileStorageConfig: total_size_limit should not be zero";
-        return false;
-    }
-    if (heartbeat_interval_seconds <= 0) {
-        LOG(ERROR) << "FileStorageConfig: heartbeat_interval_seconds must > 0";
-        return false;
-    }
-    if (disk_eviction_low_watermark_ratio <= 0.0 ||
-        disk_eviction_low_watermark_ratio > 1.0) {
-        LOG(ERROR) << "FileStorageConfig: "
-                   << "disk_eviction_low_watermark_ratio must be in (0, 1]";
-        return false;
-    }
-    if (disk_eviction_high_watermark_ratio <= 0.0 ||
-        disk_eviction_high_watermark_ratio > 1.0) {
-        LOG(ERROR) << "FileStorageConfig: "
-                   << "disk_eviction_high_watermark_ratio must be in (0, 1]";
-        return false;
-    }
-    if (disk_eviction_low_watermark_ratio >=
-        disk_eviction_high_watermark_ratio) {
-        LOG(ERROR) << "FileStorageConfig: "
-                   << "disk_eviction_low_watermark_ratio must be lower than "
-                   << "disk_eviction_high_watermark_ratio";
-        return false;
-    }
-    return true;
-}
-
 FileStorage::FileStorage(const FileStorageConfig& config,
                          std::shared_ptr<Client> client,
                          const std::string& local_rpc_addr,
@@ -263,10 +49,33 @@ FileStorage::FileStorage(const FileStorageConfig& config,
       pinned_buffer_pool_(std::make_unique<PinnedBufferPool>()),
       client_buffer_allocator_(AlignedClientBufferAllocator::create(
           config.local_buffer_size, client ? client->GetProtocol() : "")) {
-    if (!config.Validate()) {
+    if (!config_.Validate()) {
         throw std::invalid_argument("Invalid FileStorage configuration");
     }
 
+    if (config.pinned_restore_arena_size > 0) {
+        if (config.use_uring) {
+            LOG(WARNING) << "Pinned SSD restore is disabled with io_uring";
+        } else if (!client ||
+                   !client->CanUseLocalMemcpy(client->GetSegmentEndpoint())) {
+            LOG(WARNING)
+                << "Pinned SSD restore is disabled: local memcpy unavailable";
+        } else {
+            auto buffer = PinnedBufferPool::AllocatePinned(
+                static_cast<size_t>(config.pinned_restore_arena_size));
+            if (buffer.pinned_host.addr) {
+                pinned_restore_arena_ = std::move(buffer);
+                pinned_restore_arena_allocator_ = ClientBufferAllocator::create(
+                    pinned_restore_arena_.data, pinned_restore_arena_.capacity,
+                    client->GetProtocol());
+                LOG(INFO) << "Initialized pinned SSD restore arena, size="
+                          << pinned_restore_arena_.capacity;
+            } else {
+                LOG(WARNING) << "Failed to allocate pinned SSD restore arena";
+            }
+        }
+    }
+
     auto create_storage_backend_result = CreateStorageBackend(config_);
     if (!create_storage_backend_result) {
         LOG(ERROR) << "Failed to create storage backend";
@@ -274,6 +83,14 @@ FileStorage::FileStorage(const FileStorageConfig& config,
     }
 
     storage_backend_ = create_storage_backend_result.value();
+    if (auto distributed_backend =
+            std::dynamic_pointer_cast<DistributedStorageBackend>(
+                storage_backend_)) {
+        config_.enable_dfs = !distributed_backend->UsesObjectStorage();
+        if (config_.enable_dfs && client_) {
+            client_->SetDfsStorageBackend(distributed_backend);
+        }
+    }
 
     // Register the client buffer with the process-wide io_uring fixed-buffer
     // mechanism. This must happen before any I/O threads start so that they
@@ -322,6 +139,12 @@ tl::expected<void, ErrorCode> FileStorage::Init() {
                    << init_storage_backend_result.error();
         return init_storage_backend_result;
     }
+    if (config_.enable_dfs) {
+        client_buffer_gc_running_.store(true);
+        client_buffer_gc_thread_ =
+            std::thread(&FileStorage::ClientBufferGCThreadFunc, this);
+        return {};
+    }
     auto enable_offloading_result = IsEnableOffloading();
     if (enable_offloading_result.has_value()) {
         LOG(INFO) << "IsEnableOffloading result: "
@@ -376,9 +199,15 @@ tl::expected<void, ErrorCode> FileStorage::Init() {
         });
 
     if (!scan_meta_result) {
-        LOG(ERROR) << "Failed to scan meta and send to master: "
-                   << scan_meta_result.error();
-        return scan_meta_result;
+        if (config_.enable_dfs &&
+            scan_meta_result.error() == ErrorCode::NOT_SUPPORTED) {
+            LOG(INFO) << "Currently, DFS backend does not support ScanMeta; "
+                         "skip re-registering offloaded objects";
+        } else {
+            LOG(ERROR) << "Failed to scan meta and send to master: "
+                       << scan_meta_result.error();
+            return scan_meta_result;
+        }
     }
 
     heartbeat_running_.store(true);
@@ -398,15 +227,23 @@ tl::expected<void, ErrorCode> FileStorage::Init() {
     return {};
 }
 
-tl::expected<FileStorage::BatchGetResult, ErrorCode> FileStorage::BatchGet(
-    const std::vector<std::string>& keys, const std::vector<int64_t>& sizes) {
-    auto start_time = std::chrono::steady_clock::now();
-    auto allocate_res = AllocateBatch(keys, sizes);
+tl::expected<std::shared_ptr<FileStorage::AllocatedBatch>, ErrorCode>
+FileStorage::LoadBatch(const std::vector<std::string>& keys,
+                       const std::vector<int64_t>& sizes, bool prefer_pinned) {
+    const bool use_pinned = prefer_pinned && pinned_restore_arena_allocator_;
+    auto& allocator = use_pinned ? *pinned_restore_arena_allocator_
+                                 : *client_buffer_allocator_;
+    auto allocate_res = AllocateBatch(keys, sizes, allocator);
+    if (!allocate_res && use_pinned &&
+        allocate_res.error() == ErrorCode::BUFFER_OVERFLOW) {
+        VLOG(1) << "Pinned SSD restore arena exhausted; using default arena";
+        allocate_res = AllocateBatch(keys, sizes, *client_buffer_allocator_);
+    }
     if (!allocate_res) {
         LOG(ERROR) << "Failed to allocate batch objects";
         return tl::make_unexpected(allocate_res.error());
     }
-    auto allocated_batch = allocate_res.value();
+    auto allocated_batch = std::move(allocate_res.value());
     auto result = BatchLoad(allocated_batch->slices);
     if (!result) {
         LOG(ERROR) << "Batch load object failed,err_code = " << result.error();
@@ -424,6 +261,16 @@ tl::expected<FileStorage::BatchGetResult, ErrorCode> FileStorage::BatchGet(
         }
     }
 
+    return allocated_batch;
+}
+
+tl::expected<FileStorage::BatchGetResult, ErrorCode> FileStorage::BatchGet(
+    const std::vector<std::string>& keys, const std::vector<int64_t>& sizes) {
+    auto start_time = std::chrono::steady_clock::now();
+    auto load_result = LoadBatch(keys, sizes, false);
+    if (!load_result) return tl::make_unexpected(load_result.error());
+
+    auto allocated_batch = std::move(load_result.value());
     uint64_t batch_id = allocated_batch->batch_id;
     BatchGetResult batch_result{batch_id, allocated_batch->pointers};
 
@@ -439,6 +286,19 @@ tl::expected<FileStorage::BatchGetResult, ErrorCode> FileStorage::BatchGet(
     return batch_result;
 }
 
+tl::expected<FileStorage::LocalBatchResult, ErrorCode>
+FileStorage::BatchGetLocal(const std::vector<std::string>& keys,
+                           const std::vector<int64_t>& sizes) {
+    auto load_result = LoadBatch(keys, sizes, true);
+    if (!load_result) return tl::make_unexpected(load_result.error());
+
+    auto batch = std::move(load_result.value());
+    LocalBatchResult result;
+    result.pointers = std::move(batch->pointers);
+    result.owner = std::move(batch);
+    return result;
+}
+
 bool FileStorage::IsPerBucketSoftOffloadError(ErrorCode error) {
     return error == ErrorCode::INVALID_READ ||
            error == ErrorCode::OBJECT_ALREADY_EXISTS;
@@ -790,6 +650,16 @@ tl::expected<void, ErrorCode> FileStorage::Heartbeat() {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
 
+    // A drain deregistered the disk tier on purpose. Skipping the whole tick
+    // matters for the SEGMENT_NOT_FOUND branch below, which would re-mount the
+    // segment and re-register every object; there is also no point taking new
+    // offload work for a store that is leaving. The client TTL is renewed by
+    // Ping on the storage heartbeat thread, not here, so the client stays
+    // alive for its memory segments.
+    if (draining_.load()) {
+        return {};
+    }
+
     // Join previous rescan if completed
     if (rescan_future_.valid() && rescan_future_.wait_for(std::chrono::seconds(
                                       0)) == std::future_status::ready) {
@@ -816,8 +686,19 @@ tl::expected<void, ErrorCode> FileStorage::Heartbeat() {
     // === STEP 1: Send heartbeat and get offloading decisions ===
     {
         MutexLocker locker(&offloading_mutex_);
-        auto heartbeat_result = client_->OffloadObjectHeartbeat(
-            enable_offloading_, offloading_objects);
+        // Re-checked under the lock: the entry check above is only a fast
+        // path. A drain (which latches and deregisters under this same
+        // mutex) may have completed while this tick was parked on it; going
+        // on would hit SEGMENT_NOT_FOUND below and re-mount the segment the
+        // drain just deregistered.
+        if (draining_.load()) {
+            return {};
+        }
+        auto fetch_offload_tasks = [&]() -> tl::expected<void, ErrorCode> {
+            return client_->OffloadObjectHeartbeat(enable_offloading_,
+                                                   offloading_objects);
+        };
+        auto heartbeat_result = fetch_offload_tasks();
         if (!heartbeat_result) {
             ErrorCode err = heartbeat_result.error();
             if (err == ErrorCode::SEGMENT_NOT_FOUND) {
@@ -844,8 +725,7 @@ tl::expected<void, ErrorCode> FileStorage::Heartbeat() {
                                 << "heartbeat recovery: " << cap_result.error();
                         }
                     }
-                    heartbeat_result = client_->OffloadObjectHeartbeat(
-                        enable_offloading_, offloading_objects);
+                    heartbeat_result = fetch_offload_tasks();
                     if (!heartbeat_result) {
                         LOG(ERROR) << "Heartbeat failed after re-registration: "
                                    << heartbeat_result.error();
@@ -931,6 +811,45 @@ void FileStorage::RemoveAll() {
     LOG(INFO) << "FileStorage::RemoveAll: cleared storage backend";
 }
 
+tl::expected<void, ErrorCode> FileStorage::DrainLocalDiskSegment(
+    uint64_t grace_period_ms) {
+    if (client_ == nullptr) {
+        LOG(ERROR) << "client is nullptr";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    // Latch and deregister under offloading_mutex_, the lock Heartbeat holds
+    // across its master RPCs and the SEGMENT_NOT_FOUND re-mount. The latch
+    // alone is not enough: a heartbeat that read draining_ == false before
+    // this store() and was then scheduled out would, on resume, see
+    // SEGMENT_NOT_FOUND from the deregistration below and re-mount the
+    // segment. Under the mutex, such a tick is either still parked on the
+    // lock (it re-checks draining_ once it gets it and skips) or it already
+    // finished its RPCs before we latched (anything it mounted or registered
+    // is deregistered again right here, and the master refuses registrations
+    // that arrive after this call returns -- see
+    // MasterService::NotifyOffloadSuccess).
+    {
+        MutexLocker locker(&offloading_mutex_);
+        draining_.store(true);
+
+        auto result = client_->UnmountLocalDiskSegment();
+        if (!result) {
+            LOG(ERROR) << "action=drain_local_disk_segment, error="
+                       << result.error();
+            draining_.store(false);
+            return result;
+        }
+    }
+
+    LOG(INFO) << "action=drain_local_disk_segment, grace_period_ms="
+              << grace_period_ms;
+    if (grace_period_ms > 0) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(grace_period_ms));
+    }
+    return {};
+}
+
 tl::expected<void, ErrorCode> FileStorage::ProcessPromotionTasks() {
     if (client_ == nullptr) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
@@ -1023,7 +942,8 @@ tl::expected<void, ErrorCode> FileStorage::ProcessPromotionTasks() {
         // staging space when the local goes out of scope.
         std::vector<std::string> single_key{storage_key};
         std::vector<int64_t> single_size{size};
-        auto allocate_res = AllocateBatch(single_key, single_size);
+        auto allocate_res =
+            AllocateBatch(single_key, single_size, *client_buffer_allocator_);
         if (!allocate_res) {
             LOG(WARNING) << "Promotion: AllocateBatch failed for key=" << key
                          << ", error=" << allocate_res.error();
@@ -1156,7 +1076,8 @@ tl::expected<void, ErrorCode> FileStorage::RegisterLocalMemory() {
 
 tl::expected<std::shared_ptr<FileStorage::AllocatedBatch>, ErrorCode>
 FileStorage::AllocateBatch(const std::vector<std::string>& keys,
-                           const std::vector<int64_t>& sizes) {
+                           const std::vector<int64_t>& sizes,
+                           ClientBufferAllocator& allocator) {
     if (keys.size() != sizes.size()) {
         LOG(ERROR) << "Mismatched keys and sizes count: keys=" << keys.size()
                    << ", sizes=" << sizes.size();
@@ -1179,16 +1100,18 @@ FileStorage::AllocateBatch(const std::vector<std::string>& keys,
             return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
         }
 
-        // Allocate oversized buffer for O_DIRECT alignment:
-        //   +4096 for aligning the ptr to 4096 boundary
-        //   +4096 for aligned read tail padding (actual_offset may not be
-        //   aligned)
         size_t data_size = static_cast<size_t>(sizes[i]);
-        size_t alloc_size =
-            align_up(data_size, kDirectIOAlignment) + 2 * kDirectIOAlignment;
+        size_t alloc_size = std::max<size_t>(data_size, 1);
+        if (config_.use_uring) {
+            // O_DIRECT reads need room to align the pointer and to round an
+            // unaligned file range out to full pages.
+            alloc_size = align_up(data_size, kDirectIOAlignment) +
+                         2 * kDirectIOAlignment;
+        }
 
-        auto alloc_result = client_buffer_allocator_->allocate(alloc_size);
-        if (!alloc_result && !gc_triggered) {
+        auto alloc_result = allocator.allocate(alloc_size);
+        if (!alloc_result && !gc_triggered &&
+            &allocator == client_buffer_allocator_.get()) {
             gc_triggered = true;
             {
                 MutexLocker locker(&client_buffer_mutex_);
@@ -1202,28 +1125,25 @@ FileStorage::AllocateBatch(const std::vector<std::string>& keys,
                     }
                 }
             }
-            alloc_result = client_buffer_allocator_->allocate(alloc_size);
+            alloc_result = allocator.allocate(alloc_size);
         }
         if (!alloc_result) {
-            LOG(ERROR) << "Failed to allocate slice buffer, size = "
-                       << alloc_size << " (data_size=" << data_size
-                       << "), key = " << keys[i];
             return tl::make_unexpected(ErrorCode::BUFFER_OVERFLOW);
         }
 
-        // Align ptr to 4096 boundary for O_DIRECT
-        void* raw_ptr = alloc_result->ptr();
-        void* aligned_ptr = reinterpret_cast<void*>(
-            (reinterpret_cast<uintptr_t>(raw_ptr) + kDirectIOAlignment - 1) &
-            ~(kDirectIOAlignment - 1));
+        void* data_ptr = alloc_result->ptr();
+        if (config_.use_uring) {
+            data_ptr =
+                reinterpret_cast<void*>((reinterpret_cast<uintptr_t>(data_ptr) +
+                                         kDirectIOAlignment - 1) &
+                                        ~(kDirectIOAlignment - 1));
+        }
 
         total_size += data_size;
-        // Slice records data_size; the buffer behind aligned_ptr is oversized
-        // to accommodate aligned reads
-        result->slices.emplace(keys[i], Slice{aligned_ptr, data_size});
+        result->slices.emplace(keys[i], Slice{data_ptr, data_size});
         // pointers will be adjusted after BatchLoad (offset_in_buffer
         // correction)
-        result->pointers.emplace_back(reinterpret_cast<uintptr_t>(aligned_ptr));
+        result->pointers.emplace_back(reinterpret_cast<uintptr_t>(data_ptr));
         result->handles.emplace_back(std::move(alloc_result.value()));
         result->lease_timeout = lease_timeout;
     }
@@ -1256,6 +1176,14 @@ void FileStorage::ClientBufferGCThreadFunc() {
     LOG(INFO) << "action=client_buffer_gc_thread_stopped";
 }
 
+tl::expected<bool, ErrorCode> FileStorage::Exists(const std::string& key) {
+    if (!storage_backend_) {
+        LOG(ERROR) << "Storage backend is not initialized. Call Init() first.";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return storage_backend_->IsExist(key);
+}
+
 bool FileStorage::ReleaseBuffer(uint64_t batch_id) {
     MutexLocker locker(&client_buffer_mutex_);
     auto it = client_buffer_allocated_batches_.find(batch_id);
@@ -1288,6 +1216,17 @@ tl::expected<void, ErrorCode> FileStorage::ReRegisterOffloadedObjects() {
             [this, &total_keys, &total_batches, &total_failures](
                 const std::vector<std::string>& keys,
                 std::vector<StorageObjectMetadata>& metadatas) {
+                // A rescan can be mid-flight when a drain deregisters the
+                // disk tier; every batch it would register from here on
+                // re-advertises the departing store. The master refuses such
+                // registrations anyway (the segment entry is gone), so this
+                // stops the scan on the first batch instead of on a refused
+                // RPC.
+                if (draining_.load()) {
+                    LOG(INFO) << "ReRegisterOffloadedObjects: aborting scan, "
+                              << "the disk tier is draining";
+                    return ErrorCode::SEGMENT_NOT_FOUND;
+                }
                 total_batches++;
                 total_keys += keys.size();
                 for (auto& metadata : metadatas) {
@@ -1314,6 +1253,12 @@ tl::expected<void, ErrorCode> FileStorage::ReRegisterOffloadedObjects() {
     LOG(INFO) << "ReRegisterOffloadedObjects: ScanMeta returned. success="
               << scan_meta_result.has_value();
     if (!scan_meta_result) {
+        if (config_.enable_dfs &&
+            scan_meta_result.error() == ErrorCode::NOT_SUPPORTED) {
+            LOG(INFO) << "ReRegisterOffloadedObjects: Currently, DFS ScanMeta "
+                         "is not supported; skip";
+            return {};
+        }
         LOG(ERROR) << "ReRegisterOffloadedObjects: ScanMeta failed: "
                    << scan_meta_result.error();
         return scan_meta_result;
diff --git a/mooncake-store/src/ha/common/redis/redis_connection.cpp b/mooncake-store/src/ha/common/redis/redis_connection.cpp
index d694cb40df..3edc5c2861 100644
--- a/mooncake-store/src/ha/common/redis/redis_connection.cpp
+++ b/mooncake-store/src/ha/common/redis/redis_connection.cpp
@@ -2,10 +2,10 @@
 
 #include <algorithm>
 #include <chrono>
-#include <cstdlib>
-#include <cstring>
 #include <exception>
 
+#include "config/redis_connection_config.h"
+
 #ifdef STORE_USE_REDIS
 #include <hiredis/hiredis.h>
 #endif
@@ -74,11 +74,11 @@ tl::expected<int, ErrorCode> ParsePositiveInt(std::string_view text,
 }
 
 tl::expected<int, ErrorCode> ResolveRedisDbIndex() {
-    const char* raw_db_index = std::getenv("MC_REDIS_DB_INDEX");
-    if (raw_db_index == nullptr || std::strlen(raw_db_index) == 0) {
-        return 0;
+    const auto config = RedisConnectionConfig::FromEnvironment();
+    if (!config.has_value()) {
+        return tl::make_unexpected(config.error());
     }
-    return ParsePositiveInt(raw_db_index, 0, 255);
+    return config->db_index;
 }
 
 tl::expected<RedisEndpoint, ErrorCode> ParseRedisEndpoint(
@@ -174,9 +174,9 @@ tl::expected<RedisContextPtr, ErrorCode> ConnectRedis(
         return tl::make_unexpected(endpoint.error());
     }
 
-    auto db_index = ResolveRedisDbIndex();
-    if (!db_index) {
-        return tl::make_unexpected(db_index.error());
+    const auto config = RedisConnectionConfig::FromEnvironment();
+    if (!config.has_value()) {
+        return tl::make_unexpected(config.error());
     }
 
     timeval connect_timeout{};
@@ -195,26 +195,26 @@ tl::expected<RedisContextPtr, ErrorCode> ConnectRedis(
         return tl::make_unexpected(connection_error);
     }
 
-    const char* username = std::getenv("MC_REDIS_USERNAME");
-    const char* password = std::getenv("MC_REDIS_PASSWORD");
-    if (password != nullptr && std::strlen(password) > 0) {
+    if (!config->password.empty()) {
         RedisReplyPtr reply;
-        if (username != nullptr && std::strlen(username) > 0) {
+        if (!config->username.empty()) {
             reply.reset(static_cast<redisReply*>(redisCommand(
-                context.get(), "AUTH %b %b", username, std::strlen(username),
-                password, std::strlen(password))));
+                context.get(), "AUTH %b %b", config->username.data(),
+                config->username.size(), config->password.data(),
+                config->password.size())));
         } else {
-            reply.reset(static_cast<redisReply*>(redisCommand(
-                context.get(), "AUTH %b", password, std::strlen(password))));
+            reply.reset(static_cast<redisReply*>(
+                redisCommand(context.get(), "AUTH %b", config->password.data(),
+                             config->password.size())));
         }
         if (reply == nullptr || reply->type == REDIS_REPLY_ERROR) {
             return tl::make_unexpected(connection_error);
         }
     }
 
-    if (db_index.value() != 0) {
+    if (config->db_index != 0) {
         RedisReplyPtr reply(static_cast<redisReply*>(
-            redisCommand(context.get(), "SELECT %d", db_index.value())));
+            redisCommand(context.get(), "SELECT %d", config->db_index)));
         if (reply == nullptr || reply->type == REDIS_REPLY_ERROR) {
             return tl::make_unexpected(connection_error);
         }
diff --git a/mooncake-store/src/ha/kv/etcd_ha_kv_backend.cpp b/mooncake-store/src/ha/kv/etcd_ha_kv_backend.cpp
index 530d62c449..5f281d0bb8 100644
--- a/mooncake-store/src/ha/kv/etcd_ha_kv_backend.cpp
+++ b/mooncake-store/src/ha/kv/etcd_ha_kv_backend.cpp
@@ -22,6 +22,8 @@ EtcdHelper::TxnCompareKind ToEtcdCompareKind(KvCompareKind kind) {
             return EtcdHelper::TxnCompareKind::kValueEquals;
         case KvCompareKind::kKeyNotExists:
             return EtcdHelper::TxnCompareKind::kKeyNotExists;
+        case KvCompareKind::kCreateRevisionEquals:
+            return EtcdHelper::TxnCompareKind::kCreateRevisionEquals;
     }
     return EtcdHelper::TxnCompareKind::kValueEquals;
 }
@@ -74,13 +76,28 @@ ErrorCode EtcdHaKvBackend::Range(std::string_view begin_key,
 
 bool EtcdHaKvBackend::SupportsTxn() const { return true; }
 
+ErrorCode EtcdHaKvBackend::DeleteRange(std::string_view begin_key,
+                                       std::string_view end_key) {
+    // etcd treats an empty end as a single-key delete and NUL as unbounded.
+    if (begin_key.empty() || end_key.empty() ||
+        end_key == std::string_view("\0", 1) || begin_key > end_key) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (begin_key == end_key) {
+        return ErrorCode::OK;
+    }
+    return EtcdHelper::DeleteRange(begin_key.data(), begin_key.size(),
+                                   end_key.data(), end_key.size());
+}
+
 ErrorCode EtcdHaKvBackend::Txn(const KvTxn& txn) {
     std::vector<EtcdHelper::TxnCompare> compares;
     compares.reserve(txn.compares.size());
     for (const auto& compare : txn.compares) {
         compares.push_back({.key = compare.key,
                             .kind = ToEtcdCompareKind(compare.kind),
-                            .expected_value = compare.expected_value});
+                            .expected_value = compare.expected_value,
+                            .expected_revision = compare.expected_revision});
     }
 
     std::vector<EtcdHelper::TxnPut> puts;
diff --git a/mooncake-store/src/ha/leadership/backends/etcd/etcd_leader_coordinator.cpp b/mooncake-store/src/ha/leadership/backends/etcd/etcd_leader_coordinator.cpp
index 26bc7b23e7..40a875baf7 100644
--- a/mooncake-store/src/ha/leadership/backends/etcd/etcd_leader_coordinator.cpp
+++ b/mooncake-store/src/ha/leadership/backends/etcd/etcd_leader_coordinator.cpp
@@ -4,8 +4,6 @@
 #include <atomic>
 #include <chrono>
 #include <condition_variable>
-#include <cstdlib>
-#include <cstring>
 #include <mutex>
 #include <optional>
 #include <thread>
@@ -14,6 +12,7 @@
 #include <ylt/util/tl/expected.hpp>
 
 #include "types.h"
+#include "config/ha_cluster_namespace_config.h"
 
 namespace mooncake {
 namespace ha {
@@ -23,6 +22,8 @@ namespace etcd {
 namespace {
 
 constexpr int kKeepAliveReadyTimeoutMs = 1000;
+constexpr std::string_view kServiceWarmingPrefix =
+    "__mooncake_service_warming__:";
 // Fallback poll interval used only when a watch cannot be armed (e.g. the watch
 // RPC fails, or the remaining timeout is too small to be worth a watch). The
 // steady-state path blocks on an etcd watch and does not poll.
@@ -45,6 +46,14 @@ struct ViewChangeWatchState {
     bool broken = false;
 };
 
+std::string MakeServiceWarmingValue(const OwnerToken& owner_token) {
+    return std::string(kServiceWarmingPrefix) + owner_token;
+}
+
+bool IsServiceWarmingValue(std::string_view value) {
+    return value.starts_with(kServiceWarmingPrefix);
+}
+
 // C-style trampoline invoked by the etcd watch goroutine for every event on the
 // watched prefix (PUT / DELETE / WATCH_BROKEN). Any event is treated as "the
 // view may have changed"; the waiter re-reads to find out what actually
@@ -185,6 +194,13 @@ EtcdLeaderCoordinator::ReadCurrentView() {
         return tl::make_unexpected(err);
     }
 
+    // The key exists during leader warmup to preserve election fencing, but
+    // its value is not a routable endpoint until PublishServiceReady updates
+    // it after the RPC listener starts.
+    if (IsServiceWarmingValue(leader_address)) {
+        return std::optional<MasterView>{std::nullopt};
+    }
+
     return std::optional<MasterView>{
         MasterView{.leader_address = std::move(leader_address),
                    .view_version = view_version}};
@@ -205,9 +221,11 @@ EtcdLeaderCoordinator::TryAcquireLeadership(const std::string& leader_address) {
     }
 
     ViewVersionId view_version = 0;
+    const auto owner_token = MakeOwnerToken(lease_id);
+    const auto warming_value = MakeServiceWarmingValue(owner_token);
     err = EtcdHelper::CreateWithLease(
         master_view_key_.c_str(), master_view_key_.size(),
-        leader_address.c_str(), leader_address.size(), lease_id, view_version);
+        warming_value.c_str(), warming_value.size(), lease_id, view_version);
     if (err == ErrorCode::ETCD_TRANSACTION_FAIL) {
         auto revoke_err = EtcdHelper::RevokeLease(lease_id);
         if (revoke_err != ErrorCode::OK) {
@@ -238,7 +256,7 @@ EtcdLeaderCoordinator::TryAcquireLeadership(const std::string& leader_address) {
     LeadershipSession session{
         .view = MasterView{.leader_address = leader_address,
                            .view_version = view_version},
-        .owner_token = MakeOwnerToken(lease_id),
+        .owner_token = owner_token,
         .lease_ttl = std::chrono::seconds(DEFAULT_MASTER_VIEW_LEASE_TTL_SEC),
     };
 
@@ -259,6 +277,42 @@ EtcdLeaderCoordinator::TryAcquireLeadership(const std::string& leader_address) {
     };
 }
 
+ErrorCode EtcdLeaderCoordinator::PublishServiceReady(
+    const LeadershipSession& session) {
+    auto err = EnsureConnected();
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    if (session.view.leader_address.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    const auto warming_value = MakeServiceWarmingValue(session.owner_token);
+    err = EtcdHelper::TxnCompareAndPut(
+        {{.key = master_view_key_,
+          .kind = EtcdHelper::TxnCompareKind::kValueEquals,
+          .expected_value = warming_value}},
+        {{.key = master_view_key_,
+          .value = session.view.leader_address,
+          .preserve_lease = true}});
+    if (err == ErrorCode::OK) {
+        return err;
+    }
+    if (err != ErrorCode::ETCD_TRANSACTION_FAIL) {
+        return err;
+    }
+
+    // Publication is intentionally idempotent because a retry may observe a
+    // successful etcd write after the client-side RPC timed out.
+    auto current_view = ReadCurrentView();
+    if (current_view && current_view->has_value() &&
+        current_view->value().leader_address == session.view.leader_address &&
+        current_view->value().view_version == session.view.view_version) {
+        return ErrorCode::OK;
+    }
+    return ErrorCode::ETCD_TRANSACTION_FAIL;
+}
+
 tl::expected<bool, ErrorCode> EtcdLeaderCoordinator::RenewLeadership(
     const LeadershipSession& session) {
     auto err = EnsureConnected();
@@ -564,14 +618,7 @@ ClusterNamespace EtcdLeaderCoordinator::ResolveClusterNamespace(
         return cluster_namespace;
     }
 
-    std::string resolved_namespace;
-    const char* env_cluster_id = std::getenv("MC_STORE_CLUSTER_ID");
-    if (env_cluster_id != nullptr && std::strlen(env_cluster_id) > 0) {
-        resolved_namespace = env_cluster_id;
-    } else {
-        resolved_namespace = DEFAULT_CLUSTER_ID;
-    }
-    return resolved_namespace;
+    return HaClusterNamespaceConfig::FromEnvironment().cluster_namespace;
 }
 
 std::string EtcdLeaderCoordinator::BuildMasterViewKey(
diff --git a/mooncake-store/src/ha/leadership/backends/redis/redis_leader_coordinator.cpp b/mooncake-store/src/ha/leadership/backends/redis/redis_leader_coordinator.cpp
index e8539c014f..76ff1a30c2 100644
--- a/mooncake-store/src/ha/leadership/backends/redis/redis_leader_coordinator.cpp
+++ b/mooncake-store/src/ha/leadership/backends/redis/redis_leader_coordinator.cpp
@@ -2,8 +2,6 @@
 
 #include <chrono>
 #include <exception>
-#include <cstdlib>
-#include <cstring>
 #include <memory>
 #include <optional>
 #include <string>
@@ -13,6 +11,7 @@
 #include <glog/logging.h>
 
 #include "types.h"
+#include "config/ha_cluster_namespace_config.h"
 #ifdef STORE_USE_REDIS
 #include <hiredis/hiredis.h>
 #endif
@@ -662,14 +661,7 @@ ClusterNamespace RedisLeaderCoordinator::ResolveClusterNamespace(
         return cluster_namespace;
     }
 
-    std::string resolved_namespace;
-    const char* env_cluster_id = std::getenv("MC_STORE_CLUSTER_ID");
-    if (env_cluster_id != nullptr && std::strlen(env_cluster_id) > 0) {
-        resolved_namespace = env_cluster_id;
-    } else {
-        resolved_namespace = DEFAULT_CLUSTER_ID;
-    }
-    return resolved_namespace;
+    return HaClusterNamespaceConfig::FromEnvironment().cluster_namespace;
 }
 
 std::string RedisLeaderCoordinator::BuildMasterViewKey(
diff --git a/mooncake-store/src/ha/leadership/master_service_supervisor.cpp b/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
index a60995a353..bf7588d1f3 100644
--- a/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
+++ b/mooncake-store/src/ha/leadership/master_service_supervisor.cpp
@@ -3,7 +3,6 @@
 #include <atomic>
 #include <chrono>
 #include <csignal>
-#include <cstdlib>
 #include <memory>
 #include <optional>
 #include <string_view>
@@ -12,8 +11,11 @@
 #include <glog/logging.h>
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 
+#include "config/rpc_protocol_config.h"
 #include "ha/leadership/leader_coordinator_factory.h"
 #include "ha/leadership/leader_label_reconciler.h"
+#include "ha/kv/etcd_ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_storage.h"
 #include "ha/standby_controller.h"
 #include "k8s_lease_helper.h"
 #include "master_admin_service.h"
@@ -197,6 +199,22 @@ void ApplyCurrentView(MasterAdminServer& admin_server,
                          wait_result.current_view);
 }
 
+ErrorCode ClaimProducerViewForServing(
+    const HABackendSpec& spec, const MasterServiceSupervisorConfig& config,
+    ViewVersionId view_version) {
+    if (!config.enable_oplog || spec.type != HABackendType::ETCD ||
+        config.cluster_id.empty()) {
+        return ErrorCode::OK;
+    }
+    if (view_version == 0) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    EtcdHaKvBackend backend;
+    OpLogBatchStorage storage(config.cluster_id, backend);
+    return storage.ClaimProducerView(view_version);
+}
+
 void EnterStandbyMode(MasterAdminServer& admin_server,
                       StandbyController& standby_controller,
                       std::atomic<bool>& accept_runtime_updates,
@@ -217,11 +235,11 @@ void EnterStandbyMode(MasterAdminServer& admin_server,
 
 int RunSupervisorLoop(const HABackendSpec& spec,
                       const MasterServiceSupervisorConfig& config,
-                      MasterAdminServer& admin_server) {
+                      MasterAdminServer& admin_server,
+                      std::unique_ptr<StandbyController> standby_controller) {
     auto label_reconciler = MakeLeaderLabelReconciler(config);
     label_reconciler.SetLeader(false);
     SetRuntimeState(admin_server, MasterRuntimeState::kStarting);
-    auto standby_controller = CreateStandbyController(spec, config);
     std::atomic<bool> accept_standby_runtime_updates{false};
     standby_controller->SetStandbyRuntimeStateCallback(
         [&](MasterRuntimeState state) {
@@ -330,14 +348,31 @@ int RunSupervisorLoop(const HABackendSpec& spec,
             continue;
         }
 
+        auto claim_error = ClaimProducerViewForServing(
+            spec, config, leadership_session->view.view_version);
+        if (claim_error != ErrorCode::OK) {
+            EnterStandbyMode(admin_server, *standby_controller,
+                             accept_standby_runtime_updates,
+                             leadership_session->view);
+            if (HandleLeadershipPhaseError(
+                    "producer view claim failure", "claim producer view",
+                    leader_coordinator, *leadership_session, claim_error,
+                    spec.type)) {
+                return -1;
+            }
+            continue;
+        }
+
         accept_standby_runtime_updates.store(false, std::memory_order_release);
         auto promotion_ctx = standby_controller->PromoteStandbyAndExport();
         if (!promotion_ctx) {
             EnterStandbyMode(admin_server, *standby_controller,
                              accept_standby_runtime_updates,
                              leadership_session->view);
-            if (HandleSupervisorError("promote standby for serve",
-                                      promotion_ctx.error(), spec.type)) {
+            if (HandleLeadershipPhaseError(
+                    "standby promotion failure", "promote standby for serve",
+                    leader_coordinator, *leadership_session,
+                    promotion_ctx.error(), spec.type)) {
                 return -1;
             }
             continue;
@@ -374,9 +409,13 @@ int RunSupervisorLoop(const HABackendSpec& spec,
         coro_rpc::coro_rpc_server server(
             config.rpc_thread_num, config.rpc_port, config.rpc_address,
             config.rpc_conn_timeout, config.rpc_enable_tcp_no_delay);
-        const char* protocol = std::getenv("MC_RPC_PROTOCOL");
-        if (protocol && std::string_view(protocol) == "rdma") {
+        if (RpcProtocolConfig::FromEnvironment().use_rdma) {
+#ifdef YLT_ENABLE_IBV
             server.init_ibv();
+#else
+            LOG(WARNING)
+                << "RDMA RPC is disabled at compile time; using TCP RPC";
+#endif
         }
 
         mooncake::WrappedMasterServiceConfig wrapped_config(
@@ -386,18 +425,59 @@ int RunSupervisorLoop(const HABackendSpec& spec,
         wrapped_config.enable_snapshot_restore = false;
         // The serving primary handles heartbeats/unmounts, so forward the
         // metadata cleanup config here like the non-HA path does.
+        // Keep the gate alive until after the service is destroyed because the
+        // OpLog writer owned by the service invokes a callback that uses it.
+        detail::ServingStateGate serving_state;
         auto wrapped_master_service = std::make_shared<WrappedMasterService>(
             wrapped_config, config.http_metadata_server,
             config.http_metadata_remote_url);
+        wrapped_master_service->SetBatchOpLogTerminalCallback(
+            [&](const OrderedOpLogWriterTerminalState& state) {
+                serving_state.RequestShutdown([&]() {
+                    LOG(ERROR) << "Batch OpLog writer terminal: "
+                               << toString(state.error);
+                    DeactivateServingState(admin_server, label_reconciler);
+                    SetRuntimeState(admin_server, MasterRuntimeState::kStandby);
+                    server.stop();
+                });
+            });
 
-        // Restore from standby if we have context
-        if (promotion_ctx->applied_seq_id > 0 ||
-            !promotion_ctx->objects.empty() ||
-            !promotion_ctx->segments.empty()) {
-            wrapped_master_service->RestoreFromStandby(
-                promotion_ctx->objects, promotion_ctx->applied_seq_id,
-                promotion_ctx->segments);
+        // Restore is the serving gate: do not register or expose a candidate
+        // service until the complete promotion context has been applied.
+        SetRuntimeState(admin_server, MasterRuntimeState::kRecovering);
+        auto restore_result =
+            promotion_ctx->metadata_store
+                ? wrapped_master_service->RestoreFromBatchOpLogPromotion(
+                      BatchOpLogPromotionHandoff{
+                          .metadata_store =
+                              std::move(promotion_ctx->metadata_store),
+                          .segments = std::move(promotion_ctx->segments),
+                          .applied_cursor = promotion_ctx->applied_cursor,
+                          .producer_view_version =
+                              promotion_ctx->producer_view_version,
+                          .max_replica_id = promotion_ctx->max_replica_id,
+                      })
+                : wrapped_master_service->RestoreFromStandby(
+                      promotion_ctx->objects, promotion_ctx->applied_seq_id,
+                      promotion_ctx->segments);
+        if (!restore_result) {
+            LOG(ERROR) << "Standby restore failed: "
+                       << toString(restore_result.error());
+            wrapped_master_service.reset();
+            DeactivateServingState(admin_server, label_reconciler);
+            EnterStandbyMode(admin_server, *standby_controller,
+                             accept_standby_runtime_updates,
+                             leadership_session->view);
+            SetRuntimeState(admin_server, MasterRuntimeState::kRecovering);
+            if (HandleLeadershipPhaseError(
+                    "standby restore failure", "restore standby state",
+                    leader_coordinator, *leadership_session,
+                    restore_result.error(), spec.type)) {
+                return -1;
+            }
+            continue;
         }
+        SetRuntimeState(admin_server, MasterRuntimeState::kLeaderWarmup);
 
         mooncake::RegisterRpcService(server, *wrapped_master_service);
 
@@ -428,18 +508,17 @@ int RunSupervisorLoop(const HABackendSpec& spec,
             continue;
         }
 
-        std::atomic<bool> serve_shutdown_requested{false};
         auto leadership_monitor = leader_coordinator.StartLeadershipMonitor(
-            *leadership_session,
-            [&server, &admin_server, &serve_shutdown_requested,
-             &label_reconciler](auto reason) {
-                serve_shutdown_requested.store(true, std::memory_order_release);
-                admin_server.SetServiceAvailable(false);
-                label_reconciler.SetLeader(false);
-                SetRuntimeState(admin_server, MasterRuntimeState::kStandby);
-                LOG(INFO) << "Trying to stop server, reason="
-                          << LeadershipLossReasonToString(reason);
-                server.stop();
+            *leadership_session, [&server, &admin_server, &serving_state,
+                                  &label_reconciler](auto reason) {
+                serving_state.RequestShutdown([&]() {
+                    admin_server.SetServiceAvailable(false);
+                    label_reconciler.SetLeader(false);
+                    SetRuntimeState(admin_server, MasterRuntimeState::kStandby);
+                    LOG(INFO) << "Trying to stop server, reason="
+                              << LeadershipLossReasonToString(reason);
+                    server.stop();
+                });
             });
         if (!leadership_monitor) {
             DeactivateServingState(admin_server, label_reconciler);
@@ -456,10 +535,21 @@ int RunSupervisorLoop(const HABackendSpec& spec,
         }
         auto leadership_monitor_handle = std::move(leadership_monitor.value());
 
-        async_simple::Future<coro_rpc::err_code> ec = server.async_start();
-        if (ec.hasResult()) {
+        std::optional<async_simple::Future<coro_rpc::err_code>> ec;
+        serving_state.RunIfActive([&]() { ec.emplace(server.async_start()); });
+        if (!ec.has_value()) {
+            StopLeadershipMonitor(leadership_monitor_handle);
+            DeactivateServingState(admin_server, label_reconciler);
+            EnterStandbyMode(admin_server, *standby_controller,
+                             accept_standby_runtime_updates, std::nullopt);
+            LogLeadershipReleaseWarning(
+                "serve startup cancellation",
+                leader_coordinator.ReleaseLeadership(*leadership_session));
+            continue;
+        }
+        if (ec->hasResult()) {
             LOG(ERROR) << "Failed to start master service: "
-                       << ec.result().value();
+                       << ec->result().value();
             StopLeadershipMonitor(leadership_monitor_handle);
             DeactivateServingState(admin_server, label_reconciler);
             EnterStandbyMode(admin_server, *standby_controller,
@@ -473,15 +563,50 @@ int RunSupervisorLoop(const HABackendSpec& spec,
             return -1;
         }
 
-        if (!serve_shutdown_requested.load(std::memory_order_acquire)) {
-            ActivateServingState(admin_server, wrapped_master_service,
-                                 label_reconciler);
+        ErrorCode publish_ready_err = ErrorCode::OK;
+        if (serving_state.IsActive()) {
+            // The backend call can take several seconds. Keep it outside the
+            // transition gate so leadership loss can stop the listener
+            // promptly.
+            publish_ready_err =
+                leader_coordinator.PublishServiceReady(*leadership_session);
+            if (publish_ready_err == ErrorCode::OK) {
+                serving_state.RunIfActive([&]() {
+                    ActivateServingState(admin_server, wrapped_master_service,
+                                         label_reconciler);
+                });
+            } else {
+                serving_state.RequestShutdown([&]() {
+                    DeactivateServingState(admin_server, label_reconciler);
+                    server.stop();
+                });
+            }
+        }
+
+        if (publish_ready_err != ErrorCode::OK) {
+            LOG(ERROR) << "Failed to publish master service readiness: "
+                       << toString(publish_ready_err);
+            StopLeadershipMonitor(leadership_monitor_handle);
+            auto server_err = std::move(ec.value()).get();
+            LOG(ERROR) << "Master service stopped after readiness failure: "
+                       << server_err;
+            EnterStandbyMode(admin_server, *standby_controller,
+                             accept_standby_runtime_updates,
+                             leadership_session->view);
+            if (HandleLeadershipPhaseError(
+                    "service readiness publication failure",
+                    "publish master service readiness", leader_coordinator,
+                    *leadership_session, publish_ready_err, spec.type)) {
+                return -1;
+            }
+            continue;
         }
 
-        auto server_err = std::move(ec).get();
+        auto server_err = std::move(ec.value()).get();
         LOG(ERROR) << "Master service stopped: " << server_err;
 
         StopLeadershipMonitor(leadership_monitor_handle);
+        wrapped_master_service->StopBatchOpLogWriter();
         DeactivateServingState(admin_server, label_reconciler);
         auto err = leader_coordinator.ReleaseLeadership(*leadership_session);
         LOG(INFO) << "Release leadership: " << toString(err);
@@ -514,15 +639,25 @@ int MasterServiceSupervisor::Start() {
         return -1;
     }
 
+    std::unique_ptr<StandbyController> standby_controller;
+    try {
+        standby_controller = CreateStandbyController(*spec, config_);
+    } catch (const std::exception& error) {
+        LOG(ERROR) << "Standby dependency initialization failed: "
+                   << error.what();
+        return -1;
+    }
+
     mooncake::MasterAdminServer admin_server(
         static_cast<uint16_t>(config_.metrics_port),
-        config_.enable_metric_reporting);
+        config_.enable_metric_reporting, config_.metrics_host);
     if (!admin_server.Start()) {
         LOG(ERROR) << "Failed to start master admin server, metrics_port="
                    << config_.metrics_port;
         return -1;
     }
-    return RunSupervisorLoop(*spec, config_, admin_server);
+    return RunSupervisorLoop(*spec, config_, admin_server,
+                             std::move(standby_controller));
 }
 
 }  // namespace ha
diff --git a/mooncake-store/src/ha/oplog/oplog_applier.cpp b/mooncake-store/src/ha/oplog/oplog_applier.cpp
index b715b30d06..faaf2ef9cc 100644
--- a/mooncake-store/src/ha/oplog/oplog_applier.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_applier.cpp
@@ -131,7 +131,6 @@ void OpLogApplier::ApplyPutEnd(const OpLogEntry& entry) {
                      << entry.object_key
                      << ", sequence_id=" << entry.sequence_id;
         StandbyObjectMetadata empty_metadata;
-        empty_metadata.last_sequence_id = entry.sequence_id;
         if (!metadata_store_->PutMetadata(entry.tenant_id, entry.object_key,
                                           empty_metadata)) {
             LOG(ERROR) << "OpLogApplier: failed to PutMetadata key="
@@ -151,15 +150,13 @@ void OpLogApplier::ApplyPutEnd(const OpLogEntry& entry) {
                    << ", error_code=" << static_cast<int>(result);
         // Fallback to empty metadata if parsing fails
         StandbyObjectMetadata empty_metadata;
-        empty_metadata.last_sequence_id = entry.sequence_id;
         metadata_store_->PutMetadata(entry.tenant_id, entry.object_key,
                                      empty_metadata);
         return;
     }
 
     // Convert to StandbyObjectMetadata and store
-    StandbyObjectMetadata metadata =
-        payload.ToStandbyMetadata(entry.sequence_id);
+    StandbyObjectMetadata metadata = payload.ToStandbyMetadata();
 
     if (!metadata_store_->PutMetadata(entry.tenant_id, entry.object_key,
                                       metadata)) {
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_codec.cpp b/mooncake-store/src/ha/oplog/oplog_batch_codec.cpp
index 5c5a644bfa..2fbb8174e5 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_codec.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_codec.cpp
@@ -11,7 +11,7 @@
 #include <json/json.h>
 #endif
 
-#include "utils/base64.h"
+#include "common/base64.h"
 
 namespace mooncake {
 
@@ -182,12 +182,14 @@ bool DecodeDurablePrefix(const std::string& value, DurablePrefix* prefix,
         SetReason(reason, "unsupported durable prefix schema_version");
         return false;
     }
-    if (!GetUInt64Field(root, "batch_id", &prefix->batch_id, reason)) {
+    DurablePrefix decoded;
+    if (!GetUInt64Field(root, "batch_id", &decoded.batch_id, reason)) {
         return false;
     }
-    if (!GetUInt64Field(root, "last_seq", &prefix->last_seq, reason)) {
+    if (!GetUInt64Field(root, "last_seq", &decoded.last_seq, reason)) {
         return false;
     }
+    *prefix = decoded;
     return true;
 }
 
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp b/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
index 1c1d9295bd..2ae828555a 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_standby_reader.cpp
@@ -29,11 +29,72 @@ OpLogBatchStandbyReader::OpLogBatchStandbyReader(std::string cluster_id,
                                                  OpLogApplier& applier)
     : storage_(std::move(cluster_id), backend), applier_(applier) {}
 
+ErrorCode OpLogBatchStandbyReader::SetBaselineCursor(
+    const DurablePrefix& cursor) {
+    if ((cursor.batch_id == 0) != (cursor.last_seq == 0)) {
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    }
+    const uint64_t expected = applier_.GetExpectedSequenceId();
+    if (expected == 0 || IsSequenceOlder(expected - 1, cursor.last_seq)) {
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    }
+    batch_format_seen_ = true;
+    require_complete_history_ = cursor.batch_id == 0;
+    last_observed_prefix_ = cursor;
+    last_applied_durable_prefix_ = cursor;
+    last_applied_batch_id_ = cursor.batch_id;
+    last_scanned_batch_last_seq_ =
+        cursor.batch_id == 0 ? std::nullopt
+                             : std::optional<uint64_t>(cursor.last_seq);
+    return ErrorCode::OK;
+}
+
 OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
     size_t max_batches) {
     OpLogBatchStandbyPollResult result;
+    uint64_t floor = 0;
+    ErrorCode err = storage_.ReadCompactionFloor(floor);
+    if (err != ErrorCode::OK && err != ErrorCode::ETCD_KEY_NOT_EXIST) {
+        SetPollError(result, err, IsRetryableBackendError(err));
+        return result;
+    }
+    if (err == ErrorCode::OK && last_applied_batch_id_ < floor) {
+        result.compaction_floor = floor;
+        result.disposition =
+            OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED;
+        result.error = ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+        return result;
+    }
+    result = PollBatches(max_batches, floor);
+    if (result.disposition == OpLogBatchStandbyPollDisposition::FATAL) {
+        // Pruning may advance after the initial floor read. Classify missing
+        // history against the current floor before declaring corruption.
+        uint64_t current_floor = 0;
+        err = storage_.ReadCompactionFloor(current_floor);
+        if (err == ErrorCode::OK && last_applied_batch_id_ < current_floor) {
+            result.compaction_floor = current_floor;
+            result.disposition =
+                OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED;
+            result.error = ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+        } else if (err == ErrorCode::OK && current_floor > floor &&
+                   current_floor == last_applied_batch_id_) {
+            const auto applied_batches = result.applied_batches;
+            result = PollBatches(max_batches, current_floor);
+            result.applied_batches += applied_batches;
+        } else if (err != ErrorCode::OK &&
+                   err != ErrorCode::ETCD_KEY_NOT_EXIST) {
+            SetPollError(result, err, IsRetryableBackendError(err));
+        }
+    }
+    return result;
+}
+
+OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollBatches(
+    size_t max_batches, uint64_t floor) {
+    OpLogBatchStandbyPollResult result;
+    result.compaction_floor = floor;
     DurablePrefix prefix;
-    ErrorCode err = storage_.ReadDurablePrefix(prefix);
+    auto err = storage_.ReadDurablePrefix(prefix);
     if (err == ErrorCode::ETCD_KEY_NOT_EXIST) {
         if (batch_format_seen_) {
             SetPollError(result, ErrorCode::INCOMPLETE_OPLOG_CATCH_UP, false);
@@ -63,10 +124,23 @@ OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
         last_observed_prefix_ = prefix;
         if (prefix.last_seq != 0) {
             SetPollError(result, ErrorCode::INCOMPLETE_OPLOG_CATCH_UP, false);
+        } else if (applier_.GetExpectedSequenceId() == 1) {
+            last_applied_durable_prefix_ = prefix;
         }
         return result;
     }
 
+    // A proven cursor needs no historical batch read: its batch may have
+    // been pruned when the floor equals the durable prefix.
+    if (floor == prefix.batch_id && prefix.batch_id == last_applied_batch_id_ &&
+        last_scanned_batch_last_seq_ == prefix.last_seq &&
+        applier_.GetExpectedSequenceId() > 0 &&
+        applier_.GetExpectedSequenceId() - 1 == prefix.last_seq) {
+        last_observed_prefix_ = prefix;
+        last_applied_durable_prefix_ = prefix;
+        return result;
+    }
+
     TestFailPoint::Wait("standby_prefix_read_before_batch");
     OpLogBatchRecord target_batch;
     err = storage_.ReadBatch(prefix.batch_id, target_batch);
@@ -80,6 +154,12 @@ OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
     }
     last_observed_prefix_ = prefix;
     if (prefix.batch_id <= last_applied_batch_id_) {
+        const uint64_t expected = applier_.GetExpectedSequenceId();
+        if (prefix.batch_id == last_applied_batch_id_ &&
+            last_scanned_batch_last_seq_ == prefix.last_seq && expected > 0 &&
+            expected - 1 == prefix.last_seq) {
+            last_applied_durable_prefix_ = prefix;
+        }
         return result;
     }
 
@@ -91,15 +171,24 @@ OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
         return result;
     }
     for (const auto& batch : batches) {
-        if (last_scanned_batch_last_seq_ &&
-            (last_applied_batch_id_ == UINT64_MAX ||
-             batch.batch_id != last_applied_batch_id_ + 1)) {
+        if (last_applied_batch_id_ == UINT64_MAX ||
+            (last_applied_batch_id_ != 0 &&
+             batch.batch_id != last_applied_batch_id_ + 1) ||
+            (last_applied_batch_id_ == 0 && require_complete_history_ &&
+             batch.batch_id != 1)) {
             SetPollError(result, ErrorCode::INCOMPLETE_OPLOG_CATCH_UP, false);
             return result;
         }
-        if (last_scanned_batch_last_seq_ &&
-            (*last_scanned_batch_last_seq_ == UINT64_MAX ||
-             batch.first_seq != *last_scanned_batch_last_seq_ + 1)) {
+        const std::optional<uint64_t> expected_first_seq =
+            last_scanned_batch_last_seq_
+                ? std::optional<uint64_t>(
+                      *last_scanned_batch_last_seq_ == UINT64_MAX
+                          ? 0
+                          : *last_scanned_batch_last_seq_ + 1)
+                : (require_complete_history_ ? std::optional<uint64_t>(1)
+                                             : std::nullopt);
+        if (expected_first_seq && (*expected_first_seq == 0 ||
+                                   batch.first_seq != *expected_first_seq)) {
             SetPollError(result, ErrorCode::INCOMPLETE_OPLOG_CATCH_UP, false);
             return result;
         }
@@ -123,6 +212,7 @@ OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
             }
             ++result.applied_entries;
         }
+        ++result.applied_batches;
         last_applied_batch_id_ = batch.batch_id;
         last_scanned_batch_last_seq_ = batch.last_seq;
         if (last_applied_batch_id_ >= prefix.batch_id) {
@@ -136,6 +226,12 @@ OpLogBatchStandbyPollResult OpLogBatchStandbyReader::PollOnce(
         IsSequenceOlderOrEqual(applier_.GetExpectedSequenceId(),
                                prefix.last_seq)) {
         SetPollError(result, ErrorCode::INCOMPLETE_OPLOG_CATCH_UP, false);
+    } else if (!has_more_pages && last_applied_batch_id_ == prefix.batch_id &&
+               last_scanned_batch_last_seq_ == prefix.last_seq) {
+        const uint64_t expected = applier_.GetExpectedSequenceId();
+        if (expected > 0 && expected - 1 == prefix.last_seq) {
+            last_applied_durable_prefix_ = prefix;
+        }
     }
     return result;
 }
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp b/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
index 8229b2262e..bae18b4b65 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_storage.cpp
@@ -1,12 +1,15 @@
 #include "ha/oplog/oplog_batch_storage.h"
 
 #include <algorithm>
+#include <array>
 #include <charconv>
+#include <string_view>
 
 #include <glog/logging.h>
 
 #include "ha/oplog/oplog_batch_codec.h"
 #include "ha/oplog/oplog_types.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
 #include "ha_metric_manager.h"
 #endif
@@ -50,6 +53,23 @@ bool TryParseBatchIdFromKey(const std::string& key, uint64_t& batch_id) {
            result.ptr == suffix.data() + suffix.size();
 }
 
+bool TryParseProducerView(std::string_view value,
+                          ViewVersionId& producer_view_version) {
+    ViewVersionId parsed = 0;
+    const auto result =
+        std::from_chars(value.data(), value.data() + value.size(), parsed);
+    if (result.ec != std::errc() || result.ptr != value.data() + value.size() ||
+        parsed <= 0 || std::to_string(parsed) != value) {
+        return false;
+    }
+    producer_view_version = parsed;
+    return true;
+}
+
+bool IsAmbiguousTxnError(ErrorCode error) {
+    return error == ErrorCode::ETCD_OPERATION_ERROR;
+}
+
 }  // namespace
 
 OpLogBatchStorage::OpLogBatchStorage(std::string cluster_id,
@@ -98,19 +118,24 @@ ErrorCode OpLogBatchStorage::InitDurablePrefix(DurablePrefix& prefix) {
                             .expected_value = ""});
     txn.puts.push_back(
         {.key = durable_key, .value = EncodeDurablePrefix(initial)});
-    err = backend_.Txn(txn);
-    if (err == ErrorCode::OK) {
+    const ErrorCode txn_err = backend_.Txn(txn);
+    if (txn_err == ErrorCode::OK) {
         prefix = initial;
         return ErrorCode::OK;
     }
-    if (err == ErrorCode::ETCD_TRANSACTION_FAIL) {
-        err = ReadDurablePrefix(prefix);
-        if (err != ErrorCode::OK) {
-            return err;
-        }
-        return ValidateDurablePrefixAtStartup(prefix);
+    if (txn_err != ErrorCode::ETCD_TRANSACTION_FAIL &&
+        !IsAmbiguousTxnError(txn_err)) {
+        return txn_err;
+    }
+
+    err = ReadDurablePrefix(prefix);
+    if (err != ErrorCode::OK) {
+        return IsAmbiguousTxnError(txn_err) &&
+                       err == ErrorCode::ETCD_KEY_NOT_EXIST
+                   ? txn_err
+                   : err;
     }
-    return err;
+    return ValidateDurablePrefixAtStartup(prefix);
 }
 
 ErrorCode OpLogBatchStorage::ReadDurablePrefix(DurablePrefix& prefix) {
@@ -131,6 +156,126 @@ ErrorCode OpLogBatchStorage::ReadDurablePrefix(DurablePrefix& prefix) {
     return ErrorCode::OK;
 }
 
+ErrorCode OpLogBatchStorage::ReadProducerView(
+    ViewVersionId& producer_view_version) const {
+    if (!IsValidClusterId()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    std::string value;
+    ErrorCode err = backend_.Get(BuildProducerViewKey(cluster_id_), value);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    if (!TryParseProducerView(value, producer_view_version)) {
+        LOG(ERROR) << "Invalid producer view value: cluster=" << cluster_id_;
+        return ErrorCode::INTERNAL_ERROR;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode OpLogBatchStorage::ReadCompactionFloor(uint64_t& floor) const {
+    if (!IsValidClusterId()) return ErrorCode::INVALID_PARAMS;
+    std::string value;
+    const auto err = backend_.Get(
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey(cluster_id_), value);
+    if (err != ErrorCode::OK) return err;
+    uint64_t parsed = 0;
+    const auto result =
+        std::from_chars(value.data(), value.data() + value.size(), parsed);
+    if (result.ec != std::errc() || result.ptr != value.data() + value.size())
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    floor = parsed;
+    return ErrorCode::OK;
+}
+
+ErrorCode OpLogBatchStorage::ClaimProducerView(
+    ViewVersionId producer_view_version) {
+    if (!IsValidClusterId() || producer_view_version <= 0 ||
+        !backend_.SupportsTxn()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    const std::string key = BuildProducerViewKey(cluster_id_);
+    const std::string requested_value = std::to_string(producer_view_version);
+    while (true) {
+        std::string current_value;
+        ErrorCode err = backend_.Get(key, current_value);
+        if (err != ErrorCode::OK && err != ErrorCode::ETCD_KEY_NOT_EXIST) {
+            return err;
+        }
+
+        const bool key_missing = err == ErrorCode::ETCD_KEY_NOT_EXIST;
+        if (!key_missing) {
+            ViewVersionId current_view = 0;
+            if (!TryParseProducerView(current_value, current_view)) {
+                LOG(ERROR) << "Invalid producer view value while claiming: "
+                           << "cluster=" << cluster_id_;
+                return ErrorCode::INTERNAL_ERROR;
+            }
+            if (current_view > producer_view_version) {
+                LOG(WARNING)
+                    << "Producer view claim fenced: cluster=" << cluster_id_
+                    << ", requested=" << producer_view_version
+                    << ", current=" << current_view;
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+            if (current_view == producer_view_version) {
+                return ErrorCode::OK;
+            }
+        }
+
+        KvTxn txn;
+        txn.compares.push_back(
+            {.key = key,
+             .kind = key_missing ? KvCompareKind::kKeyNotExists
+                                 : KvCompareKind::kValueEquals,
+             .expected_value = key_missing ? "" : current_value});
+        txn.puts.push_back({.key = key, .value = requested_value});
+        err = backend_.Txn(txn);
+        if (err == ErrorCode::OK) {
+            return ErrorCode::OK;
+        }
+        if (IsAmbiguousTxnError(err)) {
+            ViewVersionId current_view = 0;
+            ErrorCode read_err = ReadProducerView(current_view);
+            if (read_err == ErrorCode::OK) {
+                if (current_view == producer_view_version) {
+                    return ErrorCode::OK;
+                }
+                if (current_view > producer_view_version) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (read_err != ErrorCode::ETCD_KEY_NOT_EXIST &&
+                       !IsAmbiguousTxnError(read_err)) {
+                return read_err;
+            }
+            return err;
+        }
+        if (err != ErrorCode::ETCD_TRANSACTION_FAIL) {
+            return err;
+        }
+    }
+}
+
+ErrorCode OpLogBatchStorage::ValidateProducerView(
+    ViewVersionId producer_view_version) const {
+    if (!IsValidClusterId() || producer_view_version <= 0) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    ViewVersionId current_view = 0;
+    ErrorCode err = ReadProducerView(current_view);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    if (current_view != producer_view_version) {
+        LOG(WARNING) << "Producer view validation failed: cluster="
+                     << cluster_id_ << ", expected=" << producer_view_version
+                     << ", current=" << current_view;
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+    return ErrorCode::OK;
+}
+
 ErrorCode OpLogBatchStorage::ValidateDurablePrefixAtStartup(
     const DurablePrefix& prefix) {
     if ((prefix.batch_id == 0) != (prefix.last_seq == 0)) {
@@ -178,6 +323,22 @@ ErrorCode OpLogBatchStorage::ValidateDurablePrefixAtStartup(
 
 ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefix(
     const OpLogBatchRecord& batch, const DurablePrefix& expected_prefix) {
+    return WriteBatchAndAdvancePrefixImpl(batch, expected_prefix, nullptr);
+}
+
+ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefix(
+    const OpLogBatchRecord& batch, const DurablePrefix& expected_prefix,
+    ViewVersionId producer_view_version) {
+    if (producer_view_version <= 0) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    return WriteBatchAndAdvancePrefixImpl(batch, expected_prefix,
+                                          &producer_view_version);
+}
+
+ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefixImpl(
+    const OpLogBatchRecord& batch, const DurablePrefix& expected_prefix,
+    const ViewVersionId* producer_view_version) {
     if (!IsValidClusterId()) {
         return ErrorCode::INVALID_PARAMS;
     }
@@ -213,25 +374,57 @@ ErrorCode OpLogBatchStorage::WriteBatchAndAdvancePrefix(
         encoded_batch.size());
 #endif
     KvTxn txn;
+    if (producer_view_version != nullptr) {
+        txn.compares.push_back(
+            {.key = BuildProducerViewKey(cluster_id_),
+             .kind = KvCompareKind::kValueEquals,
+             .expected_value = std::to_string(*producer_view_version)});
+    }
+    const size_t durable_compare_index = txn.compares.size();
     txn.compares.push_back(
         {.key = durable_key,
          .kind = KvCompareKind::kValueEquals,
          .expected_value = EncodeDurablePrefix(expected_prefix)});
     txn.puts.push_back({.key = BuildBatchRecordKey(cluster_id_, batch.batch_id),
                         .value = encoded_batch});
-    txn.puts.push_back(
-        {.key = durable_key,
-         .value = EncodeDurablePrefix(
-             {.batch_id = batch.batch_id, .last_seq = batch.last_seq})});
+    txn.puts.push_back({.key = durable_key,
+                        .value = EncodeDurablePrefix({
+                            .batch_id = batch.batch_id,
+                            .last_seq = batch.last_seq,
+                        })});
     ErrorCode err = backend_.Txn(txn);
-    if (err != ErrorCode::ETCD_TRANSACTION_FAIL) {
+    if (err == ErrorCode::ETCD_TRANSACTION_FAIL) {
+        std::string raw_prefix;
+        DurablePrefix decoded_prefix;
+        if (backend_.Get(durable_key, raw_prefix) == ErrorCode::OK &&
+            raw_prefix != txn.compares[durable_compare_index].expected_value &&
+            DecodeDurablePrefix(raw_prefix, &decoded_prefix) &&
+            decoded_prefix == expected_prefix) {
+            txn.compares[durable_compare_index].expected_value = raw_prefix;
+            err = backend_.Txn(txn);
+        }
+    }
+    if (err != ErrorCode::ETCD_TRANSACTION_FAIL && !IsAmbiguousTxnError(err)) {
         return err;
     }
 
+    if (producer_view_version != nullptr) {
+        ViewVersionId current_view = 0;
+        ErrorCode view_err = ReadProducerView(current_view);
+        if (view_err == ErrorCode::ETCD_KEY_NOT_EXIST ||
+            (view_err == ErrorCode::OK &&
+             current_view != *producer_view_version)) {
+            return ErrorCode::ETCD_TRANSACTION_FAIL;
+        }
+        if (view_err != ErrorCode::OK) {
+            return view_err;
+        }
+    }
+
     DurablePrefix current_prefix;
     if (ReadDurablePrefix(current_prefix) != ErrorCode::OK ||
-        current_prefix.batch_id != batch.batch_id ||
-        current_prefix.last_seq != batch.last_seq) {
+        current_prefix != DurablePrefix{.batch_id = batch.batch_id,
+                                        .last_seq = batch.last_seq}) {
         return err;
     }
     OpLogBatchRecord current_batch;
@@ -310,6 +503,17 @@ ErrorCode OpLogBatchStorage::ReadBatchesAfter(
     return ErrorCode::OK;
 }
 
+ErrorCode OpLogBatchStorage::DeleteBatchesThrough(uint64_t batch_id) {
+    if (!IsValidClusterId()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    // The suffix range starts immediately after the inclusive cutoff, and
+    // already handles UINT64_MAX without overflowing the batch ID.
+    const auto suffix = BuildBatchRecordRange(cluster_id_, batch_id);
+    return backend_.DeleteRange(BuildBatchRecordKey(cluster_id_, 0),
+                                suffix.begin_key);
+}
+
 bool OpLogBatchStorage::IsValidClusterId() const { return cluster_id_valid_; }
 
 ErrorCode OpLogBatchStorage::RejectLegacyLayout() const {
@@ -342,17 +546,26 @@ ErrorCode OpLogBatchStorage::RejectLegacyLayout() const {
     }
 
     entries.clear();
-    err = backend_.Range(root + "snapshot/", root + "snapshot0",
-                         /*limit=*/1, entries);
+    const std::string snapshot_prefix = root + "snapshot/";
+    constexpr std::array<std::string_view, 4> kBatchSnapshotControlKeys{
+        "latest", "fallback", "maintenance", "compaction_floor"};
+    err = backend_.Range(snapshot_prefix, root + "snapshot0",
+                         kBatchSnapshotControlKeys.size() + 1, entries);
     if (err != ErrorCode::OK) {
         return err;
     }
-    if (!entries.empty()) {
-        LOG(ERROR) << "Legacy OpLog snapshot sidecar exists for cluster="
-                   << cluster_id_
-                   << "; clear the legacy OpLog namespace before enabling "
-                      "batch-record OpLog";
-        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    for (const auto& entry : entries) {
+        const std::string_view key(entry.key);
+        const std::string_view suffix = key.substr(snapshot_prefix.size());
+        if (std::find(kBatchSnapshotControlKeys.begin(),
+                      kBatchSnapshotControlKeys.end(),
+                      suffix) == kBatchSnapshotControlKeys.end()) {
+            LOG(ERROR) << "Legacy OpLog snapshot sidecar exists for cluster="
+                       << cluster_id_
+                       << "; clear the legacy OpLog namespace before enabling "
+                          "batch-record OpLog";
+            return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+        }
     }
     return ErrorCode::OK;
 }
diff --git a/mooncake-store/src/ha/oplog/oplog_batch_types.cpp b/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
index 2e91730d31..f621ceb92a 100644
--- a/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
+++ b/mooncake-store/src/ha/oplog/oplog_batch_types.cpp
@@ -130,6 +130,14 @@ std::string BuildDurablePrefixKey(const std::string& cluster_id) {
     return "/oplog/" + normalized + "/durable_prefix";
 }
 
+std::string BuildProducerViewKey(const std::string& cluster_id) {
+    std::string normalized = cluster_id;
+    if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
+        return {};
+    }
+    return "/oplog/" + normalized + "/producer_view";
+}
+
 BatchRecordRange BuildBatchRecordRange(const std::string& cluster_id,
                                        uint64_t after_batch_id) {
     std::string normalized = cluster_id;
diff --git a/mooncake-store/src/ha/oplog/ordered_oplog_writer.cpp b/mooncake-store/src/ha/oplog/ordered_oplog_writer.cpp
index 43807a4703..61de6db236 100644
--- a/mooncake-store/src/ha/oplog/ordered_oplog_writer.cpp
+++ b/mooncake-store/src/ha/oplog/ordered_oplog_writer.cpp
@@ -4,20 +4,24 @@
 #include <chrono>
 #include <condition_variable>
 #include <deque>
+#include <map>
 #include <mutex>
 #include <thread>
 #include <unordered_set>
 #include <utility>
 #include <vector>
 
+#include <async_simple/Promise.h>
+
 #include "ha/oplog/oplog_test_failpoint.h"
-#ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
 #include "ha_metric_manager.h"
-#endif
 
 namespace mooncake {
 
 struct OrderedOpLogWriter::Impl {
+    using DurableWaiters =
+        std::multimap<uint64_t, async_simple::Promise<ErrorCode>>;
+
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
     using Clock = std::chrono::steady_clock;
 #endif
@@ -31,8 +35,11 @@ struct OrderedOpLogWriter::Impl {
 #endif
     };
 
-    explicit Impl(OrderedOpLogWriterConfig config, WriteBatchFn write_batch)
-        : config(std::move(config)), write_batch(std::move(write_batch)) {
+    explicit Impl(OrderedOpLogWriterConfig config, WriteBatchFn write_batch,
+                  TerminalCallback terminal_callback)
+        : config(std::move(config)),
+          write_batch(std::move(write_batch)),
+          terminal_callback(std::move(terminal_callback)) {
         if (this->config.max_entries_per_batch == 0) {
             this->config.max_entries_per_batch = 1;
         }
@@ -45,6 +52,30 @@ struct OrderedOpLogWriter::Impl {
         next_sequence_id = this->config.initial_durable_prefix.last_seq + 1;
     }
 
+    void PublishRuntime(bool activate = false) {
+        if (!activate && runtime_owner == 0) return;
+        HAMetricManager::WriterRuntimeSnapshot snapshot;
+        snapshot.accepting = accepting;
+        snapshot.retry_count = retry_count;
+        snapshot.retry_delay_ms = retry_delay_ms;
+        snapshot.waiting_slots = open_waiting_slots;
+        snapshot.committed_queue_depth =
+            committed_entries.size() + ready_entries.size();
+        snapshot.callback_queue_depth = callback_entries.size();
+        snapshot.durable_batch_id = durable_prefix.batch_id;
+        snapshot.durable_sequence = durable_prefix.last_seq;
+        snapshot.last_error = static_cast<int64_t>(last_error);
+        snapshot.terminal_reason = terminal_reason;
+        snapshot.stuck_range = stuck_range;
+        if (activate) {
+            runtime_owner =
+                HAMetricManager::instance().activate_writer_runtime(snapshot);
+        } else {
+            HAMetricManager::instance().update_writer_runtime(runtime_owner,
+                                                              snapshot);
+        }
+    }
+
     void SealCommittedEntriesIfIdle() {
         if (batch_busy || committed_entries.empty()) {
             return;
@@ -64,8 +95,69 @@ struct OrderedOpLogWriter::Impl {
         batch_busy = true;
     }
 
+    // Called with mutex held. Extracting nodes avoids allocating while
+    // advancing the prefix and leaves later waiters untouched.
+    DurableWaiters TakeCoveredWaiters() {
+        DurableWaiters covered;
+        auto end = durable_waiters.upper_bound(durable_prefix.last_seq);
+        for (auto it = durable_waiters.begin(); it != end;) {
+            auto current = it++;
+            covered.insert(durable_waiters.extract(current));
+        }
+        return covered;
+    }
+
+    // A continuation may run inline and reenter the writer, so never call
+    // this while holding mutex.
+    static void CompleteWaiters(DurableWaiters waiters, ErrorCode error) {
+        for (auto& waiter : waiters) {
+            waiter.second.setValue(ErrorCode{error});
+        }
+    }
+
+    void EnterTerminalState(ErrorCode error,
+                            OrderedOpLogWriterTerminalReason reason) {
+        TerminalCallback callback;
+        std::optional<OrderedOpLogWriterTerminalState> state;
+        DurableWaiters waiters;
+        {
+            std::lock_guard<std::mutex> lock(mutex);
+            if (stop_requested || terminal_state.has_value()) {
+                return;
+            }
+            terminal_state = {
+                .error = error,
+                .reason = reason,
+                .durable_prefix = durable_prefix,
+                .occurred_at_ms = static_cast<uint64_t>(
+                    std::chrono::duration_cast<std::chrono::milliseconds>(
+                        std::chrono::system_clock::now().time_since_epoch())
+                        .count())};
+            accepting = false;
+            last_error = error;
+            retry_delay_ms = 0;
+            terminal_reason =
+                reason == OrderedOpLogWriterTerminalReason::kRetryTimeout
+                    ? "retry_timeout"
+                : reason == OrderedOpLogWriterTerminalReason::kFenced
+                    ? "fenced"
+                    : "non_retryable_write_error";
+            PublishRuntime();
+            callback = terminal_callback;
+            state = terminal_state;
+            waiters.swap(durable_waiters);
+        }
+        cv.notify_all();
+        CompleteWaiters(std::move(waiters), error);
+        if (callback) {
+            callback(*state);
+        }
+    }
+
     OrderedOpLogWriterConfig config;
     WriteBatchFn write_batch;
+    TerminalCallback terminal_callback;
+    std::optional<OrderedOpLogWriterTerminalState> terminal_state;
     mutable std::mutex mutex;
     std::condition_variable cv;
     bool accepting{true};
@@ -73,9 +165,15 @@ struct OrderedOpLogWriter::Impl {
     bool stop_requested{false};
     bool callback_stop_requested{false};
     ErrorCode last_error{ErrorCode::OK};
+    uint64_t retry_count{0};
+    uint64_t runtime_owner{0};
+    uint64_t retry_delay_ms{0};
+    std::string terminal_reason;
+    std::optional<std::pair<uint64_t, uint64_t>> stuck_range;
     uint64_t next_reservation_id{1};
     uint64_t next_sequence_id{1};
     DurablePrefix durable_prefix{config.initial_durable_prefix};
+    DurableWaiters durable_waiters;
     size_t open_waiting_slots{0};
     std::unordered_set<uint64_t> active_reservations;
     std::deque<PendingEntry> committed_entries;
@@ -86,6 +184,16 @@ struct OrderedOpLogWriter::Impl {
     std::thread callback_thread;
 };
 
+namespace {
+
+bool IsRetryableWriteError(ErrorCode error) {
+    return error == ErrorCode::ETCD_OPERATION_ERROR ||
+           error == ErrorCode::ETCD_CTX_CANCELLED ||
+           error == ErrorCode::PERSISTENT_FAIL;
+}
+
+}  // namespace
+
 OrderedOpLogWriter::Reservation::Reservation() = default;
 
 OrderedOpLogWriter::Reservation::Reservation(OrderedOpLogWriter* writer,
@@ -128,8 +236,14 @@ uint64_t OrderedOpLogWriter::PendingHandle::sequence_id() const {
 }
 
 OrderedOpLogWriter::OrderedOpLogWriter(OrderedOpLogWriterConfig config,
-                                       WriteBatchFn write_batch)
-    : impl_(std::make_unique<Impl>(std::move(config), std::move(write_batch))) {
+                                       WriteBatchFn write_batch,
+                                       TerminalCallback terminal_callback)
+    : impl_(std::make_unique<Impl>(std::move(config), std::move(write_batch),
+                                   std::move(terminal_callback))) {}
+
+void OrderedOpLogWriter::ActivateRuntimeMetrics() {
+    std::lock_guard<std::mutex> lock(impl_->mutex);
+    if (impl_->runtime_owner == 0) impl_->PublishRuntime(true);
 }
 
 OrderedOpLogWriter::~OrderedOpLogWriter() { Stop(); }
@@ -137,6 +251,9 @@ OrderedOpLogWriter::~OrderedOpLogWriter() { Stop(); }
 tl::expected<OrderedOpLogWriter::Reservation, ErrorCode>
 OrderedOpLogWriter::Reserve() {
     std::lock_guard<std::mutex> lock(impl_->mutex);
+    if (impl_->terminal_state.has_value()) {
+        return tl::make_unexpected(impl_->terminal_state->error);
+    }
     if (!impl_->accepting) {
         return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
@@ -146,6 +263,7 @@ OrderedOpLogWriter::Reserve() {
     const uint64_t id = impl_->next_reservation_id++;
     impl_->active_reservations.insert(id);
     ++impl_->open_waiting_slots;
+    impl_->PublishRuntime();
     return Reservation(this, id);
 }
 
@@ -157,18 +275,23 @@ OrderedOpLogWriter::Commit(Reservation&& reservation, OpLogEntry entry,
         impl_->active_reservations.erase(reservation.id_) == 0) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    if (impl_->stop_requested) {
+    auto reject_reservation =
+        [&](ErrorCode error) -> tl::expected<PendingHandle, ErrorCode> {
         --impl_->open_waiting_slots;
         reservation.writer_ = nullptr;
         reservation.id_ = 0;
-        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        impl_->PublishRuntime();
+        return tl::make_unexpected(error);
+    };
+    if (impl_->terminal_state.has_value()) {
+        return reject_reservation(impl_->terminal_state->error);
+    }
+    if (impl_->stop_requested) {
+        return reject_reservation(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
     std::string reason;
     if (!ValidateOpLogBatchEntry(entry, &reason)) {
-        --impl_->open_waiting_slots;
-        reservation.writer_ = nullptr;
-        reservation.id_ = 0;
-        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        return reject_reservation(ErrorCode::INVALID_PARAMS);
     }
     reservation.writer_ = nullptr;
     reservation.id_ = 0;
@@ -188,6 +311,7 @@ OrderedOpLogWriter::Commit(Reservation&& reservation, OpLogEntry entry,
         impl_->committed_entries.size() + impl_->ready_entries.size());
 #endif
     impl_->SealCommittedEntriesIfIdle();
+    impl_->PublishRuntime();
     impl_->cv.notify_all();
     return PendingHandle(sequence_id);
 }
@@ -200,6 +324,27 @@ void OrderedOpLogWriter::Abort(Reservation&& reservation) {
     }
     reservation.writer_ = nullptr;
     reservation.id_ = 0;
+    impl_->PublishRuntime();
+}
+
+async_simple::Future<ErrorCode> OrderedOpLogWriter::AwaitDurable(
+    uint64_t sequence) {
+    std::lock_guard<std::mutex> lock(impl_->mutex);
+    if (impl_->durable_prefix.last_seq >= sequence) {
+        return async_simple::makeReadyFuture<ErrorCode>(ErrorCode::OK);
+    }
+    if (impl_->terminal_state.has_value()) {
+        return async_simple::makeReadyFuture<ErrorCode>(
+            ErrorCode{impl_->terminal_state->error});
+    }
+    if (impl_->stop_requested) {
+        return async_simple::makeReadyFuture<ErrorCode>(
+            ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    async_simple::Promise<ErrorCode> promise;
+    auto future = promise.getFuture();
+    impl_->durable_waiters.emplace(sequence, std::move(promise));
+    return future;
 }
 
 bool OrderedOpLogWriter::IsAccepting() const {
@@ -212,6 +357,26 @@ ErrorCode OrderedOpLogWriter::LastError() const {
     return impl_->last_error;
 }
 
+std::optional<OrderedOpLogWriterTerminalState>
+OrderedOpLogWriter::GetTerminalState() const {
+    std::lock_guard<std::mutex> lock(impl_->mutex);
+    return impl_->terminal_state;
+}
+
+void OrderedOpLogWriter::SetTerminalCallback(TerminalCallback callback) {
+    std::optional<OrderedOpLogWriterTerminalState> terminal;
+    TerminalCallback notify;
+    {
+        std::lock_guard<std::mutex> lock(impl_->mutex);
+        impl_->terminal_callback = std::move(callback);
+        notify = impl_->terminal_callback;
+        terminal = impl_->terminal_state;
+    }
+    if (terminal && notify) {
+        notify(*terminal);
+    }
+}
+
 void OrderedOpLogWriter::Start() {
     std::lock_guard<std::mutex> lock(impl_->mutex);
     if (impl_->running || impl_->stop_requested) {
@@ -239,6 +404,7 @@ void OrderedOpLogWriter::Start() {
                     .set_batch_record_callback_queue_depth(
                         impl_->callback_entries.size());
 #endif
+                impl_->PublishRuntime();
             }
             if (callback_entry.callback) {
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
@@ -275,6 +441,10 @@ void OrderedOpLogWriter::Start() {
                         impl_->committed_entries.size());
 #endif
                 expected_prefix = impl_->durable_prefix;
+                impl_->stuck_range =
+                    std::make_pair(expected_prefix.last_seq + 1,
+                                   expected_prefix.last_seq + entries.size());
+                impl_->PublishRuntime();
             }
 
             OpLogBatchRecord batch;
@@ -289,9 +459,31 @@ void OrderedOpLogWriter::Start() {
             constexpr auto kInitialRetryDelay = std::chrono::milliseconds(1);
             constexpr auto kMaxRetryDelay = std::chrono::milliseconds(1000);
             auto retry_delay = kInitialRetryDelay;
+            std::optional<std::chrono::steady_clock::time_point> retry_deadline;
+            bool retry_attempt = false;
 
             while (true) {
                 TestFailPoint::Wait("batch_before_txn");
+                if (retry_attempt) {
+                    std::optional<ErrorCode> timeout_error;
+                    {
+                        std::lock_guard<std::mutex> lock(impl_->mutex);
+                        if (impl_->stop_requested) {
+                            return;
+                        }
+                        if (retry_deadline.has_value() &&
+                            std::chrono::steady_clock::now() >=
+                                *retry_deadline) {
+                            timeout_error = impl_->last_error;
+                        }
+                    }
+                    if (timeout_error.has_value()) {
+                        impl_->EnterTerminalState(
+                            *timeout_error,
+                            OrderedOpLogWriterTerminalReason::kRetryTimeout);
+                        return;
+                    }
+                }
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
                 const auto txn_started_at = Impl::Clock::now();
 #endif
@@ -305,6 +497,7 @@ void OrderedOpLogWriter::Start() {
                     txn_latency_us);
 #endif
                 if (err == ErrorCode::OK) {
+                    Impl::DurableWaiters waiters;
                     TestFailPoint::Wait("batch_txn_succeeded_before_callback");
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
                     const auto durable_at = Impl::Clock::now();
@@ -321,8 +514,11 @@ void OrderedOpLogWriter::Start() {
                         std::lock_guard<std::mutex> lock(impl_->mutex);
                         impl_->durable_prefix = {.batch_id = batch.batch_id,
                                                  .last_seq = batch.last_seq};
+                        waiters = impl_->TakeCoveredWaiters();
                         impl_->last_error = ErrorCode::OK;
                         impl_->accepting = !impl_->stop_requested;
+                        impl_->retry_delay_ms = 0;
+                        impl_->stuck_range.reset();
                         for (size_t i = 0; i < entries.size(); ++i) {
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
                             entries[i].durable_at = durable_at;
@@ -346,18 +542,40 @@ void OrderedOpLogWriter::Start() {
 #endif
                         impl_->batch_busy = false;
                         impl_->SealCommittedEntriesIfIdle();
+                        impl_->PublishRuntime();
                     }
                     impl_->cv.notify_all();
+                    Impl::CompleteWaiters(std::move(waiters), ErrorCode::OK);
                     break;
                 }
 
+                if (!IsRetryableWriteError(err)) {
+                    const auto reason =
+                        err == ErrorCode::ETCD_TRANSACTION_FAIL
+                            ? OrderedOpLogWriterTerminalReason::kFenced
+                            : OrderedOpLogWriterTerminalReason::
+                                  kNonRetryableWriteError;
+                    impl_->EnterTerminalState(err, reason);
+                    return;
+                }
                 {
                     std::unique_lock<std::mutex> lock(impl_->mutex);
+                    if (impl_->stop_requested) {
+                        return;
+                    }
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
                     HAMetricManager::instance().inc_batch_record_retries();
 #endif
+                    ++impl_->retry_count;
                     impl_->last_error = err;
                     impl_->accepting = false;
+                    impl_->retry_delay_ms = retry_delay.count();
+                    impl_->PublishRuntime();
+                    if (!retry_deadline.has_value() &&
+                        impl_->config.retry_timeout.count() > 0) {
+                        retry_deadline = std::chrono::steady_clock::now() +
+                                         impl_->config.retry_timeout;
+                    }
                     if (impl_->stop_requested ||
                         impl_->cv.wait_for(lock, retry_delay, [this] {
                             return impl_->stop_requested;
@@ -366,21 +584,33 @@ void OrderedOpLogWriter::Start() {
                     }
                 }
                 retry_delay = std::min(retry_delay * 2, kMaxRetryDelay);
+                retry_attempt = true;
             }
         }
     });
 }
 
 void OrderedOpLogWriter::Stop() {
+    bool running;
+    Impl::DurableWaiters waiters;
+    ErrorCode waiter_error;
     {
         std::lock_guard<std::mutex> lock(impl_->mutex);
         impl_->accepting = false;
         impl_->stop_requested = true;
-        if (!impl_->running) {
-            return;
-        }
+        impl_->retry_delay_ms = 0;
+        impl_->PublishRuntime();
+        running = impl_->running;
+        waiters.swap(impl_->durable_waiters);
+        waiter_error = impl_->terminal_state.has_value()
+                           ? impl_->terminal_state->error
+                           : ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
     }
     impl_->cv.notify_all();
+    Impl::CompleteWaiters(std::move(waiters), waiter_error);
+    if (!running) {
+        return;
+    }
     if (impl_->writer_thread.joinable()) {
         impl_->writer_thread.join();
     }
diff --git a/mooncake-store/src/ha/snapshot/allocator_snapshot_codec.cpp b/mooncake-store/src/ha/snapshot/allocator_snapshot_codec.cpp
new file mode 100644
index 0000000000..f79640cf5e
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/allocator_snapshot_codec.cpp
@@ -0,0 +1,97 @@
+#include "ha/snapshot/allocator_snapshot_codec.h"
+
+#include <fmt/format.h>
+
+#include <exception>
+
+namespace mooncake::ha {
+
+tl::expected<void, SerializationError> AllocatorSnapshotCodec::Encode(
+    const OffsetBufferAllocatorSnapshot& snapshot, MsgpackPacker& packer) {
+    if (!snapshot.allocation_state.layout) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::SERIALIZE_FAIL, "snapshot allocator has no layout"));
+    }
+    // Preserve the legacy OffsetBufferAllocator and OffsetAllocator arrays.
+    packer.pack_array(6);
+    packer.pack(snapshot.segment_name);
+    packer.pack(static_cast<uint64_t>(snapshot.base));
+    packer.pack(static_cast<uint64_t>(snapshot.capacity));
+    packer.pack(static_cast<uint64_t>(snapshot.used_bytes));
+    packer.pack(snapshot.transport_endpoint);
+    const auto& layout = snapshot.allocation_state;
+    packer.pack_array(6);
+    packer.pack(layout.base);
+    packer.pack(layout.multiplier_bits);
+    packer.pack(layout.capacity);
+    packer.pack(layout.allocated_size);
+    packer.pack(layout.allocated_num);
+    return Serializer<offset_allocator::__Allocator>::serialize(*layout.layout,
+                                                                packer);
+}
+
+tl::expected<OffsetBufferAllocatorSnapshot, SerializationError>
+AllocatorSnapshotCodec::Decode(const msgpack::object& object) {
+    if (object.type != msgpack::type::ARRAY || object.via.array.size != 6) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            "snapshot OffsetBufferAllocator is not an array[6]"));
+    }
+
+    try {
+        const auto* array = object.via.array.ptr;
+        std::string segment_name = array[0].as<std::string>();
+        auto base = static_cast<size_t>(array[1].as<uint64_t>());
+        auto total_size = static_cast<size_t>(array[2].as<uint64_t>());
+        auto used_bytes = static_cast<size_t>(array[3].as<uint64_t>());
+        std::string transport_endpoint = array[4].as<std::string>();
+
+        if (array[5].type != msgpack::type::ARRAY ||
+            array[5].via.array.size != 6) {
+            return tl::make_unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                "snapshot OffsetAllocator is not an array[6]"));
+        }
+        const auto* state = array[5].via.array.ptr;
+        auto layout =
+            Serializer<offset_allocator::__Allocator>::deserialize(state[5]);
+        if (!layout) {
+            return tl::make_unexpected(layout.error());
+        }
+
+        OffsetBufferAllocatorSnapshot snapshot{
+            .segment_name = std::move(segment_name),
+            .base = base,
+            .capacity = total_size,
+            .used_bytes = used_bytes,
+            .transport_endpoint = std::move(transport_endpoint),
+            .allocation_state =
+                offset_allocator::OffsetAllocatorSnapshot{
+                    .base = state[0].as<uint64_t>(),
+                    .multiplier_bits = state[1].as<uint64_t>(),
+                    .capacity = state[2].as<uint64_t>(),
+                    .allocated_size = state[3].as<uint64_t>(),
+                    .allocated_num = state[4].as<uint64_t>(),
+                    .layout = std::move(*layout),
+                },
+        };
+        // The snapshot owns both the outer metadata and the inner layout, so
+        // one validation pass covers the bounds/base/usage consistency and the
+        // allocator topology. Decode propagates diagnostics to its caller;
+        // direct restore factories also log validation failures.
+        if (auto valid = snapshot.Validate(); !valid) {
+            return tl::make_unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                fmt::format("snapshot OffsetBufferAllocator {}",
+                            valid.error())));
+        }
+        return snapshot;
+    } catch (const std::exception& error) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            fmt::format("decode OffsetBufferAllocator failed: {}",
+                        error.what())));
+    }
+}
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.cpp
new file mode 100644
index 0000000000..7d266c90c3
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.cpp
@@ -0,0 +1,195 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h"
+
+#include <algorithm>
+#include <charconv>
+#include <utility>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+
+#include "ha_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+bool InspectArtifact(SnapshotObjectStore& store, const std::string& key,
+                     uint64_t size, uint32_t crc) {
+    const auto inspection = store.InspectObject(key);
+    // A successful inspection with no checksum means the backend does not
+    // supply one. N03's full pre-publication readback remains the content
+    // evidence; do not download all chunks again here. Unknown metadata is an
+    // inspection error and fails closed.
+    return size != 0 && inspection && inspection->stored_size == size &&
+           (!inspection->crc32c || *inspection->crc32c == crc);
+}
+
+bool ValidateSnapshot(SnapshotObjectStore& store, const std::string& root,
+                      const std::string& pointer,
+                      const ha::BatchOpLogSnapshotDescriptor& descriptor,
+                      const std::function<bool()>& cancelled) {
+    if (descriptor.manifest_key !=
+        ha::BuildBatchOpLogSnapshotManifestKey(root, descriptor.snapshot_id))
+        return false;
+    std::string bytes;
+    const auto descriptor_key =
+        ha::BuildBatchOpLogSnapshotDescriptorKey(root, descriptor.snapshot_id);
+    if (descriptor_key.empty() ||
+        !store.DownloadString(descriptor_key, bytes) || bytes != pointer)
+        return false;
+    if (!store.DownloadString(descriptor.manifest_key, bytes) ||
+        bytes.size() != descriptor.manifest_size ||
+        Crc32cValue(bytes.data(), bytes.size()) != descriptor.manifest_crc32c)
+        return false;
+    const auto manifest = ha::DecodeBatchOpLogSnapshotManifest(bytes);
+    if (!manifest || manifest->schema_version != descriptor.schema_version ||
+        manifest->snapshot_format != descriptor.snapshot_format ||
+        manifest->snapshot_id != descriptor.snapshot_id ||
+        manifest->last_included_batch_id != descriptor.last_included_batch_id ||
+        manifest->last_included_seq != descriptor.last_included_seq ||
+        manifest->producer_view_version != descriptor.producer_view_version ||
+        manifest->segments.key != ha::BuildBatchOpLogSnapshotSegmentsKey(
+                                      root, descriptor.snapshot_id) ||
+        !InspectArtifact(store, manifest->segments.key,
+                         manifest->segments.stored_size,
+                         manifest->segments.crc32c))
+        return false;
+    for (size_t i = 0; i < manifest->object_chunks.size(); ++i) {
+        if (cancelled()) return false;
+        const auto& chunk = manifest->object_chunks[i];
+        if (chunk.chunk_index != i ||
+            chunk.key != ha::BuildBatchOpLogSnapshotObjectChunkKey(
+                             root, descriptor.snapshot_id, i) ||
+            !InspectArtifact(store, chunk.key, chunk.stored_size, chunk.crc32c))
+            return false;
+    }
+    return true;
+}
+
+}  // namespace
+
+BatchOpLogPruningCoordinator::BatchOpLogPruningCoordinator(
+    HaKvBackend& backend, SnapshotObjectStore& object_store,
+    std::string cluster_id, std::string snapshot_root)
+    : backend_(backend),
+      object_store_(object_store),
+      cluster_id_(std::move(cluster_id)),
+      snapshot_root_(std::move(snapshot_root)) {}
+
+ErrorCode BatchOpLogPruningCoordinator::Run(
+    const SnapshotMaintenanceLease& lease,
+    const std::function<bool()>& cancelled) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Prune);
+    const auto latest_key = ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_);
+    const auto fallback_key =
+        ha::BuildBatchOpLogSnapshotFallbackKey(cluster_id_);
+    const auto floor_key =
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey(cluster_id_);
+    const auto lock_key =
+        ha::BuildBatchOpLogSnapshotMaintenanceKey(cluster_id_);
+    if (latest_key.empty() || snapshot_root_.empty() ||
+        lease.lock_key() != lock_key || !backend_.SupportsTxn())
+        return ErrorCode::INVALID_PARAMS;
+    const auto stopped = [&] {
+        return !lease.IsHeld() || (cancelled && cancelled());
+    };
+    if (stopped()) return ErrorCode::ETCD_TRANSACTION_FAIL;
+
+    HAMetricManager::instance().update_snapshot_runtime(
+        [](auto& metrics) { metrics.candidate_floor = 0; });
+    std::string latest, fallback, old_floor;
+    auto error = backend_.Get(latest_key, latest);
+    if (error != ErrorCode::OK) return error;
+    error = backend_.Get(fallback_key, fallback);
+    // The first publication has no redundant recovery baseline yet.
+    if (error == ErrorCode::ETCD_KEY_NOT_EXIST) {
+        HAMetricManager::instance().record_snapshot_skip(
+            HAMetricManager::SnapshotSkipReason::NoFallback);
+        return metric_timer.Success(ErrorCode::OK);
+    }
+    if (error != ErrorCode::OK) return error;
+    const auto latest_descriptor =
+        ha::DecodeBatchOpLogSnapshotDescriptor(latest);
+    const auto fallback_descriptor =
+        ha::DecodeBatchOpLogSnapshotDescriptor(fallback);
+    if (!latest_descriptor || !fallback_descriptor)
+        return ErrorCode::INTERNAL_ERROR;
+    const uint64_t candidate = fallback_descriptor->last_included_batch_id;
+    if (latest_descriptor->snapshot_id == fallback_descriptor->snapshot_id ||
+        latest_descriptor->last_included_batch_id <= candidate) {
+        HAMetricManager::instance().record_snapshot_skip(
+            HAMetricManager::SnapshotSkipReason::InvalidPair);
+        return metric_timer.Success(ErrorCode::OK);
+    }
+
+    HAMetricManager::instance().update_snapshot_runtime(
+        [&](auto& metrics) { metrics.candidate_floor = candidate; });
+    uint64_t floor = 0;
+    error = backend_.Get(floor_key, old_floor);
+    const bool floor_exists = error == ErrorCode::OK;
+    if (!floor_exists && error != ErrorCode::ETCD_KEY_NOT_EXIST) return error;
+    if (floor_exists) {
+        const auto parsed = std::from_chars(
+            old_floor.data(), old_floor.data() + old_floor.size(), floor);
+        if (parsed.ec != std::errc() ||
+            parsed.ptr != old_floor.data() + old_floor.size())
+            return ErrorCode::INTERNAL_ERROR;
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.compaction_floor =
+                std::max(metrics.compaction_floor, floor);
+        });
+        if (candidate < floor) {
+            HAMetricManager::instance().record_snapshot_skip(
+                HAMetricManager::SnapshotSkipReason::FloorAhead);
+            return metric_timer.Success(ErrorCode::OK);
+        }
+    }
+
+    if (!ValidateSnapshot(object_store_, snapshot_root_, latest,
+                          *latest_descriptor, stopped) ||
+        !ValidateSnapshot(object_store_, snapshot_root_, fallback,
+                          *fallback_descriptor, stopped))
+        return ErrorCode::INTERNAL_ERROR;
+    if (stopped()) return ErrorCode::ETCD_TRANSACTION_FAIL;
+
+    KvTxn txn;
+    txn.compares = {{.key = lock_key,
+                     .kind = KvCompareKind::kValueEquals,
+                     .expected_value = lease.owner_token()},
+                    {.key = lock_key,
+                     .kind = KvCompareKind::kCreateRevisionEquals,
+                     .expected_value = "",
+                     .expected_revision = lease.lock_create_revision()},
+                    {.key = latest_key,
+                     .kind = KvCompareKind::kValueEquals,
+                     .expected_value = latest},
+                    {.key = fallback_key,
+                     .kind = KvCompareKind::kValueEquals,
+                     .expected_value = fallback},
+                    {.key = floor_key,
+                     .kind = floor_exists ? KvCompareKind::kValueEquals
+                                          : KvCompareKind::kKeyNotExists,
+                     .expected_value = old_floor}};
+    txn.puts.push_back({.key = floor_key, .value = std::to_string(candidate)});
+    error = backend_.Txn(txn);
+    if (error != ErrorCode::OK) return error;
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.compaction_floor =
+            std::max(metrics.compaction_floor, candidate);
+        metrics.floor_advances_total += candidate > floor;
+    });
+    // Even if the lease is lost now, this range has already been advertised to
+    // readers. A crash or failed delete leaves the floor in place; a later
+    // successful publication can safely repeat this bounded deletion.
+    if (stopped()) return metric_timer.Success(ErrorCode::OK);
+    const auto delete_error = OpLogBatchStorage(cluster_id_, backend_)
+                                  .DeleteBatchesThrough(candidate);
+    metric_timer.error = static_cast<int64_t>(delete_error);
+    return delete_error;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.cpp
new file mode 100644
index 0000000000..09c33a6e2e
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.cpp
@@ -0,0 +1,589 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h"
+
+#include <algorithm>
+#include <chrono>
+#include <exception>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/batch_oplog/writer.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "hot_standby_service.h"
+#include "ha_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+using Skip = HAMetricManager::SnapshotSkipReason;
+
+int64_t CurrentTimeMs() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+bool IsAtOrAfter(const DurablePrefix& current, const DurablePrefix& target) {
+    return !IsSequenceOlder(current.last_seq, target.last_seq) &&
+           current.batch_id >= target.batch_id;
+}
+
+}  // namespace
+
+BatchOpLogSnapshotCoordinator::BatchOpLogSnapshotCoordinator(
+    HotStandbyService& standby, HaKvBackend& backend,
+    SnapshotObjectStore& object_store, std::string cluster_id,
+    BatchOpLogSnapshotCoordinatorConfig config, LeaseFactory lease_factory)
+    : standby_(standby),
+      backend_(backend),
+      object_store_(object_store),
+      cluster_id_(std::move(cluster_id)),
+      config_(std::move(config)),
+      lease_factory_(std::move(lease_factory)) {
+    HAMetricManager::instance().reset_snapshot_runtime(true);
+    if (!config_.clock) {
+        config_.clock = [] { return Clock::now(); };
+    }
+    if (!lease_factory_) {
+        lease_factory_ = [this] {
+            return std::make_unique<SnapshotMaintenanceLease>(cluster_id_);
+        };
+    }
+    standby_.SetBatchOpLogSnapshotCaptureReleasedCallback(
+        [this] { OnCaptureReleased(); });
+    standby_.SetBatchOpLogSnapshotPromotionCallback(
+        [this] { NotifyPromotion(); });
+    standby_.SetBatchOpLogSnapshotStopCallback([this] { RequestStop(); });
+}
+
+BatchOpLogSnapshotCoordinator::BatchOpLogSnapshotCoordinator(
+    HotStandbyService& standby, HaKvBackend& backend,
+    SnapshotObjectStore& object_store, std::string cluster_id,
+    std::string snapshot_root, uint64_t snapshot_interval_seconds,
+    size_t chunk_object_count)
+    : BatchOpLogSnapshotCoordinator(
+          standby, backend, object_store, std::move(cluster_id),
+          BatchOpLogSnapshotCoordinatorConfig{
+              .snapshot_interval_seconds = snapshot_interval_seconds,
+              .chunk_object_count = chunk_object_count,
+              .snapshot_root = std::move(snapshot_root),
+              .clock = {}},
+          {}) {}
+
+BatchOpLogSnapshotCoordinator::~BatchOpLogSnapshotCoordinator() {
+    Stop();
+    standby_.SetBatchOpLogSnapshotCaptureReleasedCallback(nullptr);
+    standby_.SetBatchOpLogSnapshotPromotionCallback(nullptr);
+    standby_.SetBatchOpLogSnapshotStopCallback(nullptr);
+}
+
+void BatchOpLogSnapshotCoordinator::Start() {
+    std::thread stale_worker;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (running_) {
+            return;
+        }
+        stop_requested_ = true;
+        stale_worker = std::move(worker_);
+    }
+    cv_.notify_all();
+    if (stale_worker.joinable()) {
+        stale_worker.join();
+    }
+
+    std::lock_guard<std::mutex> lock(mutex_);
+    stop_requested_ = false;
+    promotion_requested_ = false;
+    running_ = true;
+    worker_ = std::thread(&BatchOpLogSnapshotCoordinator::SchedulerLoop, this);
+}
+
+void BatchOpLogSnapshotCoordinator::Stop() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        stop_requested_ = true;
+        running_ = false;
+    }
+    standby_.CancelBatchOpLogSnapshotCapture();
+    cv_.notify_all();
+    if (worker_.joinable()) {
+        worker_.join();
+    }
+    std::unique_lock<std::mutex> lock(mutex_);
+    cv_.wait(lock, [this] { return !attempt_in_flight_; });
+}
+
+void BatchOpLogSnapshotCoordinator::NotifyPromotion() {
+    bool cancel_capture = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        promotion_requested_ = true;
+        cancel_capture = capture_active_;
+    }
+    if (cancel_capture) {
+        standby_.CancelBatchOpLogSnapshotCapture();
+        std::unique_lock<std::mutex> lock(mutex_);
+        cv_.wait(lock, [this] { return !capture_active_; });
+    }
+    cv_.notify_all();
+}
+
+BatchOpLogSnapshotCoordinatorStatus BatchOpLogSnapshotCoordinator::GetStatus()
+    const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return {.running = running_,
+            .attempt_in_flight = attempt_in_flight_,
+            .promotion_requested = promotion_requested_,
+            .attempts = attempts_,
+            .last_error = last_error_,
+            .catch_up_target = catch_up_target_};
+}
+
+bool BatchOpLogSnapshotCoordinator::IsRunning() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return running_;
+}
+
+bool BatchOpLogSnapshotCoordinator::IsAttemptInFlight() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return attempt_in_flight_;
+}
+
+ErrorCode BatchOpLogSnapshotCoordinator::last_error() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return last_error_;
+}
+
+BatchOpLogSnapshotCoordinator::Clock::time_point
+BatchOpLogSnapshotCoordinator::Now() const {
+    return config_.clock ? config_.clock() : Clock::now();
+}
+
+void BatchOpLogSnapshotCoordinator::OnCaptureReleased() {
+    const auto prefix = ReadDurablePrefix();
+    std::lock_guard<std::mutex> lock(mutex_);
+    capture_active_ = false;
+    if (prefix) {
+        catch_up_target_ = *prefix;
+        if (capture_cursor_ && IsSequenceOlder(catch_up_target_->last_seq,
+                                               capture_cursor_->last_seq)) {
+            catch_up_target_ = *capture_cursor_;
+        }
+    } else if (capture_cursor_) {
+        catch_up_target_ = *capture_cursor_;
+    }
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.catch_up_target_batch =
+            catch_up_target_ ? catch_up_target_->batch_id : 0;
+        metrics.catch_up_target_sequence =
+            catch_up_target_ ? catch_up_target_->last_seq : 0;
+        if (prefix)
+            metrics.durable_batch =
+                std::max(metrics.durable_batch, prefix->batch_id);
+    });
+    cv_.notify_all();
+}
+
+std::optional<DurablePrefix> BatchOpLogSnapshotCoordinator::ReadDurablePrefix()
+    const {
+    OpLogBatchStorage storage(cluster_id_, backend_);
+    DurablePrefix prefix;
+    if (storage.ReadDurablePrefix(prefix) != ErrorCode::OK) {
+        return std::nullopt;
+    }
+    return prefix;
+}
+
+std::optional<uint64_t> BatchOpLogSnapshotCoordinator::ReadLatestBatchId(
+    ErrorCode& error) const {
+    error = ErrorCode::OK;
+    uint64_t published_batch_id = 0;
+    for (const auto& key :
+         {ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_),
+          ha::BuildBatchOpLogSnapshotFallbackKey(cluster_id_)}) {
+        std::string value;
+        const auto get_error = backend_.Get(key, value);
+        const bool latest =
+            key == ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_);
+        if (get_error == ErrorCode::ETCD_KEY_NOT_EXIST) {
+            HAMetricManager::instance().update_snapshot_runtime(
+                [&](auto& metrics) {
+                    (latest ? metrics.latest_created_at_ms
+                            : metrics.fallback_created_at_ms) = std::nullopt;
+                    (latest ? metrics.latest_batch : metrics.fallback_batch) =
+                        0;
+                });
+            continue;
+        }
+        if (get_error != ErrorCode::OK) {
+            error = get_error;
+            return std::nullopt;
+        }
+        auto descriptor = ha::DecodeBatchOpLogSnapshotDescriptor(value);
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            (latest ? metrics.latest_created_at_ms
+                    : metrics.fallback_created_at_ms) =
+                descriptor ? std::optional<int64_t>(descriptor->created_at_ms)
+                           : std::nullopt;
+            (latest ? metrics.latest_batch : metrics.fallback_batch) =
+                descriptor ? descriptor->last_included_batch_id : 0;
+        });
+        // Corrupt pointers are handled by the fenced publisher; they do not
+        // qualify a newer local cursor on their own.
+        if (descriptor) {
+            published_batch_id = std::max(published_batch_id,
+                                          descriptor->last_included_batch_id);
+        }
+    }
+    return published_batch_id;
+}
+
+bool BatchOpLogSnapshotCoordinator::CatchUpComplete(
+    const DurablePrefix& target) const {
+    const auto current = standby_.GetLastAppliedBatchOpLogSnapshotPrefix();
+    return current && IsAtOrAfter(*current, target);
+}
+
+void BatchOpLogSnapshotCoordinator::FinishAttempt(ErrorCode error,
+                                                  bool count_attempt) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (count_attempt) {
+        ++attempts_;
+        last_attempt_complete_ = Now();
+    }
+    last_error_ = error;
+    attempt_in_flight_ = false;
+    capture_active_ = false;
+    cv_.notify_all();
+}
+
+ErrorCode BatchOpLogSnapshotCoordinator::RunOnce() {
+    try {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (attempt_in_flight_) {
+                HAMetricManager::instance().record_snapshot_skip(
+                    Skip::InFlight);
+                return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+            }
+            if (stop_requested_) {
+                HAMetricManager::instance().record_snapshot_skip(Skip::Stopped);
+                return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+            }
+            if (last_attempt_complete_ &&
+                Now() - *last_attempt_complete_ <
+                    std::chrono::seconds(config_.snapshot_interval_seconds)) {
+                HAMetricManager::instance().record_snapshot_skip(
+                    Skip::Interval);
+                return ErrorCode::OK;
+            }
+            if (promotion_requested_) {
+                HAMetricManager::instance().record_snapshot_skip(
+                    Skip::Promotion);
+                return ErrorCode::OK;
+            }
+        }
+        HAMetricManager::instance().record_snapshot_skip(Skip::None);
+        HAMetricManager::SnapshotOperationTimer timer(
+            HAMetricManager::SnapshotOperation::Schedule);
+        const auto error = RunAttempt();
+        timer.error = static_cast<int64_t>(error);
+        return error;
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "Batch snapshot coordinator failed: " << e.what();
+        FinishAttempt(ErrorCode::INTERNAL_ERROR, false);
+        return ErrorCode::INTERNAL_ERROR;
+    } catch (...) {
+        LOG(ERROR) << "Batch snapshot coordinator failed with unknown error";
+        FinishAttempt(ErrorCode::INTERNAL_ERROR, false);
+        return ErrorCode::INTERNAL_ERROR;
+    }
+}
+
+ErrorCode BatchOpLogSnapshotCoordinator::RunAttempt() {
+    if (config_.snapshot_root.empty() || config_.chunk_object_count == 0 ||
+        !NormalizeAndValidateClusterId(cluster_id_) || cluster_id_.empty()) {
+        FinishAttempt(ErrorCode::INVALID_PARAMS, false);
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode read_error = ErrorCode::OK;
+    const auto latest_batch_id = ReadLatestBatchId(read_error);
+    if (!latest_batch_id) {
+        FinishAttempt(read_error, false);
+        return read_error;
+    }
+    const auto local_prefix = standby_.GetLastAppliedBatchOpLogSnapshotPrefix();
+    if (!local_prefix || local_prefix->batch_id <= *latest_batch_id) {
+        HAMetricManager::instance().record_snapshot_skip(Skip::NoNewBatch);
+        FinishAttempt(ErrorCode::OK, false);
+        return ErrorCode::OK;
+    }
+    bool catch_up_blocked = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (attempt_in_flight_) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+        catch_up_blocked = catch_up_target_.has_value();
+        attempt_in_flight_ = true;
+    }
+    if (catch_up_blocked) {
+        std::optional<DurablePrefix> target;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            target = catch_up_target_;
+        }
+        if (target && !CatchUpComplete(*target)) {
+            HAMetricManager::instance().record_snapshot_skip(Skip::CatchUp);
+            FinishAttempt(ErrorCode::OK, false);
+            return ErrorCode::OK;
+        }
+    }
+
+    auto lease = lease_factory_();
+    if (!lease) {
+        HAMetricManager::instance().record_snapshot_skip(Skip::LeaseBusy);
+        // A factory may return null to represent a busy maintenance lease.
+        FinishAttempt(ErrorCode::OK, false);
+        return ErrorCode::OK;
+    }
+    const ErrorCode lease_error =
+        lease->IsHeld() ? ErrorCode::OK : lease->Acquire();
+    if (lease_error != ErrorCode::OK) {
+        if (lease_error == ErrorCode::ETCD_TRANSACTION_FAIL)
+            HAMetricManager::instance().record_snapshot_skip(Skip::LeaseBusy);
+        // A busy maintenance lease is an ordinary skipped cycle.
+        const ErrorCode result = lease_error == ErrorCode::ETCD_TRANSACTION_FAIL
+                                     ? ErrorCode::OK
+                                     : lease_error;
+        FinishAttempt(result, false);
+        return result;
+    }
+
+    // Observe and release on every exit, before making the attempt idle.
+    const auto observe_lease_loss =
+        [](SnapshotMaintenanceLease* held) noexcept {
+            try {
+                if (!held->IsHeld()) {
+                    HAMetricManager::instance().update_snapshot_runtime(
+                        [](auto& metrics) { ++metrics.lease_lost_total; });
+                }
+            } catch (...) {
+                LOG(WARNING)
+                    << "Failed to observe snapshot maintenance lease state";
+            }
+            (void)held->Release();
+        };
+    std::unique_ptr<SnapshotMaintenanceLease, decltype(observe_lease_loss)>
+        lease_observer(lease.get(), observe_lease_loss);
+    bool cancel_before_capture = false;
+    bool promotion_before_capture = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        promotion_before_capture = promotion_requested_;
+        cancel_before_capture = stop_requested_ || promotion_before_capture;
+    }
+    if (cancel_before_capture) {
+        HAMetricManager::instance().record_snapshot_skip(
+            promotion_before_capture ? Skip::Promotion : Skip::Stopped);
+        lease_observer.reset();
+        FinishAttempt(ErrorCode::OK, true);
+        return ErrorCode::OK;
+    }
+
+    // Re-read both sides after fencing the maintenance lease.
+    const auto reread_latest = ReadLatestBatchId(read_error);
+    const auto reread_local = standby_.GetLastAppliedBatchOpLogSnapshotPrefix();
+    if (!reread_latest || !reread_local ||
+        reread_local->batch_id <= *reread_latest) {
+        if (read_error == ErrorCode::OK)
+            HAMetricManager::instance().record_snapshot_skip(Skip::NoNewBatch);
+        const ErrorCode result =
+            read_error == ErrorCode::OK ? ErrorCode::OK : read_error;
+        lease_observer.reset();
+        FinishAttempt(result, true);
+        return result;
+    }
+
+    auto capture = standby_.BeginBatchOpLogSnapshotCapture();
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        capture_active_ = capture.has_value();
+        if (capture && promotion_requested_) {
+            capture_active_ = false;
+        }
+    }
+    if (!capture || capture->last_included_batch_id <= *reread_latest) {
+        HAMetricManager::instance().record_snapshot_skip(
+            capture ? Skip::NoNewBatch : Skip::CaptureUnavailable);
+        lease_observer.reset();
+        FinishAttempt(ErrorCode::OK, true);
+        return ErrorCode::OK;
+    }
+
+    bool cancel_after_promotion = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        cancel_after_promotion = promotion_requested_;
+    }
+    if (cancel_after_promotion) {
+        HAMetricManager::instance().record_snapshot_skip(Skip::Promotion);
+        standby_.CancelBatchOpLogSnapshotCapture();
+        standby_.EndBatchOpLogSnapshotCapture(*capture);
+        lease_observer.reset();
+        FinishAttempt(ErrorCode::OK, true);
+        return ErrorCode::OK;
+    }
+
+    const std::string snapshot_id =
+        std::to_string(capture->last_included_batch_id) + "-" +
+        lease->owner_token();
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        capture_cursor_ =
+            DurablePrefix{.batch_id = capture->last_included_batch_id,
+                          .last_seq = capture->last_included_seq};
+    }
+    const std::string artifact_prefix =
+        ha::BuildBatchOpLogSnapshotArtifactPrefix(config_.snapshot_root,
+                                                  snapshot_id);
+
+    BatchOpLogSnapshotWriter writer(object_store_);
+    auto descriptor =
+        writer.Write(standby_, *capture, config_.snapshot_root, snapshot_id,
+                     config_.chunk_object_count, CurrentTimeMs());
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        capture_active_ = false;
+    }
+    if (!descriptor) {
+        lease_observer.reset();
+        FinishAttempt(ErrorCode::INTERNAL_ERROR, true);
+        return ErrorCode::INTERNAL_ERROR;
+    }
+
+    bool stop_before_publish = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        stop_before_publish = stop_requested_ && !promotion_requested_;
+    }
+    if (stop_before_publish) {
+        HAMetricManager::instance().record_snapshot_skip(Skip::Stopped);
+        auto cleanup = object_store_.DeleteObjectsWithPrefix(artifact_prefix);
+        if (!cleanup) {
+            LOG(WARNING) << "Failed to clean snapshot candidate after stop: "
+                         << cleanup.error();
+        }
+        lease_observer.reset();
+        FinishAttempt(ErrorCode::OK, true);
+        return ErrorCode::OK;
+    }
+
+    BatchOpLogSnapshotPublisher publisher(backend_, cluster_id_);
+    std::optional<std::string> expected_fallback;
+    ErrorCode publish_error;
+    {
+        HAMetricManager::SnapshotOperationTimer timer(
+            HAMetricManager::SnapshotOperation::Publish);
+        publish_error =
+            publisher.Publish(*lease, *descriptor, &expected_fallback);
+        timer.error = static_cast<int64_t>(publish_error);
+    }
+    if (publish_error != ErrorCode::OK) {
+        auto cleanup = object_store_.DeleteObjectsWithPrefix(artifact_prefix);
+        if (!cleanup) {
+            LOG(WARNING) << "Failed to clean unpublished snapshot candidate: "
+                         << cleanup.error();
+        }
+    }
+    if (publish_error == ErrorCode::OK) {
+        const auto latest = ha::DecodeBatchOpLogSnapshotDescriptor(*descriptor);
+        const auto fallback = ha::DecodeBatchOpLogSnapshotDescriptor(
+            expected_fallback.value_or(""));
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.latest_batch = latest ? latest->last_included_batch_id : 0;
+            metrics.fallback_batch =
+                fallback ? fallback->last_included_batch_id : 0;
+            metrics.latest_created_at_ms =
+                latest ? std::optional<int64_t>(latest->created_at_ms)
+                       : std::nullopt;
+            metrics.fallback_created_at_ms =
+                fallback ? std::optional<int64_t>(fallback->created_at_ms)
+                         : std::nullopt;
+        });
+        BatchOpLogSnapshotGc gc(backend_, object_store_, cluster_id_,
+                                config_.snapshot_root);
+        auto cancelled = [this] {
+            std::lock_guard<std::mutex> lock(mutex_);
+            return stop_requested_ || promotion_requested_;
+        };
+        try {
+            if (gc.Run(*lease, *descriptor, expected_fallback, cancelled) !=
+                ErrorCode::OK)
+                LOG(WARNING) << "Batch snapshot object GC skipped or failed";
+        } catch (const std::exception& e) {
+            LOG(WARNING) << "Batch snapshot object GC threw: " << e.what();
+        } catch (...) {
+            LOG(WARNING) << "Batch snapshot object GC threw unknown exception";
+        }
+        // GC is best-effort and must not prevent independently validated
+        // pruning, including when it throws. Keep the publication successful.
+        try {
+            BatchOpLogPruningCoordinator pruning(
+                backend_, object_store_, cluster_id_, config_.snapshot_root);
+            const auto error = pruning.Run(*lease, cancelled);
+            if (error != ErrorCode::OK)
+                LOG(WARNING) << "Batch OpLog pruning skipped or failed: "
+                             << static_cast<int>(error);
+        } catch (const std::exception& e) {
+            LOG(WARNING) << "Batch OpLog pruning threw: " << e.what();
+        } catch (...) {
+            LOG(WARNING) << "Batch OpLog pruning threw unknown exception";
+        }
+    }
+    lease_observer.reset();
+    FinishAttempt(publish_error, true);
+    return publish_error;
+}
+
+void BatchOpLogSnapshotCoordinator::SchedulerLoop() {
+    while (true) {
+        {
+            std::unique_lock<std::mutex> lock(mutex_);
+            const auto delay =
+                std::chrono::seconds(config_.snapshot_interval_seconds == 0
+                                         ? 1
+                                         : config_.snapshot_interval_seconds);
+            if (cv_.wait_for(lock, delay, [this] { return stop_requested_; })) {
+                return;
+            }
+        }
+        if (RunOnce() == ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS) {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (stop_requested_) {
+                return;
+            }
+        }
+    }
+}
+
+void BatchOpLogSnapshotCoordinator::RequestStop() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        stop_requested_ = true;
+        running_ = false;
+    }
+    standby_.CancelBatchOpLogSnapshotCapture();
+    cv_.notify_all();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.cpp
new file mode 100644
index 0000000000..979c0762fe
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.cpp
@@ -0,0 +1,147 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h"
+
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+
+#include "ha_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+bool VerifyObject(SnapshotObjectStore& store, const std::string& key,
+                  uint64_t size, uint32_t crc) {
+    auto inspection = store.InspectObject(key);
+    if (!inspection || inspection->stored_size != size) return false;
+    if (inspection->crc32c) return *inspection->crc32c == crc;
+    std::vector<uint8_t> bytes;
+    return store.DownloadBuffer(key, bytes) && bytes.size() == size &&
+           Crc32cValue(bytes.data(), bytes.size()) == crc;
+}
+
+}  // namespace
+
+BatchOpLogSnapshotGc::BatchOpLogSnapshotGc(HaKvBackend& backend,
+                                           SnapshotObjectStore& store,
+                                           std::string cluster_id,
+                                           std::string snapshot_root)
+    : backend_(backend),
+      store_(store),
+      cluster_(std::move(cluster_id)),
+      root_(std::move(snapshot_root)) {}
+
+ErrorCode BatchOpLogSnapshotGc::Run(
+    const SnapshotMaintenanceLease& lease, std::string_view published,
+    const std::optional<std::string>& expected_fallback) {
+    return Run(lease, published, expected_fallback, {});
+}
+
+ErrorCode BatchOpLogSnapshotGc::Run(
+    const SnapshotMaintenanceLease& lease, std::string_view published,
+    const std::optional<std::string>& expected_fallback,
+    const std::function<bool()>& cancelled) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Gc);
+    if (!lease.IsHeld() || (cancelled && cancelled()))
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+
+    std::unordered_set<std::string> protected_prefixes;
+    const std::string latest_key =
+        ha::BuildBatchOpLogSnapshotLatestKey(cluster_);
+    const std::string fallback_key =
+        ha::BuildBatchOpLogSnapshotFallbackKey(cluster_);
+
+    // Phase 1: validate pointer state and every referenced artifact.
+    for (const auto& key : {latest_key, fallback_key}) {
+        std::string pointer;
+        const ErrorCode error = backend_.Get(key, pointer);
+        const bool latest = key == latest_key;
+        if (error == ErrorCode::ETCD_KEY_NOT_EXIST) {
+            if (latest || expected_fallback.has_value())
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            continue;
+        }
+        if (error != ErrorCode::OK) return error;
+        if ((latest && pointer != published) ||
+            (!latest &&
+             (!expected_fallback.has_value() || pointer != *expected_fallback)))
+            return ErrorCode::ETCD_TRANSACTION_FAIL;
+
+        auto descriptor = ha::DecodeBatchOpLogSnapshotDescriptor(pointer);
+        if (!descriptor) return ErrorCode::INTERNAL_ERROR;
+        const std::string prefix = ha::BuildBatchOpLogSnapshotArtifactPrefix(
+            root_, descriptor->snapshot_id);
+        if (prefix.empty() ||
+            descriptor->manifest_key != ha::BuildBatchOpLogSnapshotManifestKey(
+                                            root_, descriptor->snapshot_id))
+            return ErrorCode::INTERNAL_ERROR;
+
+        std::string manifest_json;
+        if (!store_.DownloadString(descriptor->manifest_key, manifest_json) ||
+            manifest_json.size() != descriptor->manifest_size ||
+            Crc32cValue(manifest_json.data(), manifest_json.size()) !=
+                descriptor->manifest_crc32c)
+            return ErrorCode::INTERNAL_ERROR;
+        auto manifest = ha::DecodeBatchOpLogSnapshotManifest(manifest_json);
+        if (!manifest || manifest->snapshot_id != descriptor->snapshot_id ||
+            manifest->segments.stored_size == 0 ||
+            manifest->segments.key != ha::BuildBatchOpLogSnapshotSegmentsKey(
+                                          root_, descriptor->snapshot_id) ||
+            !VerifyObject(store_, manifest->segments.key,
+                          manifest->segments.stored_size,
+                          manifest->segments.crc32c))
+            return ErrorCode::INTERNAL_ERROR;
+        for (size_t i = 0; i < manifest->object_chunks.size(); ++i) {
+            const auto& chunk = manifest->object_chunks[i];
+            if (chunk.chunk_index != i || chunk.stored_size == 0 ||
+                chunk.key != ha::BuildBatchOpLogSnapshotObjectChunkKey(
+                                 root_, descriptor->snapshot_id, i) ||
+                !VerifyObject(store_, chunk.key, chunk.stored_size,
+                              chunk.crc32c))
+                return ErrorCode::INTERNAL_ERROR;
+        }
+        protected_prefixes.insert(prefix);
+    }
+
+    // Phase 2: derive candidate attempt prefixes from the batch-oplog root.
+    if (!lease.IsHeld() || (cancelled && cancelled()))
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    const std::string namespace_prefix = root_ + "/batch-oplog/";
+    std::vector<std::string> objects;
+    if (!store_.ListObjectsWithPrefix(namespace_prefix, objects))
+        return ErrorCode::INTERNAL_ERROR;
+    std::unordered_set<std::string> candidates;
+    for (const auto& object : objects) {
+        if (!object.starts_with(namespace_prefix)) continue;
+        const size_t end = object.find('/', namespace_prefix.size());
+        if (end != std::string::npos)
+            candidates.insert(object.substr(0, end + 1));
+    }
+
+    uint64_t orphan_prefixes = 0;
+    for (const auto& prefix : candidates)
+        orphan_prefixes += !protected_prefixes.contains(prefix);
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.gc_orphan_prefixes = orphan_prefixes;
+        metrics.gc_deleted_prefixes = 0;
+    });
+    // Phase 3: fence every destructive operation.
+    for (const auto& prefix : candidates) {
+        if (protected_prefixes.contains(prefix)) continue;
+        if (!lease.IsHeld() || (cancelled && cancelled()))
+            return ErrorCode::ETCD_TRANSACTION_FAIL;
+        if (!store_.DeleteObjectsWithPrefix(prefix))
+            return ErrorCode::INTERNAL_ERROR;
+        HAMetricManager::instance().update_snapshot_runtime(
+            [](auto& metrics) { ++metrics.gc_deleted_prefixes; });
+    }
+    return metric_timer.Success(ErrorCode::OK);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.cpp
new file mode 100644
index 0000000000..81fdda85c0
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.cpp
@@ -0,0 +1,479 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
+
+#include <algorithm>
+#include <memory>
+#include <string_view>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_applier.h"
+#include "ha/oplog/oplog_batch_standby_reader.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/snapshot/batch_oplog/codec.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+
+#include "ha_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+enum class AttemptDisposition { kSuccess, kInvalid, kInfrastructure };
+
+struct AttemptResult {
+    AttemptDisposition disposition{AttemptDisposition::kInvalid};
+    ErrorCode error{ErrorCode::DESERIALIZE_FAIL};
+    BatchOpLogSnapshotRestoreResult value;
+};
+
+AttemptResult Invalid(ErrorCode error = ErrorCode::DESERIALIZE_FAIL) {
+    return {AttemptDisposition::kInvalid, error, {}};
+}
+
+AttemptResult Infrastructure(
+    ErrorCode error = ErrorCode::ETCD_OPERATION_ERROR) {
+    return {AttemptDisposition::kInfrastructure, error, {}};
+}
+
+bool IsRetryableBackendError(ErrorCode error) {
+    return error == ErrorCode::ETCD_OPERATION_ERROR ||
+           error == ErrorCode::ETCD_CTX_CANCELLED;
+}
+
+bool SameIdentity(const ha::BatchOpLogSnapshotDescriptor& descriptor,
+                  const ha::BatchOpLogSnapshotManifest& manifest) {
+    return descriptor.schema_version == manifest.schema_version &&
+           descriptor.snapshot_format == manifest.snapshot_format &&
+           descriptor.snapshot_id == manifest.snapshot_id &&
+           descriptor.last_included_seq == manifest.last_included_seq &&
+           descriptor.last_included_batch_id ==
+               manifest.last_included_batch_id &&
+           descriptor.producer_view_version == manifest.producer_view_version;
+}
+
+AttemptResult ReadVerifiedObject(SnapshotObjectStore& object_store,
+                                 const std::string& key, uint64_t expected_size,
+                                 uint32_t expected_crc,
+                                 std::vector<uint8_t>& bytes) {
+    auto inspection = object_store.InspectObject(key);
+    if (!inspection) {
+        return object_store.IsNotFoundError(inspection.error())
+                   ? Invalid()
+                   : Infrastructure();
+    }
+    if (inspection->stored_size != expected_size || expected_size == 0) {
+        return Invalid();
+    }
+    if (inspection->crc32c && *inspection->crc32c != expected_crc) {
+        return Invalid();
+    }
+
+    auto download = object_store.DownloadBuffer(key, bytes);
+    if (!download) {
+        return object_store.IsNotFoundError(download.error())
+                   ? Invalid()
+                   : Infrastructure();
+    }
+    if (bytes.size() != expected_size ||
+        Crc32cValue(bytes.data(), bytes.size()) != expected_crc) {
+        return Invalid();
+    }
+    return {AttemptDisposition::kSuccess, ErrorCode::OK, {}};
+}
+
+AttemptResult ReadDescriptorObject(SnapshotObjectStore& object_store,
+                                   const std::string& key,
+                                   std::string_view pointer_bytes) {
+    std::vector<uint8_t> bytes;
+    auto inspection = object_store.InspectObject(key);
+    if (!inspection) {
+        return object_store.IsNotFoundError(inspection.error())
+                   ? Invalid()
+                   : Infrastructure();
+    }
+    if (inspection->stored_size != pointer_bytes.size()) {
+        return Invalid();
+    }
+    auto download = object_store.DownloadBuffer(key, bytes);
+    if (!download) {
+        return object_store.IsNotFoundError(download.error())
+                   ? Invalid()
+                   : Infrastructure();
+    }
+    if (bytes.size() != pointer_bytes.size() ||
+        !std::equal(bytes.begin(), bytes.end(), pointer_bytes.begin(),
+                    pointer_bytes.end())) {
+        return Invalid();
+    }
+    return {AttemptDisposition::kSuccess, ErrorCode::OK, {}};
+}
+
+bool ValidateSegments(const std::vector<StandbySegmentInfo>& segments) {
+    std::unordered_set<std::string> endpoints;
+    for (const auto& segment : segments) {
+        if (segment.transport_endpoint.empty() ||
+            !endpoints.insert(segment.transport_endpoint).second) {
+            return false;
+        }
+    }
+    return true;
+}
+
+void CopyRegistry(const StandbySegmentRegistry& source,
+                  StandbySegmentRegistry& destination) {
+    destination.Clear();
+    for (const auto& segment : source.GetAllSegments()) {
+        destination.OnSegmentMount(segment);
+    }
+}
+
+AttemptResult ReplaySuffix(const std::string& cluster_id, HaKvBackend& backend,
+                           OpLogApplier& applier, const DurablePrefix* baseline,
+                           const std::function<bool()>& cancelled) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Replay);
+    OpLogBatchStandbyReader reader(cluster_id, backend, applier);
+    const DurablePrefix start =
+        baseline == nullptr ? DurablePrefix{} : *baseline;
+    if (reader.SetBaselineCursor(start) != ErrorCode::OK) {
+        return Invalid(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP);
+    }
+
+    HAMetricManager::instance().update_snapshot_runtime(
+        [](auto& metrics) { metrics.suffix_batches = 0; });
+    for (;;) {
+        if (cancelled && cancelled()) {
+            return Invalid(ErrorCode::ETCD_CTX_CANCELLED);
+        }
+        auto poll = reader.PollOnce();
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.suffix_batches += poll.applied_batches;
+            if (poll.durable_prefix_present)
+                metrics.durable_batch = std::max(metrics.durable_batch,
+                                                 poll.durable_prefix.batch_id);
+            metrics.compaction_floor =
+                std::max(metrics.compaction_floor, poll.compaction_floor);
+        });
+        if (poll.error != ErrorCode::OK) {
+            return IsRetryableBackendError(poll.error)
+                       ? Infrastructure(poll.error)
+                       : Invalid(poll.error);
+        }
+        if (!poll.durable_prefix_present) {
+            // A missing prefix cannot prove complete history, even for an
+            // empty cluster.
+            return Invalid(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP);
+        }
+        const uint64_t applied = applier.GetExpectedSequenceId() - 1;
+        if (applied == poll.durable_prefix.last_seq) {
+            metric_timer.error = 0;
+            return {AttemptDisposition::kSuccess,
+                    ErrorCode::OK,
+                    {.last_included_seq = poll.durable_prefix.last_seq,
+                     .last_included_batch_id = poll.durable_prefix.batch_id}};
+        }
+        if (poll.applied_entries == 0) {
+            return Invalid(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP);
+        }
+    }
+}
+
+AttemptResult RestorePointer(
+    const std::string& cluster_id, HaKvBackend& backend,
+    SnapshotObjectStore& object_store, const std::string& snapshot_root,
+    std::string_view pointer_bytes, StandbyMetadataStore& metadata,
+    StandbySegmentRegistry& registry, OpLogApplier* supplied_applier,
+    const std::function<bool()>& cancelled) {
+    if (cancelled && cancelled()) return Invalid(ErrorCode::ETCD_CTX_CANCELLED);
+    auto decoded_descriptor =
+        ha::DecodeBatchOpLogSnapshotDescriptor(pointer_bytes);
+    if (!decoded_descriptor) {
+        return Invalid();
+    }
+    const auto& descriptor = *decoded_descriptor;
+    const std::string expected_manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey(snapshot_root,
+                                               descriptor.snapshot_id);
+    if (descriptor.manifest_key != expected_manifest_key) {
+        return Invalid();
+    }
+    const std::string descriptor_key = ha::BuildBatchOpLogSnapshotDescriptorKey(
+        snapshot_root, descriptor.snapshot_id);
+    if (descriptor_key.empty()) {
+        return Invalid();
+    }
+
+    auto read_descriptor =
+        ReadDescriptorObject(object_store, descriptor_key, pointer_bytes);
+    if (read_descriptor.disposition != AttemptDisposition::kSuccess) {
+        return read_descriptor;
+    }
+
+    std::vector<uint8_t> manifest_bytes;
+    auto read_manifest = ReadVerifiedObject(
+        object_store, descriptor.manifest_key, descriptor.manifest_size,
+        descriptor.manifest_crc32c, manifest_bytes);
+    if (read_manifest.disposition != AttemptDisposition::kSuccess) {
+        return read_manifest;
+    }
+    auto decoded_manifest = ha::DecodeBatchOpLogSnapshotManifest(
+        std::string_view(reinterpret_cast<const char*>(manifest_bytes.data()),
+                         manifest_bytes.size()));
+    std::vector<uint8_t>().swap(manifest_bytes);
+    if (!decoded_manifest || !SameIdentity(descriptor, *decoded_manifest)) {
+        return Invalid();
+    }
+    const auto& manifest = *decoded_manifest;
+    const std::string expected_segments_key =
+        ha::BuildBatchOpLogSnapshotSegmentsKey(snapshot_root,
+                                               descriptor.snapshot_id);
+    if (descriptor.manifest_key != expected_manifest_key ||
+        manifest.segments.key != expected_segments_key) {
+        return Invalid();
+    }
+
+    std::vector<uint8_t> segments_bytes;
+    auto read_segments = ReadVerifiedObject(
+        object_store, manifest.segments.key, manifest.segments.stored_size,
+        manifest.segments.crc32c, segments_bytes);
+    if (read_segments.disposition != AttemptDisposition::kSuccess) {
+        return read_segments;
+    }
+    auto decoded_segments = DecodeBatchOpLogSnapshotSegments(segments_bytes);
+    std::vector<uint8_t>().swap(segments_bytes);
+    if (!decoded_segments || !ValidateSegments(*decoded_segments)) {
+        return Invalid();
+    }
+
+    std::unique_ptr<OpLogApplier> owned_applier;
+    OpLogApplier* applier = supplied_applier;
+    if (applier == nullptr) {
+        owned_applier = std::make_unique<OpLogApplier>(&metadata, cluster_id);
+        applier = owned_applier.get();
+    }
+    applier->LoadSegmentRegistry(*decoded_segments);
+    const DurablePrefix baseline{.batch_id = descriptor.last_included_batch_id,
+                                 .last_seq = descriptor.last_included_seq};
+    applier->Recover(baseline.last_seq);
+
+    for (size_t i = 0; i < manifest.object_chunks.size(); ++i) {
+        if (cancelled && cancelled()) {
+            return Invalid(ErrorCode::ETCD_CTX_CANCELLED);
+        }
+        const auto& chunk = manifest.object_chunks[i];
+        const std::string expected_key =
+            ha::BuildBatchOpLogSnapshotObjectChunkKey(
+                snapshot_root, descriptor.snapshot_id, i);
+        if (chunk.chunk_index != i || chunk.key != expected_key) {
+            return Invalid();
+        }
+        std::vector<uint8_t> chunk_bytes;
+        auto read_chunk =
+            ReadVerifiedObject(object_store, chunk.key, chunk.stored_size,
+                               chunk.crc32c, chunk_bytes);
+        if (read_chunk.disposition != AttemptDisposition::kSuccess) {
+            return read_chunk;
+        }
+        auto decoded_chunk = DecodeBatchOpLogSnapshotObjectChunk(
+            chunk_bytes, i, chunk.object_count);
+        if (!decoded_chunk) {
+            return Invalid();
+        }
+        for (const auto& entry : decoded_chunk->objects) {
+            if (cancelled && cancelled()) {
+                return Invalid(ErrorCode::ETCD_CTX_CANCELLED);
+            }
+            if (entry.key.empty() || !TenantId(entry.tenant_id).IsValid()) {
+                return Invalid();
+            }
+            std::unordered_set<ReplicaID> object_ids;
+            for (const auto& replica : entry.metadata.replicas) {
+                if (replica.id == 0 || !object_ids.insert(replica.id).second) {
+                    return Invalid();
+                }
+            }
+            if (!metadata.RestoreMetadata(entry.tenant_id, entry.key,
+                                          entry.metadata)) {
+                return Invalid();
+            }
+        }
+    }
+
+    auto suffix =
+        ReplaySuffix(cluster_id, backend, *applier, &baseline, cancelled);
+    if (suffix.disposition != AttemptDisposition::kSuccess) {
+        return suffix;
+    }
+    ReplicaID live_max_replica_id = 0;
+    if (!metadata.ValidateReplicaIds(live_max_replica_id)) {
+        return Invalid(ErrorCode::DESERIALIZE_FAIL);
+    }
+    CopyRegistry(applier->GetSegmentRegistry(), registry);
+    uint64_t chunk_bytes = 0;
+    for (const auto& chunk : manifest.object_chunks)
+        chunk_bytes += chunk.stored_size;
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.chunk_count = manifest.object_chunks.size();
+        metrics.chunk_bytes = chunk_bytes;
+        metrics.snapshot_bytes =
+            metrics.chunk_bytes + manifest.segments.stored_size +
+            descriptor.manifest_size + pointer_bytes.size();
+    });
+    return {AttemptDisposition::kSuccess,
+            ErrorCode::OK,
+            {.last_included_seq = descriptor.last_included_seq,
+             .last_included_batch_id = descriptor.last_included_batch_id,
+             .last_applied_seq = suffix.value.last_included_seq,
+             .last_applied_batch_id = suffix.value.last_included_batch_id,
+             .producer_view_version = descriptor.producer_view_version,
+             .max_replica_id = live_max_replica_id}};
+}
+
+AttemptResult RestoreCompleteOpLog(const std::string& cluster_id,
+                                   HaKvBackend& backend,
+                                   StandbyMetadataStore& metadata,
+                                   StandbySegmentRegistry& registry,
+                                   OpLogApplier* supplied_applier,
+                                   const std::function<bool()>& cancelled) {
+    if (cancelled && cancelled()) return Invalid(ErrorCode::ETCD_CTX_CANCELLED);
+    std::unique_ptr<OpLogApplier> owned_applier;
+    OpLogApplier* applier = supplied_applier;
+    if (applier == nullptr) {
+        owned_applier = std::make_unique<OpLogApplier>(&metadata, cluster_id);
+        applier = owned_applier.get();
+    }
+    applier->Recover(0);
+    applier->LoadSegmentRegistry({});
+    OpLogBatchStorage storage(cluster_id, backend);
+    DurablePrefix durable_prefix;
+    const ErrorCode init_error = storage.InitDurablePrefix(durable_prefix);
+    if (init_error != ErrorCode::OK) {
+        return IsRetryableBackendError(init_error) ? Infrastructure(init_error)
+                                                   : Invalid(init_error);
+    }
+    auto replay =
+        ReplaySuffix(cluster_id, backend, *applier, nullptr, cancelled);
+    if (replay.disposition != AttemptDisposition::kSuccess) {
+        return replay;
+    }
+    ReplicaID max_replica_id = 0;
+    if (!metadata.ValidateReplicaIds(max_replica_id)) {
+        return Invalid(ErrorCode::DESERIALIZE_FAIL);
+    }
+    CopyRegistry(applier->GetSegmentRegistry(), registry);
+    replay.value.max_replica_id = max_replica_id;
+    replay.value.last_applied_seq = replay.value.last_included_seq;
+    replay.value.last_applied_batch_id = replay.value.last_included_batch_id;
+    return replay;
+}
+
+}  // namespace
+
+BatchOpLogSnapshotProvider::BatchOpLogSnapshotProvider(
+    std::string cluster_id, HaKvBackend& backend,
+    SnapshotObjectStore& object_store, std::string snapshot_root)
+    : cluster_id_(std::move(cluster_id)),
+      backend_(backend),
+      object_store_(object_store),
+      snapshot_root_(std::move(snapshot_root)) {}
+
+tl::expected<BatchOpLogSnapshotRestoreResult, ErrorCode>
+BatchOpLogSnapshotProvider::RestoreBaseline(StandbyMetadataStore& metadata,
+                                            StandbySegmentRegistry& registry,
+                                            OpLogApplier* applier,
+                                            uint64_t minimum_snapshot_batch,
+                                            std::function<bool()> cancelled) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Bootstrap);
+    metadata.Clear();
+    registry.Clear();
+    if (!NormalizeAndValidateClusterId(cluster_id_) || cluster_id_.empty() ||
+        snapshot_root_.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    OpLogBatchStorage storage(cluster_id_, backend_);
+    uint64_t floor = 0;
+    const auto floor_error = storage.ReadCompactionFloor(floor);
+    if (floor_error != ErrorCode::OK &&
+        floor_error != ErrorCode::ETCD_KEY_NOT_EXIST) {
+        return tl::make_unexpected(floor_error);
+    }
+    if (floor_error == ErrorCode::OK) {
+        minimum_snapshot_batch = std::max(minimum_snapshot_batch, floor);
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.compaction_floor =
+                std::max(metrics.compaction_floor, floor);
+        });
+    }
+
+    for (const std::string& pointer_key :
+         {ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_),
+          ha::BuildBatchOpLogSnapshotFallbackKey(cluster_id_)}) {
+        if (cancelled && cancelled())
+            return tl::make_unexpected(ErrorCode::ETCD_CTX_CANCELLED);
+        std::string pointer_bytes;
+        const ErrorCode pointer_error =
+            backend_.Get(pointer_key, pointer_bytes);
+        const bool latest =
+            pointer_key == ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_);
+        if (pointer_error == ErrorCode::ETCD_KEY_NOT_EXIST) {
+            HAMetricManager::instance().update_snapshot_runtime(
+                [&](auto& metrics) {
+                    (latest ? metrics.latest_created_at_ms
+                            : metrics.fallback_created_at_ms) = std::nullopt;
+                    (latest ? metrics.latest_batch : metrics.fallback_batch) =
+                        0;
+                });
+            continue;
+        }
+        if (pointer_error != ErrorCode::OK) {
+            return tl::make_unexpected(pointer_error);
+        }
+
+        auto descriptor = ha::DecodeBatchOpLogSnapshotDescriptor(pointer_bytes);
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            (latest ? metrics.latest_created_at_ms
+                    : metrics.fallback_created_at_ms) =
+                descriptor ? std::optional<int64_t>(descriptor->created_at_ms)
+                           : std::nullopt;
+            (latest ? metrics.latest_batch : metrics.fallback_batch) =
+                descriptor ? descriptor->last_included_batch_id : 0;
+        });
+        if (!descriptor ||
+            descriptor->last_included_batch_id < minimum_snapshot_batch) {
+            continue;
+        }
+        auto attempt = RestorePointer(cluster_id_, backend_, object_store_,
+                                      snapshot_root_, pointer_bytes, metadata,
+                                      registry, applier, cancelled);
+        if (attempt.disposition == AttemptDisposition::kSuccess) {
+            return metric_timer.Success(attempt.value);
+        }
+        metadata.Clear();
+        registry.Clear();
+        if (applier != nullptr) {
+            applier->Recover(0);
+            applier->LoadSegmentRegistry({});
+        }
+        if (attempt.disposition == AttemptDisposition::kInfrastructure) {
+            return tl::make_unexpected(attempt.error);
+        }
+    }
+
+    if (minimum_snapshot_batch != 0) {
+        return tl::make_unexpected(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP);
+    }
+    auto full_replay = RestoreCompleteOpLog(cluster_id_, backend_, metadata,
+                                            registry, applier, cancelled);
+    if (full_replay.disposition != AttemptDisposition::kSuccess) {
+        metadata.Clear();
+        registry.Clear();
+        return tl::make_unexpected(full_replay.error);
+    }
+    return metric_timer.Success(full_replay.value);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.cpp
new file mode 100644
index 0000000000..0724560443
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.cpp
@@ -0,0 +1,153 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h"
+
+#include <utility>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+
+namespace mooncake {
+namespace {
+
+ErrorCode ReadPointer(HaKvBackend& backend, const std::string& key,
+                      std::string& value, bool& exists) {
+    const ErrorCode err = backend.Get(key, value);
+    if (err == ErrorCode::ETCD_KEY_NOT_EXIST) {
+        value.clear();
+        exists = false;
+        return ErrorCode::OK;
+    }
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    exists = true;
+    return ErrorCode::OK;
+}
+
+}  // namespace
+
+BatchOpLogSnapshotPublisher::BatchOpLogSnapshotPublisher(HaKvBackend& backend,
+                                                         std::string cluster_id)
+    : backend_(backend), cluster_id_(std::move(cluster_id)) {}
+
+ErrorCode BatchOpLogSnapshotPublisher::Publish(
+    const SnapshotMaintenanceLease& lease, std::string_view descriptor_json,
+    std::optional<std::string>* expected_fallback) {
+    if (!lease.IsHeld()) {
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+    return PublishImpl(lease.owner_token(), descriptor_json, lease,
+                       expected_fallback);
+}
+
+ErrorCode BatchOpLogSnapshotPublisher::PublishImpl(
+    std::string_view owner_token, std::string_view descriptor_json,
+    const SnapshotMaintenanceLease& lease,
+    std::optional<std::string>* expected_fallback) {
+    if (owner_token.empty() || !lease.IsHeld() || !backend_.SupportsTxn() ||
+        cluster_id_.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    auto candidate = ha::DecodeBatchOpLogSnapshotDescriptor(descriptor_json);
+    if (!candidate) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (candidate->snapshot_id !=
+        std::to_string(candidate->last_included_batch_id) + "-" +
+            std::string(owner_token)) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    const std::string latest_key =
+        ha::BuildBatchOpLogSnapshotLatestKey(cluster_id_);
+    const std::string fallback_key =
+        ha::BuildBatchOpLogSnapshotFallbackKey(cluster_id_);
+    const std::string maintenance_key =
+        ha::BuildBatchOpLogSnapshotMaintenanceKey(cluster_id_);
+    if (latest_key.empty() || fallback_key.empty() || maintenance_key.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    std::string latest;
+    std::string fallback;
+    bool latest_exists = false;
+    bool fallback_exists = false;
+    ErrorCode err = ReadPointer(backend_, latest_key, latest, latest_exists);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    err = ReadPointer(backend_, fallback_key, fallback, fallback_exists);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    bool fallback_valid = false;
+    uint64_t fallback_batch_id = 0;
+    if (fallback_exists) {
+        auto decoded_fallback =
+            ha::DecodeBatchOpLogSnapshotDescriptor(fallback);
+        if (!decoded_fallback) {
+            return ErrorCode::INTERNAL_ERROR;
+        }
+        fallback_valid = true;
+        fallback_batch_id = decoded_fallback->last_included_batch_id;
+    }
+
+    bool latest_valid = false;
+    uint64_t latest_batch_id = 0;
+    if (latest_exists) {
+        auto decoded_latest = ha::DecodeBatchOpLogSnapshotDescriptor(latest);
+        if (decoded_latest) {
+            latest_valid = true;
+            latest_batch_id = decoded_latest->last_included_batch_id;
+        }
+    }
+    if (latest_valid && candidate->last_included_batch_id <= latest_batch_id) {
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+    if (!latest_valid && fallback_valid &&
+        candidate->last_included_batch_id <= fallback_batch_id) {
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+
+    // Re-check immediately before the fenced transaction. A keepalive can
+    // stop while object metadata is being read; the compare remains the final
+    // etcd-side fence.
+    if (!lease.IsHeld()) {
+        return ErrorCode::ETCD_TRANSACTION_FAIL;
+    }
+    KvTxn txn;
+    txn.compares.push_back({.key = maintenance_key,
+                            .kind = KvCompareKind::kValueEquals,
+                            .expected_value = std::string(owner_token)});
+    txn.compares.push_back({.key = maintenance_key,
+                            .kind = KvCompareKind::kCreateRevisionEquals,
+                            .expected_value = "",
+                            .expected_revision = lease.lock_create_revision()});
+    txn.compares.push_back({.key = latest_key,
+                            .kind = latest_exists
+                                        ? KvCompareKind::kValueEquals
+                                        : KvCompareKind::kKeyNotExists,
+                            .expected_value = latest});
+    txn.compares.push_back({.key = fallback_key,
+                            .kind = fallback_exists
+                                        ? KvCompareKind::kValueEquals
+                                        : KvCompareKind::kKeyNotExists,
+                            .expected_value = fallback});
+    if (latest_valid) {
+        txn.puts.push_back({.key = fallback_key, .value = latest});
+    }
+    txn.puts.push_back(
+        {.key = latest_key, .value = std::string(descriptor_json)});
+    err = backend_.Txn(txn);
+    if (err == ErrorCode::OK && expected_fallback) {
+        *expected_fallback =
+            latest_valid
+                ? std::optional<std::string>(latest)
+                : (fallback_exists ? std::optional<std::string>(fallback)
+                                   : std::nullopt);
+    }
+    return err;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/codec.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/codec.cpp
new file mode 100644
index 0000000000..04dfa35f8e
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/codec.cpp
@@ -0,0 +1,66 @@
+#include "ha/snapshot/batch_oplog/codec.h"
+
+#include <limits>
+#include <utility>
+
+#include <ylt/struct_pack.hpp>
+
+namespace mooncake {
+
+namespace {
+
+template <typename T>
+tl::expected<T, std::string> Decode(const std::vector<uint8_t>& encoded,
+                                    const char* artifact) {
+    T decoded;
+    if (struct_pack::deserialize_to(decoded, encoded) !=
+        struct_pack::errc::ok) {
+        return tl::make_unexpected(std::string("Invalid ") + artifact);
+    }
+    return decoded;
+}
+
+template <typename T>
+std::vector<uint8_t> Encode(const T& value) {
+    return struct_pack::serialize<std::vector<uint8_t>>(value);
+}
+
+}  // namespace
+
+std::vector<uint8_t> EncodeBatchOpLogSnapshotSegments(
+    const std::vector<StandbySegmentInfo>& segments) {
+    return Encode(segments);
+}
+
+tl::expected<std::vector<StandbySegmentInfo>, std::string>
+DecodeBatchOpLogSnapshotSegments(const std::vector<uint8_t>& encoded) {
+    return Decode<std::vector<StandbySegmentInfo>>(encoded,
+                                                   "snapshot segments");
+}
+
+std::vector<uint8_t> EncodeBatchOpLogSnapshotObjectChunk(
+    uint64_t chunk_index, std::vector<StandbyObjectEntry> objects) {
+    return Encode(
+        BatchOpLogSnapshotObjectChunk{chunk_index, std::move(objects)});
+}
+
+tl::expected<BatchOpLogSnapshotObjectChunk, std::string>
+DecodeBatchOpLogSnapshotObjectChunk(const std::vector<uint8_t>& encoded,
+                                    uint64_t expected_chunk_index,
+                                    uint64_t expected_object_count) {
+    auto decoded =
+        Decode<BatchOpLogSnapshotObjectChunk>(encoded, "snapshot object chunk");
+    if (!decoded) {
+        return decoded;
+    }
+    if (decoded->chunk_index != expected_chunk_index) {
+        return tl::make_unexpected("Snapshot object chunk index mismatch");
+    }
+    if (expected_object_count > std::numeric_limits<size_t>::max() ||
+        decoded->objects.size() != expected_object_count) {
+        return tl::make_unexpected("Snapshot object chunk count mismatch");
+    }
+    return decoded;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/metadata.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/metadata.cpp
new file mode 100644
index 0000000000..c0cd03816f
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/metadata.cpp
@@ -0,0 +1,422 @@
+#include "ha/snapshot/batch_oplog/metadata.h"
+
+#include <charconv>
+#include <memory>
+#include <string>
+#include <utility>
+
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+
+#include "ha/oplog/oplog_types.h"
+
+namespace mooncake::ha {
+
+namespace {
+
+void SetReason(std::string* reason, const std::string& value) {
+    if (reason != nullptr) {
+        *reason = value;
+    }
+}
+
+std::string WriteJson(const Json::Value& root) {
+    Json::StreamWriterBuilder builder;
+    builder["indentation"] = "";
+    return Json::writeString(builder, root);
+}
+
+bool ParseJson(std::string_view value, Json::Value& root, std::string* reason) {
+    Json::CharReaderBuilder builder;
+    builder["allowComments"] = false;
+    builder["collectComments"] = false;
+    builder["failIfExtra"] = true;
+    builder["rejectDupKeys"] = true;
+    builder["strictRoot"] = true;
+    std::unique_ptr<Json::CharReader> reader(builder.newCharReader());
+    std::string errors;
+    if (!reader->parse(value.data(), value.data() + value.size(), &root,
+                       &errors)) {
+        SetReason(reason, errors.empty() ? "malformed json" : errors);
+        return false;
+    }
+    if (!root.isObject()) {
+        SetReason(reason, "snapshot metadata must be a JSON object");
+        return false;
+    }
+    return true;
+}
+
+bool GetString(const Json::Value& root, const char* field, std::string& value,
+               std::string* reason) {
+    if (!root.isMember(field) || !root[field].isString()) {
+        SetReason(reason, std::string("field must be a string: ") + field);
+        return false;
+    }
+    value = root[field].asString();
+    return true;
+}
+
+bool GetUInt32(const Json::Value& root, const char* field, uint32_t& value,
+               std::string* reason) {
+    if (!root.isMember(field) || !root[field].isUInt()) {
+        SetReason(reason, std::string("field must be uint32: ") + field);
+        return false;
+    }
+    value = root[field].asUInt();
+    return true;
+}
+
+bool GetUInt64(const Json::Value& root, const char* field, uint64_t& value,
+               std::string* reason) {
+    if (!root.isMember(field) || !root[field].isUInt64()) {
+        SetReason(reason, std::string("field must be uint64: ") + field);
+        return false;
+    }
+    value = root[field].asUInt64();
+    return true;
+}
+
+template <typename Integer>
+bool GetInt64(const Json::Value& root, const char* field, Integer& value,
+              std::string* reason) {
+    if (!root.isMember(field) || !root[field].isInt64()) {
+        SetReason(reason, std::string("field must be int64: ") + field);
+        return false;
+    }
+    value = static_cast<Integer>(root[field].asInt64());
+    return true;
+}
+
+template <typename Integer>
+bool ParseDecimal(std::string_view value, Integer& result) {
+    const char* begin = value.data();
+    const char* end = begin + value.size();
+    const auto parsed = std::from_chars(begin, end, result);
+    return begin != end && parsed.ec == std::errc() && parsed.ptr == end;
+}
+
+bool ParseSnapshotId(std::string_view snapshot_id, uint64_t& batch_id) {
+    const size_t separator = snapshot_id.find('-');
+    if (separator == std::string_view::npos || separator == 0 ||
+        separator + 1 == snapshot_id.size() ||
+        snapshot_id.find('-', separator + 1) != std::string_view::npos) {
+        return false;
+    }
+
+    uint64_t parsed_batch_id = 0;
+    int64_t lease_id = 0;
+    if (!ParseDecimal(snapshot_id.substr(0, separator), parsed_batch_id) ||
+        !ParseDecimal(snapshot_id.substr(separator + 1), lease_id) ||
+        lease_id <= 0 ||
+        snapshot_id !=
+            std::to_string(parsed_batch_id) + "-" + std::to_string(lease_id)) {
+        return false;
+    }
+    batch_id = parsed_batch_id;
+    return true;
+}
+
+template <typename SnapshotMetadata>
+bool ValidateIdentity(const SnapshotMetadata& metadata, std::string* reason) {
+    if (metadata.schema_version != kBatchOpLogSnapshotSchemaVersion) {
+        SetReason(reason, "unsupported snapshot schema_version");
+        return false;
+    }
+    if (metadata.snapshot_format != kBatchOpLogSnapshotFormat) {
+        SetReason(reason, "unsupported snapshot_format");
+        return false;
+    }
+    uint64_t snapshot_batch_id = 0;
+    if (!ParseSnapshotId(metadata.snapshot_id, snapshot_batch_id) ||
+        snapshot_batch_id != metadata.last_included_batch_id) {
+        SetReason(reason, "snapshot_id does not match the batch cursor");
+        return false;
+    }
+    if ((metadata.last_included_seq == 0) !=
+        (metadata.last_included_batch_id == 0)) {
+        SetReason(reason,
+                  "sequence and batch cursors must both be zero or non-zero");
+        return false;
+    }
+    if (metadata.producer_view_version < 0) {
+        SetReason(reason, "producer_view_version must be non-negative");
+        return false;
+    }
+    return true;
+}
+
+template <typename SnapshotMetadata>
+void EncodeIdentity(const SnapshotMetadata& metadata, Json::Value& root) {
+    root["schema_version"] = static_cast<Json::UInt>(metadata.schema_version);
+    root["snapshot_format"] = metadata.snapshot_format;
+    root["snapshot_id"] = metadata.snapshot_id;
+    root["last_included_seq"] =
+        static_cast<Json::UInt64>(metadata.last_included_seq);
+    root["last_included_batch_id"] =
+        static_cast<Json::UInt64>(metadata.last_included_batch_id);
+    root["producer_view_version"] =
+        static_cast<Json::Int64>(metadata.producer_view_version);
+}
+
+template <typename SnapshotMetadata>
+bool DecodeIdentity(const Json::Value& root, SnapshotMetadata& metadata,
+                    std::string* reason) {
+    return GetUInt32(root, "schema_version", metadata.schema_version, reason) &&
+           GetString(root, "snapshot_format", metadata.snapshot_format,
+                     reason) &&
+           GetString(root, "snapshot_id", metadata.snapshot_id, reason) &&
+           GetUInt64(root, "last_included_seq", metadata.last_included_seq,
+                     reason) &&
+           GetUInt64(root, "last_included_batch_id",
+                     metadata.last_included_batch_id, reason) &&
+           GetInt64(root, "producer_view_version",
+                    metadata.producer_view_version, reason) &&
+           ValidateIdentity(metadata, reason);
+}
+
+Json::Value EncodeObjectDescriptor(
+    const BatchOpLogSnapshotObjectDescriptor& descriptor) {
+    Json::Value root(Json::objectValue);
+    root["key"] = descriptor.key;
+    root["stored_size"] = static_cast<Json::UInt64>(descriptor.stored_size);
+    root["crc32c"] = static_cast<Json::UInt>(descriptor.crc32c);
+    return root;
+}
+
+bool DecodeObjectDescriptor(const Json::Value& root,
+                            BatchOpLogSnapshotObjectDescriptor& descriptor,
+                            std::string* reason) {
+    if (!root.isObject()) {
+        SetReason(reason, "segments must be a JSON object");
+        return false;
+    }
+    if (!GetString(root, "key", descriptor.key, reason) ||
+        !GetUInt64(root, "stored_size", descriptor.stored_size, reason) ||
+        !GetUInt32(root, "crc32c", descriptor.crc32c, reason)) {
+        return false;
+    }
+    if (descriptor.key.empty() || descriptor.stored_size == 0) {
+        SetReason(reason, "segments key and stored_size must be non-zero");
+        return false;
+    }
+    return true;
+}
+
+Json::Value EncodeChunkDescriptor(
+    const BatchOpLogSnapshotChunkDescriptor& descriptor) {
+    Json::Value root(Json::objectValue);
+    root["chunk_index"] = static_cast<Json::UInt64>(descriptor.chunk_index);
+    root["key"] = descriptor.key;
+    root["object_count"] = static_cast<Json::UInt64>(descriptor.object_count);
+    root["stored_size"] = static_cast<Json::UInt64>(descriptor.stored_size);
+    root["crc32c"] = static_cast<Json::UInt>(descriptor.crc32c);
+    return root;
+}
+
+bool DecodeChunkDescriptor(const Json::Value& root, uint64_t expected_index,
+                           BatchOpLogSnapshotChunkDescriptor& descriptor,
+                           std::string* reason) {
+    if (!root.isObject()) {
+        SetReason(reason, "object chunk must be a JSON object");
+        return false;
+    }
+    if (!GetUInt64(root, "chunk_index", descriptor.chunk_index, reason) ||
+        !GetString(root, "key", descriptor.key, reason) ||
+        !GetUInt64(root, "object_count", descriptor.object_count, reason) ||
+        !GetUInt64(root, "stored_size", descriptor.stored_size, reason) ||
+        !GetUInt32(root, "crc32c", descriptor.crc32c, reason)) {
+        return false;
+    }
+    if (descriptor.chunk_index != expected_index) {
+        SetReason(reason, "object chunk indices must be contiguous from zero");
+        return false;
+    }
+    if (descriptor.key.empty() || descriptor.object_count == 0 ||
+        descriptor.stored_size == 0) {
+        SetReason(
+            reason,
+            "object chunk key, object_count, and stored_size must be non-zero");
+        return false;
+    }
+    return true;
+}
+
+std::string BuildControlKey(const std::string& cluster_id,
+                            std::string_view name) {
+    std::string normalized = cluster_id;
+    if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
+        return {};
+    }
+    return "/oplog/" + normalized + "/snapshot/" + std::string(name);
+}
+
+std::string BuildArtifactPrefix(const std::string& snapshot_root,
+                                std::string_view snapshot_id) {
+    uint64_t ignored_batch_id = 0;
+    if (!ParseSnapshotId(snapshot_id, ignored_batch_id)) {
+        return {};
+    }
+    std::string normalized = snapshot_root;
+    while (!normalized.empty() && normalized.back() == '/') {
+        normalized.pop_back();
+    }
+    if (normalized.empty()) {
+        return {};
+    }
+    return normalized + "/batch-oplog/" + std::string(snapshot_id) + "/";
+}
+
+}  // namespace
+
+std::string EncodeBatchOpLogSnapshotDescriptor(
+    const BatchOpLogSnapshotDescriptor& descriptor) {
+    Json::Value root(Json::objectValue);
+    EncodeIdentity(descriptor, root);
+    root["manifest_key"] = descriptor.manifest_key;
+    root["manifest_size"] = static_cast<Json::UInt64>(descriptor.manifest_size);
+    root["manifest_crc32c"] =
+        static_cast<Json::UInt>(descriptor.manifest_crc32c);
+    root["created_at_ms"] = static_cast<Json::Int64>(descriptor.created_at_ms);
+    return WriteJson(root);
+}
+
+tl::expected<BatchOpLogSnapshotDescriptor, std::string>
+DecodeBatchOpLogSnapshotDescriptor(std::string_view value) {
+    std::string reason;
+    Json::Value root;
+    BatchOpLogSnapshotDescriptor decoded;
+    if (!ParseJson(value, root, &reason) ||
+        !DecodeIdentity(root, decoded, &reason) ||
+        !GetString(root, "manifest_key", decoded.manifest_key, &reason) ||
+        !GetUInt64(root, "manifest_size", decoded.manifest_size, &reason) ||
+        !GetUInt32(root, "manifest_crc32c", decoded.manifest_crc32c, &reason) ||
+        !GetInt64(root, "created_at_ms", decoded.created_at_ms, &reason)) {
+        return tl::make_unexpected(std::move(reason));
+    }
+    if (decoded.manifest_key.empty() || decoded.manifest_size == 0 ||
+        decoded.created_at_ms < 0) {
+        SetReason(&reason,
+                  "manifest key and size must be non-zero and created_at_ms "
+                  "non-negative");
+        return tl::make_unexpected(std::move(reason));
+    }
+    return decoded;
+}
+
+std::string EncodeBatchOpLogSnapshotManifest(
+    const BatchOpLogSnapshotManifest& manifest) {
+    Json::Value root(Json::objectValue);
+    EncodeIdentity(manifest, root);
+    root["segments"] = EncodeObjectDescriptor(manifest.segments);
+    Json::Value chunks(Json::arrayValue);
+    for (const auto& descriptor : manifest.object_chunks) {
+        chunks.append(EncodeChunkDescriptor(descriptor));
+    }
+    root["object_chunks"] = std::move(chunks);
+    return WriteJson(root);
+}
+
+tl::expected<BatchOpLogSnapshotManifest, std::string>
+DecodeBatchOpLogSnapshotManifest(std::string_view value) {
+    std::string reason;
+    Json::Value root;
+    BatchOpLogSnapshotManifest decoded;
+    if (!ParseJson(value, root, &reason) ||
+        !DecodeIdentity(root, decoded, &reason)) {
+        return tl::make_unexpected(std::move(reason));
+    }
+    if (!root.isMember("segments")) {
+        SetReason(&reason, "missing field: segments");
+        return tl::make_unexpected(std::move(reason));
+    }
+    if (!DecodeObjectDescriptor(root["segments"], decoded.segments, &reason)) {
+        return tl::make_unexpected(std::move(reason));
+    }
+    if (!root.isMember("object_chunks") || !root["object_chunks"].isArray()) {
+        SetReason(&reason, "object_chunks must be a JSON array");
+        return tl::make_unexpected(std::move(reason));
+    }
+    const auto& chunks = root["object_chunks"];
+    decoded.object_chunks.reserve(chunks.size());
+    for (Json::ArrayIndex index = 0; index < chunks.size(); ++index) {
+        BatchOpLogSnapshotChunkDescriptor descriptor;
+        if (!DecodeChunkDescriptor(chunks[index], index, descriptor, &reason)) {
+            return tl::make_unexpected(std::move(reason));
+        }
+        decoded.object_chunks.push_back(std::move(descriptor));
+    }
+    return decoded;
+}
+
+std::string BuildBatchOpLogSnapshotId(uint64_t last_included_batch_id,
+                                      int64_t maintenance_lease_id) {
+    if (maintenance_lease_id <= 0) {
+        return {};
+    }
+    return std::to_string(last_included_batch_id) + "-" +
+           std::to_string(maintenance_lease_id);
+}
+
+std::string BuildBatchOpLogSnapshotRoot(const std::string& cluster_id) {
+    std::string normalized = cluster_id;
+    if (!NormalizeAndValidateClusterId(normalized) || normalized.empty()) {
+        return {};
+    }
+    return "mooncake_master_snapshot/" + normalized;
+}
+
+std::string BuildBatchOpLogSnapshotMaintenanceKey(
+    const std::string& cluster_id) {
+    return BuildControlKey(cluster_id, "maintenance");
+}
+
+std::string BuildBatchOpLogSnapshotLatestKey(const std::string& cluster_id) {
+    return BuildControlKey(cluster_id, "latest");
+}
+
+std::string BuildBatchOpLogSnapshotFallbackKey(const std::string& cluster_id) {
+    return BuildControlKey(cluster_id, "fallback");
+}
+
+std::string BuildBatchOpLogSnapshotCompactionFloorKey(
+    const std::string& cluster_id) {
+    return BuildControlKey(cluster_id, "compaction_floor");
+}
+
+std::string BuildBatchOpLogSnapshotArtifactPrefix(
+    const std::string& snapshot_root, std::string_view snapshot_id) {
+    return BuildArtifactPrefix(snapshot_root, snapshot_id);
+}
+
+std::string BuildBatchOpLogSnapshotDescriptorKey(
+    const std::string& snapshot_root, std::string_view snapshot_id) {
+    const std::string prefix = BuildArtifactPrefix(snapshot_root, snapshot_id);
+    return prefix.empty() ? std::string() : prefix + "descriptor.json";
+}
+
+std::string BuildBatchOpLogSnapshotManifestKey(const std::string& snapshot_root,
+                                               std::string_view snapshot_id) {
+    const std::string prefix = BuildArtifactPrefix(snapshot_root, snapshot_id);
+    return prefix.empty() ? std::string() : prefix + "manifest.json";
+}
+
+std::string BuildBatchOpLogSnapshotSegmentsKey(const std::string& snapshot_root,
+                                               std::string_view snapshot_id) {
+    const std::string prefix = BuildArtifactPrefix(snapshot_root, snapshot_id);
+    return prefix.empty() ? std::string() : prefix + "segments.bin";
+}
+
+std::string BuildBatchOpLogSnapshotObjectChunkKey(
+    const std::string& snapshot_root, std::string_view snapshot_id,
+    uint64_t chunk_index) {
+    const std::string prefix = BuildArtifactPrefix(snapshot_root, snapshot_id);
+    return prefix.empty()
+               ? std::string()
+               : prefix + "objects/" + std::to_string(chunk_index) + ".bin";
+}
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/src/ha/snapshot/batch_oplog/writer.cpp b/mooncake-store/src/ha/snapshot/batch_oplog/writer.cpp
new file mode 100644
index 0000000000..1405f338db
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/batch_oplog/writer.cpp
@@ -0,0 +1,226 @@
+#include "ha/snapshot/batch_oplog/writer.h"
+
+#include <utility>
+#include <vector>
+
+#include <glog/logging.h>
+
+#include "crc32c.h"
+#include "ha/snapshot/batch_oplog/codec.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "hot_standby_service.h"
+
+#include "ha_metric_manager.h"
+
+namespace mooncake {
+
+namespace {
+
+tl::expected<void, std::string> VerifyObject(SnapshotObjectStore& object_store,
+                                             const std::string& key,
+                                             uint64_t expected_size,
+                                             uint32_t expected_crc32c) {
+    auto inspection = object_store.InspectObject(key);
+    if (!inspection) {
+        return tl::make_unexpected("Failed to inspect snapshot object " + key +
+                                   ": " + inspection.error());
+    }
+    if (inspection->stored_size != expected_size) {
+        return tl::make_unexpected("Snapshot object size mismatch: " + key);
+    }
+    if (inspection->crc32c) {
+        if (*inspection->crc32c != expected_crc32c) {
+            return tl::make_unexpected("Snapshot object CRC32C mismatch: " +
+                                       key);
+        }
+        return {};
+    }
+
+    std::vector<uint8_t> downloaded;
+    auto download = object_store.DownloadBuffer(key, downloaded);
+    if (!download) {
+        return tl::make_unexpected("Failed to read back snapshot object " +
+                                   key + ": " + download.error());
+    }
+    if (downloaded.size() != expected_size ||
+        Crc32cValue(downloaded.data(), downloaded.size()) != expected_crc32c) {
+        return tl::make_unexpected("Snapshot object readback mismatch: " + key);
+    }
+    return {};
+}
+
+}  // namespace
+
+tl::expected<std::string, std::string> BatchOpLogSnapshotWriter::Write(
+    HotStandbyService& standby, BatchOpLogSnapshotCapture& capture,
+    const std::string& snapshot_root, const std::string& snapshot_id,
+    size_t chunk_object_count, int64_t created_at_ms) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Upload);
+    bool capture_active = true;
+    bool candidate_touched = false;
+    const std::string prefix =
+        ha::BuildBatchOpLogSnapshotArtifactPrefix(snapshot_root, snapshot_id);
+
+    auto end_capture = [&] {
+        if (capture_active) {
+            standby.EndBatchOpLogSnapshotCapture(capture);
+            capture_active = false;
+        }
+    };
+    auto fail =
+        [&](std::string error) -> tl::expected<std::string, std::string> {
+        end_capture();
+        if (candidate_touched) {
+            auto cleanup = object_store_.DeleteObjectsWithPrefix(prefix);
+            if (!cleanup) {
+                LOG(WARNING) << "Failed to clean snapshot candidate " << prefix
+                             << ": " << cleanup.error();
+            }
+        }
+        return tl::make_unexpected(std::move(error));
+    };
+
+    const std::string expected_id_prefix =
+        std::to_string(capture.last_included_batch_id) + "-";
+    if (prefix.empty() || !snapshot_id.starts_with(expected_id_prefix) ||
+        (capture.last_included_seq == 0) !=
+            (capture.last_included_batch_id == 0) ||
+        capture.producer_view_version < 0 || chunk_object_count == 0 ||
+        created_at_ms < 0) {
+        return fail("Invalid batch OpLog snapshot writer arguments");
+    }
+
+    std::vector<std::string> existing;
+    auto list = object_store_.ListObjectsWithPrefix(prefix, existing);
+    if (!list) {
+        return fail("Failed to check snapshot candidate prefix: " +
+                    list.error());
+    }
+    if (!existing.empty()) {
+        return fail("Snapshot candidate prefix already exists: " + prefix);
+    }
+
+    ha::BatchOpLogSnapshotManifest manifest;
+    manifest.snapshot_id = snapshot_id;
+    manifest.last_included_seq = capture.last_included_seq;
+    manifest.last_included_batch_id = capture.last_included_batch_id;
+    manifest.producer_view_version = capture.producer_view_version;
+
+    const std::string segments_key =
+        ha::BuildBatchOpLogSnapshotSegmentsKey(snapshot_root, snapshot_id);
+    auto segments = EncodeBatchOpLogSnapshotSegments(capture.segments);
+    manifest.segments = {
+        .key = segments_key,
+        .stored_size = segments.size(),
+        .crc32c = Crc32cValue(segments.data(), segments.size()),
+    };
+    candidate_touched = true;
+    auto upload = object_store_.UploadBuffer(segments_key, segments);
+    if (!upload) {
+        return fail("Failed to upload snapshot segments: " + upload.error());
+    }
+    std::vector<uint8_t>().swap(segments);
+
+    uint64_t chunk_index = 0;
+    while (!capture.done()) {
+        std::vector<StandbyObjectEntry> objects;
+        if (!standby.CopyNextBatchOpLogSnapshotChunk(chunk_object_count,
+                                                     capture, objects)) {
+            return fail("Batch OpLog snapshot capture was cancelled");
+        }
+        if (objects.empty()) {
+            return fail("Batch OpLog snapshot capture returned an empty chunk");
+        }
+
+        const size_t object_count = objects.size();
+        auto encoded = EncodeBatchOpLogSnapshotObjectChunk(chunk_index,
+                                                           std::move(objects));
+        const std::string key = ha::BuildBatchOpLogSnapshotObjectChunkKey(
+            snapshot_root, snapshot_id, chunk_index);
+        ha::BatchOpLogSnapshotChunkDescriptor descriptor{
+            .chunk_index = chunk_index,
+            .key = key,
+            .object_count = object_count,
+            .stored_size = encoded.size(),
+            .crc32c = Crc32cValue(encoded.data(), encoded.size()),
+        };
+        upload = object_store_.UploadBuffer(key, encoded);
+        if (!upload) {
+            return fail("Failed to upload snapshot object chunk: " +
+                        upload.error());
+        }
+        manifest.object_chunks.push_back(std::move(descriptor));
+        ++chunk_index;
+    }
+    end_capture();
+
+    auto verify =
+        VerifyObject(object_store_, manifest.segments.key,
+                     manifest.segments.stored_size, manifest.segments.crc32c);
+    if (!verify) {
+        return fail(std::move(verify.error()));
+    }
+    for (const auto& chunk : manifest.object_chunks) {
+        verify = VerifyObject(object_store_, chunk.key, chunk.stored_size,
+                              chunk.crc32c);
+        if (!verify) {
+            return fail(std::move(verify.error()));
+        }
+    }
+
+    const std::string manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey(snapshot_root, snapshot_id);
+    const std::string manifest_json =
+        ha::EncodeBatchOpLogSnapshotManifest(manifest);
+    const uint32_t manifest_crc32c =
+        Crc32cValue(manifest_json.data(), manifest_json.size());
+    upload = object_store_.UploadString(manifest_key, manifest_json);
+    if (!upload) {
+        return fail("Failed to upload snapshot manifest: " + upload.error());
+    }
+    verify = VerifyObject(object_store_, manifest_key, manifest_json.size(),
+                          manifest_crc32c);
+    if (!verify) {
+        return fail(std::move(verify.error()));
+    }
+
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = snapshot_id;
+    descriptor.last_included_seq = capture.last_included_seq;
+    descriptor.last_included_batch_id = capture.last_included_batch_id;
+    descriptor.producer_view_version = capture.producer_view_version;
+    descriptor.manifest_key = manifest_key;
+    descriptor.manifest_size = manifest_json.size();
+    descriptor.manifest_crc32c = manifest_crc32c;
+    descriptor.created_at_ms = created_at_ms;
+
+    const std::string descriptor_json =
+        ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+    const std::string descriptor_key =
+        ha::BuildBatchOpLogSnapshotDescriptorKey(snapshot_root, snapshot_id);
+    upload = object_store_.UploadString(descriptor_key, descriptor_json);
+    if (!upload) {
+        return fail("Failed to upload snapshot descriptor: " + upload.error());
+    }
+    verify = VerifyObject(
+        object_store_, descriptor_key, descriptor_json.size(),
+        Crc32cValue(descriptor_json.data(), descriptor_json.size()));
+    if (!verify) {
+        return fail(std::move(verify.error()));
+    }
+    uint64_t chunk_bytes = 0;
+    for (const auto& chunk : manifest.object_chunks)
+        chunk_bytes += chunk.stored_size;
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.chunk_count = manifest.object_chunks.size();
+        metrics.chunk_bytes = chunk_bytes;
+        metrics.snapshot_bytes = metrics.chunk_bytes +
+                                 manifest.segments.stored_size +
+                                 manifest_json.size() + descriptor_json.size();
+    });
+    return metric_timer.Success(descriptor_json);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.cpp b/mooncake-store/src/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.cpp
index 93dd5c9ae8..f6259e2fe7 100644
--- a/mooncake-store/src/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.cpp
+++ b/mooncake-store/src/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.cpp
@@ -1,6 +1,5 @@
 #include "ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store.h"
 
-#include <cstdlib>
 #include <exception>
 #include <memory>
 #include <optional>
@@ -9,6 +8,7 @@
 #include <glog/logging.h>
 
 #include "types.h"
+#include "config/ha_cluster_namespace_config.h"
 #include "ascii_string.h"
 #include "integer_parser.h"
 #ifdef STORE_USE_REDIS
@@ -331,11 +331,7 @@ ClusterNamespace RedisSnapshotCatalogStore::ResolveClusterNamespace(
         return cluster_namespace;
     }
 
-    const char* env_cluster_id = std::getenv("MC_STORE_CLUSTER_ID");
-    if (env_cluster_id != nullptr && *env_cluster_id != '\0') {
-        return env_cluster_id;
-    }
-    return DEFAULT_CLUSTER_ID;
+    return HaClusterNamespaceConfig::FromEnvironment().cluster_namespace;
 }
 
 std::string RedisSnapshotCatalogStore::BuildLatestKey(
diff --git a/mooncake-store/src/ha/snapshot/catalog_backed_snapshot_provider.cpp b/mooncake-store/src/ha/snapshot/catalog_backed_snapshot_provider.cpp
index 54ee82056d..ee128e9690 100644
--- a/mooncake-store/src/ha/snapshot/catalog_backed_snapshot_provider.cpp
+++ b/mooncake-store/src/ha/snapshot/catalog_backed_snapshot_provider.cpp
@@ -17,7 +17,7 @@
 #include "ha/snapshot/object/snapshot_object_store.h"
 #include "segment.h"
 #include "serialize/serializer.h"
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake {
 
@@ -100,7 +100,6 @@ ErrorCode ValidateManifest(std::string_view snapshot_id,
 tl::expected<std::optional<StandbyObjectMetadata>, ErrorCode>
 DeserializeStandbyObjectMetadata(
     const msgpack::object& object, const SegmentView& segment_view,
-    uint64_t snapshot_sequence_id,
     const std::chrono::system_clock::time_point& now) {
     if (object.type != msgpack::type::ARRAY) {
         LOG(ERROR) << "Snapshot metadata entry is not an array";
@@ -127,10 +126,21 @@ DeserializeStandbyObjectMetadata(
         (void)array[index++].as<uint64_t>();  // put_start_time
         const auto size = static_cast<size_t>(array[index++].as<uint64_t>());
         const auto lease_timestamp_ms = array[index++].as<uint64_t>();
-        const bool has_soft_pin_timeout = array[index++].as<bool>();
-        const auto soft_pin_timestamp_ms = array[index++].as<uint64_t>();
+        (void)array[index++].as<bool>();      // legacy soft-pin flag
+        (void)array[index++].as<uint64_t>();  // legacy soft-pin deadline
         const auto replica_count = array[index++].as<uint32_t>();
 
+        const auto max_timestamp_ms =
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::system_clock::time_point::max().time_since_epoch())
+                .count();
+        if (max_timestamp_ms < 0 ||
+            lease_timestamp_ms > static_cast<uint64_t>(max_timestamp_ms)) {
+            LOG(ERROR) << "Snapshot metadata timestamp exceeds system_clock "
+                          "range";
+            return tl::make_unexpected(ErrorCode::DESERIALIZE_FAIL);
+        }
+
         // Optional fields are decoded by type for backward/forward
         // compatibility with MasterService::MetadataSerializer, which appends
         // them over time:
@@ -167,15 +177,7 @@ DeserializeStandbyObjectMetadata(
 
         const auto lease_timeout = std::chrono::system_clock::time_point(
             std::chrono::milliseconds(lease_timestamp_ms));
-        std::optional<std::chrono::system_clock::time_point> soft_pin_timeout;
-        if (has_soft_pin_timeout) {
-            soft_pin_timeout.emplace(
-                std::chrono::milliseconds(soft_pin_timestamp_ms));
-        }
-
-        if (size == 0 ||
-            (lease_timeout <= now && (!soft_pin_timeout.has_value() ||
-                                      soft_pin_timeout.value() <= now))) {
+        if (size == 0 || lease_timeout <= now) {
             return std::optional<StandbyObjectMetadata>();
         }
 
@@ -212,11 +214,10 @@ DeserializeStandbyObjectMetadata(
             return std::optional<StandbyObjectMetadata>();
         }
 
-        // Read hard_pinned and group_id if present. Standby does not need
-        // hard_pinned, but promotion needs group_id to rebuild group indexes.
+        bool hard_pinned = false;
         if (index < total_elements &&
             array[index].type == msgpack::type::BOOLEAN) {
-            ++index;  // hard_pinned
+            hard_pinned = array[index++].as<bool>();
         }
 
         std::string group_id;
@@ -228,9 +229,9 @@ DeserializeStandbyObjectMetadata(
         metadata.client_id = client_id;
         metadata.size = size;
         metadata.replicas = std::move(replicas);
-        metadata.last_sequence_id = snapshot_sequence_id;
         metadata.data_type = data_type;
         metadata.group_id = std::move(group_id);
+        metadata.hard_pinned = hard_pinned;
         return std::optional<StandbyObjectMetadata>(std::move(metadata));
     } catch (const std::exception& ex) {
         LOG(ERROR) << "Failed to parse snapshot metadata entry: " << ex.what();
@@ -240,8 +241,7 @@ DeserializeStandbyObjectMetadata(
 
 tl::expected<std::vector<StandbyObjectEntry>, ErrorCode>
 DeserializeStandbySnapshotMetadata(const std::vector<uint8_t>& data,
-                                   const SegmentView& segment_view,
-                                   uint64_t snapshot_sequence_id) {
+                                   const SegmentView& segment_view) {
     msgpack::object_handle root_handle;
     try {
         root_handle = msgpack::unpack(
@@ -329,8 +329,7 @@ DeserializeStandbySnapshotMetadata(const std::vector<uint8_t>& data,
                 const auto normalized_tenant = NormalizeTenantId(tenant_id);
 
                 auto metadata_result = DeserializeStandbyObjectMetadata(
-                    item.via.array.ptr[metadata_index], segment_view,
-                    snapshot_sequence_id, now);
+                    item.via.array.ptr[metadata_index], segment_view, now);
                 if (!metadata_result) {
                     return tl::make_unexpected(metadata_result.error());
                 }
@@ -482,8 +481,7 @@ class CatalogBackedSnapshotProvider final : public SnapshotProvider {
         }
 
         auto deserialize_metadata = DeserializeStandbySnapshotMetadata(
-            metadata_content, segment_manager.getView(),
-            descriptor.last_included_seq);
+            metadata_content, segment_manager.getView());
         if (!deserialize_metadata) {
             LOG(ERROR) << "Failed to deserialize snapshot metadata payload, "
                        << "snapshot_id=" << descriptor.snapshot_id
@@ -502,8 +500,7 @@ class CatalogBackedSnapshotProvider final : public SnapshotProvider {
         // (segment_manager.mounted_segments_, where buf_allocator is non-null
         // by construction — MountSegment is the only path that populates it).
         //
-        // Local-disk segments are serialized as per-client offloading
-        // bookkeeping (client_local_disk_segment_'s offloading_objects map)
+        // LocalSSD state is serialized as per-client offloading bookkeeping
         // without the transport_endpoint / file_path / capacity fields that
         // StandbySegmentInfo needs, and NoF segments are not serialized at
         // all in this snapshot path. Both have to be re-mounted explicitly
diff --git a/mooncake-store/src/ha/snapshot/local_ssd_codec.cpp b/mooncake-store/src/ha/snapshot/local_ssd_codec.cpp
new file mode 100644
index 0000000000..0f9d3d63c3
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/local_ssd_codec.cpp
@@ -0,0 +1,153 @@
+#include "ha/snapshot/local_ssd_codec.h"
+
+#include <fmt/format.h>
+
+#include "tenant_id.h"
+
+namespace mooncake::ha {
+namespace {
+
+bool IsMsgpackInteger(const msgpack::object& object) {
+    return object.type == msgpack::type::POSITIVE_INTEGER ||
+           object.type == msgpack::type::NEGATIVE_INTEGER;
+}
+
+SerializationError DecodeError(std::string message) {
+    return SerializationError(ErrorCode::DESERIALIZE_FAIL, message);
+}
+
+}  // namespace
+
+tl::expected<void, SerializationError> LocalSsdCodec::Encode(
+    const LocalSsdPersistedState& state, MsgpackPacker& packer) {
+    packer.pack_map(state.size());
+    for (const auto& [client_id, client] : state) {
+        packer.pack(UuidToString(client_id));
+        packer.pack_array(2 + client.pending_offloads.size() * 2 + 1);
+        packer.pack(client.enable_offloading);
+        packer.pack(static_cast<uint64_t>(client.pending_offloads.size()));
+        for (const auto& [encoded_key, task] : client.pending_offloads) {
+            packer.pack(encoded_key);
+            packer.pack_array(3);
+            packer.pack(task.tenant_id);
+            packer.pack(task.key);
+            packer.pack(task.size);
+        }
+        packer.pack(client.total_capacity_bytes);
+    }
+    return {};
+}
+
+tl::expected<LocalSsdPersistedState, SerializationError> LocalSsdCodec::Decode(
+    const msgpack::object* ld_value) {
+    LocalSsdPersistedState state;
+    if (ld_value == nullptr) {
+        return state;
+    }
+    if (ld_value->type != msgpack::type::MAP) {
+        return tl::unexpected(
+            DecodeError("deserialize local_disk_segments is not map"));
+    }
+
+    try {
+        for (uint32_t i = 0; i < ld_value->via.map.size; ++i) {
+            const auto& client_key = ld_value->via.map.ptr[i].key;
+            const auto& client_value = ld_value->via.map.ptr[i].val;
+            if (client_key.type != msgpack::type::STR) {
+                return tl::unexpected(DecodeError(
+                    "deserialize local_disk_segments client key is not "
+                    "string"));
+            }
+            std::string client_uuid(client_key.via.str.ptr,
+                                    client_key.via.str.size);
+            UUID client_id;
+            if (!StringToUuid(client_uuid, client_id)) {
+                return tl::unexpected(DecodeError(fmt::format(
+                    "deserialize local_disk_segments client uuid {} is "
+                    "invalid",
+                    client_uuid)));
+            }
+            if (client_value.type != msgpack::type::ARRAY ||
+                client_value.via.array.size < 2) {
+                return tl::unexpected(DecodeError(
+                    "deserialize local_disk_segments value is not valid "
+                    "array"));
+            }
+            if (client_value.via.array.ptr[0].type != msgpack::type::BOOLEAN ||
+                !IsMsgpackInteger(client_value.via.array.ptr[1])) {
+                return tl::unexpected(DecodeError(
+                    "deserialize local_disk_segments header is invalid"));
+            }
+
+            LocalSsdPersistedClient client;
+            client.enable_offloading = client_value.via.array.ptr[0].as<bool>();
+            uint64_t count = client_value.via.array.ptr[1].as<uint64_t>();
+            for (uint64_t task_number = 0; task_number < count; ++task_number) {
+                size_t key_index = 2 + task_number * 2;
+                size_t task_index = key_index + 1;
+                if (task_index >= client_value.via.array.size) {
+                    return tl::unexpected(DecodeError(
+                        "deserialize local_disk_segments offloading_objects "
+                        "out of bounds"));
+                }
+                const auto& key_object = client_value.via.array.ptr[key_index];
+                if (key_object.type != msgpack::type::STR) {
+                    return tl::unexpected(DecodeError(
+                        "deserialize local_disk_segments offloading key is "
+                        "not string"));
+                }
+                std::string encoded_key(key_object.via.str.ptr,
+                                        key_object.via.str.size);
+                const auto& task_object =
+                    client_value.via.array.ptr[task_index];
+                OffloadTaskItem task;
+                if (task_object.type == msgpack::type::ARRAY &&
+                    task_object.via.array.size == 3) {
+                    if (task_object.via.array.ptr[0].type !=
+                            msgpack::type::STR ||
+                        task_object.via.array.ptr[1].type !=
+                            msgpack::type::STR ||
+                        !IsMsgpackInteger(task_object.via.array.ptr[2])) {
+                        return tl::unexpected(DecodeError(
+                            "deserialize local_disk_segments offloading task "
+                            "is invalid"));
+                    }
+                    task.tenant_id =
+                        task_object.via.array.ptr[0].as<std::string>();
+                    task.key = task_object.via.array.ptr[1].as<std::string>();
+                    task.size = task_object.via.array.ptr[2].as<int64_t>();
+                } else {
+                    if (!IsMsgpackInteger(task_object)) {
+                        return tl::unexpected(DecodeError(
+                            "deserialize local_disk_segments legacy "
+                            "offloading size is not integer"));
+                    }
+                    auto [tenant_id, object_key] =
+                        TenantId::ParseScopedKey(encoded_key);
+                    task = OffloadTaskItem{.tenant_id = tenant_id.value(),
+                                           .key = std::move(object_key),
+                                           .size = task_object.as<int64_t>()};
+                }
+                client.pending_offloads.insert_or_assign(std::move(encoded_key),
+                                                         std::move(task));
+            }
+
+            const size_t capacity_index = 2 + count * 2;
+            if (client_value.via.array.size > capacity_index &&
+                IsMsgpackInteger(client_value.via.array.ptr[capacity_index])) {
+                client.total_capacity_bytes =
+                    client_value.via.array.ptr[capacity_index].as<int64_t>();
+            }
+            state.insert_or_assign(client_id, std::move(client));
+        }
+    } catch (const msgpack::type_error& error) {
+        return tl::unexpected(DecodeError(fmt::format(
+            "deserialize local_disk_segments type error: {}", error.what())));
+    } catch (const std::exception& error) {
+        return tl::unexpected(DecodeError(fmt::format(
+            "deserialize local_disk_segments failed: {}", error.what())));
+    }
+    return state;
+}
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/src/ha/snapshot/master_snapshot_codec.cpp b/mooncake-store/src/ha/snapshot/master_snapshot_codec.cpp
index 96e7da5c02..b233d39def 100644
--- a/mooncake-store/src/ha/snapshot/master_snapshot_codec.cpp
+++ b/mooncake-store/src/ha/snapshot/master_snapshot_codec.cpp
@@ -2,6 +2,7 @@
 
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
 #include "master_service.h"
@@ -30,8 +31,9 @@ MasterSnapshotCodec::Encode(MasterSnapshotStateView& state_view) const {
     payloads.metadata = std::move(metadata_result.value());
 
     // 2. Encode segments (memory segments + NoF segments)
-    auto segments_result = EncodeSegments(state_view.segment_manager,
-                                          state_view.nof_segment_manager);
+    auto segments_result =
+        EncodeSegments(state_view.segment_manager, state_view.local_ssd_manager,
+                       state_view.nof_segment_manager);
     if (!segments_result) {
         return tl::make_unexpected(segments_result.error());
     }
@@ -118,19 +120,23 @@ tl::expected<void, SerializationError> MasterSnapshotCodec::DecodeMetadata(
 
 tl::expected<std::vector<uint8_t>, SerializationError>
 MasterSnapshotCodec::EncodeSegments(
-    SegmentManager& segment_manager,
+    SegmentManager& segment_manager, LocalSsdManager& local_ssd_manager,
     NoFSegmentManager& nof_segment_manager) const {
-    // Use the existing SegmentSerializer which only handles SegmentManager
     // Note: NoFSegmentManager is not currently serialized in snapshots
     SegmentSerializer serializer(&segment_manager);
-    return serializer.Serialize();
+    return serializer.Serialize(local_ssd_manager.ExportPersistedState());
 }
 
 tl::expected<void, SerializationError> MasterSnapshotCodec::DecodeSegments(
     MasterService* master_service, const std::vector<uint8_t>& data) const {
-    // Access the segment managers from MasterService
     SegmentSerializer serializer(&master_service->segment_manager_);
-    return serializer.Deserialize(data);
+    auto local_ssd_state = serializer.Deserialize(data);
+    if (!local_ssd_state) {
+        return tl::unexpected(local_ssd_state.error());
+    }
+    master_service->local_ssd_manager_.RestorePersistedState(
+        std::move(*local_ssd_state));
+    return {};
 }
 
 tl::expected<std::vector<uint8_t>, SerializationError>
diff --git a/mooncake-store/src/ha/snapshot/object/backends/local/local_file_snapshot_object_store.cpp b/mooncake-store/src/ha/snapshot/object/backends/local/local_file_snapshot_object_store.cpp
index 6a85785789..5ac980aa58 100644
--- a/mooncake-store/src/ha/snapshot/object/backends/local/local_file_snapshot_object_store.cpp
+++ b/mooncake-store/src/ha/snapshot/object/backends/local/local_file_snapshot_object_store.cpp
@@ -1,52 +1,19 @@
 #include "ha/snapshot/object/backends/local/local_file_snapshot_object_store.h"
 
 #include <algorithm>
-#include <cstdlib>
 #include <fstream>
 #include <sstream>
 
 #include <fmt/format.h>
 #include <glog/logging.h>
 
-namespace mooncake {
-
-namespace {
-
-constexpr const char* kEnvLocalPath = "MOONCAKE_SNAPSHOT_LOCAL_PATH";
+#include "config/local_file_snapshot_config.h"
 
-}  // namespace
-
-LocalFileSnapshotObjectStore::LocalFileSnapshotObjectStore() {
-    const char* env_path = std::getenv(kEnvLocalPath);
-    if (!env_path || !*env_path) {
-        throw std::runtime_error(
-            "MOONCAKE_SNAPSHOT_LOCAL_PATH environment variable is not set. "
-            "Please set it to a persistent directory path for snapshot "
-            "storage. Example: export "
-            "MOONCAKE_SNAPSHOT_LOCAL_PATH=/data/mooncake_snapshots");
-    }
-
-    std::error_code ec;
-    fs::create_directories(env_path, ec);
-    if (ec) {
-        throw std::runtime_error(
-            fmt::format("Failed to create base_path directory '{}': {}",
-                        env_path, ec.message()));
-    }
+namespace mooncake {
 
-    base_path_ = fs::canonical(env_path, ec);
-    if (ec) {
-        throw std::runtime_error(fmt::format(
-            "Failed to resolve base_path '{}': {}", env_path, ec.message()));
-    }
-    if (!fs::is_directory(base_path_)) {
-        throw std::runtime_error(fmt::format(
-            "base_path '{}' is not a directory", base_path_.string()));
-    }
-
-    LOG(INFO) << "LocalFileSnapshotObjectStore initialized with path: "
-              << base_path_;
-}
+LocalFileSnapshotObjectStore::LocalFileSnapshotObjectStore()
+    : LocalFileSnapshotObjectStore(
+          LocalFileSnapshotConfig::FromEnvironment().base_path) {}
 
 LocalFileSnapshotObjectStore::LocalFileSnapshotObjectStore(
     const std::string& base_path) {
@@ -324,6 +291,30 @@ LocalFileSnapshotObjectStore::ListObjectsWithPrefix(
     return {};
 }
 
+tl::expected<SnapshotObjectInspection, std::string>
+LocalFileSnapshotObjectStore::InspectObject(const std::string& key) {
+    fs::path full_path = KeyToPath(key);
+    if (!IsPathWithinBase(full_path)) {
+        return tl::make_unexpected(
+            fmt::format("Security error: Path {} is outside base directory {}",
+                        full_path.string(), base_path_.string()));
+    }
+    if (!fs::exists(full_path)) {
+        return tl::make_unexpected(
+            fmt::format("File not found: {}", full_path.string()));
+    }
+
+    std::error_code ec;
+    const auto size = fs::file_size(full_path, ec);
+    if (ec) {
+        return tl::make_unexpected(
+            fmt::format("Failed to get file size: {}, error: {}",
+                        full_path.string(), ec.message()));
+    }
+    return SnapshotObjectInspection{.stored_size = size,
+                                    .crc32c = std::nullopt};
+}
+
 bool LocalFileSnapshotObjectStore::IsNotFoundError(
     const std::string& error) const {
     return error.starts_with("File not found:");
diff --git a/mooncake-store/src/ha/snapshot/object/backends/s3/s3_snapshot_object_store.cpp b/mooncake-store/src/ha/snapshot/object/backends/s3/s3_snapshot_object_store.cpp
index 1772e3a25c..b8a39bcac4 100644
--- a/mooncake-store/src/ha/snapshot/object/backends/s3/s3_snapshot_object_store.cpp
+++ b/mooncake-store/src/ha/snapshot/object/backends/s3/s3_snapshot_object_store.cpp
@@ -8,7 +8,7 @@
 
 #include <glog/logging.h>
 
-#include "utils/s3_helper.h"
+#include "common/s3_helper.h"
 
 namespace mooncake {
 
@@ -81,6 +81,17 @@ tl::expected<void, std::string> S3SnapshotObjectStore::ListObjectsWithPrefix(
     return impl_->s3_helper_.ListObjectsWithPrefix(prefix, object_keys);
 }
 
+tl::expected<SnapshotObjectInspection, std::string>
+S3SnapshotObjectStore::InspectObject(const std::string& key) {
+    SnapshotObjectInspection inspection;
+    auto result = impl_->s3_helper_.InspectObject(key, inspection.stored_size,
+                                                  inspection.crc32c);
+    if (!result) {
+        return tl::make_unexpected(std::move(result.error()));
+    }
+    return inspection;
+}
+
 bool S3SnapshotObjectStore::IsNotFoundError(const std::string& error) const {
     return ContainsAsciiInsensitive(error, "nosuchkey") ||
            ContainsAsciiInsensitive(error, "not found") ||
diff --git a/mooncake-store/src/ha/snapshot/snapshot_maintenance_lease.cpp b/mooncake-store/src/ha/snapshot/snapshot_maintenance_lease.cpp
new file mode 100644
index 0000000000..6515ad26d5
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/snapshot_maintenance_lease.cpp
@@ -0,0 +1,127 @@
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+
+#include <utility>
+
+#include "etcd_helper.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+
+namespace mooncake {
+
+SnapshotMaintenanceLease::SnapshotMaintenanceLease(std::string cluster_id)
+    : cluster_id_(std::move(cluster_id)),
+      lock_key_(ha::BuildBatchOpLogSnapshotMaintenanceKey(cluster_id_)) {}
+
+SnapshotMaintenanceLease::SnapshotMaintenanceLease(
+    std::string cluster_id, std::string owner_token, bool testing,
+    EtcdRevisionId create_revision)
+    : cluster_id_(std::move(cluster_id)),
+      lock_key_(ha::BuildBatchOpLogSnapshotMaintenanceKey(cluster_id_)),
+      owner_token_(std::move(owner_token)),
+      lock_create_revision_(create_revision),
+      testing_(testing),
+      lock_created_(testing) {}
+
+SnapshotMaintenanceLease::~SnapshotMaintenanceLease() { (void)Release(); }
+
+std::unique_ptr<SnapshotMaintenanceLease>
+SnapshotMaintenanceLease::MakeForTesting(std::string cluster_id,
+                                         std::string owner_token,
+                                         EtcdRevisionId create_revision) {
+    return std::unique_ptr<SnapshotMaintenanceLease>(
+        new SnapshotMaintenanceLease(std::move(cluster_id),
+                                     std::move(owner_token), true,
+                                     create_revision));
+}
+
+ErrorCode SnapshotMaintenanceLease::Acquire() {
+    if (testing_) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (lock_key_.empty()) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (lock_created_ || session_handle_ != 0) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+    }
+
+    int64_t session_handle = 0;
+    EtcdLeaseId lease_id = 0;
+    EtcdRevisionId create_revision = 0;
+    ErrorCode err = EtcdHelper::AcquireMaintenanceSession(
+        lock_key_, kTtlSeconds, session_handle, lease_id, create_revision);
+    if (err != ErrorCode::OK) {
+        return err;
+    }
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        session_handle_ = session_handle;
+        lease_id_ = lease_id;
+        lock_create_revision_ = create_revision;
+        owner_token_ = std::to_string(lease_id);
+        lock_created_ = true;
+    }
+    if (!IsHeld()) {
+        (void)Release();
+        return ErrorCode::ETCD_OPERATION_ERROR;
+    }
+    return ErrorCode::OK;
+}
+
+bool SnapshotMaintenanceLease::IsHeld() const {
+    if (testing_) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        return lock_created_ && !owner_token_.empty();
+    }
+    int64_t session_handle = 0;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (!lock_created_) {
+            return false;
+        }
+        session_handle = session_handle_;
+    }
+    auto alive = EtcdHelper::MaintenanceSessionAlive(session_handle);
+    return alive && *alive;
+}
+
+EtcdLeaseId SnapshotMaintenanceLease::lease_id() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return lease_id_;
+}
+
+std::string SnapshotMaintenanceLease::owner_token() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return owner_token_;
+}
+
+EtcdRevisionId SnapshotMaintenanceLease::lock_create_revision() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return lock_create_revision_;
+}
+
+ErrorCode SnapshotMaintenanceLease::Release() {
+    if (testing_) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        lock_created_ = false;
+        return ErrorCode::OK;
+    }
+    int64_t session_handle = 0;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        session_handle = session_handle_;
+        session_handle_ = 0;
+        lease_id_ = 0;
+        lock_create_revision_ = 0;
+        owner_token_.clear();
+        lock_created_ = false;
+    }
+    if (session_handle == 0) {
+        return ErrorCode::OK;
+    }
+    return EtcdHelper::CloseMaintenanceSession(session_handle);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha/snapshot/store_resource_snapshot_codec.cpp b/mooncake-store/src/ha/snapshot/store_resource_snapshot_codec.cpp
new file mode 100644
index 0000000000..1ff6087ca7
--- /dev/null
+++ b/mooncake-store/src/ha/snapshot/store_resource_snapshot_codec.cpp
@@ -0,0 +1,388 @@
+#include "ha/snapshot/store_resource_snapshot_codec.h"
+
+#include <algorithm>
+#include <limits>
+#include <map>
+#include <optional>
+#include <set>
+#include <string>
+#include <unordered_map>
+#include <utility>
+
+#include <boost/functional/hash.hpp>
+#include <msgpack.hpp>
+
+#include "ha/snapshot/allocator_snapshot_codec.h"
+#include "ha/snapshot/local_ssd_codec.h"
+#include "segment/snapshot.h"
+#include "serialize/serializer.h"
+#include "common/zstd_util.h"
+
+namespace mooncake::ha {
+namespace {
+
+struct DecodedMountedRegion final {
+    MountedRegion mounted;
+    std::optional<OffsetBufferAllocatorSnapshot> allocator;
+};
+
+tl::expected<void, SerializationError> EncodeMountedRegion(
+    const MountedRegion& mounted,
+    const OffsetBufferAllocatorSnapshot& allocator, MsgpackPacker& packer) {
+    // Preserved wire shape: [segment_id, segment_name, segment_base,
+    // segment_size, te_endpoint, status, has_allocator, allocator, host_id].
+    packer.pack_array(9);
+    packer.pack(UuidToString(mounted.segment.id));
+    packer.pack(mounted.segment.name);
+    packer.pack(static_cast<uint64_t>(mounted.segment.base));
+    packer.pack(static_cast<uint64_t>(mounted.segment.size));
+    packer.pack(mounted.segment.te_endpoint);
+    packer.pack(static_cast<int16_t>(mounted.status));
+    packer.pack(true);
+    auto encoded = AllocatorSnapshotCodec::Encode(allocator, packer);
+    if (!encoded) {
+        return tl::make_unexpected(encoded.error());
+    }
+    packer.pack(mounted.segment.host_id);
+    return {};
+}
+
+tl::expected<DecodedMountedRegion, SerializationError> DecodeMountedRegion(
+    const msgpack::object& object) {
+    if (object.type != msgpack::type::ARRAY || object.via.array.size < 8) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            "snapshot MountedRegion is not an array with at least 8 fields"));
+    }
+
+    try {
+        const auto* array = object.via.array.ptr;
+        UUID id;
+        if (!StringToUuid(array[0].as<std::string>(), id)) {
+            return tl::make_unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "snapshot MountedRegion has invalid UUID"));
+        }
+
+        DecodedMountedRegion decoded;
+        decoded.mounted.segment.id = id;
+        decoded.mounted.segment.name = array[1].as<std::string>();
+        decoded.mounted.segment.base =
+            static_cast<uintptr_t>(array[2].as<uint64_t>());
+        decoded.mounted.segment.size =
+            static_cast<size_t>(array[3].as<uint64_t>());
+        decoded.mounted.segment.te_endpoint = array[4].as<std::string>();
+        decoded.mounted.status =
+            static_cast<SegmentStatus>(array[5].as<int16_t>());
+        if (!IsKnownSegmentStatus(decoded.mounted.status)) {
+            return tl::make_unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                "snapshot MountedRegion has invalid status"));
+        }
+        decoded.mounted.kind = RegionKind::HOST_MEMORY;
+
+        if (array[6].as<bool>()) {
+            auto allocator = AllocatorSnapshotCodec::Decode(array[7]);
+            if (!allocator) {
+                return tl::make_unexpected(allocator.error());
+            }
+            decoded.allocator = std::move(*allocator);
+        }
+        if (object.via.array.size >= 9) {
+            decoded.mounted.segment.host_id = array[8].as<std::string>();
+        }
+        return decoded;
+    } catch (const std::exception& error) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            std::string("decode MountedRegion failed: ") + error.what()));
+    }
+}
+
+tl::expected<std::map<std::string, const msgpack::object*>, SerializationError>
+IndexFields(const msgpack::object& object) {
+    if (object.type != msgpack::type::MAP) {
+        return tl::make_unexpected(
+            SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                               "snapshot SegmentPool payload is not a map"));
+    }
+    std::map<std::string, const msgpack::object*> fields;
+    for (uint32_t i = 0; i < object.via.map.size; ++i) {
+        const auto& key = object.via.map.ptr[i].key;
+        if (key.type == msgpack::type::STR) {
+            fields.emplace(std::string(key.via.str.ptr, key.via.str.size),
+                           &object.via.map.ptr[i].val);
+        }
+    }
+    return fields;
+}
+
+}  // namespace
+
+tl::expected<std::vector<uint8_t>, SerializationError>
+StoreResourceSnapshotCodec::Encode(
+    const SegmentPoolSnapshot& snapshot,
+    const LocalSsdPersistedState& local_ssd_state) {
+    if (snapshot.memory_allocator_type != BufferAllocatorType::OFFSET) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::SERIALIZE_UNSUPPORTED,
+            "snapshot SegmentPool memory driver is not offset"));
+    }
+    msgpack::sbuffer buffer;
+    MsgpackPacker packer(&buffer);
+    packer.pack_map(5);
+
+    packer.pack("ma");
+    packer.pack(static_cast<int32_t>(snapshot.memory_allocator_type));
+
+    packer.pack("an");
+    packer.pack_array(snapshot.active_names.size());
+    for (const auto& name : snapshot.active_names) {
+        packer.pack(name);
+    }
+
+    packer.pack("ms");
+    packer.pack_map(snapshot.regions.size());
+    for (const auto& region : snapshot.regions) {
+        packer.pack(UuidToString(region.mounted.segment.id));
+        auto encoded =
+            EncodeMountedRegion(region.mounted, region.allocator, packer);
+        if (!encoded) {
+            return tl::make_unexpected(encoded.error());
+        }
+    }
+
+    packer.pack("cs");
+    std::map<UUID, std::vector<UUID>> clients;
+    for (const auto& region : snapshot.regions) {
+        clients[region.mounted.client_id].push_back(region.mounted.segment.id);
+    }
+    packer.pack_map(clients.size());
+    for (const auto& [client, regions] : clients) {
+        packer.pack(UuidToString(client));
+        packer.pack_array(regions.size());
+        for (const auto& id : regions) {
+            packer.pack(UuidToString(id));
+        }
+    }
+
+    packer.pack("ld");
+    auto local_ssd = LocalSsdCodec::Encode(local_ssd_state, packer);
+    if (!local_ssd) {
+        return tl::make_unexpected(local_ssd.error());
+    }
+    return zstd_compress(reinterpret_cast<const uint8_t*>(buffer.data()),
+                         buffer.size(), 3);
+}
+
+tl::expected<StoreResourceSnapshot, SerializationError>
+StoreResourceSnapshotCodec::Decode(const std::vector<uint8_t>& data) {
+    std::vector<uint8_t> decompressed;
+    try {
+        decompressed = zstd_decompress(data);
+    } catch (const std::exception& error) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            std::string("decompress SegmentPool snapshot failed: ") +
+                error.what()));
+    }
+
+    msgpack::object_handle handle;
+    try {
+        handle =
+            msgpack::unpack(reinterpret_cast<const char*>(decompressed.data()),
+                            decompressed.size());
+    } catch (const std::exception& error) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            std::string("unpack SegmentPool snapshot failed: ") +
+                error.what()));
+    }
+    auto fields = IndexFields(handle.get());
+    if (!fields) {
+        return tl::make_unexpected(fields.error());
+    }
+
+    const auto local_ssd_field = fields->find("ld");
+    auto local_ssd = LocalSsdCodec::Decode(
+        local_ssd_field == fields->end() ? nullptr : local_ssd_field->second);
+    if (!local_ssd) {
+        return tl::make_unexpected(local_ssd.error());
+    }
+
+    const auto allocator_field = fields->find("ma");
+    if (allocator_field == fields->end() ||
+        allocator_field->second->type != msgpack::type::POSITIVE_INTEGER ||
+        allocator_field->second->via.u64 !=
+            static_cast<uint64_t>(BufferAllocatorType::OFFSET)) {
+        return tl::make_unexpected(
+            SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                               "snapshot SegmentPool allocator type mismatch"));
+    }
+
+    std::vector<std::string> active_names;
+    const auto names_field = fields->find("an");
+    if (names_field != fields->end()) {
+        if (names_field->second->type != msgpack::type::ARRAY) {
+            return tl::make_unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "snapshot active names is not an array"));
+        }
+        for (uint32_t i = 0; i < names_field->second->via.array.size; ++i) {
+            const auto& name = names_field->second->via.array.ptr[i];
+            if (name.type != msgpack::type::STR) {
+                return tl::make_unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "snapshot active name is not a string"));
+            }
+            active_names.emplace_back(name.via.str.ptr, name.via.str.size);
+        }
+    }
+
+    std::unordered_map<UUID, DecodedMountedRegion, boost::hash<UUID>> decoded;
+    const auto mounted_field = fields->find("ms");
+    if (mounted_field != fields->end()) {
+        if (mounted_field->second->type != msgpack::type::MAP) {
+            return tl::make_unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "snapshot mounted regions is not a map"));
+        }
+        for (uint32_t i = 0; i < mounted_field->second->via.map.size; ++i) {
+            const auto& item = mounted_field->second->via.map.ptr[i];
+            if (item.key.type != msgpack::type::STR) {
+                return tl::make_unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "snapshot region id is not a string"));
+            }
+            UUID id;
+            if (!StringToUuid(
+                    std::string(item.key.via.str.ptr, item.key.via.str.size),
+                    id)) {
+                return tl::make_unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "snapshot region id is invalid"));
+            }
+            auto region = DecodeMountedRegion(item.val);
+            if (!region || region->mounted.segment.id != id ||
+                !region->allocator) {
+                return tl::make_unexpected(
+                    region ? SerializationError(
+                                 ErrorCode::DESERIALIZE_FAIL,
+                                 "snapshot region id or allocator mismatch")
+                           : region.error());
+            }
+            const auto& segment = region->mounted.segment;
+            if (segment.name.empty() || segment.base == 0 ||
+                segment.size == 0 ||
+                segment.base >
+                    std::numeric_limits<uintptr_t>::max() - segment.size ||
+                region->allocator->segment_name != segment.name ||
+                region->allocator->transport_endpoint != segment.te_endpoint ||
+                region->allocator->base != segment.base ||
+                region->allocator->capacity != segment.size) {
+                return tl::make_unexpected(SerializationError(
+                    ErrorCode::DESERIALIZE_FAIL,
+                    "snapshot contains invalid adopted resource"));
+            }
+            if (!decoded.emplace(id, std::move(*region)).second) {
+                return tl::make_unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "snapshot contains duplicate region"));
+            }
+        }
+    }
+
+    std::set<UUID> owned_regions;
+    const auto clients_field = fields->find("cs");
+    if (clients_field != fields->end()) {
+        if (clients_field->second->type != msgpack::type::MAP) {
+            return tl::make_unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "snapshot client regions is not a map"));
+        }
+        for (uint32_t i = 0; i < clients_field->second->via.map.size; ++i) {
+            const auto& item = clients_field->second->via.map.ptr[i];
+            if (item.key.type != msgpack::type::STR ||
+                item.val.type != msgpack::type::ARRAY) {
+                return tl::make_unexpected(SerializationError(
+                    ErrorCode::DESERIALIZE_FAIL,
+                    "snapshot contains invalid client entry"));
+            }
+            UUID client;
+            if (!StringToUuid(
+                    std::string(item.key.via.str.ptr, item.key.via.str.size),
+                    client)) {
+                return tl::make_unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "snapshot contains invalid client id"));
+            }
+            for (uint32_t j = 0; j < item.val.via.array.size; ++j) {
+                const auto& id_object = item.val.via.array.ptr[j];
+                UUID id;
+                if (id_object.type != msgpack::type::STR ||
+                    !StringToUuid(std::string(id_object.via.str.ptr,
+                                              id_object.via.str.size),
+                                  id) ||
+                    !decoded.contains(id) || !owned_regions.insert(id).second) {
+                    return tl::make_unexpected(SerializationError(
+                        ErrorCode::DESERIALIZE_FAIL,
+                        "snapshot contains invalid region ownership"));
+                }
+                decoded.at(id).mounted.client_id = client;
+            }
+        }
+    }
+    if (owned_regions.size() != decoded.size()) {
+        return tl::make_unexpected(
+            SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                               "snapshot region is missing an owner"));
+    }
+
+    std::unordered_map<std::string, UUID> owner_by_name;
+    std::set<std::string> expected_active_names;
+    for (const auto& [_, region] : decoded) {
+        auto [owner, inserted] = owner_by_name.emplace(
+            region.mounted.segment.name, region.mounted.client_id);
+        if (!inserted && owner->second != region.mounted.client_id) {
+            return tl::make_unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                "snapshot logical region group has multiple owners"));
+        }
+        if (region.mounted.status == SegmentStatus::OK) {
+            expected_active_names.insert(region.mounted.segment.name);
+        }
+    }
+
+    std::set<std::string> decoded_active_names;
+    for (const auto& name : active_names) {
+        if (!decoded_active_names.insert(name).second ||
+            !expected_active_names.contains(name)) {
+            return tl::make_unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                "snapshot contains invalid active region names"));
+        }
+    }
+    if (decoded_active_names != expected_active_names) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            "snapshot active region names do not match mounted regions"));
+    }
+
+    StoreResourceSnapshot snapshot;
+    snapshot.segment_pool.active_names = std::move(active_names);
+    snapshot.segment_pool.regions.reserve(decoded.size());
+    for (auto& [id, region] : decoded) {
+        snapshot.segment_pool.regions.push_back(
+            {std::move(region.mounted), std::move(*region.allocator)});
+    }
+    // Match CaptureSnapshot's canonical ID order for stable re-encoding.
+    std::sort(snapshot.segment_pool.regions.begin(),
+              snapshot.segment_pool.regions.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.mounted.segment.id < rhs.mounted.segment.id;
+              });
+    snapshot.local_ssd = std::move(*local_ssd);
+    return snapshot;
+}
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/src/ha/standby_controller.cpp b/mooncake-store/src/ha/standby_controller.cpp
index 6576cd9a21..53e0f31ab4 100644
--- a/mooncake-store/src/ha/standby_controller.cpp
+++ b/mooncake-store/src/ha/standby_controller.cpp
@@ -7,7 +7,12 @@
 
 #include <glog/logging.h>
 
+#include "ha/kv/etcd_ha_kv_backend.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
 #include "ha/snapshot/catalog_backed_snapshot_provider.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
 #include "hot_standby_service.h"
 
 namespace mooncake {
@@ -29,7 +34,8 @@ std::unique_ptr<HotStandbyService> CreateStandbyService(
         .verification_interval_sec = 30,
         .max_replication_lag_entries = 1000,
         .enable_verification = false,
-        .enable_snapshot_bootstrap = config.enable_snapshot_restore,
+        .enable_snapshot_bootstrap =
+            config.enable_oplog_snapshot || config.enable_snapshot_restore,
         .enable_oplog_following = capabilities.has_oplog_following,
         .oplog_poll_interval_ms = config.oplog_poll_interval_ms,
         .batch_oplog_retry_timeout_sec = config.batch_oplog_retry_timeout_sec,
@@ -39,7 +45,8 @@ std::unique_ptr<HotStandbyService> CreateStandbyService(
 StandbyRuntimeCapabilities BuildStandbyRuntimeCapabilities(
     const HABackendSpec& spec, const MasterServiceSupervisorConfig& config) {
     StandbyRuntimeCapabilities capabilities;
-    capabilities.has_snapshot_bootstrap = config.enable_snapshot_restore;
+    capabilities.has_snapshot_bootstrap =
+        config.enable_oplog_snapshot || config.enable_snapshot_restore;
     capabilities.has_oplog_following =
         config.enable_oplog && spec.type == HABackendType::ETCD;
     return capabilities;
@@ -83,7 +90,7 @@ class NoopStandbyController final : public StandbyController {
 
     tl::expected<PromotionContext, ErrorCode> PromoteStandbyAndExport()
         override {
-        return tl::unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        return PromotionContext{};
     }
 
     void UpdateObservedLeader(const std::optional<MasterView>&) override {}
@@ -112,7 +119,7 @@ class CapabilityDrivenStandbyController final : public StandbyController {
           config_(config),
           capabilities_(BuildStandbyRuntimeCapabilities(spec, config)),
           standby_service_(CreateStandbyService(config, capabilities_)) {
-        if (capabilities_.has_snapshot_bootstrap) {
+        if (config_.enable_snapshot_restore && !config_.enable_oplog_snapshot) {
             auto snapshot_provider =
                 CreateCatalogBackedSnapshotProvider(config_);
             if (!snapshot_provider) {
@@ -126,6 +133,47 @@ class CapabilityDrivenStandbyController final : public StandbyController {
             }
         }
 
+        if (config_.enable_oplog_snapshot) {
+            try {
+                if (!capabilities_.has_oplog_following ||
+                    config_.snapshot_chunk_object_count == 0) {
+                    throw std::invalid_argument(
+                        "batch snapshot requires etcd OpLog and positive chunk "
+                        "count");
+                }
+                batch_backend_ = std::make_unique<EtcdHaKvBackend>();
+                auto type = ParseSnapshotObjectStoreType(
+                    config_.snapshot_object_store_type);
+                snapshot_object_store_ = SnapshotObjectStore::Create(type);
+                const std::string snapshot_root =
+                    BuildBatchOpLogSnapshotRoot(config_.cluster_id);
+                if (snapshot_root.empty()) {
+                    throw std::invalid_argument(
+                        "batch OpLog snapshot requires a valid cluster_id");
+                }
+                standby_service_->SetBatchOpLogSnapshotProvider(
+                    std::make_unique<BatchOpLogSnapshotProvider>(
+                        config_.cluster_id, *batch_backend_,
+                        *snapshot_object_store_, snapshot_root));
+                batch_oplog_snapshot_coordinator_ =
+                    std::make_unique<BatchOpLogSnapshotCoordinator>(
+                        *standby_service_, *batch_backend_,
+                        *snapshot_object_store_, config_.cluster_id,
+                        BatchOpLogSnapshotCoordinatorConfig{
+                            .snapshot_interval_seconds =
+                                config_.snapshot_interval_seconds,
+                            .chunk_object_count =
+                                config_.snapshot_chunk_object_count,
+                            .snapshot_root = snapshot_root,
+                            .clock = {},
+                        });
+            } catch (const std::exception& e) {
+                throw std::runtime_error(
+                    std::string("Failed to initialize batch OpLog snapshot: ") +
+                    e.what());
+            }
+        }
+
         if (capabilities_.has_oplog_following) {
             oplog_connstring_ = config_.ha_backend_connstring.empty()
                                     ? config_.etcd_endpoints
@@ -147,6 +195,8 @@ class CapabilityDrivenStandbyController final : public StandbyController {
     ~CapabilityDrivenStandbyController() override {
         standby_service_->SetSyncStatusCallback({});
         standby_service_->Stop();
+        batch_oplog_snapshot_coordinator_.reset();
+        standby_service_.reset();
     }
 
     ErrorCode StartStandby(
@@ -187,12 +237,25 @@ class CapabilityDrivenStandbyController final : public StandbyController {
             }
         }
         if (err == ErrorCode::OK) {
+            if (batch_oplog_snapshot_coordinator_) {
+                try {
+                    batch_oplog_snapshot_coordinator_->Start();
+                } catch (const std::exception& error) {
+                    LOG(ERROR)
+                        << "Snapshot worker start failed: " << error.what();
+                    StopStandby();
+                    return ErrorCode::INTERNAL_ERROR;
+                }
+            }
             NotifyRuntimeStateIfChanged();
         }
         return err;
     }
 
     void StopStandby() override {
+        if (batch_oplog_snapshot_coordinator_) {
+            batch_oplog_snapshot_coordinator_->Stop();
+        }
         standby_service_->Stop();
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
@@ -220,6 +283,9 @@ class CapabilityDrivenStandbyController final : public StandbyController {
         if (err != ErrorCode::OK) {
             standby_service_->Stop();
         }
+        if (err == ErrorCode::OK && batch_oplog_snapshot_coordinator_) {
+            batch_oplog_snapshot_coordinator_->Stop();
+        }
 
         {
             std::lock_guard<std::mutex> lock(state_mutex_);
@@ -246,7 +312,40 @@ class CapabilityDrivenStandbyController final : public StandbyController {
             return tl::unexpected(promote_error);
         }
 
-        // Atomic promote + export (final catch-up happens inside)
+        if (standby_service_->IsBatchOpLogSnapshotMode()) {
+            auto handoff = standby_service_->PromoteAndDetachBatchOpLogStore();
+            if (!handoff) {
+                standby_service_->Stop();
+                {
+                    std::lock_guard<std::mutex> lock(state_mutex_);
+                    standby_running_ = false;
+                    last_standby_error_ = handoff.error();
+                }
+                NotifyRuntimeStateIfChanged();
+                return tl::unexpected(handoff.error());
+            }
+
+            {
+                std::lock_guard<std::mutex> lock(state_mutex_);
+                standby_running_ = false;
+                last_standby_error_ = ErrorCode::OK;
+            }
+            NotifyRuntimeStateIfChanged();
+
+            PromotionContext ctx;
+            ctx.applied_seq_id = handoff->applied_cursor.last_seq;
+            ctx.metadata_store = std::move(handoff->metadata_store);
+            ctx.segments = std::move(handoff->segments);
+            ctx.applied_cursor = handoff->applied_cursor;
+            ctx.producer_view_version = handoff->producer_view_version;
+            ctx.max_replica_id = handoff->max_replica_id;
+            if (batch_oplog_snapshot_coordinator_) {
+                batch_oplog_snapshot_coordinator_->Stop();
+            }
+            return ctx;
+        }
+
+        // Atomic legacy promote + export (final catch-up happens inside).
         StandbySnapshot snapshot;
         ErrorCode err = standby_service_->PromoteAndExportSnapshot(snapshot);
         if (err != ErrorCode::OK) {
@@ -334,6 +433,10 @@ class CapabilityDrivenStandbyController final : public StandbyController {
     MasterServiceSupervisorConfig config_;
     StandbyRuntimeCapabilities capabilities_;
     std::unique_ptr<HotStandbyService> standby_service_;
+    std::unique_ptr<HaKvBackend> batch_backend_;
+    std::unique_ptr<SnapshotObjectStore> snapshot_object_store_;
+    std::unique_ptr<BatchOpLogSnapshotCoordinator>
+        batch_oplog_snapshot_coordinator_;
     ErrorCode dependency_init_error_{ErrorCode::OK};
     std::string oplog_connstring_;
 
diff --git a/mooncake-store/src/ha/standby_metadata_store.cpp b/mooncake-store/src/ha/standby_metadata_store.cpp
new file mode 100644
index 0000000000..6fa23562ca
--- /dev/null
+++ b/mooncake-store/src/ha/standby_metadata_store.cpp
@@ -0,0 +1,176 @@
+#include "ha/standby_metadata_store.h"
+
+#include <algorithm>
+#include <limits>
+#include <unordered_set>
+
+namespace mooncake {
+
+bool StandbyMetadataStore::PutMetadata(const std::string& tenant_id,
+                                       const std::string& key,
+                                       const StandbyObjectMetadata& metadata) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    store_[NormalizeTenantId(tenant_id)][key] = metadata;
+    return true;
+}
+
+bool StandbyMetadataStore::RestoreMetadata(
+    const std::string& tenant_id, const std::string& key,
+    const StandbyObjectMetadata& metadata) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return store_[NormalizeTenantId(tenant_id)].emplace(key, metadata).second;
+}
+
+bool StandbyMetadataStore::Put(const std::string& key,
+                               const std::string& payload) {
+    (void)payload;
+    return PutMetadata("default", key, StandbyObjectMetadata{});
+}
+
+std::optional<StandbyObjectMetadata> StandbyMetadataStore::GetMetadata(
+    const std::string& tenant_id, const std::string& key) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto tenant = store_.find(NormalizeTenantId(tenant_id));
+    if (tenant == store_.end()) {
+        return std::nullopt;
+    }
+    auto object = tenant->second.find(key);
+    return object == tenant->second.end()
+               ? std::nullopt
+               : std::optional<StandbyObjectMetadata>(object->second);
+}
+
+bool StandbyMetadataStore::Remove(const std::string& tenant_id,
+                                  const std::string& key) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto tenant = store_.find(NormalizeTenantId(tenant_id));
+    if (tenant == store_.end() || tenant->second.erase(key) == 0) {
+        return false;
+    }
+    if (tenant->second.empty()) {
+        store_.erase(tenant);
+    }
+    return true;
+}
+
+bool StandbyMetadataStore::Exists(const std::string& tenant_id,
+                                  const std::string& key) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto tenant = store_.find(NormalizeTenantId(tenant_id));
+    return tenant != store_.end() && tenant->second.contains(key);
+}
+
+size_t StandbyMetadataStore::GetKeyCountForTenant(
+    const std::string& tenant_id) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto tenant = store_.find(NormalizeTenantId(tenant_id));
+    return tenant == store_.end() ? 0 : tenant->second.size();
+}
+
+size_t StandbyMetadataStore::GetKeyCount() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    size_t count = 0;
+    for (const auto& [tenant_id, objects] : store_) {
+        (void)tenant_id;
+        count += objects.size();
+    }
+    return count;
+}
+
+void StandbyMetadataStore::Clear() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    store_.clear();
+}
+
+void StandbyMetadataStore::Snapshot(
+    std::vector<StandbyObjectEntry>& out) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    out.clear();
+    for (const auto& [tenant_id, objects] : store_) {
+        for (const auto& [key, metadata] : objects) {
+            out.push_back({tenant_id, key, metadata});
+        }
+    }
+}
+
+bool StandbyMetadataStore::ValidateReplicaIds(ReplicaID& max_replica_id) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    max_replica_id = 0;
+    for (const auto& [tenant_id, objects] : store_) {
+        (void)tenant_id;
+        for (const auto& [key, metadata] : objects) {
+            (void)key;
+            std::unordered_set<ReplicaID> object_ids;
+            for (const auto& replica : metadata.replicas) {
+                if (replica.id == 0 ||
+                    replica.id == std::numeric_limits<ReplicaID>::max() ||
+                    !object_ids.insert(replica.id).second) {
+                    return false;
+                }
+                max_replica_id = std::max(max_replica_id, replica.id);
+            }
+        }
+    }
+    return true;
+}
+
+bool StandbyMetadataStore::DrainChunk(size_t count,
+                                      std::vector<StandbyObjectEntry>& out) {
+    out.clear();
+    if (count == 0) {
+        return false;
+    }
+
+    std::lock_guard<std::mutex> lock(mutex_);
+    out.reserve(count);
+    while (!store_.empty() && out.size() < count) {
+        auto tenant = store_.begin();
+        auto object = tenant->second.extract(tenant->second.begin());
+        out.push_back({tenant->first, std::move(object.key()),
+                       std::move(object.mapped())});
+        if (tenant->second.empty()) {
+            store_.erase(tenant);
+        }
+    }
+    return true;
+}
+
+StandbyMetadataStore::SnapshotCursor
+StandbyMetadataStore::BeginSnapshotTraversal() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto tenant = store_.cbegin();
+    const bool done = tenant == store_.cend();
+    return SnapshotCursor(
+        this, tenant, store_.cend(),
+        done ? ObjectStore::const_iterator() : tenant->second.cbegin(), done);
+}
+
+bool StandbyMetadataStore::CopyNextSnapshotChunk(
+    size_t count, SnapshotCursor& cursor,
+    std::vector<StandbyObjectEntry>& out) const {
+    out.clear();
+    if (count == 0 || cursor.store_ != this) {
+        return false;
+    }
+
+    std::lock_guard<std::mutex> lock(mutex_);
+    out.reserve(count);
+    while (!cursor.done_ && out.size() < count) {
+        const auto& objects = cursor.tenant_->second;
+        while (cursor.object_ != objects.cend() && out.size() < count) {
+            out.push_back({cursor.tenant_->first, cursor.object_->first,
+                           cursor.object_->second});
+            ++cursor.object_;
+        }
+        if (cursor.object_ == objects.cend()) {
+            ++cursor.tenant_;
+            cursor.done_ = cursor.tenant_ == cursor.tenant_end_;
+            if (!cursor.done_) {
+                cursor.object_ = cursor.tenant_->second.cbegin();
+            }
+        }
+    }
+    return true;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/ha_metric_manager.cpp b/mooncake-store/src/ha_metric_manager.cpp
index ee18a5d414..040d0a376c 100644
--- a/mooncake-store/src/ha_metric_manager.cpp
+++ b/mooncake-store/src/ha_metric_manager.cpp
@@ -2,6 +2,8 @@
 
 #include <glog/logging.h>
 
+#include "standby_state_machine.h"
+
 #include <iomanip>
 #include <sstream>
 
@@ -13,6 +15,75 @@ HAMetricManager& HAMetricManager::instance() {
     return static_instance;
 }
 
+void HAMetricManager::reset_snapshot_runtime(bool enabled) {
+    std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+    const auto lease_lost = snapshot_runtime_.lease_lost_total;
+    const auto floor_advances = snapshot_runtime_.floor_advances_total;
+    snapshot_runtime_ = {};
+    snapshot_runtime_.lease_lost_total = lease_lost;
+    snapshot_runtime_.floor_advances_total = floor_advances;
+    snapshot_runtime_.enabled = enabled;
+    snapshot_runtime_.skip_reason =
+        enabled ? SnapshotSkipReason::None : SnapshotSkipReason::Disabled;
+    // Event counters survive service replacement, like writer retry counters.
+}
+
+HAMetricManager::SnapshotRuntime HAMetricManager::get_snapshot_runtime() const {
+    std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+    return snapshot_runtime_;
+}
+
+HAMetricManager::SnapshotOperationStats HAMetricManager::get_snapshot_operation(
+    SnapshotOperation operation) const {
+    std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+    return snapshot_operations_[static_cast<size_t>(operation)];
+}
+
+void HAMetricManager::record_snapshot_skip(SnapshotSkipReason reason) {
+    std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+    if (!snapshot_runtime_.enabled) return;
+    snapshot_runtime_.skip_reason = reason;
+    if (reason != SnapshotSkipReason::None)
+        ++snapshot_skips_[static_cast<size_t>(reason)];
+}
+
+void HAMetricManager::record_snapshot_operation(
+    SnapshotOperation operation, int64_t error,
+    std::chrono::steady_clock::time_point start) {
+    const auto elapsed = std::chrono::duration_cast<std::chrono::microseconds>(
+                             std::chrono::steady_clock::now() - start)
+                             .count();
+    std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+    if (!snapshot_runtime_.enabled) return;
+    auto& stats = snapshot_operations_[static_cast<size_t>(operation)];
+    ++stats.total;
+    stats.errors += error != 0;
+    stats.elapsed_us += elapsed;
+}
+
+uint64_t HAMetricManager::activate_writer_runtime(
+    const WriterRuntimeSnapshot& snapshot) {
+    std::lock_guard<std::mutex> lock(writer_runtime_mutex_);
+    writer_retry_base_ = writer_runtime_.retry_count;
+    writer_runtime_ = snapshot;
+    writer_runtime_.retry_count += writer_retry_base_;
+    return ++writer_runtime_owner_;
+}
+
+void HAMetricManager::update_writer_runtime(
+    uint64_t owner, const WriterRuntimeSnapshot& snapshot) {
+    std::lock_guard<std::mutex> lock(writer_runtime_mutex_);
+    if (owner == 0 || owner != writer_runtime_owner_) return;
+    writer_runtime_ = snapshot;
+    writer_runtime_.retry_count += writer_retry_base_;
+}
+
+HAMetricManager::WriterRuntimeSnapshot HAMetricManager::get_writer_runtime()
+    const {
+    std::lock_guard<std::mutex> lock(writer_runtime_mutex_);
+    return writer_runtime_;
+}
+
 // --- Constructor ---
 HAMetricManager::HAMetricManager()
     // OpLog Sequence Gauges
@@ -423,6 +494,158 @@ std::string HAMetricManager::serialize_metrics() {
 #endif
     serialize_metric(state_transitions_total_);
 
+    {
+        SnapshotRuntime snapshot;
+        decltype(snapshot_operations_) operation_stats;
+        decltype(snapshot_skips_) skips;
+        {
+            std::lock_guard<std::mutex> lock(snapshot_runtime_mutex_);
+            snapshot = snapshot_runtime_;
+            operation_stats = snapshot_operations_;
+            skips = snapshot_skips_;
+        }
+        auto gauge = [&ss](const char* name, auto value) {
+            ss << "# TYPE ha_snapshot_" << name << " gauge\nha_snapshot_"
+               << name << " " << value << "\n";
+        };
+        gauge("enabled", snapshot.enabled ? 1 : 0);
+        const auto state = static_cast<StandbyState>(get_standby_state());
+        const bool active = state == StandbyState::CONNECTING ||
+                            state == StandbyState::SYNCING ||
+                            state == StandbyState::WATCHING ||
+                            state == StandbyState::RECOVERING ||
+                            state == StandbyState::RECONNECTING;
+        gauge("active", snapshot.enabled && active ? 1 : 0);
+        const auto now_ms =
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::system_clock::now().time_since_epoch())
+                .count();
+        const auto age = [now_ms](std::optional<int64_t> created) {
+            return created && now_ms > *created ? (now_ms - *created) / 1000
+                                                : 0;
+        };
+        gauge("latest_present",
+              snapshot.latest_created_at_ms.has_value() ? 1 : 0);
+        gauge("fallback_present",
+              snapshot.fallback_created_at_ms.has_value() ? 1 : 0);
+        gauge("latest_age_seconds", age(snapshot.latest_created_at_ms));
+        gauge("fallback_age_seconds", age(snapshot.fallback_created_at_ms));
+        gauge("count", snapshot.latest_created_at_ms.has_value() +
+                           snapshot.fallback_created_at_ms.has_value());
+        gauge("candidate_floor", snapshot.candidate_floor);
+        ss << "# TYPE ha_snapshot_floor_advances_total "
+              "counter\nha_snapshot_floor_advances_total "
+           << snapshot.floor_advances_total << "\n";
+        gauge("bytes", snapshot.snapshot_bytes);
+        gauge("chunk_bytes", snapshot.chunk_bytes);
+        gauge("chunk_count", snapshot.chunk_count);
+        gauge("capture_pause_us", snapshot.capture_pause_us);
+        gauge("suffix_batches", snapshot.suffix_batches);
+        gauge("catch_up_target_batch", snapshot.catch_up_target_batch);
+        gauge("catch_up_target_sequence", snapshot.catch_up_target_sequence);
+        gauge("durable_batch", snapshot.durable_batch);
+        gauge("applied_batch", snapshot.applied_batch);
+        gauge("latest_batch", snapshot.latest_batch);
+        gauge("fallback_batch", snapshot.fallback_batch);
+        gauge("compaction_floor", snapshot.compaction_floor);
+        gauge("gc_orphan_prefixes", snapshot.gc_orphan_prefixes);
+        gauge("gc_deleted_prefixes", snapshot.gc_deleted_prefixes);
+        gauge("uncompacted_batches",
+              snapshot.durable_batch > snapshot.compaction_floor
+                  ? snapshot.durable_batch - snapshot.compaction_floor
+                  : 0);
+        ss << "# TYPE ha_snapshot_lease_lost_total "
+              "counter\nha_snapshot_lease_lost_total "
+           << snapshot.lease_lost_total << "\n";
+        static constexpr const char* reasons[] = {
+            "none",         "disabled",
+            "interval",     "in_flight",
+            "stopped",      "promotion",
+            "no_new_batch", "catch_up",
+            "lease_busy",   "capture_unavailable",
+            "no_fallback",  "invalid_pair",
+            "floor_ahead"};
+        static_assert(std::size(reasons) ==
+                      static_cast<size_t>(SnapshotSkipReason::Count));
+        ss << "# TYPE ha_snapshot_skip_reason gauge\n";
+        for (size_t i = 0; i < std::size(reasons); ++i)
+            ss << "ha_snapshot_skip_reason{reason=\"" << reasons[i] << "\"} "
+               << (static_cast<size_t>(snapshot.skip_reason) == i ? 1 : 0)
+               << "\n";
+        ss << "# TYPE ha_snapshot_skips_total counter\n";
+        for (size_t i = 0; i < std::size(reasons); ++i)
+            ss << "ha_snapshot_skips_total{reason=\"" << reasons[i] << "\"} "
+               << skips[i] << "\n";
+        static constexpr const char* operations[] = {
+            "schedule", "upload", "bootstrap", "replay",
+            "publish",  "gc",     "prune",     "rebootstrap"};
+        static_assert(std::size(operations) ==
+                      static_cast<size_t>(SnapshotOperation::Count));
+        ss << "# TYPE ha_snapshot_operations_total counter\n"
+           << "# TYPE ha_snapshot_errors_total counter\n"
+           << "# TYPE ha_snapshot_duration_us_total counter\n";
+        for (size_t i = 0; i < std::size(operations); ++i) {
+            const auto& stats = operation_stats[i];
+            const std::string label =
+                std::string("{operation=\"") + operations[i] + "\"} ";
+            ss << "ha_snapshot_operations_total" << label << stats.total << "\n"
+               << "ha_snapshot_errors_total" << label << stats.errors << "\n"
+               << "ha_snapshot_duration_us_total" << label << stats.elapsed_us
+               << "\n";
+        }
+    }
+
+    const auto writer = get_writer_runtime();
+    ss << "# HELP ha_writer_accepting Whether the batch OpLog writer accepts "
+          "new entries\n"
+       << "# TYPE ha_writer_accepting gauge\n"
+       << "ha_writer_accepting " << (writer.accepting ? 1 : 0) << "\n"
+       << "# HELP ha_writer_retry_count Total writer retries\n"
+       << "# TYPE ha_writer_retry_count counter\n"
+       << "ha_writer_retry_count " << writer.retry_count << "\n"
+       << "# HELP ha_writer_retry_delay_ms Current writer retry delay\n"
+       << "# TYPE ha_writer_retry_delay_ms gauge\n"
+       << "ha_writer_retry_delay_ms " << writer.retry_delay_ms << "\n"
+       << "# HELP ha_writer_waiting_slots Current reserved writer slots\n"
+       << "# TYPE ha_writer_waiting_slots gauge\n"
+       << "ha_writer_waiting_slots " << writer.waiting_slots << "\n"
+       << "# HELP ha_writer_committed_queue_depth Committed writer queue "
+          "depth\n"
+       << "# TYPE ha_writer_committed_queue_depth gauge\n"
+       << "ha_writer_committed_queue_depth " << writer.committed_queue_depth
+       << "\n"
+       << "# HELP ha_writer_callback_queue_depth Callback queue depth\n"
+       << "# TYPE ha_writer_callback_queue_depth gauge\n"
+       << "ha_writer_callback_queue_depth " << writer.callback_queue_depth
+       << "\n"
+       << "# HELP ha_writer_last_error Last writer error code\n"
+       << "# TYPE ha_writer_last_error gauge\n"
+       << "ha_writer_last_error " << writer.last_error << "\n"
+       << "# HELP ha_writer_durable_batch_id Last durable batch ID\n"
+       << "# TYPE ha_writer_durable_batch_id gauge\n"
+       << "ha_writer_durable_batch_id " << writer.durable_batch_id << "\n"
+       << "# HELP ha_writer_durable_sequence Last durable sequence\n"
+       << "# TYPE ha_writer_durable_sequence gauge\n"
+       << "ha_writer_durable_sequence " << writer.durable_sequence << "\n"
+       << "# HELP ha_writer_stuck_first_sequence First sequence of the "
+          "in-flight batch awaiting durability; 0 when absent, not a timeout "
+          "indicator\n"
+       << "# TYPE ha_writer_stuck_first_sequence gauge\n"
+       << "ha_writer_stuck_first_sequence "
+       << (writer.stuck_range ? writer.stuck_range->first : 0) << "\n"
+       << "# HELP ha_writer_stuck_last_sequence Last sequence of the "
+          "in-flight batch awaiting durability; 0 when absent, not a timeout "
+          "indicator\n"
+       << "# TYPE ha_writer_stuck_last_sequence gauge\n"
+       << "ha_writer_stuck_last_sequence "
+       << (writer.stuck_range ? writer.stuck_range->second : 0) << "\n";
+    if (!writer.terminal_reason.empty()) {
+        ss << "# HELP ha_writer_terminal_reason Current terminal reason\n"
+           << "# TYPE ha_writer_terminal_reason gauge\n"
+           << "ha_writer_terminal_reason{reason=\"" << writer.terminal_reason
+           << "\"} 1\n";
+    }
+
     // Histograms
     serialize_metric(oplog_etcd_write_latency_us_);
     serialize_metric(oplog_apply_latency_us_);
@@ -452,6 +675,23 @@ std::string HAMetricManager::get_summary_string() {
     ss << ", etcd_fail=" << get_oplog_etcd_write_failures_total();
     ss << ", watch_disconn=" << get_oplog_watch_disconnections_total();
     ss << ", state=" << get_standby_state();
+    const auto writer = get_writer_runtime();
+    ss << ", writer_accepting=" << (writer.accepting ? "true" : "false")
+       << ", writer_retry_count=" << writer.retry_count
+       << ", writer_retry_delay_ms=" << writer.retry_delay_ms
+       << ", writer_waiting_slots=" << writer.waiting_slots
+       << ", writer_committed_queue=" << writer.committed_queue_depth
+       << ", writer_callback_queue=" << writer.callback_queue_depth
+       << ", writer_durable_batch=" << writer.durable_batch_id
+       << ", writer_durable_seq=" << writer.durable_sequence
+       << ", writer_last_error=" << writer.last_error;
+    if (!writer.terminal_reason.empty()) {
+        ss << ", writer_terminal_reason=" << writer.terminal_reason;
+    }
+    if (writer.stuck_range) {
+        ss << ", writer_stuck_range=" << writer.stuck_range->first << "-"
+           << writer.stuck_range->second;
+    }
     return ss.str();
 }
 
diff --git a/mooncake-store/src/hf3fs/CMakeLists.txt b/mooncake-store/src/hf3fs/CMakeLists.txt
index 63ae07f4e2..72b1d522c2 100644
--- a/mooncake-store/src/hf3fs/CMakeLists.txt
+++ b/mooncake-store/src/hf3fs/CMakeLists.txt
@@ -1,8 +1,6 @@
-set(HF3FS_SOURCES
-    ${CMAKE_CURRENT_SOURCE_DIR}/hf3fs_file.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/hf3fs_resource_manager.cpp
-)
-
-include_directories("include")
+set(HF3FS_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/hf3fs_file.cpp
+                  ${CMAKE_CURRENT_SOURCE_DIR}/hf3fs_resource_manager.cpp)
 
-set(HF3FS_SOURCES ${HF3FS_SOURCES} PARENT_SCOPE)
\ No newline at end of file
+set(HF3FS_SOURCES
+    ${HF3FS_SOURCES}
+    PARENT_SCOPE)
diff --git a/mooncake-store/src/hf3fs/README.md b/mooncake-store/src/hf3fs/README.md
index a542b05a9c..cf90411749 100644
--- a/mooncake-store/src/hf3fs/README.md
+++ b/mooncake-store/src/hf3fs/README.md
@@ -1,43 +1,70 @@
-# Mooncake HF3FS Plugin
+# Mooncake HF3FS USRBIO Adapter
 
-This plugin implements 3FS native API (USRBIO) as a high-performance storage backend for Mooncake.
+> **Work in progress / experimental.** Descriptor-based DFS and this HF3FS
+> adapter are intended for development and evaluation only. They are not
+> production-ready or covered by Mooncake Store's general fault-tolerance, HA
+> continuity, durability, or multi-tenant guarantees.
+
+This adapter implements the HF3FS native USRBIO data plane for Mooncake Store's
+descriptor-based DFS replicas. It is selected explicitly with
+`MOONCAKE_DFS_FS_ADAPTER=hf3fs`; the legacy `--root_fs_dir` option does not
+enable it, and it does not automatically fall back to POSIX I/O.
 
 ## Prerequisites
 
-### 1. 3FS Installation
-- Build and install [3FS](https://github.com/deepseek-ai/3FS/)
-- Required library: `libhf3fs_api_shared.so` (Default location: `3FS_PATH/build/src/lib/api`)  
-  → Install to: `/usr/lib/`
-- Required header: `hf3fs_usrbio.h` (Default location: `3FS_PATH/src/lib/api`)  
-  → Install to: `/usr/include/`
+### 1. HF3FS installation
 
-### 2. Mooncake Configuration
-- Enable 3FS support during CMake configuration:
-```bash
+- Build and install [3FS](https://github.com/deepseek-ai/3FS/).
+- Install `libhf3fs_api_shared.so` from `3FS_PATH/build/src/lib/api` in a
+  library search path such as `/usr/lib/`.
+- Install `hf3fs_usrbio.h` from `3FS_PATH/src/lib/api` in an include search
+  path such as `/usr/include/`.
+
+### 2. Mooncake build
 
+Enable HF3FS support during CMake configuration:
+
+```bash
 cmake -DUSE_3FS=ON ...
 ```
 
-- Build and install Mooncake as usual.
+Then build and install Mooncake as usual.
 
 ## Usage
 
-### Basic Operation
-Start master server and specify the 3FS mount point:
+Configure the master with a shared HF3FS root and shard layout:
+
 ```bash
+export MOONCAKE_ENABLE_DFS=1
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
 
-./build/mooncake-store/src/mooncake_master \
-    --root_fs_dir=/path/to/3fs_mount_point 
+./build/mooncake-store/src/mooncake_master [other master arguments]
 ```
-### Important Notes
-1. The specified directory **must** be a 3FS mount point  
-   - If not, the system will automatically fall back to POSIX API
-2. For optimal performance:
-   - Ensure proper permissions on the 3FS mount point
-   - Verify 3FS service is running before execution
-
-### Example
+
+Every client that may read or write DFS replicas must initialize FileStorage's
+distributed backend with the same absolute root path and layout. Use the same
+root path string in every process:
+
 ```bash
+export MOONCAKE_OFFLOAD_ENABLED=true
+export MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR=distributed_storage_backend
+export MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/data/file_storage
+export MOONCAKE_MASTER=127.0.0.1:50051
+export MOONCAKE_DFS_ROOT_DIR=/mnt/3fs/mooncake
+export MOONCAKE_DFS_FS_ADAPTER=hf3fs
+export MOONCAKE_DFS_SHARD_COUNT=64
+export MOONCAKE_DFS_SHARD_CAPACITY=4294967296
+export MOONCAKE_DFS_ALIGNMENT=4096
+export MOONCAKE_DFS_SINGLE_TENANT=true
+
+python -m mooncake.mooncake_store_service
+```
 
-ROLE=prefill MOONCAKE_STORAGE_ROOT_DIR=/mnt/3fs python3 ./stress_cluster_benchmark.py
-```
\ No newline at end of file
+`MOONCAKE_OFFLOAD_FILE_STORAGE_PATH` must already be an absolute, writable,
+non-symlink directory. For the full configuration and current limitations, see
+the [DFS deployment documentation](../../../docs/source/deployment/mooncake-store-deployment-guide.md#dfs-storage).
diff --git a/mooncake-store/src/hot_standby_service.cpp b/mooncake-store/src/hot_standby_service.cpp
index c31ae1e2e4..a40fbae8ea 100644
--- a/mooncake-store/src/hot_standby_service.cpp
+++ b/mooncake-store/src/hot_standby_service.cpp
@@ -7,12 +7,15 @@
 #include <thread>
 
 #include "etcd_helper.h"
+#ifdef STORE_USE_ETCD
 #include "ha/kv/etcd_ha_kv_backend.h"
+#endif
 #include "ha_metric_manager.h"
 #include "ha/oplog/oplog_applier.h"
 #include "ha/oplog/oplog_batch_standby_reader.h"
 #include "ha/oplog/oplog_test_failpoint.h"
 #include "ha/oplog/oplog_types.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
 
 namespace mooncake {
 
@@ -46,98 +49,6 @@ HotStandbyService::HotStandbyService(const HotStandbyConfig& config)
     });
 }
 
-// StandbyMetadataStore implementation
-bool HotStandbyService::StandbyMetadataStore::PutMetadata(
-    const std::string& tenant_id, const std::string& key,
-    const StandbyObjectMetadata& metadata) {
-    const auto normalized = NormalizeTenantId(tenant_id);
-    std::lock_guard<std::mutex> lock(mutex_);
-    store_[normalized][key] = metadata;
-    VLOG(2) << "StandbyMetadataStore: stored metadata for tenant=" << normalized
-            << ", key=" << key << ", replicas=" << metadata.replicas.size()
-            << ", size=" << metadata.size;
-    return true;
-}
-
-bool HotStandbyService::StandbyMetadataStore::Put(const std::string& key,
-                                                  const std::string& payload) {
-    // Legacy interface - create empty metadata for default tenant
-    StandbyObjectMetadata metadata;
-    std::lock_guard<std::mutex> lock(mutex_);
-    store_["default"][key] = metadata;
-    return true;
-}
-
-std::optional<StandbyObjectMetadata>
-HotStandbyService::StandbyMetadataStore::GetMetadata(
-    const std::string& tenant_id, const std::string& key) const {
-    const auto normalized = NormalizeTenantId(tenant_id);
-    std::lock_guard<std::mutex> lock(mutex_);
-    auto tenant_it = store_.find(normalized);
-    if (tenant_it == store_.end()) return std::nullopt;
-    auto it = tenant_it->second.find(key);
-    if (it == tenant_it->second.end()) return std::nullopt;
-    return it->second;
-}
-
-bool HotStandbyService::StandbyMetadataStore::Remove(
-    const std::string& tenant_id, const std::string& key) {
-    const auto normalized = NormalizeTenantId(tenant_id);
-    std::lock_guard<std::mutex> lock(mutex_);
-    auto tenant_it = store_.find(normalized);
-    if (tenant_it == store_.end()) return false;
-    auto it = tenant_it->second.find(key);
-    if (it == tenant_it->second.end()) return false;
-    tenant_it->second.erase(it);
-    if (tenant_it->second.empty()) {
-        store_.erase(tenant_it);
-    }
-    return true;
-}
-
-bool HotStandbyService::StandbyMetadataStore::Exists(
-    const std::string& tenant_id, const std::string& key) const {
-    const auto normalized = NormalizeTenantId(tenant_id);
-    std::lock_guard<std::mutex> lock(mutex_);
-    auto tenant_it = store_.find(normalized);
-    if (tenant_it == store_.end()) return false;
-    return tenant_it->second.find(key) != tenant_it->second.end();
-}
-
-size_t HotStandbyService::StandbyMetadataStore::GetKeyCount() const {
-    std::lock_guard<std::mutex> lock(mutex_);
-    size_t total = 0;
-    for (const auto& [tid, tenant_map] : store_) {
-        total += tenant_map.size();
-    }
-    return total;
-}
-
-size_t HotStandbyService::StandbyMetadataStore::GetKeyCountForTenant(
-    const std::string& tenant_id) const {
-    const auto normalized = NormalizeTenantId(tenant_id);
-    std::lock_guard<std::mutex> lock(mutex_);
-    auto it = store_.find(normalized);
-    return it == store_.end() ? 0 : it->second.size();
-}
-
-void HotStandbyService::StandbyMetadataStore::Clear() {
-    std::lock_guard<std::mutex> lock(mutex_);
-    store_.clear();
-}
-
-void HotStandbyService::StandbyMetadataStore::Snapshot(
-    std::vector<StandbyObjectEntry>& out) const {
-    std::lock_guard<std::mutex> lock(mutex_);
-    out.clear();
-    for (const auto& [tenant_id, tenant_store] : store_) {
-        for (const auto& [key, metadata] : tenant_store) {
-            out.push_back(StandbyObjectEntry{NormalizeTenantId(tenant_id), key,
-                                             metadata});
-        }
-    }
-}
-
 HotStandbyService::~HotStandbyService() {
     // Always ensure threads are joined, regardless of state
     // This prevents std::terminate() if threads are still joinable
@@ -174,10 +85,20 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
     if (verification_thread_.joinable()) {
         verification_thread_.join();
     }
+    if (!metadata_store_) {
+        metadata_store_ = std::make_unique<StandbyMetadataStore>();
+    }
     batch_standby_reader_.reset();
     batch_standby_kv_backend_.reset();
+    batch_snapshot_baseline_.reset();
+    batch_snapshot_producer_view_version_ = 0;
+    {
+        std::lock_guard<std::mutex> cursor_lock(batch_snapshot_cursor_mutex_);
+        last_applied_batch_snapshot_prefix_.reset();
+    }
 
     last_error_.store(ErrorCode::OK, std::memory_order_release);
+    recovering_.store(false, std::memory_order_release);
 
     // Trigger START event
     auto result = state_machine_.ProcessEvent(StandbyEvent::START);
@@ -186,13 +107,18 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
         return ErrorCode::INTERNAL_ERROR;  // State machine rejected START
     }
 
+    HAMetricManager::instance().reset_snapshot_runtime(
+        config_.enable_snapshot_bootstrap &&
+        batch_oplog_snapshot_provider_ != nullptr);
     config_.primary_address = primary_address;
     oplog_endpoints_ = oplog_endpoints;
     cluster_id_ = cluster_id;
 
     if (config_.enable_oplog_following) {
-#ifdef STORE_USE_ETCD
+        // Injected test backends exercise the production Start/replication
+        // path without a live etcd cluster (and without STORE_USE_ETCD).
         if (!catch_up_batch_kv_backend_for_testing_) {
+#ifdef STORE_USE_ETCD
             ErrorCode err =
                 EtcdHelper::ConnectToEtcdStoreClient(oplog_endpoints.c_str());
             if (err != ErrorCode::OK) {
@@ -200,12 +126,14 @@ ErrorCode HotStandbyService::Start(const std::string& primary_address,
                 state_machine_.ProcessEvent(StandbyEvent::CONNECTION_FAILED);
                 return err;
             }
-        }
 #else
-        state_machine_.ProcessEvent(StandbyEvent::FATAL_ERROR);
-        LOG(ERROR) << "Batch-record OpLog requires STORE_USE_ETCD";
-        return ErrorCode::INTERNAL_ERROR;
+            // Without STORE_USE_ETCD, the following loop needs an injected
+            // test backend.
+            state_machine_.ProcessEvent(StandbyEvent::FATAL_ERROR);
+            LOG(ERROR) << "Batch-record OpLog requires STORE_USE_ETCD";
+            return ErrorCode::INTERNAL_ERROR;
 #endif
+        }
     }
 
     state_machine_.ProcessEvent(StandbyEvent::CONNECTED);
@@ -250,6 +178,9 @@ ErrorCode HotStandbyService::PrepareBootstrapBaselineLocked(
 
     oplog_applier_ =
         std::make_unique<OpLogApplier>(metadata_store_.get(), cluster_id_);
+    if (batch_oplog_snapshot_provider_ && config_.enable_snapshot_bootstrap) {
+        return LoadBatchOpLogSnapshotBaselineLocked(baseline_seq_id);
+    }
     if (!config_.enable_oplog_following) {
         if (metadata_store_ && metadata_store_->GetKeyCount() > 0) {
             LOG(INFO) << "Snapshot-only restart discards local metadata and "
@@ -324,8 +255,13 @@ ErrorCode HotStandbyService::LoadSnapshotBaselineLocked(
               << ", snapshot_seq_id=" << snapshot.snapshot_sequence_id
               << ", keys=" << snapshot.metadata.size();
     for (const auto& entry : snapshot.metadata) {
-        metadata_store_->PutMetadata(entry.tenant_id, entry.key,
-                                     entry.metadata);
+        if (!metadata_store_->RestoreMetadata(entry.tenant_id, entry.key,
+                                              entry.metadata)) {
+            LOG(ERROR) << "Snapshot baseline contains duplicate object: tenant="
+                       << entry.tenant_id << ", key=" << entry.key;
+            metadata_store_->Clear();
+            return ErrorCode::DESERIALIZE_FAIL;
+        }
     }
     // Load segment registry from snapshot
     if (oplog_applier_) {
@@ -336,16 +272,64 @@ ErrorCode HotStandbyService::LoadSnapshotBaselineLocked(
     return ErrorCode::OK;
 }
 
+ErrorCode HotStandbyService::LoadBatchOpLogSnapshotBaselineLocked(
+    uint64_t& baseline_seq_id) {
+    baseline_seq_id = 0;
+    auto temporary_metadata = std::make_unique<StandbyMetadataStore>();
+    auto temporary_applier =
+        std::make_unique<OpLogApplier>(temporary_metadata.get(), cluster_id_);
+    StandbySegmentRegistry temporary_registry;
+    auto restored = batch_oplog_snapshot_provider_->RestoreBaseline(
+        *temporary_metadata, temporary_registry, temporary_applier.get());
+    if (!restored) {
+        return restored.error();
+    }
+
+    LOG(INFO) << "Batch snapshot bootstrap complete: snapshot_seq="
+              << restored->last_included_seq
+              << " applied_seq=" << restored->last_applied_seq;
+    // The provider has already replayed the suffix in temporary state. The
+    // running reader/applier starts from that proven final sequence.
+    metadata_store_ = std::move(temporary_metadata);
+    oplog_applier_ = std::move(temporary_applier);
+    baseline_seq_id = oplog_applier_->GetExpectedSequenceId() - 1;
+    batch_snapshot_baseline_ =
+        DurablePrefix{.batch_id = restored->last_applied_batch_id,
+                      .last_seq = restored->last_applied_seq};
+    batch_snapshot_producer_view_version_ = restored->producer_view_version;
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.applied_batch = batch_snapshot_baseline_->batch_id;
+    });
+    applied_seq_id_.store(baseline_seq_id, std::memory_order_release);
+    primary_seq_id_.store(baseline_seq_id, std::memory_order_release);
+    return ErrorCode::OK;
+}
+
 ErrorCode HotStandbyService::StartOplogFollowingLocked(
     uint64_t baseline_seq_id) {
     (void)baseline_seq_id;
     if (catch_up_batch_kv_backend_for_testing_) {
         batch_standby_kv_backend_ = catch_up_batch_kv_backend_for_testing_;
     } else {
+#ifdef STORE_USE_ETCD
         batch_standby_kv_backend_ = std::make_shared<EtcdHaKvBackend>();
+#else
+        state_machine_.ProcessEvent(StandbyEvent::FATAL_ERROR);
+        LOG(ERROR) << "Batch-record OpLog requires STORE_USE_ETCD";
+        return ErrorCode::INTERNAL_ERROR;
+#endif
     }
     batch_standby_reader_ = std::make_unique<OpLogBatchStandbyReader>(
         cluster_id_, *batch_standby_kv_backend_, *oplog_applier_);
+    if (batch_snapshot_baseline_) {
+        const ErrorCode cursor_error =
+            batch_standby_reader_->SetBaselineCursor(*batch_snapshot_baseline_);
+        if (cursor_error != ErrorCode::OK) {
+            return cursor_error;
+        }
+        std::lock_guard<std::mutex> cursor_lock(batch_snapshot_cursor_mutex_);
+        last_applied_batch_snapshot_prefix_ = *batch_snapshot_baseline_;
+    }
 
     state_machine_.ProcessEvent(StandbyEvent::SYNC_COMPLETE);
     replication_loop_running_.store(true, std::memory_order_release);
@@ -395,6 +379,7 @@ void HotStandbyService::SetCatchUpBatchKvBackendForTesting(
 }
 
 void HotStandbyService::StopReplicationLoop() {
+    CancelSnapshotCapture();
     replication_loop_running_.store(false, std::memory_order_release);
     replication_loop_cv_.notify_all();
     if (replication_thread_.joinable()) {
@@ -411,6 +396,9 @@ void HotStandbyService::Stop() {
         return;
     }
 
+    if (current_state != StandbyState::PROMOTED) {
+        NotifySnapshotStop();
+    }
     state_machine_.ProcessEvent(StandbyEvent::STOP);
     StopReplicationLoop();
 
@@ -423,19 +411,62 @@ void HotStandbyService::Stop() {
               << StandbyStateToString(GetState());
 }
 
+std::optional<DurablePrefix>
+HotStandbyService::GetLastAppliedBatchOpLogSnapshotPrefix() const {
+    std::lock_guard<std::mutex> lock(batch_snapshot_cursor_mutex_);
+    return last_applied_batch_snapshot_prefix_;
+}
+
+void HotStandbyService::CancelBatchOpLogSnapshotCapture() {
+    CancelSnapshotCapture();
+}
+
+void HotStandbyService::SetBatchOpLogSnapshotCaptureReleasedCallback(
+    SnapshotLifecycleCallback callback) {
+    std::lock_guard<std::mutex> lock(snapshot_lifecycle_callback_mutex_);
+    snapshot_capture_released_callback_ = std::move(callback);
+}
+
+void HotStandbyService::SetBatchOpLogSnapshotPromotionCallback(
+    SnapshotLifecycleCallback callback) {
+    std::lock_guard<std::mutex> lock(snapshot_lifecycle_callback_mutex_);
+    snapshot_promotion_callback_ = std::move(callback);
+}
+
+void HotStandbyService::SetBatchOpLogSnapshotStopCallback(
+    SnapshotLifecycleCallback callback) {
+    std::lock_guard<std::mutex> lock(snapshot_lifecycle_callback_mutex_);
+    snapshot_stop_callback_ = std::move(callback);
+}
+
+void HotStandbyService::NotifySnapshotPromotion() {
+    SnapshotLifecycleCallback callback;
+    {
+        std::lock_guard<std::mutex> lock(snapshot_lifecycle_callback_mutex_);
+        callback = snapshot_promotion_callback_;
+    }
+    if (callback) {
+        callback();
+    }
+}
+
+void HotStandbyService::NotifySnapshotStop() {
+    SnapshotLifecycleCallback callback;
+    {
+        std::lock_guard<std::mutex> lock(snapshot_lifecycle_callback_mutex_);
+        callback = snapshot_stop_callback_;
+    }
+    if (callback) {
+        callback();
+    }
+}
+
 StandbySyncStatus HotStandbyService::GetSyncStatus() const {
     StandbySyncStatus status;
 
-    // Get applied sequence ID from OpLogApplier
-    if (oplog_applier_) {
-        uint64_t expected = oplog_applier_->GetExpectedSequenceId();
-        status.applied_seq_id = (expected > 0) ? (expected - 1) : 0;
-        if (status.applied_seq_id == 0) {
-            status.applied_seq_id = applied_seq_id_.load();  // Fallback
-        }
-    } else {
-        status.applied_seq_id = applied_seq_id_.load();
-    }
+    // Callbacks can query status while mutex_ is held or state is swapped.
+    status.applied_seq_id = applied_seq_id_.load();
+    status.is_recovering = recovering_.load(std::memory_order_acquire);
 
     // Primary sequence ID (best-effort): updated by ReplicationLoop via etcd
     // `/latest`.
@@ -462,6 +493,9 @@ StandbySyncStatus HotStandbyService::GetSyncStatus() const {
 }
 
 bool HotStandbyService::IsReadyForPromotion() const {
+    if (recovering_.load(std::memory_order_acquire)) {
+        return false;
+    }
     // Use state machine to check if ready for promotion
     if (!state_machine_.IsReadyForPromotion()) {
         return false;
@@ -480,7 +514,7 @@ bool HotStandbyService::IsReadyForPromotion() const {
             << "will be synced after promotion.";
     }
 
-    // NOTE: unresolved-gap check is deferred to PromoteLockedInternal, which
+    // NOTE: unresolved-gap check is deferred to PreparePromotionLocked, which
     // runs gap resolution + final catch-up first and only rejects promotion
     // when gaps remain after both attempts. Checking here would return a
     // misleading UNAVAILABLE_IN_CURRENT_STATUS before gap resolution runs.
@@ -488,7 +522,7 @@ bool HotStandbyService::IsReadyForPromotion() const {
 }
 
 ErrorCode HotStandbyService::FinalCatchUpForPromotionLocked(
-    uint64_t current_applied_seq_id) {
+    uint64_t current_applied_seq_id, PromotionCatchUpPolicy policy) {
     (void)current_applied_seq_id;
     if (!config_.enable_oplog_following) {
         LOG(INFO) << "Promotion does not require final OpLog catch-up";
@@ -501,15 +535,20 @@ ErrorCode HotStandbyService::FinalCatchUpForPromotionLocked(
 
     if (catch_up_batch_kv_backend_for_testing_) {
         return FinalCatchUpBatchRecordsLocked(
-            *catch_up_batch_kv_backend_for_testing_);
+            *catch_up_batch_kv_backend_for_testing_, policy);
     }
 
+#ifdef STORE_USE_ETCD
     EtcdHaKvBackend batch_backend;
-    return FinalCatchUpBatchRecordsLocked(batch_backend);
+    return FinalCatchUpBatchRecordsLocked(batch_backend, policy);
+#else
+    LOG(ERROR) << "Final OpLog catch-up requires STORE_USE_ETCD";
+    return ErrorCode::INTERNAL_ERROR;
+#endif
 }
 
 ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
-    HaKvBackend& backend) {
+    HaKvBackend& backend, PromotionCatchUpPolicy policy) {
     std::unique_ptr<OpLogBatchStandbyReader> local_reader;
     OpLogBatchStandbyReader* reader = batch_standby_reader_.get();
     if (reader == nullptr) {
@@ -517,15 +556,22 @@ ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
             cluster_id_, backend, *oplog_applier_);
         reader = local_reader.get();
     }
-    const auto deadline =
-        std::chrono::steady_clock::now() + std::chrono::seconds(30);
     const auto initial_retry_delay =
         std::chrono::milliseconds(std::max(config_.oplog_poll_interval_ms, 1));
     const auto max_retry_delay =
         std::max(initial_retry_delay, std::chrono::milliseconds(1000));
+    const auto no_progress_timeout =
+        std::chrono::seconds(config_.batch_oplog_retry_timeout_sec);
+    const auto legacy_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(30);
+    auto last_progress = std::chrono::steady_clock::now();
     auto retry_delay = initial_retry_delay;
     auto wait_to_retry = [&] {
         const auto now = std::chrono::steady_clock::now();
+        const auto deadline =
+            policy == PromotionCatchUpPolicy::kLegacyTotalDeadline
+                ? legacy_deadline
+                : last_progress + no_progress_timeout;
         if (now >= deadline) {
             return false;
         }
@@ -536,10 +582,25 @@ ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
         return true;
     };
     for (;;) {
-        if (std::chrono::steady_clock::now() >= deadline) {
+        if (policy == PromotionCatchUpPolicy::kLegacyTotalDeadline &&
+            std::chrono::steady_clock::now() >= legacy_deadline) {
             return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
         }
+        const uint64_t expected_before =
+            oplog_applier_->GetExpectedSequenceId();
+        const auto cursor_before = reader->GetLastAppliedDurablePrefix();
         auto result = reader->PollOnce();
+        const uint64_t expected_after = oplog_applier_->GetExpectedSequenceId();
+        const auto cursor_after = reader->GetLastAppliedDurablePrefix();
+        const bool made_progress =
+            expected_after > expected_before || cursor_after != cursor_before;
+        if (made_progress) {
+            last_progress = std::chrono::steady_clock::now();
+            retry_delay = initial_retry_delay;
+        } else if (policy == PromotionCatchUpPolicy::kLegacyTotalDeadline &&
+                   result.error == ErrorCode::OK) {
+            retry_delay = initial_retry_delay;
+        }
         if (result.error != ErrorCode::OK) {
             if (result.disposition !=
                     OpLogBatchStandbyPollDisposition::RETRYABLE ||
@@ -548,7 +609,6 @@ ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
             }
             continue;
         }
-        retry_delay = initial_retry_delay;
         if (!result.durable_prefix_present) {
             return GetLocalLastAppliedSequenceIdLocked() == 0
                        ? ErrorCode::OK
@@ -558,6 +618,9 @@ ErrorCode HotStandbyService::FinalCatchUpBatchRecordsLocked(
             result.durable_prefix.last_seq) {
             return ErrorCode::OK;
         }
+        if (!made_progress && !wait_to_retry()) {
+            return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+        }
     }
 }
 
@@ -582,9 +645,15 @@ ErrorCode HotStandbyService::Promote() {
 
     LOG(INFO) << "Promoting Standby to Primary. Applied seq_id: "
               << current_applied_seq_id << ", lag: " << status.lag_entries
-              << " entries" << ", state: " << StandbyStateToString(GetState());
+              << " entries"
+              << ", state: " << StandbyStateToString(GetState());
 
-    auto internal_err = PromoteLockedInternal(current_applied_seq_id);
+    auto internal_err = PreparePromotionLocked(
+        current_applied_seq_id, PromotionCatchUpPolicy::kLegacyTotalDeadline);
+    if (internal_err != ErrorCode::OK) {
+        return internal_err;
+    }
+    internal_err = CompletePromotionLocked();
     if (internal_err != ErrorCode::OK) {
         return internal_err;
     }
@@ -601,11 +670,16 @@ ErrorCode HotStandbyService::Promote() {
     return ErrorCode::OK;
 }
 
-ErrorCode HotStandbyService::PromoteLockedInternal(
-    uint64_t current_applied_seq_id) {
+ErrorCode HotStandbyService::PreparePromotionLocked(
+    uint64_t current_applied_seq_id, PromotionCatchUpPolicy policy) {
+    NotifySnapshotPromotion();
     StopReplicationLoop();
+    if (recovering_.load(std::memory_order_acquire)) {
+        state_machine_.ProcessEvent(StandbyEvent::PROMOTION_FAILED);
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    }
     ErrorCode catch_up_err =
-        FinalCatchUpForPromotionLocked(current_applied_seq_id);
+        FinalCatchUpForPromotionLocked(current_applied_seq_id, policy);
     if (catch_up_err != ErrorCode::OK) {
         state_machine_.ProcessEvent(StandbyEvent::PROMOTION_FAILED);
         return catch_up_err;
@@ -615,10 +689,15 @@ ErrorCode HotStandbyService::PromoteLockedInternal(
     applied_seq_id_.store(latest_applied_seq_id, std::memory_order_release);
     primary_seq_id_.store(latest_applied_seq_id, std::memory_order_release);
 
+    return ErrorCode::OK;
+}
+
+ErrorCode HotStandbyService::CompletePromotionLocked() {
     auto promotion_success =
         state_machine_.ProcessEvent(StandbyEvent::PROMOTION_SUCCESS);
     if (!promotion_success.allowed) {
         LOG(ERROR) << "Cannot finish promotion: " << promotion_success.reason;
+        state_machine_.ProcessEvent(StandbyEvent::PROMOTION_FAILED);
         return ErrorCode::INTERNAL_ERROR;
     }
     return ErrorCode::OK;
@@ -648,7 +727,12 @@ ErrorCode HotStandbyService::PromoteAndExportSnapshot(StandbySnapshot& out) {
               << " entries"
               << ", state: " << StandbyStateToString(GetState());
 
-    auto internal_err = PromoteLockedInternal(current_applied_seq_id);
+    auto internal_err = PreparePromotionLocked(
+        current_applied_seq_id, PromotionCatchUpPolicy::kLegacyTotalDeadline);
+    if (internal_err != ErrorCode::OK) {
+        return internal_err;
+    }
+    internal_err = CompletePromotionLocked();
     if (internal_err != ErrorCode::OK) {
         return internal_err;
     }
@@ -679,6 +763,86 @@ ErrorCode HotStandbyService::PromoteAndExportSnapshot(StandbySnapshot& out) {
     return ErrorCode::OK;
 }
 
+bool HotStandbyService::IsBatchOpLogSnapshotMode() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return config_.enable_oplog_following &&
+           batch_oplog_snapshot_provider_ != nullptr &&
+           batch_standby_reader_ != nullptr;
+}
+
+tl::expected<BatchOpLogPromotionHandoff, ErrorCode>
+HotStandbyService::PromoteAndDetachBatchOpLogStore() {
+    std::unique_lock<std::mutex> lock(mutex_);
+    if (!batch_oplog_snapshot_provider_ || !config_.enable_oplog_following ||
+        !batch_standby_reader_) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    if (!IsReadyForPromotion()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+
+    auto transition = state_machine_.ProcessEvent(StandbyEvent::PROMOTE);
+    if (!transition.allowed) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+
+    const uint64_t current_applied_seq_id = GetSyncStatus().applied_seq_id;
+    ErrorCode err = PreparePromotionLocked(
+        current_applied_seq_id, PromotionCatchUpPolicy::kBoundedNoProgress);
+    if (err != ErrorCode::OK) {
+        return tl::make_unexpected(err);
+    }
+
+    const uint64_t latest_applied_seq_id =
+        GetLocalLastAppliedSequenceIdLocked();
+    auto applied_cursor =
+        batch_standby_reader_
+            ? batch_standby_reader_->GetLastAppliedDurablePrefix()
+            : std::nullopt;
+    if (!applied_cursor && latest_applied_seq_id == 0 && metadata_store_ &&
+        metadata_store_->GetKeyCount() == 0) {
+        applied_cursor = DurablePrefix{};
+    }
+    if (!metadata_store_ || !applied_cursor ||
+        applied_cursor->last_seq != latest_applied_seq_id) {
+        state_machine_.ProcessEvent(StandbyEvent::PROMOTION_FAILED);
+        return tl::make_unexpected(ErrorCode::INCOMPLETE_OPLOG_CATCH_UP);
+    }
+
+    ReplicaID max_replica_id = 0;
+    if (!metadata_store_->ValidateReplicaIds(max_replica_id)) {
+        state_machine_.ProcessEvent(StandbyEvent::PROMOTION_FAILED);
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    ViewVersionId producer_view_version = batch_snapshot_producer_view_version_;
+    ViewVersionId current_producer_view = 0;
+    if (batch_standby_reader_->ReadProducerView(current_producer_view) ==
+        ErrorCode::OK) {
+        producer_view_version = current_producer_view;
+    }
+
+    auto segments = oplog_applier_->GetSegmentRegistry().GetAllSegments();
+    err = CompletePromotionLocked();
+    if (err != ErrorCode::OK) {
+        return tl::make_unexpected(err);
+    }
+
+    BatchOpLogPromotionHandoff handoff{
+        .metadata_store = std::move(metadata_store_),
+        .segments = std::move(segments),
+        .applied_cursor = *applied_cursor,
+        .producer_view_version = producer_view_version,
+        .max_replica_id = max_replica_id,
+    };
+    batch_standby_reader_.reset();
+    oplog_applier_.reset();
+
+    lock.unlock();
+    Stop();
+    return handoff;
+}
+
 size_t HotStandbyService::GetMetadataCount() const {
     std::lock_guard<std::mutex> lock(mutex_);
     return metadata_store_ ? metadata_store_->GetKeyCount() : 0;
@@ -737,6 +901,120 @@ bool HotStandbyService::ExportStandbySnapshot(StandbySnapshot& out) const {
     return true;
 }
 
+std::optional<BatchOpLogSnapshotCapture>
+HotStandbyService::BeginBatchOpLogSnapshotCapture() {
+    std::unique_lock<std::mutex> service_lock(mutex_);
+    auto state = snapshot_capture_state_;
+    std::unique_lock<std::mutex> capture_lock(state->mutex);
+    if (!IsRunning() || recovering_.load(std::memory_order_acquire) ||
+        !batch_standby_reader_ || state->requested || state->active) {
+        return std::nullopt;
+    }
+
+    ++state->generation;
+    state->requested = true;
+    service_lock.unlock();
+    replication_loop_cv_.notify_all();
+    state->cv.wait(capture_lock, [&state] { return !state->requested; });
+    if (!ready_snapshot_capture_ || !state->active) {
+        return std::nullopt;
+    }
+
+    auto capture = std::move(*ready_snapshot_capture_);
+    ready_snapshot_capture_.reset();
+    return capture;
+}
+
+bool HotStandbyService::CopyNextBatchOpLogSnapshotChunk(
+    size_t count, BatchOpLogSnapshotCapture& capture,
+    std::vector<StandbyObjectEntry>& out) {
+    auto state = snapshot_capture_state_;
+    std::lock_guard<std::mutex> lock(state->mutex);
+    if (capture.lease_state_ != state || !state->active ||
+        capture.generation_ != state->generation || !metadata_store_) {
+        out.clear();
+        return false;
+    }
+    return metadata_store_->CopyNextSnapshotChunk(count, capture.cursor_, out);
+}
+
+void HotStandbyService::EndBatchOpLogSnapshotCapture(
+    BatchOpLogSnapshotCapture& capture) {
+    if (capture.lease_state_ == snapshot_capture_state_) {
+        capture.Release();
+        SnapshotLifecycleCallback callback;
+        {
+            std::lock_guard<std::mutex> lock(
+                snapshot_lifecycle_callback_mutex_);
+            callback = snapshot_capture_released_callback_;
+        }
+        if (callback) {
+            callback();
+        }
+    }
+}
+
+void HotStandbyService::HandleSnapshotCaptureRequest(
+    const OpLogBatchStandbyPollResult& result) {
+    auto state = snapshot_capture_state_;
+    std::unique_lock<std::mutex> lock(state->mutex);
+    if (!state->requested) {
+        return;
+    }
+
+    const auto pause_start = std::chrono::steady_clock::now();
+    state->requested = false;
+    auto applied_prefix = batch_standby_reader_->GetLastAppliedDurablePrefix();
+    ViewVersionId producer_view_version = 0;
+    const ErrorCode producer_view_error =
+        batch_standby_reader_->ReadProducerView(producer_view_version);
+    const uint64_t expected = oplog_applier_->GetExpectedSequenceId();
+    const bool consistent =
+        result.error == ErrorCode::OK && result.durable_prefix_present &&
+        (producer_view_error == ErrorCode::OK ||
+         producer_view_error == ErrorCode::ETCD_KEY_NOT_EXIST) &&
+        applied_prefix && *applied_prefix == result.durable_prefix &&
+        expected > 0 && expected - 1 == applied_prefix->last_seq;
+    if (consistent && IsRunning() && metadata_store_) {
+        BatchOpLogSnapshotCapture capture(
+            applied_prefix->last_seq, applied_prefix->batch_id,
+            producer_view_version,
+            oplog_applier_->GetSegmentRegistry().GetAllSegments(),
+            metadata_store_->BeginSnapshotTraversal(), state->generation,
+            state);
+        ready_snapshot_capture_ = std::move(capture);
+        state->active = true;
+    }
+    state->cv.notify_all();
+
+    state->cv.wait(lock, [this, &state] {
+        return !state->active ||
+               !replication_loop_running_.load(std::memory_order_acquire);
+    });
+    if (consistent) {
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.capture_pause_us =
+                std::chrono::duration_cast<std::chrono::microseconds>(
+                    std::chrono::steady_clock::now() - pause_start)
+                    .count();
+        });
+    }
+}
+
+void HotStandbyService::CancelSnapshotCapture() {
+    auto state = snapshot_capture_state_;
+    std::optional<BatchOpLogSnapshotCapture> ready_capture;
+    {
+        std::lock_guard<std::mutex> lock(state->mutex);
+        state->requested = false;
+        state->active = false;
+        ready_capture = std::move(ready_snapshot_capture_);
+        ready_snapshot_capture_.reset();
+        state->cv.notify_all();
+    }
+    ready_capture.reset();
+}
+
 void HotStandbyService::SetSnapshotProvider(
     std::unique_ptr<SnapshotProvider> provider) {
     std::lock_guard<std::mutex> lock(mutex_);
@@ -747,6 +1025,118 @@ void HotStandbyService::SetSnapshotProvider(
     }
 }
 
+void HotStandbyService::SetBatchOpLogSnapshotProvider(
+    std::unique_ptr<BatchOpLogSnapshotProvider> provider) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    batch_oplog_snapshot_provider_ = std::move(provider);
+}
+
+ErrorCode HotStandbyService::RebootstrapBatchOpLog(uint64_t floor) {
+    HAMetricManager::SnapshotOperationTimer metric_timer(
+        HAMetricManager::SnapshotOperation::Rebootstrap);
+    recovering_.store(true, std::memory_order_release);
+    CancelSnapshotCapture();
+    {
+        std::lock_guard<std::mutex> cursor_lock(batch_snapshot_cursor_mutex_);
+        last_applied_batch_snapshot_prefix_.reset();
+    }
+    NotifySyncStatus();
+
+    // Stop/promotion can hold mutex_ while joining this worker. Never block
+    // on that mutex once the worker has been asked to stop.
+    auto lock_while_running = [this](std::unique_lock<std::mutex>& lock) {
+        while (replication_loop_running_.load(std::memory_order_acquire)) {
+            if (lock.try_lock()) {
+                return replication_loop_running_.load(
+                    std::memory_order_acquire);
+            }
+            std::unique_lock<std::mutex> wait_lock(replication_loop_mutex_);
+            replication_loop_cv_.wait_for(
+                wait_lock, std::chrono::milliseconds(1),
+                [this] { return !replication_loop_running_.load(); });
+        }
+        return false;
+    };
+    std::shared_ptr<BatchOpLogSnapshotProvider> provider;
+    {
+        std::unique_lock<std::mutex> lock(mutex_, std::defer_lock);
+        if (!lock_while_running(lock)) return ErrorCode::ETCD_CTX_CANCELLED;
+        provider = batch_oplog_snapshot_provider_;
+    }
+    if (!provider) return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+
+    auto metadata = std::make_unique<StandbyMetadataStore>();
+    auto applier = std::make_unique<OpLogApplier>(metadata.get(), cluster_id_);
+    StandbySegmentRegistry registry;
+    auto restored = provider->RestoreBaseline(
+        *metadata, registry, applier.get(), floor, [this] {
+            return !replication_loop_running_.load(std::memory_order_acquire);
+        });
+    if (!restored) return restored.error();
+    auto reader = std::make_unique<OpLogBatchStandbyReader>(
+        cluster_id_, *batch_standby_kv_backend_, *applier);
+    const DurablePrefix baseline{.batch_id = restored->last_applied_batch_id,
+                                 .last_seq = restored->last_applied_seq};
+    auto err = reader->SetBaselineCursor(baseline);
+    if (err != ErrorCode::OK) return err;
+    // Recheck the floor and durable suffix after restoring the candidate.
+    OpLogBatchStandbyPollResult poll;
+    do {
+        if (!replication_loop_running_.load(std::memory_order_acquire)) {
+            return ErrorCode::ETCD_CTX_CANCELLED;
+        }
+        poll = reader->PollOnce();
+        if (poll.error != ErrorCode::OK) return poll.error;
+    } while (poll.durable_prefix_present &&
+             applier->GetExpectedSequenceId() - 1 <
+                 poll.durable_prefix.last_seq);
+    auto cursor = reader->GetLastAppliedDurablePrefix();
+    if (!poll.durable_prefix_present || !cursor ||
+        *cursor != poll.durable_prefix ||
+        cursor->last_seq < applied_seq_id_.load()) {
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    }
+    TestFailPoint::Wait("standby_rebootstrap_before_swap");
+    uint64_t current_floor = 0;
+    OpLogBatchStorage storage(cluster_id_, *batch_standby_kv_backend_);
+    err = storage.ReadCompactionFloor(current_floor);
+    if (err != ErrorCode::OK && err != ErrorCode::ETCD_KEY_NOT_EXIST)
+        return err;
+    if (err == ErrorCode::OK) {
+        HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+            metrics.compaction_floor =
+                std::max(metrics.compaction_floor, current_floor);
+        });
+    }
+    if (err == ErrorCode::OK &&
+        restored->last_included_batch_id < current_floor) {
+        return ErrorCode::INCOMPLETE_OPLOG_CATCH_UP;
+    }
+    std::unique_lock<std::mutex> lock(mutex_, std::defer_lock);
+    if (!lock_while_running(lock) || !IsRunning()) {
+        return ErrorCode::ETCD_CTX_CANCELLED;
+    }
+    // Swapping preserves old state until all replacement references exist.
+    // Locals destroy the old reader before its applier and metadata store.
+    metadata_store_.swap(metadata);
+    oplog_applier_.swap(applier);
+    batch_standby_reader_.swap(reader);
+    batch_snapshot_baseline_ = *cursor;
+    batch_snapshot_producer_view_version_ = restored->producer_view_version;
+    HAMetricManager::instance().update_snapshot_runtime([&](auto& metrics) {
+        metrics.applied_batch = batch_snapshot_baseline_->batch_id;
+    });
+    {
+        std::lock_guard<std::mutex> cursor_lock(batch_snapshot_cursor_mutex_);
+        last_applied_batch_snapshot_prefix_ = *cursor;
+    }
+    applied_seq_id_.store(cursor->last_seq);
+    primary_seq_id_.store(cursor->last_seq);
+    last_error_.store(ErrorCode::OK);
+    recovering_.store(false, std::memory_order_release);
+    return metric_timer.Success(ErrorCode::OK);
+}
+
 void HotStandbyService::ReplicationLoop() {
     LOG(INFO) << "Replication loop started (OpLog sync)";
 
@@ -760,6 +1150,7 @@ void HotStandbyService::ReplicationLoop() {
         std::max(retry_base, std::chrono::milliseconds(5000));
     auto retry_delay = retry_base;
     std::optional<std::chrono::steady_clock::time_point> retry_started;
+    uint64_t recovery_floor = 0;
 
     auto wait_for_next_poll = [this](std::chrono::milliseconds delay) {
         std::unique_lock<std::mutex> lock(replication_loop_mutex_);
@@ -775,10 +1166,56 @@ void HotStandbyService::ReplicationLoop() {
             continue;
         }
 
+        if (recovering_.load(std::memory_order_acquire)) {
+            const auto error = RebootstrapBatchOpLog(recovery_floor);
+            last_error_.store(error, std::memory_order_release);
+            NotifySyncStatus();
+            if (error != ErrorCode::OK) {
+                wait_for_next_poll(retry_delay);
+                retry_delay = std::min(retry_delay * 2, max_retry_delay);
+            } else {
+                retry_started.reset();
+                retry_delay = retry_base;
+            }
+            continue;
+        }
+
         if (batch_standby_reader_) {
             const uint64_t expected_before =
                 oplog_applier_->GetExpectedSequenceId();
             auto result = batch_standby_reader_->PollOnce();
+            if (result.durable_prefix_present ||
+                result.disposition ==
+                    OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED) {
+                const auto applied =
+                    batch_standby_reader_->GetLastAppliedDurablePrefix();
+                HAMetricManager::instance().update_snapshot_runtime(
+                    [&](auto& metrics) {
+                        metrics.applied_batch = applied ? applied->batch_id : 0;
+                        if (result.durable_prefix_present)
+                            metrics.durable_batch =
+                                std::max(metrics.durable_batch,
+                                         result.durable_prefix.batch_id);
+                        metrics.compaction_floor = std::max(
+                            metrics.compaction_floor, result.compaction_floor);
+                        if (applied &&
+                            applied->batch_id >=
+                                metrics.catch_up_target_batch &&
+                            !IsSequenceOlder(
+                                applied->last_seq,
+                                metrics.catch_up_target_sequence)) {
+                            metrics.catch_up_target_batch = 0;
+                            metrics.catch_up_target_sequence = 0;
+                        }
+                    });
+            }
+            {
+                std::lock_guard<std::mutex> cursor_lock(
+                    batch_snapshot_cursor_mutex_);
+                last_applied_batch_snapshot_prefix_ =
+                    batch_standby_reader_->GetLastAppliedDurablePrefix();
+            }
+            HandleSnapshotCaptureRequest(result);
             if (result.durable_prefix_present) {
                 const uint64_t current_primary = primary_seq_id_.load();
                 if (result.durable_prefix.last_seq > current_primary) {
@@ -794,6 +1231,12 @@ void HotStandbyService::ReplicationLoop() {
             if (result.error != ErrorCode::OK) {
                 last_error_.store(result.error, std::memory_order_release);
                 const bool made_progress = expected_after > expected_before;
+                if (result.disposition ==
+                    OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED) {
+                    recovery_floor = result.compaction_floor;
+                    recovering_.store(true, std::memory_order_release);
+                    continue;
+                }
                 if (result.disposition ==
                     OpLogBatchStandbyPollDisposition::RETRYABLE) {
                     const auto now = std::chrono::steady_clock::now();
@@ -851,6 +1294,9 @@ void HotStandbyService::ReplicationLoop() {
             std::chrono::milliseconds(config_.oplog_poll_interval_ms));
     }
 
+    replication_loop_running_.store(false, std::memory_order_release);
+    CancelSnapshotCapture();
+    replication_loop_cv_.notify_all();
     LOG(INFO) << "Replication loop stopped";
 }
 
diff --git a/mooncake-store/src/kv_event/kv_event_publisher.cpp b/mooncake-store/src/kv_event/kv_event_publisher.cpp
index 8349bfc7a1..f680153a7c 100644
--- a/mooncake-store/src/kv_event/kv_event_publisher.cpp
+++ b/mooncake-store/src/kv_event/kv_event_publisher.cpp
@@ -6,9 +6,11 @@
 #include <msgpack.hpp>
 #include <zmq.h>
 
+#include <algorithm>
 #include <chrono>
 #include <cstring>
 #include <endian.h>
+#include <unordered_set>
 #include <vector>
 
 namespace mooncake {
@@ -32,17 +34,14 @@ void PackOptionalString(msgpack::packer<msgpack::sbuffer>& packer,
     }
 }
 
-void PackOptionalU32(msgpack::packer<msgpack::sbuffer>& packer, uint32_t value,
-                     bool has_value) {
-    if (!has_value) {
-        packer.pack_nil();
-    } else {
-        packer.pack(value);
-    }
-}
-
-size_t ComputeEventMapSize(bool is_stored, bool emit_legacy,
+size_t ComputeEventMapSize(bool is_stored, bool is_cleared, bool emit_legacy,
                            bool emit_object_key) {
+    if (is_cleared) {
+        // Envelope only: event_id, timestamp, event_type, model_name,
+        // block_size, additional_salt, lora_name, tenant_id, backend_id,
+        // medium, dp_rank.
+        return 11 + (emit_legacy ? 1 : 0);
+    }
     // Base envelope: event_id, timestamp, event_type, model_name, block_size,
     // additional_salt, lora_name, tenant_id, backend_id, medium, dp_rank,
     // seq_hashes, group_id.
@@ -65,6 +64,30 @@ size_t ComputeEventMapSize(bool is_stored, bool emit_legacy,
     return map_size;
 }
 
+std::unordered_set<std::string> NormalizeMedia(
+    const std::vector<std::string>& media) {
+    std::unordered_set<std::string> result;
+    for (const auto& value : media) {
+        if (!value.empty()) {
+            result.insert(value);
+        }
+    }
+    return result;
+}
+
+std::vector<std::string> SortedMedia(
+    const std::unordered_set<std::string>& media) {
+    std::vector<std::string> result(media.begin(), media.end());
+    std::sort(result.begin(), result.end());
+    return result;
+}
+
+// Events always carry a concrete tenant so subscribers can key on it without
+// having to model an unset value.
+std::string NormalizeTenant(const std::string& tenant_id) {
+    return tenant_id.empty() ? "default" : tenant_id;
+}
+
 }  // namespace
 
 KvEventPublisher::KvEventPublisher(KvEventConfig config)
@@ -82,6 +105,16 @@ KvEventPublisher::KvEventPublisher(KvEventConfig config)
         config_.enabled = false;
         return;
     }
+    if (!config_.emit_object_key) {
+        // object_key is the only key-identifying field on the wire, so without
+        // it a stored/removed event carries nothing a subscriber can act on and
+        // is dropped. Say so at startup: the flag name reads like a formatting
+        // switch, but it silences the whole per-object stream.
+        LOG(WARNING)
+            << "kv_events: emit_object_key=false suppresses all stored "
+               "and removed events; only cleared will be published. "
+               "Suppressed events are counted as skipped_keyless_events";
+    }
 
     zmq_context_ = zmq_ctx_new();
     if (!zmq_context_) {
@@ -140,24 +173,112 @@ KvEventPublisher::~KvEventPublisher() {
 
 void KvEventPublisher::PublishStored(const std::string& object_key,
                                      const std::string& medium,
-                                     const TenantId& tenant_id,
+                                     const std::string& tenant_id,
                                      const std::string& group_id) {
     if (!config_.enabled) {
         return;
     }
-    Enqueue(PendingEvent{EventKind::kStored, object_key, medium, tenant_id,
-                         group_id});
+    // medium is the only availability field on a stored event, so an empty one
+    // would announce a replica the subscriber cannot place on any tier.
+    if (medium.empty()) {
+        return;
+    }
+    std::vector<PendingEvent> events;
+    events.push_back(PendingEvent{EventKind::kStored, object_key, medium,
+                                  NormalizeTenant(tenant_id), group_id});
+    EnqueueBatch(std::move(events));
 }
 
 void KvEventPublisher::PublishRemoved(const std::string& object_key,
                                       const std::string& medium,
-                                      const TenantId& tenant_id,
+                                      const std::string& tenant_id,
                                       const std::string& group_id) {
     if (!config_.enabled) {
         return;
     }
-    Enqueue(PendingEvent{EventKind::kRemoved, object_key, medium, tenant_id,
-                         group_id});
+    // A retraction has to name the tier it retracts; medium=nil would ask the
+    // subscriber to drop availability it cannot identify.
+    if (medium.empty()) {
+        return;
+    }
+    std::vector<PendingEvent> events;
+    events.push_back(PendingEvent{EventKind::kRemoved, object_key, medium,
+                                  NormalizeTenant(tenant_id), group_id});
+    EnqueueBatch(std::move(events));
+}
+
+void KvEventPublisher::PublishCleared(const std::string& tenant_id) {
+    if (!config_.enabled) {
+        return;
+    }
+    std::vector<PendingEvent> events;
+    events.push_back(PendingEvent{EventKind::kCleared, "", "",
+                                  NormalizeTenant(tenant_id), ""});
+    EnqueueBatch(std::move(events));
+}
+
+void KvEventPublisher::PublishCommitted(
+    const std::string& object_key,
+    const std::vector<std::string>& current_media, const std::string& tenant_id,
+    const std::string& group_id) {
+    if (!config_.enabled) {
+        return;
+    }
+    const std::string normalized_tenant = NormalizeTenant(tenant_id);
+    std::vector<PendingEvent> events;
+    // A commit announces every medium unconditionally. Unlike SyncObjectState
+    // this is not a delta: the medium set can be unchanged while the object
+    // contents are new, and a subscriber that saw no event would keep serving
+    // the previous contents.
+    for (const auto& medium : SortedMedia(NormalizeMedia(current_media))) {
+        events.push_back(PendingEvent{EventKind::kStored, object_key, medium,
+                                      normalized_tenant, group_id});
+    }
+    EnqueueBatch(std::move(events));
+}
+
+void KvEventPublisher::PublishObjectRemoved(
+    const std::string& object_key, const std::string& tenant_id,
+    const std::string& group_id,
+    const std::vector<std::string>& previous_media) {
+    if (!config_.enabled) {
+        return;
+    }
+    const std::string normalized_tenant = NormalizeTenant(tenant_id);
+    std::vector<PendingEvent> events;
+    for (const auto& medium : SortedMedia(NormalizeMedia(previous_media))) {
+        events.push_back(PendingEvent{EventKind::kRemoved, object_key, medium,
+                                      normalized_tenant, group_id});
+    }
+    EnqueueBatch(std::move(events));
+}
+
+void KvEventPublisher::SyncObjectState(
+    const std::string& object_key,
+    const std::vector<std::string>& current_media, const std::string& tenant_id,
+    const std::string& group_id,
+    const std::vector<std::string>& previous_media) {
+    if (!config_.enabled) {
+        return;
+    }
+    const std::string normalized_tenant = NormalizeTenant(tenant_id);
+    const auto new_set = NormalizeMedia(current_media);
+    const auto previous_set = NormalizeMedia(previous_media);
+
+    std::vector<PendingEvent> events;
+    for (const auto& medium : SortedMedia(previous_set)) {
+        if (!new_set.contains(medium)) {
+            events.push_back(PendingEvent{EventKind::kRemoved, object_key,
+                                          medium, normalized_tenant, group_id});
+        }
+    }
+    for (const auto& medium : SortedMedia(new_set)) {
+        if (!previous_set.contains(medium)) {
+            events.push_back(PendingEvent{EventKind::kStored, object_key,
+                                          medium, normalized_tenant, group_id});
+        }
+    }
+    EnqueueBatch(std::move(events));
 }
 
 KvEventPublisher::Stats KvEventPublisher::GetStats() const {
@@ -165,21 +286,26 @@ KvEventPublisher::Stats KvEventPublisher::GetStats() const {
     stats.published_batches = published_batches_.load();
     stats.published_events = published_events_.load();
     stats.dropped_events = dropped_events_.load();
-    stats.skipped_unparsed_keys = skipped_unparsed_keys_.load();
+    stats.skipped_keyless_events = skipped_keyless_events_.load();
     return stats;
 }
 
-void KvEventPublisher::Enqueue(PendingEvent event) {
+void KvEventPublisher::EnqueueBatch(std::vector<PendingEvent> events) {
+    if (events.empty()) {
+        return;
+    }
     {
         std::lock_guard<std::mutex> lock(queue_mutex_);
-        if (config_.queue_capacity > 0 &&
-            queue_.size() >= config_.queue_capacity) {
-            queue_.pop_front();
-            dropped_events_.fetch_add(1, std::memory_order_relaxed);
-            // Reserve a ZMQ sequence gap so consumers can detect loss.
-            next_zmq_sequence_.fetch_add(1, std::memory_order_relaxed);
+        for (auto& event : events) {
+            if (config_.queue_capacity > 0 &&
+                queue_.size() >= config_.queue_capacity) {
+                queue_.pop_front();
+                dropped_events_.fetch_add(1, std::memory_order_relaxed);
+                // Reserve a ZMQ sequence gap so consumers can detect loss.
+                next_zmq_sequence_.fetch_add(1, std::memory_order_relaxed);
+            }
+            queue_.push_back(std::move(event));
         }
-        queue_.push_back(std::move(event));
     }
     queue_cv_.notify_one();
 }
@@ -225,23 +351,18 @@ void KvEventPublisher::WorkerLoop() {
 void KvEventPublisher::PublishBatch(const std::vector<PendingEvent>& batch) {
     struct EncodedEvent {
         PendingEvent pending;
-        std::optional<uint64_t> seq_hash;
         uint64_t event_id{0};
     };
     std::vector<EncodedEvent> encoded;
     encoded.reserve(batch.size());
     for (const auto& pending : batch) {
-        const auto seq_hash = ParseSeqHashFromObjectKey(pending.object_key);
-        if (!seq_hash.has_value()) {
-            if (!config_.emit_object_key || pending.object_key.empty()) {
-                skipped_unparsed_keys_.fetch_add(1, std::memory_order_relaxed);
-                continue;
-            }
-            skipped_unparsed_keys_.fetch_add(1, std::memory_order_relaxed);
+        if (pending.kind != EventKind::kCleared &&
+            (!config_.emit_object_key || pending.object_key.empty())) {
+            skipped_keyless_events_.fetch_add(1, std::memory_order_relaxed);
+            continue;
         }
         encoded.push_back(EncodedEvent{
-            pending, seq_hash,
-            next_event_id_.fetch_add(1, std::memory_order_relaxed)});
+            pending, next_event_id_.fetch_add(1, std::memory_order_relaxed)});
     }
     if (encoded.empty()) {
         return;
@@ -258,13 +379,19 @@ void KvEventPublisher::PublishBatch(const std::vector<PendingEvent>& batch) {
     packer.pack_array(encoded.size());
     for (const auto& item : encoded) {
         const bool is_stored = item.pending.kind == EventKind::kStored;
-        const char* rfc_type = is_stored ? "stored" : "removed";
-        const char* legacy_type = is_stored ? "BlockStored" : "BlockRemoved";
-        const std::string& tenant_id = item.pending.tenant_id.value();
-
-        const size_t map_size =
-            ComputeEventMapSize(is_stored, config_.emit_legacy_compat_fields,
-                                config_.emit_object_key);
+        const bool is_cleared = item.pending.kind == EventKind::kCleared;
+        const char* rfc_type =
+            is_stored ? "stored" : (is_cleared ? "cleared" : "removed");
+        const char* legacy_type =
+            is_stored ? "BlockStored"
+                      : (is_cleared ? "AllBlocksCleared" : "BlockRemoved");
+        // Every enqueue path normalizes an empty tenant to "default" before
+        // building the PendingEvent, so no re-check is needed here.
+        const std::string& tenant_id = item.pending.tenant_id;
+
+        const size_t map_size = ComputeEventMapSize(
+            is_stored, is_cleared, config_.emit_legacy_compat_fields,
+            config_.emit_object_key);
 
         packer.pack_map(map_size);
         packer.pack("event_id");
@@ -277,26 +404,33 @@ void KvEventPublisher::PublishBatch(const std::vector<PendingEvent>& batch) {
             packer.pack("type");
             packer.pack(legacy_type);
         }
-        // Per-block envelope fields unknown to the storage pool are omitted
-        // (nil). Indexer registration supplies model/block_size/dp_rank.
         packer.pack("model_name");
-        packer.pack_nil();
+        PackOptionalString(packer, config_.model_name);
         packer.pack("block_size");
-        packer.pack_nil();
+        if (config_.block_size == 0) {
+            packer.pack_nil();
+        } else {
+            packer.pack(config_.block_size);
+        }
         packer.pack("additional_salt");
-        packer.pack_nil();
+        PackOptionalString(packer, config_.additional_salt);
         packer.pack("lora_name");
-        packer.pack_nil();
+        PackOptionalString(packer, config_.lora_name);
         packer.pack("tenant_id");
         packer.pack(tenant_id);
         packer.pack("backend_id");
         packer.pack(config_.backend_id);
-        packer.pack("group_id");
-        PackOptionalString(packer, item.pending.group_id);
         packer.pack("medium");
         PackOptionalString(packer, item.pending.medium);
         packer.pack("dp_rank");
-        packer.pack_nil();
+        packer.pack(config_.dp_rank);
+
+        if (is_cleared) {
+            continue;
+        }
+
+        packer.pack("group_id");
+        PackOptionalString(packer, item.pending.group_id);
 
         if (config_.emit_object_key) {
             packer.pack("object_key");
@@ -304,27 +438,16 @@ void KvEventPublisher::PublishBatch(const std::vector<PendingEvent>& batch) {
         }
 
         packer.pack("seq_hashes");
-        if (item.seq_hash.has_value()) {
-            packer.pack_array(1);
-            packer.pack(item.seq_hash.value());
-        } else {
-            packer.pack_array(0);
-        }
+        packer.pack_array(0);
 
-        if (config_.emit_legacy_compat_fields && item.seq_hash.has_value()) {
-            packer.pack("block_hashes");
-            packer.pack_array(1);
-            packer.pack(static_cast<int64_t>(item.seq_hash.value()));
-        } else if (config_.emit_legacy_compat_fields) {
+        if (config_.emit_legacy_compat_fields) {
             packer.pack("block_hashes");
             packer.pack_array(0);
         }
 
         if (is_stored) {
-            // Master keys are standalone pool blocks; depth 0 satisfies RFC
-            // #1527 requirement that base_block_idx or parent_hash be present.
             packer.pack("base_block_idx");
-            packer.pack(static_cast<uint32_t>(0));
+            packer.pack_nil();
             packer.pack("parent_hash");
             packer.pack_nil();
             packer.pack("token_ids");
@@ -339,8 +462,7 @@ void KvEventPublisher::PublishBatch(const std::vector<PendingEvent>& batch) {
         }
     }
 
-    // Batch-level dp_rank; storage pool has no DP context (0).
-    packer.pack(static_cast<uint32_t>(0));
+    packer.pack(config_.dp_rank);
 
     const uint64_t seq = next_zmq_sequence_.fetch_add(1);
     const uint64_t seq_be = htobe64(seq);
diff --git a/mooncake-store/src/local_ssd/CMakeLists.txt b/mooncake-store/src/local_ssd/CMakeLists.txt
new file mode 100644
index 0000000000..71dd5a292e
--- /dev/null
+++ b/mooncake-store/src/local_ssd/CMakeLists.txt
@@ -0,0 +1,11 @@
+find_package(Threads REQUIRED)
+
+add_library(mooncake_local_ssd STATIC manager.cpp)
+
+target_include_directories(
+  mooncake_local_ssd PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+                            $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>)
+
+target_link_libraries(
+  mooncake_local_ssd PUBLIC cachelib_memory_allocator
+                            yalantinglibs::yalantinglibs Threads::Threads)
diff --git a/mooncake-store/src/local_ssd/manager.cpp b/mooncake-store/src/local_ssd/manager.cpp
new file mode 100644
index 0000000000..dda7b8de71
--- /dev/null
+++ b/mooncake-store/src/local_ssd/manager.cpp
@@ -0,0 +1,405 @@
+#include "local_ssd/manager.h"
+
+#include <algorithm>
+#include <iterator>
+#include <mutex>
+#include <utility>
+
+namespace mooncake {
+
+LocalSsdTaskMailbox::LocalSsdTaskMailbox(bool enable_offloading)
+    : enable_offloading_(enable_offloading) {}
+
+ErrorCode LocalSsdTaskMailbox::EnqueueOffload(OffloadTaskItem task,
+                                              size_t limit) {
+    MutexLocker lock(&mutex_);
+    if (!enable_offloading_) {
+        return ErrorCode::UNABLE_OFFLOADING;
+    }
+    if (pending_offloads_.size() >= limit) {
+        return ErrorCode::KEYS_ULTRA_LIMIT;
+    }
+    auto index = TenantId(task.tenant_id).MakeScopedKey(task.key);
+    if (!pending_offloads_.emplace(std::move(index), std::move(task)).second) {
+        return ErrorCode::OBJECT_ALREADY_EXISTS;
+    }
+    return ErrorCode::OK;
+}
+
+std::vector<OffloadTaskItem> LocalSsdTaskMailbox::SetOffloadingAndTakePending(
+    bool enabled) {
+    MutexLocker lock(&mutex_);
+    enable_offloading_ = enabled;
+    std::vector<OffloadTaskItem> tasks;
+    tasks.reserve(pending_offloads_.size());
+    for (auto& [_, task] : pending_offloads_) {
+        tasks.push_back(std::move(task));
+    }
+    pending_offloads_.clear();
+    return tasks;
+}
+
+bool LocalSsdTaskMailbox::RemoveOffload(const TenantId& tenant_id,
+                                        std::string_view key) {
+    MutexLocker lock(&mutex_);
+    return pending_offloads_.erase(tenant_id.MakeScopedKey(key)) != 0;
+}
+
+ErrorCode LocalSsdTaskMailbox::EnqueuePromotion(PromotionTaskItem task) {
+    MutexLocker lock(&mutex_);
+    auto index = TenantId(task.tenant_id).MakeScopedKey(task.key);
+    const uint64_t seq = ++promotion_seq_;
+    auto [it, inserted] = pending_promotions_.emplace(
+        std::move(index), PromotionEntry{std::move(task), seq});
+    if (!inserted) {
+        // Already queued: keep the dedup contract but refresh recency, so a
+        // repeated admission moves ahead of stale entries.
+        it->second.seq = seq;
+        return ErrorCode::OBJECT_ALREADY_EXISTS;
+    }
+    return ErrorCode::OK;
+}
+
+std::vector<PromotionTaskItem> LocalSsdTaskMailbox::TakePromotions(
+    size_t max_items) {
+    MutexLocker lock(&mutex_);
+    std::vector<PromotionTaskItem> tasks;
+    const size_t count = std::min(max_items, pending_promotions_.size());
+    if (count == 0) {
+        return tasks;
+    }
+    // Global recency order: rank every entry by seq and take the top
+    // |count|. Entries left behind stay recency-ordered for the next tick —
+    // a backlog larger than max_items never degrades to hash order.
+    std::vector<std::pair<uint64_t, std::string>> ranked;
+    ranked.reserve(pending_promotions_.size());
+    for (const auto& [scoped_key, entry] : pending_promotions_) {
+        ranked.emplace_back(entry.seq, scoped_key);
+    }
+    std::partial_sort(
+        ranked.begin(), ranked.begin() + count, ranked.end(),
+        [](const auto& a, const auto& b) { return a.first > b.first; });
+    tasks.reserve(count);
+    for (size_t i = 0; i < count; ++i) {
+        auto node = pending_promotions_.extract(ranked[i].second);
+        tasks.push_back(std::move(node.mapped().task));
+    }
+    return tasks;
+}
+
+bool LocalSsdTaskMailbox::RemovePromotion(const TenantId& tenant_id,
+                                          std::string_view key) {
+    MutexLocker lock(&mutex_);
+    return pending_promotions_.erase(tenant_id.MakeScopedKey(key)) != 0;
+}
+
+bool LocalSsdTaskMailbox::TouchPromotion(const TenantId& tenant_id,
+                                         std::string_view key) {
+    MutexLocker lock(&mutex_);
+    auto it = pending_promotions_.find(tenant_id.MakeScopedKey(key));
+    if (it == pending_promotions_.end()) {
+        return false;
+    }
+    it->second.seq = ++promotion_seq_;
+    return true;
+}
+
+void LocalSsdTaskMailbox::RequestRemoveAll() {
+    MutexLocker lock(&mutex_);
+    pending_remove_all_ = true;
+}
+
+bool LocalSsdTaskMailbox::ConsumeRemoveAll() {
+    MutexLocker lock(&mutex_);
+    return std::exchange(pending_remove_all_, false);
+}
+
+ErrorCode LocalSsdManager::RegisterClient(const UUID& client_id,
+                                          bool enable_offloading) {
+    std::unique_lock lock(mutex_);
+    if (clients_.contains(client_id)) {
+        return ErrorCode::SEGMENT_ALREADY_EXISTS;
+    }
+    clients_.emplace(client_id,
+                     std::make_shared<ClientRecord>(enable_offloading));
+    return ErrorCode::OK;
+}
+
+std::optional<LocalSsdManager::ClientAccess> LocalSsdManager::FindClient(
+    const UUID& client_id) const {
+    std::shared_lock lock(mutex_);
+    auto it = clients_.find(client_id);
+    if (it == clients_.end()) {
+        return std::nullopt;
+    }
+    return std::optional<ClientAccess>(std::in_place, client_id, it->second);
+}
+
+std::vector<LocalSsdManager::ClientAccess> LocalSsdManager::SnapshotClients()
+    const {
+    std::vector<ClientAccess> clients;
+    std::shared_lock lock(mutex_);
+    clients.reserve(clients_.size());
+    for (const auto& [client_id, record] : clients_) {
+        clients.emplace_back(client_id, record);
+    }
+    return clients;
+}
+
+std::vector<UUID> LocalSsdManager::GetClientIds() const {
+    std::vector<UUID> client_ids;
+    std::shared_lock lock(mutex_);
+    client_ids.reserve(clients_.size());
+    for (const auto& [client_id, record] : clients_) {
+        client_ids.push_back(client_id);
+    }
+    return client_ids;
+}
+
+void LocalSsdManager::WaitForOperations(const ClientMap& clients) {
+    for (const auto& [_, record] : clients) {
+        std::unique_lock lifecycle_lock(record->lifecycle_mutex);
+    }
+}
+
+std::optional<int64_t> LocalSsdManager::UnregisterClient(
+    const UUID& client_id) {
+    std::shared_ptr<ClientRecord> record;
+    {
+        std::unique_lock lock(mutex_);
+        auto it = clients_.find(client_id);
+        if (it == clients_.end()) {
+            return std::nullopt;
+        }
+        record = std::move(it->second);
+        clients_.erase(it);
+    }
+
+    std::unique_lock lifecycle_lock(record->lifecycle_mutex);
+    MutexLocker stats_lock(&record->stats_mutex);
+    return record->total_capacity_bytes;
+}
+
+tl::expected<LocalSsdManager::CapacityChange, ErrorCode>
+LocalSsdManager::ReportCapacity(const UUID& client_id, int64_t bytes) {
+    if (bytes < 0) {
+        return tl::unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto client = FindClient(client_id);
+    if (!client) {
+        return tl::unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    auto& record = *client->record;
+    MutexLocker stats_lock(&record.stats_mutex);
+    CapacityChange change{record.total_capacity_bytes, bytes};
+    record.total_capacity_bytes = bytes;
+    return change;
+}
+
+std::optional<LocalSsdManager::Usage> LocalSsdManager::GetUsage(
+    const UUID& client_id) const {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return std::nullopt;
+    }
+    auto& record = *client->record;
+    MutexLocker stats_lock(&record.stats_mutex);
+    return Usage{record.total_capacity_bytes,
+                 record.used_bytes.load(std::memory_order_relaxed)};
+}
+
+bool LocalSsdManager::AdjustUsedBytes(const UUID& client_id, int64_t delta) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return false;
+    }
+    client->record->used_bytes.fetch_add(delta, std::memory_order_relaxed);
+    return true;
+}
+
+ErrorCode LocalSsdManager::EnqueueOffload(const UUID& client_id,
+                                          OffloadTaskItem task, size_t limit) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    return client->record->mailbox.EnqueueOffload(std::move(task), limit);
+}
+
+tl::expected<std::vector<OffloadTaskItem>, ErrorCode>
+LocalSsdManager::SetOffloadingAndTakePending(const UUID& client_id,
+                                             bool enabled) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return tl::unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    return client->record->mailbox.SetOffloadingAndTakePending(enabled);
+}
+
+bool LocalSsdManager::RemoveOffload(const UUID& client_id,
+                                    const TenantId& tenant_id,
+                                    std::string_view key) {
+    auto client = FindClient(client_id);
+    return client && client->record->mailbox.RemoveOffload(tenant_id, key);
+}
+
+size_t LocalSsdManager::RemoveOffloadFromAll(const TenantId& tenant_id,
+                                             std::string_view key) {
+    auto clients = SnapshotClients();
+    size_t removed = 0;
+    for (auto& client : clients) {
+        removed += client.record->mailbox.RemoveOffload(tenant_id, key);
+    }
+    return removed;
+}
+
+bool LocalSsdManager::CancelOffloadsIfAllPending(
+    const std::vector<UUID>& client_ids, const TenantId& tenant_id,
+    std::string_view key) {
+    if (client_ids.empty()) {
+        return false;
+    }
+
+    std::vector<UUID> sorted_ids = client_ids;
+    std::sort(sorted_ids.begin(), sorted_ids.end());
+    sorted_ids.erase(std::unique(sorted_ids.begin(), sorted_ids.end()),
+                     sorted_ids.end());
+
+    std::vector<ClientAccess> clients;
+    clients.reserve(sorted_ids.size());
+    for (const auto& client_id : sorted_ids) {
+        auto client = FindClient(client_id);
+        if (!client) {
+            return false;
+        }
+        clients.push_back(std::move(*client));
+    }
+
+    // Hold every mailbox lock before checking any entry. A heartbeat can
+    // therefore either drain a mailbox before this operation starts or after
+    // it commits, but cannot leave a partially cancelled set of mirrors.
+    std::vector<std::unique_lock<Mutex>> mailbox_locks;
+    mailbox_locks.reserve(clients.size());
+    for (auto& client : clients) {
+        mailbox_locks.emplace_back(client.record->mailbox.mutex_);
+    }
+
+    const std::string index = tenant_id.MakeScopedKey(key);
+    for (const auto& client : clients) {
+        if (!client.record->mailbox.pending_offloads_.contains(index)) {
+            return false;
+        }
+    }
+    for (auto& client : clients) {
+        client.record->mailbox.pending_offloads_.erase(index);
+    }
+    return true;
+}
+
+ErrorCode LocalSsdManager::EnqueuePromotion(const UUID& client_id,
+                                            PromotionTaskItem task) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    return client->record->mailbox.EnqueuePromotion(std::move(task));
+}
+
+tl::expected<std::vector<PromotionTaskItem>, ErrorCode>
+LocalSsdManager::TakePromotions(const UUID& client_id, size_t max_items) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return tl::unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    return client->record->mailbox.TakePromotions(max_items);
+}
+
+bool LocalSsdManager::TouchPromotion(const UUID& client_id,
+                                     const TenantId& tenant_id,
+                                     std::string_view key) {
+    auto client = FindClient(client_id);
+    return client && client->record->mailbox.TouchPromotion(tenant_id, key);
+}
+
+bool LocalSsdManager::RemovePromotion(const UUID& client_id,
+                                      const TenantId& tenant_id,
+                                      std::string_view key) {
+    auto client = FindClient(client_id);
+    return client && client->record->mailbox.RemovePromotion(tenant_id, key);
+}
+
+void LocalSsdManager::RequestRemoveAll() {
+    auto clients = SnapshotClients();
+    for (auto& client : clients) {
+        client.record->mailbox.RequestRemoveAll();
+    }
+}
+
+void LocalSsdManager::RequestRemoveAll(const std::vector<UUID>& clients) {
+    for (const auto& client_id : clients) {
+        auto client = FindClient(client_id);
+        if (client) {
+            client->record->mailbox.RequestRemoveAll();
+        }
+    }
+}
+
+tl::expected<bool, ErrorCode> LocalSsdManager::ConsumeRemoveAll(
+    const UUID& client_id) {
+    auto client = FindClient(client_id);
+    if (!client) {
+        return tl::unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    return client->record->mailbox.ConsumeRemoveAll();
+}
+
+LocalSsdPersistedState LocalSsdManager::ExportPersistedState() const {
+    auto clients = SnapshotClients();
+    LocalSsdPersistedState state;
+    for (const auto& client_access : clients) {
+        const auto& record = client_access.record;
+        LocalSsdPersistedClient client;
+        {
+            MutexLocker stats_lock(&record->stats_mutex);
+            MutexLocker mailbox_lock(&record->mailbox.mutex_);
+            client.total_capacity_bytes = record->total_capacity_bytes;
+            client.enable_offloading = record->mailbox.enable_offloading_;
+            client.pending_offloads.insert(
+                record->mailbox.pending_offloads_.begin(),
+                record->mailbox.pending_offloads_.end());
+        }
+        state.emplace(client_access.client_id, std::move(client));
+    }
+    return state;
+}
+
+void LocalSsdManager::RestorePersistedState(LocalSsdPersistedState state) {
+    ClientMap clients;
+    for (auto& [client_id, persisted] : state) {
+        auto record =
+            std::make_shared<ClientRecord>(persisted.enable_offloading);
+        record->total_capacity_bytes = persisted.total_capacity_bytes;
+        record->mailbox.pending_offloads_.insert(
+            std::make_move_iterator(persisted.pending_offloads.begin()),
+            std::make_move_iterator(persisted.pending_offloads.end()));
+        clients.emplace(client_id, std::move(record));
+    }
+    ClientMap previous;
+    {
+        std::unique_lock lock(mutex_);
+        previous.swap(clients_);
+        clients_ = std::move(clients);
+    }
+    WaitForOperations(previous);
+}
+
+void LocalSsdManager::Clear() {
+    ClientMap clients;
+    {
+        std::unique_lock lock(mutex_);
+        clients.swap(clients_);
+    }
+    WaitForOperations(clients);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/master.cpp b/mooncake-store/src/master.cpp
index e4e9dec07c..2cab884943 100644
--- a/mooncake-store/src/master.cpp
+++ b/mooncake-store/src/master.cpp
@@ -7,21 +7,25 @@
 #include <cstdlib>  // For std::getenv
 #include <fstream>  // For std::ifstream
 #include <memory>   // For std::unique_ptr
+#include <optional>
 #include <string>
 #include <thread>  // For std::thread
 #include <json/json.h>
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 #include <ylt/easylog/record.hpp>
 
+#include "allocator_status.h"
+#include "config/rpc_protocol_config.h"
 #include "default_config.h"
 #include "duration_utils.h"
 #include "ha/leadership/master_service_supervisor.h"
+#include "ha/snapshot/batch_oplog/config.h"
 
 #include "http_metadata_server.h"
 #include "master_admin_service.h"
 #include "rpc_service.h"
 #include "types.h"
-#include "utils.h"
+#include "common/network.h"
 
 #include "master_config.h"
 #include "version.h"
@@ -36,9 +40,13 @@ static_assert(mooncake::DEFAULT_DEFAULT_KV_LEASE_TTL == 10000,
 static_assert(mooncake::DEFAULT_KV_SOFT_PIN_TTL_MS == 30 * 60 * 1000,
               "Update kDefaultKvSoftPinTtlFlagValue when "
               "DEFAULT_KV_SOFT_PIN_TTL_MS changes");
+static_assert(mooncake::DEFAULT_MAX_KV_SOFT_PIN_TTL_MS == 24 * 60 * 60 * 1000,
+              "Update kDefaultMaxKvSoftPinTtlFlagValue when "
+              "DEFAULT_MAX_KV_SOFT_PIN_TTL_MS changes");
 
 constexpr char kDefaultKvLeaseTtlFlagValue[] = "10000";
 constexpr char kDefaultKvSoftPinTtlFlagValue[] = "1800000";
+constexpr char kDefaultMaxKvSoftPinTtlFlagValue[] = "86400000";
 
 namespace {
 
@@ -118,22 +126,42 @@ DEFINE_int32(
     "Maximum number of threads to use (deprecated, use rpc_thread_num)");
 DEFINE_bool(enable_metric_reporting, true, "Enable periodic metric reporting");
 DEFINE_int32(metrics_port, 9003, "Port for HTTP metrics server to listen on");
+DEFINE_string(metrics_host, "0.0.0.0",
+              "Address for the HTTP metrics/admin server to listen on. "
+              "Use \"::\" to listen on IPv6 (and IPv4 on dual-stack hosts)");
 DEFINE_string(default_kv_lease_ttl, kDefaultKvLeaseTtlFlagValue,
               "Default lease time for kv objects. Supports raw milliseconds "
               "or duration strings with ms, s, m, or h suffixes");
 DEFINE_string(default_kv_soft_pin_ttl, kDefaultKvSoftPinTtlFlagValue,
               "Default soft pin TTL for kv objects. Supports raw milliseconds "
               "or duration strings with ms, s, m, or h suffixes");
+DEFINE_string(max_kv_soft_pin_ttl, kDefaultMaxKvSoftPinTtlFlagValue,
+              "Maximum request-level soft pin TTL for kv objects. Supports "
+              "raw milliseconds or duration strings with ms, s, m, or h "
+              "suffixes");
 DEFINE_bool(allow_evict_soft_pinned_objects,
             mooncake::DEFAULT_ALLOW_EVICT_SOFT_PINNED_OBJECTS,
             "Whether to allow eviction of soft pinned objects during eviction");
 DEFINE_validator(default_kv_lease_ttl, ValidateDurationFlag);
 DEFINE_validator(default_kv_soft_pin_ttl, ValidateDurationFlag);
+DEFINE_validator(max_kv_soft_pin_ttl, ValidateDurationFlag);
 DEFINE_double(eviction_ratio, mooncake::DEFAULT_EVICTION_RATIO,
               "Ratio of objects to evict when Memory space is full");
 DEFINE_double(eviction_high_watermark_ratio,
               mooncake::DEFAULT_EVICTION_HIGH_WATERMARK_RATIO,
               "Ratio of high watermark trigger eviction in Memory");
+DEFINE_double(tenant_eviction_high_watermark_ratio,
+              mooncake::DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO,
+              "Per-tenant high watermark, as a fraction of that tenant's own "
+              "effective quota, at which background eviction starts for it. "
+              "Defaults to the same value as -eviction_high_watermark_ratio; "
+              "0 disables it. Only meaningful with -enable_multi_tenants. "
+              "This is the only mechanism that frees space for a tenant: "
+              "admission itself never evicts, it rejects with "
+              "TENANT_QUOTA_EXCEEDED. Without it, a tenant whose effective "
+              "quota sits at or below eviction_high_watermark_ratio reaches "
+              "its own ceiling before the pool crosses the pool-wide "
+              "watermark, so nothing ever reclaims on its behalf");
 DEFINE_double(nof_eviction_ratio, mooncake::DEFAULT_NOF_EVICTION_RATIO,
               "Ratio of objects to evict when NoF SSD space is full");
 DEFINE_double(nof_eviction_high_watermark_ratio,
@@ -163,6 +191,15 @@ DEFINE_validator(eviction_ratio, [](const char* flagname, double value) {
     }
     return true;
 });
+DEFINE_validator(tenant_eviction_high_watermark_ratio,
+                 [](const char* flagname, double value) {
+                     if (value < 0.0 || value > 1.0) {
+                         LOG(FATAL) << "Tenant eviction high watermark ratio "
+                                       "must be between 0.0 and 1.0";
+                         return false;
+                     }
+                     return true;
+                 });
 DEFINE_validator(nof_eviction_ratio, [](const char* flagname, double value) {
     if (value < 0.0 || value > 1.0) {
         LOG(FATAL) << "NoF eviction ratio must be between 0.0 and 1.0";
@@ -225,24 +262,35 @@ DEFINE_uint32(promotion_max_per_heartbeat, 1,
               "SSD-read + RDMA-write on the client; serializing them avoids "
               "blocking past the client-liveness window. Default 1 is "
               "conservative.");
+DEFINE_string(dynamic_replication_mode, "off",
+              "Dynamic MEMORY replica fanout mode: off, observe, or enforce");
+DEFINE_uint32(dynamic_replication_heat_window_seconds, 10,
+              "Heat observation window for dynamic MEMORY replication");
+DEFINE_double(
+    dynamic_replication_admission_qps_threshold, 0.8,
+    "Per-key access frequency threshold for dynamic MEMORY replication");
+DEFINE_uint64(
+    dynamic_replication_max_memory_replicas, 2,
+    "Maximum MEMORY replicas allowed for one dynamically replicated key");
 DEFINE_bool(enable_kv_events, false,
             "Enable RFC #1527 KV cache event publisher over ZMQ");
 DEFINE_string(kv_events_bind_endpoint, "",
               "ZMQ PUB bind endpoint for KV events, e.g. tcp://0.0.0.0:5557");
 DEFINE_string(kv_events_model_name, "",
-              "Deprecated: not emitted on events; use indexer POST /register");
+              "Fixed model name fallback for published KV events");
 DEFINE_string(kv_events_backend_id, "",
               "backend_id for published KV events (cache owner identity)");
 DEFINE_string(kv_events_tenant_id, "default",
-              "Deprecated: tenant_id comes from each object on events");
+              "Config compatibility default; events use per-object tenant_id");
 DEFINE_string(kv_events_additional_salt, "",
-              "Deprecated: not emitted on events; use indexer POST /register");
-DEFINE_string(kv_events_lora_name, "",
-              "Deprecated: not emitted on events (no LoRA context in master)");
+              "Fixed hash namespace salt for published KV events");
+DEFINE_string(
+    kv_events_lora_name, "",
+    "Fixed LoRA name for published KV events; empty means base model");
 DEFINE_uint32(kv_events_block_size, 0,
-              "Deprecated: not emitted on events; use indexer POST /register");
+              "Fixed KV block size for published events; 0 means unknown");
 DEFINE_uint32(kv_events_dp_rank, 0,
-              "Deprecated: not emitted on events; use indexer POST /register");
+              "Fixed data-parallel rank for published KV events");
 DEFINE_bool(kv_events_emit_legacy_compat, true,
             "Include vLLM/SGLang-compatible type/block_hashes fields");
 DEFINE_bool(kv_events_emit_object_key, true,
@@ -258,11 +306,16 @@ DEFINE_string(ha_backend_connstring, "",
 DEFINE_string(
     etcd_endpoints, "",
     "Endpoints of ETCD server, separated by semicolon, required in HA mode");
-DEFINE_int64(
-    client_ttl, mooncake::DEFAULT_CLIENT_LIVE_TTL_SEC,
-    "Seconds a client stays considered alive after the last heartbeat. "
-    "If this TTL elapses without a refresh, the master treats the "
-    "client as disconnected and may unmount its segments");
+DEFINE_int64(client_ttl, mooncake::DEFAULT_CLIENT_LIVE_TTL_SEC,
+             "Deprecated alias for --client_active_ttl_sec");
+DEFINE_int64(client_active_ttl_sec, mooncake::DEFAULT_CLIENT_LIVE_TTL_SEC,
+             "Seconds a client remains active after its last liveness "
+             "observation");
+DEFINE_int64(client_suspicion_ttl_sec,
+             mooncake::DEFAULT_CLIENT_SUSPICION_TTL_SEC,
+             "Seconds a suspected client may recover before going offline; "
+             "defaults to 20 seconds, or to an explicitly configured active "
+             "TTL when omitted");
 DEFINE_int64(nof_heartbeat_interval_sec,
              mooncake::DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC,
              "How often master probes each mounted NoF segment");
@@ -287,6 +340,10 @@ DEFINE_string(cluster_id, mooncake::DEFAULT_CLUSTER_ID,
 // OpLog store configuration
 DEFINE_bool(enable_oplog, false,
             "Enable HA metadata replication through batch-record OpLog");
+DEFINE_bool(enable_oplog_snapshot, false,
+            "Enable standby batch OpLog snapshot production");
+DEFINE_uint64(snapshot_chunk_object_count, 1000000,
+              "Maximum objects per standby batch OpLog snapshot chunk");
 DEFINE_int32(oplog_poll_interval_ms, 1000,
              "Batch-record standby poll interval.");
 DEFINE_uint32(oplog_batch_max_entries, 1024,
@@ -440,6 +497,8 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
                            FLAGS_enable_metric_reporting);
     default_config.GetUInt32("metrics_port", &master_config.metrics_port,
                              FLAGS_metrics_port);
+    default_config.GetString("metrics_host", &master_config.metrics_host,
+                             FLAGS_metrics_host);
     default_config.GetUInt32("rpc_port", &master_config.rpc_port,
                              FLAGS_rpc_port);
     default_config.GetUInt32("rpc_thread_num", &master_config.rpc_thread_num,
@@ -460,6 +519,9 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
     default_config.GetDurationMs("default_kv_soft_pin_ttl",
                                  &master_config.default_kv_soft_pin_ttl,
                                  mooncake::DEFAULT_KV_SOFT_PIN_TTL_MS);
+    default_config.GetDurationMs("max_kv_soft_pin_ttl",
+                                 &master_config.max_kv_soft_pin_ttl,
+                                 mooncake::DEFAULT_MAX_KV_SOFT_PIN_TTL_MS);
     default_config.GetBool("allow_evict_soft_pinned_objects",
                            &master_config.allow_evict_soft_pinned_objects,
                            FLAGS_allow_evict_soft_pinned_objects);
@@ -468,15 +530,16 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
     default_config.GetDouble("eviction_high_watermark_ratio",
                              &master_config.eviction_high_watermark_ratio,
                              FLAGS_eviction_high_watermark_ratio);
+    default_config.GetDouble(
+        "tenant_eviction_high_watermark_ratio",
+        &master_config.tenant_eviction_high_watermark_ratio,
+        FLAGS_tenant_eviction_high_watermark_ratio);
     default_config.GetDouble("nof_eviction_ratio",
                              &master_config.nof_eviction_ratio,
                              FLAGS_nof_eviction_ratio);
     default_config.GetDouble("nof_eviction_high_watermark_ratio",
                              &master_config.nof_eviction_high_watermark_ratio,
                              FLAGS_nof_eviction_high_watermark_ratio);
-    default_config.GetInt64("client_live_ttl_sec",
-                            &master_config.client_live_ttl_sec,
-                            FLAGS_client_ttl);
     default_config.GetInt64("nof_heartbeat_interval_sec",
                             &master_config.nof_heartbeat_interval_sec,
                             FLAGS_nof_heartbeat_interval_sec);
@@ -518,6 +581,26 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
     default_config.GetUInt32("promotion_max_per_heartbeat",
                              &master_config.promotion_max_per_heartbeat,
                              FLAGS_promotion_max_per_heartbeat);
+    default_config.GetString("dynamic_replication_mode",
+                             &master_config.dynamic_replication_mode,
+                             FLAGS_dynamic_replication_mode);
+    default_config.GetUInt32(
+        "dynamic_replication_heat_window_seconds",
+        &master_config.dynamic_replication_heat_window_seconds,
+        FLAGS_dynamic_replication_heat_window_seconds);
+    default_config.GetDouble(
+        "dynamic_replication_admission_qps_threshold",
+        &master_config.dynamic_replication_admission_qps_threshold,
+        FLAGS_dynamic_replication_admission_qps_threshold);
+    {
+        uint64_t tmp_dynamic_replication_max_memory_replicas =
+            FLAGS_dynamic_replication_max_memory_replicas;
+        default_config.GetUInt64("dynamic_replication_max_memory_replicas",
+                                 &tmp_dynamic_replication_max_memory_replicas,
+                                 FLAGS_dynamic_replication_max_memory_replicas);
+        master_config.dynamic_replication_max_memory_replicas =
+            static_cast<size_t>(tmp_dynamic_replication_max_memory_replicas);
+    }
     default_config.GetBool("enable_kv_events", &master_config.enable_kv_events,
                            FLAGS_enable_kv_events);
     default_config.GetString("kv_events_bind_endpoint",
@@ -564,6 +647,12 @@ void InitMasterConf(const mooncake::DefaultConfig& default_config,
                              FLAGS_cluster_id);
     default_config.GetBool("enable_oplog", &master_config.enable_oplog,
                            FLAGS_enable_oplog);
+    default_config.GetBool("enable_oplog_snapshot",
+                           &master_config.enable_oplog_snapshot,
+                           FLAGS_enable_oplog_snapshot);
+    default_config.GetUInt64("snapshot_chunk_object_count",
+                             &master_config.snapshot_chunk_object_count,
+                             FLAGS_snapshot_chunk_object_count);
     default_config.GetInt32("oplog_poll_interval_ms",
                             &master_config.oplog_poll_interval_ms,
                             FLAGS_oplog_poll_interval_ms);
@@ -780,6 +869,11 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         !conf_set) {
         master_config.metrics_port = FLAGS_metrics_port;
     }
+    if ((google::GetCommandLineFlagInfo("metrics_host", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.metrics_host = FLAGS_metrics_host;
+    }
     if ((google::GetCommandLineFlagInfo("default_kv_lease_ttl", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -792,6 +886,12 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         master_config.default_kv_soft_pin_ttl = ParseDurationFlagOrDie(
             "default_kv_soft_pin_ttl", FLAGS_default_kv_soft_pin_ttl);
     }
+    if ((google::GetCommandLineFlagInfo("max_kv_soft_pin_ttl", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.max_kv_soft_pin_ttl = ParseDurationFlagOrDie(
+            "max_kv_soft_pin_ttl", FLAGS_max_kv_soft_pin_ttl);
+    }
     if ((google::GetCommandLineFlagInfo("allow_evict_soft_pinned_objects",
                                         &info) &&
          !info.is_default) ||
@@ -811,6 +911,13 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         master_config.eviction_high_watermark_ratio =
             FLAGS_eviction_high_watermark_ratio;
     }
+    if ((google::GetCommandLineFlagInfo("tenant_eviction_high_watermark_ratio",
+                                        &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.tenant_eviction_high_watermark_ratio =
+            FLAGS_tenant_eviction_high_watermark_ratio;
+    }
     if ((google::GetCommandLineFlagInfo("nof_eviction_ratio", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -877,6 +984,32 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         master_config.promotion_max_per_heartbeat =
             FLAGS_promotion_max_per_heartbeat;
     }
+    if ((google::GetCommandLineFlagInfo("dynamic_replication_mode", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.dynamic_replication_mode = FLAGS_dynamic_replication_mode;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "dynamic_replication_heat_window_seconds", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.dynamic_replication_heat_window_seconds =
+            FLAGS_dynamic_replication_heat_window_seconds;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "dynamic_replication_admission_qps_threshold", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.dynamic_replication_admission_qps_threshold =
+            FLAGS_dynamic_replication_admission_qps_threshold;
+    }
+    if ((google::GetCommandLineFlagInfo(
+             "dynamic_replication_max_memory_replicas", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.dynamic_replication_max_memory_replicas =
+            static_cast<size_t>(FLAGS_dynamic_replication_max_memory_replicas);
+    }
     if ((google::GetCommandLineFlagInfo("enable_kv_events", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -954,6 +1087,25 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
                      << "silence this warning.";
         master_config.promotion_admission_threshold = 255;
     }
+    if (master_config.dynamic_replication_mode != "off" &&
+        master_config.dynamic_replication_mode != "observe" &&
+        master_config.dynamic_replication_mode != "enforce") {
+        LOG(FATAL)
+            << "dynamic_replication_mode must be one of off, observe, enforce";
+    }
+    if (master_config.dynamic_replication_heat_window_seconds == 0) {
+        LOG(WARNING)
+            << "dynamic_replication_heat_window_seconds=0; clamping to 1";
+        master_config.dynamic_replication_heat_window_seconds = 1;
+    }
+    if (master_config.dynamic_replication_admission_qps_threshold <= 0.0) {
+        LOG(FATAL) << "dynamic_replication_admission_qps_threshold must be > 0";
+    }
+    if (master_config.dynamic_replication_max_memory_replicas == 0) {
+        LOG(WARNING)
+            << "dynamic_replication_max_memory_replicas=0; clamping to 1";
+        master_config.dynamic_replication_max_memory_replicas = 1;
+    }
     if ((google::GetCommandLineFlagInfo("ha_backend_type", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -969,11 +1121,6 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         !conf_set) {
         master_config.etcd_endpoints = FLAGS_etcd_endpoints;
     }
-    if ((google::GetCommandLineFlagInfo("client_ttl", &info) &&
-         !info.is_default) ||
-        !conf_set) {
-        master_config.client_live_ttl_sec = FLAGS_client_ttl;
-    }
     if ((google::GetCommandLineFlagInfo("nof_heartbeat_interval_sec", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -1004,6 +1151,17 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
         !conf_set) {
         master_config.enable_oplog = FLAGS_enable_oplog;
     }
+    if ((google::GetCommandLineFlagInfo("enable_oplog_snapshot", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.enable_oplog_snapshot = FLAGS_enable_oplog_snapshot;
+    }
+    if ((google::GetCommandLineFlagInfo("snapshot_chunk_object_count", &info) &&
+         !info.is_default) ||
+        !conf_set) {
+        master_config.snapshot_chunk_object_count =
+            FLAGS_snapshot_chunk_object_count;
+    }
     if ((google::GetCommandLineFlagInfo("oplog_poll_interval_ms", &info) &&
          !info.is_default) ||
         !conf_set) {
@@ -1265,6 +1423,61 @@ void LoadConfigFromCmdline(mooncake::MasterConfig& master_config,
     }
 }
 
+std::optional<int64_t> GetConfiguredInt64(
+    const mooncake::DefaultConfig* default_config, const std::string& key) {
+    if (default_config == nullptr || !default_config->Contains(key)) {
+        return std::nullopt;
+    }
+    int64_t value = 0;
+    default_config->GetInt64(key, &value);
+    return value;
+}
+
+std::optional<int64_t> GetExplicitInt64Flag(const char* name, int64_t value) {
+    google::CommandLineFlagInfo info;
+    if (google::GetCommandLineFlagInfo(name, &info) && !info.is_default) {
+        return value;
+    }
+    return std::nullopt;
+}
+
+void InitClientLivenessConf(const mooncake::DefaultConfig* default_config,
+                            mooncake::MasterConfig& master_config) {
+    const mooncake::ClientLivenessConfigSource config_file{
+        .active_ttl_sec =
+            GetConfiguredInt64(default_config, "client_active_ttl_sec"),
+        .legacy_ttl_sec =
+            GetConfiguredInt64(default_config, "client_live_ttl_sec"),
+        .suspicion_ttl_sec =
+            GetConfiguredInt64(default_config, "client_suspicion_ttl_sec"),
+    };
+    const mooncake::ClientLivenessConfigSource command_line{
+        .active_ttl_sec = GetExplicitInt64Flag("client_active_ttl_sec",
+                                               FLAGS_client_active_ttl_sec),
+        .legacy_ttl_sec = GetExplicitInt64Flag("client_ttl", FLAGS_client_ttl),
+        .suspicion_ttl_sec = GetExplicitInt64Flag(
+            "client_suspicion_ttl_sec", FLAGS_client_suspicion_ttl_sec),
+    };
+
+    const auto resolved = mooncake::ResolveClientLivenessConfig(
+        config_file, command_line, mooncake::DEFAULT_CLIENT_LIVE_TTL_SEC,
+        mooncake::DEFAULT_CLIENT_SUSPICION_TTL_SEC);
+    if (resolved.config_active_conflict) {
+        LOG(WARNING) << "Both client_active_ttl_sec and deprecated "
+                        "client_live_ttl_sec are configured with different "
+                        "values; using client_active_ttl_sec="
+                     << *config_file.active_ttl_sec;
+    }
+    if (resolved.command_line_active_conflict) {
+        LOG(WARNING) << "Both --client_active_ttl_sec and deprecated "
+                        "--client_ttl are set with different values; using "
+                        "--client_active_ttl_sec="
+                     << *command_line.active_ttl_sec;
+    }
+    master_config.client_active_ttl_sec = resolved.active_ttl_sec;
+    master_config.client_suspicion_ttl_sec = resolved.suspicion_ttl_sec;
+}
+
 // Function to start HTTP metadata server
 std::unique_ptr<mooncake::HttpMetadataServer> StartHttpMetadataServer(
     int port, const std::string& host) {
@@ -1308,12 +1521,18 @@ int main(int argc, char* argv[]) {
         google::SetLogDestination(google::GLOG_FATAL, "");
         google::SetLogSymlink(google::GLOG_INFO, "mooncake_master");
     }
+    mooncake::LogAllocatorStatus();
+    mooncake::InstallAllocatorStatsCollector();
+
+    LOG(INFO) << "Mooncake master version: "
+              << mooncake::MOONCAKE_DISPLAY_VERSION;
 
     // Initialize the master configuration
     mooncake::MasterConfig master_config;
     std::string conf_path = FLAGS_config_path;
+    mooncake::DefaultConfig default_config;
+    const mooncake::DefaultConfig* loaded_default_config = nullptr;
     if (!conf_path.empty()) {
-        mooncake::DefaultConfig default_config;
         default_config.SetPath(conf_path);
         try {
             default_config.Load();
@@ -1322,8 +1541,15 @@ int main(int argc, char* argv[]) {
             return 1;
         }
         InitMasterConf(default_config, master_config);
+        loaded_default_config = &default_config;
     }
     LoadConfigFromCmdline(master_config, !conf_path.empty());
+    try {
+        InitClientLivenessConf(loaded_default_config, master_config);
+    } catch (const std::invalid_argument& error) {
+        LOG(ERROR) << "Invalid Client liveness configuration: " << error.what();
+        return 1;
+    }
     ResolveRpcAddressFromInterfaceOrDie(master_config);
 
     // Fall back to environment variables for pod identity (K8s Downward API)
@@ -1354,6 +1580,10 @@ int main(int argc, char* argv[]) {
         LOG(FATAL) << "enable_oplog currently requires ha_backend_type=etcd";
         return 1;
     }
+    if (auto error = ValidateBatchOpLogSnapshotConfig(master_config)) {
+        LOG(FATAL) << *error;
+        return 1;
+    }
     if (!master_config.enable_ha && (!ha_backend_connstring.empty() ||
                                      !master_config.etcd_endpoints.empty())) {
         LOG(WARNING)
@@ -1376,11 +1606,16 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
-    const char* value = std::getenv("MC_RPC_PROTOCOL");
-    std::string protocol = "tcp";
-    if (value && std::string_view(value) == "rdma") {
-        protocol = "rdma";
-    }
+    const auto rpc_protocol_config =
+        mooncake::RpcProtocolConfig::FromEnvironment();
+#ifdef YLT_ENABLE_IBV
+    const std::string protocol = rpc_protocol_config.use_rdma ? "rdma" : "tcp";
+#else
+    const std::string protocol = "tcp";
+    if (rpc_protocol_config.use_rdma) {
+        LOG(WARNING) << "RDMA RPC is disabled at compile time; using TCP RPC";
+    }
+#endif
 
     // enable_metadata_cleanup_on_timeout requires a reachable HTTP metadata
     // server. Two topologies are supported:
@@ -1421,15 +1656,22 @@ int main(int argc, char* argv[]) {
         << ", max_threads=" << master_config.rpc_thread_num
         << ", enable_metric_reporting=" << master_config.enable_metric_reporting
         << ", metrics_port=" << master_config.metrics_port
+        << ", metrics_host=" << master_config.metrics_host
         << ", default_kv_lease_ttl=" << master_config.default_kv_lease_ttl
         << ", default_kv_soft_pin_ttl=" << master_config.default_kv_soft_pin_ttl
+        << ", max_kv_soft_pin_ttl=" << master_config.max_kv_soft_pin_ttl
         << ", allow_evict_soft_pinned_objects="
         << master_config.allow_evict_soft_pinned_objects
         << ", eviction_ratio=" << master_config.eviction_ratio
         << ", eviction_high_watermark_ratio="
         << master_config.eviction_high_watermark_ratio
+        << ", tenant_eviction_high_watermark_ratio="
+        << master_config.tenant_eviction_high_watermark_ratio
         << ", enable_ha=" << master_config.enable_ha
         << ", enable_oplog=" << master_config.enable_oplog
+        << ", enable_oplog_snapshot=" << master_config.enable_oplog_snapshot
+        << ", snapshot_chunk_object_count="
+        << master_config.snapshot_chunk_object_count
         << ", enable_offload=" << master_config.enable_offload
         << ", enable_kv_events=" << master_config.enable_kv_events
         << ", kv_events_bind_endpoint=" << master_config.kv_events_bind_endpoint
@@ -1441,7 +1683,9 @@ int main(int argc, char* argv[]) {
         << ", ha_backend_type=" << master_config.ha_backend_type
         << ", ha_backend_connstring=" << ha_backend_connstring
         << ", etcd_endpoints=" << master_config.etcd_endpoints
-        << ", client_ttl=" << master_config.client_live_ttl_sec
+        << ", client_active_ttl_sec=" << master_config.client_active_ttl_sec
+        << ", client_suspicion_ttl_sec="
+        << master_config.client_suspicion_ttl_sec
         << ", rpc_thread_num=" << master_config.rpc_thread_num
         << ", rpc_port=" << master_config.rpc_port
         << ", rpc_address=" << master_config.rpc_address
@@ -1531,9 +1775,13 @@ int main(int argc, char* argv[]) {
             master_config.rpc_address,
             std::chrono::seconds(master_config.rpc_conn_timeout_seconds),
             master_config.rpc_enable_tcp_no_delay);
-        const char* value = std::getenv("MC_RPC_PROTOCOL");
-        if (value && std::string_view(value) == "rdma") {
+        if (rpc_protocol_config.use_rdma) {
+#ifdef YLT_ENABLE_IBV
             server.init_ibv();
+#else
+            LOG(WARNING)
+                << "RDMA RPC is disabled at compile time; using TCP RPC";
+#endif
         }
         auto wrapped_master_service =
             std::make_shared<mooncake::WrappedMasterService>(
@@ -1541,7 +1789,7 @@ int main(int argc, char* argv[]) {
                 metadata_server_ptr, http_metadata_remote_url);
         mooncake::MasterAdminServer admin_server(
             static_cast<uint16_t>(master_config.metrics_port),
-            master_config.enable_metric_reporting);
+            master_config.enable_metric_reporting, master_config.metrics_host);
         if (!admin_server.Start()) {
             LOG(ERROR) << "Failed to start master admin server";
             return 1;
diff --git a/mooncake-store/src/master_admin_service.cpp b/mooncake-store/src/master_admin_service.cpp
index 950f02fd60..f98cb8d334 100644
--- a/mooncake-store/src/master_admin_service.cpp
+++ b/mooncake-store/src/master_admin_service.cpp
@@ -10,7 +10,14 @@
 #include <utility>
 #include <vector>
 
+#include <asio/executor_work_guard.hpp>
 #include <glog/logging.h>
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+#include <ylt/coro_io/coro_io.hpp>
 #include <ylt/reflection/user_reflect_macro.hpp>
 #include <ylt/struct_json/json_reader.h>
 #include <ylt/struct_json/json_writer.h>
@@ -21,6 +28,7 @@
 #include "master_metric_manager.h"
 #include "rpc_service.h"
 #include "types.h"
+#include "version.h"
 
 namespace mooncake {
 
@@ -171,20 +179,24 @@ std::string EscapePrometheusLabel(std::string_view input) {
     return escaped;
 }
 
+struct HttpDfsShardCountResponse {
+    bool success{true};
+    int shard_count{0};
+};
+YLT_REFL(HttpDfsShardCountResponse, success, shard_count);
+
 struct HttpTenantQuotaSnapshot {
     std::string tenant_id;
     uint64_t requested_quota_bytes{0};
     uint64_t effective_quota_bytes{0};
-    uint64_t used_bytes{0};
-    uint64_t reserved_bytes{0};
-    uint64_t committed_count{0};
-    uint64_t metadata_object_count{0};
+    uint64_t charged_bytes{0};
+    bool admission_closed{true};
     bool over_quota{false};
     bool has_explicit_policy{false};
 };
 YLT_REFL(HttpTenantQuotaSnapshot, tenant_id, requested_quota_bytes,
-         effective_quota_bytes, used_bytes, reserved_bytes, committed_count,
-         metadata_object_count, over_quota, has_explicit_policy);
+         effective_quota_bytes, charged_bytes, admission_closed, over_quota,
+         has_explicit_policy);
 
 HttpTenantQuotaSnapshot ToHttpTenantQuotaSnapshot(
     const TenantQuotaSnapshot& snapshot) {
@@ -192,10 +204,8 @@ HttpTenantQuotaSnapshot ToHttpTenantQuotaSnapshot(
         .tenant_id = snapshot.tenant_id.value(),
         .requested_quota_bytes = snapshot.requested_quota_bytes,
         .effective_quota_bytes = snapshot.effective_quota_bytes,
-        .used_bytes = snapshot.used_bytes,
-        .reserved_bytes = snapshot.reserved_bytes,
-        .committed_count = snapshot.committed_count,
-        .metadata_object_count = snapshot.metadata_object_count,
+        .charged_bytes = snapshot.charged_bytes,
+        .admission_closed = snapshot.admission_closed,
         .over_quota = snapshot.over_quota,
         .has_explicit_policy = snapshot.has_explicit_policy,
     };
@@ -252,10 +262,12 @@ tl::expected<HttpTenantQuotaPolicyRequest, std::string> ParseQuotaPolicyBody(
 }  // namespace
 
 MasterAdminServer::MasterAdminServer(uint16_t http_port,
-                                     bool enable_metric_reporting)
+                                     bool enable_metric_reporting,
+                                     std::string http_host)
     : http_port_(http_port),
+      http_host_(std::move(http_host)),
       enable_metric_reporting_(enable_metric_reporting),
-      http_server_(4, http_port) {}
+      http_server_(4, http_port, http_host_) {}
 
 MasterAdminServer::~MasterAdminServer() { Stop(); }
 
@@ -268,8 +280,8 @@ bool MasterAdminServer::Start() {
 
     auto ec = http_server_.async_start();
     if (ec.hasResult()) {
-        LOG(ERROR) << "Failed to start master admin server on port "
-                   << http_port_;
+        LOG(ERROR) << "Failed to start master admin server on " << http_host_
+                   << ":" << http_port_ << ": " << ec.value().message();
         return false;
     }
 
@@ -278,6 +290,7 @@ bool MasterAdminServer::Start() {
         metric_report_running_.store(true);
         metric_report_thread_ = std::thread([this]() {
             while (metric_report_running_.load()) {
+                RefreshStorageMetrics();
                 const auto snapshot = SnapshotState();
                 std::ostringstream log_stream;
                 log_stream << "Master Admin Metrics: role="
@@ -336,16 +349,32 @@ void MasterAdminServer::SetObservedLeader(
 
 void MasterAdminServer::SetServiceDelegate(
     std::shared_ptr<WrappedMasterService> service) {
-    std::lock_guard<std::mutex> lock(state_mutex_);
-    service_ = std::move(service);
-    if (!service_) {
-        service_available_ = false;
+    std::lock_guard<std::mutex> refresh_lock(storage_metrics_refresh_mutex_);
+    bool clear_storage_metrics = false;
+    {
+        std::lock_guard<std::mutex> lock(state_mutex_);
+        service_ = std::move(service);
+        if (!service_) {
+            service_available_ = false;
+        }
+        clear_storage_metrics = !service_available_;
+    }
+    if (clear_storage_metrics) {
+        MasterMetricManager::instance().project_storage_usage({});
     }
 }
 
 void MasterAdminServer::SetServiceAvailable(bool available) {
-    std::lock_guard<std::mutex> lock(state_mutex_);
-    service_available_ = available && service_ != nullptr;
+    std::lock_guard<std::mutex> refresh_lock(storage_metrics_refresh_mutex_);
+    bool service_available = false;
+    {
+        std::lock_guard<std::mutex> lock(state_mutex_);
+        service_available_ = available && service_ != nullptr;
+        service_available = service_available_;
+    }
+    if (!service_available) {
+        MasterMetricManager::instance().project_storage_usage({});
+    }
 }
 
 MasterAdminServer::RuntimeSnapshot MasterAdminServer::SnapshotState() const {
@@ -359,6 +388,7 @@ MasterAdminServer::RuntimeSnapshot MasterAdminServer::SnapshotState() const {
 }
 
 std::string MasterAdminServer::BuildMetricsText() const {
+    RefreshStorageMetrics();
     std::string metrics = AppendMetricSections(
         MasterMetricManager::instance().serialize_metrics(),
         HAMetricManager::instance().serialize_metrics());
@@ -391,18 +421,12 @@ std::string MasterAdminServer::BuildTenantQuotaMetricsText() const {
         << "# HELP mooncake_tenant_quota_effective_bytes Effective tenant "
            "quota in bytes\n"
         << "# TYPE mooncake_tenant_quota_effective_bytes gauge\n"
-        << "# HELP mooncake_tenant_quota_used_bytes Tenant committed quota "
-           "usage in bytes\n"
-        << "# TYPE mooncake_tenant_quota_used_bytes gauge\n"
-        << "# HELP mooncake_tenant_quota_reserved_bytes Tenant reserved quota "
-           "usage in bytes\n"
-        << "# TYPE mooncake_tenant_quota_reserved_bytes gauge\n"
-        << "# HELP mooncake_tenant_quota_committed_count Tenant committed "
-           "object count\n"
-        << "# TYPE mooncake_tenant_quota_committed_count gauge\n"
-        << "# HELP mooncake_tenant_quota_metadata_object_count Tenant "
-           "metadata object count\n"
-        << "# TYPE mooncake_tenant_quota_metadata_object_count gauge\n"
+        << "# HELP mooncake_tenant_quota_charged_bytes Tenant quota charge in "
+           "bytes\n"
+        << "# TYPE mooncake_tenant_quota_charged_bytes gauge\n"
+        << "# HELP mooncake_tenant_quota_admission_closed Tenant quota "
+           "admission-closed flag\n"
+        << "# TYPE mooncake_tenant_quota_admission_closed gauge\n"
         << "# HELP mooncake_tenant_quota_over_quota Tenant over-quota flag\n"
         << "# TYPE mooncake_tenant_quota_over_quota gauge\n"
         << "# HELP mooncake_tenant_quota_explicit_policy Tenant explicit "
@@ -418,15 +442,11 @@ std::string MasterAdminServer::BuildTenantQuotaMetricsText() const {
         tenant_metrics << "mooncake_tenant_quota_effective_bytes{tenant_id=\""
                        << tenant << "\"} " << snapshot.effective_quota_bytes
                        << "\n";
-        tenant_metrics << "mooncake_tenant_quota_used_bytes{tenant_id=\""
-                       << tenant << "\"} " << snapshot.used_bytes << "\n";
-        tenant_metrics << "mooncake_tenant_quota_reserved_bytes{tenant_id=\""
-                       << tenant << "\"} " << snapshot.reserved_bytes << "\n";
-        tenant_metrics << "mooncake_tenant_quota_committed_count{tenant_id=\""
-                       << tenant << "\"} " << snapshot.committed_count << "\n";
-        tenant_metrics
-            << "mooncake_tenant_quota_metadata_object_count{tenant_id=\""
-            << tenant << "\"} " << snapshot.metadata_object_count << "\n";
+        tenant_metrics << "mooncake_tenant_quota_charged_bytes{tenant_id=\""
+                       << tenant << "\"} " << snapshot.charged_bytes << "\n";
+        tenant_metrics << "mooncake_tenant_quota_admission_closed{tenant_id=\""
+                       << tenant << "\"} "
+                       << (snapshot.admission_closed ? 1 : 0) << "\n";
         tenant_metrics << "mooncake_tenant_quota_over_quota{tenant_id=\""
                        << tenant << "\"} " << (snapshot.over_quota ? 1 : 0)
                        << "\n";
@@ -454,6 +474,7 @@ std::string MasterAdminServer::BuildTenantQuotaMetricsText() const {
 }
 
 std::string MasterAdminServer::BuildMetricsSummaryText() const {
+    RefreshStorageMetrics();
     const auto snapshot = SnapshotState();
     std::ostringstream oss;
     oss << "role=" << ha::MasterRuntimeRoleToString(snapshot.state)
@@ -494,6 +515,20 @@ void MasterAdminServer::HandleHealth(coro_http::coro_http_request&,
     WriteJsonResponse(resp, coro_http::status_type::ok, payload);
 }
 
+struct HttpVersionResponse {
+    std::string version;
+    std::string display_version;
+};
+YLT_REFL(HttpVersionResponse, version, display_version);
+
+void MasterAdminServer::HandleVersion(coro_http::coro_http_request&,
+                                      coro_http::coro_http_response& resp) {
+    WriteJsonResponse(
+        resp, coro_http::status_type::ok,
+        HttpVersionResponse{.version = GetMooncakeStoreVersion(),
+                            .display_version = MOONCAKE_DISPLAY_VERSION});
+}
+
 struct HttpLeaderResponse {
     bool present{false};
     std::optional<std::string> leader_address;
@@ -522,6 +557,15 @@ std::shared_ptr<WrappedMasterService> MasterAdminServer::GetActiveService()
     return snapshot.service;
 }
 
+void MasterAdminServer::RefreshStorageMetrics() const {
+    std::lock_guard<std::mutex> refresh_lock(storage_metrics_refresh_mutex_);
+    const auto runtime = SnapshotState();
+    const auto storage = runtime.service_available && runtime.service
+                             ? runtime.service->GetStorageUsageSnapshot()
+                             : TieredStorageUsageSnapshot{};
+    MasterMetricManager::instance().project_storage_usage(storage);
+}
+
 template <typename Handler>
 void MasterAdminServer::WithActiveService(coro_http::coro_http_response& resp,
                                           Handler&& handler) const {
@@ -567,10 +611,10 @@ struct HttpKvEventsStatusResponse {
     uint64_t published_batches{0};
     uint64_t published_events{0};
     uint64_t dropped_events{0};
-    uint64_t skipped_unparsed_keys{0};
+    uint64_t skipped_keyless_events{0};
 };
 YLT_REFL(HttpKvEventsStatusResponse, enabled, published_batches,
-         published_events, dropped_events, skipped_unparsed_keys);
+         published_events, dropped_events, skipped_keyless_events);
 
 void MasterAdminServer::HandleKvEventsStatus(
     coro_http::coro_http_request&, coro_http::coro_http_response& resp) {
@@ -582,7 +626,7 @@ void MasterAdminServer::HandleKvEventsStatus(
             payload.published_batches = stats.published_batches;
             payload.published_events = stats.published_events;
             payload.dropped_events = stats.dropped_events;
-            payload.skipped_unparsed_keys = stats.skipped_unparsed_keys;
+            payload.skipped_keyless_events = stats.skipped_keyless_events;
             WriteJsonResponse(resp, coro_http::status_type::ok, payload);
         });
 }
@@ -773,6 +817,87 @@ struct HttpCreateDrainJobResponse {
 YLT_REFL(HttpCreateDrainJobResponse, success, job_id, status, error_code,
          error_message);
 
+void MasterAdminServer::HandleGetDfsShardCount(
+    coro_http::coro_http_request& req, coro_http::coro_http_response& resp) {
+    WithActiveService(resp, [&](auto service) {
+        auto result = service->GetDfsShardCount();
+        if (!result) {
+            WriteErrorResponse(resp, ErrorCodeToHttpStatus(result.error()),
+                               result.error());
+            return;
+        }
+        WriteJsonResponse(resp, coro_http::status_type::ok,
+                          HttpDfsShardCountResponse{true, *result});
+    });
+}
+
+async_simple::coro::Lazy<void> MasterAdminServer::HandleExpandDfsShards(
+    coro_http::coro_http_request& req, coro_http::coro_http_response& resp) {
+    Json::CharReaderBuilder builder;
+    builder["rejectDupKeys"] = true;
+    builder["failIfExtra"] = true;
+    std::unique_ptr<Json::CharReader> reader(builder.newCharReader());
+    Json::Value body;
+    std::string errors;
+    const auto text = req.get_body();
+    const bool parsed =
+        reader->parse(text.data(), text.data() + text.size(), &body, &errors);
+    if (!parsed || !body.isObject() || !body.isMember("shard_count") ||
+        (body["shard_count"].type() != Json::intValue &&
+         body["shard_count"].type() != Json::uintValue) ||
+        !body["shard_count"].isInt() || body["shard_count"].asInt() <= 0) {
+        WriteErrorResponse(resp, coro_http::status_type::bad_request,
+                           ErrorCode::INVALID_PARAMS,
+                           "shard_count must be an integer in [1, INT_MAX]");
+        co_return;
+    }
+    const int shard_count = body["shard_count"].asInt();
+    auto service = GetActiveService();
+    if (!service) {
+        SetServiceUnavailable(resp, "Master service is not available");
+        co_return;
+    }
+    auto running = dfs_expansion_running_;
+    if (running->exchange(true)) {
+        WriteErrorResponse(resp, coro_http::status_type::conflict,
+                           ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS,
+                           "A DFS expansion is already in progress");
+        co_return;
+    }
+    struct ResetRunning {
+        std::shared_ptr<std::atomic<bool>> flag;
+        ~ResetRunning() { flag->store(false); }
+    } reset{running};
+    // Filesystem preparation can block, especially on a shared filesystem.
+    // Retain the HTTP executor until the worker finishes: server stop() drains
+    // that executor, but does not wait for the global blocking pool itself.
+    const auto io_executor =
+        req.get_conn()->get_executor()->get_asio_executor();
+    auto work = asio::make_work_guard(io_executor);
+    // Keep the owning callable and pending operation in the coroutine frame.
+    auto expand = [service, shard_count]() {
+        return service->ExpandDfsShards(shard_count);
+    };
+    auto pending = coro_io::post(expand);
+    auto completion = co_await std::move(pending);
+    // post() resumes on the worker. Response/socket handling must return to
+    // the connection's executor before releasing its outstanding work.
+    co_await coro_io::dispatch(io_executor);
+    if (completion.hasError()) {
+        WriteErrorResponse(resp, coro_http::status_type::internal_server_error,
+                           ErrorCode::INTERNAL_ERROR);
+        co_return;
+    }
+    auto result = std::move(completion).value();
+    if (!result) {
+        WriteErrorResponse(resp, ErrorCodeToHttpStatus(result.error()),
+                           result.error());
+        co_return;
+    }
+    WriteJsonResponse(resp, coro_http::status_type::ok,
+                      HttpDfsShardCountResponse{true, *result});
+}
+
 void MasterAdminServer::HandleCreateDrainJob(
     coro_http::coro_http_request& req, coro_http::coro_http_response& resp) {
     CreateDrainJobRequest request;
@@ -1109,10 +1234,12 @@ void MasterAdminServer::HandleUpsertTenantQuota(
                            ErrorCode::INVALID_PARAMS, body_result.error());
         return;
     }
-    if (body_result->requested_quota_bytes == 0) {
+    if (body_result->requested_quota_bytes == 0 ||
+        body_result->requested_quota_bytes >
+            TenantQuotaAccount::kMaxChargedBytes) {
         WriteErrorResponse(resp, coro_http::status_type::bad_request,
                            ErrorCode::INVALID_PARAMS,
-                           "Tenant quota must be positive");
+                           "Tenant quota must be in [1, 2^63 - 1] bytes");
         return;
     }
 
@@ -1200,6 +1327,10 @@ void MasterAdminServer::RegisterHandler() {
         "/health", [this](coro_http_request& req, coro_http_response& resp) {
             HandleHealth(req, resp);
         });
+    http_server_.set_http_handler<GET>(
+        "/version", [this](coro_http_request& req, coro_http_response& resp) {
+            HandleVersion(req, resp);
+        });
     http_server_.set_http_handler<GET>(
         "/role", [this](coro_http_request& req, coro_http_response& resp) {
             HandleRole(req, resp);
@@ -1242,6 +1373,16 @@ void MasterAdminServer::RegisterHandler() {
         [this](coro_http_request& req, coro_http_response& resp) {
             HandleQuerySegment(req, resp);
         });
+    http_server_.set_http_handler<GET>(
+        "/api/v1/dfs/shard_count",
+        [this](coro_http_request& req, coro_http_response& resp) {
+            HandleGetDfsShardCount(req, resp);
+        });
+    http_server_.set_http_handler<PUT>(
+        "/api/v1/dfs/shard_count",
+        [this](coro_http_request& req, coro_http_response& resp) {
+            return HandleExpandDfsShards(req, resp);
+        });
     http_server_.set_http_handler<POST>(
         "/api/v1/drain_jobs",
         [this](coro_http_request& req, coro_http_response& resp) {
diff --git a/mooncake-store/src/master_client.cpp b/mooncake-store/src/master_client.cpp
index 42fa13974b..217915d3f4 100644
--- a/mooncake-store/src/master_client.cpp
+++ b/mooncake-store/src/master_client.cpp
@@ -13,7 +13,7 @@
 #include "mutex.h"
 #include "rpc_service.h"
 #include "types.h"
-#include "utils/scoped_vlog_timer.h"
+#include "common/scoped_vlog_timer.h"
 #include "master_metric_manager.h"
 #include "version.h"
 
@@ -27,11 +27,21 @@ struct RpcNameTraits<&WrappedMasterService::ExistKey> {
     static constexpr const char* value = "ExistKey";
 };
 
+template <>
+struct RpcNameTraits<&WrappedMasterService::ProbeKey> {
+    static constexpr const char* value = "ProbeKey";
+};
+
 template <>
 struct RpcNameTraits<&WrappedMasterService::BatchExistKey> {
     static constexpr const char* value = "BatchExistKey";
 };
 
+template <>
+struct RpcNameTraits<&WrappedMasterService::BatchProbeKey> {
+    static constexpr const char* value = "BatchProbeKey";
+};
+
 template <>
 struct RpcNameTraits<&WrappedMasterService::GetReplicaList> {
     static constexpr const char* value = "GetReplicaList";
@@ -217,6 +227,11 @@ struct RpcNameTraits<&WrappedMasterService::MountLocalDiskSegment> {
     static constexpr const char* value = "MountLocalDiskSegment";
 };
 
+template <>
+struct RpcNameTraits<&WrappedMasterService::UnmountLocalDiskSegment> {
+    static constexpr const char* value = "UnmountLocalDiskSegment";
+};
+
 template <>
 struct RpcNameTraits<&WrappedMasterService::OffloadObjectHeartbeat> {
     static constexpr const char* value = "OffloadObjectHeartbeat";
@@ -256,16 +271,28 @@ template <>
 struct RpcNameTraits<&WrappedMasterService::CopyStart> {
     static constexpr const char* value = "CopyStart";
 };
+template <>
+struct RpcNameTraits<&WrappedMasterService::DynamicReplicaCopyStart> {
+    static constexpr const char* value = "DynamicReplicaCopyStart";
+};
 
 template <>
 struct RpcNameTraits<&WrappedMasterService::CopyEnd> {
     static constexpr const char* value = "CopyEnd";
 };
+template <>
+struct RpcNameTraits<&WrappedMasterService::DynamicReplicaCopyEnd> {
+    static constexpr const char* value = "DynamicReplicaCopyEnd";
+};
 
 template <>
 struct RpcNameTraits<&WrappedMasterService::CopyRevoke> {
     static constexpr const char* value = "CopyRevoke";
 };
+template <>
+struct RpcNameTraits<&WrappedMasterService::DynamicReplicaCopyRevoke> {
+    static constexpr const char* value = "DynamicReplicaCopyRevoke";
+};
 
 template <>
 struct RpcNameTraits<&WrappedMasterService::MoveStart> {
@@ -323,9 +350,13 @@ struct RpcNameTraits<&WrappedMasterService::PollRemoveAll> {
 };
 
 template <auto ServiceMethod, typename ReturnType, typename... Args>
-tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc(Args&&... args) {
-    auto pool = client_accessor_.GetClientPool();
-
+tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc_with_client_pool(
+    const std::shared_ptr<RpcClientPool::ClientPool>& client_pool,
+    Args&&... args) {
+    RpcDrainGuard::ScopedCall inflight(rpc_drain_);
+    if (!inflight.ok()) {
+        return tl::make_unexpected(ErrorCode::RPC_FAIL);
+    }
     // Increment RPC counter
     if (metrics_) {
         metrics_->rpc_count.inc({RpcNameTraits<ServiceMethod>::value});
@@ -334,7 +365,7 @@ tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc(Args&&... args) {
     auto start_time = std::chrono::steady_clock::now();
     return async_simple::coro::syncAwait(
         [&]() -> async_simple::coro::Lazy<tl::expected<ReturnType, ErrorCode>> {
-            auto ret = co_await pool->send_request(
+            auto ret = co_await client_pool->send_request(
                 [&](coro_io::client_reuse_hint,
                     coro_rpc::coro_rpc_client& client) {
                     return client.send_request<ServiceMethod>(
@@ -365,9 +396,27 @@ tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc(Args&&... args) {
         }());
 }
 
+template <auto ServiceMethod, typename ReturnType, typename... Args>
+tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc_with_pool(
+    RpcClientPool& client_accessor, Args&&... args) {
+    return invoke_rpc_with_client_pool<ServiceMethod, ReturnType>(
+        client_accessor.GetClientPool(), std::forward<Args>(args)...);
+}
+
+template <auto ServiceMethod, typename ReturnType, typename... Args>
+tl::expected<ReturnType, ErrorCode> MasterClient::invoke_rpc(Args&&... args) {
+    return invoke_rpc_with_pool<ServiceMethod, ReturnType>(
+        client_accessor_, std::forward<Args>(args)...);
+}
+
 template <auto ServiceMethod, typename ResultType, typename... Args>
 std::vector<tl::expected<ResultType, ErrorCode>> MasterClient::invoke_batch_rpc(
     size_t input_size, Args&&... args) {
+    RpcDrainGuard::ScopedCall inflight(rpc_drain_);
+    if (!inflight.ok()) {
+        return std::vector<tl::expected<ResultType, ErrorCode>>(
+            input_size, tl::make_unexpected(ErrorCode::RPC_FAIL));
+    }
     auto pool = client_accessor_.GetClientPool();
 
     // Increment RPC counter
@@ -416,21 +465,43 @@ std::vector<tl::expected<ResultType, ErrorCode>> MasterClient::invoke_batch_rpc(
         }());
 }
 
-MasterClient::~MasterClient() = default;
+MasterClient::~MasterClient() {
+    // Never release the pool under a suspended request coroutine (#3909).
+    // 30s is generous: every request carries its own RPC timeout.
+    if (!rpc_drain_.drain_for(std::chrono::seconds(30))) {
+        LOG(ERROR) << "MasterClient teardown: RPCs still in flight after "
+                      "30s drain; releasing the pool regardless";
+    }
+}
+
+void MasterClient::EnableHaConnectionPolicy() {
+    MutexLocker lock(&connect_mutex_);
+    if (!client_addr_param_.empty()) {
+        ha_control_client_accessor_.GetOrCreateClientPool(client_addr_param_);
+    }
+    ha_connection_policy_enabled_.store(true, std::memory_order_release);
+}
 
 ErrorCode MasterClient::Connect(const std::string& master_addr) {
     ScopedVLogTimer timer(1, "MasterClient::Connect");
     timer.LogRequest("master_addr=", master_addr);
 
     MutexLocker lock(&connect_mutex_);
-    if (client_addr_param_ != master_addr) {
+    const bool use_ha_control_pool =
+        ha_connection_policy_enabled_.load(std::memory_order_acquire);
+    if (use_ha_control_pool) {
+        ha_probe_client_accessor_.GetOrCreateClientPool(master_addr);
+    } else {
         client_accessor_.GetOrCreateClientPool(master_addr);
-        client_addr_param_ = master_addr;
     }
     // The client pool does not have native connection check method, so we need
     // to use custom ServiceReady API.
     auto result =
-        invoke_rpc<&WrappedMasterService::ServiceReady, std::string>();
+        use_ha_control_pool
+            ? invoke_rpc_with_pool<&WrappedMasterService::ServiceReady,
+                                   std::string>(ha_probe_client_accessor_)
+            : invoke_rpc_with_pool<&WrappedMasterService::ServiceReady,
+                                   std::string>(client_accessor_);
     if (!result.has_value()) {
         timer.LogResponse("error_code=", result.error());
         return result.error();
@@ -444,6 +515,13 @@ ErrorCode MasterClient::Connect(const std::string& master_addr) {
         timer.LogResponse("error_code=", ErrorCode::INVALID_VERSION);
         return ErrorCode::INVALID_VERSION;
     }
+    if (use_ha_control_pool) {
+        // Only move foreground traffic after the fast control-plane probe has
+        // established that the new leader is ready and version-compatible.
+        client_accessor_.GetOrCreateClientPool(master_addr);
+        ha_control_client_accessor_.GetOrCreateClientPool(master_addr);
+    }
+    client_addr_param_ = master_addr;
     timer.LogResponse("error_code=", ErrorCode::OK);
     return ErrorCode::OK;
 }
@@ -470,6 +548,28 @@ std::vector<tl::expected<bool, ErrorCode>> MasterClient::BatchExistKey(
     return result;
 }
 
+tl::expected<bool, ErrorCode> MasterClient::ProbeKey(
+    const std::string& object_key) {
+    ScopedVLogTimer timer(1, "MasterClient::ProbeKey");
+    timer.LogRequest("object_key=", object_key);
+
+    auto result = invoke_rpc<&WrappedMasterService::ProbeKey, bool>(
+        object_key, tenant_id_.value());
+    timer.LogResponseExpected(result);
+    return result;
+}
+
+std::vector<tl::expected<bool, ErrorCode>> MasterClient::BatchProbeKey(
+    const std::vector<std::string>& object_keys) {
+    ScopedVLogTimer timer(1, "MasterClient::BatchProbeKey");
+    timer.LogRequest("keys_count=", object_keys.size());
+
+    auto result = invoke_batch_rpc<&WrappedMasterService::BatchProbeKey, bool>(
+        object_keys.size(), object_keys, tenant_id_.value());
+    timer.LogResponse("result=", result.size(), " keys");
+    return result;
+}
+
 tl::expected<MasterMetricManager::CacheHitStatDict, ErrorCode>
 MasterClient::CalcCacheStats() {
     return invoke_rpc<&WrappedMasterService::CalcCacheStats,
@@ -501,8 +601,8 @@ MasterClient::BatchReplicaClear(const std::vector<std::string>& object_keys,
                      ", client_id=", client_id,
                      ", segment_name=", segment_name);
     auto result = invoke_rpc<&WrappedMasterService::BatchReplicaClear,
-                             std::vector<std::string>>(object_keys, client_id,
-                                                       segment_name);
+                             std::vector<std::string>>(
+        object_keys, client_id, segment_name, tenant_id_.value());
     timer.LogResponseExpected(result);
     return result;
 }
@@ -892,8 +992,17 @@ tl::expected<PingResponse, ErrorCode> MasterClient::Ping() {
     ScopedVLogTimer timer(1, "MasterClient::Ping");
     timer.LogRequest("client_id=", client_id_);
 
+    std::shared_ptr<RpcClientPool::ClientPool> ping_pool;
+    {
+        MutexLocker lock(&connect_mutex_);
+        ping_pool =
+            ha_connection_policy_enabled_.load(std::memory_order_acquire)
+                ? ha_control_client_accessor_.GetClientPool()
+                : client_accessor_.GetClientPool();
+    }
     auto result =
-        invoke_rpc<&WrappedMasterService::Ping, PingResponse>(client_id_);
+        invoke_rpc_with_client_pool<&WrappedMasterService::Ping, PingResponse>(
+            ping_pool, client_id_);
     timer.LogResponseExpected(result);
     return result;
 }
@@ -942,6 +1051,18 @@ tl::expected<void, ErrorCode> MasterClient::MountLocalDiskSegment(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::UnmountLocalDiskSegment(
+    const UUID& client_id) {
+    ScopedVLogTimer timer(1, "MasterClient::UnmountLocalDiskSegment");
+    timer.LogRequest("client_id=", client_id);
+
+    auto result =
+        invoke_rpc<&WrappedMasterService::UnmountLocalDiskSegment, void>(
+            client_id);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<UUID, ErrorCode> MasterClient::CreateCopyTask(
     const std::string& key, const std::vector<std::string>& targets) {
     return CreateCopyTask(key, tenant_id_.value(), targets);
@@ -1126,6 +1247,26 @@ tl::expected<CopyStartResponse, ErrorCode> MasterClient::CopyStart(
     return result;
 }
 
+tl::expected<CopyStartResponse, ErrorCode>
+MasterClient::DynamicReplicaCopyStart(
+    const std::string& key, const std::string& tenant_id,
+    const std::string& src_segment,
+    const std::vector<std::string>& tgt_segments,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    ScopedVLogTimer timer(1, "MasterClient::DynamicReplicaCopyStart");
+    timer.LogRequest("key=", key, ", tenant_id=", tenant_id,
+                     ", src_segment=", src_segment,
+                     ", tgt_segments_count=", tgt_segments.size());
+
+    auto result = invoke_rpc<&WrappedMasterService::DynamicReplicaCopyStart,
+                             CopyStartResponse>(
+        client_id_, key, tenant_id, src_segment, tgt_segments,
+        dynamic_replication_lease_id, dynamic_replication_version_epoch);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<QueryTaskResponse, ErrorCode> MasterClient::QueryTask(
     const UUID& task_id) {
     ScopedVLogTimer timer(1, "MasterClient::QueryTask");
@@ -1153,6 +1294,21 @@ tl::expected<void, ErrorCode> MasterClient::CopyEnd(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::DynamicReplicaCopyEnd(
+    const std::string& key, const std::string& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    ScopedVLogTimer timer(1, "MasterClient::DynamicReplicaCopyEnd");
+    timer.LogRequest("key=", key, ", tenant_id=", tenant_id);
+
+    auto result =
+        invoke_rpc<&WrappedMasterService::DynamicReplicaCopyEnd, void>(
+            client_id_, key, tenant_id, dynamic_replication_lease_id,
+            dynamic_replication_version_epoch);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<std::vector<TaskAssignment>, ErrorCode> MasterClient::FetchTasks(
     size_t batch_size) {
     ScopedVLogTimer timer(1, "MasterClient::FetchTasks");
@@ -1179,6 +1335,21 @@ tl::expected<void, ErrorCode> MasterClient::CopyRevoke(
     return result;
 }
 
+tl::expected<void, ErrorCode> MasterClient::DynamicReplicaCopyRevoke(
+    const std::string& key, const std::string& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    ScopedVLogTimer timer(1, "MasterClient::DynamicReplicaCopyRevoke");
+    timer.LogRequest("key=", key, ", tenant_id=", tenant_id);
+
+    auto result =
+        invoke_rpc<&WrappedMasterService::DynamicReplicaCopyRevoke, void>(
+            client_id_, key, tenant_id, dynamic_replication_lease_id,
+            dynamic_replication_version_epoch);
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<MoveStartResponse, ErrorCode> MasterClient::MoveStart(
     const std::string& key, const std::string& src_segment,
     const std::string& tgt_segment) {
diff --git a/mooncake-store/src/master_metric_manager.cpp b/mooncake-store/src/master_metric_manager.cpp
index ea52ec91df..396cbe97b4 100644
--- a/mooncake-store/src/master_metric_manager.cpp
+++ b/mooncake-store/src/master_metric_manager.cpp
@@ -7,7 +7,9 @@
 #include <vector>   // Required by histogram serialization
 #include <cmath>
 
-#include "utils.h"
+#include "common/byte_size.h"
+#include "segment.h"
+#include "version.h"
 
 namespace mooncake {
 
@@ -61,12 +63,46 @@ MasterMetricManager::MasterMetricManager()
       // Initialize cluster metrics
       active_clients_("master_active_clients",
                       "Total number of active clients"),
+      client_liveness_active_clients_(
+          "master_client_liveness_active_clients",
+          "Store Client liveness records currently Active"),
+      client_liveness_suspected_clients_(
+          "master_client_liveness_suspected_clients",
+          "Store Client liveness records currently Suspected"),
+      client_liveness_offline_clients_(
+          "master_client_liveness_offline_clients",
+          "Store Client liveness records currently Offline"),
+      client_liveness_suspected_transitions_(
+          "master_client_liveness_suspected_transitions_total",
+          "Store Client Active to Suspected transitions"),
+      client_liveness_recoveries_(
+          "master_client_liveness_recoveries_total",
+          "Store Client Suspected to Active recoveries"),
+      client_liveness_offline_transitions_(
+          "master_client_liveness_offline_transitions_total",
+          "Store Client Suspected to Offline transitions"),
+      pending_client_offboarding_jobs_metric_(
+          "master_client_offboarding_queue_depth",
+          "Queued or running Store Client offboarding jobs"),
+      client_offboarding_duration_ms_(
+          "master_client_offboarding_duration_ms",
+          "Asynchronous Store Client offboarding duration in milliseconds",
+          {1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000, 30000}),
+      client_offboarding_retries_("master_client_offboarding_retries_total",
+                                  "Retried Store Client offboarding attempts"),
+      client_offboarding_alerts_(
+          "master_client_offboarding_alerts_total",
+          "Offboarding retries at or above the operator alert threshold"),
 
       // Initialize Request Counters
       put_start_requests_("master_put_start_requests_total",
                           "Total number of PutStart requests received"),
       put_start_failures_("master_put_start_failures_total",
                           "Total number of failed PutStart requests"),
+      put_start_object_already_exists_(
+          "master_put_start_object_already_exists_total",
+          "Total PutStart requests returning "
+          "OBJECT_ALREADY_EXISTS"),
       put_start_alloc_failures_(
           "master_put_start_alloc_failures_total",
           "Total number of PutStart failures caused by replica allocation "
@@ -235,6 +271,9 @@ MasterMetricManager::MasterMetricManager()
       batch_put_start_failures_(
           "master_batch_put_start_failures_total",
           "Total number of failed BatchPutStart requests"),
+      batch_put_start_object_already_exists_(
+          "master_batch_put_start_object_already_exists_total",
+          "Total BatchPutStart response items with OBJECT_ALREADY_EXISTS"),
       batch_put_start_partial_successes_(
           "master_batch_put_start_partial_successes_total",
           "Total number of partially successful BatchPutStart requests"),
@@ -360,6 +399,11 @@ MasterMetricManager::MasterMetricManager()
           "master_promotion_failed_total",
           "Total promotion tasks aborted by holder via "
           "NotifyPromotionFailure (holder reported a downstream failure)"),
+      promotion_execution_gave_up_(
+          "master_promotion_execution_gave_up_total",
+          "Total promotion admission chains permanently abandoned after "
+          "kMaxPromotionExecutionFailures consecutive execution failures "
+          "(self-sustaining cycle stopped; reads can still re-admit)"),
       promotion_cancelled_(
           "master_promotion_cancelled_total",
           "Total promotion tasks removed because the prerequisite went "
@@ -407,6 +451,23 @@ MasterMetricManager::MasterMetricManager()
       tenant_evict_bytes_total_(
           "mooncake_tenant_evict_bytes_total",
           "Total bytes evicted by tenant-scoped quota eviction", {"tenant_id"}),
+      offload_enqueued_total_(
+          "master_offload_enqueued_total",
+          "SSD offload tasks successfully enqueued (per store worker)",
+          {"client_id"}),
+      offload_completed_total_(
+          "master_offload_completed_total",
+          "SSD offload tasks completed (worker reported OK)", {"client_id"}),
+      offload_failed_total_("master_offload_failed_total",
+                            "SSD offload tasks failed (worker reported NACK)",
+                            {"client_id"}),
+      offload_cancelled_total_(
+          "master_offload_cancelled_total",
+          "SSD offload tasks cancelled (preempted before write)",
+          {"client_id"}),
+      offload_enqueue_rejected_total_(
+          "master_offload_enqueue_rejected_total",
+          "SSD offload tasks rejected at enqueue (queue full)", {"client_id"}),
 
       // Snapshot Metrics
       snapshot_duration_ms_(
@@ -477,9 +538,17 @@ MasterMetricManager::MasterMetricManager()
           "Total number of MarkTaskToComplete requests received"),
       mark_task_to_complete_failures_(
           "master_update_task_failures_total",
-          "Total number of failed MarkTaskToComplete requests") {
+          "Total number of failed MarkTaskToComplete requests"),
+      build_info_("mooncake_build_info",
+                  "Build version of the running master; the value is always 1 "
+                  "and the version strings are carried by the labels",
+                  {{"version", GetMooncakeStoreVersion()},
+                   {"display_version", MOONCAKE_DISPLAY_VERSION}}) {
     // Update all metrics once to ensure zero values are serialized
     update_metrics_for_zero_output();
+    // Info-style metric: emit a single series for the build this binary was
+    // compiled from. Set once here because the value never changes at runtime.
+    build_info_.update(1);
 }
 
 // --- Metric Interface Methods ---
@@ -493,6 +562,10 @@ void MasterMetricManager::update_metrics_for_zero_output() {
     key_count_.update(0);
     soft_pin_key_count_.update(0);
     active_clients_.update(0);
+    client_liveness_active_clients_.update(0);
+    client_liveness_suspected_clients_.update(0);
+    client_liveness_offline_clients_.update(0);
+    pending_client_offboarding_jobs_metric_.update(0);
     mem_cache_nums_.update(0);
     file_cache_nums_.update(0);
     put_start_discarded_staging_size_.update(0);
@@ -500,10 +573,16 @@ void MasterMetricManager::update_metrics_for_zero_output() {
 
     // Update Counters (use inc(0) to mark as changed)
     promotion_admitted_.inc(0);
+    client_liveness_suspected_transitions_.inc(0);
+    client_liveness_recoveries_.inc(0);
+    client_liveness_offline_transitions_.inc(0);
+    client_offboarding_retries_.inc(0);
+    client_offboarding_alerts_.inc(0);
     promotion_completed_.inc(0);
     promotion_completed_bytes_.inc(0);
     promotion_expired_.inc(0);
     promotion_failed_.inc(0);
+    promotion_execution_gave_up_.inc(0);
     promotion_cancelled_.inc(0);
     promotion_rejected_frequency_.inc(0);
     promotion_rejected_watermark_.inc(0);
@@ -516,6 +595,7 @@ void MasterMetricManager::update_metrics_for_zero_output() {
     promotion_candidate_dropped_limit_.inc(0);
     put_start_requests_.inc(0);
     put_start_failures_.inc(0);
+    put_start_object_already_exists_.inc(0);
     put_start_alloc_failures_.inc(0);
     put_start_partial_allocations_.inc(0);
     put_end_requests_.inc(0);
@@ -593,6 +673,7 @@ void MasterMetricManager::update_metrics_for_zero_output() {
     batch_get_replica_list_failed_items_.inc(0);
     batch_put_start_requests_.inc(0);
     batch_put_start_failures_.inc(0);
+    batch_put_start_object_already_exists_.inc(0);
     batch_put_start_partial_successes_.inc(0);
     batch_put_start_items_.inc(0);
     batch_put_start_failed_items_.inc(0);
@@ -627,6 +708,7 @@ void MasterMetricManager::update_metrics_for_zero_output() {
 
     // Update Histogram (use observe(0) to mark as changed)
     value_size_distribution_.observe(0);
+    client_offboarding_duration_ms_.observe(0);
     nof_heartbeat_probe_latency_ms_.observe(0);
 
     // Note: dynamic_gauge_1t (mem_allocated_size_per_segment_ and
@@ -662,6 +744,7 @@ void MasterMetricManager::dec_total_mem_capacity(const std::string& segment,
                                                  int64_t val) {
     mem_total_capacity_.dec(val);
     if (!segment.empty()) mem_total_capacity_per_segment_.dec({segment}, val);
+    remove_segment_metrics(segment);
 }
 
 void MasterMetricManager::reset_total_mem_capacity() {
@@ -676,15 +759,6 @@ int64_t MasterMetricManager::get_total_mem_capacity() {
     return mem_total_capacity_.value();
 }
 
-double MasterMetricManager::get_global_mem_used_ratio(void) {
-    double allocated = mem_allocated_size_.value();
-    double capacity = mem_total_capacity_.value();
-    if (capacity == 0) {
-        return 0.0;
-    }
-    return allocated / capacity;
-}
-
 int64_t MasterMetricManager::get_segment_allocated_mem_size(
     const std::string& segment) {
     return mem_allocated_size_per_segment_.value({segment});
@@ -705,14 +779,14 @@ int64_t MasterMetricManager::get_segment_total_mem_capacity(
     return mem_total_capacity_per_segment_.value({segment});
 }
 
-double MasterMetricManager::get_segment_mem_used_ratio(
-    const std::string& segment) {
-    double allocated = get_segment_allocated_mem_size(segment);
-    double capacity = get_segment_total_mem_capacity(segment);
-    if (capacity == 0) {
-        return 0.0;
+void MasterMetricManager::remove_segment_metrics(const std::string& segment) {
+    if (segment.empty() ||
+        mem_allocated_size_per_segment_.value({segment}) != 0 ||
+        mem_total_capacity_per_segment_.value({segment}) != 0) {
+        return;
     }
-    return allocated / capacity;
+    mem_allocated_size_per_segment_.remove_label_value({{"segment", segment}});
+    mem_total_capacity_per_segment_.remove_label_value({{"segment", segment}});
 }
 
 // NoF segment Metrics
@@ -756,13 +830,44 @@ int64_t MasterMetricManager::get_total_nof_capacity() {
     return nof_total_capacity_.value();
 }
 
-double MasterMetricManager::get_global_nof_used_ratio(void) {
-    double allocated = nof_allocated_size_.value();
-    double capacity = nof_total_capacity_.value();
-    if (capacity == 0) {
-        return 0.0;
-    }
-    return allocated / capacity;
+void MasterMetricManager::project_storage_usage(
+    const TieredStorageUsageSnapshot& snapshot) {
+    std::lock_guard<std::mutex> lock(storage_projection_mutex_);
+
+    auto project_tier = [](const StorageUsageSnapshot& tier,
+                           ylt::metric::gauge_t& allocated,
+                           ylt::metric::gauge_t& capacity,
+                           ylt::metric::dynamic_gauge_1t& allocated_by_segment,
+                           ylt::metric::dynamic_gauge_1t& capacity_by_segment,
+                           std::set<std::string>& projected_segments) {
+        allocated.update(static_cast<int64_t>(tier.used_bytes));
+        capacity.update(static_cast<int64_t>(tier.capacity_bytes));
+
+        std::set<std::string> current_segments;
+        for (const auto& [segment_name, usage] : tier.segments) {
+            current_segments.insert(segment_name);
+            allocated_by_segment.update({segment_name},
+                                        static_cast<int64_t>(usage.used_bytes));
+            capacity_by_segment.update(
+                {segment_name}, static_cast<int64_t>(usage.capacity_bytes));
+        }
+        for (const auto& segment_name : projected_segments) {
+            if (!current_segments.contains(segment_name)) {
+                allocated_by_segment.remove_label_value(
+                    {{"segment", segment_name}});
+                capacity_by_segment.remove_label_value(
+                    {{"segment", segment_name}});
+            }
+        }
+        projected_segments = std::move(current_segments);
+    };
+
+    project_tier(snapshot.memory, mem_allocated_size_, mem_total_capacity_,
+                 mem_allocated_size_per_segment_,
+                 mem_total_capacity_per_segment_, projected_mem_segments_);
+    project_tier(snapshot.nof, nof_allocated_size_, nof_total_capacity_,
+                 nof_allocated_size_per_segment_,
+                 nof_total_capacity_per_segment_, projected_nof_segments_);
 }
 
 int64_t MasterMetricManager::get_segment_allocated_nof_size(
@@ -775,14 +880,10 @@ int64_t MasterMetricManager::get_segment_total_nof_capacity(
     return nof_total_capacity_per_segment_.value({segment});
 }
 
-double MasterMetricManager::get_segment_nof_used_ratio(
+void MasterMetricManager::remove_nof_segment_metrics(
     const std::string& segment) {
-    double allocated = get_segment_allocated_nof_size(segment);
-    double capacity = get_segment_total_nof_capacity(segment);
-    if (capacity == 0) {
-        return 0.0;
-    }
-    return allocated / capacity;
+    nof_allocated_size_per_segment_.remove_label_value({{"segment", segment}});
+    nof_total_capacity_per_segment_.remove_label_value({{"segment", segment}});
 }
 
 // File Storage Metrics
@@ -865,6 +966,79 @@ int64_t MasterMetricManager::get_active_clients() {
     return active_clients_.value();
 }
 
+void MasterMetricManager::client_liveness_record_created() {
+    client_liveness_active_clients_.inc(1);
+}
+
+void MasterMetricManager::client_liveness_became_suspected() {
+    client_liveness_active_clients_.dec(1);
+    client_liveness_suspected_clients_.inc(1);
+    client_liveness_suspected_transitions_.inc(1);
+}
+
+void MasterMetricManager::client_liveness_recovered() {
+    client_liveness_suspected_clients_.dec(1);
+    client_liveness_active_clients_.inc(1);
+    client_liveness_recoveries_.inc(1);
+}
+
+void MasterMetricManager::client_liveness_became_offline() {
+    client_liveness_suspected_clients_.dec(1);
+    client_liveness_offline_clients_.inc(1);
+    client_liveness_offline_transitions_.inc(1);
+}
+
+void MasterMetricManager::on_client_liveness_record_removed(
+    ClientLivenessState state) {
+    switch (state) {
+        case ClientLivenessState::ACTIVE:
+            client_liveness_active_clients_.dec(1);
+            break;
+        case ClientLivenessState::SUSPECTED:
+            client_liveness_suspected_clients_.dec(1);
+            break;
+        case ClientLivenessState::OFFLINE:
+            client_liveness_offline_clients_.dec(1);
+            break;
+    }
+}
+
+void MasterMetricManager::reset_client_liveness_metrics(
+    int64_t active_records) {
+    client_liveness_active_clients_.dec(
+        client_liveness_active_clients_.value());
+    client_liveness_suspected_clients_.dec(
+        client_liveness_suspected_clients_.value());
+    client_liveness_offline_clients_.dec(
+        client_liveness_offline_clients_.value());
+    pending_client_offboarding_jobs_metric_.dec(
+        pending_client_offboarding_jobs_metric_.value());
+    if (active_records > 0) {
+        client_liveness_active_clients_.inc(active_records);
+    }
+}
+
+void MasterMetricManager::inc_client_offboarding_queue_depth(int64_t jobs) {
+    pending_client_offboarding_jobs_metric_.inc(jobs);
+}
+
+void MasterMetricManager::dec_client_offboarding_queue_depth(int64_t jobs) {
+    pending_client_offboarding_jobs_metric_.dec(jobs);
+}
+
+void MasterMetricManager::inc_client_offboarding_retry() {
+    client_offboarding_retries_.inc(1);
+}
+
+void MasterMetricManager::inc_client_offboarding_alert() {
+    client_offboarding_alerts_.inc(1);
+}
+
+void MasterMetricManager::observe_client_offboarding_duration_ms(
+    int64_t duration_ms) {
+    client_offboarding_duration_ms_.observe(duration_ms);
+}
+
 // Store-observed cache reuse metrics
 void MasterMetricManager::inc_mem_cache_hit_nums(int64_t val) {
     mem_cache_hit_nums_.inc(val);
@@ -923,6 +1097,9 @@ void MasterMetricManager::inc_exist_key_failures(int64_t val) {
 void MasterMetricManager::inc_put_start_requests(int64_t val) {
     put_start_requests_.inc(val);
 }
+void MasterMetricManager::inc_put_start_object_already_exists(int64_t val) {
+    put_start_object_already_exists_.inc(val);
+}
 void MasterMetricManager::inc_put_start_failures(int64_t val) {
     put_start_failures_.inc(val);
 }
@@ -1102,6 +1279,10 @@ void MasterMetricManager::inc_batch_put_start_failures(int64_t failed_items) {
     batch_put_start_failures_.inc(1);
     batch_put_start_failed_items_.inc(failed_items);
 }
+void MasterMetricManager::inc_batch_put_start_object_already_exists(
+    int64_t items) {
+    batch_put_start_object_already_exists_.inc(items);
+}
 void MasterMetricManager::inc_batch_put_start_partial_success(
     int64_t failed_items) {
     batch_put_start_partial_successes_.inc(1);
@@ -1169,6 +1350,9 @@ void MasterMetricManager::inc_promotion_expired(int64_t val) {
 void MasterMetricManager::inc_promotion_failed(int64_t val) {
     promotion_failed_.inc(val);
 }
+void MasterMetricManager::inc_promotion_execution_gave_up(int64_t val) {
+    promotion_execution_gave_up_.inc(val);
+}
 void MasterMetricManager::inc_promotion_cancelled(int64_t val) {
     promotion_cancelled_.inc(val);
 }
@@ -1214,6 +1398,31 @@ void MasterMetricManager::inc_tenant_evict_bytes(const std::string& tenant_id,
     tenant_evict_bytes_total_.inc({tenant_id}, bytes);
 }
 
+void MasterMetricManager::inc_offload_enqueued(const std::string& client_id,
+                                               int64_t val) {
+    offload_enqueued_total_.inc({client_id}, val);
+}
+
+void MasterMetricManager::inc_offload_completed(const std::string& client_id,
+                                                int64_t val) {
+    offload_completed_total_.inc({client_id}, val);
+}
+
+void MasterMetricManager::inc_offload_failed(const std::string& client_id,
+                                             int64_t val) {
+    offload_failed_total_.inc({client_id}, val);
+}
+
+void MasterMetricManager::inc_offload_cancelled(const std::string& client_id,
+                                                int64_t val) {
+    offload_cancelled_total_.inc({client_id}, val);
+}
+
+void MasterMetricManager::inc_offload_enqueue_rejected(
+    const std::string& client_id, int64_t val) {
+    offload_enqueue_rejected_total_.inc({client_id}, val);
+}
+
 void MasterMetricManager::set_snapshot_duration_ms(int64_t size) {
     snapshot_duration_ms_.observe(size);
 }
@@ -1226,6 +1435,9 @@ int64_t MasterMetricManager::get_put_start_requests() {
     return put_start_requests_.value();
 }
 
+int64_t MasterMetricManager::get_put_start_object_already_exists() {
+    return put_start_object_already_exists_.value();
+}
 int64_t MasterMetricManager::get_put_start_failures() {
     return put_start_failures_.value();
 }
@@ -1422,6 +1634,10 @@ int64_t MasterMetricManager::get_batch_put_start_failures() {
     return batch_put_start_failures_.value();
 }
 
+int64_t MasterMetricManager::get_batch_put_start_object_already_exists() {
+    return batch_put_start_object_already_exists_.value();
+}
+
 int64_t MasterMetricManager::get_batch_put_start_partial_successes() {
     return batch_put_start_partial_successes_.value();
 }
@@ -1589,6 +1805,9 @@ int64_t MasterMetricManager::get_promotion_expired() {
 int64_t MasterMetricManager::get_promotion_failed() {
     return promotion_failed_.value();
 }
+int64_t MasterMetricManager::get_promotion_execution_gave_up() {
+    return promotion_execution_gave_up_.value();
+}
 int64_t MasterMetricManager::get_promotion_cancelled() {
     return promotion_cancelled_.value();
 }
@@ -1787,6 +2006,11 @@ std::string MasterMetricManager::serialize_metrics() {
         ss << metric_str;
     };
 
+    // The generic lambda above accepts AllocatorMetric because it matches the
+    // serialize(std::string&) shape of every other metric type here.
+    allocator_metric_.Refresh();
+    serialize_metric(allocator_metric_);
+
     // Serialize Gauges
     serialize_metric(mem_allocated_size_);
     serialize_metric(mem_total_capacity_);
@@ -1801,15 +2025,27 @@ std::string MasterMetricManager::serialize_metrics() {
     serialize_metric(key_count_);
     serialize_metric(soft_pin_key_count_);
     serialize_metric(active_clients_);
+    serialize_metric(client_liveness_active_clients_);
+    serialize_metric(client_liveness_suspected_clients_);
+    serialize_metric(client_liveness_offline_clients_);
+    serialize_metric(pending_client_offboarding_jobs_metric_);
 
     // Serialize Histogram
     serialize_metric(value_size_distribution_);
+    serialize_metric(client_offboarding_duration_ms_);
+
+    serialize_metric(client_liveness_suspected_transitions_);
+    serialize_metric(client_liveness_recoveries_);
+    serialize_metric(client_liveness_offline_transitions_);
+    serialize_metric(client_offboarding_retries_);
+    serialize_metric(client_offboarding_alerts_);
 
     // Serialize Request Counters
     serialize_metric(exist_key_requests_);
     serialize_metric(exist_key_failures_);
     serialize_metric(put_start_requests_);
     serialize_metric(put_start_failures_);
+    serialize_metric(put_start_object_already_exists_);
     serialize_metric(put_start_alloc_failures_);
     serialize_metric(put_start_partial_allocations_);
     serialize_metric(put_end_requests_);
@@ -1899,6 +2135,7 @@ std::string MasterMetricManager::serialize_metrics() {
     serialize_metric(batch_get_replica_list_failed_items_);
     serialize_metric(batch_put_start_requests_);
     serialize_metric(batch_put_start_failures_);
+    serialize_metric(batch_put_start_object_already_exists_);
     serialize_metric(batch_put_start_partial_successes_);
     serialize_metric(batch_put_start_items_);
     serialize_metric(batch_put_start_failed_items_);
@@ -1961,6 +2198,12 @@ std::string MasterMetricManager::serialize_metrics() {
     serialize_metric(promotion_candidate_dropped_limit_);
     serialize_metric(tenant_quota_reject_total_);
     serialize_metric(tenant_evict_bytes_total_);
+    serialize_metric(offload_enqueued_total_);
+    serialize_metric(offload_completed_total_);
+    serialize_metric(offload_failed_total_);
+    serialize_metric(offload_cancelled_total_);
+    serialize_metric(offload_enqueue_rejected_total_);
+    serialize_metric(build_info_);
 
     // Serialize Snapshot Metrics
     serialize_metric(snapshot_duration_ms_);
diff --git a/mooncake-store/src/master_service.cpp b/mooncake-store/src/master_service.cpp
index e38fabcd78..867b71c2df 100644
--- a/mooncake-store/src/master_service.cpp
+++ b/mooncake-store/src/master_service.cpp
@@ -3,6 +3,7 @@
 #include <algorithm>
 #include <array>
 #include <algorithm>
+#include <bitset>
 #include <cassert>
 #include <cctype>
 #include <cmath>
@@ -10,11 +11,15 @@
 #include <cstdint>
 #include <cstring>
 #include <future>
+#include <iterator>
 #include <limits>
+#include <map>
+#include <set>
 #include <shared_mutex>
 #include <sstream>
 #include <stdexcept>
 #include <thread>
+#include <tuple>
 #include <regex>
 #include <unordered_set>
 #include <unistd.h>
@@ -26,7 +31,9 @@
 #include "http_metadata_server.h"
 #include "master_metric_manager.h"
 #include "common.h"
+#include "environ.h"
 #include "segment.h"
+#include "segment/region_driver.h"
 #ifdef USE_HTTP
 #include "transfer_metadata_plugin.h"
 #endif
@@ -46,10 +53,12 @@
 #include "types.h"
 #include "serialize/serializer.h"
 #include "ha/snapshot/snapshot_logger.h"
-#include "utils/zstd_util.h"
-#include "utils/file_util.h"
+#include "common/zstd_util.h"
+#include "common/file_util.h"
+#include "storage/distributed/dfs_global_allocator.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/immutable_bucket_allocator.h"
 #include "random.h"
-#include "utils.h"
 #include "kv_event/kv_event_config.h"
 #include "master_snapshot_manager.h"
 #include "master_snapshot_repository.h"
@@ -60,7 +69,12 @@ namespace mooncake {
 
 namespace {
 
-constexpr int kMaxTenantQuotaEvictionRetries = 2;
+// Upper bound on the number of keys MasterService::ClearStaleHandles cleans
+// up while holding one metadata shard's write lock. A mass client expiry
+// marks handles stale all over the table, and without a cap the sweep held
+// each shard exclusively for as long as it took to walk that whole shard,
+// so every RPC that touched those keys stalled behind the sweep.
+constexpr size_t kStaleHandleCleanupBatchSize = 64;
 
 // Per-cycle offload cap as a fraction of `offloading_queue_limit_`. Used only
 // when offload-on-evict mode is active. Defers memory eviction for at most
@@ -122,7 +136,7 @@ uint64_t SaturatingMultiply(uint64_t lhs, uint64_t rhs) {
 bool HasExpectedReplicaAllocation(const ReplicateConfig& config,
                                   size_t allocated_memory_replicas,
                                   size_t allocated_nof_replicas) {
-    if (config.nof_replica_num == 0) {
+    if (config.nof_replica_num == 0 && config.dfs_replica_num == 0) {
         return allocated_memory_replicas > 0;
     }
     if (DetermineReplicaWriteMode(config) ==
@@ -133,6 +147,18 @@ bool HasExpectedReplicaAllocation(const ReplicateConfig& config,
            allocated_nof_replicas == config.nof_replica_num;
 }
 
+void LogTenantQuotaLedgerError(const TenantQuotaResult& result,
+                               std::string_view operation,
+                               const TenantId& tenant_id,
+                               std::string_view key) {
+    if (result) {
+        return;
+    }
+    LOG(ERROR) << "tenant quota ledger error operation=" << operation
+               << ", tenant=" << tenant_id.value() << ", key=" << key
+               << ", error=" << static_cast<int>(result.error());
+}
+
 tl::expected<std::string, ErrorCode> GetGroupIdForKey(
     const ReplicateConfig& config, size_t key_count, size_t key_index) {
     if (!config.group_ids.has_value()) {
@@ -163,16 +189,23 @@ MasterService::MasterService(const MasterServiceConfig& config)
                       << ", error=" << toString(result.error());
               }
           }),
+      replica_cleanup_worker_([this] { ClearInvalidHandles(); }),
+      enable_async_segment_cleanup_(
+          !config.enable_ha && !config.enable_snapshot && !config.enable_cxl),
       default_kv_lease_ttl_(config.default_kv_lease_ttl),
       default_kv_soft_pin_ttl_(config.default_kv_soft_pin_ttl),
+      max_kv_soft_pin_ttl_(config.max_kv_soft_pin_ttl),
       allow_evict_soft_pinned_objects_(config.allow_evict_soft_pinned_objects),
       eviction_ratio_(config.eviction_ratio),
       eviction_high_watermark_ratio_(config.eviction_high_watermark_ratio),
+      tenant_eviction_high_watermark_ratio_(
+          config.tenant_eviction_high_watermark_ratio),
       nof_eviction_ratio_(config.nof_eviction_ratio),
       nof_eviction_high_watermark_ratio_(
           config.nof_eviction_high_watermark_ratio),
       view_version_(config.view_version),
-      client_live_ttl_sec_(config.client_live_ttl_sec),
+      client_active_ttl_sec_(config.client_active_ttl_sec),
+      client_suspicion_ttl_sec_(config.client_suspicion_ttl_sec),
       nof_heartbeat_interval_sec_(
           std::chrono::seconds(config.nof_heartbeat_interval_sec)),
       nof_heartbeat_probe_timeout_ms_(
@@ -181,43 +214,40 @@ MasterService::MasterService(const MasterServiceConfig& config)
           config.nof_heartbeat_failures_threshold),
       enable_ha_(config.enable_ha),
       enable_offload_(config.enable_offload),
-      ha_backend_type_(config.ha_backend_type),
-      ha_backend_connstring_(config.ha_backend_connstring),
       enable_oplog_(config.enable_ha && config.enable_oplog &&
                     config.ha_backend_type == "etcd"),
       oplog_batch_max_entries_(config.oplog_batch_max_entries),
       cluster_id_(config.cluster_id),
       root_fs_dir_(config.root_fs_dir),
-      global_file_segment_size_(config.global_file_segment_size),
       enable_disk_eviction_(config.enable_disk_eviction),
       quota_bytes_(config.quota_bytes),
       enable_multi_tenants_(config.enable_multi_tenants),
-      tenant_quota_connector_type_(config.tenant_quota_connector_type),
-      tenant_quota_connector_uri_(config.tenant_quota_connector_uri),
       segment_manager_(config.memory_allocator, config.enable_cxl),
       nof_segment_manager_(config.memory_allocator),
       memory_allocator_type_(config.memory_allocator),
       allocation_strategy_type_(config.enable_cxl
                                     ? AllocationStrategyType::CXL
                                     : config.allocation_strategy_type),
-      allocation_strategy_(CreateAllocationStrategy(allocation_strategy_type_)),
-      enable_snapshot_restore_(config.enable_snapshot_restore),
-      enable_snapshot_(config.enable_snapshot),
-      snapshot_backup_dir_(config.snapshot_backup_dir),
-      snapshot_interval_seconds_(config.snapshot_interval_seconds),
-      snapshot_child_timeout_seconds_(config.snapshot_child_timeout_seconds),
-      snapshot_retention_count_(config.snapshot_retention_count),
-      snapshot_catalog_store_type_(config.snapshot_catalog_store_type),
-      snapshot_catalog_store_connstring_(
-          config.snapshot_catalog_store_connstring),
+      allocation_strategy_(CreateAllocationStrategy(allocation_strategy_type_,
+                                                    local_ssd_manager_)),
       put_start_discard_timeout_sec_(config.put_start_discard_timeout_sec),
       put_start_release_timeout_sec_(config.put_start_release_timeout_sec),
-      cxl_path_(config.cxl_path),
-      cxl_size_(config.cxl_size),
-      enable_cxl_(config.enable_cxl),
       offloading_queue_limit_(config.offloading_queue_limit),
       offload_cap_ratio_(config.offload_cap_ratio),
-      task_manager_(config.task_manager_config) {
+      task_manager_(config.task_manager_config),
+      batch_oplog_writer_factory_(
+          [](OrderedOpLogWriterConfig writer_config,
+             OrderedOpLogWriter::WriteBatchFn write_batch) {
+              return std::make_unique<OrderedOpLogWriter>(
+                  std::move(writer_config), std::move(write_batch));
+          }) {
+    if (default_kv_soft_pin_ttl_ > max_kv_soft_pin_ttl_) {
+        LOG(ERROR) << "Invalid soft-pin TTL configuration: default="
+                   << default_kv_soft_pin_ttl_
+                   << ", max=" << max_kv_soft_pin_ttl_;
+        throw std::invalid_argument("Invalid soft-pin TTL configuration");
+    }
+
     // Initialize HTTP metadata key prefix (read env var once at startup)
     const char* custom_prefix = std::getenv("MC_METADATA_CLUSTER_ID");
     if (custom_prefix && std::strlen(custom_prefix) > 0) {
@@ -232,47 +262,45 @@ MasterService::MasterService(const MasterServiceConfig& config)
         LOG(INFO) << "Local-first allocation strategy enabled";
     }
 
-    if (enable_snapshot_ || enable_snapshot_restore_) {
+    const bool use_snapshot_backup_dir = !config.snapshot_backup_dir.empty();
+    if (!config.enable_oplog_snapshot &&
+        (config.enable_snapshot || config.enable_snapshot_restore)) {
         try {
             auto object_store_type =
                 ParseSnapshotObjectStoreType(config.snapshot_object_store_type);
             snapshot_object_store_ =
                 SnapshotObjectStore::Create(object_store_type);
-            snapshot_catalog_store_ = CreateSnapshotCatalogStore();
+            snapshot_catalog_store_ = CreateSnapshotCatalogStore(config);
         } catch (const std::exception& e) {
             LOG(ERROR) << "Failed to create snapshot stores: " << e.what();
             throw std::runtime_error(
                 fmt::format("Failed to create snapshot stores: {}", e.what()));
         }
-        if (!snapshot_backup_dir_.empty()) {
-            use_snapshot_backup_dir_ = true;
-        }
-
         // Initialize repository and codec for both save and restore
         snapshot_repository_ = std::make_unique<MasterSnapshotRepository>(
             snapshot_object_store_.get(), snapshot_catalog_store_.get(),
-            snapshot_backup_dir_, use_snapshot_backup_dir_);
+            config.snapshot_backup_dir, use_snapshot_backup_dir);
         snapshot_codec_ = std::make_unique<ha::MasterSnapshotCodec>();
     }
 
     if (enable_multi_tenants_) {
-        auto store = CreateTenantQuotaPolicyStore(tenant_quota_connector_type_,
-                                                  tenant_quota_connector_uri_,
-                                                  cluster_id_);
+        auto store = CreateTenantQuotaPolicyStore(
+            config.tenant_quota_connector_type,
+            config.tenant_quota_connector_uri, cluster_id_);
         if (!store) {
             throw std::invalid_argument(store.error());
         }
         tenant_quota_policy_store_ = std::move(store.value());
     }
 
-    if (enable_snapshot_restore_) {
+    if (config.enable_snapshot_restore && !config.enable_oplog_snapshot) {
         RestoreState();
     }
     if (enable_multi_tenants_) {
         LoadTenantQuotaPoliciesFromStoreOrThrow();
         RebuildTenantQuotaUsageFromMetadata();
     }
-    if (enable_snapshot_ && snapshot_retention_count_ == 0) {
+    if (config.enable_snapshot && config.snapshot_retention_count == 0) {
         LOG(ERROR) << "snapshot_retention_count must be greater than 0";
         throw std::invalid_argument("snapshot_retention_count must be > 0");
     }
@@ -288,6 +316,14 @@ MasterService::MasterService(const MasterServiceConfig& config)
             << "current value: " << eviction_high_watermark_ratio_;
         throw std::invalid_argument("Invalid eviction high watermark ratio");
     }
+    if (tenant_eviction_high_watermark_ratio_ < 0.0 ||
+        tenant_eviction_high_watermark_ratio_ > 1.0) {
+        LOG(ERROR) << "Tenant eviction high watermark ratio must be between "
+                      "0.0 and 1.0, current value: "
+                   << tenant_eviction_high_watermark_ratio_;
+        throw std::invalid_argument(
+            "Invalid tenant eviction high watermark ratio");
+    }
 
     // Validate offload tuning knobs here (not only via gflags validator),
     // because values loaded from a configuration file bypass the gflags
@@ -393,17 +429,44 @@ MasterService::MasterService(const MasterServiceConfig& config)
                   << ")";
     }
 
+    if (config.dynamic_replication_mode == "observe") {
+        dynamic_replication_mode_ = DynamicReplicationMode::kObserve;
+    } else if (config.dynamic_replication_mode == "enforce") {
+        dynamic_replication_mode_ = DynamicReplicationMode::kEnforce;
+    } else {
+        dynamic_replication_mode_ = DynamicReplicationMode::kOff;
+    }
+    dynamic_replication_heat_window_seconds_ =
+        std::max<uint32_t>(1, config.dynamic_replication_heat_window_seconds);
+    dynamic_replication_admission_qps_threshold_ =
+        config.dynamic_replication_admission_qps_threshold > 0.0
+            ? config.dynamic_replication_admission_qps_threshold
+            : 0.8;
+    dynamic_replication_max_memory_replicas_ =
+        std::max<size_t>(1, config.dynamic_replication_max_memory_replicas);
+    if (DynamicReplicationEnabled()) {
+        LOG(INFO) << "Dynamic MEMORY replication mode enabled: mode="
+                  << config.dynamic_replication_mode << ", heat_window_seconds="
+                  << dynamic_replication_heat_window_seconds_
+                  << ", admission_qps_threshold="
+                  << dynamic_replication_admission_qps_threshold_
+                  << ", max_memory_replicas="
+                  << dynamic_replication_max_memory_replicas_;
+    }
+
+    InitDfsAllocatorFromEnvironment(config);
     kv_event_publisher_ =
         std::make_unique<KvEventPublisher>(BuildKvEventConfig(config));
+    kv_track_tenant_epochs_ = KvEventsEnabled();
 
     if (enable_oplog_ && !cluster_id_.empty()) {
 #ifdef STORE_USE_ETCD
-        if (ha_backend_connstring_.empty()) {
+        if (config.ha_backend_connstring.empty()) {
             LOG(INFO) << "Skipping automatic batch-record OpLog writer "
                          "initialization; no HA backend connstring configured";
         } else {
             ErrorCode connect_err = EtcdHelper::ConnectToEtcdStoreClient(
-                ha_backend_connstring_.c_str());
+                config.ha_backend_connstring.c_str());
             if (connect_err != ErrorCode::OK) {
                 throw std::runtime_error(fmt::format(
                     "failed to connect HA batch-record OpLog writer to etcd: "
@@ -411,7 +474,11 @@ MasterService::MasterService(const MasterServiceConfig& config)
                     toString(connect_err)));
             }
             auto backend = std::make_shared<EtcdHaKvBackend>();
-            ErrorCode err = InitializeBatchOpLogWriter(std::move(backend));
+            // Direct MasterService construction has no leadership session;
+            // supervisor-created services carry a non-zero acquired view.
+            ErrorCode err = InitializeBatchOpLogWriter(
+                std::move(backend),
+                /*require_fenced_writer=*/view_version_ > 0);
             if (err != ErrorCode::OK) {
                 throw std::runtime_error(fmt::format(
                     "failed to create HA batch-record OpLog writer: {}",
@@ -419,7 +486,7 @@ MasterService::MasterService(const MasterServiceConfig& config)
             }
         }
 #else
-        if (ha_backend_connstring_.empty()) {
+        if (config.ha_backend_connstring.empty()) {
             LOG(INFO) << "Skipping automatic batch-record OpLog writer "
                          "initialization; no HA backend connstring configured";
         } else {
@@ -430,6 +497,12 @@ MasterService::MasterService(const MasterServiceConfig& config)
 #endif
     }
 
+    // This worker is part of the Client lifecycle protocol. Start it before
+    // any raw std::thread so a startup failure can unwind the constructor
+    // normally instead of encountering joinable thread destructors.
+    client_offboarding_worker_.Start();
+    VLOG(1) << "action=start_client_offboarding_worker";
+
     eviction_running_ = true;
     eviction_thread_ = std::thread(&MasterService::EvictionThreadFunc, this);
     VLOG(1) << "action=start_eviction_thread";
@@ -453,6 +526,8 @@ MasterService::MasterService(const MasterServiceConfig& config)
         std::thread(&MasterService::TaskCleanupThreadFunc, this);
     VLOG(1) << "action=start_task_cleanup_thread";
 
+    replica_cleanup_worker_.Start();
+
     // NOTE: The async HTTP metadata cleanup worker is started lazily in
     // setHttpMetadataRemoteUrl() once http_metadata_remote_ is initialized,
     // since that happens after this constructor returns (in
@@ -463,58 +538,128 @@ MasterService::MasterService(const MasterServiceConfig& config)
         std::thread(&MasterService::JobDispatchThreadFunc, this);
     VLOG(1) << "action=start_job_dispatch_thread";
 
+    dynamic_replication_admission_running_ = true;
+    dynamic_replication_admission_thread_ = std::thread(
+        &MasterService::DynamicReplicationAdmissionThreadFunc, this);
+    VLOG(1) << "action=start_dynamic_replication_admission_thread";
+
     if (!root_fs_dir_.empty()) {
         use_disk_replica_ = true;
-        if (global_file_segment_size_ == std::numeric_limits<int64_t>::max()) {
+        if (config.global_file_segment_size ==
+            std::numeric_limits<int64_t>::max()) {
             MasterMetricManager::instance().set_dfs_capacity_unlimited(true);
         } else {
             MasterMetricManager::instance().inc_total_file_capacity(
-                global_file_segment_size_);
+                config.global_file_segment_size);
         }
     }
 
-    if (enable_snapshot_ && !enable_oplog_) {
+    if (config.enable_snapshot && !enable_oplog_) {
         if (memory_allocator_type_ == BufferAllocatorType::OFFSET) {
             // Initialize and start snapshot manager
             MasterSnapshotManagerOptions snapshot_options;
-            snapshot_options.enable_snapshot = enable_snapshot_;
             snapshot_options.snapshot_interval_seconds =
-                snapshot_interval_seconds_;
+                config.snapshot_interval_seconds;
             snapshot_options.snapshot_child_timeout_seconds =
-                snapshot_child_timeout_seconds_;
+                config.snapshot_child_timeout_seconds;
             snapshot_options.snapshot_retention_count =
-                snapshot_retention_count_;
-            snapshot_options.snapshot_backup_dir = snapshot_backup_dir_;
-            snapshot_options.use_snapshot_backup_dir = use_snapshot_backup_dir_;
-            snapshot_options.snapshot_catalog_store_type =
-                snapshot_catalog_store_type_;
-            snapshot_options.snapshot_catalog_store_connstring =
-                snapshot_catalog_store_connstring_;
-            snapshot_options.ha_backend_type = ha_backend_type_;
-            snapshot_options.ha_backend_connstring = ha_backend_connstring_;
-            snapshot_options.cluster_id = cluster_id_;
-            snapshot_options.enable_ha = enable_ha_;
+                config.snapshot_retention_count;
+            snapshot_options.snapshot_backup_dir = config.snapshot_backup_dir;
+            snapshot_options.use_snapshot_backup_dir = use_snapshot_backup_dir;
 
             snapshot_manager_ = std::make_unique<MasterSnapshotManager>(
                 this, snapshot_options, snapshot_mutex_,
                 snapshot_object_store_.get(), snapshot_catalog_store_.get());
             snapshot_manager_->Start();
         }
-    } else if (enable_snapshot_ && enable_oplog_) {
+    } else if (config.enable_snapshot && enable_oplog_) {
         LOG(INFO) << "Skipping primary snapshot generation in batch-record "
                      "OpLog mode; snapshots are owned by standby";
     }
 
-    if (enable_cxl_) {
+    if (config.enable_cxl) {
         allocation_strategy_ = std::make_shared<CxlAllocationStrategy>();
-        segment_manager_.initializeCxlAllocator(cxl_path_, cxl_size_);
+        const auto result = segment_manager_.initializeCxlAllocator(
+            config.cxl_path, config.cxl_size);
+        LOG_IF(FATAL, result != ErrorCode::OK)
+            << "Failed to initialize CXL allocator: "
+            << static_cast<int>(result);
         VLOG(1) << "action=start_cxl_global_allocator";
     }
 }
 
+tl::expected<int, ErrorCode> MasterService::GetDfsShardCount() const {
+    if (!shard_allocator_ || !shard_allocator_->IsInitialized()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    return shard_allocator_->GetShardCount();
+}
+
+tl::expected<int, ErrorCode> MasterService::ExpandDfsShards(int shard_count) {
+    if (!shard_allocator_ || !shard_allocator_->IsInitialized()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    return shard_allocator_->ExpandShards(shard_count);
+}
+
+void MasterService::InitDfsAllocatorFromEnvironment(
+    const MasterServiceConfig& config) {
+    enable_dfs_ = Environ::GetBool(
+        "MOONCAKE_ENABLE_DFS", Environ::GetBool("MOONCAKE_DFS_ENABLED", false));
+    if (!enable_dfs_) return;
+
+    if (config.enable_snapshot || config.enable_snapshot_restore ||
+        enable_oplog_) {
+        LOG(ERROR) << "DFS cannot be enabled with snapshot or oplog recovery "
+                      "until DFS allocator state restoration is supported";
+        throw std::invalid_argument(
+            "DFS is incompatible with snapshot/oplog recovery");
+    }
+
+    const auto dfs_config = DistributedStorageConfig::FromEnvironment();
+    if (!dfs_config.single_tenant) {
+        LOG(ERROR) << "Currently, DFS backend is not supported in "
+                      "multi-tenant mode";
+        enable_dfs_ = false;
+        return;
+    }
+
+    shard_allocator_ = nullptr;
+    bucket_allocator_ = nullptr;
+    if (dfs_config.allocator_type == "bucket") {
+        auto allocator = std::make_unique<ImmutableBucketAllocator>();
+        bucket_allocator_ = allocator.get();
+        dfs_allocator_ = std::move(allocator);
+    } else {
+        auto allocator = std::make_unique<DfsGlobalAllocator>();
+        shard_allocator_ = allocator.get();
+        dfs_allocator_ = std::move(allocator);
+    }
+    auto init_result = dfs_allocator_->Init(dfs_config);
+    if (!init_result) {
+        LOG(ERROR) << "Failed to initialize DFS allocator, error="
+                   << init_result.error() << ", config={"
+                   << dfs_config.FormatStr() << "}";
+        dfs_allocator_.reset();
+        shard_allocator_ = nullptr;
+        bucket_allocator_ = nullptr;
+        enable_dfs_ = false;
+        return;
+    }
+
+    LOG(INFO) << "DFS allocator initialized, type="
+              << ToString(dfs_allocator_->Type()) << ", config={"
+              << dfs_config.FormatStr() << "}"
+              << (shard_allocator_ != nullptr
+                      ? ", ready_shard_count=" +
+                            std::to_string(shard_allocator_->GetShardCount())
+                      : "");
+}
+
 std::unique_ptr<ha::SnapshotCatalogStore>
-MasterService::CreateSnapshotCatalogStore() {
-    auto catalog_kind = ParseSnapshotCatalogKind(snapshot_catalog_store_type_);
+MasterService::CreateSnapshotCatalogStore(const MasterServiceConfig& config) {
+    auto catalog_kind =
+        ParseSnapshotCatalogKind(config.snapshot_catalog_store_type);
     if (!catalog_kind) {
         throw std::invalid_argument(catalog_kind.error());
     }
@@ -530,9 +675,10 @@ MasterService::CreateSnapshotCatalogStore() {
                 "redis snapshot catalog store is unavailable in the current "
                 "build");
 #else
-            const auto connstring = !snapshot_catalog_store_connstring_.empty()
-                                        ? snapshot_catalog_store_connstring_
-                                        : ha_backend_connstring_;
+            const auto connstring =
+                !config.snapshot_catalog_store_connstring.empty()
+                    ? config.snapshot_catalog_store_connstring
+                    : config.ha_backend_connstring;
             if (connstring.empty()) {
                 throw std::invalid_argument(
                     "redis snapshot catalog store requires a connection "
@@ -549,10 +695,6 @@ MasterService::CreateSnapshotCatalogStore() {
 }
 
 MasterService::~MasterService() {
-    if (ordered_oplog_writer_) {
-        ordered_oplog_writer_->Stop();
-    }
-
     // Stop and join the threads
     eviction_running_ = false;
     client_monitor_running_ = false;
@@ -564,14 +706,17 @@ MasterService::~MasterService() {
 
     task_cleanup_running_ = false;
     job_dispatch_running_ = false;
+    dynamic_replication_admission_running_ = false;
     http_metadata_cleanup_running_ = false;
     graceful_unmount_scheduler_.Stop();
+    replica_cleanup_worker_.Stop();
 #ifdef USE_NOF
     nof_heartbeat_running_ = false;
 #endif
 
     // Wake sleepers so join() doesn't block for long sleep intervals.
     task_cleanup_cv_.notify_all();
+    dynamic_replication_admission_cv_.notify_all();
     http_metadata_cleanup_cv_.notify_all();
 
     if (eviction_thread_.joinable()) {
@@ -594,15 +739,23 @@ MasterService::~MasterService() {
     if (job_dispatch_thread_.joinable()) {
         job_dispatch_thread_.join();
     }
+    if (dynamic_replication_admission_thread_.joinable()) {
+        dynamic_replication_admission_thread_.join();
+    }
 
-    // Reset snapshot manager after all other threads have joined
-    // This triggers the destructor which joins the snapshot thread
+    // Join the snapshot producer before dropping queued/backoff offboarding
+    // work. No snapshot can observe those residual jobs after this point.
     if (snapshot_manager_) {
         snapshot_manager_.reset();
     }
+    client_offboarding_worker_.Stop();
+    if (ordered_oplog_writer_) {
+        ordered_oplog_writer_->Stop();
+    }
     for (const auto& [segment, bytes] : standby_accounted_memory_bytes_) {
         MasterMetricManager::instance().dec_allocated_mem_size(
             segment, static_cast<int64_t>(bytes));
+        MasterMetricManager::instance().remove_segment_metrics(segment);
     }
 
     // Segments still mounted here never went through CommitUnmountSegment;
@@ -610,65 +763,31 @@ MasterService::~MasterService() {
     // MasterMetricManager stays consistent when the next leadership term
     // constructs a fresh MasterService and the clients remount.
     segment_manager_.releaseCapacityMetrics();
-}
-
-ErrorCode MasterService::SetBatchOpLogBackendForTesting(
-    std::shared_ptr<HaKvBackend> backend) {
-    return InitializeBatchOpLogWriter(std::move(backend));
-}
-
-void MasterService::RunBatchEvictForTesting(double evict_ratio_target,
-                                            double evict_ratio_lowerbound) {
-    BatchEvict(evict_ratio_target, evict_ratio_lowerbound);
-}
-
-void MasterService::RunNoFBatchEvictForTesting(double evict_ratio_target,
-                                               double evict_ratio_lowerbound) {
-    NoFBatchEvict(evict_ratio_target, evict_ratio_lowerbound);
-}
 
-void MasterService::SetNoFProbeFnForTesting(NoFProbeFn fn) {
-#ifdef USE_NOF
-    std::lock_guard<std::mutex> lock(nof_probe_fn_mutex_);
-    if (fn) {
-        nof_probe_fn_ = std::move(fn);
-        return;
+    std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+    auto& metrics = MasterMetricManager::instance();
+    for (const auto& [_, record] : client_liveness_records_) {
+        metrics.on_client_liveness_record_removed(record->state());
     }
-    nof_probe_fn_ = [](const std::string& te_endpoint, uint32_t timeout_ms,
-                       std::string* error_reason) {
-        return SpdkWrapper::GetInstance().ProbeNofSegment(
-            te_endpoint, timeout_ms, error_reason);
-    };
-#else
-    (void)fn;
-#endif
+    client_liveness_records_.clear();
 }
 
-size_t MasterService::GetMountedNoFSegmentCountForTesting() {
-    std::vector<MountedNoFSegmentSnapshot> mounted_segments;
-    nof_segment_manager_.GetMountedSegmentsSnapshot(mounted_segments);
-    return mounted_segments.size();
+void MasterService::SetBatchOpLogTerminalCallback(
+    OrderedOpLogWriter::TerminalCallback callback) {
+    if (ordered_oplog_writer_) {
+        ordered_oplog_writer_->SetTerminalCallback(std::move(callback));
+    }
 }
 
-bool MasterService::IsNoFSegmentMountedForTesting(const UUID& segment_id) {
-    std::vector<MountedNoFSegmentSnapshot> mounted_segments;
-    nof_segment_manager_.GetMountedSegmentsSnapshot(mounted_segments);
-    return std::any_of(
-        mounted_segments.begin(), mounted_segments.end(),
-        [&segment_id](const MountedNoFSegmentSnapshot& snapshot) {
-            return snapshot.segment_id == segment_id &&
-                   snapshot.status == SegmentStatus::OK;
-        });
+void MasterService::StopBatchOpLogWriter() {
+    if (ordered_oplog_writer_) ordered_oplog_writer_->Stop();
 }
 
-std::optional<uint32_t> MasterService::GetNoFHeartbeatFailureCountForTesting(
-    const UUID& segment_id) {
-    std::lock_guard<std::mutex> lock(nof_heartbeat_mutex_);
-    auto it = nof_heartbeat_states_.find(segment_id);
-    if (it == nof_heartbeat_states_.end()) {
-        return std::nullopt;
-    }
-    return it->second.consecutive_failures;
+TieredStorageUsageSnapshot MasterService::GetStorageUsageSnapshot() const {
+    return {
+        .memory = segment_manager_.GetMemoryUsageSnapshot(),
+        .nof = nof_segment_manager_.GetUsageSnapshot(),
+    };
 }
 
 bool MasterService::IsTenantQuotaEnabled() const {
@@ -693,7 +812,8 @@ MasterService::UpsertTenantQuotaPolicy(const TenantId& tenant_id,
     if (!enable_multi_tenants_) {
         return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
     }
-    if (requested_quota_bytes == 0) {
+    if (requested_quota_bytes == 0 ||
+        requested_quota_bytes > TenantQuotaAccount::kMaxChargedBytes) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
 
@@ -750,13 +870,7 @@ MasterService::DeleteTenantQuotaPolicy(const TenantId& tenant_id) {
                                        : ErrorCode::OBJECT_NOT_FOUND);
     }
 
-    auto post_mark_snapshot = GetTenantQuotaSnapshot(tenant_id);
-    if (TenantHasObjects(tenant_id) ||
-        (post_mark_snapshot.has_value() &&
-         (post_mark_snapshot->used_bytes != 0 ||
-          post_mark_snapshot->reserved_bytes != 0 ||
-          post_mark_snapshot->committed_count != 0 ||
-          post_mark_snapshot->metadata_object_count != 0))) {
+    if (TenantHasObjects(tenant_id)) {
         restore_policy();
         return tl::make_unexpected(ErrorCode::TENANT_NOT_EMPTY);
     }
@@ -775,47 +889,54 @@ MasterService::DeleteTenantQuotaPolicy(const TenantId& tenant_id) {
 
 auto MasterService::MountSegment(const Segment& segment, const UUID& client_id)
     -> tl::expected<void, ErrorCode> {
-    ErrorCode mount_result = ErrorCode::OK;
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    ErrorCode mount_result = ErrorCode::INTERNAL_ERROR;
     {
-        ScopedSegmentAccess segment_access =
-            segment_manager_.getSegmentAccess();
-
-        // Tell the client monitor thread to start timing for this client. To
-        // avoid the following undesired situations, this message must be sent
-        // after locking the segment mutex and before the mounting operation
-        // completes:
-        // 1. Sending the message before the lock: the client expires and
-        // unmouting invokes before this mounting are completed, which prevents
-        // this segment being able to be unmounted forever;
-        // 2. Sending the message after mounting the segment: After mounting
-        // this segment, when trying to push id to the queue, the queue is
-        // already full. However, at this point, the message must be sent,
-        // otherwise this client cannot be monitored and expired.
-        {
-            PodUUID pod_client_id;
-            pod_client_id.first = client_id.first;
-            pod_client_id.second = client_id.second;
-            if (!client_ping_queue_.push(pod_client_id)) {
-                LOG(ERROR) << "segment_name=" << segment.name
-                           << ", error=client_ping_queue_full";
-                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+        auto [record_it, inserted] = client_liveness_records_.try_emplace(
+            client_id, std::make_shared<ClientLivenessRecord>(
+                           ClientLivenessRecord::Clock::now()));
+        const auto record = record_it->second;
+        if (inserted) {
+            MasterMetricManager::instance().client_liveness_record_created();
+        }
+        const auto observation =
+            record->ObserveAndRun(ClientLivenessRecord::Clock::now(), [&] {
+                std::shared_lock<std::shared_mutex> snapshot_lock(
+                    snapshot_mutex_);
+                ScopedSegmentAccess segment_access =
+                    segment_manager_.getSegmentAccess();
+                LOG(INFO) << "client_id=" << client_id
+                          << ", action=mount_segment, segment_name="
+                          << segment.name;
+                mount_result =
+                    segment_access.MountSegment(segment, client_id, record);
+                return mount_result == ErrorCode::OK ||
+                       mount_result == ErrorCode::SEGMENT_ALREADY_EXISTS;
+            });
+        if (observation == ClientLivenessObservation::REJECTED_OFFLINE) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        if (mount_result != ErrorCode::OK &&
+            mount_result != ErrorCode::SEGMENT_ALREADY_EXISTS) {
+            if (inserted) {
+                client_liveness_records_.erase(client_id);
+                MasterMetricManager::instance()
+                    .on_client_liveness_record_removed(
+                        ClientLivenessState::ACTIVE);
             }
+            return tl::make_unexpected(mount_result);
         }
-
-        LOG(INFO) << "client_id=" << client_id
-                  << ", action=mount_segment, segment_name=" << segment.name;
-
-        auto err = segment_access.MountSegment(segment, client_id);
-        if (err == ErrorCode::SEGMENT_ALREADY_EXISTS) {
-            // Return OK because this is an idempotent operation
-            mount_result = err;
-        } else if (err != ErrorCode::OK) {
-            return tl::make_unexpected(err);
+        if (observation == ClientLivenessObservation::RECOVERED_ACTIVE) {
+            MasterMetricManager::instance().client_liveness_recovered();
+            LOG(INFO) << "client_id=" << client_id
+                      << ", action=client_liveness_recovered, "
+                         "signal=memory_mount";
         }
     }
 
-    if (enable_oplog_ && ordered_oplog_writer_) {
+    if (mount_result == ErrorCode::OK && enable_oplog_ &&
+        ordered_oplog_writer_) {
         SegmentMountOp op;
         op.segment_name = segment.name;
         op.transport_endpoint = segment.te_endpoint;
@@ -827,8 +948,8 @@ auto MasterService::MountSegment(const Segment& segment, const UUID& client_id)
                                        segment.te_endpoint,
                                        std::string(bytes.begin(), bytes.end()));
     }
-    UpdateClientHostId(client_id, segment.host_id);
     if (mount_result == ErrorCode::OK) {
+        UpdateClientHostId(client_id, segment.host_id);
         RecomputeTenantEffectiveQuotas();
     }
     return {};
@@ -886,9 +1007,30 @@ ErrorCode MasterService::ValidateStandbyRemountSegment(
 auto MasterService::ReMountSegment(const std::vector<Segment>& segments,
                                    const UUID& client_id)
     -> tl::expected<void, ErrorCode> {
-    std::unique_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
     {
-        std::unique_lock<std::shared_mutex> lock(client_mutex_);
+        std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+        auto [record_it, record_inserted] =
+            client_liveness_records_.try_emplace(
+                client_id, std::make_shared<ClientLivenessRecord>(
+                               ClientLivenessRecord::Clock::now()));
+        const auto record = record_it->second;
+        if (record_inserted) {
+            MasterMetricManager::instance().client_liveness_record_created();
+        }
+        auto remount_guard = record->TryAcquireRetainingGuard();
+        if (!remount_guard) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        const auto discard_provisional_record = [&] {
+            if (!record_inserted) {
+                return;
+            }
+            client_liveness_records_.erase(client_id);
+            MasterMetricManager::instance().on_client_liveness_record_removed(
+                ClientLivenessState::ACTIVE);
+        };
+        std::unique_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
         for (const auto& segment : segments) {
             if (!segment.host_id.empty()) {
                 client_host_id_[client_id] = segment.host_id;
@@ -901,11 +1043,13 @@ auto MasterService::ReMountSegment(const std::vector<Segment>& segments,
                 auto standby_validation =
                     ValidateStandbyRemountSegment(segment);
                 if (standby_validation != ErrorCode::OK) {
+                    discard_provisional_record();
                     return tl::make_unexpected(standby_validation);
                 }
                 auto validation =
                     segment_access.ValidateRemountSegment(segment, client_id);
                 if (validation != ErrorCode::OK) {
+                    discard_provisional_record();
                     return tl::make_unexpected(validation);
                 }
             }
@@ -917,230 +1061,250 @@ auto MasterService::ReMountSegment(const std::vector<Segment>& segments,
             return {};
         }
 
-        {
+        struct SegmentRestore {
+            Segment segment;
+            std::shared_ptr<BufferAllocatorBase> old_allocator;
+            std::shared_ptr<BufferAllocatorBase> restored_allocator;
+            std::vector<Replica*> replicas;
+            std::vector<AllocatedBuffer::Descriptor> descriptors;
+            std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
+            uint64_t imported_size{0};
+        };
+        std::vector<SegmentRestore> restores;
+        restores.reserve(segments.size());
+        std::vector<bool> segment_existed(segments.size());
+        auto rollback_new_segments = [&] {
             ScopedSegmentAccess segment_access =
                 segment_manager_.getSegmentAccess();
-            std::vector<bool> segment_existed(segments.size());
             for (size_t i = 0; i < segments.size(); ++i) {
-                segment_existed[i] =
-                    segment_access.GetAllocator(segments[i].id) != nullptr;
-            }
-            auto rollback_new_segments = [&] {
-                for (size_t i = 0; i < segments.size(); ++i) {
-                    if (segment_existed[i] ||
-                        !segment_access.GetAllocator(segments[i].id)) {
-                        continue;
-                    }
-                    size_t capacity = 0;
-                    if (segment_access.PrepareUnmountSegment(
-                            segments[i].id, capacity) != ErrorCode::OK) {
-                        LOG(ERROR) << "segment_name=" << segments[i].name
-                                   << ", error=remount_rollback_prepare_failed";
-                        continue;
-                    }
-                    if (segment_access.CommitUnmountSegment(
-                            segments[i].id, client_id, capacity) !=
-                        ErrorCode::OK) {
-                        LOG(ERROR) << "segment_name=" << segments[i].name
-                                   << ", error=remount_rollback_commit_failed";
-                    }
+                if (segment_existed[i] ||
+                    !segment_access.GetAllocator(segments[i].id)) {
+                    continue;
+                }
+                size_t capacity = 0;
+                if (segment_access.PrepareUnmountSegment(
+                        segments[i].id, capacity) != ErrorCode::OK) {
+                    LOG(ERROR) << "segment_name=" << segments[i].name
+                               << ", error=remount_rollback_prepare_failed";
+                    continue;
+                }
+                if (segment_access.CommitUnmountSegment(
+                        segments[i].id, client_id, capacity) != ErrorCode::OK) {
+                    LOG(ERROR) << "segment_name=" << segments[i].name
+                               << ", error=remount_rollback_commit_failed";
                 }
-            };
-            auto fail_remount =
-                [&](ErrorCode error) -> tl::expected<void, ErrorCode> {
-                rollback_new_segments();
-                return tl::make_unexpected(error);
-            };
-
-            // Tell the client monitor thread to start timing for this client.
-            // To avoid the following undesired situations, this message must be
-            // sent after locking the segment mutex or client mutex and before
-            // the remounting operation completes:
-            // 1. Sending the message before the lock: the client expires and
-            // unmouting invokes before this remounting are completed, which
-            // prevents this segment being able to be unmounted forever;
-            // 2. Sending the message after remounting the segments: After
-            // remounting these segments, when trying to push id to the queue,
-            // the queue is already full. However, at this point, the message
-            // must be sent, otherwise this client cannot be monitored and
-            // expired.
-            PodUUID pod_client_id;
-            pod_client_id.first = client_id.first;
-            pod_client_id.second = client_id.second;
-            if (!client_ping_queue_.push(pod_client_id)) {
-                LOG(ERROR) << "client_id=" << client_id
-                           << ", error=client_ping_queue_full";
-                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
             }
+        };
+        auto fail_remount =
+            [&](ErrorCode error) -> tl::expected<void, ErrorCode> {
+            rollback_new_segments();
+            discard_provisional_record();
+            return tl::make_unexpected(error);
+        };
 
-            ErrorCode err = segment_access.ReMountSegment(segments, client_id);
-            if (err != ErrorCode::OK) {
-                return fail_remount(err);
+        ErrorCode remount_error = ErrorCode::OK;
+        {
+            ScopedSegmentAccess segment_access =
+                segment_manager_.getSegmentAccess();
+            for (size_t i = 0; i < segments.size(); ++i) {
+                segment_existed[i] =
+                    segment_access.GetAllocator(segments[i].id) != nullptr;
             }
 
-            struct SegmentRestore {
-                Segment segment;
-                std::shared_ptr<BufferAllocatorBase> old_allocator;
-                std::shared_ptr<BufferAllocatorBase> restored_allocator;
-                std::vector<Replica*> replicas;
-                std::vector<AllocatedBuffer::Descriptor> descriptors;
-                std::vector<std::unique_ptr<AllocatedBuffer>> buffers;
-                uint64_t imported_size{0};
-            };
-            std::vector<SegmentRestore> restores;
-            restores.reserve(segments.size());
-            for (const auto& segment : segments) {
-                auto allocator = segment_access.GetAllocator(segment.id);
-                Segment authoritative;
-                if (!allocator ||
-                    !segment_access.GetSegment(segment.id, authoritative)) {
-                    return fail_remount(ErrorCode::INTERNAL_ERROR);
+            remount_error =
+                segment_access.ReMountSegment(segments, client_id, record);
+            if (remount_error == ErrorCode::OK) {
+                segment_access.BindClientLiveness(client_id, record);
+                for (const auto& segment : segments) {
+                    auto allocator = segment_access.GetAllocator(segment.id);
+                    Segment authoritative;
+                    if (!allocator ||
+                        !segment_access.GetSegment(segment.id, authoritative)) {
+                        remount_error = ErrorCode::INTERNAL_ERROR;
+                        break;
+                    }
+                    restores.push_back({std::move(authoritative),
+                                        std::move(allocator),
+                                        nullptr,
+                                        {},
+                                        {},
+                                        {},
+                                        0});
                 }
-                restores.push_back({std::move(authoritative),
-                                    std::move(allocator),
-                                    nullptr,
-                                    {},
-                                    {},
-                                    {},
-                                    0});
             }
+        }
+        if (remount_error != ErrorCode::OK) {
+            return fail_remount(remount_error);
+        }
 
-            bool ambiguous_endpoint = false;
-            bool unsupported_cxl = false;
-            for (size_t shard_index = 0; shard_index < kNumShards;
-                 ++shard_index) {
-                MetadataShardAccessorRW shard(this, shard_index);
-                for (auto& [tenant_id, tenant] : shard->tenants) {
-                    (void)tenant_id;
-                    for (auto& [key, metadata] : tenant.metadata) {
-                        (void)key;
-                        metadata.VisitReplicas(
-                            [](const Replica& replica) {
-                                return replica.is_memory_replica() &&
-                                       replica.status() !=
-                                           ReplicaStatus::REMOVED &&
-                                       replica.status() !=
-                                           ReplicaStatus::FAILED;
-                            },
-                            [&](Replica& replica) {
-                                auto descriptor = replica.get_descriptor()
-                                                      .get_memory_descriptor()
-                                                      .buffer_descriptor;
-                                SegmentRestore* match = nullptr;
-                                for (auto& restore : restores) {
-                                    if (descriptor.transport_endpoint_ ==
-                                            restore.segment.te_endpoint ||
-                                        descriptor.transport_endpoint_ ==
-                                            restore.segment.name) {
-                                        if (match != nullptr) {
-                                            ambiguous_endpoint = true;
-                                            return;
-                                        }
-                                        match = &restore;
-                                    }
-                                }
-                                if (match != nullptr) {
-                                    if (descriptor.protocol_ == "cxl") {
-                                        unsupported_cxl = true;
+        bool ambiguous_endpoint = false;
+        bool unsupported_cxl = false;
+        std::unordered_set<ObjectMetadata*> affected_objects;
+        bool any_standby_kept_alive = std::any_of(
+            segments.begin(), segments.end(), [this](const Segment& segment) {
+                return standby_accounted_memory_bytes_.contains(segment.name);
+            });
+        for (size_t shard_index = 0;
+             any_standby_kept_alive && shard_index < kNumShards;
+             ++shard_index) {
+            MetadataShardAccessorRW shard(this, shard_index);
+            for (auto& [tenant_id, tenant] : shard->tenants) {
+                (void)tenant_id;
+                for (auto& [key, metadata] : tenant.metadata) {
+                    (void)key;
+                    metadata.VisitReplicas(
+                        [](const Replica& replica) {
+                            return replica.is_memory_replica() &&
+                                   replica.status() != ReplicaStatus::REMOVED &&
+                                   replica.status() != ReplicaStatus::FAILED;
+                        },
+                        [&](Replica& replica) {
+                            auto descriptor = replica.get_descriptor()
+                                                  .get_memory_descriptor()
+                                                  .buffer_descriptor;
+                            SegmentRestore* match = nullptr;
+                            for (auto& restore : restores) {
+                                if (descriptor.transport_endpoint_ ==
+                                        restore.segment.te_endpoint ||
+                                    descriptor.transport_endpoint_ ==
+                                        restore.segment.name) {
+                                    if (match != nullptr) {
+                                        ambiguous_endpoint = true;
                                         return;
                                     }
-                                    descriptor.transport_endpoint_ =
-                                        match->segment.te_endpoint;
-                                    match->replicas.push_back(&replica);
-                                    match->descriptors.push_back(descriptor);
+                                    match = &restore;
                                 }
-                            });
-                    }
+                            }
+                            if (match != nullptr) {
+                                if (descriptor.protocol_ == "cxl") {
+                                    unsupported_cxl = true;
+                                    return;
+                                }
+                                descriptor.transport_endpoint_ =
+                                    match->segment.te_endpoint;
+                                match->replicas.push_back(&replica);
+                                match->descriptors.push_back(descriptor);
+                                affected_objects.insert(&metadata);
+                            }
+                        });
                 }
             }
-            if (ambiguous_endpoint) {
-                return fail_remount(ErrorCode::INVALID_PARAMS);
+        }
+        if (ambiguous_endpoint) {
+            return fail_remount(ErrorCode::INVALID_PARAMS);
+        }
+        if (unsupported_cxl) {
+            return fail_remount(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+        }
+
+        for (auto& restore : restores) {
+            if (restore.descriptors.empty()) {
+                continue;
             }
-            if (unsupported_cxl) {
+            const RegionResourceSpec spec{
+                restore.segment.id, restore.segment.name, restore.segment.base,
+                restore.segment.size, restore.segment.te_endpoint};
+            auto allocations =
+                BuildRegionLiveAllocations(spec, restore.descriptors);
+            if (!allocations) {
+                return fail_remount(allocations.error());
+            }
+            if (std::dynamic_pointer_cast<OffsetBufferAllocator>(
+                    restore.old_allocator)) {
+                auto imported = ImportOffsetBufferAllocator(
+                    restore.segment.name, restore.segment.base,
+                    restore.segment.size, restore.segment.te_endpoint,
+                    *allocations);
+                if (!imported) {
+                    return fail_remount(ErrorCode::INVALID_PARAMS);
+                }
+                restore.restored_allocator = std::move(imported->allocator);
+                restore.buffers = std::move(imported->buffers);
+            } else if (std::dynamic_pointer_cast<CachelibBufferAllocator>(
+                           restore.old_allocator)) {
+                auto imported = ImportCachelibBufferAllocator(
+                    restore.segment.name, restore.segment.base,
+                    restore.segment.size, restore.segment.te_endpoint,
+                    *allocations);
+                if (!imported) {
+                    return fail_remount(ErrorCode::INVALID_PARAMS);
+                }
+                restore.restored_allocator = std::move(imported->allocator);
+                restore.buffers = std::move(imported->buffers);
+            } else {
                 return fail_remount(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
             }
+        }
 
-            for (auto& restore : restores) {
-                if (restore.descriptors.empty()) {
-                    continue;
+        std::vector<ScopedSegmentAccess::AllocatorReplacement>
+            allocator_replacements;
+        for (auto& restore : restores) {
+            if (restore.restored_allocator) {
+                if (restore.buffers.size() != restore.replicas.size() ||
+                    std::any_of(restore.buffers.begin(), restore.buffers.end(),
+                                [](const auto& buffer) { return !buffer; })) {
+                    return fail_remount(ErrorCode::INTERNAL_ERROR);
                 }
-                if (std::dynamic_pointer_cast<OffsetBufferAllocator>(
-                        restore.old_allocator)) {
-                    auto restored = RestoreOffsetBufferAllocator(
-                        restore.segment.name, restore.segment.base,
-                        restore.segment.size, restore.segment.te_endpoint,
-                        restore.descriptors);
-                    if (!restored) {
-                        return fail_remount(ErrorCode::INVALID_PARAMS);
-                    }
-                    restore.restored_allocator = std::move(restored->allocator);
-                    restore.buffers = std::move(restored->buffers);
-                } else if (std::dynamic_pointer_cast<CachelibBufferAllocator>(
-                               restore.old_allocator)) {
-                    auto restored = RestoreCachelibBufferAllocator(
-                        restore.segment.name, restore.segment.base,
-                        restore.segment.size, restore.segment.te_endpoint,
-                        restore.descriptors);
-                    if (!restored) {
-                        return fail_remount(ErrorCode::INVALID_PARAMS);
-                    }
-                    restore.restored_allocator = std::move(restored->allocator);
-                    restore.buffers = std::move(restored->buffers);
-                } else {
-                    return fail_remount(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+                restore.imported_size = std::accumulate(
+                    restore.descriptors.begin(), restore.descriptors.end(),
+                    uint64_t{0}, [](uint64_t sum, const auto& descriptor) {
+                        return sum + descriptor.size_;
+                    });
+                auto accounted =
+                    standby_accounted_memory_bytes_.find(restore.segment.name);
+                if (accounted == standby_accounted_memory_bytes_.end() ||
+                    accounted->second < restore.imported_size) {
+                    return fail_remount(ErrorCode::INTERNAL_ERROR);
                 }
+                allocator_replacements.push_back({restore.segment.id,
+                                                  restore.old_allocator,
+                                                  restore.restored_allocator});
             }
-
-            std::vector<ScopedSegmentAccess::AllocatorReplacement>
-                allocator_replacements;
+        }
+        bool allocators_replaced = false;
+        {
+            ScopedSegmentAccess segment_access =
+                segment_manager_.getSegmentAccess();
+            allocators_replaced =
+                segment_access.ReplaceAllocators(allocator_replacements);
+        }
+        if (!allocators_replaced) {
+            return fail_remount(ErrorCode::INTERNAL_ERROR);
+        }
+        {
+            ScopedSegmentAccess segment_access =
+                segment_manager_.getSegmentAccess();
             for (auto& restore : restores) {
-                if (restore.restored_allocator) {
-                    if (restore.buffers.size() != restore.replicas.size() ||
-                        std::any_of(
-                            restore.buffers.begin(), restore.buffers.end(),
-                            [](const auto& buffer) { return !buffer; })) {
-                        return fail_remount(ErrorCode::INTERNAL_ERROR);
-                    }
-                    restore.imported_size = std::accumulate(
-                        restore.descriptors.begin(), restore.descriptors.end(),
-                        uint64_t{0}, [](uint64_t sum, const auto& descriptor) {
-                            return sum + descriptor.size_;
-                        });
-                    auto accounted = standby_accounted_memory_bytes_.find(
-                        restore.segment.name);
-                    if (accounted == standby_accounted_memory_bytes_.end() ||
-                        accounted->second < restore.imported_size) {
-                        return fail_remount(ErrorCode::INTERNAL_ERROR);
-                    }
-                    allocator_replacements.push_back(
-                        {restore.segment.id, restore.old_allocator,
-                         restore.restored_allocator});
+                for (auto& buffer : restore.buffers) {
+                    segment_access.BindBufferToSegment(restore.segment.id,
+                                                       *buffer);
                 }
             }
-            if (!segment_access.ReplaceAllocators(allocator_replacements)) {
-                return fail_remount(ErrorCode::INTERNAL_ERROR);
-            }
-            for (auto& restore : restores) {
-                if (restore.imported_size != 0) {
-                    MasterMetricManager::instance().dec_allocated_mem_size(
-                        restore.segment.name,
-                        static_cast<int64_t>(restore.imported_size));
-                    auto accounted = standby_accounted_memory_bytes_.find(
-                        restore.segment.name);
-                    accounted->second -= restore.imported_size;
-                    if (accounted->second == 0) {
-                        standby_accounted_memory_bytes_.erase(accounted);
-                    }
-                }
-                for (size_t i = 0; i < restore.replicas.size(); ++i) {
-                    (void)restore.replicas[i]->replace_memory_buffer(
-                        std::move(restore.buffers[i]));
+        }
+        for (auto& restore : restores) {
+            if (restore.imported_size != 0) {
+                MasterMetricManager::instance().dec_allocated_mem_size(
+                    restore.segment.name,
+                    static_cast<int64_t>(restore.imported_size));
+                auto accounted =
+                    standby_accounted_memory_bytes_.find(restore.segment.name);
+                accounted->second -= restore.imported_size;
+                if (accounted->second == 0) {
+                    standby_accounted_memory_bytes_.erase(accounted);
                 }
-                invalid_replica_endpoints_.erase(restore.segment.te_endpoint);
-                invalid_replica_endpoints_.erase(restore.segment.name);
-                standby_allocator_keepalive_.erase(restore.segment.te_endpoint);
-                standby_allocator_keepalive_.erase(restore.segment.name);
             }
+            for (size_t i = 0; i < restore.replicas.size(); ++i) {
+                (void)restore.replicas[i]->replace_memory_buffer(
+                    std::move(restore.buffers[i]));
+            }
+            invalid_replica_endpoints_.erase(restore.segment.te_endpoint);
+            invalid_replica_endpoints_.erase(restore.segment.name);
+            standby_allocator_keepalive_.erase(restore.segment.te_endpoint);
+            standby_allocator_keepalive_.erase(restore.segment.name);
+        }
+        for (const auto* metadata : affected_objects) {
+            metadata->GrantReadLease(
+                std::chrono::milliseconds(default_kv_lease_ttl_));
         }
 
         // Change the client status to OK
@@ -1186,10 +1350,23 @@ auto MasterService::ReMountNoFSegment(const std::vector<NoFSegment>& segments,
 #endif
 }
 
-std::unordered_set<UUID, boost::hash<UUID>>
-MasterService::getAliveClientsSnapshot() const {
+std::shared_ptr<ClientLivenessRecord> MasterService::FindClientRecord(
+    const UUID& client_id) const {
     std::shared_lock<std::shared_mutex> lock(client_mutex_);
-    return ok_client_;
+    const auto it = client_liveness_records_.find(client_id);
+    return it == client_liveness_records_.end() ? nullptr : it->second;
+}
+
+std::unordered_set<UUID, boost::hash<UUID>>
+MasterService::GetRetainingClientIdsLocked() const {
+    std::unordered_set<UUID, boost::hash<UUID>> clients;
+    clients.reserve(client_liveness_records_.size());
+    for (const auto& [client_id, record] : client_liveness_records_) {
+        if (record->ShouldRetainResources()) {
+            clients.insert(client_id);
+        }
+    }
+    return clients;
 }
 
 void MasterService::UpdateClientHostId(const UUID& client_id,
@@ -1218,16 +1395,6 @@ std::string MasterService::GetClientHostId(const UUID& client_id) const {
     return it == client_host_id_.end() ? std::string() : it->second;
 }
 
-size_t MasterService::getMetadataShardIndex(const TenantId& tenant_id,
-                                            const std::string& key) const {
-    std::shared_lock<std::shared_mutex> lock(group_routing_mutex_);
-    auto it = object_group_ids_.find(tenant_id.MakeScopedKey(key));
-    if (it == object_group_ids_.end()) {
-        return getShardIndex(tenant_id, key);
-    }
-    return getShardIndex(it->second);
-}
-
 const TenantId& MasterService::ResolveRequestTenantId(
     const TenantId& tenant_id) const {
     assert(tenant_id.IsValid());
@@ -1303,7 +1470,11 @@ void MasterService::ApplyTenantQuotaPolicies(
     }
     std::lock_guard<std::mutex> recompute_lock(tenant_quota_recompute_mutex_);
     const uint64_t capacity = GetTenantQuotaAllocatableCapacityBytes();
-    tenant_quota_table_.ApplyTenantPolicies(policies, capacity);
+    auto result = tenant_quota_table_.ApplyTenantPolicies(policies, capacity);
+    if (!result) {
+        throw std::invalid_argument(
+            "tenant quota policy exceeds atomic accounting range");
+    }
 }
 
 void MasterService::LoadTenantQuotaPoliciesFromStoreOrThrow() {
@@ -1325,10 +1496,15 @@ void MasterService::LoadTenantQuotaPoliciesFromStoreOrThrow() {
 
 uint64_t MasterService::CompletedMemoryQuotaCharge(
     const ObjectMetadata& metadata) const {
-    return static_cast<uint64_t>(metadata.size) *
-           metadata.CountReplicas([](const Replica& replica) {
-               return replica.is_memory_replica() && replica.is_completed();
-           });
+    const auto completed_replicas =
+        metadata.CountReplicas([](const Replica& replica) {
+            return replica.is_memory_replica() && replica.is_completed();
+        });
+    const unsigned __int128 charge =
+        static_cast<unsigned __int128>(metadata.size) * completed_replicas;
+    return charge > std::numeric_limits<uint64_t>::max()
+               ? std::numeric_limits<uint64_t>::max()
+               : static_cast<uint64_t>(charge);
 }
 
 uint64_t MasterService::RequestedMemoryQuotaCharge(
@@ -1341,11 +1517,6 @@ uint64_t MasterService::RequestedMemoryQuotaCharge(
     return static_cast<uint64_t>(charge);
 }
 
-bool MasterService::ShouldProtectZeroChargeMetadataCreate(
-    uint64_t requested_quota_charge) const {
-    return enable_multi_tenants_ && requested_quota_charge == 0;
-}
-
 uint64_t MasterService::GetTenantQuotaAllocatableCapacityBytes() {
     uint64_t capacity = 0;
     ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
@@ -1371,160 +1542,120 @@ void MasterService::RecomputeTenantEffectiveQuotas() {
     tenant_quota_table_.RecomputeEffectiveQuotas(capacity);
 }
 
-tl::expected<void, ErrorCode> MasterService::ReserveTenantQuota(
-    const TenantId& tenant_id, uint64_t bytes) {
+MasterService::TenantState& MasterService::GetOrCreateTenantState(
+    MetadataShard& shard, const TenantId& tenant_id) {
+    auto it = shard.tenants.try_emplace(tenant_id).first;
+    if (enable_multi_tenants_ && it->second.quota_account == nullptr) {
+        it->second.quota_account =
+            tenant_quota_table_.GetOrCreateTenantHandle(tenant_id);
+    }
+    return it->second;
+}
+
+TenantQuotaHandle MasterService::GetBoundTenantQuotaHandle(
+    const TenantState& tenant_state) const {
+    if (!enable_multi_tenants_) {
+        return nullptr;
+    }
+    assert(tenant_state.quota_account != nullptr);
+    return tenant_state.quota_account;
+}
+
+tl::expected<void, ErrorCode> MasterService::ChargeTenantQuota(
+    TenantQuotaHandle account, uint64_t bytes) {
     if (!enable_multi_tenants_) {
         return {};
     }
-    auto result = tenant_quota_table_.Reserve(tenant_id, bytes);
+    if (account == nullptr) {
+        LOG(ERROR) << "tenant quota charge attempted without a bound handle";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    auto result = account->TryCharge(bytes);
     if (result) {
         return {};
     }
     return tl::make_unexpected(
-        result.error() == TenantQuotaError::kTenantNotRegistered
+        result.error().error == TenantQuotaError::kTenantNotRegistered
             ? ErrorCode::TENANT_NOT_REGISTERED
-        : result.error() == TenantQuotaError::kQuotaExceeded
+        : result.error().error == TenantQuotaError::kQuotaExceeded
             ? ErrorCode::TENANT_QUOTA_EXCEEDED
+        : result.error().error == TenantQuotaError::kInvalidArgument
+            ? ErrorCode::INVALID_PARAMS
             : ErrorCode::INTERNAL_ERROR);
 }
 
-void MasterService::CommitTenantQuota(const TenantId& tenant_id,
-                                      uint64_t bytes) {
+void MasterService::ReleaseTenantQuota(TenantQuotaHandle account,
+                                       uint64_t bytes) {
     if (!enable_multi_tenants_ || bytes == 0) {
         return;
     }
-    if (!tenant_quota_table_.Commit(tenant_id, bytes)) {
-        LOG(ERROR) << "tenant quota commit mismatch tenant="
-                   << tenant_id.value() << ", bytes=" << bytes;
-    }
-}
-
-void MasterService::AbortTenantQuota(const TenantId& tenant_id,
-                                     uint64_t bytes) {
-    if (!enable_multi_tenants_ || bytes == 0) {
+    if (account == nullptr) {
+        LOG(ERROR) << "tenant quota release attempted without a bound handle"
+                   << ", bytes=" << bytes;
         return;
     }
-    if (!tenant_quota_table_.Abort(tenant_id, bytes)) {
-        LOG(ERROR) << "tenant quota abort mismatch tenant=" << tenant_id.value()
-                   << ", bytes=" << bytes;
+    if (!account->Release(bytes)) {
+        LOG(ERROR) << "tenant quota release mismatch bytes=" << bytes;
     }
 }
 
-void MasterService::ReleaseTenantQuota(const TenantId& tenant_id,
-                                       uint64_t bytes) {
-    if (!enable_multi_tenants_ || bytes == 0) {
+void MasterService::RebuildTenantQuotaUsageFromMetadata() {
+    if (!enable_multi_tenants_) {
         return;
     }
-    if (!tenant_quota_table_.Release(tenant_id, bytes)) {
-        LOG(ERROR) << "tenant quota release mismatch tenant="
-                   << tenant_id.value() << ", bytes=" << bytes;
-    }
-}
 
-void MasterService::ReleaseTenantQuotaPartial(const TenantId& tenant_id,
-                                              uint64_t bytes) {
-    if (!enable_multi_tenants_ || bytes == 0) {
-        return;
+    TenantQuotaUsageMap usage;
+    for (size_t i = 0; i < kNumShards; ++i) {
+        MetadataShardAccessorRO shard(this, i);
+        for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+            for (const auto& [_, metadata] : tenant_state.metadata) {
+                auto& charged_bytes = usage[tenant_id];
+                const uint64_t charge = CompletedMemoryQuotaCharge(metadata);
+                if (charge > TenantQuotaAccount::kMaxChargedBytes ||
+                    charged_bytes >
+                        TenantQuotaAccount::kMaxChargedBytes - charge) {
+                    throw std::overflow_error(
+                        "rebuilt tenant quota exceeds 2^63 - 1 bytes");
+                }
+                charged_bytes += charge;
+            }
+        }
     }
-    if (!tenant_quota_table_.ReleasePartial(tenant_id, bytes)) {
-        LOG(ERROR) << "tenant quota partial release mismatch tenant="
-                   << tenant_id.value() << ", bytes=" << bytes;
+
+    for (size_t i = 0; i < kNumShards; ++i) {
+        MetadataShardAccessorRW shard(this, i);
+        for (auto& [tenant_id, tenant_state] : shard->tenants) {
+            tenant_state.quota_account =
+                tenant_quota_table_.GetOrCreateTenantHandle(tenant_id);
+            for (auto& [key, metadata] : tenant_state.metadata) {
+                auto rebuild_result = metadata.quota_ledger.Rebuild(
+                    tenant_state.quota_account,
+                    CompletedMemoryQuotaCharge(metadata));
+                if (!rebuild_result) {
+                    throw std::runtime_error(
+                        "failed to rebuild object tenant quota ledger for " +
+                        tenant_id.value() + "/" + key);
+                }
+            }
+        }
     }
-}
 
-void MasterService::CommitAdditionalTenantQuota(const TenantId& tenant_id,
-                                                uint64_t bytes) {
-    if (!enable_multi_tenants_ || bytes == 0) {
-        return;
+    for (const auto& [tenant_id, _] : usage) {
+        if (!tenant_quota_table_.IsTenantRegistered(tenant_id)) {
+            LOG(WARNING)
+                << "tenant " << tenant_id.value()
+                << " exists in metadata but has no connector quota policy; "
+                   "creating orphan quota state";
+        }
     }
-    if (!tenant_quota_table_.CommitAdditional(tenant_id, bytes)) {
-        LOG(ERROR) << "tenant quota additional commit mismatch tenant="
-                   << tenant_id.value() << ", bytes=" << bytes;
+    std::lock_guard<std::mutex> recompute_lock(tenant_quota_recompute_mutex_);
+    const uint64_t capacity = GetTenantQuotaAllocatableCapacityBytes();
+    auto rebuild_result = tenant_quota_table_.RebuildUsage(usage, capacity);
+    if (!rebuild_result) {
+        throw std::runtime_error("failed to rebuild tenant quota usage");
     }
 }
 
-void MasterService::IncrementTenantMetadataObjectCount(
-    const TenantId& tenant_id) {
-    if (!enable_multi_tenants_) {
-        return;
-    }
-    tenant_quota_table_.IncrementMetadataObjectCount(tenant_id);
-}
-
-void MasterService::DecrementTenantMetadataObjectCount(
-    const TenantId& tenant_id) {
-    if (!enable_multi_tenants_) {
-        return;
-    }
-    if (!tenant_quota_table_.DecrementMetadataObjectCount(tenant_id)) {
-        LOG(WARNING) << "tenant metadata object count decrement mismatch "
-                     << "tenant=" << tenant_id.value();
-    }
-}
-
-void MasterService::ReleaseCommittedQuotaCharge(ObjectMetadata& metadata,
-                                                uint64_t bytes) {
-    if (!enable_multi_tenants_ || bytes == 0) {
-        return;
-    }
-    const uint64_t release_bytes =
-        std::min(bytes, metadata.committed_quota_charge_bytes);
-    if (release_bytes == metadata.committed_quota_charge_bytes) {
-        ReleaseTenantQuota(metadata.tenant_id, release_bytes);
-    } else {
-        ReleaseTenantQuotaPartial(metadata.tenant_id, release_bytes);
-    }
-    metadata.committed_quota_charge_bytes -= release_bytes;
-}
-
-void MasterService::RebuildTenantQuotaUsageFromMetadata() {
-    if (!enable_multi_tenants_) {
-        return;
-    }
-
-    TenantQuotaUsageMap usage;
-    for (size_t i = 0; i < kNumShards; ++i) {
-        MetadataShardAccessorRW shard(this, i);
-        for (auto& [tenant_id, tenant_state] : shard->tenants) {
-            for (auto& [_, metadata] : tenant_state.metadata) {
-                auto& tenant_usage = usage[tenant_id];
-                ++tenant_usage.metadata_object_count;
-                const uint64_t charge = CompletedMemoryQuotaCharge(metadata);
-                metadata.reserved_quota_charge_bytes = 0;
-                metadata.committed_quota_charge_bytes = charge;
-                metadata.pending_replaced_quota_charge_bytes = 0;
-                if (charge == 0) {
-                    continue;
-                }
-                tenant_usage.used_bytes += charge;
-                ++tenant_usage.committed_count;
-            }
-        }
-    }
-
-    for (const auto& [tenant_id, _] : usage) {
-        if (!tenant_quota_table_.IsTenantRegistered(tenant_id)) {
-            LOG(WARNING)
-                << "tenant " << tenant_id.value()
-                << " exists in metadata but has no connector quota policy; "
-                   "creating orphan quota state";
-        }
-    }
-    std::lock_guard<std::mutex> recompute_lock(tenant_quota_recompute_mutex_);
-    const uint64_t capacity = GetTenantQuotaAllocatableCapacityBytes();
-    tenant_quota_table_.RebuildUsage(usage, capacity);
-}
-
-std::optional<std::string> MasterService::GetGroupRoute(
-    const TenantId& tenant_id, const std::string& key) const {
-    std::shared_lock<std::shared_mutex> lock(group_routing_mutex_);
-    auto it = object_group_ids_.find(tenant_id.MakeScopedKey(key));
-    if (it == object_group_ids_.end()) {
-        return std::nullopt;
-    }
-    return it->second;
-}
-
 MasterService::ObjectOperationLock MasterService::AcquireObjectOperationLock(
     const TenantId& tenant_id, const std::string& key) {
     const auto scoped_key = tenant_id.MakeScopedKey(key);
@@ -1533,43 +1664,129 @@ MasterService::ObjectOperationLock MasterService::AcquireObjectOperationLock(
     return {std::unique_lock<std::mutex>(object_operation_locks_[stripe_idx])};
 }
 
-void MasterService::RegisterGroupMember(TenantState& tenant_state,
-                                        const TenantId& tenant_id,
-                                        const std::string& key,
-                                        const std::string& group_id) {
+std::shared_ptr<Lease> MasterService::RegisterGroupMember(
+    const TenantId& tenant_id, const std::string& key,
+    const std::string& group_id) {
     if (group_id.empty()) {
-        return;
+        return nullptr;
+    }
+    GroupDomainAccessorRW shard(this);
+    const auto scoped_group = tenant_id.MakeScopedKey(group_id);
+    auto [it, inserted] = shard->groups.try_emplace(scoped_group);
+    if (inserted) {
+        it->second.lease = std::make_shared<Lease>();
     }
-    std::unique_lock<std::shared_mutex> lock(group_routing_mutex_);
-    object_group_ids_[tenant_id.MakeScopedKey(key)] = group_id;
-    groups_needing_lease_refresh_.insert(tenant_id.MakeScopedKey(group_id));
-    tenant_state.group_members[group_id].insert(key);
+    it->second.member_keys.insert(key);
+    return it->second.lease;
 }
 
-void MasterService::UnregisterGroupMember(TenantState& tenant_state,
-                                          const TenantId& tenant_id,
+void MasterService::UnregisterGroupMember(const TenantId& tenant_id,
                                           const std::string& key,
                                           const std::string& group_id) {
     if (group_id.empty()) {
         return;
     }
-    bool group_empty = false;
-    auto group_it = tenant_state.group_members.find(group_id);
-    if (group_it != tenant_state.group_members.end()) {
-        group_it->second.erase(key);
-        if (group_it->second.empty()) {
-            tenant_state.group_members.erase(group_it);
-            group_empty = true;
-        }
+    GroupDomainAccessorRW shard(this);
+    const auto scoped_group = tenant_id.MakeScopedKey(group_id);
+    auto it = shard->groups.find(scoped_group);
+    if (it == shard->groups.end()) {
+        return;
     }
-    std::unique_lock<std::shared_mutex> lock(group_routing_mutex_);
-    auto route_it = object_group_ids_.find(tenant_id.MakeScopedKey(key));
-    if (route_it != object_group_ids_.end() && route_it->second == group_id) {
-        object_group_ids_.erase(route_it);
+    it->second.member_keys.erase(key);
+    if (it->second.member_keys.empty()) {
+        shard->groups.erase(it);
+    }
+}
+
+std::vector<std::string> MasterService::GetGroupMemberKeys(
+    const TenantId& tenant_id, const std::string& group_id) const {
+    std::vector<std::string> member_keys;
+    GroupDomainAccessorRO shard(this);
+    auto it = shard->groups.find(tenant_id.MakeScopedKey(group_id));
+    if (it != shard->groups.end()) {
+        member_keys.assign(it->second.member_keys.begin(),
+                           it->second.member_keys.end());
     }
-    if (group_empty) {
-        groups_needing_lease_refresh_.erase(tenant_id.MakeScopedKey(group_id));
+    return member_keys;
+}
+
+MasterService::GroupEvictionResult MasterService::EvictGroupOrObject(
+    const TenantId& tenant_id, const std::string& key,
+    const std::string& group_id, bool allow_soft_pinned,
+    std::chrono::system_clock::time_point now,
+    const std::function<MasterService::EvictMemberOutcome(
+        const std::string&, ObjectMetadata&, TenantState&,
+        MetadataShardAccessorRW&)>& evict_one_member) {
+    GroupEvictionResult result;
+
+    // Group membership lives in group_domain_, keyed by scoped(tenant,
+    // group_id) and read WITHOUT a metadata shard lock.
+    std::vector<std::string> member_keys =
+        GetGroupMemberKeys(tenant_id, group_id);
+    if (member_keys.empty()) {
+        member_keys.push_back(key);
+    }
+
+    // Group members live in different metadata shards (routing is decoupled
+    // from groups). Partition them by shard.
+    std::map<size_t, std::vector<std::string>> members_by_shard;
+    for (const auto& member_key : member_keys) {
+        members_by_shard[getShardIndex(tenant_id, member_key)].push_back(
+            member_key);
+    }
+
+    // Acquire shard locks in canonical ascending order and re-look-up /
+    // re-validate each member under its own lock. Iterating a std::map yields
+    // ascending shard indices, so any two group evictions touching the same
+    // shards acquire them in the same global order -> no AB/BA deadlock. The
+    // caller must not hold the trigger shard lock here.
+    auto is_evictable_memory_replica = [this](const Replica& replica) {
+        return IsEvictableMemoryReplica(replica);
+    };
+    for (const auto& [shard_idx, keys] : members_by_shard) {
+        MetadataShardAccessorRW shard(this, shard_idx);
+        auto tenant_it = shard->tenants.find(tenant_id);
+        if (tenant_it == shard->tenants.end()) {
+            continue;
+        }
+        auto& tenant_state = tenant_it->second;
+        for (const auto& member_key : keys) {
+            auto it = tenant_state.metadata.find(member_key);
+            if (it == tenant_state.metadata.end()) {
+                continue;
+            }
+            auto& member_metadata = it->second;
+            // Re-validate under the member's own lock: the group/member lease
+            // and pin state may have changed since the caller's snapshot. A
+            // surviving shared group lease makes every member's lease not
+            // expired, so the whole group is skipped here.
+            if (member_metadata.IsHardPinned() ||
+                !member_metadata.IsLeaseExpired(now) ||
+                (!allow_soft_pinned && IsSoftPinActive(member_metadata, now)) ||
+                !member_metadata.HasReplica(is_evictable_memory_replica)) {
+                continue;
+            }
+            // The callback performs only the path-specific eviction (oplog
+            // persist, offload, publish) and may erase members other than key,
+            // which invalidates `it`; we do not use `it` after the call.
+            EvictMemberOutcome member_outcome = evict_one_member(
+                member_key, member_metadata, tenant_state, shard);
+            result.freed_bytes += member_outcome.freed_bytes;
+            result.evicted_objects += member_outcome.evicted_objects;
+            if (member_outcome.stop_scan) {
+                result.stop_scan = true;
+                result.error = member_outcome.error;
+                break;
+            }
+        }
+        if (tenant_state.Empty()) {
+            shard->tenants.erase(tenant_id);
+        }
+        if (result.stop_scan) {
+            break;
+        }
     }
+    return result;
 }
 
 bool MasterService::HasCompletedMemoryCacheReplica(
@@ -1647,6 +1864,20 @@ std::vector<Replica> MasterService::PopReplicasWithCacheTotalAccounting(
     return replicas;
 }
 
+size_t MasterService::RecordDynamicReplicaRemoval(
+    ObjectMetadata& metadata, const std::vector<ReplicaID>& replica_ids) {
+    if (replica_ids.empty()) {
+        return 0;
+    }
+    const size_t removed = metadata.ForgetDynamicReplicas(replica_ids);
+    if (removed > 0) {
+        metadata.SetDynamicReplicationRecreateAfter(
+            std::chrono::steady_clock::now() +
+            kDynamicReplicationRecreateCooldown);
+    }
+    return removed;
+}
+
 size_t MasterService::EraseReplicasWithCacheTotalAccounting(
     ObjectMetadata& metadata,
     const std::function<bool(const Replica&)>& pred_fn,
@@ -1660,23 +1891,59 @@ size_t MasterService::EraseReplicasWithCacheTotalAccounting(
             erased_replica_ids->push_back(replica.id());
         }
     }
+    std::vector<ReplicaID> erased_ids;
+    erased_ids.reserve(erased_replicas.size());
+    for (const auto& replica : erased_replicas) {
+        erased_ids.push_back(replica.id());
+    }
+    RecordDynamicReplicaRemoval(metadata, erased_ids);
     // Release SSD/local-disk usage for any local-disk replicas being removed.
     // No-op for memory/noF replicas, so it is safe to call unconditionally.
     ReleaseLocalDiskUsage(erased_replicas);
+    FreeDfsReplicas(metadata.user_key, erased_replicas);
     return erased_replicas.size();
 }
 
+tl::expected<void, ErrorCode> MasterService::SettlePrimaryWriteQuotaIfReady(
+    TenantState& tenant_state, ObjectMetadata& metadata) {
+    if (!enable_multi_tenants_) {
+        return {};
+    }
+    if (!metadata.IsValid()) {
+        LOG(ERROR) << "tenant quota surviving-object settlement attempted for "
+                      "invalid metadata, tenant="
+                   << metadata.tenant_id.value()
+                   << ", key=" << metadata.user_key;
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    if (metadata.HasReplica([](const Replica& replica) {
+            return replica.is_memory_replica() && replica.is_processing();
+        })) {
+        return {};
+    }
+
+    auto account = GetBoundTenantQuotaHandle(tenant_state);
+    auto settle_result = metadata.quota_ledger.SettlePrimaryWrite(
+        account, CompletedMemoryQuotaCharge(metadata));
+    if (!settle_result) {
+        LogTenantQuotaLedgerError(settle_result, "settle_primary_write",
+                                  metadata.tenant_id, metadata.user_key);
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return {};
+}
+
 void MasterService::FinalizeRemovedReplicasAfterDurable(
     const OpLogEntry& durable_entry, const std::vector<ReplicaID>& replica_ids,
-    QuotaEraseMode quota_mode) {
+    QuotaEraseMode quota_mode,
+    const std::vector<std::string>& previous_media_hint) {
     if (replica_ids.empty()) {
         return;
     }
 
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const TenantId tenant_id(durable_entry.tenant_id);
-    const size_t shard_idx =
-        getMetadataShardIndex(tenant_id, durable_entry.object_key);
+    const size_t shard_idx = getShardIndex(tenant_id, durable_entry.object_key);
     MetadataShardAccessorRW shard(this, shard_idx);
     auto tenant_it = shard->tenants.find(tenant_id);
     if (tenant_it == shard->tenants.end()) {
@@ -1690,6 +1957,12 @@ void MasterService::FinalizeRemovedReplicasAfterDurable(
 
     std::unordered_set<ReplicaID> ids(replica_ids.begin(), replica_ids.end());
     auto& metadata = metadata_it->second;
+    // The replicas being finalized are already marked REMOVED, so the normal
+    // completed-replica view no longer contains their media. Preserve the
+    // pre-removal view (and any caller-provided snapshot) for the event delta.
+    auto previous_media = KvRemovalSnapshot(metadata);
+    previous_media.insert(previous_media.end(), previous_media_hint.begin(),
+                          previous_media_hint.end());
     auto erased_replicas = PopReplicasWithCacheTotalAccounting(
         metadata, [&ids](const Replica& replica) {
             return replica.status() == ReplicaStatus::REMOVED &&
@@ -1703,28 +1976,59 @@ void MasterService::FinalizeRemovedReplicasAfterDurable(
     for (const auto& replica : erased_replicas) {
         erased_replica_ids.push_back(replica.id());
     }
+    RecordDynamicReplicaRemoval(metadata, erased_replica_ids);
     const uint64_t erased_memory_replicas = static_cast<uint64_t>(std::count_if(
         erased_replicas.begin(), erased_replicas.end(),
         [](const Replica& replica) { return replica.is_memory_replica(); }));
-    if (erased_memory_replicas > 0) {
-        ReleaseCommittedQuotaCharge(
-            metadata, SaturatingMultiply(static_cast<uint64_t>(metadata.size),
-                                         erased_memory_replicas));
+    const bool has_processing_memory =
+        metadata.HasReplica([](const Replica& replica) {
+            return replica.is_memory_replica() && replica.is_processing();
+        });
+    if (enable_multi_tenants_ && erased_memory_replicas > 0 &&
+        has_processing_memory) {
+        const uint64_t committed_charge =
+            metadata.quota_ledger.CommittedBytes();
+        if (metadata.size > committed_charge / erased_memory_replicas) {
+            LOG(ERROR) << "tenant quota removed-replica release exceeds "
+                          "committed bytes, tenant="
+                       << tenant_id.value()
+                       << ", key=" << durable_entry.object_key
+                       << ", object_size=" << metadata.size
+                       << ", erased_memory_replicas=" << erased_memory_replicas
+                       << ", committed_bytes=" << committed_charge;
+        } else {
+            const uint64_t release_bytes =
+                metadata.size * erased_memory_replicas;
+            auto release_result = metadata.quota_ledger.ReleaseCommitted(
+                GetBoundTenantQuotaHandle(tenant_state), release_bytes);
+            LogTenantQuotaLedgerError(release_result, "release_committed",
+                                      tenant_id, durable_entry.object_key);
+        }
     }
     const bool erased_local_disk = std::any_of(
         erased_replicas.begin(), erased_replicas.end(),
         [](const Replica& replica) { return replica.is_local_disk_replica(); });
     ReleaseLocalDiskUsage(erased_replicas);
+    FreeDfsReplicas(metadata.user_key, erased_replicas);
     if (erased_local_disk) {
         shard.OnDiskReplicaRemoved(erased_local_disk, metadata);
     }
     CancelPromotionTaskForRemovedReplicas(tenant_state, metadata,
                                           erased_replica_ids);
     if (!metadata.IsValid()) {
-        EraseMetadata(tenant_state, metadata_it, tenant_id, quota_mode, &shard);
+        EraseMetadata(tenant_state, metadata_it, tenant_id, quota_mode, &shard,
+                      previous_media);
         if (tenant_state.Empty()) {
             shard->tenants.erase(tenant_it);
         }
+    } else {
+        SyncKvObjectState(durable_entry.object_key, metadata, tenant_id,
+                          previous_media);
+        auto settle_result =
+            SettlePrimaryWriteQuotaIfReady(tenant_state, metadata);
+        if (settle_result && metadata.AllReplicas(&Replica::fn_is_completed)) {
+            tenant_state.processing_keys.erase(durable_entry.object_key);
+        }
     }
 }
 
@@ -1732,8 +2036,7 @@ void MasterService::FinalizeMetadataEraseAfterDurable(
     const OpLogEntry& durable_entry, QuotaEraseMode quota_mode) {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const TenantId tenant_id(durable_entry.tenant_id);
-    const size_t shard_idx =
-        getMetadataShardIndex(tenant_id, durable_entry.object_key);
+    const size_t shard_idx = getShardIndex(tenant_id, durable_entry.object_key);
     MetadataShardAccessorRW shard(this, shard_idx);
     auto tenant_it = shard->tenants.find(tenant_id);
     if (tenant_it == shard->tenants.end()) {
@@ -1762,27 +2065,36 @@ void MasterService::FinalizeExpiredProcessingReplicasAfterDurable(
     }
 
     auto& metadata = accessor.Get();
+    // Snapshot before popping: the pop is what makes a medium disappear, and
+    // the publisher needs the pre-pop set to compute the removal delta. Mirrors
+    // FinalizeExpiredReplicationTaskAfterDurable.
+    const auto previous_media = KvRemovalSnapshot(metadata);
     auto replicas = PopReplicasWithCacheTotalAccounting(
         metadata, &Replica::fn_is_processing);
     if (!replicas.empty()) {
+        FreeDfsReplicas(metadata.user_key, replicas);
         std::lock_guard lock(discarded_replicas_mutex_);
         discarded_replicas_.emplace_back(std::move(replicas), ttl);
     }
     if (!metadata.IsValid()) {
-        accessor.Erase();
-    } else if (accessor.InProcessing()) {
-        accessor.EraseFromProcessing();
+        accessor.Erase(previous_media);
+    } else {
+        SyncKvObjectState(durable_entry.object_key, metadata, tenant_id,
+                          previous_media);
+        auto settle_result =
+            SettlePrimaryWriteQuotaIfReady(accessor.GetTenantState(), metadata);
+        if (settle_result && accessor.InProcessing()) {
+            accessor.EraseFromProcessing();
+        }
     }
 }
 
 void MasterService::FinalizeExpiredReplicationTaskAfterDurable(
     const OpLogEntry& durable_entry, ReplicaID source_id,
     const std::vector<ReplicaID>& target_ids,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch,
     const std::chrono::system_clock::time_point& ttl) {
-    if (target_ids.empty()) {
-        return;
-    }
-
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const TenantId tenant_id(durable_entry.tenant_id);
     MetadataAccessorRW accessor(this, MakeObjectIdentityForRequest(
@@ -1791,42 +2103,87 @@ void MasterService::FinalizeExpiredReplicationTaskAfterDurable(
         return;
     }
 
+    if (!accessor.HasReplicationTask()) {
+        return;
+    }
+    auto& task = accessor.GetReplicationTask();
+    if (!task.durable_cleanup_pending || task.source_id != source_id ||
+        task.replica_ids != target_ids ||
+        task.dynamic_replication_lease_id != dynamic_replication_lease_id ||
+        task.dynamic_replication_version_epoch !=
+            dynamic_replication_version_epoch) {
+        return;
+    }
+
     auto& metadata = accessor.Get();
     if (auto source = metadata.GetReplicaByID(source_id); source != nullptr) {
         source->dec_refcnt();
     }
 
+    // Snapshot the visible media before popping: targets are matched by id
+    // regardless of status, so a completed replica can be dropped here and its
+    // medium would otherwise be unrecoverable for the remove delta.
+    const auto previous_media = KvRemovalSnapshot(metadata);
     std::unordered_set<ReplicaID> ids(target_ids.begin(), target_ids.end());
     auto replicas = PopReplicasWithCacheTotalAccounting(
         metadata,
         [&ids](const Replica& replica) { return ids.contains(replica.id()); });
+    std::vector<ReplicaID> erased_replica_ids;
+    erased_replica_ids.reserve(replicas.size());
+    for (const auto& replica : replicas) {
+        erased_replica_ids.push_back(replica.id());
+    }
+    const bool dynamic_task = dynamic_replication_lease_id != UUID{} ||
+                              dynamic_replication_version_epoch != 0;
+    RecordDynamicReplicaRemoval(metadata, erased_replica_ids);
     if (!replicas.empty()) {
+        FreeDfsReplicas(metadata.user_key, replicas);
         std::lock_guard lock(discarded_replicas_mutex_);
         discarded_replicas_.emplace_back(std::move(replicas), ttl);
     }
+    if (dynamic_task) {
+        ClearDynamicReplicationStateForKey(accessor.GetTenantState(),
+                                           durable_entry.object_key);
+    }
     if (!metadata.IsValid()) {
-        accessor.Erase();
-    } else if (accessor.HasReplicationTask()) {
-        AbortTenantQuota(
-            tenant_id,
-            accessor.GetReplicationTask().reserved_quota_charge_bytes);
-        accessor.EraseReplicationTask();
+        accessor.Erase(previous_media);
+    } else {
+        // Publish before EraseReplicationTask, which may drop an emptied
+        // tenant and invalidate the metadata reference.
+        SyncKvObjectState(durable_entry.object_key, metadata, tenant_id,
+                          previous_media);
+        if (accessor.HasReplicationTask()) {
+            const auto& task = accessor.GetReplicationTask();
+            ReleaseTenantQuota(
+                GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                task.pending_quota_charge_bytes);
+            accessor.EraseReplicationTask();
+        }
     }
 }
 
 MasterService::StaleHandleCleanupPlan
 MasterService::BuildStaleHandleCleanupPlan(
     const ObjectMetadata& metadata,
-    const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients) const {
+    const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients)
+    const {
+    return BuildStaleHandleCleanupPlan(
+        metadata, [&retaining_clients](const Replica& replica) {
+            return (replica.has_invalid_mem_handle() ||
+                    replica.has_invalid_nof_handle() ||
+                    replica.has_stale_local_disk_client(retaining_clients)) &&
+                   replica.is_completed();
+        });
+}
+
+MasterService::StaleHandleCleanupPlan
+MasterService::BuildStaleHandleCleanupPlan(
+    const ObjectMetadata& metadata,
+    const std::function<bool(const Replica&)>& is_stale) const {
     StaleHandleCleanupPlan plan;
     bool has_valid_after_cleanup = false;
     for (const auto& replica : metadata.GetAllReplicas()) {
-        const bool stale =
-            (replica.has_invalid_mem_handle() ||
-             replica.has_invalid_nof_handle() ||
-             replica.has_stale_local_disk_client(alive_clients)) &&
-            replica.is_completed();
-        if (stale) {
+        if (is_stale(replica)) {
             plan.removed_ids.push_back(replica.id());
             continue;
         }
@@ -1851,11 +2208,9 @@ tl::expected<void, ErrorCode> MasterService::PersistStaleHandleCleanupForHA(
     const auto op_type =
         plan.would_invalidate ? OpType::REMOVE : OpType::PUT_END;
     const std::string payload =
-        plan.would_invalidate
-            ? std::string{}
-            : SerializeMetadataForOpLogFromReplicaDescriptors(
-                  metadata.client_id, metadata.size, plan.remaining,
-                  metadata.group_id, metadata.data_type);
+        plan.would_invalidate ? std::string{}
+                              : SerializeMetadataForOpLogFromReplicaDescriptors(
+                                    metadata, plan.remaining);
 
     auto reservation = ReserveBatchOpLogSlot();
     if (!reservation) {
@@ -1875,6 +2230,11 @@ tl::expected<void, ErrorCode> MasterService::PersistStaleHandleCleanupForHA(
                                                 QuotaEraseMode::kFull);
         });
     if (!result) {
+        metadata.VisitReplicas(
+            [&ids](const Replica& replica) {
+                return ids.contains(replica.id());
+            },
+            [](Replica& replica) { replica.cancel_remove(); });
         LOG(WARNING) << why
                      << ": stale cleanup OpLog queue failed for key=" << key
                      << ", err=" << static_cast<int>(result.error());
@@ -1883,7 +2243,7 @@ tl::expected<void, ErrorCode> MasterService::PersistStaleHandleCleanupForHA(
     return {};
 }
 
-std::unordered_map<std::string, MasterService::ObjectMetadata>::iterator
+std::unordered_map<std::string, ObjectMetadata>::iterator
 MasterService::EraseMetadata(
     TenantState& tenant_state,
     std::unordered_map<std::string, ObjectMetadata>::iterator it,
@@ -1891,7 +2251,7 @@ MasterService::EraseMetadata(
     return EraseMetadata(tenant_state, it, tenant_id, QuotaEraseMode::kFull);
 }
 
-std::unordered_map<std::string, MasterService::ObjectMetadata>::iterator
+std::unordered_map<std::string, ObjectMetadata>::iterator
 MasterService::EraseMetadata(
     TenantState& tenant_state,
     std::unordered_map<std::string, ObjectMetadata>::iterator it,
@@ -1903,12 +2263,13 @@ MasterService::EraseMetadata(
 // associated per-key state: offloading_tasks (with dec_refcnt),
 // processing_keys, replication_tasks, and promotion tasks.
 // Callers no longer need to clean these up manually before calling.
-std::unordered_map<std::string, MasterService::ObjectMetadata>::iterator
+std::unordered_map<std::string, ObjectMetadata>::iterator
 MasterService::EraseMetadata(
     TenantState& tenant_state,
     std::unordered_map<std::string, ObjectMetadata>::iterator it,
     const TenantId& tenant_id, QuotaEraseMode quota_mode,
-    MetadataShardAccessorRW* shard) {
+    MetadataShardAccessorRW* shard,
+    const std::vector<std::string>& previous_media_hint) {
     bool had_completed_disk = it->second.HasReplica([](const Replica& r) {
         return r.is_local_disk_replica() && r.is_completed();
     });
@@ -1916,6 +2277,21 @@ MasterService::EraseMetadata(
     const std::string group_id = it->second.group_id;
     auto& metadata = it->second;
 
+    // Preserve the publisher's state while a size-changing upsert temporarily
+    // removes the old metadata. A complete erase emits one remove event per
+    // media that was previously visible.
+    if (quota_mode == QuotaEraseMode::kPreserveOld) {
+        // Union rather than replace: the caller hint may only describe one
+        // tier, so a medium still visible in metadata must not be dropped
+        // from the remove delta.
+        auto previous_media = KvRemovalSnapshot(metadata);
+        previous_media.insert(previous_media.end(), previous_media_hint.begin(),
+                              previous_media_hint.end());
+        SyncKvObjectState(key, metadata, tenant_id, previous_media);
+    } else {
+        PublishKvRemoved(key, metadata, tenant_id, previous_media_hint);
+    }
+
     // Clean up offloading_task + dec_refcnt before erasing metadata.
     // When BatchEvict deletes metadata, Store Worker may still have an
     // in-flight offload for this key. Without this cleanup the task
@@ -1928,44 +2304,67 @@ MasterService::EraseMetadata(
         }
         tenant_state.offloading_tasks.erase(offload_it);
 
-        // Mirror entry in local_disk_segment.offloading_objects must be
-        // dropped too, otherwise the next OffloadObjectHeartbeat drains a
-        // task-less key back to the client and produces an orphan bucket.
-        const std::string scoped_key = tenant_id.MakeScopedKey(key);
-        ScopedLocalDiskSegmentAccess ssd_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        for (auto& [_, segment] : ssd_access.getClientLocalDiskSegment()) {
-            MutexLocker locker(&segment->offloading_mutex_);
-            segment->offloading_objects.erase(scoped_key);
-        }
+        // The mailbox entry must be dropped too, otherwise the next
+        // OffloadObjectHeartbeat drains a task-less key back to the client and
+        // produces an orphan bucket.
+        local_ssd_manager_.RemoveOffloadFromAll(tenant_id, key);
     }
     tenant_state.processing_keys.erase(key);
-    tenant_state.replication_tasks.erase(key);
-    ErasePromotionTaskIfPresent(tenant_state, key, tenant_id);
+    auto replication_task_it = tenant_state.replication_tasks.find(key);
+    if (replication_task_it != tenant_state.replication_tasks.end()) {
+        auto source =
+            metadata.GetReplicaByID(replication_task_it->second.source_id);
+        if (source != nullptr) {
+            source->dec_refcnt();
+        }
+        ReleaseTenantQuota(
+            GetBoundTenantQuotaHandle(tenant_state),
+            replication_task_it->second.pending_quota_charge_bytes);
+        tenant_state.replication_tasks.erase(replication_task_it);
+    }
+    ErasePromotionTaskIfPresent(tenant_state, key);
+    ClearDynamicReplicationStateForKey(tenant_state, key);
 
     ReleaseLocalDiskUsage(metadata.GetAllReplicas());
+    FreeDfsReplicas(key, metadata.GetAllReplicas());
     AccountCacheTotalRemoval(metadata);
+    if (metadata.GetCommittedSoftPinTimeout()) {
+        soft_pin_deadline_index_.Remove(tenant_id.MakeScopedKey(key));
+    }
     switch (quota_mode) {
         case QuotaEraseMode::kFull:
-            AbortTenantQuota(tenant_id, metadata.reserved_quota_charge_bytes);
-            ReleaseTenantQuota(tenant_id,
-                               metadata.committed_quota_charge_bytes);
-            ReleaseTenantQuota(tenant_id,
-                               metadata.pending_replaced_quota_charge_bytes);
+            if (enable_multi_tenants_ &&
+                metadata.quota_ledger.TotalChargedBytes() != 0) {
+                auto release_result = metadata.quota_ledger.ReleaseAll(
+                    GetBoundTenantQuotaHandle(tenant_state));
+                LogTenantQuotaLedgerError(release_result, "release_all",
+                                          tenant_id, key);
+            }
             break;
         case QuotaEraseMode::kPreserveOld:
-            AbortTenantQuota(tenant_id, metadata.reserved_quota_charge_bytes);
-            break;
         case QuotaEraseMode::kAbortOnly:
-            AbortTenantQuota(tenant_id, metadata.reserved_quota_charge_bytes);
+            if (enable_multi_tenants_ &&
+                metadata.quota_ledger.PendingBytes() != 0) {
+                auto refund_result = metadata.quota_ledger.RefundPending(
+                    GetBoundTenantQuotaHandle(tenant_state));
+                LogTenantQuotaLedgerError(refund_result, "refund_pending",
+                                          tenant_id, key);
+            }
+            if (enable_multi_tenants_ &&
+                metadata.quota_ledger.TotalChargedBytes() != 0) {
+                LOG(ERROR)
+                    << "tenant quota ledger still owns bytes during preserved "
+                       "metadata erase tenant="
+                    << tenant_id.value() << ", key=" << key
+                    << ", bytes=" << metadata.quota_ledger.TotalChargedBytes();
+            }
             break;
     }
     auto next = tenant_state.metadata.erase(it);
-    DecrementTenantMetadataObjectCount(tenant_id);
     if (had_completed_disk && shard) {
         shard->OnDiskReplicaRemoved(had_completed_disk);
     }
-    UnregisterGroupMember(tenant_state, tenant_id, key, group_id);
+    UnregisterGroupMember(tenant_id, key, group_id);
     return next;
 }
 
@@ -1986,124 +2385,424 @@ void MasterService::ReleaseLocalDiskUsage(
         return;
     }
 
-    ScopedLocalDiskSegmentAccess ssd_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_segments = ssd_access.getClientLocalDiskSegment();
     for (const auto& [client_id, bytes] : bytes_by_client) {
-        auto disk_it = client_segments.find(client_id);
-        if (disk_it != client_segments.end()) {
-            disk_it->second->ssd_used_bytes.fetch_sub(
-                bytes, std::memory_order_relaxed);
-        }
+        local_ssd_manager_.AdjustUsedBytes(client_id, -bytes);
     }
 }
 
-void MasterService::RebuildGroupRoutingIndex() {
-    std::unordered_map<std::string, std::string> rebuilt_group_ids;
-    std::unordered_set<std::string> groups_needing_refresh;
+void MasterService::RebuildGroupState() {
+    // The group domain is a derived index of grouped object membership. Rebuild
+    // it from object metadata after snapshot/standby restore.
+    {
+        GroupDomainAccessorRW group_domain(this);
+        group_domain->groups.clear();
+    }
+    // Pass 1: aggregate the maximum restored lease deadline per group so a
+    // grouped object is not left with a zero-deadline lease, which would make
+    // it look expired and be dropped by post-restore cleanup.
+    std::unordered_map<std::string, std::chrono::system_clock::time_point>
+        max_deadline_by_group;
     for (size_t shard_idx = 0; shard_idx < kNumShards; ++shard_idx) {
-        MetadataShardAccessorRW shard(this, shard_idx);
-        for (auto& [tenant_id, tenant_state] : shard->tenants) {
-            tenant_state.group_members.clear();
+        MetadataShardAccessorRO shard(this, shard_idx);
+        for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+            for (const auto& [key, metadata] : tenant_state.metadata) {
+                if (!metadata.IsGrouped()) {
+                    continue;
+                }
+                const auto scoped = tenant_id.MakeScopedKey(metadata.group_id);
+                const auto deadline = metadata.lease_->ExpiresAt();
+                auto [it, inserted] =
+                    max_deadline_by_group.try_emplace(scoped, deadline);
+                if (!inserted) {
+                    it->second = std::max(it->second, deadline);
+                }
+            }
+        }
+    }
+    // Pass 2: rebuild membership and wire the shared lease, preserving the
+    // group's maximum restored deadline.
+    for (size_t shard_idx = 0; shard_idx < kNumShards; ++shard_idx) {
+        MetadataShardAccessorRO shard(this, shard_idx);
+        for (const auto& [tenant_id, tenant_state] : shard->tenants) {
             for (const auto& [key, metadata] : tenant_state.metadata) {
                 if (!metadata.IsGrouped()) {
                     continue;
                 }
-                tenant_state.group_members[metadata.group_id].insert(key);
-                rebuilt_group_ids[tenant_id.MakeScopedKey(key)] =
-                    metadata.group_id;
-                groups_needing_refresh.insert(
+                auto lease =
+                    RegisterGroupMember(tenant_id, key, metadata.group_id);
+                auto it = max_deadline_by_group.find(
                     tenant_id.MakeScopedKey(metadata.group_id));
+                if (it != max_deadline_by_group.end()) {
+                    lease->ExtendTo(it->second);
+                }
+                metadata.lease_ = lease;
             }
         }
     }
-    {
-        std::unique_lock<std::shared_mutex> lock(group_routing_mutex_);
-        object_group_ids_ = std::move(rebuilt_group_ids);
-        groups_needing_lease_refresh_ = std::move(groups_needing_refresh);
+}
+
+void MasterService::ReRouteRestoredObjectsByKey() {
+    // Snapshots produced by a router that placed grouped objects on
+    // hash(group_id) shards restore those objects to the wrong shard; the
+    // rest of this version looks every object up by hash(tenant, key). Move any
+    // object whose hash(tenant, key) shard differs from the one it was restored
+    // to. Node handles transfer the storage without moving ObjectMetadata
+    // (which has const members), so no copy/move constructor is required.
+    bool moved = false;
+    for (size_t src_idx = 0; src_idx < kNumShards; ++src_idx) {
+        MetadataShardAccessorRW src(this, src_idx);
+        for (auto tenant_it = src->tenants.begin();
+             tenant_it != src->tenants.end();) {
+            const auto tenant_id = tenant_it->first;
+            auto& tenant_state = tenant_it->second;
+            for (auto obj_it = tenant_state.metadata.begin();
+                 obj_it != tenant_state.metadata.end();) {
+                const size_t dst_idx =
+                    getShardIndex(tenant_id, obj_it->second.user_key);
+                if (dst_idx == src_idx) {
+                    ++obj_it;
+                    continue;
+                }
+                auto next = std::next(obj_it);
+                auto node = tenant_state.metadata.extract(obj_it);
+                if (node.empty()) {
+                    obj_it = next;
+                    continue;
+                }
+                MetadataShardAccessorRW dst(this, dst_idx);
+                auto& dst_tenant = GetOrCreateTenantState(dst.get(), tenant_id);
+                // Restored snapshots have unique (tenant, key) so a collision
+                // here would only happen for a corrupt snapshot; keep the
+                // existing entry in that case.
+                dst_tenant.metadata.insert(std::move(node));
+                moved = true;
+                obj_it = next;
+            }
+            if (tenant_state.Empty()) {
+                tenant_it = src->tenants.erase(tenant_it);
+            } else {
+                ++tenant_it;
+            }
+        }
+    }
+
+    // Only recompute the per-shard counter when objects actually moved; a
+    // current-format snapshot needs no migration and its counts are already
+    // correct from DeserializeShard.
+    if (!moved) {
+        return;
+    }
+    for (size_t i = 0; i < kNumShards; ++i) {
+        MetadataShardAccessorRW shard(this, i);
+        shard->disk_object_count = 0;
+        for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+            for (const auto& [key, metadata] : tenant_state.metadata) {
+                if (metadata.HasReplica([](const Replica& r) {
+                        return r.is_local_disk_replica() && r.is_completed();
+                    })) {
+                    shard->disk_object_count++;
+                }
+            }
+        }
     }
 }
 
-void MasterService::GrantLeaseForGroup(const TenantState& tenant_state,
-                                       const std::string& key,
-                                       const ObjectMetadata& metadata) const {
-    if (!metadata.IsGrouped()) {
-        metadata.GrantLease(default_kv_lease_ttl_, default_kv_soft_pin_ttl_);
+void MasterService::SoftPinDeadlineIndex::MaybeCompactLocked() {
+    const size_t live_count = registrations_.size();
+    const size_t ratio_limit =
+        live_count > std::numeric_limits<size_t>::max() / kCompactionRatio
+            ? std::numeric_limits<size_t>::max()
+            : live_count * kCompactionRatio;
+    const size_t threshold = std::max(kMinCompactionThreshold, ratio_limit);
+    if (heap_.size() <= threshold) {
         return;
     }
 
-    bool needs_refresh = metadata.NeedsLeaseRefresh(default_kv_lease_ttl_,
-                                                    default_kv_soft_pin_ttl_);
-    if (!needs_refresh) {
-        std::shared_lock<std::shared_mutex> lock(group_routing_mutex_);
-        needs_refresh =
-            groups_needing_lease_refresh_.find(metadata.tenant_id.MakeScopedKey(
-                metadata.group_id)) != groups_needing_lease_refresh_.end();
+    decltype(heap_) rebuilt;
+    for (const auto& [scoped_key, registration] : registrations_) {
+        rebuilt.push(
+            Entry{registration.deadline, registration.shard_idx, scoped_key});
     }
-    if (!needs_refresh) {
+    heap_.swap(rebuilt);
+}
+
+void MasterService::SoftPinDeadlineIndex::Upsert(std::string scoped_key,
+                                                 size_t shard_idx,
+                                                 const TimePoint& deadline) {
+    std::lock_guard lock(mutex_);
+    const auto it = registrations_.find(scoped_key);
+    if (it != registrations_.end() && it->second.deadline == deadline &&
+        it->second.shard_idx == shard_idx) {
         return;
     }
 
-    auto group_it = tenant_state.group_members.find(metadata.group_id);
-    if (group_it == tenant_state.group_members.end()) {
-        metadata.GrantLease(default_kv_lease_ttl_, default_kv_soft_pin_ttl_);
-        return;
+    auto [registration_it, inserted] = registrations_.insert_or_assign(
+        scoped_key, Registration{deadline, shard_idx});
+    (void)inserted;
+    heap_.push(Entry{deadline, shard_idx, registration_it->first});
+    MaybeCompactLocked();
+}
+
+void MasterService::SoftPinDeadlineIndex::Remove(
+    const std::string& scoped_key) {
+    std::lock_guard lock(mutex_);
+    if (registrations_.erase(scoped_key) > 0) {
+        MaybeCompactLocked();
     }
+}
+
+void MasterService::SoftPinDeadlineIndex::RemoveIfMatches(
+    const std::string& scoped_key, size_t shard_idx,
+    const TimePoint& deadline) {
+    std::lock_guard lock(mutex_);
+    const auto it = registrations_.find(scoped_key);
+    if (it != registrations_.end() && it->second.deadline == deadline &&
+        it->second.shard_idx == shard_idx) {
+        registrations_.erase(it);
+        MaybeCompactLocked();
+    }
+}
 
-    for (const auto& member_key : group_it->second) {
-        auto mit = tenant_state.metadata.find(member_key);
-        if (mit != tenant_state.metadata.end()) {
-            mit->second.GrantLease(default_kv_lease_ttl_,
-                                   default_kv_soft_pin_ttl_);
+std::vector<MasterService::SoftPinDeadlineIndex::Entry>
+MasterService::SoftPinDeadlineIndex::PopExpired(const TimePoint& now) {
+    std::vector<Entry> expired;
+    std::lock_guard lock(mutex_);
+    while (!heap_.empty() && heap_.top().deadline <= now) {
+        Entry entry = heap_.top();
+        heap_.pop();
+
+        const auto it = registrations_.find(entry.scoped_key);
+        if (it == registrations_.end() ||
+            it->second.deadline != entry.deadline ||
+            it->second.shard_idx != entry.shard_idx) {
+            continue;
         }
+        registrations_.erase(it);
+        expired.push_back(std::move(entry));
     }
-    if (group_it->second.find(key) == group_it->second.end()) {
-        metadata.GrantLease(default_kv_lease_ttl_, default_kv_soft_pin_ttl_);
+    MaybeCompactLocked();
+    return expired;
+}
+
+void MasterService::SoftPinDeadlineIndex::Clear() {
+    std::lock_guard lock(mutex_);
+    registrations_.clear();
+    decltype(heap_) empty;
+    heap_.swap(empty);
+}
+
+auto MasterService::ResolveSoftPinRequest(const ReplicateConfig& config) const
+    -> tl::expected<ResolvedSoftPinRequest, ErrorCode> {
+    switch (config.soft_pin_action) {
+        case SoftPinAction::PRESERVE:
+        case SoftPinAction::DISABLE:
+            if (config.soft_pin_ttl_ms.has_value()) {
+                LOG(ERROR) << "soft_pin_action=" << config.soft_pin_action
+                           << ", soft_pin_ttl_ms=" << *config.soft_pin_ttl_ms
+                           << ", error=ttl_requires_enable";
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            return ResolvedSoftPinRequest{config.soft_pin_action,
+                                          std::chrono::milliseconds::zero()};
+        case SoftPinAction::ENABLE: {
+            const uint64_t ttl_ms =
+                config.soft_pin_ttl_ms.value_or(default_kv_soft_pin_ttl_);
+            if (ttl_ms > max_kv_soft_pin_ttl_) {
+                LOG(ERROR) << "soft_pin_ttl_ms=" << ttl_ms
+                           << ", max_kv_soft_pin_ttl=" << max_kv_soft_pin_ttl_
+                           << ", error=soft_pin_ttl_exceeds_limit";
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            return ResolvedSoftPinRequest{config.soft_pin_action,
+                                          std::chrono::milliseconds(ttl_ms)};
+        }
     }
-    {
-        std::unique_lock<std::shared_mutex> lock(group_routing_mutex_);
-        groups_needing_lease_refresh_.erase(
-            metadata.tenant_id.MakeScopedKey(metadata.group_id));
+    LOG(ERROR) << "soft_pin_action="
+               << static_cast<uint32_t>(config.soft_pin_action)
+               << ", error=invalid_soft_pin_action";
+    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+}
+
+void MasterService::ApplySoftPinMetricDelta(int metric_delta) {
+    if (metric_delta > 0) {
+        MasterMetricManager::instance().inc_soft_pin_key_count(metric_delta);
+    } else if (metric_delta < 0) {
+        MasterMetricManager::instance().dec_soft_pin_key_count(-metric_delta);
     }
 }
 
-void MasterService::ClearInvalidHandles() {
-    ClearInvalidHandles(getAliveClientsSnapshot());
+size_t MasterService::GetMetadataShardIndex(
+    const ObjectMetadata& metadata) const {
+    // Object routing is decoupled from groups: always route by the object's
+    // own (tenant, key) hash. group_id is an annotation only.
+    return getShardIndex(metadata.tenant_id, metadata.user_key);
 }
 
-void MasterService::ClearInvalidHandles(
-    const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients) {
-    for (size_t i = 0; i < kNumShards; i++) {
-        MetadataShardAccessorRW shard(this, i);
-        for (auto tenant_it = shard->tenants.begin();
-             tenant_it != shard->tenants.end();) {
-            auto& tenant_state = tenant_it->second;
-            auto it = tenant_state.metadata.begin();
-            while (it != tenant_state.metadata.end()) {
-                const auto cleanup_plan =
-                    BuildStaleHandleCleanupPlan(it->second, alive_clients);
-                if (!cleanup_plan.removed_ids.empty()) {
-                    if (enable_ha_) {
-                        if (enable_oplog_) {
-                            auto persist_result =
-                                PersistStaleHandleCleanupForHA(
-                                    "ClearInvalidHandles", tenant_it->first,
-                                    it->first, it->second, cleanup_plan);
-                            if (!persist_result) {
-                                ++it;
-                                continue;
-                            }
-                            ++it;
-                            continue;
-                        }
-                    }
-                    if (CleanupStaleHandles(tenant_state, it->second,
-                                            alive_clients, &shard)) {
-                        it = EraseMetadata(tenant_state, it, tenant_it->first,
-                                           QuotaEraseMode::kFull, &shard);
-                    } else {
-                        ++it;
-                    }
+void MasterService::ApplySoftPinEvaluation(
+    const ObjectMetadata& metadata,
+    const ObjectMetadata::SoftPinEvaluation& result) const {
+    if (!result.deadline_to_index && !result.removed_deadline) {
+        ApplySoftPinMetricDelta(result.metric_delta);
+        return;
+    }
+
+    const size_t shard_idx = GetMetadataShardIndex(metadata);
+    const auto scoped_key = metadata.tenant_id.MakeScopedKey(metadata.user_key);
+    if (result.deadline_to_index) {
+        soft_pin_deadline_index_.Upsert(scoped_key, shard_idx,
+                                        *result.deadline_to_index);
+    } else if (result.removed_deadline) {
+        soft_pin_deadline_index_.RemoveIfMatches(scoped_key, shard_idx,
+                                                 *result.removed_deadline);
+    }
+    ApplySoftPinMetricDelta(result.metric_delta);
+}
+
+bool MasterService::IsSoftPinActive(
+    const ObjectMetadata& metadata,
+    const std::chrono::system_clock::time_point& now) const {
+    const auto evaluation = metadata.EvaluateSoftPin(now);
+    ApplySoftPinEvaluation(metadata, evaluation);
+    return evaluation.active;
+}
+
+void MasterService::CleanupExpiredSoftPins(
+    const std::chrono::system_clock::time_point& now) {
+    auto expired_entries = soft_pin_deadline_index_.PopExpired(now);
+    std::sort(expired_entries.begin(), expired_entries.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.shard_idx < rhs.shard_idx;
+              });
+
+    int expired_count = 0;
+    for (size_t begin = 0; begin < expired_entries.size();) {
+        const size_t shard_idx = expired_entries[begin].shard_idx;
+        size_t end = begin + 1;
+        while (end < expired_entries.size() &&
+               expired_entries[end].shard_idx == shard_idx) {
+            ++end;
+        }
+
+        MetadataShardAccessorRO shard(this, shard_idx);
+        for (size_t i = begin; i < end; ++i) {
+            const auto& entry = expired_entries[i];
+            const auto [tenant_id, key] =
+                TenantId::ParseScopedKey(entry.scoped_key);
+            const auto tenant_it = shard->tenants.find(tenant_id);
+            if (tenant_it == shard->tenants.end()) {
+                continue;
+            }
+            const auto metadata_it = tenant_it->second.metadata.find(key);
+            if (metadata_it == tenant_it->second.metadata.end()) {
+                continue;
+            }
+            if (metadata_it->second.ExpireSoftPinIfDeadlineMatches(
+                    entry.deadline, now)) {
+                ++expired_count;
+            }
+        }
+        begin = end;
+    }
+    if (expired_count > 0) {
+        MasterMetricManager::instance().dec_soft_pin_key_count(expired_count);
+    }
+}
+
+void MasterService::ClearInvalidHandles() {
+    std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
+    std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+    auto retaining_clients = GetRetainingClientIdsLocked();
+    client_lock.unlock();
+    ClearInvalidHandles(retaining_clients);
+}
+
+void MasterService::ClearInvalidHandles(
+    const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients) {
+    (void)ClearStaleHandles([&retaining_clients](const Replica& replica) {
+        return (replica.has_invalid_mem_handle() ||
+                replica.has_invalid_nof_handle() ||
+                replica.has_stale_local_disk_client(retaining_clients)) &&
+               replica.is_completed();
+    });
+}
+
+void MasterService::ClearLocalDiskHandlesOwnedBy(const UUID& owner) {
+    (void)ClearStaleHandles([&owner](const Replica& replica) {
+        return replica.is_local_disk_replica() && replica.is_completed() &&
+               replica.get_local_disk_client_id() == owner;
+    });
+}
+
+tl::expected<void, ErrorCode> MasterService::ClearStaleHandles(
+    const std::function<bool(const Replica&)>& is_stale) {
+    std::optional<ErrorCode> first_persist_error;
+    for (size_t i = 0; i < kNumShards; i++) {
+        // Pass 1: pick out the keys that need work under the shard's shared
+        // lock. A sweep normally finds nothing in most shards, and such a
+        // shard never takes the exclusive lock at all.
+        std::vector<std::pair<TenantId, std::string>> stale_keys;
+        std::vector<TenantId> empty_tenants;
+        {
+            MetadataShardAccessorRO shard(this, i);
+            for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+                if (tenant_state.Empty()) {
+                    empty_tenants.push_back(tenant_id);
+                    continue;
+                }
+                for (const auto& [key, metadata] : tenant_state.metadata) {
+                    if (metadata.HasReplica(is_stale) || !metadata.IsValid()) {
+                        stale_keys.emplace_back(tenant_id, key);
+                    }
+                }
+            }
+        }
+
+        // Pass 2: clean the picked keys in bounded batches, so the exclusive
+        // hold is capped by kStaleHandleCleanupBatchSize instead of by the
+        // size of the shard. The shard may have changed while the lock was
+        // released, so every key is looked up and re-classified here.
+        bool erased_in_shard = false;
+        for (size_t begin = 0; begin < stale_keys.size();
+             begin += kStaleHandleCleanupBatchSize) {
+            const size_t end = std::min(begin + kStaleHandleCleanupBatchSize,
+                                        stale_keys.size());
+            MetadataShardAccessorRW shard(this, i);
+            for (size_t j = begin; j < end; j++) {
+                auto tenant_it = shard->tenants.find(stale_keys[j].first);
+                if (tenant_it == shard->tenants.end()) {
+                    continue;
+                }
+                auto& tenant_state = tenant_it->second;
+                auto it = tenant_state.metadata.find(stale_keys[j].second);
+                if (it == tenant_state.metadata.end()) {
+                    continue;
+                }
+                const auto cleanup_plan =
+                    BuildStaleHandleCleanupPlan(it->second, is_stale);
+                if (!cleanup_plan.removed_ids.empty()) {
+                    if (enable_ha_) {
+                        if (enable_oplog_) {
+                            // The erase runs from the durable-finalize
+                            // callback.
+                            auto persist_result =
+                                PersistStaleHandleCleanupForHA(
+                                    "ClearStaleHandles", tenant_it->first,
+                                    it->first, it->second, cleanup_plan);
+                            if (!persist_result && !first_persist_error) {
+                                first_persist_error = persist_result.error();
+                            }
+                            continue;
+                        }
+                    }
+                    if (CleanupStaleHandles(it->first, tenant_it->first,
+                                            tenant_state, it->second, is_stale,
+                                            &shard)) {
+                        EraseMetadata(tenant_state, it, tenant_it->first,
+                                      QuotaEraseMode::kFull, &shard);
+                        erased_in_shard = true;
+                    } else {
+                        continue;
+                    }
                 } else if (!it->second.IsValid()) {
                     if (enable_ha_) {
                         if (enable_oplog_) {
@@ -2118,30 +2817,229 @@ void MasterService::ClearInvalidHandles(
                                     });
                             if (!persist_result) {
                                 LOG(WARNING)
-                                    << "ClearInvalidHandles(last replica)"
+                                    << "ClearStaleHandles(last replica)"
                                     << ": REMOVE persist failed for key="
                                     << it->first << ", err="
                                     << static_cast<int>(persist_result.error());
-                                ++it;
-                                continue;
+                                if (!first_persist_error) {
+                                    first_persist_error =
+                                        persist_result.error();
+                                }
                             }
-                            ++it;
                             continue;
                         }
+                        continue;
                     }
-                    it = EraseMetadata(tenant_state, it, tenant_it->first,
-                                       QuotaEraseMode::kFull, &shard);
+                    EraseMetadata(tenant_state, it, tenant_it->first,
+                                  QuotaEraseMode::kFull, &shard);
+                    erased_in_shard = true;
                 } else {
+                    continue;
+                }
+                if (tenant_it->second.Empty()) {
+                    shard->tenants.erase(tenant_it);
+                }
+            }
+        }
+
+        if (!empty_tenants.empty()) {
+            MetadataShardAccessorRW shard(this, i);
+            for (const auto& tenant_id : empty_tenants) {
+                auto tenant_it = shard->tenants.find(tenant_id);
+                if (tenant_it != shard->tenants.end() &&
+                    tenant_it->second.Empty()) {
+                    shard->tenants.erase(tenant_it);
+                }
+            }
+        }
+
+        if (erased_in_shard) {
+            MetadataShardAccessorRW shard(this, i);
+            for (auto& tenant : shard->tenants) {
+                ShrinkBucketsIfSparse(tenant.second.metadata);
+            }
+        }
+    }
+    if (first_persist_error) {
+        return tl::make_unexpected(*first_persist_error);
+    }
+    return {};
+}
+
+bool MasterService::ProcessClientOffboardingJob(ClientOffboardingJob& job) {
+    bool quota_recompute_needed = false;
+    {
+        std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+
+        if (!job.pending_prepare_segments.empty()) {
+            ScopedSegmentAccess segment_access =
+                segment_manager_.getSegmentAccess();
+            for (auto it = job.pending_prepare_segments.begin();
+                 it != job.pending_prepare_segments.end();) {
+                SegmentStatus status = SegmentStatus::UNDEFINED;
+                const auto status_err =
+                    segment_access.GetSegmentStatusById(it->segment_id, status);
+                if (status_err == ErrorCode::SEGMENT_NOT_FOUND) {
+                    it = job.pending_prepare_segments.erase(it);
+                    continue;
+                }
+                if (status_err == ErrorCode::OK &&
+                    status == SegmentStatus::UNMOUNTING) {
                     ++it;
+                    continue;
+                }
+
+                size_t metrics_dec_capacity = 0;
+                const auto err = segment_access.PrepareUnmountSegment(
+                    it->segment_id, metrics_dec_capacity);
+                if (err == ErrorCode::OK) {
+                    job.prepared_segments.push_back(
+                        {.segment_id = it->segment_id,
+                         .segment_name = it->segment_name,
+                         .transport_endpoint = it->transport_endpoint,
+                         .metrics_dec_capacity = metrics_dec_capacity});
+                    it = job.pending_prepare_segments.erase(it);
+                    continue;
+                }
+                if (err == ErrorCode::SEGMENT_NOT_FOUND) {
+                    it = job.pending_prepare_segments.erase(it);
+                    continue;
                 }
+                LOG(ERROR) << "client_id=" << job.client_id
+                           << ", segment_name=" << it->segment_name
+                           << ", action=prepare_client_offboarding"
+                           << ", error=" << toString(err);
+                ++it;
             }
-            if (tenant_state.Empty()) {
-                tenant_it = shard->tenants.erase(tenant_it);
-            } else {
-                ++tenant_it;
+            if (!job.pending_prepare_segments.empty()) {
+                return false;
+            }
+        }
+
+        if (!job.metadata_cleanup_accepted) {
+            const auto cleanup_result =
+                ClearStaleHandles([&job](const Replica& replica) {
+                    if (!replica.is_completed()) {
+                        return false;
+                    }
+                    if (replica.is_local_disk_replica()) {
+                        return replica.get_local_disk_client_id() ==
+                               job.client_id;
+                    }
+                    return replica.is_memory_replica() &&
+                           replica.isAffiliatedWith(job.liveness);
+                });
+            if (!cleanup_result) {
+                LOG(ERROR) << "client_id=" << job.client_id
+                           << ", action=queue_client_offboarding_metadata"
+                           << ", error=" << toString(cleanup_result.error());
+                return false;
+            }
+            bool unfinished_affiliated_replica = false;
+            for (size_t shard_index = 0;
+                 !unfinished_affiliated_replica && shard_index < kNumShards;
+                 ++shard_index) {
+                MetadataShardAccessorRO shard(this, shard_index);
+                for (const auto& [tenant_id, tenant_state] : shard->tenants) {
+                    (void)tenant_id;
+                    for (const auto& [key, metadata] : tenant_state.metadata) {
+                        (void)key;
+                        if (metadata.HasReplica([&job](const Replica& replica) {
+                                return replica.is_processing() &&
+                                       replica.isAffiliatedWith(job.liveness);
+                            })) {
+                            unfinished_affiliated_replica = true;
+                            break;
+                        }
+                    }
+                    if (unfinished_affiliated_replica) {
+                        break;
+                    }
+                }
+            }
+            if (unfinished_affiliated_replica) {
+                LOG(ERROR)
+                    << "client_id=" << job.client_id
+                    << ", action=wait_client_offboarding_processing_replica";
+                return false;
+            }
+            job.metadata_cleanup_accepted = true;
+        }
+
+        if (!job.local_ssd_unregistered) {
+            auto capacity = local_ssd_manager_.UnregisterClient(job.client_id);
+            if (capacity && *capacity > 0) {
+                MasterMetricManager::instance().dec_total_file_capacity(
+                    *capacity);
+                quota_recompute_needed = true;
+            }
+            job.local_ssd_unregistered = true;
+        }
+
+        for (auto it = job.prepared_segments.begin();
+             it != job.prepared_segments.end();) {
+            ScopedSegmentAccess segment_access =
+                segment_manager_.getSegmentAccess();
+            const auto commit_result = segment_access.CommitUnmountSegment(
+                it->segment_id, job.client_id, it->metrics_dec_capacity,
+                /*retain_name_registration=*/true);
+            if (commit_result != ErrorCode::OK &&
+                commit_result != ErrorCode::SEGMENT_NOT_FOUND) {
+                LOG(ERROR) << "client_id=" << job.client_id
+                           << ", segment_name=" << it->segment_name
+                           << ", action=commit_client_offboarding"
+                           << ", error=" << toString(commit_result);
+                ++it;
+                continue;
             }
+
+            if (enable_oplog_ && ordered_oplog_writer_ &&
+                !it->transport_endpoint.empty()) {
+                SegmentUnmountOp op{it->transport_endpoint};
+                auto bytes = struct_pack::serialize(op);
+                auto persist_result = AppendOpLogVisibleBeforeDurable(
+                    OpType::SEGMENT_UNMOUNT, TenantId::Default().value(),
+                    it->transport_endpoint,
+                    std::string(bytes.begin(), bytes.end()));
+                if (!persist_result) {
+                    LOG(ERROR)
+                        << "client_id=" << job.client_id
+                        << ", segment_name=" << it->segment_name
+                        << ", action=queue_client_offboarding_unmount"
+                        << ", error=" << toString(persist_result.error());
+                    ++it;
+                    continue;
+                }
+            }
+
+            cleanupHttpMetadata(it->segment_name);
+            segment_access.ReleaseUnmountedSegmentName(it->segment_id,
+                                                       it->segment_name);
+            LOG(INFO) << "client_id=" << job.client_id
+                      << ", segment_name=" << it->segment_name
+                      << ", action=unmount_offline_mem_segment";
+            quota_recompute_needed = true;
+            it = job.prepared_segments.erase(it);
         }
     }
+
+    if (quota_recompute_needed) {
+        RecomputeTenantEffectiveQuotas();
+    }
+    if (!job.prepared_segments.empty()) {
+        return false;
+    }
+
+    std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+    const auto current = client_liveness_records_.find(job.client_id);
+    if (current != client_liveness_records_.end() &&
+        current->second == job.liveness) {
+        const auto state = current->second->state();
+        client_liveness_records_.erase(current);
+        MasterMetricManager::instance().on_client_liveness_record_removed(
+            state);
+    }
+    return true;
 }
 
 void MasterService::TaskCleanupThreadFunc() {
@@ -2160,9 +3058,13 @@ void MasterService::TaskCleanupThreadFunc() {
         }
 
         std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-        auto write_access = task_manager_.get_write_access();
-        write_access.prune_expired_tasks();
-        write_access.prune_finished_tasks();
+        {
+            auto write_access = task_manager_.get_write_access();
+            write_access.prune_expired_tasks();
+            write_access.prune_finished_tasks();
+        }
+        CleanupExpiredSoftPins(std::chrono::system_clock::now());
+        CleanupExpiredDynamicReplicationState();
     }
     LOG(INFO) << "Task cleanup thread stopped";
 }
@@ -2172,7 +3074,10 @@ auto MasterService::UnmountSegment(const UUID& segment_id,
     -> tl::expected<void, ErrorCode> {
     size_t metrics_dec_capacity = 0;  // to update the metrics
 
+    std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    auto retaining_clients = GetRetainingClientIdsLocked();
+    client_lock.unlock();
     // 1. Prepare to unmount the segment by deleting its allocator
     {
         ScopedSegmentAccess segment_access =
@@ -2186,11 +3091,16 @@ auto MasterService::UnmountSegment(const UUID& segment_id,
         if (err != ErrorCode::OK) {
             return tl::make_unexpected(err);
         }
-    }  // Release the segment mutex before long-running step 2 and avoid
-       // deadlocks
+    }
 
-    // 2. Remove the metadata of the related objects
-    ClearInvalidHandles();
+    // Keep HA, snapshot, and CXL behavior unchanged. Regular memory segments
+    // become unreadable as soon as PrepareUnmountSegment releases their
+    // allocator; only the physical metadata sweep is deferred.
+    if (enable_async_segment_cleanup_) {
+        replica_cleanup_worker_.Schedule();
+    } else {
+        ClearInvalidHandles(retaining_clients);
+    }
 
     // Cache endpoint before commit removes segment from registry.
     std::string segment_name;
@@ -2270,6 +3180,11 @@ auto MasterService::UnmountNoFSegment(const UUID& segment_id,
 #else
     size_t metrics_dec_capacity = 0;  // to update the metrics
 
+    std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    auto retaining_clients = GetRetainingClientIdsLocked();
+    client_lock.unlock();
+
     // 1. Prepare to unmount the segment by deleting its allocator
     {
         ScopedNoFSegmentAccess segment_access =
@@ -2287,7 +3202,7 @@ auto MasterService::UnmountNoFSegment(const UUID& segment_id,
        // deadlocks
 
     // 2. Remove the metadata of the related objects
-    ClearInvalidHandles();
+    ClearInvalidHandles(retaining_clients);
 
     // 3. Commit the unmount operation
     ScopedNoFSegmentAccess segment_access =
@@ -2307,6 +3222,17 @@ auto MasterService::UnmountNoFSegment(const UUID& segment_id,
 
 auto MasterService::ExistKey(const std::string& key, const TenantId& tenant_id)
     -> tl::expected<bool, ErrorCode> {
+    return ExistKeyImpl(key, tenant_id, /*grant_lease=*/true);
+}
+
+auto MasterService::ProbeKey(const std::string& key, const TenantId& tenant_id)
+    -> tl::expected<bool, ErrorCode> {
+    return ExistKeyImpl(key, tenant_id, /*grant_lease=*/false);
+}
+
+auto MasterService::ExistKeyImpl(const std::string& key,
+                                 const TenantId& tenant_id, bool grant_lease)
+    -> tl::expected<bool, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRO accessor(this,
                                 MakeObjectIdentityForRequest(key, tenant_id));
@@ -2316,22 +3242,33 @@ auto MasterService::ExistKey(const std::string& key, const TenantId& tenant_id)
     }
 
     const auto& metadata = accessor.Get();
-    if (!metadata.HasReplica(&Replica::fn_is_completed)) {
+    if (!HasReadableReplica(metadata)) {
         return false;
     }
 
-    // Grant a lease to the object as it may be further used by the client.
-    auto* ts = accessor.GetTenantState();
-    if (ts) {
-        GrantLeaseForGroup(*ts, key, metadata);
-    } else {
-        metadata.GrantLease(default_kv_lease_ttl_, default_kv_soft_pin_ttl_);
+    if (grant_lease) {
+        // Grant a lease to the object as it may be further used by the client.
+        // Read path is group-agnostic: only the object's own lease is
+        // refreshed.
+        metadata.GrantReadLease(
+            std::chrono::milliseconds(default_kv_lease_ttl_));
     }
     return true;
 }
 
 std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchExistKey(
     const std::vector<std::string>& keys, const TenantId& tenant_id) {
+    return BatchExistKeyImpl(keys, tenant_id, /*grant_lease=*/true);
+}
+
+std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchProbeKey(
+    const std::vector<std::string>& keys, const TenantId& tenant_id) {
+    return BatchExistKeyImpl(keys, tenant_id, /*grant_lease=*/false);
+}
+
+std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchExistKeyImpl(
+    const std::vector<std::string>& keys, const TenantId& tenant_id,
+    bool grant_lease) {
     const TenantId& normalized_tenant = ResolveRequestTenantId(tenant_id);
     std::vector<tl::expected<bool, ErrorCode>> results(keys.size());
     if (keys.empty()) {
@@ -2339,18 +3276,9 @@ std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchExistKey(
     }
 
     std::vector<std::vector<size_t>> indices_by_shard(kNumShards);
-    {
-        std::shared_lock<std::shared_mutex> group_routing_lock(
-            group_routing_mutex_);
-        for (size_t i = 0; i < keys.size(); ++i) {
-            auto route_it = object_group_ids_.find(
-                normalized_tenant.MakeScopedKey(keys[i]));
-            const size_t shard_idx =
-                route_it == object_group_ids_.end()
-                    ? getShardIndex(normalized_tenant, keys[i])
-                    : getShardIndex(route_it->second);
-            indices_by_shard[shard_idx].push_back(i);
-        }
+    for (size_t i = 0; i < keys.size(); ++i) {
+        const size_t shard_idx = getShardIndex(normalized_tenant, keys[i]);
+        indices_by_shard[shard_idx].push_back(i);
     }
 
     const size_t start_shard = randomIndex(kNumShards);
@@ -2387,11 +3315,14 @@ std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchExistKey(
             }
 
             const auto& metadata = it->second;
-            if (!metadata.HasReplica(&Replica::fn_is_completed)) {
+            if (!HasReadableReplica(metadata)) {
                 results[i] = false;
                 continue;
             }
-            GrantLeaseForGroup(tenant_state, key, metadata);
+            if (grant_lease) {
+                metadata.GrantReadLease(
+                    std::chrono::milliseconds(default_kv_lease_ttl_));
+            }
             results[i] = true;
         }
     }
@@ -2401,6 +3332,7 @@ std::vector<tl::expected<bool, ErrorCode>> MasterService::BatchExistKey(
 auto MasterService::GetAllKeys(const TenantId& tenant_id)
     -> tl::expected<std::vector<std::string>, ErrorCode> {
     std::vector<std::string> all_keys;
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const TenantId& normalized_tenant = ResolveRequestTenantId(tenant_id);
     for (size_t i = 0; i < kNumShards; i++) {
         MetadataShardAccessorRO shard(this, i);
@@ -2409,6 +3341,9 @@ auto MasterService::GetAllKeys(const TenantId& tenant_id)
             continue;
         }
         for (const auto& item : tenant_it->second.metadata) {
+            if (!HasReadableReplica(item.second)) {
+                continue;
+            }
             all_keys.push_back(item.second.user_key.empty()
                                    ? item.first
                                    : item.second.user_key);
@@ -2518,41 +3453,60 @@ auto MasterService::QuerySegmentStatusById(const UUID& segment_id)
     return status;
 }
 
-void MasterService::RestoreFromStandbySnapshot(
+tl::expected<void, ErrorCode> MasterService::RestoreFromStandbySnapshot(
     const std::vector<StandbyObjectEntry>& objects,
     uint64_t initial_oplog_sequence_id,
     const std::vector<StandbySegmentInfo>& segments) {
-    // The ordered writer initializes its sequence from durable_prefix.
-    (void)initial_oplog_sequence_id;
+    return RestoreFromStandbyState(&objects, nullptr, initial_oplog_sequence_id,
+                                   segments, objects.size(), std::nullopt);
+}
 
-    // 2. Build allocator keepalive map for standby segments.
-    for (const auto& [segment, bytes] : standby_accounted_memory_bytes_) {
-        MasterMetricManager::instance().dec_allocated_mem_size(
-            segment, static_cast<int64_t>(bytes));
+tl::expected<void, ErrorCode> MasterService::RestoreFromBatchOpLogPromotion(
+    BatchOpLogPromotionHandoff handoff, size_t chunk_object_count) {
+    if (!handoff.metadata_store || chunk_object_count == 0 ||
+        ((handoff.applied_cursor.batch_id == 0) !=
+         (handoff.applied_cursor.last_seq == 0))) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    standby_accounted_memory_bytes_.clear();
-    standby_memory_segments_.clear();
-    standby_allocator_keepalive_.clear();
-    invalid_replica_endpoints_.clear();
-    for (const auto& seg : segments) {
-        if (seg.is_memory_segment) {
-            standby_memory_segments_.push_back(seg);
-            auto allocator = std::make_shared<DummyBufferAllocator>(
-                seg.segment_name, seg.transport_endpoint);
-            standby_allocator_keepalive_[seg.transport_endpoint] = allocator;
-            if (seg.segment_name != seg.transport_endpoint) {
-                standby_allocator_keepalive_[seg.segment_name] = allocator;
-            }
-        }
-        if (!segment_manager_.HasSegmentByEndpoint(seg.transport_endpoint)) {
-            invalid_replica_endpoints_.insert(seg.transport_endpoint);
-            if (seg.segment_name != seg.transport_endpoint) {
-                invalid_replica_endpoints_.insert(seg.segment_name);
-            }
-        }
+    return RestoreFromStandbyState(nullptr, std::move(handoff.metadata_store),
+                                   handoff.applied_cursor.last_seq,
+                                   handoff.segments, chunk_object_count,
+                                   handoff.max_replica_id);
+}
+
+tl::expected<void, ErrorCode> MasterService::RestoreFromStandbyState(
+    const std::vector<StandbyObjectEntry>* legacy_objects,
+    std::unique_ptr<StandbyMetadataStore> metadata_store,
+    uint64_t initial_oplog_sequence_id,
+    const std::vector<StandbySegmentInfo>& segments, size_t chunk_object_count,
+    std::optional<ReplicaID> expected_max_replica_id) {
+    if (enable_dfs_) {
+        LOG(ERROR) << "RestoreFromStandbySnapshot: DFS allocator state "
+                      "restoration is not supported";
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    if ((legacy_objects == nullptr) == (metadata_store == nullptr) ||
+        (metadata_store && chunk_object_count == 0)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    // The ordered writer initializes its sequence from durable_prefix.
+    std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+    std::unique_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+    std::unordered_map<UUID, std::shared_ptr<ClientLivenessRecord>,
+                       boost::hash<UUID>>
+        new_known_owner_records;
+    const auto record_for_known_owner = [&](const UUID& owner) {
+        const auto existing = client_liveness_records_.find(owner);
+        if (existing != client_liveness_records_.end()) {
+            return existing->second;
+        }
+        auto [record, inserted] = new_known_owner_records.try_emplace(
+            owner, std::make_shared<ClientLivenessRecord>(
+                       ClientLivenessRecord::Clock::now()));
+        (void)inserted;
+        return record->second;
+    };
 
-    // 3. Restore object metadata.
     const auto resolve_standby_object = [](const StandbyObjectEntry& entry) {
         auto [scoped_tenant_id, user_key] = TenantId::ParseScopedKey(entry.key);
         TenantId tenant_id(entry.tenant_id);
@@ -2562,100 +3516,384 @@ void MasterService::RestoreFromStandbySnapshot(
         return std::make_pair(std::move(tenant_id), std::move(user_key));
     };
 
-    std::unordered_map<size_t, std::vector<const StandbyObjectEntry*>>
-        objects_by_shard;
-    for (const auto& entry : objects) {
-        auto [tenant_id, user_key] = resolve_standby_object(entry);
-        if (!tenant_id.IsValid()) {
-            LOG(WARNING) << "RestoreFromStandbySnapshot: invalid tenant_id="
-                         << entry.tenant_id << ", key=" << entry.key
-                         << ", skipping";
+    ReplicaID max_live_id = 0;
+    if (metadata_store) {
+        if (!expected_max_replica_id ||
+            !metadata_store->ValidateReplicaIds(max_live_id) ||
+            max_live_id != *expected_max_replica_id) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    } else {
+        for (const auto& entry : *legacy_objects) {
+            auto [tenant_id, user_key] = resolve_standby_object(entry);
+            std::unordered_set<ReplicaID> object_replica_ids;
+            for (const auto& desc : entry.metadata.replicas) {
+                if (desc.id == 0 ||
+                    desc.id == std::numeric_limits<ReplicaID>::max() ||
+                    !object_replica_ids.insert(desc.id).second) {
+                    LOG(ERROR)
+                        << "RestoreFromStandbySnapshot: invalid or duplicate "
+                        << "replica id=" << desc.id
+                        << ", tenant=" << tenant_id.value()
+                        << ", key=" << user_key;
+                    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                }
+                max_live_id = std::max(max_live_id, desc.id);
+            }
+        }
+    }
+
+    std::vector<StandbySegmentInfo> restored_memory_segments;
+    std::unordered_map<std::string, const StandbySegmentInfo*>
+        memory_segments_by_alias;
+    std::unordered_map<std::string, std::shared_ptr<BufferAllocatorBase>>
+        restored_allocators;
+    std::unordered_set<std::string> restored_invalid_endpoints;
+    for (const auto& seg : segments) {
+        if (!seg.is_memory_segment) {
             continue;
         }
-        const auto shard_idx = entry.metadata.group_id.empty()
-                                   ? getShardIndex(tenant_id, user_key)
-                                   : getShardIndex(entry.metadata.group_id);
-        objects_by_shard[shard_idx].push_back(&entry);
+        if (seg.segment_name.empty() || seg.transport_endpoint.empty() ||
+            seg.capacity == 0) {
+            LOG(ERROR) << "RestoreFromStandbySnapshot: invalid memory segment "
+                       << "name=" << seg.segment_name
+                       << ", endpoint=" << seg.transport_endpoint
+                       << ", capacity=" << seg.capacity;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        const auto add_alias = [&](const std::string& alias) {
+            return memory_segments_by_alias.emplace(alias, &seg).second;
+        };
+        if (!add_alias(seg.transport_endpoint) ||
+            (seg.segment_name != seg.transport_endpoint &&
+             !add_alias(seg.segment_name))) {
+            LOG(ERROR)
+                << "RestoreFromStandbySnapshot: ambiguous memory segment "
+                << "name=" << seg.segment_name
+                << ", endpoint=" << seg.transport_endpoint;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+
+        restored_memory_segments.push_back(seg);
+        auto allocator = std::make_shared<DummyBufferAllocator>(
+            seg.segment_name, seg.transport_endpoint);
+        restored_allocators[seg.transport_endpoint] = allocator;
+        if (seg.segment_name != seg.transport_endpoint) {
+            restored_allocators[seg.segment_name] = allocator;
+        }
+        if (!segment_manager_.HasSegmentByEndpoint(seg.transport_endpoint)) {
+            restored_invalid_endpoints.insert(seg.transport_endpoint);
+            if (seg.segment_name != seg.transport_endpoint) {
+                restored_invalid_endpoints.insert(seg.segment_name);
+            }
+        }
     }
 
-    for (const auto& [shard_idx, shard_objects] : objects_by_shard) {
-        MetadataShardAccessorRW shard(this, shard_idx);
-        auto now = std::chrono::system_clock::now();
-        for (const auto* entry_ptr : shard_objects) {
-            const auto& entry = *entry_ptr;
+    struct PreparedObject {
+        const StandbyObjectEntry* entry;
+        TenantId tenant_id;
+        std::string user_key;
+        std::vector<Replica> replicas;
+    };
+    const bool bounded_restore = metadata_store != nullptr;
+    // Batch restore spans chunks, so it needs an ordered cross-chunk index;
+    // legacy restore keeps its contiguous vector-and-sort validation path.
+    std::unordered_map<const StandbySegmentInfo*,
+                       std::vector<std::pair<uintptr_t, uint64_t>>>
+        legacy_memory_ranges;
+    std::unordered_map<const StandbySegmentInfo*, std::map<uintptr_t, uint64_t>>
+        bounded_memory_ranges;
+    std::unordered_map<std::string, uint64_t> restored_accounted_memory_bytes;
+    size_t restored_object_count = 0;
+
+    const auto restore_chunk =
+        [&](const std::vector<StandbyObjectEntry>& objects)
+        -> tl::expected<void, ErrorCode> {
+        std::unordered_map<size_t, std::vector<PreparedObject>>
+            objects_by_shard;
+        std::unordered_set<std::string> chunk_object_ids;
+        for (const auto& entry : objects) {
             auto [tenant_id, user_key] = resolve_standby_object(entry);
+            if (!tenant_id.IsValid()) {
+                LOG(ERROR) << "RestoreFromStandbySnapshot: invalid tenant_id="
+                           << entry.tenant_id << ", key=" << entry.key;
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            if (!chunk_object_ids.insert(tenant_id.MakeScopedKey(user_key))
+                     .second) {
+                LOG(ERROR)
+                    << "RestoreFromStandbySnapshot: duplicate object, tenant="
+                    << tenant_id.value() << ", key=" << user_key;
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            const size_t shard_idx = getShardIndex(tenant_id, user_key);
+            {
+                MetadataShardAccessorRO existing_shard(this, shard_idx);
+                auto existing_tenant = existing_shard->tenants.find(tenant_id);
+                if (existing_tenant != existing_shard->tenants.end() &&
+                    existing_tenant->second.metadata.contains(user_key)) {
+                    LOG(ERROR)
+                        << "RestoreFromStandbySnapshot: object already exists, "
+                        << "tenant=" << tenant_id.value()
+                        << ", key=" << user_key;
+                    return tl::make_unexpected(
+                        ErrorCode::OBJECT_ALREADY_EXISTS);
+                }
+            }
             const auto& standby_meta = entry.metadata;
             std::vector<Replica> replicas;
             replicas.reserve(standby_meta.replicas.size());
 
             for (const auto& desc : standby_meta.replicas) {
                 if (desc.is_memory_replica()) {
-                    const auto& mem_desc = desc.get_memory_descriptor();
-                    const std::string& endpoint =
-                        mem_desc.buffer_descriptor.transport_endpoint_;
-                    auto it = standby_allocator_keepalive_.find(endpoint);
-                    if (it != standby_allocator_keepalive_.end()) {
-                        auto alloc = it->second;
-                        replicas.emplace_back(
-                            std::make_unique<AllocatedBuffer>(
-                                alloc, mem_desc.buffer_descriptor),
-                            desc.status);
-                        MasterMetricManager::instance().inc_allocated_mem_size(
-                            alloc->getSegmentName(),
-                            static_cast<int64_t>(
-                                mem_desc.buffer_descriptor.size_));
-                        standby_accounted_memory_bytes_
-                            [alloc->getSegmentName()] +=
-                            mem_desc.buffer_descriptor.size_;
-                    } else {
-                        invalid_replica_endpoints_.insert(endpoint);
+                    const auto& buffer =
+                        desc.get_memory_descriptor().buffer_descriptor;
+                    auto segment_it = memory_segments_by_alias.find(
+                        buffer.transport_endpoint_);
+                    if (segment_it == memory_segments_by_alias.end()) {
+                        LOG(ERROR)
+                            << "RestoreFromStandbySnapshot: unknown memory "
+                            << "endpoint=" << buffer.transport_endpoint_
+                            << ", tenant=" << tenant_id.value()
+                            << ", key=" << user_key;
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
+                    if (buffer.size_ != standby_meta.size ||
+                        buffer.size_ == 0 ||
+                        buffer.buffer_address_ >
+                            std::numeric_limits<uintptr_t>::max() -
+                                buffer.size_) {
+                        LOG(ERROR)
+                            << "RestoreFromStandbySnapshot: invalid memory "
+                            << "descriptor, tenant=" << tenant_id.value()
+                            << ", key=" << user_key;
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
+
+                    const auto* segment = segment_it->second;
+                    if (desc.status != ReplicaStatus::REMOVED &&
+                        desc.status != ReplicaStatus::FAILED) {
+                        auto& bytes =
+                            restored_accounted_memory_bytes[segment
+                                                                ->segment_name];
+                        if (bytes > segment->capacity ||
+                            buffer.size_ > segment->capacity - bytes) {
+                            LOG(ERROR)
+                                << "RestoreFromStandbySnapshot: memory "
+                                   "descriptors exceed segment capacity, "
+                                   "segment="
+                                << segment->segment_name;
+                            return tl::make_unexpected(
+                                ErrorCode::INVALID_PARAMS);
+                        }
+                        if (bounded_restore) {
+                            auto& ranges = bounded_memory_ranges[segment];
+                            auto next =
+                                ranges.lower_bound(buffer.buffer_address_);
+                            const uintptr_t end =
+                                buffer.buffer_address_ + buffer.size_;
+                            if ((next != ranges.end() && end > next->first) ||
+                                (next != ranges.begin() &&
+                                 std::prev(next)->first +
+                                         std::prev(next)->second >
+                                     buffer.buffer_address_)) {
+                                LOG(ERROR) << "RestoreFromStandbySnapshot: "
+                                              "overlapping "
+                                              "memory descriptors";
+                                return tl::make_unexpected(
+                                    ErrorCode::INVALID_PARAMS);
+                            }
+                            ranges.emplace(buffer.buffer_address_,
+                                           buffer.size_);
+                        } else {
+                            legacy_memory_ranges[segment].emplace_back(
+                                buffer.buffer_address_, buffer.size_);
+                        }
+                        bytes += buffer.size_;
                     }
+
+                    auto alloc =
+                        restored_allocators.at(buffer.transport_endpoint_);
+                    auto restored_buffer =
+                        std::make_unique<AllocatedBuffer>(alloc, buffer);
+                    replicas.push_back(Replica(
+                        desc.id, std::move(restored_buffer), desc.status));
                 } else if (desc.is_nof_replica()) {
-                    const auto& nof_desc = desc.get_nof_descriptor();
-                    const std::string& endpoint =
-                        nof_desc.buffer_descriptor.transport_endpoint_;
-                    auto& alloc = standby_allocator_keepalive_[endpoint];
+                    const auto& buffer =
+                        desc.get_nof_descriptor().buffer_descriptor;
+                    if (buffer.size_ != standby_meta.size ||
+                        buffer.size_ == 0) {
+                        LOG(ERROR) << "RestoreFromStandbySnapshot: invalid NoF "
+                                   << "descriptor, tenant=" << tenant_id.value()
+                                   << ", key=" << user_key;
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
+                    auto& alloc =
+                        restored_allocators[buffer.transport_endpoint_];
                     if (!alloc) {
                         alloc = std::make_shared<DummyBufferAllocator>(
-                            endpoint, endpoint);
+                            buffer.transport_endpoint_,
+                            buffer.transport_endpoint_);
                     }
-                    replicas.emplace_back(
-                        std::make_unique<AllocatedBuffer>(
-                            alloc, nof_desc.buffer_descriptor),
-                        desc.status, ReplicaType::NOF_SSD);
+                    auto restored_buffer =
+                        std::make_unique<AllocatedBuffer>(alloc, buffer);
+                    replicas.push_back(
+                        Replica(desc.id, std::move(restored_buffer),
+                                desc.status, ReplicaType::NOF_SSD));
                 } else if (desc.is_disk_replica()) {
                     const auto& disk_desc = desc.get_disk_descriptor();
-                    replicas.emplace_back(disk_desc.file_path,
-                                          disk_desc.object_size, desc.status);
+                    if (disk_desc.object_size != standby_meta.size) {
+                        LOG(ERROR)
+                            << "RestoreFromStandbySnapshot: invalid disk "
+                            << "descriptor, tenant=" << tenant_id.value()
+                            << ", key=" << user_key;
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
+                    replicas.push_back(Replica(desc.id, disk_desc.file_path,
+                                               disk_desc.object_size,
+                                               desc.status));
                 } else if (desc.is_local_disk_replica()) {
                     const auto& local_disk_desc =
                         desc.get_local_disk_descriptor();
-                    replicas.emplace_back(
-                        local_disk_desc.client_id, local_disk_desc.object_size,
-                        local_disk_desc.transport_endpoint, desc.status);
+                    if (local_disk_desc.object_size != standby_meta.size) {
+                        LOG(ERROR)
+                            << "RestoreFromStandbySnapshot: invalid local disk "
+                            << "descriptor, tenant=" << tenant_id.value()
+                            << ", key=" << user_key;
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
+                    replicas.push_back(Replica(
+                        desc.id, local_disk_desc.client_id,
+                        local_disk_desc.object_size,
+                        local_disk_desc.transport_endpoint, desc.status,
+                        record_for_known_owner(local_disk_desc.client_id)));
+                } else {
+                    LOG(ERROR)
+                        << "RestoreFromStandbySnapshot: unsupported replica "
+                        << "descriptor, tenant=" << tenant_id.value()
+                        << ", key=" << user_key;
+                    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                }
+            }
+            objects_by_shard[shard_idx].push_back({&entry, std::move(tenant_id),
+                                                   std::move(user_key),
+                                                   std::move(replicas)});
+        }
+
+        for (const auto& [shard_idx, shard_objects] : objects_by_shard) {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            for (const auto& object : shard_objects) {
+                auto tenant = shard->tenants.find(object.tenant_id);
+                if (tenant != shard->tenants.end() &&
+                    tenant->second.metadata.contains(object.user_key)) {
+                    return tl::make_unexpected(
+                        ErrorCode::OBJECT_ALREADY_EXISTS);
+                }
+            }
+        }
+
+        if (!bounded_restore) {
+            for (auto& [segment, ranges] : legacy_memory_ranges) {
+                (void)segment;
+                std::sort(ranges.begin(), ranges.end());
+                for (size_t i = 1; i < ranges.size(); ++i) {
+                    if (ranges[i].first <
+                        ranges[i - 1].first + ranges[i - 1].second) {
+                        LOG(ERROR)
+                            << "RestoreFromStandbySnapshot: overlapping memory "
+                               "descriptors";
+                        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                    }
                 }
             }
+        }
+
+        const auto now = std::chrono::system_clock::now();
+        for (auto& [shard_idx, shard_objects] : objects_by_shard) {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            for (auto& object : shard_objects) {
+                const auto& standby_meta = object.entry->metadata;
+                auto& tenant_state =
+                    GetOrCreateTenantState(shard.get(), object.tenant_id);
+                auto [it, inserted] = tenant_state.metadata.emplace(
+                    std::piecewise_construct,
+                    std::forward_as_tuple(object.user_key),
+                    std::forward_as_tuple(
+                        standby_meta.client_id, now, standby_meta.size,
+                        std::move(object.replicas), std::nullopt,
+                        standby_meta.hard_pinned.value_or(false),
+                        standby_meta.data_type, standby_meta.group_id,
+                        object.tenant_id, object.user_key));
+                (void)inserted;
+                if (!standby_meta.group_id.empty()) {
+                    it->second.lease_ =
+                        RegisterGroupMember(object.tenant_id, object.user_key,
+                                            standby_meta.group_id);
+                }
+                tenant_state.processing_keys.erase(object.user_key);
+            }
+        }
+        restored_object_count += objects.size();
+        return {};
+    };
 
-            auto& tenant_state = shard->tenants[tenant_id];
-            tenant_state.metadata.emplace(
-                std::piecewise_construct, std::forward_as_tuple(user_key),
-                std::forward_as_tuple(
-                    standby_meta.client_id, now, standby_meta.size,
-                    std::move(replicas), false, false, standby_meta.data_type,
-                    standby_meta.group_id, tenant_id, user_key));
-            if (!standby_meta.group_id.empty()) {
-                RegisterGroupMember(tenant_state, tenant_id, user_key,
-                                    standby_meta.group_id);
+    if (legacy_objects) {
+        auto restored = restore_chunk(*legacy_objects);
+        if (!restored) {
+            return restored;
+        }
+    } else {
+        std::vector<StandbyObjectEntry> objects;
+        for (;;) {
+            if (!metadata_store->DrainChunk(chunk_object_count, objects)) {
+                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+            if (objects.empty()) {
+                break;
+            }
+            auto restored = restore_chunk(objects);
+            if (!restored) {
+                return restored;
             }
-            tenant_state.processing_keys.erase(user_key);
         }
     }
 
-    // 4. Log the result.
-    LOG(INFO) << "Restored from standby: " << objects.size() << " objects, "
-              << segments.size()
+    for (const auto& [segment, bytes] : standby_accounted_memory_bytes_) {
+        MasterMetricManager::instance().dec_allocated_mem_size(
+            segment, static_cast<int64_t>(bytes));
+    }
+    for (const auto& [segment, bytes] : restored_accounted_memory_bytes) {
+        MasterMetricManager::instance().inc_allocated_mem_size(
+            segment, static_cast<int64_t>(bytes));
+    }
+    standby_accounted_memory_bytes_ =
+        std::move(restored_accounted_memory_bytes);
+    standby_memory_segments_ = std::move(restored_memory_segments);
+    standby_allocator_keepalive_ = std::move(restored_allocators);
+    invalid_replica_endpoints_ = std::move(restored_invalid_endpoints);
+    for (auto& [client_id, record] : new_known_owner_records) {
+        client_liveness_records_.emplace(client_id, std::move(record));
+        MasterMetricManager::instance().client_liveness_record_created();
+    }
+
+    if (max_live_id != 0) {
+        const ReplicaID desired_next_id = max_live_id + 1;
+        ReplicaID current_next_id = Replica::next_id_.load();
+        while (current_next_id < desired_next_id &&
+               !Replica::next_id_.compare_exchange_weak(current_next_id,
+                                                        desired_next_id)) {
+        }
+    }
+
+    if (enable_multi_tenants_) {
+        RebuildTenantQuotaUsageFromMetadata();
+    }
+
+    LOG(INFO) << "Restored from standby: " << restored_object_count
+              << " objects, " << segments.size()
               << " segments, initial_seq_id=" << initial_oplog_sequence_id
               << ", invalid_endpoints=" << invalid_replica_endpoints_.size();
+    return {};
 }
 
 auto MasterService::QueryIp(const UUID& client_id)
@@ -2746,6 +3984,7 @@ auto MasterService::BatchReplicaClear(
         }
 
         auto& metadata = accessor.Get();
+        const auto previous_kv_media = KvMediaSnapshot(metadata);
 
         // Security check: Ensure the requesting client owns the object.
         if (metadata.client_id != client_id) {
@@ -2889,8 +4128,7 @@ auto MasterService::BatchReplicaClear(
                             std::move(reservation.value()), OpType::PUT_END,
                             normalized_tenant.value(), key,
                             SerializeMetadataForOpLogFromReplicaDescriptors(
-                                metadata.client_id, metadata.size, remaining,
-                                metadata.group_id, metadata.data_type),
+                                metadata, remaining),
                             [this, removed_ids = std::move(removed_ids)](
                                 const OpLogEntry& durable_entry) {
                                 FinalizeRemovedReplicasAfterDurable(
@@ -2927,6 +4165,9 @@ auto MasterService::BatchReplicaClear(
             // decrements disk_object_count via OnDiskReplicaRemoved.
             if (!metadata.IsValid()) {
                 accessor.Erase();
+            } else {
+                SyncKvObjectState(key, metadata, normalized_tenant,
+                                  previous_kv_media);
             }
 
             cleared_keys.emplace_back(key);
@@ -2940,12 +4181,15 @@ auto MasterService::BatchReplicaClear(
     return cleared_keys;
 }
 
-bool MasterService::IsReplicaReadable(const Replica& replica) const {
+bool MasterService::TryGetReadableReplicaDescriptor(
+    const Replica& replica, Replica::Descriptor& descriptor) const {
     if (!replica.is_completed() || replica.has_invalid_mem_handle() ||
         replica.has_invalid_nof_handle()) {
         return false;
     }
-    const auto descriptor = replica.get_descriptor();
+    if (!replica.getDescriptorIfAvailable(descriptor)) {
+        return false;
+    }
     std::optional<std::string> endpoint;
     if (descriptor.is_memory_replica()) {
         endpoint = descriptor.get_memory_descriptor()
@@ -2956,7 +4200,40 @@ bool MasterService::IsReplicaReadable(const Replica& replica) const {
     } else if (descriptor.is_local_disk_replica()) {
         endpoint = descriptor.get_local_disk_descriptor().transport_endpoint;
     }
-    return !endpoint || !invalid_replica_endpoints_.contains(*endpoint);
+    if (endpoint && invalid_replica_endpoints_.contains(*endpoint)) {
+        return false;
+    }
+    return true;
+}
+
+std::vector<Replica::Descriptor> MasterService::GetReadableReplicaDescriptors(
+    const ObjectMetadata& metadata) const {
+    std::vector<Replica::Descriptor> descriptors;
+    descriptors.reserve(metadata.CountReplicas());
+    metadata.VisitReplicas(
+        [](const Replica&) { return true; },
+        [this, &descriptors](const Replica& replica) {
+            Replica::Descriptor descriptor;
+            if (TryGetReadableReplicaDescriptor(replica, descriptor)) {
+                descriptors.push_back(std::move(descriptor));
+            }
+        });
+    return descriptors;
+}
+
+bool MasterService::IsReplicaReadable(const Replica& replica) const {
+    Replica::Descriptor descriptor;
+    return TryGetReadableReplicaDescriptor(replica, descriptor);
+}
+
+bool MasterService::HasReadableReplica(const ObjectMetadata& metadata) const {
+    return metadata.HasReplica(
+        [this](const Replica& replica) { return IsReplicaReadable(replica); });
+}
+
+bool MasterService::IsEvictableMemoryReplica(const Replica& replica) const {
+    return replica.is_memory_replica() && IsReplicaReadable(replica) &&
+           replica.get_refcnt() == 0;
 }
 
 auto MasterService::GetReplicaListByRegex(const std::string& regex_pattern,
@@ -2985,14 +4262,7 @@ auto MasterService::GetReplicaListByRegex(const std::string& regex_pattern,
         }
         for (const auto& [key, metadata] : tenant_it->second.metadata) {
             if (std::regex_search(key, pattern)) {
-                std::vector<Replica::Descriptor> replica_list;
-                metadata.VisitReplicas(
-                    [this](const Replica& replica) {
-                        return IsReplicaReadable(replica);
-                    },
-                    [&replica_list](const Replica& replica) {
-                        replica_list.emplace_back(replica.get_descriptor());
-                    });
+                auto replica_list = GetReadableReplicaDescriptors(metadata);
 
                 if (replica_list.empty()) {
                     LOG(WARNING)
@@ -3002,7 +4272,8 @@ auto MasterService::GetReplicaListByRegex(const std::string& regex_pattern,
                 }
 
                 results.emplace(key, std::move(replica_list));
-                GrantLeaseForGroup(tenant_it->second, key, metadata);
+                metadata.GrantReadLease(
+                    std::chrono::milliseconds(default_kv_lease_ttl_));
             }
         }
     }
@@ -3018,6 +4289,7 @@ auto MasterService::GetReplicaList(const std::string& key,
 
     GetReplicaListResponse resp({}, default_kv_lease_ttl_);
     bool promotion_eligible = false;
+    bool dynamic_replication_observed = false;
     {
         MetadataAccessorRO accessor(this, object_id);
 
@@ -3029,14 +4301,15 @@ auto MasterService::GetReplicaList(const std::string& key,
         }
         const auto& metadata = accessor.Get();
 
-        std::vector<Replica::Descriptor> replica_list;
-        metadata.VisitReplicas(
-            [this](const Replica& replica) {
-                return IsReplicaReadable(replica);
-            },
-            [&replica_list](const Replica& replica) {
-                replica_list.emplace_back(replica.get_descriptor());
-            });
+        auto replica_list = GetReadableReplicaDescriptors(metadata);
+        if (dfs_allocator_) {
+            for (const auto& replica : replica_list) {
+                if (replica.is_dfs_replica()) {
+                    const auto& desc = replica.get_dfs_descriptor();
+                    dfs_allocator_->UpdateAccess(key, desc);
+                }
+            }
+        }
 
         if (replica_list.empty()) {
             if (metadata.AllReplicas([](const Replica& replica) {
@@ -3061,14 +4334,10 @@ auto MasterService::GetReplicaList(const std::string& key,
         }
         MasterMetricManager::instance().inc_valid_get_nums();
         // Grant a lease to the object so it will not be removed
-        // when the client is reading it.
-        auto* ts = accessor.GetTenantState();
-        if (ts) {
-            GrantLeaseForGroup(*ts, key, metadata);
-        } else {
-            metadata.GrantLease(default_kv_lease_ttl_,
-                                default_kv_soft_pin_ttl_);
-        }
+        // when the client is reading it. Read path is group-agnostic: only the
+        // object's own lease is refreshed.
+        metadata.GrantReadLease(
+            std::chrono::milliseconds(default_kv_lease_ttl_));
 
         // Promotion-on-hit eligibility: only when no MEMORY replica is
         // present but at least one LOCAL_DISK replica is. Decided here while
@@ -3076,11 +4345,27 @@ auto MasterService::GetReplicaList(const std::string& key,
         // release the accessor below to avoid lock-upgrade complexity.
         if (promotion_on_hit_) {
             const bool any_memory =
-                metadata.HasReplica(&Replica::fn_is_memory_replica);
+                std::any_of(replica_list.begin(), replica_list.end(),
+                            [](const auto& descriptor) {
+                                return descriptor.is_memory_replica();
+                            });
             const bool any_local_disk =
-                metadata.HasReplica(&Replica::fn_is_local_disk_replica);
+                std::any_of(replica_list.begin(), replica_list.end(),
+                            [](const auto& descriptor) {
+                                return descriptor.is_local_disk_replica();
+                            });
             promotion_eligible = !any_memory && any_local_disk;
         }
+        if (DynamicReplicationEnabled()) {
+            const size_t memory_replicas =
+                std::count_if(replica_list.begin(), replica_list.end(),
+                              [](const auto& descriptor) {
+                                  return descriptor.is_memory_replica();
+                              });
+            dynamic_replication_observed =
+                memory_replicas > 0 &&
+                memory_replicas < dynamic_replication_max_memory_replicas_;
+        }
 
         resp = GetReplicaListResponse(std::move(replica_list),
                                       default_kv_lease_ttl_,
@@ -3090,6 +4375,9 @@ auto MasterService::GetReplicaList(const std::string& key,
     if (promotion_eligible) {
         TryPushPromotionQueue(object_id);
     }
+    if (dynamic_replication_observed) {
+        MaybeQueueDynamicReplicaProposal(object_id);
+    }
     return resp;
 }
 
@@ -3108,11 +4396,7 @@ auto MasterService::GetReplicaListForAdmin(const std::string& key,
     }
     const auto& metadata = accessor.Get();
 
-    std::vector<Replica::Descriptor> replica_list;
-    metadata.VisitReplicas(
-        &Replica::fn_is_completed, [&replica_list](const Replica& replica) {
-            replica_list.emplace_back(replica.get_descriptor());
-        });
+    auto replica_list = GetReadableReplicaDescriptors(metadata);
 
     if (replica_list.empty()) {
         LOG(WARNING) << "key=" << key << ", error=replica_not_ready";
@@ -3142,20 +4426,12 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
     std::array<size_t, kNumShards> key_list_heads;
     key_list_heads.fill(kInvalidKeyIndex);
     std::vector<size_t> next_key_indexes(keys.size(), kInvalidKeyIndex);
-    {
-        std::shared_lock<std::shared_mutex> lock(group_routing_mutex_);
-        for (size_t i = keys.size(); i > 0; --i) {
-            const size_t original_idx = i - 1;
-            const auto scoped_key =
-                normalized_tenant.MakeScopedKey(keys[original_idx]);
-            const auto route_it = object_group_ids_.find(scoped_key);
-            const size_t shard_idx =
-                route_it == object_group_ids_.end()
-                    ? getShardIndex(normalized_tenant, keys[original_idx])
-                    : getShardIndex(route_it->second);
-            next_key_indexes[original_idx] = key_list_heads[shard_idx];
-            key_list_heads[shard_idx] = original_idx;
-        }
+    for (size_t i = keys.size(); i > 0; --i) {
+        const size_t original_idx = i - 1;
+        const size_t shard_idx =
+            getShardIndex(normalized_tenant, keys[original_idx]);
+        next_key_indexes[original_idx] = key_list_heads[shard_idx];
+        key_list_heads[shard_idx] = original_idx;
     }
 
     const size_t start_shard = randomIndex(kNumShards);
@@ -3167,6 +4443,8 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
         }
 
         std::vector<ObjectIdentity> promotion_candidates;
+        std::vector<ObjectIdentity> dynamic_replication_candidates;
+        std::unordered_set<std::string> dynamic_replication_seen;
         std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
         {
             MetadataShardAccessorRO shard(this, shard_idx);
@@ -3195,14 +4473,7 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
                 }
 
                 const auto& metadata = metadata_it->second;
-                std::vector<Replica::Descriptor> replica_list;
-                metadata.VisitReplicas(
-                    [this](const Replica& replica) {
-                        return IsReplicaReadable(replica);
-                    },
-                    [&replica_list](const Replica& replica) {
-                        replica_list.emplace_back(replica.get_descriptor());
-                    });
+                auto replica_list = GetReadableReplicaDescriptors(metadata);
 
                 if (replica_list.empty()) {
                     if (metadata.AllReplicas([](const Replica& replica) {
@@ -3230,18 +4501,45 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
                         static_cast<int64_t>(metadata.size));
                 }
                 MasterMetricManager::instance().inc_valid_get_nums();
-                GrantLeaseForGroup(tenant_state, key, metadata);
+                metadata.GrantReadLease(
+                    std::chrono::milliseconds(default_kv_lease_ttl_));
 
                 if (promotion_on_hit_) {
                     const bool any_memory =
-                        metadata.HasReplica(&Replica::fn_is_memory_replica);
-                    const bool any_local_disk =
-                        metadata.HasReplica(&Replica::fn_is_local_disk_replica);
+                        std::any_of(replica_list.begin(), replica_list.end(),
+                                    [](const auto& descriptor) {
+                                        return descriptor.is_memory_replica();
+                                    });
+                    const bool any_local_disk = std::any_of(
+                        replica_list.begin(), replica_list.end(),
+                        [](const auto& descriptor) {
+                            return descriptor.is_local_disk_replica();
+                        });
                     if (!any_memory && any_local_disk) {
                         promotion_candidates.push_back(
                             MakeObjectIdentity(key, normalized_tenant));
                     }
                 }
+                if (DynamicReplicationEnabled()) {
+                    const size_t memory_replicas =
+                        std::count_if(replica_list.begin(), replica_list.end(),
+                                      [](const auto& descriptor) {
+                                          return descriptor.is_memory_replica();
+                                      });
+                    if (memory_replicas > 0 &&
+                        memory_replicas <
+                            dynamic_replication_max_memory_replicas_) {
+                        auto object_id =
+                            MakeObjectIdentity(key, normalized_tenant);
+                        if (dynamic_replication_seen
+                                .insert(object_id.tenant_id.MakeScopedKey(
+                                    object_id.user_key))
+                                .second) {
+                            dynamic_replication_candidates.push_back(
+                                std::move(object_id));
+                        }
+                    }
+                }
 
                 results[original_idx] = GetReplicaListResponse(
                     std::move(replica_list), default_kv_lease_ttl_,
@@ -3252,6 +4550,9 @@ MasterService::BatchGetReplicaList(const std::vector<std::string>& keys,
         for (const auto& object_id : promotion_candidates) {
             TryPushPromotionQueue(object_id);
         }
+        for (const auto& object_id : dynamic_replication_candidates) {
+            MaybeQueueDynamicReplicaProposal(object_id);
+        }
     }
 
     return results;
@@ -3275,20 +4576,12 @@ MasterService::BatchGetReplicaListForAdmin(const std::vector<std::string>& keys,
     std::array<size_t, kNumShards> key_list_heads;
     key_list_heads.fill(kInvalidKeyIndex);
     std::vector<size_t> next_key_indexes(keys.size(), kInvalidKeyIndex);
-    {
-        std::shared_lock<std::shared_mutex> lock(group_routing_mutex_);
-        for (size_t i = keys.size(); i > 0; --i) {
-            const size_t original_idx = i - 1;
-            const auto scoped_key =
-                normalized_tenant.MakeScopedKey(keys[original_idx]);
-            const auto route_it = object_group_ids_.find(scoped_key);
-            const size_t shard_idx =
-                route_it == object_group_ids_.end()
-                    ? getShardIndex(normalized_tenant, keys[original_idx])
-                    : getShardIndex(route_it->second);
-            next_key_indexes[original_idx] = key_list_heads[shard_idx];
-            key_list_heads[shard_idx] = original_idx;
-        }
+    for (size_t i = keys.size(); i > 0; --i) {
+        const size_t original_idx = i - 1;
+        const size_t shard_idx =
+            getShardIndex(normalized_tenant, keys[original_idx]);
+        next_key_indexes[original_idx] = key_list_heads[shard_idx];
+        key_list_heads[shard_idx] = original_idx;
     }
 
     const size_t start_shard = randomIndex(kNumShards);
@@ -3324,12 +4617,7 @@ MasterService::BatchGetReplicaListForAdmin(const std::vector<std::string>& keys,
                 }
 
                 const auto& metadata = metadata_it->second;
-                std::vector<Replica::Descriptor> replica_list;
-                metadata.VisitReplicas(
-                    &Replica::fn_is_completed,
-                    [&replica_list](const Replica& replica) {
-                        replica_list.emplace_back(replica.get_descriptor());
-                    });
+                auto replica_list = GetReadableReplicaDescriptors(metadata);
 
                 if (replica_list.empty()) {
                     results[original_idx] =
@@ -3347,50 +4635,22 @@ MasterService::BatchGetReplicaListForAdmin(const std::vector<std::string>& keys,
     return results;
 }
 
-auto MasterService::AllocateAndInsertMetadata(
-    MetadataShardAccessorRW& shard, const UUID& client_id,
-    const std::string& key, uint64_t value_length,
-    const ReplicateConfig& config, const std::string& group_id,
-    const TenantId& tenant_id, const std::chrono::system_clock::time_point& now)
-    -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
-    auto& tenant_state = shard->tenants[tenant_id];
-    if (tenant_state.metadata.contains(key)) {
-        LOG(INFO) << "key=" << key << ", info=object_already_exists";
-        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
-    }
-    if (GetGroupRoute(tenant_id, key).has_value()) {
-        LOG(INFO) << "key=" << key << ", info=object_already_exists";
-        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
-    }
-
-    const uint64_t reserved_quota_charge =
-        RequestedMemoryQuotaCharge(value_length, config);
-    auto quota_result = ReserveTenantQuota(tenant_id, reserved_quota_charge);
-    if (!quota_result) {
-        return tl::make_unexpected(quota_result.error());
+auto MasterService::AllocateReplicas(const std::string& key,
+                                     uint64_t value_length,
+                                     const ReplicateConfig& config,
+                                     const std::string& writer_host_id,
+                                     bool* dfs_allocation_failed)
+    -> tl::expected<std::vector<Replica>, ErrorCode> {
+    if (dfs_allocation_failed != nullptr) {
+        *dfs_allocation_failed = false;
     }
-    auto abort_reserved_quota = [&] {
-        AbortTenantQuota(tenant_id, reserved_quota_charge);
-    };
-
     std::vector<Replica> replicas;
     const auto write_mode = DetermineReplicaWriteMode(config);
     size_t allocated_memory_replicas = 0;
     size_t allocated_nof_replicas = 0;
-    if (config.replica_num > 0) {
-        const bool use_local_first =
-            allocation_strategy_type_ == AllocationStrategyType::LOCAL_FIRST &&
-            config.replica_num == 1;
-        std::string writer_host_id;
-        if (use_local_first) {
-            writer_host_id = config.host_id.empty() ? GetClientHostId(client_id)
-                                                    : config.host_id;
-        }
-
-        ScopedAllocatorAccess allocator_access =
-            segment_manager_.getAllocatorAccess();
-        const auto& allocator_manager = allocator_access.getAllocatorManager();
+    bool has_enough_memory_segments = false;
 
+    if (config.replica_num > 0) {
         std::vector<std::string> preferred_segments;
         auto append_preferred_segment = [&preferred_segments](
                                             const std::string& segment_name) {
@@ -3407,44 +4667,45 @@ auto MasterService::AllocateAndInsertMetadata(
                 append_preferred_segment(preferred_segment);
             }
         }
-        if (!writer_host_id.empty()) {
-            auto host_ordered_segments =
-                allocator_access.GetHostOrderedSegments(writer_host_id, key);
-            for (const auto& segment_name : host_ordered_segments) {
-                append_preferred_segment(segment_name);
-            }
-            if (!host_ordered_segments.empty()) {
-                VLOG(1) << "key=" << key
-                        << ", writer_host_id=" << writer_host_id
-                        << ", local_first_preferred_segments="
-                        << host_ordered_segments.size();
+        AllocatorManager allocator_snapshot;
+        {
+            ScopedAllocatorAccess allocator_access =
+                segment_manager_.getAllocatorAccess();
+            has_enough_memory_segments = allocator_access.getAllocatorManager()
+                                             .getServingNames()
+                                             .size() >= config.replica_num;
+            if (!writer_host_id.empty()) {
+                auto host_ordered_segments =
+                    allocator_access.GetHostOrderedSegments(writer_host_id,
+                                                            key);
+                for (const auto& segment_name : host_ordered_segments) {
+                    append_preferred_segment(segment_name);
+                }
+                if (!host_ordered_segments.empty()) {
+                    VLOG(1) << "key=" << key
+                            << ", writer_host_id=" << writer_host_id
+                            << ", local_first_preferred_segments="
+                            << host_ordered_segments.size();
+                }
             }
-        }
-
-        const SsdMetricsProvider* ssd_provider = nullptr;
-        std::optional<ScopedLocalDiskSegmentAccess> ssd_access;
-        if (allocation_strategy_type_ ==
-            AllocationStrategyType::SSD_FREE_RATIO_FIRST) {
-            ssd_access.emplace(segment_manager_.getLocalDiskSegmentAccess());
-            ssd_provider = &*ssd_access;
+            allocator_snapshot = allocator_access.SnapshotAllocatorManager();
         }
 
         auto allocation_result = allocation_strategy_->Allocate(
-            allocator_manager, value_length, config.replica_num,
-            preferred_segments, std::set<std::string>(), ReplicaType::MEMORY,
-            ssd_provider);
+            allocator_snapshot, value_length, config.replica_num,
+            preferred_segments, std::set<std::string>(), ReplicaType::MEMORY);
 
         if (!allocation_result.has_value()) {
             VLOG(1) << "Failed to allocate replicas for key=" << key
                     << ", error: " << allocation_result.error();
             if (allocation_result.error() == ErrorCode::INVALID_PARAMS) {
-                abort_reserved_quota();
                 return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
             }
             if (write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
                 MasterMetricManager::instance().inc_put_start_alloc_failures();
-                need_mem_eviction_ = true;
-                abort_reserved_quota();
+                if (has_enough_memory_segments) {
+                    need_mem_eviction_ = true;
+                }
                 return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
             }
         } else {
@@ -3471,13 +4732,11 @@ auto MasterService::AllocateAndInsertMetadata(
             VLOG(1) << "Failed to allocate nof replicas for key=" << key
                     << ", error: " << allocation_result.error();
             if (allocation_result.error() == ErrorCode::INVALID_PARAMS) {
-                abort_reserved_quota();
                 return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
             }
             if (write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
                 MasterMetricManager::instance().inc_put_start_alloc_failures();
                 need_nof_eviction_ = true;
-                abort_reserved_quota();
                 return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
             }
         } else {
@@ -3497,7 +4756,8 @@ auto MasterService::AllocateAndInsertMetadata(
              allocated_nof_replicas != config.nof_replica_num)) {
             MasterMetricManager::instance().inc_put_start_alloc_failures();
             if (config.replica_num > 0 &&
-                allocated_memory_replicas != config.replica_num) {
+                allocated_memory_replicas != config.replica_num &&
+                has_enough_memory_segments) {
                 need_mem_eviction_ = true;
             }
             if (config.nof_replica_num > 0 &&
@@ -3510,7 +4770,6 @@ auto MasterService::AllocateAndInsertMetadata(
                 << ", allocated_memory_replicas=" << allocated_memory_replicas
                 << ", requested_nof_replicas=" << config.nof_replica_num
                 << ", allocated_nof_replicas=" << allocated_nof_replicas;
-        abort_reserved_quota();
         return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
     }
 
@@ -3531,19 +4790,61 @@ auto MasterService::AllocateAndInsertMetadata(
 
     if (use_disk_replica_) {
         std::string file_path =
-            ResolvePathFromKey(key, root_fs_dir_, cluster_id_);
+            FileUtil::ResolvePathFromKey(key, root_fs_dir_, cluster_id_);
         replicas.emplace_back(file_path, value_length,
                               ReplicaStatus::PROCESSING);
     }
 
+    if (config.dfs_replica_num > 0) {
+        if (!dfs_allocator_ || !dfs_allocator_->IsInitialized()) {
+            LOG(ERROR) << "Failed to allocate DFS replica for key=" << key
+                       << ", error=dfs_allocator_not_initialized";
+            return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+        }
+        auto alloc = dfs_allocator_->Allocate(key, value_length);
+        if (!alloc) {
+            LOG(ERROR) << "Failed to allocate DFS replica for key=" << key
+                       << ", error=" << alloc.error();
+            if (dfs_allocation_failed != nullptr) {
+                *dfs_allocation_failed =
+                    alloc.error() == ErrorCode::NO_AVAILABLE_HANDLE;
+            }
+            return tl::make_unexpected(alloc.error());
+        }
+        replicas.emplace_back(std::move(*alloc), ReplicaStatus::PROCESSING);
+    }
+
+    return replicas;
+}
+
+auto MasterService::InsertMetadata(
+    MetadataShardAccessorRW& shard, const UUID& client_id,
+    const std::string& key, uint64_t value_length,
+    const ReplicateConfig& config, const std::string& group_id,
+    const TenantId& tenant_id, const std::chrono::system_clock::time_point& now,
+    const ResolvedSoftPinRequest& soft_pin_request,
+    std::vector<Replica>&& replicas, uint64_t pending_quota_charge,
+    std::optional<std::chrono::system_clock::time_point>
+        committed_soft_pin_timeout)
+    -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
+    const auto deadline_to_index = committed_soft_pin_timeout;
+    auto& tenant_state = GetOrCreateTenantState(shard.get(), tenant_id);
+    if (tenant_state.metadata.contains(key)) {
+        FreeDfsReplicas(key, replicas);
+        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+    }
+
     std::vector<Replica::Descriptor> replica_list;
+    std::unordered_set<ReplicaID> eligible_replica_ids;
     replica_list.reserve(replicas.size());
+    eligible_replica_ids.reserve(replicas.size());
     int i = 0;
     VLOG(1) << "PutStart, create replicas: client_id=" << client_id
             << ", key=" << key << ", value_length=" << value_length;
     for (const auto& replica : replicas) {
         const auto desc = replica.get_descriptor();
         replica_list.emplace_back(desc);
+        eligible_replica_ids.insert(replica.id());
 
         if (replica.is_memory_replica()) {
             const auto& mem_desc = desc.get_memory_descriptor();
@@ -3557,46 +4858,129 @@ auto MasterService::AllocateAndInsertMetadata(
                     << nof_desc.buffer_descriptor.buffer_address_
                     << ", transport_endpoint="
                     << nof_desc.buffer_descriptor.transport_endpoint_;
+        } else if (replica.is_dfs_replica()) {
+            const auto& dfs_desc = desc.get_dfs_descriptor();
+            VLOG(1) << "Replica #" << ++i << ": dfs_file=" << dfs_desc.file_path
+                    << ", offset=" << dfs_desc.offset
+                    << ", shard_idx=" << dfs_desc.shard_idx;
         }
     }
 
     auto [it, inserted] = tenant_state.metadata.emplace(
         std::piecewise_construct, std::forward_as_tuple(key),
         std::forward_as_tuple(client_id, now, value_length, std::move(replicas),
-                              config.with_soft_pin, config.with_hard_pin,
-                              config.data_type, group_id, tenant_id, key));
+                              std::move(committed_soft_pin_timeout),
+                              config.with_hard_pin, config.data_type, group_id,
+                              tenant_id, key));
     if (!inserted) {
-        LOG(INFO) << "key=" << key << ", info=object_already_exists";
-        abort_reserved_quota();
+        FreeDfsReplicas(key, replicas);
         return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
     }
-    IncrementTenantMetadataObjectCount(tenant_id);
-    it->second.reserved_quota_charge_bytes = reserved_quota_charge;
-    RegisterGroupMember(tenant_state, tenant_id, key, group_id);
+    if (enable_multi_tenants_) {
+        auto adopt_result = it->second.quota_ledger.AdoptPendingCharge(
+            GetBoundTenantQuotaHandle(tenant_state), pending_quota_charge);
+        if (!adopt_result) {
+            LogTenantQuotaLedgerError(adopt_result, "adopt_pending", tenant_id,
+                                      key);
+            auto failed_replicas = it->second.PopReplicas();
+            FreeDfsReplicas(key, failed_replicas);
+            tenant_state.metadata.erase(it);
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+    }
+    it->second.BeginSoftPinAction(soft_pin_request,
+                                  std::move(eligible_replica_ids));
+    if (deadline_to_index) {
+        soft_pin_deadline_index_.Upsert(tenant_id.MakeScopedKey(key),
+                                        GetMetadataShardIndex(it->second),
+                                        *deadline_to_index);
+    }
+    // Wire grouped objects to the group's shared lease; ungrouped objects keep
+    // the per-object lease created at construction.
+    if (!group_id.empty()) {
+        it->second.lease_ = RegisterGroupMember(tenant_id, key, group_id);
+    }
     tenant_state.processing_keys.insert(key);
 
     return replica_list;
 }
 
+auto MasterService::AllocateAndInsertMetadata(
+    MetadataShardAccessorRW& shard, const UUID& client_id,
+    const std::string& key, uint64_t value_length,
+    const ReplicateConfig& config, const std::string& writer_host_id,
+    const std::string& group_id, const TenantId& tenant_id,
+    const std::chrono::system_clock::time_point& now,
+    const ResolvedSoftPinRequest& soft_pin_request,
+    std::optional<std::chrono::system_clock::time_point>
+        committed_soft_pin_timeout,
+    bool* dfs_allocation_failed)
+    -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
+    auto& tenant_state = GetOrCreateTenantState(shard.get(), tenant_id);
+    if (tenant_state.metadata.contains(key)) {
+        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+    }
+
+    const uint64_t pending_quota_charge =
+        RequestedMemoryQuotaCharge(value_length, config);
+    auto quota_result = ChargeTenantQuota(
+        GetBoundTenantQuotaHandle(tenant_state), pending_quota_charge);
+    if (!quota_result) {
+        return tl::make_unexpected(quota_result.error());
+    }
+
+    auto allocation_result = AllocateReplicas(
+        key, value_length, config, writer_host_id, dfs_allocation_failed);
+    if (!allocation_result) {
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                           pending_quota_charge);
+        return tl::make_unexpected(allocation_result.error());
+    }
+
+    auto insert_result = InsertMetadata(
+        shard, client_id, key, value_length, config, group_id, tenant_id, now,
+        soft_pin_request, std::move(allocation_result.value()),
+        pending_quota_charge, std::move(committed_soft_pin_timeout));
+    if (!insert_result) {
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                           pending_quota_charge);
+    }
+    return insert_result;
+}
+
 auto MasterService::PutStart(const UUID& client_id, const std::string& key,
                              const TenantId& tenant_id,
                              const uint64_t slice_length,
                              const ReplicateConfig& config)
     -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
-    auto normalized_tenant_result = ResolveTenantIdForWrite(tenant_id);
-    if (!normalized_tenant_result) {
-        return tl::make_unexpected(normalized_tenant_result.error());
-    }
-    const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
-                                   key};
-    if ((config.replica_num == 0 && config.nof_replica_num == 0) ||
+    const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
+    if ((config.replica_num == 0 && config.nof_replica_num == 0 &&
+         config.dfs_replica_num == 0) ||
         key.empty() || slice_length == 0) {
         LOG(ERROR) << "key=" << key << ", replica_num=" << config.replica_num
                    << ", nof_replica_num=" << config.nof_replica_num
+                   << ", dfs_replica_num=" << config.dfs_replica_num
                    << ", slice_length=" << slice_length
                    << ", key_size=" << key.size() << ", error=invalid_params";
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    if (config.dfs_replica_num > 1 ||
+        (config.dfs_replica_num > 0 && config.replica_num == 0)) {
+        LOG(ERROR) << "key=" << key << ", replica_num=" << config.replica_num
+                   << ", dfs_replica_num=" << config.dfs_replica_num
+                   << ", error=invalid_dfs_replica_config";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (config.dfs_replica_num > 0 && !object_id.tenant_id.IsDefault()) {
+        LOG(ERROR) << "key=" << key << ", tenant_id=" << tenant_id
+                   << ", error=dfs_currently_requires_default_tenant";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (config.dfs_replica_num > 0 &&
+        (!enable_dfs_ || !dfs_allocator_ || !dfs_allocator_->IsInitialized())) {
+        LOG(ERROR) << "key=" << key << ", error=dfs_allocator_not_initialized";
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
     if (config.prefer_alloc_in_same_node && config.nof_replica_num > 0) {
         LOG(ERROR) << "key=" << key
                    << ", nof_replica_num=" << config.nof_replica_num
@@ -3614,7 +4998,19 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
     }
 #endif
 
+    auto soft_pin_request = ResolveSoftPinRequest(config);
+    if (!soft_pin_request) {
+        return tl::make_unexpected(soft_pin_request.error());
+    }
+
     UpdateClientHostId(client_id, config.host_id);
+    std::string writer_host_id;
+    if ((allocation_strategy_type_ == AllocationStrategyType::LOCAL_FIRST ||
+         config.prefer_alloc_in_same_node) &&
+        config.replica_num == 1) {
+        writer_host_id = config.host_id.empty() ? GetClientHostId(client_id)
+                                                : config.host_id;
+    }
 
     if ((memory_allocator_type_ == BufferAllocatorType::CACHELIB) &&
         (slice_length > kMaxSliceSize)) {
@@ -3635,36 +5031,36 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
 
     [[maybe_unused]] auto object_operation_lock =
         AcquireObjectOperationLock(object_id.tenant_id, object_id.user_key);
-    const uint64_t requested_quota_charge =
-        RequestedMemoryQuotaCharge(slice_length, config);
-
-    auto attempt_once =
+    // Set by AllocateReplicas only when DFS allocation itself failed with
+    // capacity exhaustion; gates the forced bucket eviction retry below so
+    // memory/NoF exhaustion cannot delete unrelated DFS data.
+    bool dfs_allocation_failed = false;
+    auto admit =
         [&]() -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
-        std::unique_lock<std::mutex> zero_charge_policy_lock(
-            tenant_quota_policy_mutex_, std::defer_lock);
-        if (ShouldProtectZeroChargeMetadataCreate(requested_quota_charge)) {
-            zero_charge_policy_lock.lock();
-            auto latest_tenant_result =
-                ResolveTenantIdForWriteLocked(tenant_id);
-            if (!latest_tenant_result) {
-                return tl::make_unexpected(latest_tenant_result.error());
-            }
-        }
-
         auto now = std::chrono::system_clock::now();
-        std::optional<size_t> retry_shard_idx;
         {
-            auto alive_clients = getAliveClientsSnapshot();
+            std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
             std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+            auto retaining_clients = GetRetainingClientIdsLocked();
+            client_lock.unlock();
             const size_t lookup_shard_idx =
-                getMetadataShardIndex(object_id.tenant_id, object_id.user_key);
+                getShardIndex(object_id.tenant_id, object_id.user_key);
             MetadataShardAccessorRW shard(this, lookup_shard_idx);
-            auto& tenant_state = shard->tenants[object_id.tenant_id];
+            auto& tenant_state =
+                GetOrCreateTenantState(shard.get(), object_id.tenant_id);
+            auto admission_result =
+                ChargeTenantQuota(GetBoundTenantQuotaHandle(tenant_state), 0);
+            if (!admission_result) {
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(object_id.tenant_id);
+                }
+                return tl::make_unexpected(admission_result.error());
+            }
 
             auto it = tenant_state.metadata.find(key);
             if (it != tenant_state.metadata.end()) {
                 auto cleanup_plan =
-                    BuildStaleHandleCleanupPlan(it->second, alive_clients);
+                    BuildStaleHandleCleanupPlan(it->second, retaining_clients);
                 if (!cleanup_plan.removed_ids.empty()) {
                     auto persist_result = PersistStaleHandleCleanupForHA(
                         "PutStart(stale cleanup)", object_id.tenant_id, key,
@@ -3675,8 +5071,9 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
                     if (enable_oplog_) {
                         return tl::make_unexpected(
                             ErrorCode::OBJECT_ALREADY_EXISTS);
-                    } else if (CleanupStaleHandles(tenant_state, it->second,
-                                                   alive_clients, &shard)) {
+                    } else if (CleanupStaleHandles(key, object_id.tenant_id,
+                                                   tenant_state, it->second,
+                                                   retaining_clients, &shard)) {
                         EraseMetadata(tenant_state, it, object_id.tenant_id,
                                       QuotaEraseMode::kFull, &shard);
                         it = tenant_state.metadata.end();
@@ -3688,8 +5085,6 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
                         metadata.put_start_time +
                                 put_start_discard_timeout_sec_ >=
                             now) {
-                        LOG(INFO)
-                            << "key=" << key << ", info=object_already_exists";
                         return tl::make_unexpected(
                             ErrorCode::OBJECT_ALREADY_EXISTS);
                     }
@@ -3704,6 +5099,7 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
                     auto replicas = PopReplicasWithCacheTotalAccounting(
                         metadata, &Replica::fn_is_processing);
                     if (!replicas.empty()) {
+                        FreeDfsReplicas(key, replicas);
                         std::lock_guard lock(discarded_replicas_mutex_);
                         discarded_replicas_.emplace_back(
                             std::move(replicas),
@@ -3717,55 +5113,39 @@ auto MasterService::PutStart(const UUID& client_id, const std::string& key,
             }
 
             if (it == tenant_state.metadata.end()) {
-                const size_t target_shard_idx =
-                    group_id.empty()
-                        ? getShardIndex(object_id.tenant_id, object_id.user_key)
-                        : getShardIndex(group_id);
-                if (target_shard_idx != lookup_shard_idx) {
-                    retry_shard_idx = target_shard_idx;
-                    if (tenant_state.Empty()) {
-                        shard->tenants.erase(object_id.tenant_id);
-                    }
-                } else {
-                    return AllocateAndInsertMetadata(
-                        shard, client_id, key, slice_length, config, group_id,
-                        object_id.tenant_id, now);
-                }
+                return AllocateAndInsertMetadata(
+                    shard, client_id, key, slice_length, config, writer_host_id,
+                    group_id, object_id.tenant_id, now, *soft_pin_request,
+                    std::nullopt, &dfs_allocation_failed);
             }
-        }
-
-        std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-        MetadataShardAccessorRW shard(this, retry_shard_idx.value());
-        auto& retry_tenant_state = shard->tenants[object_id.tenant_id];
-        if (GetGroupRoute(object_id.tenant_id, object_id.user_key)
-                .has_value() ||
-            retry_tenant_state.metadata.contains(key)) {
-            LOG(INFO) << "key=" << key << ", info=object_already_exists";
+            // Logically unreachable: the object-exists paths above always
+            // return or erase the entry. Kept for -Wreturn-type.
             return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
         }
-        return AllocateAndInsertMetadata(shard, client_id, key, slice_length,
-                                         config, group_id, object_id.tenant_id,
-                                         now);
     };
 
-    for (int attempt = 0; attempt <= kMaxTenantQuotaEvictionRetries;
-         ++attempt) {
-        auto result = attempt_once();
-        if (result.has_value() ||
-            result.error() != ErrorCode::TENANT_QUOTA_EXCEEDED) {
-            return result;
-        }
-        if (attempt == kMaxTenantQuotaEvictionRetries) {
-            MasterMetricManager::instance().inc_tenant_quota_reject(
-                object_id.tenant_id.value(), "quota_exceeded");
-            return result;
-        }
-        EvictTenantMemoryForQuota(
-            object_id.tenant_id,
-            tenant_quota_table_.ComputeDeficit(object_id.tenant_id,
-                                               requested_quota_charge));
+    // Tenant over-quota remains a background-eviction concern. Bucket-count
+    // exhaustion is different: serialize recovery, retry admission after any
+    // recovery ahead of us, then allow one forced, fully validated bucket
+    // eviction and one final retry. The path is gated on dfs_allocation_failed
+    // so memory/NoF exhaustion keeps its background-eviction behavior.
+    auto result = admit();
+    if (!result && dfs_allocation_failed && config.dfs_replica_num > 0 &&
+        bucket_allocator_ != nullptr) {
+        std::lock_guard recovery_lock(dfs_bucket_recovery_mutex_);
+        dfs_allocation_failed = false;
+        result = admit();
+        if (!result && dfs_allocation_failed &&
+            TryRecoverDfsSpaceAfterAllocationFailure()) {
+            dfs_allocation_failed = false;
+            result = admit();
+        }
+    }
+    if (!result && result.error() == ErrorCode::TENANT_QUOTA_EXCEEDED) {
+        MasterMetricManager::instance().inc_tenant_quota_reject(
+            object_id.tenant_id.value(), "quota_exceeded");
     }
-    return tl::make_unexpected(ErrorCode::TENANT_QUOTA_EXCEEDED);
+    return result;
 }
 
 auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
@@ -3792,7 +5172,8 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
             return (replica.is_memory_replica() &&
                     !replica.has_invalid_mem_handle()) ||
                    (replica.is_nof_replica() &&
-                    !replica.has_invalid_nof_handle());
+                    !replica.has_invalid_nof_handle()) ||
+                   replica.is_dfs_replica();
         }
         if (replica_type == ReplicaType::MEMORY) {
             return replica.is_memory_replica() &&
@@ -3829,11 +5210,51 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
         return tl::make_unexpected(ErrorCode::INVALID_WRITE);
     }
 
+    if (bucket_allocator_ != nullptr && (replica_type == ReplicaType::ALL ||
+                                         replica_type == ReplicaType::DFS)) {
+        std::vector<DistributedFSDescriptor> pending_descriptors;
+        metadata.VisitReplicas(
+            [](const Replica& replica) {
+                return replica.is_dfs_replica() && replica.is_processing();
+            },
+            [&pending_descriptors](const Replica& replica) {
+                pending_descriptors.push_back(replica.get_dfs_descriptor());
+            });
+        for (const auto& descriptor : pending_descriptors) {
+            if (!bucket_allocator_->MarkCommitted(key, descriptor)) {
+                LOG(ERROR) << "key=" << key
+                           << ", error=dfs_runtime_commit_failed, bucket_id="
+                           << descriptor.shard_idx;
+                return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+            }
+        }
+    }
+
+    const bool had_completed_replica =
+        metadata.HasReplica(&Replica::fn_is_completed);
+    bool completed_pending_replica = false;
     metadata.VisitReplicas(
         [&is_target_replica](const Replica& replica) {
             return replica.is_processing() && is_target_replica(replica);
         },
-        [](Replica& replica) { replica.mark_complete(); });
+        [this, &key, &metadata, &completed_pending_replica](Replica& replica) {
+            if (replica.is_processing() &&
+                metadata.PendingSoftPinOwnsReplica(replica.id())) {
+                completed_pending_replica = true;
+            }
+            replica.mark_complete();
+            if (replica.is_dfs_replica() && dfs_allocator_) {
+                const auto& desc = replica.get_dfs_descriptor();
+                dfs_allocator_->UpdateAccess(key, desc);
+            }
+        });
+
+    if (!had_completed_replica && completed_pending_replica &&
+        metadata.HasReplica(&Replica::fn_is_completed)) {
+        const auto soft_pin_result =
+            metadata.CommitPendingSoftPin(std::chrono::system_clock::now());
+        ApplySoftPinEvaluation(metadata, soft_pin_result);
+    }
 
     if (object_meta.object_checksum.has_value() ||
         replica_type == ReplicaType::ALL ||
@@ -3842,50 +5263,39 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
         metadata.object_checksum = object_meta.object_checksum;
     }
 
-    const bool has_memory_replica = metadata.HasMemReplica();
-    const bool should_settle_quota =
-        replica_type == ReplicaType::MEMORY ||
-        (replica_type == ReplicaType::ALL && has_memory_replica) ||
-        !has_memory_replica;
-    if (metadata.reserved_quota_charge_bytes > 0 && should_settle_quota) {
-        const uint64_t actual_charge = CompletedMemoryQuotaCharge(metadata);
-        const uint64_t commit_charge =
-            actual_charge > metadata.committed_quota_charge_bytes
-                ? actual_charge - metadata.committed_quota_charge_bytes
-                : 0;
-        const uint64_t abort_charge =
-            metadata.reserved_quota_charge_bytes > commit_charge
-                ? metadata.reserved_quota_charge_bytes - commit_charge
-                : 0;
-        CommitTenantQuota(object_id.tenant_id, commit_charge);
-        AbortTenantQuota(object_id.tenant_id, abort_charge);
-        metadata.reserved_quota_charge_bytes = 0;
-        metadata.committed_quota_charge_bytes = actual_charge;
-        ReleaseTenantQuota(object_id.tenant_id,
-                           metadata.pending_replaced_quota_charge_bytes);
-        metadata.pending_replaced_quota_charge_bytes = 0;
-    }
-
-    if (enable_offload_ && !offload_on_evict_) {
+    auto settle_result =
+        SettlePrimaryWriteQuotaIfReady(accessor.GetTenantState(), metadata);
+    if (!settle_result) {
+        return tl::make_unexpected(settle_result.error());
+    }
+
+    if (replica_type != ReplicaType::DFS && enable_offload_ &&
+        !offload_on_evict_ && !metadata.HasReplica([](const Replica& replica) {
+            return replica.is_dfs_replica() && replica.is_processing();
+        })) {
         auto& tenant_state = accessor.GetTenantState();
-        bool task_created = false;
+        // One marker covers every mirror pushed below, so the mirrors are
+        // collected before the marker is recorded.
+        std::optional<ReplicaID> source_id;
+        std::vector<UUID> mirror_clients;
         metadata.VisitReplicas(
             [](const Replica& replica) {
                 return replica.is_completed() && replica.is_memory_replica();
             },
-            [this, &object_id, &tenant_state, &task_created](Replica& replica) {
-                auto result = PushOffloadingQueue(object_id, replica);
-                if (result) {
-                    if (!task_created) {
-                        replica.inc_refcnt();
-                        tenant_state.offloading_tasks.emplace(
-                            object_id.user_key,
-                            OffloadingTask{replica.id(),
-                                           std::chrono::system_clock::now()});
-                        task_created = true;
-                    }
+            [this, &object_id, &source_id, &mirror_clients](Replica& replica) {
+                auto result =
+                    PushOffloadingQueue(object_id, replica, &mirror_clients);
+                if (result && !source_id.has_value()) {
+                    replica.inc_refcnt();
+                    source_id = replica.id();
                 }
             });
+        if (source_id.has_value()) {
+            tenant_state.offloading_tasks.emplace(
+                object_id.user_key,
+                OffloadingTask{*source_id, std::chrono::system_clock::now(),
+                               std::move(mirror_clients)});
+        }
     }
 
     // If the object is completed, remove it from the processing set.
@@ -3896,11 +5306,8 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
 
     SyncCacheTotalAccounting(metadata);
     // TODO: add inc_nof_cache_nums() (ranhaojia)
-    // 1. Set lease timeout to now, indicating that the object has no lease
-    // at beginning. 2. If this object has soft pin enabled, set it to be soft
-    // pinned.
-    metadata.GrantLease(0, default_kv_soft_pin_ttl_);
-    PublishKvStored(key, replica_type, metadata, object_id.tenant_id);
+    metadata.GrantReadLease(std::chrono::milliseconds::zero());
+    PublishKvStored(key, metadata, object_id.tenant_id);
 
     if (enable_oplog_ && ordered_oplog_writer_) {
         std::string payload = SerializeMetadataForOpLog(metadata);
@@ -3917,6 +5324,22 @@ auto MasterService::PutEnd(const UUID& client_id, const ObjectMeta& object_meta,
 auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
                                const TenantId& tenant_id, Replica& replica)
     -> tl::expected<bool, ErrorCode> {
+    const auto client_liveness = FindClientRecord(client_id);
+    auto retaining_guard = client_liveness
+                               ? client_liveness->TryAcquireRetainingGuard()
+                               : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    replica.bindClientLiveness(client_liveness);
+    return AddReplicaForRetainedClient(client_id, key, tenant_id, replica);
+}
+
+auto MasterService::AddReplicaForRetainedClient(const UUID& client_id,
+                                                const std::string& key,
+                                                const TenantId& tenant_id,
+                                                Replica& replica)
+    -> tl::expected<bool, ErrorCode> {
     assert(tenant_id.IsValid());
     TenantId normalized_tenant;
     std::unique_lock<std::mutex> policy_lock(tenant_quota_policy_mutex_,
@@ -3931,15 +5354,28 @@ auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
         normalized_tenant = std::move(normalized_tenant_result.value());
     }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    // Same admission rule as NotifyOffloadSuccess's existing-object path,
+    // checked inside the same shared-lock section as the write below: a disk
+    // replica may only be registered for a client whose LOCAL_DISK segment
+    // entry still exists, so a registration cannot land after a concurrent
+    // UnmountLocalDiskSegment's sweep and survive as a stale owner. Scoped
+    // to enable_offload_, where the segment registry exists and a
+    // deregistration can race; with the subsystem off both the mount and
+    // unmount RPCs refuse, so there is nothing to check against and no race
+    // to close.
+    if (enable_offload_ && !HasMountedLocalDiskSegment(client_id)) {
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
     const ObjectIdentity object_id{std::move(normalized_tenant), key};
     MetadataAccessorRW accessor(this, object_id);
     if (!accessor.Exists()) {
         accessor.Create(
             client_id,
             replica.get_descriptor().get_local_disk_descriptor().object_size,
-            std::vector<Replica>{}, false);
+            std::vector<Replica>{});
     }
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     if (replica.type() != ReplicaType::LOCAL_DISK) {
         LOG(ERROR) << "Invalid replica type: " << replica.type()
                    << ". Expected ReplicaType::LOCAL_DISK.";
@@ -3980,9 +5416,7 @@ auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
 
         auto persist_result = AppendOpLogVisibleBeforeDurable(
             OpType::PUT_END, object_id.tenant_id.value(), key,
-            SerializeMetadataForOpLogFromReplicaDescriptors(
-                metadata.client_id, metadata.size, post, metadata.group_id,
-                metadata.data_type));
+            SerializeMetadataForOpLogFromReplicaDescriptors(metadata, post));
         if (!persist_result) {
             return tl::make_unexpected(persist_result.error());
         }
@@ -3995,6 +5429,8 @@ auto MasterService::AddReplica(const UUID& client_id, const std::string& key,
         auto& shard = accessor.GetShard();
         shard.OnDiskReplicaAdded(metadata);
         SyncCacheTotalAccounting(metadata);
+        SyncKvObjectState(key, metadata, object_id.tenant_id,
+                          previous_kv_media);
         return true;
     }
 
@@ -4031,6 +5467,7 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
     }
 
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     if (client_id != metadata.client_id) {
         LOG(ERROR) << "Illegal client " << client_id << " to PutRevoke key "
                    << key << ", was PutStart-ed by " << metadata.client_id;
@@ -4042,14 +5479,15 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
         return tl::make_unexpected(ErrorCode::INVALID_WRITE);
     }
 
-    auto processing_rep = metadata.GetFirstReplica([replica_type](
-                                                       const Replica& replica) {
-        if (replica_type == ReplicaType::ALL) {
-            return (replica.is_memory_replica() || replica.is_nof_replica()) &&
-                   !replica.is_processing();
-        }
-        return replica.type() == replica_type && !replica.is_processing();
-    });
+    auto processing_rep =
+        metadata.GetFirstReplica([replica_type](const Replica& replica) {
+            if (replica_type == ReplicaType::ALL) {
+                return (replica.is_memory_replica() ||
+                        replica.is_nof_replica() || replica.is_dfs_replica()) &&
+                       !replica.is_processing();
+            }
+            return replica.type() == replica_type && !replica.is_processing();
+        });
     if (processing_rep != nullptr) {
         LOG(ERROR) << "key=" << key << ", status=" << processing_rep->status()
                    << ", error=invalid_replica_status";
@@ -4061,7 +5499,8 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
             return false;
         }
         if (replica_type == ReplicaType::ALL) {
-            return r.is_memory_replica() || r.is_nof_replica();
+            return r.is_memory_replica() || r.is_nof_replica() ||
+                   r.is_dfs_replica();
         }
         return r.type() == replica_type;
     };
@@ -4078,6 +5517,7 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
             removed_ids.push_back(r.id());
             r.mark_removed();
         });
+        metadata.ClearPendingSoftPinIfNoViableReplica();
 
         tl::expected<OpLogEntry, ErrorCode> persist_result;
         if (remaining.empty()) {
@@ -4093,9 +5533,8 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
             persist_result = AppendReservedOpLogWithDurableFinalize(
                 std::move(reservation.value()), OpType::PUT_END,
                 tenant_id.value(), key,
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, remaining,
-                    metadata.group_id, metadata.data_type),
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata,
+                                                                remaining),
                 [this, removed_ids = std::move(removed_ids)](
                     const OpLogEntry& durable_entry) {
                     FinalizeRemovedReplicasAfterDurable(
@@ -4110,14 +5549,29 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
 
     const uint64_t before_charge = CompletedMemoryQuotaCharge(metadata);
     EraseReplicasWithCacheTotalAccounting(metadata, target_pred);
+    metadata.ClearPendingSoftPinIfNoViableReplica();
     const uint64_t after_charge = CompletedMemoryQuotaCharge(metadata);
-    if (before_charge > after_charge) {
-        ReleaseCommittedQuotaCharge(metadata, before_charge - after_charge);
+    if (enable_multi_tenants_ && before_charge > after_charge) {
+        auto release_result = metadata.quota_ledger.ReleaseCommitted(
+            GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+            before_charge - after_charge);
+        if (!release_result) {
+            LogTenantQuotaLedgerError(release_result, "release_committed",
+                                      object_id.tenant_id, key);
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
     }
-    if (!metadata.HasReplica(&Replica::fn_is_memory_replica)) {
-        AbortTenantQuota(object_id.tenant_id,
-                         metadata.reserved_quota_charge_bytes);
-        metadata.reserved_quota_charge_bytes = 0;
+    if (!metadata.IsValid()) {
+        accessor.Erase();
+        return {};
+    }
+
+    SyncKvObjectState(key, metadata, object_id.tenant_id, previous_kv_media);
+
+    auto settle_result =
+        SettlePrimaryWriteQuotaIfReady(accessor.GetTenantState(), metadata);
+    if (!settle_result) {
+        return tl::make_unexpected(settle_result.error());
     }
 
     // If the object is completed, remove it from the processing set.
@@ -4126,9 +5580,6 @@ auto MasterService::PutRevoke(const UUID& client_id, const std::string& key,
         accessor.EraseFromProcessing();
     }
 
-    if (metadata.IsValid() == false) {
-        accessor.Erase();
-    }
     return {};
 }
 
@@ -4169,8 +5620,9 @@ std::vector<tl::expected<void, ErrorCode>> MasterService::BatchPutRevoke(
 //
 // Three-way dispatch depending on key state:
 //   Case A: key does not exist  → allocate new buffers (same as PutStart)
-//   Case B: key exists, same size → in-place update (reuse existing buffers)
-//   Case C: key exists, different size → discard old + allocate new
+//   Case B: key exists, same size, no readers → in-place update
+//   Case C: key exists, different size, bucket DFS, or leased memory → allocate
+//           new buffers
 //
 // Before reaching Case B/C the function runs safety checks and may preempt
 // an in-progress Put/Upsert on the same key.  Preempted PROCESSING replicas
@@ -4184,21 +5636,38 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                                 const uint64_t slice_length,
                                 const ReplicateConfig& config)
     -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
-    auto normalized_tenant_result = ResolveTenantIdForWrite(tenant_id);
-    if (!normalized_tenant_result) {
-        return tl::make_unexpected(normalized_tenant_result.error());
-    }
-    const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
-                                   key};
+    const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     // --- Parameter validation (same as PutStart) ---
-    if ((config.replica_num == 0 && config.nof_replica_num == 0) ||
+    if ((config.replica_num == 0 && config.nof_replica_num == 0 &&
+         config.dfs_replica_num == 0) ||
         key.empty() || slice_length == 0) {
         LOG(ERROR) << "key=" << key << ", replica_num=" << config.replica_num
                    << ", nof_replica_num=" << config.nof_replica_num
+                   << ", dfs_replica_num=" << config.dfs_replica_num
                    << ", slice_length=" << slice_length
                    << ", key_size=" << key.size() << ", error=invalid_params";
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    if (config.dfs_replica_num > 1 ||
+        (config.dfs_replica_num > 0 && config.replica_num == 0)) {
+        LOG(ERROR) << "key=" << key << ", replica_num=" << config.replica_num
+                   << ", dfs_replica_num=" << config.dfs_replica_num
+                   << ", error=invalid_dfs_replica_config";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (config.dfs_replica_num > 0 && !object_id.tenant_id.IsDefault()) {
+        LOG(ERROR) << "key=" << key << ", tenant_id=" << tenant_id
+                   << ", error=dfs_currently_requires_default_tenant";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (config.dfs_replica_num > 0 &&
+        (!enable_dfs_ || dfs_allocator_ == nullptr ||
+         !dfs_allocator_->IsInitialized())) {
+        LOG(ERROR) << "key=" << key
+                   << ", dfs_replica_num=" << config.dfs_replica_num
+                   << ", error=dfs_service_unavailable";
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
     if (config.prefer_alloc_in_same_node && config.nof_replica_num > 0) {
         LOG(ERROR) << "key=" << key
                    << ", nof_replica_num=" << config.nof_replica_num
@@ -4216,7 +5685,19 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
     }
 #endif
 
+    auto soft_pin_request = ResolveSoftPinRequest(config);
+    if (!soft_pin_request) {
+        return tl::make_unexpected(soft_pin_request.error());
+    }
+
     UpdateClientHostId(client_id, config.host_id);
+    std::string writer_host_id;
+    if ((allocation_strategy_type_ == AllocationStrategyType::LOCAL_FIRST ||
+         config.prefer_alloc_in_same_node) &&
+        config.replica_num == 1) {
+        writer_host_id = config.host_id.empty() ? GetClientHostId(client_id)
+                                                : config.host_id;
+    }
 
     if ((memory_allocator_type_ == BufferAllocatorType::CACHELIB) &&
         (slice_length > kMaxSliceSize)) {
@@ -4237,41 +5718,42 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
 
     [[maybe_unused]] auto object_operation_lock =
         AcquireObjectOperationLock(object_id.tenant_id, object_id.user_key);
-    const uint64_t requested_quota_charge =
-        RequestedMemoryQuotaCharge(slice_length, config);
-
-    auto attempt_once =
+    bool dfs_allocation_failed = false;
+    ReplicateConfig allocation_config = config;
+    std::string allocation_group_id = group_id;
+    std::optional<std::chrono::system_clock::time_point>
+        allocation_committed_soft_pin_timeout;
+    auto admit =
         [&]() -> tl::expected<std::vector<Replica::Descriptor>, ErrorCode> {
-        std::unique_lock<std::mutex> zero_charge_policy_lock(
-            tenant_quota_policy_mutex_, std::defer_lock);
-        if (ShouldProtectZeroChargeMetadataCreate(requested_quota_charge)) {
-            zero_charge_policy_lock.lock();
-            auto latest_tenant_result =
-                ResolveTenantIdForWriteLocked(tenant_id);
-            if (!latest_tenant_result) {
-                return tl::make_unexpected(latest_tenant_result.error());
-            }
-        }
-
         auto now = std::chrono::system_clock::now();
-        std::optional<size_t> case_a_retry_shard_idx;
         {
             // --- Lock acquisition ---
-            auto alive_clients = getAliveClientsSnapshot();
+            std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
             std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-            // Use getMetadataShardIndex to find the object at its current shard
-            // (handles both grouped and ungrouped routing).
+            auto retaining_clients = GetRetainingClientIdsLocked();
+            client_lock.unlock();
+            // Objects are always routed by hash(tenant, key); group_id does
+            // not affect routing.
             const size_t lookup_shard_idx =
-                getMetadataShardIndex(object_id.tenant_id, object_id.user_key);
+                getShardIndex(object_id.tenant_id, object_id.user_key);
             MetadataShardAccessorRW shard(this, lookup_shard_idx);
-            auto& tenant_state = shard->tenants[object_id.tenant_id];
+            auto& tenant_state =
+                GetOrCreateTenantState(shard.get(), object_id.tenant_id);
+            auto admission_result =
+                ChargeTenantQuota(GetBoundTenantQuotaHandle(tenant_state), 0);
+            if (!admission_result) {
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(object_id.tenant_id);
+                }
+                return tl::make_unexpected(admission_result.error());
+            }
 
             auto it = tenant_state.metadata.find(key);
 
             // --- Step 0: stale handle cleanup ---
             if (it != tenant_state.metadata.end()) {
                 auto cleanup_plan =
-                    BuildStaleHandleCleanupPlan(it->second, alive_clients);
+                    BuildStaleHandleCleanupPlan(it->second, retaining_clients);
                 if (!cleanup_plan.removed_ids.empty()) {
                     auto persist_result = PersistStaleHandleCleanupForHA(
                         "UpsertStart(stale cleanup)", object_id.tenant_id, key,
@@ -4282,8 +5764,9 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                     if (enable_oplog_) {
                         return tl::make_unexpected(
                             ErrorCode::OBJECT_ALREADY_EXISTS);
-                    } else if (CleanupStaleHandles(tenant_state, it->second,
-                                                   alive_clients, &shard)) {
+                    } else if (CleanupStaleHandles(key, object_id.tenant_id,
+                                                   tenant_state, it->second,
+                                                   retaining_clients, &shard)) {
                         // EraseMetadata handles processing_keys,
                         // replication_tasks, offloading_tasks (with
                         // dec_refcnt), and promotion task cleanup.
@@ -4323,9 +5806,29 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                         ErrorCode::OBJECT_HAS_REPLICATION_TASK);
                 }
 
-                // Reject if an offload-to-disk task is in progress (same
-                // reason).
-                if (tenant_state.offloading_tasks.count(key) > 0) {
+                // An in-place Upsert returns and overwrites the existing
+                // buffers, so every completed Client-owned target must still
+                // be serving before any queue or metadata state is changed.
+                if (metadata.size == slice_length &&
+                    metadata.HasReplica([](const Replica& replica) {
+                        if (!replica.is_completed() ||
+                            (!replica.is_memory_replica() &&
+                             !replica.is_local_disk_replica())) {
+                            return false;
+                        }
+                        Replica::Descriptor descriptor;
+                        return !replica.getDescriptorIfAvailable(descriptor);
+                    })) {
+                    return tl::make_unexpected(
+                        ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+                }
+
+                // Cancel a still-queued offload so the upsert can take the key
+                // over. Once a store worker owns the task it is reading the
+                // source buffer for its SSD write, so the upsert waits for
+                // NotifyOffloadSuccess to clear the marker instead.
+                if (!CancelQueuedOffloadTask(tenant_state, metadata,
+                                             object_id)) {
                     LOG(INFO) << "key=" << key
                               << ", error=object_has_offloading_task";
                     return tl::make_unexpected(
@@ -4341,7 +5844,9 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                 if (tenant_state.processing_keys.count(key) > 0) {
                     auto processing_replicas =
                         metadata.PopReplicas(&Replica::fn_is_processing);
+                    metadata.ClearPendingSoftPinAction();
                     if (!processing_replicas.empty()) {
+                        FreeDfsReplicas(key, processing_replicas);
                         std::lock_guard lock(discarded_replicas_mutex_);
                         discarded_replicas_.emplace_back(
                             std::move(processing_replicas),
@@ -4352,31 +5857,36 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                     // If no COMPLETE replicas survive the preemption, this key
                     // effectively does not exist — fall through to Case A.
                     if (!metadata.HasReplica(&Replica::fn_is_completed)) {
+                        allocation_committed_soft_pin_timeout =
+                            metadata.GetCommittedSoftPinTimeout();
+                        if (allocation_committed_soft_pin_timeout &&
+                            *allocation_committed_soft_pin_timeout <= now) {
+                            allocation_committed_soft_pin_timeout.reset();
+                        }
                         EraseMetadata(tenant_state, it, object_id.tenant_id,
                                       QuotaEraseMode::kFull, &shard);
                         it = tenant_state.metadata.end();
+                    } else {
+                        auto settle_result = SettlePrimaryWriteQuotaIfReady(
+                            tenant_state, metadata);
+                        if (!settle_result) {
+                            return tl::make_unexpected(settle_result.error());
+                        }
                     }
                 }
             }
 
             // --- Case A: key does not exist (or was erased above) ---
-            // Allocate fresh buffers, identical to PutStart.
+            // Allocate fresh buffers, identical to PutStart. Objects are always
+            // routed by hash(tenant, key); group_id does not affect routing.
             if (it == tenant_state.metadata.end()) {
                 VLOG(1) << "key=" << key << ", action=upsert_start_case_a";
-                const size_t case_a_shard_idx =
-                    group_id.empty()
-                        ? getShardIndex(object_id.tenant_id, object_id.user_key)
-                        : getShardIndex(group_id);
-                if (case_a_shard_idx != lookup_shard_idx) {
-                    case_a_retry_shard_idx = case_a_shard_idx;
-                    if (tenant_state.Empty()) {
-                        shard->tenants.erase(object_id.tenant_id);
-                    }
-                } else {
-                    return AllocateAndInsertMetadata(
-                        shard, client_id, key, slice_length, config, group_id,
-                        object_id.tenant_id, now);
-                }
+                return AllocateAndInsertMetadata(
+                    shard, client_id, key, slice_length, allocation_config,
+                    writer_host_id, allocation_group_id, object_id.tenant_id,
+                    now, *soft_pin_request,
+                    allocation_committed_soft_pin_timeout,
+                    &dfs_allocation_failed);
             } else {
                 // --- Step 2: key exists with COMPLETE replicas → Case B or C
                 // ---
@@ -4391,41 +5901,79 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                     return tl::make_unexpected(ErrorCode::OBJECT_REPLICA_BUSY);
                 }
 
+                bool restore_missing_bucket_dfs = false;
                 if (metadata.size == slice_length) {
-                    // --- Case B: same size — in-place update ---
-                    // Reuse existing buffer addresses.  No allocation or
-                    // deallocation. The client will RDMA-write new data to the
-                    // same addresses.
-                    //
-                    // hard_pinned is const and preserved automatically — upsert
-                    // does not change the eviction protection level of an
-                    // existing object.
+                    // Validate same-size DFS topology before changing storage.
+                    const size_t existing_dfs_replicas =
+                        metadata.CountReplicas(&Replica::fn_is_dfs_replica);
+                    if (config.dfs_replica_num > 0 ||
+                        existing_dfs_replicas > 0) {
+                        const size_t existing_memory_replicas =
+                            metadata.CountReplicas(
+                                &Replica::fn_is_memory_replica);
+                        const size_t existing_nof_replicas =
+                            metadata.CountReplicas(&Replica::fn_is_nof_replica);
+                        restore_missing_bucket_dfs =
+                            bucket_allocator_ != nullptr &&
+                            existing_memory_replicas == config.replica_num &&
+                            existing_nof_replicas == config.nof_replica_num &&
+                            existing_dfs_replicas == 0 &&
+                            config.dfs_replica_num > 0;
+                        if (existing_memory_replicas != config.replica_num ||
+                            existing_nof_replicas != config.nof_replica_num ||
+                            (existing_dfs_replicas != config.dfs_replica_num &&
+                             !restore_missing_bucket_dfs)) {
+                            LOG(ERROR)
+                                << "key=" << key
+                                << ", error=dfs_upsert_topology_mismatch"
+                                << ", existing_memory="
+                                << existing_memory_replicas
+                                << ", requested_memory=" << config.replica_num
+                                << ", existing_nof=" << existing_nof_replicas
+                                << ", requested_nof=" << config.nof_replica_num
+                                << ", existing_dfs=" << existing_dfs_replicas
+                                << ", requested_dfs=" << config.dfs_replica_num;
+                            return tl::make_unexpected(
+                                ErrorCode::INVALID_PARAMS);
+                        }
+                    }
+                }
+
+                const bool has_read_lease = !metadata.IsLeaseExpired(now);
+                if (has_read_lease &&
+                    metadata.HasReplica([](const Replica& replica) {
+                        return !replica.is_memory_replica();
+                    })) {
+                    // File-backed reads can resolve storage by key, so they
+                    // cannot retain an old version across replacement.
+                    return tl::make_unexpected(ErrorCode::OBJECT_HAS_LEASE);
+                }
+
+                const bool has_bucket_dfs_replica =
+                    bucket_allocator_ != nullptr &&
+                    metadata.HasReplica(&Replica::fn_is_dfs_replica);
+                if (metadata.size == slice_length && !has_read_lease &&
+                    !has_bucket_dfs_replica && !restore_missing_bucket_dfs) {
                     metadata.client_id = client_id;
                     metadata.put_start_time = now;
 
-                    // Reconcile soft_pin state with the incoming config.
-                    {
-                        SpinLocker locker(&metadata.lock);
-                        if (config.with_soft_pin &&
-                            !metadata.soft_pin_timeout) {
-                            metadata.soft_pin_timeout.emplace();
-                            MasterMetricManager::instance()
-                                .inc_soft_pin_key_count(1);
-                        } else if (!config.with_soft_pin &&
-                                   metadata.soft_pin_timeout) {
-                            metadata.soft_pin_timeout.reset();
-                            MasterMetricManager::instance()
-                                .dec_soft_pin_key_count(1);
-                        }
-                    }
+                    const auto previous_kv_media = KvMediaSnapshot(metadata);
 
                     // Mark COMPLETE → PROCESSING so readers won't see stale
                     // data mid-transfer.  The key becomes unreadable until
                     // UpsertEnd.
+                    std::unordered_set<ReplicaID> eligible_replica_ids;
                     metadata.VisitReplicas(
                         &Replica::fn_is_completed,
-                        [](Replica& replica) { replica.mark_processing(); });
+                        [&eligible_replica_ids](Replica& replica) {
+                            eligible_replica_ids.insert(replica.id());
+                            replica.mark_processing();
+                        });
+                    metadata.BeginSoftPinAction(
+                        *soft_pin_request, std::move(eligible_replica_ids));
                     SyncCacheTotalAccounting(metadata);
+                    SyncKvObjectState(key, metadata, object_id.tenant_id,
+                                      previous_kv_media);
 
                     tenant_state.processing_keys.insert(key);
 
@@ -4443,8 +5991,8 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                     return replica_list;
                 }
 
-                // --- Case C: different size — discard old replicas and
-                // reallocate
+                // --- Case C: different size, bucket DFS (including a replica
+                // lost to bucket eviction), or active readers — reallocate
                 // --- Old buffers cannot be reused.  Move them to
                 // discarded_replicas_ for delayed release (readers may still
                 // hold descriptors without refcnt), then allocate fresh buffers
@@ -4453,78 +6001,186 @@ auto MasterService::UpsertStart(const UUID& client_id, const std::string& key,
                 // Preserve hard_pin and soft_pin from the old metadata so that
                 // eviction protection survives a size-changing upsert (RFC
                 // §2.2.2).
-                ReplicateConfig merged_config = config;
-                merged_config.with_hard_pin =
-                    merged_config.with_hard_pin || metadata.IsHardPinned();
-                merged_config.with_soft_pin =
-                    merged_config.with_soft_pin || metadata.IsSoftPinned();
-
-                const std::string existing_group_id = metadata.group_id;
-                const uint64_t old_quota_charge =
-                    metadata.committed_quota_charge_bytes != 0
-                        ? metadata.committed_quota_charge_bytes
-                        : CompletedMemoryQuotaCharge(metadata);
+                allocation_config = config;
+                allocation_config.with_hard_pin =
+                    allocation_config.with_hard_pin || metadata.IsHardPinned();
+                allocation_committed_soft_pin_timeout =
+                    metadata.GetCommittedSoftPinTimeout();
+                if (allocation_committed_soft_pin_timeout &&
+                    *allocation_committed_soft_pin_timeout <= now) {
+                    allocation_committed_soft_pin_timeout.reset();
+                }
+
+                allocation_group_id = metadata.group_id;
+                const auto previous_kv_media = KvMediaSnapshot(metadata);
+                TenantQuotaLedger replacement_charge;
+                auto* quota_account = GetBoundTenantQuotaHandle(tenant_state);
+                const bool has_replacement_charge =
+                    enable_multi_tenants_ &&
+                    metadata.quota_ledger.TotalChargedBytes() != 0;
+
+                // A leased memory snapshot still references the old replica
+                // descriptors. Allocate the replacement before removing the
+                // old metadata so an allocation failure leaves the old object
+                // readable instead of turning it into OBJECT_NOT_FOUND.
+                std::optional<std::vector<Replica>> replacement_replicas;
+                uint64_t replacement_pending_quota_charge = 0;
+                if (has_read_lease) {
+                    replacement_pending_quota_charge =
+                        RequestedMemoryQuotaCharge(slice_length,
+                                                   allocation_config);
+                    auto quota_result = ChargeTenantQuota(
+                        quota_account, replacement_pending_quota_charge);
+                    if (!quota_result) {
+                        return tl::make_unexpected(quota_result.error());
+                    }
+                    auto allocation_result = AllocateReplicas(
+                        key, slice_length, allocation_config, writer_host_id,
+                        &dfs_allocation_failed);
+                    if (!allocation_result) {
+                        ReleaseTenantQuota(quota_account,
+                                           replacement_pending_quota_charge);
+                        return tl::make_unexpected(allocation_result.error());
+                    }
+                    replacement_replicas.emplace(
+                        std::move(allocation_result.value()));
+                }
+
+                if (has_replacement_charge) {
+                    auto transfer_result =
+                        metadata.quota_ledger.TransferReplacementCharge(
+                            quota_account, replacement_charge);
+                    if (!transfer_result) {
+                        LogTenantQuotaLedgerError(transfer_result,
+                                                  "transfer_replacement_out",
+                                                  object_id.tenant_id, key);
+                        if (replacement_replicas.has_value()) {
+                            FreeDfsReplicas(key, *replacement_replicas);
+                            ReleaseTenantQuota(
+                                quota_account,
+                                replacement_pending_quota_charge);
+                        }
+                        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    }
+                }
+                // A query granted before this write lock can retain its
+                // descriptor for a full read TTL. Keep the old allocation for
+                // at least that long as well as the writer grace period.
+                const auto release_at =
+                    std::chrono::system_clock::now() +
+                    std::max(
+                        std::chrono::milliseconds(default_kv_lease_ttl_),
+                        std::chrono::duration_cast<std::chrono::milliseconds>(
+                            put_start_release_timeout_sec_));
                 auto old_replicas =
                     PopReplicasWithCacheTotalAccounting(metadata);
                 if (!old_replicas.empty()) {
+                    FreeDfsReplicas(key, old_replicas);
                     std::lock_guard lock(discarded_replicas_mutex_);
-                    discarded_replicas_.emplace_back(
-                        std::move(old_replicas),
-                        now + put_start_release_timeout_sec_);
+                    discarded_replicas_.emplace_back(std::move(old_replicas),
+                                                     release_at);
                 }
                 EraseMetadata(tenant_state, it, object_id.tenant_id,
-                              QuotaEraseMode::kPreserveOld, &shard);
+                              QuotaEraseMode::kPreserveOld, &shard,
+                              previous_kv_media);
 
                 VLOG(1) << "key=" << key
                         << ", action=upsert_start_case_c_reallocate";
-                auto allocate_result = AllocateAndInsertMetadata(
-                    shard, client_id, key, slice_length, merged_config,
-                    existing_group_id, object_id.tenant_id, now);
+                tl::expected<std::vector<Replica::Descriptor>, ErrorCode>
+                    allocate_result =
+                        replacement_replicas.has_value()
+                            ? InsertMetadata(
+                                  shard, client_id, key, slice_length,
+                                  allocation_config, allocation_group_id,
+                                  object_id.tenant_id, now, *soft_pin_request,
+                                  std::move(*replacement_replicas),
+                                  replacement_pending_quota_charge,
+                                  allocation_committed_soft_pin_timeout)
+                            : AllocateAndInsertMetadata(
+                                  shard, client_id, key, slice_length,
+                                  allocation_config, writer_host_id,
+                                  allocation_group_id, object_id.tenant_id, now,
+                                  *soft_pin_request,
+                                  allocation_committed_soft_pin_timeout,
+                                  &dfs_allocation_failed);
                 if (!allocate_result) {
-                    ReleaseTenantQuota(object_id.tenant_id, old_quota_charge);
+                    if (replacement_replicas.has_value()) {
+                        ReleaseTenantQuota(quota_account,
+                                           replacement_pending_quota_charge);
+                    }
+                    if (has_replacement_charge) {
+                        auto rollback_result =
+                            replacement_charge.ReleaseReplacement(
+                                quota_account);
+                        LogTenantQuotaLedgerError(rollback_result,
+                                                  "rollback_replacement",
+                                                  object_id.tenant_id, key);
+                    }
                     return allocate_result;
                 }
                 auto new_it = tenant_state.metadata.find(key);
-                if (new_it != tenant_state.metadata.end()) {
-                    new_it->second.pending_replaced_quota_charge_bytes =
-                        old_quota_charge;
+                if (has_replacement_charge) {
+                    if (new_it == tenant_state.metadata.end()) {
+                        auto rollback_result =
+                            replacement_charge.ReleaseReplacement(
+                                quota_account);
+                        LogTenantQuotaLedgerError(rollback_result,
+                                                  "rollback_replacement",
+                                                  object_id.tenant_id, key);
+                        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    }
+                    auto transfer_result =
+                        replacement_charge.TransferReplacementCharge(
+                            quota_account, new_it->second.quota_ledger);
+                    if (!transfer_result) {
+                        LogTenantQuotaLedgerError(transfer_result,
+                                                  "transfer_replacement_in",
+                                                  object_id.tenant_id, key);
+                        EraseMetadata(tenant_state, new_it, object_id.tenant_id,
+                                      QuotaEraseMode::kFull, &shard);
+                        if (replacement_charge.ReplacedBytes() != 0) {
+                            auto rollback_result =
+                                replacement_charge.ReleaseReplacement(
+                                    quota_account);
+                            LogTenantQuotaLedgerError(rollback_result,
+                                                      "rollback_replacement",
+                                                      object_id.tenant_id, key);
+                        }
+                        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    }
                 }
                 return allocate_result;
             }
         }
-        std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-        MetadataShardAccessorRW shard(this, case_a_retry_shard_idx.value());
-        auto& retry_tenant_state = shard->tenants[object_id.tenant_id];
-        const auto current_route =
-            GetGroupRoute(object_id.tenant_id, object_id.user_key);
-        if (current_route.has_value() ||
-            retry_tenant_state.metadata.contains(key)) {
-            LOG(INFO) << "key=" << key << ", info=object_already_exists";
-            return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
-        }
-        return AllocateAndInsertMetadata(shard, client_id, key, slice_length,
-                                         config, group_id, object_id.tenant_id,
-                                         now);
     };
 
-    for (int attempt = 0; attempt <= kMaxTenantQuotaEvictionRetries;
-         ++attempt) {
-        auto result = attempt_once();
-        if (result.has_value() ||
-            result.error() != ErrorCode::TENANT_QUOTA_EXCEEDED) {
-            return result;
-        }
-        if (attempt == kMaxTenantQuotaEvictionRetries) {
-            MasterMetricManager::instance().inc_tenant_quota_reject(
-                object_id.tenant_id.value(), "quota_exceeded");
-            return result;
-        }
-        EvictTenantMemoryForQuota(
-            object_id.tenant_id,
-            tenant_quota_table_.ComputeDeficit(object_id.tenant_id,
-                                               requested_quota_charge));
+    // Over-quota is rejected outright. Making room is the background pass's
+    // job (EvictTenantsOverWatermark), not the write path's: the same contract
+    // the pool has when enable_multi_tenants is false -- this write fails, the
+    // evictor builds headroom, the next one succeeds. Evicting inline instead
+    // put a scan of up to kNumShards shard write locks on admission, which
+    // every concurrent writer at the ceiling repeated for the same freed
+    // extent.
+    auto result = admit();
+    // Eviction scans metadata shards, so recover only after admit releases its
+    // shard lock. Serialize recovery and re-admit before deciding whether this
+    // request still needs to evict one bucket.
+    if (!result && dfs_allocation_failed && config.dfs_replica_num > 0 &&
+        bucket_allocator_ != nullptr) {
+        std::lock_guard recovery_lock(dfs_bucket_recovery_mutex_);
+        dfs_allocation_failed = false;
+        result = admit();
+        if (!result && dfs_allocation_failed &&
+            TryRecoverDfsSpaceAfterAllocationFailure()) {
+            dfs_allocation_failed = false;
+            result = admit();
+        }
+    }
+    if (!result && result.error() == ErrorCode::TENANT_QUOTA_EXCEEDED) {
+        MasterMetricManager::instance().inc_tenant_quota_reject(
+            object_id.tenant_id.value(), "quota_exceeded");
     }
-    return tl::make_unexpected(ErrorCode::TENANT_QUOTA_EXCEEDED);
+    return result;
 }
 
 auto MasterService::UpsertEnd(const UUID& client_id,
@@ -4611,6 +6267,7 @@ auto MasterService::EvictDiskReplica(const UUID& client_id,
     }
 
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
 
     if (replica_type != ReplicaType::DISK &&
         replica_type != ReplicaType::LOCAL_DISK) {
@@ -4659,9 +6316,8 @@ auto MasterService::EvictDiskReplica(const UUID& client_id,
                 persist_result = AppendReservedOpLogWithDurableFinalize(
                     std::move(reservation.value()), OpType::PUT_END,
                     metadata.tenant_id.value(), key,
-                    SerializeMetadataForOpLogFromReplicaDescriptors(
-                        metadata.client_id, metadata.size, remaining,
-                        metadata.group_id, metadata.data_type),
+                    SerializeMetadataForOpLogFromReplicaDescriptors(metadata,
+                                                                    remaining),
                     [this, removed_ids = std::move(removed_ids)](
                         const OpLogEntry& durable_entry) {
                         FinalizeRemovedReplicasAfterDurable(
@@ -4681,9 +6337,8 @@ auto MasterService::EvictDiskReplica(const UUID& client_id,
         } else {
             persist_result = AppendOpLogWithDurableFinalize(
                 OpType::PUT_END, metadata.tenant_id.value(), key,
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, remaining,
-                    metadata.group_id, metadata.data_type),
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata,
+                                                                remaining),
                 nullptr);
         }
         if (!persist_result) {
@@ -4704,8 +6359,8 @@ auto MasterService::EvictDiskReplica(const UUID& client_id,
         }
     }
 
+    SyncKvObjectState(key, metadata, object_id.tenant_id, previous_kv_media);
     if (!metadata.IsValid()) {
-        PublishKvRemoved(key, metadata, object_id.tenant_id);
         accessor.Erase();
     }
     return {};
@@ -4727,15 +6382,24 @@ std::vector<tl::expected<void, ErrorCode>> MasterService::BatchEvictDiskReplica(
 tl::expected<CopyStartResponse, ErrorCode> MasterService::CopyStart(
     const UUID& client_id, const std::string& key, const TenantId& tenant_id,
     const std::string& src_segment,
-    const std::vector<std::string>& tgt_segments) {
+    const std::vector<std::string>& tgt_segments,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
     auto normalized_tenant_result = ResolveTenantIdForWrite(tenant_id);
     if (!normalized_tenant_result) {
         return tl::make_unexpected(normalized_tenant_result.error());
     }
     const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
                                    key};
+    const bool dynamic_copy = dynamic_replication_lease_id != UUID{};
+    const auto record = FindClientRecord(client_id);
+    auto serving_guard =
+        record ? record->TryAcquireServingGuard() : std::nullopt;
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    {
+    if (!dynamic_copy) {
         ScopedSegmentAccess segment_access =
             segment_manager_.getSegmentAccess();
         for (const auto& tgt_segment : tgt_segments) {
@@ -4765,60 +6429,125 @@ tl::expected<CopyStartResponse, ErrorCode> MasterService::CopyStart(
     }
 
     auto& metadata = accessor.Get();
+    auto& tenant_state = accessor.GetTenantState();
+
+    size_t new_replica_count = 0;
+    for (const auto& tgt_segment : tgt_segments) {
+        if (metadata.GetReplicaBySegmentName(tgt_segment) == nullptr) {
+            ++new_replica_count;
+        }
+    }
+
+    auto pending_validation = ValidateDynamicReplicaPendingForCopyStart(
+        tenant_state, key, dynamic_replication_lease_id, client_id, src_segment,
+        DynamicReplicationVersionEpoch(metadata),
+        dynamic_replication_version_epoch, tgt_segments);
+    if (new_replica_count == 0 && dynamic_copy) {
+        if (!pending_validation) {
+            return tl::make_unexpected(pending_validation.error());
+        }
+        ClearDynamicReplicationStateForKey(tenant_state, key);
+        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+    }
+    if (!pending_validation) {
+        return tl::make_unexpected(pending_validation.error());
+    }
+    if (dynamic_copy) {
+        ScopedSegmentAccess segment_access =
+            segment_manager_.getSegmentAccess();
+        for (const auto& tgt_segment : tgt_segments) {
+            if (!segment_access.ExistsSegmentName(tgt_segment)) {
+                ClearDynamicReplicationStateForKey(tenant_state, key);
+                LOG(ERROR) << "key=" << key << ", tgt_segment=" << tgt_segment
+                           << ", error=target_segment_not_found";
+                return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+            }
+            if (!segment_access.IsSegmentAllocatable(tgt_segment)) {
+                ClearDynamicReplicationStateForKey(tenant_state, key);
+                LOG(ERROR) << "key=" << key << ", tgt_segment=" << tgt_segment
+                           << ", error=target_segment_not_allocatable";
+                return tl::make_unexpected(
+                    ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+            }
+        }
+    }
+
     auto source = metadata.GetReplicaBySegmentName(src_segment);
     if (source == nullptr || !source->is_completed() ||
         source->has_invalid_mem_handle()) {
         LOG(ERROR) << "key=" << key << ", src_segment=" << src_segment
                    << ", replica not found or not valid";
+        if (dynamic_copy) {
+            ClearDynamicReplicationStateForKey(tenant_state, key);
+        }
         return tl::make_unexpected(ErrorCode::REPLICA_NOT_FOUND);
     }
-
-    size_t new_replica_count = 0;
-    for (const auto& tgt_segment : tgt_segments) {
-        if (metadata.GetReplicaBySegmentName(tgt_segment) == nullptr) {
-            ++new_replica_count;
+    Replica::Descriptor source_descriptor;
+    if (!TryGetReadableReplicaDescriptor(*source, source_descriptor)) {
+        if (dynamic_copy) {
+            ClearDynamicReplicationStateForKey(tenant_state, key);
         }
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
 
-    const uint64_t reserved_quota_charge =
+    const uint64_t pending_quota_charge =
         SaturatingMultiply(static_cast<uint64_t>(metadata.size),
                            static_cast<uint64_t>(new_replica_count));
-    auto quota_result =
-        ReserveTenantQuota(object_id.tenant_id, reserved_quota_charge);
+    auto quota_result = ChargeTenantQuota(
+        GetBoundTenantQuotaHandle(tenant_state), pending_quota_charge);
     if (!quota_result) {
         if (quota_result.error() == ErrorCode::TENANT_QUOTA_EXCEEDED) {
             MasterMetricManager::instance().inc_tenant_quota_reject(
                 object_id.tenant_id.value(), "quota_exceeded");
         }
+        if (dynamic_copy) {
+            ClearDynamicReplicationStateForKey(tenant_state, key);
+        }
         return tl::make_unexpected(quota_result.error());
     }
-    auto abort_reserved_quota = [&] {
-        AbortTenantQuota(object_id.tenant_id, reserved_quota_charge);
+    auto refund_pending_quota = [&] {
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                           pending_quota_charge);
     };
 
     std::vector<Replica> replicas;
     replicas.reserve(new_replica_count);
+    std::vector<std::string> new_target_segments;
+    new_target_segments.reserve(new_replica_count);
+    // Target allocation acquires the target owner's guard. Do not retain the
+    // executor's guard across it: source/target Clients may be identical, and
+    // two opposite copy operations must not hold their source guards while
+    // waiting for each other's target guard. This CopyStart was already
+    // admitted while the source guard was held; the metadata shard remains
+    // locked, so terminal cleanup cannot pass this operation before its
+    // metadata changes become visible.
+    serving_guard.reset();
+    AllocatorManager allocator_snapshot;
     {
         ScopedAllocatorAccess allocator_access =
             segment_manager_.getAllocatorAccess();
-        const auto& allocator_manager = allocator_access.getAllocatorManager();
+        allocator_snapshot = allocator_access.SnapshotAllocatorManager();
+    }
 
-        for (auto& tgt_segment : tgt_segments) {
-            if (metadata.GetReplicaBySegmentName(tgt_segment) != nullptr) {
-                // Skip used segments.
-                continue;
-            }
+    for (auto& tgt_segment : tgt_segments) {
+        if (metadata.GetReplicaBySegmentName(tgt_segment) != nullptr) {
+            // Skip used segments.
+            continue;
+        }
 
-            auto replica = allocation_strategy_->AllocateFrom(
-                allocator_manager, metadata.size, tgt_segment);
-            if (!replica.has_value()) {
-                LOG(ERROR) << "key=" << key << ", tgt_segment=" << tgt_segment
-                           << ", failed to allocate replica";
-                abort_reserved_quota();
-                return tl::make_unexpected(replica.error());
+        auto replica = allocation_strategy_->AllocateFrom(
+            allocator_snapshot, metadata.size, tgt_segment);
+        if (!replica.has_value()) {
+            LOG(ERROR) << "key=" << key << ", tgt_segment=" << tgt_segment
+                       << ", failed to allocate replica";
+            refund_pending_quota();
+            if (dynamic_copy) {
+                ClearDynamicReplicationStateForKey(tenant_state, key);
             }
-            replicas.push_back(std::move(*replica));
+            return tl::make_unexpected(replica.error());
         }
+        replicas.push_back(std::move(*replica));
+        new_target_segments.push_back(tgt_segment);
     }
 
     CopyStartResponse response;
@@ -4826,24 +6555,42 @@ tl::expected<CopyStartResponse, ErrorCode> MasterService::CopyStart(
     std::vector<ReplicaID> replica_ids;
     replica_ids.reserve(replicas.size());
 
-    response.source = source->get_descriptor();
+    response.source = std::move(source_descriptor);
     for (const auto& replica : replicas) {
         replica_ids.push_back(replica.id());
-        response.targets.emplace_back(replica.get_descriptor());
+        Replica::Descriptor descriptor;
+        if (!replica.getDescriptorIfAvailable(descriptor)) {
+            refund_pending_quota();
+            if (dynamic_copy) {
+                ClearDynamicReplicationStateForKey(tenant_state, key);
+            }
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        response.targets.push_back(std::move(descriptor));
     }
 
     // Create replication task for tracking.
-    auto& tenant_state = accessor.GetTenantState();
     auto task_insert = tenant_state.replication_tasks.emplace(
         std::piecewise_construct, std::forward_as_tuple(key),
         std::forward_as_tuple(client_id, std::chrono::system_clock::now(),
                               ReplicationTask::Type::COPY, source->id(),
-                              std::move(replica_ids), reserved_quota_charge));
+                              std::move(replica_ids), pending_quota_charge,
+                              dynamic_replication_lease_id,
+                              dynamic_replication_version_epoch));
     if (!task_insert.second) {
-        abort_reserved_quota();
+        refund_pending_quota();
+        if (dynamic_copy) {
+            ClearDynamicReplicationStateForKey(tenant_state, key);
+        }
         return tl::make_unexpected(ErrorCode::OBJECT_HAS_REPLICATION_TASK);
     }
 
+    RegisterDynamicReplicaStart(tenant_state, metadata, key, src_segment,
+                                DynamicReplicationVersionEpoch(metadata),
+                                new_target_segments,
+                                task_insert.first->second.replica_ids);
+
     // Increase source refcnt to protect it from eviction.
     source->inc_refcnt();
 
@@ -4855,7 +6602,15 @@ tl::expected<CopyStartResponse, ErrorCode> MasterService::CopyStart(
 }
 
 tl::expected<void, ErrorCode> MasterService::CopyEnd(
-    const UUID& client_id, const std::string& key, const TenantId& tenant_id) {
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRW accessor(this,
                                 MakeObjectIdentityForRequest(key, tenant_id));
@@ -4881,8 +6636,19 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
         LOG(ERROR) << "Ongoing replication task type is MOVE instead of COPY";
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    if (task.durable_cleanup_pending) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    if (task.dynamic_replication_lease_id != dynamic_replication_lease_id ||
+        task.dynamic_replication_version_epoch !=
+            dynamic_replication_version_epoch) {
+        LOG(ERROR) << "key=" << key
+                   << ", error=dynamic_replication_token_mismatch";
+        return tl::make_unexpected(ErrorCode::INVALID_VERSION);
+    }
 
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     auto source_id = task.source_id;
     auto source = metadata.GetReplicaByID(source_id);
     if (source == nullptr || !source->is_completed() ||
@@ -4903,8 +6669,10 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
                                  task.replica_ids.end(),
                                  replica.id()) != task.replica_ids.end();
             });
-        AbortTenantQuota(metadata.tenant_id, task.reserved_quota_charge_bytes);
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                           task.pending_quota_charge_bytes);
         accessor.EraseReplicationTask();
+        ClearDynamicReplicationStateForKey(accessor.GetTenantState(), key);
         if (!metadata.IsValid()) {
             // Remove the object if it does not have any replicas.
             accessor.Erase();
@@ -4918,6 +6686,7 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
     bool all_complete = true;
     uint64_t completed_quota_charge = 0;
     std::vector<ReplicaID> commit_target_ids;
+    std::vector<ReplicaID> failed_target_ids;
     commit_target_ids.reserve(task.replica_ids.size());
     for (const auto& replica_id : task.replica_ids) {
         auto replica = metadata.GetReplicaByID(replica_id);
@@ -4926,6 +6695,7 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
                 << "key=" << key << ", replica_id=" << replica_id
                 << ", copy target becomes invalid during data transfer";
             all_complete = false;
+            failed_target_ids.push_back(replica_id);
         } else {
             commit_target_ids.push_back(replica_id);
         }
@@ -4950,15 +6720,27 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
         }
     }
 
+    metadata.MarkDynamicReplicasComplete(commit_target_ids);
+    metadata.ForgetDynamicReplicas(failed_target_ids);
+    if (!failed_target_ids.empty()) {
+        std::unordered_set<ReplicaID> failed_ids(failed_target_ids.begin(),
+                                                 failed_target_ids.end());
+        EraseReplicasWithCacheTotalAccounting(
+            metadata, [&failed_ids](const Replica& replica) {
+                return failed_ids.contains(replica.id());
+            });
+    }
+
+    ClearDynamicReplicationStateForKey(accessor.GetTenantState(), key);
+
     if (enable_oplog_ && ordered_oplog_writer_) {
         std::vector<Replica::Descriptor> post;
         metadata.VisitReplicas(&Replica::fn_is_completed,
                                [&post](const Replica& replica) {
                                    post.push_back(replica.get_descriptor());
                                });
-        auto payload = SerializeMetadataForOpLogFromReplicaDescriptors(
-            metadata.client_id, metadata.size, post, metadata.group_id,
-            metadata.data_type);
+        auto payload =
+            SerializeMetadataForOpLogFromReplicaDescriptors(metadata, post);
         if (batch_reservation) {
             auto persist_result = AppendReservedOpLogWithDurableFinalize(
                 std::move(*batch_reservation), OpType::PUT_END,
@@ -4981,23 +6763,35 @@ tl::expected<void, ErrorCode> MasterService::CopyEnd(
 
     SyncCacheTotalAccounting(metadata);
 
-    const uint64_t commit_charge =
-        std::min(completed_quota_charge, task.reserved_quota_charge_bytes);
-    const uint64_t abort_charge =
-        task.reserved_quota_charge_bytes - commit_charge;
-    CommitAdditionalTenantQuota(metadata.tenant_id, commit_charge);
-    AbortTenantQuota(metadata.tenant_id, abort_charge);
-    metadata.committed_quota_charge_bytes =
-        SaturatingAdd(metadata.committed_quota_charge_bytes, commit_charge);
+    if (enable_multi_tenants_) {
+        auto settle_result = metadata.quota_ledger.SettleAdditional(
+            GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+            task.pending_quota_charge_bytes, completed_quota_charge);
+        if (!settle_result) {
+            LogTenantQuotaLedgerError(settle_result, "settle_additional",
+                                      metadata.tenant_id, key);
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+    }
 
     accessor.EraseReplicationTask();
 
+    SyncKvObjectState(key, metadata, tenant_id, previous_kv_media);
+
     return all_complete ? tl::expected<void, ErrorCode>()
                         : tl::make_unexpected(ErrorCode::REPLICA_IS_GONE);
 }
 
 tl::expected<void, ErrorCode> MasterService::CopyRevoke(
-    const UUID& client_id, const std::string& key, const TenantId& tenant_id) {
+    const UUID& client_id, const std::string& key, const TenantId& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRW accessor(this,
                                 MakeObjectIdentityForRequest(key, tenant_id));
@@ -5023,9 +6817,20 @@ tl::expected<void, ErrorCode> MasterService::CopyRevoke(
         LOG(ERROR) << "Ongoing replication task type is MOVE instead of COPY";
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    if (task.durable_cleanup_pending) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    if (task.dynamic_replication_lease_id != dynamic_replication_lease_id ||
+        task.dynamic_replication_version_epoch !=
+            dynamic_replication_version_epoch) {
+        LOG(ERROR) << "key=" << key
+                   << ", error=dynamic_replication_token_mismatch";
+        return tl::make_unexpected(ErrorCode::INVALID_VERSION);
+    }
 
     auto& metadata = accessor.Get();
-    auto source_id = task.source_id;
+    const auto source_id = task.source_id;
+    const auto replica_ids = task.replica_ids;
     auto source = metadata.GetReplicaByID(source_id);
     if (source == nullptr) {
         LOG(WARNING) << "key=" << key << ", source_id=" << source_id
@@ -5036,15 +6841,17 @@ tl::expected<void, ErrorCode> MasterService::CopyRevoke(
     }
 
     // Erase all replica_ids
-    for (const auto& replica_id : task.replica_ids) {
+    for (const auto& replica_id : replica_ids) {
         EraseReplicasWithCacheTotalAccounting(
             metadata, [&replica_id](const Replica& replica) {
                 return replica.id() == replica_id;
             });
     }
 
-    AbortTenantQuota(metadata.tenant_id, task.reserved_quota_charge_bytes);
+    ReleaseTenantQuota(GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                       task.pending_quota_charge_bytes);
     accessor.EraseReplicationTask();
+    ClearDynamicReplicationStateForKey(accessor.GetTenantState(), key);
 
     if (!metadata.IsValid()) {
         // Remove the object if it does not have any replicas.
@@ -5057,12 +6864,13 @@ tl::expected<void, ErrorCode> MasterService::CopyRevoke(
 tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
     const UUID& client_id, const std::string& key, const TenantId& tenant_id,
     const std::string& src_segment, const std::string& tgt_segment) {
-    auto normalized_tenant_result = ResolveTenantIdForWrite(tenant_id);
-    if (!normalized_tenant_result) {
-        return tl::make_unexpected(normalized_tenant_result.error());
+    const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
+    const auto record = FindClientRecord(client_id);
+    auto serving_guard =
+        record ? record->TryAcquireServingGuard() : std::nullopt;
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
-    const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
-                                   key};
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     if (src_segment == tgt_segment) {
         LOG(ERROR) << "key=" << key << ", move_tgt=" << tgt_segment
@@ -5098,6 +6906,7 @@ tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
     }
 
     auto& metadata = accessor.Get();
+    auto& tenant_state = accessor.GetTenantState();
     auto source = metadata.GetReplicaBySegmentName(src_segment);
     if (source == nullptr || !source->is_completed() ||
         source->has_invalid_mem_handle()) {
@@ -5105,13 +6914,21 @@ tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
                    << ", replica not found or not completed";
         return tl::make_unexpected(ErrorCode::REPLICA_NOT_FOUND);
     }
+    Replica::Descriptor source_descriptor;
+    if (!TryGetReadableReplicaDescriptor(*source, source_descriptor)) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
 
     std::vector<Replica> replicas;
+    // See CopyStart: target allocation owns its own Client guard and must not
+    // be nested under the source executor's guard. The metadata shard keeps
+    // terminal cleanup ordered after this already-admitted MoveStart.
+    serving_guard.reset();
     if (metadata.GetReplicaBySegmentName(tgt_segment) == nullptr) {
-        const uint64_t reserved_quota_charge =
+        const uint64_t pending_quota_charge =
             SaturatingMultiply(static_cast<uint64_t>(metadata.size), 1);
-        auto quota_result =
-            ReserveTenantQuota(object_id.tenant_id, reserved_quota_charge);
+        auto quota_result = ChargeTenantQuota(
+            GetBoundTenantQuotaHandle(tenant_state), pending_quota_charge);
         if (!quota_result) {
             if (quota_result.error() == ErrorCode::TENANT_QUOTA_EXCEEDED) {
                 MasterMetricManager::instance().inc_tenant_quota_reject(
@@ -5119,31 +6936,35 @@ tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
             }
             return tl::make_unexpected(quota_result.error());
         }
-        auto abort_reserved_quota = [&] {
-            AbortTenantQuota(object_id.tenant_id, reserved_quota_charge);
+        auto refund_pending_quota = [&] {
+            ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                               pending_quota_charge);
         };
 
-        ScopedAllocatorAccess allocator_access =
-            segment_manager_.getAllocatorAccess();
-        const auto& allocator_manager = allocator_access.getAllocatorManager();
-
+        AllocatorManager allocator_snapshot;
+        {
+            ScopedAllocatorAccess allocator_access =
+                segment_manager_.getAllocatorAccess();
+            allocator_snapshot = allocator_access.SnapshotAllocatorManager();
+        }
         auto replica = allocation_strategy_->AllocateFrom(
-            allocator_manager, metadata.size, tgt_segment);
+            allocator_snapshot, metadata.size, tgt_segment);
         if (!replica.has_value()) {
             LOG(ERROR) << "key=" << key << ", tgt_segment=" << tgt_segment
                        << ", failed to allocate replica";
-            abort_reserved_quota();
+            refund_pending_quota();
             return tl::make_unexpected(replica.error());
         }
         replicas.push_back(std::move(*replica));
     } else {
-        auto quota_result = ReserveTenantQuota(object_id.tenant_id, 0);
+        auto quota_result =
+            ChargeTenantQuota(GetBoundTenantQuotaHandle(tenant_state), 0);
         if (!quota_result) {
             return tl::make_unexpected(quota_result.error());
         }
     }
 
-    const uint64_t reserved_quota_charge =
+    const uint64_t pending_quota_charge =
         replicas.empty()
             ? 0
             : SaturatingMultiply(static_cast<uint64_t>(metadata.size), 1);
@@ -5151,23 +6972,31 @@ tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
     MoveStartResponse response;
     std::vector<ReplicaID> replica_ids;
 
-    response.source = source->get_descriptor();
+    response.source = std::move(source_descriptor);
     if (!replicas.empty()) {
         replica_ids.push_back(replicas[0].id());
-        response.target = replicas[0].get_descriptor();
+        Replica::Descriptor descriptor;
+        if (!replicas[0].getDescriptorIfAvailable(descriptor)) {
+            ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                               pending_quota_charge);
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        response.target = std::move(descriptor);
     } else {
         response.target = std::nullopt;
     }
 
     // Create replication task for tracking.
-    auto& tenant_state = accessor.GetTenantState();
     auto task_insert = tenant_state.replication_tasks.emplace(
         std::piecewise_construct, std::forward_as_tuple(key),
         std::forward_as_tuple(client_id, std::chrono::system_clock::now(),
                               ReplicationTask::Type::MOVE, source->id(),
-                              std::move(replica_ids), reserved_quota_charge));
+                              std::move(replica_ids), pending_quota_charge,
+                              UUID{}, 0));
     if (!task_insert.second) {
-        AbortTenantQuota(object_id.tenant_id, reserved_quota_charge);
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                           pending_quota_charge);
         return tl::make_unexpected(ErrorCode::OBJECT_HAS_REPLICATION_TASK);
     }
 
@@ -5183,6 +7012,12 @@ tl::expected<MoveStartResponse, ErrorCode> MasterService::MoveStart(
 
 tl::expected<void, ErrorCode> MasterService::MoveEnd(
     const UUID& client_id, const std::string& key, const TenantId& tenant_id) {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRW accessor(this,
                                 MakeObjectIdentityForRequest(key, tenant_id));
@@ -5210,6 +7045,7 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
     }
 
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     auto source_id = task.source_id;
     auto source = metadata.GetReplicaByID(source_id);
     if (source == nullptr || !source->is_completed() ||
@@ -5230,7 +7066,8 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
                                  task.replica_ids.end(),
                                  replica.id()) != task.replica_ids.end();
             });
-        AbortTenantQuota(metadata.tenant_id, task.reserved_quota_charge_bytes);
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                           task.pending_quota_charge_bytes);
         accessor.EraseReplicationTask();
         if (!metadata.IsValid()) {
             // Remove the object if it does not have any replicas.
@@ -5249,9 +7086,20 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
             LOG(WARNING)
                 << "key=" << key << ", replica_id=" << target_id
                 << ", move target becomes invalid during data transfer";
-            AbortTenantQuota(metadata.tenant_id,
-                             task.reserved_quota_charge_bytes);
-            // Source untouched; safe to drop the broken task.
+            // Release the refcnt taken in MoveStart. The success path below
+            // does this once the move completes; this error path must do it
+            // too, or the source replica stays pinned.
+            source->dec_refcnt();
+            // Discard target replica and clear the replication task.
+            EraseReplicasWithCacheTotalAccounting(
+                metadata, [&task](const Replica& replica) {
+                    return std::find(task.replica_ids.begin(),
+                                     task.replica_ids.end(),
+                                     replica.id()) != task.replica_ids.end();
+                });
+            ReleaseTenantQuota(
+                GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                task.pending_quota_charge_bytes);
             accessor.EraseReplicationTask();
             return tl::make_unexpected(ErrorCode::REPLICA_IS_GONE);
         }
@@ -5286,9 +7134,7 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
             persist_result = AppendReservedOpLogWithDurableFinalize(
                 std::move(reservation.value()), OpType::PUT_END,
                 metadata.tenant_id.value(), key,
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, post, metadata.group_id,
-                    metadata.data_type),
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata, post),
                 [this, removed_ids = std::vector<ReplicaID>{source_id}](
                     const OpLogEntry& durable_entry) {
                     FinalizeRemovedReplicasAfterDurable(
@@ -5297,9 +7143,7 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
         } else {
             persist_result = AppendOpLogWithDurableFinalize(
                 OpType::PUT_END, metadata.tenant_id.value(), key,
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, post, metadata.group_id,
-                    metadata.data_type),
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata, post),
                 nullptr);
         }
         if (!persist_result) {
@@ -5315,6 +7159,17 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
             replica->mark_complete();
         }
     }
+    if (enable_multi_tenants_) {
+        auto settle_result = metadata.quota_ledger.SettleAdditional(
+            GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+            task.pending_quota_charge_bytes,
+            has_target ? static_cast<uint64_t>(metadata.size) : 0);
+        if (!settle_result) {
+            LogTenantQuotaLedgerError(settle_result, "settle_additional",
+                                      metadata.tenant_id, key);
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+    }
 
     if (!(enable_ha_ && enable_oplog_)) {
         // Remove the source replica and release its space later.
@@ -5323,6 +7178,18 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
                 return replica.id() == source_id;
             });
         if (!source_replica.empty()) {
+            FreeDfsReplicas(key, source_replica);
+            if (enable_multi_tenants_) {
+                auto release_result = metadata.quota_ledger.ReleaseCommitted(
+                    GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                    static_cast<uint64_t>(metadata.size));
+                if (!release_result) {
+                    LogTenantQuotaLedgerError(release_result,
+                                              "release_committed",
+                                              metadata.tenant_id, key);
+                    return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                }
+            }
             std::lock_guard lock(discarded_replicas_mutex_);
             discarded_replicas_.emplace_back(
                 std::move(source_replica), std::chrono::system_clock::now() +
@@ -5330,14 +7197,21 @@ tl::expected<void, ErrorCode> MasterService::MoveEnd(
         }
     }
 
-    AbortTenantQuota(metadata.tenant_id, task.reserved_quota_charge_bytes);
     accessor.EraseReplicationTask();
 
+    SyncKvObjectState(key, metadata, tenant_id, previous_kv_media);
+
     return {};
 }
 
 tl::expected<void, ErrorCode> MasterService::MoveRevoke(
     const UUID& client_id, const std::string& key, const TenantId& tenant_id) {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRW accessor(this,
                                 MakeObjectIdentityForRequest(key, tenant_id));
@@ -5383,7 +7257,8 @@ tl::expected<void, ErrorCode> MasterService::MoveRevoke(
             });
     }
 
-    AbortTenantQuota(metadata.tenant_id, task.reserved_quota_charge_bytes);
+    ReleaseTenantQuota(GetBoundTenantQuotaHandle(accessor.GetTenantState()),
+                       task.pending_quota_charge_bytes);
     accessor.EraseReplicationTask();
 
     if (!metadata.IsValid()) {
@@ -5453,7 +7328,6 @@ auto MasterService::Remove(const std::string& key, const TenantId& tenant_id,
             return {};
         }
     }
-    PublishKvRemoved(key, metadata, object_id.tenant_id);
     accessor.Erase();
     return {};
 }
@@ -5572,86 +7446,133 @@ long MasterService::RemoveAll(bool force) {
     int64_t total_freed_size = 0;
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     auto now = std::chrono::system_clock::now();
+    // Tracking which tenants ended up empty costs a hash insert per visited
+    // object, so it is skipped entirely when nobody is listening for `cleared`.
+    const bool track_cleared_tenants =
+        KvEventsEnabled() || kv_track_tenant_epochs_;
+    // Baselines must be read before the scan starts, not at first sight of each
+    // tenant: a commit can land in a shard the scan already passed while the
+    // tenant is still unseen, and a per-tenant read would then fold that commit
+    // into its own baseline and wrongly conclude nothing raced.
+    const auto epoch_baseline = SnapshotKvTenantEpochs(track_cleared_tenants);
+    std::unordered_set<std::string> tenants_seen;
+    std::unordered_set<std::string> tenants_with_remaining_objects;
 
     // Since RemoveAll clears everything, signal ALL clients with a
-    // LocalDiskSegment to physically clear their SSD immediately.
+    // LocalSSD clients to physically clear their SSD immediately.
     // This lets client cleanup overlap with master metadata deletion.
-    {
-        ScopedLocalDiskSegmentAccess local_disk_segment_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        auto& client_local_disk_segment =
-            local_disk_segment_access.getClientLocalDiskSegment();
-        for (auto& [client_id, segment] : client_local_disk_segment) {
-            MutexLocker locker(&segment->offloading_mutex_);
-            segment->pending_remove_all = true;
-        }
-    }
+    local_ssd_manager_.RequestRemoveAll();
 
     // Delete metadata — runs concurrently with client SSD cleanup.
     for (size_t i = 0; i < kNumShards; i++) {
-        MetadataShardAccessorRW shard(this, i);
-        for (auto tenant_it = shard->tenants.begin();
-             tenant_it != shard->tenants.end();) {
-            auto& tenant_state = tenant_it->second;
-            auto it = tenant_state.metadata.begin();
-            while (it != tenant_state.metadata.end()) {
-                if ((force || it->second.IsLeaseExpired(now)) &&
-                    it->second.AllReplicas(&Replica::fn_is_completed) &&
-                    !tenant_state.replication_tasks.contains(it->first)) {
-                    auto mem_rep_count = it->second.CountReplicas(
-                        &Replica::fn_is_memory_replica);
-
-                    if (enable_ha_) {
-                        if (enable_oplog_) {
-                            auto reservation = ReserveBatchOpLogSlot();
-                            if (!reservation) {
-                                ++it;
-                                continue;
-                            }
-                            std::vector<ReplicaID> removed_ids;
-                            it->second.VisitReplicas(
-                                &Replica::fn_is_completed,
-                                [&removed_ids](Replica& replica) {
-                                    removed_ids.push_back(replica.id());
-                                    replica.mark_removed();
-                                });
-                            auto persist_result =
-                                AppendReservedOpLogWithDurableFinalize(
-                                    std::move(reservation.value()),
-                                    OpType::REMOVE, tenant_it->first.value(),
-                                    it->first, {},
-                                    [this,
-                                     removed_ids = std::move(removed_ids)](
-                                        const OpLogEntry& durable_entry) {
-                                        FinalizeRemovedReplicasAfterDurable(
-                                            durable_entry, removed_ids,
-                                            QuotaEraseMode::kFull);
+        // Scoped in a lambda so the shard lock is released before the hook
+        // runs; a hook that commits into shard i would otherwise deadlock.
+        auto scan_shard = [&] {
+            MetadataShardAccessorRW shard(this, i);
+            for (auto tenant_it = shard->tenants.begin();
+                 tenant_it != shard->tenants.end();) {
+                auto& tenant_state = tenant_it->second;
+                auto it = tenant_state.metadata.begin();
+                while (it != tenant_state.metadata.end()) {
+                    // Record the tenant only once the loop actually reaches an
+                    // object. A tenant row can outlive its objects, and
+                    // recording it unconditionally made every empty-but-present
+                    // tenant look like a fresh wipe and emit a spurious
+                    // `cleared`.
+                    if (track_cleared_tenants) {
+                        tenants_seen.insert(tenant_it->first.value());
+                    }
+                    if ((force || it->second.IsLeaseExpired(now)) &&
+                        it->second.AllReplicas(&Replica::fn_is_completed) &&
+                        !tenant_state.replication_tasks.contains(it->first)) {
+                        auto mem_rep_count = it->second.CountReplicas(
+                            &Replica::fn_is_memory_replica);
+
+                        if (enable_ha_) {
+                            if (enable_oplog_) {
+                                auto reservation = ReserveBatchOpLogSlot();
+                                if (!reservation) {
+                                    // Skipped, so the tenant is not empty.
+                                    if (track_cleared_tenants) {
+                                        tenants_with_remaining_objects.insert(
+                                            tenant_it->first.value());
+                                    }
+                                    ++it;
+                                    continue;
+                                }
+                                std::vector<ReplicaID> removed_ids;
+                                it->second.VisitReplicas(
+                                    &Replica::fn_is_completed,
+                                    [&removed_ids](Replica& replica) {
+                                        removed_ids.push_back(replica.id());
+                                        replica.mark_removed();
                                     });
-                            if (!persist_result) {
+                                auto persist_result =
+                                    AppendReservedOpLogWithDurableFinalize(
+                                        std::move(reservation.value()),
+                                        OpType::REMOVE,
+                                        tenant_it->first.value(), it->first, {},
+                                        [this,
+                                         removed_ids = std::move(removed_ids)](
+                                            const OpLogEntry& durable_entry) {
+                                            FinalizeRemovedReplicasAfterDurable(
+                                                durable_entry, removed_ids,
+                                                QuotaEraseMode::kFull);
+                                        });
+                                if (!persist_result) {
+                                    if (track_cleared_tenants) {
+                                        tenants_with_remaining_objects.insert(
+                                            tenant_it->first.value());
+                                    }
+                                    ++it;
+                                    continue;
+                                }
+                                total_freed_size +=
+                                    it->second.size * mem_rep_count;
                                 ++it;
+                                removed_count++;
                                 continue;
                             }
-                            total_freed_size += it->second.size * mem_rep_count;
-                            ++it;
-                            removed_count++;
-                            continue;
                         }
-                    }
 
-                    total_freed_size += it->second.size * mem_rep_count;
-                    ErasePromotionTaskIfPresent(tenant_state, it->first,
-                                                tenant_it->first);
-                    it = EraseMetadata(tenant_state, it, tenant_it->first,
-                                       QuotaEraseMode::kFull, &shard);
-                    removed_count++;
-                } else {
-                    ++it;
-                }
+                        total_freed_size += it->second.size * mem_rep_count;
+                        ErasePromotionTaskIfPresent(tenant_state, it->first);
+                        it = EraseMetadata(tenant_state, it, tenant_it->first,
+                                           QuotaEraseMode::kFull, &shard);
+                        removed_count++;
+                    } else {
+                        // Only a skipped object means the tenant is not empty.
+                        // Under HA+oplog the erase is deferred to the durable
+                        // callback, so a non-empty metadata map does not.
+                        if (track_cleared_tenants) {
+                            tenants_with_remaining_objects.insert(
+                                tenant_it->first.value());
+                        }
+                        ++it;
+                    }
+                }
+                if (tenant_state.Empty()) {
+                    tenant_it = shard->tenants.erase(tenant_it);
+                } else {
+                    ++tenant_it;
+                }
             }
-            if (tenant_state.Empty()) {
-                tenant_it = shard->tenants.erase(tenant_it);
-            } else {
-                ++tenant_it;
+        };
+        scan_shard();
+        if (kv_remove_all_shard_hook_) {
+            kv_remove_all_shard_hook_(i);
+        }
+    }
+
+    // tenants_seen holds only tenants that actually held an object, so this
+    // difference is "held objects and lost all of them" — a real wipe. Both
+    // sets stay empty unless track_cleared_tenants was set.
+    if (track_cleared_tenants) {
+        for (const auto& tenant : tenants_seen) {
+            if (!tenants_with_remaining_objects.contains(tenant)) {
+                PublishKvClearedIfEpochUnchanged(
+                    TenantId(tenant),
+                    epoch_baseline[KvTenantEpochSlot(tenant)]);
             }
         }
     }
@@ -5668,6 +7589,16 @@ long MasterService::RemoveAll(const TenantId& tenant_id, bool force) {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     auto now = std::chrono::system_clock::now();
     const TenantId& normalized_tenant = ResolveRequestTenantId(tenant_id);
+    // A `cleared` event means "this tenant is now empty". Deciding that from
+    // tenant_state.metadata being empty is wrong in both directions: a tenant
+    // that never existed looks empty, and under HA+oplog the erase is deferred
+    // to the durable callback so a full wipe still looks non-empty. Count what
+    // the loop actually did instead.
+    bool saw_any_object = false;
+    bool skipped_any_object = false;
+    // This overload knows its tenant up front, so the epoch can be read before
+    // the scan starts rather than at first sight of an object.
+    const uint64_t entry_epoch = ReadKvTenantEpoch(normalized_tenant.value());
 
     // For the tenant-scoped overload, only signal clients that own LOCAL_DISK
     // replicas of THIS tenant — clearing all clients would cross-delete other
@@ -5675,88 +7606,95 @@ long MasterService::RemoveAll(const TenantId& tenant_id, bool force) {
     std::unordered_set<UUID, boost::hash<UUID>> clients_with_disk_replicas;
 
     for (size_t i = 0; i < kNumShards; i++) {
-        MetadataShardAccessorRW shard(this, i);
-        auto tenant_it = shard->tenants.find(normalized_tenant);
-        if (tenant_it == shard->tenants.end()) {
-            continue;
-        }
-        auto& tenant_state = tenant_it->second;
-        auto it = tenant_state.metadata.begin();
-        while (it != tenant_state.metadata.end()) {
-            if ((force || it->second.IsLeaseExpired(now)) &&
-                it->second.AllReplicas(&Replica::fn_is_completed) &&
-                !tenant_state.replication_tasks.contains(it->first)) {
-                it->second.VisitReplicas(
-                    &Replica::fn_is_local_disk_replica,
-                    [&clients_with_disk_replicas](const Replica& replica) {
-                        auto cid = replica.get_local_disk_client_id();
-                        if (cid) {
-                            clients_with_disk_replicas.insert(*cid);
-                        }
-                    });
-                auto mem_rep_count =
-                    it->second.CountReplicas(&Replica::fn_is_memory_replica);
-                if (enable_ha_) {
-                    if (enable_oplog_) {
-                        auto reservation = ReserveBatchOpLogSlot();
-                        if (!reservation) {
-                            ++it;
-                            continue;
-                        }
-                        std::vector<ReplicaID> removed_ids;
-                        it->second.VisitReplicas(
-                            &Replica::fn_is_completed,
-                            [&removed_ids](Replica& replica) {
-                                removed_ids.push_back(replica.id());
-                                replica.mark_removed();
-                            });
-                        auto persist_result =
-                            AppendReservedOpLogWithDurableFinalize(
-                                std::move(reservation.value()), OpType::REMOVE,
-                                normalized_tenant.value(), it->first, {},
-                                [this, removed_ids = std::move(removed_ids)](
-                                    const OpLogEntry& durable_entry) {
-                                    FinalizeRemovedReplicasAfterDurable(
-                                        durable_entry, removed_ids,
-                                        QuotaEraseMode::kFull);
+        // Scoped in a lambda so the shard lock is released before the hook
+        // runs; a hook that commits into shard i would otherwise deadlock.
+        auto scan_shard = [&] {
+            MetadataShardAccessorRW shard(this, i);
+            auto tenant_it = shard->tenants.find(normalized_tenant);
+            if (tenant_it == shard->tenants.end()) {
+                return;
+            }
+            auto& tenant_state = tenant_it->second;
+            auto it = tenant_state.metadata.begin();
+            while (it != tenant_state.metadata.end()) {
+                saw_any_object = true;
+                if ((force || it->second.IsLeaseExpired(now)) &&
+                    it->second.AllReplicas(&Replica::fn_is_completed) &&
+                    !tenant_state.replication_tasks.contains(it->first)) {
+                    it->second.VisitReplicas(
+                        &Replica::fn_is_local_disk_replica,
+                        [&clients_with_disk_replicas](const Replica& replica) {
+                            auto cid = replica.get_local_disk_client_id();
+                            if (cid) {
+                                clients_with_disk_replicas.insert(*cid);
+                            }
+                        });
+                    auto mem_rep_count = it->second.CountReplicas(
+                        &Replica::fn_is_memory_replica);
+                    if (enable_ha_) {
+                        if (enable_oplog_) {
+                            auto reservation = ReserveBatchOpLogSlot();
+                            if (!reservation) {
+                                // Skipped, so this is not a wipe.
+                                skipped_any_object = true;
+                                ++it;
+                                continue;
+                            }
+                            std::vector<ReplicaID> removed_ids;
+                            it->second.VisitReplicas(
+                                &Replica::fn_is_completed,
+                                [&removed_ids](Replica& replica) {
+                                    removed_ids.push_back(replica.id());
+                                    replica.mark_removed();
                                 });
-                        if (!persist_result) {
+                            auto persist_result =
+                                AppendReservedOpLogWithDurableFinalize(
+                                    std::move(reservation.value()),
+                                    OpType::REMOVE, normalized_tenant.value(),
+                                    it->first, {},
+                                    [this,
+                                     removed_ids = std::move(removed_ids)](
+                                        const OpLogEntry& durable_entry) {
+                                        FinalizeRemovedReplicasAfterDurable(
+                                            durable_entry, removed_ids,
+                                            QuotaEraseMode::kFull);
+                                    });
+                            if (!persist_result) {
+                                skipped_any_object = true;
+                                ++it;
+                                continue;
+                            }
+                            total_freed_size += it->second.size * mem_rep_count;
                             ++it;
+                            removed_count++;
                             continue;
                         }
-                        total_freed_size += it->second.size * mem_rep_count;
-                        ++it;
-                        removed_count++;
-                        continue;
                     }
+                    total_freed_size += it->second.size * mem_rep_count;
+                    ErasePromotionTaskIfPresent(tenant_state, it->first);
+                    it = EraseMetadata(tenant_state, it, normalized_tenant,
+                                       QuotaEraseMode::kFull, &shard);
+                    removed_count++;
+                } else {
+                    skipped_any_object = true;
+                    ++it;
                 }
-                total_freed_size += it->second.size * mem_rep_count;
-                ErasePromotionTaskIfPresent(tenant_state, it->first,
-                                            normalized_tenant);
-                it = EraseMetadata(tenant_state, it, normalized_tenant,
-                                   QuotaEraseMode::kFull, &shard);
-                removed_count++;
-            } else {
-                ++it;
             }
-        }
-        if (tenant_state.Empty()) {
-            shard->tenants.erase(tenant_it);
+            if (tenant_state.Empty()) {
+                shard->tenants.erase(tenant_it);
+            }
+        };
+        scan_shard();
+        if (kv_remove_all_shard_hook_) {
+            kv_remove_all_shard_hook_(i);
         }
     }
 
-    if (!clients_with_disk_replicas.empty()) {
-        ScopedLocalDiskSegmentAccess local_disk_segment_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        auto& client_local_disk_segment =
-            local_disk_segment_access.getClientLocalDiskSegment();
-        for (const auto& client_id : clients_with_disk_replicas) {
-            auto seg_it = client_local_disk_segment.find(client_id);
-            if (seg_it != client_local_disk_segment.end()) {
-                MutexLocker locker(&seg_it->second->offloading_mutex_);
-                seg_it->second->pending_remove_all = true;
-            }
-        }
+    local_ssd_manager_.RequestRemoveAll(std::vector<UUID>(
+        clients_with_disk_replicas.begin(), clients_with_disk_replicas.end()));
+
+    if (saw_any_object && !skipped_any_object) {
+        PublishKvClearedIfEpochUnchanged(normalized_tenant, entry_epoch);
     }
 
     VLOG(1) << "action=remove_all_objects"
@@ -5781,13 +7719,14 @@ auto MasterService::BatchRemove(const std::vector<std::string>& keys,
         std::min(keys.size(), static_cast<size_t>(kNumShards)));
 
     for (size_t i = 0; i < keys.size(); ++i) {
-        size_t shard_idx = getMetadataShardIndex(normalized_tenant, keys[i]);
+        size_t shard_idx = getShardIndex(normalized_tenant, keys[i]);
         keys_by_shard[shard_idx].emplace_back(i, &keys[i]);
     }
 
+    std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
     std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
-
-    auto alive_clients = getAliveClientsSnapshot();
+    auto retaining_clients = GetRetainingClientIdsLocked();
+    client_lock.unlock();
 
     // Process each shard once, acquiring lock per shard
     for (auto& [shard_idx, key_group] : keys_by_shard) {
@@ -5815,7 +7754,7 @@ auto MasterService::BatchRemove(const std::vector<std::string>& keys,
 
             // Clean up stale replica handles (consistent with single Remove).
             auto cleanup_plan =
-                BuildStaleHandleCleanupPlan(it->second, alive_clients);
+                BuildStaleHandleCleanupPlan(it->second, retaining_clients);
             if (!cleanup_plan.removed_ids.empty()) {
                 auto persist_result = PersistStaleHandleCleanupForHA(
                     "BatchRemove(stale cleanup)", normalized_tenant, key,
@@ -5831,8 +7770,9 @@ auto MasterService::BatchRemove(const std::vector<std::string>& keys,
                             ? ErrorCode::OBJECT_NOT_FOUND
                             : ErrorCode::OBJECT_ALREADY_EXISTS);
                     continue;
-                } else if (CleanupStaleHandles(tenant_state, it->second,
-                                               alive_clients, &shard)) {
+                } else if (CleanupStaleHandles(key, normalized_tenant,
+                                               tenant_state, it->second,
+                                               retaining_clients, &shard)) {
                     EraseMetadata(tenant_state, it, normalized_tenant,
                                   QuotaEraseMode::kFull, &shard);
                     if (tenant_state.Empty()) {
@@ -5940,47 +7880,57 @@ void MasterService::CancelPromotionTaskForRemovedReplicas(
         source->dec_refcnt();
     }
     const UUID holder_id = task_it->second.holder_id;
-    ErasePromotionTaskIfPresent(tenant_state, metadata.user_key,
-                                metadata.tenant_id);
+    ErasePromotionTaskIfPresent(tenant_state, metadata.user_key);
 
     // Best-effort cleanup of a task that may still be queued on the holder.
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto segment_it = client_local_disk_segment.find(holder_id);
-    if (segment_it != client_local_disk_segment.end()) {
-        MutexLocker locker(&segment_it->second->offloading_mutex_);
-        segment_it->second->promotion_objects.erase(
-            metadata.tenant_id.MakeScopedKey(metadata.user_key));
-    }
+    local_ssd_manager_.RemovePromotion(holder_id, metadata.tenant_id,
+                                       metadata.user_key);
+}
+
+bool MasterService::CleanupStaleHandles(
+    const std::string& key, const TenantId& tenant_id,
+    TenantState& tenant_state, ObjectMetadata& metadata,
+    const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients,
+    MetadataShardAccessorRW* shard) {
+    // Removes replicas with invalid allocators (memory replicas on unmounted
+    // segments) and local_disk replicas whose owner no longer retains
+    // resources.
+    // Kept as a thin wrapper over the predicate form so the owner-targeted
+    // LOCAL_DISK sweep (ClearLocalDiskHandlesOwnedBy) shares this accounting
+    // rather than duplicating it.
+    return CleanupStaleHandles(
+        key, tenant_id, tenant_state, metadata,
+        [&retaining_clients](const Replica& replica) {
+            return (replica.has_invalid_mem_handle() ||
+                    replica.has_invalid_nof_handle() ||
+                    replica.has_stale_local_disk_client(retaining_clients)) &&
+                   replica.is_completed();
+        },
+        shard);
 }
 
 bool MasterService::CleanupStaleHandles(
+    const std::string& key, const TenantId& tenant_id,
     TenantState& tenant_state, ObjectMetadata& metadata,
-    const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients,
+    const std::function<bool(const Replica&)>& is_stale,
     MetadataShardAccessorRW* shard) {
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     bool had_completed_disk = metadata.HasReplica([](const Replica& r) {
         return r.is_local_disk_replica() && r.is_completed();
     });
-    // Remove those with invalid allocators (memory replicas on unmounted
-    // segments) and local_disk replicas whose owner client is no longer alive.
     const uint64_t before_charge = CompletedMemoryQuotaCharge(metadata);
     std::vector<ReplicaID> removed_replica_ids;
-    EraseReplicasWithCacheTotalAccounting(
-        metadata,
-        [&alive_clients](const Replica& replica) {
-            return (replica.has_invalid_mem_handle() ||
-                    replica.has_invalid_nof_handle() ||
-                    replica.has_stale_local_disk_client(alive_clients)) &&
-                   replica.is_completed();
-        },
-        &removed_replica_ids);
+    EraseReplicasWithCacheTotalAccounting(metadata, is_stale,
+                                          &removed_replica_ids);
     CancelPromotionTaskForRemovedReplicas(tenant_state, metadata,
                                           removed_replica_ids);
     const uint64_t after_charge = CompletedMemoryQuotaCharge(metadata);
-    if (before_charge > after_charge) {
-        ReleaseCommittedQuotaCharge(metadata, before_charge - after_charge);
+    if (enable_multi_tenants_ && before_charge > after_charge) {
+        auto release_result = metadata.quota_ledger.ReleaseCommitted(
+            GetBoundTenantQuotaHandle(tenant_state),
+            before_charge - after_charge);
+        LogTenantQuotaLedgerError(release_result, "release_committed",
+                                  metadata.tenant_id, metadata.user_key);
     }
     if (had_completed_disk && shard &&
         !metadata.HasReplica([](const Replica& r) {
@@ -5989,10 +7939,352 @@ bool MasterService::CleanupStaleHandles(
         shard->OnDiskReplicaRemoved(had_completed_disk, metadata);
     }
 
+    SyncKvObjectState(key, metadata, tenant_id, previous_kv_media);
+
     // Return true if no valid replicas remain after cleanup
     return !metadata.IsValid();
 }
 
+void MasterService::FreeDfsReplicas(const std::string& key,
+                                    const std::vector<Replica>& replicas) {
+    if (!dfs_allocator_) return;
+    for (const auto& replica : replicas) {
+        if (!replica.is_dfs_replica()) continue;
+        const auto& desc = replica.get_dfs_descriptor();
+        dfs_allocator_->Free(key, desc);
+    }
+}
+
+void MasterService::RunBucketDfsEviction() {
+    (void)RunBucketDfsEvictionInternal(false);
+}
+
+bool MasterService::TryRecoverDfsSpaceAfterAllocationFailure() {
+    if (bucket_allocator_ == nullptr ||
+        !bucket_allocator_->IsEvictionEnabled()) {
+        return false;
+    }
+    LOG(WARNING) << "DFS bucket allocation exhausted; forcing one validated "
+                    "whole-bucket eviction";
+    return RunBucketDfsEvictionInternal(true);
+}
+
+bool MasterService::RunBucketDfsEvictionInternal(bool force_one) {
+    if (bucket_allocator_ == nullptr) return false;
+    const size_t retried = bucket_allocator_->RetryFailedEvictions();
+    bool evicted = retried > 0;
+    if (force_one && retried > 0) return evicted;
+
+    const TenantId tenant_id = TenantId::Default();
+    std::set<int64_t> attempted;
+    while (true) {
+        auto pending =
+            force_one ? bucket_allocator_->PrepareEvictionForAllocationFailure()
+                      : bucket_allocator_->PrepareEviction();
+        if (pending.Empty()) return evicted;
+        if (!attempted.insert(pending.bucket_id()).second) {
+            bucket_allocator_->AbortEviction(std::move(pending));
+            return evicted;
+        }
+
+        const auto& candidates = pending.Candidates();
+        std::map<size_t, std::vector<size_t>> indexes_by_shard;
+        for (size_t i = 0; i < candidates.size(); ++i) {
+            indexes_by_shard[getShardIndex(tenant_id, candidates[i].key)]
+                .push_back(i);
+        }
+
+        auto matches_candidate =
+            [](const Replica& replica,
+               const DfsAllocatorInterface::EvictionCandidate& candidate) {
+                if (!replica.is_dfs_replica()) return false;
+                const auto& descriptor = replica.get_dfs_descriptor();
+                return descriptor.shard_idx == candidate.descriptor.shard_idx &&
+                       descriptor.offset == candidate.descriptor.offset &&
+                       descriptor.object_size ==
+                           candidate.descriptor.object_size &&
+                       descriptor.aligned_size ==
+                           candidate.descriptor.aligned_size &&
+                       descriptor.file_path == candidate.descriptor.file_path;
+            };
+
+        bool all_accepted = true;
+        ImmutableBucketAllocator::EvictedBucket evicted_bucket;
+        bool logical_committed = false;
+        {
+            std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+            std::vector<std::unique_ptr<SharedMutexLocker>> shard_locks;
+            shard_locks.reserve(indexes_by_shard.size());
+            // std::map iteration is ascending, giving every bucket eviction
+            // the same cross-shard lock order.
+            for (const auto& [shard_idx, indexes] : indexes_by_shard) {
+                (void)indexes;
+                shard_locks.emplace_back(std::make_unique<SharedMutexLocker>(
+                    &metadata_shards_[shard_idx].mutex));
+            }
+
+            auto now = std::chrono::system_clock::now();
+            for (const auto& [shard_idx, indexes] : indexes_by_shard) {
+                if (!all_accepted) break;
+                for (const size_t index : indexes) {
+                    const auto& candidate = candidates[index];
+                    auto tenant_it =
+                        metadata_shards_[shard_idx].tenants.find(tenant_id);
+                    if (tenant_it ==
+                        metadata_shards_[shard_idx].tenants.end()) {
+                        continue;
+                    }
+                    auto& tenant_state = tenant_it->second;
+                    auto metadata_it =
+                        tenant_state.metadata.find(candidate.key);
+                    if (metadata_it == tenant_state.metadata.end()) continue;
+                    auto& metadata = metadata_it->second;
+                    if (!metadata.HasReplica([&](const Replica& replica) {
+                            return matches_candidate(replica, candidate);
+                        })) {
+                        continue;
+                    }
+
+                    const bool processing =
+                        metadata.HasReplica([&](const Replica& replica) {
+                            return matches_candidate(replica, candidate) &&
+                                   replica.is_processing();
+                        });
+                    if (processing ||
+                        tenant_state.processing_keys.contains(candidate.key) ||
+                        metadata.IsHardPinned() ||
+                        !metadata.IsLeaseExpired(now) ||
+                        (IsSoftPinActive(metadata, now) &&
+                         !allow_evict_soft_pinned_objects_)) {
+                        all_accepted = false;
+                        break;
+                    }
+                }
+            }
+
+            if (all_accepted) {
+                auto logical = bucket_allocator_->CommitEvictionLogical(
+                    std::move(pending));
+                if (logical) {
+                    evicted_bucket = std::move(*logical);
+                    logical_committed = true;
+                } else {
+                    LOG(ERROR) << "DFS bucket eviction logical commit failed, "
+                                  "error="
+                               << logical.error();
+                }
+            }
+            if (logical_committed) {
+                for (const auto& [shard_idx, indexes] : indexes_by_shard) {
+                    for (const size_t index : indexes) {
+                        const auto& candidate = candidates[index];
+                        auto tenant_it =
+                            metadata_shards_[shard_idx].tenants.find(tenant_id);
+                        if (tenant_it ==
+                            metadata_shards_[shard_idx].tenants.end()) {
+                            continue;
+                        }
+                        auto& tenant_state = tenant_it->second;
+                        auto metadata_it =
+                            tenant_state.metadata.find(candidate.key);
+                        if (metadata_it == tenant_state.metadata.end()) {
+                            continue;
+                        }
+                        auto& metadata = metadata_it->second;
+                        const size_t erased =
+                            metadata.EraseReplicas([&](const Replica& replica) {
+                                return matches_candidate(replica, candidate);
+                            });
+                        if (erased > 0) {
+                            PublishKvRemovedAfterEvict(candidate.key, erased,
+                                                       "disk", metadata,
+                                                       tenant_id);
+                            if (!metadata.IsValid()) {
+                                EraseMetadata(tenant_state, metadata_it,
+                                              tenant_id, QuotaEraseMode::kFull);
+                            }
+                        }
+                    }
+                    auto tenant_it =
+                        metadata_shards_[shard_idx].tenants.find(tenant_id);
+                    if (tenant_it !=
+                            metadata_shards_[shard_idx].tenants.end() &&
+                        tenant_it->second.Empty()) {
+                        metadata_shards_[shard_idx].tenants.erase(tenant_it);
+                    }
+                }
+            }
+        }
+
+        if (!all_accepted) {
+            bucket_allocator_->AbortEviction(std::move(pending));
+            continue;
+        }
+        if (!logical_committed) {
+            bucket_allocator_->AbortEviction(std::move(pending));
+            continue;
+        }
+
+        auto deleted =
+            bucket_allocator_->DeleteEvictedBucket(std::move(evicted_bucket));
+        if (!deleted) {
+            LOG(ERROR) << "DFS bucket data deletion failed; capacity remains "
+                          "reserved for runtime retry, error="
+                       << deleted.error();
+            return evicted;
+        } else {
+            evicted = true;
+            if (force_one) return true;
+        }
+    }
+}
+
+void MasterService::RunDfsEviction() {
+    if (!dfs_allocator_) return;
+    if (bucket_allocator_ != nullptr) {
+        RunBucketDfsEviction();
+        return;
+    }
+    RunShardDfsEviction();
+}
+
+void MasterService::RunShardDfsEviction() {
+    if (!shard_allocator_) return;
+
+    const TenantId tenant_id = TenantId::Default();
+    using CandidateIdentity = std::tuple<std::string, int, uint64_t>;
+    std::set<CandidateIdentity> attempted;
+
+    while (true) {
+        auto pending = shard_allocator_->PrepareEviction();
+        if (pending.Empty()) return;
+
+        const auto candidates = pending.Candidates();
+        std::vector<bool> accepted(candidates.size(), false);
+        std::vector<bool> considered(candidates.size(), false);
+        bool saw_repeated_candidate = false;
+
+        // Group prepared candidates by metadata shard, then validate and
+        // remove each group while holding only that shard. Prepared allocator
+        // extents remain unavailable until ResolvePreparedEviction(), so
+        // different metadata shards do not need one cross-shard transaction.
+        std::array<std::vector<size_t>, kNumShards> indexes_by_shard;
+        for (size_t i = 0; i < candidates.size(); ++i) {
+            const auto& candidate = candidates[i];
+            if (!attempted
+                     .emplace(candidate.key, candidate.shard_idx,
+                              candidate.offset)
+                     .second) {
+                saw_repeated_candidate = true;
+                continue;
+            }
+            considered[i] = true;
+            indexes_by_shard[getShardIndex(tenant_id, candidate.key)].push_back(
+                i);
+        }
+
+        auto matches_candidate = [](const Replica& replica,
+                                    const auto& candidate) {
+            return replica.is_dfs_replica() &&
+                   replica.get_dfs_descriptor().shard_idx ==
+                       candidate.shard_idx &&
+                   replica.get_dfs_descriptor().offset == candidate.offset;
+        };
+
+        auto now = std::chrono::system_clock::now();
+        for (size_t shard_idx = 0; shard_idx < kNumShards; ++shard_idx) {
+            if (indexes_by_shard[shard_idx].empty()) continue;
+
+            std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+            SharedMutexLocker shard_lock(&metadata_shards_[shard_idx].mutex);
+
+            // Validate and remove candidates under the same shard lock. Once a
+            // candidate has been seen in this cycle, it is excluded above;
+            // encountering it again means the LRU scan has wrapped.
+            for (const size_t i : indexes_by_shard[shard_idx]) {
+                const auto& candidate = candidates[i];
+                auto tenant_it =
+                    metadata_shards_[shard_idx].tenants.find(tenant_id);
+                if (tenant_it == metadata_shards_[shard_idx].tenants.end()) {
+                    accepted[i] = true;
+                    continue;
+                }
+                auto& tenant_state = tenant_it->second;
+                auto metadata_it = tenant_state.metadata.find(candidate.key);
+                if (metadata_it == tenant_state.metadata.end()) {
+                    accepted[i] = true;
+                    continue;
+                }
+
+                auto& metadata = metadata_it->second;
+                const bool has_candidate =
+                    metadata.HasReplica([&](const Replica& replica) {
+                        return matches_candidate(replica, candidate);
+                    });
+                if (!has_candidate) {
+                    accepted[i] = true;
+                    continue;
+                }
+
+                const bool candidate_is_processing =
+                    metadata.HasReplica([&](const Replica& replica) {
+                        return matches_candidate(replica, candidate) &&
+                               replica.is_processing();
+                    });
+                accepted[i] =
+                    !candidate_is_processing &&
+                    !tenant_state.processing_keys.contains(candidate.key) &&
+                    !metadata.IsHardPinned() && metadata.IsLeaseExpired(now) &&
+                    (!IsSoftPinActive(metadata, now) ||
+                     allow_evict_soft_pinned_objects_);
+                if (!accepted[i]) continue;
+
+                // A missing descriptor was accepted above and is already
+                // evicted from the master's point of view. Otherwise remove
+                // the accepted descriptor before its allocator extent can be
+                // committed and reused.
+                const size_t erased =
+                    metadata.EraseReplicas([&](const Replica& replica) {
+                        return matches_candidate(replica, candidate) &&
+                               !replica.is_processing();
+                    });
+                if (erased > 0) {
+                    PublishKvRemovedAfterEvict(candidate.key, erased, "disk",
+                                               metadata, tenant_id);
+                    if (!metadata.IsValid()) {
+                        EraseMetadata(tenant_state, metadata_it, tenant_id,
+                                      QuotaEraseMode::kFull);
+                    }
+                }
+            }
+
+            auto tenant_it =
+                metadata_shards_[shard_idx].tenants.find(tenant_id);
+            if (tenant_it != metadata_shards_[shard_idx].tenants.end() &&
+                tenant_it->second.Empty()) {
+                metadata_shards_[shard_idx].tenants.erase(tenant_it);
+            }
+        }
+
+        shard_allocator_->ResolvePreparedEviction(std::move(pending), accepted);
+
+        // A protected allocation stays live, but moving it to the MRU side
+        // lets this cycle inspect colder candidates behind it. The attempted
+        // set bounds the scan when every remaining allocation is protected.
+        for (size_t i = 0; i < candidates.size(); ++i) {
+            if (considered[i] && !accepted[i]) {
+                shard_allocator_->UpdateAccess(candidates[i].key,
+                                               candidates[i].shard_idx,
+                                               candidates[i].offset);
+            }
+        }
+
+        if (saw_repeated_candidate) {
+            return;
+        }
+    }
+}
+
 size_t MasterService::GetKeyCount() const {
     size_t total = 0;
     for (size_t i = 0; i < kNumShards; i++) {
@@ -6006,23 +8298,24 @@ size_t MasterService::GetKeyCount() const {
 
 auto MasterService::Ping(const UUID& client_id)
     -> tl::expected<PingResponse, ErrorCode> {
-    ClientStatus client_status;
-    {
-        std::shared_lock<std::shared_mutex> lock(client_mutex_);
-        auto it = ok_client_.find(client_id);
-        if (it != ok_client_.end()) {
-            client_status = ClientStatus::OK;
-        } else {
-            client_status = ClientStatus::NEED_REMOUNT;
-        }
-    }
-    PodUUID pod_client_id = {client_id.first, client_id.second};
-    if (!client_ping_queue_.push(pod_client_id)) {
-        // Queue is full
-        LOG(ERROR) << "client_id=" << client_id
-                   << ", error=client_ping_queue_full";
-        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
-    }
+    std::shared_lock<std::shared_mutex> lock(client_mutex_);
+    const auto record_it = client_liveness_records_.find(client_id);
+    bool observation_accepted = false;
+    if (record_it != client_liveness_records_.end()) {
+        const auto observation =
+            record_it->second->Observe(ClientLivenessRecord::Clock::now());
+        observation_accepted =
+            observation != ClientLivenessObservation::REJECTED_OFFLINE;
+        if (observation == ClientLivenessObservation::RECOVERED_ACTIVE) {
+            MasterMetricManager::instance().client_liveness_recovered();
+            LOG(INFO) << "client_id=" << client_id
+                      << ", action=client_liveness_recovered, signal=ping";
+        }
+    }
+    const ClientStatus client_status =
+        observation_accepted && ok_client_.contains(client_id)
+            ? ClientStatus::OK
+            : ClientStatus::NEED_REMOUNT;
     return PingResponse(view_version_, client_status);
 }
 
@@ -6056,77 +8349,127 @@ auto MasterService::MountLocalDiskSegment(const UUID& client_id,
         LOG(ERROR) << "	The offload functionality is not enabled";
         return tl::make_unexpected(ErrorCode::UNABLE_OFFLOAD);
     }
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
-
-    auto err =
-        segment_access.MountLocalDiskSegment(client_id, enable_offloading);
-    if (err == ErrorCode::SEGMENT_ALREADY_EXISTS) {
-        // Return OK because this is an idempotent operation
-        return {};
-    } else if (err != ErrorCode::OK) {
+    std::unique_lock<std::shared_mutex> client_lock(client_mutex_);
+    auto [record_it, inserted] = client_liveness_records_.try_emplace(
+        client_id, std::make_shared<ClientLivenessRecord>(
+                       ClientLivenessRecord::Clock::now()));
+    const auto record = record_it->second;
+    if (inserted) {
+        MasterMetricManager::instance().client_liveness_record_created();
+    }
+    ErrorCode err = ErrorCode::INTERNAL_ERROR;
+    const auto observation =
+        record->ObserveAndRun(ClientLivenessRecord::Clock::now(), [&] {
+            std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+            err =
+                local_ssd_manager_.RegisterClient(client_id, enable_offloading);
+            return err == ErrorCode::OK ||
+                   err == ErrorCode::SEGMENT_ALREADY_EXISTS;
+        });
+    if (observation == ClientLivenessObservation::REJECTED_OFFLINE) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    if (err != ErrorCode::OK && err != ErrorCode::SEGMENT_ALREADY_EXISTS) {
+        if (inserted) {
+            client_liveness_records_.erase(client_id);
+            MasterMetricManager::instance().on_client_liveness_record_removed(
+                ClientLivenessState::ACTIVE);
+        }
         return tl::make_unexpected(err);
     }
-
-    // Notify the client monitor thread to start tracking this client's TTL.
-    // Without this, a client that only mounts a LOCAL_DISK segment (and
-    // doesn't ping) would be considered expired by ClientMonitorFunc, which
-    // would then clear all its LOCAL_DISK replicas.
-    PodUUID pod_client_id;
-    pod_client_id.first = client_id.first;
-    pod_client_id.second = client_id.second;
-    if (!client_ping_queue_.push(pod_client_id)) {
-        LOG(ERROR) << "client_id=" << client_id
-                   << ", error=client_ping_queue_full";
-        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    if (observation == ClientLivenessObservation::RECOVERED_ACTIVE) {
+        MasterMetricManager::instance().client_liveness_recovered();
+        LOG(INFO) << "client_id=" << client_id
+                  << ", action=client_liveness_recovered, "
+                     "signal=local_disk_mount";
     }
 
     return {};
 }
 
-auto MasterService::OffloadObjectHeartbeat(const UUID& client_id,
+auto MasterService::UnmountLocalDiskSegment(const UUID& client_id)
+    -> tl::expected<void, ErrorCode> {
+    if (!enable_offload_) {
+        LOG(ERROR) << "The offload functionality is not enabled";
+        return tl::make_unexpected(ErrorCode::UNABLE_OFFLOAD);
+    }
+
+    // Drop the client's LOCAL_DISK registration first: from here on
+    // OffloadObjectHeartbeat answers SEGMENT_NOT_FOUND, so the master hands
+    // this client no further offload work. Then sweep the replicas it still
+    // owns, so no reader can be given a replica whose owner is about to stop
+    // serving. The sweep walks every metadata shard, so it must run without
+    // the registry lock held -- the same order and the same reason as the
+    // expiry branch of ClientMonitorFunc.
+    //
+    // The deregistration takes snapshot_mutex_ exclusively.
+    // NotifyOffloadSuccess admits a disk-replica registration by checking
+    // this client's registration inside one shared-lock section together with
+    // the metadata write, so that section lands entirely before this
+    // deregistration (the sweep below erases the replica) or entirely after
+    // (the check refuses it). Without the exclusive lock a registration
+    // admitted against the old one could land in a shard the sweep had
+    // already passed and survive as a stale owner.
+    std::optional<int64_t> reported_capacity;
+    {
+        std::unique_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+        reported_capacity = local_ssd_manager_.UnregisterClient(client_id);
+    }
+    if (!reported_capacity) {
+        // Idempotent, the same way MountLocalDiskSegment treats an
+        // already-mounted segment as success.
+        return {};
+    }
+    if (*reported_capacity > 0) {
+        MasterMetricManager::instance().dec_total_file_capacity(
+            *reported_capacity);
+    }
+
+    // Sweep exactly this owner's replicas. Deliberately not a
+    // liveness-complement sweep (ClearInvalidHandles with a staying set):
+    // that classifies by absence from a point-in-time snapshot, so an owner
+    // that mounts and registers after the snapshot but before the sweep
+    // reaches its shard would have its replicas classified stale and
+    // erased -- and when that disk replica was the key's only one, the key
+    // itself. An owner-id predicate cannot misclassify a concurrent mount,
+    // whatever the interleaving.
+    ClearLocalDiskHandlesOwnedBy(client_id);
+
+    LOG(INFO) << "client_id=" << client_id
+              << ", action=unmount_local_disk_segment_by_request";
+    return {};
+}
+
+bool MasterService::HasMountedLocalDiskSegment(const UUID& client_id) {
+    return local_ssd_manager_.GetUsage(client_id).has_value();
+}
+
+auto MasterService::OffloadObjectHeartbeat(const UUID& client_id,
                                            bool enable_offloading)
     -> tl::expected<std::vector<OffloadTaskItem>, ErrorCode> {
+    const auto record = FindClientRecord(client_id);
+    auto serving_guard =
+        record ? record->TryAcquireServingGuard() : std::nullopt;
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto local_disk_segment_it = client_local_disk_segment.find(client_id);
-    if (local_disk_segment_it == client_local_disk_segment.end()) {
+    auto pending = local_ssd_manager_.SetOffloadingAndTakePending(
+        client_id, enable_offloading);
+    if (!pending) {
         LOG(ERROR) << "Local disk segment not found with client id = "
                    << client_id;
-        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+        return tl::make_unexpected(pending.error());
     }
-    std::vector<OffloadTaskItem> result;
-    std::unordered_map<std::string, OffloadTaskItem> offloading_objects_copy;
-    {
-        MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
-        local_disk_segment_it->second->enable_offloading = enable_offloading;
-        if (enable_offloading) {
-            result.reserve(
-                local_disk_segment_it->second->offloading_objects.size());
-            for (const auto& [_, task] :
-                 local_disk_segment_it->second->offloading_objects) {
-                result.push_back(task);
-            }
-            local_disk_segment_it->second->offloading_objects.clear();
-            return result;
-        }
-        // Offloading is disabled: clear the pending queue to prevent
-        // unbounded growth that would trigger KEYS_ULTRA_LIMIT in
-        // PushOffloadingQueue. We must also clean up corresponding
-        // offloading_tasks and decrement source replica refcounts to avoid
-        // resource leaks and blocked writes (OBJECT_HAS_REPLICATION_TASK).
-        // Copy keys out before releasing the mutex to avoid lock order
-        // violation: the lock order is Shard Lock -> offloading_mutex_, so we
-        // must release offloading_mutex_ before taking shard locks via
-        // MetadataAccessorRW.
-        offloading_objects_copy =
-            std::move(local_disk_segment_it->second->offloading_objects);
-    }
-
-    for (auto& [_, task] : offloading_objects_copy) {
+    if (enable_offloading) {
+        return std::move(*pending);
+    }
+    // Offloading is disabled: clear the pending queue to prevent unbounded
+    // growth that would trigger KEYS_ULTRA_LIMIT in PushOffloadingQueue. We
+    // must also clean up corresponding offloading_tasks and decrement source
+    // replica refcounts to avoid resource leaks and blocked writes
+    // (OBJECT_HAS_REPLICATION_TASK).
+    for (auto& task : *pending) {
         const auto object_id =
             MakeObjectIdentity(task.key, TenantId(task.tenant_id));
         MetadataAccessorRW accessor(this, object_id);
@@ -6144,27 +8487,13 @@ auto MasterService::OffloadObjectHeartbeat(const UUID& client_id,
             }
         }
     }
-    return result;
+    return std::vector<OffloadTaskItem>{};
 }
 
 auto MasterService::PollRemoveAll(const UUID& client_id)
     -> tl::expected<bool, ErrorCode> {
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto local_disk_segment_it = client_local_disk_segment.find(client_id);
-    if (local_disk_segment_it == client_local_disk_segment.end()) {
-        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
-    }
-    bool result;
-    {
-        MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
-        result = local_disk_segment_it->second->pending_remove_all;
-        local_disk_segment_it->second->pending_remove_all = false;
-    }
-    return result;
+    return local_ssd_manager_.ConsumeRemoveAll(client_id);
 }
 
 auto MasterService::ReportSsdCapacity(const UUID& client_id,
@@ -6173,23 +8502,24 @@ auto MasterService::ReportSsdCapacity(const UUID& client_id,
     if (ssd_total_capacity_bytes < 0) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto local_disk_segment_it = client_local_disk_segment.find(client_id);
-    if (local_disk_segment_it == client_local_disk_segment.end()) {
-        LOG(ERROR) << "Local disk segment not found with client id = "
-                   << client_id;
-        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    auto capacity =
+        local_ssd_manager_.ReportCapacity(client_id, ssd_total_capacity_bytes);
+    if (!capacity) {
+        if (capacity.error() == ErrorCode::SEGMENT_NOT_FOUND) {
+            LOG(ERROR) << "Local disk segment not found with client id = "
+                       << client_id;
+        }
+        return tl::make_unexpected(capacity.error());
     }
-    MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
-    int64_t old_capacity =
-        local_disk_segment_it->second->ssd_total_capacity_bytes;
+    int64_t old_capacity = capacity->previous_bytes;
     if (ssd_total_capacity_bytes != old_capacity) {
-        local_disk_segment_it->second->ssd_total_capacity_bytes =
-            ssd_total_capacity_bytes;
         if (old_capacity > 0) {
             MasterMetricManager::instance().dec_total_file_capacity(
                 old_capacity);
@@ -6209,16 +8539,17 @@ auto MasterService::NotifyOffloadSuccess(
     if (tasks.size() != metadatas.size()) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    std::shared_ptr<LocalDiskSegment> local_disk_segment;
-    {
-        ScopedLocalDiskSegmentAccess ssd_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        auto& client_segments = ssd_access.getClientLocalDiskSegment();
-        auto disk_it = client_segments.find(client_id);
-        if (disk_it != client_segments.end()) {
-            local_disk_segment = disk_it->second;
-        }
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
+    // Set when an entry's replica registration is refused because the client
+    // no longer has a LOCAL_DISK segment entry (see the per-entry checks
+    // below). NACK cleanups still run for the rest of the batch; the caller
+    // gets SEGMENT_NOT_FOUND so a rescan stops re-registering.
+    bool refused_unmounted = false;
 
     for (size_t i = 0; i < tasks.size(); ++i) {
         const auto& task = tasks[i];
@@ -6245,20 +8576,41 @@ auto MasterService::NotifyOffloadSuccess(
                         source->dec_refcnt();
                     }
                     tenant_state.offloading_tasks.erase(task_it);
+                    MasterMetricManager::instance().inc_offload_failed(
+                        UuidToString(client_id));
                 }
             }
             continue;
         }
 
         Replica replica(client_id, metadata.data_size,
-                        metadata.transport_endpoint, ReplicaStatus::COMPLETE);
+                        metadata.transport_endpoint, ReplicaStatus::COMPLETE,
+                        record);
         bool handled_existing_object = false;
         bool added_new_local_disk_replica = false;
         {
             std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+            // A disk replica may only be registered for a client whose
+            // LOCAL_DISK segment entry still exists. Checked inside this
+            // shared-lock section, before the shard lock, so the check and
+            // the write below cannot straddle UnmountLocalDiskSegment's
+            // removal (which holds snapshot_mutex_ exclusively): either the
+            // replica lands first and its sweep erases it, or the check here
+            // sees the segment gone and refuses. Without this, a
+            // registration racing a deregistration -- an in-flight rescan
+            // batch, or an offload completion from a heartbeat that was past
+            // its own drain check -- could land after the sweep and leave
+            // the master advertising a departed owner. Scoped to
+            // enable_offload_, where the segment registry exists and a
+            // deregistration can race; with the subsystem off both the mount
+            // and unmount RPCs refuse, so there is nothing to check against
+            // and no race to close.
+            const bool segment_mounted =
+                !enable_offload_ || HasMountedLocalDiskSegment(client_id);
             MetadataAccessorRW accessor(this, request_object_id);
             if (accessor.Exists()) {
                 auto& obj_metadata = accessor.Get();
+                const auto previous_kv_media = KvMediaSnapshot(obj_metadata);
                 auto& tenant_state = accessor.GetTenantState();
                 auto task_it = tenant_state.offloading_tasks.find(
                     request_object_id.user_key);
@@ -6280,14 +8632,20 @@ auto MasterService::NotifyOffloadSuccess(
                     }
                     tenant_state.offloading_tasks.erase(task_it);
 
-                    if (!obj_metadata.HasReplica(
-                            &Replica::fn_is_local_disk_replica)) {
+                    if (!segment_mounted) {
+                        // The offload bookkeeping above still ran; only the
+                        // registration is refused.
+                        refused_unmounted = true;
+                    } else if (!obj_metadata.HasReplica(
+                                   &Replica::fn_is_local_disk_replica)) {
                         std::vector<Replica> replicas;
                         replicas.emplace_back(std::move(replica));
                         obj_metadata.AddReplicas(std::move(replicas));
                         auto& shard = accessor.GetShard();
                         shard.OnDiskReplicaAdded(obj_metadata);
                         SyncCacheTotalAccounting(obj_metadata);
+                        MasterMetricManager::instance().inc_offload_completed(
+                            UuidToString(client_id));
                         added_new_local_disk_replica = true;
                     } else {
                         obj_metadata.VisitReplicas(
@@ -6313,6 +8671,9 @@ auto MasterService::NotifyOffloadSuccess(
                             });
                     }
                     handled_existing_object = true;
+                    SyncKvObjectState(request_object_id.user_key, obj_metadata,
+                                      request_object_id.tenant_id,
+                                      previous_kv_media);
                 }
             }
         }
@@ -6327,12 +8688,19 @@ auto MasterService::NotifyOffloadSuccess(
                 std::move(normalized_tenant_result.value()),
                 request_object_id.user_key};
 
-            auto res = AddReplica(client_id, object_id.user_key,
-                                  object_id.tenant_id, replica);
+            auto res = AddReplicaForRetainedClient(
+                client_id, object_id.user_key, object_id.tenant_id, replica);
             if (!res) {
                 if (res.error() == ErrorCode::OBJECT_NOT_FOUND) {
                     continue;
                 }
+                if (res.error() == ErrorCode::SEGMENT_NOT_FOUND) {
+                    // AddReplica's own mounted-segment check refused it (the
+                    // segment entry vanished under a deregistration). Finish
+                    // the batch so remaining NACK cleanups still run.
+                    refused_unmounted = true;
+                    continue;
+                }
                 LOG(ERROR) << "Failed to add replica: error=" << res.error()
                            << ", client_id=" << client_id
                            << ", tenant_id=" << object_id.tenant_id.value()
@@ -6341,98 +8709,169 @@ auto MasterService::NotifyOffloadSuccess(
             }
             added_new_local_disk_replica = res.value();
         }
-        if (local_disk_segment && metadata.data_size > 0 &&
-            added_new_local_disk_replica) {
-            local_disk_segment->ssd_used_bytes.fetch_add(
-                metadata.data_size, std::memory_order_relaxed);
+        if (metadata.data_size > 0 && added_new_local_disk_replica) {
+            local_ssd_manager_.AdjustUsedBytes(client_id, metadata.data_size);
         }
     }
 
+    if (refused_unmounted) {
+        LOG(WARNING) << "client_id=" << client_id
+                     << ", action=notify_offload_success_refused"
+                     << ", error=no_local_disk_segment";
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
     return {};
 }
 
 tl::expected<void, ErrorCode> MasterService::PushOffloadingQueue(
-    const ObjectIdentity& object_id, Replica& replica) {
+    const ObjectIdentity& object_id, Replica& replica,
+    std::vector<UUID>* mirror_clients) {
     const auto& segment_names = replica.get_segment_names();
-    if (segment_names.empty()) {
-        return {};
+    // No source segment names means there is no usable source segment to
+    // offload from. Returning a silent {} here caused the caller to record an
+    // OffloadingTask + inc_refcnt for work that was never enqueued, leaking the
+    // refcount until TTL expiry (issue #2997). Return an explicit
+    // UNABLE_OFFLOADING so callers treat this as a no-op rather than a success.
+    if (segment_names.empty() ||
+        std::none_of(segment_names.begin(), segment_names.end(),
+                     [](const auto& name) { return name.has_value(); })) {
+        return tl::make_unexpected(ErrorCode::UNABLE_OFFLOADING);
+    }
+    Replica::Descriptor source_descriptor;
+    if (!TryGetReadableReplicaDescriptor(replica, source_descriptor) ||
+        !source_descriptor.is_memory_replica()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    bool any_enqueued = false;
+    std::string client_id_str;
+    const auto liveness = replica.getClientLiveness();
+    if (!liveness) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
     for (const auto& segment_name_it : segment_names) {
         if (!segment_name_it.has_value()) {
             continue;
         }
-        ScopedLocalDiskSegmentAccess local_disk_segment_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        const auto& client_by_name =
-            local_disk_segment_access.getClientByName();
-        auto client_id_it = client_by_name.find(segment_name_it.value());
-        if (client_id_it == client_by_name.end()) {
-            return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+        std::optional<UUID> client_id;
+        {
+            auto allocator_access = segment_manager_.getAllocatorAccess();
+            client_id =
+                allocator_access.GetOwnerClientId(segment_name_it.value());
         }
-        auto& client_local_disk_segment =
-            local_disk_segment_access.getClientLocalDiskSegment();
-        auto local_disk_segment_it =
-            client_local_disk_segment.find(client_id_it->second);
-        if (local_disk_segment_it == client_local_disk_segment.end()) {
-            return tl::make_unexpected(ErrorCode::UNABLE_OFFLOADING);
+        if (!client_id) {
+            return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
         }
-        MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
-        if (!local_disk_segment_it->second->enable_offloading) {
-            return tl::make_unexpected(ErrorCode::UNABLE_OFFLOADING);
+        // Callers hold the source metadata shard. This serving observation is
+        // the admission point; terminal cleanup must acquire the same shard
+        // before it can remove the source or unregister the destination.
+        if (!liveness->IsServing()) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
         }
-        if (local_disk_segment_it->second->offloading_objects.size() >=
-            offloading_queue_limit_) {
-            return tl::make_unexpected(ErrorCode::KEYS_ULTRA_LIMIT);
+        auto allocator_access = segment_manager_.getAllocatorAccess();
+        const auto current_owner =
+            allocator_access.GetOwnerClientId(segment_name_it.value());
+        if (!current_owner || *current_owner != *client_id ||
+            !TryGetReadableReplicaDescriptor(replica, source_descriptor)) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
         }
-        const int64_t size = replica.get_descriptor()
-                                 .get_memory_descriptor()
-                                 .buffer_descriptor.size_;
-        auto res = local_disk_segment_it->second->offloading_objects.emplace(
-            object_id.tenant_id.MakeScopedKey(object_id.user_key),
+        const int64_t size =
+            source_descriptor.get_memory_descriptor().buffer_descriptor.size_;
+        auto err = local_ssd_manager_.EnqueueOffload(
+            *client_id,
             OffloadTaskItem{.tenant_id = object_id.tenant_id.value(),
                             .key = object_id.user_key,
-                            .size = size});
-        if (!res.second) {
-            return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+                            .size = size},
+            offloading_queue_limit_);
+        if (err == ErrorCode::SEGMENT_NOT_FOUND) {
+            return tl::make_unexpected(ErrorCode::UNABLE_OFFLOADING);
+        }
+        if (err != ErrorCode::OK) {
+            if (err == ErrorCode::KEYS_ULTRA_LIMIT) {
+                MasterMetricManager::instance().inc_offload_enqueue_rejected(
+                    UuidToString(*client_id));
+            }
+            return tl::make_unexpected(err);
+        }
+        if (mirror_clients != nullptr) {
+            mirror_clients->push_back(*client_id);
         }
+        client_id_str = UuidToString(*client_id);
+        any_enqueued = true;
     }
+    // Every segment name was nullopt (or EnqueueOffload found no usable
+    // segment), so nothing was enqueued. Same invariant as the empty case:
+    // never report success when no task was actually submitted.
+    if (!any_enqueued) {
+        return tl::make_unexpected(ErrorCode::UNABLE_OFFLOADING);
+    }
+    MasterMetricManager::instance().inc_offload_enqueued(client_id_str);
     return {};
 }
 
+bool MasterService::CancelQueuedOffloadTask(TenantState& tenant_state,
+                                            ObjectMetadata& metadata,
+                                            const ObjectIdentity& object_id) {
+    auto task_it = tenant_state.offloading_tasks.find(object_id.user_key);
+    if (task_it == tenant_state.offloading_tasks.end()) {
+        return true;
+    }
+    const auto& mirror_clients = task_it->second.mirror_clients;
+    if (mirror_clients.empty()) {
+        return false;
+    }
+
+    if (!local_ssd_manager_.CancelOffloadsIfAllPending(
+            mirror_clients, object_id.tenant_id, object_id.user_key)) {
+        return false;
+    }
+
+    auto source = metadata.GetReplicaByID(task_it->second.source_id);
+    if (source != nullptr) {
+        source->dec_refcnt();
+    }
+    MasterMetricManager::instance().inc_offload_cancelled(
+        UuidToString(mirror_clients[0]));
+    tenant_state.offloading_tasks.erase(task_it);
+    return true;
+}
+
 // Promotion-on-hit
 
-// Push a key onto the holder client's promotion_objects map. Resolves the
-// holder via the LOCAL_DISK replica's embedded client_id rather than via
-// the segment-name reverse lookup.
+// Push a key into the holder client's promotion mailbox. Resolve the holder
+// via the LOCAL_DISK replica's embedded client_id rather than via the
+// segment-name reverse lookup.
 tl::expected<void, ErrorCode> MasterService::PushPromotionQueue(
     const ObjectIdentity& object_id, Replica& source_replica) {
     auto holder_id = source_replica.get_local_disk_client_id();
     if (!holder_id.has_value()) {
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto local_disk_segment_it =
-        client_local_disk_segment.find(holder_id.value());
-    if (local_disk_segment_it == client_local_disk_segment.end()) {
-        // Holder client expired or never had a LocalDiskSegment registered;
+    const auto liveness = source_replica.getClientLiveness();
+    if (!liveness) {
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    // TryPushPromotionQueue holds the source metadata shard, which orders a
+    // concurrently accepted enqueue before terminal cleanup.
+    if (!liveness->IsServing()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    auto err = local_ssd_manager_.EnqueuePromotion(
+        *holder_id, PromotionTaskItem{.tenant_id = object_id.tenant_id.value(),
+                                      .key = object_id.user_key,
+                                      .size = static_cast<int64_t>(
+                                          source_replica.get_descriptor()
+                                              .get_local_disk_descriptor()
+                                              .object_size)});
+    if (err == ErrorCode::SEGMENT_NOT_FOUND) {
+        // Holder client expired or never registered LocalSSD;
         // the LOCAL_DISK replica will be cleaned up by ClientMonitorFunc on
         // its own schedule.
         return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
     }
-    MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
-    auto res = local_disk_segment_it->second->promotion_objects.emplace(
-        object_id.tenant_id.MakeScopedKey(object_id.user_key),
-        PromotionTaskItem{
-            .tenant_id = object_id.tenant_id.value(),
-            .key = object_id.user_key,
-            .size = static_cast<int64_t>(source_replica.get_descriptor()
-                                             .get_local_disk_descriptor()
-                                             .object_size)});
-    if (!res.second) {
-        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+    if (err != ErrorCode::OK) {
+        return tl::make_unexpected(err);
     }
     return {};
 }
@@ -6458,7 +8897,7 @@ void MasterService::EraseCandidate(TenantState& tenant_state,
 
 void MasterService::EraseCandidate(const ObjectIdentity& object_id) {
     MetadataShardAccessorRW shard(
-        this, getMetadataShardIndex(object_id.tenant_id, object_id.user_key));
+        this, getShardIndex(object_id.tenant_id, object_id.user_key));
     auto tenant_it = shard->tenants.find(object_id.tenant_id);
     if (tenant_it == shard->tenants.end()) return;
     EraseCandidate(tenant_it->second, object_id.user_key);
@@ -6471,12 +8910,16 @@ void MasterService::RecordOrUpdateCandidate(TenantState& tenant_state,
                                             const std::string& key,
                                             uint8_t sketch_score,
                                             PromotionCandidateReason reason,
-                                            ErrorCode last_error) {
+                                            ErrorCode last_error,
+                                            uint32_t execution_failures) {
     const auto now = std::chrono::steady_clock::now();
     auto it = tenant_state.promotion_candidates.find(key);
     if (it != tenant_state.promotion_candidates.end()) {
         // Update existing entry: refresh last_seen, reset
-        // retry_after/retry_count.
+        // retry_after/retry_count. execution_failures is intentionally NOT
+        // updated here: a read refresh is new demand signal and may extend
+        // the budget, but it must not erase the failure history of this
+        // admission chain.
         it->second.last_seen = now;
         it->second.last_reason = reason;
         it->second.last_error = last_error;
@@ -6510,7 +8953,8 @@ void MasterService::RecordOrUpdateCandidate(TenantState& tenant_state,
                                 .retry_after = now,
                                 .last_reason = reason,
                                 .last_error = last_error,
-                                .retry_count = 0});
+                                .retry_count = 0,
+                                .execution_failures = execution_failures});
     if (inserted) {
         MasterMetricManager::instance().inc_promotion_candidate_recorded();
         VLOG(1) << "promotion_candidate_recorded key=" << key;
@@ -6541,7 +8985,7 @@ void MasterService::BackoffCandidate(const ObjectIdentity& object_id,
                                      PromotionQueueResult result) {
     const auto now = std::chrono::steady_clock::now();
     MetadataShardAccessorRW shard(
-        this, getMetadataShardIndex(object_id.tenant_id, object_id.user_key));
+        this, getShardIndex(object_id.tenant_id, object_id.user_key));
     auto tenant_it = shard->tenants.find(object_id.tenant_id);
     if (tenant_it == shard->tenants.end()) return;
     auto& tenant_state = tenant_it->second;
@@ -6594,152 +9038,758 @@ size_t MasterService::RunPromotionCandidateRetry() {
     return RunPromotionCandidateRetry(kPromotionRetryShardBatch);
 }
 
-size_t MasterService::RunPromotionCandidateRetryForTesting() {
-    return RunPromotionCandidateRetry(kNumShards);
+size_t MasterService::RunPromotionCandidateRetry(size_t max_shards_to_scan) {
+    if (!promotion_on_hit_ ||
+        promotion_candidate_count_.load(std::memory_order_relaxed) == 0) {
+        return 0;
+    }
+
+    const auto now = std::chrono::steady_clock::now();
+    std::vector<ObjectIdentity> due_candidates;
+    due_candidates.reserve(kPromotionRetryBatchSize);
+
+    const size_t shards_to_scan = std::min(max_shards_to_scan, kNumShards);
+    if (shards_to_scan == 0) return 0;
+    const size_t start_shard = promotion_retry_cursor_.fetch_add(
+                                   shards_to_scan, std::memory_order_relaxed) %
+                               kNumShards;
+
+    {
+        std::shared_lock<std::shared_mutex> snap_lock(snapshot_mutex_);
+        for (size_t scanned = 0;
+             scanned < shards_to_scan &&
+             due_candidates.size() < kPromotionRetryBatchSize;
+             ++scanned) {
+            const size_t i = (start_shard + scanned) % kNumShards;
+            MetadataShardAccessorRW shard(this, i);
+            for (auto tenant_it = shard->tenants.begin();
+                 tenant_it != shard->tenants.end() &&
+                 due_candidates.size() < kPromotionRetryBatchSize;) {
+                auto& tenant_state = tenant_it->second;
+                for (auto cit = tenant_state.promotion_candidates.begin();
+                     cit != tenant_state.promotion_candidates.end() &&
+                     due_candidates.size() < kPromotionRetryBatchSize;) {
+                    const auto& key = cit->first;
+                    auto& c = cit->second;
+
+                    const bool ttl_expired =
+                        now - c.last_seen >= kPromotionCandidateTtl;
+                    if (ttl_expired ||
+                        c.retry_count >= kPromotionCandidateMaxRetries) {
+                        VLOG(1) << "promotion_candidate_expired key=" << key
+                                << " retry_count=" << c.retry_count;
+                        const uint32_t saved_retry_count = c.retry_count;
+                        cit = tenant_state.promotion_candidates.erase(cit);
+                        DecrementCandidateCount();
+                        // retry_count == 0: scheduler never reached this
+                        // candidate before TTL elapsed — scan budget was
+                        // too small. retry_count > 0: scheduler evaluated
+                        // it but gave up after retries or TTL.
+                        if (saved_retry_count == 0) {
+                            MasterMetricManager::instance()
+                                .inc_promotion_candidate_expired_unevaluated();
+                        } else {
+                            MasterMetricManager::instance()
+                                .inc_promotion_candidate_expired_evaluated();
+                        }
+                        continue;
+                    }
+                    if (c.retry_after > now) {
+                        ++cit;
+                        continue;
+                    }
+
+                    // Quick pre-filter under shard lock to avoid adding
+                    // candidates that are obviously ineligible.
+                    auto meta_it = tenant_state.metadata.find(key);
+                    if (meta_it == tenant_state.metadata.end() ||
+                        !meta_it->second.IsValid() ||
+                        tenant_state.processing_keys.count(key) > 0 ||
+                        tenant_state.promotion_tasks.count(key) > 0 ||
+                        meta_it->second.HasReplica(
+                            &Replica::fn_is_memory_replica) ||
+                        !meta_it->second.HasReplica(
+                            &Replica::fn_is_local_disk_replica)) {
+                        cit = tenant_state.promotion_candidates.erase(cit);
+                        DecrementCandidateCount();
+                        continue;
+                    }
+
+                    due_candidates.push_back(ObjectIdentity{
+                        .tenant_id = tenant_it->first, .user_key = key});
+                    ++cit;
+                }
+
+                if (tenant_state.Empty()) {
+                    tenant_it = shard->tenants.erase(tenant_it);
+                } else {
+                    ++tenant_it;
+                }
+            }
+        }
+    }
+
+    size_t queued = 0;
+    {
+        std::shared_lock<std::shared_mutex> snap_lock(snapshot_mutex_);
+        for (const auto& object_id : due_candidates) {
+            const auto result =
+                TryPushPromotionQueue(object_id, /*record_candidate=*/false);
+            if (result == PromotionQueueResult::kQueued) {
+                queued++;
+                MasterMetricManager::instance()
+                    .inc_promotion_candidate_admitted();
+            } else if (IsTransientResult(result)) {
+                MasterMetricManager::instance()
+                    .inc_promotion_candidate_admission_rejected();
+                BackoffCandidate(object_id, result);
+            } else {
+                EraseCandidate(object_id);
+            }
+        }
+    }
+
+    return queued;
+}
+
+bool MasterService::DynamicReplicationEnabled() const {
+    return dynamic_replication_mode_ != DynamicReplicationMode::kOff;
+}
+
+uint64_t MasterService::DynamicReplicationStableScore(
+    const std::string& key, const std::string& segment) {
+    uint64_t hash = 1469598103934665603ULL;
+    auto mix = [&hash](std::string_view value) {
+        for (const unsigned char c : value) {
+            hash ^= c;
+            hash *= 1099511628211ULL;
+        }
+        hash ^= 0xff;
+        hash *= 1099511628211ULL;
+    };
+    mix(key);
+    mix(segment);
+    return hash;
+}
+
+bool MasterService::DynamicReplicationEnforce() const {
+    return dynamic_replication_mode_ == DynamicReplicationMode::kEnforce;
+}
+
+uint32_t MasterService::DynamicReplicationAdmissionMinHits() const {
+    const double hits = std::ceil(dynamic_replication_admission_qps_threshold_ *
+                                  dynamic_replication_heat_window_seconds_);
+    return std::max<uint32_t>(1, static_cast<uint32_t>(hits));
+}
+
+void MasterService::CleanupDynamicReplicationWindowsLocked(
+    std::chrono::steady_clock::time_point now, std::chrono::seconds window) {
+    size_t scanned = 0;
+    while (scanned < kDynamicReplicationWindowCleanupBudget &&
+           !dynamic_replication_window_order_.empty()) {
+        auto key = std::move(dynamic_replication_window_order_.front());
+        dynamic_replication_window_order_.pop_front();
+        auto it = dynamic_replication_windows_.find(key);
+        if (it != dynamic_replication_windows_.end()) {
+            if (now - it->second.window_start > window * 2) {
+                dynamic_replication_windows_.erase(it);
+            } else {
+                dynamic_replication_window_order_.push_back(std::move(key));
+            }
+        }
+        scanned++;
+    }
+}
+
+bool MasterService::ObserveDynamicReplicationAccess(
+    const ObjectIdentity& object_id) {
+    if (!DynamicReplicationEnabled()) {
+        return false;
+    }
+    const auto now = std::chrono::steady_clock::now();
+    const auto window =
+        std::chrono::seconds(dynamic_replication_heat_window_seconds_);
+    const auto admission_key =
+        object_id.tenant_id.MakeScopedKey(object_id.user_key);
+
+    std::lock_guard<std::mutex> lock(dynamic_replication_mutex_);
+    if (dynamic_replication_windows_.size() >=
+            kDynamicReplicationWindowEntryLimit &&
+        now >= dynamic_replication_next_window_cleanup_) {
+        dynamic_replication_next_window_cleanup_ =
+            now + kDynamicReplicationWindowCleanupInterval;
+        CleanupDynamicReplicationWindowsLocked(now, window);
+    }
+
+    auto counter_it = dynamic_replication_windows_.find(admission_key);
+    if (counter_it == dynamic_replication_windows_.end()) {
+        if (dynamic_replication_windows_.size() >=
+            kDynamicReplicationWindowEntryLimit) {
+            return false;
+        }
+        counter_it = dynamic_replication_windows_
+                         .emplace(admission_key, DynamicReplicationWindow{})
+                         .first;
+        dynamic_replication_window_order_.push_back(admission_key);
+    }
+
+    auto& counter = counter_it->second;
+    if (counter.window_start.time_since_epoch().count() == 0 ||
+        now - counter.window_start >= window) {
+        counter.window_start = now;
+        counter.hits = 0;
+    }
+    counter.hits++;
+    return counter.hits == DynamicReplicationAdmissionMinHits();
+}
+
+bool MasterService::DynamicReplicationHeatAdmitted(
+    const ObjectIdentity& object_id) {
+    if (!DynamicReplicationEnabled()) {
+        return false;
+    }
+    const auto now = std::chrono::steady_clock::now();
+    const auto window =
+        std::chrono::seconds(dynamic_replication_heat_window_seconds_);
+    const auto admission_key =
+        object_id.tenant_id.MakeScopedKey(object_id.user_key);
+
+    std::lock_guard<std::mutex> lock(dynamic_replication_mutex_);
+    auto counter_it = dynamic_replication_windows_.find(admission_key);
+    if (counter_it == dynamic_replication_windows_.end()) {
+        return false;
+    }
+    const auto& counter = counter_it->second;
+    if (counter.window_start.time_since_epoch().count() == 0 ||
+        now - counter.window_start >= window) {
+        return false;
+    }
+    return counter.hits >= DynamicReplicationAdmissionMinHits();
 }
 
-size_t MasterService::CountCandidatesForTesting(const TenantId& tenant_id) {
-    size_t count = 0;
-    std::shared_lock<std::shared_mutex> lock(snapshot_mutex_);
+void MasterService::MaybeQueueDynamicReplicaProposal(
+    const ObjectIdentity& object_id) {
+    if (!ObserveDynamicReplicationAccess(object_id)) {
+        return;
+    }
+    if (dynamic_replication_mode_ == DynamicReplicationMode::kObserve) {
+        VLOG(1) << "dynamic_replication_observe_would_propose key="
+                << object_id.user_key;
+        return;
+    }
+    if (!DynamicReplicationEnforce()) {
+        return;
+    }
+    EnqueueDynamicReplicaProposal(object_id);
+}
+
+void MasterService::EnqueueDynamicReplicaProposal(
+    const ObjectIdentity& object_id) {
+    const auto scoped_key =
+        object_id.tenant_id.MakeScopedKey(object_id.user_key);
+    std::lock_guard<std::mutex> lock(dynamic_replication_admission_mutex_);
+    if (dynamic_replication_admission_queued_.contains(scoped_key) ||
+        dynamic_replication_admission_queue_.size() >=
+            kDynamicReplicationAdmissionQueueLimit) {
+        return;
+    }
+    dynamic_replication_admission_queue_.push(object_id);
+    dynamic_replication_admission_queued_.insert(scoped_key);
+    dynamic_replication_admission_cv_.notify_one();
+}
+
+void MasterService::TrySubmitDynamicReplicaProposal(
+    const ObjectIdentity& object_id) {
+    if (!DynamicReplicationEnforce() ||
+        !DynamicReplicationHeatAdmitted(object_id)) {
+        return;
+    }
+
+    ReplicaActionProposal proposal;
+    proposal.action = ReplicaActionType::ADD;
+    proposal.proposal_id = generate_uuid();
+    proposal.tenant_id = object_id.tenant_id.value();
+    proposal.key = object_id.user_key;
+    proposal.expire_at_ms_epoch =
+        DynamicReplicationNowMs() + kDynamicReplicationLeaseTtl.count();
+
+    auto lease = SubmitReplicaActionProposalLocked(proposal);
+    if (!lease.has_value()) {
+        VLOG(1) << "dynamic_replication_auto_proposal_rejected key="
+                << object_id.user_key << ", error_code=" << lease.error();
+    }
+}
+
+void MasterService::DynamicReplicationAdmissionThreadFunc() {
+    VLOG(1) << "action=dynamic_replication_admission_thread_started";
+    while (dynamic_replication_admission_running_) {
+        std::vector<ObjectIdentity> batch;
+        {
+            std::unique_lock<std::mutex> lock(
+                dynamic_replication_admission_mutex_);
+            dynamic_replication_admission_cv_.wait_for(
+                lock,
+                std::chrono::milliseconds(
+                    kDynamicReplicationAdmissionThreadSleepMs),
+                [&] {
+                    return !dynamic_replication_admission_running_.load() ||
+                           !dynamic_replication_admission_queue_.empty();
+                });
+            if (!dynamic_replication_admission_running_) {
+                break;
+            }
+            while (!dynamic_replication_admission_queue_.empty() &&
+                   batch.size() < kDynamicReplicationAdmissionBatchSize) {
+                auto object_id =
+                    std::move(dynamic_replication_admission_queue_.front());
+                dynamic_replication_admission_queue_.pop();
+                dynamic_replication_admission_queued_.erase(
+                    object_id.tenant_id.MakeScopedKey(object_id.user_key));
+                batch.push_back(std::move(object_id));
+            }
+        }
+        for (const auto& object_id : batch) {
+            std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+            TrySubmitDynamicReplicaProposal(object_id);
+        }
+    }
+    VLOG(1) << "action=dynamic_replication_admission_thread_stopped";
+}
+
+uint64_t MasterService::DynamicReplicationVersionEpoch(
+    const ObjectMetadata& metadata) const {
+    return static_cast<uint64_t>(
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            metadata.put_start_time.time_since_epoch())
+            .count());
+}
+
+int64_t MasterService::DynamicReplicationNowMs() {
+    return static_cast<int64_t>(
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::now().time_since_epoch())
+            .count());
+}
+
+void MasterService::ClearDynamicReplicationStateForKey(
+    TenantState& tenant_state, const std::string& key) {
+    tenant_state.dynamic_replication_pending.erase(key);
+    tenant_state.dynamic_replication_cooldowns.erase(key);
+    for (auto it = tenant_state.dynamic_replication_leases.begin();
+         it != tenant_state.dynamic_replication_leases.end();) {
+        if (it->second.key == key) {
+            it = tenant_state.dynamic_replication_leases.erase(it);
+        } else {
+            ++it;
+        }
+    }
+}
+
+void MasterService::CleanupExpiredDynamicReplicationState() {
+    if (!DynamicReplicationEnabled()) {
+        return;
+    }
+    const int64_t now_ms = DynamicReplicationNowMs();
     for (size_t i = 0; i < kNumShards; i++) {
-        MetadataShardAccessorRO shard(this, i);
-        auto it = shard->tenants.find(tenant_id);
-        if (it != shard->tenants.end()) {
-            count += it->second.promotion_candidates.size();
+        MetadataShardAccessorRW shard(this, i);
+        for (auto tenant_it = shard->tenants.begin();
+             tenant_it != shard->tenants.end();) {
+            auto& tenant_state = tenant_it->second;
+            std::vector<std::string> expired_pending_keys;
+            for (const auto& [key, pending] :
+                 tenant_state.dynamic_replication_pending) {
+                if (pending.expire_at_ms_epoch < now_ms) {
+                    expired_pending_keys.push_back(key);
+                }
+            }
+            for (const auto& key : expired_pending_keys) {
+                auto pending_it =
+                    tenant_state.dynamic_replication_pending.find(key);
+                if (pending_it !=
+                    tenant_state.dynamic_replication_pending.end()) {
+                    task_manager_.get_write_access().fail_task_if_pending(
+                        pending_it->second.task_id,
+                        "dynamic replica lease expired");
+                }
+                ClearDynamicReplicationStateForKey(tenant_state, key);
+            }
+            for (auto lease_it =
+                     tenant_state.dynamic_replication_leases.begin();
+                 lease_it != tenant_state.dynamic_replication_leases.end();) {
+                if (lease_it->second.expire_at_ms_epoch < now_ms) {
+                    lease_it =
+                        tenant_state.dynamic_replication_leases.erase(lease_it);
+                } else {
+                    ++lease_it;
+                }
+            }
+            if (tenant_state.Empty()) {
+                tenant_it = shard->tenants.erase(tenant_it);
+            } else {
+                ++tenant_it;
+            }
         }
     }
-    return count;
 }
 
-void MasterService::ResetCandidateBackoffsForTesting() {
-    const auto epoch = std::chrono::steady_clock::time_point{};
-    for (size_t i = 0; i < kNumShards; i++) {
-        MetadataShardAccessorRW shard(this, i);
-        for (auto& [tenant_id, tenant_state] : shard->tenants) {
-            (void)tenant_id;
-            for (auto& [key, candidate] : tenant_state.promotion_candidates) {
-                (void)key;
-                candidate.retry_after = epoch;
+bool MasterService::HasDynamicReplicationPending(TenantState& tenant_state,
+                                                 const std::string& key) {
+    auto it = tenant_state.dynamic_replication_pending.find(key);
+    if (it == tenant_state.dynamic_replication_pending.end()) {
+        return false;
+    }
+    if (it->second.expire_at_ms_epoch >= DynamicReplicationNowMs()) {
+        return true;
+    }
+    ClearDynamicReplicationStateForKey(tenant_state, key);
+    return false;
+}
+
+std::optional<MasterService::DynamicReplicaPlan>
+MasterService::SelectDynamicReplicaPlan(
+    const ObjectMetadata& metadata,
+    const std::optional<std::string>& preferred_target_segment,
+    std::string target_domain) {
+    const std::string& object_key = metadata.user_key;
+    std::unordered_set<std::string> existing_segments;
+    std::unordered_set<std::string> existing_hosts;
+    std::vector<std::string> source_segments;
+    std::unordered_map<std::string, std::shared_ptr<ClientLivenessRecord>>
+        source_liveness_by_segment;
+    size_t memory_replicas = 0;
+
+    ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
+    std::vector<std::pair<Segment, UUID>> segments;
+    if (segment_access.GetAllSegments(segments) != ErrorCode::OK) {
+        return std::nullopt;
+    }
+    std::unordered_map<std::string, Segment> segments_by_name;
+    for (const auto& [segment, client_id] : segments) {
+        (void)client_id;
+        segments_by_name.emplace(segment.name, segment);
+    }
+
+    metadata.VisitReplicas(
+        [this](const Replica& replica) {
+            return IsReplicaReadable(replica) && replica.is_memory_replica();
+        },
+        [&](const Replica& replica) {
+            memory_replicas++;
+            const auto liveness = replica.getClientLiveness();
+            for (const auto& segment_name : replica.get_segment_names()) {
+                if (!segment_name.has_value()) {
+                    continue;
+                }
+                existing_segments.insert(*segment_name);
+                source_segments.push_back(*segment_name);
+                source_liveness_by_segment[*segment_name] = liveness;
+                auto segment_it = segments_by_name.find(*segment_name);
+                if (segment_it != segments_by_name.end() &&
+                    !segment_it->second.host_id.empty()) {
+                    existing_hosts.insert(segment_it->second.host_id);
+                }
+            }
+        });
+
+    if (source_segments.empty() || memory_replicas == 0 ||
+        memory_replicas >= dynamic_replication_max_memory_replicas_) {
+        return std::nullopt;
+    }
+
+    std::sort(source_segments.begin(), source_segments.end());
+    source_segments.erase(
+        std::unique(source_segments.begin(), source_segments.end()),
+        source_segments.end());
+    const std::string source_segment = *std::min_element(
+        source_segments.begin(), source_segments.end(),
+        [&](const auto& lhs, const auto& rhs) {
+            return DynamicReplicationStableScore(object_key, lhs) <
+                   DynamicReplicationStableScore(object_key, rhs);
+        });
+
+    auto is_valid_target = [&](const Segment& segment) {
+        if (existing_segments.contains(segment.name) ||
+            !segment_access.IsSegmentAllocatable(segment.name)) {
+            return false;
+        }
+        size_t used = 0;
+        size_t capacity = 0;
+        if (segment_access.QuerySegments(segment.name, used, capacity) !=
+                ErrorCode::OK ||
+            capacity == 0 || used >= capacity ||
+            capacity - used < metadata.size) {
+            return false;
+        }
+        const double util_after = static_cast<double>(used + metadata.size) /
+                                  static_cast<double>(capacity);
+        return util_after < kDynamicReplicationTargetHighWatermark;
+    };
+
+    auto target_score = [&](const Segment& segment) {
+        size_t used = 0;
+        size_t capacity = 0;
+        if (segment_access.QuerySegments(segment.name, used, capacity) !=
+                ErrorCode::OK ||
+            capacity == 0) {
+            return std::tuple<bool, double, uint64_t>(
+                false, std::numeric_limits<double>::max(),
+                std::numeric_limits<uint64_t>::max());
+        }
+        const bool different_host = segment.host_id.empty() ||
+                                    existing_hosts.empty() ||
+                                    !existing_hosts.contains(segment.host_id);
+        const double util =
+            static_cast<double>(used) / static_cast<double>(capacity);
+        return std::tuple<bool, double, uint64_t>(
+            different_host, util,
+            DynamicReplicationStableScore(object_key, segment.name));
+    };
+
+    std::optional<std::string> target_segment;
+    if (preferred_target_segment.has_value()) {
+        const auto preferred = std::find_if(
+            segments.begin(), segments.end(), [&](const auto& entry) {
+                return entry.first.name == *preferred_target_segment;
+            });
+        if (preferred != segments.end() && is_valid_target(preferred->first)) {
+            target_segment = preferred->first.name;
+        }
+    }
+    if (!target_segment.has_value()) {
+        std::optional<std::tuple<bool, double, uint64_t>> best_score;
+        for (const auto& [segment, client_id] : segments) {
+            (void)client_id;
+            if (!is_valid_target(segment)) {
+                continue;
+            }
+            const auto score = target_score(segment);
+            if (!best_score.has_value() ||
+                std::get<0>(score) > std::get<0>(*best_score) ||
+                (std::get<0>(score) == std::get<0>(*best_score) &&
+                 std::get<1>(score) < std::get<1>(*best_score)) ||
+                (std::get<0>(score) == std::get<0>(*best_score) &&
+                 std::get<1>(score) == std::get<1>(*best_score) &&
+                 std::get<2>(score) < std::get<2>(*best_score))) {
+                best_score = score;
+                target_segment = segment.name;
+            }
+        }
+    }
+
+    if (!target_segment.has_value()) {
+        return std::nullopt;
+    }
+    const auto source_liveness =
+        source_liveness_by_segment.find(source_segment);
+    if (source_liveness == source_liveness_by_segment.end() ||
+        !source_liveness->second) {
+        return std::nullopt;
+    }
+    return DynamicReplicaPlan{
+        .source_segment = source_segment,
+        .target_segment = *target_segment,
+        .target_domain = std::move(target_domain),
+        .source_liveness = source_liveness->second,
+    };
+}
+
+tl::expected<ReplicaActionLease, ErrorCode>
+MasterService::SubmitReplicaActionProposal(
+    const ReplicaActionProposal& proposal) {
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
+    return SubmitReplicaActionProposalLocked(proposal);
+}
+
+tl::expected<ReplicaActionLease, ErrorCode>
+MasterService::SubmitReplicaActionProposalLocked(
+    const ReplicaActionProposal& proposal) {
+    if (!DynamicReplicationEnforce()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    if (proposal.action != ReplicaActionType::ADD || proposal.key.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (proposal.proposal_id == UUID{0, 0}) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (!proposal.requester_domain.empty() || !proposal.target_domain.empty()) {
+        // Domain-aware admission and placement are reserved for the next stage.
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const int64_t now_ms = DynamicReplicationNowMs();
+    if (proposal.expire_at_ms_epoch > 0 &&
+        proposal.expire_at_ms_epoch < now_ms) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    auto normalized_tenant_result =
+        ResolveTenantIdForWrite(TenantId(proposal.tenant_id));
+    if (!normalized_tenant_result) {
+        return tl::make_unexpected(normalized_tenant_result.error());
+    }
+    ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
+                             proposal.key};
+    const UUID proposal_id = proposal.proposal_id;
+
+    MetadataAccessorRW accessor(this, object_id);
+    if (!accessor.Exists()) {
+        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+    }
+
+    auto& tenant_state = accessor.GetTenantState();
+    auto lease_it = tenant_state.dynamic_replication_leases.find(proposal_id);
+    if (lease_it != tenant_state.dynamic_replication_leases.end()) {
+        if (lease_it->second.expire_at_ms_epoch >= now_ms) {
+            const auto& lease = lease_it->second;
+            const bool same_request =
+                lease.action == proposal.action &&
+                lease.tenant_id == object_id.tenant_id.value() &&
+                lease.key == object_id.user_key &&
+                (proposal.observed_version_epoch == 0 ||
+                 lease.version_epoch == proposal.observed_version_epoch) &&
+                (!proposal.preferred_target_segment.has_value() ||
+                 lease.target_segment == *proposal.preferred_target_segment) &&
+                (proposal.target_domain.empty() ||
+                 lease.target_domain == proposal.target_domain);
+            if (!same_request) {
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
             }
+            return lease_it->second;
         }
+        tenant_state.dynamic_replication_leases.erase(lease_it);
     }
-}
 
-size_t MasterService::RunPromotionCandidateRetry(size_t max_shards_to_scan) {
-    if (!promotion_on_hit_ ||
-        promotion_candidate_count_.load(std::memory_order_relaxed) == 0) {
-        return 0;
+    if (!DynamicReplicationHeatAdmitted(object_id)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
 
-    const auto now = std::chrono::steady_clock::now();
-    std::vector<ObjectIdentity> due_candidates;
-    due_candidates.reserve(kPromotionRetryBatchSize);
-
-    const size_t shards_to_scan = std::min(max_shards_to_scan, kNumShards);
-    if (shards_to_scan == 0) return 0;
-    const size_t start_shard = promotion_retry_cursor_.fetch_add(
-                                   shards_to_scan, std::memory_order_relaxed) %
-                               kNumShards;
-
-    {
-        std::shared_lock<std::shared_mutex> snap_lock(snapshot_mutex_);
-        for (size_t scanned = 0;
-             scanned < shards_to_scan &&
-             due_candidates.size() < kPromotionRetryBatchSize;
-             ++scanned) {
-            const size_t i = (start_shard + scanned) % kNumShards;
-            MetadataShardAccessorRW shard(this, i);
-            for (auto tenant_it = shard->tenants.begin();
-                 tenant_it != shard->tenants.end() &&
-                 due_candidates.size() < kPromotionRetryBatchSize;) {
-                auto& tenant_state = tenant_it->second;
-                for (auto cit = tenant_state.promotion_candidates.begin();
-                     cit != tenant_state.promotion_candidates.end() &&
-                     due_candidates.size() < kPromotionRetryBatchSize;) {
-                    const auto& key = cit->first;
-                    auto& c = cit->second;
-
-                    const bool ttl_expired =
-                        now - c.last_seen >= kPromotionCandidateTtl;
-                    if (ttl_expired ||
-                        c.retry_count >= kPromotionCandidateMaxRetries) {
-                        VLOG(1) << "promotion_candidate_expired key=" << key
-                                << " retry_count=" << c.retry_count;
-                        const uint32_t saved_retry_count = c.retry_count;
-                        cit = tenant_state.promotion_candidates.erase(cit);
-                        DecrementCandidateCount();
-                        // retry_count == 0: scheduler never reached this
-                        // candidate before TTL elapsed — scan budget was
-                        // too small. retry_count > 0: scheduler evaluated
-                        // it but gave up after retries or TTL.
-                        if (saved_retry_count == 0) {
-                            MasterMetricManager::instance()
-                                .inc_promotion_candidate_expired_unevaluated();
-                        } else {
-                            MasterMetricManager::instance()
-                                .inc_promotion_candidate_expired_evaluated();
-                        }
-                        continue;
-                    }
-                    if (c.retry_after > now) {
-                        ++cit;
-                        continue;
-                    }
+    auto cooldown_it =
+        tenant_state.dynamic_replication_cooldowns.find(object_id.user_key);
+    if (cooldown_it != tenant_state.dynamic_replication_cooldowns.end()) {
+        const auto now = std::chrono::steady_clock::now();
+        if (cooldown_it->second > now) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        tenant_state.dynamic_replication_cooldowns.erase(cooldown_it);
+    }
 
-                    // Quick pre-filter under shard lock to avoid adding
-                    // candidates that are obviously ineligible.
-                    auto meta_it = tenant_state.metadata.find(key);
-                    if (meta_it == tenant_state.metadata.end() ||
-                        !meta_it->second.IsValid() ||
-                        tenant_state.processing_keys.count(key) > 0 ||
-                        tenant_state.promotion_tasks.count(key) > 0 ||
-                        meta_it->second.HasReplica(
-                            &Replica::fn_is_memory_replica) ||
-                        !meta_it->second.HasReplica(
-                            &Replica::fn_is_local_disk_replica)) {
-                        cit = tenant_state.promotion_candidates.erase(cit);
-                        DecrementCandidateCount();
-                        continue;
-                    }
+    if (accessor.InProcessing() || accessor.HasReplicationTask() ||
+        HasDynamicReplicationPending(tenant_state, object_id.user_key)) {
+        return tl::make_unexpected(ErrorCode::OBJECT_HAS_REPLICATION_TASK);
+    }
 
-                    due_candidates.push_back(ObjectIdentity{
-                        .tenant_id = tenant_it->first, .user_key = key});
-                    ++cit;
-                }
+    auto& metadata = accessor.Get();
+    if (proposal.observed_version_epoch != 0 &&
+        proposal.observed_version_epoch !=
+            DynamicReplicationVersionEpoch(metadata)) {
+        return tl::make_unexpected(ErrorCode::INVALID_VERSION);
+    }
+    if (proposal.object_size_bytes != 0 &&
+        proposal.object_size_bytes != metadata.size) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (metadata.DynamicReplicationRecreateBlocked(
+            std::chrono::steady_clock::now())) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
 
-                if (tenant_state.Empty()) {
-                    tenant_it = shard->tenants.erase(tenant_it);
-                } else {
-                    ++tenant_it;
-                }
-            }
-        }
+    auto plan = SelectDynamicReplicaPlan(
+        metadata, proposal.preferred_target_segment, proposal.target_domain);
+    if (!plan.has_value()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
 
-    size_t queued = 0;
+    const UUID lease_id = generate_uuid();
+    const uint64_t version_epoch = DynamicReplicationVersionEpoch(metadata);
+    const int64_t server_deadline_ms =
+        now_ms + kDynamicReplicationLeaseTtl.count();
+    const int64_t lease_expire_at_ms_epoch =
+        proposal.expire_at_ms_epoch > 0
+            ? std::min(proposal.expire_at_ms_epoch, server_deadline_ms)
+            : server_deadline_ms;
+
+    ReplicaActionLease lease;
+    lease.proposal_id = proposal_id;
+    lease.lease_id = lease_id;
+    lease.action = ReplicaActionType::ADD;
+    lease.tenant_id = object_id.tenant_id.value();
+    lease.key = object_id.user_key;
+    lease.source_segment = plan->source_segment;
+    lease.target_segment = plan->target_segment;
+    lease.target_domain = plan->target_domain;
+    lease.version_epoch = version_epoch;
+    lease.expire_at_ms_epoch = lease_expire_at_ms_epoch;
+
+    tenant_state.dynamic_replication_pending[object_id.user_key] =
+        DynamicReplicaPending{.proposal_id = proposal_id,
+                              .lease_id = lease.lease_id,
+                              .source_segment = lease.source_segment,
+                              .target_segment = lease.target_segment,
+                              .target_domain = lease.target_domain,
+                              .version_epoch = lease.version_epoch,
+                              .expire_at_ms_epoch = lease.expire_at_ms_epoch,
+                              .task_id = UUID{}};
+
+    auto task =
+        SubmitDynamicReplicaCopyTask(object_id, *plan, lease_id, version_epoch);
+    if (!task.has_value()) {
+        ClearDynamicReplicationStateForKey(tenant_state, object_id.user_key);
+        return tl::make_unexpected(task.error());
+    }
+
+    lease.task_id = task.value();
+    tenant_state.dynamic_replication_pending[object_id.user_key].task_id =
+        lease.task_id;
+    tenant_state.dynamic_replication_leases[proposal_id] = lease;
+    tenant_state.dynamic_replication_cooldowns[object_id.user_key] =
+        std::chrono::steady_clock::now() + kDynamicReplicationActionCooldown;
+    return lease;
+}
+
+tl::expected<UUID, ErrorCode> MasterService::SubmitDynamicReplicaCopyTask(
+    const ObjectIdentity& object_id, const DynamicReplicaPlan& plan,
+    const UUID& lease_id, uint64_t version_epoch) {
+    UUID source_client;
     {
-        std::shared_lock<std::shared_mutex> snap_lock(snapshot_mutex_);
-        for (const auto& object_id : due_candidates) {
-            const auto result =
-                TryPushPromotionQueue(object_id, /*record_candidate=*/false);
-            if (result == PromotionQueueResult::kQueued) {
-                queued++;
-                MasterMetricManager::instance()
-                    .inc_promotion_candidate_admitted();
-            } else if (IsTransientResult(result)) {
-                MasterMetricManager::instance()
-                    .inc_promotion_candidate_admission_rejected();
-                BackoffCandidate(object_id, result);
-            } else {
-                EraseCandidate(object_id);
-            }
+        ScopedSegmentAccess segment_access =
+            segment_manager_.getSegmentAccess();
+        ErrorCode error = segment_access.GetClientIdBySegmentName(
+            plan.source_segment, source_client);
+        if (error != ErrorCode::OK) {
+            return tl::make_unexpected(error);
         }
     }
-
-    return queued;
+    const auto& liveness = plan.source_liveness;
+    if (!liveness) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    // The proposal caller holds the object's metadata shard. Observe serving
+    // eligibility without blocking on the Client transition mutex while that
+    // shard is held; offboarding cleanup is ordered after this shard section.
+    if (!liveness->IsServing()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
+    UUID current_source_client;
+    if (segment_access.GetClientIdBySegmentName(
+            plan.source_segment, current_source_client) != ErrorCode::OK ||
+        current_source_client != source_client) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    return task_manager_.get_write_access()
+        .submit_task_typed<TaskType::REPLICA_COPY>(
+            source_client,
+            {.tenant_id = object_id.tenant_id.value(),
+             .key = object_id.user_key,
+             .source = plan.source_segment,
+             .targets = {plan.target_segment},
+             .dynamic_replication_lease_id_high = lease_id.first,
+             .dynamic_replication_lease_id_low = lease_id.second,
+             .dynamic_replication_version_epoch = version_epoch});
 }
 
-MasterService::PromotionQueueResult MasterService::TryPushPromotionQueue(
+PromotionQueueResult MasterService::TryPushPromotionQueue(
     const ObjectIdentity& object_id, bool record_candidate) {
     if (!promotion_on_hit_ || !promotion_sketch_) {
         return PromotionQueueResult::kDisabled;
@@ -6761,8 +9811,7 @@ MasterService::PromotionQueueResult MasterService::TryPushPromotionQueue(
     // Watermark gate: don't promote if DRAM is already under eviction
     // pressure. The check is best-effort (state can change between this
     // sample and the actual allocation in PromotionAllocStart).
-    const double used_ratio =
-        MasterMetricManager::instance().get_global_mem_used_ratio();
+    const double used_ratio = segment_manager_.GetMemoryUsage().used_ratio();
     if (used_ratio >= eviction_high_watermark_ratio_) {
         MasterMetricManager::instance().inc_promotion_rejected_watermark();
         if (record_candidate) {
@@ -6796,6 +9845,13 @@ MasterService::PromotionQueueResult MasterService::TryPushPromotionQueue(
     // Dedup: don't queue twice if a promotion is already in flight or if a
     // MEMORY replica has appeared since GetReplicaList observed only-disk.
     if (tenant_state.promotion_tasks.count(key) > 0) {
+        // A read hit an already in-flight promotion: re-mark the queued
+        // entry's recency so the next heartbeat delivers it ahead of stale
+        // admissions. No-op if the heartbeat already took the entry (the
+        // promotion is executing) or the holder's mailbox is gone.
+        local_ssd_manager_.TouchPromotion(
+            tenant_state.promotion_tasks.at(key).holder_id, object_id.tenant_id,
+            key);
         EraseCandidate(tenant_state, key);
         return PromotionQueueResult::kAlreadyInFlight;
     }
@@ -6868,13 +9924,22 @@ MasterService::PromotionQueueResult MasterService::TryPushPromotionQueue(
 
     // Record the in-flight task. alloc_id is filled in by
     // PromotionAllocStart once the new MEMORY replica is staged.
+    // Propagate the execution-failure count across the candidate's
+    // consumption so NotifyPromotionFailure can bound self-sustaining
+    // execution-failure cycles; an absent candidate means a fresh chain (0).
+    uint32_t execution_failures = 0;
+    if (auto cit = tenant_state.promotion_candidates.find(key);
+        cit != tenant_state.promotion_candidates.end()) {
+        execution_failures = cit->second.execution_failures;
+    }
     EraseCandidate(tenant_state, key);
     tenant_state.promotion_tasks.emplace(
         key, PromotionTask{.source_id = source->id(),
                            .alloc_id = 0,
                            .object_size = object_size,
                            .start_time = std::chrono::system_clock::now(),
-                           .holder_id = holder_id});
+                           .holder_id = holder_id,
+                           .execution_failures = execution_failures});
     promotion_in_flight_.fetch_add(1, std::memory_order_relaxed);
     MasterMetricManager::instance().inc_promotion_in_flight();
     MasterMetricManager::instance().inc_promotion_admitted();
@@ -6884,42 +9949,35 @@ MasterService::PromotionQueueResult MasterService::TryPushPromotionQueue(
 
 auto MasterService::PromotionObjectHeartbeat(const UUID& client_id)
     -> tl::expected<std::vector<PromotionTaskItem>, ErrorCode> {
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    ScopedLocalDiskSegmentAccess local_disk_segment_access =
-        segment_manager_.getLocalDiskSegmentAccess();
-    auto& client_local_disk_segment =
-        local_disk_segment_access.getClientLocalDiskSegment();
-    auto local_disk_segment_it = client_local_disk_segment.find(client_id);
-    if (local_disk_segment_it == client_local_disk_segment.end()) {
-        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    const auto record = FindClientRecord(client_id);
+    auto serving_guard =
+        record ? record->TryAcquireServingGuard() : std::nullopt;
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
-    MutexLocker locker(&local_disk_segment_it->second->offloading_mutex_);
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     // Return at most promotion_max_per_heartbeat_ tasks. Each task does
     // a synchronous SSD read + RDMA write on the client side; allowing
     // more than one per heartbeat risks blocking past the client-
     // liveness window and the master marking the client dead. The rest
-    // stay queued in promotion_objects for subsequent heartbeats. The
+    // stay queued in the mailbox for subsequent heartbeats. The
     // cap must live here (server side) rather than on the client so
     // leftover work isn't silently dropped.
-    auto& src = local_disk_segment_it->second->promotion_objects;
-    std::vector<PromotionTaskItem> result;
-    while (result.size() < promotion_max_per_heartbeat_ && !src.empty()) {
-        auto node = src.extract(src.begin());
-        result.push_back(std::move(node.mapped()));
-    }
-    return result;
+    return local_ssd_manager_.TakePromotions(client_id,
+                                             promotion_max_per_heartbeat_);
 }
 
 auto MasterService::PromotionAllocStart(
     const UUID& client_id, const std::string& key, const TenantId& tenant_id,
     uint64_t size, const std::vector<std::string>& preferred_segments)
     -> tl::expected<PromotionAllocStartResponse, ErrorCode> {
-    auto normalized_tenant_result = ResolveTenantIdForWrite(tenant_id);
-    if (!normalized_tenant_result) {
-        return tl::make_unexpected(normalized_tenant_result.error());
+    const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
+    const auto record = FindClientRecord(client_id);
+    auto serving_guard =
+        record ? record->TryAcquireServingGuard() : std::nullopt;
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
-    const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
-                                   key};
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     MetadataAccessorRW accessor(this, object_id);
     if (!accessor.Exists()) {
@@ -6964,18 +10022,19 @@ auto MasterService::PromotionAllocStart(
         return tl::make_unexpected(ErrorCode::REPLICA_IS_NOT_READY);
     }
     if (task_it->second.alloc_id != 0 ||
-        task_it->second.reserved_quota_charge_bytes != 0) {
+        task_it->second.pending_quota_charge_bytes != 0) {
         return tl::make_unexpected(ErrorCode::REPLICA_IS_NOT_READY);
     }
 
-    const uint64_t reserved_quota_charge = size;
-    auto quota_result =
-        ReserveTenantQuota(object_id.tenant_id, reserved_quota_charge);
+    const uint64_t pending_quota_charge = size;
+    auto quota_result = ChargeTenantQuota(
+        GetBoundTenantQuotaHandle(tenant_state), pending_quota_charge);
     if (!quota_result) {
         return tl::make_unexpected(quota_result.error());
     }
-    auto abort_reserved_quota = [&] {
-        AbortTenantQuota(object_id.tenant_id, reserved_quota_charge);
+    auto refund_pending_quota = [&] {
+        ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                           pending_quota_charge);
     };
 
     // Allocate a single MEMORY replica via the existing strategy, biased to
@@ -6987,26 +10046,37 @@ auto MasterService::PromotionAllocStart(
     }
 
     std::vector<Replica> staged_replicas;
+    // Allocation is guarded by the selected memory Segment owner. Release the
+    // holder guard first so a co-located holder cannot self-deadlock and two
+    // Clients cannot form a source/target lock cycle. The holder operation was
+    // already admitted and its metadata shard stays locked until the staged
+    // replica and task state are committed or rolled back.
+    serving_guard.reset();
+    AllocatorManager allocator_snapshot;
     {
         ScopedAllocatorAccess allocator_access =
             segment_manager_.getAllocatorAccess();
-        const auto& allocator_manager = allocator_access.getAllocatorManager();
-        auto allocation_result = allocation_strategy_->Allocate(
-            allocator_manager, size, config.replica_num, preferred_segments);
-        if (!allocation_result) {
-            abort_reserved_quota();
-            return tl::make_unexpected(allocation_result.error());
-        }
-        staged_replicas = std::move(allocation_result.value());
+        allocator_snapshot = allocator_access.SnapshotAllocatorManager();
     }
+    auto allocation_result = allocation_strategy_->Allocate(
+        allocator_snapshot, size, config.replica_num, preferred_segments);
+    if (!allocation_result) {
+        refund_pending_quota();
+        return tl::make_unexpected(allocation_result.error());
+    }
+    staged_replicas = std::move(allocation_result.value());
     if (staged_replicas.empty()) {
-        abort_reserved_quota();
+        refund_pending_quota();
         return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
     }
 
     // Append the new PROCESSING MEMORY replica to the existing object's
     // metadata. Visible only after NotifyPromotionSuccess flips it COMPLETE.
-    Replica::Descriptor desc = staged_replicas[0].get_descriptor();
+    Replica::Descriptor desc;
+    if (!staged_replicas[0].getDescriptorIfAvailable(desc)) {
+        refund_pending_quota();
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     const ReplicaID new_id = staged_replicas[0].id();
     std::vector<Replica> to_add;
     to_add.push_back(std::move(staged_replicas[0]));
@@ -7028,7 +10098,7 @@ auto MasterService::PromotionAllocStart(
     // (alloc_id == 0) is bounded by its own original start_time window
     // during which the reaper's EraseReplicaByID branch is a no-op.
     task_it->second.alloc_id = new_id;
-    task_it->second.reserved_quota_charge_bytes = reserved_quota_charge;
+    task_it->second.pending_quota_charge_bytes = pending_quota_charge;
     task_it->second.start_time = std::chrono::system_clock::now();
     return PromotionAllocStartResponse{std::move(desc)};
 }
@@ -7037,6 +10107,12 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
                                            const std::string& key,
                                            const TenantId& tenant_id)
     -> tl::expected<void, ErrorCode> {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
@@ -7044,6 +10120,7 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
         return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
     }
     auto& metadata = accessor.Get();
+    const auto previous_kv_media = KvMediaSnapshot(metadata);
     auto& tenant_state = accessor.GetTenantState();
 
     // Look up the in-flight task to find the exact replica we staged. A
@@ -7084,9 +10161,7 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
                                    });
 
             const auto payload =
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, post, metadata.group_id,
-                    metadata.data_type);
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata, post);
             if (batch_reservation) {
                 auto persist_result = AppendReservedOpLogWithDurableFinalize(
                     std::move(*batch_reservation), OpType::PUT_END,
@@ -7116,25 +10191,23 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
         source->dec_refcnt();
     }
     const uint64_t completed_bytes = task_it->second.object_size;
-    const uint64_t reserved_quota_charge =
-        task_it->second.reserved_quota_charge_bytes;
     if (committed) {
-        const uint64_t actual_charge = CompletedMemoryQuotaCharge(metadata);
-        const uint64_t commit_charge =
-            actual_charge > metadata.committed_quota_charge_bytes
-                ? actual_charge - metadata.committed_quota_charge_bytes
-                : 0;
-        const uint64_t abort_charge =
-            reserved_quota_charge > commit_charge
-                ? reserved_quota_charge - commit_charge
-                : 0;
-        CommitTenantQuota(object_id.tenant_id, commit_charge);
-        AbortTenantQuota(object_id.tenant_id, abort_charge);
-        metadata.committed_quota_charge_bytes = actual_charge;
+        if (enable_multi_tenants_) {
+            auto settle_result = metadata.quota_ledger.SettleAdditional(
+                GetBoundTenantQuotaHandle(tenant_state),
+                task_it->second.pending_quota_charge_bytes, completed_bytes);
+            if (!settle_result) {
+                LogTenantQuotaLedgerError(settle_result, "settle_additional",
+                                          object_id.tenant_id,
+                                          object_id.user_key);
+                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+        }
     } else {
-        AbortTenantQuota(object_id.tenant_id, reserved_quota_charge);
+        ReleaseTenantQuota(
+            GetBoundTenantQuotaHandle(tenant_state),
+            std::exchange(task_it->second.pending_quota_charge_bytes, 0));
     }
-    task_it->second.reserved_quota_charge_bytes = 0;
     tenant_state.promotion_tasks.erase(task_it);
     promotion_in_flight_.fetch_sub(1, std::memory_order_relaxed);
     MasterMetricManager::instance().dec_promotion_in_flight();
@@ -7147,24 +10220,15 @@ auto MasterService::NotifyPromotionSuccess(const UUID& client_id,
         MasterMetricManager::instance().inc_promotion_cancelled();
     }
 
-    // Erase the per-client promotion_objects entry (best-effort; the
+    // Erase the per-client promotion mailbox entry (best-effort; the
     // heartbeat may have already drained it).
-    {
-        ScopedLocalDiskSegmentAccess local_disk_segment_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        auto& client_local_disk_segment =
-            local_disk_segment_access.getClientLocalDiskSegment();
-        auto it = client_local_disk_segment.find(client_id);
-        if (it != client_local_disk_segment.end()) {
-            MutexLocker locker(&it->second->offloading_mutex_);
-            it->second->promotion_objects.erase(
-                object_id.tenant_id.MakeScopedKey(object_id.user_key));
-        }
-    }
+    local_ssd_manager_.RemovePromotion(client_id, object_id.tenant_id,
+                                       object_id.user_key);
 
     if (!committed) {
         return tl::make_unexpected(ErrorCode::REPLICA_IS_NOT_READY);
     }
+    SyncKvObjectState(key, metadata, object_id.tenant_id, previous_kv_media);
     return {};
 }
 
@@ -7172,6 +10236,12 @@ auto MasterService::NotifyPromotionFailure(const UUID& client_id,
                                            const std::string& key,
                                            const TenantId& tenant_id)
     -> tl::expected<void, ErrorCode> {
+    const auto record = FindClientRecord(client_id);
+    auto retaining_guard =
+        record ? record->TryAcquireRetainingGuard() : std::nullopt;
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto object_id = MakeObjectIdentityForRequest(key, tenant_id);
     MetadataAccessorRW accessor(this, object_id);
@@ -7208,41 +10278,118 @@ auto MasterService::NotifyPromotionFailure(const UUID& client_id,
                 return replica.id() == alloc_id;
             });
     }
-    AbortTenantQuota(object_id.tenant_id,
-                     task_it->second.reserved_quota_charge_bytes);
-    task_it->second.reserved_quota_charge_bytes = 0;
+    ReleaseTenantQuota(
+        GetBoundTenantQuotaHandle(tenant_state),
+        std::exchange(task_it->second.pending_quota_charge_bytes, 0));
+    // Capture the chain's execution-failure count BEFORE erasing the task
+    // (the iterator is invalidated by the erase).
+    const uint32_t prior_failures = task_it->second.execution_failures;
     tenant_state.promotion_tasks.erase(task_it);
     promotion_in_flight_.fetch_sub(1, std::memory_order_relaxed);
     MasterMetricManager::instance().dec_promotion_in_flight();
     MasterMetricManager::instance().inc_promotion_failed();
 
-    // Clear the holder's per-client promotion_objects entry. Same
-    // best-effort cleanup pattern as NotifyPromotionSuccess — the
-    // heartbeat may have already drained it.
-    {
-        ScopedLocalDiskSegmentAccess local_disk_segment_access =
-            segment_manager_.getLocalDiskSegmentAccess();
-        auto& client_local_disk_segment =
-            local_disk_segment_access.getClientLocalDiskSegment();
-        auto it = client_local_disk_segment.find(client_id);
-        if (it != client_local_disk_segment.end()) {
-            MutexLocker locker(&it->second->offloading_mutex_);
-            it->second->promotion_objects.erase(
-                object_id.tenant_id.MakeScopedKey(object_id.user_key));
+    // A transient execution failure (DRAM pressure at AllocStart, a TE write
+    // flake, SSD throttling) must not silently kill the promotion: re-record
+    // a retry candidate so the eviction-thread retry loop re-queues it with
+    // backoff. Bounded by kPromotionCandidateMaxRetries /
+    // kPromotionCandidateTtl, and the retry path erases the candidate on
+    // permanent conditions (not-found, memory-present, no-local-disk-source),
+    // so this cannot spin. Record the current estimate via count()
+    // (read-only), NOT increment(): an executor-side failure is not demand
+    // signal, and bumping the sketch here would pollute the frequency signal
+    // the admission gate relies on.
+    //
+    // The self-sustaining cycle is additionally bounded by
+    // kMaxPromotionExecutionFailures: without it, a persistently-failing key
+    // (e.g. a broken SSD file that still has a LOCAL_DISK replica) would
+    // re-record -> re-admit -> fail -> re-record forever, monopolizing
+    // delivery slots with no read demand. Once the bound is hit we stop
+    // re-recording — a genuine read can still re-admit the key (fresh chain).
+    if (!metadata.HasReplica(&Replica::fn_is_memory_replica) &&
+        metadata.HasReplica(&Replica::fn_is_local_disk_replica)) {
+        if (prior_failures >= kMaxPromotionExecutionFailures) {
+            LOG(WARNING) << "promotion_execution_gave_up key="
+                         << object_id.user_key
+                         << " failures=" << prior_failures;
+            MasterMetricManager::instance().inc_promotion_execution_gave_up();
+        } else {
+            const auto admission_key =
+                object_id.tenant_id.MakeScopedKey(object_id.user_key);
+            const uint8_t freq =
+                promotion_sketch_ ? promotion_sketch_->count(admission_key) : 0;
+            RecordOrUpdateCandidate(tenant_state, object_id.user_key, freq,
+                                    PromotionCandidateReason::kExecutionFailed,
+                                    ErrorCode::OK, prior_failures + 1);
         }
     }
 
+    // Clear the holder's per-client promotion mailbox entry. Same
+    // best-effort cleanup pattern as NotifyPromotionSuccess — the
+    // heartbeat may have already drained it.
+    local_ssd_manager_.RemovePromotion(client_id, object_id.tenant_id,
+                                       object_id.user_key);
+
     return {};
 }
 
+void MasterService::EvictTenantsOverWatermark() {
+    if (!enable_multi_tenants_ ||
+        tenant_eviction_high_watermark_ratio_ <= 0.0) {
+        return;
+    }
+
+    // Evict down to (watermark - eviction_ratio) of the tenant's quota,
+    // mirroring what BatchEvict does for the pool: free a slab so subsequent
+    // admissions find room already available, rather than freeing exactly the
+    // deficit of the object currently being admitted.
+    const double target_ratio =
+        std::max(0.0, tenant_eviction_high_watermark_ratio_ - eviction_ratio_);
+
+    for (const auto& snapshot : tenant_quota_table_.ListTenantSnapshots()) {
+        if (snapshot.effective_quota_bytes == 0) {
+            continue;
+        }
+        const double used_ratio =
+            static_cast<double>(snapshot.charged_bytes) /
+            static_cast<double>(snapshot.effective_quota_bytes);
+        if (used_ratio <= tenant_eviction_high_watermark_ratio_) {
+            continue;
+        }
+        const double excess_ratio = used_ratio - target_ratio;
+        const auto target_bytes = static_cast<uint64_t>(
+            excess_ratio * static_cast<double>(snapshot.effective_quota_bytes));
+        if (target_bytes == 0) {
+            continue;
+        }
+
+        // VLOG rather than INFO: this pass runs once per second and emits a
+        // line per over-watermark tenant, so sustained quota pressure in a
+        // large multi-tenant deployment would flood the log. The pool-level
+        // [EVICT-TRIGGER] above stays at INFO because it is a single line
+        // gated on a pool-wide threshold.
+        VLOG(1) << "[TENANT-EVICT-TRIGGER] tenant=" << snapshot.tenant_id
+                << " used_ratio=" << used_ratio
+                << " high_watermark=" << tenant_eviction_high_watermark_ratio_
+                << " target_ratio=" << target_ratio
+                << " target_bytes=" << target_bytes;
+        const TenantQuotaEvictionResult result =
+            EvictTenantMemoryForQuota(snapshot.tenant_id, target_bytes);
+        VLOG(1) << "[TENANT-EVICT-DONE] tenant=" << snapshot.tenant_id
+                << " freed_bytes=" << result.freed_bytes
+                << " evicted_objects=" << result.evicted_objects;
+    }
+}
+
 void MasterService::EvictionThreadFunc() {
     VLOG(1) << "action=eviction_thread_started";
 
     auto last_discard_time = std::chrono::system_clock::now();
+    auto next_dfs_eviction_time = std::chrono::steady_clock::now();
+    auto next_tenant_eviction_time = std::chrono::steady_clock::now();
     while (eviction_running_) {
         const auto now = std::chrono::system_clock::now();
-        double used_ratio =
-            MasterMetricManager::instance().get_global_mem_used_ratio();
+        double used_ratio = segment_manager_.GetMemoryUsage().used_ratio();
         if (used_ratio > eviction_high_watermark_ratio_ ||
             (need_mem_eviction_ && eviction_ratio_ > 0.0)) {
             LOG(INFO) << "[EVICT-TRIGGER] memory_ratio=" << used_ratio
@@ -7273,9 +10420,23 @@ void MasterService::EvictionThreadFunc() {
             last_discard_time = now;
         }
 
+        // Tenant-scoped watermark. Intentionally outside the branch above:
+        // the case this exists for is a tenant over its OWN watermark while
+        // the pool is still under the pool-wide one, so it must not be gated
+        // on the pool-level condition having fired.
+        if (enable_multi_tenants_ &&
+            tenant_eviction_high_watermark_ratio_ > 0.0) {
+            const auto steady_now = std::chrono::steady_clock::now();
+            if (steady_now >= next_tenant_eviction_time) {
+                EvictTenantsOverWatermark();
+                next_tenant_eviction_time =
+                    std::chrono::steady_clock::now() +
+                    std::chrono::milliseconds(kTenantEvictionCheckIntervalMs);
+            }
+        }
+
 #ifdef USE_NOF
-        double nof_used_ratio =
-            MasterMetricManager::instance().get_global_nof_used_ratio();
+        double nof_used_ratio = nof_segment_manager_.GetUsage().used_ratio();
         if (nof_used_ratio > nof_eviction_high_watermark_ratio_ ||
             (need_nof_eviction_ && nof_eviction_ratio_ > 0.0)) {
             double nof_evict_ratio_target =
@@ -7289,6 +10450,16 @@ void MasterService::EvictionThreadFunc() {
         }
 #endif
 
+        if (dfs_allocator_ && dfs_allocator_->IsEvictionEnabled()) {
+            const auto steady_now = std::chrono::steady_clock::now();
+            if (steady_now >= next_dfs_eviction_time) {
+                RunDfsEviction();
+                next_dfs_eviction_time =
+                    std::chrono::steady_clock::now() +
+                    dfs_allocator_->GetEvictionCheckInterval();
+            }
+        }
+
         if (promotion_candidate_count_.load(std::memory_order_relaxed) > 0) {
             RunPromotionCandidateRetry();
         }
@@ -7322,13 +10493,20 @@ void MasterService::DiscardExpiredProcessingReplicas(
             auto& metadata = it->second;
             if (!metadata.IsValid() ||
                 metadata.AllReplicas(&Replica::fn_is_completed)) {
+                metadata.ClearPendingSoftPinIfNoViableReplica();
                 if (!metadata.IsValid()) {
                     auto next_key_it = std::next(key_it);
                     EraseMetadata(tenant_state, it, tenant_it->first,
                                   QuotaEraseMode::kFull, &shard);
                     key_it = next_key_it;
                 } else {
-                    key_it = tenant_state.processing_keys.erase(key_it);
+                    auto settle_result =
+                        SettlePrimaryWriteQuotaIfReady(tenant_state, metadata);
+                    if (!settle_result) {
+                        ++key_it;
+                    } else {
+                        key_it = tenant_state.processing_keys.erase(key_it);
+                    }
                 }
                 continue;
             }
@@ -7361,9 +10539,7 @@ void MasterService::DiscardExpiredProcessingReplicas(
                         persist_result = AppendOpLogWithDurableFinalize(
                             OpType::PUT_END, tenant_it->first.value(), *key_it,
                             SerializeMetadataForOpLogFromReplicaDescriptors(
-                                metadata.client_id, metadata.size,
-                                post_descriptors, metadata.group_id,
-                                metadata.data_type),
+                                metadata, post_descriptors),
                             enable_oplog_
                                 ? [this, ttl](const OpLogEntry& durable_entry) {
                                       FinalizeExpiredProcessingReplicasAfterDurable(
@@ -7389,7 +10565,9 @@ void MasterService::DiscardExpiredProcessingReplicas(
                 // Persist OK (or HA disabled / never published) — apply.
                 auto replicas =
                     metadata.PopReplicas(&Replica::fn_is_processing);
+                metadata.ClearPendingSoftPinIfNoViableReplica();
                 if (!replicas.empty()) {
+                    FreeDfsReplicas(*key_it, replicas);
                     discarded_replicas.emplace_back(std::move(replicas), ttl);
                 }
                 if (!metadata.IsValid()) {
@@ -7398,7 +10576,13 @@ void MasterService::DiscardExpiredProcessingReplicas(
                                   QuotaEraseMode::kFull, &shard);
                     key_it = next_key_it;
                 } else {
-                    key_it = tenant_state.processing_keys.erase(key_it);
+                    auto settle_result =
+                        SettlePrimaryWriteQuotaIfReady(tenant_state, metadata);
+                    if (!settle_result) {
+                        ++key_it;
+                    } else {
+                        key_it = tenant_state.processing_keys.erase(key_it);
+                    }
                 }
                 continue;
             }
@@ -7411,15 +10595,15 @@ void MasterService::DiscardExpiredProcessingReplicas(
             if (metadata_it == tenant_state.metadata.end()) {
                 LOG(ERROR) << "Key " << task_it->first
                            << " was removed with ongoing replication task";
-                AbortTenantQuota(tenant_it->first,
-                                 task_it->second.reserved_quota_charge_bytes);
+                ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                                   task_it->second.pending_quota_charge_bytes);
                 task_it = tenant_state.replication_tasks.erase(task_it);
                 continue;
             }
 
             const auto ttl =
                 task_it->second.start_time + put_start_release_timeout_sec_;
-            if (ttl > now) {
+            if (ttl > now || task_it->second.durable_cleanup_pending) {
                 task_it++;
                 continue;
             }
@@ -7442,9 +10626,14 @@ void MasterService::DiscardExpiredProcessingReplicas(
 
             if (had_complete_replica && enable_oplog_ &&
                 ordered_oplog_writer_) {
+                task_it->second.durable_cleanup_pending = true;
                 tl::expected<OpLogEntry, ErrorCode> persist_result;
                 auto source_id = task_it->second.source_id;
                 auto target_ids = replica_ids;
+                auto dynamic_lease_id =
+                    task_it->second.dynamic_replication_lease_id;
+                auto dynamic_version_epoch =
+                    task_it->second.dynamic_replication_version_epoch;
                 if (would_invalidate) {
                     persist_result = AppendOpLogWithDurableFinalize(
                         OpType::REMOVE, tenant_it->first.value(),
@@ -7452,9 +10641,11 @@ void MasterService::DiscardExpiredProcessingReplicas(
                         enable_oplog_
                             ? [this, source_id,
                                target_ids = std::move(target_ids),
+                               dynamic_lease_id, dynamic_version_epoch,
                                ttl](const OpLogEntry& durable_entry) {
                                   FinalizeExpiredReplicationTaskAfterDurable(
                                       durable_entry, source_id, target_ids,
+                                      dynamic_lease_id, dynamic_version_epoch,
                                       ttl);
                               }
                             : DurableFinalizeCallback{});
@@ -7463,14 +10654,15 @@ void MasterService::DiscardExpiredProcessingReplicas(
                         OpType::PUT_END, tenant_it->first.value(),
                         task_it->first,
                         SerializeMetadataForOpLogFromReplicaDescriptors(
-                            metadata.client_id, metadata.size, post_descriptors,
-                            metadata.group_id, metadata.data_type),
+                            metadata, post_descriptors),
                         enable_oplog_
                             ? [this, source_id,
                                target_ids = std::move(target_ids),
+                               dynamic_lease_id, dynamic_version_epoch,
                                ttl](const OpLogEntry& durable_entry) {
                                   FinalizeExpiredReplicationTaskAfterDurable(
                                       durable_entry, source_id, target_ids,
+                                      dynamic_lease_id, dynamic_version_epoch,
                                       ttl);
                               }
                             : DurableFinalizeCallback{});
@@ -7482,6 +10674,7 @@ void MasterService::DiscardExpiredProcessingReplicas(
                         << task_it->first
                         << ", err=" << static_cast<int>(persist_result.error())
                         << ", deferring discard";
+                    task_it->second.durable_cleanup_pending = false;
                     ++task_it;
                     continue;
                 }
@@ -7498,15 +10691,31 @@ void MasterService::DiscardExpiredProcessingReplicas(
 
             auto replicas =
                 PopReplicasWithCacheTotalAccounting(metadata, target_pred);
+            std::vector<ReplicaID> erased_replica_ids;
+            erased_replica_ids.reserve(replicas.size());
+            for (const auto& replica : replicas) {
+                erased_replica_ids.push_back(replica.id());
+            }
+            const bool dynamic_task =
+                task_it->second.dynamic_replication_lease_id != UUID{} ||
+                task_it->second.dynamic_replication_version_epoch != 0;
+            RecordDynamicReplicaRemoval(metadata, erased_replica_ids);
             if (!replicas.empty()) {
+                FreeDfsReplicas(task_it->first, replicas);
                 discarded_replicas.emplace_back(std::move(replicas), ttl);
             }
+            if (dynamic_task) {
+                ClearDynamicReplicationStateForKey(tenant_state,
+                                                   task_it->first);
+            }
             if (!metadata.IsValid()) {
                 auto next_task_it = std::next(task_it);
                 EraseMetadata(tenant_state, metadata_it, tenant_it->first,
                               QuotaEraseMode::kFull, &shard);
                 task_it = next_task_it;
             } else {
+                ReleaseTenantQuota(GetBoundTenantQuotaHandle(tenant_state),
+                                   task_it->second.pending_quota_charge_bytes);
                 task_it = tenant_state.replication_tasks.erase(task_it);
             }
         }
@@ -7556,9 +10765,9 @@ void MasterService::DiscardExpiredProcessingReplicas(
                         });
                 }
             }
-            AbortTenantQuota(tenant_it->first,
-                             task_it->second.reserved_quota_charge_bytes);
-            task_it->second.reserved_quota_charge_bytes = 0;
+            ReleaseTenantQuota(
+                GetBoundTenantQuotaHandle(tenant_state),
+                std::exchange(task_it->second.pending_quota_charge_bytes, 0));
             LOG(WARNING) << "Promotion task expired for key: "
                          << task_it->first;
             task_it = tenant_state.promotion_tasks.erase(task_it);
@@ -7703,18 +10912,118 @@ void MasterService::ResetStateAfterFailedRestoreAttempt() {
     task_manager_serializer.Reset();
     metadata_serializer.Reset();
     segment_serializer.Reset();
+    local_ssd_manager_.Clear();
 
     {
         std::unique_lock<std::shared_mutex> lock(client_mutex_);
         ok_client_.clear();
-    }
-    PodUUID pod_uuid;
-    while (client_ping_queue_.pop(pod_uuid)) {
+        client_host_id_.clear();
+        client_liveness_records_.clear();
     }
 
     MasterMetricManager::instance().reset_allocated_mem_size();
     MasterMetricManager::instance().reset_total_mem_capacity();
     MasterMetricManager::instance().reset_cache_total_nums();
+    MasterMetricManager::instance().reset_client_liveness_metrics();
+}
+
+tl::expected<void, SerializationError>
+MasterService::RebuildClientLivenessAfterSnapshotRestore() {
+    std::vector<std::pair<Segment, UUID>> segments;
+    {
+        ScopedSegmentAccess segment_access =
+            segment_manager_.getSegmentAccess();
+        const auto err = segment_access.GetAllSegments(segments);
+        if (err != ErrorCode::OK && err != ErrorCode::SEGMENT_NOT_FOUND) {
+            return tl::make_unexpected(SerializationError(
+                err, "failed to enumerate restored memory segments"));
+        }
+    }
+
+    std::unordered_set<UUID, boost::hash<UUID>> client_ids;
+    for (const auto& [segment, owner] : segments) {
+        (void)segment;
+        client_ids.insert(owner);
+    }
+    for (const auto& client_id : local_ssd_manager_.GetClientIds()) {
+        client_ids.insert(client_id);
+    }
+
+    for (const auto& shard : metadata_shards_) {
+        for (const auto& [tenant_id, tenant_state] : shard.tenants) {
+            (void)tenant_id;
+            for (const auto& [key, metadata] : tenant_state.metadata) {
+                (void)key;
+                for (const auto& replica : metadata.GetAllReplicas()) {
+                    if (replica.is_local_disk_replica()) {
+                        const auto owner = replica.get_local_disk_client_id();
+                        if (owner) {
+                            client_ids.insert(*owner);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    std::unordered_map<UUID, std::shared_ptr<ClientLivenessRecord>,
+                       boost::hash<UUID>>
+        records;
+    records.reserve(client_ids.size());
+    const auto now = ClientLivenessRecord::Clock::now();
+    for (const auto& client_id : client_ids) {
+        records.emplace(client_id, std::make_shared<ClientLivenessRecord>(now));
+    }
+
+    bool missing_memory_registration = false;
+    {
+        ScopedSegmentAccess segment_access =
+            segment_manager_.getSegmentAccess();
+        for (const auto& [client_id, record] : records) {
+            segment_access.BindClientLiveness(client_id, record);
+        }
+        for (auto& shard : metadata_shards_) {
+            for (auto& [tenant_id, tenant_state] : shard.tenants) {
+                (void)tenant_id;
+                for (auto& [key, metadata] : tenant_state.metadata) {
+                    (void)key;
+                    metadata.VisitReplicas(
+                        [](const Replica&) { return true; },
+                        [&](Replica& replica) {
+                            if (replica.is_memory_replica()) {
+                                auto& buffer =
+                                    *std::get<MemoryReplicaData>(replica.data_)
+                                         .buffer;
+                                if (!segment_access.RebindBufferToOwningSegment(
+                                        buffer)) {
+                                    missing_memory_registration = true;
+                                }
+                            } else if (replica.is_local_disk_replica()) {
+                                const auto owner =
+                                    replica.get_local_disk_client_id();
+                                if (owner) {
+                                    replica.bindClientLiveness(
+                                        records.at(*owner));
+                                }
+                            }
+                        });
+                }
+            }
+        }
+    }
+    if (missing_memory_registration) {
+        return tl::make_unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            "restored memory replica has no Segment registration"));
+    }
+
+    {
+        std::unique_lock<std::shared_mutex> lock(client_mutex_);
+        client_liveness_records_ = std::move(records);
+    }
+    MasterMetricManager::instance().reset_client_liveness_metrics(
+        static_cast<int64_t>(client_ids.size()));
+    return {};
 }
 
 tl::expected<void, SerializationError> MasterService::ApplySnapshotState(
@@ -7723,6 +11032,11 @@ tl::expected<void, SerializationError> MasterService::ApplySnapshotState(
     // so the internal state is already restored. This method handles
     // post-restore cleanup and metrics rebuilding.
 
+    auto liveness_result = RebuildClientLivenessAfterSnapshotRestore();
+    if (!liveness_result) {
+        return tl::make_unexpected(liveness_result.error());
+    }
+
     std::vector<std::string> segment_names;
     {
         ScopedSegmentAccess segment_access =
@@ -7744,8 +11058,7 @@ tl::expected<void, SerializationError> MasterService::ApplySnapshotState(
                          it != tenant_state.metadata.end();) {
                         if (it->second.HasDiffRepStatus(
                                 ReplicaStatus::COMPLETE) ||
-                            (it->second.IsLeaseExpired(cleanup_now) &&
-                             !it->second.IsSoftPinned(cleanup_now))) {
+                            it->second.IsLeaseExpired(cleanup_now)) {
                             VLOG(1) << "clear metadata key=" << it->first;
                             it = EraseMetadata(tenant_state, it,
                                                tenant_it->first);
@@ -7798,9 +11111,12 @@ tl::expected<void, SerializationError> MasterService::ApplySnapshotState(
         }
 
         LOG(INFO) << "[Restore] Total allocated size after restore: "
-                  << MasterMetricManager::instance().get_allocated_mem_size();
+                  << segment_manager_.GetMemoryUsage().used_bytes;
     }
 
+    // Soft pin is runtime-only and is never restored from a snapshot.
+    soft_pin_deadline_index_.Clear();
+
     // Rebuild total capacity metrics
     {
         MasterMetricManager::instance().reset_total_mem_capacity();
@@ -7853,9 +11169,8 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
     auto now = std::chrono::system_clock::now();
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
 
-    auto is_evictable_memory_replica = [](const Replica& replica) {
-        return replica.is_memory_replica() && replica.is_completed() &&
-               replica.get_refcnt() == 0;
+    auto is_evictable_memory_replica = [this](const Replica& replica) {
+        return IsEvictableMemoryReplica(replica);
     };
     auto can_evict_replicas = [&](const ObjectMetadata& metadata) {
         return metadata.HasReplica(is_evictable_memory_replica);
@@ -7864,19 +11179,29 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
         return metadata.HasReplica(&Replica::fn_is_local_disk_replica);
     };
     auto evict_replicas =
-        [&, this](ObjectMetadata& metadata,
+        [&, this](TenantState& tenant_state, ObjectMetadata& metadata,
                   std::vector<std::vector<Replica>>& deferred_replicas) {
             const uint64_t before_charge = CompletedMemoryQuotaCharge(metadata);
             auto replicas = PopReplicasWithCacheTotalAccounting(
                 metadata, is_evictable_memory_replica);
+            std::vector<ReplicaID> erased_ids;
+            erased_ids.reserve(replicas.size());
+            for (const auto& replica : replicas) {
+                erased_ids.push_back(replica.id());
+            }
+            RecordDynamicReplicaRemoval(metadata, erased_ids);
             const uint64_t replica_count = replicas.size();
             if (!replicas.empty()) {
                 deferred_replicas.emplace_back(std::move(replicas));
             }
             const uint64_t after_charge = CompletedMemoryQuotaCharge(metadata);
             if (before_charge > after_charge) {
-                ReleaseCommittedQuotaCharge(metadata,
-                                            before_charge - after_charge);
+                auto release_result = metadata.quota_ledger.ReleaseCommitted(
+                    GetBoundTenantQuotaHandle(tenant_state),
+                    before_charge - after_charge);
+                LogTenantQuotaLedgerError(release_result, "release_committed",
+                                          metadata.tenant_id,
+                                          metadata.user_key);
             }
             return metadata.size * replica_count;
         };
@@ -7889,107 +11214,160 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
             ? static_cast<long>(offloading_queue_limit_ * offload_cap_ratio_)
             : 0;
 
-    auto try_evict_or_offload =
-        [&, this](const std::string& key, ObjectMetadata& metadata,
-                  TenantState& tenant_state,
-                  std::vector<std::vector<Replica>>& deferred_replicas) {
-            if (!offload_on_evict_) {
-                return evict_replicas(metadata, deferred_replicas);
-            }
-
-            if (has_local_disk_replica(metadata)) {
-                return evict_replicas(metadata, deferred_replicas);
-            }
-
-            if (offload_force_evict_ &&
-                offload_queued_this_call >= offload_cap) {
-                ++offload_cap_forced_count;
-                return evict_replicas(metadata, deferred_replicas);
-            }
+    auto try_evict_or_offload = [&, this](const std::string& key,
+                                          ObjectMetadata& metadata,
+                                          TenantState& tenant_state,
+                                          std::vector<std::vector<Replica>>&
+                                              deferred_replicas) {
+        if (!offload_on_evict_) {
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
+        }
 
-            bool queued = false;
-            metadata.VisitReplicas(
-                is_evictable_memory_replica,
-                [this, &key, &normalized_tenant, &tenant_state, &queued,
-                 &now](Replica& replica) {
-                    if (queued) {
-                        return;
-                    }
-                    auto result = PushOffloadingQueue(
-                        MakeObjectIdentity(key, normalized_tenant), replica);
-                    if (result) {
-                        replica.inc_refcnt();
-                        tenant_state.offloading_tasks.emplace(
-                            key, OffloadingTask{replica.id(), now});
-                        queued = true;
-                    }
-                });
+        if (has_local_disk_replica(metadata)) {
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
+        }
 
-            if (queued) {
-                ++offload_queued_this_call;
-                ++offload_deferred_count;
-                return evict_replicas(metadata, deferred_replicas);
-            }
+        if (offload_force_evict_ && offload_queued_this_call >= offload_cap) {
+            ++offload_cap_forced_count;
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
+        }
 
-            if (offload_force_evict_) {
-                ++offload_push_failed_forced;
-                return evict_replicas(metadata, deferred_replicas);
-            }
-            return uint64_t{0};
-        };
+        bool queued = false;
+        metadata.VisitReplicas(
+            is_evictable_memory_replica,
+            [this, &key, &normalized_tenant, &tenant_state, &queued,
+             &now](Replica& replica) {
+                if (queued) {
+                    return;
+                }
+                std::vector<UUID> mirror_clients;
+                auto result = PushOffloadingQueue(
+                    MakeObjectIdentity(key, normalized_tenant), replica,
+                    &mirror_clients);
+                if (result) {
+                    replica.inc_refcnt();
+                    tenant_state.offloading_tasks.emplace(
+                        key, OffloadingTask{replica.id(), now,
+                                            std::move(mirror_clients)});
+                    queued = true;
+                }
+            });
 
-    auto try_evict_group_or_object =
-        [&, this](const std::string& key, ObjectMetadata& metadata,
-                  TenantState& tenant_state,
-                  std::vector<std::vector<Replica>>& deferred_replicas,
-                  bool allow_soft_pinned) -> TenantQuotaEvictionResult {
-        if (!metadata.IsGrouped()) {
-            uint64_t freed = try_evict_or_offload(key, metadata, tenant_state,
-                                                  deferred_replicas);
-            return {.freed_bytes = freed,
-                    .evicted_objects = freed > 0 ? 1U : 0U};
+        if (queued) {
+            ++offload_queued_this_call;
+            ++offload_deferred_count;
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
 
-        auto group_it = tenant_state.group_members.find(metadata.group_id);
-        if (group_it == tenant_state.group_members.end()) {
-            uint64_t freed = try_evict_or_offload(key, metadata, tenant_state,
-                                                  deferred_replicas);
-            return {.freed_bytes = freed,
-                    .evicted_objects = freed > 0 ? 1U : 0U};
+        if (offload_force_evict_) {
+            ++offload_push_failed_forced;
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
+        return uint64_t{0};
+    };
 
-        for (const auto& member_key : group_it->second) {
-            auto member_it = tenant_state.metadata.find(member_key);
-            if (member_it != tenant_state.metadata.end() &&
-                !member_it->second.IsLeaseExpired(now)) {
+    auto try_evict_group_or_object =
+        [&, this](const std::string& key, size_t shard_idx,
+                  bool allow_soft_pinned,
+                  std::vector<std::vector<Replica>>& deferred_replicas)
+        -> TenantQuotaEvictionResult {
+        // Snapshot grouped-ness under the trigger lock; the lock is released
+        // before any cross-shard acquisition (see EvictGroupOrObject).
+        std::string group_id;
+        {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            auto tenant_it = shard->tenants.find(normalized_tenant);
+            if (tenant_it == shard->tenants.end()) {
                 return {};
             }
-        }
-
-        TenantQuotaEvictionResult result;
-        std::vector<std::string> member_keys(group_it->second.begin(),
-                                             group_it->second.end());
-        for (const auto& member_key : member_keys) {
-            auto member_it = tenant_state.metadata.find(member_key);
-            if (member_it == tenant_state.metadata.end()) {
-                continue;
+            auto& tenant_state = tenant_it->second;
+            auto it = tenant_state.metadata.find(key);
+            if (it == tenant_state.metadata.end()) {
+                return {};
             }
-            auto& member_metadata = member_it->second;
-            if (member_metadata.IsHardPinned() ||
-                !member_metadata.IsLeaseExpired(now) ||
-                (!allow_soft_pinned && member_metadata.IsSoftPinned(now)) ||
-                !can_evict_replicas(member_metadata)) {
-                continue;
+            auto& metadata = it->second;
+            // Re-validate: state may have changed since the collection phase.
+            // Soft pins are only a blocker when this pass is not allowed to
+            // evict them.
+            if (now < metadata.EvictionDeadline() ||
+                (!allow_soft_pinned && IsSoftPinActive(metadata, now)) ||
+                !can_evict_replicas(metadata)) {
+                return {};
             }
-
+            if (!metadata.IsGrouped()) {
+                uint64_t freed = try_evict_or_offload(
+                    key, metadata, tenant_state, deferred_replicas);
+                TenantQuotaEvictionResult result{
+                    .freed_bytes = freed,
+                    .evicted_objects = freed > 0 ? 1U : 0U};
+                if (freed > 0) {
+                    PublishKvRemovedAfterEvict(key, 1, "cpu", metadata,
+                                               normalized_tenant);
+                }
+                if (!metadata.IsValid()) {
+                    EraseMetadata(tenant_state, it, normalized_tenant);
+                }
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(tenant_it);
+                }
+                return result;
+            }
+            group_id = metadata.group_id;
+        }
+
+        // Grouped object: the group is evicted all-or-none at the group level
+        // (either the whole group is protected or it is a candidate), based on
+        // the shared group TTL. Within an evicted group, member-level
+        // best-effort safety still applies (hard pins, soft pins, active
+        // writes, busy replicas are skipped). Re-validation of each member
+        // (lease/pin/evictable replica) happens inside EvictGroupOrObject under
+        // the member's own shard lock, so this callback only performs the
+        // path-specific eviction. Object routing is decoupled from groups, so
+        // members live in different metadata shards; membership is read from
+        // group_domain_ (keyed by scoped(tenant, group_id)).
+        auto evict_one_member =
+            [&, this](const std::string& member_key,
+                      ObjectMetadata& member_metadata, TenantState& state,
+                      MetadataShardAccessorRW& accessor) -> EvictMemberOutcome {
             const uint64_t freed = try_evict_or_offload(
-                member_key, member_metadata, tenant_state, deferred_replicas);
-            result.freed_bytes += freed;
+                member_key, member_metadata, state, deferred_replicas);
+            EvictMemberOutcome outcome{.freed_bytes = freed,
+                                       .evicted_objects = freed > 0 ? 1 : 0};
             if (freed > 0) {
-                ++result.evicted_objects;
+                PublishKvRemovedAfterEvict(member_key, 1, "cpu",
+                                           member_metadata, normalized_tenant);
             }
             if (member_key != key && !member_metadata.IsValid()) {
-                EraseMetadata(tenant_state, member_it, normalized_tenant);
+                EraseMetadata(state, state.metadata.find(member_key),
+                              normalized_tenant);
+            }
+            return outcome;
+        };
+
+        GroupEvictionResult group_result =
+            EvictGroupOrObject(normalized_tenant, key, group_id,
+                               allow_soft_pinned, now, evict_one_member);
+        TenantQuotaEvictionResult result{
+            .freed_bytes = group_result.freed_bytes,
+            .evicted_objects =
+                static_cast<uint64_t>(group_result.evicted_objects)};
+
+        // The callback erased every member except the trigger; re-look-up the
+        // trigger to erase it if it is now invalid and to drop an emptied
+        // tenant.
+        {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            auto tenant_it = shard->tenants.find(normalized_tenant);
+            if (tenant_it != shard->tenants.end()) {
+                auto& tenant_state = tenant_it->second;
+                auto it = tenant_state.metadata.find(key);
+                if (it != tenant_state.metadata.end() &&
+                    !it->second.IsValid()) {
+                    EraseMetadata(tenant_state, it, normalized_tenant);
+                }
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(tenant_it);
+                }
             }
         }
         return result;
@@ -8002,6 +11380,12 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
              ++scanned) {
             const size_t shard_idx = (start_shard + scanned) % kNumShards;
             std::vector<std::vector<Replica>> deferred_replicas;
+            // Snapshot the candidate keys under the shard lock, then evict each
+            // outside it: for a grouped object the trigger lock must not be
+            // held while other member shard locks are acquired
+            // (EvictGroupOrObject owns the lock acquisition in canonical
+            // order).
+            std::vector<std::string> candidate_keys;
             {
                 MetadataShardAccessorRW shard(this, shard_idx);
                 auto tenant_it = shard->tenants.find(normalized_tenant);
@@ -8009,32 +11393,26 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
                     continue;
                 }
                 auto& tenant_state = tenant_it->second;
-                for (auto it = tenant_state.metadata.begin();
-                     it != tenant_state.metadata.end() &&
-                     total.freed_bytes < target_bytes;) {
-                    auto& metadata = it->second;
+                candidate_keys.reserve(tenant_state.metadata.size());
+                for (const auto& [k, metadata] : tenant_state.metadata) {
                     if (metadata.IsHardPinned() ||
                         !metadata.IsLeaseExpired(now) ||
-                        (!allow_soft_pinned && metadata.IsSoftPinned(now)) ||
+                        (!allow_soft_pinned &&
+                         IsSoftPinActive(metadata, now)) ||
                         !can_evict_replicas(metadata)) {
-                        ++it;
                         continue;
                     }
-
-                    auto evict_result = try_evict_group_or_object(
-                        it->first, metadata, tenant_state, deferred_replicas,
-                        allow_soft_pinned);
-                    total.freed_bytes += evict_result.freed_bytes;
-                    total.evicted_objects += evict_result.evicted_objects;
-                    if (!metadata.IsValid()) {
-                        it = EraseMetadata(tenant_state, it, normalized_tenant);
-                    } else {
-                        ++it;
-                    }
+                    candidate_keys.push_back(k);
                 }
-                if (tenant_state.Empty()) {
-                    shard->tenants.erase(tenant_it);
+            }
+            for (const auto& key : candidate_keys) {
+                if (total.freed_bytes >= target_bytes) {
+                    break;
                 }
+                auto evict_result = try_evict_group_or_object(
+                    key, shard_idx, allow_soft_pinned, deferred_replicas);
+                total.freed_bytes += evict_result.freed_bytes;
+                total.evicted_objects += evict_result.evicted_objects;
             }
         }
     };
@@ -8075,6 +11453,11 @@ MasterService::EvictTenantMemoryForQuota(const TenantId& tenant_id,
 
 void MasterService::BatchEvict(double evict_ratio_target,
                                double evict_ratio_lowerbound) {
+    // Consume the allocation-pressure signal before this pass. A new failure
+    // during the pass remains visible to the next iteration.
+    const bool allocation_pressure =
+        need_mem_eviction_.exchange(false, std::memory_order_relaxed);
+
     if (evict_ratio_target < evict_ratio_lowerbound) {
         LOG(ERROR) << "evict_ratio_target=" << evict_ratio_target
                    << ", evict_ratio_lowerbound=" << evict_ratio_lowerbound
@@ -8084,9 +11467,8 @@ void MasterService::BatchEvict(double evict_ratio_target,
 
     auto now = std::chrono::system_clock::now();
 
-    auto is_evictable_memory_replica = [](const Replica& replica) {
-        return replica.is_memory_replica() && replica.is_completed() &&
-               replica.get_refcnt() == 0;
+    auto is_evictable_memory_replica = [this](const Replica& replica) {
+        return IsEvictableMemoryReplica(replica);
     };
 
     auto can_evict_replicas = [&](const ObjectMetadata& metadata) {
@@ -8094,7 +11476,7 @@ void MasterService::BatchEvict(double evict_ratio_target,
     };
 
     auto evict_replicas =
-        [&, this](ObjectMetadata& metadata,
+        [&, this](TenantState& tenant_state, ObjectMetadata& metadata,
                   std::vector<std::vector<Replica>>& deferred_replicas) {
             if (enable_oplog_) {
                 return metadata.size *
@@ -8106,14 +11488,24 @@ void MasterService::BatchEvict(double evict_ratio_target,
             const uint64_t before_charge = CompletedMemoryQuotaCharge(metadata);
             auto replicas = PopReplicasWithCacheTotalAccounting(
                 metadata, is_evictable_memory_replica);
+            std::vector<ReplicaID> erased_ids;
+            erased_ids.reserve(replicas.size());
+            for (const auto& replica : replicas) {
+                erased_ids.push_back(replica.id());
+            }
+            RecordDynamicReplicaRemoval(metadata, erased_ids);
             const size_t replica_count = replicas.size();
             if (!replicas.empty()) {
                 deferred_replicas.emplace_back(std::move(replicas));
             }
             const uint64_t after_charge = CompletedMemoryQuotaCharge(metadata);
-            if (before_charge > after_charge) {
-                ReleaseCommittedQuotaCharge(metadata,
-                                            before_charge - after_charge);
+            if (enable_multi_tenants_ && before_charge > after_charge) {
+                auto release_result = metadata.quota_ledger.ReleaseCommitted(
+                    GetBoundTenantQuotaHandle(tenant_state),
+                    before_charge - after_charge);
+                LogTenantQuotaLedgerError(release_result, "release_committed",
+                                          metadata.tenant_id,
+                                          metadata.user_key);
             }
             return metadata.size * replica_count;
         };
@@ -8140,16 +11532,16 @@ void MasterService::BatchEvict(double evict_ratio_target,
             ObjectMetadata& metadata, TenantState& tenant_state,
             std::vector<std::vector<Replica>>& deferred_replicas) -> uint64_t {
         if (enable_oplog_) {
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
         if (!offload_on_evict_) {
             // Original behavior
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
 
         // LOCAL_DISK replica already exists — safe to delete MEMORY immediately
         if (has_local_disk_replica(metadata)) {
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
 
         // Force-evict cap: if force_evict enabled and cap reached, force
@@ -8157,25 +11549,24 @@ void MasterService::BatchEvict(double evict_ratio_target,
         // flooding.
         if (offload_force_evict_ && offload_queued_this_cycle >= offload_cap) {
             offload_cap_forced_count++;
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
 
         // Queue one MEMORY replica for offload; others will be evicted below.
         bool queued = false;
         metadata.VisitReplicas(
-            [](const Replica& r) {
-                return r.is_memory_replica() && r.is_completed() &&
-                       r.get_refcnt() == 0;
-            },
-            [this, &tenant_id, &key, &tenant_state, &queued,
-             &now](Replica& replica) {
+            is_evictable_memory_replica, [this, &tenant_id, &key, &tenant_state,
+                                          &queued, &now](Replica& replica) {
                 if (queued) return;  // only need to pin one replica for offload
-                auto result = PushOffloadingQueue(
-                    MakeObjectIdentity(key, tenant_id), replica);
+                std::vector<UUID> mirror_clients;
+                auto result =
+                    PushOffloadingQueue(MakeObjectIdentity(key, tenant_id),
+                                        replica, &mirror_clients);
                 if (result) {
                     replica.inc_refcnt();
                     tenant_state.offloading_tasks.emplace(
-                        key, OffloadingTask{replica.id(), now});
+                        key, OffloadingTask{replica.id(), now,
+                                            std::move(mirror_clients)});
                     queued = true;
                 }
             });
@@ -8186,7 +11577,7 @@ void MasterService::BatchEvict(double evict_ratio_target,
             // Any remaining MEMORY replicas with refcnt==0 are redundant copies
             // (data survives via the pinned replica → disk). Evict them now to
             // reclaim memory immediately rather than waiting another cycle.
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
 
         // PushOffloadingQueue failed. Default (data-preserving) behavior is to
@@ -8195,174 +11586,209 @@ void MasterService::BatchEvict(double evict_ratio_target,
         // prevent silent data loss when the queue is unavailable.
         if (offload_force_evict_) {
             offload_push_failed_forced++;
-            return evict_replicas(metadata, deferred_replicas);
+            return evict_replicas(tenant_state, metadata, deferred_replicas);
         }
         return 0;
     };
 
-    // HA strong-consistency: persist the post-eviction state BEFORE the
-    // helper mutates `metadata`. Returns true on success (or when HA is
-    // disabled). On false, the caller must NOT call try_evict_or_offload
-    // and must NOT erase the metadata entry — local state must stay in
-    // sync with what was published.
+    // HA strong-consistency: persist the post-eviction state before the
+    // helper mutates metadata. Keep the removed IDs local until submission
+    // succeeds so a consumed reservation cannot strand REMOVED replicas.
     auto persist_evict_oplog_or_skip =
         [&, this](const TenantId& tenant_id, const std::string& key,
-                  ObjectMetadata& metadata) -> bool {
-        if (!enable_oplog_ || !ordered_oplog_writer_) {
-            return true;
+                  ObjectMetadata& metadata) -> tl::expected<void, ErrorCode> {
+        if (!enable_oplog_) {
+            return {};
         }
 
         // Predict the descriptor list after evict_replicas() runs:
         // drop COMPLETE memory replicas with refcnt==0; keep everything else
         // that is COMPLETE.
-        auto remaining =
-            BuildRemainingReplicaDescriptors(metadata, [](const Replica& r) {
-                return r.is_memory_replica() && r.is_completed() &&
-                       r.get_refcnt() == 0;
-            });
+        auto remaining = BuildRemainingReplicaDescriptors(
+            metadata, is_evictable_memory_replica);
 
-        if (enable_oplog_) {
-            auto reservation = ReserveBatchOpLogSlot();
-            if (!reservation) {
-                LOG(WARNING)
-                    << "BatchEvict: OpLog reservation failed for key=" << key
-                    << ", err=" << static_cast<int>(reservation.error())
-                    << ", skipping eviction";
-                return false;
-            }
-            std::vector<ReplicaID> removed_ids;
-            metadata.VisitReplicas(is_evictable_memory_replica,
-                                   [&removed_ids](Replica& replica) {
-                                       removed_ids.push_back(replica.id());
-                                       replica.mark_removed();
-                                   });
-            tl::expected<OpLogEntry, ErrorCode> persist_result;
-            if (remaining.empty()) {
-                persist_result = AppendReservedOpLogWithDurableFinalize(
-                    std::move(reservation.value()), OpType::REMOVE,
-                    tenant_id.value(), key, {},
-                    [this, removed_ids = std::move(removed_ids)](
-                        const OpLogEntry& durable_entry) {
-                        FinalizeRemovedReplicasAfterDurable(
-                            durable_entry, removed_ids, QuotaEraseMode::kFull);
-                    });
-            } else {
-                persist_result = AppendReservedOpLogWithDurableFinalize(
-                    std::move(reservation.value()), OpType::PUT_END,
-                    tenant_id.value(), key,
-                    SerializeMetadataForOpLogFromReplicaDescriptors(
-                        metadata.client_id, metadata.size, remaining,
-                        metadata.group_id, metadata.data_type),
-                    [this, removed_ids = std::move(removed_ids)](
-                        const OpLogEntry& durable_entry) {
-                        FinalizeRemovedReplicasAfterDurable(
-                            durable_entry, removed_ids, QuotaEraseMode::kFull);
-                    });
-            }
-            if (!persist_result) {
-                LOG(WARNING)
-                    << "BatchEvict: OpLog persist failed for key=" << key
-                    << ", err=" << static_cast<int>(persist_result.error())
-                    << ", skipping eviction";
-                return false;
-            }
-            return true;
+        auto reservation = ReserveBatchOpLogSlot();
+        if (!reservation) {
+            LOG(WARNING) << "BatchEvict: OpLog reservation failed for key="
+                         << key
+                         << ", err=" << static_cast<int>(reservation.error())
+                         << ", stopping eviction scan";
+            return tl::make_unexpected(reservation.error());
         }
-
+        std::vector<ReplicaID> removed_ids;
+        metadata.VisitReplicas(is_evictable_memory_replica,
+                               [&removed_ids](Replica& replica) {
+                                   removed_ids.push_back(replica.id());
+                                   replica.mark_removed();
+                               });
         tl::expected<OpLogEntry, ErrorCode> persist_result;
         if (remaining.empty()) {
-            persist_result = AppendOpLogWithDurableFinalize(
-                OpType::REMOVE, tenant_id.value(), key, {}, nullptr);
+            persist_result = AppendReservedOpLogWithDurableFinalize(
+                std::move(reservation.value()), OpType::REMOVE,
+                tenant_id.value(), key, {},
+                [this, removed_ids](const OpLogEntry& durable_entry) {
+                    FinalizeRemovedReplicasAfterDurable(
+                        durable_entry, removed_ids, QuotaEraseMode::kFull);
+                });
         } else {
-            persist_result = AppendOpLogWithDurableFinalize(
-                OpType::PUT_END, tenant_id.value(), key,
-                SerializeMetadataForOpLogFromReplicaDescriptors(
-                    metadata.client_id, metadata.size, remaining,
-                    metadata.group_id, metadata.data_type),
-                nullptr);
+            persist_result = AppendReservedOpLogWithDurableFinalize(
+                std::move(reservation.value()), OpType::PUT_END,
+                tenant_id.value(), key,
+                SerializeMetadataForOpLogFromReplicaDescriptors(metadata,
+                                                                remaining),
+                [this, removed_ids](const OpLogEntry& durable_entry) {
+                    FinalizeRemovedReplicasAfterDurable(
+                        durable_entry, removed_ids, QuotaEraseMode::kFull);
+                });
         }
         if (!persist_result) {
+            const ErrorCode error = persist_result.error();
+            for (const auto& id : removed_ids) {
+                if (auto* replica = metadata.GetReplicaByID(id);
+                    replica != nullptr) {
+                    replica->cancel_remove();
+                }
+            }
             LOG(WARNING) << "BatchEvict: OpLog persist failed for key=" << key
-                         << ", err=" << static_cast<int>(persist_result.error())
-                         << ", skipping eviction";
-            return false;
+                         << ", err=" << static_cast<int>(error)
+                         << ", stopping eviction scan";
+            return tl::make_unexpected(error);
         }
-        return true;
+        return {};
     };
 
     struct EvictionResult {
         uint64_t freed_bytes{0};
         long evicted_objects{0};
+        bool stop_scan{false};
+        // Set when the candidate was present but its re-validation failed
+        // (lease still live, soft-pinned, or no evictable replica), so the
+        // first pass can keep its lease timeout for the second-pass census.
+        bool revalidation_skipped{false};
     };
 
+    // Evicts a single object or a whole group. MUST be called WITHOUT holding
+    // any metadata shard lock: it acquires the trigger/member shard locks
+    // itself, and for a grouped object it never holds the trigger lock while
+    // acquiring the other member shard locks (they are taken in canonical
+    // ascending order inside EvictGroupOrObject). This removes the AB/BA
+    // cross-shard deadlock between concurrent evictions. Because the trigger
+    // lock is not held across the member traversal, members are re-looked-up
+    // and re-validated under their own locks.
     auto try_evict_group_or_object =
         [&, this](const TenantId& tenant_id, const std::string& key,
-                  ObjectMetadata& metadata, MetadataShardAccessorRW& shard,
-                  TenantState& tenant_state,
-                  std::vector<std::vector<Replica>>& deferred_replicas,
-                  bool allow_soft_pinned) -> EvictionResult {
-        if (!metadata.IsGrouped()) {
-            if (!persist_evict_oplog_or_skip(tenant_id, key, metadata)) {
-                return {};
-            }
-            uint64_t freed = try_evict_or_offload(
-                tenant_id, key, metadata, tenant_state, deferred_replicas);
-            return {.freed_bytes = freed, .evicted_objects = freed > 0 ? 1 : 0};
-        }
-
-        auto group_it = tenant_state.group_members.find(metadata.group_id);
-        if (group_it == tenant_state.group_members.end()) {
-            if (!persist_evict_oplog_or_skip(tenant_id, key, metadata)) {
+                  size_t shard_idx, bool allow_soft_pinned,
+                  std::vector<std::vector<Replica>>& deferred_replicas)
+        -> EvictionResult {
+        // Snapshot grouped-ness/membership under the trigger lock; the lock is
+        // released before any cross-shard acquisition.
+        std::string group_id;
+        {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            auto tenant_it = shard->tenants.find(tenant_id);
+            if (tenant_it == shard->tenants.end()) {
                 return {};
             }
-            uint64_t freed = try_evict_or_offload(
-                tenant_id, key, metadata, tenant_state, deferred_replicas);
-            return {.freed_bytes = freed, .evicted_objects = freed > 0 ? 1 : 0};
-        }
-
-        for (const auto& member_key : group_it->second) {
-            auto member_it = tenant_state.metadata.find(member_key);
-            if (member_it != tenant_state.metadata.end() &&
-                !member_it->second.IsLeaseExpired(now)) {
+            auto& tenant_state = tenant_it->second;
+            auto it = tenant_state.metadata.find(key);
+            if (it == tenant_state.metadata.end()) {
                 return {};
             }
-        }
-
-        EvictionResult result;
-        std::vector<std::string> member_keys(group_it->second.begin(),
-                                             group_it->second.end());
-        for (const auto& member_key : member_keys) {
-            auto member_it = tenant_state.metadata.find(member_key);
-            if (member_it == tenant_state.metadata.end()) {
-                continue;
-            }
-            auto& member_metadata = member_it->second;
-            if (member_metadata.IsHardPinned() ||
-                !member_metadata.IsLeaseExpired(now) ||
-                (!allow_soft_pinned && member_metadata.IsSoftPinned(now)) ||
-                !can_evict_replicas(member_metadata)) {
-                continue;
-            }
-
-            if (!persist_evict_oplog_or_skip(tenant_id, member_key,
-                                             member_metadata)) {
-                continue;
-            }
-            uint64_t freed =
-                try_evict_or_offload(tenant_id, member_key, member_metadata,
-                                     tenant_state, deferred_replicas);
-            result.freed_bytes += freed;
-            if (freed > 0) {
-                result.evicted_objects++;
-                if (!enable_oplog_) {
-                    PublishKvRemovedAfterEvict(member_key, freed, "cpu",
-                                               member_metadata, tenant_id);
+            auto& metadata = it->second;
+            // Re-validate: state may have changed since the census. Soft pins
+            // are only a blocker when this pass is not allowed to evict them.
+            if (now < metadata.EvictionDeadline() ||
+                (!allow_soft_pinned && IsSoftPinActive(metadata, now)) ||
+                !can_evict_replicas(metadata)) {
+                return {.revalidation_skipped = true};
+            }
+
+            if (!metadata.IsGrouped()) {
+                auto submission =
+                    persist_evict_oplog_or_skip(tenant_id, key, metadata);
+                if (!submission) {
+                    return {.stop_scan = true};
+                }
+                uint64_t freed = try_evict_or_offload(
+                    tenant_id, key, metadata, tenant_state, deferred_replicas);
+                EvictionResult result{.freed_bytes = freed,
+                                      .evicted_objects = freed > 0 ? 1 : 0};
+                if (!enable_oplog_ && freed > 0) {
+                    PublishKvRemovedAfterEvict(key, 1, "cpu", metadata,
+                                               tenant_id);
+                }
+                if (!enable_oplog_ && !metadata.IsValid()) {
+                    EraseMetadata(tenant_state, it, tenant_id,
+                                  QuotaEraseMode::kFull, &shard);
+                }
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(tenant_it);
                 }
+                return result;
+            }
+            group_id = metadata.group_id;
+        }
+
+        // Grouped object: the group is evicted all-or-none at the group level
+        // (either the whole group is protected or it is a candidate), based on
+        // the shared group TTL. Within an evicted group, member-level
+        // best-effort safety still applies below (hard pins, soft pins, active
+        // writes, busy replicas are skipped). Re-validation of each member
+        // (lease/pin/evictable replica) happens inside EvictGroupOrObject under
+        // the member's own shard lock, so this callback only performs the
+        // path-specific eviction. Object routing is decoupled from groups, so
+        // members live in different metadata shards; membership is read from
+        // group_domain_ (keyed by scoped(tenant, group_id)) without a shard
+        // lock.
+        auto evict_one_member =
+            [&, this](const std::string& member_key,
+                      ObjectMetadata& member_metadata, TenantState& state,
+                      MetadataShardAccessorRW& accessor) -> EvictMemberOutcome {
+            auto submission = persist_evict_oplog_or_skip(tenant_id, member_key,
+                                                          member_metadata);
+            if (!submission) {
+                return {.stop_scan = true};
+            }
+            const uint64_t freed =
+                try_evict_or_offload(tenant_id, member_key, member_metadata,
+                                     state, deferred_replicas);
+            EvictMemberOutcome outcome{.freed_bytes = freed,
+                                       .evicted_objects = freed > 0 ? 1 : 0};
+            if (freed > 0 && !enable_oplog_) {
+                PublishKvRemovedAfterEvict(member_key, 1, "cpu",
+                                           member_metadata, tenant_id);
             }
             if (member_key != key && !enable_oplog_ &&
                 !member_metadata.IsValid()) {
-                EraseMetadata(tenant_state, member_it, tenant_id,
-                              QuotaEraseMode::kFull, &shard);
+                EraseMetadata(state, state.metadata.find(member_key), tenant_id,
+                              QuotaEraseMode::kFull, &accessor);
+            }
+            return outcome;
+        };
+
+        GroupEvictionResult group_result = EvictGroupOrObject(
+            tenant_id, key, group_id, allow_soft_pinned, now, evict_one_member);
+        EvictionResult result{.freed_bytes = group_result.freed_bytes,
+                              .evicted_objects = group_result.evicted_objects,
+                              .stop_scan = group_result.stop_scan};
+
+        // The callback erased every member except the trigger; re-look-up the
+        // trigger to erase it if it is now invalid and to drop an emptied
+        // tenant.
+        {
+            MetadataShardAccessorRW shard(this, shard_idx);
+            auto tenant_it = shard->tenants.find(tenant_id);
+            if (tenant_it != shard->tenants.end()) {
+                auto& tenant_state = tenant_it->second;
+                auto it = tenant_state.metadata.find(key);
+                if (!enable_oplog_ && it != tenant_state.metadata.end() &&
+                    !it->second.IsValid()) {
+                    EraseMetadata(tenant_state, it, tenant_id,
+                                  QuotaEraseMode::kFull, &shard);
+                }
+                if (tenant_state.Empty()) {
+                    shard->tenants.erase(tenant_it);
+                }
             }
         }
         return result;
@@ -8430,20 +11856,22 @@ void MasterService::BatchEvict(double evict_ratio_target,
                         if (it->second.IsHardPinned()) continue;
                         bool has_evictable = can_evict_replicas(it->second);
                         if (has_evictable) shard_evictable_count++;
-                        if (!it->second.IsLeaseExpired(now) || !has_evictable)
-                            continue;
-                        if (!it->second.IsSoftPinned(now)) {
+                        // Grouped objects are evicted all-or-none, so rank them
+                        // by the shared group TTL (consistent across members)
+                        // instead of each member's own lease; this keeps the
+                        // candidate cutoff aligned with group boundaries and
+                        // prevents over-eviction.
+                        const auto deadline = it->second.EvictionDeadline();
+                        if (now < deadline || !has_evictable) continue;
+                        if (!IsSoftPinActive(it->second, now)) {
                             if (compact_frontier_prebypass) {
                                 local_candidates[t].push_back(
-                                    {s, tenant_id, it->first,
-                                     it->second.lease_timeout});
+                                    {s, tenant_id, it->first, deadline});
                             } else {
-                                local_no_pin[t].push_back(
-                                    it->second.lease_timeout);
+                                local_no_pin[t].push_back(deadline);
                             }
                         } else if (allow_evict_soft_pinned_objects_) {
-                            local_soft_pin[t].push_back(
-                                it->second.lease_timeout);
+                            local_soft_pin[t].push_back(deadline);
                         }
                     }
                 }
@@ -8498,7 +11926,6 @@ void MasterService::BatchEvict(double evict_ratio_target,
     }
 
     if (total_eviction_base == 0) {
-        need_mem_eviction_ = false;
         VLOG(1) << "[EVICT-DIAG] object_count=" << object_count
                 << " eviction_base=0 (no evictable memory objects)";
         return;
@@ -8533,20 +11960,23 @@ void MasterService::BatchEvict(double evict_ratio_target,
                         for (const auto& [key, metadata] :
                              tenant_state.metadata) {
                             if (metadata.IsHardPinned() ||
-                                !metadata.IsLeaseExpired(now) ||
-                                metadata.IsSoftPinned(now) ||
+                                IsSoftPinActive(metadata, now) ||
                                 !can_evict_replicas(metadata)) {
                                 continue;
                             }
+                            // Group-aware eviction deadline (shared group TTL
+                            // for grouped objects) so the cutoff matches
+                            // eviction.
+                            const auto deadline = metadata.EvictionDeadline();
+                            if (now < deadline) continue;
                             if (use_cutoff) {
-                                const bool in_range =
-                                    collect_older_or_equal
-                                        ? metadata.lease_timeout <= cutoff
-                                        : metadata.lease_timeout > cutoff;
+                                const bool in_range = collect_older_or_equal
+                                                          ? deadline <= cutoff
+                                                          : deadline > cutoff;
                                 if (!in_range) continue;
                             }
                             local_frontier[t].push_back(
-                                {s, tenant_id, key, metadata.lease_timeout});
+                                {s, tenant_id, key, deadline});
                         }
                     }
                 }
@@ -8609,8 +12039,12 @@ void MasterService::BatchEvict(double evict_ratio_target,
     // ===== Phase 2: Serial eviction via key lookup =====
     long evicted_count = 0;
     uint64_t total_freed_size = 0;
+    bool stop_eviction_scan = false;
     std::vector<std::chrono::system_clock::time_point> no_pin_objects;
     std::vector<std::vector<Replica>> deferred_replicas;
+    // Shards that actually evicted this cycle; their metadata maps are
+    // shrink candidates once eviction finishes.
+    std::bitset<kNumShards> evicted_shards;
 
     // First pass: evict candidates with no soft pin
     if (!candidates.empty()) {
@@ -8621,7 +12055,6 @@ void MasterService::BatchEvict(double evict_ratio_target,
                          [](const Candidate& a, const Candidate& b) {
                              return a.lease_timeout < b.lease_timeout;
                          });
-        auto target_timeout = candidates[evict_num - 1].lease_timeout;
 
         // Treat evict_num as a minimum: if re-validation skips a candidate,
         // continue trying the next one so actual evicted count reaches
@@ -8629,51 +12062,33 @@ void MasterService::BatchEvict(double evict_ratio_target,
         long evicted_this_pass = 0;
         auto evict_candidate_batch = [&](std::vector<Candidate>& batch) {
             for (auto& c : batch) {
-                if (evicted_this_pass >= evict_num &&
-                    c.lease_timeout > target_timeout) {
+                if (stop_eviction_scan) break;
+                // Stop once the target object count is reached. Grouped
+                // eviction is all-or-none, so evicting a group can overshoot
+                // evict_num by at most one group; using evict_num (rather than
+                // the per-object lease cutoff) bounds that overshoot and keeps
+                // the eviction ratio close to the target.
+                if (evicted_this_pass >= evict_num) {
                     no_pin_objects.push_back(c.lease_timeout);
                     continue;
                 }
-                {
-                    MetadataShardAccessorRW shard(this, c.shard_idx);
-                    auto tenant_it = shard->tenants.find(c.tenant_id);
-                    if (tenant_it == shard->tenants.end()) continue;
-                    auto& tenant_state = tenant_it->second;
-                    auto it = tenant_state.metadata.find(c.key);
-                    if (it == tenant_state.metadata.end()) continue;
-
-                    // Re-validate: state may have changed since Phase 1
-                    if (!it->second.IsLeaseExpired(now) ||
-                        it->second.IsSoftPinned(now) ||
-                        !can_evict_replicas(it->second)) {
-                        no_pin_objects.push_back(c.lease_timeout);
-                        continue;
-                    }
-
-                    auto evict_result = try_evict_group_or_object(
-                        c.tenant_id, c.key, it->second, shard, tenant_state,
-                        deferred_replicas,
-                        /*allow_soft_pinned=*/false);
-
-                    total_freed_size += evict_result.freed_bytes;
-
-                    if (!enable_oplog_ && !it->second.IsGrouped()) {
-                        PublishKvRemovedAfterEvict(
-                            c.key, evict_result.freed_bytes, "cpu", it->second,
-                            c.tenant_id);
-                    }
+                auto evict_result = try_evict_group_or_object(
+                    c.tenant_id, c.key, c.shard_idx,
+                    /*allow_soft_pinned=*/false, deferred_replicas);
 
-                    if (!enable_oplog_ && !it->second.IsValid()) {
-                        EraseMetadata(tenant_state, it, c.tenant_id,
-                                      QuotaEraseMode::kFull, &shard);
-                    }
+                total_freed_size += evict_result.freed_bytes;
 
-                    if (tenant_state.Empty()) {
-                        shard->tenants.erase(tenant_it);
-                    }
+                if (evict_result.revalidation_skipped) {
+                    no_pin_objects.push_back(c.lease_timeout);
+                }
 
-                    evicted_count += evict_result.evicted_objects;
-                    evicted_this_pass += evict_result.evicted_objects;
+                evicted_count += evict_result.evicted_objects;
+                evicted_this_pass += evict_result.evicted_objects;
+                if (evict_result.evicted_objects > 0) {
+                    evicted_shards.set(c.shard_idx);
+                }
+                if (evict_result.stop_scan) {
+                    stop_eviction_scan = true;
                 }
                 deferred_replicas.clear();
             }
@@ -8686,7 +12101,8 @@ void MasterService::BatchEvict(double evict_ratio_target,
         // remainder of the current no-soft-pin population. This recovery
         // scan is paid only on churn and preserves the behavior of
         // continuing past the cutoff until evict_num is reached.
-        if (compact_frontier_used && evicted_this_pass < evict_num) {
+        if (!stop_eviction_scan && compact_frontier_used &&
+            evicted_this_pass < evict_num) {
             auto refill_candidates = collect_candidates(
                 /*use_cutoff=*/true, reserve_cutoff,
                 /*collect_older_or_equal=*/false);
@@ -8710,7 +12126,7 @@ void MasterService::BatchEvict(double evict_ratio_target,
     // Do second pass eviction only if 1). there are candidates that can be
     // evicted AND 2). The evicted number in the first pass is less than
     // evict_ratio_lowerbound.
-    if (target_evict_num > 0) {
+    if (!stop_eviction_scan && target_evict_num > 0) {
         if (target_evict_num <= static_cast<long>(no_pin_objects.size())) {
             // Second pass A: only evict objects without soft pin.
             std::nth_element(no_pin_objects.begin(),
@@ -8719,50 +12135,44 @@ void MasterService::BatchEvict(double evict_ratio_target,
             auto target_timeout = no_pin_objects[target_evict_num - 1];
 
             // Evict via key lookup — avoid full metadata traversal
-            for (size_t i = 0; i < kNumShards && target_evict_num > 0; i++) {
+            for (size_t i = 0;
+                 i < kNumShards && target_evict_num > 0 && !stop_eviction_scan;
+                 i++) {
+                const size_t shard_idx = (start_idx + i) % kNumShards;
                 {
-                    MetadataShardAccessorRW shard(this,
-                                                  (start_idx + i) % kNumShards);
-                    for (auto tenant_it = shard->tenants.begin();
-                         tenant_it != shard->tenants.end() &&
-                         target_evict_num > 0;) {
-                        auto& tenant_state = tenant_it->second;
-                        auto it = tenant_state.metadata.begin();
-                        while (it != tenant_state.metadata.end() &&
-                               target_evict_num > 0) {
-                            if (!it->second.IsHardPinned() &&
-                                it->second.IsLeaseExpired(now) &&
-                                it->second.lease_timeout <= target_timeout &&
-                                !it->second.IsSoftPinned(now) &&
-                                can_evict_replicas(it->second)) {
-                                auto evict_result = try_evict_group_or_object(
-                                    tenant_it->first, it->first, it->second,
-                                    shard, tenant_state, deferred_replicas,
-                                    /*allow_soft_pinned=*/false);
-                                total_freed_size += evict_result.freed_bytes;
-                                if (!enable_oplog_ && !it->second.IsGrouped()) {
-                                    PublishKvRemovedAfterEvict(
-                                        it->first, evict_result.freed_bytes,
-                                        "cpu", it->second, tenant_it->first);
-                                }
-                                if (!enable_oplog_ && !it->second.IsValid()) {
-                                    it = EraseMetadata(
-                                        tenant_state, it, tenant_it->first,
-                                        QuotaEraseMode::kFull, &shard);
-                                } else {
-                                    ++it;
+                    std::vector<std::pair<TenantId, std::string>> to_evict;
+                    {
+                        MetadataShardAccessorRW shard(this, shard_idx);
+                        for (auto tenant_it = shard->tenants.begin();
+                             tenant_it != shard->tenants.end(); ++tenant_it) {
+                            auto& tenant_state = tenant_it->second;
+                            for (auto it = tenant_state.metadata.begin();
+                                 it != tenant_state.metadata.end(); ++it) {
+                                if (!it->second.IsHardPinned() &&
+                                    now >= it->second.EvictionDeadline() &&
+                                    it->second.EvictionDeadline() <=
+                                        target_timeout &&
+                                    !IsSoftPinActive(it->second, now) &&
+                                    can_evict_replicas(it->second)) {
+                                    to_evict.emplace_back(tenant_it->first,
+                                                          it->first);
                                 }
-                                evicted_count += evict_result.evicted_objects;
-                                target_evict_num -=
-                                    evict_result.evicted_objects;
-                            } else {
-                                ++it;
                             }
                         }
-                        if (tenant_state.Empty()) {
-                            tenant_it = shard->tenants.erase(tenant_it);
-                        } else {
-                            ++tenant_it;
+                    }
+                    for (auto& c : to_evict) {
+                        if (target_evict_num <= 0 || stop_eviction_scan) break;
+                        auto evict_result = try_evict_group_or_object(
+                            c.first, c.second, shard_idx,
+                            /*allow_soft_pinned=*/false, deferred_replicas);
+                        total_freed_size += evict_result.freed_bytes;
+                        evicted_count += evict_result.evicted_objects;
+                        target_evict_num -= evict_result.evicted_objects;
+                        if (evict_result.evicted_objects > 0) {
+                            evicted_shards.set(shard_idx);
+                        }
+                        if (evict_result.stop_scan) {
+                            stop_eviction_scan = true;
                         }
                     }
                 }
@@ -8779,55 +12189,46 @@ void MasterService::BatchEvict(double evict_ratio_target,
                 soft_pin_objects.end());
             auto soft_target_timeout = soft_pin_objects[soft_pin_evict_num - 1];
 
-            for (size_t i = 0; i < kNumShards && target_evict_num > 0; i++) {
+            for (size_t i = 0;
+                 i < kNumShards && target_evict_num > 0 && !stop_eviction_scan;
+                 i++) {
+                const size_t shard_idx = (start_idx + i) % kNumShards;
                 {
-                    MetadataShardAccessorRW shard(this,
-                                                  (start_idx + i) % kNumShards);
-
-                    for (auto tenant_it = shard->tenants.begin();
-                         tenant_it != shard->tenants.end() &&
-                         target_evict_num > 0;) {
-                        auto& tenant_state = tenant_it->second;
-                        auto it = tenant_state.metadata.begin();
-                        while (it != tenant_state.metadata.end() &&
-                               target_evict_num > 0) {
-                            if (it->second.IsHardPinned() ||
-                                !it->second.IsLeaseExpired(now) ||
-                                !can_evict_replicas(it->second)) {
-                                ++it;
-                                continue;
-                            }
-                            if (!it->second.IsSoftPinned(now) ||
-                                it->second.lease_timeout <=
-                                    soft_target_timeout) {
-                                auto evict_result = try_evict_group_or_object(
-                                    tenant_it->first, it->first, it->second,
-                                    shard, tenant_state, deferred_replicas,
-                                    /*allow_soft_pinned=*/true);
-                                total_freed_size += evict_result.freed_bytes;
-                                if (!enable_oplog_ && !it->second.IsGrouped()) {
-                                    PublishKvRemovedAfterEvict(
-                                        it->first, evict_result.freed_bytes,
-                                        "cpu", it->second, tenant_it->first);
+                    std::vector<std::pair<TenantId, std::string>> to_evict;
+                    {
+                        MetadataShardAccessorRW shard(this, shard_idx);
+                        for (auto tenant_it = shard->tenants.begin();
+                             tenant_it != shard->tenants.end(); ++tenant_it) {
+                            auto& tenant_state = tenant_it->second;
+                            for (auto it = tenant_state.metadata.begin();
+                                 it != tenant_state.metadata.end(); ++it) {
+                                if (it->second.IsHardPinned() ||
+                                    now < it->second.EvictionDeadline() ||
+                                    !can_evict_replicas(it->second)) {
+                                    continue;
                                 }
-                                if (!enable_oplog_ && !it->second.IsValid()) {
-                                    it = EraseMetadata(
-                                        tenant_state, it, tenant_it->first,
-                                        QuotaEraseMode::kFull, &shard);
-                                } else {
-                                    ++it;
+                                if (!IsSoftPinActive(it->second, now) ||
+                                    it->second.EvictionDeadline() <=
+                                        soft_target_timeout) {
+                                    to_evict.emplace_back(tenant_it->first,
+                                                          it->first);
                                 }
-                                evicted_count += evict_result.evicted_objects;
-                                target_evict_num -=
-                                    evict_result.evicted_objects;
-                            } else {
-                                ++it;
                             }
                         }
-                        if (tenant_state.Empty()) {
-                            tenant_it = shard->tenants.erase(tenant_it);
-                        } else {
-                            ++tenant_it;
+                    }
+                    for (auto& c : to_evict) {
+                        if (target_evict_num <= 0 || stop_eviction_scan) break;
+                        auto evict_result = try_evict_group_or_object(
+                            c.first, c.second, shard_idx,
+                            /*allow_soft_pinned=*/true, deferred_replicas);
+                        total_freed_size += evict_result.freed_bytes;
+                        evicted_count += evict_result.evicted_objects;
+                        target_evict_num -= evict_result.evicted_objects;
+                        if (evict_result.evicted_objects > 0) {
+                            evicted_shards.set(shard_idx);
+                        }
+                        if (evict_result.stop_scan) {
+                            stop_eviction_scan = true;
                         }
                     }
                 }
@@ -8846,20 +12247,32 @@ void MasterService::BatchEvict(double evict_ratio_target,
         }
     }
 
-    if (evicted_count > 0 || released_discarded_cnt > 0) {
-        need_mem_eviction_ = false;
+    // erase() never returns bucket memory, so a shard that once held far
+    // more keys than it does now would keep its high-water bucket array
+    // forever. Shrink the metadata maps of the shards that evicted this
+    // cycle. The shard lock is held, and the loop iterates `tenants`, not
+    // the map being rehashed, so no live iterator is invalidated.
+    for (size_t i = 0; i < kNumShards; i++) {
+        if (!evicted_shards.test(i)) continue;
+        MetadataShardAccessorRW shard(this, i);
+        for (auto& tenant : shard->tenants) {
+            ShrinkBucketsIfSparse(tenant.second.metadata);
+        }
+    }
+
+    const bool made_progress = evicted_count > 0 || released_discarded_cnt > 0;
+    const bool success = made_progress || offload_deferred_count > 0;
+    if (allocation_pressure && !stop_eviction_scan && !success &&
+        total_eviction_base > 0) {
+        need_mem_eviction_.store(true, std::memory_order_relaxed);
+    }
+
+    if (success) {
         MasterMetricManager::instance().inc_eviction_success(evicted_count,
                                                              total_freed_size);
         MasterMetricManager::instance().inc_mem_eviction_success(
             evicted_count, total_freed_size);
-    } else if (offload_deferred_count > 0) {
-        need_mem_eviction_ = false;
-        MasterMetricManager::instance().inc_eviction_success(0, 0);
-        MasterMetricManager::instance().inc_mem_eviction_success(0, 0);
     } else {
-        if (total_eviction_base == 0) {
-            need_mem_eviction_ = false;
-        }
         MasterMetricManager::instance().inc_eviction_fail();
         MasterMetricManager::instance().inc_mem_eviction_fail();
     }
@@ -8925,6 +12338,7 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
     long evicted_count = 0;
     long object_count = 0;
     uint64_t total_freed_size = 0;
+    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
 
     auto is_evictable_nof_replica = [](const Replica& replica) {
         return replica.is_nof_replica() && replica.is_completed() &&
@@ -8956,7 +12370,7 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
                  shard_evicted_count < ideal_evict_num;) {
                 auto& metadata = it->second;
                 if (metadata.IsHardPinned() || !metadata.IsLeaseExpired(now) ||
-                    metadata.IsSoftPinned(now)) {
+                    IsSoftPinActive(metadata, now)) {
                     ++it;
                     continue;
                 }
@@ -9013,9 +12427,7 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
                                 std::move(reservation.value()), OpType::PUT_END,
                                 tenant_it->first.value(), it->first,
                                 SerializeMetadataForOpLogFromReplicaDescriptors(
-                                    metadata.client_id, metadata.size,
-                                    remaining, metadata.group_id,
-                                    metadata.data_type),
+                                    metadata, remaining),
                                 [this, removed_ids = std::move(removed_ids)](
                                     const OpLogEntry& durable_entry) {
                                     FinalizeRemovedReplicasAfterDurable(
@@ -9049,8 +12461,7 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
                             OpType::PUT_END, tenant_it->first.value(),
                             it->first,
                             SerializeMetadataForOpLogFromReplicaDescriptors(
-                                metadata.client_id, metadata.size, remaining,
-                                metadata.group_id, metadata.data_type),
+                                metadata, remaining),
                             nullptr);
                     }
                     if (!persist_result) {
@@ -9073,8 +12484,8 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
 
                 total_freed_size += metadata.size * erased;
                 shard_evicted_count++;
-                PublishKvRemovedAfterEvict(it->first, metadata.size * erased,
-                                           "disk", metadata, tenant_it->first);
+                PublishKvRemovedAfterEvict(it->first, erased, "disk", metadata,
+                                           tenant_it->first);
                 if (!metadata.IsValid()) {
                     it = EraseMetadata(tenant_state, it, tenant_it->first,
                                        QuotaEraseMode::kFull, &shard);
@@ -9111,115 +12522,119 @@ void MasterService::NoFBatchEvict(double evict_ratio_target,
 }
 
 void MasterService::ClientMonitorFunc() {
-    std::unordered_map<UUID, std::chrono::steady_clock::time_point,
-                       boost::hash<UUID>>
-        client_ttl;
     while (client_monitor_running_) {
-        auto now = std::chrono::steady_clock::now();
-
-        // Update the client ttl
-        PodUUID pod_client_id;
-        while (client_ping_queue_.pop(pod_client_id)) {
-            UUID client_id = {pod_client_id.first, pod_client_id.second};
-            client_ttl[client_id] =
-                now + std::chrono::seconds(client_live_ttl_sec_);
-        }
-
-        // Find out expired clients
-        std::vector<UUID> expired_clients;
-        for (auto it = client_ttl.begin(); it != client_ttl.end();) {
-            if (it->second < now) {
-                LOG(INFO) << "client_id=" << it->first
-                          << ", action=client_expired";
-                expired_clients.push_back(it->first);
-                it = client_ttl.erase(it);
-            } else {
-                ++it;
-            }
-        }
-
-        // Update the client status to NEED_REMOUNT
-        if (!expired_clients.empty()) {
-            // Notify graceful unmount scheduler to drop pending records
-            // for expired clients. The actual unmount is handled below.
-            for (auto& cid : expired_clients) {
-                graceful_unmount_scheduler_.RemoveIf(
-                    [&cid](const GracefulUnmountDeadlineRecord& record) {
-                        return record.client_id == cid;
-                    });
+        const auto now = ClientLivenessRecord::Clock::now();
+        std::vector<std::pair<UUID, std::shared_ptr<ClientLivenessRecord>>>
+            clients;
+        {
+            std::shared_lock<std::shared_mutex> lock(client_mutex_);
+            clients.reserve(client_liveness_records_.size());
+            for (const auto& entry : client_liveness_records_) {
+                clients.push_back(entry);
             }
+        }
 
-            // Record which segments are unmounted, will be used in the commit
-            // phase.
-            std::vector<UUID> unmount_segments;
-            std::vector<size_t> dec_capacities;
-            std::vector<UUID> client_ids;
-            std::vector<std::string> segment_names;
-            std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-            {
-                // Lock client_mutex and segment_mutex
-                std::unique_lock<std::shared_mutex> lock(client_mutex_);
-                for (auto& client_id : expired_clients) {
-                    auto it = ok_client_.find(client_id);
-                    if (it != ok_client_.end()) {
-                        ok_client_.erase(it);
-                        MasterMetricManager::instance().dec_active_clients();
+        for (const auto& [client_id, record] : clients) {
+            const auto transition = record->EvaluateAndRetire(
+                now, std::chrono::seconds(client_active_ttl_sec_),
+                std::chrono::seconds(client_suspicion_ttl_sec_),
+                [&] { client_offboarding_worker_.ReserveJob(); },
+                [&] {
+                    {
+                        std::unique_lock<std::shared_mutex> client_lock(
+                            client_mutex_);
+                        const auto current =
+                            client_liveness_records_.find(client_id);
+                        CHECK(current != client_liveness_records_.end());
+                        CHECK(current->second == record);
+                        if (ok_client_.erase(client_id) != 0) {
+                            MasterMetricManager::instance()
+                                .dec_active_clients();
+                        }
+                        client_host_id_.erase(client_id);
                     }
-                    client_host_id_.erase(client_id);
-                }
+                    graceful_unmount_scheduler_.RemoveIf(
+                        [&client_id](
+                            const GracefulUnmountDeadlineRecord& pending) {
+                            return pending.client_id == client_id;
+                        });
 
-                ScopedSegmentAccess segment_access =
-                    segment_manager_.getSegmentAccess();
-                for (auto& client_id : expired_clients) {
-                    // mounted mem segemtns of this expired client
-                    std::vector<Segment> segments;
-                    segment_access.GetClientSegments(client_id, segments);
-                    for (auto& seg : segments) {
-                        size_t metrics_dec_capacity = 0;
-                        if (segment_access.PrepareUnmountSegment(
-                                seg.id, metrics_dec_capacity) ==
-                            ErrorCode::OK) {
-                            unmount_segments.push_back(seg.id);
-                            dec_capacities.push_back(metrics_dec_capacity);
-                            client_ids.push_back(client_id);
-                            segment_names.push_back(seg.name);
-                        } else {
-                            LOG(ERROR) << "client_id=" << client_id
-                                       << ", segment_name=" << seg.name
-                                       << ", "
-                                          "error=prepare_unmount_expired_"
-                                          "mem_segment_failed";
+                    ClientOffboardingJob job;
+                    job.client_id = client_id;
+                    job.liveness = record;
+                    std::shared_lock<std::shared_mutex> snapshot_lock(
+                        snapshot_mutex_);
+                    {
+                        ScopedSegmentAccess segment_access =
+                            segment_manager_.getSegmentAccess();
+                        std::vector<Segment> segments;
+                        const auto get_result =
+                            segment_access.GetClientSegments(client_id,
+                                                             segments);
+                        if (get_result == ErrorCode::OK) {
+                            for (const auto& segment : segments) {
+                                SegmentStatus status = SegmentStatus::UNDEFINED;
+                                const auto status_result =
+                                    segment_access.GetSegmentStatusById(
+                                        segment.id, status);
+                                if (status_result ==
+                                    ErrorCode::SEGMENT_NOT_FOUND) {
+                                    continue;
+                                }
+                                if (status_result == ErrorCode::OK &&
+                                    status == SegmentStatus::UNMOUNTING) {
+                                    job.pending_prepare_segments.push_back(
+                                        {.segment_id = segment.id,
+                                         .segment_name = segment.name,
+                                         .transport_endpoint =
+                                             segment.te_endpoint});
+                                    continue;
+                                }
+
+                                size_t metrics_dec_capacity = 0;
+                                const auto prepare_result =
+                                    segment_access.PrepareUnmountSegment(
+                                        segment.id, metrics_dec_capacity);
+                                if (prepare_result == ErrorCode::OK) {
+                                    job.prepared_segments.push_back(
+                                        {.segment_id = segment.id,
+                                         .segment_name = segment.name,
+                                         .transport_endpoint =
+                                             segment.te_endpoint,
+                                         .metrics_dec_capacity =
+                                             metrics_dec_capacity});
+                                } else if (prepare_result !=
+                                           ErrorCode::SEGMENT_NOT_FOUND) {
+                                    job.pending_prepare_segments.push_back(
+                                        {.segment_id = segment.id,
+                                         .segment_name = segment.name,
+                                         .transport_endpoint =
+                                             segment.te_endpoint});
+                                    LOG(ERROR)
+                                        << "client_id=" << client_id
+                                        << ", segment_name=" << segment.name
+                                        << ", action=prepare_client_offboarding"
+                                        << ", error="
+                                        << toString(prepare_result);
+                                }
+                            }
                         }
                     }
-                }
-            }  // Release the mutex before long-running ClearInvalidHandles and
-               // avoid deadlocks
 
-            // Always clean up invalid handles when there are expired clients,
-            // even if no memory segments were unmounted. This is necessary
-            // to clean up local_disk replicas whose owner client has expired.
-            ClearInvalidHandles();
+                    MasterMetricManager::instance()
+                        .client_liveness_became_offline();
+                    client_offboarding_worker_.ScheduleReserved(std::move(job));
+                });
 
-            // Commit unmount of memory segments and clean up local_disk
-            // segments for expired clients. Both require the exclusive
-            // segment lock.
-            {
-                ScopedSegmentAccess segment_access =
-                    segment_manager_.getSegmentAccess();
-                for (size_t i = 0; i < unmount_segments.size(); i++) {
-                    segment_access.CommitUnmountSegment(
-                        unmount_segments[i], client_ids[i], dec_capacities[i]);
-                    LOG(INFO) << "client_id=" << client_ids[i]
-                              << ", segment_name=" << segment_names[i]
-                              << ", action=unmount_expired_mem_segment";
-                    // Clean up HTTP metadata if enabled
-                    cleanupHttpMetadata(segment_names[i]);
-                }
-                for (auto& client_id : expired_clients) {
-                    segment_access.UnmountLocalDiskSegment(client_id);
-                }
+            if (transition == ClientLivenessTransition::BECAME_SUSPECTED) {
+                MasterMetricManager::instance()
+                    .client_liveness_became_suspected();
+                LOG(INFO) << "client_id=" << client_id
+                          << ", action=client_liveness_suspected";
+            } else if (transition == ClientLivenessTransition::BECAME_OFFLINE) {
+                LOG(INFO) << "client_id=" << client_id
+                          << ", action=client_liveness_offline";
             }
-            RecomputeTenantEffectiveQuotas();
         }
 
         std::this_thread::sleep_for(
@@ -9257,6 +12672,10 @@ bool MasterService::TryUnmountNoFSegmentByHeartbeat(
     const MountedNoFSegmentSnapshot& snapshot,
     const std::string& error_reason) {
     size_t metrics_dec_capacity = 0;
+    std::shared_lock<std::shared_mutex> client_lock(client_mutex_);
+    std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+    auto retaining_clients = GetRetainingClientIdsLocked();
+    client_lock.unlock();
     {
         auto nof_segment_access = nof_segment_manager_.getNoFSegmentAccess();
         ErrorCode err = nof_segment_access.PrepareUnmountSegment(
@@ -9280,7 +12699,7 @@ bool MasterService::TryUnmountNoFSegmentByHeartbeat(
         }
     }
 
-    ClearInvalidHandles();
+    ClearInvalidHandles(retaining_clients);
 
     {
         auto nof_segment_access = nof_segment_manager_.getNoFSegmentAccess();
@@ -9643,7 +13062,12 @@ MasterService::MetadataSerializer::Deserialize(
 
         const msgpack::object& shard_obj = shard_oh.get();
 
-        // Get shard reference and deserialize
+        // Objects are restored to the shard index recorded in the snapshot and
+        // then re-routed to their hash(tenant, key) shard by
+        // ReRouteRestoredObjectsByKey() below. Snapshots produced by a router
+        // that placed grouped objects on hash(group_id) shards are therefore
+        // migrated automatically and need not be regenerated. See
+        // docs/source/design/store/mooncake-store.md.
         auto& shard = service_->metadata_shards_[shard_idx];
         auto result = DeserializeShard(shard_obj, shard);
         if (!result) {
@@ -9677,20 +13101,23 @@ MasterService::MetadataSerializer::Deserialize(
     auto next_id = replica_next_id_obj->as<uint64_t>();
     Replica::next_id_.store(next_id);
     LOG(INFO) << "Restored Replica::next_id_ to " << next_id;
-    service_->RebuildGroupRoutingIndex();
+    // Migrate old-format snapshots: re-route objects to their hash(tenant, key)
+    // shards before rebuilding the group domain (which is derived from
+    // metadata).
+    service_->ReRouteRestoredObjectsByKey();
+    service_->RebuildGroupState();
     service_->ClearCandidatesForReload();
     return {};
 }
 
 void MasterService::MetadataSerializer::Reset() {
+    service_->soft_pin_deadline_index_.Clear();
     for (auto& shard : service_->metadata_shards_) {
         shard.tenants.clear();
     }
     {
-        std::unique_lock<std::shared_mutex> lock(
-            service_->group_routing_mutex_);
-        service_->object_group_ids_.clear();
-        service_->groups_needing_lease_refresh_.clear();
+        GroupDomainAccessorRW group_domain(service_);
+        group_domain->groups.clear();
     }
     {
         std::lock_guard lock(service_->discarded_replicas_mutex_);
@@ -9819,19 +13246,17 @@ MasterService::MetadataSerializer::DeserializeShard(const msgpack::object& obj,
         }
 
         auto metadata_ptr = std::move(metadata_result.value());
-        auto& tenant_state = shard.tenants[tenant_id];
+        auto& tenant_state = service_->GetOrCreateTenantState(shard, tenant_id);
         const std::string user_key = key;
         auto [it, inserted] = tenant_state.metadata.emplace(
             std::piecewise_construct, std::forward_as_tuple(std::move(key)),
             std::forward_as_tuple(
                 metadata_ptr->client_id, metadata_ptr->put_start_time,
-                metadata_ptr->size, metadata_ptr->PopReplicas(),
-                metadata_ptr->soft_pin_timeout.has_value(),
+                metadata_ptr->size, metadata_ptr->PopReplicas(), std::nullopt,
                 metadata_ptr->IsHardPinned(), metadata_ptr->data_type,
                 metadata_ptr->group_id, tenant_id, user_key));
 
-        it->second.lease_timeout = metadata_ptr->lease_timeout;
-        it->second.soft_pin_timeout = metadata_ptr->soft_pin_timeout;
+        it->second.lease_->ExtendTo(metadata_ptr->lease_->ExpiresAt());
         it->second.object_checksum = metadata_ptr->object_checksum;
 
         // Recompute disk_object_count for restored metadata
@@ -9847,8 +13272,7 @@ MasterService::MetadataSerializer::DeserializeShard(const msgpack::object& obj,
 
 tl::expected<void, SerializationError>
 MasterService::MetadataSerializer::SerializeMetadata(
-    const MasterService::ObjectMetadata& metadata,
-    MsgpackPacker& packer) const {
+    const ObjectMetadata& metadata, MsgpackPacker& packer) const {
     // Pack ObjectMetadata using array structure for efficiency
     // Format: [client_id, put_start_time, size, lease_timeout,
     // has_soft_pin_timeout, soft_pin_timeout, replicas_count, data_type,
@@ -9876,25 +13300,17 @@ MasterService::MetadataSerializer::SerializeMetadata(
     // Serialize size
     packer.pack(static_cast<uint64_t>(metadata.size));
 
-    // Serialize lease_timeout (convert to timestamp)
+    // Serialize the authoritative lease deadline (converted to timestamp).
     auto lease_timestamp =
         std::chrono::duration_cast<std::chrono::milliseconds>(
-            metadata.lease_timeout.time_since_epoch())
+            metadata.lease_->ExpiresAt().time_since_epoch())
             .count();
     packer.pack(lease_timestamp);
 
-    // Serialize soft_pin_timeout (if exists)
-    if (metadata.soft_pin_timeout.has_value()) {
-        packer.pack(true);  // Mark soft_pin_timeout exists
-        auto soft_pin_timestamp =
-            std::chrono::duration_cast<std::chrono::milliseconds>(
-                metadata.soft_pin_timeout.value().time_since_epoch())
-                .count();
-        packer.pack(soft_pin_timestamp);
-    } else {
-        packer.pack(false);        // Mark soft_pin_timeout does not exist
-        packer.pack(uint64_t(0));  // Placeholder
-    }
+    // Keep the legacy snapshot slots for format compatibility, but soft pin is
+    // runtime-only state and is intentionally not persisted.
+    packer.pack(false);
+    packer.pack(uint64_t(0));
 
     // Serialize replicas count
     packer.pack(static_cast<uint32_t>(metadata.CountReplicas()));
@@ -9920,7 +13336,7 @@ MasterService::MetadataSerializer::SerializeMetadata(
     return {};
 }
 
-tl::expected<std::unique_ptr<MasterService::ObjectMetadata>, SerializationError>
+tl::expected<std::unique_ptr<ObjectMetadata>, SerializationError>
 MasterService::MetadataSerializer::DeserializeMetadata(
     const msgpack::object& obj) const {
     // Check if input is a valid array
@@ -9960,11 +13376,22 @@ MasterService::MetadataSerializer::DeserializeMetadata(
     // Deserialize lease_timeout
     uint64_t lease_timestamp = array[index++].as<uint64_t>();
 
-    // Deserialize soft_pin_timeout flag
-    bool has_soft_pin_timeout = array[index++].as<bool>();
+    // Parse and discard the legacy soft-pin fields. Recovered objects always
+    // become ordinary cache.
+    (void)array[index++].as<bool>();
+    (void)array[index++].as<uint64_t>();
 
-    // Deserialize soft_pin_timeout value
-    uint64_t soft_pin_timestamp = array[index++].as<uint64_t>();
+    const auto max_timestamp =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::system_clock::time_point::max().time_since_epoch())
+            .count();
+    if (max_timestamp < 0 ||
+        put_start_time_timestamp > static_cast<uint64_t>(max_timestamp) ||
+        lease_timestamp > static_cast<uint64_t>(max_timestamp)) {
+        return tl::unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            "ObjectMetadata timestamp exceeds system_clock range"));
+    }
 
     // Deserialize replicas count
     uint32_t replicas_count = array[index++].as<uint32_t>();
@@ -10040,26 +13467,104 @@ MasterService::MetadataSerializer::DeserializeMetadata(
             "deserialize ObjectMetadata optional field type mismatch"));
     }
 
-    // Create ObjectMetadata instance
-    bool enable_soft_pin = has_soft_pin_timeout;
+    // Create ObjectMetadata instance. Soft pin is not restored.
     auto metadata = std::make_unique<ObjectMetadata>(
         client_id,
         std::chrono::system_clock::time_point(
             std::chrono::milliseconds(put_start_time_timestamp)),
-        size, std::move(replicas), enable_soft_pin, is_hard_pinned, data_type,
+        size, std::move(replicas), std::nullopt, is_hard_pinned, data_type,
         group_id);
     metadata->object_checksum = object_checksum;
-    metadata->lease_timeout = std::chrono::system_clock::time_point(
-        std::chrono::milliseconds(lease_timestamp));
+    metadata->lease_->ExtendTo(std::chrono::system_clock::time_point(
+        std::chrono::milliseconds(lease_timestamp)));
+
+    return metadata;
+}
 
-    // Set soft_pin_timeout (if exists)
-    if (has_soft_pin_timeout) {
-        metadata->soft_pin_timeout.emplace(
-            std::chrono::system_clock::time_point(
-                std::chrono::milliseconds(soft_pin_timestamp)));
+tl::expected<void, ErrorCode>
+MasterService::ValidateDynamicReplicaPendingForCopyStart(
+    TenantState& tenant_state, const std::string& key,
+    const UUID& dynamic_replication_lease_id, const UUID& client_id,
+    const std::string& source_segment, uint64_t current_version_epoch,
+    uint64_t dynamic_replication_version_epoch,
+    const std::vector<std::string>& target_segments) {
+    auto pending_it = tenant_state.dynamic_replication_pending.find(key);
+    const bool dynamic_copy = dynamic_replication_lease_id != UUID{};
+    if (pending_it == tenant_state.dynamic_replication_pending.end()) {
+        if (dynamic_copy) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        return {};
+    }
+    auto& pending = pending_it->second;
+    if (pending.expire_at_ms_epoch < DynamicReplicationNowMs()) {
+        ClearDynamicReplicationStateForKey(tenant_state, key);
+        if (dynamic_copy) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        return {};
+    }
+    if (!dynamic_copy) {
+        return tl::make_unexpected(ErrorCode::OBJECT_HAS_REPLICATION_TASK);
     }
+    if (pending.version_epoch != current_version_epoch) {
+        ClearDynamicReplicationStateForKey(tenant_state, key);
+        return tl::make_unexpected(ErrorCode::INVALID_VERSION);
+    }
+    if (pending.lease_id != dynamic_replication_lease_id ||
+        pending.version_epoch != dynamic_replication_version_epoch) {
+        return tl::make_unexpected(ErrorCode::INVALID_VERSION);
+    }
+    if (pending.source_segment != source_segment ||
+        target_segments.size() != 1 ||
+        target_segments.front() != pending.target_segment) {
+        return tl::make_unexpected(ErrorCode::OBJECT_HAS_REPLICATION_TASK);
+    }
+    ScopedSegmentAccess segment_access = segment_manager_.getSegmentAccess();
+    UUID source_client;
+    auto err = segment_access.GetClientIdBySegmentName(pending.source_segment,
+                                                       source_client);
+    if (err != ErrorCode::OK) {
+        return tl::make_unexpected(err);
+    }
+    if (source_client != client_id) {
+        return tl::make_unexpected(ErrorCode::ILLEGAL_CLIENT);
+    }
+    return {};
+}
 
-    return metadata;
+void MasterService::RegisterDynamicReplicaStart(
+    TenantState& tenant_state, ObjectMetadata& metadata, const std::string& key,
+    const std::string& source_segment, uint64_t version_epoch,
+    const std::vector<std::string>& target_segments,
+    const std::vector<ReplicaID>& replica_ids) {
+    auto pending_it = tenant_state.dynamic_replication_pending.find(key);
+    if (pending_it == tenant_state.dynamic_replication_pending.end()) {
+        return;
+    }
+    auto pending = pending_it->second;
+    tenant_state.dynamic_replication_pending.erase(pending_it);
+    if (pending.source_segment != source_segment ||
+        pending.expire_at_ms_epoch < DynamicReplicationNowMs() ||
+        pending.version_epoch != version_epoch) {
+        return;
+    }
+    for (size_t i = 0; i < target_segments.size() && i < replica_ids.size();
+         ++i) {
+        if (target_segments[i] != pending.target_segment) {
+            continue;
+        }
+        metadata.MarkDynamicReplica(
+            replica_ids[i], ObjectMetadata::DynamicReplicaRecord{
+                                .created_at = std::chrono::system_clock::now(),
+                                .source_segment = pending.source_segment,
+                                .target_segment = pending.target_segment,
+                                .target_domain = pending.target_domain,
+                                .complete = false});
+        return;
+    }
 }
 
 tl::expected<UUID, ErrorCode> MasterService::CreateCopyTask(
@@ -10071,50 +13576,104 @@ tl::expected<UUID, ErrorCode> MasterService::CreateCopyTask(
     }
     const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
                                    key};
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     if (targets.empty()) {
         LOG(ERROR) << "key=" << key << ", error=empty_targets";
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    MetadataAccessorRO accessor(this, object_id);
-    if (!accessor.Exists()) {
-        VLOG(1) << "key=" << key << ", info=object_not_found";
-        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
-    }
 
-    ScopedSegmentAccess segment_accessor = segment_manager_.getSegmentAccess();
-    for (const auto& target : targets) {
-        if (!segment_accessor.ExistsSegmentName(target)) {
-            LOG(ERROR) << "key=" << key << ", target_segment=" << target
-                       << ", error=target_segment_not_mounted";
-            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    std::vector<
+        std::tuple<std::string, UUID, std::shared_ptr<ClientLivenessRecord>>>
+        serving_sources;
+    {
+        std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+        MetadataAccessorRO accessor(this, object_id);
+        if (!accessor.Exists()) {
+            VLOG(1) << "key=" << key << ", info=object_not_found";
+            return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
         }
-        if (!segment_accessor.IsSegmentAllocatable(target)) {
-            LOG(ERROR) << "key=" << key << ", target_segment=" << target
-                       << ", error=target_segment_not_allocatable";
-            return tl::make_unexpected(
-                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+
+        const auto& metadata = accessor.Get();
+        ScopedSegmentAccess segment_accessor =
+            segment_manager_.getSegmentAccess();
+        for (const auto& target : targets) {
+            if (!segment_accessor.ExistsSegmentName(target)) {
+                LOG(ERROR) << "key=" << key << ", target_segment=" << target
+                           << ", error=target_segment_not_mounted";
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            if (!segment_accessor.IsSegmentAllocatable(target)) {
+                LOG(ERROR) << "key=" << key << ", target_segment=" << target
+                           << ", error=target_segment_not_allocatable";
+                return tl::make_unexpected(
+                    ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+            }
         }
-    }
 
-    const auto& metadata = accessor.Get();
-    const auto& segment_names = metadata.GetReplicaSegmentNames();
-    if (segment_names.empty()) {
+        metadata.VisitReplicas(
+            [this](const Replica& replica) {
+                return IsReplicaReadable(replica);
+            },
+            [&](const Replica& replica) {
+                for (const auto& segment_name : replica.get_segment_names()) {
+                    if (!segment_name) {
+                        continue;
+                    }
+                    UUID owner;
+                    if (segment_accessor.GetClientIdBySegmentName(
+                            *segment_name, owner) == ErrorCode::OK) {
+                        const auto liveness = replica.getClientLiveness();
+                        if (liveness) {
+                            serving_sources.emplace_back(*segment_name, owner,
+                                                         std::move(liveness));
+                        }
+                    }
+                }
+            });
+    }
+    if (serving_sources.empty()) {
         LOG(ERROR) << "key=" << key << ", error=no_valid_source_replicas";
-        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
 
-    // Randomly pick a segment from the source replicas
-    std::string selected_source_segment =
-        segment_names[randomIndex(segment_names.size())];
-    UUID select_client;
-    ErrorCode error = segment_accessor.GetClientIdBySegmentName(
-        selected_source_segment, select_client);
-    if (error != ErrorCode::OK) {
-        LOG(ERROR) << "key=" << key
-                   << ", segment_name=" << selected_source_segment
-                   << ", error=client_id_not_found";
-        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    const auto& [selected_source_segment, select_client, liveness] =
+        serving_sources[randomIndex(serving_sources.size())];
+    auto serving_guard = liveness->TryAcquireServingGuard();
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+
+    // Completion paths acquire the Client guard before the metadata shard.
+    // Reacquire and validate in that same order after discovery.
+    std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+    MetadataAccessorRO submission_metadata(this, object_id);
+    if (!submission_metadata.Exists()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    const auto& metadata = submission_metadata.Get();
+    ScopedSegmentAccess submission_access = segment_manager_.getSegmentAccess();
+    UUID current_source_client;
+    if (submission_access.GetClientIdBySegmentName(
+            selected_source_segment, current_source_client) != ErrorCode::OK ||
+        current_source_client != select_client ||
+        !metadata.HasReplica(
+            [this, &selected_source_segment](const Replica& replica) {
+                if (!IsReplicaReadable(replica)) {
+                    return false;
+                }
+                const auto names = replica.get_segment_names();
+                return std::any_of(
+                    names.begin(), names.end(),
+                    [&selected_source_segment](const auto& name) {
+                        return name && *name == selected_source_segment;
+                    });
+            })) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    for (const auto& target : targets) {
+        if (!submission_access.IsSegmentAllocatable(target)) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
     }
     return task_manager_.get_write_access()
         .submit_task_typed<TaskType::REPLICA_COPY>(
@@ -10133,13 +13692,6 @@ tl::expected<UUID, ErrorCode> MasterService::CreateMoveTask(
     }
     const ObjectIdentity object_id{std::move(normalized_tenant_result.value()),
                                    key};
-    std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
-    MetadataAccessorRO accessor(this, object_id);
-    if (!accessor.Exists()) {
-        VLOG(1) << "key=" << key << ", info=object_not_found";
-        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
-    }
-
     if (source == target) {
         LOG(ERROR) << "key=" << key << ", source_segment=" << source
                    << ", target_segment=" << target
@@ -10147,35 +13699,103 @@ tl::expected<UUID, ErrorCode> MasterService::CreateMoveTask(
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
 
-    ScopedSegmentAccess segment_accessor = segment_manager_.getSegmentAccess();
-    if (!segment_accessor.ExistsSegmentName(target)) {
-        LOG(ERROR) << "key=" << key << ", target_segment=" << target
-                   << ", error=target_segment_not_mounted";
-        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    bool source_exists = false;
+    bool source_is_serving = false;
+    UUID select_client;
+    std::shared_ptr<ClientLivenessRecord> source_liveness;
+    {
+        std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+        MetadataAccessorRO accessor(this, object_id);
+        if (!accessor.Exists()) {
+            VLOG(1) << "key=" << key << ", info=object_not_found";
+            return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+        }
+
+        const auto& metadata = accessor.Get();
+        ScopedSegmentAccess segment_accessor =
+            segment_manager_.getSegmentAccess();
+        if (!segment_accessor.ExistsSegmentName(target)) {
+            LOG(ERROR) << "key=" << key << ", target_segment=" << target
+                       << ", error=target_segment_not_mounted";
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        if (!segment_accessor.IsSegmentAllocatable(target)) {
+            LOG(ERROR) << "key=" << key << ", target_segment=" << target
+                       << ", error=target_segment_not_allocatable";
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+
+        metadata.VisitReplicas(
+            [](const Replica&) { return true; },
+            [this, &source, &source_exists, &source_is_serving,
+             &source_liveness](const Replica& replica) {
+                const auto names = replica.get_segment_names();
+                const bool matches = std::any_of(
+                    names.begin(), names.end(), [&source](const auto& name) {
+                        return name && *name == source;
+                    });
+                if (matches) {
+                    source_exists = true;
+                    if (IsReplicaReadable(replica)) {
+                        source_is_serving = true;
+                        source_liveness = replica.getClientLiveness();
+                    }
+                }
+            });
+        if (!source_exists) {
+            LOG(ERROR) << "key=" << key << ", source_segment=" << source
+                       << ", error=source_replica_not_found";
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        if (!source_is_serving) {
+            LOG(ERROR) << "key=" << key << ", source_segment=" << source
+                       << ", error=source_segment_not_serving";
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        ErrorCode error =
+            segment_accessor.GetClientIdBySegmentName(source, select_client);
+        if (error != ErrorCode::OK) {
+            LOG(ERROR) << "key=" << key << ", segment_name=" << source
+                       << ", error=client_id_not_found";
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
     }
-    if (!segment_accessor.IsSegmentAllocatable(target)) {
-        LOG(ERROR) << "key=" << key << ", target_segment=" << target
-                   << ", error=target_segment_not_allocatable";
+
+    if (!source_liveness) {
         return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
-
-    const auto& metadata = accessor.Get();
-    const auto& segment_names = metadata.GetReplicaSegmentNames();
-    if (std::find(segment_names.begin(), segment_names.end(), source) ==
-        segment_names.end()) {
-        LOG(ERROR) << "key=" << key << ", source_segment=" << source
-                   << ", error=source_segment_not_found";
-        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    auto serving_guard = source_liveness->TryAcquireServingGuard();
+    if (!serving_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
 
-    UUID select_client;
-    ErrorCode error =
-        segment_accessor.GetClientIdBySegmentName(source, select_client);
-
-    if (error != ErrorCode::OK) {
-        LOG(ERROR) << "key=" << key << ", segment_name=" << source
-                   << ", error=client_id_not_found";
-        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    // Do not hold a metadata shard while acquiring the Client guard: MoveEnd
+    // takes those locks in the opposite order.
+    std::shared_lock<std::shared_mutex> snapshot_lock(snapshot_mutex_);
+    MetadataAccessorRO submission_metadata(this, object_id);
+    if (!submission_metadata.Exists()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    const auto& metadata = submission_metadata.Get();
+    ScopedSegmentAccess submission_access = segment_manager_.getSegmentAccess();
+    UUID current_source_client;
+    if (submission_access.GetClientIdBySegmentName(
+            source, current_source_client) != ErrorCode::OK ||
+        current_source_client != select_client ||
+        !submission_access.IsSegmentAllocatable(target) ||
+        !metadata.HasReplica([this, &source](const Replica& replica) {
+            if (!IsReplicaReadable(replica)) {
+                return false;
+            }
+            const auto names = replica.get_segment_names();
+            return std::any_of(names.begin(), names.end(),
+                               [&source](const auto& name) {
+                                   return name && *name == source;
+                               });
+        })) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
     }
 
     return task_manager_.get_write_access()
@@ -10199,6 +13819,14 @@ tl::expected<QueryTaskResponse, ErrorCode> MasterService::QueryTask(
 
 tl::expected<std::vector<TaskAssignment>, ErrorCode> MasterService::FetchTasks(
     const UUID& client_id, size_t batch_size) {
+    const auto liveness = FindClientRecord(client_id);
+    if (!liveness) {
+        return std::vector<TaskAssignment>{};
+    }
+    auto serving_guard = liveness->TryAcquireServingGuard();
+    if (!serving_guard) {
+        return std::vector<TaskAssignment>{};
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     const auto& tasks =
         task_manager_.get_write_access().pop_tasks(client_id, batch_size);
@@ -10211,6 +13839,14 @@ tl::expected<std::vector<TaskAssignment>, ErrorCode> MasterService::FetchTasks(
 
 tl::expected<void, ErrorCode> MasterService::MarkTaskToComplete(
     const UUID& client_id, const TaskCompleteRequest& request) {
+    const auto liveness = FindClientRecord(client_id);
+    if (!liveness) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    auto retaining_guard = liveness->TryAcquireRetainingGuard();
+    if (!retaining_guard) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
     std::shared_lock<std::shared_mutex> shared_lock(snapshot_mutex_);
     auto write_access = task_manager_.get_write_access();
     ErrorCode err = write_access.complete_task(client_id, request.id,
@@ -10528,6 +14164,27 @@ void MasterService::ScheduleDrainJobTasks(DrainJob& job) {
                             continue;
                         }
 
+                        bool source_is_serving = false;
+                        metadata.VisitReplicas(
+                            [this, &source_segment](const Replica& replica) {
+                                if (!IsReplicaReadable(replica)) {
+                                    return false;
+                                }
+                                const auto names = replica.get_segment_names();
+                                return std::any_of(
+                                    names.begin(), names.end(),
+                                    [&source_segment](const auto& name) {
+                                        return name && *name == source_segment;
+                                    });
+                            },
+                            [&source_is_serving](const Replica&) {
+                                source_is_serving = true;
+                            });
+                        if (!source_is_serving) {
+                            blocked_unit_keys.insert(unit_key);
+                            continue;
+                        }
+
                         if (metadata.IsHardPinned() ||
                             !metadata.IsLeaseExpired() ||
                             !metadata.AllReplicas(&Replica::fn_is_completed) ||
@@ -10831,77 +14488,180 @@ KvEventConfig MasterService::BuildKvEventConfig(
     return kv_config;
 }
 
-std::string MasterService::MediumForReplicaType(ReplicaType replica_type) {
-    switch (replica_type) {
-        case ReplicaType::MEMORY:
-            return "cpu";
-        case ReplicaType::DISK:
-        case ReplicaType::LOCAL_DISK:
-        case ReplicaType::NOF_SSD:
-            return "disk";
-        case ReplicaType::ALL:
-        default:
-            return "cpu";
+// Every non-memory replica type, including DFS, is normalized to the "disk"
+// medium so subscribers see one logical tier per storage class.
+std::vector<std::string> MasterService::KvMediaForMetadata(
+    const ObjectMetadata& metadata) {
+    bool has_cpu = false;
+    bool has_disk = false;
+    metadata.VisitReplicas(
+        [](const Replica& replica) { return replica.is_completed(); },
+        [&](const Replica& replica) {
+            if (replica.is_memory_replica() &&
+                !replica.has_invalid_mem_handle()) {
+                has_cpu = true;
+            } else if (replica.is_nof_replica() &&
+                       !replica.has_invalid_nof_handle()) {
+                has_disk = true;
+            } else if (replica.is_disk_replica() ||
+                       replica.is_local_disk_replica() ||
+                       replica.is_dfs_replica()) {
+                has_disk = true;
+            }
+        });
+    std::vector<std::string> media;
+    if (has_cpu) {
+        media.emplace_back("cpu");
     }
+    if (has_disk) {
+        media.emplace_back("disk");
+    }
+    return media;
 }
 
-std::string MasterService::MediumForMetadata(const ObjectMetadata& metadata) {
-    if (metadata.HasMemReplica()) {
-        return "cpu";
+std::vector<std::string> MasterService::KvMediaForRemoval(
+    const ObjectMetadata& metadata) {
+    auto media = KvMediaForMetadata(metadata);
+    bool has_cpu = std::find(media.begin(), media.end(), "cpu") != media.end();
+    bool has_disk =
+        std::find(media.begin(), media.end(), "disk") != media.end();
+    // KvMediaForMetadata above only counts completed replicas. A removal path
+    // can run after a replica has moved to PROCESSING or REMOVED, and both
+    // states still had their medium announced to subscribers, so both must
+    // appear in the removal delta or the tier is never retracted.
+    metadata.VisitReplicas(
+        [](const Replica& replica) {
+            return replica.status() == ReplicaStatus::REMOVED ||
+                   replica.status() == ReplicaStatus::PROCESSING;
+        },
+        [&](const Replica& replica) {
+            if (replica.is_memory_replica()) {
+                has_cpu = true;
+            } else if (replica.is_nof_replica() || replica.is_disk_replica() ||
+                       replica.is_local_disk_replica() ||
+                       replica.is_dfs_replica()) {
+                has_disk = true;
+            }
+        });
+    if (has_cpu &&
+        std::find(media.begin(), media.end(), "cpu") == media.end()) {
+        media.emplace_back("cpu");
     }
-    if (metadata.HasReplica(&Replica::fn_is_nof_replica) ||
-        metadata.HasReplica(&Replica::fn_is_disk_replica) ||
-        metadata.HasReplica(&Replica::fn_is_local_disk_replica)) {
-        return "disk";
+    if (has_disk &&
+        std::find(media.begin(), media.end(), "disk") == media.end()) {
+        media.emplace_back("disk");
     }
-    return "cpu";
+    return media;
 }
 
 void MasterService::PublishKvStored(const std::string& key,
-                                    ReplicaType replica_type,
                                     const ObjectMetadata& metadata,
                                     const TenantId& tenant_id) {
+    // The epoch is bumped even when no publisher is listening so that the
+    // ordering rule is testable, and always before the enqueue below: a
+    // concurrent RemoveAll must either see the new epoch and withhold its
+    // `cleared`, or have already published it ahead of this `stored`.
+    BumpKvTenantEpoch(tenant_id.value());
     if (!kv_event_publisher_ || !kv_event_publisher_->enabled()) {
         return;
     }
-    std::string medium = MediumForReplicaType(replica_type);
-    if (replica_type == ReplicaType::ALL) {
-        medium = MediumForMetadata(metadata);
-    }
-    kv_event_publisher_->PublishStored(key, medium, tenant_id,
-                                       metadata.group_id);
+    kv_event_publisher_->PublishCommitted(key, KvMediaForMetadata(metadata),
+                                          tenant_id.value(), metadata.group_id);
 }
 
-void MasterService::PublishKvRemoved(const std::string& key,
-                                     const std::string& medium,
-                                     const TenantId& tenant_id,
-                                     const std::string& group_id) {
-    if (!kv_event_publisher_ || !kv_event_publisher_->enabled()) {
+void MasterService::SyncKvObjectState(
+    const std::string& key, const ObjectMetadata& metadata,
+    const TenantId& tenant_id,
+    const std::vector<std::string>& previous_media_hint) {
+    const bool publishing =
+        kv_event_publisher_ && kv_event_publisher_->enabled();
+    if (!publishing && !kv_track_tenant_epochs_) {
         return;
     }
-    kv_event_publisher_->PublishRemoved(key, medium, tenant_id, group_id);
+    auto current_media = KvMediaForMetadata(metadata);
+    // Only an object that still has a medium can contradict a `cleared`. Sync
+    // calls that end with no medium left are retractions, which a clear may
+    // safely follow.
+    if (!current_media.empty()) {
+        BumpKvTenantEpoch(tenant_id.value());
+    }
+    if (!publishing) {
+        return;
+    }
+    kv_event_publisher_->SyncObjectState(key, current_media, tenant_id.value(),
+                                         metadata.group_id,
+                                         previous_media_hint);
 }
 
-void MasterService::PublishKvRemoved(const std::string& key,
-                                     const ObjectMetadata& metadata,
-                                     const TenantId& tenant_id) {
-    PublishKvRemoved(key, MediumForMetadata(metadata), tenant_id,
-                     metadata.group_id);
+void MasterService::PublishKvRemoved(
+    const std::string& key, const ObjectMetadata& metadata,
+    const TenantId& tenant_id,
+    const std::vector<std::string>& previous_media_hint) {
+    if (!kv_event_publisher_ || !kv_event_publisher_->enabled()) {
+        return;
+    }
+    auto previous_media = KvRemovalSnapshot(metadata);
+    previous_media.insert(previous_media.end(), previous_media_hint.begin(),
+                          previous_media_hint.end());
+    kv_event_publisher_->PublishObjectRemoved(
+        key, tenant_id.value(), metadata.group_id, previous_media);
 }
 
 void MasterService::PublishKvRemovedAfterEvict(const std::string& key,
-                                               uint64_t freed_bytes,
+                                               size_t evicted_replica_count,
                                                const std::string& medium,
                                                const ObjectMetadata& metadata,
                                                const TenantId& tenant_id) {
-    (void)freed_bytes;
-    (void)medium;
+    if (evicted_replica_count == 0) {
+        return;
+    }
     if (!kv_event_publisher_ || !kv_event_publisher_->enabled()) {
         return;
     }
+    // The object lost its last replica, so the caller is about to erase it and
+    // EraseMetadata publishes the full removal itself. Emitting here as well
+    // would repeat every medium. This mirrors the oplog eviction path, which
+    // already chooses between EraseMetadata and SyncKvObjectState.
     if (!metadata.IsValid()) {
-        PublishKvRemoved(key, metadata, tenant_id);
+        return;
+    }
+    // The object survives. Feeding the evicted medium in as part of the
+    // previous set lets the delta drop it, unless another replica still lives
+    // on it.
+    auto previous_media = KvMediaForMetadata(metadata);
+    if (std::find(previous_media.begin(), previous_media.end(), medium) ==
+        previous_media.end()) {
+        previous_media.push_back(medium);
+    }
+    SyncKvObjectState(key, metadata, tenant_id, previous_media);
+}
+
+void MasterService::PublishKvCleared(const TenantId& tenant_id) {
+    if (!kv_event_publisher_ || !kv_event_publisher_->enabled()) {
+        return;
+    }
+    kv_event_publisher_->PublishCleared(tenant_id.value());
+}
+
+void MasterService::PublishKvClearedIfEpochUnchanged(const TenantId& tenant_id,
+                                                     uint64_t expected_epoch) {
+    if (!kv_track_tenant_epochs_) {
+        PublishKvCleared(tenant_id);
+        return;
+    }
+    // Holding the epoch lock across the publish is what makes this a barrier
+    // rather than a racy re-check: a commit that wants to announce this tenant
+    // has to wait for the lock, and will then find the clear already enqueued.
+    std::lock_guard<std::mutex> lock(kv_tenant_epoch_mutex_);
+    if (kv_tenant_epochs_[KvTenantEpochSlot(tenant_id.value())] !=
+        expected_epoch) {
+        // A commit landed in an already-scanned shard. Its `stored` is on the
+        // wire, so a clear here would retract a live object.
+        kv_cleared_suppressed_by_epoch_.fetch_add(1, std::memory_order_relaxed);
+        return;
     }
+    kv_cleared_published_.fetch_add(1, std::memory_order_relaxed);
+    PublishKvCleared(tenant_id);
 }
 
 bool MasterService::KvEventsEnabled() const {
@@ -11050,6 +14810,7 @@ std::string MasterService::SerializeMetadataForOpLog(
     payload.size = metadata.size;
     payload.group_id = metadata.group_id;
     payload.data_type = metadata.data_type;
+    payload.hard_pinned = metadata.IsHardPinned();
 
     // Extract replica descriptors - get them all at once
     const auto& replicas = metadata.GetAllReplicas();
@@ -11075,6 +14836,7 @@ std::string MasterService::SerializeMetadataForOpLogWithoutMemReplicas(
     payload.size = metadata.size;
     payload.group_id = metadata.group_id;
     payload.data_type = metadata.data_type;
+    payload.hard_pinned = metadata.IsHardPinned();
 
     const auto& replicas = metadata.GetAllReplicas();
     payload.replicas.reserve(replicas.size());
@@ -11090,24 +14852,29 @@ std::string MasterService::SerializeMetadataForOpLogWithoutMemReplicas(
 }
 
 std::string MasterService::SerializeMetadataForOpLogFromReplicaDescriptors(
-    const UUID& client_id, uint64_t size,
-    const std::vector<Replica::Descriptor>& replicas,
-    const std::string& group_id, ObjectDataType data_type) const {
+    const ObjectMetadata& metadata,
+    const std::vector<Replica::Descriptor>& replicas) const {
     MetadataPayload payload;
-    payload.client_id = client_id;
-    payload.size = size;
+    payload.client_id = metadata.client_id;
+    payload.size = metadata.size;
     payload.replicas = replicas;
-    payload.group_id = group_id;
-    payload.data_type = data_type;
+    payload.group_id = metadata.group_id;
+    payload.data_type = metadata.data_type;
+    payload.hard_pinned = metadata.IsHardPinned();
     auto result = struct_pack::serialize(payload);
     return std::string(result.begin(), result.end());
 }
 
 ErrorCode MasterService::InitializeBatchOpLogWriter(
-    std::shared_ptr<HaKvBackend> backend) {
+    std::shared_ptr<HaKvBackend> backend, bool require_fenced_writer) {
     if (!backend || !backend->SupportsTxn()) {
         return ErrorCode::INVALID_PARAMS;
     }
+    if (require_fenced_writer && view_version_ == 0) {
+        LOG(ERROR) << "Fenced batch OpLog writer requires a non-zero acquired "
+                      "producer view";
+        return ErrorCode::INVALID_PARAMS;
+    }
 
     auto storage = std::make_unique<OpLogBatchStorage>(cluster_id_, *backend);
     DurablePrefix durable_prefix;
@@ -11115,17 +14882,36 @@ ErrorCode MasterService::InitializeBatchOpLogWriter(
     if (err != ErrorCode::OK) {
         return err;
     }
+    if (require_fenced_writer) {
+        err = storage->ClaimProducerView(view_version_);
+        if (err != ErrorCode::OK) {
+            LOG(ERROR) << "Failed to claim producer view for batch OpLog "
+                       << "writer: " << toString(err);
+            return err;
+        }
+    }
 
     OrderedOpLogWriterConfig writer_config;
     writer_config.max_entries_per_batch = oplog_batch_max_entries_;
     writer_config.initial_durable_prefix = durable_prefix;
     OpLogBatchStorage* storage_ptr = storage.get();
-    auto writer = std::make_unique<OrderedOpLogWriter>(
-        writer_config, [storage_ptr](const OpLogBatchRecord& batch,
-                                     const DurablePrefix& expected_prefix) {
+    const ViewVersionId producer_view_version = view_version_;
+    OrderedOpLogWriter::WriteBatchFn write_batch =
+        [storage_ptr, require_fenced_writer, producer_view_version](
+            const OpLogBatchRecord& batch,
+            const DurablePrefix& expected_prefix) {
+            if (require_fenced_writer) {
+                return storage_ptr->WriteBatchAndAdvancePrefix(
+                    batch, expected_prefix, producer_view_version);
+            }
             return storage_ptr->WriteBatchAndAdvancePrefix(batch,
                                                            expected_prefix);
-        });
+        };
+    auto writer =
+        batch_oplog_writer_factory_(writer_config, std::move(write_batch));
+    if (!writer) {
+        return ErrorCode::INVALID_PARAMS;
+    }
     if (!writer->IsAccepting()) {
         return writer->LastError();
     }
@@ -11137,6 +14923,7 @@ ErrorCode MasterService::InitializeBatchOpLogWriter(
     batch_oplog_kv_backend_ = std::move(backend);
     batch_oplog_storage_ = std::move(storage);
     ordered_oplog_writer_ = std::move(writer);
+    ordered_oplog_writer_->ActivateRuntimeMetrics();
     return ErrorCode::OK;
 }
 
diff --git a/mooncake-store/src/master_snapshot_manager.cpp b/mooncake-store/src/master_snapshot_manager.cpp
index 91f2e38609..a4592ab07b 100644
--- a/mooncake-store/src/master_snapshot_manager.cpp
+++ b/mooncake-store/src/master_snapshot_manager.cpp
@@ -21,8 +21,8 @@
 #include "serialize/serializer.h"
 #include "segment.h"
 #include "task_manager.h"
-#include "utils/file_util.h"
-#include "utils/zstd_util.h"
+#include "common/file_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake {
 
@@ -108,12 +108,6 @@ void MasterSnapshotManager::SnapshotThreadFunc() {
             break;
         }
 
-        if (!options_.enable_snapshot) {
-            // Snapshot is disabled
-            LOG(INFO)
-                << "[Snapshot] Snapshot is disabled, waiting for next cycle";
-            continue;
-        }
         // Fork a child process to save current state
 
         std::string snapshot_id =
@@ -152,6 +146,20 @@ void MasterSnapshotManager::SnapshotThreadFunc() {
             std::unique_lock<std::shared_mutex> lock(snapshot_mutex_);
             LOG(INFO) << "[Snapshot] Locking snapshot mutex, snapshot_id="
                       << snapshot_id;
+            if (!snapshot_running_.load()) {
+                close(log_pipe[0]);
+                close(log_pipe[1]);
+                break;
+            }
+            if (master_service_->ShouldSkipSnapshotForClientOffboarding()) {
+                LOG(WARNING)
+                    << "[Snapshot] Skipping snapshot while Client offboarding "
+                       "is pending, snapshot_id="
+                    << snapshot_id;
+                close(log_pipe[0]);
+                close(log_pipe[1]);
+                continue;
+            }
             pid = fork();
         }
         if (pid == -1) {
@@ -362,7 +370,7 @@ void MasterSnapshotManager::HandleChildExit(pid_t pid, int status,
 
 tl::expected<ha::OpLogSequenceId, SerializationError>
 MasterSnapshotManager::ResolveSnapshotSequenceId() const {
-    if (!options_.enable_ha || !master_service_->enable_oplog_) {
+    if (!master_service_->enable_ha_ || !master_service_->enable_oplog_) {
         // OpLog sequence ids start at 1. Returning 0 here is a sentinel that
         // means "no persisted OpLog boundary", so a standby that later calls
         // Recover(0) will replay from the first entry when oplog following is
@@ -450,6 +458,7 @@ tl::expected<void, SerializationError> MasterSnapshotManager::PersistState(
         ha::MasterSnapshotCodec codec;
         ha::MasterSnapshotStateView state_view(
             *master_service_, master_service_->segment_manager_,
+            master_service_->local_ssd_manager_,
             master_service_->nof_segment_manager_,
             master_service_->task_manager_);
 
diff --git a/mooncake-store/src/master_snapshot_repository.cpp b/mooncake-store/src/master_snapshot_repository.cpp
index b441196bdb..148448f9f8 100644
--- a/mooncake-store/src/master_snapshot_repository.cpp
+++ b/mooncake-store/src/master_snapshot_repository.cpp
@@ -9,7 +9,7 @@
 #include "ha/snapshot/object/snapshot_object_store.h"
 #include "ha/snapshot/snapshot_constants.h"
 #include "ha/snapshot/snapshot_logger.h"
-#include "utils/file_util.h"
+#include "common/file_util.h"
 
 namespace mooncake {
 
diff --git a/mooncake-store/src/mmap_arena.cpp b/mooncake-store/src/mmap_arena.cpp
index a0fc41e2cf..b92f972fdd 100644
--- a/mooncake-store/src/mmap_arena.cpp
+++ b/mooncake-store/src/mmap_arena.cpp
@@ -2,7 +2,7 @@
 // Simple arena allocator implementation
 
 #include "mmap_arena.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 #include <sys/mman.h>
 #include <glog/logging.h>
 #include <cerrno>
@@ -76,9 +76,13 @@ bool MmapArena::initialize(size_t pool_size, size_t alignment,
 
     const size_t actual_alignment = std::max(alignment, kMinAlignment);
 
-    // Align pool size to 2MB for huge pages with overflow protection
+    // Align pool size to the configured huge page size (2MB when hugepages
+    // are not explicitly requested) with overflow protection
+    unsigned int hugepage_flags = 0;
+    const size_t hugepage_size = get_hugepage_size_from_env(&hugepage_flags);
+    const size_t page_align = hugepage_size > 0 ? hugepage_size : SZ_2MB;
     size_t aligned_pool_size;
-    if (!safe_align_up(pool_size, SZ_2MB, &aligned_pool_size)) {
+    if (!safe_align_up(pool_size, page_align, &aligned_pool_size)) {
         LOG(ERROR) << "Arena pool size overflow: requested=" << pool_size;
         return false;
     }
@@ -91,7 +95,12 @@ bool MmapArena::initialize(size_t pool_size, size_t alignment,
 
 // Try huge pages for better TLB performance
 #ifdef MAP_HUGETLB
-    flags |= MAP_HUGETLB;
+    if (hugepage_size > 0) {
+        // MC_STORE_USE_HUGEPAGE set: honor the configured page size.
+        flags |= static_cast<int>(hugepage_flags);
+    } else {
+        flags |= MAP_HUGETLB;
+    }
 #endif
 
     void* pool_base =
@@ -111,7 +120,7 @@ bool MmapArena::initialize(size_t pool_size, size_t alignment,
         }
 
         // Retry without huge pages
-        flags &= ~MAP_HUGETLB;
+        flags &= ~(MAP_HUGETLB | (0x3f << 26));  // strip MAP_HUGE_* size bits
         LOG(WARNING) << "Arena hugepage mmap failed for pool_size="
                      << aligned_pool_size << " bytes"
                      << ", errno=" << mmap_errno << " (" << strerror(mmap_errno)
diff --git a/mooncake-store/src/nvme_kv/backend.cpp b/mooncake-store/src/nvme_kv/backend.cpp
new file mode 100644
index 0000000000..76dd75ea52
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/backend.cpp
@@ -0,0 +1,1533 @@
+#include "nvme_kv/backend.h"
+
+#include <algorithm>
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <cstring>
+#include <deque>
+#include <exception>
+#include <latch>
+#include <limits>
+#include <mutex>
+#include <optional>
+#include <stdexcept>
+#include <string_view>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "config/io_concurrency_config.h"
+#include "nvme_kv/executor_util.h"
+#include "nvme_kv/key_codec.h"
+#include "nvme_kv/key_conflict_policy.h"
+#include "nvme_kv/object_layout.h"
+
+namespace mooncake {
+
+namespace {
+
+constexpr uint32_t kMinMaxValueSize = sizeof(NvmeKvObjectHeader) + 1;
+constexpr size_t kDefaultReadPlanBatchSize = 8;
+
+size_t PositiveSizeEnvOr(const char *name, size_t fallback, size_t maximum) {
+    const uint32_t parsed = ParseNvmeKvU32EnvOr(name, 0);
+    return parsed == 0 ? fallback : std::min<size_t>(parsed, maximum);
+}
+
+class IndexQueue {
+   public:
+    bool Push(size_t index) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (closed_) {
+            return false;
+        }
+        queue_.push_back(index);
+        not_empty_.notify_one();
+        return true;
+    }
+
+    bool Pop(size_t &index) {
+        std::unique_lock<std::mutex> lock(mutex_);
+        not_empty_.wait(lock, [&]() { return closed_ || !queue_.empty(); });
+        if (queue_.empty()) {
+            return false;
+        }
+        index = queue_.front();
+        queue_.pop_front();
+        return true;
+    }
+
+    void Close() {
+        std::lock_guard<std::mutex> lock(mutex_);
+        closed_ = true;
+        not_empty_.notify_all();
+    }
+
+   private:
+    std::mutex mutex_;
+    std::condition_variable not_empty_;
+    std::deque<size_t> queue_;
+    bool closed_ = false;
+};
+
+bool CanRetrieveDirectlyInto(const char *data, uint32_t size) {
+    if (data == nullptr || size == 0) {
+        return false;
+    }
+    const uint32_t alignment = NvmeKvTransferAlignmentBytes();
+    return alignment != 0 && size % alignment == 0 &&
+           reinterpret_cast<uintptr_t>(data) % alignment == 0;
+}
+
+std::string_view BuildPayloadView(const std::vector<Slice> &slices,
+                                  size_t payload_size, std::string &storage) {
+    if (slices.size() == 1) {
+        const auto &slice = slices.front();
+        return slice.size == 0
+                   ? std::string_view{}
+                   : std::string_view(reinterpret_cast<const char *>(slice.ptr),
+                                      slice.size);
+    }
+    storage.reserve(payload_size);
+    for (const auto &slice : slices) {
+        storage.append(reinterpret_cast<const char *>(slice.ptr), slice.size);
+    }
+    return storage;
+}
+
+size_t ReadPlanBatchSize() {
+    return PositiveSizeEnvOr("MOONCAKE_NVME_KV_READ_PLAN_BATCH_SIZE",
+                             kDefaultReadPlanBatchSize, 1024);
+}
+
+std::optional<std::vector<size_t>> ValidateChunkRecords(
+    const NvmeKvObjectIdentity &identity, uint32_t slot,
+    size_t expected_payload_size,
+    const std::vector<NvmeKvManifestChunkRecord> &records) {
+    if (records.empty()) {
+        return std::nullopt;
+    }
+    std::vector<size_t> offsets;
+    offsets.reserve(records.size());
+    size_t offset = 0;
+    for (size_t index = 0; index < records.size(); ++index) {
+        const auto &record = records[index];
+        if (record.payload_size == 0 || offset > expected_payload_size ||
+            record.payload_size > expected_payload_size - offset ||
+            record.physical_key !=
+                EncodeNvmeKvChunkPhysicalKey(
+                    identity, static_cast<uint32_t>(index), slot)) {
+            return std::nullopt;
+        }
+        offsets.push_back(offset);
+        offset += record.payload_size;
+    }
+    return offset == expected_payload_size
+               ? std::optional<std::vector<size_t>>(std::move(offsets))
+               : std::nullopt;
+}
+
+bool ManifestChunkRecordsEqual(
+    const std::vector<NvmeKvManifestChunkRecord> &lhs,
+    const std::vector<NvmeKvManifestChunkRecord> &rhs) {
+    if (lhs.size() != rhs.size()) {
+        return false;
+    }
+    for (size_t index = 0; index < lhs.size(); ++index) {
+        if (lhs[index].physical_key != rhs[index].physical_key ||
+            lhs[index].payload_size != rhs[index].payload_size ||
+            lhs[index].payload_checksum != rhs[index].payload_checksum) {
+            return false;
+        }
+    }
+    return true;
+}
+
+struct ResolvedRoot {
+    NvmeKvPhysicalKey physical_key{};
+    uint32_t slot = 0;
+    std::string object_blob;
+};
+
+tl::expected<std::optional<ResolvedRoot>, ErrorCode> ResolveRoot(
+    NvmeKvConnector &connector, const std::string &logical_key) {
+    const NvmeKvObjectIdentity identity{.logical_key = logical_key};
+    for (uint32_t slot = 0; slot < kNvmeKvMaxPhysicalKeySlots; ++slot) {
+        const auto physical_key = EncodeNvmeKvPhysicalKey(identity, slot);
+        auto object_res = connector.Retrieve(physical_key);
+        if (!object_res) {
+            if (object_res.error() == ErrorCode::OBJECT_NOT_FOUND) {
+                continue;
+            }
+            return tl::make_unexpected(object_res.error());
+        }
+
+        NvmeKvObjectHeader header{};
+        std::string_view identity_metadata;
+        std::string_view payload;
+        if (!ParseNvmeKvObjectBlob(object_res.value(), header,
+                                   identity_metadata, payload)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+
+        NvmeKvStoredIdentityView stored_identity{};
+        if (!ParseNvmeKvStoredIdentity(identity_metadata, stored_identity)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        if (stored_identity.logical_key != logical_key) {
+            continue;
+        }
+        if (stored_identity.resolved_slot != slot ||
+            !NvmeKvKeyConflictPolicy::ValidateResolvedRootPlacement(
+                identity, stored_identity, physical_key)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        return std::optional<ResolvedRoot>(
+            ResolvedRoot{physical_key, slot, std::move(object_res.value())});
+    }
+    return std::nullopt;
+}
+
+}  // namespace
+
+NvmeKvStorageBackend::NvmeKvStorageBackend(
+    const FileStorageConfig &file_storage_config_)
+    : StorageBackendInterface(file_storage_config_) {}
+
+void NvmeKvStorageBackend::InitIoWorkers() {
+    const auto config = NvmeKvIoConcurrencyConfig::FromEnvironment(
+        connector_->GetCapabilities().queue_depth);
+    const size_t max_io_concurrency = config.max_io_concurrency;
+    io_parallelism_ = config.io_concurrency;
+    batch_submit_concurrency_ = config.batch_submit_concurrency;
+    root_submit_concurrency_ = config.root_submit_concurrency;
+    prepare_concurrency_ = config.prepare_concurrency;
+    if (io_parallelism_ > 1) {
+        io_workers_ = std::make_unique<ThreadPool>(io_parallelism_);
+    }
+    if (batch_submit_concurrency_ > 1) {
+        submit_workers_ =
+            std::make_unique<ThreadPool>(batch_submit_concurrency_);
+        root_submit_workers_ =
+            std::make_unique<ThreadPool>(root_submit_concurrency_);
+    }
+    LOG(INFO) << "NVMe KV backend I/O concurrency: " << io_parallelism_
+              << " (max " << max_io_concurrency
+              << "), batch submit concurrency: " << batch_submit_concurrency_
+              << ", root submit concurrency: " << root_submit_concurrency_
+              << ", prepare concurrency: " << prepare_concurrency_;
+}
+
+void NvmeKvStorageBackend::RunParallelIo(
+    size_t item_count, const std::function<void(size_t)> &task,
+    size_t max_inflight) {
+    if (item_count == 0) {
+        return;
+    }
+    const size_t concurrency_limit =
+        max_inflight == 0 ? io_parallelism_
+                          : std::min(io_parallelism_, max_inflight);
+    const size_t worker_count = std::min(item_count, concurrency_limit);
+    if (worker_count <= 1 || io_workers_ == nullptr) {
+        for (size_t i = 0; i < item_count; ++i) {
+            task(i);
+        }
+        return;
+    }
+
+    std::atomic<size_t> next_index{0};
+    std::latch completed(static_cast<std::ptrdiff_t>(worker_count));
+    std::mutex exception_mutex;
+    std::exception_ptr first_exception;
+    std::exception_ptr enqueue_exception;
+
+    size_t enqueued = 0;
+    try {
+        for (; enqueued < worker_count; ++enqueued) {
+            io_workers_->enqueue([&]() {
+                try {
+                    while (true) {
+                        const size_t index =
+                            next_index.fetch_add(1, std::memory_order_relaxed);
+                        if (index >= item_count) {
+                            break;
+                        }
+                        task(index);
+                    }
+                } catch (...) {
+                    std::lock_guard<std::mutex> lock(exception_mutex);
+                    if (first_exception == nullptr) {
+                        first_exception = std::current_exception();
+                    }
+                }
+                completed.count_down();
+            });
+        }
+    } catch (...) {
+        enqueue_exception = std::current_exception();
+        completed.count_down(
+            static_cast<std::ptrdiff_t>(worker_count - enqueued));
+    }
+
+    completed.wait();
+    if (enqueue_exception != nullptr) {
+        std::rethrow_exception(enqueue_exception);
+    }
+    if (first_exception != nullptr) {
+        std::rethrow_exception(first_exception);
+    }
+}
+
+void NvmeKvStorageBackend::RunPipelinedIo(
+    size_t item_count, const std::function<void(size_t)> &io_task,
+    const std::function<void(size_t)> &completion_task) {
+    if (item_count == 0) {
+        return;
+    }
+    const size_t worker_count = std::min(item_count, batch_submit_concurrency_);
+    if (worker_count <= 1 || submit_workers_ == nullptr ||
+        io_workers_ == nullptr) {
+        for (size_t index = 0; index < item_count; ++index) {
+            io_task(index);
+            completion_task(index);
+        }
+        return;
+    }
+
+    std::atomic<size_t> next_index{0};
+    std::vector<std::exception_ptr> item_exceptions(item_count);
+    std::latch items_completed(static_cast<std::ptrdiff_t>(item_count));
+    std::latch workers_completed(static_cast<std::ptrdiff_t>(worker_count));
+    std::exception_ptr enqueue_exception;
+    size_t enqueued_workers = 0;
+    try {
+        for (; enqueued_workers < worker_count; ++enqueued_workers) {
+            submit_workers_->enqueue([&]() {
+                while (true) {
+                    const size_t index =
+                        next_index.fetch_add(1, std::memory_order_relaxed);
+                    if (index >= item_count) {
+                        break;
+                    }
+                    try {
+                        io_task(index);
+                    } catch (...) {
+                        item_exceptions[index] = std::current_exception();
+                        items_completed.count_down();
+                        continue;
+                    }
+                    try {
+                        io_workers_->enqueue([&, index]() {
+                            try {
+                                completion_task(index);
+                            } catch (...) {
+                                item_exceptions[index] =
+                                    std::current_exception();
+                            }
+                            items_completed.count_down();
+                        });
+                    } catch (...) {
+                        item_exceptions[index] = std::current_exception();
+                        items_completed.count_down();
+                    }
+                }
+                workers_completed.count_down();
+            });
+        }
+    } catch (...) {
+        enqueue_exception = std::current_exception();
+        workers_completed.count_down(
+            static_cast<std::ptrdiff_t>(worker_count - enqueued_workers));
+    }
+
+    if (enqueued_workers == 0) {
+        std::rethrow_exception(enqueue_exception);
+    }
+
+    items_completed.wait();
+    workers_completed.wait();
+    if (enqueue_exception != nullptr) {
+        std::rethrow_exception(enqueue_exception);
+    }
+    for (const auto &item_exception : item_exceptions) {
+        if (item_exception != nullptr) {
+            std::rethrow_exception(item_exception);
+        }
+    }
+}
+
+std::shared_ptr<const NvmeKvStorageBackend::CachedManifest>
+NvmeKvStorageBackend::FindCachedManifest(const std::string &key,
+                                         size_t payload_size) const {
+    std::shared_lock<std::shared_mutex> lock(manifest_cache_mutex_);
+    const auto it = manifest_cache_.find(key);
+    if (it == manifest_cache_.end() ||
+        it->second->payload_size != payload_size) {
+        return nullptr;
+    }
+    return it->second;
+}
+
+std::shared_ptr<const NvmeKvStorageBackend::CachedManifest>
+NvmeKvStorageBackend::CacheManifest(
+    const std::string &key, size_t payload_size, uint32_t resolved_slot,
+    const std::vector<NvmeKvManifestChunkRecord> &chunk_records) {
+    if (payload_size > std::numeric_limits<uint32_t>::max()) {
+        return nullptr;
+    }
+    const NvmeKvObjectIdentity identity{.logical_key = key};
+    auto chunk_offsets = ValidateChunkRecords(identity, resolved_slot,
+                                              payload_size, chunk_records);
+    if (!chunk_offsets) {
+        return nullptr;
+    }
+    auto manifest = std::make_shared<const CachedManifest>(CachedManifest{
+        .resolved_slot = resolved_slot,
+        .payload_size = static_cast<uint32_t>(payload_size),
+        .chunk_records = chunk_records,
+        .chunk_offsets = std::move(*chunk_offsets),
+    });
+    std::unique_lock<std::shared_mutex> lock(manifest_cache_mutex_);
+    auto [it, inserted] = manifest_cache_.try_emplace(key, manifest);
+    if (inserted) {
+        return manifest;
+    }
+    if (it->second->payload_size == payload_size &&
+        it->second->resolved_slot == resolved_slot &&
+        ManifestChunkRecordsEqual(it->second->chunk_records, chunk_records)) {
+        return it->second;
+    }
+    it->second = manifest;
+    return manifest;
+}
+
+void NvmeKvStorageBackend::CacheManifestAfterWrite(
+    const std::string &key, size_t payload_size, uint32_t resolved_slot,
+    const std::vector<NvmeKvManifestChunkRecord> &chunk_records) noexcept {
+    try {
+        (void)CacheManifest(key, payload_size, resolved_slot, chunk_records);
+    } catch (...) {
+        LOG(WARNING) << "NVMe KV could not cache manifest for " << key;
+    }
+}
+
+void NvmeKvStorageBackend::StoreBatchParallel(
+    std::vector<NvmeKvCommandExecutor::StoreRequest> &requests) {
+    if (requests.empty()) {
+        return;
+    }
+    auto connector = connector_;
+    if (connector == nullptr) {
+        for (auto &request : requests) {
+            request.result = tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+        }
+        return;
+    }
+
+    const size_t worker_count =
+        std::min(batch_submit_concurrency_, requests.size());
+    RunParallelIo(
+        worker_count,
+        [&](size_t worker_index) {
+            std::vector<size_t> request_indices;
+            std::vector<NvmeKvCommandExecutor::StoreRequest> worker_requests;
+            const size_t worker_request_count =
+                (requests.size() + worker_count - 1 - worker_index) /
+                worker_count;
+            request_indices.reserve(worker_request_count);
+            worker_requests.reserve(worker_request_count);
+            for (size_t request_index = worker_index;
+                 request_index < requests.size();
+                 request_index += worker_count) {
+                request_indices.push_back(request_index);
+                worker_requests.push_back(requests[request_index]);
+            }
+            connector->StoreBatch(worker_requests);
+            for (size_t index = 0; index < worker_requests.size(); ++index) {
+                requests[request_indices[index]].result =
+                    std::move(worker_requests[index].result);
+            }
+        },
+        worker_count);
+}
+
+tl::expected<void, ErrorCode> NvmeKvStorageBackend::InitDevice() {
+    auto connector = std::make_shared<NvmeKvConnector>(file_storage_config_);
+    auto init_res = connector->Init();
+    if (!init_res) {
+        LOG(ERROR) << "Failed to initialize NVMe KV device: "
+                   << toString(init_res.error());
+        return init_res;
+    }
+    connector_ = std::move(connector);
+    return {};
+}
+
+tl::expected<void, ErrorCode> NvmeKvStorageBackend::Init() {
+    bool expected = false;
+    if (!initialized_.compare_exchange_strong(expected, true,
+                                              std::memory_order_acq_rel)) {
+        LOG(ERROR) << "NVMe KV backend already initialized";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    auto init_res = InitDevice();
+    if (!init_res) {
+        initialized_.store(false, std::memory_order_release);
+        return init_res;
+    }
+    total_size_.store(0, std::memory_order_relaxed);
+    total_keys_.store(0, std::memory_order_relaxed);
+    InitIoWorkers();
+    return {};
+}
+
+tl::expected<int64_t, ErrorCode> NvmeKvStorageBackend::BatchOffload(
+    const std::unordered_map<std::string, std::vector<Slice>> &batch_object,
+    std::function<ErrorCode(const std::vector<std::string> &keys,
+                            std::vector<StorageObjectMetadata> &metadatas)>
+        complete_handler,
+    NvmeKvStorageBackend::EvictionHandler eviction_handler) {
+    (void)eviction_handler;
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    if (batch_object.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_KEY);
+    }
+
+    struct OffloadPlan {
+        std::string key;
+        const std::vector<Slice> *slices = nullptr;
+        size_t payload_size = 0;
+    };
+    std::vector<OffloadPlan> plans;
+    plans.reserve(batch_object.size());
+    int64_t batch_total_size = 0;
+    for (const auto &[key, slices] : batch_object) {
+        if (slices.empty()) {
+            continue;
+        }
+        size_t payload_size = 0;
+        for (const auto &slice : slices) {
+            if (slice.size >
+                std::numeric_limits<size_t>::max() - payload_size) {
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            payload_size += slice.size;
+        }
+        if (payload_size >
+                static_cast<size_t>(std::numeric_limits<int64_t>::max()) ||
+            batch_total_size > std::numeric_limits<int64_t>::max() -
+                                   static_cast<int64_t>(payload_size)) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        batch_total_size += static_cast<int64_t>(payload_size);
+        plans.push_back(OffloadPlan{key, &slices, payload_size});
+    }
+
+    if (plans.empty()) {
+        return 0;
+    }
+
+    if (total_keys_.load(std::memory_order_relaxed) +
+            static_cast<int64_t>(plans.size()) >
+        file_storage_config_.total_keys_limit) {
+        return tl::make_unexpected(ErrorCode::KEYS_ULTRA_LIMIT);
+    }
+    if (total_size_.load(std::memory_order_relaxed) + batch_total_size >
+        file_storage_config_.total_size_limit) {
+        return tl::make_unexpected(ErrorCode::KEYS_ULTRA_LIMIT);
+    }
+    auto enable_offloading_res = IsEnableOffloading();
+    if (!enable_offloading_res) {
+        return tl::make_unexpected(enable_offloading_res.error());
+    }
+    if (!enable_offloading_res.value()) {
+        return tl::make_unexpected(ErrorCode::KEYS_ULTRA_LIMIT);
+    }
+
+    std::vector<tl::expected<OffloadResult, ErrorCode>> results;
+    results.reserve(plans.size());
+    for (size_t i = 0; i < plans.size(); ++i) {
+        results.emplace_back(OffloadResult{});
+    }
+
+    struct PreparedOffload {
+        std::string payload_storage;
+        std::string_view payload;
+        std::optional<NvmeKvKeyConflictPolicy::WritePlan> write_plan;
+        std::vector<PhysicalKey> written_chunk_keys;
+        bool root_written = false;
+        bool needs_fallback = false;
+    };
+    std::vector<PreparedOffload> prepared(plans.size());
+
+    const auto prepare_one = [&](size_t index) {
+        const auto &plan = plans[index];
+        auto &item = prepared[index];
+        item.payload = BuildPayloadView(*plan.slices, plan.payload_size,
+                                        item.payload_storage);
+        auto write_plan = NvmeKvKeyConflictPolicy::BuildWritePlan(
+            NvmeKvObjectIdentity{.logical_key = plan.key}, item.payload, 0,
+            std::max(connector_->GetCapabilities().effective_max_value_size,
+                     kMinMaxValueSize));
+        if (!write_plan) {
+            results[index] = tl::make_unexpected(write_plan.error());
+            return;
+        }
+        item.write_plan.emplace(std::move(write_plan.value()));
+    };
+
+    struct StoreContext {
+        size_t plan_index = 0;
+        size_t chunk_index = 0;
+    };
+    const auto apply_chunk_results =
+        [&prepared](std::vector<NvmeKvCommandExecutor::StoreRequest> &requests,
+                    const std::vector<StoreContext> &contexts) {
+            for (size_t request_index = 0; request_index < requests.size();
+                 ++request_index) {
+                const auto &context = contexts[request_index];
+                auto &item = prepared[context.plan_index];
+                if (requests[request_index].result) {
+                    item.written_chunk_keys.push_back(
+                        item.write_plan->chunk_values[context.chunk_index]
+                            .first);
+                } else {
+                    item.needs_fallback = true;
+                }
+            }
+        };
+
+    bool roots_pipelined = false;
+    const auto store_chunks = [&]() {
+        if (io_workers_ == nullptr || submit_workers_ == nullptr ||
+            root_submit_workers_ == nullptr || batch_submit_concurrency_ <= 1) {
+            RunParallelIo(plans.size(), prepare_one, prepare_concurrency_);
+            std::vector<NvmeKvCommandExecutor::StoreRequest> chunk_requests;
+            std::vector<StoreContext> chunk_contexts;
+            for (size_t plan_index = 0; plan_index < plans.size();
+                 ++plan_index) {
+                auto &item = prepared[plan_index];
+                if (!item.write_plan || item.write_plan->store_inline) {
+                    continue;
+                }
+                for (size_t chunk_index = 0;
+                     chunk_index < item.write_plan->chunk_values.size();
+                     ++chunk_index) {
+                    const auto &[chunk_key, chunk_value] =
+                        item.write_plan->chunk_values[chunk_index];
+                    NvmeKvCommandExecutor::StoreRequest request;
+                    request.key = chunk_key;
+                    request.value = chunk_value;
+                    chunk_requests.push_back(request);
+                    chunk_contexts.push_back(
+                        StoreContext{plan_index, chunk_index});
+                }
+            }
+            StoreBatchParallel(chunk_requests);
+            apply_chunk_results(chunk_requests, chunk_contexts);
+            return;
+        }
+
+        const size_t lane_count =
+            std::min(batch_submit_concurrency_, plans.size());
+        const size_t root_lane_count =
+            std::min(root_submit_concurrency_, plans.size());
+        roots_pipelined = true;
+        std::vector<std::unique_ptr<IndexQueue>> queues;
+        queues.reserve(lane_count);
+        for (size_t lane = 0; lane < lane_count; ++lane) {
+            queues.push_back(std::make_unique<IndexQueue>());
+        }
+
+        const auto close_queues = [&]() {
+            for (auto &queue : queues) {
+                queue->Close();
+            }
+        };
+        IndexQueue root_queue;
+        std::mutex consumer_error_mutex;
+        std::exception_ptr consumer_error;
+        const auto set_consumer_error = [&]() {
+            std::lock_guard<std::mutex> lock(consumer_error_mutex);
+            if (consumer_error == nullptr) {
+                consumer_error = std::current_exception();
+            }
+            close_queues();
+            root_queue.Close();
+        };
+        std::latch consumers_done(static_cast<std::ptrdiff_t>(lane_count));
+        std::latch root_consumers_done(
+            static_cast<std::ptrdiff_t>(root_lane_count));
+
+        size_t enqueued_root_consumers = 0;
+        try {
+            for (; enqueued_root_consumers < root_lane_count;
+                 ++enqueued_root_consumers) {
+                root_submit_workers_->enqueue([&]() {
+                    try {
+                        auto connector = connector_;
+                        if (connector == nullptr) {
+                            throw std::runtime_error(
+                                "NVMe KV connector is unavailable");
+                        }
+                        const size_t queue_depth = std::max<size_t>(
+                            1, connector->GetCapabilities().queue_depth);
+                        std::vector<NvmeKvCommandExecutor::StoreRequest>
+                            requests;
+                        std::vector<size_t> contexts;
+                        requests.reserve(queue_depth);
+                        contexts.reserve(queue_depth);
+                        const auto flush = [&]() {
+                            if (requests.empty()) {
+                                return;
+                            }
+                            connector->StoreBatch(requests);
+                            for (size_t index = 0; index < requests.size();
+                                 ++index) {
+                                auto &item = prepared[contexts[index]];
+                                if (requests[index].result) {
+                                    item.root_written = true;
+                                } else {
+                                    item.needs_fallback = true;
+                                }
+                            }
+                            requests.clear();
+                            contexts.clear();
+                        };
+
+                        size_t plan_index = 0;
+                        while (root_queue.Pop(plan_index)) {
+                            auto &item = prepared[plan_index];
+                            NvmeKvCommandExecutor::StoreRequest request;
+                            request.key = item.write_plan->root_key;
+                            request.value = item.write_plan->root_blob;
+                            requests.push_back(request);
+                            contexts.push_back(plan_index);
+                            if (requests.size() == queue_depth) {
+                                flush();
+                            }
+                        }
+                        flush();
+                    } catch (...) {
+                        set_consumer_error();
+                    }
+                    root_consumers_done.count_down();
+                });
+            }
+        } catch (...) {
+            close_queues();
+            root_queue.Close();
+            root_consumers_done.count_down(static_cast<std::ptrdiff_t>(
+                root_lane_count - enqueued_root_consumers));
+            root_consumers_done.wait();
+            throw;
+        }
+
+        size_t enqueued_consumers = 0;
+        try {
+            for (; enqueued_consumers < lane_count; ++enqueued_consumers) {
+                submit_workers_->enqueue([&, lane = enqueued_consumers]() {
+                    try {
+                        auto connector = connector_;
+                        if (connector == nullptr) {
+                            throw std::runtime_error(
+                                "NVMe KV connector is unavailable");
+                        }
+                        const size_t queue_depth = std::max<size_t>(
+                            1, connector->GetCapabilities().queue_depth);
+                        std::vector<NvmeKvCommandExecutor::StoreRequest>
+                            chunk_requests;
+                        std::vector<StoreContext> chunk_contexts;
+                        chunk_requests.reserve(queue_depth);
+                        chunk_contexts.reserve(queue_depth);
+                        const auto flush_chunks = [&]() {
+                            if (chunk_requests.empty()) {
+                                return;
+                            }
+                            connector->StoreBatch(chunk_requests);
+                            apply_chunk_results(chunk_requests, chunk_contexts);
+                            for (const auto &context : chunk_contexts) {
+                                auto &item = prepared[context.plan_index];
+                                if (context.chunk_index + 1 ==
+                                        item.write_plan->chunk_values.size() &&
+                                    !item.needs_fallback) {
+                                    if (!root_queue.Push(context.plan_index)) {
+                                        item.needs_fallback = true;
+                                    }
+                                }
+                            }
+                            chunk_requests.clear();
+                            chunk_contexts.clear();
+                        };
+
+                        size_t plan_index = 0;
+                        while (queues[lane]->Pop(plan_index)) {
+                            auto &item = prepared[plan_index];
+                            for (size_t chunk_index = 0;
+                                 chunk_index <
+                                 item.write_plan->chunk_values.size();
+                                 ++chunk_index) {
+                                const auto &[chunk_key, chunk_value] =
+                                    item.write_plan->chunk_values[chunk_index];
+                                NvmeKvCommandExecutor::StoreRequest request;
+                                request.key = chunk_key;
+                                request.value = chunk_value;
+                                chunk_requests.push_back(request);
+                                chunk_contexts.push_back(
+                                    StoreContext{plan_index, chunk_index});
+                                if (chunk_requests.size() == queue_depth) {
+                                    flush_chunks();
+                                }
+                            }
+                        }
+                        flush_chunks();
+                    } catch (...) {
+                        set_consumer_error();
+                    }
+                    consumers_done.count_down();
+                });
+            }
+        } catch (...) {
+            close_queues();
+            root_queue.Close();
+            consumers_done.count_down(
+                static_cast<std::ptrdiff_t>(lane_count - enqueued_consumers));
+            consumers_done.wait();
+            root_consumers_done.wait();
+            throw;
+        }
+
+        std::exception_ptr producer_error;
+        try {
+            RunParallelIo(
+                plans.size(),
+                [&](size_t index) {
+                    prepare_one(index);
+                    auto &item = prepared[index];
+                    if (!item.write_plan) {
+                        return;
+                    }
+                    const bool queued =
+                        item.write_plan->store_inline
+                            ? root_queue.Push(index)
+                            : queues[index % lane_count]->Push(index);
+                    if (!queued) {
+                        results[index] =
+                            tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    }
+                },
+                prepare_concurrency_);
+        } catch (...) {
+            producer_error = std::current_exception();
+        }
+        close_queues();
+        consumers_done.wait();
+        root_queue.Close();
+        root_consumers_done.wait();
+        if (producer_error != nullptr) {
+            std::rethrow_exception(producer_error);
+        }
+        if (consumer_error != nullptr) {
+            std::rethrow_exception(consumer_error);
+        }
+    };
+
+    const auto cleanup_new_writes = [&](size_t plan_index, bool delete_root) {
+        auto connector = connector_;
+        auto &item = prepared[plan_index];
+        if (connector == nullptr || !item.write_plan) {
+            return;
+        }
+        if (delete_root) {
+            auto result = connector->Delete(item.write_plan->root_key);
+            if (!result && result.error() != ErrorCode::OBJECT_NOT_FOUND) {
+                LOG(WARNING) << "NVMe KV failed to clean batched root for "
+                             << plans[plan_index].key
+                             << " error=" << toString(result.error());
+            }
+            item.root_written = false;
+        }
+        for (const auto &chunk_key : item.written_chunk_keys) {
+            auto result = connector->Delete(chunk_key);
+            if (!result && result.error() != ErrorCode::OBJECT_NOT_FOUND) {
+                LOG(WARNING) << "NVMe KV failed to clean batched chunk for "
+                             << plans[plan_index].key
+                             << " error=" << toString(result.error());
+            }
+        }
+        item.written_chunk_keys.clear();
+    };
+
+    ErrorCode worker_error = ErrorCode::OK;
+    try {
+        store_chunks();
+
+        for (size_t plan_index = 0; plan_index < plans.size(); ++plan_index) {
+            if (prepared[plan_index].needs_fallback) {
+                cleanup_new_writes(plan_index, false);
+            }
+        }
+
+        std::vector<NvmeKvCommandExecutor::StoreRequest> root_requests;
+        std::vector<size_t> root_contexts;
+        for (size_t plan_index = 0; plan_index < plans.size(); ++plan_index) {
+            auto &item = prepared[plan_index];
+            if (!item.write_plan || item.needs_fallback || roots_pipelined) {
+                continue;
+            }
+            NvmeKvCommandExecutor::StoreRequest request;
+            request.key = item.write_plan->root_key;
+            request.value = item.write_plan->root_blob;
+            root_requests.push_back(request);
+            root_contexts.push_back(plan_index);
+        }
+        StoreBatchParallel(root_requests);
+        for (size_t request_index = 0; request_index < root_requests.size();
+             ++request_index) {
+            const size_t plan_index = root_contexts[request_index];
+            auto &item = prepared[plan_index];
+            if (!root_requests[request_index].result) {
+                item.needs_fallback = true;
+                cleanup_new_writes(plan_index, false);
+                continue;
+            }
+            item.root_written = true;
+        }
+
+        for (size_t plan_index = 0; plan_index < plans.size(); ++plan_index) {
+            auto &item = prepared[plan_index];
+            if (!item.write_plan || item.needs_fallback || !item.root_written) {
+                continue;
+            }
+            item.root_written = false;
+            item.written_chunk_keys.clear();
+            results[plan_index] =
+                OffloadResult{.stored = true, .inserted = true};
+            if (!item.write_plan->store_inline) {
+                CacheManifestAfterWrite(plans[plan_index].key,
+                                        plans[plan_index].payload_size, 0,
+                                        item.write_plan->manifest_records);
+            }
+        }
+
+        RunParallelIo(plans.size(), [&](size_t index) {
+            if (!prepared[index].needs_fallback) {
+                return;
+            }
+            results[index] = OffloadOne(plans[index].key, *plans[index].slices,
+                                        plans[index].payload_size);
+        });
+    } catch (const std::exception &error) {
+        LOG(ERROR) << "NVMe KV batch offload worker failed: " << error.what();
+        worker_error = ErrorCode::INTERNAL_ERROR;
+    } catch (...) {
+        LOG(ERROR) << "NVMe KV batch offload worker failed";
+        worker_error = ErrorCode::INTERNAL_ERROR;
+    }
+    if (worker_error != ErrorCode::OK) {
+        for (size_t index = 0; index < prepared.size(); ++index) {
+            cleanup_new_writes(index, prepared[index].root_written);
+        }
+    }
+
+    std::vector<std::string> keys;
+    std::vector<StorageObjectMetadata> metadatas;
+    keys.reserve(plans.size());
+    metadatas.reserve(plans.size());
+    int64_t inserted_keys = 0;
+    int64_t inserted_size = 0;
+    ErrorCode first_error = worker_error;
+    for (size_t i = 0; i < plans.size(); ++i) {
+        if (!results[i]) {
+            if (first_error == ErrorCode::OK) {
+                first_error = results[i].error();
+            }
+            continue;
+        }
+        if (!results[i].value().stored) {
+            continue;
+        }
+        if (results[i].value().inserted) {
+            ++inserted_keys;
+            inserted_size += static_cast<int64_t>(plans[i].payload_size);
+        }
+        keys.push_back(plans[i].key);
+        metadatas.emplace_back(StorageObjectMetadata{
+            .bucket_id = 0,
+            .offset = 0,
+            .key_size = static_cast<int64_t>(plans[i].key.size()),
+            .data_size = static_cast<int64_t>(plans[i].payload_size),
+            .transport_endpoint = "",
+        });
+    }
+
+    total_keys_.fetch_add(inserted_keys, std::memory_order_relaxed);
+    total_size_.fetch_add(inserted_size, std::memory_order_relaxed);
+    if (complete_handler != nullptr && !keys.empty()) {
+        const auto error_code = complete_handler(keys, metadatas);
+        if (error_code != ErrorCode::OK) {
+            return tl::make_unexpected(error_code);
+        }
+    }
+    if (first_error != ErrorCode::OK) {
+        return tl::make_unexpected(first_error);
+    }
+    return static_cast<int64_t>(keys.size());
+}
+
+tl::expected<NvmeKvStorageBackend::OffloadResult, ErrorCode>
+NvmeKvStorageBackend::OffloadOne(const std::string &key,
+                                 const std::vector<Slice> &slices,
+                                 size_t payload_size) {
+    if (payload_size >
+        static_cast<size_t>(std::numeric_limits<uint32_t>::max())) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    std::string payload_storage;
+    const std::string_view payload =
+        BuildPayloadView(slices, payload_size, payload_storage);
+
+    auto connector = connector_;
+    if (connector == nullptr) {
+        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+    }
+    const uint32_t effective_max_value_size =
+        std::max(connector->GetCapabilities().effective_max_value_size,
+                 kMinMaxValueSize);
+
+    for (uint32_t slot = 0; slot < kNvmeKvMaxPhysicalKeySlots; ++slot) {
+        auto write_plan_res = NvmeKvKeyConflictPolicy::BuildWritePlan(
+            NvmeKvObjectIdentity{.logical_key = key}, payload, slot,
+            effective_max_value_size);
+        if (!write_plan_res) {
+            return tl::make_unexpected(write_plan_res.error());
+        }
+        auto &write_plan = write_plan_res.value();
+        const bool store_inline = write_plan.store_inline;
+        const auto &physical_key = write_plan.root_key;
+        const auto &root_blob = write_plan.root_blob;
+        const auto &chunk_store_values = write_plan.chunk_values;
+
+        std::vector<PhysicalKey> written_chunk_keys;
+        bool root_written = false;
+        const auto cleanup_new_writes = [&]() {
+            if (root_written) {
+                auto delete_res = connector->Delete(physical_key);
+                if (!delete_res &&
+                    delete_res.error() != ErrorCode::OBJECT_NOT_FOUND) {
+                    LOG(WARNING)
+                        << "NVMe KV failed to clean orphan root for " << key
+                        << " key=" << NvmeKvPhysicalKeyToHex(physical_key)
+                        << " error=" << toString(delete_res.error());
+                }
+                root_written = false;
+            }
+            if (written_chunk_keys.empty()) {
+                return;
+            }
+            for (const auto &chunk_key : written_chunk_keys) {
+                auto delete_res = connector->Delete(chunk_key);
+                if (!delete_res &&
+                    delete_res.error() != ErrorCode::OBJECT_NOT_FOUND) {
+                    LOG(WARNING)
+                        << "NVMe KV failed to clean orphan chunk for " << key
+                        << " key=" << NvmeKvPhysicalKeyToHex(chunk_key)
+                        << " error=" << toString(delete_res.error());
+                }
+            }
+            written_chunk_keys.clear();
+        };
+        const auto resolve_existing_root =
+            [&]() -> tl::expected<OffloadResult, ErrorCode> {
+            auto decision_res = NvmeKvKeyConflictPolicy::ResolveExistingObject(
+                *connector, physical_key, root_blob);
+            if (!decision_res) {
+                return tl::make_unexpected(decision_res.error());
+            }
+            if (decision_res.value() ==
+                NvmeKvKeyConflictPolicy::ExistingObjectDecision::kNotFound) {
+                return OffloadResult{};
+            }
+            if (decision_res.value() ==
+                NvmeKvKeyConflictPolicy::ExistingObjectDecision::
+                    kDifferentObject) {
+                return OffloadResult{};
+            }
+            return OffloadResult{.stored = true, .inserted = false};
+        };
+
+        bool write_success = true;
+        bool slot_collision = false;
+        ErrorCode write_error = ErrorCode::OK;
+        if (store_inline) {
+            auto store_res = connector->Store(physical_key, root_blob);
+            if (!store_res) {
+                write_success = false;
+                write_error = store_res.error();
+            } else {
+                root_written = true;
+            }
+        } else {
+            const auto handle_chunk_store_error =
+                [&](const PhysicalKey &chunk_key, std::string_view chunk_blob,
+                    ErrorCode error) -> bool {
+                if (error == ErrorCode::OBJECT_ALREADY_EXISTS) {
+                    auto existing_chunk_res =
+                        NvmeKvKeyConflictPolicy::ResolveExistingObject(
+                            *connector, chunk_key, chunk_blob);
+                    if (existing_chunk_res &&
+                        existing_chunk_res.value() ==
+                            NvmeKvKeyConflictPolicy::ExistingObjectDecision::
+                                kSameObject) {
+                        return true;
+                    }
+                    if (!existing_chunk_res) {
+                        write_error = existing_chunk_res.error();
+                    } else {
+                        write_error = ErrorCode::OBJECT_ALREADY_EXISTS;
+                    }
+                    slot_collision = true;
+                } else {
+                    write_error = error;
+                }
+                write_success = false;
+                cleanup_new_writes();
+                return false;
+            };
+            std::vector<NvmeKvCommandExecutor::StoreRequest> chunk_requests;
+            chunk_requests.reserve(chunk_store_values.size());
+            for (const auto &[chunk_key, chunk_blob] : chunk_store_values) {
+                NvmeKvCommandExecutor::StoreRequest request;
+                request.key = chunk_key;
+                request.value = chunk_blob;
+                chunk_requests.push_back(request);
+            }
+            connector->StoreBatch(chunk_requests);
+
+            for (size_t chunk_index = 0;
+                 chunk_index < chunk_store_values.size(); ++chunk_index) {
+                const auto &[chunk_key, chunk_blob] =
+                    chunk_store_values[chunk_index];
+                const auto &chunk_res = chunk_requests[chunk_index].result;
+                if (!chunk_res) {
+                    if (!handle_chunk_store_error(chunk_key, chunk_blob,
+                                                  chunk_res.error())) {
+                        break;
+                    }
+                    continue;
+                }
+                written_chunk_keys.push_back(chunk_key);
+            }
+            if (write_success) {
+                auto store_res = connector->Store(physical_key, root_blob);
+                if (!store_res) {
+                    write_success = false;
+                    write_error = store_res.error();
+                    cleanup_new_writes();
+                } else {
+                    root_written = true;
+                }
+            }
+        }
+
+        if (!write_success && write_error == ErrorCode::OBJECT_ALREADY_EXISTS) {
+            auto existing_res = resolve_existing_root();
+            if (existing_res && existing_res.value().stored) {
+                if (!store_inline) {
+                    CacheManifestAfterWrite(key, payload_size, slot,
+                                            write_plan.manifest_records);
+                }
+                return existing_res;
+            }
+            if (!existing_res) {
+                write_error = existing_res.error();
+            } else {
+                slot_collision = true;
+                cleanup_new_writes();
+            }
+        }
+
+        if (!write_success) {
+            if (!slot_collision && !store_inline) {
+                cleanup_new_writes();
+            }
+            written_chunk_keys.clear();
+            if (slot_collision) {
+                continue;
+            }
+            return tl::make_unexpected(write_error);
+        }
+
+        if (!store_inline) {
+            CacheManifestAfterWrite(key, payload_size, slot,
+                                    write_plan.manifest_records);
+        }
+        return OffloadResult{.stored = true, .inserted = true};
+    }
+    return OffloadResult{};
+}
+
+tl::expected<void, ErrorCode> NvmeKvStorageBackend::BatchLoad(
+    std::unordered_map<std::string, Slice> &batched_slices) {
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+
+    const auto connector = connector_;
+    if (connector == nullptr) {
+        return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+    }
+
+    struct ReadPlan {
+        std::string key;
+        Slice dest_slice;
+        std::shared_ptr<const CachedManifest> cached_manifest;
+    };
+    std::vector<ReadPlan> plans;
+    plans.reserve(batched_slices.size());
+
+    for (const auto &[key, dest_slice] : batched_slices) {
+        if (dest_slice.size > std::numeric_limits<uint32_t>::max()) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        plans.push_back(ReadPlan{key, dest_slice,
+                                 FindCachedManifest(key, dest_slice.size)});
+    }
+
+    struct PreparedRead {
+        std::shared_ptr<const CachedManifest> manifest;
+    };
+    std::vector<PreparedRead> prepared_reads(plans.size());
+    const auto prepare_one =
+        [&](size_t plan_index) -> tl::expected<void, ErrorCode> {
+        const auto &plan = plans[plan_index];
+        auto resolved_res = ResolveRoot(*connector, plan.key);
+        if (!resolved_res) {
+            return tl::make_unexpected(resolved_res.error());
+        }
+        if (!resolved_res.value()) {
+            return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+        }
+        const auto &resolved = *resolved_res.value();
+        const std::string &object_blob = resolved.object_blob;
+        NvmeKvObjectHeader header{};
+        std::string_view identity_metadata_view;
+        std::string_view payload_view;
+        if (!ParseNvmeKvObjectBlob(object_blob, header, identity_metadata_view,
+                                   payload_view)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+
+        NvmeKvStoredIdentityView stored_identity_view{};
+        if (!ParseNvmeKvStoredIdentity(identity_metadata_view,
+                                       stored_identity_view) ||
+            stored_identity_view.logical_key.empty() ||
+            stored_identity_view.logical_key != plan.key) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        NvmeKvObjectIdentity identity{.logical_key =
+                                          stored_identity_view.logical_key};
+        if (!NvmeKvKeyConflictPolicy::ValidateResolvedRootPlacement(
+                identity, stored_identity_view, resolved.physical_key) ||
+            stored_identity_view.resolved_slot != resolved.slot) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+
+        const auto object_type =
+            static_cast<NvmeKvObjectType>(header.object_type);
+        const uint32_t expected_identity_size =
+            ComputeNvmeKvStoredIdentityMetadataSize(identity);
+        if (object_type == NvmeKvObjectType::kInline) {
+            if (!ValidateNvmeKvHeader(
+                    header, identity, expected_identity_size,
+                    static_cast<uint32_t>(plan.dest_slice.size),
+                    NvmeKvObjectType::kInline) ||
+                header.payload_checksum !=
+                    ComputeNvmeKvPayloadChecksum(payload_view) ||
+                payload_view.size() != plan.dest_slice.size) {
+                return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+            }
+            std::memcpy(plan.dest_slice.ptr, payload_view.data(),
+                        payload_view.size());
+            return {};
+        }
+
+        if (object_type != NvmeKvObjectType::kManifest ||
+            !ValidateNvmeKvHeader(header, identity, expected_identity_size,
+                                  static_cast<uint32_t>(payload_view.size()),
+                                  NvmeKvObjectType::kManifest) ||
+            header.payload_checksum !=
+                ComputeNvmeKvPayloadChecksum(payload_view)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+
+        NvmeKvManifestMetadata metadata{};
+        std::vector<NvmeKvManifestChunkRecord> chunk_records;
+        if (!ParseNvmeKvManifest(payload_view, metadata, chunk_records) ||
+            metadata.logical_payload_size != plan.dest_slice.size ||
+            metadata.chunk_count != chunk_records.size()) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+
+        auto cached_manifest =
+            CacheManifest(plan.key, plan.dest_slice.size,
+                          stored_identity_view.resolved_slot, chunk_records);
+        if (cached_manifest == nullptr) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        prepared_reads[plan_index].manifest = std::move(cached_manifest);
+        return {};
+    };
+
+    const auto load_chunk_blob =
+        [&](size_t plan_index, size_t chunk_index,
+            std::string_view chunk_blob) -> tl::expected<void, ErrorCode> {
+        const auto &plan = plans[plan_index];
+        const auto &prepared = prepared_reads[plan_index];
+        const auto &chunk_record =
+            prepared.manifest->chunk_records[chunk_index];
+        if (chunk_blob.size() != chunk_record.payload_size ||
+            chunk_record.payload_checksum !=
+                ComputeNvmeKvPayloadChecksum(chunk_blob)) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        std::memcpy(static_cast<char *>(plan.dest_slice.ptr) +
+                        prepared.manifest->chunk_offsets[chunk_index],
+                    chunk_blob.data(), chunk_blob.size());
+        return {};
+    };
+
+    std::vector<tl::expected<void, ErrorCode>> prepare_results(plans.size());
+    std::vector<size_t> prepare_misses;
+    prepare_misses.reserve(plans.size());
+    for (size_t plan_index = 0; plan_index < plans.size(); ++plan_index) {
+        if (plans[plan_index].cached_manifest == nullptr) {
+            prepare_misses.push_back(plan_index);
+            continue;
+        }
+        prepared_reads[plan_index].manifest = plans[plan_index].cached_manifest;
+        prepare_results[plan_index] = {};
+    }
+    try {
+        RunParallelIo(prepare_misses.size(), [&](size_t index) {
+            const size_t plan_index = prepare_misses[index];
+            prepare_results[plan_index] = prepare_one(plan_index);
+        });
+        for (const auto &result : prepare_results) {
+            if (!result) {
+                return tl::make_unexpected(result.error());
+            }
+        }
+
+        std::vector<tl::expected<void, ErrorCode>> chunk_results(plans.size());
+        const size_t read_plan_batch_size = ReadPlanBatchSize();
+        const size_t read_group_count =
+            (plans.size() + read_plan_batch_size - 1) / read_plan_batch_size;
+        struct ChunkContext {
+            size_t plan_index = 0;
+            size_t chunk_index = 0;
+        };
+        struct ReadBatch {
+            std::vector<NvmeKvCommandExecutor::RetrieveIntoRequest>
+                direct_requests;
+            std::vector<ChunkContext> direct_contexts;
+            std::vector<NvmeKvCommandExecutor::RetrieveBufferRequest>
+                buffer_requests;
+            std::vector<ChunkContext> buffer_contexts;
+        };
+
+        const auto read_group = [&](size_t group_index) {
+            const size_t plan_begin = group_index * read_plan_batch_size;
+            const size_t plan_end =
+                std::min(plans.size(), plan_begin + read_plan_batch_size);
+            ReadBatch batch;
+
+            for (size_t plan_index = plan_begin; plan_index < plan_end;
+                 ++plan_index) {
+                const auto &prepared = prepared_reads[plan_index];
+                const auto chunk_count =
+                    !prepared.manifest
+                        ? 0
+                        : prepared.manifest->chunk_records.size();
+                if (chunk_count == 0) {
+                    chunk_results[plan_index] = {};
+                    continue;
+                }
+                for (size_t chunk_index = 0; chunk_index < chunk_count;
+                     ++chunk_index) {
+                    const auto &chunk_record =
+                        prepared.manifest->chunk_records[chunk_index];
+                    char *dest =
+                        static_cast<char *>(plans[plan_index].dest_slice.ptr) +
+                        prepared.manifest->chunk_offsets[chunk_index];
+                    if (CanRetrieveDirectlyInto(dest,
+                                                chunk_record.payload_size)) {
+                        NvmeKvCommandExecutor::RetrieveIntoRequest request;
+                        request.key = chunk_record.physical_key;
+                        request.data = dest;
+                        request.size = chunk_record.payload_size;
+                        batch.direct_contexts.push_back(
+                            ChunkContext{plan_index, chunk_index});
+                        batch.direct_requests.push_back(std::move(request));
+                    } else {
+                        NvmeKvCommandExecutor::RetrieveBufferRequest request;
+                        request.key = chunk_record.physical_key;
+                        request.size_hint = chunk_record.payload_size;
+                        batch.buffer_contexts.push_back(
+                            ChunkContext{plan_index, chunk_index});
+                        batch.buffer_requests.push_back(std::move(request));
+                    }
+                }
+            }
+
+            if (!batch.direct_requests.empty()) {
+                connector->RetrieveIntoBatch(batch.direct_requests);
+                for (size_t i = 0; i < batch.direct_requests.size(); ++i) {
+                    const auto &context = batch.direct_contexts[i];
+                    const auto &direct_res = batch.direct_requests[i].result;
+                    if (!direct_res) {
+                        chunk_results[context.plan_index] =
+                            tl::make_unexpected(direct_res.error());
+                        continue;
+                    }
+                    const auto &chunk_record =
+                        prepared_reads[context.plan_index]
+                            .manifest->chunk_records[context.chunk_index];
+                    if (direct_res.value() != chunk_record.payload_size) {
+                        chunk_results[context.plan_index] =
+                            tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                        continue;
+                    }
+                }
+            }
+
+            if (!batch.buffer_requests.empty()) {
+                connector->RetrieveBufferBatch(batch.buffer_requests);
+                for (size_t i = 0; i < batch.buffer_requests.size(); ++i) {
+                    const auto &context = batch.buffer_contexts[i];
+                    if (!chunk_results[context.plan_index]) {
+                        continue;
+                    }
+                    const auto &chunk_res = batch.buffer_requests[i].result;
+                    if (!chunk_res) {
+                        chunk_results[context.plan_index] =
+                            tl::make_unexpected(chunk_res.error());
+                        continue;
+                    }
+                    const auto &chunk_buffer = chunk_res.value();
+                    auto loaded = load_chunk_blob(
+                        context.plan_index, context.chunk_index,
+                        std::string_view(chunk_buffer.data, chunk_buffer.size));
+                    if (!loaded) {
+                        chunk_results[context.plan_index] = loaded;
+                    }
+                }
+            }
+
+            for (size_t plan_index = plan_begin; plan_index < plan_end;
+                 ++plan_index) {
+                if (!chunk_results[plan_index]) {
+                    continue;
+                }
+                chunk_results[plan_index] = {};
+            }
+        };
+
+        const auto verify_read_group = [&](size_t group_index) {
+            const size_t plan_begin = group_index * read_plan_batch_size;
+            const size_t plan_end =
+                std::min(plans.size(), plan_begin + read_plan_batch_size);
+            for (size_t plan_index = plan_begin; plan_index < plan_end;
+                 ++plan_index) {
+                if (!chunk_results[plan_index]) {
+                    continue;
+                }
+                const auto &manifest = prepared_reads[plan_index].manifest;
+                if (manifest == nullptr) {
+                    continue;
+                }
+                for (size_t chunk_index = 0;
+                     chunk_index < manifest->chunk_records.size();
+                     ++chunk_index) {
+                    const auto &chunk_record =
+                        manifest->chunk_records[chunk_index];
+                    const char *dest = static_cast<const char *>(
+                                           plans[plan_index].dest_slice.ptr) +
+                                       manifest->chunk_offsets[chunk_index];
+                    if (!CanRetrieveDirectlyInto(dest,
+                                                 chunk_record.payload_size)) {
+                        continue;
+                    }
+                    if (chunk_record.payload_checksum !=
+                        ComputeNvmeKvPayloadChecksum(std::string_view(
+                            dest, chunk_record.payload_size))) {
+                        chunk_results[plan_index] =
+                            tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                        break;
+                    }
+                }
+            }
+        };
+
+        RunPipelinedIo(read_group_count, read_group, verify_read_group);
+        for (size_t plan_index = 0; plan_index < plans.size(); ++plan_index) {
+            if (!chunk_results[plan_index]) {
+                const auto error = chunk_results[plan_index].error();
+                return tl::make_unexpected(error);
+            }
+        }
+    } catch (const std::exception &error) {
+        LOG(ERROR) << "NVMe KV batch load worker failed: " << error.what();
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    } catch (...) {
+        LOG(ERROR) << "NVMe KV batch load worker failed";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+
+    return {};
+}
+
+tl::expected<bool, ErrorCode> NvmeKvStorageBackend::IsExist(
+    const std::string &key) {
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    const auto connector = connector_;
+    if (connector == nullptr) {
+        return false;
+    }
+    auto resolved = ResolveRoot(*connector, key);
+    if (!resolved) {
+        return tl::make_unexpected(resolved.error());
+    }
+    return resolved.value().has_value();
+}
+
+tl::expected<bool, ErrorCode> NvmeKvStorageBackend::IsEnableOffloading() {
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    if (connector_ == nullptr) {
+        return false;
+    }
+    return total_keys_.load(std::memory_order_relaxed) <
+               file_storage_config_.total_keys_limit &&
+           total_size_.load(std::memory_order_relaxed) <
+               file_storage_config_.total_size_limit;
+}
+
+tl::expected<void, ErrorCode> NvmeKvStorageBackend::ScanMeta(
+    const std::function<
+        ErrorCode(const std::vector<std::string> &keys,
+                  std::vector<StorageObjectMetadata> &metadatas)> &handler) {
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    (void)handler;
+    return {};
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/connector_config.cpp b/mooncake-store/src/nvme_kv/config/connector_config.cpp
new file mode 100644
index 0000000000..ec77972871
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/connector_config.cpp
@@ -0,0 +1,86 @@
+#include "connector_config.h"
+
+#include <glog/logging.h>
+
+#include <optional>
+#include <string>
+
+#include "environ.h"
+#include "environment_variables.h"
+#include "u32_parser.h"
+
+namespace mooncake {
+namespace {
+
+uint32_t ReadNvmeKvU32Or(const EnvironmentVariable<std::string>& variable,
+                         uint32_t fallback) {
+    const auto value = Environ::Read(variable);
+    if (!value.has_value()) {
+        return fallback;
+    }
+    return TryParseNvmeKvU32(value->c_str()).value_or(fallback);
+}
+
+tl::expected<NvmeKvTransport, ErrorCode> ReadTransport() {
+    const auto transport =
+        Environ::Read(
+            NvmeKvConnectorEnvironmentVariables::MOONCAKE_NVME_KV_TRANSPORT)
+            .value_or("");
+    if (transport.empty() || transport == "auto") {
+        return NvmeKvTransport::kAuto;
+    }
+    if (transport == "io_uring") {
+        return NvmeKvTransport::kIoUring;
+    }
+    if (transport == "ioctl") {
+        return NvmeKvTransport::kIoctl;
+    }
+    LOG(ERROR) << "Unknown MOONCAKE_NVME_KV_TRANSPORT: " << transport;
+    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+}
+
+}  // namespace
+
+const char* NvmeKvTransportName(NvmeKvTransport transport) {
+    switch (transport) {
+        case NvmeKvTransport::kAuto:
+            return "auto";
+        case NvmeKvTransport::kIoUring:
+            return "io_uring";
+        case NvmeKvTransport::kIoctl:
+            return "ioctl";
+    }
+    return "unknown";
+}
+
+tl::expected<NvmeKvConnectorConfig, ErrorCode>
+NvmeKvConnectorConfig::FromEnvironment() {
+    NvmeKvConnectorConfig config;
+    config.device_path =
+        Environ::Read(
+            NvmeKvConnectorEnvironmentVariables::MOONCAKE_NVME_KV_DEVICE_PATH)
+            .value_or("");
+    if (config.device_path.empty()) {
+        LOG(ERROR) << "MOONCAKE_NVME_KV_DEVICE_PATH must not be empty";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    config.nsid = ReadNvmeKvU32Or(
+        NvmeKvConnectorEnvironmentVariables::MOONCAKE_NVME_KV_NSID,
+        config.nsid);
+    config.queue_depth = ReadNvmeKvU32Or(
+        NvmeKvConnectorEnvironmentVariables::MOONCAKE_NVME_KV_QUEUE_DEPTH,
+        config.queue_depth);
+    config.runtime_transfer_limit =
+        ReadNvmeKvU32Or(NvmeKvConnectorEnvironmentVariables::
+                            MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT,
+                        config.runtime_transfer_limit);
+    auto transport = ReadTransport();
+    if (!transport.has_value()) {
+        return tl::make_unexpected(transport.error());
+    }
+    config.transport = *transport;
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/connector_config.h b/mooncake-store/src/nvme_kv/config/connector_config.h
new file mode 100644
index 0000000000..a6e10a76e9
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/connector_config.h
@@ -0,0 +1,30 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+#include <ylt/util/tl/expected.hpp>
+
+#include "types.h"
+
+namespace mooncake {
+
+enum class NvmeKvTransport {
+    kAuto,
+    kIoUring,
+    kIoctl,
+};
+
+const char* NvmeKvTransportName(NvmeKvTransport transport);
+
+struct NvmeKvConnectorConfig {
+    std::string device_path;
+    uint32_t nsid = 1;
+    uint32_t queue_depth = 256;
+    uint32_t runtime_transfer_limit = 270336;
+    NvmeKvTransport transport = NvmeKvTransport::kAuto;
+
+    static tl::expected<NvmeKvConnectorConfig, ErrorCode> FromEnvironment();
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/io_concurrency_config.cpp b/mooncake-store/src/nvme_kv/config/io_concurrency_config.cpp
new file mode 100644
index 0000000000..22880a9387
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/io_concurrency_config.cpp
@@ -0,0 +1,86 @@
+#include "io_concurrency_config.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "environ.h"
+#include "environment_variables.h"
+#include "u32_parser.h"
+
+namespace mooncake {
+namespace {
+
+constexpr std::size_t kDefaultMaxIoConcurrency = 256;
+constexpr std::size_t kDefaultIoConcurrency = 18;
+constexpr std::size_t kDefaultPrepareConcurrency = 12;
+constexpr std::size_t kDefaultBatchSubmitConcurrency = 6;
+constexpr std::size_t kDefaultRootSubmitConcurrency = 1;
+
+std::optional<std::size_t> ReadOptionalPositive(
+    const EnvironmentVariable<std::string>& variable) {
+    const auto value = Environ::Read(variable);
+    if (!value.has_value()) {
+        return std::nullopt;
+    }
+    const auto parsed = TryParseNvmeKvU32(value->c_str());
+    if (!parsed.has_value() || *parsed == 0) {
+        return std::nullopt;
+    }
+    return static_cast<std::size_t>(*parsed);
+}
+
+std::size_t ReadPositiveOr(const EnvironmentVariable<std::string>& variable,
+                           std::size_t fallback, std::size_t maximum) {
+    const auto parsed = ReadOptionalPositive(variable);
+    return parsed.has_value() ? std::min(*parsed, maximum) : fallback;
+}
+
+}  // namespace
+
+NvmeKvIoConcurrencyConfig NvmeKvIoConcurrencyConfig::FromEnvironment(
+    std::size_t device_queue_depth) {
+    NvmeKvIoConcurrencyConfig config;
+    config.max_io_concurrency = ReadPositiveOr(
+        NvmeKvIoConcurrencyEnvironmentVariables::
+            MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY,
+        kDefaultMaxIoConcurrency, std::numeric_limits<uint32_t>::max());
+
+    const auto configured_io =
+        ReadOptionalPositive(NvmeKvIoConcurrencyEnvironmentVariables::
+                                 MOONCAKE_NVME_KV_IO_CONCURRENCY);
+    config.io_concurrency =
+        configured_io.has_value()
+            ? std::min(*configured_io, config.max_io_concurrency)
+            : std::min(
+                  std::max<std::size_t>(device_queue_depth, 1),
+                  std::min(kDefaultIoConcurrency, config.max_io_concurrency));
+
+    const std::size_t max_submit_concurrency =
+        config.io_concurrency > 1 ? config.io_concurrency - 1 : 1;
+    config.batch_submit_concurrency = ReadPositiveOr(
+        NvmeKvIoConcurrencyEnvironmentVariables::
+            MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY,
+        std::min(kDefaultBatchSubmitConcurrency, max_submit_concurrency),
+        max_submit_concurrency);
+    config.root_submit_concurrency = ReadPositiveOr(
+        NvmeKvIoConcurrencyEnvironmentVariables::
+            MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY,
+        std::min(kDefaultRootSubmitConcurrency, max_submit_concurrency),
+        max_submit_concurrency);
+
+    const std::size_t max_prepare_concurrency =
+        config.io_concurrency > config.batch_submit_concurrency
+            ? config.io_concurrency - config.batch_submit_concurrency
+            : 1;
+    config.prepare_concurrency = ReadPositiveOr(
+        NvmeKvIoConcurrencyEnvironmentVariables::
+            MOONCAKE_NVME_KV_PREPARE_CONCURRENCY,
+        std::min(kDefaultPrepareConcurrency, max_prepare_concurrency),
+        max_prepare_concurrency);
+    return config;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/io_concurrency_config.h b/mooncake-store/src/nvme_kv/config/io_concurrency_config.h
new file mode 100644
index 0000000000..f3343b58a3
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/io_concurrency_config.h
@@ -0,0 +1,18 @@
+#pragma once
+
+#include <cstddef>
+
+namespace mooncake {
+
+struct NvmeKvIoConcurrencyConfig {
+    std::size_t max_io_concurrency = 256;
+    std::size_t io_concurrency = 1;
+    std::size_t batch_submit_concurrency = 1;
+    std::size_t root_submit_concurrency = 1;
+    std::size_t prepare_concurrency = 1;
+
+    static NvmeKvIoConcurrencyConfig FromEnvironment(
+        std::size_t device_queue_depth);
+};
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/u32_parser.cpp b/mooncake-store/src/nvme_kv/config/u32_parser.cpp
new file mode 100644
index 0000000000..ee6b5b90ec
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/u32_parser.cpp
@@ -0,0 +1,23 @@
+#include "u32_parser.h"
+
+#include <cerrno>
+#include <cstdlib>
+#include <limits>
+
+namespace mooncake {
+
+std::optional<uint32_t> TryParseNvmeKvU32(const char* value) {
+    if (value == nullptr) {
+        return std::nullopt;
+    }
+    char* end = nullptr;
+    errno = 0;
+    const unsigned long parsed = std::strtoul(value, &end, 0);
+    if (errno != 0 || end == value || *end != '\0' ||
+        parsed > std::numeric_limits<uint32_t>::max()) {
+        return std::nullopt;
+    }
+    return static_cast<uint32_t>(parsed);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/config/u32_parser.h b/mooncake-store/src/nvme_kv/config/u32_parser.h
new file mode 100644
index 0000000000..a26b18cf59
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/config/u32_parser.h
@@ -0,0 +1,10 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+
+namespace mooncake {
+
+std::optional<uint32_t> TryParseNvmeKvU32(const char* value);
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/connector.cpp b/mooncake-store/src/nvme_kv/connector.cpp
new file mode 100644
index 0000000000..2a6295ad52
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/connector.cpp
@@ -0,0 +1,159 @@
+#include "nvme_kv/connector.h"
+
+#include <cstdlib>
+#include <filesystem>
+#include <string_view>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "config/connector_config.h"
+#include "nvme_kv/executor_util.h"
+#include "storage_backend.h"
+
+namespace mooncake {
+
+#ifdef MOONCAKE_ENABLE_NVME_KV_TEST_STUB
+std::unique_ptr<NvmeKvCommandExecutor> CreateNvmeKvStubExecutor(
+    std::filesystem::path storage_path);
+#endif
+
+NvmeKvConnector::NvmeKvConnector(const FileStorageConfig &config)
+    : storage_path_(
+          (std::filesystem::path(config.storage_filepath) / "nvme_kv_blobs")
+              .string()) {}
+
+tl::expected<void, ErrorCode> NvmeKvConnector::Init() {
+    if (executor_ != nullptr) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+#ifdef MOONCAKE_ENABLE_NVME_KV_TEST_STUB
+    const char *driver = std::getenv("MOONCAKE_NVME_KV_DRIVER");
+    if (driver != nullptr && std::string_view(driver) == "stub") {
+        std::error_code ec;
+        std::filesystem::create_directories(storage_path_, ec);
+        if (ec) {
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+        executor_ =
+            CreateNvmeKvStubExecutor(std::filesystem::path(storage_path_));
+        return {};
+    }
+#endif
+
+    return InitRealExecutor();
+}
+
+tl::expected<void, ErrorCode> NvmeKvConnector::InitRealExecutor() {
+    auto config = NvmeKvConnectorConfig::FromEnvironment();
+    if (!config.has_value()) {
+        return tl::make_unexpected(config.error());
+    }
+
+    const auto create_executor =
+        [&](NvmeKvTransport selected_transport) -> NvmeKvExecutorResult {
+        switch (selected_transport) {
+            case NvmeKvTransport::kIoUring:
+                return CreateNvmeKvIoUringExecutor(
+                    config->device_path, config->nsid, config->queue_depth,
+                    config->runtime_transfer_limit);
+            case NvmeKvTransport::kIoctl:
+                return CreateNvmeKvIoctlExecutor(
+                    config->device_path, config->nsid, config->queue_depth,
+                    config->runtime_transfer_limit);
+            case NvmeKvTransport::kAuto:
+                break;
+        }
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    };
+
+    NvmeKvExecutorResult executor_result =
+        tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    if (config->transport == NvmeKvTransport::kAuto) {
+#ifdef MOONCAKE_HAVE_NVME_URING_CMD
+        executor_result = create_executor(NvmeKvTransport::kIoUring);
+        if (!executor_result) {
+            LOG(WARNING) << "NVMe KV io_uring init failed, falling back to "
+                            "ioctl: "
+                         << toString(executor_result.error());
+        }
+#endif
+        if (!executor_result) {
+            executor_result = create_executor(NvmeKvTransport::kIoctl);
+        }
+    } else {
+        executor_result = create_executor(config->transport);
+    }
+
+    if (!executor_result) {
+        LOG(ERROR) << "Failed to initialize NVMe KV "
+                   << NvmeKvTransportName(config->transport) << " executor";
+        return tl::make_unexpected(executor_result.error());
+    }
+    executor_ = std::move(executor_result.value());
+    return {};
+}
+
+tl::expected<void, ErrorCode> NvmeKvConnector::Store(const PhysicalKey &key,
+                                                     std::string value) {
+    if (executor_ == nullptr) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return executor_->Store(key, std::move(value));
+}
+
+void NvmeKvConnector::StoreBatch(
+    std::vector<NvmeKvCommandExecutor::StoreRequest> &requests) {
+    if (executor_ == nullptr) {
+        for (auto &request : requests) {
+            request.result = tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        return;
+    }
+    executor_->StoreBatch(requests);
+}
+
+tl::expected<std::string, ErrorCode> NvmeKvConnector::Retrieve(
+    const PhysicalKey &key, uint32_t size_hint) const {
+    if (executor_ == nullptr) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return executor_->Retrieve(key, size_hint);
+}
+
+void NvmeKvConnector::RetrieveBufferBatch(
+    std::vector<NvmeKvCommandExecutor::RetrieveBufferRequest> &requests) const {
+    if (executor_ == nullptr) {
+        for (auto &request : requests) {
+            request.result = tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        return;
+    }
+    executor_->RetrieveBufferBatch(requests);
+}
+
+void NvmeKvConnector::RetrieveIntoBatch(
+    std::vector<NvmeKvCommandExecutor::RetrieveIntoRequest> &requests) const {
+    if (executor_ == nullptr) {
+        for (auto &request : requests) {
+            request.result = tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        return;
+    }
+    executor_->RetrieveIntoBatch(requests);
+}
+
+tl::expected<void, ErrorCode> NvmeKvConnector::Delete(const PhysicalKey &key) {
+    if (executor_ == nullptr) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return executor_->Delete(key);
+}
+
+const NvmeKvConnector::Capabilities &NvmeKvConnector::GetCapabilities() const {
+    static const Capabilities kDefaultCapabilities{};
+    return executor_ == nullptr ? kDefaultCapabilities
+                                : executor_->GetCapabilities();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/executor_io_uring.cpp b/mooncake-store/src/nvme_kv/executor_io_uring.cpp
new file mode 100644
index 0000000000..3aa85abb7e
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/executor_io_uring.cpp
@@ -0,0 +1,792 @@
+#include "nvme_kv/executor.h"
+
+#ifdef MOONCAKE_HAVE_NVME_URING_CMD
+
+#include "nvme_kv/executor_util.h"
+#include "nvme_kv/object_layout.h"
+
+#include <fcntl.h>
+#include <liburing.h>
+#include <linux/nvme_ioctl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+// IORING_SETUP_SQE128 was introduced in Linux 5.19.  Provide a fallback
+// definition so the file compiles against older kernel headers (the feature
+// is only usable at runtime on 5.19+ kernels).
+#ifndef IORING_SETUP_SQE128
+#define IORING_SETUP_SQE128 (1U << 10)
+#endif
+
+#include <algorithm>
+#include <cerrno>
+#include <cstdint>
+#include <cstring>
+#include <filesystem>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <glog/logging.h>
+
+namespace mooncake {
+namespace {
+
+bool CanSubmitCallerBufferDirectly(std::string_view value,
+                                   uint32_t submission_bytes) {
+    if (value.empty() || submission_bytes != value.size()) {
+        return false;
+    }
+    const size_t required_alignment = std::max<size_t>(
+        kDefaultNvmeKvTransferAlignmentBytes, NvmeKvTransferAlignmentBytes());
+    return reinterpret_cast<uintptr_t>(value.data()) % required_alignment == 0;
+}
+
+bool IsCharacterDevice(const std::filesystem::path& path) {
+    struct stat st{};
+    return ::stat(path.c_str(), &st) == 0 && S_ISCHR(st.st_mode);
+}
+
+std::string ResolveIoUringDevicePath(const std::string& device_path) {
+    const std::filesystem::path path(device_path);
+    if (IsCharacterDevice(path)) {
+        return device_path;
+    }
+
+    const std::string filename = path.filename().string();
+    if (filename.rfind("nvme", 0) != 0) {
+        return device_path;
+    }
+    const std::filesystem::path generic_path =
+        path.parent_path() / ("ng" + filename.substr(4));
+    if (IsCharacterDevice(generic_path)) {
+        LOG(INFO) << "[NvmeKvIoUringExecutor] using NVMe generic char device "
+                  << generic_path << " for namespace block device "
+                  << device_path;
+        return generic_path.string();
+    }
+    return device_path;
+}
+
+class SharedNvmeUringRing {
+   public:
+    struct BatchCommand {
+        struct nvme_uring_cmd cmd{};
+        bool is_write = false;
+        size_t context_index = 0;
+        uint32_t observed_result = 0;
+        bool has_observed_result = false;
+        ErrorCode mapped_error = ErrorCode::OK;
+        bool submitted = false;
+        bool completed = false;
+    };
+
+    static SharedNvmeUringRing& Instance(unsigned queue_depth) {
+        const unsigned normalized_queue_depth =
+            queue_depth == 0 ? kDefaultNvmeKvQueueDepth : queue_depth;
+        thread_local std::unique_ptr<SharedNvmeUringRing> ring;
+        if (ring == nullptr || ring->QueueDepth() != normalized_queue_depth) {
+            ring.reset(new SharedNvmeUringRing(normalized_queue_depth));
+        }
+        return *ring;
+    }
+
+    bool IsInitialized() const { return initialized_; }
+
+    tl::expected<void, ErrorCode> SubmitBatch(
+        int fd, std::vector<BatchCommand>& commands) {
+        if (commands.empty()) {
+            return {};
+        }
+        if (!initialized_) {
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        if (commands.size() >= UINT32_MAX) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+
+        const uint32_t completion_token = NextCompletionToken();
+        size_t next_command = 0;
+        size_t completed_count = 0;
+        size_t inflight_ops = 0;
+        ErrorCode batch_error = ErrorCode::OK;
+
+        const auto drain_ready = [&]() -> tl::expected<size_t, ErrorCode> {
+            size_t drained = 0;
+            while (inflight_ops != 0) {
+                io_uring_cqe* cqe = nullptr;
+                const int peek_ret = io_uring_peek_cqe(&ring_, &cqe);
+                if (peek_ret == -EAGAIN) {
+                    break;
+                }
+                if (peek_ret < 0 || cqe == nullptr) {
+                    return tl::make_unexpected(
+                        MapNvmeKvTransportError(peek_ret < 0 ? -peek_ret : EIO,
+                                                commands.front().is_write));
+                }
+                const uint64_t user_data = cqe->user_data;
+                const int res = cqe->res;
+                const uint64_t cqe_extra_result =
+                    cqe32_enabled_ ? cqe->big_cqe[0] : static_cast<uint64_t>(0);
+                io_uring_cqe_seen(&ring_, cqe);
+
+                const auto complete_unknown_inflight = [&]() -> bool {
+                    for (auto& command : commands) {
+                        if (!command.submitted || command.completed) {
+                            continue;
+                        }
+                        command.mapped_error = ErrorCode::INTERNAL_ERROR;
+                        command.completed = true;
+                        --inflight_ops;
+                        ++completed_count;
+                        ++drained;
+                        return true;
+                    }
+                    return false;
+                };
+
+                size_t command_index = 0;
+                if (!DecodeUserData(user_data, completion_token,
+                                    command_index) ||
+                    command_index >= commands.size() ||
+                    !commands[command_index].submitted ||
+                    commands[command_index].completed) {
+                    LOG(ERROR) << "[NvmeKvIoUringExecutor] invalid or stale "
+                                  "io_uring completion token";
+                    batch_error = ErrorCode::INTERNAL_ERROR;
+                    if (!complete_unknown_inflight()) {
+                        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    }
+                    continue;
+                }
+                auto& command = commands[command_index];
+                if (res >= 0 && cqe32_enabled_ &&
+                    cqe_extra_result <= UINT32_MAX) {
+                    command.observed_result =
+                        static_cast<uint32_t>(cqe_extra_result);
+                    command.has_observed_result = true;
+                }
+                if (res > 0) {
+                    command.mapped_error = MapNvmeKvStatus(
+                        static_cast<uint32_t>(res), command.is_write);
+                } else if (res < 0) {
+                    command.mapped_error =
+                        MapNvmeKvTransportError(-res, command.is_write);
+                } else {
+                    command.mapped_error = ErrorCode::OK;
+                }
+                command.completed = true;
+                --inflight_ops;
+                ++completed_count;
+                ++drained;
+            }
+            return drained;
+        };
+
+        const auto wait_and_drain =
+            [&](unsigned wait_min) -> tl::expected<size_t, ErrorCode> {
+            io_uring_cqe* first_cqe = nullptr;
+            int wait_ret = 0;
+            do {
+                wait_ret = io_uring_wait_cqe_nr(&ring_, &first_cqe, wait_min);
+            } while (wait_ret == -EINTR);
+            if (wait_ret < 0 || first_cqe == nullptr) {
+                return tl::make_unexpected(MapNvmeKvTransportError(
+                    wait_ret < 0 ? -wait_ret : EIO, commands.front().is_write));
+            }
+            // wait_cqe_nr leaves first_cqe in the CQ; drain_ready consumes it
+            // together with any other completions that are already available.
+            return drain_ready();
+        };
+
+        while (completed_count < commands.size()) {
+            const size_t prepared_start = next_command;
+            size_t prepared_ops = 0;
+            while (next_command < commands.size() &&
+                   inflight_ops + prepared_ops < queue_depth_) {
+                auto& command = commands[next_command];
+                io_uring_sqe* sqe = io_uring_get_sqe(&ring_);
+                if (sqe == nullptr) {
+                    break;
+                }
+                PrepareSqe(sqe, fd, command.cmd,
+                           EncodeUserData(completion_token, next_command));
+                ++next_command;
+                ++prepared_ops;
+            }
+            if (prepared_ops == 0 && inflight_ops == 0) {
+                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+
+            ErrorCode submit_error = ErrorCode::OK;
+            size_t submitted_prepared = 0;
+            while (submitted_prepared < prepared_ops) {
+                int submit_ret = 0;
+                do {
+                    submit_ret = submitted_prepared == 0
+                                     ? io_uring_submit_and_wait(&ring_, 1)
+                                     : io_uring_submit(&ring_);
+                } while (submit_ret == -EINTR);
+                const size_t remaining = prepared_ops - submitted_prepared;
+                if (submit_ret <= 0 ||
+                    static_cast<size_t>(submit_ret) > remaining) {
+                    submit_error = MapNvmeKvTransportError(
+                        submit_ret < 0 ? -submit_ret : EIO,
+                        commands.front().is_write);
+                    break;
+                }
+                const size_t accepted = static_cast<size_t>(submit_ret);
+                for (size_t index = 0; index < accepted; ++index) {
+                    auto& command =
+                        commands[prepared_start + submitted_prepared + index];
+                    command.submitted = true;
+                    ++inflight_ops;
+                }
+                submitted_prepared += accepted;
+            }
+
+            if (submit_error != ErrorCode::OK) {
+                while (inflight_ops != 0) {
+                    auto drain_result = wait_and_drain(1);
+                    if (!drain_result || drain_result.value() == 0) {
+                        const ErrorCode drain_error =
+                            drain_result ? ErrorCode::INTERNAL_ERROR
+                                         : drain_result.error();
+                        ResetRing();
+                        return tl::make_unexpected(drain_error);
+                    }
+                }
+                ResetRing();
+                return tl::make_unexpected(submit_error);
+            }
+
+            auto drain_result = wait_and_drain(1);
+            if (!drain_result || drain_result.value() == 0) {
+                const ErrorCode drain_error = drain_result
+                                                  ? ErrorCode::INTERNAL_ERROR
+                                                  : drain_result.error();
+                ResetRing();
+                return tl::make_unexpected(drain_error);
+            }
+        }
+        if (batch_error != ErrorCode::OK) {
+            ResetRing();
+            return tl::make_unexpected(batch_error);
+        }
+        return {};
+    }
+
+   private:
+    explicit SharedNvmeUringRing(unsigned queue_depth)
+        : queue_depth_(queue_depth == 0 ? kDefaultNvmeKvQueueDepth
+                                        : queue_depth) {
+        InitializeRing();
+    }
+
+    void InitializeRing() {
+        io_uring_params params{};
+        // IORING_SETUP_SQE128 is required for NVMe uring_cmd passthrough
+        // because sizeof(struct nvme_uring_cmd) = 72 bytes, which exceeds the
+        // 16 bytes available in the cmd[] area of a standard 64-byte SQE.
+        params.flags = IORING_SETUP_SQE128 | IORING_SETUP_CQE32;
+        int ret = io_uring_queue_init_params(queue_depth_, &ring_, &params);
+        if (ret < 0 && (params.flags & IORING_SETUP_CQE32)) {
+            LOG(WARNING)
+                << "[NvmeKvIoUringExecutor] io_uring_queue_init_params with "
+                   "CQE32 failed: "
+                << strerror(-ret) << ", retrying with SQE128 only";
+            params.flags = IORING_SETUP_SQE128;
+            ret = io_uring_queue_init_params(queue_depth_, &ring_, &params);
+        }
+        if (ret < 0) {
+            LOG(ERROR) << "[NvmeKvIoUringExecutor] io_uring queue init failed: "
+                       << strerror(-ret);
+            return;
+        }
+        cqe32_enabled_ = (ring_.flags & IORING_SETUP_CQE32) != 0;
+        initialized_ = true;
+    }
+
+    void ResetRing() {
+        if (initialized_) {
+            io_uring_queue_exit(&ring_);
+        }
+        ring_ = {};
+        initialized_ = false;
+        cqe32_enabled_ = false;
+        InitializeRing();
+    }
+
+    unsigned QueueDepth() const { return queue_depth_; }
+
+    static void PrepareSqe(io_uring_sqe* sqe, int fd,
+                           const struct nvme_uring_cmd& cmd,
+                           uint64_t user_data) {
+        static_assert(sizeof(cmd) <= 80,
+                      "nvme_uring_cmd must fit in SQE128 cmd area");
+        constexpr size_t kSqe128Bytes = sizeof(io_uring_sqe) * 2;
+        std::memset(sqe, 0, kSqe128Bytes);
+        sqe->opcode = IORING_OP_URING_CMD;
+        sqe->fd = fd;
+        sqe->cmd_op = NVME_URING_CMD_IO;
+        sqe->len = sizeof(struct nvme_uring_cmd);
+        sqe->user_data = user_data;
+        std::memcpy(sqe->cmd, &cmd, sizeof(cmd));
+    }
+
+    uint32_t NextCompletionToken() {
+        ++completion_token_;
+        if (completion_token_ == 0) {
+            ++completion_token_;
+        }
+        return completion_token_;
+    }
+
+    static uint64_t EncodeUserData(uint32_t token, size_t command_index) {
+        return (static_cast<uint64_t>(token) << 32) |
+               (static_cast<uint32_t>(command_index) + 1u);
+    }
+
+    static bool DecodeUserData(uint64_t user_data, uint32_t expected_token,
+                               size_t& command_index) {
+        const uint32_t token = static_cast<uint32_t>(user_data >> 32);
+        const uint32_t encoded_index = static_cast<uint32_t>(user_data);
+        if (token != expected_token || encoded_index == 0) {
+            return false;
+        }
+        command_index = static_cast<size_t>(encoded_index - 1u);
+        return true;
+    }
+
+   public:
+    ~SharedNvmeUringRing() {
+        if (initialized_) {
+            io_uring_queue_exit(&ring_);
+        }
+    }
+
+   private:
+    io_uring ring_{};
+    unsigned queue_depth_ = kDefaultNvmeKvQueueDepth;
+    uint32_t completion_token_ = 0;
+    bool initialized_ = false;
+    bool cqe32_enabled_ = false;
+};
+
+class NvmeKvIoUringExecutor : public NvmeKvCommandExecutor {
+   public:
+    NvmeKvIoUringExecutor(std::string device_path, uint32_t nsid,
+                          Capabilities capabilities)
+        : device_path_(std::move(device_path)),
+          nsid_(nsid),
+          capabilities_(capabilities) {}
+
+    tl::expected<void, ErrorCode> Init() {
+        const std::string io_uring_device_path =
+            ResolveIoUringDevicePath(device_path_);
+        if (!IsCharacterDevice(io_uring_device_path)) {
+            LOG(WARNING) << "[NvmeKvIoUringExecutor] io_uring requires an NVMe "
+                            "generic character device, configured path="
+                         << device_path_
+                         << " resolved path=" << io_uring_device_path;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+
+        fd_ = ::open(io_uring_device_path.c_str(), O_RDWR | O_CLOEXEC);
+        if (fd_ < 0) {
+            LOG(ERROR) << "[NvmeKvIoUringExecutor] open failed for "
+                       << io_uring_device_path << " (configured "
+                       << device_path_ << "): " << strerror(errno);
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+
+        auto& ring = CurrentThreadRing();
+        if (!ring.IsInitialized()) {
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        return {};
+    }
+
+    ~NvmeKvIoUringExecutor() override {
+        if (fd_ >= 0) {
+            ::close(fd_);
+        }
+    }
+
+    tl::expected<void, ErrorCode> Store(const PhysicalKey& key,
+                                        std::string value) override {
+        StoreRequest request;
+        request.key = key;
+        request.value = value;
+        std::vector<StoreRequest> requests;
+        requests.push_back(std::move(request));
+        StoreBatch(requests);
+        return std::move(requests.front().result);
+    }
+
+    void StoreBatch(std::vector<StoreRequest>& requests) override {
+        std::vector<NvmeKvAlignedBuffer> dma_buffers;
+        dma_buffers.reserve(requests.size());
+        std::vector<SharedNvmeUringRing::BatchCommand> commands;
+        commands.reserve(requests.size());
+
+        for (size_t index = 0; index < requests.size(); ++index) {
+            auto& request = requests[index];
+            if (request.value.size() > capabilities_.effective_max_value_size) {
+                request.result = tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                continue;
+            }
+            const uint32_t value_size =
+                static_cast<uint32_t>(request.value.size());
+            const uint32_t submission_bytes =
+                ResolveNvmeKvStoreSubmissionBytes(value_size);
+            if (submission_bytes > capabilities_.effective_max_value_size) {
+                request.result = tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                continue;
+            }
+            const char* submission_data = request.value.data();
+            if (!CanSubmitCallerBufferDirectly(request.value,
+                                               submission_bytes)) {
+                auto dma_buffer = AllocateNvmeKvAlignedBuffer(submission_bytes);
+                if (dma_buffer == nullptr) {
+                    request.result =
+                        tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                    continue;
+                }
+                std::memset(dma_buffer.get(), 0, submission_bytes);
+                if (!request.value.empty()) {
+                    std::memcpy(dma_buffer.get(), request.value.data(),
+                                request.value.size());
+                }
+                submission_data = dma_buffer.get();
+                dma_buffers.push_back(std::move(dma_buffer));
+            }
+
+            SharedNvmeUringRing::BatchCommand command;
+            command.is_write = true;
+            command.context_index = index;
+            BuildNvmeKvStoreCommand(command.cmd, nsid_, request.key,
+                                    submission_data, submission_bytes);
+
+            commands.push_back(std::move(command));
+        }
+
+        auto submit_result = CurrentThreadRing().SubmitBatch(fd_, commands);
+        const ErrorCode uncompleted_error =
+            submit_result ? ErrorCode::INTERNAL_ERROR : submit_result.error();
+        for (const auto& command : commands) {
+            if (command.completed && command.mapped_error == ErrorCode::OK) {
+                requests[command.context_index].result = {};
+            } else {
+                requests[command.context_index].result =
+                    tl::make_unexpected(command.completed ? command.mapped_error
+                                                          : uncompleted_error);
+            }
+        }
+    }
+
+    tl::expected<std::string, ErrorCode> Retrieve(
+        const PhysicalKey& key, uint32_t size_hint = 0) const override {
+        RetrieveBufferRequest request;
+        request.key = key;
+        request.size_hint = size_hint;
+        std::vector<RetrieveBufferRequest> requests;
+        requests.push_back(std::move(request));
+        RetrieveBufferBatch(requests);
+        if (!requests.front().result) {
+            return tl::make_unexpected(requests.front().result.error());
+        }
+        return requests.front().result->ToString();
+    }
+
+    void RetrieveBufferBatch(
+        std::vector<RetrieveBufferRequest>& requests) const override {
+        struct RetrieveAttempt {
+            size_t request_index = 0;
+            uint32_t request_bytes = 0;
+            NvmeKvAlignedBuffer dma_buffer;
+            uint32_t returned_size = 0;
+            ErrorCode error = ErrorCode::OK;
+            bool completed = false;
+        };
+        const auto make_attempt = [](size_t request_index,
+                                     uint32_t request_bytes) {
+            RetrieveAttempt attempt;
+            attempt.request_index = request_index;
+            attempt.request_bytes = request_bytes;
+            return attempt;
+        };
+
+        const auto submit_attempts = [&](std::vector<RetrieveAttempt>& attempts)
+            -> tl::expected<void, ErrorCode> {
+            std::vector<SharedNvmeUringRing::BatchCommand> commands;
+            commands.reserve(attempts.size());
+            for (size_t attempt_index = 0; attempt_index < attempts.size();
+                 ++attempt_index) {
+                auto& attempt = attempts[attempt_index];
+                const uint32_t transfer_bytes =
+                    RoundUpToNvmeKvTransferBytes(attempt.request_bytes);
+                if (transfer_bytes > capabilities_.effective_max_value_size) {
+                    attempt.error = ErrorCode::BUFFER_OVERFLOW;
+                    attempt.completed = true;
+                    continue;
+                }
+                attempt.dma_buffer =
+                    AllocateNvmeKvAlignedBuffer(transfer_bytes);
+                if (attempt.dma_buffer == nullptr) {
+                    attempt.error = ErrorCode::INTERNAL_ERROR;
+                    attempt.completed = true;
+                    continue;
+                }
+
+                const auto& request = requests[attempt.request_index];
+                SharedNvmeUringRing::BatchCommand command;
+                command.is_write = false;
+                command.context_index = attempt_index;
+                BuildNvmeKvRetrieveCommand(command.cmd, nsid_, request.key,
+                                           attempt.dma_buffer.get(),
+                                           transfer_bytes);
+                commands.push_back(std::move(command));
+            }
+
+            auto submit_result = CurrentThreadRing().SubmitBatch(fd_, commands);
+            const ErrorCode uncompleted_error = submit_result
+                                                    ? ErrorCode::INTERNAL_ERROR
+                                                    : submit_result.error();
+            for (const auto& command : commands) {
+                auto& attempt = attempts[command.context_index];
+                attempt.completed = command.completed;
+                attempt.error = command.completed ? command.mapped_error
+                                                  : uncompleted_error;
+                if (command.completed &&
+                    command.mapped_error == ErrorCode::OK) {
+                    attempt.returned_size = command.has_observed_result
+                                                ? command.observed_result
+                                                : 0;
+                }
+            }
+            if (!submit_result) {
+                return tl::make_unexpected(submit_result.error());
+            }
+            return {};
+        };
+
+        const auto finish_successful_attempt =
+            [&](RetrieveAttempt& attempt, uint32_t prefix_limit,
+                bool allow_retry,
+                std::vector<RetrieveAttempt>& retry_attempts) {
+                auto& request = requests[attempt.request_index];
+                if (attempt.error != ErrorCode::OK ||
+                    attempt.dma_buffer == nullptr) {
+                    request.result = tl::make_unexpected(attempt.error);
+                    return;
+                }
+
+                const uint32_t actual_size = ResolveNvmeKvRetrievedValueSize(
+                    attempt.dma_buffer.get(), attempt.returned_size,
+                    prefix_limit, request.size_hint);
+                if (actual_size != 0 && actual_size <= prefix_limit) {
+                    char* data = attempt.dma_buffer.get();
+                    std::shared_ptr<void> owner(attempt.dma_buffer.release(),
+                                                NvmeKvFreeDeleter());
+                    request.result = RetrievedBuffer{
+                        .owner = std::move(owner),
+                        .data = data,
+                        .size = actual_size,
+                    };
+                    return;
+                }
+
+                uint32_t required_size = attempt.returned_size;
+                if (required_size <= prefix_limit) {
+                    required_size = ResolveNvmeKvObjectBlobSizeFromPrefix(
+                        attempt.dma_buffer.get(), prefix_limit);
+                }
+                if (allow_retry && required_size > prefix_limit &&
+                    required_size <= capabilities_.effective_max_value_size) {
+                    retry_attempts.push_back(
+                        make_attempt(attempt.request_index, required_size));
+                    return;
+                }
+                request.result = tl::make_unexpected(
+                    required_size > capabilities_.effective_max_value_size
+                        ? ErrorCode::BUFFER_OVERFLOW
+                        : ErrorCode::FILE_READ_FAIL);
+            };
+
+        std::vector<RetrieveAttempt> initial_attempts;
+        initial_attempts.reserve(requests.size());
+        std::vector<uint32_t> initial_request_bytes(requests.size(), 0);
+        for (size_t index = 0; index < requests.size(); ++index) {
+            const uint32_t request_bytes = ResolveNvmeKvInitialRetrieveBytes(
+                requests[index].size_hint,
+                capabilities_.effective_max_value_size);
+            initial_request_bytes[index] = request_bytes;
+            initial_attempts.push_back(make_attempt(index, request_bytes));
+        }
+
+        (void)submit_attempts(initial_attempts);
+
+        std::vector<RetrieveAttempt> fallback_attempts;
+        std::vector<RetrieveAttempt> retry_attempts;
+        for (auto& attempt : initial_attempts) {
+            const auto& request = requests[attempt.request_index];
+            const uint32_t initial_bytes =
+                initial_request_bytes[attempt.request_index];
+            if (attempt.error != ErrorCode::OK) {
+                if (ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+                        attempt.error, request.size_hint, initial_bytes,
+                        capabilities_.effective_max_value_size)) {
+                    fallback_attempts.push_back(
+                        make_attempt(attempt.request_index,
+                                     capabilities_.effective_max_value_size));
+                } else {
+                    requests[attempt.request_index].result =
+                        tl::make_unexpected(attempt.error);
+                }
+                continue;
+            }
+            finish_successful_attempt(attempt, initial_bytes, true,
+                                      retry_attempts);
+        }
+
+        if (!fallback_attempts.empty()) {
+            (void)submit_attempts(fallback_attempts);
+            for (auto& attempt : fallback_attempts) {
+                finish_successful_attempt(
+                    attempt, capabilities_.effective_max_value_size, false,
+                    retry_attempts);
+            }
+        }
+
+        if (!retry_attempts.empty()) {
+            (void)submit_attempts(retry_attempts);
+            std::vector<RetrieveAttempt> ignored_retries;
+            for (auto& attempt : retry_attempts) {
+                finish_successful_attempt(attempt, attempt.request_bytes, false,
+                                          ignored_retries);
+            }
+        }
+    }
+
+    void RetrieveIntoBatch(
+        std::vector<RetrieveIntoRequest>& requests) const override {
+        std::vector<SharedNvmeUringRing::BatchCommand> commands;
+        commands.reserve(requests.size());
+        for (size_t index = 0; index < requests.size(); ++index) {
+            auto& request = requests[index];
+            const uint32_t transfer_bytes =
+                RoundUpToNvmeKvTransferBytes(request.size);
+            const auto address = reinterpret_cast<uintptr_t>(request.data);
+            if (request.data == nullptr || request.size == 0 ||
+                transfer_bytes != request.size ||
+                transfer_bytes > capabilities_.effective_max_value_size ||
+                address % NvmeKvTransferAlignmentBytes() != 0) {
+                request.result = tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+                continue;
+            }
+
+            SharedNvmeUringRing::BatchCommand command;
+            command.is_write = false;
+            command.context_index = index;
+            BuildNvmeKvRetrieveCommand(command.cmd, nsid_, request.key,
+                                       request.data, transfer_bytes);
+            commands.push_back(std::move(command));
+        }
+
+        auto submit_result = CurrentThreadRing().SubmitBatch(fd_, commands);
+        for (const auto& command : commands) {
+            auto& request = requests[command.context_index];
+            if (!command.completed) {
+                request.result = tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+                continue;
+            }
+            if (command.mapped_error != ErrorCode::OK) {
+                request.result = tl::make_unexpected(command.mapped_error);
+                continue;
+            }
+            const uint32_t actual_size = command.has_observed_result
+                                             ? command.observed_result
+                                             : request.size;
+            if (actual_size != request.size) {
+                request.result = tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                continue;
+            }
+            request.result = actual_size;
+        }
+        if (!submit_result) {
+            for (auto& request : requests) {
+                if (!request.result &&
+                    request.result.error() == ErrorCode::INTERNAL_ERROR) {
+                    request.result = tl::make_unexpected(submit_result.error());
+                }
+            }
+        }
+    }
+
+    tl::expected<void, ErrorCode> Delete(const PhysicalKey& key) override {
+        SharedNvmeUringRing::BatchCommand command;
+        command.is_write = true;
+        BuildNvmeKvDeleteCommand(command.cmd, nsid_, key);
+        std::vector<SharedNvmeUringRing::BatchCommand> commands;
+        commands.push_back(std::move(command));
+        auto submit_result = CurrentThreadRing().SubmitBatch(fd_, commands);
+        const auto& completed = commands.front();
+        if (!completed.completed) {
+            return tl::make_unexpected(submit_result ? ErrorCode::INTERNAL_ERROR
+                                                     : submit_result.error());
+        }
+        if (completed.mapped_error != ErrorCode::OK) {
+            return tl::make_unexpected(completed.mapped_error);
+        }
+        return {};
+    }
+
+    const Capabilities& GetCapabilities() const override {
+        return capabilities_;
+    }
+
+   private:
+    SharedNvmeUringRing& CurrentThreadRing() const {
+        return SharedNvmeUringRing::Instance(capabilities_.queue_depth);
+    }
+
+    std::string device_path_;
+    uint32_t nsid_ = 1;
+    Capabilities capabilities_;
+    int fd_ = -1;
+};
+
+}  // namespace
+
+NvmeKvExecutorResult CreateNvmeKvIoUringExecutor(
+    std::string device_path, uint32_t nsid, uint32_t queue_depth,
+    uint32_t runtime_transfer_limit) {
+    auto caps = BuildNvmeKvCapabilities(kDefaultNvmeKvQueueDepth, queue_depth,
+                                        runtime_transfer_limit);
+
+    auto executor = std::make_unique<NvmeKvIoUringExecutor>(
+        std::move(device_path), nsid, caps);
+    auto init_res = executor->Init();
+    if (!init_res) {
+        return tl::make_unexpected(init_res.error());
+    }
+    return std::unique_ptr<NvmeKvCommandExecutor>(std::move(executor));
+}
+
+}  // namespace mooncake
+
+#else
+
+namespace mooncake {
+
+NvmeKvExecutorResult CreateNvmeKvIoUringExecutor(
+    std::string /*device_path*/, uint32_t /*nsid*/, uint32_t /*queue_depth*/,
+    uint32_t /*runtime_transfer_limit*/) {
+    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+}
+
+}  // namespace mooncake
+
+#endif  // MOONCAKE_HAVE_NVME_URING_CMD
diff --git a/mooncake-store/src/nvme_kv/executor_ioctl.cpp b/mooncake-store/src/nvme_kv/executor_ioctl.cpp
new file mode 100644
index 0000000000..111d6a6154
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/executor_ioctl.cpp
@@ -0,0 +1,230 @@
+#include "nvme_kv/executor.h"
+#include "nvme_kv/executor_util.h"
+#include "nvme_kv/object_layout.h"
+
+#include <fcntl.h>
+#include <linux/nvme_ioctl.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <cerrno>
+#include <cstdint>
+#include <cstring>
+#include <string>
+#include <utility>
+
+#include <glog/logging.h>
+
+namespace mooncake {
+namespace {
+
+class NvmeKvIoctlExecutor : public NvmeKvCommandExecutor {
+   public:
+    NvmeKvIoctlExecutor(std::string device_path, uint32_t nsid,
+                        Capabilities capabilities)
+        : device_path_(std::move(device_path)),
+          nsid_(nsid),
+          capabilities_(capabilities) {}
+
+    tl::expected<void, ErrorCode> Init() {
+        fd_ = ::open(device_path_.c_str(), O_RDWR | O_CLOEXEC);
+        if (fd_ < 0) {
+            LOG(ERROR) << "[NvmeKvIoctlExecutor] open failed for "
+                       << device_path_ << ": " << strerror(errno);
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+        return {};
+    }
+
+    ~NvmeKvIoctlExecutor() override {
+        if (fd_ >= 0) {
+            ::close(fd_);
+        }
+    }
+
+    tl::expected<void, ErrorCode> Store(const PhysicalKey &key,
+                                        std::string value) override {
+        if (value.size() > capabilities_.effective_max_value_size) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+
+        const uint32_t value_size = static_cast<uint32_t>(value.size());
+        const uint32_t submission_bytes =
+            ResolveNvmeKvStoreSubmissionBytes(value_size);
+        if (submission_bytes > capabilities_.effective_max_value_size) {
+            LOG(WARNING) << "[NvmeKvIoctlExecutor] store submission exceeds "
+                            "effective_max_value_size"
+                         << " logical_bytes=" << value_size
+                         << " submission_bytes=" << submission_bytes
+                         << " effective_max_value_size="
+                         << capabilities_.effective_max_value_size;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        auto dma_buffer = AllocateNvmeKvAlignedBuffer(submission_bytes);
+        if (dma_buffer == nullptr) {
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        std::memset(dma_buffer.get(), 0, submission_bytes);
+        std::memcpy(dma_buffer.get(), value.data(), value.size());
+
+        nvme_passthru_cmd cmd{};
+        BuildNvmeKvStoreCommand(cmd, nsid_, key, dma_buffer.get(),
+                                submission_bytes);
+
+        auto result = Submit(cmd, true, "store-if-not-exists");
+        if (!result) {
+            return tl::make_unexpected(result.error());
+        }
+        return {};
+    }
+
+    tl::expected<std::string, ErrorCode> Retrieve(
+        const PhysicalKey &key, uint32_t size_hint = 0) const override {
+        const auto submit_retrieve = [&](uint32_t request_bytes,
+                                         const char *op_name)
+            -> tl::expected<std::pair<NvmeKvAlignedBuffer, uint32_t>,
+                            ErrorCode> {
+            const uint32_t transfer_bytes =
+                RoundUpToNvmeKvTransferBytes(request_bytes);
+            auto dma_buffer = AllocateNvmeKvAlignedBuffer(transfer_bytes);
+            if (dma_buffer == nullptr) {
+                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+            nvme_passthru_cmd cmd{};
+            BuildNvmeKvRetrieveCommand(cmd, nsid_, key, dma_buffer.get(),
+                                       transfer_bytes);
+
+            auto result = Submit(cmd, false, op_name);
+            if (!result) {
+                return tl::make_unexpected(result.error());
+            }
+            return std::make_pair(std::move(dma_buffer), result.value());
+        };
+
+        const uint32_t initial_request_bytes =
+            ResolveNvmeKvInitialRetrieveBytes(
+                size_hint, capabilities_.effective_max_value_size);
+        auto retrieve_res = submit_retrieve(initial_request_bytes, "retrieve");
+        bool used_fallback_request = false;
+        if (!retrieve_res) {
+            if (!ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+                    retrieve_res.error(), size_hint, initial_request_bytes,
+                    capabilities_.effective_max_value_size)) {
+                return tl::make_unexpected(retrieve_res.error());
+            }
+            retrieve_res = submit_retrieve(
+                capabilities_.effective_max_value_size, "retrieve-fallback");
+            if (!retrieve_res) {
+                return tl::make_unexpected(retrieve_res.error());
+            }
+            used_fallback_request = true;
+        }
+
+        auto [dma_buffer, reported_size] = std::move(retrieve_res.value());
+        const uint32_t prefix_limit =
+            used_fallback_request ? capabilities_.effective_max_value_size
+                                  : initial_request_bytes;
+        const uint32_t actual_size = ResolveNvmeKvRetrievedValueSize(
+            dma_buffer.get(), reported_size, prefix_limit, size_hint);
+        if (actual_size != 0 && actual_size <= prefix_limit) {
+            return std::string(dma_buffer.get(),
+                               dma_buffer.get() + actual_size);
+        }
+
+        uint32_t required_size = reported_size;
+        if (required_size <= prefix_limit) {
+            required_size = ResolveNvmeKvObjectBlobSizeFromPrefix(
+                dma_buffer.get(), prefix_limit);
+        }
+        if (required_size > prefix_limit &&
+            required_size <= capabilities_.effective_max_value_size) {
+            auto retry_res = submit_retrieve(required_size, "retrieve-retry");
+            if (!retry_res) {
+                return tl::make_unexpected(retry_res.error());
+            }
+            auto [retry_buffer, retry_reported_size] =
+                std::move(retry_res.value());
+            const uint32_t retry_actual_size = ResolveNvmeKvRetrievedValueSize(
+                retry_buffer.get(), retry_reported_size, required_size,
+                size_hint);
+            if (retry_actual_size != 0 && retry_actual_size <= required_size) {
+                return std::string(retry_buffer.get(),
+                                   retry_buffer.get() + retry_actual_size);
+            }
+        }
+
+        return tl::make_unexpected(
+            required_size > capabilities_.effective_max_value_size
+                ? ErrorCode::BUFFER_OVERFLOW
+                : ErrorCode::FILE_READ_FAIL);
+    }
+
+    tl::expected<void, ErrorCode> Delete(const PhysicalKey &key) override {
+        nvme_passthru_cmd cmd{};
+        BuildNvmeKvDeleteCommand(cmd, nsid_, key);
+
+        auto result = Submit(cmd, true, "delete");
+        if (!result) {
+            return tl::make_unexpected(result.error());
+        }
+        return {};
+    }
+
+    const Capabilities &GetCapabilities() const override {
+        return capabilities_;
+    }
+
+   private:
+    tl::expected<uint32_t, ErrorCode> Submit(nvme_passthru_cmd &cmd,
+                                             bool is_write,
+                                             const char *op_name) const {
+        errno = 0;
+        const int ret = ::ioctl(fd_, NVME_IOCTL_IO_CMD, &cmd);
+        const int err = errno;
+        if (ret < 0) {
+            const ErrorCode mapped = MapNvmeKvTransportError(err, is_write);
+            LOG(ERROR) << "[NvmeKvIoctlExecutor] ioctl failed"
+                       << " op=" << op_name << " device=" << device_path_
+                       << " errno=" << err << " strerror=" << strerror(err)
+                       << " mapped_error=" << toString(mapped);
+            return tl::make_unexpected(mapped);
+        }
+        if (ret > 0) {
+            const ErrorCode mapped =
+                MapNvmeKvStatus(static_cast<uint32_t>(ret), is_write);
+            if (!IsNvmeKvControlFlowError(mapped)) {
+                LOG(ERROR) << "[NvmeKvIoctlExecutor] ioctl returned NVMe status"
+                           << " op=" << op_name << " device=" << device_path_
+                           << " status=" << ret
+                           << " mapped_error=" << toString(mapped);
+            }
+            return tl::make_unexpected(mapped);
+        }
+        return static_cast<uint32_t>(cmd.result);
+    }
+
+    std::string device_path_;
+    uint32_t nsid_ = 1;
+    Capabilities capabilities_;
+    int fd_ = -1;
+};
+
+}  // namespace
+
+NvmeKvExecutorResult CreateNvmeKvIoctlExecutor(
+    std::string device_path, uint32_t nsid, uint32_t queue_depth,
+    uint32_t runtime_transfer_limit) {
+    auto caps = BuildNvmeKvCapabilities(kDefaultNvmeKvQueueDepth, queue_depth,
+                                        runtime_transfer_limit);
+
+    auto executor = std::make_unique<NvmeKvIoctlExecutor>(
+        std::move(device_path), nsid, caps);
+    auto init_res = executor->Init();
+    if (!init_res) {
+        return tl::make_unexpected(init_res.error());
+    }
+    return std::unique_ptr<NvmeKvCommandExecutor>(std::move(executor));
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/executor_stub.cpp b/mooncake-store/src/nvme_kv/executor_stub.cpp
new file mode 100644
index 0000000000..4830ea9a91
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/executor_stub.cpp
@@ -0,0 +1,124 @@
+#include "nvme_kv/executor.h"
+#include "nvme_kv/executor_util.h"
+
+#include <filesystem>
+#include <fstream>
+#include <system_error>
+#include <utility>
+
+#include "mutex.h"
+
+namespace mooncake {
+namespace {
+
+class NvmeKvStubExecutor : public NvmeKvCommandExecutor {
+   public:
+    explicit NvmeKvStubExecutor(std::filesystem::path storage_path)
+        : storage_path_(std::move(storage_path)),
+          capabilities_(BuildNvmeKvCapabilities(
+              1, ParseNvmeKvU32EnvOr("MOONCAKE_NVME_KV_QUEUE_DEPTH", 1),
+              ParseNvmeKvU32EnvOr("MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT",
+                                  128 * 1024))) {}
+
+    tl::expected<void, ErrorCode> Store(const PhysicalKey &key,
+                                        std::string value) override {
+        const auto blob_path = BlobPath(key);
+        {
+            SharedMutexLocker lock(&mutex_, shared_lock);
+            if (objects_.find(key) != objects_.end()) {
+                return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+            }
+        }
+        if (std::filesystem::exists(blob_path)) {
+            return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+        }
+        std::ofstream out(blob_path, std::ios::binary | std::ios::trunc);
+        if (!out) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        out.write(value.data(), static_cast<std::streamsize>(value.size()));
+        if (!out.good()) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        SharedMutexLocker lock(&mutex_);
+        objects_[key] = std::move(value);
+        return {};
+    }
+
+    tl::expected<std::string, ErrorCode> Retrieve(
+        const PhysicalKey &key, uint32_t /*size_hint*/ = 0) const override {
+        {
+            SharedMutexLocker lock(&mutex_, shared_lock);
+            auto it = objects_.find(key);
+            if (it != objects_.end()) {
+                return it->second;
+            }
+        }
+        const auto blob_path = BlobPath(key);
+        std::ifstream in(blob_path, std::ios::binary);
+        if (!in) {
+            return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+        }
+        std::string value((std::istreambuf_iterator<char>(in)),
+                          std::istreambuf_iterator<char>());
+        if (!in.good() && !in.eof()) {
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        {
+            SharedMutexLocker lock(&mutex_);
+            objects_[key] = value;
+        }
+        return value;
+    }
+
+    tl::expected<void, ErrorCode> Delete(const PhysicalKey &key) override {
+        const auto blob_path = BlobPath(key);
+        {
+            SharedMutexLocker lock(&mutex_);
+            objects_.erase(key);
+        }
+        std::error_code ec;
+        const bool removed = std::filesystem::remove(blob_path, ec);
+        if (ec) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        if (!removed) {
+            return tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+        }
+        return {};
+    }
+
+    const Capabilities &GetCapabilities() const override {
+        return capabilities_;
+    }
+
+   private:
+    struct PhysicalKeyHash {
+        size_t operator()(const PhysicalKey &key) const {
+            size_t seed = 0;
+            for (uint8_t b : key) {
+                seed = (seed * 131) ^ b;
+            }
+            return seed;
+        }
+    };
+
+    std::filesystem::path BlobPath(const PhysicalKey &key) const {
+        return storage_path_ / (NvmeKvPhysicalKeyToHex(key) + ".blob");
+    }
+
+    std::filesystem::path storage_path_;
+    mutable SharedMutex mutex_;
+    mutable std::unordered_map<PhysicalKey, std::string, PhysicalKeyHash>
+        objects_ GUARDED_BY(mutex_);
+    Capabilities capabilities_;
+};
+
+}  // namespace
+
+std::unique_ptr<NvmeKvCommandExecutor> CreateNvmeKvStubExecutor(
+    std::filesystem::path storage_path) {
+    return std::make_unique<NvmeKvStubExecutor>(std::move(storage_path));
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/executor_util.cpp b/mooncake-store/src/nvme_kv/executor_util.cpp
new file mode 100644
index 0000000000..8bc3a26852
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/executor_util.cpp
@@ -0,0 +1,211 @@
+#include "nvme_kv/executor_util.h"
+#include "nvme_kv/object_layout.h"
+
+#include <algorithm>
+#include <cstdlib>
+#include <iomanip>
+#include <limits>
+
+#include "config/u32_parser.h"
+
+namespace mooncake {
+namespace {
+
+constexpr uint32_t kNvmeStatusCodeMask = 0xFFu;
+constexpr char kNvmeKvTransferAlignmentEnv[] =
+    "MOONCAKE_NVME_KV_TRANSFER_ALIGNMENT_BYTES";
+constexpr uint32_t kNvmeKvStatusCapacityExceeded = 0x81;
+constexpr uint32_t kNvmeKvStatusInvalidValueSize = 0x85;
+constexpr uint32_t kNvmeKvStatusInvalidKeySize = 0x86;
+constexpr uint32_t kNvmeKvStatusKeyNotFound = 0x87;
+constexpr uint32_t kNvmeKvStatusUnrecoveredRead = 0x88;
+constexpr uint32_t kNvmeKvStatusKeyExists = 0x89;
+
+uint32_t ReadLe32(const uint8_t *p) {
+    return static_cast<uint32_t>(p[0]) | (static_cast<uint32_t>(p[1]) << 8) |
+           (static_cast<uint32_t>(p[2]) << 16) |
+           (static_cast<uint32_t>(p[3]) << 24);
+}
+
+}  // namespace
+
+uint32_t ParseNvmeKvU32EnvOr(const char *name, uint32_t fallback) {
+    const char *value = std::getenv(name);
+    if (value == nullptr) {
+        return fallback;
+    }
+    return TryParseNvmeKvU32(value).value_or(fallback);
+}
+
+NvmeKvAlignedBuffer AllocateNvmeKvAlignedBuffer(size_t size) {
+    void *ptr = nullptr;
+    const size_t alignment = std::max<size_t>(
+        kDefaultNvmeKvTransferAlignmentBytes, NvmeKvTransferAlignmentBytes());
+    if (posix_memalign(&ptr, alignment, size) != 0) {
+        return nullptr;
+    }
+    return NvmeKvAlignedBuffer(static_cast<char *>(ptr));
+}
+
+uint32_t RoundUpToNvmeKvTransferBytes(uint32_t bytes) {
+    if (bytes == 0) {
+        return 0;
+    }
+    const uint32_t alignment = NvmeKvTransferAlignmentBytes();
+    const uint64_t rounded =
+        ((static_cast<uint64_t>(bytes) + alignment - 1) / alignment) *
+        alignment;
+    if (rounded > std::numeric_limits<uint32_t>::max()) {
+        return std::numeric_limits<uint32_t>::max();
+    }
+    return static_cast<uint32_t>(rounded);
+}
+
+uint32_t RoundDownToNvmeKvTransferBytes(uint32_t bytes) {
+    const uint32_t alignment = NvmeKvTransferAlignmentBytes();
+    return (bytes / alignment) * alignment;
+}
+
+uint32_t NvmeKvTransferAlignmentBytes() {
+    const uint32_t configured = ParseNvmeKvU32EnvOr(
+        kNvmeKvTransferAlignmentEnv, kDefaultNvmeKvTransferAlignmentBytes);
+    return configured == 0 ? kDefaultNvmeKvTransferAlignmentBytes : configured;
+}
+
+uint32_t NvmeKvValueBlockUnitBytes() {
+    const uint32_t configured =
+        ParseNvmeKvU32EnvOr("MOONCAKE_NVME_KV_VALUE_BLOCK_UNIT_BYTES",
+                            kDefaultNvmeKvValueBlockUnitBytes);
+    return configured == 0 ? kDefaultNvmeKvValueBlockUnitBytes : configured;
+}
+
+uint32_t ResolveNvmeKvStoreSubmissionBytes(uint32_t logical_bytes) {
+    return RoundUpToNvmeKvTransferBytes(logical_bytes);
+}
+
+uint32_t ResolveNvmeKvInitialRetrieveBytes(uint32_t size_hint,
+                                           uint32_t effective_max_value_size) {
+    const uint32_t requested_bytes =
+        size_hint == 0 ? std::max<uint32_t>(sizeof(NvmeKvObjectHeader),
+                                            NvmeKvTransferAlignmentBytes())
+                       : size_hint;
+    return std::min(effective_max_value_size,
+                    RoundUpToNvmeKvTransferBytes(requested_bytes));
+}
+
+uint32_t ResolveNvmeKvRetrievedValueSize(const char *buffer,
+                                         uint32_t returned_size,
+                                         uint32_t max_size,
+                                         uint32_t size_hint) {
+    const uint32_t resolved_size =
+        ResolveNvmeKvObjectBlobSize(buffer, returned_size, max_size);
+    if (resolved_size != 0) {
+        return resolved_size;
+    }
+    if (returned_size == 0 && size_hint != 0 && size_hint <= max_size) {
+        return size_hint;
+    }
+    return 0;
+}
+
+bool ShouldRetryNvmeKvRetrieveWithMaxBuffer(ErrorCode error, uint32_t size_hint,
+                                            uint32_t request_bytes,
+                                            uint32_t effective_max_value_size) {
+    return error == ErrorCode::INVALID_PARAMS && size_hint == 0 &&
+           request_bytes < effective_max_value_size;
+}
+
+NvmeKvCommandExecutor::Capabilities BuildNvmeKvCapabilities(
+    uint32_t default_queue_depth, uint32_t queue_depth,
+    uint32_t runtime_transfer_limit) {
+    NvmeKvCommandExecutor::Capabilities caps;
+    const uint32_t protocol_max_value_size =
+        ParseNvmeKvU32EnvOr("MOONCAKE_NVME_KV_PROTOCOL_MAX_VALUE_SIZE",
+                            kDefaultNvmeKvProtocolMaxValueSize);
+    const uint32_t effective_runtime_limit =
+        runtime_transfer_limit == 0 ? kDefaultNvmeKvRuntimeTransferLimit
+                                    : runtime_transfer_limit;
+    caps.effective_max_value_size = RoundDownToNvmeKvTransferBytes(
+        std::min(protocol_max_value_size, effective_runtime_limit));
+    caps.queue_depth = queue_depth == 0 ? default_queue_depth : queue_depth;
+    return caps;
+}
+
+uint32_t ComputeNvmeKvValueBlockCountMinusOne(uint32_t bytes) {
+    if (bytes == 0) {
+        return 0;
+    }
+    const uint32_t rounded_bytes = RoundUpToNvmeKvTransferBytes(bytes);
+    const uint32_t block_unit = NvmeKvValueBlockUnitBytes();
+    const uint64_t block_count =
+        (static_cast<uint64_t>(rounded_bytes) + block_unit - 1) / block_unit;
+    return block_count == 0 ? 0 : block_count - 1;
+}
+
+NvmeKvPackedKeyFields PackNvmeKvPhysicalKey(
+    const NvmeKvCommandExecutor::PhysicalKey &key) {
+    NvmeKvPackedKeyFields fields;
+    fields.cdw2 = ReadLe32(key.data());
+    fields.cdw3 = ReadLe32(key.data() + 4);
+    fields.cdw14 = (static_cast<uint32_t>(kNvmeKvCommandSetIdentifier) << 24) |
+                   (ReadLe32(key.data() + 8) & 0x00FFFFFFu);
+    fields.cdw15 = ReadLe32(key.data() + 12);
+    return fields;
+}
+
+std::string NvmeKvPhysicalKeyToHex(
+    const NvmeKvCommandExecutor::PhysicalKey &key) {
+    std::ostringstream oss;
+    oss << std::hex << std::setfill('0');
+    for (uint8_t byte : key) {
+        oss << std::setw(2) << static_cast<int>(byte);
+    }
+    return oss.str();
+}
+
+ErrorCode MapNvmeKvStatus(uint32_t status, bool is_write) {
+    const uint32_t status_code = status & kNvmeStatusCodeMask;
+    switch (status_code) {
+        case kNvmeKvStatusCapacityExceeded:
+            return ErrorCode::KEYS_ULTRA_LIMIT;
+        case kNvmeKvStatusInvalidValueSize:
+        case kNvmeKvStatusInvalidKeySize:
+            return ErrorCode::INVALID_PARAMS;
+        case kNvmeKvStatusKeyNotFound:
+            return ErrorCode::OBJECT_NOT_FOUND;
+        case kNvmeKvStatusUnrecoveredRead:
+            return ErrorCode::FILE_READ_FAIL;
+        case kNvmeKvStatusKeyExists:
+            return ErrorCode::OBJECT_ALREADY_EXISTS;
+        default:
+            return is_write ? ErrorCode::FILE_WRITE_FAIL
+                            : ErrorCode::FILE_READ_FAIL;
+    }
+}
+
+ErrorCode MapNvmeKvTransportError(int err, bool is_write) {
+    switch (err) {
+        case ENOENT:
+            return ErrorCode::OBJECT_NOT_FOUND;
+        case ENOSPC:
+            return ErrorCode::KEYS_ULTRA_LIMIT;
+        case EINVAL:
+            return ErrorCode::INVALID_PARAMS;
+        case ENOMEM:
+            return ErrorCode::BUFFER_OVERFLOW;
+        default:
+            return MapNvmeKvStatus(static_cast<uint32_t>(err), is_write);
+    }
+}
+
+bool IsNvmeKvControlFlowError(ErrorCode error) {
+    switch (error) {
+        case ErrorCode::OBJECT_NOT_FOUND:
+        case ErrorCode::OBJECT_ALREADY_EXISTS:
+            return true;
+        default:
+            return false;
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/key_codec.cpp b/mooncake-store/src/nvme_kv/key_codec.cpp
new file mode 100644
index 0000000000..a634cf7fb4
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/key_codec.cpp
@@ -0,0 +1,105 @@
+#include "nvme_kv/key_codec.h"
+
+#include <cstring>
+
+#include <xxhash.h>
+
+namespace mooncake {
+namespace {
+
+constexpr uint8_t kIdentityEncodingVersion = 1;
+constexpr uint8_t kRootKeyRole = 1;
+constexpr uint8_t kChunkKeyRole = 2;
+
+void AppendU32(std::string& encoded, uint32_t value) {
+    const size_t offset = encoded.size();
+    encoded.resize(offset + sizeof(value));
+    std::memcpy(encoded.data() + offset, &value, sizeof(value));
+}
+
+bool ReadU32(std::string_view encoded, size_t& offset, uint32_t& value) {
+    if (offset + sizeof(value) > encoded.size()) {
+        return false;
+    }
+    std::memcpy(&value, encoded.data() + offset, sizeof(value));
+    offset += sizeof(value);
+    return true;
+}
+
+std::string BuildDerivationInput(const NvmeKvObjectIdentity& identity,
+                                 uint8_t role, uint32_t slot,
+                                 std::optional<uint32_t> chunk_index) {
+    std::string encoded = SerializeNvmeKvCanonicalIdentity(identity);
+    encoded.push_back(static_cast<char>(role));
+    AppendU32(encoded, slot);
+    encoded.push_back(chunk_index.has_value() ? 1 : 0);
+    if (chunk_index) {
+        AppendU32(encoded, *chunk_index);
+    }
+    return encoded;
+}
+
+NvmeKvPhysicalKey DerivePhysicalKey(std::string_view encoded) {
+    NvmeKvPhysicalKey physical_key{};
+    const uint64_t low = XXH64(encoded.data(), encoded.size(), 0);
+    const uint64_t high = XXH64(encoded.data(), encoded.size(), 1);
+    std::memcpy(physical_key.data(), &low, sizeof(low));
+    std::memcpy(physical_key.data() + sizeof(low), &high, sizeof(high));
+    return physical_key;
+}
+
+}  // namespace
+
+uint32_t ComputeNvmeKvChecksum(std::span<const uint8_t> data) {
+    return static_cast<uint32_t>(XXH32(data.data(), data.size(), 0));
+}
+
+std::string SerializeNvmeKvCanonicalIdentity(
+    const NvmeKvObjectIdentity& identity) {
+    std::string encoded(1, static_cast<char>(kIdentityEncodingVersion));
+    AppendU32(encoded, static_cast<uint32_t>(identity.logical_key.size()));
+    encoded.append(identity.logical_key);
+    return encoded;
+}
+
+bool ParseNvmeKvCanonicalIdentity(std::string_view encoded,
+                                  NvmeKvObjectIdentity& identity) {
+    identity = {};
+    if (encoded.empty() ||
+        static_cast<uint8_t>(encoded.front()) != kIdentityEncodingVersion) {
+        return false;
+    }
+    size_t offset = 1;
+    uint32_t key_size = 0;
+    if (!ReadU32(encoded, offset, key_size) ||
+        key_size != encoded.size() - offset) {
+        return false;
+    }
+    identity.logical_key = std::string(encoded.substr(offset));
+    return true;
+}
+
+std::array<uint8_t, 32> ComputeNvmeKvVerifyHash(
+    const NvmeKvObjectIdentity& identity) {
+    const std::string encoded = SerializeNvmeKvCanonicalIdentity(identity);
+    std::array<uint8_t, 32> hash{};
+    for (uint64_t seed = 0; seed < 4; ++seed) {
+        const uint64_t value = XXH64(encoded.data(), encoded.size(), seed);
+        std::memcpy(hash.data() + seed * sizeof(value), &value, sizeof(value));
+    }
+    return hash;
+}
+
+NvmeKvPhysicalKey EncodeNvmeKvPhysicalKey(const NvmeKvObjectIdentity& identity,
+                                          uint32_t slot) {
+    return DerivePhysicalKey(
+        BuildDerivationInput(identity, kRootKeyRole, slot, std::nullopt));
+}
+
+NvmeKvPhysicalKey EncodeNvmeKvChunkPhysicalKey(
+    const NvmeKvObjectIdentity& identity, uint32_t chunk_index, uint32_t slot) {
+    return DerivePhysicalKey(
+        BuildDerivationInput(identity, kChunkKeyRole, slot, chunk_index));
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/key_conflict_policy.cpp b/mooncake-store/src/nvme_kv/key_conflict_policy.cpp
new file mode 100644
index 0000000000..26143f197d
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/key_conflict_policy.cpp
@@ -0,0 +1,145 @@
+#include "nvme_kv/key_conflict_policy.h"
+
+#include <algorithm>
+#include <cstring>
+#include <limits>
+
+namespace mooncake {
+namespace {
+
+uint32_t PayloadLimitForIdentityMetadata(uint32_t max_value_size,
+                                         uint32_t identity_metadata_size) {
+    const uint64_t fixed_overhead =
+        static_cast<uint64_t>(sizeof(NvmeKvObjectHeader)) +
+        identity_metadata_size;
+    if (max_value_size <= fixed_overhead) {
+        return 0;
+    }
+    return static_cast<uint32_t>(max_value_size - fixed_overhead);
+}
+
+}  // namespace
+
+bool NvmeKvKeyConflictPolicy::ValidateResolvedRootPlacement(
+    const NvmeKvObjectIdentity& identity,
+    const NvmeKvStoredIdentityView& stored_view,
+    const NvmeKvPhysicalKey& observed_physical_key) {
+    return stored_view.resolved_physical_key == observed_physical_key &&
+           EncodeNvmeKvPhysicalKey(identity, stored_view.resolved_slot) ==
+               stored_view.resolved_physical_key;
+}
+
+tl::expected<NvmeKvKeyConflictPolicy::WritePlan, ErrorCode>
+NvmeKvKeyConflictPolicy::BuildWritePlan(const NvmeKvObjectIdentity& identity,
+                                        std::string_view payload, uint32_t slot,
+                                        uint32_t max_value_size) {
+    if (payload.size() >
+        static_cast<size_t>(std::numeric_limits<uint32_t>::max())) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    WritePlan plan;
+    plan.identity = identity;
+    plan.root_key = EncodeNvmeKvPhysicalKey(identity, slot);
+
+    const auto root_identity_metadata = SerializeNvmeKvStoredIdentity(
+        identity, BuildNvmeKvStoredIdentityMetadata(plan.root_key, slot));
+    const uint32_t inline_payload_limit = PayloadLimitForIdentityMetadata(
+        max_value_size, static_cast<uint32_t>(root_identity_metadata.size()));
+    plan.store_inline = payload.size() <= inline_payload_limit;
+
+    const auto verify_hash = ComputeNvmeKvVerifyHash(identity);
+    if (plan.store_inline) {
+        NvmeKvObjectHeader header{
+            .magic = NvmeKvObjectHeader::kMagic,
+            .object_type = static_cast<uint32_t>(NvmeKvObjectType::kInline),
+            .payload_size = static_cast<uint32_t>(payload.size()),
+            .verify_hash = verify_hash,
+            .payload_checksum = ComputeNvmeKvPayloadChecksum(payload),
+            .header_checksum = 0,
+            .identity_metadata_size =
+                static_cast<uint32_t>(root_identity_metadata.size()),
+        };
+        header.header_checksum = ComputeNvmeKvHeaderChecksum(header);
+        plan.root_blob =
+            BuildNvmeKvObjectBlob(header, root_identity_metadata, payload);
+        return plan;
+    }
+
+    const uint32_t chunk_payload_limit = max_value_size;
+    if (chunk_payload_limit == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const size_t chunk_count =
+        (payload.size() + chunk_payload_limit - 1) / chunk_payload_limit;
+    if (chunk_count == 0 ||
+        chunk_count >
+            static_cast<size_t>(std::numeric_limits<uint32_t>::max())) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    plan.manifest_records.reserve(chunk_count);
+    plan.chunk_values.reserve(chunk_count);
+    for (size_t chunk_index = 0; chunk_index < chunk_count; ++chunk_index) {
+        const size_t offset = chunk_index * chunk_payload_limit;
+        const size_t chunk_size = std::min(
+            static_cast<size_t>(chunk_payload_limit), payload.size() - offset);
+        std::string_view chunk_payload(payload.data() + offset, chunk_size);
+        const auto chunk_key = EncodeNvmeKvChunkPhysicalKey(
+            identity, static_cast<uint32_t>(chunk_index), slot);
+        const uint32_t chunk_checksum =
+            ComputeNvmeKvPayloadChecksum(chunk_payload);
+        plan.chunk_values.emplace_back(chunk_key, chunk_payload);
+        plan.manifest_records.push_back(NvmeKvManifestChunkRecord{
+            chunk_key, static_cast<uint32_t>(chunk_size), chunk_checksum});
+    }
+
+    const NvmeKvManifestMetadata metadata{
+        .logical_payload_size = static_cast<uint32_t>(payload.size()),
+        .chunk_count = static_cast<uint32_t>(plan.manifest_records.size()),
+    };
+    const std::string manifest_payload =
+        SerializeNvmeKvManifest(metadata, plan.manifest_records);
+    if (manifest_payload.size() + sizeof(NvmeKvObjectHeader) +
+            root_identity_metadata.size() >
+        max_value_size) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    NvmeKvObjectHeader header{
+        .magic = NvmeKvObjectHeader::kMagic,
+        .object_type = static_cast<uint32_t>(NvmeKvObjectType::kManifest),
+        .payload_size = static_cast<uint32_t>(manifest_payload.size()),
+        .verify_hash = verify_hash,
+        .payload_checksum = ComputeNvmeKvPayloadChecksum(manifest_payload),
+        .header_checksum = 0,
+        .identity_metadata_size =
+            static_cast<uint32_t>(root_identity_metadata.size()),
+    };
+    header.header_checksum = ComputeNvmeKvHeaderChecksum(header);
+    plan.root_blob =
+        BuildNvmeKvObjectBlob(header, root_identity_metadata, manifest_payload);
+    return plan;
+}
+
+tl::expected<NvmeKvKeyConflictPolicy::ExistingObjectDecision, ErrorCode>
+NvmeKvKeyConflictPolicy::ResolveExistingObject(NvmeKvConnector& connector,
+                                               const PhysicalKey& physical_key,
+                                               std::string_view expected_blob) {
+    auto existing_value_res = connector.Retrieve(physical_key);
+    if (!existing_value_res) {
+        if (existing_value_res.error() == ErrorCode::OBJECT_NOT_FOUND) {
+            return ExistingObjectDecision::kNotFound;
+        }
+        return tl::make_unexpected(existing_value_res.error());
+    }
+    const auto& existing = existing_value_res.value();
+    if (existing.size() == expected_blob.size() &&
+        std::memcmp(existing.data(), expected_blob.data(),
+                    expected_blob.size()) == 0) {
+        return ExistingObjectDecision::kSameObject;
+    }
+    return ExistingObjectDecision::kDifferentObject;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/nvme_kv/object_layout.cpp b/mooncake-store/src/nvme_kv/object_layout.cpp
new file mode 100644
index 0000000000..a6cd598244
--- /dev/null
+++ b/mooncake-store/src/nvme_kv/object_layout.cpp
@@ -0,0 +1,204 @@
+#include "nvme_kv/object_layout.h"
+
+#include <cstring>
+
+namespace mooncake {
+namespace {
+
+uint32_t ResolveNvmeKvObjectBlobSizeFromHeader(const char* buffer,
+                                               uint32_t prefix_size,
+                                               bool enforce_prefix_limit) {
+    if (prefix_size < sizeof(NvmeKvObjectHeader)) {
+        return 0;
+    }
+
+    NvmeKvObjectHeader header{};
+    std::memcpy(&header, buffer, sizeof(header));
+    if (header.magic != NvmeKvObjectHeader::kMagic) {
+        return 0;
+    }
+
+    const uint64_t object_size = static_cast<uint64_t>(sizeof(header)) +
+                                 header.identity_metadata_size +
+                                 header.payload_size;
+    if (object_size > UINT32_MAX) {
+        return 0;
+    }
+    if (enforce_prefix_limit && object_size > prefix_size) {
+        return 0;
+    }
+    return static_cast<uint32_t>(object_size);
+}
+
+}  // namespace
+
+uint32_t ComputeNvmeKvPayloadChecksum(std::string_view payload) {
+    return ComputeNvmeKvChecksum(std::span<const uint8_t>(
+        reinterpret_cast<const uint8_t*>(payload.data()), payload.size()));
+}
+
+uint32_t ComputeNvmeKvHeaderChecksum(const NvmeKvObjectHeader& header) {
+    NvmeKvObjectHeader temp = header;
+    temp.header_checksum = 0;
+    return ComputeNvmeKvChecksum(std::span<const uint8_t>(
+        reinterpret_cast<const uint8_t*>(&temp), sizeof(temp)));
+}
+
+uint32_t ComputeNvmeKvStoredIdentityMetadataSize(
+    const NvmeKvObjectIdentity& identity) {
+    return static_cast<uint32_t>(
+        sizeof(NvmeKvStoredIdentityMetadata) +
+        SerializeNvmeKvCanonicalIdentity(identity).size());
+}
+
+NvmeKvStoredIdentityMetadata BuildNvmeKvStoredIdentityMetadata(
+    const NvmeKvPhysicalKey& physical_key, uint32_t slot) {
+    return NvmeKvStoredIdentityMetadata{
+        .resolved_physical_key = physical_key,
+        .resolved_slot = slot,
+    };
+}
+
+std::string SerializeNvmeKvStoredIdentity(
+    const NvmeKvObjectIdentity& identity,
+    const NvmeKvStoredIdentityMetadata& metadata) {
+    const std::string canonical_identity =
+        SerializeNvmeKvCanonicalIdentity(identity);
+    std::string encoded(reinterpret_cast<const char*>(&metadata),
+                        sizeof(metadata));
+    encoded.append(canonical_identity);
+    return encoded;
+}
+
+bool ParseNvmeKvStoredIdentity(std::string_view encoded_identity,
+                               NvmeKvStoredIdentityView& identity_view) {
+    identity_view = {};
+    if (encoded_identity.size() < sizeof(NvmeKvStoredIdentityMetadata)) {
+        return false;
+    }
+
+    NvmeKvStoredIdentityMetadata metadata{};
+    std::memcpy(&metadata, encoded_identity.data(), sizeof(metadata));
+    NvmeKvObjectIdentity identity{};
+    if (!ParseNvmeKvCanonicalIdentity(
+            encoded_identity.substr(sizeof(NvmeKvStoredIdentityMetadata)),
+            identity)) {
+        return false;
+    }
+
+    identity_view.logical_key = std::move(identity.logical_key);
+    identity_view.resolved_physical_key = metadata.resolved_physical_key;
+    identity_view.resolved_slot = metadata.resolved_slot;
+    return true;
+}
+
+bool ValidateNvmeKvHeader(const NvmeKvObjectHeader& header,
+                          const NvmeKvObjectIdentity& identity,
+                          uint32_t expected_identity_size,
+                          uint32_t expected_size,
+                          NvmeKvObjectType expected_type) {
+    if (header.magic != NvmeKvObjectHeader::kMagic) {
+        return false;
+    }
+    if (header.object_type != static_cast<uint32_t>(expected_type)) {
+        return false;
+    }
+    if (header.payload_size != expected_size) {
+        return false;
+    }
+    if (header.identity_metadata_size != expected_identity_size) {
+        return false;
+    }
+    if (header.header_checksum != ComputeNvmeKvHeaderChecksum(header)) {
+        return false;
+    }
+    if (header.verify_hash != ComputeNvmeKvVerifyHash(identity)) {
+        return false;
+    }
+    return true;
+}
+
+std::string BuildNvmeKvObjectBlob(const NvmeKvObjectHeader& header,
+                                  std::string_view identity_metadata,
+                                  std::string_view payload) {
+    std::string object_blob(reinterpret_cast<const char*>(&header),
+                            sizeof(header));
+    object_blob.append(identity_metadata);
+    object_blob.append(payload);
+    return object_blob;
+}
+
+bool ParseNvmeKvObjectBlob(std::string_view object_blob,
+                           NvmeKvObjectHeader& header,
+                           std::string_view& identity_metadata_view,
+                           std::string_view& payload_view) {
+    if (object_blob.size() < sizeof(NvmeKvObjectHeader)) {
+        return false;
+    }
+
+    std::memcpy(&header, object_blob.data(), sizeof(header));
+    if (header.magic != NvmeKvObjectHeader::kMagic) {
+        return false;
+    }
+    const size_t total_header_bytes =
+        sizeof(NvmeKvObjectHeader) + header.identity_metadata_size;
+    const size_t expected_size = total_header_bytes + header.payload_size;
+    if (object_blob.size() != expected_size) {
+        return false;
+    }
+    identity_metadata_view = object_blob.substr(sizeof(NvmeKvObjectHeader),
+                                                header.identity_metadata_size);
+    payload_view = object_blob.substr(total_header_bytes, header.payload_size);
+    return true;
+}
+
+uint32_t ResolveNvmeKvObjectBlobSizeFromPrefix(const char* buffer,
+                                               uint32_t prefix_size) {
+    return ResolveNvmeKvObjectBlobSizeFromHeader(buffer, prefix_size, false);
+}
+
+uint32_t ResolveNvmeKvObjectBlobSize(const char* buffer, uint32_t returned_size,
+                                     uint32_t max_size) {
+    const uint32_t header_size =
+        ResolveNvmeKvObjectBlobSizeFromHeader(buffer, max_size, true);
+    if (header_size != 0) {
+        return header_size;
+    }
+    if (returned_size > max_size) {
+        return 0;
+    }
+    return returned_size;
+}
+
+std::string SerializeNvmeKvManifest(
+    const NvmeKvManifestMetadata& metadata,
+    const std::vector<NvmeKvManifestChunkRecord>& chunk_records) {
+    std::string manifest(reinterpret_cast<const char*>(&metadata),
+                         sizeof(metadata));
+    for (const auto& record : chunk_records) {
+        manifest.append(reinterpret_cast<const char*>(&record), sizeof(record));
+    }
+    return manifest;
+}
+
+bool ParseNvmeKvManifest(
+    std::string_view manifest_payload, NvmeKvManifestMetadata& metadata,
+    std::vector<NvmeKvManifestChunkRecord>& chunk_records) {
+    if (manifest_payload.size() < sizeof(NvmeKvManifestMetadata)) {
+        return false;
+    }
+    std::memcpy(&metadata, manifest_payload.data(), sizeof(metadata));
+    const size_t records_bytes = manifest_payload.size() - sizeof(metadata);
+    if (records_bytes !=
+        metadata.chunk_count * sizeof(NvmeKvManifestChunkRecord)) {
+        return false;
+    }
+    chunk_records.resize(metadata.chunk_count);
+    if (!chunk_records.empty()) {
+        std::memcpy(chunk_records.data(),
+                    manifest_payload.data() + sizeof(metadata), records_bytes);
+    }
+    return true;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/offset_allocator.cpp b/mooncake-store/src/offset_allocator.cpp
index 17f2369e2e..a3cde866aa 100644
--- a/mooncake-store/src/offset_allocator.cpp
+++ b/mooncake-store/src/offset_allocator.cpp
@@ -6,9 +6,13 @@
 #include <cmath>
 #include <iomanip>
 #include <iostream>
+#include <limits>
+#include <stdexcept>
 
+#include <fmt/format.h>
+
+#include "common/byte_size.h"
 #include "mutex.h"
-#include "utils.h"
 
 #ifdef DEBUG
 #include <assert.h>
@@ -540,6 +544,279 @@ static uint64_t calculateMultiplier(size_t size) {
     return multiplier_bits;
 }
 
+tl::expected<void, std::string> OffsetAllocatorSnapshot::ValidateNodeCapacity(
+    uint32_t size, uint32_t current_capacity, uint32_t max_capacity,
+    uint32_t free_offset) {
+    if (size == 0 || current_capacity == 0 || current_capacity > max_capacity ||
+        max_capacity > kMaxNodes || free_offset > current_capacity) {
+        return tl::make_unexpected(fmt::format(
+            "invalid layout capacity fields: size={}, current_capacity={}, "
+            "max_capacity={}, free_offset={} (node limit={})",
+            size, current_capacity, max_capacity, free_offset, kMaxNodes));
+    }
+    return {};
+}
+
+tl::expected<void, std::string> OffsetAllocatorSnapshot::ValidateHeader()
+    const {
+    if (!layout) {
+        return tl::make_unexpected(std::string("layout is missing"));
+    }
+    if (capacity == 0 || capacity > std::numeric_limits<size_t>::max() ||
+        base > std::numeric_limits<uint64_t>::max() - capacity) {
+        return tl::make_unexpected(fmt::format(
+            "invalid allocator bounds: base={}, capacity={}", base, capacity));
+    }
+    // Every shift below, including usage accounting, is gated by this check.
+    const uint64_t expected_multiplier = calculateMultiplier(capacity);
+    if (multiplier_bits >= 64 || multiplier_bits != expected_multiplier) {
+        return tl::make_unexpected(fmt::format(
+            "invalid multiplier_bits: got {}, expected {} for capacity {}",
+            multiplier_bits, expected_multiplier, capacity));
+    }
+    if (layout->m_size != (capacity >> multiplier_bits)) {
+        return tl::make_unexpected(fmt::format(
+            "layout size {} does not match capacity {} with multiplier_bits {}",
+            layout->m_size, capacity, multiplier_bits));
+    }
+    if (auto valid =
+            ValidateNodeCapacity(layout->m_size, layout->m_current_capacity,
+                                 layout->m_max_capacity, layout->m_freeOffset);
+        !valid) {
+        return valid;
+    }
+    if (layout->m_nodes.size() != layout->m_current_capacity ||
+        layout->m_freeNodes.size() != layout->m_current_capacity) {
+        return tl::make_unexpected(fmt::format(
+            "layout storage does not match current_capacity {}: nodes={}, "
+            "free_nodes={}",
+            layout->m_current_capacity, layout->m_nodes.size(),
+            layout->m_freeNodes.size()));
+    }
+    return {};
+}
+
+tl::expected<OffsetAllocatorSnapshot::LayoutUsage, std::string>
+OffsetAllocatorSnapshot::ValidateUsedNodes(
+    std::vector<NodeState>& state) const {
+    LayoutUsage usage;
+    for (uint32_t i = 0; i < layout->m_current_capacity; ++i) {
+        const auto& node = layout->m_nodes[i];
+        if (!node.used) continue;
+        if (node.dataSize == 0 || node.dataSize > layout->m_size) {
+            return tl::make_unexpected(fmt::format(
+                "used node {} has invalid size {}", i, node.dataSize));
+        }
+        uint32_t min_units = node.dataSize;
+#ifndef OFFSET_ALLOCATOR_NOT_ROUND_UP
+        const uint32_t bin = SmallFloat::uintToFloatRoundDown(node.dataSize);
+        if (SmallFloat::floatToUint(bin) != node.dataSize) {
+            return tl::make_unexpected(
+                fmt::format("used node {} size {} is not a bin boundary", i,
+                            node.dataSize));
+        }
+        // allocate() rounds first to a unit and then up to a bin. A request
+        // landing in this bin must be greater than the preceding bin boundary.
+        min_units = SmallFloat::floatToUint(bin - 1) + 1;
+#endif
+        const uint64_t max_bytes = static_cast<uint64_t>(node.dataSize)
+                                   << multiplier_bits;
+        if (max_bytes > capacity - usage.max_used_bytes) {
+            return tl::make_unexpected(fmt::format(
+                "used node {} makes occupied bytes exceed capacity {}", i,
+                capacity));
+        }
+        usage.max_used_bytes += max_bytes;
+        usage.min_used_bytes +=
+            (static_cast<uint64_t>(min_units - 1) << multiplier_bits) + 1;
+        ++usage.used_nodes;
+        state[i] = NodeState::kUsed;
+    }
+    return usage;
+}
+
+tl::expected<uint32_t, std::string> OffsetAllocatorSnapshot::ValidateBins(
+    std::vector<NodeState>& state) const {
+    constexpr uint32_t kUnused = __Allocator::Node::unused;
+    uint8_t expected_used_bins[NUM_TOP_BINS] = {};
+    uint32_t expected_used_bins_top = 0;
+    uint32_t bin_nodes = 0;
+    uint32_t free_storage = 0;
+    // Classification rejects cycles, duplicate membership and used nodes in
+    // free bins; the previous link and size class must agree with each list.
+    for (uint32_t bin = 0; bin < NUM_LEAF_BINS; ++bin) {
+        uint32_t node_index = layout->m_binIndices[bin];
+        if (node_index == kUnused) continue;
+        const uint32_t top_bin = bin >> TOP_BINS_INDEX_SHIFT;
+        expected_used_bins[top_bin] |= uint8_t{1}
+                                       << (bin & LEAF_BINS_INDEX_MASK);
+        expected_used_bins_top |= uint32_t{1} << top_bin;
+        uint32_t previous = kUnused;
+        while (node_index != kUnused) {
+            if (node_index >= state.size() ||
+                state[node_index] != NodeState::kUnclassified) {
+                return tl::make_unexpected(fmt::format(
+                    "bin {} references out-of-range or already classified node "
+                    "{}",
+                    bin, node_index));
+            }
+            const auto& node = layout->m_nodes[node_index];
+            if (SmallFloat::uintToFloatRoundDown(node.dataSize) != bin ||
+                node.binListPrev != previous) {
+                return tl::make_unexpected(fmt::format(
+                    "bin {} node {} has inconsistent size class or previous "
+                    "link",
+                    bin, node_index));
+            }
+            if (free_storage >
+                std::numeric_limits<uint32_t>::max() - node.dataSize) {
+                return tl::make_unexpected(fmt::format(
+                    "bin {} node {} overflows free storage", bin, node_index));
+            }
+            state[node_index] = NodeState::kFree;
+            ++bin_nodes;
+            free_storage += node.dataSize;
+            previous = node_index;
+            node_index = node.binListNext;
+        }
+    }
+    if (layout->m_freeStorage != free_storage) {
+        return tl::make_unexpected(
+            fmt::format("free storage mismatch: got {}, expected {}",
+                        layout->m_freeStorage, free_storage));
+    }
+    if (layout->m_usedBinsTop != expected_used_bins_top) {
+        return tl::make_unexpected(std::string("top bin bitmap mismatch"));
+    }
+    for (uint32_t top = 0; top < NUM_TOP_BINS; ++top) {
+        if (layout->m_usedBins[top] != expected_used_bins[top]) {
+            return tl::make_unexpected(
+                fmt::format("leaf bin bitmap mismatch at top bin {}", top));
+        }
+    }
+    return bin_nodes;
+}
+
+tl::expected<void, std::string> OffsetAllocatorSnapshot::ValidateFreeStack(
+    std::vector<NodeState>& state, uint32_t live_nodes) const {
+    for (uint32_t i = layout->m_freeOffset; i < state.size(); ++i) {
+        const uint32_t node_index = layout->m_freeNodes[i];
+        if (node_index >= state.size() ||
+            state[node_index] != NodeState::kUnclassified) {
+            return tl::make_unexpected(fmt::format(
+                "free stack slot {} references out-of-range or already "
+                "classified node {}",
+                i, node_index));
+        }
+        state[node_index] = NodeState::kSpare;
+    }
+    if (layout->m_freeOffset != live_nodes) {
+        return tl::make_unexpected(
+            fmt::format("free stack offset mismatch: got {}, expected {}",
+                        layout->m_freeOffset, live_nodes));
+    }
+    for (uint32_t i = 0; i < state.size(); ++i) {
+        if (state[i] == NodeState::kUnclassified) {
+            return tl::make_unexpected(fmt::format(
+                "node {} is neither used, in a free bin, nor spare", i));
+        }
+    }
+    return {};
+}
+
+tl::expected<void, std::string> OffsetAllocatorSnapshot::ValidateNeighborChain(
+    const std::vector<NodeState>& state, uint32_t live_nodes) const {
+    constexpr uint32_t kUnused = __Allocator::Node::unused;
+    const auto is_live = [&state](uint32_t index) {
+        return index < state.size() && (state[index] == NodeState::kUsed ||
+                                        state[index] == NodeState::kFree);
+    };
+    uint32_t head = kUnused;
+    for (uint32_t i = 0; i < state.size(); ++i) {
+        if (!is_live(i) || layout->m_nodes[i].neighborPrev != kUnused) continue;
+        if (head != kUnused) {
+            return tl::make_unexpected(
+                std::string("neighbor chain has multiple heads"));
+        }
+        head = i;
+    }
+    if (head == kUnused) {
+        return tl::make_unexpected(std::string("neighbor chain has no head"));
+    }
+    std::vector<uint8_t> walked(state.size(), 0);
+    uint32_t chain_nodes = 0;
+    uint32_t offset = 0;
+    for (uint32_t i = head; i != kUnused; i = layout->m_nodes[i].neighborNext) {
+        if (!is_live(i) || walked[i]) {
+            return tl::make_unexpected(fmt::format(
+                "neighbor chain references invalid or repeated node {}", i));
+        }
+        walked[i] = 1;
+        const auto& node = layout->m_nodes[i];
+        if (node.dataOffset != offset || node.dataSize == 0 ||
+            node.dataSize > layout->m_size - offset) {
+            return tl::make_unexpected(fmt::format(
+                "neighbor node {} has invalid geometry: offset={}, size={}, "
+                "expected_offset={}",
+                i, node.dataOffset, node.dataSize, offset));
+        }
+        offset += node.dataSize;
+        ++chain_nodes;
+        if (node.neighborNext != kUnused &&
+            (!is_live(node.neighborNext) ||
+             layout->m_nodes[node.neighborNext].neighborPrev != i)) {
+            return tl::make_unexpected(fmt::format(
+                "neighbor node {} has an inconsistent next link", i));
+        }
+        if (node.neighborPrev != kUnused &&
+            (!is_live(node.neighborPrev) ||
+             layout->m_nodes[node.neighborPrev].neighborNext != i)) {
+            return tl::make_unexpected(fmt::format(
+                "neighbor node {} has an inconsistent previous link", i));
+        }
+    }
+    if (offset != layout->m_size || chain_nodes != live_nodes) {
+        return tl::make_unexpected(
+            fmt::format("neighbor chain does not cover the layout: "
+                        "bytes={}/{}, nodes={}/{}",
+                        offset, layout->m_size, chain_nodes, live_nodes));
+    }
+    return {};
+}
+
+tl::expected<void, std::string> OffsetAllocatorSnapshot::ValidateAccounting(
+    const LayoutUsage& usage) const {
+    if (allocated_num != usage.used_nodes) {
+        return tl::make_unexpected(
+            fmt::format("allocated_num mismatch: got {}, expected {}",
+                        allocated_num, usage.used_nodes));
+    }
+    if (allocated_size < usage.min_used_bytes ||
+        allocated_size > usage.max_used_bytes) {
+        return tl::make_unexpected(fmt::format(
+            "allocated_size {} is outside layout's requested-byte range [{}, "
+            "{}]",
+            allocated_size, usage.min_used_bytes, usage.max_used_bytes));
+    }
+    return {};
+}
+
+tl::expected<void, std::string> OffsetAllocatorSnapshot::Validate() const {
+    if (auto valid = ValidateHeader(); !valid) return valid;
+    std::vector<NodeState> state(layout->m_current_capacity,
+                                 NodeState::kUnclassified);
+    auto usage = ValidateUsedNodes(state);
+    if (!usage) return tl::make_unexpected(usage.error());
+    auto bin_nodes = ValidateBins(state);
+    if (!bin_nodes) return tl::make_unexpected(bin_nodes.error());
+    const uint32_t live_nodes =
+        static_cast<uint32_t>(usage->used_nodes) + *bin_nodes;
+    if (auto valid = ValidateFreeStack(state, live_nodes); !valid) return valid;
+    if (auto valid = ValidateNeighborChain(state, live_nodes); !valid)
+        return valid;
+    return ValidateAccounting(*usage);
+}
+
 // Thread-safe OffsetAllocator implementation
 std::shared_ptr<OffsetAllocator> OffsetAllocator::create(uint64_t base,
                                                          size_t size,
@@ -550,6 +827,29 @@ std::shared_ptr<OffsetAllocator> OffsetAllocator::create(uint64_t base,
         new OffsetAllocator(base, size, init_capacity, max_capacity));
 }
 
+OffsetAllocatorSnapshot OffsetAllocator::CaptureSnapshot() const {
+    // The snapshot owns its layout: it can outlive this allocator and must
+    // never observe later mutations, so the bin/node state is copied here.
+    // The copy constructor is private; OffsetAllocator is a friend.
+    std::unique_ptr<__Allocator> layout(new __Allocator(*m_allocator));
+    return {m_base,           m_multiplier_bits, m_capacity,
+            m_allocated_size, m_allocated_num,   std::move(layout)};
+}
+tl::expected<std::shared_ptr<OffsetAllocator>, std::string>
+OffsetAllocator::Restore(OffsetAllocatorSnapshot snapshot) {
+    if (auto valid = snapshot.Validate(); !valid) {
+        LOG(ERROR) << "OffsetAllocator::Restore rejected snapshot: "
+                   << valid.error();
+        return tl::make_unexpected(valid.error());
+    }
+    auto allocator = std::shared_ptr<OffsetAllocator>(new OffsetAllocator(
+        snapshot.base, snapshot.capacity, snapshot.multiplier_bits,
+        std::move(snapshot.layout)));
+    allocator->m_allocated_size = snapshot.allocated_size;
+    allocator->m_allocated_num = snapshot.allocated_num;
+    return allocator;
+}
+
 OffsetAllocator::OffsetAllocator(uint64_t base, size_t size,
                                  uint32 init_capacity, uint32 max_capacity)
     : m_base(base),
diff --git a/mooncake-store/src/placement/index.cpp b/mooncake-store/src/placement/index.cpp
new file mode 100644
index 0000000000..953c741639
--- /dev/null
+++ b/mooncake-store/src/placement/index.cpp
@@ -0,0 +1,213 @@
+#include "segment/catalog.h"
+#include "placement/index.h"
+
+#include <algorithm>
+#include <unordered_set>
+#include <memory_resource>
+#include <functional>
+#include <iterator>
+
+namespace mooncake {
+PlacementIndex::Entry* PlacementIndex::EntryMap::Find(std::string_view name) {
+    auto it = by_name_.find(name);
+    return it == by_name_.end() ? nullptr : it->second.get();
+}
+
+const PlacementIndex::Entry* PlacementIndex::EntryMap::Find(
+    std::string_view name) const {
+    auto it = by_name_.find(name);
+    return it == by_name_.end() ? nullptr : it->second.get();
+}
+
+void PlacementIndex::EntryMap::Insert(std::unique_ptr<Entry> entry) noexcept {
+    auto [it, inserted] =
+        by_name_.emplace(entry->segment_name, std::move(entry));
+    DCHECK(inserted);
+    active_.push_back(it->second.get());
+}
+
+void PlacementIndex::EntryMap::Erase(const Entry& entry) {
+    auto active_it = std::find(active_.begin(), active_.end(), &entry);
+    DCHECK(active_it != active_.end());
+    *active_it = active_.back();
+    active_.pop_back();
+    by_name_.erase(entry.segment_name);
+}
+
+void PlacementIndex::EntryMap::Clear() {
+    active_.clear();
+    by_name_.clear();
+}
+
+bool PlacementIndex::AddCandidate(std::string_view segment_name,
+                                  const AllocationCandidate& candidate,
+                                  std::string_view host_id) {
+    if (segment_name.empty()) {
+        return false;
+    }
+    const size_t kind_index = KindIndex(candidate.Kind());
+    if (kind_index >= kAllocationCandidateKindCount) {
+        return false;
+    }
+    auto& entries = entries_by_kind_[kind_index];
+    if (auto* entry = entries.Find(segment_name)) {
+        if (!entry->candidates.insert(&candidate).second) {
+            return false;
+        }
+        AddHostMember(host_id, segment_name);
+        return true;
+    }
+
+    auto entry = std::make_unique<Entry>(
+        Entry{std::string(segment_name), candidate.Kind(), {&candidate}});
+    entries.Insert(std::move(entry));
+    AddHostMember(host_id, segment_name);
+    return true;
+}
+
+bool PlacementIndex::RemoveCandidate(std::string_view segment_name,
+                                     const AllocationCandidate& candidate,
+                                     std::string_view host_id) {
+    const size_t kind_index = KindIndex(candidate.Kind());
+    if (kind_index >= kAllocationCandidateKindCount) {
+        return false;
+    }
+    auto& entries = entries_by_kind_[kind_index];
+    auto* entry = entries.Find(segment_name);
+    if (!entry) {
+        return false;
+    }
+    auto& candidates = entry->candidates;
+    if (candidates.erase(&candidate) == 0) {
+        return false;
+    }
+    RemoveHostMember(host_id, segment_name);
+    if (!candidates.empty()) {
+        return true;
+    }
+
+    entries.Erase(*entry);
+    return true;
+}
+
+bool PlacementIndex::ReplaceCandidate(std::string_view segment_name,
+                                      const AllocationCandidate& expected,
+                                      const AllocationCandidate& replacement,
+                                      std::string_view host_id) {
+    if (expected.Kind() != replacement.Kind()) {
+        if (!AddCandidate(segment_name, replacement, host_id)) {
+            return false;
+        }
+        if (RemoveCandidate(segment_name, expected, host_id)) {
+            return true;
+        }
+        (void)RemoveCandidate(segment_name, replacement, host_id);
+        return false;
+    }
+
+    const size_t kind_index = KindIndex(expected.Kind());
+    if (kind_index >= kAllocationCandidateKindCount) {
+        return false;
+    }
+    auto& entries = entries_by_kind_[kind_index];
+    auto* entry = entries.Find(segment_name);
+    if (!entry) {
+        return false;
+    }
+    auto& candidates = entry->candidates;
+    auto candidate_it = candidates.find(&expected);
+    if (candidate_it == candidates.end()) {
+        return false;
+    }
+    if (&expected == &replacement) {
+        return true;
+    }
+    if (candidates.find(&replacement) != candidates.end()) {
+        return false;
+    }
+    candidates.erase(candidate_it);
+    candidates.insert(&replacement);
+    return true;
+}
+
+void PlacementIndex::Clear() {
+    segments_by_host_.clear();
+    for (auto& entries : entries_by_kind_) {
+        entries.Clear();
+    }
+}
+
+const PlacementIndex::Entry* PlacementIndex::Find(
+    std::string_view segment_name, AllocationCandidateKind kind) const {
+    const size_t kind_index = KindIndex(kind);
+    if (kind_index >= kAllocationCandidateKindCount) {
+        return nullptr;
+    }
+    const auto& entries = entries_by_kind_[kind_index];
+    return entries.Find(segment_name);
+}
+
+void PlacementIndex::GetActiveSegmentNames(
+    AllocationCandidateKind kind, std::vector<std::string>& names) const {
+    names.clear();
+    const size_t kind_index = KindIndex(kind);
+    if (kind_index >= kAllocationCandidateKindCount) {
+        return;
+    }
+    const auto active_entries = entries_by_kind_[kind_index].ActiveEntries();
+    names.reserve(active_entries.size());
+    for (const auto* entry : active_entries) {
+        names.push_back(entry->segment_name);
+    }
+}
+
+void PlacementIndex::AddHostMember(std::string_view host_id,
+                                   std::string_view segment_name) {
+    if (!host_id.empty()) {
+        ++segments_by_host_[std::string(host_id)][std::string(segment_name)];
+    }
+}
+
+void PlacementIndex::RemoveHostMember(std::string_view host_id,
+                                      std::string_view segment_name) {
+    if (host_id.empty()) return;
+    auto host = segments_by_host_.find(host_id);
+    DCHECK(host != segments_by_host_.end());
+    auto name = host->second.find(segment_name);
+    DCHECK(name != host->second.end());
+    auto& member_count = name->second;
+    if (--member_count == 0) {
+        host->second.erase(name);
+        if (host->second.empty()) segments_by_host_.erase(host);
+    }
+}
+
+void PlacementIndex::VisitHostOrderedSegmentNames(
+    std::string_view writer_host_id, std::string_view key,
+    const std::function<bool(std::string_view)>& visit) const {
+    if (writer_host_id.empty() || segments_by_host_.empty()) return;
+    auto start = segments_by_host_.lower_bound(writer_host_id);
+    if (start == segments_by_host_.end()) start = segments_by_host_.begin();
+
+    const size_t key_hash = std::hash<std::string_view>{}(key);
+    // The same name can occur on multiple hosts. Batch per-visit dedup storage.
+    std::pmr::monotonic_buffer_resource scratch;
+    std::pmr::unordered_set<std::string_view> visited_names(&scratch);
+    auto host = start;
+    do {
+        const auto& names = host->second;
+        const size_t offset = key_hash % names.size();
+        for (size_t i = 0; i < names.size(); ++i) {
+            const auto& name = names.nth((offset + i) % names.size())->first;
+            if (visited_names.insert(name).second && visit(name)) return;
+        }
+        if (++host == segments_by_host_.end()) host = segments_by_host_.begin();
+    } while (host != start);
+}
+
+std::optional<UUID> ScopedPlacementReadAccess::GetOwnerClientId(
+    std::string_view segment_name) const {
+    return catalog_.FindOwnerClientId(segment_name);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/placement/replica_allocator.cpp b/mooncake-store/src/placement/replica_allocator.cpp
new file mode 100644
index 0000000000..1739eb4bf6
--- /dev/null
+++ b/mooncake-store/src/placement/replica_allocator.cpp
@@ -0,0 +1,448 @@
+#include "placement/replica_allocator.h"
+
+#include <algorithm>
+#include <unordered_set>
+
+#include "local_ssd/manager.h"
+#include "placement/index.h"
+#include "random.h"
+
+namespace mooncake {
+namespace {
+
+constexpr size_t kMaxRetryLimit = 100;
+constexpr size_t kCandidateMultiplier = 6;
+
+struct ScoredPlacementEntry final {
+    const PlacementIndex::Entry* entry;
+    double score;
+};
+
+class EntryList final {
+   public:
+    void Clear() {
+        entries_.clear();
+        members_.clear();
+    }
+
+    void Add(const PlacementIndex::Entry* entry) {
+        if (entry && members_.insert(entry).second) {
+            entries_.push_back(entry);
+        }
+    }
+
+    bool Contains(const PlacementIndex::Entry* entry) const {
+        return members_.contains(entry);
+    }
+
+    bool empty() const noexcept { return entries_.empty(); }
+    const PlacementIndex::Entry* front() const { return entries_.front(); }
+    auto begin() const noexcept { return entries_.begin(); }
+    auto end() const noexcept { return entries_.end(); }
+
+   private:
+    // Preserve preference order; the set is only for membership queries.
+    std::vector<const PlacementIndex::Entry*> entries_;
+    std::unordered_set<const PlacementIndex::Entry*> members_;
+};
+
+struct PlacementScratch final {
+    EntryList preferred;
+    std::unordered_set<const PlacementIndex::Entry*> excluded;
+    std::vector<const PlacementIndex::Entry*> used;
+    std::vector<ScoredPlacementEntry> candidates;
+
+    bool HasUsed(const PlacementIndex::Entry* entry) const {
+        return std::find(used.begin(), used.end(), entry) != used.end();
+    }
+
+    void Clear() {
+        preferred.Clear();
+        excluded.clear();
+        used.clear();
+        candidates.clear();
+    }
+};
+
+PlacementScratch& GetPlacementScratch() {
+    thread_local PlacementScratch scratch;
+    scratch.Clear();
+    return scratch;
+}
+
+std::unique_ptr<AllocatedBuffer> TryAllocateFromEntry(
+    const PlacementIndex::Entry* entry, size_t size) {
+    if (!entry || entry->candidates.empty()) {
+        return nullptr;
+    }
+    if (entry->candidates.size() == 1) {
+        return (*entry->candidates.begin())->Allocate(size);
+    }
+
+    size_t index = randomIndex(entry->candidates.size());
+    for (size_t i = 0; i < entry->candidates.size(); ++i) {
+        if (auto buffer = (*entry->candidates.nth(index))->Allocate(size))
+            [[likely]] {
+            return buffer;
+        }
+        if (++index == entry->candidates.size()) {
+            index = 0;
+        }
+    }
+    return nullptr;
+}
+
+double GetFreeRatio(const PlacementIndex::Entry& entry) {
+    uint64_t total_capacity = 0;
+    uint64_t total_free = 0;
+    for (const auto* target : entry.candidates) {
+        const uint64_t capacity = target->Capacity();
+        const uint64_t used = target->Used();
+        total_capacity += capacity;
+        total_free += capacity - std::min(capacity, used);
+    }
+    return total_capacity == 0 ? 0.0
+                               : static_cast<double>(total_free) /
+                                     static_cast<double>(total_capacity);
+}
+
+struct RandomRanker final {
+    static constexpr bool kRanked = false;
+};
+
+struct FreeRatioRanker final {
+    static constexpr bool kRanked = true;
+
+    double Score(const PlacementIndex::Entry* entry) const {
+        return GetFreeRatio(*entry);
+    }
+};
+
+struct SsdFreeRatioRanker final {
+    static constexpr bool kRanked = true;
+
+    const ScopedPlacementReadAccess& placement;
+    const LocalSSDMetricsView& metrics;
+
+    double Score(const PlacementIndex::Entry* entry) const {
+        auto owner = placement.GetOwnerClientId(entry->segment_name);
+        if (!owner) {
+            return 1.0;
+        }
+        return metrics.GetFreeRatio(*owner).value_or(1.0);
+    }
+};
+
+bool HasExplicitPreference(const PlacementConstraints& constraints) {
+    return !constraints.preferred_segment_name.empty() ||
+           !constraints.preferred_segment_names.empty();
+}
+
+void ResolveEntries(const PlacementIndex& index,
+                    const PlacementConstraints& constraints,
+                    AllocationCandidateKind target_kind,
+                    PlacementScratch& scratch) {
+    for (const auto& excluded : constraints.excluded_segment_names) {
+        if (const auto* entry = index.Find(excluded, target_kind)) {
+            scratch.excluded.insert(entry);
+        }
+    }
+
+    if (!constraints.preferred_segment_name.empty()) {
+        scratch.preferred.Add(
+            index.Find(constraints.preferred_segment_name, target_kind));
+    } else {
+        for (const auto& preferred : constraints.preferred_segment_names) {
+            scratch.preferred.Add(index.Find(preferred, target_kind));
+        }
+    }
+}
+
+tl::expected<std::vector<Replica>, ErrorCode> AllocatePreferredOnly(
+    const PlacementIndex& index, const ReplicaAllocationRequest& request,
+    AllocationCandidateKind required_kind, PlacementScratch& scratch) {
+    const auto& replicas = request.replicas;
+    if (replicas.size == 0 || replicas.count == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (!HasExplicitPreference(request.placement)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (index.active_entries(required_kind).empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+    if (scratch.preferred.empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    const auto* entry = scratch.preferred.front();
+    if (scratch.excluded.contains(entry)) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+    auto buffer = TryAllocateFromEntry(entry, replicas.size);
+    if (!buffer) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    std::vector<Replica> result;
+    result.reserve(1);
+    result.emplace_back(std::move(buffer), ReplicaStatus::PROCESSING,
+                        replicas.type);
+    return result;
+}
+
+bool TryAddReplica(const PlacementIndex::Entry* entry,
+                   const ReplicaRequirements& requirements,
+                   PlacementScratch& scratch, std::vector<Replica>& result) {
+    auto buffer = TryAllocateFromEntry(entry, requirements.size);
+    if (!buffer) {
+        return false;
+    }
+    result.emplace_back(std::move(buffer), ReplicaStatus::PROCESSING,
+                        requirements.type);
+    scratch.used.push_back(entry);
+    return true;
+}
+
+void AllocatePreferredEntries(const ReplicaRequirements& requirements,
+                              PlacementScratch& scratch,
+                              std::vector<Replica>& result) {
+    for (const auto* entry : scratch.preferred) {
+        if (scratch.excluded.contains(entry) || scratch.HasUsed(entry)) {
+            continue;
+        }
+        if (TryAddReplica(entry, requirements, scratch, result) &&
+            result.size() == requirements.count) {
+            return;
+        }
+    }
+}
+
+template <typename Ranker>
+void AllocateRankedEntries(
+    std::span<const PlacementIndex::Entry* const> active_entries,
+    const ReplicaRequirements& requirements, const Ranker& ranker,
+    PlacementScratch& scratch, std::vector<Replica>& result) {
+    const size_t remaining = requirements.count - result.size();
+    const size_t sample_count =
+        std::min(active_entries.size(), kCandidateMultiplier * remaining);
+    const size_t start = randomIndex(active_entries.size());
+    scratch.candidates.reserve(sample_count);
+    for (size_t i = 0; i < sample_count; ++i) {
+        const auto* entry = active_entries[(start + i) % active_entries.size()];
+        if (scratch.excluded.contains(entry) || scratch.HasUsed(entry)) {
+            continue;
+        }
+        scratch.candidates.push_back({entry, ranker.Score(entry)});
+    }
+    std::sort(
+        scratch.candidates.begin(), scratch.candidates.end(),
+        [](const ScoredPlacementEntry& lhs, const ScoredPlacementEntry& rhs) {
+            return lhs.score > rhs.score;
+        });
+    for (const auto& candidate : scratch.candidates) {
+        if (TryAddReplica(candidate.entry, requirements, scratch, result) &&
+            result.size() == requirements.count) {
+            return;
+        }
+    }
+}
+
+void AllocateFallbackEntries(
+    std::span<const PlacementIndex::Entry* const> active_entries,
+    const ReplicaRequirements& requirements, PlacementScratch& scratch,
+    std::vector<Replica>& result) {
+    size_t index_offset = randomIndex(active_entries.size());
+    const size_t max_retry = std::min(kMaxRetryLimit, active_entries.size());
+    for (size_t attempt = 0;
+         attempt < max_retry && result.size() < requirements.count;
+         ++attempt, ++index_offset) {
+        const auto* entry =
+            active_entries[index_offset % active_entries.size()];
+        if (scratch.excluded.contains(entry) || scratch.HasUsed(entry)) {
+            continue;
+        }
+        TryAddReplica(entry, requirements, scratch, result);
+    }
+}
+
+template <typename Ranker>
+tl::expected<std::vector<Replica>, ErrorCode> AllocateWithRanker(
+    ScopedPlacementReadAccess& placement,
+    const ReplicaAllocationRequest& request,
+    AllocationCandidateKind target_kind, PlacementScratch& scratch,
+    [[maybe_unused]] const Ranker& ranker, bool use_host_affinity) {
+    const auto& index = placement.GetView();
+    const auto& requirements = request.replicas;
+    if (requirements.size == 0 || requirements.count == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto active_entries = index.active_entries(target_kind);
+    if (active_entries.empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    std::vector<Replica> result;
+    result.reserve(std::min(requirements.count, active_entries.size()));
+
+    if (active_entries.size() == 1) {
+        const auto* entry = active_entries.front();
+        if (scratch.excluded.contains(entry) ||
+            !TryAddReplica(entry, requirements, scratch, result)) {
+            return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+        }
+        return result;
+    }
+
+    AllocatePreferredEntries(requirements, scratch, result);
+    if (result.size() == requirements.count) {
+        return result;
+    }
+
+    if (use_host_affinity && !request.host_affinity.writer_host_id.empty()) {
+        auto visit = [&](std::string_view name) {
+            const auto* entry = index.Find(name, target_kind);
+            if (!entry || scratch.preferred.Contains(entry) ||
+                scratch.excluded.contains(entry) || scratch.HasUsed(entry)) {
+                return false;
+            }
+            return TryAddReplica(entry, requirements, scratch, result) &&
+                   result.size() == requirements.count;
+        };
+        index.VisitHostOrderedSegmentNames(request.host_affinity.writer_host_id,
+                                           request.host_affinity.object_key,
+                                           std::ref(visit));
+        if (result.size() == requirements.count) return result;
+    }
+
+    if constexpr (Ranker::kRanked) {
+        AllocateRankedEntries(active_entries, requirements, ranker, scratch,
+                              result);
+        if (result.size() == requirements.count) {
+            return result;
+        }
+    }
+
+    AllocateFallbackEntries(active_entries, requirements, scratch, result);
+    if (result.empty()) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+    return result;
+}
+
+void UpdateDiagnostics(const PlacementIndex& index,
+                       const ReplicaAllocationRequest& request,
+                       AllocationCandidateKind target_kind,
+                       PlacementDiagnostics* diagnostics) {
+    if (diagnostics) {
+        diagnostics->has_sufficient_active_entry_count =
+            index.active_entries(target_kind).size() >= request.replicas.count;
+    }
+}
+
+template <typename Ranker>
+tl::expected<std::vector<Replica>, ErrorCode> AllocateUsingRanker(
+    ScopedPlacementReadAccess& placement,
+    const ReplicaAllocationRequest& request, PlacementDiagnostics* diagnostics,
+    const Ranker& ranker, bool use_host_affinity) {
+    constexpr auto kTargetKind = AllocationCandidateKind::NATIVE;
+    const auto& index = placement.GetView();
+    UpdateDiagnostics(index, request, kTargetKind, diagnostics);
+
+    auto& scratch = GetPlacementScratch();
+    ResolveEntries(index, request.placement, kTargetKind, scratch);
+    return AllocateWithRanker(placement, request, kTargetKind, scratch, ranker,
+                              use_host_affinity);
+}
+
+tl::expected<std::vector<Replica>, ErrorCode> AllocateUsingPreferences(
+    ScopedPlacementReadAccess& placement,
+    const ReplicaAllocationRequest& request, PlacementDiagnostics* diagnostics,
+    AllocationCandidateKind required_kind) {
+    const auto& index = placement.GetView();
+    UpdateDiagnostics(index, request, required_kind, diagnostics);
+
+    auto& scratch = GetPlacementScratch();
+    ResolveEntries(index, request.placement, required_kind, scratch);
+    return AllocatePreferredOnly(index, request, required_kind, scratch);
+}
+
+tl::expected<Replica, ErrorCode> AllocateFromNamedEntry(
+    ScopedPlacementReadAccess& placement, size_t size,
+    std::string_view segment_name, ReplicaType replica_type,
+    AllocationCandidateKind kind) {
+    if (size == 0 || segment_name.empty()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto* entry = placement.GetView().Find(segment_name, kind);
+    if (!entry) {
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    auto buffer = TryAllocateFromEntry(entry, size);
+    if (!buffer) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+    return Replica(std::move(buffer), ReplicaStatus::PROCESSING, replica_type);
+}
+
+}  // namespace
+
+std::optional<double> LocalSSDMetricsView::GetFreeRatio(
+    const UUID& client_id) const {
+    auto usage = local_ssd_.GetUsage(client_id);
+    if (!usage || usage->total_capacity_bytes <= 0) {
+        return std::nullopt;
+    }
+    const int64_t used =
+        std::clamp<int64_t>(usage->used_bytes, 0, usage->total_capacity_bytes);
+    return static_cast<double>(usage->total_capacity_bytes - used) /
+           static_cast<double>(usage->total_capacity_bytes);
+}
+
+template <ReplicaPlacementPolicy Policy>
+tl::expected<std::vector<Replica>, ErrorCode>
+ReplicaAllocator<Policy>::Allocate(ScopedPlacementReadAccess& placement,
+                                   const ReplicaAllocationRequest& request,
+                                   PlacementDiagnostics* diagnostics) const {
+    if constexpr (std::same_as<Policy, PreferredOnlyPlacementPolicy>) {
+        return AllocateUsingPreferences(placement, request, diagnostics,
+                                        policy_.required_kind);
+    } else if constexpr (std::same_as<Policy, FreeRatioFirstPlacementPolicy>) {
+        return AllocateUsingRanker(placement, request, diagnostics,
+                                   FreeRatioRanker{}, false);
+    } else if constexpr (std::same_as<Policy,
+                                      SsdFreeRatioFirstPlacementPolicy>) {
+        return AllocateUsingRanker(
+            placement, request, diagnostics,
+            SsdFreeRatioRanker{placement, policy_.metrics}, false);
+    } else {
+        constexpr bool kUseHostAffinity =
+            std::same_as<Policy, LocalFirstPlacementPolicy>;
+        return AllocateUsingRanker(placement, request, diagnostics,
+                                   RandomRanker{}, kUseHostAffinity);
+    }
+}
+
+template <ReplicaPlacementPolicy Policy>
+tl::expected<Replica, ErrorCode> ReplicaAllocator<Policy>::AllocateFrom(
+    ScopedPlacementReadAccess& placement, size_t size,
+    std::string_view segment_name, ReplicaType replica_type) const {
+    constexpr bool preferred_only =
+        std::same_as<Policy, PreferredOnlyPlacementPolicy>;
+    if constexpr (preferred_only) {
+        return AllocateFromNamedEntry(placement, size, segment_name,
+                                      replica_type, policy_.required_kind);
+    } else {
+        return AllocateFromNamedEntry(placement, size, segment_name,
+                                      replica_type,
+                                      AllocationCandidateKind::NATIVE);
+    }
+}
+
+template class ReplicaAllocator<RandomPlacementPolicy>;
+template class ReplicaAllocator<FreeRatioFirstPlacementPolicy>;
+template class ReplicaAllocator<SsdFreeRatioFirstPlacementPolicy>;
+template class ReplicaAllocator<LocalFirstPlacementPolicy>;
+template class ReplicaAllocator<PreferredOnlyPlacementPolicy>;
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/posix_file.cpp b/mooncake-store/src/posix_file.cpp
index 9f16b4fa0d..3d7c976d04 100644
--- a/mooncake-store/src/posix_file.cpp
+++ b/mooncake-store/src/posix_file.cpp
@@ -117,10 +117,16 @@ tl::expected<size_t, ErrorCode> PosixFile::vector_write(const iovec *iov,
         return make_error<size_t>(ErrorCode::FILE_NOT_FOUND);
     }
 
+    size_t expected_bytes = 0;
+    for (int i = 0; i < iovcnt; ++i) expected_bytes += iov[i].iov_len;
+
     ssize_t ret = ::pwritev(fd_, iov, iovcnt, offset);
     if (ret < 0) {
         return make_error<size_t>(ErrorCode::FILE_WRITE_FAIL);
     }
+    if (static_cast<size_t>(ret) != expected_bytes) {
+        return make_error<size_t>(ErrorCode::FILE_WRITE_FAIL);
+    }
 
     return ret;
 }
@@ -140,4 +146,4 @@ tl::expected<size_t, ErrorCode> PosixFile::vector_read(const iovec *iov,
     return ret;
 }
 
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-store/src/real_client.cpp b/mooncake-store/src/real_client.cpp
index 3f5eb35fbd..d685ee12ae 100644
--- a/mooncake-store/src/real_client.cpp
+++ b/mooncake-store/src/real_client.cpp
@@ -10,25 +10,34 @@
 
 #include <dlfcn.h>  // for dlsym (Python detection)
 #include <cstdlib>  // for atexit
+#include <cstring>
 #include <algorithm>
 #include <functional>
 #include <limits>
+#include <new>
 #include <optional>
 #include <vector>
 
 #include "real_client.h"
+#include "common/client_buffer_allocation.h"
+#include "common/mmap_aligned.h"
 #include "registered_pinned_memory.h"
 #include "client_buffer.h"
 #include "replica_selection.h"
+#include "batch_read_fanout.h"
 #include "common.h"
 #include "config.h"
+#include "config/rpc_protocol_config.h"
 #include "store_rpc_client_io_context.h"
 #include "bool_parser.h"
-#include "environ.h"
+#include "client_auto_port_config.h"
+#include "config/cxl_segment_config.h"
+#include "config/hugepage_config.h"
 #include "integer_parser.h"
 #include "mutex.h"
 #include "types.h"
-#include "utils.h"
+#include "common/network.h"
+#include "common/result.h"
 #include "rpc_types.h"
 #include "file_storage.h"
 #include "device/accelerator_registry.h"
@@ -37,6 +46,7 @@
 #include "device/cuda_ipc_buffer.h"
 #include "shm_helper.h"
 #include "memory_location.h"
+#include "version.h"
 #ifdef USE_NOF
 #include "spdk/spdk_wrapper.h"
 #endif
@@ -64,11 +74,68 @@ namespace mooncake {
 namespace {
 constexpr std::chrono::seconds kIpcRequestRecvTimeout{5};
 
+size_t DivideRoundUp(size_t value, size_t divisor) {
+    return value / divisor + (value % divisor != 0);
+}
+
+size_t GetNextSegmentSize(size_t remaining,
+                          const std::optional<size_t> &split_limit,
+                          size_t alignment) {
+    if (!split_limit.has_value()) return remaining;
+    const size_t aligned_limit = (*split_limit / alignment) * alignment;
+    if (aligned_limit == 0) return 0;
+    const size_t segment_count = DivideRoundUp(remaining, aligned_limit);
+    const size_t balanced_size = DivideRoundUp(remaining, segment_count);
+    return std::min(remaining,
+                    DivideRoundUp(balanced_size, alignment) * alignment);
+}
+
 bool IsHostStoreSegmentProtocol(const std::string &protocol) {
     return protocol.empty() || protocol == "tcp" || protocol == "rdma" ||
            protocol == "efa" || protocol == "cxi" || protocol == "rpc_only";
 }
 
+#ifdef USE_ASCEND_DIRECT
+// Split standalone store capacity across NPUs: cap each mount at total/n.
+size_t AgentModeStoreChunkCap(size_t total_size) {
+    const uint32_t n = ContextManager::getInstance().getDeviceCount();
+    if (n <= 1 || total_size == 0) {
+        return 0;
+    }
+    return total_size / n;
+}
+
+bool RestoreAgentModeDeviceZero() {
+    if (!ContextManager::getInstance().setCurrentContext(0)) {
+        LOG(ERROR) << "Failed to restore current context for device 0";
+        return false;
+    }
+    return true;
+}
+
+void *AllocateAscendStoreSegment(size_t segment_size,
+                                 const std::string &protocol, bool use_hugepage,
+                                 bool defer_hugetlb, size_t *mapped_size) {
+    size_t actual_size = 0;
+    AscendHostAllocFn host_alloc = nullptr;
+    size_t host_align = 0;
+    size_t alloc_size = segment_size;
+    if (use_hugepage && !globalConfig().ascend_use_fabric_mem) {
+        host_align = get_hugepage_size_from_env();
+        alloc_size = align_up(segment_size, host_align);
+        host_alloc =
+            static_cast<AscendHostAllocFn>(allocate_buffer_mmap_memory);
+    }
+    void *ptr = ascend_allocate_memory_best_effort(alloc_size, protocol,
+                                                   &actual_size, host_alloc,
+                                                   host_align, defer_hugetlb);
+    if (ptr != nullptr) {
+        *mapped_size = actual_size;
+    }
+    return ptr;
+}
+#endif
+
 std::shared_ptr<RegisteredPinnedRegion> TryPinStoreSegment(
     void *ptr, size_t size, const std::string &protocol,
     const char *segment_owner) {
@@ -104,6 +171,116 @@ bool ReleasePinnedRegionsForFree(
     return safe_to_free;
 }
 
+template <typename T>
+std::vector<int> ToPyResults(
+    const std::vector<tl::expected<T, ErrorCode>> &results) {
+    std::vector<int> converted;
+    converted.reserve(results.size());
+    for (const auto &result : results) converted.push_back(to_py_ret(result));
+    return converted;
+}
+
+tl::expected<std::vector<std::vector<Slice>>, ErrorCode>
+BuildNestedSlicesFromBuffers(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes) {
+    if (keys.size() != all_buffers.size() ||
+        all_buffers.size() != all_sizes.size()) {
+        LOG(ERROR) << "Mismatched sizes for keys, buffers, and sizes";
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    std::vector<std::vector<Slice>> batched_slices(keys.size());
+    for (size_t i = 0; i < all_buffers.size(); ++i) {
+        const auto &buffers = all_buffers[i];
+        const auto &sizes = all_sizes[i];
+        if (buffers.size() != sizes.size()) {
+            LOG(ERROR) << "Mismatched buffers and sizes of key:" << keys[i];
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        batched_slices[i].reserve(buffers.size());
+        for (size_t j = 0; j < buffers.size(); ++j) {
+            batched_slices[i].emplace_back(Slice{buffers[j], sizes[j]});
+        }
+    }
+    return batched_slices;
+}
+
+tl::expected<std::vector<Slice>, ErrorCode> StageWriteSlices(
+    const std::shared_ptr<ClientBufferAllocator> &allocator,
+    const std::vector<Slice> &slices,
+    std::vector<BufferHandle> &staging_handles) {
+    if (!allocator) {
+        LOG(ERROR) << "Client buffer allocator is not provided";
+        return tl::unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    size_t total_size = 0;
+    for (const auto &slice : slices) {
+        if (slice.size > std::numeric_limits<size_t>::max() - total_size) {
+            return tl::unexpected(ErrorCode::BUFFER_OVERFLOW);
+        }
+        total_size += slice.size;
+    }
+    auto allocation = allocator->allocate(total_size);
+    if (!allocation) {
+        return tl::unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    auto runtime_accelerator =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
+    char *destination = static_cast<char *>(allocation->ptr());
+    std::vector<Slice> staged_slices;
+    staged_slices.reserve(slices.size());
+    size_t offset = 0;
+    for (const auto &slice : slices) {
+        if (!runtime_accelerator.CopyToHost(destination + offset, slice.ptr,
+                                            slice.size)) {
+            LOG(ERROR) << "Failed to stage non-local write buffer";
+            return tl::unexpected(ErrorCode::TRANSFER_FAIL);
+        }
+        staged_slices.emplace_back(destination + offset, slice.size);
+        offset += slice.size;
+    }
+    staging_handles.emplace_back(std::move(*allocation));
+    return staged_slices;
+}
+
+using BatchWriteMethod = std::vector<tl::expected<void, ErrorCode>> (Client::*)(
+    const std::vector<ObjectKey> &, std::vector<std::vector<Slice>> &,
+    const ReplicateConfig &, const Client::WriteBufferStager &);
+
+std::vector<tl::expected<void, ErrorCode>> BatchWriteFromMultiBuffers(
+    const std::shared_ptr<Client> &client, const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const ReplicateConfig &config,
+    const std::shared_ptr<ClientBufferAllocator> &allocator,
+    bool stage_nonlocal, BatchWriteMethod write) {
+    if (!client) {
+        LOG(ERROR) << "Client is not initialized";
+        return std::vector<tl::expected<void, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    }
+    auto batched_slices =
+        BuildNestedSlicesFromBuffers(keys, all_buffers, all_sizes);
+    if (!batched_slices) {
+        return std::vector<tl::expected<void, ErrorCode>>(
+            keys.size(), tl::unexpected(batched_slices.error()));
+    }
+
+    std::vector<BufferHandle> staging_handles;
+    staging_handles.reserve(stage_nonlocal ? keys.size() : 0);
+    Client::WriteBufferStager stager;
+    if (stage_nonlocal) {
+        stager = [&](const std::vector<Slice> &slices) {
+            return StageWriteSlices(allocator, slices, staging_handles);
+        };
+    }
+    return ((*client).*write)(keys, batched_slices.value(), config, stager);
+}
+
 #ifdef USE_ASCEND_DIRECT
 bool checkAcl(aclError result, const char *message) {
     if (result != ACL_ERROR_NONE) {
@@ -133,6 +310,23 @@ tl::expected<void, ErrorCode> set_context_if_needed(const std::string &protocol,
     }
     return {};
 }
+
+// DummyClient copy RPCs do not carry device_id; setup_dummy already stored it
+// on each mapped SHM. Use that so the RPC thread has an ACL context before TE
+// submitTransfer / aclrtGetDevice.
+template <typename MappedShms>
+tl::expected<void, ErrorCode> set_context_from_dummy_shms(
+    const std::string &protocol, const MappedShms &mapped_shms,
+    const char *action) {
+    int32_t device_id = kInvalidPhysicalDeviceId;
+    for (const auto &shm : mapped_shms) {
+        if (shm.device_id != kInvalidPhysicalDeviceId) {
+            device_id = shm.device_id;
+            break;
+        }
+    }
+    return set_context_if_needed(protocol, device_id, action);
+}
 #endif
 
 size_t sum_value_sizes(const std::vector<std::span<const char>> &values) {
@@ -261,6 +455,83 @@ inline QueryResult FilterQueryResult(const QueryResult &qr,
         {replica}, qr.lease_timeout,
         include_object_checksum ? qr.object_checksum : std::nullopt);
 }
+
+// Shared object-byte range overflow check (same semantics as
+// execute_ranged_read / session ranged get-put).
+inline bool is_object_range_overflow(size_t offset, size_t size, size_t limit) {
+    return size > limit || offset > limit - size;
+}
+
+inline const Replica::Descriptor *SelectCompleteMemoryReplica(
+    const std::vector<Replica::Descriptor> &replicas,
+    const std::unordered_set<std::string> &local_endpoints) {
+    const Replica::Descriptor *first_memory = nullptr;
+    for (const auto &r : replicas) {
+        if (r.status != ReplicaStatus::COMPLETE || !r.is_memory_replica()) {
+            continue;
+        }
+        if (local_endpoints.count(r.get_memory_descriptor()
+                                      .buffer_descriptor.transport_endpoint_)) {
+            return &r;
+        }
+        if (!first_memory) {
+            first_memory = &r;
+        }
+    }
+    return first_memory;
+}
+
+inline const Replica::Descriptor *SelectSessionReplica(
+    const std::vector<Replica::Descriptor> &replicas,
+    const std::unordered_set<std::string> &local_endpoints) {
+    if (const auto *memory =
+            SelectCompleteMemoryReplica(replicas, local_endpoints)) {
+        return memory;
+    }
+
+    for (const auto &replica : replicas) {
+        if (replica.status == ReplicaStatus::COMPLETE &&
+            replica.is_dfs_replica()) {
+            return &replica;
+        }
+    }
+    return nullptr;
+}
+
+std::shared_ptr<BufferHandle> AcquireSessionStaging(
+    const std::shared_ptr<FileStorage> &file_storage,
+    const std::shared_ptr<ClientBufferAllocator> &fallback_allocator,
+    size_t size, bool prefer_pinned) {
+    if (size == 0) return nullptr;
+
+    try {
+        std::optional<BufferHandle> allocation;
+        if (prefer_pinned && file_storage) {
+            allocation = file_storage->AllocatePinnedStagingBuffer(size);
+            if (!allocation) {
+                VLOG(1) << "Pinned session staging arena unavailable or "
+                           "exhausted; using default client buffer arena";
+            }
+        }
+        if (!allocation && fallback_allocator) {
+            allocation = fallback_allocator->allocate(size);
+        }
+        if (!allocation) return nullptr;
+        return std::make_shared<BufferHandle>(std::move(*allocation));
+    } catch (const std::bad_alloc &) {
+        return nullptr;
+    }
+}
+
+inline bool HasMemoryReplica(const std::vector<Replica::Descriptor> &replicas) {
+    for (const auto &r : replicas) {
+        if (r.is_memory_replica()) {
+            return true;
+        }
+    }
+    return false;
+}
+
 }  // namespace
 
 PyClient::~PyClient() {}
@@ -537,8 +808,7 @@ void ResourceTracker::startSignalThread() {
 RealClient::RealClient() {
     // Initialize logging severity (leave as before)
     mooncake::init_ylt_log_level();
-    const char *hp = std::getenv("MC_STORE_USE_HUGEPAGE");
-    use_hugepage_ = (hp != nullptr);
+    use_hugepage_ = HugepageConfig::IsEnabledFromEnvironment();
 }
 
 RealClient::~RealClient() {
@@ -583,8 +853,6 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
     bool enable_client_http_server, int client_http_port) {
     this->protocol = protocol;
     this->ipc_socket_path_ = ipc_socket_path;
-    const bool should_use_hugepage =
-        use_hugepage_ && this->protocol != "ubshmem";
 #ifdef USE_ASCEND_DIRECT
     if (protocol == "ascend" && globalConfig().ascend_agent_mode) {
         auto ascend_setup = setup_ascend_internal(local_buffer_size);
@@ -634,25 +902,18 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         client_ = *client_opt;
     } else {
         // Auto port binding with retry on metadata registration failure
-        const int kMaxRetries =
-            Environ::GetInt("MC_STORE_CLIENT_SETUP_RETRIES", 20);
-        const int rawMinPort =
-            Environ::GetInt("MC_STORE_CLIENT_MIN_PORT", 12300);
-        const int rawMaxPort =
-            Environ::GetInt("MC_STORE_CLIENT_MAX_PORT", 14300);
-        constexpr int kDefaultMinPort = 12300;
-        constexpr int kDefaultMaxPort = 14300;
-        auto [minPort, maxPort] = ValidatePortRange(
-            rawMinPort, rawMaxPort, kDefaultMinPort, kDefaultMaxPort);
+        const auto auto_port_config = ClientAutoPortConfig::FromEnvironment();
         bool success = false;
 
-        for (int retry = 0; retry < kMaxRetries; ++retry) {
+        for (int retry = 0; retry < auto_port_config.max_retries; ++retry) {
             // Create port binder to hold a port
-            port_binder_ = std::make_unique<AutoPortBinder>(minPort, maxPort);
+            port_binder_ = std::make_unique<AutoPortBinder>(
+                auto_port_config.min_port, auto_port_config.max_port);
             int port = port_binder_->getPort();
             if (port < 0) {
-                LOG(WARNING) << "Failed to bind available port, retry "
-                             << (retry + 1) << "/" << kMaxRetries;
+                LOG(WARNING)
+                    << "Failed to bind available port, retry " << (retry + 1)
+                    << "/" << auto_port_config.max_retries;
                 port_binder_.reset();
                 std::this_thread::sleep_for(std::chrono::milliseconds(100));
                 continue;
@@ -676,14 +937,15 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
             // Failed to create client (possibly due to metadata registration
             // conflict), release port and retry with a different port
             LOG(WARNING) << "Failed to create client on port " << port
-                         << ", retry " << (retry + 1) << "/" << kMaxRetries;
+                         << ", retry " << (retry + 1) << "/"
+                         << auto_port_config.max_retries;
             port_binder_.reset();
             std::this_thread::sleep_for(std::chrono::milliseconds(100));
         }
 
         if (!success) {
-            LOG(ERROR) << "Failed to create client after " << kMaxRetries
-                       << " retries";
+            LOG(ERROR) << "Failed to create client after "
+                       << auto_port_config.max_retries << " retries";
             return tl::unexpected(ErrorCode::INTERNAL_ERROR);
         }
     }
@@ -698,7 +960,8 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
     use_spdk_dma_for_client_buffer = true;
 #endif
     client_buffer_allocator_ = ClientBufferAllocator::create(
-        local_buffer_size, this->protocol, should_use_hugepage,
+        local_buffer_size, this->protocol,
+        use_hugepage_ && !globalConfig().ascend_use_fabric_mem,
         use_spdk_dma_for_client_buffer);
     if (local_buffer_size > 0 && protocol != "cxl") {
         LOG(INFO) << "Registering local memory: " << local_buffer_size
@@ -723,21 +986,16 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         LOG(INFO) << "Local buffer size is 0, skip registering local memory";
     }
 
-    // If global_segment_size is 0, skip mount segment;
-    // If global_segment_size is larger than max_mr_size, split to multiple
-    // mapped_shms.
+    // If global_segment_size is 0, skip mount segment. Transports with a
+    // registration limit split it into balanced chunks; other transports use
+    // one segment.
     if (protocol == "cxl") {
-        size_t cxl_dev_size = 0;
-        const char *env = std::getenv("MC_CXL_DEV_SIZE");
-        if (env) {
-            cxl_dev_size =
-                TryParseInteger<size_t>(env, {.trim_ascii_whitespace = true,
-                                              .allow_leading_plus = true})
-                    .value_or(0);
-        } else {
+        const auto cxl_config = CxlSegmentConfig::FromEnvironment();
+        if (!cxl_config.device_size.has_value()) {
             LOG(FATAL) << "MC_CXL_DEV_SIZE not set";
             return tl::unexpected(ErrorCode::INVALID_PARAMS);
         }
+        const size_t cxl_dev_size = *cxl_config.device_size;
 
         void *ptr = client_->GetBaseAddr();
         LOG(INFO) << "Mounting CXL segment: " << cxl_dev_size << " bytes, "
@@ -750,10 +1008,26 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         }
 
     } else {
-        auto max_mr_size = globalConfig().max_mr_size;     // Max segment size
         uint64_t total_glbseg_size = global_segment_size;  // For logging
         uint64_t current_glbseg_size = 0;                  // For logging
 
+        auto split_limit = GetTransportRegistrationLimit(protocol);
+        const size_t alignment = facebook::cachelib::Slab::kSize;
+#ifdef USE_ASCEND_DIRECT
+        if (protocol == "ascend" && globalConfig().ascend_agent_mode) {
+            const size_t cap = AgentModeStoreChunkCap(global_segment_size);
+            if (cap > 0) {
+                if (!split_limit.has_value() || cap < *split_limit) {
+                    split_limit = cap;
+                }
+                LOG(INFO) << "Agent-mode store chunk cap: " << cap
+                          << " bytes across "
+                          << ContextManager::getInstance().getDeviceCount()
+                          << " device(s)";
+            }
+        }
+#endif
+
         // For RDMA, auto-discover NUMA nodes with NICs and distribute
         // global_segment across them for full NIC utilization.
         std::vector<int> seg_numa_nodes;
@@ -773,10 +1047,16 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         }
 
         const bool parallel_hugetlb_population =
-            protocol == "rdma" && should_use_hugepage;
+            protocol == "rdma" && use_hugepage_;
 
         while (global_segment_size > 0) {
-            size_t segment_size = std::min(global_segment_size, max_mr_size);
+            size_t segment_size =
+                GetNextSegmentSize(global_segment_size, split_limit, alignment);
+            if (segment_size == 0) {
+                LOG(ERROR) << "Registration limit is smaller than segment "
+                              "alignment";
+                return tl::unexpected(ErrorCode::INVALID_PARAMS);
+            }
             global_segment_size -= segment_size;
 
             size_t mapped_size = segment_size;
@@ -785,7 +1065,7 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
 
             if (!seg_numa_nodes.empty()) {
                 // NUMA-segmented allocation: contiguous VMA, per-region binding
-                size_t page_sz = should_use_hugepage
+                size_t page_sz = use_hugepage_
                                      ? get_hugepage_size_from_env()
                                      : static_cast<size_t>(getpagesize());
                 mapped_size =
@@ -793,22 +1073,18 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
                 ptr = allocate_buffer_numa_segments(mapped_size, seg_numa_nodes,
                                                     page_sz);
                 seg_location = buildSegmentsLocation(page_sz, seg_numa_nodes);
-            } else if (should_use_hugepage) {
+#ifdef USE_ASCEND_DIRECT
+            } else if (protocol == "ascend" || protocol == "ubshmem") {
+                ptr = AllocateAscendStoreSegment(
+                    segment_size, this->protocol, use_hugepage_,
+                    parallel_hugetlb_population, &mapped_size);
+#endif
+            } else if (use_hugepage_) {
                 mapped_size =
                     align_up(segment_size, get_hugepage_size_from_env());
                 ptr = allocate_buffer_mmap_memory(mapped_size,
                                                   get_hugepage_size_from_env(),
                                                   parallel_hugetlb_population);
-#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
-            } else if ((protocol == "ascend" || protocol == "ubshmem") &&
-                       globalConfig().ascend_use_fabric_mem) {
-                size_t actual_size = 0;
-                ptr = ascend_allocate_memory_best_effort(
-                    segment_size, this->protocol, &actual_size);
-                if (ptr) {
-                    mapped_size = actual_size;
-                }
-#endif
             } else {
                 ptr = allocate_buffer_allocator_memory(segment_size,
                                                        this->protocol);
@@ -818,13 +1094,20 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
                 LOG(ERROR) << "Failed to allocate segment memory";
                 return tl::unexpected(ErrorCode::INVALID_PARAMS);
             }
-            current_glbseg_size += mapped_size;
-            LOG(INFO) << "Mounting segment: " << mapped_size << " bytes, "
+            const size_t mount_size =
+                split_limit.has_value() ? segment_size : mapped_size;
+            current_glbseg_size += mount_size;
+            LOG(INFO) << "Mounting segment: " << mount_size << " bytes, "
                       << current_glbseg_size << " of " << total_glbseg_size;
 
             if (this->protocol == "ascend" || this->protocol == "ubshmem") {
-                ascend_segment_ptrs_.emplace_back(
-                    ptr, AscendSegmentDeleter{this->protocol});
+                if (use_hugepage_ && !globalConfig().ascend_use_fabric_mem) {
+                    hugepage_segment_ptrs_.emplace_back(
+                        ptr, HugepageSegmentDeleter{mapped_size});
+                } else {
+                    ascend_segment_ptrs_.emplace_back(
+                        ptr, AscendSegmentDeleter{this->protocol});
+                }
             } else if (this->protocol == "sunrise_link") {
 #if defined(USE_SUNRISE)
                 sunrise_segment_ptrs_.emplace_back(ptr,
@@ -837,7 +1120,7 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
             } else if (this->protocol == "ub") {
                 ub_segment_ptrs_.emplace_back(ptr,
                                               UbSegmentDeleter{mapped_size});
-            } else if (!seg_numa_nodes.empty() || should_use_hugepage) {
+            } else if (!seg_numa_nodes.empty() || use_hugepage_) {
                 // NUMA-segmented or hugepage: track as mmap allocation for
                 // munmap cleanup
                 hugepage_segment_ptrs_.emplace_back(
@@ -865,7 +1148,7 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
             auto pinned_region =
                 TryPinStoreSegment(ptr, mapped_size, this->protocol, "setup");
             auto mount_result =
-                client_->MountSegment(ptr, mapped_size, protocol, seg_location);
+                client_->MountSegment(ptr, mount_size, protocol, seg_location);
             if (!mount_result.has_value()) {
                 if (!ReleasePinnedRegionForFree(pinned_region,
                                                 "Store setup segment")) {
@@ -883,6 +1166,12 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         if (total_glbseg_size == 0) {
             LOG(INFO) << "Global segment size is 0, skip mounting segment";
         }
+#ifdef USE_ASCEND_DIRECT
+        if (protocol == "ascend" && globalConfig().ascend_agent_mode &&
+            !RestoreAgentModeDeviceZero()) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+#endif
     }
 
     // Start IPC server to accept FD from dummy clients
@@ -931,6 +1220,22 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
                        << init_result.error();
             return init_result;
         }
+        // The dangling-replica heal in Client::Put needs an existence check
+        // against this process's offload files, which only the FileStorage
+        // owns. true: backing file is gone, false: present, nullopt: unknown.
+        std::weak_ptr<FileStorage> weak_storage = file_storage_;
+        client_->SetLocalDiskProbe(
+            [weak_storage](const std::string &key) -> std::optional<bool> {
+                auto storage = weak_storage.lock();
+                if (!storage) {
+                    return std::nullopt;
+                }
+                auto exists = storage->Exists(key);
+                if (!exists) {
+                    return std::nullopt;
+                }
+                return !*exists;
+            });
     }
     client_requester_ = std::make_shared<ClientRequester>();
     const bool should_start_http_server =
@@ -1069,8 +1374,8 @@ tl::expected<void, ErrorCode> RealClient::setup_internal(
         get_config(config, CONFIG_KEY_IPC_SOCKET_PATH);
 
     // A size of 0 keeps the pure client/server setup semantics.
-    // global_segment_size is a total capacity and may exceed max_mr_size; the
-    // setup path splits it into mountable chunks below.
+    // global_segment_size is a total capacity; protocols with a registration
+    // limit split it into mountable chunks below.
     auto validate_min_size = [](const char *key, size_t value) {
         if (value != 0 && value < MIN_SEGMENT_SIZE) {
             LOG(ERROR) << "Invalid " << key << ": " << value
@@ -1201,6 +1506,26 @@ tl::expected<void, ErrorCode> RealClient::tearDownAll_internal() {
             if (seg.shm_buffer == nullptr) {
                 continue;
             }
+#ifdef USE_NOF
+            // Unregister the SPDK registration before munmap (see
+            // unmap_shm_internal). munmap is only safe once the SPDK
+            // translation is gone; if unregister fails, retain the mapping
+            // (quarantine) so the VA cannot be reused while SPDK still holds a
+            // translation to it.
+            if (seg.spdk_registered) {
+                if (SpdkWrapper::GetInstance().UnregisterMemory(
+                        seg.shm_buffer, seg.shm_size) != 0) {
+                    LOG(ERROR) << "Failed to unregister received shm from SPDK "
+                                  "during teardown: "
+                               << seg.shm_buffer
+                               << "; quarantining mapping (never munmap)";
+                    quarantine_shms_.push_back(std::move(seg));
+                    seg.shm_buffer = nullptr;
+                    continue;
+                }
+                seg.spdk_registered = false;
+            }
+#endif
             if (seg.is_ascend) {
                 teardown_ascend_shm_buffer(seg);
             } else if (munmap(seg.shm_buffer, seg.shm_size) != 0) {
@@ -1213,9 +1538,59 @@ tl::expected<void, ErrorCode> RealClient::tearDownAll_internal() {
 
         shm_it = shm_contexts_.erase(shm_it);
     }
+    // Re-attempt quarantined segments (unregister failed during this teardown
+    // or an earlier one). Any that still fail are retained until process exit,
+    // which is safe: they are never munmapped, so SPDK's translations never
+    // point at freed/reused virtual addresses.
+    RetryQuarantinedShmsLocked();
     return {};
 }
 
+void RealClient::RetryQuarantinedShmsLocked() {
+    auto it = quarantine_shms_.begin();
+    while (it != quarantine_shms_.end()) {
+        // The transfer engine may still hold this region (unregisterLocalMemory
+        // failed earlier): retry it first, and never munmap while TE still has
+        // the MR registered, or a later mmap reusing this VA would collide
+        // (ERR_ADDRESS_OVERLAPPED) or DMA to unmapped memory.
+        if (it->te_unregister_pending) {
+            if (!client_) {
+                // No client left to retry against (torn down). Conservatively
+                // retain the mapping rather than risk a stale TE registration;
+                // it is released by the OS at process exit.
+                ++it;
+                continue;
+            }
+            if (!client_->unregisterLocalMemory(it->shm_buffer, true)) {
+                ++it;
+                continue;
+            }
+            it->te_unregister_pending = false;
+        }
+#ifdef USE_NOF
+        // A quarantined segment may still have a live SPDK registration: only
+        // munmap once the translation is actually released.
+        if (it->spdk_registered) {
+            if (SpdkWrapper::GetInstance().UnregisterMemory(
+                    it->shm_buffer, it->shm_size) != 0) {
+                ++it;
+                continue;
+            }
+            it->spdk_registered = false;
+        }
+#endif
+        if (munmap(it->shm_buffer, it->shm_size) != 0) {
+            LOG(ERROR) << "Failed to munmap quarantined shm: " << it->shm_name
+                       << ", error: " << strerror(errno);
+            ++it;
+            continue;
+        }
+        LOG(INFO) << "Released quarantined shared memory: " << it->shm_name
+                  << ", size: " << it->shm_size;
+        it = quarantine_shms_.erase(it);
+    }
+}
+
 int RealClient::tearDownAll() { return to_py_ret(tearDownAll_internal()); }
 
 int RealClient::mountSegment(const std::string &path, size_t offset,
@@ -1227,18 +1602,7 @@ int RealClient::mountSegment(const std::string &path, size_t offset,
         return -1;
     }
 
-    size_t max_mr_size = globalConfig().max_mr_size;
-    if (max_mr_size == 0) {
-        LOG(ERROR) << "Invalid max_mr_size: 0";
-        return -1;
-    }
-
     size_t page_size = sysconf(_SC_PAGESIZE);
-    if (max_mr_size < page_size) {
-        LOG(ERROR) << "max_mr_size " << max_mr_size
-                   << " is smaller than page_size " << page_size;
-        return -1;
-    }
 
     int fd = open(path.c_str(), O_RDWR);
     if (fd < 0) {
@@ -1267,14 +1631,15 @@ int RealClient::mountSegment(const std::string &path, size_t offset,
         return -1;
     }
 
-    size_t aligned_max_chunk = (max_mr_size / page_size) * page_size;
+    const auto split_limit = GetTransportRegistrationLimit(protocol);
     size_t remaining = size;
     size_t current_offset = offset;
     std::vector<std::string> mounted_ids;
     std::vector<MountedSegmentRecord> mounted_records;
 
     while (remaining > 0) {
-        size_t chunk_size = std::min(remaining, aligned_max_chunk);
+        size_t chunk_size =
+            GetNextSegmentSize(remaining, split_limit, page_size);
         if (chunk_size == 0) break;
 
         void *ptr = mmap(nullptr, chunk_size, PROT_READ | PROT_WRITE,
@@ -1480,34 +1845,12 @@ int RealClient::allocateAndMountSegment(
         return -1;
     }
 
-    size_t max_mr_size = globalConfig().max_mr_size;
-    if (max_mr_size == 0) {
-        LOG(ERROR) << "Invalid max_mr_size: 0";
-        return -1;
-    }
-
     if (size == 0) {
         LOG(ERROR) << "size is 0";
         return -1;
     }
 
     const size_t slab_size = facebook::cachelib::Slab::kSize;
-    size_t page_size = sysconf(_SC_PAGESIZE);
-    if (max_mr_size < page_size) {
-        LOG(ERROR) << "max_mr_size " << max_mr_size
-                   << " is smaller than page_size " << page_size;
-        return -1;
-    }
-
-    size_t aligned_max_chunk = (max_mr_size / page_size) * page_size;
-    if (aligned_max_chunk < slab_size) {
-        LOG(ERROR) << "max_mr_size " << max_mr_size
-                   << " is smaller than slab_size " << slab_size;
-        return -1;
-    }
-    // Round down chunk size to slab_size multiple
-    aligned_max_chunk = (aligned_max_chunk / slab_size) * slab_size;
-
     // Check overflow before aligning up to slab_size
     if (size > std::numeric_limits<size_t>::max() - (slab_size - 1)) {
         LOG(ERROR) << "size " << size
@@ -1517,12 +1860,14 @@ int RealClient::allocateAndMountSegment(
     // Round up total size to slab_size multiple
     size_t aligned_total_size =
         ((size + slab_size - 1) / slab_size) * slab_size;
+    const auto split_limit = GetTransportRegistrationLimit(protocol);
     size_t remaining = aligned_total_size;
     std::vector<std::string> mounted_ids;
     std::vector<AllocatedSegmentRecord> allocated_records;
 
     while (remaining > 0) {
-        size_t chunk_size = std::min(remaining, aligned_max_chunk);
+        size_t chunk_size =
+            GetNextSegmentSize(remaining, split_limit, slab_size);
         if (chunk_size == 0) break;
 
         void *ptr = allocate_buffer_allocator_memory(chunk_size, protocol);
@@ -1652,6 +1997,21 @@ int RealClient::unmountAndFreeSegment(
     return first_error;
 }
 
+int RealClient::drainLocalDiskSegment(uint64_t grace_period_seconds) {
+    if (!client_) {
+        LOG(ERROR) << "Client not initialized";
+        return -1;
+    }
+    if (!file_storage_) {
+        LOG(WARNING) << "action=drain_local_disk_segment, "
+                        "warn=ssd_offload_not_enabled";
+        return 0;
+    }
+    auto result =
+        file_storage_->DrainLocalDiskSegment(grace_period_seconds * 1000);
+    return result ? 0 : -1;
+}
+
 int RealClient::health_check() {
     if (closed_.load()) return HC_NOT_INITIALIZED;
     if (!client_) return HC_NOT_INITIALIZED;
@@ -1731,6 +2091,15 @@ int RealClient::start_http_server(int port) {
             resp.set_status_and_content(status_type::ok, std::move(*result));
         });
 
+    http_server_->set_http_handler<GET>(
+        "/version", [](coro_http_request &req, coro_http_response &resp) {
+            std::string body = "{\"version\":\"" + GetMooncakeStoreVersion() +
+                               "\",\"display_version\":\"" +
+                               std::string(MOONCAKE_DISPLAY_VERSION) + "\"}";
+            resp.add_header("Content-Type", "application/json");
+            resp.set_status_and_content(status_type::ok, std::move(body));
+        });
+
     auto ec = http_server_->async_start();
     if (ec.hasResult()) {
         LOG(WARNING) << "Failed to start HTTP server on port " << port;
@@ -1798,6 +2167,13 @@ tl::expected<void, ErrorCode> RealClient::put_dummy_helper(
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
     auto &context = it->second;
+#ifdef USE_ASCEND_DIRECT
+    auto context_result =
+        set_context_from_dummy_shms(protocol, context.mapped_shms, "put");
+    if (!context_result) {
+        return context_result;
+    }
+#endif
 
     return put_internal(key, value, config, context.client_buffer_allocator);
 }
@@ -1900,6 +2276,13 @@ tl::expected<void, ErrorCode> RealClient::put_batch_dummy_helper(
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
     auto &context = it->second;
+#ifdef USE_ASCEND_DIRECT
+    auto context_result =
+        set_context_from_dummy_shms(protocol, context.mapped_shms, "put_batch");
+    if (!context_result) {
+        return context_result;
+    }
+#endif
 
     return put_batch_internal(keys, values, config,
                               context.client_buffer_allocator);
@@ -1996,6 +2379,13 @@ tl::expected<void, ErrorCode> RealClient::put_parts_dummy_helper(
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
     auto &context = it->second;
+#ifdef USE_ASCEND_DIRECT
+    auto context_result =
+        set_context_from_dummy_shms(protocol, context.mapped_shms, "put_parts");
+    if (!context_result) {
+        return context_result;
+    }
+#endif
 
     return put_parts_internal(key, values, config,
                               context.client_buffer_allocator);
@@ -2122,6 +2512,33 @@ std::vector<int> RealClient::batchIsExist(
     return results;
 }
 
+int RealClient::probeKey(const std::string &key) {
+    auto result = probeKey_internal(key);
+
+    if (result.has_value()) {
+        return *result ? 1 : 0;  // 1 if exists, 0 if not
+    } else {
+        return toInt(result.error());
+    }
+}
+
+std::vector<int> RealClient::batchProbeKey(
+    const std::vector<std::string> &keys) {
+    auto internal_results = batchProbeKey_internal(keys);
+    std::vector<int> results;
+    results.reserve(internal_results.size());
+
+    for (const auto &result : internal_results) {
+        if (result.has_value()) {
+            results.push_back(result.value() ? 1 : 0);  // 1 if exists, 0 if not
+        } else {
+            results.push_back(toInt(result.error()));
+        }
+    }
+
+    return results;
+}
+
 tl::expected<int64_t, ErrorCode> RealClient::getSize_internal(
     const std::string &key) {
     if (!client_) {
@@ -2201,9 +2618,38 @@ tl::expected<void, ErrorCode> RealClient::map_shm_internal_with_device(
     }
 #endif
 
-    // Map shared memory from FD
-    void *shm_buffer =
-        mmap(nullptr, shm_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+    // Map shared memory from FD.
+    void *shm_buffer = nullptr;
+#ifdef USE_NOF
+    // Register this receiver-side mapping with SPDK for NoF zero-copy.
+    // spdk_mem_register is per-process: the sender (ShmHelper::allocate)
+    // registers ITS mapping, and in the dummy/real split the NoF submit runs
+    // HERE on our mapping of the shared fd, so it must be registered too. Gated
+    // on the same env as the sender (MC_STORE_REGISTER_SPDK=1). On SPDK < 26.09
+    // the base must be 2MB-aligned, so when we will register and the sender
+    // padded shm_size to a 2MB multiple, map the fd at a 2MB-aligned address
+    // (mmap_shm_2mb_aligned). If shm_size is not a 2MB multiple (env mismatch:
+    // sender didn't pad), fall back to a plain mmap and let the registration
+    // attempt fail non-fatally.
+    const bool register_spdk = ShmHelper::is_register_spdk_enabled();
+    if (register_spdk && (shm_size % SZ_2MB == 0)) {
+        shm_buffer = mmap_shm_2mb_aligned(shm_size, fd);
+        if (shm_buffer == MAP_FAILED) {
+            // 2MB-aligned MAP_FIXED fails for HugeTLB fds whose base must be
+            // hugepage-aligned (e.g. 1GB hugepages): fall back to a plain mmap,
+            // which lets the kernel pick a hugepage-aligned base (2MB or 1GB,
+            // both multiples of 2MB). Registration below then succeeds for
+            // those fds; for non-hugetlb fds that fail alignment it degrades
+            // non-fatally.
+            shm_buffer = mmap(nullptr, shm_size, PROT_READ | PROT_WRITE,
+                              MAP_SHARED, fd, 0);
+        }
+    } else
+#endif
+    {
+        shm_buffer =
+            mmap(nullptr, shm_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+    }
     if (shm_buffer == MAP_FAILED) {
         LOG(ERROR) << "Failed to map shared memory from fd: " << fd
                    << ", name: " << shm_name << ", error: " << strerror(errno);
@@ -2247,6 +2693,76 @@ tl::expected<void, ErrorCode> RealClient::map_shm_internal_with_device(
             ClientBufferAllocator::create(shm_buffer, shm_size, this->protocol);
     }
 
+    // Ensure push_back below cannot reallocate and throw bad_alloc after the
+    // SPDK registration succeeded (which would leak the registration and the
+    // mapping). If reserve itself throws it happens before registration.
+    context.mapped_shms.reserve(context.mapped_shms.size() + 1);
+
+#ifdef USE_NOF
+    // Register this mapping with SPDK for NoF zero-copy. Non-fatal on failure:
+    // the buffer stays usable for all non-NoF paths. Placed after the
+    // error-returning paths above so no failure path leaves a dangling SPDK
+    // registration (the unregister below is symmetric on every teardown path).
+    if (register_spdk) {
+        if (!SpdkWrapper::IsRegistrableRange(shm.shm_buffer, shm.shm_size)) {
+            // Reached by the fallback mmap above when it cannot place the
+            // mapping at a 2MB-aligned base (e.g. a non-hugetlb fd). SPDK
+            // rejects such a range before marking anything (memory.c:344), so
+            // skipping the attempt keeps the teardown below able to munmap.
+            LOG(WARNING) << "Received shm is not 2MB-aligned; not registering "
+                            "with SPDK: "
+                         << shm.shm_buffer << ", size=" << shm.shm_size
+                         << "; NoF zero-copy transfers to this buffer will be "
+                            "unavailable";
+        } else {
+            const int register_rc = SpdkWrapper::GetInstance().RegisterMemory(
+                shm.shm_buffer, shm.shm_size);
+            if (register_rc == 0) {
+                shm.spdk_registered = true;
+            } else if (register_rc == -EBUSY) {
+                // Already registered, so SPDK marked nothing new for us. Do NOT
+                // roll back: the unregister below would clear the existing
+                // registration (memory.c:358-366 detects it, 445-466 clears
+                // it). Retain the mapping and let teardown retry.
+                LOG(ERROR) << "Received shm is already registered with SPDK: "
+                           << shm.shm_buffer << ", size=" << shm.shm_size
+                           << "; retaining mapping";
+                shm.spdk_registered = true;
+            } else {
+                LOG(WARNING) << "Failed to register received shm with SPDK: "
+                             << shm.shm_buffer << ", size=" << shm.shm_size
+                             << "; NoF zero-copy transfers to this buffer will "
+                                "be unavailable";
+                // spdk_mem_register() marks the range in g_mem_reg_map before
+                // running its notify callbacks and does NOT roll back on
+                // failure (SPDK v23.01.1, memory.c:370-384), and in iova=va it
+                // can already have installed the IOMMU mapping when a later
+                // step fails (memory.c:1092-1107). This unregister is the only
+                // chance to undo that, and only a 0 return proves it worked:
+                // -EINVAL is also returned for a half-marked range
+                // (memory.c:426) and, in iova=va, for an incomplete translation
+                // before the IOMMU is unmapped (memory.c:1216-1224); it covers
+                // a failure before anything was mapped as well, and the two
+                // cannot be told apart, so retaining a clean mapping is the
+                // accepted cost. Mirrors ShmHelper::allocate.
+                const int rollback_rc =
+                    SpdkWrapper::GetInstance().UnregisterMemory(shm.shm_buffer,
+                                                                shm.shm_size);
+                if (rollback_rc != 0) {
+                    LOG(ERROR)
+                        << "Failed to roll back incomplete SPDK registration: "
+                        << shm.shm_buffer << ", size: " << shm.shm_size
+                        << ", rc: " << rollback_rc
+                        << "; treating the range as registered so teardown "
+                           "retries the unregister and quarantines the mapping "
+                           "instead of munmapping";
+                    shm.spdk_registered = true;
+                }
+            }
+        }
+    }
+#endif
+
     context.mapped_shms.push_back(std::move(shm));
 
     LOG(INFO) << "Mapped new shared memory: " << shm_name
@@ -2266,21 +2782,86 @@ tl::expected<void, ErrorCode> RealClient::unmap_shm_internal(
     auto &context = it->second;
     context.client_buffer_allocator.reset();
 
+    // Retry previously quarantined segments (unregister failed earlier) before
+    // tearing down this context.
+    RetryQuarantinedShmsLocked();
+
+    bool failed = false;
+    // Keep the quarantine push_back below from reallocating (and throwing
+    // bad_alloc) in the middle of tearing a context down.
+    quarantine_shms_.reserve(quarantine_shms_.size() +
+                             context.mapped_shms.size());
     for (auto &shm : context.mapped_shms) {
-        if (shm.shm_buffer) {
-            auto rc = client_->unregisterLocalMemory(shm.shm_buffer, true);
-            if (!rc) {
-                LOG(ERROR) << "Failed to unregister memory";
-                munmap(shm.shm_buffer, shm.shm_size);
-                context.mapped_shms.clear();
-                shm_contexts_.erase(it);
-                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
-            }
+        if (!shm.shm_buffer) {
+            continue;
+        }
+        // Unregister with the transfer engine first: TE retains its region
+        // record when unregisterLocalMemory() fails and
+        // RdmaTransport::unregisterLocalMemoryInternal returns before
+        // deregistering the MR, so munmapping here would leave TE registered
+        // for an address a later mmap can reuse (ERR_ADDRESS_OVERLAPPED, or DMA
+        // to unmapped memory).
+        const bool te_ok = static_cast<bool>(
+            client_->unregisterLocalMemory(shm.shm_buffer, true));
+#ifdef USE_NOF
+        // Unregister the SPDK registration BEFORE munmap, mirroring
+        // ShmHelper::free()/cleanup(). munmap is only safe once the SPDK
+        // translation is gone.
+        bool spdk_ok = true;
+        if (shm.spdk_registered) {
+            spdk_ok = SpdkWrapper::GetInstance().UnregisterMemory(
+                          shm.shm_buffer, shm.shm_size) == 0;
+        }
+#else
+        const bool spdk_ok = true;
+#endif
+        if (te_ok && spdk_ok) {
+#ifdef USE_NOF
+            shm.spdk_registered = false;
+#endif
+            // Both unregisters succeeded, so the VA is no longer referenced by
+            // TE or SPDK and can be released. Siblings that fail are handled by
+            // their own iterations, so a single failure does not leak the rest.
             munmap(shm.shm_buffer, shm.shm_size);
+            shm.shm_buffer = nullptr;
+            continue;
+        }
+        // Unregister failed: retain the mapping (never munmap) so neither TE
+        // nor SPDK keeps a registration to a freed/reused VA, and quarantine it
+        // for a retry on a later teardown entry point.
+        if (!te_ok) {
+            LOG(ERROR) << "Failed to unregister memory: " << shm.shm_name
+                       << "; quarantining mapping (never munmap)";
         }
+#ifdef USE_NOF
+        if (!spdk_ok) {
+            LOG(ERROR) << "Failed to unregister received shm from SPDK: "
+                       << shm.shm_buffer
+                       << "; quarantining mapping (never munmap)";
+        }
+#endif
+        shm.te_unregister_pending = !te_ok;
+#ifdef USE_NOF
+        // Record only the side that is still registered. Clear spdk_registered
+        // when the SPDK unregister above succeeded even though the mapping
+        // stays quarantined: a later RetryQuarantinedShmsLocked() would
+        // otherwise call spdk_mem_unregister() a second time, get the benign
+        // -EINVAL no-op for an already released range (SPDK memory.c: no
+        // segment is marked REGISTERED), treat it as a failure, and keep the
+        // mapping quarantined (never munmapped) forever.
+        shm.spdk_registered = !spdk_ok;
+#endif
+        quarantine_shms_.push_back(std::move(shm));
+        // std::move leaves raw pointer members unchanged; clear it so the
+        // moved-from entry cannot be munmapped a second time.
+        shm.shm_buffer = nullptr;
+        failed = true;
     }
     context.mapped_shms.clear();
     shm_contexts_.erase(it);
+    if (failed) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
     return {};
 }
 
@@ -2491,11 +3072,16 @@ tl::expected<void, ErrorCode> RealClient::ascend_unmap_shm_internal(
     auto &context = it->second;
     context.client_buffer_allocator.reset();
 
+    // Retry previously quarantined segments (unregister failed earlier) before
+    // tearing down this context.
+    RetryQuarantinedShmsLocked();
+
     // Move regions out before cleanup so failure paths cannot erase the map
     // entry while iterating (undefined behavior) or double-erase at the end.
     std::vector<MappedShm> shms = std::move(context.mapped_shms);
     context.mapped_shms.clear();
 
+    bool failed = false;
     for (auto &shm : shms) {
         if (!shm.shm_buffer) {
             continue;
@@ -2503,6 +3089,11 @@ tl::expected<void, ErrorCode> RealClient::ascend_unmap_shm_internal(
         if (shm.is_ascend) {
             teardown_ascend_shm_buffer(shm);
         } else {
+            // Unregister with the transfer engine first: TE retains its region
+            // record when unregisterLocalMemory() fails (see
+            // unmap_shm_internal), so munmapping here would leave TE registered
+            // for an address a later mmap can reuse.
+            bool te_ok = true;
 #ifdef USE_ASCEND_DIRECT
             auto context_result = set_context_if_needed(protocol, shm.device_id,
                                                         "POSIX shm cleanup");
@@ -2515,15 +3106,56 @@ tl::expected<void, ErrorCode> RealClient::ascend_unmap_shm_internal(
                 // Host POSIX shm mapped via map_shm_internal (memfd); not
                 // Ascend VMM/IPC.
                 if (shm.shm_size > 0 && client_) {
-                    auto res =
+                    const auto res =
                         client_->unregisterLocalMemory(shm.shm_buffer, true);
                     if (!res) {
-                        LOG(WARNING) << "Failed to unregister local memory for "
-                                        "POSIX shm: "
-                                     << shm.shm_name
-                                     << ", error: " << toString(res.error());
+                        te_ok = false;
+                        LOG(ERROR) << "Failed to unregister local memory for "
+                                      "POSIX shm: "
+                                   << shm.shm_name
+                                   << ", error: " << toString(res.error())
+                                   << "; quarantining mapping (never munmap)";
                     }
                 }
+            // Unregister the SPDK registration before munmap (see
+            // unmap_shm_internal). munmap is only safe once the SPDK
+            // translation is gone.
+            bool spdk_ok = true;
+#ifdef USE_NOF
+            if (shm.spdk_registered) {
+                spdk_ok = SpdkWrapper::GetInstance().UnregisterMemory(
+                              shm.shm_buffer, shm.shm_size) == 0;
+            }
+#endif
+            if (!te_ok || !spdk_ok) {
+                // Unregister failed: retain the mapping (never munmap) so
+                // neither TE nor SPDK keeps a registration to a freed/reused
+                // VA, and quarantine it for a retry on a later teardown entry
+                // point.
+                if (!spdk_ok) {
+                    LOG(ERROR) << "Failed to unregister received shm from SPDK "
+                                  "during unmap: "
+                               << shm.shm_buffer
+                               << "; quarantining mapping (never munmap)";
+                }
+                shm.te_unregister_pending = !te_ok;
+#ifdef USE_NOF
+                // Clear spdk_registered when the SPDK unregister above
+                // succeeded: see unmap_shm_internal (a stale flag makes the
+                // retry re-unregister an already released range, get -EINVAL,
+                // and keep the mapping quarantined forever).
+                shm.spdk_registered = !spdk_ok;
+#endif
+                quarantine_shms_.push_back(std::move(shm));
+                // std::move leaves raw pointer members unchanged; clear it so
+                // the moved-from entry cannot be munmapped a second time.
+                shm.shm_buffer = nullptr;
+                failed = true;
+                continue;
+            }
+#ifdef USE_NOF
+            shm.spdk_registered = false;
+#endif
             if (munmap(shm.shm_buffer, shm.shm_size) != 0) {
                 LOG(ERROR) << "Failed to munmap POSIX shared memory: "
                            << shm.shm_name << ", error: " << strerror(errno);
@@ -2534,6 +3166,9 @@ tl::expected<void, ErrorCode> RealClient::ascend_unmap_shm_internal(
         }
     }
     shm_contexts_.erase(it);
+    if (failed) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
     return {};
 }
 
@@ -2558,10 +3193,17 @@ tl::expected<void, ErrorCode> RealClient::unregister_shm_buffer_internal(
     std::unique_lock<std::shared_mutex> lock(dummy_client_mutex_);
     auto it = shm_contexts_.find(client_id);
     if (it == shm_contexts_.end()) {
-        LOG(ERROR) << "client_id=" << client_id << ", error=shm_not_mapped";
-        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        // Per-buffer unregistration is idempotent so a DummyClient can safely
+        // retry after the RealClient completed an earlier request but its
+        // response was lost.
+        return {};
     }
     auto &context = it->second;
+    bool unregister_failed = false;
+
+    // Retry previously quarantined segments (unregister failed earlier) before
+    // handling this buffer.
+    RetryQuarantinedShmsLocked();
 
     // Find the shm corresponding to this dummy address
     auto shm_it = context.mapped_shms.end();
@@ -2574,11 +3216,7 @@ tl::expected<void, ErrorCode> RealClient::unregister_shm_buffer_internal(
     }
 
     if (shm_it == context.mapped_shms.end()) {
-        std::stringstream addr_stream;
-        addr_stream << "0x" << std::hex << dummy_base_addr;
-        LOG(ERROR) << "Share memory not found for dummy address: "
-                   << addr_stream.str() << " (client_id: " << client_id << ")";
-        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        return {};
     }
 
     // Unmap and clean up the shm
@@ -2590,22 +3228,85 @@ tl::expected<void, ErrorCode> RealClient::unregister_shm_buffer_internal(
             auto context_result = set_context_if_needed(
                 protocol, shm_it->device_id, "POSIX shm unregister");
             if (!context_result) {
-                return context_result;
+                // Nothing was torn down: the mapping, its TE region and its
+                // SPDK registration are all still live here, and shm_it stays
+                // in context.mapped_shms. Report RPC_FAIL instead of
+                // propagating INVALID_PARAMS, which the two early returns above
+                // use for "the receiver holds no such mapping": the caller must
+                // be able to tell "nothing was registered here" apart from "the
+                // teardown did not run", so that it keeps its local bookkeeping
+                // and retries instead of leaking this mapping until process
+                // exit. DummyClient::unregister_buffer() only drops its
+                // shm->registered flag for OK / INTERNAL_ERROR /
+                // INVALID_PARAMS.
+                LOG(ERROR) << "Cannot unregister shm buffer for client_id="
+                           << client_id
+                           << ": could not set the Ascend context for device "
+                           << shm_it->device_id
+                           << ", error: " << toString(context_result.error())
+                           << "; no teardown performed, mapping retained";
+                return tl::make_unexpected(ErrorCode::RPC_FAIL);
             }
 #endif
-            auto rc = client_->unregisterLocalMemory(shm_it->shm_buffer, true);
-            if (!rc) {
+            // Unregister with the transfer engine first: TE retains its region
+            // record when unregisterLocalMemory() fails (see
+            // unmap_shm_internal), so munmapping here would leave TE registered
+            // for an address a later mmap can reuse.
+            const bool te_ok = static_cast<bool>(
+                client_->unregisterLocalMemory(shm_it->shm_buffer, true));
+            if (!te_ok) {
                 LOG(ERROR) << "Failed to unregister memory: "
-                           << shm_it->shm_name;
-                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
-            }
-            if (munmap(shm_it->shm_buffer, shm_it->shm_size) != 0) {
-                LOG(ERROR) << "Failed to munmap shared memory: "
                            << shm_it->shm_name
-                           << ", error: " << strerror(errno);
+                           << "; quarantining mapping (never munmap)";
+            }
+            // Unregister the SPDK registration before munmap (see
+            // unmap_shm_internal). munmap is only safe once the SPDK
+            // translation is gone.
+            bool spdk_ok = true;
+#ifdef USE_NOF
+            if (shm_it->spdk_registered) {
+                spdk_ok = SpdkWrapper::GetInstance().UnregisterMemory(
+                              shm_it->shm_buffer, shm_it->shm_size) == 0;
+            }
+#endif
+            if (!te_ok || !spdk_ok) {
+                // Unregister failed: retain the mapping (never munmap) so
+                // neither TE nor SPDK keeps a registration to a freed/reused
+                // VA, and quarantine it for a retry on a later teardown entry
+                // point.
+                if (!spdk_ok) {
+                    LOG(ERROR) << "Failed to unregister received shm from SPDK "
+                                  "during unregister: "
+                               << shm_it->shm_buffer
+                               << "; quarantining mapping (never munmap)";
+                }
+                shm_it->te_unregister_pending = !te_ok;
+#ifdef USE_NOF
+                // Clear spdk_registered when the SPDK unregister above
+                // succeeded: see unmap_shm_internal (a stale flag makes the
+                // retry re-unregister an already released range, get -EINVAL,
+                // and keep the mapping quarantined forever).
+                shm_it->spdk_registered = !spdk_ok;
+#endif
+                quarantine_shms_.push_back(std::move(*shm_it));
+                // std::move leaves raw pointer members unchanged; clear it so
+                // the moved-from entry cannot be munmapped again (the entry is
+                // erased just below).
+                shm_it->shm_buffer = nullptr;
+                unregister_failed = true;
             } else {
-                LOG(INFO) << "Unmapped and cleaned up shared memory: "
-                          << shm_it->shm_name << ", size: " << shm_it->shm_size;
+#ifdef USE_NOF
+                shm_it->spdk_registered = false;
+#endif
+                if (munmap(shm_it->shm_buffer, shm_it->shm_size) != 0) {
+                    LOG(ERROR)
+                        << "Failed to munmap shared memory: "
+                        << shm_it->shm_name << ", error: " << strerror(errno);
+                } else {
+                    LOG(INFO)
+                        << "Unmapped and cleaned up shared memory: "
+                        << shm_it->shm_name << ", size: " << shm_it->shm_size;
+                }
             }
         }
     }
@@ -2613,6 +3314,9 @@ tl::expected<void, ErrorCode> RealClient::unregister_shm_buffer_internal(
     // Remove shm from list
     context.mapped_shms.erase(shm_it);
 
+    if (unregister_failed) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
     return {};
 }
 
@@ -2648,10 +3352,10 @@ std::shared_ptr<BufferHandle> RealClient::get_buffer_internal(
         return nullptr;
     }
 
-    // Select best replica: prefer local MEMORY, then any MEMORY,
-    // then LOCAL_DISK, then DISK.
+    // Select best replica: prefer local MEMORY, any MEMORY, local NOF, any NOF,
+    // LOCAL_DISK, DFS, then DISK.
     // LOCAL_DISK data is on a remote node's SSD — must use offload RPC.
-    // MEMORY / DISK are handled via client_->Get below.
+    // MEMORY / DISK / DFS are handled via client_->Get below.
     auto local_endpoints = client_->GetLocalEndpoints();
     const auto *best_replica = SelectBestReplica(replica_list, local_endpoints);
     if (!best_replica) {
@@ -2701,14 +3405,15 @@ std::shared_ptr<BufferHandle> RealClient::get_buffer_internal(
         return buffer_handle;
     }
 
-    // MEMORY / DISK: use client_->Get.  FilterQueryResult ensures
+    // MEMORY / DISK / DFS: use client_->Get. FilterQueryResult ensures
     // Client::Get internal FindFirstCompleteReplica can only see
     // the replica we selected, preventing accidental LOCAL_DISK picks.
     auto runtime_accelerator =
         device::GetAcceleratorRegistry().RuntimeAccelerators();
-    if (replica.is_disk_replica() &&
+    if ((replica.is_disk_replica() || replica.is_dfs_replica()) &&
         runtime_accelerator.FindDeviceForPointer(buffer_handle->ptr())) {
-        LOG(WARNING) << "DISK replica for key '" << key
+        LOG(WARNING) << (replica.is_dfs_replica() ? "DFS" : "DISK")
+                     << " replica for key '" << key
                      << "' received a device pointer from the allocator; "
                      << "file I/O cannot write to GPU memory — read will fail. "
                      << "Ensure client_buffer_allocator_ returns host memory.";
@@ -2779,6 +3484,13 @@ RealClient::acquire_buffer_dummy(const std::string &key,
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
     auto &context = it->second;
+#ifdef USE_ASCEND_DIRECT
+    auto context_result = set_context_from_dummy_shms(
+        protocol, context.mapped_shms, "get_buffer");
+    if (!context_result) {
+        return tl::unexpected(context_result.error());
+    }
+#endif
 
     auto buffer_handle =
         get_buffer_internal(key, context.client_buffer_allocator);
@@ -2904,6 +3616,16 @@ RealClient::batch_acquire_buffer_dummy(const std::vector<std::string> &keys,
             r = tl::make_unexpected(ErrorCode::INVALID_PARAMS);
         return results;
     }
+#ifdef USE_ASCEND_DIRECT
+    auto context_result = set_context_from_dummy_shms(
+        protocol, ctx_it->second.mapped_shms, "batch_get_buffer");
+    if (!context_result) {
+        for (auto &r : results) {
+            r = tl::unexpected(context_result.error());
+        }
+        return results;
+    }
+#endif
 
     // Use batch_get_buffer_internal with dummy's allocator
     lock.unlock();
@@ -2973,6 +3695,7 @@ RealClient::batch_get_buffer_internal(
         QueryResult query_result;
         std::unique_ptr<BufferHandle> buffer_handle;
         std::vector<Slice> slices;
+        uint64_t total_size;
     };
     struct DiskKeyOp {
         size_t original_index;
@@ -2998,14 +3721,14 @@ RealClient::batch_get_buffer_internal(
             continue;
         }
 
-        auto query_result_values = query_results[i].value();
+        const auto &query_result_values = query_results[i].value();
         if (query_result_values.replicas.empty()) {
             LOG(ERROR) << "Empty replica list for key: " << key;
             continue;
         }
 
-        // Select best replica: prefer local MEMORY, then any MEMORY,
-        // then LOCAL_DISK, then DISK.
+        // Select best replica: prefer local MEMORY, any MEMORY, local NOF,
+        // any NOF, LOCAL_DISK, DFS, then DISK.
         const auto *best_replica =
             SelectBestReplica(query_result_values.replicas, local_endpoints);
         if (!best_replica) {
@@ -3043,15 +3766,16 @@ RealClient::batch_get_buffer_internal(
             continue;
         }
 
-        // DISK replicas use storage_backend::vector_read (file I/O) which
-        // can only write to CPU-addressable memory.  If the allocator ever
-        // returns device memory for DISK, the read will silently fail.
+        // File-backed replicas use file I/O which can only write to
+        // CPU-addressable memory. If the allocator ever returns device memory,
+        // the read will fail.
         auto runtime_accelerator =
             device::GetAcceleratorRegistry().RuntimeAccelerators();
-        if (replica.is_disk_replica() &&
+        if ((replica.is_disk_replica() || replica.is_dfs_replica()) &&
             runtime_accelerator.FindDeviceForPointer(buffer_handle->ptr())) {
             LOG(WARNING)
-                << "DISK replica for key '" << key
+                << (replica.is_dfs_replica() ? "DFS" : "DISK")
+                << " replica for key '" << key
                 << "' received a device pointer from the allocator; "
                 << "file I/O cannot write to GPU memory — read will fail. "
                 << "Ensure client_buffer_allocator_ returns host memory.";
@@ -3061,7 +3785,8 @@ RealClient::batch_get_buffer_internal(
             .key = key,
             .query_result = FilterQueryResult(query_result_values, replica),
             .buffer_handle = std::move(buffer_handle),
-            .slices = std::move(slices)});
+            .slices = std::move(slices),
+            .total_size = total_size});
     }
 
     if (valid_ops.empty() && disk_ops.empty()) {
@@ -3076,7 +3801,12 @@ RealClient::batch_get_buffer_internal(
         batch_keys.reserve(valid_ops.size());
         batch_query_results.reserve(valid_ops.size());
 
-        for (auto &op : valid_ops) {
+        // The slice map is keyed by string, so duplicate keys would collapse
+        // onto one destination. Transfer each unique key once (first
+        // occurrence as primary) and fan the verified bytes out locally.
+        const auto dedup = PlanDuplicateKeys(valid_ops);
+        for (const size_t op_idx : dedup.primaries) {
+            auto &op = valid_ops[op_idx];
             batch_keys.push_back(op.key);
             batch_query_results.push_back(op.query_result);
             batch_slices[op.key] = op.slices;
@@ -3085,16 +3815,48 @@ RealClient::batch_get_buffer_internal(
         auto batch_get_results =
             client_->BatchGet(batch_keys, batch_query_results, batch_slices);
 
-        // 4. Process results and create BufferHandles
-        for (size_t i = 0; i < valid_ops.size(); ++i) {
+        std::vector<tl::expected<int64_t, ErrorCode>> op_status(
+            valid_ops.size(), tl::make_unexpected(ErrorCode::INTERNAL_ERROR));
+        for (size_t i = 0; i < batch_get_results.size(); ++i) {
+            const size_t op_idx = dedup.primaries[i];
             if (batch_get_results[i]) {
+                op_status[op_idx] =
+                    static_cast<int64_t>(valid_ops[op_idx].total_size);
+            } else {
+                LOG(ERROR) << "BatchGet failed for key '"
+                           << valid_ops[op_idx].key
+                           << "': " << toString(batch_get_results[i].error());
+                op_status[op_idx] =
+                    tl::make_unexpected(batch_get_results[i].error());
+            }
+        }
+
+        std::vector<DuplicateFanOutJob> dup_jobs;
+        for (const auto &[dup_idx, primary_idx] : dedup.duplicates) {
+            const auto &dup_op = valid_ops[dup_idx];
+            const auto &primary_op = valid_ops[primary_idx];
+            dup_jobs.push_back(DuplicateFanOutJob{
+                .dup_result_index = dup_idx,
+                .primary_result_index = primary_idx,
+                .key = dup_op.key,
+                .dup_bytes = dup_op.total_size,
+                .primary_bytes = primary_op.total_size,
+                .copy = [dst = dup_op.slices, src = primary_op.slices,
+                         size = primary_op.total_size, key = dup_op.key]() {
+                    return CopySlicesMaybeDevice(
+                        dst, src, size, "duplicate fan-out, key: " + key);
+                }});
+        }
+        FanOutDuplicates(dup_jobs, op_status);
+
+        // 4. Process results and create BufferHandles. Duplicates copied from
+        // their primary above, before any handle is moved out here.
+        for (size_t i = 0; i < valid_ops.size(); ++i) {
+            if (op_status[i]) {
                 auto &op = valid_ops[i];
                 final_results[op.original_index] =
                     std::make_shared<BufferHandle>(
                         std::move(*op.buffer_handle));
-            } else {
-                LOG(ERROR) << "BatchGet failed for key '" << valid_ops[i].key
-                           << "': " << toString(batch_get_results[i].error());
             }
         }
     }
@@ -3105,8 +3867,11 @@ RealClient::batch_get_buffer_internal(
         std::unordered_map<std::string,
                            std::unordered_map<std::string, std::vector<Slice>>>
             offload_objects;
-        // Build key -> disk_ops index for result lookup
+        // Build key -> first disk_ops index for result lookup. The maps are
+        // keyed by string, so duplicate keys transfer once via the first
+        // occurrence and its verified bytes are fanned out locally below.
         std::unordered_map<std::string, size_t> disk_key_to_idx;
+        std::vector<std::pair<size_t, size_t>> duplicate_disk_ops;
 
         for (size_t idx = 0; idx < disk_ops.size(); ++idx) {
             auto &op = disk_ops[idx];
@@ -3122,14 +3887,21 @@ RealClient::batch_get_buffer_internal(
                 LOG(ERROR) << "No LOCAL_DISK replica found for key: " << op.key;
                 continue;
             }
+            auto [primary_it, first_seen] =
+                disk_key_to_idx.emplace(op.key, idx);
+            if (!first_seen) {
+                duplicate_disk_ops.emplace_back(idx, primary_it->second);
+                continue;
+            }
             const auto &replica = *replica_ptr;
             offload_objects[replica.get_local_disk_descriptor()
                                 .transport_endpoint]
                 .emplace(op.key, std::vector<Slice>{
                                      {op.buffer_handle->ptr(), op.total_size}});
-            disk_key_to_idx[op.key] = idx;
         }
 
+        std::vector<tl::expected<int64_t, ErrorCode>> op_status(
+            disk_ops.size(), tl::make_unexpected(ErrorCode::INTERNAL_ERROR));
         for (auto &[endpoint, objects] : offload_objects) {
             if (objects.empty()) continue;
             auto read_result =
@@ -3147,17 +3919,50 @@ RealClient::batch_get_buffer_internal(
                             << "SSD checksum verification failed for key '"
                             << key
                             << "': " << toString(checksum_result.error());
+                        op_status[idx_it->second] =
+                            tl::make_unexpected(checksum_result.error());
                         continue;
                     }
-                    final_results[op.original_index] =
-                        std::make_shared<BufferHandle>(
-                            std::move(*op.buffer_handle));
+                    op_status[idx_it->second] =
+                        static_cast<int64_t>(op.total_size);
                 } else {
                     LOG(ERROR) << "SSD read failed for key '" << key
                                << "': " << toString(read_result.error());
+                    op_status[idx_it->second] =
+                        tl::make_unexpected(read_result.error());
                 }
             }
         }
+
+        std::vector<DuplicateFanOutJob> dup_jobs;
+        for (const auto &[dup_idx, primary_idx] : duplicate_disk_ops) {
+            const auto &dup_op = disk_ops[dup_idx];
+            const auto &primary_op = disk_ops[primary_idx];
+            dup_jobs.push_back(DuplicateFanOutJob{
+                .dup_result_index = dup_idx,
+                .primary_result_index = primary_idx,
+                .key = dup_op.key,
+                .dup_bytes = dup_op.total_size,
+                .primary_bytes = primary_op.total_size,
+                .copy = [dst = dup_op.buffer_handle->ptr(),
+                         src = primary_op.buffer_handle->ptr(),
+                         size = primary_op.total_size, key = dup_op.key]() {
+                    return CopyMaybeDevice(
+                        dst, src, size, "duplicate SSD fan-out, key: " + key);
+                }});
+        }
+        FanOutDuplicates(dup_jobs, op_status);
+
+        // Duplicates copied from their primary above, before any handle is
+        // moved out here.
+        for (size_t idx = 0; idx < disk_ops.size(); ++idx) {
+            if (op_status[idx]) {
+                auto &op = disk_ops[idx];
+                final_results[op.original_index] =
+                    std::make_shared<BufferHandle>(
+                        std::move(*op.buffer_handle));
+            }
+        }
     }
 
     return final_results;
@@ -3240,7 +4045,13 @@ RealClient::resolve_writable_buffer_region(void *buffer) const {
             };
         }
     }
-    if (local_buffer_region_.has_value()) {
+    // A CUDA/UVA address can numerically fall inside the host-side local
+    // buffer range.  Only treat that range as an implicit writable region for
+    // host pointers; device destinations must be explicitly registered.
+    const bool is_device_pointer = device::GetAcceleratorRegistry()
+                                       .RuntimeAccelerators()
+                                       .FindDeviceForPointer(buffer) != nullptr;
+    if (!is_device_pointer && local_buffer_region_.has_value()) {
         const auto base =
             reinterpret_cast<uintptr_t>(local_buffer_region_->base);
         if (target >= base) {
@@ -3257,7 +4068,8 @@ RealClient::resolve_writable_buffer_region(void *buffer) const {
 
 tl::expected<RealClient::RangedReadMetadata, ErrorCode>
 RealClient::resolve_ranged_read_metadata(
-    const std::string &key, const QueryResultCache *query_result_cache) {
+    const std::string &key, const QueryResultCache *query_result_cache,
+    bool allow_query_refresh) {
     if (!client_) {
         LOG(ERROR) << "Client is not initialized";
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
@@ -3270,6 +4082,14 @@ RealClient::resolve_ranged_read_metadata(
             return build_ranged_read_metadata_from_query_result(key,
                                                                 cached->second);
         }
+        if (!allow_query_refresh) {
+            return tl::unexpected(cached == query_result_cache->end()
+                                      ? ErrorCode::INVALID_PARAMS
+                                      : ErrorCode::LEASE_EXPIRED);
+        }
+    }
+    if (!allow_query_refresh) {
+        return tl::unexpected(ErrorCode::INVALID_PARAMS);
     }
     return build_ranged_read_metadata_from_query_result(key,
                                                         client_->Query(key));
@@ -3290,7 +4110,8 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
             return tl::unexpected(ErrorCode::INVALID_PARAMS);
         }
         size = total_size;
-    } else if (size > total_size || src_offset > total_size - size) {
+    } else if (is_object_range_overflow(src_offset, size,
+                                        static_cast<size_t>(total_size))) {
         LOG(ERROR) << "Range overflow: src_offset=" << src_offset
                    << " + size=" << size << " > total=" << total_size;
         return tl::unexpected(ErrorCode::INVALID_PARAMS);
@@ -3321,13 +4142,16 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
             return static_cast<int64_t>(total_size);
         }
 
-        if (replica.is_disk_replica()) {
-            // DISK full read: local file I/O (vector_read) cannot write to
-            // GPU memory. Use temp CPU buffer, then scatter to dst.
+        if (replica.is_disk_replica() || replica.is_dfs_replica()) {
+            // File-backed full read: use a contiguous temp buffer, then
+            // scatter to the requested destination.
+            const char *replica_type =
+                replica.is_dfs_replica() ? "DFS" : "DISK";
             auto alloc_result = client_buffer_allocator_->allocate(total_size);
             if (!alloc_result) {
-                LOG(ERROR) << "Failed to allocate temp buffer for DISK full "
-                           << "read, key: " << key << ", size: " << total_size;
+                LOG(ERROR) << "Failed to allocate temp buffer for "
+                           << replica_type << " full read, key: " << key
+                           << ", size: " << total_size;
                 return tl::unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
             }
             BufferHandle tmp_handle(std::move(*alloc_result));
@@ -3337,14 +4161,15 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
                 FilterQueryResult(query_result, replica, verify_checksum);
             auto get_result = client_->Get(key, filtered_qr, tmp_slices);
             if (!get_result) {
-                LOG(ERROR) << "DISK Get failed for key: " << key
+                LOG(ERROR) << replica_type << " Get failed for key: " << key
                            << " with error: " << toString(get_result.error());
                 return tl::unexpected(get_result.error());
             }
             void *dst = static_cast<char *>(buffer) + dst_offset;
             const void *src = tmp_handle.ptr();
             if (auto r = scatter_host_to_maybe_device(
-                    dst, src, total_size, "DISK full read, key: " + key);
+                    dst, src, total_size,
+                    std::string(replica_type) + " full read, key: " + key);
                 !r) {
                 return tl::unexpected(r.error());
             }
@@ -3354,7 +4179,9 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
         auto runtime_accelerator =
             device::GetAcceleratorRegistry().RuntimeAccelerators();
         void *dst = static_cast<char *>(buffer) + dst_offset;
-        if (runtime_accelerator.FindDeviceForPointer(dst)) {
+        if (runtime_accelerator.FindDeviceForPointer(dst) &&
+            (!client_->CanUseLocalMemcpy(replica) ||
+             client_->IsHotCacheEnabled())) {
             if (!client_buffer_allocator_) {
                 LOG(ERROR) << "Client buffer allocator is not provided";
                 return tl::unexpected(ErrorCode::INVALID_PARAMS);
@@ -3400,10 +4227,10 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
         return static_cast<int64_t>(total_size);
     }
 
-    // Partial disk read: allocate temp CPU buffer, invoke read_op to
+    // Partial file-backed read: allocate temp buffer, invoke read_op to
     // fill it, then scatter [src_offset, src_offset+size) to dst.
     //
-    // buf_size controls how much to allocate / read.  DISK must use
+    // buf_size controls how much to allocate / read. DISK/DFS must use
     // total_size (allocateSlices requires full-object slices).
     // LOCAL_DISK can use src_offset + size (offload RPC transfers
     // sequentially from remote offset 0).
@@ -3412,7 +4239,8 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
             size_t buf_size) -> tl::expected<int64_t, ErrorCode> {
         auto alloc_result = client_buffer_allocator_->allocate(buf_size);
         if (!alloc_result) {
-            LOG(ERROR) << "Failed to allocate temp buffer for ranged disk "
+            LOG(ERROR) << "Failed to allocate temp buffer for ranged "
+                       << "file-backed "
                        << "read, key: " << key << ", size: " << buf_size;
             return tl::unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
         }
@@ -3423,7 +4251,7 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
         const void *src =
             static_cast<const char *>(tmp_handle.ptr()) + src_offset;
         if (auto r = scatter_host_to_maybe_device(
-                dst, src, size, "ranged disk read, key: " + key);
+                dst, src, size, "ranged file-backed read, key: " + key);
             !r) {
             return tl::unexpected(r.error());
         }
@@ -3431,12 +4259,27 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
     };
 
     if (replica.is_local_disk_replica()) {
+        const auto &endpoint =
+            replica.get_local_disk_descriptor().transport_endpoint;
+        void *dst = static_cast<char *>(buffer) + dst_offset;
+        std::unordered_map<std::string, std::vector<Slice>> objects{
+            {key, {{dst, size}}}};
+        if (can_use_pinned_restore_arena(endpoint, objects)) {
+            if (total_size > uint64_t(std::numeric_limits<int64_t>::max())) {
+                return tl::unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            const OffloadReadRange read_range{src_offset,
+                                              static_cast<int64_t>(total_size)};
+            auto result = batch_get_into_offload_object_internal(
+                endpoint, objects, &read_range);
+            if (!result) return tl::unexpected(result.error());
+            return static_cast<int64_t>(size);
+        }
+
         // LOCAL_DISK: offload RPC transfers sequentially from remote offset
         // 0, so we only need src_offset + size bytes (not total_size).
         return partial_disk_read(
             [&](void *tmp_buf) -> tl::expected<void, ErrorCode> {
-                const auto &endpoint =
-                    replica.get_local_disk_descriptor().transport_endpoint;
                 std::unordered_map<std::string, std::vector<Slice>> objects;
                 objects.emplace(
                     key, std::vector<Slice>{{static_cast<char *>(tmp_buf),
@@ -3447,9 +4290,10 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
             src_offset + size);
     }
 
-    if (replica.is_disk_replica()) {
-        // DISK: client_->Get + allocateSlices requires full-object slices,
+    if (replica.is_disk_replica() || replica.is_dfs_replica()) {
+        // DISK/DFS: client_->Get + allocateSlices requires full-object slices,
         // so we must allocate total_size.
+        const char *replica_type = replica.is_dfs_replica() ? "DFS" : "DISK";
         return partial_disk_read(
             [&](void *tmp_buf) -> tl::expected<void, ErrorCode> {
                 std::vector<mooncake::Slice> tmp_slices;
@@ -3459,7 +4303,7 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
                 auto get_result = client_->Get(key, filtered_qr, tmp_slices);
                 if (!get_result) {
                     LOG(ERROR)
-                        << "DISK Get failed for key: " << key
+                        << replica_type << " Get failed for key: " << key
                         << " with error: " << toString(get_result.error());
                     return tl::unexpected(get_result.error());
                 }
@@ -3469,14 +4313,16 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
     }
 
     if (!replica.is_memory_replica()) {
-        LOG(ERROR) << "ranged reads only support memory/disk replicas";
+        LOG(ERROR) << "ranged reads only support memory/file-backed replicas";
         return tl::unexpected(ErrorCode::INVALID_REPLICA);
     }
 
     auto runtime_accelerator =
         device::GetAcceleratorRegistry().RuntimeAccelerators();
     void *dst = static_cast<char *>(buffer) + dst_offset;
-    if (runtime_accelerator.FindDeviceForPointer(dst)) {
+    auto filtered_qr = FilterQueryResult(query_result, replica, false);
+    if (runtime_accelerator.FindDeviceForPointer(dst) &&
+        !client_->CanUseLocalMemcpy(replica)) {
         if (!client_buffer_allocator_) {
             LOG(ERROR) << "Client buffer allocator is not provided";
             return tl::unexpected(ErrorCode::INVALID_PARAMS);
@@ -3492,7 +4338,7 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
         tmp_slices.emplace_back(Slice{tmp_handle.ptr(), size});
 
         auto get_result =
-            client_->Get(key, query_result, tmp_slices, src_offset);
+            client_->Get(key, filtered_qr, tmp_slices, src_offset);
         if (!get_result) {
             return tl::unexpected(get_result.error());
         }
@@ -3507,7 +4353,7 @@ tl::expected<int64_t, ErrorCode> RealClient::execute_ranged_read(
     std::vector<Slice> slices;
     slices.emplace_back(Slice{dst, size});
 
-    auto get_result = client_->Get(key, query_result, slices, src_offset);
+    auto get_result = client_->Get(key, filtered_qr, slices, src_offset);
     if (!get_result) {
         return tl::unexpected(get_result.error());
     }
@@ -3555,7 +4401,7 @@ RealClient::get_into_ranges_internal(
     const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
     const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
     const std::vector<size_t> *buffer_capacities,
-    const QueryResultCache *query_result_cache) {
+    const QueryResultCache *query_result_cache, bool allow_query_refresh) {
     auto results = build_ranged_read_internal_error_results(
         buffers.size(), all_keys, all_dst_offsets, ErrorCode::INVALID_PARAMS);
     if (!client_) {
@@ -3589,10 +4435,13 @@ RealClient::get_into_ranges_internal(
         auto found = metadata_cache.find(key);
         if (found != metadata_cache.end()) return found->second;
         return metadata_cache
-            .emplace(key, resolve_ranged_read_metadata(key, query_result_cache))
+            .emplace(key, resolve_ranged_read_metadata(key, query_result_cache,
+                                                       allow_query_refresh))
             .first->second;
     };
 
+    auto runtime_accelerator =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
     struct ScatterLease {
         std::chrono::steady_clock::time_point expires_at;
         std::optional<ErrorCode> error;
@@ -3631,6 +4480,85 @@ RealClient::get_into_ranges_internal(
 
             const auto &metadata = metadata_result.value();
             if (metadata.replica.is_memory_replica()) {
+                if (client_->CanUseLocalMemcpy(metadata.replica) &&
+                    runtime_accelerator.FindDeviceForPointer(buffers[i])) {
+                    if (!allow_query_refresh) {
+                        for (size_t k = 0; k < range_results.size(); ++k) {
+                            if (dst_offsets[k] > capacities[i] ||
+                                sizes[k] > capacities[i] - dst_offsets[k] ||
+                                is_object_range_overflow(
+                                    src_offsets[k], sizes[k],
+                                    static_cast<size_t>(metadata.total_size))) {
+                                continue;
+                            }
+                            if (metadata.query_result.IsLeaseExpired()) {
+                                range_results[k] =
+                                    tl::unexpected(ErrorCode::LEASE_EXPIRED);
+                                continue;
+                            }
+                            // Even a full-object snapshot read must bypass
+                            // the key-based hot cache, which may hold a newer
+                            // version than the supplied replica descriptor.
+                            std::vector<Slice> slices{
+                                {static_cast<char *>(buffers[i]) +
+                                     dst_offsets[k],
+                                 sizes[k]}};
+                            auto query_result = FilterQueryResult(
+                                metadata.query_result, metadata.replica, false);
+                            auto read = client_->Get(keys[j], query_result,
+                                                     slices, src_offsets[k]);
+                            range_results[k] =
+                                read
+                                    ? tl::expected<int64_t, ErrorCode>(sizes[k])
+                                    : tl::unexpected(read.error());
+                        }
+                        continue;
+                    }
+                    // Planning cache entries may be close to expiry. Renew and
+                    // reselect the replica before copying into device memory.
+                    auto refresh_result = resolve_ranged_read_metadata(keys[j]);
+                    if (!refresh_result) {
+                        std::fill(range_results.begin(), range_results.end(),
+                                  tl::unexpected(refresh_result.error()));
+                        continue;
+                    }
+                    std::optional<RangedReadMetadata> refreshed_metadata;
+                    refreshed_metadata.emplace(std::move(*refresh_result));
+                    auto lease_refresh_at =
+                        [](const RangedReadMetadata &value) {
+                            const auto now = std::chrono::steady_clock::now();
+                            return now +
+                                   (value.query_result.lease_timeout - now) / 2;
+                        };
+                    auto refresh_at = lease_refresh_at(*refreshed_metadata);
+                    for (size_t k = 0; k < range_results.size(); ++k) {
+                        // Renew halfway through the remaining lease in long
+                        // batches.
+                        const size_t dst_offset = dst_offsets[k];
+                        if (dst_offset > capacities[i] ||
+                            sizes[k] > capacities[i] - dst_offset) {
+                            continue;
+                        }
+                        if (std::chrono::steady_clock::now() >= refresh_at) {
+                            auto next_refresh_result =
+                                resolve_ranged_read_metadata(keys[j]);
+                            if (!next_refresh_result) {
+                                std::fill(range_results.begin() + k,
+                                          range_results.end(),
+                                          tl::unexpected(
+                                              next_refresh_result.error()));
+                                break;
+                            }
+                            refreshed_metadata.emplace(
+                                std::move(*next_refresh_result));
+                            refresh_at = lease_refresh_at(*refreshed_metadata);
+                        }
+                        range_results[k] = execute_ranged_read(
+                            keys[j], buffers[i], dst_offset, src_offsets[k],
+                            sizes[k], *refreshed_metadata, false, false);
+                    }
+                    continue;
+                }
                 const auto &handle =
                     metadata.replica.get_memory_descriptor().buffer_descriptor;
                 auto [lease_it, inserted] = scatter_leases.try_emplace(keys[j]);
@@ -3677,6 +4605,10 @@ RealClient::get_into_ranges_internal(
                 range_results[k] = execute_ranged_read(
                     keys[j], buffers[i], dst_offset, src_offsets[k], sizes[k],
                     metadata, false, false);
+                if (!allow_query_refresh && range_results[k] &&
+                    metadata.query_result.IsLeaseExpired()) {
+                    range_results[k] = tl::unexpected(ErrorCode::LEASE_EXPIRED);
+                }
             }
         }
     }
@@ -3712,7 +4644,7 @@ RealClient::get_into_ranges_internal(
     };
 
     // Planning may consume most of a short lease; renew before submission.
-    if (!scatter_leases.empty()) refresh_leases();
+    if (allow_query_refresh && !scatter_leases.empty()) refresh_leases();
     auto operation = client_->SubmitScatter(memory_transfers);
     if (!operation.has_value()) {
         const auto failure =
@@ -3725,7 +4657,9 @@ RealClient::get_into_ranges_internal(
     }
 
     while (true) {
-        const auto delay = next_refresh_delay();
+        const auto delay = allow_query_refresh
+                               ? next_refresh_delay()
+                               : std::chrono::nanoseconds::max();
         const auto status = delay == std::chrono::nanoseconds::max()
                                 ? operation->wait()
                                 : operation->waitFor(delay);
@@ -3735,6 +4669,19 @@ RealClient::get_into_ranges_internal(
     return results;
 }
 
+std::vector<std::vector<std::vector<int64_t>>>
+RealClient::get_into_ranges_from_snapshot(
+    const std::vector<void *> &buffers,
+    const std::vector<std::vector<std::string>> &all_keys,
+    const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+    const QueryResultCache &query_result_cache) {
+    return convert_ranged_read_results(get_into_ranges_internal(
+        buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes, nullptr,
+        &query_result_cache, false));
+}
+
 std::vector<std::vector<std::vector<int64_t>>> RealClient::get_into_ranges(
     const std::vector<void *> &buffers,
     const std::vector<std::vector<std::string>> &all_keys,
@@ -4503,6 +5450,22 @@ std::vector<tl::expected<void, ErrorCode>>
 RealClient::batch_put_from_cuda_ipc_dummy_helper(
     const std::vector<CudaIpcWriteRequest> &requests,
     const ReplicateConfig &config, const UUID &client_id) {
+    return batch_write_from_cuda_ipc_dummy_helper(requests, config, client_id,
+                                                  false);
+}
+
+std::vector<tl::expected<void, ErrorCode>>
+RealClient::batch_upsert_from_cuda_ipc_dummy_helper(
+    const std::vector<CudaIpcWriteRequest> &requests,
+    const ReplicateConfig &config, const UUID &client_id) {
+    return batch_write_from_cuda_ipc_dummy_helper(requests, config, client_id,
+                                                  true);
+}
+
+std::vector<tl::expected<void, ErrorCode>>
+RealClient::batch_write_from_cuda_ipc_dummy_helper(
+    const std::vector<CudaIpcWriteRequest> &requests,
+    const ReplicateConfig &config, const UUID &client_id, bool is_upsert) {
     std::shared_lock<std::shared_mutex> lock(dummy_client_mutex_);
     auto it = shm_contexts_.find(client_id);
     if (it == shm_contexts_.end()) {
@@ -4564,8 +5527,12 @@ RealClient::batch_put_from_cuda_ipc_dummy_helper(
         }
     }
 
+    if (is_upsert) {
+        return batch_upsert_from_multi_buffers_internal(
+            keys, all_buffers, all_sizes, config, true);
+    }
     return batch_put_from_multi_buffers_internal(keys, all_buffers, all_sizes,
-                                                 config);
+                                                 config, true);
 }
 
 std::vector<tl::expected<int64_t, ErrorCode>>
@@ -4582,60 +5549,59 @@ RealClient::batch_get_into_cuda_ipc_dummy_helper(
 
     std::vector<tl::expected<int64_t, ErrorCode>> results(
         requests.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
-    std::vector<device::CudaIpcBufferMapping> mappings;
-    std::vector<void *> buffers;
-    std::vector<std::vector<std::string>> all_keys;
-    std::vector<std::vector<std::vector<size_t>>> all_dst_offsets;
-    std::vector<std::vector<std::vector<size_t>>> all_src_offsets;
-    std::vector<std::vector<std::vector<size_t>>> all_sizes;
-    std::vector<size_t> buffer_capacities;
-    std::vector<size_t> original_indices;
-    mappings.reserve(requests.size());
-    buffers.reserve(requests.size());
-    all_keys.reserve(requests.size());
-    all_dst_offsets.reserve(requests.size());
-    all_src_offsets.reserve(requests.size());
-    all_sizes.reserve(requests.size());
-    buffer_capacities.reserve(requests.size());
-    original_indices.reserve(requests.size());
 
     for (size_t i = 0; i < requests.size(); ++i) {
         const auto &request = requests[i];
+        if (request.size == 0) {
+            results[i] = 0;
+            continue;
+        }
         auto mapping = device::CudaIpcBufferMapping::Open(request.destination);
         if (!mapping) {
             results[i] = tl::unexpected(mapping.error());
             continue;
         }
-        mappings.push_back(std::move(*mapping));
-        buffers.push_back(mappings.back().ptr());
-        all_keys.push_back({request.key});
-        all_dst_offsets.push_back({{0}});
-        all_src_offsets.push_back(
-            {{static_cast<size_t>(request.source_offset)}});
-        all_sizes.push_back({{static_cast<size_t>(request.size)}});
-        buffer_capacities.push_back(static_cast<size_t>(request.size));
-        original_indices.push_back(i);
+        results[i] = get_into_range_internal(
+            request.key, mapping->ptr(), 0,
+            static_cast<size_t>(request.source_offset),
+            static_cast<size_t>(request.size), false, false);
     }
+    return results;
+}
 
-    if (buffers.empty()) {
-        return results;
+std::vector<tl::expected<void, ErrorCode>>
+RealClient::batch_upsert_from_multi_buffers_dummy_helper(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<uint64_t>> &dummy_all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const ReplicateConfig &config, int32_t device_id, const UUID &client_id) {
+#ifdef USE_ASCEND_DIRECT
+    if (!ContextManager::getInstance().setCurrentContextByPhysicalId(
+            device_id)) {
+        LOG(ERROR) << "Failed to set context for physical device " << device_id;
+        return std::vector<tl::expected<void, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
     }
+#endif
 
-    auto range_results = get_into_ranges_internal(
-        buffers, all_keys, all_dst_offsets, all_src_offsets, all_sizes,
-        &buffer_capacities, nullptr);
-    for (size_t i = 0; i < original_indices.size(); ++i) {
-        if (i < range_results.size() && range_results[i].size() == 1 &&
-            range_results[i][0].size() == 1) {
-            results[original_indices[i]] = range_results[i][0][0];
-        } else {
-            LOG(ERROR) << "Invalid cuda ipc tensor read result shape for key "
-                       << requests[original_indices[i]].key;
-            results[original_indices[i]] =
-                tl::unexpected(ErrorCode::INTERNAL_ERROR);
-        }
+    std::shared_lock<std::shared_mutex> lock(dummy_client_mutex_);
+    auto it = shm_contexts_.find(client_id);
+    if (it == shm_contexts_.end()) {
+        LOG(ERROR) << "client_id=" << client_id << ", error=shm_not_mapped";
+        return std::vector<tl::expected<void, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
     }
-    return results;
+    auto &context = it->second;
+
+    auto real_buffers_result = map_dummy_nested_addrs_to_real_ptrs(
+        context, dummy_all_buffers, all_sizes, keys, client_id);
+    if (!real_buffers_result) {
+        return std::vector<tl::expected<void, ErrorCode>>(
+            keys.size(), tl::unexpected(real_buffers_result.error()));
+    }
+
+    return batch_upsert_from_multi_buffers_internal(
+        keys, real_buffers_result.value(), all_sizes, config);
 }
 
 std::vector<tl::expected<int64_t, ErrorCode>>
@@ -4710,6 +5676,41 @@ RealClient::get_into_ranges_shm_helper(
     const std::map<std::string, CachedQueryResultResponse>
         &cached_query_results,
     int32_t device_id, const UUID &client_id) {
+    return get_into_ranges_shm_helper_impl(
+        dummy_buffers, std::vector<size_t>(dummy_buffers.size()), nullptr,
+        all_keys, all_dst_offsets, all_src_offsets, all_sizes,
+        cached_query_results, device_id, client_id);
+}
+
+std::vector<std::vector<std::vector<tl::expected<int64_t, ErrorCode>>>>
+RealClient::get_into_ranges_staged_shm_helper(
+    const std::vector<uint64_t> &dummy_buffers,
+    const std::vector<size_t> &dummy_buffer_sizes,
+    const std::vector<std::vector<std::string>> &all_keys,
+    const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+    const std::map<std::string, CachedQueryResultResponse>
+        &cached_query_results,
+    int32_t device_id, const UUID &client_id) {
+    return get_into_ranges_shm_helper_impl(
+        dummy_buffers, dummy_buffer_sizes, &dummy_buffer_sizes, all_keys,
+        all_dst_offsets, all_src_offsets, all_sizes, cached_query_results,
+        device_id, client_id);
+}
+
+std::vector<std::vector<std::vector<tl::expected<int64_t, ErrorCode>>>>
+RealClient::get_into_ranges_shm_helper_impl(
+    const std::vector<uint64_t> &dummy_buffers,
+    const std::vector<size_t> &dummy_buffer_sizes,
+    const std::vector<size_t> *buffer_capacities,
+    const std::vector<std::vector<std::string>> &all_keys,
+    const std::vector<std::vector<std::vector<size_t>>> &all_dst_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_src_offsets,
+    const std::vector<std::vector<std::vector<size_t>>> &all_sizes,
+    const std::map<std::string, CachedQueryResultResponse>
+        &cached_query_results,
+    int32_t device_id, const UUID &client_id) {
 #ifdef USE_ASCEND_DIRECT
     if (!ContextManager::getInstance().setCurrentContextByPhysicalId(
             device_id)) {
@@ -4732,10 +5733,10 @@ RealClient::get_into_ranges_shm_helper(
             ErrorCode::INVALID_PARAMS);
     }
 
-    std::vector<size_t> capacities;
+    std::vector<size_t> mapped_capacities;
     auto real_buffers_result = map_dummy_addrs_to_real_ptrs(
-        it->second, dummy_buffers, std::vector<size_t>(dummy_buffers.size()),
-        client_id, &capacities);
+        it->second, dummy_buffers, dummy_buffer_sizes, client_id,
+        buffer_capacities == nullptr ? &mapped_capacities : nullptr);
     if (!real_buffers_result) {
         return build_ranged_read_internal_error_results(
             dummy_buffers.size(), all_keys, all_dst_offsets,
@@ -4744,9 +5745,13 @@ RealClient::get_into_ranges_shm_helper(
 
     auto query_result_cache =
         build_query_result_cache_from_cached_results(cached_query_results);
+    const std::vector<size_t> *capacities = &mapped_capacities;
+    if (buffer_capacities != nullptr) {
+        capacities = buffer_capacities;
+    }
     return get_into_ranges_internal(
         real_buffers_result.value(), all_keys, all_dst_offsets, all_src_offsets,
-        all_sizes, &capacities,
+        all_sizes, capacities,
         query_result_cache.empty() ? nullptr : &query_result_cache);
 }
 
@@ -4754,6 +5759,36 @@ std::vector<tl::expected<int64_t, ErrorCode>>
 RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
                                     const std::vector<void *> &buffers,
                                     const std::vector<size_t> &sizes) {
+    if (!client_) {
+        LOG(ERROR) << "Client is not initialized";
+        return std::vector<tl::expected<int64_t, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    }
+    if (keys.size() != buffers.size() || keys.size() != sizes.size()) {
+        LOG(ERROR) << "Input vector sizes mismatch: keys=" << keys.size()
+                   << ", buffers=" << buffers.size()
+                   << ", sizes=" << sizes.size();
+        return std::vector<tl::expected<int64_t, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    }
+    if (keys.empty()) {
+        return {};
+    }
+
+    const auto query_results = client_->BatchQuery(keys);
+    return batch_get_into_internal(
+        keys, buffers, sizes, query_results,
+        [this](const std::string &endpoint, LocalDiskOffloadObjects &objects) {
+            return batch_get_into_offload_object_internal(endpoint, objects);
+        });
+}
+
+std::vector<tl::expected<int64_t, ErrorCode>>
+RealClient::batch_get_into_internal(
+    const std::vector<std::string> &keys, const std::vector<void *> &buffers,
+    const std::vector<size_t> &sizes,
+    const std::vector<tl::expected<QueryResult, ErrorCode>> &query_results,
+    const LocalDiskOffloadReader &local_disk_reader) {
     [[maybe_unused]] auto start_time = std::chrono::steady_clock::now();
     // Validate preconditions
     if (!client_) {
@@ -4762,10 +5797,12 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
             keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
     }
 
-    if (keys.size() != buffers.size() || keys.size() != sizes.size()) {
+    if (keys.size() != buffers.size() || keys.size() != sizes.size() ||
+        keys.size() != query_results.size()) {
         LOG(ERROR) << "Input vector sizes mismatch: keys=" << keys.size()
                    << ", buffers=" << buffers.size()
-                   << ", sizes=" << sizes.size();
+                   << ", sizes=" << sizes.size()
+                   << ", query_results=" << query_results.size();
         return std::vector<tl::expected<int64_t, ErrorCode>>(
             keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
     }
@@ -4777,9 +5814,6 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         return results;
     }
 
-    // Query metadata for all keys
-    const auto query_results = client_->BatchQuery(keys);
-
     // Process each key individually and prepare for batch transfer
     struct ValidKeyInfo {
         std::string key;
@@ -4788,16 +5822,30 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         std::vector<Slice> slices;
         uint64_t total_size;
     };
+    struct ValidLocalDiskKeyInfo {
+        std::string key;
+        size_t original_index;
+        QueryResult query_result;
+        Replica::Descriptor replica;
+        std::vector<Slice> slices;
+        uint64_t total_size;
+    };
     struct DiskKeyInfo {
         std::string key;
         size_t original_index;
         QueryResult query_result;
+        Replica::Descriptor replica;
         void *dst_buffer;
         uint64_t total_size;
     };
 
     std::vector<ValidKeyInfo> valid_operations;
-    std::unordered_map<std::string, ValidKeyInfo> valid_local_disk_operations;
+    std::unordered_map<std::string, ValidLocalDiskKeyInfo>
+        valid_local_disk_operations;
+    // Fan-out jobs for duplicate LOCAL_DISK keys, built during the scan
+    // below; the copies run after the SSD reads, from the first
+    // occurrence's verified buffer.
+    std::vector<DuplicateFanOutJob> local_disk_dup_jobs;
     std::vector<DiskKeyInfo> disk_operations;
     valid_operations.reserve(num_keys);
 
@@ -4818,15 +5866,15 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         }
 
         // Validate replica list
-        auto query_result_values = query_results[i].value();
+        const auto &query_result_values = query_results[i].value();
         if (query_result_values.replicas.empty()) {
             LOG(ERROR) << "Empty replica list for key: " << key;
             results[i] = tl::unexpected(ErrorCode::INVALID_REPLICA);
             continue;
         }
 
-        // Select best replica: prefer local MEMORY, then any MEMORY,
-        // then LOCAL_DISK, then DISK.
+        // Select best replica: prefer local MEMORY, any MEMORY, local NOF,
+        // any NOF, LOCAL_DISK, DFS, then DISK.
         const auto *best_replica =
             SelectBestReplica(query_result_values.replicas, local_endpoints);
         if (!best_replica) {
@@ -4849,31 +5897,54 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         }
 
         if (replica.is_local_disk_replica()) {
+            if (valid_local_disk_operations.count(key)) {
+                // Duplicate key: the first occurrence stays the transfer
+                // primary; its verified bytes are fanned out to this
+                // duplicate's buffer after the SSD reads below.
+                const auto &primary = valid_local_disk_operations.at(key);
+                local_disk_dup_jobs.push_back(DuplicateFanOutJob{
+                    .dup_result_index = i,
+                    .primary_result_index = primary.original_index,
+                    .key = key,
+                    .dup_bytes = total_size,
+                    .primary_bytes = primary.total_size,
+                    .copy = [dst = buffers[i],
+                             src = buffers[primary.original_index],
+                             size = total_size, key]() {
+                        return CopyMaybeDevice(
+                            dst, src, size,
+                            "duplicate SSD fan-out, key: " + key);
+                    }});
+                results[i] = static_cast<int64_t>(total_size);
+                continue;
+            }
             std::vector<Slice> key_slices;
             allocateSlices(key_slices, replica, buffers[i]);
             valid_local_disk_operations.emplace(
-                key,
-                ValidKeyInfo{.key = key,
-                             .original_index = i,
-                             .query_result = std::move(query_result_values),
-                             .slices = std::move(key_slices),
-                             .total_size = total_size});
+                key, ValidLocalDiskKeyInfo{
+                         .key = key,
+                         .original_index = i,
+                         .query_result = std::move(query_result_values),
+                         .replica = replica,
+                         .slices = std::move(key_slices),
+                         .total_size = total_size});
             results[i] = static_cast<int64_t>(total_size);
             continue;
         }
-        if (replica.is_disk_replica()) {
-            // DISK: file I/O (vector_read) cannot write to user GPU buffer.
-            // Defer — allocate CPU temp buffer, BatchGet, then scatter.
+        if (replica.is_disk_replica() || replica.is_dfs_replica()) {
+            // File-backed replicas cannot safely read directly into arbitrary
+            // user buffers. Use a contiguous temp buffer, then scatter.
             disk_operations.emplace_back(
                 DiskKeyInfo{.key = key,
                             .original_index = i,
                             .query_result = std::move(query_result_values),
+                            .replica = replica,
                             .dst_buffer = buffers[i],
                             .total_size = total_size});
             results[i] = static_cast<int64_t>(total_size);
             continue;
         }
-        // MEMORY: RDMA directly to user buffer.
+        // MEMORY / NOF: RDMA directly to user buffer.
         std::vector<Slice> key_slices;
         allocateSlices(key_slices, replica, buffers[i]);
         valid_operations.push_back(
@@ -4901,7 +5972,12 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
     batch_keys.reserve(valid_operations.size());
     batch_query_results.reserve(valid_operations.size());
 
-    for (const auto &op : valid_operations) {
+    // The slice map is keyed by string, so duplicate keys would collapse onto
+    // one destination. Transfer each unique key once (first occurrence as
+    // primary) and fan the verified bytes out to duplicate buffers locally.
+    const auto dedup = PlanDuplicateKeys(valid_operations);
+    for (const size_t op_idx : dedup.primaries) {
+        const auto &op = valid_operations[op_idx];
         batch_keys.push_back(op.key);
         batch_query_results.push_back(op.query_result);
         batch_slices[op.key] = op.slices;
@@ -4913,7 +5989,7 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
 
         // Process transfer results
         for (size_t j = 0; j < batch_get_results.size(); ++j) {
-            const auto &op = valid_operations[j];
+            const auto &op = valid_operations[dedup.primaries[j]];
 
             if (!batch_get_results[j]) {
                 const auto error = batch_get_results[j].error();
@@ -4922,9 +5998,27 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
                 results[op.original_index] = tl::unexpected(error);
             }
         }
+
+        std::vector<DuplicateFanOutJob> dup_jobs;
+        for (const auto &[dup_idx, primary_idx] : dedup.duplicates) {
+            const auto &dup_op = valid_operations[dup_idx];
+            const auto &primary_op = valid_operations[primary_idx];
+            dup_jobs.push_back(DuplicateFanOutJob{
+                .dup_result_index = dup_op.original_index,
+                .primary_result_index = primary_op.original_index,
+                .key = dup_op.key,
+                .dup_bytes = dup_op.total_size,
+                .primary_bytes = primary_op.total_size,
+                .copy = [dst = dup_op.slices, src = primary_op.slices,
+                         size = dup_op.total_size, key = dup_op.key]() {
+                    return CopySlicesMaybeDevice(
+                        dst, src, size, "duplicate fan-out, key: " + key);
+                }});
+        }
+        FanOutDuplicates(dup_jobs, results);
     }
 
-    // ---- DISK replicas: BatchGet into CPU temp buffers, then scatter ----
+    // ---- File-backed replicas: BatchGet into temp buffers, then scatter ----
     if (!disk_operations.empty()) {
         std::vector<std::string> disk_batch_keys;
         std::vector<QueryResult> disk_batch_qrs;
@@ -4932,28 +6026,21 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         std::vector<size_t> disk_batch_indices;
         std::unordered_map<std::string, std::unique_ptr<BufferHandle>>
             disk_temp_handles;
+        // Duplicate keys share the first occurrence's temp buffer; the
+        // verified bytes are scattered into every duplicate destination
+        // after the batch read.
+        const auto disk_dedup = PlanDuplicateKeys(disk_operations);
 
-        for (size_t di = 0; di < disk_operations.size(); ++di) {
+        for (const size_t di : disk_dedup.primaries) {
             auto &op = disk_operations[di];
-            // Find the DISK replica.
-            const Replica::Descriptor *replica_ptr = nullptr;
-            for (const auto &r : op.query_result.replicas) {
-                if (r.is_disk_replica()) {
-                    replica_ptr = &r;
-                    break;
-                }
-            }
-            if (!replica_ptr) {
-                LOG(ERROR) << "No DISK replica found for key: " << op.key;
-                results[op.original_index] =
-                    tl::unexpected(ErrorCode::INVALID_REPLICA);
-                continue;
-            }
+            const auto &replica = op.replica;
+            const char *replica_type =
+                replica.is_dfs_replica() ? "DFS" : "DISK";
             auto alloc_result =
                 client_buffer_allocator_->allocate(op.total_size);
             if (!alloc_result) {
-                LOG(ERROR) << "Failed to allocate temp buffer for DISK "
-                           << "read, key: " << op.key
+                LOG(ERROR) << "Failed to allocate temp buffer for "
+                           << replica_type << " read, key: " << op.key
                            << ", size: " << op.total_size;
                 results[op.original_index] =
                     tl::unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
@@ -4962,10 +6049,10 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
             auto handle =
                 std::make_unique<BufferHandle>(std::move(*alloc_result));
             std::vector<Slice> disk_slices;
-            allocateSlices(disk_slices, *replica_ptr, handle->ptr());
+            allocateSlices(disk_slices, replica, handle->ptr());
             disk_batch_keys.push_back(op.key);
             disk_batch_qrs.push_back(
-                FilterQueryResult(op.query_result, *replica_ptr));
+                FilterQueryResult(op.query_result, replica));
             disk_batch_slices[op.key] = std::move(disk_slices);
             disk_batch_indices.push_back(di);
             disk_temp_handles.emplace(op.key, std::move(handle));
@@ -4979,9 +6066,12 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
                 const auto &key = disk_batch_keys[di];
                 auto &op = disk_operations[disk_batch_indices[di]];
                 auto handle_it = disk_temp_handles.find(key);
+                const char *replica_type =
+                    op.replica.is_dfs_replica() ? "DFS" : "DISK";
                 if (!disk_results[di]) {
-                    LOG(ERROR) << "DISK BatchGet failed for key '" << key
-                               << "': " << toString(disk_results[di].error());
+                    LOG(ERROR)
+                        << replica_type << " BatchGet failed for key '" << key
+                        << "': " << toString(disk_results[di].error());
                     results[op.original_index] =
                         tl::unexpected(disk_results[di].error());
                     continue;
@@ -4989,12 +6079,40 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
                 if (auto r = scatter_host_to_maybe_device(
                         op.dst_buffer,
                         static_cast<char *>(handle_it->second->ptr()),
-                        op.total_size, "DISK read, key: " + key);
+                        op.total_size,
+                        std::string(replica_type) + " read, key: " + key);
                     !r) {
                     results[op.original_index] = tl::make_unexpected(r.error());
                 }
             }
         }
+
+        std::vector<DuplicateFanOutJob> dup_jobs;
+        for (const auto &[dup_di, primary_di] : disk_dedup.duplicates) {
+            const auto &dup_op = disk_operations[dup_di];
+            const auto &primary_op = disk_operations[primary_di];
+            dup_jobs.push_back(DuplicateFanOutJob{
+                .dup_result_index = dup_op.original_index,
+                .primary_result_index = primary_op.original_index,
+                .key = dup_op.key,
+                .dup_bytes = dup_op.total_size,
+                .primary_bytes = primary_op.total_size,
+                .copy = [&disk_temp_handles, dst = dup_op.dst_buffer,
+                         size = dup_op.total_size, key = dup_op.key,
+                         is_dfs = dup_op.replica.is_dfs_replica()]()
+                    -> tl::expected<void, ErrorCode> {
+                    auto handle_it = disk_temp_handles.find(key);
+                    if (handle_it == disk_temp_handles.end()) {
+                        return tl::make_unexpected(
+                            ErrorCode::NO_AVAILABLE_HANDLE);
+                    }
+                    return CopyMaybeDevice(
+                        dst, handle_it->second->ptr(), size,
+                        std::string(is_dfs ? "DFS" : "DISK") +
+                            " duplicate read, key: " + key);
+                }});
+        }
+        FanOutDuplicates(dup_jobs, results);
     }
 
     // Prepare batch transfer data structures
@@ -5003,21 +6121,7 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         offload_objects;
 
     for (const auto &op_it : valid_local_disk_operations) {
-        // Find the LOCAL_DISK replica from the list — replicas may be in
-        // any order from Master.
-        const Replica::Descriptor *replica_ptr = nullptr;
-        for (const auto &r : op_it.second.query_result.replicas) {
-            if (r.is_local_disk_replica()) {
-                replica_ptr = &r;
-                break;
-            }
-        }
-        if (!replica_ptr) {
-            LOG(ERROR) << "No LOCAL_DISK replica found for key: "
-                       << op_it.first;
-            continue;
-        }
-        const auto &replica = *replica_ptr;
+        const auto &replica = op_it.second.replica;
         auto [store_segment_it, _] = offload_objects.try_emplace(
             replica.get_local_disk_descriptor().transport_endpoint);
         store_segment_it->second.emplace(op_it.first, op_it.second.slices);
@@ -5028,7 +6132,7 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         std::chrono::steady_clock::now();
     for (auto &offload_objects_it : offload_objects) {
         offload_object_count += offload_objects_it.second.size();
-        auto batch_get_offload_result = batch_get_into_offload_object_internal(
+        auto batch_get_offload_result = local_disk_reader(
             offload_objects_it.first, offload_objects_it.second);
         if (!batch_get_offload_result) {
             LOG(ERROR) << "Batch get store object failed with error: "
@@ -5053,6 +6157,9 @@ RealClient::batch_get_into_internal(const std::vector<std::string> &keys,
         }
     }
 
+    // Fan verified LOCAL_DISK primary bytes out to duplicate destinations.
+    FanOutDuplicates(local_disk_dup_jobs, results);
+
     auto end_time = std::chrono::steady_clock::now();
     [[maybe_unused]] auto elapsed_time =
         std::chrono::duration_cast<std::chrono::microseconds>(end_time -
@@ -5087,6 +6194,32 @@ std::vector<tl::expected<bool, ErrorCode>> RealClient::batchIsExist_internal(
     return client_->BatchIsExist(keys);
 }
 
+tl::expected<bool, ErrorCode> RealClient::probeKey_internal(
+    const std::string &key) {
+    if (!client_) {
+        LOG(ERROR) << "Client is not initialized";
+        return tl::unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return client_->ProbeKey(key);
+}
+
+std::vector<tl::expected<bool, ErrorCode>> RealClient::batchProbeKey_internal(
+    const std::vector<std::string> &keys) {
+    if (!client_) {
+        LOG(ERROR) << "Client is not initialized";
+        return std::vector<tl::expected<bool, ErrorCode>>(
+            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    }
+
+    if (keys.empty()) {
+        LOG(WARNING) << "Empty keys vector provided to batchProbeKey_internal";
+        return std::vector<tl::expected<bool, ErrorCode>>();
+    }
+
+    // Call client BatchProbeKey and return the vector<expected> directly
+    return client_->BatchProbeKey(keys);
+}
+
 int RealClient::put_from_with_metadata(const std::string &key, void *buffer,
                                        void *metadata_buffer, size_t size,
                                        size_t metadata_size,
@@ -5103,7 +6236,7 @@ int RealClient::put_from_with_metadata(const std::string &key, void *buffer,
         return -1;
     }
 
-    if (size == 0) {
+    if (size == 0 && metadata_size == 0) {
         LOG(WARNING) << "Attempting to put empty data for key: " << key;
         return 0;
     }
@@ -5131,11 +6264,20 @@ std::vector<int> RealClient::batch_put_from_multi_buffers(
     const std::vector<std::vector<void *>> &all_buffers,
     const std::vector<std::vector<size_t>> &sizes,
     const ReplicateConfig &config) {
+    return batch_put_from_multi_buffers(keys, all_buffers, sizes, config,
+                                        false);
+}
+
+std::vector<int> RealClient::batch_put_from_multi_buffers(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &sizes,
+    const ReplicateConfig &config, bool stage_nonlocal) {
     auto internal_results =
         execute_timed_operation<std::vector<tl::expected<void, ErrorCode>>>(
             [&]() {
-                return batch_put_from_multi_buffers_internal(keys, all_buffers,
-                                                             sizes, config);
+                return batch_put_from_multi_buffers_internal(
+                    keys, all_buffers, sizes, config, stage_nonlocal);
             },
             [](const auto &) { return true; },
             [&](uint64_t latency_us, const auto &ret) {
@@ -5149,51 +6291,928 @@ std::vector<int> RealClient::batch_put_from_multi_buffers(
                     "batch_put_from_multi_buffers",
                     sum_successful_nested_sizes(py_results, sizes), latency_us);
             });
-    std::vector<int> results;
-    results.reserve(internal_results.size());
+    return ToPyResults(internal_results);
+}
 
-    for (const auto &result : internal_results) {
-        results.push_back(to_py_ret(result));
+std::vector<int> RealClient::batch_get_session_start(
+    const std::vector<std::string> &keys) {
+    std::vector<int> results(
+        keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    if (!client_) {
+        LOG(ERROR) << "Client is not initialized";
+        return results;
+    }
+    if (keys.empty()) {
+        return {};
+    }
+
+    // Master interaction only here: query replicas + lease.
+    const auto query_results = client_->BatchQuery(keys);
+    if (query_results.size() != keys.size()) {
+        LOG(ERROR) << "Session query result size mismatch: expected="
+                   << keys.size() << ", got=" << query_results.size();
+        return std::vector<int>(keys.size(),
+                                static_cast<int>(toInt(ErrorCode::RPC_FAIL)));
     }
+    auto local_endpoints = client_->GetLocalEndpoints();
 
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    for (size_t i = 0; i < keys.size(); ++i) {
+        if (!query_results[i]) {
+            results[i] = static_cast<int>(toInt(query_results[i].error()));
+            get_sessions_.erase(keys[i]);
+            continue;
+        }
+
+        const auto &query_result = query_results[i].value();
+        if (query_result.IsLeaseExpired()) {
+            results[i] = static_cast<int>(toInt(ErrorCode::LEASE_EXPIRED));
+            get_sessions_.erase(keys[i]);
+            continue;
+        }
+
+        const auto *replica =
+            SelectSessionReplica(query_result.replicas, local_endpoints);
+        if (!replica) {
+            LOG(ERROR) << "No supported complete replica for key: " << keys[i];
+            results[i] = static_cast<int>(toInt(ErrorCode::INVALID_REPLICA));
+            get_sessions_.erase(keys[i]);
+            continue;
+        }
+
+        // QueryResult members are const: erase + emplace (no operator=).
+        get_sessions_.erase(keys[i]);
+        get_sessions_.emplace(keys[i],
+                              FilterQueryResult(query_result, *replica));
+        results[i] = 0;
+    }
     return results;
 }
 
-std::vector<tl::expected<void, ErrorCode>>
-RealClient::batch_put_from_multi_buffers_internal(
+namespace {
+
+bool SessionBackendResultCountMatches(const char *operation, size_t expected,
+                                      size_t actual) {
+    if (actual == expected) return true;
+    LOG(ERROR) << operation << " result size mismatch: expected=" << expected
+               << ", got=" << actual;
+    return false;
+}
+
+}  // namespace
+
+bool RealClient::validate_session_range_batch_arguments(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const std::vector<std::vector<size_t>> &all_src_offsets) const {
+    if (client_ && keys.size() == all_buffers.size() &&
+        keys.size() == all_sizes.size() &&
+        keys.size() == all_src_offsets.size()) {
+        return true;
+    }
+    LOG(ERROR) << "Invalid get ranges args";
+    return false;
+}
+
+std::vector<RealClient::SessionRangeReadRequest>
+RealClient::prepare_session_range_read_requests(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const std::vector<std::vector<size_t>> &all_src_offsets,
+    std::vector<int> &results) {
+    std::vector<SessionRangeReadRequest> requests;
+    requests.reserve(keys.size());
+
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    auto validation_time = std::chrono::steady_clock::now();
+    for (size_t request_index = 0; request_index < keys.size();
+         ++request_index) {
+        const auto &buffers = all_buffers[request_index];
+        const auto &sizes = all_sizes[request_index];
+        const auto &offsets = all_src_offsets[request_index];
+        if (buffers.size() != sizes.size() ||
+            buffers.size() != offsets.size()) {
+            continue;
+        }
+
+        auto session = get_sessions_.find(keys[request_index]);
+        if (session == get_sessions_.end()) continue;
+        if (session->second.IsLeaseExpired(validation_time)) {
+            get_sessions_.erase(session);
+            results[request_index] =
+                static_cast<int>(toInt(ErrorCode::LEASE_EXPIRED));
+            continue;
+        }
+        if (session->second.replicas.size() != 1) {
+            results[request_index] =
+                static_cast<int>(toInt(ErrorCode::INVALID_REPLICA));
+            continue;
+        }
+
+        const auto &replica = session->second.replicas.front();
+        const uint64_t replica_size = calculate_total_size(replica);
+        if (replica_size > std::numeric_limits<size_t>::max()) {
+            results[request_index] =
+                static_cast<int>(toInt(ErrorCode::BUFFER_OVERFLOW));
+            continue;
+        }
+
+        const size_t replica_limit = static_cast<size_t>(replica_size);
+        size_t transferred_bytes = 0;
+        bool valid_request = true;
+        for (size_t range_index = 0; range_index < buffers.size();
+             ++range_index) {
+            if ((buffers[range_index] == nullptr && sizes[range_index] != 0) ||
+                is_object_range_overflow(offsets[range_index],
+                                         sizes[range_index], replica_limit) ||
+                sizes[range_index] >
+                    std::numeric_limits<size_t>::max() - transferred_bytes) {
+                valid_request = false;
+                break;
+            }
+            transferred_bytes += sizes[range_index];
+            if (transferred_bytes >
+                static_cast<size_t>(std::numeric_limits<int>::max())) {
+                valid_request = false;
+                break;
+            }
+        }
+        if (!valid_request) {
+            results[request_index] =
+                static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+        if (buffers.empty() || transferred_bytes == 0) {
+            results[request_index] = 0;
+            continue;
+        }
+
+        requests.push_back(SessionRangeReadRequest{
+            keys[request_index], request_index, replica, session->second,
+            std::vector<void *>(buffers.begin(), buffers.end()),
+            std::vector<size_t>(sizes.begin(), sizes.end()),
+            std::vector<size_t>(offsets.begin(), offsets.end()),
+            transferred_bytes, session->second.lease_timeout});
+    }
+    return requests;
+}
+
+RealClient::SessionRangeReadPlan
+RealClient::classify_session_range_read_requests(
+    std::vector<SessionRangeReadRequest> requests, std::vector<int> &results) {
+    SessionRangeReadPlan read_plan;
+    for (auto &request : requests) {
+        if (request.selected_replica.is_memory_replica()) {
+            read_plan.memory_requests.push_back(std::move(request));
+        } else if (request.selected_replica.is_dfs_replica()) {
+            read_plan.dfs_requests.push_back(std::move(request));
+        } else {
+            results[request.result_index] =
+                static_cast<int>(toInt(ErrorCode::INVALID_REPLICA));
+        }
+    }
+    return read_plan;
+}
+
+void RealClient::execute_session_memory_range_reads(
+    const std::vector<SessionRangeReadRequest> &requests,
+    std::vector<int> &results) {
+    if (requests.empty()) return;
+
+    std::vector<Replica::Descriptor> replicas;
+    std::vector<std::vector<Slice>> destination_slices;
+    std::vector<std::vector<uint64_t>> source_offsets;
+    replicas.reserve(requests.size());
+    destination_slices.reserve(requests.size());
+    source_offsets.reserve(requests.size());
+    for (const auto &request : requests) {
+        std::vector<Slice> request_slices;
+        std::vector<uint64_t> request_offsets;
+        request_slices.reserve(request.destination_buffers.size());
+        request_offsets.reserve(request.source_offsets.size());
+        for (size_t range_index = 0;
+             range_index < request.destination_buffers.size(); ++range_index) {
+            request_slices.emplace_back(
+                Slice{request.destination_buffers[range_index],
+                      request.range_sizes[range_index]});
+            request_offsets.push_back(
+                static_cast<uint64_t>(request.source_offsets[range_index]));
+        }
+        replicas.push_back(request.selected_replica);
+        destination_slices.push_back(std::move(request_slices));
+        source_offsets.push_back(std::move(request_offsets));
+    }
+
+    auto transfer_results = client_->BatchTransferReadRanges(
+        replicas, destination_slices, source_offsets);
+    if (!SessionBackendResultCountMatches(
+            "Session memory range", requests.size(), transfer_results.size())) {
+        for (const auto &request : requests) {
+            results[request.result_index] =
+                static_cast<int>(toInt(ErrorCode::INTERNAL_ERROR));
+        }
+        return;
+    }
+
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    const auto completion_time = std::chrono::steady_clock::now();
+    for (size_t request_index = 0; request_index < requests.size();
+         ++request_index) {
+        const auto &request = requests[request_index];
+        if (!transfer_results[request_index]) {
+            results[request.result_index] = static_cast<int>(
+                toInt(transfer_results[request_index].error()));
+        } else if (completion_time >= request.lease_deadline) {
+            mark_get_session_lease_expired_locked(request, results);
+        } else {
+            results[request.result_index] =
+                static_cast<int>(transfer_results[request_index].value());
+        }
+    }
+}
+
+RealClient::DfsSessionStagingArena RealClient::build_dfs_session_staging_arena(
+    const std::vector<SessionRangeReadRequest> &requests,
+    std::vector<int> &results) {
+    constexpr size_t kObjectAlignment = 64;
+    DfsSessionStagingArena staging_arena;
+    size_t arena_size = 0;
+    for (const auto &request : requests) {
+        if (staging_arena.object_offsets.count(request.object_key) != 0) {
+            continue;
+        }
+
+        const size_t object_size =
+            static_cast<size_t>(calculate_total_size(request.selected_replica));
+        const size_t padding =
+            (kObjectAlignment - arena_size % kObjectAlignment) %
+            kObjectAlignment;
+        if (padding > std::numeric_limits<size_t>::max() - arena_size ||
+            object_size >
+                std::numeric_limits<size_t>::max() - arena_size - padding) {
+            fail_file_backed_requests_for_key(requests, request.object_key,
+                                              ErrorCode::BUFFER_OVERFLOW,
+                                              results);
+            continue;
+        }
+
+        arena_size += padding;
+        staging_arena.object_offsets.emplace(request.object_key, arena_size);
+        arena_size += object_size;
+        staging_arena.object_keys.push_back(request.object_key);
+        staging_arena.cached_query_results.push_back(FilterQueryResult(
+            request.cached_query_result, request.selected_replica));
+    }
+
+    staging_arena.staging_buffer = AcquireSessionStaging(
+        file_storage_, client_buffer_allocator_, arena_size,
+        session_range_requests_target_device(requests));
+    if (!staging_arena.object_keys.empty() && !staging_arena.staging_buffer) {
+        for (const auto &object_key : staging_arena.object_keys) {
+            fail_file_backed_requests_for_key(
+                requests, object_key, ErrorCode::NO_AVAILABLE_HANDLE, results);
+        }
+        return staging_arena;
+    }
+    if (!staging_arena.staging_buffer) return staging_arena;
+
+    for (const auto &request : requests) {
+        if (staging_arena.object_slices.count(request.object_key) != 0 ||
+            staging_arena.object_offsets.count(request.object_key) == 0) {
+            continue;
+        }
+
+        std::vector<Slice> slices;
+        allocateSlices(
+            slices, request.selected_replica,
+            static_cast<char *>(staging_arena.staging_buffer->ptr()) +
+                staging_arena.object_offsets.at(request.object_key));
+        staging_arena.object_slices.emplace(request.object_key,
+                                            std::move(slices));
+    }
+    return staging_arena;
+}
+
+bool RealClient::session_range_requests_target_device(
+    const std::vector<SessionRangeReadRequest> &requests) const {
+    auto runtime_accelerator =
+        device::GetAcceleratorRegistry().RuntimeAccelerators();
+    for (const auto &request : requests) {
+        for (const void *destination : request.destination_buffers) {
+            if (runtime_accelerator.FindDeviceForPointer(destination)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+void RealClient::execute_session_dfs_range_reads(
+    const std::vector<SessionRangeReadRequest> &requests,
+    std::vector<int> &results) {
+    if (requests.empty()) return;
+
+    auto staging_arena = build_dfs_session_staging_arena(requests, results);
+    if (!staging_arena.staging_buffer) return;
+
+    auto read_results = client_->BatchGet(staging_arena.object_keys,
+                                          staging_arena.cached_query_results,
+                                          staging_arena.object_slices);
+    if (!SessionBackendResultCountMatches("Session DFS BatchGet",
+                                          staging_arena.object_keys.size(),
+                                          read_results.size())) {
+        for (const auto &object_key : staging_arena.object_keys) {
+            fail_file_backed_requests_for_key(
+                requests, object_key, ErrorCode::INTERNAL_ERROR, results);
+        }
+        return;
+    }
+
+    for (size_t object_index = 0;
+         object_index < staging_arena.object_keys.size(); ++object_index) {
+        const auto &object_key = staging_arena.object_keys[object_index];
+        if (!read_results[object_index]) {
+            fail_file_backed_requests_for_key(
+                requests, object_key, read_results[object_index].error(),
+                results);
+            continue;
+        }
+
+        const void *staging_buffer =
+            static_cast<const char *>(staging_arena.staging_buffer->ptr()) +
+            staging_arena.object_offsets.at(object_key);
+        for (const auto &request : requests) {
+            if (request.object_key == object_key) {
+                complete_staged_session_range_read(request, staging_buffer,
+                                                   results);
+            }
+        }
+    }
+}
+
+tl::expected<void, ErrorCode> RealClient::scatter_session_range_read(
+    const SessionRangeReadRequest &request, const void *staging_buffer) const {
+    for (size_t range_index = 0;
+         range_index < request.destination_buffers.size(); ++range_index) {
+        const void *source = static_cast<const char *>(staging_buffer) +
+                             request.source_offsets[range_index];
+        if (auto copy = scatter_host_to_maybe_device(
+                request.destination_buffers[range_index], source,
+                request.range_sizes[range_index],
+                "session file-backed range read, key: " + request.object_key);
+            !copy) {
+            return tl::unexpected(copy.error());
+        }
+    }
+    return {};
+}
+
+void RealClient::complete_staged_session_range_read(
+    const SessionRangeReadRequest &request, const void *staging_buffer,
+    std::vector<int> &results) {
+    if (invalidate_expired_get_session(request, results)) return;
+
+    auto scatter_result = scatter_session_range_read(request, staging_buffer);
+    if (!scatter_result) {
+        results[request.result_index] =
+            static_cast<int>(toInt(scatter_result.error()));
+        return;
+    }
+
+    if (invalidate_expired_get_session(request, results)) return;
+    results[request.result_index] = static_cast<int>(request.transferred_bytes);
+}
+
+bool RealClient::invalidate_expired_get_session(
+    const SessionRangeReadRequest &request, std::vector<int> &results) {
+    if (std::chrono::steady_clock::now() < request.lease_deadline) {
+        return false;
+    }
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    mark_get_session_lease_expired_locked(request, results);
+    return true;
+}
+
+void RealClient::mark_get_session_lease_expired_locked(
+    const SessionRangeReadRequest &request, std::vector<int> &results) {
+    results[request.result_index] =
+        static_cast<int>(toInt(ErrorCode::LEASE_EXPIRED));
+    get_sessions_.erase(request.object_key);
+}
+
+void RealClient::fail_file_backed_requests_for_key(
+    const std::vector<SessionRangeReadRequest> &requests,
+    const std::string &object_key, ErrorCode error, std::vector<int> &results) {
+    for (const auto &request : requests) {
+        if (request.object_key == object_key) {
+            results[request.result_index] = static_cast<int>(toInt(error));
+        }
+    }
+}
+
+std::vector<int> RealClient::batch_get_into_multi_buffer_ranges(
     const std::vector<std::string> &keys,
     const std::vector<std::vector<void *>> &all_buffers,
     const std::vector<std::vector<size_t>> &all_sizes,
+    const std::vector<std::vector<size_t>> &all_src_offsets) {
+    std::vector<int> results(
+        keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    if (!validate_session_range_batch_arguments(keys, all_buffers, all_sizes,
+                                                all_src_offsets)) {
+        return results;
+    }
+
+    auto requests = prepare_session_range_read_requests(
+        keys, all_buffers, all_sizes, all_src_offsets, results);
+    auto read_plan =
+        classify_session_range_read_requests(std::move(requests), results);
+
+    execute_session_memory_range_reads(read_plan.memory_requests, results);
+    execute_session_dfs_range_reads(read_plan.dfs_requests, results);
+    return results;
+}
+
+int RealClient::batch_get_session_end(const std::vector<std::string> &keys) {
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    for (const auto &key : keys) {
+        get_sessions_.erase(key);
+    }
+    return 0;
+}
+
+std::vector<int> RealClient::batch_put_session_start(
+    const std::vector<std::string> &keys, const std::vector<size_t> &sizes,
     const ReplicateConfig &config) {
+    std::vector<int> results(keys.size(), 0);
+    if (!client_ || keys.size() != sizes.size()) {
+        LOG(ERROR) << "Invalid batch_put_session_start args";
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+    if (config.group_ids.has_value() &&
+        config.group_ids->size() != keys.size()) {
+        LOG(ERROR) << "batch_put_session_start: group_ids.size()="
+                   << config.group_ids->size()
+                   << ", keys.size()=" << keys.size()
+                   << ", error=invalid_group_ids";
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    // Session put only writes MEMORY replicas. Reliable configs that require
+    // NoF completion cannot be finalized correctly on this path.
+    const auto write_mode = DetermineReplicaWriteMode(config);
+    if (config.nof_replica_num > 0 &&
+        write_mode != ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
+        LOG(ERROR) << "batch_put_session_start rejects reliable NoF configs: "
+                   << "session path never writes NoF "
+                   << "(nof_replica_num=" << config.nof_replica_num
+                   << ", replica_num=" << config.replica_num << ")";
+        return std::vector<int>(
+            keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    }
+
+    std::vector<std::string> start_keys;
+    std::vector<uint64_t> start_sizes;
+    std::vector<size_t> start_indices;
+    {
+        std::lock_guard<std::mutex> lock(session_mutex_);
+        for (size_t i = 0; i < keys.size(); ++i) {
+            if (put_sessions_.count(keys[i]) != 0) {
+                LOG(ERROR) << "Put session already exists for key: " << keys[i];
+                results[i] = static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+                continue;
+            }
+            start_keys.push_back(keys[i]);
+            start_sizes.push_back(static_cast<uint64_t>(sizes[i]));
+            start_indices.push_back(i);
+        }
+    }
+    if (start_keys.empty()) {
+        return results;
+    }
+
+    // start_keys may be a subset when some keys already have sessions; keep
+    // group_ids aligned with the filtered key list.
+    ReplicateConfig start_config = config;
+    if (start_config.group_ids.has_value()) {
+        std::vector<std::string> filtered_group_ids;
+        filtered_group_ids.reserve(start_indices.size());
+        for (size_t idx : start_indices) {
+            filtered_group_ids.push_back(start_config.group_ids->at(idx));
+        }
+        start_config.group_ids = std::move(filtered_group_ids);
+    }
+
+    // Same first half as Client::BatchPut (StartBatchPut → master
+    // BatchPutStart).
+    auto start_responses =
+        client_->StartBatchPutForSizes(start_keys, start_sizes, start_config);
+    std::vector<std::string> keys_to_revoke;
+    std::vector<std::string> hot_keys_to_remove;
+    {
+        std::lock_guard<std::mutex> lock(session_mutex_);
+        for (size_t j = 0; j < start_keys.size(); ++j) {
+            const size_t i = start_indices[j];
+            if (!start_responses[j]) {
+                results[i] =
+                    static_cast<int>(toInt(start_responses[j].error()));
+                continue;
+            }
+            auto replicas = std::move(start_responses[j].value());
+            if (!HasMemoryReplica(replicas)) {
+                hot_keys_to_remove.push_back(keys[i]);
+                keys_to_revoke.push_back(keys[i]);
+                results[i] =
+                    static_cast<int>(toInt(ErrorCode::INVALID_REPLICA));
+                continue;
+            }
+            put_sessions_[keys[i]] = PutSessionEntry{
+                .replicas = std::move(replicas),
+                .object_size = static_cast<uint64_t>(sizes[i]),
+                .write_mode = write_mode,
+            };
+        }
+    }
+    // Master RPCs and hot-cache updates run outside session_mutex_.
+    if (client_->GetHotCache() && !hot_keys_to_remove.empty()) {
+        client_->GetHotCache()->RemoveHotKeys(hot_keys_to_remove);
+    }
+    if (!keys_to_revoke.empty()) {
+        (void)client_->BatchPutRevoke(keys_to_revoke);
+    }
+    return results;
+}
+
+std::vector<int> RealClient::batch_put_from_multi_buffer_ranges(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const std::vector<std::vector<size_t>> &all_dst_offsets) {
+    std::vector<int> results(
+        keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    if (!client_ || keys.size() != all_buffers.size() ||
+        keys.size() != all_sizes.size() ||
+        keys.size() != all_dst_offsets.size()) {
+        LOG(ERROR) << "Invalid put ranges args";
+        return results;
+    }
+
+    // RealClient owns session state (overflow check vs object_size, replica
+    // lookup); the parallel replicated transfer is delegated to Client.
+    std::vector<std::vector<Replica::Descriptor>> replicas_per_entry;
+    std::vector<std::vector<Slice>> slices;
+    std::vector<std::vector<uint64_t>> dst_offsets;
+    std::vector<size_t> idx_map;  // batch entry -> original key index
+    std::vector<std::string> inflight_keys;
+
+    {
+        std::lock_guard<std::mutex> lock(session_mutex_);
+        for (size_t i = 0; i < keys.size(); ++i) {
+            const auto &buffers = all_buffers[i];
+            const auto &sizes = all_sizes[i];
+            const auto &offsets = all_dst_offsets[i];
+            if (buffers.size() != sizes.size() ||
+                buffers.size() != offsets.size()) {
+                continue;
+            }
+            auto it = put_sessions_.find(keys[i]);
+            if (it == put_sessions_.end() || !it->second.writable) {
+                continue;
+            }
+            bool overflow = false;
+            std::vector<Slice> entry_slices;
+            std::vector<uint64_t> entry_offsets;
+            entry_slices.reserve(buffers.size());
+            entry_offsets.reserve(buffers.size());
+            for (size_t j = 0; j < buffers.size(); ++j) {
+                if (is_object_range_overflow(
+                        offsets[j], sizes[j],
+                        static_cast<size_t>(it->second.object_size))) {
+                    overflow = true;
+                    break;
+                }
+                entry_slices.emplace_back(Slice{buffers[j], sizes[j]});
+                entry_offsets.push_back(static_cast<uint64_t>(offsets[j]));
+            }
+            if (overflow) {
+                continue;  // results[i] stays INVALID_PARAMS
+            }
+            ++it->second.inflight_transfers;
+            inflight_keys.push_back(keys[i]);
+            replicas_per_entry.push_back(it->second.replicas);
+            slices.push_back(std::move(entry_slices));
+            dst_offsets.push_back(std::move(entry_offsets));
+            idx_map.push_back(i);
+        }
+    }
+
+    if (replicas_per_entry.empty()) {
+        return results;
+    }
+
+    // Ensure end/revoke can make progress even if transfer throws.
+    struct InflightGuard {
+        RealClient *self;
+        std::vector<std::string> keys;
+        ~InflightGuard() {
+            if (!self) {
+                return;
+            }
+            std::lock_guard<std::mutex> lock(self->session_mutex_);
+            for (const auto &key : keys) {
+                auto it = self->put_sessions_.find(key);
+                if (it == self->put_sessions_.end()) {
+                    continue;
+                }
+                if (it->second.inflight_transfers > 0) {
+                    --it->second.inflight_transfers;
+                }
+            }
+            self->session_cv_.notify_all();
+        }
+    } inflight_guard{this, std::move(inflight_keys)};
+
+    auto transfer = client_->BatchTransferWriteRanges(replicas_per_entry,
+                                                      slices, dst_offsets);
+
+    for (size_t k = 0; k < transfer.size(); ++k) {
+        const size_t i = idx_map[k];
+        if (transfer[k]) {
+            results[i] = static_cast<int>(transfer[k].value());
+        } else {
+            results[i] = static_cast<int>(toInt(transfer[k].error()));
+        }
+    }
+    return results;
+}
+
+std::vector<int> RealClient::batch_put_session_end(
+    const std::vector<std::string> &keys) {
+    std::vector<int> results(
+        keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
     if (!client_) {
         LOG(ERROR) << "Client is not initialized";
-        return std::vector<tl::expected<void, ErrorCode>>(
-            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+        return results;
     }
 
-    if ((keys.size() != all_buffers.size()) ||
-        (all_buffers.size() != all_sizes.size())) {
-        LOG(ERROR) << "Mismatched sizes for keys, buffers, and sizes";
-        return std::vector<tl::expected<void, ErrorCode>>(
-            keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    // Session put only writes memory replicas (BatchTransferWriteRanges skips
+    // NoF). For FLEXIBLE_DUAL_REPLICA, finalize MEMORY then revoke leftover NoF
+    // — same split FinalizeBatchPut uses when only memory transfers succeed.
+    // Reliable configs with NoF are rejected at session start.
+    std::vector<std::string> end_keys;
+    std::vector<size_t> end_indices;
+    std::vector<char> has_nof;  // parallel to end_keys
+    {
+        std::unique_lock<std::mutex> lock(session_mutex_);
+        for (size_t i = 0; i < keys.size(); ++i) {
+            auto it = put_sessions_.find(keys[i]);
+            if (it == put_sessions_.end()) {
+                results[i] = static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+                continue;
+            }
+            bool nof = false;
+            for (const auto &replica : it->second.replicas) {
+                if (replica.is_nof_replica()) {
+                    nof = true;
+                    break;
+                }
+            }
+            // Seal first so concurrent range writes cannot start.
+            it->second.writable = false;
+            // MEMORY+NoF revoke fallback is only valid for flexible dual mode.
+            if (nof && it->second.write_mode !=
+                           ReplicaWriteMode::FLEXIBLE_DUAL_REPLICA) {
+                LOG(ERROR)
+                    << "batch_put_session_end: key=" << keys[i]
+                    << " has NoF replicas under non-flexible write mode; "
+                    << "use batch_put_session_revoke";
+                results[i] = static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+                continue;
+            }
+            end_keys.push_back(keys[i]);
+            end_indices.push_back(i);
+            has_nof.push_back(static_cast<char>(nof));
+        }
+        if (!end_keys.empty()) {
+            session_cv_.wait(lock, [&] {
+                for (const auto &key : end_keys) {
+                    auto it = put_sessions_.find(key);
+                    if (it != put_sessions_.end() &&
+                        it->second.inflight_transfers > 0) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+    }
+    if (end_keys.empty()) {
+        return results;
     }
 
-    std::vector<std::vector<mooncake::Slice>> batched_slices(keys.size());
-    for (size_t i = 0; i < all_buffers.size(); ++i) {
-        const auto &buffers = all_buffers[i];
-        const auto &sizes = all_sizes[i];
-        if (buffers.size() != sizes.size()) {
-            LOG(ERROR) << "Mismatched buffers and sizes of key:" << keys[i];
-            return std::vector<tl::expected<void, ErrorCode>>(
-                keys.size(), tl::unexpected(ErrorCode::INVALID_PARAMS));
+    // Session put path does not compute checksums; leave object_checksum unset.
+    std::vector<ObjectMeta> end_metas;
+    end_metas.reserve(end_keys.size());
+    for (const auto &key : end_keys) {
+        end_metas.emplace_back(ObjectMeta{key, std::nullopt});
+    }
+    auto end_responses = client_->BatchPutEnd(end_metas, ReplicaType::MEMORY);
+    if (end_responses.size() != end_keys.size()) {
+        // Ambiguous Master state: keep sessions so caller can retry end/revoke.
+        for (size_t j = 0; j < end_keys.size(); ++j) {
+            results[end_indices[j]] =
+                static_cast<int>(toInt(ErrorCode::RPC_FAIL));
         }
-        batched_slices[i].reserve(buffers.size());
-        for (size_t j = 0; j < buffers.size(); ++j) {
-            batched_slices[i].emplace_back(Slice{buffers[j], sizes[j]});
+        return results;
+    }
+
+    std::vector<std::string> nof_revoke_keys;
+    std::vector<size_t> nof_revoke_end_indices;
+    nof_revoke_keys.reserve(end_keys.size());
+    nof_revoke_end_indices.reserve(end_keys.size());
+    for (size_t j = 0; j < end_keys.size(); ++j) {
+        const size_t i = end_indices[j];
+        if (!end_responses[j]) {
+            // Keep session for retry/revoke; do not erase on per-key failure.
+            results[i] = static_cast<int>(toInt(end_responses[j].error()));
+            continue;
         }
+        if (has_nof[j]) {
+            nof_revoke_keys.push_back(end_keys[j]);
+            nof_revoke_end_indices.push_back(j);
+            continue;
+        }
+        {
+            std::lock_guard<std::mutex> lock(session_mutex_);
+            put_sessions_.erase(end_keys[j]);
+        }
+        results[i] = 0;
     }
-    // Call client BatchPut and return the vector<expected> directly
-    return client_->BatchPut(keys, batched_slices, config);
+
+    if (nof_revoke_keys.empty()) {
+        return results;
+    }
+
+    auto nof_revoke_responses =
+        client_->BatchPutRevoke(nof_revoke_keys, ReplicaType::NOF_SSD);
+    if (nof_revoke_responses.size() != nof_revoke_keys.size()) {
+        for (size_t k = 0; k < nof_revoke_keys.size(); ++k) {
+            const size_t j = nof_revoke_end_indices[k];
+            results[end_indices[j]] =
+                static_cast<int>(toInt(ErrorCode::RPC_FAIL));
+            // Keep session: MEMORY end may have succeeded; retry can re-end
+            // (idempotent) and re-revoke NoF.
+        }
+        return results;
+    }
+    for (size_t k = 0; k < nof_revoke_keys.size(); ++k) {
+        const size_t j = nof_revoke_end_indices[k];
+        const size_t i = end_indices[j];
+        if (!nof_revoke_responses[k] &&
+            nof_revoke_responses[k].error() != ErrorCode::OBJECT_NOT_FOUND) {
+            results[i] =
+                static_cast<int>(toInt(nof_revoke_responses[k].error()));
+            continue;
+        }
+        {
+            std::lock_guard<std::mutex> lock(session_mutex_);
+            put_sessions_.erase(nof_revoke_keys[k]);
+        }
+        results[i] = 0;
+    }
+    return results;
+}
+
+std::vector<int> RealClient::batch_put_session_revoke(
+    const std::vector<std::string> &keys) {
+    std::vector<int> results(
+        keys.size(), static_cast<int>(toInt(ErrorCode::INVALID_PARAMS)));
+    if (!client_) {
+        LOG(ERROR) << "Client is not initialized";
+        return results;
+    }
+
+    std::vector<std::string> revoke_keys;
+    std::vector<size_t> revoke_indices;
+    {
+        std::unique_lock<std::mutex> lock(session_mutex_);
+        for (size_t i = 0; i < keys.size(); ++i) {
+            auto it = put_sessions_.find(keys[i]);
+            if (it == put_sessions_.end()) {
+                results[i] = static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+                continue;
+            }
+            // Seal session and wait for outstanding range writes before free.
+            it->second.writable = false;
+            revoke_keys.push_back(keys[i]);
+            revoke_indices.push_back(i);
+        }
+        if (!revoke_keys.empty()) {
+            session_cv_.wait(lock, [&] {
+                for (const auto &key : revoke_keys) {
+                    auto it = put_sessions_.find(key);
+                    if (it != put_sessions_.end() &&
+                        it->second.inflight_transfers > 0) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+    }
+    if (revoke_keys.empty()) {
+        return results;
+    }
+
+    // Same path FinalizeBatchPut uses on transfer failure.
+    if (client_->GetHotCache() && !revoke_keys.empty()) {
+        client_->GetHotCache()->RemoveHotKeys(revoke_keys);
+    }
+    auto revoke_responses =
+        client_->BatchPutRevoke(revoke_keys, ReplicaType::ALL);
+    std::lock_guard<std::mutex> lock(session_mutex_);
+    if (revoke_responses.size() != revoke_keys.size()) {
+        // Ambiguous Master state: keep sessions so caller can retry revoke.
+        for (size_t j = 0; j < revoke_keys.size(); ++j) {
+            results[revoke_indices[j]] =
+                static_cast<int>(toInt(ErrorCode::RPC_FAIL));
+        }
+        return results;
+    }
+    for (size_t j = 0; j < revoke_keys.size(); ++j) {
+        const size_t i = revoke_indices[j];
+        if (!revoke_responses[j]) {
+            if (revoke_responses[j].error() == ErrorCode::OBJECT_NOT_FOUND) {
+                // Nothing left on Master; drop the local session.
+                put_sessions_.erase(revoke_keys[j]);
+                results[i] = 0;
+            } else {
+                // Keep session for retry.
+                results[i] =
+                    static_cast<int>(toInt(revoke_responses[j].error()));
+            }
+            continue;
+        }
+        put_sessions_.erase(revoke_keys[j]);
+        results[i] = 0;
+    }
+    return results;
+}
+
+std::vector<int> RealClient::batch_upsert_from_multi_buffers(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &sizes,
+    const ReplicateConfig &config) {
+    return batch_upsert_from_multi_buffers(keys, all_buffers, sizes, config,
+                                           false);
+}
+
+std::vector<int> RealClient::batch_upsert_from_multi_buffers(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &sizes,
+    const ReplicateConfig &config, bool stage_nonlocal) {
+    auto internal_results =
+        execute_timed_operation<std::vector<tl::expected<void, ErrorCode>>>(
+            [&]() {
+                return batch_upsert_from_multi_buffers_internal(
+                    keys, all_buffers, sizes, config, stage_nonlocal);
+            },
+            [](const auto &) { return true; },
+            [&](uint64_t latency_us, const auto &ret) {
+                auto py_results = ToPyResults(ret);
+                client_->ObserveTransferOperation(
+                    TransferOperationKind::kWrite,
+                    "batch_upsert_from_multi_buffers",
+                    sum_successful_nested_sizes(py_results, sizes), latency_us);
+            });
+    return ToPyResults(internal_results);
+}
+
+std::vector<tl::expected<void, ErrorCode>>
+RealClient::batch_upsert_from_multi_buffers_internal(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const ReplicateConfig &config, bool stage_nonlocal) {
+    return BatchWriteFromMultiBuffers(client_, keys, all_buffers, all_sizes,
+                                      config, client_buffer_allocator_,
+                                      stage_nonlocal, &Client::BatchUpsert);
+}
+
+std::vector<tl::expected<void, ErrorCode>>
+RealClient::batch_put_from_multi_buffers_internal(
+    const std::vector<std::string> &keys,
+    const std::vector<std::vector<void *>> &all_buffers,
+    const std::vector<std::vector<size_t>> &all_sizes,
+    const ReplicateConfig &config, bool stage_nonlocal) {
+    return BatchWriteFromMultiBuffers(client_, keys, all_buffers, all_sizes,
+                                      config, client_buffer_allocator_,
+                                      stage_nonlocal, &Client::BatchPut);
 }
 
 std::vector<int> RealClient::batch_get_into_multi_buffers(
@@ -5273,12 +7292,24 @@ RealClient::batch_get_into_multi_buffers_internal(
         std::vector<void *> buffers;
         std::vector<size_t> sizes;
         uint64_t total_size;
-        bool is_local_disk;  // true=LOCAL_DISK (offload RPC), false=DISK
+        Replica::Descriptor replica;
+        bool is_local_disk;  // true=LOCAL_DISK (offload RPC), false=DISK/DFS
                              // (BatchGet)
     };
 
+    // A duplicate of a disk/offload key: not transferred itself, receives the
+    // first occurrence's verified bytes in the fan-out passes below.
+    struct DuplicateDiskOp {
+        size_t original_index;
+        std::string key;
+        std::vector<void *> buffers;
+        std::vector<size_t> sizes;
+        uint64_t total_size;
+    };
+
     std::vector<ValidKeyInfo> valid_operations;
     std::unordered_map<std::string, DiskKeyInfo> valid_local_disk_ops;
+    std::vector<DuplicateDiskOp> duplicate_disk_ops;
     valid_operations.reserve(num_keys);
     auto local_endpoints = client_->GetLocalEndpoints();
     for (size_t i = 0; i < num_keys; ++i) {
@@ -5294,15 +7325,15 @@ RealClient::batch_get_into_multi_buffers_internal(
             continue;
         }
         // Validate replica list
-        auto query_result_values = query_results[i].value();
+        const auto &query_result_values = query_results[i].value();
         if (query_result_values.replicas.empty()) {
             LOG(ERROR) << "Empty replica list for key: " << key;
             results.emplace_back(tl::unexpected(ErrorCode::INVALID_REPLICA));
             continue;
         }
-        // Select best replica: prefer MEMORY (direct RDMA to GPU), then
-        // LOCAL_DISK, then DISK. Master may return multiple replicas in any
-        // order, so always scan rather than blindly taking replicas[0].
+        // Select best replica: prefer local MEMORY, any MEMORY, local NOF,
+        // any NOF, LOCAL_DISK, DFS, then DISK. Master may return multiple
+        // replicas in any order, so always scan.
         const auto *best_replica =
             SelectBestReplica(query_result_values.replicas, local_endpoints);
         if (!best_replica) {
@@ -5328,16 +7359,28 @@ RealClient::batch_get_into_multi_buffers_internal(
         const auto &buffers = all_buffers[i];
         std::vector<Slice> key_slices;
         key_slices.reserve(buffers.size());
-        if (replica.is_memory_replica()) {
-            // MEMORY: RDMA from remote memory directly to GPU (GPUDirect).
+        if (replica.is_memory_replica() || replica.is_nof_replica()) {
+            // MEMORY / NOF: RDMA directly to the user buffers.
             for (size_t j = 0; j < buffers.size(); ++j) {
                 key_slices.emplace_back(Slice{buffers[j], sizes[j]});
             }
         } else if (replica.is_local_disk_replica() ||
-                   replica.is_disk_replica()) {
+                   replica.is_disk_replica() || replica.is_dfs_replica()) {
             // LOCAL_DISK: GPU buffers passed directly as scatter-gather slices
-            // (zero-copy). DISK: file I/O cannot write to GPU memory; temp CPU
-            // buffer used at read time.
+            // (zero-copy). DISK/DFS use a contiguous temp buffer at read time.
+            if (valid_local_disk_ops.count(key)) {
+                // Duplicate key: the first occurrence stays the transfer
+                // primary; its verified bytes fan out to this duplicate's
+                // buffers in the read paths below.
+                duplicate_disk_ops.push_back(
+                    DuplicateDiskOp{.original_index = i,
+                                    .key = key,
+                                    .buffers = all_buffers[i],
+                                    .sizes = all_sizes[i],
+                                    .total_size = total_size});
+                results.emplace_back(static_cast<int64_t>(total_size));
+                continue;
+            }
             valid_local_disk_ops.emplace(
                 key,
                 DiskKeyInfo{.key = key,
@@ -5346,6 +7389,7 @@ RealClient::batch_get_into_multi_buffers_internal(
                             .buffers = all_buffers[i],
                             .sizes = all_sizes[i],
                             .total_size = total_size,
+                            .replica = replica,
                             .is_local_disk = replica.is_local_disk_replica()});
             results.emplace_back(static_cast<int64_t>(total_size));
             continue;
@@ -5369,14 +7413,19 @@ RealClient::batch_get_into_multi_buffers_internal(
         return results;
     }
 
-    // ---- Memory/Disk replica: existing BatchGet path ----
+    // ---- Memory/NOF replica: existing BatchGet path ----
     if (!valid_operations.empty()) {
         std::vector<std::string> batch_keys;
         std::vector<QueryResult> batch_query_results;
         std::unordered_map<std::string, std::vector<Slice>> batch_slices;
         batch_keys.reserve(valid_operations.size());
         batch_query_results.reserve(valid_operations.size());
-        for (auto &op : valid_operations) {
+        // The slice map is keyed by string, so duplicate keys would collapse
+        // onto one destination. Transfer each unique key once (first
+        // occurrence as primary) and fan the verified bytes out locally.
+        const auto dedup = PlanDuplicateKeys(valid_operations);
+        for (const size_t op_idx : dedup.primaries) {
+            const auto &op = valid_operations[op_idx];
             batch_keys.push_back(op.key);
             batch_query_results.push_back(op.query_result);
             batch_slices[op.key] = op.slices;
@@ -5387,7 +7436,7 @@ RealClient::batch_get_into_multi_buffers_internal(
                               prefer_alloc_in_same_node);
 
         for (size_t j = 0; j < batch_get_results.size(); ++j) {
-            const auto &op = valid_operations[j];
+            const auto &op = valid_operations[dedup.primaries[j]];
             if (!batch_get_results[j]) {
                 const auto error = batch_get_results[j].error();
                 LOG(ERROR) << "BatchGet failed for key '" << op.key
@@ -5395,9 +7444,27 @@ RealClient::batch_get_into_multi_buffers_internal(
                 results[op.original_index] = tl::unexpected(error);
             }
         }
+
+        std::vector<DuplicateFanOutJob> dup_jobs;
+        for (const auto &[dup_idx, primary_idx] : dedup.duplicates) {
+            const auto &dup_op = valid_operations[dup_idx];
+            const auto &primary_op = valid_operations[primary_idx];
+            dup_jobs.push_back(DuplicateFanOutJob{
+                .dup_result_index = dup_op.original_index,
+                .primary_result_index = primary_op.original_index,
+                .key = dup_op.key,
+                .dup_bytes = dup_op.total_size,
+                .primary_bytes = primary_op.total_size,
+                .copy = [dst = dup_op.slices, src = primary_op.slices,
+                         size = dup_op.total_size, key = dup_op.key]() {
+                    return CopySlicesMaybeDevice(
+                        dst, src, size, "duplicate fan-out, key: " + key);
+                }});
+        }
+        FanOutDuplicates(dup_jobs, results);
     }
 
-    // ---- LOCAL_DISK / DISK replica: disk read paths ----
+    // ---- LOCAL_DISK / file-backed replica read paths ----
     if (!valid_local_disk_ops.empty()) {
         // LOCAL_DISK: pass user GPU buffers directly as scatter-gather slices.
         // vLLM pre-registers all GPU KV-cache memory with TransferEngine via
@@ -5412,23 +7479,14 @@ RealClient::batch_get_into_multi_buffers_internal(
 
             for (auto &[key, op] : valid_local_disk_ops) {
                 if (!op.is_local_disk) continue;
-                // Find the correct LOCAL_DISK replica — Master may return
-                // replicas in any order (e.g. [DISK, LOCAL_DISK]).
-                const Replica::Descriptor *replica_ptr = nullptr;
-                for (const auto &r : op.query_result.replicas) {
-                    if (r.is_local_disk_replica()) {
-                        replica_ptr = &r;
-                        break;
-                    }
-                }
-                if (!replica_ptr) {
+                const auto &replica = op.replica;
+                if (!replica.is_local_disk_replica()) {
                     LOG(ERROR)
                         << "No LOCAL_DISK replica found for key: " << key;
                     results[op.original_index] =
                         tl::make_unexpected(ErrorCode::INVALID_REPLICA);
                     continue;
                 }
-                const auto &replica = *replica_ptr;
                 std::vector<Slice> user_slices;
                 user_slices.reserve(op.buffers.size());
                 size_t slice_total = 0;
@@ -5480,12 +7538,34 @@ RealClient::batch_get_into_multi_buffers_internal(
                     }
                 }
             }
+
+            // Fan verified LOCAL_DISK primary bytes out to duplicate
+            // destination buffer lists.
+            std::vector<DuplicateFanOutJob> dup_jobs;
+            for (const auto &dup : duplicate_disk_ops) {
+                const auto &primary_op = valid_local_disk_ops.at(dup.key);
+                if (!primary_op.is_local_disk) continue;
+                dup_jobs.push_back(DuplicateFanOutJob{
+                    .dup_result_index = dup.original_index,
+                    .primary_result_index = primary_op.original_index,
+                    .key = dup.key,
+                    .dup_bytes = dup.total_size,
+                    .primary_bytes = primary_op.total_size,
+                    .copy = [dst = SlicesFromBuffers(dup.buffers, dup.sizes),
+                             src = SlicesFromBuffers(primary_op.buffers,
+                                                     primary_op.sizes),
+                             size = dup.total_size, key = dup.key]() {
+                        return CopySlicesMaybeDevice(
+                            dst, src, size,
+                            "duplicate SSD fan-out, key: " + key);
+                    }});
+            }
+            FanOutDuplicates(dup_jobs, results);
         }
 
-        // DISK: one batched BatchGet into CPU temp buffers, then scatter.
-        // (storage_backend::vector_read cannot write directly to GPU memory)
+        // DISK/DFS: one batched BatchGet into temp buffers, then scatter.
         {
-            // Scatter temp CPU buffer -> user multi_buffers (GPU or host).
+            // Scatter temp buffer -> user multi_buffers (GPU or host).
             // Returns false and sets results[original_index] on error.
             auto scatter_to_buffers = [&](const std::string &key, char *src,
                                           const DiskKeyInfo &op) -> bool {
@@ -5496,8 +7576,12 @@ RealClient::batch_get_into_multi_buffers_internal(
                         std::min(op.sizes[j],
                                  static_cast<size_t>(op.total_size - offset));
                     void *dst = op.buffers[j];
+                    const char *replica_type =
+                        op.replica.is_dfs_replica() ? "DFS" : "DISK";
                     if (auto r = scatter_host_to_maybe_device(
-                            dst, src + offset, sz, "DISK scatter, key: " + key);
+                            dst, src + offset, sz,
+                            std::string(replica_type) +
+                                " scatter, key: " + key);
                         !r) {
                         results[op.original_index] =
                             tl::make_unexpected(r.error());
@@ -5518,39 +7602,26 @@ RealClient::batch_get_into_multi_buffers_internal(
 
             for (auto &[key, op] : valid_local_disk_ops) {
                 if (op.is_local_disk) continue;
+                const auto &replica = op.replica;
+                const char *replica_type =
+                    replica.is_dfs_replica() ? "DFS" : "DISK";
                 auto alloc_result =
                     client_buffer_allocator_->allocate(op.total_size);
                 if (!alloc_result) {
                     LOG(ERROR)
-                        << "Failed to allocate temp buffer for DISK "
-                        << "read, key: " << key << ", size: " << op.total_size;
+                        << "Failed to allocate temp buffer for " << replica_type
+                        << " read, key: " << key << ", size: " << op.total_size;
                     results[op.original_index] =
                         tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
                     continue;
                 }
                 auto handle =
                     std::make_unique<BufferHandle>(std::move(*alloc_result));
-                // Find the correct DISK replica — Master may return
-                // replicas in any order (e.g. [LOCAL_DISK, DISK]).
-                const Replica::Descriptor *replica_ptr = nullptr;
-                for (const auto &r : op.query_result.replicas) {
-                    if (r.is_disk_replica()) {
-                        replica_ptr = &r;
-                        break;
-                    }
-                }
-                if (!replica_ptr) {
-                    LOG(ERROR) << "No DISK replica found for key: " << key;
-                    results[op.original_index] =
-                        tl::make_unexpected(ErrorCode::INVALID_REPLICA);
-                    continue;
-                }
-                const auto &replica = *replica_ptr;
                 std::vector<Slice> disk_slices;
                 allocateSlices(disk_slices, replica, handle->ptr());
                 disk_batch_keys.push_back(key);
                 disk_batch_qrs.push_back(
-                    FilterQueryResult(op.query_result, *replica_ptr));
+                    FilterQueryResult(op.query_result, replica));
                 disk_batch_slices[key] = std::move(disk_slices);
                 disk_key_order.push_back(key);
                 temp_handles.emplace(key, std::move(handle));
@@ -5565,9 +7636,12 @@ RealClient::batch_get_into_multi_buffers_internal(
                     const auto &key = disk_key_order[di];
                     auto &op = valid_local_disk_ops.at(key);
                     auto handle_it = temp_handles.find(key);
+                    const char *replica_type =
+                        op.replica.is_dfs_replica() ? "DFS" : "DISK";
                     if (!disk_results[di]) {
                         LOG(ERROR)
-                            << "DISK BatchGet failed for key '" << key
+                            << replica_type << " BatchGet failed for key '"
+                            << key
                             << "': " << toString(disk_results[di].error());
                         results[op.original_index] =
                             tl::make_unexpected(disk_results[di].error());
@@ -5579,6 +7653,39 @@ RealClient::batch_get_into_multi_buffers_internal(
                         continue;
                 }
             }
+
+            // Fan the primary's verified temp bytes out to duplicate
+            // destination buffer lists (device-aware, same as primaries).
+            std::vector<DuplicateFanOutJob> dup_jobs;
+            for (const auto &dup : duplicate_disk_ops) {
+                const auto &primary_op = valid_local_disk_ops.at(dup.key);
+                if (primary_op.is_local_disk) continue;
+                dup_jobs.push_back(DuplicateFanOutJob{
+                    .dup_result_index = dup.original_index,
+                    .primary_result_index = primary_op.original_index,
+                    .key = dup.key,
+                    .dup_bytes = dup.total_size,
+                    .primary_bytes = primary_op.total_size,
+                    .copy = [&temp_handles,
+                             dst = SlicesFromBuffers(dup.buffers, dup.sizes),
+                             size = dup.total_size, key = dup.key,
+                             is_dfs = primary_op.replica.is_dfs_replica()]()
+                        -> tl::expected<void, ErrorCode> {
+                        auto handle_it = temp_handles.find(key);
+                        if (handle_it == temp_handles.end()) {
+                            return tl::make_unexpected(
+                                ErrorCode::NO_AVAILABLE_HANDLE);
+                        }
+                        return CopySlicesMaybeDevice(
+                            dst,
+                            {Slice{handle_it->second->ptr(),
+                                   static_cast<size_t>(size)}},
+                            size,
+                            std::string(is_dfs ? "DFS" : "DISK") +
+                                " duplicate read, key: " + key);
+                    }});
+            }
+            FanOutDuplicates(dup_jobs, results);
             // temp_handles: BufferHandle RAII releases allocator memory
         }
     }
@@ -5920,38 +8027,113 @@ bool RealClient::release_offload_buffer(uint64_t batch_id) {
     return file_storage_->ReleaseBuffer(batch_id);
 }
 
+bool RealClient::can_use_pinned_restore_arena(
+    const std::string &target_rpc_service_addr,
+    const std::unordered_map<std::string, std::vector<Slice>> &objects) const {
+    if (!file_storage_ || target_rpc_service_addr != local_rpc_addr ||
+        !file_storage_->HasPinnedRestoreArena()) {
+        return false;
+    }
+    auto accelerators = device::GetAcceleratorRegistry().RuntimeAccelerators();
+    bool has_data = false;
+    for (const auto &object : objects) {
+        for (const auto &slice : object.second) {
+            if (slice.size && !accelerators.FindDeviceForPointer(slice.ptr)) {
+                return false;
+            }
+            has_data |= slice.size != 0;
+        }
+    }
+    return has_data;
+}
+
 tl::expected<void, ErrorCode>
 RealClient::batch_get_into_offload_object_internal(
     const std::string &target_rpc_service_addr,
-    std::unordered_map<std::string, std::vector<Slice>> &objects) {
+    std::unordered_map<std::string, std::vector<Slice>> &objects,
+    const OffloadReadRange *read_range) {
     offload_rpc_read_count_.fetch_add(1, std::memory_order_relaxed);
     auto start_time = std::chrono::steady_clock::now();
     std::vector<std::string> keys;
     std::vector<std::string> storage_keys;
     std::vector<int64_t> sizes;
+    if (read_range && objects.size() != 1) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
     const TenantId tenant_id(client_->tenant_id());
     for (const auto &object_it : objects) {
         keys.emplace_back(object_it.first);
         storage_keys.emplace_back(tenant_id.MakeScopedKey(object_it.first));
-        int64_t total = 0;
-        for (const auto &s : object_it.second) total += s.size;
-        sizes.emplace_back(total);
-    }
-    auto batchGetResp = client_requester_->batch_get_offload_object(
-        target_rpc_service_addr, storage_keys, sizes);
-    if (!batchGetResp) {
+        uint64_t total = 0;
+        for (const auto &slice : object_it.second) {
+            if (slice.size > std::numeric_limits<uint64_t>::max() - total) {
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+            total += slice.size;
+        }
+        if (total > uint64_t(std::numeric_limits<int64_t>::max())) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        int64_t storage_size = static_cast<int64_t>(total);
+        if (read_range) {
+            storage_size = read_range->restore_size;
+            if (storage_size < 0 ||
+                read_range->source_offset > uint64_t(storage_size) ||
+                total > uint64_t(storage_size) - read_range->source_offset) {
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+            }
+        }
+        sizes.emplace_back(storage_size);
+    }
+
+    const bool local_batch =
+        can_use_pinned_restore_arena(target_rpc_service_addr, objects);
+    std::optional<FileStorage::LocalBatchResult> local_owner;
+    auto response =
+        [&]() -> tl::expected<BatchGetOffloadObjectResponse, ErrorCode> {
+        if (!local_batch) {
+            return client_requester_->batch_get_offload_object(
+                target_rpc_service_addr, storage_keys, sizes);
+        }
+        auto result = file_storage_->BatchGetLocal(storage_keys, sizes);
+        if (!result) return tl::make_unexpected(result.error());
+        local_owner.emplace(std::move(result.value()));
+        return BatchGetOffloadObjectResponse(0,
+                                             std::move(local_owner->pointers),
+                                             client_->GetSegmentEndpoint(), 0);
+    }();
+    if (!response) {
         LOG(ERROR) << "Batch get offload object failed with error: "
-                   << batchGetResp.error();
-        return tl::make_unexpected(batchGetResp.error());
+                   << response.error();
+        return tl::make_unexpected(response.error());
     }
-    if (batchGetResp->pointers.size() != keys.size()) {
+
+    const auto release_buffer = [&]() {
+        if (!local_batch) {
+            client_requester_->release_offload_buffer(target_rpc_service_addr,
+                                                      response->batch_id);
+        }
+    };
+    struct ReleaseGuard {
+        const decltype(release_buffer) &release;
+        ~ReleaseGuard() { release(); }
+    } release_guard{release_buffer};
+    if (response->pointers.size() != keys.size()) {
         LOG(ERROR) << "Pointer count mismatch from owner: expected="
-                   << keys.size() << ", got=" << batchGetResp->pointers.size();
+                   << keys.size() << ", got=" << response->pointers.size();
         return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
-    auto result =
-        client_->BatchGetOffloadObject(batchGetResp->transfer_engine_addr, keys,
-                                       batchGetResp->pointers, objects);
+    if (read_range) {
+        if (response->pointers[0] >
+            std::numeric_limits<uint64_t>::max() - read_range->source_offset) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        response->pointers[0] += read_range->source_offset;
+    }
+    auto result = client_->BatchGetOffloadObject(
+        response->transfer_engine_addr, keys, response->pointers, objects,
+        local_batch ? OffloadBufferAccess::kLocalAddress
+                    : OffloadBufferAccess::kTransferEngine);
     auto end_time = std::chrono::steady_clock::now();
     auto elapsed_time = static_cast<uint64_t>(
         std::chrono::duration_cast<std::chrono::milliseconds>(end_time -
@@ -5961,20 +8143,15 @@ RealClient::batch_get_into_offload_object_internal(
               << elapsed_time
               << "ms, with target_rpc_service_addr: " << target_rpc_service_addr
               << ", key size: " << objects.size()
-              << ", batch_id: " << batchGetResp->batch_id
-              << ", gc ttl: " << batchGetResp->gc_ttl_ms << "ms.";
-
-    // Release buffer immediately after transfer completion (fire-and-forget)
-    // This allows early buffer reclamation instead of waiting for GC lease
-    client_requester_->release_offload_buffer(target_rpc_service_addr,
-                                              batchGetResp->batch_id);
+              << ", batch_id: " << response->batch_id
+              << ", gc ttl: " << response->gc_ttl_ms << "ms.";
 
     if (!result) {
         LOG(ERROR) << "Batch get into offload object failed with error: "
                    << result.error();
         return result;
     }
-    if (elapsed_time >= batchGetResp->gc_ttl_ms) {
+    if (!local_batch && elapsed_time >= response->gc_ttl_ms) {
         return tl::make_unexpected(ErrorCode::OBJECT_HAS_LEASE);
     }
     return {};
@@ -5982,11 +8159,12 @@ RealClient::batch_get_into_offload_object_internal(
 
 ClientRequester::ClientRequester() {
     coro_io::client_pool<coro_rpc::coro_rpc_client>::pool_config pool_conf{};
-    const char *value = std::getenv("MC_RPC_PROTOCOL");
-    if (value && std::string_view(value) == "rdma") {
+#ifdef YLT_ENABLE_IBV
+    if (RpcProtocolConfig::FromEnvironment().use_rdma) {
         pool_conf.client_config.socket_config =
             coro_io::ib_socket_t::config_t{};
     }
+#endif
     // Configure reasonable retry limits for SSD offload RPC connections.
     // - connect_retry_count: Maximum connection retry attempts (default: 3)
     // - reconnect_wait_time: Wait time between retries (default: 1000ms)
@@ -5999,11 +8177,32 @@ ClientRequester::ClientRequester() {
     pool_conf.reconnect_wait_time = std::chrono::milliseconds{1000};
     pool_conf.host_alive_detect_duration = std::chrono::milliseconds{0};
 
+    // Honour the same timeout overrides as the master pool. Without this the
+    // connect timeout stays at coro_rpc's built-in 30s, so a read that picks a
+    // peer which is gone blocks for connect_retry_count * 30s plus the waits
+    // between retries -- 91s with the defaults above -- and no configuration
+    // can shorten it. Defaults are unchanged when the variables are unset.
+    detail::ApplyRpcTimeoutOverrides(pool_conf.client_config,
+                                     RpcTimeoutConfig::FromEnvironment());
+
     client_pools_ =
         std::make_shared<coro_io::client_pools<coro_rpc::coro_rpc_client>>(
             pool_conf, GetStoreRpcClientIoContextPool());
 }
 
+ClientRequester::~ClientRequester() {
+    if (!rpc_drain_.drain_for(std::chrono::seconds(30))) {
+        LOG(ERROR) << "ClientRequester teardown: offload RPCs still in "
+                      "flight after 30s drain; those calls lose their "
+                      "responses, but the pools stay alive so no late resume "
+                      "touches freed state";
+    }
+    // The pools host ylt reconnect coroutines that reference pool storage
+    // whether or not a user call is in flight (#3909), so the collection is
+    // never freed (#3943 review).
+    detail::KeepClientPoolsAlive(std::move(client_pools_));
+}
+
 tl::expected<BatchGetOffloadObjectResponse, ErrorCode>
 ClientRequester::batch_get_offload_object(const std::string &client_addr,
                                           const std::vector<std::string> &keys,
@@ -6039,6 +8238,10 @@ void ClientRequester::release_offload_buffer(const std::string &client_addr,
 template <auto ServiceMethod, typename ReturnType, typename... Args>
 tl::expected<ReturnType, ErrorCode> ClientRequester::invoke_rpc(
     const std::string &client_addr, Args &&...args) {
+    RpcDrainGuard::ScopedCall inflight(rpc_drain_);
+    if (!inflight.ok()) {
+        return tl::make_unexpected(ErrorCode::RPC_FAIL);
+    }
     auto client_pool = client_pools_->at(client_addr);
     return async_simple::coro::syncAwait(
         [&]() -> async_simple::coro::Lazy<tl::expected<ReturnType, ErrorCode>> {
@@ -6054,6 +8257,10 @@ tl::expected<ReturnType, ErrorCode> ClientRequester::invoke_rpc(
             }
             auto result = co_await std::move(ret.value());
             if (!result) {
+                if (result.error().code == coro_rpc::errc::timed_out) {
+                    LOG(ERROR) << "RPC call timed out: " << result.error().msg;
+                    co_return tl::make_unexpected(ErrorCode::RPC_TIMEOUT);
+                }
                 LOG(ERROR) << "RPC call failed: " << result.error().msg;
                 co_return tl::make_unexpected(ErrorCode::RPC_FAIL);
             }
diff --git a/mooncake-store/src/real_client_main.cpp b/mooncake-store/src/real_client_main.cpp
index a20029a8ee..7a800a4425 100644
--- a/mooncake-store/src/real_client_main.cpp
+++ b/mooncake-store/src/real_client_main.cpp
@@ -2,10 +2,13 @@
 #include <csignal>
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 
+#include "allocator_status.h"
 #include "client_service.h"
 #include "common.h"
 #include "config.h"
+#include "common/byte_size.h"
 #include "real_client.h"
+#include "version.h"
 
 using namespace mooncake;
 
@@ -42,6 +45,8 @@ void RegisterClientRpcService(coro_rpc::coro_rpc_server &server,
     server.register_handler<&RealClient::batchRemove_internal>(&real_client);
     server.register_handler<&RealClient::isExist_internal>(&real_client);
     server.register_handler<&RealClient::batchIsExist_internal>(&real_client);
+    server.register_handler<&RealClient::probeKey_internal>(&real_client);
+    server.register_handler<&RealClient::batchProbeKey_internal>(&real_client);
     server.register_handler<&RealClient::getSize_internal>(&real_client);
     server.register_handler<&RealClient::batch_put_from_dummy_helper>(
         &real_client);
@@ -49,6 +54,12 @@ void RegisterClientRpcService(coro_rpc::coro_rpc_server &server,
         &RealClient::batch_put_from_multi_buffers_dummy_helper>(&real_client);
     server.register_handler<&RealClient::batch_put_from_cuda_ipc_dummy_helper>(
         &real_client);
+    server
+        .register_handler<&RealClient::batch_upsert_from_cuda_ipc_dummy_helper>(
+            &real_client);
+    server.register_handler<
+        &RealClient::batch_upsert_from_multi_buffers_dummy_helper>(
+        &real_client);
     server.register_handler<&RealClient::upsert_dummy_helper>(&real_client);
     server.register_handler<&RealClient::upsert_from_dummy_helper>(
         &real_client);
@@ -68,6 +79,8 @@ void RegisterClientRpcService(coro_rpc::coro_rpc_server &server,
         &real_client);
     server.register_handler<&RealClient::get_into_ranges_shm_helper>(
         &real_client);
+    server.register_handler<&RealClient::get_into_ranges_staged_shm_helper>(
+        &real_client);
     server.register_handler<&RealClient::map_shm_internal>(&real_client);
     server.register_handler<&RealClient::ascend_shm_internal>(&real_client);
     server.register_handler<&RealClient::ascend_ipc_shm_internal>(&real_client);
@@ -104,10 +117,16 @@ int main(int argc, char *argv[]) {
     // spawning threads, leading to missing signal processing.
     mooncake::ResourceTracker::getInstance();
 
+    gflags::SetVersionString(mooncake::MOONCAKE_DISPLAY_VERSION);
     gflags::ParseCommandLineFlags(&argc, &argv, true);
     if (!FLAGS_log_dir.empty()) {
         google::InitGoogleLogging(argv[0]);
     }
+    mooncake::LogAllocatorStatus();
+    mooncake::InstallAllocatorStatsCollector();
+
+    LOG(INFO) << "Mooncake real client version: "
+              << mooncake::MOONCAKE_DISPLAY_VERSION;
 
     size_t global_segment_size = string_to_byte_size(FLAGS_global_segment_size);
     size_t local_buffer_size = string_to_byte_size(FLAGS_local_buffer_size);
diff --git a/mooncake-store/src/registered_pinned_memory.cpp b/mooncake-store/src/registered_pinned_memory.cpp
index 92aecb6917..b9b3351222 100644
--- a/mooncake-store/src/registered_pinned_memory.cpp
+++ b/mooncake-store/src/registered_pinned_memory.cpp
@@ -1,14 +1,9 @@
 #include "registered_pinned_memory.h"
 
-#include <cstdlib>
 #include <string>
-#include <string_view>
 
 #include <glog/logging.h>
 
-#include "ascii_string.h"
-#include "integer_parser.h"
-
 #if defined(USE_CUDA)
 #include <cuda_runtime_api.h>
 #endif
@@ -16,20 +11,6 @@
 namespace mooncake {
 namespace {
 
-std::pair<bool, uint64_t> ParsePinnedMemoryConfig() {
-    const char* raw_value = std::getenv("MC_STORE_PIN_MEMORY_MAX_BYTES");
-    if (!raw_value || raw_value[0] == '\0') return {false, 0};
-
-    const auto limit =
-        TryParseInteger<uint64_t>(TrimAsciiWhitespace(raw_value));
-    if (!limit.has_value()) {
-        LOG(WARNING) << "Invalid MC_STORE_PIN_MEMORY_MAX_BYTES='" << raw_value
-                     << "', disabling Store segment pinning";
-        return {false, 0};
-    }
-    return {*limit != 0, *limit};
-}
-
 void LogPinSkip(const std::string& owner, const char* reason, size_t size) {
     LOG(WARNING) << "Skip cudaHostRegister for " << owner << ": " << reason
                  << ", size=" << size;
@@ -88,18 +69,18 @@ RegisteredPinnedMemoryManager& RegisteredPinnedMemoryManager::instance() {
 }
 
 RegisteredPinnedMemoryManager::RegisteredPinnedMemoryManager()
-    : RegisteredPinnedMemoryManager(ParsePinnedMemoryConfig(),
-                                    DefaultPinOps()) {}
+    : RegisteredPinnedMemoryManager(
+          RegisteredPinnedMemoryConfig::FromEnvironment(), DefaultPinOps()) {}
 
 RegisteredPinnedMemoryManager::RegisteredPinnedMemoryManager(
-    std::pair<bool, uint64_t> config, PinOps pin_ops)
-    : enabled_(config.first), limit_bytes_(config.second), pin_ops_(pin_ops) {
+    RegisteredPinnedMemoryConfig config, PinOps pin_ops)
+    : limit_bytes_(config.max_bytes), pin_ops_(pin_ops) {
 #if defined(USE_CUDA)
     LOG(INFO) << "Store segment pinned memory is "
-              << (enabled_ ? "enabled" : "disabled")
+              << (limit_bytes_ != 0 ? "enabled" : "disabled")
               << ", max_bytes=" << limit_bytes_;
 #else
-    if (enabled_) {
+    if (limit_bytes_ != 0) {
         LOG(INFO) << "Store segment pinning requested but this build has no "
                      "CUDA runtime support";
     }
@@ -108,7 +89,7 @@ RegisteredPinnedMemoryManager::RegisteredPinnedMemoryManager(
 
 std::shared_ptr<RegisteredPinnedRegion> RegisteredPinnedMemoryManager::try_pin(
     void* addr, size_t size, const std::string& owner) {
-    if (!addr || size == 0 || !enabled_) return nullptr;
+    if (!addr || size == 0 || limit_bytes_ == 0) return nullptr;
     if (!pin_ops_.register_region || !pin_ops_.unregister_region) {
         return nullptr;
     }
diff --git a/mooncake-store/src/registered_pinned_memory.h b/mooncake-store/src/registered_pinned_memory.h
index cbc43c1388..f9da64f6b8 100644
--- a/mooncake-store/src/registered_pinned_memory.h
+++ b/mooncake-store/src/registered_pinned_memory.h
@@ -5,9 +5,10 @@
 #include <memory>
 #include <mutex>
 #include <string>
-#include <utility>
 #include <vector>
 
+#include "config/registered_pinned_memory_config.h"
+
 namespace mooncake {
 
 class RegisteredPinnedMemoryManager;
@@ -62,7 +63,7 @@ class RegisteredPinnedMemoryManager {
 #if defined(MOONCAKE_STORE_TEST)
    public:
 #endif
-    RegisteredPinnedMemoryManager(std::pair<bool, uint64_t> config,
+    RegisteredPinnedMemoryManager(RegisteredPinnedMemoryConfig config,
                                   PinOps pin_ops);
 #if defined(MOONCAKE_STORE_TEST)
    private:
@@ -71,7 +72,6 @@ class RegisteredPinnedMemoryManager {
     bool release(RegisteredPinnedRegion* region);
     void remove_inactive_region_locked(void* addr, size_t size);
 
-    const bool enabled_;
     const uint64_t limit_bytes_;
     const PinOps pin_ops_;
 
diff --git a/mooncake-store/src/rpc_service.cpp b/mooncake-store/src/rpc_service.cpp
index c6f3a98604..c9be2bba13 100644
--- a/mooncake-store/src/rpc_service.cpp
+++ b/mooncake-store/src/rpc_service.cpp
@@ -12,7 +12,7 @@
 #include "master_service.h"
 #include "rpc_helper.h"
 #include "types.h"
-#include "utils/scoped_vlog_timer.h"
+#include "common/scoped_vlog_timer.h"
 #include "version.h"
 
 namespace mooncake {
@@ -93,6 +93,15 @@ WrappedMasterService::WrappedMasterService(
 
 WrappedMasterService::~WrappedMasterService() = default;
 
+void WrappedMasterService::SetBatchOpLogTerminalCallback(
+    OrderedOpLogWriter::TerminalCallback callback) {
+    master_service_.SetBatchOpLogTerminalCallback(std::move(callback));
+}
+
+void WrappedMasterService::StopBatchOpLogWriter() {
+    master_service_.StopBatchOpLogWriter();
+}
+
 tl::expected<MasterMetricManager::CacheHitStatDict, ErrorCode>
 WrappedMasterService::CalcCacheStats() {
     return MasterMetricManager::instance().calculate_cache_stats();
@@ -154,6 +163,35 @@ std::vector<tl::expected<bool, ErrorCode>> WrappedMasterService::BatchExistKey(
     return result;
 }
 
+tl::expected<bool, ErrorCode> WrappedMasterService::ProbeKey(
+    const std::string& key, const std::string& tenant_id) {
+    return execute_rpc(
+        "ProbeKey",
+        [&] {
+            return WithRequestTenant(master_service_.IsTenantQuotaEnabled()
+                                         ? std::string_view(tenant_id)
+                                         : TenantId::kDefaultValue,
+                                     [&](const TenantId& resolved_tenant_id) {
+                                         return master_service_.ProbeKey(
+                                             key, resolved_tenant_id);
+                                     });
+        },
+        [&](auto& timer) { timer.LogRequest("key=", key); }, [] {}, [] {});
+}
+
+std::vector<tl::expected<bool, ErrorCode>> WrappedMasterService::BatchProbeKey(
+    const std::vector<std::string>& keys, const std::string& tenant_id) {
+    ScopedVLogTimer timer(1, "BatchProbeKey");
+    timer.LogRequest("keys_count=", keys.size());
+
+    return WithRequestTenantBatch(
+        master_service_.IsTenantQuotaEnabled() ? std::string_view(tenant_id)
+                                               : TenantId::kDefaultValue,
+        keys.size(), [&](const TenantId& resolved_tenant_id) {
+            return master_service_.BatchProbeKey(keys, resolved_tenant_id);
+        });
+}
+
 tl::expected<
     std::unordered_map<UUID, std::vector<std::string>, boost::hash<UUID>>,
     ErrorCode>
@@ -197,17 +235,23 @@ WrappedMasterService::BatchQueryIp(const std::vector<UUID>& client_ids) {
 tl::expected<std::vector<std::string>, ErrorCode>
 WrappedMasterService::BatchReplicaClear(
     const std::vector<std::string>& object_keys, const UUID& client_id,
-    const std::string& segment_name) {
+    const std::string& segment_name, const std::string& tenant_id) {
     ScopedVLogTimer timer(1, "BatchReplicaClear");
     const size_t total_keys = object_keys.size();
     timer.LogRequest("object_keys_count=", total_keys,
-                     ", client_id=", client_id,
-                     ", segment_name=", segment_name);
+                     ", client_id=", client_id, ", segment_name=", segment_name,
+                     ", tenant_id=", tenant_id);
     MasterMetricManager::instance().inc_batch_replica_clear_requests(
         total_keys);
 
-    auto result =
-        master_service_.BatchReplicaClear(object_keys, client_id, segment_name);
+    auto result = WithRequestTenant(
+        master_service_.IsTenantQuotaEnabled() ? std::string_view(tenant_id)
+                                               : TenantId::kDefaultValue,
+        [&](const TenantId& resolved_tenant_id) {
+            return master_service_.BatchReplicaClear(
+                object_keys, client_id, segment_name,
+                resolved_tenant_id.value());
+        });
 
     size_t failure_count = 0;
     if (!result.has_value()) {
@@ -366,7 +410,7 @@ WrappedMasterService::PutStart(const UUID& client_id, const std::string& key,
                                const uint64_t slice_length,
                                const ReplicateConfig& config,
                                const std::string& tenant_id) {
-    return execute_rpc(
+    auto result = execute_rpc(
         "PutStart",
         [&] {
             return WithWriteTenant(tenant_id,
@@ -383,6 +427,10 @@ WrappedMasterService::PutStart(const UUID& client_id, const std::string& key,
         },
         [&] { MasterMetricManager::instance().inc_put_start_requests(); },
         [] { MasterMetricManager::instance().inc_put_start_failures(); });
+    if (!result && result.error() == ErrorCode::OBJECT_ALREADY_EXISTS) {
+        MasterMetricManager::instance().inc_put_start_object_already_exists();
+    }
+    return result;
 }
 
 tl::expected<void, ErrorCode> WrappedMasterService::PutEnd(
@@ -497,14 +545,14 @@ WrappedMasterService::BatchPutStart(const UUID& client_id,
     }
 
     size_t failure_count = 0;
+    int64_t already_exists_count = 0;
     int no_available_handle_count = 0;
     for (size_t i = 0; i < results.size(); ++i) {
         if (!results[i].has_value()) {
             failure_count++;
             auto error = results[i].error();
             if (error == ErrorCode::OBJECT_ALREADY_EXISTS) {
-                VLOG(1) << "BatchPutStart failed for key[" << i << "] '"
-                        << keys[i] << "': " << toString(error);
+                ++already_exists_count;
             } else if (error == ErrorCode::NO_AVAILABLE_HANDLE) {
                 no_available_handle_count++;
             } else {
@@ -514,6 +562,9 @@ WrappedMasterService::BatchPutStart(const UUID& client_id,
         }
     }
 
+    MasterMetricManager::instance().inc_batch_put_start_object_already_exists(
+        already_exists_count);
+
     if (no_available_handle_count > 0) {
         LOG(WARNING) << "BatchPutStart failed for " << no_available_handle_count
                      << " keys" << PUT_NO_SPACE_HELPER_STR;
@@ -1083,6 +1134,35 @@ tl::expected<CopyStartResponse, ErrorCode> WrappedMasterService::CopyStart(
         [] { MasterMetricManager::instance().inc_copy_start_failures(); });
 }
 
+tl::expected<CopyStartResponse, ErrorCode>
+WrappedMasterService::DynamicReplicaCopyStart(
+    const UUID& client_id, const std::string& key, const std::string& tenant_id,
+    const std::string& src_segment,
+    const std::vector<std::string>& tgt_segments,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    return execute_rpc(
+        "DynamicReplicaCopyStart",
+        [&] {
+            return WithWriteTenant(
+                tenant_id, master_service_.IsTenantQuotaEnabled(),
+                [&](const TenantId& resolved_tenant_id) {
+                    return master_service_.CopyStart(
+                        client_id, key, resolved_tenant_id, src_segment,
+                        tgt_segments, dynamic_replication_lease_id,
+                        dynamic_replication_version_epoch);
+                });
+        },
+        [&](auto& timer) {
+            timer.LogRequest("client_id=", client_id, ", key=", key,
+                             ", tenant_id=", tenant_id,
+                             ", src_segment=", src_segment,
+                             ", tgt_segments_count=", tgt_segments.size());
+        },
+        [] { MasterMetricManager::instance().inc_copy_start_requests(); },
+        [] { MasterMetricManager::instance().inc_copy_start_failures(); });
+}
+
 tl::expected<void, ErrorCode> WrappedMasterService::CopyEnd(
     const UUID& client_id, const std::string& key,
     const std::string& tenant_id) {
@@ -1106,6 +1186,31 @@ tl::expected<void, ErrorCode> WrappedMasterService::CopyEnd(
         [] { MasterMetricManager::instance().inc_copy_end_failures(); });
 }
 
+tl::expected<void, ErrorCode> WrappedMasterService::DynamicReplicaCopyEnd(
+    const UUID& client_id, const std::string& key, const std::string& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    return execute_rpc(
+        "DynamicReplicaCopyEnd",
+        [&] {
+            return WithRequestTenant(master_service_.IsTenantQuotaEnabled()
+                                         ? std::string_view(tenant_id)
+                                         : TenantId::kDefaultValue,
+                                     [&](const TenantId& resolved_tenant_id) {
+                                         return master_service_.CopyEnd(
+                                             client_id, key, resolved_tenant_id,
+                                             dynamic_replication_lease_id,
+                                             dynamic_replication_version_epoch);
+                                     });
+        },
+        [&](auto& timer) {
+            timer.LogRequest("client_id=", client_id, ", key=", key,
+                             ", tenant_id=", tenant_id);
+        },
+        [] { MasterMetricManager::instance().inc_copy_end_requests(); },
+        [] { MasterMetricManager::instance().inc_copy_end_failures(); });
+}
+
 tl::expected<void, ErrorCode> WrappedMasterService::CopyRevoke(
     const UUID& client_id, const std::string& key,
     const std::string& tenant_id) {
@@ -1129,6 +1234,31 @@ tl::expected<void, ErrorCode> WrappedMasterService::CopyRevoke(
         [] { MasterMetricManager::instance().inc_copy_revoke_failures(); });
 }
 
+tl::expected<void, ErrorCode> WrappedMasterService::DynamicReplicaCopyRevoke(
+    const UUID& client_id, const std::string& key, const std::string& tenant_id,
+    const UUID& dynamic_replication_lease_id,
+    uint64_t dynamic_replication_version_epoch) {
+    return execute_rpc(
+        "DynamicReplicaCopyRevoke",
+        [&] {
+            return WithRequestTenant(master_service_.IsTenantQuotaEnabled()
+                                         ? std::string_view(tenant_id)
+                                         : TenantId::kDefaultValue,
+                                     [&](const TenantId& resolved_tenant_id) {
+                                         return master_service_.CopyRevoke(
+                                             client_id, key, resolved_tenant_id,
+                                             dynamic_replication_lease_id,
+                                             dynamic_replication_version_epoch);
+                                     });
+        },
+        [&](auto& timer) {
+            timer.LogRequest("client_id=", client_id, ", key=", key,
+                             ", tenant_id=", tenant_id);
+        },
+        [] { MasterMetricManager::instance().inc_copy_revoke_requests(); },
+        [] { MasterMetricManager::instance().inc_copy_revoke_failures(); });
+}
+
 tl::expected<MoveStartResponse, ErrorCode> WrappedMasterService::MoveStart(
     const UUID& client_id, const std::string& key, const std::string& tenant_id,
     const std::string& src_segment, const std::string& tgt_segment) {
@@ -1383,6 +1513,11 @@ tl::expected<std::string, ErrorCode> WrappedMasterService::ServiceReady() {
     return GetMooncakeStoreVersion();
 }
 
+TieredStorageUsageSnapshot WrappedMasterService::GetStorageUsageSnapshot()
+    const {
+    return master_service_.GetStorageUsageSnapshot();
+}
+
 tl::expected<std::vector<TenantQuotaSnapshot>, ErrorCode>
 WrappedMasterService::ListTenantQuotaSnapshots() {
     if (!master_service_.IsTenantQuotaEnabled()) {
@@ -1484,6 +1619,17 @@ tl::expected<void, ErrorCode> WrappedMasterService::MountLocalDiskSegment(
     return result;
 }
 
+tl::expected<void, ErrorCode> WrappedMasterService::UnmountLocalDiskSegment(
+    const UUID& client_id) {
+    ScopedVLogTimer timer(1, "UnmountLocalDiskSegment");
+    timer.LogRequest("action=unmount_local_disk_segment");
+    LOG(INFO) << "Unmount local disk segment with client id is : " << client_id;
+    auto result = master_service_.UnmountLocalDiskSegment(client_id);
+
+    timer.LogResponseExpected(result);
+    return result;
+}
+
 tl::expected<std::vector<OffloadTaskItem>, ErrorCode>
 WrappedMasterService::OffloadObjectHeartbeat(const UUID& client_id,
                                              bool enable_offloading) {
@@ -1593,6 +1739,15 @@ tl::expected<void, ErrorCode> WrappedMasterService::NotifyPromotionFailure(
     return result;
 }
 
+tl::expected<int, ErrorCode> WrappedMasterService::GetDfsShardCount() const {
+    return master_service_.GetDfsShardCount();
+}
+
+tl::expected<int, ErrorCode> WrappedMasterService::ExpandDfsShards(
+    int shard_count) {
+    return master_service_.ExpandDfsShards(shard_count);
+}
+
 tl::expected<UUID, ErrorCode> WrappedMasterService::CreateDrainJob(
     const CreateDrainJobRequest& request) {
     return master_service_.CreateDrainJob(request);
@@ -1626,19 +1781,28 @@ KvEventPublisher::Stats WrappedMasterService::GetKvEventStats() const {
     return master_service_.GetKvEventStats();
 }
 
-void WrappedMasterService::RestoreFromStandby(
+tl::expected<void, ErrorCode> WrappedMasterService::RestoreFromStandby(
     const std::vector<StandbyObjectEntry>& objects,
     uint64_t initial_oplog_sequence_id,
     const std::vector<StandbySegmentInfo>& segments) {
-    master_service_.RestoreFromStandbySnapshot(
+    return master_service_.RestoreFromStandbySnapshot(
         objects, initial_oplog_sequence_id, segments);
 }
 
+tl::expected<void, ErrorCode>
+WrappedMasterService::RestoreFromBatchOpLogPromotion(
+    BatchOpLogPromotionHandoff handoff, size_t chunk_object_count) {
+    return master_service_.RestoreFromBatchOpLogPromotion(std::move(handoff),
+                                                          chunk_object_count);
+}
+
 void RegisterRpcService(
     coro_rpc::coro_rpc_server& server,
     mooncake::WrappedMasterService& wrapped_master_service) {
     server.register_handler<&mooncake::WrappedMasterService::ExistKey>(
         &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::ProbeKey>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchQueryIp>(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchReplicaClear>(
@@ -1717,11 +1881,16 @@ void RegisterRpcService(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::BatchExistKey>(
         &wrapped_master_service);
+    server.register_handler<&mooncake::WrappedMasterService::BatchProbeKey>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::ServiceReady>(
         &wrapped_master_service);
     server.register_handler<
         &mooncake::WrappedMasterService::MountLocalDiskSegment>(
         &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::UnmountLocalDiskSegment>(
+        &wrapped_master_service);
     server.register_handler<
         &mooncake::WrappedMasterService::OffloadObjectHeartbeat>(
         &wrapped_master_service);
@@ -1744,10 +1913,19 @@ void RegisterRpcService(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::CopyStart>(
         &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::DynamicReplicaCopyStart>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::CopyEnd>(
         &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::DynamicReplicaCopyEnd>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::CopyRevoke>(
         &wrapped_master_service);
+    server.register_handler<
+        &mooncake::WrappedMasterService::DynamicReplicaCopyRevoke>(
+        &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::MoveStart>(
         &wrapped_master_service);
     server.register_handler<&mooncake::WrappedMasterService::MoveEnd>(
diff --git a/mooncake-store/src/segment.cpp b/mooncake-store/src/segment.cpp
index 8f5b1af04e..04a85e5b9e 100644
--- a/mooncake-store/src/segment.cpp
+++ b/mooncake-store/src/segment.cpp
@@ -1,32 +1,24 @@
 #include "segment.h"
 
+#include "ha/snapshot/local_ssd_codec.h"
 #include "master_metric_manager.h"
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 #include <functional>
-
 namespace mooncake {
 namespace {
 
-bool HasAllocator(const AllocatorManager& allocator_manager,
-                  const std::string& segment_name,
-                  const std::shared_ptr<BufferAllocatorBase>& allocator) {
-    if (!allocator) {
-        return false;
-    }
+bool HasAllocatorRegistration(
+    const AllocatorManager& allocator_manager, const std::string& segment_name,
+    const std::shared_ptr<SegmentAllocatorRegistration>& registration) {
     const auto* allocators = allocator_manager.getAllocators(segment_name);
     if (allocators == nullptr) {
         return false;
     }
-    return std::find(allocators->begin(), allocators->end(), allocator) !=
+    return std::find(allocators->begin(), allocators->end(), registration) !=
            allocators->end();
 }
 
-bool IsMsgpackInteger(const msgpack::object& object) {
-    return object.type == msgpack::type::POSITIVE_INTEGER ||
-           object.type == msgpack::type::NEGATIVE_INTEGER;
-}
-
 void AddHostSegment(HostSegmentIndex& index, const Segment& segment) {
     if (!segment.host_id.empty()) {
         index[segment.host_id][segment.name].insert(segment.id);
@@ -99,6 +91,27 @@ std::vector<std::string> BuildHostOrderedSegments(
     return ordered_segments;
 }
 
+void AddAllocatorUsage(
+    StorageUsageSnapshot& snapshot,
+    const std::shared_ptr<BufferAllocatorBase>& allocator,
+    std::unordered_set<const BufferAllocatorBase*>& counted_allocators) {
+    if (!allocator || !counted_allocators.insert(allocator.get()).second) {
+        return;
+    }
+
+    const size_t used_bytes = allocator->size();
+    const size_t capacity_bytes = allocator->capacity();
+    snapshot.used_bytes += used_bytes;
+    snapshot.capacity_bytes += capacity_bytes;
+
+    const std::string segment_name = allocator->getSegmentName();
+    if (!segment_name.empty()) {
+        auto& segment = snapshot.segments[segment_name];
+        segment.used_bytes += used_bytes;
+        segment.capacity_bytes += capacity_bytes;
+    }
+}
+
 }  // namespace
 
 std::vector<std::string> ScopedAllocatorAccess::GetHostOrderedSegments(
@@ -109,8 +122,88 @@ std::vector<std::string> ScopedAllocatorAccess::GetHostOrderedSegments(
     return BuildHostOrderedSegments(*segments_by_host_, writer_host_id, key);
 }
 
-ErrorCode ScopedSegmentAccess::MountSegment(const Segment& segment,
-                                            const UUID& client_id) {
+StorageUsageSnapshot SegmentManager::GetMemoryUsageSnapshot() const {
+    std::shared_lock<std::shared_mutex> lock(segment_mutex_);
+    StorageUsageSnapshot snapshot;
+    std::unordered_set<const BufferAllocatorBase*> counted_allocators;
+
+    // The CXL allocator is owned by SegmentManager independently of client
+    // mounts and may be shared by multiple mounted segment records.
+    AddAllocatorUsage(snapshot, cxl_global_allocator_, counted_allocators);
+
+    for (const auto& [segment_id, mounted_segment] : mounted_segments_) {
+        (void)segment_id;
+        AddAllocatorUsage(snapshot, mounted_segment.buf_allocator,
+                          counted_allocators);
+    }
+    return snapshot;
+}
+
+void SegmentManager::AttachMountedUsageTrackers() {
+    std::unordered_set<const BufferAllocatorBase*> attached_allocators;
+    if (cxl_global_allocator_) {
+        cxl_global_allocator_->AttachUsageTracker(usage_tracker_);
+        attached_allocators.insert(cxl_global_allocator_.get());
+    }
+    for (auto& [segment_id, mounted_segment] : mounted_segments_) {
+        (void)segment_id;
+        auto& allocator = mounted_segment.buf_allocator;
+        if (allocator && attached_allocators.insert(allocator.get()).second) {
+            allocator->AttachUsageTracker(usage_tracker_);
+        }
+    }
+}
+
+std::optional<UUID> ScopedAllocatorAccess::GetOwnerClientId(
+    const std::string& segment_name) const {
+    if (client_by_name_ == nullptr) {
+        return std::nullopt;
+    }
+    auto it = client_by_name_->find(segment_name);
+    if (it == client_by_name_->end()) {
+        return std::nullopt;
+    }
+    return it->second;
+}
+
+ErrorCode ScopedSegmentAccess::MountSegment(
+    const Segment& segment, const UUID& client_id,
+    std::shared_ptr<ClientLivenessRecord> client_liveness) {
+    const auto indexed_name =
+        segment_manager_->segment_id_by_name_.find(segment.name);
+    if (indexed_name != segment_manager_->segment_id_by_name_.end()) {
+        const auto indexed_segment =
+            segment_manager_->mounted_segments_.find(indexed_name->second);
+        if (indexed_segment == segment_manager_->mounted_segments_.end()) {
+            // Offboarding retains this name until its durable unmount record
+            // has been accepted. Live same-name Segments remain supported.
+            return ErrorCode::INVALID_PARAMS;
+        }
+        if (indexed_segment->second.status == SegmentStatus::UNMOUNTING) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+    }
+    // SEGMENT_ALREADY_EXISTS is a liveness signal only for a confirmed replay
+    // of the same mount. Keep this common to every memory protocol, including
+    // CXL, instead of letting protocol-specific branches bypass it.
+    auto existing = segment_manager_->mounted_segments_.find(segment.id);
+    if (existing != segment_manager_->mounted_segments_.end()) {
+        if (existing->second.status != SegmentStatus::OK) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+        const auto owner = segment_manager_->client_segments_.find(client_id);
+        const bool owned = owner != segment_manager_->client_segments_.end() &&
+                           std::find(owner->second.begin(), owner->second.end(),
+                                     segment.id) != owner->second.end();
+        const auto& mounted = existing->second.segment;
+        if (!owned || mounted.name != segment.name ||
+            mounted.base != segment.base || mounted.size != segment.size ||
+            mounted.te_endpoint != segment.te_endpoint ||
+            mounted.protocol != segment.protocol) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+        return ErrorCode::SEGMENT_ALREADY_EXISTS;
+    }
     const uintptr_t buffer = segment.base;
     const size_t size = segment.size;
 
@@ -124,11 +217,12 @@ ErrorCode ScopedSegmentAccess::MountSegment(const Segment& segment,
                 LOG(ERROR) << "Cxl global allocator has not been initialized.";
                 return ErrorCode::INTERNAL_ERROR;
             }
-            segment_manager_->allocator_manager_.addAllocator(segment.name,
-                                                              allocator);
+            auto registration =
+                segment_manager_->allocator_manager_.addAllocator(
+                    segment.name, allocator, std::move(client_liveness));
             segment_manager_->client_segments_[client_id].push_back(segment.id);
             segment_manager_->mounted_segments_[segment.id] = {
-                segment, SegmentStatus::OK, allocator};
+                segment, SegmentStatus::OK, allocator, registration};
             segment_manager_->client_by_name_[segment.name] = client_id;
             segment_manager_->segment_id_by_name_[segment.name] = segment.id;
             AddHostSegment(segment_manager_->segments_by_host_, segment);
@@ -157,60 +251,20 @@ ErrorCode ScopedSegmentAccess::MountSegment(const Segment& segment,
         return ErrorCode::INVALID_PARAMS;
     }
 
-    // Check if segment already exists
-    auto exist_segment_it =
-        segment_manager_->mounted_segments_.find(segment.id);
-    if (exist_segment_it != segment_manager_->mounted_segments_.end()) {
-        auto& exist_segment = exist_segment_it->second;
-        if (exist_segment.status == SegmentStatus::OK) {
-            LOG(WARNING) << "segment_name=" << segment.name
-                         << ", warn=segment_already_exists";
-            return ErrorCode::SEGMENT_ALREADY_EXISTS;
-        } else {
-            LOG(ERROR) << "segment_name=" << segment.name
-                       << ", error=segment_already_exists_but_not_ok"
-                       << ", status=" << exist_segment.status;
-            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
-        }
+    auto created =
+        CreateBufferAllocator(segment_manager_->memory_allocator_, segment.name,
+                              buffer, size, segment.te_endpoint);
+    if (!created) {
+        return created.error();
     }
+    auto allocator = std::move(*created);
 
-    std::shared_ptr<BufferAllocatorBase> allocator;
-    // CachelibBufferAllocator may throw an exception if the size or base is
-    // invalid for the slab allocator.
-    try {
-        // Create allocator based on the configured type
-        switch (segment_manager_->memory_allocator_) {
-            case BufferAllocatorType::CACHELIB:
-                allocator = std::make_shared<CachelibBufferAllocator>(
-                    segment.name, buffer, size, segment.te_endpoint);
-                break;
-            case BufferAllocatorType::OFFSET:
-                allocator = std::make_shared<OffsetBufferAllocator>(
-                    segment.name, buffer, size, segment.te_endpoint);
-                break;
-            default:
-                LOG(ERROR) << "segment_name=" << segment.name
-                           << ", error=unknown_memory_allocator="
-                           << static_cast<int>(
-                                  segment_manager_->memory_allocator_);
-                return ErrorCode::INVALID_PARAMS;
-        }
-
-        if (!allocator) {
-            LOG(ERROR) << "segment_name=" << segment.name
-                       << ", error=failed_to_create_allocator";
-            return ErrorCode::INVALID_PARAMS;
-        }
-    } catch (...) {
-        LOG(ERROR) << "segment_name=" << segment.name
-                   << ", error=exception_during_allocator_creation";
-        return ErrorCode::INVALID_PARAMS;
-    }
-
-    segment_manager_->allocator_manager_.addAllocator(segment.name, allocator);
+    allocator->AttachUsageTracker(segment_manager_->usage_tracker_);
+    auto registration = segment_manager_->allocator_manager_.addAllocator(
+        segment.name, allocator, std::move(client_liveness));
     segment_manager_->client_segments_[client_id].push_back(segment.id);
     segment_manager_->mounted_segments_[segment.id] = {
-        segment, SegmentStatus::OK, std::move(allocator)};
+        segment, SegmentStatus::OK, std::move(allocator), registration};
     segment_manager_->client_by_name_[segment.name] = client_id;
     segment_manager_->segment_id_by_name_[segment.name] = segment.id;
     AddHostSegment(segment_manager_->segments_by_host_, segment);
@@ -219,29 +273,51 @@ ErrorCode ScopedSegmentAccess::MountSegment(const Segment& segment,
     return ErrorCode::OK;
 }
 
-ErrorCode ScopedSegmentAccess::MountLocalDiskSegment(const UUID& client_id,
-                                                     bool enable_offloading) {
-    auto exist_segment_it =
-        segment_manager_->client_local_disk_segment_.find(client_id);
-    if (exist_segment_it !=
-        segment_manager_->client_local_disk_segment_.end()) {
-        LOG(WARNING) << "client_id=" << client_id
-                     << ", warn=local_disk_segment_already_exists";
-        return ErrorCode::SEGMENT_ALREADY_EXISTS;
+void ScopedSegmentAccess::BindClientLiveness(
+    const UUID& client_id,
+    const std::shared_ptr<ClientLivenessRecord>& client_liveness) {
+    const auto client_segments_it =
+        segment_manager_->client_segments_.find(client_id);
+    if (client_segments_it != segment_manager_->client_segments_.end()) {
+        for (const auto& segment_id : client_segments_it->second) {
+            auto mounted_it =
+                segment_manager_->mounted_segments_.find(segment_id);
+            if (mounted_it != segment_manager_->mounted_segments_.end() &&
+                mounted_it->second.allocator_registration) {
+                mounted_it->second.allocator_registration->BindClientLiveness(
+                    client_liveness);
+            }
+        }
     }
-    segment_manager_->client_local_disk_segment_.emplace(
-        client_id, std::make_shared<LocalDiskSegment>(enable_offloading));
-    return ErrorCode::OK;
+}
+
+void ScopedSegmentAccess::BindBufferToSegment(const UUID& segment_id,
+                                              AllocatedBuffer& buffer) {
+    segment_manager_->mounted_segments_.at(segment_id)
+        .allocator_registration->BindBuffer(buffer);
+}
+
+bool ScopedSegmentAccess::RebindBufferToOwningSegment(AllocatedBuffer& buffer) {
+    for (auto& [segment_id, mounted] : segment_manager_->mounted_segments_) {
+        (void)segment_id;
+        if (mounted.allocator_registration &&
+            mounted.allocator_registration->OwnsBuffer(buffer)) {
+            mounted.allocator_registration->BindBuffer(buffer);
+            return true;
+        }
+    }
+    return false;
 }
 
 ErrorCode ScopedSegmentAccess::ReMountSegment(
-    const std::vector<Segment>& segments, const UUID& client_id) {
+    const std::vector<Segment>& segments, const UUID& client_id,
+    std::shared_ptr<ClientLivenessRecord> client_liveness) {
     for (const auto& segment : segments) {
         auto validation = ValidateRemountSegment(segment, client_id);
         if (validation != ErrorCode::OK) {
             return validation;
         }
-        ErrorCode err = MountSegment(segment, client_id);
+        ErrorCode err = MountSegment(segment, client_id, client_liveness);
         if (err == ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS ||
             err == ErrorCode::INTERNAL_ERROR) {
             LOG(ERROR) << "segment_name=" << segment.name
@@ -308,7 +384,9 @@ bool ScopedSegmentAccess::ReplaceAllocators(
         auto mounted =
             segment_manager_->mounted_segments_.find(replacement.segment_id);
         if (mounted == segment_manager_->mounted_segments_.end() ||
-            mounted->second.buf_allocator != replacement.expected ||
+            !mounted->second.allocator_registration ||
+            mounted->second.allocator_registration->GetAllocator() !=
+                replacement.expected ||
             !replacement.replacement) {
             return false;
         }
@@ -321,6 +399,10 @@ bool ScopedSegmentAccess::ReplaceAllocators(
         return false;
     }
     for (const auto& replacement : replacements) {
+        if (replacement.expected != replacement.replacement) {
+            replacement.replacement->AttachUsageTracker(
+                segment_manager_->usage_tracker_);
+        }
         segment_manager_->mounted_segments_.at(replacement.segment_id)
             .buf_allocator = replacement.replacement;
     }
@@ -354,18 +436,23 @@ ErrorCode ScopedSegmentAccess::PrepareUnmountSegment(
     metrics_dec_capacity = segment.size;
 
     // Remove the allocator from the segment manager
-    std::shared_ptr<BufferAllocatorBase> allocator =
-        mounted_segment.buf_allocator;
+    auto registration = mounted_segment.allocator_registration;
 
     // 1. Remove from allocators if the segment is still allocatable.
-    if (HasAllocator(segment_manager_->allocator_manager_, segment.name,
-                     allocator)) {
+    if (HasAllocatorRegistration(segment_manager_->allocator_manager_,
+                                 segment.name, registration)) {
         segment_manager_->allocator_manager_.removeAllocator(segment.name,
-                                                             allocator);
+                                                             registration);
     }
     RemoveHostSegment(segment_manager_->segments_by_host_, segment);
 
-    // 2. Remove from mounted_segment
+    // 2. Invalidate detached allocation snapshots and existing buffers, then
+    // remove the registration from mounted_segment. Do not detach usage here:
+    // in-flight deallocate calls hold a local shared_ptr and must finish first.
+    // The allocator destructor RAII-detaches when the last shared_ptr is
+    // dropped.
+    registration->Invalidate();
+    mounted_segment.allocator_registration.reset();
     mounted_segment.buf_allocator.reset();
 
     // Set the segment status to UNMOUNTING
@@ -402,22 +489,66 @@ ErrorCode ScopedSegmentAccess::PrepareGracefulUnmountSegment(
     auto& segment = mounted_segment.segment;
 
     // Remove the allocator from the segment manager
-    std::shared_ptr<BufferAllocatorBase> allocator =
-        mounted_segment.buf_allocator;
-    if (HasAllocator(segment_manager_->allocator_manager_, segment.name,
-                     allocator)) {
+    auto registration = mounted_segment.allocator_registration;
+    if (HasAllocatorRegistration(segment_manager_->allocator_manager_,
+                                 segment.name, registration)) {
         segment_manager_->allocator_manager_.removeAllocator(segment.name,
-                                                             allocator);
+                                                             registration);
     }
+    registration->SetAllocatable(false);
     RemoveHostSegment(segment_manager_->segments_by_host_, segment);
     // Set the segment status to GRACEFULLY_UNMOUNTING
     mounted_segment.status = SegmentStatus::GRACEFULLY_UNMOUNTING;
     return ErrorCode::OK;
 }
 
+void ScopedSegmentAccess::ReindexSegmentNameAfterRemoval(
+    const UUID& removed_segment_id, const std::string& segment_name) {
+    const auto indexed =
+        segment_manager_->segment_id_by_name_.find(segment_name);
+    if (indexed == segment_manager_->segment_id_by_name_.end() ||
+        indexed->second != removed_segment_id) {
+        return;
+    }
+
+    segment_manager_->segment_id_by_name_.erase(indexed);
+    segment_manager_->client_by_name_.erase(segment_name);
+
+    const auto bind_remaining = [&](bool require_ok) {
+        for (const auto& [candidate_id, mounted] :
+             segment_manager_->mounted_segments_) {
+            if (candidate_id == removed_segment_id ||
+                mounted.segment.name != segment_name ||
+                (require_ok && mounted.status != SegmentStatus::OK)) {
+                continue;
+            }
+            for (const auto& [owner, segment_ids] :
+                 segment_manager_->client_segments_) {
+                if (std::find(segment_ids.begin(), segment_ids.end(),
+                              candidate_id) != segment_ids.end()) {
+                    segment_manager_->segment_id_by_name_[segment_name] =
+                        candidate_id;
+                    segment_manager_->client_by_name_[segment_name] = owner;
+                    return true;
+                }
+            }
+        }
+        return false;
+    };
+
+    if (!bind_remaining(/*require_ok=*/true)) {
+        (void)bind_remaining(/*require_ok=*/false);
+    }
+}
+
 ErrorCode ScopedSegmentAccess::CommitUnmountSegment(
     const UUID& segment_id, const UUID& client_id,
-    const size_t& metrics_dec_capacity) {
+    const size_t& metrics_dec_capacity, bool retain_name_registration) {
+    auto mounted = segment_manager_->mounted_segments_.find(segment_id);
+    if (mounted == segment_manager_->mounted_segments_.end()) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+
     // Remove from client_segments_
     bool found_in_client_segments = false;
     auto client_it = segment_manager_->client_segments_.find(client_id);
@@ -439,35 +570,34 @@ ErrorCode ScopedSegmentAccess::CommitUnmountSegment(
     }
 
     // segment_id -> segment_name
-    std::string segment_name;
-    bool is_cxl = false;
-    auto&& segment = segment_manager_->mounted_segments_.find(segment_id);
-    if (segment != segment_manager_->mounted_segments_.end()) {
-        segment_name = segment->second.segment.name;
-        RemoveHostSegment(segment_manager_->segments_by_host_,
-                          segment->second.segment);
-        auto segment_id_by_name_it =
-            segment_manager_->segment_id_by_name_.find(segment_name);
-        if (segment_id_by_name_it !=
-                segment_manager_->segment_id_by_name_.end() &&
-            segment_id_by_name_it->second == segment_id) {
-            segment_manager_->segment_id_by_name_.erase(segment_id_by_name_it);
-            segment_manager_->client_by_name_.erase(segment_name);
-        }
-        is_cxl = (segment->second.segment.protocol == "cxl");
+    const std::string segment_name = mounted->second.segment.name;
+    const bool is_cxl = mounted->second.segment.protocol == "cxl";
+    RemoveHostSegment(segment_manager_->segments_by_host_,
+                      mounted->second.segment);
+    if (!retain_name_registration) {
+        ReindexSegmentNameAfterRemoval(segment_id, segment_name);
     }
     // Remove from mounted_segments_
-    segment_manager_->mounted_segments_.erase(segment_id);
+    segment_manager_->mounted_segments_.erase(mounted);
 
     // Decrease the total capacity
     if (!is_cxl) {
         MasterMetricManager::instance().dec_total_mem_capacity(
             segment_name, metrics_dec_capacity);
+        // Remove per-segment metric labels entirely to avoid stale 0-value
+        // entries persisting in Prometheus output (e.g. after snapshot
+        // restore followed by client expiry / reaper cleanup).
+        MasterMetricManager::instance().remove_segment_metrics(segment_name);
     }
 
     return ErrorCode::OK;
 }
 
+void ScopedSegmentAccess::ReleaseUnmountedSegmentName(
+    const UUID& segment_id, const std::string& segment_name) {
+    ReindexSegmentNameAfterRemoval(segment_id, segment_name);
+}
+
 ErrorCode ScopedSegmentAccess::GetClientSegments(
     const UUID& client_id, std::vector<Segment>& segments) const {
     auto it = segment_manager_->client_segments_.find(client_id);
@@ -484,29 +614,6 @@ ErrorCode ScopedSegmentAccess::GetClientSegments(
     return ErrorCode::OK;
 }
 
-void ScopedSegmentAccess::UnmountLocalDiskSegment(const UUID& client_id) {
-    auto it = segment_manager_->client_local_disk_segment_.find(client_id);
-    if (it != segment_manager_->client_local_disk_segment_.end()) {
-        // Hold offloading_mutex_ while reading ssd_total_capacity_bytes to
-        // avoid a data race with OffloadObjectHeartbeat, which writes the
-        // field under the same lock.  Release the lock before erase() so we
-        // don't unlock an already-destroyed mutex (erase destroys the
-        // LocalDiskSegment, including its mutex).
-        int64_t reported_capacity = 0;
-        {
-            MutexLocker locker(&it->second->offloading_mutex_);
-            reported_capacity = it->second->ssd_total_capacity_bytes;
-        }
-        if (reported_capacity > 0) {
-            MasterMetricManager::instance().dec_total_file_capacity(
-                reported_capacity);
-        }
-        segment_manager_->client_local_disk_segment_.erase(it);
-        LOG(INFO) << "client_id=" << client_id
-                  << ", action=unmount_local_disk_segment";
-    }
-}
-
 ErrorCode ScopedSegmentAccess::GetAllSegments(
     std::vector<std::string>& all_segments) {
     all_segments.clear();
@@ -524,10 +631,16 @@ ErrorCode ScopedSegmentAccess::GetAllSegments(
 
     for (auto& segment_pair : segment_manager_->mounted_segments_) {
         UUID client_id{0, 0};
-        auto client_it = segment_manager_->client_by_name_.find(
-            segment_pair.second.segment.name);
-        if (client_it != segment_manager_->client_by_name_.end()) {
-            client_id = client_it->second;
+        // client_by_name_ is intentionally lossy because several Clients may
+        // mount Segments with the same hostname. Resolve exact ownership from
+        // the canonical client_id -> segment_ids relation.
+        for (const auto& [owner, segment_ids] :
+             segment_manager_->client_segments_) {
+            if (std::find(segment_ids.begin(), segment_ids.end(),
+                          segment_pair.first) != segment_ids.end()) {
+                client_id = owner;
+                break;
+            }
         }
 
         all_segments.emplace_back(segment_pair.second.segment, client_id);
@@ -556,7 +669,8 @@ ErrorCode ScopedSegmentAccess::QuerySegments(const std::string& segment,
     const auto& allocator_manager = segment_manager_->allocator_manager_;
     const auto& allocators = allocator_manager.getAllocators(segment);
     if (allocators != nullptr) {
-        for (const auto& allocator : *allocators) {
+        for (const auto& registration : *allocators) {
+            const auto allocator = registration->GetAllocator();
             total_used += allocator->size();
             total_capacity += allocator->capacity();
         }
@@ -637,11 +751,11 @@ ErrorCode SegmentView::GetMountedSegment(const UUID& segment_id,
 }
 
 tl::expected<std::vector<uint8_t>, SerializationError>
-SegmentSerializer::Serialize() {
+SegmentSerializer::Serialize(const LocalSsdPersistedState& local_ssd_state) {
     if (!segment_manager_) {
-        return tl::unexpected(SerializationError(
-            ErrorCode::SERIALIZE_FAIL,
-            "serialize SegmentManager segment_manager_ is null"));
+        return tl::unexpected(
+            SerializationError(ErrorCode::SERIALIZE_FAIL,
+                               "serialize SegmentManager dependency is null"));
     }
 
     if (segment_manager_->memory_allocator_ != BufferAllocatorType::OFFSET) {
@@ -725,48 +839,10 @@ SegmentSerializer::Serialize() {
         }
     }
 
-    // Serialize client_local_disk_segment_
-    // Sort client UUIDs first to ensure deterministic serialization results
     packer.pack("ld");  // local_disk_segments
-    packer.pack_map(segment_manager_->client_local_disk_segment_.size());
-
-    // Collect all client UUIDs and sort
-    std::vector<UUID> sorted_ld_uuids;
-    sorted_ld_uuids.reserve(
-        segment_manager_->client_local_disk_segment_.size());
-    for (const auto& pair : segment_manager_->client_local_disk_segment_) {
-        sorted_ld_uuids.push_back(pair.first);
-    }
-    std::sort(sorted_ld_uuids.begin(), sorted_ld_uuids.end());
-
-    for (const auto& client_uuid : sorted_ld_uuids) {
-        const auto& segment =
-            segment_manager_->client_local_disk_segment_.at(client_uuid);
-        packer.pack(UuidToString(client_uuid));
-
-        // Serialize LocalDiskSegment: [enable_offloading, count, storage_key1,
-        // task1, storage_key2, task2, ...] Sort keys to ensure determinism.
-        std::vector<std::string> sorted_keys;
-        for (const auto& [key, _] : segment->offloading_objects) {
-            sorted_keys.push_back(key);
-        }
-        std::sort(sorted_keys.begin(), sorted_keys.end());
-
-        // Trailing ssd_total_capacity_bytes so a restored master keeps the
-        // client-reported SSD capacity across a snapshot restore (#2783).
-        packer.pack_array(2 + sorted_keys.size() * 2 + 1);
-        packer.pack(segment->enable_offloading);
-        packer.pack(static_cast<uint64_t>(sorted_keys.size()));
-
-        for (const auto& key : sorted_keys) {
-            packer.pack(key);
-            const auto& task = segment->offloading_objects.at(key);
-            packer.pack_array(3);
-            packer.pack(task.tenant_id);
-            packer.pack(task.key);
-            packer.pack(task.size);
-        }
-        packer.pack(segment->ssd_total_capacity_bytes);
+    auto local_ssd_result = ha::LocalSsdCodec::Encode(local_ssd_state, packer);
+    if (!local_ssd_result) {
+        return tl::unexpected(local_ssd_result.error());
     }
 
     // Compress entire data
@@ -779,8 +855,8 @@ SegmentSerializer::Serialize() {
         std::make_move_iterator(compressed_data.end()));
 }
 
-tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
-    const std::vector<uint8_t>& data) {
+tl::expected<LocalSsdPersistedState, SerializationError>
+SegmentSerializer::Deserialize(const std::vector<uint8_t>& data) {
     // Decompress data
     std::vector<uint8_t> decompressed_data;
     try {
@@ -820,14 +896,9 @@ tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
     if (!segment_manager_) {
         return tl::unexpected(SerializationError(
             ErrorCode::DESERIALIZE_FAIL,
-            "deserialize SegmentManager segment_manager is null"));
+            "deserialize SegmentManager dependency is null"));
     }
 
-    // Clear existing data
-    segment_manager_->mounted_segments_.clear();
-    segment_manager_->client_segments_.clear();
-    segment_manager_->segments_by_host_.clear();
-
     // Convert MessagePack map to regular map, use pointers for values to avoid
     // copying
     std::map<std::string, const msgpack::object*> fields_map;
@@ -842,6 +913,19 @@ tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
         }
     }
 
+    auto ld_it = fields_map.find("ld");
+    auto local_ssd_state = ha::LocalSsdCodec::Decode(
+        ld_it == fields_map.end() ? nullptr : ld_it->second);
+    if (!local_ssd_state) {
+        return tl::unexpected(local_ssd_state.error());
+    }
+
+    // Do not mutate SegmentManager until the independent LocalSSD payload has
+    // been fully validated.
+    segment_manager_->mounted_segments_.clear();
+    segment_manager_->client_segments_.clear();
+    segment_manager_->segments_by_host_.clear();
+
     // Process fields in order
     // 1. First process memory_allocator_
     auto allocator_it = fields_map.find("ma");
@@ -1016,6 +1100,20 @@ tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
     // Restore allocator_manager_ based on mounted_segments_ and saved names
     // order
     segment_manager_->allocator_manager_ = AllocatorManager();
+    for (auto& [segment_id, mounted_segment] :
+         segment_manager_->mounted_segments_) {
+        (void)segment_id;
+        if (!mounted_segment.buf_allocator) {
+            continue;
+        }
+        mounted_segment.allocator_registration =
+            std::shared_ptr<SegmentAllocatorRegistration>(
+                new SegmentAllocatorRegistration(mounted_segment.buf_allocator,
+                                                 nullptr));
+        if (mounted_segment.status != SegmentStatus::OK) {
+            mounted_segment.allocator_registration->SetAllocatable(false);
+        }
+    }
 
     // Add allocators in saved original order
     for (const auto& name : saved_allocator_names) {
@@ -1024,9 +1122,8 @@ tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
             if (mounted_segment.segment.name == name &&
                 mounted_segment.status == SegmentStatus::OK &&
                 mounted_segment.buf_allocator) {
-                segment_manager_->allocator_manager_.addAllocator(
-                    name, mounted_segment.buf_allocator);
-                break;
+                segment_manager_->allocator_manager_.addRegistration(
+                    name, mounted_segment.allocator_registration);
             }
         }
     }
@@ -1053,133 +1150,8 @@ tl::expected<void, SerializationError> SegmentSerializer::Deserialize(
         }
     }
 
-    // 4. Process client_local_disk_segment_
-    segment_manager_->client_local_disk_segment_.clear();
-    auto ld_it = fields_map.find("ld");
-    if (ld_it != fields_map.end()) {
-        const msgpack::object* ld_obj = ld_it->second;
-        if (ld_obj->type != msgpack::type::MAP) {
-            return tl::unexpected(SerializationError(
-                ErrorCode::DESERIALIZE_FAIL,
-                "deserialize SegmentManager local_disk_segments is not map"));
-        }
-
-        for (uint32_t j = 0; j < ld_obj->via.map.size; ++j) {
-            const msgpack::object& client_key = ld_obj->via.map.ptr[j].key;
-            const msgpack::object& client_value = ld_obj->via.map.ptr[j].val;
-
-            // Parse client_id
-            if (client_key.type != msgpack::type::STR) {
-                return tl::unexpected(
-                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                                       "deserialize local_disk_segments "
-                                       "client key is not string"));
-            }
-
-            std::string client_uuid_str(client_key.via.str.ptr,
-                                        client_key.via.str.size);
-            UUID client_id;
-            if (!StringToUuid(client_uuid_str, client_id)) {
-                return tl::unexpected(SerializationError(
-                    ErrorCode::DESERIALIZE_FAIL,
-                    fmt::format("deserialize local_disk_segments "
-                                "client uuid {} is invalid",
-                                client_uuid_str)));
-            }
-
-            // Parse LocalDiskSegment array: [enable_offloading, count,
-            // storage_key1, task1, ...]
-            if (client_value.type != msgpack::type::ARRAY ||
-                client_value.via.array.size < 2) {
-                return tl::unexpected(
-                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                                       "deserialize local_disk_segments "
-                                       "value is not valid array"));
-            }
-
-            bool enable_offloading = client_value.via.array.ptr[0].as<bool>();
-            uint64_t count = client_value.via.array.ptr[1].as<uint64_t>();
-
-            auto segment =
-                std::make_shared<LocalDiskSegment>(enable_offloading);
-
-            // Parse offloading_objects
-            for (uint64_t k = 0; k < count; ++k) {
-                size_t key_idx = 2 + k * 2;
-                size_t task_idx = 2 + k * 2 + 1;
-                if (task_idx >= client_value.via.array.size) {
-                    return tl::unexpected(
-                        SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                                           "deserialize local_disk_segments "
-                                           "offloading_objects out of bounds"));
-                }
-
-                if (client_value.via.array.ptr[key_idx].type !=
-                    msgpack::type::STR) {
-                    return tl::unexpected(SerializationError(
-                        ErrorCode::DESERIALIZE_FAIL,
-                        "deserialize local_disk_segments offloading key is "
-                        "not string"));
-                }
-                std::string key(
-                    client_value.via.array.ptr[key_idx].via.str.ptr,
-                    client_value.via.array.ptr[key_idx].via.str.size);
-                const auto& task_obj = client_value.via.array.ptr[task_idx];
-                if (task_obj.type == msgpack::type::ARRAY &&
-                    task_obj.via.array.size == 3) {
-                    if (task_obj.via.array.ptr[0].type != msgpack::type::STR ||
-                        task_obj.via.array.ptr[1].type != msgpack::type::STR) {
-                        return tl::unexpected(SerializationError(
-                            ErrorCode::DESERIALIZE_FAIL,
-                            "deserialize local_disk_segments offloading task "
-                            "fields are not strings"));
-                    }
-                    if (!IsMsgpackInteger(task_obj.via.array.ptr[2])) {
-                        return tl::unexpected(SerializationError(
-                            ErrorCode::DESERIALIZE_FAIL,
-                            "deserialize local_disk_segments offloading task "
-                            "size is not integer"));
-                    }
-                    OffloadTaskItem task;
-                    task.tenant_id =
-                        task_obj.via.array.ptr[0].as<std::string>();
-                    task.key = task_obj.via.array.ptr[1].as<std::string>();
-                    task.size = task_obj.via.array.ptr[2].as<int64_t>();
-                    segment->offloading_objects[key] = std::move(task);
-                } else {
-                    // Backward compatibility for snapshots whose
-                    // offloading_objects value was key -> size.
-                    if (!IsMsgpackInteger(task_obj)) {
-                        return tl::unexpected(SerializationError(
-                            ErrorCode::DESERIALIZE_FAIL,
-                            "deserialize local_disk_segments legacy "
-                            "offloading size is not integer"));
-                    }
-                    auto [tenant_id, user_key] = TenantId::ParseScopedKey(key);
-                    segment->offloading_objects[key] =
-                        OffloadTaskItem{.tenant_id = tenant_id.value(),
-                                        .key = std::move(user_key),
-                                        .size = task_obj.as<int64_t>()};
-                }
-            }
-
-            // ssd_total_capacity_bytes is appended after the offloading
-            // objects. Pre-#2783 snapshots omit it, so read it only when
-            // present; otherwise it keeps the default 0 until the client
-            // re-reports capacity.
-            size_t capacity_idx = 2 + count * 2;
-            if (client_value.via.array.size > capacity_idx &&
-                IsMsgpackInteger(client_value.via.array.ptr[capacity_idx])) {
-                segment->ssd_total_capacity_bytes =
-                    client_value.via.array.ptr[capacity_idx].as<int64_t>();
-            }
-
-            segment_manager_->client_local_disk_segment_[client_id] =
-                std::move(segment);
-        }
-    }
-
-    return {};
+    segment_manager_->AttachMountedUsageTrackers();
+    return std::move(*local_ssd_state);
 }
 
 void SegmentSerializer::Reset() {
@@ -1188,7 +1160,6 @@ void SegmentSerializer::Reset() {
     segment_manager_->client_by_name_.clear();
     segment_manager_->segment_id_by_name_.clear();
     segment_manager_->segments_by_host_.clear();
-    segment_manager_->client_local_disk_segment_.clear();
     segment_manager_->allocator_manager_ = AllocatorManager();
 }
 
@@ -1220,7 +1191,8 @@ bool ScopedSegmentAccess::IsSegmentAllocatable(
     auto mounted_segment_it =
         segment_manager_->mounted_segments_.find(segment_id_it->second);
     return mounted_segment_it != segment_manager_->mounted_segments_.end() &&
-           mounted_segment_it->second.status == SegmentStatus::OK;
+           mounted_segment_it->second.status == SegmentStatus::OK &&
+           mounted_segment_it->second.allocator_registration->IsServing();
 }
 
 ErrorCode ScopedSegmentAccess::GetSegmentStatusByName(
@@ -1272,17 +1244,19 @@ ErrorCode ScopedSegmentAccess::SetSegmentStatusByName(
     }
 
     auto& allocator_manager = segment_manager_->allocator_manager_;
-    const auto& allocator = mounted_segment.buf_allocator;
+    const auto& registration = mounted_segment.allocator_registration;
     const auto& name = mounted_segment.segment.name;
     const bool should_be_allocatable = status == SegmentStatus::OK;
     const bool is_allocatable =
-        HasAllocator(allocator_manager, name, allocator);
-    if (should_be_allocatable && !is_allocatable && allocator) {
-        allocator_manager.addAllocator(name, allocator);
+        HasAllocatorRegistration(allocator_manager, name, registration);
+    if (should_be_allocatable && !is_allocatable && registration) {
+        registration->SetAllocatable(true);
+        allocator_manager.addRegistration(name, registration);
         AddHostSegment(segment_manager_->segments_by_host_,
                        mounted_segment.segment);
     } else if (!should_be_allocatable && is_allocatable) {
-        allocator_manager.removeAllocator(name, allocator);
+        allocator_manager.removeAllocator(name, registration);
+        registration->SetAllocatable(false);
         RemoveHostSegment(segment_manager_->segments_by_host_,
                           mounted_segment.segment);
     }
@@ -1343,43 +1317,21 @@ ErrorCode ScopedNoFSegmentAccess::MountSegment(const NoFSegment& segment,
         }
     }
 
-    std::shared_ptr<BufferAllocatorBase> allocator;
-    try {
-        switch (nof_segment_manager_->memory_allocator_) {
-            case BufferAllocatorType::CACHELIB:
-                allocator = std::make_shared<CachelibBufferAllocator>(
-                    segment.name, buffer, size, segment.te_endpoint,
-                    ReplicaType::NOF_SSD);
-                break;
-            case BufferAllocatorType::OFFSET:
-                allocator = std::make_shared<OffsetBufferAllocator>(
-                    segment.name, buffer, size, segment.te_endpoint,
-                    ReplicaType::NOF_SSD);
-                break;
-            default:
-                LOG(ERROR) << "NoF segment mount: segment_name=" << segment.name
-                           << ", error=unknown_memory_allocator="
-                           << static_cast<int>(
-                                  nof_segment_manager_->memory_allocator_);
-                return ErrorCode::INVALID_PARAMS;
-        }
-
-        if (!allocator) {
-            LOG(ERROR) << "NoF segment mount: segment_name=" << segment.name
-                       << ", error=failed_to_create_allocator";
-            return ErrorCode::INVALID_PARAMS;
-        }
-    } catch (...) {
-        LOG(ERROR) << "NoF segment mount: segment_name=" << segment.name
-                   << ", error=exception_during_allocator_creation";
-        return ErrorCode::INVALID_PARAMS;
+    auto created = CreateBufferAllocator(
+        nof_segment_manager_->memory_allocator_, segment.name, buffer, size,
+        segment.te_endpoint, ReplicaType::NOF_SSD);
+    if (!created) {
+        return created.error();
     }
+    auto allocator = std::move(*created);
 
-    nof_segment_manager_->allocator_manager_.addAllocator(segment.name,
-                                                          allocator);
+    allocator->AttachUsageTracker(nof_segment_manager_->usage_tracker_);
+    auto registration = nof_segment_manager_->allocator_manager_.addAllocator(
+        segment.name, allocator);
     nof_segment_manager_->client_segments_[client_id].push_back(segment.id);
     nof_segment_manager_->mounted_segments_[segment.id] = {
-        segment, client_id, SegmentStatus::OK, std::move(allocator)};
+        segment, client_id, SegmentStatus::OK, std::move(allocator),
+        registration};
     nof_segment_manager_->client_by_name_[segment.name] = client_id;
     MasterMetricManager::instance().inc_total_nof_capacity(segment.name, size);
 
@@ -1429,14 +1381,15 @@ ErrorCode ScopedNoFSegmentAccess::PrepareUnmountSegment(
     auto& segment = mounted_segment.segment;
     metrics_dec_capacity = segment.size;
 
-    std::shared_ptr<BufferAllocatorBase> allocator =
-        mounted_segment.buf_allocator;
-    if (HasAllocator(nof_segment_manager_->allocator_manager_, segment.name,
-                     allocator)) {
+    auto registration = mounted_segment.allocator_registration;
+    if (HasAllocatorRegistration(nof_segment_manager_->allocator_manager_,
+                                 segment.name, registration)) {
         nof_segment_manager_->allocator_manager_.removeAllocator(segment.name,
-                                                                 allocator);
+                                                                 registration);
     }
 
+    registration->Invalidate();
+    mounted_segment.allocator_registration.reset();
     mounted_segment.buf_allocator.reset();
     mounted_segment.status = SegmentStatus::UNMOUNTING;
     return ErrorCode::OK;
@@ -1474,6 +1427,7 @@ ErrorCode ScopedNoFSegmentAccess::CommitUnmountSegment(
     nof_segment_manager_->mounted_segments_.erase(segment_id);
     MasterMetricManager::instance().dec_total_nof_capacity(
         segment_name, metrics_dec_capacity);
+    MasterMetricManager::instance().remove_nof_segment_metrics(segment_name);
 
     return ErrorCode::OK;
 }
@@ -1528,7 +1482,8 @@ ErrorCode ScopedNoFSegmentAccess::QuerySegments(const std::string& segment,
     const auto& allocator_manager = nof_segment_manager_->allocator_manager_;
     const auto& allocators = allocator_manager.getAllocators(segment);
     if (allocators != nullptr) {
-        for (const auto& allocator : *allocators) {
+        for (const auto& registration : *allocators) {
+            const auto allocator = registration->GetAllocator();
             total_used += allocator->size();
             total_capacity += allocator->capacity();
         }
@@ -1557,6 +1512,18 @@ void NoFSegmentManager::GetMountedSegmentsSnapshot(
     }
 }
 
+StorageUsageSnapshot NoFSegmentManager::GetUsageSnapshot() const {
+    std::shared_lock<std::shared_mutex> lock(segment_mutex_);
+    StorageUsageSnapshot snapshot;
+    std::unordered_set<const BufferAllocatorBase*> counted_allocators;
+    for (const auto& [segment_id, mounted_segment] : mounted_segments_) {
+        (void)segment_id;
+        AddAllocatorUsage(snapshot, mounted_segment.buf_allocator,
+                          counted_allocators);
+    }
+    return snapshot;
+}
+
 void SegmentManager::releaseCapacityMetrics() {
     // Segments that are still mounted here never went through
     // CommitUnmountSegment, so their contribution to the capacity metrics
@@ -1572,11 +1539,12 @@ void SegmentManager::releaseCapacityMetrics() {
         }
         MasterMetricManager::instance().dec_total_mem_capacity(segment.name,
                                                                segment.size);
+        MasterMetricManager::instance().remove_segment_metrics(segment.name);
     }
 }
 
-void SegmentManager::initializeCxlAllocator(const std::string& cxl_path,
-                                            const size_t cxl_size) {
+ErrorCode SegmentManager::initializeCxlAllocator(const std::string& cxl_path,
+                                                 size_t cxl_size) {
     LOG(INFO) << "Init CXL global allocator.";
     LOG(INFO) << "[CXL] create allocator with "
               << "path=" << cxl_path << " base=0x" << std::hex
@@ -1584,35 +1552,20 @@ void SegmentManager::initializeCxlAllocator(const std::string& cxl_path,
               << std::fixed << std::setprecision(2)
               << cxl_size / (1024.0 * 1024 * 1024) << " GB)";
 
-    cxl_global_allocator_ = std::make_shared<CachelibBufferAllocator>(
-        cxl_path, DEFAULT_CXL_BASE, cxl_size, cxl_path);
-    MasterMetricManager::instance().inc_total_mem_capacity(cxl_path, cxl_size);
-}
-
-int64_t ScopedLocalDiskSegmentAccess::getSsdTotalCapacity(
-    const std::string& segment_name) const {
-    auto client_it = client_by_name_.find(segment_name);
-    if (client_it == client_by_name_.end()) {
-        return 0;
-    }
-    auto disk_it = client_local_disk_segment_.find(client_it->second);
-    if (disk_it == client_local_disk_segment_.end()) {
-        return 0;
-    }
-    return disk_it->second->ssd_total_capacity_bytes;
-}
-
-int64_t ScopedLocalDiskSegmentAccess::getSsdUsedBytes(
-    const std::string& segment_name) const {
-    auto client_it = client_by_name_.find(segment_name);
-    if (client_it == client_by_name_.end()) {
-        return 0;
+    auto created =
+        CreateBufferAllocator(BufferAllocatorType::CACHELIB, cxl_path,
+                              DEFAULT_CXL_BASE, cxl_size, cxl_path);
+    if (!created) {
+        return created.error();
     }
-    auto disk_it = client_local_disk_segment_.find(client_it->second);
-    if (disk_it == client_local_disk_segment_.end()) {
-        return 0;
+    auto allocator = std::move(*created);
+    allocator->AttachUsageTracker(usage_tracker_);
+    {
+        std::unique_lock<std::shared_mutex> lock(segment_mutex_);
+        cxl_global_allocator_ = std::move(allocator);
     }
-    return disk_it->second->ssd_used_bytes.load(std::memory_order_relaxed);
+    MasterMetricManager::instance().inc_total_mem_capacity(cxl_path, cxl_size);
+    return ErrorCode::OK;
 }
 
 bool SegmentManager::HasSegmentByEndpoint(const std::string& endpoint) const {
diff --git a/mooncake-store/src/segment/catalog.cpp b/mooncake-store/src/segment/catalog.cpp
new file mode 100644
index 0000000000..d580fb0032
--- /dev/null
+++ b/mooncake-store/src/segment/catalog.cpp
@@ -0,0 +1,44 @@
+#include "segment/catalog.h"
+
+namespace mooncake {
+
+const MountedRegion* RegionCatalog::Find(const UUID& segment_id) const {
+    auto it = records_.find(segment_id);
+    return it == records_.end() ? nullptr : &*it;
+}
+
+ErrorCode RegionCatalog::Register(const MountedRegion& mounted) {
+    if (Find(mounted.segment.id)) return ErrorCode::SEGMENT_ALREADY_EXISTS;
+    auto owner = FindOwnerClientId(mounted.segment.name);
+    if (owner && *owner != mounted.client_id) return ErrorCode::INVALID_PARAMS;
+    auto record = mounted;
+    record.generation = ++next_generation_;
+    records_.insert(std::move(record));
+    return ErrorCode::OK;
+}
+
+bool RegionCatalog::Erase(const UUID& segment_id) {
+    return records_.erase(segment_id) != 0;
+}
+
+bool RegionCatalog::SetStatus(const UUID& segment_id, SegmentStatus status) {
+    auto it = records_.find(segment_id);
+    if (it == records_.end()) return false;
+    if (it->status == status) return true;
+    return records_.modify(it, [this, status](MountedRegion& r) noexcept {
+        r.status = status;
+        r.generation = ++next_generation_;
+    });
+}
+
+void RegionCatalog::Clear() { records_.clear(); }
+
+std::optional<UUID> RegionCatalog::FindOwnerClientId(
+    std::string_view name) const {
+    const auto& names = records_.get<1>();
+    auto it = names.find(name);
+    return it == names.end() ? std::nullopt
+                             : std::optional<UUID>(it->client_id);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/pool.cpp b/mooncake-store/src/segment/pool.cpp
new file mode 100644
index 0000000000..dd6a5e9f45
--- /dev/null
+++ b/mooncake-store/src/segment/pool.cpp
@@ -0,0 +1,93 @@
+#include "segment/pool.h"
+
+#include "segment/pool_write_access.h"
+#include "segment/pool_read_access.h"
+
+#include "master_metric_manager.h"
+
+#include <utility>
+#include <unordered_set>
+
+namespace mooncake {
+
+SegmentPool::~SegmentPool() { ReleaseCapacityMetrics(); }
+
+SegmentPool::WriteAccess SegmentPool::AcquireWriteAccess() {
+    return WriteAccess(AccessKey{}, *this);
+}
+
+SegmentPool::ReadAccess SegmentPool::AcquireReadAccess() const {
+    return ReadAccess(AccessKey{}, *this);
+}
+
+ScopedPlacementReadAccess SegmentPool::AcquirePlacementAccess() const {
+    return ScopedPlacementReadAccess(placement_index_, catalog_, pool_mutex_);
+}
+
+tl::expected<Replica, ErrorCode> SegmentPool::AllocateInSegment(
+    std::string_view segment_name, AllocationCandidateKind kind, size_t size,
+    ReplicaType replica_type) const {
+    auto access = AcquirePlacementAccess();
+    return ReplicaAllocator(PreferredOnlyPlacementPolicy(kind))
+        .AllocateFrom(access, size, segment_name, replica_type);
+}
+
+StorageUsageSnapshot SegmentPool::GetMemoryUsageSnapshot() const {
+    std::shared_lock lock(pool_mutex_);
+    StorageUsageSnapshot snapshot;
+    std::unordered_set<const BufferAllocatorBase*> counted;
+    for (const auto& mounted : catalog_.Regions()) {
+        const auto* resource = GetResource(mounted);
+        if (!resource || !resource->allocator() ||
+            !counted.insert(resource->allocator().get()).second) {
+            continue;
+        }
+        const size_t used = resource->allocator()->size();
+        const size_t capacity = resource->allocator()->capacity();
+        snapshot.used_bytes += used;
+        snapshot.capacity_bytes += capacity;
+        auto& region =
+            snapshot.segments[resource->allocator()->getSegmentName()];
+        region.used_bytes += used;
+        region.capacity_bytes += capacity;
+    }
+    return snapshot;
+}
+
+RegionDriver* SegmentPool::GetDriver(RegionKind kind) {
+    return const_cast<RegionDriver*>(std::as_const(*this).GetDriver(kind));
+}
+
+const RegionDriver* SegmentPool::GetDriver(RegionKind kind) const {
+    auto it = region_drivers_.find(kind);
+    return it == region_drivers_.end() ? nullptr : it->second.get();
+}
+
+RegionResource* SegmentPool::GetResource(const MountedRegion& mounted) {
+    return const_cast<RegionResource*>(
+        std::as_const(*this).GetResource(mounted));
+}
+
+const RegionResource* SegmentPool::GetResource(
+    const MountedRegion& mounted) const {
+    auto* driver = GetDriver(mounted.kind);
+    return driver ? driver->GetResource(mounted.segment.id) : nullptr;
+}
+
+void SegmentPool::ReleaseCapacityMetrics() {
+    std::unordered_set<std::string> segment_names;
+    for (const auto& id : capacity_accounted_region_ids_) {
+        auto mounted = catalog_.Find(id);
+        if (mounted != nullptr) {
+            MasterMetricManager::instance().dec_total_mem_capacity(
+                mounted->segment.name, mounted->segment.size);
+            segment_names.insert(mounted->segment.name);
+        }
+    }
+    for (const auto& name : segment_names) {
+        MasterMetricManager::instance().remove_segment_metrics(name);
+    }
+    capacity_accounted_region_ids_.clear();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/pool_mount.cpp b/mooncake-store/src/segment/pool_mount.cpp
new file mode 100644
index 0000000000..a885122bae
--- /dev/null
+++ b/mooncake-store/src/segment/pool_mount.cpp
@@ -0,0 +1,211 @@
+#include "segment/pool_write_access.h"
+
+#include <algorithm>
+
+#include "master_metric_manager.h"
+#include "segment/pool.h"
+
+namespace mooncake {
+namespace {
+
+RegionKind ClassifyRegion(const Segment& segment) {
+    return segment.protocol == "cxl" ? RegionKind::CXL
+                                     : RegionKind::HOST_MEMORY;
+}
+
+RegionResourceSpec MakeResourceSpec(const Segment& segment) {
+    return RegionResourceSpec{segment.id, segment.name, segment.base,
+                              segment.size, segment.te_endpoint};
+}
+
+}  // namespace
+
+tl::expected<RegionMountTxn, ErrorCode> SegmentPool::WriteAccess::PrepareMount(
+    const Segment& segment, const UUID& client_id) {
+    return PrepareWithLiveAllocations(segment, client_id, {}, 0);
+}
+
+tl::expected<RegionMountTxn, ErrorCode>
+SegmentPool::WriteAccess::PrepareRestore(
+    const Segment& segment, const UUID& client_id,
+    std::span<const AllocatedBuffer::Descriptor> descriptors) {
+    if (std::any_of(descriptors.begin(), descriptors.end(),
+                    [](const auto& descriptor) {
+                        return descriptor.protocol_ == "cxl";
+                    })) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    auto live_allocations =
+        BuildRegionLiveAllocations(MakeResourceSpec(segment), descriptors);
+    if (!live_allocations) {
+        return tl::make_unexpected(live_allocations.error());
+    }
+    uint64_t requested_bytes = 0;
+    for (const auto& allocation : *live_allocations) {
+        requested_bytes += allocation.requested_size;
+    }
+    return PrepareWithLiveAllocations(segment, client_id, *live_allocations,
+                                      requested_bytes);
+}
+
+tl::expected<RegionMountTxn, ErrorCode>
+SegmentPool::WriteAccess::PrepareWithLiveAllocations(
+    const Segment& segment, const UUID& client_id,
+    const std::vector<LiveAllocation>& live_allocations,
+    uint64_t imported_requested_bytes) {
+    const RegionKind kind = ClassifyRegion(segment);
+    RegionDriver* driver = segment_pool_.GetDriver(kind);
+    if (!driver) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+
+    auto existing = catalog_.Find(segment.id);
+    const bool existed = existing != nullptr;
+    std::weak_ptr<BufferAllocatorBase> previous_allocator;
+    if (existed) {
+        if (existing->status == SegmentStatus::UNMOUNTING) {
+            return tl::make_unexpected(
+                ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        if (existing->client_id != client_id || existing->kind != kind ||
+            existing->segment != segment) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        const auto* existing_resource = segment_pool_.GetResource(*existing);
+        if (!existing_resource) {
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+        previous_allocator = existing_resource->allocator();
+    } else {
+        auto owner = catalog_.FindOwnerClientId(segment.name);
+        if (owner && *owner != client_id) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+
+    auto resource =
+        driver->PrepareOpen(MakeResourceSpec(segment), live_allocations);
+    if (!resource) {
+        return tl::make_unexpected(resource.error());
+    }
+    resource->resource().allocator()->AttachUsageTracker(
+        segment_pool_.usage_tracker_);
+    MountedRegion mounted{segment, client_id, SegmentStatus::OK, kind};
+    if (existed) {
+        mounted.status = existing->status;
+    }
+    return RegionMountTxn(TransactionKey{}, std::move(mounted), existed, true,
+                          std::move(*resource), imported_requested_bytes,
+                          std::move(previous_allocator));
+}
+
+tl::expected<RegionMountTxn, ErrorCode> SegmentPool::WriteAccess::PrepareAdopt(
+    MountedRegion mounted, std::shared_ptr<BufferAllocatorBase> allocator,
+    bool account_capacity_metrics, AdoptMode mode) {
+    mounted.kind = ClassifyRegion(mounted.segment);
+    RegionDriver* driver = segment_pool_.GetDriver(mounted.kind);
+    if (!driver) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    if (mode == AdoptMode::Insert) {
+        if (catalog_.Find(mounted.segment.id)) {
+            return tl::make_unexpected(ErrorCode::SEGMENT_ALREADY_EXISTS);
+        }
+        auto owner = catalog_.FindOwnerClientId(mounted.segment.name);
+        if (owner && *owner != mounted.client_id) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+    auto resource = driver->PrepareAdopt(MakeResourceSpec(mounted.segment),
+                                         std::move(allocator));
+    if (!resource) {
+        return tl::make_unexpected(resource.error());
+    }
+    return RegionMountTxn(TransactionKey{}, std::move(mounted), false,
+                          account_capacity_metrics, std::move(*resource));
+}
+
+ErrorCode RegionMountTxn::Commit(SegmentPool::WriteAccess& access) noexcept {
+    if (committed_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    const auto result =
+        access.PublishMount(mounted_, existed_, account_capacity_metrics_,
+                            resource_, previous_allocator_);
+    if (result == ErrorCode::OK) {
+        committed_ = true;
+    }
+    return result;
+}
+
+ErrorCode SegmentPool::WriteAccess::PublishMount(
+    const MountedRegion& mounted, bool existed, bool account_capacity_metrics,
+    PreparedRegionResource& prepared,
+    const std::weak_ptr<BufferAllocatorBase>& previous_allocator) noexcept {
+    const auto* current = catalog_.Find(mounted.segment.id);
+    if (existed) {
+        if (!current || current->segment != mounted.segment ||
+            current->client_id != mounted.client_id ||
+            current->kind != mounted.kind ||
+            current->status != mounted.status) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+        const auto* current_resource = segment_pool_.GetResource(*current);
+        if (!current_resource ||
+            current_resource->allocator() != previous_allocator.lock()) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+    } else {
+        if (current) {
+            return ErrorCode::SEGMENT_ALREADY_EXISTS;
+        }
+        const auto owner = catalog_.FindOwnerClientId(mounted.segment.name);
+        if (owner && *owner != mounted.client_id) {
+            return ErrorCode::INVALID_PARAMS;
+        }
+    }
+    auto& new_resource = prepared.resource();
+    if (existed && mounted.status == SegmentStatus::OK) {
+        auto& old_resource = *segment_pool_.GetResource(mounted);
+        prepared.Commit();
+        const bool replaced = segment_pool_.placement_index_.ReplaceCandidate(
+            mounted.segment.name, *old_resource.candidate,
+            *new_resource.candidate, mounted.segment.host_id);
+        DCHECK(replaced);
+    } else {
+        prepared.Commit();
+        if (!existed) {
+            const auto registered = catalog_.Register(mounted);
+            DCHECK(registered == ErrorCode::OK);
+        }
+    }
+    const auto transitioned =
+        TransitionRegion(mounted, new_resource, mounted.status);
+    DCHECK(transitioned == ErrorCode::OK);
+
+    new_resource.allocator()->AttachUsageTracker(segment_pool_.usage_tracker_);
+
+    if (account_capacity_metrics && mounted.kind == RegionKind::HOST_MEMORY &&
+        segment_pool_.capacity_accounted_region_ids_.insert(mounted.segment.id)
+            .second) {
+        MasterMetricManager::instance().inc_total_mem_capacity(
+            mounted.segment.name, mounted.segment.size);
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode SegmentPool::WriteAccess::MountSegment(const Segment& segment,
+                                                 const UUID& client_id) {
+    if (const auto* mounted = catalog_.Find(segment.id)) {
+        return mounted->status == SegmentStatus::OK
+                   ? ErrorCode::SEGMENT_ALREADY_EXISTS
+                   : ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    auto prepared = PrepareMount(segment, client_id);
+    if (!prepared) {
+        return prepared.error();
+    }
+    return prepared->Commit(*this);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/pool_read_access.cpp b/mooncake-store/src/segment/pool_read_access.cpp
new file mode 100644
index 0000000000..4d1533ed64
--- /dev/null
+++ b/mooncake-store/src/segment/pool_read_access.cpp
@@ -0,0 +1,79 @@
+#include "segment/pool_read_access.h"
+
+namespace mooncake {
+
+const RegionDriver* SegmentPool::ReadAccess::GetDriver(RegionKind kind) const {
+    auto driver = drivers_.find(kind);
+    return driver == drivers_.end() ? nullptr : driver->second.get();
+}
+
+const RegionResource* SegmentPool::ReadAccess::GetResource(
+    const MountedRegion& mounted) const {
+    const auto* driver = GetDriver(mounted.kind);
+    return driver ? driver->GetResource(mounted.segment.id) : nullptr;
+}
+
+std::shared_ptr<BufferAllocatorBase> SegmentPool::ReadAccess::GetAllocator(
+    const UUID& region_id) const {
+    auto mounted = catalog_.Find(region_id);
+    if (mounted == nullptr) {
+        return nullptr;
+    }
+    const auto* resource = GetResource(*mounted);
+    return resource ? resource->allocator() : nullptr;
+}
+
+ErrorCode SegmentPool::ReadAccess::QueryAllocationCandidates(
+    std::string_view name, AllocationCandidateKind kind, size_t& used,
+    size_t& capacity) const {
+    auto* entry = placement_.Find(name, kind);
+    if (!entry) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    used = 0;
+    capacity = 0;
+    for (const auto* candidate : entry->candidates) {
+        used += candidate->Used();
+        capacity += candidate->Capacity();
+    }
+    return capacity == 0 ? ErrorCode::SEGMENT_NOT_FOUND : ErrorCode::OK;
+}
+
+bool SegmentPool::ReadAccess::IsInactive(
+    const std::shared_ptr<BufferAllocatorBase>& allocator,
+    std::string_view allocation_binding) const {
+    if (!allocator) {
+        return false;
+    }
+    for (const auto& mounted : catalog_.Regions()) {
+        const auto* resource = GetResource(mounted);
+        if (!resource || resource->allocator() != allocator ||
+            (mounted.kind == RegionKind::CXL &&
+             mounted.segment.name != allocation_binding)) {
+            continue;
+        }
+
+        // Draining and graceful states stop new placement while existing
+        // replicas remain readable. Only final/immediate unmount is stale.
+        if (mounted.status != SegmentStatus::UNMOUNTING) {
+            return false;
+        }
+    }
+    return true;
+}
+
+SegmentPool::ReadAccess::ReadAccess(AccessKey, const SegmentPool& segment_pool)
+    : lock_(segment_pool.pool_mutex_),
+      catalog_(segment_pool.catalog_),
+      drivers_(segment_pool.region_drivers_),
+      placement_(segment_pool.placement_index_) {}
+
+const RegionCatalog& SegmentPool::ReadAccess::Catalog() const {
+    return catalog_;
+}
+
+const PlacementIndex& SegmentPool::ReadAccess::Placement() const {
+    return placement_;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/pool_write_access.cpp b/mooncake-store/src/segment/pool_write_access.cpp
new file mode 100644
index 0000000000..8fb49cfd78
--- /dev/null
+++ b/mooncake-store/src/segment/pool_write_access.cpp
@@ -0,0 +1,258 @@
+#include "segment/pool_write_access.h"
+
+#include <algorithm>
+#include "master_metric_manager.h"
+#include "segment/pool.h"
+
+namespace mooncake {
+SegmentPool::WriteAccess::WriteAccess(AccessKey, SegmentPool& segment_pool)
+    : segment_pool_(segment_pool),
+      lock_(segment_pool.pool_mutex_),
+      catalog_(segment_pool.catalog_) {}
+
+tl::expected<RegionUnmountTxn, ErrorCode>
+SegmentPool::WriteAccess::PrepareUnmount(const UUID& segment_id,
+                                         const UUID& client_id) {
+    auto mounted = catalog_.Find(segment_id);
+    if (mounted == nullptr) {
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    if (mounted->client_id != client_id) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (mounted->status == SegmentStatus::UNMOUNTING) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    RegionResource* resource = segment_pool_.GetResource(*mounted);
+    if (!resource) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return RegionUnmountTxn(TransactionKey{}, *this, *mounted, *resource);
+}
+
+RegionUnmountTxn::RegionUnmountTxn(TransactionKey,
+                                   SegmentPool::WriteAccess& access,
+                                   const MountedRegion& mounted,
+                                   RegionResource& resource)
+    : segment_(mounted.segment),
+      client_id_(mounted.client_id),
+      previous_status_(mounted.status) {
+    const auto result =
+        access.TransitionRegion(mounted, resource, SegmentStatus::UNMOUNTING);
+    DCHECK(result == ErrorCode::OK);
+    generation_ = mounted.generation;
+}
+
+RegionUnmountTxn::RegionUnmountTxn(RegionUnmountTxn&& other) noexcept
+    : segment_(std::move(other.segment_)),
+      client_id_(other.client_id_),
+      previous_status_(other.previous_status_),
+      generation_(other.generation_),
+      finished_(std::exchange(other.finished_, true)) {}
+
+ErrorCode RegionUnmountTxn::Commit(SegmentPool::WriteAccess& access) && {
+    auto transaction = std::move(*this);
+    if (transaction.finished_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    auto result = access.EraseUnmountedRegion(
+        transaction.segment_.id, transaction.client_id_,
+        SegmentStatus::UNMOUNTING, transaction.generation_);
+    if (result == ErrorCode::OK) {
+        transaction.finished_ = true;
+    }
+    return result;
+}
+
+ErrorCode RegionUnmountTxn::Rollback(SegmentPool::WriteAccess& access) && {
+    auto transaction = std::move(*this);
+    if (transaction.finished_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    return access.RestoreUnmountedRegion(
+        transaction.segment_.id, transaction.client_id_,
+        transaction.previous_status_, transaction.generation_);
+}
+
+ErrorCode SegmentPool::WriteAccess::RestoreUnmountedRegion(
+    const UUID& segment_id, const UUID& client_id,
+    SegmentStatus previous_status, uint64_t generation) {
+    auto mounted = catalog_.Find(segment_id);
+    if (mounted == nullptr) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    if (mounted->client_id != client_id ||
+        mounted->status != SegmentStatus::UNMOUNTING ||
+        mounted->generation != generation) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    RegionResource* resource = segment_pool_.GetResource(*mounted);
+    RegionDriver* driver = segment_pool_.GetDriver(mounted->kind);
+    if (!resource || !driver) {
+        LOG(ERROR) << "Unmount rollback missing resource or driver: segment="
+                   << mounted->segment.name << ", id=" << segment_id
+                   << ", kind=" << static_cast<int>(mounted->kind)
+                   << ", resource_present=" << (resource != nullptr)
+                   << ", driver_present=" << (driver != nullptr);
+        return ErrorCode::INTERNAL_ERROR;
+    }
+    return TransitionRegion(*mounted, *resource, previous_status);
+}
+
+tl::expected<RegionGracefulUnmountTxn, ErrorCode>
+SegmentPool::WriteAccess::PrepareGracefulUnmount(const UUID& segment_id,
+                                                 const UUID& client_id) {
+    auto mounted = catalog_.Find(segment_id);
+    if (mounted == nullptr) {
+        return tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    if (mounted->client_id != client_id) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (mounted->status != SegmentStatus::OK &&
+        mounted->status != SegmentStatus::DRAINING &&
+        mounted->status != SegmentStatus::GRACEFULLY_UNMOUNTING) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    RegionResource* resource = segment_pool_.GetResource(*mounted);
+    if (!resource) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return RegionGracefulUnmountTxn(TransactionKey{}, *this, *mounted,
+                                    *resource);
+}
+
+RegionGracefulUnmountTxn::RegionGracefulUnmountTxn(
+    TransactionKey, SegmentPool::WriteAccess& access,
+    const MountedRegion& mounted, RegionResource& resource)
+    : segment_id_(mounted.segment.id), client_id_(mounted.client_id) {
+    const auto result = access.TransitionRegion(
+        mounted, resource, SegmentStatus::GRACEFULLY_UNMOUNTING);
+    DCHECK(result == ErrorCode::OK);
+    generation_ = mounted.generation;
+}
+
+RegionGracefulUnmountTxn::RegionGracefulUnmountTxn(
+    RegionGracefulUnmountTxn&& other) noexcept
+    : segment_id_(other.segment_id_),
+      client_id_(other.client_id_),
+      generation_(other.generation_),
+      finished_(std::exchange(other.finished_, true)) {}
+
+ErrorCode RegionGracefulUnmountTxn::Finalize(
+    SegmentPool::WriteAccess& access) && {
+    auto transaction = std::move(*this);
+    if (transaction.finished_) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    return access.EraseUnmountedRegion(
+        transaction.segment_id_, transaction.client_id_,
+        SegmentStatus::GRACEFULLY_UNMOUNTING, transaction.generation_);
+}
+
+ErrorCode SegmentPool::WriteAccess::EraseUnmountedRegion(
+    const UUID& segment_id, const UUID& client_id,
+    SegmentStatus expected_status, uint64_t generation) {
+    auto mounted = catalog_.Find(segment_id);
+    if (mounted == nullptr) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    if (mounted->client_id != client_id) {
+        return ErrorCode::INVALID_PARAMS;
+    }
+    if (mounted->status != expected_status ||
+        mounted->generation != generation) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+    const MountedRegion record = *mounted;
+    RegionDriver* driver = segment_pool_.GetDriver(record.kind);
+    if (!driver || !driver->GetResource(segment_id)) {
+        return ErrorCode::INTERNAL_ERROR;
+    }
+    // Resource existence was validated above. Erase is the commit point; all
+    // remaining catalog/index operations are non-failing.
+    const bool erased = driver->Erase(segment_id);
+    DCHECK(erased);
+
+    const bool capacity_accounted =
+        segment_pool_.capacity_accounted_region_ids_.erase(segment_id) != 0;
+    const bool removed = catalog_.Erase(segment_id);
+    DCHECK(removed);
+    if (capacity_accounted) {
+        MasterMetricManager::instance().dec_total_mem_capacity(
+            record.segment.name, record.segment.size);
+        if (catalog_.RegionIds(record.segment.name).empty()) {
+            MasterMetricManager::instance().remove_segment_metrics(
+                record.segment.name);
+        }
+    }
+    return ErrorCode::OK;
+}
+
+const RegionCatalog& SegmentPool::WriteAccess::Catalog() const {
+    return catalog_;
+}
+
+ErrorCode SegmentPool::WriteAccess::SetSegmentStatusByName(
+    std::string_view segment_name, SegmentStatus status) {
+    const auto regions = catalog_.RegionIds(segment_name);
+    if (regions.empty()) {
+        return ErrorCode::SEGMENT_NOT_FOUND;
+    }
+    for (const auto& id : regions) {
+        auto mounted = catalog_.Find(id);
+        if (mounted == nullptr || !segment_pool_.GetDriver(mounted->kind) ||
+            !segment_pool_.GetResource(*mounted)) {
+            return ErrorCode::INTERNAL_ERROR;
+        }
+        if (mounted->status == SegmentStatus::UNMOUNTING) {
+            return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+        }
+    }
+
+    for (const auto& id : regions) {
+        const auto& mounted = *catalog_.Find(id);
+        auto& resource = *segment_pool_.GetResource(mounted);
+        const auto result = TransitionRegion(mounted, resource, status);
+        if (result != ErrorCode::OK) return result;
+    }
+    return ErrorCode::OK;
+}
+
+ErrorCode SegmentPool::WriteAccess::TransitionRegion(
+    const MountedRegion& mounted, RegionResource& resource,
+    SegmentStatus status) {
+    auto& driver = *segment_pool_.GetDriver(mounted.kind);
+    if (status == SegmentStatus::OK) {
+        if (!resource.active && !driver.Reactivate(mounted.segment.id)) {
+            LOG(ERROR) << "Failed to reactivate region: segment="
+                       << mounted.segment.name << ", id=" << mounted.segment.id;
+            return ErrorCode::INTERNAL_ERROR;
+        }
+        (void)segment_pool_.placement_index_.AddCandidate(
+            mounted.segment.name, *resource.candidate, mounted.segment.host_id);
+    } else {
+        (void)segment_pool_.placement_index_.RemoveCandidate(
+            mounted.segment.name, *resource.candidate, mounted.segment.host_id);
+        if (resource.active) {
+            const bool deactivated = driver.Deactivate(mounted.segment.id);
+            DCHECK(deactivated);
+        }
+    }
+    const bool updated = catalog_.SetStatus(mounted.segment.id, status);
+    DCHECK(updated);
+    return ErrorCode::OK;
+}
+
+void SegmentPool::WriteAccess::Clear() noexcept {
+    for (const auto& mounted : catalog_.Regions()) {
+        if (auto* driver = segment_pool_.GetDriver(mounted.kind)) {
+            (void)driver->Erase(mounted.segment.id);
+        }
+    }
+    segment_pool_.ReleaseCapacityMetrics();
+    segment_pool_.placement_index_.Clear();
+    catalog_.Clear();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/region_driver.cpp b/mooncake-store/src/segment/region_driver.cpp
new file mode 100644
index 0000000000..9c197e597e
--- /dev/null
+++ b/mooncake-store/src/segment/region_driver.cpp
@@ -0,0 +1,346 @@
+#include "segment/region_driver.h"
+
+#include <limits>
+#include <map>
+#include <utility>
+
+#include "master_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+bool IsValidSpec(const RegionResourceSpec& spec) {
+    return spec.id != UUID{0, 0} && !spec.name.empty() && spec.base != 0 &&
+           spec.size != 0 &&
+           spec.base <= std::numeric_limits<uintptr_t>::max() - spec.size;
+}
+
+class NativeAllocationCandidate final : public AllocationCandidate {
+   public:
+    explicit NativeAllocationCandidate(
+        std::shared_ptr<BufferAllocatorBase> allocator)
+        : AllocationCandidate(std::move(allocator)) {}
+
+    std::unique_ptr<AllocatedBuffer> Allocate(size_t size) const override {
+        return allocator().allocate(size);
+    }
+
+    AllocationCandidateKind Kind() const noexcept override {
+        return AllocationCandidateKind::NATIVE;
+    }
+};
+
+class CxlAllocationCandidate final : public AllocationCandidate {
+   public:
+    CxlAllocationCandidate(std::shared_ptr<BufferAllocatorBase> allocator,
+                           std::string binding_name)
+        : AllocationCandidate(std::move(allocator)),
+          cxl_binding_name_(std::move(binding_name)) {}
+
+    std::unique_ptr<AllocatedBuffer> Allocate(size_t size) const override {
+        auto buffer = allocator().allocate(size);
+        if (buffer) {
+            buffer->change_to_cxl(cxl_binding_name_);
+        }
+        return buffer;
+    }
+
+    AllocationCandidateKind Kind() const noexcept override {
+        return AllocationCandidateKind::CXL;
+    }
+
+   private:
+    std::string cxl_binding_name_;
+};
+
+std::unique_ptr<RegionResource> MakeNativeResource(
+    std::shared_ptr<BufferAllocatorBase> allocator) {
+    auto candidate =
+        std::make_unique<NativeAllocationCandidate>(std::move(allocator));
+    return std::make_unique<RegionResource>(std::move(candidate));
+}
+
+std::unique_ptr<RegionResource> MakeCxlResource(
+    const RegionResourceSpec& spec,
+    std::shared_ptr<BufferAllocatorBase> allocator) {
+    auto candidate = std::make_unique<CxlAllocationCandidate>(
+        std::move(allocator), spec.name);
+    return std::make_unique<RegionResource>(std::move(candidate));
+}
+
+class MemoryRegionDriver final : public RegionDriver {
+   public:
+    explicit MemoryRegionDriver(BufferAllocatorType allocator_type)
+        : RegionDriver(allocator_type) {}
+
+    tl::expected<PreparedRegionResource, ErrorCode> PrepareOpen(
+        const RegionResourceSpec& spec,
+        const std::vector<LiveAllocation>& live_allocations) override;
+    tl::expected<PreparedRegionResource, ErrorCode> PrepareAdopt(
+        const RegionResourceSpec& spec,
+        std::shared_ptr<BufferAllocatorBase> allocator) override;
+};
+
+class CxlRegionDriver final : public RegionDriver {
+   public:
+    explicit CxlRegionDriver(
+        std::shared_ptr<BufferAllocatorBase> global_allocator);
+    ~CxlRegionDriver() override;
+
+    tl::expected<PreparedRegionResource, ErrorCode> PrepareOpen(
+        const RegionResourceSpec& spec,
+        const std::vector<LiveAllocation>& live_allocations) override;
+    tl::expected<PreparedRegionResource, ErrorCode> PrepareAdopt(
+        const RegionResourceSpec& spec,
+        std::shared_ptr<BufferAllocatorBase> allocator) override;
+
+   private:
+    std::shared_ptr<BufferAllocatorBase> global_allocator_;
+};
+
+}  // namespace
+
+RegionResource::RegionResource(
+    std::unique_ptr<AllocationCandidate> allocation_candidate)
+    : candidate(std::move(allocation_candidate)) {}
+
+struct PreparedRegionResource::State {
+    State(RegionDriver& resource_driver, const UUID& id,
+          std::unique_ptr<RegionResource> staged_resource,
+          std::vector<std::unique_ptr<AllocatedBuffer>> buffers)
+        : driver(resource_driver), imported_buffers(std::move(buffers)) {
+        ResourceMap staged;
+        auto inserted = staged.emplace(id, std::move(staged_resource));
+        resource = staged.extract(inserted.first);
+    }
+
+    RegionDriver& driver;
+    ResourceMap::node_type resource;
+    std::vector<std::unique_ptr<AllocatedBuffer>> imported_buffers;
+    std::unique_ptr<RegionResource> replaced_resource;
+};
+
+PreparedRegionResource::PreparedRegionResource(
+    StageKey, RegionDriver& driver, const UUID& id,
+    std::unique_ptr<RegionResource> resource,
+    std::vector<std::unique_ptr<AllocatedBuffer>> imported_buffers)
+    : state_(std::make_unique<State>(driver, id, std::move(resource),
+                                     std::move(imported_buffers))) {}
+
+PreparedRegionResource::~PreparedRegionResource() = default;
+PreparedRegionResource::PreparedRegionResource(
+    PreparedRegionResource&& other) noexcept = default;
+PreparedRegionResource& PreparedRegionResource::operator=(
+    PreparedRegionResource&& other) noexcept = default;
+
+RegionResource& PreparedRegionResource::resource() const noexcept {
+    return *state_->resource.mapped();
+}
+
+const std::vector<std::unique_ptr<AllocatedBuffer>>&
+PreparedRegionResource::imported_buffers() const noexcept {
+    static const std::vector<std::unique_ptr<AllocatedBuffer>> empty;
+    return state_ ? state_->imported_buffers : empty;
+}
+
+std::vector<std::unique_ptr<AllocatedBuffer>>
+PreparedRegionResource::TakeImportedBuffers() {
+    return state_ ? std::move(state_->imported_buffers)
+                  : std::vector<std::unique_ptr<AllocatedBuffer>>{};
+}
+
+void PreparedRegionResource::Commit() noexcept {
+    if (!state_ || state_->resource.empty()) {
+        return;
+    }
+    state_->replaced_resource = state_->driver.CommitPrepared(state_->resource);
+}
+
+std::unique_ptr<RegionResource> RegionDriver::CommitPrepared(
+    ResourceMap::node_type& resource) noexcept {
+    auto existing = resources_.extract(resource.key());
+    std::unique_ptr<RegionResource> replaced;
+    if (!existing.empty()) {
+        replaced = std::move(existing.mapped());
+    }
+    resource.mapped()->active = true;
+    resources_.insert(std::move(resource));
+    return replaced;
+}
+
+RegionResource* RegionDriver::GetResource(const UUID& id) {
+    auto it = resources_.find(id);
+    return it == resources_.end() ? nullptr : it->second.get();
+}
+
+const RegionResource* RegionDriver::GetResource(const UUID& id) const {
+    auto it = resources_.find(id);
+    return it == resources_.end() ? nullptr : it->second.get();
+}
+
+bool RegionDriver::Deactivate(const UUID& id) {
+    auto* resource = GetResource(id);
+    if (!resource || !resource->active) {
+        return false;
+    }
+    resource->active = false;
+    return true;
+}
+
+bool RegionDriver::Reactivate(const UUID& id) {
+    auto* resource = GetResource(id);
+    if (!resource || resource->active) {
+        return false;
+    }
+    resource->active = true;
+    return true;
+}
+
+bool RegionDriver::Erase(const UUID& id) { return resources_.erase(id) != 0; }
+
+PreparedRegionResource RegionDriver::Stage(
+    const UUID& id, std::unique_ptr<RegionResource> resource,
+    std::vector<std::unique_ptr<AllocatedBuffer>> imported_buffers) {
+    return PreparedRegionResource(StageKey{}, *this, id, std::move(resource),
+                                  std::move(imported_buffers));
+}
+
+namespace {
+
+tl::expected<PreparedRegionResource, ErrorCode> MemoryRegionDriver::PrepareOpen(
+    const RegionResourceSpec& spec,
+    const std::vector<LiveAllocation>& live_allocations) {
+    if (!IsValidSpec(spec)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    if (live_allocations.empty()) {
+        auto allocator =
+            CreateBufferAllocator(*allocator_type(), spec.name, spec.base,
+                                  spec.size, spec.transport_endpoint);
+        if (!allocator) {
+            return tl::make_unexpected(allocator.error());
+        }
+        return Stage(spec.id, MakeNativeResource(std::move(*allocator)));
+    }
+
+    if (*allocator_type() == BufferAllocatorType::CACHELIB) {
+        auto restored = ImportCachelibBufferAllocator(
+            spec.name, spec.base, spec.size, spec.transport_endpoint,
+            live_allocations);
+        if (!restored) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        auto resource = MakeNativeResource(std::move(restored->allocator));
+        return Stage(spec.id, std::move(resource),
+                     std::move(restored->buffers));
+    }
+    if (*allocator_type() == BufferAllocatorType::OFFSET) {
+        auto restored = ImportOffsetBufferAllocator(
+            spec.name, spec.base, spec.size, spec.transport_endpoint,
+            live_allocations);
+        if (!restored) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        auto resource = MakeNativeResource(std::move(restored->allocator));
+        return Stage(spec.id, std::move(resource),
+                     std::move(restored->buffers));
+    }
+    return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+}
+
+tl::expected<PreparedRegionResource, ErrorCode>
+MemoryRegionDriver::PrepareAdopt(
+    const RegionResourceSpec& spec,
+    std::shared_ptr<BufferAllocatorBase> allocator) {
+    if (!IsValidSpec(spec) || !allocator ||
+        allocator->getSegmentName() != spec.name ||
+        allocator->getTransportEndpoint() != spec.transport_endpoint ||
+        allocator->base() != spec.base || allocator->capacity() != spec.size) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return Stage(spec.id, MakeNativeResource(std::move(allocator)));
+}
+
+CxlRegionDriver::CxlRegionDriver(
+    std::shared_ptr<BufferAllocatorBase> global_allocator)
+    : global_allocator_(std::move(global_allocator)) {
+    MasterMetricManager::instance().inc_total_mem_capacity(
+        global_allocator_->getSegmentName(), global_allocator_->capacity());
+}
+
+CxlRegionDriver::~CxlRegionDriver() {
+    const std::string name = global_allocator_->getSegmentName();
+    auto& metrics = MasterMetricManager::instance();
+    metrics.dec_total_mem_capacity(name, global_allocator_->capacity());
+    if (metrics.get_segment_total_mem_capacity(name) == 0) {
+        metrics.remove_segment_metrics(name);
+    }
+}
+
+tl::expected<PreparedRegionResource, ErrorCode> CxlRegionDriver::PrepareOpen(
+    const RegionResourceSpec& spec,
+    const std::vector<LiveAllocation>& live_allocations) {
+    if (!live_allocations.empty()) {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    }
+    if (spec.id == UUID{0, 0} || spec.name.empty() || spec.size == 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return Stage(spec.id, MakeCxlResource(spec, global_allocator_));
+}
+
+tl::expected<PreparedRegionResource, ErrorCode> CxlRegionDriver::PrepareAdopt(
+    const RegionResourceSpec& spec,
+    std::shared_ptr<BufferAllocatorBase> allocator) {
+    (void)spec;
+    (void)allocator;
+    return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+}
+
+}  // namespace
+
+tl::expected<RegionDriverRegistry, ErrorCode> CreateRegionDrivers(
+    const RegionDriverConfig& config) {
+    RegionDriverRegistry drivers;
+    drivers.emplace(
+        RegionKind::HOST_MEMORY,
+        std::make_unique<MemoryRegionDriver>(config.memory_allocator));
+    if (config.cxl) {
+        auto allocator = CreateBufferAllocator(
+            BufferAllocatorType::CACHELIB, config.cxl->path, DEFAULT_CXL_BASE,
+            config.cxl->size, config.cxl->path);
+        if (!allocator) {
+            return tl::make_unexpected(allocator.error());
+        }
+        drivers.emplace(RegionKind::CXL, std::make_unique<CxlRegionDriver>(
+                                             std::move(*allocator)));
+    }
+    return drivers;
+}
+
+tl::expected<std::vector<LiveAllocation>, ErrorCode> BuildRegionLiveAllocations(
+    const RegionResourceSpec& spec,
+    std::span<const AllocatedBuffer::Descriptor> descriptors) {
+    if (spec.id == UUID{0, 0} || spec.name.empty() || spec.base == 0 ||
+        spec.size == 0 ||
+        spec.base > std::numeric_limits<uintptr_t>::max() - spec.size) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const uintptr_t end = spec.base + spec.size;
+    std::vector<LiveAllocation> allocations;
+    allocations.reserve(descriptors.size());
+    for (const auto& descriptor : descriptors) {
+        if (descriptor.transport_endpoint_ != spec.transport_endpoint ||
+            descriptor.size_ == 0 || descriptor.buffer_address_ < spec.base ||
+            descriptor.buffer_address_ >= end ||
+            descriptor.size_ > end - descriptor.buffer_address_) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        allocations.push_back(
+            {descriptor.buffer_address_ - spec.base, descriptor.size_});
+    }
+    return allocations;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment/snapshot.cpp b/mooncake-store/src/segment/snapshot.cpp
new file mode 100644
index 0000000000..815a123ead
--- /dev/null
+++ b/mooncake-store/src/segment/snapshot.cpp
@@ -0,0 +1,123 @@
+#include "segment/snapshot.h"
+
+#include <algorithm>
+#include <map>
+#include <set>
+
+#include "segment/pool.h"
+#include "segment/pool_write_access.h"
+
+namespace mooncake {
+
+tl::expected<SegmentPoolSnapshot, ErrorCode> SegmentPool::CaptureSnapshot()
+    const {
+    const auto* driver = GetDriver(RegionKind::HOST_MEMORY);
+    if (!driver || driver->allocator_type() != BufferAllocatorType::OFFSET) {
+        return tl::make_unexpected(ErrorCode::SERIALIZE_UNSUPPORTED);
+    }
+    // Validate supported resources before copying any allocator layouts.
+    for (const auto& mounted : catalog_.Regions()) {
+        if (mounted.kind != RegionKind::HOST_MEMORY) {
+            return tl::make_unexpected(ErrorCode::SERIALIZE_UNSUPPORTED);
+        }
+    }
+
+    SegmentPoolSnapshot snapshot;
+    placement_index_.GetActiveSegmentNames(AllocationCandidateKind::NATIVE,
+                                           snapshot.active_names);
+    snapshot.regions.reserve(catalog_.Regions().size());
+    for (const auto& mounted : catalog_.Regions()) {
+        const auto* resource = GetResource(mounted);
+        if (!resource || !resource->allocator()) {
+            return tl::make_unexpected(ErrorCode::SERIALIZE_FAIL);
+        }
+        const auto* allocator = dynamic_cast<const OffsetBufferAllocator*>(
+            resource->allocator().get());
+        if (!allocator) {
+            return tl::make_unexpected(ErrorCode::SERIALIZE_UNSUPPORTED);
+        }
+        snapshot.regions.push_back({mounted, allocator->CaptureSnapshot()});
+    }
+    std::sort(snapshot.regions.begin(), snapshot.regions.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.mounted.segment.id < rhs.mounted.segment.id;
+              });
+    return snapshot;
+}
+
+tl::expected<void, ErrorCode> SegmentPool::RestoreSnapshot(
+    SegmentPoolSnapshot snapshot, bool account_capacity_metrics) {
+    auto access = AcquireWriteAccess();
+    const auto* driver = GetDriver(RegionKind::HOST_MEMORY);
+    if (!driver ||
+        snapshot.memory_allocator_type != BufferAllocatorType::OFFSET ||
+        driver->allocator_type() != snapshot.memory_allocator_type) {
+        return tl::make_unexpected(ErrorCode::DESERIALIZE_FAIL);
+    }
+    std::set<UUID> ids;
+    std::map<std::string, UUID> owners;
+    std::set<std::string> active_names;
+    for (const auto& region : snapshot.regions) {
+        const auto& mounted = region.mounted;
+        if (!IsKnownSegmentStatus(mounted.status)) {
+            return tl::make_unexpected(ErrorCode::DESERIALIZE_FAIL);
+        }
+        auto [owner, inserted] =
+            owners.emplace(mounted.segment.name, mounted.client_id);
+        if (!ids.insert(mounted.segment.id).second ||
+            (!inserted && owner->second != mounted.client_id) ||
+            mounted.kind != RegionKind::HOST_MEMORY ||
+            region.allocator.segment_name != mounted.segment.name ||
+            region.allocator.base != mounted.segment.base ||
+            region.allocator.capacity != mounted.segment.size ||
+            region.allocator.transport_endpoint !=
+                mounted.segment.te_endpoint) {
+            return tl::make_unexpected(ErrorCode::DESERIALIZE_FAIL);
+        }
+        if (mounted.status == SegmentStatus::OK)
+            active_names.insert(mounted.segment.name);
+    }
+    if (active_names != std::set<std::string>(snapshot.active_names.begin(),
+                                              snapshot.active_names.end()) ||
+        active_names.size() != snapshot.active_names.size()) {
+        return tl::make_unexpected(ErrorCode::DESERIALIZE_FAIL);
+    }
+    std::vector<RegionMountTxn> prepared;
+    prepared.reserve(snapshot.regions.size());
+    // Preserve the active-name order even for snapshots captured in ID order.
+    auto prepare =
+        [&](RegionSnapshot& region) -> tl::expected<void, ErrorCode> {
+        auto allocator =
+            OffsetBufferAllocator::Restore(std::move(region.allocator));
+        if (!allocator) return tl::make_unexpected(allocator.error());
+        auto txn = access.PrepareAdopt(region.mounted, std::move(*allocator),
+                                       account_capacity_metrics,
+                                       WriteAccess::AdoptMode::ReplacePool);
+        if (!txn) return tl::make_unexpected(txn.error());
+        prepared.push_back(std::move(*txn));
+        return {};
+    };
+    for (const auto& name : snapshot.active_names) {
+        for (auto& region : snapshot.regions) {
+            if (region.mounted.status == SegmentStatus::OK &&
+                region.mounted.segment.name == name) {
+                auto result = prepare(region);
+                if (!result) return result;
+            }
+        }
+    }
+    for (auto& region : snapshot.regions) {
+        if (region.mounted.status != SegmentStatus::OK) {
+            auto result = prepare(region);
+            if (!result) return result;
+        }
+    }
+    access.Clear();
+    for (auto& txn : prepared) {
+        const auto result = txn.Commit(access);
+        if (result != ErrorCode::OK) return tl::make_unexpected(result);
+    }
+    return {};
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/segment_allocator_registration.cpp b/mooncake-store/src/segment_allocator_registration.cpp
new file mode 100644
index 0000000000..7684bc331e
--- /dev/null
+++ b/mooncake-store/src/segment_allocator_registration.cpp
@@ -0,0 +1,84 @@
+#include "segment_allocator_registration.h"
+
+#include <utility>
+
+namespace mooncake {
+
+SegmentAllocatorRegistration::SegmentAllocatorRegistration(
+    std::shared_ptr<BufferAllocatorBase> allocator,
+    std::shared_ptr<ClientLivenessRecord> client_liveness)
+    : allocator_(std::move(allocator)),
+      client_liveness_(std::move(client_liveness)) {}
+
+bool SegmentAllocatorRegistration::IsServing() const {
+    if (!allocation_lifetime_.isAvailable()) {
+        return false;
+    }
+    const auto record =
+        std::atomic_load_explicit(&client_liveness_, std::memory_order_acquire);
+    return !record || record->IsServing();
+}
+
+std::unique_ptr<AllocatedBuffer> SegmentAllocatorRegistration::Allocate(
+    size_t size) const {
+    if (!allocation_lifetime_.isAvailable()) {
+        return nullptr;
+    }
+    const auto record =
+        std::atomic_load_explicit(&client_liveness_, std::memory_order_acquire);
+    if (record && !record->IsServing()) {
+        return nullptr;
+    }
+    auto buffer = GetAllocator()->allocate(size);
+    if (!buffer) {
+        return nullptr;
+    }
+    buffer->bindSegmentLifetime(buffer_lifetime_);
+    buffer->bindClientLiveness(record);
+    if (!allocation_lifetime_.isAvailable() ||
+        record != std::atomic_load_explicit(&client_liveness_,
+                                            std::memory_order_acquire) ||
+        (record && !record->IsServing())) {
+        return nullptr;
+    }
+    return buffer;
+}
+
+std::shared_ptr<BufferAllocatorBase>
+SegmentAllocatorRegistration::GetAllocator() const {
+    return std::atomic_load_explicit(&allocator_, std::memory_order_acquire);
+}
+
+void SegmentAllocatorRegistration::BindAllocator(
+    std::shared_ptr<BufferAllocatorBase> replacement) {
+    std::atomic_store_explicit(&allocator_, std::move(replacement),
+                               std::memory_order_release);
+}
+
+void SegmentAllocatorRegistration::BindClientLiveness(
+    std::shared_ptr<ClientLivenessRecord> record) {
+    std::atomic_store_explicit(&client_liveness_, std::move(record),
+                               std::memory_order_release);
+}
+
+void SegmentAllocatorRegistration::BindBuffer(AllocatedBuffer& buffer) const {
+    buffer.bindSegmentLifetime(buffer_lifetime_);
+    buffer.bindClientLiveness(std::atomic_load_explicit(
+        &client_liveness_, std::memory_order_acquire));
+}
+
+bool SegmentAllocatorRegistration::OwnsBuffer(
+    const AllocatedBuffer& buffer) const {
+    return buffer.segment_lifetime_ == buffer_lifetime_;
+}
+
+void SegmentAllocatorRegistration::SetAllocatable(bool allocatable) {
+    allocation_lifetime_.setAvailable(allocatable);
+}
+
+void SegmentAllocatorRegistration::Invalidate() {
+    allocation_lifetime_.setAvailable(false);
+    buffer_lifetime_.setAvailable(false);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/serialize/serializer.cpp b/mooncake-store/src/serialize/serializer.cpp
index ffc9ff8cc1..2006d22e4c 100644
--- a/mooncake-store/src/serialize/serializer.cpp
+++ b/mooncake-store/src/serialize/serializer.cpp
@@ -1,11 +1,14 @@
+#include <array>
 #include <iostream>
+#include <optional>
 #include <vector>
 
 #include "serialize/serializer.h"
+#include "ha/snapshot/allocator_snapshot_codec.h"
 #include "offset_allocator/offset_allocator.h"
 #include "types.h"
 #include "master_service.h"
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake {
 
@@ -120,68 +123,112 @@ Serializer<offset_allocator::__Allocator>::deserialize(
     auto *array_items = obj.via.array.ptr;
     size_t index = 0;
 
-    // Deserialize basic properties
-    uint32_t size = array_items[index++].as<uint32_t>();
-    uint32_t current_capacity = array_items[index++].as<uint32_t>();
-    uint32_t max_capacity = array_items[index++].as<uint32_t>();
-
-    // Create allocator object
-    auto allocator = std::make_unique<offset_allocator::__Allocator>(
-        size, current_capacity, max_capacity);
-
-    allocator->m_freeStorage = array_items[index++].as<uint32_t>();
-    allocator->m_usedBinsTop = array_items[index++].as<uint32_t>();
-
-    // Deserialize usedBins array
-    const auto &used_bins_array = array_items[index++];
-    if (used_bins_array.type != msgpack::type::ARRAY) {
-        return tl::unexpected(
-            SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                               "deserialize offset_allocator::__Allocator "
-                               "usedBins is not an array"));
+    // Parse every scalar before materializing or decompressing anything: the
+    // allocator constructor reserves max_capacity nodes, so corrupt capacities
+    // and a corrupt freeOffset must be rejected against the node bound before a
+    // payload can request large storage.
+    uint32_t size = 0;
+    uint32_t current_capacity = 0;
+    uint32_t max_capacity = 0;
+    uint32_t free_storage = 0;
+    uint32_t used_bins_top = 0;
+    uint32_t free_offset = 0;
+    try {
+        size = array_items[index++].as<uint32_t>();
+        current_capacity = array_items[index++].as<uint32_t>();
+        max_capacity = array_items[index++].as<uint32_t>();
+        free_storage = array_items[index++].as<uint32_t>();
+        used_bins_top = array_items[index++].as<uint32_t>();
+        // freeOffset is packed last; reading it here keeps the whole scalar
+        // header validated before any node payload is touched.
+        free_offset = array_items[9].as<uint32_t>();
+    } catch (const std::exception &e) {
+        return tl::unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            fmt::format("deserialize offset_allocator::__Allocator invalid "
+                        "scalar field: {}",
+                        e.what())));
     }
 
-    if (used_bins_array.via.array.size != offset_allocator::NUM_TOP_BINS) {
+    if (auto valid =
+            offset_allocator::OffsetAllocatorSnapshot::ValidateNodeCapacity(
+                size, current_capacity, max_capacity, free_offset);
+        !valid) {
         return tl::unexpected(SerializationError(
             ErrorCode::DESERIALIZE_FAIL,
-            fmt::format("deserialize offset_allocator::__Allocator usedBins "
-                        "invalid size: expected {}, got {}",
-                        offset_allocator::NUM_TOP_BINS,
-                        used_bins_array.via.array.size)));
+            fmt::format("deserialize offset_allocator::__Allocator {}",
+                        valid.error())));
     }
 
-    for (uint32_t i = 0; i < used_bins_array.via.array.size &&
-                         i < offset_allocator::NUM_TOP_BINS;
-         i++) {
-        allocator->m_usedBins[i] =
-            used_bins_array.via.array.ptr[i].as<uint8_t>();
-    }
+    std::array<uint8_t, offset_allocator::NUM_TOP_BINS> used_bins{};
+    std::array<offset_allocator::NodeIndex, offset_allocator::NUM_LEAF_BINS>
+        bin_indices{};
+    try {
+        // Deserialize usedBins array
+        const auto &used_bins_array = array_items[index++];
+        if (used_bins_array.type != msgpack::type::ARRAY) {
+            return tl::unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "deserialize offset_allocator::__Allocator "
+                                   "usedBins is not an array"));
+        }
 
-    // Deserialize binIndices array
-    const auto &bin_indices_array = array_items[index++];
-    if (bin_indices_array.type != msgpack::type::ARRAY) {
-        return tl::unexpected(
-            SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                               "deserialize offset_allocator::__Allocator "
-                               "binIndices is not an array"));
-    }
+        if (used_bins_array.via.array.size != offset_allocator::NUM_TOP_BINS) {
+            return tl::unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                fmt::format(
+                    "deserialize offset_allocator::__Allocator usedBins "
+                    "invalid size: expected {}, got {}",
+                    offset_allocator::NUM_TOP_BINS,
+                    used_bins_array.via.array.size)));
+        }
 
-    if (bin_indices_array.via.array.size != offset_allocator::NUM_LEAF_BINS) {
+        for (uint32_t i = 0; i < offset_allocator::NUM_TOP_BINS; i++) {
+            used_bins[i] = used_bins_array.via.array.ptr[i].as<uint8_t>();
+        }
+
+        // Deserialize binIndices array
+        const auto &bin_indices_array = array_items[index++];
+        if (bin_indices_array.type != msgpack::type::ARRAY) {
+            return tl::unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "deserialize offset_allocator::__Allocator "
+                                   "binIndices is not an array"));
+        }
+
+        if (bin_indices_array.via.array.size !=
+            offset_allocator::NUM_LEAF_BINS) {
+            return tl::unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                fmt::format(
+                    "deserialize offset_allocator::__Allocator binIndices "
+                    "invalid size: expected {}, got {}",
+                    offset_allocator::NUM_LEAF_BINS,
+                    bin_indices_array.via.array.size)));
+        }
+
+        for (uint32_t i = 0; i < offset_allocator::NUM_LEAF_BINS; i++) {
+            const uint32_t bin_index =
+                bin_indices_array.via.array.ptr[i].as<uint32_t>();
+            if (bin_index != offset_allocator::__Allocator::Node::unused &&
+                bin_index >= current_capacity) {
+                return tl::unexpected(SerializationError(
+                    ErrorCode::DESERIALIZE_FAIL,
+                    fmt::format("deserialize offset_allocator::__Allocator bin "
+                                "index {} is out of range for capacity {}",
+                                bin_index, current_capacity)));
+            }
+            bin_indices[i] = bin_index;
+        }
+    } catch (const std::exception &e) {
         return tl::unexpected(SerializationError(
             ErrorCode::DESERIALIZE_FAIL,
-            fmt::format("deserialize offset_allocator::__Allocator binIndices "
-                        "invalid size: expected {}, got {}",
-                        offset_allocator::NUM_LEAF_BINS,
-                        bin_indices_array.via.array.size)));
-    }
-
-    for (uint32_t i = 0; i < bin_indices_array.via.array.size &&
-                         i < offset_allocator::NUM_LEAF_BINS;
-         i++) {
-        allocator->m_binIndices[i] =
-            bin_indices_array.via.array.ptr[i].as<uint32_t>();
+            fmt::format("deserialize offset_allocator::__Allocator invalid "
+                        "bitmap field: {}",
+                        e.what())));
     }
 
+    std::vector<uint8_t> serialized_nodes;
     try {
         // Deserialize compressed nodes data
         const auto &nodes_bin = array_items[index++];
@@ -192,56 +239,91 @@ Serializer<offset_allocator::__Allocator>::deserialize(
                                    "nodes data is not binary"));
         }
 
-        // Create copy of compressed data
-        std::vector<uint8_t> compressed_data(
+        // The payload must describe exactly the nodes it will populate, so the
+        // decompression is bounded by that size: a frame header can then never
+        // request a far larger buffer.
+        const size_t expected_size = static_cast<size_t>(current_capacity) *
+                                     OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE;
+        serialized_nodes = zstd_decompress(
             reinterpret_cast<const uint8_t *>(nodes_bin.via.bin.ptr),
-            reinterpret_cast<const uint8_t *>(nodes_bin.via.bin.ptr) +
-                nodes_bin.via.bin.size);
-
-        // Decompress data
-        std::vector<uint8_t> serialized_nodes =
-            zstd_decompress(compressed_data);
-
-        // Verify decompressed data size is reasonable
-        if (serialized_nodes.size() % OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE !=
-            0) {
+            nodes_bin.via.bin.size, expected_size);
+        if (serialized_nodes.size() != expected_size) {
             return tl::unexpected(SerializationError(
                 ErrorCode::DESERIALIZE_FAIL,
                 fmt::format("deserialize offset_allocator::__Allocator invalid "
-                            "serialized nodes data size: expected multiple of "
-                            "{}, actual size: {}",
-                            OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE,
-                            serialized_nodes.size())));
+                            "serialized nodes data size: expected {}, actual "
+                            "size: {}",
+                            expected_size, serialized_nodes.size())));
         }
+    } catch (const std::exception &e) {
+        return tl::unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            fmt::format("deserialize offset_allocator::__Allocator error "
+                        "decompressing nodes: {}",
+                        e.what())));
+    }
 
-        if (serialized_nodes.size() / OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE !=
-            current_capacity) {
+    std::vector<uint32_t> free_nodes;
+    try {
+        // Deserialize compressed freeNodes data
+        const auto &free_nodes_bin = array_items[index++];
+        if (free_nodes_bin.type != msgpack::type::BIN) {
+            return tl::unexpected(
+                SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                   "deserialize offset_allocator::__Allocator "
+                                   "freeNodes data is not binary"));
+        }
+
+        // Bounded like the node payload, then required to be exact.
+        const size_t expected_size = static_cast<size_t>(current_capacity) * 4;
+        const std::vector<uint8_t> serialized_free_nodes = zstd_decompress(
+            reinterpret_cast<const uint8_t *>(free_nodes_bin.via.bin.ptr),
+            free_nodes_bin.via.bin.size, expected_size);
+        if (serialized_free_nodes.size() != expected_size) {
             return tl::unexpected(SerializationError(
                 ErrorCode::DESERIALIZE_FAIL,
-                fmt::format("deserialize offset_allocator::__Allocator invalid "
-                            "serialized nodes data size: expected quotient of "
-                            "{}, actual quotient: {}",
-                            current_capacity,
-                            serialized_nodes.size() /
-                                OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE)));
+                fmt::format(
+                    "deserialize offset_allocator::__Allocator invalid "
+                    "serialized free nodes data size: expected {}, actual {}",
+                    expected_size, serialized_free_nodes.size())));
+        }
+
+        // Deserialize freeNodes array in standardized format
+        free_nodes.resize(current_capacity);
+        for (uint32_t i = 0; i < current_capacity; i++) {
+            free_nodes[i] = SerializationHelper::deserializeUint32(
+                &serialized_free_nodes[static_cast<size_t>(i) * 4]);
+        }
+    } catch (const std::exception &e) {
+        return tl::unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            fmt::format("deserialize offset_allocator::__Allocator error "
+                        "processing free nodes: {}",
+                        e.what())));
+    }
+
+    // Capacities and payload sizes are consistent: both the reservation and
+    // populated node storage are bounded, and every copy stays in range.
+    try {
+        auto allocator = std::make_unique<offset_allocator::__Allocator>(
+            size, current_capacity, max_capacity);
+        allocator->m_freeStorage = free_storage;
+        allocator->m_usedBinsTop = used_bins_top;
+        allocator->m_freeOffset = free_offset;
+        for (uint32_t i = 0; i < offset_allocator::NUM_TOP_BINS; i++) {
+            allocator->m_usedBins[i] = used_bins[i];
+        }
+        for (uint32_t i = 0; i < offset_allocator::NUM_LEAF_BINS; i++) {
+            allocator->m_binIndices[i] = bin_indices[i];
         }
 
         // Deserialize nodes array in standardized format
         size_t offset = 0;
         for (uint32_t i = 0; i < current_capacity; i++) {
-            if (offset + OFFSET_ALLOCATOR_NODE_SERIALIZED_SIZE >
-                serialized_nodes.size()) {
-                return tl::unexpected(SerializationError(
-                    ErrorCode::DESERIALIZE_FAIL,
-                    fmt::format("deserialize offset_allocator::__Allocator "
-                                "incomplete serialized nodes data at index {}",
-                                i)));
-            }
-
             // Deserialize bool field
             allocator->m_nodes[i].used = (serialized_nodes[offset++] != 0);
 
-            // Deserialize uint32_t field
+            // Deserialize uint32_t fields
             allocator->m_nodes[i].dataOffset =
                 SerializationHelper::deserializeUint32(
                     &serialized_nodes[offset]);
@@ -267,71 +349,18 @@ Serializer<offset_allocator::__Allocator>::deserialize(
                     &serialized_nodes[offset]);
             offset += 4;
         }
-    } catch (const std::exception &e) {
-        return tl::unexpected(SerializationError(
-            ErrorCode::DESERIALIZE_FAIL,
-            fmt::format("deserialize offset_allocator::__Allocator error "
-                        "decompressing nodes: {}",
-                        e.what())));
-    }
-
-    try {
-        // Deserialize compressed freeNodes data
-        const auto &free_nodes_bin = array_items[index++];
-        if (free_nodes_bin.type != msgpack::type::BIN) {
-            return tl::unexpected(
-                SerializationError(ErrorCode::DESERIALIZE_FAIL,
-                                   "deserialize offset_allocator::__Allocator "
-                                   "freeNodes data is not binary"));
-        }
-
-        // Create copy of compressed data
-        std::vector<uint8_t> compressed_data(
-            reinterpret_cast<const uint8_t *>(free_nodes_bin.via.bin.ptr),
-            reinterpret_cast<const uint8_t *>(free_nodes_bin.via.bin.ptr) +
-                free_nodes_bin.via.bin.size);
-
-        // Decompress data
-        std::vector<uint8_t> serialized_free_nodes =
-            zstd_decompress(compressed_data);
-
-        // Verify decompressed data size is reasonable
-        if (serialized_free_nodes.size() != current_capacity * 4) {
-            return tl::unexpected(SerializationError(
-                ErrorCode::DESERIALIZE_FAIL,
-                fmt::format(
-                    "deserialize offset_allocator::__Allocator invalid "
-                    "serialized free nodes data size: expected {}, actual {}",
-                    current_capacity * 4, serialized_free_nodes.size())));
-        }
-
-        // Deserialize freeNodes array in standardized format
-        size_t offset = 0;
         for (uint32_t i = 0; i < current_capacity; i++) {
-            if (offset + 4 > serialized_free_nodes.size()) {
-                return tl::unexpected(SerializationError(
-                    ErrorCode::DESERIALIZE_FAIL,
-                    fmt::format(
-                        "deserialize offset_allocator::__Allocator incomplete "
-                        "serialized free nodes data at index {}",
-                        i)));
-            }
-            allocator->m_freeNodes[i] = SerializationHelper::deserializeUint32(
-                &serialized_free_nodes[offset]);
-            offset += 4;
+            allocator->m_freeNodes[i] = free_nodes[i];
         }
+
+        return allocator;
     } catch (const std::exception &e) {
         return tl::unexpected(SerializationError(
             ErrorCode::DESERIALIZE_FAIL,
             fmt::format("deserialize offset_allocator::__Allocator error "
-                        "processing free nodes: {}",
+                        "constructing layout: {}",
                         e.what())));
     }
-
-    // Deserialize freeOffset
-    allocator->m_freeOffset = array_items[index++].as<uint32_t>();
-
-    return allocator;
 }
 
 // serialize_msgpack
@@ -384,33 +413,53 @@ auto Serializer<offset_allocator::OffsetAllocator>::deserialize(
     auto *array_items = obj.via.array.ptr;
     size_t index = 0;
 
-    // Deserialize basic properties
-    uint64_t base = array_items[index++].as<uint64_t>();
-    uint64_t multiplier_bits = array_items[index++].as<uint64_t>();
-    uint64_t capacity = array_items[index++].as<uint64_t>();
+    try {
+        // Deserialize basic properties
+        uint64_t base = array_items[index++].as<uint64_t>();
+        uint64_t multiplier_bits = array_items[index++].as<uint64_t>();
+        uint64_t capacity = array_items[index++].as<uint64_t>();
+
+        uint64_t allocated_size = array_items[index++].as<uint64_t>();
+        uint64_t allocated_num = array_items[index++].as<uint64_t>();
+
+        // Deserialize __Allocator
+        auto allocator_result =
+            Serializer<offset_allocator::__Allocator>::deserialize(
+                array_items[index++]);
+        if (!allocator_result) {
+            return tl::unexpected(allocator_result.error());
+        }
 
-    uint64_t allocated_size = array_items[index++].as<uint64_t>();
-    uint64_t allocated_num = array_items[index++].as<uint64_t>();
+        // Install through the same factory that snapshot restore uses: it runs
+        // the full layout validation exactly once and returns the detailed
+        // reason.
+        offset_allocator::OffsetAllocatorSnapshot snapshot{
+            .base = base,
+            .multiplier_bits = multiplier_bits,
+            .capacity = capacity,
+            .allocated_size = allocated_size,
+            .allocated_num = allocated_num,
+            .layout = std::move(allocator_result.value()),
+        };
+        auto offset_allocator =
+            offset_allocator::OffsetAllocator::Restore(std::move(snapshot));
+        if (!offset_allocator) {
+            return tl::unexpected(SerializationError(
+                ErrorCode::DESERIALIZE_FAIL,
+                fmt::format(
+                    "deserialize offset_allocator::OffsetAllocator rejected "
+                    "its state: {}",
+                    offset_allocator.error())));
+        }
 
-    // Deserialize __Allocator
-    // Pass the third element of the array directly to __Allocator's deserialize
-    // function
-    auto allocator_result =
-        Serializer<offset_allocator::__Allocator>::deserialize(
-            array_items[index++]);
-    if (!allocator_result) {
-        return tl::unexpected(allocator_result.error());
+        return *offset_allocator;
+    } catch (const std::exception &e) {
+        return tl::unexpected(SerializationError(
+            ErrorCode::DESERIALIZE_FAIL,
+            fmt::format(
+                "deserialize offset_allocator::OffsetAllocator failed: {}",
+                e.what())));
     }
-
-    // Create OffsetAllocator instance
-    auto offset_allocator = std::shared_ptr<offset_allocator::OffsetAllocator>(
-        new offset_allocator::OffsetAllocator(
-            base, capacity, multiplier_bits,
-            std::move(allocator_result.value())));
-    offset_allocator->m_allocated_size = allocated_size;
-    offset_allocator->m_allocated_num = allocated_num;
-
-    return offset_allocator;
 }
 
 tl::expected<void, SerializationError>
@@ -643,6 +692,9 @@ auto Serializer<AllocatedBuffer>::deserialize(const msgpack::object &obj,
     // Create AllocatedBuffer object
     auto buffer = std::make_unique<AllocatedBuffer>(allocator, buffer_ptr, size,
                                                     std::move(offsetHandle));
+    if (mountedSegment.allocator_registration) {
+        mountedSegment.allocator_registration->BindBuffer(*buffer);
+    }
     // buffer->status = status;
 
     return buffer;
@@ -712,6 +764,24 @@ tl::expected<void, SerializationError> Serializer<Replica>::serialize(
             packer.pack(local_data->transport_endpoint);
             break;
         }
+        case ReplicaType::DFS: {
+            const auto *dfs_data = std::get_if<DfsReplicaData>(&replica.data_);
+            if (!dfs_data) {
+                return tl::unexpected(SerializationError(
+                    ErrorCode::DESERIALIZE_FAIL,
+                    "serialize_msgpack Replica missing DfsReplicaData"));
+            }
+            // Format: [file_path, offset, object_size, aligned_size, shard_idx]
+            packer.pack_array(5);
+            packer.pack(dfs_data->descriptor.file_path);
+            packer.pack(static_cast<uint64_t>(dfs_data->descriptor.offset));
+            packer.pack(
+                static_cast<uint64_t>(dfs_data->descriptor.object_size));
+            packer.pack(
+                static_cast<uint64_t>(dfs_data->descriptor.aligned_size));
+            packer.pack(static_cast<int32_t>(dfs_data->descriptor.shard_idx));
+            break;
+        }
         default:
             // Unsupported replica type
             packer.pack(static_cast<int8_t>(255));
@@ -812,6 +882,26 @@ auto Serializer<Replica>::deserialize(const msgpack::object &obj,
                 client_id, object_size, std::move(transport_endpoint), status);
             break;
         }
+        case static_cast<int8_t>(ReplicaType::DFS): {
+            const auto &payload = array_items[3];
+            if (payload.type != msgpack::type::ARRAY ||
+                payload.via.array.size != 5) {
+                return tl::unexpected(
+                    SerializationError(ErrorCode::DESERIALIZE_FAIL,
+                                       "deserialize_msgpack Replica DFS "
+                                       "payload is not valid array[5]"));
+            }
+            auto *payload_items = payload.via.array.ptr;
+            DistributedFSDescriptor descriptor;
+            descriptor.file_path = payload_items[0].as<std::string>();
+            descriptor.offset = payload_items[1].as<uint64_t>();
+            descriptor.object_size = payload_items[2].as<uint64_t>();
+            descriptor.aligned_size = payload_items[3].as<uint64_t>();
+            descriptor.shard_idx = payload_items[4].as<int32_t>();
+
+            replica = std::make_shared<Replica>(std::move(descriptor), status);
+            break;
+        }
         default:
             return tl::unexpected(SerializationError(
                 ErrorCode::DESERIALIZE_FAIL,
@@ -942,21 +1032,15 @@ Serializer<OffsetBufferAllocator>::serialize(
     packer.pack_array(6);
 
     // Serialize basic properties
-    packer.pack(allocator.segment_name_);
-    packer.pack(static_cast<uint64_t>(allocator.base_));
-    packer.pack(static_cast<uint64_t>(allocator.total_size_));
-    packer.pack(static_cast<uint64_t>(allocator.cur_size_.load()));
-    packer.pack(allocator.transport_endpoint_);
+    packer.pack(allocator.getSegmentName());
+    packer.pack(static_cast<uint64_t>(allocator.base()));
+    packer.pack(static_cast<uint64_t>(allocator.capacity()));
+    packer.pack(static_cast<uint64_t>(allocator.size()));
+    packer.pack(allocator.getTransportEndpoint());
 
     // Serialize offset_allocator
-    auto result =
-        Serializer<mooncake::offset_allocator::OffsetAllocator>::serialize(
-            *allocator.getOffsetAllocator(), packer);
-    if (!result) {
-        return tl::unexpected(result.error());
-    }
-
-    return {};
+    return Serializer<mooncake::offset_allocator::OffsetAllocator>::serialize(
+        *allocator.getOffsetAllocator(), packer);
 }
 
 auto Serializer<OffsetBufferAllocator>::deserialize(const msgpack::object &obj)
@@ -976,42 +1060,15 @@ auto Serializer<OffsetBufferAllocator>::deserialize(const msgpack::object &obj)
     }
 
     try {
-        msgpack::object *array = obj.via.array.ptr;
-
-        // Deserialize basic properties
-        std::string segment_name = array[0].as<std::string>();
-        auto base = static_cast<size_t>(array[1].as<uint64_t>());
-        auto total_size = static_cast<size_t>(array[2].as<uint64_t>());
-        auto cur_size = static_cast<size_t>(array[3].as<uint64_t>());
-        std::string transport_endpoint = array[4].as<std::string>();
-
-        // Deserialize offset_allocator
-        auto offset_allocator_result = Serializer<
-            mooncake::offset_allocator::OffsetAllocator>::deserialize(array[5]);
-        if (!offset_allocator_result) {
-            return tl::unexpected(offset_allocator_result.error());
-        }
-
-        // Create OffsetBufferAllocator instance
-        auto allocator = std::make_shared<OffsetBufferAllocator>(
-            segment_name, base, total_size, transport_endpoint);
-
-        // Set internal member variable values
-        allocator->offset_allocator_ = offset_allocator_result.value();
-        allocator->cur_size_ = cur_size;
-
-        // The snapshot restores cur_size_ directly from persisted data
-        // without going through the live allocate()/adoptImportedBuffer()
-        // paths, so no inc_allocated_mem_size() was paired with it. The
-        // allocator destructor still calls dec_allocated_mem_size(cur_size_)
-        // to undo its contribution to the global metric; without a matching
-        // inc the gauge would go negative and wrap to ~16M TB when formatted
-        // as uint64. Pair it here so the accounting stays symmetric and the
-        // gauge ends at 0 after this (often throwaway) allocator is destroyed.
-        MasterMetricManager::instance().inc_allocated_mem_size(
-            segment_name, static_cast<int64_t>(cur_size));
-
-        return allocator;
+        auto snapshot = ha::AllocatorSnapshotCodec::Decode(obj);
+        if (!snapshot) return tl::unexpected(snapshot.error());
+        auto allocator = OffsetBufferAllocator::Restore(std::move(*snapshot));
+        if (!allocator) {
+            return tl::unexpected(SerializationError(
+                allocator.error(),
+                "deserialize OffsetBufferAllocator rejected its state"));
+        }
+        return std::move(*allocator);
     } catch (const std::exception &e) {
         return tl::unexpected(SerializationError(
             ErrorCode::DESERIALIZE_FAIL,
diff --git a/mooncake-store/src/shm_helper.cpp b/mooncake-store/src/shm_helper.cpp
index fd2bbb8f64..612ced9d51 100644
--- a/mooncake-store/src/shm_helper.cpp
+++ b/mooncake-store/src/shm_helper.cpp
@@ -1,5 +1,6 @@
 #include "shm_helper.h"
 
+#include <cerrno>
 #include <cstdlib>
 #include <cstring>
 #include <sys/mman.h>
@@ -9,8 +10,12 @@
 #include <unistd.h>
 #include <glog/logging.h>
 
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 #include "config.h"
+#include "config/hugepage_config.h"
+#ifdef USE_NOF
+#include "spdk/spdk_wrapper.h"
+#endif
 #if defined(USE_ASCEND_DIRECT)
 #include "ascend_allocator.h"
 #endif
@@ -31,14 +36,76 @@ static int memfd_create_wrapper(const char* name, unsigned int flags) {
 #endif
 }
 
+// Build a clear error message for a failed shared-memory allocation step.
+// When the allocation uses hugepages (forced by MC_STORE_REGISTER_SPDK=1), the
+// usual failure is an insufficient hugepage pool (ENOMEM at ftruncate/mmap);
+// spell out exactly how many hugepages of what size are needed so the operator
+// can configure them. Non-hugepage messages keep the pre-existing text exactly.
+static std::string shm_alloc_error(const char* step, size_t size,
+                                   bool use_hugepage, size_t hp_size, int err) {
+    if (!use_hugepage) {
+        return std::string("Failed to ") + step + ": " + strerror(err);
+    }
+    std::string msg = std::string("Failed to ") + step + " using ";
+    if (hp_size >= SZ_1GB) {
+        msg += std::to_string(hp_size / SZ_1GB) + "GB hugepages";
+    } else {
+        msg += std::to_string(hp_size / (1024 * 1024)) + "MB hugepages";
+    }
+    msg += " (size " + std::to_string(size) + " bytes, need " +
+           std::to_string(size / hp_size) + " hugepages): " + strerror(err);
+    msg +=
+        ". Configure enough hugepages via /proc/sys/vm/nr_hugepages (or "
+        "hugepages-2048kB/hugepages-1048576kB nr_hugepages), or unset "
+        "MC_STORE_REGISTER_SPDK to skip SPDK registration";
+    return msg;
+}
+
 ShmHelper* ShmHelper::getInstance() {
     static ShmHelper instance;
     return &instance;
 }
 
 ShmHelper::ShmHelper() {
-    const char* hp = std::getenv("MC_STORE_USE_HUGEPAGE");
-    use_hugepage_ = (hp != nullptr);
+#ifdef USE_NOF
+    // Force SpdkWrapper to complete construction before ShmHelper does, so that
+    // at process exit ShmHelper is destroyed FIRST: its cleanup() (which calls
+    // SpdkWrapper::UnregisterMemory) runs while the SPDK env is still alive,
+    // before ~SpdkWrapper -> Cleanup() -> spdk_env_fini(). Without this, the
+    // first host-pool allocation constructs SpdkWrapper AFTER ShmHelper, so at
+    // exit SpdkWrapper is destroyed first and cleanup() would call
+    // spdk_mem_unregister after spdk_env_fini() (UB / NULL-deref on SPDK
+    // >= 26.09). Constructing SpdkWrapper here is side-effect free: its ctor is
+    // `= default` and the env is only initialized lazily via InitializeEnv().
+    SpdkWrapper::GetInstance();
+#endif
+    use_hugepage_ = HugepageConfig::IsEnabledFromEnvironment();
+    // Read once at construction (ShmHelper is a singleton). Opt-in only: with
+    // MC_STORE_REGISTER_SPDK=1, ShmHelper mappings are registered with SPDK so
+    // NoF zero-copy transfers can DMA to/from them; otherwise the previous
+    // allocation behavior is preserved exactly.
+    register_spdk_ = is_register_spdk_enabled();
+    if (register_spdk_) {
+#ifdef USE_NOF
+        // spdk_mem_register() requires hugepage-backed memory: SPDK's vtophys
+        // notify checks each 2MB segment's PHYSICAL address for 2MB alignment,
+        // which only hugepage pages satisfy (4KB-backed memory always fails
+        // with -EINVAL, on v23.01.1 and every later version in iova=pa mode).
+        // Virtual-address alignment alone (mmap_shm_2mb_aligned) is not
+        // sufficient, so force hugepages here; if not enough are configured the
+        // allocation below fails with a clear error instead of silently losing
+        // NoF zero-copy. This is an override on top of
+        // HugepageConfig::IsEnabledFromEnvironment() above.
+        use_hugepage_ = true;
+#endif
+        LOG(INFO) << "MC_STORE_REGISTER_SPDK=1: shared memory will be "
+                     "registered with SPDK for NoF zero-copy transfers";
+    }
+}
+
+bool ShmHelper::is_register_spdk_enabled() {
+    const char* rs = std::getenv("MC_STORE_REGISTER_SPDK");
+    return rs != nullptr && std::strcmp(rs, "1") == 0;
 }
 
 ShmHelper::~ShmHelper() { cleanup(); }
@@ -52,6 +119,25 @@ bool ShmHelper::cleanup() {
             shm->fd = -1;
         }
         if (shm->base_addr) {
+#ifdef USE_NOF
+            if (shm->spdk_registered) {
+                if (SpdkWrapper::GetInstance().UnregisterMemory(
+                        shm->base_addr, shm->size) != 0) {
+                    // SPDK still holds a translation for this range: do NOT
+                    // munmap or clear spdk_registered, or a later mmap could
+                    // reuse the VA and NoF would silently DMA to the wrong
+                    // memory. Retain the mapping (released by the OS at process
+                    // exit; cleanup() only runs from ~ShmHelper).
+                    LOG(ERROR) << "Failed to unregister shared memory from "
+                                  "SPDK during cleanup; retaining mapping "
+                                  "(never munmap): "
+                               << shm->base_addr;
+                    ret = false;
+                    continue;
+                }
+                shm->spdk_registered = false;
+            }
+#endif
 #if defined(USE_ASCEND_DIRECT)
             if (globalConfig().ascend_agent_mode &&
                 globalConfig().ascend_use_fabric_mem) {
@@ -89,6 +175,7 @@ void* ShmHelper::allocate(size_t size) {
             shm->fd = -1;
             shm->base_addr = base_addr;
             shm->size = alloc_size;
+            shm->requested_size = alloc_size;
             shm->name = MOONCAKE_SHM_NAME;
             shm->registered = false;
             shms_.push_back(shm);
@@ -98,42 +185,138 @@ void* ShmHelper::allocate(size_t size) {
     }
 #endif
 
+    // Remember the caller-requested size before any alignment padding (hugepage
+    // or 2MB for SPDK registration). shm->size is the padded size; consumers
+    // that must match the original request (e.g. DummyClient::register_buffer)
+    // use requested_size instead of re-deriving the alignment policy.
+    const size_t requested = size;
+
     unsigned int flags = MFD_CLOEXEC;
+    size_t hp_size = 0;  // hugepage size when use_hugepage_ (0 otherwise)
     if (use_hugepage_) {
         bool use_memfd = true;
-        size = align_up(size, get_hugepage_size_from_env(&flags, use_memfd));
+        hp_size = get_hugepage_size_from_env(&flags, use_memfd);
+        if (!(flags & MFD_HUGETLB)) {
+            // get_hugepage_size_from_env() returns 0 and sets no MFD_HUGETLB
+            // flag when MC_STORE_USE_HUGEPAGE is unset -- exactly the case when
+            // MC_STORE_REGISTER_SPDK=1 forces hugepages (see constructor).
+            // Default to 2MB hugepages.
+            flags |= MFD_HUGETLB | MFD_HUGE_2MB;
+            if (hp_size == 0) {
+                hp_size = SZ_2MB;
+            }
+            LOG(INFO) << "Using 2MB hugepages (set MC_STORE_USE_HUGEPAGE and "
+                         "MC_STORE_HUGEPAGE_SIZE=1GB to use 1GB)";
+        }
+        size = align_up(size, hp_size);
         LOG(INFO) << "Using huge pages for shared memory, size: " << size;
     }
+    // When MC_STORE_REGISTER_SPDK=1 forces hugepages, the branch above already
+    // aligned size to the hugepage size, and hugetlb mmap returns a
+    // hugepage-aligned base, so no separate 2MB size padding or aligned base
+    // mapping (mmap_shm_2mb_aligned, common/mmap_aligned.h) is needed on the
+    // sender side.
+    // (The receiver maps the shared fd and aligns its own base in
+    // RealClient::map_shm_internal_with_device.)
 
     int fd = memfd_create_wrapper(MOONCAKE_SHM_NAME, flags);
     if (fd == -1) {
-        std::string extra_msg =
-            use_hugepage_ ? " (Check /proc/sys/vm/nr_hugepages?)" : "";
-        throw std::runtime_error("Failed to create anonymous shared memory" +
-                                 extra_msg + ": " +
-                                 std::string(strerror(errno)));
+        throw std::runtime_error(
+            shm_alloc_error("create anonymous shared memory", size,
+                            use_hugepage_, hp_size, errno));
     }
 
     if (ftruncate(fd, size) == -1) {
+        int err = errno;
         close(fd);
-        throw std::runtime_error("Failed to set shared memory size: " +
-                                 std::string(strerror(errno)));
+        throw std::runtime_error(shm_alloc_error("set shared memory size", size,
+                                                 use_hugepage_, hp_size, err));
     }
 
     void* base_addr = mmap(nullptr, size, PROT_READ | PROT_WRITE,
                            MAP_SHARED | MAP_POPULATE, fd, 0);
     if (base_addr == MAP_FAILED) {
+        int err = errno;
         close(fd);
-        throw std::runtime_error("Failed to map shared memory: " +
-                                 std::string(strerror(errno)));
+        throw std::runtime_error(shm_alloc_error("map shared memory", size,
+                                                 use_hugepage_, hp_size, err));
     }
 
     auto shm = std::make_shared<ShmSegment>();
     shm->fd = fd;
     shm->base_addr = base_addr;
     shm->size = size;
+    shm->requested_size = requested;
     shm->name = MOONCAKE_SHM_NAME;
     shm->registered = false;
+#ifdef USE_NOF
+    // Register the mapping with SPDK so NoF (NVMe-oF) RDMA transfers can DMA
+    // to/from this buffer directly (spdk_rdma_get_translation). Registration
+    // failure is non-fatal: the buffer stays usable for all non-NoF paths.
+    // Enabled only with MC_STORE_REGISTER_SPDK=1 (read once at construction).
+    if (register_spdk_) {
+        if (!SpdkWrapper::IsRegistrableRange(base_addr, size)) {
+            // The hugepage forcing in the constructor makes this unreachable
+            // today (hugetlb mmap returns a hugepage-aligned base and size is
+            // aligned to the hugepage size), but a range SPDK would reject
+            // up-front must not be registered at all: the rejection happens
+            // before any state is marked, so munmap below stays safe.
+            LOG(WARNING) << "Shared memory is not 2MB-aligned; not registering "
+                            "with SPDK: addr="
+                         << base_addr << ", size=" << size
+                         << "; NoF zero-copy transfers to this buffer will be "
+                            "unavailable";
+        } else {
+            const int register_rc =
+                SpdkWrapper::GetInstance().RegisterMemory(base_addr, size);
+            if (register_rc == 0) {
+                shm->spdk_registered = true;
+            } else if (register_rc == -EBUSY) {
+                // The range is already registered, so SPDK marked nothing new
+                // for us. Do NOT roll back: the unregister below would clear
+                // the existing registration (memory.c:358-366 detects it,
+                // 445-466 clears it). Retain the mapping and let teardown
+                // retry.
+                LOG(ERROR) << "Shared memory is already registered with SPDK: "
+                           << base_addr << ", size: " << size
+                           << "; retaining mapping";
+                shm->spdk_registered = true;
+            } else {
+                LOG(WARNING) << "Failed to register shared memory with SPDK: "
+                             << "addr=" << base_addr << ", size=" << size
+                             << "; NoF zero-copy transfers to this buffer will "
+                                "be unavailable";
+                // spdk_mem_register() marks the range in g_mem_reg_map before
+                // running its notify callbacks and does NOT roll back on
+                // failure (SPDK v23.01.1, memory.c:370-384), and in iova=va it
+                // can already have installed the IOMMU mapping when a later
+                // step fails (memory.c:1092-1107). This unregister is the only
+                // chance to undo that, and only a 0 return proves it worked:
+                // -EINVAL is also returned for a half-marked range
+                // (memory.c:426) and, in iova=va, for an incomplete
+                // translation before the IOMMU is unmapped
+                // (memory.c:1216-1224). -EINVAL covers both a failure before
+                // anything was mapped and one after the DMA mapping was
+                // installed, and the codes cannot be told apart, so retaining
+                // a mapping that turns out to have been clean is the accepted
+                // cost of never munmapping a live translation.
+                const int rollback_rc =
+                    SpdkWrapper::GetInstance().UnregisterMemory(base_addr,
+                                                                size);
+                if (rollback_rc != 0) {
+                    LOG(ERROR)
+                        << "Failed to roll back incomplete SPDK registration: "
+                        << base_addr << ", size: " << size
+                        << ", rc: " << rollback_rc
+                        << "; treating the range as registered so free()/"
+                           "cleanup() retry the unregister and quarantine the "
+                           "mapping instead of munmapping";
+                    shm->spdk_registered = true;
+                }
+            }
+        }
+    }
+#endif
     shms_.push_back(shm);
 
     return base_addr;
@@ -145,8 +328,26 @@ int ShmHelper::free(void* addr) {
         if ((*it)->base_addr == addr) {
             if ((*it)->fd != -1) {
                 close((*it)->fd);
+                (*it)->fd = -1;
             }
             if ((*it)->base_addr) {
+#ifdef USE_NOF
+                if ((*it)->spdk_registered) {
+                    if (SpdkWrapper::GetInstance().UnregisterMemory(
+                            (*it)->base_addr, (*it)->size) != 0) {
+                        // SPDK still holds a translation for this range: do NOT
+                        // munmap, clear spdk_registered, or erase the segment.
+                        // Retain the mapping so the VA cannot be reused while
+                        // SPDK's translation is live (a later free() retries).
+                        LOG(ERROR) << "Failed to unregister shared memory from "
+                                      "SPDK during free; retaining mapping "
+                                      "(never munmap): "
+                                   << (*it)->base_addr;
+                        return -1;
+                    }
+                    (*it)->spdk_registered = false;
+                }
+#endif
 #if defined(USE_ASCEND_DIRECT)
                 if (globalConfig().ascend_agent_mode &&
                     globalConfig().ascend_use_fabric_mem) {
@@ -171,10 +372,10 @@ int ShmHelper::free(void* addr) {
 
 std::shared_ptr<ShmHelper::ShmSegment> ShmHelper::get_shm(void* addr) {
     std::lock_guard<std::mutex> lock(shm_mutex_);
+    const uintptr_t address = reinterpret_cast<uintptr_t>(addr);
     for (auto& shm : shms_) {
-        if (addr >= shm->base_addr &&
-            reinterpret_cast<uint8_t*>(addr) <
-                reinterpret_cast<uint8_t*>(shm->base_addr) + shm->size) {
+        const uintptr_t base = reinterpret_cast<uintptr_t>(shm->base_addr);
+        if (address >= base && address - base < shm->size) {
             return shm;
         }
     }
diff --git a/mooncake-store/src/spdk/spdk_wrapper.cpp b/mooncake-store/src/spdk/spdk_wrapper.cpp
index 5042c8f428..5fbecf3e50 100644
--- a/mooncake-store/src/spdk/spdk_wrapper.cpp
+++ b/mooncake-store/src/spdk/spdk_wrapper.cpp
@@ -1,71 +1,48 @@
+#define _GNU_SOURCE
+
 #include <glog/logging.h>
 
 #include <atomic>
-#include <cerrno>
 #include <chrono>
 #include <cstring>
 #include <cstdlib>
+#if defined(__linux__)
+#include <pthread.h>
+#include <sched.h>
+#endif
 #include <thread>
+#include "config/spdk_controller_config.h"
 #include "spdk/spdk_wrapper.h"
 
 namespace mooncake {
 namespace {
 
-bool ParseEnvU64(const char *name, uint64_t *out) {
-    const char *val = std::getenv(name);
-    if (!val || *val == '\0') {
-        return false;
-    }
-
-    errno = 0;
-    char *end = nullptr;
-    unsigned long long parsed = std::strtoull(val, &end, 10);
-    if (errno != 0 || end == val || (end && *end != '\0')) {
-        LOG(WARNING) << "Invalid value for " << name << ": " << val;
-        return false;
-    }
-
-    *out = static_cast<uint64_t>(parsed);
-    return true;
-}
-
-bool ParseEnvBool(const char *name, bool *out) {
-    uint64_t v = 0;
-    if (!ParseEnvU64(name, &v)) {
-        return false;
-    }
-    *out = (v != 0);
-    return true;
-}
-
 void ApplyCtrlrOptsFromEnv(struct spdk_nvme_ctrlr_opts *opts) {
-    uint64_t v = 0;
-    bool bv = false;
     opts->keep_alive_timeout_ms = 0;
-
-    if (ParseEnvU64("MC_NVME_NUM_IO_QUEUES", &v)) {
-        opts->num_io_queues = static_cast<uint32_t>(v);
+    const auto config = SpdkControllerConfig::FromEnvironment();
+    if (config.num_io_queues.has_value()) {
+        opts->num_io_queues = *config.num_io_queues;
     }
-    if (ParseEnvU64("MC_NVME_IO_QUEUE_SIZE", &v)) {
-        opts->io_queue_size = static_cast<uint32_t>(v);
+    if (config.io_queue_size.has_value()) {
+        opts->io_queue_size = *config.io_queue_size;
     }
-    if (ParseEnvU64("MC_NVME_IO_QUEUE_REQUESTS", &v)) {
-        opts->io_queue_requests = static_cast<uint32_t>(v);
+    if (config.io_queue_requests.has_value()) {
+        opts->io_queue_requests = *config.io_queue_requests;
     }
-    if (ParseEnvU64("MC_NVME_TRANSPORT_ACK_TIMEOUT", &v)) {
-        opts->transport_ack_timeout = static_cast<uint8_t>(v);
+    if (config.transport_ack_timeout.has_value()) {
+        opts->transport_ack_timeout = *config.transport_ack_timeout;
     }
-    if (ParseEnvU64("MC_NVME_ADMIN_QUEUE_SIZE", &v)) {
-        opts->admin_queue_size = static_cast<uint16_t>(v);
+    if (config.admin_queue_size.has_value()) {
+        opts->admin_queue_size = *config.admin_queue_size;
     }
-    if (ParseEnvU64("MC_NVME_FABRICS_CONNECT_TIMEOUT_US", &v)) {
-        opts->fabrics_connect_timeout_us = v;
+    if (config.fabrics_connect_timeout_us.has_value()) {
+        opts->fabrics_connect_timeout_us = *config.fabrics_connect_timeout_us;
     }
-    if (ParseEnvBool("MC_NVME_HEADER_DIGEST", &bv)) {
-        opts->header_digest = bv;
+    if (config.header_digest.has_value()) {
+        opts->header_digest = *config.header_digest;
     }
-    if (ParseEnvBool("MC_NVME_DATA_DIGEST", &bv)) {
-        opts->data_digest = bv;
+    if (config.data_digest.has_value()) {
+        opts->data_digest = *config.data_digest;
     }
     LOG(INFO) << "NVMe ctrlr opts: num_io_queues=" << opts->num_io_queues
               << ", io_queue_size=" << opts->io_queue_size
@@ -118,11 +95,41 @@ bool SpdkWrapper::InitializeEnv() {
         return true;
     }
 
+    // rte_eal_init registers the calling thread as DPDK's main lcore and may
+    // restrict its CPU affinity to the configured EAL cores (default
+    // core_mask "0x1"). Linux threads inherit the creator's affinity mask, so
+    // without restoring it, every thread the host app spawns after Mooncake's
+    // setup would be pinned to a single core and KV read/write throughput
+    // would drop sharply. Save the original affinity and restore it around
+    // spdk_env_init to stop that propagation. DPDK's main-lcore identity is a
+    // thread registration, not the kernel affinity, so later SPDK calls are
+    // unaffected by the restore. pthread affinity APIs are glibc-specific, so
+    // this is gated to Linux; other platforms see the previous behavior.
+#if defined(__linux__)
+    cpu_set_t orig_cpuset;
+    CPU_ZERO(&orig_cpuset);
+    bool affinity_saved =
+        pthread_getaffinity_np(pthread_self(), sizeof(cpu_set_t),
+                               &orig_cpuset) == 0;
+#endif
+
     struct spdk_env_opts opts;
     spdk_env_opts_init(&opts);
     opts.name = "mooncake";
 
     int rc = spdk_env_init(&opts);
+
+    // Best-effort restore of the caller's original affinity.
+#if defined(__linux__)
+    if (affinity_saved) {
+        if (pthread_setaffinity_np(pthread_self(), sizeof(cpu_set_t),
+                                   &orig_cpuset) != 0) {
+            LOG(WARNING) << "Failed to restore calling thread CPU affinity "
+                            "after SPDK env init";
+        }
+    }
+#endif
+
     if (rc != 0) {
         fprintf(stderr, "SPDK init failed: %d\n", rc);
         return false;
@@ -184,6 +191,64 @@ void SpdkWrapper::Free(void *ptr) {
     }
 }
 
+int SpdkWrapper::RegisterMemory(void *addr, size_t size) {
+    if (!addr || size == 0) {
+        return -1;
+    }
+    if (!InitializeEnv()) {
+        LOG(ERROR) << "SPDK env init failed, cannot register memory";
+        return -1;
+    }
+    int rc = spdk_mem_register(addr, size);
+    if (rc != 0) {
+        LOG(ERROR) << "spdk_mem_register failed (addr=" << addr
+                   << ", size=" << size << "): " << strerror(-rc);
+    }
+    return rc;
+}
+
+bool SpdkWrapper::IsRegistrableRange(void *addr, size_t size) {
+    // spdk_mem_register() rejects a range up front (memory.c:339-348) when the
+    // address is outside the 256TB window it can represent (MASK_256TB) or when
+    // addr/size is not 2MB-aligned. Those rejections happen before anything is
+    // marked, so a caller that skips the registration for such a range can
+    // still munmap it; every other failure may have left state behind.
+    constexpr uintptr_t kSpdkAddressMask = (1ULL << 48) - 1;  // MASK_256TB
+    constexpr uintptr_t kSpdk2MbAlignment = 2ULL * 1024 * 1024;
+    const uintptr_t vaddr = reinterpret_cast<uintptr_t>(addr);
+    return addr != nullptr && size != 0 && (vaddr & ~kSpdkAddressMask) == 0 &&
+           (vaddr % kSpdk2MbAlignment) == 0 && (size % kSpdk2MbAlignment) == 0;
+}
+
+int SpdkWrapper::UnregisterMemory(void *addr, size_t size) {
+    if (!addr || size == 0) {
+        return -1;
+    }
+    // SPDK env may not be initialized (registration is opt-in) or may already
+    // have been finalized by Cleanup() -> spdk_env_fini(). In both cases there
+    // is no registered memory to release; calling spdk_mem_unregister would
+    // walk a torn-down or never-created global mem_map. (With ShmHelper
+    // destroyed before SpdkWrapper, the `initialized` atomic is still alive
+    // here.)
+    if (!initialized.load(std::memory_order_acquire)) {
+        return 0;
+    }
+    int rc = spdk_mem_unregister(addr, size);
+    if (rc != 0) {
+        // Every code is reported, -EINVAL included: it does NOT mean "the range
+        // was never registered" (spdk_mem_unregister returns it at memory.c:426
+        // when a page of the range is not REG_MAP_REGISTERED -- exactly what
+        // spdk_mem_register leaves behind when it fails after marking the range
+        // but before its notify callbacks run, memory.c:370-384). In iova=va it
+        // is also returned by the notify callback when the translation does not
+        // cover the range, *before* the IOMMU unmap at memory.c:1224, so a live
+        // DMA mapping can remain. Callers must keep the mapping unless rc == 0.
+        LOG(ERROR) << "spdk_mem_unregister failed (addr=" << addr
+                   << ", size=" << size << "): " << strerror(-rc);
+    }
+    return rc;
+}
+
 void SpdkWrapper::ProbeReadComplete(void *ctx,
                                     const struct spdk_nvme_cpl *cpl) {
     auto *probe_ctx = reinterpret_cast<ProbeRequestContext *>(ctx);
@@ -303,6 +368,18 @@ int SpdkWrapper::ConnectController(const struct spdk_nvme_transport_id *trid,
 }
 
 nof_seg_handle *SpdkWrapper::OpenNofSegment(const std::string &tr_str) {
+    // ConnectController -> spdk_nvme_probe() uses env-provided sockets and
+    // memory, so the SPDK env must be up. Do not rely on an earlier
+    // RegisterMemory() to have initialized it: callers now skip the
+    // registration for ranges SPDK would reject (IsRegistrableRange), and that
+    // must not decide whether NoF can be used at all. Every other entry point
+    // (Alloc, RegisterMemory, ProbeNofSegment) already initializes the env
+    // itself; this makes OpenNofSegment self-sufficient too.
+    if (!InitializeEnv()) {
+        LOG(ERROR) << "SPDK env init failed, cannot open NoF segment";
+        return nullptr;
+    }
+
     tr_info tr;
     int ret = ParseTransPortStr(tr_str, &tr);
     if (ret != 0) {
diff --git a/mooncake-store/src/ssd_register_client.cpp b/mooncake-store/src/ssd_register_client.cpp
index 39cc9f393e..8bcd4bde4c 100644
--- a/mooncake-store/src/ssd_register_client.cpp
+++ b/mooncake-store/src/ssd_register_client.cpp
@@ -1,7 +1,6 @@
 #include "ssd_register_client.h"
-#include <algorithm>
-#include <cctype>
-#include <cstdlib>
+
+#include "config/nof_register_config.h"
 
 namespace mooncake {
 
@@ -25,21 +24,12 @@ int NoFRegisterClient::set_register(const std::string &nqn, size_t nsid,
         return OPERATION_FAILED;
     }
 
-    const char *trtype_env = std::getenv("MC_NOF_TRTYPE");
-    std::string trtype = trtype_env ? trtype_env : "RDMA";
-    std::transform(
-        trtype.begin(), trtype.end(), trtype.begin(),
-        [](unsigned char c) { return static_cast<char>(std::toupper(c)); });
-    if (trtype != "RDMA" && trtype != "TCP") {
-        LOG(WARNING) << "Invalid MC_NOF_TRTYPE=" << trtype
-                     << ", fallback to RDMA";
-        trtype = "RDMA";
-    }
+    const auto config = NoFRegisterConfig::FromEnvironment();
 
-    std::string te_endpoint = "traddr:" + traddr +
-                              " trsvcid:" + std::to_string(trsvcid) +
-                              " subnqn:" + nqn + " trtype:" + trtype +
-                              " adrfam:IPv4 ns:" + std::to_string(nsid);
+    std::string te_endpoint =
+        "traddr:" + traddr + " trsvcid:" + std::to_string(trsvcid) +
+        " subnqn:" + nqn + " trtype:" + config.transport_type +
+        " adrfam:IPv4 ns:" + std::to_string(nsid);
 
     NoFSegment segment;
     segment.base = base;
@@ -70,22 +60,13 @@ int NoFRegisterClient::set_unregister_by_endpoint(
         return OPERATION_FAILED;
     }
 
-    const char *trtype_env = std::getenv("MC_NOF_TRTYPE");
-    std::string trtype = trtype_env ? trtype_env : "RDMA";
-    std::transform(
-        trtype.begin(), trtype.end(), trtype.begin(),
-        [](unsigned char c) { return static_cast<char>(std::toupper(c)); });
-    if (trtype != "RDMA" && trtype != "TCP") {
-        LOG(WARNING) << "Invalid MC_NOF_TRTYPE=" << trtype
-                     << ", fallback to RDMA";
-        trtype = "RDMA";
-    }
+    const auto config = NoFRegisterConfig::FromEnvironment();
 
     // Build the te_endpoint string to match registered segments
-    std::string te_endpoint = "traddr:" + traddr +
-                              " trsvcid:" + std::to_string(trsvcid) +
-                              " subnqn:" + nqn + " trtype:" + trtype +
-                              " adrfam:IPv4 ns:" + std::to_string(nsid);
+    std::string te_endpoint =
+        "traddr:" + traddr + " trsvcid:" + std::to_string(trsvcid) +
+        " subnqn:" + nqn + " trtype:" + config.transport_type +
+        " adrfam:IPv4 ns:" + std::to_string(nsid);
 
     LOG(INFO) << "Built te_endpoint: " << te_endpoint;
 
diff --git a/mooncake-store/src/storage/distributed/dfs_global_allocator.cpp b/mooncake-store/src/storage/distributed/dfs_global_allocator.cpp
new file mode 100644
index 0000000000..471b90820f
--- /dev/null
+++ b/mooncake-store/src/storage/distributed/dfs_global_allocator.cpp
@@ -0,0 +1,693 @@
+#include "storage/distributed/dfs_global_allocator.h"
+
+#include <algorithm>
+#include <charconv>
+#include <exception>
+#include <filesystem>
+#include <iomanip>
+#include <limits>
+#include <map>
+#include <sstream>
+#include <string_view>
+#include <utility>
+
+#include "config/distributed_storage_config.h"
+#include "storage/distributed/fs_adapter.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#ifdef USE_3FS
+#include "storage/distributed/hf3fs_adapter.h"
+#endif
+
+namespace mooncake {
+
+DfsGlobalAllocator::PendingEviction::~PendingEviction() {
+    if (owner_ != nullptr) {
+        owner_->RestorePreparedEviction(std::move(*this));
+    }
+}
+
+DfsGlobalAllocator::PendingEviction::PendingEviction(
+    PendingEviction&& other) noexcept
+    : owner_(std::exchange(other.owner_, nullptr)),
+      candidates_(std::move(other.candidates_)),
+      prepared_(std::move(other.prepared_)) {}
+
+DfsGlobalAllocator::~DfsGlobalAllocator() {
+    if (fs_adapter_) fs_adapter_->Shutdown();
+}
+
+tl::expected<void, ErrorCode> DfsGlobalAllocator::Init(
+    const DistributedStorageConfig& config) {
+    std::lock_guard expansion_lock(expansion_mutex_);
+    if (initialized_.load(std::memory_order_acquire)) return {};
+    if (!config.ValidateForAllocator() ||
+        config.shard_capacity >
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max()) ||
+        config.shard_capacity > std::numeric_limits<uint64_t>::max() /
+                                    static_cast<uint64_t>(config.shard_count)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    mount_path_ = config.fsdir;
+    shard_capacity_ = config.shard_capacity;
+    alignment_ = config.alignment;
+    eviction_enabled_ = config.eviction_enabled;
+    eviction_high_watermark_ = config.eviction_high_watermark;
+    eviction_low_watermark_ = config.eviction_low_watermark;
+    deferred_free_duration_ = config.deferred_free_duration;
+    eviction_check_interval_ = config.eviction_check_interval;
+
+    std::error_code ec;
+    std::filesystem::create_directories(mount_path_, ec);
+    if (ec) {
+        LOG(ERROR) << "Failed to create DFS mount path " << mount_path_ << ": "
+                   << ec.message();
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+
+    if (fs_adapter_) fs_adapter_->Shutdown();
+    if (config.fs_adapter_type == "posix") {
+        fs_adapter_ = std::make_unique<PosixFsAdapter>();
+    } else if (config.fs_adapter_type == "hf3fs") {
+#ifdef USE_3FS
+        fs_adapter_ = std::make_unique<Hf3fsAdapter>();
+#else
+        LOG(ERROR) << "The hf3fs DFS adapter requires Mooncake to be built "
+                      "with the USE_3FS compile-time option "
+                      "(-DUSE_3FS=ON)";
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+#endif
+    }
+
+    auto adapter_init = fs_adapter_->Init(mount_path_);
+    if (!adapter_init) {
+        LOG(ERROR) << "Failed to initialize DFS fs adapter "
+                   << config.fs_adapter_type
+                   << " for mount_path=" << mount_path_
+                   << ", error=" << adapter_init.error();
+        return tl::make_unexpected(adapter_init.error());
+    }
+
+    // Recover the capacity layout only. Allocation handles and key metadata
+    // remain empty; snapshot/oplog recovery is deliberately still unsupported.
+    // Keep the exact paths of older layouts whose padding depended on count.
+    auto files = fs_adapter_->ListFiles(mount_path_);
+    if (!files) return tl::make_unexpected(files.error());
+    std::map<int, std::string> existing_paths;
+    constexpr std::string_view prefix = "dfs_shard_";
+    constexpr std::string_view suffix = ".data";
+    for (const auto& name : *files) {
+        std::string_view view(name);
+        if (!view.starts_with(prefix) || !view.ends_with(suffix)) continue;
+        const auto digits = view.substr(
+            prefix.size(), view.size() - prefix.size() - suffix.size());
+        int index = -1;
+        const auto [end, error] = std::from_chars(
+            digits.data(), digits.data() + digits.size(), index);
+        if (digits.size() < 2 || digits.front() < '0' || digits.front() > '9' ||
+            error != std::errc{} || end != digits.data() + digits.size() ||
+            index < 0 || index == std::numeric_limits<int>::max() ||
+            !existing_paths.emplace(index, mount_path_ + "/" + name).second) {
+            LOG(ERROR) << "Invalid or ambiguous DFS shard filename " << name;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+
+    int discovered_count = 0;
+    for (const auto& [index, path] : existing_paths) {
+        if (index != discovered_count++) {
+            LOG(ERROR) << "DFS shard layout is not contiguous at " << path;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+    const int target_count = std::max(config.shard_count, discovered_count);
+    if (shard_capacity_ > std::numeric_limits<uint64_t>::max() /
+                              static_cast<uint64_t>(target_count)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    std::vector<std::string> created_files;
+    try {
+        auto ready = std::make_shared<ShardList>();
+        for (int i = 0; i < target_count; ++i) {
+            const auto existing = existing_paths.find(i);
+            const std::string path = existing == existing_paths.end()
+                                         ? mount_path_ + "/dfs_shard_" +
+                                               FormatShardIdx(i, 0) + ".data"
+                                         : existing->second;
+            auto shard = CreateShard(path, created_files);
+            if (!shard) {
+                CleanupCreatedFiles(created_files);
+                return tl::make_unexpected(shard.error());
+            }
+            ready->push_back(std::move(*shard));
+        }
+        std::atomic_store_explicit(
+            &shards_, std::shared_ptr<const ShardList>(std::move(ready)),
+            std::memory_order_release);
+    } catch (const std::exception& error) {
+        CleanupCreatedFiles(created_files);
+        LOG(ERROR) << "Failed to initialize DFS shards: " << error.what();
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    initialized_.store(true, std::memory_order_release);
+    return {};
+}
+
+int DfsGlobalAllocator::GetShardCount() const {
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    return shards ? static_cast<int>(shards->size()) : 0;
+}
+
+tl::expected<int, ErrorCode> DfsGlobalAllocator::ExpandShards(
+    int target_count) {
+    std::lock_guard expansion_lock(expansion_mutex_);
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    const auto current =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (target_count <= 0 || target_count < static_cast<int>(current->size()) ||
+        shard_capacity_ > std::numeric_limits<uint64_t>::max() /
+                              static_cast<uint64_t>(target_count)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (target_count == static_cast<int>(current->size())) return target_count;
+
+    std::vector<std::string> created_files;
+    try {
+        auto ready = std::make_shared<ShardList>(*current);
+        for (int i = static_cast<int>(current->size()); i < target_count; ++i) {
+            const std::string path =
+                mount_path_ + "/dfs_shard_" + FormatShardIdx(i, 0) + ".data";
+            auto shard = CreateShard(path, created_files);
+            if (!shard) {
+                // Files from before this operation are never truncated or
+                // removed. Failed cleanup can leave a ready file for retry,
+                // but no staged shard is allocatable before publication.
+                CleanupCreatedFiles(created_files);
+                return tl::make_unexpected(shard.error());
+            }
+            ready->push_back(std::move(*shard));
+        }
+        std::atomic_store_explicit(
+            &shards_, std::shared_ptr<const ShardList>(std::move(ready)),
+            std::memory_order_release);
+    } catch (const std::exception& error) {
+        CleanupCreatedFiles(created_files);
+        LOG(ERROR) << "Failed to expand DFS shards: " << error.what();
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return target_count;
+}
+
+tl::expected<std::shared_ptr<DfsGlobalAllocator::ShardState>, ErrorCode>
+DfsGlobalAllocator::CreateShard(const std::string& path,
+                                std::vector<std::string>& created_files) {
+    auto exists = fs_adapter_->FileExists(path);
+    if (!exists) return tl::make_unexpected(exists.error());
+    if (*exists) {
+        std::error_code ec;
+        if (!std::filesystem::is_regular_file(path, ec)) {
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+        auto size = fs_adapter_->GetFileSize(path);
+        if (!size) return tl::make_unexpected(size.error());
+        if (*size != shard_capacity_) {
+            LOG(ERROR) << "DFS shard capacity mismatch for " << path
+                       << ": expected=" << shard_capacity_
+                       << ", actual=" << *size;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    } else {
+        created_files.push_back(path);
+        auto prealloc = fs_adapter_->PreallocateFile(path, shard_capacity_);
+        if (!prealloc) return tl::make_unexpected(prealloc.error());
+    }
+
+    auto shard = std::make_shared<ShardState>();
+    shard->path = path;
+    shard->capacity = shard_capacity_;
+    uint32_t init_cap = static_cast<uint32_t>(std::max<uint64_t>(
+        1, std::min<uint64_t>(shard_capacity_ / 4096, 64ULL * 1024)));
+    uint32_t max_cap = static_cast<uint32_t>(std::max<uint64_t>(
+        init_cap,
+        std::min<uint64_t>(shard_capacity_ / 1024, 64ULL * 1024 * 1024)));
+    shard->allocator =
+        OffsetAllocator::create(0, shard_capacity_, init_cap, max_cap);
+    if (!shard->allocator) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    return shard;
+}
+
+void DfsGlobalAllocator::CleanupCreatedFiles(
+    const std::vector<std::string>& created_files) {
+    for (const auto& path : created_files) {
+        auto result = fs_adapter_->DeleteFile(path);
+        if (!result && result.error() != ErrorCode::FILE_NOT_FOUND) {
+            LOG(WARNING) << "Failed to clean up unpublished DFS shard " << path
+                         << ": " << result.error();
+        }
+    }
+}
+
+tl::expected<DistributedFSDescriptor, ErrorCode> DfsGlobalAllocator::Allocate(
+    const std::string& key, uint64_t size) {
+    if (!initialized_.load(std::memory_order_acquire)) {
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    if (key.empty() || size == 0 ||
+        size > std::numeric_limits<uint64_t>::max() - (alignment_ - 1)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const uint64_t aligned_size = AlignSize(size);
+    if (aligned_size >
+        std::numeric_limits<uint64_t>::max() - (alignment_ - 1)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const uint64_t allocation_size = aligned_size + alignment_ - 1;
+    if (allocation_size > shard_capacity_) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    auto key_lock = LockKey(key);
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    const size_t preferred = std::hash<std::string>{}(key) % shards->size();
+    // A full preferred shard must not hide capacity in newly appended shards.
+    // Existing descriptors remain authoritative even when the modulo changes.
+    for (size_t attempt = 0; attempt < shards->size(); ++attempt) {
+        const size_t shard_idx = (preferred + attempt) % shards->size();
+        auto& shard = *(*shards)[shard_idx];
+        std::unique_lock handle_lock(shard.handle_mutex);
+        CleanupExpiredPendingFrees(shard, std::chrono::steady_clock::now());
+        const uint64_t reserved_bytes =
+            shard.allocator->normalizedAllocationSize(allocation_size);
+        auto handle = shard.allocator->allocate(allocation_size);
+        if (!handle) continue;
+
+        const uint64_t alloc_offset = AlignSize(handle->address());
+        auto alloc_handle =
+            std::make_shared<OffsetAllocationHandle>(std::move(*handle));
+        shard.offset_to_handle[alloc_offset] = {key, std::move(alloc_handle),
+                                                reserved_bytes};
+        return DistributedFSDescriptor{shard.path, alloc_offset, size,
+                                       aligned_size,
+                                       static_cast<int>(shard_idx)};
+    }
+    return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+}
+
+std::vector<BatchAllocateResult> DfsGlobalAllocator::BatchAllocate(
+    const std::vector<BatchAllocateRequest>& requests) {
+    std::vector<BatchAllocateResult> results;
+    results.reserve(requests.size());
+    for (const auto& request : requests) {
+        results.push_back(
+            BatchAllocateResult{request.key, {}, false, ErrorCode::OK});
+    }
+
+    for (size_t i = 0; i < requests.size(); ++i) {
+        auto descriptor = Allocate(requests[i].key, requests[i].size);
+        if (descriptor) {
+            results[i].descriptor = std::move(*descriptor);
+            results[i].success = true;
+            continue;
+        }
+
+        const ErrorCode error = descriptor.error();
+        for (size_t j = i; j > 0; --j) {
+            auto& allocated = results[j - 1];
+            if (allocated.success) {
+                Free(allocated.key, allocated.descriptor);
+            }
+        }
+        for (auto& result : results) {
+            result.descriptor = {};
+            result.success = false;
+            result.error = error;
+        }
+        return results;
+    }
+    return results;
+}
+
+void DfsGlobalAllocator::Free(const std::string& key,
+                              const DistributedFSDescriptor& descriptor) {
+    Free(descriptor.offset, descriptor.aligned_size, descriptor.shard_idx, key);
+}
+
+void DfsGlobalAllocator::UpdateAccess(
+    const std::string& key, const DistributedFSDescriptor& descriptor) {
+    UpdateAccess(key, descriptor.shard_idx, descriptor.offset);
+}
+
+uint64_t DfsGlobalAllocator::GetUsedBytes() const {
+    uint64_t used = 0;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (!shards) return 0;
+    for (const auto& shard : *shards) {
+        if (!shard) continue;
+        std::shared_lock lock(shard->handle_mutex);
+        const auto report = shard->allocator->storageReport();
+        const uint64_t free_space =
+            std::min<uint64_t>(report.totalFreeSpace, shard->capacity);
+        used += shard->capacity - free_space;
+    }
+    return used;
+}
+
+uint64_t DfsGlobalAllocator::GetTotalCapacity() const {
+    uint64_t total = 0;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (!shards) return 0;
+    for (const auto& shard : *shards) {
+        if (shard) total += shard->capacity;
+    }
+    return total;
+}
+
+void DfsGlobalAllocator::Free(uint64_t offset, uint64_t /*aligned_size*/,
+                              int shard_idx, const std::string& key) {
+    if (!initialized_.load(std::memory_order_acquire)) return;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (shard_idx < 0 || shard_idx >= static_cast<int>(shards->size())) return;
+
+    auto& shard = *(*shards)[shard_idx];
+    std::lock_guard lru_lock(shard.lru_mutex);
+    std::lock_guard handle_lock(shard.handle_mutex);
+
+    auto lru_it = shard.lru_index.find(key);
+    if (lru_it != shard.lru_index.end() && lru_it->second->second == offset) {
+        shard.lru_list.erase(lru_it->second);
+        shard.lru_index.erase(lru_it);
+    }
+
+    auto it = shard.offset_to_handle.find(offset);
+    if (it == shard.offset_to_handle.end()) return;
+    if (it->second.key != key) return;
+
+    QueuePendingFree(
+        shard, it->second.handle, it->second.bytes,
+        std::chrono::steady_clock::now() + deferred_free_duration_);
+    shard.offset_to_handle.erase(it);
+}
+
+void DfsGlobalAllocator::UpdateAccess(const std::string& key, int shard_idx,
+                                      uint64_t offset) {
+    if (!initialized_.load(std::memory_order_acquire)) return;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (shard_idx < 0 || shard_idx >= static_cast<int>(shards->size())) return;
+
+    auto& shard = *(*shards)[shard_idx];
+    std::lock_guard lru_lock(shard.lru_mutex);
+    {
+        std::shared_lock handle_lock(shard.handle_mutex);
+        auto handle_it = shard.offset_to_handle.find(offset);
+        if (handle_it == shard.offset_to_handle.end() ||
+            handle_it->second.key != key ||
+            handle_it->second.eviction_prepared) {
+            return;
+        }
+    }
+    auto lru_it = shard.lru_index.find(key);
+    if (lru_it != shard.lru_index.end()) {
+        lru_it->second->second = offset;
+        shard.lru_list.splice(shard.lru_list.begin(), shard.lru_list,
+                              lru_it->second);
+    } else {
+        shard.lru_list.push_front({key, offset});
+        shard.lru_index[key] = shard.lru_list.begin();
+    }
+}
+
+DfsGlobalAllocator::PendingEviction DfsGlobalAllocator::PrepareEviction() {
+    PendingEviction pending(this);
+    if (!initialized_.load(std::memory_order_acquire)) return pending;
+
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    for (size_t i = 0; i < shards->size(); ++i) {
+        auto& shard = *(*shards)[i];
+        {
+            std::unique_lock handle_lock(shard.handle_mutex);
+            CleanupExpiredPendingFrees(shard, std::chrono::steady_clock::now());
+        }
+        PrepareEvictionFromShard(shard, static_cast<int>(i), pending);
+    }
+    return pending;
+}
+
+void DfsGlobalAllocator::CommitPreparedEviction(PendingEviction&& pending) {
+    if (pending.owner_ != this) return;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+
+    const auto free_at =
+        std::chrono::steady_clock::now() + deferred_free_duration_;
+    for (const auto& prepared : pending.prepared_) {
+        auto& shard = *(*shards)[prepared.candidate.shard_idx];
+        std::lock_guard handle_lock(shard.handle_mutex);
+        auto it = shard.offset_to_handle.find(prepared.candidate.offset);
+        if (it == shard.offset_to_handle.end() ||
+            it->second.key != prepared.candidate.key ||
+            it->second.handle != prepared.handle) {
+            // A concurrent metadata removal may already have called Free().
+            continue;
+        }
+
+        QueuePendingFree(shard, prepared.handle, prepared.bytes, free_at);
+        shard.offset_to_handle.erase(it);
+    }
+
+    pending.prepared_.clear();
+    pending.candidates_.clear();
+    pending.owner_ = nullptr;
+}
+
+void DfsGlobalAllocator::RestorePreparedEviction(PendingEviction&& pending) {
+    if (pending.owner_ != this) return;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+
+    // Candidates were removed oldest-first. Restore in reverse order so the
+    // original relative LRU order is preserved.
+    for (auto prepared_it = pending.prepared_.rbegin();
+         prepared_it != pending.prepared_.rend(); ++prepared_it) {
+        const auto& prepared = *prepared_it;
+        auto& shard = *(*shards)[prepared.candidate.shard_idx];
+        std::lock_guard lru_lock(shard.lru_mutex);
+        std::lock_guard handle_lock(shard.handle_mutex);
+
+        auto handle_it = shard.offset_to_handle.find(prepared.candidate.offset);
+        if (handle_it == shard.offset_to_handle.end() ||
+            handle_it->second.key != prepared.candidate.key ||
+            handle_it->second.handle != prepared.handle) {
+            // Free() or a replacement already retired this allocation.
+            continue;
+        }
+
+        handle_it->second.eviction_prepared = false;
+        if (shard.lru_index.find(prepared.candidate.key) ==
+            shard.lru_index.end()) {
+            shard.lru_list.push_back(
+                {prepared.candidate.key, prepared.candidate.offset});
+            shard.lru_index[prepared.candidate.key] =
+                std::prev(shard.lru_list.end());
+        }
+    }
+
+    pending.prepared_.clear();
+    pending.candidates_.clear();
+    pending.owner_ = nullptr;
+}
+
+void DfsGlobalAllocator::ResolvePreparedEviction(
+    PendingEviction&& pending, const std::vector<bool>& accepted) {
+    if (pending.owner_ != this) return;
+    const auto shards =
+        std::atomic_load_explicit(&shards_, std::memory_order_acquire);
+    if (accepted.size() != pending.prepared_.size()) {
+        LOG(ERROR) << "DFS eviction decision count " << accepted.size()
+                   << " does not match prepared candidate count "
+                   << pending.prepared_.size();
+        RestorePreparedEviction(std::move(pending));
+        return;
+    }
+
+    const auto free_at =
+        std::chrono::steady_clock::now() + deferred_free_duration_;
+    for (size_t i = 0; i < pending.prepared_.size(); ++i) {
+        if (!accepted[i]) continue;
+
+        const auto& prepared = pending.prepared_[i];
+        auto& shard = *(*shards)[prepared.candidate.shard_idx];
+        std::lock_guard handle_lock(shard.handle_mutex);
+        auto handle_it = shard.offset_to_handle.find(prepared.candidate.offset);
+        if (handle_it == shard.offset_to_handle.end() ||
+            handle_it->second.key != prepared.candidate.key ||
+            handle_it->second.handle != prepared.handle) {
+            // Free() or a replacement already retired this allocation.
+            continue;
+        }
+
+        QueuePendingFree(shard, prepared.handle, prepared.bytes, free_at);
+        shard.offset_to_handle.erase(handle_it);
+    }
+
+    // Candidates were removed oldest-first. Restore rejected entries in
+    // reverse order so their relative LRU order is preserved.
+    for (size_t i = pending.prepared_.size(); i > 0; --i) {
+        if (accepted[i - 1]) continue;
+
+        const auto& prepared = pending.prepared_[i - 1];
+        auto& shard = *(*shards)[prepared.candidate.shard_idx];
+        std::lock_guard lru_lock(shard.lru_mutex);
+        std::lock_guard handle_lock(shard.handle_mutex);
+
+        auto handle_it = shard.offset_to_handle.find(prepared.candidate.offset);
+        if (handle_it == shard.offset_to_handle.end() ||
+            handle_it->second.key != prepared.candidate.key ||
+            handle_it->second.handle != prepared.handle) {
+            continue;
+        }
+
+        handle_it->second.eviction_prepared = false;
+        if (shard.lru_index.find(prepared.candidate.key) ==
+            shard.lru_index.end()) {
+            shard.lru_list.push_back(
+                {prepared.candidate.key, prepared.candidate.offset});
+            shard.lru_index[prepared.candidate.key] =
+                std::prev(shard.lru_list.end());
+        }
+    }
+
+    pending.prepared_.clear();
+    pending.candidates_.clear();
+    pending.owner_ = nullptr;
+}
+
+std::string DfsGlobalAllocator::FormatShardIdx(int idx, int /*shard_count*/) {
+    // Retain the second argument for source compatibility. New filenames are
+    // independent of total count; discovered legacy filenames stay unchanged.
+    constexpr int width = 2;
+    std::ostringstream oss;
+    oss << std::setw(width) << std::setfill('0') << idx;
+    return oss.str();
+}
+
+void DfsGlobalAllocator::QueuePendingFree(
+    ShardState& shard, const std::shared_ptr<OffsetAllocationHandle>& handle,
+    uint64_t bytes, std::chrono::steady_clock::time_point when) {
+    if (!handle) return;
+    std::lock_guard pending_lock(shard.pending_mutex);
+    if (bytes == 0) bytes = handle->size();
+    shard.pending_free.push_back({handle, bytes, when});
+    shard.pending_free_bytes += bytes;
+}
+
+void DfsGlobalAllocator::CleanupExpiredPendingFrees(
+    ShardState& shard, std::chrono::steady_clock::time_point now) {
+    std::lock_guard pending_lock(shard.pending_mutex);
+    while (!shard.pending_free.empty() &&
+           shard.pending_free.front().when <= now) {
+        const uint64_t bytes = shard.pending_free.front().bytes;
+        shard.pending_free.pop_front();
+        if (bytes > shard.pending_free_bytes) {
+            shard.pending_free_bytes = 0;
+        } else {
+            shard.pending_free_bytes -= bytes;
+        }
+    }
+}
+
+double DfsGlobalAllocator::EffectiveUsage(ShardState& shard) {
+    uint64_t physical_free = 0;
+    {
+        std::shared_lock lock(shard.handle_mutex);
+        auto report = shard.allocator->storageReport();
+        physical_free = report.totalFreeSpace;
+    }
+
+    uint64_t pending_free_bytes = 0;
+    {
+        std::lock_guard pending_lock(shard.pending_mutex);
+        pending_free_bytes = shard.pending_free_bytes;
+    }
+
+    const uint64_t capped_physical_free =
+        std::min<uint64_t>(physical_free, shard.capacity);
+    const uint64_t remaining_capacity = shard.capacity - capped_physical_free;
+    const uint64_t effective_free =
+        capped_physical_free + std::min(pending_free_bytes, remaining_capacity);
+    if (shard.capacity == 0) return 0.0;
+    return 1.0 - static_cast<double>(effective_free) /
+                     static_cast<double>(shard.capacity);
+}
+
+void DfsGlobalAllocator::PrepareEvictionFromShard(ShardState& shard,
+                                                  int shard_idx,
+                                                  PendingEviction& pending) {
+    const double usage = EffectiveUsage(shard);
+    uint64_t prepared_bytes = 0;
+    std::lock_guard lru_lock(shard.lru_mutex);
+    std::lock_guard handle_lock(shard.handle_mutex);
+
+    if (usage >= eviction_high_watermark_) {
+        shard.eviction_active = true;
+    }
+    if (!shard.eviction_active) return;
+    if (usage < eviction_low_watermark_) {
+        shard.eviction_active = false;
+        return;
+    }
+
+    while (true) {
+        if (shard.lru_list.empty()) break;
+        auto lru_it = std::prev(shard.lru_list.end());
+        const std::string evict_key = lru_it->first;
+        const uint64_t evict_offset = lru_it->second;
+
+        auto handle_it = shard.offset_to_handle.find(evict_offset);
+        if (handle_it == shard.offset_to_handle.end() ||
+            handle_it->second.key != evict_key ||
+            handle_it->second.eviction_prepared) {
+            shard.lru_list.erase(lru_it);
+            shard.lru_index.erase(evict_key);
+            continue;
+        }
+
+        EvictionCandidate candidate{evict_key, shard_idx, evict_offset};
+        PendingEviction::PreparedAllocation prepared{
+            candidate, handle_it->second.handle, handle_it->second.bytes};
+        pending.prepared_.push_back(std::move(prepared));
+        try {
+            pending.candidates_.push_back(std::move(candidate));
+        } catch (...) {
+            pending.prepared_.pop_back();
+            throw;
+        }
+
+        handle_it->second.eviction_prepared = true;
+        prepared_bytes += handle_it->second.bytes;
+        shard.lru_list.erase(lru_it);
+        shard.lru_index.erase(evict_key);
+
+        const double projected_usage =
+            usage - static_cast<double>(prepared_bytes) /
+                        static_cast<double>(shard.capacity);
+        if (projected_usage < eviction_low_watermark_) break;
+    }
+}
+
+uint64_t DfsGlobalAllocator::AlignSize(uint64_t size) const {
+    return (size + alignment_ - 1) & ~(alignment_ - 1);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/storage/distributed/distributed_storage_backend.cpp b/mooncake-store/src/storage/distributed/distributed_storage_backend.cpp
index 56483d05f6..fe232f2d66 100644
--- a/mooncake-store/src/storage/distributed/distributed_storage_backend.cpp
+++ b/mooncake-store/src/storage/distributed/distributed_storage_backend.cpp
@@ -1,73 +1,171 @@
 #include "storage/distributed/distributed_storage_backend.h"
 
-#include <fmt/format.h>
-
 #include <algorithm>
-#include <cstdlib>
-#include <xxhash.h>
 #include <filesystem>
+#include <limits>
+#include <optional>
+#include <string_view>
 
-#include "environ.h"
-#include "utils.h"
+#include "types.h"
 
 namespace mooncake {
 
-// === DistributedStorageConfig ===
+namespace {
 
-bool DistributedStorageConfig::Validate() const {
-    if (fsdir.empty()) {
-        LOG(ERROR) << "DistributedStorageConfig: fsdir is empty";
-        return false;
+std::optional<int> ParseShardFileName(std::string_view name) {
+    constexpr std::string_view prefix = "dfs_shard_";
+    constexpr std::string_view suffix = ".data";
+    if (!name.starts_with(prefix) || !name.ends_with(suffix)) {
+        return std::nullopt;
     }
-    if (!std::filesystem::path(fsdir).is_absolute()) {
-        LOG(ERROR)
-            << "DistributedStorageConfig: fsdir must be an absolute path: "
-            << fsdir;
-        return false;
+    name.remove_prefix(prefix.size());
+    name.remove_suffix(suffix.size());
+    if (name.size() < 2) return std::nullopt;
+
+    int index = 0;
+    for (char digit : name) {
+        if (digit < '0' || digit > '9' ||
+            index > (std::numeric_limits<int>::max() - (digit - '0')) / 10) {
+            return std::nullopt;
+        }
+        index = index * 10 + (digit - '0');
     }
-    if (fs_adapter_type.empty()) {
-        LOG(ERROR) << "DistributedStorageConfig: fs_adapter_type is empty";
+    return index;
+}
+
+std::optional<int> ParseBucketFileName(std::string_view name) {
+    constexpr std::string_view prefix = "bucket_";
+    constexpr std::string_view suffix = ".data";
+    if (!name.starts_with(prefix) || !name.ends_with(suffix)) {
+        return std::nullopt;
+    }
+    name.remove_prefix(prefix.size());
+    name.remove_suffix(suffix.size());
+    if (name.empty()) return std::nullopt;
+
+    int index = 0;
+    for (char digit : name) {
+        if (digit < '0' || digit > '9' ||
+            index > (std::numeric_limits<int>::max() - (digit - '0')) / 10) {
+            return std::nullopt;
+        }
+        index = index * 10 + (digit - '0');
+    }
+    return index;
+}
+
+bool IsDfsDescriptorRangeValid(const DistributedFSDescriptor& desc,
+                               const DistributedStorageConfig& config) {
+    if (config.alignment == 0 || desc.object_size == 0 ||
+        desc.aligned_size < desc.object_size ||
+        desc.offset % config.alignment != 0 ||
+        desc.aligned_size % config.alignment != 0) {
         return false;
     }
-    if (fs_adapter_type != "hf3fs") {
-        LOG(ERROR) << "DistributedStorageConfig: unsupported fs_adapter_type: "
-                   << fs_adapter_type;
+    if (desc.offset > config.shard_capacity ||
+        desc.aligned_size > config.shard_capacity - desc.offset) {
         return false;
     }
-    if (hash_bucket_count <= 0) {
-        LOG(ERROR) << "DistributedStorageConfig: hash_bucket_count must > 0";
+
+    constexpr uint64_t kMaxFileOffset =
+        static_cast<uint64_t>(std::numeric_limits<int64_t>::max());
+    return desc.offset <= kMaxFileOffset &&
+           desc.aligned_size <= kMaxFileOffset - desc.offset;
+}
+
+bool IsBucketDescriptorRangeValid(const DistributedFSDescriptor& desc,
+                                  const DistributedStorageConfig& config) {
+    if (config.alignment == 0 || desc.shard_idx < 0 || desc.object_size == 0 ||
+        desc.aligned_size < desc.object_size ||
+        desc.offset % config.alignment != 0 ||
+        desc.aligned_size % config.alignment != 0 ||
+        desc.offset > config.bucket_capacity ||
+        desc.aligned_size > config.bucket_capacity - desc.offset ||
+        desc.object_size > config.bucket_capacity - desc.offset) {
         return false;
     }
-    return true;
+    constexpr uint64_t kMaxOffset =
+        static_cast<uint64_t>(std::numeric_limits<int64_t>::max());
+    return desc.offset <= kMaxOffset &&
+           desc.object_size <= kMaxOffset - desc.offset &&
+           desc.aligned_size <= kMaxOffset - desc.offset;
 }
 
-DistributedStorageConfig DistributedStorageConfig::FromEnvironment() {
-    DistributedStorageConfig config;
-    config.fsdir =
-        Environ::GetString("MOONCAKE_DISTRIBUTED_ROOT_DIR", config.fsdir);
-    if (!std::filesystem::path(config.fsdir).is_absolute()) {
-        config.fsdir = std::filesystem::absolute(config.fsdir).string();
-    }
-    config.fs_adapter_type = Environ::GetString("MOONCAKE_DISTRIBUTED_FS_TYPE",
-                                                config.fs_adapter_type);
-    config.enable_health_check =
-        Environ::GetBool("MOONCAKE_DISTRIBUTED_HEALTH_CHECK", false);
-    config.hash_bucket_count =
-        Environ::GetInt("MOONCAKE_DISTRIBUTED_HASH_BUCKET_COUNT", 256);
-    return config;
+tl::expected<void, ErrorCode> TransferAll(FileSystemAdapter& adapter, int fd,
+                                          std::vector<iovec> iovs,
+                                          int64_t offset, uint64_t total,
+                                          bool write) {
+    size_t index = 0;
+    uint64_t transferred = 0;
+    while (transferred < total) {
+        while (index < iovs.size() && iovs[index].iov_len == 0) ++index;
+        if (index == iovs.size() ||
+            iovs.size() - index >
+                static_cast<size_t>(std::numeric_limits<int>::max())) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        const auto count = static_cast<int>(iovs.size() - index);
+        auto result =
+            write ? adapter.WriteAt(fd, iovs.data() + index, count, offset)
+                  : adapter.ReadAt(fd, iovs.data() + index, count, offset);
+        if (!result) return tl::make_unexpected(result.error());
+        if (*result == 0 || *result > total - transferred) {
+            return tl::make_unexpected(write ? ErrorCode::FILE_WRITE_FAIL
+                                             : ErrorCode::FILE_READ_FAIL);
+        }
+        size_t consumed = *result;
+        transferred += *result;
+        offset += static_cast<int64_t>(*result);
+        while (consumed > 0 && index < iovs.size()) {
+            if (consumed >= iovs[index].iov_len) {
+                consumed -= iovs[index].iov_len;
+                ++index;
+            } else {
+                iovs[index].iov_base =
+                    static_cast<char*>(iovs[index].iov_base) + consumed;
+                iovs[index].iov_len -= consumed;
+                consumed = 0;
+            }
+        }
+    }
+    return {};
 }
 
-// === DistributedStorageBackend ===
+}  // namespace
 
 DistributedStorageBackend::DistributedStorageBackend(
     const FileStorageConfig& file_storage_config,
     const DistributedStorageConfig& distributed_config,
     std::unique_ptr<FileSystemAdapter> fs_adapter)
+    : DistributedStorageBackend(file_storage_config, distributed_config,
+                                std::move(fs_adapter), nullptr) {}
+
+DistributedStorageBackend::DistributedStorageBackend(
+    const FileStorageConfig& file_storage_config,
+    const DistributedStorageConfig& distributed_config,
+    std::unique_ptr<FileSystemAdapter> fs_adapter,
+    std::unique_ptr<ObjectStorageAdapter> object_storage_adapter)
     : StorageBackendInterface(file_storage_config),
       fs_adapter_(std::move(fs_adapter)),
+      object_storage_adapter_(std::move(object_storage_adapter)),
       distributed_config_(distributed_config),
-      root_dir_(distributed_config.fsdir),
-      hash_bucket_count_(distributed_config.hash_bucket_count) {}
+      root_dir_(distributed_config.fsdir) {
+    CHECK((fs_adapter_ != nullptr) != (object_storage_adapter_ != nullptr))
+        << "DistributedStorageBackend: exactly one I/O adapter is required";
+    if (object_storage_adapter_) {
+        storage_mode_ = DistributedStorageMode::kObjectStorage;
+    }
+}
+
+DistributedStorageBackend::~DistributedStorageBackend() {
+    for (auto& [_, shard] : shard_files_) {
+        if (shard && shard->fd >= 0 && fs_adapter_) {
+            fs_adapter_->CloseFile(shard->fd);
+            shard->fd = -1;
+        }
+    }
+    if (fs_adapter_) fs_adapter_->Shutdown();
+}
 
 tl::expected<void, ErrorCode> DistributedStorageBackend::Init() {
     if (initialized_) {
@@ -75,64 +173,139 @@ tl::expected<void, ErrorCode> DistributedStorageBackend::Init() {
         return {};
     }
 
-    auto init_result = fs_adapter_->Init(root_dir_);
-    if (!init_result) return init_result;
+    if (UsesObjectStorage()) {
+        auto init_result = object_storage_adapter_->Init();
+        if (!init_result) return init_result;
+        if (distributed_config_.enable_health_check) {
+            auto health_result = object_storage_adapter_->CheckHealth();
+            if (!health_result) {
+                LOG(ERROR) << "Object storage health check failed, adapter="
+                           << object_storage_adapter_->GetName() << ", error="
+                           << static_cast<int>(health_result.error());
+                return health_result;
+            }
+        }
+        initialized_ = true;
+        LOG(INFO) << "DistributedStorageBackend initialized, object adapter="
+                  << object_storage_adapter_->GetName();
+        return {};
+    }
 
-    // Ensure root directory exists before health check
     std::error_code ec;
     std::filesystem::create_directories(root_dir_, ec);
     if (ec) {
-        LOG(ERROR) << "Failed to create root directory " << root_dir_ << ": "
-                   << ec.message();
+        LOG(ERROR) << "Failed to create DFS root directory " << root_dir_
+                   << ": " << ec.message();
         return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
     }
 
-    if (distributed_config_.enable_health_check) {
-        std::string probe_path =
-            fmt::format("{}/.mooncake_health_probe_{}", root_dir_,
-                        UuidToString(generate_uuid()));
-        std::string probe_data = "health_check";
-        auto write_result = fs_adapter_->WriteFile(
-            probe_path,
-            std::span<const char>(probe_data.data(), probe_data.size()));
-        if (!write_result) {
-            LOG(ERROR) << "DFS health check failed (write): "
-                       << static_cast<int>(write_result.error());
-            return tl::make_unexpected(write_result.error());
-        }
-
-        std::vector<char> read_buf(probe_data.size());
-        auto read_result =
-            fs_adapter_->ReadFile(probe_path, read_buf.data(), read_buf.size());
-        if (!read_result || *read_result != probe_data.size() ||
-            std::string(read_buf.data(), read_buf.size()) != probe_data) {
-            LOG(ERROR) << "DFS health check failed (read back mismatch)";
-            auto del_err = fs_adapter_->DeleteFile(probe_path);
-            if (!del_err) {
-                LOG(WARNING) << "Failed to delete health-check probe: "
-                             << static_cast<int>(del_err.error());
-            }
-            return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
-        }
+    auto init_result = fs_adapter_->Init(root_dir_);
+    if (!init_result) return init_result;
 
-        fs_adapter_->DeleteFile(probe_path);
-        LOG(INFO) << "DFS health check passed, adapter="
-                  << fs_adapter_->GetName();
+    // Only descriptors returned by the master identify published shards.
+    // Opening files from the configured count or a directory scan can retain
+    // handles to staged shards that a failed expansion subsequently unlinks.
+    initialized_ = true;
+    return {};
+}
+
+tl::expected<DistributedStorageBackend::ShardFile*, ErrorCode>
+DistributedStorageBackend::GetOrOpenShard(
+    const DistributedFSDescriptor& descriptor) {
+    const auto path =
+        std::filesystem::path(descriptor.file_path).lexically_normal();
+    auto root = std::filesystem::path(root_dir_).lexically_normal();
+    if (root.filename().empty()) root = root.parent_path();
+    auto parent = path.parent_path();
+    if (parent.empty()) parent = ".";
+    const auto index = ParseShardFileName(path.filename().string());
+    if (descriptor.shard_idx < 0 || !index || *index != descriptor.shard_idx ||
+        parent != root) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
     }
 
-    // Ensure hash bucket directories exist
-    for (int i = 0; i < hash_bucket_count_; ++i) {
-        std::string bucket_dir = fmt::format("{}/{:02x}", root_dir_, i);
-        std::filesystem::create_directories(bucket_dir, ec);
-        if (ec) {
-            LOG(ERROR) << "Failed to create bucket directory " << bucket_dir
-                       << ": " << ec.message();
-            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    ShardFile* shard;
+    {
+        std::lock_guard cache_lock(shard_files_mutex_);
+        auto existing = shard_files_.find(descriptor.shard_idx);
+        if (existing == shard_files_.end()) {
+            existing = shard_files_
+                           .emplace(descriptor.shard_idx,
+                                    std::make_unique<ShardFile>())
+                           .first;
         }
+        shard = existing->second.get();
     }
 
-    initialized_ = true;
-    return {};
+    // File validation and opening may block. Serialize them only with this
+    // shard's initialization and I/O, leaving other cached shards available.
+    std::lock_guard shard_lock(shard->mutex);
+    auto file_path = path.string();
+    if (shard->fd >= 0) {
+        if (shard->path != file_path) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        return shard;
+    }
+
+    // The master prepares new shards before publishing their descriptors.
+    // OpenFile may create a file, so reject missing/unprepared shards first.
+    auto file_size = fs_adapter_->GetFileSize(file_path);
+    if (!file_size) return tl::make_unexpected(file_size.error());
+    if (*file_size != distributed_config_.shard_capacity) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    std::error_code ec;
+    const auto canonical_root = std::filesystem::canonical(root, ec);
+    if (ec) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    const auto canonical_path = std::filesystem::canonical(path, ec);
+    if (ec) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    if (canonical_path.parent_path() != canonical_root ||
+        canonical_path.filename() != path.filename()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto fd = fs_adapter_->OpenFile(file_path);
+    if (!fd) return tl::make_unexpected(fd.error());
+    // Failed attempts keep fd == -1 so a later request can retry
+    // initialization.
+    shard->path = std::move(file_path);
+    shard->fd = *fd;
+    return shard;
+}
+
+bool DistributedStorageBackend::UsesBucketAllocator() const {
+    return distributed_config_.allocator_type == "bucket";
+}
+
+tl::expected<int, ErrorCode> DistributedStorageBackend::OpenBucket(
+    const DistributedFSDescriptor& descriptor) {
+    const auto path =
+        std::filesystem::path(descriptor.file_path).lexically_normal();
+    auto root = std::filesystem::path(root_dir_).lexically_normal();
+    if (root.filename().empty()) root = root.parent_path();
+    auto parent = path.parent_path();
+    if (parent.empty()) parent = ".";
+    const auto bucket_id = ParseBucketFileName(path.filename().string());
+    if (!bucket_id || *bucket_id != descriptor.shard_idx || parent != root) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    const std::string file_path = path.string();
+    auto file_size = fs_adapter_->GetFileSize(file_path);
+    if (!file_size) return tl::make_unexpected(file_size.error());
+    if (*file_size != distributed_config_.bucket_capacity) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    std::error_code error;
+    const auto canonical_root = std::filesystem::canonical(root, error);
+    if (error) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    const auto canonical_path = std::filesystem::canonical(path, error);
+    if (error) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    if (canonical_path.parent_path() != canonical_root ||
+        canonical_path.filename() != path.filename()) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    return fs_adapter_->OpenExistingFile(file_path);
 }
 
 tl::expected<int64_t, ErrorCode> DistributedStorageBackend::BatchOffload(
@@ -141,11 +314,13 @@ tl::expected<int64_t, ErrorCode> DistributedStorageBackend::BatchOffload(
                             std::vector<StorageObjectMetadata>& metadatas)>
         complete_handler,
     EvictionHandler eviction_handler) {
+    if (!UsesObjectStorage()) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
     if (!initialized_) {
         LOG(ERROR) << "DistributedStorageBackend is not initialized";
         return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
     }
-
     if (eviction_handler) {
         LOG_FIRST_N(WARNING, 1)
             << "DistributedStorageBackend does not support eviction, "
@@ -154,54 +329,338 @@ tl::expected<int64_t, ErrorCode> DistributedStorageBackend::BatchOffload(
 
     std::vector<std::string> success_keys;
     std::vector<StorageObjectMetadata> success_metas;
-
+    std::vector<ObjectPutRequest> requests;
+    // Own descriptors through PutBatch; each request only borrows an array.
+    std::vector<std::vector<iovec>> iov_storage;
+    std::vector<size_t> request_sizes;
+    requests.reserve(batch_object.size());
+    iov_storage.reserve(batch_object.size());
+    request_sizes.reserve(batch_object.size());
     for (const auto& [key, slices] : batch_object) {
-        auto path = GetObjectPath(key);
-
+        if (slices.size() >
+            static_cast<size_t>(std::numeric_limits<int>::max())) {
+            LOG(WARNING) << "Failed to offload key " << key
+                         << ": slice count exceeds INT_MAX";
+            continue;
+        }
         std::vector<iovec> iovs;
+        iovs.reserve(slices.size());
+        size_t total_size = 0;
+        bool total_size_overflow = false;
         for (const auto& slice : slices) {
+            if (slice.size > std::numeric_limits<size_t>::max() - total_size) {
+                total_size_overflow = true;
+                break;
+            }
             iovs.push_back({slice.ptr, slice.size});
+            total_size += slice.size;
         }
-
-        auto result =
-            fs_adapter_->VectorWriteFile(path, iovs.data(), iovs.size(), 0);
-        if (!result) {
-            LOG(WARNING) << "Failed to offload key " << key << ": "
-                         << static_cast<int>(result.error());
+        if (total_size_overflow) {
+            LOG(WARNING) << "Failed to offload key " << key
+                         << ": total slice size overflows size_t";
             continue;
         }
 
-        success_keys.push_back(key);
-        StorageObjectMetadata meta{-1, 0, static_cast<int64_t>(key.size()),
-                                   static_cast<int64_t>(*result), ""};
-        success_metas.push_back(meta);
+        iov_storage.push_back(std::move(iovs));
+        const auto& stored_iovs = iov_storage.back();
+        requests.push_back(
+            {key, stored_iovs.data(), static_cast<int>(stored_iovs.size())});
+        request_sizes.push_back(total_size);
     }
 
-    if (!success_keys.empty()) {
+    auto results = object_storage_adapter_->PutBatch(requests);
+    if (results.size() != requests.size()) {
+        LOG(ERROR)
+            << "Object storage returned an invalid PUT batch result count";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    for (size_t i = 0; i < results.size(); ++i) {
+        if (!results[i]) {
+            LOG(WARNING) << "Failed to offload key " << requests[i].logical_key
+                         << ": " << static_cast<int>(results[i].error());
+            continue;
+        }
+        success_keys.push_back(requests[i].logical_key);
+        success_metas.emplace_back(
+            -1, 0, static_cast<int64_t>(requests[i].logical_key.size()),
+            static_cast<int64_t>(request_sizes[i]), "");
+    }
+
+    if (complete_handler && !success_keys.empty()) {
         auto err = complete_handler(success_keys, success_metas);
         if (err != ErrorCode::OK) {
             return tl::make_unexpected(err);
         }
     }
-
     return static_cast<int64_t>(success_keys.size());
 }
 
+std::vector<tl::expected<void, ErrorCode>>
+DistributedStorageBackend::BatchWrite(
+    const std::vector<DfsWriteRequest>& requests) {
+    std::vector<tl::expected<void, ErrorCode>> results;
+    results.reserve(requests.size());
+
+    if (UsesObjectStorage()) {
+        results.assign(requests.size(),
+                       tl::make_unexpected(ErrorCode::NOT_SUPPORTED));
+        return results;
+    }
+    if (!initialized_) {
+        LOG(ERROR) << "DistributedStorageBackend is not initialized";
+        results.assign(requests.size(),
+                       tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE));
+        return results;
+    }
+
+    for (const auto& request : requests) {
+        const auto& desc = request.descriptor;
+        const bool bucket_mode = UsesBucketAllocator();
+        const bool range_valid =
+            bucket_mode
+                ? IsBucketDescriptorRangeValid(desc, distributed_config_)
+                : IsDfsDescriptorRangeValid(desc, distributed_config_);
+        if (!range_valid) {
+            LOG(ERROR) << "Invalid DFS descriptor range for key " << request.key
+                       << ", offset=" << desc.offset
+                       << ", object_size=" << desc.object_size
+                       << ", aligned_size=" << desc.aligned_size
+                       << ", capacity="
+                       << (bucket_mode ? distributed_config_.bucket_capacity
+                                       : distributed_config_.shard_capacity);
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+
+        if (request.slices.size() >
+            static_cast<size_t>(std::numeric_limits<int>::max())) {
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+        std::vector<iovec> iovs;
+        iovs.reserve(request.slices.size());
+        uint64_t total_size = 0;
+        bool invalid = false;
+        for (const auto& slice : request.slices) {
+            if ((!slice.ptr && slice.size > 0) ||
+                slice.size >
+                    std::numeric_limits<uint64_t>::max() - total_size) {
+                invalid = true;
+                break;
+            }
+            total_size += slice.size;
+            iovs.push_back({slice.ptr, slice.size});
+        }
+        if (invalid || total_size != desc.object_size) {
+            LOG(WARNING) << "Invalid DFS write request for key " << request.key
+                         << ", expected=" << desc.object_size
+                         << ", actual=" << total_size;
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+
+        if (bucket_mode) {
+            auto fd = OpenBucket(desc);
+            if (!fd) {
+                results.emplace_back(tl::make_unexpected(fd.error()));
+                continue;
+            }
+            auto write_result = TransferAll(*fs_adapter_, *fd, std::move(iovs),
+                                            static_cast<int64_t>(desc.offset),
+                                            total_size, true);
+            auto close_result = fs_adapter_->CloseFile(*fd);
+            if (!write_result) {
+                results.emplace_back(tl::make_unexpected(write_result.error()));
+            } else if (!close_result) {
+                results.emplace_back(tl::make_unexpected(close_result.error()));
+            } else {
+                results.emplace_back();
+            }
+            continue;
+        }
+
+        auto shard_result = GetOrOpenShard(desc);
+        if (!shard_result) {
+            LOG(ERROR) << "Failed to open DFS shard for key " << request.key
+                       << ": " << shard_result.error();
+            results.emplace_back(tl::make_unexpected(shard_result.error()));
+            continue;
+        }
+        auto& shard = **shard_result;
+        std::lock_guard lock(shard.mutex);
+        auto write_result =
+            fs_adapter_->WriteAt(shard.fd, iovs.data(), iovs.size(),
+                                 static_cast<int64_t>(desc.offset));
+        if (!write_result) {
+            LOG(WARNING) << "DFS write failed for key " << request.key
+                         << ", error=" << write_result.error();
+            results.emplace_back(tl::make_unexpected(write_result.error()));
+            continue;
+        }
+        if (*write_result != total_size) {
+            LOG(WARNING) << "DFS short write for key " << request.key
+                         << ", expected=" << total_size
+                         << ", actual=" << *write_result;
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL));
+            continue;
+        }
+        results.emplace_back();
+    }
+    return results;
+}
+
+std::vector<tl::expected<void, ErrorCode>> DistributedStorageBackend::BatchRead(
+    const std::vector<DfsReadRequest>& requests) {
+    std::vector<tl::expected<void, ErrorCode>> results;
+    results.reserve(requests.size());
+
+    if (UsesObjectStorage()) {
+        results.assign(requests.size(),
+                       tl::make_unexpected(ErrorCode::NOT_SUPPORTED));
+        return results;
+    }
+    if (!initialized_) {
+        LOG(ERROR) << "DistributedStorageBackend is not initialized";
+        results.assign(requests.size(),
+                       tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE));
+        return results;
+    }
+
+    for (const auto& request : requests) {
+        const auto& desc = request.descriptor;
+        const bool bucket_mode = UsesBucketAllocator();
+        const bool range_valid =
+            bucket_mode
+                ? IsBucketDescriptorRangeValid(desc, distributed_config_)
+                : IsDfsDescriptorRangeValid(desc, distributed_config_);
+        if (!range_valid) {
+            LOG(ERROR) << "Invalid DFS descriptor range for key " << request.key
+                       << ", offset=" << desc.offset
+                       << ", object_size=" << desc.object_size
+                       << ", aligned_size=" << desc.aligned_size
+                       << ", capacity="
+                       << (bucket_mode ? distributed_config_.bucket_capacity
+                                       : distributed_config_.shard_capacity);
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+        if (desc.object_size > std::numeric_limits<size_t>::max() ||
+            request.slices.size() >
+                static_cast<size_t>(std::numeric_limits<int>::max())) {
+            LOG(ERROR) << "DFS read request exceeds platform limits for key "
+                       << request.key << ", object_size=" << desc.object_size
+                       << ", slice_count=" << request.slices.size();
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+
+        std::vector<iovec> iovs;
+        iovs.reserve(request.slices.size());
+        size_t remaining = static_cast<size_t>(desc.object_size);
+        bool invalid = false;
+        for (const auto& slice : request.slices) {
+            if (!slice.ptr && slice.size > 0) {
+                invalid = true;
+                break;
+            }
+            if (remaining == 0 || slice.size == 0) {
+                continue;
+            }
+            const size_t read_size = std::min(slice.size, remaining);
+            iovs.push_back({slice.ptr, read_size});
+            remaining -= read_size;
+        }
+        if (invalid || remaining != 0) {
+            LOG(WARNING) << "Invalid DFS read request for key " << request.key
+                         << ", expected capacity at least=" << desc.object_size;
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+            continue;
+        }
+
+        if (bucket_mode) {
+            auto fd = OpenBucket(desc);
+            if (!fd) {
+                results.emplace_back(tl::make_unexpected(fd.error()));
+                continue;
+            }
+            auto read_result = TransferAll(*fs_adapter_, *fd, std::move(iovs),
+                                           static_cast<int64_t>(desc.offset),
+                                           desc.object_size, false);
+            auto close_result = fs_adapter_->CloseFile(*fd);
+            if (!read_result) {
+                results.emplace_back(tl::make_unexpected(read_result.error()));
+            } else if (!close_result) {
+                results.emplace_back(tl::make_unexpected(close_result.error()));
+            } else {
+                results.emplace_back();
+            }
+            continue;
+        }
+
+        auto shard_result = GetOrOpenShard(desc);
+        if (!shard_result) {
+            LOG(ERROR) << "Failed to open DFS shard for key " << request.key
+                       << ": " << shard_result.error();
+            results.emplace_back(tl::make_unexpected(shard_result.error()));
+            continue;
+        }
+        auto& shard = **shard_result;
+        std::lock_guard lock(shard.mutex);
+        auto read_result = fs_adapter_->ReadAt(
+            shard.fd, iovs.data(), static_cast<int>(iovs.size()),
+            static_cast<int64_t>(desc.offset));
+        if (!read_result) {
+            LOG(WARNING) << "DFS read failed for key " << request.key
+                         << ", error=" << read_result.error();
+            results.emplace_back(tl::make_unexpected(read_result.error()));
+            continue;
+        }
+        if (*read_result != desc.object_size) {
+            LOG(WARNING) << "DFS short read for key " << request.key
+                         << ", expected=" << desc.object_size
+                         << ", actual=" << *read_result;
+            results.emplace_back(
+                tl::make_unexpected(ErrorCode::FILE_READ_FAIL));
+            continue;
+        }
+        results.emplace_back();
+    }
+    return results;
+}
+
 tl::expected<void, ErrorCode> DistributedStorageBackend::BatchLoad(
     std::unordered_map<std::string, Slice>& batched_slices) {
+    if (!UsesObjectStorage()) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
     if (!initialized_) {
         LOG(ERROR) << "DistributedStorageBackend is not initialized";
         return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
     }
 
+    std::vector<ObjectGetRequest> requests;
+    requests.reserve(batched_slices.size());
     for (auto& [key, slice] : batched_slices) {
-        auto path = GetObjectPath(key);
-
-        auto result = fs_adapter_->ReadFile(path, slice.ptr, slice.size);
-        if (!result) {
-            return tl::make_unexpected(result.error());
+        requests.push_back({key, slice.ptr, slice.size});
+    }
+    auto results = object_storage_adapter_->GetBatch(requests);
+    if (results.size() != requests.size()) {
+        LOG(ERROR)
+            << "Object storage returned an invalid GET batch result count";
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    for (size_t i = 0; i < results.size(); ++i) {
+        if (!results[i]) {
+            return tl::make_unexpected(results[i].error());
         }
-        if (*result != slice.size) {
+        if (*results[i] != requests[i].size) {
             return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
         }
     }
@@ -210,23 +669,27 @@ tl::expected<void, ErrorCode> DistributedStorageBackend::BatchLoad(
 
 tl::expected<bool, ErrorCode> DistributedStorageBackend::IsExist(
     const std::string& key) {
+    if (!UsesObjectStorage()) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
     if (!initialized_) {
         LOG(ERROR) << "DistributedStorageBackend is not initialized";
         return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
     }
-
-    auto path = GetObjectPath(key);
-    return fs_adapter_->FileExists(path);
+    return object_storage_adapter_->Exists(key);
 }
 
 tl::expected<bool, ErrorCode> DistributedStorageBackend::IsEnableOffloading() {
-    return true;
+    return UsesObjectStorage();
 }
 
 tl::expected<void, ErrorCode> DistributedStorageBackend::ScanMeta(
     const std::function<
         ErrorCode(const std::vector<std::string>& keys,
                   std::vector<StorageObjectMetadata>& metadatas)>& handler) {
+    if (!UsesObjectStorage()) {
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+    }
     if (!initialized_) {
         LOG(ERROR) << "DistributedStorageBackend is not initialized";
         return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
@@ -237,31 +700,23 @@ tl::expected<void, ErrorCode> DistributedStorageBackend::ScanMeta(
     const size_t batch_limit = static_cast<size_t>(std::max<int64_t>(
         1, file_storage_config_.scanmeta_iterator_keys_limit));
 
-    for (int i = 0; i < hash_bucket_count_; ++i) {
-        std::string bucket_dir = fmt::format("{}/{:02x}", root_dir_, i);
-        auto file_infos = fs_adapter_->ListFilesWithInfo(bucket_dir);
-        if (!file_infos) {
-            if (file_infos.error() == ErrorCode::FILE_NOT_FOUND) {
-                continue;
-            }
-            LOG(ERROR) << "Failed to list files in bucket " << bucket_dir
-                       << ": " << static_cast<int>(file_infos.error());
-            return tl::make_unexpected(file_infos.error());
-        }
-
-        for (const auto& info : *file_infos) {
-            std::string key = UnescapeFilename(info.name);
-            batch_keys.push_back(key);
-            StorageObjectMetadata meta{-1, 0, static_cast<int64_t>(key.size()),
-                                       static_cast<int64_t>(info.size), ""};
-            batch_metas.push_back(meta);
-
-            if (batch_keys.size() >= batch_limit) {
-                auto err = handler(batch_keys, batch_metas);
-                if (err != ErrorCode::OK) return tl::make_unexpected(err);
-                batch_keys.clear();
-                batch_metas.clear();
-            }
+    auto key_infos = object_storage_adapter_->ListKeys();
+    if (!key_infos) {
+        LOG(ERROR) << "Failed to list keys from object storage adapter: "
+                   << static_cast<int>(key_infos.error());
+        return tl::make_unexpected(key_infos.error());
+    }
+
+    for (const auto& info : *key_infos) {
+        batch_keys.push_back(info.logical_key);
+        batch_metas.emplace_back(-1, 0,
+                                 static_cast<int64_t>(info.logical_key.size()),
+                                 static_cast<int64_t>(info.size), "");
+        if (batch_keys.size() >= batch_limit) {
+            auto err = handler(batch_keys, batch_metas);
+            if (err != ErrorCode::OK) return tl::make_unexpected(err);
+            batch_keys.clear();
+            batch_metas.clear();
         }
     }
     if (!batch_keys.empty()) {
@@ -271,50 +726,4 @@ tl::expected<void, ErrorCode> DistributedStorageBackend::ScanMeta(
     return {};
 }
 
-// === Key -> Path mapping ===
-
-std::string DistributedStorageBackend::GetObjectPath(
-    const std::string& key) const {
-    uint64_t hash = XXH64(key.data(), key.size(), 0);
-    std::string bucket = fmt::format("{:02x}", hash % hash_bucket_count_);
-    std::string safe_key = EscapeFilename(key);
-    return (std::filesystem::path(root_dir_) / bucket / safe_key).string();
-}
-
-std::string DistributedStorageBackend::EscapeFilename(const std::string& key) {
-    std::string result;
-    result.reserve(key.size() + 16);
-    for (unsigned char c : key) {
-        if (c == '@' || c == ':' || c == '/' || c == '\\' || c == '%' ||
-            c < 0x20 || c > 0x7e) {
-            result += fmt::format("%{:02x}", static_cast<unsigned>(c));
-        } else {
-            result += static_cast<char>(c);
-        }
-    }
-    return result;
-}
-
-std::string DistributedStorageBackend::UnescapeFilename(
-    const std::string& name) {
-    auto is_hex = [](char c) {
-        return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') ||
-               (c >= 'A' && c <= 'F');
-    };
-    std::string result;
-    result.reserve(name.size());
-    for (size_t i = 0; i < name.size(); ++i) {
-        if (name[i] == '%' && i + 2 < name.size() && is_hex(name[i + 1]) &&
-            is_hex(name[i + 2])) {
-            char hex[3] = {name[i + 1], name[i + 2], 0};
-            unsigned long val = strtoul(hex, nullptr, 16);
-            result += static_cast<char>(val);
-            i += 2;
-        } else {
-            result += name[i];
-        }
-    }
-    return result;
-}
-
 }  // namespace mooncake
diff --git a/mooncake-store/src/storage/distributed/hf3fs_adapter.cpp b/mooncake-store/src/storage/distributed/hf3fs_adapter.cpp
index a4ccf3b522..49cb655249 100644
--- a/mooncake-store/src/storage/distributed/hf3fs_adapter.cpp
+++ b/mooncake-store/src/storage/distributed/hf3fs_adapter.cpp
@@ -2,12 +2,16 @@
 
 #include <dirent.h>
 #include <fcntl.h>
+#include <limits.h>
 #include <unistd.h>
 
+#include <algorithm>
 #include <cerrno>
 #include <cstring>
 #include <filesystem>
 
+#include <glog/logging.h>
+
 #include "hf3fs/hf3fs.h"
 
 namespace mooncake {
@@ -21,7 +25,14 @@ tl::expected<void, ErrorCode> Hf3fsAdapter::Init(
     const std::string& mount_path) {
     resource_manager_ = std::make_unique<USRBIOResourceManager>();
     Hf3fsConfig config{};
-    config.mount_root = mount_path;
+    char hf3fs_mount_point[PATH_MAX] = {};
+    int ret = hf3fs_extract_mount_point(
+        hf3fs_mount_point, sizeof(hf3fs_mount_point), mount_path.c_str());
+    if (ret > 0 && ret <= static_cast<int>(sizeof(hf3fs_mount_point))) {
+        config.mount_root = hf3fs_mount_point;
+    } else {
+        config.mount_root = mount_path;
+    }
     resource_manager_->setDefaultParams(config);
     return {};
 }
@@ -379,4 +390,202 @@ tl::expected<std::vector<std::string>, ErrorCode> Hf3fsAdapter::ListFiles(
     return result;
 }
 
+tl::expected<int, ErrorCode> Hf3fsAdapter::OpenFile(const std::string& path) {
+    int fd = open(path.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+
+    if (hf3fs_reg_fd(fd, 0) > 0) {
+        close(fd);
+        return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    }
+    return fd;
+}
+
+tl::expected<int, ErrorCode> Hf3fsAdapter::OpenExistingFile(
+    const std::string& path) {
+    int fd;
+    do {
+        fd = open(path.c_str(), O_RDWR | O_CLOEXEC);
+    } while (fd < 0 && errno == EINTR);
+    if (fd < 0) {
+        return tl::make_unexpected(errno == ENOENT ? ErrorCode::FILE_NOT_FOUND
+                                                   : ErrorCode::FILE_OPEN_FAIL);
+    }
+    if (hf3fs_reg_fd(fd, 0) > 0) {
+        close(fd);
+        return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    }
+    return fd;
+}
+
+tl::expected<void, ErrorCode> Hf3fsAdapter::CloseFile(int fd) {
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_INVALID_HANDLE);
+    hf3fs_dereg_fd(fd);
+    if (close(fd) != 0) {
+        return tl::make_unexpected(ErrorCode::FILE_INVALID_HANDLE);
+    }
+    return {};
+}
+
+tl::expected<void, ErrorCode> Hf3fsAdapter::PreallocateFile(
+    const std::string& path, uint64_t size) {
+    int fd = open(path.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+
+    int rc = fallocate(fd, 0, 0, static_cast<off_t>(size));
+    if (rc != 0) {
+        rc = ftruncate(fd, static_cast<off_t>(size));
+    }
+    int saved_errno = errno;
+    close(fd);
+
+    if (rc != 0) {
+        errno = saved_errno;
+        LOG(ERROR) << "Failed to preallocate DFS file " << path
+                   << ", size=" << size << ", error=" << strerror(errno);
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    return {};
+}
+
+tl::expected<size_t, ErrorCode> Hf3fsAdapter::WriteAt(int fd, const iovec* iov,
+                                                      int iovcnt,
+                                                      int64_t offset) {
+    if (fd < 0 || offset < 0 || iovcnt < 0 || (iovcnt > 0 && iov == nullptr)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    for (int i = 0; i < iovcnt; ++i) {
+        if (!iov[i].iov_base && iov[i].iov_len > 0) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+
+    auto* resource = resource_manager_->getThreadResource();
+    if (!resource || !resource->initialized) {
+        return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    }
+
+    size_t total_length = 0;
+    for (int i = 0; i < iovcnt; ++i) total_length += iov[i].iov_len;
+    if (total_length == 0) return size_t{0};
+
+    auto& threefs_iov = resource->iov_;
+    auto& ior_write = resource->ior_write_;
+    size_t total_written = 0;
+    size_t remaining = total_length;
+    int iov_idx = 0;
+    size_t iov_off = 0;
+    off_t current_offset = static_cast<off_t>(offset);
+
+    while (remaining > 0) {
+        size_t chunk = std::min(remaining, resource->config_.iov_size);
+        size_t copied = 0;
+        char* dest = reinterpret_cast<char*>(threefs_iov.base);
+        while (copied < chunk && iov_idx < iovcnt) {
+            if (iov_off >= iov[iov_idx].iov_len) {
+                ++iov_idx;
+                iov_off = 0;
+                continue;
+            }
+            size_t n = std::min(chunk - copied, iov[iov_idx].iov_len - iov_off);
+            memcpy(dest + copied,
+                   static_cast<char*>(iov[iov_idx].iov_base) + iov_off, n);
+            copied += n;
+            iov_off += n;
+        }
+        if (copied == 0) break;
+
+        int ret =
+            hf3fs_prep_io(&ior_write, &threefs_iov, false, threefs_iov.base, fd,
+                          current_offset, copied, nullptr);
+        if (ret < 0) break;
+        ret = hf3fs_submit_ios(&ior_write);
+        if (ret < 0) break;
+        struct hf3fs_cqe cqe;
+        ret = hf3fs_wait_for_ios(&ior_write, &cqe, 1, 1, nullptr);
+        if (ret < 0 || cqe.result < 0) break;
+
+        size_t bytes_written = cqe.result;
+        if (bytes_written == 0) break;
+        total_written += bytes_written;
+        current_offset += bytes_written;
+        remaining -= bytes_written;
+        if (bytes_written < copied) break;
+    }
+
+    if (total_written != total_length) {
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    return total_written;
+}
+
+tl::expected<size_t, ErrorCode> Hf3fsAdapter::ReadAt(int fd, iovec* iov,
+                                                     int iovcnt,
+                                                     int64_t offset) {
+    if (fd < 0 || offset < 0 || iovcnt < 0 || (iovcnt > 0 && iov == nullptr)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    for (int i = 0; i < iovcnt; ++i) {
+        if (!iov[i].iov_base && iov[i].iov_len > 0) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+
+    auto* resource = resource_manager_->getThreadResource();
+    if (!resource || !resource->initialized) {
+        return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    }
+
+    size_t total_length = 0;
+    for (int i = 0; i < iovcnt; ++i) total_length += iov[i].iov_len;
+    if (total_length == 0) return size_t{0};
+
+    auto& threefs_iov = resource->iov_;
+    auto& ior_read = resource->ior_read_;
+    size_t total_read = 0;
+    size_t remaining = total_length;
+    int iov_idx = 0;
+    size_t iov_off = 0;
+    off_t current_offset = static_cast<off_t>(offset);
+
+    while (remaining > 0) {
+        size_t chunk = std::min(remaining, resource->config_.iov_size);
+        int ret = hf3fs_prep_io(&ior_read, &threefs_iov, true, threefs_iov.base,
+                                fd, current_offset, chunk, nullptr);
+        if (ret < 0) break;
+        ret = hf3fs_submit_ios(&ior_read);
+        if (ret < 0) break;
+        struct hf3fs_cqe cqe;
+        ret = hf3fs_wait_for_ios(&ior_read, &cqe, 1, 1, nullptr);
+        if (ret < 0 || cqe.result < 0) break;
+
+        size_t bytes_read = cqe.result;
+        if (bytes_read == 0) break;
+
+        size_t to_copy = bytes_read;
+        char* src = reinterpret_cast<char*>(threefs_iov.base);
+        while (to_copy > 0 && iov_idx < iovcnt) {
+            if (iov_off >= iov[iov_idx].iov_len) {
+                ++iov_idx;
+                iov_off = 0;
+                continue;
+            }
+            size_t n = std::min(to_copy, iov[iov_idx].iov_len - iov_off);
+            memcpy(static_cast<char*>(iov[iov_idx].iov_base) + iov_off, src, n);
+            src += n;
+            to_copy -= n;
+            total_read += n;
+            remaining -= n;
+            current_offset += n;
+            iov_off += n;
+        }
+        if (bytes_read < chunk) break;
+    }
+
+    if (total_read != total_length) {
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    }
+    return total_read;
+}
+
 }  // namespace mooncake
diff --git a/mooncake-store/src/storage/distributed/immutable_bucket_allocator.cpp b/mooncake-store/src/storage/distributed/immutable_bucket_allocator.cpp
new file mode 100644
index 0000000000..be3c9a072a
--- /dev/null
+++ b/mooncake-store/src/storage/distributed/immutable_bucket_allocator.cpp
@@ -0,0 +1,604 @@
+#include "storage/distributed/immutable_bucket_allocator.h"
+
+#include <iomanip>
+#include <limits>
+#include <sstream>
+#include <string_view>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "config/distributed_storage_config.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#ifdef USE_3FS
+#include "storage/distributed/hf3fs_adapter.h"
+#endif
+
+namespace mooncake {
+namespace {
+
+bool IsBucketArtifact(std::string_view name) {
+    return name.starts_with("bucket_") &&
+           (name.ends_with(".data") || name.ends_with(".meta"));
+}
+
+}  // namespace
+
+ImmutableBucketAllocator::PendingEviction::~PendingEviction() {
+    if (owner_) owner_->AbortEvictionLocked(*this, false);
+}
+
+ImmutableBucketAllocator::PendingEviction::PendingEviction(
+    PendingEviction&& other) noexcept
+    : owner_(std::exchange(other.owner_, nullptr)),
+      bucket_id_(std::exchange(other.bucket_id_, -1)),
+      identity_(std::move(other.identity_)),
+      candidates_(std::move(other.candidates_)) {}
+
+ImmutableBucketAllocator::PendingEviction&
+ImmutableBucketAllocator::PendingEviction::operator=(
+    PendingEviction&& other) noexcept {
+    if (this == &other) return *this;
+    if (owner_) owner_->AbortEvictionLocked(*this, false);
+    owner_ = std::exchange(other.owner_, nullptr);
+    bucket_id_ = std::exchange(other.bucket_id_, -1);
+    identity_ = std::move(other.identity_);
+    candidates_ = std::move(other.candidates_);
+    return *this;
+}
+
+ImmutableBucketAllocator::EvictedBucket::EvictedBucket(
+    EvictedBucket&& other) noexcept
+    : bucket_id_(std::exchange(other.bucket_id_, -1)),
+      identity_(std::move(other.identity_)) {}
+
+ImmutableBucketAllocator::EvictedBucket&
+ImmutableBucketAllocator::EvictedBucket::operator=(
+    EvictedBucket&& other) noexcept {
+    if (this == &other) return *this;
+    bucket_id_ = std::exchange(other.bucket_id_, -1);
+    identity_ = std::move(other.identity_);
+    return *this;
+}
+
+ImmutableBucketAllocator::~ImmutableBucketAllocator() {
+    initialized_.store(false, std::memory_order_release);
+    if (fs_adapter_) fs_adapter_->Shutdown();
+}
+
+tl::expected<void, ErrorCode> ImmutableBucketAllocator::Init(
+    const DistributedStorageConfig& config) {
+    if (initialized_.load(std::memory_order_acquire)) return {};
+    if (!config.ValidateForAllocator() ||
+        config.bucket_capacity >
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max()) ||
+        config.bucket_capacity >
+            std::numeric_limits<uint64_t>::max() /
+                static_cast<uint64_t>(config.max_bucket_count)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    std::unique_ptr<FileSystemAdapter> adapter;
+    if (config.fs_adapter_type == "posix") {
+        adapter = std::make_unique<PosixFsAdapter>();
+    } else if (config.fs_adapter_type == "hf3fs") {
+#ifdef USE_3FS
+        adapter = std::make_unique<Hf3fsAdapter>();
+#else
+        return tl::make_unexpected(ErrorCode::NOT_SUPPORTED);
+#endif
+    } else {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    auto init = adapter->Init(config.fsdir);
+    if (!init) return tl::make_unexpected(init.error());
+    auto files = adapter->ListFiles(config.fsdir);
+    if (!files) {
+        adapter->Shutdown();
+        return tl::make_unexpected(files.error());
+    }
+    for (const auto& name : *files) {
+        if (IsBucketArtifact(name)) {
+            LOG(ERROR) << "Immutable DFS bucket recovery is unsupported; "
+                          "refusing non-empty root containing "
+                       << name << ". Configure a new empty DFS root.";
+            adapter->Shutdown();
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+
+    std::lock_guard lock(mutex_);
+    fsdir_ = config.fsdir;
+    bucket_capacity_ = config.bucket_capacity;
+    alignment_ = config.alignment;
+    max_bucket_count_ = config.max_bucket_count;
+    eviction_enabled_ = config.eviction_enabled;
+    eviction_high_watermark_ = config.eviction_high_watermark;
+    eviction_low_watermark_ = config.eviction_low_watermark;
+    eviction_check_interval_ = config.eviction_check_interval;
+    fs_adapter_ = std::move(adapter);
+    initialized_.store(true, std::memory_order_release);
+    return {};
+}
+
+std::string ImmutableBucketAllocator::FormatBucketId(int64_t bucket_id) {
+    std::ostringstream stream;
+    stream << std::setw(6) << std::setfill('0') << bucket_id;
+    return stream.str();
+}
+
+std::string ImmutableBucketAllocator::BucketDataPath(int64_t bucket_id) const {
+    return fsdir_ + "/bucket_" + FormatBucketId(bucket_id) + ".data";
+}
+
+tl::expected<ImmutableBucketAllocator::BucketPtr, ErrorCode>
+ImmutableBucketAllocator::EnsureActiveBucketLocked(uint64_t required) {
+    if (required == 0 || required > bucket_capacity_) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    if (active_bucket_id_ >= 0) {
+        const auto current = buckets_.find(active_bucket_id_);
+        if (current != buckets_.end() &&
+            current->second->lifecycle == BucketLifecycle::ACTIVE &&
+            current->second->append_offset <= current->second->capacity &&
+            required <=
+                current->second->capacity - current->second->append_offset) {
+            return current->second;
+        }
+        if (current != buckets_.end() &&
+            current->second->lifecycle == BucketLifecycle::ACTIVE) {
+            current->second->lifecycle = BucketLifecycle::SEALED;
+            TouchLruLocked(current->first);
+        }
+        active_bucket_id_ = -1;
+    }
+
+    if (next_bucket_id_ > kMaxBucketId) {
+        LOG(ERROR) << "Immutable DFS bucket id space exhausted, next_id="
+                   << next_bucket_id_;
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    if (buckets_.size() >= static_cast<size_t>(max_bucket_count_)) {
+        return tl::make_unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+    }
+
+    const int64_t bucket_id = next_bucket_id_++;
+    const std::string path = BucketDataPath(bucket_id);
+    auto preallocated = fs_adapter_->PreallocateFile(path, bucket_capacity_);
+    if (!preallocated) {
+        auto cleaned = fs_adapter_->DeleteFile(path);
+        if (!cleaned && cleaned.error() != ErrorCode::FILE_NOT_FOUND) {
+            LOG(WARNING) << "Failed to clean up unpublished DFS bucket " << path
+                         << ": " << cleaned.error();
+        }
+        return tl::make_unexpected(preallocated.error());
+    }
+
+    auto bucket = std::make_shared<BucketState>();
+    bucket->id = bucket_id;
+    bucket->capacity = bucket_capacity_;
+    buckets_.emplace(bucket_id, bucket);
+    active_bucket_id_ = bucket_id;
+    return bucket;
+}
+
+tl::expected<DistributedFSDescriptor, ErrorCode>
+ImmutableBucketAllocator::ReserveInBucketLocked(BucketState& bucket,
+                                                const std::string& key,
+                                                uint64_t size) {
+    if (key.empty() || key_index_.contains(key)) {
+        return tl::make_unexpected(key.empty()
+                                       ? ErrorCode::INVALID_PARAMS
+                                       : ErrorCode::OBJECT_ALREADY_EXISTS);
+    }
+    const auto layout =
+        ComputeBucketEntryLayout(bucket.append_offset, size, alignment_);
+    if (!layout || layout->end() > bucket.capacity ||
+        layout->offset >
+            static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+        LOG(ERROR) << "Immutable DFS bucket layout invariant violated, bucket="
+                   << bucket.id << ", append_offset=" << bucket.append_offset
+                   << ", size=" << size;
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+
+    BucketEntry entry;
+    entry.layout = *layout;
+    // A key may be allocated again after its previous reservation became a
+    // tombstone. Replace only the runtime index record; append_offset is never
+    // rewound, so the stale descriptor's physical range is never reused.
+    bucket.entries.insert_or_assign(key, entry);
+    key_index_[key] = bucket.id;
+    bucket.append_offset = layout->end();
+    ++bucket.pending_entries;
+    return MakeBucketDescriptor(BucketDataPath(bucket.id), *layout, bucket.id);
+}
+
+tl::expected<DistributedFSDescriptor, ErrorCode>
+ImmutableBucketAllocator::Allocate(const std::string& key, uint64_t size) {
+    if (!IsInitialized()) {
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    const auto layout = ComputeBucketEntryLayout(0, size, alignment_);
+    if (key.empty() || !layout || layout->aligned_size > bucket_capacity_) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+
+    std::lock_guard lock(mutex_);
+    if (key_index_.contains(key)) {
+        return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+    }
+    auto bucket_result = EnsureActiveBucketLocked(layout->aligned_size);
+    if (!bucket_result) {
+        return tl::make_unexpected(bucket_result.error());
+    }
+    BucketPtr bucket = *bucket_result;
+    return ReserveInBucketLocked(*bucket, key, size);
+}
+
+std::vector<BatchAllocateResult> ImmutableBucketAllocator::BatchAllocate(
+    const std::vector<BatchAllocateRequest>& requests) {
+    std::vector<BatchAllocateResult> results;
+    results.reserve(requests.size());
+    for (const auto& request : requests) {
+        results.push_back({request.key, {}, false, ErrorCode::OK});
+    }
+    if (!IsInitialized()) {
+        for (auto& result : results) {
+            result.error = ErrorCode::DFS_SERVICE_UNAVAILABLE;
+        }
+        return results;
+    }
+
+    std::lock_guard lock(mutex_);
+    ErrorCode failure = ErrorCode::OK;
+    size_t completed = 0;
+    for (; completed < requests.size(); ++completed) {
+        const auto& request = requests[completed];
+        const auto layout =
+            ComputeBucketEntryLayout(0, request.size, alignment_);
+        if (request.key.empty() || !layout ||
+            layout->aligned_size > bucket_capacity_) {
+            failure = ErrorCode::INVALID_PARAMS;
+            break;
+        }
+        if (key_index_.contains(request.key)) {
+            failure = ErrorCode::OBJECT_ALREADY_EXISTS;
+            break;
+        }
+        auto bucket_result = EnsureActiveBucketLocked(layout->aligned_size);
+        if (!bucket_result) {
+            failure = bucket_result.error();
+            break;
+        }
+        BucketPtr bucket = *bucket_result;
+        auto descriptor =
+            ReserveInBucketLocked(*bucket, request.key, request.size);
+        if (!descriptor) {
+            failure = descriptor.error();
+            break;
+        }
+        results[completed].descriptor = std::move(*descriptor);
+        results[completed].success = true;
+    }
+
+    if (completed == requests.size()) return results;
+    for (size_t i = completed; i > 0; --i) {
+        auto& result = results[i - 1];
+        BucketPtr bucket;
+        if (auto* entry = FindMatchingEntryLocked(result.key, result.descriptor,
+                                                  &bucket)) {
+            TombstoneLocked(result.key, *bucket, *entry);
+        }
+    }
+    for (auto& result : results) {
+        result.descriptor = {};
+        result.success = false;
+        result.error = failure;
+    }
+    return results;
+}
+
+ImmutableBucketAllocator::BucketEntry*
+ImmutableBucketAllocator::FindMatchingEntryLocked(
+    const std::string& key, const DistributedFSDescriptor& descriptor,
+    BucketPtr* out_bucket) {
+    const auto key_it = key_index_.find(key);
+    if (key_it == key_index_.end() || key_it->second != descriptor.shard_idx) {
+        return nullptr;
+    }
+    const auto bucket_it = buckets_.find(key_it->second);
+    if (bucket_it == buckets_.end()) return nullptr;
+    const auto entry_it = bucket_it->second->entries.find(key);
+    if (entry_it == bucket_it->second->entries.end()) return nullptr;
+    auto& entry = entry_it->second;
+    if (entry.state == BucketEntryState::TOMBSTONE ||
+        descriptor.file_path != BucketDataPath(bucket_it->first) ||
+        descriptor.offset != entry.layout.offset ||
+        descriptor.object_size != entry.layout.object_size ||
+        descriptor.aligned_size != entry.layout.aligned_size) {
+        return nullptr;
+    }
+    if (out_bucket) *out_bucket = bucket_it->second;
+    return &entry;
+}
+
+void ImmutableBucketAllocator::TombstoneLocked(const std::string& key,
+                                               BucketState& bucket,
+                                               BucketEntry& entry) {
+    if (entry.state == BucketEntryState::TOMBSTONE) return;
+    if (entry.state == BucketEntryState::PENDING &&
+        bucket.pending_entries > 0) {
+        --bucket.pending_entries;
+    }
+    entry.state = BucketEntryState::TOMBSTONE;
+    const auto key_it = key_index_.find(key);
+    if (key_it != key_index_.end() && key_it->second == bucket.id) {
+        key_index_.erase(key_it);
+    }
+}
+
+bool ImmutableBucketAllocator::MarkCommitted(
+    const std::string& key, const DistributedFSDescriptor& descriptor) {
+    if (!IsInitialized()) return false;
+    std::lock_guard lock(mutex_);
+    BucketPtr bucket;
+    auto* entry = FindMatchingEntryLocked(key, descriptor, &bucket);
+    if (!entry) return false;
+    if (entry->state == BucketEntryState::COMMITTED) return true;
+    if (entry->state != BucketEntryState::PENDING) return false;
+    entry->state = BucketEntryState::COMMITTED;
+    if (bucket->pending_entries > 0) --bucket->pending_entries;
+    return true;
+}
+
+void ImmutableBucketAllocator::Free(const std::string& key,
+                                    const DistributedFSDescriptor& descriptor) {
+    if (!IsInitialized()) return;
+    std::lock_guard lock(mutex_);
+    BucketPtr bucket;
+    auto* entry = FindMatchingEntryLocked(key, descriptor, &bucket);
+    if (entry) TombstoneLocked(key, *bucket, *entry);
+}
+
+void ImmutableBucketAllocator::UpdateAccess(
+    const std::string& key, const DistributedFSDescriptor& descriptor) {
+    if (!IsInitialized()) return;
+    std::lock_guard lock(mutex_);
+    BucketPtr bucket;
+    if (!FindMatchingEntryLocked(key, descriptor, &bucket)) return;
+    if (bucket->lifecycle == BucketLifecycle::SEALED) {
+        TouchLruLocked(bucket->id);
+    }
+}
+
+void ImmutableBucketAllocator::TouchLruLocked(int64_t bucket_id) {
+    const auto existing = lru_index_.find(bucket_id);
+    if (existing != lru_index_.end()) {
+        lru_.erase(existing->second);
+    }
+    lru_.push_front(bucket_id);
+    lru_index_[bucket_id] = lru_.begin();
+}
+
+uint64_t ImmutableBucketAllocator::UsedBytesLocked() const {
+    // Append-only ranges remain consumed until their whole bucket is deleted.
+    uint64_t used = 0;
+    for (const auto& [id, bucket] : buckets_) {
+        (void)id;
+        const uint64_t contribution =
+            bucket->lifecycle == BucketLifecycle::EVICTING
+                ? bucket->capacity
+                : bucket->append_offset;
+        if (contribution > std::numeric_limits<uint64_t>::max() - used) {
+            return std::numeric_limits<uint64_t>::max();
+        }
+        used += contribution;
+    }
+    return used;
+}
+
+uint64_t ImmutableBucketAllocator::GetUsedBytes() const {
+    std::lock_guard lock(mutex_);
+    return UsedBytesLocked();
+}
+
+uint64_t ImmutableBucketAllocator::GetTotalCapacity() const {
+    return bucket_capacity_ * static_cast<uint64_t>(max_bucket_count_);
+}
+
+ImmutableBucketAllocator::PendingEviction
+ImmutableBucketAllocator::PrepareEvictionLocked(bool force_one) {
+    PendingEviction pending;
+    if (!eviction_enabled_) return pending;
+    const uint64_t capacity = GetTotalCapacity();
+    const uint64_t used = UsedBytesLocked();
+    const double usage = capacity == 0 ? 0.0
+                                       : static_cast<double>(used) /
+                                             static_cast<double>(capacity);
+    if (!force_one) {
+        if (!eviction_active_ && usage < eviction_high_watermark_) {
+            return pending;
+        }
+        eviction_active_ = usage > eviction_low_watermark_;
+        if (!eviction_active_) return pending;
+    }
+
+    for (auto it = lru_.rbegin(); it != lru_.rend(); ++it) {
+        const auto bucket_it = buckets_.find(*it);
+        if (bucket_it == buckets_.end()) continue;
+        auto& bucket = *bucket_it->second;
+        if (bucket.id == active_bucket_id_ ||
+            bucket.lifecycle != BucketLifecycle::SEALED ||
+            bucket.pending_entries != 0) {
+            continue;
+        }
+        bucket.lifecycle = BucketLifecycle::FROZEN;
+        const auto lru_it = lru_index_.find(bucket.id);
+        if (lru_it != lru_index_.end()) {
+            lru_.erase(lru_it->second);
+            lru_index_.erase(lru_it);
+        }
+        pending.owner_ = this;
+        pending.bucket_id_ = bucket.id;
+        pending.identity_ = bucket_it->second;
+        for (const auto& [key, entry] : bucket.entries) {
+            if (entry.state != BucketEntryState::COMMITTED) continue;
+            auto layout = RebuildBucketEntryLayout(
+                entry.layout.offset, entry.layout.object_size, alignment_);
+            if (!layout || layout->aligned_size != entry.layout.aligned_size ||
+                layout->end() > bucket.capacity) {
+                bucket.lifecycle = BucketLifecycle::SEALED;
+                TouchLruLocked(bucket.id);
+                pending.owner_ = nullptr;
+                pending.bucket_id_ = -1;
+                pending.identity_.reset();
+                pending.candidates_.clear();
+                return pending;
+            }
+            auto descriptor = MakeBucketDescriptor(BucketDataPath(bucket.id),
+                                                   *layout, bucket.id);
+            pending.candidates_.push_back({key, static_cast<int>(bucket.id),
+                                           entry.layout.offset,
+                                           std::move(descriptor)});
+        }
+        return pending;
+    }
+    return pending;
+}
+
+ImmutableBucketAllocator::PendingEviction
+ImmutableBucketAllocator::PrepareEviction() {
+    std::lock_guard lock(mutex_);
+    return PrepareEvictionLocked(false);
+}
+
+ImmutableBucketAllocator::PendingEviction
+ImmutableBucketAllocator::PrepareEvictionForAllocationFailure() {
+    std::lock_guard lock(mutex_);
+    return PrepareEvictionLocked(true);
+}
+
+void ImmutableBucketAllocator::AbortEvictionLocked(PendingEviction& pending,
+                                                   bool warm) {
+    std::lock_guard lock(mutex_);
+    if (pending.owner_ != this) return;
+    const auto bucket_it = buckets_.find(pending.bucket_id_);
+    if (bucket_it != buckets_.end() &&
+        bucket_it->second.get() == pending.identity_.get() &&
+        bucket_it->second->lifecycle == BucketLifecycle::FROZEN) {
+        bucket_it->second->lifecycle = BucketLifecycle::SEALED;
+        if (warm) {
+            TouchLruLocked(bucket_it->first);
+        } else {
+            lru_.push_back(bucket_it->first);
+            lru_index_[bucket_it->first] = std::prev(lru_.end());
+        }
+    }
+    pending.owner_ = nullptr;
+    pending.bucket_id_ = -1;
+    pending.identity_.reset();
+    pending.candidates_.clear();
+}
+
+void ImmutableBucketAllocator::AbortEviction(PendingEviction&& pending) {
+    AbortEvictionLocked(pending, true);
+}
+
+tl::expected<ImmutableBucketAllocator::EvictedBucket, ErrorCode>
+ImmutableBucketAllocator::CommitEvictionLogical(PendingEviction&& pending) {
+    std::lock_guard lock(mutex_);
+    if (pending.owner_ != this) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const auto it = buckets_.find(pending.bucket_id_);
+    if (it == buckets_.end() || it->second.get() != pending.identity_.get() ||
+        it->second->lifecycle != BucketLifecycle::FROZEN ||
+        it->second->pending_entries != 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    const BucketPtr bucket = it->second;
+    for (const auto& [key, entry] : bucket->entries) {
+        (void)entry;
+        const auto indexed = key_index_.find(key);
+        if (indexed != key_index_.end() && indexed->second == bucket->id) {
+            key_index_.erase(indexed);
+        }
+    }
+    bucket->lifecycle = BucketLifecycle::EVICTING;
+    EvictedBucket evicted;
+    evicted.bucket_id_ = pending.bucket_id_;
+    evicted.identity_ = pending.identity_;
+    pending.owner_ = nullptr;
+    return evicted;
+}
+
+tl::expected<void, ErrorCode> ImmutableBucketAllocator::DeleteEvictedBucket(
+    EvictedBucket&& bucket) {
+    if (bucket.bucket_id_ < 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto deleted = fs_adapter_->DeleteFile(BucketDataPath(bucket.bucket_id_));
+    if (!deleted && deleted.error() != ErrorCode::FILE_NOT_FOUND) {
+        std::lock_guard lock(mutex_);
+        failed_deletions_.insert(bucket.bucket_id_);
+        return tl::make_unexpected(deleted.error());
+    }
+
+    std::lock_guard lock(mutex_);
+    const auto current = buckets_.find(bucket.bucket_id_);
+    if (current != buckets_.end() && current->second == bucket.identity_) {
+        current->second->lifecycle = BucketLifecycle::RETIRED;
+        buckets_.erase(current);
+    }
+    failed_deletions_.erase(bucket.bucket_id_);
+    return {};
+}
+
+size_t ImmutableBucketAllocator::RetryFailedEvictions() {
+    std::vector<std::pair<int64_t, BucketPtr>> retries;
+    {
+        std::lock_guard lock(mutex_);
+        retries.reserve(failed_deletions_.size());
+        for (const int64_t id : failed_deletions_) {
+            const auto it = buckets_.find(id);
+            if (it != buckets_.end() &&
+                it->second->lifecycle == BucketLifecycle::EVICTING) {
+                retries.emplace_back(id, it->second);
+            }
+        }
+    }
+
+    size_t completed = 0;
+    for (const auto& [id, bucket] : retries) {
+        auto deleted = fs_adapter_->DeleteFile(BucketDataPath(id));
+        if (!deleted && deleted.error() != ErrorCode::FILE_NOT_FOUND) continue;
+        std::lock_guard lock(mutex_);
+        const auto current = buckets_.find(id);
+        if (current == buckets_.end() || current->second != bucket ||
+            bucket->lifecycle != BucketLifecycle::EVICTING) {
+            continue;
+        }
+        bucket->lifecycle = BucketLifecycle::RETIRED;
+        buckets_.erase(current);
+        failed_deletions_.erase(id);
+        ++completed;
+    }
+    return completed;
+}
+
+size_t ImmutableBucketAllocator::GetBucketCount() const {
+    std::lock_guard lock(mutex_);
+    return buckets_.size();
+}
+
+std::optional<int64_t> ImmutableBucketAllocator::GetBucketIdForKey(
+    const std::string& key) const {
+    std::lock_guard lock(mutex_);
+    const auto it = key_index_.find(key);
+    if (it == key_index_.end()) return std::nullopt;
+    return it->second;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/storage/distributed/oss_adapter.cpp b/mooncake-store/src/storage/distributed/oss_adapter.cpp
new file mode 100644
index 0000000000..b16c8df3a0
--- /dev/null
+++ b/mooncake-store/src/storage/distributed/oss_adapter.cpp
@@ -0,0 +1,923 @@
+#include "storage/distributed/oss_adapter.h"
+
+#include <curl/curl.h>
+#include <openssl/hmac.h>
+#include <openssl/sha.h>
+
+#include <boost/algorithm/string.hpp>
+
+#include <algorithm>
+#include <array>
+#include <cctype>
+#include <chrono>
+#include <cstdio>
+#include <cstdint>
+#include <ctime>
+#include <cstring>
+#include <limits>
+#include <memory>
+#include <mutex>
+#include <string_view>
+#include <thread>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "config/oss_adapter_config.h"
+
+namespace mooncake {
+namespace {
+
+std::once_flag curl_init_once;
+
+std::string UriEncode(std::string_view value, bool preserve_slash = false) {
+    static constexpr char hex[] = "0123456789ABCDEF";
+    std::string result;
+    result.reserve(value.size() * 3);
+    for (unsigned char c : value) {
+        if (std::isalnum(c) || c == '-' || c == '_' || c == '.' || c == '~' ||
+            (preserve_slash && c == '/')) {
+            result.push_back(static_cast<char>(c));
+        } else {
+            result.push_back('%');
+            result.push_back(hex[c >> 4]);
+            result.push_back(hex[c & 0x0f]);
+        }
+    }
+    return result;
+}
+
+int FromHex(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return -1;
+}
+
+std::string UriDecode(std::string_view value) {
+    std::string result;
+    result.reserve(value.size());
+    for (size_t i = 0; i < value.size(); ++i) {
+        if (value[i] == '%' && i + 2 < value.size()) {
+            int hi = FromHex(value[i + 1]);
+            int lo = FromHex(value[i + 2]);
+            if (hi >= 0 && lo >= 0) {
+                result.push_back(static_cast<char>((hi << 4) | lo));
+                i += 2;
+                continue;
+            }
+        }
+        result.push_back(value[i]);
+    }
+    return result;
+}
+
+std::string XmlDecode(std::string value) {
+    const std::array<std::pair<std::string_view, std::string_view>, 5>
+        entities = {{{"&amp;", "&"},
+                     {"&lt;", "<"},
+                     {"&gt;", ">"},
+                     {"&quot;", "\""},
+                     {"&apos;", "'"}}};
+    for (const auto& [encoded, decoded] : entities) {
+        size_t pos = 0;
+        while ((pos = value.find(encoded, pos)) != std::string::npos) {
+            value.replace(pos, encoded.size(), decoded);
+            pos += decoded.size();
+        }
+    }
+    return value;
+}
+
+std::string XmlValue(std::string_view xml, std::string_view tag,
+                     size_t start = 0) {
+    const std::string open = "<" + std::string(tag) + ">";
+    const std::string close = "</" + std::string(tag) + ">";
+    size_t begin = xml.find(open, start);
+    if (begin == std::string_view::npos) return {};
+    begin += open.size();
+    size_t end = xml.find(close, begin);
+    if (end == std::string_view::npos) return {};
+    return XmlDecode(std::string(xml.substr(begin, end - begin)));
+}
+
+std::string Hex(const unsigned char* data, size_t size) {
+    static constexpr char hex[] = "0123456789abcdef";
+    std::string result(size * 2, '\0');
+    for (size_t i = 0; i < size; ++i) {
+        result[2 * i] = hex[data[i] >> 4];
+        result[2 * i + 1] = hex[data[i] & 0x0f];
+    }
+    return result;
+}
+
+std::vector<unsigned char> HmacSha256(const void* key, size_t key_size,
+                                      std::string_view data) {
+    std::vector<unsigned char> result(EVP_MAX_MD_SIZE);
+    unsigned int result_size = 0;
+    HMAC(EVP_sha256(), key, static_cast<int>(key_size),
+         reinterpret_cast<const unsigned char*>(data.data()), data.size(),
+         result.data(), &result_size);
+    result.resize(result_size);
+    return result;
+}
+
+std::string Sha256Hex(std::string_view data) {
+    unsigned char hash[SHA256_DIGEST_LENGTH];
+    SHA256(reinterpret_cast<const unsigned char*>(data.data()), data.size(),
+           hash);
+    return Hex(hash, sizeof(hash));
+}
+
+std::pair<std::string, std::string> OssTimestamp() {
+    const auto now = std::chrono::system_clock::now();
+    const std::time_t value = std::chrono::system_clock::to_time_t(now);
+    std::tm tm{};
+    gmtime_r(&value, &tm);
+    char timestamp[17];
+    char date[9];
+    std::strftime(timestamp, sizeof(timestamp), "%Y%m%dT%H%M%SZ", &tm);
+    std::strftime(date, sizeof(date), "%Y%m%d", &tm);
+    return {timestamp, date};
+}
+
+std::string CanonicalQuery(const std::map<std::string, std::string>& query) {
+    std::map<std::string, std::string> encoded;
+    for (const auto& [name, value] : query) {
+        encoded.emplace(UriEncode(name), UriEncode(value));
+    }
+    std::string result;
+    for (const auto& [name, value] : encoded) {
+        if (!result.empty()) result.push_back('&');
+        result += name;
+        if (!value.empty()) result += "=" + value;
+    }
+    return result;
+}
+
+struct DownloadContext {
+    std::string* body = nullptr;
+    char* buffer = nullptr;
+    size_t capacity = 0;
+    size_t transferred = 0;
+    bool overflow = false;
+};
+
+size_t DownloadCallback(char* data, size_t size, size_t count,
+                        void* user_data) {
+    auto* context = static_cast<DownloadContext*>(user_data);
+    const size_t bytes = size * count;
+    if (context->buffer) {
+        if (bytes > context->capacity - context->transferred) {
+            context->overflow = true;
+            return 0;
+        }
+        std::memcpy(context->buffer + context->transferred, data, bytes);
+    } else {
+        context->body->append(data, bytes);
+    }
+    context->transferred += bytes;
+    return bytes;
+}
+
+size_t HeaderCallback(char* data, size_t size, size_t count, void* user_data) {
+    auto* headers = static_cast<std::map<std::string, std::string>*>(user_data);
+    const size_t length = size * count;
+    std::string_view line(data, length);
+    if (line.starts_with("HTTP/")) {
+        headers->clear();
+        return length;
+    }
+    const size_t colon = line.find(':');
+    if (colon != std::string_view::npos) {
+        std::string name(line.substr(0, colon));
+        std::string value(line.substr(colon + 1));
+        boost::algorithm::to_lower(name);
+        boost::algorithm::trim(value);
+        (*headers)[std::move(name)] = std::move(value);
+    }
+    return length;
+}
+
+tl::expected<size_t, ErrorCode> GetIovecSize(const iovec* iov, int iovcnt) {
+    if (iovcnt < 0 || (!iov && iovcnt > 0))
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    size_t total = 0;
+    for (int i = 0; i < iovcnt; ++i) {
+        if ((!iov[i].iov_base && iov[i].iov_len > 0) ||
+            iov[i].iov_len > std::numeric_limits<size_t>::max() - total) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+        total += iov[i].iov_len;
+    }
+    return total;
+}
+
+struct IovecUploadContext {
+    const iovec* iov = nullptr;
+    int iovcnt = 0;
+    int index = 0;
+    size_t offset = 0;
+};
+
+size_t IovecUploadCallback(char* buffer, size_t size, size_t count,
+                           void* user_data) {
+    auto* context = static_cast<IovecUploadContext*>(user_data);
+    const size_t capacity = size * count;
+    size_t copied = 0;
+    while (copied < capacity && context->index < context->iovcnt) {
+        const iovec& current = context->iov[context->index];
+        const size_t available = current.iov_len - context->offset;
+        const size_t chunk = std::min(capacity - copied, available);
+        if (chunk > 0) {
+            std::memcpy(
+                buffer + copied,
+                static_cast<const char*>(current.iov_base) + context->offset,
+                chunk);
+        }
+        copied += chunk;
+        context->offset += chunk;
+        if (context->offset == current.iov_len) {
+            ++context->index;
+            context->offset = 0;
+        }
+    }
+    return copied;
+}
+
+int IovecSeekCallback(void* user_data, curl_off_t offset, int origin) {
+    if (origin != SEEK_SET || offset != 0) return CURL_SEEKFUNC_CANTSEEK;
+    auto* context = static_cast<IovecUploadContext*>(user_data);
+    context->index = 0;
+    context->offset = 0;
+    return CURL_SEEKFUNC_OK;
+}
+
+bool IsSuccess(long status) { return status >= 200 && status < 300; }
+
+}  // namespace
+
+struct OssObjectStorageAdapter::BatchRequest {
+    bool upload = false;
+    std::string logical_key;
+    const iovec* upload_iov = nullptr;
+    int upload_iovcnt = 0;
+    void* download_buffer = nullptr;
+    size_t size = 0;
+};
+
+struct OssObjectStorageAdapter::RequestContext {
+    RequestContext() = default;
+    RequestContext(const RequestContext&) = delete;
+    RequestContext& operator=(const RequestContext&) = delete;
+    RequestContext(RequestContext&&) = delete;
+    RequestContext& operator=(RequestContext&&) = delete;
+
+    ~RequestContext() {
+        if (curl) {
+            if (multi) curl_multi_remove_handle(multi, curl);
+            curl_easy_cleanup(curl);
+        }
+        curl_slist_free_all(headers);
+    }
+
+    size_t index = 0;
+    bool upload = false;
+    size_t expected_size = 0;
+    CURL* curl = nullptr;
+    // Set only after a successful add. The owning batch outlives this context.
+    CURLM* multi = nullptr;
+    curl_slist* headers = nullptr;
+    std::string error_body;
+    IovecUploadContext upload_context;
+    DownloadContext download_context;
+};
+
+OssObjectStorageAdapter::OssObjectStorageAdapter(std::string key_prefix)
+    : key_prefix_(std::move(key_prefix)) {
+    const size_t first = key_prefix_.find_first_not_of('/');
+    if (first == std::string::npos) {
+        key_prefix_.clear();
+        return;
+    }
+    key_prefix_.erase(0, first);
+    while (!key_prefix_.empty() && key_prefix_.back() == '/')
+        key_prefix_.pop_back();
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::Init() {
+    auto config = OssAdapterConfig::FromEnvironment();
+    if (!config.has_value()) {
+        return tl::make_unexpected(config.error());
+    }
+    endpoint_ = std::move(config->endpoint);
+    bucket_ = std::move(config->bucket);
+    region_ = std::move(config->region);
+    access_key_id_ = std::move(config->access_key_id);
+    access_key_secret_ = std::move(config->access_key_secret);
+    security_token_ = std::move(config->security_token);
+    path_style_ = config->path_style;
+    anonymous_ = config->anonymous;
+    max_connections_ = config->max_connections;
+    receive_buffer_size_ = config->receive_buffer_size;
+    upload_buffer_size_ = config->upload_buffer_size;
+
+    std::call_once(curl_init_once,
+                   [] { curl_global_init(CURL_GLOBAL_DEFAULT); });
+    initialized_ = true;
+    LOG(INFO) << "OSS adapter initialized: endpoint=" << endpoint_
+              << ", bucket=" << bucket_ << ", region=" << region_
+              << ", key_prefix=" << key_prefix_
+              << ", max_connections=" << max_connections_
+              << ", receive_buffer_size=" << receive_buffer_size_
+              << ", upload_buffer_size=" << upload_buffer_size_;
+    return {};
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::CheckHealth() {
+    const std::string probe_key =
+        ".mooncake_health_probe_" + UuidToString(generate_uuid());
+    const std::string probe_data = "health_check";
+
+    auto write_result = Put(
+        probe_key, std::span<const char>(probe_data.data(), probe_data.size()));
+    if (!write_result) {
+        LOG(ERROR) << "OSS health check failed to write probe: "
+                   << static_cast<int>(write_result.error());
+        return write_result;
+    }
+
+    auto cleanup_probe = [&] {
+        auto delete_result = Delete(probe_key);
+        if (!delete_result) {
+            LOG(WARNING) << "Failed to delete OSS health-check probe: "
+                         << static_cast<int>(delete_result.error());
+        }
+    };
+
+    std::string read_buffer(probe_data.size(), '\0');
+    auto read_result = Get(probe_key, read_buffer.data(), read_buffer.size());
+    if (!read_result || *read_result != probe_data.size() ||
+        read_buffer != probe_data) {
+        LOG(ERROR) << "OSS health check failed to read back probe";
+        cleanup_probe();
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+
+    cleanup_probe();
+    LOG(INFO) << "OSS health check passed";
+    return {};
+}
+
+std::string OssObjectStorageAdapter::PhysicalPrefix() const {
+    return key_prefix_.empty() ? std::string() : key_prefix_ + "/";
+}
+
+std::string OssObjectStorageAdapter::LogicalToPhysicalKey(
+    const std::string& logical_key) const {
+    return PhysicalPrefix() + UriEncode(logical_key);
+}
+
+tl::expected<std::string, ErrorCode>
+OssObjectStorageAdapter::PhysicalToLogicalKey(
+    const std::string& physical_key) const {
+    const std::string prefix = PhysicalPrefix();
+    if (physical_key.rfind(prefix, 0) != 0) {
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    }
+    return UriDecode(physical_key.substr(prefix.size()));
+}
+
+std::string OssObjectStorageAdapter::BuildUrl(
+    const std::string& physical_key,
+    const std::map<std::string, std::string>& query) const {
+    std::string base = endpoint_;
+    if (path_style_) {
+        base += "/" + UriEncode(bucket_);
+    } else {
+        const size_t scheme = base.find("://");
+        if (scheme == std::string::npos) {
+            base = bucket_ + "." + base;
+        } else {
+            base.insert(scheme + 3, bucket_ + ".");
+        }
+    }
+    base += "/" + UriEncode(physical_key, true);
+    const auto canonical_query = CanonicalQuery(query);
+    if (!canonical_query.empty()) base += "?" + canonical_query;
+    return base;
+}
+
+std::string OssObjectStorageAdapter::BuildAuthorization(
+    const std::string& method, const std::string& physical_key,
+    const std::map<std::string, std::string>& query,
+    const std::string& timestamp,
+    const std::map<std::string, std::string>& oss_headers) const {
+    const std::string date = timestamp.substr(0, 8);
+    const std::string canonical_uri =
+        UriEncode("/" + bucket_ + "/" + physical_key, true);
+    std::string canonical_headers;
+    for (const auto& [name, value] : oss_headers) {
+        canonical_headers +=
+            name + ":" + boost::algorithm::trim_copy(value) + "\n";
+    }
+    // OSS V4 signs Content-Type, Content-MD5, and x-oss-* headers by
+    // default. AdditionalHeaders is therefore empty because this request
+    // does not sign any optional, non-default headers.
+    const std::string canonical_request =
+        method + "\n" + canonical_uri + "\n" + CanonicalQuery(query) + "\n" +
+        canonical_headers + "\n\nUNSIGNED-PAYLOAD";
+    const std::string scope = date + "/" + region_ + "/oss/aliyun_v4_request";
+    const std::string string_to_sign = "OSS4-HMAC-SHA256\n" + timestamp + "\n" +
+                                       scope + "\n" +
+                                       Sha256Hex(canonical_request);
+
+    const std::string secret = "aliyun_v4" + access_key_secret_;
+    auto date_key = HmacSha256(secret.data(), secret.size(), date);
+    auto region_key = HmacSha256(date_key.data(), date_key.size(), region_);
+    auto service_key = HmacSha256(region_key.data(), region_key.size(), "oss");
+    auto signing_key =
+        HmacSha256(service_key.data(), service_key.size(), "aliyun_v4_request");
+    auto signature =
+        HmacSha256(signing_key.data(), signing_key.size(), string_to_sign);
+    return "OSS4-HMAC-SHA256 Credential=" + access_key_id_ + "/" + scope +
+           ",Signature=" + Hex(signature.data(), signature.size());
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::PrepareRequest(
+    RequestContext& context, const std::string& method,
+    const std::string& physical_key,
+    const std::map<std::string, std::string>& query, const char* body,
+    size_t body_size, const std::string& range, const iovec* upload_iov,
+    int upload_iovcnt, void* download_buffer, size_t download_capacity) const {
+    CURL* curl = context.curl;
+    if (!curl) return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    context.upload = method == "PUT";
+    context.download_context = {&context.error_body,
+                                static_cast<char*>(download_buffer),
+                                download_capacity};
+    bool headers_ok = true;
+    auto add_header = [&](const std::string& header) {
+        auto* appended = curl_slist_append(context.headers, header.c_str());
+        if (appended)
+            context.headers = appended;
+        else
+            headers_ok = false;
+    };
+
+    const std::string timestamp = OssTimestamp().first;
+    std::map<std::string, std::string> oss_headers{
+        {"x-oss-content-sha256", "UNSIGNED-PAYLOAD"},
+        {"x-oss-date", timestamp},
+    };
+    if (!security_token_.empty())
+        oss_headers["x-oss-security-token"] = security_token_;
+    if (!range.empty()) oss_headers["x-oss-range-behavior"] = "standard";
+    for (const auto& [name, value] : oss_headers) {
+        add_header(name + ": " + value);
+    }
+    if (!anonymous_)
+        add_header("Authorization: " + BuildAuthorization(method, physical_key,
+                                                          query, timestamp,
+                                                          oss_headers));
+    add_header("Expect:");
+    add_header("Content-Type:");
+    if (!range.empty()) add_header("Range: " + range);
+    if (!headers_ok)
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+
+    const std::string url = BuildUrl(physical_key, query);
+    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, method.c_str());
+    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, context.headers);
+    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, DownloadCallback);
+    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &context.download_context);
+    curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
+    curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 5000L);
+    curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 120000L);
+    if (method == "HEAD") curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
+    if (method == "PUT") {
+        if (upload_iov) {
+            context.upload_context = {upload_iov, upload_iovcnt};
+            curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
+            curl_easy_setopt(curl, CURLOPT_READFUNCTION, IovecUploadCallback);
+            curl_easy_setopt(curl, CURLOPT_READDATA, &context.upload_context);
+            curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, IovecSeekCallback);
+            curl_easy_setopt(curl, CURLOPT_SEEKDATA, &context.upload_context);
+            curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE,
+                             static_cast<curl_off_t>(body_size));
+#if LIBCURL_VERSION_NUM >= 0x073e00  // Added in libcurl 7.62.0.
+            curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE,
+                             upload_buffer_size_);
+#endif
+        } else {
+            curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body ? body : "");
+            curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE,
+                             static_cast<curl_off_t>(body_size));
+        }
+    }
+    return {};
+}
+
+tl::expected<OssObjectStorageAdapter::Response, ErrorCode>
+OssObjectStorageAdapter::Request(
+    const std::string& method, const std::string& physical_key,
+    const std::map<std::string, std::string>& query, const char* body,
+    size_t body_size, const std::string& range, const iovec* upload_iov,
+    int upload_iovcnt, void* download_buffer, size_t download_capacity) const {
+    if (!initialized_) {
+        return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+    }
+    RequestContext context;
+    context.curl = curl_easy_init();
+    auto prepared = PrepareRequest(context, method, physical_key, query, body,
+                                   body_size, range, upload_iov, upload_iovcnt,
+                                   download_buffer, download_capacity);
+    if (!prepared) return tl::make_unexpected(prepared.error());
+    Response response;
+    curl_easy_setopt(context.curl, CURLOPT_HEADERFUNCTION, HeaderCallback);
+    curl_easy_setopt(context.curl, CURLOPT_HEADERDATA, &response.headers);
+
+    const CURLcode result = curl_easy_perform(context.curl);
+    curl_easy_getinfo(context.curl, CURLINFO_RESPONSE_CODE, &response.status);
+    response.transferred = context.download_context.transferred;
+    response.body = std::move(context.error_body);
+    // A 404 error body may exceed the caller's object buffer. Preserve the
+    // HTTP error only for this local abort, not for other transfer failures.
+    const bool missing_object = method == "GET" && response.status == 404 &&
+                                result == CURLE_WRITE_ERROR &&
+                                context.download_context.overflow;
+    if (result != CURLE_OK && !missing_object) {
+        LOG(ERROR) << "OSS " << method
+                   << " request failed: " << curl_easy_strerror(result);
+        return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    if (!IsSuccess(response.status) && response.status != 404) {
+        LOG(ERROR) << "OSS " << method << " returned HTTP " << response.status
+                   << ": " << response.body.substr(0, 512);
+    }
+    return response;
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::Put(
+    const std::string& logical_key, std::span<const char> data) {
+    auto response = Request("PUT", LogicalToPhysicalKey(logical_key), {},
+                            data.data(), data.size());
+    if (!response) return tl::make_unexpected(response.error());
+    if (!IsSuccess(response->status))
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return {};
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::PutV(
+    const std::string& logical_key, const iovec* iov, int iovcnt) {
+    auto total = GetIovecSize(iov, iovcnt);
+    if (!total) return tl::make_unexpected(total.error());
+    if (*total == 0) return Put(logical_key, {});
+    auto response = Request("PUT", LogicalToPhysicalKey(logical_key), {},
+                            nullptr, *total, "", iov, iovcnt);
+    if (!response) return tl::make_unexpected(response.error());
+    if (!IsSuccess(response->status))
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return {};
+}
+
+std::vector<tl::expected<size_t, ErrorCode>>
+OssObjectStorageAdapter::RequestBatch(
+    const std::vector<BatchRequest>& requests) {
+    std::vector<tl::expected<size_t, ErrorCode>> results;
+    results.reserve(requests.size());
+    for (size_t i = 0; i < requests.size(); ++i) {
+        results.emplace_back(
+            tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE));
+    }
+    if (requests.empty()) return results;
+    if (!initialized_) {
+        for (auto& result : results)
+            result = tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        return results;
+    }
+
+    // Each batch owns its pool; contexts must be destroyed before the pool.
+    std::unique_ptr<CURLM, decltype(&curl_multi_cleanup)> multi(
+        curl_multi_init(), &curl_multi_cleanup);
+    if (!multi) {
+        LOG(ERROR) << "Failed to initialize OSS batch curl multi handle";
+        return results;
+    }
+    if (curl_multi_setopt(multi.get(), CURLMOPT_MAX_TOTAL_CONNECTIONS,
+                          max_connections_) != CURLM_OK ||
+        curl_multi_setopt(multi.get(), CURLMOPT_MAX_HOST_CONNECTIONS,
+                          max_connections_) != CURLM_OK ||
+        curl_multi_setopt(multi.get(), CURLMOPT_MAXCONNECTS,
+                          max_connections_) != CURLM_OK) {
+        LOG(ERROR) << "Failed to configure OSS batch curl multi handle";
+        return results;
+    }
+    std::vector<RequestContext> contexts(requests.size());
+
+    for (size_t i = 0; i < requests.size(); ++i) {
+        const auto& request = requests[i];
+        auto& context = contexts[i];
+        context.curl = curl_easy_init();
+        context.index = i;
+        context.expected_size = request.size;
+        const std::string range =
+            request.upload || request.size == 0
+                ? ""
+                : "bytes=0-" + std::to_string(request.size - 1);
+        auto prepared = PrepareRequest(
+            context, request.upload ? "PUT" : "GET",
+            LogicalToPhysicalKey(request.logical_key), {}, nullptr,
+            request.upload ? request.size : 0, range, request.upload_iov,
+            request.upload_iovcnt, request.download_buffer,
+            request.upload ? 0 : request.size);
+        if (!prepared) return results;
+        curl_easy_setopt(context.curl, CURLOPT_BUFFERSIZE,
+                         receive_buffer_size_);
+        curl_easy_setopt(context.curl, CURLOPT_PRIVATE, &context);
+    }
+
+    size_t next = 0;
+    size_t active = 0;
+    // Wait outside CURLM so queued requests retain their full timeout.
+    auto admit = [&]() {
+        while (next < contexts.size() &&
+               active < static_cast<size_t>(max_connections_)) {
+            auto& context = contexts[next];
+            auto result = curl_multi_add_handle(multi.get(), context.curl);
+            if (result != CURLM_OK) return result;
+            context.multi = multi.get();
+            ++next;
+            ++active;
+        }
+        return CURLM_OK;
+    };
+    CURLMcode multi_result = admit();
+    while (multi_result == CURLM_OK && active > 0) {
+        int running = 0;
+        multi_result = curl_multi_perform(multi.get(), &running);
+        if (multi_result != CURLM_OK) break;
+        bool completed = false;
+        int remaining = 0;
+        while (CURLMsg* message =
+                   curl_multi_info_read(multi.get(), &remaining)) {
+            if (message->msg != CURLMSG_DONE) continue;
+            RequestContext* context = nullptr;
+            curl_easy_getinfo(message->easy_handle, CURLINFO_PRIVATE, &context);
+            if (!context) continue;
+            long status = 0;
+            curl_easy_getinfo(message->easy_handle, CURLINFO_RESPONSE_CODE,
+                              &status);
+            if (!context->upload && status == 404 &&
+                (message->data.result == CURLE_OK ||
+                 (message->data.result == CURLE_WRITE_ERROR &&
+                  context->download_context.overflow))) {
+                results[context->index] =
+                    tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+            } else if (message->data.result != CURLE_OK) {
+                LOG(ERROR) << "OSS batch " << (context->upload ? "PUT" : "GET")
+                           << " failed: "
+                           << curl_easy_strerror(message->data.result);
+                results[context->index] =
+                    tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+            } else if (context->upload && IsSuccess(status)) {
+                results[context->index] = context->expected_size;
+            } else if (!context->upload && status == 206 &&
+                       context->download_context.transferred ==
+                           context->expected_size) {
+                results[context->index] = context->download_context.transferred;
+            } else {
+                LOG(ERROR) << "OSS batch " << (context->upload ? "PUT" : "GET")
+                           << " returned HTTP " << status;
+                results[context->index] = tl::make_unexpected(
+                    context->upload ? ErrorCode::FILE_WRITE_FAIL
+                                    : ErrorCode::FILE_READ_FAIL);
+            }
+            curl_multi_remove_handle(multi.get(), context->curl);
+            context->multi = nullptr;
+            --active;
+            completed = true;
+        }
+        multi_result = admit();
+        if (multi_result != CURLM_OK || active == 0) break;
+        if (completed) continue;
+        int ready = 0;
+        const auto wait_start = std::chrono::steady_clock::now();
+        multi_result = curl_multi_wait(multi.get(), nullptr, 0, 1000, &ready);
+        if (multi_result == CURLM_OK && ready == 0) {
+            // With no sockets, curl_multi_wait can return immediately. Avoid
+            // spinning, but do not delay a timer that needs immediate service.
+            long timeout_ms = -1;
+            curl_multi_timeout(multi.get(), &timeout_ms);
+            if (timeout_ms != 0) {
+                std::this_thread::sleep_until(wait_start +
+                                              std::chrono::milliseconds(1));
+            }
+        }
+    }
+    if (multi_result != CURLM_OK) {
+        LOG(ERROR) << "OSS batch request failed: "
+                   << curl_multi_strerror(multi_result);
+    }
+
+    return results;
+}
+
+std::vector<tl::expected<void, ErrorCode>> OssObjectStorageAdapter::PutBatch(
+    const std::vector<ObjectPutRequest>& requests) {
+    std::vector<tl::expected<void, ErrorCode>> results;
+    results.reserve(requests.size());
+    for (size_t i = 0; i < requests.size(); ++i)
+        results.emplace_back(tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+
+    std::vector<BatchRequest> batch;
+    std::vector<size_t> mapping;
+    batch.reserve(requests.size());
+    mapping.reserve(requests.size());
+    for (size_t i = 0; i < requests.size(); ++i) {
+        const auto& request = requests[i];
+        auto total = GetIovecSize(request.iov, request.iovcnt);
+        if (!total) continue;
+        batch.push_back({true, request.logical_key, request.iov, request.iovcnt,
+                         nullptr, *total});
+        mapping.push_back(i);
+    }
+    auto batch_results = RequestBatch(batch);
+    for (size_t i = 0; i < batch_results.size(); ++i) {
+        if (batch_results[i])
+            results[mapping[i]] = {};
+        else
+            results[mapping[i]] = tl::make_unexpected(batch_results[i].error());
+    }
+    return results;
+}
+
+std::vector<tl::expected<size_t, ErrorCode>> OssObjectStorageAdapter::GetBatch(
+    const std::vector<ObjectGetRequest>& requests) {
+    std::vector<tl::expected<size_t, ErrorCode>> results;
+    results.reserve(requests.size());
+    for (size_t i = 0; i < requests.size(); ++i)
+        results.emplace_back(tl::make_unexpected(ErrorCode::INVALID_PARAMS));
+
+    std::vector<BatchRequest> batch;
+    std::vector<size_t> mapping;
+    batch.reserve(requests.size());
+    mapping.reserve(requests.size());
+    for (size_t i = 0; i < requests.size(); ++i) {
+        const auto& request = requests[i];
+        if (request.size == 0) {
+            results[i] = size_t{0};
+            continue;
+        }
+        if (!request.buffer) continue;
+        batch.push_back({false, request.logical_key, nullptr, 0, request.buffer,
+                         request.size});
+        mapping.push_back(i);
+    }
+    auto batch_results = RequestBatch(batch);
+    for (size_t i = 0; i < batch_results.size(); ++i)
+        results[mapping[i]] = std::move(batch_results[i]);
+    return results;
+}
+
+tl::expected<size_t, ErrorCode> OssObjectStorageAdapter::Get(
+    const std::string& logical_key, void* buf, size_t len) {
+    return GetRange(logical_key, buf, len, 0);
+}
+
+tl::expected<size_t, ErrorCode> OssObjectStorageAdapter::GetRange(
+    const std::string& logical_key, void* buf, size_t len, off_t offset) {
+    if (offset < 0) return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    if (len == 0) return 0;
+    if (!buf) return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    const uint64_t first = static_cast<uint64_t>(offset);
+    if (len - 1 > std::numeric_limits<uint64_t>::max() - first)
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    const std::string range = "bytes=" + std::to_string(first) + "-" +
+                              std::to_string(first + len - 1);
+    auto response = Request("GET", LogicalToPhysicalKey(logical_key), {},
+                            nullptr, 0, range, nullptr, 0, buf, len);
+    if (!response) return tl::make_unexpected(response.error());
+    if (response->status == 404)
+        return tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+    if (response->status != 206 || response->transferred != len)
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    return len;
+}
+
+tl::expected<size_t, ErrorCode> OssObjectStorageAdapter::GetV(
+    const std::string& logical_key, const iovec* iov, int iovcnt,
+    off_t offset) {
+    if (offset < 0 || iovcnt < 0 || (!iov && iovcnt > 0))
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    size_t total = 0;
+    for (int i = 0; i < iovcnt; ++i) {
+        if ((!iov[i].iov_base && iov[i].iov_len > 0) ||
+            iov[i].iov_len > std::numeric_limits<size_t>::max() - total)
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        total += iov[i].iov_len;
+    }
+    if (total == 0) return 0;
+    std::string data(total, '\0');
+    auto result = GetRange(logical_key, data.data(), data.size(), offset);
+    if (!result) return tl::make_unexpected(result.error());
+    size_t copied = 0;
+    for (int i = 0; i < iovcnt; ++i) {
+        if (iov[i].iov_len > 0) {
+            std::memcpy(iov[i].iov_base, data.data() + copied, iov[i].iov_len);
+        }
+        copied += iov[i].iov_len;
+    }
+    return total;
+}
+
+tl::expected<void, ErrorCode> OssObjectStorageAdapter::Delete(
+    const std::string& logical_key) {
+    auto response = Request("DELETE", LogicalToPhysicalKey(logical_key));
+    if (!response) return tl::make_unexpected(response.error());
+    if (!IsSuccess(response->status) && response->status != 404)
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return {};
+}
+
+tl::expected<bool, ErrorCode> OssObjectStorageAdapter::Exists(
+    const std::string& logical_key) {
+    auto response = Request("HEAD", LogicalToPhysicalKey(logical_key));
+    if (!response) return tl::make_unexpected(response.error());
+    if (response->status == 404) return false;
+    if (!IsSuccess(response->status))
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    return true;
+}
+
+tl::expected<size_t, ErrorCode> OssObjectStorageAdapter::GetSize(
+    const std::string& logical_key) {
+    auto response = Request("HEAD", LogicalToPhysicalKey(logical_key));
+    if (!response) return tl::make_unexpected(response.error());
+    if (response->status == 404)
+        return tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+    if (!IsSuccess(response->status))
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    auto it = response->headers.find("content-length");
+    if (it == response->headers.end())
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    try {
+        const auto value = std::stoull(it->second);
+        if (value > std::numeric_limits<size_t>::max())
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        return static_cast<size_t>(value);
+    } catch (...) {
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    }
+}
+
+tl::expected<std::vector<KeyInfo>, ErrorCode>
+OssObjectStorageAdapter::ListKeys() {
+    const std::string prefix = PhysicalPrefix();
+    std::vector<KeyInfo> keys;
+    std::string token;
+    do {
+        std::map<std::string, std::string> query{{"encoding-type", "url"},
+                                                 {"list-type", "2"},
+                                                 {"max-keys", "1000"},
+                                                 {"prefix", prefix}};
+        if (!token.empty()) query["continuation-token"] = token;
+        auto response = Request("GET", "", query);
+        if (!response) return tl::make_unexpected(response.error());
+        if (!IsSuccess(response->status))
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+
+        size_t pos = 0;
+        while ((pos = response->body.find("<Contents>", pos)) !=
+               std::string::npos) {
+            const size_t end = response->body.find("</Contents>", pos);
+            if (end == std::string::npos) break;
+            const std::string_view item(response->body.data() + pos,
+                                        end + 11 - pos);
+            std::string physical_key = UriDecode(XmlValue(item, "Key"));
+            const std::string size_value = XmlValue(item, "Size");
+            auto logical_key = PhysicalToLogicalKey(physical_key);
+            if (!logical_key) return tl::make_unexpected(logical_key.error());
+            try {
+                const auto value = std::stoull(size_value);
+                if (value > std::numeric_limits<size_t>::max())
+                    return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                keys.push_back(
+                    {std::move(*logical_key), static_cast<size_t>(value)});
+            } catch (...) {
+                return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+            }
+            pos = end + 11;
+        }
+        token = UriDecode(XmlValue(response->body, "NextContinuationToken"));
+        const std::string truncated = boost::algorithm::to_lower_copy(
+            XmlValue(response->body, "IsTruncated"));
+        if (truncated != "true") token.clear();
+        if (truncated == "true" && token.empty())
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    } while (!token.empty());
+    return keys;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/storage/distributed/posix_fs_adapter.cpp b/mooncake-store/src/storage/distributed/posix_fs_adapter.cpp
new file mode 100644
index 0000000000..144e6d9e1b
--- /dev/null
+++ b/mooncake-store/src/storage/distributed/posix_fs_adapter.cpp
@@ -0,0 +1,252 @@
+#include "storage/distributed/posix_fs_adapter.h"
+
+#include <dirent.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <sys/uio.h>
+#include <unistd.h>
+
+#include <cerrno>
+#include <cstring>
+#include <filesystem>
+
+namespace mooncake {
+
+namespace {
+
+tl::expected<void, ErrorCode> ValidateIov(const iovec* iov, int iovcnt) {
+    if (iovcnt < 0 || (iovcnt > 0 && iov == nullptr)) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    for (int i = 0; i < iovcnt; ++i) {
+        if (!iov[i].iov_base && iov[i].iov_len > 0) {
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+    }
+    return {};
+}
+
+ErrorCode ReadOpenError() {
+    return errno == ENOENT ? ErrorCode::FILE_NOT_FOUND
+                           : ErrorCode::FILE_OPEN_FAIL;
+}
+
+}  // namespace
+
+tl::expected<void, ErrorCode> PosixFsAdapter::Init(
+    const std::string& mount_path) {
+    mount_path_ = mount_path;
+    std::error_code ec;
+    std::filesystem::create_directories(mount_path_, ec);
+    if (ec) return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return {};
+}
+
+tl::expected<void, ErrorCode> PosixFsAdapter::Shutdown() { return {}; }
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::WriteFile(
+    const std::string& path, std::span<const char> data) {
+    int fd =
+        ::open(path.c_str(), O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+
+    size_t total_written = 0;
+    while (total_written < data.size()) {
+        ssize_t ret = ::write(fd, data.data() + total_written,
+                              data.size() - total_written);
+        if (ret < 0) {
+            int saved_errno = errno;
+            ::close(fd);
+            errno = saved_errno;
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        if (ret == 0) break;
+        total_written += static_cast<size_t>(ret);
+    }
+
+    if (::close(fd) != 0) {
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    if (total_written != data.size()) {
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    return total_written;
+}
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::ReadFile(
+    const std::string& path, void* buf, size_t len) {
+    if (!buf && len > 0) return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+
+    int fd = ::open(path.c_str(), O_RDONLY | O_CLOEXEC);
+    if (fd < 0) return tl::make_unexpected(ReadOpenError());
+
+    size_t total_read = 0;
+    char* dest = static_cast<char*>(buf);
+    while (total_read < len) {
+        ssize_t ret = ::read(fd, dest + total_read, len - total_read);
+        if (ret < 0) {
+            int saved_errno = errno;
+            ::close(fd);
+            errno = saved_errno;
+            return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        }
+        if (ret == 0) break;
+        total_read += static_cast<size_t>(ret);
+    }
+
+    if (::close(fd) != 0) {
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    }
+    return total_read;
+}
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::VectorWriteFile(
+    const std::string& path, const iovec* iov, int iovcnt, off_t offset) {
+    auto valid = ValidateIov(iov, iovcnt);
+    if (!valid) return tl::make_unexpected(valid.error());
+    if (offset < 0) return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+
+    int fd =
+        ::open(path.c_str(), O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    auto result = WriteAt(fd, iov, iovcnt, offset);
+    int saved_errno = errno;
+    ::close(fd);
+    errno = saved_errno;
+    return result;
+}
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::VectorReadFile(
+    const std::string& path, const iovec* iov, int iovcnt, off_t offset) {
+    auto valid = ValidateIov(iov, iovcnt);
+    if (!valid) return tl::make_unexpected(valid.error());
+    if (offset < 0) return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+
+    int fd = ::open(path.c_str(), O_RDONLY | O_CLOEXEC);
+    if (fd < 0) return tl::make_unexpected(ReadOpenError());
+    auto result = ReadAt(fd, const_cast<iovec*>(iov), iovcnt, offset);
+    int saved_errno = errno;
+    ::close(fd);
+    errno = saved_errno;
+    return result;
+}
+
+tl::expected<void, ErrorCode> PosixFsAdapter::DeleteFile(
+    const std::string& path) {
+    if (::unlink(path.c_str()) != 0) {
+        if (errno == ENOENT)
+            return tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    return {};
+}
+
+tl::expected<bool, ErrorCode> PosixFsAdapter::FileExists(
+    const std::string& path) {
+    if (::access(path.c_str(), F_OK) == 0) return true;
+    if (errno == ENOENT) return false;
+    return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+}
+
+tl::expected<std::vector<std::string>, ErrorCode> PosixFsAdapter::ListFiles(
+    const std::string& dir) {
+    DIR* d = ::opendir(dir.c_str());
+    if (!d) {
+        if (errno == ENOENT)
+            return tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    }
+
+    std::vector<std::string> result;
+    while (auto* entry = ::readdir(d)) {
+        std::string name = entry->d_name;
+        if (name == "." || name == "..") continue;
+        if (entry->d_type == DT_DIR) continue;
+        if (entry->d_type == DT_UNKNOWN) {
+            struct stat st;
+            if (::stat((dir + "/" + name).c_str(), &st) == 0 &&
+                S_ISDIR(st.st_mode)) {
+                continue;
+            }
+        }
+        result.push_back(std::move(name));
+    }
+    ::closedir(d);
+    return result;
+}
+
+tl::expected<int, ErrorCode> PosixFsAdapter::OpenFile(const std::string& path) {
+    int fd = ::open(path.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+    return fd;
+}
+
+tl::expected<int, ErrorCode> PosixFsAdapter::OpenExistingFile(
+    const std::string& path) {
+    int fd;
+    do {
+        fd = ::open(path.c_str(), O_RDWR | O_CLOEXEC);
+    } while (fd < 0 && errno == EINTR);
+    if (fd < 0) return tl::make_unexpected(ReadOpenError());
+    return fd;
+}
+
+tl::expected<void, ErrorCode> PosixFsAdapter::CloseFile(int fd) {
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_INVALID_HANDLE);
+    if (::close(fd) != 0) {
+        return tl::make_unexpected(ErrorCode::FILE_INVALID_HANDLE);
+    }
+    return {};
+}
+
+tl::expected<void, ErrorCode> PosixFsAdapter::PreallocateFile(
+    const std::string& path, uint64_t size) {
+    int fd = ::open(path.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0644);
+    if (fd < 0) return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+
+    int rc = ::ftruncate(fd, static_cast<off_t>(size));
+    int saved_errno = errno;
+    ::close(fd);
+    errno = saved_errno;
+    if (rc != 0) return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return {};
+}
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::WriteAt(int fd,
+                                                        const iovec* iov,
+                                                        int iovcnt,
+                                                        int64_t offset) {
+    if (fd < 0 || offset < 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto valid = ValidateIov(iov, iovcnt);
+    if (!valid) return tl::make_unexpected(valid.error());
+    if (iovcnt == 0) return size_t{0};
+
+    ssize_t ret;
+    do {
+        ret = ::pwritev(fd, iov, iovcnt, static_cast<off_t>(offset));
+    } while (ret < 0 && errno == EINTR);
+    if (ret < 0) return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    return static_cast<size_t>(ret);
+}
+
+tl::expected<size_t, ErrorCode> PosixFsAdapter::ReadAt(int fd, iovec* iov,
+                                                       int iovcnt,
+                                                       int64_t offset) {
+    if (fd < 0 || offset < 0) {
+        return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+    }
+    auto valid = ValidateIov(iov, iovcnt);
+    if (!valid) return tl::make_unexpected(valid.error());
+    if (iovcnt == 0) return size_t{0};
+
+    ssize_t ret;
+    do {
+        ret = ::preadv(fd, iov, iovcnt, static_cast<off_t>(offset));
+    } while (ret < 0 && errno == EINTR);
+    if (ret < 0) return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+    return static_cast<size_t>(ret);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/storage_backend.cpp b/mooncake-store/src/storage_backend.cpp
index d206571402..8e59e6242f 100644
--- a/mooncake-store/src/storage_backend.cpp
+++ b/mooncake-store/src/storage_backend.cpp
@@ -24,11 +24,10 @@
 #include <ylt/struct_pb.hpp>
 
 #include "mutex.h"
-#include "utils.h"
+#include "nvme_kv/backend.h"
+#include "common/timestamp.h"
+#include "common/file_util.h"
 #include "crc32c.h"
-#include "ascii_string.h"
-#include "bool_parser.h"
-#include "environ.h"
 
 #include <ylt/util/tl/expected.hpp>
 
@@ -51,196 +50,16 @@ struct FdGuard {
 }  // namespace
 
 #include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#ifdef HAVE_OSS_ADAPTER
+#include "storage/distributed/oss_adapter.h"
+#endif
+#ifdef USE_3FS
+#include "storage/distributed/hf3fs_adapter.h"
+#endif
 
 namespace mooncake {
 
-bool FilePerKeyConfig::Validate() const {
-    if (fsdir.empty()) {
-        LOG(ERROR) << "FilePerKeyConfig: fsdir is invalid";
-        return false;
-    }
-    return true;
-}
-
-bool BucketBackendConfig::Validate() const {
-    if (bucket_keys_limit <= 0) {
-        LOG(ERROR) << "BucketBackendConfig: bucket_keys_limit must > 0";
-        return false;
-    }
-    if (bucket_size_limit <= 0) {
-        LOG(ERROR) << "BucketBackendConfig: bucket_size_limit must > 0";
-        return false;
-    }
-    return true;
-}
-
-FilePerKeyConfig FilePerKeyConfig::FromEnvironment() {
-    FilePerKeyConfig config;
-
-    config.fsdir = Environ::GetString("MOONCAKE_OFFLOAD_FSDIR", config.fsdir);
-
-    config.enable_eviction = Environ::GetBool(
-        "MOONCAKE_OFFLOAD_ENABLE_EVICTION",
-        Environ::GetBool("ENABLE_EVICTION", config.enable_eviction));
-
-    return config;
-}
-
-BucketBackendConfig BucketBackendConfig::FromEnvironment() {
-    BucketBackendConfig config;
-
-    config.bucket_keys_limit = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", config.bucket_keys_limit);
-
-    config.bucket_size_limit = Environ::GetInt64(
-        "MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES", config.bucket_size_limit);
-
-    config.max_total_size =
-        Environ::GetInt64("MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE",
-                          Environ::GetInt64("MOONCAKE_BUCKET_MAX_TOTAL_SIZE",
-                                            config.max_total_size));
-
-    const auto policy_str = Environ::GetString(
-        "MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY",
-        Environ::GetString("MOONCAKE_BUCKET_EVICTION_POLICY", "fifo"));
-    if (policy_str == "fifo") {
-        config.eviction_policy = BucketEvictionPolicy::FIFO;
-    } else if (policy_str == "lru") {
-        config.eviction_policy = BucketEvictionPolicy::LRU;
-    } else {
-        config.eviction_policy = BucketEvictionPolicy::NONE;
-    }
-
-    return config;
-}
-
-bool OffsetAllocatorBackendConfig::Validate() const {
-    if (persist_mode == OffsetPersistMode::kRelaxed) {
-        if (persist_interval_seconds < 5) {
-            LOG(ERROR) << "OffsetAllocatorBackendConfig: "
-                          "persist_interval_seconds must be >= 5 for "
-                          "kRelaxed mode";
-            return false;
-        }
-    }
-    if (high_ratio <= 0.0 || high_ratio > 1.0) {
-        LOG(ERROR)
-            << "OffsetAllocatorBackendConfig: high_ratio must be in (0,1]";
-        return false;
-    }
-    if (low_ratio <= 0.0 || low_ratio >= high_ratio) {
-        LOG(ERROR) << "OffsetAllocatorBackendConfig: low_ratio must be in (0, "
-                      "high_ratio)";
-        return false;
-    }
-    if (keys_high_ratio <= 0.0 || keys_high_ratio > 1.0) {
-        LOG(ERROR)
-            << "OffsetAllocatorBackendConfig: keys_high_ratio must be in (0,1]";
-        return false;
-    }
-    if (keys_low_ratio <= 0.0 || keys_low_ratio >= keys_high_ratio) {
-        LOG(ERROR) << "OffsetAllocatorBackendConfig: keys_low_ratio must be in "
-                      "(0, keys_high_ratio)";
-        return false;
-    }
-    if (max_evict_per_offload == 0) {
-        LOG(ERROR) << "OffsetAllocatorBackendConfig: max_evict_per_offload "
-                      "must be > 0";
-        return false;
-    }
-    if (fallback_evict_batch == 0) {
-        LOG(ERROR)
-            << "OffsetAllocatorBackendConfig: fallback_evict_batch must be > 0";
-        return false;
-    }
-    if (max_capacity_nodes < 0) {
-        LOG(ERROR)
-            << "OffsetAllocatorBackendConfig: max_capacity_nodes must be >= 0";
-        return false;
-    }
-    return true;
-}
-
-static std::optional<double> GetEnvDouble(const char* name) {
-    const char* env = std::getenv(name);
-    if (!env || env[0] == '\0') return std::nullopt;
-    try {
-        return std::stod(env);
-    } catch (...) {
-        return std::nullopt;
-    }
-}
-
-OffsetAllocatorBackendConfig OffsetAllocatorBackendConfig::FromEnvironment() {
-    OffsetAllocatorBackendConfig cfg;
-
-    const char* pol = std::getenv("MOONCAKE_OFFSET_EVICTION_POLICY");
-    if (pol) {
-        if (AsciiCaseInsensitiveEquals(pol, "fifo")) {
-            cfg.eviction_policy = OffsetEvictionPolicy::FIFO;
-        }
-        // NONE is default; LRU reserved for phase 2
-    }
-
-    if (auto v = GetEnvDouble("MOONCAKE_OFFSET_HIGH_RATIO"))
-        cfg.high_ratio = *v;
-    if (auto v = GetEnvDouble("MOONCAKE_OFFSET_LOW_RATIO")) cfg.low_ratio = *v;
-    // Both byte and key watermarks derive from the same ratio pair.
-    cfg.keys_high_ratio = cfg.high_ratio;
-    cfg.keys_low_ratio = cfg.low_ratio;
-
-    cfg.max_capacity_nodes = Environ::GetInt64(
-        "MOONCAKE_OFFSET_MAX_CAPACITY_NODES", cfg.max_capacity_nodes);
-
-    // Read eviction cap as int64_t to guard against negative env values
-    // which would wrap to SIZE_MAX with an unsigned parser.
-    auto max_evict_raw =
-        Environ::GetInt64("MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD",
-                          static_cast<int64_t>(cfg.max_evict_per_offload));
-    if (max_evict_raw > 0) {
-        cfg.max_evict_per_offload = static_cast<size_t>(max_evict_raw);
-    } else if (max_evict_raw <= 0) {
-        LOG(WARNING) << "MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD="
-                     << max_evict_raw << " is non-positive; using default "
-                     << cfg.max_evict_per_offload;
-    }
-
-    // Persistence mode
-    const char* persist = std::getenv("MOONCAKE_OFFSET_PERSIST_MODE");
-    if (persist) {
-        std::string s(persist);
-        if (AsciiCaseInsensitiveEquals(s, "disabled")) {
-            cfg.persist_mode = OffsetPersistMode::kDisabled;
-        } else if (AsciiCaseInsensitiveEquals(s, "relaxed")) {
-            cfg.persist_mode = OffsetPersistMode::kRelaxed;
-        } else if (AsciiCaseInsensitiveEquals(s, "strict")) {
-            cfg.persist_mode = OffsetPersistMode::kStrict;
-        } else {
-            LOG(WARNING) << "Unknown MOONCAKE_OFFSET_PERSIST_MODE=" << s
-                         << "; using default (disabled)";
-        }
-    }
-
-    cfg.persist_interval_seconds =
-        Environ::GetInt64("MOONCAKE_OFFSET_PERSIST_INTERVAL_SECONDS",
-                          cfg.persist_interval_seconds);
-
-    // Record CRC-32C: "0"/"false"/"off" disables per-record checksums.
-    const char* crc_env = std::getenv("MOONCAKE_OFFSET_RECORD_CRC");
-    if (crc_env) {
-        const auto parsed = TryParseBool(crc_env);
-        if (parsed.has_value() && !*parsed) {
-            cfg.enable_record_crc = false;
-        }
-    }
-
-    return cfg;
-}
-
-StorageBackendInterface::StorageBackendInterface(
-    const FileStorageConfig& config)
-    : file_storage_config_(config) {}
-
 std::string StorageBackend::GetActualFsdir() const {
     std::string actual_fsdir = fsdir_;
     if (actual_fsdir.rfind("moon_", 0) == 0) {
@@ -653,14 +472,9 @@ tl::expected<void, ErrorCode> StorageBackend::LoadObject(
 
 void StorageBackend::RemoveFile(const std::string& path) {
     namespace fs = std::filesystem;
-    // TODO: attention: this function is not thread-safe, need to add lock if
-    // used in multi-thread environment Check if the file exists before
-    // attempting to remove it
-    // TODO: add a sleep to ensure the write thread has time to create the
-    // corresponding file it will be fixed in the next version
-    std::this_thread::sleep_for(
-        std::chrono::microseconds(50));  // sleep for 50 us
-
+    // StoreObject holds the same striped path lock across file creation, write,
+    // and queue insertion. Acquiring it here serializes deletion with those
+    // operations without relying on a timing delay.
     MutexLocker path_locker(&GetFilePathMutex(path));
 
     // Eviction disabled, use simple delete (no queue tracking)
@@ -1441,9 +1255,9 @@ tl::expected<int64_t, ErrorCode> StorageBackendAdaptor::BatchOffload(
             continue;  // Simulate StoreObject failure
         }
 
-        auto path =
-            ResolvePathFromKey(kv.key, file_storage_config_.storage_filepath,
-                               file_per_key_config_.fsdir);
+        auto path = FileUtil::ResolvePathFromKey(
+            kv.key, file_storage_config_.storage_filepath,
+            file_per_key_config_.fsdir);
         kv.value = ConcatSlicesToString(value);
 
         std::string kv_buf;
@@ -1500,8 +1314,8 @@ StorageBackendAdaptor::EvictAboveDiskWatermark(
 
 tl::expected<bool, ErrorCode> StorageBackendAdaptor::IsExist(
     const std::string& key) {
-    auto path = ResolvePathFromKey(key, file_storage_config_.storage_filepath,
-                                   file_per_key_config_.fsdir);
+    auto path = FileUtil::ResolvePathFromKey(
+        key, file_storage_config_.storage_filepath, file_per_key_config_.fsdir);
     namespace fs = std::filesystem;
     return fs::exists(path);
 }
@@ -1511,9 +1325,9 @@ tl::expected<void, ErrorCode> StorageBackendAdaptor::BatchLoad(
     for (const auto& [key, slice] : batched_slices) {
         KVEntry kv;
         kv.key = key;
-        auto path =
-            ResolvePathFromKey(kv.key, file_storage_config_.storage_filepath,
-                               file_per_key_config_.fsdir);
+        auto path = FileUtil::ResolvePathFromKey(
+            kv.key, file_storage_config_.storage_filepath,
+            file_per_key_config_.fsdir);
 
         kv.value.resize(slice.size);
 
@@ -1770,9 +1584,14 @@ tl::expected<int64_t, ErrorCode> BucketStorageBackend::BatchOffload(
         ReleasePreparedWrite(pending);
         return tl::make_unexpected(write_bucket_result.error());
     }
+    VLOG(1) << "Written bucket with id: " << bucket_id;
     // Save a copy of bucket->keys before std::move(bucket) into buckets_
     // consumes the shared_ptr. Needed for complete_handler and rollback.
     const auto bucket_keys = bucket->keys;
+    // Keys/metadatas actually committed below (duplicates skipped). The
+    // complete handler and the rollback path must only see these.
+    std::vector<std::string> committed_keys;
+    std::vector<StorageObjectMetadata> committed_metadatas;
 
     // Commit to metadata maps under exclusive lock FIRST.
     // This ensures any concurrent BatchLoad arriving after Master redirects
@@ -1784,36 +1603,63 @@ tl::expected<int64_t, ErrorCode> BucketStorageBackend::BatchOffload(
 
         ReleasePreparedWriteLocked(pending);
 
-        // Pre-check for duplicates before modifying any state
-        bool duplicate_found = false;
-        for (const auto& key : bucket_keys) {
-            if (object_bucket_map_.find(key) != object_bucket_map_.end()) {
-                duplicate_found = true;
-                break;
+        // Duplicate safety net under mutex_: skip keys that PrepareEviction
+        // flagged as already persisted or in flight, plus anything that got
+        // committed since (defense in depth). GroupOffloadingKeysByBucket
+        // filters persisted keys under offloading_mutex_, but a key can
+        // still be committed by a concurrent BatchOffload between that
+        // check and this one. Re-offloading an already persisted key is an
+        // idempotent no-op (same as Put), not an error.
+        const std::unordered_set<std::string> skipped_keys(
+            pending.skipped_keys.begin(), pending.skipped_keys.end());
+        std::vector<size_t> committed_indices;
+        for (size_t i = 0; i < bucket_keys.size(); ++i) {
+            if (skipped_keys.find(bucket_keys[i]) != skipped_keys.end() &&
+                object_bucket_map_.find(bucket_keys[i]) !=
+                    object_bucket_map_.end()) {
+                continue;  // Still persisted elsewhere: idempotent skip.
             }
-        }
-
-        if (!duplicate_found) {
-            total_size_ += bucket->data_size + bucket->meta_size;
-            object_bucket_map_.reserve(object_bucket_map_.size() +
-                                       bucket_keys.size());
-            for (size_t i = 0; i < bucket_keys.size(); ++i) {
-                auto [it, inserted] =
-                    object_bucket_map_.insert({bucket_keys[i], metadatas[i]});
-                CHECK(inserted)
-                    << "Reserved key became duplicated: " << bucket_keys[i];
+            if (object_bucket_map_.find(bucket_keys[i]) ==
+                object_bucket_map_.end()) {
+                committed_indices.push_back(i);
+            } else {
+                VLOG(1) << "Key already committed by a concurrent offload, "
+                           "skipping: "
+                        << bucket_keys[i];
             }
-            buckets_.emplace(bucket_id, std::move(bucket));
-            lru_index_.emplace(0LL, bucket_id);
         }
-        if (duplicate_found) {
-            LOG(ERROR) << "Reserved key became duplicated before commit, "
-                          "bucket_id="
-                       << bucket_id;
+
+        if (committed_indices.empty()) {
+            // Every key was already persisted: nothing new to commit or
+            // notify, the written bucket file is redundant.
             lock.unlock();
             CleanupOrphanedBucket(bucket_id);
-            return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
+            return bucket_id;
+        }
+
+        int64_t committed_data_size = bucket->meta_size;
+        object_bucket_map_.reserve(object_bucket_map_.size() +
+                                   committed_indices.size());
+        for (size_t i : committed_indices) {
+            auto [it, inserted] =
+                object_bucket_map_.insert({bucket_keys[i], metadatas[i]});
+            CHECK(inserted)
+                << "Reserved key became duplicated: " << bucket_keys[i];
+            committed_data_size +=
+                metadatas[i].data_size + metadatas[i].key_size;
+            committed_keys.push_back(bucket_keys[i]);
+            committed_metadatas.push_back(metadatas[i]);
+        }
+        total_size_ += committed_data_size;
+        auto ts = 0LL;
+        // Update LRU timestamp for in case of eviction.
+        if (bucket_backend_config_.eviction_policy ==
+            BucketEvictionPolicy::LRU) {
+            ts = std::chrono::steady_clock::now().time_since_epoch().count();
+            bucket->last_access_ns_.store(ts, std::memory_order_relaxed);
         }
+        buckets_.emplace(bucket_id, std::move(bucket));
+        lru_index_.emplace(ts, bucket_id);
     }
     // Lock released. From this point forward, concurrent BatchLoad
     // can find the keys and read from the committed bucket files.
@@ -1823,17 +1669,17 @@ tl::expected<int64_t, ErrorCode> BucketStorageBackend::BatchOffload(
     // complete_handler before the RPC); int64_t fields carry the metadata
     // from BuildBucket unchanged.
     if (complete_handler != nullptr) {
-        auto error_code = complete_handler(bucket_keys, metadatas);
+        auto error_code = complete_handler(committed_keys, committed_metadatas);
         if (error_code != ErrorCode::OK) {
             LOG(ERROR) << "Complete handler failed: " << error_code
-                       << ", Key count: " << bucket_keys.size()
+                       << ", Key count: " << committed_keys.size()
                        << ", Bucket id: " << bucket_id;
             // Master was NOT notified. The local index has entries that
             // Master doesn't know about — a "client can read but Master
             // doesn't know" ghost replica. Rollback the local commit
             // (removes index entries + waits for inflight reads + deletes
             // on-disk files).
-            RollbackCommittedBucket(bucket_id, bucket_keys);
+            RollbackCommittedBucket(bucket_id, committed_keys);
             return tl::make_unexpected(error_code);
         }
     }
@@ -1949,16 +1795,22 @@ tl::expected<void, ErrorCode> BucketStorageBackend::BatchLoad(
         }
         auto& file = file_res.value();
 
-        // Read each key's data
-        for (const auto& plan : read_plans) {
-            int64_t actual_offset = plan.offset + plan.key_size;
-            tl::expected<size_t, ErrorCode> read_res;
-
 #ifdef USE_URING
-            // Try to use read_aligned for O_DIRECT I/O if file is UringFile
-            UringFile* uring_file = dynamic_cast<UringFile*>(file.get());
-            if (uring_file != nullptr) {
-                // Calculate aligned read range
+        UringFile* uring_file = dynamic_cast<UringFile*>(file.get());
+        if (uring_file != nullptr) {
+            struct BatchReadPlan {
+                const ReadPlan* plan;
+                size_t offset_in_buffer;
+                size_t min_required;
+            };
+
+            std::vector<UringFile::ReadDesc> read_descs;
+            std::vector<BatchReadPlan> batch_read_plans;
+            read_descs.reserve(read_plans.size());
+            batch_read_plans.reserve(read_plans.size());
+
+            for (const auto& plan : read_plans) {
+                int64_t actual_offset = plan.offset + plan.key_size;
                 int64_t aligned_offset =
                     align_down(actual_offset, kDirectIOAlignment);
                 int64_t data_end =
@@ -1967,64 +1819,72 @@ tl::expected<void, ErrorCode> BucketStorageBackend::BatchLoad(
                     static_cast<size_t>(data_end), kDirectIOAlignment));
                 size_t aligned_size =
                     static_cast<size_t>(aligned_end - aligned_offset);
-                int64_t offset_in_buffer = actual_offset - aligned_offset;
-
-                // Zero-copy path: read directly into the slice buffer.
-                // dest_slice.ptr is 4096-aligned and oversized (from
-                // AllocateBatch) to accommodate the full aligned read range.
-                read_res = uring_file->read_aligned(
-                    plan.dest_slice.ptr, aligned_size, aligned_offset);
-
-                if (read_res) {
-                    // Verify the aligned read returned enough bytes
-                    // to cover the actual data region.  read_aligned
-                    // reads the full aligned range [aligned_offset,
-                    // aligned_end); the caller-visible data starts at
-                    // offset_in_buffer into that buffer and spans
-                    // plan.dest_slice.size bytes.
-                    size_t min_required =
-                        static_cast<size_t>(offset_in_buffer) +
-                        plan.dest_slice.size;
-                    if (read_res.value() < min_required) {
-                        LOG(ERROR)
-                            << "read_aligned short read for key: " << plan.key
-                            << ", bucket_id=" << plan.bucket_id
-                            << ", expected at least: " << min_required
-                            << " (aligned_size=" << aligned_size
-                            << ", data_size=" << plan.dest_slice.size << ")"
-                            << ", got: " << read_res.value();
-                        return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
-                    }
-                    // Adjust ptr to point to actual data start
-                    // (zero-copy: no memcpy, buffer was oversized by
-                    // AllocateBatch to accommodate the aligned read)
-                    batch_object.at(plan.key).ptr =
-                        static_cast<char*>(plan.dest_slice.ptr) +
-                        offset_in_buffer;
-                    // Normalize read_res so the common validation
-                    // below passes.  The real short-read check was
-                    // already done above (min_required).
-                    read_res = plan.dest_slice.size;
+                size_t offset_in_buffer =
+                    static_cast<size_t>(actual_offset - aligned_offset);
+
+                read_descs.push_back(UringFile::ReadDesc{
+                    plan.dest_slice.ptr, aligned_size, aligned_offset});
+                batch_read_plans.push_back(
+                    BatchReadPlan{&plan, offset_in_buffer,
+                                  offset_in_buffer + plan.dest_slice.size});
+            }
+
+            auto batch_read_result = uring_file->batch_read(
+                read_descs.data(), static_cast<int>(read_descs.size()));
+            if (!batch_read_result) {
+                for (size_t i = 0; i < read_descs.size(); ++i) {
+                    if (read_descs[i].error == ErrorCode::OK) continue;
+                    LOG(ERROR)
+                        << "batch_read failed for key: "
+                        << batch_read_plans[i].plan->key
+                        << ", bucket_id=" << batch_read_plans[i].plan->bucket_id
+                        << ", error=" << read_descs[i].error;
                 }
-            } else
-#endif
-            {
-                // Fallback to vector_read for non-UringFile
-                iovec iov{plan.dest_slice.ptr, plan.dest_slice.size};
-                read_res = file->vector_read(&iov, 1, actual_offset);
+                return tl::make_unexpected(batch_read_result.error());
             }
 
-            if (!read_res) {
+            for (size_t i = 0; i < read_descs.size(); ++i) {
+                const auto& desc = read_descs[i];
+                const auto& batch_plan = batch_read_plans[i];
+                const auto& plan = *batch_plan.plan;
+                if (!desc.completed) {
+                    LOG(ERROR)
+                        << "batch_read did not complete for key: " << plan.key
+                        << ", bucket_id=" << plan.bucket_id;
+                    return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                }
+                if (desc.bytes_read < batch_plan.min_required) {
+                    LOG(ERROR)
+                        << "batch_read short read for key: " << plan.key
+                        << ", bucket_id=" << plan.bucket_id
+                        << ", expected at least: " << batch_plan.min_required
+                        << " (aligned_size=" << desc.len
+                        << ", data_size=" << plan.dest_slice.size
+                        << "), got: " << desc.bytes_read;
+                    return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+                }
+                batch_object.at(plan.key).ptr =
+                    static_cast<char*>(plan.dest_slice.ptr) +
+                    batch_plan.offset_in_buffer;
+            }
+            continue;
+        }
+#endif
+
+        for (const auto& plan : read_plans) {
+            int64_t actual_offset = plan.offset + plan.key_size;
+            iovec iov{plan.dest_slice.ptr, plan.dest_slice.size};
+            auto read_result = file->vector_read(&iov, 1, actual_offset);
+            if (!read_result) {
                 LOG(ERROR) << "vector_read failed for key: " << plan.key
                            << ", bucket_id=" << plan.bucket_id
-                           << ", error: " << read_res.error();
-                return tl::make_unexpected(read_res.error());
+                           << ", error: " << read_result.error();
+                return tl::make_unexpected(read_result.error());
             }
-
-            if (read_res.value() != plan.dest_slice.size) {
+            if (read_result.value() != plan.dest_slice.size) {
                 LOG(ERROR) << "Read size mismatch for key: " << plan.key
                            << ", expected: " << plan.dest_slice.size
-                           << ", got: " << read_res.value();
+                           << ", got: " << read_result.value();
                 return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
             }
         }
@@ -2395,10 +2255,15 @@ tl::expected<void, ErrorCode> BucketStorageBackend::GroupOffloadingKeysByBucket(
     const std::unordered_map<std::string, int64_t>& offloading_objects,
     std::vector<std::vector<std::string>>& buckets_keys) {
     MutexLocker offloading_locker(&offloading_mutex_);
+    if (offloading_objects.empty()) {
+        return {};
+    }
     auto& ungrouped_offloading_objects = ungrouped_offloading_objects_;
+    auto carryover_objects = std::move(ungrouped_offloading_objects);
+    bool carryover_loaded = false;
     auto it = offloading_objects.cbegin();
-    int64_t residue_count = static_cast<int64_t>(
-        offloading_objects.size() + ungrouped_offloading_objects.size());
+    int64_t residue_count = static_cast<int64_t>(offloading_objects.size() +
+                                                 carryover_objects.size());
     int64_t total_count = residue_count;
 
     auto is_exist_func =
@@ -2411,20 +2276,20 @@ tl::expected<void, ErrorCode> BucketStorageBackend::GroupOffloadingKeysByBucket(
         std::unordered_map<std::string, int64_t> bucket_objects;
         int64_t bucket_data_size = 0;
 
-        if (!ungrouped_offloading_objects.empty()) {
-            for (const auto& ungrouped_it : ungrouped_offloading_objects) {
+        if (!carryover_loaded) {
+            for (const auto& ungrouped_it : carryover_objects) {
                 bucket_data_size += ungrouped_it.second;
                 bucket_keys.push_back(ungrouped_it.first);
                 bucket_objects.emplace(ungrouped_it.first, ungrouped_it.second);
             }
             VLOG(1) << "Ungrouped offloading objects have been processed and "
                        "cleared; count="
-                    << ungrouped_offloading_objects.size();
-            ungrouped_offloading_objects.clear();
+                    << carryover_objects.size();
+            carryover_loaded = true;
         }
 
-        for (int64_t i = static_cast<int64_t>(bucket_keys.size());
-             i < bucket_backend_config_.bucket_keys_limit; ++i) {
+        while (static_cast<int64_t>(bucket_keys.size()) <
+               bucket_backend_config_.bucket_keys_limit) {
             if (it == offloading_objects.cend()) {
                 for (const auto& bucket_object : bucket_objects) {
                     ungrouped_offloading_objects.emplace(bucket_object.first,
@@ -2436,6 +2301,11 @@ tl::expected<void, ErrorCode> BucketStorageBackend::GroupOffloadingKeysByBucket(
                 return {};
             }
 
+            if (carryover_objects.find(it->first) != carryover_objects.end()) {
+                ++it;
+                continue;
+            }
+
             if (it->second > bucket_backend_config_.bucket_size_limit) {
                 VLOG(1) << "Object size exceeds bucket size limit: "
                         << "key=" << it->first << ", object_size=" << it->second
@@ -2597,21 +2467,6 @@ tl::expected<void, ErrorCode> BucketStorageBackend::WriteBucket(
                        << ", got: " << write_result.value();
             return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
         }
-
-        // Flush bucket data to stable storage before writing metadata.
-        // This prevents a crash from leaving valid metadata pointing at
-        // incomplete data (write-ordering durability guarantee).
-        auto sync_result = uring_file->datasync();
-        if (!sync_result) {
-            LOG(ERROR) << "datasync failed for bucket: " << bucket_id;
-            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
-        }
-
-        // Invalidate cache for this file since content changed
-        {
-            MutexLocker cache_locker(&file_cache_mutex_);
-            file_cache_.erase(bucket_data_path);
-        }
     } else
 #endif
     {
@@ -2629,13 +2484,32 @@ tl::expected<void, ErrorCode> BucketStorageBackend::WriteBucket(
                        << ", got: " << write_result.value();
             return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
         }
+    }
 
-        // Invalidate cache for this file since content changed
-        {
-            MutexLocker cache_locker(&file_cache_mutex_);
-            file_cache_.erase(bucket_data_path);
-        }
+    // Flush bucket data to stable storage before writing metadata.
+    // This prevents a crash from leaving valid metadata pointing at
+    // incomplete data (write-ordering durability guarantee).
+    // StorageFile declares a virtual datasync() overridden by both PosixFile
+    // (fdatasync) and UringFile, so a single call covers both write paths and
+    // the branches above only keep their own write logic.
+    auto sync_result = file->datasync();
+    // Test-only: override sync result to exercise the same !sync_result
+    // cleanup path as a real fdatasync() failure.
+    if (test_datasync_failure_.load(std::memory_order_relaxed)) {
+        sync_result = tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+    if (!sync_result) {
+        LOG(ERROR) << "datasync failed for bucket: " << bucket_id;
+        CleanupOrphanedBucket(bucket_id);
+        return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+    }
+
+    // Invalidate cache for this file since content changed
+    {
+        MutexLocker cache_locker(&file_cache_mutex_);
+        file_cache_.erase(bucket_data_path);
     }
+
     auto store_bucket_metadata_result =
         StoreBucketMetadata(bucket_id, bucket_metadata);
     if (!store_bucket_metadata_result) {
@@ -2731,7 +2605,9 @@ void BucketStorageBackend::RollbackCommittedBucket(
 
         // Remove bucket metadata
         total_size_ -= bucket_meta->meta_size;
-        lru_index_.erase({0LL, bucket_id});
+        lru_index_.erase(
+            {bucket_meta->last_access_ns_.load(std::memory_order_relaxed),
+             bucket_id});
         buckets_.erase(bucket_it);
     }
 
@@ -2835,6 +2711,56 @@ BucketStorageBackend::SelectEvictionCandidate() {
     }
 }
 
+int64_t BucketStorageBackend::ActualDiskBytesUsedLocked() const {
+    namespace fs = std::filesystem;
+    auto now = std::chrono::steady_clock::now();
+    if (cached_disk_bytes_ >= 0 &&
+        now - cached_disk_bytes_at_ <
+            std::chrono::milliseconds(
+                bucket_backend_config_.disk_scan_cache_ms)) {
+        return cached_disk_bytes_;
+    }
+    int64_t total = 0;
+    std::error_code ec;
+    // Recursive scan: matches Init()'s recursive_directory_iterator and the
+    // du/kubelet accounting basis (the whole subtree, not just top-level
+    // entries), so nested content can never be silently missed.
+    fs::recursive_directory_iterator it(storage_path_, ec), end;
+    if (ec) {
+        // Cannot even open storage_path_. This is a hard safety cap, so fail
+        // CLOSED: report the cap as reached so eviction/rejection engages
+        // instead of letting the disk overflow, and do NOT cache the result
+        // (next call re-scans once the directory is readable again).
+        LOG(WARNING) << "[Bucket] physcap disk scan could not open "
+                     << storage_path_ << ": " << ec.message()
+                     << ", failing closed";
+        return bucket_backend_config_.max_physical_bytes;
+    }
+    for (; it != end; it.increment(ec)) {
+        if (ec) {
+            // Iteration errored partway. Returning the partial total would
+            // under-count and silently open the cap; fail closed and skip
+            // caching so the next call re-scans.
+            LOG(WARNING) << "[Bucket] physcap disk scan error under "
+                         << storage_path_ << ": " << ec.message()
+                         << ", failing closed";
+            return bucket_backend_config_.max_physical_bytes;
+        }
+        struct stat st;
+        // st_blocks counts 512-byte blocks actually allocated on disk — the
+        // same basis as du / kubelet's emptyDir accounting (handles block
+        // rounding; ignores apparent size). A per-entry stat failure (e.g. a
+        // file concurrently deleted during eviction) is skipped best-effort:
+        // that only under-counts by ~one file and avoids spurious fail-closed.
+        if (::stat(it->path().c_str(), &st) == 0) {
+            total += static_cast<int64_t>(st.st_blocks) * 512;
+        }
+    }
+    cached_disk_bytes_ = total;
+    cached_disk_bytes_at_ = now;
+    return total;
+}
+
 tl::expected<BucketStorageBackend::PendingEviction, ErrorCode>
 BucketStorageBackend::PrepareEviction(
     int64_t required_size, const std::vector<std::string>& write_keys) {
@@ -2844,16 +2770,27 @@ BucketStorageBackend::PrepareEviction(
     if (!write_keys.empty()) {
         for (const auto& key : write_keys) {
             if (object_bucket_map_.find(key) != object_bucket_map_.end() ||
-                pending_eviction_keys_.find(key) !=
-                    pending_eviction_keys_.end() ||
                 pending_write_keys_.find(key) != pending_write_keys_.end()) {
+                // Already persisted, or being persisted by a concurrent
+                // offload: re-offloading is an idempotent no-op (Put
+                // semantics), skip it instead of failing the whole batch.
+                result.skipped_keys.push_back(key);
+                continue;
+            }
+            if (pending_eviction_keys_.find(key) !=
+                pending_eviction_keys_.end()) {
+                // About to be evicted: the old copy is on its way out, so a
+                // skip could lose the only replica. Fail loudly here.
                 return tl::make_unexpected(ErrorCode::OBJECT_ALREADY_EXISTS);
             }
+            result.write_keys.push_back(key);
+        }
+        if (!result.write_keys.empty()) {
+            result.write_size = required_size;
+            pending_write_size_ += required_size;
+            pending_write_keys_.insert(result.write_keys.begin(),
+                                       result.write_keys.end());
         }
-        result.write_keys = write_keys;
-        result.write_size = required_size;
-        pending_write_size_ += required_size;
-        pending_write_keys_.insert(write_keys.begin(), write_keys.end());
     }
 
     if (bucket_backend_config_.eviction_policy == BucketEvictionPolicy::NONE) {
@@ -2881,7 +2818,7 @@ BucketStorageBackend::PrepareEviction(
             // Watermark eviction passes a synthetic required_size to drive
             // quota-based cleanup. It is not a real incoming write, so it
             // should not be counted as physical disk free-space demand.
-            uint64_t req_sz = (!write_keys.empty() && required_size > 0)
+            uint64_t req_sz = (!result.write_keys.empty() && required_size > 0)
                                   ? static_cast<uint64_t>(required_size)
                                   : 0;
             initial_disk_full = actual_available < req_sz + kMinFreeSpace;
@@ -2903,6 +2840,32 @@ BucketStorageBackend::PrepareEviction(
     uint64_t accumulated_freed_space = 0;
     const int64_t synthetic_required_size =
         write_keys.empty() ? required_size : 0;
+    // On-disk footprint of the incoming write (~required_size); 0 for
+    // watermark-driven eviction, which has no incoming write. Added to the
+    // physical check below so we free enough room for THIS write, not merely
+    // enough to bring current usage back under the cap.
+    const int64_t incoming_physical_size =
+        write_keys.empty() ? 0 : required_size;
+
+    // Ground-truth physical usage of the offload directory (cached),
+    // snapshotted once. As buckets are selected for eviction their files get
+    // deleted in the later FinalizeEviction, so (physical_used_start -
+    // accumulated_freed_space) projects the physical bytes that will remain
+    // after this round.
+    const int64_t physical_used_start =
+        bucket_backend_config_.max_physical_bytes > 0
+            ? ActualDiskBytesUsedLocked()
+            : 0;
+    // True when the projected physical usage after this round — real disk usage
+    // minus what we free here, plus the incoming write — would still exceed the
+    // physical cap. Shared by the in-loop "keep evicting" test and the
+    // post-loop "reject the write" test.
+    const auto phys_over_cap = [&](uint64_t freed) {
+        return bucket_backend_config_.max_physical_bytes > 0 &&
+               physical_used_start + incoming_physical_size -
+                       static_cast<int64_t>(freed) >
+                   bucket_backend_config_.max_physical_bytes;
+    };
 
     while (!buckets_.empty() && evict_count < kMaxEvictionBuckets) {
         bool quota_exceeded = total_size_ + pending_eviction_size_ +
@@ -2913,11 +2876,18 @@ BucketStorageBackend::PrepareEviction(
         bool disk_still_full =
             initial_disk_full && (accumulated_freed_space < deficit);
 
-        if (!quota_exceeded && !disk_still_full) break;
+        // Physical hard cap on real on-disk usage (not total_size_, which
+        // under-counts lingering bucket files, and not fs::space(), which is
+        // blind to cgroup/emptyDir quotas).
+        bool phys_exceeded = phys_over_cap(accumulated_freed_space);
+
+        if (!quota_exceeded && !disk_still_full && !phys_exceeded) break;
 
         if (evict_count == 0) {
             LOG(INFO) << "[Evict] triggered: total=" << total_size_ << "/"
                       << bucket_backend_config_.max_total_size
+                      << " physical=" << physical_used_start << "/"
+                      << bucket_backend_config_.max_physical_bytes
                       << " required=" << required_size
                       << " disk_full=" << initial_disk_full;
         }
@@ -2931,7 +2901,10 @@ BucketStorageBackend::PrepareEviction(
         buckets_.erase(evict_it);
 
         int64_t evicted_size = evict_meta->meta_size;
-        // Remove all keys belonging to this bucket from the object map.
+        // Remove all keys belonging to this bucket from the object map, and
+        // report ONLY those to the master: a key skipped as a duplicate at
+        // commit time keeps pointing at its authoritative bucket, so
+        // reporting it here would make the master drop a live replica.
         for (const auto& key : evict_meta->keys) {
             auto obj_it = object_bucket_map_.find(key);
             if (obj_it != object_bucket_map_.end() &&
@@ -2941,16 +2914,13 @@ BucketStorageBackend::PrepareEviction(
                 total_size_ -= object_size;
                 evicted_size += object_size;
                 object_bucket_map_.erase(obj_it);
+                pending_eviction_keys_.insert(key);
+                result.keys.push_back(key);
             }
         }
         total_size_ -= evict_meta->meta_size;
         result.evicted_size += evicted_size;
 
-        // Collect for notification and file deletion.
-        for (const auto& key : evict_meta->keys) {
-            pending_eviction_keys_.insert(key);
-            result.keys.push_back(key);
-        }
         accumulated_freed_space +=
             static_cast<uint64_t>(evict_meta->data_size) +
             static_cast<uint64_t>(evict_meta->meta_size);
@@ -2962,8 +2932,12 @@ BucketStorageBackend::PrepareEviction(
                                     pending_write_size_ +
                                     synthetic_required_size >
                                 bucket_backend_config_.max_total_size;
+    // Physical cap still exceeded after evicting up to kMaxEvictionBuckets:
+    // reject the write (FILE_WRITE_FAIL, handled as an offload miss upstream)
+    // rather than overrun the disk quota and get OOM-evicted.
+    const bool phys_exceeded = phys_over_cap(accumulated_freed_space);
     pending_eviction_size_ += result.evicted_size;
-    if (!write_keys.empty() && quota_exceeded) {
+    if (!result.write_keys.empty() && (quota_exceeded || phys_exceeded)) {
         RestorePreparedEvictionLocked(std::move(result));
         return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
     }
@@ -2991,6 +2965,8 @@ void BucketStorageBackend::RestorePreparedEvictionLocked(
     for (const auto& key : pending.keys) {
         pending_eviction_keys_.erase(key);
     }
+    const std::unordered_set<std::string> restore_keys(pending.keys.begin(),
+                                                       pending.keys.end());
     for (auto& [bucket_id, bucket_meta] : pending.buckets) {
         if (!bucket_meta || buckets_.find(bucket_id) != buckets_.end()) {
             continue;
@@ -2998,6 +2974,11 @@ void BucketStorageBackend::RestorePreparedEvictionLocked(
 
         for (size_t i = 0; i < bucket_meta->keys.size(); ++i) {
             const auto& key = bucket_meta->keys[i];
+            if (restore_keys.find(key) == restore_keys.end()) {
+                // matched-only mirror of the prepare phase: skipped duplicates
+                // stay pointed at their authoritative bucket, never re-pointed
+                continue;
+            }
             const auto& object_meta = bucket_meta->metadatas[i];
             object_bucket_map_[key] = StorageObjectMetadata{
                 bucket_id, object_meta.offset, object_meta.key_size,
@@ -3127,10 +3108,18 @@ tl::expected<void, ErrorCode> BucketStorageBackend::FinalizeEviction(
         if (bucket_cleanup_failed) {
             cleanup_failed_count++;
         }
+        VLOG(1) << "Evicted bucket with id: " << bucket_id
+                << ", policy: " << bucket_backend_config_.eviction_policy;
     }
     if (!pending.buckets.empty()) {
         LOG(INFO) << "[Evict] finalized: attempted=" << pending.buckets.size()
                   << " cleanup_failed=" << cleanup_failed_count;
+        // Files were just deleted; force the next physical-usage query to
+        // rescan rather than return the now-stale (higher) cached value.
+        {
+            SharedMutexLocker lock(&mutex_);
+            cached_disk_bytes_ = -1;
+        }
     }
     if (cleanup_failed_count != 0) {
         return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
@@ -3608,6 +3597,22 @@ tl::expected<void, ErrorCode> OffsetAllocatorStorageBackend::Init() {
             return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
         }
 
+#ifdef USE_URING
+        // O_DIRECT vector I/O rounds writes up to 4 KiB. An unaligned capacity
+        // can let an end-of-file write grow the data file past capacity_, after
+        // which recovery's exact size check rejects the file.
+        constexpr uint64_t kDirectIoAlignment = 4096;
+        if (file_storage_config_.use_uring &&
+            (capacity_ % kDirectIoAlignment) != 0) {
+            LOG(ERROR)
+                << "Invalid capacity for OffsetAllocatorStorageBackend with "
+                   "uring/O_DIRECT: "
+                << capacity_ << ". Capacity must be a multiple of "
+                << kDirectIoAlignment;
+            return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+        }
+#endif
+
         // Ensure storage path exists
         {
             std::error_code ec;
@@ -3749,6 +3754,11 @@ tl::expected<void, ErrorCode> OffsetAllocatorStorageBackend::Init() {
 
         // Open/truncate data file in read-write mode
         int flags = O_CLOEXEC | O_RDWR | O_CREAT | O_TRUNC;
+#ifdef USE_URING
+        if (file_storage_config_.use_uring) {
+            flags |= O_DIRECT;
+        }
+#endif
         int raw_fd = open(data_file_path_.c_str(), flags, 0644);
         if (raw_fd < 0) {
             LOG(ERROR) << "Failed to open data file: " << data_file_path_;
@@ -4524,6 +4534,11 @@ OffsetAllocatorStorageBackend::TryRecoverFromMetadata() {
         // Open data file without truncation
         data_file_path_ = GetDataFilePath();
         int flags = O_CLOEXEC | O_RDWR;
+#ifdef USE_URING
+        if (file_storage_config_.use_uring) {
+            flags |= O_DIRECT;
+        }
+#endif
         int raw_fd = open(data_file_path_.c_str(), flags, 0644);
         if (raw_fd < 0) {
             const int open_errno = errno;
@@ -5472,8 +5487,13 @@ void OffsetAllocatorStorageBackend::RemoveAll() {
     // BatchLoad/BatchStore that pinned the old data_file_ keeps it alive until
     // its I/O completes — no use-after-free.
     if (!data_file_path_.empty()) {
-        int fd = open(data_file_path_.c_str(),
-                      O_CLOEXEC | O_RDWR | O_CREAT | O_TRUNC, 0644);
+        int flags = O_CLOEXEC | O_RDWR | O_CREAT | O_TRUNC;
+#ifdef USE_URING
+        if (file_storage_config_.use_uring) {
+            flags |= O_DIRECT;
+        }
+#endif
+        int fd = open(data_file_path_.c_str(), flags, 0644);
         if (fd >= 0) {
 #ifdef USE_URING
             if (file_storage_config_.use_uring) {
@@ -5530,6 +5550,9 @@ CreateStorageBackend(const FileStorageConfig& config) {
             return std::make_shared<OffsetAllocatorStorageBackend>(
                 config, offset_backend_config);
         }
+        case StorageBackendType::kNvmeKv:
+            return std::make_shared<NvmeKvStorageBackend>(config);
+
         case StorageBackendType::kDistributed: {
             auto distributed_config =
                 DistributedStorageConfig::FromEnvironment();
@@ -5537,18 +5560,31 @@ CreateStorageBackend(const FileStorageConfig& config) {
                 throw std::invalid_argument(
                     "Invalid DistributedStorage configuration");
             }
-            std::unique_ptr<FileSystemAdapter> adapter;
-            if (distributed_config.fs_adapter_type == "hf3fs") {
+            std::unique_ptr<FileSystemAdapter> fs_adapter;
+            std::unique_ptr<ObjectStorageAdapter> object_storage_adapter;
+            if (distributed_config.fs_adapter_type == "posix") {
+                fs_adapter = std::make_unique<PosixFsAdapter>();
+            } else if (distributed_config.fs_adapter_type == "hf3fs") {
 #ifdef USE_3FS
-                adapter = std::make_unique<Hf3fsAdapter>();
+                fs_adapter = std::make_unique<Hf3fsAdapter>();
+#else
+                return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
+#endif
+            } else if (distributed_config.fs_adapter_type == "oss") {
+#ifdef HAVE_OSS_ADAPTER
+                object_storage_adapter =
+                    std::make_unique<OssObjectStorageAdapter>(
+                        distributed_config.fsdir);
 #else
+                LOG(ERROR) << "OSS adapter requires libcurl and OpenSSL";
                 return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
 #endif
             } else {
                 return tl::make_unexpected(ErrorCode::INVALID_PARAMS);
             }
             return std::make_shared<DistributedStorageBackend>(
-                config, distributed_config, std::move(adapter));
+                config, distributed_config, std::move(fs_adapter),
+                std::move(object_storage_adapter));
         }
         default: {
             LOG(ERROR) << "Unsupported backend type: "
diff --git a/mooncake-store/src/store_c.cpp b/mooncake-store/src/store_c.cpp
index a3a19086ef..a60b1c9533 100644
--- a/mooncake-store/src/store_c.cpp
+++ b/mooncake-store/src/store_c.cpp
@@ -17,6 +17,7 @@
 #include <cstring>
 #include <memory>
 #include <new>
+#include <optional>
 #include <span>
 #include <string>
 #include <vector>
@@ -38,13 +39,23 @@ inline const char *c_str_or(const char *s, const char *fallback) {
     return s ? s : fallback;
 }
 
-mooncake::ReplicateConfig to_replicate_config(
+std::optional<mooncake::ReplicateConfig> to_replicate_config(
     const mooncake_replicate_config_t *c_config) {
     mooncake::ReplicateConfig config;
     if (!c_config) return config;
 
+    const int action = c_config->soft_pin_action;
+    // Reject before casting: the enum's uint8_t underlying type would
+    // otherwise wrap out-of-range values into valid actions.
+    if (action < static_cast<int>(mooncake::SoftPinAction::PRESERVE) ||
+        action > static_cast<int>(mooncake::SoftPinAction::DISABLE)) {
+        return std::nullopt;
+    }
     config.replica_num = c_config->replica_num;
-    config.with_soft_pin = c_config->with_soft_pin != 0;
+    config.soft_pin_action = static_cast<mooncake::SoftPinAction>(action);
+    if (c_config->has_soft_pin_ttl) {
+        config.soft_pin_ttl_ms = c_config->soft_pin_ttl_ms;
+    }
     config.with_hard_pin = c_config->with_hard_pin != 0;
     if (c_config->preferred_segments &&
         c_config->preferred_segments_count > 0) {
@@ -149,8 +160,9 @@ int mooncake_store_put(mooncake_store_t store, const char *key,
     if (!value && size > 0) return -1;
     try {
         auto rc = to_replicate_config(config);
+        if (!rc) return -1;
         std::span<const char> data(static_cast<const char *>(value), size);
-        return as_client(store)->put(key, data, rc);
+        return as_client(store)->put(key, data, *rc);
     } catch (...) {
         return -1;
     }
@@ -163,7 +175,8 @@ int mooncake_store_put_from(mooncake_store_t store, const char *key,
     if (!buffer && size > 0) return -1;
     try {
         auto rc = to_replicate_config(config);
-        return as_client(store)->put_from(key, buffer, size, rc);
+        if (!rc) return -1;
+        return as_client(store)->put_from(key, buffer, size, *rc);
     } catch (...) {
         return -1;
     }
@@ -188,8 +201,9 @@ int mooncake_store_batch_put_from(mooncake_store_t store, const char **keys,
         std::vector<size_t> size_vec(sizes, sizes + count);
 
         auto rc = to_replicate_config(config);
+        if (!rc) return -1;
         auto results =
-            as_client(store)->batch_put_from(key_vec, buf_vec, size_vec, rc);
+            as_client(store)->batch_put_from(key_vec, buf_vec, size_vec, *rc);
 
         for (size_t i = 0; i < count; ++i) {
             results_out[i] = (i < results.size()) ? results[i] : -1;
diff --git a/mooncake-store/src/task_manager.cpp b/mooncake-store/src/task_manager.cpp
index 4a1e2b3724..d2aacb06fa 100644
--- a/mooncake-store/src/task_manager.cpp
+++ b/mooncake-store/src/task_manager.cpp
@@ -1,7 +1,7 @@
 #include "task_manager.h"
 #include <glog/logging.h>
 #include <msgpack.hpp>
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake {
 
@@ -76,18 +76,23 @@ std::vector<Task> ScopedTaskWriteAccess::pop_tasks(const UUID& client_id,
         const UUID task_id = queue.front();
         queue.pop();
 
-        if (manager_->total_pending_tasks_ > 0) {
-            manager_->total_pending_tasks_--;
-        }
-
         auto it = manager_->all_tasks_.find(task_id);
         if (it == manager_->all_tasks_.end()) {
             LOG(ERROR) << "Task " << task_id
                        << " not found in all_tasks_ while popping";
+            if (manager_->total_pending_tasks_ > 0) {
+                manager_->total_pending_tasks_--;
+            }
             continue;
         }
 
         Task& task = it->second;
+        if (task.status != TaskStatus::PENDING) {
+            continue;
+        }
+        if (manager_->total_pending_tasks_ > 0) {
+            manager_->total_pending_tasks_--;
+        }
         task.mark_processing();
 
         const auto [_, inserted] = processing_set.insert(task_id);
@@ -279,6 +284,26 @@ void ScopedTaskWriteAccess::restore_task(Task&& task) {
     }
 }
 
+ErrorCode ScopedTaskWriteAccess::fail_task_if_pending(
+    const UUID& task_id, const std::string& message) {
+    auto it = manager_->all_tasks_.find(task_id);
+    if (it == manager_->all_tasks_.end()) {
+        return ErrorCode::TASK_NOT_FOUND;
+    }
+
+    Task& task = it->second;
+    if (task.status != TaskStatus::PENDING) {
+        return ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS;
+    }
+
+    task.mark_complete(TaskStatus::FAILED, message);
+    if (manager_->total_pending_tasks_ > 0) {
+        manager_->total_pending_tasks_--;
+    }
+    manager_->finished_task_history_.push_back(task_id);
+    return ErrorCode::OK;
+}
+
 void ScopedTaskWriteAccess::clear_all() {
     manager_->all_tasks_.clear();
     manager_->pending_tasks_.clear();
diff --git a/mooncake-store/src/tenant_quota.cpp b/mooncake-store/src/tenant_quota.cpp
index fbd7372927..14c73ca176 100644
--- a/mooncake-store/src/tenant_quota.cpp
+++ b/mooncake-store/src/tenant_quota.cpp
@@ -1,6 +1,7 @@
 #include "tenant_quota.h"
 
 #include <algorithm>
+#include <cassert>
 #include <limits>
 
 namespace mooncake {
@@ -12,11 +13,16 @@ struct RemainderShare {
     unsigned __int128 remainder = 0;
 };
 
-uint64_t SaturatingAdd(uint64_t lhs, uint64_t rhs) {
-    if (lhs > std::numeric_limits<uint64_t>::max() - rhs) {
-        return std::numeric_limits<uint64_t>::max();
-    }
-    return lhs + rhs;
+TenantQuotaResult AccountingMismatch() {
+    return tl::make_unexpected(TenantQuotaError::kAccountingMismatch);
+}
+
+TenantQuotaChargeResult ChargeFailure(TenantQuotaError error,
+                                      uint64_t deficit_bytes = 0) {
+    return tl::make_unexpected(TenantQuotaChargeFailure{
+        .error = error,
+        .deficit_bytes = deficit_bytes,
+    });
 }
 
 std::map<TenantId, uint64_t> BuildEffectiveQuotaAssignmentsImpl(
@@ -78,11 +84,150 @@ std::map<TenantId, uint64_t> BuildEffectiveQuotaAssignmentsImpl(
     return assigned;
 }
 
-TenantQuotaResult AccountingMismatch() {
-    return tl::make_unexpected(TenantQuotaError::kAccountingMismatch);
+}  // namespace
+
+TenantQuotaChargeResult TenantQuotaAccount::TryCharge(uint64_t bytes) {
+    if (bytes > kMaxChargedBytes) {
+        return ChargeFailure(TenantQuotaError::kInvalidArgument);
+    }
+
+    for (;;) {
+        const uint64_t sequence_before =
+            policy_sequence_.load(std::memory_order_acquire);
+        if (sequence_before & 1) {
+            continue;
+        }
+
+        uint64_t expected = charged_state_.load(std::memory_order_acquire);
+        if (expected & kAdmissionClosed) {
+            const uint64_t sequence_after =
+                policy_sequence_.load(std::memory_order_acquire);
+            if (sequence_before == sequence_after && !(sequence_after & 1)) {
+                return ChargeFailure(TenantQuotaError::kTenantNotRegistered);
+            }
+            continue;
+        }
+
+        const uint64_t charged_bytes = expected & kChargedBytesMask;
+        const uint64_t effective_quota_bytes =
+            effective_quota_bytes_.load(std::memory_order_acquire);
+        if (bytes != 0 && (charged_bytes > effective_quota_bytes ||
+                           bytes > effective_quota_bytes - charged_bytes)) {
+            const uint64_t sequence_after =
+                policy_sequence_.load(std::memory_order_acquire);
+            if (sequence_before == sequence_after && !(sequence_after & 1)) {
+                const unsigned __int128 demand =
+                    static_cast<unsigned __int128>(charged_bytes) + bytes;
+                const unsigned __int128 deficit =
+                    demand - effective_quota_bytes;
+                return ChargeFailure(
+                    TenantQuotaError::kQuotaExceeded,
+                    deficit > std::numeric_limits<uint64_t>::max()
+                        ? std::numeric_limits<uint64_t>::max()
+                        : static_cast<uint64_t>(deficit));
+            }
+            continue;
+        }
+
+        if (bytes != 0) {
+            const uint64_t desired = charged_bytes + bytes;
+            if (!charged_state_.compare_exchange_weak(
+                    expected, desired, std::memory_order_acq_rel,
+                    std::memory_order_acquire)) {
+                continue;
+            }
+        }
+
+        const uint64_t state_after =
+            charged_state_.load(std::memory_order_acquire);
+        const uint64_t sequence_after =
+            policy_sequence_.load(std::memory_order_acquire);
+        if (sequence_before == sequence_after && !(sequence_after & 1) &&
+            !(state_after & kAdmissionClosed)) {
+            return {};
+        }
+
+        if (bytes != 0) {
+            auto release_result = Release(bytes);
+            if (!release_result) {
+                return ChargeFailure(release_result.error());
+            }
+        }
+    }
 }
 
-}  // namespace
+TenantQuotaResult TenantQuotaAccount::Release(uint64_t bytes) {
+    if (bytes == 0) {
+        return {};
+    }
+
+    uint64_t expected = charged_state_.load(std::memory_order_acquire);
+    for (;;) {
+        const uint64_t charged_bytes = expected & kChargedBytesMask;
+        if (bytes > charged_bytes) {
+            return AccountingMismatch();
+        }
+
+        const uint64_t desired =
+            (expected & kAdmissionClosed) | (charged_bytes - bytes);
+        if (charged_state_.compare_exchange_weak(expected, desired,
+                                                 std::memory_order_acq_rel,
+                                                 std::memory_order_acquire)) {
+            return {};
+        }
+    }
+}
+
+uint64_t TenantQuotaAccount::ChargedBytes() const {
+    return charged_state_.load(std::memory_order_acquire) & kChargedBytesMask;
+}
+
+uint64_t TenantQuotaAccount::EffectiveQuotaBytes() const {
+    return effective_quota_bytes_.load(std::memory_order_acquire);
+}
+
+bool TenantQuotaAccount::AdmissionClosed() const {
+    return charged_state_.load(std::memory_order_acquire) & kAdmissionClosed;
+}
+
+void TenantQuotaAccount::BeginPolicyUpdate() {
+    const uint64_t previous =
+        policy_sequence_.fetch_add(1, std::memory_order_acq_rel);
+    assert((previous & 1) == 0);
+    (void)previous;
+}
+
+void TenantQuotaAccount::EndPolicyUpdate() {
+    const uint64_t previous =
+        policy_sequence_.fetch_add(1, std::memory_order_release);
+    assert((previous & 1) != 0);
+    (void)previous;
+}
+
+void TenantQuotaAccount::SetAdmissionClosed(bool closed) {
+    uint64_t expected = charged_state_.load(std::memory_order_acquire);
+    for (;;) {
+        const uint64_t desired =
+            closed ? expected | kAdmissionClosed : expected & kChargedBytesMask;
+        if (charged_state_.compare_exchange_weak(expected, desired,
+                                                 std::memory_order_acq_rel,
+                                                 std::memory_order_acquire)) {
+            return;
+        }
+    }
+}
+
+void TenantQuotaAccount::ApplyEffectiveQuota(uint64_t effective_quota_bytes) {
+    effective_quota_bytes_.store(effective_quota_bytes,
+                                 std::memory_order_release);
+    SetAdmissionClosed(!has_explicit_policy_);
+}
+
+void TenantQuotaAccount::SetChargedBytesForRebuild(uint64_t charged_bytes) {
+    assert(charged_bytes <= kMaxChargedBytes);
+    charged_state_.store(charged_bytes | kAdmissionClosed,
+                         std::memory_order_release);
+}
 
 std::map<TenantId, uint64_t> TenantQuotaTable::BuildEffectiveQuotaAssignments(
     const std::vector<TenantQuotaSnapshot>& tenants,
@@ -93,79 +238,87 @@ std::map<TenantId, uint64_t> TenantQuotaTable::BuildEffectiveQuotaAssignments(
 
 TenantQuotaResult TenantQuotaTable::UpsertTenantPolicy(
     const TenantId& tenant_id, uint64_t requested_quota_bytes) {
-    if (requested_quota_bytes == 0) {
+    if (requested_quota_bytes == 0 ||
+        requested_quota_bytes > TenantQuotaAccount::kMaxChargedBytes) {
         return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
     }
 
-    auto& state = GetOrCreateState(tenant_id);
-    state.requested_quota_bytes = requested_quota_bytes;
-    state.has_explicit_policy = true;
-    RefreshOverQuota(&state);
+    auto& account = GetOrCreateAccount(tenant_id);
+    account.BeginPolicyUpdate();
+    account.SetAdmissionClosed(true);
+    account.requested_quota_bytes_ = requested_quota_bytes;
+    account.has_explicit_policy_ = true;
+    account.EndPolicyUpdate();
     return {};
 }
 
-TenantQuotaPolicyResult TenantQuotaTable::DisableTenantPolicyIfEmpty(
+TenantQuotaResult TenantQuotaTable::DisableTenantPolicyIfEmpty(
     const TenantId& tenant_id) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || !it->second.has_explicit_policy) {
+    auto it = accounts_.find(tenant_id);
+    if (it == accounts_.end() || !it->second->has_explicit_policy_) {
         return tl::make_unexpected(TenantQuotaError::kTenantNotFound);
     }
 
-    auto& state = it->second;
-    if (state.used_bytes != 0 || state.reserved_bytes != 0 ||
-        state.committed_count != 0 || state.metadata_object_count != 0) {
+    auto& account = *it->second;
+    account.BeginPolicyUpdate();
+    account.SetAdmissionClosed(true);
+    if (account.ChargedBytes() != 0) {
+        account.SetAdmissionClosed(false);
+        account.EndPolicyUpdate();
         return tl::make_unexpected(TenantQuotaError::kTenantNotEmpty);
     }
 
-    const uint64_t requested_quota_bytes = state.requested_quota_bytes;
-    state.requested_quota_bytes = 0;
-    state.effective_quota_bytes = 0;
-    state.has_explicit_policy = false;
-    RefreshOverQuota(&state);
-    EraseIfLazyEmpty(it);
-    return requested_quota_bytes;
+    account.requested_quota_bytes_ = 0;
+    account.effective_quota_bytes_.store(0, std::memory_order_release);
+    account.has_explicit_policy_ = false;
+    account.EndPolicyUpdate();
+    return {};
 }
 
-void TenantQuotaTable::ApplyTenantPolicies(
+TenantQuotaResult TenantQuotaTable::ApplyTenantPolicies(
     const TenantQuotaPolicyMap& policies) {
-    for (auto it = tenants_.begin(); it != tenants_.end();) {
-        auto policy_it = policies.find(it->first);
-        auto& state = it->second;
-        if (policy_it != policies.end()) {
-            state.requested_quota_bytes = policy_it->second;
-            state.has_explicit_policy = true;
-            RefreshOverQuota(&state);
-            ++it;
-            continue;
+    for (const auto& [_, requested_quota_bytes] : policies) {
+        if (requested_quota_bytes == 0 ||
+            requested_quota_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+            return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
         }
+    }
 
-        state.requested_quota_bytes = 0;
-        state.effective_quota_bytes = 0;
-        state.has_explicit_policy = false;
-        if (IsLazyEmptyTenant(state)) {
-            it = tenants_.erase(it);
+    for (auto& [tenant_id, account_ptr] : accounts_) {
+        auto& account = *account_ptr;
+        auto policy_it = policies.find(tenant_id);
+        account.BeginPolicyUpdate();
+        account.SetAdmissionClosed(true);
+        if (policy_it == policies.end()) {
+            account.requested_quota_bytes_ = 0;
+            account.effective_quota_bytes_.store(0, std::memory_order_release);
+            account.has_explicit_policy_ = false;
         } else {
-            RefreshOverQuota(&state);
-            ++it;
+            account.requested_quota_bytes_ = policy_it->second;
+            account.has_explicit_policy_ = true;
         }
+        account.EndPolicyUpdate();
     }
 
     for (const auto& [tenant_id, requested_quota_bytes] : policies) {
-        auto [it, inserted] = tenants_.try_emplace(tenant_id);
-        if (!inserted) {
+        auto& account = GetOrCreateAccount(tenant_id);
+        if (account.has_explicit_policy_) {
             continue;
         }
-        it->second.requested_quota_bytes = requested_quota_bytes;
-        it->second.has_explicit_policy = true;
-        RefreshOverQuota(&it->second);
+        account.BeginPolicyUpdate();
+        account.SetAdmissionClosed(true);
+        account.requested_quota_bytes_ = requested_quota_bytes;
+        account.has_explicit_policy_ = true;
+        account.EndPolicyUpdate();
     }
+    return {};
 }
 
 TenantQuotaPolicyMap TenantQuotaTable::GetTenantPolicies() const {
     TenantQuotaPolicyMap policies;
-    for (const auto& [tenant_id, state] : tenants_) {
-        if (state.has_explicit_policy) {
-            policies.emplace(tenant_id, state.requested_quota_bytes);
+    for (const auto& [tenant_id, account] : accounts_) {
+        if (account->has_explicit_policy_) {
+            policies.emplace(tenant_id, account->requested_quota_bytes_);
         }
     }
     return policies;
@@ -178,259 +331,97 @@ void TenantQuotaTable::RecomputeEffectiveQuotas(
 }
 
 bool TenantQuotaTable::IsTenantRegistered(const TenantId& tenant_id) const {
-    auto it = tenants_.find(tenant_id);
-    return it != tenants_.end() && it->second.has_explicit_policy;
+    auto it = accounts_.find(tenant_id);
+    return it != accounts_.end() && it->second->has_explicit_policy_;
+}
+
+TenantQuotaHandle TenantQuotaTable::GetOrCreateTenantHandle(
+    const TenantId& tenant_id) {
+    return &GetOrCreateAccount(tenant_id);
 }
 
 std::optional<TenantQuotaSnapshot> TenantQuotaTable::GetTenantSnapshot(
     const TenantId& tenant_id) const {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end()) {
+    auto it = accounts_.find(tenant_id);
+    if (it == accounts_.end() || (!it->second->has_explicit_policy_ &&
+                                  it->second->ChargedBytes() == 0)) {
         return std::nullopt;
     }
-    return MakeSnapshot(it->first, it->second);
+    return MakeSnapshot(it->first, *it->second);
 }
 
 std::vector<TenantQuotaSnapshot> TenantQuotaTable::ListTenantSnapshots() const {
     std::vector<TenantQuotaSnapshot> snapshots;
-    snapshots.reserve(tenants_.size());
-    for (const auto& [tenant_id, state] : tenants_) {
-        if (!IsLazyEmptyTenant(state)) {
-            snapshots.push_back(MakeSnapshot(tenant_id, state));
+    snapshots.reserve(accounts_.size());
+    for (const auto& [tenant_id, account] : accounts_) {
+        if (!account->has_explicit_policy_ && account->ChargedBytes() == 0) {
+            continue;
         }
+        snapshots.push_back(MakeSnapshot(tenant_id, *account));
     }
     return snapshots;
 }
 
-uint64_t TenantQuotaTable::ComputeDeficit(const TenantId& tenant_id,
-                                          uint64_t incoming_bytes) const {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end()) {
-        return incoming_bytes;
-    }
-
-    const auto& state = it->second;
-    const unsigned __int128 demand =
-        static_cast<unsigned __int128>(state.used_bytes) +
-        state.reserved_bytes + incoming_bytes;
-    if (demand <= state.effective_quota_bytes) {
-        return 0;
-    }
-
-    const unsigned __int128 deficit = demand - state.effective_quota_bytes;
-    return deficit > std::numeric_limits<uint64_t>::max()
-               ? std::numeric_limits<uint64_t>::max()
-               : static_cast<uint64_t>(deficit);
-}
-
-TenantQuotaResult TenantQuotaTable::Reserve(const TenantId& tenant_id,
-                                            uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || !it->second.has_explicit_policy) {
-        return tl::make_unexpected(TenantQuotaError::kTenantNotRegistered);
-    }
-    if (bytes == 0) {
-        return {};
-    }
-
-    auto& state = it->second;
-    if (static_cast<unsigned __int128>(state.used_bytes) +
-            state.reserved_bytes + bytes >
-        state.effective_quota_bytes) {
-        return tl::make_unexpected(TenantQuotaError::kQuotaExceeded);
-    }
-
-    state.reserved_bytes += bytes;
-    RefreshOverQuota(&state);
-    return {};
-}
-
-TenantQuotaResult TenantQuotaTable::Commit(const TenantId& tenant_id,
-                                           uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.reserved_bytes < bytes) {
-        return AccountingMismatch();
-    }
-    if (bytes == 0) {
-        return {};
-    }
-
-    auto& state = it->second;
-    state.reserved_bytes -= bytes;
-    state.used_bytes = SaturatingAdd(state.used_bytes, bytes);
-    if (state.committed_count < std::numeric_limits<uint64_t>::max()) {
-        ++state.committed_count;
-    }
-    RefreshOverQuota(&state);
-    return {};
-}
-
-TenantQuotaResult TenantQuotaTable::CommitAdditional(const TenantId& tenant_id,
-                                                     uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.reserved_bytes < bytes) {
-        return AccountingMismatch();
-    }
-    if (bytes == 0) {
-        return {};
+TenantQuotaResult TenantQuotaTable::RebuildUsage(
+    const TenantQuotaUsageMap& usage) {
+    for (const auto& [_, charged_bytes] : usage) {
+        if (charged_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+            return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
+        }
     }
 
-    auto& state = it->second;
-    state.reserved_bytes -= bytes;
-    state.used_bytes = SaturatingAdd(state.used_bytes, bytes);
-    RefreshOverQuota(&state);
-    return {};
-}
-
-TenantQuotaResult TenantQuotaTable::Abort(const TenantId& tenant_id,
-                                          uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.reserved_bytes < bytes) {
-        return AccountingMismatch();
+    for (auto& [_, account] : accounts_) {
+        account->BeginPolicyUpdate();
+        account->SetChargedBytesForRebuild(0);
+        account->EndPolicyUpdate();
     }
-    if (bytes == 0) {
-        return {};
-    }
-
-    it->second.reserved_bytes -= bytes;
-    RefreshOverQuota(&it->second);
-    EraseIfLazyEmpty(it);
-    return {};
-}
 
-TenantQuotaResult TenantQuotaTable::Release(const TenantId& tenant_id,
-                                            uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.used_bytes < bytes ||
-        (bytes != 0 && it->second.committed_count == 0)) {
-        return AccountingMismatch();
-    }
-    if (bytes == 0) {
-        return {};
-    }
-
-    auto& state = it->second;
-    state.used_bytes -= bytes;
-    --state.committed_count;
-    RefreshOverQuota(&state);
-    EraseIfLazyEmpty(it);
-    return {};
-}
-
-TenantQuotaResult TenantQuotaTable::ReleasePartial(const TenantId& tenant_id,
-                                                   uint64_t bytes) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.used_bytes < bytes) {
-        return AccountingMismatch();
-    }
-    if (bytes == 0) {
-        return {};
+    for (const auto& [tenant_id, charged_bytes] : usage) {
+        auto& account = GetOrCreateAccount(tenant_id);
+        if (!account.has_explicit_policy_) {
+            account.requested_quota_bytes_ = 0;
+            account.effective_quota_bytes_.store(0, std::memory_order_release);
+        }
+        account.BeginPolicyUpdate();
+        account.SetChargedBytesForRebuild(charged_bytes);
+        account.EndPolicyUpdate();
     }
-
-    it->second.used_bytes -= bytes;
-    RefreshOverQuota(&it->second);
-    EraseIfLazyEmpty(it);
     return {};
 }
 
-void TenantQuotaTable::IncrementMetadataObjectCount(const TenantId& tenant_id) {
-    auto& state = GetOrCreateState(tenant_id);
-    if (state.metadata_object_count < std::numeric_limits<uint64_t>::max()) {
-        ++state.metadata_object_count;
-    }
-    RefreshOverQuota(&state);
-}
-
-TenantQuotaResult TenantQuotaTable::DecrementMetadataObjectCount(
+TenantQuotaAccount& TenantQuotaTable::GetOrCreateAccount(
     const TenantId& tenant_id) {
-    auto it = tenants_.find(tenant_id);
-    if (it == tenants_.end() || it->second.metadata_object_count == 0) {
-        return AccountingMismatch();
-    }
-
-    --it->second.metadata_object_count;
-    RefreshOverQuota(&it->second);
-    EraseIfLazyEmpty(it);
-    return {};
-}
-
-void TenantQuotaTable::RebuildUsage(const TenantQuotaUsageMap& usage) {
-    for (auto& [_, state] : tenants_) {
-        state.used_bytes = 0;
-        state.reserved_bytes = 0;
-        state.committed_count = 0;
-        state.metadata_object_count = 0;
-    }
-
-    for (const auto& [tenant_id, tenant_usage] : usage) {
-        auto& state = GetOrCreateState(tenant_id);
-        if (!state.has_explicit_policy) {
-            state.requested_quota_bytes = 0;
-            state.effective_quota_bytes = 0;
-        }
-        state.used_bytes = tenant_usage.used_bytes;
-        state.committed_count = tenant_usage.committed_count;
-        state.metadata_object_count = tenant_usage.metadata_object_count;
-        RefreshOverQuota(&state);
-    }
-
-    for (auto it = tenants_.begin(); it != tenants_.end();) {
-        if (IsLazyEmptyTenant(it->second)) {
-            it = tenants_.erase(it);
-        } else {
-            RefreshOverQuota(&it->second);
-            ++it;
-        }
+    auto [it, inserted] = accounts_.try_emplace(tenant_id);
+    if (inserted) {
+        it->second = std::make_unique<TenantQuotaAccount>();
     }
-}
-
-TenantQuotaTable::TenantQuotaState& TenantQuotaTable::GetOrCreateState(
-    const TenantId& tenant_id) {
-    return tenants_.try_emplace(tenant_id).first->second;
+    return *it->second;
 }
 
 TenantQuotaSnapshot TenantQuotaTable::MakeSnapshot(
-    const TenantId& tenant_id, const TenantQuotaState& state) const {
+    const TenantId& tenant_id, const TenantQuotaAccount& account) const {
+    const uint64_t charged_bytes = account.ChargedBytes();
+    const uint64_t effective_quota_bytes = account.EffectiveQuotaBytes();
     return TenantQuotaSnapshot{
         .tenant_id = tenant_id,
-        .requested_quota_bytes = state.requested_quota_bytes,
-        .effective_quota_bytes = state.effective_quota_bytes,
-        .used_bytes = state.used_bytes,
-        .reserved_bytes = state.reserved_bytes,
-        .committed_count = state.committed_count,
-        .metadata_object_count = state.metadata_object_count,
-        .has_explicit_policy = state.has_explicit_policy,
-        .over_quota = state.over_quota,
+        .requested_quota_bytes = account.requested_quota_bytes_,
+        .effective_quota_bytes = effective_quota_bytes,
+        .charged_bytes = charged_bytes,
+        .admission_closed = account.AdmissionClosed(),
+        .has_explicit_policy = account.has_explicit_policy_,
+        .over_quota = charged_bytes > effective_quota_bytes,
     };
 }
 
-bool TenantQuotaTable::IsLazyEmptyTenant(const TenantQuotaState& state) {
-    return !state.has_explicit_policy && state.used_bytes == 0 &&
-           state.reserved_bytes == 0 && state.committed_count == 0 &&
-           state.metadata_object_count == 0;
-}
-
-void TenantQuotaTable::RefreshOverQuota(TenantQuotaState* state) {
-    state->over_quota =
-        (!state->has_explicit_policy && state->metadata_object_count > 0) ||
-        static_cast<unsigned __int128>(state->used_bytes) +
-                state->reserved_bytes >
-            state->effective_quota_bytes;
-}
-
 void TenantQuotaTable::ApplyEffectiveQuotas(
     const std::map<TenantId, uint64_t>& effective_quotas) {
-    for (auto& [tenant_id, state] : tenants_) {
+    for (auto& [tenant_id, account] : accounts_) {
         auto it = effective_quotas.find(tenant_id);
-        state.effective_quota_bytes =
+        const uint64_t effective_quota_bytes =
             it == effective_quotas.end() ? 0 : it->second;
-        RefreshOverQuota(&state);
-    }
-}
-
-void TenantQuotaTable::EraseIfLazyEmpty(StateMap::iterator it) {
-    if (IsLazyEmptyTenant(it->second)) {
-        tenants_.erase(it);
+        account->BeginPolicyUpdate();
+        account->ApplyEffectiveQuota(effective_quota_bytes);
+        account->EndPolicyUpdate();
     }
 }
 
diff --git a/mooncake-store/src/tenant_quota_ledger.cpp b/mooncake-store/src/tenant_quota_ledger.cpp
new file mode 100644
index 0000000000..33d3dbe7d8
--- /dev/null
+++ b/mooncake-store/src/tenant_quota_ledger.cpp
@@ -0,0 +1,196 @@
+#include "tenant_quota_ledger.h"
+
+#include <limits>
+
+namespace mooncake {
+namespace {
+
+TenantQuotaResult InvalidArgument() {
+    return tl::make_unexpected(TenantQuotaError::kInvalidArgument);
+}
+
+TenantQuotaResult AccountingMismatch() {
+    return tl::make_unexpected(TenantQuotaError::kAccountingMismatch);
+}
+
+bool AddOverflows(uint64_t lhs, uint64_t rhs) {
+    return rhs > TenantQuotaAccount::kMaxChargedBytes ||
+           lhs > TenantQuotaAccount::kMaxChargedBytes - rhs;
+}
+
+}  // namespace
+
+TenantQuotaResult TenantQuotaLedger::AdoptPendingCharge(
+    TenantQuotaHandle account, uint64_t bytes) {
+    if (account == nullptr || bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return InvalidArgument();
+    }
+    if (pending_bytes_ != 0 || AddOverflows(TotalChargedBytes(), bytes)) {
+        return AccountingMismatch();
+    }
+    pending_bytes_ = bytes;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::SettlePrimaryWrite(
+    TenantQuotaHandle account, uint64_t actual_committed_bytes) {
+    if (account == nullptr ||
+        actual_committed_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return InvalidArgument();
+    }
+    if (AddOverflows(pending_bytes_, committed_bytes_)) {
+        return AccountingMismatch();
+    }
+    const uint64_t primary_bytes = pending_bytes_ + committed_bytes_;
+    if (actual_committed_bytes > primary_bytes ||
+        AddOverflows(primary_bytes, replaced_bytes_)) {
+        return AccountingMismatch();
+    }
+
+    const uint64_t total_bytes = primary_bytes + replaced_bytes_;
+    auto release_result =
+        account->Release(total_bytes - actual_committed_bytes);
+    if (!release_result) {
+        return release_result;
+    }
+    pending_bytes_ = 0;
+    committed_bytes_ = actual_committed_bytes;
+    replaced_bytes_ = 0;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::SettleAdditional(TenantQuotaHandle account,
+                                                      uint64_t pending_bytes,
+                                                      uint64_t actual_bytes) {
+    if (account == nullptr ||
+        pending_bytes > TenantQuotaAccount::kMaxChargedBytes ||
+        actual_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return InvalidArgument();
+    }
+    if (actual_bytes > pending_bytes ||
+        AddOverflows(committed_bytes_, actual_bytes) ||
+        AddOverflows(TotalChargedBytes(), actual_bytes)) {
+        return AccountingMismatch();
+    }
+
+    auto release_result = account->Release(pending_bytes - actual_bytes);
+    if (!release_result) {
+        return release_result;
+    }
+    committed_bytes_ += actual_bytes;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::RefundPending(TenantQuotaHandle account) {
+    if (account == nullptr) {
+        return InvalidArgument();
+    }
+    if (pending_bytes_ == 0) {
+        return AccountingMismatch();
+    }
+    auto release_result = account->Release(pending_bytes_);
+    if (!release_result) {
+        return release_result;
+    }
+    pending_bytes_ = 0;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::ReleaseCommitted(TenantQuotaHandle account,
+                                                      uint64_t bytes) {
+    if (account == nullptr || bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return InvalidArgument();
+    }
+    if (bytes == 0) {
+        return {};
+    }
+    if (bytes > committed_bytes_) {
+        return AccountingMismatch();
+    }
+    auto release_result = account->Release(bytes);
+    if (!release_result) {
+        return release_result;
+    }
+    committed_bytes_ -= bytes;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::TransferReplacementCharge(
+    TenantQuotaHandle account, TenantQuotaLedger& destination) {
+    if (account == nullptr || this == &destination) {
+        return InvalidArgument();
+    }
+    if (pending_bytes_ != 0 || destination.replaced_bytes_ != 0 ||
+        AddOverflows(committed_bytes_, replaced_bytes_)) {
+        return AccountingMismatch();
+    }
+
+    const uint64_t transfer_bytes = committed_bytes_ + replaced_bytes_;
+    if (transfer_bytes == 0 ||
+        AddOverflows(destination.TotalChargedBytes(), transfer_bytes)) {
+        return AccountingMismatch();
+    }
+    destination.replaced_bytes_ = transfer_bytes;
+    committed_bytes_ = 0;
+    replaced_bytes_ = 0;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::ReleaseReplacement(
+    TenantQuotaHandle account) {
+    if (account == nullptr) {
+        return InvalidArgument();
+    }
+    if (replaced_bytes_ == 0) {
+        return AccountingMismatch();
+    }
+    auto release_result = account->Release(replaced_bytes_);
+    if (!release_result) {
+        return release_result;
+    }
+    replaced_bytes_ = 0;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::ReleaseAll(TenantQuotaHandle account) {
+    if (account == nullptr) {
+        return InvalidArgument();
+    }
+    const uint64_t total_bytes = TotalChargedBytes();
+    if (total_bytes == 0) {
+        return AccountingMismatch();
+    }
+    auto release_result = account->Release(total_bytes);
+    if (!release_result) {
+        return release_result;
+    }
+    pending_bytes_ = 0;
+    committed_bytes_ = 0;
+    replaced_bytes_ = 0;
+    return {};
+}
+
+TenantQuotaResult TenantQuotaLedger::Rebuild(TenantQuotaHandle account,
+                                             uint64_t committed_bytes) {
+    if (account == nullptr ||
+        committed_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return InvalidArgument();
+    }
+    pending_bytes_ = 0;
+    committed_bytes_ = committed_bytes;
+    replaced_bytes_ = 0;
+    return {};
+}
+
+uint64_t TenantQuotaLedger::TotalChargedBytes() const {
+    if (AddOverflows(pending_bytes_, committed_bytes_)) {
+        return std::numeric_limits<uint64_t>::max();
+    }
+    const uint64_t pending_and_committed = pending_bytes_ + committed_bytes_;
+    if (AddOverflows(pending_and_committed, replaced_bytes_)) {
+        return std::numeric_limits<uint64_t>::max();
+    }
+    return pending_and_committed + replaced_bytes_;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/src/tenant_quota_policy_store.cpp b/mooncake-store/src/tenant_quota_policy_store.cpp
index 1b3db9147a..5420f15020 100644
--- a/mooncake-store/src/tenant_quota_policy_store.cpp
+++ b/mooncake-store/src/tenant_quota_policy_store.cpp
@@ -1,5 +1,7 @@
 #include "tenant_quota_policy_store.h"
 
+#include "tenant_quota.h"
+
 #include <cerrno>
 #include <chrono>
 #include <cstring>
@@ -211,7 +213,12 @@ tl::expected<uint64_t, std::string> ParseTenantQuotaBytes(
     if (number > std::numeric_limits<uint64_t>::max() / multiplier) {
         return tl::make_unexpected("quota byte value overflows uint64");
     }
-    return number * multiplier;
+    const uint64_t quota_bytes = number * multiplier;
+    if (quota_bytes > TenantQuotaAccount::kMaxChargedBytes) {
+        return tl::make_unexpected(
+            "quota exceeds maximum supported tenant charge");
+    }
+    return quota_bytes;
 }
 
 tl::expected<TenantQuotaPolicySnapshot, std::string> ParseTenantQuotaPolicyYaml(
diff --git a/mooncake-store/src/transfer_task.cpp b/mooncake-store/src/transfer_task.cpp
index ca7faef384..49b4bb5e95 100644
--- a/mooncake-store/src/transfer_task.cpp
+++ b/mooncake-store/src/transfer_task.cpp
@@ -8,9 +8,12 @@
 #include <cerrno>
 #include <cstring>
 #include <cstdlib>
+#include <limits>
 #include <sstream>
 #include <string>
 #include <vector>
+#include "config/transfer_submitter_config.h"
+#include "config/fileread_worker_pool_config.h"
 #include "device/accelerator_registry.h"
 #include "transfer_engine.h"
 #include "transport/transport.h"
@@ -19,6 +22,26 @@
 #endif
 
 #ifdef USE_NOF
+static int GetPositiveEnvOrDefault(const char* name, int default_value) {
+    const char* raw_value = std::getenv(name);
+    if (!raw_value || raw_value[0] == '\0') {
+        return default_value;
+    }
+
+    errno = 0;
+    char* end_ptr = nullptr;
+    long parsed = std::strtol(raw_value, &end_ptr, 10);
+    if (errno != 0 || end_ptr == raw_value ||
+        (end_ptr != nullptr && *end_ptr != '\0') || parsed <= 0 ||
+        parsed > std::numeric_limits<int>::max()) {
+        LOG(WARNING) << "Invalid value for " << name << ": " << raw_value
+                     << ", using default " << default_value;
+        return default_value;
+    }
+
+    return static_cast<int>(parsed);
+}
+
 static bool IsTruthyEnv(const char* value) {
     if (!value) {
         return false;
@@ -53,26 +76,6 @@ static int GetSpdkNofDebugIntervalMs() {
     return interval_ms;
 }
 
-static int GetPositiveEnvOrDefault(const char* name, int default_value) {
-    const char* raw_value = std::getenv(name);
-    if (!raw_value || raw_value[0] == '\0') {
-        return default_value;
-    }
-
-    errno = 0;
-    char* end_ptr = nullptr;
-    long parsed = std::strtol(raw_value, &end_ptr, 10);
-    if (errno != 0 || end_ptr == raw_value ||
-        (end_ptr != nullptr && *end_ptr != '\0') || parsed <= 0 ||
-        parsed > std::numeric_limits<int>::max()) {
-        LOG(WARNING) << "Invalid value for " << name << ": " << raw_value
-                     << ", using default " << default_value;
-        return default_value;
-    }
-
-    return static_cast<int>(parsed);
-}
-
 static int GetSpdkNofSubmitChunkBytes() {
     static const int value = GetPositiveEnvOrDefault(
         "MC_NOF_SUBMIT_CHUNK_BYTES", mooncake::kDefaultSpdkNofSubmitChunkBytes);
@@ -173,18 +176,15 @@ SpdkNofQos::SpdkNofQos(uint32_t block_size) {
 // ============================================================================
 // FilereadWorkerPool Implementation
 // ============================================================================
-// to fully utilize the available ssd bandwidth, we use a default of 10 worker
-// threads.
-constexpr int kDefaultFilereadWorkers = 10;
-
 FilereadWorkerPool::FilereadWorkerPool(std::shared_ptr<StorageBackend>& backend)
     : shutdown_(false) {
-    VLOG(1) << "Creating FilereadWorkerPool with " << kDefaultFilereadWorkers
-            << " workers";
+    static const auto config = FilereadWorkerPoolConfig::FromEnvironment();
+    const int num_workers = config.worker_count;
+    VLOG(1) << "Creating FilereadWorkerPool with " << num_workers << " workers";
 
     // Start worker threads
-    workers_.reserve(kDefaultFilereadWorkers);
-    for (int i = 0; i < kDefaultFilereadWorkers; ++i) {
+    workers_.reserve(num_workers);
+    for (int i = 0; i < num_workers; ++i) {
         workers_.emplace_back(&FilereadWorkerPool::workerThread, this);
     }
     backend_ = backend;
@@ -820,60 +820,67 @@ void TransferEngineOperationState::wait_for_completion() {
     constexpr int64_t timeout_milliseconds = 60 * 1000;
 
 #ifdef USE_EVENT_DRIVEN_COMPLETION
-    VLOG(1) << "Waiting for transfer engine completion for batch " << batch_id_;
-
-    // Wait directly on BatchDesc's condition variable.
-    auto& batch_desc = Transport::toBatchDesc(batch_id_);
-    bool completed;
-    bool failed = false;
-
-    // Fast path: if already finished, avoid taking the mutex and waiting.
-    // Use acquire here to pair with the writer's release-store, because this
-    // path may skip taking the mutex. It ensures all prior updates are visible.
-    completed = batch_desc.is_finished.load(std::memory_order_acquire);
-    if (!completed) {
-        // Use the same mutex as the notifier when updating the predicate to
-        // avoid missed notifications. The predicate is re-checked under the
-        // lock. Under the mutex, relaxed is sufficient; the mutex acquire
-        // orders prior writes.
-        std::unique_lock<std::mutex> lock(batch_desc.completion_mutex);
-        const int64_t elapsed_milliseconds =
-            getCurrentTimeInMilli() - start_ts_;
-        if (elapsed_milliseconds < timeout_milliseconds) {
-            completed = batch_desc.completion_cv.wait_for(
-                lock,
-                std::chrono::milliseconds(timeout_milliseconds -
-                                          elapsed_milliseconds),
-                [&batch_desc] {
-                    return batch_desc.is_finished.load(
-                        std::memory_order_relaxed);
-                });
-        }
-    }  // Explicitly release completion_mutex before acquiring mutex_
+    // TENT batches do not use the classic transport BatchDesc layout.
+    if (!engine_.isUsingTent()) {
+        VLOG(1) << "Waiting for transfer engine completion for batch "
+                << batch_id_;
 
-    // Once completion is observed, read failure flag.
-    if (completed) {
-        failed = batch_desc.has_failure.load(std::memory_order_relaxed);
-    }
+        // Wait directly on BatchDesc's condition variable.
+        auto& batch_desc = Transport::toBatchDesc(batch_id_);
+        bool completed;
+        bool failed = false;
+
+        // Fast path: if already finished, avoid taking the mutex and waiting.
+        // Use acquire here to pair with the writer's release-store, because
+        // this path may skip taking the mutex. It ensures all prior updates are
+        // visible.
+        completed = batch_desc.is_finished.load(std::memory_order_acquire);
+        if (!completed) {
+            // Use the same mutex as the notifier when updating the predicate to
+            // avoid missed notifications. The predicate is re-checked under the
+            // lock. Under the mutex, relaxed is sufficient; the mutex acquire
+            // orders prior writes.
+            std::unique_lock<std::mutex> lock(batch_desc.completion_mutex);
+            const int64_t elapsed_milliseconds =
+                getCurrentTimeInMilli() - start_ts_;
+            if (elapsed_milliseconds < timeout_milliseconds) {
+                completed = batch_desc.completion_cv.wait_for(
+                    lock,
+                    std::chrono::milliseconds(timeout_milliseconds -
+                                              elapsed_milliseconds),
+                    [&batch_desc] {
+                        return batch_desc.is_finished.load(
+                            std::memory_order_relaxed);
+                    });
+            }
+        }  // Explicitly release completion_mutex before acquiring mutex_
 
-    ErrorCode error_code =
-        completed ? (failed ? ErrorCode::TRANSFER_FAIL : ErrorCode::OK)
-                  : ErrorCode::TRANSFER_FAIL;
+        // Once completion is observed, read failure flag.
+        if (completed) {
+            failed = batch_desc.has_failure.load(std::memory_order_relaxed);
+        }
 
-    {
-        std::lock_guard<std::mutex> lock(mutex_);
-        set_result_internal(error_code);
-    }
+        ErrorCode error_code =
+            completed ? (failed ? ErrorCode::TRANSFER_FAIL : ErrorCode::OK)
+                      : ErrorCode::TRANSFER_FAIL;
 
-    if (completed) {
-        VLOG(1) << "Transfer engine operation completed for batch " << batch_id_
-                << " with result: " << static_cast<int>(error_code);
-    } else {
-        LOG(ERROR) << "Failed to complete transfers after "
-                   << timeout_milliseconds << " milliseconds for batch "
-                   << batch_id_;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            set_result_internal(error_code);
+        }
+
+        if (completed) {
+            VLOG(1) << "Transfer engine operation completed for batch "
+                    << batch_id_
+                    << " with result: " << static_cast<int>(error_code);
+        } else {
+            LOG(ERROR) << "Failed to complete transfers after "
+                       << timeout_milliseconds << " milliseconds for batch "
+                       << batch_id_;
+        }
+        return;
     }
-#else
+#endif
     VLOG(1) << "Starting transfer engine polling for batch " << batch_id_;
 
     while (true) {
@@ -897,7 +904,6 @@ void TransferEngineOperationState::wait_for_completion() {
         VLOG(1) << "Transfer engine operation still pending for batch "
                 << batch_id_;
     }
-#endif
 }
 
 // ============================================================================
@@ -949,29 +955,15 @@ TransferSubmitter::TransferSubmitter(TransferEngine& engine,
     // When not set, auto-detect based on transport type:
     //   - TCP-only environment: enable memcpy (avoids TCP loopback overhead)
     //   - RDMA/other transports: disable memcpy (RDMA is more efficient)
-    const char* env_value = std::getenv("MC_STORE_MEMCPY");
-    if (env_value == nullptr) {
+    const auto config = TransferSubmitterConfig::FromEnvironment();
+    if (config.memcpy_enabled_override.has_value()) {
+        memcpy_enabled_ = *config.memcpy_enabled_override;
+    } else {
         memcpy_enabled_ = engine_.isTcpOnly();
         LOG(INFO) << "MC_STORE_MEMCPY not set, auto-detected: "
                   << (memcpy_enabled_ ? "TCP-only environment, memcpy enabled"
                                       : "non-TCP transport available, memcpy "
                                         "disabled");
-    } else {
-        std::string env_str(env_value);
-        // Convert to lowercase for case-insensitive comparison
-        std::transform(env_str.begin(), env_str.end(), env_str.begin(),
-                       [](unsigned char c) { return std::tolower(c); });
-        if (env_str == "false" || env_str == "0" || env_str == "no" ||
-            env_str == "off") {
-            memcpy_enabled_ = false;
-        } else if (env_str == "true" || env_str == "1" || env_str == "yes" ||
-                   env_str == "on") {
-            memcpy_enabled_ = true;
-        } else {
-            LOG(WARNING) << "Invalid value for MC_STORE_MEMCPY: " << env_str
-                         << ", defaulting to enabled";
-            memcpy_enabled_ = true;
-        }
     }
 
     VLOG(1) << "TransferSubmitter initialized with memcpy_enabled="
@@ -1039,16 +1031,44 @@ std::optional<TransferFuture> TransferSubmitter::submit_batch(
     const std::vector<Replica::Descriptor>& replicas,
     std::vector<std::vector<Slice>>& all_slices,
     TransferRequest::OpCode op_code) {
-    std::optional<TransferFuture> future;
+    if (replicas.size() != all_slices.size()) {
+        LOG(ERROR) << "Mismatched replicas and slice lists";
+        return std::nullopt;
+    }
+
+    bool use_local_memcpy =
+        op_code == TransferRequest::WRITE && !replicas.empty();
+    size_t operation_count = 0;
+    for (size_t i = 0; i < replicas.size(); ++i) {
+        if (!replicas[i].is_memory_replica()) {
+            LOG(ERROR) << "Batch transfer only supports memory replicas";
+            return std::nullopt;
+        }
+        const auto& handle =
+            replicas[i].get_memory_descriptor().buffer_descriptor;
+        if (!validateTransferParams(handle, all_slices[i])) {
+            return std::nullopt;
+        }
+        use_local_memcpy =
+            use_local_memcpy && canUseLocalMemcpy(handle.transport_endpoint_);
+        operation_count += all_slices[i].size();
+    }
+
     std::vector<TransferRequest> requests;
+    std::vector<MemcpyOperation> memcpy_operations;
+    if (use_local_memcpy)
+        memcpy_operations.reserve(operation_count);
+    else
+        requests.reserve(operation_count);
     for (size_t i = 0; i < replicas.size(); ++i) {
-        auto& replica = replicas[i];
         auto& slices = all_slices[i];
-        auto& mem_desc = replica.get_memory_descriptor();
-        if (!validateTransferParams(mem_desc.buffer_descriptor, slices)) {
-            return std::nullopt;
+        const auto& handle =
+            replicas[i].get_memory_descriptor().buffer_descriptor;
+        if (use_local_memcpy) {
+            appendMemcpyOperations(handle, slices, op_code, 0,
+                                   memcpy_operations);
+            continue;
         }
-        auto& handle = mem_desc.buffer_descriptor;
         uint64_t offset = 0;
         SegmentHandle seg = engine_.openSegment(handle.transport_endpoint_);
         if (seg == static_cast<uint64_t>(ERR_INVALID_ARGUMENT)) {
@@ -1056,7 +1076,7 @@ std::optional<TransferFuture> TransferSubmitter::submit_batch(
                        << handle.transport_endpoint_;
             return std::nullopt;
         }
-        for (auto slice : slices) {
+        for (const auto& slice : slices) {
             TransferRequest request;
             request.opcode = op_code;
             request.source = static_cast<char*>(slice.ptr);
@@ -1067,7 +1087,9 @@ std::optional<TransferFuture> TransferSubmitter::submit_batch(
             offset += slice.size;
         }
     }
-    future = submitTransfer(requests);
+    auto future = use_local_memcpy
+                      ? submitMemcpyOperations(std::move(memcpy_operations))
+                      : submitTransfer(requests);
     // Update metrics on successful submission
     if (future.has_value()) {
         for (auto& slices : all_slices) {
@@ -1086,81 +1108,112 @@ std::optional<TransferFuture>
 TransferSubmitter::submit_batch_get_offload_object(
     const std::string& transfer_engine_addr,
     const std::vector<std::string>& keys, const std::vector<uint64_t>& pointers,
-    const std::unordered_map<std::string, std::vector<Slice>>& batched_slices) {
-    std::optional<TransferFuture> future;
-    std::vector<TransferRequest> requests;
-    // Open the segment once — all keys share the same transfer_engine_addr.
-    SegmentHandle seg = engine_.openSegment(transfer_engine_addr);
-    if (seg == static_cast<uint64_t>(ERR_INVALID_ARGUMENT)) {
-        LOG(ERROR) << "Failed to open segment " << transfer_engine_addr;
-        // nullopt = failure (caller checks !future).  The function returns
-        // std::optional so tl::unexpected is not available here.
+    const std::unordered_map<std::string, std::vector<Slice>>& batched_slices,
+    OffloadBufferAccess buffer_access) {
+    if (keys.size() != pointers.size()) {
+        LOG(ERROR) << "Mismatched offload transfer argument counts";
+        return std::nullopt;
+    }
+
+    const bool use_local_memcpy =
+        buffer_access == OffloadBufferAccess::kLocalAddress;
+    if (use_local_memcpy && !canUseLocalMemcpy(transfer_engine_addr)) {
+        LOG(ERROR) << "Offload source is not locally addressable: "
+                   << transfer_engine_addr;
         return std::nullopt;
     }
+
+    std::vector<TransferRequest> requests;
+    std::vector<MemcpyOperation> operations;
+    constexpr uint64_t kMaxAddress = std::numeric_limits<uint64_t>::max();
+    SegmentHandle seg = 0;
+    if (!use_local_memcpy) {
+        // Open once: all keys share the same transfer endpoint.
+        seg = engine_.openSegment(transfer_engine_addr);
+        if (seg == static_cast<uint64_t>(ERR_INVALID_ARGUMENT)) {
+            LOG(ERROR) << "Failed to open segment " << transfer_engine_addr;
+            return std::nullopt;
+        }
+    }
+
     for (size_t i = 0; i < keys.size(); ++i) {
         const auto& key = keys[i];
-        const uint64_t pointer = pointers[i];
         auto it = batched_slices.find(key);
         if (it == batched_slices.end()) {
             LOG(ERROR) << "Key not found in batched_slices: " << key;
-            return std::nullopt;  // fail closed
+            return std::nullopt;
         }
-        // Emit one TransferRequest per slice: the on-disk blob is read
-        // sequentially while slices may point to non-contiguous GPU memory.
         uint64_t offset = 0;
         for (const auto& slice : it->second) {
-            TransferRequest request;
-            request.opcode = TransferRequest::READ;
-            request.source = static_cast<char*>(slice.ptr);
-            request.target_id = seg;
-            request.target_offset = pointer + offset;
-            request.length = slice.size;
-            requests.emplace_back(request);
+            if (slice.size == 0) continue;
+            if (!slice.ptr || pointers[i] > kMaxAddress - offset ||
+                slice.size > kMaxAddress - pointers[i] - offset) {
+                LOG(ERROR) << "Invalid offload transfer range for key: " << key;
+                return std::nullopt;
+            }
+            if (use_local_memcpy) {
+                operations.emplace_back(
+                    slice.ptr,
+                    reinterpret_cast<const void*>(pointers[i] + offset),
+                    slice.size);
+            } else {
+                requests.emplace_back(TransferRequest{
+                    .opcode = TransferRequest::READ,
+                    .source = static_cast<char*>(slice.ptr),
+                    .target_id = seg,
+                    .target_offset = pointers[i] + offset,
+                    .length = slice.size,
+                });
+            }
             offset += slice.size;
         }
     }
-    return submitTransfer(requests);
+    return use_local_memcpy ? submitMemcpyOperations(std::move(operations))
+                            : submitTransfer(requests);
 }
 
-std::optional<TransferFuture> TransferSubmitter::submitMemcpyOperation(
+void TransferSubmitter::appendMemcpyOperations(
     const AllocatedBuffer::Descriptor& handle, const std::vector<Slice>& slices,
-    const TransferRequest::OpCode op_code, uint64_t src_offset) {
-    auto state = std::make_shared<MemcpyOperationState>();
-
-    // Create memcpy operations
-    std::vector<MemcpyOperation> operations;
-    operations.reserve(slices.size());
+    const TransferRequest::OpCode op_code, uint64_t buffer_offset,
+    std::vector<MemcpyOperation>& operations) {
     uint64_t base_address = static_cast<uint64_t>(handle.buffer_address_);
-    uint64_t offset = src_offset;
-
-    for (size_t i = 0; i < slices.size(); ++i) {
-        const auto& slice = slices[i];
+    uint64_t offset = buffer_offset;
 
+    for (const auto& slice : slices) {
         if (slice.ptr == nullptr) continue;
 
         void* dest;
         const void* src;
-
         if (op_code == TransferRequest::READ) {
-            // READ: from handle (remote buffer) to slice (local buffer)
             dest = slice.ptr;
             src = reinterpret_cast<const void*>(base_address + offset);
         } else {
-            // WRITE: from slice (local buffer) to handle (remote buffer)
             dest = reinterpret_cast<void*>(base_address + offset);
             src = slice.ptr;
         }
         offset += slice.size;
-
         operations.emplace_back(dest, src, slice.size);
     }
+}
 
-    // Submit memcpy operations to worker pool for async execution
+std::optional<TransferFuture> TransferSubmitter::submitMemcpyOperation(
+    const AllocatedBuffer::Descriptor& handle, const std::vector<Slice>& slices,
+    const TransferRequest::OpCode op_code, uint64_t src_offset) {
+    std::vector<MemcpyOperation> operations;
+    operations.reserve(slices.size());
+    appendMemcpyOperations(handle, slices, op_code, src_offset, operations);
+    return submitMemcpyOperations(std::move(operations));
+}
+
+std::optional<TransferFuture> TransferSubmitter::submitMemcpyOperations(
+    std::vector<MemcpyOperation> operations) {
+    auto state = std::make_shared<MemcpyOperationState>();
+    const size_t operation_count = operations.size();
     MemcpyTask task(std::move(operations), state);
     memcpy_pool_->submitTask(std::move(task));
 
-    VLOG(1) << "Memcpy transfer submitted to worker pool with " << slices.size()
-            << " operations";
+    VLOG(1) << "Memcpy transfer submitted to worker pool with "
+            << operation_count << " operations";
 
     return TransferFuture(state);
 }
@@ -1258,6 +1311,25 @@ std::optional<TransferFuture> TransferSubmitter::submitMemoryReadOperation(
     return std::nullopt;
 }
 
+std::optional<TransferFuture> TransferSubmitter::submitMemoryWriteOperation(
+    const AllocatedBuffer::Descriptor& handle, const std::vector<Slice>& slices,
+    uint64_t dst_offset) {
+    TransferStrategy strategy = selectStrategy(handle, slices);
+
+    if (strategy == TransferStrategy::LOCAL_MEMCPY) {
+        return submitMemcpyOperation(handle, slices, TransferRequest::WRITE,
+                                     dst_offset);
+    }
+    if (strategy == TransferStrategy::TRANSFER_ENGINE) {
+        return submitTransferEngineOperation(
+            handle, slices, TransferRequest::WRITE, dst_offset);
+    }
+
+    LOG(ERROR) << "Write only supports LOCAL_MEMCPY or TRANSFER_ENGINE, got: "
+               << strategy;
+    return std::nullopt;
+}
+
 std::optional<TransferFuture> TransferSubmitter::submitRangeRead(
     const Replica::Descriptor& replica, std::vector<Slice>& slices,
     uint64_t src_offset) {
@@ -1269,7 +1341,8 @@ std::optional<TransferFuture> TransferSubmitter::submitRangeRead(
 
         size_t slices_size = 0;
         for (const auto& s : slices) slices_size += s.size;
-        if (src_offset + slices_size > handle.size_) {
+        if (src_offset > std::numeric_limits<uint64_t>::max() - slices_size ||
+            src_offset + slices_size > handle.size_) {
             LOG(ERROR) << "Range read overflow: src_offset=" << src_offset
                        << " + slices_size=" << slices_size
                        << " > handle.size_=" << handle.size_;
@@ -1293,6 +1366,42 @@ std::optional<TransferFuture> TransferSubmitter::submitRangeRead(
     return future;
 }
 
+std::optional<TransferFuture> TransferSubmitter::submitRangeWrite(
+    const Replica::Descriptor& replica, std::vector<Slice>& slices,
+    uint64_t dst_offset) {
+    std::optional<TransferFuture> future;
+
+    if (replica.is_memory_replica()) {
+        auto& mem_desc = replica.get_memory_descriptor();
+        auto& handle = mem_desc.buffer_descriptor;
+
+        size_t slices_size = 0;
+        for (const auto& s : slices) slices_size += s.size;
+        if (dst_offset > std::numeric_limits<uint64_t>::max() - slices_size ||
+            dst_offset + slices_size > handle.size_) {
+            LOG(ERROR) << "Range write overflow: dst_offset=" << dst_offset
+                       << " + slices_size=" << slices_size
+                       << " > handle.size_=" << handle.size_;
+            return std::nullopt;
+        }
+
+        future = submitMemoryWriteOperation(handle, slices, dst_offset);
+    } else if (replica.is_nof_replica()) {
+        LOG(ERROR) << "Range write not supported for NoF replicas";
+        return std::nullopt;
+    } else if (replica.is_disk_replica() || replica.is_local_disk_replica()) {
+        LOG(ERROR)
+            << "Range write not supported for disk replicas (use full write)";
+        return std::nullopt;
+    }
+
+    if (future.has_value()) {
+        updateTransferMetrics(slices, TransferRequest::WRITE);
+    }
+
+    return future;
+}
+
 #ifdef USE_NOF
 std::optional<TransferFuture> TransferSubmitter::submitSpdkNofOperation(
     const AllocatedBuffer::Descriptor& handle, void* ptr, size_t size,
@@ -1352,50 +1461,17 @@ std::optional<TransferFuture> TransferSubmitter::submitFileReadOperation(
 
 TransferStrategy TransferSubmitter::selectStrategy(
     const AllocatedBuffer::Descriptor& handle,
-    const std::vector<Slice>& slices) const {
-    // Check if memcpy operations are enabled via environment variable
-    if (!memcpy_enabled_) {
-        VLOG(2) << "Memcpy operations disabled via MC_STORE_MEMCPY environment "
-                   "variable";
-        return TransferStrategy::TRANSFER_ENGINE;
-    }
-
-    // Check conditions for local memcpy optimization
-    if (isLocalTransfer(handle)) {
-        return TransferStrategy::LOCAL_MEMCPY;
-    }
-
-    return TransferStrategy::TRANSFER_ENGINE;
+    const std::vector<Slice>& /* slices */) const {
+    return canUseLocalMemcpy(handle.transport_endpoint_)
+               ? TransferStrategy::LOCAL_MEMCPY
+               : TransferStrategy::TRANSFER_ENGINE;
 }
 
-namespace {
-// Helper function to extract IP address from endpoint string (ip:port format).
-// Supports both IPv4 (ip:port) and IPv6 ([ipv6]:port) formats.
-std::string extractIpAddress(const std::string& endpoint) {
-    if (endpoint.empty()) {
-        return "";
-    }
-
-    // Handle IPv6 format: [ipv6]:port
-    if (endpoint[0] == '[') {
-        size_t closing_bracket = endpoint.find(']');
-        if (closing_bracket == std::string::npos) {
-            LOG(WARNING) << "Invalid IPv6 endpoint format: " << endpoint;
-            return "";
-        }
-        return endpoint.substr(1, closing_bracket - 1);
-    }
-
-    // Handle IPv4 or hostname:port format.
-    size_t colon_pos = endpoint.rfind(':');
-    if (colon_pos != std::string::npos) {
-        return endpoint.substr(0, colon_pos);
-    }
-
-    // No colon found, return the whole string (might be just IP or hostname).
-    return endpoint;
+bool TransferSubmitter::canUseLocalMemcpy(const std::string& endpoint) const {
+    return memcpy_enabled_ &&
+           (isSameProcessEndpoint(endpoint, local_hostname_) ||
+            isSameProcessEndpoint(endpoint, local_endpoint_));
 }
-}  // namespace
 
 bool TransferSubmitter::isSameProcessEndpoint(
     const std::string& handle_endpoint, const std::string& local_endpoint) {
@@ -1405,28 +1481,7 @@ bool TransferSubmitter::isSameProcessEndpoint(
     // memcpy on a peer process's address would segfault. Require the full
     // transport endpoint to match, which uniquely identifies the owning
     // process.
-    if (handle_endpoint.empty() || local_endpoint.empty()) {
-        return false;
-    }
-    if (handle_endpoint == local_endpoint) {
-        return true;
-    }
-
-    const std::string handle_ip = extractIpAddress(handle_endpoint);
-    const std::string local_ip = extractIpAddress(local_endpoint);
-    if (!handle_ip.empty() && handle_ip == local_ip) {
-        VLOG(2) << "Disabling local memcpy for same-host endpoints with "
-                   "different process endpoints: handle="
-                << handle_endpoint << ", local=" << local_endpoint;
-    }
-
-    return false;
-}
-
-bool TransferSubmitter::isLocalTransfer(
-    const AllocatedBuffer::Descriptor& handle) const {
-    return isSameProcessEndpoint(handle.transport_endpoint_, local_hostname_) ||
-           isSameProcessEndpoint(handle.transport_endpoint_, local_endpoint_);
+    return !handle_endpoint.empty() && handle_endpoint == local_endpoint;
 }
 
 bool TransferSubmitter::validateTransferParams(
diff --git a/mooncake-store/src/types.cpp b/mooncake-store/src/types.cpp
index 7535abccbf..1956c024c4 100644
--- a/mooncake-store/src/types.cpp
+++ b/mooncake-store/src/types.cpp
@@ -50,6 +50,7 @@ const std::string& toString(ErrorCode errorCode) noexcept {
         {ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS,
          "UNAVAILABLE_IN_CURRENT_STATUS"},
         {ErrorCode::UNAVAILABLE_IN_CURRENT_MODE, "UNAVAILABLE_IN_CURRENT_MODE"},
+        {ErrorCode::NOT_SUPPORTED, "NOT_SUPPORTED"},
         {ErrorCode::FILE_NOT_FOUND, "FILE_NOT_FOUND"},
         {ErrorCode::FILE_OPEN_FAIL, "FILE_OPEN_FAIL"},
         {ErrorCode::FILE_READ_FAIL, "FILE_READ_FAIL"},
diff --git a/mooncake-store/src/uring_file.cpp b/mooncake-store/src/uring_file.cpp
index 02b9137124..f2d8b654eb 100644
--- a/mooncake-store/src/uring_file.cpp
+++ b/mooncake-store/src/uring_file.cpp
@@ -6,9 +6,11 @@
 #include <chrono>
 #include <climits>
 #include <cstring>
+#include <memory>
 #include <string>
 #include <sys/mman.h>
 #include <sys/uio.h>
+#include <thread>
 #include <unistd.h>
 #include <vector>
 
@@ -16,6 +18,7 @@
 #include <liburing.h>
 
 #include "file_interface.h"
+#include "uring_submit.h"
 
 namespace mooncake {
 
@@ -110,6 +113,8 @@ class SharedUringRing {
 
     tl::expected<size_t, ErrorCode> read(int fd, void* buf, size_t len,
                                          off_t off) {
+        if (!initialized_)
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         ensure_buf_registered();
         bool fix = in_registered_buf(buf, len);
         return submit_rw(/*write=*/false, fd, buf, len, off, fix);
@@ -117,40 +122,52 @@ class SharedUringRing {
 
     tl::expected<size_t, ErrorCode> write(int fd, const void* buf, size_t len,
                                           off_t off) {
+        if (!initialized_)
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         return submit_rw(/*write=*/true, fd, const_cast<void*>(buf), len, off,
                          /*use_fixed_buf=*/false);
     }
 
     tl::expected<size_t, ErrorCode> vector_read(int fd, const iovec* iovs,
                                                 int cnt, off_t off) {
+        if (!initialized_)
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         return submit_vector(/*write=*/false, fd, iovs, cnt, off);
     }
 
     tl::expected<size_t, ErrorCode> vector_write(int fd, const iovec* iovs,
                                                  int cnt, off_t off) {
+        if (!initialized_)
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         return submit_vector(/*write=*/true, fd, iovs, cnt, off);
     }
 
     // Descriptor for one independently-addressed read in a batch.
-    struct ReadDesc {
-        void* buf;
-        size_t len;
-        off_t off;
-    };
+    using ReadDesc = UringFile::ReadDesc;
 
     /// Submit up to QUEUE_DEPTH reads at once (each at its own offset), then
     /// collect completions. Repeat until all @p cnt descs are done.
     /// This gives the NVMe device queue depth > 1 within a single thread.
-    tl::expected<size_t, ErrorCode> batch_read(int fd, const ReadDesc* descs,
-                                               int cnt) {
+    tl::expected<void, ErrorCode> batch_read(int fd, ReadDesc* descs, int cnt) {
+        if (!initialized_)
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         ensure_buf_registered();
-        uint64_t op = ++op_id_;
-        size_t total = 0;
+        for (int i = 0; i < cnt; ++i) {
+            descs[i].bytes_read = 0;
+            descs[i].error = ErrorCode::OK;
+            descs[i].completed = false;
+        }
         int remaining = cnt;
         int idx = 0;
 
         while (remaining > 0) {
             int batch = std::min(remaining, static_cast<int>(QUEUE_DEPTH));
+            if (io_uring_sq_space_left(&ring_) < static_cast<unsigned>(batch)) {
+                LOG(ERROR) << "[SharedUringRing] insufficient SQ space for "
+                           << batch << " batch reads";
+                return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+            }
+            uint64_t op = next_operation_tag();
 
             for (int i = 0; i < batch; ++i) {
                 struct io_uring_sqe* sqe = io_uring_get_sqe(&ring_);
@@ -158,21 +175,20 @@ class SharedUringRing {
                     LOG(ERROR) << "[SharedUringRing] SQ full (batch_read)";
                     return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
                 }
-                const auto& d = descs[idx + i];
+                auto& d = descs[idx + i];
                 if (buf_registered_ && in_registered_buf(d.buf, d.len))
                     io_uring_prep_read_fixed(sqe, fd, d.buf, d.len, d.off, 0);
                 else
                     io_uring_prep_read(sqe, fd, d.buf, d.len, d.off);
-                sqe->user_data = op;
+                sqe->user_data = op | static_cast<uint64_t>(i + 1);
             }
 
-            auto res = collect(batch, op);
+            auto res = collect_batch(batch, op, descs + idx);
             if (!res) return res;
-            total += res.value();
             idx += batch;
             remaining -= batch;
         }
-        return total;
+        return {};
     }
 
     /// Issue IORING_FSYNC_DATASYNC.  Blocks until complete.
@@ -185,7 +201,7 @@ class SharedUringRing {
             LOG(ERROR) << "[SharedUringRing] SQ full (fsync)";
             return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         }
-        uint64_t op = ++op_id_;
+        uint64_t op = next_operation_tag();
         io_uring_prep_fsync(sqe, fd, IORING_FSYNC_DATASYNC);
         sqe->user_data = op;
 
@@ -199,28 +215,98 @@ class SharedUringRing {
     // Construction / destruction
     // -----------------------------------------------------------------
 
-    SharedUringRing() {
+    SharedUringRing() { initialize_ring(); }
+
+    ~SharedUringRing() { shutdown_ring(); }
+
+    // -----------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------
+
+    bool initialize_ring() {
+        ring_ = {};
         int ret = io_uring_queue_init(QUEUE_DEPTH, &ring_, 0);
         if (ret < 0) {
             LOG(ERROR) << "[SharedUringRing] io_uring_queue_init failed: "
                        << strerror(-ret);
-            return;
+            return false;
         }
         initialized_ = true;
         LOG(INFO) << "[SharedUringRing] thread-local ring initialised "
                      "queue_depth="
                   << QUEUE_DEPTH;
+        return true;
     }
 
-    ~SharedUringRing() {
+    void shutdown_ring() {
         if (!initialized_) return;
         if (buf_registered_) io_uring_unregister_buffers(&ring_);
         io_uring_queue_exit(&ring_);
+        initialized_ = false;
+        buf_registered_ = false;
+        buf_base_ = nullptr;
+        buf_size_ = 0;
     }
 
-    // -----------------------------------------------------------------
-    // Internal helpers
-    // -----------------------------------------------------------------
+    void reset_ring() {
+        shutdown_ring();
+        if (!initialize_ring()) {
+            LOG(ERROR) << "[SharedUringRing] failed to recover io_uring";
+        }
+    }
+
+    detail::UringSubmitResult submit_pending() {
+        return detail::submit_all_pending(
+            [this] { return io_uring_sq_ready(&ring_); },
+            [this](unsigned pending) {
+                return io_uring_submit_and_wait(&ring_, pending);
+            },
+            [] { std::this_thread::yield(); });
+    }
+
+    bool wait_cqe(struct io_uring_cqe** cqe) {
+        unsigned transient_retries = 0;
+        while (true) {
+            int ret = io_uring_peek_cqe(&ring_, cqe);
+            if (ret == -EAGAIN) ret = io_uring_wait_cqe(&ring_, cqe);
+            if (ret == 0) return true;
+            if ((ret == -EINTR || ret == -EAGAIN) && transient_retries++ < 64) {
+                std::this_thread::yield();
+                continue;
+            }
+            LOG(ERROR) << "[SharedUringRing] CQE wait error: "
+                       << strerror(-ret);
+            return false;
+        }
+    }
+
+    bool drain_submitted(unsigned submitted, uint64_t op_id) {
+        unsigned processed = 0;
+        while (processed < submitted) {
+            struct io_uring_cqe* cqe;
+            if (!wait_cqe(&cqe)) return false;
+            if ((cqe->user_data & ~BATCH_INDEX_MASK) == op_id) ++processed;
+            io_uring_cq_advance(&ring_, 1);
+        }
+        return true;
+    }
+
+    bool prepare_completions(int expected, uint64_t op_id) {
+        auto submit = submit_pending();
+        if (submit.error == 0 && submit.pending == 0 &&
+            submit.submitted == static_cast<unsigned>(expected)) {
+            return true;
+        }
+
+        LOG(ERROR) << "[SharedUringRing] io_uring submission incomplete: "
+                   << "expected=" << expected
+                   << " submitted=" << submit.submitted
+                   << " pending=" << submit.pending
+                   << " error=" << submit.error;
+        drain_submitted(submit.submitted, op_id);
+        reset_ring();
+        return false;
+    }
 
     bool in_registered_buf(const void* buf, size_t len) const {
         if (!buf_registered_ || !buf_base_ || !buf_size_) return false;
@@ -257,6 +343,14 @@ class SharedUringRing {
         return value;
     }
 
+    static constexpr unsigned BATCH_INDEX_BITS = 8;
+    static constexpr uint64_t BATCH_INDEX_MASK =
+        (uint64_t{1} << BATCH_INDEX_BITS) - 1;
+    static_assert(QUEUE_DEPTH <= BATCH_INDEX_MASK,
+                  "QUEUE_DEPTH exceeds batch index capacity");
+
+    uint64_t next_operation_tag() { return (++op_id_) << BATCH_INDEX_BITS; }
+
     // Drain exactly @expected CQEs matching @op_id and
     // accumulate bytes.  Stale CQEs (user_data != op_id, e.g. from
     // a previous batch_read / submit_rw that hit an error and left
@@ -267,10 +361,7 @@ class SharedUringRing {
     // a syscall in the common case.  io_uring_wait_cqe() only kicks
     // in when the ring is unexpectedly drained (stale CQE storms).
     tl::expected<size_t, ErrorCode> collect(int expected, uint64_t op_id) {
-        int ret = io_uring_submit_and_wait(&ring_, expected);
-        if (ret < 0) {
-            LOG(ERROR) << "[SharedUringRing] io_uring_submit_and_wait: "
-                       << strerror(-ret);
+        if (!prepare_completions(expected, op_id)) {
             return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         }
         size_t total = 0;
@@ -279,13 +370,8 @@ class SharedUringRing {
 
         while (processed < expected) {
             struct io_uring_cqe* cqe;
-            int wait_ret = io_uring_peek_cqe(&ring_, &cqe);
-            if (wait_ret == -EAGAIN) {
-                wait_ret = io_uring_wait_cqe(&ring_, &cqe);
-            }
-            if (wait_ret < 0) {
-                LOG(ERROR) << "[SharedUringRing] CQE wait error: "
-                           << strerror(-wait_ret);
+            if (!wait_cqe(&cqe)) {
+                reset_ring();
                 return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
             }
             if (cqe->user_data != op_id) {
@@ -307,6 +393,53 @@ class SharedUringRing {
         return total;
     }
 
+    tl::expected<void, ErrorCode> collect_batch(int expected, uint64_t op_id,
+                                                ReadDesc* descs) {
+        if (!prepare_completions(expected, op_id)) {
+            return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        }
+
+        bool has_error = false;
+        int processed = 0;
+        while (processed < expected) {
+            struct io_uring_cqe* cqe;
+            if (!wait_cqe(&cqe)) {
+                reset_ring();
+                return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+            }
+
+            const uint64_t cqe_op = cqe->user_data & ~BATCH_INDEX_MASK;
+            if (cqe_op != op_id) {
+                io_uring_cq_advance(&ring_, 1);
+                continue;
+            }
+
+            const uint64_t encoded_index = cqe->user_data & BATCH_INDEX_MASK;
+            if (encoded_index == 0 ||
+                encoded_index > static_cast<uint64_t>(expected)) {
+                LOG(ERROR) << "[SharedUringRing] invalid batch CQE index: "
+                           << encoded_index;
+                has_error = true;
+            } else {
+                auto& desc = descs[encoded_index - 1];
+                desc.completed = true;
+                if (cqe->res < 0) {
+                    LOG(ERROR) << "[SharedUringRing] batch CQE error: "
+                               << strerror(-cqe->res);
+                    desc.error = ErrorCode::FILE_READ_FAIL;
+                    has_error = true;
+                } else {
+                    desc.bytes_read = static_cast<size_t>(cqe->res);
+                }
+            }
+            io_uring_cq_advance(&ring_, 1);
+            ++processed;
+        }
+
+        if (has_error) return tl::make_unexpected(ErrorCode::FILE_READ_FAIL);
+        return {};
+    }
+
     // Chunked contiguous read or write.
     tl::expected<size_t, ErrorCode> submit_rw(bool is_write, int fd, void* buf,
                                               size_t len, off_t off,
@@ -315,7 +448,7 @@ class SharedUringRing {
             is_write ? ErrorCode::FILE_WRITE_FAIL : ErrorCode::FILE_READ_FAIL;
         const bool fix_buf = (use_fixed_buf && buf_registered_);
 
-        uint64_t op = ++op_id_;
+        uint64_t op = next_operation_tag();
         char* ptr = static_cast<char*>(buf);
         size_t total = 0;
         size_t remaining = len;
@@ -374,7 +507,7 @@ class SharedUringRing {
             is_write ? ErrorCode::FILE_WRITE_FAIL : ErrorCode::FILE_READ_FAIL;
         const size_t max_io = max_rw_count();
 
-        uint64_t op = ++op_id_;
+        uint64_t op = next_operation_tag();
         size_t total = 0;
         off_t cur = off;
         int remaining = cnt;
@@ -634,32 +767,128 @@ tl::expected<size_t, ErrorCode> UringFile::read_aligned(void* buffer,
 // batch_read — submit multiple independent reads in one ring submission
 // ---------------------------------------------------------------------------
 
-tl::expected<size_t, ErrorCode> UringFile::batch_read(const ReadDesc* descs,
-                                                      int cnt) {
-    if (fd_ < 0) return make_error<size_t>(ErrorCode::FILE_NOT_FOUND);
+tl::expected<void, ErrorCode> UringFile::batch_read(ReadDesc* descs, int cnt) {
+    if (fd_ < 0) return make_error<void>(ErrorCode::FILE_NOT_FOUND);
     if (!descs || cnt <= 0)
-        return make_error<size_t>(ErrorCode::FILE_INVALID_BUFFER);
+        return make_error<void>(ErrorCode::FILE_INVALID_BUFFER);
+
+    for (int i = 0; i < cnt; ++i) {
+        if (!descs[i].buf || descs[i].len == 0)
+            return make_error<void>(ErrorCode::FILE_INVALID_BUFFER);
+        if (use_direct_io_ &&
+            (reinterpret_cast<uintptr_t>(descs[i].buf) % ALIGNMENT_ ||
+             descs[i].len % ALIGNMENT_ || descs[i].off % ALIGNMENT_)) {
+            return make_error<void>(ErrorCode::FILE_INVALID_BUFFER);
+        }
+    }
 
-    // Map UringFile::ReadDesc → SharedUringRing::ReadDesc (same layout, but
-    // ensure they stay in sync if either changes).
-    static_assert(sizeof(ReadDesc) == sizeof(SharedUringRing::ReadDesc),
-                  "ReadDesc layout mismatch");
-    const auto* ring_descs =
-        reinterpret_cast<const SharedUringRing::ReadDesc*>(descs);
-    return SharedUringRing::instance().batch_read(fd_, ring_descs, cnt);
+    return SharedUringRing::instance().batch_read(fd_, descs, cnt);
 }
 
 // ---------------------------------------------------------------------------
 // vector_write / vector_read
 // ---------------------------------------------------------------------------
 
+namespace {
+
+size_t IovecTotalLen(const iovec* iov, int iovcnt) {
+    size_t total = 0;
+    for (int i = 0; i < iovcnt; ++i) total += iov[i].iov_len;
+    return total;
+}
+
+bool IsIovecRegionAligned(const iovec* iov, int iovcnt, off_t offset,
+                          size_t alignment) {
+    if (offset % static_cast<off_t>(alignment) != 0) return false;
+    for (int i = 0; i < iovcnt; ++i) {
+        if (reinterpret_cast<uintptr_t>(iov[i].iov_base) % alignment != 0) {
+            return false;
+        }
+        if (iov[i].iov_len % alignment != 0) return false;
+    }
+    return true;
+}
+
+struct AlignedBufferDeleter {
+    void operator()(void* ptr) const {
+        if (ptr) free(ptr);
+    }
+};
+using AlignedBufferPtr = std::unique_ptr<void, AlignedBufferDeleter>;
+
+void CopyFromIovec(char* dst, const iovec* iov, int iovcnt) {
+    for (int i = 0; i < iovcnt; ++i) {
+        std::memcpy(dst, iov[i].iov_base, iov[i].iov_len);
+        dst += iov[i].iov_len;
+    }
+}
+
+void CopyToIovec(char* src, iovec* iov, int iovcnt) {
+    for (int i = 0; i < iovcnt; ++i) {
+        std::memcpy(iov[i].iov_base, src, iov[i].iov_len);
+        src += iov[i].iov_len;
+    }
+}
+
+}  // namespace
+
 tl::expected<size_t, ErrorCode> UringFile::vector_write(const iovec* iov,
                                                         int iovcnt,
                                                         off_t offset) {
     if (fd_ < 0) return make_error<size_t>(ErrorCode::FILE_NOT_FOUND);
+    if (!iov || iovcnt <= 0)
+        return make_error<size_t>(ErrorCode::FILE_INVALID_BUFFER);
+
+    const size_t total = IovecTotalLen(iov, iovcnt);
+    // Writing nothing is a no-op success.
+    if (total == 0) return 0;
+
     auto start = std::chrono::steady_clock::now();
-    auto res =
-        SharedUringRing::instance().vector_write(fd_, iov, iovcnt, offset);
+    tl::expected<size_t, ErrorCode> res;
+
+    if (!use_direct_io_ ||
+        IsIovecRegionAligned(iov, iovcnt, offset, ALIGNMENT_)) {
+        res =
+            SharedUringRing::instance().vector_write(fd_, iov, iovcnt, offset);
+    } else {
+        const off_t aligned_off = offset & ~static_cast<off_t>(ALIGNMENT_ - 1);
+        const size_t head = static_cast<size_t>(offset - aligned_off);
+        const size_t span = head + total;
+        const size_t aligned_len =
+            ((span + ALIGNMENT_ - 1) / ALIGNMENT_) * ALIGNMENT_;
+
+        AlignedBufferPtr bounce(alloc_aligned_buffer(aligned_len));
+        if (!bounce) return make_error<size_t>(ErrorCode::FILE_WRITE_FAIL);
+
+        // Preserve bytes outside [offset, offset+total) within the aligned
+        // region; otherwise padding would clobber neighboring data.
+        const bool needs_rmw = (head != 0) || (aligned_len != total);
+        if (needs_rmw) {
+            auto read_res = SharedUringRing::instance().read(
+                fd_, bounce.get(), aligned_len, aligned_off);
+            if (!read_res) {
+                // A real read error must not proceed with a zero-filled
+                // bounce buffer — that would silently corrupt neighbors.
+                return make_error<size_t>(ErrorCode::FILE_READ_FAIL);
+            }
+            if (read_res.value() < aligned_len) {
+                // EOF / short read: only zero the unread suffix.
+                std::memset(static_cast<char*>(bounce.get()) + read_res.value(),
+                            0, aligned_len - read_res.value());
+            }
+        }
+        CopyFromIovec(static_cast<char*>(bounce.get()) + head, iov, iovcnt);
+
+        res = SharedUringRing::instance().write(fd_, bounce.get(), aligned_len,
+                                                aligned_off);
+
+        if (res && res.value() >= span) {
+            res = total;
+        } else if (res) {
+            res = make_error<size_t>(ErrorCode::FILE_WRITE_FAIL);
+        }
+    }
+
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
                   std::chrono::steady_clock::now() - start)
                   .count();
@@ -673,13 +902,39 @@ tl::expected<size_t, ErrorCode> UringFile::vector_read(const iovec* iov,
                                                        int iovcnt,
                                                        off_t offset) {
     if (fd_ < 0) return make_error<size_t>(ErrorCode::FILE_NOT_FOUND);
+    if (!iov || iovcnt <= 0)
+        return make_error<size_t>(ErrorCode::FILE_INVALID_BUFFER);
+
+    const size_t expected_bytes = IovecTotalLen(iov, iovcnt);
+    // Reading nothing is a no-op success.
+    if (expected_bytes == 0) return 0;
 
-    size_t expected_bytes = 0;
-    for (int i = 0; i < iovcnt; ++i) expected_bytes += iov[i].iov_len;
     auto start = std::chrono::steady_clock::now();
+    tl::expected<size_t, ErrorCode> res;
+
+    if (!use_direct_io_ ||
+        IsIovecRegionAligned(iov, iovcnt, offset, ALIGNMENT_)) {
+        res = SharedUringRing::instance().vector_read(fd_, iov, iovcnt, offset);
+    } else {
+        const off_t aligned_off = offset & ~static_cast<off_t>(ALIGNMENT_ - 1);
+        const size_t head = static_cast<size_t>(offset - aligned_off);
+        const size_t span = head + expected_bytes;
+        const size_t aligned_len =
+            ((span + ALIGNMENT_ - 1) / ALIGNMENT_) * ALIGNMENT_;
 
-    auto res =
-        SharedUringRing::instance().vector_read(fd_, iov, iovcnt, offset);
+        AlignedBufferPtr bounce(alloc_aligned_buffer(aligned_len));
+        if (!bounce) return make_error<size_t>(ErrorCode::FILE_READ_FAIL);
+
+        res = SharedUringRing::instance().read(fd_, bounce.get(), aligned_len,
+                                               aligned_off);
+        if (res && res.value() >= span) {
+            CopyToIovec(static_cast<char*>(bounce.get()) + head,
+                        const_cast<iovec*>(iov), iovcnt);
+            res = expected_bytes;
+        } else if (res) {
+            res = make_error<size_t>(ErrorCode::FILE_READ_FAIL);
+        }
+    }
 
     auto us = std::chrono::duration_cast<std::chrono::microseconds>(
                   std::chrono::steady_clock::now() - start)
diff --git a/mooncake-store/src/uring_submit.h b/mooncake-store/src/uring_submit.h
new file mode 100644
index 0000000000..b8d499f70b
--- /dev/null
+++ b/mooncake-store/src/uring_submit.h
@@ -0,0 +1,48 @@
+#pragma once
+
+#include <cerrno>
+#include <cstdint>
+
+namespace mooncake::detail {
+
+struct UringSubmitResult {
+    unsigned submitted = 0;
+    unsigned pending = 0;
+    int error = 0;
+};
+
+template <typename PendingFn, typename SubmitFn, typename YieldFn>
+UringSubmitResult submit_all_pending(PendingFn&& pending_fn,
+                                     SubmitFn&& submit_fn, YieldFn&& yield_fn,
+                                     unsigned max_transient_retries = 64) {
+    UringSubmitResult result;
+    unsigned transient_retries = 0;
+
+    while ((result.pending = pending_fn()) != 0) {
+        int ret = submit_fn(result.pending);
+        if (ret > 0) {
+            if (static_cast<unsigned>(ret) > result.pending) {
+                result.error = -EIO;
+                return result;
+            }
+            result.submitted += static_cast<unsigned>(ret);
+            transient_retries = 0;
+            continue;
+        }
+
+        if (ret == -EINTR || ret == -EAGAIN || ret == -ENOMEM) {
+            if (transient_retries++ < max_transient_retries) {
+                yield_fn();
+                continue;
+            }
+        }
+
+        result.error = ret == 0 ? -EIO : ret;
+        result.pending = pending_fn();
+        return result;
+    }
+
+    return result;
+}
+
+}  // namespace mooncake::detail
diff --git a/mooncake-store/src/utils.cpp b/mooncake-store/src/utils.cpp
deleted file mode 100644
index 6b52484d74..0000000000
--- a/mooncake-store/src/utils.cpp
+++ /dev/null
@@ -1,791 +0,0 @@
-#include "utils.h"
-#include "random.h"
-#include "mmap_arena.h"
-#include "config.h"
-#include "common.h"
-#include "ub_allocator.h"
-
-#include "ascii_string.h"
-#include "bool_parser.h"
-#include "environ.h"
-
-#include <Slab.h>
-#include <gflags/gflags.h>
-#include <glog/logging.h>
-#include <ifaddrs.h>
-#include <net/if.h>
-#include <netdb.h>
-#include <netinet/in.h>
-#include <sys/socket.h>
-#include <unistd.h>
-#include <algorithm>
-#include <atomic>
-#include <cerrno>
-#include <csignal>
-#include <cstdlib>
-#include <cstring>
-#include <memory>
-#include <mutex>
-#include <numa.h>
-#include <numaif.h>
-#include <sys/mman.h>
-#include <thread>
-#include <vector>
-#ifdef USE_CUDA
-#include <cuda_runtime.h>
-#endif
-#ifdef USE_INTRA_NVLINK
-#include "gpu_vendor/intra_nvlink.h"
-#endif
-
-// Feature flag to enable/disable arena allocator. Disabled by default so the
-// library does not pre-map a large pool unless the operator opts in via gflag
-// or an explicit MC_MMAP_ARENA_POOL_SIZE environment override.
-DEFINE_bool(use_mmap_arena_allocator, false,
-            "Enable the lock-free mmap arena allocator for mmap buffers");
-
-// Arena pool size (default 8GiB when explicitly enabled without an env
-// override).
-DEFINE_uint64(mmap_arena_pool_size, 8ULL * 1024 * 1024 * 1024,
-              "Arena allocator pool size in bytes");
-#ifdef USE_ASCEND_DIRECT
-#include "acl/acl.h"
-#endif
-#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
-#include "ascend_allocator.h"
-#endif
-#if defined(USE_SUNRISE)
-#include "sunrise_allocator.h"
-#endif
-
-#ifdef USE_NOF
-#include "spdk/spdk_wrapper.h"
-#endif
-
-#include <ylt/coro_http/coro_http_client.hpp>
-
-namespace mooncake {
-
-bool isPortAvailable(int port) {
-    int sock = socket(AF_INET, SOCK_STREAM, 0);
-    if (sock < 0) return false;
-
-    int opt = 1;
-    setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
-
-    struct sockaddr_in addr;
-    memset(&addr, 0, sizeof(addr));
-    addr.sin_family = AF_INET;
-    addr.sin_addr.s_addr = INADDR_ANY;
-    addr.sin_port = htons(port);
-
-    bool available = (bind(sock, (struct sockaddr *)&addr, sizeof(addr)) == 0);
-    close(sock);
-    return available;
-}
-
-// AutoPortBinder implementation
-AutoPortBinder::AutoPortBinder(int min_port, int max_port)
-    : socket_fd_(-1), port_(-1) {
-    for (int attempt = 0; attempt < 20; ++attempt) {
-        int port = randomUniform(min_port, max_port);
-
-        socket_fd_ = socket(AF_INET, SOCK_STREAM, 0);
-        if (socket_fd_ < 0) continue;
-
-        sockaddr_in addr = {};
-        addr.sin_family = AF_INET;
-        addr.sin_addr.s_addr = INADDR_ANY;
-        addr.sin_port = htons(port);
-
-        if (bind(socket_fd_, (sockaddr *)&addr, sizeof(addr)) == 0) {
-            port_ = port;
-            break;
-        } else {
-            close(socket_fd_);
-            socket_fd_ = -1;
-        }
-    }
-}
-
-AutoPortBinder::~AutoPortBinder() {
-    if (socket_fd_ >= 0) {
-        close(socket_fd_);
-    }
-}
-
-#ifdef USE_VRAM_SEGMENT
-tl::expected<void *, std::string> allocate_vram_memory(
-    size_t total_size, const std::string &protocol) {
-    cudaError_t res;
-    int device;
-    void *ptr = nullptr;
-    res = cudaGetDevice(&device);
-    if (res != cudaSuccess) {
-        LOG(ERROR) << "VRAM Segment cudaGetDevice failed.";
-        return tl::make_unexpected("VRAM Segment cudaGetDevice failed.");
-    }
-    if (protocol == "nvlink_intra") {
-#ifdef USE_INTRA_NVLINK
-        ptr = allocateFabricMemory_intra(total_size);
-        return ptr;
-#else
-        LOG(ERROR) << "Protocol nvlink_intra need USE_INTRA_NVLINK=ON. Please "
-                      "rebuild mooncake from source.";
-        return tl::make_unexpected("Protocol not supported");
-#endif
-    }
-    res = cudaMalloc((void **)&ptr, total_size);
-    if (res != cudaSuccess) {
-        LOG(ERROR) << "VRAM Segment cudaMalloc failed.";
-        return tl::make_unexpected("VRAM Segment cudaMalloc failed.");
-    }
-    return ptr;
-}
-#endif
-
-void *allocate_buffer_allocator_memory(size_t total_size,
-                                       const std::string &protocol,
-                                       size_t alignment, bool use_spdk_dma) {
-    const size_t default_alignment = facebook::cachelib::Slab::kSize;
-    // Ensure total_size is a multiple of alignment
-    if (alignment == default_alignment && total_size < alignment) {
-        LOG(ERROR) << "Total size must be at least " << alignment;
-        return nullptr;
-    }
-#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
-    if (protocol == "ascend" || protocol == "ubshmem") {
-        return ascend_allocate_memory(total_size, protocol);
-    }
-#endif
-#if defined(USE_SUNRISE)
-    if (protocol == "sunrise_link") {
-        return sunrise_allocate_memory(
-            total_size, alignment,
-            mooncake::globalConfig().sunrise_use_device_mem);
-    }
-#endif
-#if defined(USE_UB)
-    if (protocol == "ub") {
-        return mooncake::ub_allocate_memory(alignment, total_size);
-    }
-#endif
-#ifdef USE_NOF
-    if (use_spdk_dma && total_size > 0) {
-        return mooncake::SpdkWrapper::GetInstance().Alloc(total_size, alignment,
-                                                          -1);
-    }
-#endif
-#ifdef USE_VRAM_SEGMENT
-    auto ret = allocate_vram_memory(total_size, protocol);
-    if (!ret) {
-        LOG(ERROR) << ret.error();
-        return nullptr;
-    }
-    return *ret;
-#endif
-    // Allocate aligned memory
-    return aligned_alloc(alignment, total_size);
-}
-
-// Global arena instance (lazy initialization)
-static std::unique_ptr<MmapArena> g_mmap_arena;
-static std::once_flag g_arena_init_flag;
-static std::atomic<uint64_t> g_arena_oom_fallback_count{0};
-static std::atomic<uint64_t> g_arena_noop_free_count{0};
-
-static void initializeGlobalArena() {
-    const std::string env_pool_size =
-        Environ::GetString("MC_MMAP_ARENA_POOL_SIZE", "");
-    // Allow env var to override the gflag (useful when loaded as .so from
-    // Python). An explicit pool-size env var is also treated as an opt-in,
-    // because pybind11 users cannot easily pass gflags.
-    const std::string env_disable =
-        Environ::GetString("MC_DISABLE_MMAP_ARENA", "");
-    const std::optional<bool> disable_override = TryParseBool(env_disable);
-    if (!env_disable.empty() && !disable_override.has_value()) {
-        LOG(WARNING) << "Ignoring invalid MC_DISABLE_MMAP_ARENA='"
-                     << env_disable
-                     << "'; accepted values: 1/0, true/false, yes/no, on/off";
-    }
-    const bool arena_requested =
-        FLAGS_use_mmap_arena_allocator || !env_pool_size.empty();
-    const bool arena_disabled = disable_override.value_or(false);
-    if (!arena_requested || arena_disabled) {
-        LOG(INFO) << "=== ARENA ALLOCATOR DISABLED ===";
-        if (arena_disabled) {
-            LOG(INFO) << "MC_DISABLE_MMAP_ARENA=" << env_disable
-                      << " forces direct mmap()";
-        } else {
-            LOG(INFO) << "Arena is opt-in; set --use_mmap_arena_allocator or "
-                         "MC_MMAP_ARENA_POOL_SIZE to enable it";
-        }
-        return;
-    }
-
-    g_mmap_arena = std::make_unique<MmapArena>();
-    // Keep arena init consistent with the direct-mmap path:
-    //   MC_STORE_USE_HUGEPAGE=1  -> strict: hard fail if hugepage mmap fails
-    //   unset                    -> permissive: try hugepages, retry on
-    //                               regular pages if HugeTLB is unavailable
-    // This preserves both pre-existing contracts and avoids surprising
-    // operators with a silent hugepage downgrade.
-    const bool hugepages_explicitly_requested =
-        get_hugepage_size_from_env() > 0;
-
-    // Allow env var override since gflags cannot be set from Python (pybind11).
-    // Supports human-readable sizes via string_to_byte_size(): "20gb", "16GB",
-    // etc.
-    uint64_t arena_pool_size = FLAGS_mmap_arena_pool_size;
-    if (!env_pool_size.empty()) {
-        const uint64_t parsed = string_to_byte_size(env_pool_size);
-        if (parsed > 0) {
-            arena_pool_size = parsed;
-            LOG(INFO) << "MC_MMAP_ARENA_POOL_SIZE override: " << env_pool_size
-                      << " (" << byte_size_to_string(arena_pool_size) << ")";
-        } else {
-            LOG(WARNING) << "Invalid MC_MMAP_ARENA_POOL_SIZE='" << env_pool_size
-                         << "', using default "
-                         << byte_size_to_string(FLAGS_mmap_arena_pool_size);
-        }
-    }
-
-    bool success =
-        g_mmap_arena->initialize(arena_pool_size, MmapArena::kMinAlignment,
-                                 !hugepages_explicitly_requested);
-
-    if (success) {
-        auto stats = g_mmap_arena->getStats();
-        LOG(INFO) << "=== ARENA ALLOCATOR ENABLED ===";
-        LOG(INFO) << "Arena pool size: " << (stats.pool_size / BYTES_PER_GIB)
-                  << " GiB";
-        LOG(INFO) << "Using lock-free atomic bump allocation";
-    } else {
-        LOG(ERROR) << "=== ARENA INITIALIZATION FAILED ===";
-        LOG(ERROR) << "Falling back to traditional mmap()";
-        if (hugepages_explicitly_requested) {
-            LOG(ERROR) << "MC_STORE_USE_HUGEPAGE is set, so the fallback path "
-                          "will also require hugepages";
-        }
-        LOG(ERROR) << "Arena initialization is only attempted once per "
-                      "process; restart after fixing the environment if you "
-                      "want to retry arena bring-up";
-        g_mmap_arena.reset();
-    }
-}
-
-// Compute the mmap/munmap size for the fallback (non-arena) path.
-// Used by both allocate_buffer_mmap_memory and free_buffer_mmap_memory
-// so they agree on the mapping size.
-static inline size_t mmap_map_size(size_t total_size, size_t hugepage_size) {
-    const size_t page_size =
-        hugepage_size > 0 ? hugepage_size : static_cast<size_t>(getpagesize());
-    return align_up(total_size, page_size);
-}
-
-namespace {
-
-size_t touch_thread_count(size_t page_count) {
-    const unsigned int hardware_threads = std::thread::hardware_concurrency();
-    const size_t available_threads =
-        hardware_threads == 0 ? 1 : std::min<size_t>(hardware_threads, 16);
-    return std::min(available_threads, page_count);
-}
-
-void touch_page_range(volatile char *data, size_t page_size, size_t begin_page,
-                      size_t end_page, int numa_node) {
-    if (numa_node >= 0 && numa_run_on_node(numa_node) != 0) {
-        LOG(WARNING) << "Failed to bind HugeTLB population worker to NUMA node "
-                     << numa_node << ": " << std::strerror(errno);
-    }
-    for (size_t page = begin_page; page < end_page; ++page) {
-        data[page * page_size] = 0;
-    }
-}
-
-void touch_mmap_pages(void *ptr, size_t map_size, size_t page_size) {
-    if (ptr == nullptr || map_size == 0 || page_size == 0) {
-        return;
-    }
-
-    const size_t page_count = (map_size + page_size - 1) / page_size;
-    const size_t num_threads = touch_thread_count(page_count);
-
-    auto *data = static_cast<volatile char *>(ptr);
-    if (num_threads <= 1) {
-        touch_page_range(data, page_size, 0, page_count, -1);
-        return;
-    }
-
-    std::vector<std::jthread> threads;
-    threads.reserve(num_threads);
-    const size_t pages_per_thread =
-        (page_count + num_threads - 1) / num_threads;
-    for (size_t thread_index = 0; thread_index < num_threads; ++thread_index) {
-        const size_t begin_page = thread_index * pages_per_thread;
-        const size_t end_page =
-            std::min(begin_page + pages_per_thread, page_count);
-        if (begin_page >= end_page) {
-            break;
-        }
-        threads.emplace_back(touch_page_range, data, page_size, begin_page,
-                             end_page, -1);
-    }
-}
-
-void touch_numa_mmap_pages(void *ptr, size_t map_size, size_t page_size,
-                           const std::vector<int> &numa_nodes) {
-    if (ptr == nullptr || map_size == 0 || page_size == 0 ||
-        numa_nodes.empty()) {
-        return;
-    }
-
-    const size_t node_count = numa_nodes.size();
-    if (map_size % node_count != 0 ||
-        (map_size / node_count) % page_size != 0) {
-        LOG(ERROR) << "Invalid NUMA HugeTLB mapping layout: size=" << map_size
-                   << ", page_size=" << page_size << ", nodes=" << node_count;
-        return;
-    }
-
-    const size_t region_size = map_size / node_count;
-    const size_t pages_per_region = region_size / page_size;
-    const size_t page_count = pages_per_region * node_count;
-    const size_t num_threads =
-        std::max(node_count, touch_thread_count(page_count));
-    const size_t base_threads_per_node = num_threads / node_count;
-    const size_t extra_threads = num_threads % node_count;
-
-    auto *data = static_cast<volatile char *>(ptr);
-    std::vector<std::jthread> threads;
-    threads.reserve(num_threads);
-    for (size_t node_index = 0; node_index < node_count; ++node_index) {
-        const size_t node_threads =
-            base_threads_per_node + (node_index < extra_threads ? 1 : 0);
-        const size_t pages_per_thread =
-            (pages_per_region + node_threads - 1) / node_threads;
-        const size_t region_begin_page = node_index * pages_per_region;
-        for (size_t thread_index = 0; thread_index < node_threads;
-             ++thread_index) {
-            const size_t begin_page =
-                region_begin_page + thread_index * pages_per_thread;
-            const size_t end_page =
-                std::min(begin_page + pages_per_thread,
-                         region_begin_page + pages_per_region);
-            if (begin_page >= end_page) {
-                continue;
-            }
-            threads.emplace_back(touch_page_range, data, page_size, begin_page,
-                                 end_page, numa_nodes[node_index]);
-        }
-    }
-}
-
-}  // namespace
-
-void populate_hugetlb_mapping(void *ptr, size_t total_size) {
-    const size_t hugepage_size = get_hugepage_size_from_env();
-    if (ptr == nullptr || total_size == 0 || hugepage_size == 0) {
-        return;
-    }
-
-    touch_mmap_pages(ptr, mmap_map_size(total_size, hugepage_size),
-                     hugepage_size);
-}
-
-void populate_hugetlb_numa_mapping(void *ptr, size_t total_size,
-                                   const std::vector<int> &numa_nodes) {
-    const size_t hugepage_size = get_hugepage_size_from_env();
-    if (ptr == nullptr || total_size == 0 || hugepage_size == 0 ||
-        numa_nodes.empty()) {
-        return;
-    }
-
-    touch_numa_mmap_pages(ptr, total_size, hugepage_size, numa_nodes);
-}
-
-void *allocate_buffer_mmap_memory(size_t total_size, size_t alignment) {
-    return allocate_buffer_mmap_memory(total_size, alignment, false);
-}
-
-void *allocate_buffer_mmap_memory(size_t total_size, size_t alignment,
-                                  bool defer_hugetlb_population) {
-    if (total_size == 0) {
-        LOG(ERROR) << "Total size must be greater than 0 for mmap";
-        return nullptr;
-    }
-
-    // Initialize arena on first call
-    std::call_once(g_arena_init_flag, initializeGlobalArena);
-
-    // Try arena allocation first (if enabled).
-    // Forward caller's alignment so the arena honors the contract.
-    if (g_mmap_arena && g_mmap_arena->isInitialized()) {
-        void *ptr = g_mmap_arena->allocate(total_size, alignment);
-        if (ptr != nullptr) {
-            VLOG(1) << "Allocated " << total_size << " bytes from arena at "
-                    << ptr;
-            return ptr;
-        }
-        // Arena OOM, fall through to traditional mmap
-        const uint64_t fallback_count =
-            g_arena_oom_fallback_count.fetch_add(1, std::memory_order_relaxed) +
-            1;
-        LOG_FIRST_N(WARNING, 3)
-            << "Arena OOM, falling back to mmap() for size=" << total_size
-            << " (count=" << fallback_count << ")"
-            << " (further warnings suppressed)";
-    }
-
-    // Traditional mmap allocation (fallback or arena disabled).
-    const bool defer_direct_population =
-        defer_hugetlb_population && get_hugepage_size_from_env() > 0;
-    unsigned int flags = MAP_PRIVATE | MAP_ANONYMOUS;
-    if (!defer_direct_population) {
-        flags |= MAP_POPULATE;
-    }
-    const size_t hugepage_size = get_hugepage_size_from_env(&flags);
-    const size_t map_size = mmap_map_size(total_size, hugepage_size);
-    const size_t guaranteed_alignment =
-        hugepage_size > 0 ? hugepage_size : static_cast<size_t>(getpagesize());
-    if (alignment > guaranteed_alignment) {
-        LOG_FIRST_N(WARNING, 3)
-            << "Fallback mmap cannot honor alignment=" << alignment
-            << " (guaranteed=" << guaranteed_alignment
-            << "); pointer may be under-aligned"
-            << " (further warnings suppressed)";
-    }
-
-    void *ptr = mmap(nullptr, map_size, PROT_READ | PROT_WRITE, flags, -1, 0);
-    if (ptr == MAP_FAILED) {
-        LOG(ERROR) << "mmap failed, size=" << map_size << ", errno=" << errno
-                   << " (" << strerror(errno) << ")";
-        return nullptr;
-    }
-
-    VLOG(1) << "Allocated " << total_size << " bytes via mmap() at " << ptr;
-    return ptr;
-}
-
-bool is_mmap_arena_allocation(const void *ptr) {
-    return ptr != nullptr && g_mmap_arena && g_mmap_arena->isInitialized() &&
-           g_mmap_arena->owns(ptr);
-}
-
-void free_buffer_mmap_memory(void *ptr, size_t total_size) {
-    if (!ptr || total_size == 0) {
-        return;
-    }
-
-    // Check if pointer belongs to global arena
-    std::call_once(g_arena_init_flag, initializeGlobalArena);
-
-    if (g_mmap_arena && g_mmap_arena->owns(ptr)) {
-        const uint64_t noop_free_count =
-            g_arena_noop_free_count.fetch_add(1, std::memory_order_relaxed) + 1;
-        LOG_FIRST_N(WARNING, 3)
-            << "free_buffer_mmap_memory() does not individually release "
-               "arena-owned pointer "
-            << ptr << "; the global arena releases its pool at process shutdown"
-            << " (count=" << noop_free_count << ")"
-            << " (further warnings suppressed)";
-        return;
-    }
-
-    // Direct mmap allocation - safe to unmap
-    const size_t map_size =
-        mmap_map_size(total_size, get_hugepage_size_from_env());
-    if (munmap(ptr, map_size) != 0) {
-        LOG(ERROR) << "munmap hugepage failed, size=" << map_size
-                   << ", errno=" << errno << " (" << strerror(errno) << ")";
-    } else {
-        VLOG(1) << "Freed direct mmap allocation at " << ptr
-                << ", size=" << map_size;
-    }
-}
-
-// NUMA-segmented buffer allocation
-void *allocate_buffer_numa_segments(size_t total_size,
-                                    const std::vector<int> &numa_nodes,
-                                    size_t page_size) {
-    if (total_size == 0 || numa_nodes.empty()) {
-        LOG(ERROR) << "Invalid params: total_size=" << total_size
-                   << " numa_nodes.size=" << numa_nodes.size();
-        return nullptr;
-    }
-
-    if (page_size == 0) page_size = getpagesize();
-    size_t n = numa_nodes.size();
-    size_t region_size = align_up(total_size / n, page_size);
-    size_t map_size = region_size * n;
-
-    // reserve contiguous VMA; use hugepages if page_size indicates so
-    unsigned int flags = MAP_PRIVATE | MAP_ANONYMOUS;
-    if (page_size == SZ_2MB) {
-        flags |= MAP_HUGETLB | MAP_HUGE_2MB;
-    } else if (page_size == SZ_1GB) {
-        flags |= MAP_HUGETLB | MAP_HUGE_1GB;
-    } else if (page_size != static_cast<size_t>(getpagesize())) {
-        flags |= MAP_HUGETLB;
-    }
-    void *ptr = mmap(nullptr, map_size, PROT_READ | PROT_WRITE, flags, -1, 0);
-    if (ptr == MAP_FAILED) {
-        LOG(ERROR) << "mmap failed (hugepage="
-                   << ((flags & MAP_HUGETLB) ? "yes" : "no")
-                   << "), size=" << map_size << ", errno=" << errno << " ("
-                   << strerror(errno) << ")";
-        return nullptr;
-    }
-
-    // bind each region to its NUMA node
-    int max_node = numa_num_possible_nodes();
-    for (size_t i = 0; i < n; ++i) {
-        struct bitmask *mask = numa_bitmask_alloc(max_node);
-        numa_bitmask_setbit(mask, numa_nodes[i]);
-        char *region = static_cast<char *>(ptr) + i * region_size;
-        long rc =
-            mbind(region, region_size, MPOL_BIND, mask->maskp, mask->size, 0);
-        numa_bitmask_free(mask);
-        if (rc != 0) {
-            LOG(ERROR) << "mbind failed for NUMA " << numa_nodes[i]
-                       << ", errno=" << errno << " (" << strerror(errno) << ")";
-            munmap(ptr, map_size);
-            return nullptr;
-        }
-    }
-
-    // Leave the mapping lazy. The caller may explicitly populate it with
-    // NUMA-local workers before registration; otherwise ibv_reg_mr() calls
-    // get_user_pages(), whose faults respect the mbind policy.
-
-    LOG(INFO) << "Allocated NUMA-segmented buffer: " << map_size << " bytes, "
-              << n << " regions, page_size=" << page_size << ", nodes=[" <<
-        [&]() {
-            std::string s;
-            for (size_t i = 0; i < n; ++i) {
-                if (i) s += ",";
-                s += std::to_string(numa_nodes[i]);
-            }
-            return s;
-        }() << "]";
-    return ptr;
-}
-
-void free_memory(const std::string &protocol, void *ptr, bool use_spdk_dma) {
-#if defined(USE_ASCEND_DIRECT) || defined(USE_UBSHMEM)
-    if (protocol == "ascend" || protocol == "ubshmem") {
-        return ascend_free_memory(protocol, ptr);
-    }
-#endif
-#if defined(USE_SUNRISE)
-    if (protocol == "sunrise_link") {
-        return sunrise_free_memory(ptr);
-    }
-#endif
-#if defined(USE_UB)
-    if (protocol == "ub") {
-        mooncake::ub_free_memory(ptr);
-        return;
-    }
-#endif
-#ifdef USE_NOF
-    // Mirror allocate_buffer_allocator_memory(): a buffer taken from the SPDK
-    // hugepage pool (spdk_zmalloc) must be released with spdk_free, not glibc
-    // free(), which would abort with "free(): invalid pointer".
-    if (use_spdk_dma) {
-        mooncake::SpdkWrapper::GetInstance().Free(ptr);
-        return;
-    }
-#endif
-#ifdef USE_VRAM_SEGMENT
-#ifdef USE_INTRA_NVLINK
-    freeFabricMemory_intra(ptr);
-#else
-    cudaFree(ptr);
-#endif
-    return;
-#endif
-    free(ptr);
-}
-
-tl::expected<std::string, int> httpGet(const std::string &url) {
-    coro_http::coro_http_client client;
-    auto res = client.get(url);
-    if (res.status == 200) {
-        return std::string(res.resp_body);
-    }
-    return tl::unexpected(res.status);
-}
-
-tl::expected<std::string, std::string> GetInterfaceIPv4Address(
-    const std::string &interface_name) {
-    if (interface_name.empty()) {
-        return tl::unexpected(std::string("network interface name is empty"));
-    }
-
-    struct ifaddrs *interfaces = nullptr;
-    if (getifaddrs(&interfaces) != 0) {
-        return tl::unexpected("getifaddrs failed: " +
-                              std::string(strerror(errno)));
-    }
-    std::unique_ptr<struct ifaddrs, decltype(&freeifaddrs)> interface_guard(
-        interfaces, freeifaddrs);
-
-    bool found_interface = false;
-    bool interface_is_up = false;
-    for (auto *current = interfaces; current != nullptr;
-         current = current->ifa_next) {
-        if (current->ifa_name == nullptr ||
-            interface_name != current->ifa_name) {
-            continue;
-        }
-
-        found_interface = true;
-        if ((current->ifa_flags & IFF_UP) == 0) {
-            continue;
-        }
-        interface_is_up = true;
-
-        if (current->ifa_addr == nullptr ||
-            current->ifa_addr->sa_family != AF_INET) {
-            continue;
-        }
-
-        char host[NI_MAXHOST] = {};
-        auto *ipv4_addr = reinterpret_cast<sockaddr_in *>(current->ifa_addr);
-        if (getnameinfo(reinterpret_cast<sockaddr *>(ipv4_addr),
-                        sizeof(*ipv4_addr), host, sizeof(host), nullptr, 0,
-                        NI_NUMERICHOST) == 0) {
-            return std::string(host);
-        }
-    }
-
-    if (!found_interface) {
-        return tl::unexpected("network interface '" + interface_name +
-                              "' was not found");
-    }
-    if (!interface_is_up) {
-        return tl::unexpected("network interface '" + interface_name +
-                              "' is down");
-    }
-    return tl::unexpected("network interface '" + interface_name +
-                          "' has no IPv4 address");
-}
-
-int getFreeTcpPort() {
-    int sock = ::socket(AF_INET, SOCK_STREAM, 0);
-    if (sock < 0) return -1;
-    sockaddr_in addr{};
-    addr.sin_family = AF_INET;
-    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
-    addr.sin_port = htons(0);
-    if (::bind(sock, reinterpret_cast<sockaddr *>(&addr), sizeof(addr)) != 0) {
-        ::close(sock);
-        return -1;
-    }
-    socklen_t len = sizeof(addr);
-    if (::getsockname(sock, reinterpret_cast<sockaddr *>(&addr), &len) != 0) {
-        ::close(sock);
-        return -1;
-    }
-    int port = ntohs(addr.sin_port);
-    ::close(sock);
-    return port;
-}
-
-std::vector<int> getFreeTcpPorts(int count) {
-    std::vector<int> ports;
-    std::vector<int> sockets;
-    ports.reserve(count);
-    sockets.reserve(count);
-
-    for (int i = 0; i < count; ++i) {
-        int sock = ::socket(AF_INET, SOCK_STREAM, 0);
-        if (sock < 0) break;
-        sockaddr_in addr{};
-        addr.sin_family = AF_INET;
-        addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
-        addr.sin_port = htons(0);
-        if (::bind(sock, reinterpret_cast<sockaddr *>(&addr), sizeof(addr)) !=
-            0) {
-            ::close(sock);
-            break;
-        }
-        socklen_t len = sizeof(addr);
-        if (::getsockname(sock, reinterpret_cast<sockaddr *>(&addr), &len) !=
-            0) {
-            ::close(sock);
-            break;
-        }
-        ports.push_back(ntohs(addr.sin_port));
-        sockets.push_back(sock);
-    }
-
-    for (int sock : sockets) {
-        ::close(sock);
-    }
-    return ports;
-}
-
-int64_t time_gen() {
-    return std::chrono::duration_cast<std::chrono::seconds>(
-               std::chrono::system_clock::now().time_since_epoch())
-        .count();
-}
-
-std::string ResolveMooncakeHostId(const std::string &local_hostname) {
-    const std::string hostname(TrimAsciiWhitespace(local_hostname));
-    const std::string host_id = (hostname == "::1" || hostname == "::")
-                                    ? hostname
-                                    : std::string(TrimAsciiWhitespace(
-                                          getHostNameWithoutPort(hostname)));
-    if (host_id.empty()) {
-        return "";
-    }
-
-    if (AsciiCaseInsensitiveEquals(host_id, "localhost") ||
-        host_id == "127.0.0.1" || host_id == "0.0.0.0" || host_id == "::1" ||
-        host_id == "[::1]" || host_id == "::" || host_id == "[::]") {
-        return "";
-    }
-    return host_id;
-}
-
-static std::string SanitizeKey(const std::string &key) {
-    // Set of invalid filesystem characters to be replaced
-    constexpr std::string_view kInvalidChars = "/\\:*?\"<>|";
-    std::string sanitized_key;
-    sanitized_key.reserve(key.size());
-
-    for (char c : key) {
-        // Replace invalid characters with underscore
-        const bool invalid =
-            c == '\0' || kInvalidChars.find(c) != std::string_view::npos;
-        sanitized_key.push_back(invalid ? '_' : c);
-    }
-    return sanitized_key;
-}
-
-std::string ResolvePathFromKey(const std::string &key,
-                               const std::string &root_dir,
-                               const std::string &fsdir) {
-    // Compute hash of the key
-    size_t hash = std::hash<std::string>{}(key);
-
-    // Use low 8 bits to create 2-level directory structure (e.g. "a1/b2")
-    char dir1 =
-        static_cast<char>('a' + (hash & 0x0F));  // Lower 4 bits -> 16 dirs
-    char dir2 = static_cast<char>(
-        'a' + ((hash >> 4) & 0x0F));  // Next 4 bits -> 16 subdirs
-
-    // Safely construct path using std::filesystem
-    namespace fs = std::filesystem;
-    fs::path dir_path = fs::path(std::string(1, dir1)) / std::string(1, dir2);
-
-    // Combine directory path with sanitized filename
-    fs::path full_path =
-        fs::path(root_dir) / fsdir / dir_path / SanitizeKey(key);
-
-    return full_path.lexically_normal().string();
-}
-}  // namespace mooncake
diff --git a/mooncake-store/src/weight_metadata_store.cpp b/mooncake-store/src/weight_metadata_store.cpp
new file mode 100644
index 0000000000..d3127b9ac1
--- /dev/null
+++ b/mooncake-store/src/weight_metadata_store.cpp
@@ -0,0 +1,1301 @@
+#include "weight_metadata_store.h"
+
+#include <algorithm>
+#include <charconv>
+#include <limits>
+#include <memory>
+#include <sstream>
+#include <string_view>
+
+#include <openssl/evp.h>
+
+namespace mooncake {
+namespace {
+
+constexpr uint32_t kMaxListLimit = 1000;
+constexpr uint64_t kMaxLeaseTtlMs = 24ULL * 60 * 60 * 1000;
+constexpr char kPageTokenSeparator = '\x1f';
+
+bool MatchesIdempotentRetryGeneration(uint64_t current, uint64_t expected) {
+    return current == expected ||
+           (expected != std::numeric_limits<uint64_t>::max() &&
+            current == expected + 1);
+}
+
+bool SameImport(const WeightRevisionMetadata& metadata,
+                const BeginWeightImportRequest& request) {
+    return metadata.identity == request.identity &&
+           metadata.manifest.payload_group_id == request.payload_group_id &&
+           metadata.manifest.payload_count == request.expected_payload_count &&
+           metadata.manifest.logical_bytes == request.expected_logical_bytes;
+}
+
+bool SameManifest(const WeightRevisionMetadata& metadata,
+                  const WeightManifestReference& manifest) {
+    return metadata.manifest == manifest;
+}
+
+std::string Sha256Hex(const std::vector<std::string_view>& chunks) {
+    using Context = std::unique_ptr<EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>;
+    Context context(EVP_MD_CTX_new(), EVP_MD_CTX_free);
+    if (!context ||
+        EVP_DigestInit_ex(context.get(), EVP_sha256(), nullptr) != 1) {
+        return {};
+    }
+    for (const auto chunk : chunks) {
+        if (EVP_DigestUpdate(context.get(), chunk.data(), chunk.size()) != 1) {
+            return {};
+        }
+    }
+    unsigned char digest[EVP_MAX_MD_SIZE];
+    unsigned int digest_size = 0;
+    if (EVP_DigestFinal_ex(context.get(), digest, &digest_size) != 1 ||
+        digest_size != 32) {
+        return {};
+    }
+    static constexpr char kHex[] = "0123456789abcdef";
+    std::string encoded(digest_size * 2, '0');
+    for (unsigned int i = 0; i < digest_size; ++i) {
+        encoded[2 * i] = kHex[digest[i] >> 4];
+        encoded[2 * i + 1] = kHex[digest[i] & 0x0f];
+    }
+    return encoded;
+}
+
+void AppendLengthPrefixed(std::vector<std::string>* storage,
+                          std::vector<std::string_view>* chunks,
+                          std::string_view value) {
+    storage->push_back(std::to_string(value.size()));
+    chunks->push_back(storage->back());
+    chunks->push_back(":");
+    chunks->push_back(value);
+    chunks->push_back("\n");
+}
+
+std::string ComputeWeightIdentitySha256(
+    const WeightRevisionIdentity& identity) {
+    if (!ValidateWeightRevisionIdentity(identity).ok()) {
+        return {};
+    }
+    std::vector<std::string> lengths;
+    lengths.reserve(5);
+    std::vector<std::string_view> chunks;
+    chunks.reserve(20);
+    AppendLengthPrefixed(&lengths, &chunks, identity.tenant_id);
+    AppendLengthPrefixed(&lengths, &chunks, identity.name_space);
+    AppendLengthPrefixed(&lengths, &chunks, identity.resource_id);
+    AppendLengthPrefixed(&lengths, &chunks, identity.revision);
+    const auto generation = std::to_string(identity.weight_generation);
+    AppendLengthPrefixed(&lengths, &chunks, generation);
+    return Sha256Hex(chunks);
+}
+
+}  // namespace
+
+std::string ComputeWeightPayloadKeysSha256(
+    const std::vector<std::string>& payload_keys) {
+    auto sorted_keys = payload_keys;
+    std::sort(sorted_keys.begin(), sorted_keys.end());
+    std::vector<std::string> lengths;
+    lengths.reserve(sorted_keys.size());
+    std::vector<std::string_view> chunks;
+    chunks.reserve(sorted_keys.size() * 4);
+    for (const auto& key : sorted_keys) {
+        AppendLengthPrefixed(&lengths, &chunks, key);
+    }
+    return Sha256Hex(chunks);
+}
+
+std::string MakeWeightPayloadGroupId(const WeightRevisionIdentity& identity) {
+    const auto digest = ComputeWeightIdentitySha256(identity);
+    return digest.empty() ? std::string() : "weight:" + digest;
+}
+
+std::string MakeWeightRevisionMetadataKey(
+    const WeightRevisionIdentity& identity) {
+    const auto digest = ComputeWeightIdentitySha256(identity);
+    return digest.empty() ? std::string() : "weight-revision:" + digest;
+}
+
+std::string MakeWeightLeaseMetadataKey(uint64_t lease_id) {
+    return lease_id == 0 ? std::string()
+                         : "weight-lease:" + std::to_string(lease_id);
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareBeginImport(const BeginWeightImportRequest& request,
+                                        uint64_t now_ms) const {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        !IsValidWeightComponent(request.payload_group_id) ||
+        request.payload_group_id !=
+            MakeWeightPayloadGroupId(request.identity) ||
+        request.expected_payload_count == 0 ||
+        request.expected_logical_bytes == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::lock_guard lock(mutex_);
+    const auto group = group_index_.find(request.payload_group_id);
+    if (group != group_index_.end() && group->second != request.identity) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+
+    const auto current = revisions_.find(request.identity);
+    if (current != revisions_.end()) {
+        if ((current->second.availability ==
+                 WeightAvailabilityState::IMPORTING ||
+             current->second.availability == WeightAvailabilityState::READY) &&
+            SameImport(current->second, request)) {
+            return WeightMetadataMutation{
+                .identity = request.identity,
+                .previous = current->second,
+                .next = current->second,
+                .no_op = true,
+            };
+        }
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+
+    WeightRevisionMetadata metadata{
+        .identity = request.identity,
+        .manifest =
+            WeightManifestReference{
+                .manifest_key = {},
+                .manifest_sha256 = {},
+                .payload_group_id = request.payload_group_id,
+                .payload_keys_sha256 = {},
+                .payload_count = request.expected_payload_count,
+                .logical_bytes = request.expected_logical_bytes,
+            },
+        .availability = WeightAvailabilityState::IMPORTING,
+        .residency = WeightResidencyState::UNKNOWN,
+        .operation = WeightOperationState::NONE,
+        .metadata_generation = 1,
+        .created_at_ms = now_ms,
+        .updated_at_ms = now_ms,
+    };
+    return WeightMetadataMutation{
+        .kind = WeightMetadataMutationKind::UPSERT,
+        .identity = request.identity,
+        .previous = std::nullopt,
+        .next = std::move(metadata),
+        .no_op = false,
+    };
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareCommitImport(
+    const CommitWeightImportRequest& request, uint64_t now_ms) const {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        !ValidateWeightManifestReference(request.manifest).ok() ||
+        request.manifest.payload_group_id !=
+            MakeWeightPayloadGroupId(request.identity) ||
+        request.manifest.manifest_key !=
+            MakeWeightManifestKey(request.identity) ||
+        request.expected_metadata_generation == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(request.identity);
+    if (current == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.availability == WeightAvailabilityState::READY) {
+        if (!SameManifest(current->second, request.manifest)) {
+            return tl::make_unexpected(WeightManagementError::CONFLICT);
+        }
+        if (!MatchesIdempotentRetryGeneration(
+                current->second.metadata_generation,
+                request.expected_metadata_generation)) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+        return WeightMetadataMutation{
+            .identity = request.identity,
+            .previous = current->second,
+            .next = current->second,
+            .no_op = true,
+        };
+    }
+    if (current->second.metadata_generation !=
+        request.expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (current->second.availability != WeightAvailabilityState::IMPORTING) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (current->second.manifest.payload_group_id !=
+            request.manifest.payload_group_id ||
+        current->second.manifest.payload_count !=
+            request.manifest.payload_count ||
+        current->second.manifest.logical_bytes !=
+            request.manifest.logical_bytes) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(
+            current->second.metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+
+    auto next = current->second;
+    next.manifest = request.manifest;
+    next.availability = WeightAvailabilityState::READY;
+    next.residency = WeightResidencyState::HOT;
+    ++next.metadata_generation;
+    next.updated_at_ms = std::max(next.updated_at_ms, now_ms);
+    return WeightMetadataMutation{
+        .identity = request.identity,
+        .previous = current->second,
+        .next = std::move(next),
+    };
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareAbortImport(const AbortWeightImportRequest& request,
+                                        uint64_t now_ms) const {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        request.expected_metadata_generation == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(request.identity);
+    if (current == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.availability == WeightAvailabilityState::DELETING) {
+        if (!MatchesIdempotentRetryGeneration(
+                current->second.metadata_generation,
+                request.expected_metadata_generation)) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+        return WeightMetadataMutation{
+            .identity = request.identity,
+            .previous = current->second,
+            .next = current->second,
+            .no_op = true,
+        };
+    }
+    if (current->second.metadata_generation !=
+        request.expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (current->second.availability != WeightAvailabilityState::IMPORTING) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(
+            current->second.metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+
+    auto next = current->second;
+    next.availability = WeightAvailabilityState::DELETING;
+    ++next.metadata_generation;
+    next.updated_at_ms = std::max(next.updated_at_ms, now_ms);
+    return WeightMetadataMutation{
+        .identity = request.identity,
+        .previous = current->second,
+        .next = std::move(next),
+    };
+}
+
+WeightMetadataStore::Result<WeightRevisionMetadata>
+WeightMetadataStore::Publish(const WeightMetadataMutation& mutation) {
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(mutation.identity);
+    if (mutation.previous.has_value()) {
+        if (current == revisions_.end() ||
+            current->second != *mutation.previous) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+    } else if (current != revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+
+    if (mutation.no_op) {
+        return current->second;
+    }
+    if (mutation.kind == WeightMetadataMutationKind::ERASE ||
+        !mutation.next.has_value()) {
+        if (current == revisions_.end()) {
+            return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+        }
+        auto removed = current->second;
+        group_index_.erase(removed.manifest.payload_group_id);
+        revisions_.erase(current);
+        return removed;
+    }
+
+    const auto& next = *mutation.next;
+    if (!ValidateWeightRevisionMetadata(next).ok()) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    if (current != revisions_.end() &&
+        current->second.availability != WeightAvailabilityState::DELETING &&
+        next.availability == WeightAvailabilityState::DELETING) {
+        std::optional<uint64_t> nearest;
+        if (CountActiveLeasesLocked(current->second, next.updated_at_ms,
+                                    &nearest) != 0) {
+            return tl::make_unexpected(WeightManagementError::BUSY);
+        }
+    }
+    const auto group = group_index_.find(next.manifest.payload_group_id);
+    if (group != group_index_.end() && group->second != next.identity) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    revisions_[next.identity] = next;
+    group_index_[next.manifest.payload_group_id] = next.identity;
+    return next;
+}
+
+WeightMetadataStore::Result<WeightRevisionView> WeightMetadataStore::Get(
+    const WeightRevisionIdentity& identity, uint64_t now_ms) const {
+    if (!ValidateWeightRevisionIdentity(identity).ok()) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(identity);
+    if (current == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    std::optional<uint64_t> nearest;
+    const auto count =
+        CountActiveLeasesLocked(current->second, now_ms, &nearest);
+    return WeightRevisionView{
+        .metadata = current->second,
+        .active_lease_count = count,
+        .nearest_lease_expiry_ms = nearest,
+    };
+}
+
+WeightMetadataStore::Result<ListWeightRevisionsResponse>
+WeightMetadataStore::List(const ListWeightRevisionsRequest& request,
+                          uint64_t now_ms) const {
+    if (request.tenant_id.empty() || !TenantId(request.tenant_id).IsValid() ||
+        !IsValidWeightComponent(request.name_space) ||
+        !IsValidWeightComponent(request.resource_id) || request.limit == 0 ||
+        request.limit > kMaxListLimit) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::optional<std::pair<std::string, uint64_t>> cursor;
+    if (!request.page_token.empty()) {
+        auto parsed = ParsePageToken(request.page_token);
+        if (!parsed.has_value()) {
+            return tl::make_unexpected(parsed.error());
+        }
+        cursor = *parsed;
+    }
+
+    std::lock_guard lock(mutex_);
+    ListWeightRevisionsResponse response;
+    for (const auto& [identity, metadata] : revisions_) {
+        if (identity.tenant_id != request.tenant_id ||
+            identity.name_space != request.name_space ||
+            identity.resource_id != request.resource_id) {
+            continue;
+        }
+        if (cursor.has_value() &&
+            std::tie(identity.revision, identity.weight_generation) <=
+                std::tie(cursor->first, cursor->second)) {
+            continue;
+        }
+        if (response.revisions.size() == request.limit) {
+            response.next_page_token =
+                MakePageToken(response.revisions.back().metadata.identity);
+            break;
+        }
+        std::optional<uint64_t> nearest;
+        const auto count = CountActiveLeasesLocked(metadata, now_ms, &nearest);
+        response.revisions.push_back(WeightRevisionView{
+            .metadata = metadata,
+            .active_lease_count = count,
+            .nearest_lease_expiry_ms = nearest,
+        });
+    }
+    return response;
+}
+
+WeightMetadataStore::Result<WeightLeaseMutation>
+WeightMetadataStore::PrepareAcquireLease(
+    const AcquireWeightRevisionLeaseRequest& request, uint64_t now_ms) {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        request.expected_metadata_generation == 0 ||
+        !IsValidWeightComponent(request.holder) || request.ttl_ms == 0 ||
+        request.ttl_ms > kMaxLeaseTtlMs) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(request.identity);
+    if (current == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.metadata_generation !=
+        request.expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (current->second.availability != WeightAvailabilityState::READY) {
+        return tl::make_unexpected(WeightManagementError::NOT_READY);
+    }
+    if (current->second.operation != WeightOperationState::NONE) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    for (const auto& [lease_id, lease] : leases_) {
+        (void)lease_id;
+        if (lease.identity == request.identity &&
+            lease.holder == request.holder && lease.expires_at_ms > now_ms &&
+            lease.fenced_metadata_generation <=
+                current->second.metadata_generation) {
+            return WeightLeaseMutation{
+                .lease_id = lease.lease_id,
+                .previous = lease,
+                .next = lease,
+                .no_op = true,
+            };
+        }
+    }
+    if (next_lease_id_ == 0 ||
+        next_lease_id_ == std::numeric_limits<uint64_t>::max()) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    const uint64_t lease_id = next_lease_id_++;
+    return WeightLeaseMutation{
+        .kind = WeightMetadataMutationKind::UPSERT,
+        .lease_id = lease_id,
+        .previous = std::nullopt,
+        .next =
+            WeightRevisionLease{
+                .lease_id = lease_id,
+                .identity = request.identity,
+                .holder = request.holder,
+                .expires_at_ms = AddTtl(now_ms, request.ttl_ms),
+                .fenced_metadata_generation =
+                    request.expected_metadata_generation,
+            },
+        .no_op = false,
+    };
+}
+
+WeightMetadataStore::Result<WeightLeaseMutation>
+WeightMetadataStore::PrepareRenewLease(
+    const RenewWeightRevisionLeaseRequest& request, uint64_t now_ms) const {
+    if (request.tenant_id.empty() || !TenantId(request.tenant_id).IsValid() ||
+        request.lease_id == 0 || request.ttl_ms == 0 ||
+        request.ttl_ms > kMaxLeaseTtlMs) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto current = leases_.find(request.lease_id);
+    if (current == leases_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.identity.tenant_id != request.tenant_id) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.expires_at_ms <= now_ms) {
+        return tl::make_unexpected(WeightManagementError::LEASE_EXPIRED);
+    }
+    auto next = current->second;
+    next.expires_at_ms = AddTtl(now_ms, request.ttl_ms);
+    return WeightLeaseMutation{
+        .lease_id = request.lease_id,
+        .previous = current->second,
+        .next = std::move(next),
+    };
+}
+
+WeightMetadataStore::Result<WeightLeaseMutation>
+WeightMetadataStore::PrepareReleaseLease(
+    const ReleaseWeightRevisionLeaseRequest& request) const {
+    if (request.tenant_id.empty() || !TenantId(request.tenant_id).IsValid() ||
+        request.lease_id == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto current = leases_.find(request.lease_id);
+    if (current == leases_.end()) {
+        return WeightLeaseMutation{
+            .kind = WeightMetadataMutationKind::ERASE,
+            .lease_id = request.lease_id,
+            .previous = std::nullopt,
+            .next = std::nullopt,
+            .no_op = true,
+        };
+    }
+    if (current->second.identity.tenant_id != request.tenant_id) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    return WeightLeaseMutation{
+        .kind = WeightMetadataMutationKind::ERASE,
+        .lease_id = request.lease_id,
+        .previous = current->second,
+        .next = std::nullopt,
+        .no_op = false,
+    };
+}
+
+std::vector<WeightLeaseMutation> WeightMetadataStore::PrepareExpireLeases(
+    uint64_t now_ms) const {
+    std::lock_guard lock(mutex_);
+    std::vector<WeightLeaseMutation> expired;
+    for (const auto& [lease_id, lease] : leases_) {
+        if (lease.expires_at_ms <= now_ms) {
+            expired.push_back(WeightLeaseMutation{
+                .kind = WeightMetadataMutationKind::ERASE,
+                .lease_id = lease_id,
+                .previous = lease,
+                .next = std::nullopt,
+                .no_op = false,
+            });
+        }
+    }
+    std::sort(expired.begin(), expired.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.lease_id < rhs.lease_id;
+              });
+    return expired;
+}
+
+WeightMetadataStore::Result<WeightRevisionLease> WeightMetadataStore::Publish(
+    const WeightLeaseMutation& mutation) {
+    std::lock_guard lock(mutex_);
+    const auto current = leases_.find(mutation.lease_id);
+    if (mutation.no_op) {
+        if (mutation.next.has_value()) {
+            return *mutation.next;
+        }
+        return WeightRevisionLease{
+            .lease_id = mutation.lease_id,
+            .identity = {},
+            .holder = {},
+            .expires_at_ms = 0,
+            .fenced_metadata_generation = 0,
+        };
+    }
+    if (mutation.previous.has_value()) {
+        if (current == leases_.end() || current->second != *mutation.previous) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+    } else if (current != leases_.end()) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+
+    if (mutation.kind == WeightMetadataMutationKind::ERASE ||
+        !mutation.next.has_value()) {
+        auto removed = current->second;
+        leases_.erase(current);
+        return removed;
+    }
+
+    const auto& next = *mutation.next;
+    const auto revision = revisions_.find(next.identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.metadata_generation <
+        next.fenced_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (revision->second.availability != WeightAvailabilityState::READY) {
+        return tl::make_unexpected(WeightManagementError::NOT_READY);
+    }
+    if (revision->second.operation != WeightOperationState::NONE) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if (!mutation.previous.has_value() &&
+        next.lease_id == std::numeric_limits<uint64_t>::max()) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    leases_[next.lease_id] = next;
+    if (!mutation.previous.has_value()) {
+        next_lease_id_ = std::max(next_lease_id_, next.lease_id + 1);
+    }
+    return next;
+}
+
+bool WeightMetadataStore::HasActiveLease(const WeightRevisionIdentity& identity,
+                                         uint64_t metadata_generation,
+                                         uint64_t now_ms) const {
+    std::lock_guard lock(mutex_);
+    for (const auto& [lease_id, lease] : leases_) {
+        static_cast<void>(lease_id);
+        if (lease.identity == identity &&
+            lease.fenced_metadata_generation <= metadata_generation &&
+            lease.expires_at_ms > now_ms) {
+            return true;
+        }
+    }
+    return false;
+}
+
+WeightMetadataStore::Result<WeightOperationMutation>
+WeightMetadataStore::PrepareStartOperation(
+    const StartWeightResidencyOperationRequest& request, uint64_t now_ms) {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        request.expected_metadata_generation == 0 ||
+        (request.target_residency != WeightResidencyState::HOT &&
+         request.target_residency != WeightResidencyState::COLD)) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(request.identity);
+    if (current == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (current->second.operation != WeightOperationState::NONE) {
+        const auto operation = operations_.find(current->second.operation_id);
+        if (operation != operations_.end() &&
+            operation->second.target_residency == request.target_residency) {
+            if (!MatchesIdempotentRetryGeneration(
+                    current->second.metadata_generation,
+                    request.expected_metadata_generation)) {
+                return tl::make_unexpected(
+                    WeightManagementError::STALE_GENERATION);
+            }
+            return WeightOperationMutation{
+                .metadata =
+                    WeightMetadataMutation{
+                        .identity = request.identity,
+                        .previous = current->second,
+                        .next = current->second,
+                        .no_op = true,
+                    },
+                .previous = operation->second,
+                .next = operation->second,
+                .no_op = true,
+            };
+        }
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if (current->second.metadata_generation !=
+        request.expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (current->second.availability != WeightAvailabilityState::READY &&
+        current->second.availability != WeightAvailabilityState::DEGRADED) {
+        return tl::make_unexpected(WeightManagementError::NOT_READY);
+    }
+    std::optional<uint64_t> nearest;
+    if (CountActiveLeasesLocked(current->second, now_ms, &nearest) != 0) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(
+            current->second.metadata_generation) ||
+        next_operation_id_ == 0 ||
+        next_operation_id_ == std::numeric_limits<uint64_t>::max()) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+
+    const uint64_t operation_id = next_operation_id_++;
+    const uint64_t operation_time =
+        std::max(current->second.updated_at_ms, now_ms);
+    auto next_metadata = current->second;
+    next_metadata.operation = OperationForTarget(request.target_residency);
+    next_metadata.operation_id = operation_id;
+    ++next_metadata.metadata_generation;
+    next_metadata.updated_at_ms = operation_time;
+    WeightResidencyOperation next_operation{
+        .operation_id = operation_id,
+        .identity = request.identity,
+        .operation = next_metadata.operation,
+        .target_residency = request.target_residency,
+        .fenced_metadata_generation = next_metadata.metadata_generation,
+        .started_at_ms = operation_time,
+        .updated_at_ms = operation_time,
+        .processed_members = 0,
+        .total_members = 0,
+        .cursor = {},
+        .message = {},
+    };
+    return WeightOperationMutation{
+        .metadata =
+            WeightMetadataMutation{
+                .identity = request.identity,
+                .previous = current->second,
+                .next = std::move(next_metadata),
+            },
+        .previous = std::nullopt,
+        .next = std::move(next_operation),
+        .no_op = false,
+    };
+}
+
+WeightMetadataStore::Result<WeightOperationMutation>
+WeightMetadataStore::PrepareFinishOperation(
+    uint64_t operation_id, WeightResidencyState observed_residency,
+    uint64_t now_ms) const {
+    if (operation_id == 0 ||
+        (observed_residency != WeightResidencyState::HOT &&
+         observed_residency != WeightResidencyState::COLD)) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto operation = operations_.find(operation_id);
+    if (operation == operations_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    const auto revision = revisions_.find(operation->second.identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.operation_id != operation_id ||
+        revision->second.operation != operation->second.operation) {
+        if (revision->second.operation == WeightOperationState::NONE &&
+            revision->second.residency == observed_residency) {
+            return WeightOperationMutation{
+                .metadata =
+                    WeightMetadataMutation{
+                        .identity = revision->first,
+                        .previous = revision->second,
+                        .next = revision->second,
+                        .no_op = true,
+                    },
+                .previous = operation->second,
+                .next = operation->second,
+                .no_op = true,
+            };
+        }
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (operation->second.target_residency != observed_residency) {
+        return tl::make_unexpected(WeightManagementError::NOT_READY);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(
+            revision->second.metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    auto next_metadata = revision->second;
+    next_metadata.residency = observed_residency;
+    next_metadata.operation = WeightOperationState::NONE;
+    next_metadata.operation_id = 0;
+    ++next_metadata.metadata_generation;
+    const uint64_t operation_time =
+        std::max({revision->second.updated_at_ms,
+                  operation->second.updated_at_ms, now_ms});
+    next_metadata.updated_at_ms = operation_time;
+    auto next_operation = operation->second;
+    next_operation.updated_at_ms = operation_time;
+    next_operation.processed_members = next_operation.total_members;
+    next_operation.cursor.clear();
+    next_operation.message = "completed";
+    return WeightOperationMutation{
+        .metadata =
+            WeightMetadataMutation{
+                .identity = revision->first,
+                .previous = revision->second,
+                .next = std::move(next_metadata),
+            },
+        .previous = operation->second,
+        .next = std::move(next_operation),
+    };
+}
+
+WeightMetadataStore::Result<WeightOperationMutation>
+WeightMetadataStore::PrepareUpdateOperationProgress(uint64_t operation_id,
+                                                    uint64_t processed_members,
+                                                    uint64_t total_members,
+                                                    std::string cursor,
+                                                    uint64_t now_ms) const {
+    if (operation_id == 0 || total_members == 0 ||
+        processed_members > total_members ||
+        (!cursor.empty() && !IsValidWeightComponent(cursor))) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto operation = operations_.find(operation_id);
+    if (operation == operations_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    const auto revision = revisions_.find(operation->second.identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.operation_id != operation_id ||
+        revision->second.operation != operation->second.operation ||
+        operation->second.message == "completed") {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    auto next_operation = operation->second;
+    const bool unchanged =
+        next_operation.processed_members == processed_members &&
+        next_operation.total_members == total_members &&
+        next_operation.cursor == cursor;
+    if (unchanged) {
+        return WeightOperationMutation{
+            .metadata =
+                WeightMetadataMutation{
+                    .identity = revision->first,
+                    .previous = revision->second,
+                    .next = revision->second,
+                    .no_op = true,
+                },
+            .previous = operation->second,
+            .next = operation->second,
+            .no_op = true,
+        };
+    }
+    next_operation.processed_members = processed_members;
+    next_operation.total_members = total_members;
+    next_operation.cursor = std::move(cursor);
+    next_operation.updated_at_ms =
+        std::max(next_operation.updated_at_ms, now_ms);
+    return WeightOperationMutation{
+        .metadata =
+            WeightMetadataMutation{
+                .identity = revision->first,
+                .previous = revision->second,
+                .next = revision->second,
+                .no_op = false,
+            },
+        .previous = operation->second,
+        .next = std::move(next_operation),
+        .no_op = false,
+    };
+}
+
+WeightMetadataStore::Result<WeightResidencyOperation>
+WeightMetadataStore::Publish(const WeightOperationMutation& mutation) {
+    std::lock_guard lock(mutex_);
+    const auto current = revisions_.find(mutation.metadata.identity);
+    if (!mutation.metadata.previous.has_value() ||
+        current == revisions_.end() ||
+        current->second != *mutation.metadata.previous) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (mutation.no_op) {
+        if (!mutation.next.has_value()) {
+            return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+        }
+        return *mutation.next;
+    }
+    if (!mutation.metadata.next.has_value() || !mutation.next.has_value()) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    if (!mutation.previous.has_value()) {
+        std::optional<uint64_t> nearest;
+        if (CountActiveLeasesLocked(
+                current->second, mutation.next->started_at_ms, &nearest) != 0) {
+            return tl::make_unexpected(WeightManagementError::BUSY);
+        }
+    }
+    const auto operation = operations_.find(mutation.next->operation_id);
+    if (mutation.previous.has_value()) {
+        if (operation == operations_.end() ||
+            operation->second != *mutation.previous) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+    } else if (operation != operations_.end()) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (!mutation.previous.has_value() &&
+        mutation.next->operation_id == std::numeric_limits<uint64_t>::max()) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    revisions_[mutation.metadata.identity] = *mutation.metadata.next;
+    operations_[mutation.next->operation_id] = *mutation.next;
+    if (!mutation.previous.has_value()) {
+        next_operation_id_ =
+            std::max(next_operation_id_, mutation.next->operation_id + 1);
+    }
+    return *mutation.next;
+}
+
+WeightMetadataStore::Result<WeightResidencyOperation>
+WeightMetadataStore::QueryOperation(uint64_t operation_id) const {
+    if (operation_id == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto operation = operations_.find(operation_id);
+    if (operation == operations_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    return operation->second;
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareDelete(const DeleteWeightRevisionRequest& request,
+                                   uint64_t now_ms) const {
+    if (!ValidateWeightRevisionIdentity(request.identity).ok() ||
+        request.expected_metadata_generation == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    std::lock_guard lock(mutex_);
+    const auto revision = revisions_.find(request.identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.availability == WeightAvailabilityState::DELETED) {
+        if (!MatchesIdempotentRetryGeneration(
+                revision->second.metadata_generation,
+                request.expected_metadata_generation)) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+        return WeightMetadataMutation{
+            .identity = request.identity,
+            .previous = revision->second,
+            .next = revision->second,
+            .no_op = true,
+        };
+    }
+    if (revision->second.availability == WeightAvailabilityState::DELETING) {
+        if (!MatchesIdempotentRetryGeneration(
+                revision->second.metadata_generation,
+                request.expected_metadata_generation)) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+        return WeightMetadataMutation{
+            .identity = request.identity,
+            .previous = revision->second,
+            .next = revision->second,
+            .no_op = true,
+        };
+    }
+    if (revision->second.metadata_generation !=
+        request.expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    std::optional<uint64_t> nearest;
+    if (CountActiveLeasesLocked(revision->second, now_ms, &nearest) != 0) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if (revision->second.operation != WeightOperationState::NONE) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if (revision->second.availability != WeightAvailabilityState::READY &&
+        revision->second.availability != WeightAvailabilityState::DEGRADED) {
+        return tl::make_unexpected(WeightManagementError::NOT_READY);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(
+            revision->second.metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    auto next = revision->second;
+    next.availability = WeightAvailabilityState::DELETING;
+    ++next.metadata_generation;
+    next.updated_at_ms = std::max(next.updated_at_ms, now_ms);
+    return WeightMetadataMutation{
+        .identity = request.identity,
+        .previous = revision->second,
+        .next = std::move(next),
+    };
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareFinishDelete(const WeightRevisionIdentity& identity,
+                                         uint64_t expected_metadata_generation,
+                                         uint64_t now_ms) const {
+    std::lock_guard lock(mutex_);
+    const auto revision = revisions_.find(identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.availability == WeightAvailabilityState::DELETED) {
+        if (!MatchesIdempotentRetryGeneration(
+                revision->second.metadata_generation,
+                expected_metadata_generation)) {
+            return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+        }
+        return WeightMetadataMutation{
+            .identity = identity,
+            .previous = revision->second,
+            .next = revision->second,
+            .no_op = true,
+        };
+    }
+    if (revision->second.metadata_generation != expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (revision->second.availability != WeightAvailabilityState::DELETING) {
+        return tl::make_unexpected(WeightManagementError::CONFLICT);
+    }
+    if (!CanAdvanceWeightMetadataGeneration(expected_metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    auto next = revision->second;
+    next.availability = WeightAvailabilityState::DELETED;
+    next.residency = WeightResidencyState::ABSENT;
+    ++next.metadata_generation;
+    next.updated_at_ms = std::max(next.updated_at_ms, now_ms);
+    return WeightMetadataMutation{
+        .identity = identity,
+        .previous = revision->second,
+        .next = std::move(next),
+    };
+}
+
+WeightMetadataStore::Result<WeightMetadataMutation>
+WeightMetadataStore::PrepareReconcile(const WeightRevisionIdentity& identity,
+                                      uint64_t expected_metadata_generation,
+                                      WeightAvailabilityState availability,
+                                      WeightResidencyState residency,
+                                      uint64_t now_ms) const {
+    std::lock_guard lock(mutex_);
+    const auto revision = revisions_.find(identity);
+    if (revision == revisions_.end()) {
+        return tl::make_unexpected(WeightManagementError::NOT_FOUND);
+    }
+    if (revision->second.metadata_generation != expected_metadata_generation) {
+        return tl::make_unexpected(WeightManagementError::STALE_GENERATION);
+    }
+    if (revision->second.operation != WeightOperationState::NONE ||
+        revision->second.availability == WeightAvailabilityState::IMPORTING ||
+        revision->second.availability == WeightAvailabilityState::DELETING ||
+        revision->second.availability == WeightAvailabilityState::DELETED) {
+        return tl::make_unexpected(WeightManagementError::BUSY);
+    }
+    if ((availability != WeightAvailabilityState::READY &&
+         availability != WeightAvailabilityState::DEGRADED) ||
+        residency == WeightResidencyState::UNKNOWN) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    if (revision->second.availability == availability &&
+        revision->second.residency == residency) {
+        return WeightMetadataMutation{
+            .identity = identity,
+            .previous = revision->second,
+            .next = revision->second,
+            .no_op = true,
+        };
+    }
+    if (!CanAdvanceWeightMetadataGeneration(expected_metadata_generation)) {
+        return tl::make_unexpected(WeightManagementError::GENERATION_EXHAUSTED);
+    }
+    auto next = revision->second;
+    next.availability = availability;
+    next.residency = residency;
+    ++next.metadata_generation;
+    next.updated_at_ms = std::max(next.updated_at_ms, now_ms);
+    return WeightMetadataMutation{
+        .identity = identity,
+        .previous = revision->second,
+        .next = std::move(next),
+    };
+}
+
+bool WeightMetadataStore::IsManagedGroup(
+    const std::string& payload_group_id) const {
+    std::lock_guard lock(mutex_);
+    return group_index_.contains(payload_group_id);
+}
+
+bool WeightMetadataStore::AllowsGroupMemberMutation(
+    const std::string& payload_group_id) const {
+    std::lock_guard lock(mutex_);
+    const auto group = group_index_.find(payload_group_id);
+    if (group == group_index_.end()) {
+        return true;
+    }
+    const auto revision = revisions_.find(group->second);
+    return revision != revisions_.end() &&
+           revision->second.availability == WeightAvailabilityState::IMPORTING;
+}
+
+WeightMetadataSnapshot WeightMetadataStore::ExportSnapshot() const {
+    std::lock_guard lock(mutex_);
+    WeightMetadataSnapshot snapshot{
+        .schema_version = 1,
+        .metadata = {},
+        .leases = {},
+        .operations = {},
+        .next_lease_id = next_lease_id_,
+        .next_operation_id = next_operation_id_,
+    };
+    snapshot.metadata.reserve(revisions_.size());
+    for (const auto& [identity, metadata] : revisions_) {
+        static_cast<void>(identity);
+        snapshot.metadata.push_back(metadata);
+    }
+    snapshot.leases.reserve(leases_.size());
+    for (const auto& [lease_id, lease] : leases_) {
+        static_cast<void>(lease_id);
+        snapshot.leases.push_back(lease);
+    }
+    std::sort(snapshot.leases.begin(), snapshot.leases.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.lease_id < rhs.lease_id;
+              });
+    snapshot.operations.reserve(operations_.size());
+    for (const auto& [operation_id, operation] : operations_) {
+        static_cast<void>(operation_id);
+        snapshot.operations.push_back(operation);
+    }
+    std::sort(snapshot.operations.begin(), snapshot.operations.end(),
+              [](const auto& lhs, const auto& rhs) {
+                  return lhs.operation_id < rhs.operation_id;
+              });
+    return snapshot;
+}
+
+WeightMetadataStore::Result<void> WeightMetadataStore::RestoreSnapshot(
+    const WeightMetadataSnapshot& snapshot) {
+    if (snapshot.schema_version != 1 || snapshot.next_lease_id == 0 ||
+        snapshot.next_operation_id == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    std::map<WeightRevisionIdentity, WeightRevisionMetadata> revisions;
+    std::map<std::string, WeightRevisionIdentity> group_index;
+    for (const auto& metadata : snapshot.metadata) {
+        if (!ValidateWeightRevisionMetadata(metadata).ok() ||
+            !IsValidWeightComponent(metadata.manifest.payload_group_id) ||
+            !revisions.emplace(metadata.identity, metadata).second ||
+            !group_index
+                 .emplace(metadata.manifest.payload_group_id, metadata.identity)
+                 .second) {
+            return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+        }
+    }
+
+    uint64_t max_lease_id = 0;
+    std::unordered_map<uint64_t, WeightRevisionLease> leases;
+    for (const auto& lease : snapshot.leases) {
+        const auto revision = revisions.find(lease.identity);
+        if (lease.lease_id == 0 ||
+            !ValidateWeightRevisionIdentity(lease.identity).ok() ||
+            !IsValidWeightComponent(lease.holder) || lease.expires_at_ms == 0 ||
+            lease.fenced_metadata_generation == 0 ||
+            revision == revisions.end() ||
+            lease.fenced_metadata_generation >
+                revision->second.metadata_generation ||
+            !leases.emplace(lease.lease_id, lease).second) {
+            return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+        }
+        max_lease_id = std::max(max_lease_id, lease.lease_id);
+    }
+    if (snapshot.next_lease_id <= max_lease_id) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+
+    uint64_t max_operation_id = 0;
+    std::unordered_map<uint64_t, WeightResidencyOperation> operations;
+    for (const auto& operation : snapshot.operations) {
+        const auto revision = revisions.find(operation.identity);
+        const bool completed = operation.message == "completed";
+        if (operation.operation_id == 0 ||
+            !ValidateWeightRevisionIdentity(operation.identity).ok() ||
+            !IsValidWeightOperationState(operation.operation) ||
+            operation.operation == WeightOperationState::NONE ||
+            !IsValidWeightResidencyState(operation.target_residency) ||
+            (operation.target_residency != WeightResidencyState::HOT &&
+             operation.target_residency != WeightResidencyState::COLD) ||
+            (operation.operation == WeightOperationState::EVICTING &&
+             operation.target_residency != WeightResidencyState::COLD) ||
+            (operation.operation == WeightOperationState::REHYDRATING &&
+             operation.target_residency != WeightResidencyState::HOT) ||
+            operation.fenced_metadata_generation == 0 ||
+            operation.updated_at_ms < operation.started_at_ms ||
+            operation.processed_members > operation.total_members ||
+            (!operation.cursor.empty() &&
+             !IsValidWeightComponent(operation.cursor)) ||
+            revision == revisions.end() ||
+            (!completed &&
+             (revision->second.operation != operation.operation ||
+              revision->second.operation_id != operation.operation_id ||
+              revision->second.metadata_generation !=
+                  operation.fenced_metadata_generation)) ||
+            (completed &&
+             (operation.fenced_metadata_generation ==
+                  std::numeric_limits<uint64_t>::max() ||
+              revision->second.metadata_generation <=
+                  operation.fenced_metadata_generation ||
+              (revision->second.metadata_generation ==
+                   operation.fenced_metadata_generation + 1 &&
+               (revision->second.operation != WeightOperationState::NONE ||
+                revision->second.operation_id != 0 ||
+                revision->second.residency != operation.target_residency)))) ||
+            !operations.emplace(operation.operation_id, operation).second) {
+            return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+        }
+        max_operation_id = std::max(max_operation_id, operation.operation_id);
+    }
+    if (snapshot.next_operation_id <= max_operation_id) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    for (const auto& [identity, metadata] : revisions) {
+        static_cast<void>(identity);
+        if (metadata.operation != WeightOperationState::NONE &&
+            !operations.contains(metadata.operation_id)) {
+            return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+        }
+    }
+
+    std::lock_guard lock(mutex_);
+    revisions_ = std::move(revisions);
+    group_index_ = std::move(group_index);
+    leases_ = std::move(leases);
+    operations_ = std::move(operations);
+    next_lease_id_ = snapshot.next_lease_id;
+    next_operation_id_ = snapshot.next_operation_id;
+    return {};
+}
+
+void WeightMetadataStore::Clear() {
+    std::lock_guard lock(mutex_);
+    revisions_.clear();
+    group_index_.clear();
+    leases_.clear();
+    operations_.clear();
+    next_lease_id_ = 1;
+    next_operation_id_ = 1;
+}
+
+std::string WeightMetadataStore::MakePageToken(
+    const WeightRevisionIdentity& identity) {
+    return identity.revision + kPageTokenSeparator +
+           std::to_string(identity.weight_generation);
+}
+
+WeightMetadataStore::Result<std::pair<std::string, uint64_t>>
+WeightMetadataStore::ParsePageToken(const std::string& page_token) {
+    const auto separator = page_token.rfind(kPageTokenSeparator);
+    if (separator == std::string::npos || separator == 0 ||
+        separator + 1 == page_token.size()) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    uint64_t generation = 0;
+    const auto value = std::string_view(page_token).substr(separator + 1);
+    const auto [end, error] =
+        std::from_chars(value.data(), value.data() + value.size(), generation);
+    if (error != std::errc() || end != value.data() + value.size() ||
+        generation == 0) {
+        return tl::make_unexpected(WeightManagementError::INVALID_ARGUMENT);
+    }
+    return std::make_pair(page_token.substr(0, separator), generation);
+}
+
+uint64_t WeightMetadataStore::AddTtl(uint64_t now_ms, uint64_t ttl_ms) {
+    if (ttl_ms > std::numeric_limits<uint64_t>::max() - now_ms) {
+        return std::numeric_limits<uint64_t>::max();
+    }
+    return now_ms + ttl_ms;
+}
+
+WeightOperationState WeightMetadataStore::OperationForTarget(
+    WeightResidencyState target) {
+    return target == WeightResidencyState::COLD
+               ? WeightOperationState::EVICTING
+               : WeightOperationState::REHYDRATING;
+}
+
+uint64_t WeightMetadataStore::CountActiveLeasesLocked(
+    const WeightRevisionMetadata& metadata, uint64_t now_ms,
+    std::optional<uint64_t>* nearest) const {
+    uint64_t count = 0;
+    for (const auto& [lease_id, lease] : leases_) {
+        static_cast<void>(lease_id);
+        if (lease.identity != metadata.identity ||
+            lease.fenced_metadata_generation > metadata.metadata_generation ||
+            lease.expires_at_ms <= now_ms) {
+            continue;
+        }
+        ++count;
+        if (!nearest->has_value() || lease.expires_at_ms < **nearest) {
+            *nearest = lease.expires_at_ms;
+        }
+    }
+    return count;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-store/tests/CMakeLists.txt b/mooncake-store/tests/CMakeLists.txt
index 201ab04c87..5b0edd02ca 100644
--- a/mooncake-store/tests/CMakeLists.txt
+++ b/mooncake-store/tests/CMakeLists.txt
@@ -1,13 +1,16 @@
+set(MOONCAKE_STORE_TESTS_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+
 function(add_store_test name)
   add_executable(${name} ${ARGN})
-  target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+  target_include_directories(${name} PRIVATE ${MOONCAKE_STORE_TESTS_SOURCE_DIR})
   target_link_libraries(
     ${name}
     PUBLIC mooncake_store
+           master_service_test_peer
            transfer_engine
            cachelib_memory_allocator
            ${ETCD_WRAPPER_LIB}
-           glog
+           glog::glog
            ibverbs
            gtest
            gtest_main
@@ -17,15 +20,16 @@ endfunction()
 
 function(add_ha_test name)
   add_executable(${name} ${ARGN})
-  target_include_directories(${name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+  target_include_directories(${name} PRIVATE ${MOONCAKE_STORE_TESTS_SOURCE_DIR})
   target_link_libraries(
     ${name}
     PUBLIC mooncake_store
+           master_service_test_peer
            transfer_engine
            cachelib_memory_allocator
            ${ETCD_WRAPPER_LIB}
-           glog
-           gflags
+           glog::glog
+           gflags::gflags
            ibverbs
            gtest
            gtest_main
@@ -34,43 +38,91 @@ function(add_ha_test name)
 endfunction()
 
 add_store_test(buffer_allocator_test buffer_allocator_test.cpp)
+add_store_test(weight_management_contract_test
+               weight_management_contract_test.cpp)
+add_store_test(weight_metadata_store_test weight_metadata_store_test.cpp)
+add_store_test(region_driver_test region_driver_test.cpp)
+add_store_test(replica_allocator_test replica_allocator_test.cpp)
+add_store_test(segment_pool_test segment_pool_test.cpp)
 add_store_test(runtime_accelerator_test runtime_accelerator_test.cpp)
+add_store_test(batch_read_fanout_test batch_read_fanout_test.cpp)
 add_store_test(registered_pinned_memory_test registered_pinned_memory_test.cpp)
 add_store_test(allocation_strategy_test allocation_strategy_test.cpp)
+add_store_test(client_liveness_test client_liveness_test.cpp)
+add_store_test(master_config_test master_config_test.cpp)
 add_store_test(replica_selection_test replica_selection_test.cpp)
+add_store_test(replica_selection_config_test replica_selection_config_test.cpp)
+set_tests_properties(replica_selection_test
+                     PROPERTIES ENVIRONMENT "MC_STORE_REPLICA_SCORING=0")
 add_test(
   NAME replica_selection_env_opt_in_test
-  COMMAND replica_selection_test
-          --gtest_filter=ReplicaSelectionTest.EnvironmentOptInUsesBuiltinScorer)
+  COMMAND
+    replica_selection_test
+    --gtest_filter=ReplicaSelectionTest.EnvironmentOptInUsesBuiltinScorer:ReplicaSelectionTest.EnvironmentIsCachedButInjectedScorerRemainsLive
+)
 set_tests_properties(replica_selection_env_opt_in_test
                      PROPERTIES ENVIRONMENT "MC_STORE_REPLICA_SCORING=1")
 add_store_test(eviction_strategy_test eviction_strategy_test.cpp)
 add_store_test(deadline_scheduler_test deadline_scheduler_test.cpp)
+add_store_test(background_worker_test background_worker_test.cpp)
 add_store_test(kv_event_publisher_test kv_event_publisher_test.cpp)
 if(ENABLE_KV_EVENTS)
-  find_library(
-    KV_EVENT_TEST_ZMQ_LIBRARY
-    NAMES zmq libzmq
-    PATHS /usr/lib /usr/local/lib /usr/lib64)
-  find_path(
-    KV_EVENT_TEST_ZMQ_INCLUDE_DIR
-    NAMES zmq.h
-    PATHS /usr/include /usr/local/include)
   target_compile_definitions(kv_event_publisher_test
                              PRIVATE MOONCAKE_ENABLE_KV_EVENTS=1)
-  if(KV_EVENT_TEST_ZMQ_LIBRARY AND KV_EVENT_TEST_ZMQ_INCLUDE_DIR)
-    target_include_directories(kv_event_publisher_test
-                               PRIVATE ${KV_EVENT_TEST_ZMQ_INCLUDE_DIR})
-    target_link_libraries(kv_event_publisher_test
-                          PRIVATE ${KV_EVENT_TEST_ZMQ_LIBRARY})
-  endif()
+  target_link_libraries(kv_event_publisher_test PRIVATE Mooncake::libzmq)
 endif()
+add_subdirectory(master_service)
+
 add_store_test(master_service_test master_service_test.cpp)
-add_store_test(batch_evict_test batch_evict_test.cpp)
-add_store_test(master_scenario_test master_scenario.cpp
-               master_scenario_test.cpp)
-add_store_test(master_service_scenario_test master_scenario.cpp
-               master_service_scenario_test.cpp)
+add_store_test(master_service_group_test master_service_group_test.cpp)
+add_ha_test(master_service_evict_scenario_test
+            master_service_evict_scenario_test.cpp)
+target_link_libraries(master_service_evict_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_scenario_test master_service_scenario_test.cpp)
+target_link_libraries(master_service_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_group_scenario_test
+               master_service_group_scenario_test.cpp)
+target_link_libraries(master_service_group_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_tenant_scenario_test
+               master_service_tenant_scenario_test.cpp)
+target_link_libraries(master_service_tenant_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_placement_scenario_test
+               master_service_placement_scenario_test.cpp)
+target_link_libraries(master_service_placement_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_replication_scenario_test
+               master_service_replication_scenario_test.cpp)
+target_link_libraries(master_service_replication_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_task_scenario_test
+               master_service_task_scenario_test.cpp)
+target_link_libraries(master_service_task_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_segment_scenario_test
+               master_service_segment_scenario_test.cpp)
+target_link_libraries(master_service_segment_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_dfs_scenario_test
+               master_service_dfs_scenario_test.cpp)
+target_link_libraries(master_service_dfs_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_ssd_scenario_test
+               master_service_ssd_scenario_test.cpp)
+target_link_libraries(master_service_ssd_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_offload_scenario_test
+               master_service_offload_scenario_test.cpp)
+target_link_libraries(master_service_offload_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(master_service_concurrent_scenario_test
+               master_service_concurrent_scenario_test.cpp)
+target_link_libraries(master_service_concurrent_scenario_test
+                      PRIVATE master_service_test_dsl)
+add_store_test(config_helper_test config_helper_test.cpp)
 add_store_test(master_service_config_test master_service_config_test.cpp)
 add_store_test(master_service_processing_key_double_erase_test
                master_service_processing_key_double_erase_test.cpp)
@@ -80,6 +132,7 @@ add_store_test(batch_remove_test batch_remove_test.cpp)
 add_store_test(master_service_ssd_test master_service_ssd_test.cpp)
 add_store_test(offload_on_evict_test offload_on_evict_test.cpp)
 add_store_test(promotion_on_hit_test promotion_on_hit_test.cpp)
+add_store_test(dynamic_replication_test dynamic_replication_test.cpp)
 add_store_test(file_storage_promotion_test file_storage_promotion_test.cpp)
 add_store_test(master_service_ssd_test_for_snapshot
                ha/snapshot/master_service_ssd_test_for_snapshot.cpp)
@@ -88,7 +141,11 @@ add_store_test(master_service_promotion_test_for_snapshot
 if(USE_NOF)
   add_store_test(nof_heartbeat_test nof_heartbeat_test.cpp)
 endif()
+add_store_test(nof_register_config_test nof_register_config_test.cpp)
+add_store_test(spdk_controller_config_test spdk_controller_config_test.cpp)
 add_store_test(client_integration_test client_integration_test.cpp)
+add_store_test(batch_replica_clear_tenant_rpc_test
+               batch_replica_clear_tenant_rpc_test.cpp)
 add_test(
   NAME object_checksum_client_test
   COMMAND
@@ -98,6 +155,8 @@ add_test(
 set_tests_properties(object_checksum_client_test
                      PROPERTIES ENVIRONMENT "MOONCAKE_STORE_CHECKSUM=1")
 add_store_test(rpc_timeout_test rpc_timeout_test.cpp)
+add_store_test(rpc_timeout_config_test rpc_timeout_config_test.cpp)
+add_store_test(rpc_protocol_config_test rpc_protocol_config_test.cpp)
 if(USE_CXL)
   add_store_test(cxl_client_integration_test cxl_client_integration_test.cpp)
 endif()
@@ -106,38 +165,110 @@ add_store_test(master_admin_server_test master_admin_server_test.cpp)
 add_store_test(posix_file_test posix_file_test.cpp)
 add_store_test(thread_pool_test thread_pool_test.cpp)
 add_store_test(transfer_task_test transfer_task_test.cpp)
+if(USE_TENT)
+  add_test(
+    NAME transfer_task_tent_completion_test
+    COMMAND transfer_task_test
+            --gtest_filter=TransferTaskTest.RemoteTransferWaitCompletesCorrectly
+  )
+  set_tests_properties(transfer_task_tent_completion_test
+                       PROPERTIES ENVIRONMENT "MC_USE_TENT=1" TIMEOUT 30)
+endif()
+add_store_test(transfer_submitter_config_test
+               transfer_submitter_config_test.cpp)
+find_package(CUDAToolkit QUIET)
+if(CUDAToolkit_FOUND)
+  target_compile_definitions(transfer_task_test PRIVATE MOONCAKE_TEST_CUDA_H2D)
+  target_link_libraries(transfer_task_test PRIVATE CUDA::cudart)
+endif()
 if(USE_CUDA)
   find_package(CUDAToolkit REQUIRED)
   target_compile_definitions(transfer_task_test PRIVATE USE_CUDA)
-  target_link_libraries(transfer_task_test PRIVATE CUDA::cudart)
   if(USE_TENT)
     add_test(
       NAME transfer_scatter_tent_test
-      COMMAND transfer_task_test
-              --gtest_filter=TransferTaskTest.TransferScatterWritesGpuDestinationDirectly)
-    set_tests_properties(transfer_scatter_tent_test
-                         PROPERTIES ENVIRONMENT "MC_USE_TENT=1")
+      COMMAND
+        transfer_task_test
+        --gtest_filter=TransferTaskTest.TransferScatterWritesGpuDestinationDirectly
+    )
+    set_tests_properties(transfer_scatter_tent_test PROPERTIES ENVIRONMENT
+                                                               "MC_USE_TENT=1")
   endif()
 endif()
 add_store_test(tenant_quota_test tenant_quota_test.cpp)
+add_store_test(tenant_quota_ledger_test tenant_quota_ledger_test.cpp)
 add_store_test(tenant_id_test tenant_id_test.cpp)
+add_store_test(object_entry_test object_entry_test.cpp)
+add_store_test(object_index_test object_index_test.cpp)
+add_store_test(dynamic_replication_lease_table_test dynamic_replication_lease_table_test.cpp)
+add_store_test(group_index_test group_index_test.cpp)
 add_store_test(segment_test segment_test.cpp)
+add_executable(local_ssd_test local_ssd/local_ssd_test.cpp)
+target_include_directories(local_ssd_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(local_ssd_test PRIVATE mooncake_local_ssd gtest
+                                             gtest_main)
+add_test(NAME local_ssd_test COMMAND local_ssd_test)
+add_store_test(local_ssd_codec_test ha/snapshot/local_ssd_codec_test.cpp)
+add_store_test(store_resource_snapshot_codec_test
+               ha/snapshot/store_resource_snapshot_codec_test.cpp)
 add_store_test(offset_allocator_test offset_allocator_test.cpp)
-add_store_test(utils_test utils_test.cpp)
+add_store_test(byte_size_test byte_size_test.cpp)
+add_store_test(network_test network_test.cpp)
+add_store_test(hugepage_config_test hugepage_config_test.cpp)
+add_store_test(hugepage_size_env_test hugepage_size_env_test.cpp)
+add_store_test(random_test random_test.cpp)
 add_store_test(client_buffer_test client_buffer_test.cpp)
+add_store_test(client_auto_port_config_test client_auto_port_config_test.cpp)
+add_store_test(client_auto_discovery_config_test
+               client_auto_discovery_config_test.cpp)
+add_store_test(cxl_segment_config_test cxl_segment_config_test.cpp)
+add_store_test(client_numa_config_test client_numa_config_test.cpp)
+add_store_test(local_hot_cache_config_test local_hot_cache_config_test.cpp)
 add_store_test(client_local_hot_cache_test client_local_hot_cache_test.cpp)
 add_store_test(client_tcp_local_memcpy_test client_tcp_local_memcpy_test.cpp)
 add_store_test(pybind_client_test pybind_client_test.cpp)
+if(USE_CUDA)
+  target_compile_definitions(pybind_client_test PRIVATE MOONCAKE_TEST_CUDA_H2D)
+  target_link_libraries(pybind_client_test PRIVATE CUDA::cudart)
+endif()
 add_store_test(ipv6_client_test ipv6_client_test.cpp)
 add_store_test(host_port_fix_test host_port_fix_test.cpp)
 add_store_test(client_metrics_test client_metrics_test.cpp)
+add_store_test(client_host_identity_config_test
+               client_host_identity_config_test.cpp)
+add_store_test(client_metric_config_test client_metric_config_test.cpp)
 add_store_test(ssd_metrics_test ssd_metrics_test.cpp)
+add_store_test(allocator_metric_test allocator_metric_test.cpp)
 add_store_test(serializer_test serializer_test.cpp)
+add_store_test(dfs_posix_test dfs_posix_test.cpp)
+add_store_test(dfs_immutable_bucket_allocator_test
+               dfs_immutable_bucket_allocator_test.cpp)
+add_store_test(dfs_immutable_bucket_backend_test
+               dfs_immutable_bucket_backend_test.cpp)
+add_store_test(dfs_immutable_bucket_client_test
+               dfs_immutable_bucket_client_test.cpp)
+add_store_test(distributed_storage_config_test
+               distributed_storage_config_test.cpp)
+add_store_test(dfs_sync_client_test dfs_sync_client_test.cpp)
+add_test(
+  NAME dfs_read_checksum_test
+  COMMAND
+    dfs_sync_client_test
+    "--gtest_filter=DfsSyncClientTest.BatchGetVerifiesDfsChecksum:DfsSyncClientTest.GetVerifiesDfsChecksumAndRecordsError"
+)
+set_tests_properties(dfs_read_checksum_test
+                     PROPERTIES ENVIRONMENT "MOONCAKE_STORE_CHECKSUM=1")
+if(USE_3FS)
+  add_store_test(dfs_hf3fs_test dfs_hf3fs_test.cpp)
+endif()
 add_store_test(
   embedded_snapshot_catalog_store_test
   ha/snapshot/catalog/backends/embedded/embedded_snapshot_catalog_store_test.cpp
 )
 add_store_test(zstd_util_test zstd_util_test.cpp)
+add_store_test(local_file_snapshot_config_test
+               local_file_snapshot_config_test.cpp)
+add_store_test(s3_client_config_test s3_client_config_test.cpp)
 add_store_test(
   local_file_snapshot_object_store_test
   ha/snapshot/object/backends/local/local_file_snapshot_object_store_test.cpp)
@@ -146,17 +277,56 @@ add_store_test(snapshot_child_process_test
                ha/snapshot/snapshot_child_process_test.cpp)
 add_store_test(master_snapshot_codec_test
                ha/snapshot/master_snapshot_codec_test.cpp)
+add_ha_test(batch_oplog_snapshot_types_test
+            ha/snapshot/batch_oplog/metadata_test.cpp)
+add_ha_test(batch_oplog_snapshot_codec_test
+            ha/snapshot/batch_oplog/codec_test.cpp)
+add_ha_test(batch_oplog_snapshot_writer_test
+            ha/snapshot/batch_oplog/writer_test.cpp)
+add_ha_test(batch_oplog_snapshot_provider_test
+            ha/snapshot/batch_oplog/provider_test.cpp)
+add_ha_test(batch_oplog_snapshot_publisher_test
+            ha/snapshot/batch_oplog/publisher_test.cpp)
+add_ha_test(batch_oplog_pruning_coordinator_test
+            ha/snapshot/batch_oplog/pruning_coordinator_test.cpp)
+add_ha_test(batch_oplog_snapshot_gc_test ha/snapshot/batch_oplog/gc_test.cpp)
+add_ha_test(batch_oplog_snapshot_coordinator_test
+            ha/snapshot/batch_oplog/coordinator_test.cpp)
+add_ha_test(batch_oplog_snapshot_promotion_test
+            ha/snapshot/batch_oplog/promotion_test.cpp)
+add_ha_test(batch_oplog_snapshot_rebootstrap_test
+            ha/snapshot/batch_oplog/rebootstrap_test.cpp)
 add_store_test(master_service_test_for_snapshot
                ha/snapshot/master_service_test_for_snapshot.cpp)
 add_store_test(non_ha_reconnect_test non_ha_reconnect_test.cpp)
+add_store_test(nvme_kv_connector_config_test nvme_kv/connector_config_test.cpp)
+add_store_test(ha_cluster_namespace_config_test
+               ha_cluster_namespace_config_test.cpp)
+add_store_test(redis_connection_config_test redis_connection_config_test.cpp)
+add_store_test(nvme_kv_io_concurrency_config_test
+               nvme_kv/io_concurrency_config_test.cpp)
+add_store_test(nvme_kv_storage_backend_test nvme_kv/storage_backend_test.cpp)
 add_store_test(storage_backend_test storage_backend_test.cpp)
+add_store_test(bucket_backend_config_test bucket_backend_config_test.cpp)
+add_store_test(file_per_key_config_test file_per_key_config_test.cpp)
+add_store_test(offset_allocator_backend_config_test
+               offset_allocator_backend_config_test.cpp)
 add_store_test(client_storage_backend_test client_storage_backend_test.cpp)
+add_store_test(object_storage_adapter_test object_storage_adapter_test.cpp)
 add_store_test(mutex_test mutex_test.cpp)
 add_store_test(file_storage_test file_storage_test.cpp)
+add_store_test(file_storage_config_test file_storage_config_test.cpp)
+add_store_test(fileread_worker_pool_config_test
+               fileread_worker_pool_config_test.cpp)
+add_store_test(fileread_worker_pool_test fileread_worker_pool_test.cpp)
+if(MOONCAKE_OSS_ADAPTER_ENABLED)
+  target_compile_definitions(file_storage_test PRIVATE HAVE_OSS_ADAPTER)
+endif()
 add_store_test(task_manager_test task_manager_test.cpp)
 add_store_test(task_executor_test task_executor_test.cpp)
 add_store_test(task_integration_test task_integration_test.cpp)
 add_store_test(dummy_client_get_buffer_test dummy_client_get_buffer_test.cpp)
+add_store_test(dummy_client_probe_key_test dummy_client_probe_key_test.cpp)
 add_test(
   NAME dummy_client_object_checksum_test
   COMMAND
@@ -167,8 +337,13 @@ set_tests_properties(dummy_client_object_checksum_test
                      PROPERTIES ENVIRONMENT "MOONCAKE_STORE_CHECKSUM=1")
 add_store_test(uds_transport_test uds_transport_test.cpp)
 add_store_test(health_check_test health_check_test.cpp)
+if(MOONCAKE_OSS_ADAPTER_ENABLED)
+  add_store_test(oss_adapter_config_test oss_adapter_config_test.cpp)
+  add_store_test(oss_adapter_test oss_adapter_test.cpp)
+endif()
 add_store_test(http_metadata_server_test http_metadata_server_test.cpp)
 add_store_test(mmap_arena_test mmap_arena_test.cpp)
+add_store_test(mmap_arena_config_test mmap_arena_config_test.cpp)
 add_store_test(mmap_arena_fallback_test mmap_arena_fallback_test.cpp)
 add_store_test(object_data_type_test object_data_type_test.cpp)
 add_subdirectory(e2e)
@@ -180,29 +355,25 @@ if(STORE_USE_REDIS)
   target_sources(
     high_availability_test
     PRIVATE ha/leadership/backends/redis/high_availability_redis_test.cpp)
-  target_include_directories(high_availability_test
-                             PRIVATE ${MOONCAKE_STORE_HIREDIS_INCLUDE_DIR})
-  target_link_libraries(high_availability_test
-                        PRIVATE ${MOONCAKE_STORE_HIREDIS_LIBRARY})
+  target_link_libraries(high_availability_test PRIVATE Mooncake::hiredis)
 
   add_executable(
     redis_snapshot_catalog_store_test
     ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store_test.cpp)
-  target_include_directories(
-    redis_snapshot_catalog_store_test
-    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} ${MOONCAKE_STORE_HIREDIS_INCLUDE_DIR})
+  target_include_directories(redis_snapshot_catalog_store_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
   target_link_libraries(
     redis_snapshot_catalog_store_test
     PUBLIC mooncake_store
            transfer_engine
            cachelib_memory_allocator
            ${ETCD_WRAPPER_LIB}
-           glog
-           gflags
+           glog::glog
+           gflags::gflags
            ibverbs
            gtest
            pthread
-    PRIVATE ${MOONCAKE_STORE_HIREDIS_LIBRARY})
+    PRIVATE Mooncake::hiredis)
   add_test(NAME redis_snapshot_catalog_store_test
            COMMAND redis_snapshot_catalog_store_test)
 endif()
@@ -217,7 +388,7 @@ target_link_libraries(
          transfer_engine
          cachelib_memory_allocator
          ${ETCD_WRAPPER_LIB}
-         glog
+         glog::glog
          gtest
          gtest_main
          pthread)
@@ -248,8 +419,8 @@ target_link_libraries(
          cachelib_memory_allocator
          ${ETCD_WRAPPER_LIB}
          mooncake_common
-         glog
-         gflags
+         glog::glog
+         gflags::gflags
          pthread)
 
 # HA tests
@@ -257,6 +428,8 @@ add_ha_test(standby_state_machine_test
             ha/standby/standby_state_machine_test.cpp)
 add_ha_test(ha_metric_manager_test ha/standby/ha_metric_manager_test.cpp)
 add_ha_test(hot_standby_service_test ha/standby/hot_standby_service_test.cpp)
+add_ha_test(standby_metadata_store_test
+            ha/standby/standby_metadata_store_test.cpp)
 add_ha_test(hot_standby_snapshot_bootstrap_test
             ha/standby/hot_standby_snapshot_bootstrap_test.cpp)
 add_ha_test(oplog_applier_test ha/oplog/oplog_applier_test.cpp)
@@ -274,10 +447,12 @@ endif()
 add_executable(
   oplog_test_failpoint_test ha/oplog/oplog_test_failpoint_test.cpp
                             ../src/ha/oplog/oplog_test_failpoint.cpp)
+target_include_directories(oplog_test_failpoint_test
+                           PRIVATE ${MOONCAKE_STORE_INCLUDE_ROOT})
 target_compile_definitions(oplog_test_failpoint_test
                            PRIVATE MOONCAKE_ENABLE_TEST_FAILPOINTS)
-target_link_libraries(oplog_test_failpoint_test PRIVATE glog gtest gtest_main
-                                                        pthread)
+target_link_libraries(oplog_test_failpoint_test PRIVATE glog::glog gtest
+                                                        gtest_main pthread)
 add_test(NAME oplog_test_failpoint_test COMMAND oplog_test_failpoint_test)
 add_ha_test(master_service_ha_test ha/master_service_ha_test.cpp)
 add_ha_test(catalog_backed_snapshot_provider_test
@@ -285,8 +460,16 @@ add_ha_test(catalog_backed_snapshot_provider_test
 if(STORE_USE_REDIS)
   foreach(target catalog_backed_snapshot_provider_test
                  hot_standby_snapshot_bootstrap_test)
-    target_include_directories(${target}
-                               PRIVATE ${MOONCAKE_STORE_HIREDIS_INCLUDE_DIR})
-    target_link_libraries(${target} PRIVATE ${MOONCAKE_STORE_HIREDIS_LIBRARY})
+    target_link_libraries(${target} PRIVATE Mooncake::hiredis)
   endforeach()
 endif()
+
+foreach(
+  target
+  hot_standby_service_test oplog_applier_test oplog_batch_codec_test
+  oplog_batch_standby_reader_test oplog_batch_storage_test
+  ordered_oplog_writer_test)
+  target_link_libraries(${target} PRIVATE Mooncake::xxhash)
+endforeach()
+
+add_store_test(master_heartbeat_metric_test master_heartbeat_metric_test.cpp)
diff --git a/mooncake-store/tests/allocation_strategy_test.cpp b/mooncake-store/tests/allocation_strategy_test.cpp
index 7129244498..5a94469f6d 100644
--- a/mooncake-store/tests/allocation_strategy_test.cpp
+++ b/mooncake-store/tests/allocation_strategy_test.cpp
@@ -16,6 +16,8 @@
 #include <vector>
 
 #include "allocator.h"
+#include "local_ssd/manager.h"
+#include "segment.h"
 #include "types.h"
 
 namespace mooncake {
@@ -47,7 +49,7 @@ class AllocationStrategyParameterizedTest
    protected:
     void SetUp() override {
         auto [strategy_type, allocator_type] = GetParam();
-        strategy_ = CreateAllocationStrategy(strategy_type);
+        strategy_ = CreateAllocationStrategy(strategy_type, local_ssd_);
         allocator_type_ = allocator_type;
     }
 
@@ -57,19 +59,16 @@ class AllocationStrategyParameterizedTest
         const std::string& segment_name, size_t base_offset,
         size_t size = 64 * MiB) {
         const size_t base = 0x100000000ULL + base_offset;  // 4GB + offset
-        switch (allocator_type_) {
-            case BufferAllocatorType::CACHELIB:
-                return std::make_shared<CachelibBufferAllocator>(
-                    segment_name, base, size, segment_name);
-            case BufferAllocatorType::OFFSET:
-                return std::make_shared<OffsetBufferAllocator>(
-                    segment_name, base, size, segment_name);
-            default:
-                throw std::invalid_argument("Invalid allocator type");
+        auto allocator = CreateBufferAllocator(allocator_type_, segment_name,
+                                               base, size, segment_name);
+        if (!allocator) {
+            throw std::invalid_argument("Invalid allocator test parameters");
         }
+        return std::move(*allocator);
     }
 
     BufferAllocatorType allocator_type_;
+    LocalSsdManager local_ssd_;
     std::shared_ptr<AllocationStrategy> strategy_;
 };
 
@@ -124,6 +123,46 @@ TEST_F(AllocationStrategyTest, PreferredSegmentWithEmptyAllocators) {
     EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
 }
 
+TEST_F(AllocationStrategyTest, SuspectedRegistrationIsSkipped) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    auto suspected = std::make_shared<ClientLivenessRecord>(initial);
+    ASSERT_EQ(
+        suspected->Evaluate(initial + std::chrono::seconds(1),
+                            std::chrono::seconds(1), std::chrono::seconds(10)),
+        ClientLivenessTransition::BECAME_SUSPECTED);
+    auto active = std::make_shared<ClientLivenessRecord>(initial);
+
+    auto suspected_allocator = std::make_shared<OffsetBufferAllocator>(
+        "shared", DEFAULT_CXL_BASE, 64 * MiB, "suspected");
+    auto active_allocator = std::make_shared<OffsetBufferAllocator>(
+        "shared", DEFAULT_CXL_BASE + 64 * MiB, 64 * MiB, "active");
+    AllocatorManager allocator_manager;
+    allocator_manager.addAllocator("shared", suspected_allocator, suspected);
+    allocator_manager.addAllocator("shared", active_allocator, active);
+
+    // No SSD usage is registered: the SSD strategy still picks the serving
+    // registration.
+    LocalSsdManager local_ssd;
+    for (const auto strategy_type :
+         {AllocationStrategyType::RANDOM,
+          AllocationStrategyType::FREE_RATIO_FIRST,
+          AllocationStrategyType::SSD_FREE_RATIO_FIRST,
+          AllocationStrategyType::CXL}) {
+        auto strategy = CreateAllocationStrategy(strategy_type, local_ssd);
+        auto result =
+            strategy->Allocate(allocator_manager, 1024, 1, {"shared"}, {});
+        ASSERT_TRUE(result.has_value());
+        ASSERT_EQ(result->size(), 1);
+        const auto expected_endpoint =
+            strategy_type == AllocationStrategyType::CXL ? "shared" : "active";
+        EXPECT_EQ((*result)[0]
+                      .get_descriptor()
+                      .get_memory_descriptor()
+                      .buffer_descriptor.transport_endpoint_,
+                  expected_endpoint);
+    }
+}
+
 // Test preferred segment allocation when available
 TEST_P(AllocationStrategyParameterizedTest, PreferredSegmentAllocation) {
     auto allocator1 = CreateTestAllocator("segment1", 0);
@@ -755,51 +794,57 @@ TEST_F(AllocationStrategyTest, PerformanceTest) {
 // public API. The functionality is now encapsulated within the Allocate()
 // method.
 
-// Mock SsdMetricsProvider for testing SSD-aware allocation
-class MockSsdMetricsProvider : public SsdMetricsProvider {
+class SsdPlacementTestState {
    public:
-    std::unordered_map<std::string, int64_t> total_capacity;
-    std::unordered_map<std::string, int64_t> used_bytes;
+    void AddSegment(const std::string& name, size_t index, size_t segment_size,
+                    int64_t total_capacity, int64_t used_bytes) {
+        allocators.addAllocator(
+            name, std::make_shared<OffsetBufferAllocator>(
+                      name, 0x100000000ULL + index * segment_size, segment_size,
+                      name));
+        const UUID client_id{index + 1, index + 100};
+        client_by_name.emplace(name, client_id);
+        ASSERT_EQ(local_ssd.RegisterClient(client_id, true), ErrorCode::OK);
+        ASSERT_TRUE(
+            local_ssd.ReportCapacity(client_id, total_capacity).has_value());
+        ASSERT_TRUE(local_ssd.AdjustUsedBytes(client_id, used_bytes));
+    }
 
-    int64_t getSsdTotalCapacity(const std::string& name) const override {
-        auto it = total_capacity.find(name);
-        return it != total_capacity.end() ? it->second : 0;
+    void AddSegmentWithoutSsd(const std::string& name, size_t segment_size) {
+        allocators.addAllocator(
+            name, std::make_shared<OffsetBufferAllocator>(name, 0x100000000ULL,
+                                                          segment_size, name));
+        client_by_name.emplace(name, UUID{1, 100});
     }
 
-    int64_t getSsdUsedBytes(const std::string& name) const override {
-        auto it = used_bytes.find(name);
-        return it != used_bytes.end() ? it->second : 0;
+    ScopedAllocatorAccess GetPlacement() {
+        return ScopedAllocatorAccess(allocators, segments_by_host,
+                                     client_by_name, mutex);
     }
+
+    AllocatorManager allocators;
+    LocalSsdManager local_ssd;
+
+   private:
+    HostSegmentIndex segments_by_host;
+    std::unordered_map<std::string, UUID> client_by_name;
+    std::shared_mutex mutex;
 };
 
 TEST_F(AllocationStrategyTest, SsdFreeRatioFirstChoosesHighestFreeRatio) {
-    auto ssd_strategy = std::make_unique<SsdFreeRatioFirstAllocationStrategy>();
-
     const int kNumSegments = 3;
     const size_t kSegmentSize = 64 * MiB;
 
-    AllocatorManager allocator_manager;
-    for (int i = 0; i < kNumSegments; i++) {
-        const auto name = std::to_string(i) + "-segment";
-        allocator_manager.addAllocator(
-            name,
-            std::make_shared<OffsetBufferAllocator>(
-                name, 0x100000000ULL + i * kSegmentSize, kSegmentSize, name));
-    }
-
-    // SSD free ratios: segment 0 = 20%, segment 1 = 60%, segment 2 = 90%
-    MockSsdMetricsProvider ssd_provider;
+    SsdPlacementTestState state;
     for (int i = 0; i < kNumSegments; i++) {
         const auto name = std::to_string(i) + "-segment";
-        ssd_provider.total_capacity[name] = 1000 * MiB;
+        const int64_t used[] = {800 * MiB, 400 * MiB, 100 * MiB};
+        state.AddSegment(name, i, kSegmentSize, 1000 * MiB, used[i]);
     }
-    ssd_provider.used_bytes["0-segment"] = 800 * MiB;  // 20% free
-    ssd_provider.used_bytes["1-segment"] = 400 * MiB;  // 60% free
-    ssd_provider.used_bytes["2-segment"] = 100 * MiB;  // 90% free
 
-    auto result =
-        ssd_strategy->Allocate(allocator_manager, 64 * 1024, 1, {}, {},
-                               ReplicaType::MEMORY, &ssd_provider);
+    SsdFreeRatioFirstAllocationStrategy ssd_strategy(state.local_ssd);
+    auto placement = state.GetPlacement();
+    auto result = ssd_strategy.Allocate(placement, 64 * 1024);
     ASSERT_TRUE(result.has_value());
     ASSERT_EQ(result.value().size(), 1u);
 
@@ -810,18 +855,36 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstChoosesHighestFreeRatio) {
     EXPECT_EQ(mem_desc.buffer_descriptor.transport_endpoint_, "2-segment");
 }
 
-// Test that SsdFreeRatioFirstAllocationStrategy works without an
-// SsdMetricsProvider (delegates to base class random allocation).
-TEST_F(AllocationStrategyTest,
-       SsdFreeRatioFirstWithoutMetricsProviderAllocates) {
-    auto ssd_strategy = std::make_unique<SsdFreeRatioFirstAllocationStrategy>();
+TEST_F(AllocationStrategyTest, SsdFreeRatioFirstSnapshotPreservesOwnerRanking) {
+    const size_t kSegmentSize = 64 * MiB;
+    SsdPlacementTestState state;
+    state.AddSegment("busy", 0, kSegmentSize, 1000 * MiB, 900 * MiB);
+    state.AddSegment("free", 1, kSegmentSize, 1000 * MiB, 100 * MiB);
 
-    auto allocator = std::make_shared<OffsetBufferAllocator>(
-        "segment1", 0x100000000ULL, 64 * MiB, "segment1");
-    AllocatorManager allocator_manager;
-    allocator_manager.addAllocator("segment1", allocator);
+    AllocatorManager snapshot;
+    {
+        auto placement = state.GetPlacement();
+        snapshot = placement.SnapshotAllocatorManager();
+    }
+
+    SsdFreeRatioFirstAllocationStrategy strategy(state.local_ssd);
+    auto result = strategy.Allocate(snapshot, 64 * 1024);
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->size(), 1u);
+    EXPECT_EQ(result->front()
+                  .get_descriptor()
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_,
+              "free");
+}
+
+TEST_F(AllocationStrategyTest, SsdFreeRatioFirstWithoutUsageAllocates) {
+    SsdPlacementTestState state;
+    state.AddSegmentWithoutSsd("segment1", 64 * MiB);
+    SsdFreeRatioFirstAllocationStrategy ssd_strategy(state.local_ssd);
+    auto placement = state.GetPlacement();
 
-    auto result = ssd_strategy->Allocate(allocator_manager, 1024, 1, {}, {});
+    auto result = ssd_strategy.Allocate(placement, 1024);
     ASSERT_TRUE(result.has_value());
     EXPECT_EQ(result.value().size(), 1u);
 }
@@ -829,36 +892,22 @@ TEST_F(AllocationStrategyTest,
 // Test that SsdFreeRatioFirstAllocationStrategy skips excluded segments even
 // when they have the highest SSD free ratio.
 TEST_F(AllocationStrategyTest, SsdFreeRatioFirstExcludedSegmentsSkipped) {
-    auto ssd_strategy = std::make_unique<SsdFreeRatioFirstAllocationStrategy>();
-
     const int kNumSegments = 3;
     const size_t kSegmentSize = 64 * MiB;
 
-    AllocatorManager allocator_manager;
+    SsdPlacementTestState state;
+    const int64_t used[] = {50 * MiB, 500 * MiB, 700 * MiB};
     for (int i = 0; i < kNumSegments; i++) {
         const auto name = std::to_string(i) + "-segment";
-        allocator_manager.addAllocator(
-            name,
-            std::make_shared<OffsetBufferAllocator>(
-                name, 0x100000000ULL + i * kSegmentSize, kSegmentSize, name));
+        state.AddSegment(name, i, kSegmentSize, 1000 * MiB, used[i]);
     }
 
-    // SSD free ratios: 0-segment=95%, 1-segment=50%, 2-segment=30%
-    MockSsdMetricsProvider ssd_provider;
-    for (int i = 0; i < kNumSegments; i++) {
-        const auto name = std::to_string(i) + "-segment";
-        ssd_provider.total_capacity[name] = 1000 * MiB;
-    }
-    ssd_provider.used_bytes["0-segment"] = 50 * MiB;   // 95% free (highest)
-    ssd_provider.used_bytes["1-segment"] = 500 * MiB;  // 50% free
-    ssd_provider.used_bytes["2-segment"] = 700 * MiB;  // 30% free
-
     // Exclude 0-segment which has the highest SSD free ratio
     std::set<std::string> excluded = {"0-segment"};
 
-    auto result =
-        ssd_strategy->Allocate(allocator_manager, 64 * 1024, 1, {}, excluded,
-                               ReplicaType::MEMORY, &ssd_provider);
+    SsdFreeRatioFirstAllocationStrategy ssd_strategy(state.local_ssd);
+    auto placement = state.GetPlacement();
+    auto result = ssd_strategy.Allocate(placement, 64 * 1024, 1, {}, excluded);
     ASSERT_TRUE(result.has_value());
     ASSERT_EQ(result.value().size(), 1u);
 
@@ -873,31 +922,15 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstExcludedSegmentsSkipped) {
 // Test that ssd_used_bytes > ssd_total_capacity is clamped to 0% free,
 // so the other segment (with normal usage) is preferred.
 TEST_F(AllocationStrategyTest, SsdFreeRatioFirstUsedExceedsTotalIsClamped) {
-    auto ssd_strategy = std::make_unique<SsdFreeRatioFirstAllocationStrategy>();
-
     const size_t kSegmentSize = 64 * MiB;
 
-    AllocatorManager allocator_manager;
-    allocator_manager.addAllocator(
-        "0-segment",
-        std::make_shared<OffsetBufferAllocator>("0-segment", 0x100000000ULL,
-                                                kSegmentSize, "0-segment"));
-    allocator_manager.addAllocator(
-        "1-segment", std::make_shared<OffsetBufferAllocator>(
-                         "1-segment", 0x100000000ULL + kSegmentSize,
-                         kSegmentSize, "1-segment"));
-
-    // 0-segment: used exceeds total (concurrent drift) → clamped to 0% free
-    // 1-segment: used=100, total=1000 → 90% free
-    MockSsdMetricsProvider ssd_provider;
-    ssd_provider.total_capacity["0-segment"] = 1000 * MiB;
-    ssd_provider.total_capacity["1-segment"] = 1000 * MiB;
-    ssd_provider.used_bytes["0-segment"] = 1500 * MiB;  // exceeds total
-    ssd_provider.used_bytes["1-segment"] = 100 * MiB;   // 90% free
+    SsdPlacementTestState state;
+    state.AddSegment("0-segment", 0, kSegmentSize, 1000 * MiB, 1500 * MiB);
+    state.AddSegment("1-segment", 1, kSegmentSize, 1000 * MiB, 100 * MiB);
 
-    auto result =
-        ssd_strategy->Allocate(allocator_manager, 64 * 1024, 1, {}, {},
-                               ReplicaType::MEMORY, &ssd_provider);
+    SsdFreeRatioFirstAllocationStrategy ssd_strategy(state.local_ssd);
+    auto placement = state.GetPlacement();
+    auto result = ssd_strategy.Allocate(placement, 64 * 1024);
     ASSERT_TRUE(result.has_value());
     ASSERT_EQ(result.value().size(), 1u);
 
@@ -910,9 +943,6 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstUsedExceedsTotalIsClamped) {
 }
 
 // Strategy-level performance comparison: Random vs SsdFreeRatioFirst.
-// Uses OffsetBufferAllocator (real physical memory via aligned_alloc) and
-// MockSsdMetricsProvider. Measures pure strategy overhead without MasterService
-// locking, reflecting only the allocation algorithm cost.
 TEST_F(AllocationStrategyTest, SsdFreeRatioFirstVsRandomStrategyPerformance) {
     constexpr size_t kNumSegments = 64;
     constexpr size_t kSegmentSize = 8 * MiB;   // 64 * 8MB = 512MB physical
@@ -920,32 +950,21 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstVsRandomStrategyPerformance) {
     constexpr int kWarmupRounds = 200;
     constexpr int kBenchmarkRounds = 2000;
 
-    // Build AllocatorManager: 64 segments, each 8 MiB
-    AllocatorManager allocator_manager;
-    for (size_t i = 0; i < kNumSegments; i++) {
-        const auto name = "perf_seg_" + std::to_string(i);
-        allocator_manager.addAllocator(
-            name,
-            std::make_shared<OffsetBufferAllocator>(
-                name, 0x200000000ULL + i * kSegmentSize, kSegmentSize, name));
-    }
-
-    // SSD free ratios vary uniformly from ~10% to ~90% across segments
-    MockSsdMetricsProvider ssd_provider;
+    SsdPlacementTestState state;
     for (size_t i = 0; i < kNumSegments; i++) {
         const auto name = "perf_seg_" + std::to_string(i);
-        ssd_provider.total_capacity[name] = 1000 * MiB;
-        // used: 100 MiB (10% used) to 900 MiB (90% used)
-        ssd_provider.used_bytes[name] =
+        const auto used =
             static_cast<int64_t>((100 + i * 800 / kNumSegments)) * MiB;
+        state.AddSegment(name, i, kSegmentSize, 1000 * MiB, used);
     }
+    auto placement = state.GetPlacement();
 
     // -------- Random strategy --------
     auto random_strategy = std::make_unique<RandomAllocationStrategy>();
     {
         // Warmup (results discarded)
         for (int i = 0; i < kWarmupRounds; i++) {
-            (void)random_strategy->Allocate(allocator_manager, kAllocSize);
+            (void)random_strategy->Allocate(state.allocators, kAllocSize);
         }
     }
     std::vector<std::vector<Replica>> random_replicas;
@@ -953,7 +972,7 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstVsRandomStrategyPerformance) {
 
     auto t_rand_start = std::chrono::steady_clock::now();
     for (int i = 0; i < kBenchmarkRounds; i++) {
-        auto r = random_strategy->Allocate(allocator_manager, kAllocSize);
+        auto r = random_strategy->Allocate(state.allocators, kAllocSize);
         ASSERT_TRUE(r.has_value());
         random_replicas.emplace_back(std::move(r.value()));
     }
@@ -962,13 +981,11 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstVsRandomStrategyPerformance) {
     random_replicas.clear();  // deallocate so SSD strategy starts fresh
 
     // -------- SsdFreeRatioFirst strategy --------
-    auto ssd_strategy = std::make_unique<SsdFreeRatioFirstAllocationStrategy>();
+    SsdFreeRatioFirstAllocationStrategy ssd_strategy(state.local_ssd);
     {
         // Warmup
         for (int i = 0; i < kWarmupRounds; i++) {
-            (void)ssd_strategy->Allocate(allocator_manager, kAllocSize, 1, {},
-                                         {}, ReplicaType::MEMORY,
-                                         &ssd_provider);
+            (void)ssd_strategy.Allocate(placement, kAllocSize);
         }
     }
     std::vector<std::vector<Replica>> ssd_replicas;
@@ -976,8 +993,7 @@ TEST_F(AllocationStrategyTest, SsdFreeRatioFirstVsRandomStrategyPerformance) {
 
     auto t_ssd_start = std::chrono::steady_clock::now();
     for (int i = 0; i < kBenchmarkRounds; i++) {
-        auto r = ssd_strategy->Allocate(allocator_manager, kAllocSize, 1, {},
-                                        {}, ReplicaType::MEMORY, &ssd_provider);
+        auto r = ssd_strategy.Allocate(placement, kAllocSize);
         ASSERT_TRUE(r.has_value());
         ssd_replicas.emplace_back(std::move(r.value()));
     }
diff --git a/mooncake-store/tests/allocator_metric_test.cpp b/mooncake-store/tests/allocator_metric_test.cpp
new file mode 100644
index 0000000000..762fea0be8
--- /dev/null
+++ b/mooncake-store/tests/allocator_metric_test.cpp
@@ -0,0 +1,246 @@
+#include "allocator_metric.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <string>
+
+namespace mooncake::test {
+
+namespace {
+
+JemallocSnapshot g_snapshot;
+bool g_collector_succeeds = true;
+int g_collector_calls = 0;
+
+bool FakeCollector(JemallocSnapshot& snapshot) {
+    ++g_collector_calls;
+    if (!g_collector_succeeds) {
+        return false;
+    }
+    snapshot = g_snapshot;
+    return true;
+}
+
+// A ylt series is emitted as "<name>[{labels}] <value>", so an exact-value
+// assertion has to anchor on the leading newline to avoid matching a longer
+// metric name that ends with the one under test.
+bool HasSeries(const std::string& text, const std::string& name,
+               const std::string& value) {
+    return text.find("\n" + name + " " + value + "\n") != std::string::npos;
+}
+
+bool HasBinSeries(const std::string& text, const std::string& name,
+                  const std::string& size_class, const std::string& value) {
+    return text.find("\n" + name + "{size=\"" + size_class + "\"} " + value +
+                     "\n") != std::string::npos;
+}
+
+}  // namespace
+
+class AllocatorMetricTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        g_snapshot = JemallocSnapshot{};
+        g_collector_succeeds = true;
+        g_collector_calls = 0;
+        SetJemallocStatsCollector(nullptr);
+    }
+
+    void TearDown() override { SetJemallocStatsCollector(nullptr); }
+
+    // Bypasses the refresh throttle so that a test can sample repeatedly.
+    static void ForceRefresh(AllocatorMetric& metric) {
+        metric.RefreshLocked();
+    }
+};
+
+TEST_F(AllocatorMetricTest, ProcessSeriesReportedWithoutCollector) {
+    AllocatorMetric metric;
+    metric.Refresh();
+
+    std::string text;
+    metric.serialize(text);
+
+    EXPECT_NE(text.find("mooncake_process_rss_bytes"), std::string::npos);
+    EXPECT_NE(text.find("mooncake_process_rss_peak_bytes"), std::string::npos);
+    EXPECT_NE(text.find("mooncake_process_vsize_bytes"), std::string::npos);
+    // The process is alive, so its resident size cannot be zero.
+    EXPECT_FALSE(HasSeries(text, "mooncake_process_rss_bytes", "0"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_enabled", "0"));
+}
+
+TEST_F(AllocatorMetricTest, ZeroValuedSeriesAreStillEmitted) {
+    AllocatorMetric metric;
+
+    std::string text;
+    metric.serialize(text);
+
+    // ylt omits a metric that is still at its untouched zero, so every series
+    // has to be marked in the constructor or it disappears from a fresh
+    // process until the first non-zero sample.
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_allocated_bytes", "0"));
+    EXPECT_TRUE(
+        HasSeries(text, "mooncake_jemalloc_dirty_purge_runs_total", "0"));
+}
+
+TEST_F(AllocatorMetricTest, JemallocSeriesReportedWhenCollectorInstalled) {
+    g_snapshot.allocated = 1000;
+    g_snapshot.active = 2000;
+    g_snapshot.resident = 3000;
+    g_snapshot.retained = 4000;
+    g_snapshot.dirty_bytes = 5000;
+    g_snapshot.arenas = 7;
+    g_snapshot.opt_dirty_decay_ms = 10000;
+    g_snapshot.opt_muzzy_decay_ms = -1;
+    SetJemallocStatsCollector(&FakeCollector);
+
+    AllocatorMetric metric;
+    metric.Refresh();
+
+    std::string text;
+    metric.serialize(text);
+
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_enabled", "1"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_allocated_bytes", "1000"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_active_bytes", "2000"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_resident_bytes", "3000"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_retained_bytes", "4000"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_dirty_bytes", "5000"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_arenas", "7"));
+    // A negative decay means the arena never purges, so the sign has to
+    // survive into the gauge rather than be clamped.
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_opt_muzzy_decay_ms", "-1"));
+}
+
+TEST_F(AllocatorMetricTest, CollectorFailureLeavesJemallocDisabled) {
+    g_snapshot.allocated = 1000;
+    g_collector_succeeds = false;
+    SetJemallocStatsCollector(&FakeCollector);
+
+    AllocatorMetric metric;
+    metric.Refresh();
+
+    std::string text;
+    metric.serialize(text);
+
+    EXPECT_EQ(g_collector_calls, 1);
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_enabled", "0"));
+    EXPECT_TRUE(HasSeries(text, "mooncake_jemalloc_allocated_bytes", "0"));
+}
+
+TEST_F(AllocatorMetricTest, CumulativeTotalsAdvanceByDelta) {
+    SetJemallocStatsCollector(&FakeCollector);
+    AllocatorMetric metric;
+
+    g_snapshot.dirty_purge_runs = 10;
+    g_snapshot.small_allocations = 100;
+    ForceRefresh(metric);
+
+    g_snapshot.dirty_purge_runs = 25;
+    g_snapshot.small_allocations = 260;
+    ForceRefresh(metric);
+
+    std::string text;
+    metric.serialize(text);
+
+    // The counter must track jemalloc's cumulative total, not the sum of the
+    // samples: adding the absolute value each time would report 35 here.
+    EXPECT_TRUE(
+        HasSeries(text, "mooncake_jemalloc_dirty_purge_runs_total", "25"));
+    EXPECT_TRUE(
+        HasSeries(text, "mooncake_jemalloc_small_allocations_total", "260"));
+}
+
+TEST_F(AllocatorMetricTest, CounterIgnoresTotalGoingBackwards) {
+    SetJemallocStatsCollector(&FakeCollector);
+    AllocatorMetric metric;
+
+    g_snapshot.dirty_purge_runs = 25;
+    ForceRefresh(metric);
+    g_snapshot.dirty_purge_runs = 5;
+    ForceRefresh(metric);
+
+    std::string text;
+    metric.serialize(text);
+
+    // A counter can only move forward, so a total that regressed must hold the
+    // series rather than push it below its previous value.
+    EXPECT_TRUE(
+        HasSeries(text, "mooncake_jemalloc_dirty_purge_runs_total", "25"));
+}
+
+TEST_F(AllocatorMetricTest, RefreshIsThrottled) {
+    SetJemallocStatsCollector(&FakeCollector);
+    AllocatorMetric metric;
+
+    metric.Refresh();
+    metric.Refresh();
+    metric.Refresh();
+
+    EXPECT_EQ(g_collector_calls, 1);
+}
+
+TEST_F(AllocatorMetricTest, BinSeriesReportedPerSizeClass) {
+    g_snapshot.bins = {{160, 128, 266843, 3125}, {112, 256, 266779, 1563}};
+    SetJemallocStatsCollector(&FakeCollector);
+
+    AllocatorMetric metric;
+    metric.Refresh();
+
+    std::string text;
+    metric.serialize(text);
+
+    EXPECT_TRUE(
+        HasBinSeries(text, "mooncake_jemalloc_bin_regs", "160", "266843"));
+    EXPECT_TRUE(
+        HasBinSeries(text, "mooncake_jemalloc_bin_slabs", "160", "3125"));
+    // Live bytes are the region count times the size class.
+    EXPECT_TRUE(HasBinSeries(text, "mooncake_jemalloc_bin_used_bytes", "160",
+                             std::to_string(266843LL * 160)));
+    // Slab bytes are what the class holds from the OS: every slab is charged
+    // in full, which is the whole point of watching this series.
+    EXPECT_TRUE(HasBinSeries(text, "mooncake_jemalloc_bin_slab_bytes", "160",
+                             std::to_string(3125LL * 128 * 160)));
+    EXPECT_TRUE(HasBinSeries(text, "mooncake_jemalloc_bin_used_bytes", "112",
+                             std::to_string(266779LL * 112)));
+}
+
+TEST_F(AllocatorMetricTest, EmptyBinKeepsItsSeries) {
+    g_snapshot.bins = {{160, 128, 0, 0}};
+    SetJemallocStatsCollector(&FakeCollector);
+
+    AllocatorMetric metric;
+    metric.Refresh();
+
+    std::string text;
+    metric.serialize(text);
+
+    // A size class that drains must report zero rather than vanish, or the
+    // series goes stale and Grafana keeps drawing its last value.
+    EXPECT_TRUE(HasBinSeries(text, "mooncake_jemalloc_bin_slabs", "160", "0"));
+    EXPECT_TRUE(
+        HasBinSeries(text, "mooncake_jemalloc_bin_slab_bytes", "160", "0"));
+}
+
+TEST_F(AllocatorMetricTest, ResampledBinsReplaceRatherThanAccumulate) {
+    g_snapshot.bins = {{160, 128, 10, 1}};
+    SetJemallocStatsCollector(&FakeCollector);
+    AllocatorMetric metric;
+
+    ForceRefresh(metric);
+    g_snapshot.bins = {{160, 128, 20, 2}};
+    ForceRefresh(metric);
+
+    std::string text;
+    metric.serialize(text);
+
+    // One series per size class, holding the newest sample. A collector that
+    // appended to the caller's vector would grow it without bound and leave
+    // the first sample in place here.
+    EXPECT_TRUE(HasBinSeries(text, "mooncake_jemalloc_bin_regs", "160", "20"));
+    EXPECT_EQ(text.find("mooncake_jemalloc_bin_regs{size=\"160\"}"),
+              text.rfind("mooncake_jemalloc_bin_regs{size=\"160\"}"));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/background_worker_test.cpp b/mooncake-store/tests/background_worker_test.cpp
new file mode 100644
index 0000000000..e895537a77
--- /dev/null
+++ b/mooncake-store/tests/background_worker_test.cpp
@@ -0,0 +1,68 @@
+#include "background_worker.h"
+
+#include <chrono>
+#include <condition_variable>
+#include <mutex>
+
+#include <gtest/gtest.h>
+
+namespace mooncake::test {
+
+TEST(BackgroundWorkerTest, CoalescesPendingSchedules) {
+    std::mutex mutex;
+    std::condition_variable cv;
+    size_t callback_count = 0;
+    bool release_first_callback = false;
+
+    BackgroundWorker worker([&] {
+        std::unique_lock<std::mutex> lock(mutex);
+        ++callback_count;
+        cv.notify_all();
+        if (callback_count == 1) {
+            cv.wait(lock, [&] { return release_first_callback; });
+        }
+    });
+    worker.Start();
+    worker.Schedule();
+
+    {
+        std::unique_lock<std::mutex> lock(mutex);
+        ASSERT_TRUE(cv.wait_for(lock, std::chrono::seconds(1),
+                                [&] { return callback_count == 1; }));
+    }
+    for (size_t i = 0; i < 10; ++i) {
+        worker.Schedule();
+    }
+    {
+        std::lock_guard<std::mutex> lock(mutex);
+        release_first_callback = true;
+    }
+    cv.notify_all();
+
+    {
+        std::unique_lock<std::mutex> lock(mutex);
+        ASSERT_TRUE(cv.wait_for(lock, std::chrono::seconds(1),
+                                [&] { return callback_count == 2; }));
+    }
+    worker.Stop();
+    EXPECT_EQ(callback_count, 2);
+}
+
+TEST(BackgroundWorkerTest, ScheduleIsIgnoredWhileStopped) {
+    std::mutex mutex;
+    size_t callback_count = 0;
+    BackgroundWorker worker([&] {
+        std::lock_guard<std::mutex> lock(mutex);
+        ++callback_count;
+    });
+
+    worker.Schedule();
+    worker.Start();
+    worker.Stop();
+    worker.Schedule();
+
+    std::lock_guard<std::mutex> lock(mutex);
+    EXPECT_EQ(callback_count, 0);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/batch_evict_test.cpp b/mooncake-store/tests/batch_evict_test.cpp
deleted file mode 100644
index 9086b63fc1..0000000000
--- a/mooncake-store/tests/batch_evict_test.cpp
+++ /dev/null
@@ -1,467 +0,0 @@
-#include <glog/logging.h>
-#include <gtest/gtest.h>
-
-#include <algorithm>
-#include <chrono>
-#include <optional>
-#include <string>
-#include <vector>
-
-#include "master_service.h"
-#include "mutex.h"
-#include "types.h"
-#include "utils.h"
-
-namespace mooncake::test {
-
-// Deterministic correctness tests for MasterService::BatchEvict.
-//
-// These tests drive BatchEvict directly instead of filling a segment and
-// waiting for the background eviction thread. Lease timestamps are written
-// explicitly so that the eviction order, the exact eviction count, the
-// soft-pin fallback and the whole-group semantics are all observable without
-// sleeps, background threads or timing assumptions.
-class BatchEvictTest : public ::testing::Test {
-   protected:
-    static constexpr const char* kSegmentName = "batch_evict_test_segment";
-    static constexpr size_t kSegmentBase = 0x500000000;
-    static constexpr size_t kSegmentSize = 256ULL * 1024 * 1024;
-    static constexpr uint64_t kObjectSize = 1024;
-
-    void SetUp() override {
-        google::InitGoogleLogging("BatchEvictTest");
-        FLAGS_logtostderr = true;
-    }
-
-    void TearDown() override { google::ShutdownGoogleLogging(); }
-
-    // Eviction ratio 0 and a 100% high watermark keep the background eviction
-    // thread from interfering: every eviction in these tests is the one the
-    // test itself requests.
-    static MasterServiceConfig MakeConfig(bool allow_soft_pin_eviction) {
-        return MasterServiceConfig::builder()
-            .set_memory_allocator(BufferAllocatorType::OFFSET)
-            .set_default_kv_lease_ttl(0)
-            .set_default_kv_soft_pin_ttl(60 * 60 * 1000)
-            .set_allow_evict_soft_pinned_objects(allow_soft_pin_eviction)
-            .set_eviction_ratio(0.0)
-            .set_eviction_high_watermark_ratio(1.0)
-            .set_client_live_ttl_sec(3600)
-            .build();
-    }
-
-    static Segment MakeSegment() {
-        Segment segment;
-        segment.id = generate_uuid();
-        segment.name = kSegmentName;
-        segment.base = kSegmentBase;
-        segment.size = kSegmentSize;
-        segment.te_endpoint = segment.name;
-        return segment;
-    }
-
-    static UUID MountSegment(MasterService& service) {
-        const UUID client_id = generate_uuid();
-        auto result = service.MountSegment(MakeSegment(), client_id);
-        EXPECT_TRUE(result.has_value());
-        return client_id;
-    }
-
-    static std::string Key(size_t index) {
-        return "batch_evict_key_" + std::to_string(index);
-    }
-
-    static void PutObject(MasterService& service, const UUID& client_id,
-                          const std::string& key, bool with_soft_pin = false,
-                          const std::string& group_id = std::string()) {
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.preferred_segment = kSegmentName;
-        config.with_soft_pin = with_soft_pin;
-        if (!group_id.empty()) {
-            config.group_ids = std::vector<std::string>{group_id};
-        }
-
-        auto put_start = service.PutStart(client_id, key, TenantId::Default(),
-                                          kObjectSize, config);
-        ASSERT_TRUE(put_start.has_value())
-            << "PutStart failed for key=" << key
-            << ", error=" << toString(put_start.error());
-        ASSERT_TRUE(service
-                        .PutEnd(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                        .has_value());
-    }
-
-    // Ungrouped objects are sharded by key hash, but grouped objects are
-    // routed by their group id, so the direct shard index is not always the
-    // one holding the key. Fall back to a shard scan in that case.
-    template <typename Fn>
-    static bool WithMetadata(MasterService& service, const std::string& key,
-                             Fn&& fn) {
-        const TenantId tenant = TenantId::Default();
-
-        auto try_shard = [&](size_t shard_idx) -> bool {
-            MasterService::MetadataShardAccessorRW shard(&service, shard_idx);
-            auto tenant_it = shard->tenants.find(tenant);
-            if (tenant_it == shard->tenants.end()) {
-                return false;
-            }
-            auto metadata_it = tenant_it->second.metadata.find(key);
-            if (metadata_it == tenant_it->second.metadata.end()) {
-                return false;
-            }
-            fn(metadata_it->second);
-            return true;
-        };
-
-        if (try_shard(service.getMetadataShardIndex(tenant, key))) {
-            return true;
-        }
-        for (size_t shard_idx = 0; shard_idx < MasterService::kNumShards;
-             ++shard_idx) {
-            if (try_shard(shard_idx)) {
-                return true;
-            }
-        }
-        ADD_FAILURE() << "metadata not found for key=" << key;
-        return false;
-    }
-
-    static void SetLease(MasterService& service, const std::string& key,
-                         std::chrono::system_clock::time_point lease_timeout,
-                         std::optional<std::chrono::system_clock::time_point>
-                             soft_pin_timeout = std::nullopt) {
-        WithMetadata(service, key,
-                     [&](MasterService::ObjectMetadata& metadata) {
-                         SpinLocker locker(&metadata.lock);
-                         metadata.lease_timeout = lease_timeout;
-                         metadata.soft_pin_timeout = soft_pin_timeout;
-                     });
-    }
-
-    static bool Exists(MasterService& service, const std::string& key) {
-        auto result = service.ExistKey(key, TenantId::Default());
-        if (!result.has_value()) {
-            ADD_FAILURE() << "ExistKey failed for key=" << key
-                          << ", error=" << toString(result.error());
-            return false;
-        }
-        return result.value();
-    }
-
-    static void RunBatchEvict(MasterService& service, double target,
-                              double lowerbound) {
-        service.BatchEvict(target, lowerbound);
-    }
-
-    static std::chrono::system_clock::time_point ExpiredBase() {
-        return std::chrono::system_clock::now() - std::chrono::hours(1);
-    }
-
-    // Populates `count` expired objects whose lease timestamps are strictly
-    // increasing, so Key(i) is always older than Key(i + 1) and no timestamp
-    // ties exist at the eviction boundary.
-    static void PopulateOldestFirst(MasterService& service,
-                                    const UUID& client_id, size_t count) {
-        const auto base = ExpiredBase();
-        for (size_t i = 0; i < count; ++i) {
-            PutObject(service, client_id, Key(i));
-            SetLease(service, Key(i), base + std::chrono::nanoseconds(i));
-        }
-    }
-    // Builds a population whose oldest `blocked_count` candidates belong to a
-    // group that also holds one member under an active lease. Those candidates
-    // pass the census — their own lease has expired — but cannot be evicted
-    // during execution, because a group is only evictable once every member's
-    // lease has expired. That is an execution-stage failure without any hook:
-    // it exercises the same recovery path as metadata churn between the census
-    // and the eviction pass.
-    struct BlockedGroupPopulation {
-        size_t blocked_count;
-        size_t keeper_index;
-        size_t plain_begin;
-        size_t plain_count;
-        size_t total_objects;
-    };
-
-    static BlockedGroupPopulation PopulateBlockedGroup(
-        MasterService& service, const UUID& client_id,
-        const std::string& group_id, size_t blocked_count, size_t plain_count) {
-        const auto base = ExpiredBase();
-        const auto active_lease =
-            std::chrono::system_clock::now() + std::chrono::hours(1);
-
-        // Oldest leases: the blocked group members are always selected first.
-        for (size_t i = 0; i < blocked_count; ++i) {
-            PutObject(service, client_id, Key(i), /*with_soft_pin=*/false,
-                      group_id);
-            SetLease(service, Key(i), base + std::chrono::nanoseconds(i));
-        }
-
-        // The keeper shares the group but holds an active lease, so no member
-        // of the group can be evicted.
-        const size_t keeper_index = blocked_count;
-        PutObject(service, client_id, Key(keeper_index),
-                  /*with_soft_pin=*/false, group_id);
-        SetLease(service, Key(keeper_index), active_lease);
-
-        // Plain objects are strictly newer than every blocked member.
-        const size_t plain_begin = keeper_index + 1;
-        for (size_t i = 0; i < plain_count; ++i) {
-            const size_t index = plain_begin + i;
-            PutObject(service, client_id, Key(index));
-            SetLease(service, Key(index),
-                     base + std::chrono::nanoseconds(index));
-        }
-
-        return {blocked_count, keeper_index, plain_begin, plain_count,
-                plain_begin + plain_count};
-    }
-
-    static size_t CountAlive(MasterService& service, size_t begin, size_t end) {
-        size_t alive = 0;
-        for (size_t i = begin; i < end; ++i) {
-            if (Exists(service, Key(i))) {
-                ++alive;
-            }
-        }
-        return alive;
-    }
-};
-
-// Oldest-first: with distinct lease timestamps the evicted set must be exactly
-// the oldest ceil(N * ratio) objects, and nothing newer.
-TEST_F(BatchEvictTest, EvictsExactOldestObjectsAtLowRatio) {
-    constexpr size_t kObjectCount = 400;
-    constexpr size_t kExpectedEvicted = 20;  // ceil(400 * 0.05)
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-    PopulateOldestFirst(service, client_id, kObjectCount);
-    ASSERT_EQ(service.GetKeyCount(), kObjectCount);
-
-    RunBatchEvict(service, /*target=*/0.05, /*lowerbound=*/0.05);
-
-    EXPECT_EQ(service.GetKeyCount(), kObjectCount - kExpectedEvicted);
-    for (size_t i = 0; i < kObjectCount; ++i) {
-        EXPECT_EQ(Exists(service, Key(i)), i >= kExpectedEvicted)
-            << "unexpected eviction outcome at index=" << i;
-    }
-}
-
-// target == lowerbound: the first pass already satisfies the lower bound, so
-// the second pass must not evict anything extra.
-TEST_F(BatchEvictTest, TargetEqualsLowerBoundEvictsExactCount) {
-    constexpr size_t kObjectCount = 250;
-    constexpr size_t kExpectedEvicted = 25;  // ceil(250 * 0.10)
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-    PopulateOldestFirst(service, client_id, kObjectCount);
-    ASSERT_EQ(service.GetKeyCount(), kObjectCount);
-
-    RunBatchEvict(service, /*target=*/0.10, /*lowerbound=*/0.10);
-
-    EXPECT_EQ(service.GetKeyCount(), kObjectCount - kExpectedEvicted);
-    EXPECT_FALSE(Exists(service, Key(kExpectedEvicted - 1)));
-    EXPECT_TRUE(Exists(service, Key(kExpectedEvicted)));
-}
-
-// Soft-pin fallback: unpinned objects go first; soft-pinned objects are only
-// evicted by the second pass, oldest first, and only up to the lower bound.
-TEST_F(BatchEvictTest, SoftPinnedEvictedOnlyAfterUnpinned) {
-    constexpr size_t kNoPinCount = 10;
-    constexpr size_t kSoftPinCount = 10;
-    // ceil(20 * 0.80) == 16; the first pass can only evict the 10 unpinned
-    // objects, leaving 6 for the soft-pinned second pass.
-    constexpr size_t kExpectedSoftPinEvicted = 6;
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/true));
-    const UUID client_id = MountSegment(service);
-
-    const auto base = ExpiredBase();
-    const auto active_soft_pin =
-        std::chrono::system_clock::now() + std::chrono::hours(1);
-
-    for (size_t i = 0; i < kNoPinCount; ++i) {
-        PutObject(service, client_id, Key(i));
-        SetLease(service, Key(i), base + std::chrono::nanoseconds(i));
-    }
-    for (size_t i = 0; i < kSoftPinCount; ++i) {
-        const size_t index = kNoPinCount + i;
-        PutObject(service, client_id, Key(index), /*with_soft_pin=*/true);
-        SetLease(service, Key(index), base + std::chrono::nanoseconds(index),
-                 active_soft_pin);
-    }
-    ASSERT_EQ(service.GetKeyCount(), kNoPinCount + kSoftPinCount);
-
-    RunBatchEvict(service, /*target=*/0.80, /*lowerbound=*/0.80);
-
-    for (size_t i = 0; i < kNoPinCount; ++i) {
-        EXPECT_FALSE(Exists(service, Key(i)))
-            << "unpinned object survived at index=" << i;
-    }
-    for (size_t i = 0; i < kSoftPinCount; ++i) {
-        const size_t index = kNoPinCount + i;
-        EXPECT_EQ(Exists(service, Key(index)), i >= kExpectedSoftPinEvicted)
-            << "unexpected soft-pin outcome at index=" << index;
-    }
-    EXPECT_EQ(service.GetKeyCount(), kSoftPinCount - kExpectedSoftPinEvicted);
-}
-
-// Whole-group: selecting one group member evicts the entire group as a unit,
-// even when the target only calls for a single object.
-TEST_F(BatchEvictTest, WholeGroupEvictedTogether) {
-    constexpr size_t kObjectCount = 10;
-    constexpr size_t kGroupSize = 3;
-    const std::string group_id = "batch_evict_test_group";
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-
-    const auto base = ExpiredBase();
-    for (size_t i = 0; i < kObjectCount; ++i) {
-        PutObject(service, client_id, Key(i), /*with_soft_pin=*/false,
-                  i < kGroupSize ? group_id : std::string());
-        SetLease(service, Key(i), base + std::chrono::nanoseconds(i));
-    }
-
-    // ceil(10 * 0.10) == 1 and the oldest candidate is a group member, so the
-    // whole group is evicted even though only one object was requested.
-    RunBatchEvict(service, /*target=*/0.10, /*lowerbound=*/0.10);
-
-    EXPECT_EQ(service.GetKeyCount(), kObjectCount - kGroupSize);
-    for (size_t i = 0; i < kGroupSize; ++i) {
-        EXPECT_FALSE(Exists(service, Key(i)))
-            << "group member survived at index=" << i;
-    }
-    for (size_t i = kGroupSize; i < kObjectCount; ++i) {
-        EXPECT_TRUE(Exists(service, Key(i)))
-            << "non-group object evicted at index=" << i;
-    }
-}
-
-// Whole-group safety: a single group member under an active lease keeps every
-// member of that group resident.
-TEST_F(BatchEvictTest, UnexpiredGroupMemberBlocksWholeGroup) {
-    constexpr size_t kObjectCount = 10;
-    constexpr size_t kGroupSize = 3;
-    const std::string group_id = "batch_evict_test_blocked_group";
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-
-    const auto base = ExpiredBase();
-    const auto unexpired =
-        std::chrono::system_clock::now() + std::chrono::hours(1);
-
-    for (size_t i = 0; i < kObjectCount; ++i) {
-        PutObject(service, client_id, Key(i), /*with_soft_pin=*/false,
-                  i < kGroupSize ? group_id : std::string());
-        SetLease(service, Key(i), base + std::chrono::nanoseconds(i));
-    }
-    // Hold one member of the group under an active lease.
-    SetLease(service, Key(kGroupSize - 1), unexpired);
-
-    RunBatchEvict(service, /*target=*/0.10, /*lowerbound=*/0.10);
-
-    for (size_t i = 0; i < kGroupSize; ++i) {
-        EXPECT_TRUE(Exists(service, Key(i)))
-            << "blocked group member was evicted at index=" << i;
-    }
-    // The blocked group yields nothing, so exactly one ungrouped object is
-    // evicted instead.
-    EXPECT_EQ(service.GetKeyCount(), kObjectCount - 1);
-}
-
-// High ratio: the same oldest-first and exact-count guarantees must hold when
-// the requested ratio covers most of the population.
-TEST_F(BatchEvictTest, HighRatioEvictsExactOldestCount) {
-    constexpr size_t kObjectCount = 200;
-    constexpr size_t kExpectedEvicted = 160;  // ceil(200 * 0.80)
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-    PopulateOldestFirst(service, client_id, kObjectCount);
-    ASSERT_EQ(service.GetKeyCount(), kObjectCount);
-
-    RunBatchEvict(service, /*target=*/0.80, /*lowerbound=*/0.80);
-
-    EXPECT_EQ(service.GetKeyCount(), kObjectCount - kExpectedEvicted);
-    for (size_t i = 0; i < kObjectCount; ++i) {
-        EXPECT_EQ(Exists(service, Key(i)), i >= kExpectedEvicted)
-            << "unexpected eviction outcome at index=" << i;
-    }
-}
-
-// Reserve: a small number of candidates that pass the census but fail during
-// execution is absorbed by the reserve slack, so the requested target is still
-// met exactly and no refill scan is needed.
-TEST_F(BatchEvictTest, ReserveAbsorbsExecutionFailuresAndMeetsTarget) {
-    constexpr size_t kBlockedCount = 12;
-    constexpr size_t kPlainCount = 1200;
-    // 1213 objects in total, ceil(1213 * 0.05) == 61.
-    constexpr size_t kExpectedEvicted = 61;
-    // The 61 oldest candidates are the 12 blocked members plus the 49 oldest
-    // plain objects, so those 49 are always among the evicted set. The
-    // remaining 12 evictions come from the reserve, whose internal order is
-    // unspecified, so only the total is asserted for them.
-    constexpr size_t kAlwaysEvictedPlain = 49;
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-    const auto population =
-        PopulateBlockedGroup(service, client_id, "batch_evict_reserve_group",
-                             kBlockedCount, kPlainCount);
-    ASSERT_EQ(service.GetKeyCount(), population.total_objects);
-
-    RunBatchEvict(service, /*target=*/0.05, /*lowerbound=*/0.05);
-
-    EXPECT_EQ(service.GetKeyCount(),
-              population.total_objects - kExpectedEvicted);
-    EXPECT_EQ(CountAlive(service, 0, kBlockedCount), kBlockedCount)
-        << "blocked group members must survive";
-    EXPECT_TRUE(Exists(service, Key(population.keeper_index)));
-    for (size_t i = 0; i < kAlwaysEvictedPlain; ++i) {
-        EXPECT_FALSE(Exists(service, Key(population.plain_begin + i)))
-            << "oldest plain object survived at offset=" << i;
-    }
-    EXPECT_EQ(
-        CountAlive(service, population.plain_begin, population.total_objects),
-        kPlainCount - kExpectedEvicted);
-}
-
-// Refill: when every candidate inside the reserve frontier fails during
-// execution the reserve is exhausted, and the refill scan must recover the
-// remaining objects so the requested target is still met exactly.
-TEST_F(BatchEvictTest, RefillAfterReserveExhaustionStillMeetsTarget) {
-    // The reserve frontier spans target + max(1024, 10% of target), so more
-    // than 1024 blocked candidates are required to exhaust it.
-    constexpr size_t kBlockedCount = 1160;
-    constexpr size_t kPlainCount = 200;
-    // 1361 objects in total, ceil(1361 * 0.05) == 69.
-    constexpr size_t kExpectedEvicted = 69;
-
-    MasterService service(MakeConfig(/*allow_soft_pin_eviction=*/false));
-    const UUID client_id = MountSegment(service);
-    const auto population =
-        PopulateBlockedGroup(service, client_id, "batch_evict_refill_group",
-                             kBlockedCount, kPlainCount);
-    ASSERT_EQ(service.GetKeyCount(), population.total_objects);
-
-    RunBatchEvict(service, /*target=*/0.05, /*lowerbound=*/0.05);
-
-    // Exact target attainment is the property refill exists to protect: the
-    // whole frontier yielded nothing, so every eviction came from the refill.
-    EXPECT_EQ(service.GetKeyCount(),
-              population.total_objects - kExpectedEvicted);
-    EXPECT_EQ(CountAlive(service, 0, kBlockedCount), kBlockedCount)
-        << "blocked group members must survive";
-    EXPECT_TRUE(Exists(service, Key(population.keeper_index)));
-    EXPECT_EQ(
-        CountAlive(service, population.plain_begin, population.total_objects),
-        kPlainCount - kExpectedEvicted);
-}
-
-}  // namespace mooncake::test
diff --git a/mooncake-store/tests/batch_read_fanout_test.cpp b/mooncake-store/tests/batch_read_fanout_test.cpp
new file mode 100644
index 0000000000..3de34840ad
--- /dev/null
+++ b/mooncake-store/tests/batch_read_fanout_test.cpp
@@ -0,0 +1,180 @@
+#include "batch_read_fanout.h"
+
+#include <cstring>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+struct FakeOp {
+    std::string key;
+};
+
+TEST(PlanDuplicateKeysTest, UniqueKeysAreAllPrimariesInOrder) {
+    std::vector<FakeOp> ops{{"a"}, {"b"}, {"c"}};
+
+    const auto plan = PlanDuplicateKeys(ops);
+
+    EXPECT_EQ(plan.primaries, (std::vector<size_t>{0, 1, 2}));
+    EXPECT_TRUE(plan.duplicates.empty());
+}
+
+TEST(PlanDuplicateKeysTest, DuplicatesPairWithFirstOccurrence) {
+    std::vector<FakeOp> ops{{"a"}, {"b"}, {"a"}, {"a"}, {"b"}};
+
+    const auto plan = PlanDuplicateKeys(ops);
+
+    EXPECT_EQ(plan.primaries, (std::vector<size_t>{0, 1}));
+    EXPECT_EQ(plan.duplicates,
+              (std::vector<std::pair<size_t, size_t>>{{2, 0}, {3, 0}, {4, 1}}));
+}
+
+TEST(CopySlicesMaybeDeviceTest, ContiguousSingleSlice) {
+    char src[] = "hello";
+    char dst[sizeof(src)] = {};
+
+    auto r =
+        CopySlicesMaybeDevice({Slice{dst, sizeof(src)}},
+                              {Slice{src, sizeof(src)}}, sizeof(src), "test");
+
+    ASSERT_TRUE(r.has_value());
+    EXPECT_STREQ(dst, src);
+}
+
+TEST(CopySlicesMaybeDeviceTest, MismatchedChunkingCopiesAcrossBoundaries) {
+    const std::string payload = "0123456789abcdef";
+    std::vector<char> src_buf(payload.begin(), payload.end());
+    std::vector<char> dst_buf(payload.size(), '\0');
+
+    // Source in 3 chunks, destination in 5; bytes must land identically.
+    std::vector<Slice> src{
+        {src_buf.data(), 5}, {src_buf.data() + 5, 7}, {src_buf.data() + 12, 4}};
+    std::vector<Slice> dst{{dst_buf.data(), 2},
+                           {dst_buf.data() + 2, 3},
+                           {dst_buf.data() + 5, 1},
+                           {dst_buf.data() + 6, 6},
+                           {dst_buf.data() + 12, 4}};
+
+    auto r = CopySlicesMaybeDevice(dst, src, payload.size(), "test");
+
+    ASSERT_TRUE(r.has_value());
+    EXPECT_EQ(std::string(dst_buf.begin(), dst_buf.end()), payload);
+}
+
+TEST(CopySlicesMaybeDeviceTest, ZeroSizeSlicesAreSkipped) {
+    char src[] = "ab";
+    char dst[sizeof(src)] = {};
+
+    auto r =
+        CopySlicesMaybeDevice({Slice{nullptr, 0}, Slice{dst, sizeof(src)}},
+                              {Slice{src, sizeof(src)}}, sizeof(src), "test");
+
+    ASSERT_TRUE(r.has_value());
+    EXPECT_STREQ(dst, src);
+}
+
+TEST(CopySlicesMaybeDeviceTest, ShortDestinationUnderflows) {
+    char src[] = "abcd";
+    char dst[2] = {};
+
+    auto r = CopySlicesMaybeDevice({Slice{dst, sizeof(dst)}},
+                                   {Slice{src, sizeof(src) - 1}},
+                                   sizeof(src) - 1, "test");
+
+    ASSERT_FALSE(r.has_value());
+    EXPECT_EQ(r.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST(FanOutDuplicatesTest, SuccessMirrorsPrimaryResult) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(2);
+    results[0] = 16;
+    char src[] = "data";
+    char dst[sizeof(src)] = {};
+
+    FanOutDuplicates({DuplicateFanOutJob{.dup_result_index = 1,
+                                         .primary_result_index = 0,
+                                         .key = "k",
+                                         .dup_bytes = sizeof(src),
+                                         .primary_bytes = sizeof(src),
+                                         .copy =
+                                             [&]() {
+                                                 return CopyMaybeDevice(
+                                                     dst, src, sizeof(src),
+                                                     "test");
+                                             }}},
+                     results);
+
+    ASSERT_TRUE(results[1].has_value());
+    EXPECT_EQ(*results[1], 16);
+    EXPECT_STREQ(dst, src);
+}
+
+TEST(FanOutDuplicatesTest, PrimaryFailurePropagatesError) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(2);
+    results[0] = tl::make_unexpected(ErrorCode::OBJECT_NOT_FOUND);
+    bool copy_ran = false;
+
+    FanOutDuplicates(
+        {DuplicateFanOutJob{.dup_result_index = 1,
+                            .primary_result_index = 0,
+                            .key = "k",
+                            .dup_bytes = 4,
+                            .primary_bytes = 4,
+                            .copy =
+                                [&]() {
+                                    copy_ran = true;
+                                    return tl::expected<void, ErrorCode>();
+                                }}},
+        results);
+
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_FALSE(copy_ran);
+}
+
+TEST(FanOutDuplicatesTest, SizeMismatchFailsLoudlyWithoutCopying) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(2);
+    results[0] = 4;
+    bool copy_ran = false;
+
+    FanOutDuplicates(
+        {DuplicateFanOutJob{.dup_result_index = 1,
+                            .primary_result_index = 0,
+                            .key = "k",
+                            .dup_bytes = 8,
+                            .primary_bytes = 4,
+                            .copy =
+                                [&]() {
+                                    copy_ran = true;
+                                    return tl::expected<void, ErrorCode>();
+                                }}},
+        results);
+
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::INTERNAL_ERROR);
+    EXPECT_FALSE(copy_ran);
+}
+
+TEST(FanOutDuplicatesTest, CopyFailureRecordsCopyError) {
+    std::vector<tl::expected<int64_t, ErrorCode>> results(2);
+    results[0] = 4;
+
+    FanOutDuplicates({DuplicateFanOutJob{.dup_result_index = 1,
+                                         .primary_result_index = 0,
+                                         .key = "k",
+                                         .dup_bytes = 4,
+                                         .primary_bytes = 4,
+                                         .copy =
+                                             []() {
+                                                 return tl::make_unexpected(
+                                                     ErrorCode::TRANSFER_FAIL);
+                                             }}},
+                     results);
+
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::TRANSFER_FAIL);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/batch_remove_test.cpp b/mooncake-store/tests/batch_remove_test.cpp
index 519b38dd70..a3bacef53e 100644
--- a/mooncake-store/tests/batch_remove_test.cpp
+++ b/mooncake-store/tests/batch_remove_test.cpp
@@ -9,6 +9,7 @@
 #include <vector>
 
 #include "allocator.h"
+#include "common/client_buffer_allocation.h"
 #include "client_service.h"
 #include "test_server_helpers.h"
 #include "default_config.h"
diff --git a/mooncake-store/tests/batch_replica_clear_tenant_rpc_test.cpp b/mooncake-store/tests/batch_replica_clear_tenant_rpc_test.cpp
new file mode 100644
index 0000000000..653c5b50d6
--- /dev/null
+++ b/mooncake-store/tests/batch_replica_clear_tenant_rpc_test.cpp
@@ -0,0 +1,138 @@
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <optional>
+#include <string>
+#include <thread>
+
+#include <ylt/coro_rpc/coro_rpc_server.hpp>
+
+#include "common/network.h"
+#include "master_client.h"
+#include "master_config.h"
+#include "rpc_service.h"
+#include "tenant_quota_policy_store.h"
+#include "types.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedPolicyFile {
+   public:
+    ScopedPolicyFile() {
+        const UUID suffix = generate_uuid();
+        path_ = std::filesystem::temp_directory_path() /
+                ("batch_replica_clear_tenants_" + std::to_string(suffix.first) +
+                 "_" + std::to_string(suffix.second) + ".yaml");
+    }
+
+    ~ScopedPolicyFile() {
+        std::error_code ignored;
+        std::filesystem::remove(path_, ignored);
+    }
+
+    const std::filesystem::path& path() const { return path_; }
+
+   private:
+    std::filesystem::path path_;
+};
+
+TEST(BatchReplicaClearTenantRpcTest, UsesClientTenantAndKeepsTenantsIsolated) {
+    constexpr char kTenant[] = "tenant-a";
+    constexpr char kSharedKey[] = "shared-batch-clear-key";
+    constexpr uint64_t kObjectSize = 1024;
+
+    ScopedPolicyFile policy_file;
+    TenantQuotaPolicySnapshot policy;
+    policy.tenant_quotas = {
+        {std::string(TenantId::kDefaultValue), 64 * 1024 * 1024},
+        {kTenant, 64 * 1024 * 1024},
+    };
+    {
+        std::ofstream output(policy_file.path());
+        ASSERT_TRUE(output.is_open());
+        output << FormatTenantQuotaPolicyYaml(policy);
+        ASSERT_TRUE(output.good());
+    }
+
+    WrappedMasterServiceConfig service_config;
+    service_config.default_kv_lease_ttl = 0;
+    service_config.enable_metric_reporting = false;
+    service_config.enable_multi_tenants = true;
+    service_config.tenant_quota_connector_type = "file";
+    service_config.tenant_quota_connector_uri = policy_file.path().string();
+    auto service = std::make_shared<WrappedMasterService>(service_config);
+
+    const auto ports = getFreeTcpPorts(1);
+    ASSERT_EQ(ports.size(), 1u);
+    coro_rpc::coro_rpc_server server(
+        /*thread_num=*/2, /*port=*/ports.front(), /*address=*/"127.0.0.1",
+        std::chrono::seconds(0), /*tcp_no_delay=*/true);
+    RegisterRpcService(server, *service);
+    auto start_result = server.async_start();
+    ASSERT_FALSE(start_result.hasResult());
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+
+    const UUID client_id = generate_uuid();
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "batch_replica_clear_tenant_segment";
+    segment.base = 0x300000000;
+    segment.size = 16 * 1024 * 1024;
+    ASSERT_TRUE(service->MountSegment(segment, client_id).has_value());
+
+    ReplicateConfig replicate_config;
+    replicate_config.replica_num = 1;
+    for (const std::string& tenant :
+         {std::string(kTenant), std::string(TenantId::kDefaultValue)}) {
+        auto put_start = service->PutStart(client_id, kSharedKey, kObjectSize,
+                                           replicate_config, tenant);
+        ASSERT_TRUE(put_start.has_value()) << toString(put_start.error());
+        auto put_end =
+            service->PutEnd(client_id, ObjectMeta{kSharedKey, std::nullopt},
+                            ReplicaType::MEMORY, tenant);
+        ASSERT_TRUE(put_end.has_value()) << toString(put_end.error());
+    }
+
+    {
+        MasterClient tenant_client(client_id, nullptr, kTenant);
+        ASSERT_EQ(
+            tenant_client.Connect("127.0.0.1:" + std::to_string(ports.front())),
+            ErrorCode::OK);
+        auto cleared =
+            tenant_client.BatchReplicaClear({kSharedKey}, client_id, "");
+        ASSERT_TRUE(cleared.has_value()) << toString(cleared.error());
+        EXPECT_EQ(cleared.value(), std::vector<std::string>{kSharedKey});
+    }
+
+    auto tenant_exists = service->ExistKey(kSharedKey, kTenant);
+    ASSERT_TRUE(tenant_exists.has_value());
+    EXPECT_FALSE(tenant_exists.value());
+    auto default_exists =
+        service->ExistKey(kSharedKey, std::string(TenantId::kDefaultValue));
+    ASSERT_TRUE(default_exists.has_value());
+    EXPECT_TRUE(default_exists.value());
+
+    {
+        MasterClient default_client(client_id);
+        ASSERT_EQ(default_client.Connect("127.0.0.1:" +
+                                         std::to_string(ports.front())),
+                  ErrorCode::OK);
+        auto cleared =
+            default_client.BatchReplicaClear({kSharedKey}, client_id, "");
+        ASSERT_TRUE(cleared.has_value()) << toString(cleared.error());
+        EXPECT_EQ(cleared.value(), std::vector<std::string>{kSharedKey});
+    }
+
+    default_exists =
+        service->ExistKey(kSharedKey, std::string(TenantId::kDefaultValue));
+    ASSERT_TRUE(default_exists.has_value());
+    EXPECT_FALSE(default_exists.value());
+
+    server.stop();
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/bucket_backend_config_test.cpp b/mooncake-store/tests/bucket_backend_config_test.cpp
new file mode 100644
index 0000000000..3991508657
--- /dev/null
+++ b/mooncake-store/tests/bucket_backend_config_test.cpp
@@ -0,0 +1,216 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "config/bucket_backend_config.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+    void Unset() { unsetenv(name_.c_str()); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct BucketBackendEnvironment {
+    ScopedEnvVar keys_limit{"MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT"};
+    ScopedEnvVar size_limit{"MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES"};
+    ScopedEnvVar max_total_size{"MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE"};
+    ScopedEnvVar legacy_max_total_size{"MOONCAKE_BUCKET_MAX_TOTAL_SIZE"};
+    ScopedEnvVar max_physical_bytes{
+        "MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES"};
+    ScopedEnvVar disk_scan_cache_ms{
+        "MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS"};
+    ScopedEnvVar eviction_policy{"MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY"};
+    ScopedEnvVar legacy_eviction_policy{"MOONCAKE_BUCKET_EVICTION_POLICY"};
+};
+
+class BucketBackendConfigTest : public ::testing::Test {
+   protected:
+    BucketBackendEnvironment env;
+};
+
+TEST_F(BucketBackendConfigTest, UsesExistingDefaultsWhenEnvironmentIsUnset) {
+    const auto config = BucketBackendConfig::FromEnvironment();
+
+    EXPECT_EQ(config.bucket_keys_limit, 500);
+    EXPECT_EQ(config.bucket_size_limit, 256 * 1024 * 1024);
+    EXPECT_EQ(config.max_total_size, 0);
+    EXPECT_EQ(config.max_physical_bytes, 0);
+    EXPECT_EQ(config.disk_scan_cache_ms, 500);
+    EXPECT_EQ(config.eviction_policy, BucketEvictionPolicy::FIFO);
+}
+
+TEST_F(BucketBackendConfigTest, ReadsIndependentValidValues) {
+    env.keys_limit.Set("1000");
+    env.size_limit.Set("536870912");
+    env.max_total_size.Set("1073741824");
+    env.max_physical_bytes.Set("2147483648");
+    env.disk_scan_cache_ms.Set("250");
+    env.eviction_policy.Set("lru");
+
+    const auto config = BucketBackendConfig::FromEnvironment();
+
+    EXPECT_EQ(config.bucket_keys_limit, 1000);
+    EXPECT_EQ(config.bucket_size_limit, 536870912);
+    EXPECT_EQ(config.max_total_size, 1073741824);
+    EXPECT_EQ(config.max_physical_bytes, 2147483648);
+    EXPECT_EQ(config.disk_scan_cache_ms, 250);
+    EXPECT_EQ(config.eviction_policy, BucketEvictionPolicy::LRU);
+}
+
+TEST_F(BucketBackendConfigTest, PreservesAcceptedIntegerSyntax) {
+    env.keys_limit.Set(" +7 ");
+    env.size_limit.Set(" -8 ");
+    env.max_physical_bytes.Set("0");
+    env.disk_scan_cache_ms.Set("-1");
+
+    const auto config = BucketBackendConfig::FromEnvironment();
+
+    EXPECT_EQ(config.bucket_keys_limit, 7);
+    EXPECT_EQ(config.bucket_size_limit, -8);
+    EXPECT_EQ(config.max_physical_bytes, 0);
+    EXPECT_EQ(config.disk_scan_cache_ms, -1);
+}
+
+TEST_F(BucketBackendConfigTest, InvalidIntegersUseIndividualDefaults) {
+    for (const char* value :
+         {"", "invalid", "1suffix", "9223372036854775808"}) {
+        env.keys_limit.Set(value);
+        env.size_limit.Set(value);
+        env.max_physical_bytes.Set(value);
+        env.disk_scan_cache_ms.Set(value);
+        ::testing::internal::CaptureStderr();
+
+        const auto config = BucketBackendConfig::FromEnvironment();
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.bucket_keys_limit, 500) << value;
+        EXPECT_EQ(config.bucket_size_limit, 256 * 1024 * 1024) << value;
+        EXPECT_EQ(config.max_physical_bytes, 0) << value;
+        EXPECT_EQ(config.disk_scan_cache_ms, 500) << value;
+        for (const char* name : {
+                 "MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT",
+                 "MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES",
+                 "MOONCAKE_OFFLOAD_BUCKET_MAX_PHYSICAL_BYTES",
+                 "MOONCAKE_OFFLOAD_BUCKET_DISK_SCAN_CACHE_MS",
+             }) {
+            EXPECT_NE(logs.find(name), std::string::npos)
+                << name << '=' << value;
+        }
+    }
+}
+
+TEST_F(BucketBackendConfigTest, PreferredTotalSizeOverridesLegacyAlias) {
+    env.legacy_max_total_size.Set("111");
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().max_total_size, 111);
+
+    env.max_total_size.Set("222");
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().max_total_size, 222);
+}
+
+TEST_F(BucketBackendConfigTest,
+       InvalidPreferredTotalSizeFallsBackToLegacyAlias) {
+    env.legacy_max_total_size.Set("111");
+    for (const char* value : {"", "invalid", "9223372036854775808"}) {
+        env.max_total_size.Set(value);
+        EXPECT_EQ(BucketBackendConfig::FromEnvironment().max_total_size, 111)
+            << value;
+    }
+}
+
+TEST_F(BucketBackendConfigTest, PreservesTotalSizeAliasWarningOrder) {
+    env.legacy_max_total_size.Set("invalid-legacy");
+    env.max_total_size.Set("invalid-preferred");
+    ::testing::internal::CaptureStderr();
+
+    const auto config = BucketBackendConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_EQ(config.max_total_size, 0);
+    const size_t legacy = logs.find("MOONCAKE_BUCKET_MAX_TOTAL_SIZE");
+    const size_t preferred =
+        logs.find("MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE");
+    ASSERT_NE(legacy, std::string::npos);
+    ASSERT_NE(preferred, std::string::npos);
+    EXPECT_LT(legacy, preferred);
+}
+
+TEST_F(BucketBackendConfigTest, PreservesEvictionPolicyAliasPrecedence) {
+    env.legacy_eviction_policy.Set("lru");
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().eviction_policy,
+              BucketEvictionPolicy::LRU);
+
+    env.eviction_policy.Set("fifo");
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().eviction_policy,
+              BucketEvictionPolicy::FIFO);
+}
+
+TEST_F(BucketBackendConfigTest, UnknownPolicyDisablesEvictionWithoutWarning) {
+    env.legacy_eviction_policy.Set("lru");
+    for (const char* value : {"", "FIFO", "unknown"}) {
+        env.eviction_policy.Set(value);
+        ::testing::internal::CaptureStderr();
+
+        const auto config = BucketBackendConfig::FromEnvironment();
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.eviction_policy, BucketEvictionPolicy::NONE) << value;
+        EXPECT_TRUE(logs.empty()) << value;
+    }
+}
+
+TEST_F(BucketBackendConfigTest, ValidationPreservesExistingBounds) {
+    BucketBackendConfig config;
+    EXPECT_TRUE(config.Validate());
+
+    config.bucket_keys_limit = 0;
+    EXPECT_FALSE(config.Validate());
+
+    config.bucket_keys_limit = 1;
+    config.bucket_size_limit = 0;
+    EXPECT_FALSE(config.Validate());
+
+    config.bucket_size_limit = 1;
+    config.max_total_size = -1;
+    config.max_physical_bytes = -1;
+    config.disk_scan_cache_ms = -1;
+    EXPECT_TRUE(config.Validate());
+}
+
+TEST_F(BucketBackendConfigTest, EachConstructionReadsCurrentEnvironment) {
+    env.keys_limit.Set("700");
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().bucket_keys_limit, 700);
+
+    env.keys_limit.Unset();
+    EXPECT_EQ(BucketBackendConfig::FromEnvironment().bucket_keys_limit, 500);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/buffer_allocator_test.cpp b/mooncake-store/tests/buffer_allocator_test.cpp
index cefaf21080..605d51c995 100644
--- a/mooncake-store/tests/buffer_allocator_test.cpp
+++ b/mooncake-store/tests/buffer_allocator_test.cpp
@@ -6,15 +6,27 @@
 #include <cstddef>
 #include <cstring>
 #include <chrono>
+#include <functional>
+#include <limits>
 #include <memory>
 #include <thread>
 #include <vector>
 
 #include "allocator.h"
+#include "master_metric_manager.h"
 #include "types.h"
 
 namespace mooncake {
 
+namespace {
+
+LiveAllocation ToLiveAllocation(uintptr_t base,
+                                const AllocatedBuffer::Descriptor& descriptor) {
+    return {descriptor.buffer_address_ - base, descriptor.size_};
+}
+
+}  // namespace
+
 // Test fixture for BufferAllocator tests
 class BufferAllocatorTest : public ::testing::Test {
    protected:
@@ -34,16 +46,12 @@ class BufferAllocatorTest : public ::testing::Test {
         const std::string& segment_name, size_t base_offset, size_t size,
         BufferAllocatorType allocator_type) {
         const size_t base = 0x100000000ULL + base_offset;  // 4GB + offset
-        switch (allocator_type) {
-            case BufferAllocatorType::CACHELIB:
-                return std::make_shared<CachelibBufferAllocator>(
-                    segment_name, base, size, segment_name);
-            case BufferAllocatorType::OFFSET:
-                return std::make_shared<OffsetBufferAllocator>(
-                    segment_name, base, size, segment_name);
-            default:
-                throw std::invalid_argument("Invalid allocator type");
+        auto allocator = CreateBufferAllocator(allocator_type, segment_name,
+                                               base, size, segment_name);
+        if (!allocator) {
+            throw std::invalid_argument("Invalid allocator test parameters");
         }
+        return std::move(*allocator);
     }
 
     void VerifyAllocatedBuffer(const AllocatedBuffer& bufHandle,
@@ -134,7 +142,7 @@ TEST_F(BufferAllocatorTest, OffsetLargestFreeRegionRemainsExact) {
     EXPECT_EQ(allocator->getLargestFreeRegion(), CAPACITY);
 }
 
-TEST_F(BufferAllocatorTest, RestoreOffsetAllocationsAtOriginalAddresses) {
+TEST_F(BufferAllocatorTest, ImportOffsetAllocationsAtOriginalAddresses) {
     constexpr uintptr_t kBase = 0x180000000ULL;
     constexpr size_t kCapacity = 16 * 1024 * 1024;
     const std::string segment = "restore-segment";
@@ -149,132 +157,260 @@ TEST_F(BufferAllocatorTest, RestoreOffsetAllocationsAtOriginalAddresses) {
     ASSERT_NE(removed, nullptr);
     ASSERT_NE(last, nullptr);
 
-    std::vector<AllocatedBuffer::Descriptor> descriptors = {
+    const std::vector<AllocatedBuffer::Descriptor> descriptors = {
         first->get_descriptor(), last->get_descriptor()};
+    std::vector<LiveAllocation> allocations = {
+        ToLiveAllocation(kBase, descriptors[0]),
+        ToLiveAllocation(kBase, descriptors[1])};
+    const auto removed_descriptor = removed->get_descriptor();
     removed.reset();
 
-    auto restored = RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                                 endpoint, descriptors);
+    auto restored = ImportOffsetBufferAllocator(segment, kBase, kCapacity,
+                                                endpoint, allocations);
     ASSERT_TRUE(restored.has_value());
     ASSERT_EQ(restored->buffers.size(), descriptors.size());
+    EXPECT_EQ(restored->allocator->size(),
+              descriptors[0].size_ + descriptors[1].size_);
     EXPECT_EQ(restored->buffers[0]->get_descriptor().buffer_address_,
               descriptors[0].buffer_address_);
     EXPECT_EQ(restored->buffers[1]->get_descriptor().buffer_address_,
               descriptors[1].buffer_address_);
 
-    auto new_buffer = restored->allocator->allocate(1024);
+    auto new_buffer = restored->allocator->allocate(removed_descriptor.size_);
     ASSERT_NE(new_buffer, nullptr);
-    const auto new_address = reinterpret_cast<uintptr_t>(new_buffer->data());
-    for (const auto& descriptor : descriptors) {
-        EXPECT_TRUE(
-            new_address + new_buffer->size() <= descriptor.buffer_address_ ||
-            descriptor.buffer_address_ + descriptor.size_ <= new_address);
-    }
-
-    auto wrong_endpoint = descriptors;
-    wrong_endpoint[0].transport_endpoint_ = "other-endpoint";
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, wrong_endpoint)
-                     .has_value());
-
-    auto duplicate = descriptors;
-    duplicate.push_back(descriptors.front());
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, duplicate)
-                     .has_value());
-
-    auto out_of_range = descriptors;
-    out_of_range[0].buffer_address_ = kBase + kCapacity;
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, out_of_range)
-                     .has_value());
+    EXPECT_EQ(reinterpret_cast<uintptr_t>(new_buffer->data()),
+              removed_descriptor.buffer_address_);
 }
 
-TEST_F(BufferAllocatorTest, RestoreOffsetAllocationsValidatesRangesAndOrder) {
+TEST_F(BufferAllocatorTest, ImportOffsetAllocationsValidatesRangesAndOrder) {
     constexpr uintptr_t kBase = 0x190000000ULL;
     constexpr size_t kCapacity = 4096;
     const std::string segment = "restore-validation";
     const std::string endpoint = "restore-validation-endpoint";
-    auto descriptor = [&](uintptr_t address, uint64_t size) {
-        return AllocatedBuffer::Descriptor{size, address, "tcp", endpoint};
+    auto allocation = [&](uintptr_t address, uint64_t size) {
+        return LiveAllocation{address - kBase, size};
     };
 
-    std::vector<AllocatedBuffer::Descriptor> unsorted = {
-        descriptor(kBase + 512, 64), descriptor(kBase + 128, 64)};
-    auto restored = RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                                 endpoint, unsorted);
+    std::vector<LiveAllocation> unsorted = {allocation(kBase + 512, 64),
+                                            allocation(kBase + 128, 64)};
+    auto restored = ImportOffsetBufferAllocator(segment, kBase, kCapacity,
+                                                endpoint, unsorted);
     ASSERT_TRUE(restored.has_value());
     ASSERT_EQ(restored->buffers.size(), unsorted.size());
     EXPECT_EQ(reinterpret_cast<uintptr_t>(restored->buffers[0]->data()),
-              unsorted[0].buffer_address_);
+              kBase + unsorted[0].offset_from_base);
     EXPECT_EQ(reinterpret_cast<uintptr_t>(restored->buffers[1]->data()),
-              unsorted[1].buffer_address_);
+              kBase + unsorted[1].offset_from_base);
 
-    std::vector<AllocatedBuffer::Descriptor> overlapping = {
-        descriptor(kBase + 128, 100), descriptor(kBase + 200, 32)};
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, overlapping)
+    std::vector<LiveAllocation> overlapping = {allocation(kBase + 128, 100),
+                                               allocation(kBase + 200, 32)};
+    EXPECT_FALSE(ImportOffsetBufferAllocator(segment, kBase, kCapacity,
+                                             endpoint, overlapping)
                      .has_value());
 
-    std::vector<AllocatedBuffer::Descriptor> normalized_past_end = {
-        descriptor(kBase + kCapacity - 100, 100)};
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, normalized_past_end)
+    std::vector<LiveAllocation> normalized_past_end = {
+        allocation(kBase + kCapacity - 100, 100)};
+    EXPECT_FALSE(ImportOffsetBufferAllocator(segment, kBase, kCapacity,
+                                             endpoint, normalized_past_end)
                      .has_value());
 
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(
+    EXPECT_FALSE(ImportOffsetBufferAllocator(
                      segment, std::numeric_limits<size_t>::max() - 100, 200,
                      endpoint, {})
                      .has_value());
-    std::vector<AllocatedBuffer::Descriptor> descriptor_overflow = {
-        descriptor(std::numeric_limits<uintptr_t>::max() - 10, 20)};
-    EXPECT_FALSE(RestoreOffsetBufferAllocator(segment, kBase, kCapacity,
-                                              endpoint, descriptor_overflow)
+    std::vector<LiveAllocation> allocation_overflow = {
+        {std::numeric_limits<uintptr_t>::max() - kBase - 10, 20}};
+    EXPECT_FALSE(ImportOffsetBufferAllocator(segment, kBase, kCapacity,
+                                             endpoint, allocation_overflow)
                      .has_value());
 }
 
-TEST_F(BufferAllocatorTest, RestoredOffsetHandleReleasesItsExactAddress) {
+TEST_F(BufferAllocatorTest, ImportedOffsetHandleReleasesItsExactAddress) {
     constexpr uintptr_t kBase = 0x1A0000000ULL;
     constexpr size_t kCapacity = 4096;
     const std::string endpoint = "restore-release";
-    std::vector<AllocatedBuffer::Descriptor> descriptors = {
-        {64, kBase + 128, "tcp", endpoint}, {64, kBase + 512, "tcp", endpoint}};
-    auto restored = RestoreOffsetBufferAllocator(
-        "restore-release", kBase, kCapacity, endpoint, descriptors);
+    std::vector<LiveAllocation> allocations = {{0, 64}, {512, 64}};
+    auto restored = ImportOffsetBufferAllocator(
+        "restore-release", kBase, kCapacity, endpoint, allocations);
     ASSERT_TRUE(restored.has_value());
 
     restored->buffers[0].reset();
     auto replacement = restored->allocator->allocate(64);
     ASSERT_NE(replacement, nullptr);
     EXPECT_EQ(reinterpret_cast<uintptr_t>(replacement->data()),
-              descriptors[0].buffer_address_);
+              kBase + allocations[0].offset_from_base);
 }
 
-TEST_F(BufferAllocatorTest, RestoreOffsetAllocationsHasNoArbitraryGapLimit) {
+TEST_F(BufferAllocatorTest, ImportOffsetAllocationsHasNoArbitraryGapLimit) {
     constexpr uintptr_t kBase = 0x1B0000000ULL;
     constexpr size_t kGapCount = 65537;
     const std::string endpoint = "restore-many-gaps";
-    std::vector<AllocatedBuffer::Descriptor> descriptors;
-    descriptors.reserve(kGapCount);
+    std::vector<LiveAllocation> allocations;
+    allocations.reserve(kGapCount);
     for (size_t i = 0; i < kGapCount; ++i) {
-        descriptors.push_back({1, kBase + 1 + i * 2, "tcp", endpoint});
+        allocations.push_back({1 + i * 2, 1});
     }
 
-    auto restored = RestoreOffsetBufferAllocator(
-        "restore-many-gaps", kBase, kGapCount * 2 + 1, endpoint, descriptors);
+    auto restored = ImportOffsetBufferAllocator(
+        "restore-many-gaps", kBase, kGapCount * 2 + 1, endpoint, allocations);
     ASSERT_TRUE(restored.has_value());
-    EXPECT_EQ(restored->buffers.size(), descriptors.size());
+    EXPECT_EQ(restored->buffers.size(), allocations.size());
     EXPECT_EQ(reinterpret_cast<uintptr_t>(restored->buffers.back()->data()),
-              descriptors.back().buffer_address_);
+              kBase + allocations.back().offset_from_base);
 }
 
-TEST_F(BufferAllocatorTest, RestoreCachelibAllocationsAtOriginalAddresses) {
+TEST_F(BufferAllocatorTest, CachelibCreateRejectsInvalidMemoryLayout) {
+    constexpr size_t kSlabSize = facebook::cachelib::Slab::kSize;
+    constexpr uintptr_t kBase = 0x1C0000000ULL;
+
+    auto expect_invalid = [](size_t base, size_t size) {
+        auto result = CachelibBufferAllocator::Create("cachelib-invalid", base,
+                                                      size, "endpoint");
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    };
+
+    expect_invalid(kBase + 1, kSlabSize);
+    expect_invalid(kBase, kSlabSize + 1);
+    expect_invalid(std::numeric_limits<size_t>::max() - kSlabSize,
+                   2 * kSlabSize);
+    if constexpr (std::numeric_limits<size_t>::max() / kSlabSize >
+                  std::numeric_limits<unsigned int>::max()) {
+        const size_t too_many_slabs =
+            (static_cast<size_t>(std::numeric_limits<unsigned int>::max()) +
+             1) *
+            kSlabSize;
+        expect_invalid(kBase, too_many_slabs);
+    }
+}
+
+TEST_F(BufferAllocatorTest, OffsetRestoreFactoryRejectsInvalidState) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline = metrics.get_allocated_mem_size();
+    const std::string segment_name = "restore-factory";
+    constexpr size_t kBase = 0x100000000ULL;
+    constexpr size_t kCapacity = 16U * 1024 * 1024;
+    auto state = offset_allocator::OffsetAllocator::create(kBase, kCapacity);
+    ASSERT_NE(state, nullptr);
+
+    auto snapshot = [&] {
+        return OffsetBufferAllocatorSnapshot{segment_name,
+                                             kBase,
+                                             kCapacity,
+                                             0,
+                                             segment_name + "-endpoint",
+                                             state->CaptureSnapshot()};
+    };
+    const auto expect_rejected = [](OffsetBufferAllocatorSnapshot candidate) {
+        auto restored = OffsetBufferAllocator::Restore(std::move(candidate));
+        ASSERT_FALSE(restored.has_value());
+        EXPECT_EQ(restored.error(), ErrorCode::INVALID_PARAMS);
+    };
+    auto missing_layout = snapshot();
+    missing_layout.allocation_state.layout.reset();
+    expect_rejected(std::move(missing_layout));
+    auto invalid_usage = snapshot();
+    invalid_usage.used_bytes = kCapacity + 1;
+    expect_rejected(std::move(invalid_usage));
+    auto mismatched_base = snapshot();
+    ++mismatched_base.allocation_state.base;
+    expect_rejected(std::move(mismatched_base));
+    auto overflow = snapshot();
+    overflow.used_bytes = std::numeric_limits<size_t>::max();
+    expect_rejected(std::move(overflow));
+    // The persisted counters must describe the persisted layout.
+    auto wrong_alloc_num = snapshot();
+    ++wrong_alloc_num.allocation_state.allocated_num;
+    expect_rejected(std::move(wrong_alloc_num));
+    auto wrong_alloc_size = snapshot();
+    wrong_alloc_size.allocation_state.allocated_size = kCapacity;
+    expect_rejected(std::move(wrong_alloc_size));
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+
+    {
+        auto restored = OffsetBufferAllocator::Restore(snapshot());
+        ASSERT_TRUE(restored.has_value());
+        EXPECT_EQ((*restored)->size(), 0U);
+        EXPECT_EQ((*restored)->capacity(), kCapacity);
+
+        auto buffer = (*restored)->allocate(4096);
+        ASSERT_NE(buffer, nullptr);
+        EXPECT_EQ((*restored)->size(), 4096U);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline + 4096);
+    }
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+}
+
+TEST_F(BufferAllocatorTest,
+       SnapshotValidationReportsErrorsWithoutPublishingUsage) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline = metrics.get_allocated_mem_size();
+    constexpr size_t kBase = 0x100000000ULL;
+    constexpr size_t kCapacity = 16U << 20;
+    auto state =
+        offset_allocator::OffsetAllocator::create(kBase, kCapacity, 16, 32);
+    auto allocation = state->allocate(4097);
+    ASSERT_TRUE(allocation.has_value());
+    auto snapshot = [&] {
+        return OffsetBufferAllocatorSnapshot{
+            .segment_name = "validate-snapshot",
+            .base = kBase,
+            .capacity = kCapacity,
+            .used_bytes = 4097,
+            .transport_endpoint = "endpoint",
+            .allocation_state = state->CaptureSnapshot(),
+        };
+    };
+    struct Fault {
+        const char* diagnostic;
+        std::function<void(OffsetBufferAllocatorSnapshot&)> apply;
+    };
+    const std::vector<Fault> faults{
+        {"bounds", [](auto& s) { ++s.base; }},
+        {"bounds", [](auto& s) { ++s.capacity; }},
+        {"usage", [](auto& s) { s.used_bytes = s.capacity + 1; }},
+        {"used_bytes", [](auto& s) { s.used_bytes = 0; }},
+        {"layout", [](auto& s) { s.allocation_state.layout.reset(); }},
+        {"multiplier_bits",
+         [](auto& s) { s.allocation_state.multiplier_bits = 64; }},
+        {"allocated_num", [](auto& s) { ++s.allocation_state.allocated_num; }},
+        {"allocated_size",
+         [](auto& s) { s.used_bytes = s.allocation_state.allocated_size = 0; }},
+    };
+    for (const auto& fault : faults) {
+        SCOPED_TRACE(fault.diagnostic);
+        auto candidate = snapshot();
+        fault.apply(candidate);
+        const auto valid = candidate.Validate();
+        ASSERT_FALSE(valid.has_value());
+        EXPECT_NE(valid.error().find(fault.diagnostic), std::string::npos);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+        auto restored = OffsetBufferAllocator::Restore(std::move(candidate));
+        ASSERT_FALSE(restored.has_value());
+        EXPECT_EQ(restored.error(), ErrorCode::INVALID_PARAMS);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+    }
+    auto clean = snapshot();
+    ASSERT_TRUE(clean.Validate().has_value());
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+    {
+        auto restored = OffsetBufferAllocator::Restore(std::move(clean));
+        ASSERT_TRUE(restored.has_value());
+        EXPECT_EQ((*restored)->size(), 4097U);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline + 4097);
+    }
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+}
+
+TEST_F(BufferAllocatorTest, ImportCachelibAllocationsAtOriginalAddresses) {
     constexpr uintptr_t kBase = 0x1C0000000ULL;
     constexpr size_t kCapacity = 4 * facebook::cachelib::Slab::kSize;
     const std::string segment = "cachelib-restore";
     const std::string endpoint = "cachelib-restore-endpoint";
-    auto original = std::make_shared<CachelibBufferAllocator>(
-        segment, kBase, kCapacity, endpoint);
+    auto created =
+        CachelibBufferAllocator::Create(segment, kBase, kCapacity, endpoint);
+    ASSERT_TRUE(created.has_value());
+    auto original = std::move(*created);
 
     auto small_first = original->allocate(64);
     auto small_hole = original->allocate(64);
@@ -292,11 +428,16 @@ TEST_F(BufferAllocatorTest, RestoreCachelibAllocationsAtOriginalAddresses) {
     std::vector<AllocatedBuffer::Descriptor> descriptors = {
         large_last->get_descriptor(), small_first->get_descriptor(),
         large_first->get_descriptor(), small_last->get_descriptor()};
+    std::vector<LiveAllocation> allocations;
+    allocations.reserve(descriptors.size());
+    for (const auto& descriptor : descriptors) {
+        allocations.push_back(ToLiveAllocation(kBase, descriptor));
+    }
     small_hole.reset();
     large_hole.reset();
 
-    auto restored = RestoreCachelibBufferAllocator(segment, kBase, kCapacity,
-                                                   endpoint, descriptors);
+    auto restored = ImportCachelibBufferAllocator(segment, kBase, kCapacity,
+                                                  endpoint, allocations);
     ASSERT_TRUE(restored.has_value());
     ASSERT_EQ(restored->buffers.size(), descriptors.size());
     for (size_t i = 0; i < descriptors.size(); ++i) {
@@ -318,42 +459,24 @@ TEST_F(BufferAllocatorTest, RestoreCachelibAllocationsAtOriginalAddresses) {
     EXPECT_EQ(reinterpret_cast<uintptr_t>(replacement->data()), released);
 }
 
-TEST_F(BufferAllocatorTest, RestoreCachelibAllocationsRejectsInvalidLayouts) {
+TEST_F(BufferAllocatorTest, ImportCachelibAllocationsRejectsInvalidLayouts) {
     constexpr uintptr_t kBase = 0x1D0000000ULL;
     constexpr size_t kCapacity = 4 * facebook::cachelib::Slab::kSize;
-    constexpr size_t kSlabSize = facebook::cachelib::Slab::kSize;
     const std::string endpoint = "cachelib-invalid-endpoint";
-    auto descriptor = [&](uintptr_t address, uint64_t size) {
-        return AllocatedBuffer::Descriptor{size, address, "tcp", endpoint};
+    auto allocation = [&](uintptr_t address, uint64_t size) {
+        return LiveAllocation{address - kBase, size};
     };
-    auto restore = [&](const std::vector<AllocatedBuffer::Descriptor>& descs) {
-        return RestoreCachelibBufferAllocator("cachelib-invalid", kBase,
-                                              kCapacity, endpoint, descs);
+    auto import = [&](const std::vector<LiveAllocation>& allocations) {
+        return ImportCachelibBufferAllocator("cachelib-invalid", kBase,
+                                             kCapacity, endpoint, allocations);
     };
 
     EXPECT_FALSE(
-        restore({descriptor(kBase, 64), descriptor(kBase, 4096)}).has_value());
-    EXPECT_FALSE(restore({descriptor(kBase + 1, 64)}).has_value());
+        import({allocation(kBase, 64), allocation(kBase, 4096)}).has_value());
+    EXPECT_FALSE(import({allocation(kBase + 1, 64)}).has_value());
     EXPECT_FALSE(
-        restore({descriptor(kBase, 64), descriptor(kBase, 64)}).has_value());
-
-    auto wrong_endpoint = descriptor(kBase, 64);
-    wrong_endpoint.transport_endpoint_ = "wrong";
-    EXPECT_FALSE(restore({wrong_endpoint}).has_value());
-    EXPECT_FALSE(restore({descriptor(kBase + kCapacity, 64)}).has_value());
-    EXPECT_FALSE(RestoreCachelibBufferAllocator("cachelib-invalid", kBase + 1,
-                                                kCapacity, endpoint, {})
-                     .has_value());
-    EXPECT_FALSE(RestoreCachelibBufferAllocator(
-                     "cachelib-invalid",
-                     std::numeric_limits<size_t>::max() - kSlabSize,
-                     2 * kSlabSize, endpoint, {})
-                     .has_value());
-
-    auto valid_after_fail = restore({descriptor(kBase + kSlabSize, 4096)});
-    ASSERT_TRUE(valid_after_fail.has_value());
-    EXPECT_EQ(reinterpret_cast<uintptr_t>(valid_after_fail->buffers[0]->data()),
-              kBase + kSlabSize);
+        import({allocation(kBase, 64), allocation(kBase, 64)}).has_value());
+    EXPECT_FALSE(import({allocation(kBase + kCapacity, 64)}).has_value());
 }
 
 TEST_F(BufferAllocatorTest, CachelibImportRejectsChunkInSlabTail) {
@@ -371,32 +494,16 @@ TEST_F(BufferAllocatorTest, CachelibImportRejectsChunkInSlabTail) {
         pool, {{reinterpret_cast<void*>(kBase + kAllocSize), kAllocSize}}));
 }
 
-TEST_F(BufferAllocatorTest, RestoreCachelibRejectsNonMemoryDescriptors) {
+TEST_F(BufferAllocatorTest, CachelibImportRejectsNonMemoryReplicaType) {
     constexpr uintptr_t kBase = 0x1F0000000ULL;
     constexpr size_t kCapacity = 2 * facebook::cachelib::Slab::kSize;
     const std::string endpoint = "cachelib-memory-only";
-    std::vector<AllocatedBuffer::Descriptor> descriptors = {
-        {64, kBase, "tcp", endpoint}};
+    std::vector<LiveAllocation> allocations = {{0, 64}};
 
-    EXPECT_FALSE(RestoreCachelibBufferAllocator(
-                     "cachelib-memory-only", kBase, kCapacity, endpoint,
-                     descriptors, ReplicaType::NOF_SSD)
+    EXPECT_FALSE(ImportCachelibBufferAllocator("cachelib-memory-only", kBase,
+                                               kCapacity, endpoint, allocations,
+                                               ReplicaType::NOF_SSD)
                      .has_value());
-
-    descriptors[0].protocol_ = "cxl";
-    EXPECT_FALSE(RestoreCachelibBufferAllocator("cachelib-memory-only", kBase,
-                                                kCapacity, endpoint,
-                                                descriptors)
-                     .has_value());
-
-    descriptors[0].protocol_ = "rdma";
-    auto rdma = RestoreCachelibBufferAllocator(
-        "cachelib-memory-only", kBase, kCapacity, endpoint, descriptors);
-    ASSERT_TRUE(rdma.has_value());
-    const auto restored = rdma->buffers[0]->get_descriptor();
-    EXPECT_EQ(restored.protocol_, descriptors[0].protocol_);
-    EXPECT_EQ(restored.buffer_address_, descriptors[0].buffer_address_);
-    EXPECT_EQ(restored.transport_endpoint_, descriptors[0].transport_endpoint_);
 }
 
 // Test allocation request larger than available space
diff --git a/mooncake-store/tests/byte_size_test.cpp b/mooncake-store/tests/byte_size_test.cpp
new file mode 100644
index 0000000000..45c6a95180
--- /dev/null
+++ b/mooncake-store/tests/byte_size_test.cpp
@@ -0,0 +1,34 @@
+#include "common/byte_size.h"
+
+#include <gtest/gtest.h>
+
+using namespace mooncake;
+
+TEST(UtilsTest, ByteSizeToString) {
+    EXPECT_EQ(byte_size_to_string(999), "999 B");
+    EXPECT_EQ(byte_size_to_string(2048), "2.00 KB");
+    EXPECT_EQ(byte_size_to_string(5ULL * 1024 * 1024 + 1234), "5.00 MB");
+    EXPECT_EQ(byte_size_to_string(15ULL * 1024 * 1024 * 1024), "15.00 GB");
+    EXPECT_EQ(byte_size_to_string(0), "0 B");
+    EXPECT_EQ(byte_size_to_string(1), "1 B");
+    EXPECT_EQ(byte_size_to_string(1024), "1.00 KB");
+    EXPECT_EQ(byte_size_to_string(1024 * 1024), "1.00 MB");
+    EXPECT_EQ(byte_size_to_string(1024ULL * 1024 * 1024), "1.00 GB");
+    EXPECT_EQ(byte_size_to_string(1024ULL * 1024 * 1024 * 1024), "1.00 TB");
+    EXPECT_EQ(byte_size_to_string(15 * 1024 + 134), "15.13 KB");
+    EXPECT_EQ(byte_size_to_string(15 * 1024 * 1024 + 44048), "15.04 MB");
+}
+
+TEST(UtilsTest, StringToByteSize) {
+    auto parsed = try_string_to_byte_size("16 MB");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed.value(), 16ULL * 1024 * 1024);
+
+    parsed = try_string_to_byte_size("0");
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(parsed.value(), 0);
+
+    EXPECT_FALSE(try_string_to_byte_size("-5").has_value());
+    EXPECT_FALSE(try_string_to_byte_size("16XB").has_value());
+    EXPECT_EQ(string_to_byte_size("-5"), 0);
+}
diff --git a/mooncake-store/tests/client_auto_discovery_config_test.cpp b/mooncake-store/tests/client_auto_discovery_config_test.cpp
new file mode 100644
index 0000000000..e9f67f7fc3
--- /dev/null
+++ b/mooncake-store/tests/client_auto_discovery_config_test.cpp
@@ -0,0 +1,156 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "../src/config/client_auto_discovery_config.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+class ClientAutoDiscoveryConfigTest : public ::testing::Test {
+   protected:
+    using Variables = ClientAutoDiscoveryEnvironmentVariables;
+
+    ScopedEnvVar auto_discover{Variables::MC_MS_AUTO_DISC.name};
+    ScopedEnvVar filters{Variables::MC_MS_FILTERS.name};
+};
+
+TEST_F(ClientAutoDiscoveryConfigTest, UsesProtocolAndDeviceDefaults) {
+    EXPECT_FALSE(
+        ClientAutoDiscoveryConfig::FromEnvironment("tcp", false).enabled);
+    EXPECT_TRUE(
+        ClientAutoDiscoveryConfig::FromEnvironment("rdma", false).enabled);
+    EXPECT_TRUE(
+        ClientAutoDiscoveryConfig::FromEnvironment("efa", false).enabled);
+    EXPECT_FALSE(
+        ClientAutoDiscoveryConfig::FromEnvironment("rdma", true).enabled);
+    EXPECT_FALSE(
+        ClientAutoDiscoveryConfig::FromEnvironment("efa", true).enabled);
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, ExplicitZeroAndOneOverrideDefaults) {
+    auto_discover.Set("0");
+    EXPECT_FALSE(
+        ClientAutoDiscoveryConfig::FromEnvironment("rdma", false).enabled);
+
+    auto_discover.Set("1");
+    EXPECT_TRUE(
+        ClientAutoDiscoveryConfig::FromEnvironment("tcp", true).enabled);
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, PreservesStoiAcceptedSyntax) {
+    for (const char* value : {"1abc", " 1 ", "+1suffix", "01"}) {
+        auto_discover.Set(value);
+        EXPECT_TRUE(
+            ClientAutoDiscoveryConfig::FromEnvironment("tcp", true).enabled)
+            << value;
+    }
+    for (const char* value : {"0abc", " 0 ", "+0suffix", "00"}) {
+        auto_discover.Set(value);
+        EXPECT_FALSE(
+            ClientAutoDiscoveryConfig::FromEnvironment("rdma", false).enabled)
+            << value;
+    }
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, InvalidValuesUseProtocolDefault) {
+    for (const char* value : {"", "true", "-1", "2", "999999999999999999999"}) {
+        auto_discover.Set(value);
+        EXPECT_TRUE(
+            ClientAutoDiscoveryConfig::FromEnvironment("efa", false).enabled)
+            << value;
+        EXPECT_FALSE(
+            ClientAutoDiscoveryConfig::FromEnvironment("tcp", false).enabled)
+            << value;
+    }
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, SplitsAndTrimsEnabledFilters) {
+    auto_discover.Set("1");
+    filters.Set(" mlx5_0, ,mlx5_1,, ");
+
+    auto config = ClientAutoDiscoveryConfig::FromEnvironment("rdma", true);
+    config.LoadFiltersFromEnvironment();
+
+    EXPECT_EQ(config.filters,
+              (std::vector<std::string>{"mlx5_0", "", "mlx5_1", "", ""}));
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, PreservesExplicitlyEmptyFilter) {
+    auto_discover.Set("1");
+    filters.Set("");
+
+    auto config = ClientAutoDiscoveryConfig::FromEnvironment("tcp", true);
+    config.LoadFiltersFromEnvironment();
+
+    EXPECT_EQ(config.filters, (std::vector<std::string>{""}));
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, IgnoresFiltersWhenDiscoveryIsDisabled) {
+    auto_discover.Set("0");
+    filters.Set("mlx5_0,mlx5_1");
+
+    auto config = ClientAutoDiscoveryConfig::FromEnvironment("rdma", false);
+    config.LoadFiltersFromEnvironment();
+
+    EXPECT_TRUE(config.filters.empty());
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, DefersFilterReadUntilFiltersAreLoaded) {
+    auto_discover.Set("1");
+    filters.Set("before");
+    auto config = ClientAutoDiscoveryConfig::FromEnvironment("rdma", true);
+
+    filters.Set("after");
+    config.LoadFiltersFromEnvironment();
+
+    EXPECT_EQ(config.filters, (std::vector<std::string>{"after"}));
+}
+
+TEST_F(ClientAutoDiscoveryConfigTest, ReadsEnvironmentForEachConfig) {
+    auto_discover.Set("1");
+    filters.Set("first");
+    auto first = ClientAutoDiscoveryConfig::FromEnvironment("tcp", true);
+    first.LoadFiltersFromEnvironment();
+
+    auto_discover.Set("0");
+    filters.Set("second");
+    auto second = ClientAutoDiscoveryConfig::FromEnvironment("rdma", false);
+    second.LoadFiltersFromEnvironment();
+
+    EXPECT_TRUE(first.enabled);
+    EXPECT_EQ(first.filters, (std::vector<std::string>{"first"}));
+    EXPECT_FALSE(second.enabled);
+    EXPECT_TRUE(second.filters.empty());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/client_auto_port_config_test.cpp b/mooncake-store/tests/client_auto_port_config_test.cpp
new file mode 100644
index 0000000000..da37ece192
--- /dev/null
+++ b/mooncake-store/tests/client_auto_port_config_test.cpp
@@ -0,0 +1,143 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "client_auto_port_config.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct ClientAutoPortEnvironment {
+    ScopedEnvVar setup_retries{"MC_STORE_CLIENT_SETUP_RETRIES"};
+    ScopedEnvVar min_port{"MC_STORE_CLIENT_MIN_PORT"};
+    ScopedEnvVar max_port{"MC_STORE_CLIENT_MAX_PORT"};
+};
+
+class ClientAutoPortConfigTest : public ::testing::Test {
+   protected:
+    ClientAutoPortEnvironment env;
+};
+
+TEST_F(ClientAutoPortConfigTest, UsesExistingDefaultsWhenEnvironmentIsUnset) {
+    const auto config = ClientAutoPortConfig::FromEnvironment();
+
+    EXPECT_EQ(config.max_retries, 20);
+    EXPECT_EQ(config.min_port, 12300);
+    EXPECT_EQ(config.max_port, 14300);
+}
+
+TEST_F(ClientAutoPortConfigTest, ReadsValidValues) {
+    env.setup_retries.Set("7");
+    env.min_port.Set("12000");
+    env.max_port.Set("14000");
+
+    const auto config = ClientAutoPortConfig::FromEnvironment();
+
+    EXPECT_EQ(config.max_retries, 7);
+    EXPECT_EQ(config.min_port, 12000);
+    EXPECT_EQ(config.max_port, 14000);
+}
+
+TEST_F(ClientAutoPortConfigTest, InvalidIntegersUseIndividualFieldDefaults) {
+    for (const char* value : {"", "invalid", "2147483648"}) {
+        env.setup_retries.Set(value);
+        env.min_port.Set(value);
+        env.max_port.Set("15000");
+
+        auto config = ClientAutoPortConfig::FromEnvironment();
+
+        EXPECT_EQ(config.max_retries, 20) << value;
+        EXPECT_EQ(config.min_port, 12300) << value;
+        EXPECT_EQ(config.max_port, 15000) << value;
+
+        env.min_port.Set("13000");
+        env.max_port.Set(value);
+
+        config = ClientAutoPortConfig::FromEnvironment();
+
+        EXPECT_EQ(config.min_port, 13000) << value;
+        EXPECT_EQ(config.max_port, 14300) << value;
+    }
+}
+
+TEST_F(ClientAutoPortConfigTest, SupportsIndependentEndpointOverrides) {
+    env.min_port.Set("13000");
+
+    auto config = ClientAutoPortConfig::FromEnvironment();
+    EXPECT_EQ(config.min_port, 13000);
+    EXPECT_EQ(config.max_port, 14300);
+
+    env.min_port.Set("12300");
+    env.max_port.Set("15000");
+
+    config = ClientAutoPortConfig::FromEnvironment();
+    EXPECT_EQ(config.min_port, 12300);
+    EXPECT_EQ(config.max_port, 15000);
+}
+
+TEST_F(ClientAutoPortConfigTest, InvalidPortPairsRestoreBothDefaults) {
+    struct PortPair {
+        const char* min_port;
+        const char* max_port;
+    };
+    for (const auto& value :
+         {PortPair{"14301", "14300"}, PortPair{"80", "443"},
+          PortPair{"32768", "40000"}, PortPair{"61000", "65536"}}) {
+        env.min_port.Set(value.min_port);
+        env.max_port.Set(value.max_port);
+
+        const auto config = ClientAutoPortConfig::FromEnvironment();
+
+        EXPECT_EQ(config.min_port, 12300);
+        EXPECT_EQ(config.max_port, 14300);
+    }
+}
+
+TEST_F(ClientAutoPortConfigTest, PreservesNonPositiveRetryCounts) {
+    env.setup_retries.Set("0");
+    EXPECT_EQ(ClientAutoPortConfig::FromEnvironment().max_retries, 0);
+
+    env.setup_retries.Set("-1");
+    EXPECT_EQ(ClientAutoPortConfig::FromEnvironment().max_retries, -1);
+}
+
+TEST_F(ClientAutoPortConfigTest, PreservesAcceptedIntegerSyntax) {
+    env.setup_retries.Set(" +7 ");
+    env.min_port.Set(" +12000 ");
+    env.max_port.Set(" +14000 ");
+
+    const auto config = ClientAutoPortConfig::FromEnvironment();
+
+    EXPECT_EQ(config.max_retries, 7);
+    EXPECT_EQ(config.min_port, 12000);
+    EXPECT_EQ(config.max_port, 14000);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/client_buffer_test.cpp b/mooncake-store/tests/client_buffer_test.cpp
index d144f3c561..56b8445bb9 100644
--- a/mooncake-store/tests/client_buffer_test.cpp
+++ b/mooncake-store/tests/client_buffer_test.cpp
@@ -67,9 +67,9 @@ TEST_F(ClientBufferTest, SpdkDmaAllocatorDestroysWithSpdkFree) {
 
     std::shared_ptr<ClientBufferAllocator> allocator;
     try {
-        allocator = ClientBufferAllocator::create(
-            buffer_size, "tcp", /*use_hugepage=*/false,
-            /*use_spdk_dma=*/true);
+        allocator = ClientBufferAllocator::create(buffer_size, "tcp",
+                                                  /*use_hugepage=*/false,
+                                                  /*use_spdk_dma=*/true);
     } catch (const std::bad_alloc&) {
         GTEST_SKIP()
             << "SPDK DMA allocation is unavailable in this environment";
diff --git a/mooncake-store/tests/client_host_identity_config_test.cpp b/mooncake-store/tests/client_host_identity_config_test.cpp
new file mode 100644
index 0000000000..f6ccca5551
--- /dev/null
+++ b/mooncake-store/tests/client_host_identity_config_test.cpp
@@ -0,0 +1,121 @@
+#include "../src/config/client_host_identity_config.h"
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace mooncake {
+namespace {
+
+std::mutex environment_mutex;
+
+class ClientHostIdentityConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        environment_lock_ = std::unique_lock<std::mutex>(environment_mutex);
+        if (const char* value = std::getenv(kVariable)) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv(kVariable), 0);
+    }
+
+    void TearDown() override {
+        if (original_) {
+            EXPECT_EQ(setenv(kVariable, original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(kVariable), 0);
+        }
+    }
+
+    void Set(const char* value) { ASSERT_EQ(setenv(kVariable, value, 1), 0); }
+
+   private:
+    inline static constexpr char kVariable[] = "MOONCAKE_HOST_ID";
+    std::optional<std::string> original_;
+    std::unique_lock<std::mutex> environment_lock_;
+};
+
+TEST_F(ClientHostIdentityConfigTest, UsesLocalHostnameAndRejectsLoopback) {
+    EXPECT_EQ(ClientHostIdentityConfig::FromEnvironment("hostB:5000").host_id,
+              "hostB");
+    EXPECT_EQ(ClientHostIdentityConfig::FromEnvironment("hostB:5001").host_id,
+              "hostB");
+    EXPECT_EQ(
+        ClientHostIdentityConfig::FromEnvironment("[2001:db8::1]:5000").host_id,
+        "2001:db8::1");
+    EXPECT_TRUE(ClientHostIdentityConfig::FromEnvironment("localhost:5000")
+                    .host_id.empty());
+    EXPECT_TRUE(ClientHostIdentityConfig::FromEnvironment("127.0.0.1:5000")
+                    .host_id.empty());
+    EXPECT_TRUE(ClientHostIdentityConfig::FromEnvironment("0.0.0.0:5000")
+                    .host_id.empty());
+    EXPECT_TRUE(
+        ClientHostIdentityConfig::FromEnvironment("::1").host_id.empty());
+    EXPECT_TRUE(ClientHostIdentityConfig::FromEnvironment("[::1]:5000")
+                    .host_id.empty());
+    EXPECT_TRUE(
+        ClientHostIdentityConfig::FromEnvironment("::").host_id.empty());
+    EXPECT_TRUE(
+        ClientHostIdentityConfig::FromEnvironment("[::]").host_id.empty());
+    EXPECT_TRUE(
+        ClientHostIdentityConfig::FromEnvironment("[::]:5000").host_id.empty());
+}
+
+TEST_F(ClientHostIdentityConfigTest, PrefersDeploymentOverride) {
+    Set("  kubernetes-node-a  ");
+
+    EXPECT_EQ(
+        ClientHostIdentityConfig::FromEnvironment("10.244.1.17:5000").host_id,
+        "kubernetes-node-a");
+}
+
+TEST_F(ClientHostIdentityConfigTest, NormalizesEndpointOverride) {
+    Set("  kubernetes-node-a:5000  ");
+
+    EXPECT_EQ(
+        ClientHostIdentityConfig::FromEnvironment("10.244.1.17:5000").host_id,
+        "kubernetes-node-a");
+}
+
+TEST_F(ClientHostIdentityConfigTest, FallsBackForEmptyOverride) {
+    Set("");
+    EXPECT_EQ(ClientHostIdentityConfig::FromEnvironment("hostB:5000").host_id,
+              "hostB");
+
+    Set(" \t ");
+    EXPECT_EQ(ClientHostIdentityConfig::FromEnvironment("hostB:5000").host_id,
+              "hostB");
+}
+
+TEST_F(ClientHostIdentityConfigTest, RejectsInvalidOverrideWithoutFallback) {
+    const std::vector<const char*> invalid_host_ids = {
+        "localhost", "localhost:5000", "LOCALHOST",  "LoCaLhOsT:5000",
+        "127.0.0.1", "127.0.0.1:5000", "0.0.0.0",    "0.0.0.0:5000",
+        "::1",       "[::1]",          "[::1]:5000", "::",
+        "[::]",      "[::]:5000"};
+    for (const char* invalid_host_id : invalid_host_ids) {
+        SCOPED_TRACE(invalid_host_id);
+        Set(invalid_host_id);
+        EXPECT_TRUE(ClientHostIdentityConfig::FromEnvironment("hostB:5000")
+                        .host_id.empty());
+    }
+}
+
+TEST_F(ClientHostIdentityConfigTest, NewConfigsReadCurrentEnvironment) {
+    Set("host-a");
+    const auto first =
+        ClientHostIdentityConfig::FromEnvironment("fallback:5000");
+    Set("host-b");
+    const auto second =
+        ClientHostIdentityConfig::FromEnvironment("fallback:5000");
+
+    EXPECT_EQ(first.host_id, "host-a");
+    EXPECT_EQ(second.host_id, "host-b");
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/client_integration_test.cpp b/mooncake-store/tests/client_integration_test.cpp
index 6710096d87..774b786dae 100644
--- a/mooncake-store/tests/client_integration_test.cpp
+++ b/mooncake-store/tests/client_integration_test.cpp
@@ -20,8 +20,9 @@
 
 #include "allocator.h"
 #include "client_service.h"
+#include "real_client.h"
 #include "types.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 #include "test_server_helpers.h"
 #include "default_config.h"
 #include "crc_checksum.h"
@@ -568,6 +569,78 @@ TEST_F(ClientIntegrationTest, LocalPreferredAllocationTest) {
         << "Remove operation failed: " << toString(remove_result2.error());
 }
 
+TEST_F(ClientIntegrationTest, BatchWriteStagesActualNonLocalAllocation) {
+    size_t stage_calls = 0;
+    std::vector<std::pair<void*, size_t>> staged_allocations;
+    Client::WriteBufferStager stager = [&](const std::vector<Slice>& slices)
+        -> tl::expected<std::vector<Slice>, ErrorCode> {
+        size_t total_size = 0;
+        for (const auto& slice : slices) total_size += slice.size;
+        void* buffer = client_buffer_allocator_->allocate(total_size);
+        if (!buffer) return tl::unexpected(ErrorCode::NO_AVAILABLE_HANDLE);
+
+        std::vector<Slice> staged_slices;
+        size_t offset = 0;
+        for (const auto& slice : slices) {
+            std::memcpy(static_cast<char*>(buffer) + offset, slice.ptr,
+                        slice.size);
+            staged_slices.emplace_back(static_cast<char*>(buffer) + offset,
+                                       slice.size);
+            offset += slice.size;
+        }
+        staged_allocations.emplace_back(buffer, total_size);
+        ++stage_calls;
+        return staged_slices;
+    };
+    auto write = [&](const std::string& key, std::string& value,
+                     const ReplicateConfig& config, bool upsert) {
+        std::vector<std::string> keys{key};
+        std::vector<std::vector<Slice>> slices{{{value.data(), value.size()}}};
+        return upsert ? test_client_->BatchUpsert(keys, slices, config, stager)
+                      : test_client_->BatchPut(keys, slices, config, stager);
+    };
+
+    ReplicateConfig config;
+    config.preferred_segment = "localhost:17813";
+    size_t expected_stage_calls =
+        test_client_->CanUseLocalMemcpy(test_client_->GetTransportEndpoint())
+            ? 0
+            : 1;
+    std::string local_value = "local direct write";
+    auto local_result =
+        write("batch_write_actual_local", local_value, config, false);
+    ASSERT_TRUE(local_result[0]);
+    EXPECT_EQ(stage_calls, expected_stage_calls);
+
+    config.prefer_alloc_in_same_node = true;
+    config.preferred_segment = "localhost:17812";
+    std::string remote_value = "remote staged write";
+    auto remote_result =
+        write("batch_write_actual_remote", remote_value, config, false);
+    ASSERT_TRUE(remote_result[0]);
+    ++expected_stage_calls;
+    EXPECT_EQ(stage_calls, expected_stage_calls);
+    auto query = test_client_->Query("batch_write_actual_remote");
+    ASSERT_TRUE(query);
+    EXPECT_EQ(query->replicas[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_,
+              segment_provider_client_->GetTransportEndpoint());
+
+    remote_value = "remote staged upsert";
+    auto upsert_result =
+        write("batch_write_actual_remote", remote_value, config, true);
+    ASSERT_TRUE(upsert_result[0]);
+    ++expected_stage_calls;
+    EXPECT_EQ(stage_calls, expected_stage_calls);
+
+    EXPECT_TRUE(test_client_->Remove("batch_write_actual_local", true));
+    EXPECT_TRUE(test_client_->Remove("batch_write_actual_remote", true));
+    for (const auto& [ptr, size] : staged_allocations) {
+        client_buffer_allocator_->deallocate(ptr, size);
+    }
+}
+
 // Test heavy workload operations
 TEST_F(ClientIntegrationTest, DISABLED_AllocateTest) {
     const size_t data_size = 1 * 1024 * 1024;  // 1MB
@@ -784,6 +857,111 @@ TEST_F(ClientIntegrationTest, BatchPutGetOperations) {
     }
 }
 
+TEST_F(ClientIntegrationTest, BatchGetChecksLeasesWithPreferredNode) {
+    const std::vector<std::string> keys = {"batch_lease_expired",
+                                           "batch_lease_live",
+                                           "batch_lease_missing_slices"};
+    const std::string value = "batch read lease regression";
+    const size_t buffer_size = value.size() * 3;
+    void* buffer = client_buffer_allocator_->allocate(buffer_size);
+    ASSERT_NE(buffer, nullptr);
+    auto release_buffer = [buffer_size](void* ptr) {
+        client_buffer_allocator_->deallocate(ptr, buffer_size);
+    };
+    std::unique_ptr<void, decltype(release_buffer)> buffer_owner(
+        buffer, release_buffer);
+    memcpy(buffer, value.data(), value.size());
+    std::vector<Slice> source{{buffer, value.size()}};
+    ReplicateConfig config;
+    config.replica_num = 1;
+    // Keep both readable keys in the same transfer batch.
+    config.preferred_segment = "localhost:17812";
+    for (const auto& key : keys) {
+        ASSERT_TRUE(test_client_->Put(key, source, config).has_value());
+    }
+
+    const auto queries = test_client_->BatchQuery(keys);
+    ASSERT_EQ(queries.size(), keys.size());
+    std::vector<QueryResult> query_results;
+    const auto now = std::chrono::steady_clock::now();
+    for (size_t i = 0; i < queries.size(); ++i) {
+        ASSERT_TRUE(queries[i].has_value());
+        ASSERT_EQ(queries[i]->replicas.size(), 1);
+        ASSERT_TRUE(queries[i]->replicas[0].is_memory_replica());
+        auto replicas = queries[i]->replicas;
+        // Use an explicit expired deadline instead of relying on a slow
+        // transfer or sleeping until the master's lease expires.
+        query_results.emplace_back(std::move(replicas),
+                                   i == 1 ? now + std::chrono::minutes(1)
+                                          : now - std::chrono::seconds(1),
+                                   queries[i]->object_checksum);
+    }
+    EXPECT_EQ(queries[0]
+                  ->replicas[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_,
+              queries[1]
+                  ->replicas[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_);
+    auto* expired_dst = static_cast<char*>(buffer) + value.size();
+    auto* live_dst = expired_dst + value.size();
+    std::unordered_map<std::string, std::vector<Slice>> destinations{
+        {keys[0], {{expired_dst, value.size()}}},
+        {keys[1], {{live_dst, value.size()}}}};
+
+    // Both public BatchGet modes must apply the same per-key lease contract.
+    for (bool prefer_same_node : {false, true}) {
+        SCOPED_TRACE(prefer_same_node);
+        memset(expired_dst, 0, value.size() * 2);
+        const auto results = test_client_->BatchGet(
+            keys, query_results, destinations, prefer_same_node);
+        ASSERT_EQ(results.size(), keys.size());
+        ASSERT_FALSE(results[0].has_value());
+        EXPECT_EQ(results[0].error(), ErrorCode::LEASE_EXPIRED);
+        EXPECT_TRUE(results[1].has_value());
+        ASSERT_FALSE(results[2].has_value());
+        EXPECT_EQ(results[2].error(), ErrorCode::INVALID_PARAMS);
+        // The expired item completed its transfer too; it must still not be
+        // reported as a successful read once its lease has expired.
+        EXPECT_EQ(memcmp(expired_dst, value.data(), value.size()), 0);
+        EXPECT_EQ(memcmp(live_dst, value.data(), value.size()), 0);
+    }
+}
+
+TEST_F(ClientIntegrationTest, BatchGetPreservesTransferErrorWithExpiredLease) {
+    const std::string key = "batch_lease_transfer_failure";
+    const std::string value = "batch read transfer error";
+    void* buffer = client_buffer_allocator_->allocate(value.size());
+    ASSERT_NE(buffer, nullptr);
+    auto release_buffer = [&value](void* ptr) {
+        client_buffer_allocator_->deallocate(ptr, value.size());
+    };
+    std::unique_ptr<void, decltype(release_buffer)> buffer_owner(
+        buffer, release_buffer);
+    memcpy(buffer, value.data(), value.size());
+    std::vector<Slice> source{{buffer, value.size()}};
+    ASSERT_TRUE(test_client_->Put(key, source, ReplicateConfig{}).has_value());
+    const auto query = test_client_->Query(key);
+    ASSERT_TRUE(query.has_value());
+    auto replicas = query->replicas;
+    const std::vector<QueryResult> query_results{
+        QueryResult(std::move(replicas),
+                    std::chrono::steady_clock::now() - std::chrono::seconds(1),
+                    query->object_checksum)};
+    // Invalid transfer length fails submission before any bytes are copied.
+    std::unordered_map<std::string, std::vector<Slice>> destinations{
+        {key, {{buffer, value.size() - 1}}}};
+    for (bool prefer_same_node : {false, true}) {
+        SCOPED_TRACE(prefer_same_node);
+        const auto results = test_client_->BatchGet(
+            {key}, query_results, destinations, prefer_same_node);
+        ASSERT_EQ(results.size(), 1);
+        ASSERT_FALSE(results[0].has_value());
+        EXPECT_EQ(results[0].error(), ErrorCode::TRANSFER_FAIL);
+    }
+}
+
 TEST_F(ClientIntegrationTest, BatchPutMixedGroupIdsThroughClient) {
     auto find_group_id_on_different_shard = [](const std::string& key) {
         static constexpr size_t kMetadataShardCountForTest = 1024;
@@ -1083,6 +1261,77 @@ TEST_F(ClientIntegrationTest, BatchPutDuplicateKeys) {
     ASSERT_TRUE(remove_result);
 }
 
+// Regression test for duplicate keys in a batch read (#3876): the
+// destinations used to collapse onto one buffer, returning the first
+// occurrence's unwritten memory as success. Every duplicate must come back
+// with a copy of the object bytes.
+TEST_F(ClientIntegrationTest, BatchGetDuplicateKeysFanOut) {
+    auto real_client = RealClient::create();
+    const std::string rdma_devices =
+        (FLAGS_protocol == "rdma") ? FLAGS_device_name : "";
+    ASSERT_EQ(real_client->setup_real("localhost:17913", "P2PHANDSHAKE", 0,
+                                      64 * 1024 * 1024, FLAGS_protocol,
+                                      rdma_devices, master_address_),
+              0);
+
+    const std::string key = "test_key_batch_get_duplicate_keys";
+    const size_t obj_size = 4096;
+    std::string test_data(obj_size, '\0');
+    for (size_t i = 0; i < obj_size; ++i) {
+        test_data[i] = static_cast<char>(((i * 131 + 7) & 0x7f) | 0x01);
+    }
+
+    void* put_buffer = client_buffer_allocator_->allocate(obj_size);
+    memcpy(put_buffer, test_data.data(), obj_size);
+    std::vector<Slice> put_slices{Slice{put_buffer, obj_size}};
+    ReplicateConfig config;
+    config.replica_num = 1;
+    auto put_result = test_client_->Put(key, put_slices, config);
+    ASSERT_TRUE(put_result.has_value())
+        << "Put failed: " << toString(put_result.error());
+    client_buffer_allocator_->deallocate(put_buffer, obj_size);
+
+    const std::vector<std::string> dup_keys = {key, key};
+
+    // Caller-buffer variant (batch_get_into): poison the first destination;
+    // it must still come back with the object bytes.
+    void* first = malloc(obj_size);
+    void* second = malloc(obj_size);
+    ASSERT_TRUE(first != nullptr && second != nullptr);
+    ASSERT_EQ(real_client->register_buffer(first, obj_size), 0);
+    ASSERT_EQ(real_client->register_buffer(second, obj_size), 0);
+    memset(first, 0xAA, obj_size);
+    memset(second, 0xBB, obj_size);
+    std::vector<void*> dst_buffers = {first, second};
+    std::vector<size_t> dst_sizes = {obj_size, obj_size};
+    auto into_results =
+        real_client->batch_get_into(dup_keys, dst_buffers, dst_sizes);
+    ASSERT_EQ(into_results.size(), 2);
+    EXPECT_EQ(into_results[0], static_cast<int64_t>(obj_size));
+    EXPECT_EQ(into_results[1], static_cast<int64_t>(obj_size));
+    EXPECT_EQ(memcmp(first, test_data.data(), obj_size), 0)
+        << "first duplicate buffer was left unwritten";
+    EXPECT_EQ(memcmp(second, test_data.data(), obj_size), 0)
+        << "second duplicate buffer was left unwritten";
+    real_client->unregister_buffer(first);
+    real_client->unregister_buffer(second);
+    free(first);
+    free(second);
+
+    // Allocated-buffer variant (batch_get_buffer, the Python get_batch
+    // entry): both handles must carry the object bytes.
+    auto handles = real_client->batch_get_buffer(dup_keys);
+    ASSERT_EQ(handles.size(), 2);
+    ASSERT_NE(handles[0], nullptr);
+    ASSERT_NE(handles[1], nullptr);
+    EXPECT_EQ(handles[0]->size(), obj_size);
+    EXPECT_EQ(handles[1]->size(), obj_size);
+    EXPECT_EQ(memcmp(handles[0]->ptr(), test_data.data(), obj_size), 0)
+        << "first duplicate handle was left unwritten";
+    EXPECT_EQ(memcmp(handles[1]->ptr(), test_data.data(), obj_size), 0)
+        << "second duplicate handle was left unwritten";
+}
+
 // Test BatchReplicaClear operations through the client
 TEST_F(ClientIntegrationTest, BatchReplicaClearOperations) {
     // Skip test if we couldn't capture client_id
diff --git a/mooncake-store/tests/client_liveness_test.cpp b/mooncake-store/tests/client_liveness_test.cpp
new file mode 100644
index 0000000000..0b1dd620d3
--- /dev/null
+++ b/mooncake-store/tests/client_liveness_test.cpp
@@ -0,0 +1,117 @@
+#include "client_liveness.h"
+
+#include <chrono>
+#include <condition_variable>
+#include <mutex>
+#include <thread>
+
+#include <gtest/gtest.h>
+
+namespace mooncake::test {
+namespace {
+
+using namespace std::chrono_literals;
+
+TEST(ClientLivenessRecordTest, SuspicionWindowStartsAtActualTransition) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    ClientLivenessRecord record(initial);
+
+    EXPECT_EQ(record.Evaluate(initial + 30s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    EXPECT_EQ(record.state(), ClientLivenessState::SUSPECTED);
+    EXPECT_EQ(record.Evaluate(initial + 49s, 10s, 20s),
+              ClientLivenessTransition::NONE);
+    EXPECT_EQ(record.Evaluate(initial + 50s, 10s, 20s),
+              ClientLivenessTransition::BECAME_OFFLINE);
+}
+
+TEST(ClientLivenessRecordTest, ObservationRecoversSuspectedButNotOffline) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    ClientLivenessRecord record(initial);
+
+    ASSERT_EQ(record.Evaluate(initial + 10s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    EXPECT_EQ(record.Observe(initial + 11s),
+              ClientLivenessObservation::RECOVERED_ACTIVE);
+    EXPECT_TRUE(record.IsServing());
+
+    ASSERT_EQ(record.Evaluate(initial + 21s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    ASSERT_EQ(record.Evaluate(initial + 41s, 10s, 20s),
+              ClientLivenessTransition::BECAME_OFFLINE);
+    EXPECT_EQ(record.Observe(initial + 42s),
+              ClientLivenessObservation::REJECTED_OFFLINE);
+    EXPECT_FALSE(record.ShouldRetainResources());
+}
+
+TEST(ClientLivenessRecordTest, FailedOperationDoesNotRecoverOrRefresh) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    ClientLivenessRecord record(initial);
+
+    ASSERT_EQ(record.Evaluate(initial + 10s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    EXPECT_EQ(record.ObserveAndRun(initial + 11s, [] { return false; }),
+              ClientLivenessObservation::OBSERVATION_WITHHELD);
+    EXPECT_EQ(record.state(), ClientLivenessState::SUSPECTED);
+    EXPECT_EQ(record.Evaluate(initial + 30s, 10s, 20s),
+              ClientLivenessTransition::BECAME_OFFLINE);
+}
+
+TEST(ClientLivenessRecordTest, RetireCallbackRunsAfterTransitionGuardRelease) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    ClientLivenessRecord record(initial);
+    ASSERT_EQ(record.Evaluate(initial + 10s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+
+    std::mutex completion_mutex;
+    std::condition_variable completion_cv;
+    bool completed = false;
+    bool rejected_offline = false;
+    std::thread probe;
+
+    EXPECT_EQ(
+        record.EvaluateAndRetire(
+            initial + 30s, 10s, 20s,
+            [&] {
+                probe = std::thread([&] {
+                    rejected_offline =
+                        !record.TryAcquireRetainingGuard().has_value();
+                    {
+                        std::lock_guard<std::mutex> lock(completion_mutex);
+                        completed = true;
+                    }
+                    completion_cv.notify_one();
+                });
+
+                std::unique_lock<std::mutex> lock(completion_mutex);
+                EXPECT_TRUE(completion_cv.wait_for(lock, 1s,
+                                                   [&] { return completed; }));
+            }),
+        ClientLivenessTransition::BECAME_OFFLINE);
+
+    probe.join();
+    EXPECT_TRUE(rejected_offline);
+}
+
+TEST(ClientLivenessRecordTest, RetirementIsReservedBeforeOfflineIsPublished) {
+    const auto initial = ClientLivenessRecord::TimePoint{};
+    ClientLivenessRecord record(initial);
+    ASSERT_EQ(record.Evaluate(initial + 10s, 10s, 20s),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+
+    bool reserved = false;
+    EXPECT_EQ(record.EvaluateAndRetire(
+                  initial + 30s, 10s, 20s,
+                  [&] {
+                      EXPECT_EQ(record.state(), ClientLivenessState::SUSPECTED);
+                      reserved = true;
+                  },
+                  [&] {
+                      EXPECT_TRUE(reserved);
+                      EXPECT_EQ(record.state(), ClientLivenessState::OFFLINE);
+                  }),
+              ClientLivenessTransition::BECAME_OFFLINE);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/client_local_hot_cache_test.cpp b/mooncake-store/tests/client_local_hot_cache_test.cpp
index 70fbf7c162..1b87cd7616 100644
--- a/mooncake-store/tests/client_local_hot_cache_test.cpp
+++ b/mooncake-store/tests/client_local_hot_cache_test.cpp
@@ -1,11 +1,11 @@
 // client_local_hot_cache_test.cpp
 #include "client_service.h"
 #include "client_buffer.h"
+#include "common/client_buffer_allocation.h"
 #include "count_min_sketch.h"
 #include "local_hot_cache.h"
 #include "replica.h"
 #include "test_server_helpers.h"
-#include "utils.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
diff --git a/mooncake-store/tests/client_metric_config_test.cpp b/mooncake-store/tests/client_metric_config_test.cpp
new file mode 100644
index 0000000000..c6d426a166
--- /dev/null
+++ b/mooncake-store/tests/client_metric_config_test.cpp
@@ -0,0 +1,162 @@
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "client_metric.h"
+#include "environment_variables.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        const char* value = std::getenv(name);
+        if (value != nullptr) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct ClientMetricEnvironment {
+    using Variables = ClientMetricEnvironmentVariables;
+
+    ScopedEnvVar enabled{Variables::MC_STORE_CLIENT_METRIC.name};
+    ScopedEnvVar interval{Variables::MC_STORE_CLIENT_METRIC_INTERVAL.name};
+    ScopedEnvVar bandwidth{Variables::MC_STORE_CLIENT_METRIC_BANDWIDTH.name};
+};
+
+class ClientMetricConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging("ClientMetricConfigTest");
+        FLAGS_logtostderr = true;
+    }
+
+    void TearDown() override { google::ShutdownGoogleLogging(); }
+
+    ClientMetricEnvironment env;
+};
+
+TEST_F(ClientMetricConfigTest, UsesDefaultsWhenEnvironmentIsUnset) {
+    const auto config = ClientMetricConfig::FromEnvironment();
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.reporting_interval, std::chrono::milliseconds::zero());
+    EXPECT_TRUE(config.bandwidth_reporting_enabled);
+}
+
+TEST_F(ClientMetricConfigTest, ReadsValidEnvironmentValues) {
+    env.enabled.Set("true");
+    env.interval.Set(" +15 ");
+    env.bandwidth.Set("false");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = ClientMetricConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.reporting_interval, std::chrono::seconds(15));
+    EXPECT_FALSE(config.bandwidth_reporting_enabled);
+    EXPECT_NE(logs.find("Client metrics interval set to 15s via "
+                        "MC_STORE_CLIENT_METRIC_INTERVAL"),
+              std::string::npos);
+}
+
+TEST_F(ClientMetricConfigTest, InvalidEnableValueSilentlyDisablesMetrics) {
+    env.enabled.Set("invalid");
+    env.interval.Set("invalid");
+    env.bandwidth.Set("invalid");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = ClientMetricConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(config.reporting_interval, std::chrono::milliseconds::zero());
+    EXPECT_TRUE(config.bandwidth_reporting_enabled);
+    EXPECT_EQ(logs.find("MC_STORE_CLIENT_METRIC_INTERVAL"), std::string::npos);
+    EXPECT_EQ(logs.find("MC_STORE_CLIENT_METRIC_BANDWIDTH"), std::string::npos);
+}
+
+TEST_F(ClientMetricConfigTest, EmptyEnableValueSilentlyDisablesMetrics) {
+    env.enabled.Set("");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = ClientMetricConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.enabled);
+    EXPECT_TRUE(logs.empty());
+}
+
+TEST_F(ClientMetricConfigTest, InvalidIntervalValuesUseDefaultAndWarn) {
+    for (const char* value : {"invalid", "-1", "18446744073709551616", ""}) {
+        SCOPED_TRACE(value);
+        env.interval.Set(value);
+
+        ::testing::internal::CaptureStderr();
+        const auto config = ClientMetricConfig::FromEnvironment();
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.reporting_interval, std::chrono::milliseconds::zero());
+        EXPECT_NE(logs.find("Failed to parse "
+                            "MC_STORE_CLIENT_METRIC_INTERVAL"),
+                  std::string::npos);
+    }
+}
+
+TEST_F(ClientMetricConfigTest, InvalidBandwidthValuesUseDefaultAndWarn) {
+    for (const char* value : {"invalid", ""}) {
+        SCOPED_TRACE(value);
+        env.bandwidth.Set(value);
+
+        ::testing::internal::CaptureStderr();
+        const auto config = ClientMetricConfig::FromEnvironment();
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_TRUE(config.bandwidth_reporting_enabled);
+        EXPECT_NE(logs.find("Failed to parse "
+                            "MC_STORE_CLIENT_METRIC_BANDWIDTH"),
+                  std::string::npos);
+    }
+}
+
+TEST_F(ClientMetricConfigTest, ZeroIntervalRemainsEnabled) {
+    env.interval.Set("0");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = ClientMetricConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.reporting_interval, std::chrono::milliseconds::zero());
+    EXPECT_NE(logs.find("Client metrics reporting disabled (interval=0) via "
+                        "MC_STORE_CLIENT_METRIC_INTERVAL"),
+              std::string::npos);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/client_metrics_test.cpp b/mooncake-store/tests/client_metrics_test.cpp
index 1f23bc0059..17b2b093bb 100644
--- a/mooncake-store/tests/client_metrics_test.cpp
+++ b/mooncake-store/tests/client_metrics_test.cpp
@@ -3,17 +3,22 @@
 
 // csignal must precede coro_http_client.hpp: the bundled ylt's coro_io.hpp
 // calls std::signal without including <csignal> itself.
+#include <chrono>
 #include <csignal>
 #include <cstdlib>
 #include <optional>
+#include <sstream>
 #include <string>
+#include <thread>
 #include <unordered_set>
 #include <ylt/coro_http/coro_http_client.hpp>
 
 #include "client_metric.h"
+#include "common/network.h"
+#include "environment_variables.h"
 #include "real_client.h"
 #include "test_server_helpers.h"
-#include "utils.h"
+#include "version.h"
 
 namespace mooncake::test {
 namespace {
@@ -40,6 +45,18 @@ int GetTestPort(std::unordered_set<int>& used_ports) {
     return -1;
 }
 
+size_t CountOccurrences(const std::string& text, const std::string& needle) {
+    if (needle.empty()) return 0;
+
+    size_t count = 0;
+    size_t position = 0;
+    while ((position = text.find(needle, position)) != std::string::npos) {
+        ++count;
+        position += needle.size();
+    }
+    return count;
+}
+
 class ScopedEnv {
    public:
     explicit ScopedEnv(const char* name) : name_(name) {
@@ -62,9 +79,10 @@ class ScopedEnv {
 
 tl::expected<void, ErrorCode> SetupClientWithHttp(
     const std::shared_ptr<RealClient>& client, const std::string& client_addr,
-    const std::string& master_addr, bool enable_http, int http_port) {
+    const std::string& master_addr, bool enable_http, int http_port,
+    size_t global_segment_size = 0) {
     return client->setup_internal(
-        client_addr, "P2PHANDSHAKE", /*global_segment_size=*/0,
+        client_addr, "P2PHANDSHAKE", global_segment_size,
         /*local_buffer_size=*/0, "tcp", "", master_addr, nullptr, "",
         /*local_rpc_port=*/50052, /*enable_ssd_offload=*/false,
         /*start_offload_rpc_server=*/false, /*ssd_offload_path=*/"",
@@ -193,6 +211,10 @@ TEST_F(ClientMetricsTest, ClientMetricsSummaryTest) {
     EXPECT_TRUE(summary.find("ExistKey: count=1") != std::string::npos);
     EXPECT_TRUE(summary.find("get_buffer: count=1") != std::string::npos);
     EXPECT_TRUE(summary.find("put_batch: count=1") != std::string::npos);
+    // The build is named inline so the summary alone identifies the binary.
+    EXPECT_TRUE(summary.find("Version: " + GetMooncakeStoreVersion()) !=
+                std::string::npos);
+    EXPECT_TRUE(summary.find(MOONCAKE_DISPLAY_VERSION) != std::string::npos);
 
     std::cout << "Full Client Metrics Summary:\n" << summary << std::endl;
 }
@@ -250,16 +272,47 @@ TEST_F(ClientMetricsTest, CompareWithSerializedMetrics) {
                 summary.find("No data") != std::string::npos);
 }
 
+TEST_F(ClientMetricsTest, HybridHistogramSerializesEachLabelOnce) {
+    ylt::metric::hybrid_histogram_1t histogram(
+        "request_latency", "Request latency", {10.0, 20.0}, {}, {"route"});
+    histogram.observe({"alpha"}, 5);
+    histogram.observe({"beta"}, 15);
+
+    std::string serialized;
+    histogram.serialize(serialized);
+
+    EXPECT_EQ(
+        CountOccurrences(serialized, "request_latency_bucket{route=\"alpha\","),
+        3);
+    EXPECT_EQ(
+        CountOccurrences(serialized, "request_latency_bucket{route=\"beta\","),
+        3);
+}
+
+TEST_F(ClientMetricsTest, ZeroSumHybridHistogramPreservesExistingMetrics) {
+    ylt::metric::hybrid_histogram_1t histogram(
+        "request_latency", "Request latency", {10.0}, {}, {"route"});
+    histogram.observe({"idle"}, 0);
+    std::string serialized = "existing_metric 1\n";
+
+    histogram.serialize(serialized);
+
+    EXPECT_EQ(serialized, "existing_metric 1\n");
+}
+
 TEST_F(ClientMetricsTest, BandwidthSummaryRespectsEnvFlag) {
-    setenv("MC_STORE_CLIENT_METRIC_BANDWIDTH", "0", 1);
+    ScopedEnv bandwidth_env(
+        ClientMetricEnvironmentVariables::MC_STORE_CLIENT_METRIC_BANDWIDTH
+            .name);
+    setenv(
+        ClientMetricEnvironmentVariables::MC_STORE_CLIENT_METRIC_BANDWIDTH.name,
+        "0", 1);
     auto metrics = ClientMetric::Create();
     ASSERT_NE(metrics, nullptr);
 
     metrics->transfer_metric.total_read_bytes.inc(1024);
     std::string summary = metrics->summary_metrics();
     EXPECT_TRUE(summary.find("Average Read Throughput:") == std::string::npos);
-
-    unsetenv("MC_STORE_CLIENT_METRIC_BANDWIDTH");
 }
 
 TEST_F(ClientMetricsTest, SummaryCanOmitMasterRpcMetrics) {
@@ -369,6 +422,62 @@ TEST_F(ClientMetricsTest, SerializeWithoutDynamicLabels) {
     }
 }
 
+TEST_F(ClientMetricsTest, BuildInfoMetricIsSerialized) {
+    ClientMetric metrics(0);
+
+    std::string serialized;
+    metrics.serialize(serialized);
+
+    ASSERT_NE(serialized.find("mooncake_build_info{"), std::string::npos)
+        << "build info metric missing from serialized output";
+    // Label order inside the series is not asserted: only the presence of both
+    // labels with the compiled-in values matters for scraping and grouping.
+    EXPECT_NE(serialized.find("version=\"" + GetMooncakeStoreVersion() + "\""),
+              std::string::npos)
+        << "RPC handshake version missing from build info labels";
+    EXPECT_NE(serialized.find("display_version=\"" +
+                              std::string(MOONCAKE_DISPLAY_VERSION) + "\""),
+              std::string::npos)
+        << "display version missing from build info labels";
+
+    // Info-style metric: the value is fixed at 1, so exactly one series is
+    // emitted and its value follows the closing brace of the label set.
+    EXPECT_EQ(CountOccurrences(serialized, "mooncake_build_info{"), 1u);
+    const auto metric_pos = serialized.find("mooncake_build_info{");
+    const auto brace_end = serialized.find('}', metric_pos);
+    ASSERT_NE(brace_end, std::string::npos);
+    const auto line_end = serialized.find('\n', brace_end);
+    const std::string value_part =
+        serialized.substr(brace_end + 1, line_end == std::string::npos
+                                             ? std::string::npos
+                                             : line_end - brace_end - 1);
+    EXPECT_NE(value_part.find('1'), std::string::npos)
+        << "build info value should be 1, got:" << value_part;
+}
+
+TEST_F(ClientMetricsTest, BuildInfoMetricKeepsCallerLabels) {
+    // Caller supplied labels identify the instance; the version labels are
+    // added on top of them rather than replacing them.
+    std::map<std::string, std::string> static_labels = {
+        {"instance_id", "12345"}, {"cluster_id", "cluster1"}};
+    ClientMetric metrics(0, static_labels);
+
+    std::string serialized;
+    metrics.serialize(serialized);
+
+    const auto metric_pos = serialized.find("mooncake_build_info{");
+    ASSERT_NE(metric_pos, std::string::npos);
+    const auto brace_end = serialized.find('}', metric_pos);
+    ASSERT_NE(brace_end, std::string::npos);
+    const std::string labels =
+        serialized.substr(metric_pos, brace_end - metric_pos);
+
+    EXPECT_NE(labels.find("instance_id=\"12345\""), std::string::npos);
+    EXPECT_NE(labels.find("cluster_id=\"cluster1\""), std::string::npos);
+    EXPECT_NE(labels.find("version=\"" + GetMooncakeStoreVersion() + "\""),
+              std::string::npos);
+}
+
 TEST_F(ClientMetricsTest, HttpMetricsEndpointsReturnData) {
     std::unordered_set<int> used_ports;
     int master_rpc_port = GetTestPort(used_ports);
@@ -397,6 +506,13 @@ TEST_F(ClientMetricsTest, HttpMetricsEndpointsReturnData) {
         FetchUrl("http://127.0.0.1:" + std::to_string(http_port) + "/metrics");
     EXPECT_EQ(metrics.status, 200);
     EXPECT_EQ(metrics.body.find("metrics not available"), std::string::npos);
+    // A request-only client does not start the storage heartbeat.
+    EXPECT_EQ(metrics.body.find("mooncake_client_master_heartbeat_status_ok"),
+              std::string::npos);
+    EXPECT_EQ(
+        metrics.body.find(
+            "mooncake_client_master_heartbeat_observation_timestamp_seconds"),
+        std::string::npos);
 
     auto summary = FetchUrl("http://127.0.0.1:" + std::to_string(http_port) +
                             "/metrics/summary");
@@ -406,6 +522,97 @@ TEST_F(ClientMetricsTest, HttpMetricsEndpointsReturnData) {
     EXPECT_EQ(client->tearDownAll(), 0);
 }
 
+TEST_F(ClientMetricsTest, HeartbeatObservationsUseClientMetricLabels) {
+    ClientMetric metrics(
+        0, {{"cluster_id", "cluster1"}, {"instance_id", "12345"}});
+    auto& heartbeat = metrics.master_heartbeat_metric;
+    heartbeat.EndConnection(heartbeat.BeginConnection(), true);
+    heartbeat.Observe(heartbeat.BeginObservation(), false, 100.5);
+    std::string serialized;
+    metrics.serialize(serialized);
+    const std::string labels =
+        "{cluster_id=\"cluster1\",instance_id=\"12345\"}";
+    EXPECT_NE(serialized.find("mooncake_client_master_heartbeat_status_ok" +
+                              labels + " 0\n"),
+              std::string::npos);
+    EXPECT_NE(
+        serialized.find(
+            "mooncake_client_master_heartbeat_observation_timestamp_seconds" +
+            labels + " 100.500000\n"),
+        std::string::npos);
+}
+
+TEST_F(ClientMetricsTest, HttpHeartbeatMetricsRecoverAfterMasterRestart) {
+    ScopedEnv timeout("MC_RPC_TIMEOUT_MS");
+    setenv("MC_RPC_TIMEOUT_MS", "200", 1);
+    mooncake::testing::InProcMaster master;
+    ASSERT_TRUE(master.Start(mooncake::InProcMasterConfigBuilder()
+                                 .set_http_metadata_port(0)
+                                 .build()));
+    std::unordered_set<int> used_ports;
+    const int http_port = GetTestPort(used_ports);
+    const int client_port = GetTestPort(used_ports);
+    ASSERT_GT(http_port, 0);
+    ASSERT_GT(client_port, 0);
+    auto client = RealClient::create();
+    auto setup_result = SetupClientWithHttp(
+        client, "127.0.0.1:" + std::to_string(client_port),
+        master.master_address(), true, http_port, 16 * 1024 * 1024);
+    ASSERT_TRUE(setup_result.has_value()) << toString(setup_result.error());
+
+    const std::string url =
+        "http://127.0.0.1:" + std::to_string(http_port) + "/metrics";
+    const std::string status_name =
+        "mooncake_client_master_heartbeat_status_ok";
+    const std::string timestamp_name =
+        "mooncake_client_master_heartbeat_observation_timestamp_seconds";
+    auto sample = [](const std::string& body, const std::string& name) {
+        std::istringstream lines(body);
+        std::string line;
+        while (std::getline(lines, line)) {
+            if (line.starts_with(name + "{") || line.starts_with(name + " "))
+                return line;
+        }
+        return std::string{};
+    };
+    HttpResponse response;
+    auto wait_for = [&](bool known) {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(15);
+        do {
+            response = FetchUrl(url);
+            if (response.status == 200) {
+                const auto status = sample(response.body, status_name);
+                const auto timestamp = sample(response.body, timestamp_name);
+                if (known ? (status.ends_with(" 1") && !timestamp.empty())
+                          : (status.empty() && timestamp.empty()))
+                    return true;
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(50));
+        } while (std::chrono::steady_clock::now() < deadline);
+        return false;
+    };
+
+    ASSERT_TRUE(wait_for(true)) << response.body;
+    EXPECT_NE(sample(response.body, status_name).find("client_mode=\"real\""),
+              std::string::npos);
+    const auto before = std::stod(
+        sample(response.body, timestamp_name)
+            .substr(sample(response.body, timestamp_name).rfind(' ') + 1));
+    master.Stop();
+    ASSERT_TRUE(wait_for(false)) << response.body;
+    ASSERT_TRUE(
+        master.Start(mooncake::InProcMasterConfigBuilder()
+                         .set_rpc_port(master.rpc_port())
+                         .set_http_metrics_port(master.http_metrics_port())
+                         .set_http_metadata_port(0)
+                         .build()));
+    ASSERT_TRUE(wait_for(true)) << response.body;
+    const auto timestamp = sample(response.body, timestamp_name);
+    EXPECT_GT(std::stod(timestamp.substr(timestamp.rfind(' ') + 1)), before);
+    EXPECT_EQ(client->tearDownAll(), 0);
+}
+
 TEST_F(ClientMetricsTest, HttpMetricsConfigParserTrimsWhitespace) {
     std::unordered_set<int> used_ports;
     int master_rpc_port = GetTestPort(used_ports);
@@ -504,6 +711,16 @@ TEST_F(ClientMetricsTest, HttpMetricsEndpointReturns503WhenMetricsDisabled) {
     EXPECT_EQ(metrics.status, 503);
     EXPECT_NE(metrics.body.find("metrics not available"), std::string::npos);
 
+    // `/version` is served without touching the metric collector, so disabling
+    // metrics must not take it down along with `/metrics`.
+    auto version =
+        FetchUrl("http://127.0.0.1:" + std::to_string(http_port) + "/version");
+    EXPECT_EQ(version.status, 200);
+    EXPECT_NE(
+        version.body.find("\"version\":\"" + GetMooncakeStoreVersion() + "\""),
+        std::string::npos);
+    EXPECT_NE(version.body.find("display_version"), std::string::npos);
+
     EXPECT_EQ(client->tearDownAll(), 0);
 }
 
diff --git a/mooncake-store/tests/client_numa_config_test.cpp b/mooncake-store/tests/client_numa_config_test.cpp
new file mode 100644
index 0000000000..875ad4365e
--- /dev/null
+++ b/mooncake-store/tests/client_numa_config_test.cpp
@@ -0,0 +1,97 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "../src/config/client_numa_config.h"
+
+namespace mooncake {
+namespace {
+
+class ClientNumaConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv(kEnvironmentVariable)) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv(kEnvironmentVariable), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv(kEnvironmentVariable, original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(kEnvironmentVariable), 0);
+        }
+    }
+
+    void Set(const char* value) {
+        ASSERT_EQ(setenv(kEnvironmentVariable, value, 1), 0);
+    }
+
+    static constexpr const char* kEnvironmentVariable =
+        "MC_STORE_NUMA_SOCKET_ID";
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST_F(ClientNumaConfigTest, UnsetAndEmptyUseAutoDetectionWithoutWarning) {
+    ::testing::internal::CaptureStderr();
+    EXPECT_FALSE(ClientNumaConfig::FromEnvironment().socket_id.has_value());
+    EXPECT_TRUE(::testing::internal::GetCapturedStderr().empty());
+
+    Set("");
+    ::testing::internal::CaptureStderr();
+    EXPECT_FALSE(ClientNumaConfig::FromEnvironment().socket_id.has_value());
+    EXPECT_TRUE(::testing::internal::GetCapturedStderr().empty());
+}
+
+TEST_F(ClientNumaConfigTest, PreservesAcceptedDecimalSyntax) {
+    struct Case {
+        const char* value;
+        int expected;
+    };
+    const Case cases[] = {{"0", 0},
+                          {"7", 7},
+                          {"+7", 7},
+                          {" \t7", 7},
+                          {"2147483647", std::numeric_limits<int>::max()}};
+
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        Set(entry.value);
+        EXPECT_EQ(ClientNumaConfig::FromEnvironment().socket_id,
+                  entry.expected);
+    }
+}
+
+TEST_F(ClientNumaConfigTest, InvalidValuesWarnAndUseAutoDetection) {
+    for (const char* value :
+         {"-1", "7suffix", "7 ", "2147483648", "999999999999999999999999"}) {
+        SCOPED_TRACE(value);
+        Set(value);
+        ::testing::internal::CaptureStderr();
+        EXPECT_FALSE(ClientNumaConfig::FromEnvironment().socket_id.has_value());
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+        EXPECT_NE(logs.find(std::string("Invalid MC_STORE_NUMA_SOCKET_ID=") +
+                            value + ", falling back to auto-detect"),
+                  std::string::npos);
+    }
+}
+
+TEST_F(ClientNumaConfigTest, EachConfigReadsCurrentEnvironment) {
+    Set("1");
+    const auto first = ClientNumaConfig::FromEnvironment();
+
+    Set("2");
+    const auto second = ClientNumaConfig::FromEnvironment();
+
+    EXPECT_EQ(first.socket_id, 1);
+    EXPECT_EQ(second.socket_id, 2);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/client_tcp_local_memcpy_test.cpp b/mooncake-store/tests/client_tcp_local_memcpy_test.cpp
index 289ba85a76..24377ebf3d 100644
--- a/mooncake-store/tests/client_tcp_local_memcpy_test.cpp
+++ b/mooncake-store/tests/client_tcp_local_memcpy_test.cpp
@@ -14,7 +14,8 @@
 #include "client_service.h"
 #include "test_server_helpers.h"
 #include "types.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
+#include "common/network.h"
 
 namespace mooncake {
 namespace testing {
@@ -505,4 +506,4 @@ INSTANTIATE_TEST_SUITE_P(
     });
 
 }  // namespace testing
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-store/tests/config_helper_test.cpp b/mooncake-store/tests/config_helper_test.cpp
new file mode 100644
index 0000000000..29fc45678c
--- /dev/null
+++ b/mooncake-store/tests/config_helper_test.cpp
@@ -0,0 +1,60 @@
+#include <gtest/gtest.h>
+
+#include <stdexcept>
+#include <string>
+
+#include "config_helper.h"
+
+namespace mooncake::test {
+namespace {
+
+void ExpectUnsetError(const RequiredParam<int>& param,
+                      const std::string& expected_message) {
+    try {
+        (void)param.Get();
+        FAIL() << "Expected an unset RequiredParam to throw";
+    } catch (const std::runtime_error& error) {
+        EXPECT_EQ(std::string(error.what()), expected_message);
+    }
+}
+
+TEST(ConfigHelperTest, CopyAssignmentPreservesParameterName) {
+    RequiredParam<int> source("metrics_port");
+    RequiredParam<int> copy("old_name");
+    source = 42;
+
+    copy = source;
+
+    EXPECT_EQ(copy.Get(), 42);
+    copy.Clear();
+    ExpectUnsetError(copy, "Required parameter metrics_port has not been set");
+}
+
+TEST(ConfigHelperTest, CopyConstructionPreservesParameterName) {
+    RequiredParam<int> source("metrics_port");
+    source = 42;
+    RequiredParam<int> copy(source);
+    RequiredParam<int> observable("old_name");
+
+    EXPECT_EQ(copy.Get(), 42);
+    observable = copy;
+
+    EXPECT_EQ(observable.Get(), 42);
+    observable.Clear();
+    ExpectUnsetError(observable,
+                     "Required parameter metrics_port has not been set");
+}
+
+TEST(ConfigHelperTest, CopyUnsetPreservesNullName) {
+    RequiredParam<int> source;
+    RequiredParam<int> copy(source);
+    RequiredParam<int> assigned("old_name");
+
+    assigned = source;
+
+    ExpectUnsetError(copy, "Required parameter has not been set");
+    ExpectUnsetError(assigned, "Required parameter has not been set");
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/cxl_client_integration_test.cpp b/mooncake-store/tests/cxl_client_integration_test.cpp
index 35a4649acc..f3428ab1a3 100644
--- a/mooncake-store/tests/cxl_client_integration_test.cpp
+++ b/mooncake-store/tests/cxl_client_integration_test.cpp
@@ -19,7 +19,6 @@
 #include "allocator.h"
 #include "client_service.h"
 #include "types.h"
-#include "utils.h"
 #include "test_server_helpers.h"
 #include "default_config.h"
 
@@ -476,4 +475,4 @@ int main(int argc, char** argv) {
     mooncake::init_ylt_log_level();
     // Run all tests
     return RUN_ALL_TESTS();
-}
\ No newline at end of file
+}
diff --git a/mooncake-store/tests/cxl_segment_config_test.cpp b/mooncake-store/tests/cxl_segment_config_test.cpp
new file mode 100644
index 0000000000..f4e4989151
--- /dev/null
+++ b/mooncake-store/tests/cxl_segment_config_test.cpp
@@ -0,0 +1,92 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "../src/config/cxl_segment_config.h"
+
+namespace mooncake {
+namespace {
+
+class CxlSegmentConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv(kEnvironmentVariable)) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv(kEnvironmentVariable), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv(kEnvironmentVariable, original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(kEnvironmentVariable), 0);
+        }
+    }
+
+    void Set(const char* value) {
+        ASSERT_EQ(setenv(kEnvironmentVariable, value, 1), 0);
+    }
+
+    static constexpr const char* kEnvironmentVariable = "MC_CXL_DEV_SIZE";
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST_F(CxlSegmentConfigTest, UnsetLeavesDeviceSizeAbsent) {
+    EXPECT_FALSE(CxlSegmentConfig::FromEnvironment().device_size.has_value());
+}
+
+TEST_F(CxlSegmentConfigTest, PreservesAcceptedSizeSyntax) {
+    struct Case {
+        const char* value;
+        size_t expected;
+    };
+    const Case cases[] = {
+        {"0", 0},
+        {"4096", 4096},
+        {" +4096 ", 4096},
+    };
+
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        Set(entry.value);
+        EXPECT_EQ(CxlSegmentConfig::FromEnvironment().device_size,
+                  entry.expected);
+    }
+
+    const std::string maximum =
+        std::to_string(std::numeric_limits<size_t>::max());
+    Set(maximum.c_str());
+    EXPECT_EQ(CxlSegmentConfig::FromEnvironment().device_size,
+              std::numeric_limits<size_t>::max());
+}
+
+TEST_F(CxlSegmentConfigTest, PresentInvalidValuesResolveToZero) {
+    for (const char* value :
+         {"", " ", "-1", "4096bytes", "18446744073709551616"}) {
+        SCOPED_TRACE(value);
+        Set(value);
+        const auto config = CxlSegmentConfig::FromEnvironment();
+        ASSERT_TRUE(config.device_size.has_value());
+        EXPECT_EQ(*config.device_size, 0);
+    }
+}
+
+TEST_F(CxlSegmentConfigTest, EachConfigReadsCurrentEnvironment) {
+    Set("4096");
+    const auto first = CxlSegmentConfig::FromEnvironment();
+
+    Set("8192");
+    const auto second = CxlSegmentConfig::FromEnvironment();
+
+    EXPECT_EQ(first.device_size, 4096);
+    EXPECT_EQ(second.device_size, 8192);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/dfs_hf3fs_test.cpp b/mooncake-store/tests/dfs_hf3fs_test.cpp
new file mode 100644
index 0000000000..2fb780d7e8
--- /dev/null
+++ b/mooncake-store/tests/dfs_hf3fs_test.cpp
@@ -0,0 +1,178 @@
+#include <fcntl.h>
+#include <gtest/gtest.h>
+#include <limits.h>
+#include <unistd.h>
+
+#include <array>
+#include <atomic>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <memory>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "hf3fs/hf3fs.h"
+#include "storage/distributed/dfs_global_allocator.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/hf3fs_adapter.h"
+#include "storage_backend.h"
+
+namespace mooncake::test {
+namespace {
+
+constexpr const char* kDefaultRoot = "/mnt/3fs/mooncake_test";
+
+bool IsHf3fsPath(const std::string& path) {
+    char mount_point[PATH_MAX] = {};
+    int ret = hf3fs_extract_mount_point(mount_point, sizeof(mount_point),
+                                        path.c_str());
+    return ret > 0 && ret <= static_cast<int>(sizeof(mount_point));
+}
+
+std::string DfsRootFromEnv() {
+    const char* root = std::getenv("MOONCAKE_DFS_ROOT_DIR");
+    return root && root[0] != '\0' ? std::string(root)
+                                   : std::string(kDefaultRoot);
+}
+
+std::optional<std::string> ExistingAncestor(std::filesystem::path path) {
+    while (!path.empty()) {
+        if (std::filesystem::exists(path)) return path.string();
+        path = path.parent_path();
+    }
+    return std::nullopt;
+}
+
+class Hf3fsTestDir {
+   public:
+    Hf3fsTestDir() {
+        static std::atomic<int64_t> counter{0};
+        root_ = DfsRootFromEnv();
+        path_ = std::filesystem::path(root_) /
+                ("dfs_hf3fs_test_" + std::to_string(::getpid()) + "_" +
+                 std::to_string(++counter));
+        path_str_ = path_.string();
+    }
+
+    ~Hf3fsTestDir() {
+        std::error_code ec;
+        std::filesystem::remove_all(path_, ec);
+    }
+
+    void CreateOrSkip() {
+        auto ancestor = ExistingAncestor(path_);
+        if (!ancestor.has_value()) {
+            GTEST_SKIP() << "no existing parent for test root: " << root_;
+        }
+        if (!IsHf3fsPath(*ancestor)) {
+            GTEST_SKIP() << "test root is not under an hf3fs mount: " << root_;
+        }
+
+        std::filesystem::create_directories(path_);
+        if (!IsHf3fsPath(path_str_)) {
+            GTEST_SKIP() << "test directory is not on an hf3fs mount: "
+                         << path_str_;
+        }
+    }
+
+    const std::string& path() const { return path_str_; }
+
+    std::string file(const std::string& name) const {
+        return (path_ / name).string();
+    }
+
+   private:
+    std::string root_;
+    std::filesystem::path path_;
+    std::string path_str_;
+};
+
+class Hf3fsAdapterTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        test_dir_ = std::make_unique<Hf3fsTestDir>();
+        test_dir_->CreateOrSkip();
+    }
+
+    void TearDown() override { test_dir_.reset(); }
+
+    std::unique_ptr<Hf3fsTestDir> test_dir_;
+};
+
+}  // namespace
+
+TEST_F(Hf3fsAdapterTest, WriteAtReadAtThroughUsrbio) {
+    Hf3fsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(test_dir_->path()).has_value());
+
+    const std::string path = test_dir_->file("adapter_smoke.data");
+    ASSERT_TRUE(adapter.PreallocateFile(path, 4096).has_value());
+
+    auto fd = adapter.OpenFile(path);
+    ASSERT_TRUE(fd.has_value());
+
+    std::array<char, 128> write_buf;
+    std::array<char, 128> read_buf{};
+    write_buf.fill('Q');
+
+    iovec wiov{write_buf.data(), write_buf.size()};
+    auto written = adapter.WriteAt(*fd, &wiov, 1, 100);
+    ASSERT_TRUE(written.has_value());
+    EXPECT_EQ(*written, write_buf.size());
+
+    iovec riov{read_buf.data(), read_buf.size()};
+    auto read = adapter.ReadAt(*fd, &riov, 1, 100);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, read_buf.size());
+    EXPECT_EQ(std::memcmp(write_buf.data(), read_buf.data(), write_buf.size()),
+              0);
+
+    EXPECT_TRUE(adapter.CloseFile(*fd).has_value());
+    EXPECT_TRUE(adapter.Shutdown().has_value());
+}
+
+TEST_F(Hf3fsAdapterTest, DistributedBackendBatchWriteAndRead) {
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = test_dir_->path();
+
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = test_dir_->path();
+    distributed_config.fs_adapter_type = "hf3fs";
+    distributed_config.shard_count = 2;
+    distributed_config.shard_capacity = 1024 * 1024;
+    distributed_config.alignment = 4096;
+    distributed_config.single_tenant = true;
+
+    DistributedStorageBackend backend(file_config, distributed_config,
+                                      std::make_unique<Hf3fsAdapter>());
+    ASSERT_TRUE(backend.Init().has_value());
+
+    alignas(4096) std::array<char, 4096> write_buf;
+    alignas(4096) std::array<char, 4096> read_buf{};
+    write_buf.fill('B');
+
+    const std::string key = "hf3fs_backend_key";
+    const std::string shard_path = test_dir_->file(
+        "dfs_shard_" +
+        DfsGlobalAllocator::FormatShardIdx(0, distributed_config.shard_count) +
+        ".data");
+    DistributedFSDescriptor descriptor{shard_path, 0, write_buf.size(),
+                                       write_buf.size(), 0};
+    auto write = backend.BatchWrite(
+        {{key, descriptor, {{write_buf.data(), write_buf.size()}}}});
+    ASSERT_EQ(write.size(), 1);
+    ASSERT_TRUE(write[0].has_value());
+
+    auto read = backend.BatchRead(
+        {{key, descriptor, {{read_buf.data(), read_buf.size()}}}});
+    ASSERT_EQ(read.size(), 1);
+    ASSERT_TRUE(read[0].has_value());
+    EXPECT_EQ(std::memcmp(write_buf.data(), read_buf.data(), write_buf.size()),
+              0);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/dfs_immutable_bucket_allocator_test.cpp b/mooncake-store/tests/dfs_immutable_bucket_allocator_test.cpp
new file mode 100644
index 0000000000..b9d673b79c
--- /dev/null
+++ b/mooncake-store/tests/dfs_immutable_bucket_allocator_test.cpp
@@ -0,0 +1,363 @@
+#include <atomic>
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <limits>
+#include <mutex>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+#include "config/distributed_storage_config.h"
+#include "storage/distributed/bucket_entry_layout.h"
+#include "storage/distributed/immutable_bucket_allocator.h"
+
+namespace mooncake {
+namespace {
+
+class TempDir {
+   public:
+    TempDir() {
+        static std::atomic<uint64_t> sequence{0};
+        path_ =
+            std::filesystem::temp_directory_path() /
+            ("mooncake-bucket-allocator-" +
+             std::to_string(sequence.fetch_add(1)) + "-" +
+             std::to_string(
+                 std::chrono::steady_clock::now().time_since_epoch().count()));
+        std::filesystem::create_directories(path_);
+    }
+
+    ~TempDir() {
+        std::error_code error;
+        std::filesystem::remove_all(path_, error);
+    }
+
+    std::string string() const { return path_.string(); }
+    std::filesystem::path file(const std::string& name) const {
+        return path_ / name;
+    }
+
+   private:
+    std::filesystem::path path_;
+};
+
+DistributedStorageConfig BucketConfig(const TempDir& dir) {
+    DistributedStorageConfig config;
+    config.fsdir = dir.string();
+    config.fs_adapter_type = "posix";
+    config.allocator_type = "bucket";
+    config.alignment = 4096;
+    config.bucket_capacity = 8192;
+    config.max_bucket_count = 8;
+    config.eviction_enabled = true;
+    config.eviction_high_watermark = 0.01;
+    config.eviction_low_watermark = 0.0;
+    return config;
+}
+
+TEST(BucketEntryLayoutTest, ComputesValueAndPaddingWithOverflowChecks) {
+    auto layout = ComputeBucketEntryLayout(1, 4097, 4096);
+    ASSERT_TRUE(layout);
+    EXPECT_EQ(layout->offset, 4096u);
+    EXPECT_EQ(layout->object_size, 4097u);
+    EXPECT_EQ(layout->aligned_size, 8192u);
+    EXPECT_EQ(layout->end(), 12288u);
+
+    const auto descriptor =
+        MakeBucketDescriptor("/dfs/bucket_000007.data", *layout, 7);
+    EXPECT_EQ(descriptor.file_path, "/dfs/bucket_000007.data");
+    EXPECT_EQ(descriptor.offset, layout->offset);
+    EXPECT_EQ(descriptor.object_size, layout->object_size);
+    EXPECT_EQ(descriptor.aligned_size, layout->aligned_size);
+    EXPECT_EQ(descriptor.shard_idx, 7);
+
+    EXPECT_FALSE(CheckedAlignUp(std::numeric_limits<uint64_t>::max(), 4096));
+    EXPECT_FALSE(ComputeBucketEntryLayout(0, 1, 3));
+    EXPECT_FALSE(ComputeBucketEntryLayout(0, 0, 4096));
+}
+
+TEST(ImmutableBucketAllocatorTest, AppendsAndPacksBatchAcrossBuckets) {
+    TempDir dir;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(BucketConfig(dir)));
+
+    const std::vector<BatchAllocateRequest> requests = {
+        {"a", 3000}, {"b", 3000}, {"c", 3000}};
+    auto results = allocator.BatchAllocate(requests);
+    ASSERT_EQ(results.size(), requests.size());
+    ASSERT_TRUE(results[0].success);
+    ASSERT_TRUE(results[1].success);
+    ASSERT_TRUE(results[2].success);
+    EXPECT_EQ(results[0].descriptor.shard_idx, results[1].descriptor.shard_idx);
+    EXPECT_NE(results[1].descriptor.shard_idx, results[2].descriptor.shard_idx);
+    EXPECT_EQ(results[0].descriptor.offset, 0u);
+    EXPECT_EQ(results[1].descriptor.offset, 4096u);
+    EXPECT_EQ(results[2].descriptor.offset, 0u);
+    EXPECT_EQ(allocator.GetBucketCount(), 2u);
+}
+
+TEST(ImmutableBucketAllocatorTest, DuplicateBatchRollsBackWithoutOffsetReuse) {
+    TempDir dir;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(BucketConfig(dir)));
+
+    auto rolled_back = allocator.BatchAllocate({{"same", 100}, {"same", 100}});
+    ASSERT_EQ(rolled_back.size(), 2u);
+    EXPECT_FALSE(rolled_back[0].success);
+    EXPECT_FALSE(rolled_back[1].success);
+    EXPECT_TRUE(rolled_back[0].descriptor.file_path.empty());
+    EXPECT_FALSE(allocator.GetBucketIdForKey("same"));
+
+    auto replacement = allocator.Allocate("same", 100);
+    ASSERT_TRUE(replacement);
+    EXPECT_EQ(replacement->offset, 4096u);
+    EXPECT_FALSE(allocator.MarkCommitted("same", rolled_back[0].descriptor));
+    EXPECT_TRUE(allocator.MarkCommitted("same", *replacement));
+}
+
+TEST(ImmutableBucketAllocatorTest, StaleFreeCannotTombstoneReplacement) {
+    TempDir dir;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(BucketConfig(dir)));
+
+    auto first = allocator.Allocate("key", 100);
+    ASSERT_TRUE(first);
+    allocator.Free("key", *first);
+    auto replacement = allocator.Allocate("key", 100);
+    ASSERT_TRUE(replacement);
+    ASSERT_NE(first->offset, replacement->offset);
+    allocator.Free("key", *first);
+    EXPECT_TRUE(allocator.MarkCommitted("key", *replacement));
+}
+
+TEST(ImmutableBucketAllocatorTest, TombstonesPreserveConsumedBytesForEviction) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    config.bucket_capacity = 4096;
+    config.max_bucket_count = 2;
+    config.eviction_high_watermark = 0.75;
+    config.eviction_low_watermark = 0.25;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    auto stale = allocator.Allocate("stale", 100);
+    auto active = allocator.Allocate("active", 100);
+    ASSERT_TRUE(stale);
+    ASSERT_TRUE(active);
+    ASSERT_TRUE(allocator.MarkCommitted("stale", *stale));
+    ASSERT_TRUE(allocator.MarkCommitted("active", *active));
+    const uint64_t consumed = allocator.GetUsedBytes();
+    ASSERT_EQ(consumed, 2 * config.bucket_capacity);
+
+    allocator.Free("stale", *stale);
+    EXPECT_EQ(allocator.GetUsedBytes(), consumed);
+
+    auto eviction = allocator.PrepareEviction();
+    ASSERT_FALSE(eviction.Empty());
+    EXPECT_EQ(eviction.bucket_id(), stale->shard_idx);
+    allocator.AbortEviction(std::move(eviction));
+}
+
+TEST(ImmutableBucketAllocatorTest, PendingEntriesProtectSealedBucket) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    config.bucket_capacity = 4096;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    auto pending = allocator.Allocate("pending", 100);
+    auto active = allocator.Allocate("active", 100);
+    ASSERT_TRUE(pending);
+    ASSERT_TRUE(active);
+    EXPECT_TRUE(allocator.PrepareEvictionForAllocationFailure().Empty());
+
+    ASSERT_TRUE(allocator.MarkCommitted("pending", *pending));
+    auto eviction = allocator.PrepareEvictionForAllocationFailure();
+    ASSERT_FALSE(eviction.Empty());
+    ASSERT_EQ(eviction.Candidates().size(), 1u);
+    EXPECT_EQ(eviction.Candidates()[0].key, "pending");
+    allocator.AbortEviction(std::move(eviction));
+}
+
+TEST(ImmutableBucketAllocatorTest, RetiresWholeBucketAfterDelete) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    config.bucket_capacity = 4096;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    auto cold = allocator.Allocate("cold", 100);
+    auto active = allocator.Allocate("active", 100);
+    ASSERT_TRUE(cold);
+    ASSERT_TRUE(active);
+    ASSERT_TRUE(allocator.MarkCommitted("cold", *cold));
+    ASSERT_TRUE(allocator.MarkCommitted("active", *active));
+    auto eviction = allocator.PrepareEvictionForAllocationFailure();
+    ASSERT_FALSE(eviction.Empty());
+    const auto path = eviction.Candidates().front().descriptor.file_path;
+    auto logical = allocator.CommitEvictionLogical(std::move(eviction));
+    ASSERT_TRUE(logical);
+    EXPECT_TRUE(std::filesystem::exists(path));
+    EXPECT_EQ(allocator.GetBucketCount(), 2u);
+    EXPECT_FALSE(allocator.GetBucketIdForKey("cold"));
+
+    ASSERT_TRUE(allocator.DeleteEvictedBucket(std::move(*logical)));
+    EXPECT_FALSE(std::filesystem::exists(path));
+    EXPECT_EQ(allocator.GetBucketCount(), 1u);
+    EXPECT_FALSE(allocator.GetBucketIdForKey("cold"));
+}
+
+TEST(ImmutableBucketAllocatorTest,
+     LogicalEvictionAllowsSameKeyBeforePhysicalDelete) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    config.bucket_capacity = 4096;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    auto old = allocator.Allocate("same", 100);
+    auto active = allocator.Allocate("active", 100);
+    ASSERT_TRUE(old);
+    ASSERT_TRUE(active);
+    ASSERT_TRUE(allocator.MarkCommitted("same", *old));
+    ASSERT_TRUE(allocator.MarkCommitted("active", *active));
+
+    auto eviction = allocator.PrepareEvictionForAllocationFailure();
+    ASSERT_FALSE(eviction.Empty());
+    ASSERT_EQ(eviction.Candidates().size(), 1u);
+    ASSERT_EQ(eviction.Candidates().front().key, "same");
+    const std::filesystem::path old_bucket_path = old->file_path;
+
+    auto logical = allocator.CommitEvictionLogical(std::move(eviction));
+    ASSERT_TRUE(logical);
+    EXPECT_TRUE(std::filesystem::exists(old_bucket_path));
+    EXPECT_FALSE(allocator.GetBucketIdForKey("same"));
+
+    auto replacement = allocator.Allocate("same", 100);
+    ASSERT_TRUE(replacement);
+    ASSERT_NE(replacement->shard_idx, old->shard_idx);
+    ASSERT_TRUE(allocator.MarkCommitted("same", *replacement));
+
+    ASSERT_TRUE(allocator.DeleteEvictedBucket(std::move(*logical)));
+    EXPECT_FALSE(std::filesystem::exists(old_bucket_path));
+    EXPECT_EQ(allocator.GetBucketCount(), 2u);
+    const auto replacement_bucket = allocator.GetBucketIdForKey("same");
+    ASSERT_TRUE(replacement_bucket);
+    EXPECT_EQ(*replacement_bucket, replacement->shard_idx);
+}
+
+TEST(ImmutableBucketAllocatorTest,
+     FailedEvictionDeleteAllowsSameKeyReallocation) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    auto old = allocator.Allocate("same", 100);
+    auto active = allocator.Allocate("active", 4097);
+    ASSERT_TRUE(old);
+    ASSERT_TRUE(active);
+    ASSERT_NE(old->shard_idx, active->shard_idx);
+    ASSERT_TRUE(allocator.MarkCommitted("same", *old));
+    ASSERT_TRUE(allocator.MarkCommitted("active", *active));
+
+    auto eviction = allocator.PrepareEvictionForAllocationFailure();
+    ASSERT_FALSE(eviction.Empty());
+    ASSERT_EQ(eviction.Candidates().size(), 1u);
+    ASSERT_EQ(eviction.Candidates().front().key, "same");
+    const auto old_bucket_id = old->shard_idx;
+    const std::filesystem::path old_bucket_path = old->file_path;
+
+    ASSERT_TRUE(std::filesystem::remove(old_bucket_path));
+    ASSERT_TRUE(std::filesystem::create_directory(old_bucket_path));
+    std::ofstream(old_bucket_path / "keep") << "force unlink failure";
+
+    auto logical = allocator.CommitEvictionLogical(std::move(eviction));
+    ASSERT_TRUE(logical);
+    EXPECT_FALSE(allocator.GetBucketIdForKey("same"));
+    EXPECT_EQ(allocator.GetBucketCount(), 2u);
+    EXPECT_EQ(allocator.GetUsedBytes(), 2 * config.bucket_capacity);
+
+    auto replacement = allocator.Allocate("same", 100);
+    ASSERT_TRUE(replacement);
+    ASSERT_NE(replacement->shard_idx, old_bucket_id);
+    ASSERT_TRUE(allocator.MarkCommitted("same", *replacement));
+    const auto replacement_bucket = allocator.GetBucketIdForKey("same");
+    ASSERT_TRUE(replacement_bucket);
+    EXPECT_EQ(*replacement_bucket, replacement->shard_idx);
+    EXPECT_EQ(allocator.GetBucketCount(), 3u);
+    EXPECT_EQ(allocator.GetUsedBytes(),
+              2 * config.bucket_capacity + config.alignment);
+
+    auto deleted = allocator.DeleteEvictedBucket(std::move(*logical));
+    ASSERT_FALSE(deleted);
+    EXPECT_EQ(deleted.error(), ErrorCode::FILE_WRITE_FAIL);
+
+    ASSERT_TRUE(std::filesystem::remove_all(old_bucket_path));
+    std::ofstream(old_bucket_path) << "retry deletion";
+    EXPECT_EQ(allocator.RetryFailedEvictions(), 1u);
+
+    EXPECT_FALSE(std::filesystem::exists(old_bucket_path));
+    EXPECT_EQ(allocator.GetBucketCount(), 2u);
+    const auto preserved_bucket = allocator.GetBucketIdForKey("same");
+    ASSERT_TRUE(preserved_bucket);
+    EXPECT_EQ(*preserved_bucket, replacement->shard_idx);
+    EXPECT_EQ(allocator.GetUsedBytes(),
+              config.bucket_capacity + config.alignment);
+}
+
+TEST(ImmutableBucketAllocatorTest, RejectsExistingBucketArtifacts) {
+    TempDir dir;
+    std::ofstream(dir.file("bucket_000000.data")) << "old";
+    ImmutableBucketAllocator allocator;
+    auto initialized = allocator.Init(BucketConfig(dir));
+    ASSERT_FALSE(initialized);
+    EXPECT_EQ(initialized.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST(ImmutableBucketAllocatorTest, ConcurrentAllocationDoesNotOverlap) {
+    TempDir dir;
+    auto config = BucketConfig(dir);
+    config.bucket_capacity = 4096 * 16;
+    config.max_bucket_count = 16;
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+
+    constexpr int kThreads = 8;
+    constexpr int kPerThread = 16;
+    std::mutex results_mutex;
+    std::atomic<bool> allocation_failed{false};
+    std::vector<DistributedFSDescriptor> descriptors;
+    std::vector<std::thread> threads;
+    for (int thread = 0; thread < kThreads; ++thread) {
+        threads.emplace_back([&, thread] {
+            for (int i = 0; i < kPerThread; ++i) {
+                const std::string key =
+                    std::to_string(thread) + ":" + std::to_string(i);
+                auto descriptor = allocator.Allocate(key, 1);
+                if (!descriptor) {
+                    allocation_failed.store(true);
+                    return;
+                }
+                std::lock_guard lock(results_mutex);
+                descriptors.push_back(*descriptor);
+            }
+        });
+    }
+    for (auto& thread : threads) thread.join();
+
+    ASSERT_FALSE(allocation_failed.load());
+    ASSERT_EQ(descriptors.size(), kThreads * kPerThread);
+    std::set<std::pair<int, uint64_t>> addresses;
+    for (const auto& descriptor : descriptors) {
+        EXPECT_TRUE(
+            addresses.emplace(descriptor.shard_idx, descriptor.offset).second);
+    }
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/dfs_immutable_bucket_backend_test.cpp b/mooncake-store/tests/dfs_immutable_bucket_backend_test.cpp
new file mode 100644
index 0000000000..8116ef5751
--- /dev/null
+++ b/mooncake-store/tests/dfs_immutable_bucket_backend_test.cpp
@@ -0,0 +1,185 @@
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <filesystem>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+#include "config/distributed_storage_config.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/immutable_bucket_allocator.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#include "storage_backend.h"
+
+namespace mooncake {
+namespace {
+
+class TempDir {
+   public:
+    TempDir() {
+        static std::atomic<uint64_t> sequence{0};
+        path_ =
+            std::filesystem::temp_directory_path() /
+            ("mooncake-bucket-backend-" +
+             std::to_string(sequence.fetch_add(1)) + "-" +
+             std::to_string(
+                 std::chrono::steady_clock::now().time_since_epoch().count()));
+        std::filesystem::create_directories(path_);
+    }
+    ~TempDir() {
+        std::error_code error;
+        std::filesystem::remove_all(path_, error);
+    }
+    std::string string() const { return path_.string(); }
+
+   private:
+    std::filesystem::path path_;
+};
+
+DistributedStorageConfig MakeConfig(const TempDir& dir) {
+    DistributedStorageConfig config;
+    config.fsdir = dir.string();
+    config.fs_adapter_type = "posix";
+    config.allocator_type = "bucket";
+    config.alignment = 4096;
+    config.bucket_capacity = 8192;
+    config.max_bucket_count = 4;
+    return config;
+}
+
+class CountingPosixAdapter : public PosixFsAdapter {
+   public:
+    tl::expected<int, ErrorCode> OpenExistingFile(
+        const std::string& path) override {
+        ++opens;
+        return PosixFsAdapter::OpenExistingFile(path);
+    }
+    tl::expected<void, ErrorCode> CloseFile(int fd) override {
+        ++closes;
+        return PosixFsAdapter::CloseFile(fd);
+    }
+
+    int opens = 0;
+    int closes = 0;
+};
+
+class ShortIoPosixAdapter : public CountingPosixAdapter {
+   public:
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override {
+        if (iovcnt <= 0) return size_t{0};
+        iovec chunk = iov[0];
+        chunk.iov_len = std::min<size_t>(chunk.iov_len, 3);
+        return PosixFsAdapter::WriteAt(fd, &chunk, 1, offset);
+    }
+
+    tl::expected<size_t, ErrorCode> ReadAt(int fd, iovec* iov, int iovcnt,
+                                           int64_t offset) override {
+        if (iovcnt <= 0) return size_t{0};
+        iovec chunk = iov[0];
+        chunk.iov_len = std::min<size_t>(chunk.iov_len, 5);
+        return PosixFsAdapter::ReadAt(fd, &chunk, 1, offset);
+    }
+};
+
+class ZeroProgressPosixAdapter : public CountingPosixAdapter {
+   public:
+    tl::expected<size_t, ErrorCode> WriteAt(int, const iovec*, int,
+                                            int64_t) override {
+        return size_t{0};
+    }
+};
+
+TEST(ImmutableBucketBackendTest, BufferedScatterIoUsesRequestScopedHandles) {
+    TempDir dir;
+    const auto config = MakeConfig(dir);
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+    auto descriptor = allocator.Allocate("key", 11);
+    ASSERT_TRUE(descriptor);
+
+    auto adapter = std::make_unique<ShortIoPosixAdapter>();
+    auto* counts = adapter.get();
+    FileStorageConfig file_config;
+    DistributedStorageBackend backend(file_config, config, std::move(adapter));
+    ASSERT_TRUE(backend.Init());
+
+    std::string first = "hello ";
+    std::string second = "world";
+    auto writes = backend.BatchWrite(
+        {{"key",
+          *descriptor,
+          {{first.data(), first.size()}, {second.data(), second.size()}}}});
+    ASSERT_EQ(writes.size(), 1u);
+    ASSERT_TRUE(writes[0]);
+
+    std::string output(11, '\0');
+    auto reads = backend.BatchRead(
+        {{"key",
+          *descriptor,
+          {{output.data(), 4}, {output.data() + 4, output.size() - 4}}}});
+    ASSERT_EQ(reads.size(), 1u);
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, "hello world");
+    EXPECT_EQ(counts->opens, 2);
+    EXPECT_EQ(counts->closes, 2);
+}
+
+TEST(ImmutableBucketBackendTest, RejectsEscapesMismatchAndMissingFile) {
+    TempDir dir;
+    const auto config = MakeConfig(dir);
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+    auto descriptor = allocator.Allocate("key", 4);
+    ASSERT_TRUE(descriptor);
+
+    FileStorageConfig file_config;
+    DistributedStorageBackend backend(file_config, config,
+                                      std::make_unique<PosixFsAdapter>());
+    ASSERT_TRUE(backend.Init());
+    std::string value = "data";
+
+    auto escaped = *descriptor;
+    escaped.file_path = dir.string() + "/../bucket_000000.data";
+    auto result = backend.BatchWrite({{"key", escaped, {{value.data(), 4}}}});
+    ASSERT_FALSE(result[0]);
+    EXPECT_EQ(result[0].error(), ErrorCode::INVALID_PARAMS);
+
+    auto mismatched = *descriptor;
+    mismatched.shard_idx = 1;
+    result = backend.BatchWrite({{"key", mismatched, {{value.data(), 4}}}});
+    ASSERT_FALSE(result[0]);
+    EXPECT_EQ(result[0].error(), ErrorCode::INVALID_PARAMS);
+
+    ASSERT_TRUE(std::filesystem::remove(descriptor->file_path));
+    result = backend.BatchWrite({{"key", *descriptor, {{value.data(), 4}}}});
+    ASSERT_FALSE(result[0]);
+    EXPECT_EQ(result[0].error(), ErrorCode::FILE_NOT_FOUND);
+    EXPECT_FALSE(std::filesystem::exists(descriptor->file_path));
+}
+
+TEST(ImmutableBucketBackendTest, ZeroProgressIsReportedAsWriteFailure) {
+    TempDir dir;
+    const auto config = MakeConfig(dir);
+    ImmutableBucketAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+    auto descriptor = allocator.Allocate("key", 4);
+    ASSERT_TRUE(descriptor);
+
+    FileStorageConfig file_config;
+    DistributedStorageBackend backend(
+        file_config, config, std::make_unique<ZeroProgressPosixAdapter>());
+    ASSERT_TRUE(backend.Init());
+    std::string value = "data";
+    auto result =
+        backend.BatchWrite({{"key", *descriptor, {{value.data(), 4}}}});
+    ASSERT_FALSE(result[0]);
+    EXPECT_EQ(result[0].error(), ErrorCode::FILE_WRITE_FAIL);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/dfs_immutable_bucket_client_test.cpp b/mooncake-store/tests/dfs_immutable_bucket_client_test.cpp
new file mode 100644
index 0000000000..a85fc3c183
--- /dev/null
+++ b/mooncake-store/tests/dfs_immutable_bucket_client_test.cpp
@@ -0,0 +1,232 @@
+#include <algorithm>
+#include <atomic>
+#include <cstdlib>
+#include <filesystem>
+#include <memory>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <gtest/gtest.h>
+#include <unistd.h>
+
+#include "client_service.h"
+#include "common/client_buffer_allocation.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#include "test_server_helpers.h"
+
+namespace mooncake::test {
+namespace {
+
+class FailingBucketPosixAdapter : public PosixFsAdapter {
+   public:
+    void FailNextWrite() { fail_next_.store(true); }
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override {
+        if (fail_next_.exchange(false)) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        return PosixFsAdapter::WriteAt(fd, iov, iovcnt, offset);
+    }
+
+   private:
+    std::atomic<bool> fail_next_{false};
+};
+
+class DfsImmutableBucketClientTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        root_ = (std::filesystem::temp_directory_path() /
+                 ("dfs_bucket_client_" + std::to_string(::getpid()) + "_" +
+                  std::to_string(next_root_.fetch_add(1))))
+                    .string();
+        std::filesystem::create_directories(root_);
+        SetEnv("MOONCAKE_ENABLE_DFS", "1");
+        SetEnv("MOONCAKE_DFS_FS_ADAPTER", "posix");
+        SetEnv("MOONCAKE_DFS_ROOT_DIR", root_);
+        SetEnv("MOONCAKE_DFS_ALLOCATOR", "bucket");
+        SetEnv("MOONCAKE_DFS_BUCKET_CAPACITY", "4096");
+        SetEnv("MOONCAKE_DFS_MAX_BUCKET_COUNT", "2");
+        SetEnv("MOONCAKE_DFS_ALIGNMENT", "4096");
+        SetEnv("MOONCAKE_DFS_EVICTION_ENABLED", "1");
+        SetEnv("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.1");
+        SetEnv("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.0");
+        SetEnv("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+        ASSERT_TRUE(master_.Start(
+            InProcMasterConfigBuilder().set_default_kv_lease_ttl(0).build()));
+        writer_ = CreateClient("127.0.0.1:18201");
+        provider_ = CreateClient("127.0.0.1:18202");
+        ASSERT_NE(writer_, nullptr);
+        ASSERT_NE(provider_, nullptr);
+        segment_size_ = 16 * 1024 * 1024;
+        segment_ = allocate_buffer_allocator_memory(segment_size_);
+        ASSERT_NE(segment_, nullptr);
+        ASSERT_TRUE(provider_->MountSegment(segment_, segment_size_, "tcp"));
+
+        FileStorageConfig file_config;
+        file_config.storage_backend_type = StorageBackendType::kDistributed;
+        file_config.storage_filepath = root_;
+        DistributedStorageConfig distributed_config;
+        distributed_config.fsdir = root_;
+        distributed_config.fs_adapter_type = "posix";
+        distributed_config.allocator_type = "bucket";
+        distributed_config.alignment = 4096;
+        distributed_config.bucket_capacity = 4096;
+        distributed_config.max_bucket_count = 2;
+        auto adapter = std::make_unique<FailingBucketPosixAdapter>();
+        adapter_ = adapter.get();
+        backend_ = std::make_shared<DistributedStorageBackend>(
+            file_config, distributed_config, std::move(adapter));
+        ASSERT_TRUE(backend_->Init());
+        writer_->SetDfsStorageBackend(backend_);
+    }
+
+    void TearDown() override {
+        if (provider_ && segment_) {
+            (void)provider_->UnmountSegment(segment_, segment_size_);
+        }
+        writer_.reset();
+        provider_.reset();
+        backend_.reset();
+        master_.Stop();
+        if (segment_) std::free(segment_);
+        for (auto it = saved_env_.rbegin(); it != saved_env_.rend(); ++it) {
+            if (it->second) {
+                ::setenv(it->first.c_str(), it->second->c_str(), 1);
+            } else {
+                ::unsetenv(it->first.c_str());
+            }
+        }
+        std::error_code error;
+        std::filesystem::remove_all(root_, error);
+    }
+
+    std::shared_ptr<Client> CreateClient(const std::string& hostname) {
+        auto client = Client::Create(hostname, "P2PHANDSHAKE", "tcp",
+                                     std::nullopt, master_.master_address());
+        return client ? *client : nullptr;
+    }
+
+    void SetEnv(const std::string& name, const std::string& value) {
+        const char* old = ::getenv(name.c_str());
+        saved_env_.emplace_back(
+            name, old ? std::optional<std::string>(old) : std::nullopt);
+        ::setenv(name.c_str(), value.c_str(), 1);
+    }
+
+    ReplicateConfig DfsConfig() const {
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+        return config;
+    }
+
+    static std::vector<Slice> Slices(std::string& value) {
+        return {{value.data(), value.size()}};
+    }
+
+    inline static std::atomic<int> next_root_{0};
+    testing::InProcMaster master_;
+    std::shared_ptr<Client> writer_;
+    std::shared_ptr<Client> provider_;
+    std::shared_ptr<DistributedStorageBackend> backend_;
+    FailingBucketPosixAdapter* adapter_ = nullptr;
+    void* segment_ = nullptr;
+    size_t segment_size_ = 0;
+    std::string root_;
+    std::vector<std::pair<std::string, std::optional<std::string>>> saved_env_;
+};
+
+TEST_F(DfsImmutableBucketClientTest, PutReturnsAfterWriteAndFailureRevokes) {
+    std::string value(4096, 'A');
+    auto slices = Slices(value);
+    ASSERT_TRUE(writer_->Put("ok", slices, DfsConfig()));
+    auto query = writer_->Query("ok");
+    ASSERT_TRUE(query);
+    auto dfs = std::find_if(query->replicas.begin(), query->replicas.end(),
+                            [](const Replica::Descriptor& descriptor) {
+                                return descriptor.is_dfs_replica();
+                            });
+    ASSERT_NE(dfs, query->replicas.end());
+    std::string output(value.size(), '\0');
+    auto reads = backend_->BatchRead(
+        {{"ok", dfs->get_dfs_descriptor(), {{output.data(), output.size()}}}});
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, value);
+
+    adapter_->FailNextWrite();
+    auto failed_value = std::string(4096, 'B');
+    auto failed_slices = Slices(failed_value);
+    auto failed = writer_->Put("failed", failed_slices, DfsConfig());
+    ASSERT_FALSE(failed);
+    EXPECT_EQ(failed.error(), ErrorCode::FILE_WRITE_FAIL);
+    auto missing = writer_->Query("failed");
+    ASSERT_FALSE(missing);
+    EXPECT_EQ(missing.error(), ErrorCode::OBJECT_NOT_FOUND);
+}
+
+TEST_F(DfsImmutableBucketClientTest,
+       SameSizeUpsertRecoversFromBucketExhaustion) {
+    const std::string key = "same_size_upsert";
+    std::string initial(4096, 'A');
+    auto initial_slices = Slices(initial);
+    ASSERT_TRUE(writer_->Put(key, initial_slices, DfsConfig()));
+
+    auto initial_query = writer_->Query(key);
+    ASSERT_TRUE(initial_query);
+    auto initial_dfs = std::find_if(initial_query->replicas.begin(),
+                                    initial_query->replicas.end(),
+                                    [](const Replica::Descriptor& descriptor) {
+                                        return descriptor.is_dfs_replica();
+                                    });
+    ASSERT_NE(initial_dfs, initial_query->replicas.end());
+    const auto initial_descriptor = initial_dfs->get_dfs_descriptor();
+
+    // Consume the final bucket so the upsert must evict the tombstoned old
+    // bucket before it can append the replacement.
+    std::string filler(4096, 'F');
+    auto filler_slices = Slices(filler);
+    ASSERT_TRUE(writer_->Put("filler", filler_slices, DfsConfig()));
+
+    std::string replacement(4096, 'B');
+    auto replacement_slices = Slices(replacement);
+    ASSERT_TRUE(writer_->Upsert(key, replacement_slices, DfsConfig()));
+
+    auto replacement_query = writer_->Query(key);
+    ASSERT_TRUE(replacement_query);
+    auto replacement_dfs = std::find_if(
+        replacement_query->replicas.begin(), replacement_query->replicas.end(),
+        [](const Replica::Descriptor& descriptor) {
+            return descriptor.is_dfs_replica();
+        });
+    ASSERT_NE(replacement_dfs, replacement_query->replicas.end());
+    const auto& replacement_descriptor = replacement_dfs->get_dfs_descriptor();
+    EXPECT_NE(replacement_descriptor.shard_idx, initial_descriptor.shard_idx);
+    EXPECT_NE(replacement_descriptor.file_path, initial_descriptor.file_path);
+}
+
+TEST_F(DfsImmutableBucketClientTest, ExhaustionEvictsWholeBucketAndRetries) {
+    std::string first(4096, '1');
+    std::string second(4096, '2');
+    std::string third(4096, '3');
+    auto first_slices = Slices(first);
+    auto second_slices = Slices(second);
+    auto third_slices = Slices(third);
+    ASSERT_TRUE(writer_->Put("first", first_slices, DfsConfig()));
+    ASSERT_TRUE(writer_->Put("second", second_slices, DfsConfig()));
+    ASSERT_TRUE(writer_->Put("third", third_slices, DfsConfig()));
+
+    auto first_query = writer_->Query("first");
+    ASSERT_TRUE(first_query);
+    EXPECT_EQ(first_query->replicas.size(), 1u);
+    auto third_query = writer_->Query("third");
+    ASSERT_TRUE(third_query);
+    EXPECT_EQ(third_query->replicas.size(), 2u);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/dfs_posix_test.cpp b/mooncake-store/tests/dfs_posix_test.cpp
new file mode 100644
index 0000000000..750ccc8aad
--- /dev/null
+++ b/mooncake-store/tests/dfs_posix_test.cpp
@@ -0,0 +1,1797 @@
+#include <fcntl.h>
+#include <gtest/gtest.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <functional>
+#include <future>
+#include <limits>
+#include <memory>
+#include <optional>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+#include "replica.h"
+#include "storage/distributed/dfs_global_allocator.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#include "storage_backend.h"
+
+namespace mooncake::test {
+
+class TempDir {
+   public:
+    explicit TempDir(const std::string& prefix) {
+        static std::atomic<int64_t> counter{0};
+        path_ = std::filesystem::temp_directory_path() /
+                (prefix + "_" + std::to_string(::getpid()) + "_" +
+                 std::to_string(++counter));
+        path_str_ = path_.string();
+        std::filesystem::create_directories(path_);
+    }
+
+    ~TempDir() {
+        std::error_code ec;
+        std::filesystem::remove_all(path_, ec);
+    }
+
+    const std::string& path() const { return path_str_; }
+
+    std::string file(const std::string& name) const {
+        return (path_ / name).string();
+    }
+
+   private:
+    std::filesystem::path path_;
+    std::string path_str_;
+};
+
+class EnvGuard {
+   public:
+    EnvGuard() {
+        Save("MOONCAKE_DFS_FS_ADAPTER");
+        Save("MOONCAKE_DISTRIBUTED_FS_TYPE");
+        Save("MOONCAKE_DFS_EVICTION_ENABLED");
+        Save("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK");
+        Save("MOONCAKE_DFS_EVICTION_LOW_WATERMARK");
+        Save("MOONCAKE_DFS_DEFERRED_FREE_SECONDS");
+        Save("MOONCAKE_DFS_EVICTION_CHECK_INTERVAL");
+        Save("MOONCAKE_DFS_ROOT_DIR");
+        Save("MOONCAKE_DFS_SHARD_COUNT");
+        Save("MOONCAKE_DFS_SHARD_CAPACITY");
+        Save("MOONCAKE_DFS_ALIGNMENT");
+        Save("MOONCAKE_DFS_SINGLE_TENANT");
+    }
+
+    ~EnvGuard() {
+        for (const auto& [key, value] : saved_) {
+            if (value.has_value()) {
+                ::setenv(key.c_str(), value->c_str(), 1);
+            } else {
+                ::unsetenv(key.c_str());
+            }
+        }
+    }
+
+    void Set(const char* key, const char* value) { ::setenv(key, value, 1); }
+
+   private:
+    void Save(const std::string& key) {
+        const char* value = ::getenv(key.c_str());
+        if (value) {
+            saved_.push_back({key, std::string(value)});
+        } else {
+            saved_.push_back({key, std::nullopt});
+        }
+    }
+
+    std::vector<std::pair<std::string, std::optional<std::string>>> saved_;
+};
+
+class AlignedBuffer {
+   public:
+    explicit AlignedBuffer(size_t size, size_t alignment = 4096) : size_(size) {
+        void* ptr = nullptr;
+        if (::posix_memalign(&ptr, alignment, size) != 0) ptr = nullptr;
+        ptr_ = static_cast<char*>(ptr);
+    }
+
+    ~AlignedBuffer() { std::free(ptr_); }
+
+    AlignedBuffer(const AlignedBuffer&) = delete;
+    AlignedBuffer& operator=(const AlignedBuffer&) = delete;
+
+    char* data() { return ptr_; }
+    const char* data() const { return ptr_; }
+    size_t size() const { return size_; }
+
+    void Fill(char value) { std::memset(ptr_, value, size_); }
+
+   private:
+    char* ptr_ = nullptr;
+    size_t size_ = 0;
+};
+
+void ConfigurePosixDfs(EnvGuard& env) {
+    env.Set("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    env.Set("MOONCAKE_DFS_SINGLE_TENANT", "1");
+    env.Set("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+    env.Set("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+}
+
+DistributedStorageConfig MakeAllocatorConfig(const std::string& mount_path,
+                                             int shard_count,
+                                             uint64_t shard_capacity,
+                                             uint64_t alignment) {
+    auto config = DistributedStorageConfig::FromEnvironment();
+    config.fsdir = mount_path;
+    config.shard_count = shard_count;
+    config.shard_capacity = shard_capacity;
+    config.alignment = alignment;
+    return config;
+}
+
+std::vector<DfsGlobalAllocator::EvictionCandidate>
+PrepareAndCommitPreparedEviction(DfsGlobalAllocator& allocator) {
+    auto pending = allocator.PrepareEviction();
+    auto candidates = pending.Candidates();
+    allocator.CommitPreparedEviction(std::move(pending));
+    return candidates;
+}
+
+class FsAdapterFdTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        tmp_ = std::make_unique<TempDir>("dfs_fd_test");
+        adapter_ = std::make_unique<PosixFsAdapter>();
+        ASSERT_TRUE(adapter_->Init(tmp_->path()).has_value());
+    }
+
+    void TearDown() override {
+        adapter_.reset();
+        tmp_.reset();
+    }
+
+    std::unique_ptr<TempDir> tmp_;
+    std::unique_ptr<PosixFsAdapter> adapter_;
+};
+
+TEST_F(FsAdapterFdTest, OpenClose) {
+    auto pre = adapter_->PreallocateFile(tmp_->file("shard0.data"), 4096);
+    ASSERT_TRUE(pre.has_value());
+
+    auto fd = adapter_->OpenFile(tmp_->file("shard0.data"));
+    ASSERT_TRUE(fd.has_value());
+    EXPECT_GE(*fd, 0);
+
+    auto close = adapter_->CloseFile(*fd);
+    EXPECT_TRUE(close.has_value());
+}
+
+TEST_F(FsAdapterFdTest, WriteAtReadAt) {
+    ASSERT_TRUE(
+        adapter_->PreallocateFile(tmp_->file("shard0.data"), 4096).has_value());
+    auto fd = adapter_->OpenFile(tmp_->file("shard0.data"));
+    ASSERT_TRUE(fd.has_value());
+
+    char write_buf[128];
+    std::memset(write_buf, 'A', sizeof(write_buf));
+    iovec wiov{write_buf, sizeof(write_buf)};
+    auto written = adapter_->WriteAt(*fd, &wiov, 1, 100);
+    ASSERT_TRUE(written.has_value());
+    EXPECT_EQ(*written, sizeof(write_buf));
+
+    char read_buf[128] = {};
+    iovec riov{read_buf, sizeof(read_buf)};
+    auto read = adapter_->ReadAt(*fd, &riov, 1, 100);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, sizeof(read_buf));
+    EXPECT_EQ(std::memcmp(write_buf, read_buf, sizeof(write_buf)), 0);
+
+    adapter_->CloseFile(*fd);
+}
+
+TEST_F(FsAdapterFdTest, MultiIovWriteRead) {
+    constexpr size_t total = 8192;
+    ASSERT_TRUE(adapter_->PreallocateFile(tmp_->file("shard_multi.data"), total)
+                    .has_value());
+    auto fd = adapter_->OpenFile(tmp_->file("shard_multi.data"));
+    ASSERT_TRUE(fd.has_value());
+
+    char w0[2048], w1[3072], w2[3072];
+    std::memset(w0, 'A', sizeof(w0));
+    std::memset(w1, 'B', sizeof(w1));
+    std::memset(w2, 'C', sizeof(w2));
+    iovec wiovs[3] = {
+        {w0, sizeof(w0)},
+        {w1, sizeof(w1)},
+        {w2, sizeof(w2)},
+    };
+    auto written = adapter_->WriteAt(*fd, wiovs, 3, 0);
+    ASSERT_TRUE(written.has_value());
+    EXPECT_EQ(*written, total);
+
+    char r0[2048] = {}, r1[3072] = {}, r2[3072] = {};
+    iovec riovs[3] = {
+        {r0, sizeof(r0)},
+        {r1, sizeof(r1)},
+        {r2, sizeof(r2)},
+    };
+    auto read = adapter_->ReadAt(*fd, riovs, 3, 0);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, total);
+    EXPECT_EQ(std::memcmp(w0, r0, sizeof(w0)), 0);
+    EXPECT_EQ(std::memcmp(w1, r1, sizeof(w1)), 0);
+    EXPECT_EQ(std::memcmp(w2, r2, sizeof(w2)), 0);
+
+    adapter_->CloseFile(*fd);
+}
+
+TEST_F(FsAdapterFdTest, MultiIovPartialReadAndUnalignedAccess) {
+    constexpr size_t total = 8192;
+    ASSERT_TRUE(
+        adapter_->PreallocateFile(tmp_->file("shard_partial.data"), total)
+            .has_value());
+    auto fd = adapter_->OpenFile(tmp_->file("shard_partial.data"));
+    ASSERT_TRUE(fd.has_value());
+
+    std::string write_data(total, 'X');
+    iovec wiov{write_data.data(), write_data.size()};
+    ASSERT_TRUE(adapter_->WriteAt(*fd, &wiov, 1, 0).has_value());
+
+    char read_buf[3072] = {};
+    iovec riov{read_buf, sizeof(read_buf)};
+    auto read = adapter_->ReadAt(*fd, &riov, 1, 2048);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, sizeof(read_buf));
+    EXPECT_EQ(std::memcmp(read_buf, write_data.data() + 2048, sizeof(read_buf)),
+              0);
+
+    char wbuf[63];
+    std::memset(wbuf, 'Y', sizeof(wbuf));
+    iovec unaligned_wiov{wbuf, sizeof(wbuf)};
+    auto written = adapter_->WriteAt(*fd, &unaligned_wiov, 1, 101);
+    ASSERT_TRUE(written.has_value());
+    EXPECT_EQ(*written, sizeof(wbuf));
+
+    char rbuf[63] = {};
+    iovec unaligned_riov{rbuf, sizeof(rbuf)};
+    read = adapter_->ReadAt(*fd, &unaligned_riov, 1, 101);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, sizeof(rbuf));
+    EXPECT_EQ(std::memcmp(wbuf, rbuf, sizeof(wbuf)), 0);
+
+    char beyond[64] = {};
+    iovec beyond_iov{beyond, sizeof(beyond)};
+    auto beyond_read = adapter_->ReadAt(*fd, &beyond_iov, 1, 1ULL << 30);
+    ASSERT_TRUE(beyond_read.has_value());
+    EXPECT_EQ(*beyond_read, 0);
+
+    adapter_->CloseFile(*fd);
+}
+
+TEST_F(FsAdapterFdTest, PreallocateLargeSparseFile) {
+    constexpr uint64_t size = 4ULL * 1024 * 1024 * 1024;
+    ASSERT_TRUE(adapter_->PreallocateFile(tmp_->file("shard_large.data"), size)
+                    .has_value());
+
+    struct stat st;
+    ASSERT_EQ(::stat(tmp_->file("shard_large.data").c_str(), &st), 0);
+    EXPECT_EQ(static_cast<uint64_t>(st.st_size), size);
+    EXPECT_LT(static_cast<uint64_t>(st.st_blocks) * 512, size / 1000);
+
+    auto fd = adapter_->OpenFile(tmp_->file("shard_large.data"));
+    ASSERT_TRUE(fd.has_value());
+    char wbuf[4096];
+    std::memset(wbuf, 'L', sizeof(wbuf));
+    iovec wiov{wbuf, sizeof(wbuf)};
+    auto written = adapter_->WriteAt(*fd, &wiov, 1, 3ULL * 1024 * 1024 * 1024);
+    ASSERT_TRUE(written.has_value());
+    EXPECT_EQ(*written, sizeof(wbuf));
+
+    char rbuf[4096] = {};
+    iovec riov{rbuf, sizeof(rbuf)};
+    auto read = adapter_->ReadAt(*fd, &riov, 1, 3ULL * 1024 * 1024 * 1024);
+    ASSERT_TRUE(read.has_value());
+    EXPECT_EQ(*read, sizeof(rbuf));
+    EXPECT_EQ(std::memcmp(wbuf, rbuf, sizeof(wbuf)), 0);
+
+    adapter_->CloseFile(*fd);
+}
+
+TEST(DfsGlobalAllocatorTest, AllocateFreeAndFormatShardIdx) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_alloc");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 4, 1024 * 1024, 4096)));
+
+    auto desc = alloc.Allocate("key1", 100);
+    ASSERT_TRUE(desc.has_value());
+    EXPECT_EQ(desc->aligned_size, 4096);
+    EXPECT_GE(desc->shard_idx, 0);
+    EXPECT_LT(desc->shard_idx, 4);
+    EXPECT_EQ(desc->offset % 4096, 0);
+
+    alloc.Free(desc->offset, desc->aligned_size, desc->shard_idx, "key1");
+    auto desc2 = alloc.Allocate("key2", 100);
+    EXPECT_TRUE(desc2.has_value());
+
+    EXPECT_EQ(DfsGlobalAllocator::FormatShardIdx(0, 64), "00");
+    EXPECT_EQ(DfsGlobalAllocator::FormatShardIdx(9, 64), "09");
+    EXPECT_EQ(DfsGlobalAllocator::FormatShardIdx(10, 64), "10");
+    EXPECT_EQ(DfsGlobalAllocator::FormatShardIdx(63, 64), "63");
+    EXPECT_EQ(DfsGlobalAllocator::FormatShardIdx(100, 1000), "100");
+}
+
+TEST(DfsGlobalAllocatorTest, InitReturnsSpecificErrors) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_init_error");
+
+    DistributedStorageConfig invalid_config =
+        MakeAllocatorConfig(tmp.path(), 1, 1024 * 1024, 3);
+    DfsGlobalAllocator invalid_allocator;
+    auto invalid_result = invalid_allocator.Init(invalid_config);
+    ASSERT_FALSE(invalid_result);
+    EXPECT_EQ(invalid_result.error(), ErrorCode::INVALID_PARAMS);
+
+    const std::string file_path = tmp.file("not_a_directory");
+    const int fd = ::open(file_path.c_str(), O_CREAT | O_WRONLY, 0600);
+    ASSERT_GE(fd, 0);
+    ASSERT_EQ(::close(fd), 0);
+
+    DistributedStorageConfig file_error_config =
+        MakeAllocatorConfig(file_path, 1, 1024 * 1024, 4096);
+    DfsGlobalAllocator file_error_allocator;
+    auto file_error_result = file_error_allocator.Init(file_error_config);
+    ASSERT_FALSE(file_error_result);
+    EXPECT_EQ(file_error_result.error(), ErrorCode::FILE_WRITE_FAIL);
+}
+
+TEST(DfsGlobalAllocatorTest, AllocateReservesAlignmentPadding) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_alloc_padding");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8 * 1024, 4096)));
+
+    auto desc = alloc.Allocate("key1", 100);
+    ASSERT_TRUE(desc.has_value());
+    EXPECT_EQ(desc->aligned_size, 4096);
+    EXPECT_EQ(desc->offset % 4096, 0);
+
+    auto exhausted = alloc.Allocate("key2", 100);
+    EXPECT_FALSE(exhausted.has_value());
+    EXPECT_EQ(exhausted.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+
+    alloc.Free(desc->offset, desc->aligned_size, desc->shard_idx, "key1");
+    auto after_free = alloc.Allocate("key3", 100);
+    EXPECT_TRUE(after_free.has_value());
+}
+
+TEST(DfsGlobalAllocatorTest, ExhaustionAndEviction) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    env.Set("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.5");
+    env.Set("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.25");
+    TempDir tmp("dfs_exhaust");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 32 * 1024, 4096)));
+
+    std::vector<DistributedFSDescriptor> descs;
+    for (int i = 0; i < 4; ++i) {
+        auto desc = alloc.Allocate("k" + std::to_string(i), 100);
+        ASSERT_TRUE(desc.has_value()) << "allocation " << i;
+        alloc.UpdateAccess("k" + std::to_string(i), desc->shard_idx,
+                           desc->offset);
+        descs.push_back(*desc);
+    }
+
+    auto exhausted = alloc.Allocate("k_exhausted", 100);
+    EXPECT_FALSE(exhausted.has_value());
+    EXPECT_EQ(exhausted.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+
+    auto pending = alloc.PrepareEviction();
+    auto evicted = pending.Candidates();
+    ASSERT_FALSE(evicted.empty());
+    EXPECT_EQ(evicted.front().key, "k0");
+
+    // Prepare only reserves candidates; their extents are not reusable until
+    // the master accepts and commits the transaction.
+    auto before_commit = alloc.Allocate("k_before_commit", 100);
+    EXPECT_FALSE(before_commit.has_value());
+
+    alloc.CommitPreparedEviction(std::move(pending));
+
+    auto after_evict = alloc.Allocate("k_after_evict", 100);
+    EXPECT_TRUE(after_evict.has_value());
+}
+
+TEST(DfsGlobalAllocatorTest, RestorePreparedEvictionPreservesCandidateOrder) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    env.Set("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.9");
+    env.Set("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.7");
+    TempDir tmp("dfs_abort_eviction");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 32 * 1024, 4096)));
+
+    for (int i = 0; i < 4; ++i) {
+        const std::string key = "k" + std::to_string(i);
+        auto desc = alloc.Allocate(key, 100);
+        ASSERT_TRUE(desc.has_value()) << "allocation " << i;
+        alloc.UpdateAccess(key, desc->shard_idx, desc->offset);
+    }
+
+    auto pending = alloc.PrepareEviction();
+    ASSERT_EQ(pending.Candidates().size(), 2);
+    EXPECT_EQ(pending.Candidates()[0].key, "k0");
+    EXPECT_EQ(pending.Candidates()[1].key, "k1");
+    alloc.RestorePreparedEviction(std::move(pending));
+
+    auto retry = alloc.PrepareEviction();
+    ASSERT_EQ(retry.Candidates().size(), 2);
+    EXPECT_EQ(retry.Candidates()[0].key, "k0");
+    EXPECT_EQ(retry.Candidates()[1].key, "k1");
+    alloc.RestorePreparedEviction(std::move(retry));
+}
+
+TEST(DfsGlobalAllocatorTest, PartialResolutionContinuesToLowWatermark) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    env.Set("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.9");
+    env.Set("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.7");
+    TempDir tmp("dfs_partial_eviction");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 32 * 1024, 4096)));
+
+    std::vector<DistributedFSDescriptor> descs;
+    for (int i = 0; i < 4; ++i) {
+        const std::string key = "k" + std::to_string(i);
+        auto desc = alloc.Allocate(key, 100);
+        ASSERT_TRUE(desc.has_value()) << "allocation " << i;
+        alloc.UpdateAccess(key, desc->shard_idx, desc->offset);
+        descs.push_back(*desc);
+    }
+
+    auto pending = alloc.PrepareEviction();
+    ASSERT_EQ(pending.Candidates().size(), 2);
+    EXPECT_EQ(pending.Candidates()[0].key, "k0");
+    EXPECT_EQ(pending.Candidates()[1].key, "k1");
+
+    alloc.ResolvePreparedEviction(std::move(pending), {true, false});
+    alloc.UpdateAccess("k1", descs[1].shard_idx, descs[1].offset);
+
+    // Accepting only k0 drops usage below the high watermark but not the low
+    // watermark. The same active eviction cycle must therefore continue and
+    // reach k2 behind the restored, protected k1.
+    auto continuation = alloc.PrepareEviction();
+    ASSERT_EQ(continuation.Candidates().size(), 1);
+    EXPECT_EQ(continuation.Candidates().front().key, "k2");
+    alloc.CommitPreparedEviction(std::move(continuation));
+
+    auto complete = alloc.PrepareEviction();
+    EXPECT_TRUE(complete.Empty());
+}
+
+TEST(DfsGlobalAllocatorTest, EvictionCountsPendingFreeTowardWatermarks) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    env.Set("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.9");
+    env.Set("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.7");
+    env.Set("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "30");
+    TempDir tmp("dfs_pending_watermark");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 32 * 1024, 4096)));
+
+    for (int i = 0; i < 4; ++i) {
+        const std::string key = "k" + std::to_string(i);
+        auto desc = alloc.Allocate(key, 100);
+        ASSERT_TRUE(desc.has_value()) << "allocation " << i;
+        alloc.UpdateAccess(key, desc->shard_idx, desc->offset);
+    }
+
+    auto evicted = PrepareAndCommitPreparedEviction(alloc);
+    ASSERT_EQ(evicted.size(), 2);
+    EXPECT_EQ(evicted[0].key, "k0");
+    EXPECT_EQ(evicted[1].key, "k1");
+
+    auto repeated = PrepareAndCommitPreparedEviction(alloc);
+    EXPECT_TRUE(repeated.empty());
+
+    auto before_release = alloc.Allocate("k_before_release", 100);
+    EXPECT_FALSE(before_release.has_value());
+    EXPECT_EQ(before_release.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+}
+
+TEST(DfsGlobalAllocatorTest, FreeRemovesLruEntryBeforeOffsetReuse) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_free_lru_reuse");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8 * 1024, 4096)));
+
+    auto desc_a = alloc.Allocate("A", 100);
+    ASSERT_TRUE(desc_a.has_value());
+    alloc.UpdateAccess("A", desc_a->shard_idx, desc_a->offset);
+
+    alloc.Free(desc_a->offset, desc_a->aligned_size, desc_a->shard_idx, "A");
+
+    auto desc_b = alloc.Allocate("B", 100);
+    ASSERT_TRUE(desc_b.has_value());
+    ASSERT_EQ(desc_b->offset, desc_a->offset);
+    alloc.UpdateAccess("B", desc_b->shard_idx, desc_b->offset);
+
+    auto evicted = PrepareAndCommitPreparedEviction(alloc);
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted.front().key, "B");
+}
+
+TEST(DfsGlobalAllocatorTest, StaleFreeDoesNotReleaseReusedOffset) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_stale_free");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8 * 1024, 4096)));
+
+    auto desc_a = alloc.Allocate("A", 100);
+    ASSERT_TRUE(desc_a.has_value());
+    alloc.UpdateAccess("A", desc_a->shard_idx, desc_a->offset);
+
+    alloc.Free(desc_a->offset, desc_a->aligned_size, desc_a->shard_idx, "A");
+
+    auto desc_b = alloc.Allocate("B", 100);
+    ASSERT_TRUE(desc_b.has_value());
+    ASSERT_EQ(desc_b->offset, desc_a->offset);
+    alloc.UpdateAccess("B", desc_b->shard_idx, desc_b->offset);
+
+    alloc.Free(desc_a->offset, desc_a->aligned_size, desc_a->shard_idx, "A");
+
+    auto evicted = PrepareAndCommitPreparedEviction(alloc);
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted.front().key, "B");
+}
+
+TEST(DfsGlobalAllocatorTest, ConcurrentAllocate) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_concurrent");
+
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(
+        alloc.Init(MakeAllocatorConfig(tmp.path(), 4, 128 * 1024, 4096)));
+
+    constexpr int kThreadCount = 32;
+    std::vector<std::thread> threads;
+    std::atomic<int> success_count{0};
+    std::atomic<int> fail_count{0};
+    for (int i = 0; i < kThreadCount; ++i) {
+        threads.emplace_back([&alloc, &success_count, &fail_count, i]() {
+            std::string key = "key_" + std::to_string(i);
+            auto desc = alloc.Allocate(key, 100);
+            if (desc.has_value()) {
+                success_count++;
+                alloc.UpdateAccess(key, desc->shard_idx, desc->offset);
+                alloc.Free(desc->offset, desc->aligned_size, desc->shard_idx,
+                           key);
+            } else {
+                fail_count++;
+            }
+        });
+    }
+    for (auto& thread : threads) thread.join();
+
+    EXPECT_EQ(success_count.load(), kThreadCount);
+    EXPECT_EQ(fail_count.load(), 0);
+}
+
+TEST(DfsGlobalAllocatorTest, ExpansionValidatesCountAndUsesEmptyShards) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_capacity");
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096)));
+    auto old = alloc.Allocate("old", 100);
+    ASSERT_TRUE(old);
+    ASSERT_FALSE(alloc.Allocate("full", 100));
+
+    for (int count : {-1, 0}) {
+        auto result = alloc.ExpandShards(count);
+        ASSERT_FALSE(result);
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+    auto unchanged = alloc.ExpandShards(1);
+    ASSERT_TRUE(unchanged);
+    EXPECT_EQ(*unchanged, 1);
+    auto expanded = alloc.ExpandShards(2);
+    ASSERT_TRUE(expanded);
+    EXPECT_EQ(*expanded, 2);
+    EXPECT_EQ(alloc.GetShardCount(), 2);
+    ASSERT_TRUE(alloc.ExpandShards(2));
+    auto shrink = alloc.ExpandShards(1);
+    ASSERT_FALSE(shrink);
+    EXPECT_EQ(shrink.error(), ErrorCode::INVALID_PARAMS);
+
+    // This key still prefers the full original shard. Expansion must provide
+    // usable capacity even when hashing does not select the new shard.
+    std::string key;
+    for (int i = 0; i < 1000; ++i) {
+        key = "fallback_" + std::to_string(i);
+        if (std::hash<std::string>{}(key) % 2 == 0) break;
+    }
+    ASSERT_EQ(std::hash<std::string>{}(key) % 2, 0);
+    auto added = alloc.Allocate(key, 100);
+    ASSERT_TRUE(added);
+    EXPECT_EQ(added->shard_idx, 1);
+    alloc.Free(old->offset, old->aligned_size, old->shard_idx, "old");
+    alloc.Free(added->offset, added->aligned_size, added->shard_idx, key);
+}
+
+TEST(DfsGlobalAllocatorTest, ExpansionPreservesLegacyPathsAndRestartsLayout) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_legacy");
+    // Seed the legacy padded layout rather than relying on how new roots are
+    // named after this change. Crossing 100 must never rename these files.
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    for (int i = 0; i < 100; ++i) {
+        const auto path =
+            tmp.file("dfs_shard_" + DfsGlobalAllocator::FormatShardIdx(i, 100) +
+                     ".data");
+        ASSERT_TRUE(adapter.PreallocateFile(path, 8192));
+    }
+    std::string old_path;
+    {
+        DfsGlobalAllocator alloc;
+        ASSERT_TRUE(
+            alloc.Init(MakeAllocatorConfig(tmp.path(), 100, 8192, 4096)));
+        auto old = alloc.Allocate("preserved", 100);
+        ASSERT_TRUE(old);
+        old_path = old->file_path;
+        const int fd = ::open(old_path.c_str(), O_WRONLY);
+        ASSERT_GE(fd, 0);
+        const char marker = 'P';
+        EXPECT_EQ(::pwrite(fd, &marker, 1, old->offset), 1);
+        EXPECT_EQ(::close(fd), 0);
+        ASSERT_TRUE(alloc.ExpandShards(101));
+        EXPECT_EQ(alloc.GetShardCount(), 101);
+        EXPECT_TRUE(std::filesystem::exists(old_path));
+        char readback = 0;
+        const int read_fd = ::open(old_path.c_str(), O_RDONLY);
+        ASSERT_GE(read_fd, 0);
+        EXPECT_EQ(::pread(read_fd, &readback, 1, old->offset), 1);
+        EXPECT_EQ(::close(read_fd), 0);
+        EXPECT_EQ(readback, marker);
+    }
+    // Only the shard layout is recovered. This deliberately makes no claim
+    // about recovering the previous object's allocation or Master metadata.
+    DfsGlobalAllocator restarted;
+    ASSERT_TRUE(restarted.Init(MakeAllocatorConfig(tmp.path(), 2, 8192, 4096)));
+    EXPECT_EQ(restarted.GetShardCount(), 101);
+    EXPECT_TRUE(std::filesystem::exists(old_path));
+}
+
+TEST(DfsGlobalAllocatorTest, ExpansionRetainsPaddedLegacyShardDescriptors) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_padded");
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    ASSERT_TRUE(adapter.PreallocateFile(tmp.file("dfs_shard_000.data"), 8192));
+    ASSERT_TRUE(adapter.PreallocateFile(tmp.file("dfs_shard_001.data"), 8192));
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 2, 8192, 4096)));
+    auto old = alloc.Allocate("old", 100);
+    ASSERT_TRUE(old);
+    EXPECT_EQ(old->file_path,
+              tmp.file(old->shard_idx == 0 ? "dfs_shard_000.data"
+                                           : "dfs_shard_001.data"));
+    ASSERT_TRUE(alloc.ExpandShards(3));
+    EXPECT_TRUE(std::filesystem::exists(old->file_path));
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_00.data")));
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+}
+
+TEST(DfsGlobalAllocatorTest, InitRejectsMalformedShardNames) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    for (const std::string& name :
+         {"dfs_shard_0.data", "dfs_shard_.data", "dfs_shard_+0.data",
+          "dfs_shard_-1.data", "dfs_shard_00x.data",
+          "dfs_shard_2147483647.data", "dfs_shard_2147483648.data"}) {
+        SCOPED_TRACE(name);
+        TempDir tmp("dfs_invalid_shard_name");
+        PosixFsAdapter adapter;
+        ASSERT_TRUE(adapter.Init(tmp.path()));
+        ASSERT_TRUE(adapter.PreallocateFile(tmp.file(name), 8192));
+        DfsGlobalAllocator alloc;
+        auto result =
+            alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096));
+        ASSERT_FALSE(result);
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+        EXPECT_FALSE(alloc.IsInitialized());
+        EXPECT_EQ(alloc.GetShardCount(), 0);
+        EXPECT_EQ(std::filesystem::file_size(tmp.file(name)), 8192);
+        EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_00.data")));
+    }
+}
+
+TEST(DfsGlobalAllocatorTest, InitRejectsAmbiguousOrNoncontiguousLayout) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    for (const std::string& second_name :
+         {"dfs_shard_000.data", "dfs_shard_02.data"}) {
+        SCOPED_TRACE(second_name);
+        TempDir tmp("dfs_invalid_shard_layout");
+        PosixFsAdapter adapter;
+        ASSERT_TRUE(adapter.Init(tmp.path()));
+        ASSERT_TRUE(
+            adapter.PreallocateFile(tmp.file("dfs_shard_00.data"), 8192));
+        ASSERT_TRUE(adapter.PreallocateFile(tmp.file(second_name), 8192));
+        DfsGlobalAllocator alloc;
+        auto result =
+            alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096));
+        ASSERT_FALSE(result);
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+        EXPECT_EQ(alloc.GetShardCount(), 0);
+        EXPECT_EQ(std::filesystem::file_size(tmp.file("dfs_shard_00.data")),
+                  8192);
+        EXPECT_EQ(std::filesystem::file_size(tmp.file(second_name)), 8192);
+        EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+    }
+}
+
+TEST(DfsGlobalAllocatorTest, InitRejectsExistingCapacityWithoutTruncation) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_invalid_shard_capacity");
+    const auto path = tmp.file("dfs_shard_00.data");
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    ASSERT_TRUE(adapter.PreallocateFile(path, 4096));
+    DfsGlobalAllocator alloc;
+    auto result = alloc.Init(MakeAllocatorConfig(tmp.path(), 2, 8192, 4096));
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_FALSE(alloc.IsInitialized());
+    EXPECT_EQ(alloc.GetShardCount(), 0);
+    EXPECT_EQ(std::filesystem::file_size(path), 4096);
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+}
+
+TEST(DfsGlobalAllocatorTest, FailedExpansionPreservesExistingUnpublishedShard) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_existing_failure");
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096)));
+    // A previous interrupted expansion may have left a complete shard. Failed
+    // retries must only clean files created by the current operation.
+    const auto existing = tmp.file("dfs_shard_01.data");
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    ASSERT_TRUE(adapter.PreallocateFile(existing, 8192));
+    const auto blocked = tmp.file("dfs_shard_03.data");
+    ASSERT_TRUE(std::filesystem::create_directory(blocked));
+    auto result = alloc.ExpandShards(4);
+    ASSERT_FALSE(result);
+    EXPECT_EQ(alloc.GetShardCount(), 1);
+    EXPECT_EQ(std::filesystem::file_size(existing), 8192);
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_02.data")));
+    ASSERT_TRUE(std::filesystem::remove(blocked));
+    ASSERT_TRUE(alloc.ExpandShards(4));
+    EXPECT_EQ(alloc.GetShardCount(), 4);
+}
+
+TEST(DfsGlobalAllocatorTest, FailedExpansionDoesNotPublishPartialCapacity) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_failure");
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096)));
+    // The second new shard cannot be prepared. The first must not become
+    // visible to allocators when the whole expansion request fails.
+    const auto blocked = tmp.file("dfs_shard_02.data");
+    ASSERT_TRUE(std::filesystem::create_directory(blocked));
+    auto result = alloc.ExpandShards(3);
+    ASSERT_FALSE(result);
+    EXPECT_EQ(alloc.GetShardCount(), 1);
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+    auto old = alloc.Allocate("still_usable", 100);
+    ASSERT_TRUE(old);
+    EXPECT_EQ(old->shard_idx, 0);
+    EXPECT_FALSE(alloc.Allocate("not_published", 100));
+    ASSERT_TRUE(std::filesystem::remove(blocked));
+    ASSERT_TRUE(alloc.ExpandShards(3));
+    EXPECT_EQ(alloc.GetShardCount(), 3);
+}
+
+TEST(DfsGlobalAllocatorTest, PreparedEvictionRemainsValidAcrossExpansion) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_eviction");
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096)));
+    auto old = alloc.Allocate("old", 100);
+    ASSERT_TRUE(old);
+    alloc.UpdateAccess("old", old->shard_idx, old->offset);
+    auto pending = alloc.PrepareEviction();
+    ASSERT_EQ(pending.Candidates().size(), 1);
+    ASSERT_TRUE(alloc.ExpandShards(2));
+    alloc.CommitPreparedEviction(std::move(pending));
+    auto after = alloc.Allocate("after", 100);
+    ASSERT_TRUE(after);
+    alloc.Free(after->offset, after->aligned_size, after->shard_idx, "after");
+    EXPECT_TRUE(alloc.PrepareEviction().Empty());
+}
+
+TEST(DfsGlobalAllocatorTest, ConcurrentExpansionAllocationAndEvictionRestore) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_expand_concurrent");
+    DfsGlobalAllocator alloc;
+    ASSERT_TRUE(alloc.Init(MakeAllocatorConfig(tmp.path(), 1, 1 << 20, 4096)));
+    std::atomic<bool> start{false};
+    std::atomic<int> failures{0};
+    std::vector<std::thread> workers;
+    for (int worker = 0; worker < 4; ++worker) {
+        workers.emplace_back([&, worker] {
+            while (!start.load()) std::this_thread::yield();
+            for (int i = 0; i < 200; ++i) {
+                const auto key = "worker_" + std::to_string(worker) + "_" +
+                                 std::to_string(i);
+                auto desc = alloc.Allocate(key, 100);
+                if (!desc) {
+                    ++failures;
+                    continue;
+                }
+                alloc.UpdateAccess(key, desc->shard_idx, desc->offset);
+                alloc.Free(desc->offset, desc->aligned_size, desc->shard_idx,
+                           key);
+            }
+        });
+    }
+    workers.emplace_back([&] {
+        while (!start.load()) std::this_thread::yield();
+        for (int i = 0; i < 200; ++i) {
+            auto pending = alloc.PrepareEviction();
+            alloc.RestorePreparedEviction(std::move(pending));
+        }
+    });
+    workers.emplace_back([&] {
+        while (!start.load()) std::this_thread::yield();
+        for (int count = 2; count <= 8; ++count) {
+            if (!alloc.ExpandShards(count)) ++failures;
+        }
+    });
+    start.store(true);
+    for (auto& worker : workers) worker.join();
+    EXPECT_EQ(failures.load(), 0);
+    EXPECT_EQ(alloc.GetShardCount(), 8);
+    EXPECT_TRUE(alloc.PrepareEviction().Empty());
+}
+
+TEST(ReplicaDfsTest, HelpersAndDescriptor) {
+    DistributedFSDescriptor desc{"/mnt/3fs/shard0.data", 4096, 100, 4096, 0};
+    Replica replica(desc, ReplicaStatus::PROCESSING);
+
+    EXPECT_TRUE(replica.is_dfs_replica());
+    EXPECT_FALSE(replica.is_memory_replica());
+    EXPECT_FALSE(replica.is_disk_replica());
+    EXPECT_FALSE(replica.is_nof_replica());
+    EXPECT_EQ(replica.type(), ReplicaType::DFS);
+    EXPECT_EQ(replica.get_dfs_descriptor().offset, 4096);
+
+    auto descriptor = replica.get_descriptor();
+    EXPECT_TRUE(descriptor.is_dfs_replica());
+    EXPECT_FALSE(descriptor.is_memory_replica());
+    EXPECT_EQ(descriptor.status, ReplicaStatus::PROCESSING);
+    EXPECT_EQ(descriptor.get_dfs_descriptor().object_size, 100);
+
+    EXPECT_TRUE(replica.is_processing());
+    replica.mark_complete();
+    EXPECT_TRUE(replica.is_completed());
+    replica.mark_processing();
+    EXPECT_TRUE(replica.is_processing());
+
+    EXPECT_EQ(replica.get_refcnt(), 0);
+    replica.inc_refcnt();
+    EXPECT_TRUE(replica.is_busy());
+    replica.dec_refcnt();
+    EXPECT_FALSE(replica.is_busy());
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.nof_replica_num = 0;
+    config.dfs_replica_num = 1;
+    EXPECT_EQ(DetermineReplicaWriteMode(config),
+              ReplicaWriteMode::RELIABLE_MULTI_REPLICA);
+}
+
+class DfsBackendTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        tmp_ = std::make_unique<TempDir>("dfs_backend");
+        FileStorageConfig file_config;
+        file_config.storage_backend_type = StorageBackendType::kDistributed;
+        file_config.storage_filepath = tmp_->path();
+
+        DistributedStorageConfig distributed_config;
+        distributed_config.fsdir = tmp_->path();
+        distributed_config.fs_adapter_type = "posix";
+        distributed_config.shard_count = 4;
+        distributed_config.shard_capacity = 64 * 1024 * 1024;
+        distributed_config.alignment = 4096;
+
+        // The master prepares shard files; client initialization only sets up
+        // the adapter and must not create or open files before descriptors.
+        PosixFsAdapter adapter;
+        ASSERT_TRUE(adapter.Init(tmp_->path()));
+        for (int i = 0; i < distributed_config.shard_count; ++i) {
+            ASSERT_TRUE(adapter.PreallocateFile(
+                ShardPath(i), distributed_config.shard_capacity));
+        }
+
+        backend_ = std::make_unique<DistributedStorageBackend>(
+            file_config, distributed_config,
+            std::make_unique<PosixFsAdapter>());
+        ASSERT_TRUE(backend_->Init().has_value());
+    }
+
+    void TearDown() override {
+        backend_.reset();
+        tmp_.reset();
+    }
+
+    std::string ShardPath(int shard_idx) const {
+        return tmp_->file("dfs_shard_" +
+                          DfsGlobalAllocator::FormatShardIdx(shard_idx, 4) +
+                          ".data");
+    }
+
+    std::unique_ptr<TempDir> tmp_;
+    std::unique_ptr<DistributedStorageBackend> backend_;
+};
+
+class ControlledPosixFsAdapter : public PosixFsAdapter {
+   public:
+    void FailOpenCall(int call) { fail_open_call_ = call; }
+    int OpenCallCount() const { return open_calls_.load(); }
+
+    tl::expected<int, ErrorCode> OpenFile(const std::string& path) override {
+        if (++open_calls_ == fail_open_call_) {
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+        return PosixFsAdapter::OpenFile(path);
+    }
+
+    void FailWriteCall(int call) { fail_write_call_ = call; }
+    void ShortWriteCall(int call) { short_write_call_ = call; }
+    void FailReadCall(int call) { fail_read_call_ = call; }
+    void ShortReadCall(int call) { short_read_call_ = call; }
+    int WriteCallCount() const { return write_calls_.load(); }
+    int ReadCallCount() const { return read_calls_.load(); }
+
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override {
+        const int call = ++write_calls_;
+        if (call == fail_write_call_) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        if (call == short_write_call_) {
+            size_t total_size = 0;
+            for (int i = 0; i < iovcnt; ++i) {
+                total_size += iov[i].iov_len;
+            }
+            return total_size == 0 ? 0 : total_size - 1;
+        }
+        return PosixFsAdapter::WriteAt(fd, iov, iovcnt, offset);
+    }
+
+    tl::expected<size_t, ErrorCode> ReadAt(int fd, iovec* iov, int iovcnt,
+                                           int64_t offset) override {
+        const int call = ++read_calls_;
+        if (call == fail_read_call_) {
+            return tl::make_unexpected(ErrorCode::FILE_OPEN_FAIL);
+        }
+        if (call == short_read_call_) {
+            size_t total_size = 0;
+            for (int i = 0; i < iovcnt; ++i) {
+                total_size += iov[i].iov_len;
+            }
+            return total_size == 0 ? 0 : total_size - 1;
+        }
+        return PosixFsAdapter::ReadAt(fd, iov, iovcnt, offset);
+    }
+
+   private:
+    std::atomic<int> open_calls_{0};
+    int fail_open_call_ = -1;
+    std::atomic<int> write_calls_{0};
+    std::atomic<int> read_calls_{0};
+    int fail_write_call_ = -1;
+    int short_write_call_ = -1;
+    int fail_read_call_ = -1;
+    int short_read_call_ = -1;
+};
+
+class BlockingShardFsAdapter : public PosixFsAdapter {
+   public:
+    BlockingShardFsAdapter(std::string path, bool block_file_size)
+        : path_(std::move(path)), block_file_size_(block_file_size) {}
+
+    bool WaitUntilBlocked() {
+        return blocked_.wait_for(std::chrono::seconds(5)) ==
+               std::future_status::ready;
+    }
+
+    void Release() {
+        if (!released_once_.exchange(true)) release_signal_.set_value();
+    }
+
+    int OpenCallCount() const { return open_calls_.load(); }
+
+    tl::expected<size_t, ErrorCode> GetFileSize(
+        const std::string& path) override {
+        if (path == path_ && block_file_size_) Block();
+        return PosixFsAdapter::GetFileSize(path);
+    }
+
+    tl::expected<int, ErrorCode> OpenFile(const std::string& path) override {
+        if (path == path_) {
+            ++open_calls_;
+            if (!block_file_size_) Block();
+        }
+        return PosixFsAdapter::OpenFile(path);
+    }
+
+   private:
+    void Block() {
+        if (!blocked_once_.exchange(true)) blocked_signal_.set_value();
+        released_.wait();
+    }
+
+    std::string path_;
+    bool block_file_size_;
+    std::atomic<int> open_calls_{0};
+    std::atomic<bool> blocked_once_{false};
+    std::atomic<bool> released_once_{false};
+    std::promise<void> blocked_signal_;
+    std::future<void> blocked_{blocked_signal_.get_future()};
+    std::promise<void> release_signal_;
+    std::shared_future<void> released_{release_signal_.get_future().share()};
+};
+
+TEST_F(DfsBackendTest, SlowShardInitializationDoesNotBlockOtherShards) {
+    for (bool block_file_size : {false, true}) {
+        SCOPED_TRACE(block_file_size ? "GetFileSize" : "OpenFile");
+        FileStorageConfig file_config;
+        file_config.storage_backend_type = StorageBackendType::kDistributed;
+        file_config.storage_filepath = tmp_->path();
+        auto config =
+            MakeAllocatorConfig(tmp_->path(), 4, 64 * 1024 * 1024, 4096);
+        config.fs_adapter_type = "posix";
+        auto adapter = std::make_unique<BlockingShardFsAdapter>(
+            ShardPath(1), block_file_size);
+        auto* controlled = adapter.get();
+        backend_ = std::make_unique<DistributedStorageBackend>(
+            file_config, config, std::move(adapter));
+        ASSERT_TRUE(backend_->Init());
+
+        auto write_and_read = [&](int index, uint64_t offset) {
+            std::string input(4096, 'V'), output(4096, '\0');
+            const DistributedFSDescriptor descriptor{ShardPath(index), offset,
+                                                     4096, 4096, index};
+            auto writes = backend_->BatchWrite(
+                {{"value", descriptor, {{input.data(), input.size()}}}});
+            auto reads = backend_->BatchRead(
+                {{"value", descriptor, {{output.data(), output.size()}}}});
+            return writes.size() == 1 && writes[0] && reads.size() == 1 &&
+                   reads[0] && output == input;
+        };
+        ASSERT_TRUE(write_and_read(0, 0));
+
+        // Release the adapter before waiting on any async future's destructor,
+        // including when an assertion fails while initialization is blocked.
+        std::future<bool> first, same_shard, other_shards;
+        struct ReleaseOnExit {
+            BlockingShardFsAdapter* adapter;
+            ~ReleaseOnExit() { adapter->Release(); }
+        } release{controlled};
+        first = std::async(std::launch::async,
+                           [&] { return write_and_read(1, 0); });
+        ASSERT_TRUE(controlled->WaitUntilBlocked());
+        same_shard = std::async(std::launch::async,
+                                [&] { return write_and_read(1, 4096); });
+        other_shards = std::async(std::launch::async, [&] {
+            std::string output(4096, '\0');
+            auto reads =
+                backend_->BatchRead({{"cached",
+                                      {ShardPath(0), 0, 4096, 4096, 0},
+                                      {{output.data(), output.size()}}}});
+            return reads.size() == 1 && reads[0] &&
+                   output == std::string(4096, 'V') &&
+                   write_and_read(0, 4096) && write_and_read(2, 0);
+        });
+        EXPECT_EQ(other_shards.wait_for(std::chrono::seconds(5)),
+                  std::future_status::ready);
+        EXPECT_EQ(same_shard.wait_for(std::chrono::seconds(0)),
+                  std::future_status::timeout);
+        controlled->Release();
+        EXPECT_TRUE(first.get());
+        EXPECT_TRUE(same_shard.get());
+        EXPECT_TRUE(other_shards.get());
+        EXPECT_EQ(controlled->OpenCallCount(), 1);
+    }
+}
+
+TEST(DfsBackendInitializationTest, ClientBeforeMasterDoesNotCreateShards) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_client_before_master");
+    const auto client_config = MakeAllocatorConfig(tmp.path(), 4, 8192, 4096);
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp.path();
+    DistributedStorageBackend client(file_config, client_config,
+                                     std::make_unique<PosixFsAdapter>());
+    ASSERT_TRUE(client.Init());
+    EXPECT_TRUE(std::filesystem::is_empty(tmp.path()));
+
+    DfsGlobalAllocator allocator;
+    ASSERT_TRUE(allocator.Init(MakeAllocatorConfig(tmp.path(), 1, 8192, 4096)));
+    EXPECT_EQ(allocator.GetShardCount(), 1);
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+    ASSERT_TRUE(allocator.ExpandShards(4));
+    auto descriptor = allocator.Allocate("after_master_start", 100);
+    ASSERT_TRUE(descriptor);
+    std::string value(100, 'S'), output(100, '\0');
+    auto writes = client.BatchWrite(
+        {{"after_master_start", *descriptor, {{value.data(), value.size()}}}});
+    ASSERT_EQ(writes.size(), 1);
+    ASSERT_TRUE(writes[0]);
+    auto reads = client.BatchRead({{"after_master_start",
+                                    *descriptor,
+                                    {{output.data(), output.size()}}}});
+    ASSERT_EQ(reads.size(), 1);
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, value);
+}
+
+TEST(DfsBackendInitializationTest, DoesNotCacheRolledBackPreparedShard) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_prepared_shard_rollback");
+    auto config = MakeAllocatorConfig(tmp.path(), 1, 8192, 4096);
+    DfsGlobalAllocator allocator;
+    ASSERT_TRUE(allocator.Init(config));
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    const auto path = tmp.file("dfs_shard_01.data");
+    // Reproduce the preparation window before an expansion publishes shard 1.
+    ASSERT_TRUE(adapter.PreallocateFile(path, config.shard_capacity));
+    const int prepared_fd = ::open(path.c_str(), O_RDONLY);
+    ASSERT_GE(prepared_fd, 0);
+    struct stat prepared_stat{};
+    ASSERT_EQ(::fstat(prepared_fd, &prepared_stat), 0);
+
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp.path();
+    auto client_config = config;
+    client_config.shard_count = 2;
+    DistributedStorageBackend writer(file_config, client_config,
+                                     std::make_unique<PosixFsAdapter>());
+    ASSERT_TRUE(writer.Init());
+    // A failed expansion removes the unpublished file. Keep its old inode
+    // alive until retry creates a different file with the same pathname.
+    ASSERT_TRUE(std::filesystem::remove(path));
+    ASSERT_TRUE(allocator.ExpandShards(2));
+    struct stat published_stat{};
+    ASSERT_EQ(::stat(path.c_str(), &published_stat), 0);
+    EXPECT_NE(prepared_stat.st_ino, published_stat.st_ino);
+    ASSERT_EQ(::close(prepared_fd), 0);
+
+    std::string key;
+    for (int i = 0; i < 1000; ++i) {
+        key = "retry_shard_" + std::to_string(i);
+        if (std::hash<std::string>{}(key) % 2 == 1) break;
+    }
+    ASSERT_EQ(std::hash<std::string>{}(key) % 2, 1);
+    auto descriptor = allocator.Allocate(key, 100);
+    ASSERT_TRUE(descriptor);
+    ASSERT_EQ(descriptor->shard_idx, 1);
+    std::string value(100, 'R'), output(100, '\0');
+    auto writes =
+        writer.BatchWrite({{key, *descriptor, {{value.data(), value.size()}}}});
+    ASSERT_EQ(writes.size(), 1);
+    ASSERT_TRUE(writes[0]);
+    DistributedStorageBackend reader(file_config, config,
+                                     std::make_unique<PosixFsAdapter>());
+    ASSERT_TRUE(reader.Init());
+    auto reads = reader.BatchRead(
+        {{key, *descriptor, {{output.data(), output.size()}}}});
+    ASSERT_EQ(reads.size(), 1);
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, value);
+}
+
+TEST(DfsBackendInitializationTest, OpensLegacyPaddedDescriptorWithoutAliases) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_backend_legacy_padding");
+    const auto config = MakeAllocatorConfig(tmp.path(), 2, 8192, 4096);
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp.path()));
+    const auto path = tmp.file("dfs_shard_000.data");
+    ASSERT_TRUE(adapter.PreallocateFile(path, config.shard_capacity));
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp.path();
+    DistributedStorageBackend client(file_config, config,
+                                     std::make_unique<PosixFsAdapter>());
+    ASSERT_TRUE(client.Init());
+    const DistributedFSDescriptor descriptor{path, 0, 100, 4096, 0};
+    std::string value(100, 'L'), output(100, '\0');
+    auto writes = client.BatchWrite(
+        {{"legacy", descriptor, {{value.data(), value.size()}}}});
+    ASSERT_EQ(writes.size(), 1);
+    ASSERT_TRUE(writes[0]);
+    auto reads = client.BatchRead(
+        {{"legacy", descriptor, {{output.data(), output.size()}}}});
+    ASSERT_EQ(reads.size(), 1);
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, value);
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_00.data")));
+    EXPECT_FALSE(std::filesystem::exists(tmp.file("dfs_shard_01.data")));
+}
+
+// Four shard files exist before initialization. A descriptor published after
+// capacity expansion must work without restarting that existing client.
+TEST_F(DfsBackendTest, OpensNewShardDescriptorAfterClientInitialization) {
+    const std::string new_path = ShardPath(4);
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp_->path()));
+    ASSERT_TRUE(adapter.PreallocateFile(new_path, 64 * 1024 * 1024));
+
+    AlignedBuffer expected(4096), actual(4096);
+    ASSERT_NE(expected.data(), nullptr);
+    ASSERT_NE(actual.data(), nullptr);
+    expected.Fill('N');
+    actual.Fill('X');
+    const DistributedFSDescriptor descriptor{new_path, 0, 4096, 4096, 4};
+
+    auto writes = backend_->BatchWrite(
+        {{"new_shard", descriptor, {{expected.data(), expected.size()}}}});
+    ASSERT_EQ(writes.size(), 1);
+    ASSERT_TRUE(writes[0].has_value());
+    auto reads = backend_->BatchRead(
+        {{"new_shard", descriptor, {{actual.data(), actual.size()}}}});
+    ASSERT_EQ(reads.size(), 1);
+    ASSERT_TRUE(reads[0].has_value());
+    EXPECT_EQ(std::memcmp(expected.data(), actual.data(), expected.size()), 0);
+}
+
+TEST_F(DfsBackendTest, LazyOpenRetriesAfterOpenFailure) {
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp_->path();
+    auto config = MakeAllocatorConfig(tmp_->path(), 4, 64 * 1024 * 1024, 4096);
+    config.fs_adapter_type = "posix";
+    auto adapter = std::make_unique<ControlledPosixFsAdapter>();
+    auto* controlled = adapter.get();
+    controlled->FailOpenCall(1);
+    backend_ = std::make_unique<DistributedStorageBackend>(file_config, config,
+                                                           std::move(adapter));
+    ASSERT_TRUE(backend_->Init());
+
+    std::string input(4096, 'R'), output(4096, '\0');
+    const DistributedFSDescriptor descriptor{ShardPath(1), 0, 4096, 4096, 1};
+    const std::vector<DfsWriteRequest> request{
+        {"retry", descriptor, {{input.data(), input.size()}}}};
+    auto failed = backend_->BatchWrite(request);
+    ASSERT_EQ(failed.size(), 1);
+    ASSERT_FALSE(failed[0]);
+    EXPECT_EQ(failed[0].error(), ErrorCode::FILE_OPEN_FAIL);
+    auto retried = backend_->BatchWrite(request);
+    ASSERT_EQ(retried.size(), 1);
+    ASSERT_TRUE(retried[0]);
+    auto reads = backend_->BatchRead(
+        {{"retry", descriptor, {{output.data(), output.size()}}}});
+    ASSERT_EQ(reads.size(), 1);
+    ASSERT_TRUE(reads[0]);
+    EXPECT_EQ(output, input);
+    EXPECT_EQ(controlled->OpenCallCount(), 2);
+}
+
+TEST_F(DfsBackendTest, LazyOpenRejectsMissingAndMalformedShardFiles) {
+    AlignedBuffer value(4096);
+    ASSERT_NE(value.data(), nullptr);
+    value.Fill('V');
+    const auto missing = ShardPath(4);
+    auto write = backend_->BatchWrite({{"missing",
+                                        {missing, 0, 4096, 4096, 4},
+                                        {{value.data(), value.size()}}}});
+    ASSERT_EQ(write.size(), 1);
+    EXPECT_FALSE(write[0]);
+    EXPECT_FALSE(std::filesystem::exists(missing));
+
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp_->path()));
+    ASSERT_TRUE(adapter.PreallocateFile(missing, 8192));
+    write = backend_->BatchWrite({{"wrong_capacity",
+                                   {missing, 0, 4096, 4096, 4},
+                                   {{value.data(), value.size()}}}});
+    ASSERT_EQ(write.size(), 1);
+    ASSERT_FALSE(write[0]);
+    EXPECT_EQ(write[0].error(), ErrorCode::INVALID_PARAMS);
+
+    const auto mismatched = ShardPath(5);
+    ASSERT_TRUE(adapter.PreallocateFile(mismatched, 64 * 1024 * 1024));
+    write = backend_->BatchWrite({{"wrong_index",
+                                   {mismatched, 0, 4096, 4096, 4},
+                                   {{value.data(), value.size()}}}});
+    ASSERT_EQ(write.size(), 1);
+    ASSERT_FALSE(write[0]);
+    EXPECT_EQ(write[0].error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(DfsBackendTest, ConcurrentLazyOpenPreservesIndependentWrites) {
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp_->path()));
+    const auto path = ShardPath(4);
+    ASSERT_TRUE(adapter.PreallocateFile(path, 64 * 1024 * 1024));
+    std::atomic<bool> start{false};
+    std::atomic<int> failures{0};
+    std::vector<std::thread> workers;
+    for (int i = 0; i < 8; ++i) {
+        workers.emplace_back([&, i] {
+            AlignedBuffer input(4096), output(4096);
+            if (!input.data() || !output.data()) {
+                ++failures;
+                return;
+            }
+            input.Fill(static_cast<char>('A' + i));
+            output.Fill('X');
+            const DistributedFSDescriptor descriptor{
+                path, static_cast<uint64_t>(i) * 4096, 4096, 4096, 4};
+            while (!start.load()) std::this_thread::yield();
+            auto writes =
+                backend_->BatchWrite({{std::to_string(i),
+                                       descriptor,
+                                       {{input.data(), input.size()}}}});
+            auto reads =
+                backend_->BatchRead({{std::to_string(i),
+                                      descriptor,
+                                      {{output.data(), output.size()}}}});
+            if (writes.size() != 1 || !writes[0] || reads.size() != 1 ||
+                !reads[0] ||
+                std::memcmp(input.data(), output.data(), input.size())) {
+                ++failures;
+            }
+        });
+    }
+    start.store(true);
+    for (auto& worker : workers) worker.join();
+    EXPECT_EQ(failures.load(), 0);
+}
+
+TEST_F(DfsBackendTest, BatchWriteUsesExplicitDescriptors) {
+    AlignedBuffer write_buf(4096);
+    ASSERT_NE(write_buf.data(), nullptr);
+    write_buf.Fill('E');
+
+    std::vector<DfsWriteRequest> requests{
+        {"explicit",
+         {ShardPath(1), 0, 4096, 4096, 1},
+         {{write_buf.data(), write_buf.size()}}},
+        {"bad_path",
+         {tmp_->file("wrong.data"), 4096, 4096, 4096, 0},
+         {{write_buf.data(), write_buf.size()}}},
+        {"bad_size",
+         {ShardPath(0), 4096, 2048, 4096, 0},
+         {{write_buf.data(), write_buf.size()}}},
+    };
+    auto results = backend_->BatchWrite(requests);
+    ASSERT_EQ(results.size(), 3);
+    EXPECT_TRUE(results[0].has_value());
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::INVALID_PARAMS);
+    ASSERT_FALSE(results[2].has_value());
+    EXPECT_EQ(results[2].error(), ErrorCode::INVALID_PARAMS);
+
+    AlignedBuffer read_buf(4096);
+    auto read_results =
+        backend_->BatchRead({{"explicit",
+                              requests[0].descriptor,
+                              {{read_buf.data(), read_buf.size()}}}});
+    ASSERT_EQ(read_results.size(), 1);
+    ASSERT_TRUE(read_results[0].has_value());
+    EXPECT_EQ(std::memcmp(write_buf.data(), read_buf.data(), write_buf.size()),
+              0);
+}
+
+TEST_F(DfsBackendTest, BatchWritePreservesPerKeyWriteErrors) {
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp_->path();
+
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = tmp_->path();
+    distributed_config.fs_adapter_type = "posix";
+    distributed_config.shard_count = 4;
+    distributed_config.shard_capacity = 64 * 1024 * 1024;
+    distributed_config.alignment = 4096;
+
+    auto adapter = std::make_unique<ControlledPosixFsAdapter>();
+    auto* controlled_adapter = adapter.get();
+    auto backend = std::make_unique<DistributedStorageBackend>(
+        file_config, distributed_config, std::move(adapter));
+    ASSERT_TRUE(backend->Init().has_value());
+    controlled_adapter->FailWriteCall(2);
+    controlled_adapter->ShortWriteCall(3);
+
+    AlignedBuffer write_buf(4096);
+    ASSERT_NE(write_buf.data(), nullptr);
+    std::vector<DfsWriteRequest> requests{
+        {"ok",
+         {ShardPath(0), 0, 4096, 4096, 0},
+         {{write_buf.data(), write_buf.size()}}},
+        {"failed",
+         {ShardPath(0), 4096, 4096, 4096, 0},
+         {{write_buf.data(), write_buf.size()}}},
+        {"short",
+         {ShardPath(0), 8192, 4096, 4096, 0},
+         {{write_buf.data(), write_buf.size()}}},
+    };
+    auto results = backend->BatchWrite(requests);
+    ASSERT_EQ(results.size(), 3);
+    EXPECT_TRUE(results[0].has_value());
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::FILE_WRITE_FAIL);
+    ASSERT_FALSE(results[2].has_value());
+    EXPECT_EQ(results[2].error(), ErrorCode::FILE_WRITE_FAIL);
+}
+
+TEST_F(DfsBackendTest, BatchReadUsesExplicitDescriptorsAndMultipleSlices) {
+    AlignedBuffer first_value(4096), second_value(4096);
+    ASSERT_NE(first_value.data(), nullptr);
+    ASSERT_NE(second_value.data(), nullptr);
+    first_value.Fill('R');
+    second_value.Fill('S');
+
+    const DistributedFSDescriptor first_desc{ShardPath(0), 0, 4096, 4096, 0};
+    const DistributedFSDescriptor second_desc{ShardPath(0), 4096, 4096, 4096,
+                                              0};
+    auto write_results = backend_->BatchWrite(
+        {{"same_key", first_desc, {{first_value.data(), first_value.size()}}},
+         {"other_key",
+          second_desc,
+          {{second_value.data(), second_value.size()}}}});
+    ASSERT_EQ(write_results.size(), 2);
+    ASSERT_TRUE(write_results[0].has_value());
+    ASSERT_TRUE(write_results[1].has_value());
+
+    AlignedBuffer output_0(1024), output_1(3072), unused(64);
+    ASSERT_NE(output_0.data(), nullptr);
+    ASSERT_NE(output_1.data(), nullptr);
+    ASSERT_NE(unused.data(), nullptr);
+    unused.Fill('U');
+    std::vector<DfsReadRequest> requests{
+        {"same_key",
+         first_desc,
+         {{output_0.data(), output_0.size()},
+          {output_1.data(), output_1.size()},
+          {unused.data(), unused.size()}}},
+        {"too_small", first_desc, {{output_0.data(), output_0.size()}}},
+        {"null_slice", first_desc, {{nullptr, first_desc.object_size}}},
+    };
+    auto read_results = backend_->BatchRead(requests);
+    ASSERT_EQ(read_results.size(), requests.size());
+    ASSERT_TRUE(read_results[0].has_value());
+    ASSERT_FALSE(read_results[1].has_value());
+    EXPECT_EQ(read_results[1].error(), ErrorCode::INVALID_PARAMS);
+    ASSERT_FALSE(read_results[2].has_value());
+    EXPECT_EQ(read_results[2].error(), ErrorCode::INVALID_PARAMS);
+
+    EXPECT_EQ(std::memcmp(first_value.data(), output_0.data(), output_0.size()),
+              0);
+    EXPECT_EQ(std::memcmp(first_value.data() + output_0.size(), output_1.data(),
+                          output_1.size()),
+              0);
+    for (size_t i = 0; i < unused.size(); ++i) {
+        EXPECT_EQ(unused.data()[i], 'U');
+    }
+}
+
+TEST_F(DfsBackendTest, BatchReadPreservesPerKeyErrors) {
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp_->path();
+
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = tmp_->path();
+    distributed_config.fs_adapter_type = "posix";
+    distributed_config.shard_count = 4;
+    distributed_config.shard_capacity = 64 * 1024 * 1024;
+    distributed_config.alignment = 4096;
+
+    auto adapter = std::make_unique<ControlledPosixFsAdapter>();
+    auto* controlled_adapter = adapter.get();
+    auto backend = std::make_unique<DistributedStorageBackend>(
+        file_config, distributed_config, std::move(adapter));
+    ASSERT_TRUE(backend->Init().has_value());
+
+    AlignedBuffer write_buf(4096);
+    ASSERT_NE(write_buf.data(), nullptr);
+    write_buf.Fill('T');
+    std::vector<DfsWriteRequest> writes;
+    for (size_t i = 0; i < 4; ++i) {
+        writes.push_back({"key_" + std::to_string(i),
+                          {ShardPath(0), i * 4096, 4096, 4096, 0},
+                          {{write_buf.data(), write_buf.size()}}});
+    }
+    auto write_results = backend->BatchWrite(writes);
+    ASSERT_EQ(write_results.size(), writes.size());
+    for (const auto& result : write_results) {
+        ASSERT_TRUE(result.has_value());
+    }
+
+    controlled_adapter->FailReadCall(2);
+    controlled_adapter->ShortReadCall(3);
+    AlignedBuffer out0(4096), out1(4096), out2(4096), out3(4096);
+    std::vector<DfsReadRequest> reads{
+        {"ok_0", writes[0].descriptor, {{out0.data(), out0.size()}}},
+        {"failed", writes[1].descriptor, {{out1.data(), out1.size()}}},
+        {"short", writes[2].descriptor, {{out2.data(), out2.size()}}},
+        {"ok_3", writes[3].descriptor, {{out3.data(), out3.size()}}},
+    };
+    auto read_results = backend->BatchRead(reads);
+    ASSERT_EQ(read_results.size(), reads.size());
+    EXPECT_TRUE(read_results[0].has_value());
+    ASSERT_FALSE(read_results[1].has_value());
+    EXPECT_EQ(read_results[1].error(), ErrorCode::FILE_OPEN_FAIL);
+    ASSERT_FALSE(read_results[2].has_value());
+    EXPECT_EQ(read_results[2].error(), ErrorCode::FILE_READ_FAIL);
+    EXPECT_TRUE(read_results[3].has_value());
+    EXPECT_EQ(std::memcmp(write_buf.data(), out3.data(), write_buf.size()), 0);
+}
+
+TEST_F(DfsBackendTest, RejectsInvalidDescriptorRangesBeforeIo) {
+    constexpr uint64_t kShardCapacity = 64 * 1024 * 1024;
+
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp_->path();
+
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = tmp_->path();
+    distributed_config.fs_adapter_type = "posix";
+    distributed_config.shard_count = 4;
+    distributed_config.shard_capacity = kShardCapacity;
+    distributed_config.alignment = 4096;
+
+    auto adapter = std::make_unique<ControlledPosixFsAdapter>();
+    auto* controlled_adapter = adapter.get();
+    auto backend = std::make_unique<DistributedStorageBackend>(
+        file_config, distributed_config, std::move(adapter));
+    ASSERT_TRUE(backend->Init().has_value());
+
+    AlignedBuffer small_buf(4096);
+    AlignedBuffer large_buf(8192);
+    ASSERT_NE(small_buf.data(), nullptr);
+    ASSERT_NE(large_buf.data(), nullptr);
+
+    std::vector<DfsWriteRequest> requests{
+        {"past_capacity",
+         {ShardPath(0), kShardCapacity, 4096, 4096, 0},
+         {{small_buf.data(), small_buf.size()}}},
+        {"object_exceeds_allocation",
+         {ShardPath(0), 0, 8192, 4096, 0},
+         {{large_buf.data(), large_buf.size()}}},
+        {"overflow",
+         {ShardPath(0), std::numeric_limits<uint64_t>::max() - 4095, 4096, 4096,
+          0},
+         {{small_buf.data(), small_buf.size()}}},
+        {"unaligned_offset",
+         {ShardPath(0), 1, 4096, 4096, 0},
+         {{small_buf.data(), small_buf.size()}}},
+    };
+
+    auto write_results = backend->BatchWrite(requests);
+    ASSERT_EQ(write_results.size(), requests.size());
+    for (const auto& result : write_results) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+    EXPECT_EQ(controlled_adapter->WriteCallCount(), 0);
+
+    AlignedBuffer read_buf(8192);
+    ASSERT_NE(read_buf.data(), nullptr);
+    std::vector<DfsReadRequest> read_requests;
+    for (const auto& request : requests) {
+        read_requests.push_back({request.key,
+                                 request.descriptor,
+                                 {{read_buf.data(), read_buf.size()}}});
+    }
+    auto read_results = backend->BatchRead(read_requests);
+    ASSERT_EQ(read_results.size(), read_requests.size());
+    for (const auto& result : read_results) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+    EXPECT_EQ(controlled_adapter->ReadCallCount(), 0);
+}
+
+TEST_F(DfsBackendTest, KeyOnlyStorageBackendOperationsAreNotSupported) {
+    std::unordered_map<std::string, std::vector<Slice>> offload_batch;
+    auto offload_result = backend_->BatchOffload(
+        offload_batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_FALSE(offload_result.has_value());
+    EXPECT_EQ(offload_result.error(), ErrorCode::NOT_SUPPORTED);
+
+    std::unordered_map<std::string, Slice> load_batch;
+    auto load_result = backend_->BatchLoad(load_batch);
+    ASSERT_FALSE(load_result.has_value());
+    EXPECT_EQ(load_result.error(), ErrorCode::NOT_SUPPORTED);
+
+    auto exists_result = backend_->IsExist("key");
+    ASSERT_FALSE(exists_result.has_value());
+    EXPECT_EQ(exists_result.error(), ErrorCode::NOT_SUPPORTED);
+    auto enabled_result = backend_->IsEnableOffloading();
+    ASSERT_TRUE(enabled_result.has_value());
+    EXPECT_FALSE(*enabled_result);
+}
+
+TEST_F(DfsBackendTest, BatchReadAndWriteAcceptUnalignedBuffers) {
+    constexpr size_t kObjectSize = 1234;
+    AlignedBuffer write_storage(kObjectSize + 1);
+    AlignedBuffer read_storage(kObjectSize + 3);
+    ASSERT_NE(write_storage.data(), nullptr);
+    ASSERT_NE(read_storage.data(), nullptr);
+
+    char* write_ptr = write_storage.data() + 1;
+    char* read_ptr = read_storage.data() + 3;
+    ASSERT_NE(reinterpret_cast<std::uintptr_t>(write_ptr) % 4096, 0);
+    ASSERT_NE(reinterpret_cast<std::uintptr_t>(read_ptr) % 4096, 0);
+    for (size_t i = 0; i < kObjectSize; ++i) {
+        write_ptr[i] = static_cast<char>('a' + (i % 26));
+    }
+
+    const DistributedFSDescriptor descriptor{ShardPath(0), 0, kObjectSize, 4096,
+                                             0};
+    auto write_results = backend_->BatchWrite(
+        {{"unaligned", descriptor, {{write_ptr, kObjectSize}}}});
+    ASSERT_EQ(write_results.size(), 1);
+    ASSERT_TRUE(write_results[0].has_value());
+
+    auto read_results = backend_->BatchRead(
+        {{"unaligned", descriptor, {{read_ptr, kObjectSize}}}});
+    ASSERT_EQ(read_results.size(), 1);
+    ASSERT_TRUE(read_results[0].has_value());
+    EXPECT_EQ(std::memcmp(write_ptr, read_ptr, kObjectSize), 0);
+}
+
+TEST_F(DfsBackendTest, MultipleKeysAcrossShards) {
+    AlignedBuffer key0(4096), key1(4096), key2(8192);
+    ASSERT_NE(key0.data(), nullptr);
+    ASSERT_NE(key1.data(), nullptr);
+    ASSERT_NE(key2.data(), nullptr);
+    key0.Fill('A');
+    key1.Fill('B');
+    key2.Fill('C');
+
+    const std::vector<DistributedFSDescriptor> descriptors{
+        {ShardPath(0), 0, key0.size(), key0.size(), 0},
+        {ShardPath(0), 4096, key1.size(), key1.size(), 0},
+        {ShardPath(1), 0, key2.size(), key2.size(), 1},
+    };
+    auto write_results = backend_->BatchWrite(
+        {{"key0", descriptors[0], {{key0.data(), key0.size()}}},
+         {"key1", descriptors[1], {{key1.data(), key1.size()}}},
+         {"key2", descriptors[2], {{key2.data(), key2.size()}}}});
+    ASSERT_EQ(write_results.size(), 3);
+    EXPECT_TRUE(write_results[0].has_value());
+    EXPECT_TRUE(write_results[1].has_value());
+    EXPECT_TRUE(write_results[2].has_value());
+
+    AlignedBuffer out0(4096), out1(4096), out2(8192);
+    ASSERT_NE(out0.data(), nullptr);
+    ASSERT_NE(out1.data(), nullptr);
+    ASSERT_NE(out2.data(), nullptr);
+    auto read_results = backend_->BatchRead(
+        {{"key0", descriptors[0], {{out0.data(), out0.size()}}},
+         {"key1", descriptors[1], {{out1.data(), out1.size()}}},
+         {"key2", descriptors[2], {{out2.data(), out2.size()}}}});
+    ASSERT_EQ(read_results.size(), 3);
+    EXPECT_TRUE(read_results[0].has_value());
+    EXPECT_TRUE(read_results[1].has_value());
+    EXPECT_TRUE(read_results[2].has_value());
+    EXPECT_EQ(std::memcmp(key0.data(), out0.data(), key0.size()), 0);
+    EXPECT_EQ(std::memcmp(key1.data(), out1.data(), key1.size()), 0);
+    EXPECT_EQ(std::memcmp(key2.data(), out2.data(), key2.size()), 0);
+}
+
+TEST_F(DfsBackendTest, LargeObject) {
+    constexpr size_t kLargeSize = 33 * 1024 * 1024;
+    AlignedBuffer write_buf(kLargeSize);
+    ASSERT_NE(write_buf.data(), nullptr);
+    write_buf.Fill('L');
+    const DistributedFSDescriptor descriptor{ShardPath(2), 0, write_buf.size(),
+                                             write_buf.size(), 2};
+    auto write_results = backend_->BatchWrite(
+        {{"large", descriptor, {{write_buf.data(), write_buf.size()}}}});
+    ASSERT_EQ(write_results.size(), 1);
+    ASSERT_TRUE(write_results[0].has_value());
+
+    AlignedBuffer read_buf(kLargeSize);
+    ASSERT_NE(read_buf.data(), nullptr);
+    auto read_results = backend_->BatchRead(
+        {{"large", descriptor, {{read_buf.data(), read_buf.size()}}}});
+    ASSERT_EQ(read_results.size(), 1);
+    ASSERT_TRUE(read_results[0].has_value());
+    EXPECT_EQ(std::memcmp(write_buf.data(), read_buf.data(), kLargeSize), 0);
+}
+
+TEST_F(DfsBackendTest, FailurePaths) {
+    PosixFsAdapter adapter;
+    ASSERT_TRUE(adapter.Init(tmp_->path()).has_value());
+    char buf[64] = {};
+    iovec iov{buf, sizeof(buf)};
+    auto write = adapter.WriteAt(-1, &iov, 1, 0);
+    ASSERT_FALSE(write.has_value());
+    EXPECT_EQ(write.error(), ErrorCode::INVALID_PARAMS);
+
+    auto read =
+        adapter.ReadFile(tmp_->file("does_not_exist"), buf, sizeof(buf));
+    ASSERT_FALSE(read.has_value());
+    EXPECT_EQ(read.error(), ErrorCode::FILE_NOT_FOUND);
+}
+
+TEST(DfsStorageFactoryTest, CreatesDistributedBackendWithPosixAdapter) {
+    EnvGuard env;
+    ConfigurePosixDfs(env);
+    TempDir tmp("dfs_factory");
+    env.Set("MOONCAKE_DFS_ROOT_DIR", tmp.path().c_str());
+    env.Set("MOONCAKE_DFS_SHARD_COUNT", "2");
+    env.Set("MOONCAKE_DFS_SHARD_CAPACITY", "1048576");
+    env.Set("MOONCAKE_DFS_ALIGNMENT", "4096");
+    env.Set("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+    FileStorageConfig file_config;
+    file_config.storage_backend_type = StorageBackendType::kDistributed;
+    file_config.storage_filepath = tmp.path();
+
+    auto backend = CreateStorageBackend(file_config);
+    ASSERT_TRUE(backend.has_value());
+    ASSERT_NE(*backend, nullptr);
+    EXPECT_TRUE((*backend)->Init().has_value());
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/dfs_sync_client_test.cpp b/mooncake-store/tests/dfs_sync_client_test.cpp
new file mode 100644
index 0000000000..03de4b30c3
--- /dev/null
+++ b/mooncake-store/tests/dfs_sync_client_test.cpp
@@ -0,0 +1,567 @@
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+#include <array>
+
+#include <unistd.h>
+
+#include "client_service.h"
+#include "environ.h"
+#include "storage/distributed/dfs_global_allocator.h"
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/posix_fs_adapter.h"
+#include "test_server_helpers.h"
+#include "common/client_buffer_allocation.h"
+
+namespace mooncake::test {
+
+class FailingPosixFsAdapter : public PosixFsAdapter {
+   public:
+    int WriteCalls() const { return write_calls_.load(); }
+    void FailWriteCall(int call) { fail_write_call_.store(call); }
+
+    tl::expected<size_t, ErrorCode> WriteAt(int fd, const iovec* iov,
+                                            int iovcnt,
+                                            int64_t offset) override {
+        const int call = ++write_calls_;
+        if (call == fail_write_call_.load()) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+        return PosixFsAdapter::WriteAt(fd, iov, iovcnt, offset);
+    }
+
+   private:
+    std::atomic<int> write_calls_{0};
+    std::atomic<int> fail_write_call_{-1};
+};
+
+class DfsSyncClientTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        root_ = (std::filesystem::temp_directory_path() /
+                 ("dfs_sync_client_" + std::to_string(::getpid()) + "_" +
+                  std::to_string(++next_root_)))
+                    .string();
+        std::filesystem::create_directories(root_);
+
+        SetEnv("MOONCAKE_ENABLE_DFS", "1");
+        SetEnv("MOONCAKE_DFS_FS_ADAPTER", "posix");
+        SetEnv("MOONCAKE_DFS_ROOT_DIR", root_);
+        SetEnv("MOONCAKE_DFS_SHARD_COUNT", "2");
+        SetEnv("MOONCAKE_DFS_SHARD_CAPACITY", "16777216");
+        SetEnv("MOONCAKE_DFS_ALIGNMENT", "4096");
+        SetEnv("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+        SetEnv("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+        SetEnv("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+        ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()));
+        writer_ = CreateClient("127.0.0.1:18101");
+        provider_ = CreateClient("127.0.0.1:18102");
+        ASSERT_NE(writer_, nullptr);
+        ASSERT_NE(provider_, nullptr);
+
+        segment_size_ = 16 * 1024 * 1024;
+        segment_ = allocate_buffer_allocator_memory(segment_size_);
+        ASSERT_NE(segment_, nullptr);
+        ASSERT_TRUE(provider_->MountSegment(segment_, segment_size_, "tcp")
+                        .has_value());
+
+        FileStorageConfig file_config;
+        file_config.storage_backend_type = StorageBackendType::kDistributed;
+        file_config.storage_filepath = root_;
+
+        DistributedStorageConfig distributed_config;
+        distributed_config.fsdir = root_;
+        distributed_config.fs_adapter_type = "posix";
+        distributed_config.shard_count = 2;
+        distributed_config.shard_capacity = 16 * 1024 * 1024;
+        distributed_config.alignment = 4096;
+
+        auto adapter = std::make_unique<FailingPosixFsAdapter>();
+        adapter_ = adapter.get();
+        backend_ = std::make_shared<DistributedStorageBackend>(
+            file_config, distributed_config, std::move(adapter));
+        ASSERT_TRUE(backend_->Init().has_value());
+        writer_->SetDfsStorageBackend(backend_);
+    }
+
+    void TearDown() override {
+        if (provider_ && segment_) {
+            (void)provider_->UnmountSegment(segment_, segment_size_);
+        }
+        writer_.reset();
+        provider_.reset();
+        backend_.reset();
+        master_.Stop();
+        if (segment_) {
+            std::free(segment_);
+            segment_ = nullptr;
+        }
+        RestoreEnv();
+        std::error_code ec;
+        std::filesystem::remove_all(root_, ec);
+    }
+
+    std::shared_ptr<Client> CreateClient(const std::string& hostname) {
+        auto client = Client::Create(hostname, "P2PHANDSHAKE", "tcp",
+                                     std::nullopt, master_.master_address());
+        return client ? *client : nullptr;
+    }
+
+    ReplicateConfig DfsConfig() const {
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+        return config;
+    }
+
+    tl::expected<QueryResult, ErrorCode> QueryDfsOnly(const std::string& key) {
+        auto query = writer_->Query(key);
+        if (!query) {
+            return tl::make_unexpected(query.error());
+        }
+        std::vector<Replica::Descriptor> replicas;
+        for (const auto& replica : query->replicas) {
+            if (replica.is_dfs_replica()) {
+                replicas.push_back(replica);
+            }
+        }
+        if (replicas.empty()) {
+            return tl::make_unexpected(ErrorCode::INVALID_REPLICA);
+        }
+        return QueryResult(std::move(replicas), query->lease_timeout,
+                           query->object_checksum);
+    }
+
+    void ExpectDfsValue(const std::string& key, const std::string& expected) {
+        auto query = QueryDfsOnly(key);
+        ASSERT_TRUE(query.has_value());
+        last_read_lease_deadline_ = query->lease_timeout;
+        std::vector<char> output(expected.size());
+        const auto& descriptor = query->replicas[0].get_dfs_descriptor();
+        auto results = backend_->BatchRead(
+            {{key, descriptor, {{output.data(), output.size()}}}});
+        ASSERT_EQ(results.size(), 1);
+        ASSERT_TRUE(results[0].has_value());
+        EXPECT_EQ(std::memcmp(output.data(), expected.data(), expected.size()),
+                  0);
+    }
+
+    void WaitForReadLeaseExpiry() {
+        // The verification read holds a lease too. Allow the master's deadline
+        // to pass before testing the successful synchronous write path.
+        std::this_thread::sleep_until(last_read_lease_deadline_ +
+                                      std::chrono::milliseconds(100));
+    }
+
+    static std::vector<std::vector<Slice>> MakeSlices(
+        std::vector<std::string>& values) {
+        std::vector<std::vector<Slice>> slices;
+        slices.reserve(values.size());
+        for (auto& value : values) {
+            slices.push_back({Slice{value.data(), value.size()}});
+        }
+        return slices;
+    }
+
+    void SetEnv(const std::string& key, const std::string& value) {
+        const char* old_value = ::getenv(key.c_str());
+        saved_env_.push_back({key, old_value
+                                       ? std::optional<std::string>(old_value)
+                                       : std::nullopt});
+        ::setenv(key.c_str(), value.c_str(), 1);
+    }
+
+    void RestoreEnv() {
+        for (auto it = saved_env_.rbegin(); it != saved_env_.rend(); ++it) {
+            if (it->second) {
+                ::setenv(it->first.c_str(), it->second->c_str(), 1);
+            } else {
+                ::unsetenv(it->first.c_str());
+            }
+        }
+        saved_env_.clear();
+    }
+
+    inline static std::atomic<int> next_root_{0};
+    testing::InProcMaster master_;
+    std::shared_ptr<Client> writer_;
+    std::shared_ptr<Client> provider_;
+    std::shared_ptr<DistributedStorageBackend> backend_;
+    FailingPosixFsAdapter* adapter_ = nullptr;
+    void* segment_ = nullptr;
+    size_t segment_size_ = 0;
+    std::string root_;
+    std::chrono::steady_clock::time_point last_read_lease_deadline_{};
+    std::vector<std::pair<std::string, std::optional<std::string>>> saved_env_;
+};
+
+TEST_F(DfsSyncClientTest, PutAndUpsertReturnAfterDfsWrite) {
+    const std::string key = "sync_put_upsert";
+    std::string initial(4096, 'A');
+    std::vector<Slice> initial_slices{{initial.data(), initial.size()}};
+    ASSERT_TRUE(writer_->Put(key, initial_slices, DfsConfig()).has_value());
+    ExpectDfsValue(key, initial);
+
+    std::string updated(4096, 'B');
+    std::vector<Slice> updated_slices{{updated.data(), updated.size()}};
+    auto leased_upsert = writer_->Upsert(key, updated_slices, DfsConfig());
+    ASSERT_FALSE(leased_upsert.has_value());
+    EXPECT_EQ(leased_upsert.error(), ErrorCode::OBJECT_HAS_LEASE);
+    WaitForReadLeaseExpiry();
+    ASSERT_TRUE(writer_->Upsert(key, updated_slices, DfsConfig()).has_value());
+    ExpectDfsValue(key, updated);
+}
+
+TEST_F(DfsSyncClientTest, BatchPutAndBatchUpsertReturnAfterDfsWrite) {
+    std::vector<std::string> keys{"sync_batch_0", "sync_batch_1"};
+    std::vector<std::string> initial{std::string(4096, 'C'),
+                                     std::string(4096, 'D')};
+    auto initial_slices = MakeSlices(initial);
+    auto put_results = writer_->BatchPut(keys, initial_slices, DfsConfig());
+    ASSERT_EQ(put_results.size(), keys.size());
+    ASSERT_TRUE(put_results[0].has_value());
+    ASSERT_TRUE(put_results[1].has_value());
+    ExpectDfsValue(keys[0], initial[0]);
+    ExpectDfsValue(keys[1], initial[1]);
+
+    std::vector<std::string> updated{std::string(4096, 'E'),
+                                     std::string(4096, 'F')};
+    auto updated_slices = MakeSlices(updated);
+    auto leased_upserts =
+        writer_->BatchUpsert(keys, updated_slices, DfsConfig());
+    ASSERT_EQ(leased_upserts.size(), keys.size());
+    for (const auto& result : leased_upserts) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::OBJECT_HAS_LEASE);
+    }
+    WaitForReadLeaseExpiry();
+    auto upsert_results =
+        writer_->BatchUpsert(keys, updated_slices, DfsConfig());
+    ASSERT_EQ(upsert_results.size(), keys.size());
+    ASSERT_TRUE(upsert_results[0].has_value());
+    ASSERT_TRUE(upsert_results[1].has_value());
+    ExpectDfsValue(keys[0], updated[0]);
+    ExpectDfsValue(keys[1], updated[1]);
+}
+
+TEST_F(DfsSyncClientTest, PreferSameNodeBatchPutReturnsAfterDfsWrite) {
+    std::vector<std::string> keys{"sync_same_node_0", "sync_same_node_1"};
+    std::vector<std::string> values{std::string(4096, 'J'),
+                                    std::string(4096, 'K')};
+    auto slices = MakeSlices(values);
+    auto config = DfsConfig();
+    config.prefer_alloc_in_same_node = true;
+
+    auto results = writer_->BatchPut(keys, slices, config);
+    ASSERT_EQ(results.size(), keys.size());
+    ASSERT_TRUE(results[0].has_value());
+    ASSERT_TRUE(results[1].has_value());
+    ExpectDfsValue(keys[0], values[0]);
+    ExpectDfsValue(keys[1], values[1]);
+}
+
+TEST_F(DfsSyncClientTest, BatchDfsFailureOnlyRevokesFailedKey) {
+    std::vector<std::string> keys{"sync_success", "sync_failure"};
+    std::vector<std::string> values{std::string(4096, 'G'),
+                                    std::string(4096, 'H')};
+    auto slices = MakeSlices(values);
+    adapter_->FailWriteCall(adapter_->WriteCalls() + 2);
+
+    auto results = writer_->BatchPut(keys, slices, DfsConfig());
+    ASSERT_EQ(results.size(), keys.size());
+    EXPECT_TRUE(results[0].has_value());
+    ASSERT_FALSE(results[1].has_value());
+    EXPECT_EQ(results[1].error(), ErrorCode::FILE_WRITE_FAIL);
+    ExpectDfsValue(keys[0], values[0]);
+
+    auto failed_query = writer_->Query(keys[1]);
+    ASSERT_FALSE(failed_query.has_value());
+    EXPECT_EQ(failed_query.error(), ErrorCode::OBJECT_NOT_FOUND);
+}
+
+TEST_F(DfsSyncClientTest, MissingDfsBackendRevokesObject) {
+    auto client_without_backend = CreateClient("127.0.0.1:18103");
+    ASSERT_NE(client_without_backend, nullptr);
+    std::string value(4096, 'I');
+    std::vector<Slice> slices{{value.data(), value.size()}};
+
+    auto result =
+        client_without_backend->Put("sync_no_backend", slices, DfsConfig());
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    auto query = client_without_backend->Query("sync_no_backend");
+    ASSERT_FALSE(query.has_value());
+    EXPECT_EQ(query.error(), ErrorCode::OBJECT_NOT_FOUND);
+}
+
+TEST_F(DfsSyncClientTest, ExistingClientUsesOnlineExpandedDfsCapacity) {
+    const std::string old_key = "before_expansion";
+    std::string old_value(4096, 'O');
+    std::vector<Slice> old_slices{{old_value.data(), old_value.size()}};
+    ASSERT_TRUE(writer_->Put(old_key, old_slices, DfsConfig()));
+    auto old_query = QueryDfsOnly(old_key);
+    ASSERT_TRUE(old_query);
+    const auto old_path = old_query->replicas[0].get_dfs_descriptor().file_path;
+    auto expanded = master_.service()->ExpandDfsShards(4);
+    ASSERT_TRUE(expanded);
+    EXPECT_EQ(*expanded, 4);
+
+    std::string new_key;
+    for (int i = 0; i < 1000; ++i) {
+        new_key = "after_expansion_" + std::to_string(i);
+        if (std::hash<std::string>{}(new_key) % 4 == 3) break;
+    }
+    ASSERT_EQ(std::hash<std::string>{}(new_key) % 4, 3);
+    std::string value(4096, 'N');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(new_key, write_slices, DfsConfig()));
+    auto query = QueryDfsOnly(new_key);
+    ASSERT_TRUE(query);
+    EXPECT_EQ(query->replicas[0].get_dfs_descriptor().shard_idx, 3);
+    std::string output(value.size(), '\0');
+    std::vector<Slice> read_slices{{output.data(), output.size()}};
+    ASSERT_TRUE(writer_->Get(new_key, *query, read_slices));
+    EXPECT_EQ(output, value);
+    ExpectDfsValue(old_key, old_value);
+    auto after = QueryDfsOnly(old_key);
+    ASSERT_TRUE(after);
+    EXPECT_EQ(after->replicas[0].get_dfs_descriptor().file_path, old_path);
+}
+
+TEST_F(DfsSyncClientTest, GetReadsDfsIntoMultipleSlices) {
+    const std::string key = "dfs_multi_slice_get";
+    std::string value(4096, 'M');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(key, write_slices, DfsConfig()).has_value());
+
+    auto query = QueryDfsOnly(key);
+    ASSERT_TRUE(query.has_value());
+    std::vector<char> first(1024), second(3072);
+    std::vector<Slice> read_slices{{first.data(), first.size()},
+                                   {second.data(), second.size()}};
+    ASSERT_TRUE(writer_->Get(key, *query, read_slices).has_value());
+    EXPECT_EQ(std::memcmp(value.data(), first.data(), first.size()), 0);
+    EXPECT_EQ(
+        std::memcmp(value.data() + first.size(), second.data(), second.size()),
+        0);
+}
+
+TEST_F(DfsSyncClientTest, BatchGetUsesExplicitDfsDescriptors) {
+    std::vector<std::string> keys{"dfs_batch_read_0", "dfs_batch_read_1"};
+    std::vector<std::string> values{std::string(4096, 'N'),
+                                    std::string(4096, 'O')};
+    auto write_slices = MakeSlices(values);
+    auto put_results = writer_->BatchPut(keys, write_slices, DfsConfig());
+    ASSERT_EQ(put_results.size(), keys.size());
+    ASSERT_TRUE(put_results[0].has_value());
+    ASSERT_TRUE(put_results[1].has_value());
+
+    std::vector<QueryResult> queries;
+    queries.reserve(keys.size());
+    for (const auto& key : keys) {
+        auto query = QueryDfsOnly(key);
+        ASSERT_TRUE(query.has_value());
+        queries.push_back(*query);
+    }
+
+    std::vector<std::string> output{std::string(4096, '\0'),
+                                    std::string(4096, '\0')};
+    std::unordered_map<std::string, std::vector<Slice>> read_slices;
+    for (size_t i = 0; i < keys.size(); ++i) {
+        read_slices[keys[i]] = {{output[i].data(), output[i].size()}};
+    }
+    auto get_results = writer_->BatchGet(keys, queries, read_slices);
+    ASSERT_EQ(get_results.size(), keys.size());
+    ASSERT_TRUE(get_results[0].has_value());
+    ASSERT_TRUE(get_results[1].has_value());
+    EXPECT_EQ(output[0], values[0]);
+    EXPECT_EQ(output[1], values[1]);
+}
+
+TEST_F(DfsSyncClientTest, BatchGetVerifiesDfsChecksum) {
+    if (!Environ::Get().GetStoreChecksumEnabled()) {
+        GTEST_SKIP() << "MOONCAKE_STORE_CHECKSUM is not enabled";
+    }
+
+    const std::string key = "dfs_batch_checksum";
+    std::string value(4096, 'P');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(key, write_slices, DfsConfig()).has_value());
+
+    auto query = QueryDfsOnly(key);
+    ASSERT_TRUE(query.has_value());
+    ASSERT_TRUE(query->object_checksum.has_value());
+    std::vector<Replica::Descriptor> replicas = query->replicas;
+    std::vector<QueryResult> queries;
+    queries.emplace_back(
+        std::move(replicas), query->lease_timeout,
+        std::optional<uint64_t>(*query->object_checksum ^ uint64_t{1}));
+
+    std::string output(value.size(), '\0');
+    std::unordered_map<std::string, std::vector<Slice>> read_slices;
+    read_slices[key] = {{output.data(), output.size()}};
+    auto results = writer_->BatchGet({key}, queries, read_slices);
+    ASSERT_EQ(results.size(), 1);
+    ASSERT_FALSE(results[0].has_value());
+    EXPECT_EQ(results[0].error(), ErrorCode::CHECKSUM_MISMATCH);
+}
+
+TEST_F(DfsSyncClientTest, GetVerifiesDfsChecksumAndRecordsError) {
+    if (!Environ::Get().GetStoreChecksumEnabled()) {
+        GTEST_SKIP() << "MOONCAKE_STORE_CHECKSUM is not enabled";
+    }
+    auto* metric = writer_->GetDfsMetricPtr();
+    if (metric == nullptr) {
+        GTEST_SKIP() << "Client metrics are disabled";
+    }
+
+    const std::string key = "dfs_single_checksum";
+    std::string value(4096, 'V');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(key, write_slices, DfsConfig()).has_value());
+
+    auto query = QueryDfsOnly(key);
+    ASSERT_TRUE(query.has_value());
+    ASSERT_TRUE(query->object_checksum.has_value());
+
+    const std::array<std::string, 1> mismatch_label{
+        toString(ErrorCode::CHECKSUM_MISMATCH)};
+    const int64_t base_read_ops = metric->dfs_read_ops.value();
+    const int64_t base_errors = metric->dfs_read_errors.value(mismatch_label);
+
+    const std::optional<uint64_t> bad_checksum(*query->object_checksum ^
+                                               uint64_t{1});
+    std::vector<Replica::Descriptor> replicas = query->replicas;
+    QueryResult corrupted(std::move(replicas), query->lease_timeout,
+                          bad_checksum);
+
+    std::vector<char> output(value.size());
+    std::vector<Slice> read_slices{{output.data(), output.size()}};
+    auto result = writer_->Get(key, corrupted, read_slices);
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::CHECKSUM_MISMATCH);
+
+    // The I/O completed, so it still counts as a read op, exactly as in the
+    // batch path; the rejection lands in the error family instead.
+    EXPECT_EQ(metric->dfs_read_ops.value(), base_read_ops + 1);
+    EXPECT_EQ(metric->dfs_read_errors.value(mismatch_label), base_errors + 1);
+}
+
+TEST_F(DfsSyncClientTest, DfsMetricsCountSuccessfulWriteAndRead) {
+    auto* metric = writer_->GetDfsMetricPtr();
+    if (metric == nullptr) {
+        GTEST_SKIP() << "Client metrics are disabled";
+    }
+    const int64_t base_write_ops = metric->dfs_write_ops.value();
+    const int64_t base_write_bytes = metric->dfs_write_bytes.value();
+    const int64_t base_read_ops = metric->dfs_read_ops.value();
+    const int64_t base_read_bytes = metric->dfs_read_bytes.value();
+
+    const std::string key = "dfs_metric_success";
+    std::string value(4096, 'Q');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(key, write_slices, DfsConfig()).has_value());
+
+    EXPECT_EQ(metric->dfs_write_ops.value(), base_write_ops + 1);
+    EXPECT_EQ(metric->dfs_write_bytes.value(),
+              base_write_bytes + static_cast<int64_t>(value.size()));
+
+    auto query = QueryDfsOnly(key);
+    ASSERT_TRUE(query.has_value());
+    std::vector<char> output(value.size());
+    std::vector<Slice> read_slices{{output.data(), output.size()}};
+    ASSERT_TRUE(writer_->Get(key, *query, read_slices).has_value());
+
+    EXPECT_EQ(metric->dfs_read_ops.value(), base_read_ops + 1);
+    EXPECT_EQ(metric->dfs_read_bytes.value(),
+              base_read_bytes + static_cast<int64_t>(value.size()));
+    // Host-resident slices never go through the D2H staging path.
+    EXPECT_EQ(metric->dfs_writes_skipped.value(), 0);
+}
+
+TEST_F(DfsSyncClientTest, DfsMetricsCountWriteFailureSeparatelyFromOps) {
+    auto* metric = writer_->GetDfsMetricPtr();
+    if (metric == nullptr) {
+        GTEST_SKIP() << "Client metrics are disabled";
+    }
+    const std::array<std::string, 1> write_fail_label{
+        toString(ErrorCode::FILE_WRITE_FAIL)};
+    const int64_t base_write_ops = metric->dfs_write_ops.value();
+    const int64_t base_errors =
+        metric->dfs_write_errors.value(write_fail_label);
+
+    std::vector<std::string> keys{"dfs_metric_ok", "dfs_metric_fail"};
+    std::vector<std::string> values{std::string(4096, 'R'),
+                                    std::string(4096, 'S')};
+    auto slices = MakeSlices(values);
+    adapter_->FailWriteCall(adapter_->WriteCalls() + 2);
+
+    auto results = writer_->BatchPut(keys, slices, DfsConfig());
+    ASSERT_EQ(results.size(), keys.size());
+    ASSERT_TRUE(results[0].has_value());
+    ASSERT_FALSE(results[1].has_value());
+
+    // The failed key must not inflate ops/bytes; it lands in the error family
+    // instead, keyed by the ErrorCode name.
+    EXPECT_EQ(metric->dfs_write_ops.value(), base_write_ops + 1);
+    EXPECT_EQ(metric->dfs_write_errors.value(write_fail_label),
+              base_errors + 1);
+}
+
+TEST_F(DfsSyncClientTest, DfsMetricsRecordUnavailableBackend) {
+    auto client_without_backend = CreateClient("127.0.0.1:18104");
+    ASSERT_NE(client_without_backend, nullptr);
+    auto* metric = client_without_backend->GetDfsMetricPtr();
+    if (metric == nullptr) {
+        GTEST_SKIP() << "Client metrics are disabled";
+    }
+    const std::array<std::string, 1> unavailable_label{
+        toString(ErrorCode::DFS_SERVICE_UNAVAILABLE)};
+    ASSERT_EQ(metric->dfs_write_errors.value(unavailable_label), 0);
+
+    std::string value(4096, 'T');
+    std::vector<Slice> slices{{value.data(), value.size()}};
+    auto result = client_without_backend->Put("dfs_metric_no_backend", slices,
+                                              DfsConfig());
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    EXPECT_EQ(metric->dfs_write_errors.value(unavailable_label), 1);
+    EXPECT_EQ(metric->dfs_write_ops.value(), 0);
+}
+
+TEST_F(DfsSyncClientTest, DfsMetricsAppearInSerializedOutput) {
+    auto* metric = writer_->GetDfsMetricPtr();
+    if (metric == nullptr) {
+        GTEST_SKIP() << "Client metrics are disabled";
+    }
+    const std::string key = "dfs_metric_serialize";
+    std::string value(4096, 'U');
+    std::vector<Slice> write_slices{{value.data(), value.size()}};
+    ASSERT_TRUE(writer_->Put(key, write_slices, DfsConfig()).has_value());
+
+    auto serialized = writer_->SerializeMetrics();
+    ASSERT_TRUE(serialized.has_value());
+    EXPECT_NE(serialized->find("mooncake_dfs_write_bytes_total"),
+              std::string::npos);
+    EXPECT_NE(serialized->find("mooncake_dfs_write_ops_total"),
+              std::string::npos);
+
+    auto summary = writer_->GetSummaryMetrics();
+    ASSERT_TRUE(summary.has_value());
+    EXPECT_NE(summary->find("=== DFS Metrics Summary ==="), std::string::npos);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/distributed_storage_config_test.cpp b/mooncake-store/tests/distributed_storage_config_test.cpp
new file mode 100644
index 0000000000..bdd1c53320
--- /dev/null
+++ b/mooncake-store/tests/distributed_storage_config_test.cpp
@@ -0,0 +1,297 @@
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <functional>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "config/distributed_storage_config.h"
+
+namespace mooncake {
+
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        const char* value = std::getenv(name);
+        if (value != nullptr) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct DistributedStorageEnvironment {
+    ScopedEnvVar root_dir{"MOONCAKE_DFS_ROOT_DIR"};
+    ScopedEnvVar legacy_root_dir{"MOONCAKE_DISTRIBUTED_ROOT_DIR"};
+    ScopedEnvVar fs_adapter{"MOONCAKE_DFS_FS_ADAPTER"};
+    ScopedEnvVar legacy_fs_adapter{"MOONCAKE_DISTRIBUTED_FS_TYPE"};
+    ScopedEnvVar health_check{"MOONCAKE_DISTRIBUTED_HEALTH_CHECK"};
+    ScopedEnvVar shard_count{"MOONCAKE_DFS_SHARD_COUNT"};
+    ScopedEnvVar shard_capacity{"MOONCAKE_DFS_SHARD_CAPACITY"};
+    ScopedEnvVar alignment{"MOONCAKE_DFS_ALIGNMENT"};
+    ScopedEnvVar single_tenant{"MOONCAKE_DFS_SINGLE_TENANT"};
+    ScopedEnvVar eviction_enabled{"MOONCAKE_DFS_EVICTION_ENABLED"};
+    ScopedEnvVar eviction_high_watermark{
+        "MOONCAKE_DFS_EVICTION_HIGH_WATERMARK"};
+    ScopedEnvVar eviction_low_watermark{"MOONCAKE_DFS_EVICTION_LOW_WATERMARK"};
+    ScopedEnvVar deferred_free_seconds{"MOONCAKE_DFS_DEFERRED_FREE_SECONDS"};
+    ScopedEnvVar eviction_check_interval{
+        "MOONCAKE_DFS_EVICTION_CHECK_INTERVAL"};
+};
+
+void ExpectDefaultConfig(const DistributedStorageConfig& config) {
+    EXPECT_EQ(config.fsdir, "/mnt/3fs/mooncake");
+    EXPECT_EQ(config.fs_adapter_type, "hf3fs");
+    EXPECT_FALSE(config.enable_health_check);
+    EXPECT_EQ(config.shard_count, 64);
+    EXPECT_EQ(config.shard_capacity, 4ULL * 1024 * 1024 * 1024);
+    EXPECT_EQ(config.alignment, 4096);
+    EXPECT_TRUE(config.single_tenant);
+    EXPECT_TRUE(config.eviction_enabled);
+    EXPECT_DOUBLE_EQ(config.eviction_high_watermark, 0.9);
+    EXPECT_DOUBLE_EQ(config.eviction_low_watermark, 0.7);
+    EXPECT_EQ(config.deferred_free_duration, std::chrono::seconds(30));
+    EXPECT_EQ(config.eviction_check_interval, std::chrono::seconds(5));
+}
+
+DistributedStorageConfig ValidConfig() {
+    DistributedStorageConfig config;
+    config.fsdir = "/tmp/mooncake-distributed-storage";
+    config.fs_adapter_type = "posix";
+    config.shard_count = 8;
+    config.shard_capacity = 1024 * 1024;
+    config.alignment = 4096;
+    config.single_tenant = true;
+    config.eviction_enabled = true;
+    config.eviction_high_watermark = 0.85;
+    config.eviction_low_watermark = 0.65;
+    config.deferred_free_duration = std::chrono::seconds(12);
+    config.eviction_check_interval = std::chrono::seconds(3);
+    return config;
+}
+
+class DistributedStorageConfigTest : public ::testing::Test {
+   protected:
+    DistributedStorageEnvironment env;
+};
+
+TEST_F(DistributedStorageConfigTest, UsesDefaultsWhenEnvironmentIsUnset) {
+    const auto config = DistributedStorageConfig::FromEnvironment();
+
+    ExpectDefaultConfig(config);
+    EXPECT_TRUE(config.Validate());
+    EXPECT_TRUE(config.ValidateForAllocator());
+}
+
+TEST_F(DistributedStorageConfigTest, ReadsValidEnvironmentValues) {
+    env.root_dir.Set("/tmp/mooncake-dfs");
+    env.fs_adapter.Set("posix");
+    env.health_check.Set("true");
+    env.shard_count.Set("8");
+    env.shard_capacity.Set("1048576");
+    env.alignment.Set("4096");
+    env.single_tenant.Set("1");
+    env.eviction_enabled.Set("1");
+    env.eviction_high_watermark.Set("0.85");
+    env.eviction_low_watermark.Set("0.65");
+    env.deferred_free_seconds.Set("12");
+    env.eviction_check_interval.Set("3");
+
+    const auto config = DistributedStorageConfig::FromEnvironment();
+
+    EXPECT_EQ(config.fsdir, "/tmp/mooncake-dfs");
+    EXPECT_EQ(config.fs_adapter_type, "posix");
+    EXPECT_TRUE(config.enable_health_check);
+    EXPECT_EQ(config.shard_count, 8);
+    EXPECT_EQ(config.shard_capacity, 1048576);
+    EXPECT_EQ(config.alignment, 4096);
+    EXPECT_TRUE(config.single_tenant);
+    EXPECT_TRUE(config.eviction_enabled);
+    EXPECT_DOUBLE_EQ(config.eviction_high_watermark, 0.85);
+    EXPECT_DOUBLE_EQ(config.eviction_low_watermark, 0.65);
+    EXPECT_EQ(config.deferred_free_duration, std::chrono::seconds(12));
+    EXPECT_EQ(config.eviction_check_interval, std::chrono::seconds(3));
+    EXPECT_TRUE(config.Validate());
+    EXPECT_TRUE(config.ValidateForAllocator());
+
+    const std::string formatted = config.FormatStr();
+    EXPECT_NE(formatted.find("fs_adapter_type=posix"), std::string::npos);
+    EXPECT_NE(formatted.find("shard_count=8"), std::string::npos);
+    EXPECT_NE(formatted.find("eviction_high_watermark=0.85"),
+              std::string::npos);
+}
+
+TEST_F(DistributedStorageConfigTest, PreservesAliasPrecedence) {
+    env.legacy_root_dir.Set("/tmp/legacy-dfs");
+    env.legacy_fs_adapter.Set("posix");
+
+    const auto legacy = DistributedStorageConfig::FromEnvironment();
+    EXPECT_EQ(legacy.fsdir, "/tmp/legacy-dfs");
+    EXPECT_EQ(legacy.fs_adapter_type, "posix");
+
+    env.root_dir.Set("/tmp/preferred-dfs");
+    env.fs_adapter.Set("hf3fs");
+
+    const auto preferred = DistributedStorageConfig::FromEnvironment();
+    EXPECT_EQ(preferred.fsdir, "/tmp/preferred-dfs");
+    EXPECT_EQ(preferred.fs_adapter_type, "hf3fs");
+}
+
+TEST_F(DistributedStorageConfigTest, EmptyPreferredRootOverridesAlias) {
+    env.legacy_root_dir.Set("/tmp/legacy-dfs");
+    env.root_dir.Set("");
+
+    EXPECT_THROW(DistributedStorageConfig::FromEnvironment(),
+                 std::filesystem::filesystem_error);
+}
+
+TEST_F(DistributedStorageConfigTest, EmptyPreferredAdapterOverridesAlias) {
+    env.legacy_fs_adapter.Set("posix");
+    env.fs_adapter.Set("");
+
+    const auto config = DistributedStorageConfig::FromEnvironment();
+
+    EXPECT_TRUE(config.fs_adapter_type.empty());
+    EXPECT_FALSE(config.Validate());
+}
+
+TEST_F(DistributedStorageConfigTest, ConvertsRelativeRootToAbsolutePath) {
+    env.root_dir.Set("relative-dfs-root");
+
+    const auto config = DistributedStorageConfig::FromEnvironment();
+
+    EXPECT_EQ(config.fsdir,
+              std::filesystem::absolute("relative-dfs-root").string());
+}
+
+TEST_F(DistributedStorageConfigTest,
+       InvalidValuesUseDefaultsAndPreserveDiagnostics) {
+    env.health_check.Set("invalid");
+    env.shard_count.Set("invalid");
+    env.shard_capacity.Set("-1");
+    env.alignment.Set("18446744073709551616");
+    env.single_tenant.Set("invalid");
+    env.eviction_enabled.Set("invalid");
+    env.eviction_high_watermark.Set("invalid");
+    env.deferred_free_seconds.Set("invalid");
+    env.eviction_check_interval.Set("invalid");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = DistributedStorageConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    ExpectDefaultConfig(config);
+    for (const char* name : {
+             "MOONCAKE_DISTRIBUTED_HEALTH_CHECK",
+             "MOONCAKE_DFS_SHARD_COUNT",
+             "MOONCAKE_DFS_SHARD_CAPACITY",
+             "MOONCAKE_DFS_ALIGNMENT",
+             "MOONCAKE_DFS_SINGLE_TENANT",
+             "MOONCAKE_DFS_EVICTION_ENABLED",
+             "MOONCAKE_DFS_EVICTION_HIGH_WATERMARK",
+             "MOONCAKE_DFS_DEFERRED_FREE_SECONDS",
+             "MOONCAKE_DFS_EVICTION_CHECK_INTERVAL",
+         }) {
+        EXPECT_NE(logs.find(name), std::string::npos) << name;
+    }
+}
+
+TEST_F(DistributedStorageConfigTest,
+       EmptyWatermarksUseDefaultsWithoutDiagnostics) {
+    env.eviction_high_watermark.Set("");
+    env.eviction_low_watermark.Set("");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = DistributedStorageConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_DOUBLE_EQ(config.eviction_high_watermark, 0.9);
+    EXPECT_DOUBLE_EQ(config.eviction_low_watermark, 0.7);
+    EXPECT_TRUE(logs.empty());
+}
+
+TEST(DistributedStorageConfigValidationTest, RejectsInvalidBaseSettings) {
+    using Mutation =
+        std::pair<const char*, std::function<void(DistributedStorageConfig&)>>;
+    const std::vector<Mutation> mutations{
+        {"empty root", [](auto& config) { config.fsdir.clear(); }},
+        {"relative root", [](auto& config) { config.fsdir = "relative/path"; }},
+        {"unsupported adapter",
+         [](auto& config) { config.fs_adapter_type = "unsupported"; }},
+        {"zero shards", [](auto& config) { config.shard_count = 0; }},
+        {"zero capacity", [](auto& config) { config.shard_capacity = 0; }},
+        {"zero alignment", [](auto& config) { config.alignment = 0; }},
+        {"non-power-of-two alignment",
+         [](auto& config) { config.alignment = 3; }},
+        {"unaligned capacity",
+         [](auto& config) { config.shard_capacity += 1; }},
+        {"multi tenant", [](auto& config) { config.single_tenant = false; }},
+    };
+
+    for (const auto& [name, mutate] : mutations) {
+        SCOPED_TRACE(name);
+        auto config = ValidConfig();
+        mutate(config);
+        EXPECT_FALSE(config.Validate());
+    }
+}
+
+TEST(DistributedStorageConfigValidationTest, RejectsInvalidAllocatorSettings) {
+    using Mutation =
+        std::pair<const char*, std::function<void(DistributedStorageConfig&)>>;
+    const std::vector<Mutation> mutations{
+        {"negative low watermark",
+         [](auto& config) { config.eviction_low_watermark = -0.1; }},
+        {"high watermark above one",
+         [](auto& config) { config.eviction_high_watermark = 1.1; }},
+        {"unordered watermarks",
+         [](auto& config) { config.eviction_low_watermark = 0.85; }},
+        {"negative deferred free",
+         [](auto& config) {
+             config.deferred_free_duration = std::chrono::seconds(-1);
+         }},
+        {"zero eviction interval",
+         [](auto& config) {
+             config.eviction_check_interval = std::chrono::seconds(0);
+         }},
+    };
+
+    for (const auto& [name, mutate] : mutations) {
+        SCOPED_TRACE(name);
+        auto config = ValidConfig();
+        mutate(config);
+        EXPECT_FALSE(config.ValidateForAllocator());
+    }
+
+    auto eviction_disabled = ValidConfig();
+    eviction_disabled.eviction_enabled = false;
+    eviction_disabled.eviction_check_interval = std::chrono::seconds(0);
+    EXPECT_TRUE(eviction_disabled.ValidateForAllocator());
+}
+
+}  // namespace
+
+}  // namespace mooncake
diff --git a/mooncake-store/tests/dummy_client_get_buffer_test.cpp b/mooncake-store/tests/dummy_client_get_buffer_test.cpp
index 4ee6063b17..1bda47e0e1 100644
--- a/mooncake-store/tests/dummy_client_get_buffer_test.cpp
+++ b/mooncake-store/tests/dummy_client_get_buffer_test.cpp
@@ -5,6 +5,7 @@
 #include <gflags/gflags.h>
 #include <glog/logging.h>
 #include <gtest/gtest.h>
+#include <sys/mman.h>
 
 #include <chrono>
 #include <cstdlib>
@@ -14,11 +15,15 @@
 #include <string>
 #include <thread>
 #include <vector>
+#include <algorithm>
+#include <limits>
+#include <numeric>
 
+#include "common/network.h"
+#include "default_config.h"
 #include "dummy_client.h"
 #include "environ.h"
 #include "real_client.h"
-#include "default_config.h"
 #include "test_server_helpers.h"
 
 DEFINE_string(protocol, "tcp", "Transfer protocol: rdma|tcp");
@@ -43,8 +48,12 @@ static void RegisterRpcHandlers(coro_rpc::coro_rpc_server &server,
     server.register_handler<&RealClient::isExist_internal>(&rc);
     server.register_handler<&RealClient::getSize_internal>(&rc);
     server.register_handler<&RealClient::get_into_range_shm_helper>(&rc);
+    server.register_handler<&RealClient::get_into_ranges_shm_helper>(&rc);
+    server.register_handler<&RealClient::get_into_ranges_staged_shm_helper>(
+        &rc);
     server.register_handler<&RealClient::batch_get_into_dummy_helper>(&rc);
     server.register_handler<&RealClient::batch_put_from_dummy_helper>(&rc);
+    server.register_handler<&RealClient::allocate_buffer_dummy>(&rc);
     server.register_handler<&RealClient::acquire_hot_cache>(&rc);
     server.register_handler<&RealClient::release_hot_cache>(&rc);
     server.register_handler<&RealClient::batch_acquire_hot_cache>(&rc);
@@ -430,6 +439,144 @@ TEST_F(DummyClientGetBufferTest, BatchQueryPreservesObjectChecksum) {
               real_results[0]->object_checksum);
 }
 
+TEST_F(DummyClientGetBufferTest, ExternalHostRegistrationLifecycle) {
+    ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
+
+    constexpr size_t kSize = 4096;
+    std::vector<char> source(kSize);
+    std::vector<char> destination(kSize, 0);
+    std::iota(source.begin(), source.end(), 0);
+
+    ASSERT_EQ(dummy_client_->register_buffer(source.data(), kSize), 0);
+    ASSERT_EQ(dummy_client_->register_buffer(destination.data(), kSize), 0);
+    EXPECT_EQ(dummy_client_->register_buffer(source.data(), kSize), 0)
+        << "same range registration should be reference counted";
+    EXPECT_NE(dummy_client_->register_buffer(source.data(), kSize - 1), 0);
+    EXPECT_NE(dummy_client_->register_buffer(source.data() + 1, kSize - 1), 0);
+    EXPECT_NE(
+        dummy_client_->register_buffer(
+            reinterpret_cast<void *>(std::numeric_limits<uintptr_t>::max() - 3),
+            8),
+        0);
+
+    const std::string key = "dummy_external_host_lifecycle";
+    ASSERT_EQ(dummy_client_->put_from(key, source.data() + 128, 512), 0);
+    ASSERT_EQ(dummy_client_->get_into(key, destination.data() + 256, 512), 512);
+    EXPECT_TRUE(std::equal(source.begin() + 128, source.begin() + 640,
+                           destination.begin() + 256));
+
+    ASSERT_EQ(dummy_client_->unregister_buffer(source.data()), 0);
+    ASSERT_EQ(dummy_client_->put_from(key, source.data() + 128, 512), 0)
+        << "one duplicate unregister must keep registration alive";
+    ASSERT_EQ(dummy_client_->unregister_buffer(source.data()), 0);
+    EXPECT_NE(dummy_client_->unregister_buffer(source.data()), 0);
+    EXPECT_NE(dummy_client_->put_from(key, source.data(), 1), 0)
+        << "transfers after the final unregister must be rejected";
+    ASSERT_EQ(dummy_client_->unregister_buffer(destination.data()), 0);
+}
+
+TEST_F(DummyClientGetBufferTest,
+       UnregisterMissingRealBufferMappingIsIdempotent) {
+    auto client = RealClient::create();
+    ASSERT_NE(client, nullptr);
+
+    const auto result =
+        client->unregister_shm_buffer_internal(0x1234, UUID{1, 2});
+    EXPECT_TRUE(result.has_value());
+}
+
+TEST_F(DummyClientGetBufferTest, ExternalHostRangedRead) {
+    ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
+
+    const std::string key = "dummy_external_host_ranged_read";
+    const std::string data = "0123456789abcdefghijklmnopqrstuvwxyz";
+    PutData(key, data);
+
+    std::vector<char> destination(32, '_');
+    ASSERT_EQ(
+        dummy_client_->register_buffer(destination.data(), destination.size()),
+        0);
+
+    const auto results = dummy_client_->get_into_ranges(
+        {destination.data()}, {{key}}, {{{4, 20}}}, {{{2, 10}}}, {{{6, 8}}});
+    ASSERT_EQ(results.size(), 1);
+    ASSERT_EQ(results[0].size(), 1);
+    ASSERT_EQ(results[0][0], (std::vector<int64_t>{6, 8}));
+    EXPECT_EQ(std::string(destination.begin() + 4, destination.begin() + 10),
+              data.substr(2, 6));
+    EXPECT_EQ(std::string(destination.begin() + 20, destination.begin() + 28),
+              data.substr(10, 8));
+    EXPECT_EQ(destination[0], '_');
+    EXPECT_EQ(destination[15], '_');
+
+    ASSERT_EQ(dummy_client_->unregister_buffer(destination.data()), 0);
+    const auto rejected = dummy_client_->get_into_ranges(
+        {destination.data()}, {{key}}, {{{4, 20}}}, {{{2, 10}}}, {{{6, 8}}});
+    ASSERT_EQ(rejected.size(), 1);
+    ASSERT_EQ(rejected[0].size(), 1);
+    EXPECT_EQ(rejected[0][0],
+              (std::vector<int64_t>{toInt(ErrorCode::INVALID_PARAMS),
+                                    toInt(ErrorCode::INVALID_PARAMS)}));
+}
+
+// A sparse destination larger than the staging pool must cost only the bytes
+// requested. mmap keeps the regression's large unused gaps physically unbacked.
+TEST_F(DummyClientGetBufferTest, ExternalHostSparseRangedReadBeyondPool) {
+    ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
+    const std::string key = "dummy_external_sparse_ranges";
+    const std::string data = "0123456789";
+    PutData(key, data);
+
+    constexpr size_t capacity = kLocalBufSize + 4096;
+    void *mapping = mmap(nullptr, capacity, PROT_READ | PROT_WRITE,
+                         MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    ASSERT_NE(mapping, MAP_FAILED);
+    auto unmap = [](void *ptr) { munmap(ptr, capacity); };
+    std::unique_ptr<void, decltype(unmap)> owner(mapping, unmap);
+    auto *destination = static_cast<char *>(mapping);
+    ASSERT_EQ(dummy_client_->register_buffer(destination, capacity), 0);
+    destination[0] = '_';
+    destination[1] = '_';
+    destination[capacity - 2] = '_';
+    destination[capacity - 1] = '_';
+
+    auto direct = dummy_client_->allocate_client_buffer(8);
+    ASSERT_TRUE(direct.has_value());
+    // Mixed SHM/external buffers, distant fragments, zero bytes at capacity,
+    // invalid destination/source ranges, and a missing key in one RPC.
+    const auto results = dummy_client_->get_into_ranges(
+        {destination, direct->ptr()}, {{key, key + "_missing"}, {key}},
+        {{{capacity - 1, 0, capacity, capacity, capacity + 1,
+           std::numeric_limits<size_t>::max(), capacity - 2},
+          {1}},
+         {{2}}},
+        {{{0, 1, 0, 0, 0, 0, data.size()}, {0}}, {{3}}},
+        {{{1, 1, 0, 1, 0, 1, 1}, {1}}, {{2}}});
+    ASSERT_EQ(results.size(), 2);
+    ASSERT_EQ(results[0].size(), 2);
+    ASSERT_EQ(results[0][0].size(), 7);
+    EXPECT_EQ(results[0][0][0], 1);
+    EXPECT_EQ(results[0][0][1], 1);
+    EXPECT_EQ(results[0][0][2], 0);
+    for (size_t i = 3; i < 7; ++i) EXPECT_LT(results[0][0][i], 0);
+    ASSERT_EQ(results[0][1].size(), 1);
+    EXPECT_LT(results[0][1][0], 0);
+    EXPECT_EQ(results[1], (std::vector<std::vector<int64_t>>{{2}}));
+    EXPECT_EQ(destination[capacity - 1], '0');
+    EXPECT_EQ(destination[0], '1');
+    EXPECT_EQ(destination[capacity - 2], '_');
+    EXPECT_EQ(destination[1], '_');
+    EXPECT_EQ(std::string(static_cast<char *>(direct->ptr()) + 2, 2), "34");
+
+    // Registration lookup and copy-back must also work from an interior base.
+    const auto interior = dummy_client_->get_into_ranges(
+        {destination + 1}, {{key}}, {{{capacity - 2}}}, {{{2}}}, {{{1}}});
+    EXPECT_EQ(interior,
+              (std::vector<std::vector<std::vector<int64_t>>>{{{1}}}));
+    EXPECT_EQ(destination[capacity - 1], '2');
+    ASSERT_EQ(dummy_client_->unregister_buffer(destination), 0);
+}
+
 // ---- Test: get_buffer via hot cache shm zero-copy path ----
 TEST_F(DummyClientGetBufferTest, GetBuffer_HotCachePath) {
     ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
diff --git a/mooncake-store/tests/dummy_client_probe_key_test.cpp b/mooncake-store/tests/dummy_client_probe_key_test.cpp
new file mode 100644
index 0000000000..b8ba20c60d
--- /dev/null
+++ b/mooncake-store/tests/dummy_client_probe_key_test.cpp
@@ -0,0 +1,160 @@
+// dummy_client_probe_key_test.cpp
+// Verifies DummyClient::probeKey / batchProbeKey over the DummyClient ->
+// RealClient RPC boundary: argument/result serialization, the int
+// conversion in DummyClient, and the round trip down to the master.
+//
+// The handler list below is local to this test, mirroring
+// dummy_client_get_buffer_test.cpp. The production list lives in
+// RegisterClientRpcService() in real_client_main.cpp, which tests cannot
+// link against, so this test cannot catch a handler that is missing
+// there.
+
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <memory>
+#include <span>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "dummy_client.h"
+#include "real_client.h"
+#include "test_server_helpers.h"
+
+DEFINE_string(protocol, "tcp", "Transfer protocol: rdma|tcp");
+DEFINE_string(device_name, "", "Device name to use, valid if protocol=rdma");
+
+namespace mooncake {
+namespace testing {
+
+// Handlers this test needs. Kept minimal on purpose: setup/teardown plus
+// the two probe RPCs under test.
+static void RegisterRpcHandlers(coro_rpc::coro_rpc_server &server,
+                                RealClient &rc) {
+    server.register_handler<&RealClient::service_ready_internal>(&rc);
+    server.register_handler<&RealClient::ping>(&rc);
+    server.register_handler<&RealClient::map_shm_internal>(&rc);
+    server.register_handler<&RealClient::unmap_shm_internal>(&rc);
+    server.register_handler<&RealClient::unregister_shm_buffer_internal>(&rc);
+    server.register_handler<&RealClient::probeKey_internal>(&rc);
+    server.register_handler<&RealClient::batchProbeKey_internal>(&rc);
+}
+
+static constexpr size_t kMB = 1024ULL * 1024;
+static constexpr size_t kSegmentSize = 128 * kMB;
+static constexpr size_t kLocalBufSize = 64 * kMB;
+static constexpr size_t kPoolSize = 64 * kMB;
+
+class DummyClientProbeKeyTest : public ::testing::Test {
+   protected:
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("DummyClientProbeKeyTest");
+        FLAGS_logtostderr = 1;
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void SetUp() override {
+        if (getenv("PROTOCOL")) FLAGS_protocol = getenv("PROTOCOL");
+        if (getenv("DEVICE_NAME")) FLAGS_device_name = getenv("DEVICE_NAME");
+    }
+
+    void TearDown() override {
+        // Mute ylt/coro_rpc "operation canceled" noise during shutdown
+        easylog::set_min_severity(easylog::Severity::FATAL);
+        if (dummy_client_) dummy_client_->tearDownAll();
+        if (rpc_server_) rpc_server_->stop();
+        if (real_client_) real_client_->tearDownAll();
+        master_.Stop();
+        easylog::set_min_severity(easylog::Severity::WARN);
+    }
+
+    // Bring up master + RealClient + RPC server + DummyClient.
+    bool SetupStack() {
+        if (!master_.Start(InProcMasterConfigBuilder().build())) return false;
+
+        real_client_ = RealClient::create();
+        const std::string rdma_devices =
+            (FLAGS_protocol == "rdma") ? FLAGS_device_name : "";
+        ipc_path_ = "@probe_key_test_" + std::to_string(getpid()) + ".sock";
+        if (real_client_->setup_real(
+                "localhost:17819", "P2PHANDSHAKE", kSegmentSize, kLocalBufSize,
+                FLAGS_protocol, rdma_devices, master_.master_address(), nullptr,
+                ipc_path_) != 0) {
+            return false;
+        }
+
+        rpc_port_ = getFreeTcpPort();
+        rpc_server_ = std::make_unique<coro_rpc::coro_rpc_server>(
+            /*thread_num=*/2, /*port=*/rpc_port_, /*address=*/"127.0.0.1",
+            std::chrono::seconds(0), /*tcp_no_delay=*/true);
+        RegisterRpcHandlers(*rpc_server_, *real_client_);
+        auto ec = rpc_server_->async_start();
+        if (ec.hasResult()) return false;
+        std::this_thread::sleep_for(std::chrono::milliseconds(200));
+
+        dummy_client_ = std::make_shared<DummyClient>();
+        const std::string rpc_addr = "127.0.0.1:" + std::to_string(rpc_port_);
+        return dummy_client_->setup_dummy(kPoolSize, kLocalBufSize, rpc_addr,
+                                          ipc_path_) == 0;
+    }
+
+    void PutData(const std::string &key, const std::string &data) {
+        std::span<const char> span(data.data(), data.size());
+        ReplicateConfig config;
+        config.replica_num = 1;
+        ASSERT_EQ(real_client_->put(key, span, config), 0);
+    }
+
+    mooncake::testing::InProcMaster master_;
+    std::shared_ptr<RealClient> real_client_;
+    std::shared_ptr<DummyClient> dummy_client_;
+    std::unique_ptr<coro_rpc::coro_rpc_server> rpc_server_;
+    int rpc_port_ = 0;
+    std::string ipc_path_;
+};
+
+TEST_F(DummyClientProbeKeyTest, ProbeKeyOverRpcReportsExistence) {
+    ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
+
+    const std::string key = "probe_rpc_key";
+    PutData(key, std::string(1024, 'p'));
+
+    // 1 means the object existed at the time of the call. A negative result
+    // here means the handler was never registered.
+    EXPECT_EQ(dummy_client_->probeKey(key), 1)
+        << "probeKey should report an existing key as 1 over the RPC path";
+
+    EXPECT_EQ(dummy_client_->probeKey("probe_rpc_missing_key"), 0)
+        << "probeKey should report a missing key as 0, not an error";
+}
+
+TEST_F(DummyClientProbeKeyTest, BatchProbeKeyOverRpcReportsExistence) {
+    ASSERT_TRUE(SetupStack()) << "Failed to bring up real+dummy stack";
+
+    const std::string key_a = "batch_probe_rpc_key_a";
+    const std::string key_b = "batch_probe_rpc_key_b";
+    PutData(key_a, std::string(1024, 'a'));
+    PutData(key_b, std::string(1024, 'b'));
+
+    const std::vector<std::string> keys = {key_a, "batch_probe_rpc_missing",
+                                           key_b};
+    auto results = dummy_client_->batchProbeKey(keys);
+    ASSERT_EQ(results.size(), keys.size());
+    EXPECT_EQ(results[0], 1) << key_a << " should exist";
+    EXPECT_EQ(results[1], 0) << "missing key should be 0, not an error";
+    EXPECT_EQ(results[2], 1) << key_b << " should exist";
+}
+
+}  // namespace testing
+}  // namespace mooncake
+
+int main(int argc, char **argv) {
+    ::testing::InitGoogleTest(&argc, argv);
+    gflags::ParseCommandLineFlags(&argc, &argv, false);
+    return RUN_ALL_TESTS();
+}
diff --git a/mooncake-store/tests/dynamic_replication_lease_table_test.cpp b/mooncake-store/tests/dynamic_replication_lease_table_test.cpp
new file mode 100644
index 0000000000..d912dc620c
--- /dev/null
+++ b/mooncake-store/tests/dynamic_replication_lease_table_test.cpp
@@ -0,0 +1,140 @@
+#include "dynamic_replication_lease_table.h"
+
+#include <chrono>
+#include <cstdint>
+#include <string>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+// A lease for `proposal_id` with the deadline given outright, so a suite
+// decides when it expires.
+ReplicaActionLease MakeLease(const UUID& proposal_id, const std::string& key,
+                             int64_t expire_at_ms_epoch) {
+    ReplicaActionLease lease;
+    lease.proposal_id = proposal_id;
+    lease.lease_id = proposal_id;
+    lease.key = key;
+    lease.expire_at_ms_epoch = expire_at_ms_epoch;
+    return lease;
+}
+
+int64_t EpochMillis(std::chrono::system_clock::time_point tp) {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               tp.time_since_epoch())
+        .count();
+}
+
+TEST(DynamicReplicationLeaseTableTest, IsKeyedByProposalId) {
+    DynamicReplicationLeaseTable table;
+    EXPECT_TRUE(table.Empty());
+
+    // An in-flight proposal keeps the table non-empty until it is removed or
+    // expires.
+    const UUID proposal{1, 2};
+    table.Put(proposal, MakeLease(proposal, "k1", 0));
+    EXPECT_FALSE(table.Empty());
+
+    auto found = table.Find(proposal);
+    ASSERT_TRUE(found.has_value());
+    EXPECT_EQ(found->key, "k1");
+
+    // An unknown proposal finds nothing.
+    EXPECT_FALSE(table.Find(UUID{9, 9}).has_value());
+
+    EXPECT_TRUE(table.Remove(proposal));
+    EXPECT_FALSE(table.Remove(proposal));
+    EXPECT_FALSE(table.Find(proposal).has_value());
+    EXPECT_TRUE(table.Empty());
+}
+
+TEST(DynamicReplicationLeaseTableTest, ReplaceMovesTheProposalToItsNewKey) {
+    DynamicReplicationLeaseTable table;
+    const UUID proposal{1, 2};
+    table.Put(proposal, MakeLease(proposal, "k1", 0));
+    table.Put(proposal, MakeLease(proposal, "k2", 0));
+
+    // Retracting the old key must not touch a lease that no longer sits under
+    // it, and the key the lease moved to is the one that retracts it.
+    table.EraseForObject("k1");
+    EXPECT_TRUE(table.Find(proposal).has_value());
+
+    table.EraseForObject("k2");
+    EXPECT_FALSE(table.Find(proposal).has_value());
+}
+
+TEST(DynamicReplicationLeaseTableTest,
+     ErasingForAnObjectDropsItsProposalsOnly) {
+    DynamicReplicationLeaseTable table;
+    const UUID first{1, 2};
+    const UUID second{3, 4};
+    const UUID other_key{5, 6};
+    table.Put(first, MakeLease(first, "k1", 0));
+    table.Put(second, MakeLease(second, "k1", 0));  // several may be in flight
+    table.Put(other_key, MakeLease(other_key, "k2", 0));
+
+    table.EraseForObject("k1");
+
+    EXPECT_FALSE(table.Find(first).has_value());
+    EXPECT_FALSE(table.Find(second).has_value());
+    EXPECT_TRUE(table.Find(other_key).has_value());
+
+    table.EraseForObject("k1");  // nothing left to retract
+    EXPECT_TRUE(table.Find(other_key).has_value());
+}
+
+TEST(DynamicReplicationLeaseTableTest, ErasingExpiredKeepsTheLiveOnes) {
+    DynamicReplicationLeaseTable table;
+    const auto now = std::chrono::system_clock::now();
+    const UUID expired{1, 2};
+    const UUID live{3, 4};
+    // One key on purpose: the sweep has to drop the expired proposal without
+    // taking the live one, or its key, out with it.
+    table.Put(expired, MakeLease(expired, "k1", EpochMillis(now) - 1));
+    table.Put(live, MakeLease(live, "k1", EpochMillis(now) + 60'000));
+
+    table.EraseExpired(now);
+
+    EXPECT_FALSE(table.Find(expired).has_value());
+    EXPECT_TRUE(table.Find(live).has_value());
+
+    // The key still retracts what is left under it.
+    table.EraseForObject("k1");
+    EXPECT_FALSE(table.Find(live).has_value());
+}
+
+TEST(DynamicReplicationLeaseTableTest, SweepKeepsALeaseExtendedPastTheOldOne) {
+    DynamicReplicationLeaseTable table;
+    const auto now = std::chrono::system_clock::now();
+    const UUID proposal{1, 2};
+    table.Put(proposal, MakeLease(proposal, "k1", EpochMillis(now) + 1'000));
+    const int64_t extended = EpochMillis(now) + 60'000;
+    table.Put(proposal, MakeLease(proposal, "k1", extended));
+
+    // The first deadline is still queued; it must not take the live lease out.
+    table.EraseExpired(now + std::chrono::seconds(10));
+    auto found = table.Find(proposal);
+    ASSERT_TRUE(found.has_value());
+    EXPECT_EQ(found->expire_at_ms_epoch, extended);
+
+    table.EraseExpired(now + std::chrono::minutes(2));
+    EXPECT_FALSE(table.Find(proposal).has_value());
+    EXPECT_TRUE(table.Empty());
+}
+
+TEST(DynamicReplicationLeaseTableTest, SweepToleratesARemovedLeasesDeadline) {
+    DynamicReplicationLeaseTable table;
+    const auto now = std::chrono::system_clock::now();
+    const UUID proposal{1, 2};
+    table.Put(proposal, MakeLease(proposal, "k1", EpochMillis(now) + 1'000));
+    ASSERT_TRUE(table.Remove(proposal));
+
+    // The deadline is still queued even though the lease is gone.
+    table.EraseExpired(now + std::chrono::seconds(10));
+    EXPECT_TRUE(table.Empty());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/dynamic_replication_test.cpp b/mooncake-store/tests/dynamic_replication_test.cpp
new file mode 100644
index 0000000000..6de988d2e9
--- /dev/null
+++ b/mooncake-store/tests/dynamic_replication_test.cpp
@@ -0,0 +1,1112 @@
+// Unit tests for dynamic MEMORY replica fanout on hot reads.
+
+#include "master_service.h"
+#include "master_service/master_service_test_peer.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <chrono>
+#include <optional>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace mooncake::test {
+
+class DynamicReplicationTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging("DynamicReplicationTest");
+        FLAGS_logtostderr = true;
+    }
+
+    void TearDown() override { google::ShutdownGoogleLogging(); }
+
+    static constexpr size_t kDefaultSegmentSize = 16 * 1024 * 1024;
+
+    struct MountedSegmentContext {
+        UUID client_id;
+        UUID segment_id;
+        std::string segment_name;
+    };
+
+    MountedSegmentContext PrepareSegment(MasterService& service,
+                                         std::string name, size_t base) const {
+        Segment segment;
+        segment.id = generate_uuid();
+        segment.name = std::move(name);
+        segment.base = base;
+        segment.size = kDefaultSegmentSize;
+        segment.te_endpoint = segment.name;
+        UUID client_id = generate_uuid();
+        auto mount_result = service.MountSegment(segment, client_id);
+        EXPECT_TRUE(mount_result.has_value());
+        return {.client_id = client_id,
+                .segment_id = segment.id,
+                .segment_name = segment.name};
+    }
+
+    void PutObject(MasterService& service, const UUID& client_id,
+                   const std::string& key,
+                   const std::string& preferred_segment) const {
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.preferred_segment = preferred_segment;
+        auto put_start =
+            service.PutStart(client_id, key, TenantId::Default(), 1024, config);
+        ASSERT_TRUE(put_start.has_value());
+        auto put_end = service.PutEnd(client_id, key, TenantId::Default(),
+                                      ReplicaType::MEMORY);
+        ASSERT_TRUE(put_end.has_value());
+    }
+
+    void AdmitDynamicReplication(MasterService& service,
+                                 const std::string& key) const {
+        for (uint32_t i = 0; i < MasterServiceTestPeer(service)
+                                     .DynamicReplicationAdmissionMinHits();
+             ++i) {
+            ObserveDynamicReplicationAccess(service, key);
+        }
+    }
+
+    std::vector<TaskAssignment> WaitForTasks(MasterService& service,
+                                             const UUID& client_id,
+                                             size_t expected) const {
+        std::vector<TaskAssignment> last;
+        for (int i = 0; i < 100; ++i) {
+            auto tasks = service.FetchTasks(client_id, 16);
+            EXPECT_TRUE(tasks.has_value());
+            if (!tasks.has_value()) {
+                return last;
+            }
+            if (tasks->size() >= expected) {
+                return *tasks;
+            }
+            last = *tasks;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return last;
+    }
+
+    ReplicaActionProposal BuildProposal(
+        MasterService& service, const std::string& key,
+        const std::optional<std::string>& preferred_target_segment =
+            std::nullopt,
+        bool admit = true) const {
+        ReplicaActionProposal proposal;
+        proposal.action = ReplicaActionType::ADD;
+        proposal.proposal_id = generate_uuid();
+        proposal.tenant_id = TenantId::Default().value();
+        proposal.key = key;
+        proposal.expire_at_ms_epoch =
+            MasterServiceTestPeer::DynamicReplicationNowMs() +
+            std::chrono::seconds(30).count() * 1000;
+        if (preferred_target_segment.has_value()) {
+            proposal.preferred_target_segment = *preferred_target_segment;
+        }
+
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        EXPECT_TRUE(accessor.Exists());
+        if (accessor.Exists()) {
+            const auto& metadata = accessor.Get();
+            proposal.observed_version_epoch =
+                MasterServiceTestPeer(service).DynamicReplicationVersionEpoch(
+                    metadata);
+            proposal.object_size_bytes = static_cast<uint64_t>(metadata.size);
+        }
+        if (admit) {
+            AdmitDynamicReplication(service, key);
+        }
+        return proposal;
+    }
+
+    size_t DynamicReplicaCount(MasterService& service,
+                               const std::string& key) const {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        EXPECT_TRUE(accessor.Exists());
+        return accessor.Exists() ? accessor.Get().DynamicReplicaCount() : 0;
+    }
+
+    bool HasCompleteDynamicReplica(MasterService& service,
+                                   const std::string& key,
+                                   const std::string& target_segment) const {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        EXPECT_TRUE(accessor.Exists());
+        if (!accessor.Exists()) {
+            return false;
+        }
+        for (const auto& [replica_id, record] :
+             accessor.Get().dynamic_replicas) {
+            (void)replica_id;
+            if (record.target_segment == target_segment && record.complete) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    bool HasIncompleteDynamicReplica(MasterService& service,
+                                     const std::string& key,
+                                     const std::string& target_segment) const {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        EXPECT_TRUE(accessor.Exists());
+        if (!accessor.Exists()) {
+            return false;
+        }
+        return std::any_of(accessor.Get().dynamic_replicas.begin(),
+                           accessor.Get().dynamic_replicas.end(),
+                           [&target_segment](const auto& entry) {
+                               return entry.second.target_segment ==
+                                          target_segment &&
+                                      !entry.second.complete;
+                           });
+    }
+
+    void BumpVersionEpoch(MasterService& service,
+                          const std::string& key) const {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        ASSERT_TRUE(accessor.Exists());
+        accessor.Get().put_start_time += std::chrono::milliseconds(1);
+    }
+
+    bool HasDynamicState(MasterService& service, const std::string& key) const {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        auto& tenant_state = accessor.GetTenantState();
+        const bool has_lease = std::any_of(
+            tenant_state.dynamic_replication_leases.begin(),
+            tenant_state.dynamic_replication_leases.end(),
+            [&key](const auto& entry) { return entry.second.key == key; });
+        return tenant_state.dynamic_replication_pending.contains(key) ||
+               tenant_state.dynamic_replication_cooldowns.contains(key) ||
+               has_lease;
+    }
+
+    size_t DynamicReplicationWindowEntryLimit() const {
+        return MasterServiceTestPeer::kDynamicReplicationWindowEntryLimit;
+    }
+
+    size_t DynamicReplicationWindowCount(MasterService& service) const {
+        return MasterServiceTestPeer::DynamicReplicationWindows(service).size();
+    }
+
+    void ExpireDynamicReplicationWindows(MasterService& service) const {
+        const auto stale_start =
+            std::chrono::steady_clock::now() - std::chrono::seconds(3);
+        for (auto& [_, window] :
+             MasterServiceTestPeer::DynamicReplicationWindows(service)) {
+            window.window_start = stale_start;
+        }
+    }
+
+    void ClearDynamicReplicationState(MasterService& service,
+                                      const std::string& key) const {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        ASSERT_TRUE(accessor.Exists());
+        MasterServiceTestPeer(service).ClearDynamicReplicationStateForKey(
+            accessor.GetTenantState(), key);
+    }
+
+    void DiscardExpiredProcessingReplicas(MasterService& service,
+                                          const std::string& key) const {
+        const size_t shard_idx = MasterServiceTestPeer(service).getShardIndex(
+            TenantId::Default(), key);
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                             shard_idx);
+        MasterServiceTestPeer(service).DiscardExpiredProcessingReplicas(
+            shard, std::chrono::system_clock::now() + std::chrono::seconds(1));
+    }
+
+    bool ObserveDynamicReplicationAccess(MasterService& service,
+                                         const std::string& key) const {
+        return MasterServiceTestPeer(service).ObserveDynamicReplicationAccess(
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+    }
+
+    size_t EvictReplicaOnSegment(MasterService& service, const std::string& key,
+                                 const std::string& target_segment) const {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        EXPECT_TRUE(accessor.Exists());
+        if (!accessor.Exists()) {
+            return 0;
+        }
+        std::vector<ReplicaID> erased_replica_ids;
+        return MasterServiceTestPeer(service)
+            .EraseReplicasWithCacheTotalAccounting(
+                accessor.Get(),
+                [&target_segment](const Replica& replica) {
+                    if (!replica.is_memory_replica()) {
+                        return false;
+                    }
+                    const auto& segment_names = replica.get_segment_names();
+                    return std::any_of(
+                        segment_names.begin(), segment_names.end(),
+                        [&target_segment](const auto& name) {
+                            return name && *name == target_segment;
+                        });
+                },
+                &erased_replica_ids);
+    }
+
+    void ExpireDynamicPending(MasterService& service,
+                              const std::string& key) const {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service,
+            MasterServiceTestPeer::ObjectIdentity{TenantId::Default(), key});
+        auto& tenant_state = accessor.GetTenantState();
+        auto pending_it = tenant_state.dynamic_replication_pending.find(key);
+        ASSERT_NE(pending_it, tenant_state.dynamic_replication_pending.end());
+        pending_it->second.expire_at_ms_epoch = 1;
+    }
+};
+
+TEST_F(DynamicReplicationTest,
+       EnforceQueuesCopyFromProposalAboveFrequencyThreshold) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.2;
+    config.dynamic_replication_max_memory_replicas = 2;
+    config.default_kv_lease_ttl = 2000;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x300000000);
+    auto target = PrepareSegment(service, "segment_1", 0x400000000);
+    PutObject(service, source.client_id, "hot-key", source.segment_name);
+
+    auto no_task = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(no_task.has_value());
+    EXPECT_TRUE(no_task->empty());
+
+    auto lease =
+        service.SubmitReplicaActionProposal(BuildProposal(service, "hot-key"));
+    ASSERT_TRUE(lease.has_value());
+    auto tasks = WaitForTasks(service, source.client_id, 1);
+    ASSERT_EQ(tasks.size(), 1u);
+    EXPECT_EQ(tasks.front().type, TaskType::REPLICA_COPY);
+
+    ReplicaCopyPayload payload;
+    struct_json::from_json(payload, tasks.front().payload);
+    EXPECT_EQ(payload.key, "hot-key");
+    EXPECT_EQ(payload.source, source.segment_name);
+    ASSERT_EQ(payload.targets.size(), 1u);
+    EXPECT_EQ(payload.targets.front(), target.segment_name);
+}
+
+TEST_F(DynamicReplicationTest, EnforceGetPathQueuesCopyAfterHeatThreshold) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.2;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x410000000);
+    auto target = PrepareSegment(service, "segment_1", 0x420000000);
+    PutObject(service, source.client_id, "auto-hot-key", source.segment_name);
+
+    ASSERT_TRUE(service.GetReplicaList("auto-hot-key", TenantId::Default())
+                    .has_value());
+    ASSERT_TRUE(service.GetReplicaList("auto-hot-key", TenantId::Default())
+                    .has_value());
+
+    auto tasks = WaitForTasks(service, source.client_id, 1);
+    ASSERT_EQ(tasks.size(), 1u);
+    EXPECT_EQ(tasks.front().type, TaskType::REPLICA_COPY);
+
+    ReplicaCopyPayload payload;
+    struct_json::from_json(payload, tasks.front().payload);
+    EXPECT_EQ(payload.key, "auto-hot-key");
+    EXPECT_EQ(payload.source, source.segment_name);
+    ASSERT_EQ(payload.targets.size(), 1u);
+    EXPECT_EQ(payload.targets.front(), target.segment_name);
+}
+
+TEST_F(DynamicReplicationTest,
+       EnforceBatchGetPathQueuesCopyAfterHeatThreshold) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.2;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xea0000000);
+    auto target = PrepareSegment(service, "segment_1", 0xeb0000000);
+    PutObject(service, source.client_id, "batch-auto-hot-key",
+              source.segment_name);
+
+    auto first_batch = service.BatchGetReplicaList({"batch-auto-hot-key"},
+                                                   TenantId::Default());
+    ASSERT_EQ(first_batch.size(), 1u);
+    ASSERT_TRUE(first_batch.front().has_value());
+    auto second_batch = service.BatchGetReplicaList({"batch-auto-hot-key"},
+                                                    TenantId::Default());
+    ASSERT_EQ(second_batch.size(), 1u);
+    ASSERT_TRUE(second_batch.front().has_value());
+
+    auto tasks = WaitForTasks(service, source.client_id, 1);
+    ASSERT_EQ(tasks.size(), 1u);
+    ReplicaCopyPayload payload;
+    struct_json::from_json(payload, tasks.front().payload);
+    EXPECT_EQ(payload.key, "batch-auto-hot-key");
+    EXPECT_EQ(payload.source, source.segment_name);
+    ASSERT_EQ(payload.targets.size(), 1u);
+    EXPECT_EQ(payload.targets.front(), target.segment_name);
+}
+
+TEST_F(DynamicReplicationTest, ObserveModeDoesNotQueueCopy) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "observe";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.1;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x500000000);
+    (void)PrepareSegment(service, "segment_1", 0x600000000);
+    PutObject(service, source.client_id, "observe-key", source.segment_name);
+
+    for (int i = 0; i < 3; ++i) {
+        auto resp = service.GetReplicaList("observe-key", TenantId::Default());
+        ASSERT_TRUE(resp.has_value());
+    }
+
+    auto tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(tasks.has_value());
+    EXPECT_TRUE(tasks->empty());
+}
+
+TEST_F(DynamicReplicationTest, MaxReplicaLimitSuppressesFanout) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.1;
+    config.dynamic_replication_max_memory_replicas = 1;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x700000000);
+    (void)PrepareSegment(service, "segment_1", 0x800000000);
+    PutObject(service, source.client_id, "max-key", source.segment_name);
+
+    auto lease =
+        service.SubmitReplicaActionProposal(BuildProposal(service, "max-key"));
+    ASSERT_FALSE(lease.has_value());
+    auto tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(tasks.has_value());
+    EXPECT_TRUE(tasks->empty());
+}
+
+TEST_F(DynamicReplicationTest, BelowFrequencyThresholdDoesNotQueueCopy) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.3;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x900000000);
+    (void)PrepareSegment(service, "segment_1", 0xa00000000);
+    PutObject(service, source.client_id, "warm-key", source.segment_name);
+
+    auto proposal = BuildProposal(service, "warm-key", std::nullopt, false);
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_FALSE(lease.has_value());
+
+    auto tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(tasks.has_value());
+    EXPECT_TRUE(tasks->empty());
+}
+
+TEST_F(DynamicReplicationTest, RejectDomainHintsBeforeDomainAwarePlacement) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.2;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x870000000);
+    PrepareSegment(service, "segment_1", 0x880000000);
+    PutObject(service, source.client_id, "domain-hint-key",
+              source.segment_name);
+
+    auto proposal = BuildProposal(service, "domain-hint-key");
+    proposal.target_domain = "domain-a";
+
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_FALSE(lease.has_value());
+    EXPECT_EQ(lease.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(DynamicReplicationTest, LeaseDeadlineDoesNotExceedProposalDeadline) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_heat_window_seconds = 10;
+    config.dynamic_replication_admission_qps_threshold = 0.2;
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x890000000);
+    PrepareSegment(service, "segment_1", 0x8A0000000);
+    PutObject(service, source.client_id, "short-deadline-key",
+              source.segment_name);
+
+    auto proposal = BuildProposal(service, "short-deadline-key");
+    proposal.expire_at_ms_epoch =
+        static_cast<int64_t>(
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::system_clock::now().time_since_epoch())
+                .count()) +
+        std::chrono::seconds(1).count() * 1000;
+
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+    EXPECT_LE(lease->expire_at_ms_epoch, proposal.expire_at_ms_epoch);
+}
+
+TEST_F(DynamicReplicationTest, ProposalIdempotencyReturnsSameLease) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xb00000000);
+    auto target = PrepareSegment(service, "segment_1", 0xc00000000);
+    PutObject(service, source.client_id, "proposal-key", source.segment_name);
+    auto proposal = BuildProposal(service, "proposal-key", target.segment_name);
+
+    auto first = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(first.has_value());
+    auto second = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(second.has_value());
+
+    EXPECT_EQ(second->proposal_id, first->proposal_id);
+    EXPECT_EQ(second->lease_id, first->lease_id);
+    EXPECT_EQ(second->task_id, first->task_id);
+    EXPECT_EQ(second->source_segment, source.segment_name);
+    EXPECT_EQ(second->target_segment, target.segment_name);
+
+    auto tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(tasks.has_value());
+    ASSERT_EQ(tasks->size(), 1u);
+    EXPECT_EQ(tasks->front().id, first->task_id);
+}
+
+TEST_F(DynamicReplicationTest, ProposalIdempotencyRejectsConflictingRequest) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xc10000000);
+    auto target = PrepareSegment(service, "segment_1", 0xc20000000);
+    auto other_target = PrepareSegment(service, "segment_2", 0xc30000000);
+    PutObject(service, source.client_id, "proposal-key", source.segment_name);
+    auto proposal = BuildProposal(service, "proposal-key", target.segment_name);
+
+    auto first = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(first.has_value());
+
+    auto conflicting = proposal;
+    conflicting.preferred_target_segment = other_target.segment_name;
+    auto second = service.SubmitReplicaActionProposal(conflicting);
+    ASSERT_FALSE(second.has_value());
+    EXPECT_EQ(second.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(DynamicReplicationTest, CopyLifecycleMarksDynamicReplicaComplete) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xd00000000);
+    auto target = PrepareSegment(service, "segment_1", 0xe00000000);
+    PutObject(service, source.client_id, "copy-key", source.segment_name);
+    auto proposal = BuildProposal(service, "copy-key", target.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+    auto copy_start =
+        service.CopyStart(source.client_id, "copy-key", TenantId::Default(),
+                          lease->source_segment, {lease->target_segment},
+                          lease->lease_id, lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+    EXPECT_EQ(DynamicReplicaCount(service, "copy-key"), 1u);
+    EXPECT_FALSE(
+        HasCompleteDynamicReplica(service, "copy-key", lease->target_segment));
+
+    auto copy_end =
+        service.CopyEnd(source.client_id, "copy-key", TenantId::Default(),
+                        lease->lease_id, lease->version_epoch);
+    ASSERT_TRUE(copy_end.has_value());
+    EXPECT_EQ(DynamicReplicaCount(service, "copy-key"), 1u);
+    EXPECT_TRUE(
+        HasCompleteDynamicReplica(service, "copy-key", lease->target_segment));
+    EXPECT_FALSE(HasDynamicState(service, "copy-key"));
+}
+
+TEST_F(DynamicReplicationTest,
+       CopyEndForInvalidTargetClearsIncompleteDynamicReplica) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xd70000000);
+    auto target = PrepareSegment(service, "segment_1", 0xd80000000);
+    PutObject(service, source.client_id, "invalid-target-key",
+              source.segment_name);
+
+    auto proposal =
+        BuildProposal(service, "invalid-target-key", target.segment_name);
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+
+    auto copy_start = service.CopyStart(
+        source.client_id, "invalid-target-key", TenantId::Default(),
+        lease->source_segment, {lease->target_segment}, lease->lease_id,
+        lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+    ASSERT_TRUE(HasIncompleteDynamicReplica(service, "invalid-target-key",
+                                            lease->target_segment));
+
+    ASSERT_TRUE(service.UnmountSegment(target.segment_id, target.client_id)
+                    .has_value());
+
+    auto copy_end = service.CopyEnd(source.client_id, "invalid-target-key",
+                                    TenantId::Default(), lease->lease_id,
+                                    lease->version_epoch);
+    ASSERT_FALSE(copy_end.has_value());
+    EXPECT_EQ(copy_end.error(), ErrorCode::REPLICA_IS_GONE);
+    EXPECT_FALSE(HasIncompleteDynamicReplica(service, "invalid-target-key",
+                                             lease->target_segment));
+    EXPECT_FALSE(HasDynamicState(service, "invalid-target-key"));
+}
+
+TEST_F(DynamicReplicationTest, ObserveWindowDropsNewKeysAtEntryLimit) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "observe";
+    MasterService service(config);
+
+    for (size_t i = 0; i < DynamicReplicationWindowEntryLimit(); ++i) {
+        ObserveDynamicReplicationAccess(service,
+                                        "window-key-" + std::to_string(i));
+    }
+    EXPECT_EQ(DynamicReplicationWindowCount(service),
+              DynamicReplicationWindowEntryLimit());
+
+    ObserveDynamicReplicationAccess(service, "window-overflow-key");
+    EXPECT_EQ(DynamicReplicationWindowCount(service),
+              DynamicReplicationWindowEntryLimit());
+}
+
+TEST_F(DynamicReplicationTest, ObserveWindowCleanupIsBoundedAtLimit) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "observe";
+    config.dynamic_replication_heat_window_seconds = 1;
+    MasterService service(config);
+
+    for (size_t i = 0; i < DynamicReplicationWindowEntryLimit(); ++i) {
+        ObserveDynamicReplicationAccess(
+            service, "stale-window-key-" + std::to_string(i));
+    }
+    ASSERT_EQ(DynamicReplicationWindowCount(service),
+              DynamicReplicationWindowEntryLimit());
+
+    ExpireDynamicReplicationWindows(service);
+
+    ObserveDynamicReplicationAccess(service, "fresh-window-key");
+    EXPECT_LT(DynamicReplicationWindowCount(service),
+              DynamicReplicationWindowEntryLimit());
+    EXPECT_GT(DynamicReplicationWindowCount(service), 1u);
+}
+
+TEST_F(DynamicReplicationTest,
+       DynamicCopyStartRejectsStaleLeaseWithoutPending) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xdd0000000);
+    auto target = PrepareSegment(service, "segment_1", 0xde0000000);
+    PutObject(service, source.client_id, "stale-dynamic-task-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "stale-dynamic-task-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    auto tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(tasks.has_value());
+    ASSERT_EQ(tasks->size(), 1u);
+
+    ReplicaCopyPayload payload;
+    struct_json::from_json(payload, tasks->front().payload);
+    EXPECT_EQ(UUID(payload.dynamic_replication_lease_id_high,
+                   payload.dynamic_replication_lease_id_low),
+              lease->lease_id);
+    EXPECT_EQ(payload.dynamic_replication_version_epoch, lease->version_epoch);
+
+    ClearDynamicReplicationState(service, "stale-dynamic-task-key");
+
+    auto copy_start =
+        service.CopyStart(source.client_id, "stale-dynamic-task-key",
+                          TenantId::Default(), payload.source, payload.targets,
+                          UUID(payload.dynamic_replication_lease_id_high,
+                               payload.dynamic_replication_lease_id_low),
+                          payload.dynamic_replication_version_epoch);
+    ASSERT_FALSE(copy_start.has_value());
+    EXPECT_EQ(copy_start.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    EXPECT_EQ(DynamicReplicaCount(service, "stale-dynamic-task-key"), 0u);
+}
+
+TEST_F(DynamicReplicationTest, DynamicCopyStartRejectsNonSourceClient) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_admission_qps_threshold = 0.1;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xb10000000);
+    auto target = PrepareSegment(service, "segment_1", 0xb20000000);
+    auto other = PrepareSegment(service, "segment_2", 0xb30000000);
+    PutObject(service, source.client_id, "source-client-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "source-client-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+
+    auto rejected = service.CopyStart(other.client_id, "source-client-key",
+                                      TenantId::Default(), source.segment_name,
+                                      {target.segment_name}, lease->lease_id,
+                                      lease->version_epoch);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(rejected.error(), ErrorCode::ILLEGAL_CLIENT);
+
+    auto start = service.CopyStart(source.client_id, "source-client-key",
+                                   TenantId::Default(), source.segment_name,
+                                   {target.segment_name}, lease->lease_id,
+                                   lease->version_epoch);
+    ASSERT_TRUE(start.has_value());
+    auto revoke = service.CopyRevoke(source.client_id, "source-client-key",
+                                     TenantId::Default(), lease->lease_id,
+                                     lease->version_epoch);
+    ASSERT_TRUE(revoke.has_value());
+}
+
+TEST_F(DynamicReplicationTest, DynamicCopyStartFailureClearsPending) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_admission_qps_threshold = 0.1;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xc10000000);
+    auto target = PrepareSegment(service, "segment_1", 0xc20000000);
+    auto fallback = PrepareSegment(service, "segment_2", 0xc30000000);
+    PutObject(service, source.client_id, "copy-start-fail-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "copy-start-fail-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    ASSERT_TRUE(service.UnmountSegment(target.segment_id, target.client_id)
+                    .has_value());
+
+    auto failed = service.CopyStart(source.client_id, "copy-start-fail-key",
+                                    TenantId::Default(), source.segment_name,
+                                    {target.segment_name}, lease->lease_id,
+                                    lease->version_epoch);
+    ASSERT_FALSE(failed.has_value());
+    EXPECT_EQ(failed.error(), ErrorCode::SEGMENT_NOT_FOUND);
+
+    auto regular = service.CopyStart(source.client_id, "copy-start-fail-key",
+                                     TenantId::Default(), source.segment_name,
+                                     {fallback.segment_name});
+    ASSERT_TRUE(regular.has_value());
+    auto revoke = service.CopyRevoke(source.client_id, "copy-start-fail-key",
+                                     TenantId::Default());
+    ASSERT_TRUE(revoke.has_value());
+}
+
+TEST_F(DynamicReplicationTest,
+       StaleDynamicCopyStartDoesNotClearCurrentPending) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 3;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xdf0000000);
+    auto stale_target = PrepareSegment(service, "segment_1", 0xe00000000);
+    auto current_target = PrepareSegment(service, "segment_2", 0xe10000000);
+    PutObject(service, source.client_id, "stale-vs-current-key",
+              source.segment_name);
+
+    auto stale_lease = service.SubmitReplicaActionProposal(BuildProposal(
+        service, "stale-vs-current-key", stale_target.segment_name));
+    ASSERT_TRUE(stale_lease.has_value());
+    auto stale_tasks = service.FetchTasks(source.client_id, 16);
+    ASSERT_TRUE(stale_tasks.has_value());
+    ASSERT_EQ(stale_tasks->size(), 1u);
+    ReplicaCopyPayload stale_payload;
+    struct_json::from_json(stale_payload, stale_tasks->front().payload);
+
+    ClearDynamicReplicationState(service, "stale-vs-current-key");
+
+    auto current_lease = service.SubmitReplicaActionProposal(BuildProposal(
+        service, "stale-vs-current-key", current_target.segment_name));
+    ASSERT_TRUE(current_lease.has_value());
+
+    auto stale_copy_start = service.CopyStart(
+        source.client_id, "stale-vs-current-key", TenantId::Default(),
+        stale_payload.source, stale_payload.targets,
+        UUID(stale_payload.dynamic_replication_lease_id_high,
+             stale_payload.dynamic_replication_lease_id_low),
+        stale_payload.dynamic_replication_version_epoch);
+    ASSERT_FALSE(stale_copy_start.has_value());
+    EXPECT_EQ(stale_copy_start.error(), ErrorCode::INVALID_VERSION);
+    EXPECT_TRUE(HasDynamicState(service, "stale-vs-current-key"));
+
+    auto current_copy_start = service.CopyStart(
+        source.client_id, "stale-vs-current-key", TenantId::Default(),
+        current_lease->source_segment, {current_lease->target_segment},
+        current_lease->lease_id, current_lease->version_epoch);
+    ASSERT_TRUE(current_copy_start.has_value());
+    EXPECT_TRUE(HasIncompleteDynamicReplica(service, "stale-vs-current-key",
+                                            current_lease->target_segment));
+}
+
+TEST_F(DynamicReplicationTest, ExpiredDynamicCopyTaskClearsDynamicState) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    config.put_start_discard_timeout_sec = 0;
+    config.put_start_release_timeout_sec = 1;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xe10000000);
+    auto target = PrepareSegment(service, "segment_1", 0xe20000000);
+    PutObject(service, source.client_id, "expired-copy-task-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "expired-copy-task-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    auto copy_start = service.CopyStart(
+        source.client_id, "expired-copy-task-key", TenantId::Default(),
+        lease->source_segment, {lease->target_segment}, lease->lease_id,
+        lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+    ASSERT_TRUE(HasIncompleteDynamicReplica(service, "expired-copy-task-key",
+                                            lease->target_segment));
+
+    DiscardExpiredProcessingReplicas(service, "expired-copy-task-key");
+
+    EXPECT_EQ(DynamicReplicaCount(service, "expired-copy-task-key"), 0u);
+    EXPECT_FALSE(HasDynamicState(service, "expired-copy-task-key"));
+
+    auto retry = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "expired-copy-task-key", target.segment_name));
+    ASSERT_FALSE(retry.has_value());
+    EXPECT_EQ(retry.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST_F(DynamicReplicationTest, DynamicCopyEndRejectsMismatchedLease) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xe30000000);
+    auto target = PrepareSegment(service, "segment_1", 0xe40000000);
+    PutObject(service, source.client_id, "copy-end-fence-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "copy-end-fence-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    auto copy_start = service.CopyStart(
+        source.client_id, "copy-end-fence-key", TenantId::Default(),
+        lease->source_segment, {lease->target_segment}, lease->lease_id,
+        lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+
+    auto stale_end = service.CopyEnd(source.client_id, "copy-end-fence-key",
+                                     TenantId::Default(), generate_uuid(),
+                                     lease->version_epoch);
+    ASSERT_FALSE(stale_end.has_value());
+    EXPECT_EQ(stale_end.error(), ErrorCode::INVALID_VERSION);
+    EXPECT_TRUE(HasIncompleteDynamicReplica(service, "copy-end-fence-key",
+                                            lease->target_segment));
+
+    auto copy_end = service.CopyEnd(source.client_id, "copy-end-fence-key",
+                                    TenantId::Default(), lease->lease_id,
+                                    lease->version_epoch);
+    ASSERT_TRUE(copy_end.has_value());
+    EXPECT_TRUE(HasCompleteDynamicReplica(service, "copy-end-fence-key",
+                                          lease->target_segment));
+}
+
+TEST_F(DynamicReplicationTest, DynamicCopyRevokeRejectsMismatchedLease) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xe50000000);
+    auto target = PrepareSegment(service, "segment_1", 0xe60000000);
+    PutObject(service, source.client_id, "copy-revoke-fence-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "copy-revoke-fence-key", target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    auto copy_start = service.CopyStart(
+        source.client_id, "copy-revoke-fence-key", TenantId::Default(),
+        lease->source_segment, {lease->target_segment}, lease->lease_id,
+        lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+
+    auto stale_revoke = service.CopyRevoke(
+        source.client_id, "copy-revoke-fence-key", TenantId::Default(),
+        generate_uuid(), lease->version_epoch);
+    ASSERT_FALSE(stale_revoke.has_value());
+    EXPECT_EQ(stale_revoke.error(), ErrorCode::INVALID_VERSION);
+    EXPECT_TRUE(HasIncompleteDynamicReplica(service, "copy-revoke-fence-key",
+                                            lease->target_segment));
+
+    auto copy_revoke = service.CopyRevoke(
+        source.client_id, "copy-revoke-fence-key", TenantId::Default(),
+        lease->lease_id, lease->version_epoch);
+    ASSERT_TRUE(copy_revoke.has_value());
+    EXPECT_EQ(DynamicReplicaCount(service, "copy-revoke-fence-key"), 0u);
+    EXPECT_FALSE(HasDynamicState(service, "copy-revoke-fence-key"));
+}
+
+TEST_F(DynamicReplicationTest, CopyStartRejectsVersionMismatch) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xe10000000);
+    auto target = PrepareSegment(service, "segment_1", 0xe20000000);
+    PutObject(service, source.client_id, "version-key", source.segment_name);
+    auto proposal = BuildProposal(service, "version-key", target.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+    BumpVersionEpoch(service, "version-key");
+
+    auto copy_start =
+        service.CopyStart(source.client_id, "version-key", TenantId::Default(),
+                          lease->source_segment, {lease->target_segment},
+                          lease->lease_id, lease->version_epoch);
+    ASSERT_FALSE(copy_start.has_value());
+    EXPECT_EQ(copy_start.error(), ErrorCode::INVALID_VERSION);
+    EXPECT_FALSE(HasDynamicState(service, "version-key"));
+}
+
+TEST_F(DynamicReplicationTest, ExpiredDynamicPendingDoesNotBlockRegularCopy) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 3;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xe70000000);
+    auto expired_target = PrepareSegment(service, "segment_1", 0xe80000000);
+    auto regular_target = PrepareSegment(service, "segment_2", 0xe90000000);
+    PutObject(service, source.client_id, "expired-pending-regular-copy-key",
+              source.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "expired-pending-regular-copy-key",
+                      expired_target.segment_name));
+    ASSERT_TRUE(lease.has_value());
+    ExpireDynamicPending(service, "expired-pending-regular-copy-key");
+
+    auto copy_start =
+        service.CopyStart(source.client_id, "expired-pending-regular-copy-key",
+                          TenantId::Default(), source.segment_name,
+                          {regular_target.segment_name});
+    ASSERT_TRUE(copy_start.has_value());
+    auto copy_revoke =
+        service.CopyRevoke(source.client_id, "expired-pending-regular-copy-key",
+                           TenantId::Default());
+    ASSERT_TRUE(copy_revoke.has_value());
+    EXPECT_FALSE(HasDynamicState(service, "expired-pending-regular-copy-key"));
+}
+
+TEST_F(DynamicReplicationTest, ExpiredLeaseRejectsCopyStart) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0xf00000000);
+    auto target = PrepareSegment(service, "segment_1", 0x1000000000);
+    PutObject(service, source.client_id, "expired-key", source.segment_name);
+    auto proposal = BuildProposal(service, "expired-key", target.segment_name);
+
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+    ExpireDynamicPending(service, "expired-key");
+
+    auto copy_start =
+        service.CopyStart(source.client_id, "expired-key", TenantId::Default(),
+                          lease->source_segment, {lease->target_segment},
+                          lease->lease_id, lease->version_epoch);
+    ASSERT_FALSE(copy_start.has_value());
+    EXPECT_EQ(copy_start.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    EXPECT_EQ(DynamicReplicaCount(service, "expired-key"), 0u);
+    EXPECT_FALSE(HasDynamicState(service, "expired-key"));
+}
+
+TEST_F(DynamicReplicationTest, EvictedDynamicReplicaBlocksImmediateRecreate) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_admission_qps_threshold = 0.1;
+    config.dynamic_replication_max_memory_replicas = 3;
+    MasterService service(config);
+
+    auto source = PrepareSegment(service, "segment_0", 0x1100000000);
+    auto target = PrepareSegment(service, "segment_1", 0x1200000000);
+    auto next_target = PrepareSegment(service, "segment_2", 0x1300000000);
+    PutObject(service, source.client_id, "evicted-dynamic-key",
+              source.segment_name);
+
+    auto proposal =
+        BuildProposal(service, "evicted-dynamic-key", target.segment_name);
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+    auto copy_start = service.CopyStart(
+        source.client_id, "evicted-dynamic-key", TenantId::Default(),
+        lease->source_segment, {lease->target_segment}, lease->lease_id,
+        lease->version_epoch);
+    ASSERT_TRUE(copy_start.has_value());
+    auto copy_end = service.CopyEnd(source.client_id, "evicted-dynamic-key",
+                                    TenantId::Default(), lease->lease_id,
+                                    lease->version_epoch);
+    ASSERT_TRUE(copy_end.has_value());
+    ASSERT_EQ(DynamicReplicaCount(service, "evicted-dynamic-key"), 1u);
+
+    EXPECT_EQ(EvictReplicaOnSegment(service, "evicted-dynamic-key",
+                                    target.segment_name),
+              1u);
+    EXPECT_EQ(DynamicReplicaCount(service, "evicted-dynamic-key"), 0u);
+
+    auto immediate_recreate =
+        BuildProposal(service, "evicted-dynamic-key", next_target.segment_name);
+    auto rejected = service.SubmitReplicaActionProposal(immediate_recreate);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(rejected.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST_F(DynamicReplicationTest, SourceSelectionUsesStableTieBreak) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 4;
+    MasterService service(config);
+
+    auto source0 = PrepareSegment(service, "segment_0", 0x1400000000);
+    auto source1 = PrepareSegment(service, "segment_1", 0x1500000000);
+    auto target = PrepareSegment(service, "segment_2", 0x1600000000);
+    PutObject(service, source0.client_id, "source-fanout-key",
+              source0.segment_name);
+
+    auto copy_start = service.CopyStart(
+        source0.client_id, "source-fanout-key", TenantId::Default(),
+        source0.segment_name, {source1.segment_name});
+    ASSERT_TRUE(copy_start.has_value());
+    auto copy_end = service.CopyEnd(source0.client_id, "source-fanout-key",
+                                    TenantId::Default());
+    ASSERT_TRUE(copy_end.has_value());
+
+    auto proposal =
+        BuildProposal(service, "source-fanout-key", target.segment_name);
+    auto lease = service.SubmitReplicaActionProposal(proposal);
+    ASSERT_TRUE(lease.has_value());
+
+    auto stable_score = [](std::string_view key, std::string_view segment) {
+        uint64_t hash = 1469598103934665603ULL;
+        auto mix = [&hash](std::string_view value) {
+            for (const unsigned char c : value) {
+                hash ^= c;
+                hash *= 1099511628211ULL;
+            }
+            hash ^= 0xff;
+            hash *= 1099511628211ULL;
+        };
+        mix(key);
+        mix(segment);
+        return hash;
+    };
+    const auto score0 = stable_score("source-fanout-key", source0.segment_name);
+    const auto score1 = stable_score("source-fanout-key", source1.segment_name);
+    EXPECT_EQ(lease->source_segment,
+              score0 < score1 ? source0.segment_name : source1.segment_name);
+}
+
+TEST_F(DynamicReplicationTest, TargetSelectionPrefersDifferentHost) {
+    MasterServiceConfig config;
+    config.dynamic_replication_mode = "enforce";
+    config.dynamic_replication_max_memory_replicas = 2;
+    MasterService service(config);
+
+    Segment source_segment;
+    source_segment.id = generate_uuid();
+    source_segment.name = "source_segment";
+    source_segment.base = 0x1700000000;
+    source_segment.size = kDefaultSegmentSize;
+    source_segment.te_endpoint = source_segment.name;
+    source_segment.host_id = "host-a";
+    UUID source_client = generate_uuid();
+    ASSERT_TRUE(
+        service.MountSegment(source_segment, source_client).has_value());
+
+    Segment same_host_target;
+    same_host_target.id = generate_uuid();
+    same_host_target.name = "same_host_target";
+    same_host_target.base = 0x1800000000;
+    same_host_target.size = kDefaultSegmentSize;
+    same_host_target.te_endpoint = same_host_target.name;
+    same_host_target.host_id = "host-a";
+    ASSERT_TRUE(
+        service.MountSegment(same_host_target, generate_uuid()).has_value());
+
+    Segment other_host_target;
+    other_host_target.id = generate_uuid();
+    other_host_target.name = "other_host_target";
+    other_host_target.base = 0x1900000000;
+    other_host_target.size = kDefaultSegmentSize;
+    other_host_target.te_endpoint = other_host_target.name;
+    other_host_target.host_id = "host-b";
+    ASSERT_TRUE(
+        service.MountSegment(other_host_target, generate_uuid()).has_value());
+
+    PutObject(service, source_client, "target-host-key", source_segment.name);
+    auto lease = service.SubmitReplicaActionProposal(
+        BuildProposal(service, "target-host-key"));
+    ASSERT_TRUE(lease.has_value());
+    EXPECT_EQ(lease->target_segment, other_host_target.name);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/e2e/CMakeLists.txt b/mooncake-store/tests/e2e/CMakeLists.txt
index 7f477bd227..1ff8ac7f9a 100644
--- a/mooncake-store/tests/e2e/CMakeLists.txt
+++ b/mooncake-store/tests/e2e/CMakeLists.txt
@@ -8,7 +8,7 @@ target_link_libraries(clientctl PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     pthread
     ${ETCD_WRAPPER_LIB}
 )
@@ -18,7 +18,7 @@ target_link_libraries(e2e_rand_test PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     gtest
     pthread
     ${ETCD_WRAPPER_LIB}
@@ -29,7 +29,7 @@ target_link_libraries(chaosctl PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     pthread
     ${ETCD_WRAPPER_LIB}
 )
@@ -39,7 +39,7 @@ target_link_libraries(client_runner PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     pthread
     ${ETCD_WRAPPER_LIB}
 )
@@ -49,7 +49,7 @@ target_link_libraries(oplog_ha_client PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     pthread
     ${ETCD_WRAPPER_LIB}
 )
@@ -59,7 +59,7 @@ target_link_libraries(chaos_test PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     gtest
     pthread
     ${ETCD_WRAPPER_LIB}
@@ -70,7 +70,7 @@ target_link_libraries(chaos_rand_test PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     gtest
     pthread
     ${ETCD_WRAPPER_LIB}
@@ -84,7 +84,7 @@ target_link_libraries(storage_backend_e2e_test PUBLIC
     mooncake_store
     transfer_engine
     cachelib_memory_allocator
-    glog
+    glog::glog
     gtest
     pthread
     ${ETCD_WRAPPER_LIB}
@@ -93,6 +93,6 @@ target_link_libraries(storage_backend_e2e_test PUBLIC
 add_test(NAME storage_backend_e2e_test COMMAND storage_backend_e2e_test)
 
 add_executable(oplog_batch_e2e_test oplog_batch_e2e_test.cpp process_handler.cpp)
-target_link_libraries(oplog_batch_e2e_test PUBLIC glog gtest pthread)
+target_link_libraries(oplog_batch_e2e_test PUBLIC glog::glog gtest pthread)
 add_test(NAME oplog_batch_e2e_test COMMAND oplog_batch_e2e_test)
 set_tests_properties(oplog_batch_e2e_test PROPERTIES LABELS oplog_batch_smoke)
diff --git a/mooncake-store/tests/e2e/chaos_rand_test.cpp b/mooncake-store/tests/e2e/chaos_rand_test.cpp
index cd714da293..f4e6c4910f 100644
--- a/mooncake-store/tests/e2e/chaos_rand_test.cpp
+++ b/mooncake-store/tests/e2e/chaos_rand_test.cpp
@@ -11,7 +11,6 @@
 #include "ha/leadership/leader_coordinator_factory.h"
 #include "process_handler.h"
 #include "types.h"
-#include "utils.h"
 
 // Define flags
 USE_engine_flags;
diff --git a/mooncake-store/tests/e2e/chaos_test.cpp b/mooncake-store/tests/e2e/chaos_test.cpp
index 619a89c555..f5d9116f89 100644
--- a/mooncake-store/tests/e2e/chaos_test.cpp
+++ b/mooncake-store/tests/e2e/chaos_test.cpp
@@ -11,7 +11,6 @@
 #include "ha/leadership/leader_coordinator_factory.h"
 #include "process_handler.h"
 #include "types.h"
-#include "utils.h"
 
 USE_engine_flags;
 FLAG_etcd_endpoints;
diff --git a/mooncake-store/tests/e2e/client_runner.cpp b/mooncake-store/tests/e2e/client_runner.cpp
index f6be1006f3..f71e63ebff 100644
--- a/mooncake-store/tests/e2e/client_runner.cpp
+++ b/mooncake-store/tests/e2e/client_runner.cpp
@@ -8,7 +8,6 @@
 #include "e2e_utils.h"
 #include "process_handler.h"
 #include "types.h"
-#include "utils.h"
 
 // Command line flags
 USE_engine_flags;
@@ -220,4 +219,4 @@ int main(int argc, char** argv) {
     client_runner.Run();
 
     return 0;
-}
\ No newline at end of file
+}
diff --git a/mooncake-store/tests/e2e/client_wrapper.cpp b/mooncake-store/tests/e2e/client_wrapper.cpp
index 0f76a5a43e..bbdb6d89e1 100644
--- a/mooncake-store/tests/e2e/client_wrapper.cpp
+++ b/mooncake-store/tests/e2e/client_wrapper.cpp
@@ -3,7 +3,7 @@
 #include <cstring>
 #include <stdexcept>
 
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 
 namespace mooncake {
 namespace testing {
diff --git a/mooncake-store/tests/e2e/clientctl.cpp b/mooncake-store/tests/e2e/clientctl.cpp
index 29555a3f81..6dd2bf24c0 100644
--- a/mooncake-store/tests/e2e/clientctl.cpp
+++ b/mooncake-store/tests/e2e/clientctl.cpp
@@ -8,7 +8,6 @@
 
 #include "client_wrapper.h"
 #include "types.h"
-#include "utils.h"
 #include "e2e_utils.h"
 
 // Command line flags
diff --git a/mooncake-store/tests/e2e/e2e_rand_test.cpp b/mooncake-store/tests/e2e/e2e_rand_test.cpp
index 415e2b810e..668b6e07de 100644
--- a/mooncake-store/tests/e2e/e2e_rand_test.cpp
+++ b/mooncake-store/tests/e2e/e2e_rand_test.cpp
@@ -10,7 +10,6 @@
 #include "e2e_utils.h"
 #include "process_handler.h"
 #include "types.h"
-#include "utils.h"
 
 USE_engine_flags;
 FLAG_etcd_endpoints;
diff --git a/mooncake-store/tests/e2e/oplog_ha_client.cpp b/mooncake-store/tests/e2e/oplog_ha_client.cpp
index d4cdce2318..2b3bec478c 100644
--- a/mooncake-store/tests/e2e/oplog_ha_client.cpp
+++ b/mooncake-store/tests/e2e/oplog_ha_client.cpp
@@ -15,7 +15,6 @@
 #include "client_wrapper.h"
 #include "e2e_utils.h"
 #include "types.h"
-#include "utils.h"
 
 USE_engine_flags;
 DEFINE_string(master_server_entry, "etcd://0.0.0.0:2379",
diff --git a/mooncake-store/tests/e2e/readme.md b/mooncake-store/tests/e2e/readme.md
index e8ad2aedcc..ddc1d03536 100644
--- a/mooncake-store/tests/e2e/readme.md
+++ b/mooncake-store/tests/e2e/readme.md
@@ -149,3 +149,70 @@ python3 store_client_e2e.py \
 - `--payload-size 4096`: keep NoF writes 4K aligned
 - `--duration-sec`: total workload duration
 - `--sleep-ms`: interval between operations
+
+### run_oplog_snapshot_smoke.sh
+
+Runs the batch OpLog snapshot path with two real master processes and a local
+etcd instance. It publishes two snapshots with multiple object chunks, stops
+and restarts the standby, verifies suffix replay and promotion, and audits
+surviving and removed objects.
+
+```bash
+./run_oplog_snapshot_smoke.sh \
+  --build-dir /path/to/build \
+  --run-dir /tmp/mooncake-oplog-snapshot-smoke
+```
+
+Set `--failpoint-dir` to verify the same launcher environment path used by
+crash tests. The script requires `mooncake_master`, `oplog_ha_client`,
+`oplog_batch_inspector`, `hot_standby_snapshot_bootstrap_test`, `etcd`,
+`etcdctl`, `curl`, `setsid`, and Python `aiohttp`. It is a manual real-etcd
+check and is not registered in CI/nightly.
+
+The run directory must be new. The script stores configurations, master and
+client logs, snapshot artifacts, and audit results there, and stops its test
+processes on exit. Local snapshot storage is shared by the two test masters;
+for multi-host deployment, every master must be able to read the same durable
+snapshot artifacts.
+
+The production mode is opt-in with `enable_oplog_snapshot=true` together with
+`enable_oplog=true`, HA/etcd and a configured snapshot object store. The default
+chunk size is 1,000,000 objects and the default snapshot interval is 600 seconds.
+The smoke overrides these to two objects and two seconds. A chunk bounds object
+count, not byte size or total standby memory. Legacy catalog restore is not
+used by this mode. Snapshot upload failures do not stop OpLog apply, but a node
+must not serve if its recovery history cannot be proven complete.
+
+This smoke does not cover the full crash/corruption/lease-contention matrix,
+S3 outages, large-scale memory/freeze-time measurements, or safe OpLog pruning.
+Keep batch history until retention/pruning has its own verified recovery gate.
+
+## Batch OpLog capacity tests
+
+Build `mooncake_master`, `oplog_batch_inspector`, and `oplog_ha_client` with
+`STORE_USE_ETCD=ON`. Put matching etcd/etcdctl 3.5+ binaries on `PATH` and install
+Python `aiohttp`. From the repository root:
+
+```bash
+bash mooncake-store/tests/e2e/run_oplog_batch_cluster_test.sh
+mooncake-store/tests/e2e/run_oplog_batch_cluster.sh capacity-soak \
+  --build-dir /path/to/build --run-dir /tmp/n13-soak \
+  --capacity-seconds 3600 --capacity-max-batches 2048
+mooncake-store/tests/e2e/run_oplog_batch_cluster.sh capacity-nospace \
+  --build-dir /path/to/build --run-dir /tmp/n13-nospace
+```
+
+Both commands require a fresh directory and reject external etcd endpoints. They
+create two masters, one etcd member and shared local snapshots; multi-member quorum
+availability and S3 are not tested. Processes stop on exit; artifacts remain.
+
+The soak checks bounded live batch keys, snapshot/floor progress and periodic
+compact/defrag reclamation. NOSPACE fills history under a 16 MiB quota after
+quiescing masters, then verifies the alarm, reclamation, disarm and recovered writes.
+Both audit surviving/deleted keys across restart and promotion, then test new writes.
+A 30-second soak is only a smoke test; report the actual measured duration.
+
+`<run-dir>/capacity/` contains consistent-revision key/control samples, raw metrics,
+maintenance status before/after compact and defrag, `soak-result.json`, and
+`audits.log`. Process logs and acknowledgement manifests are in `logs/` and
+`workload/`. Batch-specific helpers are in `tests/ha/snapshot/batch_oplog/`.
diff --git a/mooncake-store/tests/e2e/run_nof_heartbeat_tcp_e2e.sh b/mooncake-store/tests/e2e/run_nof_heartbeat_tcp_e2e.sh
index 4e7488249a..4bdb294fb4 100644
--- a/mooncake-store/tests/e2e/run_nof_heartbeat_tcp_e2e.sh
+++ b/mooncake-store/tests/e2e/run_nof_heartbeat_tcp_e2e.sh
@@ -4,6 +4,9 @@ set -euo pipefail
 SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
 REPO_ROOT=$(cd -- "$SCRIPT_DIR/../../.." && pwd)
 BUILD_DIR=${BUILD_DIR:-"$REPO_ROOT/build"}
+# The build-tree pybind module only carries an $ORIGIN RUNPATH, which does not
+# cover libasio.so in mooncake-common.
+export LD_LIBRARY_PATH="$BUILD_DIR/mooncake-common${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
 LOG_DIR=${LOG_DIR:-/tmp/mooncake_nof_heartbeat_e2e}
 MASTER_RPC=${MASTER_RPC:-127.0.0.1:50051}
 MASTER_HOST=${MASTER_RPC%:*}
diff --git a/mooncake-store/tests/e2e/run_oplog_batch_cluster.sh b/mooncake-store/tests/e2e/run_oplog_batch_cluster.sh
index c6ea928bf8..2c77a42f33 100755
--- a/mooncake-store/tests/e2e/run_oplog_batch_cluster.sh
+++ b/mooncake-store/tests/e2e/run_oplog_batch_cluster.sh
@@ -10,7 +10,7 @@ die() {
 }
 
 usage() {
-  echo "Usage: $0 <up|status|collect|restart|down|smoke|restart-smoke|failpoint-smoke|failpoint-crash-smoke|remove-boundary-smoke|standby-read-smoke|promotion-catchup-smoke|ha-failover-smoke|allocator-recovery-smoke|allocator-recovery-matrix|non-ha-smoke> [options]" >&2
+  echo "Usage: $0 <up|status|collect|restart|down|smoke|restart-smoke|failpoint-smoke|failpoint-crash-smoke|remove-boundary-smoke|standby-read-smoke|promotion-catchup-smoke|ha-failover-smoke|allocator-recovery-smoke|allocator-recovery-matrix|non-ha-smoke|capacity-soak|capacity-nospace> [options]" >&2
 }
 
 parse_up_options() {
@@ -24,6 +24,8 @@ parse_up_options() {
   OPLOG_STORE_TYPE=etcd_batch_record
   BATCH_ENTRIES=1024
   RETRY_TIMEOUT_SEC=180
+  ENABLE_OPLOG_SNAPSHOT=false
+  SNAPSHOT_CHUNK_OBJECT_COUNT=1000000
   MASTER_CONFIG=""
   USE_ETCD_OBSERVER=true
   NON_HA_WORKERS=4
@@ -39,6 +41,8 @@ parse_up_options() {
   RECOVERY_REFILL_OBJECTS=120
   RECOVERY_PRESSURE_SEC=10
   RECOVERY_SEGMENT_BYTES=268435456
+  CAPACITY_SECONDS=3600
+  CAPACITY_MAX_BATCHES=2048
   ETCD_ENDPOINTS=""
   ETCD_BIN=${ETCD_BIN:-etcd}
   while (($#)); do
@@ -88,6 +92,15 @@ parse_up_options() {
         RETRY_TIMEOUT_SEC=$2
         shift 2
         ;;
+      --enable-oplog-snapshot)
+        ENABLE_OPLOG_SNAPSHOT=true
+        shift
+        ;;
+      --snapshot-chunk-object-count)
+        (($# >= 2)) || die "--snapshot-chunk-object-count requires a value"
+        SNAPSHOT_CHUNK_OBJECT_COUNT=$2
+        shift 2
+        ;;
       --master-config)
         (($# >= 2)) || die "--master-config requires a value"
         MASTER_CONFIG=$2
@@ -162,6 +175,16 @@ parse_up_options() {
         FAILPOINT_TIMEOUT_SEC=$2
         shift 2
         ;;
+      --capacity-seconds)
+        (($# >= 2)) || die "--capacity-seconds requires a value"
+        CAPACITY_SECONDS=$2
+        shift 2
+        ;;
+      --capacity-max-batches)
+        (($# >= 2)) || die "--capacity-max-batches requires a value"
+        CAPACITY_MAX_BATCHES=$2
+        shift 2
+        ;;
       --etcd-endpoints)
         (($# >= 2)) || die "--etcd-endpoints requires a value"
         ETCD_ENDPOINTS=$2
@@ -176,10 +199,14 @@ parse_up_options() {
     esac
   done
   [[ -d "$BUILD_DIR" ]] || die "build directory does not exist: $BUILD_DIR"
+  [[ "$CAPACITY_SECONDS" =~ ^[1-9][0-9]*$ ]] || die "capacity-seconds must be positive"
+  [[ "$CAPACITY_MAX_BATCHES" =~ ^[1-9][0-9]*$ ]] || die "capacity-max-batches must be positive"
   [[ "$MASTER_COUNT" =~ ^[1-9][0-9]*$ ]] || die "masters must be positive"
   [[ "$CLIENT_COUNT" =~ ^[0-9]+$ ]] || die "clients must be non-negative"
   [[ "$BATCH_ENTRIES" =~ ^[1-9][0-9]*$ ]] ||
     die "batch-entries must be positive"
+  [[ "$SNAPSHOT_CHUNK_OBJECT_COUNT" =~ ^[1-9][0-9]*$ ]] ||
+    die "snapshot-chunk-object-count must be positive"
   [[ "$START_TIMEOUT_SEC" =~ ^[1-9][0-9]*$ ]] ||
     die "timeout-sec must be positive"
   [[ "$FAILPOINT_TIMEOUT_SEC" =~ ^[1-9][0-9]*$ ]] ||
@@ -350,11 +377,20 @@ start_master() {
     environment=(env "MOONCAKE_TEST_FAILPOINT_DIR=$FAILPOINT_DIR"
       "MOONCAKE_TEST_FAILPOINT_TIMEOUT_SEC=$FAILPOINT_TIMEOUT_SEC")
   fi
+  if [[ "$ENABLE_OPLOG_SNAPSHOT" == true ]]; then
+    mkdir -p "$RUN_DIR/snapshots"
+    if ((${#environment[@]} == 0)); then
+      environment=(env)
+    fi
+    environment+=("MOONCAKE_SNAPSHOT_LOCAL_PATH=$RUN_DIR/snapshots")
+  fi
   local -a ha_args=(--enable_ha=false)
   local -a non_ha_args=()
   local -a config_args=()
   local -a allocator_args=()
   [[ -z "$MASTER_CONFIG" ]] || config_args=(--config_path="$MASTER_CONFIG")
+  [[ "$SNAPSHOT_CHUNK_OBJECT_COUNT" =~ ^[1-9][0-9]*$ ]] ||
+    die "snapshot-chunk-object-count must be positive"
   [[ -z "$MEMORY_ALLOCATOR" ]] ||
     allocator_args=(--memory_allocator="$MEMORY_ALLOCATOR")
   if [[ "$ENABLE_HA" == true ]]; then
@@ -362,6 +398,9 @@ start_master() {
       --ha_backend_connstring="$ETCD_ENDPOINTS"
       --etcd_endpoints="$ETCD_ENDPOINTS" --cluster_id="$CLUSTER_ID"
       --enable_oplog=true
+      --enable_oplog_snapshot="$ENABLE_OPLOG_SNAPSHOT"
+      --snapshot_chunk_object_count="$SNAPSHOT_CHUNK_OBJECT_COUNT"
+      --snapshot_object_store_type=local
       --oplog_batch_max_entries="$BATCH_ENTRIES"
       --batch_oplog_retry_timeout_sec="$RETRY_TIMEOUT_SEC")
   else
@@ -388,6 +427,8 @@ write_cluster_env() {
     printf 'OPLOG_STORE_TYPE=%q\n' "$OPLOG_STORE_TYPE"
     printf 'BATCH_ENTRIES=%q\n' "$BATCH_ENTRIES"
     printf 'RETRY_TIMEOUT_SEC=%q\n' "$RETRY_TIMEOUT_SEC"
+    printf 'ENABLE_OPLOG_SNAPSHOT=%q\n' "$ENABLE_OPLOG_SNAPSHOT"
+    printf 'SNAPSHOT_CHUNK_OBJECT_COUNT=%q\n' "$SNAPSHOT_CHUNK_OBJECT_COUNT"
     printf 'MASTER_CONFIG=%q\n' "$MASTER_CONFIG"
     printf 'USE_ETCD_OBSERVER=%q\n' "$USE_ETCD_OBSERVER"
     printf 'NON_HA_WORKERS=%q\n' "$NON_HA_WORKERS"
@@ -424,6 +465,8 @@ load_cluster_env() {
   OPLOG_STORE_TYPE=${OPLOG_STORE_TYPE:-etcd_batch_record}
   BATCH_ENTRIES=${BATCH_ENTRIES:-1024}
   RETRY_TIMEOUT_SEC=${RETRY_TIMEOUT_SEC:-180}
+  ENABLE_OPLOG_SNAPSHOT=${ENABLE_OPLOG_SNAPSHOT:-false}
+  SNAPSHOT_CHUNK_OBJECT_COUNT=${SNAPSHOT_CHUNK_OBJECT_COUNT:-1000000}
   MASTER_CONFIG=${MASTER_CONFIG:-}
   USE_ETCD_OBSERVER=${USE_ETCD_OBSERVER:-true}
   NON_HA_WORKERS=${NON_HA_WORKERS:-4}
@@ -1856,7 +1899,7 @@ main() {
   local command=$1
   shift
   case "$command" in
-    up | smoke | restart-smoke | failpoint-smoke | failpoint-crash-smoke | remove-boundary-smoke | standby-read-smoke | promotion-catchup-smoke | ha-failover-smoke | allocator-recovery-smoke | allocator-recovery-matrix | non-ha-smoke)
+    up | smoke | restart-smoke | failpoint-smoke | failpoint-crash-smoke | remove-boundary-smoke | standby-read-smoke | promotion-catchup-smoke | ha-failover-smoke | allocator-recovery-smoke | allocator-recovery-matrix | non-ha-smoke | capacity-soak | capacity-nospace)
       parse_up_options "$@"
       if [[ "$command" == allocator-recovery-smoke ||
             "$command" == allocator-recovery-matrix ]] &&
@@ -1870,7 +1913,10 @@ main() {
       if [[ "$USE_ETCD_OBSERVER" != true && "$ENABLE_HA" == true ]]; then
         die "--no-etcd-observer is only supported by non-ha-smoke"
       fi
-      if [[ "$command" == up ]]; then
+      if [[ "$command" == capacity-soak || "$command" == capacity-nospace ]]; then
+        source "$SCRIPT_DIR/../ha/snapshot/batch_oplog/capacity.sh"
+        capacity_cluster "$command"
+      elif [[ "$command" == up ]]; then
         up_cluster
       elif [[ "$command" == smoke ]]; then
         smoke_cluster
@@ -1915,4 +1961,6 @@ main() {
   esac
 }
 
-main "$@"
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  main "$@"
+fi
diff --git a/mooncake-store/tests/e2e/run_oplog_batch_cluster_test.sh b/mooncake-store/tests/e2e/run_oplog_batch_cluster_test.sh
index 4631729ca6..8d4710152a 100755
--- a/mooncake-store/tests/e2e/run_oplog_batch_cluster_test.sh
+++ b/mooncake-store/tests/e2e/run_oplog_batch_cluster_test.sh
@@ -68,6 +68,8 @@ expect_failure 1 "ha-payload-bytes must be positive" \
   "$SCRIPT" ha-failover-smoke --build-dir "$TEST_ROOT" --ha-payload-bytes 0
 expect_failure 1 "ha-pressure-sec must be positive" \
   "$SCRIPT" ha-failover-smoke --build-dir "$TEST_ROOT" --ha-pressure-sec 0
+expect_failure 1 "snapshot-chunk-object-count must be positive" \
+  "$SCRIPT" up --build-dir "$TEST_ROOT" --snapshot-chunk-object-count 0
 expect_failure 1 "memory-allocator must be offset or cachelib" \
   "$SCRIPT" allocator-recovery-smoke --build-dir "$TEST_ROOT" \
   --memory-allocator invalid
@@ -127,4 +129,56 @@ expect_success "cluster is stopped" "$SCRIPT" down --run-dir "$MATCH_RUN"
 kill -0 "$MATCH_PID" 2>/dev/null && fail "matching PID was not stopped"
 expect_success "cluster is stopped" "$SCRIPT" down --run-dir "$MATCH_RUN"
 
+# Execute start_master with a fake binary, including both environment paths.
+FAKE_MASTER="$TEST_ROOT/fake-master"
+cat >"$FAKE_MASTER" <<'MASTER'
+#!/usr/bin/env bash
+[[ "$MOONCAKE_SNAPSHOT_LOCAL_PATH" == "$EXPECTED_SNAPSHOT_PATH" ]]
+[[ "${MOONCAKE_TEST_FAILPOINT_DIR:-}" == "$EXPECTED_FAILPOINT_PATH" ]]
+[[ "$*" == *"--enable_oplog_snapshot=true"* ]]
+MASTER
+chmod +x "$FAKE_MASTER"
+for failpoints in "" "$TEST_ROOT/failpoints"; do
+  (
+    source "$SCRIPT"
+    parse_up_options --build-dir "$TEST_ROOT" --run-dir "$TEST_ROOT/env-run" \
+      --enable-oplog-snapshot --snapshot-chunk-object-count 2
+    MASTER_BIN="$FAKE_MASTER"
+    ETCD_ENDPOINTS=127.0.0.1:1
+    RPC_PORTS=(10001)
+    ADMIN_PORTS=(10002)
+    FAILPOINT_DIR="$failpoints"
+    export EXPECTED_SNAPSHOT_PATH="$RUN_DIR/snapshots"
+    export EXPECTED_FAILPOINT_PATH="$failpoints"
+    start_process() { shift; "$@"; }
+    start_master 0
+  ) || fail "snapshot environment propagation failed"
+done
+
+(
+  source "$SCRIPT"
+  RUN_DIR="$TEST_ROOT/old-run"
+  mkdir -p "$RUN_DIR"
+  printf 'RPC_PORTS=10001\nADMIN_PORTS=10002\nBUILD_DIR=/unused\n' >"$RUN_DIR/cluster.env"
+  unset ENABLE_OPLOG_SNAPSHOT SNAPSHOT_CHUNK_OBJECT_COUNT
+  load_cluster_env
+  [[ "$ENABLE_OPLOG_SNAPSHOT" == false ]]
+  [[ "$SNAPSHOT_CHUNK_OBJECT_COUNT" == 1000000 ]]
+) || fail "older cluster.env did not retain pure OpLog defaults"
+
+for command in capacity-soak capacity-nospace; do
+  expect_failure 1 "build directory does not exist" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT/missing-build"
+  expect_failure 1 "external endpoints are forbidden" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT" --etcd-endpoints localhost:2379
+  expect_failure 1 "capacity-seconds must be positive" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT" --capacity-seconds 0
+  expect_failure 1 "capacity-seconds must be at least 30" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT" --capacity-seconds 29
+  expect_failure 1 "capacity-max-batches must be positive" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT" --capacity-max-batches invalid
+  expect_failure 1 "fresh run directory" \
+    "$SCRIPT" "$command" --build-dir "$TEST_ROOT" --run-dir "$EMPTY_RUN"
+done
+python3 "$SCRIPT_DIR/../ha/snapshot/batch_oplog/capacity_test.py"
 echo "PASS"
diff --git a/mooncake-store/tests/e2e/run_oplog_snapshot_smoke.sh b/mooncake-store/tests/e2e/run_oplog_snapshot_smoke.sh
new file mode 100755
index 0000000000..f1a695c80a
--- /dev/null
+++ b/mooncake-store/tests/e2e/run_oplog_snapshot_smoke.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Real-process batch snapshot publication, cold restore, suffix and promotion.
+set -euo pipefail
+source "$(dirname -- "${BASH_SOURCE[0]}")/run_oplog_batch_cluster.sh"
+parse_up_options "$@"
+if [[ -e "$RUN_DIR" ]]; then die "snapshot smoke requires a fresh run directory"; fi
+MASTER_COUNT=2
+CLIENT_COUNT=0
+ENABLE_OPLOG_SNAPSHOT=true
+SNAPSHOT_CHUNK_OBJECT_COUNT=2
+command -v etcdctl >/dev/null || die "missing etcdctl"
+HA_CLIENT="$BUILD_DIR/mooncake-store/tests/e2e/oplog_ha_client"
+require_executable "$HA_CLIENT"
+mkdir -p "$RUN_DIR/configs"
+MASTER_CONFIG="$RUN_DIR/configs/snapshot.yaml"
+printf 'snapshot_interval_seconds: 2\nenable_snapshot: true\nenable_snapshot_restore: true\nsnapshot_catalog_store_type: invalid\n' >"$MASTER_CONFIG"
+trap 'down_cluster >/dev/null 2>&1 || true' EXIT
+# Static dependency failures must terminate before any leadership work.
+python3 - "$BUILD_DIR/mooncake-store/src/mooncake_master" "$RUN_DIR" <<'PYTEST'
+import os, pathlib, subprocess, sys
+binary, root = sys.argv[1:]
+invalid_path = pathlib.Path(root) / 'not-a-directory'
+invalid_path.write_text('file')
+for name, local_path in [('missing', ''), ('file', str(invalid_path))]:
+    env = dict(os.environ, MOONCAKE_SNAPSHOT_LOCAL_PATH=local_path)
+    result = subprocess.run([binary, '--enable_ha=true', '--enable_oplog=true',
+        '--enable_oplog_snapshot=true', '--snapshot_object_store_type=local',
+        '--etcd_endpoints=127.0.0.1:1',
+        '--logtostderr=true'], env=env, capture_output=True, text=True, timeout=10)
+    pathlib.Path(root, 'configs', name + '-failure.log').write_text(result.stderr)
+    assert result.returncode != 0, result.stderr
+    assert 'Standby dependency initialization failed' in result.stderr, result.stderr
+    assert 'candidate' not in result.stderr.lower(), result.stderr
+PYTEST
+up_cluster
+export MC_STORE_CLUSTER_ID="$CLUSTER_ID"
+GTEST_FILTER=StandbyControllerTest.BatchSnapshotRepeatedStartStopAndPromotion \
+MOONCAKE_TEST_ETCD_ENDPOINTS="$ETCD_ENDPOINTS" \
+  "$BUILD_DIR/mooncake-store/tests/hot_standby_snapshot_bootstrap_test" \
+  >"$RUN_DIR/audit/controller-lifecycle.log" 2>&1
+for index in 0 1; do
+  python3 - "$(cat "$RUN_DIR/pids/master-$index.pid")" "$RUN_DIR/snapshots" "$FAILPOINT_DIR" <<'PYENV'
+import pathlib, sys
+entries = pathlib.Path('/proc', sys.argv[1], 'environ').read_bytes().split(b'\0')
+assert ('MOONCAKE_SNAPSHOT_LOCAL_PATH=' + sys.argv[2]).encode() in entries
+if sys.argv[3]:
+    assert ('MOONCAKE_TEST_FAILPOINT_DIR=' + sys.argv[3]).encode() in entries
+PYENV
+done
+summary=$("$INSPECTOR_BIN" summary --endpoints="$ETCD_ENDPOINTS" --cluster_id="$CLUSTER_ID" --json)
+python3 -c 'import json,sys; d=json.loads(sys.argv[1]); assert d["ok"]; assert not d["errors"]' "$summary"
+client_args=(--master_server_entry="etcd://$ETCD_ENDPOINTS"
+  --engine_meta_url="http://127.0.0.1:$METADATA_PORT/metadata" --protocol=tcp
+  --payload_size=4096 --key_prefix="snapshot-$CLUSTER_ID")
+start_process provider-0 "$HA_CLIENT" --mode=provider --port="$(find_free_port)" "${client_args[@]}"
+wait_file_text "$RUN_DIR/logs/provider-0.out" provider_ready "$START_TIMEOUT_SEC"
+run_client() {
+  local mode=$1 manifest=$2
+  shift 2
+  "$HA_CLIENT" --mode="$mode" --manifest="$manifest" --port="$(find_free_port)" \
+    "${client_args[@]}" "$@" >>"$RUN_DIR/workload/$mode.log" 2>&1
+}
+pointer() {
+  ETCDCTL_API=3 etcdctl --endpoints="$ETCD_ENDPOINTS" get \
+    "/oplog/$CLUSTER_ID/snapshot/$1" --print-value-only
+}
+wait_snapshot() {
+  local previous=$1 minimum=$2 deadline=$((SECONDS + START_TIMEOUT_SEC)) value
+  while ((SECONDS < deadline)); do
+    value=$(pointer latest)
+    if [[ -n "$value" && "$value" != "$previous" ]] &&
+       python3 -c 'import json,sys; sys.exit(json.loads(sys.argv[1])["last_included_seq"] < int(sys.argv[2]))' "$value" "$minimum"; then
+      printf '%s\n' "$value"
+      return 0
+    fi
+    sleep 0.2
+  done
+  die "snapshot publication timed out"
+}
+run_client seed "$RUN_DIR/workload/first.ack" --count=12
+first=$(wait_snapshot '' "$(read_durable_sequence)")
+run_client seed "$RUN_DIR/workload/second.ack" --count=4 --start_index=100
+second=$(wait_snapshot "$first" "$(read_durable_sequence)")
+[[ -n "$(pointer fallback)" ]] || die "fallback pointer was not published"
+printf '%s\n' "$second" >"$RUN_DIR/audit/latest.json"
+python3 - "$RUN_DIR/snapshots" "$RUN_DIR/audit/latest.json" <<'PY'
+import json, pathlib, sys
+root = pathlib.Path(sys.argv[1])
+descriptor = json.load(open(sys.argv[2]))
+manifest = json.loads((root / descriptor['manifest_key']).read_text())
+assert len(manifest['object_chunks']) > 1, manifest
+for chunk in manifest['object_chunks']:
+    assert (root / chunk['key']).stat().st_size == chunk['stored_size']
+print('verified multiple snapshot chunks')
+PY
+leader=$(ready_leader_index)
+standby=$((1 - leader))
+stop_pid_file "$RUN_DIR/pids/master-$standby.pid"
+wait "$(cat "$RUN_DIR/pids/master-$standby.pid")" 2>/dev/null || true
+# Mutations now necessarily occur after the last snapshot.
+run_client seed "$RUN_DIR/workload/suffix.ack" --count=4 --start_index=200
+head -n 1 "$RUN_DIR/workload/first.ack" >"$RUN_DIR/workload/removed.ack"
+tail -n +2 "$RUN_DIR/workload/first.ack" >"$RUN_DIR/workload/survivors.ack"
+run_client delete "$RUN_DIR/workload/removed.ack"
+durable=$(read_durable_sequence)
+snapshot_seq=$(pointer latest | python3 -c 'import json,sys; print(json.load(sys.stdin)["last_included_seq"])')
+((durable > snapshot_seq)) || die "no suffix after snapshot"
+# Restart retains the store and pointers, but must not replace the snapshot
+# before we verify the restored cursor.
+start_master "$standby"
+wait_file_text "$RUN_DIR/logs/master-$standby.err" \
+  "Batch snapshot bootstrap complete: snapshot_seq=$snapshot_seq applied_seq=$durable" "$START_TIMEOUT_SEC"
+# Exercise controller stop/start through a second cold process restart.
+stop_pid_file "$RUN_DIR/pids/master-$standby.pid"
+wait "$(cat "$RUN_DIR/pids/master-$standby.pid")" 2>/dev/null || true
+start_master "$standby"
+wait_master_metric_at_least "$standby" ha_oplog_applied_sequence_id "$durable" "$START_TIMEOUT_SEC"
+"$SCRIPT_DIR/oplog_fault_ctl.sh" process kill --run-dir "$RUN_DIR" --name "master-$leader"
+wait "$(cat "$RUN_DIR/pids/master-$leader.pid")" 2>/dev/null || true
+wait_for_single_leader "$START_TIMEOUT_SEC"
+[[ "$(ready_leader_index)" == "$standby" ]] || die "restarted standby did not promote"
+wait_master_metric_at_least "$standby" master_active_clients 1 "$START_TIMEOUT_SEC"
+# Bring the former leader back as standby after promotion and verify that its
+# coordinator can publish a new snapshot.
+start_master "$leader"
+wait_file_text "$RUN_DIR/logs/master-$leader.err" \
+  "Batch snapshot bootstrap complete" "$START_TIMEOUT_SEC"
+run_client seed "$RUN_DIR/workload/post-promotion.ack" --count=4 --start_index=300
+post_promotion=$(wait_snapshot "$second" "$(read_durable_sequence)")
+[[ -n "$post_promotion" ]] || die "post-promotion snapshot was not published"
+for manifest in survivors second suffix; do
+  run_client verify "$RUN_DIR/workload/$manifest.ack"
+done
+run_client verify-absent "$RUN_DIR/workload/removed.ack"
+collect_cluster
+echo "PASS: two snapshots, cold restore, suffix replay, restart, promotion and data audit: $RUN_DIR"
diff --git a/mooncake-store/tests/e2e/run_session_ranges_tcp_e2e.sh b/mooncake-store/tests/e2e/run_session_ranges_tcp_e2e.sh
new file mode 100755
index 0000000000..92648ee830
--- /dev/null
+++ b/mooncake-store/tests/e2e/run_session_ranges_tcp_e2e.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Real TCP transport e2e for put/get session ranged multi-buffer APIs.
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+REPO_ROOT=$(cd -- "$SCRIPT_DIR/../../.." && pwd)
+BUILD_DIR=${BUILD_DIR:-"$REPO_ROOT/build"}
+LOG_DIR=${LOG_DIR:-/tmp/mooncake_session_ranges_tcp_e2e}
+MASTER_RPC=${MASTER_RPC:-127.0.0.1:50051}
+MASTER_HOST=${MASTER_RPC%:*}
+MASTER_PORT=${MASTER_RPC##*:}
+LEASE_TTL_MS=${LEASE_TTL_MS:-60000}
+
+MASTER_BIN="$BUILD_DIR/mooncake-store/src/mooncake_master"
+STORE_SO=$(ls "$BUILD_DIR"/mooncake-integration/store.cpython-*.so 2>/dev/null | head -1 || true)
+
+MASTER_PID=""
+
+cleanup() {
+  if [[ -n "${MASTER_PID}" ]]; then
+    kill "${MASTER_PID}" >/dev/null 2>&1 || true
+    wait "${MASTER_PID}" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+rm -rf "$LOG_DIR"
+mkdir -p "$LOG_DIR"
+
+if [[ ! -x "$MASTER_BIN" ]]; then
+  echo "missing mooncake_master at $MASTER_BIN; build target mooncake_master first" >&2
+  exit 2
+fi
+if [[ -z "$STORE_SO" ]]; then
+  echo "missing store python module under $BUILD_DIR/mooncake-integration" >&2
+  exit 3
+fi
+
+pkill -f "$MASTER_BIN" >/dev/null 2>&1 || true
+sleep 1
+
+echo "starting mooncake_master protocol=tcp rpc=$MASTER_RPC"
+"$MASTER_BIN" \
+  --rpc_address="$MASTER_HOST" \
+  --rpc_port="$MASTER_PORT" \
+  --default_kv_lease_ttl="$LEASE_TTL_MS" \
+  --enable_http_metadata_server=false \
+  --logtostderr=true \
+  >"$LOG_DIR/master.log" 2>&1 &
+MASTER_PID=$!
+sleep 2
+
+if ! kill -0 "$MASTER_PID" >/dev/null 2>&1; then
+  echo "mooncake_master failed to start; see $LOG_DIR/master.log" >&2
+  exit 4
+fi
+
+export PYTHONPATH="$BUILD_DIR/mooncake-integration${PYTHONPATH:+:$PYTHONPATH}"
+export LD_LIBRARY_PATH="$BUILD_DIR/mooncake-store/src:$BUILD_DIR/mooncake-common:$BUILD_DIR/mooncake-transfer-engine/src${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+export MOONCAKE_PROTOCOL=tcp
+export MOONCAKE_DEVICE=
+export MOONCAKE_MASTER="$MASTER_RPC"
+export MOONCAKE_TE_META_DATA_SERVER=P2PHANDSHAKE
+export MOONCAKE_LOCAL_HOSTNAME=localhost:17814
+# Ascend-enabled builds still try to install ascend transport unless forced.
+export MC_FORCE_TCP="${MC_FORCE_TCP:-1}"
+
+set +e
+python3 "$SCRIPT_DIR/session_ranges_tcp_e2e.py" | tee "$LOG_DIR/client.log"
+RC=${PIPESTATUS[0]}
+set -e
+
+if [[ "$RC" -eq 0 ]]; then
+  echo "PASSED: session ranges TCP e2e (logs: $LOG_DIR)"
+else
+  echo "FAILED: session ranges TCP e2e rc=$RC (logs: $LOG_DIR)" >&2
+  tail -n 80 "$LOG_DIR/master.log" >&2 || true
+fi
+exit "$RC"
diff --git a/mooncake-store/tests/e2e/session_ranges_tcp_e2e.py b/mooncake-store/tests/e2e/session_ranges_tcp_e2e.py
new file mode 100644
index 0000000000..de15499851
--- /dev/null
+++ b/mooncake-store/tests/e2e/session_ranges_tcp_e2e.py
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""TCP e2e for put/get session ranged multi-buffer APIs.
+
+Requires a running mooncake_master and built store Python module.
+
+Example:
+  PYTHONPATH=build/mooncake-integration \\
+  MOONCAKE_PROTOCOL=tcp \\
+  MOONCAKE_MASTER=127.0.0.1:50051 \\
+  MOONCAKE_TE_META_DATA_SERVER=P2PHANDSHAKE \\
+  python3 mooncake-store/tests/e2e/session_ranges_tcp_e2e.py
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+import time
+
+
+def _require_store():
+    try:
+        import store  # type: ignore
+    except Exception as exc:  # pragma: no cover
+        print(f"import_fail {exc}", flush=True)
+        raise SystemExit(10)
+    return store
+
+
+def _ptr(buf: ctypes.Array) -> int:
+    return ctypes.addressof(buf)
+
+
+def run() -> int:
+    store = _require_store()
+
+    master = os.getenv("MOONCAKE_MASTER", "127.0.0.1:50051")
+    metadata = os.getenv("MOONCAKE_TE_META_DATA_SERVER", "P2PHANDSHAKE")
+    protocol = os.getenv("MOONCAKE_PROTOCOL", "tcp")
+    device = os.getenv("MOONCAKE_DEVICE", "")
+    hostname = os.getenv("MOONCAKE_LOCAL_HOSTNAME", "localhost:17814")
+    segment = int(os.getenv("MOONCAKE_GLOBAL_SEGMENT_SIZE", str(64 * 1024 * 1024)))
+    local_buf = int(os.getenv("MOONCAKE_LOCAL_BUFFER_SIZE", str(64 * 1024 * 1024)))
+
+    num_layers = int(os.getenv("E2E_NUM_LAYERS", "4"))
+    page_size = int(os.getenv("E2E_PAGE_SIZE", "4096"))
+    num_keys = int(os.getenv("E2E_NUM_KEYS", "3"))
+    object_size = page_size * num_layers
+
+    print(
+        f"e2e_session_ranges protocol={protocol} master={master} "
+        f"keys={num_keys} layers={num_layers} page={page_size}",
+        flush=True,
+    )
+
+    mc = store.MooncakeDistributedStore()
+    setup_ret = mc.setup(
+        hostname, metadata, segment, local_buf, protocol, device, master
+    )
+    print(f"setup_ret {setup_ret}", flush=True)
+    if setup_ret != 0:
+        return setup_ret
+
+    src = (ctypes.c_char * (object_size * num_keys))()
+    dst = (ctypes.c_char * (object_size * num_keys))()
+    for i in range(len(src)):
+        src[i] = ord("a") + (i % 26)
+        dst[i] = ord("B")
+
+    assert mc.register_buffer(_ptr(src), len(src)) == 0
+    assert mc.register_buffer(_ptr(dst), len(dst)) == 0
+
+    keys = [f"session_e2e_key_{i}_{int(time.time())}" for i in range(num_keys)]
+    sizes = [object_size] * num_keys
+
+    put_start = mc.batch_put_session_start(keys, sizes)
+    print(f"batch_put_session_start {put_start}", flush=True)
+    if any(rc != 0 for rc in put_start):
+        return 20
+
+    for layer in range(num_layers):
+        all_buffers = []
+        all_sizes = []
+        all_dst_offsets = []
+        for i in range(num_keys):
+            offset = i * object_size + layer * page_size
+            all_buffers.append([_ptr(src) + offset])
+            all_sizes.append([page_size])
+            all_dst_offsets.append([layer * page_size])
+        put_rcs = mc.batch_put_from_multi_buffer_ranges(
+            keys, all_buffers, all_sizes, all_dst_offsets
+        )
+        print(f"batch_put_ranges layer={layer} rcs={put_rcs}", flush=True)
+        if any(rc != page_size for rc in put_rcs):
+            mc.batch_put_session_revoke(keys)
+            return 21
+
+    put_end = mc.batch_put_session_end(keys)
+    print(f"batch_put_session_end {put_end}", flush=True)
+    if any(rc != 0 for rc in put_end):
+        return 22
+
+    get_start = mc.batch_get_session_start(keys)
+    print(f"batch_get_session_start {get_start}", flush=True)
+    if any(rc != 0 for rc in get_start):
+        return 30
+
+    for layer in range(num_layers):
+        all_buffers = []
+        all_sizes = []
+        all_src_offsets = []
+        for i in range(num_keys):
+            offset = i * object_size + layer * page_size
+            all_buffers.append([_ptr(dst) + offset])
+            all_sizes.append([page_size])
+            all_src_offsets.append([layer * page_size])
+        get_rcs = mc.batch_get_into_multi_buffer_ranges(
+            keys, all_buffers, all_sizes, all_src_offsets
+        )
+        print(f"batch_get_ranges layer={layer} rcs={get_rcs}", flush=True)
+        if any(rc != page_size for rc in get_rcs):
+            mc.batch_get_session_end(keys)
+            return 31
+
+    get_end = mc.batch_get_session_end(keys)
+    print(f"batch_get_session_end {get_end}", flush=True)
+    if get_end != 0:
+        return 32
+
+    if bytes(src) != bytes(dst):
+        print("data_mismatch", flush=True)
+        return 40
+
+    # Revoke path: start put then revoke before end.
+    revoke_keys = [f"session_e2e_revoke_{int(time.time())}"]
+    revoke_start = mc.batch_put_session_start(revoke_keys, [page_size])
+    print(f"batch_put_session_start_revoke {revoke_start}", flush=True)
+    if any(rc != 0 for rc in revoke_start):
+        return 50
+    revoke_rcs = mc.batch_put_session_revoke(revoke_keys)
+    print(f"batch_put_session_revoke {revoke_rcs}", flush=True)
+    if any(rc != 0 for rc in revoke_rcs):
+        return 51
+
+    print("session_ranges_tcp_e2e PASSED", flush=True)
+    mc.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run())
diff --git a/mooncake-store/tests/e2e/storage_backend_e2e_test.cpp b/mooncake-store/tests/e2e/storage_backend_e2e_test.cpp
index 1a4d9b5d70..68e88d0256 100644
--- a/mooncake-store/tests/e2e/storage_backend_e2e_test.cpp
+++ b/mooncake-store/tests/e2e/storage_backend_e2e_test.cpp
@@ -28,7 +28,6 @@
 #include "client_wrapper.h"
 #include "test_server_helpers.h"
 #include "types.h"
-#include "utils.h"
 
 DEFINE_string(protocol, "tcp", "Transfer protocol: rdma|tcp");
 DEFINE_string(device_name, "ibp6s0",
diff --git a/mooncake-store/tests/file_per_key_config_test.cpp b/mooncake-store/tests/file_per_key_config_test.cpp
new file mode 100644
index 0000000000..cdfa1ad3b6
--- /dev/null
+++ b/mooncake-store/tests/file_per_key_config_test.cpp
@@ -0,0 +1,231 @@
+#include "config/file_per_key_config.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class FilePerKeyConfigTest : public ::testing::Test {
+   protected:
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("FilePerKeyConfigTest");
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void SetUp() override {
+        original_logtostderr_ = FLAGS_logtostderr;
+        FLAGS_logtostderr = true;
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_[i] = value;
+            }
+        }
+        for (const char* name : kVariables) {
+            ASSERT_EQ(unsetenv(name), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(kVariables[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+        FLAGS_logtostderr = original_logtostderr_;
+    }
+
+   private:
+    inline static constexpr std::array<const char*, 3> kVariables = {
+        "MOONCAKE_OFFLOAD_FSDIR", "MOONCAKE_OFFLOAD_ENABLE_EVICTION",
+        "ENABLE_EVICTION"};
+    std::array<std::optional<std::string>, 3> original_;
+    bool original_logtostderr_ = false;
+};
+
+TEST_F(FilePerKeyConfigTest, UnsetValuesKeepDefaults) {
+    testing::internal::CaptureStderr();
+    const auto config = FilePerKeyConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_EQ(config.fsdir, "file_per_key_dir");
+    EXPECT_TRUE(config.enable_eviction);
+    EXPECT_TRUE(config.Validate());
+    EXPECT_TRUE(diagnostics.empty());
+}
+
+TEST_F(FilePerKeyConfigTest, ReadsDirectoryVerbatimWithoutValidation) {
+    for (const char* value : {"", "   ", "relative/subdir", " /data "}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_FSDIR", value, 1), 0);
+        testing::internal::CaptureStderr();
+        const auto config = FilePerKeyConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.fsdir, value);
+        EXPECT_TRUE(diagnostics.empty());
+    }
+}
+
+TEST_F(FilePerKeyConfigTest, ValidateRejectsOnlyEmptyDirectory) {
+    FilePerKeyConfig config;
+    config.fsdir = "";
+    testing::internal::CaptureStderr();
+    const bool valid = config.Validate();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(valid);
+    EXPECT_NE(diagnostics.find("FilePerKeyConfig: fsdir is invalid"),
+              std::string::npos);
+    for (const char* value : {"   ", "relative/subdir", " /data "}) {
+        SCOPED_TRACE(value);
+        config.fsdir = value;
+        EXPECT_TRUE(config.Validate());
+    }
+}
+
+TEST_F(FilePerKeyConfigTest, BothEvictionNamesKeepBoolParsingAndWarnings) {
+    struct Case {
+        const char* value;
+        bool enabled;
+        bool warning;
+    };
+    const Case cases[] = {
+        {"1", true, false},
+        {"0", false, false},
+        {"true", true, false},
+        {"FALSE", false, false},
+        {"Yes", true, false},
+        {"nO", false, false},
+        {"on", true, false},
+        {"OFF", false, false},
+        {"enable", true, false},
+        {"DISABLE", false, false},
+        {" \tfalse\r\n", false, false},
+        {"", true, true},
+        {"   ", true, true},
+        {"2", true, true},
+        {"-1", true, true},
+        {"999999999999999999999999", true, true},
+        {"falsex", true, true},
+        {"invalid", true, true},
+    };
+    for (const char* name :
+         {"MOONCAKE_OFFLOAD_ENABLE_EVICTION", "ENABLE_EVICTION"}) {
+        SCOPED_TRACE(name);
+        for (const auto& entry : cases) {
+            SCOPED_TRACE(entry.value);
+            ASSERT_EQ(setenv(name, entry.value, 1), 0);
+            testing::internal::CaptureStderr();
+            const auto config = FilePerKeyConfig::FromEnvironment();
+            const auto diagnostics = testing::internal::GetCapturedStderr();
+
+            EXPECT_EQ(config.enable_eviction, entry.enabled);
+            const std::string expected =
+                entry.warning
+                    ? std::string("[Mooncake] Warning: invalid value '") +
+                          entry.value + "' for env " + name +
+                          ", using default 1\n"
+                    : "";
+            EXPECT_EQ(diagnostics, expected);
+        }
+        ASSERT_EQ(unsetenv(name), 0);
+    }
+}
+
+TEST_F(FilePerKeyConfigTest, PreferredEvictionNameOverridesLegacyValue) {
+    struct Case {
+        const char* legacy;
+        const char* preferred;
+        bool enabled;
+    };
+    const Case cases[] = {{"true", "false", false}, {"false", "true", true}};
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.preferred);
+        ASSERT_EQ(setenv("ENABLE_EVICTION", entry.legacy, 1), 0);
+        ASSERT_EQ(
+            setenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION", entry.preferred, 1), 0);
+        testing::internal::CaptureStderr();
+        const auto config = FilePerKeyConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.enable_eviction, entry.enabled);
+        EXPECT_TRUE(diagnostics.empty());
+    }
+}
+
+TEST_F(FilePerKeyConfigTest, InvalidPreferredValueFallsBackToLegacyValue) {
+    ASSERT_EQ(setenv("ENABLE_EVICTION", "false", 1), 0);
+    for (const char* value : {"", "bad"}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION", value, 1), 0);
+        testing::internal::CaptureStderr();
+        const auto config = FilePerKeyConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        EXPECT_FALSE(config.enable_eviction);
+        EXPECT_EQ(diagnostics,
+                  std::string("[Mooncake] Warning: invalid value '") + value +
+                      "' for env MOONCAKE_OFFLOAD_ENABLE_EVICTION, using "
+                      "default 0\n");
+    }
+}
+
+TEST_F(FilePerKeyConfigTest, InvalidLegacyValueWarnsEvenWithValidPreferred) {
+    ASSERT_EQ(setenv("ENABLE_EVICTION", "bad", 1), 0);
+    ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION", "false", 1), 0);
+    testing::internal::CaptureStderr();
+    const auto config = FilePerKeyConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.enable_eviction);
+    EXPECT_EQ(diagnostics,
+              "[Mooncake] Warning: invalid value 'bad' for env "
+              "ENABLE_EVICTION, using default 1\n");
+}
+
+TEST_F(FilePerKeyConfigTest, InvalidAliasesWarnInLegacyFirstOrder) {
+    ASSERT_EQ(setenv("ENABLE_EVICTION", "bad", 1), 0);
+    ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION", "bad", 1), 0);
+    testing::internal::CaptureStderr();
+    const auto config = FilePerKeyConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.enable_eviction);
+    EXPECT_EQ(diagnostics,
+              "[Mooncake] Warning: invalid value 'bad' for env "
+              "ENABLE_EVICTION, using default 1\n"
+              "[Mooncake] Warning: invalid value 'bad' for env "
+              "MOONCAKE_OFFLOAD_ENABLE_EVICTION, using default 1\n");
+}
+
+TEST_F(FilePerKeyConfigTest, NewConfigsReadCurrentEnvironment) {
+    ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_FSDIR", "first", 1), 0);
+    ASSERT_EQ(setenv("ENABLE_EVICTION", "false", 1), 0);
+    const auto first = FilePerKeyConfig::FromEnvironment();
+    ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_FSDIR", "second", 1), 0);
+    ASSERT_EQ(setenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION", "true", 1), 0);
+    const auto second = FilePerKeyConfig::FromEnvironment();
+    ASSERT_EQ(unsetenv("MOONCAKE_OFFLOAD_FSDIR"), 0);
+    ASSERT_EQ(unsetenv("MOONCAKE_OFFLOAD_ENABLE_EVICTION"), 0);
+    ASSERT_EQ(unsetenv("ENABLE_EVICTION"), 0);
+    const auto third = FilePerKeyConfig::FromEnvironment();
+
+    EXPECT_EQ(first.fsdir, "first");
+    EXPECT_FALSE(first.enable_eviction);
+    EXPECT_EQ(second.fsdir, "second");
+    EXPECT_TRUE(second.enable_eviction);
+    EXPECT_EQ(third.fsdir, "file_per_key_dir");
+    EXPECT_TRUE(third.enable_eviction);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/file_storage_config_test.cpp b/mooncake-store/tests/file_storage_config_test.cpp
new file mode 100644
index 0000000000..3a1a4128fc
--- /dev/null
+++ b/mooncake-store/tests/file_storage_config_test.cpp
@@ -0,0 +1,342 @@
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <filesystem>
+#include <optional>
+#include <string>
+
+#include "storage_backend.h"
+
+namespace mooncake {
+
+namespace {
+
+void SetEnv(const std::string& key, const std::string& value) {
+    setenv(key.c_str(), value.c_str(), 1);
+}
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        const char* value = std::getenv(name);
+        if (value != nullptr) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct FileStorageEnvironment {
+    ScopedEnvVar storage_backend_descriptor{
+        "MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR"};
+    ScopedEnvVar storage_path{"MOONCAKE_OFFLOAD_FILE_STORAGE_PATH"};
+    ScopedEnvVar local_buffer_size{"MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES"};
+    ScopedEnvVar pinned_restore_arena_size{
+        "MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES"};
+    ScopedEnvVar scanmeta_iterator_keys_limit{
+        "MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT"};
+    ScopedEnvVar legacy_scanmeta_iterator_keys_limit{
+        "MOONCAKE_SCANMETA_ITERATOR_KEYS_LIMIT"};
+    ScopedEnvVar total_keys_limit{"MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT"};
+    ScopedEnvVar total_size_limit{"MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES"};
+    ScopedEnvVar heartbeat_interval{
+        "MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS"};
+    ScopedEnvVar client_buffer_gc_interval{
+        "MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS"};
+    ScopedEnvVar client_buffer_gc_ttl{
+        "MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS"};
+    ScopedEnvVar enable_disk_watermark_eviction{
+        "MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION"};
+    ScopedEnvVar disk_eviction_high_watermark_ratio{
+        "MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO"};
+    ScopedEnvVar legacy_disk_eviction_high_watermark_ratio{
+        "MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO"};
+    ScopedEnvVar disk_eviction_low_watermark_ratio{
+        "MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO"};
+    ScopedEnvVar legacy_disk_eviction_low_watermark_ratio{
+        "MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO"};
+    ScopedEnvVar use_uring{"MOONCAKE_OFFLOAD_USE_URING"};
+    ScopedEnvVar legacy_use_uring{"MOONCAKE_USE_URING"};
+};
+
+void ExpectDefaultFileStorageConfig(const FileStorageConfig& config) {
+    EXPECT_EQ(config.storage_backend_type, StorageBackendType::kBucket);
+    EXPECT_EQ(config.storage_filepath, "/data/file_storage");
+    EXPECT_EQ(config.local_buffer_size, 1280 * 1024 * 1024);
+    EXPECT_EQ(config.pinned_restore_arena_size, 0);
+    EXPECT_EQ(config.scanmeta_iterator_keys_limit, 20000);
+    EXPECT_EQ(config.total_keys_limit, 10'000'000);
+    EXPECT_EQ(config.total_size_limit, 2ULL * 1024 * 1024 * 1024 * 1024);
+    EXPECT_EQ(config.heartbeat_interval_seconds, 10u);
+    EXPECT_EQ(config.client_buffer_gc_interval_seconds, 1u);
+    EXPECT_EQ(config.client_buffer_gc_ttl_ms, 5000u);
+    EXPECT_FALSE(config.use_uring);
+    EXPECT_FALSE(config.enable_dfs);
+    EXPECT_TRUE(config.enable_disk_watermark_eviction);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.80);
+}
+
+class FileStorageConfigTest : public ::testing::Test {
+   protected:
+    FileStorageEnvironment env;
+    std::filesystem::path data_path;
+
+    void SetUp() override {
+        google::InitGoogleLogging("FileStorageConfigTest");
+        FLAGS_logtostderr = true;
+        data_path =
+            std::filesystem::current_path() / "file_storage_config_data";
+        std::filesystem::create_directories(data_path);
+    }
+
+    void TearDown() override {
+        google::ShutdownGoogleLogging();
+        std::error_code ec;
+        std::filesystem::remove_all(data_path, ec);
+    }
+};
+
+TEST_F(FileStorageConfigTest, DefaultValuesWhenNoEnvSet) {
+    const auto config = FileStorageConfig::FromEnvironment();
+
+    ExpectDefaultFileStorageConfig(config);
+}
+
+TEST_F(FileStorageConfigTest, ReadsValidValues) {
+    env.storage_backend_descriptor.Set("distributed_storage_backend");
+    env.storage_path.Set("/tmp/storage");
+    env.local_buffer_size.Set("2147483648");
+    env.pinned_restore_arena_size.Set("67108864");
+    env.scanmeta_iterator_keys_limit.Set("12345");
+    env.total_keys_limit.Set("5000000");
+    env.total_size_limit.Set("1099511627776");
+    env.heartbeat_interval.Set("5");
+    env.client_buffer_gc_interval.Set("7");
+    env.client_buffer_gc_ttl.Set("9000");
+    env.enable_disk_watermark_eviction.Set("0");
+    env.disk_eviction_high_watermark_ratio.Set("0.75");
+    env.disk_eviction_low_watermark_ratio.Set("0.50");
+    env.use_uring.Set("1");
+
+    const auto config = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(config.storage_backend_type, StorageBackendType::kDistributed);
+    EXPECT_FALSE(config.enable_dfs);
+    EXPECT_EQ(config.storage_filepath, "/tmp/storage");
+    EXPECT_EQ(config.local_buffer_size, 2147483648);
+    EXPECT_EQ(config.pinned_restore_arena_size, 64 * 1024 * 1024);
+    EXPECT_EQ(config.scanmeta_iterator_keys_limit, 12345);
+    EXPECT_EQ(config.total_keys_limit, 5000000);
+    EXPECT_EQ(config.total_size_limit, 1099511627776);
+    EXPECT_EQ(config.heartbeat_interval_seconds, 5u);
+    EXPECT_EQ(config.client_buffer_gc_interval_seconds, 7u);
+    EXPECT_EQ(config.client_buffer_gc_ttl_ms, 9000u);
+    EXPECT_FALSE(config.enable_disk_watermark_eviction);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.75);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.50);
+    EXPECT_TRUE(config.use_uring);
+}
+
+TEST_F(FileStorageConfigTest, PreservesAliasPrecedence) {
+    env.legacy_scanmeta_iterator_keys_limit.Set("111");
+    env.legacy_disk_eviction_high_watermark_ratio.Set("0.77");
+    env.legacy_disk_eviction_low_watermark_ratio.Set("0.55");
+    env.legacy_use_uring.Set("true");
+
+    const auto fallback = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(fallback.scanmeta_iterator_keys_limit, 111);
+    EXPECT_DOUBLE_EQ(fallback.disk_eviction_high_watermark_ratio, 0.77);
+    EXPECT_DOUBLE_EQ(fallback.disk_eviction_low_watermark_ratio, 0.55);
+    EXPECT_TRUE(fallback.use_uring);
+
+    env.scanmeta_iterator_keys_limit.Set("222");
+    env.disk_eviction_high_watermark_ratio.Set("0.75");
+    env.disk_eviction_low_watermark_ratio.Set("0.50");
+    env.use_uring.Set("false");
+
+    const auto preferred = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(preferred.scanmeta_iterator_keys_limit, 222);
+    EXPECT_DOUBLE_EQ(preferred.disk_eviction_high_watermark_ratio, 0.75);
+    EXPECT_DOUBLE_EQ(preferred.disk_eviction_low_watermark_ratio, 0.50);
+    EXPECT_FALSE(preferred.use_uring);
+}
+
+TEST_F(FileStorageConfigTest, PreservesEmptyPreferredAliasBehavior) {
+    env.legacy_scanmeta_iterator_keys_limit.Set("111");
+    env.legacy_disk_eviction_high_watermark_ratio.Set("0.77");
+    env.legacy_disk_eviction_low_watermark_ratio.Set("0.55");
+    env.legacy_use_uring.Set("true");
+    env.scanmeta_iterator_keys_limit.Set("");
+    env.disk_eviction_high_watermark_ratio.Set("");
+    env.disk_eviction_low_watermark_ratio.Set("");
+    env.use_uring.Set("");
+
+    const auto config = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(config.scanmeta_iterator_keys_limit, 111);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.77);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.55);
+    EXPECT_FALSE(config.use_uring);
+}
+
+TEST_F(FileStorageConfigTest, PreservesInvalidPreferredAliasBehavior) {
+    env.legacy_scanmeta_iterator_keys_limit.Set("111");
+    env.legacy_disk_eviction_high_watermark_ratio.Set("0.77");
+    env.legacy_disk_eviction_low_watermark_ratio.Set("0.55");
+    env.legacy_use_uring.Set("true");
+    env.scanmeta_iterator_keys_limit.Set("invalid");
+    env.disk_eviction_high_watermark_ratio.Set("invalid");
+    env.disk_eviction_low_watermark_ratio.Set("invalid");
+    env.use_uring.Set("invalid");
+
+    const auto config = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(config.scanmeta_iterator_keys_limit, 111);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.80);
+    EXPECT_FALSE(config.use_uring);
+}
+
+TEST_F(FileStorageConfigTest, InvalidValuesUseDefaultsAndPreserveDiagnostics) {
+    env.local_buffer_size.Set("invalid");
+    env.pinned_restore_arena_size.Set("invalid");
+    env.scanmeta_iterator_keys_limit.Set("invalid");
+    env.total_keys_limit.Set("invalid");
+    env.total_size_limit.Set("invalid");
+    env.heartbeat_interval.Set("invalid");
+    env.client_buffer_gc_interval.Set("invalid");
+    env.client_buffer_gc_ttl.Set("invalid");
+    env.enable_disk_watermark_eviction.Set("invalid");
+    env.disk_eviction_high_watermark_ratio.Set("0.75suffix");
+    env.disk_eviction_low_watermark_ratio.Set("nan");
+    env.use_uring.Set("invalid");
+
+    ::testing::internal::CaptureStderr();
+    const auto config = FileStorageConfig::FromEnvironment();
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    ExpectDefaultFileStorageConfig(config);
+    for (const char* name : {
+             "MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES",
+             "MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES",
+             "MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT",
+             "MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT",
+             "MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES",
+             "MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS",
+             "MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS",
+             "MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS",
+         }) {
+        EXPECT_NE(logs.find(name), std::string::npos) << name;
+    }
+    EXPECT_EQ(logs.find("MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION"),
+              std::string::npos);
+    EXPECT_EQ(logs.find("MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO"),
+              std::string::npos);
+    EXPECT_EQ(logs.find("MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO"),
+              std::string::npos);
+    EXPECT_EQ(logs.find("MOONCAKE_OFFLOAD_USE_URING"), std::string::npos);
+}
+
+TEST_F(FileStorageConfigTest, InvalidIntValueUsesDefault) {
+    SetEnv("MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES", "sdfsdf");
+    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "-1");
+
+    const auto config = FileStorageConfig::FromEnvironment();
+
+    EXPECT_EQ(config.total_size_limit, 2ULL * 1024 * 1024 * 1024 * 1024);
+    EXPECT_EQ(config.heartbeat_interval_seconds, 10u);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.80);
+}
+
+TEST_F(FileStorageConfigTest, OutOfRangeValueUsesDefault) {
+    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "4294967296");
+    const auto too_large = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(too_large.heartbeat_interval_seconds, 10u);
+
+    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "-10");
+    const auto negative = FileStorageConfig::FromEnvironment();
+    EXPECT_EQ(negative.heartbeat_interval_seconds, 10u);
+}
+
+TEST_F(FileStorageConfigTest, ValidateSuccessWithValidConfig) {
+    FileStorageConfig config;
+    config.storage_filepath = data_path.string();
+    config.total_keys_limit = 1000000;
+    config.total_size_limit = 1073741824;
+    config.heartbeat_interval_seconds = 5;
+
+    EXPECT_TRUE(config.Validate());
+}
+
+TEST_F(FileStorageConfigTest, ValidateFailsOnInvalidStoragePath) {
+    FileStorageConfig config;
+    config.storage_filepath = "";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "   ";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "relative/path";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "./data";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "../data";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "/valid/../invalid";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "/path/./sub";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = "/tmp/this_directory_does_not_exist_12345";
+    EXPECT_FALSE(config.Validate());
+    config.storage_filepath = data_path.string();
+    EXPECT_TRUE(config.Validate());
+}
+
+TEST_F(FileStorageConfigTest, ValidateFailsOnInvalidLimits) {
+    FileStorageConfig config;
+    config.storage_filepath = "/tmp";
+
+    config.total_keys_limit = 0;
+    EXPECT_FALSE(config.Validate());
+
+    config.total_keys_limit = 1;
+    config.total_size_limit = 0;
+    EXPECT_FALSE(config.Validate());
+
+    config.total_size_limit = 1;
+    config.pinned_restore_arena_size = -1;
+    EXPECT_FALSE(config.Validate());
+
+    config.pinned_restore_arena_size = 0;
+    config.heartbeat_interval_seconds = 0;
+    EXPECT_FALSE(config.Validate());
+
+    config.heartbeat_interval_seconds = 1;
+    config.disk_eviction_low_watermark_ratio = 0.9;
+    config.disk_eviction_high_watermark_ratio = 0.8;
+    EXPECT_FALSE(config.Validate());
+
+    config.disk_eviction_low_watermark_ratio = 0.0;
+    config.disk_eviction_high_watermark_ratio = 0.8;
+    EXPECT_FALSE(config.Validate());
+
+    config.disk_eviction_low_watermark_ratio = 0.8;
+    config.disk_eviction_high_watermark_ratio = 1.1;
+    EXPECT_FALSE(config.Validate());
+}
+
+}  // namespace
+
+}  // namespace mooncake
diff --git a/mooncake-store/tests/file_storage_test.cpp b/mooncake-store/tests/file_storage_test.cpp
index ef29ccae8b..f3ebd336b5 100644
--- a/mooncake-store/tests/file_storage_test.cpp
+++ b/mooncake-store/tests/file_storage_test.cpp
@@ -1,17 +1,21 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <chrono>
 #include <cstring>
+#include <cstdlib>
 #include <filesystem>
-#include <optional>
+#include <string>
 #include <thread>
 
 #include "allocator.h"
 #include "client_metric.h"
+#include "common/network.h"
 #include "file_storage.h"
 #include "storage_backend.h"
 #include "tenant_id.h"
 #include "test_server_helpers.h"
+#include "common/client_buffer_allocation.h"
 #include "utils/common.h"
 
 namespace mooncake {
@@ -28,8 +32,10 @@ class FileStorageTest : public ::testing::Test {
     void SetUp() override {
         google::InitGoogleLogging("FileStorageTest");
         FLAGS_logtostderr = true;
+        UnsetEnv("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR");
         UnsetEnv("MOONCAKE_OFFLOAD_FILE_STORAGE_PATH");
         UnsetEnv("MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES");
+        UnsetEnv("MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES");
         UnsetEnv("MOONCAKE_OFFLOAD_SCANMETA_ITERATOR_KEYS_LIMIT");
         UnsetEnv("MOONCAKE_SCANMETA_ITERATOR_KEYS_LIMIT");
         UnsetEnv("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT");
@@ -37,12 +43,21 @@ class FileStorageTest : public ::testing::Test {
         UnsetEnv("MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT");
         UnsetEnv("MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES");
         UnsetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS");
+        UnsetEnv("MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_INTERVAL_SECONDS");
+        UnsetEnv("MOONCAKE_OFFLOAD_CLIENT_BUFFER_GC_TTL_MS");
         UnsetEnv("MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION");
         UnsetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO");
         UnsetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO");
         UnsetEnv("MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO");
         UnsetEnv("MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO");
-        data_path = std::filesystem::current_path().string() + "/data";
+        UnsetEnv("MOONCAKE_OFFLOAD_USE_URING");
+        UnsetEnv("MOONCAKE_USE_URING");
+        UnsetEnv("MOONCAKE_DISTRIBUTED_FS_TYPE");
+        UnsetEnv("MOONCAKE_DFS_FS_ADAPTER");
+        UnsetEnv("MOONCAKE_DISTRIBUTED_ROOT_DIR");
+        UnsetEnv("MOONCAKE_DFS_ROOT_DIR");
+        data_path = (std::filesystem::current_path() / "file_storage_test_data")
+                        .string();
         fs::create_directories(data_path);
         for (const auto& entry : fs::directory_iterator(data_path)) {
             std::error_code ec;
@@ -67,7 +82,14 @@ class FileStorageTest : public ::testing::Test {
     FileStorageAllocateBatch(FileStorage& fileStorage,
                              const std::vector<std::string>& keys,
                              const std::vector<int64_t>& sizes) {
-        return fileStorage.AllocateBatch(keys, sizes);
+        return fileStorage.AllocateBatch(keys, sizes,
+                                         *fileStorage.client_buffer_allocator_);
+    }
+
+    void SetPinnedRestoreArena(FileStorage& fileStorage, void* address,
+                               size_t size) {
+        fileStorage.pinned_restore_arena_allocator_ =
+            ClientBufferAllocator::create(address, size);
     }
 
     tl::expected<void, ErrorCode> FileStorageBatchLoad(
@@ -81,6 +103,10 @@ class FileStorageTest : public ::testing::Test {
         return fileStorage.IsEnableOffloading();
     }
 
+    bool FileStorageUsesDfsControlPlane(const FileStorage& file_storage) {
+        return file_storage.config_.enable_dfs;
+    }
+
     tl::expected<void, ErrorCode> FileStorageNotifyEvictedDiskReplicas(
         FileStorage& fileStorage,
         const std::vector<std::string>& evicted_keys) {
@@ -115,6 +141,52 @@ class FileStorageTest : public ::testing::Test {
         return FileStorage::IsPerBucketSoftOffloadError(error);
     }
 
+    // Funnel to the private FileStorage::Heartbeat, for the drain tests.
+    static tl::expected<void, ErrorCode> FileStorageHeartbeat(
+        FileStorage& fileStorage) {
+        return fileStorage.Heartbeat();
+    }
+
+    // Drives the drain-vs-heartbeat interleaving deterministically: a
+    // heartbeat tick that has already passed its entry draining_ check parks
+    // on offloading_mutex_, a drain runs, and the parked tick resumes only
+    // around the drain's own critical section. The fixture holds the mutex
+    // as the scheduler while both threads are launched, so the tick is
+    // provably not inside its RPC section when the drain latches. After the
+    // release the two race for the lock; the postcondition (segment
+    // deregistered, never re-mounted) must hold in both wake orders, so the
+    // assertions do not depend on the schedule. Without the drain taking
+    // offloading_mutex_, the parked tick would resume after the drain
+    // finished, get SEGMENT_NOT_FOUND, and re-mount the segment.
+    tl::expected<void, ErrorCode> DrainWhileHeartbeatTickParked(
+        FileStorage& fileStorage) {
+        // The parked tick may win the lock and run a full pass, which is
+        // only supported on an initialized backend (Init() is also what
+        // starts the heartbeat thread in production).
+        EXPECT_TRUE(fileStorage.storage_backend_->Init());
+        tl::expected<void, ErrorCode> drain_result =
+            tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
+        std::thread heartbeat_thread;
+        std::thread drain_thread;
+        {
+            MutexLocker scheduler(&fileStorage.offloading_mutex_);
+            heartbeat_thread =
+                std::thread([&fileStorage] { fileStorage.Heartbeat(); });
+            // Let the tick pass the entry check and park on the mutex we
+            // hold. The assertions do not depend on it parking -- a tick
+            // that has not reached the lock is caught by the entry check
+            // instead -- the pause just pins the adversarial schedule.
+            std::this_thread::sleep_for(std::chrono::milliseconds(200));
+            drain_thread = std::thread([&fileStorage, &drain_result] {
+                drain_result = fileStorage.DrainLocalDiskSegment(0);
+            });
+            std::this_thread::sleep_for(std::chrono::milliseconds(200));
+        }
+        heartbeat_thread.join();
+        drain_thread.join();
+        return drain_result;
+    }
+
     void AssertHeartbeatEvictsAllKeys(
         FileStorage& fileStorage, const std::vector<std::string>& expected_keys,
         const std::unordered_map<std::string, std::vector<Slice>>&
@@ -176,6 +248,255 @@ class FileStorageTest : public ::testing::Test {
             }
         }
     }
+    void RunPutHealWipeScenario(const std::string& data_path,
+                                StorageBackendType backend_type,
+                                const std::string& suffix) {
+        std::filesystem::path master_root =
+            std::filesystem::path(data_path) / ("heal_master" + suffix);
+        std::filesystem::create_directories(master_root);
+
+        testing::InProcMaster master;
+        auto master_config = InProcMasterConfigBuilder()
+                                 .set_enable_offload(true)
+                                 .set_root_fs_dir(master_root.string())
+                                 .build();
+        ASSERT_TRUE(master.Start(master_config));
+
+        std::string local_rpc_addr =
+            "127.0.0.1:" + std::to_string(getFreeTcpPort());
+        auto client =
+            Client::Create(local_rpc_addr, master.metadata_url(), "tcp",
+                           std::nullopt, master.master_address());
+        ASSERT_TRUE(client.has_value());
+        ASSERT_TRUE(client.value()->MountLocalDiskSegment(true).has_value());
+
+        // Memory segment and registered buffers, so the retried PutStart can
+        // allocate a memory replica and Get can read it back.
+        constexpr size_t kSegSize = 64 * 1024 * 1024;
+        void* seg_ptr = allocate_buffer_allocator_memory(kSegSize);
+        ASSERT_NE(seg_ptr, nullptr);
+        ASSERT_TRUE(
+            client.value()->MountSegment(seg_ptr, kSegSize, "tcp").has_value());
+        SimpleAllocator allocator(16 * 1024 * 1024);
+        ASSERT_TRUE(client.value()
+                        ->RegisterLocalMemory(allocator.getBase(),
+                                              16 * 1024 * 1024, "cpu:0", false,
+                                              false)
+                        .has_value());
+
+        FileStorageConfig config = FileStorageConfig::FromEnvironment();
+        config.storage_backend_type = backend_type;
+        config.storage_filepath = data_path + "/heal_ssd" + suffix;
+        config.local_buffer_size = 4 * 1024 * 1024;
+        fs::create_directories(config.storage_filepath);
+        FileStorage file_storage(config, client.value(), local_rpc_addr);
+        ASSERT_TRUE(file_storage.storage_backend_->Init());
+        {
+            MutexLocker locker(&file_storage.offloading_mutex_);
+            file_storage.enable_offloading_ = true;
+        }
+
+        // Offload one key so master tracks a LOCAL_DISK replica backed by a
+        // real file on the client SSD.
+        const std::string key = "heal_key" + suffix;
+        std::string original(512, 'x');
+        std::unordered_map<std::string, std::vector<Slice>> batch_object;
+        batch_object.emplace(key,
+                             std::vector<Slice>{Slice{original.data(), 512}});
+        auto offload_result = file_storage.storage_backend_->BatchOffload(
+            batch_object,
+            [&file_storage](const std::vector<std::string>& keys,
+                            std::vector<StorageObjectMetadata>& metadatas) {
+                for (auto& metadata : metadatas) {
+                    metadata.transport_endpoint = file_storage.local_rpc_addr_;
+                }
+                auto result =
+                    file_storage.client_->NotifyOffloadSuccess(keys, metadatas);
+                return result ? ErrorCode::OK : result.error();
+            });
+        ASSERT_TRUE(offload_result.has_value());
+
+        // Wire the probe the way RealClient does in production: existence
+        // against this process's offload files.
+        client.value()->SetLocalDiskProbe(
+            [&file_storage](const std::string& k) -> std::optional<bool> {
+                auto exists = file_storage.Exists(k);
+                if (!exists) {
+                    return std::nullopt;
+                }
+                return !*exists;
+            });
+
+        auto query = client.value()->Query(key);
+        ASSERT_TRUE(query.has_value());
+        bool has_local_disk = false;
+        for (const auto& replica : query->replicas) {
+            has_local_disk |= replica.is_local_disk_replica();
+        }
+        ASSERT_TRUE(has_local_disk);
+
+        // Simulate the #3709 divergence: the SSD file is wiped physically while
+        // master keeps the metadata.
+        file_storage.storage_backend_->RemoveAll();
+        auto exists = file_storage.Exists(key);
+        ASSERT_TRUE(exists.has_value());
+        ASSERT_FALSE(exists.value());
+        // QueryResult is not assignable, so re-query into a fresh variable.
+        auto query_after_wipe = client.value()->Query(key);
+        ASSERT_TRUE(query_after_wipe.has_value());
+
+        // Put the same key again: the dangling replica must be evicted and the
+        // Put must really store new data.
+        void* buf = allocator.allocate(512);
+        ASSERT_NE(buf, nullptr);
+        std::string updated(512, 'y');
+        std::memcpy(buf, updated.data(), 512);
+        std::vector<Slice> slices{Slice{buf, 512}};
+        ReplicateConfig cfg;
+        cfg.replica_num = 1;
+        auto put = client.value()->Put(key, slices, cfg);
+        ASSERT_TRUE(put.has_value())
+            << "Put over a dangling replica failed: " << toString(put.error());
+        allocator.deallocate(buf, 512);
+
+        // The new data is readable through the normal Get path.
+        void* read_buf = allocator.allocate(512);
+        ASSERT_NE(read_buf, nullptr);
+        std::vector<Slice> read_slices{Slice{read_buf, 512}};
+        auto get = client.value()->Get(key, read_slices);
+        ASSERT_TRUE(get.has_value())
+            << "Get after self-heal failed: " << toString(get.error());
+        EXPECT_EQ(std::memcmp(read_slices[0].ptr, updated.data(), 512), 0);
+        allocator.deallocate(read_buf, 512);
+
+        auto unmount = client.value()->UnmountSegment(seg_ptr, kSegSize);
+        EXPECT_TRUE(unmount.has_value());
+        std::free(seg_ptr);
+    }
+    void RunBatchPutHealWipeScenario(const std::string& data_path) {
+        std::filesystem::path master_root =
+            std::filesystem::path(data_path) / "heal_master_batch";
+        std::filesystem::create_directories(master_root);
+
+        testing::InProcMaster master;
+        auto master_config = InProcMasterConfigBuilder()
+                                 .set_enable_offload(true)
+                                 .set_root_fs_dir(master_root.string())
+                                 .build();
+        ASSERT_TRUE(master.Start(master_config));
+
+        std::string local_rpc_addr =
+            "127.0.0.1:" + std::to_string(getFreeTcpPort());
+        auto client =
+            Client::Create(local_rpc_addr, master.metadata_url(), "tcp",
+                           std::nullopt, master.master_address());
+        ASSERT_TRUE(client.has_value());
+        ASSERT_TRUE(client.value()->MountLocalDiskSegment(true).has_value());
+
+        constexpr size_t kSegSize = 64 * 1024 * 1024;
+        void* seg_ptr = allocate_buffer_allocator_memory(kSegSize);
+        ASSERT_NE(seg_ptr, nullptr);
+        ASSERT_TRUE(
+            client.value()->MountSegment(seg_ptr, kSegSize, "tcp").has_value());
+        SimpleAllocator allocator(16 * 1024 * 1024);
+        ASSERT_TRUE(client.value()
+                        ->RegisterLocalMemory(allocator.getBase(),
+                                              16 * 1024 * 1024, "cpu:0", false,
+                                              false)
+                        .has_value());
+
+        FileStorageConfig config = FileStorageConfig::FromEnvironment();
+        config.storage_backend_type = StorageBackendType::kFilePerKey;
+        config.storage_filepath = data_path + "/heal_ssd_batch";
+        config.local_buffer_size = 4 * 1024 * 1024;
+        fs::create_directories(config.storage_filepath);
+        FileStorage file_storage(config, client.value(), local_rpc_addr);
+        ASSERT_TRUE(file_storage.storage_backend_->Init());
+        {
+            MutexLocker locker(&file_storage.offloading_mutex_);
+            file_storage.enable_offloading_ = true;
+        }
+
+        // Offload two keys, then wipe the backing files to recreate the #3709
+        // divergence on both.
+        const std::vector<std::string> wiped_keys = {"heal_batch_a",
+                                                     "heal_batch_b"};
+        std::string original(512, 'x');
+        std::unordered_map<std::string, std::vector<Slice>> batch_object;
+        for (const auto& key : wiped_keys) {
+            batch_object.emplace(
+                key, std::vector<Slice>{Slice{original.data(), 512}});
+        }
+        auto offload_result = file_storage.storage_backend_->BatchOffload(
+            batch_object,
+            [&file_storage](const std::vector<std::string>& keys,
+                            std::vector<StorageObjectMetadata>& metadatas) {
+                for (auto& metadata : metadatas) {
+                    metadata.transport_endpoint = file_storage.local_rpc_addr_;
+                }
+                auto result =
+                    file_storage.client_->NotifyOffloadSuccess(keys, metadatas);
+                return result ? ErrorCode::OK : result.error();
+            });
+        ASSERT_TRUE(offload_result.has_value());
+
+        client.value()->SetLocalDiskProbe(
+            [&file_storage](const std::string& k) -> std::optional<bool> {
+                auto exists = file_storage.Exists(k);
+                if (!exists) {
+                    return std::nullopt;
+                }
+                return !*exists;
+            });
+
+        file_storage.storage_backend_->RemoveAll();
+        auto exists = file_storage.Exists(wiped_keys[0]);
+        ASSERT_TRUE(exists.has_value());
+        ASSERT_FALSE(exists.value());
+
+        // One batch with both wiped keys and a fresh key.
+        const std::string fresh_key = "heal_batch_fresh";
+        const std::string updated(512, 'y');
+        std::vector<ObjectKey> keys = {wiped_keys[0], wiped_keys[1], fresh_key};
+        std::vector<std::vector<Slice>> batched_slices;
+        std::vector<void*> buffers;
+        for (size_t i = 0; i < keys.size(); ++i) {
+            void* buf = allocator.allocate(512);
+            ASSERT_NE(buf, nullptr);
+            std::memcpy(buf, updated.data(), 512);
+            buffers.push_back(buf);
+            batched_slices.push_back({Slice{buf, 512}});
+        }
+        ReplicateConfig cfg;
+        cfg.replica_num = 1;
+        auto results = client.value()->BatchPut(keys, batched_slices, cfg);
+        ASSERT_EQ(results.size(), keys.size());
+        for (size_t i = 0; i < results.size(); ++i) {
+            ASSERT_TRUE(results[i].has_value())
+                << "BatchPut over a dangling replica failed for " << keys[i]
+                << ": " << toString(results[i].error());
+        }
+
+        // Every key, healed or fresh, reads the new data back.
+        for (const auto& key : keys) {
+            void* read_buf = allocator.allocate(512);
+            ASSERT_NE(read_buf, nullptr);
+            std::vector<Slice> read_slices{Slice{read_buf, 512}};
+            auto get = client.value()->Get(key, read_slices);
+            ASSERT_TRUE(get.has_value())
+                << "Get after batch self-heal failed for " << key << ": "
+                << toString(get.error());
+            EXPECT_EQ(std::memcmp(read_slices[0].ptr, updated.data(), 512), 0);
+            allocator.deallocate(read_buf, 512);
+        }
+        for (void* buf : buffers) {
+            allocator.deallocate(buf, 512);
+        }
+
+        auto unmount = client.value()->UnmountSegment(seg_ptr, kSegSize);
+        EXPECT_TRUE(unmount.has_value());
+        std::free(seg_ptr);
+    }
 };
 
 TEST_F(FileStorageTest, IsEnableOffloading) {
@@ -216,27 +537,102 @@ TEST_F(FileStorageTest, IsEnableOffloading) {
                 !enable_offloading_result3.value());
 }
 
-TEST_F(FileStorageTest, BatchLoad) {
+TEST_F(FileStorageTest, DistributedBackendSelectsControlPlaneFromStorageMode) {
+    SetEnv("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR",
+           "distributed_storage_backend");
+    SetEnv("MOONCAKE_DISTRIBUTED_ROOT_DIR", data_path + "/distributed");
+
+    auto config = FileStorageConfig::FromEnvironment();
+    config.storage_filepath = data_path;
+    config.local_buffer_size = 4 * 1024 * 1024;
+    EXPECT_FALSE(config.enable_dfs);
+
+    SetEnv("MOONCAKE_DISTRIBUTED_FS_TYPE", "posix");
+    {
+        FileStorage file_storage(config, nullptr, "localhost:9003");
+        EXPECT_TRUE(FileStorageUsesDfsControlPlane(file_storage));
+    }
+
+#ifdef HAVE_OSS_ADAPTER
+    SetEnv("MOONCAKE_DISTRIBUTED_FS_TYPE", "oss");
+    FileStorage file_storage(config, nullptr, "localhost:9003");
+    EXPECT_FALSE(FileStorageUsesDfsControlPlane(file_storage));
+
+    auto enable_offloading = FileStorageIsEnableOffloading(file_storage);
+    ASSERT_TRUE(enable_offloading);
+    EXPECT_TRUE(*enable_offloading);
+#endif
+}
+
+TEST_F(FileStorageTest, BatchGetUsesPinnedArenaAndFallsBackWhenFull) {
     std::vector<std::string> keys;
     std::vector<int64_t> sizes;
     std::unordered_map<std::string, std::string> batch_data;
+
     auto file_storage_config = FileStorageConfig::FromEnvironment();
     file_storage_config.storage_filepath = data_path;
+    file_storage_config.local_buffer_size = 128 * 1024 * 1024;
     FileStorage fileStorage(file_storage_config, nullptr, "localhost:9003");
     ASSERT_TRUE(FileStorageBatchOffload(fileStorage, keys, sizes, batch_data));
-    std::unordered_map<std::string, Slice> batch_slice;
-    std::vector<BufferHandle> buff;
 
-    auto allocate_res = FileStorageAllocateBatch(fileStorage, keys, sizes);
-    ASSERT_TRUE(allocate_res);
+    size_t payload_size = 0;
+    for (const auto size : sizes) {
+        payload_size += static_cast<size_t>(size);
+    }
+    const size_t arena_size = payload_size * 3 / 2;
+    std::vector<char> restore_arena(arena_size + 4096);
+    const auto arena_begin =
+        (reinterpret_cast<uintptr_t>(restore_arena.data()) + 4095) & ~4095ULL;
+    SetPinnedRestoreArena(fileStorage, reinterpret_cast<void*>(arena_begin),
+                          arena_size);
+
+    auto pinned_result = fileStorage.BatchGetLocal(keys, sizes);
+    ASSERT_TRUE(pinned_result);
+    ASSERT_EQ(pinned_result->pointers.size(), keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        EXPECT_GE(pinned_result->pointers[i], arena_begin);
+        EXPECT_LT(pinned_result->pointers[i], arena_begin + arena_size);
+        EXPECT_EQ(
+            std::string(reinterpret_cast<char*>(pinned_result->pointers[i]),
+                        sizes[i]),
+            batch_data.at(keys[i]));
+    }
 
-    ASSERT_TRUE(
-        FileStorageBatchLoad(fileStorage, allocate_res.value()->slices));
-    for (auto& slice_it : batch_slice) {
-        std::string data(static_cast<char*>(slice_it.second.ptr),
-                         slice_it.second.size);
-        LOG(INFO) << "key: " << slice_it.first;
-        ASSERT_EQ(data, batch_data.at(slice_it.first));
+    auto fallback_result = fileStorage.BatchGetLocal(keys, sizes);
+    ASSERT_TRUE(fallback_result);
+    ASSERT_EQ(fallback_result->pointers.size(), keys.size());
+    for (size_t i = 0; i < keys.size(); ++i) {
+        EXPECT_TRUE(fallback_result->pointers[i] < arena_begin ||
+                    fallback_result->pointers[i] >= arena_begin + arena_size);
+        EXPECT_EQ(
+            std::string(reinterpret_cast<char*>(fallback_result->pointers[i]),
+                        sizes[i]),
+            batch_data.at(keys[i]));
+    }
+}
+
+TEST_F(FileStorageTest, AllocateBatchAvoidsDirectIoPaddingForPosixReads) {
+    auto file_storage_config = FileStorageConfig::FromEnvironment();
+    file_storage_config.storage_filepath = data_path;
+    file_storage_config.local_buffer_size = 64 * 1024;
+    file_storage_config.use_uring = false;
+    FileStorage fileStorage(file_storage_config, nullptr, "localhost:9003");
+
+    std::vector<std::string> keys;
+    std::vector<int64_t> sizes;
+    for (size_t i = 0; i < 16; ++i) {
+        keys.emplace_back("key" + std::to_string(i));
+        sizes.emplace_back(4 * 1024);
+    }
+
+    auto allocate_result = FileStorageAllocateBatch(fileStorage, keys, sizes);
+    ASSERT_TRUE(allocate_result)
+        << "POSIX reads should not reserve O_DIRECT padding";
+    EXPECT_EQ(allocate_result.value()->total_size,
+              file_storage_config.local_buffer_size);
+    ASSERT_EQ(allocate_result.value()->handles.size(), keys.size());
+    for (const auto& handle : allocate_result.value()->handles) {
+        EXPECT_EQ(handle.size(), 4 * 1024);
     }
 }
 
@@ -258,6 +654,9 @@ TEST_F(FileStorageTest, GroupOffloadingKeysByBucket_bucket_keys_limit) {
         ASSERT_EQ(bucket_keys.size(), 10);
     }
     ASSERT_EQ(GetUngroupedOffloadingObjectsSize(fileStorage), 5);
+    for (size_t i = 35; i < 40; ++i) {
+        offloading_objects.emplace("test" + std::to_string(i), 1);
+    }
     buckets_keys.clear();
     ASSERT_TRUE(FileStorageGroupOffloadingKeysByBucket(
         fileStorage, offloading_objects, buckets_keys));
@@ -268,6 +667,35 @@ TEST_F(FileStorageTest, GroupOffloadingKeysByBucket_bucket_keys_limit) {
     ASSERT_EQ(GetUngroupedOffloadingObjectsSize(fileStorage), 0);
 }
 
+TEST_F(FileStorageTest, GroupOffloadingKeysByBucket_deduplicates_carryover) {
+    std::unordered_map<std::string, int64_t> offloading_objects;
+    offloading_objects.emplace("duplicate", 1);
+
+    std::vector<std::vector<std::string>> buckets_keys;
+    auto file_storage_config = FileStorageConfig::FromEnvironment();
+    file_storage_config.storage_filepath = data_path;
+    SetEnv("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", "10");
+    FileStorage fileStorage(file_storage_config, nullptr, "localhost:9003");
+
+    ASSERT_TRUE(FileStorageGroupOffloadingKeysByBucket(
+        fileStorage, offloading_objects, buckets_keys));
+    ASSERT_TRUE(buckets_keys.empty());
+    ASSERT_EQ(GetUngroupedOffloadingObjectsSize(fileStorage), 1);
+
+    for (size_t i = 0; i < 9; ++i) {
+        offloading_objects.emplace("new" + std::to_string(i), 1);
+    }
+    ASSERT_TRUE(FileStorageGroupOffloadingKeysByBucket(
+        fileStorage, offloading_objects, buckets_keys));
+
+    ASSERT_EQ(buckets_keys.size(), 1);
+    ASSERT_EQ(buckets_keys.front().size(), 10);
+    std::unordered_set<std::string> unique_keys(buckets_keys.front().begin(),
+                                                buckets_keys.front().end());
+    EXPECT_EQ(unique_keys.size(), 10);
+    EXPECT_EQ(GetUngroupedOffloadingObjectsSize(fileStorage), 0);
+}
+
 TEST_F(FileStorageTest, GroupOffloadingKeysByBucket_bucket_size_limit) {
     std::unordered_map<std::string, int64_t> offloading_objects;
     for (size_t i = 0; i < 35; i++) {
@@ -285,6 +713,9 @@ TEST_F(FileStorageTest, GroupOffloadingKeysByBucket_bucket_size_limit) {
         ASSERT_EQ(bucket_keys.size(), 10);
     }
     ASSERT_EQ(GetUngroupedOffloadingObjectsSize(fileStorage), 5);
+    for (size_t i = 35; i < 40; ++i) {
+        offloading_objects.emplace("test" + std::to_string(i), 1);
+    }
     buckets_keys.clear();
     ASSERT_TRUE(FileStorageGroupOffloadingKeysByBucket(
         fileStorage, offloading_objects, buckets_keys));
@@ -344,75 +775,6 @@ TEST_F(FileStorageTest,
         fileStorage, offloading_objects, buckets_keys));
 }
 
-TEST_F(FileStorageTest, DefaultValuesWhenNoEnvSet) {
-    auto config = FileStorageConfig::FromEnvironment();
-    auto bucket_backend_config = BucketBackendConfig::FromEnvironment();
-
-    EXPECT_EQ(config.storage_filepath, "/data/file_storage");
-    EXPECT_EQ(config.local_buffer_size, 1280 * 1024 * 1024);
-    EXPECT_EQ(config.scanmeta_iterator_keys_limit, 20000);
-    EXPECT_EQ(bucket_backend_config.bucket_keys_limit, 500);
-    EXPECT_EQ(bucket_backend_config.bucket_size_limit, 256 * 1024 * 1024);
-    EXPECT_EQ(config.total_keys_limit, 10'000'000);
-    EXPECT_EQ(config.total_size_limit, 2ULL * 1024 * 1024 * 1024 * 1024);
-    EXPECT_EQ(config.heartbeat_interval_seconds, 10u);
-    EXPECT_TRUE(config.enable_disk_watermark_eviction);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.90);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.80);
-}
-
-TEST_F(FileStorageTest, ReadStringFromEnv) {
-    SetEnv("MOONCAKE_OFFLOAD_FILE_STORAGE_PATH", "/tmp/storage");
-
-    auto config = FileStorageConfig::FromEnvironment();
-    EXPECT_EQ(config.storage_filepath, "/tmp/storage");
-}
-
-TEST_F(FileStorageTest, ReadInt64FromEnv) {
-    SetEnv("MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES", "2147483648");  // 2GB
-    SetEnv("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", "1000");
-    SetEnv("MOONCAKE_OFFLOAD_TOTAL_KEYS_LIMIT", "5000000");
-
-    auto config = FileStorageConfig::FromEnvironment();
-    auto bucket_backend_config = BucketBackendConfig::FromEnvironment();
-
-    EXPECT_EQ(config.local_buffer_size, 2147483648);
-    EXPECT_EQ(bucket_backend_config.bucket_keys_limit, 1000);
-    EXPECT_EQ(config.total_keys_limit, 5000000);
-}
-
-TEST_F(FileStorageTest, ReadUint32FromEnv) {
-    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "5");
-
-    auto config = FileStorageConfig::FromEnvironment();
-    EXPECT_EQ(config.heartbeat_interval_seconds, 5u);
-}
-
-TEST_F(FileStorageTest, ReadDiskWatermarkConfigFromEnv) {
-    SetEnv("MOONCAKE_DISK_EVICTION_HIGH_WATERMARK_RATIO", "0.77");
-    SetEnv("MOONCAKE_DISK_EVICTION_LOW_WATERMARK_RATIO", "0.55");
-
-    auto alias_config = FileStorageConfig::FromEnvironment();
-    EXPECT_DOUBLE_EQ(alias_config.disk_eviction_high_watermark_ratio, 0.77);
-    EXPECT_DOUBLE_EQ(alias_config.disk_eviction_low_watermark_ratio, 0.55);
-
-    SetEnv("MOONCAKE_OFFLOAD_ENABLE_DISK_WATERMARK_EVICTION", "0");
-    SetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO", "0.75");
-    SetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO", "0.50");
-
-    auto config = FileStorageConfig::FromEnvironment();
-    EXPECT_FALSE(config.enable_disk_watermark_eviction);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.75);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.50);
-
-    SetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_HIGH_WATERMARK_RATIO", "0,75");
-    SetEnv("MOONCAKE_OFFLOAD_DISK_EVICTION_LOW_WATERMARK_RATIO", "nan");
-
-    auto invalid_config = FileStorageConfig::FromEnvironment();
-    EXPECT_DOUBLE_EQ(invalid_config.disk_eviction_high_watermark_ratio, 0.90);
-    EXPECT_DOUBLE_EQ(invalid_config.disk_eviction_low_watermark_ratio, 0.80);
-}
-
 TEST_F(FileStorageTest, HeartbeatRunsDiskWatermarkEvictionWithoutOffloadWork) {
     std::filesystem::path master_root =
         std::filesystem::path(data_path) / "heartbeat_master";
@@ -459,6 +821,89 @@ TEST_F(FileStorageTest, HeartbeatRunsDiskWatermarkEvictionWithoutOffloadWork) {
     AssertHeartbeatEvictsAllKeys(file_storage, expected_keys, batch_object);
 }
 
+// A drain deregisters the disk tier; the heartbeat re-mounts the segment
+// whenever the master answers SEGMENT_NOT_FOUND. These pin the interleavings
+// where the two overlap: the drain must win in every schedule.
+
+TEST_F(FileStorageTest, HeartbeatAfterDrainDoesNotRemount) {
+    std::filesystem::path master_root =
+        std::filesystem::path(data_path) / "drain_hb_master";
+    std::filesystem::create_directories(master_root);
+
+    testing::InProcMaster master;
+    auto master_config = InProcMasterConfigBuilder()
+                             .set_enable_offload(true)
+                             .set_root_fs_dir(master_root.string())
+                             .build();
+    ASSERT_TRUE(master.Start(master_config));
+
+    std::string local_rpc_addr =
+        "127.0.0.1:" + std::to_string(getFreeTcpPort());
+    auto client = Client::Create(local_rpc_addr, master.metadata_url(), "tcp",
+                                 std::nullopt, master.master_address());
+    ASSERT_TRUE(client.has_value());
+    ASSERT_TRUE(client.value()->MountLocalDiskSegment(true).has_value());
+
+    FileStorageConfig config = FileStorageConfig::FromEnvironment();
+    config.storage_backend_type = StorageBackendType::kFilePerKey;
+    config.storage_filepath = data_path + "/drain_hb";
+    config.local_buffer_size = 4 * 1024 * 1024;
+    fs::create_directories(config.storage_filepath);
+    FileStorage file_storage(config, client.value(), local_rpc_addr);
+
+    ASSERT_TRUE(file_storage.DrainLocalDiskSegment(0).has_value());
+
+    // A tick after the drain is a no-op: it must not take the
+    // SEGMENT_NOT_FOUND recovery branch and re-mount the segment.
+    ASSERT_TRUE(FileStorageHeartbeat(file_storage).has_value());
+
+    std::vector<OffloadTaskItem> offload_items;
+    auto heartbeat_rpc =
+        client.value()->OffloadObjectHeartbeat(true, offload_items);
+    ASSERT_FALSE(heartbeat_rpc.has_value());
+    EXPECT_EQ(ErrorCode::SEGMENT_NOT_FOUND, heartbeat_rpc.error());
+}
+
+TEST_F(FileStorageTest, DrainSurvivesParkedHeartbeatTick) {
+    std::filesystem::path master_root =
+        std::filesystem::path(data_path) / "drain_race_master";
+    std::filesystem::create_directories(master_root);
+
+    testing::InProcMaster master;
+    auto master_config = InProcMasterConfigBuilder()
+                             .set_enable_offload(true)
+                             .set_root_fs_dir(master_root.string())
+                             .build();
+    ASSERT_TRUE(master.Start(master_config));
+
+    std::string local_rpc_addr =
+        "127.0.0.1:" + std::to_string(getFreeTcpPort());
+    auto client = Client::Create(local_rpc_addr, master.metadata_url(), "tcp",
+                                 std::nullopt, master.master_address());
+    ASSERT_TRUE(client.has_value());
+    ASSERT_TRUE(client.value()->MountLocalDiskSegment(true).has_value());
+
+    FileStorageConfig config = FileStorageConfig::FromEnvironment();
+    config.storage_backend_type = StorageBackendType::kFilePerKey;
+    config.storage_filepath = data_path + "/drain_race";
+    config.local_buffer_size = 4 * 1024 * 1024;
+    fs::create_directories(config.storage_filepath);
+    FileStorage file_storage(config, client.value(), local_rpc_addr);
+
+    // A tick that passed its entry draining_ check is parked on
+    // offloading_mutex_ while the drain runs (see the fixture helper). It
+    // must not resume into the SEGMENT_NOT_FOUND recovery branch and
+    // re-mount the segment the drain deregistered.
+    auto drain_result = DrainWhileHeartbeatTickParked(file_storage);
+    ASSERT_TRUE(drain_result.has_value());
+
+    std::vector<OffloadTaskItem> offload_items;
+    auto heartbeat_rpc =
+        client.value()->OffloadObjectHeartbeat(true, offload_items);
+    ASSERT_FALSE(heartbeat_rpc.has_value());
+    EXPECT_EQ(ErrorCode::SEGMENT_NOT_FOUND, heartbeat_rpc.error());
+}
+
 TEST_F(FileStorageTest, NotifyEvictedDiskReplicasUsesTenantScopedKeys) {
     std::filesystem::path master_root =
         std::filesystem::path(data_path) / "tenant_notify_master";
@@ -547,99 +992,6 @@ TEST_F(FileStorageTest, DuplicateOffloadErrorIsPerBucketSoftError) {
     EXPECT_FALSE(CallIsPerBucketSoftOffloadError(ErrorCode::OK));
 }
 
-TEST_F(FileStorageTest, InvalidIntValueUsesDefault) {
-    SetEnv("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", "abc");
-    SetEnv("MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES", "sdfsdf");
-    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "-1");
-
-    auto config = FileStorageConfig::FromEnvironment();
-    auto bucket_backend_config = BucketBackendConfig::FromEnvironment();
-
-    EXPECT_EQ(bucket_backend_config.bucket_keys_limit, 500);
-    EXPECT_EQ(config.total_size_limit, 2ULL * 1024 * 1024 * 1024 * 1024);
-    EXPECT_EQ(config.heartbeat_interval_seconds, 10u);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_high_watermark_ratio, 0.90);
-    EXPECT_DOUBLE_EQ(config.disk_eviction_low_watermark_ratio, 0.80);
-}
-
-TEST_F(FileStorageTest, OutOfRangeValueUsesDefault) {
-    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS",
-           "4294967296");  // > UINT32_MAX
-    SetEnv("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "-10");  // negative
-
-    auto config = FileStorageConfig::FromEnvironment();
-    EXPECT_EQ(config.heartbeat_interval_seconds, 10u);  // fallback to default
-}
-
-TEST_F(FileStorageTest, EmptyEnvValueUsesDefault) {
-    SetEnv("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", "");  // empty string
-
-    auto config = FileStorageConfig::FromEnvironment();
-    auto bucket_backend_config = BucketBackendConfig::FromEnvironment();
-    EXPECT_EQ(bucket_backend_config.bucket_keys_limit, 500);  // fallback
-}
-
-TEST_F(FileStorageTest, ValidateSuccessWithValidConfig) {
-    FileStorageConfig config;
-    config.storage_filepath = std::filesystem::current_path().string();
-    config.total_keys_limit = 1000000;
-    config.total_size_limit = 1073741824;  // 1GB
-    config.heartbeat_interval_seconds = 5;
-
-    EXPECT_TRUE(config.Validate());
-}
-
-TEST_F(FileStorageTest, ValidateFailsOnEmptyStoragePath) {
-    FileStorageConfig config;
-    config.storage_filepath = "";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "   ";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "relative/path";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "./data";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "../data";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "/valid/../invalid";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "/path/./sub";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = "/tmp/this_directory_does_not_exist_12345";
-    EXPECT_FALSE(config.Validate());
-    config.storage_filepath = data_path;
-    EXPECT_TRUE(config.Validate());
-}
-
-TEST_F(FileStorageTest, ValidateFailsOnInvalidLimits) {
-    FileStorageConfig config;
-    config.storage_filepath = "/tmp";
-
-    config.total_keys_limit = 0;
-    EXPECT_FALSE(config.Validate());
-
-    config.total_keys_limit = 1;
-    config.total_size_limit = 0;
-    EXPECT_FALSE(config.Validate());
-
-    config.total_size_limit = 1;
-    config.heartbeat_interval_seconds = 0;
-    EXPECT_FALSE(config.Validate());
-
-    config.heartbeat_interval_seconds = 1;
-    config.disk_eviction_low_watermark_ratio = 0.9;
-    config.disk_eviction_high_watermark_ratio = 0.8;
-    EXPECT_FALSE(config.Validate());
-
-    config.disk_eviction_low_watermark_ratio = 0.0;
-    config.disk_eviction_high_watermark_ratio = 0.8;
-    EXPECT_FALSE(config.Validate());
-
-    config.disk_eviction_low_watermark_ratio = 0.8;
-    config.disk_eviction_high_watermark_ratio = 1.1;
-    EXPECT_FALSE(config.Validate());
-}
-
 TEST_F(FileStorageTest, BatchLoad_WithStorageBackendAdaptor) {
     std::vector<std::string> keys;
     std::vector<int64_t> sizes;
@@ -795,4 +1147,33 @@ TEST_F(FileStorageTest, NullSsdMetricDoesNotCrash) {
     // No crash = success. No metrics pointer, so nothing to verify.
 }
 
+// Issue #3709: a RemoveAll-style physical wipe of the SSD files while master
+// still tracks the key's LOCAL_DISK replica leaves a dangling entry. A Put
+// for the same key must not report success while storing nothing: the client
+// evicts the dangling replica and retries PutStart, so the new data is
+// actually written.
+
+TEST_F(FileStorageTest, PutAfterPhysicalWipeHealsDanglingLocalDiskReplica) {
+    // The per-key file backend reports the wiped file as OBJECT_NOT_FOUND /
+    // FILE_OPEN_FAIL, the original proof set.
+    RunPutHealWipeScenario(data_path, StorageBackendType::kFilePerKey,
+                           "_per_key");
+}
+
+TEST_F(FileStorageTest,
+       PutAfterPhysicalWipeHealsDanglingLocalDiskReplicaOnBucket) {
+    // The bucket backend's BatchLoad reports a missing key as INVALID_KEY
+    // (fanganpai's production trace in #3709); the heal must still fire.
+    RunPutHealWipeScenario(data_path, StorageBackendType::kBucket, "_bucket");
+}
+
+TEST_F(FileStorageTest,
+       BatchPutAfterPhysicalWipeHealsDanglingLocalDiskReplica) {
+    // The BatchPut twin of the scenario above: OBJECT_ALREADY_EXISTS results
+    // on the batch path must not be converted to success for keys whose
+    // backing file is gone. Two wiped keys and one fresh key go through one
+    // batch; every key must really store.
+    RunBatchPutHealWipeScenario(data_path);
+}
+
 }  // namespace mooncake
diff --git a/mooncake-store/tests/file_util_test.cpp b/mooncake-store/tests/file_util_test.cpp
index 2d76b2166e..e53eaf5ca5 100644
--- a/mooncake-store/tests/file_util_test.cpp
+++ b/mooncake-store/tests/file_util_test.cpp
@@ -7,7 +7,7 @@
 #include <string>
 #include <vector>
 
-#include "utils/file_util.h"
+#include "common/file_util.h"
 
 namespace mooncake::test {
 
diff --git a/mooncake-store/tests/fileread_worker_pool_config_test.cpp b/mooncake-store/tests/fileread_worker_pool_config_test.cpp
new file mode 100644
index 0000000000..4617ccb990
--- /dev/null
+++ b/mooncake-store/tests/fileread_worker_pool_config_test.cpp
@@ -0,0 +1,77 @@
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+#include <utility>
+
+#include "../src/config/fileread_worker_pool_config.h"
+
+namespace mooncake {
+namespace {
+
+class FilereadWorkerPoolConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging("FilereadWorkerPoolConfigTest");
+        FLAGS_logtostderr = 1;
+        if (const char* value = std::getenv("MC_FILEREAD_WORKERS")) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv("MC_FILEREAD_WORKERS"), 0);
+    }
+
+    void TearDown() override {
+        if (original_) {
+            EXPECT_EQ(setenv("MC_FILEREAD_WORKERS", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_FILEREAD_WORKERS"), 0);
+        }
+        google::ShutdownGoogleLogging();
+    }
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST_F(FilereadWorkerPoolConfigTest, DefaultsSilentlyForUnsetAndEmpty) {
+    testing::internal::CaptureStderr();
+    EXPECT_EQ(FilereadWorkerPoolConfig::FromEnvironment().worker_count, 10);
+    EXPECT_TRUE(testing::internal::GetCapturedStderr().empty());
+
+    ASSERT_EQ(setenv("MC_FILEREAD_WORKERS", "", 1), 0);
+    testing::internal::CaptureStderr();
+    EXPECT_EQ(FilereadWorkerPoolConfig::FromEnvironment().worker_count, 10);
+    EXPECT_TRUE(testing::internal::GetCapturedStderr().empty());
+}
+
+TEST_F(FilereadWorkerPoolConfigTest, ParsesTypedPositiveIntegersOnEachRead) {
+    for (const auto& [value, expected] :
+         {std::pair{"2", 2}, std::pair{"+3", 3}, std::pair{" 4 ", 4},
+          std::pair{"2147483647", 2147483647}}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MC_FILEREAD_WORKERS", value, 1), 0);
+        testing::internal::CaptureStderr();
+        EXPECT_EQ(FilereadWorkerPoolConfig::FromEnvironment().worker_count,
+                  expected);
+        EXPECT_TRUE(testing::internal::GetCapturedStderr().empty());
+    }
+}
+
+TEST_F(FilereadWorkerPoolConfigTest, InvalidValuesWarnOnceAndFallBack) {
+    for (const char* value : {"0", "-1", "abc", "3x", "2147483648"}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MC_FILEREAD_WORKERS", value, 1), 0);
+        testing::internal::CaptureStderr();
+        EXPECT_EQ(FilereadWorkerPoolConfig::FromEnvironment().worker_count, 10);
+        const auto log = testing::internal::GetCapturedStderr();
+        EXPECT_NE(
+            log.find(std::string("Invalid value for MC_FILEREAD_WORKERS: ") +
+                     value + ", using default 10"),
+            std::string::npos);
+    }
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/fileread_worker_pool_test.cpp b/mooncake-store/tests/fileread_worker_pool_test.cpp
new file mode 100644
index 0000000000..2c941f06ac
--- /dev/null
+++ b/mooncake-store/tests/fileread_worker_pool_test.cpp
@@ -0,0 +1,62 @@
+#include "transfer_task.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <memory>
+#include <optional>
+#include <string>
+
+namespace mooncake {
+
+class FilereadWorkerPoolTestPeer {
+   public:
+    static size_t WorkerCount(const FilereadWorkerPool& pool) {
+        return pool.workers_.size();
+    }
+};
+
+namespace {
+
+class ScopedFilereadWorkersEnv {
+   public:
+    explicit ScopedFilereadWorkersEnv(const char* value) {
+        if (const char* old = std::getenv("MC_FILEREAD_WORKERS")) {
+            original_ = old;
+        }
+        EXPECT_EQ(setenv("MC_FILEREAD_WORKERS", value, 1), 0);
+    }
+
+    ~ScopedFilereadWorkersEnv() {
+        if (original_) {
+            EXPECT_EQ(setenv("MC_FILEREAD_WORKERS", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_FILEREAD_WORKERS"), 0);
+        }
+    }
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST(FilereadWorkerPoolTest, AcceptsTypedTrailingWhitespaceAndCaches) {
+    google::InitGoogleLogging("FilereadWorkerPoolTest");
+    ScopedFilereadWorkersEnv env("2 ");
+    std::shared_ptr<StorageBackend> backend;
+    // Inspect only this pool: linked runtimes (e.g. Go via etcd) can create
+    // unrelated process threads asynchronously, including during destruction.
+    {
+        FilereadWorkerPool pool(backend);
+        EXPECT_EQ(FilereadWorkerPoolTestPeer::WorkerCount(pool), 2u);
+    }
+    ASSERT_EQ(setenv("MC_FILEREAD_WORKERS", "3", 1), 0);
+    {
+        FilereadWorkerPool pool(backend);
+        EXPECT_EQ(FilereadWorkerPoolTestPeer::WorkerCount(pool), 2u);
+    }
+    google::ShutdownGoogleLogging();
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/group_index_test.cpp b/mooncake-store/tests/group_index_test.cpp
new file mode 100644
index 0000000000..74bb7f4d3d
--- /dev/null
+++ b/mooncake-store/tests/group_index_test.cpp
@@ -0,0 +1,80 @@
+#include "group_index.h"
+
+#include <string>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+TEST(GroupIndexTest, AddMemberCreatesAndSharesOneLeasePerGroup) {
+    GroupIndex index;
+
+    const auto a1 = index.AddMember("g1", "k1");
+    const auto a2 = index.AddMember("g1", "k2");
+    const auto b = index.AddMember("g2", "k1");
+
+    ASSERT_NE(a1, nullptr);
+    EXPECT_EQ(a1.get(), a2.get());  // same group -> same Lease
+    EXPECT_NE(a1.get(), b.get());   // different group -> its own
+}
+
+TEST(GroupIndexTest, UngroupedMemberHasNoLease) {
+    GroupIndex index;
+
+    // An empty group_id is the ungrouped case: nothing is registered, so two
+    // ungrouped objects can never end up sharing one lease.
+    EXPECT_EQ(index.AddMember("", "k1"), nullptr);
+    EXPECT_TRUE(index.Empty());
+}
+
+TEST(GroupIndexTest, RepeatedMemberKeepsTheOneLease) {
+    GroupIndex index;
+    const auto first = index.AddMember("g1", "k1");
+    ASSERT_NE(first, nullptr);
+
+    // A repeat is not an error and does not disturb the group: the caller gets
+    // the same lease back and the membership stays single.
+    const auto again = index.AddMember("g1", "k1");
+    EXPECT_EQ(first.get(), again.get());
+    EXPECT_EQ(index.Members("g1").size(), 1u);
+}
+
+TEST(GroupIndexTest, AddRemoveGroupMembers) {
+    GroupIndex index;
+
+    EXPECT_NE(index.AddMember("g1", "k1"), nullptr);
+    EXPECT_NE(index.AddMember("g1", "k2"), nullptr);
+    EXPECT_FALSE(index.Empty());
+
+    auto members = index.Members("g1");
+    EXPECT_EQ(members.size(), 2u);
+
+    EXPECT_TRUE(index.RemoveMember("g1", "k1"));
+    auto after = index.Members("g1");
+    ASSERT_EQ(after.size(), 1u);
+    EXPECT_EQ(after[0], "k2");
+
+    EXPECT_TRUE(index.RemoveMember("g1", "k2"));
+    EXPECT_FALSE(index.RemoveMember("g1", "k2"));  // already gone
+    EXPECT_TRUE(index.Empty());
+}
+
+TEST(GroupIndexTest, EmptyGroupIsDroppedOnLastMemberRemoved) {
+    GroupIndex index;
+    const auto before = index.AddMember("g1", "k1");
+    ASSERT_NE(before, nullptr);
+
+    EXPECT_TRUE(index.RemoveMember("g1", "k1"));
+    EXPECT_TRUE(index.Members("g1").empty());
+    EXPECT_TRUE(index.Empty());
+
+    // The dropped group is not revived: the re-add materializes a fresh group
+    // with a new Lease.
+    const auto after = index.AddMember("g1", "k1");
+    ASSERT_NE(after, nullptr);
+    EXPECT_NE(before.get(), after.get());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/ha/leadership/high_availability_test.cpp b/mooncake-store/tests/ha/leadership/high_availability_test.cpp
index dbd2c5fe97..2a1625aa5e 100644
--- a/mooncake-store/tests/ha/leadership/high_availability_test.cpp
+++ b/mooncake-store/tests/ha/leadership/high_availability_test.cpp
@@ -1,8 +1,13 @@
+#include <sys/wait.h>
+#include <unistd.h>
+
 #include <gflags/gflags.h>
 #include <glog/logging.h>
+#include <ylt/coro_http/coro_http_client.hpp>
 
 #include <atomic>
 #include <chrono>
+#include <csignal>
 #include <future>
 #include <mutex>
 #include <optional>
@@ -12,8 +17,11 @@
 #ifdef STORE_USE_ETCD
 #include "etcd_helper.h"
 #endif
+#include "common/network.h"
 #include "ha/leadership/leader_coordinator_factory.h"
 #include "ha/leadership/high_availability_test_fixture.h"
+#include "ha/leadership/master_service_supervisor.h"
+#include "master_service.h"
 #include "types.h"
 
 namespace mooncake {
@@ -22,6 +30,11 @@ namespace testing {
 DEFINE_string(etcd_endpoints, "127.0.0.1:2379", "Etcd endpoints");
 DEFINE_string(etcd_test_key_prefix, "mooncake-store/test/",
               "The prefix of the test keys in ETCD");
+DEFINE_bool(ha_supervisor_child, false,
+            "Run a real HA supervisor for the parent integration test");
+DEFINE_int32(ha_supervisor_rpc_port, 0, "Child supervisor RPC port");
+DEFINE_int32(ha_supervisor_admin_port, 0, "Child supervisor admin port");
+DEFINE_string(ha_supervisor_cluster_id, "", "Child supervisor cluster ID");
 
 void HighAvailabilityTest::SetUpTestSuite() {
     // Initialize glog
@@ -95,10 +108,360 @@ std::unique_ptr<ha::LeaderCoordinator> CreateEtcdCoordinatorOrNull(
     return std::move(coordinator.value());
 }
 
+class FakeLeaderCoordinator : public ha::LeaderCoordinator {
+   public:
+    explicit FakeLeaderCoordinator(ViewVersionId view_version)
+        : session_{.view = {.leader_address = "fake-leader",
+                            .view_version = view_version},
+                   .owner_token = "fake-owner",
+                   .lease_ttl = std::chrono::milliseconds(0)} {}
+
+    tl::expected<std::optional<ha::MasterView>, ErrorCode> ReadCurrentView()
+        override {
+        return current_view_;
+    }
+
+    tl::expected<ha::AcquireLeadershipResult, ErrorCode> TryAcquireLeadership(
+        const std::string& /*leader_address*/) override {
+        return ha::AcquireLeadershipResult{
+            .status = ha::AcquireLeadershipStatus::ACQUIRED,
+            .session = session_,
+            .observed_view = std::nullopt,
+        };
+    }
+
+    tl::expected<bool, ErrorCode> RenewLeadership(
+        const ha::LeadershipSession& /*session*/) override {
+        return true;
+    }
+
+    tl::expected<ha::ViewChangeResult, ErrorCode> WaitForViewChange(
+        std::optional<ViewVersionId> /*known_version*/,
+        std::chrono::milliseconds timeout) override {
+        ++wait_calls_;
+        last_wait_timeout_ = timeout;
+        return wait_result_;
+    }
+
+    tl::expected<std::unique_ptr<ha::LeadershipMonitorHandle>, ErrorCode>
+    StartLeadershipMonitor(
+        const ha::LeadershipSession& /*session*/,
+        ha::LeadershipLostCallback /*on_leadership_lost*/) override {
+        return tl::make_unexpected(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+
+    ErrorCode ReleaseLeadership(
+        const ha::LeadershipSession& /*session*/) override {
+        return ErrorCode::OK;
+    }
+
+    void SetCurrentView(std::optional<ha::MasterView> view) {
+        current_view_ = std::move(view);
+    }
+
+    void SetWaitResult(ha::ViewChangeResult result) {
+        wait_result_ = std::move(result);
+    }
+
+    size_t wait_calls() const { return wait_calls_; }
+    std::chrono::milliseconds last_wait_timeout() const {
+        return last_wait_timeout_;
+    }
+
+   private:
+    ha::LeadershipSession session_;
+    std::optional<ha::MasterView> current_view_;
+    ha::ViewChangeResult wait_result_;
+    size_t wait_calls_{0};
+    std::chrono::milliseconds last_wait_timeout_{0};
+};
+
+class SupervisorChildProcess {
+   public:
+    SupervisorChildProcess(int rpc_port, int admin_port, std::string cluster_id)
+        : rpc_port_(rpc_port),
+          admin_port_(admin_port),
+          cluster_id_(std::move(cluster_id)) {}
+
+    ~SupervisorChildProcess() { Stop(); }
+
+    bool Start() {
+        pid_ = fork();
+        if (pid_ != 0) {
+            return pid_ > 0;
+        }
+
+        const std::string endpoints_arg =
+            "--etcd_endpoints=" + FLAGS_etcd_endpoints;
+        const std::string rpc_port_arg =
+            "--ha_supervisor_rpc_port=" + std::to_string(rpc_port_);
+        const std::string admin_port_arg =
+            "--ha_supervisor_admin_port=" + std::to_string(admin_port_);
+        const std::string cluster_arg =
+            "--ha_supervisor_cluster_id=" + cluster_id_;
+        execl("/proc/self/exe", "/proc/self/exe", "--ha_supervisor_child=true",
+              endpoints_arg.c_str(), rpc_port_arg.c_str(),
+              admin_port_arg.c_str(), cluster_arg.c_str(), nullptr);
+        _exit(127);
+    }
+
+    bool IsRunning() {
+        if (pid_ <= 0) {
+            return false;
+        }
+        int status = 0;
+        if (waitpid(pid_, &status, WNOHANG) == 0) {
+            return true;
+        }
+        pid_ = 0;
+        return false;
+    }
+
+    void Stop() {
+        if (pid_ <= 0) {
+            return;
+        }
+        kill(pid_, SIGKILL);
+        waitpid(pid_, nullptr, 0);
+        pid_ = 0;
+    }
+
+   private:
+    pid_t pid_{0};
+    int rpc_port_;
+    int admin_port_;
+    std::string cluster_id_;
+};
+
+struct HttpResponse {
+    int status;
+    std::string body;
+};
+
+HttpResponse HttpGet(int port, const std::string& path) {
+    coro_http::coro_http_client client;
+    auto result = client.get("http://127.0.0.1:" + std::to_string(port) + path);
+    return {.status = result.status, .body = std::string(result.resp_body)};
+}
+
+bool WaitForServing(SupervisorChildProcess& child, int admin_port,
+                    std::chrono::seconds timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline && child.IsRunning()) {
+        const auto health = HttpGet(admin_port, "/health");
+        if (health.status == 200 &&
+            health.body.find("\"ha_state\":\"serving\"") != std::string::npos &&
+            health.body.find("\"service_ready\":true") != std::string::npos) {
+            return true;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    }
+    return false;
+}
+
 }  // namespace
 
+int RunSupervisorChild() {
+    MasterServiceSupervisorConfig config;
+    config.enable_metric_reporting = false;
+    config.metrics_port = FLAGS_ha_supervisor_admin_port;
+    config.metrics_host = "127.0.0.1";
+    config.default_kv_lease_ttl = DEFAULT_DEFAULT_KV_LEASE_TTL;
+    config.default_kv_soft_pin_ttl = DEFAULT_KV_SOFT_PIN_TTL_MS;
+    config.allow_evict_soft_pinned_objects = true;
+    config.eviction_ratio = DEFAULT_EVICTION_RATIO;
+    config.eviction_high_watermark_ratio =
+        DEFAULT_EVICTION_HIGH_WATERMARK_RATIO;
+    config.nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
+    config.nof_eviction_high_watermark_ratio =
+        DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
+    config.client_active_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    config.client_suspicion_ttl_sec = DEFAULT_CLIENT_SUSPICION_TTL_SEC;
+    config.nof_heartbeat_interval_sec = DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
+    config.nof_heartbeat_probe_timeout_ms =
+        DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS;
+    config.nof_heartbeat_failures_threshold =
+        DEFAULT_NOF_HEARTBEAT_FAILURES_THRESHOLD;
+    config.enable_offload = false;
+    config.rpc_address = "127.0.0.1";
+    config.rpc_port = FLAGS_ha_supervisor_rpc_port;
+    config.rpc_thread_num = 1;
+    config.local_hostname =
+        config.rpc_address + ":" + std::to_string(FLAGS_ha_supervisor_rpc_port);
+    config.ha_backend_type = "etcd";
+    config.ha_backend_connstring = FLAGS_etcd_endpoints;
+    config.etcd_endpoints = FLAGS_etcd_endpoints;
+    config.cluster_id = FLAGS_ha_supervisor_cluster_id;
+    config.enable_oplog = false;
+
+    ha::MasterServiceSupervisor supervisor(config);
+    return supervisor.Start();
+}
+
+TEST_F(HighAvailabilityTest, AcquiredViewFlowsIntoServingMasterService) {
+    constexpr ViewVersionId kAcquiredView = 42;
+    FakeLeaderCoordinator coordinator(kAcquiredView);
+    auto acquired = coordinator.TryAcquireLeadership("primary");
+    ASSERT_TRUE(acquired.has_value());
+    ASSERT_TRUE(acquired->session.has_value());
+
+    MasterServiceSupervisorConfig supervisor_config;
+    supervisor_config.default_kv_lease_ttl = DEFAULT_DEFAULT_KV_LEASE_TTL;
+    supervisor_config.default_kv_soft_pin_ttl = DEFAULT_KV_SOFT_PIN_TTL_MS;
+    supervisor_config.allow_evict_soft_pinned_objects = true;
+    supervisor_config.enable_metric_reporting = false;
+    supervisor_config.metrics_port = 0;
+    supervisor_config.eviction_ratio = DEFAULT_EVICTION_RATIO;
+    supervisor_config.eviction_high_watermark_ratio =
+        DEFAULT_EVICTION_HIGH_WATERMARK_RATIO;
+    supervisor_config.nof_eviction_ratio = DEFAULT_NOF_EVICTION_RATIO;
+    supervisor_config.nof_eviction_high_watermark_ratio =
+        DEFAULT_NOF_EVICTION_HIGH_WATERMARK_RATIO;
+    supervisor_config.client_active_ttl_sec = DEFAULT_CLIENT_LIVE_TTL_SEC;
+    supervisor_config.client_suspicion_ttl_sec =
+        DEFAULT_CLIENT_SUSPICION_TTL_SEC;
+    supervisor_config.nof_heartbeat_interval_sec =
+        DEFAULT_NOF_HEARTBEAT_INTERVAL_SEC;
+    supervisor_config.nof_heartbeat_probe_timeout_ms =
+        DEFAULT_NOF_HEARTBEAT_PROBE_TIMEOUT_MS;
+    supervisor_config.nof_heartbeat_failures_threshold =
+        DEFAULT_NOF_HEARTBEAT_FAILURES_THRESHOLD;
+    supervisor_config.enable_offload = false;
+
+    WrappedMasterServiceConfig serving_config(
+        supervisor_config, acquired->session->view.view_version);
+    MasterService service{MasterServiceConfig(serving_config)};
+
+    auto ping = service.Ping(generate_uuid());
+    ASSERT_TRUE(ping.has_value());
+    EXPECT_EQ(kAcquiredView, ping->view_version_id);
+}
+
+TEST_F(HighAvailabilityTest, InitialDiscoveryWaitsForReadyView) {
+    FakeLeaderCoordinator coordinator(/*view_version=*/42);
+    const ha::MasterView ready_view{
+        .leader_address = "ready-leader",
+        .view_version = 43,
+    };
+    coordinator.SetWaitResult(ha::ViewChangeResult{
+        .changed = true,
+        .timed_out = false,
+        .current_view = ready_view,
+    });
+
+    constexpr auto kTimeout = std::chrono::milliseconds(1234);
+    auto result = ha::ReadCurrentViewOrWaitForReady(coordinator, kTimeout);
+
+    ASSERT_TRUE(result.has_value());
+    ASSERT_TRUE(result->has_value());
+    EXPECT_EQ(result->value().leader_address, ready_view.leader_address);
+    EXPECT_EQ(result->value().view_version, ready_view.view_version);
+    EXPECT_EQ(coordinator.wait_calls(), 1u);
+    EXPECT_EQ(coordinator.last_wait_timeout(), kTimeout);
+}
+
+TEST_F(HighAvailabilityTest, InitialDiscoveryReturnsEmptyAfterTimeout) {
+    FakeLeaderCoordinator coordinator(/*view_version=*/42);
+    coordinator.SetWaitResult(ha::ViewChangeResult{
+        .changed = false,
+        .timed_out = true,
+        .current_view = std::nullopt,
+    });
+
+    auto result = ha::ReadCurrentViewOrWaitForReady(
+        coordinator, std::chrono::milliseconds(25));
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_FALSE(result->has_value());
+    EXPECT_EQ(coordinator.wait_calls(), 1u);
+}
+
+TEST_F(HighAvailabilityTest, ServingStateLossDoesNotWaitForPublication) {
+    ha::detail::ServingStateGate serving_state;
+    std::promise<void> publication_started;
+    std::promise<void> finish_publication;
+    auto finish_publication_future = finish_publication.get_future();
+    std::atomic<bool> activated{false};
+    std::atomic<bool> stopped{false};
+
+    auto publication = std::async(std::launch::async, [&]() {
+        publication_started.set_value();
+        finish_publication_future.wait();
+        return serving_state.RunIfActive(
+            [&]() { activated.store(true, std::memory_order_release); });
+    });
+    publication_started.get_future().wait();
+
+    auto leadership_loss = std::async(std::launch::async, [&]() {
+        serving_state.RequestShutdown(
+            [&]() { stopped.store(true, std::memory_order_release); });
+    });
+
+    EXPECT_EQ(leadership_loss.wait_for(std::chrono::milliseconds(500)),
+              std::future_status::ready);
+    EXPECT_TRUE(stopped.load(std::memory_order_acquire));
+
+    finish_publication.set_value();
+    EXPECT_FALSE(publication.get());
+    leadership_loss.get();
+    EXPECT_FALSE(activated.load(std::memory_order_acquire));
+}
+
+TEST_F(HighAvailabilityTest, ServingStateSerializesActivationAndLoss) {
+    ha::detail::ServingStateGate serving_state;
+    std::promise<void> activation_started;
+    std::promise<void> finish_activation;
+    auto finish_activation_future = finish_activation.get_future();
+    std::promise<void> shutdown_started;
+    std::atomic<bool> activated{false};
+    std::atomic<bool> stopped{false};
+
+    auto activation = std::async(std::launch::async, [&]() {
+        return serving_state.RunIfActive([&]() {
+            activation_started.set_value();
+            finish_activation_future.wait();
+            activated.store(true, std::memory_order_release);
+        });
+    });
+    activation_started.get_future().wait();
+
+    auto leadership_loss = std::async(std::launch::async, [&]() {
+        shutdown_started.set_value();
+        return serving_state.RequestShutdown(
+            [&]() { stopped.store(true, std::memory_order_release); });
+    });
+    shutdown_started.get_future().wait();
+
+    EXPECT_EQ(leadership_loss.wait_for(std::chrono::milliseconds(100)),
+              std::future_status::timeout);
+    EXPECT_TRUE(serving_state.IsActive());
+
+    finish_activation.set_value();
+    EXPECT_TRUE(activation.get());
+    EXPECT_TRUE(leadership_loss.get());
+    EXPECT_TRUE(activated.load(std::memory_order_acquire));
+    EXPECT_TRUE(stopped.load(std::memory_order_acquire));
+    EXPECT_FALSE(serving_state.IsActive());
+}
+
 #ifdef STORE_USE_ETCD
 
+TEST_F(HighAvailabilityTest, HaWithoutOplogRestoresEmptyContextAndServes) {
+    if (auto skip_reason = GetEtcdSkipReason(); skip_reason.has_value()) {
+        GTEST_SKIP() << *skip_reason;
+    }
+
+    const auto ports = getFreeTcpPorts(2);
+    ASSERT_EQ(ports.size(), 2);
+    const std::string cluster_id =
+        "ha-without-oplog-supervisor-" + std::to_string(getpid());
+    SupervisorChildProcess child(ports[0], ports[1], cluster_id);
+    ASSERT_TRUE(child.Start());
+    ASSERT_TRUE(WaitForServing(child, ports[1], std::chrono::seconds(20)));
+
+    EXPECT_EQ(HttpGet(ports[1], "/get_all_keys").status, 200);
+}
+
 TEST_F(HighAvailabilityTest, EtcdBasicOperations) {
     if (auto skip_reason = GetEtcdSkipReason(); skip_reason.has_value()) {
         GTEST_SKIP() << *skip_reason;
@@ -274,7 +637,46 @@ TEST_F(HighAvailabilityTest, BasicMasterViewOperations) {
     ASSERT_TRUE(renew.has_value());
     ASSERT_TRUE(renew.value());
 
-    // Check the master view is correctly set
+    // The ownership reservation must block both upgraded and legacy
+    // candidates while the service endpoint is still hidden.
+    auto contender = CreateEtcdCoordinatorOrNull(FLAGS_etcd_endpoints);
+    ASSERT_NE(contender, nullptr);
+    auto contended = contender->TryAcquireLeadership("other-master:8888");
+    ASSERT_TRUE(contended.has_value());
+    ASSERT_EQ(ha::AcquireLeadershipStatus::CONTENDED, contended->status);
+    ASSERT_FALSE(contended->observed_view.has_value());
+
+#ifdef STORE_USE_ETCD
+    EtcdLeaseId legacy_lease = 0;
+    ASSERT_EQ(ErrorCode::OK,
+              EtcdHelper::GrantLease(DEFAULT_MASTER_VIEW_LEASE_TTL_SEC,
+                                     legacy_lease));
+    EtcdRevisionId legacy_revision = 0;
+    const std::string master_view_key =
+        "mooncake-store/mooncake_cluster/master_view";
+    const std::string legacy_address = "legacy-master:8888";
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              EtcdHelper::CreateWithLease(
+                  master_view_key.c_str(), master_view_key.size(),
+                  legacy_address.c_str(), legacy_address.size(), legacy_lease,
+                  legacy_revision));
+    ASSERT_EQ(ErrorCode::OK, EtcdHelper::RevokeLease(legacy_lease));
+#endif
+
+    // The lease-bound placeholder is not exposed as a routable master view.
+    current_view = coordinator->ReadCurrentView();
+    ASSERT_TRUE(current_view.has_value());
+    ASSERT_FALSE(current_view.value().has_value());
+
+    auto stale_session = session;
+    stale_session.owner_token = "stale-owner";
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              coordinator->PublishServiceReady(stale_session));
+
+    ASSERT_EQ(ErrorCode::OK, coordinator->PublishServiceReady(session));
+    EXPECT_EQ(ErrorCode::OK, coordinator->PublishServiceReady(session));
+
+    // Check the master view is published after readiness.
     current_view = coordinator->ReadCurrentView();
     ASSERT_TRUE(current_view.has_value());
     ASSERT_TRUE(current_view.value().has_value());
@@ -340,6 +742,8 @@ TEST_F(HighAvailabilityTest, WaitForViewChangeReturnsPromptlyOnLeaderLoss) {
     ASSERT_TRUE(renew.has_value());
     ASSERT_TRUE(renew.value());
 
+    ASSERT_EQ(ErrorCode::OK, coordinator->PublishServiceReady(session));
+
     // Release leadership from another thread after a short delay; this revokes
     // the lease and deletes the master_view key, which the watch observes.
     std::thread releaser([&]() {
@@ -382,6 +786,8 @@ TEST_F(HighAvailabilityTest, WaitForViewChangeTimesOutWhenStable) {
     ASSERT_TRUE(renew.has_value());
     ASSERT_TRUE(renew.value());
 
+    ASSERT_EQ(ErrorCode::OK, coordinator->PublishServiceReady(session));
+
     const auto timeout = std::chrono::milliseconds(500);
     const auto start = std::chrono::steady_clock::now();
     auto result =
@@ -418,6 +824,8 @@ TEST_F(HighAvailabilityTest, WaitForViewChangeReturnsCurrentViewImmediately) {
     ASSERT_TRUE(acquire->session.has_value());
     const auto session = *acquire->session;
 
+    ASSERT_EQ(ErrorCode::OK, coordinator->PublishServiceReady(session));
+
     const auto start = std::chrono::steady_clock::now();
     auto result =
         coordinator->WaitForViewChange(std::nullopt, std::chrono::seconds(5));
@@ -432,6 +840,44 @@ TEST_F(HighAvailabilityTest, WaitForViewChangeReturnsCurrentViewImmediately) {
     ASSERT_EQ(ErrorCode::OK, coordinator->ReleaseLeadership(session));
 }
 
+TEST_F(HighAvailabilityTest, WaitForViewChangeObservesWarmingLeaderReady) {
+    if (auto skip_reason = GetEtcdSkipReason(); skip_reason.has_value()) {
+        GTEST_SKIP() << *skip_reason;
+    }
+
+    auto coordinator = CreateEtcdCoordinatorOrNull(FLAGS_etcd_endpoints);
+    ASSERT_NE(coordinator, nullptr);
+
+    auto acquire = coordinator->TryAcquireLeadership("0.0.0.0:2222");
+    ASSERT_TRUE(acquire.has_value());
+    ASSERT_EQ(ha::AcquireLeadershipStatus::ACQUIRED, acquire->status);
+    ASSERT_TRUE(acquire->session.has_value());
+    const auto session = *acquire->session;
+
+    auto warming_view = coordinator->ReadCurrentView();
+    ASSERT_TRUE(warming_view.has_value());
+    ASSERT_FALSE(warming_view->has_value());
+
+    auto publisher = std::async(std::launch::async, [&]() {
+        std::this_thread::sleep_for(std::chrono::milliseconds(300));
+        return coordinator->PublishServiceReady(session);
+    });
+
+    auto ready_view =
+        coordinator->WaitForViewChange(std::nullopt, std::chrono::seconds(5));
+    EXPECT_EQ(ErrorCode::OK, publisher.get());
+
+    ASSERT_TRUE(ready_view.has_value());
+    EXPECT_TRUE(ready_view->changed);
+    ASSERT_TRUE(ready_view->current_view.has_value());
+    EXPECT_EQ(ready_view->current_view->leader_address,
+              session.view.leader_address);
+    EXPECT_EQ(ready_view->current_view->view_version,
+              session.view.view_version);
+
+    ASSERT_EQ(ErrorCode::OK, coordinator->ReleaseLeadership(session));
+}
+
 TEST_F(HighAvailabilityTest, LeadershipMonitorReportsKeepAliveLoss) {
     if (auto skip_reason = GetEtcdSkipReason(); skip_reason.has_value()) {
         GTEST_SKIP() << *skip_reason;
@@ -458,6 +904,11 @@ TEST_F(HighAvailabilityTest, LeadershipMonitorReportsKeepAliveLoss) {
         });
     ASSERT_TRUE(monitor.has_value());
 
+    ASSERT_EQ(ErrorCode::OK,
+              EtcdHelper::ResetEtcdStoreClient(FLAGS_etcd_endpoints));
+    EXPECT_EQ(loss_future.wait_for(std::chrono::seconds(1)),
+              std::future_status::timeout);
+
     const auto lease_id =
         static_cast<EtcdLeaseId>(std::stoll(session.owner_token));
     ASSERT_EQ(ErrorCode::OK, EtcdHelper::CancelKeepAlive(lease_id));
@@ -504,7 +955,7 @@ TEST_F(HighAvailabilityTest, EtcdStoreClientResetKeepsBasicOperationsWorking) {
     ASSERT_EQ(ErrorCode::OK, EtcdHelper::RevokeLease(lease_id));
 }
 
-TEST_F(HighAvailabilityTest, EtcdStoreClientResetStopsOldKeepAlive) {
+TEST_F(HighAvailabilityTest, EtcdStoreClientResetKeepsOldKeepAlive) {
     if (auto skip_reason = GetEtcdSkipReason(); skip_reason.has_value()) {
         GTEST_SKIP() << *skip_reason;
     }
@@ -536,12 +987,20 @@ TEST_F(HighAvailabilityTest, EtcdStoreClientResetStopsOldKeepAlive) {
     }
     ASSERT_EQ(ErrorCode::OK, reset_err);
 
-    auto keep_alive_status = future.wait_for(std::chrono::seconds(5));
-    if (keep_alive_status != std::future_status::ready) {
+    auto keep_alive_status = future.wait_for(std::chrono::seconds(1));
+    if (keep_alive_status != std::future_status::timeout) {
+        keep_alive_thread.join();
+    }
+    ASSERT_EQ(keep_alive_status, std::future_status::timeout);
+
+    auto cancel_err = EtcdHelper::CancelKeepAlive(lease_id);
+    if (cancel_err != ErrorCode::OK) {
         cleanup_keep_alive();
     }
-    ASSERT_EQ(keep_alive_status, std::future_status::ready);
-    EXPECT_NE(ErrorCode::OK, future.get());
+    ASSERT_EQ(ErrorCode::OK, cancel_err);
+    ASSERT_EQ(future.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    EXPECT_EQ(ErrorCode::ETCD_CTX_CANCELLED, future.get());
     keep_alive_thread.join();
 
     EtcdLeaseId new_lease_id = 0;
@@ -822,6 +1281,12 @@ int main(int argc, char** argv) {
     // Initialize Google's flags library
     gflags::ParseCommandLineFlags(&argc, &argv, true);
 
+    if (mooncake::testing::FLAGS_ha_supervisor_child) {
+        google::InitGoogleLogging("HighAvailabilitySupervisorChild");
+        FLAGS_logtostderr = 1;
+        return mooncake::testing::RunSupervisorChild();
+    }
+
     // Initialize Google Test
     ::testing::InitGoogleTest(&argc, argv);
 
diff --git a/mooncake-store/tests/ha/master_service_ha_test.cpp b/mooncake-store/tests/ha/master_service_ha_test.cpp
index a898480109..a65f56b45b 100644
--- a/mooncake-store/tests/ha/master_service_ha_test.cpp
+++ b/mooncake-store/tests/ha/master_service_ha_test.cpp
@@ -1,13 +1,17 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <algorithm>
+#include <atomic>
 #include <chrono>
 #include <condition_variable>
 #include <filesystem>
 #include <fstream>
 #include <future>
+#include <limits>
 #include <map>
 #include <memory>
 #include <mutex>
@@ -34,6 +38,10 @@ namespace mooncake::test {
 
 class FakeBatchHaKvBackend : public HaKvBackend {
    public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
     ErrorCode Get(std::string_view key, std::string& value) override {
         auto it = kvs_.find(std::string(key));
         if (it == kvs_.end()) {
@@ -149,8 +157,137 @@ class FailingBatchHaKvBackend : public FakeBatchHaKvBackend {
     size_t txn_calls_{0};
 };
 
+class GatedOrderedOpLogWriter : public OrderedOpLogWriter {
+   public:
+    GatedOrderedOpLogWriter(OrderedOpLogWriterConfig config,
+                            WriteBatchFn write_batch)
+        : OrderedOpLogWriter(std::move(config), std::move(write_batch)) {}
+
+    ~GatedOrderedOpLogWriter() override { Stop(); }
+
+    tl::expected<PendingHandle, ErrorCode> Commit(
+        Reservation&& reservation, OpLogEntry entry,
+        DurableCallback callback) override {
+        return OrderedOpLogWriter::Commit(
+            std::move(reservation), std::move(entry),
+            [this, callback = std::move(callback)](const OpLogEntry& durable) {
+                {
+                    std::unique_lock<std::mutex> lock(mutex_);
+                    cv_.wait(lock, [&] {
+                        return stopping_ ||
+                               durable.sequence_id <= released_through_;
+                    });
+                }
+                if (callback) {
+                    callback(durable);
+                }
+                {
+                    std::lock_guard<std::mutex> lock(mutex_);
+                    completed_through_ = durable.sequence_id;
+                }
+                cv_.notify_all();
+            });
+    }
+
+    bool PauseCallbacksAfter(
+        uint64_t sequence_id,
+        std::chrono::milliseconds timeout = std::chrono::seconds(1)) {
+        std::unique_lock<std::mutex> lock(mutex_);
+        released_through_ = sequence_id;
+        return cv_.wait_for(lock, timeout,
+                            [&] { return completed_through_ >= sequence_id; });
+    }
+
+    bool RunCallbacksThrough(
+        uint64_t sequence_id,
+        std::chrono::milliseconds timeout = std::chrono::seconds(1)) {
+        std::unique_lock<std::mutex> lock(mutex_);
+        released_through_ = std::max(released_through_, sequence_id);
+        cv_.notify_all();
+        return cv_.wait_for(lock, timeout,
+                            [&] { return completed_through_ >= sequence_id; });
+    }
+
+    void Stop() override {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            stopping_ = true;
+        }
+        cv_.notify_all();
+        OrderedOpLogWriter::Stop();
+    }
+
+   private:
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    uint64_t released_through_{UINT64_MAX};
+    uint64_t completed_through_{0};
+    bool stopping_{false};
+};
+
+class RejectingOrderedOpLogWriter : public OrderedOpLogWriter {
+   public:
+    RejectingOrderedOpLogWriter(OrderedOpLogWriterConfig config,
+                                WriteBatchFn write_batch)
+        : OrderedOpLogWriter(std::move(config), std::move(write_batch)) {}
+
+    tl::expected<PendingHandle, ErrorCode> Commit(
+        Reservation&& reservation, OpLogEntry entry,
+        DurableCallback callback) override {
+        if (commit_error_ != ErrorCode::OK) {
+            ++rejected_commits_;
+            return tl::make_unexpected(commit_error_);
+        }
+        return OrderedOpLogWriter::Commit(
+            std::move(reservation), std::move(entry), std::move(callback));
+    }
+
+    void RejectCommitsWith(ErrorCode error) { commit_error_ = error; }
+
+    size_t rejected_commits() const { return rejected_commits_; }
+
+   private:
+    ErrorCode commit_error_{ErrorCode::OK};
+    size_t rejected_commits_{0};
+};
+
+class RejectOnceOrderedOpLogWriter : public OrderedOpLogWriter {
+   public:
+    RejectOnceOrderedOpLogWriter(OrderedOpLogWriterConfig config,
+                                 WriteBatchFn write_batch)
+        : OrderedOpLogWriter(std::move(config), std::move(write_batch)) {}
+
+    void RejectNextCommit() { reject_next_.store(true); }
+
+    void RejectNextSegmentUnmount() {
+        reject_next_segment_unmount_.store(true);
+    }
+
+    tl::expected<PendingHandle, ErrorCode> Commit(
+        Reservation&& reservation, OpLogEntry entry,
+        DurableCallback callback) override {
+        if (reject_next_.exchange(false)) {
+            return tl::make_unexpected(ErrorCode::PERSISTENT_FAIL);
+        }
+        if (entry.op_type == OpType::SEGMENT_UNMOUNT &&
+            reject_next_segment_unmount_.exchange(false)) {
+            return tl::make_unexpected(ErrorCode::PERSISTENT_FAIL);
+        }
+        return OrderedOpLogWriter::Commit(
+            std::move(reservation), std::move(entry), std::move(callback));
+    }
+
+   private:
+    std::atomic<bool> reject_next_{false};
+    std::atomic<bool> reject_next_segment_unmount_{false};
+};
+
 class MasterServiceHATest : public ::testing::Test {
    protected:
+    static void EnableDfsForTesting(MasterService& service) {
+        MasterServiceTestPeer::EnableDfs(service) = true;
+    }
+
     static void SetUpTestSuite() {
         google::InitGoogleLogging("MasterServiceHATest");
         FLAGS_logtostderr = 1;
@@ -221,15 +358,23 @@ class MasterServiceHATest : public ::testing::Test {
     }
 
     static bool HasOpLogWriter(const MasterService& service) {
-        return service.ordered_oplog_writer_ != nullptr;
+        return MasterServiceTestPeer::OrderedOplogWriter(service) != nullptr;
     }
 
     static bool IsOpLogEnabled(const MasterService& service) {
-        return service.enable_oplog_;
+        return MasterServiceTestPeer::EnableOplog(service);
     }
 
     static bool HasBatchOpLogStorage(const MasterService& service) {
-        return service.batch_oplog_storage_ != nullptr;
+        return MasterServiceTestPeer::BatchOplogStorage(service) != nullptr;
+    }
+
+    static std::optional<OrderedOpLogWriterTerminalState>
+    GetWriterTerminalStateForTesting(const MasterService& service) {
+        return MasterServiceTestPeer::OrderedOplogWriter(service)
+                   ? MasterServiceTestPeer::OrderedOplogWriter(service)
+                         ->GetTerminalState()
+                   : std::nullopt;
     }
 
     Segment MakeSegment(std::string name = "test_segment",
@@ -320,6 +465,57 @@ class MasterServiceHATest : public ::testing::Test {
         ASSERT_EQ(ErrorCode::OK, read_err);
     }
 
+    static GatedOrderedOpLogWriter* InstallGatedWriter(
+        MasterService& service, std::shared_ptr<HaKvBackend> backend) {
+        MasterServiceTestPeer(service).SetBatchOpLogWriterFactoryForTesting(
+            [](OrderedOpLogWriterConfig config,
+               OrderedOpLogWriter::WriteBatchFn write_batch) {
+                return std::make_unique<GatedOrderedOpLogWriter>(
+                    std::move(config), std::move(write_batch));
+            });
+        EXPECT_EQ(ErrorCode::OK,
+                  MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(
+                      std::move(backend)));
+        return static_cast<GatedOrderedOpLogWriter*>(
+            MasterServiceTestPeer::OrderedOplogWriter(service).get());
+    }
+
+    static RejectingOrderedOpLogWriter* InstallRejectingWriter(
+        MasterService& service, std::shared_ptr<HaKvBackend> backend) {
+        MasterServiceTestPeer(service).SetBatchOpLogWriterFactoryForTesting(
+            [](OrderedOpLogWriterConfig config,
+               OrderedOpLogWriter::WriteBatchFn write_batch) {
+                return std::make_unique<RejectingOrderedOpLogWriter>(
+                    std::move(config), std::move(write_batch));
+            });
+        EXPECT_EQ(ErrorCode::OK,
+                  MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(
+                      std::move(backend)));
+        return static_cast<RejectingOrderedOpLogWriter*>(
+            MasterServiceTestPeer::OrderedOplogWriter(service).get());
+    }
+
+    static RejectOnceOrderedOpLogWriter* InstallRejectOnceWriter(
+        MasterService& service, std::shared_ptr<HaKvBackend> backend) {
+        MasterServiceTestPeer(service).SetBatchOpLogWriterFactoryForTesting(
+            [](OrderedOpLogWriterConfig config,
+               OrderedOpLogWriter::WriteBatchFn write_batch) {
+                return std::make_unique<RejectOnceOrderedOpLogWriter>(
+                    std::move(config), std::move(write_batch));
+            });
+        EXPECT_EQ(ErrorCode::OK,
+                  MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(
+                      std::move(backend)));
+        return static_cast<RejectOnceOrderedOpLogWriter*>(
+            MasterServiceTestPeer::OrderedOplogWriter(service).get());
+    }
+
+    static uint64_t TenantUsedBytes(MasterService& service) {
+        auto snapshot = service.GetTenantQuotaSnapshot(kDefaultTenant);
+        EXPECT_TRUE(snapshot.has_value());
+        return snapshot ? snapshot->charged_bytes : 0;
+    }
+
     void ReadRemoveBatchEventually(OpLogBatchStorage& storage,
                                    uint64_t first_batch_id,
                                    const std::string& key,
@@ -400,7 +596,6 @@ class MasterServiceHATest : public ::testing::Test {
         StandbyObjectMetadata metadata;
         metadata.client_id = generate_uuid();
         metadata.size = size;
-        metadata.last_sequence_id = 1;
         metadata.replicas.push_back(MakeStandbyMemoryReplica(endpoint, size));
         return StandbyObjectEntry{"default", key, std::move(metadata)};
     }
@@ -416,10 +611,38 @@ class MasterServiceHATest : public ::testing::Test {
         return segment;
     }
 
-    // Friend access to MasterService::metadata_shards_ and
-    // getMetadataShardIndex, which are otherwise private.
-    // MasterServiceHATest is friended; TEST_F-generated subclasses are not,
-    // hence this static funnel. Seeds an in-flight PromotionTask for a
+    static std::string FindGroupIdOnDifferentShard(MasterService& service,
+                                                   size_t source_shard,
+                                                   const std::string& prefix) {
+        for (size_t index = 0; index < MasterServiceTestPeer::kNumShards * 2;
+             ++index) {
+            std::string group_id = prefix + std::to_string(index);
+            if (MasterServiceTestPeer(service).getShardIndex(group_id) !=
+                source_shard) {
+                return group_id;
+            }
+        }
+        return {};
+    }
+
+    static std::string FindGroupIdOnDifferentShardFromObject(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key, const std::string& prefix) {
+        return FindGroupIdOnDifferentShard(
+            service,
+            MasterServiceTestPeer(service).getShardIndex(tenant_id, key),
+            prefix);
+    }
+
+    static std::string FindGroupIdOnDifferentShardFromGroup(
+        MasterService& service, const std::string& group_id,
+        const std::string& prefix) {
+        return FindGroupIdOnDifferentShard(
+            service, MasterServiceTestPeer(service).getShardIndex(group_id),
+            prefix);
+    }
+
+    // Use the test peer to seed an in-flight PromotionTask for a
     // given (tenant, key) so NotifyPromotionSuccess can proceed without
     // going through the on-hit admission gate (which is currently
     // restricted to the "default" tenant). Used only by the non-default
@@ -427,12 +650,15 @@ class MasterServiceHATest : public ::testing::Test {
     static void SeedPromotionTaskForTesting(
         MasterService* service, const TenantId& tenant, const std::string& key,
         const UUID& holder_id, ReplicaID alloc_id, uint64_t object_size) {
-        const size_t shard_idx = service->getMetadataShardIndex(tenant, key);
+        const size_t shard_idx =
+            MasterServiceTestPeer(*service).getShardIndex(tenant, key);
         auto shard_access =
-            MasterService::MetadataShardAccessorRW(service, shard_idx);
-        auto& tenant_state = shard_access->tenants[tenant];
+            MasterServiceTestPeer::MetadataShardAccessorRW(service, shard_idx);
+        auto& tenant_state =
+            MasterServiceTestPeer(*service).GetOrCreateTenantState(
+                shard_access.get(), tenant);
         tenant_state.promotion_tasks.emplace(
-            key, MasterService::PromotionTask{
+            key, MasterServiceTestPeer::PromotionTask{
                      .source_id = 0,
                      .alloc_id = alloc_id,
                      .object_size = object_size,
@@ -441,28 +667,33 @@ class MasterServiceHATest : public ::testing::Test {
     }
 
     static bool SnapshotManagerCreatedForTesting(const MasterService& service) {
-        return service.snapshot_manager_ != nullptr;
+        return MasterServiceTestPeer::SnapshotManager(service) != nullptr;
+    }
+
+    static bool NeedMemoryEvictionForTesting(const MasterService& service) {
+        return MasterServiceTestPeer::NeedMemEviction(service).load(
+            std::memory_order_relaxed);
     }
 
     static tl::expected<uint64_t, ErrorCode> AppendVisibleForTesting(
         MasterService& service, OpType type, const std::string& tenant_id,
         const std::string& key, const std::string& payload) {
-        return service.AppendOpLogVisibleBeforeDurable(type, tenant_id, key,
-                                                       payload);
+        return MasterServiceTestPeer(service).AppendOpLogVisibleBeforeDurable(
+            type, tenant_id, key, payload);
     }
 
     static tl::expected<uint64_t, ErrorCode> AppendVisibleForTesting(
         MasterService& service, OpType type, const TenantId& tenant_id,
         const std::string& key, const std::string& payload) {
-        return service.AppendOpLogVisibleBeforeDurable(type, tenant_id.value(),
-                                                       key, payload);
+        return MasterServiceTestPeer(service).AppendOpLogVisibleBeforeDurable(
+            type, tenant_id.value(), key, payload);
     }
 
     static tl::expected<OpLogEntry, ErrorCode> AppendFinalizeForTesting(
         MasterService& service, OpType type, const std::string& tenant_id,
         const std::string& key, const std::string& payload,
         MasterService::DurableFinalizeCallback callback) {
-        return service.AppendOpLogWithDurableFinalize(
+        return MasterServiceTestPeer(service).AppendOpLogWithDurableFinalize(
             type, tenant_id, key, payload, std::move(callback));
     }
 
@@ -470,37 +701,58 @@ class MasterServiceHATest : public ::testing::Test {
         MasterService& service, OpType type, const TenantId& tenant_id,
         const std::string& key, const std::string& payload,
         MasterService::DurableFinalizeCallback callback) {
-        return service.AppendOpLogWithDurableFinalize(
+        return MasterServiceTestPeer(service).AppendOpLogWithDurableFinalize(
             type, tenant_id.value(), key, payload, std::move(callback));
     }
 
     static tl::expected<OrderedOpLogWriter::Reservation, ErrorCode>
     ReserveBatchSlotForTesting(MasterService& service) {
-        if (!service.ordered_oplog_writer_) {
+        if (!MasterServiceTestPeer::OrderedOplogWriter(service)) {
             return tl::make_unexpected(ErrorCode::INTERNAL_ERROR);
         }
-        return service.ordered_oplog_writer_->Reserve();
+        return MasterServiceTestPeer::OrderedOplogWriter(service)->Reserve();
+    }
+
+    static void SetNeedMemEvictionForTesting(MasterService& service,
+                                             bool value) {
+        MasterServiceTestPeer::NeedMemEviction(service).store(value);
+    }
+
+    static bool NeedMemEvictionForTesting(const MasterService& service) {
+        return MasterServiceTestPeer::NeedMemEviction(service).load();
     }
 
     static void ClearInvalidHandlesForTesting(
         MasterService& service,
         const std::unordered_set<UUID, boost::hash<UUID>>& alive_clients) {
-        service.ClearInvalidHandles(alive_clients);
+        MasterServiceTestPeer(service).ClearInvalidHandles(alive_clients);
+    }
+
+    static void ClearInvalidHandlesForTesting(MasterService& service) {
+        MasterServiceTestPeer(service).ClearInvalidHandles();
     }
 
     static size_t ReplicaCountForTesting(MasterService& service,
                                          const TenantId& tenant_id,
                                          const std::string& key) {
-        MasterService::MetadataAccessorRO accessor(
-            &service, MasterService::ObjectIdentity{tenant_id, key});
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
         return accessor.Exists() ? accessor.Get().CountReplicas() : 0;
     }
 
+    static bool IsHardPinnedForTesting(MasterService& service,
+                                       const TenantId& tenant_id,
+                                       const std::string& key) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+        return accessor.Exists() && accessor.Get().IsHardPinned();
+    }
+
     static std::vector<Replica::Descriptor> ReplicaDescriptorsForTesting(
         MasterService& service, const TenantId& tenant_id,
         const std::string& key) {
-        MasterService::MetadataAccessorRO accessor(
-            &service, MasterService::ObjectIdentity{tenant_id, key});
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
         if (!accessor.Exists()) {
             return {};
         }
@@ -511,11 +763,23 @@ class MasterServiceHATest : public ::testing::Test {
         return descriptors;
     }
 
+    static bool HasMetadataEntryForTesting(MasterService& service,
+                                           const TenantId& tenant_id,
+                                           const std::string& key) {
+        const auto shard_idx =
+            MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+        MasterServiceTestPeer::MetadataShardAccessorRO shard(&service,
+                                                             shard_idx);
+        auto tenant = shard->tenants.find(tenant_id);
+        return tenant != shard->tenants.end() &&
+               tenant->second.metadata.contains(key);
+    }
+
     static bool HasInvalidMemoryHandleForTesting(MasterService& service,
                                                  const TenantId& tenant_id,
                                                  const std::string& key) {
-        MasterService::MetadataAccessorRO accessor(
-            &service, MasterService::ObjectIdentity{tenant_id, key});
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
         if (!accessor.Exists()) {
             return true;
         }
@@ -527,30 +791,215 @@ class MasterServiceHATest : public ::testing::Test {
         return false;
     }
 
+    static bool HasReadableReplicaForTesting(MasterService& service,
+                                             const TenantId& tenant_id,
+                                             const std::string& key) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+        return accessor.Exists() &&
+               accessor.Get().HasReplica([&service](const Replica& replica) {
+                   return MasterServiceTestPeer(service).IsReplicaReadable(
+                       replica);
+               });
+    }
+
+    static std::shared_ptr<ClientLivenessRecord> ClientRecordForTesting(
+        MasterService& service, const UUID& client_id) {
+        return MasterServiceTestPeer(service).FindClientRecord(client_id);
+    }
+
+    static tl::expected<bool, ErrorCode> AddReplicaForRetainedClientForTesting(
+        MasterService& service, const UUID& client_id, const std::string& key,
+        Replica& replica) {
+        return MasterServiceTestPeer(service).AddReplicaForRetainedClient(
+            client_id, key, kDefaultTenant, replica);
+    }
+
+    static bool ProcessClientOffboardingForTesting(MasterService& service,
+                                                   ClientOffboardingJob& job) {
+        return MasterServiceTestPeer(service).ProcessClientOffboardingJob(job);
+    }
+
+    static bool HasCompletedMemoryReplicaForTesting(MasterService& service,
+                                                    const TenantId& tenant_id,
+                                                    const std::string& key) {
+        const size_t shard_idx =
+            MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+        MasterServiceTestPeer::MetadataShardAccessorRO shard(&service,
+                                                             shard_idx);
+        const auto tenant = shard->tenants.find(tenant_id);
+        if (tenant == shard->tenants.end()) {
+            return false;
+        }
+        const auto metadata = tenant->second.metadata.find(key);
+        return metadata != tenant->second.metadata.end() &&
+               metadata->second.HasReplica([](const Replica& replica) {
+                   return replica.is_memory_replica() && replica.is_completed();
+               });
+    }
+
+    static bool MemoryReplicaAffiliatedWithForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key,
+        const std::shared_ptr<ClientLivenessRecord>& record) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+        if (!accessor.Exists()) {
+            return false;
+        }
+        return accessor.Get().HasReplica([&](const Replica& replica) {
+            return replica.is_memory_replica() &&
+                   replica.isAffiliatedWith(record);
+        });
+    }
+
+    static void SetLeaseDeadlineForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key,
+        std::chrono::system_clock::time_point deadline) {
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+        ASSERT_TRUE(accessor.Exists());
+        SpinLocker locker(&accessor.Get().lock);
+        accessor.Get().lease_->SetDeadline(deadline);
+    }
+
+    static std::chrono::system_clock::time_point LeaseDeadlineForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+        EXPECT_TRUE(accessor.Exists());
+        if (!accessor.Exists()) {
+            return {};
+        }
+        SpinLocker locker(&accessor.Get().lock);
+        return accessor.Get().lease_->ExpiresAt();
+    }
+
+    static uint64_t EvictTenantMemoryForQuotaForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        uint64_t target_bytes) {
+        return MasterServiceTestPeer(service)
+            .EvictTenantMemoryForQuota(tenant_id, target_bytes)
+            .freed_bytes;
+    }
+
+    static std::unique_lock<std::shared_mutex> LockSnapshotForTesting(
+        MasterService& service) {
+        return std::unique_lock<std::shared_mutex>(
+            MasterServiceTestPeer::SnapshotMutex(service));
+    }
+
+    static std::unique_lock<SharedMutex> LockMetadataShardForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key) {
+        const size_t shard_idx =
+            MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+        return std::unique_lock<SharedMutex>(
+            MasterServiceTestPeer::MetadataShards(service)[shard_idx].mutex);
+    }
+
+    template <typename CreateTask>
+    static bool CreateTaskReleasesMetadataBeforeServingGuardForTesting(
+        MasterService& service, const UUID& source_client,
+        const TenantId& tenant_id, const std::string& key,
+        CreateTask create_task) {
+        auto liveness =
+            MasterServiceTestPeer(service).FindClientRecord(source_client);
+        auto serving_guard =
+            liveness ? liveness->TryAcquireServingGuard() : std::nullopt;
+        if (!serving_guard) {
+            return false;
+        }
+
+        auto segment_lock = std::make_unique<ScopedSegmentAccess>(
+            MasterServiceTestPeer::SegmentManager(service).getSegmentAccess());
+        auto task = std::async(std::launch::async, std::move(create_task));
+        auto& metadata_mutex =
+            MasterServiceTestPeer::MetadataShards(
+                service)[MasterServiceTestPeer(service).getShardIndex(tenant_id,
+                                                                      key)]
+                .mutex;
+        const auto wait_for_metadata = [&](bool available, auto timeout) {
+            const auto deadline = std::chrono::steady_clock::now() + timeout;
+            while (std::chrono::steady_clock::now() < deadline) {
+                std::unique_lock<SharedMutex> metadata_lock(metadata_mutex,
+                                                            std::try_to_lock);
+                if (metadata_lock.owns_lock() == available) {
+                    return true;
+                }
+                std::this_thread::yield();
+            }
+            return false;
+        };
+
+        const bool reached_discovery =
+            wait_for_metadata(false, std::chrono::seconds(5));
+        segment_lock.reset();
+        const bool metadata_released =
+            reached_discovery &&
+            wait_for_metadata(true, std::chrono::seconds(1));
+        serving_guard.reset();
+        return task.get().has_value() && reached_discovery && metadata_released;
+    }
+
+    static bool PutStartHoldsSnapshotAfterClientReleaseForTesting(
+        MasterService& service, const TenantId& tenant_id,
+        const std::string& key) {
+        const auto scoped_key = tenant_id.MakeScopedKey(key);
+        const size_t stripe_idx =
+            std::hash<std::string>{}(scoped_key) %
+            MasterServiceTestPeer::kObjectOperationLockStripes;
+        std::unique_lock<std::mutex> object_lock(
+            MasterServiceTestPeer::ObjectOperationLocks(service)[stripe_idx],
+            std::try_to_lock);
+        if (object_lock.owns_lock()) {
+            return false;
+        }
+        std::unique_lock<std::shared_mutex> client_lock(
+            MasterServiceTestPeer::ClientMutex(service), std::try_to_lock);
+        if (!client_lock.owns_lock()) {
+            return false;
+        }
+        std::unique_lock<std::shared_mutex> snapshot_lock(
+            MasterServiceTestPeer::SnapshotMutex(service), std::try_to_lock);
+        return !snapshot_lock.owns_lock();
+    }
+
+    static std::unique_lock<std::shared_mutex> LockClientForTesting(
+        MasterService& service) {
+        return std::unique_lock<std::shared_mutex>(
+            MasterServiceTestPeer::ClientMutex(service));
+    }
+
     static size_t SegmentAllocatedSizeForTesting(MasterService& service,
                                                  const std::string& name) {
-        auto access = service.segment_manager_.getAllocatorAccess();
+        auto access =
+            MasterServiceTestPeer::SegmentManager(service).getAllocatorAccess();
         const auto* allocators =
             access.getAllocatorManager().getAllocators(name);
         EXPECT_NE(allocators, nullptr);
         EXPECT_EQ(allocators == nullptr ? 0 : allocators->size(), 1);
-        return allocators == nullptr || allocators->empty()
-                   ? 0
-                   : allocators->front()->size();
+        const auto allocator = allocators == nullptr || allocators->empty()
+                                   ? nullptr
+                                   : allocators->front()->GetAllocator();
+        return allocator ? allocator->size() : 0;
     }
 
     static void EraseObjectForTesting(MasterService& service,
                                       const TenantId& tenant_id,
                                       const std::string& key) {
-        MasterService::MetadataAccessorRW accessor(
-            &service, MasterService::ObjectIdentity{tenant_id, key});
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
         ASSERT_TRUE(accessor.Exists());
         accessor.Erase();
     }
 
     static void PrepareUnmountSegmentForTesting(MasterService& service,
                                                 const UUID& segment_id) {
-        auto segment_access = service.segment_manager_.getSegmentAccess();
+        auto segment_access =
+            MasterServiceTestPeer::SegmentManager(service).getSegmentAccess();
         size_t metrics_dec_capacity = 0;
         ASSERT_EQ(ErrorCode::OK, segment_access.PrepareUnmountSegment(
                                      segment_id, metrics_dec_capacity));
@@ -559,8 +1008,8 @@ class MasterServiceHATest : public ::testing::Test {
     static std::vector<ReplicaID> MarkCompletedReplicasRemovedForTesting(
         MasterService& service, const TenantId& tenant_id,
         const std::string& key) {
-        MasterService::MetadataAccessorRW accessor(
-            &service, MasterService::ObjectIdentity{tenant_id, key});
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            &service, MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
         if (!accessor.Exists()) {
             return {};
         }
@@ -576,22 +1025,32 @@ class MasterServiceHATest : public ::testing::Test {
     static void FinalizeRemovedReplicasForTesting(
         MasterService& service, const OpLogEntry& durable_entry,
         const std::vector<ReplicaID>& replica_ids) {
-        service.FinalizeRemovedReplicasAfterDurable(
-            durable_entry, replica_ids, MasterService::QuotaEraseMode::kFull);
+        MasterServiceTestPeer(service).FinalizeRemovedReplicasAfterDurable(
+            durable_entry, replica_ids,
+            MasterServiceTestPeer::QuotaEraseMode::kFull);
     }
 
     static void SetLocalDiskUsedBytesForTesting(MasterService& service,
                                                 const UUID& client_id,
                                                 int64_t used_bytes) {
-        auto access = service.segment_manager_.getLocalDiskSegmentAccess();
-        access.getClientLocalDiskSegment().at(client_id)->ssd_used_bytes.store(
-            used_bytes, std::memory_order_relaxed);
+        auto usage =
+            MasterServiceTestPeer::LocalSsdManager(service).GetUsage(client_id);
+        ASSERT_TRUE(usage.has_value());
+        MasterServiceTestPeer::LocalSsdManager(service).AdjustUsedBytes(
+            client_id, used_bytes - usage->used_bytes);
     }
 
     static int64_t GetLocalDiskUsedBytesForTesting(
         MasterService& service, const std::string& segment_name) {
-        auto access = service.segment_manager_.getLocalDiskSegmentAccess();
-        return access.getSsdUsedBytes(segment_name);
+        auto access =
+            MasterServiceTestPeer::SegmentManager(service).getAllocatorAccess();
+        auto client_id = access.GetOwnerClientId(segment_name);
+        if (!client_id) {
+            return 0;
+        }
+        auto usage = MasterServiceTestPeer::LocalSsdManager(service).GetUsage(
+            *client_id);
+        return usage ? usage->used_bytes : 0;
     }
 
     std::vector<std::string> policy_files_;
@@ -600,6 +1059,97 @@ class MasterServiceHATest : public ::testing::Test {
 
 class MasterServiceBatchRecordE2ETest : public MasterServiceHATest {};
 
+TEST_F(MasterServiceHATest, PutStartWithoutMemorySegmentsDoesNotArmEviction) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_eviction_ratio(0.0)
+                              .set_eviction_high_watermark_ratio(1.0)
+                              .build());
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    auto result = service.PutStart(generate_uuid(), "no_memory_segments",
+                                   kDefaultTenant, 1024, config);
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_FALSE(NeedMemoryEvictionForTesting(service));
+}
+
+TEST_F(MasterServiceHATest,
+       PutStartWithFewerMemorySegmentsThanReplicasDoesNotArmEviction) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_eviction_ratio(0.0)
+                              .set_eviction_high_watermark_ratio(1.0)
+                              .build());
+    const auto mounted =
+        PrepareSimpleSegment(service, "insufficient_segment_count");
+    ReplicateConfig config;
+    config.replica_num = 2;
+
+    auto result =
+        service.PutStart(mounted.client_id, "insufficient_segment_count",
+                         kDefaultTenant, 2 * kDefaultSegmentSize, config);
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_FALSE(NeedMemoryEvictionForTesting(service));
+}
+
+TEST_F(MasterServiceHATest,
+       PutStartAllocationFailureWithEnoughMemorySegmentsArmsEviction) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_eviction_ratio(0.0)
+                              .set_eviction_high_watermark_ratio(1.0)
+                              .build());
+    const auto first = PrepareSimpleSegment(service, "full_segment_1");
+    PrepareSimpleSegment(service, "full_segment_2",
+                         kDefaultSegmentBase + kDefaultSegmentSize);
+    ReplicateConfig config;
+    config.replica_num = 2;
+
+    auto result =
+        service.PutStart(first.client_id, "enough_full_segments",
+                         kDefaultTenant, 2 * kDefaultSegmentSize, config);
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_TRUE(NeedMemoryEvictionForTesting(service));
+}
+
+TEST_F(MasterServiceHATest,
+       PutStartWithTooFewMemorySegmentsPreservesArmedEviction) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_eviction_ratio(0.0)
+                              .set_eviction_high_watermark_ratio(1.0)
+                              .build());
+    const auto first = PrepareSimpleSegment(service, "preserve_flag_segment_1");
+    const auto second =
+        PrepareSimpleSegment(service, "preserve_flag_segment_2",
+                             kDefaultSegmentBase + kDefaultSegmentSize);
+    ReplicateConfig config;
+    config.replica_num = 2;
+
+    auto first_result =
+        service.PutStart(first.client_id, "arm_eviction", kDefaultTenant,
+                         2 * kDefaultSegmentSize, config);
+    ASSERT_FALSE(first_result.has_value());
+    ASSERT_TRUE(NeedMemoryEvictionForTesting(service));
+    ASSERT_TRUE(service.UnmountSegment(second.segment_id, second.client_id)
+                    .has_value());
+
+    auto second_result =
+        service.PutStart(first.client_id, "preserve_armed_eviction",
+                         kDefaultTenant, 2 * kDefaultSegmentSize, config);
+
+    ASSERT_FALSE(second_result.has_value());
+    EXPECT_EQ(second_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_TRUE(NeedMemoryEvictionForTesting(service));
+}
+
 TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesMemoryBufferDescriptor) {
     MasterService service(
         MasterServiceConfig::builder().set_enable_ha(false).build());
@@ -614,8 +1164,10 @@ TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesMemoryBufferDescriptor) {
     descriptor.buffer_address_ = address;
     descriptor.protocol_ = "tcp";
 
-    service.RestoreFromStandbySnapshot({object}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
 
     auto replicas = ReplicaDescriptorsForTesting(service, kDefaultTenant,
                                                  "standby_restore_key");
@@ -629,6 +1181,780 @@ TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesMemoryBufferDescriptor) {
     EXPECT_EQ(restored.transport_endpoint_, endpoint);
 }
 
+TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesReplicaIds) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string endpoint = "standby_replica_id_segment";
+    PrepareSimpleSegment(service, endpoint);
+    auto object = MakeStandbyObject("standby_replica_id_key", endpoint);
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase + 4096;
+    object.metadata.replicas.front().id = 41;
+    auto removed = MakeStandbyMemoryReplica(endpoint);
+    removed.id = 42;
+    removed.status = ReplicaStatus::REMOVED;
+    object.metadata.replicas.push_back(std::move(removed));
+
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+
+    auto replicas = ReplicaDescriptorsForTesting(service, kDefaultTenant,
+                                                 "standby_replica_id_key");
+    ASSERT_EQ(replicas.size(), 2);
+    EXPECT_EQ(replicas[0].id, 41);
+    EXPECT_EQ(replicas[1].id, 42);
+
+    const UUID client_id = generate_uuid();
+    const std::string new_key = "standby_replica_id_new_key";
+    PutObjectOnSegment(service, client_id, new_key, endpoint);
+    auto new_replicas =
+        ReplicaDescriptorsForTesting(service, kDefaultTenant, new_key);
+    ASSERT_EQ(new_replicas.size(), 1);
+    EXPECT_GE(new_replicas.front().id, 43);
+}
+
+TEST_F(MasterServiceHATest, BatchPromotionDrainsMultipleChunksAndPreservesIds) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    const std::string endpoint = "batch_promotion_segment";
+
+    auto first = MakeStandbyObject("batch_promotion_first", endpoint);
+    first.metadata.replicas.front().id = 41;
+    first.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    auto second = MakeStandbyObject("batch_promotion_second", endpoint);
+    second.tenant_id = "batch-promotion-tenant";
+    second.metadata.replicas.front().id = 42;
+    second.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase + 4096;
+
+    auto source = std::make_unique<StandbyMetadataStore>();
+    ASSERT_TRUE(
+        source->PutMetadata(first.tenant_id, first.key, first.metadata));
+    ASSERT_TRUE(
+        source->PutMetadata(second.tenant_id, second.key, second.metadata));
+    BatchOpLogPromotionHandoff handoff;
+    handoff.metadata_store = std::move(source);
+    handoff.segments = {MakeStandbyMemorySegment(endpoint)};
+    handoff.applied_cursor = {.batch_id = 7, .last_seq = 7};
+    handoff.max_replica_id = 42;
+
+    ASSERT_TRUE(service.RestoreFromBatchOpLogPromotion(std::move(handoff), 1)
+                    .has_value());
+    auto first_descriptors =
+        ReplicaDescriptorsForTesting(service, kDefaultTenant, first.key);
+    auto second_descriptors = ReplicaDescriptorsForTesting(
+        service, TenantId(second.tenant_id), second.key);
+    ASSERT_EQ(first_descriptors.size(), 1);
+    ASSERT_EQ(second_descriptors.size(), 1);
+    EXPECT_EQ(first_descriptors.front().id, 41);
+    EXPECT_EQ(second_descriptors.front().id, 42);
+}
+
+TEST_F(MasterServiceHATest, BatchPromotionRejectsCrossChunkOverlap) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    const std::string endpoint = "batch_promotion_overlap_segment";
+    auto first = MakeStandbyObject("batch_promotion_overlap_first", endpoint);
+    first.metadata.replicas.front().id = 51;
+    first.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    auto second = MakeStandbyObject("batch_promotion_overlap_second", endpoint);
+    second.metadata.replicas.front().id = 52;
+    second.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+
+    auto source = std::make_unique<StandbyMetadataStore>();
+    ASSERT_TRUE(
+        source->PutMetadata(first.tenant_id, first.key, first.metadata));
+    ASSERT_TRUE(
+        source->PutMetadata(second.tenant_id, second.key, second.metadata));
+    BatchOpLogPromotionHandoff handoff;
+    handoff.metadata_store = std::move(source);
+    handoff.segments = {MakeStandbyMemorySegment(endpoint)};
+    handoff.applied_cursor = {.batch_id = 7, .last_seq = 7};
+    handoff.max_replica_id = 52;
+
+    auto result = service.RestoreFromBatchOpLogPromotion(std::move(handoff), 1);
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
+    EXPECT_EQ(
+        HasMetadataEntryForTesting(service, kDefaultTenant, first.key) +
+            HasMetadataEntryForTesting(service, kDefaultTenant, second.key),
+        1);
+}
+
+TEST_F(MasterServiceHATest, RestoreRejectsInvalidReplicaIds) {
+    const std::string endpoint = "standby_invalid_replica_id_segment";
+    for (const ReplicaID id :
+         {ReplicaID{0}, std::numeric_limits<ReplicaID>::max()}) {
+        MasterService service(
+            MasterServiceConfig::builder().set_enable_ha(false).build());
+        auto object = MakeStandbyObject("standby_invalid_replica_id", endpoint);
+        object.metadata.replicas.front().id = id;
+
+        auto result = service.RestoreFromStandbySnapshot(
+            {object}, 7, {MakeStandbyMemorySegment(endpoint)});
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    auto object = MakeStandbyObject("standby_duplicate_replica_id", endpoint);
+    auto duplicate = MakeStandbyMemoryReplica(endpoint);
+    duplicate.id = object.metadata.replicas.front().id;
+    duplicate.status = ReplicaStatus::REMOVED;
+    object.metadata.replicas.push_back(std::move(duplicate));
+
+    auto result = service.RestoreFromStandbySnapshot(
+        {object}, 7, {MakeStandbyMemorySegment(endpoint)});
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+
+    auto first = MakeStandbyObject("standby_cross_object_id_first", endpoint);
+    auto second = MakeStandbyObject("standby_cross_object_id_second", endpoint);
+    first.metadata.replicas.front().id = 73;
+    second.metadata.replicas.front().id = 73;
+    second.metadata.replicas.front().status = ReplicaStatus::REMOVED;
+    ASSERT_TRUE(
+        service
+            .RestoreFromStandbySnapshot({first, second}, 7,
+                                        {MakeStandbyMemorySegment(endpoint)})
+            .has_value());
+}
+
+TEST_F(MasterServiceHATest, FailedRestoreDoesNotAdvanceReplicaIdCounter) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    PrepareSimpleSegment(service, "replica_id_counter");
+    const UUID first_client = generate_uuid();
+    const std::string first_key = "replica_id_counter_first";
+    PutObjectOnSegment(service, first_client, first_key, "replica_id_counter");
+    const auto first =
+        ReplicaDescriptorsForTesting(service, kDefaultTenant, first_key);
+    ASSERT_EQ(first.size(), 1);
+
+    auto valid =
+        MakeStandbyObject("replica_id_counter_valid", "replica_id_counter");
+    valid.metadata.replicas.front().id = first.front().id + 1000;
+    valid.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase + 4096;
+    auto invalid = MakeStandbyObject("replica_id_counter_invalid",
+                                     "unknown_replica_id_endpoint");
+    invalid.metadata.replicas.front().id = first.front().id + 2000;
+    auto result = service.RestoreFromStandbySnapshot(
+        {valid, invalid}, 7, {MakeStandbyMemorySegment("replica_id_counter")});
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant,
+                                     "replica_id_counter_valid"),
+              0);
+
+    const UUID second_client = generate_uuid();
+    const std::string second_key = "replica_id_counter_second";
+    PutObjectOnSegment(service, second_client, second_key,
+                       "replica_id_counter");
+    const auto second =
+        ReplicaDescriptorsForTesting(service, kDefaultTenant, second_key);
+    ASSERT_EQ(second.size(), 1);
+    EXPECT_EQ(second.front().id, first.front().id + 1);
+}
+
+TEST_F(MasterServiceHATest,
+       StandbyMemoryRemainsUnaffiliatedUntilActualOwnerRemounts) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string key = "standby_unaffiliated_key";
+    const std::string endpoint = "standby_unaffiliated_segment";
+    auto object = MakeStandbyObject(key, endpoint);
+    const UUID writer_id = object.metadata.client_id;
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+    EXPECT_FALSE(ClientRecordForTesting(service, writer_id));
+    auto before_remount = service.GetReplicaList(key, kDefaultTenant);
+    ASSERT_FALSE(before_remount.has_value());
+    EXPECT_EQ(before_remount.error(), ErrorCode::REPLICA_IS_NOT_READY);
+
+    const UUID actual_owner = generate_uuid();
+    ASSERT_TRUE(service.ReMountSegment({MakeSegment(endpoint)}, actual_owner)
+                    .has_value());
+    const auto actual_record = ClientRecordForTesting(service, actual_owner);
+    ASSERT_TRUE(actual_record);
+    EXPECT_FALSE(ClientRecordForTesting(service, writer_id));
+    EXPECT_TRUE(MemoryReplicaAffiliatedWithForTesting(service, kDefaultTenant,
+                                                      key, actual_record));
+}
+
+TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesHardPinned) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string key = "standby_restore_hard_pinned";
+    const std::string endpoint = "standby_restore_hard_pinned_segment";
+    auto object = MakeStandbyObject(key, endpoint);
+    object.metadata.hard_pinned = true;
+
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+    EXPECT_TRUE(IsHardPinnedForTesting(service, kDefaultTenant, key));
+}
+
+TEST_F(MasterServiceHATest, RestoreFailureKeepsExistingState) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string endpoint = "standby_restore_existing_segment";
+    auto existing = MakeStandbyObject("standby_restore_existing", endpoint);
+    existing.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {existing}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+    const auto metric_after_restore =
+        MasterMetricManager::instance().get_allocated_mem_size();
+
+    auto invalid =
+        MakeStandbyObject("standby_restore_invalid", "unknown_endpoint");
+    auto result = service.RestoreFromStandbySnapshot(
+        {invalid}, 7, {MakeStandbyMemorySegment(endpoint)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant,
+                                     "standby_restore_existing"),
+              1);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant,
+                                     "standby_restore_invalid"),
+              0);
+    EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size(),
+              metric_after_restore);
+    ASSERT_TRUE(service.ReMountSegment({MakeSegment(endpoint)}, generate_uuid())
+                    .has_value());
+}
+
+TEST_F(MasterServiceHATest,
+       RestoreRejectsUngroupedObjectDuplicatedIntoAnotherShard) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string key = "standby_cross_shard_duplicate";
+    const std::string endpoint = "standby_cross_shard_segment";
+    auto existing = MakeStandbyObject(key, endpoint);
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {existing}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+
+    auto duplicate = MakeStandbyObject(key, endpoint);
+    duplicate.metadata.group_id = FindGroupIdOnDifferentShardFromObject(
+        service, kDefaultTenant, key, "group-");
+    ASSERT_FALSE(duplicate.metadata.group_id.empty());
+
+    auto result = service.RestoreFromStandbySnapshot(
+        {duplicate}, 8, {MakeStandbyMemorySegment(endpoint)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+}
+
+TEST_F(MasterServiceHATest,
+       RestoreRejectsGroupedObjectDuplicatedIntoAnotherGroupDomain) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string key = "standby_cross_group_duplicate";
+    const std::string endpoint = "standby_cross_group_segment";
+    auto existing = MakeStandbyObject(key, endpoint);
+    existing.metadata.group_id = "existing-group";
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {existing}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+
+    auto duplicate = MakeStandbyObject(key, endpoint);
+    duplicate.metadata.group_id = FindGroupIdOnDifferentShardFromGroup(
+        service, existing.metadata.group_id, "replacement-group-");
+    ASSERT_FALSE(duplicate.metadata.group_id.empty());
+
+    auto result = service.RestoreFromStandbySnapshot(
+        {duplicate}, 8, {MakeStandbyMemorySegment(endpoint)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+}
+
+TEST_F(MasterServiceHATest, RestoreRejectsDescriptorSizeMismatch) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string endpoint = "standby_descriptor_mismatch_segment";
+    auto object = MakeStandbyObject("standby_descriptor_mismatch", endpoint);
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.size_ = object.metadata.size + 1;
+
+    auto result = service.RestoreFromStandbySnapshot(
+        {object}, 7, {MakeStandbyMemorySegment(endpoint)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(MasterServiceHATest, RestoreRejectsDescriptorsBeyondSegmentCapacity) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string endpoint = "standby_capacity_segment";
+    auto first = MakeStandbyObject("standby_capacity_first", endpoint);
+    auto second = MakeStandbyObject("standby_capacity_second", endpoint);
+    first.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    second.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase + 4096;
+
+    auto result = service.RestoreFromStandbySnapshot(
+        {first, second}, 7, {MakeStandbyMemorySegment(endpoint, 1024)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(MasterServiceHATest, RestoreRejectsDfsMode) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    EnableDfsForTesting(service);
+
+    auto result = service.RestoreFromStandbySnapshot({}, 0, {});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+}
+
+TEST_F(MasterServiceHATest, RestoreFromStandbyRebuildsTenantQuotaAccounting) {
+    const TenantId tenant_id("tenant_a");
+    constexpr uint64_t object_size = 1024;
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_multi_tenants(true)
+                      .set_tenant_quota_connector_type("file")
+                      .set_tenant_quota_connector_uri(WriteTenantPolicyFile(
+                          {{tenant_id.value(), object_size}}))
+                      .build();
+    MasterService service(config);
+
+    const std::string key = "standby_quota_key";
+    const std::string endpoint = "standby_quota_segment";
+    auto object = MakeStandbyObject(key, endpoint, object_size);
+    object.tenant_id = tenant_id.value();
+
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+
+    auto snapshot = service.GetTenantQuotaSnapshot(tenant_id);
+    ASSERT_TRUE(snapshot.has_value());
+    EXPECT_EQ(snapshot->charged_bytes, object_size);
+    ASSERT_TRUE(service.Remove(key, tenant_id, /*force=*/true).has_value());
+    EXPECT_EQ(service.GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 0);
+}
+
+TEST_F(MasterServiceHATest, UnreadableRestoredMemoryReplicaIsNotEvictable) {
+    constexpr uint64_t object_size = 1024;
+    auto config = MasterServiceConfig::builder()
+                      .set_default_kv_lease_ttl(10000)
+                      .set_enable_multi_tenants(true)
+                      .set_tenant_quota_connector_type("file")
+                      .set_tenant_quota_connector_uri(WriteTenantPolicyFile(
+                          {{kDefaultTenant.value(), object_size}}))
+                      .build();
+    MasterService service(config);
+    const std::string key = "unreadable_restored_evict_key";
+    const std::string endpoint = "unreadable_restored_evict_segment";
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {MakeStandbyObject(key, endpoint, object_size)}, 7,
+                        {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+    SetLeaseDeadlineForTesting(service, kDefaultTenant, key,
+                               std::chrono::system_clock::time_point{});
+
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant, key), 1);
+    EXPECT_EQ(EvictTenantMemoryForQuotaForTesting(service, kDefaultTenant,
+                                                  object_size),
+              0);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant, key), 1);
+    EXPECT_FALSE(HasReadableReplicaForTesting(service, kDefaultTenant, key));
+    auto get = service.GetReplicaList(key, kDefaultTenant);
+    ASSERT_FALSE(get.has_value());
+    EXPECT_EQ(get.error(), ErrorCode::REPLICA_IS_NOT_READY);
+}
+
+TEST_F(MasterServiceHATest, SuccessfulRemountGrantsEvictionLease) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_default_kv_lease_ttl(10000)
+                              .build());
+    const std::string key = "remount_lease_key";
+    const std::string endpoint = "remount_lease_segment";
+    auto object = MakeStandbyObject(key, endpoint);
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
+    SetLeaseDeadlineForTesting(service, kDefaultTenant, key,
+                               std::chrono::system_clock::time_point{});
+
+    ASSERT_TRUE(service.ReMountSegment({MakeSegment(endpoint)}, generate_uuid())
+                    .has_value());
+    EXPECT_TRUE(HasReadableReplicaForTesting(service, kDefaultTenant, key));
+    EXPECT_GT(LeaseDeadlineForTesting(service, kDefaultTenant, key),
+              std::chrono::system_clock::now());
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant, key), 1);
+
+    SetLeaseDeadlineForTesting(service, kDefaultTenant, key,
+                               std::chrono::system_clock::time_point{});
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant, key), 0);
+}
+
+TEST_F(MasterServiceHATest, RemountRefreshesLeaseWhenAnotherReplicaIsReadable) {
+    MasterService service(MasterServiceConfig::builder()
+                              .set_enable_ha(false)
+                              .set_default_kv_lease_ttl(10000)
+                              .build());
+    const std::string key = "remount_existing_readable_key";
+    const std::string recovered_endpoint = "remount_recovered_segment";
+    const std::string readable_endpoint = "remount_readable_segment";
+    Segment readable_segment = MakeSegment(
+        readable_endpoint, kDefaultSegmentBase + kDefaultSegmentSize);
+    ASSERT_TRUE(
+        service.MountSegment(readable_segment, generate_uuid()).has_value());
+
+    auto object = MakeStandbyObject(key, recovered_endpoint);
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    auto readable_replica = MakeStandbyMemoryReplica(readable_endpoint);
+    readable_replica.id = 2;
+    readable_replica.get_memory_descriptor().buffer_descriptor.buffer_address_ =
+        kDefaultSegmentBase + kDefaultSegmentSize;
+    object.metadata.replicas.push_back(std::move(readable_replica));
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7,
+                        {MakeStandbyMemorySegment(recovered_endpoint),
+                         MakeStandbyMemorySegment(readable_endpoint)})
+                    .has_value());
+    ASSERT_TRUE(HasReadableReplicaForTesting(service, kDefaultTenant, key));
+    SetLeaseDeadlineForTesting(service, kDefaultTenant, key,
+                               std::chrono::system_clock::time_point{});
+
+    ASSERT_TRUE(
+        service
+            .ReMountSegment({MakeSegment(recovered_endpoint)}, generate_uuid())
+            .has_value());
+    EXPECT_GT(LeaseDeadlineForTesting(service, kDefaultTenant, key),
+              std::chrono::system_clock::now());
+}
+
+TEST_F(MasterServiceHATest,
+       LocalFirstAllocationDoesNotReacquireClientLockUnderSnapshotBarrier) {
+    MasterService service(
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build());
+    const UUID client_id = generate_uuid();
+    const std::string key = "local_first_lock_order_key";
+    Segment segment = MakeSegment("local_first_lock_order_segment");
+    segment.host_id = "writer-host";
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    auto shard_lock = LockMetadataShardForTesting(service, kDefaultTenant, key);
+    auto put = std::async(std::launch::async, [&] {
+        return service.PutStart(client_id, key, kDefaultTenant, 1024, config);
+    });
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    bool reached_snapshot = false;
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (PutStartHoldsSnapshotAfterClientReleaseForTesting(
+                service, kDefaultTenant, key)) {
+            reached_snapshot = true;
+            break;
+        }
+        std::this_thread::yield();
+    }
+    if (!reached_snapshot) {
+        shard_lock.unlock();
+        EXPECT_EQ(put.wait_for(std::chrono::seconds(5)),
+                  std::future_status::ready);
+        if (put.wait_for(std::chrono::seconds(0)) ==
+            std::future_status::ready) {
+            (void)put.get();
+        }
+        FAIL() << "PutStart did not reach the snapshot barrier";
+    }
+
+    // ReMountSegment holds client_mutex_ exclusively while waiting for the
+    // snapshot barrier. PutStart must not reacquire it inside that barrier.
+    auto client_lock = LockClientForTesting(service);
+    shard_lock.unlock();
+    const bool completed_while_client_locked =
+        put.wait_for(std::chrono::seconds(1)) == std::future_status::ready;
+    client_lock.unlock();
+
+    ASSERT_EQ(put.wait_for(std::chrono::seconds(5)), std::future_status::ready);
+    auto result = put.get();
+    ASSERT_TRUE(result.has_value()) << toString(result.error());
+    EXPECT_TRUE(completed_while_client_locked);
+}
+
+TEST_F(MasterServiceHATest,
+       CopyAndMoveTaskCreationReleaseMetadataBeforeServingGuard) {
+    for (const bool move : {false, true}) {
+        SCOPED_TRACE(move ? "move" : "copy");
+        MasterService service(MasterServiceConfig::builder().build());
+        const std::string suffix = move ? "move" : "copy";
+        const std::string source_name = "task_lock_order_" + suffix + "_src";
+        const std::string target_name = "task_lock_order_" + suffix + "_dst";
+        const std::string key = "task_lock_order_" + suffix + "_key";
+        auto source = PrepareSimpleSegment(service, source_name);
+        PrepareSimpleSegment(service, target_name,
+                             kDefaultSegmentBase + kDefaultSegmentSize);
+        PutObjectOnSegment(service, source.client_id, key, source_name);
+
+        EXPECT_TRUE(CreateTaskReleasesMetadataBeforeServingGuardForTesting(
+            service, source.client_id, kDefaultTenant, key,
+            [&service, move, &key, &source_name, &target_name] {
+                if (move) {
+                    return service.CreateMoveTask(key, kDefaultTenant,
+                                                  source_name, target_name);
+                }
+                return service.CreateCopyTask(key, kDefaultTenant,
+                                              {target_name});
+            }));
+    }
+}
+
+TEST_F(MasterServiceHATest,
+       RetainedAddReplicaDoesNotReacquireClientRegistryLock) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_offload(true).build());
+    auto mounted =
+        PrepareSimpleSegment(service, "retained_add_replica_segment");
+    ASSERT_TRUE(service
+                    .MountLocalDiskSegment(mounted.client_id,
+                                           /*enable_offloading=*/false)
+                    .has_value());
+    const auto record = ClientRecordForTesting(service, mounted.client_id);
+    ASSERT_TRUE(record);
+    auto retaining_guard = record->TryAcquireRetainingGuard();
+    ASSERT_TRUE(retaining_guard);
+
+    Replica replica(mounted.client_id, 1024, "retained_add_replica_endpoint",
+                    ReplicaStatus::COMPLETE, record);
+    auto client_lock = LockClientForTesting(service);
+    auto add = std::async(std::launch::async, [&] {
+        return AddReplicaForRetainedClientForTesting(
+            service, mounted.client_id, "retained_add_replica_key", replica);
+    });
+    const bool completed_while_client_locked =
+        add.wait_for(std::chrono::seconds(1)) == std::future_status::ready;
+    client_lock.unlock();
+
+    ASSERT_EQ(add.wait_for(std::chrono::seconds(5)), std::future_status::ready);
+    auto result = add.get();
+    ASSERT_TRUE(result.has_value()) << toString(result.error());
+    EXPECT_TRUE(completed_while_client_locked);
+}
+
+TEST_F(MasterServiceHATest,
+       ClientOffboardingRetriesRejectedMetadataOpLogBeforeSegmentCommit) {
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_ha(true)
+                      .set_enable_oplog(true)
+                      .set_cluster_id("offboarding_retry_oplog")
+                      .build();
+    MasterService service(config);
+    auto writer = InstallRejectOnceWriter(
+        service, std::make_shared<FakeBatchHaKvBackend>());
+    ASSERT_NE(writer, nullptr);
+
+    auto segment = MakeSegment("offboarding_retry_oplog_segment");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+    const std::string key = "offboarding_retry_oplog_key";
+    PutObjectOnSegment(service, client_id, key, segment.name);
+
+    const auto liveness = ClientRecordForTesting(service, client_id);
+    ASSERT_TRUE(liveness);
+    const auto now = ClientLivenessRecord::Clock::now();
+    ASSERT_EQ(liveness->Evaluate(now, std::chrono::seconds::zero(),
+                                 std::chrono::seconds::zero()),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    MasterMetricManager::instance().client_liveness_became_suspected();
+    ASSERT_EQ(liveness->Evaluate(now, std::chrono::seconds::zero(),
+                                 std::chrono::seconds::zero()),
+              ClientLivenessTransition::BECAME_OFFLINE);
+    MasterMetricManager::instance().client_liveness_became_offline();
+
+    ClientOffboardingJob job;
+    job.client_id = client_id;
+    job.liveness = liveness;
+    job.pending_prepare_segments.push_back(
+        {.segment_id = segment.id,
+         .segment_name = segment.name,
+         .transport_endpoint = segment.te_endpoint});
+
+    writer->RejectNextCommit();
+    ASSERT_FALSE(ProcessClientOffboardingForTesting(service, job));
+    EXPECT_FALSE(job.metadata_cleanup_accepted);
+    ASSERT_EQ(job.prepared_segments.size(), 1u);
+    EXPECT_TRUE(
+        HasCompletedMemoryReplicaForTesting(service, kDefaultTenant, key));
+    EXPECT_TRUE(service.QuerySegmentStatusById(segment.id).has_value());
+
+    ASSERT_TRUE(ProcessClientOffboardingForTesting(service, job));
+    EXPECT_TRUE(job.prepared_segments.empty());
+    EXPECT_FALSE(service.QuerySegmentStatusById(segment.id).has_value());
+    EXPECT_FALSE(ClientRecordForTesting(service, client_id));
+}
+
+TEST_F(MasterServiceHATest,
+       ClientOffboardingRetainsNameAcrossRejectedUnmountOpLog) {
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_ha(true)
+                      .set_enable_oplog(true)
+                      .set_cluster_id("offboarding_retry_unmount_oplog")
+                      .build();
+    MasterService service(config);
+    auto writer = InstallRejectOnceWriter(
+        service, std::make_shared<FakeBatchHaKvBackend>());
+    ASSERT_NE(writer, nullptr);
+
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline_capacity = metrics.get_total_mem_capacity();
+    auto segment = MakeSegment("offboarding_reserved_segment_name");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+    ASSERT_EQ(metrics.get_total_mem_capacity(),
+              baseline_capacity + static_cast<int64_t>(segment.size));
+
+    const auto liveness = ClientRecordForTesting(service, client_id);
+    ASSERT_TRUE(liveness);
+    const auto now = ClientLivenessRecord::Clock::now();
+    ASSERT_EQ(liveness->Evaluate(now, std::chrono::seconds::zero(),
+                                 std::chrono::seconds::zero()),
+              ClientLivenessTransition::BECAME_SUSPECTED);
+    MasterMetricManager::instance().client_liveness_became_suspected();
+    ASSERT_EQ(liveness->Evaluate(now, std::chrono::seconds::zero(),
+                                 std::chrono::seconds::zero()),
+              ClientLivenessTransition::BECAME_OFFLINE);
+    MasterMetricManager::instance().client_liveness_became_offline();
+
+    ClientOffboardingJob job;
+    job.client_id = client_id;
+    job.liveness = liveness;
+    job.pending_prepare_segments.push_back(
+        {.segment_id = segment.id,
+         .segment_name = segment.name,
+         .transport_endpoint = segment.te_endpoint});
+
+    writer->RejectNextSegmentUnmount();
+    ASSERT_FALSE(ProcessClientOffboardingForTesting(service, job));
+    EXPECT_FALSE(service.QuerySegmentStatusById(segment.id).has_value());
+    EXPECT_EQ(metrics.get_total_mem_capacity(), baseline_capacity);
+
+    auto replacement = MakeSegment(segment.name, /*base=*/0x400000000);
+    const UUID replacement_client = generate_uuid();
+    auto blocked_mount = service.MountSegment(replacement, replacement_client);
+    ASSERT_FALSE(blocked_mount.has_value());
+    EXPECT_EQ(blocked_mount.error(), ErrorCode::INVALID_PARAMS);
+
+    ASSERT_TRUE(ProcessClientOffboardingForTesting(service, job));
+    EXPECT_EQ(metrics.get_total_mem_capacity(), baseline_capacity);
+    ASSERT_TRUE(
+        service.MountSegment(replacement, replacement_client).has_value());
+}
+
+TEST_F(MasterServiceHATest, NoFBatchEvictWaitsForSnapshotBarrier) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    auto snapshot_lock = LockSnapshotForTesting(service);
+    std::promise<void> started;
+    auto started_future = started.get_future();
+    auto eviction = std::async(std::launch::async, [&] {
+        started.set_value();
+        MasterServiceTestPeer(service).RunNoFBatchEvictForTesting(
+            /*evict_ratio_target=*/1.0,
+            /*evict_ratio_lowerbound=*/1.0);
+    });
+    started_future.wait();
+    EXPECT_EQ(eviction.wait_for(std::chrono::milliseconds(100)),
+              std::future_status::timeout);
+    snapshot_lock.unlock();
+    ASSERT_EQ(eviction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    eviction.get();
+}
+
+TEST_F(MasterServiceHATest, InvalidHandleCleanupWaitsForSnapshotBarrier) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    auto snapshot_lock = LockSnapshotForTesting(service);
+    std::promise<void> started;
+    auto started_future = started.get_future();
+    auto cleanup = std::async(std::launch::async, [&] {
+        started.set_value();
+        ClearInvalidHandlesForTesting(service);
+    });
+    started_future.wait();
+    EXPECT_EQ(cleanup.wait_for(std::chrono::milliseconds(100)),
+              std::future_status::timeout);
+    snapshot_lock.unlock();
+    ASSERT_EQ(cleanup.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    cleanup.get();
+}
+
 TEST_F(MasterServiceHATest, RemountMakesRestoredMemoryReplicaReady) {
     MasterService service(
         MasterServiceConfig::builder().set_enable_ha(false).build());
@@ -646,8 +1972,11 @@ TEST_F(MasterServiceHATest, RemountMakesRestoredMemoryReplicaReady) {
     second_object.metadata.replicas.front()
         .get_memory_descriptor()
         .buffer_descriptor.buffer_address_ = kDefaultSegmentBase + 4096;
-    service.RestoreFromStandbySnapshot({first_object, second_object}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    ASSERT_TRUE(
+        service
+            .RestoreFromStandbySnapshot({first_object, second_object}, 7,
+                                        {MakeStandbyMemorySegment(endpoint)})
+            .has_value());
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
               2048);
@@ -689,10 +2018,10 @@ TEST_F(MasterServiceHATest, RemountMakesRestoredMemoryReplicaReady) {
                   .get_memory_descriptor()
                   .buffer_descriptor.buffer_address_,
               kDefaultSegmentBase + 4096);
-    EXPECT_EQ(SegmentAllocatedSizeForTesting(service, endpoint), 5120);
+    EXPECT_EQ(SegmentAllocatedSizeForTesting(service, endpoint), 2048);
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
-              5120);
+              2048);
 
     const std::string new_key = "post_remount_allocation";
     PutObjectOnSegment(service, generate_uuid(), new_key, endpoint);
@@ -705,12 +2034,12 @@ TEST_F(MasterServiceHATest, RemountMakesRestoredMemoryReplicaReady) {
               kDefaultSegmentBase + 1024);
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
-              6144);
+              3072);
 
     EraseObjectForTesting(service, kDefaultTenant, first_key);
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
-              5120);
+              2048);
     const std::string replacement_key = "post_remount_replacement";
     PutObjectOnSegment(service, generate_uuid(), replacement_key, endpoint);
     auto replacement =
@@ -722,7 +2051,7 @@ TEST_F(MasterServiceHATest, RemountMakesRestoredMemoryReplicaReady) {
               kDefaultSegmentBase);
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
-              6144);
+              3072);
 }
 
 TEST_F(MasterServiceHATest, RemountRestoresCachelibMemoryReplica) {
@@ -740,8 +2069,13 @@ TEST_F(MasterServiceHATest, RemountRestoresCachelibMemoryReplica) {
     object.metadata.replicas.front()
         .get_memory_descriptor()
         .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
-    service.RestoreFromStandbySnapshot({object}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    object.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.protocol_ = "rdma";
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {object}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
               64);
@@ -761,6 +2095,11 @@ TEST_F(MasterServiceHATest, RemountRestoresCachelibMemoryReplica) {
     ASSERT_TRUE(batch_after[0].has_value());
     EXPECT_FALSE(
         HasInvalidMemoryHandleForTesting(service, kDefaultTenant, key));
+    EXPECT_EQ(batch_after[0]
+                  ->replicas.front()
+                  .get_memory_descriptor()
+                  .buffer_descriptor.protocol_,
+              "rdma");
     EXPECT_EQ(SegmentAllocatedSizeForTesting(service, endpoint), 64);
     EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size() -
                   metric_before,
@@ -780,21 +2119,54 @@ TEST_F(MasterServiceHATest, RemountRestoresCachelibMemoryReplica) {
     EXPECT_NE(new_descriptor.buffer_address_, old_descriptor.buffer_address_);
 }
 
-TEST_F(MasterServiceHATest, FailedRemountKeepsReplicaInvalidAndCanBeRetried) {
+TEST_F(MasterServiceHATest, RestoreRejectsOverlappingMemoryDescriptors) {
     MasterService service(
         MasterServiceConfig::builder().set_enable_ha(false).build());
 
     const std::string endpoint = "standby_retry_remount_segment";
-    auto first = MakeStandbyObject("standby_retry_first", endpoint);
-    auto conflicting = MakeStandbyObject("standby_retry_conflict", endpoint);
+    auto first = MakeStandbyObject("standby_overlap_first", endpoint);
+    auto conflicting = MakeStandbyObject("standby_overlap_second", endpoint);
     first.metadata.replicas.front()
         .get_memory_descriptor()
         .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
     conflicting.metadata.replicas.front()
         .get_memory_descriptor()
         .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
-    service.RestoreFromStandbySnapshot({first, conflicting}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    auto result = service.RestoreFromStandbySnapshot(
+        {first, conflicting}, 7, {MakeStandbyMemorySegment(endpoint)});
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant,
+                                     "standby_overlap_first"),
+              0);
+    EXPECT_EQ(ReplicaCountForTesting(service, kDefaultTenant,
+                                     "standby_overlap_second"),
+              0);
+}
+
+TEST_F(MasterServiceHATest, FailedRemountKeepsReplicaInvalidAndCanBeRetried) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+
+    const std::string endpoint = "standby_retry_remount_segment";
+    auto first = MakeStandbyObject("standby_retry_first", endpoint);
+    auto out_of_range =
+        MakeStandbyObject("standby_retry_out_of_range", endpoint);
+    first.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ = kDefaultSegmentBase;
+    out_of_range.metadata.replicas.front()
+        .get_memory_descriptor()
+        .buffer_descriptor.buffer_address_ =
+        kDefaultSegmentBase + kDefaultSegmentSize - 1;
+    ASSERT_TRUE(
+        service
+            .RestoreFromStandbySnapshot({first, out_of_range}, 7,
+                                        {MakeStandbyMemorySegment(endpoint)})
+            .has_value());
+    SetLeaseDeadlineForTesting(service, kDefaultTenant, "standby_retry_first",
+                               std::chrono::system_clock::time_point{});
 
     Segment segment = MakeSegment(endpoint);
     auto failed = service.ReMountSegment({segment}, generate_uuid());
@@ -809,6 +2181,9 @@ TEST_F(MasterServiceHATest, FailedRemountKeepsReplicaInvalidAndCanBeRetried) {
     ASSERT_EQ(batch_after_failure.size(), 1);
     ASSERT_FALSE(batch_after_failure[0].has_value());
     EXPECT_EQ(batch_after_failure[0].error(), ErrorCode::REPLICA_IS_NOT_READY);
+    EXPECT_EQ(
+        LeaseDeadlineForTesting(service, kDefaultTenant, "standby_retry_first"),
+        std::chrono::system_clock::time_point{});
     ReplicateConfig config;
     config.replica_num = 1;
     config.preferred_segments = {endpoint};
@@ -816,10 +2191,14 @@ TEST_F(MasterServiceHATest, FailedRemountKeepsReplicaInvalidAndCanBeRetried) {
                                        kDefaultTenant, 1024, config);
     EXPECT_FALSE(allocation.has_value());
 
-    EraseObjectForTesting(service, kDefaultTenant, "standby_retry_conflict");
+    EraseObjectForTesting(service, kDefaultTenant,
+                          "standby_retry_out_of_range");
     ASSERT_TRUE(service.ReMountSegment({segment}, generate_uuid()).has_value());
     EXPECT_FALSE(HasInvalidMemoryHandleForTesting(service, kDefaultTenant,
                                                   "standby_retry_first"));
+    EXPECT_GT(
+        LeaseDeadlineForTesting(service, kDefaultTenant, "standby_retry_first"),
+        std::chrono::system_clock::now());
     EXPECT_TRUE(service.GetReplicaList("standby_retry_first", kDefaultTenant)
                     .has_value());
 }
@@ -842,12 +2221,16 @@ TEST_F(MasterServiceHATest, MultiSegmentRemountFailurePublishesNeitherSegment) {
         object->metadata.replicas.front()
             .get_memory_descriptor()
             .buffer_descriptor.buffer_address_ =
-            kDefaultSegmentBase + kDefaultSegmentSize;
+            &bad_first == object
+                ? kDefaultSegmentBase + kDefaultSegmentSize - 1
+                : kDefaultSegmentBase + kDefaultSegmentSize + 4096;
     }
-    service.RestoreFromStandbySnapshot(
-        {good, bad_first, bad_second}, 7,
-        {MakeStandbyMemorySegment(good_endpoint),
-         MakeStandbyMemorySegment(bad_endpoint)});
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {good, bad_first, bad_second}, 7,
+                        {MakeStandbyMemorySegment(good_endpoint),
+                         MakeStandbyMemorySegment(bad_endpoint)})
+                    .has_value());
 
     Segment good_segment = MakeSegment(good_endpoint);
     Segment bad_segment =
@@ -880,8 +2263,10 @@ TEST_F(MasterServiceHATest, EmptyStandbySegmentCanRemount) {
     MasterService service(
         MasterServiceConfig::builder().set_enable_ha(false).build());
     const std::string endpoint = "standby_empty_segment";
-    service.RestoreFromStandbySnapshot({}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
 
     Segment segment = MakeSegment(endpoint);
     ASSERT_TRUE(service.ReMountSegment({segment}, generate_uuid()).has_value());
@@ -897,7 +2282,8 @@ TEST_F(MasterServiceHATest, RemountRejectsStandbySegmentNameMismatch) {
     const std::string endpoint = "standby_identity_endpoint";
     StandbySegmentInfo standby = MakeStandbyMemorySegment(endpoint);
     standby.segment_name = name;
-    service.RestoreFromStandbySnapshot({}, 7, {standby});
+    ASSERT_TRUE(
+        service.RestoreFromStandbySnapshot({}, 7, {standby}).has_value());
 
     Segment mismatched = MakeSegment("wrong_name");
     mismatched.te_endpoint = endpoint;
@@ -917,7 +2303,8 @@ TEST_F(MasterServiceHATest, RemountRejectsStandbySegmentEndpointMismatch) {
     const std::string endpoint = "standby_endpoint_value";
     StandbySegmentInfo standby = MakeStandbyMemorySegment(endpoint);
     standby.segment_name = name;
-    service.RestoreFromStandbySnapshot({}, 7, {standby});
+    ASSERT_TRUE(
+        service.RestoreFromStandbySnapshot({}, 7, {standby}).has_value());
 
     Segment mismatched = MakeSegment(name);
     mismatched.te_endpoint = "wrong_endpoint";
@@ -934,8 +2321,10 @@ TEST_F(MasterServiceHATest, RemountRejectsCxlForStandbyMemorySegment) {
     MasterService service(
         MasterServiceConfig::builder().set_enable_ha(false).build());
     const std::string endpoint = "standby_protocol_segment";
-    service.RestoreFromStandbySnapshot({}, 7,
-                                       {MakeStandbyMemorySegment(endpoint)});
+    ASSERT_TRUE(service
+                    .RestoreFromStandbySnapshot(
+                        {}, 7, {MakeStandbyMemorySegment(endpoint)})
+                    .has_value());
 
     Segment mismatched = MakeSegment(endpoint);
     mismatched.protocol = "cxl";
@@ -966,7 +2355,8 @@ TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesCxlBufferDescriptor) {
 
     StandbySegmentInfo segment = MakeStandbyMemorySegment(transport_endpoint);
     segment.segment_name = segment_name;
-    service.RestoreFromStandbySnapshot({object}, 7, {segment});
+    ASSERT_TRUE(
+        service.RestoreFromStandbySnapshot({object}, 7, {segment}).has_value());
 
     auto replicas = ReplicaDescriptorsForTesting(service, kDefaultTenant,
                                                  "standby_restore_cxl_key");
@@ -1045,12 +2435,12 @@ TEST_F(MasterServiceHATest, RestoreFromStandbyPreservesNoFBufferDescriptor) {
     StandbyObjectMetadata metadata;
     metadata.client_id = generate_uuid();
     metadata.size = size;
-    metadata.last_sequence_id = 1;
     metadata.replicas.push_back(std::move(replica));
     StandbyObjectEntry object{kDefaultTenant.value(), "standby_restore_nof_key",
                               std::move(metadata)};
 
-    service.RestoreFromStandbySnapshot({object}, 7, {});
+    ASSERT_TRUE(
+        service.RestoreFromStandbySnapshot({object}, 7, {}).has_value());
 
     auto replicas = ReplicaDescriptorsForTesting(service, kDefaultTenant,
                                                  "standby_restore_nof_key");
@@ -1089,10 +2479,83 @@ TEST_F(MasterServiceHATest, OplogExplicitEnableCreatesWriter) {
                       .build();
 
     MasterService service(config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
     EXPECT_TRUE(IsOpLogEnabled(service));
     EXPECT_TRUE(HasOpLogWriter(service));
     EXPECT_TRUE(HasBatchOpLogStorage(service));
+    std::string producer_view;
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST,
+              backend->Get(BuildProducerViewKey("oplog_explicit_enable"),
+                           producer_view));
+}
+
+TEST_F(MasterServiceHATest, FencedWriterClaimsConfiguredProducerView) {
+    constexpr ViewVersionId kProducerView = 7;
+    const std::string cluster_id = "fenced_writer_claim";
+    auto backend = std::make_shared<FakeBatchHaKvBackend>();
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_ha(true)
+                      .set_enable_oplog(true)
+                      .set_view_version(kProducerView)
+                      .set_cluster_id(cluster_id)
+                      .set_oplog_batch_max_entries(1)
+                      .build();
+
+    MasterService service(config);
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
+
+    std::string producer_view;
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Get(BuildProducerViewKey(cluster_id), producer_view));
+    EXPECT_EQ(std::to_string(kProducerView), producer_view);
+
+    ASSERT_TRUE(AppendVisibleForTesting(service, OpType::PUT_END, "default",
+                                        "fenced_writer_key", {})
+                    .has_value());
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 1, batch);
+
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildProducerViewKey(cluster_id), "8"));
+    ASSERT_TRUE(AppendVisibleForTesting(service, OpType::PUT_END, "default",
+                                        "stale_writer_key", {})
+                    .has_value());
+    std::optional<OrderedOpLogWriterTerminalState> terminal_state;
+    for (int i = 0; i < 100; ++i) {
+        terminal_state = GetWriterTerminalStateForTesting(service);
+        if (terminal_state.has_value()) {
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    ASSERT_TRUE(terminal_state.has_value());
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, terminal_state->error);
+    EXPECT_EQ(OrderedOpLogWriterTerminalReason::kFenced,
+              terminal_state->reason);
+}
+
+TEST_F(MasterServiceHATest, FencedWriterRejectsContendedProducerViewClaim) {
+    const std::string cluster_id = "fenced_writer_contention";
+    auto backend = std::make_shared<FakeBatchHaKvBackend>();
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildProducerViewKey(cluster_id), "8"));
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_ha(true)
+                      .set_enable_oplog(true)
+                      .set_view_version(7)
+                      .set_cluster_id(cluster_id)
+                      .build();
+
+    MasterService service(config);
+    EXPECT_EQ(
+        ErrorCode::ETCD_TRANSACTION_FAIL,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
+    EXPECT_FALSE(HasOpLogWriter(service));
 }
 
 TEST_F(MasterServiceHATest, OplogDoesNotStartWithUnsupportedHABackend) {
@@ -1311,7 +2774,9 @@ TEST_F(MasterServiceHATest, BatchRecordSubmissionHelpersUseOrderedWriter) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto visible = AppendVisibleForTesting(service, OpType::PUT_END, "tenant",
                                            "visible_key", "visible_payload");
@@ -1354,7 +2819,9 @@ TEST_F(MasterServiceHATest,
                               .set_enable_multi_tenants(false)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto appended = AppendFinalizeForTesting(service, OpType::REMOVE, "",
                                              "default_tenant_key", {}, nullptr);
@@ -1379,7 +2846,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_primary_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1422,7 +2891,9 @@ TEST_F(MasterServiceBatchRecordE2ETest, StandbyAppliesPrimaryBatchRecords) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_standby_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1456,7 +2927,9 @@ TEST_F(MasterServiceBatchRecordE2ETest, PromotionCatchesUpToDurablePrefix) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_promotion_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1504,7 +2977,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     backend->SetTxnError(ErrorCode::PERSISTENT_FAIL);
     auto first = AppendVisibleForTesting(service, OpType::PUT_END,
@@ -1539,7 +3014,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
     OpLogBatchStorage storage(cluster_id, *backend);
     OpLogBatchRecord batch;
 
@@ -1570,7 +3047,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_remove_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1612,7 +3091,9 @@ TEST_F(MasterServiceBatchRecordE2ETest, RemoveByRegexWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_regex_remove_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1657,7 +3138,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_remove_reserve_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1699,7 +3182,7 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted =
         PrepareSimpleSegment(service, "batch_e2e_remove_finalize_segment");
@@ -1711,6 +3194,7 @@ TEST_F(MasterServiceBatchRecordE2ETest,
     PutObjectOnSegment(service, mounted.client_id, key,
                        "batch_e2e_remove_finalize_segment");
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     backend->BlockTxn();
     ASSERT_TRUE(
@@ -1725,6 +3209,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 3, batch);
+    EXPECT_EQ(1024, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0, TenantUsedBytes(service));
 
     auto removed = service.ExistKey(key, kDefaultTenant);
     ASSERT_TRUE(removed.has_value());
@@ -1753,7 +3240,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_stale_finalize_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1813,12 +3302,16 @@ TEST_F(MasterServiceBatchRecordE2ETest,
             .set_cluster_id(cluster_id)
             .set_oplog_batch_max_entries(1)
             .set_enable_multi_tenants(true)
+            // Keep quota release under the durable callback's control.
+            .set_tenant_eviction_high_watermark_ratio(0.0)
             .set_tenant_quota_connector_type("file")
             .set_tenant_quota_connector_uri(
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_upsert_stale_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1884,7 +3377,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted =
         PrepareSimpleSegment(service, "batch_remove_stale_finalize_seg");
@@ -1947,7 +3442,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_partial_evict_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -1970,8 +3467,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
     ReadBatchEventually(storage, 3, batch);
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     ReadBatchEventually(storage, 4, batch);
 
     ASSERT_EQ(1u, batch.entries.size());
@@ -1996,7 +3494,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_evict_all_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2009,8 +3509,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
     ReadBatchEventually(storage, 2, batch);
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     ReadBatchEventually(storage, 3, batch);
 
     auto replicas = service.GetReplicaList(key, kDefaultTenant);
@@ -2034,7 +3535,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_e2e_processing_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2070,7 +3573,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted =
         PrepareSimpleSegment(service, "batch_e2e_offload_promotion_seg");
@@ -2139,7 +3644,9 @@ TEST_F(MasterServiceBatchRecordE2ETest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     OpLogBatchStorage storage(cluster_id, *backend);
     OpLogBatchRecord batch;
@@ -2186,7 +3693,9 @@ TEST_F(MasterServiceHATest, PutEndWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_put_end_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2204,6 +3713,7 @@ TEST_F(MasterServiceHATest, PutEndWritesBatchRecordOpLog) {
     ReplicateConfig config;
     config.replica_num = 1;
     config.preferred_segments = {"batch_put_end_segment"};
+    config.with_hard_pin = true;
     const std::string key = "batch_put_end_key";
     auto put_start =
         service.PutStart(mounted.client_id, key, kDefaultTenant, 1024, config);
@@ -2225,6 +3735,10 @@ TEST_F(MasterServiceHATest, PutEndWritesBatchRecordOpLog) {
     EXPECT_EQ(OpType::PUT_END, batch.entries[0].op_type);
     EXPECT_EQ(kDefaultTenant.value(), batch.entries[0].tenant_id);
     EXPECT_EQ(key, batch.entries[0].object_key);
+    MetadataPayload payload;
+    ASSERT_EQ(struct_pack::errc::ok,
+              struct_pack::deserialize_to(payload, batch.entries[0].payload));
+    EXPECT_TRUE(payload.hard_pinned.value_or(false));
     EXPECT_EQ(2u, batch.entries[0].sequence_id);
 
     DurablePrefix prefix;
@@ -2244,7 +3758,9 @@ TEST_F(MasterServiceHATest, PutEndVisibleBeforeBatchRecordDurable) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_put_visible_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2295,7 +3811,9 @@ TEST_F(MasterServiceHATest, CopyEndVisibleBeforeBatchRecordDurable) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto source = PrepareSimpleSegment(service, "batch_copy_visible_src");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2359,7 +3877,9 @@ TEST_F(MasterServiceHATest,
                               .set_eviction_high_watermark_ratio(1.0)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto source = PrepareSimpleSegment(service, "batch_move_visible_src",
                                        kDefaultSegmentBase, 1024);
@@ -2432,6 +3952,90 @@ TEST_F(MasterServiceHATest,
     EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
+TEST_F(MasterServiceHATest,
+       MoveFinalizeDuringSameSizeUpsertReleasesOnlyRemovedReplicaQuota) {
+    const std::string cluster_id = "test_batch_move_upsert_quota";
+    constexpr uint64_t object_size = 1024;
+    auto backend = std::make_shared<BlockingBatchHaKvBackend>();
+    auto service_config =
+        MasterServiceConfig::builder()
+            .set_default_kv_lease_ttl(50)
+            .set_enable_ha(true)
+            .set_enable_oplog(true)
+            .set_cluster_id(cluster_id)
+            .set_oplog_batch_max_entries(1)
+            .set_eviction_high_watermark_ratio(1.0)
+            .set_enable_multi_tenants(true)
+            .set_tenant_quota_connector_type("file")
+            .set_tenant_quota_connector_uri(WriteTenantPolicyFile(
+                {{kDefaultTenant.value(), 2 * object_size}}))
+            .build();
+    MasterService service(service_config);
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
+
+    const std::string source_name = "batch_move_upsert_quota_src";
+    const std::string target_name = "batch_move_upsert_quota_dst";
+    auto source = PrepareSimpleSegment(service, source_name,
+                                       kDefaultSegmentBase, object_size);
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 1, batch);
+    PrepareSimpleSegment(service, target_name,
+                         kDefaultSegmentBase + kDefaultSegmentSize,
+                         object_size);
+    ReadBatchEventually(storage, 2, batch);
+
+    const std::string key = "batch_move_upsert_quota_key";
+    PutObjectOnSegment(service, source.client_id, key, source_name,
+                       object_size);
+    ReadBatchEventually(storage, 3, batch);
+    ASSERT_TRUE(service
+                    .MoveStart(source.client_id, key, kDefaultTenant,
+                               source_name, target_name)
+                    .has_value());
+
+    backend->BlockTxn();
+    auto move_future = std::async(std::launch::async, [&] {
+        return service.MoveEnd(source.client_id, key, kDefaultTenant);
+    });
+    const auto status = move_future.wait_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(std::future_status::ready, status);
+    if (status != std::future_status::ready) {
+        backend->AllowTxn();
+    }
+    auto move_end = move_future.get();
+    ASSERT_TRUE(move_end.has_value()) << toString(move_end.error());
+    ASSERT_EQ(service.GetTenantQuotaSnapshot(kDefaultTenant)->charged_bytes,
+              2 * object_size);
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.preferred_segments = {target_name};
+    auto upsert = service.UpsertStart(source.client_id, key, kDefaultTenant,
+                                      object_size, config);
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+
+    backend->AllowTxn();
+    ReadBatchEventually(storage, 4, batch);
+    uint64_t charged_bytes = 2 * object_size;
+    for (int i = 0; i < 50 && charged_bytes == 2 * object_size; ++i) {
+        charged_bytes =
+            service.GetTenantQuotaSnapshot(kDefaultTenant)->charged_bytes;
+        if (charged_bytes == 2 * object_size) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+    }
+    ASSERT_EQ(charged_bytes, object_size);
+
+    auto upsert_end = service.UpsertEnd(source.client_id, key, kDefaultTenant,
+                                        ReplicaType::MEMORY);
+    ASSERT_TRUE(upsert_end.has_value()) << toString(upsert_end.error());
+    EXPECT_EQ(service.GetTenantQuotaSnapshot(kDefaultTenant)->charged_bytes,
+              object_size);
+}
+
 TEST_F(MasterServiceHATest,
        NotifyOffloadSuccessFallbackWritesBatchRecordOpLog) {
     const std::string cluster_id = "test_batch_record_offload_cluster";
@@ -2444,7 +4048,9 @@ TEST_F(MasterServiceHATest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_offload_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2515,7 +4121,9 @@ TEST_F(MasterServiceHATest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_offload_visible_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2570,48 +4178,39 @@ TEST_F(MasterServiceHATest, SegmentLifecycleWritesBatchRecordOpLogs) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
+    OpLogBatchStorage storage(cluster_id, *backend);
 
     const UUID client_id = generate_uuid();
     Segment mounted = MakeSegment("batch_segment_mount");
     ASSERT_TRUE(service.MountSegment(mounted, client_id).has_value());
+    OpLogBatchRecord mount_batch;
+    ReadBatchEventually(storage, 1, mount_batch);
 
     const UUID remount_client_id = generate_uuid();
     Segment remounted = MakeSegment("batch_segment_remount",
                                     kDefaultSegmentBase + kDefaultSegmentSize);
     ASSERT_TRUE(
         service.ReMountSegment({remounted}, remount_client_id).has_value());
+    OpLogBatchRecord remount_batch;
+    ReadBatchEventually(storage, 2, remount_batch);
 
     ASSERT_TRUE(service.UnmountSegment(mounted.id, client_id).has_value());
+    OpLogBatchRecord unmount_batch;
+    ReadBatchEventually(storage, 3, unmount_batch);
 
-    OpLogBatchStorage storage(cluster_id, *backend);
-    auto read_batch = [&](uint64_t batch_id) {
-        OpLogBatchRecord batch;
-        ErrorCode read_err = ErrorCode::ETCD_KEY_NOT_EXIST;
-        for (int i = 0; i < 50; ++i) {
-            read_err = storage.ReadBatch(batch_id, batch);
-            if (read_err == ErrorCode::OK) {
-                break;
-            }
-            std::this_thread::sleep_for(std::chrono::milliseconds(20));
-        }
-        EXPECT_EQ(ErrorCode::OK, read_err);
-        return batch;
-    };
-
-    auto mount_batch = read_batch(1);
     ASSERT_EQ(1u, mount_batch.entries.size());
     EXPECT_EQ(OpType::SEGMENT_MOUNT, mount_batch.entries[0].op_type);
     EXPECT_EQ(1u, mount_batch.entries[0].sequence_id);
     EXPECT_FALSE(mount_batch.entries[0].payload.empty());
 
-    auto remount_batch = read_batch(2);
     ASSERT_EQ(1u, remount_batch.entries.size());
     EXPECT_EQ(OpType::SEGMENT_MOUNT, remount_batch.entries[0].op_type);
     EXPECT_EQ(2u, remount_batch.entries[0].sequence_id);
     EXPECT_FALSE(remount_batch.entries[0].payload.empty());
 
-    auto unmount_batch = read_batch(3);
     ASSERT_EQ(1u, unmount_batch.entries.size());
     EXPECT_EQ(OpType::SEGMENT_UNMOUNT, unmount_batch.entries[0].op_type);
     EXPECT_EQ(3u, unmount_batch.entries[0].sequence_id);
@@ -2629,7 +4228,9 @@ TEST_F(MasterServiceHATest, NotifyPromotionSuccessWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     const auto mounted = PrepareSimpleSegment(service, "batch_promotion_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2687,7 +4288,9 @@ TEST_F(MasterServiceHATest,
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     const auto mounted =
         PrepareSimpleSegment(service, "batch_promotion_visible_seg");
@@ -2742,7 +4345,9 @@ TEST_F(MasterServiceHATest, RemoveWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_remove_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2780,7 +4385,7 @@ TEST_F(MasterServiceHATest, RemoveHidesBeforeDurableAndReleasesAfterFinalize) {
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted = PrepareSimpleSegment(service, "batch_remove_finalize_seg");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2791,6 +4396,7 @@ TEST_F(MasterServiceHATest, RemoveHidesBeforeDurableAndReleasesAfterFinalize) {
     PutObjectOnSegment(service, mounted.client_id, key,
                        "batch_remove_finalize_seg");
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     backend->BlockTxn();
     ASSERT_TRUE(
@@ -2806,15 +4412,14 @@ TEST_F(MasterServiceHATest, RemoveHidesBeforeDurableAndReleasesAfterFinalize) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 3, batch);
+    EXPECT_EQ(1024, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0, TenantUsedBytes(service));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key = "after_remove_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(mounted.client_id, "after_remove_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
 TEST_F(MasterServiceHATest, BatchRemoveWritesBatchRecordOpLog) {
@@ -2828,7 +4433,9 @@ TEST_F(MasterServiceHATest, BatchRemoveWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_remove_many_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2868,7 +4475,7 @@ TEST_F(MasterServiceHATest, BatchRemoveFinalizesEachObjectAfterDurable) {
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted =
         PrepareSimpleSegment(service, "batch_remove_finalize_segment");
@@ -2880,6 +4487,7 @@ TEST_F(MasterServiceHATest, BatchRemoveFinalizesEachObjectAfterDurable) {
     PutObjectOnSegment(service, mounted.client_id, key,
                        "batch_remove_finalize_segment");
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     backend->BlockTxn();
     auto results = service.BatchRemove({key}, kDefaultTenant, /*force=*/true);
@@ -2896,16 +4504,14 @@ TEST_F(MasterServiceHATest, BatchRemoveFinalizesEachObjectAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 3, batch);
+    EXPECT_EQ(1024, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0, TenantUsedBytes(service));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key =
-            "after_batch_remove_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(mounted.client_id, "after_batch_remove_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
 TEST_F(MasterServiceHATest, RemoveAllWritesBatchRecordOpLog) {
@@ -2919,7 +4525,9 @@ TEST_F(MasterServiceHATest, RemoveAllWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_remove_all_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2952,12 +4560,14 @@ TEST_F(MasterServiceHATest, RemoveAllFinalizesAfterDurable) {
             .set_cluster_id(cluster_id)
             .set_oplog_batch_max_entries(1)
             .set_enable_multi_tenants(true)
+            // Keep quota release under the durable callback's control.
+            .set_tenant_eviction_high_watermark_ratio(0.0)
             .set_tenant_quota_connector_type("file")
             .set_tenant_quota_connector_uri(
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted = PrepareSimpleSegment(service, "remove_all_finalize_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -2968,6 +4578,7 @@ TEST_F(MasterServiceHATest, RemoveAllFinalizesAfterDurable) {
     PutObjectOnSegment(service, mounted.client_id, key,
                        "remove_all_finalize_segment");
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     backend->BlockTxn();
     EXPECT_EQ(1, service.RemoveAll(kDefaultTenant, /*force=*/true));
@@ -2982,15 +4593,14 @@ TEST_F(MasterServiceHATest, RemoveAllFinalizesAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 3, batch);
+    EXPECT_EQ(1024, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0, TenantUsedBytes(service));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key = "after_remove_all_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(mounted.client_id, "after_remove_all_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
 TEST_F(MasterServiceHATest, BatchReplicaClearAllWritesBatchRecordOpLog) {
@@ -3004,7 +4614,9 @@ TEST_F(MasterServiceHATest, BatchReplicaClearAllWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_clear_all_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3041,7 +4653,9 @@ TEST_F(MasterServiceHATest, BatchReplicaClearSegmentWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_clear_seg1");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3095,7 +4709,7 @@ TEST_F(MasterServiceHATest, BatchReplicaClearAllReleasesAfterDurable) {
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted = PrepareSimpleSegment(service, "clear_all_finalize_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3106,6 +4720,7 @@ TEST_F(MasterServiceHATest, BatchReplicaClearAllReleasesAfterDurable) {
     PutObjectOnSegment(service, mounted.client_id, key,
                        "clear_all_finalize_segment");
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
     backend->BlockTxn();
@@ -3124,15 +4739,14 @@ TEST_F(MasterServiceHATest, BatchReplicaClearAllReleasesAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 3, batch);
+    EXPECT_EQ(1024, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0, TenantUsedBytes(service));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key = "after_clear_all_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(mounted.client_id, "after_clear_all_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
 TEST_F(MasterServiceHATest, BatchReplicaClearSegmentReleasesAfterDurable) {
@@ -3151,7 +4765,7 @@ TEST_F(MasterServiceHATest, BatchReplicaClearSegmentReleasesAfterDurable) {
                 WriteTenantPolicyFile({{kDefaultTenant.value(), 2048}}))
             .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     auto mounted = PrepareSimpleSegment(service, "clear_finalize_seg1");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3184,6 +4798,7 @@ TEST_F(MasterServiceHATest, BatchReplicaClearSegmentReleasesAfterDurable) {
     ASSERT_TRUE(
         service.CopyEnd(mounted.client_id, key, kDefaultTenant).has_value());
     ReadBatchEventually(storage, 4, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
     backend->BlockTxn();
@@ -3202,104 +4817,14 @@ TEST_F(MasterServiceHATest, BatchReplicaClearSegmentReleasesAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 5, batch);
+    EXPECT_EQ(2048, TenantUsedBytes(service));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(1024, TenantUsedBytes(service));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key =
-            "after_clear_segment_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
-}
-
-TEST_F(MasterServiceHATest, BatchEvictWritesBatchRecordOpLog) {
-    const std::string cluster_id = "test_batch_record_batch_evict_cluster";
-    auto backend = std::make_shared<FakeBatchHaKvBackend>();
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(50)
-                              .set_enable_ha(true)
-                              .set_enable_oplog(true)
-                              .set_cluster_id(cluster_id)
-                              .set_oplog_batch_max_entries(1)
-                              .build();
-    MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
-
-    auto mounted = PrepareSimpleSegment(service, "batch_evict_segment");
-    OpLogBatchStorage storage(cluster_id, *backend);
-    OpLogBatchRecord batch;
-    ReadBatchEventually(storage, 1, batch);
-
-    const std::string key = "batch_evict_key";
-    PutObjectOnSegment(service, mounted.client_id, key, "batch_evict_segment");
-    ReadBatchEventually(storage, 2, batch);
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(60));
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
-    ReadBatchEventually(storage, 3, batch);
-
-    ASSERT_EQ(1u, batch.entries.size());
-    EXPECT_EQ(OpType::REMOVE, batch.entries[0].op_type);
-    EXPECT_EQ(kDefaultTenant.value(), batch.entries[0].tenant_id);
-    EXPECT_EQ(key, batch.entries[0].object_key);
-    EXPECT_EQ(3u, batch.entries[0].sequence_id);
-}
-
-TEST_F(MasterServiceHATest, BatchEvictReleasesMemoryAfterDurable) {
-    const std::string cluster_id = "test_batch_record_batch_evict_finalize";
-    auto backend = std::make_shared<BlockingBatchHaKvBackend>();
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_default_kv_lease_ttl(50)
-            .set_enable_ha(true)
-            .set_enable_oplog(true)
-            .set_cluster_id(cluster_id)
-            .set_oplog_batch_max_entries(1)
-            .set_enable_multi_tenants(true)
-            .set_tenant_quota_connector_type("file")
-            .set_tenant_quota_connector_uri(
-                WriteTenantPolicyFile({{kDefaultTenant.value(), 1024}}))
-            .build();
-    MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
-
-    auto mounted = PrepareSimpleSegment(service, "batch_evict_finalize_seg");
-    OpLogBatchStorage storage(cluster_id, *backend);
-    OpLogBatchRecord batch;
-    ReadBatchEventually(storage, 1, batch);
-
-    const std::string key = "batch_evict_finalize_key";
-    PutObjectOnSegment(service, mounted.client_id, key,
-                       "batch_evict_finalize_seg");
-    ReadBatchEventually(storage, 2, batch);
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(60));
-    backend->BlockTxn();
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
-    EXPECT_FALSE(service.GetReplicaList(key, kDefaultTenant).has_value());
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    const std::string before_finalize_key = "before_batch_evict_finalize_key";
-    auto before_finalize = service.PutStart(
-        mounted.client_id, before_finalize_key, kDefaultTenant, 1024, config);
-    EXPECT_FALSE(before_finalize.has_value());
-
-    backend->AllowTxn();
-    ReadBatchEventually(storage, 3, batch);
-
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key = "after_batch_evict_finalize_key";
-        auto after_finalize =
-            service.PutStart(mounted.client_id, after_finalize_key,
-                             kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(mounted.client_id, "after_clear_segment_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 
 TEST_F(MasterServiceHATest, EvictDiskReplicaWritesBatchRecordOpLog) {
@@ -3313,7 +4838,9 @@ TEST_F(MasterServiceHATest, EvictDiskReplicaWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto mounted = PrepareSimpleSegment(service, "batch_disk_evict_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3360,7 +4887,7 @@ TEST_F(MasterServiceHATest, EvictDiskReplicaReleasesLocalDiskAfterDurable) {
                               .set_enable_offload(true)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     const std::string segment_name = "batch_disk_evict_finalize_segment";
     auto mounted = PrepareSimpleSegment(service, segment_name);
@@ -3383,6 +4910,7 @@ TEST_F(MasterServiceHATest, EvictDiskReplicaReleasesLocalDiskAfterDurable) {
                                 local_disk_replica)
                     .has_value());
     ReadBatchEventually(storage, 3, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
     SetLocalDiskUsedBytesForTesting(service, mounted.client_id, 1024);
 
     backend->BlockTxn();
@@ -3402,6 +4930,8 @@ TEST_F(MasterServiceHATest, EvictDiskReplicaReleasesLocalDiskAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 4, batch);
+    EXPECT_EQ(1024, GetLocalDiskUsedBytesForTesting(service, segment_name));
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
     EXPECT_EQ(0, GetLocalDiskUsedBytesForTesting(service, segment_name));
 }
 
@@ -3417,7 +4947,9 @@ TEST_F(MasterServiceHATest, NoFBatchEvictWritesBatchRecordOpLog) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     NoFSegment nof_segment =
         MakeNoFSegment("batch_nof_evict_segment", "batch_nof_evict_endpoint");
@@ -3439,8 +4971,9 @@ TEST_F(MasterServiceHATest, NoFBatchEvictWritesBatchRecordOpLog) {
     ReadBatchEventually(storage, 1, batch);
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
-    service.RunNoFBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                       /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunNoFBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     ReadBatchEventually(storage, 2, batch);
 
     ASSERT_EQ(1u, batch.entries.size());
@@ -3462,7 +4995,7 @@ TEST_F(MasterServiceHATest, NoFBatchEvictReleasesNoFSpaceAfterDurable) {
                               .set_oplog_batch_max_entries(1)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    auto* writer = InstallGatedWriter(service, backend);
 
     NoFSegment nof_segment = MakeNoFSegment("batch_nof_evict_finalize_segment",
                                             "batch_nof_evict_finalize_endpoint",
@@ -3482,11 +5015,13 @@ TEST_F(MasterServiceHATest, NoFBatchEvictReleasesNoFSpaceAfterDurable) {
     OpLogBatchStorage storage(cluster_id, *backend);
     OpLogBatchRecord batch;
     ReadBatchEventually(storage, 1, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
 
     std::this_thread::sleep_for(std::chrono::milliseconds(60));
     backend->BlockTxn();
-    service.RunNoFBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                       /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunNoFBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     EXPECT_FALSE(service.GetReplicaList(key, kDefaultTenant).has_value());
 
     const std::string before_finalize_key =
@@ -3497,18 +5032,208 @@ TEST_F(MasterServiceHATest, NoFBatchEvictReleasesNoFSpaceAfterDurable) {
 
     backend->AllowTxn();
     ReadBatchEventually(storage, 2, batch);
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
 
-    if (!before_finalize.has_value()) {
-        const std::string after_finalize_key =
-            "after_batch_nof_evict_finalize_key";
-        auto after_finalize = service.PutStart(client_id, after_finalize_key,
-                                               kDefaultTenant, 1024, config);
-        EXPECT_TRUE(after_finalize.has_value())
-            << toString(after_finalize.error());
-    }
+    auto after_finalize =
+        service.PutStart(client_id, "after_batch_nof_evict_finalize_key",
+                         kDefaultTenant, 1024, config);
+    EXPECT_TRUE(after_finalize.has_value()) << toString(after_finalize.error());
 }
 #endif
 
+TEST_F(MasterServiceHATest,
+       BatchEvictQueueSaturationDoesNotRequestAnotherPass) {
+    const std::string cluster_id = "test_batch_evict_reservation_failure";
+    auto backend = std::make_shared<FakeBatchHaKvBackend>();
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(50)
+                              .set_enable_ha(true)
+                              .set_enable_oplog(true)
+                              .set_cluster_id(cluster_id)
+                              .set_oplog_batch_max_entries(1)
+                              .set_eviction_ratio(0.0)
+                              .build();
+    MasterService service(service_config);
+    auto* writer = InstallGatedWriter(service, backend);
+
+    auto mounted = PrepareSimpleSegment(service, "batch_evict_reserve_segment");
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 1, batch);
+
+    const std::string first_key = "batch_evict_reserve_first";
+    const std::string second_key = "batch_evict_reserve_second";
+    PutObjectOnSegment(service, mounted.client_id, first_key,
+                       "batch_evict_reserve_segment");
+    ReadBatchEventually(storage, 2, batch);
+    PutObjectOnSegment(service, mounted.client_id, second_key,
+                       "batch_evict_reserve_segment");
+    ReadBatchEventually(storage, 3, batch);
+    ASSERT_TRUE(writer->PauseCallbacksAfter(batch.last_seq));
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(60));
+    {
+        auto held_reservation = ReserveBatchSlotForTesting(service);
+        ASSERT_TRUE(held_reservation.has_value())
+            << toString(held_reservation.error());
+        SetNeedMemEvictionForTesting(service, true);
+
+        ::testing::internal::CaptureStderr();
+        MasterServiceTestPeer(service).RunBatchEvictForTesting(
+            /*evict_ratio_target=*/0.5,
+            /*evict_ratio_lowerbound=*/0.5);
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+        const std::string warning = "OpLog reservation failed";
+        const auto first_warning = logs.find(warning);
+        ASSERT_NE(std::string::npos, first_warning) << logs;
+        EXPECT_EQ(std::string::npos,
+                  logs.find(warning, first_warning + warning.size()))
+            << logs;
+        EXPECT_NE(std::string::npos, logs.find("err=-1401")) << logs;
+        EXPECT_FALSE(NeedMemEvictionForTesting(service));
+        EXPECT_EQ(1u,
+                  ReplicaCountForTesting(service, kDefaultTenant, first_key));
+        EXPECT_EQ(1u,
+                  ReplicaCountForTesting(service, kDefaultTenant, second_key));
+    }
+
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    ReadBatchEventually(storage, 4, batch);
+    ReadBatchEventually(storage, 5, batch);
+    EXPECT_EQ(1u, ReplicaCountForTesting(service, kDefaultTenant, first_key));
+    EXPECT_EQ(1u, ReplicaCountForTesting(service, kDefaultTenant, second_key));
+
+    ASSERT_TRUE(writer->RunCallbacksThrough(batch.last_seq));
+    EXPECT_EQ(0u, ReplicaCountForTesting(service, kDefaultTenant, first_key));
+    EXPECT_EQ(0u, ReplicaCountForTesting(service, kDefaultTenant, second_key));
+}
+
+TEST_F(MasterServiceHATest,
+       BatchEvictStopsWithoutRetryWhenOpLogWriterIsFenced) {
+    const std::string cluster_id = "test_batch_evict_writer_fenced";
+    auto backend = std::make_shared<FailingBatchHaKvBackend>();
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(50)
+                              .set_enable_ha(true)
+                              .set_enable_oplog(true)
+                              .set_cluster_id(cluster_id)
+                              .set_oplog_batch_max_entries(1)
+                              .set_eviction_ratio(0.0)
+                              .build();
+    MasterService service(service_config);
+    auto* writer = InstallGatedWriter(service, backend);
+
+    auto mounted = PrepareSimpleSegment(service, "batch_evict_fenced_segment");
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 1, batch);
+    const std::string first_key = "batch_evict_fenced_first";
+    const std::string second_key = "batch_evict_fenced_second";
+    PutObjectOnSegment(service, mounted.client_id, first_key,
+                       "batch_evict_fenced_segment");
+    ReadBatchEventually(storage, 2, batch);
+    PutObjectOnSegment(service, mounted.client_id, second_key,
+                       "batch_evict_fenced_segment");
+    ReadBatchEventually(storage, 3, batch);
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(60));
+    backend->SetTxnError(ErrorCode::ETCD_TRANSACTION_FAIL);
+    ASSERT_TRUE(AppendVisibleForTesting(service, OpType::PUT_END,
+                                        kDefaultTenant,
+                                        "batch_evict_fence_writer", {})
+                    .has_value());
+    ASSERT_TRUE(backend->WaitForTxnCalls(1));
+    for (int i = 0; i < 100 && !writer->GetTerminalState().has_value(); ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    const auto terminal_state = writer->GetTerminalState();
+    ASSERT_TRUE(terminal_state.has_value());
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, terminal_state->error);
+    EXPECT_EQ(OrderedOpLogWriterTerminalReason::kFenced,
+              terminal_state->reason);
+
+    SetNeedMemEvictionForTesting(service, true);
+    ::testing::internal::CaptureStderr();
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+    const std::string warning = "OpLog reservation failed";
+    const auto first_warning = logs.find(warning);
+    ASSERT_NE(std::string::npos, first_warning) << logs;
+    EXPECT_EQ(std::string::npos,
+              logs.find(warning, first_warning + warning.size()))
+        << logs;
+    EXPECT_NE(std::string::npos, logs.find("err=-1002")) << logs;
+    EXPECT_FALSE(NeedMemEvictionForTesting(service));
+    for (const auto& key : {first_key, second_key}) {
+        auto replicas = service.GetReplicaList(key, kDefaultTenant);
+        ASSERT_TRUE(replicas.has_value())
+            << key << ": " << toString(replicas.error());
+        ASSERT_EQ(1u, replicas->replicas.size());
+        EXPECT_EQ(ReplicaStatus::COMPLETE, replicas->replicas.front().status);
+    }
+}
+
+TEST_F(MasterServiceHATest, BatchEvictCommitFailureRestoresRemovedReplicas) {
+    const std::string cluster_id = "test_batch_evict_commit_failure";
+    auto backend = std::make_shared<FakeBatchHaKvBackend>();
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(50)
+                              .set_enable_ha(true)
+                              .set_enable_oplog(true)
+                              .set_cluster_id(cluster_id)
+                              .set_oplog_batch_max_entries(1)
+                              .set_eviction_ratio(0.0)
+                              .build();
+    MasterService service(service_config);
+    auto* writer = InstallRejectingWriter(service, backend);
+
+    auto mounted =
+        PrepareSimpleSegment(service, "batch_evict_commit_failure_segment");
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 1, batch);
+    const std::string first_key = "batch_evict_commit_failure_first";
+    const std::string second_key = "batch_evict_commit_failure_second";
+    PutObjectOnSegment(service, mounted.client_id, first_key,
+                       "batch_evict_commit_failure_segment");
+    ReadBatchEventually(storage, 2, batch);
+    PutObjectOnSegment(service, mounted.client_id, second_key,
+                       "batch_evict_commit_failure_segment");
+    ReadBatchEventually(storage, 3, batch);
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(60));
+    writer->RejectCommitsWith(ErrorCode::INVALID_PARAMS);
+    SetNeedMemEvictionForTesting(service, true);
+    ::testing::internal::CaptureStderr();
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_EQ(1u, writer->rejected_commits());
+    EXPECT_NE(std::string::npos, logs.find("OpLog persist failed")) << logs;
+    EXPECT_NE(std::string::npos, logs.find("err=-600")) << logs;
+    EXPECT_FALSE(NeedMemEvictionForTesting(service));
+    for (const auto& key : {first_key, second_key}) {
+        auto replicas = service.GetReplicaList(key, kDefaultTenant);
+        ASSERT_TRUE(replicas.has_value())
+            << key << ": " << toString(replicas.error());
+        ASSERT_EQ(1u, replicas->replicas.size());
+        EXPECT_EQ(ReplicaStatus::COMPLETE, replicas->replicas.front().status);
+    }
+
+    auto released_reservation = ReserveBatchSlotForTesting(service);
+    ASSERT_TRUE(released_reservation.has_value())
+        << toString(released_reservation.error());
+    auto full = ReserveBatchSlotForTesting(service);
+    ASSERT_FALSE(full.has_value());
+    EXPECT_EQ(ErrorCode::TASK_PENDING_LIMIT_EXCEEDED, full.error());
+}
+
 TEST_F(MasterServiceHATest, PutStartExpiredOverwriteWritesBatchRecordOpLog) {
     const std::string cluster_id =
         "test_batch_record_put_start_cleanup_cluster";
@@ -3523,7 +5248,9 @@ TEST_F(MasterServiceHATest, PutStartExpiredOverwriteWritesBatchRecordOpLog) {
                               .set_put_start_release_timeout_sec(2)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     [[maybe_unused]] const auto mounted =
         PrepareSimpleSegment(service, "batch_put_start_cleanup_segment");
@@ -3567,9 +5294,11 @@ TEST_F(MasterServiceHATest,
                               .set_put_start_release_timeout_sec(2)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
-    [[maybe_unused]] const auto mounted =
+    const auto mounted =
         PrepareSimpleSegment(service, "batch_discard_processing_segment");
     OpLogBatchStorage storage(cluster_id, *backend);
     OpLogBatchRecord batch;
@@ -3577,7 +5306,7 @@ TEST_F(MasterServiceHATest,
 
     ReplicateConfig config;
     config.replica_num = 1;
-    const UUID client_id = generate_uuid();
+    const UUID client_id = mounted.client_id;
     const std::string key = "batch_discard_processing_key";
     ASSERT_TRUE(service.PutStart(client_id, key, kDefaultTenant, 1024, config)
                     .has_value());
@@ -3590,8 +5319,9 @@ TEST_F(MasterServiceHATest,
     ReadBatchEventually(storage, 2, batch);
 
     std::this_thread::sleep_for(std::chrono::milliseconds(2100));
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     ReadBatchEventually(storage, 3, batch);
 
     ASSERT_EQ(1u, batch.entries.size());
@@ -3617,7 +5347,9 @@ TEST_F(MasterServiceHATest,
                               .set_put_start_release_timeout_sec(2)
                               .build();
     MasterService service(service_config);
-    ASSERT_EQ(ErrorCode::OK, service.SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        MasterServiceTestPeer(service).SetBatchOpLogBackendForTesting(backend));
 
     auto src = PrepareSimpleSegment(service, "batch_replication_src");
     OpLogBatchStorage storage(cluster_id, *backend);
@@ -3640,8 +5372,9 @@ TEST_F(MasterServiceHATest,
                     .has_value());
 
     std::this_thread::sleep_for(std::chrono::milliseconds(2100));
-    service.RunBatchEvictForTesting(/*evict_ratio_target=*/1.0,
-                                    /*evict_ratio_lowerbound=*/1.0);
+    MasterServiceTestPeer(service).RunBatchEvictForTesting(
+        /*evict_ratio_target=*/1.0,
+        /*evict_ratio_lowerbound=*/1.0);
     ReadBatchEventually(storage, 4, batch);
 
     ASSERT_EQ(1u, batch.entries.size());
diff --git a/mooncake-store/tests/ha/oplog/oplog_applier_test.cpp b/mooncake-store/tests/ha/oplog/oplog_applier_test.cpp
index 9bbc975230..4327e1e12d 100644
--- a/mooncake-store/tests/ha/oplog/oplog_applier_test.cpp
+++ b/mooncake-store/tests/ha/oplog/oplog_applier_test.cpp
@@ -43,10 +43,13 @@ OpLogEntry MakeEntry(uint64_t seq, OpType type, const std::string& key,
 // Helper function to create a valid struct_pack payload for PUT_END
 std::string MakeValidPayload(uint64_t client_id_first = 1,
                              uint64_t client_id_second = 2,
-                             uint64_t size = 1024) {
+                             uint64_t size = 1024, bool hard_pinned = false) {
     mooncake::MetadataPayload payload;
     payload.client_id = {client_id_first, client_id_second};
     payload.size = size;
+    if (hard_pinned) {
+        payload.hard_pinned = true;
+    }
     auto result = struct_pack::serialize(payload);
     return std::string(result.begin(), result.end());
 }
@@ -289,6 +292,17 @@ TEST_F(OpLogApplierTest, TestApplyPutEnd_ValidPayload) {
     EXPECT_EQ(1u, meta->client_id.first);
     EXPECT_EQ(2u, meta->client_id.second);
     EXPECT_EQ(2048u, meta->size);
+    EXPECT_FALSE(meta->hard_pinned.value_or(false));
+}
+
+TEST_F(OpLogApplierTest, TestApplyPutEnd_PreservesHardPinned) {
+    std::string payload = MakeValidPayload(1, 2, 2048, true);
+    OpLogEntry entry = MakeEntry(1, OpType::PUT_END, "key1", payload);
+
+    EXPECT_TRUE(applier_->ApplyOpLogEntry(entry));
+    auto meta = mock_metadata_store_->GetMetadata("key1");
+    ASSERT_TRUE(meta.has_value());
+    EXPECT_TRUE(meta->hard_pinned.value_or(false));
 }
 
 TEST_F(OpLogApplierTest, TestApplyPutEnd_InvalidPayload) {
diff --git a/mooncake-store/tests/ha/oplog/oplog_batch_auditor_test.cpp b/mooncake-store/tests/ha/oplog/oplog_batch_auditor_test.cpp
index f376d04bb3..7570ab3cd2 100644
--- a/mooncake-store/tests/ha/oplog/oplog_batch_auditor_test.cpp
+++ b/mooncake-store/tests/ha/oplog/oplog_batch_auditor_test.cpp
@@ -19,6 +19,10 @@ namespace {
 
 class RangeBackend : public HaKvBackend {
    public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
     explicit RangeBackend(std::vector<KvPair> values)
         : values_(std::move(values)) {}
 
diff --git a/mooncake-store/tests/ha/oplog/oplog_batch_codec_test.cpp b/mooncake-store/tests/ha/oplog/oplog_batch_codec_test.cpp
index 22a1bf8b64..f4c15523bf 100644
--- a/mooncake-store/tests/ha/oplog/oplog_batch_codec_test.cpp
+++ b/mooncake-store/tests/ha/oplog/oplog_batch_codec_test.cpp
@@ -127,6 +127,11 @@ TEST(OpLogBatchKeyLayoutTest, BuildsDurablePrefixKey) {
               BuildDurablePrefixKey("clusterA"));
 }
 
+TEST(OpLogBatchKeyLayoutTest, BuildsProducerViewKey) {
+    EXPECT_EQ("/oplog/clusterA/producer_view",
+              BuildProducerViewKey("clusterA"));
+}
+
 TEST(OpLogBatchKeyLayoutTest, BuildsBatchRangeBounds) {
     auto bounds = BuildBatchRecordRange("clusterA", 7);
     EXPECT_EQ("/oplog/clusterA/batches/00000000000000000008", bounds.begin_key);
@@ -144,6 +149,7 @@ TEST(OpLogBatchKeyLayoutTest, RejectsInvalidClusterId) {
     EXPECT_FALSE(reason.empty());
     EXPECT_TRUE(BuildBatchRecordKey("bad/cluster", 1).empty());
     EXPECT_TRUE(BuildDurablePrefixKey("bad/cluster").empty());
+    EXPECT_TRUE(BuildProducerViewKey("bad/cluster").empty());
     auto bounds = BuildBatchRecordRange("bad/cluster", 1);
     EXPECT_TRUE(bounds.begin_key.empty());
     EXPECT_TRUE(bounds.end_key.empty());
@@ -178,6 +184,52 @@ TEST(OpLogDurablePrefixCodecTest, RoundTripsNonZeroPrefix) {
     EXPECT_TRUE(reason.empty());
 }
 
+TEST(OpLogDurablePrefixCodecTest, PreservesCanonicalEncoding) {
+    const std::string encoded =
+        R"({"batch_id":9,"last_seq":1024,"schema_version":1})";
+
+    DurablePrefix prefix;
+    std::string reason;
+    ASSERT_TRUE(DecodeDurablePrefix(encoded, &prefix, &reason));
+    EXPECT_EQ(encoded, EncodeDurablePrefix(prefix));
+    EXPECT_TRUE(reason.empty());
+}
+
+TEST(OpLogDurablePrefixCodecTest, IgnoresDetachedProducerViewField) {
+    const std::string with_view =
+        R"({"batch_id":9,"last_seq":1024,"producer_view_version":7,"schema_version":1})";
+    const std::string canonical =
+        R"({"batch_id":9,"last_seq":1024,"schema_version":1})";
+
+    DurablePrefix prefix;
+    std::string reason;
+    ASSERT_TRUE(DecodeDurablePrefix(with_view, &prefix, &reason));
+    EXPECT_EQ(canonical, EncodeDurablePrefix(prefix));
+    EXPECT_TRUE(reason.empty());
+}
+
+TEST(OpLogDurablePrefixCodecTest, IgnoresUnknownFields) {
+    DurablePrefix prefix;
+    std::string reason;
+    ASSERT_TRUE(DecodeDurablePrefix(
+        R"({"batch_id":9,"last_seq":1024,"producer_view_version":7,"schema_version":1,"unknown":"ignored"})",
+        &prefix, &reason));
+    EXPECT_EQ(9u, prefix.batch_id);
+    EXPECT_EQ(1024u, prefix.last_seq);
+    EXPECT_TRUE(reason.empty());
+}
+
+TEST(OpLogDurablePrefixCodecTest, InvalidLastSeqLeavesOutputUnchanged) {
+    DurablePrefix prefix{.batch_id = 11, .last_seq = 22};
+    std::string reason;
+    EXPECT_FALSE(DecodeDurablePrefix(
+        R"({"batch_id":9,"last_seq":"invalid","schema_version":1})", &prefix,
+        &reason));
+    EXPECT_EQ(11u, prefix.batch_id);
+    EXPECT_EQ(22u, prefix.last_seq);
+    EXPECT_FALSE(reason.empty());
+}
+
 TEST(OpLogDurablePrefixCodecTest, RejectsMalformedPayload) {
     DurablePrefix out;
     std::string reason;
diff --git a/mooncake-store/tests/ha/oplog/oplog_batch_standby_reader_test.cpp b/mooncake-store/tests/ha/oplog/oplog_batch_standby_reader_test.cpp
index b2de07ba5a..4bac67e3ec 100644
--- a/mooncake-store/tests/ha/oplog/oplog_batch_standby_reader_test.cpp
+++ b/mooncake-store/tests/ha/oplog/oplog_batch_standby_reader_test.cpp
@@ -4,6 +4,7 @@
 #include <xxhash.h>
 
 #include <map>
+#include <functional>
 #include <string_view>
 #include <string>
 #include <vector>
@@ -18,6 +19,10 @@ namespace {
 
 class FakeHaKvBackend : public HaKvBackend {
    public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
     ErrorCode Get(std::string_view key, std::string& value) override {
         if (next_get_error_ != ErrorCode::OK) {
             auto error = next_get_error_;
@@ -37,6 +42,10 @@ class FakeHaKvBackend : public HaKvBackend {
     }
     ErrorCode Range(std::string_view begin_key, std::string_view end_key,
                     size_t limit, std::vector<KvPair>& kvs) override {
+        if (before_range) {
+            auto callback = std::move(before_range);
+            callback();
+        }
         if (next_range_error_ != ErrorCode::OK) {
             auto error = next_range_error_;
             next_range_error_ = ErrorCode::OK;
@@ -56,6 +65,7 @@ class FakeHaKvBackend : public HaKvBackend {
     ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
 
     int range_calls() const { return range_calls_; }
+    std::function<void()> before_range;
     void Erase(std::string_view key) { values_.erase(std::string(key)); }
     void FailNextGet(ErrorCode error) { next_get_error_ = error; }
     void FailNextRange(ErrorCode error) { next_range_error_ = error; }
@@ -94,6 +104,96 @@ OpLogBatchRecord MakeBatch(uint64_t batch_id, uint64_t first_seq,
 
 }  // namespace
 
+TEST(OpLogBatchStandbyReaderTest, CompactionFloorBoundariesAndDeletion) {
+    FakeHaKvBackend backend;
+    const std::string floor_key = "/oplog/clusterA/snapshot/compaction_floor";
+    backend.Put(BuildDurablePrefixKey("clusterA"),
+                EncodeDurablePrefix({.batch_id = 2, .last_seq = 2}));
+    backend.Put(BuildBatchRecordKey("clusterA", 2),
+                EncodeOpLogBatchRecord(MakeBatch(2, 2, 2)));
+    MockMetadataStore metadata;
+    OpLogApplier applier(&metadata, "clusterA");
+    applier.Recover(2);
+    OpLogBatchStandbyReader reader("clusterA", backend, applier);
+    ASSERT_EQ(ErrorCode::OK,
+              reader.SetBaselineCursor({.batch_id = 2, .last_seq = 2}));
+    EXPECT_EQ(ErrorCode::OK, reader.PollOnce().error);
+    for (const auto* value : {"1", "2", "3", "18446744073709551615"}) {
+        backend.Put(floor_key, value);
+        if (std::string(value) == "2") {
+            backend.Erase(BuildBatchRecordKey("clusterA", 2));
+        }
+        const auto poll = reader.PollOnce();
+        if (std::string(value) == "1" || std::string(value) == "2") {
+            EXPECT_EQ(OpLogBatchStandbyPollDisposition::OK, poll.disposition);
+        } else {
+            EXPECT_EQ(OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED,
+                      poll.disposition);
+            EXPECT_EQ(0u, poll.applied_entries);
+        }
+        EXPECT_EQ(3u, applier.GetExpectedSequenceId());
+    }
+    backend.Erase(floor_key);
+    backend.Put(BuildBatchRecordKey("clusterA", 2),
+                EncodeOpLogBatchRecord(MakeBatch(2, 2, 2)));
+    EXPECT_EQ(ErrorCode::OK, reader.PollOnce().error);
+}
+
+TEST(OpLogBatchStandbyReaderTest, InvalidFloorFailsClosed) {
+    for (const auto* value :
+         {"", "-1", "+1", " 1", "1 ", "1x", "18446744073709551616"}) {
+        SCOPED_TRACE(value);
+        FakeHaKvBackend backend;
+        backend.Put("/oplog/clusterA/snapshot/compaction_floor", value);
+        MockMetadataStore metadata;
+        OpLogApplier applier(&metadata, "clusterA");
+        OpLogBatchStandbyReader reader("clusterA", backend, applier);
+        EXPECT_EQ(OpLogBatchStandbyPollDisposition::FATAL,
+                  reader.PollOnce().disposition);
+    }
+}
+
+TEST(OpLogBatchStandbyReaderTest, FloorAdvancingDuringPollRequiresRebootstrap) {
+    FakeHaKvBackend backend;
+    backend.Put(BuildDurablePrefixKey("clusterA"),
+                EncodeDurablePrefix({.batch_id = 3, .last_seq = 3}));
+    backend.Put(BuildBatchRecordKey("clusterA", 3),
+                EncodeOpLogBatchRecord(MakeBatch(3, 3, 3)));
+    backend.before_range = [&] {
+        backend.Put("/oplog/clusterA/snapshot/compaction_floor", "2");
+    };
+    MockMetadataStore metadata;
+    OpLogApplier applier(&metadata, "clusterA");
+    applier.Recover(1);
+    OpLogBatchStandbyReader reader("clusterA", backend, applier);
+    ASSERT_EQ(ErrorCode::OK,
+              reader.SetBaselineCursor({.batch_id = 1, .last_seq = 1}));
+    const auto result = reader.PollOnce();
+    EXPECT_EQ(OpLogBatchStandbyPollDisposition::REBOOTSTRAP_REQUIRED,
+              result.disposition);
+    EXPECT_EQ(2u, result.compaction_floor);
+    EXPECT_EQ(0u, result.applied_entries);
+    EXPECT_EQ(2u, applier.GetExpectedSequenceId());
+}
+
+TEST(OpLogBatchStandbyReaderTest, FloorDoesNotHideUnknownSuffixGap) {
+    FakeHaKvBackend backend;
+    backend.Put("/oplog/clusterA/snapshot/compaction_floor", "1");
+    backend.Put(BuildDurablePrefixKey("clusterA"),
+                EncodeDurablePrefix({.batch_id = 3, .last_seq = 3}));
+    backend.Put(BuildBatchRecordKey("clusterA", 3),
+                EncodeOpLogBatchRecord(MakeBatch(3, 3, 3)));
+    MockMetadataStore metadata;
+    OpLogApplier applier(&metadata, "clusterA");
+    applier.Recover(1);
+    OpLogBatchStandbyReader reader("clusterA", backend, applier);
+    ASSERT_EQ(ErrorCode::OK,
+              reader.SetBaselineCursor({.batch_id = 1, .last_seq = 1}));
+    EXPECT_EQ(OpLogBatchStandbyPollDisposition::FATAL,
+              reader.PollOnce().disposition);
+    EXPECT_EQ(2u, applier.GetExpectedSequenceId());
+}
+
 TEST(OpLogBatchStandbyReaderTest, MissingPrefixWaitsWithoutLegacyFallback) {
     FakeHaKvBackend backend;
     MockMetadataStore metadata_store;
@@ -108,6 +208,28 @@ TEST(OpLogBatchStandbyReaderTest, MissingPrefixWaitsWithoutLegacyFallback) {
     EXPECT_EQ(1u, applier.GetExpectedSequenceId());
 }
 
+TEST(OpLogBatchStandbyReaderTest, ResumesAfterSnapshotBatchCursor) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildBatchRecordKey("clusterA", 2),
+                          EncodeOpLogBatchRecord(MakeBatch(2, 2, 2))));
+
+    MockMetadataStore metadata_store;
+    OpLogApplier applier(&metadata_store, "clusterA");
+    applier.Recover(1);
+    OpLogBatchStandbyReader reader("clusterA", backend, applier);
+    ASSERT_EQ(ErrorCode::OK,
+              reader.SetBaselineCursor({.batch_id = 1, .last_seq = 1}));
+
+    const auto result = reader.PollOnce();
+    EXPECT_EQ(ErrorCode::OK, result.error);
+    EXPECT_EQ(1u, result.applied_entries);
+    EXPECT_EQ(3u, applier.GetExpectedSequenceId());
+}
+
 TEST(OpLogBatchStandbyReaderTest, MissingPrefixAfterObservationFailsClosed) {
     FakeHaKvBackend backend;
     ASSERT_EQ(ErrorCode::OK,
@@ -269,12 +391,35 @@ TEST(OpLogBatchStandbyReaderTest, FullPageContinuesOnNextPoll) {
     auto first = reader.PollOnce(/*max_batches=*/2);
     ASSERT_EQ(ErrorCode::OK, first.error);
     EXPECT_EQ(2u, first.applied_entries);
+    EXPECT_EQ(2u, first.applied_batches);
     EXPECT_EQ(3u, applier.GetExpectedSequenceId());
+    EXPECT_FALSE(reader.GetLastAppliedDurablePrefix().has_value());
 
     auto second = reader.PollOnce(/*max_batches=*/2);
     ASSERT_EQ(ErrorCode::OK, second.error);
     EXPECT_EQ(1u, second.applied_entries);
+    EXPECT_EQ(1u, second.applied_batches);
     EXPECT_EQ(4u, applier.GetExpectedSequenceId());
+    auto applied_prefix = reader.GetLastAppliedDurablePrefix();
+    ASSERT_TRUE(applied_prefix.has_value());
+    EXPECT_EQ(3u, applied_prefix->batch_id);
+    EXPECT_EQ(3u, applied_prefix->last_seq);
+}
+
+TEST(OpLogBatchStandbyReaderTest, ReportsValidZeroBoundaryAsComplete) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    MockMetadataStore metadata_store;
+    OpLogApplier applier(&metadata_store, "clusterA");
+    OpLogBatchStandbyReader reader("clusterA", backend, applier);
+
+    ASSERT_EQ(ErrorCode::OK, reader.PollOnce().error);
+    auto applied_prefix = reader.GetLastAppliedDurablePrefix();
+    ASSERT_TRUE(applied_prefix.has_value());
+    EXPECT_EQ(0u, applied_prefix->batch_id);
+    EXPECT_EQ(0u, applied_prefix->last_seq);
 }
 
 TEST(OpLogBatchStandbyReaderTest, RejectsPrefixPointingIntoBatch) {
@@ -316,6 +461,10 @@ TEST(OpLogBatchStandbyReaderTest, AppliesExpandedEntriesInSequenceOrder) {
     ASSERT_EQ(ErrorCode::OK, result.error);
     EXPECT_EQ(3u, result.applied_entries);
     EXPECT_EQ(4u, applier.GetExpectedSequenceId());
+    auto applied_prefix = reader.GetLastAppliedDurablePrefix();
+    ASSERT_TRUE(applied_prefix.has_value());
+    EXPECT_EQ(2u, applied_prefix->batch_id);
+    EXPECT_EQ(3u, applied_prefix->last_seq);
 }
 
 TEST(OpLogBatchStandbyReaderTest, AcceptsFirstBatchAfterSnapshotBaseline) {
@@ -357,7 +506,9 @@ TEST(OpLogBatchStandbyReaderTest, FailsWhenLaterBatchHasSequenceGap) {
 
     EXPECT_NE(ErrorCode::OK, result.error);
     EXPECT_EQ(2u, result.applied_entries);
+    EXPECT_EQ(1u, result.applied_batches);
     EXPECT_EQ(3u, applier.GetExpectedSequenceId());
+    EXPECT_FALSE(reader.GetLastAppliedDurablePrefix().has_value());
 }
 
 TEST(OpLogBatchStandbyReaderTest, MissingBatchMarksReaderUnhealthy) {
diff --git a/mooncake-store/tests/ha/oplog/oplog_batch_storage_test.cpp b/mooncake-store/tests/ha/oplog/oplog_batch_storage_test.cpp
index c1df73d21a..337181087f 100644
--- a/mooncake-store/tests/ha/oplog/oplog_batch_storage_test.cpp
+++ b/mooncake-store/tests/ha/oplog/oplog_batch_storage_test.cpp
@@ -3,13 +3,22 @@
 #include <gtest/gtest.h>
 #include <xxhash.h>
 
+#include <unistd.h>
+
+#include <cstdlib>
+#include <functional>
+#include <limits>
 #include <map>
 #include <string>
+#include <thread>
 #include <vector>
 
+#include "etcd_helper.h"
+#include "ha/kv/etcd_ha_kv_backend.h"
 #include "ha/kv/ha_kv_backend.h"
 #include "ha/oplog/oplog_batch_codec.h"
 #include "ha/oplog/oplog_batch_types.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
 
 namespace mooncake::test {
 namespace {
@@ -63,6 +72,31 @@ class FakeHaKvBackend : public HaKvBackend {
 
     bool SupportsTxn() const override { return supports_txn_; }
 
+    ErrorCode DeleteRange(std::string_view begin_key,
+                          std::string_view end_key) override {
+        delete_ranges.push_back({std::string(begin_key), std::string(end_key)});
+        if (before_delete) {
+            auto callback = std::move(before_delete);
+            before_delete = nullptr;
+            callback();
+        }
+        size_t deleted = 0;
+        auto it = kvs_.lower_bound(std::string(begin_key));
+        while (it != kvs_.end() && it->first < end_key) {
+            if (deleted == delete_fail_after) {
+                return ErrorCode::ETCD_OPERATION_ERROR;
+            }
+            it = kvs_.erase(it);
+            ++deleted;
+        }
+        return delete_result;
+    }
+
+    std::vector<BatchRecordRange> delete_ranges;
+    std::function<void()> before_delete;
+    size_t delete_fail_after{std::numeric_limits<size_t>::max()};
+    ErrorCode delete_result{ErrorCode::OK};
+
     ErrorCode Txn(const KvTxn& txn) override {
         if (!supports_txn_) {
             return ErrorCode::INVALID_PARAMS;
@@ -90,6 +124,11 @@ class FakeHaKvBackend : public HaKvBackend {
         for (const auto& put : txn.puts) {
             kvs_[put.key] = put.value;
         }
+        if (next_committed_txn_error_ != ErrorCode::OK) {
+            ErrorCode err = next_committed_txn_error_;
+            next_committed_txn_error_ = ErrorCode::OK;
+            return err;
+        }
         return ErrorCode::OK;
     }
 
@@ -106,6 +145,9 @@ class FakeHaKvBackend : public HaKvBackend {
     }
     void FailNextRange(ErrorCode err) { next_range_error_ = err; }
     void FailNextTxn(ErrorCode err) { next_txn_error_ = err; }
+    void FailNextCommittedTxn(ErrorCode err) {
+        next_committed_txn_error_ = err;
+    }
     const std::vector<size_t>& range_limits() const { return range_limits_; }
 
    private:
@@ -119,6 +161,7 @@ class FakeHaKvBackend : public HaKvBackend {
     ErrorCode next_get_key_error_{ErrorCode::OK};
     ErrorCode next_range_error_{ErrorCode::OK};
     ErrorCode next_txn_error_{ErrorCode::OK};
+    ErrorCode next_committed_txn_error_{ErrorCode::OK};
     std::vector<size_t> range_limits_;
 };
 
@@ -169,6 +212,133 @@ TEST(OpLogBatchStorageTest, InitializesEmptyNamespaceAtZero) {
     EXPECT_EQ(prefix.last_seq, stored.last_seq);
 }
 
+TEST(OpLogBatchStorageTest, ResolvesCommittedInitTxnError) {
+    FakeHaKvBackend backend;
+    backend.FailNextCommittedTxn(ErrorCode::ETCD_OPERATION_ERROR);
+    OpLogBatchStorage storage("clusterA", backend);
+
+    DurablePrefix prefix;
+    EXPECT_EQ(ErrorCode::OK, storage.InitDurablePrefix(prefix));
+    EXPECT_EQ((DurablePrefix{.batch_id = 0, .last_seq = 0}), prefix);
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewCreatesIndependentKey) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST, storage.ValidateProducerView(7));
+    ASSERT_EQ(ErrorCode::OK, storage.ClaimProducerView(7));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(7));
+
+    std::string stored;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Get("/oplog/clusterA/producer_view", stored));
+    EXPECT_EQ("7", stored);
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST,
+              backend.Get("/oplog/clusterA/durable_prefix", stored));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewIsIdempotent) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::OK, storage.ClaimProducerView(7));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(7));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewAcceptsMaxView) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+    const auto max_view = std::numeric_limits<ViewVersionId>::max();
+
+    EXPECT_EQ(ErrorCode::OK, storage.ClaimProducerView(max_view));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(max_view));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewRejectsStaleView) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "8"));
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, storage.ClaimProducerView(7));
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              storage.ValidateProducerView(7));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(8));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewIgnoresDurablePrefixRace) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put("/oplog/clusterA/durable_prefix",
+                          EncodeDurablePrefix({.batch_id = 1, .last_seq = 3})));
+    backend.CreateBeforeNextTxn(
+        "/oplog/clusterA/durable_prefix",
+        EncodeDurablePrefix({.batch_id = 2, .last_seq = 6}));
+    OpLogBatchStorage storage("clusterA", backend);
+
+    ASSERT_EQ(ErrorCode::OK, storage.ClaimProducerView(8));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(8));
+    DurablePrefix prefix;
+    ASSERT_EQ(ErrorCode::OK, storage.ReadDurablePrefix(prefix));
+    EXPECT_EQ((DurablePrefix{.batch_id = 2, .last_seq = 6}), prefix);
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewLosesRaceToNewerView) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    backend.CreateBeforeNextTxn("/oplog/clusterA/producer_view", "9");
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, storage.ClaimProducerView(8));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(9));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewPropagatesBackendTxnError) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    backend.FailNextTxn(ErrorCode::ETCD_OPERATION_ERROR);
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR, storage.ClaimProducerView(8));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(7));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewResolvesCommittedTxnError) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    backend.FailNextCommittedTxn(ErrorCode::ETCD_OPERATION_ERROR);
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::OK, storage.ClaimProducerView(8));
+    EXPECT_EQ(ErrorCode::OK, storage.ValidateProducerView(8));
+}
+
+TEST(OpLogBatchStorageTest, ClaimProducerViewRejectsZeroAndNonTxnBackend) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, storage.ClaimProducerView(0));
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, storage.ValidateProducerView(0));
+    backend.SetSupportsTxn(false);
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, storage.ClaimProducerView(1));
+}
+
+TEST(OpLogBatchStorageTest, RejectsMalformedProducerView) {
+    for (const std::string value :
+         {"", "0", "-1", "07", "7x", " 7", "8.0", "9223372036854775808"}) {
+        SCOPED_TRACE(value);
+        FakeHaKvBackend backend;
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put("/oplog/clusterA/producer_view", value));
+        OpLogBatchStorage storage("clusterA", backend);
+
+        EXPECT_EQ(ErrorCode::INTERNAL_ERROR, storage.ClaimProducerView(8));
+        EXPECT_EQ(ErrorCode::INTERNAL_ERROR, storage.ValidateProducerView(8));
+    }
+}
+
 TEST(OpLogBatchStorageTest, RejectsLegacyLatest) {
     FakeHaKvBackend backend;
     ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/latest", "42"));
@@ -190,6 +360,12 @@ TEST(OpLogBatchStorageTest, RejectsLegacyEntry) {
 
 TEST(OpLogBatchStorageTest, RejectsLegacySnapshotSidecar) {
     FakeHaKvBackend backend;
+    for (const std::string_view key :
+         {"compaction_floor", "fallback", "latest", "maintenance"}) {
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put("/oplog/clusterA/snapshot/" + std::string(key),
+                              "control"));
+    }
     ASSERT_EQ(ErrorCode::OK,
               backend.Put("/oplog/clusterA/snapshot/old/sequence_id", "42"));
     OpLogBatchStorage storage("clusterA", backend);
@@ -198,6 +374,21 @@ TEST(OpLogBatchStorageTest, RejectsLegacySnapshotSidecar) {
     EXPECT_NE(ErrorCode::OK, storage.InitDurablePrefix(prefix));
 }
 
+TEST(OpLogBatchStorageTest, AllowsBatchSnapshotControlKeys) {
+    FakeHaKvBackend backend;
+    for (const std::string_view key :
+         {"compaction_floor", "fallback", "latest", "maintenance"}) {
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put("/oplog/clusterA/snapshot/" + std::string(key),
+                              "control"));
+    }
+    OpLogBatchStorage storage("clusterA", backend);
+
+    DurablePrefix prefix;
+    EXPECT_EQ(ErrorCode::OK, storage.InitDurablePrefix(prefix));
+    EXPECT_EQ((DurablePrefix{.batch_id = 0, .last_seq = 0}), prefix);
+}
+
 TEST(OpLogBatchStorageTest, InitDurablePrefixFailsClosedWhenBatchesExist) {
     FakeHaKvBackend backend;
     ASSERT_EQ(ErrorCode::OK,
@@ -215,6 +406,9 @@ TEST(OpLogBatchStorageTest, RejectsInvalidClusterId) {
 
     DurablePrefix prefix;
     EXPECT_EQ(ErrorCode::INVALID_PARAMS, storage.InitDurablePrefix(prefix));
+    ViewVersionId producer_view = 0;
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS,
+              storage.ReadProducerView(producer_view));
 }
 
 TEST(OpLogBatchStorageTest, RereadsDurablePrefixWhenCreateIfAbsentLosesRace) {
@@ -379,6 +573,92 @@ TEST(OpLogBatchStorageTest, WriteBatchAndAdvancePrefixCommitsAtomically) {
     EXPECT_EQ(5u, prefix.last_seq);
 }
 
+TEST(OpLogBatchStorageTest, FencedAdvanceDoesNotModifyProducerView) {
+    FakeHaKvBackend backend;
+    const DurablePrefix expected_prefix{.batch_id = 1, .last_seq = 3};
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/durable_prefix",
+                                         EncodeDurablePrefix(expected_prefix)));
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    OpLogBatchStorage storage("clusterA", backend);
+
+    auto batch = MakeBatch(/*batch_id=*/2, /*first_seq=*/4, /*count=*/2);
+    ASSERT_EQ(ErrorCode::OK,
+              storage.WriteBatchAndAdvancePrefix(batch, expected_prefix, 7));
+
+    std::string encoded_prefix;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Get("/oplog/clusterA/durable_prefix", encoded_prefix));
+    DurablePrefix prefix;
+    ASSERT_TRUE(DecodeDurablePrefix(encoded_prefix, &prefix));
+    EXPECT_EQ(2u, prefix.batch_id);
+    EXPECT_EQ(5u, prefix.last_seq);
+    std::string producer_view;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Get("/oplog/clusterA/producer_view", producer_view));
+    EXPECT_EQ("7", producer_view);
+}
+
+TEST(OpLogBatchStorageTest, FencedAdvanceResolvesCommittedTxnError) {
+    FakeHaKvBackend backend;
+    const DurablePrefix expected_prefix{.batch_id = 1, .last_seq = 3};
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/durable_prefix",
+                                         EncodeDurablePrefix(expected_prefix)));
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "7"));
+    backend.FailNextCommittedTxn(ErrorCode::ETCD_OPERATION_ERROR);
+    OpLogBatchStorage storage("clusterA", backend);
+
+    auto batch = MakeBatch(/*batch_id=*/2, /*first_seq=*/4, /*count=*/2);
+    EXPECT_EQ(ErrorCode::OK,
+              storage.WriteBatchAndAdvancePrefix(batch, expected_prefix, 7));
+
+    OpLogBatchRecord stored_batch;
+    EXPECT_EQ(ErrorCode::OK, storage.ReadBatch(2, stored_batch));
+    EXPECT_EQ(EncodeOpLogBatchRecord(batch),
+              EncodeOpLogBatchRecord(stored_batch));
+}
+
+TEST(OpLogBatchStorageTest, HigherProducerViewFencesStaleWriter) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+
+    DurablePrefix prefix;
+    ASSERT_EQ(ErrorCode::OK, storage.InitDurablePrefix(prefix));
+    ASSERT_EQ(ErrorCode::OK, storage.ClaimProducerView(7));
+    ASSERT_EQ(ErrorCode::OK, storage.ClaimProducerView(8));
+
+    auto batch = MakeBatch(/*batch_id=*/1, /*first_seq=*/1, /*count=*/1);
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              storage.WriteBatchAndAdvancePrefix(batch, prefix, 7));
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST, storage.ReadBatch(1, batch));
+    EXPECT_EQ(ErrorCode::OK,
+              storage.WriteBatchAndAdvancePrefix(
+                  MakeBatch(/*batch_id=*/1, /*first_seq=*/1, /*count=*/1),
+                  prefix, 8));
+}
+
+TEST(OpLogBatchStorageTest, FencedAdvanceRequiresClaimedViewKey) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put("/oplog/clusterA/durable_prefix",
+                          EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              storage.WriteBatchAndAdvancePrefix(
+                  MakeBatch(/*batch_id=*/1, /*first_seq=*/1, /*count=*/1),
+                  {.batch_id = 0, .last_seq = 0}, 7));
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS,
+              storage.WriteBatchAndAdvancePrefix(
+                  MakeBatch(/*batch_id=*/1, /*first_seq=*/1, /*count=*/1),
+                  {.batch_id = 0, .last_seq = 0}, 0));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put("/oplog/clusterA/producer_view", "invalid"));
+    EXPECT_EQ(ErrorCode::INTERNAL_ERROR,
+              storage.WriteBatchAndAdvancePrefix(
+                  MakeBatch(/*batch_id=*/1, /*first_seq=*/1, /*count=*/1),
+                  {.batch_id = 0, .last_seq = 0}, 7));
+}
+
 TEST(OpLogBatchStorageTest, CompareFailureDoesNotWriteBatchOrAdvancePrefix) {
     FakeHaKvBackend backend;
     ASSERT_EQ(ErrorCode::OK,
@@ -418,6 +698,24 @@ TEST(OpLogBatchStorageTest, CompareFailureIsOkWhenTargetBatchAlreadyDurable) {
                                  batch, {.batch_id = 1, .last_seq = 3}));
 }
 
+TEST(OpLogBatchStorageTest, FencedBatchIsNotIdempotentSuccess) {
+    FakeHaKvBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put("/oplog/clusterA/durable_prefix",
+                          EncodeDurablePrefix({.batch_id = 2, .last_seq = 5})));
+    ASSERT_EQ(ErrorCode::OK, backend.Put("/oplog/clusterA/producer_view", "8"));
+    auto batch = MakeBatch(/*batch_id=*/2, /*first_seq=*/4, /*count=*/2);
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put("/oplog/clusterA/batches/00000000000000000002",
+                          EncodeOpLogBatchRecord(batch)));
+    backend.FailNextTxn(ErrorCode::ETCD_TRANSACTION_FAIL);
+    OpLogBatchStorage storage("clusterA", backend);
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              storage.WriteBatchAndAdvancePrefix(
+                  batch, {.batch_id = 1, .last_seq = 3}, 7));
+}
+
 TEST(OpLogBatchStorageTest, RejectsSkippedBatchId) {
     FakeHaKvBackend backend;
     ASSERT_EQ(ErrorCode::OK,
@@ -665,4 +963,180 @@ TEST(OpLogBatchStorageBackendErrorTest, TxnErrorDoesNotAdvanceDurablePrefix) {
     EXPECT_EQ(3u, prefix.last_seq);
 }
 
+TEST(OpLogBatchStorageDeleteTest, InclusiveBoundariesAndProtectedKeys) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+    const std::vector<uint64_t> ids{0, 1, 2, 9, 10, UINT64_MAX - 1, UINT64_MAX};
+    const std::vector<std::string> protected_keys{
+        BuildDurablePrefixKey("clusterA"),
+        BuildProducerViewKey("clusterA"),
+        ha::BuildBatchOpLogSnapshotLatestKey("clusterA"),
+        ha::BuildBatchOpLogSnapshotFallbackKey("clusterA"),
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey("clusterA"),
+        ha::BuildBatchOpLogSnapshotMaintenanceKey("clusterA"),
+        BuildBatchRecordKey("clusterAB", 1),
+        BuildBatchRecordKey("clusterB", 0)};
+    for (const auto& key : protected_keys) {
+        ASSERT_EQ(ErrorCode::OK, backend.Put(key, "protected"));
+    }
+    for (auto id : ids) {
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put(BuildBatchRecordKey("clusterA", id), "record"));
+    }
+    for (auto cutoff : ids) {
+        ASSERT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(cutoff));
+        ASSERT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(cutoff));
+        std::string value;
+        for (auto id : ids) {
+            EXPECT_EQ(
+                id <= cutoff ? ErrorCode::ETCD_KEY_NOT_EXIST : ErrorCode::OK,
+                backend.Get(BuildBatchRecordKey("clusterA", id), value));
+        }
+        for (const auto& key : protected_keys) {
+            ASSERT_EQ(ErrorCode::OK, backend.Get(key, value)) << key;
+            EXPECT_EQ("protected", value);
+        }
+    }
+}
+
+TEST(OpLogBatchStorageDeleteTest, EmptyNamespaceAndInvalidCluster) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+    EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(0));
+    EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(UINT64_MAX));
+    backend.delete_ranges.clear();
+    for (const auto* cluster : {"", "/", "a/b"}) {
+        OpLogBatchStorage invalid(cluster, backend);
+        EXPECT_EQ(ErrorCode::INVALID_PARAMS, invalid.DeleteBatchesThrough(1));
+    }
+    EXPECT_TRUE(backend.delete_ranges.empty());
+}
+
+TEST(OpLogBatchStorageDeleteTest, AppendInterleavedBeforeDeleteSurvives) {
+    FakeHaKvBackend backend;
+    OpLogBatchStorage storage("clusterA", backend);
+    DurablePrefix prefix;
+    ASSERT_EQ(ErrorCode::OK, storage.InitDurablePrefix(prefix));
+    ASSERT_EQ(ErrorCode::OK,
+              storage.WriteBatchAndAdvancePrefix(MakeBatch(1, 1, 1), prefix));
+    backend.before_delete = [&] {
+        EXPECT_EQ(ErrorCode::OK,
+                  storage.WriteBatchAndAdvancePrefix(
+                      MakeBatch(2, 2, 1), {.batch_id = 1, .last_seq = 1}));
+    };
+    ASSERT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(1));
+    OpLogBatchRecord record;
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST, storage.ReadBatch(1, record));
+    EXPECT_EQ(ErrorCode::OK, storage.ReadBatch(2, record));
+    ASSERT_EQ(ErrorCode::OK, storage.ReadDurablePrefix(prefix));
+    EXPECT_EQ(2u, prefix.batch_id);
+}
+
+TEST(OpLogBatchStorageDeleteTest, FailureDoesNotRetryOrExpandRange) {
+    // Before mutation, partial deletion, and committed-but-response-lost.
+    for (size_t fail_after : {0u, 1u, 3u}) {
+        FakeHaKvBackend backend;
+        OpLogBatchStorage storage("clusterA", backend);
+        for (uint64_t id = 1; id <= 4; ++id) {
+            ASSERT_EQ(
+                ErrorCode::OK,
+                backend.Put(BuildBatchRecordKey("clusterA", id), "record"));
+        }
+        backend.delete_fail_after = fail_after;
+        backend.delete_result = ErrorCode::ETCD_OPERATION_ERROR;
+        EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR,
+                  storage.DeleteBatchesThrough(3));
+        ASSERT_EQ(1u, backend.delete_ranges.size());
+        const auto attempted = backend.delete_ranges.front();
+        EXPECT_EQ(BuildBatchRecordKey("clusterA", 0), attempted.begin_key);
+        EXPECT_EQ(BuildBatchRecordKey("clusterA", 4), attempted.end_key);
+        std::string value;
+        for (uint64_t id = 1; id <= 4; ++id) {
+            EXPECT_EQ(id <= fail_after ? ErrorCode::ETCD_KEY_NOT_EXIST
+                                       : ErrorCode::OK,
+                      backend.Get(BuildBatchRecordKey("clusterA", id), value));
+        }
+        backend.delete_fail_after = std::numeric_limits<size_t>::max();
+        backend.delete_result = ErrorCode::OK;
+        EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(3));
+        ASSERT_EQ(2u, backend.delete_ranges.size());
+        EXPECT_EQ(attempted.begin_key, backend.delete_ranges.back().begin_key);
+        EXPECT_EQ(attempted.end_key, backend.delete_ranges.back().end_key);
+        EXPECT_EQ(ErrorCode::OK,
+                  backend.Get(BuildBatchRecordKey("clusterA", 4), value));
+    }
+}
+
+TEST(EtcdHaKvBackendDeleteTest, RejectsUnboundedAndReversedRanges) {
+    EtcdHaKvBackend backend;
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, backend.DeleteRange("", "z"));
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, backend.DeleteRange("a", ""));
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS,
+              backend.DeleteRange("a", std::string_view("\0", 1)));
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, backend.DeleteRange("z", "a"));
+    EXPECT_EQ(ErrorCode::OK, backend.DeleteRange("a", "a"));
+}
+
+#ifdef STORE_USE_ETCD
+TEST(EtcdHaKvBackendDeleteTest, RealEtcdDeleteWhileAppending) {
+    const char* endpoints = std::getenv("MOONCAKE_N10_TEST_ETCD_ENDPOINTS");
+    if (endpoints == nullptr) {
+        GTEST_SKIP()
+            << "Set MOONCAKE_N10_TEST_ETCD_ENDPOINTS for isolated etcd";
+    }
+    ASSERT_EQ(ErrorCode::OK, EtcdHelper::ConnectToEtcdStoreClient(endpoints));
+    EtcdHaKvBackend backend;
+    const std::string cluster = "n10-delete-" + std::to_string(getpid());
+    OpLogBatchStorage storage(cluster, backend);
+    DurablePrefix prefix;
+    ASSERT_EQ(ErrorCode::OK, storage.InitDurablePrefix(prefix));
+    ASSERT_EQ(ErrorCode::OK, storage.ClaimProducerView(1));
+    ASSERT_EQ(ErrorCode::OK, storage.WriteBatchAndAdvancePrefix(
+                                 MakeBatch(1, 1, 1), prefix, 1));
+    const std::vector<std::string> protected_keys{
+        ha::BuildBatchOpLogSnapshotLatestKey(cluster),
+        ha::BuildBatchOpLogSnapshotFallbackKey(cluster),
+        ha::BuildBatchOpLogSnapshotMaintenanceKey(cluster),
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey(cluster),
+        BuildBatchRecordKey(cluster + "-other", 1)};
+    for (const auto& key : protected_keys) {
+        ASSERT_EQ(ErrorCode::OK, backend.Put(key, "protected"));
+    }
+    std::thread append([&] {
+        for (uint64_t id = 2; id <= 16; ++id) {
+            EXPECT_EQ(ErrorCode::OK,
+                      storage.WriteBatchAndAdvancePrefix(
+                          MakeBatch(id, id, 1),
+                          {.batch_id = id - 1, .last_seq = id - 1}, 1));
+        }
+    });
+    for (int i = 0; i < 16; ++i) {
+        EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(1));
+    }
+    append.join();
+    OpLogBatchRecord record;
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST, storage.ReadBatch(1, record));
+    for (uint64_t id = 2; id <= 16; ++id) {
+        EXPECT_EQ(ErrorCode::OK, storage.ReadBatch(id, record));
+    }
+    ASSERT_EQ(ErrorCode::OK, storage.ReadDurablePrefix(prefix));
+    EXPECT_EQ(16u, prefix.batch_id);
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildBatchRecordKey(cluster, UINT64_MAX), "record"));
+    EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(UINT64_MAX));
+    EXPECT_EQ(ErrorCode::OK, storage.DeleteBatchesThrough(UINT64_MAX));
+    std::string value;
+    EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST,
+              backend.Get(BuildBatchRecordKey(cluster, UINT64_MAX), value));
+    EXPECT_EQ(ErrorCode::OK, storage.ReadDurablePrefix(prefix));
+    ViewVersionId view = 0;
+    EXPECT_EQ(ErrorCode::OK, storage.ReadProducerView(view));
+    EXPECT_EQ(1, view);
+    for (const auto& key : protected_keys) {
+        EXPECT_EQ(ErrorCode::OK, backend.Get(key, value));
+        EXPECT_EQ("protected", value);
+    }
+}
+#endif
+
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/oplog/ordered_oplog_writer_test.cpp b/mooncake-store/tests/ha/oplog/ordered_oplog_writer_test.cpp
index 29c2c011a7..b8d9a999be 100644
--- a/mooncake-store/tests/ha/oplog/ordered_oplog_writer_test.cpp
+++ b/mooncake-store/tests/ha/oplog/ordered_oplog_writer_test.cpp
@@ -3,17 +3,21 @@
 #include <gtest/gtest.h>
 #include <xxhash.h>
 
+#include <async_simple/coro/FutureAwaiter.h>
+#include <async_simple/coro/Lazy.h>
+#include <async_simple/executors/SimpleExecutor.h>
+
 #include <atomic>
 #include <chrono>
 #include <condition_variable>
+#include <deque>
+#include <future>
 #include <mutex>
 #include <string>
 #include <thread>
 #include <vector>
 
-#ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
 #include "ha_metric_manager.h"
-#endif
 
 namespace mooncake::test {
 namespace {
@@ -43,6 +47,7 @@ class FakeBatchWriter {
             return repeated_error_;
         }
         writes_.push_back({.batch = batch, .expected_prefix = expected_prefix});
+        if (writes_.size() == block_after_writes_) blocked_ = true;
         cv_.notify_all();
         return ErrorCode::OK;
     }
@@ -57,6 +62,16 @@ class FakeBatchWriter {
         return batches;
     }
 
+    std::vector<DurablePrefix> ExpectedPrefixes() const {
+        std::lock_guard<std::mutex> lock(mutex_);
+        std::vector<DurablePrefix> prefixes;
+        prefixes.reserve(writes_.size());
+        for (const auto& write : writes_) {
+            prefixes.push_back(write.expected_prefix);
+        }
+        return prefixes;
+    }
+
     bool WaitForWrites(size_t count, std::chrono::milliseconds timeout =
                                          std::chrono::milliseconds(1000)) {
         std::unique_lock<std::mutex> lock(mutex_);
@@ -90,6 +105,10 @@ class FakeBatchWriter {
         next_error_ = ErrorCode::OK;
         failures_remaining_ = 0;
     }
+    void BlockAfterWrites(size_t count) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        block_after_writes_ = count;
+    }
     void BlockWrites() {
         std::lock_guard<std::mutex> lock(mutex_);
         blocked_ = true;
@@ -123,6 +142,7 @@ class FakeBatchWriter {
     ErrorCode next_error_{ErrorCode::OK};
     ErrorCode repeated_error_{ErrorCode::OK};
     size_t failures_remaining_{0};
+    size_t block_after_writes_{0};
     bool blocked_{false};
     bool blocked_write_active_{false};
 };
@@ -155,6 +175,434 @@ bool WaitForMetric(const std::function<bool()>& predicate) {
 
 }  // namespace
 
+namespace {
+
+async_simple::coro::Lazy<ErrorCode> AwaitOnExecutor(
+    OrderedOpLogWriter& writer, uint64_t sequence,
+    std::promise<std::thread::id>& registered,
+    std::promise<std::thread::id>& resumed) {
+    auto future = writer.AwaitDurable(sequence);
+    registered.set_value(std::this_thread::get_id());
+    auto error = co_await std::move(future);
+    resumed.set_value(std::this_thread::get_id());
+    co_return error;
+}
+
+class OrderedOpLogWriterAwaitTest : public ::testing::Test {
+   protected:
+    void CreateWriter(OrderedOpLogWriterConfig config = {},
+                      OrderedOpLogWriter::TerminalCallback callback = {}) {
+        writer_ = std::make_unique<OrderedOpLogWriter>(
+            config,
+            [this](const OpLogBatchRecord& batch, const DurablePrefix& prefix) {
+                return storage_.Write(batch, prefix);
+            },
+            std::move(callback));
+    }
+
+    async_simple::Future<ErrorCode>& Await(uint64_t sequence) {
+        waiters_.push_back(writer_->AwaitDurable(sequence));
+        return waiters_.back();
+    }
+
+    void ExpectPending(async_simple::Future<ErrorCode>& waiter) {
+        // Storage is gated, so readiness can be checked without a timeout.
+        EXPECT_FALSE(waiter.hasResult());
+    }
+
+    void ExpectResult(async_simple::Future<ErrorCode>& waiter,
+                      ErrorCode expected) {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(5);
+        while (!waiter.hasResult() &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_TRUE(waiter.hasResult());
+        EXPECT_EQ(std::move(waiter).get(), expected);
+    }
+
+    void ExpectReadyResult(async_simple::Future<ErrorCode>& waiter,
+                           ErrorCode expected) {
+        ASSERT_TRUE(waiter.hasResult());
+        EXPECT_EQ(std::move(waiter).get(), expected);
+    }
+
+    void ReenterFromContinuation(async_simple::Future<ErrorCode>& waiter) {
+        waiter = std::move(waiter).thenValue([this](ErrorCode error) {
+            // These methods all acquire the writer mutex. Inline completion
+            // must not hold it, including terminal failure and Stop().
+            writer_->IsAccepting();
+            writer_->LastError();
+            writer_->GetTerminalState();
+            EXPECT_TRUE(writer_->AwaitDurable(0).hasResult());
+            return error;
+        });
+    }
+
+    void BlockCallback() {
+        std::unique_lock<std::mutex> lock(callback_mutex_);
+        callback_entered_ = true;
+        callback_cv_.notify_all();
+        callback_cv_.wait(lock, [this] { return callback_released_; });
+    }
+
+    bool WaitForCallback() {
+        std::unique_lock<std::mutex> lock(callback_mutex_);
+        return callback_cv_.wait_for(lock, std::chrono::seconds(5),
+                                     [this] { return callback_entered_; });
+    }
+
+    void ReleaseCallback() {
+        {
+            std::lock_guard<std::mutex> lock(callback_mutex_);
+            callback_released_ = true;
+        }
+        callback_cv_.notify_all();
+    }
+
+    void CheckTerminal(ErrorCode error, OrderedOpLogWriterTerminalReason reason,
+                       std::chrono::milliseconds retry_timeout = {}) {
+        storage_.BlockWrites();
+        storage_.FailNextWrites(100000, error);
+        CreateWriter({.initial_durable_prefix = {.batch_id = 1, .last_seq = 10},
+                      .retry_timeout = retry_timeout},
+                     [this](const OrderedOpLogWriterTerminalState&) {
+                         ++terminal_callbacks_;
+                         BlockCallback();
+                     });
+        auto reservation = writer_->Reserve();
+        ASSERT_TRUE(reservation.has_value());
+        auto pending =
+            writer_->Commit(std::move(*reservation), MakeEntry(), {});
+        ASSERT_TRUE(pending.has_value());
+        auto& first = Await(pending->sequence_id());
+        auto& later = Await(pending->sequence_id() + 1);
+        ReenterFromContinuation(first);
+        writer_->Start();
+        ASSERT_TRUE(storage_.WaitForBlockedWrite());
+        ExpectPending(first);
+        ExpectPending(later);
+        storage_.UnblockWrites();
+        ASSERT_TRUE(WaitForCallback());
+
+        // Awaiters must wake before the terminal callback is allowed to finish.
+        ExpectResult(first, error);
+        ExpectResult(later, error);
+        auto state = writer_->GetTerminalState();
+        ASSERT_TRUE(state.has_value());
+        EXPECT_EQ(state->reason, reason);
+        EXPECT_EQ(state->error, error);
+        EXPECT_EQ(state->durable_prefix.last_seq, 10);
+        EXPECT_EQ(terminal_callbacks_.load(), 1);
+        ExpectReadyResult(Await(pending->sequence_id()), error);
+        ExpectReadyResult(Await(10), ErrorCode::OK);
+        ReleaseCallback();
+        writer_->Stop();
+        ExpectReadyResult(Await(pending->sequence_id()), error);
+    }
+
+    void TearDown() override {
+        storage_.UnblockWrites();
+        ReleaseCallback();
+        if (writer_) writer_->Stop();
+    }
+
+    FakeBatchWriter storage_;
+    std::unique_ptr<OrderedOpLogWriter> writer_;
+    std::deque<async_simple::Future<ErrorCode>> waiters_;
+    std::atomic<int> terminal_callbacks_{0};
+    std::atomic<bool> callback_finished_{false};
+    std::mutex callback_mutex_;
+    std::condition_variable callback_cv_;
+    bool callback_entered_{false};
+    bool callback_released_{false};
+};
+
+}  // namespace
+
+TEST_F(OrderedOpLogWriterAwaitTest,
+       RestoredPrefixSucceedsBeforeStartAndAfterStop) {
+    CreateWriter({.initial_durable_prefix = {.batch_id = 2, .last_seq = 10}});
+    ExpectReadyResult(Await(0), ErrorCode::OK);
+    ExpectReadyResult(Await(1), ErrorCode::OK);
+    ExpectReadyResult(Await(10), ErrorCode::OK);
+    writer_->Stop();
+    ExpectReadyResult(Await(10), ErrorCode::OK);
+    ExpectReadyResult(Await(11), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, CommittedSequenceWaitsForStorageSuccess) {
+    storage_.BlockWrites();
+    CreateWriter();
+    writer_->Start();
+    auto reservation = writer_->Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    auto pending = writer_->Commit(std::move(*reservation), MakeEntry(), {});
+    ASSERT_TRUE(pending.has_value());
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+    auto& waiter = Await(pending->sequence_id());
+    ExpectPending(waiter);
+    storage_.UnblockWrites();
+    ExpectResult(waiter, ErrorCode::OK);
+    // Registration after advancement cannot miss an earlier notification.
+    ExpectReadyResult(Await(pending->sequence_id()), ErrorCode::OK);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, PrefixAdvancesInStages) {
+    storage_.BlockWrites();
+    storage_.BlockAfterWrites(1);
+    CreateWriter({.max_entries_per_batch = 3});
+    for (int i = 0; i < 3; ++i) {
+        auto reservation = writer_->Reserve();
+        ASSERT_TRUE(reservation.has_value());
+        ASSERT_TRUE(writer_->Commit(std::move(*reservation), MakeEntry(), {})
+                        .has_value());
+    }
+    auto& third = Await(3);
+    auto& second = Await(2);
+    auto& first = Await(1);
+    writer_->Start();
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+    ExpectPending(first);
+    storage_.UnblockWrites();
+    ExpectResult(first, ErrorCode::OK);
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+    ExpectPending(second);
+    ExpectPending(third);
+    storage_.UnblockWrites();
+    ExpectResult(second, ErrorCode::OK);
+    ExpectResult(third, ErrorCode::OK);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest,
+       NonRetryableFailureWakesBeforeTerminalCallback) {
+    CheckTerminal(ErrorCode::INVALID_PARAMS,
+                  OrderedOpLogWriterTerminalReason::kNonRetryableWriteError);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, FencingFailurePreservesTerminalError) {
+    CheckTerminal(ErrorCode::ETCD_TRANSACTION_FAIL,
+                  OrderedOpLogWriterTerminalReason::kFenced);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, RetryTimeoutWakesAllOutstandingWaiters) {
+    CheckTerminal(ErrorCode::PERSISTENT_FAIL,
+                  OrderedOpLogWriterTerminalReason::kRetryTimeout,
+                  std::chrono::milliseconds(5));
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, StopWakesUncoveredWaitersBeforeStart) {
+    CreateWriter();
+    auto& waiter = Await(1);
+    ReenterFromContinuation(waiter);
+    ExpectPending(waiter);
+    writer_->Stop();
+    ExpectResult(waiter, ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, StopWakesUncoveredWaitersAfterStart) {
+    CreateWriter();
+    writer_->Start();
+    auto& waiter = Await(1);
+    ReenterFromContinuation(waiter);
+    ExpectPending(waiter);
+    writer_->Stop();
+    ExpectResult(waiter, ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, DurableCallbackCompletionIsNotRequired) {
+    CreateWriter();
+    auto reservation = writer_->Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    auto pending = writer_->Commit(std::move(*reservation), MakeEntry(),
+                                   [this](const OpLogEntry&) {
+                                       BlockCallback();
+                                       callback_finished_ = true;
+                                   });
+    ASSERT_TRUE(pending.has_value());
+    auto& waiter = Await(pending->sequence_id());
+    writer_->Start();
+    ASSERT_TRUE(WaitForCallback());
+    ExpectResult(waiter, ErrorCode::OK);
+    EXPECT_FALSE(callback_finished_.load());
+    ReleaseCallback();
+    writer_->Stop();
+    EXPECT_TRUE(callback_finished_.load());
+    ExpectResult(Await(pending->sequence_id()), ErrorCode::OK);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, AllWaitersForSameSequenceWake) {
+    storage_.BlockWrites();
+    CreateWriter();
+    auto reservation = writer_->Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    auto pending = writer_->Commit(std::move(*reservation), MakeEntry(), {});
+    ASSERT_TRUE(pending.has_value());
+    for (int i = 0; i < 8; ++i) Await(pending->sequence_id());
+    writer_->Start();
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+    for (auto& waiter : waiters_) ExpectPending(waiter);
+    storage_.UnblockWrites();
+    for (auto& waiter : waiters_) ExpectResult(waiter, ErrorCode::OK);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, DurableContinuationCanReenterWriter) {
+    storage_.BlockWrites();
+    CreateWriter();
+    auto reservation = writer_->Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    ASSERT_TRUE(
+        writer_->Commit(std::move(*reservation), MakeEntry(), {}).has_value());
+    auto& waiter = Await(1);
+    ReenterFromContinuation(waiter);
+    writer_->Start();
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+    ExpectPending(waiter);
+    storage_.UnblockWrites();
+    ExpectResult(waiter, ErrorCode::OK);
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest, CompletesWaitersInSequenceOrder) {
+    storage_.BlockWrites();
+    CreateWriter({.max_entries_per_batch = 3});
+    for (int i = 0; i < 3; ++i) {
+        auto reservation = writer_->Reserve();
+        ASSERT_TRUE(reservation.has_value());
+        ASSERT_TRUE(writer_->Commit(std::move(*reservation), MakeEntry(), {})
+                        .has_value());
+    }
+    std::mutex mutex;
+    std::vector<uint64_t> completed;
+    for (uint64_t sequence : {3, 1, 2}) {
+        auto& waiter = Await(sequence);
+        waiter = std::move(waiter).thenValue([&, sequence](ErrorCode error) {
+            std::lock_guard<std::mutex> lock(mutex);
+            completed.push_back(sequence);
+            return error;
+        });
+    }
+    writer_->Start();
+    EXPECT_TRUE(storage_.WaitForBlockedWrite());
+    storage_.UnblockWrites();
+    for (auto& waiter : waiters_) ExpectResult(waiter, ErrorCode::OK);
+    writer_->Stop();
+    std::lock_guard<std::mutex> lock(mutex);
+    EXPECT_EQ(completed, (std::vector<uint64_t>{1, 2, 3}));
+}
+
+TEST_F(OrderedOpLogWriterAwaitTest,
+       OutstandingWaitAllowsOtherWorkOnSameExecutorThread) {
+    storage_.BlockWrites();
+    CreateWriter();
+    auto reservation = writer_->Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    ASSERT_TRUE(
+        writer_->Commit(std::move(*reservation), MakeEntry(), {}).has_value());
+    writer_->Start();
+    ASSERT_TRUE(storage_.WaitForBlockedWrite());
+
+    std::promise<std::thread::id> registered;
+    std::promise<std::thread::id> resumed;
+    std::promise<std::thread::id> other_work;
+    std::promise<ErrorCode> completed;
+    auto registered_future = registered.get_future();
+    auto resumed_future = resumed.get_future();
+    auto work_future = other_work.get_future();
+    auto completed_future = completed.get_future();
+    async_simple::executors::SimpleExecutor executor(1);
+    AwaitOnExecutor(*writer_, 1, registered, resumed)
+        .via(&executor)
+        .start([&](async_simple::Try<ErrorCode>&& result) {
+            if (result.hasError()) {
+                completed.set_exception(result.getException());
+            } else {
+                completed.set_value(result.value());
+            }
+        });
+    const auto registered_status =
+        registered_future.wait_for(std::chrono::seconds(5));
+    EXPECT_EQ(registered_status, std::future_status::ready);
+    EXPECT_TRUE(executor.schedule(
+        [&] { other_work.set_value(std::this_thread::get_id()); }));
+    const auto work_status = work_future.wait_for(std::chrono::seconds(5));
+    EXPECT_EQ(work_status, std::future_status::ready);
+    EXPECT_EQ(completed_future.wait_for(std::chrono::milliseconds(0)),
+              std::future_status::timeout);
+
+    // Always release storage and drain the writer before destroying executor,
+    // even if a non-blocking/scheduling assertion above failed.
+    storage_.UnblockWrites();
+    const auto completed_status =
+        completed_future.wait_for(std::chrono::seconds(5));
+    writer_->Stop();
+    EXPECT_EQ(completed_status, std::future_status::ready);
+    if (completed_status == std::future_status::ready) {
+        EXPECT_EQ(completed_future.get(), ErrorCode::OK);
+    }
+    if (registered_status == std::future_status::ready &&
+        work_status == std::future_status::ready) {
+        const auto executor_thread = registered_future.get();
+        EXPECT_EQ(work_future.get(), executor_thread);
+        if (resumed_future.wait_for(std::chrono::milliseconds(0)) ==
+            std::future_status::ready) {
+            EXPECT_EQ(resumed_future.get(), executor_thread);
+        } else {
+            ADD_FAILURE() << "durability coroutine did not resume";
+        }
+    }
+}
+
+TEST(OrderedOpLogWriterMetricsTest, RuntimeSnapshotTracksAdmission) {
+    OrderedOpLogWriter writer(
+        OrderedOpLogWriterConfig{.max_entries_per_batch = 2},
+        [](const OpLogBatchRecord&, const DurablePrefix&) {
+            return ErrorCode::OK;
+        });
+    writer.ActivateRuntimeMetrics();
+    auto snapshot = HAMetricManager::instance().get_writer_runtime();
+    EXPECT_TRUE(snapshot.accepting);
+    EXPECT_EQ(snapshot.waiting_slots, 0);
+
+    auto reservation = writer.Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    snapshot = HAMetricManager::instance().get_writer_runtime();
+    EXPECT_EQ(snapshot.waiting_slots, 1);
+    writer.Abort(std::move(*reservation));
+    snapshot = HAMetricManager::instance().get_writer_runtime();
+    EXPECT_EQ(snapshot.waiting_slots, 0);
+}
+
+TEST(OrderedOpLogWriterMetricsTest,
+     CandidateAndOldDestructorCannotOverwriteOwner) {
+    auto write = [](const OpLogBatchRecord&, const DurablePrefix&) {
+        return ErrorCode::OK;
+    };
+    auto old = std::make_unique<OrderedOpLogWriter>(
+        OrderedOpLogWriterConfig{
+            .initial_durable_prefix = {.batch_id = 1, .last_seq = 10}},
+        write);
+    old->ActivateRuntimeMetrics();
+    auto& metrics = HAMetricManager::instance();
+    {
+        OrderedOpLogWriter rejected({}, write);
+        EXPECT_EQ(metrics.get_writer_runtime().durable_sequence, 10);
+    }
+    EXPECT_TRUE(metrics.get_writer_runtime().accepting);
+    OrderedOpLogWriter replacement(
+        OrderedOpLogWriterConfig{
+            .initial_durable_prefix = {.batch_id = 2, .last_seq = 20}},
+        write);
+    EXPECT_EQ(metrics.get_writer_runtime().durable_sequence, 10);
+    replacement.ActivateRuntimeMetrics();
+    old->Stop();
+    old.reset();
+    EXPECT_TRUE(metrics.get_writer_runtime().accepting);
+    EXPECT_EQ(metrics.get_writer_runtime().durable_sequence, 20);
+    replacement.Stop();
+    EXPECT_FALSE(metrics.get_writer_runtime().accepting);
+}
+
 TEST(OrderedOpLogWriterAdmissionTest, AbortLeavesNoSequenceGap) {
     FakeBatchWriter storage;
     OrderedOpLogWriter writer(
@@ -211,7 +659,7 @@ TEST(OrderedOpLogWriterAdmissionTest, CommitAssignsContiguousSequences) {
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
 TEST(OrderedOpLogWriterMetricTest, RecordsDurabilityQueuesAndRetry) {
     FakeBatchWriter storage;
-    storage.FailNextWrites(1, ErrorCode::ETCD_TRANSACTION_FAIL);
+    storage.FailNextWrites(1, ErrorCode::PERSISTENT_FAIL);
     auto& metrics = HAMetricManager::instance();
     const auto batches_before =
         metrics.get_batch_record_durable_batches_total();
@@ -713,6 +1161,107 @@ TEST(OrderedOpLogWriterFailureTest, FirstStorageFailureStopsNewReservations) {
     writer.Stop();
 }
 
+TEST(OrderedOpLogWriterFailureTest, NonRetryableFailureLatchesTerminalState) {
+    FakeBatchWriter storage;
+    std::mutex mutex;
+    std::condition_variable cv;
+    int terminal_callbacks = 0;
+    std::optional<OrderedOpLogWriterTerminalState> callback_state;
+    OrderedOpLogWriter writer(
+        OrderedOpLogWriterConfig{.max_entries_per_batch = 2},
+        [&](const OpLogBatchRecord& batch,
+            const DurablePrefix& expected_prefix) {
+            return storage.Write(batch, expected_prefix);
+        },
+        [&](const OrderedOpLogWriterTerminalState& state) {
+            std::lock_guard<std::mutex> lock(mutex);
+            ++terminal_callbacks;
+            callback_state = state;
+            cv.notify_all();
+        });
+    writer.Start();
+
+    auto held = writer.Reserve();
+    auto failing = writer.Reserve();
+    ASSERT_TRUE(held.has_value());
+    ASSERT_TRUE(failing.has_value());
+    storage.FailNextWrite(ErrorCode::INVALID_PARAMS);
+    ASSERT_TRUE(
+        writer
+            .Commit(std::move(*failing), MakeEntry("fail"), [](const auto&) {})
+            .has_value());
+
+    {
+        std::unique_lock<std::mutex> lock(mutex);
+        ASSERT_TRUE(cv.wait_for(lock, std::chrono::seconds(1),
+                                [&] { return terminal_callbacks == 1; }));
+    }
+    const auto state = writer.GetTerminalState();
+    ASSERT_TRUE(state.has_value());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, state->error);
+    EXPECT_EQ(OrderedOpLogWriterTerminalReason::kNonRetryableWriteError,
+              state->reason);
+    EXPECT_EQ(0u, state->durable_prefix.batch_id);
+    EXPECT_EQ(0u, state->durable_prefix.last_seq);
+    EXPECT_NE(0u, state->occurred_at_ms);
+    ASSERT_TRUE(callback_state.has_value());
+    EXPECT_EQ(state->error, callback_state->error);
+    EXPECT_FALSE(writer.IsAccepting());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, writer.LastError());
+    auto reserve_after_terminal = writer.Reserve();
+    ASSERT_FALSE(reserve_after_terminal.has_value());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, reserve_after_terminal.error());
+
+    auto committed =
+        writer.Commit(std::move(*held), MakeEntry(), [](const auto&) {});
+    ASSERT_FALSE(committed.has_value());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, committed.error());
+    auto reused =
+        writer.Commit(std::move(*held), MakeEntry(), [](const auto&) {});
+    ASSERT_FALSE(reused.has_value());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, reused.error());
+    writer.Stop();
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS, writer.LastError());
+    const auto state_after_stop = writer.GetTerminalState();
+    ASSERT_TRUE(state_after_stop.has_value());
+    EXPECT_EQ(state->error, state_after_stop->error);
+    EXPECT_EQ(state->reason, state_after_stop->reason);
+    EXPECT_EQ(state->durable_prefix.batch_id,
+              state_after_stop->durable_prefix.batch_id);
+    EXPECT_EQ(state->durable_prefix.last_seq,
+              state_after_stop->durable_prefix.last_seq);
+    EXPECT_EQ(state->occurred_at_ms, state_after_stop->occurred_at_ms);
+    EXPECT_EQ(1, terminal_callbacks);
+}
+
+TEST(OrderedOpLogWriterFailureTest, TransactionConflictBecomesFencedTerminal) {
+    FakeBatchWriter storage;
+    OrderedOpLogWriter writer(
+        OrderedOpLogWriterConfig{.max_entries_per_batch = 1},
+        [&](const OpLogBatchRecord& batch,
+            const DurablePrefix& expected_prefix) {
+            return storage.Write(batch, expected_prefix);
+        });
+    writer.Start();
+
+    storage.FailNextWrite(ErrorCode::ETCD_TRANSACTION_FAIL);
+    auto reservation = writer.Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    ASSERT_TRUE(
+        writer.Commit(std::move(*reservation), MakeEntry(), [](const auto&) {})
+            .has_value());
+    ASSERT_TRUE(storage.WaitForAttempts(1));
+    for (int i = 0; i < 100 && !writer.GetTerminalState().has_value(); ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    const auto state = writer.GetTerminalState();
+    ASSERT_TRUE(state.has_value());
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, state->error);
+    EXPECT_EQ(OrderedOpLogWriterTerminalReason::kFenced, state->reason);
+    EXPECT_EQ(1u, storage.AttemptTimes().size());
+    writer.Stop();
+}
+
 TEST(OrderedOpLogWriterFailureTest,
      DoesNotInvokeCallbacksWhileBatchIsUndurable) {
     FakeBatchWriter storage;
@@ -738,6 +1287,86 @@ TEST(OrderedOpLogWriterFailureTest,
     writer.Stop();
 }
 
+TEST(OrderedOpLogWriterFailureTest, RetryTimeoutStopsFurtherAttempts) {
+    using namespace std::chrono_literals;
+
+    FakeBatchWriter storage;
+    std::atomic<int> terminal_callbacks{0};
+    OrderedOpLogWriter writer(
+        OrderedOpLogWriterConfig{.max_entries_per_batch = 1,
+                                 .retry_timeout = 50ms},
+        [&](const OpLogBatchRecord& batch,
+            const DurablePrefix& expected_prefix) {
+            return storage.Write(batch, expected_prefix);
+        },
+        [&](const OrderedOpLogWriterTerminalState&) { ++terminal_callbacks; });
+    writer.Start();
+
+    storage.FailNextWrites(100000, ErrorCode::PERSISTENT_FAIL);
+    auto reservation = writer.Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    ASSERT_TRUE(writer
+                    .Commit(std::move(*reservation), MakeEntry("k1"),
+                            [](const auto&) {})
+                    .has_value());
+
+    for (int i = 0; i < 200 && !writer.GetTerminalState().has_value(); ++i) {
+        std::this_thread::sleep_for(10ms);
+    }
+    const auto state = writer.GetTerminalState();
+    ASSERT_TRUE(state.has_value());
+    EXPECT_EQ(ErrorCode::PERSISTENT_FAIL, state->error);
+    EXPECT_EQ(OrderedOpLogWriterTerminalReason::kRetryTimeout, state->reason);
+    EXPECT_NE(0u, state->occurred_at_ms);
+    EXPECT_EQ(ErrorCode::PERSISTENT_FAIL, writer.LastError());
+    EXPECT_EQ(0u,
+              HAMetricManager::instance().get_writer_runtime().retry_delay_ms);
+    for (int i = 0; i < 100 && terminal_callbacks.load() != 1; ++i) {
+        std::this_thread::sleep_for(10ms);
+    }
+    EXPECT_EQ(1, terminal_callbacks.load());
+
+    const size_t attempts_after_terminal = storage.AttemptTimes().size();
+    std::this_thread::sleep_for(100ms);
+    EXPECT_EQ(attempts_after_terminal, storage.AttemptTimes().size());
+    writer.Stop();
+}
+
+TEST(OrderedOpLogWriterFailureTest,
+     SuccessBeforeRetryTimeoutDoesNotBecomeTerminal) {
+    using namespace std::chrono_literals;
+
+    FakeBatchWriter storage;
+    std::atomic<int> terminal_callbacks{0};
+    OrderedOpLogWriter writer(
+        OrderedOpLogWriterConfig{.max_entries_per_batch = 1,
+                                 .retry_timeout = 2s},
+        [&](const OpLogBatchRecord& batch,
+            const DurablePrefix& expected_prefix) {
+            return storage.Write(batch, expected_prefix);
+        },
+        [&](const OrderedOpLogWriterTerminalState&) { ++terminal_callbacks; });
+    writer.Start();
+
+    storage.FailNextWrites(1, ErrorCode::PERSISTENT_FAIL);
+    auto reservation = writer.Reserve();
+    ASSERT_TRUE(reservation.has_value());
+    ASSERT_TRUE(writer
+                    .Commit(std::move(*reservation), MakeEntry("k1"),
+                            [](const auto&) {})
+                    .has_value());
+
+    ASSERT_TRUE(storage.WaitForWrites(1));
+    for (int i = 0; i < 100 && !writer.IsAccepting(); ++i) {
+        std::this_thread::sleep_for(10ms);
+    }
+    EXPECT_FALSE(writer.GetTerminalState().has_value());
+    EXPECT_EQ(0, terminal_callbacks.load());
+    EXPECT_TRUE(writer.IsAccepting());
+    EXPECT_EQ(ErrorCode::OK, writer.LastError());
+    writer.Stop();
+}
+
 TEST(OrderedOpLogWriterFailureTest, RetriesSameBatchUntilSuccess) {
     FakeBatchWriter storage;
     OrderedOpLogWriter writer(
@@ -859,6 +1488,9 @@ TEST(OrderedOpLogWriterFailureTest, StopInterruptsRetryBackoff) {
     const auto started_at = FakeBatchWriter::Clock::now();
     writer.Stop();
     EXPECT_LT(FakeBatchWriter::Clock::now() - started_at, 250ms);
+    EXPECT_FALSE(writer.GetTerminalState().has_value());
+    EXPECT_EQ(0u,
+              HAMetricManager::instance().get_writer_runtime().retry_delay_ms);
 }
 
 TEST(OrderedOpLogWriterFailureTest, SuccessAfterRetryRestoresAccepting) {
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.py b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.py
new file mode 100644
index 0000000000..33a204a6f0
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.py
@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Evidence collection and assertions for the disposable N13 etcd harness."""
+
+import argparse
+import base64
+import json
+from pathlib import Path
+import subprocess
+import time
+import urllib.request
+
+
+def require(condition, message):
+    if not condition:
+        raise RuntimeError(message)
+
+
+class Etcd:
+    def __init__(self, endpoint):
+        self.endpoint = endpoint
+
+    def run(self, *args, value=None):
+        return subprocess.run(
+            ["etcdctl", "--endpoints=" + self.endpoint, "--command-timeout=15s", *args],
+            input=value,
+            text=True,
+            capture_output=True,
+            timeout=20,
+        )
+
+    def json(self, *args):
+        result = self.run(*args, "--write-out=json")
+        require(result.returncode == 0, result.stderr)
+        return json.loads(result.stdout)
+
+
+def save(path, value):
+    path.write_text(json.dumps(value, indent=2) + "\n")
+
+
+def status(etcd, directory):
+    directory.mkdir(parents=True, exist_ok=False)
+    endpoints = etcd.json("endpoint", "status")
+    save(directory / "status.json", endpoints)
+    alarm = etcd.json("alarm", "list")
+    save(directory / "alarm.json", alarm)
+    # Retain the actual quota gauge, not only a configured/default value.
+    with urllib.request.urlopen("http://" + etcd.endpoint + "/metrics", timeout=5) as r:
+        metrics = r.read().decode()
+    (directory / "etcd.prom").write_text(metrics)
+    health = etcd.run("endpoint", "health")
+    (directory / "health.log").write_text(health.stdout + health.stderr)
+    require(
+        health.returncode == 0 or alarm.get("alarms"), "unhealthy etcd without alarm"
+    )
+    return endpoints, alarm
+
+
+def sample(etcd, directory, cluster, ports):
+    endpoints, alarm = status(etcd, directory)
+    prefix = "/oplog/" + cluster + "/"
+    keys = etcd.json("get", prefix + "batches/", "--prefix", "--keys-only")
+    save(directory / "batch-keys.json", keys)
+    revision = keys["header"]["revision"]
+    # Pin control reads to the same revision as the live key set.
+    control = etcd.json(
+        "get", prefix + "snapshot/", "--prefix", "--rev=" + str(revision)
+    )
+    durable = etcd.json("get", prefix + "durable_prefix", "--rev=" + str(revision))
+    save(directory / "control.json", control)
+    save(directory / "durable.json", durable)
+    values = {
+        base64.b64decode(kv["key"]).decode().rsplit("/", 1)[-1]: json.loads(
+            base64.b64decode(kv["value"])
+        )
+        for kv in control.get("kvs", [])
+    }
+    batches = [
+        int(base64.b64decode(kv["key"]).decode().rsplit("/", 1)[-1])
+        for kv in keys.get("kvs", [])
+    ]
+    head = json.loads(base64.b64decode(durable["kvs"][0]["value"]))
+    for index, port in enumerate(ports.split(",")):
+        with urllib.request.urlopen(
+            "http://127.0.0.1:" + port + "/metrics", timeout=5
+        ) as r:
+            metrics = r.read().decode()
+            (directory / f"master-{index}.prom").write_text(metrics)
+            require(
+                "ha_snapshot_enabled " in metrics, "M02 snapshot metrics unavailable"
+            )
+    state = {
+        "time": time.time(),
+        "revision": revision,
+        "live_batches": len(batches),
+        "min_batch": min(batches, default=0),
+        "max_batch": max(batches, default=0),
+        "durable": head,
+        "retained_durable_batches": sum(
+            values.get("compaction_floor", 0) < b <= head["batch_id"] for b in batches
+        ),
+        "latest": values.get("latest"),
+        "fallback": values.get("fallback"),
+        "floor": values.get("compaction_floor", 0),
+        "status": endpoints,
+        "alarms": alarm.get("alarms", []),
+    }
+    save(directory / "sample.json", state)
+    return state
+
+
+def pruned(state):
+    latest, fallback = state["latest"], state["fallback"]
+    return bool(
+        latest
+        and fallback
+        and state["floor"] > 0
+        and latest["snapshot_id"] != fallback["snapshot_id"]
+        and latest["last_included_batch_id"] > fallback["last_included_batch_id"]
+        and state["floor"] <= fallback["last_included_batch_id"]
+        and (state["min_batch"] == 0 or state["min_batch"] > state["floor"])
+    )
+
+
+def validate(samples, max_batches):
+    require(len(samples) >= 3, "need at least three capacity samples")
+    floors = [s["floor"] for s in samples]
+    require(floors == sorted(floors), "floor moved backwards")
+    require(len(set(floors) - {0}) >= 3, "need at least three distinct positive floors")
+    require(all(not s["alarms"] for s in samples), "unexpected etcd alarm during soak")
+    require(
+        max(s["live_batches"] for s in samples) <= max_batches,
+        "live batch bound exceeded",
+    )
+    require(pruned(samples[-1]), "final batch deletion did not reach the floor")
+    for state in samples:
+        require(
+            state["retained_durable_batches"]
+            == state["durable"]["batch_id"] - state["floor"],
+            "missing batch above floor",
+        )
+    final = samples[-1]
+    require(
+        final["max_batch"] <= final["durable"]["batch_id"] + 1,
+        "batch beyond writer head",
+    )
+    return {
+        "samples": len(samples),
+        "floor_advances": sum(a < b for a, b in zip(floors, floors[1:])),
+        "peak_live_batches": max(s["live_batches"] for s in samples),
+        "final_floor": final["floor"],
+        "elapsed_seconds": samples[-1]["time"] - samples[0]["time"],
+    }
+
+
+def maintain(etcd, root, label):
+    before, _ = status(etcd, root / (label + "-before"))
+    require(len(before) == 1, "test maintenance requires its single local member")
+    revision = before[0]["Status"]["header"]["revision"]
+    for name, args in [
+        ("compact", ("compact", str(revision), "--physical")),
+        ("defrag", ("defrag",)),
+    ]:
+        result = etcd.run(*args)
+        (root / (label + "-" + name + ".log")).write_text(result.stdout + result.stderr)
+        require(result.returncode == 0, name + " failed: " + result.stderr)
+        status(etcd, root / (label + "-after-" + name))
+    after = json.loads((root / (label + "-after-defrag/status.json")).read_text())
+    old, new = before[0]["Status"], after[0]["Status"]
+    require(
+        old["leader"] == new["leader"] == new["header"]["member_id"],
+        "local etcd leader changed during maintenance",
+    )
+    metrics = (root / (label + "-after-defrag/etcd.prom")).read_text()
+    quota = next(
+        float(line.split()[1])
+        for line in metrics.splitlines()
+        if line.startswith("etcd_server_quota_backend_bytes ")
+    )
+    require(new["dbSize"] < quota, "backend still above quota; do not disarm")
+    require(new["dbSize"] < old["dbSize"], "defrag did not reduce backend size")
+    require(
+        new["dbSize"] <= new["dbSizeInUse"] + 1024 * 1024,
+        "backend remains fragmented after defrag",
+    )
+
+
+def nospace(etcd, root):
+    # Revisions of one expendable key fill MVCC without touching Mooncake data.
+    # Limit attempts so a wrong quota cannot consume the operator's disk.
+    for _ in range(256):
+        result = etcd.run("put", "/n13-capacity-padding", value="x" * (256 * 1024))
+        if result.returncode:
+            (root / "nospace-put.log").write_text(result.stdout + result.stderr)
+            require(
+                "database space exceeded" in result.stderr, "unexpected fill failure"
+            )
+            break
+    else:
+        raise RuntimeError("quota was not reached within 64 MiB of test writes")
+    _, alarm = status(etcd, root / "nospace-alarm")
+    require(
+        any(a["alarm"] == 1 for a in alarm.get("alarms", [])), "NOSPACE not observed"
+    )
+    deleted = etcd.run("del", "/n13-capacity-padding")
+    require(deleted.returncode == 0, deleted.stderr)
+    maintain(etcd, root, "nospace")
+    result = etcd.run("alarm", "disarm")
+    (root / "disarm.log").write_text(result.stdout + result.stderr)
+    require(result.returncode == 0, result.stderr)
+    _, alarm = status(etcd, root / "nospace-disarmed")
+    require(not alarm.get("alarms"), "alarm persists after disarm")
+    result = etcd.run("put", "/n13-capacity-probe", "recovered")
+    require(result.returncode == 0, result.stderr)
+    require(etcd.json("get", "/n13-capacity-probe")["count"] == 1, "probe not readable")
+    health = etcd.run("endpoint", "health")
+    (root / "recovered-health.log").write_text(health.stdout + health.stderr)
+    require(health.returncode == 0, health.stderr)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "command", choices=["sample", "ready", "validate", "maintain", "nospace"]
+    )
+    parser.add_argument("directory", type=Path)
+    parser.add_argument("--endpoint")
+    parser.add_argument("--cluster")
+    parser.add_argument("--ports")
+    parser.add_argument("--max-batches", type=int, default=2048)
+    args = parser.parse_args()
+    if args.command == "ready":
+        return 0 if pruned(json.loads(args.directory.read_text())) else 1
+    if args.command == "validate":
+        samples = [
+            json.loads(p.read_text())
+            for p in sorted(args.directory.glob("sample-*/sample.json"))
+        ]
+        save(args.directory / "soak-result.json", validate(samples, args.max_batches))
+    elif args.command == "sample":
+        sample(Etcd(args.endpoint), args.directory, args.cluster, args.ports)
+    elif args.command == "maintain":
+        maintain(Etcd(args.endpoint), args.directory, "soak")
+    else:
+        nospace(Etcd(args.endpoint), args.directory)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.sh b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.sh
new file mode 100644
index 0000000000..5174ce2c0f
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity.sh
@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# Sourced by run_oplog_batch_cluster.sh; all maintenance targets a fresh local etcd.
+
+capacity_sample() {
+  local directory
+  printf -v directory '%s/capacity/sample-%06d' "$RUN_DIR" "$CAPACITY_SAMPLE"
+  [[ -z "${1:-}" ]] || directory="$RUN_DIR/capacity/$1"
+  CAPACITY_SAMPLE=$((CAPACITY_SAMPLE + 1))
+  python3 "$CAPACITY_HELPER" sample "$directory" --endpoint "$ETCD_ENDPOINTS" \
+    --cluster "$CLUSTER_ID" --ports "${ADMIN_PORTS[0]},${ADMIN_PORTS[1]}"
+  CAPACITY_LAST_SAMPLE="$directory/sample.json"
+}
+
+capacity_client() {
+  local mode=$1 manifest=$2
+  shift 2
+  "$CAPACITY_CLIENT" --mode="$mode" --manifest="$manifest" \
+    --port="$(find_free_port)" "${CAPACITY_CLIENT_ARGS[@]}" "$@" \
+    >>"$RUN_DIR/workload/$mode.log" 2>&1
+}
+
+capacity_wait_pruned() {
+  local deadline=$((SECONDS + START_TIMEOUT_SEC))
+  while ((SECONDS < deadline)); do
+    capacity_sample
+    if python3 "$CAPACITY_HELPER" ready "$CAPACITY_LAST_SAMPLE"; then return; fi
+    sleep 1
+  done
+  die "pruning did not catch up; see $RUN_DIR/capacity"
+}
+
+capacity_audit() {
+  local phase=$1
+  wait_master_metric_at_least "$(ready_leader_index)" master_active_clients 1 "$START_TIMEOUT_SEC"
+  capacity_client verify "$RUN_DIR/workload/anchor.ack"
+  capacity_client verify "$RUN_DIR/workload/current.ack"
+  if [[ -s "$RUN_DIR/workload/deleted.ack" ]]; then
+    capacity_client verify-absent "$RUN_DIR/workload/deleted.ack"
+  fi
+  capacity_sample "$phase"
+  printf '%s acknowledged-data audit passed\n' "$phase" >>"$RUN_DIR/capacity/audits.log"
+}
+
+capacity_cluster() (
+  local mode=$1
+  [[ -z "$ETCD_ENDPOINTS" ]] || die "capacity tests require a new local etcd; external endpoints are forbidden"
+  [[ ! -e "$RUN_DIR" ]] || die "capacity tests require a fresh run directory"
+  [[ "$CAPACITY_SECONDS" -ge 30 ]] || die "capacity-seconds must be at least 30"
+  [[ -z "$MASTER_CONFIG" ]] || die "capacity tests generate their own master config"
+  command -v etcdctl >/dev/null || die "missing executable: etcdctl"
+  CAPACITY_HELPER="$SCRIPT_DIR/../ha/snapshot/batch_oplog/capacity.py"
+  CAPACITY_CLIENT="$BUILD_DIR/mooncake-store/tests/e2e/oplog_ha_client"
+  require_executable "$CAPACITY_CLIENT"
+  MASTER_COUNT=2
+  CLIENT_COUNT=0
+  ENABLE_OPLOG_SNAPSHOT=true
+  SNAPSHOT_CHUNK_OBJECT_COUNT=64
+  mkdir -p "$RUN_DIR"/{configs,capacity}
+  MASTER_CONFIG="$RUN_DIR/configs/capacity.yaml"
+  printf 'snapshot_interval_seconds: 2\ndefault_kv_lease_ttl: 1s\n' >"$MASTER_CONFIG"
+  # These scoped settings are inherited only by the disposable local etcd.
+  export ETCD_QUOTA_BACKEND_BYTES=67108864
+  [[ "$mode" != capacity-nospace ]] || export ETCD_QUOTA_BACKEND_BYTES=16777216
+  export ETCD_AUTO_COMPACTION_RETENTION=0
+  "$ETCD_BIN" --version >"$RUN_DIR/capacity/etcd-version.txt"
+  etcdctl version >"$RUN_DIR/capacity/etcdctl-version.txt"
+  printf 'mode=%s\nseconds=%s\nmax_batches=%s\nquota_bytes=%s\n' \
+    "$mode" "$CAPACITY_SECONDS" "$CAPACITY_MAX_BATCHES" "$ETCD_QUOTA_BACKEND_BYTES" \
+    >"$RUN_DIR/capacity/config.txt"
+  CAPACITY_SAMPLE=0
+  local pressure_pid=""
+  trap 'down_cluster >/dev/null 2>&1 || true' EXIT
+  up_cluster
+  export MC_STORE_CLUSTER_ID="$CLUSTER_ID" ETCDCTL_API=3
+  CAPACITY_CLIENT_ARGS=(--master_server_entry="etcd://$ETCD_ENDPOINTS"
+    --engine_meta_url="http://127.0.0.1:$METADATA_PORT/metadata"
+    --protocol="$PROTOCOL" --payload_size=1024 --key_prefix="capacity-$CLUSTER_ID")
+  start_process provider-0 "$CAPACITY_CLIENT" --mode=provider \
+    --port="$(find_free_port)" "${CAPACITY_CLIENT_ARGS[@]}"
+  wait_file_text "$RUN_DIR/logs/provider-0.out" provider_ready "$START_TIMEOUT_SEC"
+  capacity_client seed "$RUN_DIR/workload/anchor.ack" --count=16
+  local deadline=$((SECONDS + CAPACITY_SECONDS)) index=1000 round=0
+  while ((SECONDS < deadline || round < 3)); do
+    start_process client-pressure "$CAPACITY_CLIENT" --mode=pressure \
+      --manifest="$RUN_DIR/workload/next.ack" --port="$(find_free_port)" \
+      "${CAPACITY_CLIENT_ARGS[@]}" --start_index="$index" --duration_sec=10 --sleep_ms=25
+    pressure_pid=$(cat "$RUN_DIR/pids/client-pressure.pid")
+    while kill -0 "$pressure_pid" 2>/dev/null; do
+      capacity_sample
+      sleep 2
+    done
+    wait "$pressure_pid"
+    pressure_pid=""
+    cp "$RUN_DIR/workload/next.ack" "$RUN_DIR/workload/round-$round.ack"
+    index=$((index + $(wc -l <"$RUN_DIR/workload/next.ack")))
+    if [[ -s "$RUN_DIR/workload/current.ack" ]]; then
+      capacity_client delete "$RUN_DIR/workload/current.ack"
+      cat "$RUN_DIR/workload/current.ack" >>"$RUN_DIR/workload/deleted.ack"
+    fi
+    mv "$RUN_DIR/workload/next.ack" "$RUN_DIR/workload/current.ack"
+    capacity_wait_pruned
+    round=$((round + 1))
+    if [[ "$mode" == capacity-soak ]] && ((round % 6 == 0)); then
+      mkdir "$RUN_DIR/capacity/maintenance-$round"
+      python3 "$CAPACITY_HELPER" maintain "$RUN_DIR/capacity/maintenance-$round" --endpoint "$ETCD_ENDPOINTS"
+    fi
+    # Quota recovery needs only enough churn to establish redundant snapshots.
+    [[ "$mode" != capacity-nospace || "$round" -lt 3 ]] || break
+  done
+  python3 "$CAPACITY_HELPER" validate "$RUN_DIR/capacity" --max-batches "$CAPACITY_MAX_BATCHES"
+  capacity_audit before-maintenance
+  if [[ "$mode" == capacity-nospace ]]; then
+    # Quiesce metadata mutations before inducing the quota alarm. Providers stay
+    # alive so an etcd restart/recovery cannot be confused with lost payloads.
+    local i
+    for i in 0 1; do stop_pid_file "$RUN_DIR/pids/master-$i.pid"; done
+    python3 "$CAPACITY_HELPER" nospace "$RUN_DIR/capacity" --endpoint "$ETCD_ENDPOINTS"
+  else
+    python3 "$CAPACITY_HELPER" maintain "$RUN_DIR/capacity" --endpoint "$ETCD_ENDPOINTS"
+  fi
+  local started=$SECONDS
+  restart_masters
+  capacity_audit after-restart
+  printf 'restart_and_audit_seconds=%s\n' "$((SECONDS - started))" >>"$RUN_DIR/capacity/audits.log"
+  local leader standby
+  leader=$(ready_leader_index)
+  standby=$((1 - leader))
+  wait_master_metric_at_least "$standby" ha_oplog_applied_sequence_id \
+    "$(read_durable_sequence)" "$START_TIMEOUT_SEC"
+  started=$SECONDS
+  "$SCRIPT_DIR/oplog_fault_ctl.sh" process kill --run-dir "$RUN_DIR" --name "master-$leader"
+  wait "$(cat "$RUN_DIR/pids/master-$leader.pid")" 2>/dev/null || true
+  wait_for_single_leader "$START_TIMEOUT_SEC"
+  [[ "$(ready_leader_index)" == "$standby" ]] || die "standby did not promote"
+  start_master "$leader"
+  wait_master_metric_at_least "$leader" ha_oplog_applied_sequence_id \
+    "$(read_durable_sequence)" "$START_TIMEOUT_SEC"
+  capacity_audit after-promotion
+  printf 'promotion_and_audit_seconds=%s\n' "$((SECONDS - started))" >>"$RUN_DIR/capacity/audits.log"
+  capacity_client seed "$RUN_DIR/workload/recovered.ack" --start_index="$index" --count=16
+  capacity_client verify "$RUN_DIR/workload/recovered.ack"
+  capacity_sample after-new-write
+  printf 'PASS\n' >"$RUN_DIR/capacity/result.txt"
+  printf 'PASS: %s; evidence: %s/capacity\n' "$mode" "$RUN_DIR"
+)
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/capacity_test.py b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity_test.py
new file mode 100644
index 0000000000..cfe56dd567
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/capacity_test.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Offline evidence checks; invoked by run_oplog_batch_cluster_test.sh."""
+
+from copy import deepcopy
+
+from capacity import pruned, validate
+
+
+def sample(floor):
+    return {
+        "time": floor,
+        "floor": floor,
+        "alarms": [],
+        "live_batches": 5,
+        "min_batch": floor + 1,
+        "max_batch": floor + 5,
+        "durable": {"batch_id": floor + 5},
+        "retained_durable_batches": 5,
+        "latest": {"snapshot_id": str(floor + 1), "last_included_batch_id": floor + 1},
+        "fallback": {"snapshot_id": str(floor), "last_included_batch_id": floor},
+    }
+
+
+def fails(samples, message):
+    try:
+        validate(samples, 20)
+    except RuntimeError as error:
+        assert message in str(error), error
+    else:
+        raise AssertionError("invalid evidence accepted: " + message)
+
+
+def main():
+    samples = [sample(i) for i in (1, 2, 3)]
+    assert validate(samples, 20)["final_floor"] == 3
+    fails(samples[:2], "three capacity samples")
+    fails(samples[::-1], "backwards")
+    fails([sample(1)] * 3, "distinct positive floors")
+    broken = deepcopy(samples)
+    broken[1]["alarms"] = [{"alarm": 1}]
+    fails(broken, "alarm")
+    broken = deepcopy(samples)
+    broken[1]["live_batches"] = 21
+    fails(broken, "bound")
+    broken = deepcopy(samples)
+    broken[-1]["min_batch"] = 1
+    fails(broken, "deletion")
+    broken = deepcopy(samples)
+    broken[-1]["fallback"] = None
+    assert not pruned(broken[-1])
+    broken = deepcopy(samples)
+    broken[-1]["max_batch"] = 100
+    fails(broken, "writer head")
+    broken = deepcopy(samples)
+    broken[1]["retained_durable_batches"] = 4
+    fails(broken, "missing batch")
+    print("PASS: capacity evidence rejects stalled pruning, alarms and unbounded keys")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/codec_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/codec_test.cpp
new file mode 100644
index 0000000000..43d3899294
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/codec_test.cpp
@@ -0,0 +1,111 @@
+#include "ha/snapshot/batch_oplog/codec.h"
+
+#include <gtest/gtest.h>
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace mooncake::test {
+
+namespace {
+
+struct LegacyStandbyObjectMetadata {
+    UUID client_id{0, 0};
+    uint64_t size{0};
+    std::vector<Replica::Descriptor> replicas;
+    std::string group_id;
+    ObjectDataType data_type{ObjectDataType::UNKNOWN};
+
+    YLT_REFL(LegacyStandbyObjectMetadata, client_id, size, replicas, group_id,
+             data_type);
+};
+
+struct LegacyStandbyObjectEntry {
+    std::string tenant_id{"default"};
+    std::string key;
+    LegacyStandbyObjectMetadata metadata;
+
+    YLT_REFL(LegacyStandbyObjectEntry, tenant_id, key, metadata);
+};
+
+struct LegacyBatchOpLogSnapshotObjectChunk {
+    uint64_t chunk_index{0};
+    std::vector<LegacyStandbyObjectEntry> objects;
+
+    YLT_REFL(LegacyBatchOpLogSnapshotObjectChunk, chunk_index, objects);
+};
+
+}  // namespace
+
+TEST(BatchOpLogSnapshotCodecTest, SegmentsRoundTrip) {
+    std::vector<StandbySegmentInfo> segments{{
+        .segment_name = "segment-1",
+        .transport_endpoint = "127.0.0.1:12345",
+        .capacity = 4096,
+        .is_memory_segment = true,
+        .file_path = "",
+    }};
+
+    auto decoded = DecodeBatchOpLogSnapshotSegments(
+        EncodeBatchOpLogSnapshotSegments(segments));
+
+    ASSERT_TRUE(decoded) << decoded.error();
+    ASSERT_EQ(1u, decoded->size());
+    EXPECT_EQ("segment-1", decoded->front().segment_name);
+    EXPECT_EQ("127.0.0.1:12345", decoded->front().transport_endpoint);
+    EXPECT_EQ(4096u, decoded->front().capacity);
+    EXPECT_TRUE(decoded->front().is_memory_segment);
+}
+
+TEST(BatchOpLogSnapshotCodecTest, ObjectChunkRoundTripsAndChecksEnvelope) {
+    StandbyObjectMetadata metadata;
+    metadata.client_id = {1, 2};
+    metadata.size = 8192;
+    metadata.group_id = "group";
+    metadata.hard_pinned = true;
+    std::vector<StandbyObjectEntry> objects{
+        {.tenant_id = "tenant", .key = "key", .metadata = metadata}};
+    auto encoded = EncodeBatchOpLogSnapshotObjectChunk(7, std::move(objects));
+
+    auto decoded = DecodeBatchOpLogSnapshotObjectChunk(encoded, 7, 1);
+
+    ASSERT_TRUE(decoded) << decoded.error();
+    EXPECT_EQ(7u, decoded->chunk_index);
+    ASSERT_EQ(1u, decoded->objects.size());
+    EXPECT_EQ("tenant", decoded->objects[0].tenant_id);
+    EXPECT_EQ("key", decoded->objects[0].key);
+    EXPECT_EQ(UUID(1, 2), decoded->objects[0].metadata.client_id);
+    EXPECT_EQ(8192u, decoded->objects[0].metadata.size);
+    EXPECT_EQ("group", decoded->objects[0].metadata.group_id);
+    EXPECT_TRUE(decoded->objects[0].metadata.hard_pinned.value_or(false));
+
+    EXPECT_FALSE(DecodeBatchOpLogSnapshotObjectChunk(encoded, 8, 1));
+    EXPECT_FALSE(DecodeBatchOpLogSnapshotObjectChunk(encoded, 7, 300000000));
+}
+
+TEST(BatchOpLogSnapshotCodecTest, OldObjectChunkDefaultsHardPinnedToFalse) {
+    LegacyBatchOpLogSnapshotObjectChunk old_chunk{
+        0, {{"tenant", "key", {{1, 2}, 8192, {}, "group", {}}}}};
+    auto old_encoded = struct_pack::serialize(old_chunk);
+    std::vector<uint8_t> encoded(old_encoded.begin(), old_encoded.end());
+
+    auto decoded = DecodeBatchOpLogSnapshotObjectChunk(encoded, 0, 1);
+
+    ASSERT_TRUE(decoded) << decoded.error();
+    EXPECT_FALSE(decoded->objects[0].metadata.hard_pinned.value_or(false));
+}
+
+TEST(BatchOpLogSnapshotCodecTest, RejectsTruncatedArtifacts) {
+    auto segments = EncodeBatchOpLogSnapshotSegments({});
+    auto objects = EncodeBatchOpLogSnapshotObjectChunk(
+        0, std::vector<StandbyObjectEntry>{
+               {.tenant_id = "default", .key = "key", .metadata = {}}});
+    segments.pop_back();
+    objects.pop_back();
+
+    EXPECT_FALSE(DecodeBatchOpLogSnapshotSegments(segments));
+    EXPECT_FALSE(DecodeBatchOpLogSnapshotObjectChunk(objects, 0, 1));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/coordinator_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/coordinator_test.cpp
new file mode 100644
index 0000000000..2741fa9778
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/coordinator_test.cpp
@@ -0,0 +1,501 @@
+#include "ha_metric_manager.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_coordinator.h"
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/oplog/oplog_types.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "hot_standby_service.h"
+
+namespace mooncake::test {
+namespace {
+
+class EmptyBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        if (get_error != ErrorCode::OK) return get_error;
+        auto it = values.find(std::string(key));
+        if (it == values.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        values[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view, std::string_view, size_t,
+                    std::vector<KvPair>& output) override {
+        output.clear();
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
+
+    ErrorCode get_error{ErrorCode::OK};
+    std::map<std::string, std::string> values;
+};
+
+class UnusedObjectStore final : public SnapshotObjectStore {
+   public:
+    tl::expected<void, std::string> UploadBuffer(
+        const std::string&, const std::vector<uint8_t>&) override {
+        return {};
+    }
+    tl::expected<void, std::string> DownloadBuffer(
+        const std::string&, std::vector<uint8_t>&) override {
+        return tl::make_unexpected("unused");
+    }
+    tl::expected<void, std::string> UploadString(const std::string&,
+                                                 const std::string&) override {
+        return {};
+    }
+    tl::expected<void, std::string> DownloadString(const std::string&,
+                                                   std::string&) override {
+        return tl::make_unexpected("unused");
+    }
+    tl::expected<void, std::string> DeleteObjectsWithPrefix(
+        const std::string&) override {
+        return {};
+    }
+    tl::expected<void, std::string> ListObjectsWithPrefix(
+        const std::string&, std::vector<std::string>& output) override {
+        output.clear();
+        return {};
+    }
+    std::string GetConnectionInfo() const override { return "unused"; }
+};
+
+class RecordingBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view begin,
+                          std::string_view end) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        EXPECT_EQ(
+            "1",
+            values_[ha::BuildBatchOpLogSnapshotCompactionFloorKey("cluster")]);
+        ++delete_count;
+        values_.erase(values_.lower_bound(std::string(begin)),
+                      values_.lower_bound(std::string(end)));
+        return ErrorCode::OK;
+    }
+    size_t delete_count{0};
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        const std::string owned_key(key);
+        values_[owned_key] = std::string(value);
+        create_revisions_.try_emplace(owned_key, next_revision_++);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin, std::string_view end, size_t limit,
+                    std::vector<KvPair>& output) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (pause_replay.load()) return ErrorCode::ETCD_OPERATION_ERROR;
+        output.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin && key < end &&
+                (limit == 0 || output.size() < limit)) {
+                output.push_back({key, value});
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (const auto& compare : txn.compares) {
+            auto it = values_.find(compare.key);
+            if (compare.kind == KvCompareKind::kKeyNotExists) {
+                if (it != values_.end())
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+            } else if (compare.kind == KvCompareKind::kCreateRevisionEquals) {
+                auto revision = create_revisions_.find(compare.key);
+                if (revision == create_revisions_.end() ||
+                    revision->second != compare.expected_revision) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (it == values_.end() ||
+                       it->second != compare.expected_value) {
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+        }
+        for (const auto& put : txn.puts) {
+            values_[put.key] = put.value;
+            create_revisions_.try_emplace(put.key, next_revision_++);
+        }
+        return ErrorCode::OK;
+    }
+
+    bool Contains(std::string_view key) const {
+        std::lock_guard<std::mutex> lock(mutex_);
+        return values_.contains(std::string(key));
+    }
+
+    std::atomic<bool> pause_replay{false};
+
+   private:
+    mutable std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+    std::map<std::string, EtcdRevisionId> create_revisions_;
+    EtcdRevisionId next_revision_{1};
+};
+
+class RecordingObjectStore final : public SnapshotObjectStore {
+   public:
+    tl::expected<void, std::string> UploadBuffer(
+        const std::string& key, const std::vector<uint8_t>& buffer) override {
+        if (on_upload) on_upload();
+        objects_[key] = buffer;
+        return {};
+    }
+    tl::expected<void, std::string> DownloadBuffer(
+        const std::string& key, std::vector<uint8_t>& buffer) override {
+        auto it = objects_.find(key);
+        if (it == objects_.end()) return tl::make_unexpected("not found");
+        buffer = it->second;
+        return {};
+    }
+    tl::expected<void, std::string> UploadString(
+        const std::string& key, const std::string& value) override {
+        objects_[key] = std::vector<uint8_t>(value.begin(), value.end());
+        return {};
+    }
+    tl::expected<void, std::string> DownloadString(
+        const std::string& key, std::string& value) override {
+        std::vector<uint8_t> bytes;
+        auto result = DownloadBuffer(key, bytes);
+        if (!result) return result;
+        value.assign(bytes.begin(), bytes.end());
+        return {};
+    }
+    tl::expected<void, std::string> DeleteObjectsWithPrefix(
+        const std::string& prefix) override {
+        for (auto it = objects_.begin(); it != objects_.end();) {
+            if (it->first.starts_with(prefix))
+                it = objects_.erase(it);
+            else
+                ++it;
+        }
+        return {};
+    }
+    tl::expected<void, std::string> ListObjectsWithPrefix(
+        const std::string& prefix, std::vector<std::string>& output) override {
+        if (prefix == "snapshots/batch-oplog/") {
+            if (gc_failure == 1) return tl::make_unexpected("GC list failed");
+            if (gc_failure == 2) throw std::runtime_error("GC list threw");
+        }
+        output.clear();
+        for (const auto& [key, value] : objects_) {
+            (void)value;
+            if (key.starts_with(prefix)) output.push_back(key);
+        }
+        return {};
+    }
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override {
+        auto it = objects_.find(key);
+        if (it == objects_.end()) return tl::make_unexpected("not found");
+        return SnapshotObjectInspection{.stored_size = it->second.size(),
+                                        .crc32c = std::nullopt};
+    }
+    std::string GetConnectionInfo() const override { return "recording"; }
+    int gc_failure{0};
+    std::function<void()> on_upload;
+
+   private:
+    std::map<std::string, std::vector<uint8_t>> objects_;
+};
+
+OpLogBatchRecord MakeBatch() {
+    OpLogEntry entry;
+    entry.sequence_id = 1;
+    entry.op_type = OpType::REMOVE;
+    entry.tenant_id = "tenant";
+    entry.object_key = "key";
+    entry.checksum = ComputeOpLogChecksum(entry.payload);
+    OpLogBatchRecord batch;
+    batch.batch_id = 1;
+    batch.first_seq = 1;
+    batch.last_seq = 1;
+    batch.entries.push_back(std::move(entry));
+    return batch;
+}
+
+}  // namespace
+
+TEST(BatchOpLogSnapshotCoordinatorTest, EmptyStandbySkipsWithoutLease) {
+    HotStandbyConfig standby_config;
+    standby_config.enable_verification = false;
+    HotStandbyService standby(standby_config);
+    EmptyBackend backend;
+    UnusedObjectStore object_store;
+    size_t lease_factory_calls = 0;
+    BatchOpLogSnapshotCoordinatorConfig config;
+    config.snapshot_root = "snapshots";
+    config.clock = [] { return std::chrono::steady_clock::now(); };
+    BatchOpLogSnapshotCoordinator coordinator(
+        standby, backend, object_store, "cluster", std::move(config), [&] {
+            ++lease_factory_calls;
+            return std::unique_ptr<SnapshotMaintenanceLease>();
+        });
+
+    EXPECT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_EQ(0u, lease_factory_calls);
+    EXPECT_FALSE(coordinator.IsAttemptInFlight());
+    EXPECT_EQ(0u, coordinator.GetStatus().attempts);
+    EXPECT_EQ(HAMetricManager::SnapshotSkipReason::NoNewBatch,
+              HAMetricManager::instance().get_snapshot_runtime().skip_reason);
+
+    auto& metrics = HAMetricManager::instance();
+    const auto before = metrics.get_snapshot_operation(
+        HAMetricManager::SnapshotOperation::Schedule);
+    backend.get_error = ErrorCode::ETCD_OPERATION_ERROR;
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR, coordinator.RunOnce());
+    EXPECT_EQ(before.errors + 1,
+              metrics
+                  .get_snapshot_operation(
+                      HAMetricManager::SnapshotOperation::Schedule)
+                  .errors);
+    EXPECT_EQ(0u, lease_factory_calls);
+    backend.get_error = ErrorCode::OK;
+    coordinator.Start();
+    EXPECT_TRUE(coordinator.IsRunning());
+    coordinator.Stop();
+    EXPECT_FALSE(coordinator.IsRunning());
+}
+
+TEST(BatchOpLogSnapshotCoordinatorTest,
+     LeaseLossAndCatchUpAreNotPublicationSuccess) {
+    auto backend = std::make_shared<RecordingBackend>();
+    const auto add_batch = [&](uint64_t id) {
+        auto batch = MakeBatch();
+        batch.batch_id = batch.first_seq = batch.last_seq = id;
+        batch.entries[0].sequence_id = id;
+        backend->Put(BuildBatchRecordKey("cluster", id),
+                     EncodeOpLogBatchRecord(batch));
+        backend->Put(BuildDurablePrefixKey("cluster"),
+                     EncodeDurablePrefix({.batch_id = id, .last_seq = id}));
+    };
+    add_batch(1);
+    backend->Put(BuildProducerViewKey("cluster"), "7");
+    backend->Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"), "101");
+    HotStandbyConfig config;
+    config.enable_verification = false;
+    config.oplog_poll_interval_ms = 1;
+    HotStandbyService standby(config);
+    standby.SetCatchUpBatchKvBackendForTesting(backend);
+    ASSERT_EQ(ErrorCode::OK, standby.Start("", "", "cluster"));
+    const auto wait_for_batch = [&](uint64_t id) {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(3);
+        while (std::chrono::steady_clock::now() < deadline) {
+            auto prefix = standby.GetLastAppliedBatchOpLogSnapshotPrefix();
+            if (prefix && prefix->batch_id == id) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        return false;
+    };
+    ASSERT_TRUE(wait_for_batch(1));
+    RecordingObjectStore objects;
+    SnapshotMaintenanceLease* active_lease = nullptr;
+    BatchOpLogSnapshotCoordinatorConfig coordinator_config;
+    coordinator_config.snapshot_root = "snapshots";
+    coordinator_config.snapshot_interval_seconds = 0;
+    BatchOpLogSnapshotCoordinator coordinator(
+        standby, *backend, objects, "cluster", coordinator_config, [&] {
+            auto lease =
+                SnapshotMaintenanceLease::MakeForTesting("cluster", "101", 4);
+            active_lease = lease.get();
+            return lease;
+        });
+    auto& metrics = HAMetricManager::instance();
+    using Operation = HAMetricManager::SnapshotOperation;
+    const auto before = metrics.get_snapshot_operation(Operation::Publish);
+    const auto lost = metrics.get_snapshot_runtime().lease_lost_total;
+    objects.on_upload = [] {
+        throw std::runtime_error("upload failed with held lease");
+    };
+    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, coordinator.RunOnce());
+    EXPECT_EQ(lost, metrics.get_snapshot_runtime().lease_lost_total);
+    objects.on_upload = [&] {
+        active_lease->Release();
+        throw std::runtime_error("upload failed after lease loss");
+    };
+    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, coordinator.RunOnce());
+    EXPECT_EQ(lost + 1, metrics.get_snapshot_runtime().lease_lost_total);
+
+    objects.on_upload = [&] {
+        backend->pause_replay = true;
+        add_batch(2);
+        active_lease->Release();
+    };
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, coordinator.RunOnce());
+    EXPECT_EQ(lost + 2, metrics.get_snapshot_runtime().lease_lost_total);
+    EXPECT_EQ(before.errors + 1,
+              metrics.get_snapshot_operation(Operation::Publish).errors);
+    EXPECT_EQ(2u, metrics.get_snapshot_runtime().catch_up_target_batch);
+    EXPECT_FALSE(
+        backend->Contains(ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+    EXPECT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_EQ(HAMetricManager::SnapshotSkipReason::CatchUp,
+              metrics.get_snapshot_runtime().skip_reason);
+    EXPECT_EQ(before.total + 1,
+              metrics.get_snapshot_operation(Operation::Publish).total);
+    objects.on_upload = {};
+    backend->pause_replay = false;
+    ASSERT_TRUE(wait_for_batch(2));
+    EXPECT_EQ(0u, metrics.get_snapshot_runtime().catch_up_target_batch);
+    EXPECT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_EQ(before.total + 2,
+              metrics.get_snapshot_operation(Operation::Publish).total);
+    EXPECT_EQ(before.errors + 1,
+              metrics.get_snapshot_operation(Operation::Publish).errors);
+    standby.Stop();
+}
+
+class SnapshotMaintenanceTest : public ::testing::TestWithParam<int> {};
+
+TEST_P(SnapshotMaintenanceTest, PublishesAndPrunesDespiteGcFailure) {
+    auto backend = std::make_shared<RecordingBackend>();
+    ASSERT_EQ(ErrorCode::OK, backend->Put(BuildBatchRecordKey("cluster", 1),
+                                          EncodeOpLogBatchRecord(MakeBatch())));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey("cluster"),
+                     EncodeDurablePrefix({.batch_id = 1, .last_seq = 1})));
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildProducerViewKey("cluster"), "7"));
+    const auto maintenance_key =
+        ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster");
+    ASSERT_EQ(ErrorCode::OK, backend->Put(maintenance_key, "101"));
+
+    HotStandbyConfig standby_config;
+    standby_config.enable_verification = false;
+    standby_config.oplog_poll_interval_ms = 1;
+    HotStandbyService standby(standby_config);
+    standby.SetCatchUpBatchKvBackendForTesting(backend);
+    ASSERT_EQ(ErrorCode::OK, standby.Start("", "", "cluster"));
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (std::chrono::steady_clock::now() < deadline) {
+        auto prefix = standby.GetLastAppliedBatchOpLogSnapshotPrefix();
+        if (prefix && prefix->batch_id == 1) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+
+    RecordingObjectStore object_store;
+    object_store.gc_failure = GetParam();
+    BatchOpLogSnapshotCoordinatorConfig config;
+    config.snapshot_root = "snapshots";
+    config.snapshot_interval_seconds = 0;
+    bool lease_busy = true;
+    BatchOpLogSnapshotCoordinator coordinator(
+        standby, *backend, object_store, "cluster", std::move(config), [&] {
+            return lease_busy ? nullptr
+                              : SnapshotMaintenanceLease::MakeForTesting(
+                                    "cluster", "101", 4);
+        });
+    auto& metrics = HAMetricManager::instance();
+    using Operation = HAMetricManager::SnapshotOperation;
+    const auto gc_before = metrics.get_snapshot_operation(Operation::Gc);
+    const auto publish_before =
+        metrics.get_snapshot_operation(Operation::Publish);
+    const auto prune_before = metrics.get_snapshot_operation(Operation::Prune);
+    EXPECT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_EQ(HAMetricManager::SnapshotSkipReason::LeaseBusy,
+              metrics.get_snapshot_runtime().skip_reason);
+    EXPECT_EQ(publish_before.total,
+              metrics.get_snapshot_operation(Operation::Publish).total);
+    lease_busy = false;
+
+    EXPECT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_TRUE(
+        backend->Contains(ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+    EXPECT_EQ(1u, coordinator.GetStatus().attempts);
+    EXPECT_TRUE(coordinator.GetStatus().catch_up_target.has_value());
+    EXPECT_FALSE(backend->Contains(
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey("cluster")));
+    auto second = MakeBatch();
+    second.batch_id = second.first_seq = second.last_seq = 2;
+    second.entries[0].sequence_id = 2;
+    ASSERT_EQ(ErrorCode::OK, backend->Put(BuildBatchRecordKey("cluster", 2),
+                                          EncodeOpLogBatchRecord(second)));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey("cluster"),
+                     EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+    const auto next_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (std::chrono::steady_clock::now() < next_deadline) {
+        const auto prefix = standby.GetLastAppliedBatchOpLogSnapshotPrefix();
+        if (prefix && prefix->batch_id == 2) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    ASSERT_EQ(2u, standby.GetLastAppliedBatchOpLogSnapshotPrefix()->batch_id);
+    ASSERT_EQ(ErrorCode::OK, coordinator.RunOnce());
+    EXPECT_EQ(2u, coordinator.GetStatus().attempts);
+    EXPECT_EQ(1u, backend->delete_count);
+    const auto runtime = metrics.get_snapshot_runtime();
+    EXPECT_TRUE(runtime.latest_created_at_ms.has_value());
+    EXPECT_TRUE(runtime.fallback_created_at_ms.has_value());
+    EXPECT_EQ(1u, runtime.compaction_floor);
+    EXPECT_EQ(1u, runtime.candidate_floor);
+    EXPECT_GT(runtime.snapshot_bytes, 0u);
+    EXPECT_EQ(publish_before.total + 2,
+              metrics.get_snapshot_operation(Operation::Publish).total);
+    EXPECT_EQ(publish_before.errors,
+              metrics.get_snapshot_operation(Operation::Publish).errors);
+    EXPECT_EQ(gc_before.total + 2,
+              metrics.get_snapshot_operation(Operation::Gc).total);
+    EXPECT_EQ(gc_before.errors + (GetParam() == 0 ? 0 : 2),
+              metrics.get_snapshot_operation(Operation::Gc).errors);
+    EXPECT_EQ(prune_before.errors,
+              metrics.get_snapshot_operation(Operation::Prune).errors);
+    EXPECT_FALSE(backend->Contains(BuildBatchRecordKey("cluster", 1)));
+    EXPECT_TRUE(backend->Contains(BuildBatchRecordKey("cluster", 2)));
+    standby.Stop();
+}
+
+INSTANTIATE_TEST_SUITE_P(GcOutcomes, SnapshotMaintenanceTest,
+                         ::testing::Values(0, 1, 2));
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/gc_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/gc_test.cpp
new file mode 100644
index 0000000000..38c99b3895
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/gc_test.cpp
@@ -0,0 +1,185 @@
+#include "ha_metric_manager.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_gc.h"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <map>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+
+namespace mooncake::test {
+
+namespace {
+
+class FakeBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        auto it = values.find(std::string(key));
+        if (it == values.end()) return ErrorCode::ETCD_KEY_NOT_EXIST;
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view, std::string_view) override {
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view, std::string_view, size_t,
+                    std::vector<KvPair>&) override {
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
+
+    std::map<std::string, std::string> values;
+};
+
+class RecordingObjectStore final : public SnapshotObjectStore {
+   public:
+    tl::expected<void, std::string> UploadBuffer(
+        const std::string&, const std::vector<uint8_t>&) override {
+        return {};
+    }
+
+    tl::expected<void, std::string> DownloadBuffer(
+        const std::string& key, std::vector<uint8_t>& bytes) override {
+        auto it = objects.find(key);
+        if (it == objects.end()) return tl::make_unexpected("missing");
+        bytes = it->second;
+        return {};
+    }
+
+    tl::expected<void, std::string> UploadString(const std::string&,
+                                                 const std::string&) override {
+        return {};
+    }
+
+    tl::expected<void, std::string> DownloadString(
+        const std::string& key, std::string& value) override {
+        std::vector<uint8_t> bytes;
+        auto result = DownloadBuffer(key, bytes);
+        if (!result) return result;
+        value.assign(bytes.begin(), bytes.end());
+        return {};
+    }
+
+    tl::expected<void, std::string> DeleteObjectsWithPrefix(
+        const std::string& prefix) override {
+        deleted.push_back(prefix);
+        return {};
+    }
+
+    tl::expected<void, std::string> ListObjectsWithPrefix(
+        const std::string& prefix, std::vector<std::string>& keys) override {
+        for (const auto& [key, _] : objects)
+            if (key.starts_with(prefix)) keys.push_back(key);
+        return {};
+    }
+
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override {
+        auto it = objects.find(key);
+        if (it == objects.end()) return tl::make_unexpected("missing");
+        return SnapshotObjectInspection{
+            .stored_size = it->second.size(),
+            .crc32c = Crc32cValue(it->second.data(), it->second.size())};
+    }
+
+    std::string GetConnectionInfo() const override { return "test"; }
+
+    std::vector<std::string> deleted;
+    std::map<std::string, std::vector<uint8_t>> objects;
+};
+
+ha::BatchOpLogSnapshotDescriptor MakeDescriptor(const std::string& root,
+                                                uint64_t batch_id) {
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = ha::BuildBatchOpLogSnapshotId(batch_id, 1);
+    descriptor.last_included_seq = batch_id * 10;
+    descriptor.last_included_batch_id = batch_id;
+    descriptor.producer_view_version = 1;
+    descriptor.manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey(root, descriptor.snapshot_id);
+    descriptor.manifest_size = 1;
+    descriptor.manifest_crc32c = 0;
+    descriptor.created_at_ms = 1;
+    return descriptor;
+}
+
+}  // namespace
+
+TEST(BatchOpLogSnapshotGcTest, PointerMismatchSkipsDeletion) {
+    FakeBackend backend;
+    RecordingObjectStore object_store;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("c", "1");
+    backend.values[::mooncake::ha::BuildBatchOpLogSnapshotLatestKey("c")] =
+        "changed";
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              BatchOpLogSnapshotGc(backend, object_store, "c", "r")
+                  .Run(*lease, "published", std::nullopt));
+    EXPECT_TRUE(object_store.deleted.empty());
+}
+
+TEST(BatchOpLogSnapshotGcTest, DeletesOnlyUnprotectedAttempt) {
+    HAMetricManager::instance().reset_snapshot_runtime(true);
+    constexpr std::string_view kRoot = "snapshots";
+    FakeBackend backend;
+    RecordingObjectStore object_store;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("c", "1");
+    auto descriptor = MakeDescriptor(std::string(kRoot), 2);
+    ha::BatchOpLogSnapshotManifest manifest;
+    manifest.snapshot_id = descriptor.snapshot_id;
+    manifest.last_included_batch_id = descriptor.last_included_batch_id;
+    manifest.last_included_seq = descriptor.last_included_seq;
+    const std::vector<uint8_t> segment_bytes = {0};
+    manifest.segments = {ha::BuildBatchOpLogSnapshotSegmentsKey(
+                             std::string(kRoot), descriptor.snapshot_id),
+                         1, Crc32cValue(segment_bytes.data(), 1)};
+    const std::string manifest_json =
+        ha::EncodeBatchOpLogSnapshotManifest(manifest);
+    descriptor.manifest_size = manifest_json.size();
+    descriptor.manifest_crc32c =
+        Crc32cValue(manifest_json.data(), manifest_json.size());
+    const std::string descriptor_json =
+        ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+    backend.values[::mooncake::ha::BuildBatchOpLogSnapshotLatestKey("c")] =
+        descriptor_json;
+    object_store.objects[descriptor.manifest_key] =
+        std::vector<uint8_t>(manifest_json.begin(), manifest_json.end());
+    object_store.objects[manifest.segments.key] = segment_bytes;
+
+    const auto protected_prefix =
+        ha::BuildBatchOpLogSnapshotArtifactPrefix(std::string(kRoot), "2-1");
+    const auto stale_prefix =
+        ha::BuildBatchOpLogSnapshotArtifactPrefix(std::string(kRoot), "1-1");
+    object_store.objects[protected_prefix + "marker"] = {1};
+    object_store.objects[stale_prefix + "marker"] = {2};
+
+    EXPECT_EQ(ErrorCode::OK, BatchOpLogSnapshotGc(backend, object_store, "c",
+                                                  std::string(kRoot))
+                                 .Run(*lease, descriptor_json, std::nullopt));
+    ASSERT_EQ(1U, object_store.deleted.size());
+    EXPECT_EQ(
+        1u,
+        HAMetricManager::instance().get_snapshot_runtime().gc_orphan_prefixes);
+    EXPECT_EQ(
+        1u,
+        HAMetricManager::instance().get_snapshot_runtime().gc_deleted_prefixes);
+    EXPECT_EQ(stale_prefix, object_store.deleted.front());
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/metadata_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/metadata_test.cpp
new file mode 100644
index 0000000000..3518e65a4f
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/metadata_test.cpp
@@ -0,0 +1,272 @@
+#include "ha/snapshot/batch_oplog/metadata.h"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <sstream>
+#include <string>
+
+#if __has_include(<jsoncpp/json/json.h>)
+#include <jsoncpp/json/json.h>
+#else
+#include <json/json.h>
+#endif
+
+namespace mooncake::ha::test {
+
+namespace {
+
+BatchOpLogSnapshotDescriptor MakeDescriptor() {
+    return {
+        .snapshot_id = "9-12345",
+        .last_included_seq = 42,
+        .last_included_batch_id = 9,
+        .producer_view_version = 7,
+        .manifest_key = "snapshots/batch-oplog/9-12345/manifest.json",
+        .manifest_size = 128,
+        .manifest_crc32c = 17,
+        .created_at_ms = 1700000000000,
+    };
+}
+
+BatchOpLogSnapshotManifest MakeManifest() {
+    return {
+        .snapshot_id = "9-12345",
+        .last_included_seq = 42,
+        .last_included_batch_id = 9,
+        .producer_view_version = 7,
+        .segments = {.key = "snapshots/batch-oplog/9-12345/segments.bin",
+                     .stored_size = 64,
+                     .crc32c = 18},
+        .object_chunks =
+            {
+                {.chunk_index = 0,
+                 .key = "snapshots/batch-oplog/9-12345/objects/0.bin",
+                 .object_count = 100,
+                 .stored_size = 1024,
+                 .crc32c = 19},
+                {.chunk_index = 1,
+                 .key = "snapshots/batch-oplog/9-12345/objects/1.bin",
+                 .object_count = 50,
+                 .stored_size = 512,
+                 .crc32c = 20},
+            },
+    };
+}
+
+Json::Value ParseJson(const std::string& value) {
+    Json::CharReaderBuilder builder;
+    Json::Value root;
+    std::string errors;
+    std::istringstream stream(value);
+    EXPECT_TRUE(Json::parseFromStream(builder, stream, &root, &errors))
+        << errors;
+    return root;
+}
+
+std::string WriteJson(const Json::Value& root) {
+    Json::StreamWriterBuilder builder;
+    builder["indentation"] = "";
+    return Json::writeString(builder, root);
+}
+
+void ExpectDescriptorRejected(const std::string& json) {
+    auto decoded = DecodeBatchOpLogSnapshotDescriptor(json);
+    ASSERT_FALSE(decoded.has_value());
+    EXPECT_FALSE(decoded.error().empty());
+}
+
+void ExpectManifestRejected(const std::string& json) {
+    SCOPED_TRACE(json);
+    auto decoded = DecodeBatchOpLogSnapshotManifest(json);
+    ASSERT_FALSE(decoded.has_value());
+    EXPECT_FALSE(decoded.error().empty());
+}
+
+}  // namespace
+
+TEST(BatchOpLogSnapshotTypesTest, DescriptorRoundTripsCompactJson) {
+    const auto encoded = EncodeBatchOpLogSnapshotDescriptor(MakeDescriptor());
+    EXPECT_EQ(encoded.find('\n'), std::string::npos);
+
+    auto json = ParseJson(encoded);
+    json["future_optional_field"] = true;
+
+    auto decoded = DecodeBatchOpLogSnapshotDescriptor(WriteJson(json));
+    ASSERT_TRUE(decoded.has_value()) << decoded.error();
+    EXPECT_EQ(decoded->schema_version, kBatchOpLogSnapshotSchemaVersion);
+    EXPECT_EQ(decoded->snapshot_format, kBatchOpLogSnapshotFormat);
+    EXPECT_EQ(decoded->snapshot_id, "9-12345");
+    EXPECT_EQ(decoded->last_included_seq, 42u);
+    EXPECT_EQ(decoded->last_included_batch_id, 9u);
+    EXPECT_EQ(decoded->producer_view_version, 7u);
+    EXPECT_EQ(decoded->manifest_key,
+              "snapshots/batch-oplog/9-12345/manifest.json");
+    EXPECT_EQ(decoded->manifest_size, 128u);
+    EXPECT_EQ(decoded->manifest_crc32c, 17u);
+    EXPECT_EQ(decoded->created_at_ms, 1700000000000);
+}
+
+TEST(BatchOpLogSnapshotTypesTest, ManifestRoundTripsChunksAndAllowsEmptySet) {
+    auto encoded = EncodeBatchOpLogSnapshotManifest(MakeManifest());
+    EXPECT_EQ(encoded.find('\n'), std::string::npos);
+    auto json = ParseJson(encoded);
+    json["future_optional_field"] = true;
+    auto decoded = DecodeBatchOpLogSnapshotManifest(WriteJson(json));
+    ASSERT_TRUE(decoded.has_value()) << decoded.error();
+    ASSERT_EQ(decoded->object_chunks.size(), 2u);
+    EXPECT_EQ(decoded->segments.stored_size, 64u);
+    EXPECT_EQ(decoded->object_chunks[1].chunk_index, 1u);
+    EXPECT_EQ(decoded->object_chunks[1].object_count, 50u);
+
+    auto empty = MakeManifest();
+    empty.object_chunks.clear();
+    auto decoded_empty = DecodeBatchOpLogSnapshotManifest(
+        EncodeBatchOpLogSnapshotManifest(empty));
+    ASSERT_TRUE(decoded_empty.has_value()) << decoded_empty.error();
+    EXPECT_TRUE(decoded_empty->object_chunks.empty());
+}
+
+TEST(BatchOpLogSnapshotTypesTest, JsonRoundTripPreservesEscapedKeys) {
+    auto descriptor = MakeDescriptor();
+    descriptor.manifest_key = R"(snapshots/"quoted"/manifest\key.json)";
+    auto decoded_descriptor = DecodeBatchOpLogSnapshotDescriptor(
+        EncodeBatchOpLogSnapshotDescriptor(descriptor));
+    ASSERT_TRUE(decoded_descriptor.has_value()) << decoded_descriptor.error();
+    EXPECT_EQ(decoded_descriptor->manifest_key, descriptor.manifest_key);
+
+    auto manifest = MakeManifest();
+    manifest.segments.key = R"(snapshots/"quoted"/segments\key.bin)";
+    manifest.object_chunks[0].key = R"(snapshots/"quoted"/objects\0.bin)";
+    auto decoded_manifest = DecodeBatchOpLogSnapshotManifest(
+        EncodeBatchOpLogSnapshotManifest(manifest));
+    ASSERT_TRUE(decoded_manifest.has_value()) << decoded_manifest.error();
+    EXPECT_EQ(decoded_manifest->segments.key, manifest.segments.key);
+    EXPECT_EQ(decoded_manifest->object_chunks[0].key,
+              manifest.object_chunks[0].key);
+}
+
+TEST(BatchOpLogSnapshotTypesTest, RejectsInvalidDescriptorJson) {
+    const auto encoded = EncodeBatchOpLogSnapshotDescriptor(MakeDescriptor());
+    auto json = ParseJson(encoded);
+
+    ExpectDescriptorRejected("{");
+    ExpectDescriptorRejected("[]");
+    ExpectDescriptorRejected(encoded.substr(0, encoded.size() - 1) +
+                             ",\"schema_version\":1}");
+
+    auto invalid = json;
+    invalid.removeMember("manifest_key");
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["manifest_size"] = "128";
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["schema_version"] = 2;
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["snapshot_format"] = "standby-oplog-materialized/v2";
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["last_included_batch_id"] = Json::UInt64(0);
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["snapshot_id"] = "10-12345";
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["manifest_key"] = "";
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["manifest_size"] = Json::UInt64(0);
+    ExpectDescriptorRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["created_at_ms"] = Json::Int64(-1);
+    ExpectDescriptorRejected(WriteJson(invalid));
+
+    auto overflow = encoded;
+    const std::string old_value = "\"last_included_seq\":42";
+    const auto position = overflow.find(old_value);
+    ASSERT_NE(position, std::string::npos);
+    overflow.replace(position, old_value.size(),
+                     "\"last_included_seq\":18446744073709551616");
+    ExpectDescriptorRejected(overflow);
+}
+
+TEST(BatchOpLogSnapshotTypesTest, AcceptsAnEmptyCursor) {
+    auto descriptor = MakeDescriptor();
+    descriptor.snapshot_id = "0-12345";
+    descriptor.last_included_seq = 0;
+    descriptor.last_included_batch_id = 0;
+
+    auto decoded = DecodeBatchOpLogSnapshotDescriptor(
+        EncodeBatchOpLogSnapshotDescriptor(descriptor));
+    ASSERT_TRUE(decoded.has_value()) << decoded.error();
+}
+
+TEST(BatchOpLogSnapshotTypesTest, RejectsInvalidManifestJson) {
+    const auto encoded = EncodeBatchOpLogSnapshotManifest(MakeManifest());
+    auto json = ParseJson(encoded);
+
+    ExpectManifestRejected(encoded.substr(0, encoded.size() - 1) +
+                           ",\"schema_version\":1}");
+
+    auto invalid = json;
+    invalid.removeMember("segments");
+    ExpectManifestRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["segments"]["key"] = "";
+    ExpectManifestRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["segments"]["crc32c"] =
+        Json::UInt64(static_cast<uint64_t>(UINT32_MAX) + 1);
+    ExpectManifestRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["object_chunks"][1]["chunk_index"] = Json::UInt64(2);
+    ExpectManifestRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["object_chunks"][0]["object_count"] = Json::UInt64(0);
+    ExpectManifestRejected(WriteJson(invalid));
+    invalid = json;
+    invalid["snapshot_id"] = "8-12345";
+    ExpectManifestRejected(WriteJson(invalid));
+}
+
+TEST(BatchOpLogSnapshotTypesTest, BuildsControlAndArtifactKeys) {
+    EXPECT_EQ(BuildBatchOpLogSnapshotRoot("cluster-a/"),
+              "mooncake_master_snapshot/cluster-a");
+    EXPECT_TRUE(BuildBatchOpLogSnapshotRoot("../cluster").empty());
+    EXPECT_EQ(BuildBatchOpLogSnapshotMaintenanceKey("cluster-a/"),
+              "/oplog/cluster-a/snapshot/maintenance");
+    EXPECT_EQ(BuildBatchOpLogSnapshotLatestKey("cluster-a"),
+              "/oplog/cluster-a/snapshot/latest");
+    EXPECT_EQ(BuildBatchOpLogSnapshotFallbackKey("cluster-a"),
+              "/oplog/cluster-a/snapshot/fallback");
+    EXPECT_EQ(BuildBatchOpLogSnapshotCompactionFloorKey("cluster-a"),
+              "/oplog/cluster-a/snapshot/compaction_floor");
+    EXPECT_TRUE(BuildBatchOpLogSnapshotLatestKey("../cluster").empty());
+
+    const auto snapshot_id = BuildBatchOpLogSnapshotId(9, 12345);
+    ASSERT_EQ(snapshot_id, "9-12345");
+    EXPECT_EQ(BuildBatchOpLogSnapshotArtifactPrefix("snapshots/", snapshot_id),
+              "snapshots/batch-oplog/9-12345/");
+    EXPECT_EQ(BuildBatchOpLogSnapshotDescriptorKey("snapshots", snapshot_id),
+              "snapshots/batch-oplog/9-12345/descriptor.json");
+    EXPECT_EQ(BuildBatchOpLogSnapshotManifestKey("snapshots/", snapshot_id),
+              "snapshots/batch-oplog/9-12345/manifest.json");
+    EXPECT_EQ(BuildBatchOpLogSnapshotSegmentsKey("snapshots", snapshot_id),
+              "snapshots/batch-oplog/9-12345/segments.bin");
+    EXPECT_EQ(
+        BuildBatchOpLogSnapshotObjectChunkKey("snapshots", snapshot_id, 7),
+        "snapshots/batch-oplog/9-12345/objects/7.bin");
+}
+
+TEST(BatchOpLogSnapshotTypesTest, RejectsUnsafeSnapshotIdInArtifactKeys) {
+    EXPECT_TRUE(BuildBatchOpLogSnapshotId(9, 0).empty());
+    EXPECT_TRUE(
+        BuildBatchOpLogSnapshotDescriptorKey("snapshots", "9-x").empty());
+    EXPECT_TRUE(BuildBatchOpLogSnapshotDescriptorKey("snapshots",
+                                                     "9-12345/../../latest")
+                    .empty());
+}
+
+}  // namespace mooncake::ha::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/promotion_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/promotion_test.cpp
new file mode 100644
index 0000000000..f9bfbb4ed8
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/promotion_test.cpp
@@ -0,0 +1,219 @@
+#include "ha/snapshot/batch_oplog/promotion.h"
+
+#include <gtest/gtest.h>
+
+#include <map>
+#include <mutex>
+#include <type_traits>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
+#include "ha/snapshot/object/backends/local/local_file_snapshot_object_store.h"
+#include "ha/standby_controller.h"
+#include "hot_standby_service.h"
+#include "master_service.h"
+
+namespace mooncake::test {
+namespace {
+
+class MemoryBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin, std::string_view end, size_t limit,
+                    std::vector<KvPair>& output) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        output.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin && key < end &&
+                (limit == 0 || output.size() < limit)) {
+                output.push_back({key, value});
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        for (const auto& put : txn.puts) {
+            auto error = Put(put.key, put.value);
+            if (error != ErrorCode::OK) {
+                return error;
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+   private:
+    std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+};
+
+std::unique_ptr<HotStandbyService> MakeBatchSnapshotStandby(
+    const std::shared_ptr<MemoryBackend>& backend,
+    LocalFileSnapshotObjectStore& object_store,
+    bool enable_oplog_following = true) {
+    HotStandbyConfig config;
+    config.enable_snapshot_bootstrap = false;
+    config.enable_oplog_following = enable_oplog_following;
+    config.enable_verification = false;
+    config.oplog_poll_interval_ms = 1;
+    config.batch_oplog_retry_timeout_sec = 0;
+    auto standby = std::make_unique<HotStandbyService>(config);
+    standby->SetCatchUpBatchKvBackendForTesting(backend);
+    standby->SetBatchOpLogSnapshotProvider(
+        std::make_unique<BatchOpLogSnapshotProvider>(
+            "promotion-test", *backend, object_store, "snapshots"));
+    return standby;
+}
+
+StandbyObjectMetadata MakeMetadata(uint64_t size) {
+    StandbyObjectMetadata metadata;
+    metadata.size = size;
+    return metadata;
+}
+
+}  // namespace
+
+static_assert(std::is_move_constructible_v<BatchOpLogPromotionHandoff>);
+static_assert(!std::is_copy_constructible_v<BatchOpLogPromotionHandoff>);
+static_assert(std::is_move_constructible_v<ha::PromotionContext>);
+static_assert(!std::is_copy_constructible_v<ha::PromotionContext>);
+
+TEST(BatchOpLogPromotionTest, EmptyStoreHandoffIsMoveOnly) {
+    auto store = std::make_unique<StandbyMetadataStore>();
+    BatchOpLogPromotionHandoff handoff;
+    handoff.metadata_store = std::move(store);
+    handoff.applied_cursor = {.batch_id = 0, .last_seq = 0};
+
+    auto moved = std::move(handoff);
+    ASSERT_TRUE(moved.metadata_store);
+    EXPECT_EQ(0u, moved.metadata_store->GetKeyCount());
+
+    ha::PromotionContext context;
+    context.metadata_store = std::move(moved.metadata_store);
+    EXPECT_TRUE(context.metadata_store);
+}
+
+TEST(BatchOpLogPromotionTest, StoreDrainsBoundedChunksAcrossTenants) {
+    StandbyMetadataStore store;
+    ASSERT_TRUE(store.PutMetadata("tenant-a", "a1", MakeMetadata(1)));
+    ASSERT_TRUE(store.PutMetadata("tenant-a", "a2", MakeMetadata(2)));
+    ASSERT_TRUE(store.PutMetadata("tenant-b", "b1", MakeMetadata(3)));
+
+    std::vector<StandbyObjectEntry> chunk;
+    ASSERT_TRUE(store.DrainChunk(2, chunk));
+    EXPECT_EQ(2u, chunk.size());
+    EXPECT_EQ(1u, store.GetKeyCount());
+    ASSERT_TRUE(store.DrainChunk(2, chunk));
+    EXPECT_EQ(1u, chunk.size());
+    EXPECT_EQ(0u, store.GetKeyCount());
+    ASSERT_TRUE(store.DrainChunk(2, chunk));
+    EXPECT_TRUE(chunk.empty());
+    EXPECT_FALSE(store.DrainChunk(0, chunk));
+}
+
+TEST(BatchOpLogPromotionTest, DetachesStoreWithFinalCursorAndProducerView) {
+    auto backend = std::make_shared<MemoryBackend>();
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey("promotion-test"),
+                     EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildProducerViewKey("promotion-test"), "7"));
+    LocalFileSnapshotObjectStore object_store(
+        "/tmp/mooncake-n07-promotion-success");
+    auto standby = MakeBatchSnapshotStandby(backend, object_store);
+    ASSERT_EQ(ErrorCode::OK, standby->Start("", "", "promotion-test"));
+
+    auto handoff = standby->PromoteAndDetachBatchOpLogStore();
+
+    ASSERT_TRUE(handoff.has_value());
+    ASSERT_TRUE(handoff->metadata_store);
+    EXPECT_EQ(DurablePrefix(), handoff->applied_cursor);
+    EXPECT_EQ(7, handoff->producer_view_version);
+    std::vector<StandbyObjectEntry> ignored;
+    EXPECT_FALSE(standby->ExportMetadataSnapshot(ignored));
+}
+
+TEST(BatchOpLogPromotionTest, EmptyStoreWithoutDurablePrefixUsesZeroCursor) {
+    auto backend = std::make_shared<MemoryBackend>();
+    LocalFileSnapshotObjectStore object_store(
+        "/tmp/mooncake-n07-promotion-missing-cursor");
+    auto standby = MakeBatchSnapshotStandby(backend, object_store);
+    ASSERT_EQ(ErrorCode::OK, standby->Start("", "", "promotion-test"));
+
+    auto handoff = standby->PromoteAndDetachBatchOpLogStore();
+
+    ASSERT_TRUE(handoff.has_value());
+    EXPECT_EQ(DurablePrefix(), handoff->applied_cursor);
+    ASSERT_TRUE(handoff->metadata_store);
+    EXPECT_EQ(StandbyState::STOPPED, standby->GetState());
+    std::vector<StandbyObjectEntry> retained;
+    EXPECT_FALSE(standby->ExportMetadataSnapshot(retained));
+}
+
+TEST(BatchOpLogPromotionTest, SnapshotOnlyProviderFallsBackToLegacyExport) {
+    auto backend = std::make_shared<MemoryBackend>();
+    LocalFileSnapshotObjectStore object_store(
+        "/tmp/mooncake-n07-promotion-snapshot-only");
+    auto standby = MakeBatchSnapshotStandby(backend, object_store,
+                                            /*enable_oplog_following=*/false);
+    ASSERT_EQ(ErrorCode::OK, standby->Start("", "", "promotion-test"));
+
+    EXPECT_FALSE(standby->IsBatchOpLogSnapshotMode());
+    auto detach = standby->PromoteAndDetachBatchOpLogStore();
+    ASSERT_FALSE(detach.has_value());
+    EXPECT_EQ(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS, detach.error());
+    StandbySnapshot snapshot;
+    ASSERT_EQ(ErrorCode::OK, standby->PromoteAndExportSnapshot(snapshot));
+    EXPECT_EQ(0u, snapshot.oplog_sequence_id);
+    EXPECT_TRUE(snapshot.objects.empty());
+}
+
+TEST(BatchOpLogPromotionTest, RecreatesStoreAfterBatchDetachOnRestart) {
+    auto backend = std::make_shared<MemoryBackend>();
+    LocalFileSnapshotObjectStore object_store(
+        "/tmp/mooncake-n07-promotion-restart");
+    auto standby = MakeBatchSnapshotStandby(backend, object_store);
+    ASSERT_EQ(ErrorCode::OK, standby->Start("", "", "promotion-test"));
+    ASSERT_TRUE(standby->PromoteAndDetachBatchOpLogStore().has_value());
+
+    ASSERT_EQ(ErrorCode::OK, standby->Start("", "", "promotion-test"));
+    EXPECT_EQ(StandbyState::WATCHING, standby->GetState());
+    EXPECT_EQ(0u, standby->GetMetadataCount());
+}
+
+TEST(BatchOpLogPromotionTest, EmptyStoreRestoresWithoutChunks) {
+    MasterService service(
+        MasterServiceConfig::builder().set_enable_ha(false).build());
+    BatchOpLogPromotionHandoff handoff;
+    handoff.metadata_store = std::make_unique<StandbyMetadataStore>();
+    handoff.applied_cursor = {.batch_id = 0, .last_seq = 0};
+
+    EXPECT_TRUE(service.RestoreFromBatchOpLogPromotion(std::move(handoff), 1)
+                    .has_value());
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/provider_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/provider_test.cpp
new file mode 100644
index 0000000000..d4d26f2849
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/provider_test.cpp
@@ -0,0 +1,372 @@
+#include "ha_metric_manager.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_provider.h"
+
+#include <gtest/gtest.h>
+#include <cstdlib>
+#include <filesystem>
+
+#include <map>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/oplog/oplog_applier.h"
+#include "ha/oplog/oplog_batch_types.h"
+#include "ha/snapshot/batch_oplog/codec.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/backends/local/local_file_snapshot_object_store.h"
+
+namespace mooncake::test {
+namespace {
+
+class EmptyBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin, std::string_view end, size_t limit,
+                    std::vector<KvPair>& output) override {
+        if (begin == fail_range_begin) return ErrorCode::ETCD_OPERATION_ERROR;
+        output.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin && key < end &&
+                (limit == 0 || output.size() < limit)) {
+                output.push_back({key, value});
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        for (const auto& put : txn.puts) {
+            values_[put.key] = put.value;
+        }
+        return ErrorCode::OK;
+    }
+
+    std::string fail_range_begin;
+
+   private:
+    std::map<std::string, std::string> values_;
+};
+
+class BatchOpLogSnapshotProviderTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        HAMetricManager::instance().reset_snapshot_runtime(true);
+        char pattern[] = "/tmp/mooncake-provider-XXXXXX";
+        const char* root = mkdtemp(pattern);
+        ASSERT_NE(nullptr, root);
+        root_ = root;
+    }
+    void TearDown() override { std::filesystem::remove_all(root_); }
+    std::string root_;
+};
+
+}  // namespace
+
+TEST_F(BatchOpLogSnapshotProviderTest,
+       FailedBootstrapStillReportsObservedFloor) {
+    EmptyBackend backend;
+    LocalFileSnapshotObjectStore objects(root_);
+    backend.Put(ha::BuildBatchOpLogSnapshotCompactionFloorKey("clusterA"),
+                "42");
+    BatchOpLogSnapshotProvider provider("clusterA", backend, objects,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    EXPECT_FALSE(provider.RestoreBaseline(metadata, registry));
+    EXPECT_EQ(
+        42u,
+        HAMetricManager::instance().get_snapshot_runtime().compaction_floor);
+    // A decodable pointer with a missing descriptor/manifest fails before
+    // replay too.
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = "42-1";
+    descriptor.last_included_batch_id = descriptor.last_included_seq = 42;
+    descriptor.manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey("snapshots", "42-1");
+    descriptor.manifest_size = 1;
+    backend.Put(ha::BuildBatchOpLogSnapshotLatestKey("clusterA"),
+                ha::EncodeBatchOpLogSnapshotDescriptor(descriptor));
+    HAMetricManager::instance().reset_snapshot_runtime(true);
+    EXPECT_FALSE(provider.RestoreBaseline(metadata, registry));
+    EXPECT_EQ(
+        42u,
+        HAMetricManager::instance().get_snapshot_runtime().compaction_floor);
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest,
+       FailedSecondPageRetainsCompleteBatchProgress) {
+    EmptyBackend backend;
+    LocalFileSnapshotObjectStore objects(root_);
+    for (uint64_t id = 1; id <= 1025; ++id) {
+        OpLogEntry entry;
+        entry.sequence_id = id;
+        entry.op_type = OpType::REMOVE;
+        entry.object_key = "missing";
+        OpLogBatchRecord batch;
+        batch.batch_id = batch.first_seq = batch.last_seq = id;
+        batch.entries = {entry};
+        backend.Put(BuildBatchRecordKey("clusterA", id),
+                    EncodeOpLogBatchRecord(batch));
+    }
+    backend.Put(BuildDurablePrefixKey("clusterA"),
+                EncodeDurablePrefix({.batch_id = 1025, .last_seq = 1025}));
+    backend.fail_range_begin =
+        BuildBatchRecordRange("clusterA", 1024).begin_key;
+    BatchOpLogSnapshotProvider provider("clusterA", backend, objects,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    OpLogApplier applier(&metadata, "clusterA");
+    const auto result = provider.RestoreBaseline(metadata, registry, &applier);
+    ASSERT_FALSE(result);
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR, result.error());
+    EXPECT_EQ(1025u, applier.GetExpectedSequenceId());
+    EXPECT_EQ(
+        1024u,
+        HAMetricManager::instance().get_snapshot_runtime().suffix_batches);
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest, AllAbsentNamespaceIsAnEmptyBaseline) {
+    EmptyBackend backend;
+    LocalFileSnapshotObjectStore object_store(root_);
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+
+    auto result = provider.RestoreBaseline(metadata, registry);
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(0u, result->last_applied_seq);
+    EXPECT_EQ(0u, result->last_applied_batch_id);
+    std::string prefix;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Get(BuildDurablePrefixKey("clusterA"), prefix));
+    EXPECT_EQ(EncodeDurablePrefix({.batch_id = 0, .last_seq = 0}), prefix);
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest, RestoreHonorsCancellation) {
+    EmptyBackend backend;
+    LocalFileSnapshotObjectStore object_store(root_);
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    auto result = provider.RestoreBaseline(metadata, registry, nullptr, 0,
+                                           [] { return true; });
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(ErrorCode::ETCD_CTX_CANCELLED, result.error());
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest, EmptyCompleteHistoryIsAValidBaseline) {
+    EmptyBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    LocalFileSnapshotObjectStore object_store(root_);
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+
+    auto result = provider.RestoreBaseline(metadata, registry);
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(0u, result->last_included_seq);
+    EXPECT_EQ(0u, result->last_included_batch_id);
+    EXPECT_EQ(0u, metadata.GetKeyCount());
+    EXPECT_TRUE(registry.GetAllSegments().empty());
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest, UsesFallbackWhenLatestIsCorrupt) {
+    LocalFileSnapshotObjectStore object_store(root_);
+    EmptyBackend backend;
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+
+    const std::string snapshot_id = "0-7";
+    const std::string segments_key =
+        ha::BuildBatchOpLogSnapshotSegmentsKey("snapshots", snapshot_id);
+    const auto segments = EncodeBatchOpLogSnapshotSegments({});
+    ASSERT_TRUE(object_store.UploadBuffer(segments_key, segments));
+    ha::BatchOpLogSnapshotManifest manifest;
+    manifest.snapshot_id = snapshot_id;
+    manifest.segments = {
+        .key = segments_key,
+        .stored_size = segments.size(),
+        .crc32c = Crc32cValue(segments.data(), segments.size())};
+    const std::string manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey("snapshots", snapshot_id);
+    const std::string manifest_bytes =
+        ha::EncodeBatchOpLogSnapshotManifest(manifest);
+    ASSERT_TRUE(object_store.UploadString(manifest_key, manifest_bytes));
+
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = snapshot_id;
+    descriptor.manifest_key = manifest_key;
+    descriptor.manifest_size = manifest_bytes.size();
+    descriptor.manifest_crc32c =
+        Crc32cValue(manifest_bytes.data(), manifest_bytes.size());
+    const std::string descriptor_bytes =
+        ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+    const std::string descriptor_key =
+        ha::BuildBatchOpLogSnapshotDescriptorKey("snapshots", snapshot_id);
+    ASSERT_TRUE(object_store.UploadString(descriptor_key, descriptor_bytes));
+
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend.Put(ha::BuildBatchOpLogSnapshotLatestKey("clusterA"), "{}"));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("clusterA"),
+                          descriptor_bytes));
+
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    auto result = provider.RestoreBaseline(metadata, registry);
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(0u, result->last_included_seq);
+    EXPECT_EQ(0u, metadata.GetKeyCount());
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest, ReturnsFinalCursorAfterSuffixReplay) {
+    LocalFileSnapshotObjectStore object_store(root_);
+    EmptyBackend backend;
+
+    OpLogBatchRecord suffix_batch;
+    suffix_batch.batch_id = 2;
+    suffix_batch.first_seq = 2;
+    suffix_batch.last_seq = 2;
+    OpLogEntry suffix_entry;
+    suffix_entry.sequence_id = 2;
+    suffix_entry.op_type = OpType::REMOVE;
+    suffix_entry.tenant_id = "tenant";
+    suffix_entry.object_key = "suffix-key";
+    suffix_batch.entries.push_back(std::move(suffix_entry));
+    ASSERT_EQ(ErrorCode::OK, backend.Put(BuildBatchRecordKey("clusterA", 2),
+                                         EncodeOpLogBatchRecord(suffix_batch)));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+
+    const std::string snapshot_id = "1-7";
+    const auto segments = EncodeBatchOpLogSnapshotSegments({});
+    const std::string segments_key =
+        ha::BuildBatchOpLogSnapshotSegmentsKey("snapshots", snapshot_id);
+    ASSERT_TRUE(object_store.UploadBuffer(segments_key, segments));
+
+    ha::BatchOpLogSnapshotManifest manifest;
+    manifest.snapshot_id = snapshot_id;
+    manifest.last_included_seq = 1;
+    manifest.last_included_batch_id = 1;
+    manifest.segments = {
+        .key = segments_key,
+        .stored_size = segments.size(),
+        .crc32c = Crc32cValue(segments.data(), segments.size())};
+    const std::string manifest_bytes =
+        ha::EncodeBatchOpLogSnapshotManifest(manifest);
+    const std::string manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey("snapshots", snapshot_id);
+    ASSERT_TRUE(object_store.UploadString(manifest_key, manifest_bytes));
+
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = snapshot_id;
+    descriptor.last_included_seq = 1;
+    descriptor.last_included_batch_id = 1;
+    descriptor.manifest_key = manifest_key;
+    descriptor.manifest_size = manifest_bytes.size();
+    descriptor.manifest_crc32c =
+        Crc32cValue(manifest_bytes.data(), manifest_bytes.size());
+    const std::string descriptor_bytes =
+        ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+    const std::string descriptor_key =
+        ha::BuildBatchOpLogSnapshotDescriptorKey("snapshots", snapshot_id);
+    ASSERT_TRUE(object_store.UploadString(descriptor_key, descriptor_bytes));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotLatestKey("clusterA"),
+                          descriptor_bytes));
+
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    auto result = provider.RestoreBaseline(metadata, registry);
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(1u, result->last_included_seq);
+    EXPECT_EQ(1u, result->last_included_batch_id);
+    EXPECT_EQ(2u, result->last_applied_seq);
+    EXPECT_EQ(2u, result->last_applied_batch_id);
+    EXPECT_EQ(
+        1u, HAMetricManager::instance().get_snapshot_runtime().suffix_batches);
+    EXPECT_EQ(2u,
+              HAMetricManager::instance().get_snapshot_runtime().durable_batch);
+}
+
+TEST_F(BatchOpLogSnapshotProviderTest,
+       ReplaysCompleteHistoryAfterBothPointersAreInvalid) {
+    LocalFileSnapshotObjectStore object_store(root_);
+    EmptyBackend backend;
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend.Put(ha::BuildBatchOpLogSnapshotLatestKey("clusterA"), "{}"));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("clusterA"), "{}"));
+
+    for (uint64_t id = 1; id <= 2; ++id) {
+        OpLogEntry entry;
+        entry.sequence_id = id;
+        entry.op_type = OpType::REMOVE;
+        entry.tenant_id = "tenant";
+        entry.object_key = "key-" + std::to_string(id);
+        OpLogBatchRecord batch;
+        batch.batch_id = id;
+        batch.first_seq = id;
+        batch.last_seq = id;
+        batch.entries.push_back(std::move(entry));
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put(BuildBatchRecordKey("clusterA", id),
+                              EncodeOpLogBatchRecord(batch)));
+    }
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey("clusterA"),
+                          EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+
+    BatchOpLogSnapshotProvider provider("clusterA", backend, object_store,
+                                        "snapshots");
+    StandbyMetadataStore metadata;
+    StandbySegmentRegistry registry;
+    auto result = provider.RestoreBaseline(metadata, registry);
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(2u, result->last_applied_seq);
+    EXPECT_EQ(2u, result->last_applied_batch_id);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/pruning_coordinator_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/pruning_coordinator_test.cpp
new file mode 100644
index 0000000000..92ce4c3169
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/pruning_coordinator_test.cpp
@@ -0,0 +1,474 @@
+#include "ha_metric_manager.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_pruning_coordinator.h"
+
+#include <gtest/gtest.h>
+#include <functional>
+#include <map>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+#ifdef STORE_USE_ETCD
+#include <unistd.h>
+#include "etcd_helper.h"
+#include "ha/kv/etcd_ha_kv_backend.h"
+#endif
+
+namespace mooncake::test {
+namespace {
+class FakeBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        ++delete_count;
+        EXPECT_TRUE(values.contains(
+            ha::BuildBatchOpLogSnapshotCompactionFloorKey("cluster")));
+        if (before_delete) before_delete();
+        return delete_error;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        auto it = values.find(std::string(key));
+        if (it == values.end()) return ErrorCode::ETCD_KEY_NOT_EXIST;
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        const std::string owned_key(key);
+        values[owned_key] = std::string(value);
+        if (!create_revisions.contains(owned_key)) {
+            create_revisions[owned_key] = next_create_revision++;
+        }
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view, std::string_view, size_t,
+                    std::vector<KvPair>&) override {
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        ++txn_count;
+        if (!mutate_key.empty()) {
+            values[mutate_key] = mutate_value;
+            mutate_key.clear();
+        }
+        if (next_txn_error != ErrorCode::OK) {
+            const auto error = next_txn_error;
+            next_txn_error = ErrorCode::OK;
+            return error;
+        }
+        for (const auto& compare : txn.compares) {
+            const auto it = values.find(compare.key);
+            if (compare.kind == KvCompareKind::kKeyNotExists) {
+                if (it != values.end()) return ErrorCode::ETCD_TRANSACTION_FAIL;
+            } else if (compare.kind == KvCompareKind::kCreateRevisionEquals) {
+                auto revision = create_revisions.find(compare.key);
+                if (revision == create_revisions.end() ||
+                    revision->second != compare.expected_revision) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (it == values.end() ||
+                       it->second != compare.expected_value) {
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+        }
+        for (const auto& put : txn.puts) {
+            values[put.key] = put.value;
+            if (!create_revisions.contains(put.key)) {
+                create_revisions[put.key] = next_create_revision++;
+            }
+        }
+        if (after_txn) after_txn();
+        return ErrorCode::OK;
+    }
+
+    size_t delete_count{0};
+    ErrorCode delete_error{ErrorCode::OK};
+    std::function<void()> before_delete;
+    std::function<void()> after_txn;
+    std::map<std::string, std::string> values;
+    std::map<std::string, EtcdRevisionId> create_revisions;
+    ErrorCode next_txn_error{ErrorCode::OK};
+    std::string mutate_key;
+    std::string mutate_value;
+    size_t txn_count{0};
+    EtcdRevisionId next_create_revision{1};
+};
+
+class RecordingObjectStore final : public SnapshotObjectStore {
+   public:
+    tl::expected<void, std::string> UploadBuffer(
+        const std::string&, const std::vector<uint8_t>&) override {
+        return {};
+    }
+
+    tl::expected<void, std::string> DownloadBuffer(
+        const std::string& key, std::vector<uint8_t>& bytes) override {
+        ++buffer_downloads;
+        auto it = objects.find(key);
+        if (it == objects.end()) return tl::make_unexpected("missing");
+        bytes = it->second;
+        return {};
+    }
+
+    tl::expected<void, std::string> UploadString(const std::string&,
+                                                 const std::string&) override {
+        return {};
+    }
+
+    tl::expected<void, std::string> DownloadString(
+        const std::string& key, std::string& value) override {
+        auto it = objects.find(key);
+        if (it == objects.end()) return tl::make_unexpected("missing");
+        value.assign(it->second.begin(), it->second.end());
+        return {};
+    }
+
+    tl::expected<void, std::string> DeleteObjectsWithPrefix(
+        const std::string& prefix) override {
+        deleted.push_back(prefix);
+        return {};
+    }
+
+    tl::expected<void, std::string> ListObjectsWithPrefix(
+        const std::string& prefix, std::vector<std::string>& keys) override {
+        for (const auto& [key, _] : objects)
+            if (key.starts_with(prefix)) keys.push_back(key);
+        return {};
+    }
+
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override {
+        auto it = objects.find(key);
+        if (it == objects.end()) return tl::make_unexpected("missing");
+        if (inspection_error) return tl::make_unexpected("unknown metadata");
+        return SnapshotObjectInspection{
+            .stored_size = it->second.size(),
+            .crc32c = checksums ? std::optional<uint32_t>(
+                                      Crc32cValue(it->second.data(),
+                                                  it->second.size()) ^
+                                      (bad_checksum ? 1 : 0))
+                                : std::nullopt};
+    }
+
+    std::string GetConnectionInfo() const override { return "test"; }
+
+    bool checksums{true}, bad_checksum{false}, inspection_error{false};
+    size_t buffer_downloads{0};
+    std::vector<std::string> deleted;
+    std::map<std::string, std::vector<uint8_t>> objects;
+};
+
+std::string AddSnapshot(RecordingObjectStore& store, uint64_t batch,
+                        int64_t lease_id = 101) {
+    ha::BatchOpLogSnapshotManifest manifest;
+    manifest.snapshot_id = ha::BuildBatchOpLogSnapshotId(batch, lease_id);
+    manifest.last_included_batch_id = batch;
+    manifest.last_included_seq = batch * 10;
+    manifest.producer_view_version = 7;
+    const std::string root = "snapshots";
+    manifest.segments = {
+        ha::BuildBatchOpLogSnapshotSegmentsKey(root, manifest.snapshot_id), 1,
+        Crc32cValue("s", 1)};
+    manifest.object_chunks.push_back({0,
+                                      ha::BuildBatchOpLogSnapshotObjectChunkKey(
+                                          root, manifest.snapshot_id, 0),
+                                      1, 1, Crc32cValue("o", 1)});
+    store.objects[manifest.segments.key] = {'s'};
+    store.objects[manifest.object_chunks[0].key] = {'o'};
+    const auto bytes = ha::EncodeBatchOpLogSnapshotManifest(manifest);
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = manifest.snapshot_id;
+    descriptor.last_included_batch_id = batch;
+    descriptor.last_included_seq = manifest.last_included_seq;
+    descriptor.producer_view_version = manifest.producer_view_version;
+    descriptor.manifest_key =
+        ha::BuildBatchOpLogSnapshotManifestKey(root, manifest.snapshot_id);
+    descriptor.manifest_size = bytes.size();
+    descriptor.manifest_crc32c = Crc32cValue(bytes.data(), bytes.size());
+    descriptor.created_at_ms = 1;
+    store.objects[descriptor.manifest_key] = {bytes.begin(), bytes.end()};
+    const auto json = ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+    store.objects[ha::BuildBatchOpLogSnapshotDescriptorKey(
+        root, manifest.snapshot_id)] = {json.begin(), json.end()};
+    return json;
+}
+
+class PruningTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        HAMetricManager::instance().reset_snapshot_runtime(true);
+        ASSERT_EQ(ErrorCode::OK, backend.Put(lock_key, "101"));
+        latest = AddSnapshot(store, 20);
+        fallback = AddSnapshot(store, 10);
+        backend.Put(latest_key, latest);
+        backend.Put(fallback_key, fallback);
+    }
+    ErrorCode Run() { return pruning.Run(*lease); }
+    const std::string latest_key =
+        ha::BuildBatchOpLogSnapshotLatestKey("cluster");
+    const std::string fallback_key =
+        ha::BuildBatchOpLogSnapshotFallbackKey("cluster");
+    const std::string lock_key =
+        ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster");
+    const std::string floor_key =
+        ha::BuildBatchOpLogSnapshotCompactionFloorKey("cluster");
+    FakeBackend backend;
+    RecordingObjectStore store;
+    std::unique_ptr<SnapshotMaintenanceLease> lease =
+        SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    BatchOpLogPruningCoordinator pruning{backend, store, "cluster",
+                                         "snapshots"};
+    std::string latest, fallback;
+};
+
+TEST_F(PruningTest, FirstSnapshotDoesNotPublishFloor) {
+    backend.values.erase(fallback_key);
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_FALSE(backend.values.contains(floor_key));
+    EXPECT_EQ(0u, backend.txn_count);
+    EXPECT_EQ(HAMetricManager::SnapshotSkipReason::NoFallback,
+              HAMetricManager::instance().get_snapshot_runtime().skip_reason);
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, PublishesFloorBeforeDeletionAndRotates) {
+    backend.before_delete = [&] { EXPECT_EQ("10", backend.values[floor_key]); };
+    ASSERT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ(1u, backend.delete_count);
+    backend.before_delete = [&] { EXPECT_EQ("20", backend.values[floor_key]); };
+    ASSERT_EQ(ErrorCode::OK, BatchOpLogSnapshotPublisher(backend, "cluster")
+                                 .Publish(*lease, AddSnapshot(store, 30)));
+    ASSERT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ(2u, backend.delete_count);
+}
+
+TEST_F(PruningTest, RequiresIndependentOrderedSnapshots) {
+    for (const auto& value :
+         {latest, AddSnapshot(store, 20, 102), AddSnapshot(store, 30)}) {
+        backend.values[fallback_key] = value;
+        EXPECT_EQ(ErrorCode::OK, Run());
+        EXPECT_FALSE(backend.values.contains(floor_key));
+    }
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, RejectsCorruptPointersAndArtifacts) {
+    const auto original_objects = store.objects;
+    for (const auto& pointer_key : {latest_key, fallback_key}) {
+        const auto pointer = backend.values[pointer_key];
+        backend.values[pointer_key] = "invalid";
+        EXPECT_NE(ErrorCode::OK, Run());
+        backend.values[pointer_key] = pointer;
+    }
+    // Exercise every artifact of both snapshots, including descriptor raw
+    // bytes, manifest CRC, segments and chunks.
+    for (const auto& [key, bytes] : original_objects) {
+        SCOPED_TRACE(key);
+        store.objects.erase(key);
+        EXPECT_NE(ErrorCode::OK, Run());
+        store.objects = original_objects;
+        store.objects[key].push_back('x');
+        EXPECT_NE(ErrorCode::OK, Run());
+        store.objects = original_objects;
+        store.objects[key][0] ^= 1;
+        EXPECT_NE(ErrorCode::OK, Run());
+        store.objects = original_objects;
+    }
+    EXPECT_FALSE(backend.values.contains(floor_key));
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, RejectsManifestIdentityDespiteValidCrc) {
+    const auto original_objects = store.objects;
+    for (const auto& key : {latest_key, fallback_key}) {
+        store.objects = original_objects;
+        const auto original = backend.values[key];
+        auto descriptor = *ha::DecodeBatchOpLogSnapshotDescriptor(original);
+        const auto manifest_bytes = store.objects[descriptor.manifest_key];
+        auto manifest = *ha::DecodeBatchOpLogSnapshotManifest(
+            std::string(manifest_bytes.begin(), manifest_bytes.end()));
+        ++manifest.last_included_seq;
+        const auto bytes = ha::EncodeBatchOpLogSnapshotManifest(manifest);
+        store.objects[descriptor.manifest_key] = {bytes.begin(), bytes.end()};
+        descriptor.manifest_size = bytes.size();
+        descriptor.manifest_crc32c = Crc32cValue(bytes.data(), bytes.size());
+        const auto json = ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+        backend.values[key] = json;
+        store.objects[ha::BuildBatchOpLogSnapshotDescriptorKey(
+            "snapshots", descriptor.snapshot_id)] = {json.begin(), json.end()};
+        EXPECT_NE(ErrorCode::OK, Run());
+        backend.values[key] = original;
+    }
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, InspectionUnknownOrChecksumMismatchFailsClosed) {
+    store.bad_checksum = true;
+    EXPECT_NE(ErrorCode::OK, Run());
+    store.bad_checksum = false;
+    store.inspection_error = true;
+    EXPECT_NE(ErrorCode::OK, Run());
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, UnsupportedChecksumNeverDownloadsChunkBodies) {
+    store.checksums = false;
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ(0u, store.buffer_downloads);
+    EXPECT_EQ(1u, backend.delete_count);
+}
+
+TEST_F(PruningTest, CasFencesPointersLeaseAndRawFloor) {
+    for (const auto& key : {latest_key, fallback_key, lock_key, floor_key}) {
+        SCOPED_TRACE(key);
+        const auto values = backend.values;
+        backend.mutate_key = key;
+        backend.mutate_value = "changed";
+        EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, Run());
+        EXPECT_EQ(0u, backend.delete_count);
+        backend.values = values;
+    }
+    backend.values[floor_key] = "0009";
+    backend.mutate_key = floor_key;
+    backend.mutate_value = "9";
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, Run());
+    backend.create_revisions[lock_key] = 99;
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, Run());
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+TEST_F(PruningTest, FailedOrUnknownTxnDoesNotDelete) {
+    for (auto error :
+         {ErrorCode::ETCD_OPERATION_ERROR, ErrorCode::ETCD_TRANSACTION_FAIL}) {
+        backend.next_txn_error = error;
+        EXPECT_EQ(error, Run());
+        EXPECT_EQ(0u, backend.delete_count);
+    }
+}
+
+TEST_F(PruningTest, DeleteFailureKeepsFloorAndRetries) {
+    auto& metrics = HAMetricManager::instance();
+    const auto before = metrics.get_snapshot_runtime().floor_advances_total;
+    const auto errors =
+        metrics
+            .get_snapshot_operation(HAMetricManager::SnapshotOperation::Prune)
+            .errors;
+    backend.delete_error = ErrorCode::ETCD_OPERATION_ERROR;
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR, Run());
+    EXPECT_EQ("10", backend.values[floor_key]);
+    EXPECT_EQ(10u, metrics.get_snapshot_runtime().compaction_floor);
+    EXPECT_EQ(before + 1, metrics.get_snapshot_runtime().floor_advances_total);
+    EXPECT_EQ(errors + 1, metrics
+                              .get_snapshot_operation(
+                                  HAMetricManager::SnapshotOperation::Prune)
+                              .errors);
+    backend.delete_error = ErrorCode::OK;
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ(before + 1, metrics.get_snapshot_runtime().floor_advances_total);
+    EXPECT_EQ(errors + 1, metrics
+                              .get_snapshot_operation(
+                                  HAMetricManager::SnapshotOperation::Prune)
+                              .errors);
+    EXPECT_EQ(2u, backend.delete_count);
+    EXPECT_EQ("10", backend.values[floor_key]);
+}
+
+TEST_F(PruningTest, CrashAfterCasLeavesReaderVisibleFloorForRetry) {
+    bool stopped = false;
+    backend.after_txn = [&] { stopped = true; };
+    EXPECT_EQ(ErrorCode::OK, pruning.Run(*lease, [&] { return stopped; }));
+    EXPECT_EQ("10", backend.values[floor_key]);
+    EXPECT_EQ(0u, backend.delete_count);
+    backend.after_txn = {};
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ(1u, backend.delete_count);
+}
+
+TEST_F(PruningTest, FloorNeverRegressesAndParsingIsStrict) {
+    backend.values[floor_key] = "11";
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ("11", backend.values[floor_key]);
+    EXPECT_EQ(0u, backend.delete_count);
+    for (const auto& value :
+         {"", "-1", "+1", " 1", "1x", "18446744073709551616"}) {
+        backend.values[floor_key] = value;
+        EXPECT_NE(ErrorCode::OK, Run());
+    }
+    EXPECT_EQ(0u, backend.txn_count);
+    backend.values[floor_key] = "0009";
+    EXPECT_EQ(ErrorCode::OK, Run());
+    EXPECT_EQ("10", backend.values[floor_key]);
+}
+
+TEST_F(PruningTest, CancelledOrReleasedLeaseDoesNotDelete) {
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              pruning.Run(*lease, [] { return true; }));
+    ASSERT_EQ(ErrorCode::OK, lease->Release());
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, Run());
+    EXPECT_EQ(0u, backend.delete_count);
+}
+
+#ifdef STORE_USE_ETCD
+TEST(PruningRealEtcdTest, FloorPrecedesInclusiveDeleteAndProtectsControlKeys) {
+    constexpr char endpoints[] = "127.0.0.1:2379";
+    ASSERT_EQ(ErrorCode::OK, EtcdHelper::ConnectToEtcdStoreClient(endpoints));
+    const std::string cluster = "n12-test-" + std::to_string(getpid());
+    EtcdHaKvBackend backend;
+    const std::string root = "/oplog/" + cluster + "/";
+    std::string ignored;
+    const auto probe = backend.Get(root + "probe", ignored);
+    if (probe != ErrorCode::OK && probe != ErrorCode::ETCD_KEY_NOT_EXIST)
+        GTEST_SKIP() << "etcd is not reachable at " << endpoints;
+    ASSERT_EQ(ErrorCode::OK, backend.DeleteRange(root, root + "\xff"));
+    SnapshotMaintenanceLease lease(cluster);
+    ASSERT_EQ(ErrorCode::OK, lease.Acquire());
+    RecordingObjectStore store;
+    BatchOpLogSnapshotPublisher publisher(backend, cluster);
+    ASSERT_EQ(
+        ErrorCode::OK,
+        publisher.Publish(lease, AddSnapshot(store, 10, lease.lease_id())));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        publisher.Publish(lease, AddSnapshot(store, 20, lease.lease_id())));
+    for (uint64_t id : {0, 1, 10, 11, 20, 21})
+        ASSERT_EQ(ErrorCode::OK,
+                  backend.Put(BuildBatchRecordKey(cluster, id), "batch"));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(BuildDurablePrefixKey(cluster), "durable"));
+    ASSERT_EQ(ErrorCode::OK, backend.Put(BuildProducerViewKey(cluster), "7"));
+    BatchOpLogPruningCoordinator pruning(backend, store, cluster, "snapshots");
+    ASSERT_EQ(ErrorCode::OK, pruning.Run(lease));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend.Get(ha::BuildBatchOpLogSnapshotCompactionFloorKey(cluster),
+                    ignored));
+    EXPECT_EQ("10", ignored);
+    for (uint64_t id : {0, 1, 10})
+        EXPECT_EQ(ErrorCode::ETCD_KEY_NOT_EXIST,
+                  backend.Get(BuildBatchRecordKey(cluster, id), ignored));
+    for (const auto& key :
+         {BuildBatchRecordKey(cluster, 11), BuildBatchRecordKey(cluster, 20),
+          BuildBatchRecordKey(cluster, 21), BuildDurablePrefixKey(cluster),
+          BuildProducerViewKey(cluster),
+          ha::BuildBatchOpLogSnapshotLatestKey(cluster),
+          ha::BuildBatchOpLogSnapshotFallbackKey(cluster), lease.lock_key()})
+        EXPECT_EQ(ErrorCode::OK, backend.Get(key, ignored));
+    EXPECT_EQ(ErrorCode::OK, pruning.Run(lease));
+    ASSERT_EQ(ErrorCode::OK, lease.Release());
+    ASSERT_EQ(ErrorCode::OK, backend.DeleteRange(root, root + "\xff"));
+}
+#endif
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/publisher_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/publisher_test.cpp
new file mode 100644
index 0000000000..25bdb593e8
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/publisher_test.cpp
@@ -0,0 +1,391 @@
+#include "ha/snapshot/batch_oplog/batch_oplog_snapshot_publisher.h"
+
+#include <gtest/gtest.h>
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/snapshot_maintenance_lease.h"
+#ifdef STORE_USE_ETCD
+#include <unistd.h>
+
+#include "etcd_helper.h"
+#include "ha/kv/etcd_ha_kv_backend.h"
+#endif
+
+namespace mooncake::test {
+namespace {
+
+class FakeBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        auto it = values.find(std::string(key));
+        if (it == values.end()) return ErrorCode::ETCD_KEY_NOT_EXIST;
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        const std::string owned_key(key);
+        values[owned_key] = std::string(value);
+        if (!create_revisions.contains(owned_key)) {
+            create_revisions[owned_key] = next_create_revision++;
+        }
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view, std::string_view, size_t,
+                    std::vector<KvPair>&) override {
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        ++txn_count;
+        if (!mutate_key.empty()) {
+            values[mutate_key] = mutate_value;
+            mutate_key.clear();
+        }
+        if (next_txn_error != ErrorCode::OK) {
+            const auto error = next_txn_error;
+            next_txn_error = ErrorCode::OK;
+            return error;
+        }
+        for (const auto& compare : txn.compares) {
+            const auto it = values.find(compare.key);
+            if (compare.kind == KvCompareKind::kKeyNotExists) {
+                if (it != values.end()) return ErrorCode::ETCD_TRANSACTION_FAIL;
+            } else if (compare.kind == KvCompareKind::kCreateRevisionEquals) {
+                auto revision = create_revisions.find(compare.key);
+                if (revision == create_revisions.end() ||
+                    revision->second != compare.expected_revision) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (it == values.end() ||
+                       it->second != compare.expected_value) {
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+        }
+        for (const auto& put : txn.puts) {
+            values[put.key] = put.value;
+            if (!create_revisions.contains(put.key)) {
+                create_revisions[put.key] = next_create_revision++;
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    std::map<std::string, std::string> values;
+    std::map<std::string, EtcdRevisionId> create_revisions;
+    ErrorCode next_txn_error{ErrorCode::OK};
+    std::string mutate_key;
+    std::string mutate_value;
+    size_t txn_count{0};
+    EtcdRevisionId next_create_revision{1};
+};
+
+std::string MakeDescriptor(uint64_t batch_id, int64_t lease_id = 101,
+                           ViewVersionId producer_view = 7) {
+    ha::BatchOpLogSnapshotDescriptor descriptor;
+    descriptor.snapshot_id = ha::BuildBatchOpLogSnapshotId(batch_id, lease_id);
+    descriptor.last_included_seq = batch_id * 10;
+    descriptor.last_included_batch_id = batch_id;
+    descriptor.producer_view_version = producer_view;
+    descriptor.manifest_key =
+        "snapshots/batch-oplog/" + descriptor.snapshot_id + "/manifest.json";
+    descriptor.manifest_size = 1;
+    descriptor.created_at_ms = 1234;
+    return ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+}
+
+}  // namespace
+
+TEST(BatchOpLogSnapshotPublisherTest, PublishesAndRotatesPointersAtomically) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+
+    const auto first = MakeDescriptor(1);
+    EXPECT_EQ(ErrorCode::OK, publisher.Publish(*lease, first));
+    EXPECT_EQ(first,
+              backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")]);
+    EXPECT_FALSE(backend.values.contains(
+        ha::BuildBatchOpLogSnapshotFallbackKey("cluster")));
+
+    const auto second = MakeDescriptor(2);
+    EXPECT_EQ(ErrorCode::OK, publisher.Publish(*lease, second));
+    EXPECT_EQ(second,
+              backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")]);
+    EXPECT_EQ(
+        first,
+        backend.values[ha::BuildBatchOpLogSnapshotFallbackKey("cluster")]);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, CapturesPublishedFallbackState) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    std::optional<std::string> fallback;
+    const auto first = MakeDescriptor(1);
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(*lease, first, &fallback));
+    EXPECT_FALSE(fallback.has_value());
+    const auto second = MakeDescriptor(2);
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(*lease, second, &fallback));
+    EXPECT_EQ(first, fallback.value());
+}
+
+TEST(BatchOpLogSnapshotPublisherTest,
+     RepairsMissingLatestAndPreservesFallback) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    const auto fallback = MakeDescriptor(5);
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("cluster"),
+                          fallback));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+
+    const auto candidate = MakeDescriptor(6);
+    EXPECT_EQ(ErrorCode::OK, publisher.Publish(*lease, candidate));
+    EXPECT_EQ(candidate,
+              backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")]);
+    EXPECT_EQ(
+        fallback,
+        backend.values[ha::BuildBatchOpLogSnapshotFallbackKey("cluster")]);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest,
+     RepairsCorruptLatestAndPreservesFallback) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    const auto fallback = MakeDescriptor(5);
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("cluster"),
+                          fallback));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotLatestKey("cluster"),
+                          "not-json"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+
+    const auto candidate = MakeDescriptor(6);
+    EXPECT_EQ(ErrorCode::OK, publisher.Publish(*lease, candidate));
+    EXPECT_EQ(candidate,
+              backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")]);
+    EXPECT_EQ(
+        fallback,
+        backend.values[ha::BuildBatchOpLogSnapshotFallbackKey("cluster")]);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest,
+     RejectsRepairCandidateNotNewerThanFallback) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    const auto fallback = MakeDescriptor(5);
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("cluster"),
+                          fallback));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, MakeDescriptor(5)));
+    EXPECT_FALSE(backend.values.contains(
+        ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+    EXPECT_EQ(0u, backend.txn_count);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, RejectsStaleAndLostLeaseWithoutTxn) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    const auto lock_key = ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster");
+    ASSERT_EQ(ErrorCode::OK, backend.Put(lock_key, "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    const auto first = MakeDescriptor(4);
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(*lease, first));
+    const auto txn_count = backend.txn_count;
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, first));
+    EXPECT_EQ(txn_count, backend.txn_count);
+
+    lease->Release();
+    const auto next = MakeDescriptor(5);
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, next));
+    EXPECT_EQ(txn_count, backend.txn_count);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, LeavesPointersUnchangedOnCasFailure) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    const auto first = MakeDescriptor(1);
+    backend.next_txn_error = ErrorCode::ETCD_TRANSACTION_FAIL;
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, first));
+    EXPECT_FALSE(backend.values.contains(
+        ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, FencesLatestAndFallbackRaces) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    const auto first = MakeDescriptor(1);
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(*lease, first));
+
+    const auto latest_racer = MakeDescriptor(4);
+    backend.mutate_key = ha::BuildBatchOpLogSnapshotLatestKey("cluster");
+    backend.mutate_value = latest_racer;
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, MakeDescriptor(2)));
+    EXPECT_EQ(latest_racer,
+              backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")]);
+
+    backend.values.erase(ha::BuildBatchOpLogSnapshotFallbackKey("cluster"));
+    backend.values[ha::BuildBatchOpLogSnapshotLatestKey("cluster")] = first;
+    backend.mutate_key = ha::BuildBatchOpLogSnapshotFallbackKey("cluster");
+    backend.mutate_value = first;
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, MakeDescriptor(2)));
+    EXPECT_EQ(
+        first,
+        backend.values[ha::BuildBatchOpLogSnapshotFallbackKey("cluster")]);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, RejectsCandidateFromAnotherLease) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "102");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "102"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS,
+              publisher.Publish(*lease, MakeDescriptor(1)));
+    EXPECT_EQ(0u, backend.txn_count);
+}
+
+TEST(BatchOpLogSnapshotPublisherTest,
+     AllowsOlderProducerViewWhenCursorAdvances) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    ASSERT_EQ(ErrorCode::OK,
+              publisher.Publish(*lease, MakeDescriptor(1, 101, 9)));
+    EXPECT_EQ(ErrorCode::OK,
+              publisher.Publish(*lease, MakeDescriptor(2, 101, 3)));
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, LockOwnerRaceCannotPublish) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    backend.mutate_key = ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster");
+    backend.mutate_value = "102";
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, MakeDescriptor(1)));
+    EXPECT_FALSE(backend.values.contains(
+        ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, FencesOldMaintenanceLockIncarnation) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101", 1);
+    const auto lock_key = ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster");
+    ASSERT_EQ(ErrorCode::OK, backend.Put(lock_key, "101"));
+    backend.create_revisions[lock_key] = 2;
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL,
+              publisher.Publish(*lease, MakeDescriptor(1)));
+    EXPECT_FALSE(backend.values.contains(
+        ha::BuildBatchOpLogSnapshotLatestKey("cluster")));
+}
+
+TEST(BatchOpLogSnapshotPublisherTest, RejectsCorruptFallback) {
+    FakeBackend backend;
+    auto lease = SnapshotMaintenanceLease::MakeForTesting("cluster", "101");
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotMaintenanceKey("cluster"),
+                          "101"));
+    ASSERT_EQ(ErrorCode::OK,
+              backend.Put(ha::BuildBatchOpLogSnapshotFallbackKey("cluster"),
+                          "not-json"));
+    BatchOpLogSnapshotPublisher publisher(backend, "cluster");
+    EXPECT_EQ(ErrorCode::INTERNAL_ERROR,
+              publisher.Publish(*lease, MakeDescriptor(1)));
+    EXPECT_EQ(0u, backend.txn_count);
+}
+
+#ifdef STORE_USE_ETCD
+TEST(BatchOpLogSnapshotPublisherTest, RealEtcdLeaseAndPublisherLifecycle) {
+    constexpr char kEndpoints[] = "127.0.0.1:2379";
+    if (EtcdHelper::ConnectToEtcdStoreClient(kEndpoints) != ErrorCode::OK) {
+        GTEST_SKIP() << "etcd is not available at " << kEndpoints;
+    }
+    const std::string probe_key =
+        "/oplog/n04-probe-" + std::to_string(static_cast<long long>(getpid()));
+    std::string probe_value;
+    EtcdRevisionId probe_revision = 0;
+    const auto probe = EtcdHelper::Get(probe_key.c_str(), probe_key.size(),
+                                       probe_value, probe_revision);
+    if (probe != ErrorCode::OK && probe != ErrorCode::ETCD_KEY_NOT_EXIST) {
+        GTEST_SKIP() << "etcd is not reachable at " << kEndpoints << ": "
+                     << static_cast<int>(probe);
+    }
+
+    const std::string cluster =
+        "n04-real-" + std::to_string(static_cast<long long>(getpid()));
+    SnapshotMaintenanceLease first(cluster);
+    ASSERT_EQ(ErrorCode::OK, first.Acquire());
+    SnapshotMaintenanceLease second(cluster);
+    EXPECT_EQ(ErrorCode::ETCD_TRANSACTION_FAIL, second.Acquire());
+
+    EtcdHaKvBackend backend;
+    BatchOpLogSnapshotPublisher publisher(backend, cluster);
+    const auto first_descriptor = MakeDescriptor(1, first.lease_id());
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(first, first_descriptor));
+    const auto second_descriptor = MakeDescriptor(2, first.lease_id());
+    ASSERT_EQ(ErrorCode::OK, publisher.Publish(first, second_descriptor));
+
+    ASSERT_EQ(ErrorCode::OK, first.Release());
+    ASSERT_EQ(ErrorCode::OK, second.Acquire());
+    EXPECT_EQ(ErrorCode::INVALID_PARAMS,
+              publisher.Publish(second, second_descriptor));
+    ASSERT_EQ(ErrorCode::OK, second.Release());
+}
+#endif
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/rebootstrap_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/rebootstrap_test.cpp
new file mode 100644
index 0000000000..afcaae0011
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/rebootstrap_test.cpp
@@ -0,0 +1,337 @@
+#include "ha_metric_manager.h"
+#include "hot_standby_service.h"
+
+#include <gtest/gtest.h>
+#include <unistd.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <future>
+#include <map>
+#include <mutex>
+#include <thread>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/snapshot/batch_oplog/codec.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/backends/local/local_file_snapshot_object_store.h"
+
+namespace mooncake::test {
+namespace {
+
+class MemoryBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) return ErrorCode::ETCD_KEY_NOT_EXIST;
+        value = it->second;
+        return ErrorCode::OK;
+    }
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+    ErrorCode Range(std::string_view begin, std::string_view end, size_t limit,
+                    std::vector<KvPair>& output) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        output.clear();
+        for (auto it = values_.lower_bound(std::string(begin));
+             it != values_.end() && it->first < end &&
+             (limit == 0 || output.size() < limit);
+             ++it) {
+            output.push_back({it->first, it->second});
+        }
+        return ErrorCode::OK;
+    }
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn& txn) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (const auto& put : txn.puts) values_[put.key] = put.value;
+        return ErrorCode::OK;
+    }
+
+   private:
+    std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+};
+
+template <typename Predicate>
+bool WaitUntil(Predicate predicate) {
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    while (!predicate()) {
+        if (std::chrono::steady_clock::now() >= deadline) return false;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return true;
+}
+
+class RebootstrapTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        char pattern[] = "/tmp/mooncake-n09-XXXXXX";
+        const auto* directory = mkdtemp(pattern);
+        ASSERT_NE(nullptr, directory);
+        root_ = directory;
+        objects_ = std::make_unique<LocalFileSnapshotObjectStore>(root_);
+        HotStandbyConfig config;
+        config.enable_snapshot_bootstrap = true;
+        config.enable_verification = false;
+        config.oplog_poll_interval_ms = 1;
+        service_ = std::make_unique<HotStandbyService>(config);
+        service_->SetCatchUpBatchKvBackendForTesting(backend_);
+        service_->SetBatchOpLogSnapshotProvider(
+            std::make_unique<BatchOpLogSnapshotProvider>(
+                "n09", *backend_, *objects_, "snapshots"));
+        Publish(1, "old", false);
+        OpLogEntry initial;
+        initial.sequence_id = 1;
+        initial.op_type = OpType::REMOVE;
+        initial.object_key = "absent";
+        OpLogBatchRecord batch;
+        batch.batch_id = batch.first_seq = batch.last_seq = 1;
+        batch.entries = {initial};
+        backend_->Put(BuildBatchRecordKey("n09", 1),
+                      EncodeOpLogBatchRecord(batch));
+        Prefix(1);
+        ASSERT_EQ(ErrorCode::OK, service_->Start("", "", "n09"));
+    }
+    void TearDown() override {
+        ReleaseSwap();
+        service_->Stop();
+        if (armed_) unsetenv("MOONCAKE_TEST_FAILPOINT_DIR");
+        std::filesystem::remove_all(root_);
+    }
+    void Prefix(uint64_t id) {
+        backend_->Put(BuildDurablePrefixKey("n09"),
+                      EncodeDurablePrefix({.batch_id = id, .last_seq = id}));
+    }
+    void Publish(uint64_t id, const std::string& key, bool fallback) {
+        const auto snapshot_id = std::to_string(id) + "-1";
+        const auto segments = EncodeBatchOpLogSnapshotSegments(
+            {{.segment_name = key,
+              .transport_endpoint = key + ":1234",
+              .file_path = ""}});
+        const auto segment_key =
+            ha::BuildBatchOpLogSnapshotSegmentsKey("snapshots", snapshot_id);
+        ASSERT_TRUE(objects_->UploadBuffer(segment_key, segments));
+        const auto chunk = EncodeBatchOpLogSnapshotObjectChunk(
+            0, {{.key = key, .metadata = {}},
+                {.key = "remove-me", .metadata = {}}});
+        const auto chunk_key = ha::BuildBatchOpLogSnapshotObjectChunkKey(
+            "snapshots", snapshot_id, 0);
+        ASSERT_TRUE(objects_->UploadBuffer(chunk_key, chunk));
+        ha::BatchOpLogSnapshotManifest manifest;
+        manifest.snapshot_id = snapshot_id;
+        manifest.last_included_batch_id = id;
+        manifest.last_included_seq = id;
+        manifest.segments = {
+            .key = segment_key,
+            .stored_size = segments.size(),
+            .crc32c = Crc32cValue(segments.data(), segments.size())};
+        manifest.object_chunks = {
+            {.chunk_index = 0,
+             .key = chunk_key,
+             .object_count = 2,
+             .stored_size = chunk.size(),
+             .crc32c = Crc32cValue(chunk.data(), chunk.size())}};
+        const auto bytes = ha::EncodeBatchOpLogSnapshotManifest(manifest);
+        ha::BatchOpLogSnapshotDescriptor descriptor;
+        descriptor.snapshot_id = snapshot_id;
+        descriptor.last_included_batch_id = id;
+        descriptor.last_included_seq = id;
+        descriptor.manifest_key =
+            ha::BuildBatchOpLogSnapshotManifestKey("snapshots", snapshot_id);
+        descriptor.manifest_size = bytes.size();
+        descriptor.manifest_crc32c = Crc32cValue(bytes.data(), bytes.size());
+        ASSERT_TRUE(objects_->UploadString(descriptor.manifest_key, bytes));
+        const auto encoded = ha::EncodeBatchOpLogSnapshotDescriptor(descriptor);
+        ASSERT_TRUE(objects_->UploadString(
+            ha::BuildBatchOpLogSnapshotDescriptorKey("snapshots", snapshot_id),
+            encoded));
+        backend_->Put(fallback ? ha::BuildBatchOpLogSnapshotFallbackKey("n09")
+                               : ha::BuildBatchOpLogSnapshotLatestKey("n09"),
+                      encoded);
+    }
+    void Compact() {
+        // Freeze at a complete batch so the reader observes one new history.
+        auto capture = service_->BeginBatchOpLogSnapshotCapture();
+        ASSERT_TRUE(capture);
+        OpLogEntry entry;
+        entry.sequence_id = 4;
+        entry.op_type = OpType::REMOVE;
+        entry.tenant_id = "default";
+        entry.object_key = "remove-me";
+        OpLogBatchRecord batch;
+        batch.batch_id = batch.first_seq = batch.last_seq = 4;
+        batch.entries = {entry};
+        backend_->Put(BuildBatchRecordKey("n09", 4),
+                      EncodeOpLogBatchRecord(batch));
+        Prefix(4);
+        backend_->Put(ha::BuildBatchOpLogSnapshotCompactionFloorKey("n09"),
+                      "3");
+        service_->EndBatchOpLogSnapshotCapture(*capture);
+    }
+    void ExpectOldState() {
+        StandbySnapshot snapshot;
+        ASSERT_TRUE(service_->ExportStandbySnapshot(snapshot));
+        EXPECT_EQ(1u, snapshot.oplog_sequence_id);
+        ASSERT_EQ(2u, snapshot.objects.size());
+        ASSERT_EQ(1u, snapshot.segments.size());
+        EXPECT_EQ("old", snapshot.segments[0].segment_name);
+        EXPECT_FALSE(service_->IsReadyForPromotion());
+        EXPECT_FALSE(service_->BeginBatchOpLogSnapshotCapture());
+        EXPECT_EQ(ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS,
+                  service_->Promote());
+    }
+    void ExpectRecovered() {
+        ASSERT_TRUE(WaitUntil([&] {
+            return service_->GetLatestAppliedSequenceId() == 4 &&
+                   !service_->GetSyncStatus().is_recovering;
+        }));
+        EXPECT_TRUE(service_->IsReadyForPromotion());
+        auto handoff = service_->PromoteAndDetachBatchOpLogStore();
+        ASSERT_TRUE(handoff);
+        EXPECT_EQ(4u, handoff->applied_cursor.batch_id);
+        EXPECT_EQ(4u, handoff->applied_cursor.last_seq);
+        EXPECT_EQ(1u, handoff->metadata_store->GetKeyCount());
+        EXPECT_TRUE(handoff->metadata_store->Exists("new"));
+        ASSERT_EQ(1u, handoff->segments.size());
+        EXPECT_EQ("new", handoff->segments[0].segment_name);
+    }
+    void ArmSwap() {
+        setenv("MOONCAKE_TEST_FAILPOINT_DIR", root_.c_str(), 1);
+        armed_ = true;
+        std::ofstream(root_ + "/standby_rebootstrap_before_swap.arm");
+    }
+    void ReleaseSwap() {
+        if (armed_)
+            std::ofstream(root_ + "/standby_rebootstrap_before_swap.release");
+    }
+    std::string root_;
+    bool armed_{false};
+    std::shared_ptr<MemoryBackend> backend_{std::make_shared<MemoryBackend>()};
+    std::unique_ptr<LocalFileSnapshotObjectStore> objects_;
+    std::unique_ptr<HotStandbyService> service_;
+};
+
+TEST_F(RebootstrapTest, CorruptLatestUsesFallbackAndReplaysSuffix) {
+    auto& metrics = HAMetricManager::instance();
+    const auto before = metrics.get_snapshot_operation(
+        HAMetricManager::SnapshotOperation::Rebootstrap);
+    Publish(3, "new", true);
+    backend_->Put(ha::BuildBatchOpLogSnapshotLatestKey("n09"), "{}");
+    Compact();
+    ExpectRecovered();
+    ASSERT_TRUE(WaitUntil([&] {
+        return metrics
+                   .get_snapshot_operation(
+                       HAMetricManager::SnapshotOperation::Rebootstrap)
+                   .total > before.total;
+    }));
+    EXPECT_EQ(before.errors,
+              metrics
+                  .get_snapshot_operation(
+                      HAMetricManager::SnapshotOperation::Rebootstrap)
+                  .errors);
+    EXPECT_EQ(1u, metrics.get_snapshot_runtime().suffix_batches);
+    EXPECT_EQ(3u, metrics.get_snapshot_runtime().compaction_floor);
+}
+
+TEST_F(RebootstrapTest, NoEligibleSnapshotPreservesStateAndRetriesOnline) {
+    Compact();
+    ASSERT_TRUE(
+        WaitUntil([&] { return service_->GetSyncStatus().is_recovering; }));
+    ExpectOldState();
+    Publish(3, "new", false);
+    ExpectRecovered();
+}
+
+TEST_F(RebootstrapTest, CorruptCandidatePreservesOldStateUntilRepaired) {
+    Publish(3, "new", false);
+    ASSERT_TRUE(objects_->UploadString(
+        ha::BuildBatchOpLogSnapshotObjectChunkKey("snapshots", "3-1", 0),
+        "corrupt"));
+    Compact();
+    ASSERT_TRUE(
+        WaitUntil([&] { return service_->GetSyncStatus().is_recovering; }));
+    ExpectOldState();
+    Publish(3, "new", false);
+    ExpectRecovered();
+}
+
+#ifdef MOONCAKE_ENABLE_TEST_FAILPOINTS
+TEST_F(RebootstrapTest, PromotionDuringSwapFailsClosedThenSucceeds) {
+    ArmSwap();
+    Publish(3, "new", false);
+    Compact();
+    ASSERT_TRUE(WaitUntil([&] {
+        return std::filesystem::exists(root_ +
+                                       "/standby_rebootstrap_before_swap.hit");
+    }));
+    ExpectOldState();
+    EXPECT_EQ(1u,
+              HAMetricManager::instance().get_snapshot_runtime().applied_batch);
+    EXPECT_EQ(
+        3u,
+        HAMetricManager::instance().get_snapshot_runtime().compaction_floor);
+    ReleaseSwap();
+    ExpectRecovered();
+}
+
+TEST_F(RebootstrapTest, StopDuringSwapDoesNotDeadlockOrInstallCandidate) {
+    ArmSwap();
+    Publish(3, "new", false);
+    Compact();
+    ASSERT_TRUE(WaitUntil([&] {
+        return std::filesystem::exists(root_ +
+                                       "/standby_rebootstrap_before_swap.hit");
+    }));
+    auto stopped = std::async(std::launch::async, [&] { service_->Stop(); });
+    EXPECT_TRUE(WaitUntil(
+        [&] { return service_->GetState() == StandbyState::STOPPED; }));
+    ReleaseSwap();
+    ASSERT_EQ(std::future_status::ready,
+              stopped.wait_for(std::chrono::seconds(5)));
+    EXPECT_EQ(1u, service_->GetLatestAppliedSequenceId());
+    EXPECT_EQ(2u, service_->GetMetadataCount());
+    EXPECT_EQ(1u,
+              HAMetricManager::instance().get_snapshot_runtime().applied_batch);
+}
+
+TEST_F(RebootstrapTest, FloorAdvancingBeforeSwapRejectsCandidate) {
+    ArmSwap();
+    Publish(3, "new", false);
+    Compact();
+    ASSERT_TRUE(WaitUntil([&] {
+        return std::filesystem::exists(root_ +
+                                       "/standby_rebootstrap_before_swap.hit");
+    }));
+    backend_->Put(ha::BuildBatchOpLogSnapshotCompactionFloorKey("n09"), "4");
+    ReleaseSwap();
+    ASSERT_TRUE(WaitUntil([&] {
+        return !std::filesystem::exists(root_ +
+                                        "/standby_rebootstrap_before_swap.hit");
+    }));
+    ExpectOldState();
+    Publish(4, "new", false);
+    ASSERT_TRUE(WaitUntil([&] {
+        return service_->GetLatestAppliedSequenceId() == 4 &&
+               !service_->GetSyncStatus().is_recovering;
+    }));
+    EXPECT_TRUE(service_->IsReadyForPromotion());
+}
+#endif
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/batch_oplog/writer_test.cpp b/mooncake-store/tests/ha/snapshot/batch_oplog/writer_test.cpp
new file mode 100644
index 0000000000..cd44be05f8
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/batch_oplog/writer_test.cpp
@@ -0,0 +1,397 @@
+#include "ha_metric_manager.h"
+#include "ha/snapshot/batch_oplog/writer.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include <ylt/struct_pack.hpp>
+
+#include "crc32c.h"
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_codec.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/snapshot/batch_oplog/codec.h"
+#include "ha/snapshot/batch_oplog/metadata.h"
+#include "ha/snapshot/object/snapshot_object_store.h"
+#include "hot_standby_service.h"
+
+namespace mooncake::test {
+
+namespace {
+
+class FakeHaKvBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin_key, std::string_view end_key,
+                    size_t limit, std::vector<KvPair>& kvs) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        kvs.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin_key && key < end_key) {
+                kvs.push_back({key, value});
+                if (limit != 0 && kvs.size() == limit) {
+                    break;
+                }
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
+
+   private:
+    std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+};
+
+class FakeObjectStore final : public SnapshotObjectStore {
+   public:
+    tl::expected<void, std::string> UploadBuffer(
+        const std::string& key, const std::vector<uint8_t>& buffer) override {
+        ++upload_attempts;
+        if (fail_upload_at && upload_attempts == *fail_upload_at) {
+            return tl::make_unexpected("injected upload failure");
+        }
+        objects_[key] = buffer;
+        return {};
+    }
+
+    tl::expected<void, std::string> DownloadBuffer(
+        const std::string& key, std::vector<uint8_t>& buffer) override {
+        ++download_attempts;
+        if (fail_download) {
+            return tl::make_unexpected("injected download failure");
+        }
+        auto it = objects_.find(key);
+        if (it == objects_.end()) {
+            return tl::make_unexpected("not found");
+        }
+        buffer = it->second;
+        return {};
+    }
+
+    tl::expected<void, std::string> UploadString(
+        const std::string& key, const std::string& data) override {
+        ++string_upload_attempts;
+        return UploadBuffer(key, {data.begin(), data.end()});
+    }
+
+    tl::expected<void, std::string> DownloadString(const std::string& key,
+                                                   std::string& data) override {
+        std::vector<uint8_t> buffer;
+        auto result = DownloadBuffer(key, buffer);
+        if (!result) {
+            return result;
+        }
+        data.assign(buffer.begin(), buffer.end());
+        return {};
+    }
+
+    tl::expected<void, std::string> DeleteObjectsWithPrefix(
+        const std::string& prefix) override {
+        ++cleanup_attempts;
+        for (auto it = objects_.begin(); it != objects_.end();) {
+            if (it->first.starts_with(prefix)) {
+                it = objects_.erase(it);
+            } else {
+                ++it;
+            }
+        }
+        return {};
+    }
+
+    tl::expected<void, std::string> ListObjectsWithPrefix(
+        const std::string& prefix,
+        std::vector<std::string>& object_keys) override {
+        object_keys.clear();
+        for (const auto& [key, value] : objects_) {
+            (void)value;
+            if (key.starts_with(prefix)) {
+                object_keys.push_back(key);
+            }
+        }
+        return {};
+    }
+
+    tl::expected<SnapshotObjectInspection, std::string> InspectObject(
+        const std::string& key) override {
+        auto it = objects_.find(key);
+        if (it == objects_.end()) {
+            return tl::make_unexpected("not found");
+        }
+        SnapshotObjectInspection inspection{.stored_size = it->second.size(),
+                                            .crc32c = std::nullopt};
+        if (provide_checksum) {
+            inspection.crc32c =
+                Crc32cValue(it->second.data(), it->second.size());
+            if (bad_checksum) {
+                *inspection.crc32c ^= 1;
+            }
+        }
+        return inspection;
+    }
+
+    std::string GetConnectionInfo() const override { return "fake"; }
+
+    void PutExisting(const std::string& key) { objects_[key] = {1}; }
+    bool Contains(const std::string& key) const {
+        return objects_.contains(key);
+    }
+    size_t size() const { return objects_.size(); }
+
+    bool provide_checksum{false};
+    bool bad_checksum{false};
+    bool fail_download{false};
+    std::optional<size_t> fail_upload_at;
+    size_t upload_attempts{0};
+    size_t download_attempts{0};
+    size_t cleanup_attempts{0};
+    size_t string_upload_attempts{0};
+
+   private:
+    std::map<std::string, std::vector<uint8_t>> objects_;
+};
+
+OpLogBatchRecord MakeObjectBatch(size_t object_count) {
+    OpLogBatchRecord batch;
+    batch.batch_id = 1;
+    batch.first_seq = 1;
+    batch.last_seq = object_count;
+    for (size_t i = 0; i < object_count; ++i) {
+        MetadataPayload metadata;
+        metadata.client_id = {0, i + 1};
+        metadata.size = 1024 + i;
+        if (i == 1) {
+            metadata.hard_pinned = true;
+        }
+        auto encoded = struct_pack::serialize(metadata);
+
+        OpLogEntry entry;
+        entry.sequence_id = i + 1;
+        entry.op_type = OpType::PUT_END;
+        entry.tenant_id = "tenant";
+        entry.object_key = "key-" + std::to_string(i);
+        entry.payload.assign(encoded.begin(), encoded.end());
+        entry.checksum = ComputeOpLogChecksum(entry.payload);
+        batch.entries.push_back(std::move(entry));
+    }
+    return batch;
+}
+
+}  // namespace
+
+class BatchOpLogSnapshotWriterTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging("BatchOpLogSnapshotWriterTest");
+        FLAGS_logtostderr = true;
+    }
+
+    void TearDown() override {
+        if (standby_) {
+            standby_->Stop();
+        }
+        google::ShutdownGoogleLogging();
+    }
+
+    std::optional<BatchOpLogSnapshotCapture> StartCapture(size_t object_count) {
+        backend_ = std::make_shared<FakeHaKvBackend>();
+        if (object_count != 0) {
+            EXPECT_EQ(ErrorCode::OK,
+                      backend_->Put(BuildBatchRecordKey(kClusterId, 1),
+                                    EncodeOpLogBatchRecord(
+                                        MakeObjectBatch(object_count))));
+        }
+        EXPECT_EQ(ErrorCode::OK,
+                  backend_->Put(BuildDurablePrefixKey(kClusterId),
+                                EncodeDurablePrefix(
+                                    {.batch_id = object_count == 0 ? 0u : 1u,
+                                     .last_seq = object_count})));
+        EXPECT_EQ(ErrorCode::OK,
+                  backend_->Put(BuildProducerViewKey(kClusterId), "7"));
+
+        HotStandbyConfig config;
+        config.enable_oplog_following = true;
+        config.enable_verification = false;
+        config.oplog_poll_interval_ms = 1;
+        standby_ = std::make_unique<HotStandbyService>(config);
+        standby_->SetCatchUpBatchKvBackendForTesting(backend_);
+        EXPECT_EQ(ErrorCode::OK, standby_->Start("", "", kClusterId));
+        HAMetricManager::instance().reset_snapshot_runtime(true);
+        return standby_->BeginBatchOpLogSnapshotCapture();
+    }
+
+    static constexpr char kClusterId[] = "n03-test";
+    std::shared_ptr<FakeHaKvBackend> backend_;
+    std::unique_ptr<HotStandbyService> standby_;
+};
+
+TEST_F(BatchOpLogSnapshotWriterTest, WritesAndVerifiesMultipleChunks) {
+    auto capture = StartCapture(3);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto descriptor_json =
+        writer.Write(*standby_, *capture, "snapshots", "1-42", 2, 1234);
+
+    ASSERT_TRUE(descriptor_json) << descriptor_json.error();
+    auto descriptor = ha::DecodeBatchOpLogSnapshotDescriptor(*descriptor_json);
+    ASSERT_TRUE(descriptor) << descriptor.error();
+    EXPECT_EQ("1-42", descriptor->snapshot_id);
+    EXPECT_EQ(3u, descriptor->last_included_seq);
+    EXPECT_EQ(1u, descriptor->last_included_batch_id);
+    EXPECT_EQ(7, descriptor->producer_view_version);
+    EXPECT_EQ(1234, descriptor->created_at_ms);
+
+    std::string manifest_json;
+    ASSERT_TRUE(
+        object_store.DownloadString(descriptor->manifest_key, manifest_json));
+    auto manifest = ha::DecodeBatchOpLogSnapshotManifest(manifest_json);
+    ASSERT_TRUE(manifest) << manifest.error();
+    ASSERT_EQ(2u, manifest->object_chunks.size());
+    EXPECT_EQ(2u, manifest->object_chunks[0].object_count);
+    EXPECT_EQ(1u, manifest->object_chunks[1].object_count);
+    for (const auto& chunk : manifest->object_chunks) {
+        std::vector<uint8_t> encoded_chunk;
+        ASSERT_TRUE(object_store.DownloadBuffer(chunk.key, encoded_chunk));
+        auto decoded_chunk = DecodeBatchOpLogSnapshotObjectChunk(
+            encoded_chunk, chunk.chunk_index, chunk.object_count);
+        ASSERT_TRUE(decoded_chunk) << decoded_chunk.error();
+        for (const auto& object : decoded_chunk->objects) {
+            EXPECT_EQ(object.key == "key-1",
+                      object.metadata.hard_pinned.value_or(false));
+        }
+    }
+    const auto metrics = HAMetricManager::instance().get_snapshot_runtime();
+    EXPECT_EQ(2u, metrics.chunk_count);
+    EXPECT_EQ(manifest->object_chunks[0].stored_size +
+                  manifest->object_chunks[1].stored_size,
+              metrics.chunk_bytes);
+    EXPECT_EQ(metrics.chunk_bytes + manifest->segments.stored_size +
+                  manifest_json.size() + descriptor_json->size(),
+              metrics.snapshot_bytes);
+    EXPECT_EQ(5u, object_store.size());
+    EXPECT_EQ(2u, object_store.string_upload_attempts);
+    EXPECT_GT(object_store.download_attempts, 0u);
+    standby_
+        ->Stop();  // Join the apply loop before inspecting its pause sample.
+    EXPECT_GT(
+        HAMetricManager::instance().get_snapshot_runtime().capture_pause_us,
+        0u);
+}
+
+TEST_F(BatchOpLogSnapshotWriterTest, WritesEmptyClusterWithoutObjectChunks) {
+    auto capture = StartCapture(0);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    object_store.provide_checksum = true;
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto descriptor_json =
+        writer.Write(*standby_, *capture, "snapshots", "0-42", 2, 1234);
+
+    ASSERT_TRUE(descriptor_json) << descriptor_json.error();
+    auto descriptor = ha::DecodeBatchOpLogSnapshotDescriptor(*descriptor_json);
+    ASSERT_TRUE(descriptor);
+    std::string manifest_json;
+    ASSERT_TRUE(
+        object_store.DownloadString(descriptor->manifest_key, manifest_json));
+    auto manifest = ha::DecodeBatchOpLogSnapshotManifest(manifest_json);
+    ASSERT_TRUE(manifest);
+    EXPECT_TRUE(manifest->object_chunks.empty());
+}
+
+TEST_F(BatchOpLogSnapshotWriterTest,
+       RejectsExistingCandidateWithoutDeletingIt) {
+    auto capture = StartCapture(1);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    const std::string existing_key =
+        ha::BuildBatchOpLogSnapshotSegmentsKey("snapshots", "1-42");
+    object_store.PutExisting(existing_key);
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto result =
+        writer.Write(*standby_, *capture, "snapshots", "1-42", 2, 1234);
+
+    EXPECT_FALSE(result);
+    EXPECT_TRUE(object_store.Contains(existing_key));
+    EXPECT_EQ(0u, object_store.cleanup_attempts);
+}
+
+TEST_F(BatchOpLogSnapshotWriterTest, CleansCandidateOnUploadFailure) {
+    auto capture = StartCapture(3);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    object_store.fail_upload_at = 2;
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto result =
+        writer.Write(*standby_, *capture, "snapshots", "1-42", 2, 1234);
+
+    EXPECT_FALSE(result);
+    EXPECT_EQ(0u, object_store.size());
+    EXPECT_EQ(1u, object_store.cleanup_attempts);
+}
+
+TEST_F(BatchOpLogSnapshotWriterTest, CleansCandidateOnChecksumMismatch) {
+    auto capture = StartCapture(1);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    object_store.provide_checksum = true;
+    object_store.bad_checksum = true;
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto result =
+        writer.Write(*standby_, *capture, "snapshots", "1-42", 2, 1234);
+
+    EXPECT_FALSE(result);
+    EXPECT_EQ(0u, object_store.size());
+    EXPECT_EQ(1u, object_store.cleanup_attempts);
+}
+
+TEST_F(BatchOpLogSnapshotWriterTest, CleansCandidateOnReadbackFailure) {
+    auto capture = StartCapture(1);
+    ASSERT_TRUE(capture);
+    FakeObjectStore object_store;
+    object_store.fail_download = true;
+    BatchOpLogSnapshotWriter writer(object_store);
+
+    auto result =
+        writer.Write(*standby_, *capture, "snapshots", "1-42", 2, 1234);
+
+    EXPECT_FALSE(result);
+    EXPECT_EQ(0u, object_store.size());
+    EXPECT_EQ(1u, object_store.cleanup_attempts);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store_test.cpp b/mooncake-store/tests/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store_test.cpp
index f22712d6af..1a54193577 100644
--- a/mooncake-store/tests/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store_test.cpp
+++ b/mooncake-store/tests/ha/snapshot/catalog/backends/redis/redis_snapshot_catalog_store_test.cpp
@@ -1,7 +1,9 @@
 #include <gflags/gflags.h>
 #include <gtest/gtest.h>
 
+#include <cstdlib>
 #include <memory>
+#include <optional>
 #include <string>
 #include <unordered_map>
 #include <vector>
@@ -19,6 +21,27 @@ DEFINE_string(redis_endpoint, "",
 
 namespace {
 
+class ScopedClusterId {
+   public:
+    ScopedClusterId() {
+        if (const char* value = std::getenv("MC_STORE_CLUSTER_ID")) {
+            original_ = value;
+        }
+        EXPECT_EQ(unsetenv("MC_STORE_CLUSTER_ID"), 0);
+    }
+
+    ~ScopedClusterId() {
+        if (original_) {
+            EXPECT_EQ(setenv("MC_STORE_CLUSTER_ID", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_STORE_CLUSTER_ID"), 0);
+        }
+    }
+
+   private:
+    std::optional<std::string> original_;
+};
+
 class FakeObjectStore final : public SnapshotObjectStore {
    public:
     tl::expected<void, std::string> UploadBuffer(
@@ -78,6 +101,39 @@ class FakeObjectStore final : public SnapshotObjectStore {
     std::unordered_map<std::string, std::string> objects_;
 };
 
+TEST(RedisSnapshotClusterNamespaceTest, ReadsFallbackForEachConstruction) {
+    ScopedClusterId env;
+    FakeObjectStore object_store;
+    using ha::backends::redis::RedisSnapshotCatalogStore;
+
+    RedisSnapshotCatalogStore missing(&object_store, "", "");
+    EXPECT_EQ(missing.GetSnapshotRoot(),
+              "mooncake_master_snapshot/mooncake_cluster/");
+
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "", 1), 0);
+    RedisSnapshotCatalogStore empty(&object_store, "", "");
+    EXPECT_EQ(empty.GetSnapshotRoot(),
+              "mooncake_master_snapshot/mooncake_cluster/");
+
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "team a", 1), 0);
+    RedisSnapshotCatalogStore configured(&object_store, "", "");
+    EXPECT_EQ(configured.GetSnapshotRoot(), "mooncake_master_snapshot/team a/");
+
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "team b", 1), 0);
+    RedisSnapshotCatalogStore changed(&object_store, "", "");
+    EXPECT_EQ(changed.GetSnapshotRoot(), "mooncake_master_snapshot/team b/");
+    EXPECT_EQ(configured.GetSnapshotRoot(), "mooncake_master_snapshot/team a/");
+}
+
+TEST(RedisSnapshotClusterNamespaceTest, ExplicitNamespaceOverridesEnvironment) {
+    ScopedClusterId env;
+    FakeObjectStore object_store;
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "environment", 1), 0);
+    ha::backends::redis::RedisSnapshotCatalogStore store(&object_store, "",
+                                                         "explicit");
+    EXPECT_EQ(store.GetSnapshotRoot(), "mooncake_master_snapshot/explicit/");
+}
+
 ha::SnapshotDescriptor MakeDescriptor(const std::string& snapshot_root,
                                       const std::string& snapshot_id) {
     ha::SnapshotDescriptor descriptor;
diff --git a/mooncake-store/tests/ha/snapshot/catalog_backed_snapshot_provider_test.cpp b/mooncake-store/tests/ha/snapshot/catalog_backed_snapshot_provider_test.cpp
index c81d5eccf8..fa4117492f 100644
--- a/mooncake-store/tests/ha/snapshot/catalog_backed_snapshot_provider_test.cpp
+++ b/mooncake-store/tests/ha/snapshot/catalog_backed_snapshot_provider_test.cpp
@@ -2,11 +2,11 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <chrono>
 #include <cstdint>
 #include <filesystem>
 #include <limits>
 #include <memory>
-#include <optional>
 #include <string>
 #include <vector>
 
@@ -71,7 +71,7 @@ class CatalogBackedSnapshotProviderTest
 
     // Loads the published snapshot and asserts the single default object
     // round-trips intact, regardless of the metadata on-wire format.
-    void ExpectLoadsDefaultObject() {
+    void ExpectLoadsDefaultObject(bool expected_hard_pinned = false) {
         auto provider = CreateProvider();
         ASSERT_TRUE(provider.has_value()) << toString(provider.error());
 
@@ -86,6 +86,7 @@ class CatalogBackedSnapshotProviderTest
         EXPECT_EQ(key, kDefaultTestObjectKey);
         EXPECT_EQ(metadata.client_id, (UUID{1, 2}));
         EXPECT_EQ(metadata.size, kDefaultTestObjectSize);
+        EXPECT_EQ(metadata.hard_pinned.value_or(false), expected_hard_pinned);
         ASSERT_EQ(metadata.replicas.size(), 1u);
 
         const auto& replica = metadata.replicas.front();
@@ -151,7 +152,6 @@ TEST_P(CatalogBackedSnapshotProviderTest, LoadLatestSnapshotRoundTrip) {
     EXPECT_EQ(entry.key, kDefaultTestObjectKey);
     EXPECT_EQ(entry.metadata.client_id, (UUID{1, 2}));
     EXPECT_EQ(entry.metadata.size, kDefaultTestObjectSize);
-    EXPECT_EQ(entry.metadata.last_sequence_id, descriptor_.last_included_seq);
     ASSERT_EQ(entry.metadata.replicas.size(), 1u);
 
     const auto& replica = entry.metadata.replicas.front();
@@ -179,14 +179,14 @@ TEST_P(CatalogBackedSnapshotProviderTest,
     // 8 + replica_count: trailing hard_pinned flag, no data_type. Exercises the
     // type-based disambiguation (first replica is not a positive integer).
     PublishSnapshotPayload(SnapshotMetadataFormat::kHardPinnedOnly);
-    ExpectLoadsDefaultObject();
+    ExpectLoadsDefaultObject(true);
 }
 
 TEST_P(CatalogBackedSnapshotProviderTest,
        LoadLatestSnapshotWithDataTypeAndHardPinned) {
     // 9 + replica_count: data_type + trailing hard_pinned.
     PublishSnapshotPayload(SnapshotMetadataFormat::kDataTypeAndHardPinned);
-    ExpectLoadsDefaultObject();
+    ExpectLoadsDefaultObject(true);
 }
 
 TEST_P(CatalogBackedSnapshotProviderTest, LoadLatestSnapshotWithGroupId) {
@@ -194,13 +194,37 @@ TEST_P(CatalogBackedSnapshotProviderTest, LoadLatestSnapshotWithGroupId) {
     // trailing group_id). Regression test for the live snapshot restore
     // failure against the latest metadata layout.
     PublishSnapshotPayload(SnapshotMetadataFormat::kWithGroupId);
-    ExpectLoadsDefaultObject();
+    ExpectLoadsDefaultObject(true);
 }
 
 TEST_P(CatalogBackedSnapshotProviderTest,
        LoadLatestSnapshotIgnoresObjectChecksum) {
     PublishSnapshotPayload(SnapshotMetadataFormat::kWithObjectChecksum);
-    ExpectLoadsDefaultObject();
+    ExpectLoadsDefaultObject(true);
+}
+
+TEST_P(CatalogBackedSnapshotProviderTest,
+       LoadLatestSnapshotIgnoresSoftPinForRetention) {
+    const auto now_ms = std::chrono::duration_cast<std::chrono::milliseconds>(
+                            std::chrono::system_clock::now().time_since_epoch())
+                            .count();
+    ASSERT_GT(now_ms, 0);
+    auto published = mooncake::test::PublishSnapshotPayloadBytes(
+        *object_store_, *catalog_store_, descriptor_,
+        BuildMetadataPayload(
+            UUID{1, 2}, kDefaultTestObjectKey, kDefaultTestDiskFilePath,
+            kDefaultTestObjectSize, kDefaultTestPutStartTimeMs,
+            static_cast<uint64_t>(now_ms - 1), SnapshotMetadataFormat::kLegacy,
+            static_cast<uint64_t>(now_ms + 60'000)));
+    ASSERT_TRUE(published.has_value()) << published.error();
+    snapshot_published_ = true;
+
+    auto provider = CreateProvider();
+    ASSERT_TRUE(provider.has_value()) << toString(provider.error());
+    auto snapshot = provider.value()->LoadLatestSnapshot(cluster_id_);
+    ASSERT_TRUE(snapshot.has_value()) << toString(snapshot.error());
+    ASSERT_TRUE(snapshot->has_value());
+    EXPECT_TRUE(snapshot->value().metadata.empty());
 }
 
 TEST_P(CatalogBackedSnapshotProviderTest, RejectsOverflowingReplicaCount) {
diff --git a/mooncake-store/tests/ha/snapshot/local_ssd_codec_test.cpp b/mooncake-store/tests/ha/snapshot/local_ssd_codec_test.cpp
new file mode 100644
index 0000000000..2bbf6e2b08
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/local_ssd_codec_test.cpp
@@ -0,0 +1,79 @@
+#include <gtest/gtest.h>
+
+#include "ha/snapshot/local_ssd_codec.h"
+
+namespace mooncake::ha {
+namespace {
+
+OffloadTaskItem Offload(std::string tenant, std::string key, int64_t size) {
+    return OffloadTaskItem{
+        .tenant_id = std::move(tenant), .key = std::move(key), .size = size};
+}
+
+std::string PackState(const LocalSsdPersistedState& state) {
+    msgpack::sbuffer buffer;
+    MsgpackPacker packer(&buffer);
+    EXPECT_TRUE(LocalSsdCodec::Encode(state, packer).has_value());
+    return std::string(buffer.data(), buffer.size());
+}
+
+TEST(LocalSsdCodecTest, RoundTripIsDeterministic) {
+    LocalSsdPersistedState state;
+    state[{9, 2}] = LocalSsdPersistedClient{
+        .enable_offloading = false,
+        .total_capacity_bytes = 10,
+        .pending_offloads = {{"z", Offload("tenant", "z", 1)}}};
+    state[{1, 8}] = LocalSsdPersistedClient{
+        .enable_offloading = true,
+        .total_capacity_bytes = 20,
+        .pending_offloads = {{"b", Offload("tenant", "b", 2)},
+                             {"a", Offload("tenant", "a", 3)}}};
+
+    auto first = PackState(state);
+    auto second = PackState(state);
+    EXPECT_EQ(first, second);
+    auto object = msgpack::unpack(first.data(), first.size());
+    auto decoded = LocalSsdCodec::Decode(&object.get());
+    ASSERT_TRUE(decoded.has_value());
+    EXPECT_EQ(PackState(*decoded), first);
+}
+
+TEST(LocalSsdCodecTest, DecodesLegacySizeAndPreservesEncodedKey) {
+    const std::string encoded_key("legacy\0key", 10);
+    msgpack::sbuffer buffer;
+    MsgpackPacker packer(&buffer);
+    packer.pack_map(1);
+    packer.pack(UuidToString(UUID{11, 12}));
+    packer.pack_array(4);
+    packer.pack(true);
+    packer.pack(uint64_t{1});
+    packer.pack(encoded_key);
+    packer.pack(int64_t{99});
+
+    auto object = msgpack::unpack(buffer.data(), buffer.size());
+    auto decoded = LocalSsdCodec::Decode(&object.get());
+    ASSERT_TRUE(decoded.has_value());
+    const auto& client = decoded->at(UUID{11, 12});
+    EXPECT_EQ(client.total_capacity_bytes, 0);
+    ASSERT_EQ(client.pending_offloads.size(), 1);
+    auto task = client.pending_offloads.find(encoded_key);
+    ASSERT_NE(task, client.pending_offloads.end());
+    EXPECT_EQ(task->second.tenant_id, "legacy");
+    EXPECT_EQ(task->second.key, "key");
+    EXPECT_EQ(task->second.size, 99);
+}
+
+TEST(LocalSsdCodecTest, MissingFieldIsEmptyAndInvalidInputFails) {
+    auto missing = LocalSsdCodec::Decode(nullptr);
+    ASSERT_TRUE(missing.has_value());
+    EXPECT_TRUE(missing->empty());
+
+    msgpack::sbuffer buffer;
+    MsgpackPacker packer(&buffer);
+    packer.pack_array(0);
+    auto object = msgpack::unpack(buffer.data(), buffer.size());
+    EXPECT_FALSE(LocalSsdCodec::Decode(&object.get()).has_value());
+}
+
+}  // namespace
+}  // namespace mooncake::ha
diff --git a/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot.cpp b/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot.cpp
index 4231a9ef99..d329ae7aa0 100644
--- a/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot.cpp
+++ b/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot.cpp
@@ -1216,7 +1216,15 @@ TEST_F(MasterServiceSnapshotTest, ConcurrentRemoveAllOperations) {
 }
 
 TEST_F(MasterServiceSnapshotTest, UnmountSegmentImmediateCleanup) {
-    service_.reset(new MasterService());
+    // Snapshot mode keeps the invalid-handle sweep synchronous inside
+    // UnmountSegment. A default-configured MasterService would instead defer
+    // it to the replica cleanup worker, making the key-count assertion below
+    // race with that worker.
+    auto service_config = MasterServiceConfig::builder()
+                              .set_enable_snapshot(true)
+                              .set_snapshot_object_store_type("local")
+                              .build();
+    service_.reset(new MasterService(service_config));
 
     // Mount two segments for testing
     constexpr size_t buffer1 = 0x300000000;
@@ -1272,7 +1280,11 @@ TEST_F(MasterServiceSnapshotTest, UnmountSegmentImmediateCleanup) {
 }
 
 TEST_F(MasterServiceSnapshotTest, ReadableAfterPartialUnmountWithReplication) {
-    service_.reset(new MasterService());
+    auto service_config = MasterServiceConfig::builder()
+                              .set_enable_snapshot(true)
+                              .set_snapshot_object_store_type("local")
+                              .build();
+    service_.reset(new MasterService(service_config));
 
     // Mount two large segments
     constexpr size_t buffer1 = 0x300000000;
@@ -1328,7 +1340,11 @@ TEST_F(MasterServiceSnapshotTest, ReadableAfterPartialUnmountWithReplication) {
 }
 
 TEST_F(MasterServiceSnapshotTest, UnmountSegmentPerformance) {
-    service_.reset(new MasterService());
+    auto service_config = MasterServiceConfig::builder()
+                              .set_enable_snapshot(true)
+                              .set_snapshot_object_store_type("local")
+                              .build();
+    service_.reset(new MasterService(service_config));
     constexpr size_t kBufferAddress = 0x300000000;
     constexpr size_t kSegmentSize = 1024 * 1024 * 256;  // 256MB
     std::string segment_name = "perf_test_segment";
@@ -1642,7 +1658,7 @@ TEST_F(MasterServiceSnapshotTest, RemoveSoftPinObject) {
     uint64_t slice_length = 1024;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.with_soft_pin = true;
+    config.soft_pin_action = SoftPinAction::ENABLE;
 
     // Verify soft pin does not block remove
     ASSERT_TRUE(service_
@@ -1698,7 +1714,7 @@ TEST_F(MasterServiceSnapshotTest, SoftPinObjectsNotEvictedBeforeOtherObjects) {
             uint64_t slice_length = value_size;
             ReplicateConfig soft_pin_config;
             soft_pin_config.replica_num = 1;
-            soft_pin_config.with_soft_pin = true;
+            soft_pin_config.soft_pin_action = SoftPinAction::ENABLE;
 
             ASSERT_TRUE(service_
                             ->PutStart(client_id, pin_key, TenantId::Default(),
@@ -1779,7 +1795,7 @@ TEST_F(MasterServiceSnapshotTest, SoftPinObjectsCanBeEvicted) {
         uint64_t slice_length = value_size;
         ReplicateConfig config;
         config.replica_num = 1;
-        config.with_soft_pin = true;
+        config.soft_pin_action = SoftPinAction::ENABLE;
         if (service_
                 ->PutStart(client_id, key, TenantId::Default(), slice_length,
                            config)
@@ -1807,101 +1823,53 @@ TEST_F(MasterServiceSnapshotTest, SoftPinObjectsCanBeEvicted) {
     // service_->RemoveAll();
 }
 
-TEST_F(MasterServiceSnapshotTest, SoftPinExtendedOnGet) {
+TEST_F(MasterServiceSnapshotTest, SoftPinExpiresAndGetDoesNotReactivate) {
     const uint64_t kv_lease_ttl = 200;
-    // The soft pin ttl shall not be too large, otherwise the test will take too
-    // long
-    const uint64_t kv_soft_pin_ttl = 1000;
-    static_assert(
-        kv_soft_pin_ttl > kv_lease_ttl,
-        "kv_soft_pin_ttl must be larger than kv_lease_ttl in this test");
-    const double eviction_ratio = 0.5;
-    const bool allow_evict_soft_pinned_objects = true;
+    const uint64_t kv_soft_pin_ttl = 20;
     auto service_config = MasterServiceConfig::builder()
                               .set_default_kv_lease_ttl(kv_lease_ttl)
                               .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .set_eviction_ratio(eviction_ratio)
                               .build();
     service_.reset(new MasterService(service_config));
     const UUID client_id = generate_uuid();
 
-    // Mount segment and put an object
     constexpr size_t buffer = 0x300000000;
     constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
+    constexpr size_t value_size = 1024;
     [[maybe_unused]] const auto context =
         PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
 
-    // The eviction has random factors, so test 3 times
-    for (int test_i = 0; test_i < 3; test_i++) {
-        // Put pin_key first
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig soft_pin_config;
-            soft_pin_config.replica_num = 1;
-            soft_pin_config.with_soft_pin = true;
-
-            ASSERT_TRUE(service_->PutStart(client_id, pin_key,
-                                           TenantId::Default(), slice_length,
-                                           soft_pin_config));
-            ASSERT_TRUE(service_
-                            ->PutEnd(client_id, pin_key, TenantId::Default(),
-                                     ReplicaType::MEMORY)
-                            .has_value());
-        }
-
-        // Wait for the soft pin to expire
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_soft_pin_ttl));
-
-        // Get the pin_key to extend the soft pin
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            ASSERT_TRUE(service_->GetReplicaList(pin_key, TenantId::Default())
-                            .has_value());
-        }
-
-        // Fill the segment to trigger eviction
-        int failed_puts = 0;
-        for (int i = 0; i < 16; i++) {
-            std::string key = "key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig config;
-            config.replica_num = 1;
-            if (service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value()) {
-                ASSERT_TRUE(service_
-                                ->PutEnd(client_id, key, TenantId::Default(),
-                                         ReplicaType::MEMORY)
-                                .has_value());
-            } else {
-                failed_puts++;
-            }
-        }
-        ASSERT_GT(failed_puts, 0);
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
+    ReplicateConfig config;
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    ASSERT_TRUE(service_
+                    ->PutStart(client_id, "pin_key", TenantId::Default(),
+                               value_size, config)
+                    .has_value());
+    ASSERT_TRUE(service_
+                    ->PutEnd(client_id, "pin_key", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
 
-        // wait for eviction
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
+    std::this_thread::sleep_for(
+        std::chrono::milliseconds(kv_soft_pin_ttl + 10));
+    ASSERT_TRUE(
+        service_->GetReplicaList("pin_key", TenantId::Default()).has_value());
 
-        // pin_key should still be accessible
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            ASSERT_TRUE(service_->GetReplicaList(pin_key, TenantId::Default())
-                            .has_value());
-        }
-        // [Commented for snapshot test] The following RemoveAll would clear
-        // data before TearDown snapshot verification Only remove all objects
-        // before the next turn (skip last round)
-        if (test_i < 2) {
-            std::this_thread::sleep_for(
-                std::chrono::milliseconds(kv_lease_ttl));
-            service_->RemoveAll();
-        }
-    }
+    ReplicateConfig preserve;
+    ASSERT_TRUE(service_
+                    ->UpsertStart(client_id, "pin_key", TenantId::Default(),
+                                  value_size, preserve)
+                    .has_value());
+    ASSERT_TRUE(service_
+                    ->UpsertEnd(client_id, "pin_key", TenantId::Default(),
+                                ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 }
 
 TEST_F(MasterServiceSnapshotTest, SoftPinObjectsNotAllowEvict) {
@@ -1934,7 +1902,7 @@ TEST_F(MasterServiceSnapshotTest, SoftPinObjectsNotAllowEvict) {
         uint64_t slice_length = value_size;
         ReplicateConfig config;
         config.replica_num = 1;
-        config.with_soft_pin = true;
+        config.soft_pin_action = SoftPinAction::ENABLE;
         if (service_
                 ->PutStart(client_id, key, TenantId::Default(), slice_length,
                            config)
@@ -2454,19 +2422,30 @@ TEST_F(MasterServiceSnapshotTest, PutStartExpiringTest) {
 
     // Put key_2 again, should fail because eviction has not been triggered. And
     // this PutStart should trigger the eviction.
+    const int64_t eviction_attempts_before =
+        MasterMetricManager::instance().get_mem_eviction_attempts();
     put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
                                           slice_length, config);
-    EXPECT_FALSE(put_start_result.has_value());
+    ASSERT_FALSE(put_start_result.has_value());
     EXPECT_EQ(put_start_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
 
-    // Wait a moment for the eviction to complete.
-    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(4);
+    while (MasterMetricManager::instance().get_mem_eviction_attempts() <=
+               eviction_attempts_before &&
+           std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    }
+    ASSERT_GT(MasterMetricManager::instance().get_mem_eviction_attempts(),
+              eviction_attempts_before)
+        << "Timed out waiting for asynchronous eviction";
 
     // Put key_2 again, should success because the previous one has been
     // discarded and released.
     put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
                                           slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
+    ASSERT_TRUE(put_start_result.has_value())
+        << toString(put_start_result.error());
     replica_list = put_start_result.value();
     EXPECT_EQ(replica_list.size(), kReplicaCnt);
     for (size_t i = 0; i < kReplicaCnt; i++) {
@@ -2656,7 +2635,7 @@ TEST_F(MasterServiceSnapshotTest, BatchReplicaClearSpecificSegment) {
     ASSERT_TRUE(put_end_result.has_value());
 
     // 4. Wait for lease to expire and verify it's actually expired
-    // PutEnd calls GrantLease(0, ...) which sets lease_timeout to now.
+    // PutEnd grants a zero-duration read lease, setting lease_timeout to now.
     // Due to clock precision and timing, we need to ensure the lease is
     // actually expired before calling BatchReplicaClear.
     // Use a small delay and then poll to ensure lease is expired.
@@ -3378,8 +3357,7 @@ TEST_F(MasterServiceSnapshotTest, CopyStart) {
 
     // Mount 4 segments (segment_1, segment_2, segment_3, segment_4) with
     // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
     [[maybe_unused]] const auto context2 =
         PrepareSimpleSegment(*service_, "segment_2");
     [[maybe_unused]] const auto context3 =
@@ -3387,7 +3365,7 @@ TEST_F(MasterServiceSnapshotTest, CopyStart) {
     [[maybe_unused]] const auto context4 =
         PrepareSimpleSegment(*service_, "segment_4");
 
-    UUID client_id = generate_uuid();
+    UUID client_id = context1.client_id;
 
     // Test Case 1: CopyStart a non-existent key, should fail.
     auto copy_result =
@@ -3522,15 +3500,13 @@ TEST_F(MasterServiceSnapshotTest, CopyEnd) {
 
     // Mount 3 segments (segment_1, segment_2, segment_3) with
     // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
+    const auto context2 = PrepareSimpleSegment(*service_, "segment_2");
     [[maybe_unused]] const auto context3 =
         PrepareSimpleSegment(*service_, "segment_3");
 
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
+    UUID client_id = context1.client_id;
+    UUID invalid_client_id = context2.client_id;
 
     // Test Case 1: CopyEnd a non-existent key, should fail.
     auto copy_end_result =
@@ -3637,13 +3613,11 @@ TEST_F(MasterServiceSnapshotTest, CopyRevoke) {
 
     // Mount 2 segments (segment_1, segment_2) with
     // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
+    const auto context2 = PrepareSimpleSegment(*service_, "segment_2");
 
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
+    UUID client_id = context1.client_id;
+    UUID invalid_client_id = context2.client_id;
 
     // Test Case 1: CopyRevoke a non-existent key, should fail.
     auto copy_revoke_result = service_->CopyRevoke(
@@ -3728,13 +3702,11 @@ TEST_F(MasterServiceSnapshotTest, MoveEnd) {
 
     // Mount 2 segments (segment_1, segment_2) with
     // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
+    const auto context2 = PrepareSimpleSegment(*service_, "segment_2");
 
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
+    UUID client_id = context1.client_id;
+    UUID invalid_client_id = context2.client_id;
 
     // Test Case 1: MoveEnd a non-existent key, should fail.
     auto move_end_result =
@@ -3810,13 +3782,11 @@ TEST_F(MasterServiceSnapshotTest, MoveRevoke) {
     service_.reset(new MasterService());
 
     // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
+    const auto context2 = PrepareSimpleSegment(*service_, "segment_2");
 
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
+    UUID client_id = context1.client_id;
+    UUID invalid_client_id = context2.client_id;
 
     // Test Case 1: MoveRevoke a non-existent key, should fail.
     auto move_revoke_result = service_->MoveRevoke(
@@ -3908,14 +3878,13 @@ TEST_F(MasterServiceSnapshotTest, MoveStart) {
 
     // Mount 3 segments (segment_1, segment_2, segment_3) with
     // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
+    const auto context1 = PrepareSimpleSegment(*service_, "segment_1");
     [[maybe_unused]] const auto context2 =
         PrepareSimpleSegment(*service_, "segment_2");
     [[maybe_unused]] const auto context3 =
         PrepareSimpleSegment(*service_, "segment_3");
 
-    UUID client_id = generate_uuid();
+    UUID client_id = context1.client_id;
 
     // Test Case 1: MoveStart a non-existent key, should fail.
     auto move_start_result =
@@ -4059,12 +4028,12 @@ TEST_F(MasterServiceSnapshotTest, ProtectCopyMoveSourceFromEviction) {
     // 16 MB
     constexpr size_t kBaseAddr = 0x100000000;
     constexpr size_t kSegmentSize = 16 * 1024 * 1024;  // 16 MB
-    [[maybe_unused]] const auto context1 =
+    const auto context1 =
         PrepareSimpleSegment(*service_, "segment_1", kBaseAddr, kSegmentSize);
     [[maybe_unused]] const auto context2 =
         PrepareSimpleSegment(*service_, "segment_2", kBaseAddr, kSegmentSize);
 
-    UUID client_id = generate_uuid();
+    UUID client_id = context1.client_id;
 
     const std::string copy_key = "copy_key";
     const std::string move_key = "move_key";
diff --git a/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot_base.h b/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot_base.h
index 5486e9daf0..05bb73a8eb 100644
--- a/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot_base.h
+++ b/mooncake-store/tests/ha/snapshot/master_service_test_for_snapshot_base.h
@@ -1,6 +1,7 @@
 #pragma once
 
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 #include "master_snapshot_manager.h"
 #include "master_metric_manager.h"
 #include "segment.h"
@@ -19,6 +20,7 @@
 #include <iomanip>
 #include <map>
 #include <memory>
+#include <mutex>
 #include <sstream>
 #include <thread>
 #include <unordered_map>
@@ -160,14 +162,15 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
 
     // ==================== Snapshot Helper Methods ====================
 
-    // Wrapper method: Call MasterSnapshotManager's PersistState through
-    // MasterService This class is a friend of MasterService, so it can access
-    // private members
+    // Persist the master's snapshot using state exposed by the test peer.
     static tl::expected<void, SerializationError> CallPersistState(
         MasterService* service, const std::string& snapshot_id) {
+        std::unique_lock<std::shared_mutex> snapshot_lock(
+            MasterServiceTestPeer::SnapshotMutex(*service));
         // If snapshot_manager_ exists, use it; otherwise create a temporary one
-        if (service->snapshot_manager_) {
-            return service->snapshot_manager_->PersistState(snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service)) {
+            return MasterServiceTestPeer::SnapshotManager(*service)
+                ->PersistState(snapshot_id);
         }
 
         // For tests that don't have snapshot_manager_ initialized,
@@ -176,38 +179,31 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
         EnsureSnapshotStores(service);
 
         MasterSnapshotManagerOptions options;
-        options.enable_snapshot = true;
         options.snapshot_interval_seconds = 300;
         options.snapshot_child_timeout_seconds = 300;
         options.snapshot_retention_count = 3;
         options.snapshot_backup_dir = "";
         options.use_snapshot_backup_dir = false;
-        options.snapshot_catalog_store_type =
-            service->snapshot_catalog_store_type_;
-        options.snapshot_catalog_store_connstring =
-            service->snapshot_catalog_store_connstring_;
-        options.ha_backend_type = service->ha_backend_type_;
-        options.ha_backend_connstring = service->ha_backend_connstring_;
-        options.cluster_id = service->cluster_id_;
-        options.enable_ha = service->enable_ha_;
 
         auto temp_manager = std::make_unique<MasterSnapshotManager>(
-            service, options, service->snapshot_mutex_,
-            service->snapshot_object_store_.get(),
-            service->snapshot_catalog_store_.get());
+            service, options, MasterServiceTestPeer::SnapshotMutex(*service),
+            MasterServiceTestPeer::SnapshotObjectStore(*service).get(),
+            MasterServiceTestPeer::SnapshotCatalogStore(*service).get());
 
         return temp_manager->PersistState(snapshot_id);
     }
 
     static void EnsureSnapshotStores(MasterService* service) {
-        if (!service->snapshot_object_store_) {
-            service->snapshot_object_store_ = SnapshotObjectStore::Create(
-                SnapshotObjectStoreType::LOCAL_FILE);
+        if (!MasterServiceTestPeer::SnapshotObjectStore(*service)) {
+            MasterServiceTestPeer::SnapshotObjectStore(*service) =
+                SnapshotObjectStore::Create(
+                    SnapshotObjectStoreType::LOCAL_FILE);
         }
-        if (!service->snapshot_catalog_store_ &&
-            service->snapshot_object_store_) {
-            service->snapshot_catalog_store_ =
-                service->CreateSnapshotCatalogStore();
+        if (!MasterServiceTestPeer::SnapshotCatalogStore(*service) &&
+            MasterServiceTestPeer::SnapshotObjectStore(*service)) {
+            MasterServiceTestPeer::SnapshotCatalogStore(*service) =
+                MasterServiceTestPeer(*service).CreateSnapshotCatalogStore(
+                    MasterServiceConfig{});
         }
     }
 
@@ -283,30 +279,30 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
         // === Enhanced State ===
         state.key_count = service->GetKeyCount();
 
-        // === LocalDiskSegment State (via friend access) ===
+        // === LocalSSD persisted state ===
         {
-            auto access = service->segment_manager_.getLocalDiskSegmentAccess();
-            // Copy client_by_name_ to sorted map
-            for (const auto& [name, client_id] : access.getClientByName()) {
-                state.client_by_name[name] = client_id;
+            auto access = MasterServiceTestPeer::SegmentManager(*service)
+                              .getAllocatorAccess();
+            for (const auto& name : state.all_segments) {
+                auto client_id = access.GetOwnerClientId(name);
+                if (client_id) {
+                    state.client_by_name[name] = *client_id;
+                }
             }
-            // Copy local_disk_segments with full state
-            for (const auto& [client_id, segment] :
-                 access.getClientLocalDiskSegment()) {
+            for (const auto& [client_id, client] :
+                 MasterServiceTestPeer::LocalSsdManager(*service)
+                     .ExportPersistedState()) {
                 LocalDiskSegmentState seg_state;
-                seg_state.enable_offloading = segment->enable_offloading;
-                // Copy offloading_objects to sorted map
-                std::lock_guard<Mutex> lock(segment->offloading_mutex_);
-                for (const auto& [key, task] : segment->offloading_objects) {
-                    seg_state.offloading_objects[key] = task;
-                }
+                seg_state.enable_offloading = client.enable_offloading;
+                seg_state.offloading_objects = client.pending_offloads;
                 state.local_disk_segments[client_id] = std::move(seg_state);
             }
         }
 
-        // === TaskManager State (via friend access) ===
+        // === TaskManager State (via test peer) ===
         {
-            auto read_access = service->task_manager_.get_read_access();
+            auto read_access =
+                MasterServiceTestPeer::TaskManager(*service).get_read_access();
             for (const auto& [task_id, task] : read_access) {
                 TaskState task_state;
                 task_state.id = task.id;
@@ -758,6 +754,65 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
 
     // ==================== Core Test Method ====================
 
+    static void AssertRestoredClientAffiliations(MasterService* service) {
+        std::unordered_set<const ClientLivenessRecord*> known_records;
+        {
+            auto segment_access =
+                MasterServiceTestPeer::SegmentManager(*service)
+                    .getSegmentAccess();
+            std::vector<std::pair<Segment, UUID>> segments;
+            ASSERT_EQ(segment_access.GetAllSegments(segments), ErrorCode::OK);
+            for (const auto& [segment, owner] : segments) {
+                (void)segment;
+                const auto record =
+                    MasterServiceTestPeer::ClientLivenessRecords(*service).find(
+                        owner);
+                ASSERT_NE(record,
+                          MasterServiceTestPeer::ClientLivenessRecords(*service)
+                              .end());
+                known_records.insert(record->second.get());
+            }
+        }
+        for (const auto& owner :
+             MasterServiceTestPeer::LocalSsdManager(*service).GetClientIds()) {
+            ASSERT_TRUE(
+                MasterServiceTestPeer::ClientLivenessRecords(*service).contains(
+                    owner));
+        }
+
+        for (const auto& shard :
+             MasterServiceTestPeer::MetadataShards(*service)) {
+            for (const auto& [tenant_id, tenant_state] : shard.tenants) {
+                (void)tenant_id;
+                for (const auto& [key, metadata] : tenant_state.metadata) {
+                    (void)key;
+                    for (const auto& replica : metadata.GetAllReplicas()) {
+                        if (replica.is_memory_replica()) {
+                            const auto record = replica.getClientLiveness();
+                            ASSERT_TRUE(record);
+                            EXPECT_TRUE(known_records.contains(record.get()));
+                        } else if (replica.is_local_disk_replica()) {
+                            const auto owner =
+                                replica.get_local_disk_client_id();
+                            ASSERT_TRUE(owner.has_value());
+                            const auto record =
+                                MasterServiceTestPeer::ClientLivenessRecords(
+                                    *service)
+                                    .find(*owner);
+                            ASSERT_NE(
+                                record,
+                                MasterServiceTestPeer::ClientLivenessRecords(
+                                    *service)
+                                    .end());
+                            EXPECT_TRUE(
+                                replica.isAffiliatedWith(record->second));
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     // Test snapshot and restore functionality
     void TestSnapshotAndRestore(std::unique_ptr<MasterService>& service) {
         // ========== Phase 1: Manually persist metadata ==========
@@ -779,11 +834,22 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
                 .set_memory_allocator(BufferAllocatorType::OFFSET)
                 .set_enable_snapshot_restore(true)
                 .set_snapshot_object_store_type("local")
-                .set_root_fs_dir(service->root_fs_dir_)
+                .set_root_fs_dir(MasterServiceTestPeer::RootFsDir(*service))
+                // Prevent eviction before the constructor returns and we can
+                // stop the restored instance's eviction worker.
+                .set_eviction_high_watermark_ratio(1.0)
                 .build();
         std::unique_ptr<MasterService> restored_service(
             new MasterService(restore_config));
         ::unsetenv("MOONCAKE_MASTER_SERVICE_SNAPSHOT_TEST_SKIP_CLEANUP");
+        // Freeze the restored instance before comparing snapshots. Its
+        // eviction worker would otherwise mutate metadata between snapshots.
+        MasterServiceTestPeer::EvictionRunning(*restored_service) = false;
+        if (MasterServiceTestPeer::EvictionThread(*restored_service)
+                .joinable()) {
+            MasterServiceTestPeer::EvictionThread(*restored_service).join();
+        }
+        AssertRestoredClientAffiliations(restored_service.get());
 
         // ========== Phase 4: Persist restored metadata again ==========
         std::string snapshot_id2 = GenerateSnapshotId();
@@ -839,6 +905,15 @@ class MasterServiceSnapshotTestBase : public ::testing::Test {
             << "Use 'service_.reset(new MasterService(...))' instead of "
                "'std::unique_ptr<MasterService> service_(...)'";
 
+        // Freeze the original service before snapshot/restore validation. The
+        // eviction worker can otherwise mutate replica metadata while the
+        // snapshot is being serialized, making the post-restore comparison
+        // compare two different points in time.
+        MasterServiceTestPeer::EvictionRunning(*service_) = false;
+        if (MasterServiceTestPeer::EvictionThread(*service_).joinable()) {
+            MasterServiceTestPeer::EvictionThread(*service_).join();
+        }
+
         // Some test configs may not enable snapshot/restore, so the backend
         // is not created in the constructor. We create it here for TearDown
         // validation.
diff --git a/mooncake-store/tests/ha/snapshot/master_snapshot_codec_test.cpp b/mooncake-store/tests/ha/snapshot/master_snapshot_codec_test.cpp
index c83c7e4f03..e7ef7ef8d3 100644
--- a/mooncake-store/tests/ha/snapshot/master_snapshot_codec_test.cpp
+++ b/mooncake-store/tests/ha/snapshot/master_snapshot_codec_test.cpp
@@ -9,13 +9,16 @@
 #include "ha/snapshot/master_snapshot_codec.h"
 #include "master_config.h"
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 #include "segment.h"
 #include "task_manager.h"
 #include "tenant_id.h"
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake::ha {
 
+using mooncake::test::MasterServiceTestPeer;
+
 class MasterSnapshotCodecTest : public ::testing::Test {
    protected:
     void SetUp() override { master_service_ = MakeMasterService(); }
@@ -29,13 +32,13 @@ class MasterSnapshotCodecTest : public ::testing::Test {
         return std::make_unique<MasterService>(config);
     }
 
-    // The fixture is befriended by MasterService, so private state access is
-    // funneled through this helper (friendship is not inherited by the
-    // TEST_F-generated subclasses).
+    // Assemble the codec state view through the shared test peer.
     static MasterSnapshotStateView MakeStateView(MasterService& service) {
-        return MasterSnapshotStateView(service, service.segment_manager_,
-                                       service.nof_segment_manager_,
-                                       service.task_manager_);
+        return MasterSnapshotStateView(
+            service, MasterServiceTestPeer::SegmentManager(service),
+            MasterServiceTestPeer::LocalSsdManager(service),
+            MasterServiceTestPeer::NofSegmentManager(service),
+            MasterServiceTestPeer::TaskManager(service));
     }
 
     std::unique_ptr<MasterService> master_service_;
diff --git a/mooncake-store/tests/ha/snapshot/object/backends/local/local_file_snapshot_object_store_test.cpp b/mooncake-store/tests/ha/snapshot/object/backends/local/local_file_snapshot_object_store_test.cpp
index 1104ab84be..5fed236f87 100644
--- a/mooncake-store/tests/ha/snapshot/object/backends/local/local_file_snapshot_object_store_test.cpp
+++ b/mooncake-store/tests/ha/snapshot/object/backends/local/local_file_snapshot_object_store_test.cpp
@@ -3,6 +3,7 @@
 
 #include <cstdlib>
 #include <filesystem>
+#include <optional>
 #include <string>
 #include <vector>
 
@@ -22,6 +23,11 @@ class LocalFileSnapshotObjectStoreTest : public ::testing::Test {
         google::InitGoogleLogging("LocalFileSnapshotObjectStoreTest");
         FLAGS_logtostderr = true;
 
+        if (const char* value = std::getenv("MOONCAKE_SNAPSHOT_LOCAL_PATH")) {
+            original_path_ = value;
+        }
+        ASSERT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+
         // Create a unique temporary directory
         std::string tmpl = (fs::temp_directory_path() /
                             "local_file_snapshot_object_store_test_XXXXXX")
@@ -35,6 +41,13 @@ class LocalFileSnapshotObjectStoreTest : public ::testing::Test {
 
     void TearDown() override {
         backend_.reset();
+        if (original_path_) {
+            EXPECT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH",
+                             original_path_->c_str(), 1),
+                      0);
+        } else {
+            EXPECT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+        }
         if (!tmp_dir().empty() && fs::exists(tmp_dir())) {
             fs::remove_all(tmp_dir());
         }
@@ -43,6 +56,7 @@ class LocalFileSnapshotObjectStoreTest : public ::testing::Test {
 
    private:
     std::string tmp_dir_;
+    std::optional<std::string> original_path_;
 };
 
 // ========== Normal Functionality ==========
@@ -105,6 +119,15 @@ TEST_F(LocalFileSnapshotObjectStoreTest, GetConnectionInfo) {
     EXPECT_NE(info.find(tmp_dir()), std::string::npos);
 }
 
+TEST_F(LocalFileSnapshotObjectStoreTest, InspectObjectReturnsSize) {
+    ASSERT_TRUE(backend_->UploadString("test/inspect", "data"));
+
+    auto inspection = backend_->InspectObject("test/inspect");
+    ASSERT_TRUE(inspection) << inspection.error();
+    EXPECT_EQ(4u, inspection->stored_size);
+    EXPECT_FALSE(inspection->crc32c.has_value());
+}
+
 TEST_F(LocalFileSnapshotObjectStoreTest, UploadBuffer_CreatesSubdirectories) {
     std::vector<uint8_t> data = {42};
     auto result = backend_->UploadBuffer("a/b/c/deep_file", data);
@@ -119,7 +142,84 @@ TEST_F(LocalFileSnapshotObjectStoreTest, UploadBuffer_CreatesSubdirectories) {
 // ========== Error Handling ==========
 
 TEST_F(LocalFileSnapshotObjectStoreTest, Constructor_EmptyPath_Throws) {
-    EXPECT_THROW(LocalFileSnapshotObjectStore(""), std::runtime_error);
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", tmp_dir().c_str(), 1), 0);
+    try {
+        LocalFileSnapshotObjectStore store("");
+        FAIL()
+            << "An empty explicit path must not fall back to the environment";
+    } catch (const std::runtime_error& error) {
+        EXPECT_STREQ(
+            error.what(),
+            "LocalFileSnapshotObjectStore base_path is empty. "
+            "Please provide a valid persistent directory path for snapshot "
+            "storage.");
+    }
+}
+
+TEST_F(LocalFileSnapshotObjectStoreTest, Constructor_MissingOrEmptyEnv_Throws) {
+    for (const char* value : {static_cast<const char*>(nullptr), ""}) {
+        if (value) {
+            ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", value, 1), 0);
+        } else {
+            ASSERT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+        }
+        try {
+            LocalFileSnapshotObjectStore store;
+            FAIL() << "A missing or empty environment path must be rejected";
+        } catch (const std::runtime_error& error) {
+            EXPECT_STREQ(
+                error.what(),
+                "MOONCAKE_SNAPSHOT_LOCAL_PATH environment variable is not set. "
+                "Please set it to a persistent directory path for snapshot "
+                "storage. Example: export "
+                "MOONCAKE_SNAPSHOT_LOCAL_PATH=/data/mooncake_snapshots");
+        }
+    }
+}
+
+TEST_F(LocalFileSnapshotObjectStoreTest, Constructor_ReadsEnvForEachStore) {
+    const auto first_path = fs::path(tmp_dir()) / "first" / "snapshots";
+    ASSERT_FALSE(fs::exists(first_path));
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", first_path.c_str(), 1), 0);
+    LocalFileSnapshotObjectStore first;
+    ASSERT_TRUE(fs::is_directory(first_path));
+
+    const auto second_path = fs::path(tmp_dir()) / "second";
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", second_path.c_str(), 1),
+              0);
+    LocalFileSnapshotObjectStore second;
+
+    ASSERT_TRUE(first.UploadString("key", "first snapshot"));
+    ASSERT_TRUE(second.UploadString("key", "second snapshot"));
+    EXPECT_TRUE(fs::is_regular_file(first_path / "key"));
+    EXPECT_TRUE(fs::is_regular_file(second_path / "key"));
+
+    std::string data;
+    ASSERT_TRUE(first.DownloadString("key", data));
+    EXPECT_EQ(data, "first snapshot");
+    ASSERT_TRUE(second.DownloadString("key", data));
+    EXPECT_EQ(data, "second snapshot");
+}
+
+TEST_F(LocalFileSnapshotObjectStoreTest, Constructor_EnvRegularFile_Throws) {
+    ASSERT_TRUE(backend_->UploadString("regular-file", "data"));
+    const auto path = fs::path(tmp_dir()) / "regular-file";
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", path.c_str(), 1), 0);
+    EXPECT_THROW(LocalFileSnapshotObjectStore{}, std::runtime_error);
+}
+
+TEST_F(LocalFileSnapshotObjectStoreTest, Constructor_ExplicitPathIgnoresEnv) {
+    EXPECT_NO_THROW(LocalFileSnapshotObjectStore{tmp_dir()});
+    const std::string env_path = (fs::path(tmp_dir()) / "unused-env").string();
+    const std::string explicit_path =
+        (fs::path(tmp_dir()) / "explicit").string();
+    for (const auto& value : {std::string{}, env_path}) {
+        ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", value.c_str(), 1), 0);
+        LocalFileSnapshotObjectStore store(explicit_path);
+        ASSERT_TRUE(store.UploadString("key", "explicit path"));
+        EXPECT_TRUE(fs::is_regular_file(fs::path(explicit_path) / "key"));
+        EXPECT_FALSE(fs::exists(env_path));
+    }
 }
 
 TEST_F(LocalFileSnapshotObjectStoreTest, DownloadBuffer_NonExistentKey) {
diff --git a/mooncake-store/tests/ha/snapshot/snapshot_child_process_test.cpp b/mooncake-store/tests/ha/snapshot/snapshot_child_process_test.cpp
index 0d9b58769b..fe8785af81 100644
--- a/mooncake-store/tests/ha/snapshot/snapshot_child_process_test.cpp
+++ b/mooncake-store/tests/ha/snapshot/snapshot_child_process_test.cpp
@@ -1,4 +1,5 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 #include "master_snapshot_manager.h"
 #include "master_snapshot_repository.h"
 #include "master_metric_manager.h"
@@ -18,6 +19,7 @@
 #include <cstdlib>
 #include <filesystem>
 #include <memory>
+#include <optional>
 #include <regex>
 #include <string>
 #include <thread>
@@ -27,7 +29,7 @@
 #include <sys/wait.h>
 #include <unistd.h>
 
-#include "utils/file_util.h"
+#include "common/file_util.h"
 
 namespace mooncake::test {
 
@@ -45,10 +47,16 @@ class SnapshotChildProcessTest : public ::testing::Test {
     }
 
     std::unique_ptr<MasterService> service_;
+    MasterServiceConfig service_config_;
 
     static constexpr const char* kEnvSnapshotLocalPath =
         "MOONCAKE_SNAPSHOT_LOCAL_PATH";
 
+    void CreateService(MasterServiceConfig config) {
+        service_config_ = std::move(config);
+        service_ = std::make_unique<MasterService>(service_config_);
+    }
+
     void SetUp() override {
         google::InitGoogleLogging("SnapshotChildProcessTest");
         FLAGS_logtostderr = true;
@@ -90,7 +98,7 @@ class SnapshotChildProcessTest : public ::testing::Test {
                           .set_snapshot_object_store_type("local")
                           .set_view_version(view_version)
                           .build();
-        service_ = std::make_unique<MasterService>(config);
+        CreateService(std::move(config));
     }
 
 #ifdef STORE_USE_ETCD
@@ -112,7 +120,7 @@ class SnapshotChildProcessTest : public ::testing::Test {
                           .set_snapshot_object_store_type("local")
                           .set_view_version(view_version)
                           .build();
-        service_ = std::make_unique<MasterService>(config);
+        CreateService(std::move(config));
     }
 
     void CreateBatchEtcdHASnapshotService(const std::string& cluster_id,
@@ -133,16 +141,17 @@ class SnapshotChildProcessTest : public ::testing::Test {
                           .set_snapshot_object_store_type("local")
                           .set_view_version(view_version)
                           .build();
-        service_ = std::make_unique<MasterService>(config);
+        CreateService(std::move(config));
     }
 #endif
 
-    // Helper wrappers for private methods (friend access)
+    // Helper wrappers for private methods (test peer)
     std::string CallFormatTimestamp(
         const std::chrono::system_clock::time_point& tp) {
         // FormatTimestamp is now in MasterSnapshotManager
-        if (service_->snapshot_manager_) {
-            return service_->snapshot_manager_->FormatTimestamp(tp);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            return MasterServiceTestPeer::SnapshotManager(*service_)
+                ->FormatTimestamp(tp);
         }
         // Fallback for tests without snapshot_manager_
         auto temp_manager = CreateTempSnapshotManager();
@@ -151,9 +160,9 @@ class SnapshotChildProcessTest : public ::testing::Test {
 
     void CallHandleChildExit(pid_t pid, int status,
                              const std::string& snapshot_id) {
-        if (service_->snapshot_manager_) {
-            service_->snapshot_manager_->HandleChildExit(pid, status,
-                                                         snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            MasterServiceTestPeer::SnapshotManager(*service_)->HandleChildExit(
+                pid, status, snapshot_id);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             temp_manager->HandleChildExit(pid, status, snapshot_id);
@@ -161,8 +170,9 @@ class SnapshotChildProcessTest : public ::testing::Test {
     }
 
     void CallHandleChildTimeout(pid_t pid, const std::string& snapshot_id) {
-        if (service_->snapshot_manager_) {
-            service_->snapshot_manager_->HandleChildTimeout(pid, snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            MasterServiceTestPeer::SnapshotManager(*service_)
+                ->HandleChildTimeout(pid, snapshot_id);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             temp_manager->HandleChildTimeout(pid, snapshot_id);
@@ -171,9 +181,9 @@ class SnapshotChildProcessTest : public ::testing::Test {
 
     void CallCleanupOldSnapshot(int keep_count,
                                 const std::string& snapshot_id) {
-        if (service_->snapshot_manager_) {
-            service_->snapshot_manager_->repository_->CleanupOldSnapshots(
-                keep_count, snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            MasterServiceTestPeer::SnapshotManager(*service_)
+                ->repository_->CleanupOldSnapshots(keep_count, snapshot_id);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             temp_manager->repository_->CleanupOldSnapshots(keep_count,
@@ -184,9 +194,10 @@ class SnapshotChildProcessTest : public ::testing::Test {
     tl::expected<void, SerializationError> CallUploadSnapshotPayloadFile(
         const std::vector<uint8_t>& data, const std::string& path,
         const std::string& local_filename, const std::string& snapshot_id) {
-        if (service_->snapshot_manager_) {
-            return service_->snapshot_manager_->repository_->UploadPayloadFile(
-                data, path, local_filename, snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            return MasterServiceTestPeer::SnapshotManager(*service_)
+                ->repository_->UploadPayloadFile(data, path, local_filename,
+                                                 snapshot_id);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             return temp_manager->repository_->UploadPayloadFile(
@@ -195,17 +206,18 @@ class SnapshotChildProcessTest : public ::testing::Test {
     }
 
     SnapshotObjectStore* GetSnapshotObjectStore() {
-        return service_->snapshot_object_store_.get();
+        return MasterServiceTestPeer::SnapshotObjectStore(*service_).get();
     }
 
     ha::SnapshotCatalogStore* GetSnapshotCatalogStore() {
-        return service_->snapshot_catalog_store_.get();
+        return MasterServiceTestPeer::SnapshotCatalogStore(*service_).get();
     }
 
     tl::expected<void, SerializationError> CallPersistState(
         const std::string& snapshot_id) {
-        if (service_->snapshot_manager_) {
-            return service_->snapshot_manager_->PersistState(snapshot_id);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            return MasterServiceTestPeer::SnapshotManager(*service_)
+                ->PersistState(snapshot_id);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             return temp_manager->PersistState(snapshot_id);
@@ -214,22 +226,19 @@ class SnapshotChildProcessTest : public ::testing::Test {
 
     tl::expected<void, SerializationError> CallPersistState(
         const ha::SnapshotDescriptor& descriptor) {
-        if (service_->snapshot_manager_) {
-            return service_->snapshot_manager_->PersistState(descriptor);
+        if (MasterServiceTestPeer::SnapshotManager(*service_)) {
+            return MasterServiceTestPeer::SnapshotManager(*service_)
+                ->PersistState(descriptor);
         } else {
             auto temp_manager = CreateTempSnapshotManager();
             return temp_manager->PersistState(descriptor);
         }
     }
 
-    bool GetUseSnapshotBackupDir() {
-        return service_->use_snapshot_backup_dir_;
-    }
-
     // Check if a key exists in raw metadata (regardless of replica status)
     bool KeyExistsInMetadata(MasterService* svc, const std::string& key) {
-        size_t shard_idx = svc->getShardIndex(key);
-        auto& shard = svc->metadata_shards_[shard_idx];
+        size_t shard_idx = MasterServiceTestPeer(*svc).getShardIndex(key);
+        auto& shard = MasterServiceTestPeer::MetadataShards(*svc)[shard_idx];
         SharedMutexLocker lock(&shard.mutex, shared_lock_t{});
         auto tenant_it = shard.tenants.find(TenantId::Default());
         return tenant_it != shard.tenants.end() &&
@@ -237,18 +246,40 @@ class SnapshotChildProcessTest : public ::testing::Test {
                    tenant_it->second.metadata.end();
     }
 
+    size_t SoftPinRegistrationCount(MasterService* svc) {
+        return MasterServiceTestPeer(*svc).SoftPinRegistrationCount();
+    }
+
+    std::optional<std::chrono::system_clock::time_point> GetSoftPinDeadline(
+        MasterService* svc, const std::string& key) {
+        const size_t shard_idx =
+            MasterServiceTestPeer(*svc).getShardIndex(TenantId::Default(), key);
+        MasterServiceTestPeer::MetadataShardAccessorRO shard(svc, shard_idx);
+        const auto tenant_it = shard->tenants.find(TenantId::Default());
+        if (tenant_it == shard->tenants.end()) {
+            return std::nullopt;
+        }
+        const auto metadata_it = tenant_it->second.metadata.find(key);
+        if (metadata_it == tenant_it->second.metadata.end()) {
+            return std::nullopt;
+        }
+        return metadata_it->second.GetCommittedSoftPinTimeout();
+    }
+
     uint32_t GetShardIndexForTest(const std::string& key) {
-        return static_cast<uint32_t>(service_->getShardIndex(key));
+        return static_cast<uint32_t>(
+            MasterServiceTestPeer(*service_).getShardIndex(key));
     }
 
     tl::expected<void, SerializationError> DeserializeMetadataForTest(
         const std::vector<uint8_t>& data) {
-        MasterService::MetadataSerializer serializer(service_.get());
+        MasterServiceTestPeer::MetadataSerializer serializer(service_.get());
         return serializer.Deserialize(data);
     }
 
     bool ObjectIsGroupedInMetadata(const std::string& key, size_t shard_idx) {
-        auto& shard = service_->metadata_shards_[shard_idx];
+        auto& shard =
+            MasterServiceTestPeer::MetadataShards(*service_)[shard_idx];
         SharedMutexLocker lock(&shard.mutex, shared_lock_t{});
         for (const auto& [tenant_id, tenant_state] : shard.tenants) {
             auto it = tenant_state.metadata.find(key);
@@ -261,10 +292,11 @@ class SnapshotChildProcessTest : public ::testing::Test {
 
     std::string FindGroupIdOnDifferentShard(MasterService* svc,
                                             const std::string& key) {
-        const size_t key_shard = svc->getShardIndex(key);
+        const size_t key_shard = MasterServiceTestPeer(*svc).getShardIndex(key);
         for (int i = 0; i < 1024; ++i) {
             std::string group_id = key + "_group_" + std::to_string(i);
-            if (svc->getShardIndex(group_id) != key_shard) {
+            if (MasterServiceTestPeer(*svc).getShardIndex(group_id) !=
+                key_shard) {
                 return group_id;
             }
         }
@@ -277,38 +309,34 @@ class SnapshotChildProcessTest : public ::testing::Test {
         EnsureSnapshotStores();
 
         MasterSnapshotManagerOptions options;
-        options.enable_snapshot = true;
         options.snapshot_interval_seconds =
-            service_->snapshot_interval_seconds_;
+            service_config_.snapshot_interval_seconds;
         options.snapshot_child_timeout_seconds =
-            service_->snapshot_child_timeout_seconds_;
-        options.snapshot_retention_count = service_->snapshot_retention_count_;
-        options.snapshot_backup_dir = service_->snapshot_backup_dir_;
-        options.use_snapshot_backup_dir = service_->use_snapshot_backup_dir_;
-        options.snapshot_catalog_store_type =
-            service_->snapshot_catalog_store_type_;
-        options.snapshot_catalog_store_connstring =
-            service_->snapshot_catalog_store_connstring_;
-        options.ha_backend_type = service_->ha_backend_type_;
-        options.ha_backend_connstring = service_->ha_backend_connstring_;
-        options.cluster_id = service_->cluster_id_;
-        options.enable_ha = service_->enable_ha_;
+            service_config_.snapshot_child_timeout_seconds;
+        options.snapshot_retention_count =
+            service_config_.snapshot_retention_count;
+        options.snapshot_backup_dir = service_config_.snapshot_backup_dir;
+        options.use_snapshot_backup_dir =
+            !service_config_.snapshot_backup_dir.empty();
 
         return std::make_unique<MasterSnapshotManager>(
-            service_.get(), options, service_->snapshot_mutex_,
-            service_->snapshot_object_store_.get(),
-            service_->snapshot_catalog_store_.get());
+            service_.get(), options,
+            MasterServiceTestPeer::SnapshotMutex(*service_),
+            MasterServiceTestPeer::SnapshotObjectStore(*service_).get(),
+            MasterServiceTestPeer::SnapshotCatalogStore(*service_).get());
     }
 
     void EnsureSnapshotStores() {
-        if (!service_->snapshot_object_store_) {
-            service_->snapshot_object_store_ = SnapshotObjectStore::Create(
-                SnapshotObjectStoreType::LOCAL_FILE);
+        if (!MasterServiceTestPeer::SnapshotObjectStore(*service_)) {
+            MasterServiceTestPeer::SnapshotObjectStore(*service_) =
+                SnapshotObjectStore::Create(
+                    SnapshotObjectStoreType::LOCAL_FILE);
         }
-        if (!service_->snapshot_catalog_store_ &&
-            service_->snapshot_object_store_) {
-            service_->snapshot_catalog_store_ =
-                service_->CreateSnapshotCatalogStore();
+        if (!MasterServiceTestPeer::SnapshotCatalogStore(*service_) &&
+            MasterServiceTestPeer::SnapshotObjectStore(*service_)) {
+            MasterServiceTestPeer::SnapshotCatalogStore(*service_) =
+                MasterServiceTestPeer(*service_).CreateSnapshotCatalogStore(
+                    service_config_);
         }
     }
 
@@ -598,7 +626,7 @@ TEST_F(SnapshotChildProcessTest, RestoreRebuildsGroupedObjectRouting) {
             .set_default_kv_lease_ttl(600000)
             .build();
     };
-    service_ = std::make_unique<MasterService>(make_config());
+    CreateService(make_config());
 
     Segment segment;
     segment.id = generate_uuid();
@@ -629,7 +657,7 @@ TEST_F(SnapshotChildProcessTest, RestoreRebuildsGroupedObjectRouting) {
         << "PersistState failed: " << persist_result.error().message;
 
     service_.reset();
-    service_ = std::make_unique<MasterService>(make_config());
+    CreateService(make_config());
 
     auto restored_replicas = service_->GetReplicaList(key, TenantId::Default());
     ASSERT_TRUE(restored_replicas.has_value())
@@ -652,7 +680,7 @@ TEST_F(SnapshotChildProcessTest, RestorePreservesObjectChecksum) {
             .set_default_kv_lease_ttl(600000)
             .build();
     };
-    service_ = std::make_unique<MasterService>(make_config());
+    CreateService(make_config());
 
     Segment segment;
     segment.id = generate_uuid();
@@ -681,7 +709,7 @@ TEST_F(SnapshotChildProcessTest, RestorePreservesObjectChecksum) {
         << "PersistState failed: " << persist_result.error().message;
 
     service_.reset();
-    service_ = std::make_unique<MasterService>(make_config());
+    CreateService(make_config());
 
     auto restored = service_->GetReplicaList(key, TenantId::Default());
     ASSERT_TRUE(restored.has_value());
@@ -843,7 +871,9 @@ TEST_F(SnapshotChildProcessTest,
 
     const std::string snapshot_id = "20240601_120000_789";
     CreateBatchEtcdHASnapshotService(cluster_id, etcd_endpoints, kViewVersion);
-    ASSERT_EQ(ErrorCode::OK, service_->SetBatchOpLogBackendForTesting(backend));
+    ASSERT_EQ(ErrorCode::OK,
+              MasterServiceTestPeer(*service_).SetBatchOpLogBackendForTesting(
+                  backend));
     auto persist_result = CallPersistState(snapshot_id);
     ASSERT_TRUE(persist_result.has_value())
         << "PersistState failed: " << persist_result.error().message;
@@ -922,7 +952,7 @@ TEST_F(SnapshotChildProcessTest, RestoreWithoutBackupDir_NoBackupFiles) {
     auto restore_service = std::make_unique<MasterService>(config);
 
     // Step 3: Verify NO backup directory was created
-    // With empty backup_dir, use_snapshot_backup_dir_ should be false
+    // With an empty backup_dir, no restore directory should be created.
     // and no restore directory should exist anywhere in tmp_dir()
     bool any_restore_dir_found = false;
     for (auto& entry : fs::recursive_directory_iterator(tmp_dir())) {
@@ -1070,7 +1100,7 @@ TEST_F(SnapshotChildProcessTest, RestoreCleansNonCompleteReplica) {
                       .set_snapshot_retention_count(3)
                       .set_snapshot_object_store_type("local")
                       .build();
-    service_ = std::make_unique<MasterService>(config);
+    CreateService(std::move(config));
 
     // Mount a segment
     Segment segment;
@@ -1145,7 +1175,7 @@ TEST_F(SnapshotChildProcessTest, RestoreCleansExpiredLease) {
                       .set_snapshot_object_store_type("local")
                       .set_default_kv_lease_ttl(600000)  // 10 min lease
                       .build();
-    service_ = std::make_unique<MasterService>(config);
+    CreateService(std::move(config));
 
     // Mount a segment
     Segment segment;
@@ -1159,7 +1189,8 @@ TEST_F(SnapshotChildProcessTest, RestoreCleansExpiredLease) {
     ASSERT_TRUE(mount_result.has_value()) << "MountSegment failed";
 
     // Add two complete objects via PutStart + PutEnd
-    // Note: PutEnd calls GrantLease(0, ...) so lease is immediately expired
+    // PutEnd only grants a zero-duration read lease, so it is immediately
+    // expired.
     std::string expired_key = "expired_lease_object";
     auto put_exp =
         service_->PutStart(client_id, expired_key, TenantId::Default(), {1024},
@@ -1181,9 +1212,27 @@ TEST_F(SnapshotChildProcessTest, RestoreCleansExpiredLease) {
                     .has_value())
         << "PutEnd normal failed";
 
+    const int64_t soft_pin_baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
+    std::string soft_pinned_key = "soft_pin_valid_lease_object";
+    ReplicateConfig soft_pin_config;
+    soft_pin_config.soft_pin_action = SoftPinAction::ENABLE;
+    soft_pin_config.soft_pin_ttl_ms = 60'000;
+    auto put_soft =
+        service_->PutStart(client_id, soft_pinned_key, TenantId::Default(),
+                           {1024}, soft_pin_config);
+    ASSERT_TRUE(put_soft.has_value()) << "PutStart soft pin failed";
+    ASSERT_TRUE(service_
+                    ->PutEnd(client_id, soft_pinned_key, TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value())
+        << "PutEnd soft pin failed";
+
     // ExistKey grants a fresh lease (now + 600s) to normal_key
     EXPECT_TRUE(
         service_->ExistKey(normal_key, TenantId::Default()).value_or(false));
+    EXPECT_TRUE(service_->ExistKey(soft_pinned_key, TenantId::Default())
+                    .value_or(false));
     // Do NOT call ExistKey on expired_key, its lease stays expired from PutEnd
 
     // Step 2: Persist state
@@ -1210,6 +1259,17 @@ TEST_F(SnapshotChildProcessTest, RestoreCleansExpiredLease) {
         << "Normal object with valid lease should survive restore";
     EXPECT_FALSE(KeyExistsInMetadata(restored_service.get(), expired_key))
         << "Lease-expired object should be cleaned during restore";
+    EXPECT_TRUE(restored_service->ExistKey(soft_pinned_key, TenantId::Default())
+                    .value_or(false))
+        << "Soft-pinned object with a valid read lease should restore as cache";
+    EXPECT_FALSE(
+        GetSoftPinDeadline(restored_service.get(), soft_pinned_key).has_value())
+        << "Snapshot restore must discard soft-pin state";
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              soft_pin_baseline)
+        << "Restored soft pins must not remain in the active gauge";
+    EXPECT_EQ(SoftPinRegistrationCount(restored_service.get()), 0u)
+        << "Restored soft pins must not remain in the deadline index";
 
     restored_service.reset();
 }
@@ -1228,7 +1288,7 @@ TEST_F(SnapshotChildProcessTest, PersistState_FailFast_StopsOnFirstError) {
             .set_snapshot_retention_count(3)
             .set_snapshot_object_store_type("local")
             .build();
-    service_ = std::make_unique<MasterService>(config);
+    CreateService(std::move(config));
 
     // Mount a segment to have some data to serialize
     Segment segment;
@@ -1296,7 +1356,7 @@ TEST_F(SnapshotChildProcessTest, UploadFail_WithBackupDir_SavesAllFiles) {
                       .set_snapshot_retention_count(3)
                       .set_snapshot_object_store_type("local")
                       .build();
-    service_ = std::make_unique<MasterService>(config);
+    CreateService(std::move(config));
 
     // Mount a segment to have some data to serialize
     Segment segment;
diff --git a/mooncake-store/tests/ha/snapshot/snapshot_test_utils.h b/mooncake-store/tests/ha/snapshot/snapshot_test_utils.h
index d6f0c28ef8..f9decf6bbd 100644
--- a/mooncake-store/tests/ha/snapshot/snapshot_test_utils.h
+++ b/mooncake-store/tests/ha/snapshot/snapshot_test_utils.h
@@ -3,6 +3,7 @@
 #include <cstdlib>
 #include <filesystem>
 #include <memory>
+#include <optional>
 #include <stdexcept>
 #include <string>
 #include <string_view>
@@ -21,7 +22,7 @@
 #include "segment.h"
 #include "serialize/serializer.h"
 #include "types.h"
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake::test {
 
@@ -141,7 +142,7 @@ inline void PackDiskReplica(
 inline std::vector<uint8_t> BuildSegmentsPayload() {
     SegmentManager segment_manager(BufferAllocatorType::OFFSET);
     SegmentSerializer serializer(&segment_manager);
-    auto serialized = serializer.Serialize();
+    auto serialized = serializer.Serialize(LocalSsdPersistedState{});
     if (!serialized) {
         throw std::runtime_error(serialized.error().message);
     }
@@ -176,7 +177,8 @@ inline std::vector<uint8_t> BuildMetadataPayloadWithClientIdString(
     uint64_t object_size = kDefaultTestObjectSize,
     uint64_t put_start_time_ms = kDefaultTestPutStartTimeMs,
     uint64_t lease_timeout_ms = kDefaultTestLeaseTimeoutMs,
-    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy) {
+    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy,
+    std::optional<uint64_t> soft_pin_deadline_ms = std::nullopt) {
     const bool include_data_type =
         format == SnapshotMetadataFormat::kDataTypeOnly ||
         format == SnapshotMetadataFormat::kDataTypeAndHardPinned ||
@@ -212,8 +214,8 @@ inline std::vector<uint8_t> BuildMetadataPayloadWithClientIdString(
     shard_packer.pack(put_start_time_ms);
     shard_packer.pack(object_size);
     shard_packer.pack(lease_timeout_ms);
-    shard_packer.pack(false);
-    shard_packer.pack(uint64_t{0});
+    shard_packer.pack(soft_pin_deadline_ms.has_value());
+    shard_packer.pack(soft_pin_deadline_ms.value_or(0));
     shard_packer.pack(kReplicaCount);
     if (include_data_type) {
         shard_packer.pack(static_cast<uint8_t>(ObjectDataType::TENSOR));
@@ -238,10 +240,11 @@ inline std::vector<uint8_t> BuildMetadataPayload(
     uint64_t object_size = kDefaultTestObjectSize,
     uint64_t put_start_time_ms = kDefaultTestPutStartTimeMs,
     uint64_t lease_timeout_ms = kDefaultTestLeaseTimeoutMs,
-    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy) {
+    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy,
+    std::optional<uint64_t> soft_pin_deadline_ms = std::nullopt) {
     return BuildMetadataPayloadWithClientIdString(
         UuidToString(client_id), object_key, disk_file_path, object_size,
-        put_start_time_ms, lease_timeout_ms, format);
+        put_start_time_ms, lease_timeout_ms, format, soft_pin_deadline_ms);
 }
 
 // Builds a metadata payload whose declared replica_count field is set to
@@ -361,12 +364,14 @@ inline tl::expected<void, std::string> PublishSnapshotPayload(
     std::string_view object_key = kDefaultTestObjectKey,
     std::string_view disk_file_path = kDefaultTestDiskFilePath,
     uint64_t object_size = kDefaultTestObjectSize,
-    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy) {
+    SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy,
+    std::optional<uint64_t> soft_pin_deadline_ms = std::nullopt) {
     return PublishSnapshotPayloadBytes(
         object_store, catalog_store, descriptor,
         BuildMetadataPayload(client_id, object_key, disk_file_path, object_size,
                              kDefaultTestPutStartTimeMs,
-                             kDefaultTestLeaseTimeoutMs, format));
+                             kDefaultTestLeaseTimeoutMs, format,
+                             soft_pin_deadline_ms));
 }
 
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha/snapshot/store_resource_snapshot_codec_test.cpp b/mooncake-store/tests/ha/snapshot/store_resource_snapshot_codec_test.cpp
new file mode 100644
index 0000000000..85d2eddf65
--- /dev/null
+++ b/mooncake-store/tests/ha/snapshot/store_resource_snapshot_codec_test.cpp
@@ -0,0 +1,881 @@
+#include "ha/snapshot/store_resource_snapshot_codec.h"
+
+#include <gtest/gtest.h>
+#include <msgpack.hpp>
+
+#include <algorithm>
+#include <functional>
+#include <limits>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "common/zstd_util.h"
+#include "ha/snapshot/local_ssd_codec.h"
+#include "master_metric_manager.h"
+#include "segment.h"
+#include "segment/pool.h"
+#include "segment/pool_read_access.h"
+#include "segment/pool_write_access.h"
+#include "segment/snapshot.h"
+#include "serialize/serializer.h"
+
+namespace mooncake::ha {
+namespace {
+
+constexpr size_t kRegionSize = 16U * 1024 * 1024;
+
+RegionDriverRegistry Drivers(bool enable_cxl = false) {
+    RegionDriverConfig config;
+    config.memory_allocator = BufferAllocatorType::OFFSET;
+    if (enable_cxl) {
+        config.cxl = CxlRegionDriverConfig{"cxl-test-path", kRegionSize};
+    }
+    auto drivers = CreateRegionDrivers(config);
+    EXPECT_TRUE(drivers.has_value());
+    return std::move(drivers.value());
+}
+
+Segment MakeSegment(size_t index, std::string name,
+                    std::string protocol = "tcp", std::string host = {}) {
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = std::move(name);
+    segment.base = 0x100000000ULL + index * 0x2000000ULL;
+    segment.size = kRegionSize;
+    segment.te_endpoint = segment.name + "-endpoint";
+    segment.protocol = std::move(protocol);
+    segment.host_id = std::move(host);
+    return segment;
+}
+
+void CommitUnmount(SegmentPool& pool, const Segment& segment,
+                   const UUID& client_id) {
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(segment.id, client_id);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(std::move(*transaction).Commit(access), ErrorCode::OK);
+    EXPECT_EQ(std::move(*transaction).Commit(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    EXPECT_EQ(std::move(*transaction).Rollback(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+tl::expected<std::vector<uint8_t>, SerializationError> CaptureAndEncode(
+    const SegmentPool& pool, const LocalSsdPersistedState& local_ssd) {
+    auto snapshot = pool.CaptureSnapshot();
+    if (!snapshot) {
+        return tl::make_unexpected(
+            SerializationError(snapshot.error(), "capture SegmentPool failed"));
+    }
+    return StoreResourceSnapshotCodec::Encode(*snapshot, local_ssd);
+}
+
+tl::expected<LocalSsdPersistedState, SerializationError> DecodeAndRestore(
+    SegmentPool& pool, const std::vector<uint8_t>& bytes,
+    bool account_capacity) {
+    auto decoded = StoreResourceSnapshotCodec::Decode(bytes);
+    if (!decoded) return tl::make_unexpected(decoded.error());
+    auto restored = pool.RestoreSnapshot(std::move(decoded->segment_pool),
+                                         account_capacity);
+    if (!restored)
+        return tl::make_unexpected(
+            SerializationError(restored.error(), "restore SegmentPool failed"));
+    return std::move(decoded->local_ssd);
+}
+
+// Mutate the unpacked wire payload rather than duplicating the codec in tests.
+std::vector<uint8_t> RewriteSnapshot(
+    const std::vector<uint8_t>& snapshot,
+    const std::function<void(msgpack::object&, msgpack::zone&)>& rewrite) {
+    const auto bytes = zstd_decompress(snapshot);
+    auto unpacked = msgpack::unpack(reinterpret_cast<const char*>(bytes.data()),
+                                    bytes.size());
+    auto root = unpacked.get();
+    rewrite(root, *unpacked.zone());
+
+    msgpack::sbuffer buffer;
+    msgpack::pack(buffer, root);
+    return zstd_compress(reinterpret_cast<const uint8_t*>(buffer.data()),
+                         buffer.size(), 3);
+}
+
+msgpack::object& SnapshotField(msgpack::object& root, std::string_view name) {
+    for (uint32_t i = 0; i < root.via.map.size; ++i) {
+        auto& item = root.via.map.ptr[i];
+        if (item.key.as<std::string>() == name) {
+            return item.val;
+        }
+    }
+
+    throw std::runtime_error("missing snapshot field");
+}
+
+std::string PackLocalSsd(const LocalSsdPersistedState& state) {
+    msgpack::sbuffer buffer;
+    MsgpackPacker packer(&buffer);
+    EXPECT_TRUE(LocalSsdCodec::Encode(state, packer).has_value());
+    return {buffer.data(), buffer.size()};
+}
+
+std::vector<uint8_t> ReplaceSnapshotActiveNames(
+    const std::vector<uint8_t>& snapshot,
+    const std::vector<std::string>& active_names) {
+    return RewriteSnapshot(snapshot, [&](auto& root, auto& zone) {
+        SnapshotField(root, "an") = msgpack::object(active_names, zone);
+    });
+}
+
+std::vector<uint8_t> ReplaceSnapshotAllocatorType(
+    const std::vector<uint8_t>& snapshot, uint64_t allocator_type) {
+    return RewriteSnapshot(snapshot, [&](auto& root, auto&) {
+        SnapshotField(root, "ma") = msgpack::object(allocator_type);
+    });
+}
+
+}  // namespace
+
+TEST(StoreResourceSnapshotCodecTest,
+     CapturedSnapshotOutlivesPoolAndPreservesOriginalLayout) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline_used = metrics.get_allocated_mem_size();
+    const auto baseline_capacity = metrics.get_total_mem_capacity();
+    const auto segment = MakeSegment(0, "detached-snapshot", "tcp", "host-a");
+    const UUID client = generate_uuid();
+    std::optional<SegmentPoolSnapshot> snapshot;
+    std::vector<uint8_t> original_bytes;
+    uintptr_t first_address = 0;
+    uintptr_t last_address = 0;
+    {
+        SegmentPool pool(Drivers());
+        ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, client),
+                  ErrorCode::OK);
+        auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+        auto first = allocator->allocate(4096);
+        auto hole = allocator->allocate(4096);
+        auto last = allocator->allocate(4096);
+        ASSERT_NE(first, nullptr);
+        ASSERT_NE(hole, nullptr);
+        ASSERT_NE(last, nullptr);
+        first_address = reinterpret_cast<uintptr_t>(first->data());
+        last_address = reinterpret_cast<uintptr_t>(last->data());
+        hole.reset();
+        const auto used = metrics.get_allocated_mem_size();
+        auto captured = pool.CaptureSnapshot();
+        ASSERT_TRUE(captured.has_value());
+        snapshot.emplace(std::move(*captured));
+        EXPECT_EQ(metrics.get_allocated_mem_size(), used);
+        auto encoded = StoreResourceSnapshotCodec::Encode(*snapshot, {});
+        ASSERT_TRUE(encoded.has_value());
+        original_bytes = std::move(*encoded);
+
+        // Change both allocation bins/nodes and catalog/placement after
+        // capture.
+        first.reset();
+        last.reset();
+        auto all = allocator->allocate(kRegionSize);
+        ASSERT_NE(all, nullptr);
+        ASSERT_EQ(pool.AcquireWriteAccess().SetSegmentStatusByName(
+                      segment.name, SegmentStatus::DRAINED),
+                  ErrorCode::OK);
+        pool.AcquireWriteAccess().Clear();
+    }
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline_used);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), baseline_capacity);
+    auto encoded = StoreResourceSnapshotCodec::Encode(*snapshot, {});
+    ASSERT_TRUE(encoded.has_value());
+    EXPECT_EQ(*encoded, original_bytes);
+    snapshot.reset();
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline_used);
+
+    SegmentPool restored(Drivers());
+    ASSERT_TRUE(DecodeAndRestore(restored, *encoded, false).has_value());
+    EXPECT_EQ(restored.GetMemoryUsage().used_bytes, 8192U);
+    auto access = restored.AcquireReadAccess();
+    const auto* mounted = access.Catalog().Find(segment.id);
+    ASSERT_NE(mounted, nullptr);
+    EXPECT_EQ(mounted->status, SegmentStatus::OK);
+    EXPECT_EQ(mounted->client_id, client);
+    EXPECT_EQ(mounted->segment.host_id, segment.host_id);
+    EXPECT_TRUE(access.Placement().Contains(segment.name,
+                                            AllocationCandidateKind::NATIVE));
+    auto next = access.GetAllocator(segment.id)->allocate(4096);
+    ASSERT_NE(next, nullptr);
+    EXPECT_NE(reinterpret_cast<uintptr_t>(next->data()), first_address);
+    EXPECT_NE(reinterpret_cast<uintptr_t>(next->data()), last_address);
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     DecodeReturnsDetachedStateWithoutMetricSideEffects) {
+    SegmentPool source(Drivers());
+    const auto segment = MakeSegment(0, "decode-detached");
+    const auto client = generate_uuid();
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    auto allocator = source.AcquireReadAccess().GetAllocator(segment.id);
+    auto buffer = allocator->allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+    auto encoded = CaptureAndEncode(source, {});
+    ASSERT_TRUE(encoded);
+    auto& metrics = MasterMetricManager::instance();
+    const auto used = metrics.get_allocated_mem_size();
+    const auto capacity = metrics.get_total_mem_capacity();
+    {
+        auto decoded = StoreResourceSnapshotCodec::Decode(*encoded);
+        ASSERT_TRUE(decoded);
+        ASSERT_EQ(decoded->segment_pool.regions.size(), 1U);
+        EXPECT_EQ(decoded->segment_pool.regions.front().allocator.used_bytes,
+                  4096U);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), used);
+        EXPECT_EQ(metrics.get_total_mem_capacity(), capacity);
+    }
+    EXPECT_EQ(metrics.get_allocated_mem_size(), used);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), capacity);
+}
+
+TEST(StoreResourceSnapshotCodecTest, SnapshotDecodeReencodePreservesBytes) {
+    SegmentPool pool(Drivers());
+    const UUID client{1, 1};
+    auto first = MakeSegment(0, "roundtrip-z");
+    auto second = MakeSegment(1, "roundtrip-a");
+    auto inactive = MakeSegment(2, "roundtrip-inactive");
+    // ID order differs from both mount order and active-name order.
+    first.id = UUID{0, 3};
+    second.id = UUID{0, 1};
+    inactive.id = UUID{0, 2};
+    {
+        auto access = pool.AcquireWriteAccess();
+        for (const auto* segment : {&first, &second, &inactive}) {
+            ASSERT_EQ(access.MountSegment(*segment, client), ErrorCode::OK);
+        }
+        ASSERT_EQ(access.SetSegmentStatusByName(inactive.name,
+                                                SegmentStatus::DRAINED),
+                  ErrorCode::OK);
+    }
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    for (bool reverse_region_order : {false, true}) {
+        SCOPED_TRACE(reverse_region_order);
+        auto input = *encoded;
+        if (reverse_region_order) {
+            input = RewriteSnapshot(*encoded, [](auto& root, auto&) {
+                auto& regions = SnapshotField(root, "ms").via.map;
+                std::reverse(regions.ptr, regions.ptr + regions.size);
+            });
+        }
+        auto decoded = StoreResourceSnapshotCodec::Decode(input);
+        ASSERT_TRUE(decoded.has_value()) << decoded.error().message;
+        const auto& snapshot = decoded->segment_pool;
+        ASSERT_EQ(snapshot.regions.size(), 3U);
+        EXPECT_EQ(snapshot.regions[0].mounted.segment.id, second.id);
+        EXPECT_EQ(snapshot.regions[1].mounted.segment.id, inactive.id);
+        EXPECT_EQ(snapshot.regions[2].mounted.segment.id, first.id);
+        EXPECT_EQ(snapshot.active_names,
+                  (std::vector<std::string>{first.name, second.name}));
+
+        auto reencoded =
+            StoreResourceSnapshotCodec::Encode(snapshot, decoded->local_ssd);
+        ASSERT_TRUE(reencoded.has_value()) << reencoded.error().message;
+        EXPECT_EQ(*reencoded, *encoded);
+    }
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     OutOfRangeSnapshotAllocatorTypeReturnsError) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "snapshot-invalid-allocator-type");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(pool, LocalSsdPersistedState{});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    for (const uint64_t value :
+         {uint64_t{std::numeric_limits<int32_t>::max()} + 1,
+          std::numeric_limits<uint64_t>::max()}) {
+        auto corrupted = ReplaceSnapshotAllocatorType(*encoded, value);
+        ASSERT_NO_THROW({
+            auto result = DecodeAndRestore(pool, corrupted, false);
+            ASSERT_FALSE(result.has_value());
+            EXPECT_EQ(result.error().code, ErrorCode::DESERIALIZE_FAIL);
+        });
+        EXPECT_NE(pool.AcquireReadAccess().Catalog().Find(segment.id), nullptr);
+    }
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     InvalidSnapshotDoesNotReplacePublishedPool) {
+    SegmentPool source(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "snapshot-active");
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(source, LocalSsdPersistedState{});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    SegmentPool restored(Drivers());
+    auto stale = MakeSegment(1, "published");
+    ASSERT_EQ(restored.AcquireWriteAccess().MountSegment(stale, client),
+              ErrorCode::OK);
+    auto corrupted = ReplaceSnapshotActiveNames(*encoded, {});
+    auto result = DecodeAndRestore(restored, corrupted, false);
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error().code, ErrorCode::DESERIALIZE_FAIL);
+
+    {
+        auto view = restored.AcquireReadAccess();
+        EXPECT_NE(view.Catalog().Find(stale.id), nullptr);
+        EXPECT_EQ(view.Catalog().Find(segment.id), nullptr);
+    }
+
+    CommitUnmount(source, segment, client);
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     SnapshotInteroperatesWithLegacySerializer) {
+    SegmentPool source(Drivers());
+    const UUID client = generate_uuid();
+    // Preserve insertion order, not lexicographic name order.
+    auto first = MakeSegment(0, "compat-z", "tcp", "host-a");
+    auto second = MakeSegment(1, "compat-a", "tcp", "host-b");
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(first, client),
+              ErrorCode::OK);
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(second, client),
+              ErrorCode::OK);
+
+    LocalSsdPersistedState ssd;
+    ssd[client] = LocalSsdPersistedClient{
+        .enable_offloading = true,
+        .total_capacity_bytes = 12345,
+        .pending_offloads = {
+            {"tenant/key",
+             OffloadTaskItem{
+                 .tenant_id = "tenant", .key = "key", .size = 4096}}}};
+    auto encoded = CaptureAndEncode(source, ssd);
+    ASSERT_TRUE(encoded.has_value());
+
+    SegmentManager legacy(BufferAllocatorType::OFFSET);
+    SegmentSerializer serializer(&legacy);
+    auto old_decoded = serializer.Deserialize(*encoded);
+    ASSERT_TRUE(old_decoded.has_value()) << old_decoded.error().message;
+    EXPECT_EQ(PackLocalSsd(*old_decoded), PackLocalSsd(ssd));
+
+    MountedSegment mounted;
+    ASSERT_EQ(legacy.getView().GetMountedSegment(first.id, mounted),
+              ErrorCode::OK);
+    EXPECT_EQ(mounted.segment.host_id, first.host_id);
+
+    auto old_encoded = serializer.Serialize(*old_decoded);
+    ASSERT_TRUE(old_encoded.has_value());
+
+    SegmentPool restored(Drivers());
+    auto decoded = DecodeAndRestore(restored, *old_encoded, false);
+    ASSERT_TRUE(decoded.has_value()) << decoded.error().message;
+    EXPECT_EQ(PackLocalSsd(*decoded), PackLocalSsd(ssd));
+    {
+        auto access = restored.AcquireReadAccess();
+        ASSERT_EQ(access.Catalog().Regions().size(), 2U);
+        ASSERT_NE(access.Catalog().Find(first.id), nullptr);
+        EXPECT_EQ(access.Catalog().Find(first.id)->client_id, client);
+        std::vector<std::string> names;
+        access.Placement().GetActiveSegmentNames(
+            AllocationCandidateKind::NATIVE, names);
+        EXPECT_EQ(names, (std::vector<std::string>{first.name, second.name}));
+    }
+
+    // Historical MountedSegment arrays had no host_id, and ld was optional.
+    auto historical = RewriteSnapshot(*old_encoded, [](auto& root, auto&) {
+        auto& regions = SnapshotField(root, "ms");
+        for (uint32_t i = 0; i < regions.via.map.size; ++i) {
+            regions.via.map.ptr[i].val.via.array.size = 8;
+        }
+
+        for (uint32_t i = 0; i < root.via.map.size; ++i) {
+            if (root.via.map.ptr[i].key.template as<std::string>() == "ld") {
+                root.via.map.ptr[i] = root.via.map.ptr[root.via.map.size - 1];
+                --root.via.map.size;
+                break;
+            }
+        }
+    });
+    decoded = DecodeAndRestore(restored, historical, false);
+    ASSERT_TRUE(decoded.has_value());
+    EXPECT_TRUE(decoded->empty());
+    EXPECT_TRUE(restored.AcquireReadAccess()
+                    .Catalog()
+                    .Find(first.id)
+                    ->segment.host_id.empty());
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     MalformedSnapshotsPreservePublishedResourcesAndMetrics) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    const auto segment = MakeSegment(0, "snapshot-atomic");
+    const auto other = MakeSegment(1, "snapshot-atomic-other");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(other, client),
+              ErrorCode::OK);
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto live = allocator->allocate(4096);
+    ASSERT_NE(live, nullptr);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value());
+    auto& metrics = MasterMetricManager::instance();
+    const auto used = metrics.get_allocated_mem_size();
+    const auto capacity = metrics.get_total_mem_capacity();
+
+    using Rewrite = std::function<void(msgpack::object&, msgpack::zone&)>;
+    const std::vector<std::pair<std::string, Rewrite>> cases{
+        {"missing owner",
+         [](auto& root, auto&) { SnapshotField(root, "cs").via.map.size = 0; }},
+        {"duplicate ownership",
+         [](auto& root, auto&) {
+             auto& ids = SnapshotField(root, "cs").via.map.ptr[0].val;
+             ids.via.array.ptr[1] = ids.via.array.ptr[0];
+         }},
+        {"unknown owned region",
+         [](auto& root, auto& zone) {
+             SnapshotField(root, "cs").via.map.ptr[0].val.via.array.ptr[0] =
+                 msgpack::object(UuidToString(UUID{99, 99}), zone);
+         }},
+        {"duplicate region",
+         [](auto& root, auto&) {
+             auto& regions = SnapshotField(root, "ms");
+             regions.via.map.ptr[1] = regions.via.map.ptr[0];
+         }},
+        {"invalid status",
+         [](auto& root, auto&) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[5] =
+                 msgpack::object(99);
+         }},
+        {"mismatched base",
+         [](auto& root, auto&) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[2] =
+                 msgpack::object(uint64_t{1});
+         }},
+        {"mismatched capacity",
+         [](auto& root, auto&) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[3] =
+                 msgpack::object(uint64_t{1});
+         }},
+        {"mismatched name",
+         [](auto& root, auto& zone) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[1] =
+                 msgpack::object(std::string("wrong"), zone);
+         }},
+        {"mismatched endpoint",
+         [](auto& root, auto& zone) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[4] =
+                 msgpack::object(std::string("wrong"), zone);
+         }},
+        {"broken allocator",
+         [](auto& root, auto&) {
+             SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[7] =
+                 msgpack::object();
+         }},
+        {"usage exceeds capacity",
+         [](auto& root, auto&) {
+             // Mirror the new usage onto the inner allocated_size so the
+             // outer/inner consistency check passes and the bound itself is
+             // exercised.
+             auto& allocator =
+                 SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[7];
+             auto usage = msgpack::object(uint64_t{kRegionSize + 1});
+             allocator.via.array.ptr[3] = usage;
+             allocator.via.array.ptr[5].via.array.ptr[3] = usage;
+         }},
+        {"usage overflows metrics",
+         [](auto& root, auto&) {
+             auto& allocator =
+                 SnapshotField(root, "ms").via.map.ptr[1].val.via.array.ptr[7];
+             auto usage = msgpack::object(std::numeric_limits<uint64_t>::max());
+             allocator.via.array.ptr[3] = usage;
+             allocator.via.array.ptr[5].via.array.ptr[3] = usage;
+         }},
+        {"second adoption fails",
+         [&](auto& root, auto& zone) {
+             // A zero UUID passes payload consistency checks but is rejected by
+             // the memory driver. The first active region has already staged.
+             const auto zero = msgpack::object(UuidToString(UUID{0, 0}), zone);
+             auto& regions = SnapshotField(root, "ms");
+             for (uint32_t i = 0; i < regions.via.map.size; ++i) {
+                 auto& item = regions.via.map.ptr[i];
+                 if (item.key.template as<std::string>() ==
+                     UuidToString(other.id)) {
+                     item.key = zero;
+                     item.val.via.array.ptr[0] = zero;
+                 }
+             }
+             auto& ids = SnapshotField(root, "cs").via.map.ptr[0].val;
+             for (uint32_t i = 0; i < ids.via.array.size; ++i) {
+                 if (ids.via.array.ptr[i].template as<std::string>() ==
+                     UuidToString(other.id)) {
+                     ids.via.array.ptr[i] = zero;
+                 }
+             }
+         }},
+        {"invalid local ssd",
+         [](auto& root, auto&) {
+             SnapshotField(root, "ld") = msgpack::object(42);
+         }},
+    };
+
+    for (const auto& [name, rewrite] : cases) {
+        SCOPED_TRACE(name);
+        auto corrupted = RewriteSnapshot(*encoded, rewrite);
+        auto result = DecodeAndRestore(pool, corrupted, true);
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error().code, name == "second adoption fails"
+                                           ? ErrorCode::INVALID_PARAMS
+                                           : ErrorCode::DESERIALIZE_FAIL);
+        EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), allocator);
+
+        if (name == "second adoption fails") {
+            EXPECT_EQ(result.error().message, "restore SegmentPool failed");
+        } else if (name == "usage exceeds capacity" ||
+                   name == "usage overflows metrics") {
+            // Decode propagates the detailed reason from the snapshot.
+            EXPECT_NE(result.error().message.find("invalid usage"),
+                      std::string::npos)
+                << result.error().message;
+        }
+
+        EXPECT_EQ(pool.AcquireReadAccess().Catalog().Regions().size(), 2U);
+        EXPECT_TRUE(pool.AcquireReadAccess().Placement().Contains(
+            segment.name, AllocationCandidateKind::NATIVE));
+        EXPECT_EQ(pool.GetMemoryUsage().used_bytes, 4096U);
+        EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, 2 * kRegionSize);
+        EXPECT_EQ(metrics.get_allocated_mem_size(), used);
+        EXPECT_EQ(metrics.get_total_mem_capacity(), capacity);
+        EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 4096);
+    }
+}
+
+TEST(StoreResourceSnapshotCodecTest,
+     SnapshotRejectsUnsupportedDriversAndCorruptContainers) {
+    RegionDriverConfig config;
+    config.memory_allocator = BufferAllocatorType::CACHELIB;
+    auto drivers = CreateRegionDrivers(config);
+    ASSERT_TRUE(drivers.has_value());
+    SegmentPool unsupported(std::move(*drivers));
+    auto encoded = CaptureAndEncode(unsupported, {});
+    ASSERT_FALSE(encoded.has_value());
+    EXPECT_EQ(encoded.error().code, ErrorCode::SERIALIZE_UNSUPPORTED);
+
+    SegmentPool cxl(Drivers(true));
+    ASSERT_EQ(cxl.AcquireWriteAccess().MountSegment(
+                  MakeSegment(0, "snapshot-cxl", "cxl"), generate_uuid()),
+              ErrorCode::OK);
+    encoded = CaptureAndEncode(cxl, {});
+    ASSERT_FALSE(encoded.has_value());
+    EXPECT_EQ(encoded.error().code, ErrorCode::SERIALIZE_UNSUPPORTED);
+
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(1, "snapshot-container");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+
+    // Invalid zstd, invalid MessagePack, and a valid non-map root.
+    const uint8_t invalid_msgpack = 0xc1;
+    const uint8_t array = 0x90;
+    const std::vector<std::vector<uint8_t>> corrupt{
+        {},
+        {1, 2, 3},
+        zstd_compress(&invalid_msgpack, 1, 3),
+        zstd_compress(&array, 1, 3)};
+    for (const auto& bytes : corrupt) {
+        auto decoded = DecodeAndRestore(pool, bytes, false);
+        ASSERT_FALSE(decoded.has_value());
+        EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+        EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), allocator);
+    }
+}
+
+// Capacities from the payload drive node storage allocation, so they must be
+// bounded and validated before the allocator is materialized.
+TEST(StoreResourceSnapshotCodecTest, CorruptAllocatorCapacityIsRejected) {
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-capacity");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value());
+
+    // Element 1 of the __Allocator payload is current_capacity, element 2 is
+    // max_capacity and element 9 is freeOffset.
+    const std::vector<std::pair<uint64_t, uint64_t>> corruptions{
+        {2, uint64_t{offset_allocator::OffsetAllocatorSnapshot::kMaxNodes} + 1},
+        {2, std::numeric_limits<uint32_t>::max()},
+        {1, std::numeric_limits<uint32_t>::max()},
+        {9, std::numeric_limits<uint32_t>::max()},
+    };
+    for (const auto& [element, value] : corruptions) {
+        SCOPED_TRACE(element);
+        auto corrupted = RewriteSnapshot(*encoded, [&](auto& root, auto&) {
+            // region[7] = OffsetBufferAllocator, [5] = OffsetAllocator, [5] =
+            // __Allocator.
+            auto& region = SnapshotField(root, "ms").via.map.ptr[0].val;
+            auto& allocator = region.via.array.ptr[7];
+            auto& offset_allocator = allocator.via.array.ptr[5];
+            auto& layout = offset_allocator.via.array.ptr[5];
+            layout.via.array.ptr[element] = msgpack::object(value);
+        });
+        auto decoded = StoreResourceSnapshotCodec::Decode(corrupted);
+        ASSERT_FALSE(decoded.has_value());
+        EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+        EXPECT_NE(decoded.error().message.find("capacity"), std::string::npos);
+        EXPECT_NE(pool.AcquireReadAccess().Catalog().Find(segment.id), nullptr);
+    }
+}
+
+// A detached snapshot of a multi-gigabyte segment is pure metadata: encoding,
+// decoding and restoring it must never mount or touch the described memory.
+TEST(StoreResourceSnapshotCodecTest,
+     LargeSegmentSnapshotRoundTripsWithoutPhysicalMemory) {
+    constexpr uint64_t kLargeBase = 0x200000000ULL;
+    constexpr size_t kLargeCapacity = 64ULL * 1024 * 1024 * 1024;
+    constexpr size_t kAllocation = 4096;
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline_used = metrics.get_allocated_mem_size();
+    const auto baseline_capacity = metrics.get_total_mem_capacity();
+
+    // Two live metadata nodes describe the whole 64GiB region: one 4KiB
+    // allocation and the free remainder. Use the real host-memory node ceiling
+    // (64Mi), not a small test ceiling: the former 16Mi limit must fail this
+    // round trip. reserve() is lazy; nothing is mapped at kLargeBase.
+    auto source = offset_allocator::OffsetAllocator::create(
+        kLargeBase, kLargeCapacity, /*init_capacity=*/2,
+        offset_allocator::OffsetAllocatorSnapshot::kMaxNodes);
+    ASSERT_NE(source, nullptr);
+    auto allocation = source->allocate(kAllocation);
+    ASSERT_TRUE(allocation.has_value());
+
+    auto segment = MakeSegment(3, "detached-large");
+    segment.base = kLargeBase;
+    segment.size = kLargeCapacity;
+    MountedRegion mounted;
+    mounted.segment = segment;
+    mounted.client_id = generate_uuid();
+    mounted.status = SegmentStatus::OK;
+
+    SegmentPoolSnapshot snapshot;
+    snapshot.active_names = {segment.name};
+    snapshot.regions.push_back(RegionSnapshot{
+        .mounted = mounted,
+        .allocator =
+            OffsetBufferAllocatorSnapshot{
+                .segment_name = segment.name,
+                .base = kLargeBase,
+                .capacity = kLargeCapacity,
+                .used_bytes = kAllocation,
+                .transport_endpoint = segment.te_endpoint,
+                .allocation_state = source->CaptureSnapshot(),
+            },
+    });
+    auto valid = snapshot.regions.front().allocator.Validate();
+    ASSERT_TRUE(valid.has_value()) << valid.error();
+
+    auto encoded = StoreResourceSnapshotCodec::Encode(snapshot, {});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+    auto decoded = StoreResourceSnapshotCodec::Decode(*encoded);
+    ASSERT_TRUE(decoded.has_value()) << decoded.error().message;
+    ASSERT_EQ(decoded->segment_pool.regions.size(), 1U);
+    auto& state = decoded->segment_pool.regions.front().allocator;
+    EXPECT_EQ(state.capacity, kLargeCapacity);
+    EXPECT_EQ(state.used_bytes, kAllocation);
+    EXPECT_EQ(state.allocation_state.allocated_num, 1U);
+
+    auto restored = OffsetBufferAllocator::Restore(std::move(state));
+    ASSERT_TRUE(restored.has_value());
+    auto allocator = std::move(*restored);
+    EXPECT_EQ(allocator->capacity(), kLargeCapacity);
+    EXPECT_EQ(allocator->size(), kAllocation);
+    EXPECT_EQ(allocator->base(), kLargeBase);
+    EXPECT_EQ(allocator->getSegmentName(), segment.name);
+    // The free remainder kept its size and unit multiplier across the round
+    // trip, which is only possible if the persisted nodes were restored.
+    EXPECT_EQ(allocator->getLargestFreeRegion(),
+              source->storageReport().largestFreeRegion);
+
+    allocator.reset();
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline_used);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), baseline_capacity);
+}
+
+// A node payload whose zstd frame header declares far more than the expected
+// node bytes must be rejected before the decompression buffer is allocated.
+TEST(StoreResourceSnapshotCodecTest,
+     OversizedNodeFrameIsRejectedBeforeAllocation) {
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-frame-header");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    // Minimal zstd frame header: magic, a descriptor selecting the 8-byte
+    // Frame_Content_Size field in single-segment mode, then 1TiB. No content
+    // follows, so only the declared size can be examined.
+    constexpr uint64_t kDeclaredBytes = 1ULL << 40;
+    std::vector<uint8_t> frame{0x28, 0xB5, 0x2F, 0xFD, 0xE0};
+    for (uint32_t shift = 0; shift < 64; shift += 8) {
+        frame.push_back(static_cast<uint8_t>(kDeclaredBytes >> shift));
+    }
+
+    // Element 7 of the __Allocator payload is the node data and element 8 the
+    // free-node data.
+    for (const uint32_t element : {7U, 8U}) {
+        SCOPED_TRACE(element);
+        auto corrupted = RewriteSnapshot(*encoded, [&](auto& root, auto& zone) {
+            // region[7] = OffsetBufferAllocator, [5] = OffsetAllocator, [5] =
+            // __Allocator.
+            auto& layout = SnapshotField(root, "ms")
+                               .via.map.ptr[0]
+                               .val.via.array.ptr[7]
+                               .via.array.ptr[5]
+                               .via.array.ptr[5];
+            layout.via.array.ptr[element] = msgpack::object(
+                msgpack::type::raw_ref(
+                    reinterpret_cast<const char*>(frame.data()), frame.size()),
+                zone);
+        });
+        auto decoded = StoreResourceSnapshotCodec::Decode(corrupted);
+        ASSERT_FALSE(decoded.has_value());
+        EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+        EXPECT_NE(decoded.error().message.find("exceeds maximum allowed"),
+                  std::string::npos)
+            << decoded.error().message;
+    }
+}
+
+// The inner allocator counters and unit multiplier must describe the inner
+// layout, and Decode reports the specific mismatch instead of a generic
+// rejection.
+TEST(StoreResourceSnapshotCodecTest, CorruptAllocatorInternalsAreRejected) {
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-internals");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto buffer = allocator->allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+    const auto baseline_used =
+        MasterMetricManager::instance().get_allocated_mem_size();
+
+    struct Corruption {
+        const char* name;
+        // OffsetAllocator element: 1 = multiplier_bits, 3 = allocated_size,
+        // 4 = allocated_num.
+        uint32_t element;
+        uint64_t value;
+        const char* reason;
+        // allocate() records the requested bytes in the outer usage too, so an
+        // altered allocated_size has to be mirrored to reach the inner check.
+        bool mirror_usage;
+    };
+    const std::vector<Corruption> corruptions{
+        {"allocated_size smaller than the used nodes", 3, 0, "allocated_size",
+         true},
+        {"allocated_num mismatch", 4, 0, "allocated_num", false},
+        {"multiplier_bits beyond the shift range", 1, 64, "multiplier_bits",
+         false},
+    };
+    for (const auto& corruption : corruptions) {
+        SCOPED_TRACE(corruption.name);
+        auto corrupted = RewriteSnapshot(*encoded, [&](auto& root, auto&) {
+            // region[7] = OffsetBufferAllocator, [5] = OffsetAllocator; element
+            // 3 of the OffsetBufferAllocator is the outer used_bytes.
+            auto& allocator_field =
+                SnapshotField(root, "ms").via.map.ptr[0].val.via.array.ptr[7];
+            auto& state = allocator_field.via.array.ptr[5];
+            state.via.array.ptr[corruption.element] =
+                msgpack::object(corruption.value);
+            if (corruption.mirror_usage) {
+                allocator_field.via.array.ptr[3] =
+                    msgpack::object(corruption.value);
+            }
+        });
+        auto decoded = StoreResourceSnapshotCodec::Decode(corrupted);
+        ASSERT_FALSE(decoded.has_value());
+        EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+        EXPECT_NE(decoded.error().message.find(corruption.reason),
+                  std::string::npos)
+            << decoded.error().message;
+    }
+
+    // Decoding is pure: the published allocator and the metrics are unchanged.
+    EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), allocator);
+    EXPECT_EQ(MasterMetricManager::instance().get_allocated_mem_size(),
+              baseline_used);
+}
+
+// The OffsetAllocator wire deserializer installs through the snapshot factory,
+// so a rejected snapshot reports the specific reason instead of a generic
+// rejection.
+TEST(StoreResourceSnapshotCodecTest,
+     LegacyAllocatorDeserializeReportsDetailedReason) {
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-legacy-reason");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto buffer = allocator->allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    auto corrupted = RewriteSnapshot(*encoded, [](auto& root, auto&) {
+        // Element 4 of the OffsetAllocator array is allocated_num; it cannot
+        // exceed the single used node.
+        auto& state = SnapshotField(root, "ms")
+                          .via.map.ptr[0]
+                          .val.via.array.ptr[7]
+                          .via.array.ptr[5];
+        state.via.array.ptr[4] = msgpack::object(uint64_t{2});
+    });
+    const auto bytes = zstd_decompress(corrupted);
+    auto unpacked = msgpack::unpack(reinterpret_cast<const char*>(bytes.data()),
+                                    bytes.size());
+    auto root = unpacked.get();
+    auto& offset_allocator_object = SnapshotField(root, "ms")
+                                        .via.map.ptr[0]
+                                        .val.via.array.ptr[7]
+                                        .via.array.ptr[5];
+    auto decoded = Serializer<offset_allocator::OffsetAllocator>::deserialize(
+        offset_allocator_object);
+    ASSERT_FALSE(decoded.has_value());
+    EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+    EXPECT_NE(decoded.error().message.find("allocated_num"), std::string::npos)
+        << decoded.error().message;
+
+    // Conversion failures must use the same expected-based error boundary,
+    // rather than leaking msgpack exceptions from the legacy entry point.
+    offset_allocator_object.via.array.ptr[4] = msgpack::object();
+    decoded = Serializer<offset_allocator::OffsetAllocator>::deserialize(
+        offset_allocator_object);
+    ASSERT_FALSE(decoded.has_value());
+    EXPECT_EQ(decoded.error().code, ErrorCode::DESERIALIZE_FAIL);
+    EXPECT_NE(decoded.error().message.find("failed"), std::string::npos);
+
+    auto& layout = offset_allocator_object.via.array.ptr[5];
+    layout.via.array.ptr[9] = msgpack::object();
+    auto decoded_layout =
+        Serializer<offset_allocator::__Allocator>::deserialize(layout);
+    ASSERT_FALSE(decoded_layout.has_value());
+    EXPECT_EQ(decoded_layout.error().code, ErrorCode::DESERIALIZE_FAIL);
+    EXPECT_NE(decoded_layout.error().message.find("invalid scalar field"),
+              std::string::npos);
+}
+
+}  // namespace mooncake::ha
diff --git a/mooncake-store/tests/ha/standby/ha_metric_manager_test.cpp b/mooncake-store/tests/ha/standby/ha_metric_manager_test.cpp
index 7034db0979..4a76830faa 100644
--- a/mooncake-store/tests/ha/standby/ha_metric_manager_test.cpp
+++ b/mooncake-store/tests/ha/standby/ha_metric_manager_test.cpp
@@ -1,15 +1,44 @@
 #include "ha_metric_manager.h"
+#include "standby_state_machine.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
 #include <atomic>
 #include <chrono>
+#include <optional>
+#include <sstream>
 #include <string>
 #include <thread>
 
 namespace mooncake::test {
 
+namespace {
+
+std::optional<int64_t> FindSerializedMetricValue(
+    const std::string& metrics, const std::string& metric_name) {
+    std::istringstream lines(metrics);
+    std::string line;
+    const std::string prefix = metric_name + " ";
+    while (std::getline(lines, line)) {
+        if (line.rfind(prefix, 0) != 0) {
+            continue;
+        }
+
+        std::istringstream value_stream(line.substr(prefix.size()));
+        int64_t value = 0;
+        if (!(value_stream >> value)) {
+            return std::nullopt;
+        }
+        value_stream >> std::ws;
+        return value_stream.eof() ? std::optional<int64_t>(value)
+                                  : std::nullopt;
+    }
+    return std::nullopt;
+}
+
+}  // namespace
+
 class HAMetricManagerTest : public ::testing::Test {
    protected:
     void SetUp() override {
@@ -22,6 +51,99 @@ class HAMetricManagerTest : public ::testing::Test {
     HAMetricManager& M() { return HAMetricManager::instance(); }
 };
 
+TEST_F(HAMetricManagerTest,
+       SnapshotActivityFollowsStandbyLifecycleWithoutDroppingCounters) {
+    M().reset_snapshot_runtime(true);
+    using Operation = HAMetricManager::SnapshotOperation;
+    for (const auto state :
+         {StandbyState::CONNECTING, StandbyState::WATCHING,
+          StandbyState::PROMOTING, StandbyState::PROMOTED, StandbyState::FAILED,
+          StandbyState::STOPPED, StandbyState::CONNECTING}) {
+        M().set_standby_state(static_cast<int64_t>(state));
+        const bool active = state == StandbyState::CONNECTING ||
+                            state == StandbyState::WATCHING;
+        EXPECT_EQ(active ? 1 : 0,
+                  FindSerializedMetricValue(M().serialize_metrics(),
+                                            "ha_snapshot_active"));
+        const auto before =
+            M().get_snapshot_operation(Operation::Publish).total;
+        M().record_snapshot_operation(Operation::Publish, 0,
+                                      std::chrono::steady_clock::now());
+        EXPECT_EQ(before + 1,
+                  M().get_snapshot_operation(Operation::Publish).total);
+    }
+    M().reset_snapshot_runtime(false);
+    EXPECT_EQ(0, FindSerializedMetricValue(M().serialize_metrics(),
+                                           "ha_snapshot_active"));
+    M().set_standby_state(static_cast<int64_t>(StandbyState::STOPPED));
+}
+
+TEST_F(HAMetricManagerTest, SnapshotMetricsResetGaugesAndKeepCounters) {
+    using Operation = HAMetricManager::SnapshotOperation;
+    using Skip = HAMetricManager::SnapshotSkipReason;
+    M().reset_snapshot_runtime(true);
+    const auto before = M().get_snapshot_operation(Operation::Publish);
+    M().update_snapshot_runtime([](auto& metrics) {
+        metrics.latest_created_at_ms = 0;  // Epoch zero is a valid timestamp.
+        metrics.fallback_created_at_ms =
+            std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::system_clock::now().time_since_epoch())
+                .count() +
+            60000;
+        metrics.durable_batch = 7;
+        metrics.compaction_floor = 3;
+    });
+    M().record_snapshot_skip(Skip::LeaseBusy);
+    {
+        HAMetricManager::SnapshotOperationTimer timer(Operation::Publish);
+        timer.Success(0);
+    }
+    try {
+        HAMetricManager::SnapshotOperationTimer timer(Operation::Publish);
+        throw 1;
+    } catch (int) {
+    }
+    const auto after = M().get_snapshot_operation(Operation::Publish);
+    EXPECT_EQ(before.total + 2, after.total);
+    EXPECT_EQ(before.errors + 1, after.errors);
+    const auto upload_before = M().get_snapshot_operation(Operation::Upload);
+    M().record_snapshot_operation(
+        Operation::Upload, 0,
+        std::chrono::steady_clock::now() - std::chrono::seconds(2));
+    EXPECT_GE(M().get_snapshot_operation(Operation::Upload).elapsed_us -
+                  upload_before.elapsed_us,
+              2000000u);
+    auto text = M().serialize_metrics();
+    EXPECT_EQ(2, FindSerializedMetricValue(text, "ha_snapshot_count"));
+    EXPECT_EQ(1, FindSerializedMetricValue(text, "ha_snapshot_latest_present"));
+    EXPECT_GT(
+        *FindSerializedMetricValue(text, "ha_snapshot_latest_age_seconds"), 0);
+    EXPECT_EQ(
+        0, FindSerializedMetricValue(text, "ha_snapshot_fallback_age_seconds"));
+    EXPECT_EQ(
+        4, FindSerializedMetricValue(text, "ha_snapshot_uncompacted_batches"));
+    EXPECT_EQ(1, FindSerializedMetricValue(
+                     text, "ha_snapshot_skip_reason{reason=\"lease_busy\"}"));
+    M().reset_snapshot_runtime(false);
+    M().update_snapshot_runtime(
+        [](auto& metrics) { metrics.snapshot_bytes = 100; });
+    M().record_snapshot_operation(Operation::Publish, 0,
+                                  std::chrono::steady_clock::now());
+    EXPECT_EQ(after.total,
+              M().get_snapshot_operation(Operation::Publish).total);
+    text = M().serialize_metrics();
+    EXPECT_EQ(0, FindSerializedMetricValue(text, "ha_snapshot_enabled"));
+    EXPECT_EQ(0, FindSerializedMetricValue(text, "ha_snapshot_bytes"));
+    EXPECT_EQ(0, FindSerializedMetricValue(text, "ha_snapshot_count"));
+    EXPECT_EQ(1, FindSerializedMetricValue(
+                     text, "ha_snapshot_skip_reason{reason=\"disabled\"}"));
+    M().reset_snapshot_runtime(true);
+    M().update_snapshot_runtime(
+        [](auto& metrics) { metrics.compaction_floor = 100; });
+    EXPECT_EQ(0, FindSerializedMetricValue(M().serialize_metrics(),
+                                           "ha_snapshot_uncompacted_batches"));
+}
+
 // ========== 7.1.1 Metric update tests ==========
 
 TEST_F(HAMetricManagerTest, TestSetOpLogLastSequenceId) {
@@ -95,16 +217,47 @@ TEST_F(HAMetricManagerTest, TestIncWatchDisconnectionsAndAppliedEntries) {
 }
 
 TEST_F(HAMetricManagerTest, TestRecordOpLogEtcdWriteLatency) {
-    // Call histogram observe functions, mainly to ensure they do not crash
+    const std::string count_name = "ha_oplog_etcd_write_latency_us_count";
+    const std::string sum_name = "ha_oplog_etcd_write_latency_us_sum";
+    const std::string before_metrics = M().serialize_metrics();
+    const int64_t count_before =
+        FindSerializedMetricValue(before_metrics, count_name).value_or(0);
+    const int64_t sum_before =
+        FindSerializedMetricValue(before_metrics, sum_name).value_or(0);
+
     M().observe_oplog_etcd_write_latency_us(100);
     M().observe_oplog_etcd_write_latency_us(5000);
-    SUCCEED();
+
+    const std::string after_metrics = M().serialize_metrics();
+    const auto count_after =
+        FindSerializedMetricValue(after_metrics, count_name);
+    const auto sum_after = FindSerializedMetricValue(after_metrics, sum_name);
+    ASSERT_TRUE(count_after.has_value());
+    ASSERT_TRUE(sum_after.has_value());
+    EXPECT_EQ(count_before + 2, *count_after);
+    EXPECT_EQ(sum_before + 5100, *sum_after);
 }
 
 TEST_F(HAMetricManagerTest, TestRecordOpLogApplyLatency) {
+    const std::string count_name = "ha_oplog_apply_latency_us_count";
+    const std::string sum_name = "ha_oplog_apply_latency_us_sum";
+    const std::string before_metrics = M().serialize_metrics();
+    const int64_t count_before =
+        FindSerializedMetricValue(before_metrics, count_name).value_or(0);
+    const int64_t sum_before =
+        FindSerializedMetricValue(before_metrics, sum_name).value_or(0);
+
     M().observe_oplog_apply_latency_us(50);
     M().observe_oplog_apply_latency_us(1000);
-    SUCCEED();
+
+    const std::string after_metrics = M().serialize_metrics();
+    const auto count_after =
+        FindSerializedMetricValue(after_metrics, count_name);
+    const auto sum_after = FindSerializedMetricValue(after_metrics, sum_name);
+    ASSERT_TRUE(count_after.has_value());
+    ASSERT_TRUE(sum_after.has_value());
+    EXPECT_EQ(count_before + 2, *count_after);
+    EXPECT_EQ(sum_before + 1050, *sum_after);
 }
 
 #ifdef MOONCAKE_ENABLE_OPLOG_PERF_METRICS
@@ -225,6 +378,57 @@ TEST_F(HAMetricManagerTest, TestConcurrentAccess) {
     EXPECT_EQ(before + kThreads * kIncrementsPerThread, after);
 }
 
+TEST_F(HAMetricManagerTest, WriterOwnershipAndRangeSerialization) {
+    auto& mgr = HAMetricManager::instance();
+    const auto before = mgr.get_writer_runtime().retry_count;
+    HAMetricManager::WriterRuntimeSnapshot first;
+    first.accepting = true;
+    const auto old_owner = mgr.activate_writer_runtime(first);
+    auto serialized = mgr.serialize_metrics();
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_first_sequence"),
+        0);
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_last_sequence"),
+        0);
+
+    first.retry_count = 2;
+    first.stuck_range = std::make_pair(11, 15);
+    mgr.update_writer_runtime(old_owner, first);
+    serialized = mgr.serialize_metrics();
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_first_sequence"),
+        11);
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_last_sequence"),
+        15);
+    EXPECT_EQ(mgr.get_writer_runtime().retry_count, before + 2);
+
+    first.stuck_range.reset();
+    mgr.update_writer_runtime(old_owner, first);
+    serialized = mgr.serialize_metrics();
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_first_sequence"),
+        0);
+    EXPECT_EQ(
+        FindSerializedMetricValue(serialized, "ha_writer_stuck_last_sequence"),
+        0);
+
+    HAMetricManager::WriterRuntimeSnapshot second;
+    second.accepting = true;
+    second.durable_sequence = 20;
+    const auto new_owner = mgr.activate_writer_runtime(second);
+    first.accepting = false;
+    first.terminal_reason = "fenced";
+    mgr.update_writer_runtime(old_owner, first);
+    EXPECT_TRUE(mgr.get_writer_runtime().accepting);
+    EXPECT_EQ(mgr.get_writer_runtime().durable_sequence, 20);
+    EXPECT_TRUE(mgr.get_writer_runtime().terminal_reason.empty());
+    second.retry_count = 1;
+    mgr.update_writer_runtime(new_owner, second);
+    EXPECT_EQ(mgr.get_writer_runtime().retry_count, before + 3);
+}
+
 }  // namespace mooncake::test
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp b/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
index 317a48d799..a9dea37fca 100644
--- a/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
+++ b/mooncake-store/tests/ha/standby/hot_standby_service_test.cpp
@@ -3,16 +3,22 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <atomic>
 #include <chrono>
 #include <map>
 #include <memory>
+#include <mutex>
+#include <optional>
 #include <string>
 #include <string_view>
 #include <thread>
+#include <utility>
 
 #include <xxhash.h>
 
+#include "ha_metric_manager.h"
 #include "master_service.h"
+#include "metadata_store.h"
 #include "ha/kv/ha_kv_backend.h"
 #include "ha/oplog/oplog_batch_codec.h"
 #include "ha/oplog/oplog_batch_storage.h"
@@ -41,6 +47,199 @@ class FakeSnapshotProvider final : public SnapshotProvider {
     tl::expected<std::optional<LoadedSnapshot>, ErrorCode> result_;
 };
 
+class FakeCaptureHaKvBackend final : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin_key, std::string_view end_key,
+                    size_t limit, std::vector<KvPair>& kvs) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        kvs.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin_key && key < end_key) {
+                kvs.push_back({.key = key, .value = value});
+                if (limit != 0 && kvs.size() >= limit) {
+                    break;
+                }
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
+
+   private:
+    std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+};
+
+OpLogEntry MakeEntry(uint64_t seq, OpType type, const std::string& key,
+                     const std::string& payload) {
+    OpLogEntry e;
+    e.sequence_id = seq;
+    e.timestamp_ms = std::chrono::duration_cast<std::chrono::milliseconds>(
+                         std::chrono::steady_clock::now().time_since_epoch())
+                         .count();
+    e.op_type = type;
+    e.object_key = key;
+    e.payload = payload;
+    e.checksum =
+        static_cast<uint32_t>(XXH32(payload.data(), payload.size(), 0));
+    e.prefix_hash =
+        key.empty() ? 0
+                    : static_cast<uint32_t>(XXH32(key.data(), key.size(), 0));
+    return e;
+}
+
+std::string MakeValidPayload(uint64_t client_id_first = 1,
+                             uint64_t client_id_second = 2,
+                             uint64_t size = 1024) {
+    mooncake::MetadataPayload payload;
+    payload.client_id = {client_id_first, client_id_second};
+    payload.size = size;
+    auto result = struct_pack::serialize(payload);
+    return std::string(result.begin(), result.end());
+}
+
+class FakeHaKvBackend : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (next_get_error_ != ErrorCode::OK) {
+            auto error = next_get_error_;
+            next_get_error_ = ErrorCode::OK;
+            return error;
+        }
+        if (get_error_ != ErrorCode::OK) {
+            return get_error_;
+        }
+        auto it = values_.find(std::string(key));
+        if (it == values_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        values_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+    ErrorCode Range(std::string_view begin_key, std::string_view end_key,
+                    size_t limit, std::vector<KvPair>& kvs) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (range_error_ != ErrorCode::OK) {
+            return range_error_;
+        }
+        kvs.clear();
+        for (const auto& [key, value] : values_) {
+            if (key >= begin_key && key < end_key) {
+                kvs.push_back({.key = key, .value = value});
+                if (kvs.size() >= limit) break;
+            }
+        }
+        return ErrorCode::OK;
+    }
+    bool SupportsTxn() const override { return true; }
+    ErrorCode Txn(const KvTxn& txn) override {
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (const auto& compare : txn.compares) {
+            auto it = values_.find(compare.key);
+            if (compare.kind == KvCompareKind::kKeyNotExists) {
+                if (it != values_.end()) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (it == values_.end() ||
+                       it->second != compare.expected_value) {
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+        }
+        for (const auto& put : txn.puts) {
+            values_[put.key] = put.value;
+        }
+        return ErrorCode::OK;
+    }
+    void SetGetError(ErrorCode err) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        get_error_ = err;
+    }
+    void SetRangeError(ErrorCode err) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        range_error_ = err;
+    }
+    void FailNextGet(ErrorCode err) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        next_get_error_ = err;
+    }
+
+   private:
+    mutable std::mutex mutex_;
+    std::map<std::string, std::string> values_;
+    ErrorCode get_error_{ErrorCode::OK};
+    ErrorCode range_error_{ErrorCode::OK};
+    ErrorCode next_get_error_{ErrorCode::OK};
+};
+
+OpLogBatchRecord MakeBatch(uint64_t batch_id, uint64_t first_seq,
+                           uint64_t last_seq) {
+    OpLogBatchRecord batch;
+    batch.batch_id = batch_id;
+    batch.first_seq = first_seq;
+    batch.last_seq = last_seq;
+    for (uint64_t seq = first_seq; seq <= last_seq; ++seq) {
+        batch.entries.push_back(MakeEntry(seq, OpType::PUT_END,
+                                          "batch_key_" + std::to_string(seq),
+                                          MakeValidPayload()));
+    }
+    return batch;
+}
+
+OpLogBatchRecord MakeCaptureBatch(uint64_t batch_id, uint64_t sequence_id,
+                                  OpType op_type = OpType::REMOVE,
+                                  std::string object_key = "key",
+                                  std::string payload = {}) {
+    OpLogEntry entry;
+    entry.sequence_id = sequence_id;
+    entry.op_type = op_type;
+    entry.tenant_id = "tenant";
+    entry.object_key = std::move(object_key);
+    entry.payload = std::move(payload);
+    entry.checksum = static_cast<uint32_t>(
+        XXH32(entry.payload.data(), entry.payload.size(), 0));
+    entry.prefix_hash = static_cast<uint32_t>(
+        XXH32(entry.object_key.data(), entry.object_key.size(), 0));
+
+    OpLogBatchRecord batch;
+    batch.batch_id = batch_id;
+    batch.first_seq = sequence_id;
+    batch.last_seq = sequence_id;
+    batch.entries.push_back(std::move(entry));
+    return batch;
+}
+
 LoadedSnapshot MakeSnapshot(std::string snapshot_id, uint64_t seq_id,
                             std::string key, uint64_t size) {
     LoadedSnapshot snapshot;
@@ -50,11 +249,42 @@ LoadedSnapshot MakeSnapshot(std::string snapshot_id, uint64_t seq_id,
     StandbyObjectMetadata metadata;
     metadata.client_id = UUID{1, 2};
     metadata.size = size;
-    metadata.last_sequence_id = seq_id;
     snapshot.metadata.emplace_back("default", std::move(key), metadata);
     return snapshot;
 }
 
+std::shared_ptr<FakeHaKvBackend> MakeBackendWithBatch(
+    const std::string& cluster_id, uint64_t batch_id, uint64_t first_seq,
+    uint64_t last_seq) {
+    auto backend = std::make_shared<FakeHaKvBackend>();
+    EXPECT_EQ(ErrorCode::OK,
+              backend->Put(BuildDurablePrefixKey(cluster_id),
+                           EncodeDurablePrefix(
+                               {.batch_id = batch_id, .last_seq = last_seq})));
+    EXPECT_EQ(ErrorCode::OK,
+              backend->Put(BuildBatchRecordKey(cluster_id, batch_id),
+                           EncodeOpLogBatchRecord(
+                               MakeBatch(batch_id, first_seq, last_seq))));
+    return backend;
+}
+
+bool WaitForAppliedSequence(HotStandbyService& service, uint64_t seq,
+                            int max_attempts = 200) {
+    for (int i = 0;
+         i < max_attempts && service.GetLatestAppliedSequenceId() < seq; ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+    return service.GetLatestAppliedSequenceId() >= seq;
+}
+
+bool WaitForState(HotStandbyService& service, StandbyState state,
+                  int max_attempts = 200) {
+    for (int i = 0; i < max_attempts && service.GetState() != state; ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+    return service.GetState() == state;
+}
+
 }  // namespace
 
 class HotStandbyServiceTest : public ::testing::Test {
@@ -99,7 +329,6 @@ std::unique_ptr<HotStandbyService> CreateSnapshotOnlyReadyStandby(
     StandbyObjectMetadata metadata;
     metadata.client_id = UUID{1, 2};
     metadata.size = 4096;
-    metadata.last_sequence_id = 42;
     snapshot.metadata.emplace_back("default", "key-1", metadata);
 
     service->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
@@ -109,105 +338,141 @@ std::unique_ptr<HotStandbyService> CreateSnapshotOnlyReadyStandby(
     return service;
 }
 
+std::unique_ptr<HotStandbyService> CreateOplogFollowingStandby(
+    HotStandbyConfig config, const std::string& cluster_id,
+    std::shared_ptr<HaKvBackend> backend) {
+    config.enable_oplog_following = true;
+    config.oplog_poll_interval_ms =
+        config.oplog_poll_interval_ms > 0 ? config.oplog_poll_interval_ms : 1;
+    auto service = std::make_unique<HotStandbyService>(config);
+    service->SetCatchUpBatchKvBackendForTesting(std::move(backend));
+    return service;
+}
+
 }  // namespace
 
 // ========== 6.1.1 Start/Stop tests ==========
 
 TEST_F(HotStandbyServiceTest, TestStart) {
-#ifdef STORE_USE_ETCD
-    // Requires a real etcd cluster and valid cluster configuration; acts as an
-    // integration placeholder
-    GTEST_SKIP()
-        << "Requires real etcd connection, run in integration environment.";
-#else
-    ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
-    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
-#endif
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+    EXPECT_EQ(1u, service_->GetLatestAppliedSequenceId());
 }
 
 TEST_F(HotStandbyServiceTest, TestStart_AlreadyRunning) {
+    service_ = CreateSnapshotOnlyReadyStandby(config_, cluster_id_);
+
+    EXPECT_EQ(ErrorCode::OK,
+              service_->Start("unused", "unused", "unused-cluster"));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+}
+
+TEST_F(HotStandbyServiceTest, TestStart_InvalidEtcdEndpoints) {
 #ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Requires real etcd connection to verify double start semantics.";
+    // Empty endpoints fail synchronously in NewStoreEtcdClient (no dial).
+    // Unreachable hosts such as 127.0.0.1:1 only fail later on Get/watch.
+    config_.enable_oplog_following = true;
+    service_ = std::make_unique<HotStandbyService>(config_);
+
+    const ErrorCode err = service_->Start("primary", "", cluster_id_);
+    EXPECT_NE(ErrorCode::OK, err);
+    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 #else
-    // After the first Start fails and state becomes FAILED, the second Start
-    // should still return INTERNAL_ERROR
-    ErrorCode err1 =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err1);
-    ErrorCode err2 =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err2);
+    GTEST_SKIP() << "Invalid etcd endpoint coverage requires STORE_USE_ETCD";
 #endif
 }
 
-TEST_F(HotStandbyServiceTest, TestStart_InvalidEtcdEndpoints) {
+TEST_F(HotStandbyServiceTest,
+       TestStart_OpLogFollowingRequiresEtcdWithoutInjectedBackend) {
 #ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd to simulate invalid endpoints.";
+    GTEST_SKIP() << "Feature-gate coverage applies when STORE_USE_ETCD is OFF";
 #else
-    std::string invalid_endpoints = "invalid_endpoint";
-    ErrorCode err =
-        service_->Start("primary_unused", invalid_endpoints, cluster_id_);
+    config_.enable_oplog_following = true;
+    service_ = std::make_unique<HotStandbyService>(config_);
+
+    const ErrorCode err =
+        service_->Start("primary", oplog_endpoints_, cluster_id_);
     EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
+    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 #endif
 }
 
-TEST_F(HotStandbyServiceTest, TestStop) {
-    // Stop should be safe and idempotent even if Start was never called
-    service_->Stop();
-    SUCCEED();
-}
-
 TEST_F(HotStandbyServiceTest, TestStop_WhenNotRunning) {
-    // Multiple Stop calls should be idempotent
+    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
     service_->Stop();
+    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
     service_->Stop();
-    SUCCEED();
+    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
 }
 
 // ========== 6.1.2 State transition tests ==========
 
 TEST_F(HotStandbyServiceTest, TestStateTransition_StartToWatching) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Requires real etcd to drive full state transition to WATCHING.";
-#else
-    // In non-STORE_USE_ETCD builds, Start will set the state machine directly
-    // to FAILED
-    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
-    ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
-    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
-#endif
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
 }
 
 TEST_F(HotStandbyServiceTest, TestStateTransition_ConnectionFailed) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Connection failure requires real etcd and invalid endpoints.";
-#else
-    // In non-etcd mode we cannot distinguish detailed connection errors; only
-    // verify it doesn't crash
-    ErrorCode err =
-        service_->Start("primary_unused", "bad_endpoint", cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
-#endif
+    // Deterministic connection-failure coverage: Start() succeeds with an
+    // injected backend, then a later Get error from the replication loop
+    // drives WATCHING -> FAILED. Prefer this over a live unreachable-etcd
+    // dial so we do not touch the process-global store client or network
+    // timeouts.
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    config_.batch_oplog_retry_timeout_sec = 0;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+
+    backend->SetGetError(ErrorCode::ETCD_OPERATION_ERROR);
+    ASSERT_TRUE(WaitForState(*service_, StandbyState::FAILED));
+    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR,
+              service_->GetSyncStatus().last_error);
 }
 
 TEST_F(HotStandbyServiceTest, TestStateTransition_SyncFailed) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Sync failure requires real etcd and OpLog watcher behavior.";
-#else
-    // In non-etcd mode, the sync phase is not actually executed; just ensure
-    // the call is safe
-    ErrorCode err =
-        service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    EXPECT_EQ(ErrorCode::INTERNAL_ERROR, err);
-#endif
+    // Start successfully, then publish an unreadable batch so the replication
+    // loop (not snapshot restore) drives the FAILED transition.
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    config_.batch_oplog_retry_timeout_sec = 0;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+
+    ASSERT_EQ(ErrorCode::OK, backend->Put(BuildBatchRecordKey(cluster_id_, 2),
+                                          "not-a-valid-batch-record"));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+
+    ASSERT_TRUE(WaitForState(*service_, StandbyState::FAILED));
+    EXPECT_NE(ErrorCode::OK, service_->GetSyncStatus().last_error);
 }
 
 // ========== 6.1.3 Sync status tests ==========
@@ -223,24 +488,22 @@ TEST_F(HotStandbyServiceTest, TestGetSyncStatus_InitialState) {
 }
 
 TEST_F(HotStandbyServiceTest, TestGetSyncStatus_AfterSync) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Requires real etcd and OpLog activity to change sync status.";
-#else
-    // In non-etcd mode, calling Start will not change applied/primary, but the
-    // state machine enters FAILED
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    StandbySyncStatus status = service_->GetSyncStatus();
-    EXPECT_EQ(StandbyState::FAILED, status.state);
-#endif
-}
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
 
-TEST_F(HotStandbyServiceTest, TestGetSyncStatus) {
-    // Basic coverage: multiple calls should return consistent values and not
-    // crash
-    StandbySyncStatus s1 = service_->GetSyncStatus();
-    StandbySyncStatus s2 = service_->GetSyncStatus();
-    EXPECT_EQ(s1.state, s2.state);
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+
+    StandbySyncStatus status = service_->GetSyncStatus();
+    EXPECT_EQ(StandbyState::WATCHING, status.state);
+    EXPECT_TRUE(status.is_connected);
+    EXPECT_TRUE(status.is_syncing);
+    EXPECT_EQ(1u, status.applied_seq_id);
+    EXPECT_GE(status.primary_seq_id, status.applied_seq_id);
+    EXPECT_EQ(ErrorCode::OK, status.last_error);
 }
 
 // ========== 6.1.4 Promotion tests ==========
@@ -274,7 +537,6 @@ TEST_F(HotStandbyServiceTest, TestPromoteAndExportSnapshot_FinalCatchUp) {
     StandbyObjectMetadata metadata;
     metadata.client_id = UUID{1, 2};
     metadata.size = 4096;
-    metadata.last_sequence_id = 10;
     snapshot.metadata.emplace_back("default", "key-1", metadata);
 
     service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
@@ -305,36 +567,62 @@ TEST_F(HotStandbyServiceTest, TestPromoteAndExportSnapshot_FinalCatchUp) {
 // ========== 6.1.5 Warm start tests ==========
 
 TEST_F(HotStandbyServiceTest, TestWarmStart_WithLocalState) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd and pre-populated local metadata to "
-                    "test warm start.";
-#else
-    // In non-etcd mode, only verify that Start is safe to call
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    SUCCEED();
-#endif
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+    EXPECT_GE(service_->GetMetadataCount(), 1u);
+    service_->Stop();
+    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+    EXPECT_EQ(1u, service_->GetLatestAppliedSequenceId());
+    EXPECT_GE(service_->GetMetadataCount(), 1u);
 }
 
 TEST_F(HotStandbyServiceTest, TestWarmStart_WithoutLocalState) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd and snapshot provider configuration.";
-#else
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    SUCCEED();
-#endif
+    auto backend = std::make_shared<FakeHaKvBackend>();
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    config_.enable_oplog_following = true;
+    config_.enable_snapshot_bootstrap = false;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+    EXPECT_EQ(0u, service_->GetLatestAppliedSequenceId());
+    EXPECT_EQ(0u, service_->GetMetadataCount());
 }
 
 TEST_F(HotStandbyServiceTest, TestWarmStart_WithSnapshot) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires snapshot provider and real etcd to exercise "
-                    "snapshot bootstrap.";
-#else
+    auto backend = std::make_shared<FakeHaKvBackend>();
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
     config_.enable_snapshot_bootstrap = true;
-    // Recreate service to apply the new configuration
-    service_.reset(new HotStandbyService(config_));
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    SUCCEED();
-#endif
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+    service_->SetSnapshotProvider(
+        std::make_unique<FakeSnapshotProvider>(std::optional<LoadedSnapshot>(
+            MakeSnapshot("warm-start-snapshot", 42, "key-1", 4096))));
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
+    EXPECT_EQ(42u, service_->GetLatestAppliedSequenceId());
+    EXPECT_EQ(1u, service_->GetMetadataCount());
 }
 
 TEST_F(HotStandbyServiceTest, TestStart_SnapshotOnlyWithSnapshot) {
@@ -395,7 +683,6 @@ TEST_F(HotStandbyServiceTest,
     ASSERT_EQ(1u, exported.size());
     EXPECT_EQ("key-new", exported[0].key);
     EXPECT_EQ(8192u, exported[0].metadata.size);
-    EXPECT_EQ(84u, exported[0].metadata.last_sequence_id);
 }
 
 TEST_F(HotStandbyServiceTest, TestStart_SnapshotOnlyWhenProviderFails) {
@@ -411,6 +698,22 @@ TEST_F(HotStandbyServiceTest, TestStart_SnapshotOnlyWhenProviderFails) {
     EXPECT_EQ(StandbyState::FAILED, service_->GetState());
 }
 
+TEST_F(HotStandbyServiceTest, SnapshotRestoreRejectsDuplicateObject) {
+    config_.enable_snapshot_bootstrap = true;
+    config_.enable_oplog_following = false;
+    service_ = std::make_unique<HotStandbyService>(config_);
+
+    auto snapshot = MakeSnapshot("snapshot", 42, "key", 1);
+    snapshot.metadata.push_back(snapshot.metadata.front());
+    snapshot.metadata.back().metadata.size = 2;
+    service_->SetSnapshotProvider(std::make_unique<FakeSnapshotProvider>(
+        std::optional<LoadedSnapshot>(std::move(snapshot))));
+
+    EXPECT_EQ(ErrorCode::DESERIALIZE_FAIL,
+              service_->Start("", "", cluster_id_));
+    EXPECT_EQ(StandbyState::FAILED, service_->GetState());
+}
+
 // ========== 6.1.6 Metadata operation tests ==========
 
 TEST_F(HotStandbyServiceTest, TestGetMetadataCount) {
@@ -467,158 +770,176 @@ TEST_F(HotStandbyServiceTest, TestExportStandbySnapshot_Empty) {
     EXPECT_TRUE(snapshot.segments.empty());
 }
 
-// ========== 6.1.7 Replication loop tests ==========
+TEST_F(HotStandbyServiceTest,
+       SnapshotCaptureLeaseTransfersAndReleasesOnDestruction) {
+    auto backend = std::make_shared<FakeCaptureHaKvBackend>();
+    SegmentMountOp mount;
+    mount.segment_name = "segment-1";
+    mount.transport_endpoint = "127.0.0.1:12345";
+    mount.capacity = 4096;
+    mount.is_memory_segment = true;
+    auto mount_payload = struct_pack::serialize(mount);
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(
+            BuildBatchRecordKey(cluster_id_, 1),
+            EncodeOpLogBatchRecord(MakeCaptureBatch(
+                1, 1, OpType::SEGMENT_MOUNT, mount.segment_name,
+                std::string(mount_payload.begin(), mount_payload.end())))));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 1, .last_seq = 1})));
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildProducerViewKey(cluster_id_), "7"));
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = std::make_unique<HotStandbyService>(config_);
+    service_->SetCatchUpBatchKvBackendForTesting(backend);
+    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
 
-TEST_F(HotStandbyServiceTest, TestReplicationLoop_UpdatesMetrics) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP()
-        << "Requires real etcd and running replication loop to update metrics.";
-#else
-    // In non-etcd mode, ReplicationLoop is never started, but calling Stop
-    // should be safe
-    service_->Stop();
-    SUCCEED();
-#endif
-}
+    auto capture = service_->BeginBatchOpLogSnapshotCapture();
+    ASSERT_TRUE(capture.has_value());
+    EXPECT_EQ(1u, capture->last_included_seq);
+    EXPECT_EQ(1u, capture->last_included_batch_id);
+    EXPECT_EQ(7, capture->producer_view_version);
+    ASSERT_EQ(1u, capture->segments.size());
+    EXPECT_EQ(mount.segment_name, capture->segments[0].segment_name);
+    EXPECT_EQ(mount.transport_endpoint,
+              capture->segments[0].transport_endpoint);
+
+    std::optional<BatchOpLogSnapshotCapture> capture_owner(std::move(*capture));
+    EXPECT_TRUE(capture->done());
+    std::vector<StandbyObjectEntry> moved_from_chunk;
+    EXPECT_FALSE(service_->CopyNextBatchOpLogSnapshotChunk(1, *capture,
+                                                           moved_from_chunk));
+    capture.reset();
+
+    std::vector<StandbyObjectEntry> chunk;
+    ASSERT_TRUE(
+        service_->CopyNextBatchOpLogSnapshotChunk(2, *capture_owner, chunk));
+    EXPECT_TRUE(chunk.empty());
+    EXPECT_TRUE(capture_owner->done());
 
-TEST_F(HotStandbyServiceTest, TestReplicationLoop_HandlesDisconnect) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd and watcher disconnect to exercise "
-                    "disconnect path.";
-#else
-    // DisconnectFromPrimary is private; verify Stop() is safe instead
-    service_->Stop();
-    SUCCEED();
-#endif
+    ASSERT_EQ(ErrorCode::OK,
+              backend->Put(BuildBatchRecordKey(cluster_id_, 2),
+                           EncodeOpLogBatchRecord(MakeCaptureBatch(2, 2))));
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 2, .last_seq = 2})));
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    EXPECT_EQ(1u, service_->GetLatestAppliedSequenceId());
+
+    capture_owner.reset();
+    for (int i = 0; i < 100 && service_->GetLatestAppliedSequenceId() != 2;
+         ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    EXPECT_EQ(2u, service_->GetLatestAppliedSequenceId());
 }
 
-// ========== 6.1.8 Verification loop tests ==========
+TEST_F(HotStandbyServiceTest, PromotionCancelsActiveSnapshotCapture) {
+    auto backend = std::make_shared<FakeCaptureHaKvBackend>();
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = std::make_unique<HotStandbyService>(config_);
+    service_->SetCatchUpBatchKvBackendForTesting(backend);
+    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
 
-TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenEnabled) {
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd and running verification loop to "
-                    "observe behavior.";
-#else
-    config_.enable_verification = true;
-    service_.reset(new HotStandbyService(config_));
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    service_->Stop();
-    SUCCEED();
-#endif
+    auto capture = service_->BeginBatchOpLogSnapshotCapture();
+    ASSERT_TRUE(capture.has_value());
+    ASSERT_EQ(ErrorCode::OK, service_->Promote());
+
+    std::vector<StandbyObjectEntry> chunk;
+    EXPECT_FALSE(service_->CopyNextBatchOpLogSnapshotChunk(1, *capture, chunk));
 }
 
-TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenDisabled) {
-    // By default config_.enable_verification = false, so Start should not spawn
-    // a verification thread
-#ifdef STORE_USE_ETCD
-    GTEST_SKIP() << "Requires real etcd connection to start service.";
-#else
-    (void)service_->Start("primary_unused", oplog_endpoints_, cluster_id_);
-    service_->Stop();
-    SUCCEED();
-#endif
+TEST_F(HotStandbyServiceTest, SnapshotCaptureRejectsInconsistentSequence) {
+    auto backend = std::make_shared<FakeCaptureHaKvBackend>();
+    ASSERT_EQ(
+        ErrorCode::OK,
+        backend->Put(BuildDurablePrefixKey(cluster_id_),
+                     EncodeDurablePrefix({.batch_id = 0, .last_seq = 0})));
+    config_.enable_snapshot_bootstrap = true;
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = std::make_unique<HotStandbyService>(config_);
+    service_->SetSnapshotProvider(
+        std::make_unique<FakeSnapshotProvider>(std::optional<LoadedSnapshot>(
+            MakeSnapshot("snapshot", 42, "key", 4096))));
+    service_->SetCatchUpBatchKvBackendForTesting(backend);
+    ASSERT_EQ(ErrorCode::OK, service_->Start("", "", cluster_id_));
+
+    EXPECT_FALSE(service_->BeginBatchOpLogSnapshotCapture().has_value());
 }
 
-// ========== Issue 2 fail-closed catch-up ==========
+// ========== 6.1.7 Replication loop tests ==========
 
-namespace {
+TEST_F(HotStandbyServiceTest, TestReplicationLoop_UpdatesMetrics) {
+    auto backend = MakeBackendWithBatch(cluster_id_, 1, 1, 1);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    // Shared so Stop()/TearDown callbacks cannot outlive a stack atomic.
+    auto observed_applied = std::make_shared<std::atomic<uint64_t>>(0);
+    service_->SetSyncStatusCallback(
+        [observed_applied](const StandbySyncStatus& status) {
+            observed_applied->store(status.applied_seq_id,
+                                    std::memory_order_relaxed);
+        });
 
-// Helper to create a valid OpLogEntry with checksum (mirrors the helper in
-// oplog_applier_test.cpp).
-OpLogEntry MakeEntry(uint64_t seq, OpType type, const std::string& key,
-                     const std::string& payload) {
-    OpLogEntry e;
-    e.sequence_id = seq;
-    e.timestamp_ms = std::chrono::duration_cast<std::chrono::milliseconds>(
-                         std::chrono::steady_clock::now().time_since_epoch())
-                         .count();
-    e.op_type = type;
-    e.object_key = key;
-    e.payload = payload;
-    // Compute checksum and prefix_hash using the production algorithm.
-    e.checksum =
-        static_cast<uint32_t>(XXH32(payload.data(), payload.size(), 0));
-    e.prefix_hash =
-        key.empty() ? 0
-                    : static_cast<uint32_t>(XXH32(key.data(), key.size(), 0));
-    return e;
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForAppliedSequence(*service_, 1));
+    EXPECT_EQ(static_cast<int64_t>(StandbyState::WATCHING),
+              HAMetricManager::instance().get_standby_state());
+    for (int i = 0; i < 100 && observed_applied->load() < 1; ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+    EXPECT_GE(observed_applied->load(), 1u);
+    service_->Stop();
+    service_->SetSyncStatusCallback({});
+    EXPECT_EQ(StandbyState::STOPPED, service_->GetState());
 }
 
-// Helper to create a valid struct_pack payload for PUT_END
-std::string MakeValidPayload(uint64_t client_id_first = 1,
-                             uint64_t client_id_second = 2,
-                             uint64_t size = 1024) {
-    mooncake::MetadataPayload payload;
-    payload.client_id = {client_id_first, client_id_second};
-    payload.size = size;
-    auto result = struct_pack::serialize(payload);
-    return std::string(result.begin(), result.end());
+TEST_F(HotStandbyServiceTest, TestReplicationLoop_HandlesDisconnect) {
+    auto backend = std::make_shared<FakeHaKvBackend>();
+    backend->SetGetError(ErrorCode::ETCD_OPERATION_ERROR);
+    config_.enable_oplog_following = true;
+    config_.oplog_poll_interval_ms = 1;
+    config_.batch_oplog_retry_timeout_sec = 0;
+    service_ = CreateOplogFollowingStandby(config_, cluster_id_, backend);
+
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("primary", oplog_endpoints_, cluster_id_));
+    ASSERT_TRUE(WaitForState(*service_, StandbyState::FAILED));
+    EXPECT_EQ(ErrorCode::ETCD_OPERATION_ERROR,
+              service_->GetSyncStatus().last_error);
 }
 
-class FakeHaKvBackend : public HaKvBackend {
-   public:
-    ErrorCode Get(std::string_view key, std::string& value) override {
-        if (next_get_error_ != ErrorCode::OK) {
-            auto error = next_get_error_;
-            next_get_error_ = ErrorCode::OK;
-            return error;
-        }
-        if (get_error_ != ErrorCode::OK) {
-            return get_error_;
-        }
-        auto it = values_.find(std::string(key));
-        if (it == values_.end()) {
-            return ErrorCode::ETCD_KEY_NOT_EXIST;
-        }
-        value = it->second;
-        return ErrorCode::OK;
-    }
-    ErrorCode Put(std::string_view key, std::string_view value) override {
-        values_[std::string(key)] = std::string(value);
-        return ErrorCode::OK;
-    }
-    ErrorCode Range(std::string_view begin_key, std::string_view end_key,
-                    size_t limit, std::vector<KvPair>& kvs) override {
-        if (range_error_ != ErrorCode::OK) {
-            return range_error_;
-        }
-        kvs.clear();
-        for (const auto& [key, value] : values_) {
-            if (key >= begin_key && key < end_key) {
-                kvs.push_back({.key = key, .value = value});
-                if (kvs.size() >= limit) break;
-            }
-        }
-        return ErrorCode::OK;
-    }
-    bool SupportsTxn() const override { return true; }
-    ErrorCode Txn(const KvTxn&) override { return ErrorCode::OK; }
-    void SetGetError(ErrorCode err) { get_error_ = err; }
-    void SetRangeError(ErrorCode err) { range_error_ = err; }
-    void FailNextGet(ErrorCode err) { next_get_error_ = err; }
+// ========== 6.1.8 Verification loop tests ==========
+// Production verification is not implemented yet (loop only VLOG-skips), so
+// these cases stay skipped until checksum comparison has an observable effect.
 
-   private:
-    std::map<std::string, std::string> values_;
-    ErrorCode get_error_{ErrorCode::OK};
-    ErrorCode range_error_{ErrorCode::OK};
-    ErrorCode next_get_error_{ErrorCode::OK};
-};
+TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenEnabled) {
+    GTEST_SKIP() << "Verification has no observable effect yet (loop only "
+                    "VLOG-skips); re-enable when checksum comparison is "
+                    "implemented";
+}
 
-OpLogBatchRecord MakeBatch(uint64_t batch_id, uint64_t first_seq,
-                           uint64_t last_seq) {
-    OpLogBatchRecord batch;
-    batch.batch_id = batch_id;
-    batch.first_seq = first_seq;
-    batch.last_seq = last_seq;
-    for (uint64_t seq = first_seq; seq <= last_seq; ++seq) {
-        batch.entries.push_back(MakeEntry(seq, OpType::PUT_END,
-                                          "batch_key_" + std::to_string(seq),
-                                          MakeValidPayload()));
-    }
-    return batch;
+TEST_F(HotStandbyServiceTest, TestVerificationLoop_WhenDisabled) {
+    GTEST_SKIP() << "Verification has no observable effect yet (loop only "
+                    "VLOG-skips); re-enable when checksum comparison is "
+                    "implemented";
 }
 
-}  // namespace
+// ========== Issue 2 fail-closed catch-up ==========
 
 TEST_F(HotStandbyServiceTest,
        BatchRecordStandbyPollsInjectedBackendWithoutNotifier) {
@@ -811,11 +1132,8 @@ TEST_F(PromotionCatchUpTest, UsesDurablePrefixLastSeqAsCatchUpTarget) {
               batch_backend_->Put(BuildBatchRecordKey(cluster_id_, 1),
                                   EncodeOpLogBatchRecord(MakeBatch(1, 1, 2))));
 
-    auto err = service_->Start("", oplog_endpoints_, cluster_id_);
-    if (err != ErrorCode::OK) {
-        GTEST_SKIP() << "Service could not reach WATCHING state; "
-                        "skipping promotion test";
-    }
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("", oplog_endpoints_, cluster_id_));
     EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
 
     StandbySnapshot out;
@@ -825,6 +1143,7 @@ TEST_F(PromotionCatchUpTest, UsesDurablePrefixLastSeqAsCatchUpTarget) {
 }
 
 TEST_F(PromotionCatchUpTest, RetriesTransientDurablePrefixReadFailure) {
+    config_.batch_oplog_retry_timeout_sec = 0;
     auto batch_backend = std::make_shared<FakeHaKvBackend>();
     ASSERT_EQ(ErrorCode::OK,
               batch_backend->Put(
@@ -833,6 +1152,7 @@ TEST_F(PromotionCatchUpTest, RetriesTransientDurablePrefixReadFailure) {
     ASSERT_EQ(ErrorCode::OK,
               batch_backend->Put(BuildBatchRecordKey(cluster_id_, 1),
                                  EncodeOpLogBatchRecord(MakeBatch(1, 1, 1))));
+    service_ = std::make_unique<HotStandbyService>(config_);
     service_->SetCatchUpBatchKvBackendForTesting(batch_backend);
 
     ASSERT_EQ(ErrorCode::OK,
@@ -870,16 +1190,17 @@ TEST_F(PromotionCatchUpTest, MissingDurablePrefixRejectsNonzeroSequence) {
 }
 
 TEST_F(PromotionCatchUpTest, CatchesUpPrefixThatAppearsBeforePromotion) {
+    const DurablePrefix initial_prefix{.batch_id = 0, .last_seq = 0};
+    ASSERT_EQ(ErrorCode::OK,
+              batch_backend_->Put(BuildDurablePrefixKey(cluster_id_),
+                                  EncodeDurablePrefix(initial_prefix)));
     ASSERT_EQ(ErrorCode::OK,
               service_->Start("", oplog_endpoints_, cluster_id_));
     ASSERT_EQ(StandbyState::WATCHING, service_->GetState());
-    ASSERT_EQ(ErrorCode::OK,
-              batch_backend_->Put(
-                  BuildDurablePrefixKey(cluster_id_),
-                  EncodeDurablePrefix({.batch_id = 1, .last_seq = 1})));
-    ASSERT_EQ(ErrorCode::OK,
-              batch_backend_->Put(BuildBatchRecordKey(cluster_id_, 1),
-                                  EncodeOpLogBatchRecord(MakeBatch(1, 1, 1))));
+
+    OpLogBatchStorage storage(cluster_id_, *batch_backend_);
+    ASSERT_EQ(ErrorCode::OK, storage.WriteBatchAndAdvancePrefix(
+                                 MakeBatch(1, 1, 1), initial_prefix));
 
     StandbySnapshot out;
     ASSERT_EQ(ErrorCode::OK, service_->PromoteAndExportSnapshot(out));
@@ -900,13 +1221,13 @@ TEST_F(PromotionCatchUpTest, PaginatesBatchRecords) {
             batch_backend->Put(BuildBatchRecordKey(cluster_id_, id),
                                EncodeOpLogBatchRecord(MakeBatch(id, id, id))));
     }
+    config_.batch_oplog_retry_timeout_sec = 0;
+    service_ = std::make_unique<HotStandbyService>(config_);
     service_->SetCatchUpBatchKvBackendForTesting(batch_backend);
 
-    auto err = service_->Start("", oplog_endpoints_, cluster_id_);
-    if (err != ErrorCode::OK) {
-        GTEST_SKIP() << "Service could not reach WATCHING state; "
-                        "skipping promotion test";
-    }
+    ASSERT_EQ(ErrorCode::OK,
+              service_->Start("", oplog_endpoints_, cluster_id_));
+    EXPECT_EQ(StandbyState::WATCHING, service_->GetState());
 
     StandbySnapshot out;
     ASSERT_EQ(ErrorCode::OK, service_->PromoteAndExportSnapshot(out));
diff --git a/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp b/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
index c9a425b563..00a164717c 100644
--- a/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
+++ b/mooncake-store/tests/ha/standby/hot_standby_snapshot_bootstrap_test.cpp
@@ -1,4 +1,5 @@
 #include "hot_standby_service.h"
+#include "ha_metric_manager.h"
 
 #include <gflags/gflags.h>
 #include <glog/logging.h>
@@ -77,9 +78,12 @@ class HotStandbySnapshotBootstrapTest
             GetParam(), cluster_id_, FLAGS_redis_endpoint));
     }
 
-    void PublishSnapshot() {
-        auto result = PublishSnapshotPayload(*object_store_, *catalog_store_,
-                                             descriptor_);
+    void PublishSnapshot(
+        SnapshotMetadataFormat format = SnapshotMetadataFormat::kLegacy) {
+        auto result = PublishSnapshotPayload(
+            *object_store_, *catalog_store_, descriptor_, UUID{1, 2},
+            kDefaultTestObjectKey, kDefaultTestDiskFilePath,
+            kDefaultTestObjectSize, format);
         ASSERT_TRUE(result.has_value()) << result.error();
         snapshot_published_ = true;
     }
@@ -103,7 +107,15 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     HotStandbyService service(MakeSnapshotOnlyConfig());
     service.SetSnapshotProvider(std::move(provider.value()));
 
+    HAMetricManager::instance().reset_snapshot_runtime(true);
+    HAMetricManager::instance().update_snapshot_runtime(
+        [](auto& metrics) { metrics.snapshot_bytes = 100; });
     ASSERT_EQ(ErrorCode::OK, service.Start("", "", cluster_id_));
+    const auto metrics = HAMetricManager::instance().get_snapshot_runtime();
+    EXPECT_FALSE(metrics.enabled);
+    EXPECT_EQ(0u, metrics.snapshot_bytes);
+    EXPECT_EQ(HAMetricManager::SnapshotSkipReason::Disabled,
+              metrics.skip_reason);
     EXPECT_EQ(StandbyState::WATCHING, service.GetState());
     EXPECT_EQ(1u, service.GetMetadataCount());
     EXPECT_EQ(descriptor_.last_included_seq,
@@ -119,8 +131,6 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     ASSERT_EQ(1u, exported.size());
     EXPECT_EQ(kDefaultTestObjectKey, exported.front().key);
     EXPECT_EQ(kDefaultTestObjectSize, exported.front().metadata.size);
-    EXPECT_EQ(descriptor_.last_included_seq,
-              exported.front().metadata.last_sequence_id);
 }
 
 TEST_P(HotStandbySnapshotBootstrapTest,
@@ -188,6 +198,87 @@ TEST(StandbyControllerTest, OplogEnablementControlsReaderController) {
     EXPECT_EQ(ErrorCode::OK, unsupported->PromoteStandby());
 }
 
+TEST(StandbyControllerTest, BatchSnapshotDependencyFailureThrowsBeforeStart) {
+    ha::HABackendSpec spec{};
+    spec.type = ha::HABackendType::ETCD;
+    MasterServiceSupervisorConfig config;
+    config.enable_oplog = true;
+    config.enable_oplog_snapshot = true;
+    config.snapshot_object_store_type = "invalid";
+    EXPECT_THROW(ha::CreateStandbyController(spec, config), std::runtime_error);
+
+    // The same unused snapshot setting must not prevent pure OpLog startup.
+    config.enable_oplog_snapshot = false;
+    EXPECT_NO_THROW(ha::CreateStandbyController(spec, config));
+}
+
+TEST(StandbyControllerTest, BatchSnapshotIgnoresLegacyCatalogConfiguration) {
+    const auto path = MakeSnapshotTestTempDir("batch-controller-");
+    ScopedEnvVar local_path(kSnapshotLocalPathEnv, path);
+    ha::HABackendSpec spec{};
+    spec.type = ha::HABackendType::ETCD;
+    MasterServiceSupervisorConfig config;
+    config.enable_oplog = true;
+    config.enable_oplog_snapshot = true;
+    config.enable_snapshot_restore = true;
+    config.snapshot_object_store_type = "local";
+    config.snapshot_catalog_store_type = "invalid";
+    auto controller = ha::CreateStandbyController(spec, config);
+    EXPECT_NO_THROW(controller->StopStandby());
+    EXPECT_NO_THROW(controller->StopStandby());
+    controller.reset();
+    std::filesystem::remove_all(path);
+}
+
+TEST(StandbyControllerTest, BatchSnapshotRepeatedStartStopAndPromotion) {
+    const char* endpoints = std::getenv("MOONCAKE_TEST_ETCD_ENDPOINTS");
+    if (!endpoints) GTEST_SKIP() << "Run with the real-etcd snapshot smoke";
+    const auto path = MakeSnapshotTestTempDir("batch-lifecycle-");
+    ScopedEnvVar local_path(kSnapshotLocalPathEnv, path);
+    MasterServiceSupervisorConfig config;
+    config.cluster_id = "batch-lifecycle-" + UuidToString(generate_uuid());
+    config.enable_oplog = true;
+    config.enable_oplog_snapshot = true;
+    config.snapshot_object_store_type = "local";
+    config.ha_backend_connstring = endpoints;
+    config.snapshot_interval_seconds = 1;
+    ha::HABackendSpec spec{};
+    spec.type = ha::HABackendType::ETCD;
+    auto controller = ha::CreateStandbyController(spec, config);
+    for (int cycle = 0; cycle < 2; ++cycle) {
+        ASSERT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+        ASSERT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+        controller->StopStandby();
+        controller->StopStandby();
+    }
+    ASSERT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+    auto promoted = controller->PromoteStandbyAndExport();
+    ASSERT_TRUE(promoted.has_value());
+    EXPECT_NE(nullptr, promoted->metadata_store);
+    ASSERT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+    controller.reset();  // Destruction while both workers are running.
+    std::filesystem::remove_all(path);
+}
+
+TEST(StandbyControllerTest, HaWithoutOplogPromotesWithEmptyContext) {
+    ha::HABackendSpec spec{
+        .type = ha::HABackendType::ETCD,
+        .connstring = "http://localhost:2379",
+        .cluster_namespace = "ha-without-oplog-test",
+    };
+    MasterServiceSupervisorConfig config;
+    config.enable_oplog = false;
+
+    auto controller = ha::CreateStandbyController(spec, config);
+    ASSERT_EQ(ErrorCode::OK, controller->StartStandby(std::nullopt));
+
+    auto result = controller->PromoteStandbyAndExport();
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(0u, result->applied_seq_id);
+    EXPECT_TRUE(result->objects.empty());
+    EXPECT_TRUE(result->segments.empty());
+}
+
 TEST(StandbyControllerTest,
      PromoteStandbyAndExport_ReturnsErrorWhenNotStarted) {
     ha::HABackendSpec spec{
@@ -220,7 +311,7 @@ TEST(StandbyControllerTest,
 
 TEST_P(HotStandbySnapshotBootstrapTest,
        PromoteStandbyAndExport_SuccessWithSnapshot) {
-    PublishSnapshot();
+    PublishSnapshot(SnapshotMetadataFormat::kHardPinnedOnly);
 
     ha::HABackendSpec spec{
         .type = ha::HABackendType::UNKNOWN,
@@ -246,6 +337,7 @@ TEST_P(HotStandbySnapshotBootstrapTest,
     ASSERT_EQ(1u, ctx.objects.size());
     EXPECT_EQ(kDefaultTestObjectKey, ctx.objects[0].key);
     EXPECT_EQ(kDefaultTestObjectSize, ctx.objects[0].metadata.size);
+    EXPECT_TRUE(ctx.objects[0].metadata.hard_pinned.value_or(false));
     EXPECT_TRUE(ctx.segments.empty());
 }
 
diff --git a/mooncake-store/tests/ha/standby/standby_metadata_store_test.cpp b/mooncake-store/tests/ha/standby/standby_metadata_store_test.cpp
new file mode 100644
index 0000000000..450ecfe9de
--- /dev/null
+++ b/mooncake-store/tests/ha/standby/standby_metadata_store_test.cpp
@@ -0,0 +1,81 @@
+#include "ha/standby_metadata_store.h"
+
+#include <gtest/gtest.h>
+
+#include <set>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace mooncake::test {
+namespace {
+
+StandbyObjectMetadata MakeMetadata(uint64_t size) {
+    StandbyObjectMetadata metadata;
+    metadata.size = size;
+    return metadata;
+}
+
+}  // namespace
+
+static_assert(
+    std::is_move_constructible_v<StandbyMetadataStore::SnapshotCursor>);
+static_assert(
+    !std::is_copy_constructible_v<StandbyMetadataStore::SnapshotCursor>);
+
+TEST(StandbyMetadataStoreTest, EmptySnapshotCompletesWithoutObjects) {
+    StandbyMetadataStore store;
+    auto cursor = store.BeginSnapshotTraversal();
+    std::vector<StandbyObjectEntry> chunk;
+
+    ASSERT_TRUE(store.CopyNextSnapshotChunk(2, cursor, chunk));
+    EXPECT_TRUE(chunk.empty());
+    EXPECT_TRUE(cursor.done());
+}
+
+TEST(StandbyMetadataStoreTest, CopiesMultipleTenantsAcrossBoundedChunks) {
+    StandbyMetadataStore store;
+    ASSERT_TRUE(store.PutMetadata("tenant-a", "a1", MakeMetadata(1)));
+    ASSERT_TRUE(store.PutMetadata("tenant-a", "a2", MakeMetadata(2)));
+    ASSERT_TRUE(store.PutMetadata("tenant-b", "b1", MakeMetadata(3)));
+    ASSERT_TRUE(store.PutMetadata("tenant-b", "b2", MakeMetadata(4)));
+    ASSERT_TRUE(store.PutMetadata("tenant-c", "c1", MakeMetadata(5)));
+
+    auto cursor = store.BeginSnapshotTraversal();
+    std::set<std::pair<std::string, std::string>> copied;
+    while (!cursor.done()) {
+        std::vector<StandbyObjectEntry> chunk;
+        ASSERT_TRUE(store.CopyNextSnapshotChunk(2, cursor, chunk));
+        ASSERT_LE(chunk.size(), 2u);
+        for (const auto& entry : chunk) {
+            EXPECT_TRUE(copied.emplace(entry.tenant_id, entry.key).second);
+        }
+    }
+
+    EXPECT_EQ(5u, copied.size());
+    EXPECT_EQ(5u, store.GetKeyCount());
+}
+
+TEST(StandbyMetadataStoreTest, RejectsZeroSizedChunkWithoutAdvancing) {
+    StandbyMetadataStore store;
+    ASSERT_TRUE(store.PutMetadata("tenant", "key", MakeMetadata(1)));
+    auto cursor = store.BeginSnapshotTraversal();
+    std::vector<StandbyObjectEntry> chunk;
+
+    EXPECT_FALSE(store.CopyNextSnapshotChunk(0, cursor, chunk));
+    EXPECT_TRUE(chunk.empty());
+    EXPECT_FALSE(cursor.done());
+}
+
+TEST(StandbyMetadataStoreTest, RestoreInsertRejectsDuplicateWithoutOverwrite) {
+    StandbyMetadataStore store;
+    ASSERT_TRUE(store.RestoreMetadata("tenant", "key", MakeMetadata(1)));
+
+    EXPECT_FALSE(store.RestoreMetadata("tenant", "key", MakeMetadata(2)));
+    auto restored = store.GetMetadata("tenant", "key");
+    ASSERT_TRUE(restored.has_value());
+    EXPECT_EQ(1u, restored->size);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ha_cluster_namespace_config_test.cpp b/mooncake-store/tests/ha_cluster_namespace_config_test.cpp
new file mode 100644
index 0000000000..931e683960
--- /dev/null
+++ b/mooncake-store/tests/ha_cluster_namespace_config_test.cpp
@@ -0,0 +1,54 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "../src/config/ha_cluster_namespace_config.h"
+
+namespace mooncake {
+namespace {
+
+class HaClusterNamespaceConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* original = std::getenv("MC_STORE_CLUSTER_ID")) {
+            original_ = original;
+        }
+        ASSERT_EQ(unsetenv("MC_STORE_CLUSTER_ID"), 0);
+    }
+
+    void TearDown() override {
+        if (original_) {
+            EXPECT_EQ(setenv("MC_STORE_CLUSTER_ID", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_STORE_CLUSTER_ID"), 0);
+        }
+    }
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST_F(HaClusterNamespaceConfigTest, FallsBackWhenUnsetOrEmpty) {
+    EXPECT_EQ(HaClusterNamespaceConfig::FromEnvironment().cluster_namespace,
+              "mooncake_cluster");
+
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "", 1), 0);
+    EXPECT_EQ(HaClusterNamespaceConfig::FromEnvironment().cluster_namespace,
+              "mooncake_cluster");
+}
+
+TEST_F(HaClusterNamespaceConfigTest, PreservesValueAndReadsEachConstruction) {
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "  team a  ", 1), 0);
+    const auto first = HaClusterNamespaceConfig::FromEnvironment();
+    EXPECT_EQ(first.cluster_namespace, "  team a  ");
+
+    ASSERT_EQ(setenv("MC_STORE_CLUSTER_ID", "team b", 1), 0);
+    EXPECT_EQ(HaClusterNamespaceConfig::FromEnvironment().cluster_namespace,
+              "team b");
+    EXPECT_EQ(first.cluster_namespace, "  team a  ");
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/health_check_test.cpp b/mooncake-store/tests/health_check_test.cpp
index 7a059d7355..018674585f 100644
--- a/mooncake-store/tests/health_check_test.cpp
+++ b/mooncake-store/tests/health_check_test.cpp
@@ -11,9 +11,11 @@
 #include <ylt/coro_http/coro_http_client.hpp>
 
 #include "client_service.h"
+#include "common/network.h"
+#include "default_config.h"
 #include "real_client.h"
 #include "test_server_helpers.h"
-#include "default_config.h"
+#include "version.h"
 
 DEFINE_string(protocol, "tcp", "Transfer protocol: rdma|tcp");
 DEFINE_string(device_name, "", "Device name to use, valid if protocol=rdma");
@@ -241,5 +243,26 @@ TEST_F(HealthCheckTest, MetricsEndpointsReturnCorrectData) {
     master_.Stop();
 }
 
+// Test 8: HTTP /version returns 200 with version information
+TEST_F(HealthCheckTest, VersionEndpointReturnsVersion) {
+    int http_port = getFreeTcpPort();
+    FLAGS_http_port = http_port;
+    ASSERT_EQ(StartMasterAndSetupClient(18930), 0) << "setup_real failed";
+
+    std::this_thread::sleep_for(std::chrono::seconds(2));
+
+    auto resp = fetch_url(http_port, "/version");
+    EXPECT_EQ(resp.http_status, 200);
+    EXPECT_NE(resp.body.find("\"version\""), std::string::npos);
+    EXPECT_NE(resp.body.find("\"display_version\""), std::string::npos);
+    EXPECT_NE(resp.body.find(GetMooncakeStoreVersion()), std::string::npos)
+        << "store version missing from /version response";
+    EXPECT_NE(resp.body.find(MOONCAKE_DISPLAY_VERSION), std::string::npos)
+        << "display version missing from /version response";
+
+    py_client_->tearDownAll();
+    master_.Stop();
+}
+
 }  // namespace testing
 }  // namespace mooncake
diff --git a/mooncake-store/tests/host_port_fix_test.cpp b/mooncake-store/tests/host_port_fix_test.cpp
index 6609ef9e7d..75ff3291ce 100644
--- a/mooncake-store/tests/host_port_fix_test.cpp
+++ b/mooncake-store/tests/host_port_fix_test.cpp
@@ -3,7 +3,7 @@
 #include <ylt/coro_rpc/coro_rpc_server.hpp>
 
 #include "common.h"
-#include "utils.h"
+#include "common/network.h"
 
 namespace mooncake {
 namespace {
diff --git a/mooncake-store/tests/http_metadata_server_test.cpp b/mooncake-store/tests/http_metadata_server_test.cpp
index 26b3726b9f..41de266b55 100644
--- a/mooncake-store/tests/http_metadata_server_test.cpp
+++ b/mooncake-store/tests/http_metadata_server_test.cpp
@@ -8,7 +8,7 @@
 #include <ylt/coro_http/coro_http_client.hpp>
 
 #include "http_metadata_server.h"
-#include "utils.h"
+#include "common/network.h"
 
 namespace mooncake::testing {
 
diff --git a/mooncake-store/tests/hugepage_config_test.cpp b/mooncake-store/tests/hugepage_config_test.cpp
new file mode 100644
index 0000000000..fb3a26a26a
--- /dev/null
+++ b/mooncake-store/tests/hugepage_config_test.cpp
@@ -0,0 +1,149 @@
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "../src/config/hugepage_config.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        EXPECT_EQ(unsetenv(name), 0);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv(name_.c_str(), original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(name_.c_str()), 0);
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) {
+        ASSERT_EQ(setenv(name_.c_str(), value, 1), 0);
+    }
+
+    void Unset() { ASSERT_EQ(unsetenv(name_.c_str()), 0); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+class HugepageConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        FLAGS_logtostderr = 1;
+        FLAGS_minloglevel = google::WARNING;
+    }
+
+    ScopedEnvVar use_hugepage{"MC_STORE_USE_HUGEPAGE"};
+    ScopedEnvVar hugepage_size{"MC_STORE_HUGEPAGE_SIZE"};
+};
+
+TEST_F(HugepageConfigTest, UnsetDisablesHugepagesAndSkipsSizeValidation) {
+    hugepage_size.Set("invalid");
+    ::testing::internal::CaptureStderr();
+
+    const HugepageConfig config = HugepageConfig::FromEnvironment();
+
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(config.page_size, 0);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+    EXPECT_EQ(logs.find("Invalid MC_STORE_HUGEPAGE_SIZE"), std::string::npos);
+}
+
+TEST_F(HugepageConfigTest, AnyPresentEnableValueRequestsHugepages) {
+    for (const char* value : {"", "0"}) {
+        SCOPED_TRACE(value);
+        use_hugepage.Set(value);
+
+        EXPECT_TRUE(HugepageConfig::IsEnabledFromEnvironment());
+        const HugepageConfig config = HugepageConfig::FromEnvironment();
+        EXPECT_TRUE(config.enabled);
+        EXPECT_EQ(config.page_size, 2ULL * 1024 * 1024);
+    }
+}
+
+TEST_F(HugepageConfigTest, UnsetSizeDefaultsTo2Mb) {
+    use_hugepage.Set("1");
+    hugepage_size.Unset();
+
+    const HugepageConfig config = HugepageConfig::FromEnvironment();
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.page_size, 2ULL * 1024 * 1024);
+}
+
+TEST_F(HugepageConfigTest, AcceptsLegacyByteSizeSyntaxForSupportedSizes) {
+    struct Case {
+        const char* value;
+        size_t expected;
+    };
+    const Case cases[] = {
+        {"2MB", 2ULL * 1024 * 1024},     {"512MB", 512ULL * 1024 * 1024},
+        {"1GB", 1024ULL * 1024 * 1024},  {" 2 mb ", 2ULL * 1024 * 1024},
+        {"+512M", 512ULL * 1024 * 1024}, {"0.5GB", 512ULL * 1024 * 1024},
+        {"2048K", 2ULL * 1024 * 1024},
+    };
+
+    use_hugepage.Set("1");
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        hugepage_size.Set(entry.value);
+
+        const HugepageConfig config = HugepageConfig::FromEnvironment();
+
+        EXPECT_TRUE(config.enabled);
+        EXPECT_EQ(config.page_size, entry.expected);
+    }
+}
+
+TEST_F(HugepageConfigTest, InvalidSizesWarnAndFallBackTo2Mb) {
+    use_hugepage.Set("1");
+    for (const char* value :
+         {"", " ", "2MiB", "2MBjunk", "1e999", "infinite", "256MB", "1.5GB"}) {
+        SCOPED_TRACE(value);
+        hugepage_size.Set(value);
+        ::testing::internal::CaptureStderr();
+
+        const HugepageConfig config = HugepageConfig::FromEnvironment();
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_TRUE(config.enabled);
+        EXPECT_EQ(config.page_size, 2ULL * 1024 * 1024);
+        EXPECT_NE(logs.find("Invalid MC_STORE_HUGEPAGE_SIZE='"),
+                  std::string::npos);
+        EXPECT_NE(logs.find("Supported: 2MB, 512MB, 1GB. Fallback to 2MB."),
+                  std::string::npos);
+    }
+}
+
+TEST_F(HugepageConfigTest, EachCallReadsCurrentEnvironment) {
+    use_hugepage.Set("1");
+    hugepage_size.Set("2MB");
+    EXPECT_EQ(HugepageConfig::FromEnvironment().page_size, 2ULL * 1024 * 1024);
+
+    hugepage_size.Set("1GB");
+    EXPECT_EQ(HugepageConfig::FromEnvironment().page_size,
+              1024ULL * 1024 * 1024);
+
+    use_hugepage.Unset();
+    EXPECT_FALSE(HugepageConfig::IsEnabledFromEnvironment());
+    EXPECT_EQ(HugepageConfig::FromEnvironment().page_size, 0);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/hugepage_size_env_test.cpp b/mooncake-store/tests/hugepage_size_env_test.cpp
new file mode 100644
index 0000000000..455b34a563
--- /dev/null
+++ b/mooncake-store/tests/hugepage_size_env_test.cpp
@@ -0,0 +1,102 @@
+#include "common/client_buffer_allocation.h"
+
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        EXPECT_EQ(unsetenv(name), 0);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv(name_.c_str(), original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(name_.c_str()), 0);
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) {
+        ASSERT_EQ(setenv(name_.c_str(), value, 1), 0);
+    }
+
+    void Unset() { ASSERT_EQ(unsetenv(name_.c_str()), 0); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+class HugepageSizeEnvTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        FLAGS_logtostderr = 1;
+        FLAGS_minloglevel = google::WARNING;
+    }
+
+    ScopedEnvVar use_hugepage{"MC_STORE_USE_HUGEPAGE"};
+    ScopedEnvVar hugepage_size{"MC_STORE_HUGEPAGE_SIZE"};
+};
+
+TEST_F(HugepageSizeEnvTest, AppliesMmapAndMemfdFlagsForEachSupportedSize) {
+    struct Case {
+        const char* value;
+        unsigned int mmap_size_flag;
+        unsigned int memfd_size_flag;
+    };
+    const Case cases[] = {
+        {"2MB", MAP_HUGE_2MB, MFD_HUGE_2MB},
+        {"512MB", MAP_HUGE_512MB, MFD_HUGE_512MB},
+        {"1GB", MAP_HUGE_1GB, MFD_HUGE_1GB},
+    };
+
+    use_hugepage.Set("1");
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        hugepage_size.Set(entry.value);
+
+        unsigned int mmap_flags = MAP_PRIVATE;
+        EXPECT_NE(get_hugepage_size_from_env(&mmap_flags), 0);
+        EXPECT_EQ(mmap_flags, MAP_PRIVATE | MAP_HUGETLB | entry.mmap_size_flag);
+
+        unsigned int memfd_flags = MFD_CLOEXEC;
+        EXPECT_NE(get_hugepage_size_from_env(&memfd_flags, true), 0);
+        EXPECT_EQ(memfd_flags,
+                  MFD_CLOEXEC | MFD_HUGETLB | entry.memfd_size_flag);
+    }
+}
+
+TEST_F(HugepageSizeEnvTest, LogsSelectedSizeOnlyWhenFlagsAreRequested) {
+    use_hugepage.Set("1");
+    hugepage_size.Set("512MB");
+
+    ::testing::internal::CaptureStderr();
+    EXPECT_EQ(get_hugepage_size_from_env(), 512ULL * 1024 * 1024);
+    std::string logs = ::testing::internal::GetCapturedStderr();
+    EXPECT_EQ(logs.find("Using hugepage size"), std::string::npos);
+
+    FLAGS_minloglevel = google::INFO;
+    ::testing::internal::CaptureStderr();
+    unsigned int flags = 0;
+    EXPECT_EQ(get_hugepage_size_from_env(&flags), 512ULL * 1024 * 1024);
+    logs = ::testing::internal::GetCapturedStderr();
+    EXPECT_NE(logs.find("Using hugepage size: 512MB"), std::string::npos);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/kv_event_publisher_test.cpp b/mooncake-store/tests/kv_event_publisher_test.cpp
index 9230e21aeb..e3dfe7f51f 100644
--- a/mooncake-store/tests/kv_event_publisher_test.cpp
+++ b/mooncake-store/tests/kv_event_publisher_test.cpp
@@ -7,7 +7,6 @@
 #include <unistd.h>
 #include <vector>
 
-#include "kv_event/key_util.h"
 #include "kv_event/kv_event_publisher.h"
 
 #if defined(MOONCAKE_ENABLE_KV_EVENTS) && MOONCAKE_ENABLE_KV_EVENTS
@@ -18,16 +17,6 @@
 namespace mooncake {
 namespace {
 
-TEST(KvEventKeyUtilTest, ParseSeqHashFromObjectKey) {
-    EXPECT_EQ(ParseSeqHashFromObjectKey("12345"), 12345u);
-    EXPECT_EQ(ParseSeqHashFromObjectKey("0x2a"), 42u);
-    EXPECT_EQ(ParseSeqHashFromObjectKey("0XFF"), 255u);
-    EXPECT_FALSE(ParseSeqHashFromObjectKey("").has_value());
-    EXPECT_FALSE(ParseSeqHashFromObjectKey("not-a-hash").has_value());
-    EXPECT_FALSE(ParseSeqHashFromObjectKey("123abc").has_value());
-    EXPECT_EQ(KvEventPublisher::ParseSeqHashFromObjectKey("99"), 99u);
-}
-
 TEST(KvEventPublisherTest, DisabledPublisherIsNoop) {
     KvEventConfig config;
     config.enabled = false;
@@ -35,6 +24,7 @@ TEST(KvEventPublisherTest, DisabledPublisherIsNoop) {
     EXPECT_FALSE(publisher.enabled());
     publisher.PublishStored("42", "cpu");
     publisher.PublishRemoved("42", "cpu");
+    publisher.PublishCleared("tenant-a");
     const auto stats = publisher.GetStats();
     EXPECT_EQ(stats.published_events, 0u);
     EXPECT_EQ(stats.dropped_events, 0u);
@@ -73,6 +63,123 @@ bool ReceiveZmqMultipart(void* socket, std::vector<std::string>& frames) {
     return true;
 }
 
+bool ReceivePayload(void* socket, msgpack::object_handle* payload) {
+    std::vector<std::string> frames;
+    if (!ReceiveZmqMultipart(socket, frames) || frames.size() != 3) {
+        return false;
+    }
+    *payload = msgpack::unpack(frames[2].data(), frames[2].size());
+    return true;
+}
+
+const msgpack::object* FindMapValue(const msgpack::object& map,
+                                    const std::string& field) {
+    if (map.type != msgpack::type::MAP) {
+        return nullptr;
+    }
+    for (uint32_t i = 0; i < map.via.map.size; ++i) {
+        const auto& key = map.via.map.ptr[i].key;
+        if (key.type == msgpack::type::STR &&
+            std::string(key.via.str.ptr, key.via.str.size) == field) {
+            return &map.via.map.ptr[i].val;
+        }
+    }
+    return nullptr;
+}
+
+std::string MsgpackString(const msgpack::object& value) {
+    return value.type == msgpack::type::STR
+               ? std::string(value.via.str.ptr, value.via.str.size)
+               : std::string{};
+}
+
+const msgpack::object& FirstEvent(const msgpack::object_handle& payload) {
+    return payload.get().via.array.ptr[1].via.array.ptr[0];
+}
+
+void ExpectObjectEvent(const msgpack::object& event, const std::string& type,
+                       const std::string& object_key) {
+    ASSERT_EQ(event.type, msgpack::type::MAP);
+    const auto* event_type = FindMapValue(event, "event_type");
+    const auto* actual_key = FindMapValue(event, "object_key");
+    const auto* seq_hashes = FindMapValue(event, "seq_hashes");
+    ASSERT_NE(event_type, nullptr);
+    ASSERT_NE(actual_key, nullptr);
+    ASSERT_NE(seq_hashes, nullptr);
+    EXPECT_EQ(MsgpackString(*event_type), type);
+    EXPECT_EQ(MsgpackString(*actual_key), object_key);
+    ASSERT_EQ(seq_hashes->type, msgpack::type::ARRAY);
+    EXPECT_EQ(seq_hashes->via.array.size, 0u);
+    EXPECT_EQ(FindMapValue(event, "connector_block_hash"), nullptr);
+    EXPECT_EQ(FindMapValue(event, "cache_prefix"), nullptr);
+}
+
+KvEventConfig MakeEnabledConfig(const std::string& endpoint) {
+    KvEventConfig config;
+    config.enabled = true;
+    config.bind_endpoint = endpoint;
+    config.backend_id = "mooncake-test";
+    config.emit_object_key = true;
+    return config;
+}
+
+uint32_t EventCount(const msgpack::object_handle& payload) {
+    return payload.get().via.array.ptr[1].via.array.size;
+}
+
+const msgpack::object& EventAt(const msgpack::object_handle& payload,
+                               uint32_t index) {
+    return payload.get().via.array.ptr[1].via.array.ptr[index];
+}
+
+// Confirms the publisher emitted nothing more, using a short receive timeout so
+// negative assertions do not stall the suite.
+bool ExpectNoMessage(void* socket) {
+    int short_timeout_ms = 200;
+    zmq_setsockopt(socket, ZMQ_RCVTIMEO, &short_timeout_ms,
+                   sizeof(short_timeout_ms));
+    std::vector<std::string> frames;
+    const bool received = ReceiveZmqMultipart(socket, frames);
+    int restore_timeout_ms = 2000;
+    zmq_setsockopt(socket, ZMQ_RCVTIMEO, &restore_timeout_ms,
+                   sizeof(restore_timeout_ms));
+    return !received;
+}
+
+// Owns the SUB socket lifetime so each test body stays focused on assertions.
+struct ScopedSubscriber {
+    void* ctx{nullptr};
+    void* sub{nullptr};
+
+    bool Connect(const std::string& endpoint, int timeout_ms = 2000) {
+        ctx = zmq_ctx_new();
+        if (ctx == nullptr) {
+            return false;
+        }
+        sub = zmq_socket(ctx, ZMQ_SUB);
+        if (sub == nullptr) {
+            return false;
+        }
+        if (zmq_setsockopt(sub, ZMQ_RCVTIMEO, &timeout_ms,
+                           sizeof(timeout_ms)) != 0 ||
+            zmq_connect(sub, endpoint.c_str()) != 0 ||
+            zmq_setsockopt(sub, ZMQ_SUBSCRIBE, "", 0) != 0) {
+            return false;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(100));
+        return true;
+    }
+
+    ~ScopedSubscriber() {
+        if (sub != nullptr) {
+            zmq_close(sub);
+        }
+        if (ctx != nullptr) {
+            zmq_ctx_destroy(ctx);
+        }
+    }
+};
+
 }  // namespace
 
 TEST(KvEventPublisherTest, PublishesSglangObjectKeyOverZmq) {
@@ -87,6 +194,11 @@ TEST(KvEventPublisherTest, PublishesSglangObjectKeyOverZmq) {
     config.enabled = true;
     config.bind_endpoint = endpoint;
     config.backend_id = "mooncake-test";
+    config.model_name = "configured-model";
+    config.block_size = 128;
+    config.additional_salt = "salt-a";
+    config.lora_name = "adapter-a";
+    config.dp_rank = 5;
     config.emit_object_key = true;
     config.emit_legacy_compat_fields = true;
     config.queue_capacity = 64;
@@ -97,97 +209,188 @@ TEST(KvEventPublisherTest, PublishesSglangObjectKeyOverZmq) {
     ASSERT_NE(ctx, nullptr);
     void* sub = zmq_socket(ctx, ZMQ_SUB);
     ASSERT_NE(sub, nullptr);
+    const int timeout_ms = 2000;
+    ASSERT_EQ(
+        zmq_setsockopt(sub, ZMQ_RCVTIMEO, &timeout_ms, sizeof(timeout_ms)), 0);
     ASSERT_EQ(zmq_connect(sub, endpoint.c_str()), 0);
     ASSERT_EQ(zmq_setsockopt(sub, ZMQ_SUBSCRIBE, "", 0), 0);
-
-    // Allow SUB connect before first publish propagates.
     std::this_thread::sleep_for(std::chrono::milliseconds(100));
 
-    publisher.PublishStored(object_key, "cpu", TenantId("tenant-a"), group_id);
+    publisher.PublishStored(object_key, "cpu", "tenant-a", group_id);
+    msgpack::object_handle payload;
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ASSERT_EQ(payload.get().type, msgpack::type::ARRAY);
+    ASSERT_EQ(payload.get().via.array.size, 3u);
+    ExpectObjectEvent(FirstEvent(payload), "stored", object_key);
+    const auto& event = FirstEvent(payload);
+    EXPECT_EQ(MsgpackString(*FindMapValue(event, "group_id")), group_id);
+    EXPECT_EQ(MsgpackString(*FindMapValue(event, "backend_id")),
+              "mooncake-test");
+    EXPECT_EQ(MsgpackString(*FindMapValue(event, "tenant_id")), "tenant-a");
+    EXPECT_EQ(FindMapValue(event, "model_name")->as<std::string>(),
+              "configured-model");
+    EXPECT_EQ(FindMapValue(event, "block_size")->as<uint32_t>(), 128u);
+    EXPECT_EQ(FindMapValue(event, "dp_rank")->as<uint32_t>(), 5u);
 
-    std::vector<std::string> frames;
-    ASSERT_TRUE(ReceiveZmqMultipart(sub, frames)) << zmq_strerror(zmq_errno());
-    ASSERT_EQ(frames.size(), 3u);
-    EXPECT_TRUE(frames[0].empty());
-    ASSERT_EQ(frames[1].size(), sizeof(uint64_t));
-
-    const auto object_handle =
-        msgpack::unpack(frames[2].data(), frames[2].size());
-    const auto& root = object_handle.get();
-    ASSERT_EQ(root.type, msgpack::type::ARRAY);
-    ASSERT_EQ(root.via.array.size, 3u);
-
-    const auto& events = root.via.array.ptr[1];
-    ASSERT_EQ(events.type, msgpack::type::ARRAY);
-    ASSERT_EQ(events.via.array.size, 1u);
-
-    const auto& event = events.via.array.ptr[0];
-    ASSERT_EQ(event.type, msgpack::type::MAP);
+    publisher.PublishRemoved(object_key, "cpu", "tenant-a", group_id);
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "removed", object_key);
 
-    bool has_object_key = false;
-    bool has_group_id = false;
-    bool has_empty_seq_hashes = false;
-    std::string event_type;
-    std::string backend_id;
-    std::string tenant_id;
-    for (uint32_t i = 0; i < event.via.map.size; ++i) {
-        const auto& key = event.via.map.ptr[i].key;
-        const auto& val = event.via.map.ptr[i].val;
-        ASSERT_EQ(key.type, msgpack::type::STR);
-        const std::string field(key.via.str.ptr, key.via.str.size);
-        if (field == "object_key") {
-            ASSERT_EQ(val.type, msgpack::type::STR);
-            EXPECT_EQ(std::string(val.via.str.ptr, val.via.str.size),
-                      object_key);
-            has_object_key = true;
-        } else if (field == "group_id") {
-            ASSERT_EQ(val.type, msgpack::type::STR);
-            EXPECT_EQ(std::string(val.via.str.ptr, val.via.str.size), group_id);
-            has_group_id = true;
-        } else if (field == "seq_hashes") {
-            ASSERT_EQ(val.type, msgpack::type::ARRAY);
-            EXPECT_EQ(val.via.array.size, 0u);
-            has_empty_seq_hashes = true;
-        } else if (field == "event_type") {
-            ASSERT_EQ(val.type, msgpack::type::STR);
-            event_type = std::string(val.via.str.ptr, val.via.str.size);
-        } else if (field == "backend_id") {
-            ASSERT_EQ(val.type, msgpack::type::STR);
-            backend_id = std::string(val.via.str.ptr, val.via.str.size);
-        } else if (field == "tenant_id") {
-            ASSERT_EQ(val.type, msgpack::type::STR);
-            tenant_id = std::string(val.via.str.ptr, val.via.str.size);
-        }
-    }
-
-    EXPECT_EQ(event_type, "stored");
-    EXPECT_EQ(backend_id, "mooncake-test");
-    EXPECT_EQ(tenant_id, "tenant-a");
-    EXPECT_TRUE(has_object_key);
-    EXPECT_TRUE(has_group_id);
-    EXPECT_TRUE(has_empty_seq_hashes);
+    publisher.PublishCleared("tenant-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    const auto& cleared = FirstEvent(payload);
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "event_type")), "cleared");
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "tenant_id")), "tenant-a");
+    EXPECT_EQ(FindMapValue(cleared, "object_key"), nullptr);
 
-    // Wait for async worker to finish publishing.
     for (int i = 0; i < 50; ++i) {
         const auto stats = publisher.GetStats();
-        if (stats.published_events == 1 && stats.published_batches == 1) {
-            EXPECT_EQ(stats.dropped_events, 0u);
+        if (stats.published_events == 3 && stats.published_batches == 3) {
             break;
         }
         std::this_thread::sleep_for(std::chrono::milliseconds(20));
     }
     const auto stats = publisher.GetStats();
-    EXPECT_EQ(stats.published_events, 1u);
-    EXPECT_EQ(stats.published_batches, 1u);
+    EXPECT_EQ(stats.published_events, 3u);
+    EXPECT_EQ(stats.published_batches, 3u);
     EXPECT_EQ(stats.dropped_events, 0u);
 
     zmq_close(sub);
     zmq_ctx_destroy(ctx);
 }
 
-TEST(KvEventPublisherTest, DropsOldestWhenQueueFull) {
+TEST(KvEventPublisherTest, PublishesStoreMetadataAndMediumDelta) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventConfig config;
+    config.enabled = true;
+    config.bind_endpoint = endpoint;
+    config.backend_id = "mooncake-test";
+    config.model_name = "model-a";
+    config.block_size = 64;
+    config.additional_salt = "salt-a";
+    config.lora_name = "adapter-a";
+    config.dp_rank = 4;
+    config.emit_object_key = true;
+    config.emit_legacy_compat_fields = true;
+    KvEventPublisher publisher(config);
+    ASSERT_TRUE(publisher.enabled());
+
+    void* ctx = zmq_ctx_new();
+    ASSERT_NE(ctx, nullptr);
+    void* sub = zmq_socket(ctx, ZMQ_SUB);
+    ASSERT_NE(sub, nullptr);
+    const int timeout_ms = 2000;
+    ASSERT_EQ(
+        zmq_setsockopt(sub, ZMQ_RCVTIMEO, &timeout_ms, sizeof(timeout_ms)), 0);
+    ASSERT_EQ(zmq_connect(sub, endpoint.c_str()), 0);
+    ASSERT_EQ(zmq_setsockopt(sub, ZMQ_SUBSCRIBE, "", 0), 0);
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+    const std::string object_key =
+        "deployment-a@model-a@tp_rank:2@pcp1@dcp0@pp_rank:3@group:7@"
+        "0123456789abcdef000000000000002a";
+    msgpack::object_handle payload;
+    publisher.PublishCommitted(object_key, {"cpu"}, "tenant-a", "group-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "stored", object_key);
+
+    publisher.PublishCommitted(object_key, {"cpu"}, "tenant-a", "group-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "stored", object_key);
+
+    publisher.SyncObjectState(object_key, {}, "tenant-a", "group-a", {"cpu"});
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "removed", object_key);
+
+    publisher.PublishCommitted(object_key, {"cpu"}, "tenant-a", "group-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "stored", object_key);
+
+    publisher.SyncObjectState(object_key, {"disk"}, "tenant-a", "group-a",
+                              {"cpu"});
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ASSERT_EQ(payload.get().via.array.ptr[1].via.array.size, 2u);
+    ExpectObjectEvent(payload.get().via.array.ptr[1].via.array.ptr[0],
+                      "removed", object_key);
+    ExpectObjectEvent(payload.get().via.array.ptr[1].via.array.ptr[1], "stored",
+                      object_key);
+
+    publisher.PublishObjectRemoved(object_key, "tenant-a", "group-a", {"disk"});
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    ExpectObjectEvent(FirstEvent(payload), "removed", object_key);
+
+    zmq_close(sub);
+    zmq_ctx_destroy(ctx);
+}
+
+TEST(KvEventPublisherTest, ClearIsTenantScoped) {
     const std::string endpoint = MakeIpcEndpoint();
+    KvEventConfig config;
+    config.enabled = true;
+    config.bind_endpoint = endpoint;
+    config.backend_id = "mooncake-test";
+    config.model_name = "model-a";
+    config.block_size = 64;
+    KvEventPublisher publisher(config);
+    ASSERT_TRUE(publisher.enabled());
+
+    void* ctx = zmq_ctx_new();
+    ASSERT_NE(ctx, nullptr);
+    void* sub = zmq_socket(ctx, ZMQ_SUB);
+    ASSERT_NE(sub, nullptr);
+    const int timeout_ms = 2000;
+    ASSERT_EQ(
+        zmq_setsockopt(sub, ZMQ_RCVTIMEO, &timeout_ms, sizeof(timeout_ms)), 0);
+    ASSERT_EQ(zmq_connect(sub, endpoint.c_str()), 0);
+    ASSERT_EQ(zmq_setsockopt(sub, ZMQ_SUBSCRIBE, "", 0), 0);
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+    msgpack::object_handle payload;
+    publisher.PublishStored("tenant-a-key", "cpu", "tenant-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    publisher.PublishStored("tenant-b-key", "cpu", "tenant-b");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    publisher.PublishCleared("tenant-a");
+    ASSERT_TRUE(ReceivePayload(sub, &payload));
+    const auto& event = FirstEvent(payload);
+    EXPECT_EQ(MsgpackString(*FindMapValue(event, "event_type")), "cleared");
+    EXPECT_EQ(MsgpackString(*FindMapValue(event, "tenant_id")), "tenant-a");
+
+    zmq_close(sub);
+    zmq_ctx_destroy(ctx);
+}
+
+TEST(KvEventPublisherTest, DisabledObjectKeySkipsObjectEventsButKeepsClear) {
+    KvEventConfig config;
+    config.enabled = true;
+    config.bind_endpoint = MakeIpcEndpoint();
+    config.backend_id = "mooncake-test";
+    config.emit_object_key = false;
+    KvEventPublisher publisher(config);
+    ASSERT_TRUE(publisher.enabled());
 
+    publisher.PublishStored("object-a", "cpu", "tenant-a");
+    publisher.PublishRemoved("object-a", "cpu", "tenant-a");
+    publisher.PublishCleared("tenant-a");
+
+    for (int i = 0; i < 50; ++i) {
+        const auto stats = publisher.GetStats();
+        if (stats.skipped_keyless_events == 2 && stats.published_events == 1) {
+            EXPECT_EQ(stats.published_batches, 1u);
+            EXPECT_EQ(stats.dropped_events, 0u);
+            return;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    const auto stats = publisher.GetStats();
+    FAIL() << "unexpected publisher stats: skipped="
+           << stats.skipped_keyless_events
+           << " published_events=" << stats.published_events
+           << " published_batches=" << stats.published_batches;
+}
+
+TEST(KvEventPublisherTest, DropsOldestWhenQueueFull) {
+    const std::string endpoint = MakeIpcEndpoint();
     KvEventConfig config;
     config.enabled = true;
     config.bind_endpoint = endpoint;
@@ -212,6 +415,203 @@ TEST(KvEventPublisherTest, DropsOldestWhenQueueFull) {
     FAIL() << "expected dropped_events after queue overflow";
 }
 
+// Removal is driven entirely by the caller's previous-media set, in sorted
+// order so a multi-medium object produces a deterministic event sequence.
+TEST(KvEventPublisherTest, RemovalEmitsEveryMediumFromCaller) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    msgpack::object_handle payload;
+    publisher.PublishObjectRemoved("object-a", "tenant-a", "group-a",
+                                   {"disk", "cpu"});
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 2u);
+    ExpectObjectEvent(EventAt(payload, 0), "removed", "object-a");
+    ExpectObjectEvent(EventAt(payload, 1), "removed", "object-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 0), "medium")),
+              "cpu");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 1), "medium")),
+              "disk");
+}
+
+// A medium that survives the mutation must not be announced as removed, even
+// though the caller lists it as previously present. This is what keeps a
+// partial eviction from retracting the tier that still holds a replica.
+TEST(KvEventPublisherTest, SurvivingMediumIsNotRemoved) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    msgpack::object_handle payload;
+    publisher.SyncObjectState("object-a", {"cpu"}, "tenant-a", "group-a",
+                              {"cpu", "disk"});
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 1u);
+    ExpectObjectEvent(EventAt(payload, 0), "removed", "object-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 0), "medium")),
+              "disk");
+}
+
+TEST(KvEventPublisherTest, RemovesBothMediaAfterStoredOnCpuAndDisk) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    msgpack::object_handle payload;
+    publisher.PublishCommitted("object-a", {"cpu", "disk"}, "tenant-a",
+                               "group-a");
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 2u);
+    ExpectObjectEvent(EventAt(payload, 0), "stored", "object-a");
+    ExpectObjectEvent(EventAt(payload, 1), "stored", "object-a");
+
+    publisher.PublishObjectRemoved("object-a", "tenant-a", "group-a",
+                                   {"cpu", "disk"});
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 2u);
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 0), "medium")),
+              "cpu");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 1), "medium")),
+              "disk");
+}
+
+// Covers restart and snapshot-restore: metadata can name media the publisher
+// A mutation that left the medium set alone carries no availability news, so it
+// must stay off the wire. This is what separates SyncObjectState from a commit,
+// which always re-announces.
+TEST(KvEventPublisherTest, SyncWithUnchangedMediaEmitsNothing) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    publisher.SyncObjectState("object-a", {"cpu", "disk"}, "tenant-a",
+                              "group-a", {"disk", "cpu"});
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+}
+
+// A medium that appears during an internal mutation, such as an offload landing
+// on disk, has to be announced as stored even though no commit ran.
+TEST(KvEventPublisherTest, SyncAnnouncesNewlyAppearedMedium) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    msgpack::object_handle payload;
+    publisher.SyncObjectState("object-a", {"disk"}, "tenant-a", "group-a",
+                              {"cpu"});
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 2u);
+    ExpectObjectEvent(EventAt(payload, 0), "removed", "object-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 0), "medium")),
+              "cpu");
+    ExpectObjectEvent(EventAt(payload, 1), "stored", "object-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 1), "medium")),
+              "disk");
+}
+
+TEST(KvEventPublisherTest, DisabledObjectKeyCountsSkippedObjectEvents) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventConfig config = MakeEnabledConfig(endpoint);
+    config.emit_object_key = false;
+    KvEventPublisher publisher(config);
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    publisher.PublishCommitted("object-a", {"cpu"}, "tenant-a", "group-a");
+    publisher.PublishObjectRemoved("object-a", "tenant-a", "group-a", {"cpu"});
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+
+    // Clear carries no object key, so it survives the filter.
+    msgpack::object_handle payload;
+    publisher.PublishCleared("tenant-a");
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 1u);
+    EXPECT_EQ(MsgpackString(*FindMapValue(EventAt(payload, 0), "event_type")),
+              "cleared");
+
+    const auto stats = publisher.GetStats();
+    EXPECT_GT(stats.skipped_keyless_events, 0u);
+}
+
+TEST(KvEventPublisherTest, ClearedEventIsEnvelopeOnlyWithNilMedium) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventConfig config = MakeEnabledConfig(endpoint);
+    config.model_name = "model-a";
+    config.block_size = 64;
+    config.additional_salt = "salt-a";
+    config.lora_name = "adapter-a";
+    config.dp_rank = 3;
+    config.emit_legacy_compat_fields = true;
+    KvEventPublisher publisher(config);
+    ASSERT_TRUE(publisher.enabled());
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    msgpack::object_handle payload;
+    publisher.PublishCleared("tenant-a");
+    ASSERT_TRUE(ReceivePayload(subscriber.sub, &payload));
+    ASSERT_EQ(EventCount(payload), 1u);
+    const auto& cleared = EventAt(payload, 0);
+
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "event_type")), "cleared");
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "type")),
+              "AllBlocksCleared");
+    ASSERT_NE(FindMapValue(cleared, "medium"), nullptr);
+    EXPECT_EQ(FindMapValue(cleared, "medium")->type, msgpack::type::NIL);
+
+    // A cleared envelope carries no object, hash, token, or group fields.
+    EXPECT_EQ(FindMapValue(cleared, "object_key"), nullptr);
+    EXPECT_EQ(FindMapValue(cleared, "group_id"), nullptr);
+    EXPECT_EQ(FindMapValue(cleared, "seq_hashes"), nullptr);
+    EXPECT_EQ(FindMapValue(cleared, "block_hashes"), nullptr);
+    EXPECT_EQ(FindMapValue(cleared, "base_block_idx"), nullptr);
+
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "tenant_id")), "tenant-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "model_name")), "model-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "additional_salt")),
+              "salt-a");
+    EXPECT_EQ(MsgpackString(*FindMapValue(cleared, "lora_name")), "adapter-a");
+    EXPECT_EQ(FindMapValue(cleared, "block_size")->as<uint32_t>(), 64u);
+    EXPECT_EQ(FindMapValue(cleared, "dp_rank")->as<uint32_t>(), 3u);
+}
+
+// medium is the availability field, so an empty one would describe a replica
+// the subscriber cannot place on any tier. Every entry point has to drop it
+// rather than publish a nil medium.
+TEST(KvEventPublisherTest, EmptyMediumProducesNoEvent) {
+    const std::string endpoint = MakeIpcEndpoint();
+    KvEventPublisher publisher(MakeEnabledConfig(endpoint));
+    ScopedSubscriber subscriber;
+    ASSERT_TRUE(subscriber.Connect(endpoint));
+
+    publisher.PublishStored("object-a", "", "tenant-a", "group-a");
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+
+    publisher.PublishRemoved("object-a", "", "tenant-a", "group-a");
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+
+    publisher.PublishCommitted("object-a", {""}, "tenant-a", "group-a");
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+
+    publisher.PublishObjectRemoved("object-a", "tenant-a", "group-a", {""});
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+
+    publisher.SyncObjectState("object-a", {""}, "tenant-a", "group-a", {""});
+    EXPECT_TRUE(ExpectNoMessage(subscriber.sub));
+}
+
 #endif  // MOONCAKE_ENABLE_KV_EVENTS
 
 }  // namespace
diff --git a/mooncake-store/tests/local_file_snapshot_config_test.cpp b/mooncake-store/tests/local_file_snapshot_config_test.cpp
new file mode 100644
index 0000000000..eb426a28bf
--- /dev/null
+++ b/mooncake-store/tests/local_file_snapshot_config_test.cpp
@@ -0,0 +1,107 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <optional>
+#include <stdexcept>
+#include <string>
+
+#include "../src/config/local_file_snapshot_config.h"
+
+namespace mooncake {
+namespace {
+
+class LocalFileSnapshotConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv("MOONCAKE_SNAPSHOT_LOCAL_PATH")) {
+            original_path_ = value;
+        }
+        ASSERT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+
+        std::string pattern = (std::filesystem::temp_directory_path() /
+                               "local_file_snapshot_config_test_XXXXXX")
+                                  .string();
+        char* dir = mkdtemp(pattern.data());
+        ASSERT_NE(dir, nullptr);
+        tmp_dir_ = dir;
+    }
+
+    void TearDown() override {
+        if (original_path_) {
+            EXPECT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH",
+                             original_path_->c_str(), 1),
+                      0);
+        } else {
+            EXPECT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+        }
+        if (!tmp_dir_.empty()) {
+            std::filesystem::remove_all(tmp_dir_);
+        }
+    }
+
+    std::filesystem::path tmp_dir_;
+
+   private:
+    std::optional<std::string> original_path_;
+};
+
+TEST_F(LocalFileSnapshotConfigTest, RejectsMissingAndEmptyPath) {
+    EXPECT_THROW(LocalFileSnapshotConfig::FromEnvironment(),
+                 std::runtime_error);
+
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", "", 1), 0);
+    EXPECT_THROW(LocalFileSnapshotConfig::FromEnvironment(),
+                 std::runtime_error);
+}
+
+TEST_F(LocalFileSnapshotConfigTest, PreservesPathLiterally) {
+    for (const char* value :
+         {"relative/snapshots", "/tmp/snapshots", " ", " snapshots/../data "}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", value, 1), 0);
+        EXPECT_EQ(LocalFileSnapshotConfig::FromEnvironment().base_path, value);
+    }
+}
+
+TEST_F(LocalFileSnapshotConfigTest, ReadsEnvironmentForEachConfig) {
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", "first", 1), 0);
+    const auto first = LocalFileSnapshotConfig::FromEnvironment();
+
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", "second", 1), 0);
+    EXPECT_EQ(LocalFileSnapshotConfig::FromEnvironment().base_path, "second");
+    EXPECT_EQ(first.base_path, "first");
+
+    ASSERT_EQ(unsetenv("MOONCAKE_SNAPSHOT_LOCAL_PATH"), 0);
+    EXPECT_THROW(LocalFileSnapshotConfig::FromEnvironment(),
+                 std::runtime_error);
+    EXPECT_EQ(first.base_path, "first");
+}
+
+TEST_F(LocalFileSnapshotConfigTest, DoesNotCreateDirectory) {
+    const auto path = tmp_dir_ / "not-created" / "snapshots";
+    ASSERT_FALSE(std::filesystem::exists(path));
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", path.c_str(), 1), 0);
+
+    EXPECT_EQ(LocalFileSnapshotConfig::FromEnvironment().base_path,
+              path.string());
+    EXPECT_FALSE(std::filesystem::exists(path));
+}
+
+TEST_F(LocalFileSnapshotConfigTest, LeavesFilesystemValidationToStore) {
+    const auto path = tmp_dir_ / "regular-file";
+    {
+        std::ofstream file(path);
+        ASSERT_TRUE(file.is_open());
+    }
+    ASSERT_TRUE(std::filesystem::is_regular_file(path));
+    ASSERT_EQ(setenv("MOONCAKE_SNAPSHOT_LOCAL_PATH", path.c_str(), 1), 0);
+
+    EXPECT_EQ(LocalFileSnapshotConfig::FromEnvironment().base_path,
+              path.string());
+    EXPECT_TRUE(std::filesystem::is_regular_file(path));
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/local_hot_cache_config_test.cpp b/mooncake-store/tests/local_hot_cache_config_test.cpp
new file mode 100644
index 0000000000..354dfd4de0
--- /dev/null
+++ b/mooncake-store/tests/local_hot_cache_config_test.cpp
@@ -0,0 +1,150 @@
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "local_hot_cache.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct LocalHotCacheEnvironment {
+    ScopedEnvVar total_size{"MC_STORE_LOCAL_HOT_CACHE_SIZE"};
+    ScopedEnvVar block_size{"MC_STORE_LOCAL_HOT_BLOCK_SIZE"};
+    ScopedEnvVar use_shm{"MC_STORE_LOCAL_HOT_CACHE_USE_SHM"};
+    ScopedEnvVar admission_threshold{"MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD"};
+};
+
+class LocalHotCacheConfigTest : public ::testing::Test {
+   protected:
+    LocalHotCacheEnvironment env;
+
+    void SetUp() override {
+        google::InitGoogleLogging("LocalHotCacheConfigTest");
+        FLAGS_logtostderr = true;
+    }
+
+    void TearDown() override { google::ShutdownGoogleLogging(); }
+};
+
+TEST_F(LocalHotCacheConfigTest, UsesExistingDefaultsWhenEnvironmentIsUnset) {
+    const auto config = LocalHotCacheConfig::FromEnvironment();
+
+    EXPECT_EQ(config.total_size_bytes, 0);
+    EXPECT_EQ(config.block_size_bytes, 16 * 1024 * 1024);
+    EXPECT_FALSE(config.use_shm);
+    EXPECT_EQ(config.admission_threshold, 2);
+}
+
+TEST_F(LocalHotCacheConfigTest, ReadsValidValues) {
+    env.total_size.Set("33554432");
+    env.block_size.Set("4194304");
+    env.use_shm.Set("1");
+    env.admission_threshold.Set("5");
+
+    const auto config = LocalHotCacheConfig::FromEnvironment();
+
+    EXPECT_EQ(config.total_size_bytes, 32 * 1024 * 1024);
+    EXPECT_EQ(config.block_size_bytes, 4 * 1024 * 1024);
+    EXPECT_TRUE(config.use_shm);
+    EXPECT_EQ(config.admission_threshold, 5);
+}
+
+TEST_F(LocalHotCacheConfigTest, DisabledCacheDoesNotReadDependentSettings) {
+    env.total_size.Set("0");
+    env.block_size.Set("4194304");
+    env.use_shm.Set("1");
+    env.admission_threshold.Set("5");
+
+    const auto config = LocalHotCacheConfig::FromEnvironment();
+
+    EXPECT_EQ(config.total_size_bytes, 0);
+    EXPECT_EQ(config.block_size_bytes, 16 * 1024 * 1024);
+    EXPECT_FALSE(config.use_shm);
+    EXPECT_EQ(config.admission_threshold, 2);
+}
+
+TEST_F(LocalHotCacheConfigTest, InvalidCacheSizesDisableCache) {
+    for (const char* value :
+         {"", "0", "-1", "invalid", "18446744073709551616"}) {
+        env.total_size.Set(value);
+        EXPECT_EQ(LocalHotCacheConfig::FromEnvironment().total_size_bytes, 0)
+            << value;
+    }
+}
+
+TEST_F(LocalHotCacheConfigTest, InvalidBlockSizesUseDefault) {
+    env.total_size.Set("33554432");
+
+    for (const char* value :
+         {"", "0", "-1", "invalid", "18446744073709551616"}) {
+        env.block_size.Set(value);
+        EXPECT_EQ(LocalHotCacheConfig::FromEnvironment().block_size_bytes,
+                  16 * 1024 * 1024)
+            << value;
+    }
+}
+
+TEST_F(LocalHotCacheConfigTest, InvalidAdmissionThresholdsUseDefault) {
+    env.total_size.Set("33554432");
+
+    for (const char* value :
+         {"", "0", "-1", "256", "invalid", "18446744073709551616"}) {
+        env.admission_threshold.Set(value);
+        EXPECT_EQ(LocalHotCacheConfig::FromEnvironment().admission_threshold, 2)
+            << value;
+    }
+}
+
+TEST_F(LocalHotCacheConfigTest, PreservesLegacyNumericPrefixParsing) {
+    env.total_size.Set("33554432suffix");
+    env.block_size.Set("4194304suffix");
+    env.admission_threshold.Set("5suffix");
+
+    const auto config = LocalHotCacheConfig::FromEnvironment();
+
+    EXPECT_EQ(config.total_size_bytes, 32 * 1024 * 1024);
+    EXPECT_EQ(config.block_size_bytes, 4 * 1024 * 1024);
+    EXPECT_EQ(config.admission_threshold, 5);
+}
+
+TEST_F(LocalHotCacheConfigTest, SharedMemoryRequiresExactOne) {
+    env.total_size.Set("33554432");
+
+    for (const char* value : {"", "0", "true", "01", " 1"}) {
+        env.use_shm.Set(value);
+        EXPECT_FALSE(LocalHotCacheConfig::FromEnvironment().use_shm) << value;
+    }
+
+    env.use_shm.Set("1");
+    EXPECT_TRUE(LocalHotCacheConfig::FromEnvironment().use_shm);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/local_ssd/local_ssd_test.cpp b/mooncake-store/tests/local_ssd/local_ssd_test.cpp
new file mode 100644
index 0000000000..6abe394c71
--- /dev/null
+++ b/mooncake-store/tests/local_ssd/local_ssd_test.cpp
@@ -0,0 +1,244 @@
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <thread>
+
+#include "local_ssd/manager.h"
+
+namespace mooncake {
+namespace {
+
+OffloadTaskItem Offload(std::string tenant, std::string key, int64_t size) {
+    return OffloadTaskItem{
+        .tenant_id = std::move(tenant), .key = std::move(key), .size = size};
+}
+
+PromotionTaskItem Promotion(std::string tenant, std::string key, int64_t size) {
+    return PromotionTaskItem{
+        .tenant_id = std::move(tenant), .key = std::move(key), .size = size};
+}
+
+TEST(LocalSsdTaskMailboxTest, OffloadsAreTenantScopedDeduplicatedAndLimited) {
+    LocalSsdTaskMailbox mailbox(true);
+    EXPECT_TRUE(mailbox.EnqueueOffload(Offload("tenant-a", "key", 1), 2) ==
+                ErrorCode::OK);
+    EXPECT_TRUE(mailbox.EnqueueOffload(Offload("tenant-b", "key", 2), 2) ==
+                ErrorCode::OK);
+    EXPECT_TRUE(mailbox.EnqueueOffload(Offload("tenant-a", "key", 3), 3) ==
+                ErrorCode::OBJECT_ALREADY_EXISTS);
+    EXPECT_TRUE(mailbox.EnqueueOffload(Offload("tenant-c", "key", 3), 2) ==
+                ErrorCode::KEYS_ULTRA_LIMIT);
+
+    EXPECT_TRUE(mailbox.RemoveOffload(TenantId("tenant-a"), "key"));
+    EXPECT_FALSE(mailbox.RemoveOffload(TenantId("tenant-a"), "key"));
+    auto tasks = mailbox.SetOffloadingAndTakePending(true);
+    ASSERT_EQ(tasks.size(), 1);
+    EXPECT_EQ(tasks.front(), Offload("tenant-b", "key", 2));
+    EXPECT_TRUE(mailbox.SetOffloadingAndTakePending(true).empty());
+}
+
+TEST(LocalSsdTaskMailboxTest, DisabledOffloadingDrainsPendingTasks) {
+    LocalSsdTaskMailbox mailbox(true);
+    ASSERT_TRUE(mailbox.EnqueueOffload(Offload("tenant", "key", 1), 10) ==
+                ErrorCode::OK);
+    auto tasks = mailbox.SetOffloadingAndTakePending(false);
+    ASSERT_EQ(tasks.size(), 1);
+    EXPECT_TRUE(mailbox.EnqueueOffload(Offload("tenant", "next", 2), 10) ==
+                ErrorCode::UNABLE_OFFLOADING);
+}
+
+TEST(LocalSsdTaskMailboxTest, PromotionsAreBatchedAndRemoveAllIsConsumed) {
+    LocalSsdTaskMailbox mailbox(false);
+    EXPECT_TRUE(mailbox.EnqueuePromotion(Promotion("a", "key", 1)) ==
+                ErrorCode::OK);
+    EXPECT_TRUE(mailbox.EnqueuePromotion(Promotion("b", "key", 2)) ==
+                ErrorCode::OK);
+    EXPECT_TRUE(mailbox.EnqueuePromotion(Promotion("a", "key", 3)) ==
+                ErrorCode::OBJECT_ALREADY_EXISTS);
+    EXPECT_EQ(mailbox.TakePromotions(1).size(), 1);
+    EXPECT_EQ(mailbox.TakePromotions(10).size(), 1);
+    EXPECT_TRUE(mailbox.TakePromotions(10).empty());
+
+    EXPECT_FALSE(mailbox.ConsumeRemoveAll());
+    mailbox.RequestRemoveAll();
+    EXPECT_TRUE(mailbox.ConsumeRemoveAll());
+    EXPECT_FALSE(mailbox.ConsumeRemoveAll());
+}
+
+TEST(LocalSsdTaskMailboxTest, PromotionsAreDeliveredByRecency) {
+    LocalSsdTaskMailbox mailbox(false);
+    ASSERT_TRUE(mailbox.EnqueuePromotion(Promotion("t", "a", 1)) ==
+                ErrorCode::OK);
+    ASSERT_TRUE(mailbox.EnqueuePromotion(Promotion("t", "b", 2)) ==
+                ErrorCode::OK);
+    ASSERT_TRUE(mailbox.EnqueuePromotion(Promotion("t", "c", 3)) ==
+                ErrorCode::OK);
+
+    // Without any touch, the most recent enqueue is delivered first.
+    auto first = mailbox.TakePromotions(1);
+    ASSERT_EQ(first.size(), 1);
+    EXPECT_EQ(first.front(), Promotion("t", "c", 3));
+
+    // A touch re-marks an older entry ahead of newer ones.
+    ASSERT_TRUE(mailbox.TouchPromotion(TenantId("t"), "a"));
+    auto second = mailbox.TakePromotions(1);
+    ASSERT_EQ(second.size(), 1);
+    EXPECT_EQ(second.front(), Promotion("t", "a", 1));
+
+    // A duplicate enqueue keeps the dedup contract but refreshes recency.
+    ASSERT_TRUE(mailbox.EnqueuePromotion(Promotion("t", "b", 2)) ==
+                ErrorCode::OBJECT_ALREADY_EXISTS);
+    auto third = mailbox.TakePromotions(1);
+    ASSERT_EQ(third.size(), 1);
+    EXPECT_EQ(third.front(), Promotion("t", "b", 2));
+
+    EXPECT_TRUE(mailbox.TakePromotions(10).empty());
+    EXPECT_FALSE(mailbox.TouchPromotion(TenantId("t"), "missing"));
+}
+
+TEST(LocalSsdTaskMailboxTest, TakePromotionsKeepsGlobalRecencyAcrossTicks) {
+    LocalSsdTaskMailbox mailbox(false);
+    for (const char* key : {"k1", "k2", "k3", "k4", "k5"}) {
+        ASSERT_TRUE(mailbox.EnqueuePromotion(Promotion("t", key, 1)) ==
+                    ErrorCode::OK);
+    }
+    ASSERT_TRUE(mailbox.TouchPromotion(TenantId("t"), "k2"));
+
+    // k2 (touched) first, then the newest enqueue. The batch limit must not
+    // degrade the remainder to hash order on the next tick.
+    auto batch = mailbox.TakePromotions(2);
+    ASSERT_EQ(batch.size(), 2);
+    EXPECT_EQ(batch[0], Promotion("t", "k2", 1));
+    EXPECT_EQ(batch[1], Promotion("t", "k5", 1));
+
+    auto rest = mailbox.TakePromotions(10);
+    ASSERT_EQ(rest.size(), 3);
+    EXPECT_EQ(rest[0], Promotion("t", "k4", 1));
+    EXPECT_EQ(rest[1], Promotion("t", "k3", 1));
+    EXPECT_EQ(rest[2], Promotion("t", "k1", 1));
+}
+
+TEST(LocalSsdManagerTest, TouchPromotionIsClientScoped) {
+    LocalSsdManager manager;
+    UUID client{7, 8};
+    UUID other{9, 10};
+    ASSERT_TRUE(manager.RegisterClient(client, false) == ErrorCode::OK);
+    ASSERT_TRUE(manager.RegisterClient(other, false) == ErrorCode::OK);
+    ASSERT_TRUE(manager.EnqueuePromotion(client, Promotion("t", "a", 1)) ==
+                ErrorCode::OK);
+    ASSERT_TRUE(manager.EnqueuePromotion(client, Promotion("t", "b", 2)) ==
+                ErrorCode::OK);
+
+    // Unknown clients and foreign clients cannot touch the entry.
+    EXPECT_FALSE(manager.TouchPromotion(UUID{11, 12}, TenantId("t"), "a"));
+    EXPECT_FALSE(manager.TouchPromotion(other, TenantId("t"), "a"));
+
+    ASSERT_TRUE(manager.TouchPromotion(client, TenantId("t"), "a"));
+    auto taken = manager.TakePromotions(client, 1);
+    ASSERT_EQ(taken->size(), 1);
+    EXPECT_EQ(taken->front(), Promotion("t", "a", 1));
+}
+
+TEST(LocalSsdManagerTest, ManagesRegistrationCapacityAndUsage) {
+    LocalSsdManager manager;
+    UUID client{1, 2};
+    EXPECT_TRUE(manager.RegisterClient(client, true) == ErrorCode::OK);
+    EXPECT_TRUE(manager.RegisterClient(client, false) ==
+                ErrorCode::SEGMENT_ALREADY_EXISTS);
+
+    auto change = manager.ReportCapacity(client, 1024);
+    ASSERT_TRUE(change.has_value());
+    EXPECT_EQ(change->previous_bytes, 0);
+    EXPECT_EQ(change->current_bytes, 1024);
+    EXPECT_TRUE(manager.AdjustUsedBytes(client, 300));
+    auto usage = manager.GetUsage(client);
+    ASSERT_TRUE(usage.has_value());
+    EXPECT_EQ(usage->total_capacity_bytes, 1024);
+    EXPECT_EQ(usage->used_bytes, 300);
+
+    auto capacity = manager.UnregisterClient(client);
+    ASSERT_TRUE(capacity.has_value());
+    EXPECT_EQ(*capacity, 1024);
+    EXPECT_FALSE(manager.GetUsage(client).has_value());
+    EXPECT_FALSE(manager.AdjustUsedBytes(client, 1));
+}
+
+TEST(LocalSsdManagerTest, UnregisterSerializesWithConcurrentOperations) {
+    LocalSsdManager manager;
+    UUID client{3, 4};
+    ASSERT_TRUE(manager.RegisterClient(client, true) == ErrorCode::OK);
+    std::atomic<bool> stop{false};
+    std::thread worker([&] {
+        while (!stop.load(std::memory_order_relaxed)) {
+            manager.AdjustUsedBytes(client, 1);
+            manager.GetUsage(client);
+        }
+    });
+    auto removed = manager.UnregisterClient(client);
+    stop.store(true, std::memory_order_relaxed);
+    worker.join();
+    EXPECT_TRUE(removed.has_value());
+    EXPECT_FALSE(manager.GetUsage(client).has_value());
+}
+
+TEST(LocalSsdManagerTest, CancelsOffloadMirrorsOnlyWhenAllArePending) {
+    LocalSsdManager manager;
+    UUID client_a{10, 11};
+    UUID client_b{12, 13};
+    ASSERT_TRUE(manager.RegisterClient(client_a, true) == ErrorCode::OK);
+    ASSERT_TRUE(manager.RegisterClient(client_b, true) == ErrorCode::OK);
+
+    const auto enqueue_mirrors = [&] {
+        ASSERT_TRUE(manager.EnqueueOffload(client_a,
+                                           Offload("tenant", "key", 1),
+                                           10) == ErrorCode::OK);
+        ASSERT_TRUE(manager.EnqueueOffload(client_b,
+                                           Offload("tenant", "key", 1),
+                                           10) == ErrorCode::OK);
+    };
+
+    enqueue_mirrors();
+    auto claimed = manager.SetOffloadingAndTakePending(client_b, true);
+    ASSERT_TRUE(claimed.has_value());
+    ASSERT_EQ(claimed->size(), 1);
+    EXPECT_FALSE(manager.CancelOffloadsIfAllPending({client_a, client_b},
+                                                    TenantId("tenant"), "key"));
+    auto still_pending = manager.SetOffloadingAndTakePending(client_a, true);
+    ASSERT_TRUE(still_pending.has_value());
+    ASSERT_EQ(still_pending->size(), 1);
+
+    enqueue_mirrors();
+    EXPECT_TRUE(manager.CancelOffloadsIfAllPending({client_b, client_a},
+                                                   TenantId("tenant"), "key"));
+    EXPECT_TRUE(manager.SetOffloadingAndTakePending(client_a, true)->empty());
+    EXPECT_TRUE(manager.SetOffloadingAndTakePending(client_b, true)->empty());
+}
+
+TEST(LocalSsdManagerTest, RestoreResetsRuntimeOnlyState) {
+    LocalSsdManager manager;
+    UUID client{5, 6};
+    ASSERT_TRUE(manager.RegisterClient(client, true) == ErrorCode::OK);
+    ASSERT_TRUE(manager.ReportCapacity(client, 2048).has_value());
+    ASSERT_TRUE(manager.AdjustUsedBytes(client, 512));
+    ASSERT_TRUE(manager.EnqueueOffload(client, Offload("tenant", "key", 10),
+                                       10) == ErrorCode::OK);
+    ASSERT_TRUE(manager.EnqueuePromotion(
+                    client, Promotion("tenant", "key", 10)) == ErrorCode::OK);
+    manager.RequestRemoveAll();
+
+    auto state = manager.ExportPersistedState();
+    manager.RestorePersistedState(std::move(state));
+    auto usage = manager.GetUsage(client);
+    ASSERT_TRUE(usage.has_value());
+    EXPECT_EQ(usage->total_capacity_bytes, 2048);
+    EXPECT_EQ(usage->used_bytes, 0);
+    EXPECT_TRUE(manager.TakePromotions(client, 10)->empty());
+    EXPECT_FALSE(*manager.ConsumeRemoveAll(client));
+    auto offloads = manager.SetOffloadingAndTakePending(client, true);
+    ASSERT_TRUE(offloads.has_value());
+    ASSERT_EQ(offloads->size(), 1);
+    EXPECT_EQ(offloads->front(), Offload("tenant", "key", 10));
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/master_admin_server_test.cpp b/mooncake-store/tests/master_admin_server_test.cpp
index 8c572a4199..6c525f201f 100644
--- a/mooncake-store/tests/master_admin_server_test.cpp
+++ b/mooncake-store/tests/master_admin_server_test.cpp
@@ -1,26 +1,33 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <atomic>
 #include <chrono>
 #include <csignal>
+#include <cstdlib>
 #include <filesystem>
 #include <fstream>
+#include <future>
 #include <map>
 #include <memory>
+#include <optional>
 #include <string>
 #include <thread>
+#include <vector>
 
 #include <ylt/coro_http/coro_http_client.hpp>
+#include <ylt/coro_io/coro_io.hpp>
 #include <ylt/struct_json/json_reader.h>
 #include <ylt/struct_json/json_writer.h>
 
+#include "common/network.h"
 #include "ha/ha_types.h"
 #include "master_admin_service.h"
 #include "master_config.h"
 #include "rpc_service.h"
 #include "tenant_quota_policy_store.h"
 #include "types.h"
-#include "utils.h"
+#include "version.h"
 
 #include <ylt/reflection/user_reflect_macro.hpp>
 
@@ -29,6 +36,97 @@ namespace test {
 
 namespace {
 
+struct HttpDfsShardCountResponse {
+    bool success{false};
+    int shard_count{0};
+};
+YLT_REFL(HttpDfsShardCountResponse, success, shard_count);
+
+class DfsAdminEnvironment {
+   public:
+    explicit DfsAdminEnvironment(bool enabled) {
+        root_ = std::filesystem::temp_directory_path() /
+                ("mooncake_admin_dfs_" + UuidToString(generate_uuid()));
+        std::filesystem::create_directories(root_);
+        Set("MOONCAKE_ENABLE_DFS", enabled ? "1" : "0");
+        Set("MOONCAKE_DFS_FS_ADAPTER", "posix");
+        Set("MOONCAKE_DFS_ROOT_DIR", root_.string());
+        Set("MOONCAKE_DFS_SHARD_COUNT", "1");
+        Set("MOONCAKE_DFS_SHARD_CAPACITY", "8192");
+        Set("MOONCAKE_DFS_ALIGNMENT", "4096");
+        Set("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+        Set("MOONCAKE_DFS_SINGLE_TENANT", "true");
+    }
+
+    ~DfsAdminEnvironment() {
+        for (const auto& [key, value] : saved_) {
+            if (value) {
+                ::setenv(key.c_str(), value->c_str(), 1);
+            } else {
+                ::unsetenv(key.c_str());
+            }
+        }
+        std::error_code ec;
+        std::filesystem::remove_all(root_, ec);
+    }
+
+   private:
+    void Set(const std::string& key, const std::string& value) {
+        const char* previous = ::getenv(key.c_str());
+        saved_.push_back({key, previous ? std::optional<std::string>(previous)
+                                        : std::nullopt});
+        ::setenv(key.c_str(), value.c_str(), 1);
+    }
+    std::filesystem::path root_;
+    std::vector<std::pair<std::string, std::optional<std::string>>> saved_;
+};
+
+// Queue filesystem work deterministically without adding a production test
+// hook. HTTP uses its own pool, so it must remain responsive while this pool
+// is held. Release before destroying futures that may await queued work.
+class ScopedBlockingPoolHold {
+   public:
+    ScopedBlockingPoolHold()
+        : release_(std::make_unique<std::promise<void>>()),
+          entered_(std::make_shared<std::atomic<size_t>>(0)) {
+        const auto ready = release_->get_future().share();
+        const auto executors =
+            coro_io::g_block_io_context_pool<>().get_all_executor();
+        count_ = executors.size();
+        for (const auto& executor : executors) {
+            asio::post(executor->get_asio_executor(),
+                       [ready, entered = entered_] {
+                           entered->fetch_add(1);
+                           ready.wait();
+                       });
+        }
+    }
+
+    ~ScopedBlockingPoolHold() { Release(); }
+
+    bool WaitUntilBlocked() const {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(10);
+        while (entered_->load() != count_) {
+            if (std::chrono::steady_clock::now() >= deadline) return false;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        return true;
+    }
+
+    void Release() {
+        if (release_) {
+            release_->set_value();
+            release_.reset();
+        }
+    }
+
+   private:
+    std::unique_ptr<std::promise<void>> release_;
+    std::shared_ptr<std::atomic<size_t>> entered_;
+    size_t count_ = 0;
+};
+
 struct HttpCreateDrainJobResponse {
     bool success{false};
     std::string job_id;
@@ -154,6 +252,146 @@ class MasterAdminServerTest : public ::testing::Test {
 // Always-available endpoint tests
 // =========================================================================
 
+TEST_F(MasterAdminServerTest, DfsShardCountExpandsAndValidatesRequests) {
+    DfsAdminEnvironment env(true);
+    WrappedMasterServiceConfig config;
+    config.default_kv_lease_ttl = 5000;
+    config.enable_metric_reporting = false;
+    config.client_active_ttl_sec = 3600;
+    auto service = std::make_shared<WrappedMasterService>(config);
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kServing);
+    admin.SetServiceDelegate(service);
+    admin.SetServiceAvailable(true);
+    const std::string path = "/api/v1/dfs/shard_count";
+
+    auto before = HttpGet(port, path);
+    ASSERT_EQ(before.http_status, 200);
+    HttpDfsShardCountResponse parsed;
+    struct_json::from_json(parsed, before.body);
+    EXPECT_TRUE(parsed.success);
+    EXPECT_EQ(parsed.shard_count, 1);
+    for (int i = 0; i < 2; ++i) {
+        auto expanded = HttpPutJson(port, path, R"({"shard_count":3})");
+        ASSERT_EQ(expanded.http_status, 200);
+        struct_json::from_json(parsed, expanded.body);
+        EXPECT_TRUE(parsed.success);
+        EXPECT_EQ(parsed.shard_count, 3);
+    }
+    for (const auto& invalid :
+         {R"({"shard_count":2})", R"({"shard_count":0})",
+          R"({"shard_count":-1})", R"({"shard_count":3.0})",
+          R"({"shard_count":true})", R"({"shard_count":"3"})",
+          R"({"shard_count":null})", R"({"shard_count":2147483648})",
+          R"({"shard_count":3,"shard_count":4})", "{}", "[]",
+          R"({"shard_count":4} trailing)"}) {
+        EXPECT_EQ(HttpPutJson(port, path, invalid).http_status, 400) << invalid;
+    }
+    auto after = HttpGet(port, path);
+    ASSERT_EQ(after.http_status, 200);
+    struct_json::from_json(parsed, after.body);
+    EXPECT_EQ(parsed.shard_count, 3);
+    auto count = service->GetDfsShardCount();
+    ASSERT_TRUE(count);
+    EXPECT_EQ(*count, 3);
+    admin.Stop();
+}
+
+TEST_F(MasterAdminServerTest, DfsExpansionKeepsHttpResponsiveAndDrainsOnStop) {
+    DfsAdminEnvironment env(true);
+    WrappedMasterServiceConfig config;
+    config.default_kv_lease_ttl = 5000;
+    config.enable_metric_reporting = false;
+    config.client_active_ttl_sec = 3600;
+    auto service = std::make_shared<WrappedMasterService>(config);
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kServing);
+    admin.SetServiceDelegate(service);
+    admin.SetServiceAvailable(true);
+    const std::string path = "/api/v1/dfs/shard_count";
+
+    // Declare futures first so a failed assertion releases the held workers
+    // before future destruction waits for either request or shutdown.
+    std::future<HttpResponse> first;
+    std::future<HttpResponse> second;
+    std::future<void> stopped;
+    ScopedBlockingPoolHold hold;
+    ASSERT_TRUE(hold.WaitUntilBlocked());
+    auto expand = [&] {
+        return HttpPutJson(port, path, R"({"shard_count":3})");
+    };
+    first = std::async(std::launch::async, expand);
+    second = std::async(std::launch::async, expand);
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(10);
+    while (
+        first.wait_for(std::chrono::seconds(0)) != std::future_status::ready &&
+        second.wait_for(std::chrono::seconds(0)) != std::future_status::ready &&
+        std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    const bool first_ready =
+        first.wait_for(std::chrono::seconds(0)) == std::future_status::ready;
+    auto& rejected = first_ready ? first : second;
+    auto& pending = first_ready ? second : first;
+    ASSERT_EQ(rejected.wait_for(std::chrono::seconds(0)),
+              std::future_status::ready);
+    EXPECT_EQ(rejected.get().http_status, 409);
+    EXPECT_EQ(HttpGet(port, "/health").http_status, 200);
+    EXPECT_EQ(pending.wait_for(std::chrono::seconds(0)),
+              std::future_status::timeout);
+
+    stopped = std::async(std::launch::async, [&] { admin.Stop(); });
+    // Stop closes the client connection, but must retain its executor until
+    // the queued expansion has resumed and finished the handler.
+    ASSERT_EQ(pending.wait_for(std::chrono::seconds(10)),
+              std::future_status::ready);
+    pending.get();
+    EXPECT_EQ(stopped.wait_for(std::chrono::milliseconds(50)),
+              std::future_status::timeout);
+    hold.Release();
+    ASSERT_EQ(stopped.wait_for(std::chrono::seconds(10)),
+              std::future_status::ready);
+    stopped.get();
+    auto count = service->GetDfsShardCount();
+    ASSERT_TRUE(count);
+    EXPECT_EQ(*count, 3);
+}
+
+TEST_F(MasterAdminServerTest, DfsShardCountRejectsDisabledBackend) {
+    DfsAdminEnvironment env(false);
+    WrappedMasterServiceConfig config;
+    config.default_kv_lease_ttl = 5000;
+    config.enable_metric_reporting = false;
+    config.client_active_ttl_sec = 3600;
+    auto service = std::make_shared<WrappedMasterService>(config);
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kServing);
+    admin.SetServiceDelegate(service);
+    admin.SetServiceAvailable(true);
+    const std::string path = "/api/v1/dfs/shard_count";
+    EXPECT_EQ(HttpGet(port, path).http_status, 409);
+    EXPECT_EQ(HttpPutJson(port, path, R"({"shard_count":3})").http_status, 409);
+    admin.Stop();
+}
+
+TEST_F(MasterAdminServerTest, DfsShardCountRejectsUnavailableService) {
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kStandby);
+    const std::string path = "/api/v1/dfs/shard_count";
+    EXPECT_EQ(HttpGet(port, path).http_status, 503);
+    EXPECT_EQ(HttpPutJson(port, path, R"({"shard_count":3})").http_status, 503);
+    admin.Stop();
+}
+
 TEST_F(MasterAdminServerTest, MetricsEndpointReturns200) {
     int port = getFreeTcpPort();
     MasterAdminServer admin(static_cast<uint16_t>(port), false);
@@ -208,6 +446,35 @@ TEST_F(MasterAdminServerTest, HealthEndpointReturns200InServing) {
     admin.Stop();
 }
 
+TEST_F(MasterAdminServerTest, VersionEndpointReturnsVersion) {
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kServing);
+
+    auto resp = HttpGet(port, "/version");
+    EXPECT_EQ(resp.http_status, 200);
+    EXPECT_NE(resp.body.find("\"version\""), std::string::npos);
+    EXPECT_NE(resp.body.find("\"display_version\""), std::string::npos);
+    EXPECT_NE(resp.body.find(GetMooncakeStoreVersion()), std::string::npos);
+    EXPECT_NE(resp.body.find(MOONCAKE_DISPLAY_VERSION), std::string::npos);
+
+    admin.Stop();
+}
+
+TEST_F(MasterAdminServerTest, VersionEndpointAvailableInStandby) {
+    int port = getFreeTcpPort();
+    MasterAdminServer admin(static_cast<uint16_t>(port), false);
+    ASSERT_TRUE(admin.Start());
+    admin.SetRuntimeState(ha::MasterRuntimeState::kStandby);
+
+    auto resp = HttpGet(port, "/version");
+    EXPECT_EQ(resp.http_status, 200);
+    EXPECT_NE(resp.body.find(GetMooncakeStoreVersion()), std::string::npos);
+
+    admin.Stop();
+}
+
 TEST_F(MasterAdminServerTest, HealthEndpointIncludesLeaderInfoWhenSet) {
     int port = getFreeTcpPort();
     MasterAdminServer admin(static_cast<uint16_t>(port), false);
@@ -535,7 +802,8 @@ TEST_F(MasterAdminServerTest, TenantQuotaAdminLifecycleEndpoints) {
 
     auto one = HttpGet(port, "/api/v1/tenant_quotas?tenant_id=tenant-a");
     EXPECT_EQ(one.http_status, 200);
-    EXPECT_NE(one.body.find("\"committed_count\":0"), std::string::npos);
+    EXPECT_NE(one.body.find("\"charged_bytes\":0"), std::string::npos);
+    EXPECT_NE(one.body.find("\"admission_closed\":false"), std::string::npos);
     EXPECT_NE(one.body.find("\"over_quota\":false"), std::string::npos);
 
     ReplicateConfig cfg;
@@ -549,6 +817,21 @@ TEST_F(MasterAdminServerTest, TenantQuotaAdminLifecycleEndpoints) {
                              ReplicaType::MEMORY, "tenant-a")
                     .has_value());
 
+    auto metrics = HttpGet(port, "/metrics");
+    EXPECT_EQ(metrics.http_status, 200);
+    EXPECT_NE(
+        metrics.body.find(
+            "mooncake_tenant_quota_charged_bytes{tenant_id=\"tenant-a\"} 100"),
+        std::string::npos);
+    EXPECT_NE(metrics.body.find(
+                  "mooncake_tenant_quota_admission_closed{tenant_id=\"tenant-a"
+                  "\"} 0"),
+              std::string::npos);
+    EXPECT_EQ(metrics.body.find("mooncake_tenant_quota_reserved_bytes"),
+              std::string::npos);
+    EXPECT_EQ(metrics.body.find("mooncake_tenant_quota_used_bytes"),
+              std::string::npos);
+
     auto delete_non_empty =
         HttpDelete(port, "/api/v1/tenant_quotas?tenant_id=tenant-a");
     EXPECT_EQ(delete_non_empty.http_status, 409);
@@ -598,6 +881,11 @@ TEST_F(MasterAdminServerTest, TenantQuotaAdminValidationErrors) {
                     "{\"requested_quota_bytes\":0}");
     EXPECT_EQ(zero_explicit.http_status, 400);
 
+    auto above_atomic_range =
+        HttpPutJson(port, "/api/v1/tenant_quotas?tenant_id=tenant-a",
+                    "{\"requested_quota_bytes\":9223372036854775808}");
+    EXPECT_EQ(above_atomic_range.http_status, 400);
+
     auto reserved_tenant =
         HttpGet(port, "/api/v1/tenant_quotas?tenant_id=_system");
     EXPECT_EQ(reserved_tenant.http_status, 400);
@@ -647,7 +935,7 @@ class MasterAdminServerWithServiceTest : public ::testing::Test {
         WrappedMasterServiceConfig svc_config;
         svc_config.default_kv_lease_ttl = 5000;
         svc_config.enable_metric_reporting = false;
-        svc_config.client_live_ttl_sec =
+        svc_config.client_active_ttl_sec =
             3600;  // prevent client expiry in slow CI
         service_ = std::make_shared<WrappedMasterService>(svc_config);
 
diff --git a/mooncake-store/tests/master_config_test.cpp b/mooncake-store/tests/master_config_test.cpp
new file mode 100644
index 0000000000..2e676ad763
--- /dev/null
+++ b/mooncake-store/tests/master_config_test.cpp
@@ -0,0 +1,65 @@
+#include "master_config.h"
+
+#include <gtest/gtest.h>
+
+namespace mooncake::test {
+namespace {
+
+TEST(ClientLivenessConfigTest, UsesIndependentDefaultsWhenNothingIsSet) {
+    const auto resolved = ResolveClientLivenessConfig({}, {});
+
+    EXPECT_EQ(resolved.active_ttl_sec, DEFAULT_CLIENT_LIVE_TTL_SEC);
+    EXPECT_EQ(resolved.suspicion_ttl_sec, DEFAULT_CLIENT_SUSPICION_TTL_SEC);
+}
+
+TEST(ClientLivenessConfigTest, ExplicitActiveAlsoDefaultsSuspicion) {
+    const ClientLivenessConfigSource file{
+        .active_ttl_sec = std::nullopt,
+        .legacy_ttl_sec = 60,
+        .suspicion_ttl_sec = std::nullopt,
+    };
+
+    const auto resolved = ResolveClientLivenessConfig(file, {});
+    EXPECT_EQ(resolved.active_ttl_sec, 60);
+    EXPECT_EQ(resolved.suspicion_ttl_sec, 60);
+}
+
+TEST(ClientLivenessConfigTest, CommandLineCanonicalValuesTakePrecedence) {
+    const ClientLivenessConfigSource file{
+        .active_ttl_sec = 30,
+        .legacy_ttl_sec = 40,
+        .suspicion_ttl_sec = 50,
+    };
+    const ClientLivenessConfigSource command_line{
+        .active_ttl_sec = 70,
+        .legacy_ttl_sec = 80,
+        .suspicion_ttl_sec = 90,
+    };
+
+    const auto resolved = ResolveClientLivenessConfig(file, command_line);
+    EXPECT_EQ(resolved.active_ttl_sec, 70);
+    EXPECT_EQ(resolved.suspicion_ttl_sec, 90);
+    EXPECT_TRUE(resolved.config_active_conflict);
+    EXPECT_TRUE(resolved.command_line_active_conflict);
+}
+
+TEST(ClientLivenessConfigTest, RejectsNonPositiveExplicitValues) {
+    const ClientLivenessConfigSource file{
+        .active_ttl_sec = std::nullopt,
+        .legacy_ttl_sec = std::nullopt,
+        .suspicion_ttl_sec = 0,
+    };
+
+    EXPECT_THROW(ResolveClientLivenessConfig(file, {}), std::invalid_argument);
+}
+
+TEST(ClientLivenessConfigTest, LegacyBuilderSetterDefaultsBothWindows) {
+    const auto config =
+        MasterServiceConfig::builder().set_client_live_ttl_sec(45).build();
+
+    EXPECT_EQ(config.client_active_ttl_sec, 45);
+    EXPECT_EQ(config.client_suspicion_ttl_sec, 45);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_heartbeat_metric_test.cpp b/mooncake-store/tests/master_heartbeat_metric_test.cpp
new file mode 100644
index 0000000000..605ddf57d0
--- /dev/null
+++ b/mooncake-store/tests/master_heartbeat_metric_test.cpp
@@ -0,0 +1,282 @@
+#include "master_heartbeat_metric.h"
+#include "rpc_types.h"
+#include <ylt/util/tl/expected.hpp>
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <thread>
+
+namespace mooncake::test {
+namespace {
+
+std::string Serialize(MasterHeartbeatMetric& metric) {
+    std::string result;
+    metric.serialize(result);
+    return result;
+}
+
+void Connect(MasterHeartbeatMetric& metric) {
+    metric.EndConnection(metric.BeginConnection(), true);
+}
+
+tl::expected<PingResponse, ErrorCode> Ping(ClientStatus status) {
+    return PingResponse{42, status};
+}
+
+TEST(MasterHeartbeatMetricTest,
+     ObserveConnectPreservesResultAndInvalidatesSample) {
+    MasterHeartbeatMetric metric;
+    int calls = 0;
+    EXPECT_EQ(metric.ObserveConnect([&] {
+        ++calls;
+        EXPECT_TRUE(Serialize(metric).empty());
+        EXPECT_FALSE(metric.BeginObservation());
+        return ErrorCode::OK;
+    }),
+              ErrorCode::OK);
+    EXPECT_EQ(calls, 1);
+    metric.ObservePing([] { return Ping(ClientStatus::OK); });
+    EXPECT_FALSE(Serialize(metric).empty());
+    EXPECT_EQ(metric.ObserveConnect([&] {
+        ++calls;
+        EXPECT_TRUE(Serialize(metric).empty());
+        return ErrorCode::RPC_FAIL;
+    }),
+              ErrorCode::RPC_FAIL);
+    EXPECT_EQ(calls, 2);
+    EXPECT_FALSE(metric.BeginObservation());
+    EXPECT_TRUE(Serialize(metric).empty());
+}
+
+TEST(MasterHeartbeatMetricTest, ObservePingMapsStatusAndPreservesResponse) {
+    MasterHeartbeatMetric metric;
+    metric.ObserveConnect([] { return ErrorCode::OK; });
+    for (auto status : {ClientStatus::OK, ClientStatus::NEED_REMOUNT}) {
+        const auto before = std::chrono::system_clock::now();
+        int calls = 0;
+        auto result = metric.ObservePing([&] {
+            ++calls;
+            // Reentering serialization would deadlock if the wrapper held
+            // the metric lock while invoking the RPC callback.
+            Serialize(metric);
+            return Ping(status);
+        });
+        const auto after = std::chrono::system_clock::now();
+        ASSERT_TRUE(result);
+        EXPECT_EQ(calls, 1);
+        EXPECT_EQ(result->view_version_id, 42);
+        EXPECT_EQ(result->client_status, status);
+        const auto text = Serialize(metric);
+        EXPECT_NE(
+            text.find(status == ClientStatus::OK ? "heartbeat_status_ok 1\n"
+                                                 : "heartbeat_status_ok 0\n"),
+            std::string::npos);
+        const std::string name =
+            "\nmooncake_client_master_heartbeat_observation_timestamp_seconds ";
+        const auto offset = text.find(name);
+        ASSERT_NE(offset, std::string::npos);
+        const auto timestamp = std::stod(text.substr(offset + name.size()));
+        // The gauge exposition rounds to six decimal places.
+        EXPECT_GE(
+            timestamp,
+            std::chrono::duration<double>(before.time_since_epoch()).count() -
+                1e-6);
+        EXPECT_LE(
+            timestamp,
+            std::chrono::duration<double>(after.time_since_epoch()).count() +
+                1e-6);
+    }
+}
+
+TEST(MasterHeartbeatMetricTest,
+     ObservePingClearsFailedAndUnsupportedResponses) {
+    MasterHeartbeatMetric metric;
+    metric.ObserveConnect([] { return ErrorCode::OK; });
+    metric.ObservePing([] { return Ping(ClientStatus::OK); });
+    auto unsupported =
+        metric.ObservePing([] { return Ping(ClientStatus::UNDEFINED); });
+    ASSERT_TRUE(unsupported);
+    EXPECT_EQ(unsupported->client_status, ClientStatus::UNDEFINED);
+    EXPECT_TRUE(Serialize(metric).empty());
+    metric.ObservePing([] { return Ping(ClientStatus::OK); });
+    auto failed =
+        metric.ObservePing([]() -> tl::expected<PingResponse, ErrorCode> {
+            return tl::make_unexpected(ErrorCode::RPC_FAIL);
+        });
+    ASSERT_FALSE(failed);
+    EXPECT_EQ(failed.error(), ErrorCode::RPC_FAIL);
+    EXPECT_TRUE(Serialize(metric).empty());
+}
+
+TEST(MasterHeartbeatMetricTest, ObservePingRejectsLateSuccessAndFailure) {
+    MasterHeartbeatMetric metric;
+    metric.ObserveConnect([] { return ErrorCode::OK; });
+    for (bool success : {true, false}) {
+        std::string current;
+        auto result =
+            metric.ObservePing([&]() -> tl::expected<PingResponse, ErrorCode> {
+                metric.ObserveConnect([] { return ErrorCode::OK; });
+                metric.ObservePing(
+                    [] { return Ping(ClientStatus::NEED_REMOUNT); });
+                current = Serialize(metric);
+                if (success) return Ping(ClientStatus::OK);
+                return tl::make_unexpected(ErrorCode::RPC_FAIL);
+            });
+        EXPECT_EQ(result.has_value(), success);
+        EXPECT_FALSE(current.empty());
+        EXPECT_EQ(Serialize(metric), current);
+    }
+}
+
+TEST(MasterHeartbeatMetricTest, ObservePingDuringConnectCannotPublish) {
+    MasterHeartbeatMetric metric;
+    metric.ObserveConnect([&] {
+        auto result = metric.ObservePing([] { return Ping(ClientStatus::OK); });
+        EXPECT_TRUE(result);
+        EXPECT_TRUE(Serialize(metric).empty());
+        return ErrorCode::OK;
+    });
+    EXPECT_TRUE(metric.BeginObservation());
+    EXPECT_TRUE(Serialize(metric).empty());
+}
+
+TEST(MasterHeartbeatMetricTest, InitialObservationIsUnknown) {
+    MasterHeartbeatMetric metric;
+    EXPECT_FALSE(metric.BeginObservation());
+    EXPECT_TRUE(Serialize(metric).empty());
+    Connect(metric);
+    EXPECT_TRUE(Serialize(metric).empty());
+}
+
+TEST(MasterHeartbeatMetricTest, StatusAndReceiveTimeFollowSuccessfulPing) {
+    MasterHeartbeatMetric metric;
+    Connect(metric);
+    const auto generation = metric.BeginObservation();
+    metric.Observe(generation, false, 100.25);
+    const auto remount = Serialize(metric);
+    EXPECT_NE(remount.find("mooncake_client_master_heartbeat_status_ok 0\n"),
+              std::string::npos);
+    EXPECT_NE(remount.find("timestamp_seconds 100.250000\n"),
+              std::string::npos);
+    EXPECT_NE(remount.find(
+                  "# TYPE mooncake_client_master_heartbeat_status_ok gauge\n"),
+              std::string::npos);
+    metric.Observe(generation, true, 200.5);
+    const auto recovered = Serialize(metric);
+    EXPECT_NE(recovered.find("mooncake_client_master_heartbeat_status_ok 1\n"),
+              std::string::npos);
+    EXPECT_NE(recovered.find("timestamp_seconds 200.500000\n"),
+              std::string::npos);
+    EXPECT_EQ(recovered.find("100.250000"), std::string::npos);
+}
+
+TEST(MasterHeartbeatMetricTest, FailedOrUnsupportedObservationIsUnknown) {
+    MasterHeartbeatMetric metric;
+    Connect(metric);
+    const auto generation = metric.BeginObservation();
+    metric.Observe(generation, true, 100);
+    metric.Observe(generation, std::nullopt, 0);
+    EXPECT_TRUE(Serialize(metric).empty());
+    metric.Observe(generation, std::nullopt, 0);
+    EXPECT_TRUE(Serialize(metric).empty());
+    metric.Observe(generation, false, 200);
+    EXPECT_NE(Serialize(metric).find("heartbeat_status_ok 0\n"),
+              std::string::npos);
+}
+
+TEST(MasterHeartbeatMetricTest, PreservesAndEscapesLabels) {
+    MasterHeartbeatMetric metric(
+        {{"cluster_id", "cluster1"}, {"instance_id", "node\"a\\b\nc"}});
+    Connect(metric);
+    metric.Observe(metric.BeginObservation(), true, 100);
+    const auto text = Serialize(metric);
+    const std::string labels =
+        "{cluster_id=\"cluster1\",instance_id=\"node\\\"a\\\\b\\nc\"}";
+    EXPECT_NE(text.find("heartbeat_status_ok" + labels + " 1\n"),
+              std::string::npos);
+    EXPECT_NE(text.find("timestamp_seconds" + labels + " 100.000000\n"),
+              std::string::npos);
+}
+
+TEST(MasterHeartbeatMetricTest, ReconnectRejectsLateSuccessAndFailure) {
+    MasterHeartbeatMetric metric;
+    Connect(metric);
+    const auto old = metric.BeginObservation();
+    metric.Observe(old, true, 100);
+    const auto connection = metric.BeginConnection();
+    EXPECT_TRUE(Serialize(metric).empty());
+    EXPECT_FALSE(metric.BeginObservation());
+    metric.Observe(old, true, 200);
+    EXPECT_TRUE(Serialize(metric).empty());
+    metric.EndConnection(connection, true);
+    metric.Observe(old, true, 300);
+    EXPECT_TRUE(Serialize(metric).empty());
+    metric.Observe(metric.BeginObservation(), false, 400);
+    const auto current = Serialize(metric);
+    metric.Observe(old, std::nullopt, 0);
+    EXPECT_EQ(Serialize(metric), current);
+    metric.Observe(old, true, 500);
+    EXPECT_EQ(Serialize(metric), current);
+}
+
+TEST(MasterHeartbeatMetricTest, PingStartedDuringConnectCannotPublish) {
+    MasterHeartbeatMetric metric;
+    const auto connection = metric.BeginConnection();
+    const auto observation = metric.BeginObservation();
+    metric.EndConnection(connection, true);
+    metric.Observe(observation, true, 100);
+    EXPECT_TRUE(Serialize(metric).empty());
+}
+
+TEST(MasterHeartbeatMetricTest, FailedConnectRemainsUnknown) {
+    MasterHeartbeatMetric metric;
+    Connect(metric);
+    metric.Observe(metric.BeginObservation(), true, 100);
+    const auto connection = metric.BeginConnection();
+    metric.EndConnection(connection, false);
+    EXPECT_FALSE(metric.BeginObservation());
+    EXPECT_TRUE(Serialize(metric).empty());
+    Connect(metric);
+    metric.Observe(metric.BeginObservation(), true, 200);
+    EXPECT_NE(Serialize(metric).find("timestamp_seconds 200.000000\n"),
+              std::string::npos);
+}
+
+TEST(MasterHeartbeatMetricTest, OldConnectionCompletionCannotEnableNewOne) {
+    MasterHeartbeatMetric metric;
+    const auto old = metric.BeginConnection();
+    const auto current = metric.BeginConnection();
+    metric.EndConnection(old, true);
+    EXPECT_FALSE(metric.BeginObservation());
+    metric.EndConnection(current, true);
+    EXPECT_EQ(metric.BeginObservation(), current);
+}
+
+TEST(MasterHeartbeatMetricTest, ConcurrentScrapesKeepObservationTogether) {
+    MasterHeartbeatMetric metric;
+    Connect(metric);
+    const auto generation = metric.BeginObservation();
+    metric.Observe(generation, false, 100);
+    const auto first = Serialize(metric);
+    metric.Observe(generation, true, 200);
+    const auto second = Serialize(metric);
+    std::atomic<bool> start{false};
+    std::thread writer([&] {
+        while (!start.load()) std::this_thread::yield();
+        for (int i = 0; i < 10000; ++i) {
+            metric.Observe(generation, false, 100);
+            metric.Observe(generation, std::nullopt, 0);
+            metric.Observe(generation, true, 200);
+        }
+    });
+    start.store(true);
+    for (int i = 0; i < 10000; ++i) {
+        const auto text = Serialize(metric);
+        EXPECT_TRUE(text.empty() || text == first || text == second);
+    }
+    writer.join();
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_metrics_test.cpp b/mooncake-store/tests/master_metrics_test.cpp
index 6f6889d59e..3f6913d0c1 100644
--- a/mooncake-store/tests/master_metrics_test.cpp
+++ b/mooncake-store/tests/master_metrics_test.cpp
@@ -2,6 +2,7 @@
 #include <gtest/gtest.h>
 
 #include <algorithm>
+#include <atomic>
 #include <chrono>
 #include <cmath>
 #include <csignal>
@@ -10,7 +11,7 @@
 
 #include <ylt/coro_http/coro_http_client.hpp>
 
-#include "utils.h"
+#include "common/network.h"
 #include "master_admin_service.h"
 #include "master_service.h"
 #include "segment.h"
@@ -18,6 +19,7 @@
 #include "types.h"
 #include "master_config.h"
 #include "master_metric_manager.h"
+#include "version.h"
 
 namespace mooncake::test {
 
@@ -51,7 +53,6 @@ TEST_F(MasterMetricsTest, InitialStatusTest) {
     // Mem Storage Metrics
     ASSERT_EQ(metrics.get_allocated_mem_size(), 0);
     ASSERT_EQ(metrics.get_total_mem_capacity(), 0);
-    ASSERT_DOUBLE_EQ(metrics.get_global_mem_used_ratio(), 0.0);
 
     // File Storage Metrics
     ASSERT_EQ(metrics.get_allocated_file_size(), 0);
@@ -63,6 +64,10 @@ TEST_F(MasterMetricsTest, InitialStatusTest) {
 
     // Operation Statistics
     ASSERT_EQ(metrics.get_put_start_requests(), 0);
+    ASSERT_EQ(metrics.get_put_start_object_already_exists(), 0);
+    EXPECT_NE(metrics.serialize_metrics().find(
+                  "master_put_start_object_already_exists_total 0\n"),
+              std::string::npos);
     ASSERT_EQ(metrics.get_put_start_failures(), 0);
     ASSERT_EQ(metrics.get_put_start_alloc_failures(), 0);
     ASSERT_EQ(metrics.get_put_start_partial_allocations(), 0);
@@ -116,6 +121,10 @@ TEST_F(MasterMetricsTest, InitialStatusTest) {
     ASSERT_EQ(metrics.get_batch_get_replica_list_failed_items(), 0);
     ASSERT_EQ(metrics.get_batch_put_start_requests(), 0);
     ASSERT_EQ(metrics.get_batch_put_start_failures(), 0);
+    ASSERT_EQ(metrics.get_batch_put_start_object_already_exists(), 0);
+    EXPECT_NE(metrics.serialize_metrics().find(
+                  "master_batch_put_start_object_already_exists_total 0\n"),
+              std::string::npos);
     ASSERT_EQ(metrics.get_batch_put_start_partial_successes(), 0);
     ASSERT_EQ(metrics.get_batch_put_start_items(), 0);
     ASSERT_EQ(metrics.get_batch_put_start_failed_items(), 0);
@@ -136,6 +145,21 @@ TEST_F(MasterMetricsTest, InitialStatusTest) {
     ASSERT_EQ(metrics.get_put_start_discarded_staging_size(), 0);
 }
 
+TEST_F(MasterMetricsTest, ClientOffboardingMetricsAreExported) {
+    auto& metrics = MasterMetricManager::instance();
+    metrics.inc_client_offboarding_alert();
+    const auto serialized = metrics.serialize_metrics();
+
+    EXPECT_NE(serialized.find("master_client_liveness_active_clients"),
+              std::string::npos);
+    EXPECT_NE(serialized.find("master_client_offboarding_queue_depth"),
+              std::string::npos);
+    EXPECT_NE(serialized.find("master_client_offboarding_retries_total"),
+              std::string::npos);
+    EXPECT_NE(serialized.find("master_client_offboarding_alerts_total"),
+              std::string::npos);
+}
+
 TEST_F(MasterMetricsTest, BasicRequestTest) {
     const uint64_t default_kv_lease_ttl = 100;
     auto& metrics = MasterMetricManager::instance();
@@ -166,11 +190,9 @@ TEST_F(MasterMetricsTest, BasicRequestTest) {
     ASSERT_TRUE(mount_result.has_value());
     ASSERT_EQ(metrics.get_allocated_mem_size(), 0);
     ASSERT_EQ(metrics.get_total_mem_capacity(), kSegmentSize);
-    ASSERT_DOUBLE_EQ(metrics.get_global_mem_used_ratio(), 0.0);
     ASSERT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
     ASSERT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
               kSegmentSize);
-    ASSERT_DOUBLE_EQ(metrics.get_segment_mem_used_ratio(segment.name), 0.0);
     ASSERT_EQ(metrics.get_mount_segment_requests(), 1);
     ASSERT_EQ(metrics.get_mount_segment_failures(), 0);
 
@@ -262,17 +284,23 @@ TEST_F(MasterMetricsTest, BasicRequestTest) {
     ASSERT_TRUE(unmount_result.has_value());
     ASSERT_EQ(metrics.get_unmount_segment_requests(), 1);
     ASSERT_EQ(metrics.get_unmount_segment_failures(), 0);
-    ASSERT_EQ(metrics.get_key_count(), 0);
-    ASSERT_EQ(metrics.get_allocated_mem_size(), 0);
     ASSERT_EQ(metrics.get_total_mem_capacity(), 0);
-    ASSERT_DOUBLE_EQ(metrics.get_global_mem_used_ratio(), 0.0);
-    ASSERT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
     ASSERT_EQ(metrics.get_segment_total_mem_capacity(segment.name), 0);
-    ASSERT_DOUBLE_EQ(metrics.get_segment_mem_used_ratio(segment.name), 0.0);
 
-    // check segment mem used ratio for non-existent segment
-    ASSERT_DOUBLE_EQ(metrics.get_segment_mem_used_ratio(""), 0.0);
-    ASSERT_DOUBLE_EQ(metrics.get_segment_mem_used_ratio("xxxxxx_segment"), 0.0);
+    // Unmount removes the segment capacity synchronously, but invalid replica
+    // metadata and its allocation metrics are reclaimed by the background
+    // cleanup worker.
+    const auto cleanup_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    while ((metrics.get_key_count() != 0 ||
+            metrics.get_allocated_mem_size() != 0 ||
+            metrics.get_segment_allocated_mem_size(segment.name) != 0) &&
+           std::chrono::steady_clock::now() < cleanup_deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    ASSERT_EQ(metrics.get_key_count(), 0);
+    ASSERT_EQ(metrics.get_allocated_mem_size(), 0);
+    ASSERT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
 }
 
 TEST_F(MasterMetricsTest, ServiceTeardownReleasesSegmentCapacity) {
@@ -316,14 +344,27 @@ TEST_F(MasterMetricsTest, SnapshotReaderTeardownKeepsCapacityIntact) {
     segment.base = 0x300000000;
     segment.size = 1024 * 1024 * 16;
     UUID client_id = generate_uuid();
-    ASSERT_EQ(
-        source_manager.getSegmentAccess().MountSegment(segment, client_id),
-        ErrorCode::OK);
+    ASSERT_EQ(source_manager.getSegmentAccess().MountSegment(
+                  segment, client_id,
+                  std::make_shared<ClientLivenessRecord>(
+                      ClientLivenessRecord::Clock::now())),
+              ErrorCode::OK);
     const int64_t capacity_after_mount = metrics.get_total_mem_capacity();
     ASSERT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
               static_cast<int64_t>(segment.size));
 
-    auto snapshot = SegmentSerializer(&source_manager).Serialize();
+    constexpr size_t kAllocationSize = 4 * 1024 * 1024;
+    std::shared_ptr<BufferAllocatorBase> source_allocator;
+    {
+        auto access = source_manager.getSegmentAccess();
+        source_allocator = access.GetAllocator(segment.id);
+    }
+    ASSERT_NE(source_allocator, nullptr);
+    auto source_buffer = source_allocator->allocate(kAllocationSize);
+    ASSERT_NE(source_buffer, nullptr);
+
+    auto snapshot =
+        SegmentSerializer(&source_manager).Serialize(LocalSsdPersistedState{});
     ASSERT_TRUE(snapshot.has_value());
 
     {
@@ -335,12 +376,28 @@ TEST_F(MasterMetricsTest, SnapshotReaderTeardownKeepsCapacityIntact) {
         SegmentSerializer reader_serializer(&reader);
         ASSERT_TRUE(
             reader_serializer.Deserialize(snapshot.value()).has_value());
+        const auto restored_usage = reader.GetMemoryUsageSnapshot();
+        const auto restored_aggregate = reader.GetMemoryUsage();
+        EXPECT_EQ(restored_usage.used_bytes, kAllocationSize);
+        EXPECT_EQ(restored_usage.capacity_bytes, segment.size);
+        EXPECT_DOUBLE_EQ(restored_usage.used_ratio(), 0.25);
+        EXPECT_EQ(restored_aggregate.used_bytes, kAllocationSize);
+        EXPECT_EQ(restored_aggregate.capacity_bytes, segment.size);
+        EXPECT_DOUBLE_EQ(restored_aggregate.used_ratio(), 0.25);
+        ASSERT_EQ(restored_usage.segments.size(), 1u);
+        EXPECT_EQ(restored_usage.segments.at(segment.name).used_bytes,
+                  kAllocationSize);
+
+        reader_serializer.Reset();
+        EXPECT_EQ(reader.GetMemoryUsage().used_bytes, 0u);
+        EXPECT_EQ(reader.GetMemoryUsage().capacity_bytes, 0u);
     }
     ASSERT_EQ(metrics.get_total_mem_capacity(), capacity_after_mount);
     ASSERT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
               static_cast<int64_t>(segment.size));
 
     // Unmount to restore the gauges for the other tests.
+    source_buffer.reset();
     {
         auto access = source_manager.getSegmentAccess();
         size_t dec_capacity = 0;
@@ -487,6 +544,14 @@ TEST_F(MasterMetricsTest, CalcCacheStatsTest) {
 }
 
 TEST_F(MasterMetricsTest, AdminServerExposesStandbyStateWithoutService) {
+    TieredStorageUsageSnapshot stale_storage;
+    stale_storage.memory.used_bytes = 4096;
+    stale_storage.memory.capacity_bytes = 8192;
+    stale_storage.memory.segments["stale_leader_segment"] = {4096, 8192};
+    auto& metrics = MasterMetricManager::instance();
+    metrics.project_storage_usage(stale_storage);
+    ASSERT_EQ(metrics.get_allocated_mem_size(), 4096);
+
     const int http_port = getFreeTcpPort();
     MasterAdminServer admin_server(static_cast<uint16_t>(http_port),
                                    /*enable_metric_reporting=*/false);
@@ -505,6 +570,17 @@ TEST_F(MasterMetricsTest, AdminServerExposesStandbyStateWithoutService) {
     EXPECT_EQ(status_resp.http_status, 200);
     EXPECT_EQ(status_resp.body, "standby");
 
+    auto metrics_resp = FetchUrl(http_port, "/metrics");
+    EXPECT_EQ(metrics_resp.http_status, 200);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), 0);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), 0);
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size("stale_leader_segment"),
+              0);
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity("stale_leader_segment"),
+              0);
+    EXPECT_EQ(metrics_resp.body.find("stale_leader_segment"),
+              std::string::npos);
+
     auto leader_resp = FetchUrl(http_port, "/leader");
     EXPECT_EQ(leader_resp.http_status, 200);
     EXPECT_NE(leader_resp.body.find("\"present\":true"), std::string::npos);
@@ -524,6 +600,36 @@ TEST_F(MasterMetricsTest, AdminServerExposesStandbyStateWithoutService) {
     admin_server.Stop();
 }
 
+TEST_F(MasterMetricsTest, ProjectStorageUsageRemovesAbsentSegmentLabels) {
+    auto& metrics = MasterMetricManager::instance();
+    const std::string mem_segment = "projected_removed_mem_segment";
+    const std::string nof_segment = "projected_removed_nof_segment";
+
+    TieredStorageUsageSnapshot snapshot;
+    snapshot.memory.used_bytes = 4096;
+    snapshot.memory.capacity_bytes = 8192;
+    snapshot.memory.segments[mem_segment] = {4096, 8192};
+    snapshot.nof.used_bytes = 1024;
+    snapshot.nof.capacity_bytes = 4096;
+    snapshot.nof.segments[nof_segment] = {1024, 4096};
+    metrics.project_storage_usage(snapshot);
+
+    const std::string with_labels = metrics.serialize_metrics();
+    EXPECT_NE(with_labels.find("segment=\"" + mem_segment + "\""),
+              std::string::npos);
+    EXPECT_NE(with_labels.find("segment=\"" + nof_segment + "\""),
+              std::string::npos);
+
+    metrics.project_storage_usage({});
+    const std::string after = metrics.serialize_metrics();
+    EXPECT_EQ(after.find("segment=\"" + mem_segment + "\""), std::string::npos);
+    EXPECT_EQ(after.find("segment=\"" + nof_segment + "\""), std::string::npos);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), 0);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), 0);
+    EXPECT_EQ(metrics.get_allocated_nof_size(), 0);
+    EXPECT_EQ(metrics.get_total_nof_capacity(), 0);
+}
+
 TEST_F(MasterMetricsTest, AdminServerRoutesServiceEndpointsWhenAvailable) {
     WrappedMasterServiceConfig service_config;
     service_config.default_kv_lease_ttl = 100;
@@ -537,6 +643,13 @@ TEST_F(MasterMetricsTest, AdminServerRoutesServiceEndpointsWhenAvailable) {
     segment.size = 8 * 1024 * 1024;
     UUID client_id = generate_uuid();
     ASSERT_TRUE(service->MountSegment(segment, client_id).has_value());
+    ReplicateConfig config;
+    config.replica_num = 1;
+    constexpr size_t kAllocationSize = 4096;
+    ASSERT_TRUE(service
+                    ->PutStart(client_id, "admin_metrics_projection_key",
+                               kAllocationSize, config)
+                    .has_value());
 
     const int http_port = getFreeTcpPort();
     MasterAdminServer admin_server(static_cast<uint16_t>(http_port),
@@ -546,6 +659,55 @@ TEST_F(MasterMetricsTest, AdminServerRoutesServiceEndpointsWhenAvailable) {
     admin_server.SetServiceDelegate(service);
     admin_server.SetServiceAvailable(true);
 
+    auto& metrics = MasterMetricManager::instance();
+    metrics.reset_allocated_mem_size();
+    metrics.reset_total_mem_capacity();
+    metrics.reset_segment_allocated_mem_size(segment.name);
+    metrics.reset_segment_total_mem_capacity(segment.name);
+    ASSERT_EQ(metrics.get_allocated_mem_size(), 0);
+    ASSERT_EQ(metrics.get_total_mem_capacity(), 0);
+
+    auto metrics_resp = FetchUrl(http_port, "/metrics");
+    EXPECT_EQ(metrics_resp.http_status, 200);
+    EXPECT_NE(metrics_resp.body.find("master_allocated_bytes 4096"),
+              std::string::npos);
+    EXPECT_NE(metrics_resp.body.find("master_total_capacity_bytes 8388608"),
+              std::string::npos);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), kAllocationSize);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), segment.size);
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name),
+              kAllocationSize);
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
+              segment.size);
+
+    // Losing service availability must clear the old leader projection even
+    // while the delegate remains installed. A concurrent refresh is
+    // serialized with this transition and cannot restore stale values.
+    admin_server.SetServiceAvailable(false);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), 0);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), 0);
+    {
+        const std::string serialized = metrics.serialize_metrics();
+        EXPECT_EQ(serialized.find("segment=\"" + segment.name + "\""),
+                  std::string::npos);
+    }
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name), 0);
+
+    metrics_resp = FetchUrl(http_port, "/metrics");
+    EXPECT_EQ(metrics_resp.http_status, 200);
+    EXPECT_NE(metrics_resp.body.find("master_allocated_bytes 0"),
+              std::string::npos);
+    EXPECT_NE(metrics_resp.body.find("master_total_capacity_bytes 0"),
+              std::string::npos);
+    EXPECT_EQ(metrics_resp.body.find("segment=\"" + segment.name + "\""),
+              std::string::npos);
+    admin_server.SetServiceAvailable(true);
+    metrics_resp = FetchUrl(http_port, "/metrics");
+    EXPECT_EQ(metrics_resp.http_status, 200);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), kAllocationSize);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), segment.size);
+
     auto segments_resp = FetchUrl(http_port, "/get_all_segments");
     EXPECT_EQ(segments_resp.http_status, 200);
     EXPECT_NE(segments_resp.body.find(segment.name), std::string::npos);
@@ -566,6 +728,12 @@ TEST_F(MasterMetricsTest, AdminServerRoutesServiceEndpointsWhenAvailable) {
     EXPECT_NE(detail_resp.body.find("\"allocator_capacity_bytes\""),
               std::string::npos);
 
+    ASSERT_TRUE(service
+                    ->PutRevoke(client_id, "admin_metrics_projection_key",
+                                ReplicaType::MEMORY)
+                    .has_value());
+    ASSERT_TRUE(service->UnmountSegment(segment.id, client_id).has_value());
+
     admin_server.Stop();
 }
 
@@ -1021,6 +1189,227 @@ TEST_F(MasterMetricsTest, SsdOffloadCacheHitAndTotalConsistent) {
     service_.Remove(ssd_only_key, "default");
 }
 
+// Build info is an "info"-style metric: the value is always 1 and the version
+// strings are carried by labels, so serialization must emit a single series
+// containing both version labels.
+TEST_F(MasterMetricsTest, BuildInfoMetricIsSerialized) {
+    auto& metrics = MasterMetricManager::instance();
+
+    const std::string serialized = metrics.serialize_metrics();
+
+    ASSERT_NE(serialized.find("mooncake_build_info"), std::string::npos)
+        << "build info metric missing from serialized output";
+    // Label order inside the series is not asserted: only the presence of both
+    // labels with the compiled-in values matters for scraping and grouping.
+    EXPECT_NE(serialized.find("version=\"" + GetMooncakeStoreVersion() + "\""),
+              std::string::npos)
+        << "RPC handshake version missing from build info labels";
+    EXPECT_NE(serialized.find("display_version=\"" +
+                              std::string(MOONCAKE_DISPLAY_VERSION) + "\""),
+              std::string::npos)
+        << "display version missing from build info labels";
+
+    // The series value is fixed at 1; extract the number after the closing
+    // brace of the build info series to confirm it is exposed as such.
+    const auto metric_pos = serialized.find("mooncake_build_info{");
+    ASSERT_NE(metric_pos, std::string::npos)
+        << "build info metric has no labelled series";
+    const auto brace_end = serialized.find('}', metric_pos);
+    ASSERT_NE(brace_end, std::string::npos);
+    const auto line_end = serialized.find('\n', brace_end);
+    const std::string value_part =
+        serialized.substr(brace_end + 1, line_end == std::string::npos
+                                             ? std::string::npos
+                                             : line_end - brace_end - 1);
+    EXPECT_NE(value_part.find('1'), std::string::npos)
+        << "build info value should be 1, got:" << value_part;
+}
+
+// Verify the five SSD offload lifecycle counters increment per client_id
+// label. MasterMetricManager is a process-wide singleton without reset APIs,
+// so the test uses unique client_id labels whose values are determined solely
+// by this test, independent of cumulative singleton state from other tests.
+TEST_F(MasterMetricsTest, OffloadCountersIncrementByClient) {
+    auto& mm = MasterMetricManager::instance();
+    const std::string cid_a = "offload-metric-test-a";
+    const std::string cid_b = "offload-metric-test-b";
+
+    mm.inc_offload_enqueued(cid_a, 10);
+    mm.inc_offload_enqueued(cid_b, 5);
+    mm.inc_offload_completed(cid_a, 7);
+    mm.inc_offload_failed(cid_a, 2);
+    mm.inc_offload_cancelled(cid_a, 1);
+    mm.inc_offload_enqueue_rejected(cid_b, 3);
+
+    const std::string out = mm.serialize_metrics();
+    EXPECT_NE(out.find("master_offload_enqueued_total{client_id=\"offload-"
+                       "metric-test-a\"} 10"),
+              std::string::npos);
+    EXPECT_NE(out.find("master_offload_enqueued_total{client_id=\"offload-"
+                       "metric-test-b\"} 5"),
+              std::string::npos);
+    EXPECT_NE(out.find("master_offload_completed_total{client_id=\"offload-"
+                       "metric-test-a\"} 7"),
+              std::string::npos);
+    EXPECT_NE(out.find("master_offload_failed_total{client_id=\"offload-metric-"
+                       "test-a\"} 2"),
+              std::string::npos);
+    EXPECT_NE(out.find("master_offload_cancelled_total{client_id=\"offload-"
+                       "metric-test-a\"} 1"),
+              std::string::npos);
+    EXPECT_NE(out.find("master_offload_enqueue_rejected_total{client_id="
+                       "\"offload-metric-test-b\"} 3"),
+              std::string::npos);
+}
+
+// Capture only the removed diagnostics; generic verbose RPC tracing remains.
+class DuplicatePutLogSink : public google::LogSink {
+   public:
+    DuplicatePutLogSink() : old_verbosity_(FLAGS_v) {
+        google::AddLogSink(this);
+    }
+    ~DuplicatePutLogSink() override {
+        google::RemoveLogSink(this);
+        FLAGS_v = old_verbosity_;
+    }
+    void send(google::LogSeverity, const char*, const char*, int,
+              const struct ::tm*, const char* message,
+              size_t message_len) override {
+        const std::string text(message, message_len);
+        if (text.find("info=object_already_exists") != std::string::npos ||
+            (text.find("BatchPutStart failed for key[") != std::string::npos &&
+             text.find("OBJECT_ALREADY_EXISTS") != std::string::npos)) {
+            duplicate_logs.fetch_add(1);
+        }
+        if (text.find("BatchPutStart: keys.size()=") != std::string::npos) {
+            other_errors.fetch_add(1);
+        }
+    }
+    std::atomic<int> duplicate_logs{0};
+    std::atomic<int> other_errors{0};
+
+   private:
+    int old_verbosity_;
+};
+
+TEST_F(MasterMetricsTest, DuplicatePutResponsesCountItemsWithoutPerKeyLogs) {
+    auto& metrics = MasterMetricManager::instance();
+    DuplicatePutLogSink sink;
+    // Cover both verbosity levels and both batch placement paths.
+    for (int verbosity : {0, 1}) {
+        FLAGS_v = verbosity;
+        for (bool same_node : {false, true}) {
+            SCOPED_TRACE(::testing::Message()
+                         << "v=" << verbosity << ", same_node=" << same_node);
+            WrappedMasterServiceConfig service_config;
+            service_config.default_kv_lease_ttl = 100;
+            service_config.enable_metric_reporting = false;
+            WrappedMasterService service(service_config);
+            const auto client_id = generate_uuid();
+            Segment segment;
+            segment.id = generate_uuid();
+            segment.name = "duplicate_metric_segment";
+            segment.base = 0x300000000;
+            segment.size = 16 * 1024 * 1024;
+            ASSERT_TRUE(service.MountSegment(segment, client_id));
+            ReplicateConfig config;
+            config.replica_num = 1;
+            config.prefer_alloc_in_same_node = same_node;
+            const auto single_baseline =
+                metrics.get_put_start_object_already_exists();
+            const auto batch_baseline =
+                metrics.get_batch_put_start_object_already_exists();
+            auto expect_duplicates = [&](int64_t single, int64_t batch) {
+                EXPECT_EQ(metrics.get_put_start_object_already_exists(),
+                          single_baseline + single);
+                EXPECT_EQ(metrics.get_batch_put_start_object_already_exists(),
+                          batch_baseline + batch);
+            };
+            const auto single_failures = metrics.get_put_start_failures();
+            const auto batch_failures = metrics.get_batch_put_start_failures();
+            const auto partial =
+                metrics.get_batch_put_start_partial_successes();
+
+            ASSERT_TRUE(service.PutStart(client_id, "existing", 1024, config));
+            ASSERT_TRUE(service.PutEnd(client_id,
+                                       ObjectMeta{"existing", std::nullopt},
+                                       ReplicaType::MEMORY));
+            expect_duplicates(0, 0);
+            auto duplicate =
+                service.PutStart(client_id, "existing", 1024, config);
+            ASSERT_FALSE(duplicate);
+            EXPECT_EQ(duplicate.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+            expect_duplicates(1, 0);
+            EXPECT_EQ(metrics.get_put_start_failures(), single_failures + 1);
+
+            auto all = service.BatchPutStart(
+                client_id, {"existing", "existing"}, {1024, 1024}, config);
+            ASSERT_EQ(all.size(), 2);
+            for (const auto& result : all) {
+                ASSERT_FALSE(result);
+                EXPECT_EQ(result.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+            }
+            expect_duplicates(1, 2);
+            EXPECT_EQ(metrics.get_batch_put_start_failures(),
+                      batch_failures + 1);
+
+            auto mixed = service.BatchPutStart(client_id, {"existing", "new"},
+                                               {1024, 1024}, config);
+            ASSERT_EQ(mixed.size(), 2);
+            ASSERT_FALSE(mixed[0]);
+            EXPECT_EQ(mixed[0].error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+            EXPECT_TRUE(mixed[1]);
+            expect_duplicates(1, 3);
+            EXPECT_EQ(metrics.get_batch_put_start_partial_successes(),
+                      partial + 1);
+
+            // Also count an unfinished duplicate and another attempt at the
+            // key.
+            auto processing = service.PutStart(client_id, "new", 1024, config);
+            ASSERT_FALSE(processing);
+            EXPECT_EQ(processing.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+            expect_duplicates(2, 3);
+            auto invalid =
+                service.BatchPutStart(client_id, {"existing"}, {}, config);
+            ASSERT_EQ(invalid.size(), 1);
+            ASSERT_FALSE(invalid[0]);
+            EXPECT_EQ(invalid[0].error(), ErrorCode::INVALID_PARAMS);
+            EXPECT_TRUE(
+                service.BatchPutStart(client_id, {}, {}, config).empty());
+            expect_duplicates(2, 3);
+        }
+    }
+    EXPECT_EQ(sink.duplicate_logs.load(), 0);
+    EXPECT_EQ(sink.other_errors.load(), 4);
+
+    const std::string sample =
+        "master_put_start_object_already_exists_total " +
+        std::to_string(metrics.get_put_start_object_already_exists()) + "\n";
+    const std::string batch_sample =
+        "master_batch_put_start_object_already_exists_total " +
+        std::to_string(metrics.get_batch_put_start_object_already_exists()) +
+        "\n";
+    const auto serialized = metrics.serialize_metrics();
+    EXPECT_NE(serialized.find(batch_sample), std::string::npos);
+    EXPECT_NE(serialized.find(
+                  "# TYPE master_batch_put_start_object_already_exists_total "
+                  "counter"),
+              std::string::npos);
+    EXPECT_NE(serialized.find(sample), std::string::npos);
+    EXPECT_NE(
+        serialized.find(
+            "# TYPE master_put_start_object_already_exists_total counter"),
+        std::string::npos);
+    const int port = getFreeTcpPort();
+    MasterAdminServer admin_server(static_cast<uint16_t>(port),
+                                   /*enable_metric_reporting=*/false);
+    ASSERT_TRUE(admin_server.Start());
+    const auto response = FetchUrl(port, "/metrics");
+    EXPECT_EQ(response.http_status, 200);
+    EXPECT_NE(response.body.find(sample), std::string::npos);
+    EXPECT_NE(response.body.find(batch_sample), std::string::npos);
+}
+
 }  // namespace mooncake::test
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/master_scenario.cpp b/mooncake-store/tests/master_scenario.cpp
deleted file mode 100644
index ccf4187bf3..0000000000
--- a/mooncake-store/tests/master_scenario.cpp
+++ /dev/null
@@ -1,252 +0,0 @@
-#include "master_scenario.h"
-
-#include <gtest/gtest.h>
-
-#include <algorithm>
-#include <utility>
-
-#include "types.h"
-
-namespace mooncake::test {
-namespace {
-
-constexpr uint64_t kFnvOffset = 14695981039346656037ULL;
-constexpr uint64_t kFnvPrime = 1099511628211ULL;
-
-uint64_t StableHash(std::string_view kind, std::string_view name,
-                    uint64_t seed) {
-    uint64_t hash = seed;
-    for (const char value : kind) {
-        hash = (hash ^ static_cast<unsigned char>(value)) * kFnvPrime;
-    }
-    for (const char value : name) {
-        hash = (hash ^ static_cast<unsigned char>(value)) * kFnvPrime;
-    }
-    return hash;
-}
-
-UUID StableUuid(std::string_view kind, std::string_view name) {
-    return {StableHash(kind, name, kFnvOffset),
-            StableHash(kind, name, kFnvOffset ^ 0x9e3779b97f4a7c15ULL)};
-}
-
-}  // namespace
-
-MemoryNodeSpec MemoryNode(std::string name) {
-    return {.name = std::move(name)};
-}
-
-PutStartAction<> PutStart(std::string key, uint64_t size) {
-    return PutStartAction<>(std::move(key), size);
-}
-
-PutEndAction PutEnd(std::string key) { return {.key = std::move(key)}; }
-
-PutRevokeAction PutRevoke(std::string key) { return {.key = std::move(key)}; }
-
-RemoveAction Remove(std::string key) { return {.key = std::move(key)}; }
-
-ObjectSpec<> Object(std::string key) { return ObjectSpec<>(std::move(key)); }
-
-MasterScenario::MasterScenario(std::string name) : name_(std::move(name)) {}
-
-MasterScenario::~MasterScenario() = default;
-
-MasterScenario& MasterScenario::Given(MemoryNodeSpec node) {
-    if (declarations_frozen_) {
-        Fail("MemoryNode declarations must precede actions and assertions");
-        return *this;
-    }
-    if (node.name.empty()) {
-        Fail("MemoryNode requires a name");
-        return *this;
-    }
-    if (node.capacity == 0) {
-        Fail("MemoryNode " + node.name + " requires non-zero capacity");
-        return *this;
-    }
-    const auto duplicate = std::find_if(
-        nodes_.begin(), nodes_.end(),
-        [&](const auto& existing) { return existing.name == node.name; });
-    if (duplicate != nodes_.end()) {
-        Fail("duplicate MemoryNode " + node.name);
-        return *this;
-    }
-    nodes_.push_back(std::move(node));
-    return *this;
-}
-
-MasterScenario& MasterScenario::WhenPutStart(PutStartActionData action) {
-    if (!EnsureService()) {
-        return *this;
-    }
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    const auto result =
-        service_->PutStart(ActorId(action.actor), action.key,
-                           TenantId::Default(), action.size, config);
-    ValidateActionResult("PutStart(" + action.key + ")", action.expected_error,
-                         result.has_value(),
-                         result ? ErrorCode::OK : result.error());
-    if (!result) {
-        return *this;
-    }
-    if (action.expected_replica_count.has_value() &&
-        result->size() != *action.expected_replica_count) {
-        Fail("PutStart(" + action.key + ") returned " +
-             std::to_string(result->size()) + " replicas; expected " +
-             std::to_string(*action.expected_replica_count));
-    }
-    if (action.expected_replica_status.has_value() &&
-        std::any_of(result->begin(), result->end(), [&](const auto& replica) {
-            return replica.status != *action.expected_replica_status;
-        })) {
-        Fail("PutStart(" + action.key + ") replica status mismatch");
-    }
-    return *this;
-}
-
-MasterScenario& MasterScenario::When(PutEndAction action) {
-    if (!EnsureService()) {
-        return *this;
-    }
-
-    const auto result =
-        service_->PutEnd(ActorId(action.actor), action.key, TenantId::Default(),
-                         ReplicaType::MEMORY);
-    ValidateActionResult("PutEnd(" + action.key + ")", action.expected_error,
-                         result.has_value(),
-                         result ? ErrorCode::OK : result.error());
-    return *this;
-}
-
-MasterScenario& MasterScenario::When(PutRevokeAction action) {
-    if (!EnsureService()) {
-        return *this;
-    }
-
-    const auto result =
-        service_->PutRevoke(ActorId(action.actor), action.key,
-                            TenantId::Default(), ReplicaType::MEMORY);
-    ValidateActionResult("PutRevoke(" + action.key + ")", action.expected_error,
-                         result.has_value(),
-                         result ? ErrorCode::OK : result.error());
-    return *this;
-}
-
-MasterScenario& MasterScenario::When(RemoveAction action) {
-    if (!EnsureService()) {
-        return *this;
-    }
-
-    const auto result = service_->Remove(action.key, TenantId::Default());
-    ValidateActionResult("Remove(" + action.key + ")", action.expected_error,
-                         result.has_value(),
-                         result ? ErrorCode::OK : result.error());
-    return *this;
-}
-
-MasterScenario& MasterScenario::ThenObject(ObjectSpecData object,
-                                           ObjectExpectation expectation) {
-    if (!EnsureService()) {
-        return *this;
-    }
-
-    const auto result =
-        service_->GetReplicaList(object.key, TenantId::Default());
-    if (expectation == ObjectExpectation::NOT_READY) {
-        if (result || result.error() != ErrorCode::REPLICA_IS_NOT_READY) {
-            Fail("Object(" + object.key + ") was expected to be not ready");
-        }
-        return *this;
-    }
-    if (!result) {
-        Fail("Object(" + object.key +
-             ") is not readable: " + toString(result.error()));
-        return *this;
-    }
-    if (result->replicas.empty()) {
-        Fail("Object(" + object.key + ") has no readable replicas");
-    }
-    if (object.expected_replica_count.has_value() &&
-        result->replicas.size() != *object.expected_replica_count) {
-        Fail("Object(" + object.key + ") has " +
-             std::to_string(result->replicas.size()) + " replicas; expected " +
-             std::to_string(*object.expected_replica_count));
-    }
-    if (object.expected_complete_replica_count.has_value()) {
-        const size_t complete =
-            std::count_if(result->replicas.begin(), result->replicas.end(),
-                          [](const auto& replica) {
-                              return replica.status == ReplicaStatus::COMPLETE;
-                          });
-        if (complete != *object.expected_complete_replica_count) {
-            Fail("Object(" + object.key + ") has " + std::to_string(complete) +
-                 " complete replicas; expected " +
-                 std::to_string(*object.expected_complete_replica_count));
-        }
-    }
-    return *this;
-}
-
-bool MasterScenario::EnsureService() {
-    if (service_) {
-        return true;
-    }
-    declarations_frozen_ = true;
-    if (nodes_.empty()) {
-        Fail("scenario requires at least one MemoryNode");
-        return false;
-    }
-
-    service_ = std::make_unique<MasterService>();
-    for (const auto& node : nodes_) {
-        Segment segment;
-        segment.id = StableUuid("segment", node.name);
-        segment.name = node.name;
-        segment.base = next_segment_base_;
-        segment.size = node.capacity;
-        segment.te_endpoint = node.name;
-        next_segment_base_ += node.capacity + 4096;
-
-        const auto result = service_->MountSegment(segment, ActorId(node.name));
-        if (!result) {
-            Fail("failed to mount MemoryNode " + node.name + ": " +
-                 toString(result.error()));
-            service_.reset();
-            return false;
-        }
-    }
-    return true;
-}
-
-UUID MasterScenario::ActorId(std::string_view actor) {
-    const std::string name(actor);
-    const auto result = actor_ids_.emplace(name, StableUuid("actor", name));
-    return result.first->second;
-}
-
-void MasterScenario::ValidateActionResult(
-    std::string_view action, const std::optional<ErrorCode>& expected_error,
-    bool succeeded, ErrorCode error) {
-    if (!expected_error.has_value()) {
-        if (!succeeded) {
-            Fail(std::string(action) + " failed: " + toString(error));
-        }
-        return;
-    }
-    if (succeeded) {
-        Fail(std::string(action) + " succeeded; expected " +
-             toString(*expected_error));
-    } else if (error != *expected_error) {
-        Fail(std::string(action) + " failed with " + toString(error) +
-             "; expected " + toString(*expected_error));
-    }
-}
-
-void MasterScenario::Fail(std::string message) const {
-    ADD_FAILURE() << "MasterScenario[" << name_ << "]: " << message;
-}
-
-}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_scenario.h b/mooncake-store/tests/master_scenario.h
deleted file mode 100644
index 850fa796a9..0000000000
--- a/mooncake-store/tests/master_scenario.h
+++ /dev/null
@@ -1,241 +0,0 @@
-#pragma once
-
-#include <cstddef>
-#include <cstdint>
-#include <memory>
-#include <optional>
-#include <string>
-#include <string_view>
-#include <unordered_map>
-#include <utility>
-#include <vector>
-
-#include "master_service.h"
-
-namespace mooncake::test {
-
-constexpr uint64_t operator""_KB(unsigned long long value) {
-    return value * 1024;
-}
-
-struct MemoryNodeSpec {
-    std::string name;
-    uint64_t capacity{16 * 1024 * 1024};
-
-    MemoryNodeSpec& Capacity(uint64_t value) {
-        capacity = value;
-        return *this;
-    }
-};
-
-MemoryNodeSpec MemoryNode(std::string name);
-
-enum class PutStartExpectation {
-    UNSPECIFIED,
-    SUCCESS,
-    ERROR,
-};
-
-struct PutStartActionData {
-    std::string key;
-    uint64_t size;
-    std::string actor{"default"};
-    std::optional<ErrorCode> expected_error{};
-    std::optional<size_t> expected_replica_count{};
-    std::optional<ReplicaStatus> expected_replica_status{};
-};
-
-template <PutStartExpectation expectation = PutStartExpectation::UNSPECIFIED>
-struct PutStartAction : PutStartActionData {
-    PutStartAction(std::string key, uint64_t size)
-        requires(expectation == PutStartExpectation::UNSPECIFIED)
-        : PutStartActionData{.key = std::move(key), .size = size} {}
-
-    PutStartAction& By(std::string value) {
-        actor = std::move(value);
-        return *this;
-    }
-
-    auto ExpectError(ErrorCode value) const
-        requires(expectation == PutStartExpectation::UNSPECIFIED)
-    {
-        PutStartAction<PutStartExpectation::ERROR> action(*this);
-        action.expected_error = value;
-        return action;
-    }
-
-    auto ExpectReplicas(size_t value) const
-        requires(expectation != PutStartExpectation::ERROR)
-    {
-        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
-        action.expected_replica_count = value;
-        return action;
-    }
-
-    auto ExpectStatus(ReplicaStatus value) const
-        requires(expectation != PutStartExpectation::ERROR)
-    {
-        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
-        action.expected_replica_status = value;
-        return action;
-    }
-
-   private:
-    template <PutStartExpectation other>
-    friend struct PutStartAction;
-
-    template <PutStartExpectation other>
-    PutStartAction(const PutStartAction<other>& action)
-        : PutStartActionData(action) {}
-};
-
-PutStartAction<> PutStart(std::string key, uint64_t size);
-
-struct PutEndAction {
-    std::string key;
-    std::string actor{"default"};
-    std::optional<ErrorCode> expected_error{};
-
-    PutEndAction& By(std::string value) {
-        actor = std::move(value);
-        return *this;
-    }
-
-    PutEndAction& ExpectError(ErrorCode value) {
-        expected_error = value;
-        return *this;
-    }
-};
-
-PutEndAction PutEnd(std::string key);
-
-struct PutRevokeAction {
-    std::string key;
-    std::string actor{"default"};
-    std::optional<ErrorCode> expected_error{};
-
-    PutRevokeAction& By(std::string value) {
-        actor = std::move(value);
-        return *this;
-    }
-
-    PutRevokeAction& ExpectError(ErrorCode value) {
-        expected_error = value;
-        return *this;
-    }
-};
-
-PutRevokeAction PutRevoke(std::string key);
-
-struct RemoveAction {
-    std::string key;
-    std::optional<ErrorCode> expected_error{};
-
-    RemoveAction& ExpectError(ErrorCode value) {
-        expected_error = value;
-        return *this;
-    }
-};
-
-RemoveAction Remove(std::string key);
-
-enum class ObjectExpectation {
-    UNSPECIFIED,
-    READABLE,
-    NOT_READY,
-};
-
-struct ObjectSpecData {
-    std::string key;
-    std::optional<size_t> expected_replica_count{};
-    std::optional<size_t> expected_complete_replica_count{};
-};
-
-template <ObjectExpectation expectation = ObjectExpectation::UNSPECIFIED>
-struct ObjectSpec : ObjectSpecData {
-    explicit ObjectSpec(std::string key)
-        requires(expectation == ObjectExpectation::UNSPECIFIED)
-        : ObjectSpecData{.key = std::move(key)} {}
-
-    auto IsReadable() const
-        requires(expectation != ObjectExpectation::NOT_READY)
-    {
-        return ObjectSpec<ObjectExpectation::READABLE>(*this);
-    }
-
-    auto IsNotReady() const
-        requires(expectation == ObjectExpectation::UNSPECIFIED)
-    {
-        return ObjectSpec<ObjectExpectation::NOT_READY>(*this);
-    }
-
-    auto HasReplicas(size_t value) const
-        requires(expectation != ObjectExpectation::NOT_READY)
-    {
-        ObjectSpec<ObjectExpectation::READABLE> object(*this);
-        object.expected_replica_count = value;
-        return object;
-    }
-
-    auto HasCompleteReplicas(size_t value) const
-        requires(expectation != ObjectExpectation::NOT_READY)
-    {
-        ObjectSpec<ObjectExpectation::READABLE> object(*this);
-        object.expected_complete_replica_count = value;
-        return object;
-    }
-
-   private:
-    template <ObjectExpectation other>
-    friend struct ObjectSpec;
-
-    template <ObjectExpectation other>
-    ObjectSpec(const ObjectSpec<other>& object) : ObjectSpecData(object) {}
-};
-
-ObjectSpec<> Object(std::string key);
-
-class MasterScenario {
-   public:
-    explicit MasterScenario(std::string name);
-    ~MasterScenario();
-
-    MasterScenario(const MasterScenario&) = delete;
-    MasterScenario& operator=(const MasterScenario&) = delete;
-
-    MasterScenario& Given(MemoryNodeSpec node);
-    template <PutStartExpectation expectation>
-    MasterScenario& When(PutStartAction<expectation> action) {
-        return WhenPutStart(std::move(action));
-    }
-
-    MasterScenario& When(PutEndAction action);
-    MasterScenario& When(PutRevokeAction action);
-    MasterScenario& When(RemoveAction action);
-
-    template <ObjectExpectation expectation>
-        requires(expectation != ObjectExpectation::UNSPECIFIED)
-    MasterScenario& Then(ObjectSpec<expectation> object) {
-        return ThenObject(std::move(object), expectation);
-    }
-
-   private:
-    MasterScenario& WhenPutStart(PutStartActionData action);
-    MasterScenario& ThenObject(ObjectSpecData object,
-                               ObjectExpectation expectation);
-    bool EnsureService();
-    UUID ActorId(std::string_view actor);
-    void ValidateActionResult(std::string_view action,
-                              const std::optional<ErrorCode>& expected_error,
-                              bool succeeded, ErrorCode error);
-    void Fail(std::string message) const;
-
-    std::string name_;
-    bool declarations_frozen_{false};
-    uintptr_t next_segment_base_{0x300000000};
-    std::vector<MemoryNodeSpec> nodes_;
-    std::unique_ptr<MasterService> service_;
-    std::unordered_map<std::string, UUID> actor_ids_;
-};
-
-}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_scenario_test.cpp b/mooncake-store/tests/master_scenario_test.cpp
deleted file mode 100644
index bea24d6761..0000000000
--- a/mooncake-store/tests/master_scenario_test.cpp
+++ /dev/null
@@ -1,120 +0,0 @@
-#include "master_scenario.h"
-
-#include <gtest/gtest-spi.h>
-#include <gtest/gtest.h>
-
-namespace mooncake::test {
-namespace {
-
-template <typename T>
-concept SupportsExpectError =
-    requires(T value) { value.ExpectError(ErrorCode::INTERNAL_ERROR); };
-
-template <typename T>
-concept SupportsExpectReplicas = requires(T value) { value.ExpectReplicas(1); };
-
-template <typename T>
-concept SupportsExpectStatus =
-    requires(T value) { value.ExpectStatus(ReplicaStatus::COMPLETE); };
-
-template <typename T>
-concept SupportsIsReadable = requires(T value) { value.IsReadable(); };
-
-template <typename T>
-concept SupportsIsNotReady = requires(T value) { value.IsNotReady(); };
-
-template <typename T>
-concept SupportsHasReplicas = requires(T value) { value.HasReplicas(1); };
-
-template <typename T>
-concept SupportsThen =
-    requires(MasterScenario& scenario, T value) { scenario.Then(value); };
-
-using ErrorExpectedPutStart =
-    decltype(PutStart("compile-time", 1_KB)
-                 .ExpectError(ErrorCode::INTERNAL_ERROR));
-using SuccessExpectedPutStart =
-    decltype(PutStart("compile-time", 1_KB).ExpectReplicas(1));
-using UnspecifiedObject = decltype(Object("compile-time"));
-using NotReadyObject = decltype(Object("compile-time").IsNotReady());
-using ReadableObject = decltype(Object("compile-time").HasReplicas(1));
-
-static_assert(!SupportsExpectReplicas<ErrorExpectedPutStart>);
-static_assert(!SupportsExpectStatus<ErrorExpectedPutStart>);
-static_assert(!SupportsExpectError<SuccessExpectedPutStart>);
-static_assert(!SupportsIsReadable<NotReadyObject>);
-static_assert(!SupportsHasReplicas<NotReadyObject>);
-static_assert(!SupportsIsNotReady<ReadableObject>);
-static_assert(!SupportsThen<UnspecifiedObject>);
-static_assert(SupportsThen<NotReadyObject>);
-static_assert(SupportsThen<ReadableObject>);
-
-}  // namespace
-
-TEST(MasterScenarioContractTest, ReportsUnexpectedActionError) {
-    EXPECT_NONFATAL_FAILURE(MasterScenario("unexpected action error")
-                                .Given(MemoryNode("memory"))
-                                .When(PutEnd("missing")),
-                            "PutEnd(missing) failed: OBJECT_NOT_FOUND");
-}
-
-TEST(MasterScenarioContractTest, ReportsUnexpectedActionSuccess) {
-    EXPECT_NONFATAL_FAILURE(
-        MasterScenario("unexpected action success")
-            .Given(MemoryNode("memory"))
-            .When(PutStart("key", 1_KB)
-                      .ExpectError(ErrorCode::OBJECT_ALREADY_EXISTS)),
-        "PutStart(key) succeeded; expected OBJECT_ALREADY_EXISTS");
-}
-
-TEST(MasterScenarioContractTest, ReportsWrongErrorCode) {
-    EXPECT_NONFATAL_FAILURE(
-        MasterScenario("wrong error code")
-            .Given(MemoryNode("memory"))
-            .When(PutEnd("missing").ExpectError(ErrorCode::ILLEGAL_CLIENT)),
-        "PutEnd(missing) failed with OBJECT_NOT_FOUND; expected "
-        "ILLEGAL_CLIENT");
-}
-
-TEST(MasterScenarioContractTest, ReportsPutStartReplicaCountMismatch) {
-    EXPECT_NONFATAL_FAILURE(MasterScenario("put start replica count mismatch")
-                                .Given(MemoryNode("memory"))
-                                .When(PutStart("key", 1_KB).ExpectReplicas(2)),
-                            "PutStart(key) returned 1 replicas; expected 2");
-}
-
-TEST(MasterScenarioContractTest, ReportsPutStartReplicaStatusMismatch) {
-    EXPECT_NONFATAL_FAILURE(
-        MasterScenario("put start replica status mismatch")
-            .Given(MemoryNode("memory"))
-            .When(PutStart("key", 1_KB).ExpectStatus(ReplicaStatus::COMPLETE)),
-        "PutStart(key) replica status mismatch");
-}
-
-TEST(MasterScenarioContractTest, ReportsUnreadableObject) {
-    EXPECT_NONFATAL_FAILURE(
-        MasterScenario("unreadable object")
-            .Given(MemoryNode("memory"))
-            .Then(Object("missing").IsReadable()),
-        "Object(missing) is not readable: OBJECT_NOT_FOUND");
-}
-
-TEST(MasterScenarioContractTest, ReportsObjectReplicaCountMismatch) {
-    EXPECT_NONFATAL_FAILURE(MasterScenario("object replica count mismatch")
-                                .Given(MemoryNode("memory"))
-                                .When(PutStart("key", 1_KB))
-                                .When(PutEnd("key"))
-                                .Then(Object("key").HasReplicas(2)),
-                            "Object(key) has 1 replicas; expected 2");
-}
-
-TEST(MasterScenarioContractTest, ReportsCompleteReplicaCountMismatch) {
-    EXPECT_NONFATAL_FAILURE(MasterScenario("complete replica count mismatch")
-                                .Given(MemoryNode("memory"))
-                                .When(PutStart("key", 1_KB))
-                                .When(PutEnd("key"))
-                                .Then(Object("key").HasCompleteReplicas(0)),
-                            "Object(key) has 1 complete replicas; expected 0");
-}
-
-}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service/CMakeLists.txt b/mooncake-store/tests/master_service/CMakeLists.txt
new file mode 100644
index 0000000000..444008f7d0
--- /dev/null
+++ b/mooncake-store/tests/master_service/CMakeLists.txt
@@ -0,0 +1 @@
+add_subdirectory(dsl)
diff --git a/mooncake-store/tests/master_service/README.md b/mooncake-store/tests/master_service/README.md
new file mode 100644
index 0000000000..5c02064af2
--- /dev/null
+++ b/mooncake-store/tests/master_service/README.md
@@ -0,0 +1,43 @@
+# Master service scenario DSL
+
+`dsl/` contains the typed `MasterScenario` vocabulary used to describe
+client-visible behavior of methods exported by the master RPC service. The test
+harness invokes `MasterService` in process, while scenarios use the same
+operations, inputs, results, and error codes that a client observes.
+
+The DSL is intentionally limited to the client boundary:
+
+- actions model exported RPC operations and make success the default;
+- expected failures must name their `ErrorCode` explicitly;
+- assertions use client-visible queries and results;
+- private indexes, metrics, allocators, background-worker state, RPC adapter
+  normalization, and subsystem invariants remain in focused direct tests.
+
+Existing MasterService tests are migrated by component in follow-up changes.
+Component-specific actions and deterministic concurrency helpers are introduced
+with their first consumer and contract coverage. The foundation introduced here
+does not reorganize or rewrite those suites.
+
+## Private-state access
+
+`master_service_test_peer.h` defines `mooncake::test::MasterServiceTestPeer`,
+the only test friend of `MasterService`. Fixtures, the scenario DSL, and the
+eviction benchmark use it instead of adding friends or public `ForTesting`
+methods to the production service:
+
+```cpp
+#include "master_service/master_service_test_peer.h"
+
+MasterServiceTestPeer peer(service);
+peer.RunBatchEvictForTesting(0.8, 0.7);
+```
+
+Add new private inspection/mutation helpers to the peer. Nontrivial test-only
+implementations live in `master_service_test_peer.cpp`; the
+`master_service_test_peer` library is built only for tests or benchmarks and is
+not linked into production targets. The Store test helpers link it automatically.
+
+Raw state accessors do not take locks. Preserve the service's lock order and
+existing synchronization when using them. Synchronous drivers must not race the
+corresponding background worker. Runtime hook invocation points remain in the
+production code; the peer only installs their callbacks.
diff --git a/mooncake-store/tests/master_service/dsl/CMakeLists.txt b/mooncake-store/tests/master_service/dsl/CMakeLists.txt
new file mode 100644
index 0000000000..53c9fedb52
--- /dev/null
+++ b/mooncake-store/tests/master_service/dsl/CMakeLists.txt
@@ -0,0 +1,8 @@
+add_library(master_service_test_dsl STATIC scenario.cpp)
+target_include_directories(master_service_test_dsl
+                           PUBLIC ${MOONCAKE_STORE_TESTS_SOURCE_DIR})
+target_link_libraries(master_service_test_dsl PUBLIC master_service_test_peer
+                                                     gtest)
+
+add_store_test(master_scenario_test scenario_contract_test.cpp)
+target_link_libraries(master_scenario_test PRIVATE master_service_test_dsl)
diff --git a/mooncake-store/tests/master_service/dsl/scenario.cpp b/mooncake-store/tests/master_service/dsl/scenario.cpp
new file mode 100644
index 0000000000..d7022dbb83
--- /dev/null
+++ b/mooncake-store/tests/master_service/dsl/scenario.cpp
@@ -0,0 +1,2252 @@
+#include "master_service/dsl/scenario.h"
+#include "master_service/master_service_test_peer.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <atomic>
+#include <filesystem>
+#include <fstream>
+#include <mutex>
+#include <thread>
+#include <utility>
+
+#include <unistd.h>
+
+#include "mutex.h"
+#include "tenant_quota_policy_store.h"
+#include "types.h"
+
+namespace mooncake::test {
+namespace {
+
+constexpr uint64_t kFnvOffset = 14695981039346656037ULL;
+constexpr uint64_t kFnvPrime = 1099511628211ULL;
+
+uint64_t StableHash(std::string_view kind, std::string_view name,
+                    uint64_t seed) {
+    uint64_t hash = seed;
+    for (const char value : kind) {
+        hash = (hash ^ static_cast<unsigned char>(value)) * kFnvPrime;
+    }
+    for (const char value : name) {
+        hash = (hash ^ static_cast<unsigned char>(value)) * kFnvPrime;
+    }
+    return hash;
+}
+
+UUID StableUuid(std::string_view kind, std::string_view name) {
+    return {StableHash(kind, name, kFnvOffset),
+            StableHash(kind, name, kFnvOffset ^ 0x9e3779b97f4a7c15ULL)};
+}
+
+}  // namespace
+
+MemoryNodeSpec MemoryNode(std::string name) {
+    MemoryNodeSpec node;
+    node.name = std::move(name);
+    return node;
+}
+
+NoFNodeSpec NoFNode(std::string name) {
+    NoFNodeSpec node;
+    node.name = std::move(name);
+    node.endpoint = node.name + "-endpoint";
+    return node;
+}
+
+TenantSpec Tenant(std::string name) { return {.name = std::move(name)}; }
+
+PutStartAction<> PutStart(std::string key, uint64_t size) {
+    return PutStartAction<>(std::move(key), size);
+}
+
+UpsertStartAction<> UpsertStart(std::string key, uint64_t size) {
+    return UpsertStartAction<>(std::move(key), size);
+}
+
+PutEndAction PutEnd(std::string key) { return {.key = std::move(key)}; }
+
+UpsertEndAction UpsertEnd(std::string key) { return {.key = std::move(key)}; }
+
+PutRevokeAction PutRevoke(std::string key) { return {.key = std::move(key)}; }
+
+UpsertRevokeAction UpsertRevoke(std::string key) {
+    return {.key = std::move(key)};
+}
+
+BatchUpsertStartAction BatchUpsertStart(
+    std::initializer_list<std::pair<std::string, uint64_t>> objects) {
+    BatchUpsertStartAction action;
+    action.keys.reserve(objects.size());
+    action.sizes.reserve(objects.size());
+    for (const auto& [key, size] : objects) {
+        action.keys.push_back(key);
+        action.sizes.push_back(size);
+    }
+    return action;
+}
+
+BatchUpsertEndAction BatchUpsertEnd(std::initializer_list<std::string> keys) {
+    BatchUpsertEndAction action;
+    action.keys.assign(keys.begin(), keys.end());
+    return action;
+}
+
+BatchRemoveAction BatchRemove(std::initializer_list<std::string> keys) {
+    BatchRemoveAction action;
+    action.keys.assign(keys.begin(), keys.end());
+    return action;
+}
+
+RemoveAction Remove(std::string key) { return {.key = std::move(key)}; }
+
+ClearReplicasAction ClearReplicas(std::initializer_list<std::string> keys) {
+    ClearReplicasAction action;
+    action.keys.assign(keys.begin(), keys.end());
+    return action;
+}
+
+CopyStartAction CopyStart(std::string key) { return {.key = std::move(key)}; }
+
+CopyEndAction CopyEnd(std::string key) { return {.key = std::move(key)}; }
+
+CopyRevokeAction CopyRevoke(std::string key) { return {.key = std::move(key)}; }
+
+MoveStartAction MoveStart(std::string key) { return {.key = std::move(key)}; }
+
+MoveEndAction MoveEnd(std::string key) { return {.key = std::move(key)}; }
+
+MoveRevokeAction MoveRevoke(std::string key) { return {.key = std::move(key)}; }
+
+CreateCopyTaskAction CreateCopyTask(std::string name, std::string key) {
+    return {.name = std::move(name), .key = std::move(key)};
+}
+
+CreateMoveTaskAction CreateMoveTask(std::string name, std::string key) {
+    return {.name = std::move(name), .key = std::move(key)};
+}
+
+FetchTasksAction FetchTasks(std::string actor) {
+    return {.actor = std::move(actor)};
+}
+
+CompleteTaskAction CompleteTask(std::string name) {
+    return {.name = std::move(name)};
+}
+
+CompleteUnknownTaskAction CompleteUnknownTask(std::string name) {
+    return {.name = std::move(name)};
+}
+
+RemoveByRegexAction RemoveByRegex(std::string pattern) {
+    return {.pattern = std::move(pattern)};
+}
+
+UnmountMemoryNodeAction UnmountMemoryNode(std::string node) {
+    UnmountMemoryNodeAction action;
+    action.node = std::move(node);
+    action.actor = action.node;
+    return action;
+}
+
+GracefulUnmountMemoryNodeAction GracefullyUnmountMemoryNode(std::string node) {
+    GracefulUnmountMemoryNodeAction action;
+    action.node = std::move(node);
+    action.actor = action.node;
+    return action;
+}
+
+MountMemorySegmentAction MountMemorySegment(std::string alias) {
+    MountMemorySegmentAction action;
+    action.alias = std::move(alias);
+    action.name = action.alias;
+    action.endpoint = action.name;
+    action.actor = action.alias;
+    return action;
+}
+
+MountUnmountMemoryCapacitiesAction MountUnmountMemoryCapacities(
+    std::string name, std::initializer_list<uint64_t> capacities) {
+    return {.name = std::move(name),
+            .capacities = {capacities.begin(), capacities.end()}};
+}
+
+RemoveAllAction RemoveAll() { return {}; }
+
+ExpireAtAction ExpireAt(std::string key,
+                        std::chrono::system_clock::time_point lease_timeout) {
+    return {.key = std::move(key), .lease_timeout = lease_timeout};
+}
+
+MemoryEvictAction EvictMemory(double target_ratio) {
+    return {.target_ratio = target_ratio, .lower_bound_ratio = target_ratio};
+}
+
+DfsEvictAction EvictDfs() { return {}; }
+
+TenantEvictAction EvictTenants() { return {}; }
+
+ObjectSpec<> Object(std::string key) { return ObjectSpec<>(std::move(key)); }
+
+ObjectsSpec<> Objects(size_t begin, size_t end) {
+    return ObjectsSpec<>(begin, end);
+}
+
+ObjectsSpec<> Objects(std::initializer_list<std::string> keys) {
+    return ObjectsSpec<>(std::vector<std::string>(keys));
+}
+
+ReadableObjectCountSpec ReadableCount(ObjectsSpec<> objects, size_t expected) {
+    return {.objects = std::move(objects), .expected = expected};
+}
+
+KeyExistsSpec KeyExists(std::string key) { return {.key = std::move(key)}; }
+
+BatchExistenceSpec BatchExistence(std::initializer_list<std::string> keys) {
+    BatchExistenceSpec existence;
+    existence.keys.assign(keys.begin(), keys.end());
+    return existence;
+}
+
+BatchReplicaListsSpec BatchReplicaLists(
+    std::initializer_list<std::string> keys) {
+    BatchReplicaListsSpec replica_lists;
+    replica_lists.keys.assign(keys.begin(), keys.end());
+    return replica_lists;
+}
+
+NamedTaskSpec NamedTask(std::string name) { return {.name = std::move(name)}; }
+
+UnknownTaskSpec UnknownTask(std::string name) {
+    return {.name = std::move(name)};
+}
+
+MatchingKeysSpec MatchingKeys(std::string pattern) {
+    MatchingKeysSpec keys;
+    keys.pattern = std::move(pattern);
+    return keys;
+}
+
+ClientIpsSpec ClientIps(std::initializer_list<std::string> actors) {
+    ClientIpsSpec ips;
+    ips.actors.assign(actors.begin(), actors.end());
+    return ips;
+}
+
+MemoryNodeStatusSpec MemoryNodeStatus(std::string node) {
+    return {.node = std::move(node)};
+}
+
+std::string GroupOnDifferentShard(std::string_view key) {
+    constexpr size_t kMetadataShardCount = 1024;
+    const size_t key_shard =
+        std::hash<std::string>{}(std::string(key)) % kMetadataShardCount;
+    for (size_t suffix = 0; suffix < 10000; ++suffix) {
+        std::string group =
+            std::string(key) + "_group_" + std::to_string(suffix);
+        if (std::hash<std::string>{}(group) % kMetadataShardCount !=
+            key_shard) {
+            return group;
+        }
+    }
+    return std::string(key) + "_fallback_group";
+}
+
+WaitAction WaitFor(std::chrono::milliseconds duration) { return {duration}; }
+
+WaitForOpLogFailureAction WaitForOpLogFailure() { return {}; }
+
+PingAction Ping(std::string actor) { return {.actor = std::move(actor)}; }
+
+MountLocalDiskAction MountLocalDisk(std::string actor) {
+    return {.actor = std::move(actor)};
+}
+
+UnmountLocalDiskAction UnmountLocalDisk(std::string actor) {
+    return {.actor = std::move(actor)};
+}
+
+ReportSsdCapacityAction ReportSsdCapacity(std::string actor,
+                                          int64_t capacity_bytes) {
+    return {.actor = std::move(actor), .capacity_bytes = capacity_bytes};
+}
+
+OffloadHeartbeatAction OffloadHeartbeat(std::string actor) {
+    return {.actor = std::move(actor)};
+}
+
+CompleteOffloadAction CompleteOffload(std::initializer_list<std::string> keys) {
+    CompleteOffloadAction action;
+    action.keys.assign(keys.begin(), keys.end());
+    return action;
+}
+
+EvictDiskReplicaAction EvictDiskReplica(std::string key) {
+    return {.key = std::move(key)};
+}
+
+RacePutStartAction RacePutStart(std::string key, uint64_t size) {
+    return {.key = std::move(key), .size = size};
+}
+
+RaceMountUnmountAction RaceMountUnmount(std::string prefix) {
+    return {.prefix = std::move(prefix)};
+}
+
+RaceMountLocalDiskAction RaceMountLocalDisk(std::string prefix) {
+    return {.prefix = std::move(prefix)};
+}
+
+RaceWritesWithRemoveAllAction RaceWritesWithRemoveAll(std::string prefix) {
+    return {.prefix = std::move(prefix)};
+}
+
+RaceReadsWithRemoveAllAction RaceReadsWithRemoveAll(
+    std::vector<std::string> keys) {
+    return {.keys = std::move(keys)};
+}
+
+RaceRemoveAllAction RaceRemoveAll() { return {}; }
+
+MasterScenario::MasterScenario(std::string name) : name_(std::move(name)) {}
+
+MasterScenario::MasterScenario(std::string name, MasterServiceConfig config,
+                               std::shared_ptr<HaKvBackend> batch_oplog_backend)
+    : name_(std::move(name)),
+      config_(std::move(config)),
+      batch_oplog_backend_(std::move(batch_oplog_backend)) {}
+
+MasterScenario::~MasterScenario() {
+    service_.reset();
+    if (!tenant_policy_path_.empty()) {
+        std::error_code error;
+        std::filesystem::remove(tenant_policy_path_, error);
+    }
+}
+
+MasterScenario& MasterScenario::Given(MemoryNodeSpec node) {
+    if (declarations_frozen_) {
+        Fail("MemoryNode declarations must precede actions and assertions");
+        return *this;
+    }
+    if (node.name.empty()) {
+        Fail("MemoryNode requires a name");
+        return *this;
+    }
+    if (node.capacity == 0) {
+        Fail("MemoryNode " + node.name + " requires non-zero capacity");
+        return *this;
+    }
+    const auto duplicate = std::find_if(
+        nodes_.begin(), nodes_.end(),
+        [&](const auto& existing) { return existing.name == node.name; });
+    if (duplicate != nodes_.end()) {
+        Fail("duplicate MemoryNode " + node.name);
+        return *this;
+    }
+    nodes_.push_back(std::move(node));
+    return *this;
+}
+
+MasterScenario& MasterScenario::Given(NoFNodeSpec node) {
+    if (declarations_frozen_) {
+        Fail("NoFNode declarations must precede actions and assertions");
+        return *this;
+    }
+    if (node.name.empty() || node.endpoint.empty() || node.capacity == 0) {
+        Fail("NoFNode requires name, endpoint, and non-zero capacity");
+        return *this;
+    }
+    const auto duplicate = std::find_if(
+        nof_nodes_.begin(), nof_nodes_.end(),
+        [&](const auto& existing) { return existing.name == node.name; });
+    if (duplicate != nof_nodes_.end()) {
+        Fail("duplicate NoFNode " + node.name);
+        return *this;
+    }
+    nof_nodes_.push_back(std::move(node));
+    return *this;
+}
+
+MasterScenario& MasterScenario::Given(TenantSpec tenant) {
+    if (declarations_frozen_) {
+        Fail("Tenant declarations must precede actions and assertions");
+        return *this;
+    }
+    if (tenant.name.empty() || !TenantId(tenant.name).IsValid()) {
+        Fail("Tenant requires a valid name");
+        return *this;
+    }
+    if (tenant.quota_bytes == 0) {
+        Fail("Tenant " + tenant.name + " requires non-zero quota");
+        return *this;
+    }
+    const auto duplicate = std::find_if(
+        tenants_.begin(), tenants_.end(),
+        [&](const auto& existing) { return existing.name == tenant.name; });
+    if (duplicate != tenants_.end()) {
+        Fail("duplicate Tenant " + tenant.name);
+        return *this;
+    }
+    tenants_.push_back(std::move(tenant));
+    return *this;
+}
+
+MasterScenario& MasterScenario::Given(ObjectsSpec<> objects) {
+    if (objects.keys.empty()) {
+        Fail(
+            "Objects requires at least one key; indexed ranges must use "
+            "NamedBy");
+        return *this;
+    }
+    if (objects.size == 0) {
+        Fail("Objects requires non-zero Size");
+        return *this;
+    }
+    if (objects.preferred_node.empty()) {
+        Fail("Objects requires CompleteOn");
+        return *this;
+    }
+
+    for (size_t offset = 0; offset < objects.keys.size(); ++offset) {
+        const auto& key = objects.keys[offset];
+        auto put = PutStart(key, objects.size)
+                       .By(objects.actor)
+                       .ForTenant(objects.tenant)
+                       .OnNode(objects.preferred_node);
+        if (!objects.group_id.empty()) {
+            put.InGroup(objects.group_id);
+        }
+        if (objects.with_soft_pin) {
+            put.WithSoftPin();
+        }
+        if (objects.with_hard_pin) {
+            put.WithHardPin();
+        }
+        When(std::move(put));
+        When(PutEnd(key).By(objects.actor).ForTenant(objects.tenant));
+
+        if (objects.lease_timeout_base.has_value()) {
+            auto expire = ExpireAt(key, *objects.lease_timeout_base +
+                                            objects.lease_timeout_step * offset)
+                              .ForTenant(objects.tenant);
+            if (objects.soft_pin_timeout.has_value()) {
+                expire.SoftPinnedUntil(*objects.soft_pin_timeout);
+            }
+            When(std::move(expire));
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::WhenPutStart(PutStartActionData action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    ReplicateConfig config;
+    config.replica_num = action.requested_replica_count;
+    config.nof_replica_num = action.requested_nof_replica_count;
+    config.dfs_replica_num = action.requested_dfs_replica_count;
+    config.preferred_segment = action.preferred_node;
+    config.preferred_segments = action.preferred_nodes;
+    config.host_id = action.host_id;
+    config.prefer_alloc_in_same_node = action.prefer_same_node;
+    config.soft_pin_action = action.soft_pin_action;
+    config.soft_pin_ttl_ms = action.soft_pin_ttl_ms;
+    config.with_hard_pin = action.with_hard_pin;
+    if (action.group_ids.has_value()) {
+        config.group_ids = std::move(action.group_ids);
+    }
+    const auto actor_id = ActorId(action.actor);
+    const TenantId tenant_id(action.tenant);
+    const auto deadline =
+        std::chrono::steady_clock::now() + action.eventual_timeout;
+    auto result = service_->PutStart(actor_id, action.key, tenant_id,
+                                     action.size, config);
+    while (!result && action.eventual_timeout.count() > 0 &&
+           (result.error() == ErrorCode::TENANT_QUOTA_EXCEEDED ||
+            result.error() == ErrorCode::NO_AVAILABLE_HANDLE) &&
+           std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        result = service_->PutStart(actor_id, action.key, tenant_id,
+                                    action.size, config);
+    }
+    ValidateStartResult("PutStart(" + action.key + ")", action.expected_error,
+                        action.expected_replica_count,
+                        action.expected_replica_status, result,
+                        action.expected_memory_nodes);
+    if (result) {
+        last_start_results_[action.tenant + "\n" + action.key] = *result;
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::WhenUpsertStart(UpsertStartActionData action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    ReplicateConfig config;
+    config.replica_num = action.requested_replica_count;
+    config.preferred_segment = action.preferred_node;
+    if (action.group_id.has_value()) {
+        config.group_ids = {*action.group_id};
+    }
+    const auto result =
+        service_->UpsertStart(ActorId(action.actor), action.key,
+                              TenantId(action.tenant), action.size, config);
+    ValidateStartResult("UpsertStart(" + action.key + ")",
+                        action.expected_error, action.expected_replica_count,
+                        action.expected_replica_status, result);
+    if (result && action.expected_buffer_reuse.has_value()) {
+        const auto previous =
+            last_start_results_.find(action.tenant + "\n" + action.key);
+        if (previous == last_start_results_.end()) {
+            Fail("UpsertStart(" + action.key +
+                 ") cannot check buffer reuse without a prior start result");
+        } else {
+            const auto memory_address =
+                [](const auto& replicas) -> std::optional<uintptr_t> {
+                const auto replica = std::find_if(
+                    replicas.begin(), replicas.end(),
+                    [](const auto& item) { return item.is_memory_replica(); });
+                if (replica == replicas.end()) {
+                    return std::nullopt;
+                }
+                return replica->get_memory_descriptor()
+                    .buffer_descriptor.buffer_address_;
+            };
+            const auto old_address = memory_address(previous->second);
+            const auto new_address = memory_address(*result);
+            if (!old_address.has_value() || !new_address.has_value()) {
+                Fail("UpsertStart(" + action.key +
+                     ") buffer reuse requires memory replicas");
+            } else if ((*old_address == *new_address) !=
+                       *action.expected_buffer_reuse) {
+                Fail("UpsertStart(" + action.key + ") " +
+                     (*action.expected_buffer_reuse
+                          ? "did not reuse the previous buffer"
+                          : "reused the previous buffer"));
+            }
+        }
+    }
+    if (result) {
+        last_start_results_[action.tenant + "\n" + action.key] = *result;
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(PutEndAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->PutEnd(
+        ActorId(action.actor), ObjectMeta{action.key, action.checksum},
+        TenantId(action.tenant), action.replica_type);
+    ValidateActionResult("PutEnd(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(UpsertEndAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->UpsertEnd(
+        ActorId(action.actor), ObjectMeta{action.key, action.checksum},
+        TenantId(action.tenant), action.replica_type);
+    ValidateActionResult("UpsertEnd(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(PutRevokeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->PutRevoke(ActorId(action.actor), action.key,
+                            TenantId(action.tenant), action.replica_type);
+    ValidateActionResult("PutRevoke(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(UpsertRevokeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->UpsertRevoke(ActorId(action.actor), action.key,
+                               TenantId(action.tenant), action.replica_type);
+    ValidateActionResult("UpsertRevoke(" + action.key + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(BatchUpsertStartAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    ReplicateConfig config;
+    config.replica_num = action.requested_replica_count;
+    config.preferred_segment = action.preferred_node;
+    config.group_ids = action.group_ids;
+    const auto results = service_->BatchUpsertStart(
+        ActorId(action.actor), action.keys, TenantId(action.tenant),
+        action.sizes, config);
+    if (results.size() != action.keys.size()) {
+        Fail("BatchUpsertStart returned " + std::to_string(results.size()) +
+             " results; expected " + std::to_string(action.keys.size()));
+        return *this;
+    }
+    for (size_t index = 0; index < results.size(); ++index) {
+        ValidateStartResult("BatchUpsertStart(" + action.keys[index] + ")",
+                            action.expected_error,
+                            action.expected_replica_count,
+                            action.expected_replica_status, results[index]);
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(BatchRemoveAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto results = service_->BatchRemove(
+        action.keys, TenantId(action.tenant), action.force);
+    if (results.size() != action.keys.size()) {
+        Fail("BatchRemove returned " + std::to_string(results.size()) +
+             " results; expected " + std::to_string(action.keys.size()));
+        return *this;
+    }
+    for (size_t index = 0; index < results.size(); ++index) {
+        ValidateActionResult(
+            "BatchRemove(" + action.keys[index] + ")", action.expected_error,
+            results[index].has_value(),
+            results[index] ? ErrorCode::OK : results[index].error());
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(BatchUpsertEndAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    std::vector<ObjectMeta> objects;
+    objects.reserve(action.keys.size());
+    for (const auto& key : action.keys) {
+        objects.push_back({.key = key, .object_checksum = std::nullopt});
+    }
+    const auto results = service_->BatchUpsertEnd(
+        ActorId(action.actor), objects, TenantId(action.tenant));
+    if (results.size() != action.keys.size()) {
+        Fail("BatchUpsertEnd returned " + std::to_string(results.size()) +
+             " results; expected " + std::to_string(action.keys.size()));
+        return *this;
+    }
+    for (size_t index = 0; index < results.size(); ++index) {
+        ValidateActionResult(
+            "BatchUpsertEnd(" + action.keys[index] + ")", std::nullopt,
+            results[index].has_value(),
+            results[index] ? ErrorCode::OK : results[index].error());
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RemoveAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->Remove(action.key, TenantId(action.tenant), action.force);
+    ValidateActionResult("Remove(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(ClearReplicasAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->BatchReplicaClear(
+        action.keys, ActorId(action.actor), action.node, action.tenant);
+    ValidateActionResult("ClearReplicas", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (!result || action.expected_error.has_value() ||
+        !action.expected_cleared.has_value()) {
+        return *this;
+    }
+    if (*result != *action.expected_cleared) {
+        Fail("ClearReplicas cleared an unexpected set of keys");
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CopyStartAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->CopyStart(ActorId(action.actor), action.key,
+                                            TenantId(action.tenant),
+                                            action.source, action.targets);
+    ValidateActionResult("CopyStart(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (!result || action.expected_error.has_value()) {
+        return *this;
+    }
+
+    const auto& source_endpoint = result->source.get_memory_descriptor()
+                                      .buffer_descriptor.transport_endpoint_;
+    if (source_endpoint != action.source) {
+        Fail("CopyStart(" + action.key + ") returned source " +
+             source_endpoint + "; expected " + action.source);
+    }
+    if (action.expected_allocated_targets.has_value()) {
+        std::vector<std::string> actual;
+        actual.reserve(result->targets.size());
+        for (const auto& target : result->targets) {
+            actual.push_back(target.get_memory_descriptor()
+                                 .buffer_descriptor.transport_endpoint_);
+        }
+        auto expected = *action.expected_allocated_targets;
+        std::sort(actual.begin(), actual.end());
+        std::sort(expected.begin(), expected.end());
+        if (actual != expected) {
+            Fail("CopyStart(" + action.key +
+                 ") allocated an unexpected set of targets");
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CopyEndAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->CopyEnd(ActorId(action.actor), action.key,
+                                          TenantId(action.tenant));
+    ValidateActionResult("CopyEnd(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CopyRevokeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->CopyRevoke(ActorId(action.actor), action.key,
+                                             TenantId(action.tenant));
+    ValidateActionResult("CopyRevoke(" + action.key + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MoveStartAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->MoveStart(ActorId(action.actor), action.key,
+                                            TenantId(action.tenant),
+                                            action.source, action.target);
+    ValidateActionResult("MoveStart(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (!result || action.expected_error.has_value()) {
+        return *this;
+    }
+
+    const auto& source_endpoint = result->source.get_memory_descriptor()
+                                      .buffer_descriptor.transport_endpoint_;
+    if (source_endpoint != action.source) {
+        Fail("MoveStart(" + action.key + ") returned source " +
+             source_endpoint + "; expected " + action.source);
+    }
+    if (result->target.has_value()) {
+        const auto& target_endpoint =
+            result->target->get_memory_descriptor()
+                .buffer_descriptor.transport_endpoint_;
+        if (target_endpoint != action.target) {
+            Fail("MoveStart(" + action.key + ") returned target " +
+                 target_endpoint + "; expected " + action.target);
+        }
+    }
+    if (action.expected_target_allocation.has_value() &&
+        result->target.has_value() != *action.expected_target_allocation) {
+        Fail("MoveStart(" + action.key +
+             ") target allocation did not match expectation");
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MoveEndAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->MoveEnd(ActorId(action.actor), action.key,
+                                          TenantId(action.tenant));
+    ValidateActionResult("MoveEnd(" + action.key + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MoveRevokeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->MoveRevoke(ActorId(action.actor), action.key,
+                                             TenantId(action.tenant));
+    ValidateActionResult("MoveRevoke(" + action.key + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CreateCopyTaskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->CreateCopyTask(
+        action.key, TenantId(action.tenant), action.targets);
+    ValidateActionResult("CreateCopyTask(" + action.name + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result && !action.expected_error.has_value()) {
+        const bool inserted = task_ids_.emplace(action.name, *result).second;
+        if (!inserted) {
+            Fail("duplicate task name " + action.name);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CreateMoveTaskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->CreateMoveTask(
+        action.key, TenantId(action.tenant), action.source, action.target);
+    ValidateActionResult("CreateMoveTask(" + action.name + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result && !action.expected_error.has_value()) {
+        const bool inserted = task_ids_.emplace(action.name, *result).second;
+        if (!inserted) {
+            Fail("duplicate task name " + action.name);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(FetchTasksAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->FetchTasks(ActorId(action.actor), action.batch_size);
+    ValidateActionResult("FetchTasks(" + action.actor + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result && !action.expected_error.has_value() &&
+        action.expected_count.has_value() &&
+        result->size() != *action.expected_count) {
+        Fail("FetchTasks(" + action.actor + ") returned " +
+             std::to_string(result->size()) + "; expected " +
+             std::to_string(*action.expected_count));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CompleteTaskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto task = task_ids_.find(action.name);
+    if (task == task_ids_.end()) {
+        Fail("CompleteTask references unknown task " + action.name);
+        return *this;
+    }
+
+    TaskCompleteRequest request;
+    request.id = task->second;
+    request.status = action.status;
+    request.message = std::move(action.message);
+    const auto result =
+        service_->MarkTaskToComplete(ActorId(action.actor), request);
+    ValidateActionResult("CompleteTask(" + action.name + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CompleteUnknownTaskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    TaskCompleteRequest request;
+    request.id = StableUuid("unknown-task", action.name);
+    request.status = action.status;
+    request.message = std::move(action.message);
+    const auto result =
+        service_->MarkTaskToComplete(ActorId(action.actor), request);
+    ValidateActionResult("CompleteUnknownTask(" + action.name + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RemoveByRegexAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->RemoveByRegex(
+        action.pattern, TenantId(action.tenant), action.force);
+    ValidateActionResult("RemoveByRegex(" + action.pattern + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result && action.expected_removed.has_value() &&
+        *result != static_cast<long>(*action.expected_removed)) {
+        Fail("RemoveByRegex(" + action.pattern + ") removed " +
+             std::to_string(*result) + "; expected " +
+             std::to_string(*action.expected_removed));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(UnmountMemoryNodeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto segment = segment_ids_.find(action.node);
+    if (segment == segment_ids_.end()) {
+        if (!action.unknown) {
+            Fail("UnmountMemoryNode references undeclared node " + action.node);
+            return *this;
+        }
+    }
+    const UUID segment_id = segment == segment_ids_.end()
+                                ? StableUuid("unknown-segment", action.node)
+                                : segment->second;
+    const auto actor = action.actor.empty() ? action.node : action.actor;
+    const auto started = std::chrono::steady_clock::now();
+    const auto result = service_->UnmountSegment(segment_id, ActorId(actor));
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - started);
+    ValidateActionResult("UnmountMemoryNode(" + action.node + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (action.maximum_duration.has_value() &&
+        elapsed > *action.maximum_duration) {
+        Fail("UnmountMemoryNode(" + action.node + ") took " +
+             std::to_string(elapsed.count()) + "ms; expected at most " +
+             std::to_string(action.maximum_duration->count()) + "ms");
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(GracefulUnmountMemoryNodeAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto segment = segment_ids_.find(action.node);
+    if (segment == segment_ids_.end()) {
+        Fail("GracefullyUnmountMemoryNode references undeclared node " +
+             action.node);
+        return *this;
+    }
+    const auto actor = action.actor.empty() ? action.node : action.actor;
+    const auto result = service_->GracefulUnmountSegment(
+        segment->second, ActorId(actor), action.grace_period_ms);
+    ValidateActionResult("GracefullyUnmountMemoryNode(" + action.node + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MountMemorySegmentAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    Segment segment;
+    const auto existing = segments_.find(action.alias);
+    segment.id = existing == segments_.end()
+                     ? StableUuid("dynamic-segment", action.alias)
+                     : existing->second.id;
+    segment.name = action.name;
+    segment.base = action.base;
+    segment.size = action.capacity;
+    segment.te_endpoint = action.endpoint;
+    const auto result = service_->MountSegment(segment, ActorId(action.actor));
+    ValidateActionResult("MountMemorySegment(" + action.alias + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result) {
+        segment_ids_[action.alias] = segment.id;
+        segments_[action.alias] = std::move(segment);
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(
+    MountUnmountMemoryCapacitiesAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.capacities.empty()) {
+        Fail("MountUnmountMemoryCapacities requires capacities");
+        return *this;
+    }
+    Segment segment;
+    segment.id = StableUuid("variable-segment", action.name);
+    segment.name = action.name;
+    segment.base = 0x500000000;
+    segment.te_endpoint = action.name;
+    const UUID actor = ActorId(action.name);
+    for (const uint64_t capacity : action.capacities) {
+        segment.size = capacity;
+        const auto mount = service_->MountSegment(segment, actor);
+        if (!mount) {
+            Fail("MountUnmountMemoryCapacities mount failed: " +
+                 toString(mount.error()));
+            continue;
+        }
+        const auto unmount = service_->UnmountSegment(segment.id, actor);
+        if (!unmount) {
+            Fail("MountUnmountMemoryCapacities unmount failed: " +
+                 toString(unmount.error()));
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RemoveAllAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const long removed =
+        action.tenant.has_value()
+            ? service_->RemoveAll(TenantId(*action.tenant), action.force)
+            : service_->RemoveAll(action.force);
+    if (action.expected_removed.has_value() &&
+        removed != static_cast<long>(*action.expected_removed)) {
+        Fail("RemoveAll removed " + std::to_string(removed) +
+             " objects; expected " + std::to_string(*action.expected_removed));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(ExpireAtAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const TenantId tenant(action.tenant);
+    auto update = [&](size_t shard_idx) {
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(service_.get(),
+                                                             shard_idx);
+        auto tenant_it = shard->tenants.find(tenant);
+        if (tenant_it == shard->tenants.end()) {
+            return false;
+        }
+        auto metadata_it = tenant_it->second.metadata.find(action.key);
+        if (metadata_it == tenant_it->second.metadata.end()) {
+            return false;
+        }
+        SpinLocker locker(&metadata_it->second.lock);
+        metadata_it->second.lease_->SetDeadline(action.lease_timeout);
+        metadata_it->second.soft_pin_timeout = action.soft_pin_timeout;
+        return true;
+    };
+
+    const size_t routed =
+        MasterServiceTestPeer(*service_).getShardIndex(tenant, action.key);
+    if (update(routed)) {
+        return *this;
+    }
+    for (size_t shard_idx = 0; shard_idx < MasterServiceTestPeer::kNumShards;
+         ++shard_idx) {
+        if (shard_idx != routed && update(shard_idx)) {
+            return *this;
+        }
+    }
+    Fail("ExpireAt(" + action.key + ") could not find object");
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MemoryEvictAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    MasterServiceTestPeer(*service_).RunBatchEvictForTesting(
+        action.target_ratio, action.lower_bound_ratio);
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(DfsEvictAction) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    MasterServiceTestPeer(*service_).RunDfsEvictionForTesting();
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(TenantEvictAction) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    MasterServiceTestPeer(*service_).RunTenantEvictForTesting();
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(WaitAction action) {
+    if (action.duration < std::chrono::milliseconds::zero()) {
+        Fail("WaitFor requires a non-negative duration");
+        return *this;
+    }
+    std::this_thread::sleep_for(action.duration);
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(WaitForOpLogFailureAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (!MasterServiceTestPeer::OrderedOplogWriter(*service_)) {
+        Fail("OpLog writer is not configured");
+        return *this;
+    }
+    const auto deadline = std::chrono::steady_clock::now() + action.timeout;
+    while (
+        MasterServiceTestPeer::OrderedOplogWriter(*service_)->IsAccepting() &&
+        std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    if (MasterServiceTestPeer::OrderedOplogWriter(*service_)->IsAccepting()) {
+        Fail("OpLog writer was expected to be unavailable");
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(PingAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->Ping(ActorId(action.actor));
+    ValidateActionResult("Ping(" + action.actor + ")", action.expected_error,
+                         result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(MountLocalDiskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->MountLocalDiskSegment(
+        ActorId(action.actor), action.enable_offloading);
+    ValidateActionResult("MountLocalDisk(" + action.actor + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(UnmountLocalDiskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result =
+        service_->UnmountLocalDiskSegment(ActorId(action.actor));
+    ValidateActionResult("UnmountLocalDisk(" + action.actor + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(ReportSsdCapacityAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->ReportSsdCapacity(ActorId(action.actor),
+                                                    action.capacity_bytes);
+    ValidateActionResult("ReportSsdCapacity(" + action.actor + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(OffloadHeartbeatAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->OffloadObjectHeartbeat(
+        ActorId(action.actor), action.enable_offloading);
+    ValidateActionResult("OffloadHeartbeat(" + action.actor + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (result && action.expect_some_tasks && result->empty()) {
+        Fail("OffloadHeartbeat(" + action.actor +
+             ") returned no offload tasks; expected at least one");
+    }
+    if (!result || !action.expected_task_keys.has_value()) {
+        return *this;
+    }
+    if (result->size() != action.expected_task_keys->size()) {
+        Fail("OffloadHeartbeat(" + action.actor + ") returned " +
+             std::to_string(result->size()) + " offload tasks; expected " +
+             std::to_string(action.expected_task_keys->size()));
+        return *this;
+    }
+    for (const auto& key : *action.expected_task_keys) {
+        const auto match = std::find_if(
+            result->begin(), result->end(), [&](const OffloadTaskItem& task) {
+                return task.tenant_id == action.tenant && task.key == key &&
+                       task.size == action.expected_task_size;
+            });
+        if (match == result->end()) {
+            Fail("OffloadHeartbeat(" + action.actor +
+                 ") is missing an offload task for " + key);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(CompleteOffloadAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.keys.empty()) {
+        Fail("CompleteOffload requires at least one key");
+        return *this;
+    }
+    if (action.node.empty()) {
+        Fail("CompleteOffload requires OnNode");
+        return *this;
+    }
+    const auto segment = segments_.find(action.node);
+    const std::string endpoint =
+        segment != segments_.end() ? segment->second.te_endpoint : action.node;
+    std::vector<OffloadTaskItem> tasks;
+    std::vector<StorageObjectMetadata> metadatas;
+    tasks.reserve(action.keys.size());
+    metadatas.reserve(action.keys.size());
+    for (const auto& key : action.keys) {
+        int64_t size = 0;
+        if (action.size.has_value()) {
+            size = *action.size;
+        } else {
+            const auto record =
+                last_start_results_.find(action.tenant + "\n" + key);
+            const Replica::Descriptor* descriptor = nullptr;
+            if (record != last_start_results_.end()) {
+                for (const auto& candidate : record->second) {
+                    if (candidate.is_memory_replica()) {
+                        descriptor = &candidate;
+                        break;
+                    }
+                }
+            }
+            if (descriptor == nullptr) {
+                Fail("CompleteOffload(" + key +
+                     ") has no PutStart-recorded size; use OfSize");
+                return *this;
+            }
+            size = static_cast<int64_t>(
+                descriptor->get_memory_descriptor().buffer_descriptor.size_);
+        }
+        tasks.push_back(OffloadTaskItem{
+            .tenant_id = action.tenant, .key = key, .size = size});
+        StorageObjectMetadata metadata{};
+        metadata.data_size = size;
+        metadata.transport_endpoint = endpoint;
+        metadatas.push_back(std::move(metadata));
+    }
+    const auto result =
+        service_->NotifyOffloadSuccess(ActorId(action.actor), tasks, metadatas);
+    ValidateActionResult("CompleteOffload(" + action.keys.front() + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(EvictDiskReplicaAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->EvictDiskReplica(
+        ActorId(action.actor), action.key, TenantId(action.tenant),
+        action.replica_type);
+    ValidateActionResult("EvictDiskReplica(" + action.key + ")",
+                         action.expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RacePutStartAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.thread_count == 0) {
+        Fail("RacePutStart requires at least one thread");
+        return *this;
+    }
+    const UUID actor_id = ActorId(action.actor);
+    const TenantId tenant_id(action.tenant);
+    std::atomic<size_t> ready{0};
+    std::atomic<bool> go{false};
+    std::atomic<size_t> admitted{0};
+    std::atomic<size_t> completed{0};
+    std::mutex failures_mutex;
+    std::vector<std::string> failures;
+    std::vector<std::thread> threads;
+    threads.reserve(action.thread_count);
+    for (size_t index = 0; index < action.thread_count; ++index) {
+        threads.emplace_back([&, index] {
+            ReplicateConfig config;
+            config.replica_num = 1;
+            if (!action.group_ids.empty()) {
+                // An empty entry means this thread races without a group.
+                const auto& group =
+                    action.group_ids[index % action.group_ids.size()];
+                if (!group.empty()) {
+                    config.group_ids = {group};
+                }
+            }
+            ready.fetch_add(1);
+            while (!go.load()) {
+                std::this_thread::yield();
+            }
+            const auto result = service_->PutStart(
+                actor_id, action.key, tenant_id, action.size, config);
+            if (result) {
+                admitted.fetch_add(1);
+                const auto end = service_->PutEnd(
+                    actor_id, action.key, tenant_id, ReplicaType::MEMORY);
+                if (end) {
+                    completed.fetch_add(1);
+                } else {
+                    std::lock_guard lock(failures_mutex);
+                    failures.push_back("PutEnd failed: " +
+                                       toString(end.error()));
+                }
+            } else if (result.error() != ErrorCode::OBJECT_ALREADY_EXISTS) {
+                std::lock_guard lock(failures_mutex);
+                failures.push_back("losing PutStart failed with " +
+                                   toString(result.error()) +
+                                   "; expected OBJECT_ALREADY_EXISTS");
+            }
+        });
+    }
+    while (ready.load() < action.thread_count) {
+        std::this_thread::yield();
+    }
+    go.store(true);
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    for (const auto& failure : failures) {
+        Fail("RacePutStart(" + action.key + ") " + failure);
+    }
+    if (admitted.load() != action.expected_successes) {
+        Fail("RacePutStart(" + action.key + ") admitted " +
+             std::to_string(admitted.load()) + " writers; expected " +
+             std::to_string(action.expected_successes));
+    }
+    if (completed.load() != action.expected_completions) {
+        Fail("RacePutStart(" + action.key + ") completed " +
+             std::to_string(completed.load()) + " writes; expected " +
+             std::to_string(action.expected_completions));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RaceMountUnmountAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.node_count == 0 || action.iterations == 0) {
+        Fail("RaceMountUnmount requires nodes and iterations");
+        return *this;
+    }
+    std::vector<Segment> segments;
+    std::vector<UUID> actors;
+    segments.reserve(action.node_count);
+    actors.reserve(action.node_count);
+    for (size_t index = 0; index < action.node_count; ++index) {
+        const std::string name = action.prefix + "-" + std::to_string(index);
+        Segment segment;
+        segment.id = StableUuid("race-segment", name);
+        segment.name = name;
+        segment.base = next_segment_base_;
+        segment.size = action.capacity;
+        segment.te_endpoint = name;
+        next_segment_base_ += action.capacity + 4096;
+        segments.push_back(std::move(segment));
+        actors.push_back(ActorId(name));
+    }
+    std::atomic<size_t> cycles{0};
+    std::mutex failures_mutex;
+    std::vector<std::string> failures;
+    std::vector<std::thread> threads;
+    threads.reserve(action.node_count);
+    for (size_t index = 0; index < action.node_count; ++index) {
+        threads.emplace_back([&, index] {
+            for (size_t iteration = 0; iteration < action.iterations;
+                 ++iteration) {
+                const auto mount =
+                    service_->MountSegment(segments[index], actors[index]);
+                if (!mount) {
+                    continue;
+                }
+                const auto unmount =
+                    service_->UnmountSegment(segments[index].id, actors[index]);
+                if (!unmount) {
+                    std::lock_guard lock(failures_mutex);
+                    failures.push_back("unmount of " + segments[index].name +
+                                       " failed after a successful mount: " +
+                                       toString(unmount.error()));
+                    return;
+                }
+                cycles.fetch_add(1);
+            }
+        });
+    }
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    for (const auto& failure : failures) {
+        Fail("RaceMountUnmount(" + action.prefix + ") " + failure);
+    }
+    if (cycles.load() < action.expected_min_cycles) {
+        Fail("RaceMountUnmount(" + action.prefix + ") completed " +
+             std::to_string(cycles.load()) +
+             " mount and unmount cycles; expected at least " +
+             std::to_string(action.expected_min_cycles));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RaceMountLocalDiskAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.client_count == 0) {
+        Fail("RaceMountLocalDisk requires at least one client");
+        return *this;
+    }
+    std::vector<UUID> actors;
+    actors.reserve(action.client_count);
+    for (size_t index = 0; index < action.client_count; ++index) {
+        actors.push_back(ActorId(action.prefix + "-" + std::to_string(index)));
+    }
+    std::mutex failures_mutex;
+    std::vector<std::string> failures;
+    std::vector<std::thread> threads;
+    threads.reserve(action.client_count);
+    for (size_t index = 0; index < action.client_count; ++index) {
+        threads.emplace_back([&, index] {
+            const auto result =
+                service_->MountLocalDiskSegment(actors[index], true);
+            if (!result) {
+                std::lock_guard lock(failures_mutex);
+                failures.push_back("mount failed: " + toString(result.error()));
+            }
+        });
+    }
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    for (const auto& failure : failures) {
+        Fail("RaceMountLocalDisk(" + action.prefix + ") " + failure);
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RaceWritesWithRemoveAllAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.writer_count == 0 || action.objects_per_writer == 0) {
+        Fail("RaceWritesWithRemoveAll requires writers and objects");
+        return *this;
+    }
+    const UUID actor_id = ActorId(action.actor);
+    const TenantId tenant_id(action.tenant);
+    std::atomic<size_t> written{0};
+    std::mutex failures_mutex;
+    std::vector<std::string> failures;
+    std::vector<std::thread> writers;
+    writers.reserve(action.writer_count);
+    for (size_t writer = 0; writer < action.writer_count; ++writer) {
+        writers.emplace_back([&, writer] {
+            for (size_t index = 0; index < action.objects_per_writer; ++index) {
+                const std::string key = action.prefix + "-" +
+                                        std::to_string(writer) + "-" +
+                                        std::to_string(index);
+                ReplicateConfig config;
+                config.replica_num = 1;
+                const auto start = service_->PutStart(
+                    actor_id, key, tenant_id, action.object_size, config);
+                if (!start) {
+                    std::lock_guard lock(failures_mutex);
+                    failures.push_back("PutStart(" + key +
+                                       ") failed: " + toString(start.error()));
+                    continue;
+                }
+                const auto end = service_->PutEnd(actor_id, key, tenant_id,
+                                                  ReplicaType::MEMORY);
+                if (!end) {
+                    std::lock_guard lock(failures_mutex);
+                    failures.push_back("PutEnd(" + key +
+                                       ") failed: " + toString(end.error()));
+                    continue;
+                }
+                written.fetch_add(1);
+            }
+        });
+    }
+    long removed_during = 0;
+    std::thread remover([&] {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(10);
+        while (written.load() == 0 &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::yield();
+        }
+        removed_during = service_->RemoveAll();
+    });
+    for (auto& writer : writers) {
+        writer.join();
+    }
+    remover.join();
+    const long removed_after = service_->RemoveAll();
+    for (const auto& failure : failures) {
+        Fail("RaceWritesWithRemoveAll(" + action.prefix + ") " + failure);
+    }
+    if (removed_during < 1) {
+        Fail("RaceWritesWithRemoveAll(" + action.prefix +
+             ") removed nothing while writes were in flight");
+    }
+    const long expected_total = static_cast<long>(action.writer_count) *
+                                static_cast<long>(action.objects_per_writer);
+    if (removed_during + removed_after != expected_total) {
+        Fail("RaceWritesWithRemoveAll(" + action.prefix + ") removed " +
+             std::to_string(removed_during + removed_after) +
+             " objects across both sweeps; expected " +
+             std::to_string(expected_total));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RaceReadsWithRemoveAllAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.keys.empty()) {
+        Fail("RaceReadsWithRemoveAll requires at least one key");
+        return *this;
+    }
+    if (action.reader_count == 0) {
+        Fail("RaceReadsWithRemoveAll requires at least one reader");
+        return *this;
+    }
+    const TenantId tenant_id(action.tenant);
+    std::atomic<size_t> reads{0};
+    std::vector<std::thread> readers;
+    readers.reserve(action.reader_count);
+    for (size_t reader = 0; reader < action.reader_count; ++reader) {
+        readers.emplace_back([&] {
+            for (const auto& key : action.keys) {
+                if (service_->GetReplicaList(key, tenant_id)) {
+                    reads.fetch_add(1);
+                }
+            }
+        });
+    }
+    long removed_during = 0;
+    std::thread remover([&] {
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(10);
+        while (reads.load() == 0 &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::yield();
+        }
+        removed_during = service_->RemoveAll();
+    });
+    for (auto& reader : readers) {
+        reader.join();
+    }
+    remover.join();
+    if (reads.load() == 0) {
+        Fail("RaceReadsWithRemoveAll read nothing while removal was racing");
+        return *this;
+    }
+    long removed_after = 0;
+    if (action.final_remove_after > std::chrono::milliseconds::zero()) {
+        std::this_thread::sleep_for(action.final_remove_after);
+        removed_after = service_->RemoveAll();
+    }
+    if (action.expected_total_removed.has_value() &&
+        removed_during + removed_after !=
+            static_cast<long>(*action.expected_total_removed)) {
+        Fail("RaceReadsWithRemoveAll removed " +
+             std::to_string(removed_during + removed_after) +
+             " objects across both sweeps; expected " +
+             std::to_string(*action.expected_total_removed));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::When(RaceRemoveAllAction action) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    if (action.caller_count == 0) {
+        Fail("RaceRemoveAll requires at least one caller");
+        return *this;
+    }
+    std::atomic<long> removed{0};
+    std::vector<std::thread> callers;
+    callers.reserve(action.caller_count);
+    for (size_t caller = 0; caller < action.caller_count; ++caller) {
+        callers.emplace_back([&] { removed.fetch_add(service_->RemoveAll()); });
+    }
+    for (auto& caller : callers) {
+        caller.join();
+    }
+    if (action.expected_total_removed.has_value() &&
+        removed.load() != static_cast<long>(*action.expected_total_removed)) {
+        Fail("RaceRemoveAll removed " + std::to_string(removed.load()) +
+             " objects; expected " +
+             std::to_string(*action.expected_total_removed));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::ThenObject(ObjectSpecData object,
+                                           ObjectExpectation expectation) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->GetReplicaList(object.key, TenantId(object.tenant));
+    if (expectation == ObjectExpectation::MISSING) {
+        if (result) {
+            Fail("Object(" + object.key + ") exists; expected it not to exist");
+        } else if (result.error() != ErrorCode::OBJECT_NOT_FOUND) {
+            Fail("Object(" + object.key + ") lookup failed with " +
+                 toString(result.error()) + "; expected OBJECT_NOT_FOUND");
+        }
+        return *this;
+    }
+    if (expectation == ObjectExpectation::NOT_READY) {
+        if (result || result.error() != ErrorCode::REPLICA_IS_NOT_READY) {
+            Fail("Object(" + object.key + ") was expected to be not ready");
+        }
+        return *this;
+    }
+    if (!result) {
+        Fail("Object(" + object.key +
+             ") is not readable: " + toString(result.error()));
+        return *this;
+    }
+    if (result->replicas.empty()) {
+        Fail("Object(" + object.key + ") has no readable replicas");
+    }
+    if (object.expected_replica_count.has_value() &&
+        result->replicas.size() != *object.expected_replica_count) {
+        Fail("Object(" + object.key + ") has " +
+             std::to_string(result->replicas.size()) + " replicas; expected " +
+             std::to_string(*object.expected_replica_count));
+    }
+    if (object.expected_complete_replica_count.has_value()) {
+        const size_t complete =
+            std::count_if(result->replicas.begin(), result->replicas.end(),
+                          [](const auto& replica) {
+                              return replica.status == ReplicaStatus::COMPLETE;
+                          });
+        if (complete != *object.expected_complete_replica_count) {
+            Fail("Object(" + object.key + ") has " + std::to_string(complete) +
+                 " complete replicas; expected " +
+                 std::to_string(*object.expected_complete_replica_count));
+        }
+    }
+    if (object.expected_checksum.has_value() &&
+        result->object_checksum != *object.expected_checksum) {
+        const auto format_checksum = [](const std::optional<uint64_t>& value) {
+            return value.has_value() ? std::to_string(*value) : "none";
+        };
+        Fail("Object(" + object.key + ") has checksum " +
+             format_checksum(result->object_checksum) + "; expected " +
+             format_checksum(*object.expected_checksum));
+    }
+    std::vector<std::string> memory_nodes;
+    size_t memory_replicas = 0;
+    size_t nof_replicas = 0;
+    size_t dfs_replicas = 0;
+    size_t local_disk_replicas = 0;
+    size_t disk_replicas = 0;
+    size_t complete_memory_replicas = 0;
+    size_t complete_nof_replicas = 0;
+    size_t complete_dfs_replicas = 0;
+    size_t complete_local_disk_replicas = 0;
+    size_t complete_disk_replicas = 0;
+    for (const auto& replica : result->replicas) {
+        if (replica.is_nof_replica()) {
+            ++nof_replicas;
+            if (replica.status == ReplicaStatus::COMPLETE) {
+                ++complete_nof_replicas;
+            }
+        }
+        if (replica.is_dfs_replica()) {
+            ++dfs_replicas;
+            if (replica.status == ReplicaStatus::COMPLETE) {
+                ++complete_dfs_replicas;
+            }
+        }
+        if (replica.is_local_disk_replica()) {
+            ++local_disk_replicas;
+            if (replica.status == ReplicaStatus::COMPLETE) {
+                ++complete_local_disk_replicas;
+            }
+        }
+        if (replica.is_disk_replica()) {
+            ++disk_replicas;
+            if (replica.status == ReplicaStatus::COMPLETE) {
+                ++complete_disk_replicas;
+            }
+        }
+        if (!replica.is_memory_replica()) {
+            continue;
+        }
+        ++memory_replicas;
+        if (replica.status == ReplicaStatus::COMPLETE) {
+            ++complete_memory_replicas;
+        }
+        const auto& descriptor =
+            replica.get_memory_descriptor().buffer_descriptor;
+        memory_nodes.push_back(descriptor.transport_endpoint_);
+        if (object.expected_memory_replica_size.has_value() &&
+            descriptor.size_ != *object.expected_memory_replica_size) {
+            Fail("Object(" + object.key + ") has memory replica size " +
+                 std::to_string(descriptor.size_) + "; expected " +
+                 std::to_string(*object.expected_memory_replica_size));
+        }
+        if (object.expected_memory_node.has_value() &&
+            descriptor.transport_endpoint_ != *object.expected_memory_node) {
+            Fail("Object(" + object.key + ") has a memory replica on " +
+                 descriptor.transport_endpoint_ + "; expected " +
+                 *object.expected_memory_node);
+        }
+    }
+    const bool expects_memory_replica =
+        object.expected_memory_replica_size.has_value() ||
+        object.expected_memory_node.has_value() ||
+        object.expected_memory_nodes.has_value() ||
+        object.expect_distinct_memory_nodes;
+    if (expects_memory_replica && memory_nodes.empty()) {
+        Fail("Object(" + object.key +
+             ") has no memory replicas; expected at least one");
+    }
+    if (object.expect_distinct_memory_nodes) {
+        std::sort(memory_nodes.begin(), memory_nodes.end());
+        const auto duplicate =
+            std::adjacent_find(memory_nodes.begin(), memory_nodes.end());
+        if (duplicate != memory_nodes.end()) {
+            Fail("Object(" + object.key +
+                 ") has duplicate memory replicas on " + *duplicate);
+        }
+    }
+    if (object.expected_memory_nodes.has_value()) {
+        std::sort(memory_nodes.begin(), memory_nodes.end());
+        auto expected = *object.expected_memory_nodes;
+        std::sort(expected.begin(), expected.end());
+        if (memory_nodes != expected) {
+            Fail("Object(" + object.key +
+                 ") is on an unexpected set of memory nodes");
+        }
+    }
+    const auto validate_count = [&](std::string_view kind, size_t actual,
+                                    const std::optional<size_t>& expected) {
+        if (expected.has_value() && actual != *expected) {
+            Fail("Object(" + object.key + ") has " + std::to_string(actual) +
+                 " " + std::string(kind) + "; expected " +
+                 std::to_string(*expected));
+        }
+    };
+    validate_count("memory replicas", memory_replicas,
+                   object.expected_memory_replica_count);
+    validate_count("NoF replicas", nof_replicas,
+                   object.expected_nof_replica_count);
+    validate_count("DFS replicas", dfs_replicas,
+                   object.expected_dfs_replica_count);
+    validate_count("local-disk replicas", local_disk_replicas,
+                   object.expected_local_disk_replica_count);
+    validate_count("disk replicas", disk_replicas,
+                   object.expected_disk_replica_count);
+    validate_count("complete memory replicas", complete_memory_replicas,
+                   object.expected_complete_memory_replica_count);
+    validate_count("complete NoF replicas", complete_nof_replicas,
+                   object.expected_complete_nof_replica_count);
+    validate_count("complete DFS replicas", complete_dfs_replicas,
+                   object.expected_complete_dfs_replica_count);
+    validate_count("complete local-disk replicas", complete_local_disk_replicas,
+                   object.expected_complete_local_disk_replica_count);
+    validate_count("complete disk replicas", complete_disk_replicas,
+                   object.expected_complete_disk_replica_count);
+    return *this;
+}
+
+MasterScenario& MasterScenario::ThenObjects(ObjectsSpecData objects,
+                                            ObjectExpectation expectation) {
+    if (objects.keys.empty()) {
+        Fail(
+            "Objects requires at least one key; indexed ranges must use "
+            "NamedBy");
+        return *this;
+    }
+    for (auto& key : objects.keys) {
+        ObjectSpecData object(std::move(key));
+        object.tenant = objects.tenant;
+        ThenObject(std::move(object), expectation);
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(ReadableObjectCountSpec objects) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    size_t readable = 0;
+    for (const auto& key : objects.objects.keys) {
+        const auto result =
+            service_->GetReplicaList(key, TenantId(objects.objects.tenant));
+        if (result) {
+            ++readable;
+        } else if (result.error() != ErrorCode::OBJECT_NOT_FOUND) {
+            Fail("ReadableCount lookup for " + key +
+                 " failed: " + toString(result.error()));
+        }
+    }
+    if (readable != objects.expected) {
+        Fail("ReadableCount is " + std::to_string(readable) + "; expected " +
+             std::to_string(objects.expected));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(KeyExistsSpec key_exists) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->ExistKey(key_exists.key, TenantId(key_exists.tenant));
+    if (!result) {
+        Fail("KeyExists(" + key_exists.key +
+             ") failed: " + toString(result.error()));
+    } else if (!*result) {
+        Fail("KeyExists(" + key_exists.key + ") returned false");
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(BatchExistenceSpec batch_existence) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result = service_->BatchExistKey(
+        batch_existence.keys, TenantId(batch_existence.tenant));
+    if (result.size() != batch_existence.expected.size()) {
+        Fail("BatchExistence returned " + std::to_string(result.size()) +
+             " results; expected " +
+             std::to_string(batch_existence.expected.size()));
+        return *this;
+    }
+    for (size_t index = 0; index < result.size(); ++index) {
+        if (!result[index]) {
+            Fail("BatchExistence failed for key " +
+                 batch_existence.keys[index] + ": " +
+                 toString(result[index].error()));
+        } else if (*result[index] != batch_existence.expected[index]) {
+            Fail("BatchExistence returned an unexpected result for key " +
+                 batch_existence.keys[index]);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(
+    BatchReplicaListsSpec batch_replica_lists) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto results = service_->BatchGetReplicaList(
+        batch_replica_lists.keys, TenantId(batch_replica_lists.tenant));
+    if (results.size() != batch_replica_lists.expected.size()) {
+        Fail("BatchReplicaLists returned " + std::to_string(results.size()) +
+             " results; expected " +
+             std::to_string(batch_replica_lists.expected.size()));
+        return *this;
+    }
+    for (size_t index = 0; index < results.size(); ++index) {
+        const ErrorCode expected = batch_replica_lists.expected[index];
+        if (expected == ErrorCode::OK) {
+            if (!results[index]) {
+                Fail("BatchReplicaLists(" + batch_replica_lists.keys[index] +
+                     ") failed: " + toString(results[index].error()));
+            } else if (results[index]->replicas.empty()) {
+                Fail("BatchReplicaLists(" + batch_replica_lists.keys[index] +
+                     ") returned no replicas");
+            }
+        } else if (results[index]) {
+            Fail("BatchReplicaLists(" + batch_replica_lists.keys[index] +
+                 ") succeeded; expected " + toString(expected));
+        } else if (results[index].error() != expected) {
+            Fail("BatchReplicaLists(" + batch_replica_lists.keys[index] +
+                 ") failed with " + toString(results[index].error()) +
+                 "; expected " + toString(expected));
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(NamedTaskSpec task) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto task_id = task_ids_.find(task.name);
+    if (task_id == task_ids_.end()) {
+        Fail("NamedTask references unknown task " + task.name);
+        return *this;
+    }
+
+    const auto result = service_->QueryTask(task_id->second);
+    if (!result) {
+        Fail("NamedTask(" + task.name +
+             ") failed: " + toString(result.error()));
+        return *this;
+    }
+    if (task.expected_type.has_value() && result->type != *task.expected_type) {
+        Fail("NamedTask(" + task.name + ") has an unexpected type");
+    }
+    if (task.expected_status.has_value() &&
+        result->status != *task.expected_status) {
+        Fail("NamedTask(" + task.name + ") has an unexpected status");
+    }
+    if (task.expected_actor.has_value() &&
+        result->assigned_client != ActorId(*task.expected_actor)) {
+        Fail("NamedTask(" + task.name + ") has an unexpected assignee");
+    }
+    if (task.expected_message.has_value() &&
+        result->message != *task.expected_message) {
+        Fail("NamedTask(" + task.name + ") has message " + result->message +
+             "; expected " + *task.expected_message);
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(UnknownTaskSpec task) {
+    if (!EnsureService()) {
+        return *this;
+    }
+
+    const auto result =
+        service_->QueryTask(StableUuid("unknown-task", task.name));
+    if (result) {
+        Fail("UnknownTask(" + task.name + ") unexpectedly exists");
+    } else if (result.error() != task.expected_error) {
+        Fail("UnknownTask(" + task.name + ") failed with " +
+             toString(result.error()) + "; expected " +
+             toString(task.expected_error));
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(MatchingKeysSpec matching_keys) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto result = service_->GetReplicaListByRegex(
+        matching_keys.pattern, TenantId(matching_keys.tenant));
+    if (!result) {
+        Fail("MatchingKeys(" + matching_keys.pattern +
+             ") failed: " + toString(result.error()));
+        return *this;
+    }
+    if (matching_keys.expected_count.has_value() &&
+        result->size() != *matching_keys.expected_count) {
+        Fail("MatchingKeys(" + matching_keys.pattern + ") returned " +
+             std::to_string(result->size()) + "; expected " +
+             std::to_string(*matching_keys.expected_count));
+    }
+    for (const auto& key : matching_keys.expected_keys) {
+        if (!result->contains(key)) {
+            Fail("MatchingKeys(" + matching_keys.pattern + ") is missing " +
+                 key);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(ClientIpsSpec client_ips) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    std::vector<UUID> clients;
+    clients.reserve(client_ips.actors.size());
+    for (const auto& actor : client_ips.actors) {
+        clients.push_back(ActorId(actor));
+    }
+    const auto result = service_->BatchQueryIp(clients);
+    if (!result) {
+        Fail("ClientIps query failed: " + toString(result.error()));
+        return *this;
+    }
+    if (client_ips.actors.empty() && !result->empty()) {
+        Fail("ClientIps for an empty actor list returned entries");
+    }
+    for (const auto& [actor, expected_values] : client_ips.expected) {
+        const auto found = result->find(ActorId(actor));
+        if (found == result->end()) {
+            Fail("ClientIps omitted expected actor " + actor);
+            continue;
+        }
+        auto actual = found->second;
+        auto expected = expected_values;
+        std::sort(actual.begin(), actual.end());
+        std::sort(expected.begin(), expected.end());
+        if (actual != expected) {
+            Fail("ClientIps for " + actor + " differ from expectation");
+        }
+    }
+    for (const auto& actor : client_ips.omitted) {
+        if (result->contains(ActorId(actor))) {
+            Fail("ClientIps unexpectedly returned actor " + actor);
+        }
+    }
+    return *this;
+}
+
+MasterScenario& MasterScenario::Then(MemoryNodeStatusSpec node_status) {
+    if (!EnsureService()) {
+        return *this;
+    }
+    const auto deadline =
+        std::chrono::steady_clock::now() + node_status.eventual_timeout;
+    auto matches = [&]() {
+        tl::expected<SegmentStatus, ErrorCode> result =
+            tl::make_unexpected(ErrorCode::SEGMENT_NOT_FOUND);
+        if (node_status.query_by_id) {
+            const auto segment = segment_ids_.find(node_status.node);
+            if (segment == segment_ids_.end()) {
+                Fail("MemoryNodeStatus references undeclared node " +
+                     node_status.node);
+                return false;
+            }
+            result = service_->QuerySegmentStatusById(segment->second);
+        } else {
+            result = service_->QuerySegmentStatus(node_status.node);
+        }
+        if (node_status.expected_missing) {
+            return !result.has_value() || *result == SegmentStatus::UNDEFINED;
+        }
+        return result.has_value() && node_status.expected_status.has_value() &&
+               *result == *node_status.expected_status;
+    };
+    while (!matches() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    if (!matches()) {
+        Fail("MemoryNodeStatus(" + node_status.node + ") mismatch");
+    }
+    return *this;
+}
+
+bool MasterScenario::EnsureService() {
+    if (service_) {
+        return true;
+    }
+    declarations_frozen_ = true;
+    if (nodes_.empty() && nof_nodes_.empty()) {
+        Fail("scenario requires at least one storage node");
+        return false;
+    }
+
+    if (!tenants_.empty()) {
+        TenantQuotaPolicySnapshot snapshot;
+        for (const auto& tenant : tenants_) {
+            snapshot.tenant_quotas.emplace(tenant.name, tenant.quota_bytes);
+        }
+        tenant_policy_path_ =
+            (std::filesystem::temp_directory_path() /
+             ("mooncake_master_scenario_tenants_" + std::to_string(::getpid()) +
+              "_" + std::to_string(reinterpret_cast<uintptr_t>(this)) +
+              ".yaml"))
+                .string();
+        std::ofstream output(tenant_policy_path_);
+        output << FormatTenantQuotaPolicyYaml(snapshot);
+        output.close();
+        config_.enable_multi_tenants = true;
+        config_.tenant_quota_connector_type = "file";
+        config_.tenant_quota_connector_uri = tenant_policy_path_;
+    }
+
+    service_ = std::make_unique<MasterService>(config_);
+    if (batch_oplog_backend_) {
+        const auto result =
+            MasterServiceTestPeer(*service_).SetBatchOpLogBackendForTesting(
+                batch_oplog_backend_);
+        if (result != ErrorCode::OK) {
+            Fail("failed to install batch OpLog backend: " + toString(result));
+            service_.reset();
+            return false;
+        }
+    }
+    for (const auto& node : nodes_) {
+        Segment segment;
+        segment.id = StableUuid("segment", node.name);
+        segment.name = node.name;
+        segment.base = next_segment_base_;
+        segment.size = node.capacity;
+        segment.te_endpoint = node.endpoint.value_or(node.name);
+        segment.host_id = node.host_id;
+        next_segment_base_ += node.capacity + 4096;
+
+        const auto owner = node.owner.empty() ? node.name : node.owner;
+        const auto result = service_->MountSegment(segment, ActorId(owner));
+        if (!result) {
+            Fail("failed to mount MemoryNode " + node.name + ": " +
+                 toString(result.error()));
+            service_.reset();
+            return false;
+        }
+        segment_ids_.emplace(node.name, segment.id);
+        segments_.emplace(node.name, std::move(segment));
+    }
+    for (const auto& node : nof_nodes_) {
+        NoFSegment segment;
+        segment.id = StableUuid("nof-segment", node.name);
+        segment.name = node.name;
+        segment.base = next_segment_base_;
+        segment.size = node.capacity;
+        segment.te_endpoint = node.endpoint;
+        next_segment_base_ += node.capacity + 4096;
+
+        const auto owner = node.owner.empty() ? node.name : node.owner;
+        const auto result = service_->MountNoFSegment(segment, ActorId(owner));
+        if (!result) {
+            Fail("failed to mount NoFNode " + node.name + ": " +
+                 toString(result.error()));
+            service_.reset();
+            return false;
+        }
+        nof_segments_.emplace(node.name, std::move(segment));
+    }
+    return true;
+}
+
+UUID MasterScenario::ActorId(std::string_view actor) {
+    const std::string name(actor);
+    const auto result = actor_ids_.emplace(name, StableUuid("actor", name));
+    return result.first->second;
+}
+
+void MasterScenario::ValidateActionResult(
+    std::string_view action, const std::optional<ErrorCode>& expected_error,
+    bool succeeded, ErrorCode error) {
+    if (!expected_error.has_value()) {
+        if (!succeeded) {
+            Fail(std::string(action) + " failed: " + toString(error));
+        }
+        return;
+    }
+    if (succeeded) {
+        Fail(std::string(action) + " succeeded; expected " +
+             toString(*expected_error));
+    } else if (error != *expected_error) {
+        Fail(std::string(action) + " failed with " + toString(error) +
+             "; expected " + toString(*expected_error));
+    }
+}
+
+void MasterScenario::ValidateStartResult(
+    std::string_view action, const std::optional<ErrorCode>& expected_error,
+    const std::optional<size_t>& expected_replica_count,
+    const std::optional<ReplicaStatus>& expected_replica_status,
+    const StartResult& result,
+    const std::optional<std::vector<std::string>>& expected_memory_nodes) {
+    ValidateActionResult(action, expected_error, result.has_value(),
+                         result ? ErrorCode::OK : result.error());
+    if (!result) {
+        return;
+    }
+    if (expected_replica_count.has_value() &&
+        result->size() != *expected_replica_count) {
+        Fail(std::string(action) + " returned " +
+             std::to_string(result->size()) + " replicas; expected " +
+             std::to_string(*expected_replica_count));
+    }
+    if (expected_replica_status.has_value() &&
+        std::any_of(result->begin(), result->end(), [&](const auto& replica) {
+            return replica.status != *expected_replica_status;
+        })) {
+        Fail(std::string(action) + " replica status mismatch");
+    }
+    if (expected_memory_nodes.has_value()) {
+        std::vector<std::string> actual;
+        for (const auto& replica : *result) {
+            if (replica.is_memory_replica()) {
+                actual.push_back(replica.get_memory_descriptor()
+                                     .buffer_descriptor.transport_endpoint_);
+            }
+        }
+        auto expected = *expected_memory_nodes;
+        std::sort(actual.begin(), actual.end());
+        std::sort(expected.begin(), expected.end());
+        if (actual != expected) {
+            Fail(std::string(action) + " memory-node allocation mismatch");
+        }
+    }
+}
+
+void MasterScenario::Fail(std::string message) const {
+    ADD_FAILURE() << "MasterScenario[" << name_ << "]: " << message;
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service/dsl/scenario.h b/mooncake-store/tests/master_service/dsl/scenario.h
new file mode 100644
index 0000000000..dccf0749eb
--- /dev/null
+++ b/mooncake-store/tests/master_service/dsl/scenario.h
@@ -0,0 +1,2259 @@
+#pragma once
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <initializer_list>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "master_service.h"
+
+namespace mooncake::test {
+
+class MasterScenario;
+
+constexpr uint64_t operator""_KB(unsigned long long value) {
+    return value * 1024;
+}
+
+struct MemoryNodeSpec {
+    std::string name;
+    uint64_t capacity{16 * 1024 * 1024};
+    std::optional<std::string> endpoint{};
+    std::string host_id;
+    std::string owner;
+
+    MemoryNodeSpec& Capacity(uint64_t value) {
+        capacity = value;
+        return *this;
+    }
+
+    MemoryNodeSpec& Endpoint(std::string value) {
+        endpoint = std::move(value);
+        return *this;
+    }
+
+    MemoryNodeSpec& OnHost(std::string value) {
+        host_id = std::move(value);
+        return *this;
+    }
+
+    MemoryNodeSpec& OwnedBy(std::string value) {
+        owner = std::move(value);
+        return *this;
+    }
+};
+
+MemoryNodeSpec MemoryNode(std::string name);
+
+struct NoFNodeSpec {
+    std::string name;
+    std::string endpoint;
+    uint64_t capacity{16 * 1024 * 1024};
+    std::string owner;
+
+    NoFNodeSpec& Endpoint(std::string value) {
+        endpoint = std::move(value);
+        return *this;
+    }
+
+    NoFNodeSpec& Capacity(uint64_t value) {
+        capacity = value;
+        return *this;
+    }
+
+    NoFNodeSpec& OwnedBy(std::string value) {
+        owner = std::move(value);
+        return *this;
+    }
+};
+
+NoFNodeSpec NoFNode(std::string name);
+
+struct TenantSpec {
+    std::string name;
+    uint64_t quota_bytes{64 * 1024 * 1024};
+
+    TenantSpec& Quota(uint64_t value) {
+        quota_bytes = value;
+        return *this;
+    }
+};
+
+TenantSpec Tenant(std::string name);
+
+enum class PutStartExpectation {
+    UNSPECIFIED,
+    SUCCESS,
+    ERROR,
+};
+
+template <PutStartExpectation expectation = PutStartExpectation::UNSPECIFIED>
+struct PutStartAction;
+
+struct PutStartActionData {
+    PutStartActionData(const PutStartActionData&) = default;
+
+   private:
+    PutStartActionData(std::string value, uint64_t object_size)
+        : key(std::move(value)), size(object_size) {}
+
+    std::string key;
+    uint64_t size;
+    std::string actor{"default"};
+    size_t requested_replica_count{1};
+    size_t requested_nof_replica_count{0};
+    size_t requested_dfs_replica_count{0};
+    std::string tenant{TenantId::Default().value()};
+    std::string preferred_node;
+    std::vector<std::string> preferred_nodes;
+    std::string host_id;
+    std::optional<std::vector<std::string>> group_ids{};
+    bool prefer_same_node{false};
+    SoftPinAction soft_pin_action{SoftPinAction::PRESERVE};
+    std::optional<uint64_t> soft_pin_ttl_ms{};
+    bool with_hard_pin{false};
+    std::optional<ErrorCode> expected_error{};
+    std::optional<size_t> expected_replica_count{};
+    std::optional<ReplicaStatus> expected_replica_status{};
+    std::optional<std::vector<std::string>> expected_memory_nodes{};
+    std::chrono::milliseconds eventual_timeout{};
+
+    template <PutStartExpectation>
+    friend struct PutStartAction;
+    friend class MasterScenario;
+};
+
+template <PutStartExpectation expectation>
+struct PutStartAction : PutStartActionData {
+    PutStartAction(std::string key, uint64_t size)
+        requires(expectation == PutStartExpectation::UNSPECIFIED)
+        : PutStartActionData(std::move(key), size) {}
+
+    PutStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    PutStartAction& Replicas(size_t value) {
+        requested_replica_count = value;
+        return *this;
+    }
+
+    PutStartAction& NofReplicas(size_t value) {
+        requested_nof_replica_count = value;
+        return *this;
+    }
+
+    PutStartAction& DfsReplicas(size_t value) {
+        requested_dfs_replica_count = value;
+        return *this;
+    }
+
+    PutStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    PutStartAction& OnNode(std::string value) {
+        preferred_node = std::move(value);
+        return *this;
+    }
+
+    PutStartAction& OnNodes(std::initializer_list<std::string> values) {
+        preferred_nodes.assign(values.begin(), values.end());
+        return *this;
+    }
+
+    PutStartAction& FromHost(std::string value) {
+        host_id = std::move(value);
+        return *this;
+    }
+
+    PutStartAction& PreferSameNode() {
+        prefer_same_node = true;
+        return *this;
+    }
+
+    PutStartAction& InGroup(std::string value) {
+        group_ids = std::vector<std::string>{std::move(value)};
+        return *this;
+    }
+
+    PutStartAction& InGroups(std::initializer_list<std::string> values) {
+        group_ids.emplace(values.begin(), values.end());
+        return *this;
+    }
+
+    PutStartAction& WithSoftPin() {
+        soft_pin_action = SoftPinAction::ENABLE;
+        return *this;
+    }
+
+    PutStartAction& WithSoftPinAction(SoftPinAction value) {
+        soft_pin_action = value;
+        return *this;
+    }
+
+    PutStartAction& WithSoftPinTtl(uint64_t value) {
+        soft_pin_ttl_ms = value;
+        return *this;
+    }
+
+    PutStartAction& WithHardPin() {
+        with_hard_pin = true;
+        return *this;
+    }
+
+    auto ExpectError(ErrorCode value) const
+        requires(expectation == PutStartExpectation::UNSPECIFIED)
+    {
+        PutStartAction<PutStartExpectation::ERROR> action(*this);
+        action.expected_error = value;
+        return action;
+    }
+
+    auto ExpectReplicas(size_t value) const
+        requires(expectation != PutStartExpectation::ERROR)
+    {
+        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
+        action.expected_replica_count = value;
+        return action;
+    }
+
+    auto ExpectStatus(ReplicaStatus value) const
+        requires(expectation != PutStartExpectation::ERROR)
+    {
+        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
+        action.expected_replica_status = value;
+        return action;
+    }
+
+    auto ExpectMemoryNodes(std::initializer_list<std::string> values) const
+        requires(expectation != PutStartExpectation::ERROR)
+    {
+        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
+        action.expected_memory_nodes.emplace(values.begin(), values.end());
+        return action;
+    }
+
+    auto Eventually(
+        std::chrono::milliseconds timeout = std::chrono::seconds(2)) const
+        requires(expectation != PutStartExpectation::ERROR)
+    {
+        PutStartAction<PutStartExpectation::SUCCESS> action(*this);
+        action.eventual_timeout = timeout;
+        return action;
+    }
+
+   private:
+    template <PutStartExpectation other>
+    friend struct PutStartAction;
+
+    template <PutStartExpectation other>
+    PutStartAction(const PutStartAction<other>& action)
+        : PutStartActionData(action) {}
+};
+
+PutStartAction<> PutStart(std::string key, uint64_t size);
+
+enum class UpsertStartExpectation {
+    UNSPECIFIED,
+    SUCCESS,
+    ERROR,
+};
+
+template <UpsertStartExpectation expectation =
+              UpsertStartExpectation::UNSPECIFIED>
+struct UpsertStartAction;
+
+struct UpsertStartActionData {
+    UpsertStartActionData(const UpsertStartActionData&) = default;
+
+   private:
+    UpsertStartActionData(std::string value, uint64_t object_size)
+        : key(std::move(value)), size(object_size) {}
+
+    std::string key;
+    uint64_t size;
+    std::string actor{"default"};
+    size_t requested_replica_count{1};
+    std::string tenant{TenantId::Default().value()};
+    std::string preferred_node;
+    std::optional<std::string> group_id{};
+    std::optional<ErrorCode> expected_error{};
+    std::optional<size_t> expected_replica_count{};
+    std::optional<ReplicaStatus> expected_replica_status{};
+    std::optional<bool> expected_buffer_reuse{};
+
+    template <UpsertStartExpectation>
+    friend struct UpsertStartAction;
+    friend class MasterScenario;
+};
+
+template <UpsertStartExpectation expectation>
+struct UpsertStartAction : UpsertStartActionData {
+    UpsertStartAction(std::string key, uint64_t size)
+        requires(expectation == UpsertStartExpectation::UNSPECIFIED)
+        : UpsertStartActionData(std::move(key), size) {}
+
+    UpsertStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    UpsertStartAction& Replicas(size_t value) {
+        requested_replica_count = value;
+        return *this;
+    }
+
+    UpsertStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    UpsertStartAction& OnNode(std::string value) {
+        preferred_node = std::move(value);
+        return *this;
+    }
+
+    UpsertStartAction& InGroup(std::string value) {
+        group_id = std::move(value);
+        return *this;
+    }
+
+    auto ExpectError(ErrorCode value) const
+        requires(expectation == UpsertStartExpectation::UNSPECIFIED)
+    {
+        UpsertStartAction<UpsertStartExpectation::ERROR> action(*this);
+        action.expected_error = value;
+        return action;
+    }
+
+    auto ExpectReplicas(size_t value) const
+        requires(expectation != UpsertStartExpectation::ERROR)
+    {
+        UpsertStartAction<UpsertStartExpectation::SUCCESS> action(*this);
+        action.expected_replica_count = value;
+        return action;
+    }
+
+    auto ExpectStatus(ReplicaStatus value) const
+        requires(expectation != UpsertStartExpectation::ERROR)
+    {
+        UpsertStartAction<UpsertStartExpectation::SUCCESS> action(*this);
+        action.expected_replica_status = value;
+        return action;
+    }
+
+    auto ExpectBufferReuse() const
+        requires(expectation != UpsertStartExpectation::ERROR)
+    {
+        UpsertStartAction<UpsertStartExpectation::SUCCESS> action(*this);
+        action.expected_buffer_reuse = true;
+        return action;
+    }
+
+    auto ExpectNewBuffer() const
+        requires(expectation != UpsertStartExpectation::ERROR)
+    {
+        UpsertStartAction<UpsertStartExpectation::SUCCESS> action(*this);
+        action.expected_buffer_reuse = false;
+        return action;
+    }
+
+   private:
+    template <UpsertStartExpectation other>
+    friend struct UpsertStartAction;
+
+    template <UpsertStartExpectation other>
+    UpsertStartAction(const UpsertStartAction<other>& action)
+        : UpsertStartActionData(action) {}
+};
+
+UpsertStartAction<> UpsertStart(std::string key, uint64_t size);
+
+struct PutEndAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<uint64_t> checksum{};
+    std::optional<ErrorCode> expected_error{};
+    ReplicaType replica_type{ReplicaType::MEMORY};
+
+    PutEndAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    PutEndAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    PutEndAction& WithChecksum(uint64_t value) {
+        checksum = value;
+        return *this;
+    }
+
+    PutEndAction& OfType(ReplicaType value) {
+        replica_type = value;
+        return *this;
+    }
+
+    PutEndAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+PutEndAction PutEnd(std::string key);
+
+struct UpsertEndAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<uint64_t> checksum{};
+    std::optional<ErrorCode> expected_error{};
+    ReplicaType replica_type{ReplicaType::MEMORY};
+
+    UpsertEndAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    UpsertEndAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    UpsertEndAction& WithChecksum(uint64_t value) {
+        checksum = value;
+        return *this;
+    }
+
+    UpsertEndAction& OfType(ReplicaType value) {
+        replica_type = value;
+        return *this;
+    }
+
+    UpsertEndAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+UpsertEndAction UpsertEnd(std::string key);
+
+struct PutRevokeAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+    ReplicaType replica_type{ReplicaType::MEMORY};
+
+    PutRevokeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    PutRevokeAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    PutRevokeAction& OfType(ReplicaType value) {
+        replica_type = value;
+        return *this;
+    }
+
+    PutRevokeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+PutRevokeAction PutRevoke(std::string key);
+
+struct UpsertRevokeAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+    ReplicaType replica_type{ReplicaType::MEMORY};
+
+    UpsertRevokeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    UpsertRevokeAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    UpsertRevokeAction& OfType(ReplicaType value) {
+        replica_type = value;
+        return *this;
+    }
+
+    UpsertRevokeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+UpsertRevokeAction UpsertRevoke(std::string key);
+
+struct BatchUpsertStartAction {
+    std::vector<std::string> keys;
+    std::vector<uint64_t> sizes;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    size_t requested_replica_count{1};
+    std::string preferred_node;
+    std::optional<std::vector<std::string>> group_ids{};
+    std::optional<ErrorCode> expected_error{};
+    std::optional<size_t> expected_replica_count{};
+    std::optional<ReplicaStatus> expected_replica_status{};
+
+    BatchUpsertStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    BatchUpsertStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    BatchUpsertStartAction& Replicas(size_t value) {
+        requested_replica_count = value;
+        return *this;
+    }
+
+    BatchUpsertStartAction& OnNode(std::string value) {
+        preferred_node = std::move(value);
+        return *this;
+    }
+
+    BatchUpsertStartAction& InGroups(
+        std::initializer_list<std::string> values) {
+        group_ids.emplace(values.begin(), values.end());
+        return *this;
+    }
+
+    BatchUpsertStartAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+
+    BatchUpsertStartAction& ExpectReplicas(size_t value) {
+        expected_replica_count = value;
+        return *this;
+    }
+
+    BatchUpsertStartAction& ExpectStatus(ReplicaStatus value) {
+        expected_replica_status = value;
+        return *this;
+    }
+};
+
+BatchUpsertStartAction BatchUpsertStart(
+    std::initializer_list<std::pair<std::string, uint64_t>> objects);
+
+struct BatchUpsertEndAction {
+    std::vector<std::string> keys;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+
+    BatchUpsertEndAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    BatchUpsertEndAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+};
+
+BatchUpsertEndAction BatchUpsertEnd(std::initializer_list<std::string> keys);
+
+struct BatchRemoveAction {
+    std::vector<std::string> keys;
+    std::string tenant{TenantId::Default().value()};
+    bool force{false};
+    std::optional<ErrorCode> expected_error{};
+
+    BatchRemoveAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    BatchRemoveAction& Force() {
+        force = true;
+        return *this;
+    }
+
+    BatchRemoveAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+BatchRemoveAction BatchRemove(std::initializer_list<std::string> keys);
+
+struct RemoveAction {
+    std::string key;
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+    bool force{false};
+
+    RemoveAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+
+    RemoveAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    RemoveAction& Force() {
+        force = true;
+        return *this;
+    }
+};
+
+RemoveAction Remove(std::string key);
+
+struct ClearReplicasAction {
+    std::vector<std::string> keys;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::string node;
+    std::optional<std::vector<std::string>> expected_cleared{};
+    std::optional<ErrorCode> expected_error{};
+
+    ClearReplicasAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    ClearReplicasAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    ClearReplicasAction& FromNode(std::string value) {
+        node = std::move(value);
+        return *this;
+    }
+
+    ClearReplicasAction& ExpectCleared(
+        std::initializer_list<std::string> values) {
+        expected_cleared.emplace(values.begin(), values.end());
+        return *this;
+    }
+
+    ClearReplicasAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+ClearReplicasAction ClearReplicas(std::initializer_list<std::string> keys);
+
+struct CopyStartAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::string source{};
+    std::vector<std::string> targets{};
+    std::optional<std::vector<std::string>> expected_allocated_targets{};
+    std::optional<ErrorCode> expected_error{};
+
+    CopyStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CopyStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CopyStartAction& From(std::string value) {
+        source = std::move(value);
+        return *this;
+    }
+
+    CopyStartAction& To(std::initializer_list<std::string> values) {
+        targets.assign(values.begin(), values.end());
+        return *this;
+    }
+
+    CopyStartAction& ExpectAllocatedTargets(
+        std::initializer_list<std::string> values) {
+        expected_allocated_targets.emplace(values.begin(), values.end());
+        return *this;
+    }
+
+    CopyStartAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CopyStartAction CopyStart(std::string key);
+
+struct CopyEndAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+
+    CopyEndAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CopyEndAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CopyEndAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CopyEndAction CopyEnd(std::string key);
+
+struct CopyRevokeAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+
+    CopyRevokeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CopyRevokeAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CopyRevokeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CopyRevokeAction CopyRevoke(std::string key);
+
+struct MoveStartAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::string source{};
+    std::string target{};
+    std::optional<bool> expected_target_allocation{};
+    std::optional<ErrorCode> expected_error{};
+
+    MoveStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    MoveStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    MoveStartAction& From(std::string value) {
+        source = std::move(value);
+        return *this;
+    }
+
+    MoveStartAction& To(std::string value) {
+        target = std::move(value);
+        return *this;
+    }
+
+    MoveStartAction& ExpectTargetAllocation() {
+        expected_target_allocation = true;
+        return *this;
+    }
+
+    MoveStartAction& ExpectNoTargetAllocation() {
+        expected_target_allocation = false;
+        return *this;
+    }
+
+    MoveStartAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MoveStartAction MoveStart(std::string key);
+
+struct MoveEndAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+
+    MoveEndAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    MoveEndAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    MoveEndAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MoveEndAction MoveEnd(std::string key);
+
+struct MoveRevokeAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::optional<ErrorCode> expected_error{};
+
+    MoveRevokeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    MoveRevokeAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    MoveRevokeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MoveRevokeAction MoveRevoke(std::string key);
+
+struct CreateCopyTaskAction {
+    std::string name;
+    std::string key;
+    std::string tenant{TenantId::Default().value()};
+    std::vector<std::string> targets{};
+    std::optional<ErrorCode> expected_error{};
+
+    CreateCopyTaskAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CreateCopyTaskAction& To(std::initializer_list<std::string> values) {
+        targets.assign(values.begin(), values.end());
+        return *this;
+    }
+
+    CreateCopyTaskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CreateCopyTaskAction CreateCopyTask(std::string name, std::string key);
+
+struct CreateMoveTaskAction {
+    std::string name;
+    std::string key;
+    std::string tenant{TenantId::Default().value()};
+    std::string source{};
+    std::string target{};
+    std::optional<ErrorCode> expected_error{};
+
+    CreateMoveTaskAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CreateMoveTaskAction& From(std::string value) {
+        source = std::move(value);
+        return *this;
+    }
+
+    CreateMoveTaskAction& To(std::string value) {
+        target = std::move(value);
+        return *this;
+    }
+
+    CreateMoveTaskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CreateMoveTaskAction CreateMoveTask(std::string name, std::string key);
+
+struct FetchTasksAction {
+    std::string actor{"default"};
+    size_t batch_size{16};
+    std::optional<size_t> expected_count{};
+    std::optional<ErrorCode> expected_error{};
+
+    FetchTasksAction& Limit(size_t value) {
+        batch_size = value;
+        return *this;
+    }
+
+    FetchTasksAction& ExpectCount(size_t value) {
+        expected_count = value;
+        return *this;
+    }
+
+    FetchTasksAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+FetchTasksAction FetchTasks(std::string actor);
+
+struct CompleteTaskAction {
+    std::string name;
+    std::string actor{"default"};
+    TaskStatus status{TaskStatus::SUCCESS};
+    std::string message{};
+    std::optional<ErrorCode> expected_error{};
+
+    CompleteTaskAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CompleteTaskAction& WithStatus(TaskStatus value) {
+        status = value;
+        return *this;
+    }
+
+    CompleteTaskAction& WithMessage(std::string value) {
+        message = std::move(value);
+        return *this;
+    }
+
+    CompleteTaskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CompleteTaskAction CompleteTask(std::string name);
+
+struct CompleteUnknownTaskAction {
+    std::string name;
+    std::string actor{"default"};
+    TaskStatus status{TaskStatus::FAILED};
+    std::string message{};
+    std::optional<ErrorCode> expected_error{};
+
+    CompleteUnknownTaskAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CompleteUnknownTaskAction& WithStatus(TaskStatus value) {
+        status = value;
+        return *this;
+    }
+
+    CompleteUnknownTaskAction& WithMessage(std::string value) {
+        message = std::move(value);
+        return *this;
+    }
+
+    CompleteUnknownTaskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CompleteUnknownTaskAction CompleteUnknownTask(std::string name);
+
+struct RemoveByRegexAction {
+    std::string pattern;
+    std::string tenant{TenantId::Default().value()};
+    bool force{false};
+    std::optional<size_t> expected_removed{};
+    std::optional<ErrorCode> expected_error{};
+
+    RemoveByRegexAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    RemoveByRegexAction& Force() {
+        force = true;
+        return *this;
+    }
+
+    RemoveByRegexAction& ExpectRemoved(size_t value) {
+        expected_removed = value;
+        return *this;
+    }
+
+    RemoveByRegexAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+RemoveByRegexAction RemoveByRegex(std::string pattern);
+
+struct UnmountMemoryNodeAction {
+    std::string node;
+    std::string actor;
+    std::optional<ErrorCode> expected_error{};
+    bool unknown{false};
+    std::optional<std::chrono::milliseconds> maximum_duration{};
+
+    UnmountMemoryNodeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    UnmountMemoryNodeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+
+    UnmountMemoryNodeAction& Unknown() {
+        unknown = true;
+        return *this;
+    }
+
+    UnmountMemoryNodeAction& Within(std::chrono::milliseconds value) {
+        maximum_duration = value;
+        return *this;
+    }
+};
+
+UnmountMemoryNodeAction UnmountMemoryNode(std::string node);
+
+struct GracefulUnmountMemoryNodeAction {
+    std::string node;
+    std::string actor;
+    uint64_t grace_period_ms{1000};
+    std::optional<ErrorCode> expected_error{};
+
+    GracefulUnmountMemoryNodeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    GracefulUnmountMemoryNodeAction& After(std::chrono::milliseconds value) {
+        grace_period_ms = static_cast<uint64_t>(value.count());
+        return *this;
+    }
+
+    GracefulUnmountMemoryNodeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+GracefulUnmountMemoryNodeAction GracefullyUnmountMemoryNode(std::string node);
+
+struct MountMemorySegmentAction {
+    std::string alias;
+    std::string name;
+    uintptr_t base{0x400000000};
+    uint64_t capacity{16 * 1024 * 1024};
+    std::string endpoint;
+    std::string actor;
+    std::optional<ErrorCode> expected_error{};
+
+    MountMemorySegmentAction& Named(std::string value) {
+        name = std::move(value);
+        return *this;
+    }
+
+    MountMemorySegmentAction& Base(uintptr_t value) {
+        base = value;
+        return *this;
+    }
+
+    MountMemorySegmentAction& Capacity(uint64_t value) {
+        capacity = value;
+        return *this;
+    }
+
+    MountMemorySegmentAction& Endpoint(std::string value) {
+        endpoint = std::move(value);
+        return *this;
+    }
+
+    MountMemorySegmentAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    MountMemorySegmentAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MountMemorySegmentAction MountMemorySegment(std::string alias);
+
+struct MountUnmountMemoryCapacitiesAction {
+    std::string name;
+    std::vector<uint64_t> capacities;
+};
+
+MountUnmountMemoryCapacitiesAction MountUnmountMemoryCapacities(
+    std::string name, std::initializer_list<uint64_t> capacities);
+
+struct RemoveAllAction {
+    std::optional<std::string> tenant{};
+    bool force{false};
+    std::optional<size_t> expected_removed{};
+
+    RemoveAllAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    RemoveAllAction& Force() {
+        force = true;
+        return *this;
+    }
+
+    RemoveAllAction& ExpectRemoved(size_t value) {
+        expected_removed = value;
+        return *this;
+    }
+};
+
+RemoveAllAction RemoveAll();
+
+struct ExpireAtAction {
+    std::string key;
+    std::chrono::system_clock::time_point lease_timeout;
+    std::string tenant{TenantId::Default().value()};
+    std::optional<std::chrono::system_clock::time_point> soft_pin_timeout{};
+
+    ExpireAtAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    ExpireAtAction& SoftPinnedUntil(
+        std::chrono::system_clock::time_point value) {
+        soft_pin_timeout = value;
+        return *this;
+    }
+};
+
+ExpireAtAction ExpireAt(std::string key,
+                        std::chrono::system_clock::time_point lease_timeout);
+
+struct MemoryEvictAction {
+    double target_ratio;
+    double lower_bound_ratio;
+
+    MemoryEvictAction& ToLowerBound(double value) {
+        lower_bound_ratio = value;
+        return *this;
+    }
+};
+
+MemoryEvictAction EvictMemory(double target_ratio);
+
+struct DfsEvictAction {};
+
+DfsEvictAction EvictDfs();
+
+// Drives one pass of the per-tenant quota watermark evictor.
+struct TenantEvictAction {};
+
+TenantEvictAction EvictTenants();
+
+struct WaitAction {
+    std::chrono::milliseconds duration;
+};
+
+WaitAction WaitFor(std::chrono::milliseconds duration);
+
+struct WaitForOpLogFailureAction {
+    std::chrono::milliseconds timeout{std::chrono::seconds(1)};
+};
+
+WaitForOpLogFailureAction WaitForOpLogFailure();
+
+struct PingAction {
+    std::string actor;
+    std::optional<ErrorCode> expected_error{};
+
+    PingAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+PingAction Ping(std::string actor);
+
+struct MountMemoryNodeAction {
+    std::string node;
+    std::string actor;
+    std::optional<ErrorCode> expected_error{};
+
+    MountMemoryNodeAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    MountMemoryNodeAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MountMemoryNodeAction MountMemoryNode(std::string node);
+
+struct MountLocalDiskAction {
+    std::string actor;
+    bool enable_offloading{true};
+    std::optional<ErrorCode> expected_error{};
+
+    MountLocalDiskAction& OffloadingDisabled() {
+        enable_offloading = false;
+        return *this;
+    }
+
+    MountLocalDiskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+MountLocalDiskAction MountLocalDisk(std::string actor);
+
+struct UnmountLocalDiskAction {
+    std::string actor;
+    std::optional<ErrorCode> expected_error{};
+
+    UnmountLocalDiskAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+UnmountLocalDiskAction UnmountLocalDisk(std::string actor);
+
+struct ReportSsdCapacityAction {
+    std::string actor;
+    int64_t capacity_bytes{0};
+    std::optional<ErrorCode> expected_error{};
+
+    ReportSsdCapacityAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+ReportSsdCapacityAction ReportSsdCapacity(std::string actor,
+                                          int64_t capacity_bytes);
+
+struct OffloadHeartbeatAction {
+    std::string actor;
+    std::string tenant{TenantId::Default().value()};
+    bool enable_offloading{true};
+    bool expect_some_tasks{false};
+    std::optional<std::vector<std::string>> expected_task_keys{};
+    int64_t expected_task_size{0};
+    std::optional<ErrorCode> expected_error{};
+
+    OffloadHeartbeatAction& Disabled() {
+        enable_offloading = false;
+        return *this;
+    }
+
+    OffloadHeartbeatAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    OffloadHeartbeatAction& ExpectTasks(std::vector<std::string> keys,
+                                        int64_t size_each) {
+        expected_task_keys = std::move(keys);
+        expected_task_size = size_each;
+        return *this;
+    }
+
+    OffloadHeartbeatAction& ExpectNoTasks() {
+        expected_task_keys.emplace();
+        return *this;
+    }
+
+    OffloadHeartbeatAction& ExpectSomeTasks() {
+        expect_some_tasks = true;
+        return *this;
+    }
+
+    OffloadHeartbeatAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+OffloadHeartbeatAction OffloadHeartbeat(std::string actor);
+
+struct CompleteOffloadAction {
+    std::vector<std::string> keys;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::string node;
+    std::optional<int64_t> size{};
+    std::optional<ErrorCode> expected_error{};
+
+    CompleteOffloadAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    CompleteOffloadAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    CompleteOffloadAction& OnNode(std::string value) {
+        node = std::move(value);
+        return *this;
+    }
+
+    CompleteOffloadAction& OfSize(int64_t value) {
+        size = value;
+        return *this;
+    }
+
+    CompleteOffloadAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+CompleteOffloadAction CompleteOffload(std::initializer_list<std::string> keys);
+
+struct EvictDiskReplicaAction {
+    std::string key;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    ReplicaType replica_type{ReplicaType::DISK};
+    std::optional<ErrorCode> expected_error{};
+
+    EvictDiskReplicaAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    EvictDiskReplicaAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    EvictDiskReplicaAction& OfType(ReplicaType value) {
+        replica_type = value;
+        return *this;
+    }
+
+    EvictDiskReplicaAction& ExpectError(ErrorCode value) {
+        expected_error = value;
+        return *this;
+    }
+};
+
+EvictDiskReplicaAction EvictDiskReplica(std::string key);
+
+struct RacePutStartAction {
+    std::string key;
+    uint64_t size;
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::vector<std::string> group_ids;
+    size_t thread_count{16};
+    size_t expected_successes{1};
+    size_t expected_completions{1};
+
+    RacePutStartAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    RacePutStartAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    RacePutStartAction& AcrossGroups(
+        std::initializer_list<std::string> values) {
+        group_ids.assign(values.begin(), values.end());
+        return *this;
+    }
+
+    RacePutStartAction& Threads(size_t value) {
+        thread_count = value;
+        return *this;
+    }
+
+    RacePutStartAction& ExpectSuccesses(size_t value) {
+        expected_successes = value;
+        return *this;
+    }
+
+    RacePutStartAction& ExpectCompletions(size_t value) {
+        expected_completions = value;
+        return *this;
+    }
+};
+
+RacePutStartAction RacePutStart(std::string key, uint64_t size);
+
+struct RaceMountUnmountAction {
+    std::string prefix;
+    size_t node_count{4};
+    size_t iterations{100};
+    uint64_t capacity{16 * 1024 * 1024};
+    size_t expected_min_cycles{1};
+
+    RaceMountUnmountAction& Nodes(size_t value) {
+        node_count = value;
+        return *this;
+    }
+
+    RaceMountUnmountAction& Iterations(size_t value) {
+        iterations = value;
+        return *this;
+    }
+
+    RaceMountUnmountAction& EachOfCapacity(uint64_t value) {
+        capacity = value;
+        return *this;
+    }
+
+    RaceMountUnmountAction& ExpectCyclesAtLeast(size_t value) {
+        expected_min_cycles = value;
+        return *this;
+    }
+};
+
+RaceMountUnmountAction RaceMountUnmount(std::string prefix);
+
+struct RaceMountLocalDiskAction {
+    std::string prefix;
+    size_t client_count{100};
+
+    RaceMountLocalDiskAction& Clients(size_t value) {
+        client_count = value;
+        return *this;
+    }
+};
+
+RaceMountLocalDiskAction RaceMountLocalDisk(std::string prefix);
+
+struct RaceWritesWithRemoveAllAction {
+    std::string prefix;
+    size_t writer_count{4};
+    size_t objects_per_writer{100};
+    uint64_t object_size{1024};
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+
+    RaceWritesWithRemoveAllAction& Writers(size_t value) {
+        writer_count = value;
+        return *this;
+    }
+
+    RaceWritesWithRemoveAllAction& ObjectsPerWriter(size_t value) {
+        objects_per_writer = value;
+        return *this;
+    }
+
+    RaceWritesWithRemoveAllAction& OfSize(uint64_t value) {
+        object_size = value;
+        return *this;
+    }
+
+    RaceWritesWithRemoveAllAction& By(std::string value) {
+        actor = std::move(value);
+        return *this;
+    }
+
+    RaceWritesWithRemoveAllAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+};
+
+RaceWritesWithRemoveAllAction RaceWritesWithRemoveAll(std::string prefix);
+
+struct RaceReadsWithRemoveAllAction {
+    std::vector<std::string> keys;
+    std::string tenant{TenantId::Default().value()};
+    size_t reader_count{4};
+    std::chrono::milliseconds final_remove_after{std::chrono::milliseconds(0)};
+    std::optional<size_t> expected_total_removed{};
+
+    RaceReadsWithRemoveAllAction& Readers(size_t value) {
+        reader_count = value;
+        return *this;
+    }
+
+    RaceReadsWithRemoveAllAction& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    RaceReadsWithRemoveAllAction& FinalRemoveAfter(
+        std::chrono::milliseconds value) {
+        final_remove_after = value;
+        return *this;
+    }
+
+    RaceReadsWithRemoveAllAction& ExpectTotalRemoved(size_t value) {
+        expected_total_removed = value;
+        return *this;
+    }
+};
+
+RaceReadsWithRemoveAllAction RaceReadsWithRemoveAll(
+    std::vector<std::string> keys);
+
+struct RaceRemoveAllAction {
+    size_t caller_count{2};
+    std::optional<size_t> expected_total_removed{};
+
+    RaceRemoveAllAction& Callers(size_t value) {
+        caller_count = value;
+        return *this;
+    }
+
+    RaceRemoveAllAction& ExpectTotalRemoved(size_t value) {
+        expected_total_removed = value;
+        return *this;
+    }
+};
+
+RaceRemoveAllAction RaceRemoveAll();
+
+enum class ObjectExpectation {
+    UNSPECIFIED,
+    READABLE,
+    NOT_READY,
+    MISSING,
+};
+
+template <ObjectExpectation expectation = ObjectExpectation::UNSPECIFIED>
+struct ObjectSpec;
+
+struct ObjectSpecData {
+    ObjectSpecData(const ObjectSpecData&) = default;
+
+   private:
+    explicit ObjectSpecData(std::string value) : key(std::move(value)) {}
+
+    std::string key;
+    std::string tenant{TenantId::Default().value()};
+    std::optional<size_t> expected_replica_count{};
+    std::optional<size_t> expected_complete_replica_count{};
+    std::optional<std::optional<uint64_t>> expected_checksum{};
+    std::optional<uint64_t> expected_memory_replica_size{};
+    std::optional<size_t> expected_memory_replica_count{};
+    std::optional<size_t> expected_nof_replica_count{};
+    std::optional<size_t> expected_dfs_replica_count{};
+    std::optional<size_t> expected_local_disk_replica_count{};
+    std::optional<size_t> expected_disk_replica_count{};
+    std::optional<size_t> expected_complete_memory_replica_count{};
+    std::optional<size_t> expected_complete_nof_replica_count{};
+    std::optional<size_t> expected_complete_dfs_replica_count{};
+    std::optional<size_t> expected_complete_local_disk_replica_count{};
+    std::optional<size_t> expected_complete_disk_replica_count{};
+    std::optional<std::string> expected_memory_node{};
+    std::optional<std::vector<std::string>> expected_memory_nodes{};
+    bool expect_distinct_memory_nodes{false};
+
+    template <ObjectExpectation>
+    friend struct ObjectSpec;
+    friend class MasterScenario;
+};
+
+template <ObjectExpectation expectation>
+struct ObjectSpec : ObjectSpecData {
+    explicit ObjectSpec(std::string key)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+        : ObjectSpecData(std::move(key)) {}
+
+    auto IsReadable() const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        return ObjectSpec<ObjectExpectation::READABLE>(*this);
+    }
+
+    auto IsNotReady() const
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        return ObjectSpec<ObjectExpectation::NOT_READY>(*this);
+    }
+
+    auto DoesNotExist() const
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        return ObjectSpec<ObjectExpectation::MISSING>(*this);
+    }
+
+    ObjectSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    auto HasReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_replica_count = value;
+        return object;
+    }
+
+    auto HasChecksum(uint64_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_checksum.emplace(value);
+        return object;
+    }
+
+    auto HasNoChecksum() const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_checksum.emplace(std::nullopt);
+        return object;
+    }
+
+    auto HasMemoryReplicaSize(uint64_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_memory_replica_size = value;
+        return object;
+    }
+
+    auto HasMemoryReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_memory_replica_count = value;
+        return object;
+    }
+
+    auto HasNoFReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_nof_replica_count = value;
+        return object;
+    }
+
+    auto HasDfsReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_dfs_replica_count = value;
+        return object;
+    }
+
+    auto HasLocalDiskReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_local_disk_replica_count = value;
+        return object;
+    }
+
+    auto HasDiskReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_disk_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteMemoryReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_memory_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteNoFReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_nof_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteDfsReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_dfs_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteLocalDiskReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_local_disk_replica_count = value;
+        return object;
+    }
+
+    auto HasCompleteDiskReplicas(size_t value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_complete_disk_replica_count = value;
+        return object;
+    }
+
+    auto IsOnMemoryNode(std::string value) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_memory_node = std::move(value);
+        return object;
+    }
+
+    auto HasMemoryNodes(std::initializer_list<std::string> values) const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expected_memory_nodes.emplace(values.begin(), values.end());
+        return object;
+    }
+
+    auto HasDistinctMemoryNodes() const
+        requires(expectation != ObjectExpectation::NOT_READY &&
+                 expectation != ObjectExpectation::MISSING)
+    {
+        ObjectSpec<ObjectExpectation::READABLE> object(*this);
+        object.expect_distinct_memory_nodes = true;
+        return object;
+    }
+
+   private:
+    template <ObjectExpectation other>
+    friend struct ObjectSpec;
+
+    template <ObjectExpectation other>
+    ObjectSpec(const ObjectSpec<other>& object) : ObjectSpecData(object) {}
+};
+
+ObjectSpec<> Object(std::string key);
+
+struct ObjectsSpecData {
+    std::vector<size_t> indices;
+    std::vector<std::string> keys;
+    uint64_t size{0};
+    std::string actor{"default"};
+    std::string tenant{TenantId::Default().value()};
+    std::string preferred_node;
+    std::string group_id;
+    bool with_soft_pin{false};
+    bool with_hard_pin{false};
+    std::optional<std::chrono::system_clock::time_point> lease_timeout_base{};
+    std::chrono::nanoseconds lease_timeout_step{1};
+    std::optional<std::chrono::system_clock::time_point> soft_pin_timeout{};
+};
+
+template <ObjectExpectation expectation = ObjectExpectation::UNSPECIFIED>
+struct ObjectsSpec : ObjectsSpecData {
+    ObjectsSpec(size_t begin, size_t end)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        indices.reserve(end > begin ? end - begin : 0);
+        for (size_t index = begin; index < end; ++index) {
+            indices.push_back(index);
+        }
+    }
+
+    explicit ObjectsSpec(std::vector<std::string> values)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        keys = std::move(values);
+    }
+
+    template <typename KeyFactory>
+    ObjectsSpec& NamedBy(KeyFactory&& key_factory)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        keys.clear();
+        keys.reserve(indices.size());
+        for (const size_t index : indices) {
+            keys.push_back(std::invoke(key_factory, index));
+        }
+        return *this;
+    }
+
+    ObjectsSpec& Size(uint64_t value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        size = value;
+        return *this;
+    }
+
+    ObjectsSpec& By(std::string value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        actor = std::move(value);
+        return *this;
+    }
+
+    ObjectsSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    ObjectsSpec& CompleteOn(std::string value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        preferred_node = std::move(value);
+        return *this;
+    }
+
+    ObjectsSpec& InGroup(std::string value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        group_id = std::move(value);
+        return *this;
+    }
+
+    ObjectsSpec& WithSoftPin()
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        with_soft_pin = true;
+        return *this;
+    }
+
+    ObjectsSpec& WithHardPin()
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        with_hard_pin = true;
+        return *this;
+    }
+
+    ObjectsSpec& ExpiredFrom(
+        std::chrono::system_clock::time_point value,
+        std::chrono::nanoseconds step = std::chrono::nanoseconds(1))
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        lease_timeout_base = value;
+        lease_timeout_step = step;
+        return *this;
+    }
+
+    ObjectsSpec& ExpiresAt(std::chrono::system_clock::time_point value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        lease_timeout_base = value;
+        lease_timeout_step = std::chrono::nanoseconds::zero();
+        return *this;
+    }
+
+    ObjectsSpec& SoftPinnedUntil(std::chrono::system_clock::time_point value)
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        with_soft_pin = true;
+        soft_pin_timeout = value;
+        return *this;
+    }
+
+    auto AreReadable() const
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        return ObjectsSpec<ObjectExpectation::READABLE>(*this);
+    }
+
+    auto AreNotReady() const
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        return ObjectsSpec<ObjectExpectation::NOT_READY>(*this);
+    }
+
+    auto DoNotExist() const
+        requires(expectation == ObjectExpectation::UNSPECIFIED)
+    {
+        return ObjectsSpec<ObjectExpectation::MISSING>(*this);
+    }
+
+   private:
+    template <ObjectExpectation other>
+    friend struct ObjectsSpec;
+
+    template <ObjectExpectation other>
+    ObjectsSpec(const ObjectsSpec<other>& objects) : ObjectsSpecData(objects) {}
+};
+
+ObjectsSpec<> Objects(size_t begin, size_t end);
+ObjectsSpec<> Objects(std::initializer_list<std::string> keys);
+
+struct ReadableObjectCountSpec {
+    ObjectsSpecData objects;
+    size_t expected;
+};
+
+ReadableObjectCountSpec ReadableCount(ObjectsSpec<> objects, size_t expected);
+
+struct KeyExistsSpec {
+    std::string key;
+    std::string tenant{TenantId::Default().value()};
+
+    KeyExistsSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+};
+
+KeyExistsSpec KeyExists(std::string key);
+
+struct BatchExistenceSpec {
+    std::vector<std::string> keys;
+    std::string tenant{TenantId::Default().value()};
+    std::vector<bool> expected;
+
+    BatchExistenceSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    BatchExistenceSpec& Returns(std::initializer_list<bool> values) {
+        expected.assign(values.begin(), values.end());
+        return *this;
+    }
+};
+
+BatchExistenceSpec BatchExistence(std::initializer_list<std::string> keys);
+
+struct BatchReplicaListsSpec {
+    std::vector<std::string> keys;
+    std::string tenant{TenantId::Default().value()};
+    std::vector<ErrorCode> expected;
+
+    BatchReplicaListsSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    BatchReplicaListsSpec& Returns(std::initializer_list<ErrorCode> values) {
+        expected.assign(values.begin(), values.end());
+        return *this;
+    }
+};
+
+BatchReplicaListsSpec BatchReplicaLists(
+    std::initializer_list<std::string> keys);
+
+struct NamedTaskSpec {
+    std::string name;
+    std::optional<TaskType> expected_type{};
+    std::optional<TaskStatus> expected_status{};
+    std::optional<std::string> expected_actor{};
+    std::optional<std::string> expected_message{};
+
+    NamedTaskSpec& HasType(TaskType value) {
+        expected_type = value;
+        return *this;
+    }
+
+    NamedTaskSpec& HasStatus(TaskStatus value) {
+        expected_status = value;
+        return *this;
+    }
+
+    NamedTaskSpec& IsAssignedTo(std::string value) {
+        expected_actor = std::move(value);
+        return *this;
+    }
+
+    NamedTaskSpec& HasMessage(std::string value) {
+        expected_message = std::move(value);
+        return *this;
+    }
+};
+
+NamedTaskSpec NamedTask(std::string name);
+
+struct UnknownTaskSpec {
+    std::string name;
+    ErrorCode expected_error{ErrorCode::TASK_NOT_FOUND};
+};
+
+UnknownTaskSpec UnknownTask(std::string name);
+
+struct MatchingKeysSpec {
+    std::string pattern;
+    std::string tenant{TenantId::Default().value()};
+    std::optional<size_t> expected_count{};
+    std::vector<std::string> expected_keys;
+
+    MatchingKeysSpec& ForTenant(std::string value) {
+        tenant = std::move(value);
+        return *this;
+    }
+
+    MatchingKeysSpec& HasCount(size_t value) {
+        expected_count = value;
+        return *this;
+    }
+
+    MatchingKeysSpec& HasKeys(std::initializer_list<std::string> values) {
+        expected_keys.assign(values.begin(), values.end());
+        return *this;
+    }
+};
+
+MatchingKeysSpec MatchingKeys(std::string pattern);
+
+struct ClientIpsSpec {
+    std::vector<std::string> actors;
+    std::unordered_map<std::string, std::vector<std::string>> expected;
+    std::vector<std::string> omitted;
+
+    ClientIpsSpec& Returns(std::string actor,
+                           std::initializer_list<std::string> values) {
+        expected.emplace(std::move(actor), std::vector<std::string>(
+                                               values.begin(), values.end()));
+        return *this;
+    }
+
+    ClientIpsSpec& Omits(std::string actor) {
+        omitted.push_back(std::move(actor));
+        return *this;
+    }
+};
+
+ClientIpsSpec ClientIps(std::initializer_list<std::string> actors);
+
+struct MemoryNodeStatusSpec {
+    std::string node;
+    std::optional<SegmentStatus> expected_status{};
+    bool expected_missing{false};
+    bool query_by_id{false};
+    std::chrono::milliseconds eventual_timeout{};
+
+    MemoryNodeStatusSpec& Is(SegmentStatus value) {
+        expected_status = value;
+        return *this;
+    }
+
+    MemoryNodeStatusSpec& DoesNotExist() {
+        expected_missing = true;
+        return *this;
+    }
+
+    MemoryNodeStatusSpec& ById() {
+        query_by_id = true;
+        return *this;
+    }
+
+    MemoryNodeStatusSpec& Eventually(
+        std::chrono::milliseconds timeout = std::chrono::seconds(2)) {
+        eventual_timeout = timeout;
+        return *this;
+    }
+};
+
+MemoryNodeStatusSpec MemoryNodeStatus(std::string node);
+
+std::string GroupOnDifferentShard(std::string_view key);
+
+class MasterScenario {
+   public:
+    explicit MasterScenario(std::string name);
+    MasterScenario(std::string name, MasterServiceConfig config,
+                   std::shared_ptr<HaKvBackend> batch_oplog_backend = nullptr);
+    ~MasterScenario();
+
+    MasterScenario(const MasterScenario&) = delete;
+    MasterScenario& operator=(const MasterScenario&) = delete;
+
+    MasterScenario& Given(MemoryNodeSpec node);
+    MasterScenario& Given(NoFNodeSpec node);
+    MasterScenario& Given(TenantSpec tenant);
+    MasterScenario& Given(ObjectsSpec<> objects);
+    template <PutStartExpectation expectation>
+    MasterScenario& When(PutStartAction<expectation> action) {
+        return WhenPutStart(std::move(action));
+    }
+    template <UpsertStartExpectation expectation>
+    MasterScenario& When(UpsertStartAction<expectation> action) {
+        return WhenUpsertStart(std::move(action));
+    }
+
+    MasterScenario& When(PutEndAction action);
+    MasterScenario& When(UpsertEndAction action);
+    MasterScenario& When(PutRevokeAction action);
+    MasterScenario& When(UpsertRevokeAction action);
+    MasterScenario& When(BatchUpsertStartAction action);
+    MasterScenario& When(BatchUpsertEndAction action);
+    MasterScenario& When(BatchRemoveAction action);
+    MasterScenario& When(RemoveAction action);
+    MasterScenario& When(ClearReplicasAction action);
+    MasterScenario& When(CopyStartAction action);
+    MasterScenario& When(CopyEndAction action);
+    MasterScenario& When(CopyRevokeAction action);
+    MasterScenario& When(MoveStartAction action);
+    MasterScenario& When(MoveEndAction action);
+    MasterScenario& When(MoveRevokeAction action);
+    MasterScenario& When(CreateCopyTaskAction action);
+    MasterScenario& When(CreateMoveTaskAction action);
+    MasterScenario& When(FetchTasksAction action);
+    MasterScenario& When(CompleteTaskAction action);
+    MasterScenario& When(CompleteUnknownTaskAction action);
+    MasterScenario& When(RemoveByRegexAction action);
+    MasterScenario& When(UnmountMemoryNodeAction action);
+    MasterScenario& When(GracefulUnmountMemoryNodeAction action);
+    MasterScenario& When(MountMemorySegmentAction action);
+    MasterScenario& When(MountUnmountMemoryCapacitiesAction action);
+    MasterScenario& When(RemoveAllAction action);
+    MasterScenario& When(ExpireAtAction action);
+    MasterScenario& When(MemoryEvictAction action);
+    MasterScenario& When(DfsEvictAction action);
+    MasterScenario& When(TenantEvictAction action);
+    MasterScenario& When(WaitAction action);
+    MasterScenario& When(WaitForOpLogFailureAction action);
+    MasterScenario& When(PingAction action);
+    MasterScenario& When(MountMemoryNodeAction action);
+    MasterScenario& When(MountLocalDiskAction action);
+    MasterScenario& When(UnmountLocalDiskAction action);
+    MasterScenario& When(ReportSsdCapacityAction action);
+    MasterScenario& When(OffloadHeartbeatAction action);
+    MasterScenario& When(CompleteOffloadAction action);
+    MasterScenario& When(EvictDiskReplicaAction action);
+    MasterScenario& When(RacePutStartAction action);
+    MasterScenario& When(RaceMountUnmountAction action);
+    MasterScenario& When(RaceMountLocalDiskAction action);
+    MasterScenario& When(RaceWritesWithRemoveAllAction action);
+    MasterScenario& When(RaceReadsWithRemoveAllAction action);
+    MasterScenario& When(RaceRemoveAllAction action);
+
+    template <ObjectExpectation expectation>
+        requires(expectation != ObjectExpectation::UNSPECIFIED)
+    MasterScenario& Then(ObjectSpec<expectation> object) {
+        return ThenObject(std::move(object), expectation);
+    }
+    template <ObjectExpectation expectation>
+        requires(expectation != ObjectExpectation::UNSPECIFIED)
+    MasterScenario& Then(ObjectsSpec<expectation> objects) {
+        return ThenObjects(std::move(objects), expectation);
+    }
+    MasterScenario& Then(ReadableObjectCountSpec objects);
+    MasterScenario& Then(KeyExistsSpec key_exists);
+    MasterScenario& Then(BatchExistenceSpec batch_existence);
+    MasterScenario& Then(BatchReplicaListsSpec batch_replica_lists);
+    MasterScenario& Then(NamedTaskSpec task);
+    MasterScenario& Then(UnknownTaskSpec task);
+    MasterScenario& Then(MatchingKeysSpec matching_keys);
+    MasterScenario& Then(ClientIpsSpec client_ips);
+    MasterScenario& Then(MemoryNodeStatusSpec node_status);
+
+   private:
+    using StartResult =
+        tl::expected<std::vector<Replica::Descriptor>, ErrorCode>;
+
+    MasterScenario& WhenPutStart(PutStartActionData action);
+    MasterScenario& WhenUpsertStart(UpsertStartActionData action);
+    MasterScenario& ThenObject(ObjectSpecData object,
+                               ObjectExpectation expectation);
+    MasterScenario& ThenObjects(ObjectsSpecData objects,
+                                ObjectExpectation expectation);
+    bool EnsureService();
+    UUID ActorId(std::string_view actor);
+    void ValidateActionResult(std::string_view action,
+                              const std::optional<ErrorCode>& expected_error,
+                              bool succeeded, ErrorCode error);
+    void ValidateStartResult(
+        std::string_view action, const std::optional<ErrorCode>& expected_error,
+        const std::optional<size_t>& expected_replica_count,
+        const std::optional<ReplicaStatus>& expected_replica_status,
+        const StartResult& result,
+        const std::optional<std::vector<std::string>>& expected_memory_nodes =
+            std::nullopt);
+    void Fail(std::string message) const;
+
+    std::string name_;
+    MasterServiceConfig config_;
+    std::shared_ptr<HaKvBackend> batch_oplog_backend_;
+    bool declarations_frozen_{false};
+    uintptr_t next_segment_base_{0x300000000};
+    std::vector<MemoryNodeSpec> nodes_;
+    std::vector<NoFNodeSpec> nof_nodes_;
+    std::vector<TenantSpec> tenants_;
+    std::string tenant_policy_path_;
+    std::unique_ptr<MasterService> service_;
+    std::unordered_map<std::string, UUID> actor_ids_;
+    std::unordered_map<std::string, UUID> segment_ids_;
+    std::unordered_map<std::string, Segment> segments_;
+    std::unordered_map<std::string, NoFSegment> nof_segments_;
+    std::unordered_map<std::string, UUID> task_ids_;
+    std::unordered_map<std::string, std::vector<Replica::Descriptor>>
+        last_start_results_;
+};
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service/dsl/scenario_contract_test.cpp b/mooncake-store/tests/master_service/dsl/scenario_contract_test.cpp
new file mode 100644
index 0000000000..fd07b1014b
--- /dev/null
+++ b/mooncake-store/tests/master_service/dsl/scenario_contract_test.cpp
@@ -0,0 +1,542 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest-spi.h>
+#include <gtest/gtest.h>
+
+namespace mooncake::test {
+namespace {
+
+template <typename T>
+concept SupportsExpectError =
+    requires(T value) { value.ExpectError(ErrorCode::INTERNAL_ERROR); };
+
+template <typename T>
+concept SupportsExpectReplicas = requires(T value) { value.ExpectReplicas(1); };
+
+template <typename T>
+concept SupportsExpectStatus =
+    requires(T value) { value.ExpectStatus(ReplicaStatus::COMPLETE); };
+
+template <typename T>
+concept SupportsEventually = requires(T value) { value.Eventually(); };
+
+template <typename T>
+concept SupportsIsReadable = requires(T value) { value.IsReadable(); };
+
+template <typename T>
+concept SupportsIsNotReady = requires(T value) { value.IsNotReady(); };
+
+template <typename T>
+concept SupportsDoesNotExist = requires(T value) { value.DoesNotExist(); };
+
+template <typename T>
+concept SupportsHasReplicas = requires(T value) { value.HasReplicas(1); };
+
+template <typename T>
+concept SupportsHasCompleteReplicas =
+    requires(T value) { value.HasCompleteReplicas(1); };
+
+template <typename T>
+concept SupportsHasChecksum = requires(T value) { value.HasChecksum(1); };
+
+template <typename T>
+concept SupportsHasNoChecksum = requires(T value) { value.HasNoChecksum(); };
+
+template <typename T>
+concept SupportsHasMemoryReplicaSize =
+    requires(T value) { value.HasMemoryReplicaSize(1); };
+
+template <typename T>
+concept SupportsIsOnMemoryNode =
+    requires(T value) { value.IsOnMemoryNode("memory"); };
+
+template <typename T>
+concept SupportsExpectedErrorMutation =
+    requires(T value) { value.expected_error = ErrorCode::INTERNAL_ERROR; };
+
+template <typename T>
+concept SupportsExpectedReplicaCountMutation =
+    requires(T value) { value.expected_replica_count = 1; };
+
+template <typename T>
+concept SupportsExpectedCompleteReplicaCountMutation =
+    requires(T value) { value.expected_complete_replica_count = 1; };
+
+template <typename T>
+concept SupportsThen =
+    requires(MasterScenario& scenario, T value) { scenario.Then(value); };
+
+using ErrorExpectedPutStart =
+    decltype(PutStart("compile-time", 1_KB)
+                 .ExpectError(ErrorCode::INTERNAL_ERROR));
+using SuccessExpectedPutStart =
+    decltype(PutStart("compile-time", 1_KB).ExpectReplicas(1));
+using ErrorExpectedUpsertStart =
+    decltype(UpsertStart("compile-time", 1_KB)
+                 .ExpectError(ErrorCode::INTERNAL_ERROR));
+using SuccessExpectedUpsertStart =
+    decltype(UpsertStart("compile-time", 1_KB).ExpectReplicas(1));
+using UnspecifiedObject = decltype(Object("compile-time"));
+using NotReadyObject = decltype(Object("compile-time").IsNotReady());
+using MissingObject = decltype(Object("compile-time").DoesNotExist());
+using ReadableObject = decltype(Object("compile-time").HasReplicas(1));
+using UnspecifiedObjects = decltype(Objects(0, 1));
+using MissingObjects = decltype(Objects(0, 1).DoNotExist());
+using ReadableObjects = decltype(Objects(0, 1).AreReadable());
+
+static_assert(!SupportsExpectReplicas<ErrorExpectedPutStart>);
+static_assert(!SupportsExpectStatus<ErrorExpectedPutStart>);
+static_assert(!SupportsEventually<ErrorExpectedPutStart>);
+static_assert(!SupportsExpectError<SuccessExpectedPutStart>);
+static_assert(SupportsEventually<SuccessExpectedPutStart>);
+static_assert(!SupportsExpectError<
+              decltype(PutStart("compile-time", 1_KB).Eventually())>);
+static_assert(!SupportsExpectedReplicaCountMutation<ErrorExpectedPutStart>);
+static_assert(!SupportsExpectedErrorMutation<SuccessExpectedPutStart>);
+static_assert(!SupportsExpectReplicas<ErrorExpectedUpsertStart>);
+static_assert(!SupportsExpectStatus<ErrorExpectedUpsertStart>);
+static_assert(!SupportsExpectError<SuccessExpectedUpsertStart>);
+static_assert(!SupportsExpectedReplicaCountMutation<ErrorExpectedUpsertStart>);
+static_assert(!SupportsExpectedErrorMutation<SuccessExpectedUpsertStart>);
+static_assert(!SupportsIsReadable<NotReadyObject>);
+static_assert(!SupportsHasReplicas<NotReadyObject>);
+static_assert(!SupportsIsNotReady<ReadableObject>);
+static_assert(!SupportsDoesNotExist<ReadableObject>);
+static_assert(!SupportsDoesNotExist<NotReadyObject>);
+static_assert(!SupportsIsReadable<MissingObject>);
+static_assert(!SupportsIsNotReady<MissingObject>);
+static_assert(!SupportsHasReplicas<MissingObject>);
+static_assert(!SupportsHasCompleteReplicas<MissingObject>);
+static_assert(!SupportsHasChecksum<MissingObject>);
+static_assert(!SupportsHasNoChecksum<MissingObject>);
+static_assert(!SupportsHasMemoryReplicaSize<MissingObject>);
+static_assert(!SupportsIsOnMemoryNode<MissingObject>);
+static_assert(!SupportsExpectedReplicaCountMutation<MissingObject>);
+static_assert(!SupportsExpectedCompleteReplicaCountMutation<MissingObject>);
+static_assert(!SupportsThen<UnspecifiedObject>);
+static_assert(SupportsThen<NotReadyObject>);
+static_assert(SupportsThen<MissingObject>);
+static_assert(SupportsThen<ReadableObject>);
+static_assert(!SupportsThen<UnspecifiedObjects>);
+static_assert(SupportsThen<MissingObjects>);
+static_assert(SupportsThen<ReadableObjects>);
+
+MasterServiceConfig ContractOffloadConfig() {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.default_kv_lease_ttl = 0;
+    return config;
+}
+
+}  // namespace
+
+TEST(MasterScenarioContractTest, HonorsRequestedPutStartReplicaCount) {
+    MasterScenario("requested put start replica count")
+        .Given(MemoryNode("memory-1"))
+        .Given(MemoryNode("memory-2"))
+        .When(PutStart("key", 1_KB).Replicas(2).ExpectReplicas(2));
+}
+
+TEST(MasterScenarioContractTest, HonorsRequestedUpsertStartReplicaCount) {
+    MasterScenario("requested upsert start replica count")
+        .Given(MemoryNode("memory-1"))
+        .Given(MemoryNode("memory-2"))
+        .When(UpsertStart("key", 1_KB).Replicas(2).ExpectReplicas(2));
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedActionError) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("unexpected action error")
+                                .Given(MemoryNode("memory"))
+                                .When(PutEnd("missing")),
+                            "PutEnd(missing) failed: OBJECT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedActionSuccess) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("unexpected action success")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB)
+                      .ExpectError(ErrorCode::OBJECT_ALREADY_EXISTS)),
+        "PutStart(key) succeeded; expected OBJECT_ALREADY_EXISTS");
+}
+
+TEST(MasterScenarioContractTest, ReportsWrongErrorCode) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("wrong error code")
+            .Given(MemoryNode("memory"))
+            .When(PutEnd("missing").ExpectError(ErrorCode::ILLEGAL_CLIENT)),
+        "PutEnd(missing) failed with OBJECT_NOT_FOUND; expected "
+        "ILLEGAL_CLIENT");
+}
+
+TEST(MasterScenarioContractTest, ReportsPutStartReplicaCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("put start replica count mismatch")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB).ExpectReplicas(2)),
+                            "PutStart(key) returned 1 replicas; expected 2");
+}
+
+TEST(MasterScenarioContractTest, ReportsPutStartReplicaStatusMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("put start replica status mismatch")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB).ExpectStatus(ReplicaStatus::COMPLETE)),
+        "PutStart(key) replica status mismatch");
+}
+
+TEST(MasterScenarioContractTest, PutStartEventuallyHasBoundedTimeout) {
+    MasterScenario scenario("bounded put start eventual timeout");
+    scenario.Given(MemoryNode("memory").Capacity(1_KB));
+
+    const auto started = std::chrono::steady_clock::now();
+    EXPECT_NONFATAL_FAILURE(
+        scenario.When(PutStart("key", 2_KB)
+                          .ExpectReplicas(1)
+                          .Eventually(std::chrono::milliseconds(10))),
+        "PutStart(key) failed: NO_AVAILABLE_HANDLE");
+    EXPECT_LT(std::chrono::steady_clock::now() - started,
+              std::chrono::seconds(1));
+}
+
+TEST(MasterScenarioContractTest, PutStartEventuallyStopsOnPermanentError) {
+    MasterScenario scenario("put start eventual permanent error");
+    scenario.Given(MemoryNode("memory")).When(PutStart("key", 1_KB));
+
+    const auto started = std::chrono::steady_clock::now();
+    EXPECT_NONFATAL_FAILURE(scenario.When(PutStart("key", 1_KB).Eventually()),
+                            "PutStart(key) failed: OBJECT_ALREADY_EXISTS");
+    EXPECT_LT(std::chrono::steady_clock::now() - started,
+              std::chrono::seconds(1));
+}
+
+TEST(MasterScenarioContractTest, ReportsUpsertStartReplicaCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("upsert start replica count mismatch")
+            .Given(MemoryNode("memory"))
+            .When(UpsertStart("key", 1_KB).ExpectReplicas(2)),
+        "UpsertStart(key) returned 1 replicas; expected 2");
+}
+
+TEST(MasterScenarioContractTest, ReportsUpsertStartReplicaStatusMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("upsert start replica status mismatch")
+            .Given(MemoryNode("memory"))
+            .When(
+                UpsertStart("key", 1_KB).ExpectStatus(ReplicaStatus::COMPLETE)),
+        "UpsertStart(key) replica status mismatch");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedUpsertStartError) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("unexpected upsert start error")
+                                .Given(MemoryNode("memory").Capacity(1_KB))
+                                .When(UpsertStart("key", 2_KB)),
+                            "UpsertStart(key) failed: NO_AVAILABLE_HANDLE");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedUpsertStartSuccess) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("unexpected upsert start success")
+            .Given(MemoryNode("memory"))
+            .When(UpsertStart("key", 1_KB)
+                      .ExpectError(ErrorCode::OBJECT_ALREADY_EXISTS)),
+        "UpsertStart(key) succeeded; expected OBJECT_ALREADY_EXISTS");
+}
+
+TEST(MasterScenarioContractTest, ReportsWrongUpsertEndErrorCode) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("wrong upsert end error code")
+            .Given(MemoryNode("memory"))
+            .When(UpsertEnd("missing").ExpectError(ErrorCode::ILLEGAL_CLIENT)),
+        "UpsertEnd(missing) failed with OBJECT_NOT_FOUND; expected "
+        "ILLEGAL_CLIENT");
+}
+
+TEST(MasterScenarioContractTest, ReportsWrongUpsertRevokeErrorCode) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("wrong upsert revoke error code")
+            .Given(MemoryNode("memory"))
+            .When(
+                UpsertRevoke("missing").ExpectError(ErrorCode::ILLEGAL_CLIENT)),
+        "UpsertRevoke(missing) failed with OBJECT_NOT_FOUND; expected "
+        "ILLEGAL_CLIENT");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnreadableObject) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("unreadable object")
+            .Given(MemoryNode("memory"))
+            .Then(Object("missing").IsReadable()),
+        "Object(missing) is not readable: OBJECT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, ReportsExistingObjectWhenAbsenceExpected) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("existing object expected absent")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key"))
+                                .Then(Object("key").DoesNotExist()),
+                            "Object(key) exists; expected it not to exist");
+}
+
+TEST(MasterScenarioContractTest, ReportsNotReadyObjectWhenAbsenceExpected) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("not-ready object expected absent")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB))
+            .Then(Object("key").DoesNotExist()),
+        "Object(key) lookup failed with REPLICA_IS_NOT_READY; expected "
+        "OBJECT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, ReportsReadableObjectCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("readable object count mismatch")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key"))
+                                .Then(ReadableCount(Objects({"key"}), 0)),
+                            "ReadableCount is 1; expected 0");
+}
+
+TEST(MasterScenarioContractTest, ReportsNotReadyObjectInReadableCount) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("not-ready object in readable count")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB))
+            .Then(ReadableCount(Objects({"key"}), 0)),
+        "ReadableCount lookup for key failed: REPLICA_IS_NOT_READY");
+}
+
+TEST(MasterScenarioContractTest, ReportsObjectReplicaCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("object replica count mismatch")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key"))
+                                .Then(Object("key").HasReplicas(2)),
+                            "Object(key) has 1 replicas; expected 2");
+}
+
+TEST(MasterScenarioContractTest, ReportsCompleteReplicaCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("complete replica count mismatch")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key"))
+                                .Then(Object("key").HasCompleteReplicas(0)),
+                            "Object(key) has 1 complete replicas; expected 0");
+}
+
+TEST(MasterScenarioContractTest, ReportsObjectChecksumMismatch) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("object checksum mismatch")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key").WithChecksum(7))
+                                .Then(Object("key").HasChecksum(8)),
+                            "Object(key) has checksum 7; expected 8");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedObjectChecksum) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("unexpected object checksum")
+                                .Given(MemoryNode("memory"))
+                                .When(PutStart("key", 1_KB))
+                                .When(PutEnd("key").WithChecksum(7))
+                                .Then(Object("key").HasNoChecksum()),
+                            "Object(key) has checksum 7; expected none");
+}
+
+TEST(MasterScenarioContractTest, ReportsMemoryReplicaSizeMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("memory replica size mismatch")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB))
+            .When(PutEnd("key"))
+            .Then(Object("key").HasMemoryReplicaSize(2_KB)),
+        "Object(key) has memory replica size 1024; expected 2048");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedMemoryNode) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("unexpected memory node")
+            .Given(MemoryNode("memory"))
+            .When(PutStart("key", 1_KB))
+            .When(PutEnd("key"))
+            .Then(Object("key").IsOnMemoryNode("other")),
+        "Object(key) has a memory replica on memory; expected other");
+}
+
+TEST(MasterScenarioContractTest, ReportsRemoveAllCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("remove all count mismatch")
+            .Given(MemoryNode("memory"))
+            .Given(Objects({"key"}).Size(1_KB).CompleteOn("memory").ExpiredFrom(
+                std::chrono::system_clock::now() - std::chrono::hours(1)))
+            .When(RemoveAll().ExpectRemoved(2)),
+        "RemoveAll removed 1 objects; expected 2");
+}
+
+TEST(MasterScenarioContractTest, CreatesAndChecksObjectCollections) {
+    MasterScenario("object collections")
+        .Given(MemoryNode("memory"))
+        .Given(Objects(2, 5)
+                   .NamedBy([](size_t index) {
+                       return "collection-" + std::to_string(index);
+                   })
+                   .Size(1_KB)
+                   .CompleteOn("memory"))
+        .Then(Objects(2, 5)
+                  .NamedBy([](size_t index) {
+                      return "collection-" + std::to_string(index);
+                  })
+                  .AreReadable());
+}
+
+TEST(MasterScenarioContractTest, CollectionFailureIdentifiesObjectKey) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("collection failure")
+            .Given(MemoryNode("memory"))
+            .Given(Objects({"present"}).Size(1_KB).CompleteOn("memory"))
+            .Then(Objects({"present", "missing"}).AreReadable()),
+        "Object(missing) is not readable: OBJECT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedMountLocalDiskError) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("mount local disk without offload mode")
+            .Given(MemoryNode("memory"))
+            .When(MountLocalDisk("memory")),
+        "MountLocalDisk(memory) failed: UNABLE_OFFLOAD");
+}
+
+TEST(MasterScenarioContractTest, ReportsWrongUnmountLocalDiskErrorCode) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("wrong unmount local disk error code")
+            .Given(MemoryNode("memory"))
+            .When(UnmountLocalDisk("memory").ExpectError(
+                ErrorCode::ILLEGAL_CLIENT)),
+        "UnmountLocalDisk(memory) failed with UNABLE_OFFLOAD; expected "
+        "ILLEGAL_CLIENT");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedReportSsdCapacityError) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("ssd capacity report without a mounted local disk",
+                       ContractOffloadConfig())
+            .Given(MemoryNode("memory"))
+            .When(ReportSsdCapacity("memory", 1000)),
+        "ReportSsdCapacity(memory) failed: SEGMENT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, ReportsOffloadHeartbeatTaskCountMismatch) {
+    MasterScenario scenario("offload heartbeat task count mismatch",
+                            ContractOffloadConfig());
+    scenario.Given(MemoryNode("memory"))
+        .When(MountLocalDisk("memory"))
+        .Given(
+            Objects({"queued"}).Size(1_KB).By("memory").CompleteOn("memory"));
+    EXPECT_NONFATAL_FAILURE(
+        scenario.When(OffloadHeartbeat("memory").ExpectNoTasks()),
+        "OffloadHeartbeat(memory) returned 1 offload tasks; expected 0");
+}
+
+TEST(MasterScenarioContractTest, ReportsMissingOffloadTask) {
+    MasterScenario scenario("offload heartbeat missing task",
+                            ContractOffloadConfig());
+    scenario.Given(MemoryNode("memory"))
+        .When(MountLocalDisk("memory"))
+        .Given(
+            Objects({"queued"}).Size(1_KB).By("memory").CompleteOn("memory"));
+    EXPECT_NONFATAL_FAILURE(
+        scenario.When(OffloadHeartbeat("memory").ExpectTasks({"other"}, 1024)),
+        "OffloadHeartbeat(memory) is missing an offload task for other");
+}
+
+TEST(MasterScenarioContractTest, ReportsCompleteOffloadWithoutRecordedSize) {
+    MasterScenario scenario("complete offload without a recorded size",
+                            ContractOffloadConfig());
+    scenario.Given(MemoryNode("memory")).When(MountLocalDisk("memory"));
+    EXPECT_NONFATAL_FAILURE(
+        scenario.When(
+            CompleteOffload({"unknown"}).By("memory").OnNode("memory")),
+        "CompleteOffload(unknown) has no PutStart-recorded size; use OfSize");
+}
+
+TEST(MasterScenarioContractTest, ReportsUnexpectedEvictDiskReplicaError) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("evict disk replica of a missing key",
+                       ContractOffloadConfig())
+            .Given(MemoryNode("memory"))
+            .When(EvictDiskReplica("missing")),
+        "EvictDiskReplica(missing) failed: OBJECT_NOT_FOUND");
+}
+
+TEST(MasterScenarioContractTest, CompletesOffloadUsingRecordedPutStartSize) {
+    MasterScenario("complete offload sized from the recorded PutStart",
+                   ContractOffloadConfig())
+        .Given(MemoryNode("memory"))
+        .When(MountLocalDisk("memory"))
+        .When(PutStart("recorded", 2_KB).By("memory"))
+        .When(PutEnd("recorded").By("memory"))
+        .When(CompleteOffload({"recorded"}).By("memory").OnNode("memory"))
+        .Then(Object("recorded")
+                  .HasReplicas(2)
+                  .HasMemoryReplicas(1)
+                  .HasLocalDiskReplicas(1));
+}
+
+TEST(MasterScenarioContractTest, ReportsRacePutStartAdmissionMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("race put start admission mismatch")
+            .Given(MemoryNode("memory"))
+            .When(RacePutStart("key", 1_KB).Threads(2).ExpectSuccesses(2)),
+        "RacePutStart(key) admitted 1 writers; expected 2");
+}
+
+TEST(MasterScenarioContractTest, ReportsRaceMountUnmountWithoutNodes) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("race mount unmount without nodes")
+                                .Given(MemoryNode("memory"))
+                                .When(RaceMountUnmount("race").Nodes(0)),
+                            "RaceMountUnmount requires nodes and iterations");
+}
+
+TEST(MasterScenarioContractTest, ReportsRaceMountLocalDiskFailure) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("race local disk mounts without offload mode")
+            .Given(MemoryNode("memory"))
+            .When(RaceMountLocalDisk("client").Clients(1)),
+        "RaceMountLocalDisk(client) mount failed: UNABLE_OFFLOAD");
+}
+
+TEST(MasterScenarioContractTest, ReportsRaceWritesWithoutWriters) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("race writes without writers")
+            .Given(MemoryNode("memory"))
+            .When(RaceWritesWithRemoveAll("race").Writers(0)),
+        "RaceWritesWithRemoveAll requires writers and objects");
+}
+
+TEST(MasterScenarioContractTest, ReportsRaceReadsWithoutKeys) {
+    EXPECT_NONFATAL_FAILURE(MasterScenario("race reads without keys")
+                                .Given(MemoryNode("memory"))
+                                .When(RaceReadsWithRemoveAll({})),
+                            "RaceReadsWithRemoveAll requires at least one key");
+}
+
+TEST(MasterScenarioContractTest, ReportsRaceRemoveAllCountMismatch) {
+    EXPECT_NONFATAL_FAILURE(
+        MasterScenario("race remove all count mismatch")
+            .Given(MemoryNode("memory"))
+            .Given(Objects({"key"}).Size(1_KB).CompleteOn("memory").ExpiredFrom(
+                std::chrono::system_clock::now() - std::chrono::hours(1)))
+            .When(RaceRemoveAll().ExpectTotalRemoved(2)),
+        "RaceRemoveAll removed 1 objects; expected 2");
+}
+
+TEST(MasterScenarioContractTest, ReportsMissingOffloadTasksWhenSomeExpected) {
+    MasterScenario scenario("offload heartbeat expected some tasks",
+                            ContractOffloadConfig());
+    scenario.Given(MemoryNode("memory")).When(MountLocalDisk("memory"));
+    EXPECT_NONFATAL_FAILURE(
+        scenario.When(OffloadHeartbeat("memory").ExpectSomeTasks()),
+        "OffloadHeartbeat(memory) returned no offload tasks; expected at "
+        "least one");
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service/master_service_test_peer.cpp b/mooncake-store/tests/master_service/master_service_test_peer.cpp
new file mode 100644
index 0000000000..fb5b5a9599
--- /dev/null
+++ b/mooncake-store/tests/master_service/master_service_test_peer.cpp
@@ -0,0 +1,162 @@
+#include "master_service/master_service_test_peer.h"
+
+#include <algorithm>
+#include <cassert>
+
+#include "ha/snapshot/catalog/snapshot_catalog_store.h"
+#ifdef USE_NOF
+#include "spdk/spdk_wrapper.h"
+#endif
+
+namespace mooncake::test {
+
+ErrorCode MasterServiceTestPeer::SetBatchOpLogBackendForTesting(
+    std::shared_ptr<HaKvBackend> backend) {
+    // Explicit test injection keeps the zero-view fixture API. A configured
+    // view still exercises the production fenced path.
+    return service_.InitializeBatchOpLogWriter(std::move(backend),
+                                               service_.view_version_ > 0);
+}
+
+void MasterServiceTestPeer::SetBatchOpLogWriterFactoryForTesting(
+    MasterService::BatchOpLogWriterFactory factory) {
+    assert(factory);
+    assert(!service_.ordered_oplog_writer_);
+    service_.batch_oplog_writer_factory_ = std::move(factory);
+}
+
+void MasterServiceTestPeer::RunBatchEvictForTesting(
+    double evict_ratio_target, double evict_ratio_lowerbound) {
+    service_.BatchEvict(evict_ratio_target, evict_ratio_lowerbound);
+}
+
+void MasterServiceTestPeer::RunNoFBatchEvictForTesting(
+    double evict_ratio_target, double evict_ratio_lowerbound) {
+    service_.NoFBatchEvict(evict_ratio_target, evict_ratio_lowerbound);
+}
+
+void MasterServiceTestPeer::RunDfsEvictionForTesting() {
+    service_.RunDfsEviction();
+}
+
+void MasterServiceTestPeer::RunTenantEvictForTesting() {
+    service_.EvictTenantsOverWatermark();
+}
+
+void MasterServiceTestPeer::SetKvTenantEpochTrackingForTesting(bool enabled) {
+    service_.kv_track_tenant_epochs_ = enabled;
+}
+
+void MasterServiceTestPeer::SetRemoveAllShardHookForTesting(
+    std::function<void(size_t)> hook) {
+    service_.kv_remove_all_shard_hook_ = std::move(hook);
+}
+
+uint64_t MasterServiceTestPeer::GetKvClearedPublishedForTesting() const {
+    return service_.kv_cleared_published_.load(std::memory_order_relaxed);
+}
+
+uint64_t MasterServiceTestPeer::GetKvClearedSuppressedForTesting() const {
+    return service_.kv_cleared_suppressed_by_epoch_.load(
+        std::memory_order_relaxed);
+}
+
+void MasterServiceTestPeer::SetNoFProbeFnForTesting(
+    MasterService::NoFProbeFn fn) {
+#ifdef USE_NOF
+    std::lock_guard<std::mutex> lock(service_.nof_probe_fn_mutex_);
+    if (fn) {
+        service_.nof_probe_fn_ = std::move(fn);
+        return;
+    }
+    service_.nof_probe_fn_ = [](const std::string& te_endpoint,
+                                uint32_t timeout_ms,
+                                std::string* error_reason) {
+        return SpdkWrapper::GetInstance().ProbeNofSegment(
+            te_endpoint, timeout_ms, error_reason);
+    };
+#else
+    (void)fn;
+#endif
+}
+
+size_t MasterServiceTestPeer::GetMountedNoFSegmentCountForTesting() {
+    std::vector<MountedNoFSegmentSnapshot> mounted_segments;
+    service_.nof_segment_manager_.GetMountedSegmentsSnapshot(mounted_segments);
+    return mounted_segments.size();
+}
+
+bool MasterServiceTestPeer::IsNoFSegmentMountedForTesting(
+    const UUID& segment_id) {
+    std::vector<MountedNoFSegmentSnapshot> mounted_segments;
+    service_.nof_segment_manager_.GetMountedSegmentsSnapshot(mounted_segments);
+    return std::any_of(
+        mounted_segments.begin(), mounted_segments.end(),
+        [&segment_id](const MountedNoFSegmentSnapshot& snapshot) {
+            return snapshot.segment_id == segment_id &&
+                   snapshot.status == SegmentStatus::OK;
+        });
+}
+
+std::optional<uint32_t>
+MasterServiceTestPeer::GetNoFHeartbeatFailureCountForTesting(
+    const UUID& segment_id) {
+    std::lock_guard<std::mutex> lock(service_.nof_heartbeat_mutex_);
+    auto it = service_.nof_heartbeat_states_.find(segment_id);
+    if (it == service_.nof_heartbeat_states_.end()) {
+        return std::nullopt;
+    }
+    return it->second.consecutive_failures;
+}
+
+size_t MasterServiceTestPeer::RunPromotionCandidateRetryForTesting() {
+    return service_.RunPromotionCandidateRetry(MasterService::kNumShards);
+}
+
+size_t MasterServiceTestPeer::CountCandidatesForTesting(
+    const TenantId& tenant_id) {
+    size_t count = 0;
+    std::shared_lock<std::shared_mutex> lock(service_.snapshot_mutex_);
+    for (size_t i = 0; i < MasterService::kNumShards; i++) {
+        MetadataShardAccessorRO shard(&service_, i);
+        auto it = shard->tenants.find(tenant_id);
+        if (it != shard->tenants.end()) {
+            count += it->second.promotion_candidates.size();
+        }
+    }
+    return count;
+}
+
+void MasterServiceTestPeer::ResetCandidateBackoffsForTesting() {
+    const auto epoch = std::chrono::steady_clock::time_point{};
+    for (size_t i = 0; i < MasterService::kNumShards; i++) {
+        MetadataShardAccessorRW shard(&service_, i);
+        for (auto& [tenant_id, tenant_state] : shard->tenants) {
+            (void)tenant_id;
+            for (auto& [key, candidate] : tenant_state.promotion_candidates) {
+                (void)key;
+                candidate.retry_after = epoch;
+            }
+        }
+    }
+}
+
+size_t MasterServiceTestPeer::SoftPinHeapSize() const {
+    const auto& index = service_.soft_pin_deadline_index_;
+    std::lock_guard lock(index.mutex_);
+    return index.heap_.size();
+}
+
+size_t MasterServiceTestPeer::SoftPinRegistrationCount() const {
+    const auto& index = service_.soft_pin_deadline_index_;
+    std::lock_guard lock(index.mutex_);
+    return index.registrations_.size();
+}
+
+std::unique_ptr<ha::SnapshotCatalogStore>
+MasterServiceTestPeer::CreateSnapshotCatalogStore(
+    const MasterServiceConfig& config) {
+    return service_.CreateSnapshotCatalogStore(config);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service/master_service_test_peer.h b/mooncake-store/tests/master_service/master_service_test_peer.h
new file mode 100644
index 0000000000..e058b32d87
--- /dev/null
+++ b/mooncake-store/tests/master_service/master_service_test_peer.h
@@ -0,0 +1,513 @@
+#pragma once
+
+#include <utility>
+
+#include "master_service.h"
+
+namespace mooncake::test {
+
+// The single test access boundary for MasterService. Keep test-only inspection,
+// mutation and synchronous drivers here, not in the production service API.
+// Raw state accessors do not acquire locks. Callers must preserve the service's
+// lock order; synchronous drivers must not race their background workers.
+class MasterServiceTestPeer {
+   public:
+    explicit MasterServiceTestPeer(MasterService& service)
+        : service_(service) {}
+
+    using GroupDomainAccessorRO = MasterService::GroupDomainAccessorRO;
+    using GroupDomainAccessorRW = MasterService::GroupDomainAccessorRW;
+    using MetadataAccessorRO = MasterService::MetadataAccessorRO;
+    using MetadataAccessorRW = MasterService::MetadataAccessorRW;
+    using MetadataSerializer = MasterService::MetadataSerializer;
+    using MetadataShard = MasterService::MetadataShard;
+    using MetadataShardAccessorRO = MasterService::MetadataShardAccessorRO;
+    using MetadataShardAccessorRW = MasterService::MetadataShardAccessorRW;
+    using ObjectIdentity = MasterService::ObjectIdentity;
+    using ObjectMetadata = mooncake::ObjectMetadata;
+    using PromotionQueueResult = mooncake::PromotionQueueResult;
+    using PromotionTask = mooncake::PromotionTask;
+    using QuotaEraseMode = MasterService::QuotaEraseMode;
+    using TenantQuotaEvictionResult = MasterService::TenantQuotaEvictionResult;
+    using TenantState = MasterService::TenantState;
+
+    static constexpr auto kDynamicReplicationWindowEntryLimit =
+        MasterService::kDynamicReplicationWindowEntryLimit;
+    static constexpr auto kMaxPromotionExecutionFailures =
+        MasterService::kMaxPromotionExecutionFailures;
+    static constexpr auto kNumShards = MasterService::kNumShards;
+    static constexpr auto kObjectOperationLockStripes =
+        MasterService::kObjectOperationLockStripes;
+    static constexpr auto kPromotionCandidateMaxRetries =
+        MasterService::kPromotionCandidateMaxRetries;
+
+    ErrorCode SetBatchOpLogBackendForTesting(
+        std::shared_ptr<HaKvBackend> backend);
+
+    void SetBatchOpLogWriterFactoryForTesting(
+        MasterService::BatchOpLogWriterFactory factory);
+
+    // Drive one eviction cycle synchronously, without the periodic worker.
+    void RunBatchEvictForTesting(double evict_ratio_target,
+                                 double evict_ratio_lowerbound);
+
+    void RunNoFBatchEvictForTesting(double evict_ratio_target,
+                                    double evict_ratio_lowerbound);
+
+    void RunDfsEvictionForTesting();
+
+    // Drive one tenant watermark eviction pass without the periodic worker.
+    void RunTenantEvictForTesting();
+
+    // Enable epoch bookkeeping without starting a live KV event publisher.
+    void SetKvTenantEpochTrackingForTesting(bool enabled);
+
+    // Called after each shard lock is released during RemoveAll. Tests can
+    // commit into an already-scanned shard to pin the interleaving.
+    void SetRemoveAllShardHookForTesting(std::function<void(size_t)> hook);
+
+    // Counts of published clears and clears suppressed by a concurrent commit.
+    uint64_t GetKvClearedPublishedForTesting() const;
+
+    uint64_t GetKvClearedSuppressedForTesting() const;
+
+    void SetNoFProbeFnForTesting(MasterService::NoFProbeFn fn);
+
+    size_t GetMountedNoFSegmentCountForTesting();
+
+    bool IsNoFSegmentMountedForTesting(const UUID& segment_id);
+
+    std::optional<uint32_t> GetNoFHeartbeatFailureCountForTesting(
+        const UUID& segment_id);
+
+    size_t RunPromotionCandidateRetryForTesting();
+
+    size_t CountCandidatesForTesting(const TenantId& tenant_id);
+
+    void ResetCandidateBackoffsForTesting();
+
+    size_t SoftPinHeapSize() const;
+
+    size_t SoftPinRegistrationCount() const;
+
+    static auto& AllocationStrategy(MasterService& service) {
+        return service.allocation_strategy_;
+    }
+    static const auto& AllocationStrategy(const MasterService& service) {
+        return service.allocation_strategy_;
+    }
+
+    static auto& BatchOplogStorage(MasterService& service) {
+        return service.batch_oplog_storage_;
+    }
+    static const auto& BatchOplogStorage(const MasterService& service) {
+        return service.batch_oplog_storage_;
+    }
+
+    static auto& ClientLivenessRecords(MasterService& service) {
+        return service.client_liveness_records_;
+    }
+    static const auto& ClientLivenessRecords(const MasterService& service) {
+        return service.client_liveness_records_;
+    }
+
+    static auto& ClientMutex(MasterService& service) {
+        return service.client_mutex_;
+    }
+    static const auto& ClientMutex(const MasterService& service) {
+        return service.client_mutex_;
+    }
+
+    static auto& DynamicReplicationWindows(MasterService& service) {
+        return service.dynamic_replication_windows_;
+    }
+    static const auto& DynamicReplicationWindows(const MasterService& service) {
+        return service.dynamic_replication_windows_;
+    }
+
+    static auto& EnableDfs(MasterService& service) {
+        return service.enable_dfs_;
+    }
+    static const auto& EnableDfs(const MasterService& service) {
+        return service.enable_dfs_;
+    }
+
+    static auto& EnableOplog(MasterService& service) {
+        return service.enable_oplog_;
+    }
+    static const auto& EnableOplog(const MasterService& service) {
+        return service.enable_oplog_;
+    }
+
+    static auto& EvictionRunning(MasterService& service) {
+        return service.eviction_running_;
+    }
+    static const auto& EvictionRunning(const MasterService& service) {
+        return service.eviction_running_;
+    }
+
+    static auto& EvictionThread(MasterService& service) {
+        return service.eviction_thread_;
+    }
+    static const auto& EvictionThread(const MasterService& service) {
+        return service.eviction_thread_;
+    }
+
+    static auto& LocalSsdManager(MasterService& service) {
+        return service.local_ssd_manager_;
+    }
+    static const auto& LocalSsdManager(const MasterService& service) {
+        return service.local_ssd_manager_;
+    }
+
+    static auto& MetadataShards(MasterService& service) {
+        return service.metadata_shards_;
+    }
+    static const auto& MetadataShards(const MasterService& service) {
+        return service.metadata_shards_;
+    }
+
+    static auto& NeedMemEviction(MasterService& service) {
+        return service.need_mem_eviction_;
+    }
+    static const auto& NeedMemEviction(const MasterService& service) {
+        return service.need_mem_eviction_;
+    }
+
+    static auto& NofSegmentManager(MasterService& service) {
+        return service.nof_segment_manager_;
+    }
+    static const auto& NofSegmentManager(const MasterService& service) {
+        return service.nof_segment_manager_;
+    }
+
+    static auto& ObjectOperationLocks(MasterService& service) {
+        return service.object_operation_locks_;
+    }
+    static const auto& ObjectOperationLocks(const MasterService& service) {
+        return service.object_operation_locks_;
+    }
+
+    static auto& OrderedOplogWriter(MasterService& service) {
+        return service.ordered_oplog_writer_;
+    }
+    static const auto& OrderedOplogWriter(const MasterService& service) {
+        return service.ordered_oplog_writer_;
+    }
+
+    static auto& PromotionAdmissionThreshold(MasterService& service) {
+        return service.promotion_admission_threshold_;
+    }
+    static const auto& PromotionAdmissionThreshold(
+        const MasterService& service) {
+        return service.promotion_admission_threshold_;
+    }
+
+    static auto& PromotionCandidateCount(MasterService& service) {
+        return service.promotion_candidate_count_;
+    }
+    static const auto& PromotionCandidateCount(const MasterService& service) {
+        return service.promotion_candidate_count_;
+    }
+
+    static auto& PromotionInFlight(MasterService& service) {
+        return service.promotion_in_flight_;
+    }
+    static const auto& PromotionInFlight(const MasterService& service) {
+        return service.promotion_in_flight_;
+    }
+
+    static auto& ReplicaCleanupWorker(MasterService& service) {
+        return service.replica_cleanup_worker_;
+    }
+    static const auto& ReplicaCleanupWorker(const MasterService& service) {
+        return service.replica_cleanup_worker_;
+    }
+
+    static auto& RootFsDir(MasterService& service) {
+        return service.root_fs_dir_;
+    }
+    static const auto& RootFsDir(const MasterService& service) {
+        return service.root_fs_dir_;
+    }
+
+    static auto& SegmentManager(MasterService& service) {
+        return service.segment_manager_;
+    }
+    static const auto& SegmentManager(const MasterService& service) {
+        return service.segment_manager_;
+    }
+
+    static auto& SnapshotCatalogStore(MasterService& service) {
+        return service.snapshot_catalog_store_;
+    }
+    static const auto& SnapshotCatalogStore(const MasterService& service) {
+        return service.snapshot_catalog_store_;
+    }
+
+    static auto& SnapshotManager(MasterService& service) {
+        return service.snapshot_manager_;
+    }
+    static const auto& SnapshotManager(const MasterService& service) {
+        return service.snapshot_manager_;
+    }
+
+    static auto& SnapshotMutex(MasterService& service) {
+        return service.snapshot_mutex_;
+    }
+    static const auto& SnapshotMutex(const MasterService& service) {
+        return service.snapshot_mutex_;
+    }
+
+    static auto& SnapshotObjectStore(MasterService& service) {
+        return service.snapshot_object_store_;
+    }
+    static const auto& SnapshotObjectStore(const MasterService& service) {
+        return service.snapshot_object_store_;
+    }
+
+    static auto& SoftPinDeadlineIndex(MasterService& service) {
+        return service.soft_pin_deadline_index_;
+    }
+    static const auto& SoftPinDeadlineIndex(const MasterService& service) {
+        return service.soft_pin_deadline_index_;
+    }
+
+    static auto& TaskManager(MasterService& service) {
+        return service.task_manager_;
+    }
+    static const auto& TaskManager(const MasterService& service) {
+        return service.task_manager_;
+    }
+
+    static auto& TenantQuotaPolicyMutex(MasterService& service) {
+        return service.tenant_quota_policy_mutex_;
+    }
+    static const auto& TenantQuotaPolicyMutex(const MasterService& service) {
+        return service.tenant_quota_policy_mutex_;
+    }
+
+    static auto& TenantQuotaPolicyStore(MasterService& service) {
+        return service.tenant_quota_policy_store_;
+    }
+    static const auto& TenantQuotaPolicyStore(const MasterService& service) {
+        return service.tenant_quota_policy_store_;
+    }
+
+    static auto& TenantQuotaRecomputeMutex(MasterService& service) {
+        return service.tenant_quota_recompute_mutex_;
+    }
+    static const auto& TenantQuotaRecomputeMutex(const MasterService& service) {
+        return service.tenant_quota_recompute_mutex_;
+    }
+
+    static auto& TenantQuotaTable(MasterService& service) {
+        return service.tenant_quota_table_;
+    }
+    static const auto& TenantQuotaTable(const MasterService& service) {
+        return service.tenant_quota_table_;
+    }
+
+    auto AddReplicaForRetainedClient(const UUID& client_id,
+                                     const std::string& key,
+                                     const TenantId& tenant_id,
+                                     Replica& replica)
+        -> tl::expected<bool, ErrorCode> {
+        return service_.AddReplicaForRetainedClient(client_id, key, tenant_id,
+                                                    replica);
+    }
+
+    tl::expected<uint64_t, ErrorCode> AppendOpLogVisibleBeforeDurable(
+        OpType type, const std::string& tenant_id, const std::string& key,
+        const std::string& payload) {
+        return service_.AppendOpLogVisibleBeforeDurable(type, tenant_id, key,
+                                                        payload);
+    }
+
+    tl::expected<OpLogEntry, ErrorCode> AppendOpLogWithDurableFinalize(
+        OpType type, const std::string& tenant_id, const std::string& key,
+        const std::string& payload,
+        MasterService::DurableFinalizeCallback callback) {
+        return service_.AppendOpLogWithDurableFinalize(
+            type, tenant_id, key, payload, std::move(callback));
+    }
+
+    tl::expected<void, ErrorCode> ChargeTenantQuota(TenantQuotaHandle account,
+                                                    uint64_t bytes) {
+        return service_.ChargeTenantQuota(std::move(account), bytes);
+    }
+
+    void CleanupExpiredSoftPins(
+        const std::chrono::system_clock::time_point& now) {
+        service_.CleanupExpiredSoftPins(now);
+    }
+
+    void ClearCandidatesForReload() { service_.ClearCandidatesForReload(); }
+
+    void ClearDynamicReplicationStateForKey(TenantState& tenant_state,
+                                            const std::string& key) {
+        service_.ClearDynamicReplicationStateForKey(tenant_state, key);
+    }
+
+    void ClearLocalDiskHandlesOwnedBy(const UUID& owner) {
+        service_.ClearLocalDiskHandlesOwnedBy(owner);
+    }
+
+    void ClearInvalidHandles() { service_.ClearInvalidHandles(); }
+
+    void ClearInvalidHandles(
+        const std::unordered_set<UUID, boost::hash<UUID>>& retaining_clients) {
+        service_.ClearInvalidHandles(retaining_clients);
+    }
+
+    std::unique_ptr<ha::SnapshotCatalogStore> CreateSnapshotCatalogStore(
+        const MasterServiceConfig& config);
+
+    void DiscardExpiredProcessingReplicas(
+        MetadataShardAccessorRW& shard,
+        const std::chrono::system_clock::time_point& now) {
+        service_.DiscardExpiredProcessingReplicas(shard, now);
+    }
+
+    uint32_t DynamicReplicationAdmissionMinHits() const {
+        return service_.DynamicReplicationAdmissionMinHits();
+    }
+
+    static int64_t DynamicReplicationNowMs() {
+        return MasterService::DynamicReplicationNowMs();
+    }
+
+    uint64_t DynamicReplicationVersionEpoch(
+        const ObjectMetadata& metadata) const {
+        return service_.DynamicReplicationVersionEpoch(metadata);
+    }
+
+    size_t EraseReplicasWithCacheTotalAccounting(
+        ObjectMetadata& metadata,
+        const std::function<bool(const Replica&)>& pred_fn,
+        std::vector<ReplicaID>* erased_replica_ids = nullptr) {
+        return service_.EraseReplicasWithCacheTotalAccounting(
+            metadata, pred_fn, erased_replica_ids);
+    }
+
+    TenantQuotaEvictionResult EvictTenantMemoryForQuota(
+        const TenantId& tenant_id, uint64_t target_bytes) {
+        return service_.EvictTenantMemoryForQuota(tenant_id, target_bytes);
+    }
+
+    void FinalizeExpiredProcessingReplicasAfterDurable(
+        const OpLogEntry& durable_entry,
+        const std::chrono::system_clock::time_point& ttl) {
+        service_.FinalizeExpiredProcessingReplicasAfterDurable(durable_entry,
+                                                               ttl);
+    }
+
+    void FinalizeRemovedReplicasAfterDurable(
+        const OpLogEntry& durable_entry,
+        const std::vector<ReplicaID>& replica_ids, QuotaEraseMode quota_mode,
+        const std::vector<std::string>& previous_media_hint = {}) {
+        service_.FinalizeRemovedReplicasAfterDurable(
+            durable_entry, replica_ids, quota_mode, previous_media_hint);
+    }
+
+    std::shared_ptr<ClientLivenessRecord> FindClientRecord(
+        const UUID& client_id) const {
+        return service_.FindClientRecord(client_id);
+    }
+
+    TenantQuotaHandle GetBoundTenantQuotaHandle(
+        const TenantState& tenant_state) const {
+        return service_.GetBoundTenantQuotaHandle(tenant_state);
+    }
+
+    TenantState& GetOrCreateTenantState(MetadataShard& shard,
+                                        const TenantId& tenant_id) {
+        return service_.GetOrCreateTenantState(shard, tenant_id);
+    }
+
+    bool IsReplicaReadable(const Replica& replica) const {
+        return service_.IsReplicaReadable(replica);
+    }
+
+    static std::vector<std::string> KvMediaForMetadata(
+        const ObjectMetadata& metadata) {
+        return MasterService::KvMediaForMetadata(metadata);
+    }
+
+    static std::vector<std::string> KvMediaForRemoval(
+        const ObjectMetadata& metadata) {
+        return MasterService::KvMediaForRemoval(metadata);
+    }
+
+    void LoadTenantQuotaPoliciesFromStoreOrThrow() {
+        service_.LoadTenantQuotaPoliciesFromStoreOrThrow();
+    }
+
+    ObjectIdentity MakeObjectIdentityForRequest(
+        const std::string& user_key, const TenantId& tenant_id) const {
+        return service_.MakeObjectIdentityForRequest(user_key, tenant_id);
+    }
+
+    bool ObserveDynamicReplicationAccess(const ObjectIdentity& object_id) {
+        return service_.ObserveDynamicReplicationAccess(object_id);
+    }
+
+    bool ProcessClientOffboardingJob(ClientOffboardingJob& job) {
+        return service_.ProcessClientOffboardingJob(job);
+    }
+
+    tl::expected<void, ErrorCode> PushOffloadingQueue(
+        const ObjectIdentity& object_id, Replica& replica,
+        std::vector<UUID>* mirror_clients = nullptr) {
+        return service_.PushOffloadingQueue(object_id, replica, mirror_clients);
+    }
+
+    void ReRouteRestoredObjectsByKey() {
+        service_.ReRouteRestoredObjectsByKey();
+    }
+
+    void RebuildGroupState() { service_.RebuildGroupState(); }
+
+    void RebuildTenantQuotaUsageFromMetadata() {
+        service_.RebuildTenantQuotaUsageFromMetadata();
+    }
+
+    void RecomputeTenantEffectiveQuotas() {
+        service_.RecomputeTenantEffectiveQuotas();
+    }
+
+    void ReleaseTenantQuota(TenantQuotaHandle account, uint64_t bytes) {
+        service_.ReleaseTenantQuota(std::move(account), bytes);
+    }
+
+    const TenantId& ResolveRequestTenantId(const TenantId& tenant_id) const {
+        return service_.ResolveRequestTenantId(tenant_id);
+    }
+
+    size_t RunPromotionCandidateRetry(size_t max_shards_to_scan) {
+        return service_.RunPromotionCandidateRetry(max_shards_to_scan);
+    }
+
+    size_t RunPromotionCandidateRetry() {
+        return service_.RunPromotionCandidateRetry();
+    }
+
+    PromotionQueueResult TryPushPromotionQueue(const ObjectIdentity& object_id,
+                                               bool record_candidate = true) {
+        return service_.TryPushPromotionQueue(object_id, record_candidate);
+    }
+
+    size_t getShardIndex(const TenantId& tenant_id,
+                         const std::string& user_key) const {
+        return service_.getShardIndex(tenant_id, user_key);
+    }
+
+    size_t getShardIndex(const std::string& key) const {
+        return service_.getShardIndex(key);
+    }
+
+   private:
+    MasterService& service_;
+};
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_concurrent_scenario_test.cpp b/mooncake-store/tests/master_service_concurrent_scenario_test.cpp
new file mode 100644
index 0000000000..3382995c86
--- /dev/null
+++ b/mooncake-store/tests/master_service_concurrent_scenario_test.cpp
@@ -0,0 +1,157 @@
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <string>
+#include <vector>
+
+#include "master_service/dsl/scenario.h"
+
+namespace mooncake::test {
+namespace {
+
+MasterServiceConfig LeaseConfig(uint64_t lease_ttl_ms) {
+    return MasterServiceConfig::builder()
+        .set_default_kv_lease_ttl(lease_ttl_ms)
+        .build();
+}
+
+MasterServiceConfig OffloadEnabledConfig() {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    return config;
+}
+
+std::string ReadKey(size_t index) {
+    return "read_race_" + std::to_string(index);
+}
+
+std::vector<std::string> ReadKeys(size_t begin, size_t end) {
+    std::vector<std::string> keys;
+    keys.reserve(end - begin);
+    for (size_t index = begin; index < end; ++index) {
+        keys.push_back(ReadKey(index));
+    }
+    return keys;
+}
+
+std::string RemovedKey(size_t index) {
+    return "remove_race_" + std::to_string(index);
+}
+
+}  // namespace
+
+TEST(MasterServiceConcurrentScenarioTest, RemountsAcrossChangingCapacities) {
+    MasterScenario("a segment remounts cleanly across changing capacities")
+        .Given(MemoryNode("memory"))
+        .When(MountUnmountMemoryCapacities(
+            "variable", {1 * 16384_KB, 4 * 16384_KB, 10 * 16384_KB,
+                         2 * 16384_KB, 7 * 16384_KB, 1 * 16384_KB, 3 * 16384_KB,
+                         9 * 16384_KB, 5 * 16384_KB, 8 * 16384_KB}));
+}
+
+TEST(MasterServiceConcurrentScenarioTest, MountUnmountCyclesDoNotInterfere) {
+    MasterScenario("concurrent mount and unmount cycles do not interfere")
+        .Given(MemoryNode("memory"))
+        .When(RaceMountUnmount("race-node")
+                  .Nodes(4)
+                  .Iterations(100)
+                  .ExpectCyclesAtLeast(1));
+}
+
+TEST(MasterServiceConcurrentScenarioTest, ConcurrentPutStartsAdmitOneWriter) {
+    MasterScenario("racing writers of one key admit a single writer")
+        .Given(MemoryNode("memory"))
+        .When(RacePutStart("contested_key", 1_KB).Threads(16))
+        .Then(Object("contested_key").HasReplicas(1).HasCompleteReplicas(1))
+        .Then(MatchingKeys("^contested_key$").HasCount(1));
+}
+
+TEST(MasterServiceConcurrentScenarioTest,
+     GroupedAndUngroupedFirstCreatesAdmitOneWriter) {
+    const std::string key = "grouped_ungrouped_first_create";
+    MasterScenario scenario(
+        "grouped and ungrouped first creates admit a single writer");
+    scenario.Given(MemoryNode("memory"))
+        .When(RacePutStart(key, 1_KB).Threads(16).AcrossGroups(
+            {GroupOnDifferentShard(key), ""}))
+        .Then(Object(key).HasReplicas(1).HasCompleteReplicas(1))
+        .Then(MatchingKeys("^" + key + "$").HasCount(1));
+}
+
+TEST(MasterServiceConcurrentScenarioTest,
+     DifferentlyGroupedFirstCreatesAdmitOneWriter) {
+    const std::string key = "different_grouped_first_create";
+    const std::string group_a = GroupOnDifferentShard(key);
+    MasterScenario scenario(
+        "first creates under different groups admit a single writer");
+    scenario.Given(MemoryNode("memory"))
+        .When(RacePutStart(key, 1_KB).Threads(16).AcrossGroups(
+            {group_a, GroupOnDifferentShard(group_a)}))
+        .Then(Object(key).HasReplicas(1).HasCompleteReplicas(1))
+        .Then(MatchingKeys("^" + key + "$").HasCount(1));
+}
+
+TEST(MasterServiceConcurrentScenarioTest, RemoveAllSweepsAroundInFlightWrites) {
+    MasterScenario scenario("RemoveAll sweeps around writes still in flight");
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .When(RaceWritesWithRemoveAll("write-race")
+                  .Writers(4)
+                  .ObjectsPerWriter(100)
+                  .OfSize(1_KB))
+        .Then(Object("write-race-0-0").DoesNotExist())
+        .Then(Object("write-race-3-99").DoesNotExist());
+}
+
+TEST(MasterServiceConcurrentScenarioTest, RemoveAllPreservesInFlightWrite) {
+    MasterScenario scenario("an in-flight write completes after RemoveAll",
+                            LeaseConfig(0));
+    scenario.Given(MemoryNode("memory"))
+        .When(PutStart("completed", 1_KB))
+        .When(PutEnd("completed"))
+        .When(PutStart("in-flight", 1_KB))
+        .When(RemoveAll().ExpectRemoved(1))
+        .Then(Object("completed").DoesNotExist())
+        .When(PutEnd("in-flight"))
+        .Then(Object("in-flight").IsReadable())
+        .When(RemoveAll().ExpectRemoved(1))
+        .Then(Object("in-flight").DoesNotExist());
+}
+
+TEST(MasterServiceConcurrentScenarioTest, LeasedReadsHoldOffARacingRemoveAll) {
+    constexpr size_t kObjectCount = 1000;
+    constexpr uint64_t kLeaseTtlMs = 200;
+    MasterScenario scenario("reads lease objects past a racing RemoveAll",
+                            LeaseConfig(kLeaseTtlMs));
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(Objects(0, kObjectCount)
+                   .NamedBy(ReadKey)
+                   .Size(1_KB)
+                   .CompleteOn("memory"))
+        .When(RaceReadsWithRemoveAll(ReadKeys(0, kObjectCount))
+                  .Readers(4)
+                  .FinalRemoveAfter(std::chrono::milliseconds(2 * kLeaseTtlMs))
+                  .ExpectTotalRemoved(kObjectCount))
+        .Then(Objects(0, kObjectCount).NamedBy(ReadKey).DoNotExist());
+}
+
+TEST(MasterServiceConcurrentScenarioTest,
+     ConcurrentRemoveAllOperationsPartitionTheStore) {
+    constexpr size_t kObjectCount = 1000;
+    MasterScenario scenario("two RemoveAll sweeps partition the objects");
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(Objects(0, kObjectCount)
+                   .NamedBy(RemovedKey)
+                   .Size(1_KB)
+                   .CompleteOn("memory"))
+        .When(RaceRemoveAll().Callers(2).ExpectTotalRemoved(kObjectCount))
+        .Then(Objects(0, kObjectCount).NamedBy(RemovedKey).DoNotExist());
+}
+
+TEST(MasterServiceConcurrentScenarioTest, ConcurrentLocalDiskMountsAllSucceed) {
+    MasterScenario("one hundred clients mount local disks together",
+                   OffloadEnabledConfig())
+        .Given(MemoryNode("memory"))
+        .When(RaceMountLocalDisk("disk-client").Clients(100));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_config_test.cpp b/mooncake-store/tests/master_service_config_test.cpp
index 4b69bcf5f0..9b909a890b 100644
--- a/mooncake-store/tests/master_service_config_test.cpp
+++ b/mooncake-store/tests/master_service_config_test.cpp
@@ -1,4 +1,5 @@
 #include "master_config.h"
+#include "ha/snapshot/batch_oplog/config.h"
 
 #include <gtest/gtest.h>
 
@@ -26,6 +27,41 @@ TEST(MasterServiceConfigTest, OplogBuilderOverrideIsRespected) {
     EXPECT_TRUE(config.enable_oplog);
 }
 
+TEST(MasterServiceConfigTest, OplogSnapshotDefaultsAndOverridesPropagate) {
+    MasterConfig master_config{};
+    EXPECT_FALSE(master_config.enable_oplog_snapshot);
+    EXPECT_EQ(1000000u, master_config.snapshot_chunk_object_count);
+
+    master_config.enable_oplog_snapshot = true;
+    master_config.snapshot_chunk_object_count = 17;
+    MasterServiceSupervisorConfig supervisor_config(master_config);
+    WrappedMasterServiceConfig wrapped_config(supervisor_config, 1);
+    MasterServiceConfig service_config(wrapped_config);
+
+    EXPECT_TRUE(service_config.enable_oplog_snapshot);
+    EXPECT_EQ(17u, service_config.snapshot_chunk_object_count);
+}
+
+TEST(MasterServiceConfigTest, ValidatesOplogSnapshotConfiguration) {
+    MasterConfig config{};
+    EXPECT_FALSE(ValidateBatchOpLogSnapshotConfig(config).has_value());
+
+    config.enable_oplog_snapshot = true;
+    EXPECT_TRUE(ValidateBatchOpLogSnapshotConfig(config).has_value());
+    config.enable_oplog = true;
+    config.enable_ha = true;
+    config.ha_backend_type = "etcd";
+    config.cluster_id = "snapshot-config-test";
+    config.snapshot_object_store_type = "local";
+    EXPECT_FALSE(ValidateBatchOpLogSnapshotConfig(config).has_value());
+
+    config.snapshot_chunk_object_count = 0;
+    EXPECT_TRUE(ValidateBatchOpLogSnapshotConfig(config).has_value());
+    config.snapshot_chunk_object_count = 1;
+    config.snapshot_object_store_type.clear();
+    EXPECT_TRUE(ValidateBatchOpLogSnapshotConfig(config).has_value());
+}
+
 TEST(MasterServiceConfigTest, OplogEnablementPropagatesToServingConfig) {
     MasterConfig master_config{};
     master_config.enable_oplog = true;
diff --git a/mooncake-store/tests/master_service_dfs_scenario_test.cpp b/mooncake-store/tests/master_service_dfs_scenario_test.cpp
new file mode 100644
index 0000000000..c0af80bc8a
--- /dev/null
+++ b/mooncake-store/tests/master_service_dfs_scenario_test.cpp
@@ -0,0 +1,185 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <filesystem>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include <unistd.h>
+
+#include "master_service/dsl/scenario.h"
+
+namespace mooncake::test {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    ScopedEnvVar(const char* name, const char* value) : name_(name) {
+        const char* previous = ::getenv(name_.c_str());
+        if (previous != nullptr) {
+            previous_value_ = previous;
+        }
+        ::setenv(name_.c_str(), value, 1);
+    }
+
+    ~ScopedEnvVar() {
+        if (previous_value_.has_value()) {
+            ::setenv(name_.c_str(), previous_value_->c_str(), 1);
+        } else {
+            ::unsetenv(name_.c_str());
+        }
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> previous_value_;
+};
+
+// The DFS backend reads its configuration from the environment when the
+// MasterService is constructed, which the scenario defers until its first
+// action; setting the variables in the test body therefore configures the
+// scenario's service exactly as it configured a directly constructed one.
+class ScopedDfsEnvironment {
+   public:
+    ScopedDfsEnvironment(const std::string& tag, const char* shard_capacity)
+        : root_((std::filesystem::temp_directory_path() /
+                 (tag + "_" + std::to_string(::getpid())))
+                    .string()),
+          enable_dfs_("MOONCAKE_ENABLE_DFS", "1"),
+          fs_adapter_("MOONCAKE_DFS_FS_ADAPTER", "posix"),
+          root_dir_("MOONCAKE_DFS_ROOT_DIR", root_.c_str()),
+          shard_count_("MOONCAKE_DFS_SHARD_COUNT", "1"),
+          shard_capacity_("MOONCAKE_DFS_SHARD_CAPACITY", shard_capacity),
+          alignment_("MOONCAKE_DFS_ALIGNMENT", "4096"),
+          // Keep the background path disabled so tests drive one exact
+          // transaction through the EvictDfs action.
+          eviction_("MOONCAKE_DFS_EVICTION_ENABLED", "0"),
+          high_watermark_("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.9"),
+          low_watermark_("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.7"),
+          deferred_free_("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0"),
+          single_tenant_("MOONCAKE_DFS_SINGLE_TENANT", "true") {
+        std::filesystem::create_directories(root_);
+    }
+
+    ~ScopedDfsEnvironment() {
+        std::error_code error;
+        std::filesystem::remove_all(root_, error);
+    }
+
+   private:
+    std::string root_;
+    ScopedEnvVar enable_dfs_;
+    ScopedEnvVar fs_adapter_;
+    ScopedEnvVar root_dir_;
+    ScopedEnvVar shard_count_;
+    ScopedEnvVar shard_capacity_;
+    ScopedEnvVar alignment_;
+    ScopedEnvVar eviction_;
+    ScopedEnvVar high_watermark_;
+    ScopedEnvVar low_watermark_;
+    ScopedEnvVar deferred_free_;
+    ScopedEnvVar single_tenant_;
+};
+
+std::string DfsEvictionKey(size_t index) {
+    return "dfs_evict_" + std::to_string(index);
+}
+
+// One prepared batch of four dual-replica objects, an optional set of leased
+// keys, one eviction transaction, and the per-key survivor counts. A leased
+// key is a rejected candidate; eviction must skip it without rolling back the
+// accepted candidates that share its prepared batch.
+void RunDfsEvictionCase(
+    const std::string& case_name, const std::vector<size_t>& leased_indexes,
+    const std::vector<std::optional<size_t>>& expected_replica_counts,
+    bool evict_memory_first = false) {
+    const ScopedDfsEnvironment dfs("master_dfs_scenario_evict_" + case_name,
+                                   "32768");
+    MasterScenario scenario("DFS eviction case " + case_name);
+    scenario.Given(MemoryNode("memory"));
+    for (size_t index = 0; index < 4; ++index) {
+        scenario.When(PutStart(DfsEvictionKey(index), 100).DfsReplicas(1));
+        scenario.When(PutEnd(DfsEvictionKey(index)).OfType(ReplicaType::ALL));
+    }
+    for (const size_t index : leased_indexes) {
+        scenario.Then(Object(DfsEvictionKey(index)).IsReadable());
+    }
+    if (evict_memory_first) {
+        scenario.When(EvictMemory(1.0));
+    }
+    scenario.When(EvictDfs());
+    for (size_t index = 0; index < expected_replica_counts.size(); ++index) {
+        const auto& expected = expected_replica_counts[index];
+        if (expected.has_value()) {
+            scenario.Then(Object(DfsEvictionKey(index)).HasReplicas(*expected));
+        } else {
+            scenario.Then(Object(DfsEvictionKey(index)).DoesNotExist());
+        }
+    }
+    if (evict_memory_first) {
+        scenario.When(PutStart("dfs_evict_reclaimed", 100).DfsReplicas(1));
+        scenario.When(
+            PutRevoke("dfs_evict_reclaimed").OfType(ReplicaType::ALL));
+    }
+}
+
+}  // namespace
+
+TEST(MasterServiceDfsScenarioTest, PutEndAllAndMismatchedUpsertAreAtomic) {
+    const ScopedDfsEnvironment dfs("master_dfs_scenario_atomic", "1048576");
+    MasterScenario(
+        "PutEnd(ALL) commits both replicas together and a "
+        "mismatched upsert changes neither")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("dfs_atomic", 4_KB).DfsReplicas(1).ExpectReplicas(2))
+        .When(PutEnd("dfs_atomic").OfType(ReplicaType::ALL))
+        .Then(Object("dfs_atomic").HasReplicas(2).HasCompleteReplicas(2))
+        .When(UpsertStart("dfs_atomic", 4_KB)
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .Then(Object("dfs_atomic").HasReplicas(2).HasCompleteReplicas(2))
+        .When(PutStart("dfs_revoke", 4_KB).DfsReplicas(1))
+        .When(PutRevoke("dfs_revoke").OfType(ReplicaType::ALL))
+        .Then(Object("dfs_revoke").DoesNotExist());
+}
+
+TEST(MasterServiceDfsScenarioTest, FailedDfsPutStartDoesNotLeakTenantQuota) {
+    const ScopedDfsEnvironment dfs("master_dfs_scenario_quota", "1048576");
+    // The DFS shard holds 1 MB, so a 4 MB dual-replica put fails admission.
+    // The follow-up memory-only put of the full 4 MB quota succeeds, which it
+    // could not if the failed attempt had leaked a quota charge.
+    MasterScenario("a DFS put that fails admission releases its quota charge")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(TenantId::Default().value()).Quota(4096_KB))
+        .When(PutStart("dfs_quota_failure", 4096_KB)
+                  .DfsReplicas(1)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(PutStart("quota_after_dfs_failure", 4096_KB))
+        .When(PutRevoke("quota_after_dfs_failure").OfType(ReplicaType::ALL));
+}
+
+TEST(MasterServiceDfsScenarioTest, EvictionCommitsUnleasedCandidates) {
+    RunDfsEvictionCase("commit", {}, {1, 1, 2, 2});
+}
+
+TEST(MasterServiceDfsScenarioTest, EvictionRejectsAllLeasedCandidates) {
+    RunDfsEvictionCase("reject", {0, 1, 2, 3}, {2, 2, 2, 2});
+}
+
+TEST(MasterServiceDfsScenarioTest, EvictionSplitsSharedPreparedBatch) {
+    // Key 1 shares the first prepared batch with key 0. Rejecting key 1 must
+    // not roll back key 0, and the same high-watermark trigger must continue
+    // to key 2 so the shard reaches its low watermark.
+    RunDfsEvictionCase("mixed", {1}, {1, 2, 1, 2});
+}
+
+TEST(MasterServiceDfsScenarioTest, EvictionReclaimsLastReplicas) {
+    // Memory eviction may leave DFS as the only remaining replica. DFS
+    // eviction must still reclaim those allocations and erase metadata for
+    // objects whose final replica was removed.
+    RunDfsEvictionCase("last_replica", {},
+                       {std::nullopt, std::nullopt, size_t{1}, size_t{1}},
+                       /*evict_memory_first=*/true);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_evict_scenario_test.cpp b/mooncake-store/tests/master_service_evict_scenario_test.cpp
new file mode 100644
index 0000000000..1ea009af51
--- /dev/null
+++ b/mooncake-store/tests/master_service_evict_scenario_test.cpp
@@ -0,0 +1,831 @@
+#include "master_service/dsl/scenario.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <condition_variable>
+#include <filesystem>
+#include <fstream>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <vector>
+
+#include <unistd.h>
+
+#include "ha/kv/ha_kv_backend.h"
+#include "ha/oplog/oplog_batch_storage.h"
+#include "ha/oplog/oplog_batch_types.h"
+#include "tenant_quota_policy_store.h"
+#include "types.h"
+
+namespace mooncake::test {
+namespace {
+
+class EvictFakeBatchHaKvBackend : public HaKvBackend {
+   public:
+    ErrorCode DeleteRange(std::string_view, std::string_view) override {
+        return ErrorCode::INVALID_PARAMS;
+    }
+
+    ErrorCode Get(std::string_view key, std::string& value) override {
+        std::lock_guard lock(kvs_mutex_);
+        auto it = kvs_.find(std::string(key));
+        if (it == kvs_.end()) {
+            return ErrorCode::ETCD_KEY_NOT_EXIST;
+        }
+        value = it->second;
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Put(std::string_view key, std::string_view value) override {
+        std::lock_guard lock(kvs_mutex_);
+        kvs_[std::string(key)] = std::string(value);
+        return ErrorCode::OK;
+    }
+
+    ErrorCode Range(std::string_view begin_key, std::string_view end_key,
+                    size_t limit, std::vector<KvPair>& kvs) override {
+        std::lock_guard lock(kvs_mutex_);
+        kvs.clear();
+        for (auto it = kvs_.lower_bound(std::string(begin_key));
+             it != kvs_.end() && it->first < end_key; ++it) {
+            kvs.push_back({.key = it->first, .value = it->second});
+            if (limit != 0 && kvs.size() >= limit) {
+                break;
+            }
+        }
+        return ErrorCode::OK;
+    }
+
+    bool SupportsTxn() const override { return true; }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        std::lock_guard lock(kvs_mutex_);
+        for (const auto& compare : txn.compares) {
+            auto it = kvs_.find(compare.key);
+            if (compare.kind == KvCompareKind::kKeyNotExists) {
+                if (it != kvs_.end()) {
+                    return ErrorCode::ETCD_TRANSACTION_FAIL;
+                }
+            } else if (it == kvs_.end() ||
+                       it->second != compare.expected_value) {
+                return ErrorCode::ETCD_TRANSACTION_FAIL;
+            }
+        }
+        for (const auto& put : txn.puts) {
+            kvs_[put.key] = put.value;
+        }
+        return ErrorCode::OK;
+    }
+
+   private:
+    std::mutex kvs_mutex_;
+    std::map<std::string, std::string> kvs_;
+};
+
+class EvictBlockingBatchHaKvBackend : public EvictFakeBatchHaKvBackend {
+   public:
+    void BlockTxn() {
+        std::lock_guard lock(block_mutex_);
+        blocked_ = true;
+    }
+
+    void AllowTxn() {
+        {
+            std::lock_guard lock(block_mutex_);
+            blocked_ = false;
+        }
+        block_cv_.notify_all();
+    }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        {
+            std::unique_lock lock(block_mutex_);
+            block_cv_.wait(lock, [this] { return !blocked_; });
+        }
+        return EvictFakeBatchHaKvBackend::Txn(txn);
+    }
+
+   private:
+    std::mutex block_mutex_;
+    std::condition_variable block_cv_;
+    bool blocked_{false};
+};
+
+class EvictFailingBatchHaKvBackend : public EvictFakeBatchHaKvBackend {
+   public:
+    void FailTransactionsWith(ErrorCode error) {
+        std::lock_guard lock(failure_mutex_);
+        transaction_error_ = error;
+        transaction_calls_ = 0;
+    }
+
+    bool WaitForTransactionCalls(
+        size_t count,
+        std::chrono::milliseconds timeout = std::chrono::seconds(1)) {
+        std::unique_lock lock(failure_mutex_);
+        return failure_cv_.wait_for(
+            lock, timeout, [&] { return transaction_calls_ >= count; });
+    }
+
+    ErrorCode Txn(const KvTxn& txn) override {
+        ErrorCode error;
+        {
+            std::lock_guard lock(failure_mutex_);
+            ++transaction_calls_;
+            error = transaction_error_;
+        }
+        failure_cv_.notify_all();
+        if (error != ErrorCode::OK) {
+            return error;
+        }
+        return EvictFakeBatchHaKvBackend::Txn(txn);
+    }
+
+   private:
+    std::mutex failure_mutex_;
+    std::condition_variable failure_cv_;
+    ErrorCode transaction_error_{ErrorCode::OK};
+    size_t transaction_calls_{0};
+};
+
+class MasterServiceEvictScenarioTest : public ::testing::Test {
+   protected:
+    static constexpr uint64_t kObjectSize = 1_KB;
+
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("MasterServiceEvictScenarioTest");
+        FLAGS_logtostderr = true;
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void TearDown() override {
+        for (const auto& path : policy_files_) {
+            std::error_code error;
+            std::filesystem::remove(path, error);
+        }
+    }
+
+    MasterServiceConfig EvictConfig(bool allow_soft_pin_eviction = false) {
+        return MasterServiceConfig::builder()
+            .set_memory_allocator(BufferAllocatorType::OFFSET)
+            .set_default_kv_lease_ttl(0)
+            .set_default_kv_soft_pin_ttl(60 * 60 * 1000)
+            .set_allow_evict_soft_pinned_objects(allow_soft_pin_eviction)
+            .set_eviction_ratio(0.0)
+            .set_eviction_high_watermark_ratio(1.0)
+            .set_client_live_ttl_sec(3600)
+            .build();
+    }
+
+    MasterServiceConfig PressureConfig(bool allow_soft_pin_eviction = false) {
+        auto config = EvictConfig(allow_soft_pin_eviction);
+        config.eviction_ratio = 0.05;
+        return config;
+    }
+
+    MasterServiceConfig TenantConfig(
+        const std::map<std::string, uint64_t>& quotas) {
+        auto config = EvictConfig();
+        config.enable_multi_tenants = true;
+        config.tenant_quota_connector_type = "file";
+        config.tenant_quota_connector_uri = WritePolicyFile(quotas);
+        return config;
+    }
+
+    MasterServiceConfig HaConfig(
+        const std::string& cluster_id,
+        const std::map<std::string, uint64_t>& quotas = {}) {
+        auto config = EvictConfig();
+        config.enable_ha = true;
+        config.enable_oplog = true;
+        config.cluster_id = cluster_id;
+        config.oplog_batch_max_entries = 1;
+        if (!quotas.empty()) {
+            config.enable_multi_tenants = true;
+            config.tenant_quota_connector_type = "file";
+            config.tenant_quota_connector_uri = WritePolicyFile(quotas);
+        }
+        return config;
+    }
+
+    static std::string Key(size_t index) {
+        return "evict_scenario_key_" + std::to_string(index);
+    }
+
+    static std::chrono::system_clock::time_point ExpiredBase() {
+        return std::chrono::system_clock::now() - std::chrono::hours(1);
+    }
+
+    static ObjectsSpec<> IndexedObjects(size_t begin, size_t end) {
+        auto objects = Objects(begin, end);
+        objects.NamedBy(Key);
+        return objects;
+    }
+
+    void ReadBatchEventually(OpLogBatchStorage& storage, uint64_t batch_id,
+                             OpLogBatchRecord& batch) {
+        ErrorCode error = ErrorCode::ETCD_KEY_NOT_EXIST;
+        for (int attempt = 0; attempt < 100; ++attempt) {
+            error = storage.ReadBatch(batch_id, batch);
+            if (error == ErrorCode::OK) {
+                break;
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        }
+        ASSERT_EQ(error, ErrorCode::OK);
+    }
+
+   private:
+    std::string WritePolicyFile(const std::map<std::string, uint64_t>& quotas) {
+        TenantQuotaPolicySnapshot snapshot;
+        snapshot.tenant_quotas = quotas;
+        const auto path =
+            std::filesystem::temp_directory_path() /
+            ("mooncake_evict_scenario_quota_" + std::to_string(::getpid()) +
+             "_" + std::to_string(policy_files_.size()) + ".yaml");
+        std::ofstream output(path);
+        output << FormatTenantQuotaPolicyYaml(snapshot);
+        output.close();
+        policy_files_.push_back(path.string());
+        return path.string();
+    }
+
+    std::vector<std::string> policy_files_;
+};
+
+TEST_F(MasterServiceEvictScenarioTest, EvictsExactOldestObjectsAtLowRatio) {
+    constexpr size_t kObjectCount = 400;
+    constexpr size_t kExpectedEvicted = 20;
+
+    MasterScenario scenario("evict exact oldest objects", EvictConfig());
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(IndexedObjects(0, kObjectCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase()))
+        .When(EvictMemory(0.05))
+        .Then(ReadableCount(IndexedObjects(0, kObjectCount),
+                            kObjectCount - kExpectedEvicted))
+        .Then(IndexedObjects(0, kExpectedEvicted).DoNotExist())
+        .Then(IndexedObjects(kExpectedEvicted, kObjectCount).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, TargetEqualsLowerBoundEvictsExactCount) {
+    constexpr size_t kObjectCount = 250;
+    constexpr size_t kExpectedEvicted = 25;
+
+    MasterScenario scenario("equal target and lower bound", EvictConfig());
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(IndexedObjects(0, kObjectCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase()))
+        .When(EvictMemory(0.10).ToLowerBound(0.10))
+        .Then(ReadableCount(IndexedObjects(0, kObjectCount),
+                            kObjectCount - kExpectedEvicted))
+        .Then(Object(Key(kExpectedEvicted - 1)).DoesNotExist())
+        .Then(Object(Key(kExpectedEvicted)).IsReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, SoftPinnedObjectsAreFallbackCandidates) {
+    constexpr size_t kUnpinnedCount = 10;
+    constexpr size_t kSoftPinnedCount = 10;
+    constexpr size_t kExpectedSoftPinnedEvicted = 6;
+    const auto base = ExpiredBase();
+    const auto active_soft_pin =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+
+    MasterScenario scenario("soft pin fallback", EvictConfig(true));
+    scenario.Given(MemoryNode("memory"))
+        .Given(IndexedObjects(0, kUnpinnedCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base))
+        .Given(IndexedObjects(kUnpinnedCount, kUnpinnedCount + kSoftPinnedCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base + std::chrono::nanoseconds(kUnpinnedCount))
+                   .SoftPinnedUntil(active_soft_pin))
+        .When(EvictMemory(0.80))
+        .Then(
+            ReadableCount(IndexedObjects(0, kUnpinnedCount + kSoftPinnedCount),
+                          kSoftPinnedCount - kExpectedSoftPinnedEvicted))
+        .Then(IndexedObjects(0, kUnpinnedCount + kExpectedSoftPinnedEvicted)
+                  .DoNotExist())
+        .Then(IndexedObjects(kUnpinnedCount + kExpectedSoftPinnedEvicted,
+                             kUnpinnedCount + kSoftPinnedCount)
+                  .AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, EvictsWholeGroupTogether) {
+    constexpr size_t kObjectCount = 10;
+    constexpr size_t kGroupSize = 3;
+    const auto base = ExpiredBase();
+
+    MasterScenario scenario("whole group eviction", EvictConfig());
+    scenario.Given(MemoryNode("memory"))
+        .Given(IndexedObjects(0, kGroupSize)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("group")
+                   .ExpiredFrom(base))
+        .Given(IndexedObjects(kGroupSize, kObjectCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base + std::chrono::nanoseconds(kGroupSize)))
+        .When(EvictMemory(0.10))
+        .Then(ReadableCount(IndexedObjects(0, kObjectCount),
+                            kObjectCount - kGroupSize))
+        .Then(IndexedObjects(0, kGroupSize).DoNotExist())
+        .Then(IndexedObjects(kGroupSize, kObjectCount).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, ActiveGroupMemberBlocksWholeGroup) {
+    constexpr size_t kObjectCount = 10;
+    constexpr size_t kGroupSize = 3;
+    const auto base = ExpiredBase();
+
+    MasterScenario scenario("active group member blocks eviction",
+                            EvictConfig());
+    scenario.Given(MemoryNode("memory"))
+        .Given(IndexedObjects(0, kGroupSize)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("group")
+                   .ExpiredFrom(base))
+        .Given(IndexedObjects(kGroupSize, kObjectCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base + std::chrono::nanoseconds(kGroupSize)))
+        .When(ExpireAt(Key(kGroupSize - 1), std::chrono::system_clock::now() +
+                                                std::chrono::hours(1)))
+        .When(EvictMemory(0.10))
+        .Then(ReadableCount(IndexedObjects(0, kObjectCount), kObjectCount - 1))
+        .Then(IndexedObjects(0, kGroupSize).AreReadable())
+        .Then(Object(Key(kGroupSize)).DoesNotExist());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, EvictsExactOldestObjectsAtHighRatio) {
+    constexpr size_t kObjectCount = 200;
+    constexpr size_t kExpectedEvicted = 160;
+
+    MasterScenario scenario("high ratio eviction", EvictConfig());
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(IndexedObjects(0, kObjectCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase()))
+        .When(EvictMemory(0.80))
+        .Then(ReadableCount(IndexedObjects(0, kObjectCount),
+                            kObjectCount - kExpectedEvicted))
+        .Then(IndexedObjects(0, kExpectedEvicted).DoNotExist())
+        .Then(IndexedObjects(kExpectedEvicted, kObjectCount).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       ReserveAbsorbsBlockedCandidatesAndMeetsTarget) {
+    constexpr size_t kBlockedCount = 12;
+    constexpr size_t kPlainCount = 1200;
+    constexpr size_t kExpectedEvicted = 61;
+    constexpr size_t kAlwaysEvictedPlain = 49;
+    const auto base = ExpiredBase();
+
+    MasterScenario scenario("reserve absorbs blocked candidates",
+                            EvictConfig());
+    const size_t keeper = kBlockedCount;
+    const size_t plain_begin = keeper + 1;
+    const size_t total = plain_begin + kPlainCount;
+
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(IndexedObjects(0, kBlockedCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("blocked-group")
+                   .ExpiredFrom(base))
+        .Given(IndexedObjects(keeper, keeper + 1)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("blocked-group")
+                   .ExpiresAt(std::chrono::system_clock::now() +
+                              std::chrono::hours(1)))
+        .Given(IndexedObjects(plain_begin, total)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base + std::chrono::nanoseconds(plain_begin)))
+        .When(EvictMemory(0.05))
+        .Then(ReadableCount(IndexedObjects(0, total), total - kExpectedEvicted))
+        .Then(IndexedObjects(0, kBlockedCount + 1).AreReadable())
+        .Then(IndexedObjects(plain_begin, plain_begin + kAlwaysEvictedPlain)
+                  .DoNotExist());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       RefillAfterReserveExhaustionStillMeetsTarget) {
+    constexpr size_t kBlockedCount = 1160;
+    constexpr size_t kPlainCount = 200;
+    constexpr size_t kExpectedEvicted = 69;
+    const auto base = ExpiredBase();
+
+    MasterScenario scenario("refill after reserve exhaustion", EvictConfig());
+    const size_t keeper = kBlockedCount;
+    const size_t plain_begin = keeper + 1;
+    const size_t total = plain_begin + kPlainCount;
+
+    scenario.Given(MemoryNode("memory").Capacity(256 * 1024 * 1024))
+        .Given(IndexedObjects(0, kBlockedCount)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("blocked-group")
+                   .ExpiredFrom(base))
+        .Given(IndexedObjects(keeper, keeper + 1)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .InGroup("blocked-group")
+                   .ExpiresAt(std::chrono::system_clock::now() +
+                              std::chrono::hours(1)))
+        .Given(IndexedObjects(plain_begin, total)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(base + std::chrono::nanoseconds(plain_begin)))
+        .When(EvictMemory(0.05))
+        .Then(ReadableCount(IndexedObjects(0, total), total - kExpectedEvicted))
+        .Then(IndexedObjects(0, kBlockedCount + 1).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, OpLogRecordsEvictedTenantAndKey) {
+    const std::string cluster_id = "evict_scenario_oplog";
+    auto backend = std::make_shared<EvictFakeBatchHaKvBackend>();
+    MasterScenario scenario("eviction writes tenant-scoped oplog",
+                            HaConfig(cluster_id, {{"tenant-a", kObjectSize}}),
+                            backend);
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects({"cold"})
+                   .Size(kObjectSize)
+                   .ForTenant("tenant-a")
+                   .CompleteOn("memory")
+                   .ExpiresAt(ExpiredBase()));
+
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 2, batch);
+
+    scenario.When(EvictMemory(1.0));
+    ReadBatchEventually(storage, 3, batch);
+
+    ASSERT_EQ(batch.entries.size(), 1);
+    EXPECT_EQ(batch.entries[0].op_type, OpType::REMOVE);
+    EXPECT_EQ(batch.entries[0].tenant_id, "tenant-a");
+    EXPECT_EQ(batch.entries[0].object_key, "cold");
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       OpLogDurabilityGatesTenantQuotaReclamation) {
+    const std::string cluster_id = "evict_scenario_durability";
+    const std::string tenant = TenantId::Default().value();
+    auto backend = std::make_shared<EvictBlockingBatchHaKvBackend>();
+    MasterScenario scenario("durability gates eviction quota reclamation",
+                            HaConfig(cluster_id, {{tenant, kObjectSize}}),
+                            backend);
+    scenario.Given(MemoryNode("memory").Capacity(kObjectSize))
+        .Given(Objects({"cold"})
+                   .Size(kObjectSize)
+                   .ForTenant(tenant)
+                   .CompleteOn("memory")
+                   .ExpiresAt(ExpiredBase()));
+
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 2, batch);
+
+    backend->BlockTxn();
+    scenario.When(EvictMemory(1.0))
+        .Then(Object("cold").DoesNotExist())
+        .When(PutStart("before-durable", kObjectSize)
+                  .ForTenant(tenant)
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED));
+
+    backend->AllowTxn();
+    ReadBatchEventually(storage, 3, batch);
+    scenario.When(PutStart("after-durable", kObjectSize)
+                      .ForTenant(tenant)
+                      .ExpectReplicas(1)
+                      .Eventually());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       OpLogReservationFailureLeavesEvictionCandidateReadable) {
+    const std::string cluster_id = "evict_scenario_oplog_failure";
+    auto backend = std::make_shared<EvictFailingBatchHaKvBackend>();
+    MasterScenario scenario("oplog failure keeps eviction candidate intact",
+                            HaConfig(cluster_id), backend);
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects({"cold"})
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .ExpiresAt(ExpiredBase()));
+
+    OpLogBatchStorage storage(cluster_id, *backend);
+    OpLogBatchRecord batch;
+    ReadBatchEventually(storage, 2, batch);
+
+    // Fail a preceding hard-pinned object's PUT_END to put the ordered writer
+    // into its terminal failure state. The following eviction cannot reserve
+    // an OpLog slot and therefore must not mutate the cold object.
+    backend->FailTransactionsWith(ErrorCode::INTERNAL_ERROR);
+    scenario
+        .When(PutStart("writer-failure", kObjectSize)
+                  .OnNode("memory")
+                  .WithHardPin())
+        .When(PutEnd("writer-failure"));
+    ASSERT_TRUE(backend->WaitForTransactionCalls(1));
+
+    scenario.When(WaitForOpLogFailure())
+        .When(EvictMemory(1.0))
+        .Then(Object("cold").IsReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       GlobalEvictReclaimsOnlySelectedTenantQuota) {
+    MasterScenario scenario(
+        "global eviction preserves tenant isolation",
+        TenantConfig({{"tenant-a", kObjectSize}, {"tenant-b", kObjectSize}}));
+    const auto base = ExpiredBase();
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects({"same-key"})
+                   .Size(kObjectSize)
+                   .ForTenant("tenant-a")
+                   .CompleteOn("memory")
+                   .ExpiresAt(base))
+        .Given(Objects({"same-key"})
+                   .Size(kObjectSize)
+                   .ForTenant("tenant-b")
+                   .WithHardPin()
+                   .CompleteOn("memory")
+                   .ExpiresAt(base + std::chrono::seconds(1)))
+        .When(EvictMemory(0.5))
+        .Then(Object("same-key").ForTenant("tenant-a").DoesNotExist())
+        .Then(Object("same-key").ForTenant("tenant-b").IsReadable())
+        .When(PutStart("tenant-a-probe", kObjectSize).ForTenant("tenant-a"))
+        .When(PutStart("tenant-b-probe", 1)
+                  .ForTenant("tenant-b")
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED));
+}
+
+// Admission does not evict. A tenant at its ceiling is rejected outright and
+// the background watermark pass is what makes room -- within that tenant only.
+TEST_F(MasterServiceEvictScenarioTest,
+       TenantOverQuotaRejectsAdmissionAndBackgroundPassReclaims) {
+    MasterScenario scenario(
+        "over-quota admission rejects; the tenant pass makes room",
+        TenantConfig({{"tenant-a", kObjectSize}, {"tenant-b", kObjectSize}}));
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects({"tenant-a-old"})
+                   .Size(kObjectSize)
+                   .ForTenant("tenant-a")
+                   .CompleteOn("memory")
+                   .ExpiresAt(ExpiredBase()))
+        .Given(Objects({"tenant-b-object"})
+                   .Size(kObjectSize)
+                   .ForTenant("tenant-b")
+                   .WithHardPin()
+                   .CompleteOn("memory"))
+        // The write path no longer evicts inline, so the expired object
+        // survives the rejected admission.
+        .When(PutStart("tenant-a-new", kObjectSize)
+                  .ForTenant("tenant-a")
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED))
+        .Then(Object("tenant-a-old").ForTenant("tenant-a").IsReadable())
+        // The pass reclaims tenant-a's own expired object. tenant-b is over
+        // its watermark too, but its object is hard-pinned, so the pass frees
+        // nothing for it and never reaches across tenants to compensate.
+        .When(EvictTenants())
+        .Then(Object("tenant-a-old").ForTenant("tenant-a").DoesNotExist())
+        .Then(Object("tenant-b-object").ForTenant("tenant-b").IsReadable())
+        // With headroom built ahead of it, the retry is admitted.
+        .When(PutStart("tenant-a-new", kObjectSize)
+                  .ForTenant("tenant-a")
+                  .ExpectReplicas(1))
+        .When(PutEnd("tenant-a-new").ForTenant("tenant-a"))
+        // tenant-b has nothing evictable, so it keeps rejecting -- now
+        // without a shard scan per attempt.
+        .When(PutStart("tenant-b-overflow", 1)
+                  .ForTenant("tenant-b")
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED));
+}
+
+// The scenarios below drive the background eviction thread through the
+// client-visible pressure path: a failed allocation arms eviction, and the
+// only observable outcomes are which writes eventually succeed and which
+// objects remain readable. Sizes are chosen so each armed cycle reclaims
+// exactly one expired one-megabyte object.
+
+TEST_F(MasterServiceEvictScenarioTest, AllocationPressureEvictsOldestFirst) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    MasterScenario scenario("allocation pressure evicts the oldest objects",
+                            PressureConfig());
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase()))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(IndexedObjects(0, 3).DoNotExist())
+        .Then(IndexedObjects(3, 15).AreReadable())
+        .Then(ReadableCount(IndexedObjects(0, 15), 12));
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       ClientRequestedSoftPinsSurviveAllocationPressure) {
+    constexpr uint64_t kObjectSize = 1024 * 1024;
+    MasterScenario scenario("client-requested soft pins survive pressure",
+                            PressureConfig(true));
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 2)
+                   .Size(kObjectSize)
+                   .CompleteOn("memory")
+                   .WithSoftPin())
+        .Given(IndexedObjects(2, 14).Size(kObjectSize).CompleteOn("memory"))
+        .When(PutStart(Key(14), 3 * kObjectSize)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(IndexedObjects(0, 2).AreReadable())
+        .Then(Object(Key(14)).IsReadable())
+        .Then(ReadableCount(IndexedObjects(2, 14), 9));
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       PressureEvictsUnpinnedObjectsBeforeSoftPinned) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto active_pin =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    MasterScenario scenario("pressure spares soft-pinned objects",
+                            PressureConfig(true));
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 2)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase())
+                   .SoftPinnedUntil(active_pin))
+        .Given(IndexedObjects(2, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase() + std::chrono::nanoseconds(2)))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(IndexedObjects(0, 2).AreReadable())
+        .Then(IndexedObjects(2, 5).DoNotExist())
+        .Then(IndexedObjects(5, 15).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       PressureEvictsSoftPinnedAsFallbackWhenAllowed) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto active_pin =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    MasterScenario scenario("pressure falls back to soft-pinned objects",
+                            PressureConfig(true));
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase())
+                   .SoftPinnedUntil(active_pin))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .WithSoftPin()
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(IndexedObjects(0, 3).DoNotExist())
+        .Then(IndexedObjects(3, 15).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       PressureCannotReclaimSoftPinnedWhenDisallowed) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto active_pin =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    MasterScenario scenario("soft pins block reclamation when disallowed",
+                            PressureConfig(false));
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase())
+                   .SoftPinnedUntil(active_pin))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(WaitFor(std::chrono::milliseconds(100)))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .Then(IndexedObjects(0, 14).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, HardPinnedObjectsSurvivePressure) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    MasterScenario scenario("hard pins survive pressure until forced removal",
+                            PressureConfig());
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 1)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase())
+                   .WithHardPin())
+        .Given(IndexedObjects(1, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase() + std::chrono::nanoseconds(1)))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(Object(Key(0)).IsReadable())
+        .Then(IndexedObjects(1, 4).DoNotExist())
+        .Then(IndexedObjects(4, 15).AreReadable())
+        .When(Remove(Key(0)).Force())
+        .Then(Object(Key(0)).DoesNotExist());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       PressureSparesHardPinnedAndSoftPinnedInOrder) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto active_pin =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    MasterScenario scenario("pressure spares hard and soft pins in order",
+                            PressureConfig(true));
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024))
+        .Given(IndexedObjects(0, 1)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase())
+                   .WithHardPin())
+        .Given(IndexedObjects(1, 2)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase() + std::chrono::nanoseconds(1))
+                   .SoftPinnedUntil(active_pin))
+        .Given(IndexedObjects(2, 14)
+                   .Size(kLargeObject)
+                   .CompleteOn("memory")
+                   .ExpiredFrom(ExpiredBase() + std::chrono::nanoseconds(2)))
+        .When(PutStart(Key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(Key(14)))
+        .Then(Object(Key(0)).IsReadable())
+        .Then(Object(Key(1)).IsReadable())
+        .Then(IndexedObjects(2, 5).DoNotExist())
+        .Then(IndexedObjects(5, 15).AreReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest, PressureEvictionExpandsToWholeGroup) {
+    constexpr uint64_t kGroupObject = 2 * 1024 * 1024;
+    MasterScenario scenario("pressure eviction expands to the whole group",
+                            PressureConfig());
+    scenario.Given(MemoryNode("memory").Capacity(4 * 1024 * 1024))
+        .Given(Objects({"grouped_evict_a", "grouped_evict_b"})
+                   .Size(kGroupObject)
+                   .CompleteOn("memory")
+                   .InGroup(GroupOnDifferentShard("grouped_evict_a"))
+                   .ExpiredFrom(ExpiredBase()))
+        .When(PutStart("grouped_evict_trigger", kGroupObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd("grouped_evict_trigger"))
+        .Then(Object("grouped_evict_a").DoesNotExist())
+        .Then(Object("grouped_evict_b").DoesNotExist())
+        .Then(Object("grouped_evict_trigger").IsReadable());
+}
+
+TEST_F(MasterServiceEvictScenarioTest,
+       LeasedGroupMemberShieldsWholeGroupFromPressure) {
+    constexpr uint64_t kGroupObject = 2 * 1024 * 1024;
+    auto config = PressureConfig();
+    config.default_kv_lease_ttl = 60 * 60 * 1000;
+    MasterScenario scenario("a leased member shields its group from pressure",
+                            config);
+    scenario.Given(MemoryNode("memory").Capacity(4 * 1024 * 1024))
+        .Given(Objects({"grouped_leased_a", "grouped_leased_b"})
+                   .Size(kGroupObject)
+                   .CompleteOn("memory")
+                   .InGroup(GroupOnDifferentShard("grouped_leased_a"))
+                   .ExpiredFrom(ExpiredBase()))
+        // Reading one member grants it a fresh lease, which shields the whole
+        // group from the eviction armed by the failing writes below.
+        .Then(Object("grouped_leased_a").IsReadable())
+        .When(PutStart("grouped_leased_trigger", kGroupObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(WaitFor(std::chrono::milliseconds(200)))
+        .When(PutStart("grouped_leased_trigger", kGroupObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .Then(Object("grouped_leased_a").IsReadable())
+        .Then(Object("grouped_leased_b").IsReadable());
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_group_scenario_test.cpp b/mooncake-store/tests/master_service_group_scenario_test.cpp
new file mode 100644
index 0000000000..b2e8f4d819
--- /dev/null
+++ b/mooncake-store/tests/master_service_group_scenario_test.cpp
@@ -0,0 +1,241 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <functional>
+#include <string>
+
+namespace mooncake::test {
+
+TEST(MasterServiceGroupScenarioTest, PutStartGroupIdsValidation) {
+    MasterScenario("group ids are validated at put start")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("empty_group_ids", 1_KB)
+                  .InGroups({})
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("too_many_group_ids", 1_KB)
+                  .InGroups({"g0", "g1"})
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("explicit_ungrouped", 1_KB).InGroup(""))
+        .When(PutEnd("explicit_ungrouped"))
+        .Then(KeyExists("explicit_ungrouped"));
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     GroupedObjectRoutesKeyLevelLookupAndRemove) {
+    const std::string key = "grouped_route_key";
+    MasterScenario("grouped object routes key-level lookup and remove")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(PutEnd(key))
+        .Then(KeyExists(key))
+        .Then(Object(key).IsReadable())
+        .When(Remove(key).Force())
+        .Then(Object(key).DoesNotExist());
+}
+
+TEST(MasterServiceGroupScenarioTest, GroupRoutingIsTenantScopedForSameUserKey) {
+    const std::string key = "tenant_grouped_shared_user_key";
+    const std::string group_a = GroupOnDifferentShard(key);
+    std::string group_b;
+    for (int i = 0; i < 10000; ++i) {
+        group_b = key + "_tenant_b_group_" + std::to_string(i);
+        if (std::hash<std::string>{}(group_b) % 1024 !=
+            std::hash<std::string>{}(group_a) % 1024) {
+            break;
+        }
+    }
+
+    MasterScenario("group routing is tenant scoped for the same user key")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant("tenant_group_route_a"))
+        .Given(Tenant("tenant_group_route_b"))
+        .When(PutStart(key, 1_KB)
+                  .ForTenant("tenant_group_route_a")
+                  .InGroup(group_a))
+        .When(PutEnd(key).ForTenant("tenant_group_route_a"))
+        .When(PutStart(key, 2_KB)
+                  .ForTenant("tenant_group_route_b")
+                  .InGroup(group_b))
+        .When(PutEnd(key).ForTenant("tenant_group_route_b"))
+        .Then(KeyExists(key).ForTenant("tenant_group_route_a"))
+        .Then(KeyExists(key).ForTenant("tenant_group_route_b"))
+        .Then(Object(key).ForTenant("tenant_group_route_a").IsReadable())
+        .Then(Object(key).ForTenant("tenant_group_route_b").IsReadable())
+        .When(Remove(key).ForTenant("tenant_group_route_a").Force())
+        .Then(Object(key).ForTenant("tenant_group_route_a").DoesNotExist())
+        .Then(Object(key).ForTenant("tenant_group_route_b").IsReadable());
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     ExpiredGroupedPutCanBeReplacedByUngroupedPut) {
+    auto config = MasterServiceConfig::builder()
+                      .set_put_start_discard_timeout_sec(0)
+                      .set_put_start_release_timeout_sec(1)
+                      .build();
+    const std::string key = "expired_grouped_put_to_ungrouped";
+    MasterScenario("expired grouped put can be replaced by an ungrouped put",
+                   std::move(config))
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(WaitFor(std::chrono::milliseconds(2)))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .Then(KeyExists(key));
+}
+
+TEST(MasterServiceGroupScenarioTest, BatchRemoveUnregistersGroupedRoute) {
+    const std::string key = "batch_remove_grouped_route";
+    MasterScenario("batch remove unregisters the grouped route")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(PutEnd(key))
+        .When(BatchRemove({key}).Force())
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .Then(Object(key).IsReadable());
+}
+
+TEST(MasterServiceGroupScenarioTest, RemoveByRegexUnregistersGroupedRoute) {
+    const std::string key = "regex_remove_grouped_route";
+    MasterScenario("remove by regex unregisters the grouped route")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(PutEnd(key))
+        .When(RemoveByRegex("^regex_remove_grouped_route$")
+                  .Force()
+                  .ExpectRemoved(1))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .Then(Object(key).IsReadable());
+}
+
+TEST(MasterServiceGroupScenarioTest, RemoveGroupedMemberPreservesOtherMembers) {
+    const std::string key_a = "remove_group_key_a";
+    const std::string key_b = "remove_group_key_b";
+    const std::string group = GroupOnDifferentShard(key_a);
+    MasterScenario("removing one grouped member preserves the others")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key_a, 1_KB).InGroup(group))
+        .When(PutEnd(key_a))
+        .When(PutStart(key_b, 1_KB).InGroup(group))
+        .When(PutEnd(key_b))
+        .When(Remove(key_a).Force())
+        .Then(Object(key_a).DoesNotExist())
+        .Then(Object(key_b).IsReadable())
+        .When(Remove(key_b).Force())
+        .Then(Object(key_b).DoesNotExist());
+}
+
+TEST(MasterServiceGroupScenarioTest, UpsertPreservesGroupMembership) {
+    const std::string key = "upsert_group_key";
+    MasterScenario("upsert preserves existing group membership")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(PutEnd(key))
+        .When(UpsertStart(key, 1_KB))
+        .When(UpsertEnd(key))
+        .Then(Object(key).IsReadable())
+        .When(UpsertStart(key, 1_KB)
+                  .InGroup(GroupOnDifferentShard(key + "_other"))
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(UpsertStart(key, 1_KB).InGroup("").ExpectError(
+            ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     IncompleteGroupedUpsertCanBecomeUngrouped) {
+    auto config = MasterServiceConfig::builder()
+                      .set_put_start_discard_timeout_sec(0)
+                      .set_put_start_release_timeout_sec(1)
+                      .build();
+    const std::string key = "incomplete_grouped_upsert_to_ungrouped";
+    MasterScenario("incomplete grouped upsert can become ungrouped",
+                   std::move(config))
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB).InGroup(GroupOnDifferentShard(key)))
+        .When(WaitFor(std::chrono::milliseconds(2)))
+        .When(UpsertStart(key, 1_KB))
+        .When(UpsertEnd(key))
+        .Then(KeyExists(key));
+}
+
+TEST(MasterServiceGroupScenarioTest, UpsertRejectsExistingUngroupedToGrouped) {
+    const std::string key = "upsert_ungrouped_to_grouped";
+    MasterScenario("upsert cannot turn an ungrouped object into a grouped one")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .When(UpsertStart(key, 2_KB)
+                  .InGroup(GroupOnDifferentShard(key))
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .Then(Object(key).IsReadable());
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     BatchUpsertStartMixedGroupIdsPreservesOrder) {
+    const std::string group_a = GroupOnDifferentShard("batch_grouped_a");
+    const std::string group_b = GroupOnDifferentShard("batch_grouped_b");
+    MasterScenario("batch upsert start preserves order with mixed group ids")
+        .Given(MemoryNode("memory"))
+        .When(BatchUpsertStart({{"batch_grouped_a", 1_KB},
+                                {"batch_ungrouped", 2_KB},
+                                {"batch_grouped_b", 4_KB}})
+                  .InGroups({group_a, "", group_b}))
+        .When(BatchUpsertEnd(
+            {"batch_grouped_a", "batch_ungrouped", "batch_grouped_b"}))
+        .Then(Object("batch_grouped_a").IsReadable())
+        .Then(Object("batch_ungrouped").IsReadable())
+        .Then(Object("batch_grouped_b").IsReadable())
+        .When(BatchUpsertStart({{"batch_grouped_a", 1_KB},
+                                {"batch_ungrouped", 2_KB},
+                                {"batch_grouped_b", 4_KB}})
+                  .InGroups({"only_one"})
+                  .ExpectError(ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     BatchExistKeyGroupedAndIncompletePreservesOrder) {
+    const std::string grouped_key_a = "batch_grouped_key_a";
+    const std::string grouped_key_b = "batch_grouped_key_b";
+    const std::string group = GroupOnDifferentShard(grouped_key_a);
+    MasterScenario("batch exist key preserves order with grouped keys")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(grouped_key_a, 1_KB).InGroup(group))
+        .When(PutEnd(grouped_key_a))
+        .When(PutStart(grouped_key_b, 1_KB).InGroup(group))
+        .When(PutEnd(grouped_key_b))
+        .When(PutStart("batch_completed_key", 1_KB))
+        .When(PutEnd("batch_completed_key"))
+        .When(PutStart("batch_incomplete_key", 1_KB))
+        .Then(BatchExistence({grouped_key_a, "batch_completed_key",
+                              "batch_incomplete_key", "batch_missing_key",
+                              grouped_key_b})
+                  .Returns({true, true, false, false, true}));
+}
+
+TEST(MasterServiceGroupScenarioTest,
+     BatchGetReplicaListPreservesOrderWithGroupedKeys) {
+    const std::string grouped_key_a = "batch_get_grouped_a";
+    const std::string grouped_key_b = "batch_get_grouped_b";
+    MasterScenario("batch get replica list preserves order with grouped keys")
+        .Given(MemoryNode("memory"))
+        .When(PutStart(grouped_key_a, 1_KB)
+                  .InGroup(GroupOnDifferentShard(grouped_key_a)))
+        .When(PutEnd(grouped_key_a))
+        .When(PutStart("batch_get_ungrouped", 1_KB))
+        .When(PutEnd("batch_get_ungrouped"))
+        .When(PutStart(grouped_key_b, 1_KB)
+                  .InGroup(GroupOnDifferentShard(grouped_key_b)))
+        .When(PutEnd(grouped_key_b))
+        .When(PutStart("batch_get_pending", 1_KB))
+        .Then(BatchReplicaLists({grouped_key_a, "batch_get_missing",
+                                 "batch_get_ungrouped", grouped_key_b,
+                                 "batch_get_pending"})
+                  .Returns({ErrorCode::OK, ErrorCode::OBJECT_NOT_FOUND,
+                            ErrorCode::OK, ErrorCode::OK,
+                            ErrorCode::REPLICA_IS_NOT_READY}));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_group_test.cpp b/mooncake-store/tests/master_service_group_test.cpp
new file mode 100644
index 0000000000..dfa59e3f68
--- /dev/null
+++ b/mooncake-store/tests/master_service_group_test.cpp
@@ -0,0 +1,544 @@
+#include "master_service_test_fixture.h"
+#include "rpc_service.h"
+
+#include <glog/logging.h>
+
+#include <chrono>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace mooncake::test {
+
+TEST_F(MasterServiceTest, GroupedLeaseRefreshNearExpiryProtectsCurrentMembers) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(200).build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "lease_group_key_a";
+    const std::string key_b = "lease_group_key_b";
+    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+
+    ReplicateConfig config_a;
+    config_a.replica_num = 1;
+    config_a.group_ids = std::vector<std::string>{group_id};
+    ReplicateConfig config_b = config_a;
+
+    PutCompletedObject(*service_, client_id, key_a, config_a);
+    PutCompletedObject(*service_, client_id, key_b, config_b);
+
+    auto exists = service_->ExistKey(key_a, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(120));
+    exists = service_->ExistKey(key_a, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+    auto remove_group_peer = service_->Remove(key_b, TenantId::Default());
+    ASSERT_FALSE(remove_group_peer.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_group_peer.error());
+
+    EXPECT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
+                    .has_value());
+    EXPECT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
+                    .has_value());
+}
+
+TEST_F(MasterServiceTest, GroupedEvictionSkipsUnsafeMembersAndEvictsSafePeers) {
+    constexpr size_t kSegmentSize = 4 * 1024 * 1024;
+    constexpr size_t kObjectSize = 2 * 1024 * 1024;
+    std::unique_ptr<MasterService> service_(new MasterService());
+    [[maybe_unused]] const auto context =
+        PrepareSimpleSegment(*service_, "grouped_mixed_safety_segment",
+                             kDefaultSegmentBase, kSegmentSize);
+    const UUID client_id = generate_uuid();
+
+    const std::string safe_key = "grouped_mixed_safe_key";
+    const std::string hard_pinned_key = "grouped_mixed_hard_pinned_key";
+    const std::string group_id = FindGroupIdOnDifferentShard(safe_key);
+
+    ReplicateConfig safe_config;
+    safe_config.replica_num = 1;
+    safe_config.group_ids = std::vector<std::string>{group_id};
+    PutCompletedObject(*service_, client_id, safe_key, safe_config,
+                       kObjectSize);
+
+    ReplicateConfig hard_pinned_config = safe_config;
+    hard_pinned_config.with_hard_pin = true;
+    PutCompletedObject(*service_, client_id, hard_pinned_key,
+                       hard_pinned_config, kObjectSize);
+
+    ReplicateConfig trigger_config;
+    trigger_config.replica_num = 1;
+    auto trigger_result =
+        service_->PutStart(client_id, "trigger_mixed_safety_group_eviction",
+                           TenantId::Default(), kObjectSize, trigger_config);
+    ASSERT_FALSE(trigger_result.has_value());
+    EXPECT_EQ(ErrorCode::NO_AVAILABLE_HANDLE, trigger_result.error());
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+
+    EXPECT_FALSE(
+        service_->ExistKey(safe_key, TenantId::Default()).value_or(true));
+    EXPECT_TRUE(service_->GetReplicaList(hard_pinned_key, TenantId::Default())
+                    .has_value());
+    EXPECT_TRUE(
+        service_->Remove(hard_pinned_key, TenantId::Default(), /*force=*/true)
+            .has_value());
+}
+
+TEST_F(MasterServiceTest, WrappedBatchPutStartMixedGroupIdsPreservesOrder) {
+    WrappedMasterServiceConfig service_config;
+    service_config.default_kv_lease_ttl = 100;
+    service_config.enable_metric_reporting = false;
+    WrappedMasterService service_(service_config);
+
+    Segment segment = MakeSegment("wrapped_batch_group_segment");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service_.MountSegment(segment, client_id).has_value());
+
+    const std::vector<std::string> keys = {
+        "wrapped_batch_grouped_a",
+        "wrapped_batch_ungrouped",
+        "wrapped_batch_grouped_b",
+    };
+    const std::vector<uint64_t> sizes = {1024, 2048, 4096};
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids =
+        std::vector<std::string>{FindGroupIdOnDifferentShard(keys[0]), "",
+                                 FindGroupIdOnDifferentShard(keys[2])};
+
+    auto results = service_.BatchPutStart(client_id, keys, sizes, config);
+    ASSERT_EQ(results.size(), keys.size());
+    for (const auto& result : results) {
+        ASSERT_TRUE(result.has_value()) << toString(result.error());
+    }
+
+    auto end_results = service_.BatchPutEnd(client_id, MakeObjectMetas(keys));
+    ASSERT_EQ(end_results.size(), keys.size());
+    for (const auto& result : end_results) {
+        ASSERT_TRUE(result.has_value());
+    }
+
+    for (const auto& key : keys) {
+        EXPECT_TRUE(
+            service_.GetReplicaList(key, std::string(TenantId::kDefaultValue))
+                .has_value());
+    }
+
+    ReplicateConfig invalid_config = config;
+    invalid_config.group_ids = std::vector<std::string>{"only_one"};
+    auto invalid_group_results =
+        service_.BatchPutStart(client_id, keys, sizes, invalid_config);
+    ASSERT_EQ(invalid_group_results.size(), keys.size());
+    for (const auto& result : invalid_group_results) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
+    }
+
+    auto invalid_size_results =
+        service_.BatchPutStart(client_id, keys, {1024}, config);
+    ASSERT_EQ(invalid_size_results.size(), keys.size());
+    for (const auto& result : invalid_size_results) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
+    }
+}
+
+TEST_F(MasterServiceTest, TryEvictLeasedObject) {
+    // set a large kv_lease_ttl so the granted lease will not quickly expire
+    const uint64_t kv_lease_ttl = 500;
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    const UUID client_id = generate_uuid();
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t size = 1024 * 1024 * 16;
+    constexpr size_t object_size = 1024 * 1024;
+    [[maybe_unused]] const auto context =
+        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
+
+    // Verify leased object will not be evicted.
+    int success_puts = 0;
+    int failed_puts = 0;
+    std::vector<std::string> leased_keys;
+    for (int i = 0; i < 16 + 10; ++i) {
+        std::string key = "test_key" + std::to_string(i);
+        uint64_t slice_length = object_size;
+        ReplicateConfig config;
+        config.replica_num = 1;
+        auto put_start_result = service_->PutStart(
+            client_id, key, TenantId::Default(), slice_length, config);
+        if (put_start_result.has_value()) {
+            auto put_end_result = service_->PutEnd(
+                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
+            ASSERT_TRUE(put_end_result.has_value());
+            // the object is leased
+            auto get_result =
+                service_->GetReplicaList(key, TenantId::Default());
+            ASSERT_TRUE(get_result.has_value());
+            leased_keys.push_back(key);
+            success_puts++;
+        } else {
+            failed_puts++;
+        }
+    }
+    ASSERT_GT(success_puts, 0);
+    ASSERT_GT(failed_puts, 0);
+    // wait for eviction to do eviction
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    // All leased objects should be accessible
+    for (const auto& key : leased_keys) {
+        auto get_result = service_->GetReplicaList(key, TenantId::Default());
+        ASSERT_TRUE(get_result.has_value());
+    }
+    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
+    service_->RemoveAll();
+}
+
+TEST_F(MasterServiceTest, BatchReplicaClearWithLeaseActive) {
+    const uint64_t kv_lease_ttl = 2000;  // Long lease
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    // Create an object
+    std::string key = "lease_active_key";
+    uint64_t value_length = 1024;
+    ReplicateConfig config;
+    config.replica_num = 1;
+    auto put_start_result = service_->PutStart(
+        client_id, key, TenantId::Default(), value_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
+                                           ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
+
+    // Grant a lease by calling GetReplicaList (similar to normal usage)
+    auto get_result = service_->GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(get_result.has_value());
+
+    // Try to clear immediately (lease should still be active)
+    std::vector<std::string> keys = {key};
+    auto clear_result = service_->BatchReplicaClear(keys, client_id, "");
+    ASSERT_TRUE(clear_result.has_value());
+
+    // Should return empty list because lease is still active
+    const auto& cleared_keys = clear_result.value();
+    EXPECT_TRUE(cleared_keys.empty())
+        << "No keys should be cleared when lease is active";
+
+    // Verify object still exists
+    auto exist_result = service_->ExistKey(key, TenantId::Default());
+    ASSERT_TRUE(exist_result.has_value());
+    ASSERT_TRUE(exist_result.value()) << "Key should still exist";
+}
+
+TEST_F(MasterServiceTest, GroupedRoutingUsesHashOfTenantAndKeyOnly) {
+    // Route-decoupling invariant: object routing is a pure function of
+    // (tenant, key); the group_id is only a lifecycle annotation and never
+    // affects which metadata shard an object lands in. The group domain is
+    // keyed by scoped(tenant, group_id) and stores only the member key list.
+    std::unique_ptr<MasterService> service_(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    // Two member keys that hash to different metadata shards, sharing one
+    // group whose id hashes to yet another shard. The default-tenant route is
+    // hash(key) % kNumShards (mirrors MasterService::getShardIndex).
+    constexpr size_t kMetadataShardCountForTest = 1024;
+    const std::string key_a = "route_decouple_key_a";
+    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+    std::string key_b = "route_decouple_key_b";
+    const size_t shard_a =
+        std::hash<std::string>{}(key_a) % kMetadataShardCountForTest;
+    size_t shard_b =
+        std::hash<std::string>{}(key_b) % kMetadataShardCountForTest;
+    for (int i = 0; i < 10000 && shard_b == shard_a; ++i) {
+        key_b = "route_decouple_key_b_" + std::to_string(i);
+        shard_b = std::hash<std::string>{}(key_b) % kMetadataShardCountForTest;
+    }
+    ASSERT_NE(shard_a, shard_b);  // members span metadata shards
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids = std::vector<std::string>{group_id};
+    PutCompletedObject(*service_, client_id, key_a, config);
+    PutCompletedObject(*service_, client_id, key_b, config);
+
+    // Both members are reachable purely through hash(tenant, key) routing,
+    // which is decoupled from the group domain.
+    EXPECT_TRUE(service_->ExistKey(key_a, TenantId::Default()).value_or(false));
+    EXPECT_TRUE(service_->ExistKey(key_b, TenantId::Default()).value_or(false));
+    EXPECT_TRUE(
+        service_->GetReplicaList(key_a, TenantId::Default()).has_value());
+    EXPECT_TRUE(
+        service_->GetReplicaList(key_b, TenantId::Default()).has_value());
+
+    // The group table still sees both members: group state is a separate,
+    // key-list-only domain.
+    auto members = GetGroupMemberKeysForTest(*service_, group_id);
+    EXPECT_EQ(2u, members.size());
+
+    // Route stability: the object route is hash(tenant, key) alone — grouping
+    // does not change it (identical to the ungrouped route computed before the
+    // objects existed), so a later ungrouped put of the same key would land on
+    // the same shard.
+    EXPECT_EQ(shard_a,
+              std::hash<std::string>{}(key_a) % kMetadataShardCountForTest);
+    EXPECT_EQ(shard_b,
+              std::hash<std::string>{}(key_b) % kMetadataShardCountForTest);
+}
+
+TEST_F(MasterServiceTest, GroupedReadRefreshesSharedGroupLease) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(200).build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "lease_group_key_a";
+    const std::string key_b = "lease_group_key_b";
+    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+
+    ReplicateConfig config_a;
+    config_a.replica_num = 1;
+    config_a.group_ids = std::vector<std::string>{group_id};
+    ReplicateConfig config_b = config_a;
+
+    PutCompletedObject(*service_, client_id, key_a, config_a);
+    PutCompletedObject(*service_, client_id, key_b, config_b);
+
+    // Read key_a (twice, near expiry). Group protection is keyed on ONE shared
+    // group TTL, so reading a member refreshes the group TTL and protects the
+    // WHOLE group (both key_a and key_b), not just the read member.
+    auto exists = service_->ExistKey(key_a, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(120));
+    exists = service_->ExistKey(key_a, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
+
+    // The shared group TTL is active, so a non-force remove of key_a is
+    // rejected.
+    auto remove_read_member = service_->Remove(key_a, TenantId::Default());
+    ASSERT_FALSE(remove_read_member.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_read_member.error());
+
+    // key_b shares the same group TTL and is therefore ALSO protected.
+    auto remove_peer = service_->Remove(key_b, TenantId::Default());
+    ASSERT_FALSE(remove_peer.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_peer.error());
+
+    // Force cleanup both members.
+    EXPECT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
+                    .has_value());
+    EXPECT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
+                    .has_value());
+}
+
+TEST_F(MasterServiceTest, GroupedMembershipChangeStillSharesGroupLeaseOnRead) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(500).build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "lease_group_dirty_key_a";
+    const std::string key_b = "lease_group_dirty_key_b";
+    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids = std::vector<std::string>{group_id};
+
+    PutCompletedObject(*service_, client_id, key_a, config);
+    ASSERT_TRUE(service_->ExistKey(key_a, TenantId::Default()).value_or(false));
+
+    // Add a new member to the group after key_a was already written. On put,
+    // key_b is wired to the SAME shared Lease, so it participates in the
+    // group's protection.
+    PutCompletedObject(*service_, client_id, key_b, config);
+    std::this_thread::sleep_for(std::chrono::milliseconds(150));
+
+    // Reading key_a refreshes the shared group TTL, which key_b also shares.
+    auto exists = service_->ExistKey(key_a, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
+
+    // key_a is protected by the shared group lease...
+    auto remove_read_member = service_->Remove(key_a, TenantId::Default());
+    ASSERT_FALSE(remove_read_member.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_read_member.error());
+
+    // ...and key_b (sharing the same group TTL) is protected too.
+    auto remove_peer = service_->Remove(key_b, TenantId::Default());
+    ASSERT_FALSE(remove_peer.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_peer.error());
+
+    EXPECT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
+                    .has_value());
+    EXPECT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
+                    .has_value());
+}
+
+TEST_F(MasterServiceTest, GroupStateRegistersAndCleansUpMembers) {
+    std::unique_ptr<MasterService> service_(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "group_state_key_a";
+    const std::string key_b = "group_state_key_b";
+    const std::string group_id = "group_state_group";
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids = std::vector<std::string>{group_id};
+    PutCompletedObject(*service_, client_id, key_a, config);
+    PutCompletedObject(*service_, client_id, key_b, config);
+
+    auto members = GetGroupMemberKeysForTest(*service_, group_id);
+    EXPECT_EQ(2u, members.size());
+
+    // Removing one member shrinks, but does not erase, the group.
+    ASSERT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
+                    .has_value());
+    members = GetGroupMemberKeysForTest(*service_, group_id);
+    ASSERT_EQ(1u, members.size());
+    EXPECT_EQ(key_b, members[0]);
+
+    // Removing the last member erases the group.
+    ASSERT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
+                    .has_value());
+    EXPECT_TRUE(GetGroupMemberKeysForTest(*service_, group_id).empty());
+}
+
+TEST_F(MasterServiceTest, RebuildGroupStateRestoresMembershipFromMetadata) {
+    std::unique_ptr<MasterService> service_(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "rebuild_group_key_a";
+    const std::string key_b = "rebuild_group_key_b";
+    const std::string group_id = "rebuild_group_id";
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids = std::vector<std::string>{group_id};
+    PutCompletedObject(*service_, client_id, key_a, config);
+    PutCompletedObject(*service_, client_id, key_b, config);
+
+    // Simulate a snapshot reset: drop all group state.
+    ClearGroupStateForTest(*service_);
+    EXPECT_TRUE(GetGroupMemberKeysForTest(*service_, group_id).empty());
+
+    // Rebuild from object metadata (as snapshot deserialization does).
+    RebuildGroupStateForTest(*service_);
+
+    auto members = GetGroupMemberKeysForTest(*service_, group_id);
+    EXPECT_EQ(2u, members.size());
+}
+
+TEST_F(MasterServiceTest, GroupLeaseIsSharedAndExtendsOnMemberRead) {
+    const uint64_t kv_lease_ttl = 1000;
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+
+    const std::string key_a = "group_lease_member_a";
+    const std::string key_b = "group_lease_member_b";
+    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.group_ids = std::vector<std::string>{group_id};
+    PutCompletedObject(*service_, client_id, key_a, config);
+    PutCompletedObject(*service_, client_id, key_b, config);
+
+    // Both members resolve to the SAME shared Lease.
+    const auto lease_a = GetGroupLeaseForTest(*service_, group_id);
+    ASSERT_NE(nullptr, lease_a);
+    const auto lease_b = GetGroupLeaseForTest(*service_, group_id);
+    ASSERT_NE(nullptr, lease_b);
+    EXPECT_EQ(lease_a.get(), lease_b.get());
+
+    // A freshly-created group (no reads yet) is not protected -> evictable.
+    EXPECT_TRUE(lease_a->IsExpired(std::chrono::system_clock::now()));
+
+    // Reading one member extends the shared group lease -> the whole group is
+    // now protected.
+    EXPECT_TRUE(
+        service_->GetReplicaList(key_a, TenantId::Default()).has_value());
+    EXPECT_FALSE(lease_a->IsExpired(std::chrono::system_clock::now()));
+    // The other member sees the same (shared) extended deadline.
+    EXPECT_FALSE(lease_b->IsExpired(std::chrono::system_clock::now()));
+}
+
+TEST_F(MasterServiceTest, ReRouteRestoredObjectsMovesStaleShardObjects) {
+    std::unique_ptr<MasterService> service_(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    ReRouteRestoredObjectsMigrationForTest(*service_);
+}
+
+TEST_F(MasterServiceTest, RemoveAllLeasedObject) {
+    const uint64_t kv_lease_ttl = 50;
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    const UUID client_id = generate_uuid();
+    for (int i = 0; i < 10; ++i) {
+        std::string key = "test_key" + std::to_string(i);
+        uint64_t slice_length = 1024;
+        ReplicateConfig config;
+        config.replica_num = 1;
+        auto put_start_result = service_->PutStart(
+            client_id, key, TenantId::Default(), slice_length, config);
+        ASSERT_TRUE(put_start_result.has_value());
+        auto put_end_result = service_->PutEnd(
+            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
+        ASSERT_TRUE(put_end_result.has_value());
+        if (i >= 5) {
+            auto exist_result = service_->ExistKey(key, TenantId::Default());
+            ASSERT_TRUE(exist_result.has_value());
+        }
+    }
+    ASSERT_EQ(5, service_->RemoveAll());
+    for (int i = 0; i < 5; ++i) {
+        std::string key = "test_key" + std::to_string(i);
+        auto exist_result = service_->ExistKey(key, TenantId::Default());
+        ASSERT_FALSE(exist_result.value());
+    }
+    // wait for all the lease to expire
+    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
+    ASSERT_EQ(5, service_->RemoveAll());
+    for (int i = 5; i < 10; ++i) {
+        std::string key = "test_key" + std::to_string(i);
+        auto exist_result = service_->ExistKey(key, TenantId::Default());
+        ASSERT_FALSE(exist_result.value());
+    }
+}
+
+}  // namespace mooncake::test
+
+int main(int argc, char** argv) {
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
diff --git a/mooncake-store/tests/master_service_offload_scenario_test.cpp b/mooncake-store/tests/master_service_offload_scenario_test.cpp
new file mode 100644
index 0000000000..e4f16816e8
--- /dev/null
+++ b/mooncake-store/tests/master_service_offload_scenario_test.cpp
@@ -0,0 +1,620 @@
+#include <gtest/gtest.h>
+
+#include <string>
+#include <vector>
+
+#include "master_service/dsl/scenario.h"
+
+namespace mooncake::test {
+namespace {
+
+MasterServiceConfig OffloadConfig(uint64_t lease_ttl_ms = 2000) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.default_kv_lease_ttl = lease_ttl_ms;
+    return config;
+}
+
+MasterServiceConfig OffloadOnEvictConfig() {
+    MasterServiceConfig config = OffloadConfig();
+    config.offload_on_evict = true;
+    return config;
+}
+
+MasterServiceConfig OffloadForceEvictConfig() {
+    MasterServiceConfig config = OffloadOnEvictConfig();
+    config.offload_force_evict = true;
+    return config;
+}
+
+// Matches the local-disk fleet the direct tests build: offloading enabled, no
+// leases in the way, and the allocator ranking segments by SSD free ratio.
+MasterServiceConfig SsdAwareOffloadConfig() {
+    MasterServiceConfig config = OffloadConfig(/*lease_ttl_ms=*/0);
+    config.allocation_strategy_type =
+        AllocationStrategyType::SSD_FREE_RATIO_FIRST;
+    return config;
+}
+
+// Allocation-pressure variant: no leases, the high watermark disabled, and a
+// small eviction ratio so every armed cycle handles exactly one expired
+// one-megabyte object.
+MasterServiceConfig PressureOffloadConfig() {
+    MasterServiceConfig config = OffloadConfig(/*lease_ttl_ms=*/0);
+    config.eviction_ratio = 0.05;
+    config.eviction_high_watermark_ratio = 1.0;
+    return config;
+}
+
+MasterServiceConfig PressureOffloadOnEvictConfig() {
+    MasterServiceConfig config = PressureOffloadConfig();
+    config.offload_on_evict = true;
+    return config;
+}
+
+std::string HeartbeatKey(size_t index) {
+    return "offload_hb_" + std::to_string(index);
+}
+
+std::vector<std::string> HeartbeatKeys(size_t begin, size_t end) {
+    std::vector<std::string> keys;
+    keys.reserve(end - begin);
+    for (size_t index = begin; index < end; ++index) {
+        keys.push_back(HeartbeatKey(index));
+    }
+    return keys;
+}
+
+}  // namespace
+
+TEST(MasterServiceOffloadScenarioTest, HeartbeatReturnsObjectsPutSinceEnable) {
+    // Spread enough keys across the metadata shards that the heartbeat sweep
+    // covers all of them, as the direct test did with 3000 keys per phase.
+    constexpr size_t kBatch = 3000;
+    MasterScenario scenario(
+        "the heartbeat hands back objects put while offloading was enabled",
+        OffloadConfig());
+    scenario.Given(MemoryNode("node").Capacity(16384_KB));
+    scenario.When(MountLocalDisk("node").OffloadingDisabled());
+    scenario.Given(Objects(0, kBatch)
+                       .NamedBy(HeartbeatKey)
+                       .Size(1_KB)
+                       .By("node")
+                       .CompleteOn("node"));
+    scenario.When(OffloadHeartbeat("node").ExpectNoTasks());
+    scenario.Given(Objects(kBatch, 2 * kBatch)
+                       .NamedBy(HeartbeatKey)
+                       .Size(1_KB)
+                       .By("node")
+                       .CompleteOn("node"));
+    scenario.When(OffloadHeartbeat("node").ExpectTasks(
+        HeartbeatKeys(kBatch, 2 * kBatch), 1024));
+    scenario.Given(Objects(2 * kBatch, 3 * kBatch)
+                       .NamedBy(HeartbeatKey)
+                       .Size(1_KB)
+                       .By("node")
+                       .CompleteOn("node"));
+    scenario.When(OffloadHeartbeat("node").ExpectTasks(
+        HeartbeatKeys(2 * kBatch, 3 * kBatch), 1024));
+}
+
+TEST(MasterServiceOffloadScenarioTest, PutEndQueuesOffloadByDefault) {
+    MasterScenario("the default mode queues offload work at PutEnd",
+                   OffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"key_a1", "key_a2", "key_a3"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(OffloadHeartbeat("node").ExpectTasks(
+            {"key_a1", "key_a2", "key_a3"}, 1024));
+}
+
+TEST(MasterServiceOffloadScenarioTest, OffloadOnEvictSkipsQueueingAtPutEnd) {
+    MasterScenario("offload_on_evict defers queueing to eviction",
+                   OffloadOnEvictConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"key_b1", "key_b2", "key_b3"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(OffloadHeartbeat("node").ExpectNoTasks());
+}
+
+TEST(MasterServiceOffloadScenarioTest,
+     OffloadOnEvictWithForceEvictSkipsQueueingAtPutEnd) {
+    MasterScenario("offload_force_evict does not restore PutEnd queueing",
+                   OffloadForceEvictConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"key_c1", "key_c2"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(OffloadHeartbeat("node").ExpectNoTasks());
+}
+
+TEST(MasterServiceOffloadScenarioTest, ForceEvictAloneKeepsDefaultQueueing) {
+    MasterServiceConfig config = OffloadConfig();
+    config.offload_force_evict = true;  // on_evict is false, so it is ignored
+    MasterScenario("offload_force_evict alone behaves like the default mode",
+                   config)
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"key_d1", "key_d2"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(OffloadHeartbeat("node").ExpectTasks({"key_d1", "key_d2"}, 1024));
+}
+
+TEST(MasterServiceOffloadScenarioTest, BatchRemoveDropsQueuedOffloadMirrors) {
+    // EraseMetadata must drop the mirror entry in the LocalDisk segment's
+    // offloading_objects; a stale entry would be drained back to the client
+    // and produce an orphan bucket on SSD.
+    MasterScenario("a removed key leaves nothing in the offload queue",
+                   OffloadConfig(/*lease_ttl_ms=*/0))
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"key_r1", "key_r2", "key_r3"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(BatchRemove({"key_r1", "key_r2", "key_r3"}).Force())
+        .When(OffloadHeartbeat("node").ExpectNoTasks());
+}
+
+// An offload task passes through two observable states in
+// offloading_tasks[key]: QUEUED (mirror still present, worker has not seen
+// the task; UpsertStart cancels it in place) and IN-FLIGHT (mirror drained by
+// the heartbeat; UpsertStart returns OBJECT_HAS_REPLICATION_TASK and the
+// caller retries after the worker's completion).
+
+TEST(MasterServiceOffloadScenarioTest, UpsertPreemptsQueuedOffload) {
+    MasterScenario(
+        "an upsert cancels a queued offload and leaves no stale "
+        "queue entry",
+        OffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(PutStart("upsert_over_queued_offload", 1_KB)
+                  .By("node")
+                  .ExpectReplicas(1))
+        .When(PutEnd("upsert_over_queued_offload").By("node"))
+        .When(UpsertStart("upsert_over_queued_offload", 1_KB)
+                  .By("node")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .When(OffloadHeartbeat("node").ExpectNoTasks())
+        .When(PutEnd("upsert_over_queued_offload").By("node"));
+}
+
+TEST(MasterServiceOffloadScenarioTest, BatchUpsertPreemptsQueuedOffloads) {
+    MasterScenario("a batch upsert preempts every queued offload it covers",
+                   OffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .Given(Objects({"batch_k1", "batch_k2", "batch_k3"})
+                   .Size(1_KB)
+                   .By("node")
+                   .CompleteOn("node"))
+        .When(BatchUpsertStart(
+                  {{"batch_k1", 1_KB}, {"batch_k2", 1_KB}, {"batch_k3", 1_KB}})
+                  .By("node"))
+        .When(OffloadHeartbeat("node").ExpectNoTasks());
+}
+
+TEST(MasterServiceOffloadScenarioTest, UpsertIsRejectedWhileOffloadInFlight) {
+    MasterScenario("an upsert cannot displace an offload the worker owns",
+                   OffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(PutStart("upsert_over_inflight_offload", 1_KB)
+                  .By("node")
+                  .ExpectReplicas(1))
+        .When(PutEnd("upsert_over_inflight_offload").By("node"))
+        .When(OffloadHeartbeat("node").ExpectTasks(
+            {"upsert_over_inflight_offload"}, 1024))
+        .When(UpsertStart("upsert_over_inflight_offload", 1_KB)
+                  .By("node")
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK));
+}
+
+TEST(MasterServiceOffloadScenarioTest,
+     RejectedUpsertLeavesTheOtherMirrorInPlace) {
+    // A key replicated onto two clients gets a mirror on each of their
+    // LocalDisk segments, both covered by a single offloading_tasks entry.
+    // Draining one client's queue hands that worker the task, so the upsert
+    // must be rejected and the other client's mirror must survive for the
+    // worker's completion.
+    MasterScenario("a rejected upsert does not consume the second mirror",
+                   OffloadConfig())
+        .Given(MemoryNode("node-a"))
+        .Given(MemoryNode("node-b"))
+        .When(MountLocalDisk("node-a"))
+        .When(MountLocalDisk("node-b"))
+        .When(PutStart("upsert_over_partially_drained_offload", 1_KB)
+                  .By("node-a")
+                  .Replicas(2)
+                  .OnNodes({"node-a", "node-b"})
+                  .ExpectReplicas(2))
+        .When(PutEnd("upsert_over_partially_drained_offload").By("node-a"))
+        .When(OffloadHeartbeat("node-a").ExpectTasks(
+            {"upsert_over_partially_drained_offload"}, 1024))
+        .When(UpsertStart("upsert_over_partially_drained_offload", 1_KB)
+                  .By("node-a")
+                  .Replicas(2)
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK))
+        .When(OffloadHeartbeat("node-b").ExpectTasks(
+            {"upsert_over_partially_drained_offload"}, 1024));
+}
+
+TEST(MasterServiceOffloadScenarioTest, RemoveReleasesLocalDiskUsage) {
+    // Both stores report 1000 bytes of SSD. Offloading 800 bytes to disk-1
+    // leaves it 20% free against disk-2's 90%, so disk-2 would win the next
+    // allocation; removing the heavy object must hand disk-1 its bytes back.
+    MasterScenario("Remove returns an offloaded object's SSD bytes",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("disk-1"))
+        .Given(MemoryNode("disk-2"))
+        .When(MountLocalDisk("disk-1"))
+        .When(ReportSsdCapacity("disk-1", 1000))
+        .When(MountLocalDisk("disk-2"))
+        .When(ReportSsdCapacity("disk-2", 1000))
+        .When(PutStart("ssd_remove_released", 800).By("disk-1"))
+        .When(PutEnd("ssd_remove_released").By("disk-1"))
+        .When(CompleteOffload({"ssd_remove_released"})
+                  .By("disk-1")
+                  .OnNode("disk-1"))
+        .When(PutStart("ssd_remove_baseline", 100).By("disk-2"))
+        .When(PutEnd("ssd_remove_baseline").By("disk-2"))
+        .When(CompleteOffload({"ssd_remove_baseline"})
+                  .By("disk-2")
+                  .OnNode("disk-2"))
+        .When(Remove("ssd_remove_released"))
+        .When(PutStart("ssd_remove_probe", 64)
+                  .By("disk-1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"disk-1"}));
+}
+
+TEST(MasterServiceOffloadScenarioTest, ReplicaClearReleasesLocalDiskUsage) {
+    MasterScenario("BatchReplicaClear returns an offloaded object's SSD bytes",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("disk-1"))
+        .Given(MemoryNode("disk-2"))
+        .When(MountLocalDisk("disk-1"))
+        .When(ReportSsdCapacity("disk-1", 1000))
+        .When(MountLocalDisk("disk-2"))
+        .When(ReportSsdCapacity("disk-2", 1000))
+        .When(PutStart("ssd_clear_released", 800).By("disk-1"))
+        .When(PutEnd("ssd_clear_released").By("disk-1"))
+        .When(CompleteOffload({"ssd_clear_released"})
+                  .By("disk-1")
+                  .OnNode("disk-1"))
+        .When(PutStart("ssd_clear_baseline", 100).By("disk-2"))
+        .When(PutEnd("ssd_clear_baseline").By("disk-2"))
+        .When(CompleteOffload({"ssd_clear_baseline"})
+                  .By("disk-2")
+                  .OnNode("disk-2"))
+        .When(ClearReplicas({"ssd_clear_released"})
+                  .By("disk-1")
+                  .ExpectCleared({"ssd_clear_released"}))
+        .When(PutStart("ssd_clear_probe", 64)
+                  .By("disk-1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"disk-1"}));
+}
+
+TEST(MasterServiceOffloadScenarioTest, AllocationPrefersTheFresherSsd) {
+    MasterScenario("the allocator follows SSD free ratio after offloads",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("disk-1"))
+        .Given(MemoryNode("disk-2"))
+        .When(MountLocalDisk("disk-1"))
+        .When(ReportSsdCapacity("disk-1", 1000))
+        .When(MountLocalDisk("disk-2"))
+        .When(ReportSsdCapacity("disk-2", 1000))
+        .When(PutStart("ssd_fresher_heavy", 800).By("disk-1"))
+        .When(PutEnd("ssd_fresher_heavy").By("disk-1"))
+        .When(CompleteOffload({"ssd_fresher_heavy"})
+                  .By("disk-1")
+                  .OnNode("disk-1"))
+        .When(PutStart("ssd_fresher_light", 100).By("disk-2"))
+        .When(PutEnd("ssd_fresher_light").By("disk-2"))
+        .When(CompleteOffload({"ssd_fresher_light"})
+                  .By("disk-2")
+                  .OnNode("disk-2"))
+        .When(PutStart("ssd_fresher_probe", 64)
+                  .By("disk-2")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"disk-2"}));
+}
+
+TEST(MasterServiceOffloadScenarioTest, EvictDiskReplicaReleasesLocalDiskUsage) {
+    MasterScenario("evicting a LOCAL_DISK replica returns its SSD bytes",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("disk-1"))
+        .Given(MemoryNode("disk-2"))
+        .When(MountLocalDisk("disk-1"))
+        .When(ReportSsdCapacity("disk-1", 1000))
+        .When(MountLocalDisk("disk-2"))
+        .When(ReportSsdCapacity("disk-2", 1000))
+        .When(PutStart("ssd_evict_dec_heavy", 800).By("disk-1"))
+        .When(PutEnd("ssd_evict_dec_heavy").By("disk-1"))
+        .When(CompleteOffload({"ssd_evict_dec_heavy"})
+                  .By("disk-1")
+                  .OnNode("disk-1"))
+        .When(PutStart("ssd_evict_dec_light", 100).By("disk-2"))
+        .When(PutEnd("ssd_evict_dec_light").By("disk-2"))
+        .When(CompleteOffload({"ssd_evict_dec_light"})
+                  .By("disk-2")
+                  .OnNode("disk-2"))
+        .When(PutStart("ssd_evict_dec_probe1", 64)
+                  .By("disk-2")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"disk-2"}))
+        .When(EvictDiskReplica("ssd_evict_dec_heavy")
+                  .By("disk-1")
+                  .OfType(ReplicaType::LOCAL_DISK))
+        .When(PutStart("ssd_evict_dec_probe2", 64)
+                  .By("disk-1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"disk-1"}));
+}
+
+// A LOCAL_DISK segment used to leave the master only when its client expired,
+// so a store that was shutting down stayed advertised as the owner of its
+// offloaded keys for up to one client_ttl. These cover the operation that
+// lets it deregister itself instead.
+
+TEST(MasterServiceOffloadScenarioTest, UnmountLocalDiskRequiresOffloadMode) {
+    MasterScenario(
+        "deregistration is refused when offload is not enabled",
+        MasterServiceConfig::builder().set_root_fs_dir("/mnt/ssd").build())
+        .Given(MemoryNode("node"))
+        .When(UnmountLocalDisk("node").ExpectError(ErrorCode::UNABLE_OFFLOAD));
+}
+
+TEST(MasterServiceOffloadScenarioTest, UnmountLocalDiskIsIdempotent) {
+    MasterScenario("repeated and never-mounted deregistrations succeed",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(ReportSsdCapacity("node", 1000))
+        .When(UnmountLocalDisk("node"))
+        .When(UnmountLocalDisk("node"))
+        .When(UnmountLocalDisk("never-mounted"));
+}
+
+TEST(MasterServiceOffloadScenarioTest, UnmountLocalDiskStopsOffloadWork) {
+    // The master hands a deregistered client no further offload work. The
+    // client reads this as its cue to re-mount, which is why a draining store
+    // must latch offloading off before calling.
+    MasterScenario("a deregistered client's heartbeat is refused",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(ReportSsdCapacity("node", 1000))
+        .When(OffloadHeartbeat("node"))
+        .When(UnmountLocalDisk("node"))
+        .When(
+            OffloadHeartbeat("node").ExpectError(ErrorCode::SEGMENT_NOT_FOUND));
+}
+
+TEST(MasterServiceOffloadScenarioTest, UnmountLocalDiskDropsOnlyItsReplicas) {
+    // Neither client re-mounts, so neither is in the master's alive set. That
+    // is the case that catches a deregistration which sweeps by liveness
+    // instead of by owner: it would take the staying store's replicas too.
+    MasterScenario("deregistration sweeps by owner, not by liveness",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("leaving"))
+        .Given(MemoryNode("staying"))
+        .When(MountLocalDisk("leaving"))
+        .When(ReportSsdCapacity("leaving", 1000))
+        .When(MountLocalDisk("staying"))
+        .When(ReportSsdCapacity("staying", 1000))
+        .When(PutStart("ssd_unmount_leaving_key", 1_KB).By("leaving"))
+        .When(PutEnd("ssd_unmount_leaving_key").By("leaving"))
+        .When(CompleteOffload({"ssd_unmount_leaving_key"})
+                  .By("leaving")
+                  .OnNode("leaving"))
+        .When(PutStart("ssd_unmount_staying_key", 1_KB).By("staying"))
+        .When(PutEnd("ssd_unmount_staying_key").By("staying"))
+        .When(CompleteOffload({"ssd_unmount_staying_key"})
+                  .By("staying")
+                  .OnNode("staying"))
+        .When(UnmountLocalDisk("leaving"))
+        .Then(Object("ssd_unmount_leaving_key")
+                  .HasReplicas(1)
+                  .HasMemoryReplicas(1))
+        .Then(Object("ssd_unmount_staying_key")
+                  .HasReplicas(2)
+                  .HasLocalDiskReplicas(1));
+}
+
+TEST(MasterServiceOffloadScenarioTest, UnmountLocalDiskKeepsReAdoptionWorking) {
+    // A key whose only replica is the disk is what a store's own files look
+    // like to the master after it re-registers them. Deregistration erases it
+    // the same as client expiry would, and a store that comes back re-adopts
+    // its files, so deregistering costs a restart nothing.
+    MasterScenario("a disk-only key is erased and can be re-adopted",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(ReportSsdCapacity("node", 1000))
+        .When(CompleteOffload({"ssd_unmount_disk_only_key"})
+                  .By("node")
+                  .OnNode("node")
+                  .OfSize(1024))
+        .Then(Object("ssd_unmount_disk_only_key").IsReadable())
+        .When(UnmountLocalDisk("node"))
+        .Then(Object("ssd_unmount_disk_only_key").DoesNotExist())
+        .When(MountLocalDisk("node"))
+        .When(CompleteOffload({"ssd_unmount_disk_only_key"})
+                  .By("node")
+                  .OnNode("node")
+                  .OfSize(1024))
+        .Then(Object("ssd_unmount_disk_only_key")
+                  .HasReplicas(1)
+                  .HasLocalDiskReplicas(1));
+}
+
+TEST(MasterServiceOffloadScenarioTest, CompleteOffloadAfterUnmountIsRefused) {
+    // A registration that arrives after the deregistration -- an in-flight
+    // rescan batch, or an offload completion racing the drain -- must be
+    // refused, so it cannot land after the sweep and leave the master
+    // advertising a departed owner. The orphan re-adoption path is refused
+    // the same way.
+    MasterScenario("late offload completions cannot revive a swept segment",
+                   SsdAwareOffloadConfig())
+        .Given(MemoryNode("node"))
+        .When(MountLocalDisk("node"))
+        .When(ReportSsdCapacity("node", 1000))
+        .When(PutStart("ssd_gate_key", 1_KB).By("node"))
+        .When(PutEnd("ssd_gate_key").By("node"))
+        .When(CompleteOffload({"ssd_gate_key"}).By("node").OnNode("node"))
+        .When(UnmountLocalDisk("node"))
+        .When(CompleteOffload({"ssd_gate_key"})
+                  .By("node")
+                  .OnNode("node")
+                  .ExpectError(ErrorCode::SEGMENT_NOT_FOUND))
+        .Then(Object("ssd_gate_key").HasReplicas(1).HasMemoryReplicas(1))
+        .When(CompleteOffload({"ssd_gate_orphan_key"})
+                  .By("node")
+                  .OnNode("node")
+                  .OfSize(1024)
+                  .ExpectError(ErrorCode::SEGMENT_NOT_FOUND))
+        .Then(Object("ssd_gate_orphan_key").DoesNotExist());
+}
+
+// The four offload/eviction config combos, driven through the client-visible
+// pressure path: a failed allocation arms the background eviction thread, and
+// the observable outcomes are which writes eventually succeed, which objects
+// stay readable, and what the offload heartbeat hands back.
+
+TEST(MasterServiceOffloadScenarioTest, DefaultModeEvictsUnderPressure) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto key = [](size_t index) {
+        return "combo_a_" + std::to_string(index);
+    };
+    MasterScenario scenario("the default mode reclaims memory under pressure",
+                            PressureOffloadConfig());
+    scenario.Given(MemoryNode("node").Capacity(16 * 1024 * 1024))
+        .Given(Objects(0, 14)
+                   .NamedBy(key)
+                   .Size(kLargeObject)
+                   .CompleteOn("node")
+                   .ExpiredFrom(std::chrono::system_clock::now() -
+                                std::chrono::hours(1)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(key(14)))
+        .Then(Objects(0, 3).NamedBy(key).DoNotExist())
+        .Then(Objects(3, 15).NamedBy(key).AreReadable());
+}
+
+TEST(MasterServiceOffloadScenarioTest,
+     ForceEvictAloneStillEvictsUnderPressure) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto key = [](size_t index) {
+        return "combo_d_" + std::to_string(index);
+    };
+    MasterServiceConfig config = PressureOffloadConfig();
+    config.offload_force_evict = true;  // on_evict is false, so it is ignored
+    MasterScenario scenario(
+        "offload_force_evict alone leaves pressure eviction unchanged", config);
+    scenario.Given(MemoryNode("node").Capacity(16 * 1024 * 1024))
+        .Given(Objects(0, 14)
+                   .NamedBy(key)
+                   .Size(kLargeObject)
+                   .CompleteOn("node")
+                   .ExpiredFrom(std::chrono::system_clock::now() -
+                                std::chrono::hours(1)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(key(14)))
+        .Then(Objects(0, 3).NamedBy(key).DoNotExist())
+        .Then(Objects(3, 15).NamedBy(key).AreReadable());
+}
+
+TEST(MasterServiceOffloadScenarioTest, OffloadOnEvictQueuesInsteadOfFreeing) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto key = [](size_t index) {
+        return "combo_b_" + std::to_string(index);
+    };
+    MasterScenario scenario(
+        "offload_on_evict queues eviction candidates without freeing memory",
+        PressureOffloadOnEvictConfig());
+    scenario.Given(MemoryNode("node").Capacity(16 * 1024 * 1024))
+        .When(MountLocalDisk("node"))
+        .Given(Objects(0, 14)
+                   .NamedBy(key)
+                   .Size(kLargeObject)
+                   .By("node")
+                   .CompleteOn("node")
+                   .ExpiredFrom(std::chrono::system_clock::now() -
+                                std::chrono::hours(1)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .By("node")
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(WaitFor(std::chrono::milliseconds(100)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .By("node")
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(OffloadHeartbeat("node").ExpectSomeTasks())
+        .Then(Objects(0, 14).NamedBy(key).AreReadable());
+}
+
+TEST(MasterServiceOffloadScenarioTest,
+     OffloadOnEvictWithoutLocalDiskPreservesMemory) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto key = [](size_t index) {
+        return "combo_b2_" + std::to_string(index);
+    };
+    MasterScenario scenario(
+        "offload_on_evict without a local disk cannot free memory",
+        PressureOffloadOnEvictConfig());
+    scenario.Given(MemoryNode("node").Capacity(16 * 1024 * 1024))
+        .Given(Objects(0, 14)
+                   .NamedBy(key)
+                   .Size(kLargeObject)
+                   .CompleteOn("node")
+                   .ExpiredFrom(std::chrono::system_clock::now() -
+                                std::chrono::hours(1)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .When(WaitFor(std::chrono::milliseconds(100)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .ExpectError(ErrorCode::NO_AVAILABLE_HANDLE))
+        .Then(Objects(0, 14).NamedBy(key).AreReadable());
+}
+
+TEST(MasterServiceOffloadScenarioTest,
+     ForceEvictReclaimsMemoryWhenOffloadPushFails) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    const auto key = [](size_t index) {
+        return "combo_c_" + std::to_string(index);
+    };
+    MasterServiceConfig config = PressureOffloadOnEvictConfig();
+    config.offload_force_evict = true;
+    MasterScenario scenario(
+        "offload_force_evict reclaims memory when the queue push fails",
+        config);
+    scenario.Given(MemoryNode("node").Capacity(16 * 1024 * 1024))
+        .Given(Objects(0, 14)
+                   .NamedBy(key)
+                   .Size(kLargeObject)
+                   .CompleteOn("node")
+                   .ExpiredFrom(std::chrono::system_clock::now() -
+                                std::chrono::hours(1)))
+        .When(PutStart(key(14), 3 * kLargeObject)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(key(14)))
+        .Then(Objects(0, 3).NamedBy(key).DoNotExist())
+        .Then(Objects(3, 15).NamedBy(key).AreReadable());
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_placement_scenario_test.cpp b/mooncake-store/tests/master_service_placement_scenario_test.cpp
new file mode 100644
index 0000000000..f49bdf7e53
--- /dev/null
+++ b/mooncake-store/tests/master_service_placement_scenario_test.cpp
@@ -0,0 +1,216 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+#include <string>
+
+namespace mooncake::test {
+
+TEST(MasterServicePlacementScenarioTest, PutWithPreferredSegment) {
+    MasterScenario("a single preferred node receives the replica")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("preferred_key", 1_KB)
+                  .OnNode("node-1")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING)
+                  .ExpectMemoryNodes({"node-1"}))
+        .When(PutEnd("preferred_key"))
+        .Then(Object("preferred_key").IsReadable().IsOnMemoryNode("node-1"));
+}
+
+TEST(MasterServicePlacementScenarioTest, PutWithPreferredSegments) {
+    MasterScenario("preferred nodes receive one replica each")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("preferred_keys", 1_KB)
+                  .Replicas(2)
+                  .OnNodes({"node-0", "node-1"})
+                  .ExpectReplicas(2)
+                  .ExpectStatus(ReplicaStatus::PROCESSING)
+                  .ExpectMemoryNodes({"node-0", "node-1"}))
+        .When(PutEnd("preferred_keys"))
+        .Then(Object("preferred_keys")
+                  .IsReadable()
+                  .HasMemoryNodes({"node-0", "node-1"}));
+}
+
+TEST(MasterServicePlacementScenarioTest, LocalFirstPutPrefersWriterHost) {
+    auto config =
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build();
+    MasterScenario("local-first placement prefers the writer host",
+                   std::move(config))
+        .Given(MemoryNode("node-host0").OnHost("host0"))
+        .Given(MemoryNode("node-host1").OnHost("host1"))
+        .When(PutStart("local_first_key", 1_KB)
+                  .FromHost("host1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host1"}));
+}
+
+TEST(MasterServicePlacementScenarioTest,
+     PreferSameNodeUsesHostAwareLocalFirstPlacement) {
+    MasterScenario("prefer-same-node opts into host-aware placement")
+        .Given(MemoryNode("node-host0").OnHost("host0"))
+        .Given(MemoryNode("node-host1").OnHost("host1"))
+        .When(PutStart("prefer_same_node_key", 1_KB)
+                  .PreferSameNode()
+                  .FromHost("host1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host1"}));
+}
+
+TEST(MasterServicePlacementScenarioTest, LocalFirstPutFallsBackToNextHost) {
+    auto config =
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build();
+    MasterScenario("local-first falls back to the next ordered host",
+                   std::move(config))
+        .Given(MemoryNode("node-host0").OnHost("host0"))
+        .Given(MemoryNode("node-host2").OnHost("host2"))
+        .When(PutStart("ordered_fallback_key", 1_KB)
+                  .FromHost("host1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host2"}));
+}
+
+TEST(MasterServicePlacementScenarioTest,
+     LocalFirstPutFallsBackWhenLocalSegmentIsFull) {
+    auto config =
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build();
+    MasterScenario("local-first falls back once the local node is full",
+                   std::move(config))
+        .Given(MemoryNode("node-host1").OnHost("host1").Capacity(1024))
+        .Given(MemoryNode("node-host2").OnHost("host2"))
+        .When(PutStart("fill_local_segment", 1_KB)
+                  .FromHost("host1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host1"}))
+        .When(PutEnd("fill_local_segment"))
+        .When(PutStart("fallback_after_local_full", 1)
+                  .FromHost("host1")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host2"}));
+}
+
+TEST(MasterServicePlacementScenarioTest,
+     ExplicitPreferredSegmentOverridesLocalFirst) {
+    auto config =
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build();
+    MasterScenario("an explicit preferred node overrides local-first",
+                   std::move(config))
+        .Given(MemoryNode("node-host0").OnHost("host0"))
+        .Given(MemoryNode("node-host1").OnHost("host1"))
+        .When(PutStart("explicit_preferred_key", 1_KB)
+                  .FromHost("host1")
+                  .OnNode("node-host0")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host0"}));
+}
+
+TEST(MasterServicePlacementScenarioTest,
+     ExplicitPreferredSegmentFallsBackToLocalFirst) {
+    auto config =
+        MasterServiceConfig::builder()
+            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
+            .build();
+    MasterScenario("a full preferred node falls back to local-first",
+                   std::move(config))
+        .Given(MemoryNode("node-host0").OnHost("host0").Capacity(1024))
+        .Given(MemoryNode("node-host1").OnHost("host1"))
+        .When(PutStart("fill_preferred", 1_KB)
+                  .FromHost("host1")
+                  .OnNode("node-host0")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host0"}))
+        .When(PutEnd("fill_preferred"))
+        .When(PutStart("fallback_after_preferred_full", 1)
+                  .FromHost("host1")
+                  .OnNode("node-host0")
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"node-host1"}));
+}
+
+TEST(MasterServicePlacementScenarioTest, SingleSliceMultiReplicaFlow) {
+    constexpr uint64_t kNodeCapacity = 64 * 1024 * 1024;
+    constexpr uint64_t kObjectSize = 5 * 1024 * 1024;
+    MasterScenario scenario("a multi-replica object completes on every node");
+    scenario.Given(MemoryNode("node-0").Capacity(kNodeCapacity))
+        .Given(MemoryNode("node-1").Capacity(kNodeCapacity))
+        .Given(MemoryNode("node-2").Capacity(kNodeCapacity))
+        .When(PutStart("multi_slice_object", kObjectSize)
+                  .Replicas(3)
+                  .ExpectReplicas(3)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .Then(Object("multi_slice_object").IsNotReady())
+        .When(PutEnd("multi_slice_object"))
+        .Then(Object("multi_slice_object")
+                  .IsReadable()
+                  .HasReplicas(3)
+                  .HasCompleteReplicas(3)
+                  .HasMemoryReplicaSize(kObjectSize));
+}
+
+TEST(MasterServicePlacementScenarioTest, ReplicaSegmentsAreUnique) {
+    constexpr uint64_t kObjectSize = 1024 * 1024 - 16;
+    constexpr size_t kReplicaCount = 10;
+    MasterScenario scenario("replicas of one object land on distinct nodes");
+    for (size_t index = 0; index < 20; ++index) {
+        scenario.Given(MemoryNode("node-" + std::to_string(index)));
+    }
+    scenario
+        .When(PutStart("replica_uniqueness_key", kObjectSize)
+                  .Replicas(kReplicaCount)
+                  .ExpectReplicas(kReplicaCount)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .When(PutEnd("replica_uniqueness_key"))
+        .Then(Object("replica_uniqueness_key")
+                  .IsReadable()
+                  .HasCompleteReplicas(kReplicaCount)
+                  .HasDistinctMemoryNodes()
+                  .HasMemoryReplicaSize(kObjectSize));
+}
+
+TEST(MasterServicePlacementScenarioTest, ReplicationFactorTwoWithSingleNode) {
+    MasterScenario("best-effort allocation degrades to the only node")
+        .Given(MemoryNode("single-node"))
+        .When(PutStart("replication_factor_two", 1_KB)
+                  .Replicas(2)
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"single-node"}))
+        .When(PutEnd("replication_factor_two"))
+        .Then(Object("replication_factor_two")
+                  .IsReadable()
+                  .HasCompleteReplicas(1)
+                  .IsOnMemoryNode("single-node")
+                  .HasMemoryReplicaSize(1_KB));
+}
+
+TEST(MasterServicePlacementScenarioTest, PutStartPartialAllocationIsVisible) {
+    MasterScenario("best-effort allocation reports the degraded replica count")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("partial_alloc_key", 1_KB)
+                  .Replicas(3)
+                  .ExpectReplicas(2)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .When(PutEnd("partial_alloc_key"))
+        .Then(Object("partial_alloc_key")
+                  .IsReadable()
+                  .HasCompleteReplicas(2)
+                  .HasDistinctMemoryNodes())
+        .When(PutStart("full_alloc_key", 1_KB).Replicas(2).ExpectReplicas(2))
+        .When(PutEnd("full_alloc_key"))
+        .Then(Object("full_alloc_key").IsReadable().HasCompleteReplicas(2));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_processing_key_double_erase_test.cpp b/mooncake-store/tests/master_service_processing_key_double_erase_test.cpp
index 186e260bfa..c9337e11a8 100644
--- a/mooncake-store/tests/master_service_processing_key_double_erase_test.cpp
+++ b/mooncake-store/tests/master_service_processing_key_double_erase_test.cpp
@@ -26,7 +26,7 @@
 // dereferences nullptr -> SIGSEGV (fault address 0x0, exactly as observed in
 // the prod kernel logs).
 //
-// Production trigger chain reproduced here (public API + one friend hook):
+// Production trigger chain reproduced here (public API + test peer):
 //   1. MountSegment                     (a "ghost" client mounts a segment)
 //   2. PutStart without PutEnd          (key stays in processing_keys with an
 //                                        incomplete replica on that segment)
@@ -55,6 +55,7 @@
 // simply reports OBJECT_NOT_FOUND) and the test passes.
 
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
@@ -86,17 +87,17 @@ class MasterServiceProcessingKeyDoubleEraseTest : public ::testing::Test {
     static constexpr int kExitUnmountFailed = 4;   // scenario setup broken
 
     // Friend access: find a key that routes to the SAME metadata shard as
-    // `key` (getMetadataShardIndex hashes tenant+key, so a naive second key
+    // `key` (getShardIndex hashes tenant+key, so a naive second key
     // lands in a different shard's TenantState and cannot keep THIS shard's
     // tenant non-empty).
     std::string FindKeyOnSameShard(MasterService& service,
                                    const std::string& key) {
-        const size_t target =
-            service.getMetadataShardIndex(TenantId::Default(), key);
+        const size_t target = MasterServiceTestPeer(service).getShardIndex(
+            TenantId::Default(), key);
         for (int i = 0; i < 100000; ++i) {
             std::string candidate = key + "_keepalive_" + std::to_string(i);
-            if (service.getMetadataShardIndex(TenantId::Default(), candidate) ==
-                target) {
+            if (MasterServiceTestPeer(service).getShardIndex(
+                    TenantId::Default(), candidate) == target) {
                 return candidate;
             }
         }
@@ -151,7 +152,8 @@ class MasterServiceProcessingKeyDoubleEraseTest : public ::testing::Test {
         //    No ClearInvalidHandles sweep here (see file header).
         size_t metrics_dec_capacity = 0;
         {
-            auto segment_access = service.segment_manager_.getSegmentAccess();
+            auto segment_access = MasterServiceTestPeer::SegmentManager(service)
+                                      .getSegmentAccess();
             if (segment_access.PrepareUnmountSegment(
                     segment.id, metrics_dec_capacity) != ErrorCode::OK) {
                 ::_exit(kExitUnmountFailed);
diff --git a/mooncake-store/tests/master_service_replication_scenario_test.cpp b/mooncake-store/tests/master_service_replication_scenario_test.cpp
new file mode 100644
index 0000000000..41c85af131
--- /dev/null
+++ b/mooncake-store/tests/master_service_replication_scenario_test.cpp
@@ -0,0 +1,453 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+std::chrono::system_clock::time_point ExpiredLease() {
+    return std::chrono::system_clock::now() - std::chrono::seconds(1);
+}
+
+}  // namespace
+
+TEST(MasterServiceReplicationScenarioTest, CopyStart) {
+    MasterScenario("copy start validates inputs and allocates free targets")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .Given(MemoryNode("node-3"))
+        .Given(MemoryNode("node-4"))
+        .When(CopyStart("missing_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2"})
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("copy_key", 1_KB).OnNode("node-1"))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2", "node-3"})
+                  .ExpectError(ErrorCode::REPLICA_NOT_FOUND))
+        .When(PutEnd("copy_key"))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2", "node-3"})
+                  .ExpectAllocatedTargets({"node-2", "node-3"}))
+        .When(Remove("copy_key").ExpectError(ErrorCode::REPLICA_IS_NOT_READY))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-4"})
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK))
+        .When(CopyEnd("copy_key").By("node-1"))
+        .Then(Object("copy_key").IsReadable().HasReplicas(3))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("ghost-node")
+                  .To({"node-3", "node-4"})
+                  .ExpectError(ErrorCode::REPLICA_NOT_FOUND))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-4", "ghost-node"})
+                  .ExpectError(ErrorCode::SEGMENT_NOT_FOUND))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-3", "node-4"})
+                  .ExpectAllocatedTargets({"node-4"}))
+        .When(CopyEnd("copy_key").By("node-1"))
+        .Then(Object("copy_key").IsReadable().HasReplicas(4))
+        .When(CopyStart("copy_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-4"})
+                  .ExpectAllocatedTargets({}))
+        .When(ExpireAt("copy_key", ExpiredLease()))
+        .When(Remove("copy_key")
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK))
+        .When(CopyEnd("copy_key").By("node-1"))
+        .When(ExpireAt("copy_key", ExpiredLease()))
+        .When(Remove("copy_key"))
+        .Then(Object("copy_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, CopyEnd) {
+    MasterScenario("copy end commits targets and reports vanished replicas")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .Given(MemoryNode("node-3"))
+        .When(CopyEnd("missing_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("copy_end_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("copy_end_key"))
+        .When(CopyEnd("copy_end_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NO_REPLICATION_TASK))
+        .When(CopyStart("copy_end_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2"}))
+        .When(CopyEnd("copy_end_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(MoveEnd("copy_end_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CopyEnd("copy_end_key").By("node-1"))
+        .Then(Object("copy_end_key").IsReadable().HasReplicas(2))
+        .When(CopyStart("copy_end_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-3"}))
+        .When(UnmountMemoryNode("node-1"))
+        .When(CopyEnd("copy_end_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::REPLICA_IS_GONE))
+        .Then(Object("copy_end_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-2"))
+        .When(CopyStart("copy_end_key")
+                  .By("node-2")
+                  .From("node-2")
+                  .To({"node-3"}))
+        .When(UnmountMemoryNode("node-3"))
+        .When(CopyEnd("copy_end_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::REPLICA_IS_GONE))
+        .Then(Object("copy_end_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-2"));
+}
+
+TEST(MasterServiceReplicationScenarioTest, CopyRevoke) {
+    MasterScenario("copy revoke discards the pending copy")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(CopyRevoke("missing_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("copy_revoke_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("copy_revoke_key"))
+        .When(CopyRevoke("copy_revoke_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NO_REPLICATION_TASK))
+        .When(CopyStart("copy_revoke_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2"}))
+        .When(CopyRevoke("copy_revoke_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(MoveRevoke("copy_revoke_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CopyRevoke("copy_revoke_key").By("node-1"))
+        .Then(Object("copy_revoke_key").IsReadable().HasReplicas(1))
+        .When(CopyStart("copy_revoke_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To({"node-2"}))
+        .When(UnmountMemoryNode("node-1"))
+        .When(CopyRevoke("copy_revoke_key").By("node-1"))
+        .Then(Object("copy_revoke_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, MoveStart) {
+    MasterScenario("move start validates inputs and allocates the target")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .Given(MemoryNode("node-3"))
+        .When(MoveStart("missing_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("move_key", 1_KB).OnNode("node-1"))
+        .When(MoveStart("move_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2")
+                  .ExpectError(ErrorCode::REPLICA_NOT_FOUND))
+        .When(PutEnd("move_key"))
+        .When(CopyStart("move_key").By("node-1").From("node-1").To({"node-3"}))
+        .When(CopyEnd("move_key").By("node-1"))
+        .When(MoveStart("move_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(MoveStart("move_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2")
+                  .ExpectTargetAllocation())
+        .When(Remove("move_key").ExpectError(ErrorCode::REPLICA_IS_NOT_READY))
+        .When(MoveStart("move_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-3")
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK))
+        .When(MoveEnd("move_key").By("node-1"))
+        .Then(Object("move_key")
+                  .IsReadable()
+                  .HasReplicas(2)
+                  .HasMemoryNodes({"node-2", "node-3"}))
+        .When(MoveStart("move_key")
+                  .By("node-2")
+                  .From("ghost-node")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::REPLICA_NOT_FOUND))
+        .When(MoveStart("move_key")
+                  .By("node-2")
+                  .From("node-2")
+                  .To("ghost-node")
+                  .ExpectError(ErrorCode::SEGMENT_NOT_FOUND))
+        .When(MoveStart("move_key")
+                  .By("node-2")
+                  .From("node-2")
+                  .To("node-3")
+                  .ExpectNoTargetAllocation())
+        .When(ExpireAt("move_key", ExpiredLease()))
+        .When(Remove("move_key")
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK))
+        .When(MoveEnd("move_key").By("node-2"))
+        .Then(Object("move_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-3"))
+        .When(ExpireAt("move_key", ExpiredLease()))
+        .When(Remove("move_key"))
+        .Then(Object("move_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, MoveEnd) {
+    MasterScenario("move end commits the move and reports a vanished source")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(MoveEnd("missing_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("move_end_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("move_end_key"))
+        .When(MoveEnd("move_end_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NO_REPLICATION_TASK))
+        .When(
+            MoveStart("move_end_key").By("node-1").From("node-1").To("node-2"))
+        .When(MoveEnd("move_end_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(CopyEnd("move_end_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(MoveEnd("move_end_key").By("node-1"))
+        .Then(Object("move_end_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-2"))
+        .When(
+            MoveStart("move_end_key").By("node-2").From("node-2").To("node-1"))
+        .When(UnmountMemoryNode("node-2"))
+        .When(MoveEnd("move_end_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::REPLICA_IS_GONE));
+}
+
+TEST(MasterServiceReplicationScenarioTest,
+     MoveEndWithVanishedTargetReleasesSource) {
+    MasterScenario("a vanished move target fails move end and frees the source")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("target_gone_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("target_gone_key"))
+        .When(MoveStart("target_gone_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2"))
+        .When(UnmountMemoryNode("node-2"))
+        .When(MoveEnd("target_gone_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::REPLICA_IS_GONE))
+        .When(UpsertStart("target_gone_key", 1_KB).By("node-1"))
+        .When(MoveRevoke("target_gone_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NO_REPLICATION_TASK))
+        .When(UpsertRevoke("target_gone_key").By("node-1"));
+}
+
+TEST(MasterServiceReplicationScenarioTest, MoveRevoke) {
+    MasterScenario("move revoke restores the source replica")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(MoveRevoke("missing_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(PutStart("move_revoke_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("move_revoke_key"))
+        .When(MoveRevoke("move_revoke_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NO_REPLICATION_TASK))
+        .When(MoveStart("move_revoke_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2"))
+        .When(MoveRevoke("move_revoke_key")
+                  .By("node-2")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(CopyRevoke("move_revoke_key")
+                  .By("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(MoveRevoke("move_revoke_key").By("node-1"))
+        .Then(Object("move_revoke_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-1"))
+        .When(MoveStart("move_revoke_key")
+                  .By("node-1")
+                  .From("node-1")
+                  .To("node-2"))
+        .When(UnmountMemoryNode("node-1"))
+        .When(MoveRevoke("move_revoke_key").By("node-1"))
+        .Then(Object("move_revoke_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest,
+     ReadableAfterPartialUnmountWithReplication) {
+    constexpr uint64_t kNodeCapacity = 64 * 1024 * 1024;
+    constexpr uint64_t kObjectSize = 1024 * 1024;
+    MasterScenario("a replicated object survives losing one node")
+        .Given(MemoryNode("node-1").Capacity(kNodeCapacity))
+        .Given(MemoryNode("node-2").Capacity(kNodeCapacity))
+        .When(PutStart("replicated_key", kObjectSize)
+                  .Replicas(2)
+                  .ExpectReplicas(2))
+        .When(PutEnd("replicated_key"))
+        .Then(Object("replicated_key")
+                  .IsReadable()
+                  .HasCompleteReplicas(2)
+                  .HasDistinctMemoryNodes()
+                  .HasMemoryReplicaSize(kObjectSize))
+        .When(UnmountMemoryNode("node-1"))
+        .Then(Object("replicated_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("node-2"));
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasAcrossAllNodes) {
+    MasterScenario scenario("expired objects are cleared across all nodes");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 5)
+                   .NamedBy([](size_t index) {
+                       return "batch_clear_key_" + std::to_string(index);
+                   })
+                   .Size(1_KB)
+                   .CompleteOn("memory"));
+    for (size_t index = 0; index < 5; ++index) {
+        scenario.Then(KeyExists("batch_clear_key_" + std::to_string(index)));
+        scenario.When(ExpireAt("batch_clear_key_" + std::to_string(index),
+                               ExpiredLease()));
+    }
+    scenario
+        .When(ClearReplicas({"batch_clear_key_0", "batch_clear_key_1",
+                             "batch_clear_key_2", "batch_clear_key_3",
+                             "batch_clear_key_4"})
+                  .ExpectCleared({"batch_clear_key_0", "batch_clear_key_1",
+                                  "batch_clear_key_2", "batch_clear_key_3",
+                                  "batch_clear_key_4"}))
+        .Then(Objects(0, 5)
+                  .NamedBy([](size_t index) {
+                      return "batch_clear_key_" + std::to_string(index);
+                  })
+                  .DoNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasOnSpecificNode) {
+    MasterScenario("an expired object is cleared from its node")
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("node_specific_key", 1_KB).OnNode("node-1"))
+        .When(PutEnd("node_specific_key"))
+        .When(ExpireAt("node_specific_key", ExpiredLease()))
+        .When(ClearReplicas({"node_specific_key"})
+                  .FromNode("node-1")
+                  .ExpectCleared({"node_specific_key"}))
+        .Then(Object("node_specific_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasSkipsLeasedObjects) {
+    MasterScenario("a leased object is not cleared")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("lease_active_key", 1_KB))
+        .When(PutEnd("lease_active_key"))
+        .Then(KeyExists("lease_active_key"))
+        .When(ClearReplicas({"lease_active_key"}).ExpectCleared({}))
+        .Then(KeyExists("lease_active_key"));
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasSkipsForeignObjects) {
+    MasterScenario("another client's object is not cleared")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("client_specific_key", 1_KB).By("writer"))
+        .When(PutEnd("client_specific_key").By("writer"))
+        .When(ExpireAt("client_specific_key", ExpiredLease()))
+        .When(ClearReplicas({"client_specific_key"})
+                  .By("other-client")
+                  .ExpectCleared({}))
+        .Then(KeyExists("client_specific_key"));
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasSkipsMissingKeys) {
+    MasterScenario("missing keys clear nothing")
+        .Given(MemoryNode("memory"))
+        .When(ClearReplicas({"missing_key_1", "missing_key_2"})
+                  .ExpectCleared({}));
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasWithNoKeys) {
+    MasterScenario("an empty key list clears nothing")
+        .Given(MemoryNode("memory"))
+        .When(ClearReplicas({}).ExpectCleared({}));
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasSkipsEmptyKeys) {
+    MasterScenario("empty-string keys are skipped")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("valid_key", 1_KB))
+        .When(PutEnd("valid_key"))
+        .When(ExpireAt("valid_key", ExpiredLease()))
+        .When(ClearReplicas({"", "valid_key", "", "another_empty"})
+                  .ExpectCleared({"valid_key"}))
+        .Then(Object("valid_key").DoesNotExist());
+}
+
+TEST(MasterServiceReplicationScenarioTest, ClearReplicasMixedOwnership) {
+    MasterScenario("only the caller's expired keys are cleared")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("mixed_key1", 1_KB).By("client-1"))
+        .When(PutEnd("mixed_key1").By("client-1"))
+        .When(PutStart("mixed_key2", 1_KB).By("client-1"))
+        .When(PutEnd("mixed_key2").By("client-1"))
+        .When(PutStart("mixed_key3", 1_KB).By("client-2"))
+        .When(PutEnd("mixed_key3").By("client-2"))
+        .When(ExpireAt("mixed_key1", ExpiredLease()))
+        .When(ExpireAt("mixed_key2", ExpiredLease()))
+        .When(ExpireAt("mixed_key3", ExpiredLease()))
+        .When(ClearReplicas({"mixed_key1", "mixed_key2", "mixed_key3",
+                             "non_existent", ""})
+                  .By("client-1")
+                  .ExpectCleared({"mixed_key1", "mixed_key2"}))
+        .Then(Object("mixed_key1").DoesNotExist())
+        .Then(Object("mixed_key2").DoesNotExist())
+        .Then(KeyExists("mixed_key3"));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_scenario_test.cpp b/mooncake-store/tests/master_service_scenario_test.cpp
index ba342bf151..3556b0e6b6 100644
--- a/mooncake-store/tests/master_service_scenario_test.cpp
+++ b/mooncake-store/tests/master_service_scenario_test.cpp
@@ -1,4 +1,8 @@
-#include "master_scenario.h"
+#include "master_service/dsl/scenario.h"
+
+#include <array>
+#include <chrono>
+#include <string>
 
 #include <gtest/gtest.h>
 
@@ -26,4 +30,532 @@ TEST(MasterServiceTest, PutStartEndFlow) {
                   .HasCompleteReplicas(1));
 }
 
+TEST(MasterServiceTest, PutLifecycleForEveryReplicaCount) {
+    constexpr std::array<size_t, 5> kReplicaCounts{1, 2, 3, 4, 5};
+    MasterScenario scenario(
+        "put lifecycle for replica counts one through five");
+    for (size_t index : kReplicaCounts) {
+        scenario.Given(MemoryNode("memory-" + std::to_string(index)));
+    }
+    for (size_t replica_count : kReplicaCounts) {
+        const std::string key = "key-" + std::to_string(replica_count);
+        scenario
+            .When(PutStart(key, 1_KB)
+                      .Replicas(replica_count)
+                      .ExpectReplicas(replica_count)
+                      .ExpectStatus(ReplicaStatus::PROCESSING))
+            .Then(Object(key).IsNotReady())
+            .When(Remove(key).ExpectError(ErrorCode::REPLICA_IS_NOT_READY))
+            .When(PutEnd(key))
+            .Then(Object(key)
+                      .IsReadable()
+                      .HasReplicas(replica_count)
+                      .HasCompleteReplicas(replica_count));
+    }
+}
+
+TEST(MasterServiceTest, GetReplicaListDistinguishesMissingAndReadable) {
+    MasterScenario("get replica list distinguishes missing and readable")
+        .Given(MemoryNode("memory"))
+        .Then(Object("missing").DoesNotExist())
+        .When(PutStart("key", 1_KB))
+        .When(PutEnd("key"))
+        .Then(Object("key").IsReadable().HasReplicas(1));
+}
+
+TEST(MasterServiceTest, RemoveObjectAndRejectMissingObject) {
+    MasterScenario("remove object and reject a missing object")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("key", 1_KB))
+        .When(PutEnd("key"))
+        .When(Remove("key"))
+        .Then(Object("key").DoesNotExist())
+        .When(Remove("missing").ExpectError(ErrorCode::OBJECT_NOT_FOUND));
+}
+
+TEST(MasterServiceTest, RepeatedPutAndRemoveIsDeterministic) {
+    MasterScenario scenario("repeated put and remove with fixed keys");
+    scenario.Given(MemoryNode("memory"));
+    for (int index = 0; index < 10; ++index) {
+        const std::string key = "key-" + std::to_string(index);
+        scenario.When(PutStart(key, 1_KB))
+            .When(PutEnd(key))
+            .When(Remove(key))
+            .Then(Object(key).DoesNotExist());
+    }
+}
+
+TEST(MasterServiceTest, UpsertNewKey) {
+    MasterScenario("upsert creates a new object")
+        .Given(MemoryNode("memory"))
+        .When(UpsertStart("upsert_new_key", 1_KB)
+                  .By("writer")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .Then(Object("upsert_new_key").IsNotReady())
+        .When(UpsertEnd("upsert_new_key").By("writer"))
+        .Then(Object("upsert_new_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertPreemptsInProgressPut) {
+    MasterScenario("upsert preempts an in-progress put")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_preempt", 1_KB).By("old-writer"))
+        .When(UpsertStart("upsert_preempt", 1_KB)
+                  .By("new-writer")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .When(PutEnd("upsert_preempt")
+                  .By("old-writer")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(UpsertEnd("upsert_preempt").By("new-writer"))
+        .Then(Object("upsert_preempt")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertSameSizeRefreshesMetadata) {
+    MasterScenario("same-size upsert refreshes writer identity")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_refresh_metadata", 1_KB).By("old-writer"))
+        .When(PutEnd("upsert_refresh_metadata").By("old-writer"))
+        .When(UpsertStart("upsert_refresh_metadata", 1_KB).By("new-writer"))
+        .When(UpsertEnd("upsert_refresh_metadata")
+                  .By("old-writer")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(UpsertEnd("upsert_refresh_metadata").By("new-writer"))
+        .Then(Object("upsert_refresh_metadata")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertRevoke) {
+    MasterScenario("revoke a new-key upsert")
+        .Given(MemoryNode("memory"))
+        .When(UpsertStart("upsert_revoke", 1_KB).By("writer"))
+        .Then(Object("upsert_revoke").IsNotReady())
+        .When(UpsertRevoke("upsert_revoke").By("writer"))
+        .Then(Object("upsert_revoke").DoesNotExist());
+}
+
+TEST(MasterServiceTest, UpsertInPlaceThenRevoke) {
+    MasterScenario("revoke an in-place upsert")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_inplace_revoke", 1_KB).By("old-writer"))
+        .When(PutEnd("upsert_inplace_revoke").By("old-writer"))
+        .When(UpsertStart("upsert_inplace_revoke", 1_KB).By("new-writer"))
+        .Then(Object("upsert_inplace_revoke").IsNotReady())
+        .When(UpsertRevoke("upsert_inplace_revoke").By("new-writer"))
+        .Then(Object("upsert_inplace_revoke").DoesNotExist());
+}
+
+TEST(MasterServiceTest, UpsertPreemptsInProgressUpsert) {
+    MasterScenario("upsert preempts an in-progress upsert")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_preempt_upsert", 1_KB).By("first-writer"))
+        .When(PutEnd("upsert_preempt_upsert").By("first-writer"))
+        .When(
+            UpsertStart("upsert_preempt_upsert", 1_KB).By("old-upsert-writer"))
+        .Then(Object("upsert_preempt_upsert").IsNotReady())
+        .When(UpsertStart("upsert_preempt_upsert", 1_KB)
+                  .By("new-upsert-writer")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .When(UpsertEnd("upsert_preempt_upsert")
+                  .By("old-upsert-writer")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT))
+        .When(UpsertEnd("upsert_preempt_upsert").By("new-upsert-writer"))
+        .Then(Object("upsert_preempt_upsert")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertDifferentSizeThenRevoke) {
+    MasterScenario("revoke a different-size upsert")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_diff_revoke", 1_KB).By("writer"))
+        .When(PutEnd("upsert_diff_revoke").By("writer"))
+        .Then(Object("upsert_diff_revoke")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .HasCompleteReplicas(1))
+        .When(UpsertStart("upsert_diff_revoke", 2_KB)
+                  .By("writer")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING))
+        .Then(Object("upsert_diff_revoke").IsNotReady())
+        .When(UpsertRevoke("upsert_diff_revoke").By("writer"))
+        .Then(Object("upsert_diff_revoke").DoesNotExist());
+}
+
+TEST(MasterServiceTest, PutStartInvalidParams) {
+    MasterScenario("put start rejects invalid parameters")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("test_key", 1_KB)
+                  .Replicas(0)
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("test_key", 0).ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("test_key", 1_KB)
+                  .NofReplicas(1)
+                  .PreferSameNode()
+                  .ExpectError(ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceTest, ObjectChecksumIsStoredAndClearedByUpsert) {
+    MasterScenario("object checksum is stored and cleared by upsert")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("checksum_key", 1_KB))
+        .When(PutEnd("checksum_key").WithChecksum(0))
+        .Then(Object("checksum_key").IsReadable().HasChecksum(0))
+        .When(UpsertStart("checksum_key", 1_KB))
+        .When(UpsertEnd("checksum_key"))
+        .Then(Object("checksum_key").IsReadable().HasNoChecksum());
+}
+
+TEST(MasterServiceTest, UpsertSameSizeReusesBuffer) {
+    MasterScenario("same-size upsert reuses the existing buffer")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_same_size", 1_KB).By("writer"))
+        .When(PutEnd("upsert_same_size").By("writer"))
+        .When(UpsertStart("upsert_same_size", 1_KB)
+                  .By("new-writer")
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING)
+                  .ExpectBufferReuse())
+        .When(UpsertEnd("upsert_same_size").By("new-writer"))
+        .Then(Object("upsert_same_size").IsReadable().HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertDifferentSizeAllocatesNewBuffer) {
+    MasterScenario("different-size upsert allocates a new buffer")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("upsert_diff_size", 1_KB))
+        .When(PutEnd("upsert_diff_size"))
+        .When(UpsertStart("upsert_diff_size", 2_KB)
+                  .ExpectReplicas(1)
+                  .ExpectStatus(ReplicaStatus::PROCESSING)
+                  .ExpectNewBuffer())
+        .When(UpsertEnd("upsert_diff_size"))
+        .Then(Object("upsert_diff_size").IsReadable().HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, UpsertConflictReplicationTask) {
+    MasterScenario("upsert fails while a copy is in progress")
+        .Given(MemoryNode("node-a"))
+        .Given(MemoryNode("node-b"))
+        .When(PutStart("upsert_conflict_copy", 1_KB).OnNode("node-a"))
+        .When(PutEnd("upsert_conflict_copy"))
+        .When(CopyStart("upsert_conflict_copy")
+                  .By("node-a")
+                  .From("node-a")
+                  .To({"node-b"}))
+        .When(UpsertStart("upsert_conflict_copy", 1_KB)
+                  .ExpectError(ErrorCode::OBJECT_HAS_REPLICATION_TASK));
+}
+
+TEST(MasterServiceTest, BatchUpsertStartMixesNewAndExistingKeys) {
+    MasterScenario("batch upsert start handles new and existing keys")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("key_1", 1_KB))
+        .When(PutEnd("key_1"))
+        .When(BatchUpsertStart({{"key_1", 1_KB}, {"key_2", 2_KB}}))
+        .When(BatchUpsertEnd({"key_1", "key_2"}))
+        .Then(Object("key_1").IsReadable().HasCompleteReplicas(1))
+        .Then(Object("key_2").IsReadable().HasCompleteReplicas(1));
+}
+
+TEST(MasterServiceTest, RemoveAllRemovesEveryObject) {
+    MasterScenario scenario("remove all removes every completed object");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10)
+                   .NamedBy([](size_t index) {
+                       return "test_key" + std::to_string(index);
+                   })
+                   .Size(1_KB)
+                   .CompleteOn("memory"))
+        .When(RemoveAll().ExpectRemoved(10))
+        .Then(Objects(0, 10)
+                  .NamedBy([](size_t index) {
+                      return "test_key" + std::to_string(index);
+                  })
+                  .DoNotExist());
+}
+
+TEST(MasterServiceTest, RemoveAllSkipsLeasedObjects) {
+    const auto expired =
+        std::chrono::system_clock::now() - std::chrono::seconds(1);
+    const auto name = [](size_t index) {
+        return "test_key" + std::to_string(index);
+    };
+    MasterScenario scenario("remove all skips leased objects");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10).NamedBy(name).Size(1_KB).CompleteOn("memory"));
+    for (size_t index = 5; index < 10; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.When(RemoveAll().ExpectRemoved(5))
+        .Then(Objects(0, 5).NamedBy(name).DoNotExist());
+    for (size_t index = 5; index < 10; ++index) {
+        scenario.When(ExpireAt(name(index), expired));
+    }
+    scenario.When(RemoveAll().ExpectRemoved(5))
+        .Then(Objects(5, 10).NamedBy(name).DoNotExist());
+}
+
+TEST(MasterServiceTest, RemoveLeasedObject) {
+    const auto expired =
+        std::chrono::system_clock::now() - std::chrono::seconds(1);
+    MasterScenario("reads grant and extend leases that block remove")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("test_key", 1_KB))
+        .When(PutEnd("test_key"))
+        .Then(KeyExists("test_key"))
+        .When(Remove("test_key").ExpectError(ErrorCode::OBJECT_HAS_LEASE))
+        .When(ExpireAt("test_key", expired))
+        .Then(KeyExists("test_key"))
+        .When(Remove("test_key").ExpectError(ErrorCode::OBJECT_HAS_LEASE))
+        .When(ExpireAt("test_key", expired))
+        .When(Remove("test_key"))
+        .When(PutStart("test_key", 1_KB))
+        .When(PutEnd("test_key"))
+        .Then(Object("test_key").IsReadable())
+        .When(Remove("test_key").ExpectError(ErrorCode::OBJECT_HAS_LEASE))
+        .When(ExpireAt("test_key", expired))
+        .Then(Object("test_key").IsReadable())
+        .When(Remove("test_key").ExpectError(ErrorCode::OBJECT_HAS_LEASE))
+        .When(ExpireAt("test_key", expired))
+        .When(Remove("test_key"))
+        .Then(Object("test_key").DoesNotExist());
+}
+
+TEST(MasterServiceTest, ForceRemoveLeasedObject) {
+    MasterScenario("force remove bypasses an active lease")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("leased_key", 1_KB))
+        .When(PutEnd("leased_key"))
+        .Then(KeyExists("leased_key"))
+        .When(Remove("leased_key").ExpectError(ErrorCode::OBJECT_HAS_LEASE))
+        .When(Remove("leased_key").Force())
+        .Then(Object("leased_key").DoesNotExist());
+}
+
+TEST(MasterServiceTest, ForceRemoveByRegexLeasedObjects) {
+    const auto name = [](size_t index) {
+        return "force_regex_key_" + std::to_string(index);
+    };
+    MasterScenario scenario("force remove by regex bypasses active leases");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 5).NamedBy(name).Size(1_KB).CompleteOn("memory"));
+    for (size_t index = 0; index < 5; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.When(RemoveByRegex("^force_regex_key_").ExpectRemoved(0));
+    for (size_t index = 0; index < 5; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.When(RemoveByRegex("^force_regex_key_").Force().ExpectRemoved(5))
+        .Then(Objects(0, 5).NamedBy(name).DoNotExist());
+}
+
+TEST(MasterServiceTest, ForceRemoveAllLeasedObjects) {
+    const auto name = [](size_t index) {
+        return "force_all_key_" + std::to_string(index);
+    };
+    MasterScenario scenario("force remove all bypasses active leases");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10).NamedBy(name).Size(1_KB).CompleteOn("memory"));
+    for (size_t index = 0; index < 10; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.When(RemoveAll().ExpectRemoved(0));
+    for (size_t index = 0; index < 10; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.When(RemoveAll().Force().ExpectRemoved(10))
+        .Then(Objects(0, 10).NamedBy(name).DoNotExist());
+}
+
+TEST(MasterServiceTest, GetReplicaListByRegex) {
+    MasterScenario scenario("get replica list by regex matches completed keys");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10)
+                   .NamedBy([](size_t index) {
+                       return "test_key" + std::to_string(index);
+                   })
+                   .Size(1_KB)
+                   .CompleteOn("memory"))
+        .Then(Object("non_existent_key").DoesNotExist())
+        .Then(MatchingKeys("^test_key").HasCount(10));
+}
+
+TEST(MasterServiceTest, GetReplicaListByRegexComplex) {
+    MasterScenario("get replica list by regex handles complex patterns")
+        .Given(MemoryNode("memory"))
+        .Given(
+            Objects({"test_key_01", "test_key_02", "test_key_10",
+                     "prod_key_alpha", "prod_key_beta", "data_part_1_chunk_a",
+                     "data_part_2_chunk_b", "config/user/settings.json",
+                     "logs/app-2025-08-13.log", "short",
+                     "a_very_very_very_long_key_that_tests_length_limits",
+                     "test-key-extra", "another_key"})
+                .Size(1_KB)
+                .CompleteOn("memory"))
+        .Then(MatchingKeys("^test_key_").HasCount(3))
+        .Then(MatchingKeys("^test_key_\\d+$").HasCount(3))
+        .Then(MatchingKeys("^data_part_\\d_chunk_.$").HasCount(2))
+        .Then(MatchingKeys("key").HasCount(8))
+        .Then(MatchingKeys("\\.log$").HasCount(1).HasKeys(
+            {"logs/app-2025-08-13.log"}))
+        .Then(MatchingKeys("^prod|\\.json$").HasCount(3))
+        .Then(MatchingKeys("^non_existent_prefix_").HasCount(0))
+        .Then(MatchingKeys("^short$").HasCount(1).HasKeys({"short"}))
+        .Then(MatchingKeys(".*absolutely_non_existent.*").HasCount(0));
+}
+
+TEST(MasterServiceTest, RemoveByRegex) {
+    const auto name = [](size_t index) {
+        return "test_key" + std::to_string(index);
+    };
+    MasterScenario scenario("remove by regex removes matching keys");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10).NamedBy(name).Size(1_KB).CompleteOn("memory"))
+        .When(RemoveByRegex("^test_key").ExpectRemoved(10))
+        .Then(Objects(0, 10).NamedBy(name).DoNotExist());
+}
+
+TEST(MasterServiceTest, RemoveByRegexComplex) {
+    const auto keys = [] {
+        return Objects({"test_key_01", "test_key_02", "test_key_10",
+                        "prod_key_alpha", "prod_key_beta",
+                        "data_part_1_chunk_a", "data_part_2_chunk_b",
+                        "config/user/settings.json", "logs/app-2025-08-13.log",
+                        "short",
+                        "a_very_very_very_long_key_that_tests_length_limits",
+                        "test-key-extra", "another_key"})
+            .Size(1_KB)
+            .CompleteOn("memory");
+    };
+
+    MasterScenario("remove by regex removes a prefix subset")
+        .Given(MemoryNode("memory"))
+        .Given(keys())
+        .When(RemoveByRegex("^test_key_").ExpectRemoved(3))
+        .Then(
+            Objects({"test_key_01", "test_key_02", "test_key_10"}).DoNotExist())
+        .Then(KeyExists("prod_key_alpha"))
+        .Then(KeyExists("short"))
+        .Then(KeyExists("test-key-extra"));
+
+    MasterScenario("remove by regex removes everything with a wildcard")
+        .Given(MemoryNode("memory"))
+        .Given(keys())
+        .When(RemoveByRegex(".*").ExpectRemoved(13))
+        .Then(MatchingKeys(".*").HasCount(0));
+
+    MasterScenario(
+        "remove by regex with a non-matching pattern removes nothing")
+        .Given(MemoryNode("memory"))
+        .Given(keys())
+        .When(RemoveByRegex("^nonexistent-pattern-").ExpectRemoved(0))
+        .Then(MatchingKeys(".*").HasCount(13));
+
+    MasterScenario("remove by regex handles alternation patterns")
+        .Given(MemoryNode("memory"))
+        .Given(keys())
+        .When(RemoveByRegex("chunk|config").ExpectRemoved(3))
+        .Then(Objects({"data_part_1_chunk_a", "data_part_2_chunk_b",
+                       "config/user/settings.json"})
+                  .DoNotExist())
+        .Then(KeyExists("prod_key_alpha"));
+
+    MasterScenario("remove by regex combines path and trailing-digit matches")
+        .Given(MemoryNode("memory"))
+        .Given(keys())
+        .When(RemoveByRegex("/|\\d$").ExpectRemoved(5))
+        .Then(Objects({"test_key_01", "test_key_02", "test_key_10",
+                       "config/user/settings.json", "logs/app-2025-08-13.log"})
+                  .DoNotExist())
+        .Then(MatchingKeys(".*").HasCount(8).HasKeys(
+            {"prod_key_alpha", "prod_key_beta", "data_part_1_chunk_a",
+             "data_part_2_chunk_b", "short",
+             "a_very_very_very_long_key_that_tests_length_limits",
+             "test-key-extra", "another_key"}));
+}
+
+TEST(MasterServiceTest, BatchExistKey) {
+    const auto name = [](size_t index) {
+        return "test_key" + std::to_string(index);
+    };
+    MasterScenario scenario(
+        "batch exist key reports completed and missing keys");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Objects(0, 10).NamedBy(name).Size(1_KB).CompleteOn("memory"));
+    for (size_t index = 0; index < 10; ++index) {
+        scenario.Then(KeyExists(name(index)));
+    }
+    scenario.Then(
+        BatchExistence({"test_key0", "test_key1", "test_key2", "test_key3",
+                        "test_key4", "test_key5", "test_key6", "test_key7",
+                        "test_key8", "test_key9", "non_existent_key"})
+            .Returns({true, true, true, true, true, true, true, true, true,
+                      true, false}));
+}
+
+TEST(MasterServiceTest, SoftPinRequestValidation) {
+    auto config = MasterServiceConfig::builder()
+                      .set_default_kv_soft_pin_ttl(50)
+                      .set_max_kv_soft_pin_ttl(100)
+                      .build();
+    MasterScenario("soft pin requests are validated at put start",
+                   std::move(config))
+        .Given(MemoryNode("memory"))
+        .When(PutStart("preserve_with_ttl", 1_KB)
+                  .WithSoftPinTtl(10)
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("disable_with_ttl", 1_KB)
+                  .WithSoftPinAction(SoftPinAction::DISABLE)
+                  .WithSoftPinTtl(10)
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("over_limit", 1_KB)
+                  .WithSoftPin()
+                  .WithSoftPinTtl(101)
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("invalid_action", 1_KB)
+                  .WithSoftPinAction(static_cast<SoftPinAction>(255))
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(PutStart("zero_ttl", 1_KB).WithSoftPin().WithSoftPinTtl(0))
+        .When(PutEnd("zero_ttl"))
+        .Then(Object("zero_ttl").IsReadable());
+}
+
+TEST(MasterServiceTest, SoftPinDoesNotBlockRemove) {
+    MasterScenario("soft pinned objects can be removed")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("soft_pinned", 1_KB).WithSoftPin())
+        .When(PutEnd("soft_pinned"))
+        .When(Remove("soft_pinned"))
+        .Then(Object("soft_pinned").DoesNotExist())
+        .When(PutStart("soft_pinned", 1_KB).WithSoftPin())
+        .When(PutEnd("soft_pinned"))
+        .When(RemoveAll().ExpectRemoved(1))
+        .Then(Object("soft_pinned").DoesNotExist());
+}
+
+TEST(MasterServiceTest, HardPinDefaultIsFalse) {
+    MasterScenario("hard pin is opt-in per put")
+        .Given(MemoryNode("memory"))
+        .When(PutStart("normal_key", 1_KB))
+        .When(PutEnd("normal_key"))
+        .When(PutStart("hp_key", 1_KB).WithHardPin())
+        .When(PutEnd("hp_key"))
+        .Then(Object("normal_key").IsReadable())
+        .Then(Object("hp_key").IsReadable());
+}
+
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_segment_scenario_test.cpp b/mooncake-store/tests/master_service_segment_scenario_test.cpp
new file mode 100644
index 0000000000..480a2e6a20
--- /dev/null
+++ b/mooncake-store/tests/master_service_segment_scenario_test.cpp
@@ -0,0 +1,185 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+
+namespace mooncake::test {
+
+using std::chrono::milliseconds;
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountSetsCorrectStatus) {
+    MasterScenario("graceful unmount marks the node gracefully unmounting")
+        .Given(MemoryNode("graceful-node"))
+        .Then(MemoryNodeStatus("graceful-node").Is(SegmentStatus::OK))
+        .When(GracefullyUnmountMemoryNode("graceful-node")
+                  .After(milliseconds(10000)))
+        .Then(MemoryNodeStatus("graceful-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING));
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountRejectsWrongClient) {
+    MasterScenario("only the owner may gracefully unmount a node")
+        .Given(MemoryNode("owned-node"))
+        .When(GracefullyUnmountMemoryNode("owned-node")
+                  .By("stranger")
+                  .After(milliseconds(10000))
+                  .ExpectError(ErrorCode::SEGMENT_NOT_FOUND))
+        .Then(MemoryNodeStatus("owned-node").Is(SegmentStatus::OK))
+        .When(GracefullyUnmountMemoryNode("owned-node")
+                  .After(milliseconds(10000)))
+        .Then(MemoryNodeStatus("owned-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING));
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountIsIdempotent) {
+    MasterScenario("repeated graceful unmounts succeed")
+        .Given(MemoryNode("idempotent-node"))
+        .When(GracefullyUnmountMemoryNode("idempotent-node")
+                  .After(milliseconds(10000)))
+        .When(GracefullyUnmountMemoryNode("idempotent-node")
+                  .After(milliseconds(10000)))
+        .Then(MemoryNodeStatus("idempotent-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING));
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountTimerExpiresAndUnmounts) {
+    MasterScenario("the grace timer eventually unmounts the node")
+        .Given(MemoryNode("timer-node"))
+        .When(
+            GracefullyUnmountMemoryNode("timer-node").After(milliseconds(200)))
+        .Then(MemoryNodeStatus("timer-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING))
+        .Then(MemoryNodeStatus("timer-node").DoesNotExist().Eventually());
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountQueryByIdWithReusedName) {
+    MasterScenario("status by id separates a reused node name")
+        .Given(MemoryNode("reused-name"))
+        .When(
+            GracefullyUnmountMemoryNode("reused-name").After(milliseconds(200)))
+        .When(MountMemorySegment("reused-replacement")
+                  .Named("reused-name")
+                  .Base(0x400000000)
+                  .Endpoint("reused-name")
+                  .By("reused-name"))
+        .Then(MemoryNodeStatus("reused-name")
+                  .ById()
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING))
+        .Then(
+            MemoryNodeStatus("reused-replacement").ById().Is(SegmentStatus::OK))
+        .Then(
+            MemoryNodeStatus("reused-name").ById().DoesNotExist().Eventually())
+        .Then(
+            MemoryNodeStatus("reused-replacement").ById().Is(SegmentStatus::OK))
+        .Then(MemoryNodeStatus("reused-name").Is(SegmentStatus::OK));
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountEarlierTimerPreempts) {
+    MasterScenario("a shorter grace period fires before a longer one")
+        .Given(MemoryNode("long-timer-node"))
+        .Given(MemoryNode("short-timer-node"))
+        .When(GracefullyUnmountMemoryNode("long-timer-node")
+                  .After(milliseconds(10000)))
+        .When(WaitFor(milliseconds(20)))
+        .When(GracefullyUnmountMemoryNode("short-timer-node")
+                  .After(milliseconds(50)))
+        .Then(MemoryNodeStatus("short-timer-node").DoesNotExist().Eventually())
+        .Then(MemoryNodeStatus("long-timer-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING));
+}
+
+TEST(MasterServiceSegmentScenarioTest, GracefulUnmountPreventsNewAllocation) {
+    MasterScenario("a gracefully unmounting node stays readable but full")
+        .Given(MemoryNode("draining-node"))
+        .Given(MemoryNode("healthy-node"))
+        .When(PutStart("existing_key", 1_KB).OnNode("draining-node"))
+        .When(PutEnd("existing_key"))
+        .When(GracefullyUnmountMemoryNode("draining-node")
+                  .After(milliseconds(10000)))
+        .Then(MemoryNodeStatus("draining-node")
+                  .Is(SegmentStatus::GRACEFULLY_UNMOUNTING))
+        .Then(Object("existing_key")
+                  .IsReadable()
+                  .HasReplicas(1)
+                  .IsOnMemoryNode("draining-node"))
+        .Then(MemoryNodeStatus("healthy-node").Is(SegmentStatus::OK))
+        .When(PutStart("new_key", 1_KB)
+                  .ExpectReplicas(1)
+                  .ExpectMemoryNodes({"healthy-node"}))
+        .When(PutEnd("new_key"));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsFromSingleEndpoint) {
+    MasterScenario("client IPs derive from the owned node endpoint")
+        .Given(MemoryNode("segment-a")
+                   .Endpoint("127.0.0.1:12345")
+                   .OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"}).Returns("client-a", {"127.0.0.1"}))
+        .Then(ClientIps({"client-a", "ghost-client"})
+                  .Returns("client-a", {"127.0.0.1"})
+                  .Omits("ghost-client"));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsAreUniqueAcrossNodes) {
+    MasterScenario("client IPs are deduplicated across owned nodes")
+        .Given(MemoryNode("segment-a")
+                   .Endpoint("127.0.0.1:12345")
+                   .OwnedBy("client-a"))
+        .Given(MemoryNode("segment-b")
+                   .Endpoint("127.0.0.1:12346")
+                   .OwnedBy("client-a"))
+        .Given(MemoryNode("segment-c")
+                   .Endpoint("192.168.1.1:12345")
+                   .OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"})
+                  .Returns("client-a", {"127.0.0.1", "192.168.1.1"}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsForNoActors) {
+    MasterScenario("an empty client list returns no entries")
+        .Given(MemoryNode("segment-a"))
+        .Then(ClientIps({}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsWithEmptyEndpoints) {
+    MasterScenario("empty endpoints yield a client entry with no IPs")
+        .Given(MemoryNode("segment-a").Endpoint("").OwnedBy("client-a"))
+        .Given(MemoryNode("segment-b").Endpoint("").OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"}).Returns("client-a", {}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsParseBracketedIpv6) {
+    MasterScenario("bracketed IPv6 endpoints lose brackets and port")
+        .Given(
+            MemoryNode("segment-a").Endpoint("[::1]:17813").OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"}).Returns("client-a", {"::1"}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsKeepLinkLocalIpv6Scope) {
+    MasterScenario("link-local IPv6 endpoints keep their scope id")
+        .Given(MemoryNode("segment-a")
+                   .Endpoint("fe80::a236:bcff:fecb:a1be%eno2:15773")
+                   .OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"})
+                  .Returns("client-a", {"fe80::a236:bcff:fecb:a1be%eno2"}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsParseIpv6WithoutPort) {
+    MasterScenario("a portless IPv6 endpoint is returned as-is")
+        .Given(MemoryNode("segment-a").Endpoint("::1").OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"}).Returns("client-a", {"::1"}));
+}
+
+TEST(MasterServiceSegmentScenarioTest, ClientIpsMixIpv4AndIpv6) {
+    MasterScenario("IPv4 and IPv6 endpoints combine per client")
+        .Given(MemoryNode("segment-a")
+                   .Endpoint("192.168.1.1:12345")
+                   .OwnedBy("client-a"))
+        .Given(
+            MemoryNode("segment-b").Endpoint("[::1]:17813").OwnedBy("client-a"))
+        .Then(ClientIps({"client-a"})
+                  .Returns("client-a", {"192.168.1.1", "::1"}));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_ssd_scenario_test.cpp b/mooncake-store/tests/master_service_ssd_scenario_test.cpp
new file mode 100644
index 0000000000..00bf24ae23
--- /dev/null
+++ b/mooncake-store/tests/master_service_ssd_scenario_test.cpp
@@ -0,0 +1,161 @@
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <string>
+
+#include "master_service/dsl/scenario.h"
+
+namespace mooncake::test {
+namespace {
+
+// root_fs_dir turns every PutStart into a dual allocation: one MEMORY replica
+// and one DISK replica that the client is expected to persist itself.
+MasterServiceConfig RootFsConfig() {
+    return MasterServiceConfig::builder().set_root_fs_dir("/mnt/ssd").build();
+}
+
+// Memory-pressure variant: no leases in the way, the high watermark disabled,
+// and a small eviction ratio so every armed cycle reclaims exactly one
+// expired one-megabyte memory replica.
+MasterServiceConfig PressureRootFsConfig() {
+    return MasterServiceConfig::builder()
+        .set_root_fs_dir("/mnt/ssd")
+        .set_default_kv_lease_ttl(0)
+        .set_eviction_ratio(0.05)
+        .set_eviction_high_watermark_ratio(1.0)
+        .build();
+}
+
+std::string PressureKey(size_t index) {
+    return "ssd_pressure_" + std::to_string(index);
+}
+
+}  // namespace
+
+TEST(MasterServiceSsdScenarioTest, PutEndCompletesBothReplica) {
+    MasterScenario("PutEnd of each type completes the matching replica",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("disk_key", 1_KB).ExpectReplicas(2))
+        .Then(Object("disk_key").IsNotReady())
+        .When(PutEnd("disk_key").OfType(ReplicaType::MEMORY))
+        .When(PutEnd("disk_key").OfType(ReplicaType::DISK))
+        .Then(Object("disk_key")
+                  .HasReplicas(2)
+                  .HasCompleteReplicas(2)
+                  .HasMemoryReplicas(1)
+                  .HasDiskReplicas(1));
+}
+
+TEST(MasterServiceSsdScenarioTest, PutRevokeDropsOnlyTheDiskReplica) {
+    MasterScenario("revoking the disk half leaves the memory replica",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("revoke_key", 1_KB).ExpectReplicas(2))
+        .When(PutEnd("revoke_key").OfType(ReplicaType::MEMORY))
+        .Then(Object("revoke_key").HasReplicas(1).HasMemoryReplicas(1))
+        .When(PutRevoke("revoke_key").OfType(ReplicaType::DISK))
+        .Then(Object("revoke_key").HasReplicas(1).HasMemoryReplicas(1));
+}
+
+TEST(MasterServiceSsdScenarioTest, PutRevokeDropsOnlyTheMemoryReplica) {
+    MasterScenario("revoking the memory half leaves the disk replica",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("revoke_key", 1_KB).ExpectReplicas(2))
+        .When(PutRevoke("revoke_key").OfType(ReplicaType::MEMORY))
+        .Then(Object("revoke_key").IsNotReady())
+        .When(PutEnd("revoke_key").OfType(ReplicaType::DISK))
+        .Then(Object("revoke_key").HasReplicas(1).HasDiskReplicas(1));
+}
+
+TEST(MasterServiceSsdScenarioTest, PutRevokeOfBothReplicasErasesTheKey) {
+    MasterScenario("revoking both halves erases the object", RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("revoke_key", 1_KB).ExpectReplicas(2))
+        .When(PutRevoke("revoke_key").OfType(ReplicaType::DISK))
+        .Then(Object("revoke_key").IsNotReady())
+        .When(PutRevoke("revoke_key").OfType(ReplicaType::MEMORY))
+        .Then(Object("revoke_key").DoesNotExist());
+}
+
+TEST(MasterServiceSsdScenarioTest, RemoveErasesBothReplicas) {
+    MasterScenario("Remove drops a fully committed dual-replica object",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("remove_key", 1_KB).ExpectReplicas(2))
+        .When(PutEnd("remove_key").OfType(ReplicaType::MEMORY))
+        .When(PutEnd("remove_key").OfType(ReplicaType::DISK))
+        .When(Remove("remove_key"))
+        .Then(Object("remove_key").DoesNotExist());
+}
+
+TEST(MasterServiceSsdScenarioTest, EvictDiskReplicaRemovesOnlyTheDiskReplica) {
+    MasterScenario("client-driven disk eviction keeps the memory replica",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("evict_disk_key", 1_KB).ExpectReplicas(2))
+        .When(PutEnd("evict_disk_key").OfType(ReplicaType::MEMORY))
+        .When(PutEnd("evict_disk_key").OfType(ReplicaType::DISK))
+        .Then(Object("evict_disk_key").HasReplicas(2))
+        .When(EvictDiskReplica("evict_disk_key"))
+        .Then(Object("evict_disk_key").HasReplicas(1).HasMemoryReplicas(1));
+}
+
+TEST(MasterServiceSsdScenarioTest, EvictDiskReplicaOfUnknownKeyIsRefused) {
+    MasterScenario("disk eviction of an unknown key reports OBJECT_NOT_FOUND",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(EvictDiskReplica("nonexistent_key")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND));
+}
+
+TEST(MasterServiceSsdScenarioTest, EvictDiskReplicaOfMemoryTypeIsRefused) {
+    MasterScenario("disk eviction only accepts disk replica types",
+                   RootFsConfig())
+        .Given(MemoryNode("memory"))
+        .When(PutStart("evict_invalid_type_key", 1_KB).ExpectReplicas(2))
+        .When(PutEnd("evict_invalid_type_key").OfType(ReplicaType::MEMORY))
+        .When(PutEnd("evict_invalid_type_key").OfType(ReplicaType::DISK))
+        .When(EvictDiskReplica("evict_invalid_type_key")
+                  .OfType(ReplicaType::MEMORY)
+                  .ExpectError(ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceSsdScenarioTest, MemoryPressureEvictsOnlyTheMemoryHalf) {
+    constexpr uint64_t kLargeObject = 1024 * 1024;
+    constexpr size_t kFilled = 14;
+    const auto expired_base =
+        std::chrono::system_clock::now() - std::chrono::hours(1);
+    MasterScenario scenario("memory pressure leaves the disk halves readable",
+                            PressureRootFsConfig());
+    scenario.Given(MemoryNode("memory").Capacity(16 * 1024 * 1024));
+    for (size_t index = 0; index < kFilled; ++index) {
+        scenario
+            .When(PutStart(PressureKey(index), kLargeObject).ExpectReplicas(2))
+            .When(PutEnd(PressureKey(index)).OfType(ReplicaType::MEMORY))
+            .When(PutEnd(PressureKey(index)).OfType(ReplicaType::DISK))
+            .When(ExpireAt(PressureKey(index),
+                           expired_base + std::chrono::nanoseconds(index)));
+    }
+    scenario
+        .When(PutStart(PressureKey(kFilled), 3 * kLargeObject)
+                  .ExpectReplicas(2)
+                  .Eventually(std::chrono::seconds(10)))
+        .When(PutEnd(PressureKey(kFilled)).OfType(ReplicaType::MEMORY))
+        .When(PutEnd(PressureKey(kFilled)).OfType(ReplicaType::DISK))
+        .Then(ReadableCount(Objects(0, kFilled + 1).NamedBy(PressureKey),
+                            kFilled + 1));
+    for (size_t index = 0; index < 3; ++index) {
+        scenario.Then(Object(PressureKey(index))
+                          .HasReplicas(1)
+                          .HasMemoryReplicas(0)
+                          .HasDiskReplicas(1));
+    }
+    scenario.Then(Object(PressureKey(3))
+                      .HasReplicas(2)
+                      .HasMemoryReplicas(1)
+                      .HasDiskReplicas(1));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_ssd_test.cpp b/mooncake-store/tests/master_service_ssd_test.cpp
index fcde4b4768..0d4b512533 100644
--- a/mooncake-store/tests/master_service_ssd_test.cpp
+++ b/mooncake-store/tests/master_service_ssd_test.cpp
@@ -1,9 +1,12 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
 #include <memory>
+#include <mutex>
+#include <shared_mutex>
 #include <thread>
 #include <vector>
 
@@ -26,6 +29,15 @@ class MasterServiceSSDTest : public ::testing::Test {
     }
 
     void TearDown() override { google::ShutdownGoogleLogging(); }
+
+    // Reach PushOffloadingQueue and its private identity type through the
+    // test peer to exercise replica states unavailable via PutStart (#2997).
+    static tl::expected<void, ErrorCode> CallPushOffloadingQueue(
+        MasterService& service, const TenantId& tenant, const std::string& key,
+        Replica& replica) {
+        const MasterServiceTestPeer::ObjectIdentity id{tenant, key};
+        return MasterServiceTestPeer(service).PushOffloadingQueue(id, replica);
+    }
 };
 
 std::unique_ptr<MasterService> CreateSsdAwareOffloadService() {
@@ -76,128 +88,6 @@ void PutAndOffload(MasterService& service, const UUID& client_id,
                     .has_value());
 }
 
-void ExpectNextAllocationOnSegment(MasterService& service,
-                                   const UUID& client_id,
-                                   const std::string& key,
-                                   const std::string& expected_segment) {
-    ReplicateConfig config;
-    config.replica_num = 1;
-    auto result =
-        service.PutStart(client_id, key, TenantId::Default(), 64, config);
-    ASSERT_TRUE(result.has_value());
-    ASSERT_EQ(result->size(), 1u);
-    ASSERT_TRUE((*result)[0].is_memory_replica());
-    EXPECT_EQ((*result)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              expected_segment);
-}
-
-TEST_F(MasterServiceSSDTest, PutEndBothReplica) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "disk_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto replicas = put_start_result.value();
-    ASSERT_EQ(2, replicas.size());
-
-    bool has_mem = false, has_disk = false;
-    for (const auto& r : replicas) {
-        if (r.is_memory_replica()) has_mem = true;
-        if (r.is_disk_replica()) has_disk = true;
-    }
-    EXPECT_TRUE(has_mem);
-    EXPECT_TRUE(has_disk);
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-
-    // PutEnd for both memory and disk
-    EXPECT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(
-        service_->PutEnd(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(2, get_result.value().replicas.size());
-
-    for (const auto& r : get_result.value().replicas) {
-        EXPECT_EQ(ReplicaStatus::COMPLETE, r.status);
-    }
-}
-
-TEST_F(MasterServiceSSDTest, PutRevokeDiskReplica) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "revoke_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    EXPECT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-    ASSERT_TRUE(get_result.value().replicas[0].is_memory_replica());
-
-    EXPECT_TRUE(
-        service_
-            ->PutRevoke(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-    ASSERT_TRUE(get_result.value().replicas[0].is_memory_replica());
-}
-
 TEST_F(MasterServiceSSDTest, PutRevokeProcessingDiskKeepsSsdTotal) {
     auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
     auto& metrics = MasterMetricManager::instance();
@@ -248,195 +138,6 @@ TEST_F(MasterServiceSSDTest, PutRevokeProcessingDiskKeepsSsdTotal) {
     EXPECT_EQ(stats[CacheHitStat::SSD_TOTAL], base_ssd_total);
 }
 
-TEST_F(MasterServiceSSDTest, PutRevokeMemoryReplica) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "revoke_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    EXPECT_TRUE(service_
-                    ->PutRevoke(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                    .has_value());
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-
-    EXPECT_TRUE(
-        service_->PutEnd(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-    ASSERT_TRUE(get_result.value().replicas[0].is_disk_replica());
-}
-
-TEST_F(MasterServiceSSDTest, PutRevokeBothReplica) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "revoke_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    EXPECT_TRUE(
-        service_
-            ->PutRevoke(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-
-    EXPECT_TRUE(service_
-                    ->PutRevoke(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                    .has_value());
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-}
-
-TEST_F(MasterServiceSSDTest, RemoveKey) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "remove_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    EXPECT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(
-        service_->PutEnd(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    EXPECT_TRUE(service_->Remove(key, TenantId::Default()).has_value());
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-}
-
-TEST_F(MasterServiceSSDTest, EvictObject) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-    // Mount a segment that can hold about 1024 * 16 objects.
-    // As the eviction is processed separately for each shard,
-    // we need to fill each shard with enough objects to thoroughly
-    // test the eviction process.
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    std::string segment_name = "test_segment";
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = segment_name;
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Verify if we can put objects more than the segment can hold
-    int success_puts = 0;
-    for (int i = 0; i < 1024 * 16 + 50; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = object_size;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        if (put_start_result.has_value()) {
-            auto put_end_mem_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-            auto put_end_disk_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::DISK);
-            ASSERT_TRUE(put_end_mem_result.has_value());
-            ASSERT_TRUE(put_end_disk_result.has_value());
-            success_puts++;
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-    ASSERT_GT(success_puts, 1024 * 16);
-
-    // Verify if we can get objects more than the segment can hold
-    int success_gets = 0;
-    for (int i = 0; i < 1024 * 16 + 50; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        if (get_result.has_value()) {
-            success_gets++;
-        }
-    }
-    ASSERT_GT(success_gets, 1024 * 16);
-
-    std::this_thread::sleep_for(
-        std::chrono::milliseconds(DEFAULT_DEFAULT_KV_LEASE_TTL));
-    service_->RemoveAll();
-}
-
 TEST_F(MasterServiceSSDTest, PutStartExpires) {
     // Reset storage space metrics.
     MasterMetricManager::instance().reset_allocated_mem_size();
@@ -551,53 +252,6 @@ TEST_F(MasterServiceSSDTest, PutStartExpires) {
     test_discard_replica(ReplicaType::MEMORY);
 }
 
-TEST_F(MasterServiceSSDTest, EvictDiskReplica_RemovesDiskReplica) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = "test_segment";
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "evict_disk_key";
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         1024, {.replica_num = 1});
-    ASSERT_TRUE(put_result.has_value());
-
-    // Complete both replicas
-    EXPECT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(
-        service_->PutEnd(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    // Verify we have 2 replicas (MEM + DISK)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(2, get_result.value().replicas.size());
-
-    // Evict disk replica
-    auto evict_result = service_->EvictDiskReplica(
-        client_id, key, TenantId::Default(), ReplicaType::DISK);
-    ASSERT_TRUE(evict_result.has_value());
-
-    // Verify only memory replica remains
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-    EXPECT_TRUE(get_result.value().replicas[0].is_memory_replica());
-}
-
 TEST_F(MasterServiceSSDTest, RemoveDecrementsCacheTotalMetrics) {
     auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
     auto& metrics = MasterMetricManager::instance();
@@ -643,149 +297,6 @@ TEST_F(MasterServiceSSDTest, RemoveDecrementsCacheTotalMetrics) {
     EXPECT_EQ(stats[CacheHitStat::SSD_TOTAL], base_ssd_total);
 }
 
-TEST_F(MasterServiceSSDTest, EvictDiskReplica_NonExistentKeyReturnsError) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    UUID client_id = generate_uuid();
-    auto evict_result = service_->EvictDiskReplica(
-        client_id, "nonexistent_key", TenantId::Default(), ReplicaType::DISK);
-    EXPECT_FALSE(evict_result.has_value());
-    EXPECT_EQ(evict_result.error(), ErrorCode::OBJECT_NOT_FOUND);
-}
-
-TEST_F(MasterServiceSSDTest, EvictDiskReplica_InvalidReplicaTypeReturnsError) {
-    auto service_ = CreateMasterServiceWithSSDFeat("/mnt/ssd");
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 64;
-    Segment segment;
-    segment.id = generate_uuid();
-    segment.name = "test_segment";
-    segment.base = buffer;
-    segment.size = size;
-    segment.te_endpoint = segment.name;
-    UUID client_id = generate_uuid();
-
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::string key = "evict_invalid_type_key";
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         1024, {.replica_num = 1});
-    ASSERT_TRUE(put_result.has_value());
-    EXPECT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(
-        service_->PutEnd(client_id, key, TenantId::Default(), ReplicaType::DISK)
-            .has_value());
-
-    // Attempting to evict with MEMORY type should fail
-    auto evict_result = service_->EvictDiskReplica(
-        client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-    EXPECT_FALSE(evict_result.has_value());
-    EXPECT_EQ(evict_result.error(), ErrorCode::INVALID_PARAMS);
-}
-
-TEST_F(MasterServiceSSDTest, RemoveReleasesLocalDiskUsageTracking) {
-    auto service = CreateSsdAwareOffloadService();
-    UUID client1 = generate_uuid();
-    UUID client2 = generate_uuid();
-    const std::string segment1 = "ssd_remove_segment_1";
-    const std::string segment2 = "ssd_remove_segment_2";
-    MountMemoryAndLocalDisk(*service, client1, segment1, 0x400000000);
-    MountMemoryAndLocalDisk(*service, client2, segment2, 0x500000000);
-
-    PutAndOffload(*service, client1, "ssd_remove_released", 800, segment1);
-    PutAndOffload(*service, client2, "ssd_remove_baseline", 100, segment2);
-
-    ASSERT_TRUE(service->Remove("ssd_remove_released", TenantId::Default())
-                    .has_value());
-
-    ExpectNextAllocationOnSegment(*service, client1, "ssd_remove_probe",
-                                  segment1);
-}
-
-TEST_F(MasterServiceSSDTest,
-       BatchReplicaClearAllSegmentsReleasesLocalDiskUsageTracking) {
-    auto service = CreateSsdAwareOffloadService();
-    UUID client1 = generate_uuid();
-    UUID client2 = generate_uuid();
-    const std::string segment1 = "ssd_clear_segment_1";
-    const std::string segment2 = "ssd_clear_segment_2";
-    MountMemoryAndLocalDisk(*service, client1, segment1, 0x600000000);
-    MountMemoryAndLocalDisk(*service, client2, segment2, 0x700000000);
-
-    PutAndOffload(*service, client1, "ssd_clear_released", 800, segment1);
-    PutAndOffload(*service, client2, "ssd_clear_baseline", 100, segment2);
-
-    auto clear_result =
-        service->BatchReplicaClear({"ssd_clear_released"}, client1, "");
-    ASSERT_TRUE(clear_result.has_value());
-    ASSERT_EQ(clear_result->size(), 1u);
-    EXPECT_EQ((*clear_result)[0], "ssd_clear_released");
-
-    ExpectNextAllocationOnSegment(*service, client1, "ssd_clear_probe",
-                                  segment1);
-}
-
-// Test that after offloading more data to segment1, the next allocation prefers
-// segment2 which has more SSD free space.
-TEST_F(MasterServiceSSDTest, SsdFreeRatioFirstPrefersFresherSsdAfterOffload) {
-    auto service = CreateSsdAwareOffloadService();
-    UUID client1 = generate_uuid();
-    UUID client2 = generate_uuid();
-    const std::string segment1 = "ssd_fresher_seg_1";
-    const std::string segment2 = "ssd_fresher_seg_2";
-    // Each segment reports total SSD capacity = 1000 bytes
-    MountMemoryAndLocalDisk(*service, client1, segment1, 0x800000000);
-    MountMemoryAndLocalDisk(*service, client2, segment2, 0x900000000);
-
-    // Offload 800 bytes to segment1 → ssd_used[seg1]=800, free=20%
-    PutAndOffload(*service, client1, "ssd_fresher_heavy", 800, segment1);
-    // Offload 100 bytes to segment2 → ssd_used[seg2]=100, free=90%
-    PutAndOffload(*service, client2, "ssd_fresher_light", 100, segment2);
-
-    // segment2 has higher SSD free ratio → allocation should prefer segment2
-    ExpectNextAllocationOnSegment(*service, client2, "ssd_fresher_probe",
-                                  segment2);
-}
-
-// Test that EvictDiskReplica decrements ssd_used_bytes so that the evicted
-// segment becomes preferred again for the next allocation.
-TEST_F(MasterServiceSSDTest, EvictDiskReplicaDecrementsLocalDiskUsageTracking) {
-    auto service = CreateSsdAwareOffloadService();
-    UUID client1 = generate_uuid();
-    UUID client2 = generate_uuid();
-    const std::string segment1 = "ssd_evict_dec_seg_1";
-    const std::string segment2 = "ssd_evict_dec_seg_2";
-    MountMemoryAndLocalDisk(*service, client1, segment1, 0xa00000000);
-    MountMemoryAndLocalDisk(*service, client2, segment2, 0xb00000000);
-
-    // Offload 800 bytes to segment1 → ssd_used[seg1]=800 (20% free)
-    PutAndOffload(*service, client1, "ssd_evict_dec_heavy", 800, segment1);
-    // Offload 100 bytes to segment2 → ssd_used[seg2]=100 (90% free)
-    PutAndOffload(*service, client2, "ssd_evict_dec_light", 100, segment2);
-
-    // segment2 has more SSD free space → should be preferred
-    ExpectNextAllocationOnSegment(*service, client2, "ssd_evict_dec_probe1",
-                                  segment2);
-
-    // Evict the LOCAL_DISK replica of the heavy object from segment1.
-    // NotifyOffloadSuccess creates a LOCAL_DISK replica (not DISK).
-    // This decrements ssd_used[seg1] by 800 → ssd_used[seg1]=0 (100% free)
-    auto evict_result =
-        service->EvictDiskReplica(client1, "ssd_evict_dec_heavy",
-                                  TenantId::Default(), ReplicaType::LOCAL_DISK);
-    ASSERT_TRUE(evict_result.has_value());
-
-    // After eviction: segment1 has 100% free, segment2 has 90% free
-    // → segment1 should now be preferred
-    ExpectNextAllocationOnSegment(*service, client1, "ssd_evict_dec_probe2",
-                                  segment1);
-}
-
 // Evicting a LOCAL_DISK replica via EvictDiskReplica must decrement
 // file_cache_nums_ even when the object still has a MEMORY replica (so
 // accessor.Erase() does not run). Without SyncCacheTotalAccounting in the
@@ -939,6 +450,127 @@ TEST_F(MasterServiceSSDTest,
         << "%\n\n";
 }
 
+// Uses the test peer to run the two halves of UnmountLocalDiskSegment
+// (deregistration, replica sweep) as separate steps, so a competing mount +
+// register can be serialized between them -- the interleaving is pinned by
+// construction instead of hoping a scheduler produces it.
+class LocalDiskUnmountInterleavingTest : public MasterServiceSSDTest {
+   protected:
+    static void DeregisterHalf(MasterService& service, const UUID& client_id) {
+        std::unique_lock<std::shared_mutex> snapshot_lock(
+            MasterServiceTestPeer::SnapshotMutex(service));
+        MasterServiceTestPeer::LocalSsdManager(service).UnregisterClient(
+            client_id);
+    }
+
+    static void SweepHalf(MasterService& service, const UUID& client_id) {
+        MasterServiceTestPeer(service).ClearLocalDiskHandlesOwnedBy(client_id);
+    }
+};
+
+TEST_F(LocalDiskUnmountInterleavingTest,
+       MountAndRegisterBetweenRemovalAndSweepSurvives) {
+    auto service = CreateSsdAwareOffloadService();
+    UUID leaving = generate_uuid();
+    UUID late = generate_uuid();
+    const std::string leaving_segment = "ssd_interleave_leaving_segment";
+    const std::string late_segment = "ssd_interleave_late_segment";
+    MountMemoryAndLocalDisk(*service, leaving, leaving_segment, 0x1300000000);
+    PutAndOffload(*service, leaving, "ssd_interleave_leaving_key", 1024,
+                  leaving_segment);
+
+    // First half of UnmountLocalDiskSegment(leaving): the client is
+    // deregistered; the sweep has not run.
+    DeregisterHalf(*service, leaving);
+
+    // The interleaving under test: another store mounts and registers a
+    // replica before the sweep reaches its shard. Whether the client monitor
+    // has admitted `late` to the alive set yet does not matter to an
+    // owner-targeted sweep -- while a liveness-complement sweep taken before
+    // this mount would classify the replica stale and erase it, and with it
+    // the key, since this disk replica is the key's only one.
+    MountMemoryAndLocalDisk(*service, late, late_segment, 0x1400000000);
+    StorageObjectMetadata late_metadata;
+    late_metadata.data_size = 1024;
+    late_metadata.transport_endpoint = late_segment;
+    OffloadTaskItem late_task{.tenant_id = TenantId::Default().value(),
+                              .key = "ssd_interleave_late_key",
+                              .size = 1024};
+    ASSERT_TRUE(
+        service->NotifyOffloadSuccess(late, {late_task}, {late_metadata})
+            .has_value());
+
+    // Second half: the sweep.
+    SweepHalf(*service, leaving);
+
+    // The leaving owner's disk replica is gone (the memory replica stays)...
+    auto leaving_replicas = service->GetReplicaList(
+        "ssd_interleave_leaving_key", TenantId::Default());
+    ASSERT_TRUE(leaving_replicas.has_value());
+    ASSERT_EQ(1u, leaving_replicas.value().replicas.size());
+    EXPECT_TRUE(leaving_replicas.value().replicas[0].is_memory_replica());
+
+    // ...while the late mounter's registration survived the sweep.
+    auto late_replicas =
+        service->GetReplicaList("ssd_interleave_late_key", TenantId::Default());
+    ASSERT_TRUE(late_replicas.has_value());
+    ASSERT_EQ(1u, late_replicas.value().replicas.size());
+    EXPECT_TRUE(late_replicas.value().replicas[0].is_local_disk_replica());
+}
+
+// Regression test for issue #2997.
+//
+// PushOffloadingQueue has two no-op paths that used to return a silent success
+// ({}) without enqueuing anything:
+//
+//   1. get_segment_names() is empty   — the replica carries no source segment
+//      metadata (e.g. a DISK/LOCAL_DISK/DFS replica).
+//   2. every segment name is nullopt  — a MEMORY/NOF replica whose backing
+//      buffer is absent or has an invalid allocator, so get_segment_names()
+//      yields a single nullopt entry and the loop body is skipped for it.
+//
+// In both cases the caller's `if (result)` branch fired and executed
+// inc_refcnt() + offloading_tasks.emplace() for work that was never submitted,
+// leaking the source replica's refcount until the 600s TTL reaper cleared the
+// phantom task. The fix returns UNABLE_OFFLOADING from both paths.
+//
+// These two states cannot arise from the public PutStart/PutEnd path — that
+// path always produces a MEMORY replica with a valid buffer, whose
+// segment_names is a single real name, so PushOffloadingQueue reaches
+// EnqueueOffload and (pre-fix as well as post-fix) already returned
+// UNABLE_OFFLOADING via SEGMENT_NOT_FOUND. To actually guard the two lines this
+// PR changed, the test constructs the degenerate replicas directly and calls
+// PushOffloadingQueue through the test peer, asserting the no-op is
+// reported as a failure rather than a silent success.
+TEST_F(MasterServiceSSDTest, PushOffloadingQueueReportsNoopAsFailure) {
+    auto service = CreateSsdAwareOffloadService();
+    // The helper constructs the peer-exposed identity from tenant/key args.
+    const TenantId tenant = TenantId::Default();
+    const std::string key = "noop_offload_key";
+
+    // Path 2: MEMORY replica with a null buffer -> get_segment_names() is
+    // [nullopt] -> the loop enqueues nothing -> the !any_enqueued guard fires.
+    Replica all_nullopt_replica(/*buffer=*/nullptr, ReplicaStatus::COMPLETE);
+    ASSERT_FALSE(all_nullopt_replica.get_segment_names().empty());
+    auto r2 =
+        CallPushOffloadingQueue(*service, tenant, key, all_nullopt_replica);
+    ASSERT_FALSE(r2.has_value())
+        << "all-nullopt segment names must not report a silent success "
+           "(issue #2997)";
+    EXPECT_EQ(ErrorCode::UNABLE_OFFLOADING, r2.error());
+
+    // Path 1: a non-MEMORY/non-NOF replica -> get_segment_names() is empty ->
+    // the empty-source guard fires before the loop.
+    Replica empty_names_replica(/*file_path=*/"/tmp/nonexistent_offload_src",
+                                /*object_size=*/1024, ReplicaStatus::COMPLETE);
+    ASSERT_TRUE(empty_names_replica.get_segment_names().empty());
+    auto r1 =
+        CallPushOffloadingQueue(*service, tenant, key, empty_names_replica);
+    ASSERT_FALSE(r1.has_value())
+        << "empty segment names must not report a silent success (issue #2997)";
+    EXPECT_EQ(ErrorCode::UNABLE_OFFLOADING, r1.error());
+}
+
 }  // namespace mooncake::test
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/master_service_task_scenario_test.cpp b/mooncake-store/tests/master_service_task_scenario_test.cpp
new file mode 100644
index 0000000000..3b16892452
--- /dev/null
+++ b/mooncake-store/tests/master_service_task_scenario_test.cpp
@@ -0,0 +1,165 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+namespace mooncake::test {
+
+TEST(MasterServiceTaskScenarioTest, CreateCopyTask) {
+    MasterScenario("copy tasks validate inputs and go to the source owner")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("copy_task_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("copy_task_key"))
+        .When(CreateCopyTask("copy-task", "copy_task_key")
+                  .To({"node-1", "node-2"}))
+        .Then(NamedTask("copy-task")
+                  .HasType(TaskType::REPLICA_COPY)
+                  .IsAssignedTo("node-0"))
+        .When(CreateCopyTask("empty-targets", "copy_task_key")
+                  .To({})
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CreateCopyTask("missing-object", "missing_key")
+                  .To({"node-1"})
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(CreateCopyTask("unmounted-target", "copy_task_key")
+                  .To({"ghost-node"})
+                  .ExpectError(ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceTaskScenarioTest, CreateMoveTask) {
+    MasterScenario("move tasks validate inputs and go to the source owner")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .Given(MemoryNode("node-2"))
+        .When(PutStart("move_task_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("move_task_key"))
+        .When(CreateMoveTask("move-task", "move_task_key")
+                  .From("node-0")
+                  .To("node-1"))
+        .Then(NamedTask("move-task")
+                  .HasType(TaskType::REPLICA_MOVE)
+                  .IsAssignedTo("node-0"))
+        .When(CreateMoveTask("missing-object", "missing_key")
+                  .From("node-0")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::OBJECT_NOT_FOUND))
+        .When(CreateMoveTask("same-source-target", "move_task_key")
+                  .From("node-1")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CreateMoveTask("unmounted-target", "move_task_key")
+                  .From("node-0")
+                  .To("ghost-node")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CreateMoveTask("source-without-replica", "move_task_key")
+                  .From("node-2")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS))
+        .When(CreateMoveTask("unmounted-source", "move_task_key")
+                  .From("ghost-node")
+                  .To("node-1")
+                  .ExpectError(ErrorCode::INVALID_PARAMS));
+}
+
+TEST(MasterServiceTaskScenarioTest, QueryTask) {
+    MasterScenario("query task reports known and unknown tasks")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("query_task_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("query_task_key"))
+        .When(CreateMoveTask("move-task", "query_task_key")
+                  .From("node-0")
+                  .To("node-1"))
+        .Then(UnknownTask("never-created"))
+        .Then(NamedTask("move-task")
+                  .HasType(TaskType::REPLICA_MOVE)
+                  .IsAssignedTo("node-0"));
+}
+
+TEST(MasterServiceTaskScenarioTest, FetchTasksEmptyWhenNoTasks) {
+    MasterScenario("fetching without tasks returns nothing")
+        .Given(MemoryNode("node-0"))
+        .When(FetchTasks("node-0").ExpectCount(0));
+}
+
+TEST(MasterServiceTaskScenarioTest, FetchTasksReturnsAssignedTasksOnly) {
+    MasterScenario("fetch returns the owner's tasks once")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("fetch_tasks_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("fetch_tasks_key"))
+        .When(CreateCopyTask("copy-task", "fetch_tasks_key").To({"node-1"}))
+        .When(CreateMoveTask("move-task", "fetch_tasks_key")
+                  .From("node-0")
+                  .To("node-1"))
+        .When(FetchTasks("node-0").ExpectCount(2))
+        .Then(NamedTask("copy-task")
+                  .HasStatus(TaskStatus::PROCESSING)
+                  .IsAssignedTo("node-0"))
+        .Then(NamedTask("move-task")
+                  .HasStatus(TaskStatus::PROCESSING)
+                  .IsAssignedTo("node-0"))
+        .When(FetchTasks("node-1").ExpectCount(0))
+        .When(FetchTasks("node-0").ExpectCount(0));
+}
+
+TEST(MasterServiceTaskScenarioTest, FetchTasksRespectsBatchSize) {
+    MasterScenario("fetch drains pending tasks one batch at a time")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("batch_size_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("batch_size_key"))
+        .When(CreateCopyTask("copy-task", "batch_size_key").To({"node-1"}))
+        .When(CreateMoveTask("move-task", "batch_size_key")
+                  .From("node-0")
+                  .To("node-1"))
+        .When(FetchTasks("node-0").Limit(1).ExpectCount(1))
+        .When(FetchTasks("node-0").Limit(1).ExpectCount(1))
+        .Then(NamedTask("copy-task").HasStatus(TaskStatus::PROCESSING))
+        .Then(NamedTask("move-task").HasStatus(TaskStatus::PROCESSING))
+        .When(FetchTasks("node-0").Limit(1).ExpectCount(0));
+}
+
+TEST(MasterServiceTaskScenarioTest, CompleteTaskSuccessFlow) {
+    MasterScenario("a fetched task completes with status and message")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("complete_task_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("complete_task_key"))
+        .When(CreateCopyTask("copy-task", "complete_task_key").To({"node-1"}))
+        .When(FetchTasks("node-0").ExpectCount(1))
+        .When(CompleteTask("copy-task").By("node-0").WithMessage("done"))
+        .Then(NamedTask("copy-task")
+                  .HasStatus(TaskStatus::SUCCESS)
+                  .IsAssignedTo("node-0")
+                  .HasMessage("done"))
+        .When(FetchTasks("node-0").ExpectCount(0));
+}
+
+TEST(MasterServiceTaskScenarioTest, CompleteTaskRejectsWrongClient) {
+    MasterScenario("only the assignee may complete a task")
+        .Given(MemoryNode("node-0"))
+        .Given(MemoryNode("node-1"))
+        .When(PutStart("wrong_client_key", 1_KB).OnNode("node-0"))
+        .When(PutEnd("wrong_client_key"))
+        .When(CreateMoveTask("move-task", "wrong_client_key")
+                  .From("node-0")
+                  .To("node-1"))
+        .When(FetchTasks("node-0").ExpectCount(1))
+        .When(CompleteTask("move-task")
+                  .By("node-1")
+                  .WithMessage("should_not_work")
+                  .ExpectError(ErrorCode::ILLEGAL_CLIENT));
+}
+
+TEST(MasterServiceTaskScenarioTest, CompleteTaskNotFound) {
+    MasterScenario("completing an unknown task fails")
+        .Given(MemoryNode("node-0"))
+        .When(CompleteUnknownTask("never-created")
+                  .By("node-0")
+                  .WithMessage("not_found")
+                  .ExpectError(ErrorCode::TASK_NOT_FOUND));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_tenant_quota_test.cpp b/mooncake-store/tests/master_service_tenant_quota_test.cpp
index 5016af2b55..538bc2f212 100644
--- a/mooncake-store/tests/master_service_tenant_quota_test.cpp
+++ b/mooncake-store/tests/master_service_tenant_quota_test.cpp
@@ -1,4 +1,5 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <atomic>
 #include <chrono>
@@ -78,18 +79,6 @@ class BlockingAllocationStrategy final : public AllocationStrategy {
                                   replica_type);
     }
 
-    tl::expected<std::vector<Replica>, ErrorCode> Allocate(
-        const AllocatorManager& allocator_manager, const size_t slice_length,
-        const size_t replica_num,
-        const std::vector<std::string>& preferred_segments,
-        const std::set<std::string>& excluded_segments,
-        const ReplicaType replica_type,
-        const SsdMetricsProvider* ssd_provider) override {
-        (void)ssd_provider;
-        return Allocate(allocator_manager, slice_length, replica_num,
-                        preferred_segments, excluded_segments, replica_type);
-    }
-
     tl::expected<Replica, ErrorCode> AllocateFrom(
         const AllocatorManager& allocator_manager, const size_t slice_length,
         const std::string& segment_name) override {
@@ -147,6 +136,37 @@ class MasterServiceTenantQuotaTest : public ::testing::Test {
         return builder.build();
     }
 
+    // Config for the tenant-scoped eviction watermark. Two settings here are
+    // load-bearing rather than incidental:
+    //   default_kv_lease_ttl(0) -- EvictTenantMemoryForQuota skips any object
+    //     whose lease is still live, so with the 10 s default the pass under
+    //     test would be a no-op and the assertions would pass for the wrong
+    //     reason.
+    //   eviction_high_watermark_ratio(1.0) -- keeps the POOL-wide evictor out
+    //     of the way. The whole point of the tenant watermark is that it fires
+    //     while the pool is nowhere near its own, so the test must not let the
+    //     pool-level path account for the bytes freed.
+    // A nullopt ratio leaves the builder default in place, which is how the
+    // "on out of the box" behaviour is exercised.
+    MasterServiceConfig MakeTenantWatermarkConfig(
+        const std::map<TenantId, uint64_t>& tenant_quotas,
+        std::optional<double> tenant_high_watermark_ratio,
+        double eviction_ratio = 0.05) {
+        auto builder =
+            MasterServiceConfig::builder()
+                .set_enable_multi_tenants(true)
+                .set_tenant_quota_connector_type("file")
+                .set_tenant_quota_connector_uri(WritePolicyFile(tenant_quotas))
+                .set_default_kv_lease_ttl(0)
+                .set_eviction_ratio(eviction_ratio)
+                .set_eviction_high_watermark_ratio(1.0);
+        if (tenant_high_watermark_ratio.has_value()) {
+            builder.set_tenant_eviction_high_watermark_ratio(
+                *tenant_high_watermark_ratio);
+        }
+        return builder.build();
+    }
+
     UUID MountSegment(MasterService& service, size_t size = 4096,
                       std::string name = "quota_segment") {
         Segment segment;
@@ -198,6 +218,13 @@ class MasterServiceTenantQuotaTest : public ::testing::Test {
         ASSERT_TRUE(end.has_value()) << toString(end.error());
     }
 
+    // MasterService befriends this fixture, but TEST_F bodies are a derived
+    // class and friendship does not inherit -- so private access has to go
+    // through a fixture method, as it does for the helpers around this one.
+    void RunTenantEvictionPass(MasterService& service) {
+        MasterServiceTestPeer(service).RunTenantEvictForTesting();
+    }
+
     TenantQuotaSnapshot Snapshot(MasterService& service,
                                  const TenantId& tenant_id) {
         auto snapshot = service.GetTenantQuotaSnapshot(tenant_id);
@@ -206,47 +233,149 @@ class MasterServiceTenantQuotaTest : public ::testing::Test {
     }
 
     void ReloadTenantQuotaPolicyFromStore(MasterService& service) {
-        service.LoadTenantQuotaPoliciesFromStoreOrThrow();
-        service.RebuildTenantQuotaUsageFromMetadata();
+        MasterServiceTestPeer(service)
+            .LoadTenantQuotaPoliciesFromStoreOrThrow();
+        MasterServiceTestPeer(service).RebuildTenantQuotaUsageFromMetadata();
     }
 
     void ReplaceTenantQuotaPolicyStore(
         MasterService& service, std::unique_ptr<TenantQuotaPolicyStore> store) {
-        service.tenant_quota_policy_store_ = std::move(store);
+        MasterServiceTestPeer::TenantQuotaPolicyStore(service) =
+            std::move(store);
     }
 
     int64_t LocalDiskUsedBytes(MasterService& service, const UUID& client_id) {
-        auto access = service.segment_manager_.getLocalDiskSegmentAccess();
-        auto& segments = access.getClientLocalDiskSegment();
-        auto it = segments.find(client_id);
-        EXPECT_TRUE(it != segments.end());
-        if (it == segments.end()) {
+        auto usage =
+            MasterServiceTestPeer::LocalSsdManager(service).GetUsage(client_id);
+        EXPECT_TRUE(usage.has_value());
+        if (!usage) {
             return -1;
         }
-        return it->second->ssd_used_bytes.load(std::memory_order_relaxed);
+        return usage->used_bytes;
     }
 
 #ifdef USE_NOF
     void ReplaceAllocationStrategy(
         MasterService& service, std::shared_ptr<AllocationStrategy> strategy) {
-        service.allocation_strategy_ = std::move(strategy);
+        MasterServiceTestPeer::AllocationStrategy(service) =
+            std::move(strategy);
     }
 #endif
 
-    tl::expected<void, ErrorCode> ReserveTenantQuotaForTest(
+    tl::expected<void, ErrorCode> ChargeTenantQuotaForTest(
         MasterService& service, const TenantId& tenant_id, uint64_t bytes) {
-        return service.ReserveTenantQuota(tenant_id, bytes);
+        return MasterServiceTestPeer(service).ChargeTenantQuota(
+            MasterServiceTestPeer::TenantQuotaTable(service)
+                .GetOrCreateTenantHandle(tenant_id),
+            bytes);
+    }
+
+    TenantQuotaHandle GetOrCreateTenantStateHandleForTest(
+        MasterService& service, size_t shard_idx, const TenantId& tenant_id) {
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                             shard_idx);
+        auto& tenant_state =
+            MasterServiceTestPeer(service).GetOrCreateTenantState(shard.get(),
+                                                                  tenant_id);
+        return MasterServiceTestPeer(service).GetBoundTenantQuotaHandle(
+            tenant_state);
+    }
+
+    tl::expected<void, ErrorCode> ChargeBoundTenantQuotaForTest(
+        MasterService& service, TenantQuotaHandle account, uint64_t bytes) {
+        return MasterServiceTestPeer(service).ChargeTenantQuota(account, bytes);
+    }
+
+    void ReleaseBoundTenantQuotaForTest(MasterService& service,
+                                        TenantQuotaHandle account,
+                                        uint64_t bytes) {
+        MasterServiceTestPeer(service).ReleaseTenantQuota(account, bytes);
+    }
+
+    void DiscardExpiredProcessingForTest(MasterService& service,
+                                         const TenantId& tenant_id,
+                                         const std::string& key) {
+        const size_t shard_idx =
+            MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                             shard_idx);
+        MasterServiceTestPeer(service).DiscardExpiredProcessingReplicas(
+            shard, std::chrono::system_clock::time_point::max());
+    }
+
+    void FinalizeExpiredProcessingForTest(MasterService& service,
+                                          const TenantId& tenant_id,
+                                          const std::string& key) {
+        OpLogEntry entry;
+        entry.tenant_id = tenant_id.value();
+        entry.object_key = key;
+        MasterServiceTestPeer(service)
+            .FinalizeExpiredProcessingReplicasAfterDurable(
+                entry, std::chrono::system_clock::now());
+    }
+
+    void FinalizeRemovedMemoryReplicasForTest(MasterService& service,
+                                              const TenantId& tenant_id,
+                                              const std::string& key) {
+        std::vector<ReplicaID> removed_ids;
+        {
+            MasterServiceTestPeer::MetadataAccessorRW accessor(
+                &service,
+                MasterServiceTestPeer::ObjectIdentity{tenant_id, key});
+            ASSERT_TRUE(accessor.Exists());
+            accessor.Get().VisitReplicas(
+                &Replica::fn_is_memory_replica,
+                [&removed_ids](Replica& replica) {
+                    removed_ids.push_back(replica.id());
+                    replica.mark_removed();
+                });
+        }
+        ASSERT_FALSE(removed_ids.empty());
+
+        OpLogEntry entry;
+        entry.tenant_id = tenant_id.value();
+        entry.object_key = key;
+        MasterServiceTestPeer(service).FinalizeRemovedReplicasAfterDurable(
+            entry, removed_ids, MasterServiceTestPeer::QuotaEraseMode::kFull);
+    }
+
+    void AddCompletedDiskReplica(MasterService& service, const UUID& client_id,
+                                 const std::string& key,
+                                 const TenantId& tenant_id, uint64_t size) {
+        Replica disk_replica(client_id, size, "disk-endpoint",
+                             ReplicaStatus::COMPLETE);
+        auto result =
+            service.AddReplica(client_id, key, tenant_id, disk_replica);
+        ASSERT_TRUE(result.has_value()) << toString(result.error());
+    }
+
+    void ExpectDiskOnlyObjectAndChargedBytes(MasterService& service,
+                                             const TenantId& tenant_id,
+                                             const std::string& key,
+                                             uint64_t charged_bytes) {
+        EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, charged_bytes);
+        auto replicas = service.GetReplicaList(key, tenant_id);
+        ASSERT_TRUE(replicas.has_value()) << toString(replicas.error());
+        ASSERT_EQ(replicas->replicas.size(), 1);
+        EXPECT_TRUE(replicas->replicas.front().is_local_disk_replica());
     }
 
     std::unique_lock<std::shared_mutex> LockSnapshotForTest(
         MasterService& service) {
-        return std::unique_lock<std::shared_mutex>(service.snapshot_mutex_);
+        return std::unique_lock<std::shared_mutex>(
+            MasterServiceTestPeer::SnapshotMutex(service));
     }
 
     std::unique_lock<std::mutex> LockTenantQuotaRecomputeForTest(
         MasterService& service) {
         return std::unique_lock<std::mutex>(
-            service.tenant_quota_recompute_mutex_);
+            MasterServiceTestPeer::TenantQuotaRecomputeMutex(service));
+    }
+
+    std::unique_lock<std::mutex> LockTenantQuotaPolicyForTest(
+        MasterService& service) {
+        return std::unique_lock<std::mutex>(
+            MasterServiceTestPeer::TenantQuotaPolicyMutex(service));
     }
 
     ErrorCode MountSegmentWithoutQuotaRecomputeForTest(MasterService& service,
@@ -260,20 +389,25 @@ class MasterServiceTenantQuotaTest : public ::testing::Test {
         segment.te_endpoint = segment.name;
         next_segment_offset_ += size + 4096;
 
-        auto segment_access = service.segment_manager_.getSegmentAccess();
-        return segment_access.MountSegment(segment, generate_uuid());
+        auto segment_access =
+            MasterServiceTestPeer::SegmentManager(service).getSegmentAccess();
+        return segment_access.MountSegment(
+            segment, generate_uuid(),
+            std::make_shared<ClientLivenessRecord>(
+                ClientLivenessRecord::Clock::now()));
     }
 
     void RecomputeTenantEffectiveQuotasForTest(MasterService& service) {
-        service.RecomputeTenantEffectiveQuotas();
+        MasterServiceTestPeer(service).RecomputeTenantEffectiveQuotas();
     }
 
     bool WaitForTenantQuotaPolicyMutexContention(MasterService& service) {
         for (int i = 0; i < 500; ++i) {
-            if (!service.tenant_quota_policy_mutex_.try_lock()) {
+            if (!MasterServiceTestPeer::TenantQuotaPolicyMutex(service)
+                     .try_lock()) {
                 return true;
             }
-            service.tenant_quota_policy_mutex_.unlock();
+            MasterServiceTestPeer::TenantQuotaPolicyMutex(service).unlock();
             std::this_thread::sleep_for(std::chrono::milliseconds(10));
         }
         return false;
@@ -339,6 +473,40 @@ TEST_F(MasterServiceTenantQuotaTest,
     PutComplete(service, client_id, "ok", TenantId("tenant-a"), 10);
 }
 
+TEST_F(MasterServiceTenantQuotaTest,
+       SameTenantStatesAcrossMetadataShardsShareBoundHandle) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    MountSegment(service);
+
+    auto* first_handle =
+        GetOrCreateTenantStateHandleForTest(service, 0, tenant_id);
+    auto* second_handle =
+        GetOrCreateTenantStateHandleForTest(service, 1, tenant_id);
+
+    ASSERT_NE(first_handle, nullptr);
+    EXPECT_EQ(first_handle, second_handle);
+
+    auto charge = ChargeBoundTenantQuotaForTest(service, first_handle, 128);
+    ASSERT_TRUE(charge.has_value()) << toString(charge.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 128);
+
+    ReleaseBoundTenantQuotaForTest(service, second_handle, 128);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       ChargeRejectsMissingHandleWhenQuotaIsEnabled) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    MountSegment(service);
+
+    auto charge = ChargeBoundTenantQuotaForTest(service, nullptr, 1);
+    ASSERT_FALSE(charge.has_value());
+    EXPECT_EQ(charge.error(), ErrorCode::INTERNAL_ERROR);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 0);
+}
+
 TEST_F(MasterServiceTenantQuotaTest,
        MultiTenantModeRejectsUnregisteredOffloadSuccess) {
     MasterService service(MakeConfig({{TenantId("tenant-a"), 1000}}));
@@ -376,11 +544,11 @@ TEST_F(MasterServiceTenantQuotaTest,
     auto exists = service.ExistKey("cold", TenantId("tenant-a"));
     ASSERT_TRUE(exists.has_value()) << toString(exists.error());
     EXPECT_TRUE(exists.value());
-    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).used_bytes, 0);
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 0);
 }
 
 TEST_F(MasterServiceTenantQuotaTest,
-       ConnectorPolicyReloadKeepsLocalDiskOnlyOrphanVisible) {
+       ConnectorPolicyReloadKeepsLocalDiskOnlyOrphanAccessible) {
     const std::string initial_policy = WritePolicyFile(
         {{TenantId("tenant-a"), 1000}, {TenantId("tenant-b"), 1000}});
     auto config = MasterServiceConfig::builder()
@@ -407,12 +575,8 @@ TEST_F(MasterServiceTenantQuotaTest,
     }
     ReloadTenantQuotaPolicyFromStore(service);
 
-    auto orphan = Snapshot(service, TenantId("tenant-b"));
-    EXPECT_FALSE(orphan.has_explicit_policy);
-    EXPECT_EQ(orphan.used_bytes, 0);
-    EXPECT_EQ(orphan.committed_count, 0);
-    EXPECT_EQ(orphan.metadata_object_count, 1);
-    EXPECT_TRUE(orphan.over_quota);
+    EXPECT_FALSE(
+        service.GetTenantQuotaSnapshot(TenantId("tenant-b")).has_value());
 
     EXPECT_TRUE(service.Remove("cold", TenantId("tenant-b"), /*force=*/true)
                     .has_value());
@@ -442,7 +606,10 @@ TEST_F(MasterServiceTenantQuotaTest,
         out << FormatTenantQuotaPolicyYaml(replacement);
     }
     ReloadTenantQuotaPolicyFromStore(service);
-    EXPECT_FALSE(Snapshot(service, TenantId("tenant-b")).has_explicit_policy);
+    auto orphan = Snapshot(service, TenantId("tenant-b"));
+    EXPECT_FALSE(orphan.has_explicit_policy);
+    EXPECT_TRUE(orphan.admission_closed);
+    EXPECT_EQ(orphan.charged_bytes, 128);
 
     StorageObjectMetadata metadata;
     metadata.data_size = 128;
@@ -542,6 +709,7 @@ TEST_F(MasterServiceTenantQuotaTest,
     auto first = service.PutStart(client_id, "key-a", TenantId("tenant-a"), 80,
                                   hard_pinned);
     ASSERT_TRUE(first.has_value()) << toString(first.error());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 80);
     ASSERT_TRUE(service
                     .PutEnd(client_id, "key-a", TenantId("tenant-a"),
                             ReplicaType::MEMORY)
@@ -552,11 +720,166 @@ TEST_F(MasterServiceTenantQuotaTest,
 
     ASSERT_FALSE(over.has_value());
     EXPECT_EQ(over.error(), ErrorCode::TENANT_QUOTA_EXCEEDED);
-    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).used_bytes, 80);
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 80);
     EXPECT_FALSE(
         service.GetTenantQuotaSnapshot(TenantId("tenant-b")).has_value());
 }
 
+TEST_F(MasterServiceTenantQuotaTest, PutRevokeRefundsStartCharge) {
+    MasterService service(MakeConfig({{TenantId("tenant-a"), 100}}));
+    UUID client_id = MountSegment(service);
+
+    auto start = service.PutStart(client_id, "key", TenantId("tenant-a"), 100,
+                                  MemoryConfig());
+    ASSERT_TRUE(start.has_value()) << toString(start.error());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 100);
+
+    auto over = service.PutStart(client_id, "other", TenantId("tenant-a"), 1,
+                                 MemoryConfig());
+    ASSERT_FALSE(over.has_value());
+    EXPECT_EQ(over.error(), ErrorCode::TENANT_QUOTA_EXCEEDED);
+
+    ASSERT_TRUE(service
+                    .PutRevoke(client_id, "key", TenantId("tenant-a"),
+                               ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       SizeChangingUpsertTransfersAndReleasesReplacementCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+    PutComplete(service, client_id, "key", tenant_id, 100);
+
+    auto upsert =
+        service.UpsertStart(client_id, "key", tenant_id, 200, MemoryConfig());
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 300);
+
+    auto end =
+        service.UpsertEnd(client_id, "key", tenant_id, ReplicaType::MEMORY);
+    ASSERT_TRUE(end.has_value()) << toString(end.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 200);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       SizeChangingUpsertFromDiskOnlyObjectChargesNewReplica) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+
+    StorageObjectMetadata metadata;
+    metadata.data_size = 100;
+    metadata.transport_endpoint = "disk-endpoint";
+    std::vector<OffloadTaskItem> tasks{OffloadTaskItem{
+        .tenant_id = tenant_id.value(), .key = "key", .size = 100}};
+    ASSERT_TRUE(
+        service.NotifyOffloadSuccess(client_id, tasks, {metadata}).has_value());
+    ASSERT_EQ(Snapshot(service, tenant_id).charged_bytes, 0);
+
+    auto upsert =
+        service.UpsertStart(client_id, "key", tenant_id, 200, MemoryConfig());
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 200);
+
+    auto end =
+        service.UpsertEnd(client_id, "key", tenant_id, ReplicaType::MEMORY);
+    ASSERT_TRUE(end.has_value()) << toString(end.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 200);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       SizeChangingUpsertRevokeReleasesNewAndReplacementCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+    PutComplete(service, client_id, "key", tenant_id, 100);
+
+    auto upsert =
+        service.UpsertStart(client_id, "key", tenant_id, 200, MemoryConfig());
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 300);
+
+    auto revoke =
+        service.UpsertRevoke(client_id, "key", tenant_id, ReplicaType::MEMORY);
+    ASSERT_TRUE(revoke.has_value()) << toString(revoke.error());
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       PartialProcessingExpirySettlesPendingCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+
+    auto start =
+        service.PutStart(client_id, "key", tenant_id, 100, MemoryConfig());
+    ASSERT_TRUE(start.has_value()) << toString(start.error());
+    AddCompletedDiskReplica(service, client_id, "key", tenant_id, 100);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 100);
+
+    DiscardExpiredProcessingForTest(service, tenant_id, "key");
+
+    ExpectDiskOnlyObjectAndChargedBytes(service, tenant_id, "key", 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       DurablePartialProcessingExpirySettlesPendingCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+
+    auto start =
+        service.PutStart(client_id, "key", tenant_id, 100, MemoryConfig());
+    ASSERT_TRUE(start.has_value()) << toString(start.error());
+    AddCompletedDiskReplica(service, client_id, "key", tenant_id, 100);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 100);
+
+    FinalizeExpiredProcessingForTest(service, tenant_id, "key");
+
+    ExpectDiskOnlyObjectAndChargedBytes(service, tenant_id, "key", 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       PartialSizeChangingUpsertRevokeReleasesReplacementCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+    PutComplete(service, client_id, "key", tenant_id, 100);
+
+    auto upsert =
+        service.UpsertStart(client_id, "key", tenant_id, 200, MemoryConfig());
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+    AddCompletedDiskReplica(service, client_id, "key", tenant_id, 200);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 300);
+
+    auto revoke =
+        service.UpsertRevoke(client_id, "key", tenant_id, ReplicaType::MEMORY);
+
+    ASSERT_TRUE(revoke.has_value()) << toString(revoke.error());
+    ExpectDiskOnlyObjectAndChargedBytes(service, tenant_id, "key", 0);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       DurablePartialUpsertRevokeReleasesReplacementCharge) {
+    const TenantId tenant_id("tenant-a");
+    MasterService service(MakeConfig({{tenant_id, 1000}}));
+    UUID client_id = MountSegment(service);
+    PutComplete(service, client_id, "key", tenant_id, 100);
+
+    auto upsert =
+        service.UpsertStart(client_id, "key", tenant_id, 200, MemoryConfig());
+    ASSERT_TRUE(upsert.has_value()) << toString(upsert.error());
+    AddCompletedDiskReplica(service, client_id, "key", tenant_id, 200);
+    EXPECT_EQ(Snapshot(service, tenant_id).charged_bytes, 300);
+
+    FinalizeRemovedMemoryReplicasForTest(service, tenant_id, "key");
+
+    ExpectDiskOnlyObjectAndChargedBytes(service, tenant_id, "key", 0);
+}
+
 TEST_F(MasterServiceTenantQuotaTest, CopyStartRequiresQuotaForNewReplica) {
     MasterService service(MakeConfig({{TenantId("tenant-a"), 150}}));
     UUID client_id = MountSegment(service, /*size=*/1024, "segment-a");
@@ -578,13 +901,10 @@ TEST_F(MasterServiceTenantQuotaTest, CopyStartRequiresQuotaForNewReplica) {
     ASSERT_FALSE(copy.has_value());
     EXPECT_EQ(copy.error(), ErrorCode::TENANT_QUOTA_EXCEEDED);
     auto snapshot = Snapshot(service, TenantId("tenant-a"));
-    EXPECT_EQ(snapshot.used_bytes, 100);
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
-    EXPECT_EQ(snapshot.committed_count, 1);
+    EXPECT_EQ(snapshot.charged_bytes, 100);
 }
 
-TEST_F(MasterServiceTenantQuotaTest,
-       CopyEndCommitsAdditionalReplicaWithoutExtraObjectCount) {
+TEST_F(MasterServiceTenantQuotaTest, CopyEndRetainsAdditionalReplicaCharge) {
     MasterService service(MakeConfig({{TenantId("tenant-a"), 300}}));
     UUID client_id = MountSegment(service, /*size=*/1024, "segment-a");
     MountSegment(service, /*size=*/1024, "segment-b");
@@ -603,16 +923,38 @@ TEST_F(MasterServiceTenantQuotaTest,
                                   "segment-a", {"segment-b"});
     ASSERT_TRUE(copy.has_value()) << toString(copy.error());
     auto in_flight = Snapshot(service, TenantId("tenant-a"));
-    EXPECT_EQ(in_flight.used_bytes, 100);
-    EXPECT_EQ(in_flight.reserved_bytes, 100);
+    EXPECT_EQ(in_flight.charged_bytes, 200);
 
     ASSERT_TRUE(
         service.CopyEnd(client_id, "key", TenantId("tenant-a")).has_value());
     auto completed = Snapshot(service, TenantId("tenant-a"));
-    EXPECT_EQ(completed.used_bytes, 200);
-    EXPECT_EQ(completed.reserved_bytes, 0);
-    EXPECT_EQ(completed.committed_count, 1);
-    EXPECT_EQ(completed.metadata_object_count, 1);
+    EXPECT_EQ(completed.charged_bytes, 200);
+}
+
+TEST_F(MasterServiceTenantQuotaTest, CopyRevokeRefundsStartCharge) {
+    MasterService service(MakeConfig({{TenantId("tenant-a"), 300}}));
+    UUID client_id = MountSegment(service, /*size=*/1024, "segment-a");
+    MountSegment(service, /*size=*/1024, "segment-b");
+
+    ReplicateConfig config = MemoryConfig();
+    config.preferred_segment = "segment-a";
+    auto put_start =
+        service.PutStart(client_id, "key", TenantId("tenant-a"), 100, config);
+    ASSERT_TRUE(put_start.has_value()) << toString(put_start.error());
+    ASSERT_TRUE(
+        service
+            .PutEnd(client_id, "key", TenantId("tenant-a"), ReplicaType::MEMORY)
+            .has_value());
+
+    ASSERT_TRUE(service
+                    .CopyStart(client_id, "key", TenantId("tenant-a"),
+                               "segment-a", {"segment-b"})
+                    .has_value());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 200);
+
+    ASSERT_TRUE(
+        service.CopyRevoke(client_id, "key", TenantId("tenant-a")).has_value());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 100);
 }
 
 TEST_F(MasterServiceTenantQuotaTest,
@@ -637,8 +979,33 @@ TEST_F(MasterServiceTenantQuotaTest,
     ASSERT_FALSE(move.has_value());
     EXPECT_EQ(move.error(), ErrorCode::TENANT_QUOTA_EXCEEDED);
     auto snapshot = Snapshot(service, TenantId("tenant-a"));
-    EXPECT_EQ(snapshot.used_bytes, 100);
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
+    EXPECT_EQ(snapshot.charged_bytes, 100);
+}
+
+TEST_F(MasterServiceTenantQuotaTest, MoveEndSettlesToFinalReplicaCharge) {
+    MasterService service(MakeConfig({{TenantId("tenant-a"), 300}}));
+    UUID client_id = MountSegment(service, /*size=*/1024, "segment-a");
+    MountSegment(service, /*size=*/1024, "segment-b");
+
+    ReplicateConfig config = MemoryConfig();
+    config.preferred_segment = "segment-a";
+    ASSERT_TRUE(
+        service.PutStart(client_id, "key", TenantId("tenant-a"), 100, config)
+            .has_value());
+    ASSERT_TRUE(
+        service
+            .PutEnd(client_id, "key", TenantId("tenant-a"), ReplicaType::MEMORY)
+            .has_value());
+
+    ASSERT_TRUE(service
+                    .MoveStart(client_id, "key", TenantId("tenant-a"),
+                               "segment-a", "segment-b")
+                    .has_value());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 200);
+
+    ASSERT_TRUE(
+        service.MoveEnd(client_id, "key", TenantId("tenant-a")).has_value());
+    EXPECT_EQ(Snapshot(service, TenantId("tenant-a")).charged_bytes, 100);
 }
 
 TEST_F(MasterServiceTenantQuotaTest, DeletePolicyRequiresTenantWithoutObjects) {
@@ -659,7 +1026,7 @@ TEST_F(MasterServiceTenantQuotaTest, DeletePolicyRequiresTenantWithoutObjects) {
 }
 
 TEST_F(MasterServiceTenantQuotaTest,
-       DeletePolicyBlocksValidatedReservationsBeforeConnectorSave) {
+       DeletePolicyBlocksValidatedChargesBeforeConnectorSave) {
     MasterService service(MakeConfig({{TenantId("tenant-a"), 1000}}));
     MountSegment(service);
 
@@ -686,14 +1053,14 @@ TEST_F(MasterServiceTenantQuotaTest,
         FAIL() << "timed out waiting for connector save";
     }
 
-    auto reserve = ReserveTenantQuotaForTest(service, TenantId("tenant-a"), 1);
-    EXPECT_FALSE(reserve.has_value());
-    EXPECT_EQ(reserve.error(), ErrorCode::TENANT_NOT_REGISTERED);
+    auto charge = ChargeTenantQuotaForTest(service, TenantId("tenant-a"), 1);
+    EXPECT_FALSE(charge.has_value());
+    EXPECT_EQ(charge.error(), ErrorCode::TENANT_NOT_REGISTERED);
 
-    auto zero_byte_reserve =
-        ReserveTenantQuotaForTest(service, TenantId("tenant-a"), 0);
-    EXPECT_FALSE(zero_byte_reserve.has_value());
-    EXPECT_EQ(zero_byte_reserve.error(), ErrorCode::TENANT_NOT_REGISTERED);
+    auto zero_byte_charge =
+        ChargeTenantQuotaForTest(service, TenantId("tenant-a"), 0);
+    EXPECT_FALSE(zero_byte_charge.has_value());
+    EXPECT_EQ(zero_byte_charge.error(), ErrorCode::TENANT_NOT_REGISTERED);
 
     blocking_store_ptr->AllowSave();
     delete_thread.join();
@@ -766,7 +1133,7 @@ TEST_F(MasterServiceTenantQuotaTest,
 
 #ifdef USE_NOF
 TEST_F(MasterServiceTenantQuotaTest,
-       DeletePolicyWaitsForZeroChargePutStartMetadataCreate) {
+       DeletePolicySeesZeroChargePutStartMetadataCreateWithoutPolicyLock) {
     MasterService service(MakeConfig({{TenantId("tenant-a"), 1000}}));
     UUID client_id = MountNoFSegment(service);
 
@@ -781,6 +1148,7 @@ TEST_F(MasterServiceTenantQuotaTest,
 
     std::optional<tl::expected<std::vector<Replica::Descriptor>, ErrorCode>>
         put_result;
+    auto policy_lock = LockTenantQuotaPolicyForTest(service);
     std::thread put_thread([&] {
         put_result.emplace(service.PutStart(client_id, "nof-key",
                                             TenantId("tenant-a"), 128, config));
@@ -788,21 +1156,26 @@ TEST_F(MasterServiceTenantQuotaTest,
 
     if (allocation_started.wait_for(std::chrono::seconds(5)) !=
         std::future_status::ready) {
+        policy_lock.unlock();
         blocking_strategy_ptr->AllowAllocation();
         put_thread.join();
-        FAIL() << "timed out waiting for PutStart allocation";
+        FAIL() << "zero-charge PutStart waited for tenant quota policy mutex";
     }
+    policy_lock.unlock();
 
     using DeleteResult =
         tl::expected<std::optional<TenantQuotaSnapshot>, ErrorCode>;
-    std::optional<DeleteResult> delete_result;
+    std::promise<DeleteResult> delete_promise;
+    auto delete_future = delete_promise.get_future();
     std::thread delete_thread([&] {
-        delete_result.emplace(
+        delete_promise.set_value(
             service.DeleteTenantQuotaPolicy(TenantId("tenant-a")));
     });
 
-    ASSERT_TRUE(WaitForTenantQuotaPolicyMutexContention(service))
-        << "DeleteTenantQuotaPolicy did not wait for zero-charge PutStart";
+    EXPECT_EQ(delete_future.wait_for(std::chrono::milliseconds(200)),
+              std::future_status::timeout)
+        << "tenant deletion passed the metadata scan while zero-charge "
+           "PutStart still held the target metadata shard";
 
     blocking_strategy_ptr->AllowAllocation();
     put_thread.join();
@@ -810,14 +1183,12 @@ TEST_F(MasterServiceTenantQuotaTest,
 
     ASSERT_TRUE(put_result.has_value());
     ASSERT_TRUE(put_result->has_value()) << toString(put_result->error());
-    ASSERT_TRUE(delete_result.has_value());
-    ASSERT_FALSE(delete_result->has_value());
-    EXPECT_EQ(delete_result->error(), ErrorCode::TENANT_NOT_EMPTY);
+    auto delete_result = delete_future.get();
+    ASSERT_FALSE(delete_result.has_value());
+    EXPECT_EQ(delete_result.error(), ErrorCode::TENANT_NOT_EMPTY);
 
     auto snapshot = Snapshot(service, TenantId("tenant-a"));
-    EXPECT_EQ(snapshot.used_bytes, 0);
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
-    EXPECT_EQ(snapshot.metadata_object_count, 1);
+    EXPECT_EQ(snapshot.charged_bytes, 0);
 }
 #endif
 
@@ -903,4 +1274,124 @@ TEST_F(MasterServiceTenantQuotaTest,
                     .has_value());
 }
 
+// --- Tenant-scoped eviction watermark -------------------------------------
+//
+// This pass is the only thing that makes room for a tenant. A tenant whose
+// effective quota sits at or below the pool-wide eviction_high_watermark_ratio
+// reaches its own ceiling before the pool crosses the pool-wide watermark:
+// EvictionThreadFunc gates on a pool-global used_ratio (strictly greater), and
+// the quota path cannot arm it either -- need_mem_eviction_ is only set next to
+// inc_put_start_alloc_failures(), and a quota rejection returns before
+// allocation is attempted. Admission itself does not evict; it rejects with
+// TENANT_QUOTA_EXCEEDED and leaves the headroom to this pass.
+
+TEST_F(MasterServiceTenantQuotaTest, TenantEvictionWatermarkDefaultsToOn) {
+    const TenantId tenant("tenant-a");
+    // No explicit ratio: the tenant watermark must default to the same 0.90 as
+    // the pool-wide one, so a multi-tenant master gets the evict-to-make-room
+    // contract without having to opt in.
+    ASSERT_DOUBLE_EQ(DEFAULT_TENANT_EVICTION_HIGH_WATERMARK_RATIO,
+                     DEFAULT_EVICTION_HIGH_WATERMARK_RATIO);
+    MasterService service(MakeTenantWatermarkConfig({{tenant, 1000}},
+                                                    /*watermark=*/std::nullopt,
+                                                    /*eviction_ratio=*/0.05));
+    UUID client_id = MountSegment(service, /*size=*/4096);
+
+    for (int i = 0; i < 4; ++i) {
+        PutComplete(service, client_id, "key-" + std::to_string(i), tenant,
+                    240);
+    }
+    ASSERT_EQ(Snapshot(service, tenant).charged_bytes, 960u);  // 0.96 > 0.90
+
+    RunTenantEvictionPass(service);
+
+    EXPECT_LE(Snapshot(service, tenant).charged_bytes, 850u)
+        << "the pass must run without an explicit watermark setting";
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       TenantEvictionWatermarkOfZeroDisablesThePass) {
+    const TenantId tenant("tenant-a");
+    // Watermark 0.0 == the pre-existing behaviour, and remains available as an
+    // opt-out.
+    MasterService service(MakeTenantWatermarkConfig({{tenant, 1000}},
+                                                    /*watermark=*/0.0));
+    UUID client_id = MountSegment(service, /*size=*/4096);
+
+    for (int i = 0; i < 4; ++i) {
+        PutComplete(service, client_id, "key-" + std::to_string(i), tenant,
+                    240);
+    }
+    ASSERT_EQ(Snapshot(service, tenant).charged_bytes, 960u);
+
+    RunTenantEvictionPass(service);
+
+    EXPECT_EQ(Snapshot(service, tenant).charged_bytes, 960u)
+        << "the pass must not run when the watermark is 0";
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       TenantEvictionWatermarkLeavesTenantsBelowItAlone) {
+    const TenantId tenant("tenant-a");
+    MasterService service(MakeTenantWatermarkConfig({{tenant, 1000}},
+                                                    /*watermark=*/0.9));
+    UUID client_id = MountSegment(service, /*size=*/4096);
+
+    for (int i = 0; i < 4; ++i) {
+        PutComplete(service, client_id, "key-" + std::to_string(i), tenant,
+                    200);
+    }
+    ASSERT_EQ(Snapshot(service, tenant).charged_bytes, 800u);  // 0.80
+
+    RunTenantEvictionPass(service);
+
+    EXPECT_EQ(Snapshot(service, tenant).charged_bytes, 800u);
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       TenantEvictionWatermarkEvictsDownToTargetRatio) {
+    const TenantId tenant("tenant-a");
+    // watermark 0.9, eviction_ratio 0.05 -> evict down to 0.85 of the quota.
+    MasterService service(MakeTenantWatermarkConfig({{tenant, 1000}},
+                                                    /*watermark=*/0.9,
+                                                    /*eviction_ratio=*/0.05));
+    UUID client_id = MountSegment(service, /*size=*/4096);
+
+    for (int i = 0; i < 4; ++i) {
+        PutComplete(service, client_id, "key-" + std::to_string(i), tenant,
+                    240);
+    }
+    ASSERT_EQ(Snapshot(service, tenant).charged_bytes, 960u);  // 0.96 > 0.90
+
+    RunTenantEvictionPass(service);
+
+    const uint64_t charged = Snapshot(service, tenant).charged_bytes;
+    EXPECT_LT(charged, 960u) << "tenant was over its watermark and not evicted";
+    EXPECT_LE(charged, 850u) << "must reach (watermark - eviction_ratio)";
+}
+
+TEST_F(MasterServiceTenantQuotaTest,
+       TenantEvictionWatermarkOnlyTouchesTenantsOverIt) {
+    const TenantId hot("tenant-hot");
+    const TenantId cold("tenant-cold");
+    // Sum of requested (2000) is below capacity, so each tenant gets its
+    // literal quota rather than a proportional share.
+    MasterService service(MakeTenantWatermarkConfig({{hot, 1000}, {cold, 1000}},
+                                                    /*watermark=*/0.9));
+    UUID client_id = MountSegment(service, /*size=*/8192);
+
+    for (int i = 0; i < 4; ++i) {
+        PutComplete(service, client_id, "hot-" + std::to_string(i), hot, 240);
+        PutComplete(service, client_id, "cold-" + std::to_string(i), cold, 100);
+    }
+    ASSERT_EQ(Snapshot(service, hot).charged_bytes, 960u);   // 0.96
+    ASSERT_EQ(Snapshot(service, cold).charged_bytes, 400u);  // 0.40
+
+    RunTenantEvictionPass(service);
+
+    EXPECT_LE(Snapshot(service, hot).charged_bytes, 850u);
+    EXPECT_EQ(Snapshot(service, cold).charged_bytes, 400u)
+        << "a tenant under its own watermark must not pay for a noisy one";
+}
+
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_tenant_scenario_test.cpp b/mooncake-store/tests/master_service_tenant_scenario_test.cpp
new file mode 100644
index 0000000000..48f0a47e72
--- /dev/null
+++ b/mooncake-store/tests/master_service_tenant_scenario_test.cpp
@@ -0,0 +1,233 @@
+#include "master_service/dsl/scenario.h"
+
+#include <gtest/gtest.h>
+
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+std::string DefaultTenant() { return std::string(TenantId::kDefaultValue); }
+
+}  // namespace
+
+TEST(MasterServiceTenantScenarioTest, TenantPutGetRemoveIsolatesSameUserKey) {
+    const std::string key = "shared_user_key";
+    MasterScenario("tenants isolate the same user key")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("tenant_a"))
+        .Given(Tenant("tenant_b"))
+        .When(PutStart(key, 1_KB).ForTenant("tenant_a"))
+        .When(PutEnd(key).ForTenant("tenant_a"))
+        .When(PutStart(key, 2_KB).ForTenant("tenant_b"))
+        .When(PutEnd(key).ForTenant("tenant_b"))
+        .Then(Object(key).DoesNotExist())
+        .Then(KeyExists(key).ForTenant("tenant_a"))
+        .Then(KeyExists(key).ForTenant("tenant_b"))
+        .Then(Object(key).ForTenant("tenant_a").IsReadable())
+        .Then(Object(key).ForTenant("tenant_b").IsReadable())
+        .When(Remove(key).ForTenant("tenant_a").Force())
+        .Then(Object(key).ForTenant("tenant_a").DoesNotExist())
+        .Then(Object(key).ForTenant("tenant_b").IsReadable());
+}
+
+TEST(MasterServiceTenantScenarioTest, RegexOperationsAreTenantScoped) {
+    const std::string key = "regex_shared_key";
+    MasterScenario("regex operations are tenant scoped")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("tenant_regex_a"))
+        .Given(Tenant("tenant_regex_b"))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .When(PutStart(key, 1_KB).ForTenant("tenant_regex_a"))
+        .When(PutEnd(key).ForTenant("tenant_regex_a"))
+        .When(PutStart(key, 1_KB).ForTenant("tenant_regex_b"))
+        .When(PutEnd(key).ForTenant("tenant_regex_b"))
+        .Then(MatchingKeys("^regex_shared").HasCount(1))
+        .When(RemoveByRegex("^regex_shared").Force().ExpectRemoved(1))
+        .Then(Object(key).DoesNotExist())
+        .Then(Object(key).ForTenant("tenant_regex_a").IsReadable())
+        .Then(Object(key).ForTenant("tenant_regex_b").IsReadable())
+        .When(RemoveByRegex("^regex_shared")
+                  .ForTenant("tenant_regex_a")
+                  .Force()
+                  .ExpectRemoved(1))
+        .Then(Object(key).ForTenant("tenant_regex_a").DoesNotExist())
+        .Then(Object(key).ForTenant("tenant_regex_b").IsReadable());
+}
+
+TEST(MasterServiceTenantScenarioTest, TenantBatchUpsertAndRevokeAreScoped) {
+    const std::string key_a = "tenant_batch_upsert_key_a";
+    const std::string key_b = "tenant_batch_upsert_key_b";
+    MasterScenario scenario("batch upsert and revoke are tenant scoped");
+    scenario.Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("tenant_batch_upsert_a"))
+        .Given(Tenant("tenant_batch_upsert_b"))
+        .When(BatchUpsertStart({{key_a, 1_KB}, {key_b, 2_KB}})
+                  .ForTenant("tenant_batch_upsert_a"))
+        .When(BatchUpsertEnd({key_a, key_b}).ForTenant("tenant_batch_upsert_a"))
+        .When(BatchUpsertStart({{key_a, 1_KB}, {key_b, 2_KB}})
+                  .ForTenant("tenant_batch_upsert_b"))
+        .When(
+            BatchUpsertEnd({key_a, key_b}).ForTenant("tenant_batch_upsert_b"));
+    for (const auto& key : {key_a, key_b}) {
+        scenario.Then(Object(key).DoesNotExist())
+            .Then(Object(key).ForTenant("tenant_batch_upsert_a").IsReadable())
+            .Then(Object(key).ForTenant("tenant_batch_upsert_b").IsReadable());
+    }
+    scenario
+        .When(UpsertStart("tenant_batch_upsert_revoke_key", 1_KB)
+                  .ForTenant("tenant_batch_upsert_a"))
+        .When(UpsertRevoke("tenant_batch_upsert_revoke_key")
+                  .ForTenant("tenant_batch_upsert_a"))
+        .Then(Object("tenant_batch_upsert_revoke_key")
+                  .ForTenant("tenant_batch_upsert_a")
+                  .DoesNotExist());
+}
+
+TEST(MasterServiceTenantScenarioTest, TenantBatchRemoveAndRemoveAllAreScoped) {
+    const std::string key = "tenant_batch_remove_shared_key";
+    MasterScenario("batch remove and remove all are tenant scoped")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("tenant_batch_remove_a"))
+        .Given(Tenant("tenant_batch_remove_b"))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .When(PutStart(key, 1_KB).ForTenant("tenant_batch_remove_a"))
+        .When(PutEnd(key).ForTenant("tenant_batch_remove_a"))
+        .When(PutStart(key, 1_KB).ForTenant("tenant_batch_remove_b"))
+        .When(PutEnd(key).ForTenant("tenant_batch_remove_b"))
+        .When(BatchRemove({key}).ForTenant("tenant_batch_remove_a").Force())
+        .Then(Object(key).ForTenant("tenant_batch_remove_a").DoesNotExist())
+        .Then(Object(key).IsReadable())
+        .Then(Object(key).ForTenant("tenant_batch_remove_b").IsReadable())
+        .When(RemoveAll()
+                  .ForTenant("tenant_batch_remove_b")
+                  .Force()
+                  .ExpectRemoved(1))
+        .Then(Object(key).ForTenant("tenant_batch_remove_b").DoesNotExist())
+        .Then(Object(key).IsReadable())
+        .When(RemoveAll().Force().ExpectRemoved(1))
+        .Then(Object(key).DoesNotExist());
+}
+
+TEST(MasterServiceTenantScenarioTest, LegacyRemoveAllRemovesAllTenants) {
+    const std::string key = "legacy_remove_all_shared_key";
+    MasterScenario("legacy remove all removes objects across tenants")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("legacy_remove_all_a"))
+        .Given(Tenant("legacy_remove_all_b"))
+        .When(PutStart(key, 1_KB))
+        .When(PutEnd(key))
+        .When(PutStart(key, 1_KB).ForTenant("legacy_remove_all_a"))
+        .When(PutEnd(key).ForTenant("legacy_remove_all_a"))
+        .When(PutStart(key, 1_KB).ForTenant("legacy_remove_all_b"))
+        .When(PutEnd(key).ForTenant("legacy_remove_all_b"))
+        .When(RemoveAll().Force().ExpectRemoved(3))
+        .Then(Object(key).DoesNotExist())
+        .Then(Object(key).ForTenant("legacy_remove_all_a").DoesNotExist())
+        .Then(Object(key).ForTenant("legacy_remove_all_b").DoesNotExist())
+        .When(RemoveAll().Force().ExpectRemoved(0));
+}
+
+TEST(MasterServiceTenantScenarioTest, BatchExistKeyTenantAwarePreservesOrder) {
+    const std::string tenant_only_key = "batch_tenant_only";
+    const std::string default_only_key = "batch_default_only";
+    const std::string incomplete_key = "batch_tenant_incomplete";
+    const std::string missing_key = "batch_tenant_missing";
+    MasterScenario("batch exist key is tenant aware and preserves order")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("tenant_batch_exist"))
+        .When(PutStart(tenant_only_key, 1_KB).ForTenant("tenant_batch_exist"))
+        .When(PutEnd(tenant_only_key).ForTenant("tenant_batch_exist"))
+        .When(PutStart(default_only_key, 1_KB))
+        .When(PutEnd(default_only_key))
+        .When(PutStart(incomplete_key, 1_KB).ForTenant("tenant_batch_exist"))
+        .Then(BatchExistence({tenant_only_key, default_only_key, missing_key,
+                              incomplete_key, tenant_only_key})
+                  .ForTenant("tenant_batch_exist")
+                  .Returns({true, false, false, false, true}))
+        .Then(BatchExistence({tenant_only_key, default_only_key})
+                  .Returns({false, true}));
+}
+
+TEST(MasterServiceTenantScenarioTest, BatchGetReplicaListKeepsTenantIsolation) {
+    const std::string key = "batch_get_tenant_shared_key";
+    MasterScenario("batch get replica list keeps tenant isolation")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant(DefaultTenant()))
+        .Given(Tenant("batch_get_tenant_a"))
+        .Given(Tenant("batch_get_tenant_b"))
+        .When(PutStart(key, 1_KB)
+                  .ForTenant("batch_get_tenant_a")
+                  .InGroup(GroupOnDifferentShard(key)))
+        .When(PutEnd(key).ForTenant("batch_get_tenant_a"))
+        .When(PutStart(key, 2_KB).ForTenant("batch_get_tenant_b"))
+        .When(PutEnd(key).ForTenant("batch_get_tenant_b"))
+        .Then(BatchReplicaLists({key})
+                  .ForTenant("batch_get_tenant_a")
+                  .Returns({ErrorCode::OK}))
+        .Then(BatchReplicaLists({key})
+                  .ForTenant("batch_get_tenant_b")
+                  .Returns({ErrorCode::OK}))
+        .Then(BatchReplicaLists({key}).Returns({ErrorCode::OBJECT_NOT_FOUND}));
+}
+
+TEST(MasterServiceTenantScenarioTest,
+     TenantQuotaAdmissionRejectsPutsOverQuota) {
+    MasterScenario("tenant quota rejects puts over the registered quota")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant("tenant_quota_admission").Quota(100))
+        .When(PutStart("quota_key_a", 80)
+                  .ForTenant("tenant_quota_admission")
+                  .WithHardPin())
+        .When(PutEnd("quota_key_a").ForTenant("tenant_quota_admission"))
+        .When(PutStart("quota_key_b", 30)
+                  .ForTenant("tenant_quota_admission")
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED))
+        .Then(Object("quota_key_a")
+                  .ForTenant("tenant_quota_admission")
+                  .IsReadable());
+}
+
+TEST(MasterServiceTenantScenarioTest, PutRevokeRefundsQuotaCharge) {
+    MasterScenario("put revoke refunds the quota charged at start")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant("tenant_quota_refund").Quota(100))
+        .When(
+            PutStart("quota_refund_key", 100).ForTenant("tenant_quota_refund"))
+        .When(PutStart("quota_refund_other", 1)
+                  .ForTenant("tenant_quota_refund")
+                  .ExpectError(ErrorCode::TENANT_QUOTA_EXCEEDED))
+        .When(PutRevoke("quota_refund_key").ForTenant("tenant_quota_refund"))
+        .When(
+            PutStart("quota_refund_other", 1).ForTenant("tenant_quota_refund"))
+        .When(PutEnd("quota_refund_other").ForTenant("tenant_quota_refund"))
+        .Then(Object("quota_refund_other")
+                  .ForTenant("tenant_quota_refund")
+                  .IsReadable());
+}
+
+TEST(MasterServiceTenantScenarioTest, UnregisteredTenantWritesAreRejected) {
+    MasterScenario("multi tenant mode rejects unregistered tenant writes")
+        .Given(MemoryNode("memory"))
+        .Given(Tenant("tenant_registered"))
+        .When(PutStart("unregistered_key", 1_KB)
+                  .ForTenant("tenant_unregistered")
+                  .ExpectError(ErrorCode::TENANT_NOT_REGISTERED))
+        .When(PutStart("implicit_default_key", 1_KB)
+                  .ExpectError(ErrorCode::TENANT_NOT_REGISTERED))
+        .When(PutStart("registered_key", 1_KB).ForTenant("tenant_registered"))
+        .When(PutEnd("registered_key").ForTenant("tenant_registered"))
+        .Then(Object("registered_key")
+                  .ForTenant("tenant_registered")
+                  .IsReadable());
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_test.cpp b/mooncake-store/tests/master_service_test.cpp
index f8c453cbdc..9d04dda967 100644
--- a/mooncake-store/tests/master_service_test.cpp
+++ b/mooncake-store/tests/master_service_test.cpp
@@ -1,4 +1,5 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 #include "rpc_service.h"
 
 #include <glog/logging.h>
@@ -7,6 +8,7 @@
 
 #include <algorithm>
 #include <atomic>
+#include <barrier>
 #include <chrono>
 #include <cstdlib>
 #include <filesystem>
@@ -14,8 +16,8 @@
 #include <functional>
 #include <map>
 #include <memory>
+#include <limits>
 #include <optional>
-#include <random>
 #include <string>
 #include <thread>
 #include <utility>
@@ -26,19 +28,10 @@
 
 #include "tenant_quota_policy_store.h"
 #include "types.h"
-#include "utils.h"
+#include "master_service_test_fixture.h"
 
 namespace mooncake::test {
 
-std::vector<ObjectMeta> MakeObjectMetas(const std::vector<std::string>& keys) {
-    std::vector<ObjectMeta> object_metas;
-    object_metas.reserve(keys.size());
-    for (const auto& key : keys) {
-        object_metas.emplace_back(ObjectMeta{key, std::nullopt});
-    }
-    return object_metas;
-}
-
 class ScopedEnvVar {
    public:
     explicit ScopedEnvVar(const char* name) : name_(name) {
@@ -71,305 +64,6 @@ class ScopedEnvVar {
     std::optional<std::string> previous_value_;
 };
 
-class MasterServiceTest : public ::testing::Test {
-   protected:
-    void SetUp() override {
-        google::InitGoogleLogging("MasterServiceTest");
-        FLAGS_logtostderr = true;
-    }
-
-    struct MountedSegmentContext {
-        UUID segment_id;
-        UUID client_id;
-    };
-
-    static constexpr size_t kDefaultSegmentBase = 0x300000000;
-    static constexpr size_t kDefaultSegmentSize = 1024 * 1024 * 16;
-    static constexpr uint64_t kStrictTenantQuotaBytes = 4 * 1024 * 1024;
-
-    std::string WriteTenantPolicyFile(
-        const std::map<std::string, uint64_t>& tenant_quotas) {
-        TenantQuotaPolicySnapshot snapshot;
-        snapshot.tenant_quotas = tenant_quotas;
-        auto path =
-            std::filesystem::temp_directory_path() /
-            ("mooncake_master_service_test_" + std::to_string(::getpid()) +
-             "_" + std::to_string(next_policy_file_++) + ".yaml");
-        std::ofstream out(path);
-        out << FormatTenantQuotaPolicyYaml(snapshot);
-        out.close();
-        policy_files_.push_back(path.string());
-        return path.string();
-    }
-
-    MasterServiceConfig MakeStrictTenantConfig(
-        const std::vector<std::string>& tenants) {
-        std::map<std::string, uint64_t> tenant_quotas;
-        for (const auto& tenant : tenants) {
-            tenant_quotas.emplace(tenant, kStrictTenantQuotaBytes);
-        }
-        return MasterServiceConfig::builder()
-            .set_enable_multi_tenants(true)
-            .set_tenant_quota_connector_type("file")
-            .set_tenant_quota_connector_uri(
-                WriteTenantPolicyFile(tenant_quotas))
-            .build();
-    }
-
-    WrappedMasterServiceConfig MakeStrictWrappedConfig(
-        const std::vector<std::string>& tenants) {
-        WrappedMasterServiceConfig config;
-        config.default_kv_lease_ttl = 100;
-        config.enable_metric_reporting = false;
-        config.enable_multi_tenants = true;
-        config.tenant_quota_connector_type = "file";
-        std::map<std::string, uint64_t> tenant_quotas;
-        for (const auto& tenant : tenants) {
-            tenant_quotas.emplace(tenant, kStrictTenantQuotaBytes);
-        }
-        config.tenant_quota_connector_uri =
-            WriteTenantPolicyFile(tenant_quotas);
-        return config;
-    }
-
-    Segment MakeSegment(std::string name = "test_segment",
-                        size_t base = kDefaultSegmentBase,
-                        size_t size = kDefaultSegmentSize,
-                        std::string host_id = "") const {
-        Segment segment;
-        segment.id = generate_uuid();
-        segment.name = std::move(name);
-        segment.base = base;
-        segment.size = size;
-        segment.te_endpoint = segment.name;
-        segment.host_id = std::move(host_id);
-        return segment;
-    }
-
-#ifdef USE_NOF
-    NoFSegment MakeNoFSegment(
-        std::string name = "test_nof_segment",
-        std::string endpoint = "test_nof_segment_endpoint",
-        size_t base = kDefaultSegmentBase + kDefaultSegmentSize,
-        size_t size = kDefaultSegmentSize) const {
-        NoFSegment segment;
-        segment.id = generate_uuid();
-        segment.name = std::move(name);
-        segment.base = base;
-        segment.size = size;
-        segment.te_endpoint = std::move(endpoint);
-        return segment;
-    }
-#endif
-
-    MountedSegmentContext PrepareSimpleSegment(
-        MasterService& service, std::string name = "test_segment",
-        size_t base = kDefaultSegmentBase, size_t size = kDefaultSegmentSize,
-        std::string host_id = "") const {
-        Segment segment =
-            MakeSegment(std::move(name), base, size, std::move(host_id));
-        UUID client_id = generate_uuid();
-        auto mount_result = service.MountSegment(segment, client_id);
-        EXPECT_TRUE(mount_result.has_value());
-        return {.segment_id = segment.id, .client_id = client_id};
-    }
-
-    std::string PutObjectOnSegment(MasterService& service,
-                                   const UUID& client_id,
-                                   const std::string& segment_name,
-                                   size_t slice_length = 1024) const {
-        static std::atomic<uint64_t> counter{0};
-        std::string key =
-            "drain_job_key_" + std::to_string(counter.fetch_add(1));
-
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.preferred_segment = segment_name;
-
-        auto put_start = service.PutStart(client_id, key, TenantId::Default(),
-                                          slice_length, config);
-        EXPECT_TRUE(put_start.has_value());
-        EXPECT_TRUE(service
-                        .PutEnd(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                        .has_value());
-        return key;
-    }
-
-    std::string FindGroupIdOnDifferentShard(const std::string& key) const {
-        static constexpr size_t kMetadataShardCountForTest = 1024;
-        const size_t key_shard =
-            std::hash<std::string>{}(key) % kMetadataShardCountForTest;
-        for (int i = 0; i < 10000; ++i) {
-            std::string group_id = key + "_group_" + std::to_string(i);
-            if (std::hash<std::string>{}(group_id) %
-                    kMetadataShardCountForTest !=
-                key_shard) {
-                return group_id;
-            }
-        }
-        return key + "_fallback_group";
-    }
-
-    void PutCompletedObject(MasterService& service, const UUID& client_id,
-                            const std::string& key,
-                            const ReplicateConfig& config,
-                            uint64_t slice_length = 1024) const {
-        auto put_start = service.PutStart(client_id, key, TenantId::Default(),
-                                          slice_length, config);
-        ASSERT_TRUE(put_start.has_value())
-            << "PutStart failed for key=" << key
-            << ", error=" << toString(put_start.error());
-        ASSERT_TRUE(service
-                        .PutEnd(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                        .has_value());
-    }
-
-    void PutCompletedObject(MasterService& service, const UUID& client_id,
-                            const std::string& key, const TenantId& tenant_id,
-                            const ReplicateConfig& config,
-                            uint64_t slice_length = 1024) const {
-        auto put_start =
-            service.PutStart(client_id, key, tenant_id, slice_length, config);
-        ASSERT_TRUE(put_start.has_value())
-            << "PutStart failed for key=" << key << ", tenant_id=" << tenant_id
-            << ", error=" << toString(put_start.error());
-        ASSERT_TRUE(
-            service.PutEnd(client_id, key, tenant_id, ReplicaType::MEMORY)
-                .has_value());
-    }
-
-    bool ExecutePendingMoveTasks(MasterService& service,
-                                 const UUID& client_id) const {
-        auto fetched = service.FetchTasks(client_id, /*batch_size=*/16);
-        EXPECT_TRUE(fetched.has_value());
-        if (!fetched.has_value() || fetched->empty()) {
-            return false;
-        }
-
-        bool processed = false;
-        for (const auto& assignment : *fetched) {
-            if (assignment.type != TaskType::REPLICA_MOVE) {
-                continue;
-            }
-
-            ReplicaMovePayload payload;
-            struct_json::from_json(payload, assignment.payload);
-
-            const TenantId tenant_id(payload.tenant_id);
-            EXPECT_TRUE(tenant_id.IsValid());
-            if (!tenant_id.IsValid()) {
-                return false;
-            }
-            auto move_start =
-                service.MoveStart(client_id, payload.key, tenant_id,
-                                  payload.source, payload.target);
-            EXPECT_TRUE(move_start.has_value());
-            EXPECT_TRUE(
-                service.MoveEnd(client_id, payload.key, tenant_id).has_value());
-
-            TaskCompleteRequest complete_request;
-            complete_request.id = assignment.id;
-            complete_request.status = TaskStatus::SUCCESS;
-            complete_request.message = "move_done";
-            EXPECT_TRUE(service.MarkTaskToComplete(client_id, complete_request)
-                            .has_value());
-            processed = true;
-        }
-        return processed;
-    }
-
-    bool FailPendingMoveTasks(MasterService& service,
-                              const UUID& client_id) const {
-        auto fetched = service.FetchTasks(client_id, /*batch_size=*/16);
-        EXPECT_TRUE(fetched.has_value());
-        if (!fetched.has_value() || fetched->empty()) {
-            return false;
-        }
-
-        bool processed = false;
-        for (const auto& assignment : *fetched) {
-            if (assignment.type != TaskType::REPLICA_MOVE) {
-                continue;
-            }
-
-            TaskCompleteRequest complete_request;
-            complete_request.id = assignment.id;
-            complete_request.status = TaskStatus::FAILED;
-            complete_request.message = "move_failed";
-            EXPECT_TRUE(service.MarkTaskToComplete(client_id, complete_request)
-                            .has_value());
-            processed = true;
-        }
-        return processed;
-    }
-
-    template <typename Predicate>
-    void WaitUntil(
-        Predicate&& predicate,
-        std::chrono::milliseconds timeout = std::chrono::milliseconds(4000),
-        std::chrono::milliseconds interval =
-            std::chrono::milliseconds(50)) const {
-        const auto deadline = std::chrono::steady_clock::now() + timeout;
-        while (std::chrono::steady_clock::now() < deadline) {
-            if (predicate()) {
-                return;
-            }
-            std::this_thread::sleep_for(interval);
-        }
-        EXPECT_TRUE(predicate());
-    }
-
-    std::vector<Replica::Descriptor> replica_list;
-    std::vector<std::string> policy_files_;
-    size_t next_policy_file_ = 0;
-
-    void TearDown() override {
-        for (const auto& path : policy_files_) {
-            std::error_code ec;
-            std::filesystem::remove(path, ec);
-        }
-        google::ShutdownGoogleLogging();
-    }
-};
-
-TEST_F(MasterServiceTest, ObjectChecksumIsStoredAndClearedByUpsert) {
-    MasterService service;
-    const auto segment = PrepareSimpleSegment(service, "checksum_segment");
-    const std::string key = "checksum_key";
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "checksum_segment";
-
-    ASSERT_TRUE(
-        service
-            .PutStart(segment.client_id, key, TenantId::Default(), 1024, config)
-            .has_value());
-    constexpr uint64_t kChecksum = 0;
-    ASSERT_TRUE(service
-                    .PutEnd(segment.client_id, ObjectMeta{key, kChecksum},
-                            TenantId::Default(), ReplicaType::MEMORY)
-                    .has_value());
-
-    auto query = service.GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(query.has_value());
-    ASSERT_TRUE(query->object_checksum.has_value());
-    EXPECT_EQ(*query->object_checksum, kChecksum);
-
-    ASSERT_TRUE(service
-                    .UpsertStart(segment.client_id, key, TenantId::Default(),
-                                 1024, config)
-                    .has_value());
-    ASSERT_TRUE(service
-                    .UpsertEnd(segment.client_id, ObjectMeta{key, std::nullopt},
-                               TenantId::Default(), ReplicaType::MEMORY)
-                    .has_value());
-    query = service.GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(query.has_value());
-    EXPECT_FALSE(query->object_checksum.has_value());
-}
-
 TEST(TenantScopedStorageKeyTest, RoundTripsAndParsesLegacyKeys) {
     const auto scoped =
         TenantId("tenant:with:colon").MakeScopedKey("path/key:with:colon");
@@ -571,101 +265,57 @@ TEST_F(MasterServiceTest, MountUnmountSegmentWithOffsetAllocator) {
     EXPECT_TRUE(unmount_result4.has_value());
 }
 
-TEST_F(MasterServiceTest, RandomMountUnmountSegment) {
-    // Create a MasterService instance for testing.
-    std::unique_ptr<MasterService> service_(new MasterService());
-    // Define a constant buffer address for the segment.
-    constexpr size_t kBufferAddress = 0x300000000;
-    // Define the name of the test segment.
-    std::string segment_name = "test_random_segment";
-    UUID segment_id = generate_uuid();
-    UUID client_id = generate_uuid();
-    size_t times = 10;
-    std::random_device rd;
-    std::mt19937 gen(rd());
-    std::uniform_int_distribution<> dis(1, 10);
-    while (times--) {
-        int random_number = dis(gen);
-        // Define the size of the segment (16MB).
-        size_t kSegmentSize = 1024 * 1024 * 16 * random_number;
-
-        auto segment = MakeSegment(segment_name, kBufferAddress, kSegmentSize);
-        segment.id = segment_id;
-
-        // Test remounting after unmount.
-        auto mount_result = service_->MountSegment(segment, client_id);
-        EXPECT_TRUE(mount_result.has_value());
-        auto unmount_result = service_->UnmountSegment(segment.id, client_id);
-        EXPECT_TRUE(unmount_result.has_value());
-    }
-}
-
-TEST_F(MasterServiceTest, ConcurrentMountUnmount) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    constexpr size_t num_threads = 4;
-    constexpr size_t iterations = 100;
-    std::vector<std::thread> threads;
-    std::atomic<int> success_count{0};
-
-    // Launch multiple threads to mount/unmount segments concurrently
-    for (size_t i = 0; i < num_threads; i++) {
-        threads.emplace_back([&service_, i, &success_count, this]() {
-            auto segment =
-                MakeSegment("segment_" + std::to_string(i),
-                            0x300000000 + i * 0x10000000, 16 * 1024 * 1024);
-            UUID client_id = generate_uuid();
-
-            for (size_t j = 0; j < iterations; j++) {
-                auto mount_result = service_->MountSegment(segment, client_id);
-                if (mount_result.has_value()) {
-                    auto unmount_result =
-                        service_->UnmountSegment(segment.id, client_id);
-                    EXPECT_TRUE(unmount_result.has_value());
-                    success_count++;
-                }
-            }
-        });
-    }
-
-    // Wait for all threads to complete
-    for (auto& thread : threads) {
-        thread.join();
-    }
-
-    // Verify that some mount/unmount operations succeeded
-    EXPECT_GT(success_count, 0);
-}
-
-TEST_F(MasterServiceTest, PutStartInvalidParams) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+TEST_F(MasterServiceTest, SoftPinZeroTtlSkipsSoftPinRegistration) {
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_soft_pin_ttl(50)
+                              .set_max_kv_soft_pin_ttl(100)
+                              .build();
+    std::unique_ptr<MasterService> service(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
     const UUID client_id = generate_uuid();
 
-    std::string key = "test_key";
     ReplicateConfig config;
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    config.soft_pin_ttl_ms = 0;
+    ASSERT_TRUE(
+        service
+            ->PutStart(client_id, "zero_ttl", TenantId::Default(), 1024, config)
+            .has_value());
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "zero_ttl", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "zero_ttl").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+}
 
-    // Test invalid replica config
-    config.replica_num = 0;
-    config.nof_replica_num = 0;
-    auto put_result1 =
-        service_->PutStart(client_id, key, TenantId::Default(), 1024, config);
-    EXPECT_FALSE(put_result1.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, put_result1.error());
+TEST_F(MasterServiceTest, SoftPinMasterConfigRejectsDefaultAboveMaximum) {
+    auto invalid_config = MasterServiceConfig::builder()
+                              .set_default_kv_soft_pin_ttl(101)
+                              .set_max_kv_soft_pin_ttl(100)
+                              .build();
+    EXPECT_THROW(MasterService service(invalid_config), std::invalid_argument);
+}
 
-    // Test zero slice_length
-    config.replica_num = 1;
-    auto put_result2 =
-        service_->PutStart(client_id, key, TenantId::Default(), 0, config);
-    EXPECT_FALSE(put_result2.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, put_result2.error());
+TEST_F(MasterServiceTest, SoftPinDeadlineCalculationSaturatesAtMaximum) {
+    using Clock = std::chrono::system_clock;
 
-    // Test prefer_alloc_in_same_node with nof replicas
-    config.nof_replica_num = 1;
-    config.prefer_alloc_in_same_node = true;
-    auto put_result3 =
-        service_->PutStart(client_id, key, TenantId::Default(), 1024, config);
-    EXPECT_FALSE(put_result3.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, put_result3.error());
+    const auto normal_now = Clock::time_point(std::chrono::seconds(10));
+    EXPECT_EQ(ComputeSoftPinDeadlineForTest(normal_now,
+                                            std::chrono::milliseconds(25)),
+              normal_now + std::chrono::milliseconds(25));
+    EXPECT_EQ(ComputeSoftPinDeadlineForTest(normal_now,
+                                            std::chrono::milliseconds::max()),
+              Clock::time_point::max());
+
+    const auto near_max =
+        Clock::time_point::max() - std::chrono::milliseconds(5);
+    EXPECT_EQ(
+        ComputeSoftPinDeadlineForTest(near_max, std::chrono::milliseconds(10)),
+        Clock::time_point::max());
 }
 
 #ifdef USE_NOF
@@ -746,234 +396,787 @@ TEST_F(MasterServiceTest, PutEndMemoryDoesNotCompleteNoFReplica) {
               ReplicaStatus::COMPLETE);
 }
 
-TEST_F(MasterServiceTest, PutStartOnePlusOneAllowsSingleAllocatedReplica) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto mem_context = PrepareSimpleSegment(*service_);
+TEST_F(MasterServiceTest, PartialRevokePreservesPendingSoftPin) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto mem_context = PrepareSimpleSegment(*service);
+    NoFSegment nof_segment =
+        MakeNoFSegment("soft_pin_nof", "soft_pin_nof_endpoint");
     const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service->MountNoFSegment(nof_segment, client_id).has_value());
 
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
     ReplicateConfig config;
     config.replica_num = 1;
     config.nof_replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, "test_key_one_plus_one", TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    ASSERT_EQ(put_start_result->size(), 1u);
-    EXPECT_TRUE(put_start_result->front().is_memory_replica());
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    ASSERT_TRUE(service
+                    ->PutStart(client_id, "partial_revoke_soft_pin",
+                               TenantId::Default(), 1024, config)
+                    .has_value());
+    ASSERT_TRUE(service
+                    ->PutRevoke(client_id, "partial_revoke_soft_pin",
+                                TenantId::Default(), ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "partial_revoke_soft_pin",
+                             TenantId::Default(), ReplicaType::NOF_SSD)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+    EXPECT_TRUE(
+        GetSoftPinDeadline(*service, "partial_revoke_soft_pin").has_value());
 }
-#endif
 
-TEST_F(MasterServiceTest, PutStartGroupIdsValidation) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+TEST_F(MasterServiceTest, LaterReplicaEndDoesNotRefreshSoftPin) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto mem_context = PrepareSimpleSegment(*service);
+    NoFSegment nof_segment =
+        MakeNoFSegment("soft_pin_later_end", "soft_pin_later_end_endpoint");
     const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service->MountNoFSegment(nof_segment, client_id).has_value());
 
     ReplicateConfig config;
     config.replica_num = 1;
-
-    config.group_ids = std::vector<std::string>{};
-    auto empty_group_ids = service_->PutStart(
-        client_id, "empty_group_ids", TenantId::Default(), 1024, config);
-    EXPECT_FALSE(empty_group_ids.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, empty_group_ids.error());
-
-    config.group_ids = std::vector<std::string>{"g0", "g1"};
-    auto too_many_group_ids = service_->PutStart(
-        client_id, "too_many_group_ids", TenantId::Default(), 1024, config);
-    EXPECT_FALSE(too_many_group_ids.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, too_many_group_ids.error());
-
-    config.group_ids = std::vector<std::string>{""};
-    auto ungrouped = service_->PutStart(client_id, "explicit_ungrouped",
-                                        TenantId::Default(), 1024, config);
-    ASSERT_TRUE(ungrouped.has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(client_id, "explicit_ungrouped",
+    config.nof_replica_num = 1;
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    ASSERT_TRUE(service
+                    ->PutStart(client_id, "later_end_soft_pin",
+                               TenantId::Default(), 1024, config)
+                    .has_value());
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "later_end_soft_pin",
                              TenantId::Default(), ReplicaType::MEMORY)
                     .has_value());
-    auto exists = service_->ExistKey("explicit_ungrouped", TenantId::Default());
-    ASSERT_TRUE(exists.has_value());
-    EXPECT_TRUE(exists.value());
+    const auto first_deadline =
+        GetSoftPinDeadline(*service, "later_end_soft_pin");
+    ASSERT_TRUE(first_deadline.has_value());
+
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "later_end_soft_pin",
+                             TenantId::Default(), ReplicaType::NOF_SSD)
+                    .has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "later_end_soft_pin"),
+              first_deadline);
 }
 
-TEST_F(MasterServiceTest, GroupedObjectRoutesKeyLevelLookupAndRemove) {
+TEST_F(MasterServiceTest, PutStartOnePlusOneAllowsSingleAllocatedReplica) {
     std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    [[maybe_unused]] const auto mem_context = PrepareSimpleSegment(*service_);
     const UUID client_id = generate_uuid();
 
-    const std::string key = "grouped_route_key";
     ReplicateConfig config;
     config.replica_num = 1;
-    config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
+    config.nof_replica_num = 1;
+    auto put_start_result = service_->PutStart(
+        client_id, "test_key_one_plus_one", TenantId::Default(), 1024, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    ASSERT_EQ(put_start_result->size(), 1u);
+    EXPECT_TRUE(put_start_result->front().is_memory_replica());
+}
+#endif
 
-    PutCompletedObject(*service_, client_id, key, config);
+TEST_F(MasterServiceTest, DfsPutEndAllAndUpsertTopologyAreAtomic) {
+    const auto dfs_root = (std::filesystem::temp_directory_path() /
+                           ("master_dfs_sync_" + std::to_string(::getpid())))
+                              .string();
+    std::filesystem::create_directories(dfs_root);
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar fs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar root_dir("MOONCAKE_DFS_ROOT_DIR", dfs_root.c_str());
+    ScopedEnvVar shard_count("MOONCAKE_DFS_SHARD_COUNT", "1");
+    ScopedEnvVar shard_capacity("MOONCAKE_DFS_SHARD_CAPACITY", "1048576");
+    ScopedEnvVar alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar eviction("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+    ScopedEnvVar deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
 
-    auto exists = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exists.has_value());
-    EXPECT_TRUE(exists.value());
-    EXPECT_TRUE(service_->GetReplicaList(key, TenantId::Default()).has_value());
+    {
+        MasterService service;
+        const auto context = PrepareSimpleSegment(service);
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
 
-    ASSERT_TRUE(
-        service_->Remove(key, TenantId::Default(), /*force=*/true).has_value());
-    auto exists_after_remove = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exists_after_remove.has_value());
-    EXPECT_FALSE(exists_after_remove.value());
-}
+        auto start = service.PutStart(context.client_id, "dfs_atomic",
+                                      TenantId::Default(), 4096, config);
+        ASSERT_TRUE(start.has_value());
+        ASSERT_EQ(start->size(), 2);
+        ASSERT_TRUE(service
+                        .PutEnd(context.client_id, "dfs_atomic",
+                                TenantId::Default(), ReplicaType::ALL)
+                        .has_value());
 
-TEST_F(MasterServiceTest, GroupRoutingIsTenantScopedForSameUserKey) {
-    const std::string key = "tenant_grouped_shared_user_key";
-    const TenantId tenant_a("tenant_group_route_a");
-    const TenantId tenant_b("tenant_group_route_b");
-    auto service_ = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+        auto query = service.GetReplicaList("dfs_atomic", TenantId::Default());
+        ASSERT_TRUE(query.has_value());
+        ASSERT_EQ(query->replicas.size(), 2);
+        for (const auto& replica : query->replicas) {
+            EXPECT_EQ(replica.status, ReplicaStatus::COMPLETE);
+        }
 
-    const std::string group_a = FindGroupIdOnDifferentShard(key);
-    std::string group_b;
-    for (int i = 0; i < 10000; ++i) {
-        group_b = key + "_tenant_b_group_" + std::to_string(i);
-        if (std::hash<std::string>{}(group_b) % 1024 !=
-            std::hash<std::string>{}(group_a) % 1024) {
-            break;
+        ReplicateConfig mismatched_config;
+        auto leased_upsert = service.UpsertStart(
+            context.client_id, "dfs_atomic", TenantId::Default(), 4096, config);
+        ASSERT_FALSE(leased_upsert.has_value());
+        EXPECT_EQ(leased_upsert.error(), ErrorCode::OBJECT_HAS_LEASE);
+
+        mismatched_config.replica_num = 1;
+        auto upsert =
+            service.UpsertStart(context.client_id, "dfs_atomic",
+                                TenantId::Default(), 4096, mismatched_config);
+        ASSERT_FALSE(upsert.has_value());
+        EXPECT_EQ(upsert.error(), ErrorCode::INVALID_PARAMS);
+
+        query = service.GetReplicaList("dfs_atomic", TenantId::Default());
+        ASSERT_TRUE(query.has_value());
+        ASSERT_EQ(query->replicas.size(), 2);
+        for (const auto& replica : query->replicas) {
+            EXPECT_EQ(replica.status, ReplicaStatus::COMPLETE);
         }
+
+        auto revoke_start = service.PutStart(context.client_id, "dfs_revoke",
+                                             TenantId::Default(), 4096, config);
+        ASSERT_TRUE(revoke_start.has_value());
+        ASSERT_TRUE(service
+                        .PutRevoke(context.client_id, "dfs_revoke",
+                                   TenantId::Default(), ReplicaType::ALL)
+                        .has_value());
+        auto revoked =
+            service.GetReplicaList("dfs_revoke", TenantId::Default());
+        ASSERT_FALSE(revoked.has_value());
+        EXPECT_EQ(revoked.error(), ErrorCode::OBJECT_NOT_FOUND);
+    }
+
+    {
+        MasterService service(MakeStrictTenantConfig({"default"}));
+        const auto context = PrepareSimpleSegment(service);
+        ReplicateConfig dfs_config;
+        dfs_config.replica_num = 1;
+        dfs_config.dfs_replica_num = 1;
+
+        auto failed = service.PutStart(context.client_id, "dfs_quota_failure",
+                                       TenantId::Default(),
+                                       kStrictTenantQuotaBytes, dfs_config);
+        ASSERT_FALSE(failed.has_value());
+        EXPECT_EQ(failed.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+
+        ReplicateConfig memory_config;
+        memory_config.replica_num = 1;
+        auto retry = service.PutStart(
+            context.client_id, "quota_after_dfs_failure", TenantId::Default(),
+            kStrictTenantQuotaBytes, memory_config);
+        ASSERT_TRUE(retry.has_value()) << toString(retry.error());
+        ASSERT_TRUE(service
+                        .PutRevoke(context.client_id, "quota_after_dfs_failure",
+                                   TenantId::Default(), ReplicaType::ALL)
+                        .has_value());
     }
+    std::error_code ec;
+    std::filesystem::remove_all(dfs_root, ec);
+}
+
+TEST_F(MasterServiceTest, DfsBucketMemoryAllocationFailurePreservesBuckets) {
+    const auto dfs_root =
+        (std::filesystem::temp_directory_path() /
+         ("master_dfs_bucket_memory_failure_" + std::to_string(::getpid())))
+            .string();
+    std::filesystem::create_directories(dfs_root);
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar fs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar root_dir("MOONCAKE_DFS_ROOT_DIR", dfs_root.c_str());
+    ScopedEnvVar allocator("MOONCAKE_DFS_ALLOCATOR", "bucket");
+    ScopedEnvVar bucket_capacity("MOONCAKE_DFS_BUCKET_CAPACITY", "8192");
+    ScopedEnvVar max_bucket_count("MOONCAKE_DFS_MAX_BUCKET_COUNT", "4");
+    ScopedEnvVar alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar eviction("MOONCAKE_DFS_EVICTION_ENABLED", "1");
+    ScopedEnvVar high_watermark("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "1.0");
+    ScopedEnvVar low_watermark("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.9");
+    ScopedEnvVar deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
 
-    ReplicateConfig config_a;
-    config_a.replica_num = 1;
-    config_a.group_ids = std::vector<std::string>{group_a};
-    ReplicateConfig config_b;
-    config_b.replica_num = 1;
-    config_b.group_ids = std::vector<std::string>{group_b};
+    {
+        MasterService service;
+        const auto context = PrepareSimpleSegment(service, "small_memory",
+                                                  kDefaultSegmentBase, 8192);
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+
+        for (const char* key : {"memory_full_a", "memory_full_b"}) {
+            auto start = service.PutStart(context.client_id, key,
+                                          TenantId::Default(), 4096, config);
+            ASSERT_TRUE(start.has_value()) << key << ": " << start.error();
+            ASSERT_TRUE(service
+                            .PutEnd(context.client_id, key, TenantId::Default(),
+                                    ReplicaType::ALL)
+                            .has_value());
+        }
 
-    ASSERT_TRUE(service_->PutStart(client_id, key, tenant_a, 1024, config_a)
-                    .has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY)
-                    .has_value());
-    ASSERT_TRUE(service_->PutStart(client_id, key, tenant_b, 2048, config_b)
-                    .has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY)
-                    .has_value());
+        ASSERT_TRUE(
+            service.UnmountSegment(context.segment_id, context.client_id)
+                .has_value());
 
-    EXPECT_TRUE(service_->ExistKey(key, tenant_a).value_or(false));
-    EXPECT_TRUE(service_->ExistKey(key, tenant_b).value_or(false));
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
+        auto failed = service.PutStart(context.client_id, "memory_full_c",
+                                       TenantId::Default(), 4096, config);
+        ASSERT_FALSE(failed.has_value());
+        EXPECT_EQ(failed.error(), ErrorCode::NO_AVAILABLE_HANDLE);
 
-    ASSERT_TRUE(service_->Remove(key, tenant_a, /*force=*/true).has_value());
-    EXPECT_FALSE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
-}
+        for (const char* key : {"memory_full_a", "memory_full_b"}) {
+            auto query = service.GetReplicaList(key, TenantId::Default());
+            ASSERT_TRUE(query.has_value()) << key;
+            ASSERT_EQ(query->replicas.size(), 1u);
+            EXPECT_TRUE(query->replicas.front().is_dfs_replica());
+        }
+    }
 
-TEST_F(MasterServiceTest, StandbySnapshotRestorePreservesTenantScopedKeys) {
-    const TenantId tenant_a("tenant_restore_a");
-    const TenantId tenant_b("tenant_restore_b");
-    MasterService service(
-        MakeStrictTenantConfig({tenant_a.value(), tenant_b.value()}));
-    const std::string key = "shared_restore_key";
+    std::error_code ec;
+    std::filesystem::remove_all(dfs_root, ec);
+}
+
+TEST_F(MasterServiceTest, DfsBucketUpsertRestoresEvictedReplica) {
+    const auto dfs_root =
+        (std::filesystem::temp_directory_path() /
+         ("master_dfs_bucket_upsert_restore_" + std::to_string(::getpid())))
+            .string();
+    std::filesystem::create_directories(dfs_root);
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar fs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar root_dir("MOONCAKE_DFS_ROOT_DIR", dfs_root.c_str());
+    ScopedEnvVar allocator("MOONCAKE_DFS_ALLOCATOR", "bucket");
+    ScopedEnvVar bucket_capacity("MOONCAKE_DFS_BUCKET_CAPACITY", "8192");
+    ScopedEnvVar max_bucket_count("MOONCAKE_DFS_MAX_BUCKET_COUNT", "2");
+    ScopedEnvVar alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar eviction("MOONCAKE_DFS_EVICTION_ENABLED", "1");
+    ScopedEnvVar high_watermark("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "0.7");
+    ScopedEnvVar low_watermark("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.5");
+    ScopedEnvVar eviction_interval("MOONCAKE_DFS_EVICTION_CHECK_INTERVAL",
+                                   "60");
+    ScopedEnvVar deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
 
-    Replica replica(generate_uuid(), 128, "local://standby",
-                    ReplicaStatus::COMPLETE);
-    StandbyObjectMetadata metadata;
-    metadata.client_id = generate_uuid();
-    metadata.size = 128;
-    metadata.replicas.push_back(replica.get_descriptor());
+    {
+        MasterService service;
+        const auto context = PrepareSimpleSegment(service);
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+
+        std::optional<uint64_t> old_memory_address;
+        std::optional<int> old_bucket_id;
+        for (const std::string key :
+             {"upsert_restore", "bucket_0_peer", "bucket_1_peer"}) {
+            auto start = service.PutStart(context.client_id, key,
+                                          TenantId::Default(), 4096, config);
+            ASSERT_TRUE(start.has_value()) << key << ": " << start.error();
+            if (key == "upsert_restore") {
+                for (const auto& descriptor : *start) {
+                    if (descriptor.is_memory_replica()) {
+                        old_memory_address =
+                            descriptor.get_memory_descriptor()
+                                .buffer_descriptor.buffer_address_;
+                    } else if (descriptor.is_dfs_replica()) {
+                        old_bucket_id =
+                            descriptor.get_dfs_descriptor().shard_idx;
+                    }
+                }
+            }
+            ASSERT_TRUE(service
+                            .PutEnd(context.client_id, key, TenantId::Default(),
+                                    ReplicaType::ALL)
+                            .has_value());
+        }
+        ASSERT_TRUE(old_memory_address.has_value());
+        ASSERT_TRUE(old_bucket_id.has_value());
+
+        MasterServiceTestPeer(service).RunDfsEvictionForTesting();
+        auto after_eviction =
+            service.GetReplicaList("upsert_restore", TenantId::Default());
+        ASSERT_TRUE(after_eviction.has_value());
+        ASSERT_EQ(after_eviction->replicas.size(), 1u);
+        EXPECT_TRUE(after_eviction->replicas.front().is_memory_replica());
+
+        auto mismatched_config = config;
+        mismatched_config.replica_num = 2;
+        auto mismatched =
+            service.UpsertStart(context.client_id, "upsert_restore",
+                                TenantId::Default(), 4096, mismatched_config);
+        ASSERT_FALSE(mismatched.has_value());
+        EXPECT_EQ(mismatched.error(), ErrorCode::INVALID_PARAMS);
+
+        auto restored = service.UpsertStart(context.client_id, "upsert_restore",
+                                            TenantId::Default(), 4096, config);
+        ASSERT_TRUE(restored.has_value()) << restored.error();
+        ASSERT_EQ(restored->size(), 2u);
+        bool restored_memory = false;
+        bool restored_dfs = false;
+        for (const auto& descriptor : *restored) {
+            if (descriptor.is_memory_replica()) {
+                restored_memory = true;
+                EXPECT_NE(descriptor.get_memory_descriptor()
+                              .buffer_descriptor.buffer_address_,
+                          *old_memory_address);
+            } else if (descriptor.is_dfs_replica()) {
+                restored_dfs = true;
+                EXPECT_NE(descriptor.get_dfs_descriptor().shard_idx,
+                          *old_bucket_id);
+            }
+        }
+        EXPECT_TRUE(restored_memory);
+        EXPECT_TRUE(restored_dfs);
+        ASSERT_TRUE(service
+                        .UpsertEnd(context.client_id, "upsert_restore",
+                                   TenantId::Default(), ReplicaType::ALL)
+                        .has_value());
 
-    service.RestoreFromStandbySnapshot({{tenant_a.value(), key, metadata}},
-                                       /*initial_oplog_sequence_id=*/0, {});
+        auto complete =
+            service.GetReplicaList("upsert_restore", TenantId::Default());
+        ASSERT_TRUE(complete.has_value());
+        EXPECT_EQ(complete->replicas.size(), 2u);
+        EXPECT_EQ(
+            std::count_if(complete->replicas.begin(), complete->replicas.end(),
+                          [](const Replica::Descriptor& descriptor) {
+                              return descriptor.is_dfs_replica();
+                          }),
+            1);
+    }
 
-    EXPECT_TRUE(service.ExistKey(key, tenant_a).value_or(false));
-    EXPECT_FALSE(service.ExistKey(key, tenant_b).value_or(true));
-    EXPECT_FALSE(service.ExistKey(key, TenantId::Default()).value_or(true));
+    std::error_code ec;
+    std::filesystem::remove_all(dfs_root, ec);
 }
 
-TEST_F(MasterServiceTest, BatchGetReplicaListPreservesOrderWithGroupedKeys) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest,
+       DfsBucketConcurrentPutAndUpsertShareSingleRecoveryBucket) {
+    const auto dfs_root =
+        (std::filesystem::temp_directory_path() /
+         ("master_dfs_bucket_single_flight_" + std::to_string(::getpid())))
+            .string();
+    std::filesystem::create_directories(dfs_root);
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar fs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar root_dir("MOONCAKE_DFS_ROOT_DIR", dfs_root.c_str());
+    ScopedEnvVar allocator("MOONCAKE_DFS_ALLOCATOR", "bucket");
+    ScopedEnvVar bucket_capacity("MOONCAKE_DFS_BUCKET_CAPACITY", "32768");
+    ScopedEnvVar max_bucket_count("MOONCAKE_DFS_MAX_BUCKET_COUNT", "4");
+    ScopedEnvVar alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar eviction("MOONCAKE_DFS_EVICTION_ENABLED", "1");
+    ScopedEnvVar high_watermark("MOONCAKE_DFS_EVICTION_HIGH_WATERMARK", "1.0");
+    ScopedEnvVar low_watermark("MOONCAKE_DFS_EVICTION_LOW_WATERMARK", "0.9");
+    ScopedEnvVar eviction_interval("MOONCAKE_DFS_EVICTION_CHECK_INTERVAL",
+                                   "60");
+    ScopedEnvVar deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
 
-    const std::string grouped_key_a = "batch_get_grouped_a";
-    const std::string missing_key = "batch_get_missing";
-    const std::string ungrouped_key = "batch_get_ungrouped";
-    const std::string grouped_key_b = "batch_get_grouped_b";
-    const std::string pending_key = "batch_get_pending";
+    {
+        MasterService service;
+        const auto context = PrepareSimpleSegment(service);
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+
+        constexpr size_t kObjectSize = 4096;
+        constexpr size_t kConcurrentWrites = 8;
+        constexpr size_t kOldKeyCount = 32;
+        const size_t old_shard =
+            MetadataShardIndex(service, "single_flight_old_seed");
+        std::vector<std::string> old_keys;
+        std::vector<std::string> new_keys;
+        for (size_t i = 0; old_keys.size() < kOldKeyCount ||
+                           new_keys.size() < kConcurrentWrites;
+             ++i) {
+            const std::string key = "single_flight_key_" + std::to_string(i);
+            if (MetadataShardIndex(service, key) == old_shard) {
+                if (old_keys.size() < kOldKeyCount) old_keys.push_back(key);
+            } else if (new_keys.size() < kConcurrentWrites) {
+                new_keys.push_back(key);
+            }
+        }
 
-    ReplicateConfig grouped_config_a;
-    grouped_config_a.replica_num = 1;
-    grouped_config_a.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(grouped_key_a)};
-    PutCompletedObject(*service_, client_id, grouped_key_a, grouped_config_a);
+        for (const auto& key : old_keys) {
+            auto start =
+                service.PutStart(context.client_id, key, TenantId::Default(),
+                                 kObjectSize, config);
+            ASSERT_TRUE(start.has_value()) << key << ": " << start.error();
+            ASSERT_TRUE(service
+                            .PutEnd(context.client_id, key, TenantId::Default(),
+                                    ReplicaType::ALL)
+                            .has_value());
+        }
 
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    PutCompletedObject(*service_, client_id, ungrouped_key, ungrouped_config);
+        auto old_shard_lock = LockMetadataShardForTest(service, old_shard);
+        std::barrier start_barrier(kConcurrentWrites + 1);
+        std::vector<int> errors(kConcurrentWrites,
+                                static_cast<int>(ErrorCode::INTERNAL_ERROR));
+        std::vector<int> bucket_ids(kConcurrentWrites, -1);
+        std::vector<std::thread> writers;
+        writers.reserve(kConcurrentWrites);
+        for (size_t i = 0; i < kConcurrentWrites; ++i) {
+            writers.emplace_back([&, i] {
+                start_barrier.arrive_and_wait();
+                auto result =
+                    i % 2 == 0
+                        ? service.PutStart(context.client_id, new_keys[i],
+                                           TenantId::Default(), kObjectSize,
+                                           config)
+                        : service.UpsertStart(context.client_id, new_keys[i],
+                                              TenantId::Default(), kObjectSize,
+                                              config);
+                if (!result) {
+                    errors[i] = static_cast<int>(result.error());
+                    return;
+                }
+                errors[i] = static_cast<int>(ErrorCode::OK);
+                for (const auto& descriptor : *result) {
+                    if (descriptor.is_dfs_replica()) {
+                        bucket_ids[i] =
+                            descriptor.get_dfs_descriptor().shard_idx;
+                    }
+                }
+            });
+        }
 
-    ReplicateConfig grouped_config_b;
-    grouped_config_b.replica_num = 1;
-    grouped_config_b.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(grouped_key_b)};
-    PutCompletedObject(*service_, client_id, grouped_key_b, grouped_config_b);
+        start_barrier.arrive_and_wait();
+        // Keep eviction validation blocked long enough for all writers to
+        // encounter the full allocator. Without single-flight recovery they
+        // freeze different LRU buckets while waiting on this shard.
+        std::this_thread::sleep_for(std::chrono::milliseconds(250));
+        old_shard_lock.reset();
+        for (auto& writer : writers) writer.join();
+
+        for (size_t i = 0; i < kConcurrentWrites; ++i) {
+            EXPECT_EQ(errors[i], static_cast<int>(ErrorCode::OK))
+                << new_keys[i];
+            EXPECT_GE(bucket_ids[i], 0) << new_keys[i];
+            EXPECT_EQ(bucket_ids[i], bucket_ids.front()) << new_keys[i];
+        }
 
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, pending_key, TenantId::Default(),
-                               1024, ungrouped_config)
+        size_t old_dfs_replicas = 0;
+        for (const auto& key : old_keys) {
+            auto query = service.GetReplicaList(key, TenantId::Default());
+            ASSERT_TRUE(query.has_value()) << key;
+            old_dfs_replicas +=
+                std::count_if(query->replicas.begin(), query->replicas.end(),
+                              [](const Replica::Descriptor& descriptor) {
+                                  return descriptor.is_dfs_replica();
+                              });
+        }
+        EXPECT_EQ(old_dfs_replicas, kOldKeyCount - kConcurrentWrites);
+    }
+
+    std::error_code ec;
+    std::filesystem::remove_all(dfs_root, ec);
+}
+
+TEST_F(MasterServiceTest, LeasedUpsertAllocationFailurePreservesObject) {
+    MasterServiceConfig service_config;
+    service_config.memory_allocator = BufferAllocatorType::OFFSET;
+    service_config.default_kv_lease_ttl = 10 * 1000;
+    MasterService service(service_config);
+
+    constexpr size_t kSegmentSize = 1024 * 1024;
+    const auto context = PrepareSimpleSegment(
+        service, "leased_upsert_segment", kDefaultSegmentBase, kSegmentSize);
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    const std::string key = "leased_upsert_allocation_failure";
+    auto initial = service.PutStart(context.client_id, key, TenantId::Default(),
+                                    kSegmentSize, config);
+    ASSERT_TRUE(initial.has_value()) << toString(initial.error());
+    ASSERT_TRUE(service
+                    .PutEnd(context.client_id, key, TenantId::Default(),
+                            ReplicaType::MEMORY)
                     .has_value());
 
-    const std::vector<std::string> keys = {
-        grouped_key_a, missing_key, ungrouped_key, grouped_key_b, pending_key};
-    auto results = service_->BatchGetReplicaList(keys, TenantId::Default());
+    // Retain a read lease so UpsertStart must allocate a replacement instead
+    // of reusing the old buffer.
+    auto snapshot = service.GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(snapshot.has_value());
 
-    ASSERT_EQ(results.size(), keys.size());
-    ASSERT_TRUE(results[0].has_value());
-    EXPECT_FALSE(results[0]->replicas.empty());
-    ASSERT_FALSE(results[1].has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, results[1].error());
-    ASSERT_TRUE(results[2].has_value());
-    EXPECT_FALSE(results[2]->replicas.empty());
-    ASSERT_TRUE(results[3].has_value());
-    EXPECT_FALSE(results[3]->replicas.empty());
-    ASSERT_FALSE(results[4].has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, results[4].error());
+    auto failed = service.UpsertStart(
+        context.client_id, key, TenantId::Default(), kSegmentSize, config);
+    ASSERT_FALSE(failed.has_value());
+    EXPECT_EQ(failed.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+
+    auto still_readable = service.GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(still_readable.has_value());
+    ASSERT_EQ(still_readable->replicas.size(), snapshot->replicas.size());
+    EXPECT_EQ(still_readable->replicas[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.buffer_address_,
+              snapshot->replicas[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.buffer_address_);
 }
 
-TEST_F(MasterServiceTest, BatchGetReplicaListKeepsTenantIsolation) {
-    const std::string key = "batch_get_tenant_shared_key";
-    const TenantId tenant_a("batch_get_tenant_a");
-    const TenantId tenant_b("batch_get_tenant_b");
-    auto service_ = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+// DFS replicas live in their own variant branch, so is_disk_replica() does not
+// match them. KV subscribers still expect one logical tier per storage class,
+// which is what these assertions pin down.
+TEST_F(MasterServiceTest, DfsReplicaNormalizesToDiskMediumForKvEvents) {
+    const auto dfs_root =
+        (std::filesystem::temp_directory_path() /
+         ("master_dfs_kv_media_" + std::to_string(::getpid())))
+            .string();
+    std::filesystem::create_directories(dfs_root);
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar fs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar root_dir("MOONCAKE_DFS_ROOT_DIR", dfs_root.c_str());
+    ScopedEnvVar shard_count("MOONCAKE_DFS_SHARD_COUNT", "1");
+    ScopedEnvVar shard_capacity("MOONCAKE_DFS_SHARD_CAPACITY", "1048576");
+    ScopedEnvVar alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar eviction("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+    ScopedEnvVar deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+    {
+        MasterService service;
+        const auto context = PrepareSimpleSegment(service);
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.dfs_replica_num = 1;
+
+        auto start = service.PutStart(context.client_id, "dfs_kv_media",
+                                      TenantId::Default(), 4096, config);
+        ASSERT_TRUE(start.has_value());
+        ASSERT_EQ(start->size(), 2);
+        ASSERT_TRUE(service
+                        .PutEnd(context.client_id, "dfs_kv_media",
+                                TenantId::Default(), ReplicaType::ALL)
+                        .has_value());
+
+        // Memory + DFS collapse to exactly the two logical tiers, sorted the
+        // same way the publisher sorts them.
+        auto media = KvMediaForKey(service, "dfs_kv_media");
+        ASSERT_TRUE(media.has_value());
+        EXPECT_EQ(std::vector<std::string>({"cpu", "disk"}), *media);
 
-    ReplicateConfig config_a;
-    config_a.replica_num = 1;
-    config_a.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-    ASSERT_TRUE(service_->PutStart(client_id, key, tenant_a, 1024, config_a)
+        auto removal_media = KvRemovalMediaForKey(service, "dfs_kv_media");
+        ASSERT_TRUE(removal_media.has_value());
+        EXPECT_EQ(std::vector<std::string>({"cpu", "disk"}), *removal_media);
+    }
+
+    std::error_code ec;
+    std::filesystem::remove_all(dfs_root, ec);
+}
+
+// A removal path can run while a replica is still PROCESSING. That medium was
+// never announced as available, but the removal snapshot must still name it:
+// otherwise a tier that a subscriber may have seen is never retracted. The
+// contrast with KvMediaForKey, which counts only completed replicas, is the
+// whole point of having two helpers.
+TEST_F(MasterServiceTest, ProcessingReplicaMediumAppearsInRemovalSnapshot) {
+    MasterService service;
+    const auto context = PrepareSimpleSegment(service);
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    // PutStart without PutEnd leaves the replica PROCESSING.
+    auto start = service.PutStart(context.client_id, "processing_kv_media",
+                                  TenantId::Default(), 4096, config);
+    ASSERT_TRUE(start.has_value());
+
+    auto media = KvMediaForKey(service, "processing_kv_media");
+    ASSERT_TRUE(media.has_value());
+    EXPECT_TRUE(media->empty()) << "a PROCESSING replica is not yet available "
+                                   "and must not be announced";
+
+    auto removal_media = KvRemovalMediaForKey(service, "processing_kv_media");
+    ASSERT_TRUE(removal_media.has_value());
+    EXPECT_EQ(std::vector<std::string>({"cpu"}), *removal_media);
+}
+
+// A RemoveAll whose oplog slot reservation fails must leave the object in
+// place. That is the state in which announcing `cleared` would be a lie, so the
+// skip has to be recorded rather than treated as a successful wipe.
+TEST_F(MasterServiceTest, RemoveAllKeepsObjectWhenOpLogReservationFails) {
+    // enable_oplog_ needs HA + oplog + the etcd backend, but the ordered oplog
+    // writer is only installed by a separate init that needs a live etcd. So
+    // this config reaches ReserveBatchOpLogSlot with a null writer, which is
+    // exactly the reservation-failure branch.
+    auto config = MasterServiceConfig::builder()
+                      .set_enable_ha(true)
+                      .set_enable_oplog(true)
+                      .set_ha_backend_type("etcd")
+                      .build();
+    auto service = std::make_unique<MasterService>(config);
+    const auto context = PrepareSimpleSegment(*service);
+
+    ReplicateConfig replicate_config;
+    replicate_config.replica_num = 1;
+    ASSERT_TRUE(service
+                    ->PutStart(context.client_id, "reservation_fail_key",
+                               TenantId::Default(), 4096, replicate_config)
                     .has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY)
+    ASSERT_TRUE(service
+                    ->PutEnd(context.client_id, "reservation_fail_key",
+                             TenantId::Default(), ReplicaType::ALL)
                     .has_value());
 
-    ReplicateConfig config_b;
-    config_b.replica_num = 1;
-    ASSERT_TRUE(service_->PutStart(client_id, key, tenant_b, 2048, config_b)
+    // force=true clears the lease gate, so the reservation is the only thing
+    // left that can stop the removal.
+    EXPECT_EQ(0, service->RemoveAll(TenantId::Default(), true));
+
+    auto exists =
+        service->ExistKey("reservation_fail_key", TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    EXPECT_TRUE(exists.value())
+        << "the object survived, so the tenant was never emptied";
+}
+
+// RemoveAll holds one shard lock at a time, so a commit can land in a shard the
+// scan already passed. The scan's own bookkeeping cannot see it, and publishing
+// `cleared` would order it after that commit's `stored` — telling subscribers
+// to drop an object that is live. Pause the scan right after the shard the new
+// key belongs to, commit there, and the clear must be withheld.
+TEST_F(MasterServiceTest, ConcurrentCommitDuringScanSuppressesClear) {
+    MasterService service;
+    MasterServiceTestPeer(service).SetKvTenantEpochTrackingForTesting(true);
+    const auto context = PrepareSimpleSegment(service);
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    ASSERT_TRUE(service
+                    .PutStart(context.client_id, "victim_key",
+                              TenantId::Default(), 1024, config)
                     .has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY)
+    ASSERT_TRUE(service
+                    .PutEnd(context.client_id, "victim_key",
+                            TenantId::Default(), ReplicaType::ALL)
+                    .has_value());
+
+    const size_t racer_shard = ShardIndexForKey(service, "racer_key");
+    bool committed = false;
+    MasterServiceTestPeer(service).SetRemoveAllShardHookForTesting(
+        [&](size_t shard) {
+            // Commit exactly once, immediately after the scan releases the
+            // shard the new key hashes to, so the scan can never observe it.
+            if (shard != racer_shard || committed) {
+                return;
+            }
+            committed = true;
+            ASSERT_TRUE(service
+                            .PutStart(context.client_id, "racer_key",
+                                      TenantId::Default(), 1024, config)
+                            .has_value());
+            ASSERT_TRUE(service
+                            .PutEnd(context.client_id, "racer_key",
+                                    TenantId::Default(), ReplicaType::ALL)
+                            .has_value());
+        });
+
+    service.RemoveAll(true);
+    MasterServiceTestPeer(service).SetRemoveAllShardHookForTesting(nullptr);
+
+    ASSERT_TRUE(committed) << "the hook never fired, so nothing was raced";
+    auto exists = service.ExistKey("racer_key", TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    EXPECT_TRUE(exists.value()) << "the raced commit must still be live";
+
+    EXPECT_EQ(0u,
+              MasterServiceTestPeer(service).GetKvClearedPublishedForTesting())
+        << "a clear here would retract racer_key, which was just announced";
+    EXPECT_EQ(
+        1u, MasterServiceTestPeer(service).GetKvClearedSuppressedForTesting());
+}
+
+// The mirror image: with no concurrent commit the epoch is unchanged, so the
+// clear must still go out. Without this the fix could pass by never publishing.
+TEST_F(MasterServiceTest, UncontendedScanStillPublishesClear) {
+    MasterService service;
+    MasterServiceTestPeer(service).SetKvTenantEpochTrackingForTesting(true);
+    const auto context = PrepareSimpleSegment(service);
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    ASSERT_TRUE(service
+                    .PutStart(context.client_id, "lonely_key",
+                              TenantId::Default(), 1024, config)
+                    .has_value());
+    ASSERT_TRUE(service
+                    .PutEnd(context.client_id, "lonely_key",
+                            TenantId::Default(), ReplicaType::ALL)
+                    .has_value());
+
+    service.RemoveAll(true);
+
+    EXPECT_EQ(1u,
+              MasterServiceTestPeer(service).GetKvClearedPublishedForTesting());
+    EXPECT_EQ(
+        0u, MasterServiceTestPeer(service).GetKvClearedSuppressedForTesting());
+}
+
+// The tenant-scoped overload reads the epoch before its scan instead of at
+// first sight of an object, so it needs its own coverage of the same ordering
+// rule.
+TEST_F(MasterServiceTest, TenantScopedRemoveAllSuppressesClearOnRace) {
+    MasterService service;
+    MasterServiceTestPeer(service).SetKvTenantEpochTrackingForTesting(true);
+    const auto context = PrepareSimpleSegment(service);
+    ReplicateConfig config;
+    config.replica_num = 1;
+
+    ASSERT_TRUE(service
+                    .PutStart(context.client_id, "scoped_victim",
+                              TenantId::Default(), 1024, config)
+                    .has_value());
+    ASSERT_TRUE(service
+                    .PutEnd(context.client_id, "scoped_victim",
+                            TenantId::Default(), ReplicaType::ALL)
                     .has_value());
 
-    auto tenant_a_results = service_->BatchGetReplicaList({key}, tenant_a);
-    auto tenant_b_results = service_->BatchGetReplicaList({key}, tenant_b);
-    auto default_results =
-        service_->BatchGetReplicaList({key}, TenantId::Default());
-
-    ASSERT_EQ(tenant_a_results.size(), 1u);
-    ASSERT_EQ(tenant_b_results.size(), 1u);
-    ASSERT_EQ(default_results.size(), 1u);
-    EXPECT_TRUE(tenant_a_results[0].has_value());
-    EXPECT_TRUE(tenant_b_results[0].has_value());
-    ASSERT_FALSE(default_results[0].has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, default_results[0].error());
+    const size_t racer_shard = ShardIndexForKey(service, "scoped_racer");
+    bool committed = false;
+    MasterServiceTestPeer(service).SetRemoveAllShardHookForTesting(
+        [&](size_t shard) {
+            if (shard != racer_shard || committed) {
+                return;
+            }
+            committed = true;
+            ASSERT_TRUE(service
+                            .PutStart(context.client_id, "scoped_racer",
+                                      TenantId::Default(), 1024, config)
+                            .has_value());
+            ASSERT_TRUE(service
+                            .PutEnd(context.client_id, "scoped_racer",
+                                    TenantId::Default(), ReplicaType::ALL)
+                            .has_value());
+        });
+
+    service.RemoveAll(TenantId::Default(), true);
+    MasterServiceTestPeer(service).SetRemoveAllShardHookForTesting(nullptr);
+
+    ASSERT_TRUE(committed) << "the hook never fired, so nothing was raced";
+    EXPECT_EQ(0u,
+              MasterServiceTestPeer(service).GetKvClearedPublishedForTesting());
+    EXPECT_EQ(
+        1u, MasterServiceTestPeer(service).GetKvClearedSuppressedForTesting());
+}
+
+TEST_F(MasterServiceTest, StandbySnapshotRestorePreservesTenantScopedKeys) {
+    const TenantId tenant_a("tenant_restore_a");
+    const TenantId tenant_b("tenant_restore_b");
+    MasterService service(
+        MakeStrictTenantConfig({tenant_a.value(), tenant_b.value()}));
+    const std::string key = "shared_restore_key";
+
+    Replica replica(generate_uuid(), 128, "local://standby",
+                    ReplicaStatus::COMPLETE);
+    StandbyObjectMetadata metadata;
+    metadata.client_id = generate_uuid();
+    metadata.size = 128;
+    metadata.replicas.push_back(replica.get_descriptor());
+
+    ASSERT_TRUE(
+        service
+            .RestoreFromStandbySnapshot({{tenant_a.value(), key, metadata}},
+                                        /*initial_oplog_sequence_id=*/0, {})
+            .has_value());
+
+    EXPECT_TRUE(service.ExistKey(key, tenant_a).value_or(false));
+    EXPECT_FALSE(service.ExistKey(key, tenant_b).value_or(true));
+    EXPECT_FALSE(service.ExistKey(key, TenantId::Default()).value_or(true));
 }
 
 TEST_F(MasterServiceTest, GetAllKeysListsOnlyRequestedTenant) {
@@ -1042,6642 +1245,2089 @@ TEST_F(MasterServiceTest, GetAllKeysListsOnlyRequestedTenant) {
         tenant_keys->end());
 }
 
-TEST_F(MasterServiceTest,
-       ConcurrentGroupedAndUngroupedFirstCreateDoesNotDuplicateMetadata) {
-    std::unique_ptr<MasterService> service_(new MasterService());
+TEST_F(MasterServiceTest, TenantScopedPutsAndRemovesUpdateGlobalKeyCount) {
+    const std::string key = "shared_user_key";
+    const TenantId tenant_a("tenant_key_count_a");
+    const TenantId tenant_b("tenant_key_count_b");
+    auto service_ = std::make_unique<MasterService>(
+        MakeStrictTenantConfig({tenant_a.value(), tenant_b.value()}));
     [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
     const UUID client_id = generate_uuid();
 
-    const std::string key = "concurrent_grouped_ungrouped_first_create";
-    const TenantId tenant_id("tenant_concurrent_first_create");
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-
-    static constexpr size_t kThreadCount = 16;
-    std::atomic<size_t> ready{0};
-    std::atomic<bool> start{false};
-    std::vector<int> put_start_success(kThreadCount, 0);
-    std::vector<int> put_end_success(kThreadCount, 0);
-    std::vector<std::thread> threads;
-    threads.reserve(kThreadCount);
-
-    for (size_t i = 0; i < kThreadCount; ++i) {
-        threads.emplace_back([&, i]() {
-            ready.fetch_add(1, std::memory_order_acq_rel);
-            while (!start.load(std::memory_order_acquire)) {
-                std::this_thread::yield();
-            }
-            const auto& config =
-                (i % 2 == 0) ? grouped_config : ungrouped_config;
-            auto put_start =
-                service_->PutStart(client_id, key, tenant_id, 1024, config);
-            put_start_success[i] = put_start.has_value() ? 1 : 0;
-            if (put_start.has_value()) {
-                put_end_success[i] = service_->PutEnd(client_id, key, tenant_id,
-                                                      ReplicaType::MEMORY)
-                                             .has_value()
-                                         ? 1
-                                         : 0;
-            } else {
-                EXPECT_EQ(ErrorCode::OBJECT_ALREADY_EXISTS, put_start.error());
-            }
-        });
-    }
+    ReplicateConfig config;
+    config.replica_num = 1;
 
-    while (ready.load(std::memory_order_acquire) < kThreadCount) {
-        std::this_thread::yield();
-    }
-    start.store(true, std::memory_order_release);
-    for (auto& thread : threads) {
-        thread.join();
-    }
+    EXPECT_EQ(service_->GetKeyCount(), 0u);
+    ASSERT_TRUE(
+        service_->PutStart(client_id, key, tenant_a, 1024, config).has_value());
+    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY)
+                    .has_value());
+    ASSERT_TRUE(
+        service_->PutStart(client_id, key, tenant_b, 2048, config).has_value());
+    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(service_->GetKeyCount(), 2u);
 
-    EXPECT_EQ(std::count(put_start_success.begin(), put_start_success.end(), 1),
-              1);
-    EXPECT_EQ(std::count(put_end_success.begin(), put_end_success.end(), 1), 1);
+    ASSERT_TRUE(service_->Remove(key, tenant_a, /*force=*/true).has_value());
+    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
     EXPECT_EQ(service_->GetKeyCount(), 1u);
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_id).has_value());
-}
-
-TEST_F(MasterServiceTest,
-       ConcurrentDifferentGroupedFirstCreateDoesNotDuplicateMetadata) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
 
-    const std::string key = "concurrent_different_grouped_first_create";
-    const TenantId tenant_id("tenant_concurrent_grouped_first_create");
-    const std::string group_a = FindGroupIdOnDifferentShard(key);
-    std::string group_b;
-    for (int i = 0; i < 10000; ++i) {
-        group_b = key + "_other_group_" + std::to_string(i);
-        if (std::hash<std::string>{}(group_b) % 1024 !=
-            std::hash<std::string>{}(group_a) % 1024) {
-            break;
-        }
-    }
-    ReplicateConfig config_a;
-    config_a.replica_num = 1;
-    config_a.group_ids = std::vector<std::string>{group_a};
-    ReplicateConfig config_b;
-    config_b.replica_num = 1;
-    config_b.group_ids = std::vector<std::string>{group_b};
-
-    static constexpr size_t kThreadCount = 16;
-    std::atomic<size_t> ready{0};
-    std::atomic<bool> start{false};
-    std::vector<int> put_start_success(kThreadCount, 0);
-    std::vector<int> put_end_success(kThreadCount, 0);
-    std::vector<std::thread> threads;
-    threads.reserve(kThreadCount);
-
-    for (size_t i = 0; i < kThreadCount; ++i) {
-        threads.emplace_back([&, i]() {
-            ready.fetch_add(1, std::memory_order_acq_rel);
-            while (!start.load(std::memory_order_acquire)) {
-                std::this_thread::yield();
-            }
-            const auto& config = (i % 2 == 0) ? config_a : config_b;
-            auto put_start =
-                service_->PutStart(client_id, key, tenant_id, 1024, config);
-            put_start_success[i] = put_start.has_value() ? 1 : 0;
-            if (put_start.has_value()) {
-                put_end_success[i] = service_->PutEnd(client_id, key, tenant_id,
-                                                      ReplicaType::MEMORY)
-                                             .has_value()
-                                         ? 1
-                                         : 0;
-            } else {
-                EXPECT_EQ(ErrorCode::OBJECT_ALREADY_EXISTS, put_start.error());
-            }
-        });
-    }
+    ASSERT_TRUE(service_->Remove(key, tenant_b, /*force=*/true).has_value());
+    EXPECT_EQ(service_->GetKeyCount(), 0u);
+}
 
-    while (ready.load(std::memory_order_acquire) < kThreadCount) {
-        std::this_thread::yield();
-    }
-    start.store(true, std::memory_order_release);
-    for (auto& thread : threads) {
-        thread.join();
-    }
+TEST_F(MasterServiceTest, MasterConfigParsesLocalFirstStrategy) {
+    MasterConfig config{};
+    config.allocation_strategy = "local_first";
 
-    EXPECT_EQ(std::count(put_start_success.begin(), put_start_success.end(), 1),
-              1);
-    EXPECT_EQ(std::count(put_end_success.begin(), put_end_success.end(), 1), 1);
-    EXPECT_EQ(service_->GetKeyCount(), 1u);
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_id).has_value());
+    WrappedMasterServiceConfig wrapped_config(config, 0);
+    MasterServiceConfig service_config(wrapped_config);
+    EXPECT_EQ(service_config.allocation_strategy_type,
+              AllocationStrategyType::LOCAL_FIRST);
 }
 
-TEST_F(MasterServiceTest, ExpiredGroupedPutCanBeReplacedByUngroupedPut) {
+TEST_F(MasterServiceTest, ProtectCopyMoveSourceFromEviction) {
+    const uint64_t kv_lease_ttl = 100;
+    const uint64_t client_live_ttl = 600;
     auto service_config = MasterServiceConfig::builder()
-                              .set_put_start_discard_timeout_sec(0)
-                              .set_put_start_release_timeout_sec(1)
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .set_client_live_ttl_sec(client_live_ttl)
                               .build();
     std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = context.client_id;
-
-    const std::string key = "expired_grouped_put_to_ungrouped";
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(), 1024,
-                               grouped_config)
-                    .has_value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(2));
-
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    auto put_start = service_->PutStart(client_id, key, TenantId::Default(),
-                                        1024, ungrouped_config);
-    ASSERT_TRUE(put_start.has_value()) << toString(put_start.error());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(service_->ExistKey(key, TenantId::Default()).value_or(false));
-}
 
-TEST_F(MasterServiceTest, BatchRemoveUnregistersGroupedRoute) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+    // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment, each
+    // 16 MB
+    constexpr size_t kBaseAddr = 0x100000000;
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;  // 16 MB
+    [[maybe_unused]] const auto context1 =
+        PrepareSimpleSegment(*service_, "segment_1", kBaseAddr, kSegmentSize);
+    [[maybe_unused]] const auto context2 =
+        PrepareSimpleSegment(*service_, "segment_2", kBaseAddr, kSegmentSize);
 
-    const std::string key = "batch_remove_grouped_route";
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-    PutCompletedObject(*service_, client_id, key, grouped_config);
-
-    auto remove_results = service_->BatchRemove(
-        std::vector<std::string>{key}, TenantId::Default(), /*force=*/true);
-    ASSERT_EQ(remove_results.size(), 1u);
-    ASSERT_TRUE(remove_results[0].has_value());
-
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    PutCompletedObject(*service_, client_id, key, ungrouped_config);
-    EXPECT_TRUE(service_->GetReplicaList(key, TenantId::Default()).has_value());
-}
+    const UUID client_id = context1.client_id;
 
-TEST_F(MasterServiceTest, RemoveByRegexUnregistersGroupedRoute) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+    const std::string copy_key = "copy_key";
+    const std::string move_key = "move_key";
+    uint64_t slice_length = 1024 * 1024;
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.preferred_segment = "segment_1";
 
-    const std::string key = "regex_remove_grouped_route";
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-    PutCompletedObject(*service_, client_id, key, grouped_config);
-
-    auto removed = service_->RemoveByRegex("^regex_remove_grouped_route$",
-                                           TenantId::Default(),
-                                           /*force=*/true);
-    ASSERT_TRUE(removed.has_value());
-    EXPECT_EQ(removed.value(), 1);
-
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    PutCompletedObject(*service_, client_id, key, ungrouped_config);
-    EXPECT_TRUE(service_->GetReplicaList(key, TenantId::Default()).has_value());
-}
+    // Put two objects for move and copy tests.
+    auto put_start_result = service_->PutStart(
+        client_id, copy_key, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    auto put_end_result = service_->PutEnd(
+        client_id, copy_key, TenantId::Default(), ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
 
-TEST_F(MasterServiceTest, GroupedLeaseRefreshNearExpiryProtectsCurrentMembers) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(200).build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+    put_start_result = service_->PutStart(
+        client_id, move_key, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    put_end_result = service_->PutEnd(client_id, move_key, TenantId::Default(),
+                                      ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
 
-    const std::string key_a = "lease_group_key_a";
-    const std::string key_b = "lease_group_key_b";
-    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+    // Start copy and move operations.
+    auto copy_start_result = service_->CopyStart(
+        client_id, copy_key, TenantId::Default(), "segment_1", {"segment_2"});
+    ASSERT_TRUE(copy_start_result.has_value());
 
-    ReplicateConfig config_a;
-    config_a.replica_num = 1;
-    config_a.group_ids = std::vector<std::string>{group_id};
-    ReplicateConfig config_b = config_a;
+    auto move_start_result = service_->MoveStart(
+        client_id, move_key, TenantId::Default(), "segment_1", "segment_2");
+    ASSERT_TRUE(move_start_result.has_value());
 
-    PutCompletedObject(*service_, client_id, key_a, config_a);
-    PutCompletedObject(*service_, client_id, key_b, config_b);
+    // Put more objects to trigger eviction. Do not prefer any segments.
+    config.preferred_segment = "";
+    for (size_t i = 0; i < 128 * (kSegmentSize * 2 / slice_length); ++i) {
+        std::string key = "test_key_" + std::to_string(i);
+        auto put_start_result = service_->PutStart(
+            client_id, key, TenantId::Default(), slice_length, config);
+        if (put_start_result.has_value()) {
+            auto put_end_result = service_->PutEnd(
+                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
+            ASSERT_TRUE(put_end_result.has_value());
+        } else {
+            // wait for eviction to work
+            std::this_thread::sleep_for(std::chrono::milliseconds(50));
+        }
+    }
 
-    auto exists = service_->ExistKey(key_a, TenantId::Default());
-    ASSERT_TRUE(exists.has_value());
-    ASSERT_TRUE(exists.value());
+    // Wait all objects lease expiring and then remove them.
+    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
+    auto remove_all_result = service_->RemoveAll();
+    ASSERT_TRUE(remove_all_result > 0);
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(120));
-    exists = service_->ExistKey(key_a, TenantId::Default());
-    ASSERT_TRUE(exists.has_value());
-    ASSERT_TRUE(exists.value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    // Try end copy and move operations, should success.
+    auto copy_end_result =
+        service_->CopyEnd(client_id, copy_key, TenantId::Default());
+    EXPECT_TRUE(copy_end_result.has_value());
 
-    auto remove_group_peer = service_->Remove(key_b, TenantId::Default());
-    ASSERT_FALSE(remove_group_peer.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_group_peer.error());
+    auto move_end_result =
+        service_->MoveEnd(client_id, move_key, TenantId::Default());
+    EXPECT_TRUE(move_end_result.has_value());
+}
 
-    EXPECT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
-                    .has_value());
-    EXPECT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
-                    .has_value());
-}
-
-TEST_F(MasterServiceTest,
-       GroupedLeaseRefreshAfterMembershipChangeDoesNotWaitForTriggerExpiry) {
+TEST_F(MasterServiceTest, DiscardTimeoutCopyMove) {
+    const uint64_t kv_lease_ttl = 100;
+    const uint64_t client_live_ttl = 600;
+    const uint64_t put_discard_timeout = 1;
+    const uint64_t put_release_timeout = 2;
     auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(500).build();
+        MasterServiceConfig::builder()
+            .set_default_kv_lease_ttl(kv_lease_ttl)
+            .set_client_live_ttl_sec(client_live_ttl)
+            .set_put_start_discard_timeout_sec(put_discard_timeout)
+            .set_put_start_release_timeout_sec(put_release_timeout)
+            .build();
     std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
 
-    const std::string key_a = "lease_group_dirty_key_a";
-    const std::string key_b = "lease_group_dirty_key_b";
-    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
+    // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment, each
+    // 16 MB
+    constexpr size_t kBaseAddr = 0x100000000;
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;  // 16 MB
+    [[maybe_unused]] const auto context1 =
+        PrepareSimpleSegment(*service_, "segment_1", kBaseAddr, kSegmentSize);
+    [[maybe_unused]] const auto context2 =
+        PrepareSimpleSegment(*service_, "segment_2", kBaseAddr, kSegmentSize);
+
+    const UUID client_id = context1.client_id;
 
+    const std::string copy_key = "copy_key";
+    const std::string move_key = "move_key";
+    uint64_t slice_length = 1024 * 1024;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.group_ids = std::vector<std::string>{group_id};
+    config.preferred_segment = "segment_1";
+
+    // Put two objects for move and copy tests.
+    auto put_start_result = service_->PutStart(
+        client_id, copy_key, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    auto put_end_result = service_->PutEnd(
+        client_id, copy_key, TenantId::Default(), ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
 
-    PutCompletedObject(*service_, client_id, key_a, config);
-    ASSERT_TRUE(service_->ExistKey(key_a, TenantId::Default()).value_or(false));
+    put_start_result = service_->PutStart(
+        client_id, move_key, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    put_end_result = service_->PutEnd(client_id, move_key, TenantId::Default(),
+                                      ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
 
-    PutCompletedObject(*service_, client_id, key_b, config);
-    std::this_thread::sleep_for(std::chrono::milliseconds(150));
+    // Start copy and move operations.
+    auto copy_start_result = service_->CopyStart(
+        client_id, copy_key, TenantId::Default(), "segment_1", {"segment_2"});
+    ASSERT_TRUE(copy_start_result.has_value());
 
-    auto exists = service_->ExistKey(key_a, TenantId::Default());
-    ASSERT_TRUE(exists.has_value());
-    ASSERT_TRUE(exists.value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(390));
+    auto move_start_result = service_->MoveStart(
+        client_id, move_key, TenantId::Default(), "segment_1", "segment_2");
+    ASSERT_TRUE(move_start_result.has_value());
 
-    auto remove_group_peer = service_->Remove(key_b, TenantId::Default());
-    ASSERT_FALSE(remove_group_peer.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_group_peer.error());
+    // Wait for the operations timeout.
+    std::this_thread::sleep_for(std::chrono::seconds(put_release_timeout));
 
-    EXPECT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
-                    .has_value());
-    EXPECT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
-                    .has_value());
+    // Put more objects to trigger eviction. Do not prefer any segments.
+    config.preferred_segment = "";
+    for (size_t i = 0; i < 128 * (kSegmentSize * 2 / slice_length); ++i) {
+        std::string key = "test_key_" + std::to_string(i);
+        auto put_start_result = service_->PutStart(
+            client_id, key, TenantId::Default(), slice_length, config);
+        if (put_start_result.has_value()) {
+            auto put_end_result = service_->PutEnd(
+                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
+            ASSERT_TRUE(put_end_result.has_value());
+        } else {
+            // wait for eviction to work
+            std::this_thread::sleep_for(std::chrono::milliseconds(50));
+        }
+    }
+
+    // Try end copy and move operations, should fail because the objects are
+    // evicted.
+    auto copy_end_result =
+        service_->CopyEnd(client_id, copy_key, TenantId::Default());
+    EXPECT_FALSE(copy_end_result.has_value());
+    EXPECT_EQ(copy_end_result.error(), ErrorCode::OBJECT_NOT_FOUND);
+
+    auto move_end_result =
+        service_->MoveEnd(client_id, move_key, TenantId::Default());
+    EXPECT_FALSE(move_end_result.has_value());
+    EXPECT_EQ(move_end_result.error(), ErrorCode::OBJECT_NOT_FOUND);
 }
 
-TEST_F(MasterServiceTest, RemoveGroupedMemberPreservesOtherMembers) {
+TEST_F(MasterServiceTest, CleanupStaleHandlesTest) {
     std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    const std::string key_a = "remove_group_key_a";
-    const std::string key_b = "remove_group_key_b";
-    const std::string group_id = FindGroupIdOnDifferentShard(key_a);
 
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.group_ids = std::vector<std::string>{group_id};
-    PutCompletedObject(*service_, client_id, key_a, config);
-    PutCompletedObject(*service_, client_id, key_b, config);
+    // Mount a segment for testing
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t size = 1024 * 1024 * 16;  // 16MB
+    auto segment = MakeSegment("test_segment", buffer, size);
+    UUID client_id = generate_uuid();
 
-    ASSERT_TRUE(service_->Remove(key_a, TenantId::Default(), /*force=*/true)
-                    .has_value());
+    // Mount the segment
+    auto mount_result = service_->MountSegment(segment, client_id);
+    ASSERT_TRUE(mount_result.has_value());
 
-    auto removed_exists = service_->ExistKey(key_a, TenantId::Default());
-    ASSERT_TRUE(removed_exists.has_value());
-    EXPECT_FALSE(removed_exists.value());
-    EXPECT_TRUE(
-        service_->GetReplicaList(key_b, TenantId::Default()).has_value());
+    // Create an object that will be stored in the segment
+    std::string key = "segment_object";
+    uint64_t slice_length = 1024 * 1024;  // One 1MB slice
+    ReplicateConfig config;
+    config.replica_num = 1;  // One replica
 
-    ASSERT_TRUE(service_->Remove(key_b, TenantId::Default(), /*force=*/true)
-                    .has_value());
-    auto group_empty = service_->ExistKey(key_b, TenantId::Default());
-    ASSERT_TRUE(group_empty.has_value());
-    EXPECT_FALSE(group_empty.value());
-}
+    // Create the object
+    auto put_start_result = service_->PutStart(
+        client_id, key, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
+                                           ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
 
-TEST_F(MasterServiceTest, UpsertPreservesGroupMembership) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+    // Verify object exists
+    auto get_result = service_->GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(get_result.has_value());
+    auto retrieved_replicas = get_result.value().replicas;
+    ASSERT_EQ(1, retrieved_replicas.size());
 
-    const std::string key = "upsert_group_key";
-    const std::string group_id = FindGroupIdOnDifferentShard(key);
+    // Unmount the segment
+    auto unmount_result1 = service_->UnmountSegment(segment.id, client_id);
+    ASSERT_TRUE(unmount_result1.has_value());
 
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids = std::vector<std::string>{group_id};
-    PutCompletedObject(*service_, client_id, key, grouped_config);
+    // Try to get the object - it should be automatically removed since the
+    // replica is invalid
+    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
+    EXPECT_FALSE(get_result2.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result2.error());
 
-    ReplicateConfig unset_group_config;
-    unset_group_config.replica_num = 1;
-    auto preserve_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), 1024, unset_group_config);
-    ASSERT_TRUE(preserve_result.has_value())
-        << "Unset group_ids should preserve existing group membership";
-    ASSERT_TRUE(service_
-                    ->UpsertEnd(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                    .has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, TenantId::Default()).has_value());
-
-    ReplicateConfig different_group_config;
-    different_group_config.replica_num = 1;
-    different_group_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key + "_other")};
-    auto different_group_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), 1024, different_group_config);
-    ASSERT_FALSE(different_group_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, different_group_result.error());
-
-    ReplicateConfig explicit_ungrouped_config;
-    explicit_ungrouped_config.replica_num = 1;
-    explicit_ungrouped_config.group_ids = std::vector<std::string>{""};
-    auto explicit_ungrouped_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), 1024, explicit_ungrouped_config);
-    ASSERT_FALSE(explicit_ungrouped_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, explicit_ungrouped_result.error());
-}
+    // Mount the segment again
+    mount_result = service_->MountSegment(segment, client_id);
+    ASSERT_TRUE(mount_result.has_value());
 
-TEST_F(MasterServiceTest, IncompleteGroupedUpsertCanBecomeUngrouped) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = context.client_id;
+    // Create another object
+    std::string key2 = "another_segment_object";
+    auto put_start_result2 = service_->PutStart(
+        client_id, key2, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result2.has_value());
+    auto put_end_result2 = service_->PutEnd(
+        client_id, key2, TenantId::Default(), ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result2.has_value());
 
-    const std::string key = "incomplete_grouped_upsert_to_ungrouped";
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
+    // Verify we can get it
+    auto get_result3 = service_->GetReplicaList(key2, TenantId::Default());
+    ASSERT_TRUE(get_result3.has_value());
 
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(), 1024,
-                               grouped_config)
-                    .has_value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(2));
+    // Unmount the segment
+    auto unmount_result2 = service_->UnmountSegment(segment.id, client_id);
+    ASSERT_TRUE(unmount_result2.has_value());
 
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    auto upsert_start = service_->UpsertStart(
-        client_id, key, TenantId::Default(), 1024, ungrouped_config);
-    ASSERT_TRUE(upsert_start.has_value()) << toString(upsert_start.error());
-    ASSERT_TRUE(service_
-                    ->UpsertEnd(client_id, key, TenantId::Default(),
-                                ReplicaType::MEMORY)
-                    .has_value());
-    EXPECT_TRUE(service_->ExistKey(key, TenantId::Default()).value_or(false));
+    // Try to remove the object that should already be cleaned up
+    auto remove_result = service_->Remove(key2, TenantId::Default());
+    EXPECT_FALSE(remove_result.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, remove_result.error());
 }
 
-TEST_F(MasterServiceTest, UpsertRejectsExistingUngroupedToGrouped) {
+TEST_F(MasterServiceTest, UnmountSegmentHidesReplicasBeforeAsyncCleanup) {
     std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
 
-    const std::string key = "upsert_ungrouped_to_grouped";
-    ReplicateConfig ungrouped_config;
-    ungrouped_config.replica_num = 1;
-    PutCompletedObject(*service_, client_id, key, ungrouped_config);
-
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(key)};
-    auto upsert_start = service_->UpsertStart(
-        client_id, key, TenantId::Default(), 2048, grouped_config);
-    ASSERT_FALSE(upsert_start.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, upsert_start.error());
-
-    EXPECT_TRUE(service_->GetReplicaList(key, TenantId::Default()).has_value());
-}
+    // Mount two segments for testing
+    constexpr size_t buffer1 = 0x300000000;
+    constexpr size_t buffer2 = 0x400000000;
+    constexpr size_t size = 1024 * 1024 * 16;
 
-TEST_F(MasterServiceTest,
-       GroupedEvictionExpandsSafeMembersAndSkipsLeasedGroup) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(1000).build();
-    constexpr size_t kSegmentSize = 4 * 1024 * 1024;
-    constexpr size_t kObjectSize = 2 * 1024 * 1024;
+    auto segment1 = MakeSegment("segment1", buffer1, size);
+    auto segment2 = MakeSegment("segment2", buffer2, size);
+    UUID client_id = generate_uuid();
+    auto mount_result1 = service_->MountSegment(segment1, client_id);
+    ASSERT_TRUE(mount_result1.has_value());
+    auto mount_result2 = service_->MountSegment(segment2, client_id);
+    ASSERT_TRUE(mount_result2.has_value());
 
-    {
-        std::unique_ptr<MasterService> service_(
-            new MasterService(service_config));
-        [[maybe_unused]] const auto context =
-            PrepareSimpleSegment(*service_, "grouped_evict_segment",
-                                 kDefaultSegmentBase, kSegmentSize);
-        const UUID client_id = generate_uuid();
+    // Create two objects in the two segments
+    std::string key1 =
+        GenerateKeyForSegment(client_id, service_, segment1.name);
+    std::string key2 =
+        GenerateKeyForSegment(client_id, service_, segment2.name);
+    uint64_t slice_length = 1024;
+    ReplicateConfig config;
+    config.replica_num = 1;
 
-        const std::string evict_key_a = "grouped_evict_key_a";
-        const std::string evict_key_b = "grouped_evict_key_b";
-        ReplicateConfig evict_config;
-        evict_config.replica_num = 1;
-        evict_config.group_ids =
-            std::vector<std::string>{FindGroupIdOnDifferentShard(evict_key_a)};
-        PutCompletedObject(*service_, client_id, evict_key_a, evict_config,
-                           kObjectSize);
-        PutCompletedObject(*service_, client_id, evict_key_b, evict_config,
-                           kObjectSize);
+    PauseReplicaCleanup(*service_);
 
-        ReplicateConfig trigger_config;
-        trigger_config.replica_num = 1;
-        auto trigger_result = service_->PutStart(
-            client_id, "trigger_grouped_eviction", TenantId::Default(),
-            kObjectSize, trigger_config);
-        ASSERT_FALSE(trigger_result.has_value());
-        EXPECT_EQ(ErrorCode::NO_AVAILABLE_HANDLE, trigger_result.error());
+    // Unmount segment1. The allocator becomes unavailable synchronously while
+    // physical metadata cleanup runs on the background worker.
+    auto unmount_result1 = service_->UnmountSegment(segment1.id, client_id);
+    ASSERT_TRUE(unmount_result1.has_value());
 
-        std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    // Query paths must not expose the unavailable replica while its physical
+    // metadata is still waiting for background cleanup.
+    ASSERT_EQ(2u, service_->GetKeyCount());
+    auto get_result1 = service_->GetReplicaList(key1, TenantId::Default());
+    ASSERT_FALSE(get_result1.has_value());
+    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result1.error());
+
+    auto exists1 = service_->ExistKey(key1, TenantId::Default());
+    ASSERT_TRUE(exists1.has_value());
+    EXPECT_FALSE(*exists1);
+    auto exists2 = service_->ExistKey(key2, TenantId::Default());
+    ASSERT_TRUE(exists2.has_value());
+    EXPECT_TRUE(*exists2);
+
+    auto batch_exists =
+        service_->BatchExistKey({key1, key2}, TenantId::Default());
+    ASSERT_EQ(2u, batch_exists.size());
+    ASSERT_TRUE(batch_exists[0].has_value());
+    EXPECT_FALSE(*batch_exists[0]);
+    ASSERT_TRUE(batch_exists[1].has_value());
+    EXPECT_TRUE(*batch_exists[1]);
+
+    auto all_keys = service_->GetAllKeys(TenantId::Default());
+    ASSERT_TRUE(all_keys.has_value());
+    EXPECT_EQ(all_keys->end(),
+              std::find(all_keys->begin(), all_keys->end(), key1));
+    EXPECT_NE(all_keys->end(),
+              std::find(all_keys->begin(), all_keys->end(), key2));
 
-        EXPECT_FALSE(service_->ExistKey(evict_key_a, TenantId::Default())
-                         .value_or(true));
-        EXPECT_FALSE(service_->ExistKey(evict_key_b, TenantId::Default())
-                         .value_or(true));
-    }
+    // Verify objects in segment2 is still there
+    auto get_result2 = service_->GetReplicaList(key2, TenantId::Default());
+    ASSERT_TRUE(get_result2.has_value());
 
-    {
-        std::unique_ptr<MasterService> service_(
-            new MasterService(service_config));
-        [[maybe_unused]] const auto context =
-            PrepareSimpleSegment(*service_, "grouped_lease_segment",
-                                 kDefaultSegmentBase, kSegmentSize);
-        const UUID client_id = generate_uuid();
+    // The worker eventually removes the old physical metadata, after which
+    // the same key can be inserted again.
+    ResumeReplicaCleanup(*service_);
+    for (size_t i = 0; i < 100 && service_->GetKeyCount() != 1; ++i) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    ASSERT_EQ(1u, service_->GetKeyCount());
 
-        const std::string leased_key_a = "grouped_leased_key_a";
-        const std::string leased_key_b = "grouped_leased_key_b";
-        ReplicateConfig leased_config;
-        leased_config.replica_num = 1;
-        leased_config.group_ids =
-            std::vector<std::string>{FindGroupIdOnDifferentShard(leased_key_a)};
-        PutCompletedObject(*service_, client_id, leased_key_a, leased_config,
-                           kObjectSize);
-        PutCompletedObject(*service_, client_id, leased_key_b, leased_config,
-                           kObjectSize);
-
-        auto exists = service_->ExistKey(leased_key_a, TenantId::Default());
-        ASSERT_TRUE(exists.has_value());
-        ASSERT_TRUE(exists.value());
+    // Verify put key1 will put into segment2 rather than segment1
+    auto put_start_result = service_->PutStart(
+        client_id, key1, TenantId::Default(), slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    replica_list = put_start_result.value();
+    auto put_end_result = service_->PutEnd(client_id, key1, TenantId::Default(),
+                                           ReplicaType::MEMORY);
+    ASSERT_TRUE(put_end_result.has_value());
+    auto get_result3 = service_->GetReplicaList(key1, TenantId::Default());
+    ASSERT_TRUE(get_result3.has_value());
+    auto retrieved = get_result3.value();
+    ASSERT_EQ(replica_list[0]
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_,
+              segment2.name);
+    EXPECT_EQ(2u, service_->GetKeyCount());
+}
+
+// A mass client expiry marks handles stale all over the metadata table, so
+// the sweep cleans a shard in bounded write-lock batches instead of holding
+// it exclusively for the whole walk. Dropping and retaking the lock mid-shard
+// must not cost coverage: every key of the departed segment is erased, and
+// every key of a live segment survives. The keys are forced onto one shard
+// because the batch bound is per shard.
+TEST_F(MasterServiceTest, ClearInvalidHandlesSweepsShardAcrossLockBatches) {
+    auto service = std::make_unique<MasterService>();
+    PauseReplicaCleanup(*service);
+
+    constexpr size_t kSegmentSize = 1024 * 1024 * 128;
+    const std::string stale_segment_name = "batch_sweep_stale_segment";
+    const std::string live_segment_name = "batch_sweep_live_segment";
+    const auto stale_segment = PrepareSimpleSegment(
+        *service, stale_segment_name, 0x300000000, kSegmentSize);
+    const auto live_segment = PrepareSimpleSegment(*service, live_segment_name,
+                                                   0x400000000, kSegmentSize);
+
+    // Enough keys per segment that draining the shard takes several batches.
+    constexpr size_t kKeysPerSegment = 100;
+    const size_t target_shard =
+        MetadataShardIndex(*service, "batch_sweep_seed");
+
+    std::vector<std::string> stale_keys;
+    std::vector<std::string> live_keys;
+    for (size_t i = 0;
+         stale_keys.size() + live_keys.size() < 2 * kKeysPerSegment; ++i) {
+        ASSERT_LT(i, 1000000u)
+            << "could not gather enough keys on shard " << target_shard;
+        const std::string key = "batch_sweep_key_" + std::to_string(i);
+        if (MetadataShardIndex(*service, key) != target_shard) {
+            continue;
+        }
 
-        ReplicateConfig trigger_config;
-        trigger_config.replica_num = 1;
-        auto trigger_result = service_->PutStart(
-            client_id, "trigger_leased_group_eviction", TenantId::Default(),
-            kObjectSize, trigger_config);
-        ASSERT_FALSE(trigger_result.has_value());
-        EXPECT_EQ(ErrorCode::NO_AVAILABLE_HANDLE, trigger_result.error());
+        const bool on_stale_segment = stale_keys.size() < kKeysPerSegment;
+        const UUID& client_id =
+            on_stale_segment ? stale_segment.client_id : live_segment.client_id;
+        const std::string& segment_name =
+            on_stale_segment ? stale_segment_name : live_segment_name;
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.preferred_segments = {segment_name};
+
+        auto put_start = service->PutStart(client_id, key, TenantId::Default(),
+                                           1024, config);
+        ASSERT_TRUE(put_start.has_value()) << "key=" << key;
+        ASSERT_EQ(1u, put_start->size());
+        ASSERT_EQ(segment_name, (*put_start)[0]
+                                    .get_memory_descriptor()
+                                    .buffer_descriptor.transport_endpoint_);
+        ASSERT_TRUE(service
+                        ->PutEnd(client_id, key, TenantId::Default(),
+                                 ReplicaType::MEMORY)
+                        .has_value());
+        (on_stale_segment ? stale_keys : live_keys).push_back(key);
+    }
 
-        std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    ASSERT_TRUE(
+        service
+            ->UnmountSegment(stale_segment.segment_id, stale_segment.client_id)
+            .has_value());
+    ClearInvalidHandlesForTest(*service);
 
-        EXPECT_TRUE(service_->GetReplicaList(leased_key_a, TenantId::Default())
-                        .has_value());
-        EXPECT_TRUE(service_->GetReplicaList(leased_key_b, TenantId::Default())
-                        .has_value());
+    // GetKeyCount counts physical metadata, so it distinguishes "swept" from
+    // "merely hidden from the read paths by the unmount".
+    EXPECT_EQ(live_keys.size(), service->GetKeyCount());
+    for (const auto& key : stale_keys) {
+        auto get_result = service->GetReplicaList(key, TenantId::Default());
+        ASSERT_FALSE(get_result.has_value()) << "key=" << key;
+        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error())
+            << "key=" << key;
+    }
+    for (const auto& key : live_keys) {
+        auto get_result = service->GetReplicaList(key, TenantId::Default());
+        ASSERT_TRUE(get_result.has_value()) << "key=" << key << " was swept";
+        ASSERT_EQ(1u, get_result->replicas.size()) << "key=" << key;
+        EXPECT_TRUE(get_result->replicas[0].is_memory_replica())
+            << "key=" << key;
     }
 }
 
-TEST_F(MasterServiceTest, GroupedEvictionSkipsUnsafeMembersAndEvictsSafePeers) {
-    constexpr size_t kSegmentSize = 4 * 1024 * 1024;
-    constexpr size_t kObjectSize = 2 * 1024 * 1024;
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "grouped_mixed_safety_segment",
-                             kDefaultSegmentBase, kSegmentSize);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, UnmountSegmentKeepsSynchronousCleanupInHaMode) {
+    auto config = MasterServiceConfig::builder().set_enable_ha(true).build();
+    auto service = std::make_unique<MasterService>(config);
 
-    const std::string safe_key = "grouped_mixed_safe_key";
-    const std::string hard_pinned_key = "grouped_mixed_hard_pinned_key";
-    const std::string group_id = FindGroupIdOnDifferentShard(safe_key);
+    auto segment = MakeSegment("ha_sync_segment");
+    UUID client_id = generate_uuid();
+    ASSERT_TRUE(service->MountSegment(segment, client_id).has_value());
+    const auto key = GenerateKeyForSegment(client_id, service, segment.name);
+    auto exists = service->ExistKey(key, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    ASSERT_TRUE(exists.value());
 
-    ReplicateConfig safe_config;
-    safe_config.replica_num = 1;
-    safe_config.group_ids = std::vector<std::string>{group_id};
-    PutCompletedObject(*service_, client_id, safe_key, safe_config,
-                       kObjectSize);
-
-    ReplicateConfig hard_pinned_config = safe_config;
-    hard_pinned_config.with_hard_pin = true;
-    PutCompletedObject(*service_, client_id, hard_pinned_key,
-                       hard_pinned_config, kObjectSize);
-
-    ReplicateConfig trigger_config;
-    trigger_config.replica_num = 1;
-    auto trigger_result =
-        service_->PutStart(client_id, "trigger_mixed_safety_group_eviction",
-                           TenantId::Default(), kObjectSize, trigger_config);
-    ASSERT_FALSE(trigger_result.has_value());
-    EXPECT_EQ(ErrorCode::NO_AVAILABLE_HANDLE, trigger_result.error());
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(200));
-
-    EXPECT_FALSE(
-        service_->ExistKey(safe_key, TenantId::Default()).value_or(true));
-    EXPECT_TRUE(service_->GetReplicaList(hard_pinned_key, TenantId::Default())
-                    .has_value());
-    EXPECT_TRUE(
-        service_->Remove(hard_pinned_key, TenantId::Default(), /*force=*/true)
-            .has_value());
+    ASSERT_TRUE(service->UnmountSegment(segment.id, client_id).has_value());
+    EXPECT_EQ(0u, service->GetKeyCount());
 }
 
-TEST_F(MasterServiceTest, BatchUpsertStartMixedGroupIdsPreservesOrder) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    const std::vector<std::string> keys = {
-        "batch_grouped_a",
-        "batch_ungrouped",
-        "batch_grouped_b",
-    };
-    const std::vector<uint64_t> sizes = {1024, 2048, 4096};
+TEST_F(MasterServiceTest, CopyInProgressDoesNotKeepUnmountedSourceVisible) {
+    auto service = std::make_unique<MasterService>();
+    const auto source =
+        PrepareSimpleSegment(*service, "copy_source", kDefaultSegmentBase);
+    PrepareSimpleSegment(*service, "copy_target",
+                         kDefaultSegmentBase + kDefaultSegmentSize);
 
+    const UUID client_id = source.client_id;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(keys[0]), "",
-                                 FindGroupIdOnDifferentShard(keys[2])};
-
-    auto results = service_->BatchUpsertStart(
-        client_id, keys, TenantId::Default(), sizes, config);
-    ASSERT_EQ(results.size(), keys.size());
-    for (const auto& result : results) {
-        ASSERT_TRUE(result.has_value());
-    }
+    config.preferred_segment = "copy_source";
+    PutCompletedObject(*service, client_id, "copy_key", config);
+    ASSERT_TRUE(service
+                    ->CopyStart(client_id, "copy_key", TenantId::Default(),
+                                "copy_source", {"copy_target"})
+                    .has_value());
 
-    auto end_results = service_->BatchUpsertEnd(
-        client_id, MakeObjectMetas(keys), TenantId::Default());
-    ASSERT_EQ(end_results.size(), keys.size());
-    for (const auto& result : end_results) {
-        ASSERT_TRUE(result.has_value());
-    }
+    PauseReplicaCleanup(*service);
+    ASSERT_TRUE(service->UnmountSegment(source.segment_id, source.client_id)
+                    .has_value());
 
-    for (const auto& key : keys) {
-        EXPECT_TRUE(
-            service_->GetReplicaList(key, TenantId::Default()).has_value());
-    }
+    ExpectKeyHiddenFromReadApis(*service, "copy_key");
 
-    ReplicateConfig invalid_config = config;
-    invalid_config.group_ids = std::vector<std::string>{"only_one"};
-    auto invalid_results = service_->BatchUpsertStart(
-        client_id, keys, TenantId::Default(), sizes, invalid_config);
-    ASSERT_EQ(invalid_results.size(), keys.size());
-    for (const auto& result : invalid_results) {
-        ASSERT_FALSE(result.has_value());
-        EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
-    }
+    ASSERT_TRUE(service->CopyRevoke(client_id, "copy_key", TenantId::Default())
+                    .has_value());
+    ResumeReplicaCleanup(*service);
 }
 
-TEST_F(MasterServiceTest, WrappedBatchPutStartMixedGroupIdsPreservesOrder) {
-    WrappedMasterServiceConfig service_config;
-    service_config.default_kv_lease_ttl = 100;
-    service_config.enable_metric_reporting = false;
-    WrappedMasterService service_(service_config);
-
-    Segment segment = MakeSegment("wrapped_batch_group_segment");
-    const UUID client_id = generate_uuid();
-    ASSERT_TRUE(service_.MountSegment(segment, client_id).has_value());
-
-    const std::vector<std::string> keys = {
-        "wrapped_batch_grouped_a",
-        "wrapped_batch_ungrouped",
-        "wrapped_batch_grouped_b",
-    };
-    const std::vector<uint64_t> sizes = {1024, 2048, 4096};
+TEST_F(MasterServiceTest, MoveInProgressDoesNotKeepUnmountedSourceVisible) {
+    auto service = std::make_unique<MasterService>();
+    const auto source =
+        PrepareSimpleSegment(*service, "move_source", kDefaultSegmentBase);
+    PrepareSimpleSegment(*service, "move_target",
+                         kDefaultSegmentBase + kDefaultSegmentSize);
 
+    const UUID client_id = source.client_id;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.group_ids =
-        std::vector<std::string>{FindGroupIdOnDifferentShard(keys[0]), "",
-                                 FindGroupIdOnDifferentShard(keys[2])};
-
-    auto results = service_.BatchPutStart(client_id, keys, sizes, config);
-    ASSERT_EQ(results.size(), keys.size());
-    for (const auto& result : results) {
-        ASSERT_TRUE(result.has_value()) << toString(result.error());
-    }
-
-    auto end_results = service_.BatchPutEnd(client_id, MakeObjectMetas(keys));
-    ASSERT_EQ(end_results.size(), keys.size());
-    for (const auto& result : end_results) {
-        ASSERT_TRUE(result.has_value());
-    }
+    config.preferred_segment = "move_source";
+    PutCompletedObject(*service, client_id, "move_key", config);
+    ASSERT_TRUE(service
+                    ->MoveStart(client_id, "move_key", TenantId::Default(),
+                                "move_source", "move_target")
+                    .has_value());
 
-    for (const auto& key : keys) {
-        EXPECT_TRUE(
-            service_.GetReplicaList(key, std::string(TenantId::kDefaultValue))
-                .has_value());
-    }
+    PauseReplicaCleanup(*service);
+    ASSERT_TRUE(service->UnmountSegment(source.segment_id, source.client_id)
+                    .has_value());
 
-    ReplicateConfig invalid_config = config;
-    invalid_config.group_ids = std::vector<std::string>{"only_one"};
-    auto invalid_group_results =
-        service_.BatchPutStart(client_id, keys, sizes, invalid_config);
-    ASSERT_EQ(invalid_group_results.size(), keys.size());
-    for (const auto& result : invalid_group_results) {
-        ASSERT_FALSE(result.has_value());
-        EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
-    }
+    ExpectKeyHiddenFromReadApis(*service, "move_key");
 
-    auto invalid_size_results =
-        service_.BatchPutStart(client_id, keys, {1024}, config);
-    ASSERT_EQ(invalid_size_results.size(), keys.size());
-    for (const auto& result : invalid_size_results) {
-        ASSERT_FALSE(result.has_value());
-        EXPECT_EQ(ErrorCode::INVALID_PARAMS, result.error());
-    }
+    ASSERT_TRUE(service->MoveRevoke(client_id, "move_key", TenantId::Default())
+                    .has_value());
+    ResumeReplicaCleanup(*service);
 }
 
-TEST_F(MasterServiceTest, TenantPutGetRemoveIsolatesSameUserKey) {
-    const std::string key = "shared_user_key";
-    const TenantId tenant_a("tenant_a");
-    const TenantId tenant_b("tenant_b");
-    auto service_ = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, MoveEndReleasesSourceRefcountWhenTargetGone) {
+    // The client-visible flow (MoveEnd fails with REPLICA_IS_GONE, a
+    // subsequent UpsertStart succeeds, MoveRevoke reports no task) is covered
+    // by the MoveEndWithVanishedTargetReleasesSource scenario. This test keeps
+    // the private invariant: the source refcount must be released before the
+    // move task is erased.
+    auto service = std::make_unique<MasterService>();
+    const auto source =
+        PrepareSimpleSegment(*service, "refcnt_source", kDefaultSegmentBase);
+    const auto target = PrepareSimpleSegment(
+        *service, "refcnt_target", kDefaultSegmentBase + kDefaultSegmentSize);
 
+    const UUID client_id = source.client_id;
     ReplicateConfig config;
     config.replica_num = 1;
+    config.preferred_segment = "refcnt_source";
+    PutCompletedObject(*service, client_id, "refcnt_key", config);
 
-    ASSERT_TRUE(
-        service_->PutStart(client_id, key, tenant_a, 1024, config).has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY)
+    ASSERT_TRUE(service
+                    ->MoveStart(client_id, "refcnt_key", TenantId::Default(),
+                                "refcnt_source", "refcnt_target")
                     .has_value());
-    ASSERT_TRUE(
-        service_->PutStart(client_id, key, tenant_b, 2048, config).has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY)
+    ASSERT_TRUE(service->UnmountSegment(target.segment_id, target.client_id)
                     .has_value());
 
-    EXPECT_FALSE(
-        service_->GetReplicaList(key, TenantId::Default()).has_value());
-    EXPECT_FALSE(service_->ExistKey(key, TenantId::Default()).value());
-    EXPECT_TRUE(service_->ExistKey(key, tenant_a).value());
-    EXPECT_TRUE(service_->ExistKey(key, tenant_b).value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
-    EXPECT_EQ(service_->GetKeyCount(), 2u);
+    auto move_end =
+        service->MoveEnd(client_id, "refcnt_key", TenantId::Default());
+    ASSERT_FALSE(move_end.has_value());
+    EXPECT_EQ(ErrorCode::REPLICA_IS_GONE, move_end.error());
 
-    ASSERT_TRUE(service_->Remove(key, tenant_a, /*force=*/true).has_value());
-    EXPECT_FALSE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
-    EXPECT_EQ(service_->GetKeyCount(), 1u);
+    const auto source_refcnt =
+        GetReplicaRefcntBySegmentName(*service, "refcnt_key", "refcnt_source");
+    ASSERT_TRUE(source_refcnt.has_value());
+    EXPECT_EQ(0, source_refcnt.value());
 }
 
-TEST_F(MasterServiceTest, RegexOperationsAreTenantScoped) {
-    const std::string key = "regex_shared_key";
-    const TenantId tenant_a("tenant_regex_a");
-    const TenantId tenant_b("tenant_regex_b");
-    auto service_ = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, PutStartPartialAllocationIsObservable) {
+    std::unique_ptr<MasterService> service_(new MasterService());
 
-    ReplicateConfig config;
-    config.replica_num = 1;
+    // Mount two segments only
+    constexpr size_t buffer1 = 0x300000000;
+    constexpr size_t buffer2 = 0x400000000;
+    constexpr size_t segment_size = 1024 * 1024 * 64;  // 64MB
 
-    ASSERT_TRUE(
-        service_->PutStart(client_id, key, TenantId::Default(), 1024, config)
-            .has_value());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    ASSERT_TRUE(
-        service_->PutStart(client_id, key, tenant_a, 1024, config).has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY)
-                    .has_value());
-    ASSERT_TRUE(
-        service_->PutStart(client_id, key, tenant_b, 1024, config).has_value());
-    ASSERT_TRUE(service_->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY)
-                    .has_value());
+    auto segment1 = MakeSegment("segment1", buffer1, segment_size);
+    auto segment2 = MakeSegment("segment2", buffer2, segment_size);
+    UUID client_id = generate_uuid();
+    ASSERT_TRUE(service_->MountSegment(segment1, client_id).has_value());
+    ASSERT_TRUE(service_->MountSegment(segment2, client_id).has_value());
 
-    auto default_matches =
-        service_->GetReplicaListByRegex("^regex_shared", TenantId::Default());
-    ASSERT_TRUE(default_matches.has_value());
-    EXPECT_EQ(default_matches->size(), 1);
+    auto& metrics = MasterMetricManager::instance();
+    const int64_t partial_before = metrics.get_put_start_partial_allocations();
 
-    auto remove_default = service_->RemoveByRegex(
-        "^regex_shared", TenantId::Default(), /*force=*/true);
-    ASSERT_TRUE(remove_default.has_value());
-    EXPECT_EQ(remove_default.value(), 1);
-    EXPECT_FALSE(
-        service_->GetReplicaList(key, TenantId::Default()).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
+    // Request more replicas than available segments: best-effort keeps the
+    // put successful but the degradation must be recorded.
+    ReplicateConfig config;
+    config.replica_num = 3;
+    auto put_start_result = service_->PutStart(
+        client_id, "partial_alloc_key", TenantId::Default(), 1024, config);
+    ASSERT_TRUE(put_start_result.has_value());
+    ASSERT_EQ(2u, put_start_result->size());
+    ASSERT_EQ(metrics.get_put_start_partial_allocations(), partial_before + 1);
 
-    auto remove_tenant_a =
-        service_->RemoveByRegex("^regex_shared", tenant_a, /*force=*/true);
-    ASSERT_TRUE(remove_tenant_a.has_value());
-    EXPECT_EQ(remove_tenant_a.value(), 1);
-    EXPECT_FALSE(service_->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_TRUE(service_->GetReplicaList(key, tenant_b).has_value());
+    // A fully satisfied allocation must not be counted as partial.
+    ReplicateConfig full_config;
+    full_config.replica_num = 2;
+    auto full_result = service_->PutStart(
+        client_id, "full_alloc_key", TenantId::Default(), 1024, full_config);
+    ASSERT_TRUE(full_result.has_value());
+    ASSERT_EQ(2u, full_result->size());
+    ASSERT_EQ(metrics.get_put_start_partial_allocations(), partial_before + 1);
 }
 
-TEST_F(MasterServiceTest, TenantBatchUpsertAndRevokeAreScoped) {
-    const std::vector<std::string> keys = {"tenant_batch_upsert_key_a",
-                                           "tenant_batch_upsert_key_b"};
-    const std::vector<uint64_t> sizes = {1024, 2048};
-    const TenantId tenant_a("tenant_batch_upsert_a");
-    const TenantId tenant_b("tenant_batch_upsert_b");
-    auto svc = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*svc);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, UnmountSegmentPerformance) {
+    std::unique_ptr<MasterService> service_(new MasterService());
+    constexpr size_t kBufferAddress = 0x300000000;
+    constexpr size_t kSegmentSize = 1024 * 1024 * 256;  // 256MB
+    std::string segment_name = "perf_test_segment";
+    auto segment = MakeSegment(segment_name, kBufferAddress, kSegmentSize);
+    UUID client_id = generate_uuid();
 
-    ReplicateConfig config;
-    config.replica_num = 1;
+    // Mount a segment for testing
+    auto mount_result = service_->MountSegment(segment, client_id);
+    ASSERT_TRUE(mount_result.has_value());
 
-    auto tenant_a_results =
-        svc->BatchUpsertStart(client_id, keys, tenant_a, sizes, config);
-    ASSERT_EQ(tenant_a_results.size(), keys.size());
-    for (const auto& result : tenant_a_results) {
-        ASSERT_TRUE(result.has_value());
-    }
-    auto tenant_a_end =
-        svc->BatchUpsertEnd(client_id, MakeObjectMetas(keys), tenant_a);
-    ASSERT_EQ(tenant_a_end.size(), keys.size());
-    for (const auto& result : tenant_a_end) {
-        ASSERT_TRUE(result.has_value());
-    }
+    // Create 10000 keys for testing
+    constexpr int kNumKeys = 1000;
+    std::vector<std::string> keys;
+    keys.reserve(kNumKeys);
 
-    auto tenant_b_results =
-        svc->BatchUpsertStart(client_id, keys, tenant_b, sizes, config);
-    ASSERT_EQ(tenant_b_results.size(), keys.size());
-    for (const auto& result : tenant_b_results) {
-        ASSERT_TRUE(result.has_value());
-    }
-    auto tenant_b_end =
-        svc->BatchUpsertEnd(client_id, MakeObjectMetas(keys), tenant_b);
-    ASSERT_EQ(tenant_b_end.size(), keys.size());
-    for (const auto& result : tenant_b_end) {
-        ASSERT_TRUE(result.has_value());
-    }
+    auto start = std::chrono::steady_clock::now();
 
-    for (const auto& key : keys) {
-        EXPECT_FALSE(svc->GetReplicaList(key, TenantId::Default()).has_value());
-        EXPECT_TRUE(svc->GetReplicaList(key, tenant_a).has_value());
-        EXPECT_TRUE(svc->GetReplicaList(key, tenant_b).has_value());
+    // Create `kNumKeys` keys
+    for (int i = 0; i < kNumKeys; ++i) {
+        std::string key =
+            GenerateKeyForSegment(client_id, service_, segment_name);
+        keys.push_back(key);
     }
 
-    const std::string revoke_key = "tenant_batch_upsert_revoke_key";
-    auto revoke_start =
-        svc->UpsertStart(client_id, revoke_key, tenant_a, 1024, config);
-    ASSERT_TRUE(revoke_start.has_value());
-    ASSERT_TRUE(
-        svc->UpsertRevoke(client_id, revoke_key, tenant_a, ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_FALSE(svc->GetReplicaList(revoke_key, tenant_a).has_value());
-}
-
-TEST_F(MasterServiceTest, TenantBatchRemoveAndRemoveAllAreScoped) {
-    const std::string shared_key = "tenant_batch_remove_shared_key";
-    const TenantId tenant_a("tenant_batch_remove_a");
-    const TenantId tenant_b("tenant_batch_remove_b");
-    auto svc = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*svc);
-    const UUID client_id = generate_uuid();
+    auto create_end = std::chrono::steady_clock::now();
 
-    ReplicateConfig config;
-    config.replica_num = 1;
+    // Execute unmount operation and record operation time
+    auto unmount_start = std::chrono::steady_clock::now();
+    auto unmount_result = service_->UnmountSegment(segment.id, client_id);
+    EXPECT_TRUE(unmount_result.has_value());
+    auto unmount_end = std::chrono::steady_clock::now();
 
-    ASSERT_TRUE(
-        svc->PutStart(client_id, shared_key, TenantId::Default(), 1024, config)
-            .has_value());
-    ASSERT_TRUE(svc->PutEnd(client_id, shared_key, TenantId::Default(),
-                            ReplicaType::MEMORY)
-                    .has_value());
-    ASSERT_TRUE(svc->PutStart(client_id, shared_key, tenant_a, 1024, config)
-                    .has_value());
-    ASSERT_TRUE(
-        svc->PutEnd(client_id, shared_key, tenant_a, ReplicaType::MEMORY)
-            .has_value());
-    ASSERT_TRUE(svc->PutStart(client_id, shared_key, tenant_b, 1024, config)
-                    .has_value());
-    ASSERT_TRUE(
-        svc->PutEnd(client_id, shared_key, tenant_b, ReplicaType::MEMORY)
-            .has_value());
+    auto unmount_duration =
+        std::chrono::duration_cast<std::chrono::milliseconds>(unmount_end -
+                                                              unmount_start);
 
-    auto remove_a = svc->BatchRemove({shared_key}, tenant_a, /*force=*/true);
-    ASSERT_EQ(remove_a.size(), 1u);
-    ASSERT_TRUE(remove_a[0].has_value());
-    EXPECT_FALSE(svc->GetReplicaList(shared_key, tenant_a).has_value());
-    EXPECT_TRUE(
-        svc->GetReplicaList(shared_key, TenantId::Default()).has_value());
-    EXPECT_TRUE(svc->GetReplicaList(shared_key, tenant_b).has_value());
+    // Unmount operation should be very fast, so we set 1s limit
+    EXPECT_LE(unmount_duration.count(), 1000)
+        << "Unmount operation took " << unmount_duration.count()
+        << "ms which exceeds 1 second limit";
 
-    EXPECT_EQ(svc->RemoveAll(tenant_b, /*force=*/true), 1);
-    EXPECT_FALSE(svc->GetReplicaList(shared_key, tenant_b).has_value());
-    EXPECT_TRUE(
-        svc->GetReplicaList(shared_key, TenantId::Default()).has_value());
+    // Verify all keys are gone
+    for (const auto& key : keys) {
+        auto get_result = service_->GetReplicaList(key, TenantId::Default());
+        EXPECT_FALSE(get_result.has_value());
+        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
+    }
 
-    EXPECT_EQ(svc->RemoveAll(/*force=*/true), 1);
-    EXPECT_FALSE(
-        svc->GetReplicaList(shared_key, TenantId::Default()).has_value());
+    // Output performance report
+    auto total_create_duration =
+        std::chrono::duration_cast<std::chrono::milliseconds>(create_end -
+                                                              start);
+    std::cout << "\nPerformance Metrics:\n"
+              << "Keys created: " << kNumKeys << "\n"
+              << "Creation time: " << total_create_duration.count() << "ms\n"
+              << "Unmount time: " << unmount_duration.count() << "ms\n";
 }
 
-TEST_F(MasterServiceTest, LegacyRemoveAllRemovesAllTenants) {
-    const std::string key = "legacy_remove_all_shared_key";
-    const TenantId tenant_a("legacy_remove_all_a");
-    const TenantId tenant_b("legacy_remove_all_b");
-    auto svc = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({std::string(TenantId::kDefaultValue),
-                                tenant_a.value(), tenant_b.value()}));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*svc);
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, ShrinkBucketsIfSparseThresholds) {
+    // Small containers stay untouched regardless of sparsity: their bucket
+    // memory is negligible and rehash churn is not worth it.
+    std::unordered_map<std::string, int> small;
+    small.emplace("small_key", 0);
+    const size_t small_buckets = small.bucket_count();
+    ASSERT_LE(small_buckets, kShrinkMinBucketCount);
+    ShrinkBucketsIfSparse(small);
+    EXPECT_EQ(small.bucket_count(), small_buckets);
 
-    ReplicateConfig config;
-    config.replica_num = 1;
+    // Grow a map well past the bucket floor, then erase most entries: the
+    // bucket array keeps its high-water size until explicitly shrunk.
+    std::unordered_map<std::string, int> map;
+    for (size_t i = 0; i < 4 * kShrinkMinBucketCount; ++i) {
+        map.emplace("key" + std::to_string(i), 0);
+    }
+    const size_t high_water = map.bucket_count();
+    ASSERT_GT(high_water, kShrinkMinBucketCount);
 
-    ASSERT_TRUE(svc->PutStart(client_id, key, TenantId::Default(), 1024, config)
-                    .has_value());
-    ASSERT_TRUE(
-        svc->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    ASSERT_TRUE(
-        svc->PutStart(client_id, key, tenant_a, 1024, config).has_value());
-    ASSERT_TRUE(
-        svc->PutEnd(client_id, key, tenant_a, ReplicaType::MEMORY).has_value());
-    ASSERT_TRUE(
-        svc->PutStart(client_id, key, tenant_b, 1024, config).has_value());
-    ASSERT_TRUE(
-        svc->PutEnd(client_id, key, tenant_b, ReplicaType::MEMORY).has_value());
+    // At exactly a quarter full there is nothing to shrink yet.
+    while (map.size() > high_water / 4) {
+        map.erase(map.begin());
+    }
+    ShrinkBucketsIfSparse(map);
+    EXPECT_EQ(map.bucket_count(), high_water);
 
-    EXPECT_EQ(svc->RemoveAll(/*force=*/true), 3);
-    EXPECT_FALSE(svc->GetReplicaList(key, TenantId::Default()).has_value());
-    EXPECT_FALSE(svc->GetReplicaList(key, tenant_a).has_value());
-    EXPECT_FALSE(svc->GetReplicaList(key, tenant_b).has_value());
-    EXPECT_EQ(svc->RemoveAll(/*force=*/true), 0);
+    // One more erase crosses the threshold and triggers the shrink.
+    map.erase(map.begin());
+    ShrinkBucketsIfSparse(map);
+    EXPECT_LT(map.bucket_count(), high_water);
+    EXPECT_GE(map.bucket_count(), map.size());
 }
 
-TEST_F(MasterServiceTest, PutWithPreferredSegment) {
-    // For backward compatibility, test the deprecated single preferred_segment
-    std::unique_ptr<MasterService> service_(new MasterService());
+TEST_F(MasterServiceTest, BatchEvictShrinksSparseMetadataMaps) {
+    // Zero lease TTL so every committed object is immediately evictable.
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
     const UUID client_id = generate_uuid();
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t object_size = 1024;
+    constexpr size_t object_count = 2 * kShrinkMinBucketCount;
+    // Size the segment with ample headroom so the background eviction
+    // thread never fires; only the explicit call below evicts.
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(
+        *service_, "test_segment", buffer, object_size * object_count * 16);
 
-    // Mount 3 segments, each 16MB
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    for (int i = 0; i < 3; ++i) {
-        [[maybe_unused]] const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
+    // Pick keys that all hash to one shard so its metadata map grows past
+    // the shrink floor; random keys would spread these objects thinly
+    // across all 1024 shards.
+    const size_t target_shard = MetadataShardIndex(*service_, "shrink_key_0");
+    std::vector<std::string> keys;
+    for (size_t i = 0; keys.size() < object_count; ++i) {
+        std::string key = "shrink_key_" + std::to_string(i);
+        if (MetadataShardIndex(*service_, key) != target_shard) continue;
+        keys.push_back(std::move(key));
     }
 
-    // Prepare preferred segments
-    std::string preferred_segment = "segment_1";
-
-    // Test PutStart with multiple preferred segments
-    std::string key = "test_key";
-    uint64_t value_length = 1024;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.preferred_segment = preferred_segment;
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(1, replica_list.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[0].status);
-    const auto& mem_desc = replica_list[0].get_memory_descriptor();
-    EXPECT_EQ(preferred_segment,
-              mem_desc.buffer_descriptor.transport_endpoint_);
+    for (const auto& key : keys) {
+        // Hard-pin the first object: it is excluded from eviction, so the
+        // tenant (and its metadata map) deterministically survives the
+        // full eviction below and the shrunk bucket count stays
+        // observable.
+        config.with_hard_pin = (&key == &keys.front());
+        ASSERT_TRUE(service_
+                        ->PutStart(client_id, key, TenantId::Default(),
+                                   object_size, config)
+                        .has_value());
+        ASSERT_TRUE(service_
+                        ->PutEnd(client_id, key, TenantId::Default(),
+                                 ReplicaType::MEMORY)
+                        .has_value());
+    }
 
-    // Complete the Put operation
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-}
+    const size_t buckets_before = MetadataBucketCount(*service_, target_shard);
+    ASSERT_GT(buckets_before, kShrinkMinBucketCount);
+
+    MasterServiceTestPeer(*service_).RunBatchEvictForTesting(1.0, 1.0);
+
+    const size_t buckets_after = MetadataBucketCount(*service_, target_shard);
+    ASSERT_GT(buckets_after, 0u);
+    // Without the post-eviction shrink the bucket array would still sit at
+    // its high-water mark and this assertion would fail.
+    EXPECT_LT(buckets_after, buckets_before / 2);
+}
+
+TEST_F(MasterServiceTest, ClearStaleHandlesShrinksSparseMetadataMaps) {
+    // Regression for the lease-expire / client-offboarding delete path.
+    // ClearInvalidHandles -> ClearStaleHandles can erase tens of millions of
+    // keys from a shared tenant; erase() never returns bucket memory, so a
+    // tenant that loses most (but not all) of its keys would keep its
+    // high-water bucket array forever and RSS would never drop. The shrink
+    // pass at the end of ClearStaleHandles mirrors the one in BatchEvict.
+    auto service = std::make_unique<MasterService>();
+    PauseReplicaCleanup(*service);
+
+    constexpr size_t kSegmentSize = 1024 * 1024 * 128;
+    const std::string stale_segment_name = "clear_shrink_stale_segment";
+    const std::string live_segment_name = "clear_shrink_live_segment";
+    const auto stale_segment = PrepareSimpleSegment(
+        *service, stale_segment_name, 0x300000000, kSegmentSize);
+    const auto live_segment = PrepareSimpleSegment(*service, live_segment_name,
+                                                   0x400000000, kSegmentSize);
+
+    // Gather keys on one shard so its metadata map grows past the shrink
+    // floor; spreading them across all 1024 shards would leave each map tiny.
+    const size_t target_shard =
+        MetadataShardIndex(*service, "clear_shrink_key_0");
+    // A few live keys keep the shared tenant alive after the sweep (partial
+    // drain, not full erase); the rest are swept and must trigger a shrink.
+    constexpr size_t kLiveKeys = 128;
+    constexpr size_t kTotalKeys = 2 * kShrinkMinBucketCount;
+
+    std::vector<std::string> stale_keys;
+    std::vector<std::string> live_keys;
+    for (size_t i = 0; stale_keys.size() + live_keys.size() < kTotalKeys; ++i) {
+        ASSERT_LT(i, 5000000u)
+            << "could not gather enough keys on shard " << target_shard;
+        const std::string key = "clear_shrink_key_" + std::to_string(i);
+        if (MetadataShardIndex(*service, key) != target_shard) {
+            continue;
+        }
 
-TEST_F(MasterServiceTest, PutWithPreferredSegments) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
+        const bool on_live = live_keys.size() < kLiveKeys;
+        const UUID& client_id =
+            on_live ? live_segment.client_id : stale_segment.client_id;
+        const std::string& segment_name =
+            on_live ? live_segment_name : stale_segment_name;
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.preferred_segments = {segment_name};
 
-    // Mount 3 segments, each 16MB
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    for (int i = 0; i < 3; ++i) {
-        [[maybe_unused]] const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
+        ASSERT_TRUE(
+            service->PutStart(client_id, key, TenantId::Default(), 1024, config)
+                .has_value())
+            << "key=" << key;
+        ASSERT_TRUE(service
+                        ->PutEnd(client_id, key, TenantId::Default(),
+                                 ReplicaType::MEMORY)
+                        .has_value())
+            << "key=" << key;
+        (on_live ? live_keys : stale_keys).push_back(key);
     }
+    ASSERT_GT(stale_keys.size(), live_keys.size());
 
-    // Prepare preferred segments
-    std::vector<std::string> preferred_segments = {"segment_0", "segment_1"};
+    const size_t buckets_before = MetadataBucketCount(*service, target_shard);
+    ASSERT_GT(buckets_before, kShrinkMinBucketCount);
 
-    // Test PutStart with multiple preferred segments
-    std::string key = "test_key";
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 2;
-    config.preferred_segments = preferred_segments;
+    // Unmount the stale segment, then sweep inline. The tenant survives
+    // because the live segment still holds keys, so the metadata map is only
+    // partially drained — exactly the case that leaks bucket memory without
+    // the shrink.
+    ASSERT_TRUE(
+        service
+            ->UnmountSegment(stale_segment.segment_id, stale_segment.client_id)
+            .has_value());
+    ClearInvalidHandlesForTest(*service);
 
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(2, replica_list.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[0].status);
-    EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[1].status);
-    const auto& mem_desc1 = replica_list[0].get_memory_descriptor();
-    const auto& mem_desc2 = replica_list[1].get_memory_descriptor();
-    std::unordered_set<std::string> used_segments = {
-        mem_desc1.buffer_descriptor.transport_endpoint_,
-        mem_desc2.buffer_descriptor.transport_endpoint_};
-    EXPECT_TRUE(used_segments.find("segment_0") != used_segments.end());
-    EXPECT_TRUE(used_segments.find("segment_1") != used_segments.end());
-
-    // Complete the Put operation
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-}
+    // GetKeyCount counts physical metadata, so it distinguishes "swept" from
+    // "merely hidden by the unmount".
+    EXPECT_EQ(live_keys.size(), service->GetKeyCount());
 
-TEST_F(MasterServiceTest,
-       ResolveMooncakeHostIdUsesLocalHostnameAndRejectsLoopback) {
-    {
-        EXPECT_EQ(ResolveMooncakeHostId("hostB:5000"), "hostB");
-        EXPECT_EQ(ResolveMooncakeHostId("hostB:5001"), "hostB");
-        EXPECT_EQ(ResolveMooncakeHostId("[2001:db8::1]:5000"), "2001:db8::1");
-        EXPECT_TRUE(ResolveMooncakeHostId("localhost:5000").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("127.0.0.1:5000").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("0.0.0.0:5000").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("::1").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("[::1]:5000").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("::").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("[::]").empty());
-        EXPECT_TRUE(ResolveMooncakeHostId("[::]:5000").empty());
+    const size_t buckets_after = MetadataBucketCount(*service, target_shard);
+    ASSERT_GT(buckets_after, 0u);
+    // Without the post-sweep shrink the bucket array would stay at its
+    // high-water mark and this assertion would fail.
+    EXPECT_LT(buckets_after, buckets_before / 2);
+    // The shrunk map must still be large enough to hold every live key.
+    EXPECT_GE(buckets_after, live_keys.size());
+
+    for (const auto& key : live_keys) {
+        auto get_result = service->GetReplicaList(key, TenantId::Default());
+        ASSERT_TRUE(get_result.has_value()) << "key=" << key << " was swept";
+        ASSERT_EQ(1u, get_result->replicas.size()) << "key=" << key;
+    }
+    for (const auto& key : stale_keys) {
+        auto get_result = service->GetReplicaList(key, TenantId::Default());
+        ASSERT_FALSE(get_result.has_value()) << "key=" << key;
+        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error())
+            << "key=" << key;
     }
 }
 
-TEST_F(MasterServiceTest, MasterConfigParsesLocalFirstStrategy) {
-    MasterConfig config{};
-    config.allocation_strategy = "local_first";
-
-    WrappedMasterServiceConfig wrapped_config(config, 0);
-    MasterServiceConfig service_config(wrapped_config);
-    EXPECT_EQ(service_config.allocation_strategy_type,
-              AllocationStrategyType::LOCAL_FIRST);
-}
-
-TEST_F(MasterServiceTest, LocalFirstPutPrefersWriterHost) {
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
-            .build();
-    MasterService service(service_config);
-    const UUID writer_client_id = generate_uuid();
-
-    [[maybe_unused]] const auto host0 = PrepareSimpleSegment(
-        service, "segment_host0", 0x300000000, kDefaultSegmentSize, "host0");
-    [[maybe_unused]] const auto host1 = PrepareSimpleSegment(
-        service, "segment_host1", 0x400000000, kDefaultSegmentSize, "host1");
+TEST_F(MasterServiceTest, RemoveSoftPinObject) {
+    const uint64_t kv_lease_ttl = 200;
+    // set a large soft_pin_ttl so the granted soft pin will not quickly expire
+    const uint64_t kv_soft_pin_ttl = 10000;
+    const bool allow_evict_soft_pinned_objects = true;
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
+                              .set_allow_evict_soft_pinned_objects(
+                                  allow_evict_soft_pinned_objects)
+                              .build();
+    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    const UUID client_id = generate_uuid();
+    // Mount segment and put an object
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t size = 1024 * 1024 * 16;
+    [[maybe_unused]] const auto context =
+        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
 
+    std::string key = "test_key";
+    uint64_t slice_length = 1024;
     ReplicateConfig config;
     config.replica_num = 1;
-    config.host_id = "host1";
+    config.soft_pin_action = SoftPinAction::ENABLE;
 
-    auto put_start = service.PutStart(writer_client_id, "local_first_key",
-                                      TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start.has_value());
-    ASSERT_EQ(put_start->size(), 1u);
-    EXPECT_EQ((*put_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host1");
+    // Verify soft pin does not block remove
+    ASSERT_TRUE(service_
+                    ->PutStart(client_id, key, TenantId::Default(),
+                               slice_length, config)
+                    .has_value());
+    ASSERT_TRUE(
+        service_
+            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
+            .has_value());
+    EXPECT_EQ(SoftPinRegistrationCount(*service_), 1u);
+    EXPECT_TRUE(service_->Remove(key, TenantId::Default()).has_value());
+    EXPECT_EQ(SoftPinRegistrationCount(*service_), 0u);
+
+    // Verify soft pin does not block RemoveAll
+    ASSERT_TRUE(service_
+                    ->PutStart(client_id, key, TenantId::Default(),
+                               slice_length, config)
+                    .has_value());
+    ASSERT_TRUE(
+        service_
+            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
+            .has_value());
+    EXPECT_EQ(SoftPinRegistrationCount(*service_), 1u);
+    EXPECT_EQ(1, service_->RemoveAll());
+    EXPECT_EQ(SoftPinRegistrationCount(*service_), 0u);
 }
 
-TEST_F(MasterServiceTest, LocalFirstPutFallsBackToNextOrderedHost) {
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
-            .build();
-    MasterService service(service_config);
-    const UUID writer_client_id = generate_uuid();
+TEST_F(MasterServiceTest, SoftPinActionsCommitOnFirstReadableUpsert) {
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_soft_pin_ttl(10000)
+                              .build();
+    std::unique_ptr<MasterService> service(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
+    const UUID client_id = generate_uuid();
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
 
-    [[maybe_unused]] const auto host0 = PrepareSimpleSegment(
-        service, "segment_host0", 0x300000000, kDefaultSegmentSize, "host0");
-    [[maybe_unused]] const auto host2 = PrepareSimpleSegment(
-        service, "segment_host2", 0x400000000, kDefaultSegmentSize, "host2");
+    ReplicateConfig enable;
+    enable.soft_pin_action = SoftPinAction::ENABLE;
+    enable.soft_pin_ttl_ms = 5000;
+    ASSERT_TRUE(service
+                    ->PutStart(client_id, "action_key", TenantId::Default(),
+                               1024, enable)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+    const auto before_first_completion = std::chrono::system_clock::now();
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "action_key", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    const auto initial_deadline = GetSoftPinDeadline(*service, "action_key");
+    ASSERT_TRUE(initial_deadline.has_value());
+    EXPECT_GT(*initial_deadline,
+              before_first_completion + std::chrono::seconds(4));
+    EXPECT_LT(*initial_deadline,
+              before_first_completion + std::chrono::seconds(9));
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+
+    ReplicateConfig preserve;
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_id, "action_key", TenantId::Default(),
+                                  1024, preserve)
+                    .has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "action_key"), initial_deadline);
+    ASSERT_TRUE(service
+                    ->UpsertEnd(client_id, "action_key", TenantId::Default(),
+                                ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "action_key"), initial_deadline);
 
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.host_id = "host1";
+    ReplicateConfig disable;
+    disable.soft_pin_action = SoftPinAction::DISABLE;
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_id, "action_key", TenantId::Default(),
+                                  2048, disable)
+                    .has_value());
+    EXPECT_TRUE(GetSoftPinDeadline(*service, "action_key").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+    ASSERT_TRUE(service
+                    ->UpsertEnd(client_id, "action_key", TenantId::Default(),
+                                ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "action_key").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 
-    auto put_start = service.PutStart(writer_client_id, "ordered_fallback_key",
-                                      TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start.has_value());
-    ASSERT_EQ(put_start->size(), 1u);
-    EXPECT_EQ((*put_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host2");
+    ReplicateConfig enable_again;
+    enable_again.soft_pin_action = SoftPinAction::ENABLE;
+    enable_again.soft_pin_ttl_ms = 3000;
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_id, "action_key", TenantId::Default(),
+                                  2048, enable_again)
+                    .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "action_key").has_value());
+    const auto before_enable_again = std::chrono::system_clock::now();
+    ASSERT_TRUE(service
+                    ->UpsertEnd(client_id, "action_key", TenantId::Default(),
+                                ReplicaType::MEMORY)
+                    .has_value());
+    const auto enabled_again_deadline =
+        GetSoftPinDeadline(*service, "action_key");
+    ASSERT_TRUE(enabled_again_deadline.has_value());
+    EXPECT_GT(*enabled_again_deadline,
+              before_enable_again + std::chrono::seconds(2));
+    EXPECT_LT(*enabled_again_deadline,
+              before_enable_again + std::chrono::seconds(5));
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+}
+
+TEST_F(MasterServiceTest, SoftPinDeadlineIndexExpiresOnlyDueEntries) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
+    const UUID client_id = generate_uuid();
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
+
+    ReplicateConfig config;
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    PutCompletedObject(*service, client_id, "deadline_key", config);
+
+    ReplicateConfig grouped_config = config;
+    grouped_config.group_ids = std::vector<std::string>{
+        FindGroupIdOnDifferentShard("grouped_deadline_key")};
+    PutCompletedObject(*service, client_id, "grouped_deadline_key",
+                       grouped_config);
+
+    const auto first_deadline =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    const auto second_deadline = first_deadline + std::chrono::seconds(1);
+    SetSoftPinDeadlineForTest(*service, "deadline_key", first_deadline);
+    SetSoftPinDeadlineForTest(*service, "grouped_deadline_key",
+                              second_deadline);
+
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 2u);
+    CleanupExpiredSoftPinsAt(*service, first_deadline);
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "deadline_key").has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "grouped_deadline_key"),
+              second_deadline);
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 1u);
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+
+    CleanupExpiredSoftPinsAt(*service, second_deadline);
+    EXPECT_FALSE(
+        GetSoftPinDeadline(*service, "grouped_deadline_key").has_value());
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 0u);
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 }
 
-TEST_F(MasterServiceTest, LocalFirstPutFallsBackWhenLocalSegmentIsFull) {
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
-            .build();
-    MasterService service(service_config);
-    const UUID writer_client_id = generate_uuid();
+TEST_F(MasterServiceTest, SoftPinTtlUpdateInvalidatesOldHeapEntry) {
+    auto service_config = MasterServiceConfig::builder()
+                              .set_default_kv_soft_pin_ttl(5000)
+                              .build();
+    std::unique_ptr<MasterService> service(new MasterService(service_config));
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
+    const UUID client_id = generate_uuid();
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
 
-    [[maybe_unused]] const auto local = PrepareSimpleSegment(
-        service, "segment_host1", 0x300000000, 1024, "host1");
-    [[maybe_unused]] const auto remote = PrepareSimpleSegment(
-        service, "segment_host2", 0x400000000, kDefaultSegmentSize, "host2");
+    ReplicateConfig enable;
+    enable.soft_pin_action = SoftPinAction::ENABLE;
+    PutCompletedObject(*service, client_id, "ttl_update_key", enable);
+    const auto first_deadline = GetSoftPinDeadline(*service, "ttl_update_key");
+    ASSERT_TRUE(first_deadline.has_value());
 
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.host_id = "host1";
+    enable.soft_pin_ttl_ms = 20000;
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_id, "ttl_update_key",
+                                  TenantId::Default(), 1024, enable)
+                    .has_value());
+    ASSERT_TRUE(service
+                    ->UpsertEnd(client_id, "ttl_update_key",
+                                TenantId::Default(), ReplicaType::MEMORY)
+                    .has_value());
+    const auto updated_deadline =
+        GetSoftPinDeadline(*service, "ttl_update_key");
+    ASSERT_TRUE(updated_deadline.has_value());
+    EXPECT_GT(*updated_deadline, *first_deadline);
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 1u);
+    EXPECT_GE(SoftPinDeadlineHeapSize(*service), 2u);
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+
+    CleanupExpiredSoftPinsAt(*service, *first_deadline);
+    EXPECT_EQ(GetSoftPinDeadline(*service, "ttl_update_key"), updated_deadline);
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+
+    CleanupExpiredSoftPinsAt(*service, *updated_deadline);
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "ttl_update_key").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+}
 
-    auto fill_start = service.PutStart(writer_client_id, "fill_local_segment",
-                                       TenantId::Default(), 1024, config);
-    ASSERT_TRUE(fill_start.has_value());
-    ASSERT_EQ(fill_start->size(), 1u);
-    EXPECT_EQ((*fill_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host1");
+TEST_F(MasterServiceTest,
+       SizeChangingUpsertIndexesInheritedDeadlineBeforeCompletion) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
+    const UUID client_id = generate_uuid();
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
+
+    ReplicateConfig enable;
+    enable.soft_pin_action = SoftPinAction::ENABLE;
+    PutCompletedObject(*service, client_id, "resize_pending", enable);
+    const auto inherited_deadline =
+        std::chrono::system_clock::now() + std::chrono::hours(1);
+    SetSoftPinDeadlineForTest(*service, "resize_pending", inherited_deadline);
+
+    ReplicateConfig preserve;
     ASSERT_TRUE(service
-                    .PutEnd(writer_client_id, "fill_local_segment",
-                            TenantId::Default(), ReplicaType::MEMORY)
+                    ->UpsertStart(client_id, "resize_pending",
+                                  TenantId::Default(), 2048, preserve)
                     .has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "resize_pending"),
+              inherited_deadline);
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 1u);
 
-    auto fallback_start =
-        service.PutStart(writer_client_id, "fallback_after_local_full",
-                         TenantId::Default(), 1, config);
-    ASSERT_TRUE(fallback_start.has_value());
-    ASSERT_EQ(fallback_start->size(), 1u);
-    EXPECT_EQ((*fallback_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host2");
-}
+    CleanupExpiredSoftPinsAt(*service, inherited_deadline);
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "resize_pending").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 
-TEST_F(MasterServiceTest, ExplicitPreferredSegmentOverridesLocalFirst) {
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
-            .build();
-    MasterService service(service_config);
-    const UUID writer_client_id = generate_uuid();
+    ASSERT_TRUE(service
+                    ->UpsertEnd(client_id, "resize_pending",
+                                TenantId::Default(), ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "resize_pending").has_value());
+    EXPECT_EQ(SoftPinRegistrationCount(*service), 0u);
+}
 
-    [[maybe_unused]] const auto host0 = PrepareSimpleSegment(
-        service, "segment_host0", 0x300000000, kDefaultSegmentSize, "host0");
-    [[maybe_unused]] const auto host1 = PrepareSimpleSegment(
-        service, "segment_host1", 0x400000000, kDefaultSegmentSize, "host1");
+TEST_F(MasterServiceTest, SoftPinDeadlineHeapCompactsRepeatedUpdates) {
+    MasterService service;
+    const auto base = std::chrono::system_clock::now();
+    constexpr size_t kUpdates = 5000;
+    for (size_t i = 0; i < kUpdates; ++i) {
+        UpsertSoftPinDeadlineIndexForTest(
+            service, "compaction_key", 0,
+            base + std::chrono::milliseconds(i + 1));
+    }
 
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.host_id = "host1";
-    config.preferred_segment = "segment_host0";
-
-    auto put_start =
-        service.PutStart(writer_client_id, "explicit_preferred_key",
-                         TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start.has_value());
-    ASSERT_EQ(put_start->size(), 1u);
-    EXPECT_EQ((*put_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host0");
+    EXPECT_EQ(SoftPinRegistrationCount(service), 1u);
+    EXPECT_LE(SoftPinDeadlineHeapSize(service), 4096u);
+    EXPECT_EQ(PopExpiredSoftPinDeadlinesForTest(
+                  service, base + std::chrono::milliseconds(kUpdates - 1)),
+              0u);
+    EXPECT_EQ(SoftPinRegistrationCount(service), 1u);
+    EXPECT_EQ(PopExpiredSoftPinDeadlinesForTest(
+                  service, base + std::chrono::milliseconds(kUpdates)),
+              1u);
 }
 
-TEST_F(MasterServiceTest, ExplicitPreferredSegmentFallsBackToLocalFirst) {
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_allocation_strategy_type(AllocationStrategyType::LOCAL_FIRST)
-            .build();
-    MasterService service(service_config);
-    const UUID writer_client_id = generate_uuid();
+TEST_F(MasterServiceTest,
+       ExpiredSoftPinIsNotCarriedAcrossUpsertMetadataReplacement) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
+    const UUID client_a = generate_uuid();
+    const UUID client_b = generate_uuid();
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
 
-    [[maybe_unused]] const auto preferred = PrepareSimpleSegment(
-        service, "segment_host0", 0x300000000, 1024, "host0");
-    [[maybe_unused]] const auto local = PrepareSimpleSegment(
-        service, "segment_host1", 0x400000000, kDefaultSegmentSize, "host1");
+    ReplicateConfig enable;
+    enable.soft_pin_action = SoftPinAction::ENABLE;
+    enable.soft_pin_ttl_ms = 10000;
+    ReplicateConfig preserve;
 
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.host_id = "host1";
-    config.preferred_segment = "segment_host0";
-
-    auto fill_start = service.PutStart(writer_client_id, "fill_preferred",
-                                       TenantId::Default(), 1024, config);
-    ASSERT_TRUE(fill_start.has_value());
-    ASSERT_EQ(fill_start->size(), 1u);
-    EXPECT_EQ((*fill_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host0");
+    ASSERT_TRUE(
+        service
+            ->PutStart(client_a, "preempted", TenantId::Default(), 1024, enable)
+            .has_value());
+    ASSERT_TRUE(service
+                    ->PutEnd(client_a, "preempted", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    SetSoftPinDeadlineForTest(
+        *service, "preempted",
+        std::chrono::system_clock::now() - std::chrono::seconds(1));
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_a, "preempted", TenantId::Default(),
+                                  1024, preserve)
+                    .has_value());
     ASSERT_TRUE(service
-                    .PutEnd(writer_client_id, "fill_preferred",
-                            TenantId::Default(), ReplicaType::MEMORY)
+                    ->UpsertStart(client_b, "preempted", TenantId::Default(),
+                                  1024, preserve)
                     .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "preempted").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 
-    auto fallback_start =
-        service.PutStart(writer_client_id, "fallback_after_preferred_full",
-                         TenantId::Default(), 1, config);
-    ASSERT_TRUE(fallback_start.has_value());
-    ASSERT_EQ(fallback_start->size(), 1u);
-    EXPECT_EQ((*fallback_start)[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_host1");
+    ASSERT_TRUE(
+        service
+            ->PutStart(client_a, "resized", TenantId::Default(), 1024, enable)
+            .has_value());
+    ASSERT_TRUE(service
+                    ->PutEnd(client_a, "resized", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    SetSoftPinDeadlineForTest(
+        *service, "resized",
+        std::chrono::system_clock::now() - std::chrono::seconds(1));
+    ASSERT_TRUE(service
+                    ->UpsertStart(client_a, "resized", TenantId::Default(),
+                                  2048, preserve)
+                    .has_value());
+    EXPECT_FALSE(GetSoftPinDeadline(*service, "resized").has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
 }
 
-TEST_F(MasterServiceTest, RandomPutStartEndFlow) {
-    std::unique_ptr<MasterService> service_(new MasterService());
+TEST_F(MasterServiceTest, RepeatedPutEndDoesNotRefreshSoftPin) {
+    std::unique_ptr<MasterService> service(new MasterService());
+    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service);
     const UUID client_id = generate_uuid();
 
-    // Mount 5 segments, each 16MB
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    for (int i = 0; i < 5; ++i) {
-        [[maybe_unused]] const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-    }
-
-    // Test PutStart
-    std::string key = "test_key";
-    uint64_t value_length = 1024;
     ReplicateConfig config;
-    std::random_device rd;
-    std::mt19937 gen(rd());
-    std::uniform_int_distribution<> dis(1, 5);
-    int random_number = dis(gen);
-    config.replica_num = random_number;
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_FALSE(replica_list.empty());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[0].status);
-    // During put, Get/Remove should fail
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-    auto remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, remove_result.error());
-    // Test PutEnd
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-    // Verify replica list after PutEnd
-    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result2.has_value());
-    replica_list = get_result2.value().replicas;
-    EXPECT_EQ(random_number, replica_list.size());
-    for (int i = 0; i < random_number; ++i) {
-        EXPECT_EQ(ReplicaStatus::COMPLETE, replica_list[i].status);
-    }
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    config.soft_pin_ttl_ms = 5000;
+    ASSERT_TRUE(service
+                    ->PutStart(client_id, "repeat_end", TenantId::Default(),
+                               1024, config)
+                    .has_value());
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "repeat_end", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    const auto first_deadline = GetSoftPinDeadline(*service, "repeat_end");
+    ASSERT_TRUE(first_deadline.has_value());
+
+    ASSERT_TRUE(service
+                    ->PutEnd(client_id, "repeat_end", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(GetSoftPinDeadline(*service, "repeat_end"), first_deadline);
 }
 
-TEST_F(MasterServiceTest, GetReplicaListByRegex) {
-    const uint64_t kv_lease_ttl = 50;
+TEST_F(MasterServiceTest, SoftPinExpiresAndGetDoesNotReactivate) {
+    const uint64_t kv_lease_ttl = 200;
+    const uint64_t kv_soft_pin_ttl = 20;
     auto service_config = MasterServiceConfig::builder()
                               .set_default_kv_lease_ttl(kv_lease_ttl)
+                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
                               .build();
     std::unique_ptr<MasterService> service_(new MasterService(service_config));
     const UUID client_id = generate_uuid();
-    // Test getting non-existent key
-    auto get_result =
-        service_->GetReplicaList(".*non_existent.*", TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
 
-    int times = 10;
-    while (times--) {
-        std::string key = "test_key" + std::to_string(times);
-        uint64_t value_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), value_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-    }
-    // wait for all the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-
-    // Test getting existing key
-    auto get_result2 =
-        service_->GetReplicaListByRegex("^test_key", TenantId::Default());
-    EXPECT_TRUE(get_result2.has_value());
-    auto replica_list_local = get_result2.value();
-    EXPECT_EQ(10, replica_list_local.size());
-}
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t segment_size = 1024 * 1024 * 16;
+    constexpr size_t value_size = 1024;
+    [[maybe_unused]] const auto context =
+        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
 
-// Helper function to put an object, making the test cleaner
-void put_object(MasterService& service, const UUID& client_id,
-                const std::string& key) {
-    uint64_t value_length = 1024;
+    const int64_t baseline =
+        MasterMetricManager::instance().get_soft_pin_key_count();
     ReplicateConfig config;
-    config.replica_num = 1;
-    auto put_start_result = service.PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value())
-        << "Failed to PutStart for key: " << key;
-    auto put_end_result = service.PutEnd(client_id, key, TenantId::Default(),
-                                         ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value())
-        << "Failed to PutEnd for key: " << key;
-    auto exist_result = service.ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value())
-        << "Key does not exist after put: " << key;
+    config.soft_pin_action = SoftPinAction::ENABLE;
+    ASSERT_TRUE(service_
+                    ->PutStart(client_id, "pin_key", TenantId::Default(),
+                               value_size, config)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+    ASSERT_TRUE(service_
+                    ->PutEnd(client_id, "pin_key", TenantId::Default(),
+                             ReplicaType::MEMORY)
+                    .has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline + 1);
+
+    const auto deadline = GetSoftPinDeadline(*service_, "pin_key");
+    ASSERT_TRUE(deadline.has_value());
+    CleanupExpiredSoftPinsAt(*service_, *deadline);
+    ASSERT_TRUE(
+        service_->GetReplicaList("pin_key", TenantId::Default()).has_value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+
+    ASSERT_TRUE(service_->ExistKey("pin_key", TenantId::Default()).value());
+    EXPECT_EQ(MasterMetricManager::instance().get_soft_pin_key_count(),
+              baseline);
+    service_->RemoveAll();
 }
 
-TEST_F(MasterServiceTest, GetReplicaListByRegexComplex) {
-    const uint64_t kv_lease_ttl = 100;
+TEST_F(MasterServiceTest, ExistKeyLeasesPinSegmentButProbeKeyDoesNot) {
+    // Set a long lease TTL so leases granted by ExistKey will not expire
+    // during the test.
+    const uint64_t kv_lease_ttl = 2000;
     auto service_config = MasterServiceConfig::builder()
                               .set_default_kv_lease_ttl(kv_lease_ttl)
                               .build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-    const UUID client_id = generate_uuid();
-
-    // 1. Mount segment
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-
-    // 2. Prepare a diverse set of keys
-    std::vector<std::string> keys_to_put = {
-        // Basic keys for prefix matching
-        "test_key_01", "test_key_02", "test_key_10",
-        // Keys with different prefixes
-        "prod_key_alpha", "prod_key_beta",
-        // Keys with numbers in the middle
-        "data_part_1_chunk_a", "data_part_2_chunk_b",
-        // Keys with special characters (if your system supports them)
-        "config/user/settings.json", "logs/app-2025-08-13.log",
-        // Keys with varying lengths
-        "short", "a_very_very_very_long_key_that_tests_length_limits",
-        // Keys that look similar but should not match certain regex
-        "test-key-extra", "another_key"};
-
-    for (const auto& key : keys_to_put) {
-        put_object(*service_, client_id, key);
-    }
+    constexpr size_t kSegmentSize = 4 * 1024 * 1024;
+    constexpr size_t kObjectSize = 2 * 1024 * 1024;
 
-    // Wait for all leases to be written to the underlying KV store.
-    // In a real system, you might not need this if PutEnd is synchronous.
-    // For this test, let's assume it's needed for consistency.
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
+    // ExistKey grants a read lease on every hit, so a scan-heavy client can
+    // pin the entire segment: eviction cannot reclaim the probed objects and
+    // new allocations fail.
+    {
+        std::unique_ptr<MasterService> service_(
+            new MasterService(service_config));
+        [[maybe_unused]] const auto context =
+            PrepareSimpleSegment(*service_, "exist_lease_segment",
+                                 kDefaultSegmentBase, kSegmentSize);
+        const UUID client_id = generate_uuid();
 
-    // 3. Run a series of regex tests
+        ReplicateConfig config;
+        config.replica_num = 1;
+        for (const auto& key : {"exist_key_a", "exist_key_b"}) {
+            PutCompletedObject(*service_, client_id, key, config, kObjectSize);
+            auto exists = service_->ExistKey(key, TenantId::Default());
+            ASSERT_TRUE(exists.has_value());
+            ASSERT_TRUE(exists.value());
+        }
 
-    // Test 3.1: Simple prefix matching
-    {
-        auto result =
-            service_->GetReplicaListByRegex("^test_key_", TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        EXPECT_EQ(result.value().size(),
-                  3);  // Matches test_key_01, test_key_02, test_key_10
+        ReplicateConfig trigger_config;
+        trigger_config.replica_num = 1;
+        auto trigger_result = service_->PutStart(
+            client_id, "trigger_exist_eviction", TenantId::Default(),
+            kObjectSize, trigger_config);
+        ASSERT_FALSE(trigger_result.has_value());
+        EXPECT_EQ(ErrorCode::NO_AVAILABLE_HANDLE, trigger_result.error());
     }
 
-    // Test 3.2: Matching with a wildcard for any number
+    // ProbeKey shares the lookup path but grants no lease, so the probed
+    // objects stay evictable and the allocation eventually succeeds by
+    // evicting them.
     {
-        auto result = service_->GetReplicaListByRegex("^test_key_\\d+$",
-                                                      TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        EXPECT_EQ(result.value().size(), 3);
-    }
+        std::unique_ptr<MasterService> service_(
+            new MasterService(service_config));
+        [[maybe_unused]] const auto context = PrepareSimpleSegment(
+            *service_, "probe_segment", kDefaultSegmentBase, kSegmentSize);
+        const UUID client_id = generate_uuid();
 
-    // Test 3.3: Matching a specific pattern with wildcards
-    {
-        // Matches "data_part_1_chunk_a" and "data_part_2_chunk_b"
-        auto result = service_->GetReplicaListByRegex("^data_part_\\d_chunk_.$",
-                                                      TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        EXPECT_EQ(result.value().size(), 2);
-    }
+        ReplicateConfig config;
+        config.replica_num = 1;
+        for (const auto& key : {"probe_key_a", "probe_key_b"}) {
+            PutCompletedObject(*service_, client_id, key, config, kObjectSize);
+            auto probed = service_->ProbeKey(key, TenantId::Default());
+            ASSERT_TRUE(probed.has_value());
+            ASSERT_TRUE(probed.value());
+        }
 
-    // Test 3.4: Matching keys containing a specific substring
-    {
-        // Matches all keys with "key" in them
-        auto result =
-            service_->GetReplicaListByRegex("key", TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        // Expected: test_key_01, test_key_02, test_key_10,
-        //           prod_key_alpha, prod_key_beta,
-        //           a_very_very_very_long_key_that_tests_length_limits,
-        //           test-key-extra, another_key
-        EXPECT_EQ(result.value().size(), 8);
-    }
+        // A missing key reports false.
+        auto missing =
+            service_->ProbeKey("probe_missing_key", TenantId::Default());
+        ASSERT_TRUE(missing.has_value());
+        EXPECT_FALSE(missing.value());
 
-    // Test 3.5: Matching based on file-like paths
-    {
-        // Match all .log files
-        auto result =
-            service_->GetReplicaListByRegex("\\.log$", TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        EXPECT_EQ(result.value().size(), 1);
-        EXPECT_EQ(result.value().begin()->first, "logs/app-2025-08-13.log");
+        ReplicateConfig trigger_config;
+        trigger_config.replica_num = 1;
+        bool allocated = false;
+        for (int i = 0; i < 40 && !allocated; ++i) {
+            auto trigger_result = service_->PutStart(
+                client_id, "trigger_probe_eviction_" + std::to_string(i),
+                TenantId::Default(), kObjectSize, trigger_config);
+            allocated = trigger_result.has_value();
+            if (!allocated) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(50));
+            }
+        }
+        EXPECT_TRUE(allocated);
     }
+}
 
-    // Test 3.6: OR condition using |
-    {
-        // Match keys starting with "prod" OR ending with "json"
-        auto result = service_->GetReplicaListByRegex("^prod|\\.json$",
-                                                      TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        // Expected: prod_key_alpha, prod_key_beta, config/user/settings.json
-        EXPECT_EQ(result.value().size(), 3);
-    }
-
-    // Test 3.7: Regex that should not match anything
-    {
-        auto result = service_->GetReplicaListByRegex("^non_existent_prefix_",
-                                                      TenantId::Default());
-        // This should succeed but return an empty map.
-        ASSERT_TRUE(result.has_value());
-        EXPECT_TRUE(result.value().empty());
-    }
-
-    // Test 3.8: Exact match regex
-    {
-        auto result =
-            service_->GetReplicaListByRegex("^short$", TenantId::Default());
-        ASSERT_TRUE(result.has_value());
-        EXPECT_EQ(result.value().size(), 1);
-        EXPECT_EQ(result.value().begin()->first, "short");
-    }
-
-    // Test 3.9: Initial test for non-existent key (as a sanity check)
-    {
-        auto get_result = service_->GetReplicaListByRegex(
-            ".*absolutely_non_existent.*", TenantId::Default());
-        // Depending on implementation, this could return an empty map or an
-        // error. Let's assume it returns an empty map for a valid regex with no
-        // matches.
-        ASSERT_TRUE(get_result.has_value());
-        EXPECT_TRUE(get_result.value().empty());
-    }
-}
-
-TEST_F(MasterServiceTest, GetReplicaList) {
+TEST_F(MasterServiceTest, BatchProbeKeyReportsPointInTimeExistence) {
     std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-    // Test getting non-existent key
-    auto get_result =
-        service_->GetReplicaList("non_existent", TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
 
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+    constexpr size_t buffer = 0x300000000;
+    constexpr size_t size = 1024 * 1024 * 16;
+    auto segment = MakeSegment("probe_batch_segment", buffer, size);
+    UUID client_id = generate_uuid();
+    ASSERT_TRUE(service_->MountSegment(segment, client_id).has_value());
 
-    std::string key = "test_key";
-    uint64_t value_length = 1024;
+    const std::string existing_key = "probe_batch_existing_key";
     ReplicateConfig config;
     config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
+    PutCompletedObject(*service_, client_id, existing_key, config);
 
-    // Test getting existing key
-    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result2.has_value());
-    auto replica_list_local = get_result2.value().replicas;
-    EXPECT_FALSE(replica_list_local.empty());
+    const std::string missing_key = "probe_batch_missing_key";
+    auto results = service_->BatchProbeKey(
+        {existing_key, missing_key, existing_key}, TenantId::Default());
+    ASSERT_EQ(3u, results.size());
+    ASSERT_TRUE(results[0].has_value());
+    EXPECT_TRUE(*results[0]);
+    ASSERT_TRUE(results[1].has_value());
+    EXPECT_FALSE(*results[1]);
+    ASSERT_TRUE(results[2].has_value());
+    EXPECT_TRUE(*results[2]);
 }
 
-TEST_F(MasterServiceTest, RemoveObject) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
+TEST_F(MasterServiceTest, WrappedBatchExistKeyUsesTenantAwareBatchPath) {
+    const TenantId tenant_id("wrapped_batch_exist_tenant");
+    auto service_config = MakeStrictWrappedConfig(
+        {std::string(TenantId::kDefaultValue), tenant_id.value()});
+    WrappedMasterService service_(service_config);
+
+    Segment segment = MakeSegment("wrapped_batch_exist_segment");
     const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service_.MountSegment(segment, client_id).has_value());
 
-    std::string key = "test_key";
-    uint64_t value_length = 1024;
     ReplicateConfig config;
     config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test removing the object
-    auto remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result.has_value());
-
-    // Verify object is removed
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-
-    // Test removing non-existent object
-    auto remove_result2 = service_->Remove("non_existent", TenantId::Default());
-    EXPECT_FALSE(remove_result2.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, remove_result2.error());
-}
-
-TEST_F(MasterServiceTest, RandomRemoveObject) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-    int times = 10;
-    std::random_device rd;
-    std::mt19937 gen(rd());
-    std::uniform_int_distribution<> dis(1, 1000);
-    while (times--) {
-        std::string key = "test_key" + std::to_string(dis(gen));
-        uint64_t value_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), value_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-
-        // Test removing the object
-        auto remove_result = service_->Remove(key, TenantId::Default());
-        EXPECT_TRUE(remove_result.has_value());
-
-        // Verify object is removed
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        EXPECT_FALSE(get_result.has_value());
-        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-    }
-}
+    const std::string tenant_key_a = "wrapped_batch_tenant_a";
+    const std::string tenant_key_b = "wrapped_batch_tenant_b";
+    const std::string default_only_key = "wrapped_batch_default_only";
+    const std::string missing_key = "wrapped_batch_missing";
 
-TEST_F(MasterServiceTest, RemoveByRegex) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-    int times = 10;
-    while (times--) {
-        std::string key = "test_key" + std::to_string(times);
-        uint64_t value_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), value_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
+    std::vector<std::string> tenant_keys = {tenant_key_a, tenant_key_b};
+    std::vector<uint64_t> tenant_sizes = {1024, 2048};
+    auto tenant_put_start = service_.BatchPutStart(
+        client_id, tenant_keys, tenant_sizes, config, tenant_id.value());
+    ASSERT_EQ(tenant_put_start.size(), tenant_keys.size());
+    for (const auto& result : tenant_put_start) {
+        ASSERT_TRUE(result.has_value()) << toString(result.error());
     }
-    // wait for all the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto res = service_->RemoveByRegex("^test_key", TenantId::Default());
-    ASSERT_TRUE(res.has_value());
-    ASSERT_EQ(10, res.value());
-    times = 10;
-    while (times--) {
-        std::string key = "test_key" + std::to_string(times);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_FALSE(exist_result.value());
+    auto tenant_put_end =
+        service_.BatchPutEnd(client_id, MakeObjectMetas(tenant_keys),
+                             ReplicaType::MEMORY, tenant_id.value());
+    ASSERT_EQ(tenant_put_end.size(), tenant_keys.size());
+    for (const auto& result : tenant_put_end) {
+        ASSERT_TRUE(result.has_value()) << toString(result.error());
     }
-}
 
-TEST_F(MasterServiceTest, CopyStart) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
+    auto default_put_start =
+        service_.PutStart(client_id, default_only_key, 1024, config);
+    ASSERT_TRUE(default_put_start.has_value());
+    ASSERT_TRUE(service_
+                    .PutEnd(client_id,
+                            ObjectMeta{default_only_key, std::nullopt},
+                            ReplicaType::MEMORY)
+                    .has_value());
 
-    // Mount 4 segments (segment_1, segment_2, segment_3, segment_4) with
-    // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-    [[maybe_unused]] const auto context3 =
-        PrepareSimpleSegment(*service_, "segment_3");
-    [[maybe_unused]] const auto context4 =
-        PrepareSimpleSegment(*service_, "segment_4");
+    auto& metrics = MasterMetricManager::instance();
+    const auto base_requests = metrics.get_batch_exist_key_requests();
+    const auto base_items = metrics.get_batch_exist_key_items();
+    const auto base_failures = metrics.get_batch_exist_key_failures();
+    const auto base_partial = metrics.get_batch_exist_key_partial_successes();
+    const auto base_failed_items = metrics.get_batch_exist_key_failed_items();
 
-    UUID client_id = generate_uuid();
+    std::vector<std::string> lookup_keys = {tenant_key_a, default_only_key,
+                                            missing_key, tenant_key_b};
+    auto resp = service_.BatchExistKey(lookup_keys, tenant_id.value());
+    ASSERT_EQ(resp.size(), lookup_keys.size());
+    EXPECT_TRUE(resp[0].value());
+    EXPECT_FALSE(resp[1].value());
+    EXPECT_FALSE(resp[2].value());
+    EXPECT_TRUE(resp[3].value());
 
-    // Test Case 1: CopyStart a non-existent key, should fail.
-    auto copy_result =
-        service_->CopyStart(client_id, "non_existent_key", TenantId::Default(),
-                            "segment_1", {"segment_2"});
-    EXPECT_FALSE(copy_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, copy_result.error());
+    EXPECT_EQ(base_requests + 1, metrics.get_batch_exist_key_requests());
+    EXPECT_EQ(base_items + lookup_keys.size(),
+              metrics.get_batch_exist_key_items());
+    EXPECT_EQ(base_failures, metrics.get_batch_exist_key_failures());
+    EXPECT_EQ(base_partial, metrics.get_batch_exist_key_partial_successes());
+    EXPECT_EQ(base_failed_items, metrics.get_batch_exist_key_failed_items());
+}
 
-    // PutStart an object with 1 replica and preferred_segment=segment_1 for
-    // testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
+TEST_F(MasterServiceTest, WrappedWriteBoundaryRejectsInvalidTenantIds) {
+    WrappedMasterService service(
+        MakeStrictWrappedConfig({"registered-tenant"}));
     ReplicateConfig config;
     config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
+    const UUID client_id = generate_uuid();
 
-    // Test Case 2: CopyStart to segment_2 and segment_3, should fail because
-    // the only replica is not completed.
-    copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                      "segment_1", {"segment_2", "segment_3"});
-    EXPECT_FALSE(copy_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_NOT_FOUND, copy_result.error());
+    auto empty =
+        service.PutStart(client_id, "empty-tenant-key", 1024, config, "");
+    ASSERT_FALSE(empty.has_value());
+    EXPECT_EQ(empty.error(), ErrorCode::TENANT_NOT_REGISTERED);
 
-    // PutEnd the object.
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
+    const std::string control_tenant("tenant\0bad", 10);
+    auto invalid = service.PutStart(client_id, "invalid-tenant-key", 1024,
+                                    config, control_tenant);
+    ASSERT_FALSE(invalid.has_value());
+    EXPECT_EQ(invalid.error(), ErrorCode::TENANT_NOT_REGISTERED);
+}
 
-    // Test Case 3: CopyStart to segment_2 and segment_3, should success.
-    copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                      "segment_1", {"segment_2", "segment_3"});
-    EXPECT_TRUE(copy_result.has_value());
-    auto copy_response = copy_result.value();
-    EXPECT_EQ("segment_1", copy_response.source.get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-    EXPECT_EQ(2, copy_response.targets.size());
-
-    // Test Case 4: Try remove the object, should fail because it is copying.
-    auto remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, remove_result.error());
+TEST_F(MasterServiceTest, WrappedRequestBoundaryRejectsInvalidTenantIds) {
+    WrappedMasterService service(
+        MakeStrictWrappedConfig({std::string(TenantId::kDefaultValue)}));
 
-    // Test Case 5: CopyStart to segment_4, should fail because there is an
-    // ongoing copy task.
-    copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                      "segment_1", {"segment_4"});
-    EXPECT_FALSE(copy_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_REPLICATION_TASK, copy_result.error());
+    auto invalid = service.GetReplicaList("missing-key", "_invalid-tenant");
+    ASSERT_FALSE(invalid.has_value());
+    EXPECT_EQ(invalid.error(), ErrorCode::INVALID_PARAMS);
 
-    // Test Case 6: CopyEnd, should success and the object now has 3 replicas.
-    auto copy_end_result =
-        service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_end_result.has_value());
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    EXPECT_EQ(3, get_result.value().replicas.size());
-
-    // Test Case 7: Copy from a non-existent replica to segment_3 and
-    // segment_4, should fail.
-    copy_result =
-        service_->CopyStart(client_id, key, TenantId::Default(),
-                            "non_existent_segment", {"segment_3", "segment_4"});
-    EXPECT_FALSE(copy_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_NOT_FOUND, copy_result.error());
-
-    // Test Case 8: Copy to segment_4 and a non-existent segment, should fail.
-    copy_result =
-        service_->CopyStart(client_id, key, TenantId::Default(), "segment_1",
-                            {"segment_4", "non_existent_segment"});
-    EXPECT_FALSE(copy_result.has_value());
-    EXPECT_EQ(ErrorCode::SEGMENT_NOT_FOUND, copy_result.error());
-
-    // Test Case 9: Copy to segment_3 and segment_4, should skip segment_3 and
-    // successfully copy to segment_4.
-    copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                      "segment_1", {"segment_3", "segment_4"});
-    EXPECT_TRUE(copy_result.has_value());
-    copy_response = copy_result.value();
-    EXPECT_EQ("segment_1", copy_response.source.get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-    EXPECT_EQ(1, copy_response.targets
-                     .size());  // Only 1 replica since segment_3 is skipped
-    EXPECT_EQ("segment_4", copy_response.targets[0]
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-
-    // End the copy operation to clean up state
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_end_result.has_value());
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    EXPECT_EQ(4, get_result.value().replicas.size());
-
-    // Test Case 10: Copy to segment_4 again, should skip because it's already
-    // used.
-    copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                      "segment_1", {"segment_4"});
-    EXPECT_TRUE(copy_result.has_value());
-    copy_response = copy_result.value();
-    EXPECT_EQ("segment_1", copy_response.source.get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-    EXPECT_EQ(0,
-              copy_response.targets
-                  .size());  // No replicas since segment_4 is already used
-
-    // Wait for the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
+    const std::string control_tenant("tenant\0bad", 10);
+    auto batch =
+        service.BatchGetReplicaList({"key-a", "key-b"}, control_tenant);
+    ASSERT_EQ(batch.size(), 2u);
+    for (const auto& result : batch) {
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
 
-    // Test Case 11: Try remove the object, should fail because it is copying.
-    remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_REPLICATION_TASK, remove_result.error());
+    std::vector<OffloadTaskItem> tasks = {
+        {.tenant_id = "_invalid-tenant", .key = "key", .size = 1}};
+    std::vector<StorageObjectMetadata> metadatas = {
+        {.bucket_id = 0,
+         .offset = 0,
+         .key_size = 3,
+         .data_size = 1,
+         .transport_endpoint = "segment"}};
+    auto offload =
+        service.NotifyOffloadSuccess(generate_uuid(), tasks, metadatas);
+    ASSERT_FALSE(offload.has_value());
+    EXPECT_EQ(offload.error(), ErrorCode::INVALID_PARAMS);
 
-    // Clean up the copy operation
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_end_result.has_value());
+    // RemoveAll has a legacy scalar return type and cannot carry ErrorCode.
+    EXPECT_EQ(service.RemoveAll(false, "_invalid-tenant"), 0);
+}
 
-    // Wait for the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
+TEST_F(MasterServiceTest, WrappedRequestBoundaryPreservesTenantNormalization) {
+    WrappedMasterService multi_tenant_service(
+        MakeStrictWrappedConfig({std::string(TenantId::kDefaultValue)}));
+    auto empty = multi_tenant_service.ExistKey("missing-key", "");
+    ASSERT_TRUE(empty.has_value());
+    EXPECT_FALSE(empty.value());
 
-    // Test Case 12: Try remove the object, should success.
-    remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result.has_value());
+    WrappedMasterServiceConfig single_tenant_config;
+    single_tenant_config.default_kv_lease_ttl = 100;
+    single_tenant_config.enable_metric_reporting = false;
+    single_tenant_config.enable_multi_tenants = false;
+    WrappedMasterService single_tenant_service(single_tenant_config);
+    auto invalid =
+        single_tenant_service.ExistKey("missing-key", "_invalid-tenant");
+    ASSERT_TRUE(invalid.has_value());
+    EXPECT_FALSE(invalid.value());
 }
 
-TEST_F(MasterServiceTest, CopyEnd) {
-    std::unique_ptr<MasterService> service_(new MasterService());
+TEST_F(MasterServiceTest, PutStartExpiringTest) {
+    // Reset storage space metrics.
+    MasterMetricManager::instance().reset_allocated_mem_size();
+    MasterMetricManager::instance().reset_total_mem_capacity();
 
-    // Mount 3 segments (segment_1, segment_2, segment_3) with
-    // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-    [[maybe_unused]] const auto context3 =
-        PrepareSimpleSegment(*service_, "segment_3");
+    MasterServiceConfig master_config;
+    master_config.put_start_discard_timeout_sec = 3;
+    master_config.put_start_release_timeout_sec = 5;
+    std::unique_ptr<MasterService> service_(new MasterService(master_config));
 
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
+    constexpr size_t kReplicaCnt = 3;
+    constexpr size_t kBaseAddr = 0x300000000;
+    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
 
-    // Test Case 1: CopyEnd a non-existent key, should fail.
-    auto copy_end_result =
-        service_->CopyEnd(client_id, "non_existent_key", TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, copy_end_result.error());
+    // Mount 3 segments.
+    std::vector<MountedSegmentContext> contexts;
+    contexts.reserve(kReplicaCnt);
+    for (size_t i = 0; i < kReplicaCnt; ++i) {
+        auto context = PrepareSimpleSegment(
+            *service_, "segment_" + std::to_string(i),
+            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
+        contexts.push_back(context);
+    }
 
-    // Put an object with 1 replica and preferred_segment=segment_1 for testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
+    // The client_id used to put objects.
+    auto client_id = generate_uuid();
+    std::string key_1 = "test_key_1", key_2 = "test_key_2";
+    uint64_t value_length = 6 * 1024 * 1024;  // 6MB
+    uint64_t slice_length = value_length;
     ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
+    config.replica_num = kReplicaCnt;
 
+    // Put key_1, should success.
     auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test Case 2: CopyEnd the object, should fail because there is no ongoing
-    // copy task.
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NO_REPLICATION_TASK, copy_end_result.error());
+        client_id, key_1, TenantId::Default(), slice_length, config);
+    EXPECT_TRUE(put_start_result.has_value());
+    replica_list = put_start_result.value();
+    EXPECT_EQ(replica_list.size(), kReplicaCnt);
+    for (size_t i = 0; i < kReplicaCnt; i++) {
+        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
+    }
 
-    // CopyStart the object to segment_2
-    auto copy_start_result = service_->CopyStart(
-        client_id, key, TenantId::Default(), "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    // Test Case 3: CopyEnd with an invalid client id, should fail.
-    copy_end_result =
-        service_->CopyEnd(invalid_client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::ILLEGAL_CLIENT, copy_end_result.error());
-
-    // Test Case 4: MoveEnd the object, should fail because the ongoing task is
-    // Copy.
-    auto move_end_result =
-        service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_end_result.error());
-
-    // Test Case 5: CopyEnd, should success.
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_end_result.has_value());
-
-    // Verify we now have 2 replicas
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    EXPECT_EQ(2, get_result.value().replicas.size());
-
-    // CopyStart the object from segment_1 to segment_3, then unmount segment_1
-    copy_start_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                            "segment_1", {"segment_3"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    // Unmount segment_1 to simulate source gone
-    auto unmount_result =
-        service_->UnmountSegment(context1.segment_id, context1.client_id);
-    ASSERT_TRUE(unmount_result.has_value());
-
-    // Test Case 6: CopyEnd, should fail because the source is gone, the object
-    // should have only 1 replica from segment_2.
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_GONE, copy_end_result.error());
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    auto& replicas = get_result.value().replicas;
-    EXPECT_EQ(1, replicas.size());
-    EXPECT_EQ("segment_2", replicas[0]
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-
-    // CopyStart the object from segment_2 to segment_3, then unmount segment_3
-    copy_start_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                            "segment_2", {"segment_3"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    // Unmount segment_3 to simulate target gone
-    unmount_result =
-        service_->UnmountSegment(context3.segment_id, context3.client_id);
-    ASSERT_TRUE(unmount_result.has_value());
-
-    // Test Case 7: CopyEnd, should fail because the target is gone, the object
-    // should have only 1 replica from segment_2.
-    copy_end_result = service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_GONE, copy_end_result.error());
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    replicas = get_result.value().replicas;
-    EXPECT_EQ(1, replicas.size());
-    EXPECT_EQ("segment_2", replicas[0]
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-}
-
-TEST_F(MasterServiceTest, CopyRevoke) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 2 segments (segment_1, segment_2) with
-    // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
-
-    // Test Case 1: CopyRevoke a non-existent key, should fail.
-    auto copy_revoke_result = service_->CopyRevoke(
-        client_id, "non_existent_key", TenantId::Default());
-    EXPECT_FALSE(copy_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, copy_revoke_result.error());
-
-    // Put an object with 1 replica and preferred_segment=segment_1 for testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test Case 2: CopyRevoke the object, should fail because there is no
-    // ongoing copy task.
-    copy_revoke_result =
-        service_->CopyRevoke(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NO_REPLICATION_TASK,
-              copy_revoke_result.error());
-
-    // CopyStart the object to segment_2
-    auto copy_start_result = service_->CopyStart(
-        client_id, key, TenantId::Default(), "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    // Test Case 3: CopyRevoke with an invalid client id, should fail.
-    copy_revoke_result =
-        service_->CopyRevoke(invalid_client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::ILLEGAL_CLIENT, copy_revoke_result.error());
-
-    // Test Case 4: MoveRevoke the object, should fail because the ongoing task
-    // is Copy.
-    auto move_revoke_result =
-        service_->MoveRevoke(client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_revoke_result.error());
-
-    // Test Case 5: CopyRevoke, should success.
-    copy_revoke_result =
-        service_->CopyRevoke(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_revoke_result.has_value());
-
-    // Verify we still have 1 replica (the copy was revoked)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-
-    // CopyStart the object from segment_1 to segment_2 again, then unmount
-    // segment_1
-    copy_start_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                            "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    // Unmount segment_1 to simulate source gone
-    auto unmount_result =
-        service_->UnmountSegment(context1.segment_id, context1.client_id);
-    ASSERT_TRUE(unmount_result.has_value());
-
-    // Test Case 6: CopyRevoke, should success even though the source is gone,
-    // the object should be erased too.
-    copy_revoke_result =
-        service_->CopyRevoke(client_id, key, TenantId::Default());
-    EXPECT_TRUE(copy_revoke_result.has_value());
-
-    // Verify the object has been removed.
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-}
-
-TEST_F(MasterServiceTest, MoveStart) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-
-    // Mount 3 segments (segment_1, segment_2, segment_3) with
-    // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-    [[maybe_unused]] const auto context3 =
-        PrepareSimpleSegment(*service_, "segment_3");
-
-    UUID client_id = generate_uuid();
-
-    // Test Case 1: MoveStart a non-existent key, should fail.
-    auto move_start_result =
-        service_->MoveStart(client_id, "non_existent_key", TenantId::Default(),
-                            "segment_1", "segment_2");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, move_start_result.error());
-
-    // Put an object with 1 replica and preferred_segment=segment_1 for testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-
-    // Test Case 2: MoveStart the object, should fail because the only replica
-    // is not completed.
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_1", "segment_2");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_NOT_FOUND, move_start_result.error());
-
-    // PutEnd the object.
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Copy the object to segment_3.
-    auto copy_start_result = service_->CopyStart(
-        client_id, key, TenantId::Default(), "segment_1", {"segment_3"});
-    ASSERT_TRUE(copy_start_result.has_value());
-    auto copy_end_result =
-        service_->CopyEnd(client_id, key, TenantId::Default());
-    ASSERT_TRUE(copy_end_result.has_value());
-
-    // Test Case 3: MoveStart with source and target be the same, should fail.
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_1", "segment_1");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(move_start_result.error(), ErrorCode::INVALID_PARAMS);
-
-    // Test Case 4: MoveStart to segment_2, should succeed.
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_1", "segment_2");
-    EXPECT_TRUE(move_start_result.has_value());
-    auto move_response = move_start_result.value();
-    EXPECT_EQ("segment_1", move_response.source.get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-    EXPECT_TRUE(move_response.target.has_value());
-    EXPECT_EQ("segment_2", move_response.target.value()
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-
-    // Test Case 5: Try remove the object, should fail because it is moving.
-    auto remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, remove_result.error());
-
-    // Test Case 6: MoveStart again, should fail because there is an ongoing
-    // move task.
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_1", "segment_3");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_REPLICATION_TASK,
-              move_start_result.error());
-
-    // Test Case 7: MoveEnd, should succeed and the object now has 2 replicas
-    // from segment_2 and segment_3
-    auto move_end_result =
-        service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(move_end_result.has_value());
-
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    auto& replicas = get_result.value().replicas;
-    EXPECT_EQ(2, replicas.size());
-
-    // Test Case 8: Move from a non-existent replica to segment_1, should fail.
-    move_start_result =
-        service_->MoveStart(client_id, key, TenantId::Default(),
-                            "non_existent_segment", "segment_1");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_NOT_FOUND, move_start_result.error());
-
-    // Test Case 8.5: Move to a non-existent target segment, should fail.
-    move_start_result =
-        service_->MoveStart(client_id, key, TenantId::Default(), "segment_2",
-                            "non_existent_segment");
-    EXPECT_FALSE(move_start_result.has_value());
-    EXPECT_EQ(ErrorCode::SEGMENT_NOT_FOUND, move_start_result.error());
-
-    // Test Case 9: Move to an already existing segment, should succeed but
-    // return nullopt.
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_2", "segment_3");
-    EXPECT_TRUE(move_start_result.has_value());
-    move_response = move_start_result.value();
-    EXPECT_EQ("segment_2", move_response.source.get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-    EXPECT_FALSE(move_response.target.has_value());
-
-    // Test Case 10: Try remove the object, should fail because it is moving.
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
-    remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_REPLICATION_TASK, remove_result.error());
-
-    // End the move.
-    move_end_result = service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(move_end_result.has_value());
-
-    // Now the object should have only 1 replica on segment_3.
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    replicas = get_result.value().replicas;
-    EXPECT_EQ(1, replicas.size());
-    EXPECT_EQ("segment_3", replicas[0]
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-
-    // Test Case 11: Try remove the object, should succeed after lease expires.
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
-    remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result.has_value());
-}
-
-TEST_F(MasterServiceTest, MoveEnd) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 2 segments (segment_1, segment_2) with
-    // PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
-
-    // Test Case 1: MoveEnd a non-existent key, should fail.
-    auto move_end_result =
-        service_->MoveEnd(client_id, "non_existent_key", TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, move_end_result.error());
-
-    // Put an object with 1 replica and preferred_segment=segment_1 for testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test Case 2: MoveEnd the object, should fail because there is no ongoing
-    // move task.
-    move_end_result = service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NO_REPLICATION_TASK, move_end_result.error());
-
-    // MoveStart the object to segment_2
-    auto move_start_result = service_->MoveStart(
-        client_id, key, TenantId::Default(), "segment_1", "segment_2");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Test Case 3: MoveEnd with an invalid client id, should fail.
-    move_end_result =
-        service_->MoveEnd(invalid_client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(ErrorCode::ILLEGAL_CLIENT, move_end_result.error());
-
-    // Test Case 4: CopyEnd the object, should fail because the ongoing task is
-    // Move.
-    auto copy_end_result =
-        service_->CopyEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, copy_end_result.error());
-
-    // Test Case 5: MoveEnd, should success.
-    move_end_result = service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_TRUE(move_end_result.has_value());
-
-    // Verify we still have 1 replica (the move was successful)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    EXPECT_EQ(1, get_result.value().replicas.size());
-
-    // MoveStart the object from segment_2 to segment_1 again, then unmount
-    // segment_2
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_2", "segment_1");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Unmount segment_2 to simulate source gone
-    auto unmount_result =
-        service_->UnmountSegment(context2.segment_id, context2.client_id);
-    ASSERT_TRUE(unmount_result.has_value());
-
-    // Test Case 6: MoveEnd, should fail because the source is gone.
-    move_end_result = service_->MoveEnd(client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_GONE, move_end_result.error());
-}
-
-TEST_F(MasterServiceTest, MoveRevoke) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-
-    UUID client_id = generate_uuid();
-    UUID invalid_client_id = generate_uuid();
-
-    // Test Case 1: MoveRevoke a non-existent key, should fail.
-    auto move_revoke_result = service_->MoveRevoke(
-        client_id, "non_existent_key", TenantId::Default());
-    EXPECT_FALSE(move_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, move_revoke_result.error());
-
-    // Put an object with 1 replica and preferred_segment=segment_1 for testing
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test Case 2: MoveRevoke the object, should fail because there is no
-    // ongoing move task.
-    move_revoke_result =
-        service_->MoveRevoke(client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NO_REPLICATION_TASK,
-              move_revoke_result.error());
-
-    // MoveStart the object from segment_1 to segment_2
-    auto move_start_result = service_->MoveStart(
-        client_id, key, TenantId::Default(), "segment_1", "segment_2");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Test Case 3: MoveRevoke with an invalid client id, should fail.
-    move_revoke_result =
-        service_->MoveRevoke(invalid_client_id, key, TenantId::Default());
-    EXPECT_FALSE(move_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::ILLEGAL_CLIENT, move_revoke_result.error());
-
-    // Test Case 4: CopyRevoke the object, should fail because the ongoing task
-    // is Move.
-    auto copy_revoke_result =
-        service_->CopyRevoke(client_id, key, TenantId::Default());
-    EXPECT_FALSE(copy_revoke_result.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, copy_revoke_result.error());
-
-    // Test Case 5: MoveRevoke, should succeed.
-    move_revoke_result =
-        service_->MoveRevoke(client_id, key, TenantId::Default());
-    EXPECT_TRUE(move_revoke_result.has_value());
-
-    // Verify we still have 1 replica (the move was revoked)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-    auto& replicas = get_result.value().replicas;
-    EXPECT_EQ(1, replicas.size());
-    EXPECT_EQ("segment_1", replicas[0]
-                               .get_memory_descriptor()
-                               .buffer_descriptor.transport_endpoint_);
-
-    // MoveStart the object from segment_1 to segment_2 again, then unmount
-    // segment_1
-    move_start_result = service_->MoveStart(client_id, key, TenantId::Default(),
-                                            "segment_1", "segment_2");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Unmount segment_1 to simulate source gone
-    auto unmount_result =
-        service_->UnmountSegment(context1.segment_id, context1.client_id);
-    ASSERT_TRUE(unmount_result.has_value());
-
-    // Test Case 6: MoveRevoke, should succeed even though the source is gone.
-    move_revoke_result =
-        service_->MoveRevoke(client_id, key, TenantId::Default());
-    EXPECT_TRUE(move_revoke_result.has_value());
-
-    // The object should be erased as there is no replica left.
-    get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-}
-
-TEST_F(MasterServiceTest, ProtectCopyMoveSourceFromEviction) {
-    const uint64_t kv_lease_ttl = 100;
-    const uint64_t client_live_ttl = 600;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_client_live_ttl_sec(client_live_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-
-    // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment, each
-    // 16 MB
-    constexpr size_t kBaseAddr = 0x100000000;
-    constexpr size_t kSegmentSize = 16 * 1024 * 1024;  // 16 MB
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1", kBaseAddr, kSegmentSize);
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2", kBaseAddr, kSegmentSize);
-
-    UUID client_id = generate_uuid();
-
-    const std::string copy_key = "copy_key";
-    const std::string move_key = "move_key";
-    uint64_t slice_length = 1024 * 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    // Put two objects for move and copy tests.
-    auto put_start_result = service_->PutStart(
-        client_id, copy_key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(
-        client_id, copy_key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    put_start_result = service_->PutStart(
-        client_id, move_key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    put_end_result = service_->PutEnd(client_id, move_key, TenantId::Default(),
-                                      ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Start copy and move operations.
-    auto copy_start_result = service_->CopyStart(
-        client_id, copy_key, TenantId::Default(), "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    auto move_start_result = service_->MoveStart(
-        client_id, move_key, TenantId::Default(), "segment_1", "segment_2");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Put more objects to trigger eviction. Do not prefer any segments.
-    config.preferred_segment = "";
-    for (size_t i = 0; i < 128 * (kSegmentSize * 2 / slice_length); ++i) {
-        std::string key = "test_key_" + std::to_string(i);
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        if (put_start_result.has_value()) {
-            auto put_end_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-            ASSERT_TRUE(put_end_result.has_value());
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-
-    // Wait all objects lease expiring and then remove them.
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
-    auto remove_all_result = service_->RemoveAll();
-    ASSERT_TRUE(remove_all_result > 0);
-
-    // Try end copy and move operations, should success.
-    auto copy_end_result =
-        service_->CopyEnd(client_id, copy_key, TenantId::Default());
-    EXPECT_TRUE(copy_end_result.has_value());
-
-    auto move_end_result =
-        service_->MoveEnd(client_id, move_key, TenantId::Default());
-    EXPECT_TRUE(move_end_result.has_value());
-}
-
-TEST_F(MasterServiceTest, DiscardTimeoutCopyMove) {
-    const uint64_t kv_lease_ttl = 100;
-    const uint64_t client_live_ttl = 600;
-    const uint64_t put_discard_timeout = 1;
-    const uint64_t put_release_timeout = 2;
-    auto service_config =
-        MasterServiceConfig::builder()
-            .set_default_kv_lease_ttl(kv_lease_ttl)
-            .set_client_live_ttl_sec(client_live_ttl)
-            .set_put_start_discard_timeout_sec(put_discard_timeout)
-            .set_put_start_release_timeout_sec(put_release_timeout)
-            .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-
-    // Mount 2 segments (segment_1, segment_2) with PrepareSimpleSegment, each
-    // 16 MB
-    constexpr size_t kBaseAddr = 0x100000000;
-    constexpr size_t kSegmentSize = 16 * 1024 * 1024;  // 16 MB
-    [[maybe_unused]] const auto context1 =
-        PrepareSimpleSegment(*service_, "segment_1", kBaseAddr, kSegmentSize);
-    [[maybe_unused]] const auto context2 =
-        PrepareSimpleSegment(*service_, "segment_2", kBaseAddr, kSegmentSize);
-
-    UUID client_id = generate_uuid();
-
-    const std::string copy_key = "copy_key";
-    const std::string move_key = "move_key";
-    uint64_t slice_length = 1024 * 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    // Put two objects for move and copy tests.
-    auto put_start_result = service_->PutStart(
-        client_id, copy_key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(
-        client_id, copy_key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    put_start_result = service_->PutStart(
-        client_id, move_key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    put_end_result = service_->PutEnd(client_id, move_key, TenantId::Default(),
-                                      ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Start copy and move operations.
-    auto copy_start_result = service_->CopyStart(
-        client_id, copy_key, TenantId::Default(), "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_start_result.has_value());
-
-    auto move_start_result = service_->MoveStart(
-        client_id, move_key, TenantId::Default(), "segment_1", "segment_2");
-    ASSERT_TRUE(move_start_result.has_value());
-
-    // Wait for the operations timeout.
-    std::this_thread::sleep_for(std::chrono::seconds(put_release_timeout));
-
-    // Put more objects to trigger eviction. Do not prefer any segments.
-    config.preferred_segment = "";
-    for (size_t i = 0; i < 128 * (kSegmentSize * 2 / slice_length); ++i) {
-        std::string key = "test_key_" + std::to_string(i);
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        if (put_start_result.has_value()) {
-            auto put_end_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-            ASSERT_TRUE(put_end_result.has_value());
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-
-    // Try end copy and move operations, should fail because the objects are
-    // evicted.
-    auto copy_end_result =
-        service_->CopyEnd(client_id, copy_key, TenantId::Default());
-    EXPECT_FALSE(copy_end_result.has_value());
-    EXPECT_EQ(copy_end_result.error(), ErrorCode::OBJECT_NOT_FOUND);
-
-    auto move_end_result =
-        service_->MoveEnd(client_id, move_key, TenantId::Default());
-    EXPECT_FALSE(move_end_result.has_value());
-    EXPECT_EQ(move_end_result.error(), ErrorCode::OBJECT_NOT_FOUND);
-}
-
-TEST_F(MasterServiceTest, RemoveByRegexComplex) {
-    const uint64_t kv_lease_ttl = 100;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-    const UUID client_id = generate_uuid();
-
-    // 1. Mount segment
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment_remove");
-
-    // A helper lambda to repopulate the store for each test case
-    auto populate_store = [&]() {
-        std::vector<std::string> keys_to_put = {
-            "test_key_01",
-            "test_key_02",
-            "test_key_10",
-            "prod_key_alpha",
-            "prod_key_beta",
-            "data_part_1_chunk_a",
-            "data_part_2_chunk_b",
-            "config/user/settings.json",
-            "logs/app-2025-08-13.log",
-            "short",
-            "a_very_very_very_long_key_that_tests_length_limits",
-            "test-key-extra",
-            "another_key"};
-        for (const auto& key : keys_to_put) {
-            put_object(*service_, client_id, key);
-        }
-        // Wait for potential lease propagation
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    };
-
-    // --- Test Case 1: Remove a specific subset and verify ---
-    {
-        SCOPED_TRACE("Test Case 1: Removing keys with prefix 'test_key_'");
-        populate_store();
-
-        // Action: Remove keys starting with "test_key_"
-        auto remove_result =
-            service_->RemoveByRegex("^test_key_", TenantId::Default());
-        ASSERT_TRUE(remove_result.has_value());
-        EXPECT_EQ(remove_result.value(), 3);  // Should remove 3 keys
-
-        // Verification: Check which keys were deleted and which remain
-        std::vector<std::string> deleted_keys = {"test_key_01", "test_key_02",
-                                                 "test_key_10"};
-        for (const auto& key : deleted_keys) {
-            auto exist_result = service_->ExistKey(key, TenantId::Default());
-            ASSERT_TRUE(exist_result.has_value());
-            EXPECT_FALSE(exist_result.value())
-                << "Key " << key << " should have been deleted.";
-        }
-
-        std::vector<std::string> remaining_keys = {
-            "prod_key_alpha", "short", "test-key-extra"};  // Sample a few
-        for (const auto& key : remaining_keys) {
-            auto exist_result = service_->ExistKey(key, TenantId::Default());
-            ASSERT_TRUE(exist_result.has_value());
-            EXPECT_TRUE(exist_result.value())
-                << "Key " << key << " should NOT have been deleted.";
-        }
-    }
-
-    // --- Test Case 2: Remove everything ---
-    {
-        SCOPED_TRACE("Test Case 2: Removing all keys with '.*'");
-        // Store is already populated from the previous (failed) test run, or we
-        // can repopulate For isolation, let's assume we start fresh
-        auto service_config = MasterServiceConfig::builder()
-                                  .set_default_kv_lease_ttl(kv_lease_ttl)
-                                  .build();
-        service_ = std::make_unique<MasterService>(service_config);
-        [[maybe_unused]] const auto context_reset =
-            PrepareSimpleSegment(*service_, "test_segment_remove");
-        populate_store();
-
-        size_t total_keys = 13;  // Count from the keys_to_put vector
-
-        // Action: Remove all keys
-        auto remove_result = service_->RemoveByRegex(".*", TenantId::Default());
-        ASSERT_TRUE(remove_result.has_value());
-        EXPECT_EQ(remove_result.value(), total_keys);
-
-        // Verification: Check that no keys remain
-        auto get_all_result =
-            service_->GetReplicaListByRegex(".*", TenantId::Default());
-        ASSERT_TRUE(get_all_result.has_value());
-        EXPECT_TRUE(get_all_result.value().empty());
-    }
-
-    // --- Test Case 3: Attempt to remove with a non-matching pattern ---
-    {
-        SCOPED_TRACE("Test Case 3: Removing with a non-matching pattern");
-        auto service_config = MasterServiceConfig::builder()
-                                  .set_default_kv_lease_ttl(kv_lease_ttl)
-                                  .build();
-        service_ = std::make_unique<MasterService>(
-            service_config);  // Reset the service
-        [[maybe_unused]] const auto context_reset =
-            PrepareSimpleSegment(*service_, "test_segment_remove");
-        populate_store();
-
-        size_t total_keys_before_remove = 13;
-
-        // Action: Attempt to remove using a pattern that matches nothing
-        auto remove_result = service_->RemoveByRegex("^nonexistent-pattern-",
-                                                     TenantId::Default());
-        ASSERT_TRUE(remove_result.has_value());
-        EXPECT_EQ(remove_result.value(), 0);  // Should remove 0 keys
-
-        // Verification: Check that all keys still exist
-        auto get_all_result =
-            service_->GetReplicaListByRegex(".*", TenantId::Default());
-        ASSERT_TRUE(get_all_result.has_value());
-        EXPECT_EQ(get_all_result.value().size(), total_keys_before_remove);
-    }
-
-    // --- Test Case 4: Remove based on a complex pattern and verify ---
-    {
-        SCOPED_TRACE(
-            "Test Case 4: Removing based on file paths or containing digits");
-        auto service_config = MasterServiceConfig::builder()
-                                  .set_default_kv_lease_ttl(kv_lease_ttl)
-                                  .build();
-        service_ = std::make_unique<MasterService>(service_config);  // Reset
-        [[maybe_unused]] const auto context_reset =
-            PrepareSimpleSegment(*service_, "test_segment_remove");
-        populate_store();
-
-        // Action: Remove all keys that contain a slash '/' OR end with a number
-        auto remove_result =
-            service_->RemoveByRegex("/|\\d$", TenantId::Default());
-        ASSERT_TRUE(remove_result.has_value());
-        // Matches: "config/user/settings.json", "logs/app-2025-08-13.log",
-        //          "test_key_01", "test_key_02", "test_key_10"
-        // Note: logs/app-2025-08-13.log matches both, but is counted once.
-        EXPECT_EQ(remove_result.value(),
-                  5);  // The two paths + test_key_01 and test_key_02.
-                       // (test_key_10 ends with 0) wait, no, 10 ends with 0.
-        // Ah, \d$ matches a single digit at the end. So test_key_01,
-        // test_key_02. test_key_10 does NOT match \d$. Let's refine the regex.
-    }
-
-    // --- Test Case 4 ---
-    {
-        SCOPED_TRACE(
-            "Test Case 4 (Corrected): Removing based on complex pattern");
-        auto service_config = MasterServiceConfig::builder()
-                                  .set_default_kv_lease_ttl(kv_lease_ttl)
-                                  .build();
-        service_ = std::make_unique<MasterService>(service_config);  // Reset
-        [[maybe_unused]] const auto context_reset =
-            PrepareSimpleSegment(*service_, "test_segment_remove");
-        populate_store();
-
-        // Action: Remove all keys that contain "chunk" OR "config"
-        auto remove_result =
-            service_->RemoveByRegex("chunk|config", TenantId::Default());
-        ASSERT_TRUE(remove_result.has_value());
-        // Matches: "data_part_1_chunk_a", "data_part_2_chunk_b",
-        // "config/user/settings.json"
-        EXPECT_EQ(remove_result.value(), 3);
-
-        // Verification
-        auto exist_result_chunk =
-            service_->ExistKey("data_part_1_chunk_a", TenantId::Default());
-        ASSERT_TRUE(exist_result_chunk.has_value());
-        EXPECT_FALSE(exist_result_chunk.value());
-
-        auto exist_result_config = service_->ExistKey(
-            "config/user/settings.json", TenantId::Default());
-        ASSERT_TRUE(exist_result_config.has_value());
-        EXPECT_FALSE(exist_result_config.value());
-
-        auto exist_result_untouched =
-            service_->ExistKey("prod_key_alpha", TenantId::Default());
-        ASSERT_TRUE(exist_result_untouched.has_value());
-        EXPECT_TRUE(exist_result_untouched.value());
-    }
-}
-
-TEST_F(MasterServiceTest, RemoveAll) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-    int times = 10;
-    while (times--) {
-        std::string key = "test_key" + std::to_string(times);
-        uint64_t value_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), value_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-    }
-    // wait for all the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    ASSERT_EQ(10, service_->RemoveAll());
-    times = 10;
-    while (times--) {
-        std::string key = "test_key" + std::to_string(times);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_FALSE(exist_result.value());
-    }
-}
-
-TEST_F(MasterServiceTest, SingleSliceMultiReplicaFlow) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // Mount 3 segments, each 64MB
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 64;  // 64MB
-    for (int i = 0; i < 3; ++i) {
-        [[maybe_unused]] const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-    }
-
-    // Test parameters
-    std::string key = "multi_slice_object";
-    constexpr size_t num_replicas = 3;
-    constexpr size_t slice_length = 1024 * 1024 * 5;  // 5MB
-
-    // Configure replication
-    ReplicateConfig config;
-    config.replica_num = num_replicas;
-    std::vector<Replica::Descriptor> replica_list;
-
-    // Test PutStart with multiple slices and replicas
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-
-    // Verify replica list properties
-    ASSERT_EQ(num_replicas, replica_list.size());
-    for (const auto& replica : replica_list) {
-        // Verify replica status
-        EXPECT_EQ(ReplicaStatus::PROCESSING, replica.status);
-
-        // Verify slice length matches buffer descriptor
-        EXPECT_EQ(slice_length,
-                  replica.get_memory_descriptor().buffer_descriptor.size_);
-    }
-
-    // Test GetReplicaList during processing (should fail)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-
-    // Complete the put operation
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Test GetReplicaList after completion
-    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result2.has_value());
-    auto retrieved_replicas = get_result2.value().replicas;
-    ASSERT_EQ(num_replicas, retrieved_replicas.size());
-
-    // Verify final state of all replicas
-    for (const auto& replica : retrieved_replicas) {
-        EXPECT_EQ(ReplicaStatus::COMPLETE, replica.status);
-        ASSERT_EQ(slice_length,
-                  replica.get_memory_descriptor().buffer_descriptor.size_);
-    }
-}
-
-TEST_F(MasterServiceTest, CleanupStaleHandlesTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount a segment for testing
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;  // 16MB
-    auto segment = MakeSegment("test_segment", buffer, size);
-    UUID client_id = generate_uuid();
-
-    // Mount the segment
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Create an object that will be stored in the segment
-    std::string key = "segment_object";
-    uint64_t slice_length = 1024 * 1024;  // One 1MB slice
-    ReplicateConfig config;
-    config.replica_num = 1;  // One replica
-
-    // Create the object
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Verify object exists
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    auto retrieved_replicas = get_result.value().replicas;
-    ASSERT_EQ(1, retrieved_replicas.size());
-
-    // Unmount the segment
-    auto unmount_result1 = service_->UnmountSegment(segment.id, client_id);
-    ASSERT_TRUE(unmount_result1.has_value());
-
-    // Try to get the object - it should be automatically removed since the
-    // replica is invalid
-    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result2.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result2.error());
-
-    // Mount the segment again
-    mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Create another object
-    std::string key2 = "another_segment_object";
-    auto put_start_result2 = service_->PutStart(
-        client_id, key2, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result2.has_value());
-    auto put_end_result2 = service_->PutEnd(
-        client_id, key2, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result2.has_value());
-
-    // Verify we can get it
-    auto get_result3 = service_->GetReplicaList(key2, TenantId::Default());
-    ASSERT_TRUE(get_result3.has_value());
-
-    // Unmount the segment
-    auto unmount_result2 = service_->UnmountSegment(segment.id, client_id);
-    ASSERT_TRUE(unmount_result2.has_value());
-
-    // Try to remove the object that should already be cleaned up
-    auto remove_result = service_->Remove(key2, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, remove_result.error());
-}
-
-TEST_F(MasterServiceTest, ConcurrentWriteAndRemoveAll) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 256;  // 256MB for concurrent testing
-    auto segment = MakeSegment("concurrent_segment", buffer, size);
-    UUID client_id = generate_uuid();
-    auto mount_result_concurrent = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result_concurrent.has_value());
-
-    constexpr int num_threads = 4;
-    constexpr int objects_per_thread = 100;
-    std::atomic success_writes(0);
-    std::atomic remove_all_done(false);
-    std::atomic total_removed(0);
-
-    // Writer threads
-    std::vector<std::thread> writers;
-    for (int i = 0; i < num_threads; ++i) {
-        writers.emplace_back([&, i]() {
-            for (int j = 0; j < objects_per_thread; ++j) {
-                std::string key =
-                    "key_" + std::to_string(i) + "_" + std::to_string(j);
-                uint64_t slice_length = 1024;
-                ReplicateConfig config;
-                config.replica_num = 1;
-                std::vector<Replica::Descriptor> replica_list;
-
-                auto put_start_result = service_->PutStart(
-                    client_id, key, TenantId::Default(), slice_length, config);
-                if (put_start_result.has_value()) {
-                    auto put_end_result =
-                        service_->PutEnd(client_id, key, TenantId::Default(),
-                                         ReplicaType::MEMORY);
-                    if (put_end_result.has_value()) {
-                        success_writes++;
-                    }
-                }
-
-                // Random sleep to increase concurrency complexity
-                std::this_thread::sleep_for(
-                    std::chrono::milliseconds(rand() % 10));
-            }
-        });
-    }
-
-    // RemoveAll thread
-    std::thread remove_thread([&]() {
-        std::this_thread::sleep_for(
-            std::chrono::milliseconds(50));  // Let some writes start
-        long removed = service_->RemoveAll();
-        LOG(INFO) << "Removed " << removed
-                  << " objects during concurrent writes";
-        ASSERT_GT(removed, 0);
-        remove_all_done = true;
-        total_removed.fetch_add(removed);
-    });
-
-    // Join all threads
-    for (auto& t : writers) {
-        t.join();
-    }
-    remove_thread.join();
-
-    // Verify results
-    EXPECT_GT(success_writes, 0);
-    EXPECT_TRUE(remove_all_done);
-
-    // Final RemoveAll to ensure clean state
-    long final_removed = service_->RemoveAll();
-    LOG(INFO) << "Final RemoveAll removed " << final_removed << " objects";
-    ASSERT_GT(final_removed, 0);
-    total_removed.fetch_add(final_removed);
-    ASSERT_EQ(total_removed, num_threads * objects_per_thread);
-}
-
-TEST_F(MasterServiceTest, ConcurrentReadAndRemoveAll) {
-    // set a large kv_lease_ttl so the granted lease will not quickly expire
-    const uint64_t kv_lease_ttl = 200;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 256;  // 256MB for concurrent testing
-    auto segment = MakeSegment("concurrent_segment", buffer, size);
-    UUID client_id = generate_uuid();
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Pre-populate with test data
-    constexpr int num_objects = 1000;
-    for (int i = 0; i < num_objects; ++i) {
-        std::string key = "pre_key_" + std::to_string(i);
-        uint64_t slice_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-    }
-
-    std::atomic<int> success_reads(0);
-    std::atomic<bool> remove_all_done(false);
-
-    // Reader threads
-    std::vector<std::thread> readers;
-    for (int i = 0; i < 4; ++i) {
-        readers.emplace_back([&]() {
-            for (int j = 0; j < num_objects; ++j) {
-                std::string key = "pre_key_" + std::to_string(j);
-                auto get_result =
-                    service_->GetReplicaList(key, TenantId::Default());
-                if (get_result.has_value()) {
-                    success_reads++;
-                }
-
-                // Random sleep to increase concurrency complexity
-                std::this_thread::sleep_for(
-                    std::chrono::milliseconds(rand() % 5));
-            }
-        });
-    }
-
-    // RemoveAll thread
-    std::thread remove_thread([&]() {
-        std::this_thread::sleep_for(
-            std::chrono::milliseconds(10));  // Let some reads start
-        long removed = service_->RemoveAll();
-        LOG(INFO) << "Removed " << removed
-                  << " objects during concurrent reads";
-        remove_all_done = true;
-    });
-
-    // Join all threads
-    for (auto& t : readers) {
-        t.join();
-    }
-    remove_thread.join();
-
-    EXPECT_TRUE(remove_all_done);
-    // Verify 0 < success_reads < num_objects
-    EXPECT_GT(success_reads, 0);
-    EXPECT_NE(success_reads, num_objects);
-
-    // wait for all the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    long removed = service_->RemoveAll();
-    LOG(INFO) << "Removed " << removed << " objects after kv lease expired";
-
-    // Verify all objects were removed
-    for (int i = 0; i < num_objects; ++i) {
-        std::string key = "pre_key_" + std::to_string(i);
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        EXPECT_FALSE(get_result.has_value());
-        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-    }
-}
-
-TEST_F(MasterServiceTest, ConcurrentRemoveAllOperations) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16 * 100;
-    auto segment = MakeSegment("concurrent_segment", buffer, size);
-    UUID client_id = generate_uuid();
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Pre-populate with test data
-    constexpr int num_objects = 1000;
-    for (int i = 0; i < num_objects; ++i) {
-        std::string key = "pre_key_" + std::to_string(i);
-        uint64_t slice_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-    }
-
-    std::atomic<int> remove_all_count(0);
-
-    // Two RemoveAll threads
-    std::vector<std::thread> remove_threads;
-    for (int i = 0; i < 2; ++i) {
-        remove_threads.emplace_back([&]() {
-            long removed = service_->RemoveAll();
-            LOG(INFO) << "RemoveAll removed " << removed << " objects";
-            remove_all_count += removed;
-        });
-    }
-
-    // Join all threads
-    for (auto& t : remove_threads) {
-        t.join();
-    }
-
-    // Verify results - one RemoveAll should return num_objects, the other 0
-    EXPECT_EQ(num_objects, remove_all_count);
-
-    // Verify all objects were removed
-    for (int i = 0; i < num_objects; ++i) {
-        std::string key = "pre_key_" + std::to_string(i);
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        EXPECT_FALSE(get_result.has_value());
-        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-    }
-}
-
-TEST_F(MasterServiceTest, UnmountSegmentImmediateCleanup) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount two segments for testing
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-
-    auto segment1 = MakeSegment("segment1", buffer1, size);
-    auto segment2 = MakeSegment("segment2", buffer2, size);
-    UUID client_id = generate_uuid();
-    auto mount_result1 = service_->MountSegment(segment1, client_id);
-    ASSERT_TRUE(mount_result1.has_value());
-    auto mount_result2 = service_->MountSegment(segment2, client_id);
-    ASSERT_TRUE(mount_result2.has_value());
-
-    // Create two objects in the two segments
-    std::string key1 =
-        GenerateKeyForSegment(client_id, service_, segment1.name);
-    std::string key2 =
-        GenerateKeyForSegment(client_id, service_, segment2.name);
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Unmount segment1
-    auto unmount_result1 = service_->UnmountSegment(segment1.id, client_id);
-    ASSERT_TRUE(unmount_result1.has_value());
-    // Umount will remove all objects in the segment, include the key1
-    ASSERT_EQ(1, service_->GetKeyCount());
-    // Verify objects in segment1 is gone
-    auto get_result1 = service_->GetReplicaList(key1, TenantId::Default());
-    ASSERT_FALSE(get_result1.has_value());
-    ASSERT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result1.error());
-
-    // Verify objects in segment2 is still there
-    auto get_result2 = service_->GetReplicaList(key2, TenantId::Default());
-    ASSERT_TRUE(get_result2.has_value());
-
-    // Verify put key1 will put into segment2 rather than segment1
-    auto put_start_result = service_->PutStart(
-        client_id, key1, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    auto put_end_result = service_->PutEnd(client_id, key1, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-    auto get_result3 = service_->GetReplicaList(key1, TenantId::Default());
-    ASSERT_TRUE(get_result3.has_value());
-    auto retrieved = get_result3.value();
-    ASSERT_EQ(replica_list[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              segment2.name);
-}
-
-TEST_F(MasterServiceTest, ReadableAfterPartialUnmountWithReplication) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount two large segments
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t segment_size = 1024 * 1024 * 64;  // 64MB
-    constexpr size_t object_size = 1024 * 1024;        // 1MB
-
-    auto segment1 = MakeSegment("segment1", buffer1, segment_size);
-    auto segment2 = MakeSegment("segment2", buffer2, segment_size);
-    UUID client_id = generate_uuid();
-    auto mount_result1 = service_->MountSegment(segment1, client_id);
-    ASSERT_TRUE(mount_result1.has_value());
-    auto mount_result2 = service_->MountSegment(segment2, client_id);
-    ASSERT_TRUE(mount_result2.has_value());
-
-    // Put a key with 2 replicas
-    std::string key = "replicated_key";
-    uint64_t slice_length = object_size;
-    ReplicateConfig config;
-    config.replica_num = 2;
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    ASSERT_EQ(2u, put_start_result->size());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-
-    // Verify two replicas exist and they are on distinct segments
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    auto replicas = get_result.value().replicas;
-    ASSERT_EQ(2u, replicas.size());
-    std::unordered_set<std::string> seg_names;
-    for (const auto& rep : replicas) {
-        ASSERT_EQ(ReplicaStatus::COMPLETE, rep.status);
-        const auto& mem = rep.get_memory_descriptor();
-        ASSERT_EQ(slice_length, mem.buffer_descriptor.size_);
-        seg_names.insert(mem.buffer_descriptor.transport_endpoint_);
-    }
-    ASSERT_EQ(2u, seg_names.size())
-        << "Replicas should be on different segments";
-
-    // Unmount one segment
-    ASSERT_TRUE(service_->UnmountSegment(segment1.id, client_id).has_value());
-
-    // Key should still be readable via the remaining replica
-    auto get_after_unmount = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_after_unmount.has_value())
-        << "Object should remain accessible with surviving replica";
-}
-
-TEST_F(MasterServiceTest, PutStartPartialAllocationIsObservable) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount two segments only
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t segment_size = 1024 * 1024 * 64;  // 64MB
-
-    auto segment1 = MakeSegment("segment1", buffer1, segment_size);
-    auto segment2 = MakeSegment("segment2", buffer2, segment_size);
-    UUID client_id = generate_uuid();
-    ASSERT_TRUE(service_->MountSegment(segment1, client_id).has_value());
-    ASSERT_TRUE(service_->MountSegment(segment2, client_id).has_value());
-
-    auto& metrics = MasterMetricManager::instance();
-    const int64_t partial_before = metrics.get_put_start_partial_allocations();
-
-    // Request more replicas than available segments: best-effort keeps the
-    // put successful but the degradation must be recorded.
-    ReplicateConfig config;
-    config.replica_num = 3;
-    auto put_start_result = service_->PutStart(
-        client_id, "partial_alloc_key", TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    ASSERT_EQ(2u, put_start_result->size());
-    ASSERT_EQ(metrics.get_put_start_partial_allocations(), partial_before + 1);
-
-    // A fully satisfied allocation must not be counted as partial.
-    ReplicateConfig full_config;
-    full_config.replica_num = 2;
-    auto full_result = service_->PutStart(
-        client_id, "full_alloc_key", TenantId::Default(), 1024, full_config);
-    ASSERT_TRUE(full_result.has_value());
-    ASSERT_EQ(2u, full_result->size());
-    ASSERT_EQ(metrics.get_put_start_partial_allocations(), partial_before + 1);
-}
-
-TEST_F(MasterServiceTest, UnmountSegmentPerformance) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    constexpr size_t kBufferAddress = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 256;  // 256MB
-    std::string segment_name = "perf_test_segment";
-    auto segment = MakeSegment(segment_name, kBufferAddress, kSegmentSize);
-    UUID client_id = generate_uuid();
-
-    // Mount a segment for testing
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Create 10000 keys for testing
-    constexpr int kNumKeys = 1000;
-    std::vector<std::string> keys;
-    keys.reserve(kNumKeys);
-
-    auto start = std::chrono::steady_clock::now();
-
-    // Create `kNumKeys` keys
-    for (int i = 0; i < kNumKeys; ++i) {
-        std::string key =
-            GenerateKeyForSegment(client_id, service_, segment_name);
-        keys.push_back(key);
-    }
-
-    auto create_end = std::chrono::steady_clock::now();
-
-    // Execute unmount operation and record operation time
-    auto unmount_start = std::chrono::steady_clock::now();
-    auto unmount_result = service_->UnmountSegment(segment.id, client_id);
-    EXPECT_TRUE(unmount_result.has_value());
-    auto unmount_end = std::chrono::steady_clock::now();
-
-    auto unmount_duration =
-        std::chrono::duration_cast<std::chrono::milliseconds>(unmount_end -
-                                                              unmount_start);
-
-    // Unmount operation should be very fast, so we set 1s limit
-    EXPECT_LE(unmount_duration.count(), 1000)
-        << "Unmount operation took " << unmount_duration.count()
-        << "ms which exceeds 1 second limit";
-
-    // Verify all keys are gone
-    for (const auto& key : keys) {
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        EXPECT_FALSE(get_result.has_value());
-        EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-    }
-
-    // Output performance report
-    auto total_create_duration =
-        std::chrono::duration_cast<std::chrono::milliseconds>(create_end -
-                                                              start);
-    std::cout << "\nPerformance Metrics:\n"
-              << "Keys created: " << kNumKeys << "\n"
-              << "Creation time: " << total_create_duration.count() << "ms\n"
-              << "Unmount time: " << unmount_duration.count() << "ms\n";
-}
-
-TEST_F(MasterServiceTest, RemoveLeasedObject) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Verify lease is granted on ExistsKey
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    auto remove_result = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_result.error());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto remove_result2 = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result2.has_value());
-
-    // Verify lease is extended on successive ExistsKey
-    auto put_start_result2 = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result2.has_value());
-    auto put_end_result2 = service_->PutEnd(client_id, key, TenantId::Default(),
-                                            ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result2.has_value());
-    auto exist_result2 = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result2.has_value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto exist_result3 = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result3.has_value());
-    auto remove_result3 = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result3.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_result3.error());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto remove_result4 = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result4.has_value());
-
-    // Verify lease is granted on GetReplicaList
-    auto put_start_result3 = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result3.has_value());
-    auto put_end_result3 = service_->PutEnd(client_id, key, TenantId::Default(),
-                                            ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result3.has_value());
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-    auto remove_result5 = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result5.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_result5.error());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto remove_result6 = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result6.has_value());
-
-    // Verify lease is extended on successive GetReplicaList
-    auto put_start_result4 = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result4.has_value());
-    auto put_end_result4 = service_->PutEnd(client_id, key, TenantId::Default(),
-                                            ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result4.has_value());
-    auto get_result2 = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result2.has_value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto get_result3 = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result3.has_value());
-    auto remove_result7 = service_->Remove(key, TenantId::Default());
-    EXPECT_FALSE(remove_result7.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_result7.error());
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    auto remove_result8 = service_->Remove(key, TenantId::Default());
-    EXPECT_TRUE(remove_result8.has_value());
-
-    // Verify object is removed
-    auto get_result4 = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result4.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result4.error());
-}
-
-TEST_F(MasterServiceTest, RemoveAllLeasedObject) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-    for (int i = 0; i < 10; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        if (i >= 5) {
-            auto exist_result = service_->ExistKey(key, TenantId::Default());
-            ASSERT_TRUE(exist_result.has_value());
-        }
-    }
-    ASSERT_EQ(5, service_->RemoveAll());
-    for (int i = 0; i < 5; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_FALSE(exist_result.value());
-    }
-    // wait for all the lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    ASSERT_EQ(5, service_->RemoveAll());
-    for (int i = 5; i < 10; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_FALSE(exist_result.value());
-    }
-}
-
-TEST_F(MasterServiceTest, EvictObject) {
-    // set a large kv_lease_ttl so the granted lease will not quickly expire
-    const uint64_t kv_lease_ttl = 2000;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-    // Mount a segment that can hold about 1024 * 16 objects.
-    // As the eviction is processed separately for each shard,
-    // we need to fill each shard with enough objects to thoroughly
-    // test the eviction process.
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    // Verify if we can put objects more than the segment can hold
-    int success_puts = 0;
-    for (int i = 0; i < 1024 * 16 + 50; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = object_size;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        if (put_start_result.has_value()) {
-            auto put_end_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-            ASSERT_TRUE(put_end_result.has_value());
-            success_puts++;
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-    ASSERT_GT(success_puts, 1024 * 16);
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service_->RemoveAll();
-}
-
-TEST_F(MasterServiceTest, TryEvictLeasedObject) {
-    // set a large kv_lease_ttl so the granted lease will not quickly expire
-    const uint64_t kv_lease_ttl = 500;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    constexpr size_t object_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    // Verify leased object will not be evicted.
-    int success_puts = 0;
-    int failed_puts = 0;
-    std::vector<std::string> leased_keys;
-    for (int i = 0; i < 16 + 10; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = object_size;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        if (put_start_result.has_value()) {
-            auto put_end_result = service_->PutEnd(
-                client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-            ASSERT_TRUE(put_end_result.has_value());
-            // the object is leased
-            auto get_result =
-                service_->GetReplicaList(key, TenantId::Default());
-            ASSERT_TRUE(get_result.has_value());
-            leased_keys.push_back(key);
-            success_puts++;
-        } else {
-            failed_puts++;
-        }
-    }
-    ASSERT_GT(success_puts, 0);
-    ASSERT_GT(failed_puts, 0);
-    // wait for eviction to do eviction
-    std::this_thread::sleep_for(std::chrono::milliseconds(50));
-    // All leased objects should be accessible
-    for (const auto& key : leased_keys) {
-        auto get_result = service_->GetReplicaList(key, TenantId::Default());
-        ASSERT_TRUE(get_result.has_value());
-    }
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service_->RemoveAll();
-}
-
-TEST_F(MasterServiceTest, RemoveSoftPinObject) {
-    const uint64_t kv_lease_ttl = 200;
-    // set a large soft_pin_ttl so the granted soft pin will not quickly expire
-    const uint64_t kv_soft_pin_ttl = 10000;
-    const bool allow_evict_soft_pinned_objects = true;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-    // Mount segment and put an object
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    std::string key = "test_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.with_soft_pin = true;
-
-    // Verify soft pin does not block remove
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_TRUE(service_->Remove(key, TenantId::Default()).has_value());
-
-    // Verify soft pin does not block RemoveAll
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-    EXPECT_EQ(1, service_->RemoveAll());
-}
-
-TEST_F(MasterServiceTest, SoftPinObjectsNotEvictedBeforeOtherObjects) {
-    const uint64_t kv_lease_ttl = 200;
-    // set a large soft_pin_ttl so the granted soft pin will not quickly expire
-    const uint64_t kv_soft_pin_ttl = 10000;
-    const double eviction_ratio = 0.5;
-    const bool allow_evict_soft_pinned_objects = true;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .set_eviction_ratio(eviction_ratio)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // Mount segment and put an object
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
-
-    // The eviction has random factors, so test 5 times
-    for (int test_i = 0; test_i < 5; test_i++) {
-        // Put pin_key first
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig soft_pin_config;
-            soft_pin_config.replica_num = 1;
-            soft_pin_config.with_soft_pin = true;
-
-            ASSERT_TRUE(service_
-                            ->PutStart(client_id, pin_key, TenantId::Default(),
-                                       slice_length, soft_pin_config)
-                            .has_value());
-            ASSERT_TRUE(service_
-                            ->PutEnd(client_id, pin_key, TenantId::Default(),
-                                     ReplicaType::MEMORY)
-                            .has_value());
-        }
-
-        // Fill the segment to trigger eviction
-        int failed_puts = 0;
-        for (int i = 0; i < 20; i++) {
-            std::string key = "key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig config;
-            config.replica_num = 1;
-            if (service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value()) {
-                ASSERT_TRUE(service_
-                                ->PutEnd(client_id, key, TenantId::Default(),
-                                         ReplicaType::MEMORY)
-                                .has_value());
-            } else {
-                failed_puts++;
-            }
-        }
-        ASSERT_GT(failed_puts, 0);
-        // wait for eviction to do eviction
-        std::this_thread::sleep_for(
-            std::chrono::milliseconds(kv_lease_ttl + 1000));
-        // pin_key should still be accessible
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            ASSERT_TRUE(service_->GetReplicaList(pin_key, TenantId::Default())
-                            .has_value());
-        }
-
-        // wait for the lease to expire
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-        // remove all objects before the next turn
-        service_->RemoveAll();
-    }
-}
-
-TEST_F(MasterServiceTest, SoftPinObjectsCanBeEvicted) {
-    const uint64_t kv_lease_ttl = 200;
-    // set a large soft_pin_ttl so the granted soft pin will not quickly expire
-    const uint64_t kv_soft_pin_ttl = 10000;
-    const bool allow_evict_soft_pinned_objects = true;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // Mount segment and put an object
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
-
-    // Verify if we can put objects more than the segment can hold
-    int success_puts = 0;
-    for (int i = 0; i < 16 + 50; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = value_size;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.with_soft_pin = true;
-        if (service_
-                ->PutStart(client_id, key, TenantId::Default(), slice_length,
-                           config)
-                .has_value()) {
-            ASSERT_TRUE(service_
-                            ->PutEnd(client_id, key, TenantId::Default(),
-                                     ReplicaType::MEMORY)
-                            .has_value());
-            success_puts++;
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-    ASSERT_GT(success_puts, 16);
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service_->RemoveAll();
-}
-
-TEST_F(MasterServiceTest, SoftPinExtendedOnGet) {
-    const uint64_t kv_lease_ttl = 200;
-    // The soft pin ttl shall not be too large, otherwise the test will take too
-    // long
-    const uint64_t kv_soft_pin_ttl = 1000;
-    static_assert(
-        kv_soft_pin_ttl > kv_lease_ttl,
-        "kv_soft_pin_ttl must be larger than kv_lease_ttl in this test");
-    const double eviction_ratio = 0.5;
-    const bool allow_evict_soft_pinned_objects = true;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .set_eviction_ratio(eviction_ratio)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // Mount segment and put an object
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
-
-    // The eviction has random factors, so test 3 times
-    for (int test_i = 0; test_i < 3; test_i++) {
-        // Put pin_key first
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig soft_pin_config;
-            soft_pin_config.replica_num = 1;
-            soft_pin_config.with_soft_pin = true;
-
-            ASSERT_TRUE(service_->PutStart(client_id, pin_key,
-                                           TenantId::Default(), slice_length,
-                                           soft_pin_config));
-            ASSERT_TRUE(service_
-                            ->PutEnd(client_id, pin_key, TenantId::Default(),
-                                     ReplicaType::MEMORY)
-                            .has_value());
-        }
-
-        // Wait for the soft pin to expire
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_soft_pin_ttl));
-
-        // Get the pin_key to extend the soft pin
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            ASSERT_TRUE(service_->GetReplicaList(pin_key, TenantId::Default())
-                            .has_value());
-        }
-
-        // Fill the segment to trigger eviction
-        int failed_puts = 0;
-        for (int i = 0; i < 16; i++) {
-            std::string key = "key" + std::to_string(i);
-            uint64_t slice_length = value_size;
-            ReplicateConfig config;
-            config.replica_num = 1;
-            if (service_
-                    ->PutStart(client_id, key, TenantId::Default(),
-                               slice_length, config)
-                    .has_value()) {
-                ASSERT_TRUE(service_
-                                ->PutEnd(client_id, key, TenantId::Default(),
-                                         ReplicaType::MEMORY)
-                                .has_value());
-            } else {
-                failed_puts++;
-            }
-        }
-        ASSERT_GT(failed_puts, 0);
-
-        // wait for eviction
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-
-        // pin_key should still be accessible
-        for (int i = 0; i < 2; i++) {
-            std::string pin_key = "pin_key" + std::to_string(i);
-            ASSERT_TRUE(service_->GetReplicaList(pin_key, TenantId::Default())
-                            .has_value());
-        }
-
-        // wait for the lease to expire
-        std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-        // remove all objects before the next turn
-        service_->RemoveAll();
-    }
-}
-
-TEST_F(MasterServiceTest, SoftPinObjectsNotAllowEvict) {
-    const uint64_t kv_lease_ttl = 200;
-    // set a large soft_pin_ttl so the granted soft pin will not quickly expire
-    const uint64_t kv_soft_pin_ttl = 10000;
-    // set allow_evict_soft_pinned_objects to false to disable eviction of soft
-    // pinned objects
-    const bool allow_evict_soft_pinned_objects = false;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // Mount segment and put an object
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
-
-    // Put objects more than the segment can hold
-    std::vector<std::string> success_keys;
-    for (int i = 0; i < 16 + 50; ++i) {
-        std::string key = "test_key" + std::to_string(i);
-        uint64_t slice_length = value_size;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.with_soft_pin = true;
-        if (service_
-                ->PutStart(client_id, key, TenantId::Default(), slice_length,
-                           config)
-                .has_value()) {
-            ASSERT_TRUE(service_
-                            ->PutEnd(client_id, key, TenantId::Default(),
-                                     ReplicaType::MEMORY)
-                            .has_value());
-            success_keys.push_back(key);
-        } else {
-            // wait for eviction to work
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-    ASSERT_LE(success_keys.size(), 17);
-    // All soft pinned objects should be accessible
-    for (const auto& key : success_keys) {
-        ASSERT_TRUE(
-            service_->GetReplicaList(key, TenantId::Default()).has_value());
-    }
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service_->RemoveAll();
-}
-
-TEST_F(MasterServiceTest, ReplicaSegmentsAreUnique) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount 20 segments, each 16MB and slab-aligned
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    for (int i = 0; i < 20; ++i) {
-        [[maybe_unused]] const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-    }
-
-    // Object with 16 slices of ~1MB and replication factor 10
-    const std::string key = "replica_uniqueness_test_key";
-    uint64_t slice_length = 1024 * 1024 - 16;
-    ReplicateConfig config;
-    config.replica_num = 10;
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto replica_list_local = put_start_result.value();
-    ASSERT_EQ(config.replica_num, replica_list_local.size());
-
-    // Segment names across replicas must be unique
-    std::unordered_set<std::string> segment_names;
-    for (const auto& replica : replica_list_local) {
-        ASSERT_TRUE(replica.is_memory_replica());
-        const auto& mem = replica.get_memory_descriptor();
-        ASSERT_EQ(slice_length, mem.buffer_descriptor.size_);
-        segment_names.insert(mem.buffer_descriptor.transport_endpoint_);
-    }
-    EXPECT_EQ(segment_names.size(), config.replica_num)
-        << "Duplicate segment found";
-
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
-}
-
-TEST_F(MasterServiceTest, ReplicationFactorTwoWithSingleSegment) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a single 16MB segment
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(
-        *service_, "single_segment", kBaseAddr, kSegmentSize);
-
-    // Request replication factor 2 with a single 1KB slice.
-    // With best-effort semantics, should succeed with 1 replica.
-    const std::string key = "replication_factor_two_single_segment";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 2;
-
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto replicas = put_start_result.value();
-
-    // Should get 1 replica instead of the requested 2 (best-effort).
-    EXPECT_EQ(1u, replicas.size());
-    EXPECT_TRUE(replicas[0].is_memory_replica());
-
-    // Verify the replica is properly allocated on the single segment.
-    auto mem_desc = replicas[0].get_memory_descriptor();
-    EXPECT_EQ("single_segment", mem_desc.buffer_descriptor.transport_endpoint_);
-    EXPECT_EQ(1024u, mem_desc.buffer_descriptor.size_);
-}
-
-TEST_F(MasterServiceTest, BatchExistKeyTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a segment
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 128;
-    constexpr size_t value_size = 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    int test_object_num = 10;
-    std::vector<std::string> test_keys;
-    for (int i = 0; i < test_object_num; ++i) {
-        test_keys.push_back("test_key" + std::to_string(i));
-        ReplicateConfig config;
-        config.replica_num = 1;
-        uint64_t slice_length = value_size;
-        auto put_start_result = service_->PutStart(
-            client_id, test_keys[i], TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, test_keys[i], TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-    }
-
-    // Test individual ExistKey calls to verify the underlying functionality
-    for (int i = 0; i < test_object_num; ++i) {
-        auto exist_result =
-            service_->ExistKey(test_keys[i], TenantId::Default());
-        EXPECT_TRUE(exist_result.value());
-    }
-
-    // Tets batch
-    test_keys.push_back("non_existent_key");
-    auto exist_resp = service_->BatchExistKey(test_keys, TenantId::Default());
-    for (int i = 0; i < test_object_num; ++i) {
-        ASSERT_TRUE(exist_resp[i].value());
-    }
-    ASSERT_FALSE(exist_resp[test_object_num].value());
-}
-
-TEST_F(MasterServiceTest, BatchExistKeyGroupedAndIncompletePreservesOrder) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 128;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    const std::string grouped_key_a = "batch_grouped_key_a";
-    const std::string grouped_key_b = "batch_grouped_key_b";
-    const std::string group_id = FindGroupIdOnDifferentShard(grouped_key_a);
-    ReplicateConfig grouped_config;
-    grouped_config.replica_num = 1;
-    grouped_config.group_ids = std::vector<std::string>{group_id};
-    PutCompletedObject(*service_, client_id, grouped_key_a, grouped_config);
-    PutCompletedObject(*service_, client_id, grouped_key_b, grouped_config);
-
-    const std::string completed_key = "batch_completed_key";
-    ReplicateConfig config;
-    config.replica_num = 1;
-    PutCompletedObject(*service_, client_id, completed_key, config);
-
-    const std::string incomplete_key = "batch_incomplete_key";
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, incomplete_key, TenantId::Default(),
-                               1024, config)
-                    .has_value());
-
-    const std::string missing_key = "batch_missing_key";
-    std::vector<std::string> keys = {grouped_key_a, completed_key,
-                                     incomplete_key, missing_key,
-                                     grouped_key_b};
-
-    auto resp = service_->BatchExistKey(keys, TenantId::Default());
-    ASSERT_EQ(resp.size(), keys.size());
-    ASSERT_TRUE(resp[0].has_value());
-    ASSERT_TRUE(resp[1].has_value());
-    ASSERT_TRUE(resp[2].has_value());
-    ASSERT_TRUE(resp[3].has_value());
-    ASSERT_TRUE(resp[4].has_value());
-    EXPECT_TRUE(resp[0].value());
-    EXPECT_TRUE(resp[1].value());
-    EXPECT_FALSE(resp[2].value());
-    EXPECT_FALSE(resp[3].value());
-    EXPECT_TRUE(resp[4].value());
-}
-
-TEST_F(MasterServiceTest, BatchExistKeyTenantAwarePreservesOrder) {
-    const TenantId tenant_id("tenant_batch_exist");
-    auto service_ = std::make_unique<MasterService>(MakeStrictTenantConfig(
-        {std::string(TenantId::kDefaultValue), tenant_id.value()}));
-    const UUID client_id = generate_uuid();
-
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 128;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, size);
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    const std::string tenant_only_key = "batch_tenant_only";
-    const std::string default_only_key = "batch_default_only";
-    const std::string incomplete_key = "batch_tenant_incomplete";
-    const std::string missing_key = "batch_tenant_missing";
-
-    PutCompletedObject(*service_, client_id, tenant_only_key, tenant_id,
-                       config);
-    PutCompletedObject(*service_, client_id, default_only_key, config);
-    ASSERT_TRUE(
-        service_->PutStart(client_id, incomplete_key, tenant_id, 1024, config)
-            .has_value());
-
-    std::vector<std::string> tenant_keys = {tenant_only_key, default_only_key,
-                                            missing_key, incomplete_key,
-                                            tenant_only_key};
-    auto tenant_resp = service_->BatchExistKey(tenant_keys, tenant_id);
-    ASSERT_EQ(tenant_resp.size(), tenant_keys.size());
-    EXPECT_TRUE(tenant_resp[0].value());
-    EXPECT_FALSE(tenant_resp[1].value());
-    EXPECT_FALSE(tenant_resp[2].value());
-    EXPECT_FALSE(tenant_resp[3].value());
-    EXPECT_TRUE(tenant_resp[4].value());
-
-    std::vector<std::string> default_keys = {tenant_only_key, default_only_key};
-    auto default_resp =
-        service_->BatchExistKey(default_keys, TenantId::Default());
-    ASSERT_EQ(default_resp.size(), default_keys.size());
-    EXPECT_FALSE(default_resp[0].value());
-    EXPECT_TRUE(default_resp[1].value());
-}
-
-TEST_F(MasterServiceTest, WrappedBatchExistKeyUsesTenantAwareBatchPath) {
-    const TenantId tenant_id("wrapped_batch_exist_tenant");
-    auto service_config = MakeStrictWrappedConfig(
-        {std::string(TenantId::kDefaultValue), tenant_id.value()});
-    WrappedMasterService service_(service_config);
-
-    Segment segment = MakeSegment("wrapped_batch_exist_segment");
-    const UUID client_id = generate_uuid();
-    ASSERT_TRUE(service_.MountSegment(segment, client_id).has_value());
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    const std::string tenant_key_a = "wrapped_batch_tenant_a";
-    const std::string tenant_key_b = "wrapped_batch_tenant_b";
-    const std::string default_only_key = "wrapped_batch_default_only";
-    const std::string missing_key = "wrapped_batch_missing";
-
-    std::vector<std::string> tenant_keys = {tenant_key_a, tenant_key_b};
-    std::vector<uint64_t> tenant_sizes = {1024, 2048};
-    auto tenant_put_start = service_.BatchPutStart(
-        client_id, tenant_keys, tenant_sizes, config, tenant_id.value());
-    ASSERT_EQ(tenant_put_start.size(), tenant_keys.size());
-    for (const auto& result : tenant_put_start) {
-        ASSERT_TRUE(result.has_value()) << toString(result.error());
-    }
-    auto tenant_put_end =
-        service_.BatchPutEnd(client_id, MakeObjectMetas(tenant_keys),
-                             ReplicaType::MEMORY, tenant_id.value());
-    ASSERT_EQ(tenant_put_end.size(), tenant_keys.size());
-    for (const auto& result : tenant_put_end) {
-        ASSERT_TRUE(result.has_value()) << toString(result.error());
-    }
-
-    auto default_put_start =
-        service_.PutStart(client_id, default_only_key, 1024, config);
-    ASSERT_TRUE(default_put_start.has_value());
-    ASSERT_TRUE(service_
-                    .PutEnd(client_id,
-                            ObjectMeta{default_only_key, std::nullopt},
-                            ReplicaType::MEMORY)
-                    .has_value());
-
-    auto& metrics = MasterMetricManager::instance();
-    const auto base_requests = metrics.get_batch_exist_key_requests();
-    const auto base_items = metrics.get_batch_exist_key_items();
-    const auto base_failures = metrics.get_batch_exist_key_failures();
-    const auto base_partial = metrics.get_batch_exist_key_partial_successes();
-    const auto base_failed_items = metrics.get_batch_exist_key_failed_items();
-
-    std::vector<std::string> lookup_keys = {tenant_key_a, default_only_key,
-                                            missing_key, tenant_key_b};
-    auto resp = service_.BatchExistKey(lookup_keys, tenant_id.value());
-    ASSERT_EQ(resp.size(), lookup_keys.size());
-    EXPECT_TRUE(resp[0].value());
-    EXPECT_FALSE(resp[1].value());
-    EXPECT_FALSE(resp[2].value());
-    EXPECT_TRUE(resp[3].value());
-
-    EXPECT_EQ(base_requests + 1, metrics.get_batch_exist_key_requests());
-    EXPECT_EQ(base_items + lookup_keys.size(),
-              metrics.get_batch_exist_key_items());
-    EXPECT_EQ(base_failures, metrics.get_batch_exist_key_failures());
-    EXPECT_EQ(base_partial, metrics.get_batch_exist_key_partial_successes());
-    EXPECT_EQ(base_failed_items, metrics.get_batch_exist_key_failed_items());
-}
-
-TEST_F(MasterServiceTest, WrappedWriteBoundaryRejectsInvalidTenantIds) {
-    WrappedMasterService service(
-        MakeStrictWrappedConfig({"registered-tenant"}));
-    ReplicateConfig config;
-    config.replica_num = 1;
-    const UUID client_id = generate_uuid();
-
-    auto empty =
-        service.PutStart(client_id, "empty-tenant-key", 1024, config, "");
-    ASSERT_FALSE(empty.has_value());
-    EXPECT_EQ(empty.error(), ErrorCode::TENANT_NOT_REGISTERED);
-
-    const std::string control_tenant("tenant\0bad", 10);
-    auto invalid = service.PutStart(client_id, "invalid-tenant-key", 1024,
-                                    config, control_tenant);
-    ASSERT_FALSE(invalid.has_value());
-    EXPECT_EQ(invalid.error(), ErrorCode::TENANT_NOT_REGISTERED);
-}
-
-TEST_F(MasterServiceTest, WrappedRequestBoundaryRejectsInvalidTenantIds) {
-    WrappedMasterService service(
-        MakeStrictWrappedConfig({std::string(TenantId::kDefaultValue)}));
-
-    auto invalid = service.GetReplicaList("missing-key", "_invalid-tenant");
-    ASSERT_FALSE(invalid.has_value());
-    EXPECT_EQ(invalid.error(), ErrorCode::INVALID_PARAMS);
-
-    const std::string control_tenant("tenant\0bad", 10);
-    auto batch =
-        service.BatchGetReplicaList({"key-a", "key-b"}, control_tenant);
-    ASSERT_EQ(batch.size(), 2u);
-    for (const auto& result : batch) {
-        ASSERT_FALSE(result.has_value());
-        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
-    }
-
-    std::vector<OffloadTaskItem> tasks = {
-        {.tenant_id = "_invalid-tenant", .key = "key", .size = 1}};
-    std::vector<StorageObjectMetadata> metadatas = {
-        {.bucket_id = 0,
-         .offset = 0,
-         .key_size = 3,
-         .data_size = 1,
-         .transport_endpoint = "segment"}};
-    auto offload =
-        service.NotifyOffloadSuccess(generate_uuid(), tasks, metadatas);
-    ASSERT_FALSE(offload.has_value());
-    EXPECT_EQ(offload.error(), ErrorCode::INVALID_PARAMS);
-
-    // RemoveAll has a legacy scalar return type and cannot carry ErrorCode.
-    EXPECT_EQ(service.RemoveAll(false, "_invalid-tenant"), 0);
-}
-
-TEST_F(MasterServiceTest, WrappedRequestBoundaryPreservesTenantNormalization) {
-    WrappedMasterService multi_tenant_service(
-        MakeStrictWrappedConfig({std::string(TenantId::kDefaultValue)}));
-    auto empty = multi_tenant_service.ExistKey("missing-key", "");
-    ASSERT_TRUE(empty.has_value());
-    EXPECT_FALSE(empty.value());
-
-    WrappedMasterServiceConfig single_tenant_config;
-    single_tenant_config.default_kv_lease_ttl = 100;
-    single_tenant_config.enable_metric_reporting = false;
-    single_tenant_config.enable_multi_tenants = false;
-    WrappedMasterService single_tenant_service(single_tenant_config);
-    auto invalid =
-        single_tenant_service.ExistKey("missing-key", "_invalid-tenant");
-    ASSERT_TRUE(invalid.has_value());
-    EXPECT_FALSE(invalid.value());
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a segment with a specific te_endpoint (IP:Port format)
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    Segment segment = MakeSegment("test_segment", buffer, size);
-    segment.te_endpoint = "127.0.0.1:12345";  // Set IP:Port format for testing
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    // Test BatchQueryIp with a single client_id
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-
-    ASSERT_TRUE(query_result.has_value())
-        << "BatchQueryIp failed: " << toString(query_result.error());
-
-    const auto& results = query_result.value();
-    ASSERT_FALSE(results.empty()) << "BatchQueryIp returned empty results";
-
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end()) << "Client ID not found in results";
-
-    const auto& ip_addresses = it->second;
-    ASSERT_FALSE(ip_addresses.empty()) << "No IP addresses found for client";
-    ASSERT_EQ(1u, ip_addresses.size()) << "Expected exactly 1 IP address";
-    EXPECT_EQ("127.0.0.1", ip_addresses[0]) << "IP address mismatch";
-
-    // Test BatchQueryIp with multiple client_ids (one valid, one invalid)
-    UUID non_existent_client_id = generate_uuid();
-    std::vector<UUID> mixed_client_ids = {client_id, non_existent_client_id};
-    auto mixed_query_result = service_->BatchQueryIp(mixed_client_ids);
-
-    ASSERT_TRUE(mixed_query_result.has_value());
-    const auto& mixed_results = mixed_query_result.value();
-
-    // Valid client_id should be in results
-    ASSERT_NE(mixed_results.find(client_id), mixed_results.end())
-        << "Valid client_id should be in results";
-
-    // Invalid client_id should not be in results (silently skipped)
-    EXPECT_EQ(mixed_results.find(non_existent_client_id), mixed_results.end())
-        << "Invalid client_id should not be in results";
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpMultipleSegmentsTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount multiple segments with different IPs for the same client
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-
-    Segment segment1 = MakeSegment("segment1", buffer1, size);
-    segment1.te_endpoint = "127.0.0.1:12345";
-    auto mount_result1 = service_->MountSegment(segment1, client_id);
-    ASSERT_TRUE(mount_result1.has_value());
-
-    Segment segment2 = MakeSegment("segment2", buffer2, size);
-    segment2.te_endpoint = "127.0.0.1:12346";  // Same IP, different port
-    auto mount_result2 = service_->MountSegment(segment2, client_id);
-    ASSERT_TRUE(mount_result2.has_value());
-
-    Segment segment3 = MakeSegment("segment3", 0x500000000, size);
-    segment3.te_endpoint = "192.168.1.1:12345";  // Different IP
-    auto mount_result3 = service_->MountSegment(segment3, client_id);
-    ASSERT_TRUE(mount_result3.has_value());
-
-    // Test BatchQueryIp - should return unique IPs
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-
-    ASSERT_TRUE(query_result.has_value());
-    const auto& results = query_result.value();
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end());
-
-    const auto& ip_addresses = it->second;
-    // Should have 2 unique IPs: 127.0.0.1 and 192.168.1.1
-    ASSERT_EQ(2u, ip_addresses.size()) << "Expected 2 unique IP addresses";
-
-    // Verify both IPs are present
-    std::unordered_set<std::string> ip_set(ip_addresses.begin(),
-                                           ip_addresses.end());
-    EXPECT_NE(ip_set.find("127.0.0.1"), ip_set.end());
-    EXPECT_NE(ip_set.find("192.168.1.1"), ip_set.end());
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpEmptyClientIdTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Test with empty client_ids list
-    std::vector<UUID> empty_client_ids;
-    auto query_result = service_->BatchQueryIp(empty_client_ids);
-
-    ASSERT_TRUE(query_result.has_value());
-    const auto& results = query_result.value();
-    EXPECT_TRUE(results.empty())
-        << "Empty client_ids should return empty results";
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpMultipleSegmentsEmptyTeEndpointTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount multiple segments, all with empty te_endpoint
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-
-    Segment segment1 = MakeSegment("segment1", buffer1, size);
-    segment1.te_endpoint = "";  // Empty te_endpoint
-    auto mount_result1 = service_->MountSegment(segment1, client_id);
-    ASSERT_TRUE(mount_result1.has_value());
-
-    Segment segment2 = MakeSegment("segment2", buffer2, size);
-    segment2.te_endpoint = "";  // Empty te_endpoint
-    auto mount_result2 = service_->MountSegment(segment2, client_id);
-    ASSERT_TRUE(mount_result2.has_value());
-
-    // Test BatchQueryIp - should return client with empty IP vector
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-
-    ASSERT_TRUE(query_result.has_value());
-    const auto& results = query_result.value();
-    ASSERT_FALSE(results.empty())
-        << "BatchQueryIp should include client in results even with empty IPs";
-
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end()) << "Client ID should be found in results even "
-                                    "with all empty te_endpoints";
-
-    // Verify the IP vector is empty
-    const auto& ip_addresses = it->second;
-    EXPECT_TRUE(ip_addresses.empty())
-        << "Client with all empty te_endpoints should have empty IP vector";
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpBracketedIpv6Test) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a segment with a bracketed IPv6 endpoint
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    Segment segment = MakeSegment("test_segment", buffer, size);
-    segment.te_endpoint = "[::1]:17813";
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-    ASSERT_TRUE(query_result.has_value());
-
-    const auto& results = query_result.value();
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end());
-
-    const auto& ip_addresses = it->second;
-    ASSERT_EQ(1u, ip_addresses.size());
-    EXPECT_EQ("::1", ip_addresses[0]);
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpLinkLocalIpv6WithScopeTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a segment with a link-local IPv6 address with scope ID
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    Segment segment = MakeSegment("test_segment", buffer, size);
-    segment.te_endpoint = "fe80::a236:bcff:fecb:a1be%eno2:15773";
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-    ASSERT_TRUE(query_result.has_value());
-
-    const auto& results = query_result.value();
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end());
-
-    const auto& ip_addresses = it->second;
-    ASSERT_EQ(1u, ip_addresses.size());
-    EXPECT_EQ("fe80::a236:bcff:fecb:a1be%eno2", ip_addresses[0]);
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpIpv6NoPortTest) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount a segment with an IPv6 address without port
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    Segment segment = MakeSegment("test_segment", buffer, size);
-    segment.te_endpoint = "::1";
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-    ASSERT_TRUE(query_result.has_value());
-
-    const auto& results = query_result.value();
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end());
-
-    const auto& ip_addresses = it->second;
-    ASSERT_EQ(1u, ip_addresses.size());
-    EXPECT_EQ("::1", ip_addresses[0]);
-}
-
-TEST_F(MasterServiceTest, BatchQueryIpMixedIpv4AndIpv6Test) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const UUID client_id = generate_uuid();
-
-    // Mount segments with IPv4 and IPv6 endpoints for the same client
-    constexpr size_t buffer1 = 0x300000000;
-    constexpr size_t buffer2 = 0x400000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-
-    Segment segment1 = MakeSegment("segment1", buffer1, size);
-    segment1.te_endpoint = "192.168.1.1:12345";
-    auto mount_result1 = service_->MountSegment(segment1, client_id);
-    ASSERT_TRUE(mount_result1.has_value());
-
-    Segment segment2 = MakeSegment("segment2", buffer2, size);
-    segment2.te_endpoint = "[::1]:17813";
-    auto mount_result2 = service_->MountSegment(segment2, client_id);
-    ASSERT_TRUE(mount_result2.has_value());
-
-    std::vector<UUID> client_ids = {client_id};
-    auto query_result = service_->BatchQueryIp(client_ids);
-    ASSERT_TRUE(query_result.has_value());
-
-    const auto& results = query_result.value();
-    auto it = results.find(client_id);
-    ASSERT_NE(it, results.end());
-
-    const auto& ip_addresses = it->second;
-    ASSERT_EQ(2u, ip_addresses.size());
-
-    std::unordered_set<std::string> ip_set(ip_addresses.begin(),
-                                           ip_addresses.end());
-    EXPECT_NE(ip_set.find("192.168.1.1"), ip_set.end());
-    EXPECT_NE(ip_set.find("::1"), ip_set.end());
-}
-
-TEST_F(MasterServiceTest, PutStartExpiringTest) {
-    // Reset storage space metrics.
-    MasterMetricManager::instance().reset_allocated_mem_size();
-    MasterMetricManager::instance().reset_total_mem_capacity();
-
-    MasterServiceConfig master_config;
-    master_config.put_start_discard_timeout_sec = 3;
-    master_config.put_start_release_timeout_sec = 5;
-    std::unique_ptr<MasterService> service_(new MasterService(master_config));
-
-    constexpr size_t kReplicaCnt = 3;
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-
-    // Mount 3 segments.
-    std::vector<MountedSegmentContext> contexts;
-    contexts.reserve(kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; ++i) {
-        auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-        contexts.push_back(context);
-    }
-
-    // The client_id used to put objects.
-    auto client_id = generate_uuid();
-    std::string key_1 = "test_key_1", key_2 = "test_key_2";
-    uint64_t value_length = 6 * 1024 * 1024;  // 6MB
-    uint64_t slice_length = value_length;
-    ReplicateConfig config;
-    config.replica_num = kReplicaCnt;
-
-    // Put key_1, should success.
-    auto put_start_result = service_->PutStart(
-        client_id, key_1, TenantId::Default(), slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(replica_list.size(), kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; i++) {
-        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
-    }
-
-    // Put key_1 again, should fail because the key exists.
-    put_start_result = service_->PutStart(client_id, key_1, TenantId::Default(),
-                                          slice_length, config);
-    EXPECT_FALSE(put_start_result.has_value());
-    EXPECT_EQ(put_start_result.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
-
-    // Wait for a while until the put-start expired.
-    for (size_t i = 0; i <= master_config.put_start_discard_timeout_sec; i++) {
-        for (auto& context : contexts) {
-            auto result = service_->Ping(context.client_id);
-            EXPECT_TRUE(result.has_value());
-        }
-        std::this_thread::sleep_for(std::chrono::seconds(1));
-    }
-
-    // Put key_1 again, should success because the old one has expired and will
-    // be discarded by this put.
-    put_start_result = service_->PutStart(client_id, key_1, TenantId::Default(),
-                                          slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(replica_list.size(), kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; i++) {
-        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
-    }
-
-    // Complete key_1.
-    auto put_end_result = service_->PutEnd(
-        client_id, key_1, TenantId::Default(), ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-
-    // Protect key_1 from eviction.
-    auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
-    EXPECT_TRUE(get_result.has_value());
-
-    // Put key_2, should fail because the key_1 occupied 12MB (6MB processing,
-    // 6MB discarded but not yet released) on each segment.
-    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
-                                          slice_length, config);
-    EXPECT_FALSE(put_start_result.has_value());
-    EXPECT_EQ(put_start_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
-
-    // Wait for a while until the discarded replicas are released.
-    for (size_t i = 0; i <= master_config.put_start_release_timeout_sec -
-                                master_config.put_start_discard_timeout_sec;
-         i++) {
-        for (auto& context : contexts) {
-            auto result = service_->Ping(context.client_id);
-            EXPECT_TRUE(result.has_value());
-        }
-        // Protect key_1 from eviction.
-        auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
-        EXPECT_TRUE(get_result.has_value());
-        std::this_thread::sleep_for(std::chrono::seconds(1));
-    }
-
-    // Put key_2 again, should success because the discarded replica has been
-    // released.
-    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
-                                          slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(replica_list.size(), kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; i++) {
-        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
-    }
-
-    // Wait for a while until key_2 can be discarded and released.
-    for (size_t i = 0; i <= master_config.put_start_release_timeout_sec; i++) {
-        for (auto& context : contexts) {
-            auto result = service_->Ping(context.client_id);
-            EXPECT_TRUE(result.has_value());
-        }
-        // Protect key_1 from eviction.
-        auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
-        EXPECT_TRUE(get_result.has_value());
-        std::this_thread::sleep_for(std::chrono::seconds(1));
-    }
-
-    // Put key_2 again, should fail because eviction has not been triggered. And
-    // this PutStart should trigger the eviction. Only BatchEvict moves the
-    // eviction attempt counter, so take the baseline before the trigger: the
-    // eviction thread polls every 10 ms, and sampling after the failing
-    // PutStart could race a completed BatchEvict and wait for a second one
-    // that never comes.
-    const int64_t eviction_attempts_before =
-        MasterMetricManager::instance().get_mem_eviction_attempts();
-    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
-                                          slice_length, config);
-    EXPECT_FALSE(put_start_result.has_value());
-    EXPECT_EQ(put_start_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
-
-    // The failed PutStart above sets need_mem_eviction_, and the eviction
-    // thread answers with an asynchronous BatchEvict. Polling PutStart for up
-    // to put_start_release_timeout_sec cannot tell that path apart from the
-    // periodic DiscardExpiredProcessingReplicas fallback, which releases the
-    // same replicas on the same 5 s scale and would pass the test without
-    // exercising the immediate eviction, and the periodic path never touches
-    // the attempt counter.
-    WaitUntil([&] {
-        return MasterMetricManager::instance().get_mem_eviction_attempts() >
-               eviction_attempts_before;
-    });
-    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
-                                          slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value())
-        << toString(put_start_result.error());
-    replica_list = put_start_result.value();
-    EXPECT_EQ(replica_list.size(), kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; i++) {
-        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
-    }
-
-    // Complete key_2.
-    put_end_result = service_->PutEnd(client_id, key_2, TenantId::Default(),
-                                      ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-}
-
-TEST_F(MasterServiceTest, ConcurrentMountLocalDiskSegment) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    std::unique_ptr<MasterService> service_(new MasterService(config));
-
-    constexpr size_t num_threads = 100;
-    std::vector<std::thread> threads;
-    std::atomic<int> success_count{0};
-
-    // Launch multiple threads to mount local disk segments concurrently
-    for (size_t i = 0; i < num_threads; i++) {
-        threads.emplace_back([&service_, i, &success_count, this]() {
-            UUID client_id = generate_uuid();
-            auto mount_result =
-                service_->MountLocalDiskSegment(client_id, true);
-            ASSERT_TRUE(mount_result.has_value());
-            ++success_count;
-        });
-    }
-
-    // Wait for all threads to complete
-    for (auto& thread : threads) {
-        thread.join();
-    }
-
-    // Verify that some mount/unmount operations succeeded
-    EXPECT_GT(success_count, 0);
-}
-
-TEST_F(MasterServiceTest, OffloadObjectHeartbeat) {
-    constexpr size_t key_cnt = 3000;
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    std::unique_ptr<MasterService> service_(new MasterService(config));
-    UUID client_id = generate_uuid();
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t size = 1024 * 1024 * 16;
-    auto segment = MakeSegment("segment", buffer, size);
-    auto mount_result = service_->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-    auto mount_local_disk_result =
-        service_->MountLocalDiskSegment(client_id, false);
-    ASSERT_TRUE(mount_local_disk_result.has_value());
-    for (size_t i = 0; i < key_cnt; i++) {
-        auto key = GenerateKeyForSegment(client_id, service_, segment.name);
-    }
-    auto res = service_->OffloadObjectHeartbeat(client_id, true);
-    if (!res) {
-        LOG(ERROR) << "OffloadObjectHeartbeat failed with error: "
-                   << res.error();
-        ASSERT_TRUE(res);
-    }
-    ASSERT_EQ(res->size(), 0);
-    std::vector<std::string> keys;
-    for (size_t i = 0; i < key_cnt; i++) {
-        auto key = GenerateKeyForSegment(client_id, service_, segment.name);
-        keys.push_back(key);
-    }
-    res = service_->OffloadObjectHeartbeat(client_id, true);
-    if (!res) {
-        LOG(ERROR) << "OffloadObjectHeartbeat failed with error: "
-                   << res.error();
-        ASSERT_TRUE(res);
-    }
-    ASSERT_EQ(res->size(), keys.size());
-    for (auto& key : keys) {
-        auto it = std::find_if(
-            res->begin(), res->end(),
-            [&key](const OffloadTaskItem& task) { return task.key == key; });
-        ASSERT_TRUE(it != res->end());
-        ASSERT_EQ(it->size, 1024);
-    }
-
-    keys.clear();
-    for (size_t i = 0; i < key_cnt; i++) {
-        auto key = GenerateKeyForSegment(client_id, service_, segment.name);
-        keys.push_back(key);
-    }
-    res = service_->OffloadObjectHeartbeat(client_id, true);
-    if (!res) {
-        LOG(ERROR) << "OffloadObjectHeartbeat failed with error: "
-                   << res.error();
-        ASSERT_TRUE(res);
-    }
-    ASSERT_EQ(res->size(), keys.size());
-    for (auto& key : keys) {
-        auto it = std::find_if(
-            res->begin(), res->end(),
-            [&key](const OffloadTaskItem& task) { return task.key == key; });
-        ASSERT_TRUE(it != res->end());
-        ASSERT_EQ(it->size, 1024);
-    }
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearAllSegments) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Create multiple objects
-    std::vector<std::string> keys;
-    const int num_objects = 5;
-    for (int i = 0; i < num_objects; ++i) {
-        std::string key = "batch_clear_key_" + std::to_string(i);
-        keys.push_back(key);
-        uint64_t value_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), value_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-    }
-
-    // Verify objects exist
-    for (const auto& key : keys) {
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_TRUE(exist_result.value());
-    }
-
-    // Wait for lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 10));
-
-    // Clear all replicas (empty segment_name means clear all segments)
-    auto clear_result = service_->BatchReplicaClear(keys, client_id, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    const auto& cleared_keys = clear_result.value();
-    ASSERT_EQ(num_objects, cleared_keys.size()) << "All keys should be cleared";
-
-    // Verify objects are removed
-    for (const auto& key : keys) {
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_FALSE(exist_result.value())
-            << "Key " << key << " should be removed";
-    }
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearSpecificSegment) {
-    // 1. Setup: Control the lease time
-    const uint64_t kv_lease_ttl = 200;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
-
-    // 2. Setup: Mount segments
-    Segment segment1 = MakeSegment("segment1", 0x300000000, 1024 * 1024 * 16);
-    Segment segment2 = MakeSegment("segment2", 0x400000000, 1024 * 1024 * 16);
-    ASSERT_TRUE(service_->MountSegment(segment1, client_id).has_value());
-    ASSERT_TRUE(service_->MountSegment(segment2, client_id).has_value());
-
-    // 3. Setup: Create the object on segment1 using preferred_segment
-    std::string key = "segment_specific_key";
-    std::string segment_name = segment1.name;
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment =
-        segment_name;  // Ensure object is placed on segment1
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // 4. Wait for lease to expire and verify it's actually expired
-    // PutEnd calls GrantLease(0, ...) which sets lease_timeout to now.
-    // Due to clock precision and timing, we need to ensure the lease is
-    // actually expired before calling BatchReplicaClear.
-    // Use a small delay and then poll to ensure lease is expired.
-    std::this_thread::sleep_for(std::chrono::milliseconds(10));
-
-    // Poll until lease is expired (with timeout to avoid infinite loop)
-    const auto timeout = std::chrono::seconds(5);
-    const auto start_time = std::chrono::steady_clock::now();
-    bool lease_expired = false;
-    std::vector<std::string> keys = {key};
-    tl::expected<std::vector<std::string>, ErrorCode> clear_result;
-
-    while (std::chrono::steady_clock::now() - start_time < timeout) {
-        // Try to clear - if it succeeds, lease is expired
-        clear_result =
-            service_->BatchReplicaClear(keys, client_id, segment_name);
-        ASSERT_TRUE(clear_result.has_value());
-
-        if (clear_result.value().size() == 1) {
-            lease_expired = true;
-            break;
-        }
-
-        // Lease not expired yet, wait a bit and retry
-        std::this_thread::sleep_for(std::chrono::milliseconds(50));
-    }
-
-    ASSERT_TRUE(lease_expired) << "Lease did not expire within timeout period";
-
-    // 5. Verify the key was cleared
-    const auto& cleared_keys = clear_result.value();
-    ASSERT_EQ(1u, cleared_keys.size()) << "Key should be cleared";
-
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    ASSERT_FALSE(exist_result.value())
-        << "Key should be removed after being cleared.";
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearWithLeaseActive) {
-    const uint64_t kv_lease_ttl = 2000;  // Long lease
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Create an object
-    std::string key = "lease_active_key";
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Grant a lease by calling GetReplicaList (similar to normal usage)
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(get_result.has_value());
-
-    // Try to clear immediately (lease should still be active)
-    std::vector<std::string> keys = {key};
-    auto clear_result = service_->BatchReplicaClear(keys, client_id, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should return empty list because lease is still active
-    const auto& cleared_keys = clear_result.value();
-    EXPECT_TRUE(cleared_keys.empty())
-        << "No keys should be cleared when lease is active";
-
-    // Verify object still exists
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    ASSERT_TRUE(exist_result.value()) << "Key should still exist";
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearWithDifferentClientId) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id1 = generate_uuid();
-    const UUID client_id2 = generate_uuid();
-
-    // Create an object with client_id1
-    std::string key = "client_specific_key";
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id1, key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id1, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Wait for lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 10));
-
-    // Try to clear with different client_id
-    std::vector<std::string> keys = {key};
-    auto clear_result = service_->BatchReplicaClear(keys, client_id2, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should return empty list because client_id doesn't match
-    const auto& cleared_keys = clear_result.value();
-    EXPECT_TRUE(cleared_keys.empty())
-        << "No keys should be cleared for different client_id";
-
-    // Verify object still exists
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    ASSERT_TRUE(exist_result.value()) << "Key should still exist";
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearWithNonExistentKeys) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Try to clear non-existent keys
-    std::vector<std::string> keys = {"non_existent_key1", "non_existent_key2"};
-    auto clear_result = service_->BatchReplicaClear(keys, client_id, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should return empty list
-    const auto& cleared_keys = clear_result.value();
-    EXPECT_TRUE(cleared_keys.empty())
-        << "No keys should be cleared for non-existent keys";
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearWithEmptyKeys) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Try to clear empty keys list
-    std::vector<std::string> empty_keys;
-    auto clear_result = service_->BatchReplicaClear(empty_keys, client_id, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should return empty list
-    const auto& cleared_keys = clear_result.value();
-    EXPECT_TRUE(cleared_keys.empty())
-        << "Empty keys list should return empty result";
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearWithEmptyStringKeys) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Create a valid object
-    std::string valid_key = "valid_key";
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, valid_key, TenantId::Default(), value_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(
-        client_id, valid_key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Wait for lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 10));
-
-    // Try to clear with empty string keys mixed with valid keys
-    std::vector<std::string> keys = {"", valid_key, "", "another_empty"};
-    auto clear_result = service_->BatchReplicaClear(keys, client_id, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should only clear the valid key, skip empty strings
-    const auto& cleared_keys = clear_result.value();
-    ASSERT_EQ(1u, cleared_keys.size()) << "Only valid key should be cleared";
-    EXPECT_EQ(valid_key, cleared_keys[0]);
-}
-
-TEST_F(MasterServiceTest, BatchReplicaClearMixedScenario) {
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id1 = generate_uuid();
-    const UUID client_id2 = generate_uuid();
-
-    // Create objects with different client_ids
-    std::string key1 = "mixed_key1";  // client_id1
-    std::string key2 = "mixed_key2";  // client_id1
-    std::string key3 = "mixed_key3";  // client_id2
-
-    uint64_t value_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Create key1 and key2 with client_id1
-    auto put_start1 = service_->PutStart(client_id1, key1, TenantId::Default(),
-                                         value_length, config);
-    ASSERT_TRUE(put_start1.has_value());
-    auto put_end1 = service_->PutEnd(client_id1, key1, TenantId::Default(),
-                                     ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end1.has_value());
-
-    auto put_start2 = service_->PutStart(client_id1, key2, TenantId::Default(),
-                                         value_length, config);
-    ASSERT_TRUE(put_start2.has_value());
-    auto put_end2 = service_->PutEnd(client_id1, key2, TenantId::Default(),
-                                     ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end2.has_value());
-
-    // Create key3 with client_id2
-    auto put_start3 = service_->PutStart(client_id2, key3, TenantId::Default(),
-                                         value_length, config);
-    ASSERT_TRUE(put_start3.has_value());
-    auto put_end3 = service_->PutEnd(client_id2, key3, TenantId::Default(),
-                                     ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end3.has_value());
-
-    // Wait for lease to expire
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 10));
-
-    // Try to clear with mixed keys (some belong to client_id1, some to
-    // client_id2)
-    std::vector<std::string> keys = {key1, key2, key3, "non_existent", ""};
-    auto clear_result = service_->BatchReplicaClear(keys, client_id1, "");
-    ASSERT_TRUE(clear_result.has_value());
-
-    // Should only clear key1 and key2 (belonging to client_id1)
-    const auto& cleared_keys = clear_result.value();
-    ASSERT_EQ(2u, cleared_keys.size())
-        << "Only keys belonging to client_id1 should be cleared";
-
-    // Verify key1 and key2 are cleared
-    auto exist1 = service_->ExistKey(key1, TenantId::Default());
-    ASSERT_TRUE(exist1.has_value());
-    ASSERT_FALSE(exist1.value()) << "key1 should be cleared";
-
-    auto exist2 = service_->ExistKey(key2, TenantId::Default());
-    ASSERT_TRUE(exist2.has_value());
-    ASSERT_FALSE(exist2.value()) << "key2 should be cleared";
-
-    // Verify key3 still exists (different client_id)
-    auto exist3 = service_->ExistKey(key3, TenantId::Default());
-    ASSERT_TRUE(exist3.has_value());
-    ASSERT_TRUE(exist3.value())
-        << "key3 should still exist (different client_id)";
-}
-
-TEST_F(MasterServiceTest, CreateCopyTaskTest) {
-    // Reset storage space metrics.
-    MasterMetricManager::instance().reset_allocated_mem_size();
-    MasterMetricManager::instance().reset_total_mem_capacity();
-
-    // Create MasterService
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 3 segments.
-    constexpr size_t kReplicaCnt = 3;
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    std::vector<MountedSegmentContext> contexts;
-    contexts.reserve(kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; ++i) {
-        const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-        contexts.push_back(context);
-    }
-
-    // The client putting the object to segment_0
-    auto client_id = generate_uuid();
-    std::string key1 = "test_key_1";
-    uint64_t value_length = 6 * 1024 * 1024;  // 6MB
-    uint64_t slice_length = value_length;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-    auto put_start_result = service_->PutStart(
-        client_id, key1, TenantId::Default(), slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key1, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-
-    // Copy key1 to "segment_1" and "segment_2"
-    auto copy_result = service_->CreateCopyTask(key1, TenantId::Default(),
-                                                {"segment_1", "segment_2"});
-    EXPECT_TRUE(copy_result.has_value());
-
-    // verify the copy task is created and assigned to the client who executed
-    // the copy
-    auto task = service_->QueryTask(copy_result.value());
-    EXPECT_TRUE(task.has_value());
-    EXPECT_EQ(TaskType::REPLICA_COPY, task.value().type);
-    EXPECT_EQ(contexts[0].client_id, task.value().assigned_client);
-
-    // Copy with empty targets should fail
-    auto copy_result1 = service_->CreateCopyTask(key1, TenantId::Default(), {});
-    EXPECT_FALSE(copy_result1.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, copy_result1.error());
-
-    // Copy not exist key should fail
-    auto copy_result2 = service_->CreateCopyTask(
-        "not_exist_key", TenantId::Default(), {"segment_1"});
-    EXPECT_FALSE(copy_result2.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, copy_result2.error());
-
-    // Copy to segment that not mounted should fail
-    auto copy_result3 = service_->CreateCopyTask(key1, TenantId::Default(),
-                                                 {"not_mounted_segment"});
-    EXPECT_FALSE(copy_result3.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, copy_result3.error());
-}
-
-TEST_F(MasterServiceTest, CreateMoveTaskTest) {
-    // Reset storage space metrics.
-    MasterMetricManager::instance().reset_allocated_mem_size();
-    MasterMetricManager::instance().reset_total_mem_capacity();
-
-    // Create MasterService
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 3 segments.
-    constexpr size_t kReplicaCnt = 3;
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    std::vector<MountedSegmentContext> contexts;
-    contexts.reserve(kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; ++i) {
-        const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-        contexts.push_back(context);
-    }
-
-    // The client putting the object to segment_0
-    auto client_id = generate_uuid();
-    std::string key1 = "test_key_1";
-    uint64_t value_length = 6 * 1024 * 1024;  // 6MB
-    uint64_t slice_length = value_length;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-    auto put_start_result = service_->PutStart(
-        client_id, key1, TenantId::Default(), slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key1, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-
-    // Move key1 from "segment_0" to "segment_1"
-    auto move_result = service_->CreateMoveTask(key1, TenantId::Default(),
-                                                "segment_0", "segment_1");
-    EXPECT_TRUE(move_result.has_value());
-
-    // Verify the move task is created and assigned to the client owning the
-    // source segment
-    auto task = service_->QueryTask(move_result.value());
-    EXPECT_TRUE(task.has_value());
-    EXPECT_EQ(TaskType::REPLICA_MOVE, task.value().type);
-    EXPECT_EQ(contexts[0].client_id, task.value().assigned_client);
-
-    // Move non-existent key should fail
-    auto move_result1 = service_->CreateMoveTask(
-        "not_exist_key", TenantId::Default(), "segment_0", "segment_1");
-    EXPECT_FALSE(move_result1.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, move_result1.error());
-
-    // Move to segment that is same as source should fail
-    auto move_result_same = service_->CreateMoveTask(key1, TenantId::Default(),
-                                                     "segment_1", "segment_1");
-    EXPECT_FALSE(move_result_same.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_result_same.error());
-
-    // Move to segment that is not mounted should fail
-    auto move_result2 = service_->CreateMoveTask(
-        key1, TenantId::Default(), "segment_0", "not_mounted_segment");
-    EXPECT_FALSE(move_result2.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_result2.error());
-
-    // Move from segment that does not have the replica should fail
-    auto move_result3 = service_->CreateMoveTask(key1, TenantId::Default(),
-                                                 "segment_2", "segment_1");
-    EXPECT_FALSE(move_result3.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_result3.error());
-
-    // Move from segment that is not mounted should fail
-    auto move_result4 = service_->CreateMoveTask(
-        key1, TenantId::Default(), "not_mounted_segment", "segment_1");
-    EXPECT_FALSE(move_result4.has_value());
-    EXPECT_EQ(ErrorCode::INVALID_PARAMS, move_result4.error());
-}
-
-TEST_F(MasterServiceTest, QueryTaskTest) {
-    // Reset storage space metrics.
-    MasterMetricManager::instance().reset_allocated_mem_size();
-    MasterMetricManager::instance().reset_total_mem_capacity();
-
-    // Create MasterService
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    // Mount 3 segments.
-    constexpr size_t kReplicaCnt = 3;
-    constexpr size_t kBaseAddr = 0x300000000;
-    constexpr size_t kSegmentSize = 1024 * 1024 * 16;  // 16MB
-    std::vector<MountedSegmentContext> contexts;
-    contexts.reserve(kReplicaCnt);
-    for (size_t i = 0; i < kReplicaCnt; ++i) {
-        const auto context = PrepareSimpleSegment(
-            *service_, "segment_" + std::to_string(i),
-            kBaseAddr + static_cast<size_t>(i) * kSegmentSize, kSegmentSize);
-        contexts.push_back(context);
-    }
-
-    // The client putting the object to segment_0
-    auto client_id = generate_uuid();
-    std::string key1 = "test_key_1";
-    uint64_t value_length = 6 * 1024 * 1024;  // 6MB
-    uint64_t slice_length = value_length;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-    auto put_start_result = service_->PutStart(
-        client_id, key1, TenantId::Default(), slice_length, config);
-    EXPECT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key1, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    EXPECT_TRUE(put_end_result.has_value());
-
-    // Move key1 from "segment_0" to "segment_1"
-    auto move_result = service_->CreateMoveTask(key1, TenantId::Default(),
-                                                "segment_0", "segment_1");
-    EXPECT_TRUE(move_result.has_value());
-
-    // Query non-existent task should fail
-    auto query_result = service_->QueryTask(UUID{0, 0});
-    EXPECT_FALSE(query_result.has_value());
-    EXPECT_EQ(ErrorCode::TASK_NOT_FOUND, query_result.error());
-
-    // Query the move task
-    auto query_result_move = service_->QueryTask(move_result.value());
-    EXPECT_TRUE(query_result_move.has_value());
-    EXPECT_EQ(TaskType::REPLICA_MOVE, query_result_move.value().type);
-    EXPECT_EQ(contexts[0].client_id, query_result_move.value().assigned_client);
-}
-
-TEST_F(MasterServiceTest, FetchTasksEmptyWhenNoTasks) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-
-    auto fetch = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetch.has_value());
-    EXPECT_TRUE(fetch->empty());
-}
-
-TEST_F(MasterServiceTest, FetchTasksReturnsAssignedTasksOnlyAndDrainsQueue) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    const auto ctx1 = PrepareSimpleSegment(*service_, "segment_1", 0x400000000,
-                                           kDefaultSegmentSize);
-    // Put an object with its (only) replica on segment_0 so Copy/Move
-    // assignment is deterministic.
-    const UUID put_client_id = generate_uuid();
-    const std::string key = "fetch_tasks_key_0";
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    ASSERT_TRUE(service_
-                    ->PutStart(put_client_id, key, TenantId::Default(),
-                               /*slice_length=*/1024, config)
-                    .has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(put_client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
-
-    // Create two tasks; both should be assigned to the client owning source
-    // segment_0.
-    auto copy_task_id =
-        service_->CreateCopyTask(key, TenantId::Default(), {"segment_1"});
-    ASSERT_TRUE(copy_task_id.has_value());
-
-    auto move_task_id = service_->CreateMoveTask(key, TenantId::Default(),
-                                                 "segment_0", "segment_1");
-    ASSERT_TRUE(move_task_id.has_value());
-
-    // Fetch from client_0 should get both tasks (order not guaranteed).
-    auto fetch0 = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetch0.has_value());
-    ASSERT_EQ(fetch0->size(), 2u);
-
-    std::vector<UUID> fetched_ids;
-    fetched_ids.reserve(fetch0->size());
-    for (const auto& a : *fetch0) {
-        fetched_ids.push_back(
-            a.id);  // TaskAssignment is expected to carry id/type/payload
-    }
-
-    EXPECT_NE(
-        std::find(fetched_ids.begin(), fetched_ids.end(), copy_task_id.value()),
-        fetched_ids.end());
-    EXPECT_NE(
-        std::find(fetched_ids.begin(), fetched_ids.end(), move_task_id.value()),
-        fetched_ids.end());
-
-    // Fetch from client_1 should return empty (no tasks assigned to it).
-    auto fetch1 = service_->FetchTasks(ctx1.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetch1.has_value());
-    EXPECT_TRUE(fetch1->empty());
-
-    // Fetch again from client_0 should be empty if pop_tasks drains pending
-    // queue.
-    auto fetch0_again = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetch0_again.has_value());
-    EXPECT_TRUE(fetch0_again->empty());
-}
-
-TEST_F(MasterServiceTest, TenantTasksCarryTenantInPayload) {
-    const TenantId tenant_id("tenant_for_async_task");
-    auto service = std::make_unique<MasterService>(
-        MakeStrictTenantConfig({tenant_id.value()}));
-    const auto ctx0 = PrepareSimpleSegment(*service, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    const std::string key = "tenant_task_key";
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    ASSERT_TRUE(service
-                    ->PutStart(put_client_id, key, tenant_id,
-                               /*slice_length=*/1024, config)
-                    .has_value());
-    ASSERT_TRUE(
-        service->PutEnd(put_client_id, key, tenant_id, ReplicaType::MEMORY)
-            .has_value());
-
-    auto copy_task_id = service->CreateCopyTask(key, tenant_id, {"segment_1"});
-    ASSERT_TRUE(copy_task_id.has_value());
-    auto move_task_id =
-        service->CreateMoveTask(key, tenant_id, "segment_0", "segment_1");
-    ASSERT_TRUE(move_task_id.has_value());
-
-    auto fetched = service->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetched.has_value());
-    ASSERT_EQ(fetched->size(), 2u);
-
-    bool saw_copy = false;
-    bool saw_move = false;
-    for (const auto& assignment : *fetched) {
-        if (assignment.id == copy_task_id.value()) {
-            ReplicaCopyPayload payload;
-            struct_json::from_json(payload, assignment.payload);
-            EXPECT_EQ(payload.tenant_id, tenant_id.value());
-            EXPECT_EQ(payload.key, key);
-            saw_copy = true;
-        } else if (assignment.id == move_task_id.value()) {
-            ReplicaMovePayload payload;
-            struct_json::from_json(payload, assignment.payload);
-            EXPECT_EQ(payload.tenant_id, tenant_id.value());
-            EXPECT_EQ(payload.key, key);
-            saw_move = true;
-        }
-    }
-    EXPECT_TRUE(saw_copy);
-    EXPECT_TRUE(saw_move);
-}
-
-TEST_F(MasterServiceTest, LegacyTaskPayloadDefaultsTenant) {
-    ReplicaCopyPayload copy_payload;
-    struct_json::from_json(
-        copy_payload,
-        R"({"key":"legacy_copy_key","source":"segment_0","targets":["segment_1"]})");
-    EXPECT_EQ(copy_payload.tenant_id, TenantId::kDefaultValue);
-    EXPECT_EQ(copy_payload.key, "legacy_copy_key");
-    EXPECT_EQ(copy_payload.source, "segment_0");
-    ASSERT_EQ(copy_payload.targets.size(), 1u);
-    EXPECT_EQ(copy_payload.targets[0], "segment_1");
-
-    ReplicaMovePayload move_payload;
-    struct_json::from_json(
-        move_payload,
-        R"({"key":"legacy_move_key","source":"segment_0","target":"segment_1"})");
-    EXPECT_EQ(move_payload.tenant_id, TenantId::kDefaultValue);
-    EXPECT_EQ(move_payload.key, "legacy_move_key");
-    EXPECT_EQ(move_payload.source, "segment_0");
-    EXPECT_EQ(move_payload.target, "segment_1");
-}
-
-TEST_F(MasterServiceTest, FetchTasksRespectsBatchSize) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    const std::string key = "fetch_tasks_key_1";
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    ASSERT_TRUE(service_
-                    ->PutStart(put_client_id, key, TenantId::Default(),
-                               /*slice_length=*/1024, config)
-                    .has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(put_client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
-
-    auto t1 = service_->CreateCopyTask(key, TenantId::Default(), {"segment_1"});
-    ASSERT_TRUE(t1.has_value());
-    auto t2 = service_->CreateMoveTask(key, TenantId::Default(), "segment_0",
-                                       "segment_1");
-    ASSERT_TRUE(t2.has_value());
-
-    auto fetch_first = service_->FetchTasks(ctx0.client_id, /*batch_size=*/1);
-    ASSERT_TRUE(fetch_first.has_value());
-    ASSERT_EQ(fetch_first->size(), 1u);
-
-    auto fetch_second = service_->FetchTasks(ctx0.client_id, /*batch_size=*/1);
-    ASSERT_TRUE(fetch_second.has_value());
-    ASSERT_EQ(fetch_second->size(), 1u);
-
-    // Combined should contain both task ids (order not guaranteed).
-    std::vector<UUID> ids;
-    ids.push_back(fetch_first->at(0).id);
-    ids.push_back(fetch_second->at(0).id);
-
-    EXPECT_NE(std::find(ids.begin(), ids.end(), t1.value()), ids.end());
-    EXPECT_NE(std::find(ids.begin(), ids.end(), t2.value()), ids.end());
-
-    auto fetch_third = service_->FetchTasks(ctx0.client_id, /*batch_size=*/1);
-    ASSERT_TRUE(fetch_third.has_value());
-    EXPECT_TRUE(fetch_third->empty());
-}
-
-TEST_F(MasterServiceTest, UpdateTaskSuccessFlow) {
-    auto service_ = std::make_unique<MasterService>();
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    // Put an object with its (only) replica on segment_0 so task assignment is
-    // deterministic.
-    const UUID put_client_id = generate_uuid();
-    const std::string key = "update_task_key_success";
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    ASSERT_TRUE(service_
-                    ->PutStart(put_client_id, key, TenantId::Default(),
-                               /*slice_length=*/1024, config)
-                    .has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(put_client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
-
-    // Create a task assigned to client owning segment_0.
-    auto task_id_res =
-        service_->CreateCopyTask(key, TenantId::Default(), {"segment_1"});
-    ASSERT_TRUE(task_id_res.has_value());
-    const UUID task_id = task_id_res.value();
-
-    // Poll once so the task transitions to PROCESSING (typical semantics).
-    auto fetched = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetched.has_value());
-    ASSERT_EQ(fetched->size(), 1u);
-    EXPECT_EQ(fetched->at(0).id, task_id);
-
-    // Update task to SUCCESS.
-    TaskCompleteRequest req{};
-    req.id = task_id;
-    req.status = TaskStatus::SUCCESS;
-    req.message = "done";
-
-    auto update_res = service_->MarkTaskToComplete(ctx0.client_id, req);
-    ASSERT_TRUE(update_res.has_value()) << "MarkTaskToComplete failed";
-
-    // Verify task state via QueryTask.
-    auto qt = service_->QueryTask(task_id);
-    ASSERT_TRUE(qt.has_value());
-    EXPECT_EQ(qt->id, task_id);
-    EXPECT_EQ(qt->status, TaskStatus::SUCCESS);
-    EXPECT_EQ(qt->assigned_client, ctx0.client_id);
-    EXPECT_EQ(qt->message, "done");
-
-    // Queue should be drained for that client.
-    auto fetched_again =
-        service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetched_again.has_value());
-    EXPECT_TRUE(fetched_again->empty());
-}
-
-TEST_F(MasterServiceTest, UpdateTaskRejectsWrongClient) {
-    auto service_ = std::make_unique<MasterService>();
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    const auto ctx1 = PrepareSimpleSegment(*service_, "segment_1", 0x400000000,
-                                           kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    const std::string key = "update_task_wrong_client";
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    ASSERT_TRUE(service_
-                    ->PutStart(put_client_id, key, TenantId::Default(),
-                               /*slice_length=*/1024, config)
-                    .has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(put_client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
-
-    auto task_id_res = service_->CreateMoveTask(key, TenantId::Default(),
-                                                "segment_0", "segment_1");
-    ASSERT_TRUE(task_id_res.has_value());
-    const UUID task_id = task_id_res.value();
-
-    // Poll by the correct client to take the task.
-    auto fetched = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-    ASSERT_TRUE(fetched.has_value());
-    ASSERT_EQ(fetched->size(), 1u);
-    EXPECT_EQ(fetched->at(0).id, task_id);
-
-    // Try to update with a different client id, should fail.
-    TaskCompleteRequest req{};
-    req.id = task_id;
-    req.status = TaskStatus::SUCCESS;
-    req.message = "should_not_work";
-
-    auto update_res = service_->MarkTaskToComplete(ctx1.client_id, req);
-    ASSERT_FALSE(update_res.has_value());
-    EXPECT_EQ(update_res.error(), ErrorCode::ILLEGAL_CLIENT);
-}
-
-TEST_F(MasterServiceTest, UpdateTaskNotFound) {
-    auto service_ = std::make_unique<MasterService>();
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-
-    TaskCompleteRequest req{};
-    req.id = generate_uuid();  // non-existent task id
-    req.status = TaskStatus::FAILED;
-    req.message = "not_found";
-
-    auto update_res = service_->MarkTaskToComplete(ctx0.client_id, req);
-    ASSERT_FALSE(update_res.has_value());
-    EXPECT_EQ(update_res.error(), ErrorCode::TASK_NOT_FOUND);
-}
-
-TEST_F(MasterServiceTest,
-       CreateDrainJobMarksSegmentDrainingAndSkipsAllocation) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    CreateDrainJobRequest request;
-    request.segments = {"segment_0"};
-    request.target_segments = {"segment_1"};
-    request.max_concurrency = 1;
-
-    auto job_id = service_->CreateDrainJob(request);
-    ASSERT_TRUE(job_id.has_value());
-
-    auto segment_status = service_->QuerySegmentStatus("segment_0");
-    ASSERT_TRUE(segment_status.has_value());
-    EXPECT_EQ(segment_status.value(), SegmentStatus::DRAINING);
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_0";
-
-    auto put_result =
-        service_->PutStart(ctx0.client_id, "drain_skip_allocation_key",
-                           TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_result.has_value());
-    ASSERT_EQ(put_result->size(), 1u);
-    EXPECT_EQ(put_result->front()
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              "segment_1");
-    ASSERT_TRUE(service_
-                    ->PutEnd(ctx0.client_id, "drain_skip_allocation_key",
-                             TenantId::Default(), ReplicaType::MEMORY)
-                    .has_value());
-}
-
-TEST_F(MasterServiceTest, DrainJobSchedulesMoveTaskAndConvergesToDrained) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    const std::string key =
-        PutObjectOnSegment(*service_, put_client_id, "segment_0");
-
-    CreateDrainJobRequest request;
-    request.segments = {"segment_0"};
-    request.target_segments = {"segment_1"};
-    request.max_concurrency = 1;
-
-    auto job_id = service_->CreateDrainJob(request);
-    ASSERT_TRUE(job_id.has_value());
-
-    WaitUntil(
-        [&] { return ExecutePendingMoveTasks(*service_, ctx0.client_id); });
-
-    WaitUntil([&] {
-        auto query = service_->QueryDrainJob(job_id.value());
-        return query.has_value() && query->status == JobStatus::SUCCEEDED;
-    });
-
-    auto query = service_->QueryDrainJob(job_id.value());
-    ASSERT_TRUE(query.has_value());
-    EXPECT_EQ(query->status, JobStatus::SUCCEEDED);
-    EXPECT_EQ(query->active_units, 0u);
-    EXPECT_GE(query->succeeded_units, 1u);
-
-    auto segment_status = service_->QuerySegmentStatus("segment_0");
-    ASSERT_TRUE(segment_status.has_value());
-    EXPECT_EQ(segment_status.value(), SegmentStatus::DRAINED);
-
-    auto replicas = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(replicas.has_value());
-    std::unordered_set<std::string> segment_names;
-    for (const auto& replica : replicas->replicas) {
-        segment_names.insert(replica.get_memory_descriptor()
-                                 .buffer_descriptor.transport_endpoint_);
-    }
-    EXPECT_TRUE(segment_names.contains("segment_1"));
-    EXPECT_FALSE(segment_names.contains("segment_0"));
-}
-
-TEST_F(MasterServiceTest, CancelDrainJobRestoresSegmentStatus) {
-    auto service_ = std::make_unique<MasterService>();
-
-    [[maybe_unused]] const auto ctx0 = PrepareSimpleSegment(
-        *service_, "segment_0", 0x300000000, kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    CreateDrainJobRequest request;
-    request.segments = {"segment_0"};
-    request.target_segments = {"segment_1"};
-    request.max_concurrency = 1;
-
-    auto job_id = service_->CreateDrainJob(request);
-    ASSERT_TRUE(job_id.has_value());
-
-    auto draining_status = service_->QuerySegmentStatus("segment_0");
-    ASSERT_TRUE(draining_status.has_value());
-    EXPECT_EQ(draining_status.value(), SegmentStatus::DRAINING);
-
-    auto cancel_result = service_->CancelDrainJob(job_id.value());
-    ASSERT_TRUE(cancel_result.has_value());
-
-    auto job = service_->QueryDrainJob(job_id.value());
-    ASSERT_TRUE(job.has_value());
-    EXPECT_EQ(job->status, JobStatus::CANCELED);
-
-    auto restored_status = service_->QuerySegmentStatus("segment_0");
-    ASSERT_TRUE(restored_status.has_value());
-    EXPECT_EQ(restored_status.value(), SegmentStatus::OK);
-}
-
-TEST_F(MasterServiceTest, CancelDrainJobRejectsActiveMoveTasks) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    PutObjectOnSegment(*service_, put_client_id, "segment_0");
-
-    CreateDrainJobRequest request;
-    request.segments = {"segment_0"};
-    request.target_segments = {"segment_1"};
-    request.max_concurrency = 1;
-
-    auto job_id = service_->CreateDrainJob(request);
-    ASSERT_TRUE(job_id.has_value());
-
-    WaitUntil([&] {
-        auto fetched = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
-        return fetched.has_value() && !fetched->empty();
-    });
-
-    auto cancel_result = service_->CancelDrainJob(job_id.value());
-    ASSERT_FALSE(cancel_result.has_value());
-    EXPECT_EQ(cancel_result.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
-}
-
-TEST_F(MasterServiceTest, DrainJobFailsAfterRetryBudgetExhausted) {
-    auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
-    auto service_ = std::make_unique<MasterService>(service_config);
-
-    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
-                                           kDefaultSegmentSize);
-    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
-        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
-
-    const UUID put_client_id = generate_uuid();
-    PutObjectOnSegment(*service_, put_client_id, "segment_0");
-
-    CreateDrainJobRequest request;
-    request.segments = {"segment_0"};
-    request.target_segments = {"segment_1"};
-    request.max_concurrency = 1;
-
-    auto job_id = service_->CreateDrainJob(request);
-    ASSERT_TRUE(job_id.has_value());
-
-    for (int attempt = 0; attempt < 3; ++attempt) {
-        WaitUntil(
-            [&] { return FailPendingMoveTasks(*service_, ctx0.client_id); });
-    }
-
-    WaitUntil([&] {
-        auto query = service_->QueryDrainJob(job_id.value());
-        return query.has_value() && query->status == JobStatus::FAILED;
-    });
-
-    auto query = service_->QueryDrainJob(job_id.value());
-    ASSERT_TRUE(query.has_value());
-    EXPECT_EQ(query->status, JobStatus::FAILED);
-    EXPECT_EQ(query->active_units, 0u);
-    EXPECT_GE(query->failed_units, 3u);
-
-    auto segment_status = service_->QuerySegmentStatus("segment_0");
-    ASSERT_TRUE(segment_status.has_value());
-    EXPECT_EQ(segment_status.value(), SegmentStatus::OK);
-}
-
-TEST_F(MasterServiceTest, ForceRemoveLeasedObject) {
-    // Set a long lease TTL so objects will have active leases
-    const uint64_t kv_lease_ttl = 10000;  // 10 seconds
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Put an object
-    std::string key = "leased_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    auto put_start_result = service_->PutStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(put_start_result.has_value());
-    auto put_end_result = service_->PutEnd(client_id, key, TenantId::Default(),
-                                           ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end_result.has_value());
-
-    // Verify object exists
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    ASSERT_TRUE(exist_result.value());
-
-    // Normal remove should fail because object has active lease
-    auto remove_result_no_force =
-        service_->Remove(key, TenantId::Default(), false);
-    EXPECT_FALSE(remove_result_no_force.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_LEASE, remove_result_no_force.error());
-
-    // Force remove should succeed even with active lease
-    auto remove_result_force = service_->Remove(key, TenantId::Default(), true);
-    EXPECT_TRUE(remove_result_force.has_value());
-
-    // Verify object is removed
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_NOT_FOUND, get_result.error());
-}
-
-// Test force RemoveByRegex - should bypass lease check
-TEST_F(MasterServiceTest, ForceRemoveByRegexLeasedObjects) {
-    // Set a long lease TTL so objects will have active leases
-    const uint64_t kv_lease_ttl = 10000;  // 10 seconds
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Put 5 objects and grant them active leases by reading
-    for (int i = 0; i < 5; ++i) {
-        std::string key = "force_regex_key_" + std::to_string(i);
-        uint64_t slice_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        // Grant lease by reading the object
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_TRUE(exist_result.value());
-    }
-
-    // Normal RemoveByRegex should remove 0 because all objects have active
-    // leases
-    auto remove_result_no_force = service_->RemoveByRegex(
-        "^force_regex_key_", TenantId::Default(), false);
-    ASSERT_TRUE(remove_result_no_force.has_value());
-    EXPECT_EQ(0, remove_result_no_force.value());
-
-    // All objects should still exist
-    for (int i = 0; i < 5; ++i) {
-        std::string key = "force_regex_key_" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_TRUE(exist_result.value());
-    }
-
-    // Force RemoveByRegex should remove all 5 objects
-    auto remove_result_force =
-        service_->RemoveByRegex("^force_regex_key_", TenantId::Default(), true);
-    ASSERT_TRUE(remove_result_force.has_value());
-    EXPECT_EQ(5, remove_result_force.value());
-
-    // All objects should be removed
-    for (int i = 0; i < 5; ++i) {
-        std::string key = "force_regex_key_" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_FALSE(exist_result.value());
-    }
-}
-
-// Test force RemoveAll - should bypass lease check
-TEST_F(MasterServiceTest, ForceRemoveAllLeasedObjects) {
-    // Set a long lease TTL so objects will have active leases
-    const uint64_t kv_lease_ttl = 10000;  // 10 seconds
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    // Put 10 objects and grant them active leases by reading
-    for (int i = 0; i < 10; ++i) {
-        std::string key = "force_all_key_" + std::to_string(i);
-        uint64_t slice_length = 1024;
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto put_start_result = service_->PutStart(
-            client_id, key, TenantId::Default(), slice_length, config);
-        ASSERT_TRUE(put_start_result.has_value());
-        auto put_end_result = service_->PutEnd(
-            client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-        ASSERT_TRUE(put_end_result.has_value());
-        // Grant lease by reading the object
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_TRUE(exist_result.value());
-    }
-
-    // Normal RemoveAll should remove 0 because all objects have active leases
-    EXPECT_EQ(0, service_->RemoveAll(false));
-
-    // All objects should still exist
-    for (int i = 0; i < 10; ++i) {
-        std::string key = "force_all_key_" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_TRUE(exist_result.value());
-    }
-
-    // Force RemoveAll should remove all 10 objects
-    EXPECT_EQ(10, service_->RemoveAll(true));
-
-    // All objects should be removed
-    for (int i = 0; i < 10; ++i) {
-        std::string key = "force_all_key_" + std::to_string(i);
-        auto exist_result = service_->ExistKey(key, TenantId::Default());
-        ASSERT_TRUE(exist_result.has_value());
-        ASSERT_FALSE(exist_result.value());
-    }
-}
-// ===================== Upsert Tests =====================
-
-TEST_F(MasterServiceTest, UpsertNewKey) {
-    // Case A: key does not exist — behaves like PutStart
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_new_key";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    auto upsert_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-    auto replicas = upsert_result.value();
-    EXPECT_EQ(1, replicas.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, replicas[0].status);
-
-    // During upsert, GetReplicaList should return not ready
-    auto get_result = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_result.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_result.error());
-
-    // UpsertEnd completes the operation
-    auto end_result = service_->UpsertEnd(client_id, key, TenantId::Default(),
-                                          ReplicaType::MEMORY);
-    ASSERT_TRUE(end_result.has_value());
-
-    // Verify replica is COMPLETE
-    auto final_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(final_result.has_value());
-    EXPECT_EQ(1, final_result.value().replicas.size());
-    EXPECT_EQ(ReplicaStatus::COMPLETE, final_result.value().replicas[0].status);
-}
-
-TEST_F(MasterServiceTest, UpsertSameSize) {
-    // Case B: key exists with same size — in-place update
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_same_size";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // First: PutStart + PutEnd to create the object
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto original_replicas = put_result.value();
-    auto put_end = service_->PutEnd(client_id, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // UpsertStart with same size — should reuse buffers
-    const UUID new_client_id = generate_uuid();
-    auto upsert_result = service_->UpsertStart(
-        new_client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-    auto upsert_replicas = upsert_result.value();
-    EXPECT_EQ(1, upsert_replicas.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, upsert_replicas[0].status);
-
-    // Verify same buffer address (in-place reuse)
-    EXPECT_EQ(original_replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.buffer_address_,
-              upsert_replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.buffer_address_);
-
-    // UpsertEnd with the new client_id
-    auto end_result = service_->UpsertEnd(
-        new_client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(end_result.has_value());
-
-    // Verify replica is COMPLETE again
-    auto final_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(final_result.has_value());
-    EXPECT_EQ(ReplicaStatus::COMPLETE, final_result.value().replicas[0].status);
-}
-
-TEST_F(MasterServiceTest, UpsertSameSizeRefreshesMetadata) {
-    // Case B: verify client_id and put_start_time are refreshed
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id_a = generate_uuid();
-    const UUID client_id_b = generate_uuid();
-
-    std::string key = "upsert_refresh_metadata";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Create object with client_a
-    auto put_result = service_->PutStart(client_id_a, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_id_a, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // UpsertStart with client_b
-    auto upsert_result = service_->UpsertStart(
-        client_id_b, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-
-    // UpsertEnd with client_a should fail (client_id was refreshed to client_b)
-    auto end_fail = service_->UpsertEnd(client_id_a, key, TenantId::Default(),
-                                        ReplicaType::MEMORY);
-    EXPECT_FALSE(end_fail.has_value());
-    EXPECT_EQ(ErrorCode::ILLEGAL_CLIENT, end_fail.error());
-
-    // UpsertEnd with client_b should succeed
-    auto end_ok = service_->UpsertEnd(client_id_b, key, TenantId::Default(),
-                                      ReplicaType::MEMORY);
-    ASSERT_TRUE(end_ok.has_value());
-}
-
-TEST_F(MasterServiceTest, UpsertDifferentSize) {
-    // Case C: key exists with different size — delete and reallocate
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_diff_size";
-    uint64_t original_size = 1024;
-    uint64_t new_size = 2048;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Create object with original_size
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         original_size, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto original_replicas = put_result.value();
-    auto put_end = service_->PutEnd(client_id, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // UpsertStart with different size
-    auto upsert_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), new_size, config);
-    ASSERT_TRUE(upsert_result.has_value());
-    auto new_replicas = upsert_result.value();
-    EXPECT_EQ(1, new_replicas.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, new_replicas[0].status);
-
-    // Buffer address should be different (reallocated)
-    EXPECT_NE(original_replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.buffer_address_,
-              new_replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.buffer_address_);
-
-    // UpsertEnd
-    auto end_result = service_->UpsertEnd(client_id, key, TenantId::Default(),
-                                          ReplicaType::MEMORY);
-    ASSERT_TRUE(end_result.has_value());
-
-    // Verify the object is complete
-    auto final_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(final_result.has_value());
-    EXPECT_EQ(ReplicaStatus::COMPLETE, final_result.value().replicas[0].status);
-}
-
-TEST_F(MasterServiceTest, UpsertConflictReplicationTask) {
-    // Upsert should fail if Copy is in progress
-    const uint64_t kv_lease_ttl = 50;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-
-    [[maybe_unused]] const auto ctx1 =
-        PrepareSimpleSegment(*service_, "segment_1");
-    [[maybe_unused]] const auto ctx2 =
-        PrepareSimpleSegment(*service_, "segment_2");
-    UUID client_id = generate_uuid();
-
-    std::string key = "upsert_conflict_copy";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.preferred_segment = "segment_1";
-
-    // Create object
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_id, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // Start a Copy
-    auto copy_result = service_->CopyStart(client_id, key, TenantId::Default(),
-                                           "segment_1", {"segment_2"});
-    ASSERT_TRUE(copy_result.has_value());
-
-    // UpsertStart should fail with OBJECT_HAS_REPLICATION_TASK
-    auto upsert_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    EXPECT_FALSE(upsert_result.has_value());
-    EXPECT_EQ(ErrorCode::OBJECT_HAS_REPLICATION_TASK, upsert_result.error());
-}
-
-TEST_F(MasterServiceTest, UpsertPreemptsInProgressPut) {
-    // Upsert should preempt an in-progress Put (no discard timeout needed
-    // for preemption via Upsert — Upsert always preempts immediately)
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_a = generate_uuid();
-    const UUID client_b = generate_uuid();
-
-    std::string key = "upsert_preempt";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Client A starts a Put but doesn't finish
-    auto put_result = service_->PutStart(client_a, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-
-    // Client B upserts the same key — should preempt client A
-    auto upsert_result = service_->UpsertStart(
-        client_b, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-    auto upsert_replicas = upsert_result.value();
-    EXPECT_EQ(1, upsert_replicas.size());
-    EXPECT_EQ(ReplicaStatus::PROCESSING, upsert_replicas[0].status);
-
-    // Client A's PutEnd should fail
-    auto put_end_a = service_->PutEnd(client_a, key, TenantId::Default(),
-                                      ReplicaType::MEMORY);
-    EXPECT_FALSE(put_end_a.has_value());
-
-    // Client B's UpsertEnd should succeed
-    auto upsert_end = service_->UpsertEnd(client_b, key, TenantId::Default(),
-                                          ReplicaType::MEMORY);
-    ASSERT_TRUE(upsert_end.has_value());
-
-    // Verify final state
-    auto final_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(final_result.has_value());
-    EXPECT_EQ(ReplicaStatus::COMPLETE, final_result.value().replicas[0].status);
-}
-
-TEST_F(MasterServiceTest, UpsertRevoke) {
-    // UpsertRevoke should clean up like PutRevoke
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_revoke";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // UpsertStart (Case A — new key)
-    auto upsert_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-
-    // UpsertRevoke
-    auto revoke_result = service_->UpsertRevoke(
-        client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(revoke_result.has_value());
-
-    // Key should be gone
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    EXPECT_FALSE(exist_result.value());
-}
-
-TEST_F(MasterServiceTest, UpsertInPlaceThenRevoke) {
-    // UpsertRevoke after in-place UpsertStart should clean up
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_inplace_revoke";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Create object first
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_id, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // UpsertStart in-place (same size)
-    const UUID new_client = generate_uuid();
-    auto upsert_result = service_->UpsertStart(
-        new_client, key, TenantId::Default(), slice_length, config);
-    ASSERT_TRUE(upsert_result.has_value());
-
-    // UpsertRevoke — replicas are PROCESSING, should be erased
-    auto revoke_result = service_->UpsertRevoke(
-        new_client, key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(revoke_result.has_value());
-
-    // Key should be gone (no valid replicas left)
-    auto exist_result = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    EXPECT_FALSE(exist_result.value());
-}
-
-TEST_F(MasterServiceTest, BatchUpsertStart) {
-    // Test batch upsert with a mix of new and existing keys
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Create key_1 with size 1024
-    auto put_result = service_->PutStart(client_id, "key_1",
-                                         TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_id, "key_1", TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // BatchUpsertStart: key_1 (same size), key_2 (new)
-    std::vector<std::string> keys = {"key_1", "key_2"};
-    std::vector<uint64_t> slice_lengths = {1024, 2048};
-
-    auto results = service_->BatchUpsertStart(
-        client_id, keys, TenantId::Default(), slice_lengths, config);
-    ASSERT_EQ(2, results.size());
-    EXPECT_TRUE(results[0].has_value());  // key_1: Case B (in-place)
-    EXPECT_TRUE(results[1].has_value());  // key_2: Case A (new)
-
-    // Complete both
-    auto end_results = service_->BatchUpsertEnd(
-        client_id, MakeObjectMetas(keys), TenantId::Default());
-    ASSERT_EQ(2, end_results.size());
-    EXPECT_TRUE(end_results[0].has_value());
-    EXPECT_TRUE(end_results[1].has_value());
-}
-
-TEST_F(MasterServiceTest, UpsertPreemptsInProgressUpsert) {
-    // Upsert should preempt an in-progress Upsert (Case B in-place).
-    // After preemption, all replicas were PROCESSING (no COMPLETE survives),
-    // so metadata is erased and the new upsert falls through to Case A.
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_a = generate_uuid();
-    const UUID client_b = generate_uuid();
-    const UUID client_c = generate_uuid();
-
-    std::string key = "upsert_preempt_upsert";
-    uint64_t slice_length = 1024;
-    ReplicateConfig config;
-    config.replica_num = 1;
-
-    // Step 1: Create the object via Put
-    auto put_result = service_->PutStart(client_a, key, TenantId::Default(),
-                                         slice_length, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_a, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // Step 2: Client B starts in-place upsert (Case B) — marks COMPLETE →
-    // PROCESSING
-    auto upsert_b = service_->UpsertStart(client_b, key, TenantId::Default(),
+    // Put key_1 again, should fail because the key exists.
+    put_start_result = service_->PutStart(client_id, key_1, TenantId::Default(),
                                           slice_length, config);
-    ASSERT_TRUE(upsert_b.has_value());
+    EXPECT_FALSE(put_start_result.has_value());
+    EXPECT_EQ(put_start_result.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
 
-    // Key should be unreadable now (all replicas are PROCESSING)
-    auto get_mid = service_->GetReplicaList(key, TenantId::Default());
-    EXPECT_FALSE(get_mid.has_value());
-    EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get_mid.error());
+    // Wait for a while until the put-start expired.
+    for (size_t i = 0; i <= master_config.put_start_discard_timeout_sec; i++) {
+        for (auto& context : contexts) {
+            auto result = service_->Ping(context.client_id);
+            EXPECT_TRUE(result.has_value());
+        }
+        std::this_thread::sleep_for(std::chrono::seconds(1));
+    }
 
-    // Step 3: Client C upserts the same key — preempts Client B
-    auto upsert_c = service_->UpsertStart(client_c, key, TenantId::Default(),
+    // Put key_1 again, should success because the old one has expired and will
+    // be discarded by this put.
+    put_start_result = service_->PutStart(client_id, key_1, TenantId::Default(),
                                           slice_length, config);
-    ASSERT_TRUE(upsert_c.has_value());
-    EXPECT_EQ(1, upsert_c.value().size());
-
-    // Step 4: Client B's UpsertEnd should fail (preempted)
-    auto end_b = service_->UpsertEnd(client_b, key, TenantId::Default(),
-                                     ReplicaType::MEMORY);
-    EXPECT_FALSE(end_b.has_value());
-
-    // Step 5: Client C's UpsertEnd should succeed
-    auto end_c = service_->UpsertEnd(client_c, key, TenantId::Default(),
-                                     ReplicaType::MEMORY);
-    ASSERT_TRUE(end_c.has_value());
-
-    // Final verification
-    auto final_result = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(final_result.has_value());
-    EXPECT_EQ(1, final_result.value().replicas.size());
-    EXPECT_EQ(ReplicaStatus::COMPLETE, final_result.value().replicas[0].status);
-}
-
-TEST_F(MasterServiceTest, UpsertDifferentSizeThenRevoke) {
-    // Case C (different size) followed by UpsertRevoke.
-    // Old replicas go to discarded_replicas_, new replicas are erased by
-    // revoke. The key should disappear entirely.
-    std::unique_ptr<MasterService> service_(new MasterService());
-    [[maybe_unused]] const auto context = PrepareSimpleSegment(*service_);
-    const UUID client_id = generate_uuid();
-
-    std::string key = "upsert_diff_revoke";
-    uint64_t original_size = 1024;
-    uint64_t new_size = 2048;
-    ReplicateConfig config;
-    config.replica_num = 1;
+    EXPECT_TRUE(put_start_result.has_value());
+    replica_list = put_start_result.value();
+    EXPECT_EQ(replica_list.size(), kReplicaCnt);
+    for (size_t i = 0; i < kReplicaCnt; i++) {
+        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
+    }
 
-    // Create object with original size
-    auto put_result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         original_size, config);
-    ASSERT_TRUE(put_result.has_value());
-    auto put_end = service_->PutEnd(client_id, key, TenantId::Default(),
-                                    ReplicaType::MEMORY);
-    ASSERT_TRUE(put_end.has_value());
-
-    // Verify the key exists
-    auto exist_before = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_before.has_value());
-    EXPECT_TRUE(exist_before.value());
-
-    // UpsertStart with different size (Case C) — old replicas discarded,
-    // new replicas allocated
-    auto upsert_result = service_->UpsertStart(
-        client_id, key, TenantId::Default(), new_size, config);
-    ASSERT_TRUE(upsert_result.has_value());
-
-    // Revoke — erase the newly allocated PROCESSING replicas
-    auto revoke_result = service_->UpsertRevoke(
-        client_id, key, TenantId::Default(), ReplicaType::MEMORY);
-    ASSERT_TRUE(revoke_result.has_value());
-
-    // Key should be gone (old replicas in discarded, new replicas erased)
-    auto exist_after = service_->ExistKey(key, TenantId::Default());
-    ASSERT_TRUE(exist_after.has_value());
-    EXPECT_FALSE(exist_after.value());
-}
+    // Complete key_1.
+    auto put_end_result = service_->PutEnd(
+        client_id, key_1, TenantId::Default(), ReplicaType::MEMORY);
+    EXPECT_TRUE(put_end_result.has_value());
 
-// ===================== Hard Pin Tests =====================
+    // Protect key_1 from eviction.
+    auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
+    EXPECT_TRUE(get_result.has_value());
 
-TEST_F(MasterServiceTest, HardPinObjectNotEvicted) {
-    // Hard-pinned objects must survive eviction under memory pressure,
-    // even after lease expires and all non-pinned objects are gone.
-    const uint64_t kv_lease_ttl = 200;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
+    // Put key_2, should fail because the key_1 occupied 12MB (6MB processing,
+    // 6MB discarded but not yet released) on each segment.
+    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
+                                          slice_length, config);
+    EXPECT_FALSE(put_start_result.has_value());
+    EXPECT_EQ(put_start_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
 
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
+    // Wait for a while until the discarded replicas are released.
+    for (size_t i = 0; i <= master_config.put_start_release_timeout_sec -
+                                master_config.put_start_discard_timeout_sec;
+         i++) {
+        for (auto& context : contexts) {
+            auto result = service_->Ping(context.client_id);
+            EXPECT_TRUE(result.has_value());
+        }
+        // Protect key_1 from eviction.
+        auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
+        EXPECT_TRUE(get_result.has_value());
+        std::this_thread::sleep_for(std::chrono::seconds(1));
+    }
 
-    // Put a hard-pinned object
-    {
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.with_hard_pin = true;
-        auto result = service_->PutStart(
-            client_id, "pinned_model", TenantId::Default(), value_size, config);
-        ASSERT_TRUE(result.has_value());
-        ASSERT_TRUE(service_
-                        ->PutEnd(client_id, "pinned_model", TenantId::Default(),
-                                 ReplicaType::MEMORY)
-                        .has_value());
+    // Put key_2 again, should success because the discarded replica has been
+    // released.
+    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
+                                          slice_length, config);
+    EXPECT_TRUE(put_start_result.has_value());
+    replica_list = put_start_result.value();
+    EXPECT_EQ(replica_list.size(), kReplicaCnt);
+    for (size_t i = 0; i < kReplicaCnt; i++) {
+        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
     }
 
-    // Fill remaining space with normal objects to trigger eviction
-    for (int i = 0; i < 20; i++) {
-        std::string key = "filler_" + std::to_string(i);
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         value_size, config);
-        if (result.has_value()) {
-            service_->PutEnd(client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY);
+    // Wait for a while until key_2 can be discarded and released.
+    for (size_t i = 0; i <= master_config.put_start_release_timeout_sec; i++) {
+        for (auto& context : contexts) {
+            auto result = service_->Ping(context.client_id);
+            EXPECT_TRUE(result.has_value());
         }
+        // Protect key_1 from eviction.
+        auto get_result = service_->GetReplicaList(key_1, TenantId::Default());
+        EXPECT_TRUE(get_result.has_value());
+        std::this_thread::sleep_for(std::chrono::seconds(1));
     }
 
-    // Wait for leases to expire and eviction to kick in
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 500));
-
-    // Hard-pinned object must still be there
-    auto get_result =
-        service_->GetReplicaList("pinned_model", TenantId::Default());
-    ASSERT_TRUE(get_result.has_value())
-        << "Hard-pinned object was evicted, but it should never be";
+    // Put key_2 again, should fail because eviction has not been triggered. And
+    // this PutStart should trigger the eviction. Only BatchEvict moves the
+    // eviction attempt counter, so take the baseline before the trigger: the
+    // eviction thread polls every 10 ms, and sampling after the failing
+    // PutStart could race a completed BatchEvict and wait for a second one
+    // that never comes.
+    const int64_t eviction_attempts_before =
+        MasterMetricManager::instance().get_mem_eviction_attempts();
+    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
+                                          slice_length, config);
+    EXPECT_FALSE(put_start_result.has_value());
+    EXPECT_EQ(put_start_result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
 
-    // Explicit Remove should still work on hard-pinned objects
-    auto remove_result =
-        service_->Remove("pinned_model", TenantId::Default(), /*force=*/true);
-    ASSERT_TRUE(remove_result.has_value());
-    auto exist_result = service_->ExistKey("pinned_model", TenantId::Default());
-    ASSERT_TRUE(exist_result.has_value());
-    ASSERT_FALSE(exist_result.value());
+    // The failed PutStart above sets need_mem_eviction_, and the eviction
+    // thread answers with an asynchronous BatchEvict. Polling PutStart for up
+    // to put_start_release_timeout_sec cannot tell that path apart from the
+    // periodic DiscardExpiredProcessingReplicas fallback, which releases the
+    // same replicas on the same 5 s scale and would pass the test without
+    // exercising the immediate eviction, and the periodic path never touches
+    // the attempt counter.
+    WaitUntil([&] {
+        return MasterMetricManager::instance().get_mem_eviction_attempts() >
+               eviction_attempts_before;
+    });
+    put_start_result = service_->PutStart(client_id, key_2, TenantId::Default(),
+                                          slice_length, config);
+    ASSERT_TRUE(put_start_result.has_value())
+        << toString(put_start_result.error());
+    replica_list = put_start_result.value();
+    EXPECT_EQ(replica_list.size(), kReplicaCnt);
+    for (size_t i = 0; i < kReplicaCnt; i++) {
+        EXPECT_EQ(ReplicaStatus::PROCESSING, replica_list[i].status);
+    }
 
-    service_->RemoveAll();
+    // Complete key_2.
+    put_end_result = service_->PutEnd(client_id, key_2, TenantId::Default(),
+                                      ReplicaType::MEMORY);
+    EXPECT_TRUE(put_end_result.has_value());
 }
 
-TEST_F(MasterServiceTest, HardPinWithSoftPinEvictionOrder) {
-    // Verify eviction priority: non-pinned first, then soft-pinned,
-    // and hard-pinned objects are never evicted even under extreme pressure.
-    const uint64_t kv_lease_ttl = 200;
-    const uint64_t kv_soft_pin_ttl = 10000;
-    const bool allow_evict_soft_pinned_objects = true;
-    auto service_config = MasterServiceConfig::builder()
-                              .set_default_kv_lease_ttl(kv_lease_ttl)
-                              .set_default_kv_soft_pin_ttl(kv_soft_pin_ttl)
-                              .set_allow_evict_soft_pinned_objects(
-                                  allow_evict_soft_pinned_objects)
-                              .set_eviction_ratio(0.5)
-                              .build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, TenantTasksCarryTenantInPayload) {
+    const TenantId tenant_id("tenant_for_async_task");
+    auto service = std::make_unique<MasterService>(
+        MakeStrictTenantConfig({tenant_id.value()}));
+    const auto ctx0 = PrepareSimpleSegment(*service, "segment_0", 0x300000000,
+                                           kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service, "segment_1", 0x400000000, kDefaultSegmentSize);
 
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    constexpr size_t value_size = 1024 * 1024;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
+    const UUID put_client_id = generate_uuid();
+    const std::string key = "tenant_task_key";
 
-    // Put a hard-pinned object
-    {
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.with_hard_pin = true;
-        ASSERT_TRUE(service_
-                        ->PutStart(client_id, "hard_pinned",
-                                   TenantId::Default(), value_size, config)
-                        .has_value());
-        ASSERT_TRUE(service_
-                        ->PutEnd(client_id, "hard_pinned", TenantId::Default(),
-                                 ReplicaType::MEMORY)
-                        .has_value());
-    }
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.preferred_segment = "segment_0";
 
-    // Put a soft-pinned object
-    {
-        ReplicateConfig config;
-        config.replica_num = 1;
-        config.with_soft_pin = true;
-        ASSERT_TRUE(service_
-                        ->PutStart(client_id, "soft_pinned",
-                                   TenantId::Default(), value_size, config)
-                        .has_value());
-        ASSERT_TRUE(service_
-                        ->PutEnd(client_id, "soft_pinned", TenantId::Default(),
-                                 ReplicaType::MEMORY)
-                        .has_value());
-    }
+    ASSERT_TRUE(service
+                    ->PutStart(put_client_id, key, tenant_id,
+                               /*slice_length=*/1024, config)
+                    .has_value());
+    ASSERT_TRUE(
+        service->PutEnd(put_client_id, key, tenant_id, ReplicaType::MEMORY)
+            .has_value());
 
-    // Fill the rest
-    for (int i = 0; i < 20; i++) {
-        std::string key = "normal_" + std::to_string(i);
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto result = service_->PutStart(client_id, key, TenantId::Default(),
-                                         value_size, config);
-        if (result.has_value()) {
-            service_->PutEnd(client_id, key, TenantId::Default(),
-                             ReplicaType::MEMORY);
+    auto copy_task_id = service->CreateCopyTask(key, tenant_id, {"segment_1"});
+    ASSERT_TRUE(copy_task_id.has_value());
+    auto move_task_id =
+        service->CreateMoveTask(key, tenant_id, "segment_0", "segment_1");
+    ASSERT_TRUE(move_task_id.has_value());
+
+    auto fetched = service->FetchTasks(ctx0.client_id, /*batch_size=*/16);
+    ASSERT_TRUE(fetched.has_value());
+    ASSERT_EQ(fetched->size(), 2u);
+
+    bool saw_copy = false;
+    bool saw_move = false;
+    for (const auto& assignment : *fetched) {
+        if (assignment.id == copy_task_id.value()) {
+            ReplicaCopyPayload payload;
+            struct_json::from_json(payload, assignment.payload);
+            EXPECT_EQ(payload.tenant_id, tenant_id.value());
+            EXPECT_EQ(payload.key, key);
+            saw_copy = true;
+        } else if (assignment.id == move_task_id.value()) {
+            ReplicaMovePayload payload;
+            struct_json::from_json(payload, assignment.payload);
+            EXPECT_EQ(payload.tenant_id, tenant_id.value());
+            EXPECT_EQ(payload.key, key);
+            saw_move = true;
         }
     }
+    EXPECT_TRUE(saw_copy);
+    EXPECT_TRUE(saw_move);
+}
 
-    // Let leases expire, trigger eviction
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl + 500));
-
-    // Hard-pinned always survives
-    ASSERT_TRUE(service_->GetReplicaList("hard_pinned", TenantId::Default())
-                    .has_value())
-        << "Hard-pinned object was evicted";
+TEST_F(MasterServiceTest, LegacyTaskPayloadDefaultsTenant) {
+    ReplicaCopyPayload copy_payload;
+    struct_json::from_json(
+        copy_payload,
+        R"({"key":"legacy_copy_key","source":"segment_0","targets":["segment_1"]})");
+    EXPECT_EQ(copy_payload.tenant_id, TenantId::kDefaultValue);
+    EXPECT_EQ(copy_payload.key, "legacy_copy_key");
+    EXPECT_EQ(copy_payload.source, "segment_0");
+    ASSERT_EQ(copy_payload.targets.size(), 1u);
+    EXPECT_EQ(copy_payload.targets[0], "segment_1");
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service_->RemoveAll();
+    ReplicaMovePayload move_payload;
+    struct_json::from_json(
+        move_payload,
+        R"({"key":"legacy_move_key","source":"segment_0","target":"segment_1"})");
+    EXPECT_EQ(move_payload.tenant_id, TenantId::kDefaultValue);
+    EXPECT_EQ(move_payload.key, "legacy_move_key");
+    EXPECT_EQ(move_payload.source, "segment_0");
+    EXPECT_EQ(move_payload.target, "segment_1");
 }
 
-TEST_F(MasterServiceTest, HardPinDefaultIsFalse) {
-    // Objects created without with_hard_pin should not be hard-pinned
+TEST_F(MasterServiceTest,
+       CreateDrainJobMarksSegmentDrainingAndSkipsAllocation) {
     auto service_config =
-        MasterServiceConfig::builder().set_default_kv_lease_ttl(5000).build();
-    std::unique_ptr<MasterService> service_(new MasterService(service_config));
-    const UUID client_id = generate_uuid();
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
+    auto service_ = std::make_unique<MasterService>(service_config);
 
-    constexpr size_t buffer = 0x300000000;
-    constexpr size_t segment_size = 1024 * 1024 * 16;
-    [[maybe_unused]] const auto context =
-        PrepareSimpleSegment(*service_, "test_segment", buffer, segment_size);
+    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
+                                           kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
+
+    CreateDrainJobRequest request;
+    request.segments = {"segment_0"};
+    request.target_segments = {"segment_1"};
+    request.max_concurrency = 1;
+
+    auto job_id = service_->CreateDrainJob(request);
+    ASSERT_TRUE(job_id.has_value());
+
+    auto segment_status = service_->QuerySegmentStatus("segment_0");
+    ASSERT_TRUE(segment_status.has_value());
+    EXPECT_EQ(segment_status.value(), SegmentStatus::DRAINING);
 
-    // Put without hard_pin (default)
     ReplicateConfig config;
     config.replica_num = 1;
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, "normal_key", TenantId::Default(),
-                               1024, config)
-                    .has_value());
-    ASSERT_TRUE(service_
-                    ->PutEnd(client_id, "normal_key", TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
+    config.preferred_segment = "segment_0";
 
-    // Put with hard_pin
-    ReplicateConfig hp_config;
-    hp_config.replica_num = 1;
-    hp_config.with_hard_pin = true;
-    ASSERT_TRUE(service_
-                    ->PutStart(client_id, "hp_key", TenantId::Default(), 1024,
-                               hp_config)
-                    .has_value());
+    auto put_result =
+        service_->PutStart(ctx0.client_id, "drain_skip_allocation_key",
+                           TenantId::Default(), 1024, config);
+    ASSERT_TRUE(put_result.has_value());
+    ASSERT_EQ(put_result->size(), 1u);
+    EXPECT_EQ(put_result->front()
+                  .get_memory_descriptor()
+                  .buffer_descriptor.transport_endpoint_,
+              "segment_1");
     ASSERT_TRUE(service_
-                    ->PutEnd(client_id, "hp_key", TenantId::Default(),
-                             ReplicaType::MEMORY)
-                    .has_value());
-
-    // Both should exist
-    ASSERT_TRUE(service_->GetReplicaList("normal_key", TenantId::Default())
+                    ->PutEnd(ctx0.client_id, "drain_skip_allocation_key",
+                             TenantId::Default(), ReplicaType::MEMORY)
                     .has_value());
-    ASSERT_TRUE(
-        service_->GetReplicaList("hp_key", TenantId::Default()).has_value());
-
-    service_->RemoveAll();
 }
 
-// ===================== Graceful Unmount Tests =====================
+TEST_F(MasterServiceTest, DrainJobSchedulesMoveTaskAndConvergesToDrained) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
+    auto service_ = std::make_unique<MasterService>(service_config);
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_SetsCorrectStatus) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto segment = MakeSegment("graceful_test_segment");
-    UUID client_id = generate_uuid();
+    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
+                                           kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
 
-    // Mount segment
-    ASSERT_TRUE(service_->MountSegment(segment, client_id).has_value());
+    const UUID put_client_id = generate_uuid();
+    const std::string key =
+        PutObjectOnSegment(*service_, put_client_id, "segment_0");
 
-    // Verify initial status
-    auto status_before = service_->QuerySegmentStatus(segment.name);
-    ASSERT_TRUE(status_before.has_value());
-    EXPECT_EQ(status_before.value(), SegmentStatus::OK);
-
-    // Graceful unmount with 1 second grace period
-    auto graceful_result = service_->GracefulUnmountSegment(
-        segment.id, client_id, /*grace_period_ms=*/1000);
-    ASSERT_TRUE(graceful_result.has_value())
-        << "Graceful unmount should succeed: "
-        << toString(graceful_result.error());
-
-    // Verify status is GRACEFULLY_UNMOUNTING
-    auto status_after = service_->QuerySegmentStatus(segment.name);
-    ASSERT_TRUE(status_after.has_value());
-    EXPECT_EQ(status_after.value(), SegmentStatus::GRACEFULLY_UNMOUNTING);
-
-    // Wait for timer to expire and clean up
-    std::this_thread::sleep_for(std::chrono::milliseconds(1500));
-}
+    CreateDrainJobRequest request;
+    request.segments = {"segment_0"};
+    request.target_segments = {"segment_1"};
+    request.max_concurrency = 1;
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_RejectWrongClient) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto segment = MakeSegment("graceful_owner_segment");
-    UUID owner_client = generate_uuid();
-    UUID wrong_client = generate_uuid();
+    auto job_id = service_->CreateDrainJob(request);
+    ASSERT_TRUE(job_id.has_value());
 
-    ASSERT_TRUE(service_->MountSegment(segment, owner_client).has_value());
+    WaitUntil(
+        [&] { return ExecutePendingMoveTasks(*service_, ctx0.client_id); });
+
+    WaitUntil([&] {
+        auto query = service_->QueryDrainJob(job_id.value());
+        return query.has_value() && query->status == JobStatus::SUCCEEDED;
+    });
 
-    // Wrong client trying to graceful unmount should fail
-    auto graceful_result = service_->GracefulUnmountSegment(
-        segment.id, wrong_client, /*grace_period_ms=*/1000);
-    ASSERT_FALSE(graceful_result.has_value());
-    EXPECT_EQ(graceful_result.error(), ErrorCode::SEGMENT_NOT_FOUND);
+    auto query = service_->QueryDrainJob(job_id.value());
+    ASSERT_TRUE(query.has_value());
+    EXPECT_EQ(query->status, JobStatus::SUCCEEDED);
+    EXPECT_EQ(query->active_units, 0u);
+    EXPECT_GE(query->succeeded_units, 1u);
 
-    // Owner should still be able to unmount
-    auto owner_result = service_->GracefulUnmountSegment(
-        segment.id, owner_client, /*grace_period_ms=*/1000);
-    EXPECT_TRUE(owner_result.has_value());
+    auto segment_status = service_->QuerySegmentStatus("segment_0");
+    ASSERT_TRUE(segment_status.has_value());
+    EXPECT_EQ(segment_status.value(), SegmentStatus::DRAINED);
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(1500));
+    auto replicas = service_->GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(replicas.has_value());
+    std::unordered_set<std::string> segment_names;
+    for (const auto& replica : replicas->replicas) {
+        segment_names.insert(replica.get_memory_descriptor()
+                                 .buffer_descriptor.transport_endpoint_);
+    }
+    EXPECT_TRUE(segment_names.contains("segment_1"));
+    EXPECT_FALSE(segment_names.contains("segment_0"));
 }
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_Idempotent) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto segment = MakeSegment("graceful_idempotent_segment");
-    UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, CancelDrainJobRestoresSegmentStatus) {
+    auto service_ = std::make_unique<MasterService>();
 
-    ASSERT_TRUE(service_->MountSegment(segment, client_id).has_value());
+    [[maybe_unused]] const auto ctx0 = PrepareSimpleSegment(
+        *service_, "segment_0", 0x300000000, kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
 
-    // First graceful unmount should succeed
-    auto result1 = service_->GracefulUnmountSegment(segment.id, client_id,
-                                                    /*grace_period_ms=*/1000);
-    ASSERT_TRUE(result1.has_value());
+    CreateDrainJobRequest request;
+    request.segments = {"segment_0"};
+    request.target_segments = {"segment_1"};
+    request.max_concurrency = 1;
 
-    // Second graceful unmount on the same segment should also succeed
-    // (idempotent)
-    auto result2 = service_->GracefulUnmountSegment(segment.id, client_id,
-                                                    /*grace_period_ms=*/1000);
-    EXPECT_TRUE(result2.has_value()) << "Graceful unmount should be idempotent";
+    auto job_id = service_->CreateDrainJob(request);
+    ASSERT_TRUE(job_id.has_value());
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(1500));
-}
+    auto draining_status = service_->QuerySegmentStatus("segment_0");
+    ASSERT_TRUE(draining_status.has_value());
+    EXPECT_EQ(draining_status.value(), SegmentStatus::DRAINING);
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_TimerExpiresAndUnmounts) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto segment = MakeSegment("graceful_timer_segment");
-    UUID client_id = generate_uuid();
+    auto cancel_result = service_->CancelDrainJob(job_id.value());
+    ASSERT_TRUE(cancel_result.has_value());
 
-    ASSERT_TRUE(service_->MountSegment(segment, client_id).has_value());
+    auto job = service_->QueryDrainJob(job_id.value());
+    ASSERT_TRUE(job.has_value());
+    EXPECT_EQ(job->status, JobStatus::CANCELED);
 
-    // Graceful unmount with a short grace period (50ms)
-    auto graceful_result = service_->GracefulUnmountSegment(
-        segment.id, client_id, /*grace_period_ms=*/50);
-    ASSERT_TRUE(graceful_result.has_value());
-
-    // Immediately after graceful unmount, segment should still exist
-    auto status_immediate = service_->QuerySegmentStatus(segment.name);
-    ASSERT_TRUE(status_immediate.has_value());
-    EXPECT_EQ(status_immediate.value(), SegmentStatus::GRACEFULLY_UNMOUNTING);
-
-    // Wait for timer to expire and unmount (give some margin)
-    std::this_thread::sleep_for(std::chrono::milliseconds(300));
-
-    // After timer expires, segment should be fully unmounted (UNDEFINED or
-    // error)
-    auto status_after = service_->QuerySegmentStatus(segment.name);
-    // Segment may be UNDEFINED (not found) or return an error
-    EXPECT_TRUE(!status_after.has_value() ||
-                status_after.value() == SegmentStatus::UNDEFINED)
-        << "Segment should be unmounted after timer expires, got status="
-        << (status_after.has_value() ? static_cast<int>(status_after.value())
-                                     : -1);
+    auto restored_status = service_->QuerySegmentStatus("segment_0");
+    ASSERT_TRUE(restored_status.has_value());
+    EXPECT_EQ(restored_status.value(), SegmentStatus::OK);
 }
 
-TEST_F(MasterServiceTest,
-       GracefulUnmountSegment_QueryStatusByIdWithReusedName) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto old_segment = MakeSegment("graceful_reused_name_segment");
-    auto new_segment = MakeSegment(old_segment.name, /*base=*/0x400000000);
-    UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, CancelDrainJobRejectsActiveMoveTasks) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
+    auto service_ = std::make_unique<MasterService>(service_config);
 
-    ASSERT_TRUE(service_->MountSegment(old_segment, client_id).has_value());
-    ASSERT_TRUE(service_
-                    ->GracefulUnmountSegment(old_segment.id, client_id,
-                                             /*grace_period_ms=*/50)
-                    .has_value());
-    ASSERT_TRUE(service_->MountSegment(new_segment, client_id).has_value());
+    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
+                                           kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
 
-    auto old_status = service_->QuerySegmentStatusById(old_segment.id);
-    ASSERT_TRUE(old_status.has_value());
-    EXPECT_EQ(old_status.value(), SegmentStatus::GRACEFULLY_UNMOUNTING);
+    const UUID put_client_id = generate_uuid();
+    PutObjectOnSegment(*service_, put_client_id, "segment_0");
 
-    auto new_status = service_->QuerySegmentStatusById(new_segment.id);
-    ASSERT_TRUE(new_status.has_value());
-    EXPECT_EQ(new_status.value(), SegmentStatus::OK);
+    CreateDrainJobRequest request;
+    request.segments = {"segment_0"};
+    request.target_segments = {"segment_1"};
+    request.max_concurrency = 1;
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    auto job_id = service_->CreateDrainJob(request);
+    ASSERT_TRUE(job_id.has_value());
 
-    EXPECT_FALSE(service_->QuerySegmentStatusById(old_segment.id).has_value());
-    ASSERT_TRUE(service_->QuerySegmentStatusById(new_segment.id).has_value());
+    WaitUntil([&] {
+        auto fetched = service_->FetchTasks(ctx0.client_id, /*batch_size=*/16);
+        return fetched.has_value() && !fetched->empty();
+    });
 
-    auto status_by_name = service_->QuerySegmentStatus(new_segment.name);
-    ASSERT_TRUE(status_by_name.has_value());
-    EXPECT_EQ(status_by_name.value(), SegmentStatus::OK);
+    auto cancel_result = service_->CancelDrainJob(job_id.value());
+    ASSERT_FALSE(cancel_result.has_value());
+    EXPECT_EQ(cancel_result.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 }
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_EarlierTimerPreemptsWait) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto long_segment = MakeSegment("graceful_long_timer_segment");
-    auto short_segment =
-        MakeSegment("graceful_short_timer_segment", /*base=*/0x400000000);
-    UUID client_id = generate_uuid();
+TEST_F(MasterServiceTest, DrainJobFailsAfterRetryBudgetExhausted) {
+    auto service_config =
+        MasterServiceConfig::builder().set_default_kv_lease_ttl(0).build();
+    auto service_ = std::make_unique<MasterService>(service_config);
 
-    ASSERT_TRUE(service_->MountSegment(long_segment, client_id).has_value());
-    ASSERT_TRUE(service_->MountSegment(short_segment, client_id).has_value());
+    const auto ctx0 = PrepareSimpleSegment(*service_, "segment_0", 0x300000000,
+                                           kDefaultSegmentSize);
+    [[maybe_unused]] const auto ctx1 = PrepareSimpleSegment(
+        *service_, "segment_1", 0x400000000, kDefaultSegmentSize);
 
-    ASSERT_TRUE(service_
-                    ->GracefulUnmountSegment(long_segment.id, client_id,
-                                             /*grace_period_ms=*/1000)
-                    .has_value());
-    std::this_thread::sleep_for(std::chrono::milliseconds(20));
-    ASSERT_TRUE(service_
-                    ->GracefulUnmountSegment(short_segment.id, client_id,
-                                             /*grace_period_ms=*/50)
-                    .has_value());
+    const UUID put_client_id = generate_uuid();
+    PutObjectOnSegment(*service_, put_client_id, "segment_0");
+
+    CreateDrainJobRequest request;
+    request.segments = {"segment_0"};
+    request.target_segments = {"segment_1"};
+    request.max_concurrency = 1;
+
+    auto job_id = service_->CreateDrainJob(request);
+    ASSERT_TRUE(job_id.has_value());
+
+    for (int attempt = 0; attempt < 3; ++attempt) {
+        WaitUntil(
+            [&] { return FailPendingMoveTasks(*service_, ctx0.client_id); });
+    }
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    WaitUntil([&] {
+        auto query = service_->QueryDrainJob(job_id.value());
+        return query.has_value() && query->status == JobStatus::FAILED;
+    });
 
-    auto short_status = service_->QuerySegmentStatus(short_segment.name);
-    EXPECT_TRUE(!short_status.has_value() ||
-                short_status.value() == SegmentStatus::UNDEFINED);
+    auto query = service_->QueryDrainJob(job_id.value());
+    ASSERT_TRUE(query.has_value());
+    EXPECT_EQ(query->status, JobStatus::FAILED);
+    EXPECT_EQ(query->active_units, 0u);
+    EXPECT_GE(query->failed_units, 3u);
 
-    auto long_status = service_->QuerySegmentStatus(long_segment.name);
-    ASSERT_TRUE(long_status.has_value());
-    EXPECT_EQ(long_status.value(), SegmentStatus::GRACEFULLY_UNMOUNTING);
+    auto segment_status = service_->QuerySegmentStatus("segment_0");
+    ASSERT_TRUE(segment_status.has_value());
+    EXPECT_EQ(segment_status.value(), SegmentStatus::OK);
 }
 
-TEST_F(MasterServiceTest, GracefulUnmountSegment_PreventAllocation) {
-    std::unique_ptr<MasterService> service_(new MasterService());
-    auto segment1 = MakeSegment("graceful_seg1");
-    auto segment2 = MakeSegment("graceful_seg2", /*base=*/0x400000000);
-    UUID client_id = generate_uuid();
+// ===================== Client Offboarding Tests =====================
 
-    ASSERT_TRUE(service_->MountSegment(segment1, client_id).has_value());
-    ASSERT_TRUE(service_->MountSegment(segment2, client_id).has_value());
+TEST_F(MasterServiceTest, ClientOffboardingRetryPolicy) {
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(1), std::chrono::seconds(1));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(2), std::chrono::seconds(2));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(3), std::chrono::seconds(4));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(4), std::chrono::seconds(8));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(5), std::chrono::seconds(16));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(6), std::chrono::seconds(30));
+    EXPECT_EQ(ClientOffboardingRetryDelayForTest(100),
+              std::chrono::seconds(30));
+    EXPECT_FALSE(ClientOffboardingShouldAlertForTest(9));
+    EXPECT_TRUE(ClientOffboardingShouldAlertForTest(10));
+    EXPECT_TRUE(ClientOffboardingShouldAlertForTest(11));
+}
 
-    // Put an object on segment1
-    std::string key = "test_key_prevent_alloc";
+TEST_F(MasterServiceTest, ReMountDoesNotRecoverSuspectedClient) {
+    MasterService service;
+    auto segment = MakeSegment("suspected_remount_segment");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+
+    const auto liveness = FindClientLivenessForTest(service, client_id);
+    ASSERT_TRUE(liveness);
+    ASSERT_EQ(
+        liveness->Evaluate(ClientLivenessRecord::Clock::now(),
+                           std::chrono::seconds::zero(), std::chrono::hours(1)),
+        ClientLivenessTransition::BECAME_SUSPECTED);
+    MasterMetricManager::instance().client_liveness_became_suspected();
+
+    ASSERT_TRUE(service.ReMountSegment({segment}, client_id).has_value());
+    EXPECT_EQ(liveness->state(), ClientLivenessState::SUSPECTED);
+    EXPECT_EQ(service.Ping(client_id)->client_status, ClientStatus::OK);
+    EXPECT_EQ(liveness->state(), ClientLivenessState::ACTIVE);
+}
+
+TEST_F(MasterServiceTest,
+       InPlaceUpsertRejectsSuspectedTargetWithoutChangingMetadata) {
+    MasterService service;
+    auto segment = MakeSegment("suspected_upsert_segment");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+
+    const auto key = PutObjectOnSegment(service, client_id, segment.name);
     ReplicateConfig config;
     config.replica_num = 1;
-    config.preferred_segment = segment1.name;
+    config.preferred_segment = segment.name;
 
-    auto put_start =
-        service_->PutStart(client_id, key, TenantId::Default(), 1024, config);
-    ASSERT_TRUE(put_start.has_value());
-    ASSERT_TRUE(
-        service_
-            ->PutEnd(client_id, key, TenantId::Default(), ReplicaType::MEMORY)
-            .has_value());
+    const auto liveness = FindClientLivenessForTest(service, client_id);
+    ASSERT_TRUE(liveness);
+    ASSERT_EQ(
+        liveness->Evaluate(ClientLivenessRecord::Clock::now(),
+                           std::chrono::seconds::zero(), std::chrono::hours(1)),
+        ClientLivenessTransition::BECAME_SUSPECTED);
+    MasterMetricManager::instance().client_liveness_became_suspected();
 
-    // Graceful unmount segment1
-    ASSERT_TRUE(service_->GracefulUnmountSegment(segment1.id, client_id, 1000)
-                    .has_value());
+    auto upsert =
+        service.UpsertStart(client_id, key, TenantId::Default(), 1024, config);
+    ASSERT_FALSE(upsert.has_value());
+    EXPECT_EQ(upsert.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 
-    // Segment1 status should be GRACEFULLY_UNMOUNTING
-    auto status1 = service_->QuerySegmentStatus(segment1.name);
-    ASSERT_TRUE(status1.has_value());
-    EXPECT_EQ(status1.value(), SegmentStatus::GRACEFULLY_UNMOUNTING);
-
-    // Existing replicas on the graceful segment should remain readable during
-    // the grace window.
-    auto existing_replicas = service_->GetReplicaList(key, TenantId::Default());
-    ASSERT_TRUE(existing_replicas.has_value());
-    ASSERT_EQ(existing_replicas->replicas.size(), 1u);
-    EXPECT_EQ(existing_replicas->replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              segment1.name);
-
-    // Segment2 status should still be OK
-    auto status2 = service_->QuerySegmentStatus(segment2.name);
-    ASSERT_TRUE(status2.has_value());
-    EXPECT_EQ(status2.value(), SegmentStatus::OK);
-
-    // New put without preferred_segment should succeed on segment2
-    std::string key2 = "test_key_after_graceful";
-    ReplicateConfig config2;
-    config2.replica_num = 1;
-
-    auto put_start2 =
-        service_->PutStart(client_id, key2, TenantId::Default(), 1024, config2);
-    ASSERT_TRUE(put_start2.has_value());
-    auto replicas = put_start2.value();
-    ASSERT_EQ(replicas.size(), 1u);
-    // Should be placed on segment2, not segment1
-    EXPECT_EQ(replicas[0]
-                  .get_memory_descriptor()
-                  .buffer_descriptor.transport_endpoint_,
-              segment2.name);
+    ASSERT_TRUE(service.Ping(client_id).has_value());
+    auto get = service.GetReplicaList(key, TenantId::Default());
+    ASSERT_TRUE(get.has_value()) << toString(get.error());
+    ASSERT_EQ(get->replicas.size(), 1u);
+    EXPECT_EQ(get->replicas.front().status, ReplicaStatus::COMPLETE);
+}
+
+TEST_F(MasterServiceTest,
+       ClientOffboardingProcessesRealSegmentAndMetadataResiduals) {
+    MasterService service;
+    auto segment = MakeSegment("offboarding_segment");
+    const UUID client_id = generate_uuid();
+    ASSERT_TRUE(service.MountSegment(segment, client_id).has_value());
+
+    const std::string key =
+        PutObjectOnSegment(service, client_id, segment.name);
+    const auto liveness = FindClientLivenessForTest(service, client_id);
+    ASSERT_TRUE(liveness);
+
+    ClientOffboardingJob job;
+    job.client_id = client_id;
+    job.liveness = liveness;
+    job.pending_prepare_segments.push_back(
+        {.segment_id = segment.id,
+         .segment_name = segment.name,
+         .transport_endpoint = segment.te_endpoint});
+
+    ASSERT_TRUE(ProcessClientOffboardingForTest(service, job));
+    EXPECT_TRUE(job.pending_prepare_segments.empty());
+    EXPECT_TRUE(job.prepared_segments.empty());
+    EXPECT_TRUE(job.metadata_cleanup_accepted);
+    EXPECT_TRUE(job.local_ssd_unregistered);
+    EXPECT_FALSE(FindClientLivenessForTest(service, client_id));
+    EXPECT_FALSE(service.QuerySegmentStatusById(segment.id).has_value());
+
+    auto exists = service.ExistKey(key, TenantId::Default());
+    ASSERT_TRUE(exists.has_value());
+    EXPECT_FALSE(*exists);
+}
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(1500));
+TEST_F(MasterServiceTest,
+       ClientOffboardingKeepsPreparedResidualWithoutRepreparingIt) {
+    MasterService service;
+    const UUID client_id = generate_uuid();
+    auto prepared_segment = MakeSegment("offboarding_prepared_segment");
+    auto blocked_segment =
+        MakeSegment("offboarding_blocked_segment", /*base=*/0x400000000);
+    ASSERT_TRUE(service.MountSegment(prepared_segment, client_id).has_value());
+    ASSERT_TRUE(service.MountSegment(blocked_segment, client_id).has_value());
+    size_t blocked_metrics_dec_capacity = 0;
+    ASSERT_EQ(ErrorCode::OK,
+              PrepareUnmountSegmentForTest(service, blocked_segment.id,
+                                           blocked_metrics_dec_capacity));
+
+    ClientOffboardingJob job;
+    job.client_id = client_id;
+    job.liveness = FindClientLivenessForTest(service, client_id);
+    ASSERT_TRUE(job.liveness);
+    job.pending_prepare_segments = {
+        {.segment_id = prepared_segment.id,
+         .segment_name = prepared_segment.name,
+         .transport_endpoint = prepared_segment.te_endpoint},
+        {.segment_id = blocked_segment.id,
+         .segment_name = blocked_segment.name,
+         .transport_endpoint = blocked_segment.te_endpoint}};
+
+    ASSERT_FALSE(ProcessClientOffboardingForTest(service, job));
+    ASSERT_EQ(job.prepared_segments.size(), 1u);
+    ASSERT_EQ(job.pending_prepare_segments.size(), 1u);
+    EXPECT_EQ(job.prepared_segments.front().segment_id, prepared_segment.id);
+    EXPECT_EQ(job.pending_prepare_segments.front().segment_id,
+              blocked_segment.id);
+    const auto retained_capacity =
+        job.prepared_segments.front().metrics_dec_capacity;
+
+    ASSERT_FALSE(ProcessClientOffboardingForTest(service, job));
+    ASSERT_EQ(job.prepared_segments.size(), 1u);
+    ASSERT_EQ(job.pending_prepare_segments.size(), 1u);
+    EXPECT_EQ(job.prepared_segments.front().segment_id, prepared_segment.id);
+    EXPECT_EQ(job.prepared_segments.front().metrics_dec_capacity,
+              retained_capacity);
+
+    ASSERT_EQ(ErrorCode::OK, CommitUnmountSegmentForTest(
+                                 service, blocked_segment.id, client_id,
+                                 blocked_metrics_dec_capacity));
+    ASSERT_TRUE(ProcessClientOffboardingForTest(service, job));
+    EXPECT_TRUE(job.prepared_segments.empty());
+    EXPECT_TRUE(job.pending_prepare_segments.empty());
+    EXPECT_FALSE(FindClientLivenessForTest(service, client_id));
 }
 
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/master_service_test_fixture.h b/mooncake-store/tests/master_service_test_fixture.h
new file mode 100644
index 0000000000..12a2de94a3
--- /dev/null
+++ b/mooncake-store/tests/master_service_test_fixture.h
@@ -0,0 +1,630 @@
+// master_service_test_fixture.h
+//
+// Shared MasterServiceTest fixture used by the master_service test binaries.
+// Business-behavior coverage lives in the scenario DSL; this fixture is the
+// implementation-coupled harness (segment setup, put helpers) shared by the
+// focused behavior-area test files.
+
+#pragma once
+
+#include "master_service.h"
+#include "master_service/master_service_test_peer.h"
+#include "types.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace mooncake::test {
+
+std::vector<ObjectMeta> MakeObjectMetas(const std::vector<std::string>& keys) {
+    std::vector<ObjectMeta> object_metas;
+    object_metas.reserve(keys.size());
+    for (const auto& key : keys) {
+        object_metas.emplace_back(ObjectMeta{key, std::nullopt});
+    }
+    return object_metas;
+}
+
+class MasterServiceTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging("MasterServiceTest");
+        FLAGS_logtostderr = true;
+    }
+
+    struct MountedSegmentContext {
+        UUID segment_id;
+        UUID client_id;
+    };
+
+    static constexpr size_t kDefaultSegmentBase = 0x300000000;
+    static constexpr size_t kDefaultSegmentSize = 1024 * 1024 * 16;
+    static constexpr uint64_t kStrictTenantQuotaBytes = 4 * 1024 * 1024;
+
+    void PauseReplicaCleanup(MasterService& service) {
+        MasterServiceTestPeer::ReplicaCleanupWorker(service).Stop();
+    }
+
+    void ResumeReplicaCleanup(MasterService& service) {
+        MasterServiceTestPeer::ReplicaCleanupWorker(service).Start();
+        MasterServiceTestPeer::ReplicaCleanupWorker(service).Schedule();
+    }
+
+    std::shared_ptr<ClientLivenessRecord> FindClientLivenessForTest(
+        MasterService& service, const UUID& client_id) {
+        return MasterServiceTestPeer(service).FindClientRecord(client_id);
+    }
+
+    bool ProcessClientOffboardingForTest(MasterService& service,
+                                         ClientOffboardingJob& job) {
+        return MasterServiceTestPeer(service).ProcessClientOffboardingJob(job);
+    }
+
+    ErrorCode PrepareUnmountSegmentForTest(MasterService& service,
+                                           const UUID& segment_id,
+                                           size_t& metrics_dec_capacity) {
+        auto access =
+            MasterServiceTestPeer::SegmentManager(service).getSegmentAccess();
+        return access.PrepareUnmountSegment(segment_id, metrics_dec_capacity);
+    }
+
+    ErrorCode CommitUnmountSegmentForTest(MasterService& service,
+                                          const UUID& segment_id,
+                                          const UUID& client_id,
+                                          size_t metrics_dec_capacity) {
+        auto access =
+            MasterServiceTestPeer::SegmentManager(service).getSegmentAccess();
+        return access.CommitUnmountSegment(segment_id, client_id,
+                                           metrics_dec_capacity);
+    }
+
+    std::chrono::seconds ClientOffboardingRetryDelayForTest(
+        uint64_t retry_count) {
+        return ClientOffboardingWorker::RetryDelay(retry_count);
+    }
+
+    bool ClientOffboardingShouldAlertForTest(uint64_t retry_count) {
+        return ClientOffboardingWorker::ShouldAlert(retry_count);
+    }
+
+    // Run the stale-handle sweep synchronously through the test peer.
+    void ClearInvalidHandlesForTest(MasterService& service) {
+        MasterServiceTestPeer(service).ClearInvalidHandles();
+    }
+
+    void ExpectKeyHiddenFromReadApis(MasterService& service,
+                                     const std::string& key) {
+        auto get = service.GetReplicaList(key, TenantId::Default());
+        ASSERT_FALSE(get.has_value());
+        EXPECT_EQ(ErrorCode::REPLICA_IS_NOT_READY, get.error());
+
+        auto exists = service.ExistKey(key, TenantId::Default());
+        ASSERT_TRUE(exists.has_value());
+        EXPECT_FALSE(*exists);
+
+        auto batch_exists = service.BatchExistKey({key}, TenantId::Default());
+        ASSERT_EQ(1u, batch_exists.size());
+        ASSERT_TRUE(batch_exists[0].has_value());
+        EXPECT_FALSE(*batch_exists[0]);
+
+        auto all_keys = service.GetAllKeys(TenantId::Default());
+        ASSERT_TRUE(all_keys.has_value());
+        EXPECT_EQ(all_keys->end(),
+                  std::find(all_keys->begin(), all_keys->end(), key));
+    }
+
+    std::optional<std::chrono::system_clock::time_point> GetSoftPinDeadline(
+        MasterService& service, const std::string& key,
+        const std::string& tenant_id = "default") {
+        const TenantId normalized_tenant =
+            MasterServiceTestPeer(service).ResolveRequestTenantId(
+                TenantId(tenant_id));
+        const size_t shard_idx = MasterServiceTestPeer(service).getShardIndex(
+            normalized_tenant, key);
+        MasterServiceTestPeer::MetadataShardAccessorRO shard(&service,
+                                                             shard_idx);
+        const auto tenant_it = shard->tenants.find(normalized_tenant);
+        if (tenant_it == shard->tenants.end()) {
+            return std::nullopt;
+        }
+        const auto metadata_it = tenant_it->second.metadata.find(key);
+        if (metadata_it == tenant_it->second.metadata.end()) {
+            return std::nullopt;
+        }
+        return metadata_it->second.GetCommittedSoftPinTimeout();
+    }
+
+    void CleanupExpiredSoftPinsAt(
+        MasterService& service,
+        const std::chrono::system_clock::time_point& now) {
+        MasterServiceTestPeer(service).CleanupExpiredSoftPins(now);
+    }
+
+    size_t MetadataShardIndex(MasterService& service, const std::string& key,
+                              const TenantId& tenant_id = TenantId::Default()) {
+        return MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+    }
+
+    std::unique_ptr<SharedMutexLocker> LockMetadataShardForTest(
+        MasterService& service, size_t shard_idx) {
+        return std::make_unique<SharedMutexLocker>(
+            &MasterServiceTestPeer::MetadataShards(service)[shard_idx].mutex);
+    }
+
+    size_t MetadataBucketCount(
+        MasterService& service, size_t shard_idx,
+        const TenantId& tenant_id = TenantId::Default()) {
+        MasterServiceTestPeer::MetadataShardAccessorRO shard(&service,
+                                                             shard_idx);
+        const auto tenant_it = shard->tenants.find(tenant_id);
+        return tenant_it == shard->tenants.end()
+                   ? 0
+                   : tenant_it->second.metadata.bucket_count();
+    }
+
+    void SetSoftPinDeadlineForTest(
+        MasterService& service, const std::string& key,
+        const std::chrono::system_clock::time_point& deadline,
+        const std::string& tenant_id = "default") {
+        const TenantId normalized_tenant =
+            MasterServiceTestPeer(service).ResolveRequestTenantId(
+                TenantId(tenant_id));
+        const size_t shard_idx = MasterServiceTestPeer(service).getShardIndex(
+            normalized_tenant, key);
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                             shard_idx);
+        auto& metadata = shard->tenants.at(normalized_tenant).metadata.at(key);
+        {
+            SpinLocker locker(&metadata.lock);
+            metadata.soft_pin_timeout = deadline;
+        }
+        MasterServiceTestPeer::SoftPinDeadlineIndex(service).Upsert(
+            normalized_tenant.MakeScopedKey(key), shard_idx, deadline);
+    }
+
+    size_t SoftPinDeadlineHeapSize(MasterService& service) {
+        return MasterServiceTestPeer(service).SoftPinHeapSize();
+    }
+
+    size_t SoftPinRegistrationCount(MasterService& service) {
+        return MasterServiceTestPeer(service).SoftPinRegistrationCount();
+    }
+
+    std::optional<uint32_t> GetReplicaRefcntBySegmentName(
+        MasterService& service, const std::string& key,
+        const std::string& segment_name) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer(service).MakeObjectIdentityForRequest(
+                key, TenantId::Default()));
+        if (!accessor.Exists()) {
+            return std::nullopt;
+        }
+
+        for (const auto& replica : accessor.Get().GetAllReplicas()) {
+            for (const auto& name : replica.get_segment_names()) {
+                if (name.has_value() && *name == segment_name) {
+                    return replica.get_refcnt();
+                }
+            }
+        }
+        return std::nullopt;
+    }
+
+    // Inspect normalized media through the peer's locked metadata accessors.
+    std::optional<std::vector<std::string>> KvMediaForKey(
+        MasterService& service, const std::string& key,
+        const TenantId& tenant_id = TenantId::Default()) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer(service).MakeObjectIdentityForRequest(
+                key, tenant_id));
+        if (!accessor.Exists()) {
+            return std::nullopt;
+        }
+        return MasterServiceTestPeer::KvMediaForMetadata(accessor.Get());
+    }
+
+    std::optional<std::vector<std::string>> KvRemovalMediaForKey(
+        MasterService& service, const std::string& key,
+        const TenantId& tenant_id = TenantId::Default()) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            &service,
+            MasterServiceTestPeer(service).MakeObjectIdentityForRequest(
+                key, tenant_id));
+        if (!accessor.Exists()) {
+            return std::nullopt;
+        }
+        return MasterServiceTestPeer::KvMediaForRemoval(accessor.Get());
+    }
+
+    // Lets a test line up a key with a shard the RemoveAll scan has already
+    // passed, which is the only way to reproduce the commit/clear ordering race
+    // deterministically.
+    size_t ShardIndexForKey(MasterService& service, const std::string& key,
+                            const TenantId& tenant_id = TenantId::Default()) {
+        return MasterServiceTestPeer(service).getShardIndex(tenant_id, key);
+    }
+
+    void UpsertSoftPinDeadlineIndexForTest(
+        MasterService& service, const std::string& key, size_t shard_idx,
+        const std::chrono::system_clock::time_point& deadline,
+        const std::string& tenant_id = "default") {
+        MasterServiceTestPeer::SoftPinDeadlineIndex(service).Upsert(
+            TenantId(tenant_id).MakeScopedKey(key), shard_idx, deadline);
+    }
+
+    size_t PopExpiredSoftPinDeadlinesForTest(
+        MasterService& service,
+        const std::chrono::system_clock::time_point& now) {
+        return MasterServiceTestPeer::SoftPinDeadlineIndex(service)
+            .PopExpired(now)
+            .size();
+    }
+
+    std::chrono::system_clock::time_point ComputeSoftPinDeadlineForTest(
+        const std::chrono::system_clock::time_point& now,
+        std::chrono::milliseconds ttl) {
+        return MasterServiceTestPeer::ObjectMetadata::ComputeSoftPinDeadline(
+            now, ttl);
+    }
+
+    std::string WriteTenantPolicyFile(
+        const std::map<std::string, uint64_t>& tenant_quotas) {
+        TenantQuotaPolicySnapshot snapshot;
+        snapshot.tenant_quotas = tenant_quotas;
+        auto path =
+            std::filesystem::temp_directory_path() /
+            ("mooncake_master_service_test_" + std::to_string(::getpid()) +
+             "_" + std::to_string(next_policy_file_++) + ".yaml");
+        std::ofstream out(path);
+        out << FormatTenantQuotaPolicyYaml(snapshot);
+        out.close();
+        policy_files_.push_back(path.string());
+        return path.string();
+    }
+
+    MasterServiceConfig MakeStrictTenantConfig(
+        const std::vector<std::string>& tenants) {
+        std::map<std::string, uint64_t> tenant_quotas;
+        for (const auto& tenant : tenants) {
+            tenant_quotas.emplace(tenant, kStrictTenantQuotaBytes);
+        }
+        return MasterServiceConfig::builder()
+            .set_enable_multi_tenants(true)
+            .set_tenant_quota_connector_type("file")
+            .set_tenant_quota_connector_uri(
+                WriteTenantPolicyFile(tenant_quotas))
+            .build();
+    }
+
+    WrappedMasterServiceConfig MakeStrictWrappedConfig(
+        const std::vector<std::string>& tenants) {
+        WrappedMasterServiceConfig config;
+        config.default_kv_lease_ttl = 100;
+        config.enable_metric_reporting = false;
+        config.enable_multi_tenants = true;
+        config.tenant_quota_connector_type = "file";
+        std::map<std::string, uint64_t> tenant_quotas;
+        for (const auto& tenant : tenants) {
+            tenant_quotas.emplace(tenant, kStrictTenantQuotaBytes);
+        }
+        config.tenant_quota_connector_uri =
+            WriteTenantPolicyFile(tenant_quotas);
+        return config;
+    }
+
+    Segment MakeSegment(std::string name = "test_segment",
+                        size_t base = kDefaultSegmentBase,
+                        size_t size = kDefaultSegmentSize,
+                        std::string host_id = "") const {
+        Segment segment;
+        segment.id = generate_uuid();
+        segment.name = std::move(name);
+        segment.base = base;
+        segment.size = size;
+        segment.te_endpoint = segment.name;
+        segment.host_id = std::move(host_id);
+        return segment;
+    }
+
+#ifdef USE_NOF
+    NoFSegment MakeNoFSegment(
+        std::string name = "test_nof_segment",
+        std::string endpoint = "test_nof_segment_endpoint",
+        size_t base = kDefaultSegmentBase + kDefaultSegmentSize,
+        size_t size = kDefaultSegmentSize) const {
+        NoFSegment segment;
+        segment.id = generate_uuid();
+        segment.name = std::move(name);
+        segment.base = base;
+        segment.size = size;
+        segment.te_endpoint = std::move(endpoint);
+        return segment;
+    }
+#endif
+
+    MountedSegmentContext PrepareSimpleSegment(
+        MasterService& service, std::string name = "test_segment",
+        size_t base = kDefaultSegmentBase, size_t size = kDefaultSegmentSize,
+        std::string host_id = "") const {
+        Segment segment =
+            MakeSegment(std::move(name), base, size, std::move(host_id));
+        UUID client_id = generate_uuid();
+        auto mount_result = service.MountSegment(segment, client_id);
+        EXPECT_TRUE(mount_result.has_value());
+        return {.segment_id = segment.id, .client_id = client_id};
+    }
+
+    std::string PutObjectOnSegment(MasterService& service,
+                                   const UUID& client_id,
+                                   const std::string& segment_name,
+                                   size_t slice_length = 1024) const {
+        static std::atomic<uint64_t> counter{0};
+        std::string key =
+            "drain_job_key_" + std::to_string(counter.fetch_add(1));
+
+        ReplicateConfig config;
+        config.replica_num = 1;
+        config.preferred_segment = segment_name;
+
+        auto put_start = service.PutStart(client_id, key, TenantId::Default(),
+                                          slice_length, config);
+        EXPECT_TRUE(put_start.has_value());
+        EXPECT_TRUE(service
+                        .PutEnd(client_id, key, TenantId::Default(),
+                                ReplicaType::MEMORY)
+                        .has_value());
+        return key;
+    }
+
+    std::string FindGroupIdOnDifferentShard(const std::string& key) const {
+        static constexpr size_t kMetadataShardCountForTest = 1024;
+        const size_t key_shard =
+            std::hash<std::string>{}(key) % kMetadataShardCountForTest;
+        for (int i = 0; i < 10000; ++i) {
+            std::string group_id = key + "_group_" + std::to_string(i);
+            if (std::hash<std::string>{}(group_id) %
+                    kMetadataShardCountForTest !=
+                key_shard) {
+                return group_id;
+            }
+        }
+        return key + "_fallback_group";
+    }
+
+    void PutCompletedObject(MasterService& service, const UUID& client_id,
+                            const std::string& key,
+                            const ReplicateConfig& config,
+                            uint64_t slice_length = 1024) const {
+        auto put_start = service.PutStart(client_id, key, TenantId::Default(),
+                                          slice_length, config);
+        ASSERT_TRUE(put_start.has_value())
+            << "PutStart failed for key=" << key
+            << ", error=" << toString(put_start.error());
+        ASSERT_TRUE(service
+                        .PutEnd(client_id, key, TenantId::Default(),
+                                ReplicaType::MEMORY)
+                        .has_value());
+    }
+
+    void PutCompletedObject(MasterService& service, const UUID& client_id,
+                            const std::string& key, const TenantId& tenant_id,
+                            const ReplicateConfig& config,
+                            uint64_t slice_length = 1024) const {
+        auto put_start =
+            service.PutStart(client_id, key, tenant_id, slice_length, config);
+        ASSERT_TRUE(put_start.has_value())
+            << "PutStart failed for key=" << key << ", tenant_id=" << tenant_id
+            << ", error=" << toString(put_start.error());
+        ASSERT_TRUE(
+            service.PutEnd(client_id, key, tenant_id, ReplicaType::MEMORY)
+                .has_value());
+    }
+
+    bool ExecutePendingMoveTasks(MasterService& service,
+                                 const UUID& client_id) const {
+        auto fetched = service.FetchTasks(client_id, /*batch_size=*/16);
+        EXPECT_TRUE(fetched.has_value());
+        if (!fetched.has_value() || fetched->empty()) {
+            return false;
+        }
+
+        bool processed = false;
+        for (const auto& assignment : *fetched) {
+            if (assignment.type != TaskType::REPLICA_MOVE) {
+                continue;
+            }
+
+            ReplicaMovePayload payload;
+            struct_json::from_json(payload, assignment.payload);
+
+            const TenantId tenant_id(payload.tenant_id);
+            EXPECT_TRUE(tenant_id.IsValid());
+            if (!tenant_id.IsValid()) {
+                return false;
+            }
+            auto move_start =
+                service.MoveStart(client_id, payload.key, tenant_id,
+                                  payload.source, payload.target);
+            EXPECT_TRUE(move_start.has_value());
+            EXPECT_TRUE(
+                service.MoveEnd(client_id, payload.key, tenant_id).has_value());
+
+            TaskCompleteRequest complete_request;
+            complete_request.id = assignment.id;
+            complete_request.status = TaskStatus::SUCCESS;
+            complete_request.message = "move_done";
+            EXPECT_TRUE(service.MarkTaskToComplete(client_id, complete_request)
+                            .has_value());
+            processed = true;
+        }
+        return processed;
+    }
+
+    bool FailPendingMoveTasks(MasterService& service,
+                              const UUID& client_id) const {
+        auto fetched = service.FetchTasks(client_id, /*batch_size=*/16);
+        EXPECT_TRUE(fetched.has_value());
+        if (!fetched.has_value() || fetched->empty()) {
+            return false;
+        }
+
+        bool processed = false;
+        for (const auto& assignment : *fetched) {
+            if (assignment.type != TaskType::REPLICA_MOVE) {
+                continue;
+            }
+
+            TaskCompleteRequest complete_request;
+            complete_request.id = assignment.id;
+            complete_request.status = TaskStatus::FAILED;
+            complete_request.message = "move_failed";
+            EXPECT_TRUE(service.MarkTaskToComplete(client_id, complete_request)
+                            .has_value());
+            processed = true;
+        }
+        return processed;
+    }
+
+    template <typename Predicate>
+    void WaitUntil(
+        Predicate&& predicate,
+        std::chrono::milliseconds timeout = std::chrono::milliseconds(4000),
+        std::chrono::milliseconds interval =
+            std::chrono::milliseconds(50)) const {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) {
+                return;
+            }
+            std::this_thread::sleep_for(interval);
+        }
+        EXPECT_TRUE(predicate());
+    }
+
+    std::vector<Replica::Descriptor> replica_list;
+    std::vector<std::string> policy_files_;
+    size_t next_policy_file_ = 0;
+
+    void TearDown() override {
+        for (const auto& path : policy_files_) {
+            std::error_code ec;
+            std::filesystem::remove(path, ec);
+        }
+        google::ShutdownGoogleLogging();
+    }
+
+    std::vector<std::string> GetGroupMemberKeysForTest(
+        MasterService& service, const std::string& group_id,
+        const std::string& tenant_id = "default") {
+        const TenantId normalized_tenant =
+            MasterServiceTestPeer(service).ResolveRequestTenantId(
+                TenantId(tenant_id));
+        MasterServiceTestPeer::GroupDomainAccessorRO gs(&service);
+        auto it = gs->groups.find(normalized_tenant.MakeScopedKey(group_id));
+        if (it == gs->groups.end()) {
+            return {};
+        }
+        return {it->second.member_keys.begin(), it->second.member_keys.end()};
+    }
+
+    void ClearGroupStateForTest(MasterService& service) {
+        MasterServiceTestPeer::GroupDomainAccessorRW gs(&service);
+        gs->groups.clear();
+    }
+
+    void RebuildGroupStateForTest(MasterService& service) {
+        MasterServiceTestPeer(service).RebuildGroupState();
+    }
+
+    std::shared_ptr<Lease> GetGroupLeaseForTest(
+        MasterService& service, const std::string& group_id,
+        const std::string& tenant_id = "default") {
+        const TenantId normalized_tenant =
+            MasterServiceTestPeer(service).ResolveRequestTenantId(
+                TenantId(tenant_id));
+        MasterServiceTestPeer::GroupDomainAccessorRO gs(&service);
+        auto it = gs->groups.find(normalized_tenant.MakeScopedKey(group_id));
+        return it == gs->groups.end() ? nullptr : it->second.lease;
+    }
+
+    void ReRouteRestoredObjectsMigrationForTest(MasterService& service) {
+        const UUID client_id = generate_uuid();
+        const std::string grouped_key = "reroute_grouped_key";
+        const std::string ungrouped_key = "reroute_ungrouped_key";
+        const std::string group_id = FindGroupIdOnDifferentShard(grouped_key);
+
+        ReplicateConfig grouped_config;
+        grouped_config.replica_num = 1;
+        grouped_config.group_ids = std::vector<std::string>{group_id};
+        ReplicateConfig ungrouped_config;
+        ungrouped_config.replica_num = 1;
+
+        PutCompletedObject(service, client_id, grouped_key, grouped_config);
+        PutCompletedObject(service, client_id, ungrouped_key, ungrouped_config);
+
+        const TenantId tenant = TenantId::Default();
+        const size_t grouped_correct =
+            MasterServiceTestPeer(service).getShardIndex(tenant, grouped_key);
+        const size_t wrong =
+            (grouped_correct + 1) %
+            static_cast<size_t>(MasterServiceTestPeer::kNumShards);
+
+        // Reachable initially (placed on the correct hash(tenant, key) shard).
+        EXPECT_TRUE(service.ExistKey(grouped_key, tenant).value_or(false));
+
+        // Simulate an old snapshot that placed grouped_key on a stale shard.
+        {
+            MasterServiceTestPeer::MetadataShardAccessorRW src(&service,
+                                                               grouped_correct);
+            auto tenant_it = src->tenants.find(tenant);
+            ASSERT_NE(tenant_it, src->tenants.end());
+            auto obj_it = tenant_it->second.metadata.find(grouped_key);
+            ASSERT_NE(obj_it, tenant_it->second.metadata.end());
+            auto node = tenant_it->second.metadata.extract(obj_it);
+            ASSERT_FALSE(node.empty());
+            MasterServiceTestPeer::MetadataShardAccessorRW dst(&service, wrong);
+            auto& dst_tenant =
+                MasterServiceTestPeer(service).GetOrCreateTenantState(dst.get(),
+                                                                      tenant);
+            dst_tenant.metadata.insert(std::move(node));
+        }
+
+        // Now unreachable via hash(tenant, key) lookup (the old-snapshot
+        // problem).
+        EXPECT_FALSE(service.ExistKey(grouped_key, tenant).value_or(true));
+
+        // Run the migration.
+        MasterServiceTestPeer(service).ReRouteRestoredObjectsByKey();
+
+        // Reachable again, and back on the correct shard.
+        EXPECT_TRUE(service.ExistKey(grouped_key, tenant).value_or(false));
+        MasterServiceTestPeer::MetadataShardAccessorRW shard(&service,
+                                                             grouped_correct);
+        auto tenant_it = shard->tenants.find(tenant);
+        ASSERT_NE(tenant_it, shard->tenants.end());
+        EXPECT_NE(tenant_it->second.metadata.find(grouped_key),
+                  tenant_it->second.metadata.end());
+        // The stale shard no longer holds it.
+        MasterServiceTestPeer::MetadataShardAccessorRW stale(&service, wrong);
+        auto stale_it = stale->tenants.find(tenant);
+        if (stale_it != stale->tenants.end()) {
+            EXPECT_EQ(stale_it->second.metadata.find(grouped_key),
+                      stale_it->second.metadata.end());
+        }
+        // The correctly-placed ungrouped object is unaffected.
+        EXPECT_TRUE(service.ExistKey(ungrouped_key, tenant).value_or(false));
+    }
+};
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/mmap_arena_config_test.cpp b/mooncake-store/tests/mmap_arena_config_test.cpp
new file mode 100644
index 0000000000..85237c4e07
--- /dev/null
+++ b/mooncake-store/tests/mmap_arena_config_test.cpp
@@ -0,0 +1,197 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "../src/config/mmap_arena_config.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+    void Unset() { unsetenv(name_.c_str()); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct MmapArenaEnvironment {
+    ScopedEnvVar pool_size{"MC_MMAP_ARENA_POOL_SIZE"};
+    ScopedEnvVar disable{"MC_DISABLE_MMAP_ARENA"};
+    ScopedEnvVar use_hugepage{"MC_STORE_USE_HUGEPAGE"};
+    ScopedEnvVar hugepage_size{"MC_STORE_HUGEPAGE_SIZE"};
+};
+
+class MmapArenaConfigTest : public ::testing::Test {
+   protected:
+    static constexpr uint64_t kFlagPoolSize = 8ULL * 1024 * 1024 * 1024;
+
+    MmapArenaEnvironment env;
+};
+
+TEST_F(MmapArenaConfigTest, UnsetAndEmptyEnvironmentPreserveFlagInputs) {
+    auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(config.pool_size, kFlagPoolSize);
+    EXPECT_FALSE(config.hugepages_explicitly_requested);
+
+    env.pool_size.Set("");
+    env.disable.Set("");
+    config = MmapArenaConfig::FromEnvironment(true, kFlagPoolSize);
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.pool_size, kFlagPoolSize);
+    EXPECT_FALSE(config.hugepages_explicitly_requested);
+}
+
+TEST_F(MmapArenaConfigTest, PoolSizeEnvironmentOptsInAndOverridesFlag) {
+    env.pool_size.Set(" 1.5 MB ");
+
+    const auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.pool_size, 1572864);
+    EXPECT_FALSE(config.hugepages_explicitly_requested);
+}
+
+TEST_F(MmapArenaConfigTest, PreservesAcceptedInfinitePoolSize) {
+    env.pool_size.Set("infinite");
+
+    const auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.pool_size, std::numeric_limits<uint64_t>::max());
+}
+
+TEST_F(MmapArenaConfigTest, InvalidAndZeroPoolSizesOptInWithFlagFallback) {
+    for (const char* value : {"0", "-1", "invalid", "   ", "1e999"}) {
+        env.pool_size.Set(value);
+        ::testing::internal::CaptureStderr();
+
+        const auto config =
+            MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_TRUE(config.enabled) << value;
+        EXPECT_EQ(config.pool_size, kFlagPoolSize) << value;
+        EXPECT_NE(logs.find("Invalid MC_MMAP_ARENA_POOL_SIZE='"),
+                  std::string::npos)
+            << value;
+    }
+}
+
+TEST_F(MmapArenaConfigTest, DisableEnvironmentUsesCanonicalBooleanTokens) {
+    env.pool_size.Set("2mb");
+    for (const char* value : {"1", " TRUE ", "yes", "on", "enable"}) {
+        env.disable.Set(value);
+        EXPECT_FALSE(
+            MmapArenaConfig::FromEnvironment(false, kFlagPoolSize).enabled)
+            << value;
+    }
+
+    for (const char* value : {"0", " false ", "no", "off", "disable"}) {
+        env.disable.Set(value);
+        EXPECT_TRUE(
+            MmapArenaConfig::FromEnvironment(false, kFlagPoolSize).enabled)
+            << value;
+    }
+
+    env.disable.Set("true");
+    EXPECT_FALSE(MmapArenaConfig::FromEnvironment(true, kFlagPoolSize).enabled);
+}
+
+TEST_F(MmapArenaConfigTest, InvalidDisableValueWarnsAndFallsBackToFalse) {
+    env.disable.Set("maybe");
+    ::testing::internal::CaptureStderr();
+
+    const auto config = MmapArenaConfig::FromEnvironment(true, kFlagPoolSize);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_NE(logs.find("Ignoring invalid MC_DISABLE_MMAP_ARENA='maybe'"),
+              std::string::npos);
+}
+
+TEST_F(MmapArenaConfigTest, DisabledPathSkipsHugepageAndPoolValidation) {
+    env.pool_size.Set("invalid");
+    env.disable.Set("true");
+    env.use_hugepage.Set("1");
+    env.hugepage_size.Set("invalid");
+    ::testing::internal::CaptureStderr();
+
+    const auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(logs.find("Invalid MC_STORE_HUGEPAGE_SIZE"), std::string::npos);
+    EXPECT_EQ(logs.find("Invalid MC_MMAP_ARENA_POOL_SIZE"), std::string::npos);
+}
+
+TEST_F(MmapArenaConfigTest, PreservesValidationDiagnosticOrder) {
+    env.pool_size.Set("invalid");
+    env.disable.Set("maybe");
+    env.use_hugepage.Set("1");
+    env.hugepage_size.Set("invalid");
+    ::testing::internal::CaptureStderr();
+
+    const auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+    const std::string logs = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.enabled);
+    const size_t disable_warning =
+        logs.find("Ignoring invalid MC_DISABLE_MMAP_ARENA");
+    const size_t hugepage_warning = logs.find("Invalid MC_STORE_HUGEPAGE_SIZE");
+    const size_t pool_warning = logs.find("Invalid MC_MMAP_ARENA_POOL_SIZE");
+    ASSERT_NE(disable_warning, std::string::npos);
+    ASSERT_NE(hugepage_warning, std::string::npos);
+    ASSERT_NE(pool_warning, std::string::npos);
+    EXPECT_LT(disable_warning, hugepage_warning);
+    EXPECT_LT(hugepage_warning, pool_warning);
+}
+
+TEST_F(MmapArenaConfigTest, AnyPresentHugepageFlagIsAnExplicitRequest) {
+    env.use_hugepage.Set("0");
+
+    const auto config = MmapArenaConfig::FromEnvironment(true, kFlagPoolSize);
+
+    EXPECT_TRUE(config.enabled);
+    EXPECT_TRUE(config.hugepages_explicitly_requested);
+}
+
+TEST_F(MmapArenaConfigTest, EachConstructionReadsCurrentEnvironment) {
+    env.pool_size.Set("2mb");
+    auto config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.pool_size, 2ULL * 1024 * 1024);
+
+    env.pool_size.Unset();
+    config = MmapArenaConfig::FromEnvironment(false, kFlagPoolSize);
+    EXPECT_FALSE(config.enabled);
+    EXPECT_EQ(config.pool_size, kFlagPoolSize);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/mmap_arena_fallback_test.cpp b/mooncake-store/tests/mmap_arena_fallback_test.cpp
index 85f0fc7806..417953c176 100644
--- a/mooncake-store/tests/mmap_arena_fallback_test.cpp
+++ b/mooncake-store/tests/mmap_arena_fallback_test.cpp
@@ -13,7 +13,22 @@
 #include <string>
 #include <vector>
 
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
+
+#if defined(__has_feature)
+#define MC_HAS_FEATURE(x) __has_feature(x)
+#else
+#define MC_HAS_FEATURE(x) 0
+#endif
+#if defined(__SANITIZE_ADDRESS__) || MC_HAS_FEATURE(address_sanitizer) || \
+    MC_HAS_FEATURE(leak_sanitizer)
+// Suppress false positives from libnuma.so process-wide caches that are
+// intentionally retained until process exit.
+extern "C" __attribute__((weak, visibility("default"))) const char*
+__lsan_default_suppressions() {
+    return "leak:libnuma.so\n";
+}
+#endif
 
 namespace mooncake {
 
@@ -77,7 +92,6 @@ TEST_F(MmapArenaFallbackTest, PopulateNumaHugetlbMappingTouchesEveryRegion) {
     if (numa_available() < 0) {
         GTEST_SKIP() << "NUMA is unavailable";
     }
-
     setenv("MC_STORE_USE_HUGEPAGE", "1", 1);
     setenv("MC_STORE_HUGEPAGE_SIZE", "2MB", 1);
 
diff --git a/mooncake-store/tests/mmap_arena_test.cpp b/mooncake-store/tests/mmap_arena_test.cpp
index 438aea2b14..53ce5ef075 100644
--- a/mooncake-store/tests/mmap_arena_test.cpp
+++ b/mooncake-store/tests/mmap_arena_test.cpp
@@ -5,7 +5,6 @@
 #include <gtest/gtest.h>
 #include <glog/logging.h>
 #include "mmap_arena.h"
-#include "utils.h"
 #include <thread>
 #include <vector>
 #include <atomic>
diff --git a/mooncake-store/tests/mutex_test.cpp b/mooncake-store/tests/mutex_test.cpp
index 8ded4cc8cf..032bbcaeec 100644
--- a/mooncake-store/tests/mutex_test.cpp
+++ b/mooncake-store/tests/mutex_test.cpp
@@ -79,58 +79,83 @@ TEST(SharedMutexTest, SharedAccessIsConcurrent) {
 
 TEST(SharedMutexTest, WriterBlocksReaders) {
     SharedMutex mtx;
-    std::atomic<bool> reader_started{false};
-    std::atomic<bool> writer_proceeded{false};
+    mtx.lock();
 
+    bool reader_acquired = false;
     std::thread reader([&]() {
-        mtx.lock_shared();
-        reader_started = true;
-        while (!writer_proceeded) {
-            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        reader_acquired = mtx.try_lock_shared();
+        if (reader_acquired) {
+            mtx.unlock_shared();
         }
-        mtx.unlock_shared();
     });
-
-    // Give reader time to start
-    std::this_thread::sleep_for(std::chrono::milliseconds(50));
-
-    auto try_write =
-        mtx.try_lock();  // Should fail because reader holds shared lock
-    EXPECT_FALSE(try_write);
-
-    // Let reader finish
-    writer_proceeded = true;
     reader.join();
+    EXPECT_FALSE(reader_acquired);
 
-    // Now writer should be able to acquire the lock
-    mtx.lock();
-    EXPECT_TRUE(true);  // No deadlock occurred
     mtx.unlock();
+
+    const bool reader_acquired_after_unlock = mtx.try_lock_shared();
+    EXPECT_TRUE(reader_acquired_after_unlock);
+    if (reader_acquired_after_unlock) {
+        mtx.unlock_shared();
+    }
 }
 
 TEST(SharedMutexTest, LocksOnConstructionExclusive) {
     SharedMutex mtx;
     {
         SharedMutexLocker locker(&mtx);
-        // Lock should still be held before destruction
-        EXPECT_FALSE(mtx.try_lock());  // Cannot acquire another exclusive lock
-        EXPECT_FALSE(mtx.try_lock_shared());  // Shared lock may also be blocked
-                                              // (implementation-defined)
-    }  // Destructor automatically unlocks
-    EXPECT_TRUE(mtx.try_lock());  // After destruction, lock should be available
+        bool exclusive_acquired = false;
+        bool shared_acquired = false;
+        std::thread contender([&]() {
+            exclusive_acquired = mtx.try_lock();
+            if (exclusive_acquired) {
+                mtx.unlock();
+            }
+            shared_acquired = mtx.try_lock_shared();
+            if (shared_acquired) {
+                mtx.unlock_shared();
+            }
+        });
+        contender.join();
+
+        EXPECT_FALSE(exclusive_acquired);
+        EXPECT_FALSE(shared_acquired);
+    }
+
+    const bool exclusive_acquired = mtx.try_lock();
+    EXPECT_TRUE(exclusive_acquired);
+    if (exclusive_acquired) {
+        mtx.unlock();
+    }
 }
 
 TEST(SharedMutexTest, LocksOnConstructionShared) {
     SharedMutex mtx;
     {
         SharedMutexLocker locker(&mtx, shared_lock);
-        EXPECT_TRUE(
-            mtx.try_lock_shared());  // Multiple shared locks should be allowed
-        // Note: This test does not attempt recursive locking (UB), just checks
-        // concurrent shared access.
+        bool shared_acquired = false;
+        bool exclusive_acquired = false;
+        std::thread contender([&]() {
+            shared_acquired = mtx.try_lock_shared();
+            if (shared_acquired) {
+                mtx.unlock_shared();
+            }
+            exclusive_acquired = mtx.try_lock();
+            if (exclusive_acquired) {
+                mtx.unlock();
+            }
+        });
+        contender.join();
+
+        EXPECT_TRUE(shared_acquired);
+        EXPECT_FALSE(exclusive_acquired);
+    }
+
+    const bool shared_acquired = mtx.try_lock_shared();
+    EXPECT_TRUE(shared_acquired);
+    if (shared_acquired) {
+        mtx.unlock_shared();
     }
-    EXPECT_TRUE(
-        mtx.try_lock_shared());  // Should still be available after unlock
 }
 
 TEST(SharedMutexTest, ManualLockUnlock) {
@@ -139,8 +164,12 @@ TEST(SharedMutexTest, ManualLockUnlock) {
     EXPECT_NO_THROW(locker.unlock());  // Unlocking a null locker should be safe
 
     SharedMutexLocker temp(&mtx);
-    temp.unlock();                // Manually release the lock
-    EXPECT_TRUE(mtx.try_lock());  // Now we should be able to acquire it
+    temp.unlock();
+    const bool acquired = mtx.try_lock();
+    EXPECT_TRUE(acquired);
+    if (acquired) {
+        mtx.unlock();
+    }
 }
 
 TEST(SharedMutexTest, TryLockSuccess) {
@@ -151,6 +180,7 @@ TEST(SharedMutexTest, TryLockSuccess) {
     bool result = locker.try_lock();
     EXPECT_TRUE(result);
     EXPECT_FALSE(locker.try_lock());  // Should not allow re-locking
+    locker.unlock();
 }
 
 TEST(SharedMutexTest, TryLockSharedSuccess) {
@@ -161,6 +191,7 @@ TEST(SharedMutexTest, TryLockSharedSuccess) {
     bool result = locker.try_lock_shared();
     EXPECT_TRUE(result);
     EXPECT_FALSE(locker.try_lock_shared());  // Should not allow re-locking
+    locker.unlock();
 }
 
 TEST(SharedMutexTest, HandlesNullptrSafely) {
@@ -247,4 +278,4 @@ TEST(SpinLockTest, SpinLockerTest) {
     EXPECT_FALSE(lock.is_locked());
 }
 
-}  // namespace mooncake::test
\ No newline at end of file
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/utils_test.cpp b/mooncake-store/tests/network_test.cpp
similarity index 58%
rename from mooncake-store/tests/utils_test.cpp
rename to mooncake-store/tests/network_test.cpp
index ef224eb203..ee9f7c80f2 100644
--- a/mooncake-store/tests/utils_test.cpp
+++ b/mooncake-store/tests/network_test.cpp
@@ -1,112 +1,14 @@
-#include "utils.h"
-#include "random.h"
+#include "common/network.h"
 
-#include <cstdint>
-#include <future>
-#include <gtest/gtest.h>
+#include <cerrno>
+#include <cstring>
 #include <netinet/in.h>
-#include <random>
 #include <sys/socket.h>
-#include <thread>
 #include <unistd.h>
-#include <errno.h>
-
-using namespace mooncake;
-
-TEST(RandomTest, ReusesEngineWithinThread) {
-    EXPECT_EQ(&threadLocalRandomEngine(), &threadLocalRandomEngine());
-}
-
-TEST(RandomTest, UsesDifferentEngineAcrossThreads) {
-    auto* main_engine = &threadLocalRandomEngine();
-    std::promise<RandomEngine*> worker_address;
-    std::promise<void> release_worker;
-    auto release_future = release_worker.get_future();
-
-    std::thread worker([&] {
-        worker_address.set_value(&threadLocalRandomEngine());
-        release_future.wait();
-    });
-
-    EXPECT_NE(main_engine, worker_address.get_future().get());
-    release_worker.set_value();
-    worker.join();
-}
-
-TEST(RandomTest, RandomIndexStaysWithinBounds) {
-    std::mt19937_64 engine(42);
-    for (size_t i = 0; i < 10000; ++i) {
-        EXPECT_LT(randomIndex(17, engine), 17);
-    }
-}
-
-TEST(RandomTest, ExplicitEngineIsDeterministic) {
-    std::mt19937_64 first(42);
-    std::mt19937_64 second(42);
-    for (size_t i = 0; i < 100; ++i) {
-        EXPECT_EQ(randomIndex(1000, first), randomIndex(1000, second));
-    }
-}
 
-TEST(RandomTest, RandomUniformIncludesRequestedBounds) {
-    std::mt19937_64 engine(42);
-    for (size_t i = 0; i < 10000; ++i) {
-        int value = randomUniform(-5, 9, engine);
-        EXPECT_GE(value, -5);
-        EXPECT_LE(value, 9);
-    }
-    EXPECT_EQ(randomUniform(7, 7, engine), 7);
-}
-
-TEST(RandomTest, RandomUniformSupportsNarrowIntegers) {
-    std::mt19937_64 engine(42);
-    for (size_t i = 0; i < 1000; ++i) {
-        auto signed_value = randomUniform<int8_t>(-5, 9, engine);
-        EXPECT_GE(signed_value, -5);
-        EXPECT_LE(signed_value, 9);
-
-        auto unsigned_value = randomUniform<uint8_t>(2, 7, engine);
-        EXPECT_GE(unsigned_value, 2);
-        EXPECT_LE(unsigned_value, 7);
-    }
-    EXPECT_FALSE(randomUniform<bool>(false, false, engine));
-    EXPECT_TRUE(randomUniform<bool>(true, true, engine));
-}
-
-TEST(RandomTest, RejectsInvalidBounds) {
-    std::mt19937_64 engine(42);
-    EXPECT_THROW(randomIndex(0, engine), std::invalid_argument);
-    EXPECT_THROW(randomUniform(2, 1, engine), std::invalid_argument);
-}
-
-TEST(UtilsTest, ByteSizeToString) {
-    EXPECT_EQ(byte_size_to_string(999), "999 B");
-    EXPECT_EQ(byte_size_to_string(2048), "2.00 KB");
-    EXPECT_EQ(byte_size_to_string(5ULL * 1024 * 1024 + 1234), "5.00 MB");
-    EXPECT_EQ(byte_size_to_string(15ULL * 1024 * 1024 * 1024), "15.00 GB");
-    EXPECT_EQ(byte_size_to_string(0), "0 B");
-    EXPECT_EQ(byte_size_to_string(1), "1 B");
-    EXPECT_EQ(byte_size_to_string(1024), "1.00 KB");
-    EXPECT_EQ(byte_size_to_string(1024 * 1024), "1.00 MB");
-    EXPECT_EQ(byte_size_to_string(1024ULL * 1024 * 1024), "1.00 GB");
-    EXPECT_EQ(byte_size_to_string(1024ULL * 1024 * 1024 * 1024), "1.00 TB");
-    EXPECT_EQ(byte_size_to_string(15 * 1024 + 134), "15.13 KB");
-    EXPECT_EQ(byte_size_to_string(15 * 1024 * 1024 + 44048), "15.04 MB");
-}
-
-TEST(UtilsTest, StringToByteSize) {
-    auto parsed = try_string_to_byte_size("16 MB");
-    ASSERT_TRUE(parsed.has_value());
-    EXPECT_EQ(parsed.value(), 16ULL * 1024 * 1024);
-
-    parsed = try_string_to_byte_size("0");
-    ASSERT_TRUE(parsed.has_value());
-    EXPECT_EQ(parsed.value(), 0);
+#include <gtest/gtest.h>
 
-    EXPECT_FALSE(try_string_to_byte_size("-5").has_value());
-    EXPECT_FALSE(try_string_to_byte_size("16XB").has_value());
-    EXPECT_EQ(string_to_byte_size("-5"), 0);
-}
+using namespace mooncake;
 
 TEST(UtilsTest, IsPortAvailable) {
     // Find an available port
diff --git a/mooncake-store/tests/nof_heartbeat_test.cpp b/mooncake-store/tests/nof_heartbeat_test.cpp
index 765e8cdcc3..402afa1898 100644
--- a/mooncake-store/tests/nof_heartbeat_test.cpp
+++ b/mooncake-store/tests/nof_heartbeat_test.cpp
@@ -1,4 +1,5 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
@@ -72,7 +73,7 @@ TEST_F(NoFHeartbeatTest, HealthyNoFSegmentDoesNotUnmount) {
                                  /*probe_timeout_ms=*/50,
                                  /*failure_threshold=*/3);
     std::atomic<int> probe_calls{0};
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [&probe_calls](const std::string&, uint32_t, std::string*) {
             probe_calls.fetch_add(1, std::memory_order_relaxed);
             return true;
@@ -85,10 +86,14 @@ TEST_F(NoFHeartbeatTest, HealthyNoFSegmentDoesNotUnmount) {
     ASSERT_TRUE(WaitForCondition(std::chrono::milliseconds(2500),
                                  std::chrono::milliseconds(50),
                                  [&]() { return probe_calls.load() >= 1; }));
-    EXPECT_TRUE(service->IsNoFSegmentMountedForTesting(segment.id));
-    EXPECT_EQ(service->GetMountedNoFSegmentCountForTesting(), 1u);
+    EXPECT_TRUE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        segment.id));
+    EXPECT_EQ(
+        MasterServiceTestPeer(*service).GetMountedNoFSegmentCountForTesting(),
+        1u);
     auto failure_count =
-        service->GetNoFHeartbeatFailureCountForTesting(segment.id);
+        MasterServiceTestPeer(*service).GetNoFHeartbeatFailureCountForTesting(
+            segment.id);
     ASSERT_TRUE(failure_count.has_value());
     EXPECT_EQ(*failure_count, 0u);
 }
@@ -98,7 +103,7 @@ TEST_F(NoFHeartbeatTest, NewlyMountedNoFSegmentHasInitialGracePeriod) {
                                  /*probe_timeout_ms=*/50,
                                  /*failure_threshold=*/1);
     std::atomic<int> probe_calls{0};
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [&probe_calls](const std::string&, uint32_t, std::string* reason) {
             probe_calls.fetch_add(1, std::memory_order_relaxed);
             if (reason) {
@@ -114,9 +119,11 @@ TEST_F(NoFHeartbeatTest, NewlyMountedNoFSegmentHasInitialGracePeriod) {
     std::this_thread::sleep_for(std::chrono::milliseconds(800));
 
     EXPECT_EQ(probe_calls.load(), 0);
-    EXPECT_TRUE(service->IsNoFSegmentMountedForTesting(segment.id));
+    EXPECT_TRUE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        segment.id));
     auto failure_count =
-        service->GetNoFHeartbeatFailureCountForTesting(segment.id);
+        MasterServiceTestPeer(*service).GetNoFHeartbeatFailureCountForTesting(
+            segment.id);
     ASSERT_TRUE(failure_count.has_value());
     EXPECT_EQ(*failure_count, 0u);
 }
@@ -126,7 +133,7 @@ TEST_F(NoFHeartbeatTest, FailedNoFSegmentUnmountsAfterThreshold) {
                                  /*probe_timeout_ms=*/50,
                                  /*failure_threshold=*/3);
     std::atomic<int> probe_calls{0};
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [&probe_calls](const std::string&, uint32_t, std::string* reason) {
             probe_calls.fetch_add(1, std::memory_order_relaxed);
             if (reason) {
@@ -140,12 +147,17 @@ TEST_F(NoFHeartbeatTest, FailedNoFSegmentUnmountsAfterThreshold) {
     ASSERT_TRUE(service->MountNoFSegment(segment, client_id).has_value());
 
     ASSERT_TRUE(WaitForCondition(
-        std::chrono::milliseconds(5000), std::chrono::milliseconds(50),
-        [&]() { return !service->IsNoFSegmentMountedForTesting(segment.id); }));
+        std::chrono::milliseconds(5000), std::chrono::milliseconds(50), [&]() {
+            return !MasterServiceTestPeer(*service)
+                        .IsNoFSegmentMountedForTesting(segment.id);
+        }));
     EXPECT_GE(probe_calls.load(), 3);
-    EXPECT_EQ(service->GetMountedNoFSegmentCountForTesting(), 0u);
-    EXPECT_FALSE(
-        service->GetNoFHeartbeatFailureCountForTesting(segment.id).has_value());
+    EXPECT_EQ(
+        MasterServiceTestPeer(*service).GetMountedNoFSegmentCountForTesting(),
+        0u);
+    EXPECT_FALSE(MasterServiceTestPeer(*service)
+                     .GetNoFHeartbeatFailureCountForTesting(segment.id)
+                     .has_value());
 }
 
 TEST_F(NoFHeartbeatTest, FailureCountResetsAfterRecovery) {
@@ -153,7 +165,7 @@ TEST_F(NoFHeartbeatTest, FailureCountResetsAfterRecovery) {
                                  /*probe_timeout_ms=*/50,
                                  /*failure_threshold=*/3);
     std::atomic<int> probe_calls{0};
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [&probe_calls](const std::string&, uint32_t, std::string* reason) {
             int current = probe_calls.fetch_add(1, std::memory_order_relaxed);
             if (current < 2) {
@@ -172,11 +184,13 @@ TEST_F(NoFHeartbeatTest, FailureCountResetsAfterRecovery) {
     ASSERT_TRUE(WaitForCondition(
         std::chrono::milliseconds(5000), std::chrono::milliseconds(50), [&]() {
             auto failure_count =
-                service->GetNoFHeartbeatFailureCountForTesting(segment.id);
+                MasterServiceTestPeer(*service)
+                    .GetNoFHeartbeatFailureCountForTesting(segment.id);
             return probe_calls.load() >= 4 && failure_count.has_value() &&
                    *failure_count == 0;
         }));
-    EXPECT_TRUE(service->IsNoFSegmentMountedForTesting(segment.id));
+    EXPECT_TRUE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        segment.id));
 }
 
 TEST_F(NoFHeartbeatTest, OnlyFailedSegmentIsUnmounted) {
@@ -185,7 +199,7 @@ TEST_F(NoFHeartbeatTest, OnlyFailedSegmentIsUnmounted) {
                                  /*failure_threshold=*/2);
     std::atomic<int> good_probe_calls{0};
     std::atomic<int> bad_probe_calls{0};
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [&good_probe_calls, &bad_probe_calls](const std::string& endpoint,
                                               uint32_t, std::string* reason) {
             if (endpoint == "nof_good") {
@@ -210,10 +224,13 @@ TEST_F(NoFHeartbeatTest, OnlyFailedSegmentIsUnmounted) {
 
     ASSERT_TRUE(WaitForCondition(
         std::chrono::milliseconds(5000), std::chrono::milliseconds(50), [&]() {
-            return service->GetMountedNoFSegmentCountForTesting() == 1u;
+            return MasterServiceTestPeer(*service)
+                       .GetMountedNoFSegmentCountForTesting() == 1u;
         }));
-    EXPECT_TRUE(service->IsNoFSegmentMountedForTesting(good_segment.id));
-    EXPECT_FALSE(service->IsNoFSegmentMountedForTesting(bad_segment.id));
+    EXPECT_TRUE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        good_segment.id));
+    EXPECT_FALSE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        bad_segment.id));
     EXPECT_GE(good_probe_calls.load(), 1);
     EXPECT_GE(bad_probe_calls.load(), 2);
 }
@@ -223,7 +240,7 @@ TEST_F(NoFHeartbeatTest, ClientExpiryDoesNotUnmountNoFSegment) {
                                  /*probe_timeout_ms=*/50,
                                  /*failure_threshold=*/1,
                                  /*client_ttl_sec=*/1);
-    service->SetNoFProbeFnForTesting(
+    MasterServiceTestPeer(*service).SetNoFProbeFnForTesting(
         [](const std::string&, uint32_t, std::string* reason) {
             if (reason) {
                 *reason = "submit_fail";
@@ -238,10 +255,14 @@ TEST_F(NoFHeartbeatTest, ClientExpiryDoesNotUnmountNoFSegment) {
 
     std::this_thread::sleep_for(std::chrono::milliseconds(1800));
 
-    EXPECT_TRUE(service->IsNoFSegmentMountedForTesting(segment.id));
-    EXPECT_EQ(service->GetMountedNoFSegmentCountForTesting(), 1u);
+    EXPECT_TRUE(MasterServiceTestPeer(*service).IsNoFSegmentMountedForTesting(
+        segment.id));
+    EXPECT_EQ(
+        MasterServiceTestPeer(*service).GetMountedNoFSegmentCountForTesting(),
+        1u);
     auto failure_count =
-        service->GetNoFHeartbeatFailureCountForTesting(segment.id);
+        MasterServiceTestPeer(*service).GetNoFHeartbeatFailureCountForTesting(
+            segment.id);
     ASSERT_TRUE(failure_count.has_value());
     EXPECT_EQ(*failure_count, 0u);
 }
diff --git a/mooncake-store/tests/nof_register_config_test.cpp b/mooncake-store/tests/nof_register_config_test.cpp
new file mode 100644
index 0000000000..1204ae4d4c
--- /dev/null
+++ b/mooncake-store/tests/nof_register_config_test.cpp
@@ -0,0 +1,112 @@
+#include "../src/config/nof_register_config.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class NoFRegisterConfigTest : public ::testing::Test {
+   protected:
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("NoFRegisterConfigTest");
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void SetUp() override {
+        original_logtostderr_ = FLAGS_logtostderr;
+        FLAGS_logtostderr = true;
+        if (const char* value = std::getenv("MC_NOF_TRTYPE")) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv("MC_NOF_TRTYPE"), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv("MC_NOF_TRTYPE", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_NOF_TRTYPE"), 0);
+        }
+        FLAGS_logtostderr = original_logtostderr_;
+    }
+
+   private:
+    std::optional<std::string> original_;
+    bool original_logtostderr_ = false;
+};
+
+TEST_F(NoFRegisterConfigTest, UnsetTransportDefaultsToRdmaSilently) {
+    testing::internal::CaptureStderr();
+    const auto config = NoFRegisterConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_EQ(config.transport_type, "RDMA");
+    EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+}
+
+TEST_F(NoFRegisterConfigTest, ValidTransportIsCaseInsensitive) {
+    struct Case {
+        const char* value;
+        const char* expected;
+    };
+    const Case cases[] = {{"RDMA", "RDMA"}, {"rdma", "RDMA"}, {"RdMa", "RDMA"},
+                          {"TCP", "TCP"},   {"tcp", "TCP"},   {"TcP", "TCP"}};
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        ASSERT_EQ(setenv("MC_NOF_TRTYPE", entry.value, 1), 0);
+
+        testing::internal::CaptureStderr();
+        const auto config = NoFRegisterConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.transport_type, entry.expected);
+        EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+    }
+}
+
+TEST_F(NoFRegisterConfigTest, EmptyAndInvalidValuesWarnAndFallbackToRdma) {
+    struct Case {
+        const char* value;
+        const char* normalized;
+    };
+    const Case cases[] = {{"", ""},
+                          {"udp", "UDP"},
+                          {" tcp", " TCP"},
+                          {"tcp ", "TCP "},
+                          {"1", "1"}};
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        ASSERT_EQ(setenv("MC_NOF_TRTYPE", entry.value, 1), 0);
+
+        testing::internal::CaptureStderr();
+        const auto config = NoFRegisterConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.transport_type, "RDMA");
+        EXPECT_NE(diagnostics.find(std::string("Invalid MC_NOF_TRTYPE=") +
+                                   entry.normalized + ", fallback to RDMA"),
+                  std::string::npos);
+    }
+}
+
+TEST_F(NoFRegisterConfigTest, NewConfigsReadCurrentEnvironment) {
+    ASSERT_EQ(setenv("MC_NOF_TRTYPE", "tcp", 1), 0);
+    const auto first = NoFRegisterConfig::FromEnvironment();
+    ASSERT_EQ(setenv("MC_NOF_TRTYPE", "rdma", 1), 0);
+    const auto second = NoFRegisterConfig::FromEnvironment();
+    ASSERT_EQ(unsetenv("MC_NOF_TRTYPE"), 0);
+    const auto third = NoFRegisterConfig::FromEnvironment();
+
+    EXPECT_EQ(first.transport_type, "TCP");
+    EXPECT_EQ(second.transport_type, "RDMA");
+    EXPECT_EQ(third.transport_type, "RDMA");
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/non_ha_reconnect_test.cpp b/mooncake-store/tests/non_ha_reconnect_test.cpp
index 4c3de3a4cb..a7ab5305fc 100644
--- a/mooncake-store/tests/non_ha_reconnect_test.cpp
+++ b/mooncake-store/tests/non_ha_reconnect_test.cpp
@@ -15,7 +15,7 @@
 
 #include "client_service.h"
 #include "master_metric_manager.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 #include "test_server_helpers.h"
 #include "default_config.h"
 
diff --git a/mooncake-store/tests/nvme_kv/connector_config_test.cpp b/mooncake-store/tests/nvme_kv/connector_config_test.cpp
new file mode 100644
index 0000000000..8709f92223
--- /dev/null
+++ b/mooncake-store/tests/nvme_kv/connector_config_test.cpp
@@ -0,0 +1,208 @@
+#include "../../src/nvme_kv/config/connector_config.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class NvmeKvConnectorConfigTest : public ::testing::Test {
+   protected:
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("NvmeKvConnectorConfigTest");
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void SetUp() override {
+        original_logtostderr_ = FLAGS_logtostderr;
+        FLAGS_logtostderr = true;
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_[i] = value;
+            }
+            ASSERT_EQ(unsetenv(kVariables[i]), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(kVariables[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+        FLAGS_logtostderr = original_logtostderr_;
+    }
+
+    void SetDevicePath() {
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_DEVICE_PATH", "/dev/nvme0n1", 1), 0);
+    }
+
+   private:
+    inline static constexpr std::array<const char*, 5> kVariables = {
+        "MOONCAKE_NVME_KV_DEVICE_PATH", "MOONCAKE_NVME_KV_NSID",
+        "MOONCAKE_NVME_KV_QUEUE_DEPTH",
+        "MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT",
+        "MOONCAKE_NVME_KV_TRANSPORT"};
+    std::array<std::optional<std::string>, kVariables.size()> original_;
+    bool original_logtostderr_ = false;
+};
+
+TEST_F(NvmeKvConnectorConfigTest, MissingDevicePathStopsBeforeTransport) {
+    ASSERT_EQ(setenv("MOONCAKE_NVME_KV_TRANSPORT", "invalid", 1), 0);
+
+    testing::internal::CaptureStderr();
+    const auto config = NvmeKvConnectorConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    ASSERT_FALSE(config.has_value());
+    EXPECT_EQ(config.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_NE(
+        diagnostics.find("MOONCAKE_NVME_KV_DEVICE_PATH must not be empty"),
+        std::string::npos);
+    EXPECT_EQ(diagnostics.find("Unknown MOONCAKE_NVME_KV_TRANSPORT"),
+              std::string::npos);
+}
+
+TEST_F(NvmeKvConnectorConfigTest, EmptyDevicePathIsRejected) {
+    ASSERT_EQ(setenv("MOONCAKE_NVME_KV_DEVICE_PATH", "", 1), 0);
+
+    testing::internal::CaptureStderr();
+    const auto config = NvmeKvConnectorConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    ASSERT_FALSE(config.has_value());
+    EXPECT_EQ(config.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_NE(
+        diagnostics.find("MOONCAKE_NVME_KV_DEVICE_PATH must not be empty"),
+        std::string::npos);
+}
+
+TEST_F(NvmeKvConnectorConfigTest, UnsetOptionalValuesKeepRealExecutorDefaults) {
+    SetDevicePath();
+
+    const auto config = NvmeKvConnectorConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_EQ(config->device_path, "/dev/nvme0n1");
+    EXPECT_EQ(config->nsid, 1u);
+    EXPECT_EQ(config->queue_depth, 256u);
+    EXPECT_EQ(config->runtime_transfer_limit, 270336u);
+    EXPECT_EQ(config->transport, NvmeKvTransport::kAuto);
+}
+
+TEST_F(NvmeKvConnectorConfigTest, PreservesLegacyUnsignedIntegerSyntax) {
+    struct Case {
+        const char* value;
+        uint32_t expected;
+    };
+    const Case cases[] = {{"0", 0u},
+                          {"+17", 17u},
+                          {" 17", 17u},
+                          {"010", 8u},
+                          {"0x10", 16u},
+                          {"-0", 0u},
+                          {"4294967295", std::numeric_limits<uint32_t>::max()}};
+    SetDevicePath();
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_NSID", entry.value, 1), 0);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_QUEUE_DEPTH", entry.value, 1), 0);
+        ASSERT_EQ(
+            setenv("MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT", entry.value, 1),
+            0);
+
+        const auto config = NvmeKvConnectorConfig::FromEnvironment();
+
+        ASSERT_TRUE(config.has_value());
+        EXPECT_EQ(config->nsid, entry.expected);
+        EXPECT_EQ(config->queue_depth, entry.expected);
+        EXPECT_EQ(config->runtime_transfer_limit, entry.expected);
+    }
+}
+
+TEST_F(NvmeKvConnectorConfigTest, InvalidUnsignedIntegersKeepDefaultsSilently) {
+    const char* values[] = {"", "17 ", "17x", "-1", "0x", "4294967296", "abc"};
+    SetDevicePath();
+    for (const char* value : values) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_NSID", value, 1), 0);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_QUEUE_DEPTH", value, 1), 0);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT", value, 1),
+                  0);
+
+        testing::internal::CaptureStderr();
+        const auto config = NvmeKvConnectorConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        ASSERT_TRUE(config.has_value());
+        EXPECT_EQ(config->nsid, 1u);
+        EXPECT_EQ(config->queue_depth, 256u);
+        EXPECT_EQ(config->runtime_transfer_limit, 270336u);
+        EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+    }
+}
+
+TEST_F(NvmeKvConnectorConfigTest, AcceptsOnlyExistingTransportTokens) {
+    struct Case {
+        const char* value;
+        NvmeKvTransport expected;
+    };
+    const Case cases[] = {{"", NvmeKvTransport::kAuto},
+                          {"auto", NvmeKvTransport::kAuto},
+                          {"io_uring", NvmeKvTransport::kIoUring},
+                          {"ioctl", NvmeKvTransport::kIoctl}};
+    SetDevicePath();
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_TRANSPORT", entry.value, 1), 0);
+
+        const auto config = NvmeKvConnectorConfig::FromEnvironment();
+
+        ASSERT_TRUE(config.has_value());
+        EXPECT_EQ(config->transport, entry.expected);
+    }
+}
+
+TEST_F(NvmeKvConnectorConfigTest, InvalidTransportKeepsErrorAndDiagnostic) {
+    SetDevicePath();
+    for (const char* value : {"AUTO", "io-uring", " ioctl", "invalid"}) {
+        SCOPED_TRACE(value);
+        ASSERT_EQ(setenv("MOONCAKE_NVME_KV_TRANSPORT", value, 1), 0);
+
+        testing::internal::CaptureStderr();
+        const auto config = NvmeKvConnectorConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+
+        ASSERT_FALSE(config.has_value());
+        EXPECT_EQ(config.error(), ErrorCode::INVALID_PARAMS);
+        EXPECT_NE(diagnostics.find(std::string("Unknown ") +
+                                   "MOONCAKE_NVME_KV_TRANSPORT: " + value),
+                  std::string::npos);
+    }
+}
+
+TEST_F(NvmeKvConnectorConfigTest, NewConfigsReadCurrentEnvironment) {
+    SetDevicePath();
+    ASSERT_EQ(setenv("MOONCAKE_NVME_KV_NSID", "1", 1), 0);
+    const auto first = NvmeKvConnectorConfig::FromEnvironment();
+    ASSERT_EQ(setenv("MOONCAKE_NVME_KV_NSID", "2", 1), 0);
+    const auto second = NvmeKvConnectorConfig::FromEnvironment();
+
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+    EXPECT_EQ(first->nsid, 1u);
+    EXPECT_EQ(second->nsid, 2u);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/nvme_kv/io_concurrency_config_test.cpp b/mooncake-store/tests/nvme_kv/io_concurrency_config_test.cpp
new file mode 100644
index 0000000000..2675a0e29e
--- /dev/null
+++ b/mooncake-store/tests/nvme_kv/io_concurrency_config_test.cpp
@@ -0,0 +1,153 @@
+#include "../../src/nvme_kv/config/io_concurrency_config.h"
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdlib>
+#include <mutex>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class NvmeKvIoConcurrencyConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        environment_lock_ = std::unique_lock<std::mutex>(environment_mutex_);
+        for (std::size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_values_[i] = value;
+            }
+            ASSERT_EQ(unsetenv(kVariables[i]), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (std::size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_values_[i].has_value()) {
+                EXPECT_EQ(
+                    setenv(kVariables[i], original_values_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+    }
+
+    void SetEnvironment(const char* name, const char* value) {
+        ASSERT_EQ(setenv(name, value, 1), 0);
+    }
+
+    void ExpectConfig(const NvmeKvIoConcurrencyConfig& config,
+                      std::size_t maximum, std::size_t io, std::size_t batch,
+                      std::size_t root, std::size_t prepare) {
+        EXPECT_EQ(config.max_io_concurrency, maximum);
+        EXPECT_EQ(config.io_concurrency, io);
+        EXPECT_EQ(config.batch_submit_concurrency, batch);
+        EXPECT_EQ(config.root_submit_concurrency, root);
+        EXPECT_EQ(config.prepare_concurrency, prepare);
+    }
+
+    inline static constexpr std::array<const char*, 5> kVariables = {
+        "MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY",
+        "MOONCAKE_NVME_KV_IO_CONCURRENCY",
+        "MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY",
+        "MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY",
+        "MOONCAKE_NVME_KV_PREPARE_CONCURRENCY"};
+
+   private:
+    inline static std::mutex environment_mutex_;
+    std::unique_lock<std::mutex> environment_lock_;
+    std::array<std::optional<std::string>, kVariables.size()> original_values_;
+};
+
+TEST_F(NvmeKvIoConcurrencyConfigTest, DefaultsFollowDeviceQueueDepth) {
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(0), 256, 1, 1, 1,
+                 1);
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(8), 256, 8, 6, 1,
+                 2);
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 256, 18, 6, 1,
+                 12);
+}
+
+TEST_F(NvmeKvIoConcurrencyConfigTest, PreservesLegacyUnsignedSyntax) {
+    struct Case {
+        const char* value;
+        std::size_t expected;
+    };
+    const Case cases[] = {{"+17", 17}, {" 17", 17},
+                          {"010", 8},  {"0x10", 16},
+                          {"-0", 256}, {"4294967295", 4294967295ULL}};
+
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        SetEnvironment("MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY", entry.value);
+        const auto config = NvmeKvIoConcurrencyConfig::FromEnvironment(64);
+        EXPECT_EQ(config.max_io_concurrency, entry.expected);
+    }
+}
+
+TEST_F(NvmeKvIoConcurrencyConfigTest,
+       InvalidAndZeroValuesKeepDefaultsSilently) {
+    const char* values[] = {"",   "0",  "17 ",        "17x",
+                            "-1", "0x", "4294967296", "abc"};
+    for (const char* variable : kVariables) {
+        for (const char* value : values) {
+            SCOPED_TRACE(std::string(variable) + "=" + value);
+            SetEnvironment(variable, value);
+
+            testing::internal::CaptureStderr();
+            const auto config = NvmeKvIoConcurrencyConfig::FromEnvironment(64);
+            const std::string diagnostics =
+                testing::internal::GetCapturedStderr();
+
+            ExpectConfig(config, 256, 18, 6, 1, 12);
+            EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+            ASSERT_EQ(unsetenv(variable), 0);
+        }
+    }
+}
+
+TEST_F(NvmeKvIoConcurrencyConfigTest, AppliesDependentCapsInOrder) {
+    SetEnvironment("MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY", "8");
+    SetEnvironment("MOONCAKE_NVME_KV_IO_CONCURRENCY", "16");
+    SetEnvironment("MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY", "99");
+    SetEnvironment("MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY", "99");
+    SetEnvironment("MOONCAKE_NVME_KV_PREPARE_CONCURRENCY", "99");
+
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 8, 8, 7, 7, 1);
+}
+
+TEST_F(NvmeKvIoConcurrencyConfigTest, SettingsRemainIndependent) {
+    SetEnvironment("MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY", "10");
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 10, 10, 6, 1,
+                 4);
+    ASSERT_EQ(unsetenv("MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY"), 0);
+
+    SetEnvironment("MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY", "4");
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 256, 18, 4, 1,
+                 12);
+    ASSERT_EQ(unsetenv("MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY"), 0);
+
+    SetEnvironment("MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY", "9");
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 256, 18, 6, 9,
+                 12);
+    ASSERT_EQ(unsetenv("MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY"), 0);
+
+    SetEnvironment("MOONCAKE_NVME_KV_PREPARE_CONCURRENCY", "99");
+    ExpectConfig(NvmeKvIoConcurrencyConfig::FromEnvironment(64), 256, 18, 6, 1,
+                 12);
+}
+
+TEST_F(NvmeKvIoConcurrencyConfigTest, NewConfigsReadCurrentEnvironment) {
+    SetEnvironment("MOONCAKE_NVME_KV_IO_CONCURRENCY", "4");
+    const auto first = NvmeKvIoConcurrencyConfig::FromEnvironment(64);
+    SetEnvironment("MOONCAKE_NVME_KV_IO_CONCURRENCY", "7");
+    const auto second = NvmeKvIoConcurrencyConfig::FromEnvironment(64);
+
+    EXPECT_EQ(first.io_concurrency, 4);
+    EXPECT_EQ(second.io_concurrency, 7);
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/nvme_kv/storage_backend_test.cpp b/mooncake-store/tests/nvme_kv/storage_backend_test.cpp
new file mode 100644
index 0000000000..e47ef9dce7
--- /dev/null
+++ b/mooncake-store/tests/nvme_kv/storage_backend_test.cpp
@@ -0,0 +1,322 @@
+#include "nvme_kv/backend.h"
+#include "nvme_kv/executor_util.h"
+#include "storage_backend.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cerrno>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace fs = std::filesystem;
+
+namespace mooncake::test {
+
+namespace {
+
+class EnvVarGuard {
+   public:
+    EnvVarGuard(const char *name, const char *value) : name_(name) {
+        if (const char *old_value = getenv(name)) {
+            old_value_ = old_value;
+        }
+        setenv(name, value, 1);
+    }
+
+    ~EnvVarGuard() {
+        if (old_value_.has_value()) {
+            setenv(name_.c_str(), old_value_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> old_value_;
+};
+
+class BoolFlagGuard {
+   public:
+    BoolFlagGuard(bool &flag, bool value) : flag_(flag), old_value_(flag) {
+        flag_ = value;
+    }
+
+    ~BoolFlagGuard() { flag_ = old_value_; }
+
+   private:
+    bool &flag_;
+    bool old_value_;
+};
+
+class NvmeKvStorageBackendTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        data_path_ = (fs::current_path() / "nvme_kv_test_data").string();
+        std::error_code ec;
+        fs::remove_all(data_path_, ec);
+        ASSERT_FALSE(ec) << ec.message();
+        fs::create_directories(data_path_, ec);
+        ASSERT_FALSE(ec) << ec.message();
+    }
+
+    void TearDown() override {
+        std::error_code ec;
+        fs::remove_all(data_path_, ec);
+    }
+
+    std::string data_path_;
+};
+
+}  // namespace
+
+TEST_F(NvmeKvStorageBackendTest, PhysicalKeyPackingEncodesCommandSet) {
+    NvmeKvCommandExecutor::PhysicalKey key{};
+    for (size_t i = 0; i < key.size(); ++i) {
+        key[i] = static_cast<uint8_t>(0x10 + i);
+    }
+
+    const auto fields = PackNvmeKvPhysicalKey(key);
+    uint32_t expected_cdw14 = 0;
+    std::memcpy(&expected_cdw14, key.data() + 8, sizeof(expected_cdw14));
+    expected_cdw14 &= 0x00FFFFFFu;
+    expected_cdw14 |= static_cast<uint32_t>(kNvmeKvCommandSetIdentifier) << 24;
+
+    EXPECT_EQ(fields.cdw14, expected_cdw14);
+    EXPECT_EQ(static_cast<uint8_t>(fields.cdw14 >> 24),
+              kNvmeKvCommandSetIdentifier);
+}
+
+TEST_F(NvmeKvStorageBackendTest, StatusMappingHandlesKvSpecificStatusCodes) {
+    EXPECT_EQ(MapNvmeKvStatus(0x81, true), ErrorCode::KEYS_ULTRA_LIMIT);
+    EXPECT_EQ(MapNvmeKvStatus(0x85, true), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(MapNvmeKvStatus(0x86, false), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(MapNvmeKvStatus(0x87, false), ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_EQ(MapNvmeKvStatus(0x89, true), ErrorCode::OBJECT_ALREADY_EXISTS);
+
+    EXPECT_EQ(MapNvmeKvTransportError(ENOENT, false),
+              ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_EQ(MapNvmeKvTransportError(ENOSPC, true),
+              ErrorCode::KEYS_ULTRA_LIMIT);
+    EXPECT_EQ(MapNvmeKvTransportError(ENOMEM, false),
+              ErrorCode::BUFFER_OVERFLOW);
+    EXPECT_EQ(MapNvmeKvTransportError(0x4087, false),
+              ErrorCode::OBJECT_NOT_FOUND);
+
+    constexpr uint32_t kRawValueSize = 1234;
+    std::array<char, 4096> raw_value{};
+    EXPECT_EQ(
+        ResolveNvmeKvInitialRetrieveBytes(kRawValueSize, raw_value.size()),
+        RoundUpToNvmeKvTransferBytes(kRawValueSize));
+    EXPECT_EQ(ResolveNvmeKvRetrievedValueSize(raw_value.data(), 0,
+                                              raw_value.size(), kRawValueSize),
+              kRawValueSize);
+    EXPECT_EQ(ResolveNvmeKvRetrievedValueSize(raw_value.data(), 0, 1024,
+                                              kRawValueSize),
+              0);
+
+    EXPECT_TRUE(ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+        ErrorCode::INVALID_PARAMS, 0, kDefaultNvmeKvTransferAlignmentBytes,
+        kDefaultNvmeKvRuntimeTransferLimit));
+    EXPECT_FALSE(ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+        ErrorCode::INVALID_PARAMS, kDefaultNvmeKvTransferAlignmentBytes,
+        kDefaultNvmeKvTransferAlignmentBytes,
+        kDefaultNvmeKvRuntimeTransferLimit));
+    EXPECT_FALSE(ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+        ErrorCode::OBJECT_NOT_FOUND, 0, kDefaultNvmeKvTransferAlignmentBytes,
+        kDefaultNvmeKvRuntimeTransferLimit));
+    EXPECT_FALSE(ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+        ErrorCode::INTERNAL_ERROR, 0, kDefaultNvmeKvTransferAlignmentBytes,
+        kDefaultNvmeKvRuntimeTransferLimit));
+    EXPECT_FALSE(ShouldRetryNvmeKvRetrieveWithMaxBuffer(
+        ErrorCode::INVALID_PARAMS, 0, kDefaultNvmeKvRuntimeTransferLimit,
+        kDefaultNvmeKvRuntimeTransferLimit));
+}
+
+TEST_F(NvmeKvStorageBackendTest, IoWorkerConcurrencyPreservesDependentCaps) {
+    EnvVarGuard driver_guard("MOONCAKE_NVME_KV_DRIVER", "stub");
+    EnvVarGuard maximum_guard("MOONCAKE_NVME_KV_MAX_IO_CONCURRENCY", "8");
+    EnvVarGuard io_guard("MOONCAKE_NVME_KV_IO_CONCURRENCY", "16");
+    EnvVarGuard batch_guard("MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY", "99");
+    EnvVarGuard root_guard("MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY", "99");
+    EnvVarGuard prepare_guard("MOONCAKE_NVME_KV_PREPARE_CONCURRENCY", "99");
+    BoolFlagGuard log_to_stderr_guard(FLAGS_logtostderr, true);
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path_ + "/concurrency_caps";
+    config.storage_backend_type = StorageBackendType::kNvmeKv;
+
+    testing::internal::CaptureStderr();
+    NvmeKvStorageBackend backend(config);
+    const auto result = backend.Init();
+    const std::string diagnostics = testing::internal::GetCapturedStderr();
+
+    ASSERT_TRUE(result.has_value());
+    EXPECT_NE(diagnostics.find(
+                  "NVMe KV backend I/O concurrency: 8 (max 8), batch submit "
+                  "concurrency: 7, root submit concurrency: 7, prepare "
+                  "concurrency: 1"),
+              std::string::npos)
+        << diagnostics;
+}
+
+TEST_F(NvmeKvStorageBackendTest, BackendLoadsKnownObjectsFromDevice) {
+    EnvVarGuard driver_guard("MOONCAKE_NVME_KV_DRIVER", "stub");
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path_ + "/known_objects";
+    config.storage_backend_type = StorageBackendType::kNvmeKv;
+
+    constexpr int kObjectCount = 9;
+    std::vector<std::string> keys;
+    std::vector<std::string> values;
+    keys.reserve(kObjectCount);
+    values.reserve(kObjectCount);
+    std::unordered_map<std::string, std::vector<Slice>> batch;
+    for (int i = 0; i < kObjectCount; ++i) {
+        keys.emplace_back("nvme_kv_known_key_" + std::to_string(i));
+        const size_t value_size = i == 0 ? 4096 : 128 * 1024 + 4096 + i * 17;
+        values.emplace_back(value_size, static_cast<char>('a' + (i % 26)));
+        batch.emplace(keys.back(),
+                      std::vector<Slice>{
+                          Slice{values.back().data(), values.back().size()}});
+    }
+
+    {
+        NvmeKvStorageBackend backend(config);
+        ASSERT_TRUE(backend.Init().has_value());
+        auto offload_result = backend.BatchOffload(
+            batch,
+            [](const std::vector<std::string> &,
+               std::vector<StorageObjectMetadata> &) { return ErrorCode::OK; });
+        ASSERT_TRUE(offload_result.has_value());
+        ASSERT_EQ(offload_result.value(), kObjectCount);
+    }
+
+    NvmeKvStorageBackend reader(config);
+    ASSERT_TRUE(reader.Init().has_value());
+    for (const auto &key : keys) {
+        EXPECT_TRUE(reader.IsExist(key).value_or(false));
+    }
+    EXPECT_FALSE(reader.IsExist("nvme_kv_missing_key").value_or(true));
+
+    auto duplicate_result = reader.BatchOffload(
+        batch,
+        [](const std::vector<std::string> &,
+           std::vector<StorageObjectMetadata> &) { return ErrorCode::OK; });
+    ASSERT_TRUE(duplicate_result.has_value());
+    EXPECT_EQ(duplicate_result.value(), kObjectCount);
+
+    std::vector<std::string> loaded_values;
+    loaded_values.reserve(kObjectCount);
+    std::unordered_map<std::string, Slice> load_batch;
+    for (int i = 0; i < kObjectCount; ++i) {
+        loaded_values.emplace_back(values[i].size(), '\0');
+        load_batch.emplace(keys[i], Slice{loaded_values.back().data(),
+                                          loaded_values.back().size()});
+    }
+    ASSERT_TRUE(reader.BatchLoad(load_batch).has_value());
+    EXPECT_EQ(loaded_values, values);
+}
+
+TEST_F(NvmeKvStorageBackendTest, PipelinedStubRoundTripChunkedObjects) {
+    EnvVarGuard driver_guard("MOONCAKE_NVME_KV_DRIVER", "stub");
+    EnvVarGuard queue_depth_guard("MOONCAKE_NVME_KV_QUEUE_DEPTH", "8");
+    EnvVarGuard runtime_limit_guard("MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT",
+                                    "65536");
+    EnvVarGuard io_concurrency_guard("MOONCAKE_NVME_KV_IO_CONCURRENCY", "8");
+    EnvVarGuard batch_submit_guard("MOONCAKE_NVME_KV_BATCH_SUBMIT_CONCURRENCY",
+                                   "3");
+    EnvVarGuard root_submit_guard("MOONCAKE_NVME_KV_ROOT_SUBMIT_CONCURRENCY",
+                                  "2");
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path_ + "/pipelined";
+    config.storage_backend_type = StorageBackendType::kNvmeKv;
+
+    NvmeKvStorageBackend backend(config);
+    ASSERT_TRUE(backend.Init().has_value());
+
+    constexpr int kObjectCount = 24;
+    std::vector<std::string> keys;
+    std::vector<std::string> values;
+    keys.reserve(kObjectCount);
+    values.reserve(kObjectCount);
+    std::unordered_map<std::string, std::vector<Slice>> batch;
+    for (int i = 0; i < kObjectCount; ++i) {
+        keys.emplace_back("nvme_kv_pipelined_key_" + std::to_string(i));
+        values.emplace_back(180 * 1024 + i * 4096,
+                            static_cast<char>('A' + (i % 26)));
+        batch.emplace(keys.back(),
+                      std::vector<Slice>{
+                          Slice{values.back().data(), values.back().size()}});
+    }
+
+    auto offload_result = backend.BatchOffload(
+        batch,
+        [](const std::vector<std::string> &,
+           std::vector<StorageObjectMetadata> &) { return ErrorCode::OK; });
+    ASSERT_TRUE(offload_result.has_value());
+    EXPECT_EQ(offload_result.value(), kObjectCount);
+
+    std::vector<std::string> loaded_values;
+    loaded_values.reserve(kObjectCount);
+    std::unordered_map<std::string, Slice> load_batch;
+    for (int i = 0; i < kObjectCount; ++i) {
+        loaded_values.emplace_back(values[i].size(), '\0');
+        load_batch.emplace(keys[i], Slice{loaded_values.back().data(),
+                                          loaded_values.back().size()});
+    }
+    ASSERT_TRUE(backend.BatchLoad(load_batch).has_value());
+    EXPECT_EQ(loaded_values, values);
+}
+
+TEST_F(NvmeKvStorageBackendTest, ManifestCacheUpdatesAfterSameKeyRewrite) {
+    EnvVarGuard driver_guard("MOONCAKE_NVME_KV_DRIVER", "stub");
+    EnvVarGuard runtime_limit_guard("MOONCAKE_NVME_KV_RUNTIME_TRANSFER_LIMIT",
+                                    "65536");
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path_ + "/manifest_cache";
+    config.storage_backend_type = StorageBackendType::kNvmeKv;
+
+    NvmeKvStorageBackend backend(config);
+    ASSERT_TRUE(backend.Init().has_value());
+
+    const std::string key = "nvme_kv_manifest_cache_rewrite";
+    std::string first_value(192 * 1024, 'x');
+    std::string second_value(first_value.size(), 'y');
+
+    auto store_value = [&](std::string &value) {
+        std::unordered_map<std::string, std::vector<Slice>> batch;
+        batch.emplace(key,
+                      std::vector<Slice>{Slice{value.data(), value.size()}});
+        auto offload_result = backend.BatchOffload(
+            batch,
+            [](const std::vector<std::string> &,
+               std::vector<StorageObjectMetadata> &) { return ErrorCode::OK; });
+        ASSERT_TRUE(offload_result.has_value());
+        EXPECT_EQ(offload_result.value(), 1);
+    };
+
+    store_value(first_value);
+    std::string loaded(first_value.size(), '\0');
+    std::unordered_map<std::string, Slice> load_batch{
+        {key, Slice{loaded.data(), loaded.size()}}};
+    ASSERT_TRUE(backend.BatchLoad(load_batch).has_value());
+    EXPECT_EQ(loaded, first_value);
+
+    store_value(second_value);
+    std::fill(loaded.begin(), loaded.end(), '\0');
+    ASSERT_TRUE(backend.BatchLoad(load_batch).has_value());
+    EXPECT_EQ(loaded, second_value);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/object_data_type_test.cpp b/mooncake-store/tests/object_data_type_test.cpp
index a14a72e5eb..88b84ee254 100644
--- a/mooncake-store/tests/object_data_type_test.cpp
+++ b/mooncake-store/tests/object_data_type_test.cpp
@@ -6,7 +6,6 @@
 #include <gtest/gtest.h>
 
 #include <sstream>
-#include <vector>
 
 namespace mooncake::test {
 
@@ -79,13 +78,6 @@ TEST_F(ObjectDataTypeTest, ReplicateConfigDefaultDataType) {
     EXPECT_EQ(config.data_type, ObjectDataType::UNKNOWN);
 }
 
-// ReplicateConfig can be set to other types
-TEST_F(ObjectDataTypeTest, ReplicateConfigSetDataType) {
-    ReplicateConfig config;
-    config.data_type = ObjectDataType::WEIGHT;
-    EXPECT_EQ(config.data_type, ObjectDataType::WEIGHT);
-}
-
 // ReplicateConfig stream output includes data_type
 TEST_F(ObjectDataTypeTest, ReplicateConfigStreamIncludesDataType) {
     ReplicateConfig config;
@@ -95,32 +87,7 @@ TEST_F(ObjectDataTypeTest, ReplicateConfigStreamIncludesDataType) {
     EXPECT_NE(oss.str().find("data_type: TENSOR"), std::string::npos);
 }
 
-// PutStart with data_type propagates to ObjectMetadata
-TEST_F(ObjectDataTypeTest, PutStartWithDataType) {
-    std::unique_ptr<MasterService> service(new MasterService());
-    Segment segment = MakeSegment();
-    UUID client_id = generate_uuid();
-    auto mount_result = service->MountSegment(segment, client_id);
-    ASSERT_TRUE(mount_result.has_value());
-
-    UUID put_client = generate_uuid();
-
-    // Put with WEIGHT type
-    ReplicateConfig config;
-    config.replica_num = 1;
-    config.data_type = ObjectDataType::WEIGHT;
-
-    auto result = service->PutStart(put_client, "key_weight",
-                                    TenantId::Default(), 1024, config);
-    ASSERT_TRUE(result.has_value());
-    EXPECT_FALSE(result.value().empty());
-
-    auto end_result = service->PutEnd(put_client, "key_weight",
-                                      TenantId::Default(), ReplicaType::MEMORY);
-    EXPECT_TRUE(end_result.has_value());
-}
-
-// PutStart with default UNKNOWN data_type still works (backward compat)
+// PutStart accepts the default UNKNOWN data type.
 TEST_F(ObjectDataTypeTest, PutStartDefaultDataType) {
     std::unique_ptr<MasterService> service(new MasterService());
     Segment segment = MakeSegment();
@@ -139,21 +106,4 @@ TEST_F(ObjectDataTypeTest, PutStartDefaultDataType) {
     EXPECT_FALSE(result.value().empty());
 }
 
-// Verify all enum values can roundtrip through uint8_t cast
-TEST_F(ObjectDataTypeTest, EnumRoundtrip) {
-    std::vector<ObjectDataType> all_types = {
-        ObjectDataType::UNKNOWN,  ObjectDataType::KVCACHE,
-        ObjectDataType::TENSOR,   ObjectDataType::WEIGHT,
-        ObjectDataType::SAMPLE,   ObjectDataType::ACTIVATION,
-        ObjectDataType::GRADIENT, ObjectDataType::OPTIMIZER_STATE,
-        ObjectDataType::METADATA, ObjectDataType::GENERAL,
-    };
-
-    for (auto type : all_types) {
-        uint8_t raw = static_cast<uint8_t>(type);
-        auto recovered = static_cast<ObjectDataType>(raw);
-        EXPECT_EQ(type, recovered);
-    }
-}
-
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/object_entry_test.cpp b/mooncake-store/tests/object_entry_test.cpp
new file mode 100644
index 0000000000..9168b4da4a
--- /dev/null
+++ b/mooncake-store/tests/object_entry_test.cpp
@@ -0,0 +1,49 @@
+#include "object_entry.h"
+#include "object_test_helpers.h"
+
+#include <memory>
+#include <utility>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+TEST(ObjectEntryTest, OwnsMetadataEnvelopeFromConstruction) {
+    auto metadata = test::MakeObjectMetadata("k1");
+    auto* raw = metadata.get();
+    auto entry = std::make_shared<ObjectEntry>(std::move(metadata));
+
+    // The envelope is wired from construction on, so a callback always sees
+    // one and there is nothing to null-check at the call sites.
+    entry->WithExclusiveAccess([&](ObjectMetadata& m, ObjectEntry::State&) {
+        EXPECT_EQ(&m, raw);
+        EXPECT_EQ(m.size, 128u);
+        m.object_checksum = 42;
+    });
+
+    entry->WithSharedAccess(
+        [&](const ObjectMetadata& m, const ObjectEntry::State& state) {
+            ASSERT_TRUE(m.object_checksum.has_value());
+            EXPECT_EQ(*m.object_checksum, 42u);
+            EXPECT_FALSE(state.is_processing);
+            EXPECT_FALSE(state.is_torn_down);
+        });
+}
+
+TEST(ObjectEntryTest, AccessorsSeeTheStateWrittenUnderTheLock) {
+    auto entry = test::MakeObjectEntry("k1");
+    entry->WithExclusiveAccess([](ObjectMetadata&, ObjectEntry::State& state) {
+        state.is_processing = true;
+    });
+
+    // A shared reader sees the write, and its callback's value comes back.
+    const bool processing = entry->WithSharedAccess(
+        [](const ObjectMetadata&, const ObjectEntry::State& state) {
+            return state.is_processing;
+        });
+    EXPECT_TRUE(processing);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/object_index_test.cpp b/mooncake-store/tests/object_index_test.cpp
new file mode 100644
index 0000000000..677498bf74
--- /dev/null
+++ b/mooncake-store/tests/object_index_test.cpp
@@ -0,0 +1,90 @@
+#include "object_index.h"
+#include "object_test_helpers.h"
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+TEST(ObjectIndexTest, InsertPublishesTheEntryUnderItsKey) {
+    ObjectIndex store;
+    EXPECT_EQ(store.ObjectCount(), 0u);
+
+    auto e1 = test::MakeObjectEntry("k1");
+    EXPECT_TRUE(store.Insert(e1));
+    EXPECT_TRUE(store.Contains("k1"));
+    EXPECT_EQ(store.ObjectCount(), 1u);
+
+    auto entry = store.Get("k1");
+    ASSERT_NE(entry, nullptr);
+    EXPECT_EQ(entry.get(), e1.get());  // the route hands back the same entry
+    EXPECT_EQ(entry->key(), "k1");
+    EXPECT_EQ(store.Get("missing"), nullptr);
+}
+
+TEST(ObjectIndexTest, EraseIfHonoursEntryIdentity) {
+    ObjectIndex store;
+    auto e1 = test::MakeObjectEntry("k1");
+    ASSERT_TRUE(store.Insert(e1));
+
+    // The route points at e1, so a stale pointer may not erase it.
+    auto replacement = test::MakeObjectEntry("k1");
+    EXPECT_FALSE(store.EraseIf("k1", replacement));
+    EXPECT_TRUE(store.Contains("k1"));
+
+    EXPECT_TRUE(store.EraseIf("k1", e1));
+    EXPECT_FALSE(store.EraseIf("k1", e1));  // slot already gone
+    EXPECT_FALSE(store.Contains("k1"));
+    EXPECT_EQ(store.ObjectCount(), 0u);
+}
+
+TEST(ObjectIndexTest, InsertAssignsAMonotonicGeneration) {
+    ObjectIndex store;
+    auto e1 = test::MakeObjectEntry("k1");
+    EXPECT_EQ(e1->generation(), 0u);  // never published
+    ASSERT_TRUE(store.Insert(e1));
+    EXPECT_GT(e1->generation(), 0u);
+
+    // A replacement of the same key gets a fresh, higher generation, which is
+    // what lets a holder tell itself apart from the entry now published.
+    ASSERT_TRUE(store.EraseIf("k1", e1));
+    auto e2 = test::MakeObjectEntry("k1");
+    ASSERT_TRUE(store.Insert(e2));
+    EXPECT_GT(e2->generation(), e1->generation());
+}
+
+TEST(ObjectIndexTest, DuplicateInsertIsRejected) {
+    ObjectIndex store;
+    auto winner = test::MakeObjectEntry("k1");
+    ASSERT_TRUE(store.Insert(winner));
+
+    // The loser must neither clobber the routed entry nor look published: it
+    // never reaches the route, so it keeps generation 0.
+    auto loser = test::MakeObjectEntry("k1");
+    EXPECT_FALSE(store.Insert(loser));
+    EXPECT_EQ(loser->generation(), 0u);
+    EXPECT_EQ(store.ObjectCount(), 1u);
+    EXPECT_EQ(store.Get("k1").get(), winner.get());
+}
+
+TEST(ObjectIndexTest, SnapshotObjectsEnumeratesEveryEntry) {
+    ObjectIndex store;
+    ASSERT_TRUE(store.Insert(test::MakeObjectEntry("k1")));
+    ASSERT_TRUE(store.Insert(test::MakeObjectEntry("k2", "g1")));
+    ASSERT_TRUE(store.Insert(test::MakeObjectEntry("k3", "g1")));
+
+    std::vector<std::string> keys;
+    for (const auto& entry : store.SnapshotObjects()) {
+        keys.push_back(entry->key());
+    }
+    // Enumeration order is the map's, so compare as a set.
+    std::sort(keys.begin(), keys.end());
+    EXPECT_EQ(keys, (std::vector<std::string>{"k1", "k2", "k3"}));
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/object_storage_adapter_test.cpp b/mooncake-store/tests/object_storage_adapter_test.cpp
new file mode 100644
index 0000000000..87c40981eb
--- /dev/null
+++ b/mooncake-store/tests/object_storage_adapter_test.cpp
@@ -0,0 +1,627 @@
+#include "storage/distributed/object_storage_adapter.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <array>
+#include <cstring>
+#include <filesystem>
+#include <limits>
+#include <map>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+#include <unistd.h>
+
+#include "storage/distributed/distributed_storage_backend.h"
+
+namespace mooncake {
+namespace {
+
+class FakeObjectStorageAdapter : public ObjectStorageAdapter {
+   public:
+    std::map<std::string, std::string> objects;
+    std::unordered_set<std::string> fail_keys;
+    int init_calls = 0;
+    int health_check_calls = 0;
+    int putv_calls = 0;
+    int put_batch_calls = 0;
+    std::vector<std::pair<const iovec*, int>> putv_inputs;
+    int get_calls = 0;
+    int get_batch_calls = 0;
+    bool fail_health_check = false;
+    bool initialized = false;
+
+    tl::expected<void, ErrorCode> Put(const std::string& logical_key,
+                                      std::span<const char> data) override {
+        objects[logical_key] = std::string(data.begin(), data.end());
+        return {};
+    }
+
+    tl::expected<void, ErrorCode> PutV(const std::string& logical_key,
+                                       const iovec* iov, int iovcnt) override {
+        ++putv_calls;
+        putv_inputs.emplace_back(iov, iovcnt);
+        if (fail_keys.contains(logical_key)) {
+            return tl::make_unexpected(ErrorCode::FILE_WRITE_FAIL);
+        }
+
+        std::string buffer;
+        for (int i = 0; i < iovcnt; ++i) {
+            buffer.append(static_cast<const char*>(iov[i].iov_base),
+                          iov[i].iov_len);
+        }
+        objects[logical_key] = std::move(buffer);
+        return {};
+    }
+
+    tl::expected<size_t, ErrorCode> Get(const std::string& logical_key,
+                                        void* buf, size_t len) override {
+        ++get_calls;
+        auto it = objects.find(logical_key);
+        if (it == objects.end()) {
+            return tl::make_unexpected(ErrorCode::FILE_NOT_FOUND);
+        }
+
+        size_t bytes_read = std::min(len, it->second.size());
+        if (bytes_read > 0) {
+            std::memcpy(buf, it->second.data(), bytes_read);
+        }
+        return bytes_read;
+    }
+
+    std::vector<tl::expected<void, ErrorCode>> PutBatch(
+        const std::vector<ObjectPutRequest>& requests) override {
+        ++put_batch_calls;
+        return ObjectStorageAdapter::PutBatch(requests);
+    }
+
+    std::vector<tl::expected<size_t, ErrorCode>> GetBatch(
+        const std::vector<ObjectGetRequest>& requests) override {
+        ++get_batch_calls;
+        return ObjectStorageAdapter::GetBatch(requests);
+    }
+
+    tl::expected<bool, ErrorCode> Exists(
+        const std::string& logical_key) override {
+        return objects.contains(logical_key);
+    }
+
+    tl::expected<void, ErrorCode> Delete(
+        const std::string& logical_key) override {
+        objects.erase(logical_key);
+        return {};
+    }
+
+    tl::expected<std::vector<KeyInfo>, ErrorCode> ListKeys() override {
+        std::vector<KeyInfo> result;
+        result.reserve(objects.size());
+        for (const auto& [key, value] : objects) {
+            result.push_back({key, value.size()});
+        }
+        return result;
+    }
+
+    tl::expected<void, ErrorCode> Init() override {
+        ++init_calls;
+        initialized = true;
+        return {};
+    }
+
+    tl::expected<void, ErrorCode> CheckHealth() override {
+        ++health_check_calls;
+        if (fail_health_check) {
+            return tl::make_unexpected(ErrorCode::DFS_SERVICE_UNAVAILABLE);
+        }
+        return {};
+    }
+
+    const char* GetName() const override { return "fake-object-storage"; }
+};
+
+class FakeFileSystemAdapter : public FileSystemAdapter {
+   public:
+    bool initialized = false;
+
+    tl::expected<size_t, ErrorCode> WriteFile(
+        const std::string&, std::span<const char> data) override {
+        return data.size();
+    }
+
+    tl::expected<size_t, ErrorCode> ReadFile(const std::string&, void*,
+                                             size_t) override {
+        return 0;
+    }
+
+    tl::expected<size_t, ErrorCode> VectorWriteFile(const std::string&,
+                                                    const iovec* iov,
+                                                    int iovcnt,
+                                                    off_t) override {
+        size_t total = 0;
+        for (int i = 0; i < iovcnt; ++i) total += iov[i].iov_len;
+        return total;
+    }
+
+    tl::expected<size_t, ErrorCode> VectorReadFile(const std::string&,
+                                                   const iovec*, int,
+                                                   off_t) override {
+        return 0;
+    }
+
+    tl::expected<void, ErrorCode> DeleteFile(const std::string&) override {
+        return {};
+    }
+
+    tl::expected<bool, ErrorCode> FileExists(const std::string&) override {
+        return false;
+    }
+
+    tl::expected<std::vector<std::string>, ErrorCode> ListFiles(
+        const std::string&) override {
+        return std::vector<std::string>{};
+    }
+
+    tl::expected<void, ErrorCode> Init(const std::string&) override {
+        initialized = true;
+        return {};
+    }
+
+    tl::expected<void, ErrorCode> Shutdown() override {
+        initialized = false;
+        return {};
+    }
+
+    const char* GetName() const override { return "fake-filesystem"; }
+};
+
+class ObjectStorageAdapterTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        root_dir_ = std::filesystem::temp_directory_path() /
+                    ("mooncake_object_storage_adapter_test_" +
+                     std::to_string(getpid()));
+        std::error_code ec;
+        std::filesystem::remove_all(root_dir_, ec);
+    }
+
+    void TearDown() override {
+        std::error_code ec;
+        std::filesystem::remove_all(root_dir_, ec);
+    }
+
+    std::unique_ptr<DistributedStorageBackend> MakeObjectStorageBackend(
+        FakeObjectStorageAdapter*& adapter, FileStorageConfig file_config = {},
+        bool enable_health_check = false) const {
+        DistributedStorageConfig distributed_config;
+        distributed_config.fsdir = root_dir_.string();
+        distributed_config.enable_health_check = enable_health_check;
+        auto owned_adapter = std::make_unique<FakeObjectStorageAdapter>();
+        adapter = owned_adapter.get();
+        return std::make_unique<DistributedStorageBackend>(
+            file_config, distributed_config, nullptr, std::move(owned_adapter));
+    }
+
+    std::filesystem::path root_dir_;
+};
+
+TEST_F(ObjectStorageAdapterTest, DefaultPutBatchForwardsIovecArrayAndCount) {
+    FakeObjectStorageAdapter adapter;
+    adapter.fail_keys.insert("failed");
+    std::string first = "first", second = "second", unused = "unused";
+    const iovec segments[] = {{first.data(), first.size()},
+                              {second.data(), second.size()},
+                              {unused.data(), unused.size()}};
+    auto results =
+        adapter.ObjectStorageAdapter::PutBatch({{"joined", segments, 2},
+                                                {"failed", segments + 1, 1},
+                                                {"empty", nullptr, 0}});
+    ASSERT_EQ(results.size(), 3U);
+    EXPECT_TRUE(results[0]);
+    ASSERT_FALSE(results[1]);
+    EXPECT_EQ(results[1].error(), ErrorCode::FILE_WRITE_FAIL);
+    EXPECT_TRUE(results[2]);
+    EXPECT_EQ(adapter.objects.at("joined"), first + second);
+    EXPECT_EQ(adapter.objects.at("empty"), "");
+    ASSERT_EQ(adapter.putv_inputs.size(), 3U);
+    EXPECT_EQ(adapter.putv_inputs[0].first, segments);
+    EXPECT_EQ(adapter.putv_inputs[0].second, 2);
+    EXPECT_EQ(adapter.putv_inputs[1].first, segments + 1);
+    EXPECT_EQ(adapter.putv_inputs[1].second, 1);
+    EXPECT_EQ(adapter.putv_inputs[2].first, nullptr);
+    EXPECT_EQ(adapter.putv_inputs[2].second, 0);
+    EXPECT_TRUE(adapter.ObjectStorageAdapter::PutBatch({}).empty());
+    EXPECT_EQ(adapter.putv_calls, 3);
+}
+
+TEST_F(ObjectStorageAdapterTest, ObjectStorageModeInitSkipsDirectories) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+
+    EXPECT_EQ(backend->GetStorageMode(),
+              DistributedStorageMode::kObjectStorage);
+    EXPECT_TRUE(backend->UsesObjectStorage());
+    ASSERT_TRUE(backend->Init());
+    EXPECT_TRUE(adapter->initialized);
+    EXPECT_EQ(adapter->init_calls, 1);
+    EXPECT_EQ(adapter->health_check_calls, 0);
+    EXPECT_FALSE(std::filesystem::exists(root_dir_));
+
+    ASSERT_TRUE(backend->Init());
+    EXPECT_EQ(adapter->init_calls, 1);
+}
+
+TEST_F(ObjectStorageAdapterTest, ObjectStorageModeRejectsDfsRequests) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    auto write_results = backend->BatchWrite({DfsWriteRequest{}});
+    ASSERT_EQ(write_results.size(), 1);
+    ASSERT_FALSE(write_results.front());
+    EXPECT_EQ(write_results.front().error(), ErrorCode::NOT_SUPPORTED);
+
+    auto read_results = backend->BatchRead({DfsReadRequest{}});
+    ASSERT_EQ(read_results.size(), 1);
+    ASSERT_FALSE(read_results.front());
+    EXPECT_EQ(read_results.front().error(), ErrorCode::NOT_SUPPORTED);
+}
+
+TEST_F(ObjectStorageAdapterTest, ObjectStorageModeRunsEnabledHealthCheck) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter, {}, true);
+
+    ASSERT_TRUE(backend->Init());
+    EXPECT_EQ(adapter->init_calls, 1);
+    EXPECT_EQ(adapter->health_check_calls, 1);
+
+    ASSERT_TRUE(backend->Init());
+    EXPECT_EQ(adapter->init_calls, 1);
+    EXPECT_EQ(adapter->health_check_calls, 1);
+}
+
+TEST_F(ObjectStorageAdapterTest, ObjectStorageHealthCheckFailureFailsInit) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter, {}, true);
+    adapter->fail_health_check = true;
+
+    auto result = backend->Init();
+
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    EXPECT_EQ(adapter->init_calls, 1);
+    EXPECT_EQ(adapter->health_check_calls, 1);
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchOffloadWritesMultiSliceObjects) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    std::string first_a = "hello";
+    std::string first_b = "-world";
+    std::string second = "payload";
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {"first",
+         {{first_a.data(), first_a.size()}, {first_b.data(), first_b.size()}}},
+        {"second", {{second.data(), second.size()}}},
+    };
+    std::vector<std::string> completed_keys;
+    std::vector<StorageObjectMetadata> completed_metadata;
+
+    auto result = backend->BatchOffload(
+        batch, [&](const std::vector<std::string>& keys,
+                   std::vector<StorageObjectMetadata>& metadata) {
+            completed_keys = keys;
+            completed_metadata = metadata;
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(*result, 2);
+    EXPECT_EQ(adapter->put_batch_calls, 1);
+    EXPECT_EQ(adapter->putv_calls, 2);
+    EXPECT_EQ(adapter->objects.at("first"), "hello-world");
+    EXPECT_EQ(adapter->objects.at("second"), "payload");
+    EXPECT_EQ(completed_keys.size(), 2);
+    ASSERT_EQ(completed_metadata.size(), 2);
+
+    std::map<std::string, int64_t> sizes;
+    for (size_t i = 0; i < completed_keys.size(); ++i) {
+        sizes[completed_keys[i]] = completed_metadata[i].data_size;
+    }
+    EXPECT_EQ(sizes.at("first"), 11);
+    EXPECT_EQ(sizes.at("second"), 7);
+}
+
+TEST_F(ObjectStorageAdapterTest, PreservesOpaqueLogicalKeys) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    std::string logical_key = "tenant";
+    logical_key.push_back('\0');
+    logical_key += "a/b%\\";
+    std::string payload = "payload";
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {logical_key, {{payload.data(), payload.size()}}},
+    };
+    std::vector<std::string> completed_keys;
+
+    auto offload_result =
+        backend->BatchOffload(batch, [&](const std::vector<std::string>& keys,
+                                         std::vector<StorageObjectMetadata>&) {
+            completed_keys = keys;
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(offload_result);
+    EXPECT_EQ(*offload_result, 1);
+    EXPECT_EQ(completed_keys, (std::vector<std::string>{logical_key}));
+    EXPECT_TRUE(adapter->objects.contains(logical_key));
+
+    auto exists_result = backend->IsExist(logical_key);
+    ASSERT_TRUE(exists_result);
+    EXPECT_TRUE(*exists_result);
+
+    std::string output(payload.size(), '\0');
+    std::unordered_map<std::string, Slice> load_slices{
+        {logical_key, {output.data(), output.size()}},
+    };
+    ASSERT_TRUE(backend->BatchLoad(load_slices));
+    EXPECT_EQ(output, payload);
+
+    std::vector<std::string> scanned_keys;
+    std::vector<StorageObjectMetadata> scanned_metadata;
+    auto scan_result =
+        backend->ScanMeta([&](const std::vector<std::string>& keys,
+                              std::vector<StorageObjectMetadata>& metadata) {
+            scanned_keys.insert(scanned_keys.end(), keys.begin(), keys.end());
+            scanned_metadata.insert(scanned_metadata.end(), metadata.begin(),
+                                    metadata.end());
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(scan_result);
+    EXPECT_EQ(scanned_keys, (std::vector<std::string>{logical_key}));
+    ASSERT_EQ(scanned_metadata.size(), 1);
+    EXPECT_EQ(scanned_metadata.front().key_size,
+              static_cast<int64_t>(logical_key.size()));
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchOffloadAllowsPartialFailure) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+    adapter->fail_keys.insert("bad");
+
+    std::string good = "good-data";
+    std::string bad = "bad-data";
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {"good", {{good.data(), good.size()}}},
+        {"bad", {{bad.data(), bad.size()}}},
+    };
+    std::vector<std::string> completed_keys;
+
+    auto result =
+        backend->BatchOffload(batch, [&](const std::vector<std::string>& keys,
+                                         std::vector<StorageObjectMetadata>&) {
+            completed_keys = keys;
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(*result, 1);
+    ASSERT_EQ(completed_keys.size(), 1);
+    EXPECT_EQ(completed_keys.front(), "good");
+    EXPECT_TRUE(adapter->objects.contains("good"));
+    EXPECT_FALSE(adapter->objects.contains("bad"));
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchOffloadAllowsNullCompleteHandler) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    std::string value = "value";
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {"key", {{value.data(), value.size()}}},
+    };
+    std::function<ErrorCode(const std::vector<std::string>&,
+                            std::vector<StorageObjectMetadata>&)>
+        complete_handler;
+
+    auto result = backend->BatchOffload(batch, complete_handler);
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(*result, 1);
+    EXPECT_EQ(adapter->objects.at("key"), value);
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchOffloadRejectsTotalSizeOverflow) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    char value = 'x';
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {"overflow",
+         {{&value, std::numeric_limits<size_t>::max()}, {&value, 1}}},
+    };
+    bool complete_handler_called = false;
+
+    auto result =
+        backend->BatchOffload(batch, [&](const std::vector<std::string>&,
+                                         std::vector<StorageObjectMetadata>&) {
+            complete_handler_called = true;
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(*result, 0);
+    EXPECT_EQ(adapter->putv_calls, 0);
+    EXPECT_FALSE(complete_handler_called);
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchOffloadIgnoresEvictionHandler) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    std::string value = "value";
+    std::unordered_map<std::string, std::vector<Slice>> batch{
+        {"key", {{value.data(), value.size()}}},
+    };
+    bool eviction_called = false;
+
+    auto result = backend->BatchOffload(
+        batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; },
+        [&](const std::vector<std::string>&) -> tl::expected<void, ErrorCode> {
+            eviction_called = true;
+            return {};
+        });
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(*result, 1);
+    EXPECT_FALSE(eviction_called);
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchLoadReadsObjects) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+    adapter->objects["first"] = "hello";
+    adapter->objects["second"] = "world";
+
+    std::array<char, 5> first{};
+    std::array<char, 5> second{};
+    std::unordered_map<std::string, Slice> slices{
+        {"first", {first.data(), first.size()}},
+        {"second", {second.data(), second.size()}},
+    };
+
+    ASSERT_TRUE(backend->BatchLoad(slices));
+    EXPECT_EQ(std::string(first.data(), first.size()), "hello");
+    EXPECT_EQ(std::string(second.data(), second.size()), "world");
+    EXPECT_EQ(adapter->get_batch_calls, 1);
+    EXPECT_EQ(adapter->get_calls, 2);
+}
+
+TEST_F(ObjectStorageAdapterTest, BatchLoadReturnsMissingKeyError) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    std::array<char, 4> buffer{};
+    std::unordered_map<std::string, Slice> slices{
+        {"missing", {buffer.data(), buffer.size()}},
+    };
+
+    auto result = backend->BatchLoad(slices);
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::FILE_NOT_FOUND);
+}
+
+TEST_F(ObjectStorageAdapterTest, IsExistUsesObjectStorageAdapter) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    auto backend = MakeObjectStorageBackend(adapter);
+    ASSERT_TRUE(backend->Init());
+
+    auto before = backend->IsExist("key");
+    ASSERT_TRUE(before);
+    EXPECT_FALSE(*before);
+
+    adapter->objects["key"] = "value";
+    auto after = backend->IsExist("key");
+    ASSERT_TRUE(after);
+    EXPECT_TRUE(*after);
+}
+
+TEST_F(ObjectStorageAdapterTest, ScanMetaBatchesKeysAndSizes) {
+    FakeObjectStorageAdapter* adapter = nullptr;
+    FileStorageConfig file_config;
+    file_config.scanmeta_iterator_keys_limit = 2;
+    auto backend = MakeObjectStorageBackend(adapter, file_config);
+    ASSERT_TRUE(backend->Init());
+    adapter->objects = {{"a", "1"}, {"bb", "22"}, {"ccc", "333"}};
+
+    std::vector<size_t> batch_sizes;
+    std::map<std::string, StorageObjectMetadata> metadata_by_key;
+    auto result =
+        backend->ScanMeta([&](const std::vector<std::string>& keys,
+                              std::vector<StorageObjectMetadata>& metadata) {
+            batch_sizes.push_back(keys.size());
+            for (size_t i = 0; i < keys.size(); ++i) {
+                metadata_by_key.emplace(keys[i], metadata[i]);
+            }
+            return ErrorCode::OK;
+        });
+
+    ASSERT_TRUE(result);
+    EXPECT_EQ(batch_sizes, (std::vector<size_t>{2, 1}));
+    ASSERT_EQ(metadata_by_key.size(), 3);
+    EXPECT_EQ(metadata_by_key.at("a").key_size, 1);
+    EXPECT_EQ(metadata_by_key.at("a").data_size, 1);
+    EXPECT_EQ(metadata_by_key.at("bb").key_size, 2);
+    EXPECT_EQ(metadata_by_key.at("bb").data_size, 2);
+    EXPECT_EQ(metadata_by_key.at("ccc").key_size, 3);
+    EXPECT_EQ(metadata_by_key.at("ccc").data_size, 3);
+}
+
+TEST_F(ObjectStorageAdapterTest, FileSystemModeKeepsDfsOnlyContract) {
+    FileStorageConfig file_config;
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = root_dir_.string();
+    auto owned_adapter = std::make_unique<FakeFileSystemAdapter>();
+    DistributedStorageBackend backend(file_config, distributed_config,
+                                      std::move(owned_adapter));
+
+    EXPECT_EQ(backend.GetStorageMode(), DistributedStorageMode::kFileSystem);
+    EXPECT_FALSE(backend.UsesObjectStorage());
+
+    std::unordered_map<std::string, std::vector<Slice>> offload_batch;
+    auto offload_result = backend.BatchOffload(
+        offload_batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_FALSE(offload_result);
+    EXPECT_EQ(offload_result.error(), ErrorCode::NOT_SUPPORTED);
+
+    std::unordered_map<std::string, Slice> load_batch;
+    auto load_result = backend.BatchLoad(load_batch);
+    ASSERT_FALSE(load_result);
+    EXPECT_EQ(load_result.error(), ErrorCode::NOT_SUPPORTED);
+
+    auto exists_result = backend.IsExist("key");
+    ASSERT_FALSE(exists_result);
+    EXPECT_EQ(exists_result.error(), ErrorCode::NOT_SUPPORTED);
+
+    auto scan_result = backend.ScanMeta(
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_FALSE(scan_result);
+    EXPECT_EQ(scan_result.error(), ErrorCode::NOT_SUPPORTED);
+}
+
+TEST_F(ObjectStorageAdapterTest, RejectsAmbiguousAdapterSelection) {
+    FileStorageConfig file_config;
+    DistributedStorageConfig distributed_config;
+    distributed_config.fsdir = root_dir_.string();
+
+    EXPECT_DEATH(
+        {
+            DistributedStorageBackend backend(
+                file_config, distributed_config,
+                std::make_unique<FakeFileSystemAdapter>(),
+                std::make_unique<FakeObjectStorageAdapter>());
+        },
+        "exactly one I/O adapter is required");
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/object_test_helpers.h b/mooncake-store/tests/object_test_helpers.h
new file mode 100644
index 0000000000..4a3e081c9f
--- /dev/null
+++ b/mooncake-store/tests/object_test_helpers.h
@@ -0,0 +1,39 @@
+// object_test_helpers.h
+//
+// Builders shared by the per-object metadata suites.
+
+#pragma once
+
+#include <chrono>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "object_entry.h"
+#include "object_metadata.h"
+
+namespace mooncake {
+namespace test {
+
+// A minimal 128 B, replica-less envelope. These suites exercise the object
+// model, not replica validity, so nothing here sets a real replica. The write
+// time is fixed rather than read from the clock so a suite that ages a lease
+// cannot pick up a moving value.
+inline std::unique_ptr<ObjectMetadata> MakeObjectMetadata(
+    const std::string& user_key, const std::string& group_id = {}) {
+    constexpr auto kWriteTime =
+        std::chrono::system_clock::time_point(std::chrono::seconds(1));
+    return std::make_unique<ObjectMetadata>(
+        UUID{1, 2}, kWriteTime, 128, std::vector<Replica>{}, std::nullopt,
+        false, ObjectDataType::UNKNOWN, group_id, TenantId(), user_key);
+}
+
+// The same envelope inside the per-object shell the route stores.
+inline std::shared_ptr<ObjectEntry> MakeObjectEntry(
+    const std::string& key, const std::string& group_id = {}) {
+    return std::make_shared<ObjectEntry>(MakeObjectMetadata(key, group_id));
+}
+
+}  // namespace test
+}  // namespace mooncake
diff --git a/mooncake-store/tests/offload_on_evict_test.cpp b/mooncake-store/tests/offload_on_evict_test.cpp
index 08810e6fdf..f93a6c06fc 100644
--- a/mooncake-store/tests/offload_on_evict_test.cpp
+++ b/mooncake-store/tests/offload_on_evict_test.cpp
@@ -1,9 +1,9 @@
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
-#include <atomic>
 #include <chrono>
 #include <memory>
 #include <string>
@@ -76,352 +76,79 @@ class OffloadOnEvictTest : public ::testing::Test {
         }
         return queued;
     }
-
-    template <typename Predicate>
-    void WaitUntil(
-        Predicate&& predicate,
-        std::chrono::milliseconds timeout = std::chrono::milliseconds(4000),
-        std::chrono::milliseconds interval =
-            std::chrono::milliseconds(50)) const {
-        const auto deadline = std::chrono::steady_clock::now() + timeout;
-        while (std::chrono::steady_clock::now() < deadline) {
-            if (predicate()) {
-                return;
-            }
-            std::this_thread::sleep_for(interval);
-        }
-        EXPECT_TRUE(predicate());
-    }
-
-    // Fill a segment until PutStart fails, triggering eviction.
-    // Returns the number of successful puts.
-    int FillSegmentUntilEviction(MasterService& service, const UUID& client_id,
-                                 const std::string& key_prefix,
-                                 size_t object_size, int max_puts) {
-        int success_puts = 0;
-        for (int i = 0; i < max_puts; ++i) {
-            std::string key = key_prefix + std::to_string(i);
-            ReplicateConfig config;
-            config.replica_num = 1;
-            auto result = service.PutStart(client_id, key, TenantId::Default(),
-                                           object_size, config);
-            if (result.has_value()) {
-                auto end = service.PutEnd(client_id, key, TenantId::Default(),
-                                          ReplicaType::MEMORY);
-                EXPECT_TRUE(end.has_value());
-                success_puts++;
-            } else {
-                // Wait for eviction to process
-                std::this_thread::sleep_for(std::chrono::milliseconds(50));
-            }
-        }
-        return success_puts;
-    }
 };
 
 // =============================================================================
-// Combo A: Default config (offload at PutEnd)
-// =============================================================================
-
-TEST_F(OffloadOnEvictTest, ComboA_OffloadAtPutEnd) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.default_kv_lease_ttl = 2000;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-
-    // Mount local disk segment with offloading ENABLED
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    // Put objects
-    PutObject(*service, ctx.client_id, "key_a1");
-    PutObject(*service, ctx.client_id, "key_a2");
-    PutObject(*service, ctx.client_id, "key_a3");
-
-    // Default mode: PutEnd pushes to offload queue immediately
-    auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_EQ(queued.size(), 3u)
-        << "Default: all 3 objects should be in offload queue after PutEnd";
-    EXPECT_TRUE(queued.count("key_a1"));
-    EXPECT_TRUE(queued.count("key_a2"));
-    EXPECT_TRUE(queued.count("key_a3"));
-
-    service->RemoveAll();
-}
-
-TEST_F(OffloadOnEvictTest, ComboA_EvictionWorks) {
-    // Regression: eviction still works in default mode
-    const uint64_t kv_lease_ttl = 2000;
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.default_kv_lease_ttl = kv_lease_ttl;
-    auto service = std::make_unique<MasterService>(config);
-
-    // Large segment: can hold ~16K objects of 15KB
-    constexpr size_t seg_size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-
-    // Put more objects than the segment can hold
-    int success_puts = FillSegmentUntilEviction(
-        *service, ctx.client_id, "evict_a_", object_size, 1024 * 16 + 50);
-    EXPECT_GT(success_puts, 1024 * 16)
-        << "Default: eviction should allow more puts than capacity";
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service->RemoveAll();
-}
-
-// =============================================================================
-// Combo B: offload_on_evict=true (offload on evict, no force-evict)
+// UpsertStart interaction with an outstanding offload task.
+//
+// The task passes through two observable states in offloading_tasks[key]:
+//   QUEUED    - mirror entry still present in offloading_objects; the store
+//               worker has not observed the task. UpsertStart cancels the
+//               task in place and allocates a fresh replica.
+//   IN-FLIGHT - mirror already drained by OffloadObjectHeartbeat; the worker
+//               is reading the source buffer for SSD write. UpsertStart
+//               returns OBJECT_HAS_REPLICATION_TASK; the caller retries
+//               after NotifyOffloadSuccess clears the marker.
 // =============================================================================
 
-TEST_F(OffloadOnEvictTest, ComboB_PutEndSkipsOffloadQueue) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_on_evict = true;
-    config.default_kv_lease_ttl = 2000;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    PutObject(*service, ctx.client_id, "key_b1");
-    PutObject(*service, ctx.client_id, "key_b2");
-    PutObject(*service, ctx.client_id, "key_b3");
-
-    // Offload-on-evict: PutEnd should NOT push to offload queue
-    auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_EQ(queued.size(), 0u)
-        << "Offload-on-evict: queue should be empty after PutEnd";
-
-    service->RemoveAll();
-}
-
-TEST_F(OffloadOnEvictTest, ComboB_EvictionTriggersOffload) {
-    const uint64_t kv_lease_ttl = 2000;
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_on_evict = true;
-    config.default_kv_lease_ttl = kv_lease_ttl;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    // Fill segment to trigger eviction
-    bool eviction_triggered = false;
-    int success_puts = 0;
-    for (int i = 0; i < 1024 * 16 + 50; ++i) {
-        std::string key = "evict_b_" + std::to_string(i);
-        ReplicateConfig config;
-        config.replica_num = 1;
-        auto result = service->PutStart(ctx.client_id, key, TenantId::Default(),
-                                        object_size, config);
-        if (result.has_value()) {
-            auto end = service->PutEnd(ctx.client_id, key, TenantId::Default(),
-                                       ReplicaType::MEMORY);
-            ASSERT_TRUE(end.has_value());
-            success_puts++;
-        } else {
-            eviction_triggered = true;
-            std::this_thread::sleep_for(std::chrono::milliseconds(50));
-        }
-    }
-
-    EXPECT_TRUE(eviction_triggered)
-        << "Eviction should trigger when segment fills up";
-
-    // Offload-on-evict: eviction should push objects to offload queue
-    auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_GT(queued.size(), 0u)
-        << "Offload-on-evict: eviction should push to offload queue";
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service->RemoveAll();
-}
-
-TEST_F(OffloadOnEvictTest, ComboB_NoFallbackWithoutForceEvict) {
-    // Without force_evict AND without a LocalDiskSegment, offload queue push
-    // fails and eviction does NOT force-delete MEMORY (data-preserving).
-    // The segment fills and subsequent puts fail — this is the safe default.
-    const uint64_t kv_lease_ttl = 2000;
+TEST_F(OffloadOnEvictTest, UpsertPreemptsQueuedOffloadWithOffloadOnEvict) {
+    // With offload_on_evict the task is queued by eviction rather than by
+    // PutEnd.
+    const uint64_t kv_lease_ttl = 500;
     MasterServiceConfig config;
     config.enable_offload = true;
     config.offload_on_evict = true;
     config.default_kv_lease_ttl = kv_lease_ttl;
     auto service = std::make_unique<MasterService>(config);
 
-    // NO local disk segment mounted — PushOffloadingQueue will fail
-    constexpr size_t seg_size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-
-    // Without force_evict, push failures mean DRAM cannot be freed,
-    // so we can only put up to segment capacity (no overflow).
-    int success_puts = FillSegmentUntilEviction(
-        *service, ctx.client_id, "evict_b2_", object_size, 1024 * 16 + 50);
-    EXPECT_LE(success_puts, 1024 * 16)
-        << "Without force_evict, segment should fill and stay full";
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service->RemoveAll();
-}
-
-// =============================================================================
-// Combo C: offload_on_evict=true + offload_force_evict=true
-// =============================================================================
-
-TEST_F(OffloadOnEvictTest, ComboC_PutEndSkipsOffloadQueue) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_on_evict = true;
-    config.offload_force_evict = true;
-    config.default_kv_lease_ttl = 2000;
-    auto service = std::make_unique<MasterService>(config);
-
     constexpr size_t seg_size = 1024 * 1024 * 16;
+    constexpr size_t object_size = 1024 * 1024;
     auto ctx =
         PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    PutObject(*service, ctx.client_id, "key_c1");
-    PutObject(*service, ctx.client_id, "key_c2");
-
-    // Same as Combo B: PutEnd should skip offload queue
-    auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_EQ(queued.size(), 0u)
-        << "Combo C: offload queue should be empty after PutEnd";
-
-    service->RemoveAll();
-}
-
-TEST_F(OffloadOnEvictTest, ComboC_EvictionWithForceEvict) {
-    const uint64_t kv_lease_ttl = 2000;
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_on_evict = true;
-    config.offload_force_evict = true;
-    config.default_kv_lease_ttl = kv_lease_ttl;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    // With force-evict, eviction should work effectively.
-    // Note: without a real FileStorage heartbeat, offloaded objects' refcnt
-    // never decreases, so DRAM isn't fully freed beyond what direct eviction
-    // allows. We verify eviction doesn't deadlock (can fill to capacity).
-    int success_puts = FillSegmentUntilEviction(
-        *service, ctx.client_id, "evict_c_", object_size, 1024 * 16 + 50);
-    EXPECT_GE(success_puts, 1024 * 16)
-        << "Combo C: eviction should work with force-evict enabled";
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service->RemoveAll();
-}
-
-// =============================================================================
-// Combo D: offload_force_evict=true only (should be no-op without on_evict)
-// =============================================================================
+    ASSERT_TRUE(service->MountLocalDiskSegment(ctx.client_id, true));
 
-TEST_F(OffloadOnEvictTest, ComboD_ForceEvictAloneIsIgnored) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_force_evict = true;  // on_evict is false → force is ignored
-    config.default_kv_lease_ttl = 2000;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    // Should behave like Combo A (default: offload at PutEnd)
-    PutObject(*service, ctx.client_id, "key_d1");
-    PutObject(*service, ctx.client_id, "key_d2");
+    std::vector<std::string> keys;
+    for (int i = 0; i < 8; ++i) {
+        keys.push_back("evict_upsert_" + std::to_string(i));
+        PutObject(*service, ctx.client_id, keys.back(), object_size);
+    }
 
+    // PutEnd does not queue offloads in this mode; eviction does.
     auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_EQ(queued.size(), 2u)
-        << "Combo D: FORCE_EVICT alone should not change default behavior";
+    ASSERT_TRUE(queued.empty())
+        << "offload_on_evict: PutEnd must not queue offloads";
 
-    service->RemoveAll();
-}
+    // Let leases expire so the keys are evictable, then run one eviction
+    // cycle to queue their offloads without draining the mirrors.
+    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl * 2));
+    MasterServiceTestPeer(*service).RunBatchEvictForTesting(1.0, 1.0);
 
-TEST_F(OffloadOnEvictTest, ComboD_EvictionWorks) {
-    const uint64_t kv_lease_ttl = 2000;
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.offload_force_evict = true;  // on_evict is false → force is ignored
-    config.default_kv_lease_ttl = kv_lease_ttl;
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16 * 15;
-    constexpr size_t object_size = 1024 * 15;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-
-    int success_puts = FillSegmentUntilEviction(
-        *service, ctx.client_id, "evict_d_", object_size, 1024 * 16 + 50);
-    EXPECT_GT(success_puts, 1024 * 16)
-        << "Combo D: eviction should work normally";
-
-    std::this_thread::sleep_for(std::chrono::milliseconds(kv_lease_ttl));
-    service->RemoveAll();
-}
-
-// Regression: EraseMetadata must drop the mirror entry in
-// LocalDiskSegment::offloading_objects. Otherwise BatchRemove leaves a
-// task-less key in the offload queue which the next
-// OffloadObjectHeartbeat drains back to the client, producing an
-// orphan bucket on SSD.
-TEST_F(OffloadOnEvictTest, BatchRemoveDropsOffloadingObjectsMirror) {
-    MasterServiceConfig config;
-    config.enable_offload = true;
-    config.default_kv_lease_ttl = 0;  // no lease so BatchRemove succeeds
-    auto service = std::make_unique<MasterService>(config);
-
-    constexpr size_t seg_size = 1024 * 1024 * 16;
-    auto ctx =
-        PrepareSegment(*service, "test_segment", kDefaultSegmentBase, seg_size);
-    auto mount_ld = service->MountLocalDiskSegment(ctx.client_id, true);
-    ASSERT_TRUE(mount_ld.has_value());
-
-    const std::vector<std::string> keys = {"key_r1", "key_r2", "key_r3"};
+    std::string offloading_key;
     for (const auto& k : keys) {
-        PutObject(*service, ctx.client_id, k);
+        auto upsert =
+            service->UpsertStart(ctx.client_id, k, TenantId::Default(),
+                                 object_size, ReplicateConfig{});
+        if (upsert.has_value()) {
+            offloading_key = k;
+            EXPECT_EQ(upsert->size(), 1u);
+            EXPECT_EQ(upsert->at(0).status, ReplicaStatus::PROCESSING);
+            ASSERT_TRUE(service
+                            ->PutEnd(ctx.client_id, k, TenantId::Default(),
+                                     ReplicaType::MEMORY)
+                            .has_value());
+            break;
+        }
     }
+    ASSERT_FALSE(offloading_key.empty())
+        << "expected UpsertStart to preempt an offload queued by eviction";
 
-    // Remove before heartbeat drains the offload queue.
-    auto rm = service->BatchRemove(keys, TenantId::Default(), /*force=*/true);
-    for (const auto& r : rm) {
-        EXPECT_TRUE(r.has_value());
-    }
+    // Preempt cleared the marker and the mirror, so no stale entry is handed
+    // to the store worker for the preempted key.
+    auto stale = DrainOffloadQueue(*service, ctx.client_id);
+    EXPECT_EQ(stale.count(offloading_key), 0u)
+        << "preempted key must not remain queued";
 
-    auto queued = DrainOffloadQueue(*service, ctx.client_id);
-    EXPECT_TRUE(queued.empty())
-        << "OffloadObjectHeartbeat returned " << queued.size()
-        << " stale entries after BatchRemove; EraseMetadata failed to clean "
-           "offloading_objects.";
+    service->RemoveAll();
 }
 
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/offset_allocator_backend_config_test.cpp b/mooncake-store/tests/offset_allocator_backend_config_test.cpp
new file mode 100644
index 0000000000..71107eba86
--- /dev/null
+++ b/mooncake-store/tests/offset_allocator_backend_config_test.cpp
@@ -0,0 +1,224 @@
+#include "config/offset_allocator_backend_config.h"
+
+#include <gtest/gtest.h>
+
+#include <cmath>
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+struct OffsetAllocatorEnvironment {
+    ScopedEnvVar policy{"MOONCAKE_OFFSET_EVICTION_POLICY"};
+    ScopedEnvVar high_ratio{"MOONCAKE_OFFSET_HIGH_RATIO"};
+    ScopedEnvVar low_ratio{"MOONCAKE_OFFSET_LOW_RATIO"};
+    ScopedEnvVar max_nodes{"MOONCAKE_OFFSET_MAX_CAPACITY_NODES"};
+    ScopedEnvVar max_evict{"MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD"};
+    ScopedEnvVar persist_mode{"MOONCAKE_OFFSET_PERSIST_MODE"};
+    ScopedEnvVar persist_interval{"MOONCAKE_OFFSET_PERSIST_INTERVAL_SECONDS"};
+    ScopedEnvVar record_crc{"MOONCAKE_OFFSET_RECORD_CRC"};
+
+    void SetAll(const char* value) {
+        policy.Set(value);
+        high_ratio.Set(value);
+        low_ratio.Set(value);
+        max_nodes.Set(value);
+        max_evict.Set(value);
+        persist_mode.Set(value);
+        persist_interval.Set(value);
+        record_crc.Set(value);
+    }
+};
+
+void ExpectDefaultOffsetAllocatorConfig(
+    const OffsetAllocatorBackendConfig& config) {
+    EXPECT_EQ(config.eviction_policy, OffsetEvictionPolicy::NONE);
+    EXPECT_EQ(config.high_watermark_bytes, 0);
+    EXPECT_EQ(config.low_watermark_bytes, 0);
+    EXPECT_DOUBLE_EQ(config.high_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.low_ratio, 0.80);
+    EXPECT_EQ(config.high_watermark_keys, 0);
+    EXPECT_EQ(config.low_watermark_keys, 0);
+    EXPECT_DOUBLE_EQ(config.keys_high_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.keys_low_ratio, 0.80);
+    EXPECT_EQ(config.max_capacity_nodes, 0);
+    EXPECT_EQ(config.max_evict_per_offload, 4096);
+    EXPECT_EQ(config.fallback_evict_batch, 16);
+    EXPECT_EQ(config.persist_mode, OffsetPersistMode::kDisabled);
+    EXPECT_EQ(config.persist_interval_seconds, 60);
+    EXPECT_TRUE(config.enable_record_crc);
+}
+
+class OffsetAllocatorEnvironmentTest : public ::testing::Test {
+   protected:
+    OffsetAllocatorEnvironment env;
+};
+
+TEST_F(OffsetAllocatorEnvironmentTest, KeepsDefaultsWhenVariablesAreUnset) {
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    ExpectDefaultOffsetAllocatorConfig(config);
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest, ReadsValidValues) {
+    env.policy.Set("FIFO");
+    env.high_ratio.Set("0.75");
+    env.low_ratio.Set("0.50");
+    env.max_nodes.Set("123");
+    env.max_evict.Set("17");
+    env.persist_mode.Set("RELAXED");
+    env.persist_interval.Set("10");
+    env.record_crc.Set("false");
+
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    EXPECT_EQ(config.eviction_policy, OffsetEvictionPolicy::FIFO);
+    EXPECT_DOUBLE_EQ(config.high_ratio, 0.75);
+    EXPECT_DOUBLE_EQ(config.low_ratio, 0.50);
+    EXPECT_DOUBLE_EQ(config.keys_high_ratio, 0.75);
+    EXPECT_DOUBLE_EQ(config.keys_low_ratio, 0.50);
+    EXPECT_EQ(config.max_capacity_nodes, 123);
+    EXPECT_EQ(config.max_evict_per_offload, 17);
+    EXPECT_EQ(config.persist_mode, OffsetPersistMode::kRelaxed);
+    EXPECT_EQ(config.persist_interval_seconds, 10);
+    EXPECT_FALSE(config.enable_record_crc);
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest, PreservesLegacyRatioParsing) {
+    env.high_ratio.Set("0.75suffix");
+
+    const auto suffixed = OffsetAllocatorBackendConfig::FromEnvironment();
+    EXPECT_DOUBLE_EQ(suffixed.high_ratio, 0.75);
+    EXPECT_DOUBLE_EQ(suffixed.keys_high_ratio, 0.75);
+
+    env.high_ratio.Set("nan");
+    const auto nan = OffsetAllocatorBackendConfig::FromEnvironment();
+    EXPECT_TRUE(std::isnan(nan.high_ratio));
+    EXPECT_TRUE(std::isnan(nan.keys_high_ratio));
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest, KeepsDefaultsForInvalidValues) {
+    env.policy.Set("unknown");
+    env.high_ratio.Set("not-a-ratio");
+    env.low_ratio.Set("not-a-ratio");
+    env.max_nodes.Set("not-an-integer");
+    env.max_evict.Set("-1");
+    env.persist_mode.Set("unknown");
+    env.persist_interval.Set("not-an-integer");
+    env.record_crc.Set("unknown");
+
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    ExpectDefaultOffsetAllocatorConfig(config);
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest,
+       KeepsDefaultRatioForWhitespacePrefixedInvalidValue) {
+    env.high_ratio.Set(" invalid");
+
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    EXPECT_DOUBLE_EQ(config.high_ratio, 0.90);
+    EXPECT_DOUBLE_EQ(config.keys_high_ratio, 0.90);
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest, KeepsDefaultsForEmptyValues) {
+    env.SetAll("");
+
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    ExpectDefaultOffsetAllocatorConfig(config);
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest,
+       PreservesDiagnosticsForUnparsableAndEmptyValues) {
+    for (const char* value : {"invalid", ""}) {
+        env.SetAll(value);
+        testing::internal::CaptureStderr();
+        const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+        const std::string logs = testing::internal::GetCapturedStderr();
+
+        ExpectDefaultOffsetAllocatorConfig(config);
+        EXPECT_NE(logs.find("MOONCAKE_OFFSET_MAX_CAPACITY_NODES"),
+                  std::string::npos);
+        EXPECT_NE(logs.find("MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD"),
+                  std::string::npos);
+        EXPECT_NE(logs.find("MOONCAKE_OFFSET_PERSIST_MODE"), std::string::npos);
+        EXPECT_NE(logs.find("MOONCAKE_OFFSET_PERSIST_INTERVAL_SECONDS"),
+                  std::string::npos);
+        EXPECT_EQ(logs.find("MOONCAKE_OFFSET_EVICTION_POLICY"),
+                  std::string::npos);
+        EXPECT_EQ(logs.find("MOONCAKE_OFFSET_HIGH_RATIO"), std::string::npos);
+        EXPECT_EQ(logs.find("MOONCAKE_OFFSET_LOW_RATIO"), std::string::npos);
+        EXPECT_EQ(logs.find("MOONCAKE_OFFSET_RECORD_CRC"), std::string::npos);
+    }
+}
+
+TEST_F(OffsetAllocatorEnvironmentTest,
+       PreservesWarningForNonPositiveEvictionCap) {
+    env.max_evict.Set("-1");
+    testing::internal::CaptureStderr();
+    const auto config = OffsetAllocatorBackendConfig::FromEnvironment();
+    const std::string logs = testing::internal::GetCapturedStderr();
+
+    ExpectDefaultOffsetAllocatorConfig(config);
+    EXPECT_NE(logs.find("MOONCAKE_OFFSET_MAX_EVICT_PER_OFFLOAD=-1 is "
+                        "non-positive"),
+              std::string::npos);
+}
+
+TEST(OffsetAllocatorBackendConfigValidationTest, AcceptsDefaults) {
+    EXPECT_TRUE(OffsetAllocatorBackendConfig{}.Validate());
+}
+
+TEST(OffsetAllocatorBackendConfigValidationTest, RejectsExistingInvalidCases) {
+    auto expect_invalid = [](auto mutate) {
+        OffsetAllocatorBackendConfig config;
+        mutate(config);
+        EXPECT_FALSE(config.Validate());
+    };
+
+    expect_invalid([](auto& config) {
+        config.persist_mode = OffsetPersistMode::kRelaxed;
+        config.persist_interval_seconds = 4;
+    });
+    expect_invalid([](auto& config) { config.high_ratio = 0.0; });
+    expect_invalid([](auto& config) { config.high_ratio = 1.1; });
+    expect_invalid([](auto& config) { config.low_ratio = 0.0; });
+    expect_invalid([](auto& config) { config.low_ratio = config.high_ratio; });
+    expect_invalid([](auto& config) { config.keys_high_ratio = 0.0; });
+    expect_invalid([](auto& config) { config.keys_high_ratio = 1.1; });
+    expect_invalid([](auto& config) { config.keys_low_ratio = 0.0; });
+    expect_invalid(
+        [](auto& config) { config.keys_low_ratio = config.keys_high_ratio; });
+    expect_invalid([](auto& config) { config.max_evict_per_offload = 0; });
+    expect_invalid([](auto& config) { config.fallback_evict_batch = 0; });
+    expect_invalid([](auto& config) { config.max_capacity_nodes = -1; });
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/offset_allocator_test.cpp b/mooncake-store/tests/offset_allocator_test.cpp
index abf976a2d5..cb2273c102 100644
--- a/mooncake-store/tests/offset_allocator_test.cpp
+++ b/mooncake-store/tests/offset_allocator_test.cpp
@@ -1,3 +1,4 @@
+#include "allocator.h"
 #include "offset_allocator/offset_allocator.h"
 #include "mutex.h"
 #include "serializer.h"
@@ -6,6 +7,7 @@
 #include <gtest/gtest.h>
 
 #include <chrono>
+#include <functional>
 #include <future>
 #include <limits>
 #include <map>
@@ -342,6 +344,171 @@ class OffsetAllocatorTest : public ::testing::Test {
         handle.getHandle().m_allocator = new_allocator;
     }
 
+    // Corruptions used by SnapshotValidationRejectsInconsistentLayout. TEST_F
+    // bodies live in a derived class, so the layout access stays in fixture
+    // members, which hold __Allocator's friendship.
+    enum class LayoutFault {
+        kNone,
+        kBinIndexOutOfRange,
+        kUsedNodeInBinList,
+        kFreeStorageMismatch,
+        kFreeOffsetTooLarge,
+        kFreeOffsetTooSmall,
+        kDuplicateSpareNode,
+        kSpareNodeIsLive,
+        kUnclassifiedNode,
+        kNodeOffsetShifted,
+        kNeighborChainBroken,
+        kBinBitWithoutList,
+        kUsedNodeZeroSize,
+        kUsedNodeNotBinBoundary,
+        kBinCycle,
+        kNeighborOutOfRange,
+        kNodeCapacityZero,
+        kNodeCapacityTooLarge,
+        kFreeOffsetOutOfRange,
+        kNodeStorageTooShort,
+        kNodeStorageTooLong,
+        kFreeNodeStorageTooLong,
+    };
+
+    static uint32 firstUsedNode(const __Allocator& layout) {
+        for (uint32 i = 0; i < layout.m_current_capacity; ++i) {
+            if (layout.m_nodes[i].used) {
+                return i;
+            }
+        }
+        return __Allocator::Node::unused;
+    }
+
+    static void applyLayoutFault(__Allocator& layout, LayoutFault fault) {
+        const uint32 used = firstUsedNode(layout);
+        ASSERT_NE(used, __Allocator::Node::unused);
+        switch (fault) {
+            case LayoutFault::kNone:
+                break;
+            case LayoutFault::kUsedNodeZeroSize:
+                layout.m_nodes[used].dataSize = 0;
+                break;
+            case LayoutFault::kUsedNodeNotBinBoundary:
+                ++layout.m_nodes[used].dataSize;
+                break;
+            case LayoutFault::kBinCycle:
+                for (uint32 bin = 0; bin < NUM_LEAF_BINS; ++bin) {
+                    const uint32 head = layout.m_binIndices[bin];
+                    if (head != __Allocator::Node::unused) {
+                        layout.m_nodes[head].binListNext = head;
+                        return;
+                    }
+                }
+                FAIL() << "no free bin to corrupt";
+                break;
+            case LayoutFault::kNeighborOutOfRange:
+                layout.m_nodes[used].neighborNext = layout.m_current_capacity;
+                break;
+            case LayoutFault::kNodeCapacityZero:
+                layout.m_current_capacity = 0;
+                break;
+            case LayoutFault::kNodeCapacityTooLarge:
+                layout.m_max_capacity = OffsetAllocatorSnapshot::kMaxNodes + 1;
+                break;
+            case LayoutFault::kFreeOffsetOutOfRange:
+                layout.m_freeOffset = layout.m_current_capacity + 1;
+                break;
+            case LayoutFault::kNodeStorageTooShort:
+                layout.m_nodes.clear();
+                break;
+            case LayoutFault::kNodeStorageTooLong:
+                layout.m_nodes.emplace_back();
+                break;
+            case LayoutFault::kFreeNodeStorageTooLong:
+                layout.m_freeNodes.push_back(0);
+                break;
+            case LayoutFault::kBinIndexOutOfRange:
+                layout.m_binIndices[0] = layout.m_current_capacity;
+                break;
+            case LayoutFault::kUsedNodeInBinList: {
+                uint32 empty_bin = NUM_LEAF_BINS;
+                for (uint32 bin = 0; bin < NUM_LEAF_BINS; ++bin) {
+                    if (layout.m_binIndices[bin] == __Allocator::Node::unused) {
+                        empty_bin = bin;
+                        break;
+                    }
+                }
+                ASSERT_NE(empty_bin, NUM_LEAF_BINS);
+                layout.m_binIndices[empty_bin] = used;
+                layout.m_nodes[used].binListNext = __Allocator::Node::unused;
+                layout.m_nodes[used].binListPrev = __Allocator::Node::unused;
+                layout.m_usedBins[empty_bin >> TOP_BINS_INDEX_SHIFT] |=
+                    uint8{1} << (empty_bin & LEAF_BINS_INDEX_MASK);
+                layout.m_usedBinsTop |= uint32{1}
+                                        << (empty_bin >> TOP_BINS_INDEX_SHIFT);
+                break;
+            }
+            case LayoutFault::kFreeStorageMismatch:
+                ++layout.m_freeStorage;
+                break;
+            case LayoutFault::kFreeOffsetTooLarge:
+                ++layout.m_freeOffset;
+                break;
+            case LayoutFault::kFreeOffsetTooSmall:
+                --layout.m_freeOffset;
+                break;
+            case LayoutFault::kDuplicateSpareNode:
+                ASSERT_LT(layout.m_freeOffset + 1, layout.m_current_capacity);
+                layout.m_freeNodes[layout.m_freeOffset + 1] =
+                    layout.m_freeNodes[layout.m_freeOffset];
+                break;
+            case LayoutFault::kSpareNodeIsLive:
+                layout.m_freeNodes[layout.m_freeOffset] = used;
+                break;
+            case LayoutFault::kUnclassifiedNode:
+                layout.m_nodes[used].used = false;
+                break;
+            case LayoutFault::kNodeOffsetShifted:
+                ++layout.m_nodes[used].dataOffset;
+                break;
+            case LayoutFault::kNeighborChainBroken:
+                layout.m_nodes[used].neighborNext = __Allocator::Node::unused;
+                break;
+            case LayoutFault::kBinBitWithoutList:
+                for (uint32 bin = 0; bin < NUM_LEAF_BINS; ++bin) {
+                    if (layout.m_binIndices[bin] == __Allocator::Node::unused) {
+                        layout.m_usedBins[bin >> TOP_BINS_INDEX_SHIFT] |=
+                            uint8{1} << (bin & LEAF_BINS_INDEX_MASK);
+                        return;
+                    }
+                }
+                FAIL() << "no empty bin to corrupt";
+                break;
+        }
+    }
+
+    static bool layoutPassesValidation(
+        const std::shared_ptr<OffsetAllocator>& allocator, LayoutFault fault) {
+        auto snapshot = allocator->CaptureSnapshot();
+        applyLayoutFault(*snapshot.layout, fault);
+        return snapshot.Validate().has_value();
+    }
+
+    // End-to-end: the store level factory must refuse to install the same
+    // broken layout the validator rejects.
+    static ErrorCode restoreBufferAllocatorAfterLayoutFault(
+        const std::shared_ptr<OffsetAllocator>& allocator, LayoutFault fault) {
+        auto state = allocator->CaptureSnapshot();
+        applyLayoutFault(*state.layout, fault);
+        OffsetBufferAllocatorSnapshot snapshot{
+            .segment_name = "segment",
+            .base = static_cast<size_t>(state.base),
+            .capacity = state.capacity,
+            .used_bytes = state.allocated_size,
+            .transport_endpoint = "endpoint",
+            .allocation_state = std::move(state),
+        };
+        auto restored = OffsetBufferAllocator::Restore(std::move(snapshot));
+        return restored ? ErrorCode::OK : restored.error();
+    }
+
     void assertAllocatorEQ(const std::shared_ptr<OffsetAllocator>& a,
                            const std::shared_ptr<OffsetAllocator>& b) {
         MutexLocker lock_a(&a->m_mutex);
@@ -1857,6 +2024,173 @@ TEST_F(OffsetAllocatorTest, ChainedAllocationAndDeserialization) {
     }
 }
 
+// A persisted layout is only installed when it is internally consistent, so a
+// corrupt layout cannot produce overlapping allocations, dangling bin links or
+// a free stack that hands the same node out twice. Both snapshot validation
+// and the lowest-level restore factory reject the same corruptions.
+TEST_F(OffsetAllocatorTest, SnapshotValidationRejectsInconsistentLayout) {
+    constexpr uint64_t kBase = 0x100000000ULL;
+    constexpr size_t kSize = 16U * 1024 * 1024;
+    auto allocator = OffsetAllocator::create(kBase, kSize);
+    ASSERT_NE(allocator, nullptr);
+    auto first = allocator->allocate(4096);
+    auto second = allocator->allocate(4096);
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+
+    auto clean = allocator->CaptureSnapshot();
+    ASSERT_TRUE(clean.Validate().has_value());
+    EXPECT_EQ(clean.allocated_num, 2U);
+    EXPECT_EQ(clean.allocated_size, 8192U);
+
+    const std::vector<LayoutFault> faults{
+        LayoutFault::kBinIndexOutOfRange,
+        LayoutFault::kUsedNodeInBinList,
+        LayoutFault::kFreeStorageMismatch,
+        LayoutFault::kFreeOffsetTooLarge,
+        LayoutFault::kFreeOffsetTooSmall,
+        LayoutFault::kDuplicateSpareNode,
+        LayoutFault::kSpareNodeIsLive,
+        LayoutFault::kUnclassifiedNode,
+        LayoutFault::kNodeOffsetShifted,
+        LayoutFault::kNeighborChainBroken,
+        LayoutFault::kBinBitWithoutList,
+        LayoutFault::kUsedNodeZeroSize,
+        LayoutFault::kUsedNodeNotBinBoundary,
+        LayoutFault::kBinCycle,
+        LayoutFault::kNeighborOutOfRange,
+        LayoutFault::kNodeCapacityZero,
+        LayoutFault::kNodeCapacityTooLarge,
+        LayoutFault::kFreeOffsetOutOfRange,
+        LayoutFault::kNodeStorageTooShort,
+        LayoutFault::kNodeStorageTooLong,
+        LayoutFault::kFreeNodeStorageTooLong,
+    };
+    for (const auto fault : faults) {
+        SCOPED_TRACE(static_cast<int>(fault));
+        EXPECT_FALSE(layoutPassesValidation(allocator, fault));
+        auto snapshot = allocator->CaptureSnapshot();
+        applyLayoutFault(*snapshot.layout, fault);
+        const auto valid = snapshot.Validate();
+        ASSERT_FALSE(valid.has_value());
+        EXPECT_FALSE(valid.error().empty());
+        auto restored = OffsetAllocator::Restore(std::move(snapshot));
+        ASSERT_FALSE(restored.has_value());
+        EXPECT_EQ(restored.error(), valid.error());
+        EXPECT_EQ(restoreBufferAllocatorAfterLayoutFault(allocator, fault),
+                  ErrorCode::INVALID_PARAMS);
+    }
+
+    // Rejected layouts must not disturb the allocator they came from.
+    EXPECT_TRUE(layoutPassesValidation(allocator, LayoutFault::kNone));
+}
+
+TEST_F(OffsetAllocatorTest,
+       SnapshotValidationRejectsHeaderAndAccountingFaults) {
+    auto allocator = OffsetAllocator::create(0x100000000ULL, 16U << 20, 16, 32);
+    auto first = allocator->allocate(4096);
+    auto second = allocator->allocate(4096);
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+    struct Fault {
+        const char* diagnostic;
+        std::function<void(OffsetAllocatorSnapshot&)> apply;
+    };
+    const std::vector<Fault> faults{
+        {"layout", [](auto& s) { s.layout.reset(); }},
+        {"bounds", [](auto& s) { s.capacity = 0; }},
+        {"bounds",
+         [](auto& s) { s.base = std::numeric_limits<uint64_t>::max(); }},
+        {"multiplier_bits", [](auto& s) { s.multiplier_bits = 64; }},
+        {"multiplier_bits",
+         [](auto& s) {
+             s.multiplier_bits = std::numeric_limits<uint64_t>::max();
+         }},
+        {"multiplier_bits", [](auto& s) { s.multiplier_bits = 1; }},
+        {"layout size", [](auto& s) { ++s.capacity; }},
+        {"allocated_num", [](auto& s) { s.allocated_num = 0; }},
+        {"allocated_num", [](auto& s) { ++s.allocated_num; }},
+        {"allocated_size", [](auto& s) { s.allocated_size = 0; }},
+        {"allocated_size", [](auto& s) { s.allocated_size = 7681; }},
+        {"allocated_size", [](auto& s) { s.allocated_size = 8193; }},
+    };
+    for (const auto& fault : faults) {
+        SCOPED_TRACE(fault.diagnostic);
+        auto snapshot = allocator->CaptureSnapshot();
+        fault.apply(snapshot);
+        const auto valid = snapshot.Validate();
+        ASSERT_FALSE(valid.has_value());
+        EXPECT_NE(valid.error().find(fault.diagnostic), std::string::npos);
+        auto restored = OffsetAllocator::Restore(std::move(snapshot));
+        ASSERT_FALSE(restored.has_value());
+        EXPECT_EQ(restored.error(), valid.error());
+    }
+}
+
+TEST_F(OffsetAllocatorTest, SnapshotCapacityPreflightRejectsInvalidFields) {
+    const auto validate = OffsetAllocatorSnapshot::ValidateNodeCapacity;
+    EXPECT_TRUE(validate(1024, 16, OffsetAllocatorSnapshot::kMaxNodes, 1));
+    EXPECT_TRUE(validate(1024, OffsetAllocatorSnapshot::kMaxNodes,
+                         OffsetAllocatorSnapshot::kMaxNodes,
+                         OffsetAllocatorSnapshot::kMaxNodes));
+    EXPECT_FALSE(validate(0, 16, 32, 1));
+    EXPECT_FALSE(validate(1024, 0, 32, 0));
+    EXPECT_FALSE(validate(1024, 16, 0, 1));
+    EXPECT_FALSE(validate(1024, 33, 32, 1));
+    EXPECT_FALSE(validate(1024, 16, OffsetAllocatorSnapshot::kMaxNodes + 1, 1));
+    EXPECT_FALSE(validate(1024, 16, 32, 17));
+}
+
+TEST_F(OffsetAllocatorTest, SnapshotValidationAcceptsRoundingAndBoundsUsage) {
+    for (const uint64_t capacity : {uint64_t{16} << 20, uint64_t{32} << 30}) {
+        SCOPED_TRACE(capacity);
+        auto allocator =
+            OffsetAllocator::create(0x100000000ULL, capacity, 16, 32);
+        auto allocation = allocator->allocate(4097);
+        ASSERT_TRUE(allocation.has_value());
+        auto snapshot = allocator->CaptureSnapshot();
+        ASSERT_TRUE(snapshot.Validate().has_value());
+        EXPECT_EQ(snapshot.allocated_size, 4097U);
+        auto restored = OffsetAllocator::Restore(std::move(snapshot));
+        ASSERT_TRUE(restored.has_value());
+        EXPECT_EQ((*restored)->get_metrics().allocated_size_, 4097U);
+        EXPECT_EQ((*restored)->get_metrics().allocated_num_, 1U);
+
+#ifndef OFFSET_ALLOCATOR_NOT_ROUND_UP
+        // A 4097-byte request consumes 4608 bytes. Both bin rounding and the
+        // large allocator's unit shift allow [4097, 4608], not arbitrary values
+        // below the occupied size. Exact original requests cannot be recovered
+        // from the layout alone.
+        for (const uint64_t requested : {4096U, 4097U, 4608U, 4609U}) {
+            auto candidate = allocator->CaptureSnapshot();
+            candidate.allocated_size = requested;
+            EXPECT_EQ(candidate.Validate().has_value(),
+                      requested >= 4097 && requested <= 4608);
+        }
+#endif
+    }
+}
+
+TEST_F(OffsetAllocatorTest,
+       SnapshotValidationAcceptsEmptyFullAndSmallAllocations) {
+    auto allocator = OffsetAllocator::create(0, 16, 16, 32);
+    EXPECT_TRUE(allocator->CaptureSnapshot().Validate().has_value());
+    auto full = allocator->allocate(16);
+    ASSERT_TRUE(full.has_value());
+    EXPECT_TRUE(allocator->CaptureSnapshot().Validate().has_value());
+    full.reset();
+    EXPECT_TRUE(allocator->CaptureSnapshot().Validate().has_value());
+
+    for (const uint64_t capacity : {uint64_t{16} << 20, uint64_t{32} << 30}) {
+        auto small = OffsetAllocator::create(0, capacity, 16, 32);
+        for (const size_t requested : {1U, 7U, 8U, 9U}) {
+            auto allocation = small->allocate(requested);
+            ASSERT_TRUE(allocation.has_value());
+            EXPECT_TRUE(small->CaptureSnapshot().Validate().has_value());
+        }
+    }
+}
+
 }  // namespace mooncake::offset_allocator
 
 int main(int argc, char** argv) {
diff --git a/mooncake-store/tests/oss_adapter_config_test.cpp b/mooncake-store/tests/oss_adapter_config_test.cpp
new file mode 100644
index 0000000000..d8e42a1030
--- /dev/null
+++ b/mooncake-store/tests/oss_adapter_config_test.cpp
@@ -0,0 +1,352 @@
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdlib>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <string>
+
+#include "../src/config/oss_adapter_config.h"
+#include "storage/distributed/oss_adapter.h"
+
+namespace mooncake {
+namespace {
+
+std::mutex environment_mutex;
+
+class OssAdapterConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        environment_lock_ = std::unique_lock<std::mutex>(environment_mutex);
+        for (const char* name : kVariables) {
+            if (const char* value = std::getenv(name)) {
+                original_values_[name] = value;
+            } else {
+                original_values_[name] = std::nullopt;
+            }
+            ASSERT_EQ(unsetenv(name), 0) << name;
+        }
+    }
+
+    void TearDown() override {
+        for (const auto& [name, value] : original_values_) {
+            if (value) {
+                EXPECT_EQ(setenv(name.c_str(), value->c_str(), 1), 0) << name;
+            } else {
+                EXPECT_EQ(unsetenv(name.c_str()), 0) << name;
+            }
+        }
+    }
+
+    void Set(const char* name, const std::string& value) {
+        ASSERT_EQ(setenv(name, value.c_str(), 1), 0) << name;
+    }
+
+    void SetRequiredPrimary() {
+        Set("MOONCAKE_OSS_ENDPOINT", "https://oss.example.com");
+        Set("MOONCAKE_OSS_BUCKET", "bucket");
+        Set("MOONCAKE_OSS_REGION", "region");
+    }
+
+   private:
+    inline static constexpr std::array<const char*, 17> kVariables = {
+        "MOONCAKE_OSS_ENDPOINT",
+        "OSS_ENDPOINT",
+        "MOONCAKE_OSS_BUCKET",
+        "OSS_BUCKET",
+        "MOONCAKE_OSS_REGION",
+        "OSS_REGION",
+        "MOONCAKE_OSS_ACCESS_KEY_ID",
+        "OSS_ACCESS_KEY_ID",
+        "MOONCAKE_OSS_ACCESS_KEY_SECRET",
+        "OSS_ACCESS_KEY_SECRET",
+        "MOONCAKE_OSS_SECURITY_TOKEN",
+        "OSS_SESSION_TOKEN",
+        "MOONCAKE_OSS_PATH_STYLE",
+        "MOONCAKE_OSS_ANONYMOUS",
+        "MOONCAKE_OSS_MAX_CONNECTIONS",
+        "MOONCAKE_OSS_RECEIVE_BUFFER_SIZE",
+        "MOONCAKE_OSS_UPLOAD_BUFFER_SIZE",
+    };
+
+    std::map<std::string, std::optional<std::string>> original_values_;
+    std::unique_lock<std::mutex> environment_lock_;
+};
+
+TEST_F(OssAdapterConfigTest, InitUsesCompatibilityAliases) {
+    Set("OSS_ENDPOINT", "https://oss.example.com");
+    Set("OSS_BUCKET", "bucket");
+    Set("OSS_REGION", "region");
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("prefix");
+    EXPECT_TRUE(adapter.Init());
+}
+
+TEST_F(OssAdapterConfigTest, EmptyPrimaryOverridesCompatibilityAlias) {
+    Set("OSS_ENDPOINT", "https://oss.example.com");
+    Set("MOONCAKE_OSS_ENDPOINT", "");
+    Set("MOONCAKE_OSS_BUCKET", "bucket");
+    Set("MOONCAKE_OSS_REGION", "region");
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("prefix");
+    const auto result = adapter.Init();
+
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(OssAdapterConfigTest, CredentialsAreRequiredUnlessAnonymous) {
+    SetRequiredPrimary();
+
+    OssObjectStorageAdapter authenticated("prefix");
+    const auto missing_credentials = authenticated.Init();
+    ASSERT_FALSE(missing_credentials);
+    EXPECT_EQ(missing_credentials.error(), ErrorCode::INVALID_PARAMS);
+
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    OssObjectStorageAdapter anonymous("prefix");
+    EXPECT_TRUE(anonymous.Init());
+}
+
+TEST_F(OssAdapterConfigTest, InvalidAnonymousValueWarnsAndUsesFalse) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "invalid");
+
+    testing::internal::CaptureStderr();
+    OssObjectStorageAdapter adapter("prefix");
+    const auto result = adapter.Init();
+    const std::string diagnostics = testing::internal::GetCapturedStderr();
+
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_NE(diagnostics.find("invalid value 'invalid' for env "
+                               "MOONCAKE_OSS_ANONYMOUS, using default 0"),
+              std::string::npos);
+}
+
+TEST_F(OssAdapterConfigTest, InitReadsCurrentEnvironmentEachTime) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("prefix");
+    EXPECT_TRUE(adapter.Init());
+
+    Set("MOONCAKE_OSS_ANONYMOUS", "false");
+    const auto second = adapter.Init();
+    ASSERT_FALSE(second);
+    EXPECT_EQ(second.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(OssAdapterConfigTest, LoadsPrimaryValuesAndNormalizesStrings) {
+    Set("MOONCAKE_OSS_ENDPOINT", "https://oss.example.com///");
+    Set("MOONCAKE_OSS_BUCKET", "primary-bucket");
+    Set("MOONCAKE_OSS_REGION", "primary-region");
+    Set("MOONCAKE_OSS_ACCESS_KEY_ID", "primary-id");
+    Set("MOONCAKE_OSS_ACCESS_KEY_SECRET", "primary-secret");
+    Set("MOONCAKE_OSS_SECURITY_TOKEN", "  primary-token\t");
+    Set("MOONCAKE_OSS_PATH_STYLE", "TRUE");
+    Set("MOONCAKE_OSS_ANONYMOUS", "On");
+
+    const auto config = OssAdapterConfig::FromEnvironment();
+
+    ASSERT_TRUE(config);
+    EXPECT_EQ(config->endpoint, "https://oss.example.com");
+    EXPECT_EQ(config->bucket, "primary-bucket");
+    EXPECT_EQ(config->region, "primary-region");
+    EXPECT_EQ(config->access_key_id, "primary-id");
+    EXPECT_EQ(config->access_key_secret, "primary-secret");
+    EXPECT_EQ(config->security_token, "primary-token");
+    EXPECT_TRUE(config->path_style);
+    EXPECT_TRUE(config->anonymous);
+}
+
+TEST_F(OssAdapterConfigTest, LoadsCompatibilityAliases) {
+    Set("OSS_ENDPOINT", "https://alias.example.com");
+    Set("OSS_BUCKET", "alias-bucket");
+    Set("OSS_REGION", "alias-region");
+    Set("OSS_ACCESS_KEY_ID", "alias-id");
+    Set("OSS_ACCESS_KEY_SECRET", "alias-secret");
+    Set("OSS_SESSION_TOKEN", "alias-token");
+
+    const auto config = OssAdapterConfig::FromEnvironment();
+
+    ASSERT_TRUE(config);
+    EXPECT_EQ(config->endpoint, "https://alias.example.com");
+    EXPECT_EQ(config->bucket, "alias-bucket");
+    EXPECT_EQ(config->region, "alias-region");
+    EXPECT_EQ(config->access_key_id, "alias-id");
+    EXPECT_EQ(config->access_key_secret, "alias-secret");
+    EXPECT_EQ(config->security_token, "alias-token");
+    EXPECT_FALSE(config->path_style);
+    EXPECT_FALSE(config->anonymous);
+}
+
+TEST_F(OssAdapterConfigTest, PresentPrimaryOverridesCompatibilityAlias) {
+    Set("OSS_ENDPOINT", "https://alias.example.com");
+    Set("MOONCAKE_OSS_ENDPOINT", "https://primary.example.com");
+    Set("OSS_BUCKET", "alias-bucket");
+    Set("MOONCAKE_OSS_BUCKET", "primary-bucket");
+    Set("OSS_REGION", "alias-region");
+    Set("MOONCAKE_OSS_REGION", "primary-region");
+    Set("OSS_ACCESS_KEY_ID", "alias-id");
+    Set("MOONCAKE_OSS_ACCESS_KEY_ID", "primary-id");
+    Set("OSS_ACCESS_KEY_SECRET", "alias-secret");
+    Set("MOONCAKE_OSS_ACCESS_KEY_SECRET", "primary-secret");
+    Set("OSS_SESSION_TOKEN", "alias-token");
+    Set("MOONCAKE_OSS_SECURITY_TOKEN", "");
+
+    const auto config = OssAdapterConfig::FromEnvironment();
+
+    ASSERT_TRUE(config);
+    EXPECT_EQ(config->endpoint, "https://primary.example.com");
+    EXPECT_EQ(config->bucket, "primary-bucket");
+    EXPECT_EQ(config->region, "primary-region");
+    EXPECT_EQ(config->access_key_id, "primary-id");
+    EXPECT_EQ(config->access_key_secret, "primary-secret");
+    EXPECT_TRUE(config->security_token.empty());
+}
+
+TEST_F(OssAdapterConfigTest, InvalidBoolValuesWarnAndUseFalse) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ACCESS_KEY_ID", "id");
+    Set("MOONCAKE_OSS_ACCESS_KEY_SECRET", "secret");
+    Set("MOONCAKE_OSS_PATH_STYLE", "invalid-path-style");
+    Set("MOONCAKE_OSS_ANONYMOUS", "invalid-anonymous");
+
+    testing::internal::CaptureStderr();
+    const auto config = OssAdapterConfig::FromEnvironment();
+    const std::string diagnostics = testing::internal::GetCapturedStderr();
+
+    ASSERT_TRUE(config);
+    EXPECT_FALSE(config->path_style);
+    EXPECT_FALSE(config->anonymous);
+    const size_t path_warning = diagnostics.find(
+        "invalid value 'invalid-path-style' for env "
+        "MOONCAKE_OSS_PATH_STYLE, using default 0");
+    const size_t anonymous_warning = diagnostics.find(
+        "invalid value 'invalid-anonymous' for env MOONCAKE_OSS_ANONYMOUS, "
+        "using default 0");
+    EXPECT_NE(path_warning, std::string::npos);
+    EXPECT_NE(anonymous_warning, std::string::npos);
+    EXPECT_LT(path_warning, anonymous_warning);
+}
+
+TEST_F(OssAdapterConfigTest, RejectsMissingRequiredValuesBeforeCredentials) {
+    Set("MOONCAKE_OSS_BUCKET", "bucket");
+    Set("MOONCAKE_OSS_REGION", "region");
+    Set("MOONCAKE_OSS_ACCESS_KEY_ID", "id");
+    Set("MOONCAKE_OSS_ACCESS_KEY_SECRET", "secret");
+
+    const auto config = OssAdapterConfig::FromEnvironment();
+
+    ASSERT_FALSE(config);
+    EXPECT_EQ(config.error(), ErrorCode::INVALID_PARAMS);
+}
+
+TEST_F(OssAdapterConfigTest, AllowsMissingCredentialsOnlyWhenAnonymous) {
+    SetRequiredPrimary();
+
+    const auto authenticated = OssAdapterConfig::FromEnvironment();
+    ASSERT_FALSE(authenticated);
+    EXPECT_EQ(authenticated.error(), ErrorCode::INVALID_PARAMS);
+
+    Set("MOONCAKE_OSS_ANONYMOUS", "yes");
+    const auto anonymous = OssAdapterConfig::FromEnvironment();
+    ASSERT_TRUE(anonymous);
+    EXPECT_TRUE(anonymous->anonymous);
+    EXPECT_TRUE(anonymous->access_key_id.empty());
+    EXPECT_TRUE(anonymous->access_key_secret.empty());
+}
+
+TEST_F(OssAdapterConfigTest, NewConfigsReadCurrentEnvironment) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    const auto first = OssAdapterConfig::FromEnvironment();
+
+    Set("MOONCAKE_OSS_ENDPOINT", "https://second.example.com");
+    const auto second = OssAdapterConfig::FromEnvironment();
+
+    ASSERT_TRUE(first);
+    ASSERT_TRUE(second);
+    EXPECT_EQ(first->endpoint, "https://oss.example.com");
+    EXPECT_EQ(second->endpoint, "https://second.example.com");
+}
+
+TEST_F(OssAdapterConfigTest, TuningDefaultsAndOverrides) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    const auto defaults = OssAdapterConfig::FromEnvironment();
+    ASSERT_TRUE(defaults);
+    EXPECT_EQ(defaults->max_connections, 64);
+    EXPECT_EQ(defaults->receive_buffer_size, 1024 * 1024);
+    EXPECT_EQ(defaults->upload_buffer_size, 1024 * 1024);
+
+    Set("MOONCAKE_OSS_MAX_CONNECTIONS", "128");
+    Set("MOONCAKE_OSS_RECEIVE_BUFFER_SIZE", "65536");
+    Set("MOONCAKE_OSS_UPLOAD_BUFFER_SIZE", "131072");
+    const auto configured = OssAdapterConfig::FromEnvironment();
+    ASSERT_TRUE(configured);
+    EXPECT_EQ(configured->max_connections, 128);
+    EXPECT_EQ(configured->receive_buffer_size, 65536);
+    EXPECT_EQ(configured->upload_buffer_size, 131072);
+}
+
+TEST_F(OssAdapterConfigTest, TuningValuesKeepExistingBounds) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    for (const char* value : {"-1", "0"}) {
+        SCOPED_TRACE(value);
+        Set("MOONCAKE_OSS_MAX_CONNECTIONS", value);
+        Set("MOONCAKE_OSS_RECEIVE_BUFFER_SIZE", value);
+        Set("MOONCAKE_OSS_UPLOAD_BUFFER_SIZE", value);
+        const auto config = OssAdapterConfig::FromEnvironment();
+        ASSERT_TRUE(config);
+        EXPECT_EQ(config->max_connections, 1);
+        EXPECT_EQ(config->receive_buffer_size, 16 * 1024);
+        EXPECT_EQ(config->upload_buffer_size, 16 * 1024);
+    }
+
+    Set("MOONCAKE_OSS_MAX_CONNECTIONS", "2147483647");
+    Set("MOONCAKE_OSS_RECEIVE_BUFFER_SIZE", "2147483647");
+    Set("MOONCAKE_OSS_UPLOAD_BUFFER_SIZE", "2147483647");
+    const auto config = OssAdapterConfig::FromEnvironment();
+    ASSERT_TRUE(config);
+    EXPECT_EQ(config->max_connections, 2147483647);
+    EXPECT_EQ(config->receive_buffer_size, 10 * 1024 * 1024);
+    EXPECT_EQ(config->upload_buffer_size, 2 * 1024 * 1024);
+}
+
+TEST_F(OssAdapterConfigTest, InvalidTuningValuesWarnAndUseDefaults) {
+    SetRequiredPrimary();
+    Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    for (const char* value :
+         {"invalid", "", "65536bytes", "2147483648", "-2147483649"}) {
+        SCOPED_TRACE(value);
+        Set("MOONCAKE_OSS_MAX_CONNECTIONS", value);
+        Set("MOONCAKE_OSS_RECEIVE_BUFFER_SIZE", value);
+        Set("MOONCAKE_OSS_UPLOAD_BUFFER_SIZE", value);
+        testing::internal::CaptureStderr();
+        const auto config = OssAdapterConfig::FromEnvironment();
+        const std::string diagnostics = testing::internal::GetCapturedStderr();
+        ASSERT_TRUE(config);
+        EXPECT_EQ(config->max_connections, 64);
+        EXPECT_EQ(config->receive_buffer_size, 1024 * 1024);
+        EXPECT_EQ(config->upload_buffer_size, 1024 * 1024);
+        EXPECT_NE(
+            diagnostics.find("MOONCAKE_OSS_MAX_CONNECTIONS, using default 64"),
+            std::string::npos);
+        EXPECT_NE(
+            diagnostics.find(
+                "MOONCAKE_OSS_RECEIVE_BUFFER_SIZE, using default 1048576"),
+            std::string::npos);
+        EXPECT_NE(diagnostics.find(
+                      "MOONCAKE_OSS_UPLOAD_BUFFER_SIZE, using default 1048576"),
+                  std::string::npos);
+    }
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/oss_adapter_test.cpp b/mooncake-store/tests/oss_adapter_test.cpp
new file mode 100644
index 0000000000..6c366773fa
--- /dev/null
+++ b/mooncake-store/tests/oss_adapter_test.cpp
@@ -0,0 +1,1614 @@
+#include <gtest/gtest.h>
+
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <poll.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <array>
+#include <cctype>
+#include <chrono>
+#include <cstdint>
+#include <cstdlib>
+#include <future>
+#include <limits>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "storage/distributed/distributed_storage_backend.h"
+#include "storage/distributed/oss_adapter.h"
+#include "storage_backend.h"
+#include "oss_fault_test_helpers.h"
+#include "oss_live_test_helpers.h"
+
+namespace mooncake {
+namespace {
+
+class ScopedEnvironment {
+   public:
+    ~ScopedEnvironment() {
+        for (const auto& [name, value] : original_values_) {
+            if (value) {
+                setenv(name.c_str(), value->c_str(), 1);
+            } else {
+                unsetenv(name.c_str());
+            }
+        }
+    }
+
+    void Set(const std::string& name, const std::string& value) {
+        if (!original_values_.contains(name)) {
+            const char* original = std::getenv(name.c_str());
+            original_values_[name] =
+                original ? std::optional<std::string>(original) : std::nullopt;
+        }
+        setenv(name.c_str(), value.c_str(), 1);
+    }
+
+   private:
+    std::map<std::string, std::optional<std::string>> original_values_;
+};
+
+class ObjectCleanup {
+   public:
+    explicit ObjectCleanup(OssObjectStorageAdapter& adapter)
+        : adapter_(adapter) {}
+
+    ~ObjectCleanup() {
+        for (const auto& key : keys_) adapter_.Delete(key);
+    }
+
+    void Add(std::string key) { keys_.push_back(std::move(key)); }
+
+   private:
+    OssObjectStorageAdapter& adapter_;
+    std::vector<std::string> keys_;
+};
+
+class ScriptedOssServer {
+   public:
+    struct Response {
+        long status;
+        std::string body;
+        std::string raw_response{};
+        bool keep_alive = false;
+        bool close_without_response = false;
+    };
+
+    explicit ScriptedOssServer(std::vector<Response> responses,
+                               bool defer_first_response = false)
+        : responses_(std::move(responses)),
+          defer_first_response_(defer_first_response) {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) throw std::runtime_error("socket failed");
+
+        int reuse = 1;
+        setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
+        sockaddr_in address{};
+        address.sin_family = AF_INET;
+        address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        address.sin_port = 0;
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&address),
+                 sizeof(address)) != 0) {
+            close(listen_fd_);
+            throw std::runtime_error("bind failed");
+        }
+        const int backlog =
+            static_cast<int>(std::max<size_t>(2, responses_.size()));
+        if (listen(listen_fd_, backlog) != 0) {
+            close(listen_fd_);
+            throw std::runtime_error("listen failed");
+        }
+        socklen_t address_size = sizeof(address);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&address),
+                        &address_size) != 0) {
+            close(listen_fd_);
+            throw std::runtime_error("getsockname failed");
+        }
+        port_ = ntohs(address.sin_port);
+        thread_ = std::thread([this] { Serve(); });
+    }
+
+    ~ScriptedOssServer() {
+        ReleaseFirstResponse();
+        Wait();
+    }
+
+    uint16_t port() const { return port_; }
+
+    void Wait() {
+        if (thread_.joinable()) thread_.join();
+        if (listen_fd_ >= 0) {
+            close(listen_fd_);
+            listen_fd_ = -1;
+        }
+    }
+
+    const std::vector<std::string>& requests() const { return requests_; }
+    const std::string& error() const { return error_; }
+
+    bool WaitForFirstRequest() {
+        return first_request_seen_.wait_for(std::chrono::seconds(5)) ==
+               std::future_status::ready;
+    }
+
+    void ReleaseFirstResponse() {
+        std::call_once(release_first_once_,
+                       [this] { release_first_.set_value(); });
+    }
+
+   private:
+    static bool SendAll(int fd, const std::string& data) {
+#if defined(MSG_NOSIGNAL)
+        constexpr int send_flags = MSG_NOSIGNAL;
+#else
+        constexpr int send_flags = 0;
+#endif
+        size_t offset = 0;
+        while (offset < data.size()) {
+            const ssize_t sent = send(fd, data.data() + offset,
+                                      data.size() - offset, send_flags);
+            if (sent <= 0) return false;
+            offset += static_cast<size_t>(sent);
+        }
+        return true;
+    }
+
+    static std::string ReadRequest(int fd) {
+        std::string request;
+        std::array<char, 4096> buffer{};
+        std::optional<size_t> request_size;
+        while (!request_size || request.size() < *request_size) {
+            pollfd descriptor{fd, POLLIN, 0};
+            if (poll(&descriptor, 1, 5000) <= 0) break;
+            const ssize_t received = recv(fd, buffer.data(), buffer.size(), 0);
+            if (received <= 0) break;
+            request.append(buffer.data(), static_cast<size_t>(received));
+            const size_t header_end = request.find("\r\n\r\n");
+            if (!request_size && header_end != std::string::npos) {
+                std::string headers = request.substr(0, header_end);
+                std::transform(headers.begin(), headers.end(), headers.begin(),
+                               [](unsigned char c) { return std::tolower(c); });
+                constexpr std::string_view content_length =
+                    "\r\ncontent-length:";
+                const size_t length_pos = headers.find(content_length);
+                const size_t body_size =
+                    length_pos == std::string::npos
+                        ? 0
+                        : std::stoull(headers.substr(length_pos +
+                                                     content_length.size()));
+                request_size = header_end + 4 + body_size;
+            }
+        }
+        return request;
+    }
+
+    void Serve() {
+        // Hold A's connection open while serving B. This makes the overlap
+        // test depend on request admission, not on timing or a fast server.
+        struct DeferredResponse {
+            int client = -1;
+            std::string data;
+            ~DeferredResponse() {
+                if (client >= 0) close(client);
+            }
+        } deferred;
+        struct Connection {
+            int fd = -1;
+            ~Connection() {
+                if (fd >= 0) close(fd);
+            }
+        } connection;
+        for (const auto& response : responses_) {
+            if (connection.fd < 0) {
+                pollfd descriptor{listen_fd_, POLLIN, 0};
+                if (poll(&descriptor, 1, 5000) <= 0) {
+                    error_ = "timed out waiting for OSS request";
+                    return;
+                }
+                connection.fd = accept(listen_fd_, nullptr, nullptr);
+                if (connection.fd < 0) {
+                    error_ = "accept failed";
+                    return;
+                }
+            }
+            const int client = connection.fd;
+            requests_.push_back(ReadRequest(client));
+            if (response.close_without_response) {
+                // Read the upload first so libcurl must rewind its source
+                // when it retries this reused connection on a fresh socket.
+                close(client);
+                connection.fd = -1;
+                continue;
+            }
+            std::string response_data = response.raw_response;
+            if (response_data.empty()) {
+                const std::string status_text =
+                    response.status == 204   ? "No Content"
+                    : response.status == 206 ? "Partial Content"
+                                             : "OK";
+                // A single-part 206 must identify its range. Unknown total size
+                // is valid; this scripted server only knows the selected body.
+                std::string content_range;
+                if (response.status == 206 && !response.body.empty()) {
+                    constexpr std::string_view range_header =
+                        "\r\nRange: bytes=";
+                    const auto start = requests_.back().find(range_header);
+                    const auto offset =
+                        start == std::string::npos
+                            ? 0ULL
+                            : std::stoull(requests_.back().substr(
+                                  start + range_header.size()));
+                    content_range =
+                        "Content-Range: bytes " + std::to_string(offset) + "-" +
+                        std::to_string(offset + response.body.size() - 1) +
+                        "/*\r\n";
+                }
+                response_data =
+                    "HTTP/1.1 " + std::to_string(response.status) + " " +
+                    status_text +
+                    "\r\nContent-Type: application/xml\r\n"
+                    "Content-Length: " +
+                    std::to_string(response.body.size()) +
+                    (response.keep_alive ? "\r\nConnection: keep-alive\r\n"
+                                         : "\r\nConnection: close\r\n") +
+                    content_range + "\r\n" + response.body;
+            }
+            if (defer_first_response_ && deferred.client < 0) {
+                deferred.client = client;
+                connection.fd = -1;
+                deferred.data = response_data;
+                first_request_.set_value();
+                continue;
+            }
+            if (!SendAll(client, response_data)) error_ = "send failed";
+            if (!response.keep_alive) {
+                close(client);
+                connection.fd = -1;
+            }
+            if (!error_.empty()) return;
+        }
+        if (deferred.client >= 0) {
+            if (first_response_released_.wait_for(std::chrono::seconds(5)) !=
+                std::future_status::ready) {
+                error_ = "timed out waiting to release the first response";
+            } else if (!SendAll(deferred.client, deferred.data)) {
+                error_ = "deferred send failed";
+            }
+        }
+    }
+
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    std::thread thread_;
+    std::vector<Response> responses_;
+    std::vector<std::string> requests_;
+    std::string error_;
+    bool defer_first_response_ = false;
+    std::promise<void> first_request_;
+    std::future<void> first_request_seen_{first_request_.get_future()};
+    std::promise<void> release_first_;
+    std::future<void> first_response_released_{release_first_.get_future()};
+    std::once_flag release_first_once_;
+};
+
+bool HasOssConfiguration() {
+    const auto has = [](const char* primary, const char* fallback = nullptr) {
+        const char* value = std::getenv(primary);
+        if ((!value || !*value) && fallback) value = std::getenv(fallback);
+        return value && *value;
+    };
+    if (!has("MOONCAKE_OSS_ENDPOINT", "OSS_ENDPOINT") ||
+        !has("MOONCAKE_OSS_BUCKET", "OSS_BUCKET") ||
+        !has("MOONCAKE_OSS_REGION", "OSS_REGION")) {
+        return false;
+    }
+    const char* anonymous = std::getenv("MOONCAKE_OSS_ANONYMOUS");
+    if (anonymous) {
+        std::string value(anonymous);
+        std::transform(value.begin(), value.end(), value.begin(),
+                       [](unsigned char c) { return std::tolower(c); });
+        if (value == "1" || value == "true" || value == "on" ||
+            value == "yes") {
+            return true;
+        }
+    }
+    return has("MOONCAKE_OSS_ACCESS_KEY_ID", "OSS_ACCESS_KEY_ID") &&
+           has("MOONCAKE_OSS_ACCESS_KEY_SECRET", "OSS_ACCESS_KEY_SECRET");
+}
+
+std::string UniquePrefix(const std::string& suffix) {
+    const auto now =
+        std::chrono::steady_clock::now().time_since_epoch().count();
+    return "/mooncake-oss-adapter-test/" + std::to_string(getpid()) + "-" +
+           std::to_string(now) + "-" + suffix;
+}
+
+void ConfigureFaultEndpoint(ScopedEnvironment& environment, uint16_t port) {
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(port));
+    environment.Set("MOONCAKE_OSS_BUCKET", "fault-bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "fault-region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "8");
+    // Never send inherited real credentials to even a loopback test server.
+    // ScopedEnvironment restores these process-local values at test teardown.
+    environment.Set("MOONCAKE_OSS_ACCESS_KEY_ID", "fault-test-id");
+    environment.Set("MOONCAKE_OSS_ACCESS_KEY_SECRET", "fault-test-secret");
+    environment.Set("MOONCAKE_OSS_SECURITY_TOKEN", "fault-test-token");
+    environment.Set("NO_PROXY", "127.0.0.1");
+    environment.Set("no_proxy", "127.0.0.1");
+}
+
+// Two slots, more requests than slots, and holes left by local validation.
+// The first network request stays pending while the other slot must drain
+// every later request, including failures. Only then release the first one.
+void CheckMixedGetBatch(bool timeout) {
+    using Server = test::OssFaultHttpServer;
+    Server server(
+        {{"waiting", timeout ? Server::Stall() : Server::Gate(206, "first")},
+         {"missing", Server::Reply(404, "")},
+         {"reset", Server::Reset()},
+         {"large-error", Server::Reply(404, std::string(512, 'x'))},
+         {"forbidden", Server::Reply(403, "deny")},
+         {"truncated", Server::Raw("HTTP/1.1 206 Test\r\nContent-Length: 5\r\n"
+                                   "Connection: close\r\n\r\nva")},
+         {"short", Server::Reply(206, "val")},
+         {"oversized", Server::Reply(206, "too-long")},
+         {"unavailable", Server::Reply(503, "busy!")},
+         {"tail", Server::Reply(206, "later")}},
+        true);
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "2");
+    OssObjectStorageAdapter adapter("/mixed-get/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<std::array<char, 7>, 13> buffers;
+    for (auto& buffer : buffers) buffer.fill('!');
+    const std::vector<ObjectGetRequest> requests{
+        {"invalid-first", nullptr, 5},
+        {"waiting", buffers[1].data() + 1, 5},
+        {"missing", buffers[2].data() + 1, 5},
+        {"empty", nullptr, 0},
+        {"reset", buffers[4].data() + 1, 5},
+        {"large-error", buffers[5].data() + 1, 5},
+        {"forbidden", buffers[6].data() + 1, 5},
+        {"truncated", buffers[7].data() + 1, 5},
+        {"short", buffers[8].data() + 1, 5},
+        {"oversized", buffers[9].data() + 1, 5},
+        {"unavailable", buffers[10].data() + 1, 5},
+        {"tail", buffers[11].data() + 1, 5},
+        {"invalid-last", nullptr, 1},
+    };
+    const auto started = std::chrono::steady_clock::now();
+    auto pending = std::async(std::launch::async,
+                              [&] { return adapter.GetBatch(requests); });
+    const bool tail_admitted = server.WaitForRequest("tail");
+    const auto before_release = pending.wait_for(std::chrono::seconds(0));
+    server.ReleaseResponses();
+    const auto results = pending.get();
+    if (timeout) {
+        const auto elapsed = std::chrono::steady_clock::now() - started;
+        EXPECT_GE(elapsed, std::chrono::seconds(110));
+        EXPECT_LT(elapsed, std::chrono::seconds(130));
+    }
+    EXPECT_TRUE(tail_admitted);
+    EXPECT_EQ(before_release, std::future_status::timeout);
+    ASSERT_EQ(results.size(), requests.size());
+    const std::array<std::optional<ErrorCode>, 13> errors{
+        ErrorCode::INVALID_PARAMS,
+        timeout ? std::optional(ErrorCode::DFS_SERVICE_UNAVAILABLE)
+                : std::nullopt,
+        ErrorCode::FILE_NOT_FOUND,
+        std::nullopt,
+        ErrorCode::DFS_SERVICE_UNAVAILABLE,
+        ErrorCode::FILE_NOT_FOUND,
+        ErrorCode::FILE_READ_FAIL,
+        ErrorCode::DFS_SERVICE_UNAVAILABLE,
+        ErrorCode::FILE_READ_FAIL,
+        ErrorCode::DFS_SERVICE_UNAVAILABLE,
+        ErrorCode::FILE_READ_FAIL,
+        std::nullopt,
+        ErrorCode::INVALID_PARAMS};
+    for (size_t i = 0; i < results.size(); ++i) {
+        SCOPED_TRACE(requests[i].logical_key);
+        EXPECT_EQ(results[i].has_value(), !errors[i].has_value());
+        if (errors[i] && !results[i]) EXPECT_EQ(results[i].error(), *errors[i]);
+        if (!errors[i] && results[i]) EXPECT_EQ(*results[i], requests[i].size);
+        EXPECT_EQ(buffers[i].front(), '!');
+        EXPECT_EQ(buffers[i].back(), '!');
+    }
+    if (!timeout) EXPECT_EQ(std::string(buffers[1].data() + 1, 5), "first");
+    EXPECT_EQ(std::string(buffers[11].data() + 1, 5), "later");
+    // Local invalid/zero-length reads must never reach HTTP. No request may
+    // be lost or accidentally submitted twice by the admission loop.
+    auto received = server.requests();
+    ASSERT_EQ(received.size(), 10U);
+    for (size_t i = 0; i < requests.size(); ++i) {
+        const auto count = std::count_if(
+            received.begin(), received.end(), [&](const auto& wire) {
+                return wire.find("/" + requests[i].logical_key + " HTTP/") !=
+                       std::string::npos;
+            });
+        EXPECT_EQ(count, i == 0 || i == 3 || i == 12 ? 0 : 1);
+    }
+    auto recovered = adapter.GetBatch({{"tail", buffers[0].data() + 1, 5}});
+    ASSERT_EQ(recovered.size(), 1U);
+    ASSERT_TRUE(recovered[0]);
+    EXPECT_EQ(std::string(buffers[0].data() + 1, 5), "later");
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+void CheckMixedPutBatch(bool timeout) {
+    using Server = test::OssFaultHttpServer;
+    Server server(
+        {{"waiting", timeout ? Server::Stall() : Server::Gate(200, "")},
+         {"missing", Server::Reply(404, "missing")},
+         {"reset", Server::Reset()},
+         {"forbidden", Server::Reply(403, "deny")},
+         {"unavailable", Server::Reply(503, "busy")},
+         {"empty", Server::Reply(200, "")},
+         {"tail", Server::Reply(200, "")}},
+        true);
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "2");
+    OssObjectStorageAdapter adapter("/mixed-put/");
+    ASSERT_TRUE(adapter.Init());
+    std::string left = "left", right = "right";
+    const iovec data[] = {
+        {left.data(), left.size()}, {nullptr, 0}, {right.data(), right.size()}};
+    const iovec invalid{nullptr, 1};
+    const iovec overflow[] = {{left.data(), std::numeric_limits<size_t>::max()},
+                              {right.data(), 1}};
+    const std::vector<ObjectPutRequest> requests{
+        {"negative-count", nullptr, -1},
+        {"waiting", data, 3},
+        {"missing", data, 3},
+        {"null-array", nullptr, 1},
+        {"reset", data, 3},
+        {"overflow", overflow, 2},
+        {"forbidden", data, 3},
+        {"bad-base", &invalid, 1},
+        {"unavailable", data, 3},
+        {"empty", nullptr, 0},
+        {"tail", data, 3},
+    };
+    const auto started = std::chrono::steady_clock::now();
+    auto pending = std::async(std::launch::async,
+                              [&] { return adapter.PutBatch(requests); });
+    const bool tail_admitted = server.WaitForRequest("tail");
+    const auto before_release = pending.wait_for(std::chrono::seconds(0));
+    server.ReleaseResponses();
+    const auto results = pending.get();
+    if (timeout) {
+        const auto elapsed = std::chrono::steady_clock::now() - started;
+        EXPECT_GE(elapsed, std::chrono::seconds(110));
+        EXPECT_LT(elapsed, std::chrono::seconds(130));
+    }
+    EXPECT_TRUE(tail_admitted);
+    EXPECT_EQ(before_release, std::future_status::timeout);
+    ASSERT_EQ(results.size(), requests.size());
+    const std::array<std::optional<ErrorCode>, 11> errors{
+        ErrorCode::INVALID_PARAMS,
+        timeout ? std::optional(ErrorCode::DFS_SERVICE_UNAVAILABLE)
+                : std::nullopt,
+        ErrorCode::FILE_WRITE_FAIL,
+        ErrorCode::INVALID_PARAMS,
+        ErrorCode::DFS_SERVICE_UNAVAILABLE,
+        ErrorCode::INVALID_PARAMS,
+        ErrorCode::FILE_WRITE_FAIL,
+        ErrorCode::INVALID_PARAMS,
+        ErrorCode::FILE_WRITE_FAIL,
+        std::nullopt,
+        std::nullopt};
+    for (size_t i = 0; i < results.size(); ++i) {
+        SCOPED_TRACE(requests[i].logical_key);
+        EXPECT_EQ(results[i].has_value(), !errors[i].has_value());
+        if (errors[i] && !results[i]) EXPECT_EQ(results[i].error(), *errors[i]);
+    }
+    const auto received = server.requests();
+    ASSERT_EQ(received.size(), 7U);
+    for (size_t i = 0; i < requests.size(); ++i) {
+        const auto count = std::count_if(
+            received.begin(), received.end(), [&](const auto& wire) {
+                return wire.find("/" + requests[i].logical_key + " HTTP/") !=
+                       std::string::npos;
+            });
+        EXPECT_EQ(count, i == 0 || i == 3 || i == 5 || i == 7 ? 0 : 1);
+    }
+    for (const auto& wire : received) {
+        EXPECT_EQ(wire.rfind("PUT ", 0), 0U);
+        const auto body_start = wire.find("\r\n\r\n");
+        ASSERT_NE(body_start, std::string::npos);
+        const bool empty = wire.find("/empty HTTP/") != std::string::npos;
+        EXPECT_EQ(wire.substr(body_start + 4), empty ? "" : left + right);
+    }
+    auto recovered = adapter.PutBatch({{"tail", data, 3}});
+    ASSERT_EQ(recovered.size(), 1U);
+    EXPECT_TRUE(recovered[0]);
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest, MixedGetBatchRefillsWhileFirstRequestWaits) {
+    CheckMixedGetBatch(false);
+}
+
+TEST(OssObjectStorageAdapterTest, MixedPutBatchRefillsWhileFirstRequestWaits) {
+    CheckMixedPutBatch(false);
+}
+
+TEST(OssObjectStorageAdapterTest, MixedGetBatchIsolatesRequestTimeout) {
+    const char* enabled = std::getenv("MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS");
+    if (!enabled || std::string_view(enabled) != "1")
+        GTEST_SKIP() << "Set MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS=1 for the "
+                        "production 120-second timeout regression";
+    CheckMixedGetBatch(true);
+}
+
+TEST(OssObjectStorageAdapterTest, MixedPutBatchIsolatesRequestTimeout) {
+    const char* enabled = std::getenv("MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS");
+    if (!enabled || std::string_view(enabled) != "1")
+        GTEST_SKIP() << "Set MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS=1 for the "
+                        "production 120-second timeout regression";
+    CheckMixedPutBatch(true);
+}
+
+TEST(OssObjectStorageAdapterTest, BatchConnectionLimitAppliesToGetAndPut) {
+    using Server = test::OssFaultHttpServer;
+    for (bool upload : {false, true}) {
+        for (int limit : {1, 2, 4}) {
+            SCOPED_TRACE(upload ? "PUT" : "GET");
+            SCOPED_TRACE(limit);
+            constexpr size_t count = 6;
+            std::map<std::string, Server::Response> routes;
+            std::vector<ObjectGetRequest> gets;
+            std::vector<ObjectPutRequest> puts;
+            std::array<char, count> buffers{};
+            char payload = 'x';
+            const iovec iov{&payload, 1};
+            for (size_t i = 0; i < count; ++i) {
+                const auto key = std::to_string(i);
+                routes.emplace(
+                    key, Server::Gate(upload ? 200 : 206, upload ? "" : "x"));
+                gets.push_back({key, &buffers[i], 1});
+                puts.push_back({key, &iov, 1});
+            }
+            Server server(std::move(routes), true);
+            ScopedEnvironment environment;
+            ConfigureFaultEndpoint(environment, server.port());
+            environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS",
+                            std::to_string(limit));
+            OssObjectStorageAdapter adapter("/connection-limit/");
+            ASSERT_TRUE(adapter.Init());
+            auto pending = std::async(std::launch::async, [&] {
+                if (upload) {
+                    const auto results = adapter.PutBatch(puts);
+                    return results.size() == count &&
+                           std::all_of(results.begin(), results.end(),
+                                       [](const auto& r) { return bool(r); });
+                }
+                const auto results = adapter.GetBatch(gets);
+                return results.size() == count &&
+                       std::all_of(results.begin(), results.end(),
+                                   [](const auto& r) { return r && *r == 1; });
+            });
+            const bool window_full =
+                server.WaitForRequest(std::to_string(limit - 1));
+            // All admitted requests are gated: no slot can finish yet.
+            const bool exceeded = server.WaitForRequest(
+                std::to_string(limit), std::chrono::milliseconds(200));
+            const auto admitted = server.requests().size();
+            server.ReleaseResponses();
+            const bool succeeded = pending.get();
+            EXPECT_TRUE(window_full);
+            EXPECT_FALSE(exceeded);
+            EXPECT_EQ(admitted, static_cast<size_t>(limit));
+            EXPECT_TRUE(succeeded);
+            if (!upload)
+                for (char value : buffers) EXPECT_EQ(value, 'x');
+            server.Stop();
+            EXPECT_EQ(server.requests().size(), count);
+            EXPECT_TRUE(server.error().empty()) << server.error();
+        }
+    }
+}
+
+TEST(OssObjectStorageAdapterTest,
+     FaultResetAndPartialHeaderFailThenSameAdapterRecovers) {
+    using Server = test::OssFaultHttpServer;
+    Server server(
+        {{"reset", Server::Reset()},
+         {"partial-header",
+          Server::Raw("HTTP/1.1 206 Partial Content\r\nContent-Len")},
+         {"healthy",
+          Server::Reply(206, "value", "Content-Range: bytes 0-4/5\r\n")}});
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    for (const char* key : {"reset", "partial-header"}) {
+        SCOPED_TRACE(key);
+        std::array<char, 7> output;
+        output.fill('!');
+        auto failed = adapter.Get(key, output.data() + 1, 5);
+        EXPECT_FALSE(failed);
+        if (!failed) {
+            if (std::string_view(key) == "reset") {
+                EXPECT_EQ(failed.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+            } else {
+                // libcurl may report a transport error or let the adapter
+                // reject the incomplete response. Neither is a valid read.
+                EXPECT_TRUE(failed.error() ==
+                                ErrorCode::DFS_SERVICE_UNAVAILABLE ||
+                            failed.error() == ErrorCode::FILE_READ_FAIL);
+            }
+        }
+        EXPECT_EQ(output.front(), '!');
+        EXPECT_EQ(output.back(), '!');
+        auto recovered = adapter.Get("healthy", output.data() + 1, 5);
+        ASSERT_TRUE(recovered);
+        EXPECT_EQ(*recovered, 5U);
+        EXPECT_EQ(std::string(output.data() + 1, 5), "value");
+        EXPECT_EQ(output.front(), '!');
+        EXPECT_EQ(output.back(), '!');
+    }
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest,
+     FaultTruncatedBodyFailsThenSameAdapterRecovers) {
+    using Server = test::OssFaultHttpServer;
+    Server server({
+        {"truncated",
+         Server::Raw(
+             "HTTP/1.1 206 Partial Content\r\nContent-Length: 5\r\n"
+             "Content-Range: bytes 0-4/5\r\nConnection: close\r\n\r\nva")},
+        {"healthy",
+         Server::Reply(206, "value", "Content-Range: bytes 0-4/5\r\n")},
+    });
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 7> output;
+    output.fill('!');
+    auto failed = adapter.Get("truncated", output.data() + 1, 5);
+    EXPECT_FALSE(failed);
+    if (!failed) {
+        EXPECT_EQ(failed.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    EXPECT_EQ(output.front(), '!');
+    EXPECT_EQ(output.back(), '!');
+    auto recovered = adapter.Get("healthy", output.data() + 1, 5);
+    ASSERT_TRUE(recovered);
+    EXPECT_EQ(*recovered, 5U);
+    EXPECT_EQ(std::string(output.data() + 1, 5), "value");
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest,
+     FaultRangeShortReadAndHttpErrorAreRejectedThenRecovers) {
+    using Server = test::OssFaultHttpServer;
+    Server server({
+        {"clipped-range",
+         Server::Reply(206, "end", "Content-Range: bytes 5-7/8\r\n")},
+        {"unsatisfiable-range", Server::Reply(416, "")},
+        {"healthy",
+         Server::Reply(206, "later", "Content-Range: bytes 5-9/10\r\n")},
+    });
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    for (const char* key : {"clipped-range", "unsatisfiable-range"}) {
+        SCOPED_TRACE(key);
+        std::array<char, 7> output;
+        output.fill('!');
+        // Reject short reads and HTTP errors using status and actual length.
+        auto failed = adapter.GetRange(key, output.data() + 1, 5, 5);
+        EXPECT_FALSE(failed);
+        if (!failed) {
+            EXPECT_EQ(failed.error(), ErrorCode::FILE_READ_FAIL);
+        }
+        EXPECT_EQ(output.front(), '!');
+        EXPECT_EQ(output.back(), '!');
+        auto recovered = adapter.GetRange("healthy", output.data() + 1, 5, 5);
+        ASSERT_TRUE(recovered);
+        EXPECT_EQ(*recovered, 5U);
+        EXPECT_EQ(std::string(output.data() + 1, 5), "later");
+    }
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+    for (const auto& request : server.requests()) {
+        EXPECT_NE(request.find("Range: bytes=5-9"), std::string::npos);
+    }
+}
+
+TEST(OssObjectStorageAdapterTest,
+     FaultShortReadAndHttpErrorAreRejectedByDirectAndBatchGet) {
+    using Server = test::OssFaultHttpServer;
+    Server server({
+        {"short-200", Server::Reply(200, "val")},
+        {"clipped-range",
+         Server::Reply(206, "val", "Content-Range: bytes 0-2/3\r\n")},
+        {"unsatisfiable-range", Server::Reply(416, "error")},
+        {"full-200", Server::Reply(200, "value")},
+        {"full-206", Server::Reply(206, "value")},
+    });
+    const std::array<const char*, 5> keys{"short-200", "clipped-range",
+                                          "unsatisfiable-range", "full-200",
+                                          "full-206"};
+    constexpr size_t invalid_count = 4;
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::vector<std::array<char, 7>> buffers(keys.size());
+    std::vector<ObjectGetRequest> requests;
+    for (size_t i = 0; i < keys.size(); ++i) {
+        SCOPED_TRACE(keys[i]);
+        buffers[i].fill('!');
+        auto result = adapter.Get(keys[i], buffers[i].data() + 1, 5);
+        if (i < invalid_count) {
+            EXPECT_FALSE(result);
+            if (!result) {
+                EXPECT_EQ(result.error(), ErrorCode::FILE_READ_FAIL);
+            }
+        } else {
+            ASSERT_TRUE(result);
+            EXPECT_EQ(*result, 5U);
+            EXPECT_EQ(std::string(buffers[i].data() + 1, 5), "value");
+        }
+        EXPECT_EQ(buffers[i].front(), '!');
+        EXPECT_EQ(buffers[i].back(), '!');
+        buffers[i].fill('!');
+        requests.push_back({keys[i], buffers[i].data() + 1, 5});
+    }
+    // Check status and actual length in both paths. The 200 and 416 bodies
+    // have the expected length but are not valid range responses.
+    auto results = adapter.GetBatch(requests);
+    ASSERT_EQ(results.size(), keys.size());
+    for (size_t i = 0; i < results.size(); ++i) {
+        SCOPED_TRACE(keys[i]);
+        if (i < invalid_count) {
+            EXPECT_FALSE(results[i]);
+            if (!results[i]) {
+                EXPECT_EQ(results[i].error(), ErrorCode::FILE_READ_FAIL);
+            }
+        } else {
+            ASSERT_TRUE(results[i]);
+            EXPECT_EQ(*results[i], 5U);
+            EXPECT_EQ(std::string(buffers[i].data() + 1, 5), "value");
+        }
+        EXPECT_EQ(buffers[i].front(), '!');
+        EXPECT_EQ(buffers[i].back(), '!');
+    }
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest,
+     ConcurrentSyncBatchesDoNotWaitForSharedMultiHandle) {
+    ScriptedOssServer server({{206, "first"}, {206, "later"}}, true);
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    // The limit is per batch, not per adapter: the first batch consumes its
+    // only connection while the second batch must still make progress.
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "1");
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 7> first_buffer, later_buffer;
+    first_buffer.fill('!');
+    later_buffer.fill('!');
+    auto first = std::async(std::launch::async, [&] {
+        return adapter.GetBatch({{"first", first_buffer.data() + 1, 5}});
+    });
+    const bool first_received = server.WaitForFirstRequest();
+    auto later = std::async(std::launch::async, [&] {
+        return adapter.GetBatch({{"later", later_buffer.data() + 1, 5}});
+    });
+    const auto later_status = later.wait_for(std::chrono::seconds(2));
+    const auto first_before_release = first.wait_for(std::chrono::seconds(0));
+    // Always release and join before asserting. Wait() also closes the
+    // listener after its bounded accept timeout, so the old serialized
+    // implementation fails this regression without waiting for a 120 s GET.
+    server.ReleaseFirstResponse();
+    server.Wait();
+    auto first_result = first.get();
+    auto later_result = later.get();
+    ASSERT_TRUE(first_received);
+    ASSERT_EQ(later_status, std::future_status::ready);
+    EXPECT_EQ(first_before_release, std::future_status::timeout);
+    ASSERT_EQ(first_result.size(), 1U);
+    ASSERT_EQ(later_result.size(), 1U);
+    ASSERT_TRUE(first_result[0]);
+    ASSERT_TRUE(later_result[0]);
+    EXPECT_EQ(*first_result[0], 5U);
+    EXPECT_EQ(*later_result[0], 5U);
+    EXPECT_EQ(std::string(first_buffer.data() + 1, 5), "first");
+    EXPECT_EQ(std::string(later_buffer.data() + 1, 5), "later");
+    EXPECT_EQ(first_buffer.front(), '!');
+    EXPECT_EQ(first_buffer.back(), '!');
+    EXPECT_EQ(later_buffer.front(), '!');
+    EXPECT_EQ(later_buffer.back(), '!');
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest,
+     FaultBatchErrorsRemainIsolatedAndNextBatchRecovers) {
+    using Server = test::OssFaultHttpServer;
+    Server server({
+        {"healthy",
+         Server::Reply(206, "value", "Content-Range: bytes 0-4/5\r\n")},
+        {"reset", Server::Reset()},
+        {"truncated",
+         Server::Raw(
+             "HTTP/1.1 206 Partial Content\r\nContent-Length: 5\r\n"
+             "Content-Range: bytes 0-4/5\r\nConnection: close\r\n\r\nva")},
+        {"forbidden", Server::Reply(403, "deny")},
+        {"unavailable", Server::Reply(503, "busy!")},
+        {"recovery-a",
+         Server::Reply(206, "after", "Content-Range: bytes 0-4/5\r\n")},
+        {"recovery-b",
+         Server::Reply(206, "again", "Content-Range: bytes 0-4/5\r\n")},
+    });
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<std::array<char, 7>, 5> output;
+    for (auto& buffer : output) buffer.fill('!');
+    const std::array<const char*, 5> keys{"healthy", "reset", "truncated",
+                                          "forbidden", "unavailable"};
+    std::vector<ObjectGetRequest> requests;
+    for (size_t i = 0; i < keys.size(); ++i)
+        requests.push_back({keys[i], output[i].data() + 1, 5});
+    auto results = adapter.GetBatch(requests);
+    ASSERT_EQ(results.size(), requests.size());
+    ASSERT_TRUE(results[0]);
+    EXPECT_EQ(*results[0], 5U);
+    EXPECT_EQ(std::string(output[0].data() + 1, 5), "value");
+    for (size_t i = 1; i < keys.size(); ++i) {
+        SCOPED_TRACE(keys[i]);
+        EXPECT_FALSE(results[i]);
+        if (!results[i]) {
+            EXPECT_EQ(results[i].error(),
+                      i < 3 ? ErrorCode::DFS_SERVICE_UNAVAILABLE
+                            : ErrorCode::FILE_READ_FAIL);
+        }
+    }
+    for (const auto& buffer : output) {
+        EXPECT_EQ(buffer.front(), '!');
+        EXPECT_EQ(buffer.back(), '!');
+    }
+    auto recovered =
+        adapter.GetBatch({{"recovery-a", output[0].data() + 1, 5},
+                          {"recovery-b", output[1].data() + 1, 5}});
+    ASSERT_EQ(recovered.size(), 2U);
+    ASSERT_TRUE(recovered[0]);
+    ASSERT_TRUE(recovered[1]);
+    EXPECT_EQ(std::string(output[0].data() + 1, 5), "after");
+    EXPECT_EQ(std::string(output[1].data() + 1, 5), "again");
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest, FaultBatchPutFailureDoesNotPoisonNextUpload) {
+    using Server = test::OssFaultHttpServer;
+    Server server({{"healthy", Server::Reply(200, "")},
+                   {"unavailable", Server::Reply(503, "busy")},
+                   {"reset", Server::Reset()},
+                   {"recovered", Server::Reply(200, "")}});
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::string payload(16 * 1024, 'p');
+    const iovec source{payload.data(), payload.size()};
+    auto results = adapter.PutBatch({{"healthy", &source, 1},
+                                     {"unavailable", &source, 1},
+                                     {"reset", &source, 1}});
+    ASSERT_EQ(results.size(), 3U);
+    EXPECT_TRUE(results[0]);
+    EXPECT_FALSE(results[1]);
+    EXPECT_FALSE(results[2]);
+    if (!results[1]) {
+        EXPECT_EQ(results[1].error(), ErrorCode::FILE_WRITE_FAIL);
+    }
+    if (!results[2]) {
+        EXPECT_EQ(results[2].error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    auto recovered = adapter.PutBatch({{"recovered", &source, 1}});
+    ASSERT_EQ(recovered.size(), 1U);
+    EXPECT_TRUE(recovered[0]);
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+    for (const auto& request : server.requests()) {
+        EXPECT_EQ(request.rfind("PUT ", 0), 0U);
+        const auto body = request.find("\r\n\r\n");
+        ASSERT_NE(body, std::string::npos);
+        EXPECT_EQ(request.substr(body + 4), payload);
+    }
+}
+
+TEST(OssObjectStorageAdapterTest,
+     BatchReusedConnectionPutRewindsIovecsForCurlRetry) {
+    ScriptedOssServer server({
+        {200, "", "", true},
+        {0, "", "", false, true},
+        {200, ""},
+    });
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "1");
+    OssObjectStorageAdapter adapter("/retry-test/");
+    ASSERT_TRUE(adapter.Init());
+
+    std::string left(20 * 1024, 'a');
+    std::string right(12 * 1024, 'b');
+    const iovec source[] = {
+        {left.data(), left.size()}, {nullptr, 0}, {right.data(), right.size()}};
+    // Within one batch, reuse the warmup connection, then drop the upload
+    // response. libcurl must rewind the iovecs before retrying the PUT.
+    auto results =
+        adapter.PutBatch({{"warmup", nullptr, 0}, {"payload", source, 3}});
+    ASSERT_EQ(results.size(), 2U);
+    EXPECT_TRUE(results[0]);
+    EXPECT_TRUE(results[1]);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+    ASSERT_EQ(server.requests().size(), 3U);
+    EXPECT_EQ(server.requests()[0].rfind(
+                  "PUT /fault-bucket/retry-test/warmup HTTP/", 0),
+              0U);
+    for (size_t i = 1; i < server.requests().size(); ++i) {
+        const auto& received = server.requests()[i];
+        EXPECT_EQ(
+            received.rfind("PUT /fault-bucket/retry-test/payload HTTP/", 0),
+            0U);
+        const auto body = received.find("\r\n\r\n");
+        ASSERT_NE(body, std::string::npos);
+        EXPECT_EQ(received.substr(body + 4), left + right);
+    }
+}
+
+TEST(OssObjectStorageAdapterTest, FaultRequestTimeoutThenSameAdapterRecovers) {
+    const char* enabled = std::getenv("MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS");
+    if (!enabled || std::string_view(enabled) != "1") {
+        GTEST_SKIP() << "Set MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS=1 for the "
+                        "production 120-second timeout regression";
+    }
+    // Slow by design: the current production request timeout is 120 s and is
+    // not configurable. Run this test with an outer timeout greater than 130 s.
+    using Server = test::OssFaultHttpServer;
+    Server server(
+        {{"stall", Server::Stall()},
+         {"healthy",
+          Server::Reply(206, "value", "Content-Range: bytes 0-4/5\r\n")}});
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 7> output;
+    output.fill('!');
+    const auto started = std::chrono::steady_clock::now();
+    auto failed = adapter.Get("stall", output.data() + 1, 5);
+    const auto elapsed = std::chrono::steady_clock::now() - started;
+    EXPECT_FALSE(failed);
+    if (!failed) {
+        EXPECT_EQ(failed.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    }
+    EXPECT_GE(elapsed, std::chrono::seconds(110));
+    EXPECT_LT(elapsed, std::chrono::seconds(130));
+    auto recovered = adapter.Get("healthy", output.data() + 1, 5);
+    ASSERT_TRUE(recovered);
+    EXPECT_EQ(*recovered, 5U);
+    EXPECT_EQ(std::string(output.data() + 1, 5), "value");
+    EXPECT_EQ(output.front(), '!');
+    EXPECT_EQ(output.back(), '!');
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest, BatchQueueDoesNotConsumeRequestTimeout) {
+    const char* enabled = std::getenv("MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS");
+    if (!enabled || std::string_view(enabled) != "1") {
+        GTEST_SKIP() << "Set MOONCAKE_RUN_OSS_FAULT_TIMEOUT_TESTS=1 for the "
+                        "production 120-second timeout regression";
+    }
+    using Server = test::OssFaultHttpServer;
+    Server server(
+        {{"stall", Server::Stall()}, {"healthy", Server::Reply(206, "value")}});
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "1");
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 5> stalled{};
+    std::array<char, 5> healthy{};
+    // The second request waits for the first one's full 120-second timeout.
+    // Its own timeout must begin on admission, not while waiting for a slot.
+    auto results =
+        adapter.GetBatch({{"stall", stalled.data(), stalled.size()},
+                          {"healthy", healthy.data(), healthy.size()}});
+    ASSERT_EQ(results.size(), 2U);
+    ASSERT_FALSE(results[0]);
+    EXPECT_EQ(results[0].error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    ASSERT_TRUE(results[1]);
+    EXPECT_EQ(*results[1], healthy.size());
+    EXPECT_EQ(std::string(healthy.data(), healthy.size()), "value");
+    server.Stop();
+    EXPECT_TRUE(server.error().empty()) << server.error();
+    EXPECT_EQ(server.requests().size(), 2U);
+}
+
+TEST(OssObjectStorageAdapterTest, ValidatesVectorAndRangeArguments) {
+    OssObjectStorageAdapter adapter("/test-prefix");
+
+    auto invalid_count = adapter.PutV("key", nullptr, -1);
+    ASSERT_FALSE(invalid_count);
+    EXPECT_EQ(invalid_count.error(), ErrorCode::INVALID_PARAMS);
+
+    iovec invalid_iov{nullptr, 1};
+    auto invalid_buffer = adapter.PutV("key", &invalid_iov, 1);
+    ASSERT_FALSE(invalid_buffer);
+    EXPECT_EQ(invalid_buffer.error(), ErrorCode::INVALID_PARAMS);
+
+    char value = '\0';
+    std::array<iovec, 2> overflowing_iov{
+        {{&value, std::numeric_limits<size_t>::max()}, {&value, 1}}};
+    auto overflow = adapter.PutV("key", overflowing_iov.data(), 2);
+    ASSERT_FALSE(overflow);
+    EXPECT_EQ(overflow.error(), ErrorCode::INVALID_PARAMS);
+
+    auto invalid_offset = adapter.GetRange("key", nullptr, 1, -1);
+    ASSERT_FALSE(invalid_offset);
+    EXPECT_EQ(invalid_offset.error(), ErrorCode::INVALID_PARAMS);
+
+    auto invalid_batch =
+        adapter.PutBatch({{"negative-count", nullptr, -1},
+                          {"null-array", nullptr, 1},
+                          {"bad-pointer", &invalid_iov, 1},
+                          {"overflow", overflowing_iov.data(), 2}});
+    ASSERT_EQ(invalid_batch.size(), 4U);
+    for (const auto& result : invalid_batch) {
+        ASSERT_FALSE(result);
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+}
+
+TEST(OssObjectStorageAdapterTest, RejectsIgnoredRangeResponse) {
+    ScriptedOssServer server({
+        {200, "abcd", ""},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 4> buffer{};
+    auto result = adapter.GetRange("key", buffer.data(), buffer.size(), 2);
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::FILE_READ_FAIL);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+
+    ASSERT_EQ(server.requests().size(), 1U);
+    EXPECT_NE(server.requests()[0].find("Range: bytes=2-5"), std::string::npos);
+    EXPECT_NE(server.requests()[0].find("x-oss-range-behavior: standard"),
+              std::string::npos);
+}
+
+TEST(OssObjectStorageAdapterTest,
+     BatchRejectsIgnoredRangeResponseThenRecovers) {
+    ScriptedOssServer server({{200, "abcd"}, {206, "efgh"}, {206, "ijkl"}});
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "1");
+    OssObjectStorageAdapter adapter("/fault-test/");
+    ASSERT_TRUE(adapter.Init());
+
+    std::array<char, 4> ignored{};
+    std::array<char, 4> healthy{};
+    auto results =
+        adapter.GetBatch({{"ignored", ignored.data(), ignored.size()},
+                          {"healthy", healthy.data(), healthy.size()}});
+    ASSERT_EQ(results.size(), 2U);
+    ASSERT_FALSE(results[0]);
+    EXPECT_EQ(results[0].error(), ErrorCode::FILE_READ_FAIL);
+    ASSERT_TRUE(results[1]);
+    EXPECT_EQ(*results[1], healthy.size());
+    EXPECT_EQ(std::string(healthy.data(), healthy.size()), "efgh");
+
+    auto recovered =
+        adapter.GetBatch({{"recovered", healthy.data(), healthy.size()}});
+    ASSERT_EQ(recovered.size(), 1U);
+    ASSERT_TRUE(recovered[0]);
+    EXPECT_EQ(*recovered[0], healthy.size());
+    EXPECT_EQ(std::string(healthy.data(), healthy.size()), "ijkl");
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+    ASSERT_EQ(server.requests().size(), 3U);
+    for (const auto& request : server.requests()) {
+        EXPECT_NE(request.find("Range: bytes=0-3"), std::string::npos);
+        EXPECT_NE(request.find("x-oss-range-behavior: standard"),
+                  std::string::npos);
+    }
+}
+
+TEST(OssObjectStorageAdapterTest, ClearsHeadersAtResponseBoundaries) {
+    ScriptedOssServer server({
+        {200, "",
+         "HTTP/1.1 103 Early Hints\r\n"
+         "Content-Length: 123\r\n\r\n"
+         "HTTP/1.1 200 OK\r\n"
+         "Connection: close\r\n\r\n"},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    auto result = adapter.GetSize("key");
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::FILE_READ_FAIL);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest, IgnoresDfsOnlyConfiguration) {
+    DistributedStorageConfig config;
+    config.fsdir = "/object-prefix";
+    config.fs_adapter_type = "oss";
+    config.shard_count = 0;
+    config.shard_capacity = 0;
+    config.alignment = 0;
+    config.single_tenant = false;
+
+    EXPECT_TRUE(config.Validate());
+    EXPECT_FALSE(config.ValidateForAllocator());
+}
+
+TEST(OssObjectStorageAdapterTest, DecodesPaginatedLogicalKeys) {
+    ScriptedOssServer server({
+        {200,
+         "<ListBucketResult>"
+         "<EncodingType>url</EncodingType>"
+         "<IsTruncated>true</IsTruncated>"
+         "<Contents><Key>test-prefix%2Falpha%252Fbeta</Key>"
+         "<Size>3</Size></Contents>"
+         "<NextContinuationToken>next%2Btoken</NextContinuationToken>"
+         "</ListBucketResult>"},
+        {200,
+         "<ListBucketResult>"
+         "<EncodingType>url</EncodingType>"
+         "<IsTruncated>false</IsTruncated>"
+         "<Contents><Key>test-prefix%2Fpercent%2525value</Key>"
+         "<Size>5</Size></Contents>"
+         "</ListBucketResult>"},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    auto keys = adapter.ListKeys();
+    ASSERT_TRUE(keys);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+
+    ASSERT_EQ(keys->size(), 2U);
+    EXPECT_EQ((*keys)[0].logical_key, "alpha/beta");
+    EXPECT_EQ((*keys)[0].size, 3U);
+    EXPECT_EQ((*keys)[1].logical_key, "percent%value");
+    EXPECT_EQ((*keys)[1].size, 5U);
+    ASSERT_EQ(server.requests().size(), 2U);
+    EXPECT_NE(server.requests()[0].find("prefix=test-prefix%2F"),
+              std::string::npos);
+    EXPECT_NE(server.requests()[1].find("continuation-token=next%2Btoken"),
+              std::string::npos);
+}
+
+TEST(OssObjectStorageAdapterTest, HealthCheckWritesReadsAndDeletesProbe) {
+    ScriptedOssServer server({
+        {200, ""},
+        {206, "health_check"},
+        {204, ""},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    ASSERT_TRUE(adapter.CheckHealth());
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+
+    ASSERT_EQ(server.requests().size(), 3U);
+    EXPECT_EQ(server.requests()[0].rfind("PUT ", 0), 0U);
+    EXPECT_EQ(server.requests()[1].rfind("GET ", 0), 0U);
+    EXPECT_EQ(server.requests()[2].rfind("DELETE ", 0), 0U);
+    EXPECT_NE(server.requests()[0].find(
+                  "/bucket/test-prefix/.mooncake_health_probe_"),
+              std::string::npos);
+    EXPECT_NE(server.requests()[1].find("Range: bytes=0-11"),
+              std::string::npos);
+}
+
+TEST(OssObjectStorageAdapterTest, HealthCheckCleansUpAfterReadMismatch) {
+    ScriptedOssServer server({
+        {200, ""},
+        {206, "wrong_health"},
+        {204, ""},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    auto result = adapter.CheckHealth();
+    ASSERT_FALSE(result);
+    EXPECT_EQ(result.error(), ErrorCode::DFS_SERVICE_UNAVAILABLE);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+
+    ASSERT_EQ(server.requests().size(), 3U);
+    EXPECT_EQ(server.requests()[2].rfind("DELETE ", 0), 0U);
+}
+
+TEST(OssObjectStorageAdapterTest,
+     DirectGetPreservesNotFoundWithOversizedErrorBody) {
+    ScriptedOssServer server({
+        {404,
+         "<Error><Code>NoSuchKey</Code>" + std::string(512, 'x') + "</Error>"},
+        {206, "value"},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<char, 7> buffer{'!', '\0', '\0', '\0', '\0', '\0', '!'};
+    auto missing = adapter.Get("missing", buffer.data() + 1, 5);
+    ASSERT_FALSE(missing);
+    EXPECT_EQ(missing.error(), ErrorCode::FILE_NOT_FOUND);
+    EXPECT_EQ(buffer.front(), '!');
+    EXPECT_EQ(buffer.back(), '!');
+
+    // A failed request must not prevent subsequent reads on the same adapter.
+    auto present = adapter.Get("present", buffer.data() + 1, 5);
+    ASSERT_TRUE(present);
+    EXPECT_EQ(*present, 5U);
+    EXPECT_EQ(std::string(buffer.data() + 1, 5), "value");
+    EXPECT_EQ(buffer.front(), '!');
+    EXPECT_EQ(buffer.back(), '!');
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+}
+
+TEST(OssObjectStorageAdapterTest,
+     GetRangeAndBatchDistinguishNotFoundFromTransferFailures) {
+    using Server = test::OssFaultHttpServer;
+    Server server({{"missing", Server::Reply(404, std::string(512, 'x'))},
+                   {"truncated-error",
+                    Server::Raw("HTTP/1.1 404 Test\r\nContent-Length: 5\r\n"
+                                "Connection: close\r\n\r\nxx")},
+                   {"large-error", Server::Reply(503, std::string(512, 'x'))},
+                   {"oversized", Server::Reply(206, "too-long")},
+                   {"present", Server::Reply(206, "value")}},
+                  true);
+    ScopedEnvironment environment;
+    ConfigureFaultEndpoint(environment, server.port());
+    OssObjectStorageAdapter adapter("/get-error-mapping/");
+    ASSERT_TRUE(adapter.Init());
+    const std::vector<std::pair<std::string, ErrorCode>> cases{
+        {"missing", ErrorCode::FILE_NOT_FOUND},
+        {"truncated-error", ErrorCode::DFS_SERVICE_UNAVAILABLE},
+        {"large-error", ErrorCode::DFS_SERVICE_UNAVAILABLE},
+        {"oversized", ErrorCode::DFS_SERVICE_UNAVAILABLE}};
+    for (const auto& [key, error] : cases) {
+        SCOPED_TRACE(key);
+        std::array<char, 7> buffer;
+        buffer.fill('!');
+        const auto single = adapter.GetRange(key, buffer.data() + 1, 5, 1);
+        ASSERT_FALSE(single);
+        EXPECT_EQ(single.error(), error);
+        const auto batch = adapter.GetBatch({{key, buffer.data() + 1, 5}});
+        ASSERT_EQ(batch.size(), 1U);
+        ASSERT_FALSE(batch[0]);
+        EXPECT_EQ(batch[0].error(), error);
+        EXPECT_EQ(buffer.front(), '!');
+        EXPECT_EQ(buffer.back(), '!');
+    }
+    std::array<char, 5> buffer;
+    const auto recovered = adapter.GetBatch({{"present", buffer.data(), 5}});
+    ASSERT_EQ(recovered.size(), 1U);
+    ASSERT_TRUE(recovered[0]);
+    EXPECT_EQ(*recovered[0], buffer.size());
+    EXPECT_EQ(std::string(buffer.data(), buffer.size()), "value");
+}
+
+TEST(OssObjectStorageAdapterTest,
+     BatchGetPreservesRequestOrderAndReportsPartialFailures) {
+    ScriptedOssServer server({
+        {206, "value"},
+        {404, ""},
+        {206, "bad"},
+    });
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "3");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    std::array<std::array<char, 5>, 3> buffers{};
+    const std::vector<ObjectGetRequest> requests{
+        {"first", buffers[0].data(), buffers[0].size()},
+        {"invalid", nullptr, 5},
+        {"second", buffers[1].data(), buffers[1].size()},
+        {"empty", nullptr, 0},
+        {"third", buffers[2].data(), buffers[2].size()},
+    };
+    auto results = adapter.GetBatch(requests);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+    ASSERT_EQ(results.size(), requests.size());
+    ASSERT_FALSE(results[1]);
+    EXPECT_EQ(results[1].error(), ErrorCode::INVALID_PARAMS);
+    ASSERT_TRUE(results[3]);
+    EXPECT_EQ(*results[3], 0U);
+    ASSERT_EQ(server.requests().size(), 3U);
+
+    // Match responses to observed request order rather than assuming that
+    // concurrent connections arrive in the order of the input vector.
+    for (size_t i = 0; i < server.requests().size(); ++i) {
+        const auto& received = server.requests()[i];
+        auto request = std::find_if(
+            requests.begin(), requests.end(), [&](const auto& candidate) {
+                return received.find("/" + candidate.logical_key + " HTTP/") !=
+                       std::string::npos;
+            });
+        ASSERT_NE(request, requests.end());
+        const auto& result = results[request - requests.begin()];
+        EXPECT_NE(received.find("Range: bytes=0-4"), std::string::npos);
+        if (i == 0) {
+            ASSERT_TRUE(result);
+            EXPECT_EQ(*result, 5U);
+            EXPECT_EQ(std::string(static_cast<char*>(request->buffer), 5),
+                      "value");
+        } else {
+            ASSERT_FALSE(result);
+            EXPECT_EQ(result.error(), i == 1 ? ErrorCode::FILE_NOT_FOUND
+                                             : ErrorCode::FILE_READ_FAIL);
+        }
+    }
+    EXPECT_TRUE(adapter.GetBatch({}).empty());
+}
+
+TEST(OssObjectStorageAdapterTest,
+     BatchPutStreamsIovecsAndPreservesPartialResults) {
+    ScriptedOssServer server({{200, ""}, {503, "unavailable"}, {200, ""}});
+    ScopedEnvironment environment;
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    environment.Set("MOONCAKE_OSS_MAX_CONNECTIONS", "3");
+
+    OssObjectStorageAdapter adapter("/test-prefix/");
+    ASSERT_TRUE(adapter.Init());
+    std::string left(20 * 1024, 'a');
+    std::string right(12 * 1024, 'b');
+    std::string second = "second value";
+    const iovec first_iov[] = {
+        {left.data(), left.size()}, {nullptr, 0}, {right.data(), right.size()}};
+    const iovec invalid_iov{nullptr, 1};
+    // Only the first descriptor belongs to this request. The trailing invalid
+    // descriptor must not be read: iovcnt, not the backing array size, wins.
+    const iovec second_iov[] = {{second.data(), second.size()}, {nullptr, 1}};
+    const std::vector<ObjectPutRequest> requests{
+        {"first", first_iov, 3},
+        {"invalid", &invalid_iov, 1},
+        {"second", second_iov, 1},
+        {"empty", nullptr, 0},
+    };
+    auto results = adapter.PutBatch(requests);
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+    ASSERT_EQ(results.size(), requests.size());
+    ASSERT_FALSE(results[1]);
+    EXPECT_EQ(results[1].error(), ErrorCode::INVALID_PARAMS);
+    ASSERT_EQ(server.requests().size(), 3U);
+
+    const std::map<std::string, std::string> expected_bodies{
+        {"first", left + right}, {"second", second}, {"empty", ""}};
+    for (size_t i = 0; i < server.requests().size(); ++i) {
+        const auto& received = server.requests()[i];
+        auto request = std::find_if(
+            requests.begin(), requests.end(), [&](const auto& candidate) {
+                return received.find("/" + candidate.logical_key + " HTTP/") !=
+                       std::string::npos;
+            });
+        ASSERT_NE(request, requests.end());
+        EXPECT_EQ(received.rfind("PUT ", 0), 0U);
+        const size_t body_start = received.find("\r\n\r\n");
+        ASSERT_NE(body_start, std::string::npos);
+        EXPECT_EQ(received.substr(body_start + 4),
+                  expected_bodies.at(request->logical_key));
+        const auto& result = results[request - requests.begin()];
+        if (i == 1) {
+            ASSERT_FALSE(result);
+            EXPECT_EQ(result.error(), ErrorCode::FILE_WRITE_FAIL);
+        } else {
+            EXPECT_TRUE(result);
+        }
+    }
+    EXPECT_TRUE(adapter.PutBatch({}).empty());
+}
+
+TEST(OssObjectStorageAdapterTest, LiveSyncBatchGetSmokeAndTiming) {
+    mooncake::test::RunLiveOssBatchGet(
+        "sync", [](OssObjectStorageAdapter& adapter,
+                   const std::vector<ObjectGetRequest>& requests) {
+            return adapter.GetBatch(requests);
+        });
+}
+
+TEST(OssObjectStorageAdapterTest, ObjectLifecycleAndVectorIO) {
+    if (!HasOssConfiguration()) {
+        GTEST_SKIP() << "OSS configuration is not available";
+    }
+
+    OssObjectStorageAdapter adapter(UniquePrefix("lifecycle"));
+    ASSERT_TRUE(adapter.Init());
+    ObjectCleanup cleanup(adapter);
+
+    std::string first_key = "tenant";
+    first_key.push_back('\0');
+    first_key += "/file%one";
+    const std::string first_data = "hello oss";
+    ASSERT_TRUE(adapter.Put(
+        first_key,
+        std::span<const char>(first_data.data(), first_data.size())));
+    cleanup.Add(first_key);
+
+    auto exists = adapter.Exists(first_key);
+    ASSERT_TRUE(exists);
+    EXPECT_TRUE(*exists);
+    auto size = adapter.GetSize(first_key);
+    ASSERT_TRUE(size);
+    EXPECT_EQ(*size, first_data.size());
+
+    std::string read_buffer(first_data.size(), '\0');
+    auto read = adapter.Get(first_key, read_buffer.data(), read_buffer.size());
+    ASSERT_TRUE(read);
+    EXPECT_EQ(*read, first_data.size());
+    EXPECT_EQ(read_buffer, first_data);
+
+    const std::string second_key = "file-two";
+    std::array<char, 3> left{{'a', 'b', 'c'}};
+    std::array<char, 3> right{{'d', 'e', 'f'}};
+    std::array<iovec, 2> write_iov{
+        {{left.data(), left.size()}, {right.data(), right.size()}}};
+    ASSERT_TRUE(adapter.PutV(second_key, write_iov.data(), 2));
+    cleanup.Add(second_key);
+
+    std::array<char, 2> read_left{};
+    std::array<char, 2> read_right{};
+    std::array<iovec, 2> read_iov{{{read_left.data(), read_left.size()},
+                                   {read_right.data(), read_right.size()}}};
+    auto vector_read = adapter.GetV(second_key, read_iov.data(), 2, 1);
+    ASSERT_TRUE(vector_read);
+    EXPECT_EQ(*vector_read, 4U);
+    EXPECT_EQ(std::string(read_left.data(), read_left.size()), "bc");
+    EXPECT_EQ(std::string(read_right.data(), read_right.size()), "de");
+
+    auto keys = adapter.ListKeys();
+    ASSERT_TRUE(keys);
+    std::map<std::string, size_t> sizes;
+    for (const auto& key : *keys) sizes[key.logical_key] = key.size;
+    EXPECT_EQ(sizes[first_key], first_data.size());
+    EXPECT_EQ(sizes[second_key], 6U);
+
+    EXPECT_TRUE(adapter.Delete(first_key));
+    EXPECT_TRUE(adapter.Delete(second_key));
+    exists = adapter.Exists(first_key);
+    ASSERT_TRUE(exists);
+    EXPECT_FALSE(*exists);
+}
+
+TEST(OssObjectStorageAdapterTest, StorageBackendFactoryRunsObjectHealthCheck) {
+    ScriptedOssServer server({
+        {200, ""},
+        {206, "health_check"},
+        {204, ""},
+    });
+    ScopedEnvironment environment;
+    const std::string root = UniquePrefix("factory");
+    environment.Set("MOONCAKE_OSS_ENDPOINT",
+                    "http://127.0.0.1:" + std::to_string(server.port()));
+    environment.Set("MOONCAKE_OSS_BUCKET", "bucket");
+    environment.Set("MOONCAKE_OSS_REGION", "region");
+    environment.Set("MOONCAKE_OSS_PATH_STYLE", "true");
+    environment.Set("MOONCAKE_OSS_ANONYMOUS", "true");
+    environment.Set("MOONCAKE_DISTRIBUTED_FS_TYPE", "oss");
+    environment.Set("MOONCAKE_DISTRIBUTED_ROOT_DIR", root);
+    environment.Set("MOONCAKE_DISTRIBUTED_HEALTH_CHECK", "true");
+    environment.Set("MOONCAKE_DISTRIBUTED_HASH_BUCKET_COUNT", "4");
+    environment.Set("MOONCAKE_DFS_SHARD_COUNT", "0");
+    environment.Set("MOONCAKE_DFS_SHARD_CAPACITY", "0");
+    environment.Set("MOONCAKE_DFS_ALIGNMENT", "0");
+    environment.Set("MOONCAKE_DFS_SINGLE_TENANT", "false");
+
+    FileStorageConfig config;
+    config.storage_backend_type = StorageBackendType::kDistributed;
+    auto backend = CreateStorageBackend(config);
+    ASSERT_TRUE(backend);
+    auto distributed =
+        std::dynamic_pointer_cast<DistributedStorageBackend>(*backend);
+    ASSERT_NE(distributed, nullptr);
+    EXPECT_TRUE(distributed->UsesObjectStorage());
+    ASSERT_TRUE(distributed->Init());
+    server.Wait();
+    ASSERT_TRUE(server.error().empty()) << server.error();
+
+    ASSERT_EQ(server.requests().size(), 3U);
+    EXPECT_EQ(server.requests()[0].rfind("PUT ", 0), 0U);
+    EXPECT_EQ(server.requests()[1].rfind("GET ", 0), 0U);
+    EXPECT_EQ(server.requests()[2].rfind("DELETE ", 0), 0U);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/oss_fault_test_helpers.h b/mooncake-store/tests/oss_fault_test_helpers.h
new file mode 100644
index 0000000000..818185b9ba
--- /dev/null
+++ b/mooncake-store/tests/oss_fault_test_helpers.h
@@ -0,0 +1,317 @@
+#pragma once
+
+#include <arpa/inet.h>
+#include <fcntl.h>
+#include <netinet/in.h>
+#include <poll.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cerrno>
+#include <chrono>
+#include <cctype>
+#include <condition_variable>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace mooncake::test {
+
+// Loopback-only, path-routed fault injection. Replies do not depend on the
+// arrival order of concurrent requests. Stop() never closes a descriptor owned
+// by a server thread: handlers observe stop_ in bounded poll intervals.
+class OssFaultHttpServer {
+   public:
+    struct Response {
+        enum class Action { kReply, kReset, kStall, kGate };
+        Action action = Action::kReply;
+        std::string wire;
+    };
+
+    static Response Reply(int status, const std::string& body,
+                          const std::string& extra_headers = "") {
+        return {Response::Action::kReply,
+                "HTTP/1.1 " + std::to_string(status) +
+                    " Test\r\nContent-Length: " + std::to_string(body.size()) +
+                    "\r\nConnection: close\r\n" + extra_headers + "\r\n" +
+                    body};
+    }
+    static Response Raw(std::string wire) {
+        return {Response::Action::kReply, std::move(wire)};
+    }
+    static Response Reset() { return {Response::Action::kReset, {}}; }
+    static Response Stall() { return {Response::Action::kStall, {}}; }
+    static Response Gate(int status, const std::string& body,
+                         const std::string& extra_headers = "") {
+        auto response = Reply(status, body, extra_headers);
+        response.action = Response::Action::kGate;
+        return response;
+    }
+
+    explicit OssFaultHttpServer(std::map<std::string, Response> routes,
+                                bool concurrent = false)
+        : routes_(std::move(routes)), concurrent_(concurrent) {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) throw std::runtime_error("socket failed");
+        sockaddr_in address{};
+        address.sin_family = AF_INET;
+        address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        address.sin_port = 0;
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&address),
+                 sizeof(address)) != 0 ||
+            listen(listen_fd_, 32) != 0 || !SetNonblocking(listen_fd_)) {
+            close(listen_fd_);
+            throw std::runtime_error("loopback listener setup failed");
+        }
+        socklen_t length = sizeof(address);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&address),
+                        &length) != 0) {
+            close(listen_fd_);
+            throw std::runtime_error("getsockname failed");
+        }
+        port_ = ntohs(address.sin_port);
+        try {
+            thread_ = std::thread([this] { Serve(); });
+        } catch (...) {
+            close(listen_fd_);
+            throw;
+        }
+    }
+
+    ~OssFaultHttpServer() { Stop(); }
+
+    void Stop() {
+        {
+            std::lock_guard lock(mutex_);
+            stop_.store(true);
+        }
+        condition_.notify_all();
+        if (thread_.joinable()) thread_.join();
+        // Only the accept thread adds handlers; join it before reading them.
+        for (auto& handler : handlers_) {
+            if (handler.joinable()) handler.join();
+        }
+        if (listen_fd_ >= 0) {
+            close(listen_fd_);
+            listen_fd_ = -1;
+        }
+    }
+
+    bool WaitForRequest(
+        const std::string& key,
+        std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        std::unique_lock lock(mutex_);
+        auto received = [&] {
+            return std::find(request_keys_.begin(), request_keys_.end(), key) !=
+                   request_keys_.end();
+        };
+        condition_.wait_for(lock, timeout,
+                            [&] { return stop_.load() || received(); });
+        return received();
+    }
+
+    void ReleaseResponses() {
+        {
+            std::lock_guard lock(mutex_);
+            responses_released_ = true;
+        }
+        condition_.notify_all();
+    }
+
+    uint16_t port() const { return port_; }
+    std::string error() const {
+        std::lock_guard lock(mutex_);
+        return error_;
+    }
+    std::vector<std::string> requests() const {
+        std::lock_guard lock(mutex_);
+        return requests_;
+    }
+
+   private:
+    using Clock = std::chrono::steady_clock;
+
+    static bool SetNonblocking(int fd) {
+        const int flags = fcntl(fd, F_GETFL, 0);
+        return flags >= 0 && fcntl(fd, F_SETFL, flags | O_NONBLOCK) == 0;
+    }
+
+    void SetError(const char* error) {
+        std::lock_guard lock(mutex_);
+        if (error_.empty()) error_ = error;
+    }
+
+    bool Ready(int fd, short events, Clock::time_point deadline) {
+        while (!stop_.load() && Clock::now() < deadline) {
+            pollfd descriptor{fd, events, 0};
+            const int ready = poll(&descriptor, 1, 25);
+            if (ready > 0) return true;
+            if (ready < 0 && errno != EINTR) return false;
+        }
+        return false;
+    }
+
+    std::string ReadRequest(int fd) {
+        const auto deadline = Clock::now() + std::chrono::seconds(5);
+        std::string request;
+        std::array<char, 4096> buffer{};
+        std::optional<size_t> request_size;
+        while (Ready(fd, POLLIN, deadline)) {
+            const ssize_t count = recv(fd, buffer.data(), buffer.size(), 0);
+            if (count < 0 && (errno == EAGAIN || errno == EINTR)) continue;
+            if (count <= 0) return {};
+            request.append(buffer.data(), static_cast<size_t>(count));
+            if (request.size() > 1024 * 1024) return {};
+            const size_t header_end = request.find("\r\n\r\n");
+            if (!request_size && header_end != std::string::npos) {
+                std::string headers = request.substr(0, header_end);
+                std::transform(headers.begin(), headers.end(), headers.begin(),
+                               [](unsigned char c) { return std::tolower(c); });
+                constexpr const char* field = "\r\ncontent-length:";
+                const size_t field_pos = headers.find(field);
+                size_t body_size = 0;
+                if (field_pos != std::string::npos) {
+                    try {
+                        body_size = std::stoull(headers.substr(field_pos + 17));
+                    } catch (...) {
+                        return {};
+                    }
+                }
+                if (body_size > 1024 * 1024) return {};
+                request_size = header_end + 4 + body_size;
+            }
+            if (request_size && request.size() >= *request_size) return request;
+        }
+        return {};
+    }
+
+    void SendReply(int fd, const std::string& wire) {
+        const auto deadline = Clock::now() + std::chrono::seconds(5);
+        size_t sent = 0;
+        while (sent < wire.size() && Ready(fd, POLLOUT, deadline)) {
+            const ssize_t count =
+                send(fd, wire.data() + sent, wire.size() - sent, MSG_NOSIGNAL);
+            if (count < 0 && (errno == EAGAIN || errno == EINTR)) continue;
+            // The client may legitimately abort an error or malformed body.
+            if (count <= 0) return;
+            sent += static_cast<size_t>(count);
+        }
+    }
+
+    void StallUntilPeerCloses(int fd) {
+        // Production currently has a 120 s request deadline. The test server
+        // holds the connection beyond that deadline; Stop() still exits within
+        // a poll interval, including when a test assertion fails.
+        const auto deadline = Clock::now() + std::chrono::seconds(135);
+        char byte;
+        while (Ready(fd, POLLIN, deadline)) {
+            const ssize_t count = recv(fd, &byte, 1, 0);
+            if (count == 0) return;
+            if (count < 0 && errno != EAGAIN && errno != EINTR) return;
+        }
+    }
+
+    bool WaitForRelease() {
+        std::unique_lock lock(mutex_);
+        if (!condition_.wait_for(lock, std::chrono::seconds(5), [&] {
+                return stop_.load() || responses_released_;
+            })) {
+            if (error_.empty())
+                error_ = "timed out waiting to release response";
+            return false;
+        }
+        return !stop_.load();
+    }
+
+    void HandleClient(int client) {
+        // The handler owns this descriptor until it returns, including Stop.
+        struct ClientGuard {
+            int fd;
+            ~ClientGuard() { close(fd); }
+        } guard{client};
+        if (!SetNonblocking(client)) {
+            SetError("client nonblocking setup failed");
+            return;
+        }
+        const std::string request = ReadRequest(client);
+        if (request.empty()) {
+            if (!stop_.load()) SetError("incomplete request");
+            return;
+        }
+        const size_t first_space = request.find(' ');
+        const size_t second_space = request.find(' ', first_space + 1);
+        const std::string target =
+            request.substr(first_space + 1, second_space - first_space - 1);
+        const std::string key = target.substr(target.find_last_of('/') + 1);
+        {
+            std::lock_guard lock(mutex_);
+            requests_.push_back(request);
+            request_keys_.push_back(key);
+        }
+        condition_.notify_all();
+        const auto response = routes_.find(key);
+        if (response == routes_.end()) {
+            SetError("unexpected request target");
+            SendReply(client, Reply(404, "unknown").wire);
+        } else if (response->second.action == Response::Action::kReset) {
+            linger reset{1, 0};
+            if (setsockopt(client, SOL_SOCKET, SO_LINGER, &reset,
+                           sizeof(reset)) != 0)
+                SetError("reset setup failed");
+        } else if (response->second.action == Response::Action::kStall) {
+            StallUntilPeerCloses(client);
+        } else if (response->second.action != Response::Action::kGate ||
+                   WaitForRelease()) {
+            SendReply(client, response->second.wire);
+        }
+    }
+
+    void Serve() {
+        while (!stop_.load()) {
+            if (!Ready(listen_fd_, POLLIN,
+                       Clock::now() + std::chrono::milliseconds(50)))
+                continue;
+            const int client = accept(listen_fd_, nullptr, nullptr);
+            if (client < 0) {
+                if (errno != EAGAIN && errno != EINTR)
+                    SetError("accept failed");
+                continue;
+            }
+            if (concurrent_) {
+                try {
+                    handlers_.emplace_back(
+                        [this, client] { HandleClient(client); });
+                } catch (...) {
+                    close(client);
+                    SetError("client thread setup failed");
+                }
+            } else {
+                HandleClient(client);
+            }
+        }
+    }
+
+    const std::map<std::string, Response> routes_;
+    const bool concurrent_;
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    std::atomic<bool> stop_{false};
+    std::thread thread_;
+    std::vector<std::thread> handlers_;
+    mutable std::mutex mutex_;
+    std::condition_variable condition_;
+    std::vector<std::string> requests_;
+    std::vector<std::string> request_keys_;
+    bool responses_released_ = false;
+    std::string error_;
+};
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/oss_live_test_helpers.h b/mooncake-store/tests/oss_live_test_helpers.h
new file mode 100644
index 0000000000..2a4ec226fc
--- /dev/null
+++ b/mooncake-store/tests/oss_live_test_helpers.h
@@ -0,0 +1,124 @@
+#pragma once
+#include <gtest/gtest.h>
+#include <unistd.h>
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <iostream>
+#include <optional>
+#include <string>
+#include <vector>
+#include "storage/distributed/oss_adapter.h"
+
+namespace mooncake::test {
+class LiveOssParameter {
+   public:
+    LiveOssParameter(const char* key, const char* value) : key_(key) {
+        if (const char* old = getenv(key)) old_ = old;
+        setenv(key, value, 1);
+    }
+    ~LiveOssParameter() {
+        if (old_)
+            setenv(key_.c_str(), old_->c_str(), 1);
+        else
+            unsetenv(key_.c_str());
+    }
+
+   private:
+    std::string key_;
+    std::optional<std::string> old_;
+};
+class LiveOssCleanup {
+   public:
+    explicit LiveOssCleanup(OssObjectStorageAdapter& adapter)
+        : adapter_(adapter) {}
+    ~LiveOssCleanup() {
+        for (const auto& key : keys)
+            EXPECT_TRUE(adapter_.Delete(key).has_value());
+        auto remaining = adapter_.ListKeys();
+        EXPECT_TRUE(remaining.has_value());
+        if (remaining) {
+            EXPECT_TRUE(remaining->empty());
+        }
+    }
+    std::vector<std::string> keys;
+
+   private:
+    OssObjectStorageAdapter& adapter_;
+};
+
+// Cloud acceptance timing: a finite continuous queue, NOT a maximum-throughput
+// guarantee. Every request owns a separate buffer; only final queue drain
+// occurs.
+template <class Execute>
+void RunLiveOssBatchGet(const char* mode, Execute execute) {
+    const char* enabled = getenv("MOONCAKE_RUN_LIVE_OSS");
+    if (!enabled || std::string(enabled) != "1") {
+        GTEST_SKIP() << "Set MOONCAKE_RUN_LIVE_OSS=1 for real OSS batch I/O";
+    }
+    constexpr size_t size = size_t{4} << 20, depth = 64, count = 1024,
+                     rounds = 3;
+    LiveOssParameter connections("MOONCAKE_OSS_MAX_CONNECTIONS", "64");
+    const auto nonce =
+        std::chrono::steady_clock::now().time_since_epoch().count();
+    OssObjectStorageAdapter adapter("/mooncake-review-live/" +
+                                    std::to_string(getpid()) + "-" +
+                                    std::to_string(nonce) + "-" + mode);
+    ASSERT_TRUE(adapter.Init());
+    LiveOssCleanup cleanup(adapter);
+    std::vector<char> source(size);
+    for (size_t i = 0; i < size; ++i)
+        source[i] = static_cast<char>((i * 17 + 29) & 255);
+    const iovec source_iov{source.data(), size};
+    std::vector<ObjectPutRequest> puts;
+    for (size_t i = 0; i < depth; ++i) {
+        cleanup.keys.push_back("object-" + std::to_string(i));
+        puts.push_back({cleanup.keys.back(), &source_iov, 1});
+    }
+    auto uploaded = adapter.PutBatch(puts);
+    ASSERT_EQ(uploaded.size(), puts.size());
+    for (const auto& result : uploaded) ASSERT_TRUE(result);
+    // Allocate and touch all 4 GiB before timed GET; reuse a 256 MiB OSS
+    // working set.
+    std::vector<char> destination(size * count);
+    std::vector<ObjectGetRequest> requests;
+    for (size_t i = 0; i < count; ++i)
+        requests.push_back(
+            {cleanup.keys[i % depth], destination.data() + i * size, size});
+    std::vector<ObjectGetRequest> warm_requests(requests.begin(),
+                                                requests.begin() + depth);
+    auto warm = execute(adapter, warm_requests);
+    ASSERT_EQ(warm.size(), depth);
+    for (size_t i = 0; i < depth; ++i) {
+        ASSERT_TRUE(warm[i]);
+        ASSERT_EQ(*warm[i], size);
+        ASSERT_EQ(
+            std::memcmp(destination.data() + i * size, source.data(), size), 0);
+    }
+    std::cout
+        << "LIVE_OSS_FUNCTIONAL mode=" << mode
+        << " objects=64 object_mib=4 batch_put=ok batch_get=ok memcmp=ok\n";
+    double total = 0;
+    for (size_t round = 0; round < rounds; ++round) {
+        auto begin = std::chrono::steady_clock::now();
+        auto results = execute(adapter, requests);
+        const double seconds = std::chrono::duration<double>(
+                                   std::chrono::steady_clock::now() - begin)
+                                   .count();
+        ASSERT_EQ(results.size(), count);
+        for (const auto& result : results) {
+            ASSERT_TRUE(result);
+            ASSERT_EQ(*result, size);
+        }
+        total += seconds;
+        std::cout << "LIVE_OSS_GET mode=" << mode << " round=" << round
+                  << " object_mib=4 depth=64 requests=1024 working_set_mib=256"
+                  << " window=continuous-queue-final-drain GiB=4 seconds="
+                  << seconds << " GiBps=" << 4.0 / seconds
+                  << " memcmp=0 length_check=1 errors=0\n";
+    }
+    std::cout << "LIVE_OSS_GET_TOTAL mode=" << mode
+              << " rounds=3 GiB=12 seconds=" << total
+              << " GiBps=" << 12.0 / total << " errors=0\n";
+}
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/posix_file_test.cpp b/mooncake-store/tests/posix_file_test.cpp
index 543c36aa37..3ca2da4cdc 100644
--- a/mooncake-store/tests/posix_file_test.cpp
+++ b/mooncake-store/tests/posix_file_test.cpp
@@ -1,9 +1,20 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
+#include <array>
+#include <cerrno>
+#include <csignal>
+#include <cstdlib>
+#include <cstring>
+#include <memory>
 #include <fcntl.h>
+#include <sys/resource.h>
+#include <sys/wait.h>
 #include <unistd.h>
 #include <sys/uio.h>
+#include <string_view>
+#include <vector>
 #include "file_interface.h"
+#include "../src/uring_submit.h"
 
 namespace mooncake {
 
@@ -31,6 +42,68 @@ class PosixFileTest : public ::testing::Test {
     int test_fd = -1;
 };
 
+#ifdef USE_URING
+TEST(UringSubmitTest, ContinuesAfterPositiveShortSubmit) {
+    unsigned pending = 8;
+    std::vector<unsigned> requested;
+    std::array<int, 2> returns{3, 5};
+    size_t call = 0;
+
+    auto result = detail::submit_all_pending(
+        [&] { return pending; },
+        [&](unsigned requested_count) {
+            requested.push_back(requested_count);
+            int submitted = returns[call++];
+            pending -= static_cast<unsigned>(submitted);
+            return submitted;
+        },
+        [] {});
+
+    EXPECT_EQ(result.error, 0);
+    EXPECT_EQ(result.submitted, 8U);
+    EXPECT_EQ(result.pending, 0U);
+    EXPECT_EQ(requested, (std::vector<unsigned>{8, 5}));
+}
+
+TEST(UringSubmitTest, RetriesTransientSubmissionErrors) {
+    unsigned pending = 4;
+    std::array<int, 3> returns{-EINTR, -EAGAIN, 4};
+    size_t call = 0;
+    unsigned yields = 0;
+
+    auto result = detail::submit_all_pending(
+        [&] { return pending; },
+        [&](unsigned) {
+            int ret = returns[call++];
+            if (ret > 0) pending -= static_cast<unsigned>(ret);
+            return ret;
+        },
+        [&] { ++yields; });
+
+    EXPECT_EQ(result.error, 0);
+    EXPECT_EQ(result.submitted, 4U);
+    EXPECT_EQ(result.pending, 0U);
+    EXPECT_EQ(yields, 2U);
+}
+
+TEST(UringSubmitTest, StopsAfterBoundedNoProgress) {
+    unsigned pending = 4;
+    unsigned calls = 0;
+    auto submit = [&](unsigned) {
+        ++calls;
+        return -ENOMEM;
+    };
+
+    auto result =
+        detail::submit_all_pending([&] { return pending; }, submit, [] {}, 2);
+
+    EXPECT_EQ(result.error, -ENOMEM);
+    EXPECT_EQ(result.submitted, 0U);
+    EXPECT_EQ(result.pending, pending);
+    EXPECT_EQ(calls, 3U);
+}
+#endif
+
 // Test basic file lifecycle
 TEST_F(PosixFileTest, FileLifecycle) {
     PosixFile posix_file(test_filename, test_fd);
@@ -98,6 +171,50 @@ TEST_F(PosixFileTest, VectorizedWrite) {
     EXPECT_EQ(posix_file.get_error_code(), ErrorCode::OK);
 }
 
+// A short pwritev must be treated as a failed write. Otherwise the PosixFile
+// destructor has no failure state and leaves a truncated object on disk.
+TEST_F(PosixFileTest, ShortVectorizedWriteRemovesPartialFile) {
+#if defined(RLIMIT_FSIZE) && defined(SIGXFSZ)
+    const std::string partial_filename =
+        "short_vector_write_" + std::to_string(getpid()) + ".tmp";
+
+    pid_t child = fork();
+    ASSERT_GE(child, 0) << "Failed to fork short-write test";
+
+    if (child == 0) {
+        if (signal(SIGXFSZ, SIG_IGN) == SIG_ERR) _exit(10);
+
+        const struct rlimit limit = {4096, 4096};
+        if (setrlimit(RLIMIT_FSIZE, &limit) != 0) _exit(11);
+
+        int fd =
+            open(partial_filename.c_str(), O_CREAT | O_RDWR | O_TRUNC, 0644);
+        if (fd < 0) _exit(12);
+
+        std::string data(8192, 'x');
+        {
+            PosixFile posix_file(partial_filename, fd);
+            iovec iov{data.data(), data.size()};
+            auto result = posix_file.vector_write(&iov, 1, 0);
+            if (result || result.error() != ErrorCode::FILE_WRITE_FAIL)
+                _exit(13);
+        }
+
+        if (access(partial_filename.c_str(), F_OK) == 0) _exit(14);
+        if (errno != ENOENT) _exit(15);
+        _exit(0);
+    }
+
+    int status = 0;
+    ASSERT_EQ(waitpid(child, &status, 0), child);
+    unlink(partial_filename.c_str());
+    ASSERT_TRUE(WIFEXITED(status));
+    EXPECT_EQ(WEXITSTATUS(status), 0);
+#else
+    GTEST_SKIP() << "RLIMIT_FSIZE/SIGXFSZ is unavailable on this platform";
+#endif
+}
+
 // Test vectorized read operation
 TEST_F(PosixFileTest, VectorizedRead) {
     // Clear file content
@@ -173,9 +290,252 @@ TEST_F(PosixFileTest, FileLocking) {
     }
 }
 
+#ifdef USE_URING
+TEST_F(PosixFileTest, UringBatchReadReportsPerRequestResultsAcrossQueueDepth) {
+    constexpr size_t kBlockSize = 128;
+    constexpr int kRequestCount = 40;
+    std::vector<std::array<char, kBlockSize>> expected(kRequestCount);
+    for (int i = 0; i < kRequestCount; ++i) {
+        expected[i].fill(static_cast<char>('A' + i % 26));
+        ASSERT_EQ(pwrite(test_fd, expected[i].data(), expected[i].size(),
+                         static_cast<off_t>(i * kBlockSize)),
+                  static_cast<ssize_t>(expected[i].size()));
+    }
+
+    int uring_fd = dup(test_fd);
+    ASSERT_GE(uring_fd, 0);
+    UringFile uring_file(test_filename, uring_fd, 32, false);
+    std::vector<std::array<char, kBlockSize>> actual(kRequestCount);
+    std::vector<UringFile::ReadDesc> descs;
+    descs.reserve(kRequestCount);
+    for (int i = 0; i < kRequestCount; ++i) {
+        descs.push_back(
+            UringFile::ReadDesc{actual[i].data(), actual[i].size(),
+                                static_cast<off_t>(i * kBlockSize)});
+    }
+
+    auto result = uring_file.batch_read(descs.data(), descs.size());
+    ASSERT_TRUE(result.has_value()) << toString(result.error());
+    for (int i = 0; i < kRequestCount; ++i) {
+        EXPECT_TRUE(descs[i].completed);
+        EXPECT_EQ(descs[i].error, ErrorCode::OK);
+        EXPECT_EQ(descs[i].bytes_read, kBlockSize);
+        EXPECT_EQ(actual[i], expected[i]);
+    }
+}
+
+TEST_F(PosixFileTest, UringBatchReadReportsShortReadPerRequest) {
+    constexpr std::string_view data = "abcdef";
+    ASSERT_EQ(pwrite(test_fd, data.data(), data.size(), 0),
+              static_cast<ssize_t>(data.size()));
+
+    int uring_fd = dup(test_fd);
+    ASSERT_GE(uring_fd, 0);
+    UringFile uring_file(test_filename, uring_fd, 32, false);
+    std::array<char, 3> complete{};
+    std::array<char, 8> short_read{};
+    std::array<UringFile::ReadDesc, 2> descs{
+        UringFile::ReadDesc{complete.data(), complete.size(), 0},
+        UringFile::ReadDesc{short_read.data(), short_read.size(), 4}};
+
+    auto result = uring_file.batch_read(descs.data(), descs.size());
+    ASSERT_TRUE(result.has_value()) << toString(result.error());
+    EXPECT_TRUE(descs[0].completed);
+    EXPECT_EQ(descs[0].error, ErrorCode::OK);
+    EXPECT_EQ(descs[0].bytes_read, complete.size());
+    EXPECT_TRUE(descs[1].completed);
+    EXPECT_EQ(descs[1].error, ErrorCode::OK);
+    EXPECT_EQ(descs[1].bytes_read, 2U);
+}
+
+TEST_F(PosixFileTest, UringBatchReadRejectsMisalignedDirectIoDescriptors) {
+    int uring_fd = dup(test_fd);
+    ASSERT_GE(uring_fd, 0);
+    UringFile uring_file(test_filename, uring_fd, 32, true);
+
+    void* allocation = nullptr;
+    ASSERT_EQ(posix_memalign(&allocation, 4096, 8192), 0);
+    std::unique_ptr<void, decltype(&std::free)> buffer(allocation, &std::free);
+    auto* aligned = static_cast<char*>(buffer.get());
+
+    auto expect_invalid = [&](UringFile::ReadDesc desc) {
+        auto result = uring_file.batch_read(&desc, 1);
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::FILE_INVALID_BUFFER);
+        EXPECT_FALSE(desc.completed);
+    };
+
+    expect_invalid(UringFile::ReadDesc{aligned + 1, 4096, 0});
+    expect_invalid(UringFile::ReadDesc{aligned, 4095, 0});
+    expect_invalid(UringFile::ReadDesc{aligned, 4096, 1});
+}
+
+TEST_F(PosixFileTest, UringBatchReadDrainsErrorsBeforeNextOperation) {
+    std::array<char, 16> first{};
+    std::array<char, 16> second{};
+    {
+        int invalid_fd = open("/dev/null", O_WRONLY | O_CLOEXEC);
+        ASSERT_GE(invalid_fd, 0);
+        UringFile invalid_file("/dev/null", invalid_fd, 32, false);
+        std::array<UringFile::ReadDesc, 2> invalid_descs{
+            UringFile::ReadDesc{first.data(), first.size(), 0},
+            UringFile::ReadDesc{second.data(), second.size(), 0}};
+
+        auto invalid_result =
+            invalid_file.batch_read(invalid_descs.data(), invalid_descs.size());
+        ASSERT_FALSE(invalid_result.has_value());
+        EXPECT_EQ(invalid_result.error(), ErrorCode::FILE_READ_FAIL);
+        EXPECT_TRUE(invalid_descs[0].completed);
+        EXPECT_EQ(invalid_descs[0].error, ErrorCode::FILE_READ_FAIL);
+        EXPECT_TRUE(invalid_descs[1].completed);
+        EXPECT_EQ(invalid_descs[1].error, ErrorCode::FILE_READ_FAIL);
+    }
+
+    constexpr std::string_view data = "ring-remains-usable";
+    ASSERT_EQ(pwrite(test_fd, data.data(), data.size(), 0),
+              static_cast<ssize_t>(data.size()));
+    int valid_fd = dup(test_fd);
+    ASSERT_GE(valid_fd, 0);
+    UringFile valid_file(test_filename, valid_fd, 32, false);
+    std::vector<char> output(data.size());
+    UringFile::ReadDesc desc{output.data(), output.size(), 0};
+
+    auto valid_result = valid_file.batch_read(&desc, 1);
+    ASSERT_TRUE(valid_result.has_value()) << toString(valid_result.error());
+    EXPECT_TRUE(desc.completed);
+    EXPECT_EQ(desc.error, ErrorCode::OK);
+    EXPECT_EQ(desc.bytes_read, data.size());
+    EXPECT_EQ(std::string_view(output.data(), output.size()), data);
+}
+
+TEST_F(PosixFileTest, UringVectorIoHandlesUnalignedDirectIo) {
+    const std::string direct_filename = "direct_vector_test.bin";
+    remove(direct_filename.c_str());
+
+    int direct_fd = open(direct_filename.c_str(),
+                         O_CREAT | O_RDWR | O_DIRECT | O_CLOEXEC, 0644);
+    ASSERT_GE(direct_fd, 0) << strerror(errno);
+    ASSERT_EQ(ftruncate(direct_fd, 16384), 0);
+
+    UringFile uring_file(direct_filename, direct_fd, 32, true);
+
+    // Neighboring data in the same 4KiB block must survive RMW writes.
+    const std::string neighbor = "keep-me";
+    iovec neighbor_iov;
+    neighbor_iov.iov_base = const_cast<char*>(neighbor.data());
+    neighbor_iov.iov_len = neighbor.size();
+    auto neighbor_write = uring_file.vector_write(&neighbor_iov, 1, 0);
+    ASSERT_TRUE(neighbor_write.has_value()) << toString(neighbor_write.error());
+
+    char header[48] = {};
+    std::memcpy(header, "HDR", 3);
+    const std::string key = "object-key";
+    const std::string payload = "payload-bytes-for-direct-io";
+
+    iovec write_iov[3];
+    write_iov[0].iov_base = header;
+    write_iov[0].iov_len = sizeof(header);
+    write_iov[1].iov_base = const_cast<char*>(key.data());
+    write_iov[1].iov_len = key.size();
+    write_iov[2].iov_base = const_cast<char*>(payload.data());
+    write_iov[2].iov_len = payload.size();
+
+    constexpr off_t kOffset = 513;
+    auto write_result = uring_file.vector_write(write_iov, 3, kOffset);
+    ASSERT_TRUE(write_result.has_value()) << toString(write_result.error());
+    const size_t expected = sizeof(header) + key.size() + payload.size();
+    EXPECT_EQ(*write_result, expected);
+
+    char out_header[sizeof(header)] = {};
+    std::string out_key(key.size(), '\0');
+    std::string out_payload(payload.size(), '\0');
+    iovec read_iov[3];
+    read_iov[0].iov_base = out_header;
+    read_iov[0].iov_len = sizeof(out_header);
+    read_iov[1].iov_base = out_key.data();
+    read_iov[1].iov_len = out_key.size();
+    read_iov[2].iov_base = out_payload.data();
+    read_iov[2].iov_len = out_payload.size();
+
+    auto read_result = uring_file.vector_read(read_iov, 3, kOffset);
+    ASSERT_TRUE(read_result.has_value()) << toString(read_result.error());
+    EXPECT_EQ(*read_result, expected);
+    EXPECT_EQ(std::string_view(out_header, 3), "HDR");
+    EXPECT_EQ(out_key, key);
+    EXPECT_EQ(out_payload, payload);
+
+    std::string out_neighbor(neighbor.size(), '\0');
+    iovec neighbor_read_iov;
+    neighbor_read_iov.iov_base = out_neighbor.data();
+    neighbor_read_iov.iov_len = out_neighbor.size();
+    auto neighbor_read = uring_file.vector_read(&neighbor_read_iov, 1, 0);
+    ASSERT_TRUE(neighbor_read.has_value()) << toString(neighbor_read.error());
+    EXPECT_EQ(out_neighbor, neighbor);
+
+    remove(direct_filename.c_str());
+}
+
+TEST_F(PosixFileTest, UringVectorWriteAbortsWhenPreservationReadFails) {
+    const std::string direct_filename = "direct_vector_preserve_fail.bin";
+    remove(direct_filename.c_str());
+
+    {
+        int setup_fd = open(direct_filename.c_str(),
+                            O_CREAT | O_RDWR | O_DIRECT | O_CLOEXEC, 0644);
+        ASSERT_GE(setup_fd, 0) << strerror(errno);
+        ASSERT_EQ(ftruncate(setup_fd, 16384), 0);
+        UringFile setup_file(direct_filename, setup_fd, 32, true);
+
+        const std::string neighbor = "keep-neighbor-bytes";
+        iovec neighbor_iov;
+        neighbor_iov.iov_base = const_cast<char*>(neighbor.data());
+        neighbor_iov.iov_len = neighbor.size();
+        auto neighbor_write = setup_file.vector_write(&neighbor_iov, 1, 0);
+        ASSERT_TRUE(neighbor_write.has_value())
+            << toString(neighbor_write.error());
+    }
+
+    // Re-open write-only so the RMW preservation read must fail. The write
+    // must abort without clobbering the already-written neighbor bytes.
+    int write_only_fd =
+        open(direct_filename.c_str(), O_WRONLY | O_DIRECT | O_CLOEXEC);
+    ASSERT_GE(write_only_fd, 0) << strerror(errno);
+    {
+        UringFile write_only_file(direct_filename, write_only_fd, 32, true);
+        char payload[64];
+        std::memset(payload, 'X', sizeof(payload));
+        iovec write_iov;
+        write_iov.iov_base = payload;
+        write_iov.iov_len = sizeof(payload);
+
+        constexpr off_t kOffset = 513;
+        auto write_result =
+            write_only_file.vector_write(&write_iov, 1, kOffset);
+        ASSERT_FALSE(write_result.has_value());
+        EXPECT_EQ(write_result.error(), ErrorCode::FILE_READ_FAIL);
+    }
+
+    int verify_fd =
+        open(direct_filename.c_str(), O_RDONLY | O_DIRECT | O_CLOEXEC);
+    ASSERT_GE(verify_fd, 0) << strerror(errno);
+    UringFile verify_file(direct_filename, verify_fd, 32, true);
+
+    const std::string neighbor = "keep-neighbor-bytes";
+    std::string out_neighbor(neighbor.size(), '\0');
+    iovec neighbor_read_iov;
+    neighbor_read_iov.iov_base = out_neighbor.data();
+    neighbor_read_iov.iov_len = out_neighbor.size();
+    auto neighbor_read = verify_file.vector_read(&neighbor_read_iov, 1, 0);
+    ASSERT_TRUE(neighbor_read.has_value()) << toString(neighbor_read.error());
+    EXPECT_EQ(out_neighbor, neighbor);
+
+    remove(direct_filename.c_str());
+}
+#endif
+
 }  // namespace mooncake
 
 int main(int argc, char** argv) {
     ::testing::InitGoogleTest(&argc, argv);
     return RUN_ALL_TESTS();
-}
\ No newline at end of file
+}
diff --git a/mooncake-store/tests/promotion_on_hit_test.cpp b/mooncake-store/tests/promotion_on_hit_test.cpp
index dc14273626..ff3f3c0d93 100644
--- a/mooncake-store/tests/promotion_on_hit_test.cpp
+++ b/mooncake-store/tests/promotion_on_hit_test.cpp
@@ -3,6 +3,7 @@
 // layer.
 
 #include "master_service.h"
+#include "master_service/master_service_test_peer.h"
 
 #include <glog/logging.h>
 #include <gtest/gtest.h>
@@ -13,6 +14,7 @@
 #include <fstream>
 #include <map>
 #include <memory>
+#include <optional>
 #include <string>
 #include <thread>
 #include <vector>
@@ -46,68 +48,138 @@ class PromotionOnHitTest : public ::testing::Test {
         google::ShutdownGoogleLogging();
     }
 
-    // Friend access to MasterService::promotion_admission_threshold_, which
-    // is otherwise private. PromotionOnHitTest is friended; TEST_F-generated
-    // subclasses are not, hence this static funnel.
+    // Inspect admission state through the shared test peer.
     static uint32_t GetPromotionAdmissionThresholdForTesting(
         MasterService* service) {
-        return service->promotion_admission_threshold_;
+        return MasterServiceTestPeer::PromotionAdmissionThreshold(*service);
     }
 
     static size_t CountPromotionCandidatesForTesting(MasterService* service,
                                                      const TenantId& tenant) {
-        return service->CountCandidatesForTesting(tenant);
+        return MasterServiceTestPeer(*service).CountCandidatesForTesting(
+            tenant);
+    }
+
+    static constexpr uint32_t MaxPromotionCandidateRetriesForTesting() {
+        return MasterServiceTestPeer::kPromotionCandidateMaxRetries;
+    }
+
+    static constexpr uint32_t MaxPromotionExecutionFailuresForTesting() {
+        return MasterServiceTestPeer::kMaxPromotionExecutionFailures;
     }
 
     static void ResetCandidateBackoffsForTesting(MasterService* service) {
-        service->ResetCandidateBackoffsForTesting();
+        MasterServiceTestPeer(*service).ResetCandidateBackoffsForTesting();
     }
 
     static size_t RunPromotionCandidateRetryForTesting(MasterService* service) {
-        return service->RunPromotionCandidateRetryForTesting();
+        return MasterServiceTestPeer(*service)
+            .RunPromotionCandidateRetryForTesting();
     }
 
     static size_t RunPromotionCandidateRetryForTesting(MasterService* service,
                                                        size_t shards_to_scan) {
-        return service->RunPromotionCandidateRetry(shards_to_scan);
+        return MasterServiceTestPeer(*service).RunPromotionCandidateRetry(
+            shards_to_scan);
     }
 
     static void ClearCandidatesForReloadForTesting(MasterService* service) {
-        service->ClearCandidatesForReload();
+        MasterServiceTestPeer(*service).ClearCandidatesForReload();
     }
 
     static uint64_t GetPromotionCandidateCountForTesting(
         MasterService* service) {
-        return service->promotion_candidate_count_.load(
+        return MasterServiceTestPeer::PromotionCandidateCount(*service).load(
             std::memory_order_relaxed);
     }
 
     static uint64_t GetPromotionInFlightForTesting(MasterService* service) {
-        return service->promotion_in_flight_.load(std::memory_order_relaxed);
+        return MasterServiceTestPeer::PromotionInFlight(*service).load(
+            std::memory_order_relaxed);
+    }
+
+    static void MarkClientOfflineForTesting(MasterService* service,
+                                            const UUID& client_id) {
+        auto record =
+            MasterServiceTestPeer(*service).FindClientRecord(client_id);
+        ASSERT_TRUE(record);
+        const auto now = ClientLivenessRecord::Clock::now();
+        ASSERT_EQ(record->Evaluate(now, std::chrono::seconds::zero(),
+                                   std::chrono::seconds::zero()),
+                  ClientLivenessTransition::BECAME_SUSPECTED);
+        ASSERT_EQ(record->Evaluate(now, std::chrono::seconds::zero(),
+                                   std::chrono::seconds::zero()),
+                  ClientLivenessTransition::BECAME_OFFLINE);
+    }
+
+    static bool HasPromotionTaskForTesting(MasterService* service,
+                                           const TenantId& tenant_id,
+                                           const std::string& key) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            service, MasterServiceTestPeer::ObjectIdentity{
+                         .tenant_id = tenant_id, .user_key = key});
+        const auto* tenant_state = accessor.GetTenantState();
+        return tenant_state != nullptr &&
+               tenant_state->promotion_tasks.contains(key);
+    }
+
+    // std::nullopt when the key has no in-flight promotion task.
+    static std::optional<uint32_t> GetPromotionTaskExecutionFailuresForTesting(
+        MasterService* service, const TenantId& tenant_id,
+        const std::string& key) {
+        MasterServiceTestPeer::MetadataAccessorRO accessor(
+            service, MasterServiceTestPeer::ObjectIdentity{
+                         .tenant_id = tenant_id, .user_key = key});
+        const auto* tenant_state = accessor.GetTenantState();
+        if (tenant_state == nullptr) {
+            return std::nullopt;
+        }
+        auto it = tenant_state->promotion_tasks.find(key);
+        if (it == tenant_state->promotion_tasks.end()) {
+            return std::nullopt;
+        }
+        return it->second.execution_failures;
     }
 
     static bool PromotionAdmissionBlockedByPrimaryWriteForTesting(
         MasterService* service, const TenantId& tenant_id,
         const std::string& key) {
         const auto result =
-            service->TryPushPromotionQueue(MasterService::ObjectIdentity{
-                .tenant_id = tenant_id, .user_key = key});
-        return result == MasterService::PromotionQueueResult::kAlreadyInFlight;
+            MasterServiceTestPeer(*service).TryPushPromotionQueue(
+                MasterServiceTestPeer::ObjectIdentity{.tenant_id = tenant_id,
+                                                      .user_key = key});
+        return result ==
+               MasterServiceTestPeer::PromotionQueueResult::kAlreadyInFlight;
     }
 
     static void MarkReplicaCompleteForTesting(MasterService* service,
                                               const TenantId& tenant_id,
                                               const std::string& key,
                                               ReplicaID replica_id) {
-        MasterService::MetadataAccessorRW accessor(
-            service, MasterService::ObjectIdentity{.tenant_id = tenant_id,
-                                                   .user_key = key});
+        MasterServiceTestPeer::MetadataAccessorRW accessor(
+            service, MasterServiceTestPeer::ObjectIdentity{
+                         .tenant_id = tenant_id, .user_key = key});
         ASSERT_TRUE(accessor.Exists());
         auto* replica = accessor.Get().GetReplicaByID(replica_id);
         ASSERT_NE(replica, nullptr);
         replica->mark_complete();
     }
 
+    static std::unique_ptr<AllocatedBuffer> AllocateOnSegmentForTesting(
+        MasterService* service, const UUID& segment_id, size_t size) {
+        std::shared_ptr<BufferAllocatorBase> allocator;
+        {
+            auto segment_access =
+                MasterServiceTestPeer::SegmentManager(*service)
+                    .getSegmentAccess();
+            allocator = segment_access.GetAllocator(segment_id);
+        }
+        if (!allocator) {
+            return nullptr;
+        }
+        return allocator->allocate(size);
+    }
+
     static constexpr size_t kDefaultSegmentBase = 0x300000000;
 
     std::string WriteTenantQuotaPolicyFile(
@@ -175,6 +247,14 @@ class PromotionOnHitTest : public ::testing::Test {
         MasterService& service, const UUID& client_id, const std::string& key,
         int64_t size, const std::string& transport_endpoint,
         std::string tenant_id = std::string(TenantId::kDefaultValue)) {
+        // NotifyOffloadSuccess registers replicas only for a client with a
+        // mounted LOCAL_DISK segment, the way the real offload pipeline
+        // mounts before registering. Idempotent, so repeat injections for
+        // the same client are fine.
+        auto mount = service.MountLocalDiskSegment(client_id, true);
+        if (!mount.has_value()) {
+            return false;
+        }
         std::vector<OffloadTaskItem> tasks{
             OffloadTaskItem{.tenant_id = tenant_id, .key = key, .size = size}};
         StorageObjectMetadata sm;
@@ -423,8 +503,8 @@ TEST_F(PromotionOnHitTest,
     service->RemoveAll();
 }
 
-// PromotionObjectHeartbeat returns an empty task list when called against a
-// client that has no LocalDiskSegment registered.
+// An unknown Client is rejected by the liveness work gate before the
+// LocalDisk mailbox is consulted.
 TEST_F(PromotionOnHitTest, HeartbeatReturnsErrorForUnknownClient) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -434,10 +514,10 @@ TEST_F(PromotionOnHitTest, HeartbeatReturnsErrorForUnknownClient) {
     UUID unknown_client = generate_uuid();
     auto pending = service->PromotionObjectHeartbeat(unknown_client);
     ASSERT_FALSE(pending.has_value());
-    EXPECT_EQ(pending.error(), ErrorCode::SEGMENT_NOT_FOUND);
+    EXPECT_EQ(pending.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 }
 
-// PromotionAllocStart on a non-existent key returns OBJECT_NOT_FOUND.
+// An unknown Client is rejected before object metadata is consulted.
 TEST_F(PromotionOnHitTest, AllocStartUnknownKey) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -447,7 +527,7 @@ TEST_F(PromotionOnHitTest, AllocStartUnknownKey) {
     auto resp = service->PromotionAllocStart(generate_uuid(), "nonexistent",
                                              TenantId::Default(), 1024, {});
     ASSERT_FALSE(resp.has_value());
-    EXPECT_EQ(resp.error(), ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_EQ(resp.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 }
 
 TEST_F(PromotionOnHitTest, InvalidPrimaryEndCannotCompletePromotionReplica) {
@@ -592,6 +672,17 @@ TEST_F(PromotionOnHitTest, StalePromotionReplicaCleanupErasesTask) {
     ASSERT_TRUE(
         service->UnmountSegment(target_segment.id, target_id).has_value());
 
+    constexpr auto kCleanupTimeout = std::chrono::seconds(5);
+    constexpr auto kPollInterval = std::chrono::milliseconds(10);
+    const auto cleanup_deadline =
+        std::chrono::steady_clock::now() + kCleanupTimeout;
+    while (HasPromotionTaskForTesting(service.get(), TenantId::Default(),
+                                      "k_cold") &&
+           std::chrono::steady_clock::now() < cleanup_deadline) {
+        std::this_thread::sleep_for(kPollInterval);
+    }
+    ASSERT_FALSE(HasPromotionTaskForTesting(service.get(), TenantId::Default(),
+                                            "k_cold"));
     EXPECT_EQ(GetPromotionInFlightForTesting(service.get()), 0u);
     EXPECT_EQ(metrics.get_promotion_cancelled() - cancelled_before, 1);
     auto pending = service->PromotionObjectHeartbeat(holder_id);
@@ -612,7 +703,7 @@ TEST_F(PromotionOnHitTest, StalePromotionReplicaCleanupErasesTask) {
     service->RemoveAll();
 }
 
-// NotifyPromotionSuccess on a non-existent key returns OBJECT_NOT_FOUND.
+// An unknown Client is rejected before promotion metadata is consulted.
 TEST_F(PromotionOnHitTest, NotifyUnknownKey) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -623,7 +714,7 @@ TEST_F(PromotionOnHitTest, NotifyUnknownKey) {
     auto resp = service->NotifyPromotionSuccess(client_id, "nonexistent",
                                                 TenantId::Default());
     ASSERT_FALSE(resp.has_value());
-    EXPECT_EQ(resp.error(), ErrorCode::OBJECT_NOT_FOUND);
+    EXPECT_EQ(resp.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 }
 
 // Concurrent readers racing into TryPushPromotionQueue must dedupe to a
@@ -1075,6 +1166,10 @@ TEST_F(PromotionOnHitTest, HeartbeatBoundedBatchPreservesLeftovers) {
 TEST_F(PromotionOnHitTest, ReaperPopsStagedMemoryReplicaOnExpiry) {
     MasterServiceConfig config;
     config.enable_offload = true;
+    config.enable_multi_tenants = true;
+    config.tenant_quota_connector_type = "file";
+    config.tenant_quota_connector_uri =
+        WriteTenantQuotaPolicyFile({{TenantId::Default().value(), 4096}});
     config.promotion_on_hit = true;
     config.promotion_admission_threshold = 1;
     config.default_kv_lease_ttl = 2000;
@@ -1103,6 +1198,9 @@ TEST_F(PromotionOnHitTest, ReaperPopsStagedMemoryReplicaOnExpiry) {
     auto alloc = service->PromotionAllocStart(ctx.client_id, "k_cold",
                                               TenantId::Default(), 1024, {});
     ASSERT_TRUE(alloc.has_value());
+    ASSERT_EQ(
+        service->GetTenantQuotaSnapshot(TenantId::Default())->charged_bytes,
+        1024);
 
     // After AllocStart, the DRAM allocator must have committed bytes for
     // the staged PROCESSING MEMORY replica.
@@ -1134,6 +1232,8 @@ TEST_F(PromotionOnHitTest, ReaperPopsStagedMemoryReplicaOnExpiry) {
         << "be freed back to the DRAM allocator. If this fires, the "
         << "reaper is not popping the staged replica and the buffer "
         << "leaks until the object itself is removed or evicted.";
+    EXPECT_EQ(
+        service->GetTenantQuotaSnapshot(TenantId::Default())->charged_bytes, 0);
 
     // NotifyPromotionSuccess for a reaped task must not commit anything
     // and must return REPLICA_IS_NOT_READY (the task entry is gone, so
@@ -1386,6 +1486,89 @@ TEST_F(PromotionOnHitTest, NotifySuccessDecrementsCounter) {
     service->RemoveAll();
 }
 
+TEST_F(PromotionOnHitTest, TenantQuotaChargesAtAllocStartAndSettlesLifecycle) {
+    const TenantId tenant_id("tenant-a");
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.enable_multi_tenants = true;
+    config.tenant_quota_connector_type = "file";
+    config.tenant_quota_connector_uri =
+        WriteTenantQuotaPolicyFile({{tenant_id.value(), 4096}});
+    config.promotion_on_hit = true;
+    config.promotion_admission_threshold = 1;
+    config.default_kv_lease_ttl = 2000;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto seg =
+        PrepareSegment(*service, "seg_quota", kDefaultSegmentBase, seg_size);
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, seg.client_id, "success", 1024,
+                                       seg.segment_name, tenant_id.value()));
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, seg.client_id, "failure", 1024,
+                                       seg.segment_name, tenant_id.value()));
+
+    ASSERT_TRUE(service->GetReplicaList("success", tenant_id));
+    ASSERT_TRUE(service->PromotionAllocStart(seg.client_id, "success",
+                                             tenant_id, 1024, {}));
+    ASSERT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 1024);
+    ASSERT_TRUE(
+        service->NotifyPromotionSuccess(seg.client_id, "success", tenant_id));
+    EXPECT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 1024);
+
+    ASSERT_TRUE(service->GetReplicaList("failure", tenant_id));
+    ASSERT_TRUE(service->PromotionAllocStart(seg.client_id, "failure",
+                                             tenant_id, 1024, {}));
+    ASSERT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 2048);
+    ASSERT_TRUE(
+        service->NotifyPromotionFailure(seg.client_id, "failure", tenant_id));
+    EXPECT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 1024);
+
+    ASSERT_TRUE(service->Remove("success", tenant_id, /*force=*/true));
+    EXPECT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes, 0);
+    service->RemoveAll();
+}
+
+TEST_F(PromotionOnHitTest, UpsertStartRejectsActivePromotionTask) {
+    const TenantId tenant_id("tenant-a");
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.enable_multi_tenants = true;
+    config.tenant_quota_connector_type = "file";
+    config.tenant_quota_connector_uri =
+        WriteTenantQuotaPolicyFile({{tenant_id.value(), 4096}});
+    config.promotion_on_hit = true;
+    config.promotion_admission_threshold = 1;
+    config.default_kv_lease_ttl = 2000;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    constexpr uint64_t object_size = 1024;
+    auto seg =
+        PrepareSegment(*service, "seg_quota", kDefaultSegmentBase, seg_size);
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, seg.client_id, "key",
+                                       object_size, seg.segment_name,
+                                       tenant_id.value()));
+
+    ASSERT_TRUE(service->GetReplicaList("key", tenant_id));
+    ASSERT_TRUE(service->PromotionAllocStart(seg.client_id, "key", tenant_id,
+                                             object_size, {}));
+    ASSERT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes,
+              object_size);
+
+    ReplicateConfig replicate_config;
+    replicate_config.replica_num = 1;
+    auto upsert = service->UpsertStart(seg.client_id, "key", tenant_id,
+                                       object_size, replicate_config);
+    ASSERT_FALSE(upsert.has_value());
+    EXPECT_EQ(upsert.error(), ErrorCode::OBJECT_HAS_REPLICATION_TASK);
+
+    ASSERT_TRUE(
+        service->NotifyPromotionSuccess(seg.client_id, "key", tenant_id));
+    EXPECT_EQ(service->GetTenantQuotaSnapshot(tenant_id)->charged_bytes,
+              object_size);
+    service->RemoveAll();
+}
+
 // PromotionAllocStart must reject when the in-flight task has been
 // reaped between the holder's heartbeat and the AllocStart RPC arriving
 // (e.g. client stall past put_start_release_timeout_sec_). Without the
@@ -1480,10 +1663,11 @@ TEST_F(PromotionOnHitTest, NotifyRejectsNonHolder) {
                                               TenantId::Default(), 1024, {});
     ASSERT_TRUE(alloc.has_value());
 
-    // An unrelated client tries to Notify. Must be rejected as
-    // INVALID_PARAMS so the staged replica stays PROCESSING.
+    // A live but unrelated client reaches the holder check and is rejected,
+    // so the staged replica stays PROCESSING.
     UUID intruder_id = generate_uuid();
     ASSERT_NE(intruder_id, holder.client_id);
+    ASSERT_TRUE(service->MountLocalDiskSegment(intruder_id, true).has_value());
     auto bad_notify = service->NotifyPromotionSuccess(intruder_id, "k_cold",
                                                       TenantId::Default());
     ASSERT_FALSE(bad_notify.has_value())
@@ -1528,6 +1712,13 @@ TEST_F(PromotionOnHitTest, NotifyRejectsNonHolder) {
 // be silently dropped until reaper TTL if Notify-Failure didn't
 // fast-release. The TTL is set high enough here that any test pass
 // can be attributed to the explicit release, not to reaper expiry.
+//
+// Note: failure also re-records the failed key as a retry candidate
+// (transient execution errors are retried, not dropped). With queue_limit=1
+// the retried key and a fresh admission on another key race for the freed
+// slot; the assertions below accept either winner — what they must NOT
+// accept is an undeliverable heartbeat, which is what a saturated slot
+// would produce.
 TEST_F(PromotionOnHitTest, NotifyFailureReleasesStateImmediately) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -1554,6 +1745,7 @@ TEST_F(PromotionOnHitTest, NotifyFailureReleasesStateImmediately) {
 
     auto& mm = MasterMetricManager::instance();
     const int64_t failed_pre = mm.get_promotion_failed();
+    const int64_t recorded_pre = mm.get_promotion_candidate_recorded();
 
     // Admit + stage k_a. promotion_in_flight_ goes 0 -> 1.
     {
@@ -1580,6 +1772,12 @@ TEST_F(PromotionOnHitTest, NotifyFailureReleasesStateImmediately) {
         << "legitimate holder must succeed; error=" << failure.error();
     EXPECT_EQ(mm.get_promotion_failed() - failed_pre, 1)
         << "holder-reported failure must bump promotion_failed";
+    // The failure must also re-record a retry candidate for k_a (metric
+    // moves synchronously inside NotifyPromotionFailure; the background
+    // retry loop can only consume the candidate, never un-record it).
+    EXPECT_EQ(mm.get_promotion_candidate_recorded() - recorded_pre, 1)
+        << "NotifyPromotionFailure must re-record k_a as a retry candidate "
+        << "so transient execution errors are retried, not dropped";
 
     // The staged buffer must be freed back to the DRAM allocator. If
     // this fires, NotifyPromotionFailure did not pop the staged replica
@@ -1592,20 +1790,31 @@ TEST_F(PromotionOnHitTest, NotifyFailureReleasesStateImmediately) {
         << "to the allocator; otherwise it leaks until the object is "
         << "removed or evicted.";
 
-    // The slot must be freed: a second admission on a different key must
-    // succeed even though queue_limit=1. Without the failure-side
-    // decrement the cap would stay saturated until reaper TTL.
+    // The slot must be freed. Two outcomes prove it, and which one occurs
+    // depends on a benign race with the eviction thread's retry loop:
+    //   (a) k_b's read admits k_b while the freed slot is still open, or
+    //   (b) k_a — re-recorded as a retry candidate by the failure above —
+    //       is re-admitted first, so k_b is cap-rejected and becomes a
+    //       candidate itself.
+    // Either way the heartbeat must deliver exactly one task (queue_limit=1)
+    // and it must be one of the two keys; before the fast-release fix the
+    // slot would have stayed saturated and the heartbeat would be empty.
     {
         auto r = service->GetReplicaList("k_b", TenantId::Default());
         ASSERT_TRUE(r.has_value());
     }
     auto heartbeat = service->PromotionObjectHeartbeat(seg.client_id);
     ASSERT_TRUE(heartbeat.has_value());
-    EXPECT_EQ(CountPromotionTask(*heartbeat, "k_b"), 1u)
-        << "k_b admission must succeed after k_a's failure released the "
-        << "slot. If this fires, NotifyPromotionFailure did not decrement "
-        << "promotion_in_flight_, and transient client-side errors "
-        << "would saturate the queue limit for the full reaper TTL.";
+    ASSERT_EQ(heartbeat->size(), 1u)
+        << "after k_a's failure released the slot, exactly one promotion "
+        << "must be deliverable (queue_limit=1); an empty result means "
+        << "NotifyPromotionFailure did not decrement promotion_in_flight_, "
+        << "and transient client-side errors would saturate the queue "
+        << "limit for the full reaper TTL";
+    const std::string& winner = heartbeat->front().key;
+    EXPECT_TRUE(winner == "k_a" || winner == "k_b")
+        << "delivered task must be the retried k_a or the newly admitted "
+        << "k_b, got: " << winner;
 
     // Idempotency: repeated failure notification on the same key must be
     // safe (return OK without underflowing the counter).
@@ -1618,6 +1827,160 @@ TEST_F(PromotionOnHitTest, NotifyFailureReleasesStateImmediately) {
     service->RemoveAll();
 }
 
+// NotifyPromotionFailure must re-record a retry candidate for the failed
+// key so transient execution errors (DRAM pressure at AllocStart, TE write
+// flake, SSD throttle) are retried by the eviction-thread retry loop rather
+// than silently dropped. The re-admission can be driven by the background
+// retry loop or by an explicit scan — the final state is identical either
+// way: candidate consumed, key re-queued for the holder.
+TEST_F(PromotionOnHitTest, NotifyFailureRecordsCandidateAndRetries) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.promotion_on_hit = true;
+    config.promotion_admission_threshold = 1;
+    config.default_kv_lease_ttl = 5000;
+    config.put_start_release_timeout_sec = 300;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto seg = PrepareSegment(*service, "seg_a", kDefaultSegmentBase, seg_size);
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, seg.client_id, "k_a", 1024,
+                                       seg.segment_name));
+
+    auto& mm = MasterMetricManager::instance();
+    const int64_t recorded_pre = mm.get_promotion_candidate_recorded();
+
+    {
+        auto r = service->GetReplicaList("k_a", TenantId::Default());
+        ASSERT_TRUE(r.has_value());
+    }
+    auto alloc = service->PromotionAllocStart(seg.client_id, "k_a",
+                                              TenantId::Default(), 1024, {});
+    ASSERT_TRUE(alloc.has_value());
+
+    // Holder reports failure after a successful AllocStart (simulating an
+    // SSD read error / TE write flake past the staging point).
+    auto failure = service->NotifyPromotionFailure(seg.client_id, "k_a",
+                                                   TenantId::Default());
+    ASSERT_TRUE(failure.has_value());
+    EXPECT_EQ(mm.get_promotion_candidate_recorded() - recorded_pre, 1)
+        << "NotifyPromotionFailure must re-record a retry candidate";
+
+    // Whether the eviction thread's retry loop or this explicit scan wins
+    // the race to re-admit, the resulting state is identical: the candidate
+    // is consumed and k_a is queued again for the holder.
+    ResetCandidateBackoffsForTesting(service.get());
+    RunPromotionCandidateRetryForTesting(service.get());
+    EXPECT_EQ(GetPromotionInFlightForTesting(service.get()), 1u)
+        << "k_a must be re-admitted after its transient failure";
+    EXPECT_EQ(
+        CountPromotionCandidatesForTesting(service.get(), TenantId::Default()),
+        0u)
+        << "the re-admitted candidate must be consumed";
+
+    auto heartbeat = service->PromotionObjectHeartbeat(seg.client_id);
+    ASSERT_TRUE(heartbeat.has_value());
+    ASSERT_EQ(heartbeat->size(), 1u);
+    EXPECT_EQ(heartbeat->front().key, "k_a");
+
+    service->RemoveAll();
+}
+
+// A persistently-failing key (e.g. a broken SSD file that still has a
+// LOCAL_DISK replica) must not re-record -> re-admit -> fail -> re-record
+// forever: each NotifyPromotionFailure re-records with execution_failures+1
+// (propagated candidate -> task at admission), and once the chain reaches
+// kMaxPromotionExecutionFailures the failure stops re-recording. The
+// give-up kills only the self-sustaining cycle — a genuine read afterwards
+// re-admits with a fresh count.
+TEST_F(PromotionOnHitTest, NotifyFailureGivesUpAfterMaxExecutionFailures) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.promotion_on_hit = true;
+    config.promotion_admission_threshold = 1;
+    config.default_kv_lease_ttl = 5000;
+    config.put_start_release_timeout_sec = 300;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t seg_size = 1024 * 1024 * 16;
+    auto seg = PrepareSegment(*service, "seg_a", kDefaultSegmentBase, seg_size);
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, seg.client_id, "k_a", 1024,
+                                       seg.segment_name));
+
+    auto& mm = MasterMetricManager::instance();
+    const int64_t recorded_pre = mm.get_promotion_candidate_recorded();
+    const int64_t gave_up_pre = mm.get_promotion_execution_gave_up();
+
+    // First admission is driven by a real read (fresh chain, count 0).
+    {
+        auto r = service->GetReplicaList("k_a", TenantId::Default());
+        ASSERT_TRUE(r.has_value());
+    }
+
+    // Fail kMaxPromotionExecutionFailures times. Each failure must re-record
+    // with an incremented count, and each re-admission must show the count
+    // propagated across the candidate's consumption. The background eviction
+    // thread may win the re-admission race against the explicit retry call —
+    // assertions only target the resulting terminal state, which is
+    // identical under both interleavings.
+    for (uint32_t i = 1; i <= MaxPromotionExecutionFailuresForTesting(); ++i) {
+        ASSERT_EQ(GetPromotionInFlightForTesting(service.get()), 1u)
+            << "chain must be in-flight at iteration " << i;
+        EXPECT_EQ(GetPromotionTaskExecutionFailuresForTesting(
+                      service.get(), TenantId::Default(), "k_a"),
+                  std::optional<uint32_t>(i - 1))
+            << "execution_failures must propagate candidate -> task";
+        auto alloc = service->PromotionAllocStart(
+            seg.client_id, "k_a", TenantId::Default(), 1024, {});
+        ASSERT_TRUE(alloc.has_value());
+        auto failure = service->NotifyPromotionFailure(seg.client_id, "k_a",
+                                                       TenantId::Default());
+        ASSERT_TRUE(failure.has_value());
+        EXPECT_EQ(mm.get_promotion_candidate_recorded() - recorded_pre,
+                  static_cast<int64_t>(i))
+            << "failure " << i << " must re-record (still below the bound)";
+        ResetCandidateBackoffsForTesting(service.get());
+        RunPromotionCandidateRetryForTesting(service.get());
+    }
+
+    // The next failure hits the bound: no re-record, no re-admission.
+    ASSERT_EQ(GetPromotionInFlightForTesting(service.get()), 1u);
+    EXPECT_EQ(
+        GetPromotionTaskExecutionFailuresForTesting(service.get(),
+                                                    TenantId::Default(), "k_a"),
+        std::optional<uint32_t>(MaxPromotionExecutionFailuresForTesting()));
+    auto alloc = service->PromotionAllocStart(seg.client_id, "k_a",
+                                              TenantId::Default(), 1024, {});
+    ASSERT_TRUE(alloc.has_value());
+    auto failure = service->NotifyPromotionFailure(seg.client_id, "k_a",
+                                                   TenantId::Default());
+    ASSERT_TRUE(failure.has_value());
+    EXPECT_EQ(mm.get_promotion_candidate_recorded() - recorded_pre,
+              static_cast<int64_t>(MaxPromotionExecutionFailuresForTesting()))
+        << "the bound-crossing failure must NOT re-record";
+    EXPECT_EQ(mm.get_promotion_execution_gave_up() - gave_up_pre, 1)
+        << "give-up must bump promotion_execution_gave_up";
+    EXPECT_EQ(
+        CountPromotionCandidatesForTesting(service.get(), TenantId::Default()),
+        0u);
+    EXPECT_EQ(RunPromotionCandidateRetryForTesting(service.get()), 0u);
+    EXPECT_EQ(GetPromotionInFlightForTesting(service.get()), 0u)
+        << "the self-sustaining cycle must be dead";
+
+    // Give-up kills only the self-sustaining cycle: a genuine read re-admits
+    // with a fresh chain (count 0).
+    {
+        auto r = service->GetReplicaList("k_a", TenantId::Default());
+        ASSERT_TRUE(r.has_value());
+    }
+    EXPECT_EQ(GetPromotionInFlightForTesting(service.get()), 1u);
+    EXPECT_EQ(GetPromotionTaskExecutionFailuresForTesting(
+                  service.get(), TenantId::Default(), "k_a"),
+              std::optional<uint32_t>(0u));
+
+    service->RemoveAll();
+}
+
 // NotifyPromotionFailure must reject calls from a client that is not the
 // holder. Without this gate, any client knowing the key could prematurely
 // release a legitimate in-flight promotion's master state and free the
@@ -1649,6 +2012,7 @@ TEST_F(PromotionOnHitTest, NotifyFailureRejectsNonHolder) {
     // Intruder calls Failure with the wrong client_id.
     UUID intruder_id = generate_uuid();
     ASSERT_NE(intruder_id, holder.client_id);
+    ASSERT_TRUE(service->MountLocalDiskSegment(intruder_id, true).has_value());
     auto bad_failure = service->NotifyPromotionFailure(intruder_id, "k_cold",
                                                        TenantId::Default());
     ASSERT_FALSE(bad_failure.has_value())
@@ -1699,6 +2063,7 @@ TEST_F(PromotionOnHitTest, AllocStartRejectsNonHolder) {
 
     UUID intruder_id = generate_uuid();
     ASSERT_NE(intruder_id, holder.client_id);
+    ASSERT_TRUE(service->MountLocalDiskSegment(intruder_id, true).has_value());
     auto bad_alloc = service->PromotionAllocStart(
         intruder_id, "k_cold", TenantId::Default(), 1024, {});
     ASSERT_FALSE(bad_alloc.has_value())
@@ -1807,7 +2172,8 @@ TEST_F(PromotionOnHitTest, ClientExpiryClearsPromotionTask) {
     // ClearInvalidHandles, not from the promotion-task reaper.
     config.put_start_release_timeout_sec = 300;
     // Short client TTL so expiration is fast.
-    config.client_live_ttl_sec = 1;
+    config.client_active_ttl_sec = 1;
+    config.client_suspicion_ttl_sec = 1;
     auto service = std::make_unique<MasterService>(config);
 
     constexpr size_t seg_size = 1024 * 1024 * 16;
@@ -1829,22 +2195,8 @@ TEST_F(PromotionOnHitTest, ClientExpiryClearsPromotionTask) {
     // different-shard admission must be rejected right now.
     auto second_holder = PrepareSegment(
         *service, "seg_b", kDefaultSegmentBase + seg_size, seg_size);
-    // Promote second_holder into ok_client_ via ReMountSegment so its
-    // LOCAL_DISK replicas survive any ClearInvalidHandles run triggered
-    // by the first holder's expiry. MountSegment alone does not register
-    // the client as alive (only ReMountSegment does), and
-    // CleanupStaleHandles uses ok_client_ to decide which LOCAL_DISK
-    // replicas to erase — without this, second_holder's k_other replica
-    // would be wiped alongside the first holder's k_cold replica when
-    // ClearInvalidHandles runs.
-    {
-        Segment seg_b =
-            MakeSegment("seg_b", kDefaultSegmentBase + seg_size, seg_size);
-        seg_b.id = second_holder.segment_id;
-        std::vector<Segment> segs{seg_b};
-        auto remount = service->ReMountSegment(segs, second_holder.client_id);
-        ASSERT_TRUE(remount.has_value()) << "ReMount failed";
-    }
+    // MountSegment and MountLocalDiskSegment establish Active liveness; no
+    // ReMountSegment is needed for stale cleanup to retain this holder.
     ASSERT_TRUE(InjectLocalDiskReplica(*service, second_holder.client_id,
                                        "k_other", 1024,
                                        second_holder.segment_name));
@@ -2105,9 +2457,7 @@ TEST_F(PromotionOnHitTest, RemoveAllErasesPromotionTask) {
 }
 
 // BatchRemove normal-completion path on a key with an in-flight
-// PromotionTask must drop the task entry. ReMountSegment registers the
-// holder in ok_client_ so CleanupStaleHandles returns false and
-// BatchRemove takes the non-stale branch.
+// PromotionTask must drop the task entry while its holder remains Active.
 TEST_F(PromotionOnHitTest, BatchRemoveErasesPromotionTask) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -2121,13 +2471,6 @@ TEST_F(PromotionOnHitTest, BatchRemoveErasesPromotionTask) {
     constexpr size_t seg_size = 1024 * 1024 * 16;
     auto holder =
         PrepareSegment(*service, "seg_a", kDefaultSegmentBase, seg_size);
-    {
-        Segment seg_a = MakeSegment("seg_a", kDefaultSegmentBase, seg_size);
-        seg_a.id = holder.segment_id;
-        std::vector<Segment> segs{seg_a};
-        auto remount = service->ReMountSegment(segs, holder.client_id);
-        ASSERT_TRUE(remount.has_value()) << "ReMount failed";
-    }
     ASSERT_TRUE(InjectLocalDiskReplica(*service, holder.client_id, "k_first",
                                        1024, holder.segment_name));
     ASSERT_TRUE(InjectLocalDiskReplica(*service, holder.client_id, "k_second",
@@ -2169,11 +2512,8 @@ TEST_F(PromotionOnHitTest, BatchRemoveErasesPromotionTask) {
     service->RemoveAll(/*force=*/true);
 }
 
-// BatchRemove stale-handle path on a key with an in-flight
-// PromotionTask must drop the task entry. The holder is mounted via
-// PrepareSegment only (no ReMount), so its client is absent from
-// ok_client_; BatchRemove's CleanupStaleHandles then erases the
-// LOCAL_DISK replica and the stale-handle branch fires.
+// BatchRemove stale-handle path on a key with an in-flight PromotionTask must
+// drop the task entry after its holder becomes Offline.
 TEST_F(PromotionOnHitTest, BatchRemoveStaleHandleErasesPromotionTask) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -2203,6 +2543,8 @@ TEST_F(PromotionOnHitTest, BatchRemoveStaleHandleErasesPromotionTask) {
         EXPECT_EQ(CountPromotionTask(*pending, "k_first"), 1u);
     }
 
+    MarkClientOfflineForTesting(service.get(), holder.client_id);
+
     auto results =
         service->BatchRemove({"k_first"}, TenantId::Default(), /*force=*/true);
     ASSERT_EQ(results.size(), 1u);
@@ -2216,14 +2558,6 @@ TEST_F(PromotionOnHitTest, BatchRemoveStaleHandleErasesPromotionTask) {
 
     auto second_holder = PrepareSegment(
         *service, "seg_b", kDefaultSegmentBase + seg_size, seg_size);
-    {
-        Segment seg_b =
-            MakeSegment("seg_b", kDefaultSegmentBase + seg_size, seg_size);
-        seg_b.id = second_holder.segment_id;
-        std::vector<Segment> segs{seg_b};
-        auto remount = service->ReMountSegment(segs, second_holder.client_id);
-        ASSERT_TRUE(remount.has_value()) << "ReMount failed";
-    }
     ASSERT_TRUE(InjectLocalDiskReplica(*service, second_holder.client_id,
                                        "k_second", 1024,
                                        second_holder.segment_name));
@@ -2368,6 +2702,50 @@ TEST_F(PromotionOnHitTest, MetricsRejectionCountersIncrementOnGateMiss) {
     wm_service->RemoveAll();
 }
 
+TEST_F(PromotionOnHitTest, WatermarkUsesAllocatorStateAfterMetricsReset) {
+    MasterServiceConfig config;
+    config.enable_offload = true;
+    config.promotion_on_hit = true;
+    config.promotion_admission_threshold = 1;
+    config.eviction_high_watermark_ratio = 0.5;
+    config.default_kv_lease_ttl = 2000;
+    auto service = std::make_unique<MasterService>(config);
+
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kAllocationSize = 12 * 1024 * 1024;
+    const std::string segment_name = "allocator_watermark_segment";
+    auto segment = PrepareSegment(*service, segment_name, kDefaultSegmentBase,
+                                  kSegmentSize);
+    auto allocated = AllocateOnSegmentForTesting(
+        service.get(), segment.segment_id, kAllocationSize);
+    ASSERT_NE(allocated, nullptr);
+    ASSERT_TRUE(InjectLocalDiskReplica(*service, segment.client_id,
+                                       "allocator_watermark_key", 1024,
+                                       segment.segment_name));
+
+    auto& metrics = MasterMetricManager::instance();
+    metrics.reset_allocated_mem_size();
+    metrics.reset_total_mem_capacity();
+    metrics.reset_segment_allocated_mem_size(segment_name);
+    metrics.reset_segment_total_mem_capacity(segment_name);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), 0);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), 0);
+
+    const int64_t rejected_before = metrics.get_promotion_rejected_watermark();
+    auto get_result =
+        service->GetReplicaList("allocator_watermark_key", TenantId::Default());
+    EXPECT_TRUE(get_result.has_value());
+    EXPECT_EQ(metrics.get_promotion_rejected_watermark() - rejected_before, 1);
+
+    // Restore the observable gauges before normal teardown. The business
+    // assertion above intentionally reset them, but allocator and service
+    // destructors still emit their matching decrements.
+    metrics.inc_allocated_mem_size(segment_name, kAllocationSize);
+    metrics.inc_total_mem_capacity(segment_name, kSegmentSize);
+    allocated.reset();
+    service->RemoveAll();
+}
+
 TEST_F(PromotionOnHitTest, AdmissionFrequencyIsTenantScoped) {
     MasterServiceConfig config;
     config.enable_offload = true;
@@ -2622,9 +3000,17 @@ TEST_F(PromotionOnHitTest, RetryCandidate_CapRejectedThenQueuedOnRetry) {
         CountPromotionCandidatesForTesting(service.get(), TenantId::Default()),
         1u);
 
-    auto failed = service->NotifyPromotionFailure(seg.client_id, "k_busy",
-                                                  TenantId::Default());
-    ASSERT_TRUE(failed.has_value());
+    // Release the slot via a *successful* promotion of k_busy. Using
+    // NotifyPromotionFailure here would change the candidate set: failure
+    // deliberately re-records a retry candidate for the failed key
+    // (transient execution errors are retried, not dropped), so k_busy
+    // would then compete with k_retry for the freed slot.
+    auto alloc = service->PromotionAllocStart(seg.client_id, "k_busy",
+                                              TenantId::Default(), 1024, {});
+    ASSERT_TRUE(alloc.has_value());
+    auto done = service->NotifyPromotionSuccess(seg.client_id, "k_busy",
+                                                TenantId::Default());
+    ASSERT_TRUE(done.has_value());
     ASSERT_EQ(GetPromotionInFlightForTesting(service.get()), 0u);
 
     ResetCandidateBackoffsForTesting(service.get());
@@ -2710,8 +3096,10 @@ TEST_F(PromotionOnHitTest, RetryCandidate_ExhaustedAfterMaxRetries) {
 
     // Drive retries; each scan increments retry_count until exhausted.
     // Reset backoff timestamps before each scan so wall-clock time doesn't
-    // gate retries and the loop completes without sleeping.
-    for (int i = 0; i <= 10; ++i) {
+    // gate retries and the loop completes without sleeping. The scan count
+    // is derived from kPromotionCandidateMaxRetries (one scan to reach the
+    // limit, one more to observe it and erase).
+    for (uint32_t i = 0; i <= MaxPromotionCandidateRetriesForTesting(); ++i) {
         ResetCandidateBackoffsForTesting(service.get());
         RunPromotionCandidateRetryForTesting(service.get());
     }
diff --git a/mooncake-store/tests/pybind_client_test.cpp b/mooncake-store/tests/pybind_client_test.cpp
index c08a48a8e7..55f713ae14 100644
--- a/mooncake-store/tests/pybind_client_test.cpp
+++ b/mooncake-store/tests/pybind_client_test.cpp
@@ -2,18 +2,26 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <algorithm>
 #include <barrier>
 #include <chrono>
 #include <cstdio>
 #include <cstring>
+#include <filesystem>
 #include <fcntl.h>
 #include <limits>
 #include <memory>
+#include <optional>
 #include <random>
 #include <string>
 #include <thread>
 #include <unistd.h>
 
+#ifdef MOONCAKE_TEST_CUDA_H2D
+#include <cuda_runtime_api.h>
+#endif
+
+#include "config.h"
 #include "real_client.h"
 #include "test_server_helpers.h"
 
@@ -36,6 +44,50 @@ class GLogMuter {
     int original_log_level_;
 };
 
+class ScopedEnvVar {
+   public:
+    ScopedEnvVar(const char* name, const char* value) : name_(name) {
+        if (const char* previous = getenv(name)) previous_ = previous;
+        setenv(name, value, 1);
+    }
+
+    ~ScopedEnvVar() {
+        if (previous_) {
+            setenv(name_.c_str(), previous_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> previous_;
+};
+
+class ScopedMaxMrSize {
+   public:
+    explicit ScopedMaxMrSize(size_t max_mr_size)
+        : old_max_mr_size_(globalConfig().max_mr_size) {
+        globalConfig().max_mr_size = max_mr_size;
+    }
+
+    ~ScopedMaxMrSize() { globalConfig().max_mr_size = old_max_mr_size_; }
+
+   private:
+    size_t old_max_mr_size_;
+};
+
+TEST(TransportRegistrationLimitTest, ClassifiesProtocols) {
+    constexpr size_t kMaxMrSize = 64 * 1024 * 1024;
+    ScopedMaxMrSize limit(kMaxMrSize);
+
+    EXPECT_EQ(GetTransportRegistrationLimit("rdma"), std::nullopt);
+    EXPECT_EQ(GetTransportRegistrationLimit("tcp"), std::nullopt);
+    EXPECT_EQ(GetTransportRegistrationLimit("efa"), kMaxMrSize);
+    EXPECT_EQ(GetTransportRegistrationLimit("cxi"), kMaxMrSize);
+    EXPECT_TRUE(GetTransportRegistrationLimit("ub").has_value());
+}
+
 class RealClientTest : public ::testing::Test {
    protected:
     static void SetUpTestSuite() {
@@ -60,9 +112,11 @@ class RealClientTest : public ::testing::Test {
     void TearDown() override {
         if (py_client_) {
             py_client_->tearDownAll();
+            if (!ssd_path_.empty()) py_client_.reset();
         }
 
         master_.Stop();
+        if (!ssd_path_.empty()) std::filesystem::remove_all(ssd_path_);
     }
 
     std::shared_ptr<RealClient> py_client_;
@@ -70,6 +124,7 @@ class RealClientTest : public ::testing::Test {
     // In-proc master for tests
     mooncake::testing::InProcMaster master_;
     std::string master_address_;
+    std::string ssd_path_;
 
     void StartMasterAndSetupClient() {
         ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
@@ -117,6 +172,420 @@ class RealClientTest : public ::testing::Test {
     }
 };
 
+TEST_F(RealClientTest, BatchGetIntoUsesSelectedLocalDiskEndpoint) {
+    StartMasterAndSetupClient();
+
+    constexpr size_t object_size = 16;
+    auto make_local_disk = [object_size](const std::string& endpoint,
+                                         ReplicaStatus status) {
+        Replica::Descriptor replica;
+        LocalDiskDescriptor descriptor;
+        descriptor.client_id = generate_uuid();
+        descriptor.object_size = object_size;
+        descriptor.transport_endpoint = endpoint;
+        replica.descriptor_variant = std::move(descriptor);
+        replica.status = status;
+        return replica;
+    };
+
+    struct TestCase {
+        std::string name;
+        std::vector<Replica::Descriptor> replicas;
+        std::string expected_endpoint;
+    };
+    std::vector<TestCase> test_cases;
+    // SelectBestReplica currently chooses the last COMPLETE LOCAL_DISK
+    // descriptor. Both list orders make a first-vs-last mismatch observable.
+    test_cases.push_back(
+        {.name = "a_then_b",
+         .replicas = {make_local_disk("endpoint-a", ReplicaStatus::COMPLETE),
+                      make_local_disk("endpoint-b", ReplicaStatus::COMPLETE)},
+         .expected_endpoint = "endpoint-b"});
+    test_cases.push_back(
+        {.name = "b_then_a",
+         .replicas = {make_local_disk("endpoint-b", ReplicaStatus::COMPLETE),
+                      make_local_disk("endpoint-a", ReplicaStatus::COMPLETE)},
+         .expected_endpoint = "endpoint-a"});
+    test_cases.push_back(
+        {.name = "not_ready_then_complete",
+         .replicas = {make_local_disk("endpoint-not-ready",
+                                      ReplicaStatus::PROCESSING),
+                      make_local_disk("endpoint-complete",
+                                      ReplicaStatus::COMPLETE)},
+         .expected_endpoint = "endpoint-complete"});
+
+    for (auto& test_case : test_cases) {
+        SCOPED_TRACE(test_case.name);
+        std::vector<tl::expected<QueryResult, ErrorCode>> query_results;
+        query_results.emplace_back(QueryResult(
+            std::move(test_case.replicas),
+            std::chrono::steady_clock::now() + std::chrono::minutes(1)));
+
+        std::vector<char> destination(object_size);
+        std::string visited_endpoint;
+        // Stop at the offload RPC boundary after recording its destination.
+        // The injected error also prevents checksum verification of the
+        // intentionally untouched destination buffer.
+        auto local_disk_reader = [&visited_endpoint](
+                                     const std::string& endpoint,
+                                     RealClient::LocalDiskOffloadObjects&)
+            -> tl::expected<void, ErrorCode> {
+            visited_endpoint = endpoint;
+            return tl::make_unexpected(ErrorCode::RPC_FAIL);
+        };
+
+        std::vector<tl::expected<int64_t, ErrorCode>> results;
+        {
+            GLogMuter muter;
+            results = py_client_->batch_get_into_internal(
+                {"endpoint-selection-key"}, {destination.data()},
+                {destination.size()}, query_results, local_disk_reader);
+        }
+
+        EXPECT_EQ(visited_endpoint, test_case.expected_endpoint);
+        ASSERT_EQ(results.size(), 1);
+        ASSERT_FALSE(results[0].has_value());
+        EXPECT_EQ(results[0].error(), ErrorCode::RPC_FAIL);
+    }
+}
+
+TEST_F(RealClientTest, SessionRangesReadDfsAndPropagateShortRead) {
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar storage_backend("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR",
+                                 "distributed_storage_backend");
+    ScopedEnvVar local_buffer("MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES",
+                              "16777216");
+    ScopedEnvVar dfs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar dfs_shards("MOONCAKE_DFS_SHARD_COUNT", "1");
+    ScopedEnvVar dfs_capacity("MOONCAKE_DFS_SHARD_CAPACITY", "16777216");
+    ScopedEnvVar dfs_alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar dfs_eviction("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+    ScopedEnvVar dfs_deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar dfs_single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+    char path[] = "/tmp/mooncake_session_dfs_XXXXXX";
+    const char* created = mkdtemp(path);
+    ASSERT_NE(created, nullptr);
+    ssd_path_ = created;
+    ScopedEnvVar dfs_root("MOONCAKE_DFS_ROOT_DIR", ssd_path_.c_str());
+
+    ASSERT_TRUE(master_.Start(
+        InProcMasterConfigBuilder().set_default_kv_lease_ttl(1000).build()));
+    master_address_ = master_.master_address();
+    constexpr char kClientAddress[] = "localhost:17824";
+    ASSERT_EQ(
+        py_client_->setup_real(kClientAddress, "P2PHANDSHAKE", 16 * 1024 * 1024,
+                               16 * 1024 * 1024, "tcp", "", master_address_,
+                               nullptr, "", true, ssd_path_),
+        0);
+
+    constexpr size_t kObjectSize = 4096;
+    const std::string key = "session_dfs";
+    std::string source(kObjectSize, '\0');
+    for (size_t i = 0; i < source.size(); ++i) {
+        source[i] = static_cast<char>((i * 7) % 251);
+    }
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.dfs_replica_num = 1;
+    ASSERT_EQ(py_client_->put(key, source, config), 0);
+    ASSERT_EQ(py_client_->batch_replica_clear({key}, kClientAddress).size(), 1);
+
+    const auto replicas = py_client_->get_replica_desc(key);
+    ASSERT_EQ(replicas.size(), 1);
+    ASSERT_TRUE(replicas.front().is_dfs_replica());
+    const auto dfs_descriptor = replicas.front().get_dfs_descriptor();
+
+    std::string first(512, '\0');
+    std::string second(777, '\0');
+    ASSERT_EQ(py_client_->register_buffer(first.data(), first.size()), 0);
+    ASSERT_EQ(py_client_->register_buffer(second.data(), second.size()), 0);
+    ASSERT_EQ(py_client_->batch_get_session_start({key}), std::vector<int>{0});
+
+    auto client_buffer_allocator =
+        std::move(py_client_->client_buffer_allocator_);
+    auto results = py_client_->batch_get_into_multi_buffer_ranges(
+        {key}, {{first.data()}}, {{first.size()}}, {{127}});
+    ASSERT_EQ(results, std::vector<int>{static_cast<int>(
+                           toInt(ErrorCode::NO_AVAILABLE_HANDLE))});
+    py_client_->client_buffer_allocator_ = std::move(client_buffer_allocator);
+
+    results = py_client_->batch_get_into_multi_buffer_ranges(
+        {key}, {{first.data(), second.data()}}, {{first.size(), second.size()}},
+        {{127, 2048}});
+    ASSERT_EQ(results,
+              std::vector<int>{static_cast<int>(first.size() + second.size())});
+    EXPECT_EQ(first, source.substr(127, first.size()));
+    EXPECT_EQ(second, source.substr(2048, second.size()));
+
+    std::filesystem::resize_file(dfs_descriptor.file_path,
+                                 dfs_descriptor.offset + kObjectSize / 2);
+    results = py_client_->batch_get_into_multi_buffer_ranges(
+        {key}, {{first.data()}}, {{first.size()}}, {{0}});
+    ASSERT_EQ(results.size(), 1);
+    EXPECT_EQ(results[0], static_cast<int>(toInt(ErrorCode::FILE_READ_FAIL)));
+
+    EXPECT_EQ(py_client_->batch_get_session_end({key}), 0);
+    EXPECT_EQ(py_client_->unregister_buffer(first.data()), 0);
+    EXPECT_EQ(py_client_->unregister_buffer(second.data()), 0);
+}
+
+#ifdef MOONCAKE_TEST_CUDA_H2D
+TEST_F(RealClientTest, SessionRangesReadDfsIntoGpuUsesPinnedArena) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count == 0) {
+        GTEST_SKIP() << "CUDA device is unavailable";
+    }
+
+    ScopedEnvVar local_memcpy("MC_STORE_MEMCPY", "1");
+    ScopedEnvVar pinned_restore_arena(
+        "MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES", "1048576");
+    ScopedEnvVar enable_dfs("MOONCAKE_ENABLE_DFS", "1");
+    ScopedEnvVar storage_backend("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR",
+                                 "distributed_storage_backend");
+    ScopedEnvVar local_buffer("MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES",
+                              "16777216");
+    ScopedEnvVar dfs_adapter("MOONCAKE_DFS_FS_ADAPTER", "posix");
+    ScopedEnvVar dfs_shards("MOONCAKE_DFS_SHARD_COUNT", "1");
+    ScopedEnvVar dfs_capacity("MOONCAKE_DFS_SHARD_CAPACITY", "16777216");
+    ScopedEnvVar dfs_alignment("MOONCAKE_DFS_ALIGNMENT", "4096");
+    ScopedEnvVar dfs_eviction("MOONCAKE_DFS_EVICTION_ENABLED", "0");
+    ScopedEnvVar dfs_deferred_free("MOONCAKE_DFS_DEFERRED_FREE_SECONDS", "0");
+    ScopedEnvVar dfs_single_tenant("MOONCAKE_DFS_SINGLE_TENANT", "true");
+
+    char path[] = "/tmp/mooncake_session_dfs_gpu_XXXXXX";
+    const char* created = mkdtemp(path);
+    ASSERT_NE(created, nullptr);
+    ssd_path_ = created;
+    ScopedEnvVar dfs_root("MOONCAKE_DFS_ROOT_DIR", ssd_path_.c_str());
+
+    ASSERT_TRUE(master_.Start(
+        InProcMasterConfigBuilder().set_default_kv_lease_ttl(1000).build()));
+    master_address_ = master_.master_address();
+    constexpr char kClientAddress[] = "localhost:17825";
+    ASSERT_EQ(
+        py_client_->setup_real(kClientAddress, "P2PHANDSHAKE", 16 * 1024 * 1024,
+                               16 * 1024 * 1024, "tcp", "", master_address_,
+                               nullptr, "", true, ssd_path_),
+        0);
+
+    constexpr size_t kObjectSize = 4096;
+    constexpr size_t kSourceOffset = 257;
+    constexpr size_t kRangeSize = 1024;
+    const std::string key = "session_dfs_gpu";
+    std::vector<char> source(kObjectSize);
+    for (size_t i = 0; i < source.size(); ++i) {
+        source[i] = static_cast<char>(i % 251);
+    }
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.dfs_replica_num = 1;
+    ASSERT_EQ(py_client_->put(key, source, config), 0);
+    ASSERT_EQ(py_client_->batch_replica_clear({key}, kClientAddress).size(), 1);
+    const auto replicas = py_client_->get_replica_desc(key);
+    ASSERT_EQ(replicas.size(), 1);
+    ASSERT_TRUE(replicas.front().is_dfs_replica());
+    ASSERT_EQ(py_client_->batch_get_session_start({key}), std::vector<int>{0});
+
+    void* gpu_destination = nullptr;
+    ASSERT_EQ(cudaMalloc(&gpu_destination, kRangeSize), cudaSuccess);
+    bool registered = false;
+    auto cleanup = [this, &registered](void* ptr) {
+        if (registered) EXPECT_EQ(py_client_->unregister_buffer(ptr), 0);
+        EXPECT_EQ(cudaFree(ptr), cudaSuccess);
+    };
+    std::unique_ptr<void, decltype(cleanup)> gpu_owner(gpu_destination,
+                                                       cleanup);
+    ASSERT_EQ(py_client_->register_buffer(gpu_destination, kRangeSize), 0);
+    registered = true;
+
+    // Remove the fallback allocator so success proves that device-targeted DFS
+    // staging came from the pinned restore arena.
+    auto fallback_allocator = std::move(py_client_->client_buffer_allocator_);
+    auto results = py_client_->batch_get_into_multi_buffer_ranges(
+        {key}, {{gpu_destination}}, {{kRangeSize}}, {{kSourceOffset}});
+    py_client_->client_buffer_allocator_ = std::move(fallback_allocator);
+
+    ASSERT_EQ(results, std::vector<int>{static_cast<int>(kRangeSize)});
+    std::vector<char> actual(kRangeSize);
+    ASSERT_EQ(cudaMemcpy(actual.data(), gpu_destination, kRangeSize,
+                         cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_TRUE(std::equal(actual.begin(), actual.end(),
+                           source.begin() + kSourceOffset));
+    EXPECT_EQ(py_client_->batch_get_session_end({key}), 0);
+}
+
+TEST_F(RealClientTest, RangedSnapshotGpuReadBypassesNewerHotCacheValue) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count == 0) {
+        GTEST_SKIP() << "CUDA device is unavailable";
+    }
+
+    ScopedEnvVar local_memcpy("MC_STORE_MEMCPY", "1");
+    ScopedEnvVar cache_size("MC_STORE_LOCAL_HOT_CACHE_SIZE", "1048576");
+    ScopedEnvVar block_size("MC_STORE_LOCAL_HOT_BLOCK_SIZE", "4096");
+    ScopedEnvVar shared_cache("MC_STORE_LOCAL_HOT_CACHE_USE_SHM", "1");
+    ScopedEnvVar admission("MC_STORE_LOCAL_HOT_ADMISSION_THRESHOLD", "1");
+    StartMasterAndSetupClient();
+    const std::string key = "snapshot_gpu_hot_cache";
+    const std::string original(32, 'A');
+    const std::string replacement(32, 'B');
+    ASSERT_EQ(py_client_->put(key, std::span<const char>(original)), 0);
+    auto queries = py_client_->batch_query({key});
+    ASSERT_EQ(queries.size(), 1);
+    ASSERT_TRUE(queries[0].has_value());
+    PyClient::QueryResultCache snapshot;
+    snapshot.emplace(key, std::move(queries[0]));
+    ASSERT_EQ(py_client_->upsert(key, std::span<const char>(replacement)), 0);
+
+    // Populate the key-based cache with the new value after taking the old
+    // snapshot. Keep the read buffer alive until the async cache fill
+    // completes.
+    auto current = py_client_->get_buffer(key);
+    ASSERT_NE(current, nullptr);
+    ASSERT_EQ(std::string(static_cast<char*>(current->ptr()), current->size()),
+              replacement);
+    bool cache_ready = false;
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (py_client_->acquire_hot_cache(key).has_value()) {
+            ASSERT_TRUE(py_client_->release_hot_cache(key).has_value());
+            cache_ready = true;
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    ASSERT_TRUE(cache_ready);
+
+    void* destination = nullptr;
+    ASSERT_EQ(cudaMalloc(&destination, original.size()), cudaSuccess);
+    bool registered = false;
+    auto cleanup = [this, &registered](void* ptr) {
+        if (registered) EXPECT_EQ(py_client_->unregister_buffer(ptr), 0);
+        EXPECT_EQ(cudaFree(ptr), cudaSuccess);
+    };
+    std::unique_ptr<void, decltype(cleanup)> owner(destination, cleanup);
+    ASSERT_EQ(py_client_->register_buffer(destination, original.size()), 0);
+    registered = true;
+    EXPECT_EQ(py_client_->get_into_ranges_from_snapshot(
+                  {destination}, {{key}}, {{{0}}}, {{{0}}},
+                  {{{original.size()}}}, snapshot),
+              (std::vector<std::vector<std::vector<int64_t>>>{{{32}}}));
+    std::string actual(original.size(), '\0');
+    ASSERT_EQ(cudaMemcpy(actual.data(), destination, actual.size(),
+                         cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_EQ(actual, original);
+}
+
+TEST_F(RealClientTest, PinnedSsdRestoreReadsNonTailRangeIntoGpu) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count == 0) {
+        GTEST_SKIP() << "CUDA device is unavailable";
+    }
+
+    ScopedEnvVar local_memcpy("MC_STORE_MEMCPY", "1");
+    ScopedEnvVar heartbeat("MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS", "1");
+    ScopedEnvVar pinned_restore_arena(
+        "MC_STORE_PINNED_RESTORE_ARENA_SIZE_BYTES", "1048576");
+    ScopedEnvVar storage_backend("MOONCAKE_OFFLOAD_STORAGE_BACKEND_DESCRIPTOR",
+                                 "bucket_storage_backend");
+    ScopedEnvVar bucket_keys("MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT", "1");
+
+    char path[] = "/tmp/mooncake_ssd_pinned_restore_XXXXXX";
+    const char* created = mkdtemp(path);
+    ASSERT_NE(created, nullptr);
+    ssd_path_ = created;
+
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder()
+                                  .set_enable_offload(true)
+                                  .set_default_kv_lease_ttl(10)
+                                  .build()));
+    master_address_ = master_.master_address();
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17813", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024, "tcp", "",
+                               master_address_, nullptr, "", true, ssd_path_),
+        0);
+
+    constexpr size_t kObjectSize = 64 * 1024;
+    constexpr size_t kSourceOffset = 8 * 1024;
+    constexpr size_t kRangeSize = 16 * 1024;
+    static_assert(kSourceOffset + kRangeSize < kObjectSize);
+    std::vector<char> source(kObjectSize);
+    for (size_t i = 0; i < source.size(); ++i) {
+        source[i] = static_cast<char>(i % 251);
+    }
+    const std::string key = "pinned_ssd_non_tail_range";
+    ASSERT_EQ(py_client_->put(key, source), 0);
+
+    bool disk_ready = false;
+    const auto offload_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(10);
+    while (std::chrono::steady_clock::now() < offload_deadline && !disk_ready) {
+        for (const auto& replica : py_client_->get_replica_desc(key)) {
+            if (replica.is_local_disk_replica()) {
+                disk_ready = true;
+            }
+        }
+        if (!disk_ready)
+            std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    }
+    ASSERT_TRUE(disk_ready);
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    const auto clear_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    bool memory_cleared = false;
+    while (std::chrono::steady_clock::now() < clear_deadline) {
+        if (py_client_->batch_replica_clear({key}, "localhost:17813").size() ==
+            1) {
+            memory_cleared = true;
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(memory_cleared);
+
+    auto replicas = py_client_->get_replica_desc(key);
+    ASSERT_EQ(replicas.size(), 1);
+    ASSERT_TRUE(replicas.front().is_local_disk_replica());
+
+    void* gpu_destination = nullptr;
+    ASSERT_EQ(cudaMalloc(&gpu_destination, kRangeSize), cudaSuccess);
+    bool registered = false;
+    auto cleanup = [this, &registered](void* ptr) {
+        if (registered) {
+            EXPECT_EQ(py_client_->unregister_buffer(ptr), 0);
+        }
+        EXPECT_EQ(cudaFree(ptr), cudaSuccess);
+    };
+    std::unique_ptr<void, decltype(cleanup)> gpu_owner(gpu_destination,
+                                                       cleanup);
+    ASSERT_EQ(py_client_->register_buffer(gpu_destination, kRangeSize), 0);
+    registered = true;
+
+    const auto reads_before = py_client_->get_offload_rpc_read_count();
+    auto results =
+        py_client_->get_into_ranges({gpu_destination}, {{key}}, {{{0}}},
+                                    {{{kSourceOffset}}}, {{{kRangeSize}}});
+    ASSERT_EQ(results.size(), 1);
+    ASSERT_EQ(results[0].size(), 1);
+    ASSERT_EQ(results[0][0].size(), 1);
+    EXPECT_EQ(results[0][0][0], static_cast<int64_t>(kRangeSize));
+    EXPECT_EQ(py_client_->get_offload_rpc_read_count(), reads_before + 1);
+
+    std::vector<char> actual(kRangeSize);
+    ASSERT_EQ(cudaMemcpy(actual.data(), gpu_destination, kRangeSize,
+                         cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_TRUE(std::equal(actual.begin(), actual.end(),
+                           source.begin() + kSourceOffset));
+}
+#endif
+
 TEST_F(RealClientTest, AllocateAndMountSegmentAlignsAndUnmounts) {
     StartMasterAndSetupClient();
 
@@ -142,6 +611,95 @@ TEST_F(RealClientTest, AllocateAndMountSegmentAlignsAndUnmounts) {
     EXPECT_EQ(py_client_->unmountAndFreeSegment(segment_ids), 0);
 }
 
+TEST_F(RealClientTest, TcpSetupDoesNotSplitAtMaxMrSize) {
+    const size_t slab_size = facebook::cachelib::Slab::kSize;
+    ScopedMaxMrSize limit(2 * slab_size);
+
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()));
+    master_address_ = master_.master_address();
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17814", "P2PHANDSHAKE", 6 * slab_size,
+                               0, "tcp", "", master_address_),
+        0);
+
+    auto details = master_.service()->GetSegmentsDetailForAdmin();
+    ASSERT_TRUE(details.has_value());
+    ASSERT_EQ(details->size(), 1u);
+    EXPECT_EQ(details->front().size_bytes, 6 * slab_size);
+}
+
+TEST_F(RealClientTest, DynamicMountApisBalanceLimitedSegments) {
+    const size_t slab_size = facebook::cachelib::Slab::kSize;
+    ScopedMaxMrSize limit(4 * slab_size);
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()));
+    master_address_ = master_.master_address();
+    ASSERT_EQ(py_client_->setup_real("localhost:17815", "P2PHANDSHAKE", 0, 0,
+                                     "tcp", "", master_address_),
+              0);
+
+    std::vector<std::string> allocated_ids;
+    size_t allocated_size = 0;
+    ASSERT_EQ(py_client_->allocateAndMountSegment(
+                  6 * slab_size, "efa", "", allocated_ids, &allocated_size),
+              0);
+    ASSERT_EQ(allocated_ids.size(), 2u);
+
+    const std::string path = CreateTempSegmentFile(6 * slab_size);
+    ASSERT_FALSE(path.empty());
+    std::vector<std::string> mounted_ids;
+    ASSERT_EQ(py_client_->mountSegment(path, 0, 6 * slab_size, "efa", "",
+                                       mounted_ids),
+              0);
+    ASSERT_EQ(mounted_ids.size(), 2u);
+
+    auto details = master_.service()->GetSegmentsDetailForAdmin();
+    ASSERT_TRUE(details.has_value());
+    ASSERT_EQ(details->size(), 4u);
+    for (const auto& detail : *details) {
+        EXPECT_EQ(detail.size_bytes, 3 * slab_size);
+    }
+
+    EXPECT_EQ(py_client_->unmountAndFreeSegment(allocated_ids), 0);
+    EXPECT_EQ(py_client_->unmountSegment(mounted_ids), 0);
+    EXPECT_EQ(std::remove(path.c_str()), 0);
+}
+
+TEST_F(RealClientTest, DynamicMountApisDoNotSplitRdma) {
+    const size_t slab_size = facebook::cachelib::Slab::kSize;
+    ScopedMaxMrSize limit(4 * slab_size);
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()));
+    master_address_ = master_.master_address();
+    ASSERT_EQ(py_client_->setup_real("localhost:17816", "P2PHANDSHAKE", 0, 0,
+                                     "tcp", "", master_address_),
+              0);
+
+    std::vector<std::string> allocated_ids;
+    size_t allocated_size = 0;
+    ASSERT_EQ(py_client_->allocateAndMountSegment(
+                  6 * slab_size, "rdma", "", allocated_ids, &allocated_size),
+              0);
+    ASSERT_EQ(allocated_ids.size(), 1u);
+
+    const std::string path = CreateTempSegmentFile(6 * slab_size);
+    ASSERT_FALSE(path.empty());
+    std::vector<std::string> mounted_ids;
+    ASSERT_EQ(py_client_->mountSegment(path, 0, 6 * slab_size, "rdma", "",
+                                       mounted_ids),
+              0);
+    ASSERT_EQ(mounted_ids.size(), 1u);
+
+    auto details = master_.service()->GetSegmentsDetailForAdmin();
+    ASSERT_TRUE(details.has_value());
+    ASSERT_EQ(details->size(), 2u);
+    for (const auto& detail : *details) {
+        EXPECT_EQ(detail.size_bytes, 6 * slab_size);
+    }
+
+    EXPECT_EQ(py_client_->unmountAndFreeSegment(allocated_ids), 0);
+    EXPECT_EQ(py_client_->unmountSegment(mounted_ids), 0);
+    EXPECT_EQ(std::remove(path.c_str()), 0);
+}
+
 TEST_F(RealClientTest, AllocateAndMountSegmentRejectsOverflowSize) {
     StartMasterAndSetupClient();
 
@@ -308,6 +866,72 @@ TEST_F(RealClientTest, GetIntoAcceptsSubrangeOfLocalRegisteredBuffer) {
     EXPECT_EQ(std::string(dst, test_data.size()), test_data);
 }
 
+TEST_F(RealClientTest, RangedSnapshotPreservesPayloadAcrossSameSizeUpsert) {
+    StartMasterAndSetupClient();
+    const std::string key = "ranged_snapshot_upsert";
+    const std::string original(32, 'A');
+    const std::string replacement(32, 'B');
+    ASSERT_EQ(py_client_->put(key, std::span<const char>(original)), 0);
+    auto queries = py_client_->batch_query({key});
+    ASSERT_EQ(queries.size(), 1);
+    ASSERT_TRUE(queries[0].has_value());
+    PyClient::QueryResultCache snapshot;
+    snapshot.emplace(key, std::move(queries[0]));
+    auto destination = py_client_->allocate_client_buffer(original.size());
+    ASSERT_TRUE(destination.has_value());
+    auto read = [&](size_t offset, size_t size) {
+        return py_client_->get_into_ranges_from_snapshot(
+            {destination->ptr()}, {{key}}, {{{offset}}}, {{{offset}}},
+            {{{size}}}, snapshot);
+    };
+
+    // Pause between prefix and payload, then replace the same-size object.
+    EXPECT_EQ(read(0, 4),
+              (std::vector<std::vector<std::vector<int64_t>>>{{{4}}}));
+    ASSERT_EQ(py_client_->upsert(key, std::span<const char>(replacement)), 0);
+    EXPECT_EQ(read(4, 28),
+              (std::vector<std::vector<std::vector<int64_t>>>{{{28}}}));
+    EXPECT_EQ(std::string(static_cast<char*>(destination->ptr()), 32),
+              original);
+    auto current = py_client_->get_buffer(key);
+    ASSERT_NE(current, nullptr);
+    EXPECT_EQ(std::string(static_cast<char*>(current->ptr()), current->size()),
+              replacement);
+}
+
+TEST_F(RealClientTest, RangedSnapshotDoesNotRefreshExpiredOrMissingEntries) {
+    StartMasterAndSetupClient();
+    const std::string key = "ranged_snapshot_expired";
+    const std::string data(32, 'A');
+    ASSERT_EQ(py_client_->put(key, std::span<const char>(data)), 0);
+    auto queries = py_client_->batch_query({key});
+    ASSERT_EQ(queries.size(), 1);
+    ASSERT_TRUE(queries[0].has_value());
+    PyClient::QueryResultCache snapshot;
+    snapshot.emplace(
+        key, QueryResult(
+                 std::vector<Replica::Descriptor>(queries[0]->replicas),
+                 std::chrono::steady_clock::now() - std::chrono::seconds(1)));
+    auto destination = py_client_->allocate_client_buffer(data.size());
+    ASSERT_TRUE(destination.has_value());
+    auto read = [&]() {
+        return py_client_->get_into_ranges_from_snapshot(
+            {destination->ptr()}, {{key}}, {{{0}}}, {{{4}}}, {{{4}}}, snapshot);
+    };
+    EXPECT_EQ(read(), (std::vector<std::vector<std::vector<int64_t>>>{
+                          {{toInt(ErrorCode::LEASE_EXPIRED)}}}));
+    // The existing cache API still allows refresh for independent reads.
+    EXPECT_EQ(py_client_->get_into_ranges({destination->ptr()}, {{key}},
+                                          {{{0}}}, {{{4}}}, {{{4}}}, &snapshot),
+              (std::vector<std::vector<std::vector<int64_t>>>{{{4}}}));
+    snapshot.clear();
+    EXPECT_EQ(read(), (std::vector<std::vector<std::vector<int64_t>>>{
+                          {{toInt(ErrorCode::INVALID_PARAMS)}}}));
+    snapshot.emplace(key, tl::unexpected(ErrorCode::OBJECT_NOT_FOUND));
+    EXPECT_EQ(read(), (std::vector<std::vector<std::vector<int64_t>>>{
+                          {{toInt(ErrorCode::OBJECT_NOT_FOUND)}}}));
+}
+
 // Test Get Operation will fail if the lease has expired.
 // Set the lease time to 1ms and use large data size to ensure the lease will
 // expire.
@@ -747,6 +1371,7 @@ TEST_F(RealClientTest, TestBatchPutAndGetMultiBuffers) {
         0);
 
     std::string test_data(1000, '1');
+    std::string upsert_data(1000, '2');
     std::string dst_data(1000, '0');
 
     // Register buffers for zero-copy operations
@@ -758,26 +1383,36 @@ TEST_F(RealClientTest, TestBatchPutAndGetMultiBuffers) {
         py_client_->register_buffer(dst_data.data(), dst_data.size());
     ASSERT_EQ(reg_result_dst, 0)
         << "Dst data buffer registration should succeed";
+    int reg_result_upsert =
+        py_client_->register_buffer(upsert_data.data(), upsert_data.size());
+    ASSERT_EQ(reg_result_upsert, 0)
+        << "Upsert data buffer registration should succeed";
 
     std::vector<std::string> keys;
     std::vector<std::vector<void*>> all_ptrs;
+    std::vector<std::vector<void*>> all_upsert_ptrs;
     std::vector<std::vector<void*>> all_dst_ptrs;
     std::vector<std::vector<size_t>> all_sizes;
     auto ptr = test_data.data();
+    auto upsert_ptr = upsert_data.data();
     auto dst_ptr = dst_data.data();
     for (size_t i = 0; i < 10; i++) {
         keys.emplace_back("test_key_" + std::to_string(i));
         std::vector<void*> ptrs;
+        std::vector<void*> upsert_ptrs;
         std::vector<void*> dst_ptrs;
         std::vector<size_t> sizes;
         for (size_t j = 0; j < 10; j++) {
             ptrs.emplace_back(ptr);
+            upsert_ptrs.emplace_back(upsert_ptr);
             dst_ptrs.emplace_back(dst_ptr);
             sizes.emplace_back(10);
             ptr += 10;
+            upsert_ptr += 10;
             dst_ptr += 10;
         }
         all_ptrs.emplace_back(ptrs);
+        all_upsert_ptrs.emplace_back(upsert_ptrs);
         all_dst_ptrs.emplace_back(dst_ptrs);
         all_sizes.emplace_back(sizes);
     }
@@ -796,6 +1431,21 @@ TEST_F(RealClientTest, TestBatchPutAndGetMultiBuffers) {
     }
     EXPECT_EQ(dst_data, test_data) << "Retrieved data should match original";
 
+    std::vector<int> upsert_results =
+        py_client_->batch_upsert_from_multi_buffers(keys, all_upsert_ptrs,
+                                                    all_sizes, config);
+    for (auto result : upsert_results) {
+        EXPECT_EQ(result, 0) << "Upsert operation should succeed";
+    }
+    std::fill(dst_data.begin(), dst_data.end(), '0');
+    get_results = py_client_->batch_get_into_multi_buffers(keys, all_dst_ptrs,
+                                                           all_sizes, true);
+    for (auto result : get_results) {
+        EXPECT_EQ(result, 100) << "Get after upsert should succeed";
+    }
+    EXPECT_EQ(dst_data, upsert_data)
+        << "Retrieved data should match upserted data";
+
     // Unregister buffers
     int unreg_result_test = py_client_->unregister_buffer(test_data.data());
     ASSERT_EQ(unreg_result_test, 0)
@@ -803,6 +1453,497 @@ TEST_F(RealClientTest, TestBatchPutAndGetMultiBuffers) {
     int unreg_result_dst = py_client_->unregister_buffer(dst_data.data());
     ASSERT_EQ(unreg_result_dst, 0)
         << "Dst data buffer unregistration should succeed";
+    int unreg_result_upsert = py_client_->unregister_buffer(upsert_data.data());
+    ASSERT_EQ(unreg_result_upsert, 0)
+        << "Upsert data buffer unregistration should succeed";
+}
+
+TEST_F(RealClientTest, TestPutGetSessionRanges) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17814", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kNumLayers = 4;
+    constexpr size_t kPageSize = 64;
+    constexpr size_t kObjectSize = kPageSize * kNumLayers;
+    constexpr size_t kNumKeys = 3;
+
+    std::string src_data(kObjectSize * kNumKeys, 'A');
+    std::string dst_data(kObjectSize * kNumKeys, 'B');
+    for (size_t i = 0; i < src_data.size(); ++i) {
+        src_data[i] = static_cast<char>('a' + (i % 26));
+    }
+
+    ASSERT_EQ(py_client_->register_buffer(src_data.data(), src_data.size()), 0);
+    ASSERT_EQ(py_client_->register_buffer(dst_data.data(), dst_data.size()), 0);
+
+    std::vector<std::string> keys;
+    std::vector<size_t> object_sizes;
+    keys.reserve(kNumKeys);
+    object_sizes.reserve(kNumKeys);
+    for (size_t i = 0; i < kNumKeys; ++i) {
+        keys.push_back("session_key_" + std::to_string(i));
+        object_sizes.push_back(kObjectSize);
+    }
+
+    auto put_start_rcs =
+        py_client_->batch_put_session_start(keys, object_sizes);
+    ASSERT_EQ(put_start_rcs.size(), kNumKeys);
+    for (auto rc : put_start_rcs) {
+        EXPECT_EQ(rc, 0) << "batch_put_session_start should succeed";
+    }
+
+    for (size_t layer = 0; layer < kNumLayers; ++layer) {
+        std::vector<std::vector<void*>> all_buffers(kNumKeys);
+        std::vector<std::vector<size_t>> all_sizes(kNumKeys);
+        std::vector<std::vector<size_t>> all_dst_offsets(kNumKeys);
+        for (size_t i = 0; i < kNumKeys; ++i) {
+            char* layer_ptr =
+                src_data.data() + i * kObjectSize + layer * kPageSize;
+            all_buffers[i] = {layer_ptr};
+            all_sizes[i] = {kPageSize};
+            all_dst_offsets[i] = {layer * kPageSize};
+        }
+        auto put_rcs = py_client_->batch_put_from_multi_buffer_ranges(
+            keys, all_buffers, all_sizes, all_dst_offsets);
+        ASSERT_EQ(put_rcs.size(), kNumKeys);
+        for (auto rc : put_rcs) {
+            EXPECT_EQ(rc, static_cast<int>(kPageSize));
+        }
+    }
+
+    auto put_end_rcs = py_client_->batch_put_session_end(keys);
+    ASSERT_EQ(put_end_rcs.size(), kNumKeys);
+    for (auto rc : put_end_rcs) {
+        EXPECT_EQ(rc, 0) << "batch_put_session_end should succeed";
+    }
+
+    auto get_start_rcs = py_client_->batch_get_session_start(keys);
+    ASSERT_EQ(get_start_rcs.size(), kNumKeys);
+    for (auto rc : get_start_rcs) {
+        EXPECT_EQ(rc, 0) << "batch_get_session_start should succeed";
+    }
+
+    for (size_t layer = 0; layer < kNumLayers; ++layer) {
+        std::vector<std::vector<void*>> all_buffers(kNumKeys);
+        std::vector<std::vector<size_t>> all_sizes(kNumKeys);
+        std::vector<std::vector<size_t>> all_src_offsets(kNumKeys);
+        for (size_t i = 0; i < kNumKeys; ++i) {
+            char* layer_ptr =
+                dst_data.data() + i * kObjectSize + layer * kPageSize;
+            all_buffers[i] = {layer_ptr};
+            all_sizes[i] = {kPageSize};
+            all_src_offsets[i] = {layer * kPageSize};
+        }
+        auto get_rcs = py_client_->batch_get_into_multi_buffer_ranges(
+            keys, all_buffers, all_sizes, all_src_offsets);
+        ASSERT_EQ(get_rcs.size(), kNumKeys);
+        for (auto rc : get_rcs) {
+            EXPECT_EQ(rc, static_cast<int>(kPageSize));
+        }
+    }
+
+    EXPECT_EQ(py_client_->batch_get_session_end(keys), 0);
+    EXPECT_EQ(dst_data, src_data);
+
+    // Revoke path: start then revoke without end.
+    std::vector<std::string> revoke_keys = {"session_revoke_0"};
+    std::vector<size_t> revoke_sizes = {kObjectSize};
+    auto revoke_start =
+        py_client_->batch_put_session_start(revoke_keys, revoke_sizes);
+    ASSERT_EQ(revoke_start.size(), 1);
+    EXPECT_EQ(revoke_start[0], 0);
+    auto revoke_rcs = py_client_->batch_put_session_revoke(revoke_keys);
+    ASSERT_EQ(revoke_rcs.size(), 1);
+    EXPECT_EQ(revoke_rcs[0], 0);
+    auto missing = py_client_->batch_get_session_start(revoke_keys);
+    ASSERT_EQ(missing.size(), 1);
+    EXPECT_LT(missing[0], 0);
+
+    ASSERT_EQ(py_client_->unregister_buffer(src_data.data()), 0);
+    ASSERT_EQ(py_client_->unregister_buffer(dst_data.data()), 0);
+}
+
+// Abnormal put/get session cases. See check table in PR / review notes.
+TEST_F(RealClientTest, TestPutGetSessionAbnormal) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17815", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kPage = 64;
+    constexpr size_t kObjectSize = kPage * 2;
+    const int kInvalidParams =
+        static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+
+    std::string buf(kObjectSize, 'x');
+    ASSERT_EQ(py_client_->register_buffer(buf.data(), buf.size()), 0);
+
+    EXPECT_TRUE(py_client_->batch_get_session_start({}).empty());
+    EXPECT_TRUE(
+        py_client_->batch_get_into_multi_buffer_ranges({}, {}, {}, {}).empty());
+    EXPECT_EQ(py_client_->batch_get_session_end({}), 0);
+    EXPECT_EQ(py_client_->batch_get_into_multi_buffer_ranges(
+                  {"outer_arity_get"}, {}, {}, {}),
+              std::vector<int>{kInvalidParams});
+
+    // --- Put: ranges/end/revoke without start ---
+    {
+        std::vector<std::string> keys = {"no_put_session"};
+        auto ranges = py_client_->batch_put_from_multi_buffer_ranges(
+            keys, {{buf.data()}}, {{kPage}}, {{0}});
+        ASSERT_EQ(ranges.size(), 1);
+        EXPECT_EQ(ranges[0], kInvalidParams);
+
+        auto end_rcs = py_client_->batch_put_session_end(keys);
+        ASSERT_EQ(end_rcs.size(), 1);
+        EXPECT_EQ(end_rcs[0], kInvalidParams);
+
+        auto revoke_rcs = py_client_->batch_put_session_revoke(keys);
+        ASSERT_EQ(revoke_rcs.size(), 1);
+        EXPECT_EQ(revoke_rcs[0], kInvalidParams);
+    }
+
+    // --- Put: keys/sizes mismatch ---
+    {
+        auto rcs =
+            py_client_->batch_put_session_start({"a", "b"}, {kObjectSize});
+        ASSERT_EQ(rcs.size(), 2);
+        EXPECT_EQ(rcs[0], kInvalidParams);
+        EXPECT_EQ(rcs[1], kInvalidParams);
+    }
+
+    // --- Put: duplicate start ---
+    {
+        std::vector<std::string> keys = {"dup_put"};
+        auto first = py_client_->batch_put_session_start(keys, {kObjectSize});
+        ASSERT_EQ(first.size(), 1);
+        EXPECT_EQ(first[0], 0);
+        auto second = py_client_->batch_put_session_start(keys, {kObjectSize});
+        ASSERT_EQ(second.size(), 1);
+        EXPECT_EQ(second[0], kInvalidParams);
+        EXPECT_EQ(py_client_->batch_put_session_revoke(keys)[0], 0);
+    }
+
+    // --- Put: range overflow past object_size ---
+    {
+        std::vector<std::string> keys = {"overflow_put"};
+        ASSERT_EQ(py_client_->batch_put_session_start(keys, {kObjectSize})[0],
+                  0);
+        auto overflow = py_client_->batch_put_from_multi_buffer_ranges(
+            keys, {{buf.data()}}, {{kPage}},
+            {{kObjectSize}});  // offset == size
+        ASSERT_EQ(overflow.size(), 1);
+        EXPECT_EQ(overflow[0], kInvalidParams);
+        EXPECT_EQ(py_client_->batch_put_session_revoke(keys)[0], 0);
+    }
+
+    // --- Put: buffer/size/offset arity mismatch ---
+    {
+        std::vector<std::string> keys = {"arity_put"};
+        ASSERT_EQ(py_client_->batch_put_session_start(keys, {kObjectSize})[0],
+                  0);
+        auto bad = py_client_->batch_put_from_multi_buffer_ranges(
+            keys, {{buf.data(), buf.data() + kPage}}, {{kPage}}, {{0}});
+        ASSERT_EQ(bad.size(), 1);
+        EXPECT_EQ(bad[0], kInvalidParams);
+        EXPECT_EQ(py_client_->batch_put_session_revoke(keys)[0], 0);
+    }
+
+    // --- Put: end clears session; second end fails ---
+    {
+        std::vector<std::string> keys = {"put_end_once"};
+        ASSERT_EQ(py_client_->batch_put_session_start(keys, {kObjectSize})[0],
+                  0);
+        ASSERT_EQ(py_client_->batch_put_from_multi_buffer_ranges(
+                      keys, {{buf.data()}}, {{kObjectSize}}, {{0}})[0],
+                  static_cast<int>(kObjectSize));
+        EXPECT_EQ(py_client_->batch_put_session_end(keys)[0], 0);
+        EXPECT_EQ(py_client_->batch_put_session_end(keys)[0], kInvalidParams);
+        // ranges after end also fail
+        EXPECT_EQ(py_client_->batch_put_from_multi_buffer_ranges(
+                      keys, {{buf.data()}}, {{kPage}}, {{0}})[0],
+                  kInvalidParams);
+    }
+
+    // --- Get: ranges without start ---
+    {
+        std::vector<std::string> keys = {"no_get_session"};
+        auto ranges = py_client_->batch_get_into_multi_buffer_ranges(
+            keys, {{buf.data()}}, {{kPage}}, {{0}});
+        ASSERT_EQ(ranges.size(), 1);
+        EXPECT_EQ(ranges[0], kInvalidParams);
+    }
+
+    // --- Get: start on missing object ---
+    {
+        auto rcs = py_client_->batch_get_session_start({"missing_obj"});
+        ASSERT_EQ(rcs.size(), 1);
+        EXPECT_LT(rcs[0], 0);
+    }
+
+    // --- Get: end clears session; ranges after end fail ---
+    {
+        std::vector<std::string> keys = {"put_end_once"};  // exists from above
+        auto start = py_client_->batch_get_session_start(keys);
+        ASSERT_EQ(start.size(), 1);
+        EXPECT_EQ(start[0], 0);
+        EXPECT_EQ(py_client_->batch_get_session_end(keys), 0);
+        auto after_end = py_client_->batch_get_into_multi_buffer_ranges(
+            keys, {{buf.data()}}, {{kPage}}, {{0}});
+        ASSERT_EQ(after_end.size(), 1);
+        EXPECT_EQ(after_end[0], kInvalidParams);
+    }
+
+    // --- Get: arity mismatch while session exists ---
+    {
+        std::vector<std::string> keys = {"put_end_once"};
+        ASSERT_EQ(py_client_->batch_get_session_start(keys)[0], 0);
+        auto bad = py_client_->batch_get_into_multi_buffer_ranges(
+            keys, {{buf.data()}}, {{kPage, kPage}}, {{0}});
+        ASSERT_EQ(bad.size(), 1);
+        EXPECT_EQ(bad[0], kInvalidParams);
+        EXPECT_EQ(py_client_->batch_get_session_end(keys), 0);
+    }
+
+    ASSERT_EQ(py_client_->unregister_buffer(buf.data()), 0);
+}
+
+// Put session must survive BatchPutEnd failure so caller can retry end/revoke.
+TEST_F(RealClientTest, TestPutSessionKeptAfterEndFailure) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17817", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kSize = 128;
+    const int kObjectNotFound =
+        static_cast<int>(toInt(ErrorCode::OBJECT_NOT_FOUND));
+    const int kInvalidParams =
+        static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+
+    std::vector<std::string> keys = {"session_end_fail_keep"};
+    ASSERT_EQ(py_client_->batch_put_session_start(keys, {kSize})[0], 0);
+
+    // Drop Master reservation while keeping the local put session.
+    ASSERT_NE(py_client_->client_, nullptr);
+    auto revoked = py_client_->client_->BatchPutRevoke(keys, ReplicaType::ALL);
+    ASSERT_EQ(revoked.size(), 1u);
+    ASSERT_TRUE(revoked[0].has_value());
+
+    auto end1 = py_client_->batch_put_session_end(keys);
+    ASSERT_EQ(end1.size(), 1u);
+    EXPECT_EQ(end1[0], kObjectNotFound)
+        << "end should surface Master OBJECT_NOT_FOUND";
+
+    // Session must still exist: second end is not INVALID_PARAMS.
+    auto end2 = py_client_->batch_put_session_end(keys);
+    ASSERT_EQ(end2.size(), 1u);
+    EXPECT_EQ(end2[0], kObjectNotFound)
+        << "put session should be kept after end failure";
+
+    // Revoke clears the local session even when Master object is already gone.
+    auto revoke_rcs = py_client_->batch_put_session_revoke(keys);
+    ASSERT_EQ(revoke_rcs.size(), 1u);
+    EXPECT_EQ(revoke_rcs[0], 0);
+    EXPECT_EQ(py_client_->batch_put_session_end(keys)[0], kInvalidParams);
+    EXPECT_EQ(py_client_->batch_put_session_revoke(keys)[0], kInvalidParams);
+}
+
+// Reliable NoF configs cannot be finalized by the session put path.
+TEST_F(RealClientTest, TestPutSessionStartRejectsReliableNofConfig) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17819", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    const int kInvalidParams =
+        static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+    ReplicateConfig config;
+    config.replica_num = 1;
+    config.nof_replica_num = 2;  // RELIABLE_MULTI_REPLICA
+
+    auto rcs =
+        py_client_->batch_put_session_start({"reliable_nof"}, {128}, config);
+    ASSERT_EQ(rcs.size(), 1u);
+    EXPECT_EQ(rcs[0], kInvalidParams);
+}
+
+// Filtered start_keys must keep group_ids aligned (skip existing sessions).
+TEST_F(RealClientTest, TestPutSessionStartFiltersGroupIds) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17820", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kSize = 128;
+    const int kInvalidParams =
+        static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+
+    ReplicateConfig first_config;
+    first_config.group_ids = std::vector<std::string>{"group_a"};
+    ASSERT_EQ(py_client_->batch_put_session_start({"group_key_a"}, {kSize},
+                                                  first_config)[0],
+              0);
+
+    ReplicateConfig batch_config;
+    batch_config.group_ids = std::vector<std::string>{"group_a", "group_b"};
+    auto rcs = py_client_->batch_put_session_start(
+        {"group_key_a", "group_key_b"}, {kSize, kSize}, batch_config);
+    ASSERT_EQ(rcs.size(), 2u);
+    EXPECT_EQ(rcs[0], kInvalidParams) << "existing session should be skipped";
+    EXPECT_EQ(rcs[1], 0) << "filtered group_ids must match remaining keys";
+
+    auto revoke_rcs =
+        py_client_->batch_put_session_revoke({"group_key_a", "group_key_b"});
+    ASSERT_EQ(revoke_rcs.size(), 2u);
+    EXPECT_EQ(revoke_rcs[0], 0);
+    EXPECT_EQ(revoke_rcs[1], 0);
+}
+
+// Session put finalizes MEMORY only; complete object must be readable.
+TEST_F(RealClientTest, TestPutSessionEndCompletesMemoryReplica) {
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder().build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17818", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kSize = 256;
+    std::string src(kSize, 'P');
+    std::string dst(kSize, 'Q');
+    ASSERT_EQ(py_client_->register_buffer(src.data(), src.size()), 0);
+    ASSERT_EQ(py_client_->register_buffer(dst.data(), dst.size()), 0);
+
+    std::vector<std::string> keys = {"session_memory_end"};
+    ASSERT_EQ(py_client_->batch_put_session_start(keys, {kSize})[0], 0);
+    ASSERT_EQ(py_client_->batch_put_from_multi_buffer_ranges(
+                  keys, {{src.data()}}, {{kSize}}, {{0}})[0],
+              static_cast<int>(kSize));
+    ASSERT_EQ(py_client_->batch_put_session_end(keys)[0], 0);
+
+    auto descs = py_client_->get_replica_desc(keys[0]);
+    ASSERT_EQ(descs.size(), 1u);
+    EXPECT_TRUE(descs[0].is_memory_replica());
+    EXPECT_EQ(descs[0].status, ReplicaStatus::COMPLETE);
+
+    ASSERT_EQ(py_client_->batch_get_session_start(keys)[0], 0);
+    ASSERT_EQ(py_client_->batch_get_into_multi_buffer_ranges(
+                  keys, {{dst.data()}}, {{kSize}}, {{0}})[0],
+              static_cast<int>(kSize));
+    EXPECT_EQ(py_client_->batch_get_session_end(keys), 0);
+    EXPECT_EQ(dst, src);
+
+    ASSERT_EQ(py_client_->unregister_buffer(src.data()), 0);
+    ASSERT_EQ(py_client_->unregister_buffer(dst.data()), 0);
+}
+
+// Lease expire on get ranges must drop the cached get session.
+TEST_F(RealClientTest, TestGetSessionLeaseExpiredDropsSession) {
+    constexpr uint64_t kLeaseTtlMs = 50;
+    ASSERT_TRUE(master_.Start(InProcMasterConfigBuilder()
+                                  .set_default_kv_lease_ttl(kLeaseTtlMs)
+                                  .build()))
+        << "Failed to start in-proc master";
+    master_address_ = master_.master_address();
+
+    const std::string rdma_devices = (FLAGS_protocol == std::string("rdma"))
+                                         ? FLAGS_device_name
+                                         : std::string("");
+    ASSERT_EQ(
+        py_client_->setup_real("localhost:17816", "P2PHANDSHAKE",
+                               16 * 1024 * 1024, 16 * 1024 * 1024,
+                               FLAGS_protocol, rdma_devices, master_address_),
+        0);
+
+    constexpr size_t kSize = 128;
+    const int kLeaseExpired = static_cast<int>(toInt(ErrorCode::LEASE_EXPIRED));
+    const int kInvalidParams =
+        static_cast<int>(toInt(ErrorCode::INVALID_PARAMS));
+
+    std::string src(kSize, 'S');
+    std::string dst(kSize, 'D');
+    ASSERT_EQ(py_client_->register_buffer(src.data(), src.size()), 0);
+    ASSERT_EQ(py_client_->register_buffer(dst.data(), dst.size()), 0);
+
+    std::vector<std::string> keys = {"lease_session_key"};
+    ASSERT_EQ(py_client_->batch_put_session_start(keys, {kSize})[0], 0);
+    ASSERT_EQ(py_client_->batch_put_from_multi_buffer_ranges(
+                  keys, {{src.data()}}, {{kSize}}, {{0}})[0],
+              static_cast<int>(kSize));
+    ASSERT_EQ(py_client_->batch_put_session_end(keys)[0], 0);
+
+    ASSERT_EQ(py_client_->batch_get_session_start(keys)[0], 0);
+
+    // Wait past cached lease_deadline (client-local check; no Master query).
+    std::this_thread::sleep_for(std::chrono::milliseconds(kLeaseTtlMs + 50));
+
+    auto expired = py_client_->batch_get_into_multi_buffer_ranges(
+        keys, {{dst.data()}}, {{kSize}}, {{0}});
+    ASSERT_EQ(expired.size(), 1);
+    EXPECT_EQ(expired[0], kLeaseExpired)
+        << "get ranges after lease ttl should return LEASE_EXPIRED";
+
+    // Session must have been erased: next ranges sees no session.
+    auto again = py_client_->batch_get_into_multi_buffer_ranges(
+        keys, {{dst.data()}}, {{kSize}}, {{0}});
+    ASSERT_EQ(again.size(), 1);
+    EXPECT_EQ(again[0], kInvalidParams)
+        << "get session should be dropped after LEASE_EXPIRED";
+
+    // get_end is still safe (idempotent erase).
+    EXPECT_EQ(py_client_->batch_get_session_end(keys), 0);
+
+    ASSERT_EQ(py_client_->unregister_buffer(src.data()), 0);
+    ASSERT_EQ(py_client_->unregister_buffer(dst.data()), 0);
 }
 
 TEST_F(RealClientTest, TestBatchAndNormalGetReplicaDesc) {
diff --git a/mooncake-store/tests/random_test.cpp b/mooncake-store/tests/random_test.cpp
new file mode 100644
index 0000000000..2a09b9b6c7
--- /dev/null
+++ b/mooncake-store/tests/random_test.cpp
@@ -0,0 +1,76 @@
+#include "random.h"
+
+#include <cstdint>
+#include <future>
+#include <random>
+#include <thread>
+
+#include <gtest/gtest.h>
+
+using namespace mooncake;
+
+TEST(RandomTest, ReusesEngineWithinThread) {
+    EXPECT_EQ(&threadLocalRandomEngine(), &threadLocalRandomEngine());
+}
+
+TEST(RandomTest, UsesDifferentEngineAcrossThreads) {
+    auto* main_engine = &threadLocalRandomEngine();
+    std::promise<RandomEngine*> worker_address;
+    std::promise<void> release_worker;
+    auto release_future = release_worker.get_future();
+
+    std::thread worker([&] {
+        worker_address.set_value(&threadLocalRandomEngine());
+        release_future.wait();
+    });
+
+    EXPECT_NE(main_engine, worker_address.get_future().get());
+    release_worker.set_value();
+    worker.join();
+}
+
+TEST(RandomTest, RandomIndexStaysWithinBounds) {
+    std::mt19937_64 engine(42);
+    for (size_t i = 0; i < 10000; ++i) {
+        EXPECT_LT(randomIndex(17, engine), 17);
+    }
+}
+
+TEST(RandomTest, ExplicitEngineIsDeterministic) {
+    std::mt19937_64 first(42);
+    std::mt19937_64 second(42);
+    for (size_t i = 0; i < 100; ++i) {
+        EXPECT_EQ(randomIndex(1000, first), randomIndex(1000, second));
+    }
+}
+
+TEST(RandomTest, RandomUniformIncludesRequestedBounds) {
+    std::mt19937_64 engine(42);
+    for (size_t i = 0; i < 10000; ++i) {
+        int value = randomUniform(-5, 9, engine);
+        EXPECT_GE(value, -5);
+        EXPECT_LE(value, 9);
+    }
+    EXPECT_EQ(randomUniform(7, 7, engine), 7);
+}
+
+TEST(RandomTest, RandomUniformSupportsNarrowIntegers) {
+    std::mt19937_64 engine(42);
+    for (size_t i = 0; i < 1000; ++i) {
+        auto signed_value = randomUniform<int8_t>(-5, 9, engine);
+        EXPECT_GE(signed_value, -5);
+        EXPECT_LE(signed_value, 9);
+
+        auto unsigned_value = randomUniform<uint8_t>(2, 7, engine);
+        EXPECT_GE(unsigned_value, 2);
+        EXPECT_LE(unsigned_value, 7);
+    }
+    EXPECT_FALSE(randomUniform<bool>(false, false, engine));
+    EXPECT_TRUE(randomUniform<bool>(true, true, engine));
+}
+
+TEST(RandomTest, RejectsInvalidBounds) {
+    std::mt19937_64 engine(42);
+    EXPECT_THROW(randomIndex(0, engine), std::invalid_argument);
+    EXPECT_THROW(randomUniform(2, 1, engine), std::invalid_argument);
+}
diff --git a/mooncake-store/tests/redis_connection_config_test.cpp b/mooncake-store/tests/redis_connection_config_test.cpp
new file mode 100644
index 0000000000..4180044197
--- /dev/null
+++ b/mooncake-store/tests/redis_connection_config_test.cpp
@@ -0,0 +1,211 @@
+#include "ha/common/redis/redis_connection.h"
+
+#include "../src/config/redis_connection_config.h"
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdlib>
+#include <mutex>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+std::mutex environment_mutex;
+
+class RedisConnectionConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        environment_lock_ = std::unique_lock<std::mutex>(environment_mutex);
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_[i] = value;
+            }
+            ASSERT_EQ(unsetenv(kVariables[i]), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(kVariables[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+    }
+
+    void SetDbIndex(const char* value) {
+        ASSERT_EQ(setenv("MC_REDIS_DB_INDEX", value, 1), 0);
+    }
+
+   private:
+    inline static constexpr std::array<const char*, 3> kVariables = {
+        "MC_REDIS_DB_INDEX", "MC_REDIS_USERNAME", "MC_REDIS_PASSWORD"};
+    std::array<std::optional<std::string>, kVariables.size()> original_;
+    std::unique_lock<std::mutex> environment_lock_;
+};
+
+TEST_F(RedisConnectionConfigTest, UnsetAndEmptyDbIndexUseZero) {
+    auto result = ha::common::redis::ResolveRedisDbIndex();
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(*result, 0);
+
+    SetDbIndex("");
+    result = ha::common::redis::ResolveRedisDbIndex();
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(*result, 0);
+}
+
+TEST_F(RedisConnectionConfigTest, AcceptsSupportedDbIndexSyntax) {
+    struct Case {
+        const char* value;
+        int expected;
+    };
+    const Case cases[] = {{"0", 0},    {"255", 255}, {" \t42\r\n", 42},
+                          {"+17", 17}, {"010", 10},  {"-0", 0}};
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        SetDbIndex(entry.value);
+        const auto result = ha::common::redis::ResolveRedisDbIndex();
+        ASSERT_TRUE(result.has_value());
+        EXPECT_EQ(*result, entry.expected);
+    }
+}
+
+TEST_F(RedisConnectionConfigTest, RejectsInvalidDbIndexSilently) {
+    const char* values[] = {"-1", "256", "999999999999999999999999", "abc"};
+    for (const char* value : values) {
+        SCOPED_TRACE(value);
+        SetDbIndex(value);
+        testing::internal::CaptureStderr();
+        const auto result = ha::common::redis::ResolveRedisDbIndex();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+        EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+    }
+}
+
+TEST_F(RedisConnectionConfigTest, RejectsDbIndexWithNonIntegerSuffix) {
+    for (const char* value : {"1junk", "1e2", "0x1"}) {
+        SCOPED_TRACE(value);
+        SetDbIndex(value);
+        const auto result = ha::common::redis::ResolveRedisDbIndex();
+        EXPECT_FALSE(result.has_value());
+        if (result.has_value()) {
+            continue;
+        }
+        EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+    }
+}
+
+TEST_F(RedisConnectionConfigTest, UnsetValuesUseConnectionDefaults) {
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_EQ(config->db_index, 0);
+    EXPECT_TRUE(config->username.empty());
+    EXPECT_TRUE(config->password.empty());
+}
+
+TEST_F(RedisConnectionConfigTest, EmptyCredentialsRemainEmpty) {
+    ASSERT_EQ(setenv("MC_REDIS_USERNAME", "", 1), 0);
+    ASSERT_EQ(setenv("MC_REDIS_PASSWORD", "", 1), 0);
+
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_TRUE(config->username.empty());
+    EXPECT_TRUE(config->password.empty());
+}
+
+TEST_F(RedisConnectionConfigTest, UsernameWithoutPasswordRemainsValid) {
+    ASSERT_EQ(setenv("MC_REDIS_USERNAME", "unused-user", 1), 0);
+
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_EQ(config->username, "unused-user");
+    EXPECT_TRUE(config->password.empty());
+}
+
+TEST_F(RedisConnectionConfigTest, PasswordWithoutUsernameRemainsValid) {
+    ASSERT_EQ(setenv("MC_REDIS_PASSWORD", "secret", 1), 0);
+
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_TRUE(config->username.empty());
+    EXPECT_EQ(config->password, "secret");
+}
+
+TEST_F(RedisConnectionConfigTest, PreservesCredentialTextExactly) {
+    ASSERT_EQ(setenv("MC_REDIS_USERNAME", "user name", 1), 0);
+    ASSERT_EQ(setenv("MC_REDIS_PASSWORD", "p@ss word", 1), 0);
+
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_EQ(config->username, "user name");
+    EXPECT_EQ(config->password, "p@ss word");
+}
+
+TEST_F(RedisConnectionConfigTest, LoadsIndependentConnectionSettings) {
+    SetDbIndex("7");
+    ASSERT_EQ(setenv("MC_REDIS_USERNAME", "alice", 1), 0);
+    ASSERT_EQ(setenv("MC_REDIS_PASSWORD", "secret", 1), 0);
+
+    const auto config = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(config.has_value());
+    EXPECT_EQ(config->db_index, 7);
+    EXPECT_EQ(config->username, "alice");
+    EXPECT_EQ(config->password, "secret");
+}
+
+TEST_F(RedisConnectionConfigTest, NewConfigsReadCurrentEnvironment) {
+    SetDbIndex("1");
+    const auto first = RedisConnectionConfig::FromEnvironment();
+    SetDbIndex("2");
+    const auto second = RedisConnectionConfig::FromEnvironment();
+
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+    EXPECT_EQ(first->db_index, 1);
+    EXPECT_EQ(second->db_index, 2);
+}
+
+TEST_F(RedisConnectionConfigTest, PublicDbResolverMatchesOwnerConfig) {
+    const char* values[] = {"",   "0",  "255", " \t42\r\n", "+17",   "010",
+                            "-0", "-1", "256", "abc",       "1junk", "0x1"};
+    for (const char* value : values) {
+        SCOPED_TRACE(value);
+        SetDbIndex(value);
+        const auto config = RedisConnectionConfig::FromEnvironment();
+        const auto resolved = ha::common::redis::ResolveRedisDbIndex();
+        EXPECT_EQ(config.has_value(), resolved.has_value());
+        if (config.has_value() && resolved.has_value()) {
+            EXPECT_EQ(config->db_index, *resolved);
+        } else if (!config.has_value() && !resolved.has_value()) {
+            EXPECT_EQ(config.error(), resolved.error());
+        }
+    }
+}
+
+#ifdef STORE_USE_REDIS
+TEST_F(RedisConnectionConfigTest,
+       ConnectRedisRejectsMalformedDbBeforeOpeningConnection) {
+    SetDbIndex("1junk");
+    const auto result = ha::common::redis::ConnectRedis(
+        "redis://127.0.0.1:1", ErrorCode::PERSISTENT_FAIL);
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::INVALID_PARAMS);
+}
+#endif
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/region_driver_test.cpp b/mooncake-store/tests/region_driver_test.cpp
new file mode 100644
index 0000000000..2f64dafdfe
--- /dev/null
+++ b/mooncake-store/tests/region_driver_test.cpp
@@ -0,0 +1,208 @@
+#include "segment/region_driver.h"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <vector>
+
+#include "master_metric_manager.h"
+
+namespace mooncake {
+namespace {
+
+constexpr size_t kRegionSize = 16U * 1024 * 1024;
+
+RegionResourceSpec MakeSpec(uintptr_t base = 0x100000000ULL) {
+    return {generate_uuid(), "memory", base, kRegionSize, "memory-endpoint"};
+}
+
+std::unique_ptr<RegionDriver> CreateTestDriver(RegionKind kind) {
+    RegionDriverConfig config;
+    config.memory_allocator = BufferAllocatorType::OFFSET;
+    if (kind == RegionKind::CXL) {
+        config.cxl = CxlRegionDriverConfig{"cxl-test", kRegionSize};
+    }
+    auto drivers = CreateRegionDrivers(config);
+    if (!drivers) {
+        return nullptr;
+    }
+    auto driver = drivers->extract(kind);
+    return driver.empty() ? nullptr : std::move(driver.mapped());
+}
+
+TEST(RegionDriverTest, PreparedResourceRollsBackUntilCommitted) {
+    auto driver = CreateTestDriver(RegionKind::HOST_MEMORY);
+    ASSERT_NE(driver, nullptr);
+    const auto spec = MakeSpec();
+
+    {
+        auto prepared = driver->PrepareOpen(spec, {});
+        ASSERT_TRUE(prepared.has_value());
+        EXPECT_EQ(driver->GetResource(spec.id), nullptr);
+    }
+    EXPECT_EQ(driver->GetResource(spec.id), nullptr);
+
+    auto prepared = driver->PrepareOpen(spec, {});
+    ASSERT_TRUE(prepared.has_value());
+    prepared->Commit();
+    auto* resource = driver->GetResource(spec.id);
+    ASSERT_NE(resource, nullptr);
+    EXPECT_TRUE(resource->active);
+}
+
+TEST(RegionDriverTest, ReplacementRollbackKeepsCommittedResource) {
+    auto driver = CreateTestDriver(RegionKind::HOST_MEMORY);
+    ASSERT_NE(driver, nullptr);
+    const auto spec = MakeSpec();
+    auto first = driver->PrepareOpen(spec, {});
+    ASSERT_TRUE(first.has_value());
+    first->Commit();
+    auto* committed = driver->GetResource(spec.id);
+    ASSERT_NE(committed, nullptr);
+
+    {
+        auto replacement = driver->PrepareOpen(spec, {});
+        ASSERT_TRUE(replacement.has_value());
+        EXPECT_NE(&replacement->resource(), committed);
+    }
+    EXPECT_EQ(driver->GetResource(spec.id), committed);
+}
+
+TEST(RegionDriverTest,
+     CommitRetainsReplacedResourceUntilPreparationIsReleased) {
+    auto driver = CreateTestDriver(RegionKind::HOST_MEMORY);
+    ASSERT_NE(driver, nullptr);
+    const auto spec = MakeSpec();
+    auto first = driver->PrepareOpen(spec, {});
+    ASSERT_TRUE(first.has_value());
+    std::weak_ptr<BufferAllocatorBase> old_allocator =
+        first->resource().allocator();
+    first->Commit();
+
+    {
+        auto replacement = driver->PrepareOpen(spec, {});
+        ASSERT_TRUE(replacement.has_value());
+        auto& resource = replacement->resource();
+        replacement->Commit();
+        EXPECT_EQ(driver->GetResource(spec.id), &resource);
+        EXPECT_TRUE(resource.active);
+        EXPECT_FALSE(old_allocator.expired());
+        replacement->Commit();
+        EXPECT_FALSE(old_allocator.expired());
+    }
+    EXPECT_TRUE(old_allocator.expired());
+    ASSERT_NE(driver->GetResource(spec.id), nullptr);
+    EXPECT_TRUE(driver->GetResource(spec.id)->active);
+}
+
+TEST(RegionDriverTest, RestoreInputValidatesEndpointBoundsAndPreservesOrder) {
+    const auto spec = MakeSpec(0x200000000ULL);
+    std::vector<AllocatedBuffer::Descriptor> descriptors{
+        {4096, spec.base + 8192, "tcp", spec.transport_endpoint},
+        {4096, spec.base, "tcp", spec.transport_endpoint}};
+    auto allocations = BuildRegionLiveAllocations(spec, descriptors);
+    ASSERT_TRUE(allocations.has_value());
+    ASSERT_EQ(allocations->size(), 2U);
+    EXPECT_EQ((*allocations)[0].offset_from_base, 8192U);
+    EXPECT_EQ((*allocations)[1].offset_from_base, 0U);
+
+    auto bad_endpoint = descriptors;
+    bad_endpoint[0].transport_endpoint_ = "other";
+    EXPECT_EQ(BuildRegionLiveAllocations(spec, bad_endpoint).error(),
+              ErrorCode::INVALID_PARAMS);
+    auto segment_name_alias = descriptors;
+    segment_name_alias[0].transport_endpoint_ = spec.name;
+    EXPECT_EQ(BuildRegionLiveAllocations(spec, segment_name_alias).error(),
+              ErrorCode::INVALID_PARAMS);
+    auto out_of_bounds = descriptors;
+    out_of_bounds[0].buffer_address_ = spec.base + spec.size - 1024;
+    EXPECT_EQ(BuildRegionLiveAllocations(spec, out_of_bounds).error(),
+              ErrorCode::INVALID_PARAMS);
+}
+
+TEST(RegionDriverTest, OffsetImportPreservesInputOrder) {
+    auto driver = CreateTestDriver(RegionKind::HOST_MEMORY);
+    ASSERT_NE(driver, nullptr);
+    const auto spec = MakeSpec(0x300000000ULL);
+    std::vector<LiveAllocation> allocations{{8192, 4096}, {0, 4096}};
+    auto prepared = driver->PrepareOpen(spec, allocations);
+    ASSERT_TRUE(prepared.has_value());
+    ASSERT_EQ(prepared->imported_buffers().size(), 2U);
+    EXPECT_EQ(
+        reinterpret_cast<uintptr_t>(prepared->imported_buffers()[0]->data()),
+        spec.base + 8192);
+    EXPECT_EQ(
+        reinterpret_cast<uintptr_t>(prepared->imported_buffers()[1]->data()),
+        spec.base);
+}
+
+TEST(RegionDriverTest, FailedRestoreDoesNotPublishResource) {
+    auto driver = CreateTestDriver(RegionKind::HOST_MEMORY);
+    ASSERT_NE(driver, nullptr);
+    const auto spec = MakeSpec(0x400000000ULL);
+    auto prepared = driver->PrepareOpen(spec, {{{0, 4096}, {0, 4096}}});
+    EXPECT_FALSE(prepared.has_value());
+    EXPECT_EQ(prepared.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(driver->GetResource(spec.id), nullptr);
+}
+
+TEST(RegionDriverTest, CxlRejectsLiveRestoreInput) {
+    auto driver = CreateTestDriver(RegionKind::CXL);
+    ASSERT_NE(driver, nullptr);
+    RegionResourceSpec spec{generate_uuid(), "binding", 0, kRegionSize,
+                            "transport"};
+    auto prepared = driver->PrepareOpen(spec, {{{0, 4096}}});
+    EXPECT_FALSE(prepared.has_value());
+    EXPECT_EQ(prepared.error(), ErrorCode::UNAVAILABLE_IN_CURRENT_MODE);
+    EXPECT_EQ(driver->GetResource(spec.id), nullptr);
+}
+
+TEST(RegionDriverTest, CxlCandidateProducesCxlDescriptors) {
+    auto driver = CreateTestDriver(RegionKind::CXL);
+    ASSERT_NE(driver, nullptr);
+    RegionResourceSpec spec{generate_uuid(), "binding", 0, kRegionSize,
+                            "transport"};
+    auto prepared = driver->PrepareOpen(spec, {});
+    ASSERT_TRUE(prepared.has_value());
+
+    auto buffer = prepared->resource().candidate->Allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+    const auto descriptor = buffer->get_descriptor();
+    EXPECT_EQ(descriptor.protocol_, "cxl");
+    EXPECT_EQ(descriptor.transport_endpoint_, spec.name);
+}
+
+TEST(RegionDriverTest, CxlDriverOwnsCapacityMetricLifetime) {
+    constexpr char kCxlPath[] = "region-driver-cxl-metric";
+    auto& metrics = MasterMetricManager::instance();
+    const int64_t total_before = metrics.get_total_mem_capacity();
+    const int64_t segment_before =
+        metrics.get_segment_total_mem_capacity(kCxlPath);
+
+    {
+        RegionDriverConfig config;
+        config.cxl = CxlRegionDriverConfig{kCxlPath, kRegionSize};
+        auto drivers = CreateRegionDrivers(config);
+        ASSERT_TRUE(drivers.has_value());
+        EXPECT_EQ(metrics.get_total_mem_capacity(),
+                  total_before + static_cast<int64_t>(kRegionSize));
+        EXPECT_EQ(metrics.get_segment_total_mem_capacity(kCxlPath),
+                  segment_before + static_cast<int64_t>(kRegionSize));
+    }
+
+    EXPECT_EQ(metrics.get_total_mem_capacity(), total_before);
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(kCxlPath), segment_before);
+}
+
+TEST(RegionDriverTest, InvalidCxlConfigIsReturnedExplicitly) {
+    RegionDriverConfig config;
+    config.cxl =
+        CxlRegionDriverConfig{"cxl-test", facebook::cachelib::Slab::kSize + 1};
+
+    auto drivers = CreateRegionDrivers(config);
+    ASSERT_FALSE(drivers.has_value());
+    EXPECT_EQ(drivers.error(), ErrorCode::INVALID_PARAMS);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/registered_pinned_memory_test.cpp b/mooncake-store/tests/registered_pinned_memory_test.cpp
index 04219025e3..3e52fda240 100644
--- a/mooncake-store/tests/registered_pinned_memory_test.cpp
+++ b/mooncake-store/tests/registered_pinned_memory_test.cpp
@@ -1,7 +1,10 @@
 #define MOONCAKE_STORE_TEST
 #include "../src/registered_pinned_memory.h"
+#include "../src/config/registered_pinned_memory_config.h"
 
 #include <array>
+#include <cstdlib>
+#include <optional>
 
 #include <gtest/gtest.h>
 
@@ -11,6 +14,70 @@ namespace {
 using Manager = RegisteredPinnedMemoryManager;
 using UnregisterResult = Manager::UnregisterResult;
 
+class ScopedEnvVar {
+   public:
+    explicit ScopedEnvVar(const char* name) : name_(name) {
+        if (const char* value = std::getenv(name)) {
+            original_ = value;
+        }
+        unsetenv(name_.c_str());
+    }
+
+    ~ScopedEnvVar() {
+        if (original_.has_value()) {
+            setenv(name_.c_str(), original_->c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ScopedEnvVar(const ScopedEnvVar&) = delete;
+    ScopedEnvVar& operator=(const ScopedEnvVar&) = delete;
+
+    void Set(const char* value) { setenv(name_.c_str(), value, 1); }
+
+   private:
+    std::string name_;
+    std::optional<std::string> original_;
+};
+
+class RegisteredPinnedMemoryConfigTest : public ::testing::Test {
+   protected:
+    ScopedEnvVar max_bytes{"MC_STORE_PIN_MEMORY_MAX_BYTES"};
+};
+
+TEST_F(RegisteredPinnedMemoryConfigTest, UnsetAndEmptyDisableWithoutWarning) {
+    ::testing::internal::CaptureStderr();
+    EXPECT_EQ(RegisteredPinnedMemoryConfig::FromEnvironment().max_bytes, 0);
+    EXPECT_TRUE(::testing::internal::GetCapturedStderr().empty());
+
+    max_bytes.Set("");
+    ::testing::internal::CaptureStderr();
+    EXPECT_EQ(RegisteredPinnedMemoryConfig::FromEnvironment().max_bytes, 0);
+    EXPECT_TRUE(::testing::internal::GetCapturedStderr().empty());
+}
+
+TEST_F(RegisteredPinnedMemoryConfigTest, ReadsZeroAndPositiveByteLimits) {
+    max_bytes.Set("0");
+    EXPECT_EQ(RegisteredPinnedMemoryConfig::FromEnvironment().max_bytes, 0);
+
+    max_bytes.Set(" 4096\t");
+    EXPECT_EQ(RegisteredPinnedMemoryConfig::FromEnvironment().max_bytes, 4096);
+}
+
+TEST_F(RegisteredPinnedMemoryConfigTest, InvalidValuesWarnAndDisable) {
+    for (const char* value :
+         {"-1", "+1", "1suffix", "   ", "18446744073709551616"}) {
+        max_bytes.Set(value);
+        ::testing::internal::CaptureStderr();
+        EXPECT_EQ(RegisteredPinnedMemoryConfig::FromEnvironment().max_bytes, 0)
+            << value;
+        const std::string logs = ::testing::internal::GetCapturedStderr();
+        EXPECT_NE(logs.find("MC_STORE_PIN_MEMORY_MAX_BYTES"), std::string::npos)
+            << value;
+    }
+}
+
 struct FakePinState {
     bool register_succeeds = true;
     UnregisterResult unregister_result = UnregisterResult::kSuccess;
@@ -44,7 +111,7 @@ class RegisteredPinnedMemoryManagerTest : public ::testing::Test {
     void SetUp() override { State() = FakePinState(); }
 
     Manager MakeManager(size_t limit) {
-        return Manager({true, limit}, {FakeRegister, FakeUnregister});
+        return Manager({.max_bytes = limit}, {FakeRegister, FakeUnregister});
     }
 
     std::shared_ptr<RegisteredPinnedRegion> Pin(Manager& manager, size_t offset,
diff --git a/mooncake-store/tests/replica_allocator_test.cpp b/mooncake-store/tests/replica_allocator_test.cpp
new file mode 100644
index 0000000000..bc655a8a6e
--- /dev/null
+++ b/mooncake-store/tests/replica_allocator_test.cpp
@@ -0,0 +1,515 @@
+#include "segment/catalog.h"
+#include "placement/replica_allocator.h"
+
+#include <gtest/gtest.h>
+
+#include <memory>
+#include <set>
+#include <shared_mutex>
+#include <string>
+#include <vector>
+
+#include "local_ssd/manager.h"
+#include "placement/index.h"
+#include "test_buffer_allocator.h"
+
+namespace mooncake::test {
+namespace {
+
+constexpr size_t kCapacity = 1U << 20;
+
+class TestAllocationCandidate final : public AllocationCandidate {
+   public:
+    TestAllocationCandidate(std::shared_ptr<TestBufferAllocator> allocator,
+                            bool is_cxl, std::string cxl_binding)
+        : AllocationCandidate(std::move(allocator)),
+          is_cxl_(is_cxl),
+          cxl_binding_(std::move(cxl_binding)) {}
+
+    std::unique_ptr<AllocatedBuffer> Allocate(size_t size) const override {
+        auto buffer = allocator().allocate(size);
+        if (buffer && is_cxl_) {
+            buffer->change_to_cxl(cxl_binding_);
+        }
+        return buffer;
+    }
+
+    AllocationCandidateKind Kind() const noexcept override {
+        return is_cxl_ ? AllocationCandidateKind::CXL
+                       : AllocationCandidateKind::NATIVE;
+    }
+
+   private:
+    bool is_cxl_;
+    std::string cxl_binding_;
+};
+
+class PlacementState {
+   public:
+    TestBufferAllocator* Add(std::string name, std::string endpoint,
+                             size_t used = 0, bool is_cxl = false,
+                             std::string cxl_binding = {},
+                             std::string host = {}) {
+        auto allocator = std::make_shared<TestBufferAllocator>(
+            name, std::move(endpoint), kCapacity,
+            is_cxl ? DEFAULT_CXL_BASE : next_base_);
+        next_base_ += kCapacity + 4096;
+        allocator->SetUsed(used);
+        auto candidate = std::make_unique<TestAllocationCandidate>(
+            allocator, is_cxl, std::move(cxl_binding));
+        EXPECT_TRUE(index.AddCandidate(name, *candidate, host));
+        auto* result = allocator.get();
+        allocators.push_back(std::move(allocator));
+        candidates.push_back(std::move(candidate));
+        return result;
+    }
+
+    ScopedPlacementReadAccess Access() { return {index, catalog, mutex}; }
+
+    PlacementIndex index;
+    void Metadata(std::string name, UUID client) {
+        Segment segment;
+        segment.id = generate_uuid();
+        segment.name = std::move(name);
+        ASSERT_EQ(catalog.Register({segment, client, SegmentStatus::OK,
+                                    RegionKind::HOST_MEMORY}),
+                  ErrorCode::OK);
+    }
+    RegionCatalog catalog;
+    LocalSsdManager local_ssd;
+    std::vector<std::shared_ptr<TestBufferAllocator>> allocators;
+    std::vector<std::unique_ptr<AllocationCandidate>> candidates;
+    std::shared_mutex mutex;
+
+   private:
+    uintptr_t next_base_{0x100000000ULL};
+};
+
+ReplicaAllocationRequest Request(size_t replica_count = 1) {
+    ReplicaAllocationRequest request;
+    request.replicas.size = 4096;
+    request.replicas.count = replica_count;
+    return request;
+}
+
+std::set<std::string> Endpoints(const std::vector<Replica>& replicas) {
+    std::set<std::string> result;
+    for (const auto& replica : replicas) {
+        result.insert(ReplicaEndpoint(replica));
+    }
+    return result;
+}
+
+}  // namespace
+
+TEST(PlacementIndexTest,
+     KeepsPointersStableAndRemovesCandidateSetsWithSwapPop) {
+    PlacementState state;
+    state.Add("a", "a");
+    state.Add("b", "b");
+    state.Add("c", "c");
+    auto* a = state.index.Find("a", AllocationCandidateKind::NATIVE);
+    auto* c = state.index.Find("c", AllocationCandidateKind::NATIVE);
+
+    for (size_t i = 0; i < 64; ++i) {
+        state.Add("extra-" + std::to_string(i),
+                  "endpoint-" + std::to_string(i));
+    }
+    ASSERT_TRUE(state.index.RemoveCandidate("b", *state.candidates[1], {}));
+    EXPECT_EQ(state.index.Find("a", AllocationCandidateKind::NATIVE), a);
+    EXPECT_EQ(state.index.Find("c", AllocationCandidateKind::NATIVE), c);
+    EXPECT_EQ(state.index.Find("b", AllocationCandidateKind::NATIVE), nullptr);
+}
+
+TEST(PlacementIndexTest, UpdatesCandidatesWithoutReplacingEntry) {
+    PlacementState state;
+    state.Add("shared", "first");
+    state.Add("shared", "second");
+    const auto* entry =
+        state.index.Find("shared", AllocationCandidateKind::NATIVE);
+    ASSERT_NE(entry, nullptr);
+    EXPECT_FALSE(state.index.AddCandidate("shared", *state.candidates[0], {}));
+    EXPECT_EQ(entry->candidates.size(), 2U);
+
+    EXPECT_TRUE(state.index.ReplaceCandidate("shared", *state.candidates[0],
+                                             *state.candidates[0], {}));
+    EXPECT_FALSE(state.index.ReplaceCandidate("shared", *state.candidates[0],
+                                              *state.candidates[1], {}));
+    EXPECT_NE(entry->candidates.find(state.candidates[0].get()),
+              entry->candidates.end());
+    EXPECT_EQ(entry->candidates.size(), 2U);
+
+    auto allocator = std::make_shared<TestBufferAllocator>(
+        "shared", "replacement", kCapacity);
+    TestAllocationCandidate replacement(allocator, false, "");
+    ASSERT_TRUE(state.index.ReplaceCandidate("shared", *state.candidates[0],
+                                             replacement, {}));
+    EXPECT_EQ(state.index.Find("shared", AllocationCandidateKind::NATIVE),
+              entry);
+    EXPECT_FALSE(
+        state.index.RemoveCandidate("shared", *state.candidates[0], {}));
+    ASSERT_TRUE(
+        state.index.RemoveCandidate("shared", *state.candidates[1], {}));
+    ASSERT_EQ(entry->candidates.size(), 1U);
+    {
+        auto access = state.Access();
+        auto result = ReplicaAllocator(PreferredOnlyPlacementPolicy(
+                                           AllocationCandidateKind::NATIVE))
+                          .AllocateFrom(access, 4096, "shared");
+        ASSERT_TRUE(result.has_value());
+        EXPECT_EQ(ReplicaEndpoint(*result), "replacement");
+    }
+    ASSERT_TRUE(state.index.RemoveCandidate("shared", replacement, {}));
+    EXPECT_EQ(state.index.Find("shared", AllocationCandidateKind::NATIVE),
+              nullptr);
+    EXPECT_TRUE(
+        state.index.active_entries(AllocationCandidateKind::NATIVE).empty());
+}
+
+TEST(ReplicaAllocatorTest, SameNameFallbackStaysWithinOneCandidateSet) {
+    PlacementState state;
+    auto* failing = state.Add("shared", "bad");
+    failing->SetAlwaysFail();
+    state.Add("shared", "good");
+    state.Add("other", "other");
+
+    for (size_t i = 0; i < 64; ++i) {
+        auto access = state.Access();
+        auto result = ReplicaAllocator(RandomPlacementPolicy{})
+                          .Allocate(access, Request(2));
+        ASSERT_TRUE(result.has_value());
+        EXPECT_EQ(Endpoints(*result), (std::set<std::string>{"good", "other"}));
+    }
+    EXPECT_GT(failing->allocation_calls(), 0U);
+}
+
+TEST(ReplicaAllocatorTest, FailedPreferencesFallBackBestEffort) {
+    PlacementState state;
+    state.Add("failed", "failed")->SetAlwaysFail();
+    state.Add("preferred", "preferred");
+    state.Add("fallback", "fallback");
+    auto* excluded_allocator = state.Add("excluded", "excluded");
+    std::vector<std::string> preferred{"failed", "excluded", "preferred",
+                                       "preferred"};
+    std::vector<std::string> excluded{"unused", "excluded", "excluded"};
+
+    auto request = Request(3);
+    request.placement.preferred_segment_names = preferred;
+    request.placement.excluded_segment_names = excluded;
+    auto access = state.Access();
+    auto result =
+        ReplicaAllocator(RandomPlacementPolicy{}).Allocate(access, request);
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->size(), 2U);
+    EXPECT_EQ(excluded_allocator->allocation_calls(), 0U);
+    EXPECT_EQ(Endpoints(*result),
+              (std::set<std::string>{"fallback", "preferred"}));
+}
+
+TEST(ReplicaAllocatorTest, MembershipIsResetBetweenOrderedRequests) {
+    PlacementState state;
+    state.Add("a", "a", 0, false, {}, "writer");
+    state.Add("b", "b", 0, false, {}, "writer");
+    auto access = state.Access();
+    ReplicaAllocator allocator(RandomPlacementPolicy{});
+    std::vector<std::string> preferred{"b", "b", "a"};
+    std::vector<std::string> excluded{"a"};
+    auto request = Request(2);
+    request.placement.preferred_segment_names = preferred;
+    request.placement.excluded_segment_names = excluded;
+    {
+        auto first = allocator.Allocate(access, request);
+        ASSERT_TRUE(first.has_value());
+        ASSERT_EQ(first->size(), 1U);
+        EXPECT_EQ(ReplicaEndpoint(first->front()), "b");
+    }
+    preferred = {"a", "a", "b"};
+    request.placement.preferred_segment_names = preferred;
+    request.placement.excluded_segment_names = {};
+    auto second = allocator.Allocate(access, request);
+    ASSERT_TRUE(second.has_value());
+    ASSERT_EQ(second->size(), 2U);
+    EXPECT_EQ(ReplicaEndpoint((*second)[0]), "a");
+    EXPECT_EQ(ReplicaEndpoint((*second)[1]), "b");
+    preferred = {"b", "b"};
+    request.placement.preferred_segment_names = preferred;
+    request.host_affinity = {"writer", "key"};
+    auto local =
+        ReplicaAllocator(LocalFirstPlacementPolicy{}).Allocate(access, request);
+    ASSERT_TRUE(local.has_value());
+    ASSERT_EQ(local->size(), 2U);
+    EXPECT_EQ(ReplicaEndpoint((*local)[0]), "b");
+    EXPECT_EQ(ReplicaEndpoint((*local)[1]), "a");
+}
+
+TEST(ReplicaAllocatorTest, RankedPoliciesUseFreeCapacityFeedback) {
+    PlacementState state;
+    state.Add("full", "full", kCapacity - 4096);
+    auto* best = state.Add("best", "best", 0);
+    state.Add("second", "second", kCapacity / 2);
+    best->SetAlwaysFail();
+
+    auto access = state.Access();
+    auto result = ReplicaAllocator(FreeRatioFirstPlacementPolicy{})
+                      .Allocate(access, Request());
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(ReplicaEndpoint(result->front()), "second");
+    EXPECT_GT(best->allocation_calls(), 0U);
+}
+
+TEST(ReplicaAllocatorTest, SsdPolicyUsesSegmentNameOwner) {
+    PlacementState state;
+    const UUID low{1, 1};
+    const UUID high{2, 2};
+    state.Add("low", "low");
+    state.Add("high", "high");
+    state.Metadata("low", low);
+    state.Metadata("high", high);
+    ASSERT_EQ(state.local_ssd.RegisterClient(low, true), ErrorCode::OK);
+    ASSERT_EQ(state.local_ssd.RegisterClient(high, true), ErrorCode::OK);
+    ASSERT_TRUE(state.local_ssd.ReportCapacity(low, 1000).has_value());
+    ASSERT_TRUE(state.local_ssd.ReportCapacity(high, 1000).has_value());
+    ASSERT_TRUE(state.local_ssd.AdjustUsedBytes(low, 900));
+    ASSERT_TRUE(state.local_ssd.AdjustUsedBytes(high, 100));
+
+    auto access = state.Access();
+    auto result = ReplicaAllocator(SsdFreeRatioFirstPlacementPolicy{
+                                       LocalSSDMetricsView(state.local_ssd)})
+                      .Allocate(access, Request());
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(ReplicaEndpoint(result->front()), "high");
+}
+
+TEST(ReplicaAllocatorTest, LocalPolicyConsumesHostOrdering) {
+    PlacementState state;
+    state.Add("remote", "remote");
+    state.Add("local-a", "local-a", 0, false, {}, "writer");
+    state.Add("local-b", "local-b", 0, false, {}, "writer");
+
+    auto request = Request(2);
+    request.host_affinity.writer_host_id = "writer";
+    request.host_affinity.object_key = "key";
+    auto access = state.Access();
+    std::vector<std::string_view> expected;
+    access.GetView().VisitHostOrderedSegmentNames("writer", "key",
+                                                  [&](auto name) {
+                                                      expected.push_back(name);
+                                                      return false;
+                                                  });
+    auto result =
+        ReplicaAllocator(LocalFirstPlacementPolicy{}).Allocate(access, request);
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->size(), 2U);
+    EXPECT_EQ(ReplicaEndpoint((*result)[0]), expected[0]);
+    EXPECT_EQ(ReplicaEndpoint((*result)[1]), expected[1]);
+}
+
+TEST(ReplicaAllocatorTest, LocalPlacementSkipsUnavailableKindsAndFallsBack) {
+    PlacementState state;
+    state.Add("cxl-only", "cxl-only", 0, true, {}, "writer");
+    auto* full = state.Add("full", "full", 0, false, {}, "writer");
+    full->SetAlwaysFail();
+    state.Add("local", "local", 0, false, {}, "writer");
+    state.Add("remote", "remote");
+    auto access = state.Access();
+    auto request = Request(2);
+    request.host_affinity = {"writer", "key"};
+    auto result =
+        ReplicaAllocator(LocalFirstPlacementPolicy{}).Allocate(access, request);
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->size(), 2U);
+    EXPECT_EQ(Endpoints(*result), (std::set<std::string>{"local", "remote"}));
+}
+
+TEST(ReplicaAllocatorTest, NamedAllocationSelectsKindWithoutFallback) {
+    PlacementState state;
+    auto* native = state.Add("mixed", "native");
+    auto* cxl = state.Add("mixed", "global-cxl", 0, true, "client-binding");
+    cxl->SetAlwaysFail();
+    auto access = state.Access();
+    auto failed = ReplicaAllocator(PreferredOnlyPlacementPolicy(
+                                       AllocationCandidateKind::CXL))
+                      .AllocateFrom(access, 4096, "mixed");
+    ASSERT_FALSE(failed.has_value());
+    EXPECT_EQ(failed.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_EQ(native->allocation_calls(), 0U);
+    EXPECT_GT(cxl->allocation_calls(), 0U);
+    cxl->SetAlwaysFail(false);
+    auto result = ReplicaAllocator(PreferredOnlyPlacementPolicy(
+                                       AllocationCandidateKind::CXL))
+                      .AllocateFrom(access, 4096, "mixed");
+    ASSERT_TRUE(result.has_value());
+    auto descriptor =
+        result->get_descriptor().get_memory_descriptor().buffer_descriptor;
+    EXPECT_EQ(descriptor.protocol_, "cxl");
+    EXPECT_EQ(descriptor.transport_endpoint_, "client-binding");
+    auto native_result = ReplicaAllocator(RandomPlacementPolicy{})
+                             .AllocateFrom(access, 4096, "mixed");
+    ASSERT_TRUE(native_result.has_value());
+    EXPECT_EQ(ReplicaEndpoint(*native_result), "native");
+}
+
+TEST(ReplicaAllocatorTest,
+     NamedAllocationValidatesRequestAndRetriesSameSegment) {
+    PlacementState state;
+    state.Add("logical", "bad")->SetAlwaysFail();
+    state.Add("logical", "good");
+    auto access = state.Access();
+    auto result = ReplicaAllocator(PreferredOnlyPlacementPolicy(
+                                       AllocationCandidateKind::NATIVE))
+                      .AllocateFrom(access, 4096, "logical");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(ReplicaEndpoint(*result), "good");
+    EXPECT_EQ(ReplicaAllocator(
+                  PreferredOnlyPlacementPolicy(AllocationCandidateKind::NATIVE))
+                  .AllocateFrom(access, 4096, "missing")
+                  .error(),
+              ErrorCode::SEGMENT_NOT_FOUND);
+    EXPECT_EQ(ReplicaAllocator(
+                  PreferredOnlyPlacementPolicy(AllocationCandidateKind::NATIVE))
+                  .AllocateFrom(access, 4096, "")
+                  .error(),
+              ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(ReplicaAllocator(
+                  PreferredOnlyPlacementPolicy(AllocationCandidateKind::NATIVE))
+                  .AllocateFrom(access, 0, "logical")
+                  .error(),
+              ErrorCode::INVALID_PARAMS);
+}
+
+TEST(ReplicaAllocatorTest, PreferredOnlyRequiresSegmentName) {
+    PlacementState state;
+    ReplicaAllocator allocator(
+        PreferredOnlyPlacementPolicy{AllocationCandidateKind::CXL});
+    {
+        auto access = state.Access();
+        EXPECT_EQ(allocator.Allocate(access, Request()).error(),
+                  ErrorCode::INVALID_PARAMS);
+    }
+
+    state.Add("cxl", "global-cxl", 0, true, "client-binding");
+    {
+        auto access = state.Access();
+        EXPECT_EQ(allocator.Allocate(access, Request()).error(),
+                  ErrorCode::INVALID_PARAMS);
+    }
+
+    auto request = Request();
+    request.placement.preferred_segment_name = "cxl";
+    auto access = state.Access();
+    auto result = allocator.Allocate(access, request);
+    ASSERT_TRUE(result.has_value());
+    auto descriptor = result->front()
+                          .get_descriptor()
+                          .get_memory_descriptor()
+                          .buffer_descriptor;
+    EXPECT_EQ(descriptor.protocol_, "cxl");
+    EXPECT_EQ(descriptor.transport_endpoint_, "client-binding");
+}
+
+TEST(ReplicaAllocatorTest, PreferredOnlySelectsKindWithoutFallback) {
+    PlacementState state;
+    auto* native = state.Add("mixed", "native");
+    auto* cxl = state.Add("mixed", "global-cxl", 0, true, "client-binding");
+    cxl->SetAlwaysFail();
+    EXPECT_NE(state.index.Find("mixed", AllocationCandidateKind::NATIVE),
+              state.index.Find("mixed", AllocationCandidateKind::CXL));
+
+    auto request = Request();
+    request.placement.preferred_segment_name = "mixed";
+    {
+        ReplicaAllocator allocator(
+            PreferredOnlyPlacementPolicy{AllocationCandidateKind::CXL});
+        auto access = state.Access();
+        auto result = allocator.Allocate(access, request);
+        ASSERT_FALSE(result.has_value());
+        EXPECT_EQ(result.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+        EXPECT_EQ(native->allocation_calls(), 0U);
+        EXPECT_GT(cxl->allocation_calls(), 0U);
+    }
+    {
+        ReplicaAllocator allocator(
+            PreferredOnlyPlacementPolicy{AllocationCandidateKind::NATIVE});
+        auto access = state.Access();
+        auto result = allocator.Allocate(access, request);
+        ASSERT_TRUE(result.has_value());
+        EXPECT_EQ(ReplicaEndpoint(result->front()), "native");
+    }
+}
+
+TEST(PlacementIndexTest, HostNamesCountAcrossKindsAndIgnoreFailedMutations) {
+    PlacementState state;
+    state.Add("shared", "native", 0, false, {}, "host");
+    state.Add("shared", "cxl", 0, true, {}, "host");
+    auto names = [&] {
+        std::vector<std::string> result;
+        state.index.VisitHostOrderedSegmentNames("host", "key", [&](auto name) {
+            result.emplace_back(name);
+            return false;
+        });
+        return result;
+    };
+    EXPECT_FALSE(
+        state.index.AddCandidate("shared", *state.candidates[0], "host"));
+    EXPECT_EQ(names(), (std::vector<std::string>{"shared"}));
+    TestAllocationCandidate missing(state.allocators[0], false, "");
+    TestAllocationCandidate replacement(state.allocators[1], true, "");
+    EXPECT_FALSE(
+        state.index.ReplaceCandidate("shared", missing, replacement, "host"));
+    ASSERT_TRUE(state.index.ReplaceCandidate("shared", *state.candidates[0],
+                                             replacement, "host"));
+    ASSERT_TRUE(state.index.RemoveCandidate("shared", replacement, "host"));
+    EXPECT_EQ(names(), (std::vector<std::string>{"shared"}));
+    ASSERT_TRUE(
+        state.index.RemoveCandidate("shared", *state.candidates[1], "host"));
+    EXPECT_TRUE(names().empty());
+    EXPECT_FALSE(
+        state.index.RemoveCandidate("shared", *state.candidates[1], "host"));
+    EXPECT_TRUE(names().empty());
+}
+
+TEST(ReplicaAllocatorTest, HostOrderingWrapsAndDeduplicatesCatalogRecords) {
+    PlacementState state;
+    state.Add("unbound", "unbound");
+    state.Add("a", "a", 0, false, {}, "host-b");
+    state.Add("a", "a-duplicate", 0, false, {}, "host-b");
+    state.Add("b", "b", 0, false, {}, "host-b");
+    state.Add("a", "a-other-host", 0, false, {}, "host-d");
+    state.Add("c", "c", 0, false, {}, "host-d");
+    std::string key;
+    while (std::hash<std::string_view>{}(key) % 2 != 0) key += 'x';
+    auto names = [&](std::string_view host) {
+        auto access = state.Access();
+        std::vector<std::string_view> names;
+        access.GetView().VisitHostOrderedSegmentNames(host, key,
+                                                      [&](auto name) {
+                                                          names.push_back(name);
+                                                          return false;
+                                                      });
+        return std::vector<std::string>(names.begin(), names.end());
+    };
+    EXPECT_EQ(names("host-c"), (std::vector<std::string>{"a", "c", "b"}));
+    EXPECT_EQ(names("host-z"), (std::vector<std::string>{"a", "b", "c"}));
+    EXPECT_TRUE(names("").empty());
+    {
+        auto access = state.Access();
+        std::vector<std::string> visited;
+        access.GetView().VisitHostOrderedSegmentNames(
+            "host-c", key, [&](auto name) {
+                visited.emplace_back(name);
+                return true;
+            });
+        EXPECT_EQ(visited, (std::vector<std::string>{"a"}));
+    }
+    ASSERT_TRUE(
+        state.index.RemoveCandidate("a", *state.candidates[1], "host-b"));
+    EXPECT_EQ(names("host-z"), (std::vector<std::string>{"a", "b", "c"}));
+    ASSERT_TRUE(
+        state.index.RemoveCandidate("a", *state.candidates[2], "host-b"));
+    EXPECT_EQ(names("host-z"), (std::vector<std::string>{"b", "a", "c"}));
+    ASSERT_TRUE(
+        state.index.RemoveCandidate("a", *state.candidates[4], "host-d"));
+    EXPECT_EQ(names("host-c"), (std::vector<std::string>{"c", "b"}));
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/replica_selection_config_test.cpp b/mooncake-store/tests/replica_selection_config_test.cpp
new file mode 100644
index 0000000000..09ac44bc85
--- /dev/null
+++ b/mooncake-store/tests/replica_selection_config_test.cpp
@@ -0,0 +1,72 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "config/replica_selection_config.h"
+
+namespace mooncake {
+namespace {
+
+class ReplicaSelectionConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv("MC_STORE_REPLICA_SCORING")) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv("MC_STORE_REPLICA_SCORING"), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv("MC_STORE_REPLICA_SCORING", original_->c_str(), 1),
+                      0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_STORE_REPLICA_SCORING"), 0);
+        }
+    }
+
+   private:
+    std::optional<std::string> original_;
+};
+
+TEST_F(ReplicaSelectionConfigTest, UnsetDisablesScoring) {
+    EXPECT_FALSE(
+        ReplicaSelectionConfig::FromEnvironment().remote_scoring_enabled);
+}
+
+TEST_F(ReplicaSelectionConfigTest, OnlyExactOneEnablesScoring) {
+    struct Case {
+        const char* value;
+        bool enabled;
+    };
+    for (const auto& test_case :
+         {Case{"1", true}, Case{"", false}, Case{"0", false},
+          Case{"true", false}, Case{"TRUE", false}, Case{"yes", false},
+          Case{"on", false}, Case{"false", false}, Case{"-1", false},
+          Case{"2", false}, Case{"01", false}, Case{"+1", false},
+          Case{" 1", false}, Case{"1 ", false}, Case{"1\n", false},
+          Case{"1suffix", false}}) {
+        SCOPED_TRACE(test_case.value);
+        ASSERT_EQ(setenv("MC_STORE_REPLICA_SCORING", test_case.value, 1), 0);
+        testing::internal::CaptureStderr();
+        const auto config = ReplicaSelectionConfig::FromEnvironment();
+        const auto diagnostics = testing::internal::GetCapturedStderr();
+        EXPECT_EQ(config.remote_scoring_enabled, test_case.enabled);
+        EXPECT_TRUE(diagnostics.empty());
+    }
+}
+
+TEST_F(ReplicaSelectionConfigTest, NewConfigsReadTheCurrentEnvironment) {
+    ASSERT_EQ(setenv("MC_STORE_REPLICA_SCORING", "1", 1), 0);
+    const auto enabled_config = ReplicaSelectionConfig::FromEnvironment();
+
+    ASSERT_EQ(unsetenv("MC_STORE_REPLICA_SCORING"), 0);
+    EXPECT_FALSE(
+        ReplicaSelectionConfig::FromEnvironment().remote_scoring_enabled);
+    EXPECT_TRUE(enabled_config.remote_scoring_enabled);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/replica_selection_test.cpp b/mooncake-store/tests/replica_selection_test.cpp
index 388cede25a..4dc097f0a8 100644
--- a/mooncake-store/tests/replica_selection_test.cpp
+++ b/mooncake-store/tests/replica_selection_test.cpp
@@ -10,6 +10,8 @@
 #include <gtest/gtest.h>
 
 #include <atomic>
+#include <cstdlib>
+#include <optional>
 #include <string>
 #include <thread>
 #include <unordered_set>
@@ -67,11 +69,37 @@ Replica::Descriptor MakeLocalDisk(const std::string& endpoint) {
     return d;
 }
 
-// A test fixture that guarantees scoring state is reset between tests, since
-// the enable flag / injected scorer are process-wide.
+Replica::Descriptor MakeDfs(const std::string& path) {
+    Replica::Descriptor d;
+    d.id = 0;
+    d.descriptor_variant = DistributedFSDescriptor{path, 0, 1024, 4096, 0};
+    d.status = ReplicaStatus::COMPLETE;
+    return d;
+}
+
+// Restore the environment and injected scorer between tests. The cached
+// environment setting intentionally remains fixed for the process lifetime.
 class ReplicaSelectionTest : public ::testing::Test {
    protected:
-    void TearDown() override { SetRemoteReplicaScorer(nullptr); }
+    void SetUp() override {
+        if (const char* value = std::getenv("MC_STORE_REPLICA_SCORING")) {
+            original_env_ = value;
+        }
+    }
+
+    void TearDown() override {
+        SetRemoteReplicaScorer(nullptr);
+        if (original_env_.has_value()) {
+            EXPECT_EQ(
+                setenv("MC_STORE_REPLICA_SCORING", original_env_->c_str(), 1),
+                0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_STORE_REPLICA_SCORING"), 0);
+        }
+    }
+
+   private:
+    std::optional<std::string> original_env_;
 };
 
 // --- Base policy (scoring off): behaviour must be unchanged --------------
@@ -89,6 +117,65 @@ TEST_F(ReplicaSelectionTest, LocalMemoryAlwaysWins) {
         "nodeB");  // locality beats protocol
 }
 
+// Regression for issue #3658: a complete local MEMORY replica must win over a
+// complete local NOF replica regardless of the order they appear in the list.
+// ObjectMetadata preserves insertion order, and promotion appends a new MEMORY
+// replica to existing metadata, so a MEMORY replica may legally appear after a
+// NOF replica. The session planner supports MEMORY and DFS, but not NOF, so
+// selecting NOF here would regress a session that has a usable MEMORY replica.
+TEST_F(ReplicaSelectionTest, LocalMemoryBeatsLocalNoFInBothOrders) {
+    std::unordered_set<std::string> local = {"memB", "nofB"};
+
+    // local NOF listed before local MEMORY
+    std::vector<Replica::Descriptor> nof_first = {
+        MakeNoF("nofB"),
+        MakeMemory("memB", "tcp"),
+    };
+    const auto* sel = SelectBestReplica(nof_first, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_memory_replica());
+    EXPECT_EQ(
+        sel->get_memory_descriptor().buffer_descriptor.transport_endpoint_,
+        "memB");
+
+    // local MEMORY listed before local NOF (the previously-correct order)
+    std::vector<Replica::Descriptor> mem_first = {
+        MakeMemory("memB", "tcp"),
+        MakeNoF("nofB"),
+    };
+    sel = SelectBestReplica(mem_first, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_memory_replica());
+    EXPECT_EQ(
+        sel->get_memory_descriptor().buffer_descriptor.transport_endpoint_,
+        "memB");
+}
+
+TEST_F(ReplicaSelectionTest, IncompleteLocalMemoryFallsBackToLocalNoF) {
+    // The local MEMORY replica is not readable yet, so the local NOF_SSD one
+    // remains the best choice.
+    std::unordered_set<std::string> local = {"nodeA"};
+    std::vector<Replica::Descriptor> reps = {
+        MakeNoF("nodeA"),
+        MakeMemory("nodeA", "rdma", ReplicaStatus::PROCESSING),
+    };
+    const auto* sel = SelectBestReplica(reps, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_nof_replica());
+}
+
+TEST_F(ReplicaSelectionTest, LocalNoFPrecedesRemoteMemory) {
+    // Locality still outranks tier for remote MEMORY replicas.
+    std::unordered_set<std::string> local = {"nodeA"};
+    std::vector<Replica::Descriptor> reps = {
+        MakeNoF("nodeA"),
+        MakeMemory("nodeB", "rdma"),
+    };
+    const auto* sel = SelectBestReplica(reps, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_nof_replica());
+}
+
 TEST_F(ReplicaSelectionTest, ScoringOffKeepsFirstRemoteMemory) {
     // No scorer injected and env not set -> must return the FIRST remote
     // MEMORY.
@@ -172,6 +259,19 @@ TEST_F(ReplicaSelectionTest, EnvironmentOptInUsesBuiltinScorer) {
     EXPECT_EQ(sel->get_memory_descriptor().buffer_descriptor.protocol_, "rdma");
 }
 
+TEST_F(ReplicaSelectionTest, EnvironmentIsCachedButInjectedScorerRemainsLive) {
+    const bool initially_enabled = RemoteReplicaScoringEnabled();
+    ASSERT_EQ(
+        setenv("MC_STORE_REPLICA_SCORING", initially_enabled ? "0" : "1", 1),
+        0);
+    EXPECT_EQ(RemoteReplicaScoringEnabled(), initially_enabled);
+
+    SetRemoteReplicaScorer(BuiltinRemoteReplicaScore);
+    EXPECT_TRUE(RemoteReplicaScoringEnabled());
+    SetRemoteReplicaScorer(nullptr);
+    EXPECT_EQ(RemoteReplicaScoringEnabled(), initially_enabled);
+}
+
 TEST_F(ReplicaSelectionTest, ScorerTieKeepsMasterOrder) {
     // All equal score -> strictly-less comparison keeps the first one.
     SetRemoteReplicaScorer([](const Replica::Descriptor&) { return 5.0; });
@@ -280,6 +380,28 @@ TEST_F(ReplicaSelectionTest, DiskIsLastCompleteFallback) {
     EXPECT_TRUE(sel->is_disk_replica());
 }
 
+TEST_F(ReplicaSelectionTest, DfsPrecedesDisk) {
+    std::unordered_set<std::string> local;
+    std::vector<Replica::Descriptor> reps = {
+        MakeDisk("/remote/object"),
+        MakeDfs("/dfs/object"),
+    };
+    const auto* sel = SelectBestReplica(reps, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_dfs_replica());
+}
+
+TEST_F(ReplicaSelectionTest, LocalDiskPrecedesDfs) {
+    std::unordered_set<std::string> local;
+    std::vector<Replica::Descriptor> reps = {
+        MakeDfs("/dfs/object"),
+        MakeLocalDisk("nodeA"),
+    };
+    const auto* sel = SelectBestReplica(reps, local);
+    ASSERT_NE(sel, nullptr);
+    EXPECT_TRUE(sel->is_local_disk_replica());
+}
+
 TEST_F(ReplicaSelectionTest, NoCompleteReplicaReturnsNull) {
     std::unordered_set<std::string> local;
     std::vector<Replica::Descriptor> reps = {
diff --git a/mooncake-store/tests/rpc_protocol_config_test.cpp b/mooncake-store/tests/rpc_protocol_config_test.cpp
new file mode 100644
index 0000000000..5a1e979b40
--- /dev/null
+++ b/mooncake-store/tests/rpc_protocol_config_test.cpp
@@ -0,0 +1,66 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "config/rpc_protocol_config.h"
+
+namespace mooncake {
+namespace {
+
+class RpcProtocolConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv(kName)) {
+            original_ = value;
+        }
+        ASSERT_EQ(unsetenv(kName), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv(kName, original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv(kName), 0);
+        }
+    }
+
+    static constexpr const char* kName = "MC_RPC_PROTOCOL";
+    std::optional<std::string> original_;
+};
+
+TEST_F(RpcProtocolConfigTest, OnlyExactRdmaTokenEnablesRdma) {
+    EXPECT_FALSE(RpcProtocolConfig::FromEnvironment().use_rdma);
+
+    struct Case {
+        const char* value;
+        bool expected;
+    };
+    const Case cases[] = {{"", false},      {"rdma", true},   {"RDMA", false},
+                          {" rdma", false}, {"rdma ", false}, {"tcp", false},
+                          {"1", false}};
+    for (const auto& entry : cases) {
+        SCOPED_TRACE(entry.value);
+        ASSERT_EQ(setenv(kName, entry.value, 1), 0);
+        EXPECT_EQ(RpcProtocolConfig::FromEnvironment().use_rdma,
+                  entry.expected);
+    }
+}
+
+TEST_F(RpcProtocolConfigTest, EachConstructionReadsCurrentEnvironment) {
+    const auto unset = RpcProtocolConfig::FromEnvironment();
+
+    ASSERT_EQ(setenv(kName, "rdma", 1), 0);
+    const auto enabled = RpcProtocolConfig::FromEnvironment();
+
+    ASSERT_EQ(setenv(kName, "tcp", 1), 0);
+    const auto disabled = RpcProtocolConfig::FromEnvironment();
+
+    EXPECT_FALSE(unset.use_rdma);
+    EXPECT_TRUE(enabled.use_rdma);
+    EXPECT_FALSE(disabled.use_rdma);
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/rpc_timeout_config_test.cpp b/mooncake-store/tests/rpc_timeout_config_test.cpp
new file mode 100644
index 0000000000..efb5cf5591
--- /dev/null
+++ b/mooncake-store/tests/rpc_timeout_config_test.cpp
@@ -0,0 +1,106 @@
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+#include "config/rpc_timeout_config.h"
+
+namespace mooncake {
+namespace {
+
+class RpcTimeoutConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        for (int i = 0; i < 2; ++i) {
+            if (const char* value = std::getenv(names_[i])) {
+                original_[i] = value;
+            }
+        }
+        for (const char* name : names_) {
+            ASSERT_EQ(unsetenv(name), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (int i = 0; i < 2; ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(names_[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(names_[i]), 0);
+            }
+        }
+    }
+
+    static constexpr const char* names_[] = {"MC_RPC_TIMEOUT_MS",
+                                             "MC_RPC_CONNECT_TIMEOUT_MS"};
+    std::optional<std::string> original_[2];
+};
+
+TEST_F(RpcTimeoutConfigTest, UnsetVariablesLeaveOverridesAbsent) {
+    const auto config = RpcTimeoutConfig::FromEnvironment();
+    EXPECT_FALSE(config.request_timeout.has_value());
+    EXPECT_FALSE(config.connect_timeout.has_value());
+}
+
+TEST_F(RpcTimeoutConfigTest, PreservesLegacyConversionForEachVariable) {
+    struct Case {
+        const char* value;
+        int64_t expected;
+    };
+    const Case cases[] = {
+        {"", 0},
+        {"garbage", 0},
+        {"0", 0},
+        {"1500", 1500},
+        {"-1", -1},
+        {" +42 ", 42},
+        {" \t", 0},
+        {"1500ms", 1500},
+        {"0x10", 0},
+        {"9223372036854775807", std::numeric_limits<int64_t>::max()},
+        {"-9223372036854775808", std::numeric_limits<int64_t>::min()},
+    };
+    for (int i = 0; i < 2; ++i) {
+        SCOPED_TRACE(names_[i]);
+        for (const auto& entry : cases) {
+            SCOPED_TRACE(entry.value);
+            ASSERT_EQ(setenv(names_[i], entry.value, 1), 0);
+            const auto config = RpcTimeoutConfig::FromEnvironment();
+            const auto& selected =
+                i == 0 ? config.request_timeout : config.connect_timeout;
+            const auto& other =
+                i == 0 ? config.connect_timeout : config.request_timeout;
+            ASSERT_TRUE(selected.has_value());
+            EXPECT_EQ(*selected, std::chrono::milliseconds(entry.expected));
+            EXPECT_FALSE(other.has_value());
+        }
+        ASSERT_EQ(unsetenv(names_[i]), 0);
+    }
+}
+
+TEST_F(RpcTimeoutConfigTest, EachConstructionReadsCurrentEnvironment) {
+    ASSERT_EQ(setenv("MC_RPC_TIMEOUT_MS", "1500", 1), 0);
+    ASSERT_EQ(setenv("MC_RPC_CONNECT_TIMEOUT_MS", "1000", 1), 0);
+    const auto original = RpcTimeoutConfig::FromEnvironment();
+
+    ASSERT_EQ(setenv("MC_RPC_TIMEOUT_MS", "0", 1), 0);
+    ASSERT_EQ(setenv("MC_RPC_CONNECT_TIMEOUT_MS", "-1", 1), 0);
+    const auto changed = RpcTimeoutConfig::FromEnvironment();
+    EXPECT_EQ(changed.request_timeout, std::chrono::milliseconds(0));
+    EXPECT_EQ(changed.connect_timeout, std::chrono::milliseconds(-1));
+
+    ASSERT_EQ(unsetenv("MC_RPC_TIMEOUT_MS"), 0);
+    ASSERT_EQ(unsetenv("MC_RPC_CONNECT_TIMEOUT_MS"), 0);
+    const auto cleared = RpcTimeoutConfig::FromEnvironment();
+    EXPECT_FALSE(cleared.request_timeout.has_value());
+    EXPECT_FALSE(cleared.connect_timeout.has_value());
+    EXPECT_EQ(original.request_timeout, std::chrono::milliseconds(1500));
+    EXPECT_EQ(original.connect_timeout, std::chrono::milliseconds(1000));
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/rpc_timeout_test.cpp b/mooncake-store/tests/rpc_timeout_test.cpp
index 310832b42d..a0b5020cc2 100644
--- a/mooncake-store/tests/rpc_timeout_test.cpp
+++ b/mooncake-store/tests/rpc_timeout_test.cpp
@@ -1,10 +1,17 @@
-// Unit tests for the client->master RPC timeout feature.
+// Tests for the client->master and store->store RPC timeout overrides.
 //
 // Covers:
 //   1. The ErrorCode::RPC_TIMEOUT enum value and its toString() mapping.
 //   2. End-to-end: MC_RPC_TIMEOUT_MS shortens the per-request deadline so that
 //      an unresponsive master surfaces ErrorCode::RPC_TIMEOUT (not RPC_FAIL),
 //      and it does so within the configured budget rather than the 30s default.
+//   3. The offload requester honors the same timeout and error mapping.
+//   4. MasterClient does not add its own retry delay around a failed leader
+//      connection; the HA monitor owns that retry schedule.
+//   5. HA MasterClient bounds failed leader connections while non-HA clients
+//      retain the default initial-connection retry policy.
+//   6. HA MasterClient bounds control-plane probes without changing the
+//      foreground RPC retry policy.
 //
 // The end-to-end test points a MasterClient at a "black hole" TCP listener: a
 // socket that accepts the connection (so connect() succeeds) but never sends a
@@ -19,16 +26,51 @@
 #include <sys/socket.h>
 #include <unistd.h>
 
+#include <atomic>
 #include <chrono>
 #include <cstdlib>
+#include <thread>
+#include <vector>
+#include <optional>
 #include <string>
 
 #include "master_client.h"
+#include "pyclient.h"
+#include "test_server_helpers.h"
 #include "types.h"
 
 namespace mooncake {
 namespace {
 
+class RpcTimeoutEnvTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        for (int i = 0; i < 3; ++i) {
+            if (const char* value = std::getenv(names_[i])) {
+                original_[i] = value;
+            }
+        }
+        // These integration tests use TCP regardless of the ambient protocol.
+        for (const char* name : names_) {
+            ASSERT_EQ(unsetenv(name), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (int i = 0; i < 3; ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(names_[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(names_[i]), 0);
+            }
+        }
+    }
+
+    static constexpr const char* names_[] = {
+        "MC_RPC_TIMEOUT_MS", "MC_RPC_CONNECT_TIMEOUT_MS", "MC_RPC_PROTOCOL"};
+    std::optional<std::string> original_[3];
+};
+
 // A TCP listener on 127.0.0.1 that accepts connections but never replies.
 // The kernel completes the TCP handshake for backlogged connections, so a
 // client's connect() succeeds; any subsequent request simply never gets a
@@ -84,7 +126,7 @@ TEST(RpcTimeoutTest, ErrorCodeValueAndString) {
 
 // End-to-end: a small MC_RPC_TIMEOUT_MS must be honored by every RPC and turn
 // an unanswered call into ErrorCode::RPC_TIMEOUT well before the 30s default.
-TEST(RpcTimeoutTest, RpcTimesOutAgainstUnresponsiveMaster) {
+TEST_F(RpcTimeoutEnvTest, RpcTimesOutAgainstUnresponsiveMaster) {
     constexpr int kTimeoutMs = 500;
 
     // The constructor reads MC_RPC_TIMEOUT_MS, so it must be set beforehand.
@@ -102,8 +144,6 @@ TEST(RpcTimeoutTest, RpcTimesOutAgainstUnresponsiveMaster) {
                              std::chrono::steady_clock::now() - start)
                              .count();
 
-    ::unsetenv("MC_RPC_TIMEOUT_MS");
-
     // The unanswered ServiceReady RPC must be reported as a timeout, not as a
     // generic RPC failure.
     EXPECT_EQ(rc, ErrorCode::RPC_TIMEOUT)
@@ -117,4 +157,267 @@ TEST(RpcTimeoutTest, RpcTimesOutAgainstUnresponsiveMaster) {
                                 "timeout still active?)";
 }
 
+// #3909: tearing a client down while timeout-backed requests are in flight
+// used to release the pool under suspended coroutines (intermittent segfault).
+// The destructor now drains first; this loop used to crash within a few rounds
+// when the race lost, and must run clean with the guard.
+TEST_F(RpcTimeoutEnvTest, TeardownDrainsInFlightTimeoutRequests) {
+    // Long request timeout so teardown lands squarely inside the call window.
+    ASSERT_EQ(::setenv("MC_RPC_TIMEOUT_MS", "3000", /*overwrite=*/1), 0);
+    ASSERT_EQ(::setenv("MC_RPC_CONNECT_TIMEOUT_MS", "100", /*overwrite=*/1), 0);
+
+    BlackHoleServer server;
+
+    for (int round = 0; round < 10; ++round) {
+        auto client = std::make_unique<MasterClient>(generate_uuid());
+        // ServiceReady inside Connect times out against the black hole; the
+        // pool exists by then either way.
+        (void)client->Connect(server.address());
+
+        // Each worker issues exactly one ExistKey and never touches the
+        // client again, which is the owner's actual shape: a torn-down client
+        // is never invoked after teardown. `entered` plus the 500ms sleep put
+        // every call squarely inside its 3s timeout window at reset time.
+        std::atomic<int> entered{0};
+        std::vector<std::thread> workers;
+        for (int i = 0; i < 16; ++i) {
+            workers.emplace_back([&] {
+                entered.fetch_add(1);
+                (void)client->ExistKey("never-there");
+            });
+        }
+        while (entered.load() < 16) {
+            std::this_thread::yield();
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(500));
+        client.reset();  // teardown with 16 requests suspended mid-flight
+        for (auto& w : workers) {
+            w.join();
+        }
+    }
+}
+
+// During failover the heartbeat can still be connecting to the deleted
+// leader's pod IP. It must return promptly so the HA loop can use the newly
+// published view instead of spending the default retry budget on a stale
+// peer. Bind an ephemeral loopback port without listening on it so connection
+// attempts are rejected deterministically while the port remains reserved by
+// this test.
+TEST(RpcTimeoutTest, HaControlPolicyPreservesForegroundRetryPolicy) {
+    int probe_fd = ::socket(AF_INET, SOCK_STREAM, 0);
+    ASSERT_GE(probe_fd, 0) << "failed to create probe socket";
+
+    sockaddr_in addr{};
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = ::inet_addr("127.0.0.1");
+    addr.sin_port = 0;
+    ASSERT_EQ(
+        ::bind(probe_fd, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)), 0)
+        << "failed to reserve loopback port";
+
+    socklen_t len = sizeof(addr);
+    ASSERT_EQ(::getsockname(probe_fd, reinterpret_cast<sockaddr*>(&addr), &len),
+              0);
+    const auto port = ntohs(addr.sin_port);
+    ASSERT_GT(port, 0);
+
+    ASSERT_EQ(::setenv("MC_RPC_CONNECT_TIMEOUT_MS", "100", 1), 0);
+
+    MasterClient client(generate_uuid());
+
+    // Initialization keeps the normal retry policy. With an immediately
+    // refused endpoint, its three one-second retry waits are observable.
+    const auto initial_start = std::chrono::steady_clock::now();
+    const auto initial_rc = client.Connect("127.0.0.1:" + std::to_string(port));
+    const auto initial_elapsed =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::steady_clock::now() - initial_start)
+            .count();
+
+    // HA runtime uses a separate fast-fail pool for leader readiness probes.
+    client.EnableHaConnectionPolicy();
+    const auto start = std::chrono::steady_clock::now();
+    const auto rc = client.Connect("127.0.0.1:" + std::to_string(port));
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+                             std::chrono::steady_clock::now() - start)
+                             .count();
+
+    // A foreground request still uses the original resilient pool even after
+    // the HA control policy has been enabled.
+    const auto foreground_start = std::chrono::steady_clock::now();
+    const auto foreground_rc = client.GetStorageConfig();
+    const auto foreground_elapsed =
+        std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::steady_clock::now() - foreground_start)
+            .count();
+
+    ::unsetenv("MC_RPC_CONNECT_TIMEOUT_MS");
+    EXPECT_EQ(::close(probe_fd), 0);
+
+    EXPECT_EQ(initial_rc, ErrorCode::RPC_FAIL);
+    EXPECT_GE(initial_elapsed, 2500)
+        << "initial connection unexpectedly lost its retry resilience";
+    EXPECT_EQ(rc, ErrorCode::RPC_FAIL);
+    EXPECT_LT(elapsed, 750)
+        << "HA readiness probe retried a failed leader internally for "
+        << elapsed << "ms";
+    ASSERT_FALSE(foreground_rc.has_value());
+    EXPECT_EQ(foreground_rc.error(), ErrorCode::RPC_FAIL);
+    EXPECT_GE(foreground_elapsed, 2500)
+        << "foreground RPC unexpectedly inherited the HA fast-fail policy";
+}
+
+TEST(RpcTimeoutTest, FailedCandidateProbeDoesNotRetargetHeartbeat) {
+    testing::InProcMaster confirmed_leader;
+    ASSERT_TRUE(confirmed_leader.Start(InProcMasterConfigBuilder().build()));
+
+    int probe_fd = ::socket(AF_INET, SOCK_STREAM, 0);
+    ASSERT_GE(probe_fd, 0);
+    sockaddr_in addr{};
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = ::inet_addr("127.0.0.1");
+    addr.sin_port = 0;
+    ASSERT_EQ(
+        ::bind(probe_fd, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)), 0);
+    socklen_t len = sizeof(addr);
+    ASSERT_EQ(::getsockname(probe_fd, reinterpret_cast<sockaddr*>(&addr), &len),
+              0);
+    const std::string candidate_address =
+        "127.0.0.1:" + std::to_string(ntohs(addr.sin_port));
+
+    ASSERT_EQ(::setenv("MC_RPC_CONNECT_TIMEOUT_MS", "100", 1), 0);
+    MasterClient client(generate_uuid());
+    ASSERT_EQ(ErrorCode::OK, client.Connect(confirmed_leader.master_address()));
+    client.EnableHaConnectionPolicy();
+
+    EXPECT_EQ(ErrorCode::RPC_FAIL, client.Connect(candidate_address));
+    auto heartbeat = client.Ping();
+
+    ::unsetenv("MC_RPC_CONNECT_TIMEOUT_MS");
+    EXPECT_EQ(::close(probe_fd), 0);
+    ASSERT_TRUE(heartbeat.has_value());
+}
+
+// The offload data path (store->store) builds its own client pool, separate
+// from the master pool, and used to ignore these variables entirely: its
+// connect timeout stayed at the built-in 30s, so a read that picked a peer
+// which had gone away blocked for connect_retry_count * 30s plus the waits
+// between retries with no way to configure it down. Both pools now go through
+// one helper, so cover the helper itself: an unset variable must leave the
+// built-in default alone, and a set one must be applied.
+TEST_F(RpcTimeoutEnvTest, TimeoutEnvOverridesAreOptIn) {
+    struct StubClientConfig {
+        std::chrono::milliseconds request_timeout_duration{
+            std::chrono::seconds(30)};
+        std::chrono::milliseconds connect_timeout_duration{
+            std::chrono::seconds(30)};
+    };
+
+    ::unsetenv("MC_RPC_TIMEOUT_MS");
+    ::unsetenv("MC_RPC_CONNECT_TIMEOUT_MS");
+
+    auto non_ha_config = detail::MakeMasterRpcClientPoolConfig();
+    EXPECT_EQ(non_ha_config.connect_retry_count, 3u);
+    EXPECT_EQ(non_ha_config.reconnect_wait_time,
+              std::chrono::milliseconds(1000));
+    EXPECT_EQ(non_ha_config.client_config.connect_timeout_duration,
+              std::chrono::seconds(30));
+
+    auto ha_config = detail::MakeMasterRpcClientPoolConfig(/*ha_enabled=*/true);
+    EXPECT_EQ(ha_config.connect_retry_count, 0u);
+    EXPECT_EQ(ha_config.reconnect_wait_time, std::chrono::milliseconds(0));
+    EXPECT_EQ(ha_config.client_config.connect_timeout_duration,
+              std::chrono::seconds(1));
+
+    StubClientConfig defaults;
+    detail::ApplyRpcTimeoutOverrides(defaults,
+                                     RpcTimeoutConfig::FromEnvironment());
+    EXPECT_EQ(defaults.request_timeout_duration, std::chrono::seconds(30));
+    EXPECT_EQ(defaults.connect_timeout_duration, std::chrono::seconds(30));
+    const auto original_master_config = detail::MakeMasterRpcClientPoolConfig();
+
+    ASSERT_EQ(::setenv("MC_RPC_TIMEOUT_MS", "1500", /*overwrite=*/1), 0);
+    ASSERT_EQ(::setenv("MC_RPC_CONNECT_TIMEOUT_MS", "1500", /*overwrite=*/1),
+              0);
+
+    StubClientConfig overridden;
+    detail::ApplyRpcTimeoutOverrides(overridden,
+                                     RpcTimeoutConfig::FromEnvironment());
+    EXPECT_EQ(overridden.request_timeout_duration,
+              std::chrono::milliseconds(1500));
+    EXPECT_EQ(overridden.connect_timeout_duration,
+              std::chrono::milliseconds(1500));
+
+    // The master pool is built from the same helper, so it sees them too.
+    auto master_config =
+        detail::MakeMasterRpcClientPoolConfig(/*ha_enabled=*/true);
+    EXPECT_EQ(master_config.client_config.request_timeout_duration,
+              std::chrono::milliseconds(1500));
+    EXPECT_EQ(master_config.connect_retry_count, 0u);
+    EXPECT_EQ(master_config.reconnect_wait_time, std::chrono::milliseconds(0));
+    EXPECT_EQ(master_config.client_config.connect_timeout_duration,
+              std::chrono::milliseconds(1500));
+    EXPECT_EQ(original_master_config.client_config.request_timeout_duration,
+              std::chrono::seconds(30));
+    EXPECT_EQ(original_master_config.client_config.connect_timeout_duration,
+              std::chrono::seconds(30));
+}
+
+TEST_F(RpcTimeoutEnvTest, OverridesPreserveCallerPolicyAndUseResolvedValues) {
+    struct StubClientConfig {
+        std::chrono::milliseconds request_timeout_duration{7000};
+        std::chrono::milliseconds connect_timeout_duration{1000};
+    };
+    StubClientConfig defaults;
+    detail::ApplyRpcTimeoutOverrides(defaults,
+                                     RpcTimeoutConfig::FromEnvironment());
+    EXPECT_EQ(defaults.request_timeout_duration,
+              std::chrono::milliseconds(7000));
+    EXPECT_EQ(defaults.connect_timeout_duration,
+              std::chrono::milliseconds(1000));
+
+    // The helper must apply this snapshot, not re-read the environment.
+    ASSERT_EQ(setenv("MC_RPC_TIMEOUT_MS", "9999", 1), 0);
+    ASSERT_EQ(setenv("MC_RPC_CONNECT_TIMEOUT_MS", "9999", 1), 0);
+    for (const int timeout_ms : {0, -1, 1500}) {
+        SCOPED_TRACE(timeout_ms);
+        RpcTimeoutConfig config;
+        config.request_timeout = std::chrono::milliseconds(timeout_ms);
+        StubClientConfig request_only;
+        detail::ApplyRpcTimeoutOverrides(request_only, config);
+        EXPECT_EQ(request_only.request_timeout_duration,
+                  std::chrono::milliseconds(timeout_ms));
+        EXPECT_EQ(request_only.connect_timeout_duration,
+                  std::chrono::milliseconds(1000));
+
+        config.request_timeout.reset();
+        config.connect_timeout = std::chrono::milliseconds(timeout_ms);
+        StubClientConfig connect_only;
+        detail::ApplyRpcTimeoutOverrides(connect_only, config);
+        EXPECT_EQ(connect_only.request_timeout_duration,
+                  std::chrono::milliseconds(7000));
+        EXPECT_EQ(connect_only.connect_timeout_duration,
+                  std::chrono::milliseconds(timeout_ms));
+    }
+}
+
+TEST_F(RpcTimeoutEnvTest, RpcTimesOutAgainstUnresponsiveOffloadPeer) {
+    constexpr int kTimeoutMs = 500;
+    ASSERT_EQ(setenv("MC_RPC_TIMEOUT_MS", "500", 1), 0);
+    BlackHoleServer server;
+    ClientRequester requester;
+
+    const auto start = std::chrono::steady_clock::now();
+    const auto result =
+        requester.batch_get_offload_object(server.address(), {"key"}, {1});
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+                             std::chrono::steady_clock::now() - start)
+                             .count();
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), ErrorCode::RPC_TIMEOUT);
+    EXPECT_GE(elapsed, kTimeoutMs - 100);
+    EXPECT_LT(elapsed, 5000);
+}
+
 }  // namespace mooncake
diff --git a/mooncake-store/tests/runtime_accelerator_test.cpp b/mooncake-store/tests/runtime_accelerator_test.cpp
index 395084f4b5..8cf027c103 100644
--- a/mooncake-store/tests/runtime_accelerator_test.cpp
+++ b/mooncake-store/tests/runtime_accelerator_test.cpp
@@ -110,5 +110,65 @@ TEST(RuntimeAcceleratorTest, CopyFromHostUsesHostToDeviceCopy) {
     EXPECT_EQ(device.last_direction(), CopyDirection::kHostToDevice);
 }
 
+TEST(RuntimeAcceleratorTest, CopyAutoFallsBackToMemcpyForHostPointers) {
+    char src[] = "abc";
+    char dst[sizeof(src)] = {};
+    RuntimeAccelerator runtime_accelerator;
+
+    EXPECT_TRUE(runtime_accelerator.CopyAuto(dst, src, sizeof(src)));
+
+    EXPECT_STREQ(dst, src);
+}
+
+TEST(RuntimeAcceleratorTest, CopyAutoUsesDestinationDeviceContext) {
+    char src[] = "abc";
+    char dst[sizeof(src)] = {};
+    FakeAcceleratorDevice device(AcceleratorVendor::kNvidia, dst, 5);
+    RuntimeAccelerator runtime_accelerator({&device});
+
+    EXPECT_TRUE(runtime_accelerator.CopyAuto(dst, src, sizeof(src)));
+
+    EXPECT_STREQ(dst, src);
+    EXPECT_EQ(device.current_device_id(), 5);
+    EXPECT_EQ(device.last_direction(), CopyDirection::kAuto);
+}
+
+TEST(RuntimeAcceleratorTest, CopyAutoUsesSourceDeviceForDeviceToHost) {
+    char src[] = "abc";
+    char dst[sizeof(src)] = {};
+    FakeAcceleratorDevice device(AcceleratorVendor::kNvidia, src, 6);
+    RuntimeAccelerator runtime_accelerator({&device});
+
+    EXPECT_TRUE(runtime_accelerator.CopyAuto(dst, src, sizeof(src)));
+
+    EXPECT_STREQ(dst, src);
+    EXPECT_EQ(device.current_device_id(), 6);
+    EXPECT_EQ(device.last_direction(), CopyDirection::kAuto);
+}
+
+TEST(RuntimeAcceleratorTest, CopyAutoReportsDeviceCopyFailure) {
+    char src[] = "abc";
+    char dst[sizeof(src)] = {};
+    FakeAcceleratorDevice device(AcceleratorVendor::kNvidia, dst, 5);
+    device.set_copy_succeeds(false);
+    RuntimeAccelerator runtime_accelerator({&device});
+
+    EXPECT_FALSE(runtime_accelerator.CopyAuto(dst, src, sizeof(src)));
+}
+
+TEST(RuntimeAcceleratorTest, CopyAutoRejectsCrossRuntimeDevicePairs) {
+    char src[] = "abc";
+    char dst[sizeof(src)] = {};
+    FakeAcceleratorDevice src_device(AcceleratorVendor::kNvidia, src, 1);
+    FakeAcceleratorDevice dst_device(AcceleratorVendor::kAscend, dst, 2);
+    RuntimeAccelerator runtime_accelerator({&src_device, &dst_device});
+
+    EXPECT_FALSE(runtime_accelerator.CopyAuto(dst, src, sizeof(src)));
+
+    // Neither device was asked to copy across runtimes.
+    EXPECT_EQ(src_device.current_device_id(), -1);
+    EXPECT_EQ(dst_device.current_device_id(), -1);
+}
+
 }  // namespace
 }  // namespace mooncake::device
diff --git a/mooncake-store/tests/s3_client_config_test.cpp b/mooncake-store/tests/s3_client_config_test.cpp
new file mode 100644
index 0000000000..3fadedf7f7
--- /dev/null
+++ b/mooncake-store/tests/s3_client_config_test.cpp
@@ -0,0 +1,155 @@
+#include "../src/config/s3_client_config.h"
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <chrono>
+#include <cstdlib>
+#include <mutex>
+#include <optional>
+#include <string>
+
+namespace mooncake {
+namespace {
+
+std::mutex environment_mutex;
+
+class S3ClientConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        environment_lock_ = std::unique_lock<std::mutex>(environment_mutex);
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_[i] = value;
+            }
+            ASSERT_EQ(unsetenv(kVariables[i]), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_[i]) {
+                EXPECT_EQ(setenv(kVariables[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+    }
+
+    void Set(const char* name, const char* value) {
+        ASSERT_EQ(setenv(name, value, 1), 0);
+    }
+
+   private:
+    inline static constexpr std::array<const char*, 11> kVariables = {
+        "MOONCAKE_AWS_REGION",
+        "MOONCAKE_AWS_S3_ENDPOINT",
+        "MOONCAKE_AWS_BUCKET_NAME",
+        "MOONCAKE_AWS_ACCESS_KEY_ID",
+        "MOONCAKE_AWS_SECRET_ACCESS_KEY",
+        "MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING",
+        "MOONCAKE_AWS_USE_HTTPS",
+        "MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION",
+        "MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION",
+        "MOONCAKE_AWS_CONNECT_TIMEOUT_MS",
+        "MOONCAKE_AWS_REQUEST_TIMEOUT_MS"};
+    std::array<std::optional<std::string>, kVariables.size()> original_;
+    std::unique_lock<std::mutex> environment_lock_;
+};
+
+TEST_F(S3ClientConfigTest, UsesExistingDefaults) {
+    const auto config = S3ClientConfig::FromEnvironment();
+    EXPECT_TRUE(config.region.empty());
+    EXPECT_TRUE(config.s3_endpoint.empty());
+    EXPECT_TRUE(config.bucket_name.empty());
+    EXPECT_TRUE(config.access_key_id.empty());
+    EXPECT_TRUE(config.secret_access_key.empty());
+    EXPECT_TRUE(config.use_virtual_addressing);
+    EXPECT_TRUE(config.use_https);
+    EXPECT_TRUE(config.request_checksum_calculation.empty());
+    EXPECT_TRUE(config.response_checksum_validation.empty());
+    EXPECT_EQ(config.connect_timeout, std::chrono::milliseconds(10000));
+    EXPECT_EQ(config.request_timeout, std::chrono::milliseconds(30000));
+}
+
+TEST_F(S3ClientConfigTest, ReadsAllExistingSettings) {
+    Set("MOONCAKE_AWS_REGION", "us-east-1");
+    Set("MOONCAKE_AWS_S3_ENDPOINT", "https://s3.example.com");
+    Set("MOONCAKE_AWS_BUCKET_NAME", "bucket");
+    Set("MOONCAKE_AWS_ACCESS_KEY_ID", "access");
+    Set("MOONCAKE_AWS_SECRET_ACCESS_KEY", "secret");
+    Set("MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING", "0");
+    Set("MOONCAKE_AWS_USE_HTTPS", "false");
+    Set("MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION", "when_required");
+    Set("MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION", "when_supported");
+    Set("MOONCAKE_AWS_CONNECT_TIMEOUT_MS", "5000");
+    Set("MOONCAKE_AWS_REQUEST_TIMEOUT_MS", "6000");
+
+    const auto config = S3ClientConfig::FromEnvironment();
+    EXPECT_EQ(config.region, "us-east-1");
+    EXPECT_EQ(config.s3_endpoint, "https://s3.example.com");
+    EXPECT_EQ(config.bucket_name, "bucket");
+    EXPECT_EQ(config.access_key_id, "access");
+    EXPECT_EQ(config.secret_access_key, "secret");
+    EXPECT_FALSE(config.use_virtual_addressing);
+    EXPECT_FALSE(config.use_https);
+    EXPECT_EQ(config.request_checksum_calculation, "when_required");
+    EXPECT_EQ(config.response_checksum_validation, "when_supported");
+    EXPECT_EQ(config.connect_timeout, std::chrono::milliseconds(5000));
+    EXPECT_EQ(config.request_timeout, std::chrono::milliseconds(6000));
+}
+
+TEST_F(S3ClientConfigTest, PreservesExplicitlyEmptyStrings) {
+    Set("MOONCAKE_AWS_REGION", "");
+    Set("MOONCAKE_AWS_S3_ENDPOINT", "");
+    Set("MOONCAKE_AWS_BUCKET_NAME", "");
+    Set("MOONCAKE_AWS_ACCESS_KEY_ID", "");
+    Set("MOONCAKE_AWS_SECRET_ACCESS_KEY", "");
+    Set("MOONCAKE_AWS_REQUEST_CHECKSUM_CALCULATION", "");
+    Set("MOONCAKE_AWS_RESPONSE_CHECKSUM_VALIDATION", "");
+
+    const auto config = S3ClientConfig::FromEnvironment();
+    EXPECT_TRUE(config.region.empty());
+    EXPECT_TRUE(config.s3_endpoint.empty());
+    EXPECT_TRUE(config.bucket_name.empty());
+    EXPECT_TRUE(config.access_key_id.empty());
+    EXPECT_TRUE(config.secret_access_key.empty());
+    EXPECT_TRUE(config.request_checksum_calculation.empty());
+    EXPECT_TRUE(config.response_checksum_validation.empty());
+}
+
+TEST_F(S3ClientConfigTest, InvalidTypedValuesUseExistingDefaultsAndWarn) {
+    Set("MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING", "invalid");
+    Set("MOONCAKE_AWS_USE_HTTPS", "invalid");
+    Set("MOONCAKE_AWS_CONNECT_TIMEOUT_MS", "invalid");
+    Set("MOONCAKE_AWS_REQUEST_TIMEOUT_MS", "invalid");
+
+    testing::internal::CaptureStderr();
+    const auto config = S3ClientConfig::FromEnvironment();
+    const std::string diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_TRUE(config.use_virtual_addressing);
+    EXPECT_TRUE(config.use_https);
+    EXPECT_EQ(config.connect_timeout, std::chrono::milliseconds(10000));
+    EXPECT_EQ(config.request_timeout, std::chrono::milliseconds(30000));
+    EXPECT_NE(diagnostics.find("MOONCAKE_AWS_USE_VIRTUAL_ADDRESSING"),
+              std::string::npos);
+    EXPECT_NE(diagnostics.find("MOONCAKE_AWS_USE_HTTPS"), std::string::npos);
+    EXPECT_NE(diagnostics.find("MOONCAKE_AWS_CONNECT_TIMEOUT_MS"),
+              std::string::npos);
+    EXPECT_NE(diagnostics.find("MOONCAKE_AWS_REQUEST_TIMEOUT_MS"),
+              std::string::npos);
+}
+
+TEST_F(S3ClientConfigTest, NewConfigsReadCurrentEnvironment) {
+    Set("MOONCAKE_AWS_REGION", "first");
+    const auto first = S3ClientConfig::FromEnvironment();
+    Set("MOONCAKE_AWS_REGION", "second");
+    const auto second = S3ClientConfig::FromEnvironment();
+
+    EXPECT_EQ(first.region, "first");
+    EXPECT_EQ(second.region, "second");
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/segment_pool_test.cpp b/mooncake-store/tests/segment_pool_test.cpp
new file mode 100644
index 0000000000..eda1f50a2e
--- /dev/null
+++ b/mooncake-store/tests/segment_pool_test.cpp
@@ -0,0 +1,1524 @@
+#include "segment/pool.h"
+
+#include <gtest/gtest.h>
+#include <msgpack.hpp>
+
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cerrno>
+#include <chrono>
+#include <future>
+#include <map>
+#include <memory>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "client_liveness.h"
+#include "ha/snapshot/store_resource_snapshot_codec.h"
+#include "master_metric_manager.h"
+#include "segment.h"
+#include "segment/pool_read_access.h"
+#include "segment/pool_write_access.h"
+#include "test_buffer_allocator.h"
+
+namespace mooncake::test {
+namespace {
+
+auto ActiveRegionsByHost(const RegionCatalog& catalog) {
+    std::map<std::string, std::map<std::string, std::set<UUID>>> result;
+    for (const auto& r : catalog.Regions()) {
+        if (r.status != SegmentStatus::OK || r.segment.host_id.empty())
+            continue;
+        result[r.segment.host_id][r.segment.name].insert(r.segment.id);
+    }
+    return result;
+}
+
+constexpr size_t kRegionSize = 16U * 1024 * 1024;
+
+RegionDriverRegistry Drivers(bool enable_cxl = false) {
+    RegionDriverConfig config;
+    config.memory_allocator = BufferAllocatorType::OFFSET;
+    if (enable_cxl) {
+        config.cxl = CxlRegionDriverConfig{"cxl-test-path", kRegionSize};
+    }
+    auto drivers = CreateRegionDrivers(config);
+    EXPECT_TRUE(drivers.has_value());
+    return std::move(drivers.value());
+}
+
+Segment MakeSegment(size_t index, std::string name,
+                    std::string protocol = "tcp", std::string host = {}) {
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = std::move(name);
+    segment.base = 0x100000000ULL + index * 0x2000000ULL;
+    segment.size = kRegionSize;
+    segment.te_endpoint = segment.name + "-endpoint";
+    segment.protocol = std::move(protocol);
+    segment.host_id = std::move(host);
+    return segment;
+}
+
+void CommitUnmount(SegmentPool& pool, const Segment& segment,
+                   const UUID& client_id) {
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(segment.id, client_id);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(std::move(*transaction).Commit(access), ErrorCode::OK);
+    EXPECT_EQ(std::move(*transaction).Commit(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    EXPECT_EQ(std::move(*transaction).Rollback(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+tl::expected<std::vector<uint8_t>, SerializationError> CaptureAndEncode(
+    const SegmentPool& pool, const LocalSsdPersistedState& local_ssd) {
+    auto snapshot = pool.CaptureSnapshot();
+    if (!snapshot) {
+        return tl::make_unexpected(
+            SerializationError(snapshot.error(), "capture SegmentPool failed"));
+    }
+    return ha::StoreResourceSnapshotCodec::Encode(*snapshot, local_ssd);
+}
+
+tl::expected<LocalSsdPersistedState, SerializationError> DecodeAndRestore(
+    SegmentPool& pool, const std::vector<uint8_t>& bytes,
+    bool account_capacity) {
+    auto decoded = ha::StoreResourceSnapshotCodec::Decode(bytes);
+    if (!decoded) return tl::make_unexpected(decoded.error());
+    auto restored = pool.RestoreSnapshot(std::move(decoded->segment_pool),
+                                         account_capacity);
+    if (!restored)
+        return tl::make_unexpected(
+            SerializationError(restored.error(), "restore SegmentPool failed"));
+    return std::move(decoded->local_ssd);
+}
+
+}  // namespace
+
+TEST(SegmentPoolTest, ClassifiesOnlyCxlProtocolAsCxl) {
+    SegmentPool pool(Drivers(true));
+    const UUID client = generate_uuid();
+    auto host = MakeSegment(0, "host", "rdma");
+    auto cxl = MakeSegment(1, "cxl", "cxl");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(host, client), ErrorCode::OK);
+        ASSERT_EQ(access.MountSegment(cxl, client), ErrorCode::OK);
+    }
+
+    {
+        auto view = pool.AcquireReadAccess();
+        ASSERT_NE(view.Catalog().Find(host.id), nullptr);
+        EXPECT_EQ(view.Catalog().Find(host.id)->kind, RegionKind::HOST_MEMORY);
+        ASSERT_NE(view.Catalog().Find(cxl.id), nullptr);
+        EXPECT_EQ(view.Catalog().Find(cxl.id)->kind, RegionKind::CXL);
+        EXPECT_NE(
+            view.Placement().Find(host.name, AllocationCandidateKind::NATIVE),
+            nullptr);
+        EXPECT_NE(view.Placement().Find(cxl.name, AllocationCandidateKind::CXL),
+                  nullptr);
+    }
+
+    CommitUnmount(pool, host, client);
+    CommitUnmount(pool, cxl, client);
+}
+
+TEST(SegmentPoolTest, PreparedMountPublishesOnlyOnCommit) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "prepared");
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareMount(segment, client);
+        ASSERT_TRUE(transaction.has_value());
+    }
+    EXPECT_EQ(pool.AcquireReadAccess().Catalog().Find(segment.id), nullptr);
+
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareMount(segment, client);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(transaction->Commit(access), ErrorCode::OK);
+    }
+    EXPECT_NE(pool.AcquireReadAccess().Catalog().Find(segment.id), nullptr);
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest, MountCommitRejectsPreparedIdAndOwnerConflicts) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "prepared-conflict");
+    auto other = MakeSegment(1, segment.name);
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto first = access.PrepareMount(segment, client);
+        auto duplicate = access.PrepareMount(segment, client);
+        auto conflicting_owner = access.PrepareMount(other, generate_uuid());
+        ASSERT_TRUE(first.has_value());
+        ASSERT_TRUE(duplicate.has_value());
+        ASSERT_TRUE(conflicting_owner.has_value());
+        ASSERT_EQ(first->Commit(access), ErrorCode::OK);
+        EXPECT_EQ(duplicate->Commit(access), ErrorCode::SEGMENT_ALREADY_EXISTS);
+        EXPECT_EQ(conflicting_owner->Commit(access), ErrorCode::INVALID_PARAMS);
+        EXPECT_EQ(first->Commit(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    }
+    {
+        auto read = pool.AcquireReadAccess();
+        EXPECT_EQ(read.Catalog().Regions().size(), 1U);
+        EXPECT_EQ(read.GetAllocator(other.id), nullptr);
+        auto* entry = read.Placement().Find(segment.name,
+                                            AllocationCandidateKind::NATIVE);
+        ASSERT_NE(entry, nullptr);
+        ASSERT_EQ(entry->candidates.size(), 1U);
+        EXPECT_EQ((*entry->candidates.begin())->allocator_handle(),
+                  read.GetAllocator(segment.id));
+    }
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, kRegionSize);
+    EXPECT_TRUE(pool.AllocateInSegment(segment.name,
+                                       AllocationCandidateKind::NATIVE, 4096)
+                    .has_value());
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest, RemountCommitRejectsInterveningStatusChanges) {
+    for (auto initial : {SegmentStatus::OK, SegmentStatus::DRAINING}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "status-conflict");
+        {
+            auto access = pool.AcquireWriteAccess();
+            ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+            ASSERT_EQ(access.SetSegmentStatusByName(segment.name, initial),
+                      ErrorCode::OK);
+        }
+        auto original = pool.AcquireReadAccess().GetAllocator(segment.id);
+        const auto next = initial == SegmentStatus::OK ? SegmentStatus::DRAINING
+                                                       : SegmentStatus::OK;
+        {
+            auto access = pool.AcquireWriteAccess();
+            auto prepared = access.PrepareMount(segment, client);
+            ASSERT_TRUE(prepared.has_value());
+            ASSERT_EQ(access.SetSegmentStatusByName(segment.name, next),
+                      ErrorCode::OK);
+            EXPECT_EQ(prepared->Commit(access),
+                      ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        {
+            auto read = pool.AcquireReadAccess();
+            EXPECT_EQ(read.GetAllocator(segment.id), original);
+            EXPECT_EQ(read.Catalog().Find(segment.id)->status, next);
+        }
+        EXPECT_EQ(pool.AllocateInSegment(segment.name,
+                                         AllocationCandidateKind::NATIVE, 4096)
+                      .has_value(),
+                  next == SegmentStatus::OK);
+        CommitUnmount(pool, segment, client);
+    }
+}
+
+TEST(SegmentPoolTest, RemountCommitRejectsReplacedOrRemovedResource) {
+    for (bool clear : {false, true}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "resource-conflict");
+        {
+            auto access = pool.AcquireWriteAccess();
+            ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+            auto stale = access.PrepareMount(segment, client);
+            ASSERT_TRUE(stale.has_value());
+            if (clear) {
+                access.Clear();
+            } else {
+                auto replacement = access.PrepareMount(segment, client);
+                ASSERT_TRUE(replacement.has_value());
+                ASSERT_EQ(replacement->Commit(access), ErrorCode::OK);
+            }
+            EXPECT_EQ(stale->Commit(access),
+                      ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        }
+        EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes,
+                  clear ? 0U : kRegionSize);
+        EXPECT_EQ(pool.AllocateInSegment(segment.name,
+                                         AllocationCandidateKind::NATIVE, 4096)
+                      .has_value(),
+                  !clear);
+        if (!clear) {
+            CommitUnmount(pool, segment, client);
+        }
+    }
+}
+
+TEST(SegmentPoolTest, RestoreReturnsImportedBuffersInInputOrder) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "restore");
+    std::vector<AllocatedBuffer::Descriptor> descriptors{
+        {4096, segment.base + 8192, "tcp", segment.te_endpoint},
+        {4096, segment.base, "tcp", segment.te_endpoint}};
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareRestore(segment, client, descriptors);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(transaction->imported_buffers().size(), 2U);
+        EXPECT_EQ(transaction->imported_requested_bytes(), 8192U);
+        EXPECT_EQ(reinterpret_cast<uintptr_t>(
+                      transaction->imported_buffers()[0]->data()),
+                  segment.base + 8192);
+        EXPECT_EQ(reinterpret_cast<uintptr_t>(
+                      transaction->imported_buffers()[1]->data()),
+                  segment.base);
+        ASSERT_EQ(transaction->Commit(access), ErrorCode::OK);
+        auto buffers = transaction->TakeImportedBuffers();
+        buffers.clear();
+    }
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest, RollbackRestoresOriginalLifecycleState) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "draining", "tcp", "host");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        ASSERT_EQ(access.SetSegmentStatusByName(segment.name,
+                                                SegmentStatus::DRAINING),
+                  ErrorCode::OK);
+        auto transaction = access.PrepareUnmount(segment.id, client);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(std::move(*transaction).Rollback(access), ErrorCode::OK);
+        ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(access.Catalog().Find(segment.id)->status,
+                  SegmentStatus::DRAINING);
+    }
+
+    {
+        auto view = pool.AcquireReadAccess();
+        ASSERT_NE(view.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(view.Catalog().Find(segment.id)->status,
+                  SegmentStatus::DRAINING);
+        EXPECT_TRUE(ActiveRegionsByHost(view.Catalog()).empty());
+        EXPECT_EQ(view.Placement().Find(segment.name,
+                                        AllocationCandidateKind::NATIVE),
+                  nullptr);
+    }
+
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(
+            access.SetSegmentStatusByName(segment.name, SegmentStatus::OK),
+            ErrorCode::OK);
+    }
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest, ImmediateUnmountRollbackRestoresPlacement) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "rollback", "tcp", "host");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    }
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(segment.id, client);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    {
+        auto access = pool.AcquireWriteAccess();
+        EXPECT_TRUE(ActiveRegionsByHost(access.Catalog()).empty());
+        ASSERT_EQ(std::move(*transaction).Rollback(access), ErrorCode::OK);
+        EXPECT_EQ(std::move(*transaction).Rollback(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        EXPECT_EQ(std::move(*transaction).Commit(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        EXPECT_TRUE(ActiveRegionsByHost(access.Catalog())
+                        .at("host")
+                        .at(segment.name)
+                        .contains(segment.id));
+    }
+    {
+        auto view = pool.AcquireReadAccess();
+        EXPECT_NE(view.Placement().Find(segment.name,
+                                        AllocationCandidateKind::NATIVE),
+                  nullptr);
+    }
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest,
+     UnmountMoveTransfersOwnershipAndFailureConsumesTransaction) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "consume-unmount");
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto prepared = access.PrepareUnmount(segment.id, client);
+    ASSERT_TRUE(prepared.has_value());
+    auto transaction = std::move(*prepared);
+    EXPECT_EQ(std::move(*prepared).Commit(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    EXPECT_EQ(access.Catalog().Find(segment.id)->status,
+              SegmentStatus::UNMOUNTING);
+    access.Clear();
+    EXPECT_EQ(std::move(transaction).Rollback(access),
+              ErrorCode::SEGMENT_NOT_FOUND);
+    EXPECT_EQ(std::move(transaction).Commit(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST(SegmentPoolTest, AllocationKeepsReadLockAcrossAllocatorCall) {
+    for (bool named : {false, true}) {
+        SCOPED_TRACE(named);
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "blocking");
+        auto allocator = std::make_shared<TestBufferAllocator>(
+            segment.name, segment.te_endpoint, kRegionSize, segment.base);
+        {
+            MountedRegion mounted{segment, client, SegmentStatus::OK,
+                                  RegionKind::HOST_MEMORY};
+            auto access = pool.AcquireWriteAccess();
+            auto transaction = access.PrepareAdopt(mounted, allocator, true);
+            ASSERT_TRUE(transaction.has_value());
+            ASSERT_EQ(transaction->Commit(access), ErrorCode::OK);
+        }
+
+        allocator->BlockNext();
+        auto started = allocator->AllocationStarted();
+        auto allocation = std::async(std::launch::async, [&] {
+            if (named) {
+                return pool
+                    .AllocateInSegment(segment.name,
+                                       AllocationCandidateKind::NATIVE, 4096)
+                    .has_value();
+            }
+            ReplicaAllocationRequest request;
+            request.replicas.size = 4096;
+            return pool.AllocateReplicas(request).has_value();
+        });
+        ASSERT_EQ(started.wait_for(std::chrono::seconds(5)),
+                  std::future_status::ready);
+
+        std::atomic<bool> unmount_finished{false};
+        std::thread unmount([&] {
+            CommitUnmount(pool, segment, client);
+            unmount_finished.store(true, std::memory_order_release);
+        });
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        EXPECT_FALSE(unmount_finished.load(std::memory_order_acquire));
+        allocator->AllowAllocation();
+        EXPECT_TRUE(allocation.get());
+        unmount.join();
+        EXPECT_TRUE(unmount_finished.load(std::memory_order_acquire));
+    }
+}
+
+TEST(SegmentPoolTest, LocalPlacementUsesMountedHostIdentity) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto local = MakeSegment(0, "local", "tcp", "writer");
+    auto remote = MakeSegment(1, "remote", "tcp", "other-host");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(local, client), ErrorCode::OK);
+        ASSERT_EQ(access.MountSegment(remote, client), ErrorCode::OK);
+    }
+    ReplicaAllocationRequest request;
+    request.replicas.size = 4096;
+    request.host_affinity = {"writer", "key"};
+    auto result = pool.AllocateReplicas(request, LocalFirstPlacementPolicy{});
+    ASSERT_TRUE(result.has_value());
+    ASSERT_EQ(result->size(), 1U);
+    EXPECT_EQ(ReplicaEndpoint(result->front()), local.te_endpoint);
+}
+
+TEST(SegmentPoolTest, SameNameKindsRemainIndependentAcrossUnmountRollback) {
+    SegmentPool pool(Drivers(true));
+    const UUID client = generate_uuid();
+    auto native = MakeSegment(0, "shared", "tcp", "host");
+    auto cxl = MakeSegment(1, "shared", "cxl", "host");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(native, client), ErrorCode::OK);
+        ASSERT_EQ(access.MountSegment(cxl, client), ErrorCode::OK);
+    }
+    {
+        auto native_replica = pool.AllocateInSegment(
+            "shared", AllocationCandidateKind::NATIVE, 4096);
+        auto cxl_replica = pool.AllocateInSegment(
+            "shared", AllocationCandidateKind::CXL, 4096);
+        ASSERT_TRUE(native_replica.has_value());
+        ASSERT_TRUE(cxl_replica.has_value());
+        EXPECT_EQ(ReplicaEndpoint(*native_replica), native.te_endpoint);
+        EXPECT_EQ(ReplicaEndpoint(*cxl_replica), cxl.name);
+    }
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(cxl.id, client);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    EXPECT_TRUE(
+        pool.AllocateInSegment("shared", AllocationCandidateKind::NATIVE, 4096)
+            .has_value());
+    EXPECT_FALSE(
+        pool.AllocateInSegment("shared", AllocationCandidateKind::CXL, 4096)
+            .has_value());
+    {
+        auto access = pool.AcquireReadAccess();
+        size_t used = 0;
+        size_t capacity = 0;
+        EXPECT_EQ(
+            access.QueryAllocationCandidates(
+                "shared", AllocationCandidateKind::NATIVE, used, capacity),
+            ErrorCode::OK);
+        EXPECT_EQ(capacity, kRegionSize);
+        EXPECT_EQ(access.QueryAllocationCandidates(
+                      "shared", AllocationCandidateKind::CXL, used, capacity),
+                  ErrorCode::SEGMENT_NOT_FOUND);
+    }
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(std::move(*transaction).Rollback(access), ErrorCode::OK);
+    }
+    EXPECT_TRUE(
+        pool.AllocateInSegment("shared", AllocationCandidateKind::CXL, 4096)
+            .has_value());
+    CommitUnmount(pool, cxl, client);
+    EXPECT_TRUE(
+        pool.AllocateInSegment("shared", AllocationCandidateKind::NATIVE, 4096)
+            .has_value());
+    CommitUnmount(pool, native, client);
+}
+
+TEST(SegmentPoolTest,
+     FailedRestoreKeepsExistingRegionAndRequiresCanonicalEndpoint) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "restore-validation");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    }
+    auto original = pool.AcquireReadAccess().GetAllocator(segment.id);
+    std::vector<AllocatedBuffer::Descriptor> descriptors{
+        {4096, segment.base, "tcp", segment.name}};
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto alias = access.PrepareRestore(segment, client, descriptors);
+        ASSERT_FALSE(alias.has_value());
+        EXPECT_EQ(alias.error(), ErrorCode::INVALID_PARAMS);
+        descriptors[0].transport_endpoint_ = segment.te_endpoint;
+        descriptors.push_back(descriptors[0]);
+        auto overlap = access.PrepareRestore(segment, client, descriptors);
+        ASSERT_FALSE(overlap.has_value());
+        EXPECT_EQ(overlap.error(), ErrorCode::INVALID_PARAMS);
+    }
+    EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), original);
+    EXPECT_TRUE(pool.AllocateInSegment(segment.name,
+                                       AllocationCandidateKind::NATIVE, 4096)
+                    .has_value());
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest,
+     RemountReplacesPublishedCandidateWithoutDuplicatingCapacity) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto capacity_before = metrics.get_total_mem_capacity();
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "remount");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    }
+    EXPECT_EQ(metrics.get_total_mem_capacity(), capacity_before + kRegionSize);
+    auto old_allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareMount(segment, client);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(transaction->Commit(access), ErrorCode::OK);
+    }
+    {
+        auto access = pool.AcquireReadAccess();
+        EXPECT_NE(access.GetAllocator(segment.id), old_allocator);
+        EXPECT_TRUE(access.IsInactive(old_allocator, segment.name));
+        EXPECT_FALSE(
+            access.IsInactive(access.GetAllocator(segment.id), segment.name));
+        const auto* entry = access.Placement().Find(
+            segment.name, AllocationCandidateKind::NATIVE);
+        ASSERT_NE(entry, nullptr);
+        EXPECT_EQ(entry->candidates.size(), 1U);
+    }
+    EXPECT_EQ(metrics.get_total_mem_capacity(), capacity_before + kRegionSize);
+    EXPECT_EQ(pool.GetMemoryUsageSnapshot().capacity_bytes, kRegionSize);
+    old_allocator.reset();
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, kRegionSize);
+    EXPECT_TRUE(pool.AllocateInSegment(segment.name,
+                                       AllocationCandidateKind::NATIVE, 4096)
+                    .has_value());
+    CommitUnmount(pool, segment, client);
+    EXPECT_EQ(metrics.get_total_mem_capacity(), capacity_before);
+}
+
+TEST(SegmentPoolTest, GracefulUnmountRetainsResourceUntilFinalization) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "graceful");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    }
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto buffer = allocator->allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareGracefulUnmount(segment.id, client);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    {
+        auto access = pool.AcquireReadAccess();
+        EXPECT_FALSE(access.IsInactive(allocator, segment.name));
+        EXPECT_EQ(access.GetAllocator(segment.id), allocator);
+        EXPECT_EQ(access.Placement().Find(segment.name,
+                                          AllocationCandidateKind::NATIVE),
+                  nullptr);
+    }
+    allocator.reset();
+    EXPECT_TRUE(buffer->isAllocatorValid());
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(std::move(*transaction).Finalize(access), ErrorCode::OK);
+    }
+    EXPECT_FALSE(buffer->isAllocatorValid());
+    buffer.reset();
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, 0U);
+}
+
+TEST(SegmentPoolTest, GracefulUnmountCanResumeAndConsumesMovedTransaction) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "graceful-resume");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        auto wrong_client =
+            access.PrepareGracefulUnmount(segment.id, generate_uuid());
+        ASSERT_FALSE(wrong_client.has_value());
+        EXPECT_EQ(wrong_client.error(), ErrorCode::INVALID_PARAMS);
+        auto abandoned = access.PrepareGracefulUnmount(segment.id, client);
+        ASSERT_TRUE(abandoned.has_value());
+    }
+    {
+        auto access = pool.AcquireReadAccess();
+        ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(access.Catalog().Find(segment.id)->status,
+                  SegmentStatus::GRACEFULLY_UNMOUNTING);
+        EXPECT_EQ(access.Placement().Find(segment.name,
+                                          AllocationCandidateKind::NATIVE),
+                  nullptr);
+    }
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareGracefulUnmount(segment.id, client);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    auto moved = std::move(*transaction);
+    {
+        auto access = pool.AcquireWriteAccess();
+        EXPECT_EQ(std::move(*transaction).Finalize(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        EXPECT_NE(access.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(std::move(moved).Finalize(access), ErrorCode::OK);
+        EXPECT_EQ(std::move(moved).Finalize(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        EXPECT_EQ(access.Catalog().Find(segment.id), nullptr);
+    }
+}
+
+TEST(SegmentPoolTest, StaleGracefulUnmountCannotFinalizeNewMount) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "graceful-remount");
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto stale = access.PrepareGracefulUnmount(segment.id, client);
+    auto resumed = access.PrepareGracefulUnmount(segment.id, client);
+    ASSERT_TRUE(stale.has_value());
+    ASSERT_TRUE(resumed.has_value());
+    ASSERT_EQ(std::move(*resumed).Finalize(access), ErrorCode::OK);
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto current = access.PrepareGracefulUnmount(segment.id, client);
+    ASSERT_TRUE(current.has_value());
+    EXPECT_EQ(std::move(*stale).Finalize(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+    EXPECT_EQ(std::move(*current).Finalize(access), ErrorCode::OK);
+}
+
+TEST(SegmentPoolTest, UnmountCannotEraseRegionOwnedByAnotherClient) {
+    for (bool graceful : {false, true}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        const UUID new_client = generate_uuid();
+        auto segment = MakeSegment(0, "unmount-new-owner");
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        auto remount = [&] {
+            access.Clear();
+            ASSERT_EQ(access.MountSegment(segment, new_client), ErrorCode::OK);
+        };
+        if (graceful) {
+            auto stale = access.PrepareGracefulUnmount(segment.id, client);
+            ASSERT_TRUE(stale.has_value());
+            remount();
+            EXPECT_EQ(std::move(*stale).Finalize(access),
+                      ErrorCode::INVALID_PARAMS);
+        } else {
+            auto stale = access.PrepareUnmount(segment.id, client);
+            ASSERT_TRUE(stale.has_value());
+            remount();
+            EXPECT_EQ(std::move(*stale).Commit(access),
+                      ErrorCode::INVALID_PARAMS);
+        }
+        const auto* mounted = access.Catalog().Find(segment.id);
+        ASSERT_NE(mounted, nullptr);
+        EXPECT_EQ(mounted->client_id, new_client);
+        EXPECT_EQ(mounted->status, SegmentStatus::OK);
+        auto current = access.PrepareUnmount(segment.id, new_client);
+        ASSERT_TRUE(current.has_value());
+        EXPECT_EQ(std::move(*current).Commit(access), ErrorCode::OK);
+    }
+}
+
+TEST(SegmentPoolTest, GracefulUnmountCannotFinalizeUnexpectedStatus) {
+    for (auto status : {SegmentStatus::OK, SegmentStatus::DRAINING}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "graceful-status-changed");
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        auto transaction = access.PrepareGracefulUnmount(segment.id, client);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(access.SetSegmentStatusByName(segment.name, status),
+                  ErrorCode::OK);
+        EXPECT_EQ(std::move(*transaction).Finalize(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(access.Catalog().Find(segment.id)->status, status);
+        auto current = access.PrepareUnmount(segment.id, client);
+        ASSERT_TRUE(current.has_value());
+        EXPECT_EQ(std::move(*current).Commit(access), ErrorCode::OK);
+    }
+}
+
+TEST(SegmentPoolTest, StaleGracefulUnmountCannotFinalizeNewDrain) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "graceful-new-drain");
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto stale = access.PrepareGracefulUnmount(segment.id, client);
+    ASSERT_TRUE(stale.has_value());
+    ASSERT_EQ(access.SetSegmentStatusByName(segment.name, SegmentStatus::OK),
+              ErrorCode::OK);
+    auto current = access.PrepareGracefulUnmount(segment.id, client);
+    ASSERT_TRUE(current.has_value());
+    EXPECT_EQ(std::move(*stale).Finalize(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+    ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+    EXPECT_EQ(std::move(*current).Finalize(access), ErrorCode::OK);
+}
+
+TEST(SegmentPoolTest, StaleUnmountCannotModifyRegionAfterClear) {
+    for (bool rollback : {false, true}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "unmount-clear");
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        auto stale = access.PrepareUnmount(segment.id, client);
+        ASSERT_TRUE(stale.has_value());
+        access.Clear();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        auto current = access.PrepareUnmount(segment.id, client);
+        ASSERT_TRUE(current.has_value());
+        EXPECT_EQ(rollback ? std::move(*stale).Rollback(access)
+                           : std::move(*stale).Commit(access),
+                  ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+        ASSERT_NE(access.Catalog().Find(segment.id), nullptr);
+        EXPECT_EQ(access.Catalog().Find(segment.id)->status,
+                  SegmentStatus::UNMOUNTING);
+        EXPECT_EQ(std::move(*current).Rollback(access), ErrorCode::OK);
+    }
+}
+
+TEST(SegmentPoolTest, GracefulUnmountFailureConsumesTransaction) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "graceful-removed");
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto transaction = access.PrepareGracefulUnmount(segment.id, client);
+    ASSERT_TRUE(transaction.has_value());
+    access.Clear();
+    EXPECT_EQ(std::move(*transaction).Finalize(access),
+              ErrorCode::SEGMENT_NOT_FOUND);
+    EXPECT_EQ(std::move(*transaction).Finalize(access),
+              ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
+}
+
+TEST(SegmentPoolTest, RemovedCxlBindingIsInactiveWhileSiblingRemainsReadable) {
+    SegmentPool pool(Drivers(true));
+    const UUID client = generate_uuid();
+    auto first = MakeSegment(0, "first-binding", "cxl");
+    auto second = MakeSegment(1, "second-binding", "cxl");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(first, client), ErrorCode::OK);
+        ASSERT_EQ(access.MountSegment(second, client), ErrorCode::OK);
+    }
+    auto allocator = pool.AcquireReadAccess().GetAllocator(first.id);
+    auto transaction = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(first.id, client);
+    }();
+    ASSERT_TRUE(transaction.has_value());
+    EXPECT_TRUE(pool.AcquireReadAccess().IsInactive(allocator, first.name));
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(std::move(*transaction).Commit(access), ErrorCode::OK);
+    }
+    {
+        auto access = pool.AcquireReadAccess();
+        EXPECT_TRUE(access.IsInactive(allocator, first.name));
+        EXPECT_FALSE(access.IsInactive(allocator, second.name));
+    }
+    auto graceful = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareGracefulUnmount(second.id, client);
+    }();
+    ASSERT_TRUE(graceful.has_value());
+    EXPECT_FALSE(pool.AcquireReadAccess().IsInactive(allocator, second.name));
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(std::move(*graceful).Finalize(access), ErrorCode::OK);
+    }
+    EXPECT_TRUE(pool.AcquireReadAccess().IsInactive(allocator, second.name));
+}
+
+TEST(SegmentPoolTest, CxlBindingsShareUsageAndDriverCapacityLifetime) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto before = metrics.get_total_mem_capacity();
+    {
+        SegmentPool pool(Drivers(true));
+        const UUID client = generate_uuid();
+        auto first = MakeSegment(0, "cxl-first", "cxl");
+        auto second = MakeSegment(1, "cxl-second", "cxl");
+        {
+            auto access = pool.AcquireWriteAccess();
+            ASSERT_EQ(access.MountSegment(first, client), ErrorCode::OK);
+            ASSERT_EQ(access.MountSegment(second, client), ErrorCode::OK);
+        }
+        EXPECT_EQ(pool.GetMemoryUsageSnapshot().capacity_bytes, kRegionSize);
+        EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, kRegionSize);
+        EXPECT_EQ(metrics.get_total_mem_capacity(), before + kRegionSize);
+        CommitUnmount(pool, first, client);
+        CommitUnmount(pool, second, client);
+        EXPECT_EQ(metrics.get_total_mem_capacity(), before + kRegionSize);
+    }
+    EXPECT_EQ(metrics.get_total_mem_capacity(), before);
+}
+
+TEST(RegionCatalogTest, RegistrationAndRemovalKeepRelatedIndexesConsistent) {
+    RegionCatalog catalog;
+    const UUID client = generate_uuid();
+    const UUID other_client = generate_uuid();
+    auto first = MakeSegment(0, "shared", "tcp", "host");
+    auto second = MakeSegment(1, "shared", "tcp", "host");
+    ASSERT_EQ(catalog.Register({first, client, SegmentStatus::OK}),
+              ErrorCode::OK);
+    ASSERT_EQ(catalog.Register({second, client, SegmentStatus::OK}),
+              ErrorCode::OK);
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).at("host").at("shared").contains(
+        first.id));
+
+    auto duplicate = first;
+    duplicate.name = "duplicate";
+    EXPECT_EQ(catalog.Register({duplicate, other_client, SegmentStatus::OK}),
+              ErrorCode::SEGMENT_ALREADY_EXISTS);
+    auto conflict = MakeSegment(2, "shared", "tcp", "other-host");
+    EXPECT_EQ(catalog.Register({conflict, other_client, SegmentStatus::OK}),
+              ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(catalog.Regions().size(), 2U);
+    EXPECT_TRUE(catalog.RegionIds("duplicate").empty());
+    EXPECT_FALSE(ActiveRegionsByHost(catalog).contains("other-host"));
+    EXPECT_EQ(catalog.FindOwnerClientId("shared"), client);
+
+    ASSERT_TRUE(catalog.Erase(first.id));
+    EXPECT_FALSE(ActiveRegionsByHost(catalog).at("host").at("shared").contains(
+        first.id));
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).at("host").at("shared").contains(
+        second.id));
+    EXPECT_EQ(catalog.RegionIds("shared").size(), 1U);
+    ASSERT_TRUE(catalog.Erase(second.id));
+    EXPECT_TRUE(catalog.RegionIds("shared").empty());
+    EXPECT_FALSE(catalog.FindOwnerClientId("shared").has_value());
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).empty());
+    EXPECT_TRUE(catalog.Regions().empty());
+}
+
+TEST(RegionCatalogTest, StatusChangesPreserveIdentityAndOwnership) {
+    RegionCatalog catalog;
+    const UUID client = generate_uuid();
+    auto first = MakeSegment(0, "shared", "tcp", "host");
+    auto second = MakeSegment(1, "shared", "tcp", "host");
+    ASSERT_EQ(catalog.Register({first, client, SegmentStatus::DRAINING}),
+              ErrorCode::OK);
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).empty());
+    ASSERT_EQ(catalog.Register({second, client, SegmentStatus::OK}),
+              ErrorCode::OK);
+    ASSERT_TRUE(catalog.SetStatus(first.id, SegmentStatus::OK));
+    EXPECT_EQ(ActiveRegionsByHost(catalog).at("host").at("shared").size(), 2U);
+    ASSERT_TRUE(catalog.SetStatus(second.id, SegmentStatus::UNMOUNTING));
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).at("host").at("shared").contains(
+        first.id));
+    EXPECT_FALSE(ActiveRegionsByHost(catalog).at("host").at("shared").contains(
+        second.id));
+    ASSERT_TRUE(catalog.SetStatus(first.id, SegmentStatus::DRAINING));
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).empty());
+    EXPECT_EQ(catalog.RegionIds("shared").size(), 2U);
+    EXPECT_EQ(catalog.FindOwnerClientId("shared"), client);
+    EXPECT_FALSE(catalog.SetStatus(generate_uuid(), SegmentStatus::OK));
+    EXPECT_TRUE(ActiveRegionsByHost(catalog).empty());
+
+    EXPECT_EQ(catalog.Find(first.id)->status, SegmentStatus::DRAINING);
+    EXPECT_EQ(catalog.Find(second.id)->status, SegmentStatus::UNMOUNTING);
+}
+
+TEST(SegmentPoolTest, HostPlacementTracksLastMemberAndLifecycle) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto a1 = MakeSegment(0, "a", "tcp", "host-b");
+    auto a2 = MakeSegment(1, "a", "tcp", "host-b");
+    auto a3 = MakeSegment(2, "a", "tcp", "host-d");
+    auto b = MakeSegment(3, "b", "tcp", "host-b");
+    auto c = MakeSegment(4, "c", "tcp", "host-d");
+    {
+        auto access = pool.AcquireWriteAccess();
+        for (const auto& segment : {a1, a2, a3, b, c}) {
+            ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+        }
+    }
+    std::string key;
+    while (std::hash<std::string_view>{}(key) % 2 != 0) key += 'x';
+    auto names = [&] {
+        auto access = pool.AcquireReadAccess();
+        std::vector<std::string> result;
+        access.Placement().VisitHostOrderedSegmentNames(
+            "host-b", key, [&](auto name) {
+                result.emplace_back(name);
+                return false;
+            });
+        return result;
+    };
+    EXPECT_EQ(names(), (std::vector<std::string>{"a", "b", "c"}));
+    for (const auto& segment : {a1, a2, a3}) {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareUnmount(segment.id, client);
+        ASSERT_TRUE(transaction.has_value());
+        ASSERT_EQ(std::move(*transaction).Commit(access), ErrorCode::OK);
+    }
+    EXPECT_EQ(names(), (std::vector<std::string>{"b", "c"}));
+    auto graceful = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareGracefulUnmount(b.id, client);
+    }();
+    ASSERT_TRUE(graceful.has_value());
+    EXPECT_EQ(names(), (std::vector<std::string>{"c"}));
+    auto unmount = [&] {
+        auto access = pool.AcquireWriteAccess();
+        return access.PrepareUnmount(c.id, client);
+    }();
+    ASSERT_TRUE(unmount.has_value());
+    EXPECT_TRUE(names().empty());
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(std::move(*unmount).Rollback(access), ErrorCode::OK);
+        ASSERT_EQ(std::move(*graceful).Finalize(access), ErrorCode::OK);
+        ASSERT_EQ(access.MountSegment(b, client), ErrorCode::OK);
+        auto replacement = access.PrepareMount(c, client);
+        ASSERT_TRUE(replacement.has_value());
+        ASSERT_EQ(replacement->Commit(access), ErrorCode::OK);
+    }
+    EXPECT_EQ(names(), (std::vector<std::string>{"b", "c"}));
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.SetSegmentStatusByName("b", SegmentStatus::DRAINING),
+                  ErrorCode::OK);
+    }
+    EXPECT_EQ(names(), (std::vector<std::string>{"c"}));
+    CommitUnmount(pool, c, client);
+    EXPECT_TRUE(names().empty());
+    {
+        auto access = pool.AcquireWriteAccess();
+        access.Clear();
+        ASSERT_EQ(access.MountSegment(b, client), ErrorCode::OK);
+    }
+    EXPECT_EQ(names(), (std::vector<std::string>{"b"}));
+}
+
+TEST(SegmentPoolTest, AbandonedAdoptionDoesNotRegisterUsage) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "adopt-abandoned");
+    auto allocator = std::make_shared<TestBufferAllocator>(
+        segment.name, segment.te_endpoint, kRegionSize, segment.base);
+    {
+        auto access = pool.AcquireWriteAccess();
+        auto transaction = access.PrepareAdopt(
+            {segment, client, SegmentStatus::OK}, allocator, true);
+        ASSERT_TRUE(transaction.has_value());
+    }
+    EXPECT_TRUE(pool.AcquireReadAccess().Catalog().Regions().empty());
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, 0U);
+
+    SegmentPool destination(Drivers());
+    auto access = destination.AcquireWriteAccess();
+    auto transaction = access.PrepareAdopt({segment, client, SegmentStatus::OK},
+                                           allocator, true);
+    ASSERT_TRUE(transaction.has_value());
+    ASSERT_EQ(transaction->Commit(access), ErrorCode::OK);
+    EXPECT_EQ(destination.GetMemoryUsage().capacity_bytes, kRegionSize);
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, 0U);
+}
+
+TEST(SegmentPoolTest, RejectedAdoptionCommitDoesNotRegisterUsage) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "adopt-rejected");
+    auto allocator = std::make_shared<TestBufferAllocator>(
+        segment.name, segment.te_endpoint, kRegionSize, segment.base);
+    auto access = pool.AcquireWriteAccess();
+    auto transaction = access.PrepareAdopt({segment, client, SegmentStatus::OK},
+                                           allocator, true);
+    ASSERT_TRUE(transaction.has_value());
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    EXPECT_EQ(transaction->Commit(access), ErrorCode::SEGMENT_ALREADY_EXISTS);
+    access.Clear();
+    EXPECT_EQ(pool.GetMemoryUsage().capacity_bytes, 0U);
+}
+
+TEST(SegmentPoolTest, AdoptRejectsCatalogConflictWithoutReplacingResource) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "adopt-conflict");
+    auto access = pool.AcquireWriteAccess();
+    ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+    auto allocator = std::make_shared<TestBufferAllocator>(
+        segment.name, segment.te_endpoint, kRegionSize, segment.base);
+    auto duplicate = access.PrepareAdopt({segment, client, SegmentStatus::OK},
+                                         allocator, true);
+    ASSERT_FALSE(duplicate.has_value());
+    EXPECT_EQ(duplicate.error(), ErrorCode::SEGMENT_ALREADY_EXISTS);
+    segment.id = generate_uuid();
+    auto conflict = access.PrepareAdopt(
+        {segment, generate_uuid(), SegmentStatus::OK}, allocator, true);
+    ASSERT_FALSE(conflict.has_value());
+    EXPECT_EQ(conflict.error(), ErrorCode::INVALID_PARAMS);
+    EXPECT_EQ(access.Catalog().Regions().size(), 1U);
+}
+
+TEST(SegmentPoolTest, SnapshotCaptureDoesNotAcquireInheritedPoolMutex) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "fork-safe");
+    {
+        auto access = pool.AcquireWriteAccess();
+        ASSERT_EQ(access.MountSegment(segment, client), ErrorCode::OK);
+
+        // A fork child can inherit this mutex as locked by a vanished thread.
+        // Capture must not acquire the inherited runtime lock.
+        auto encoded = CaptureAndEncode(pool, LocalSsdPersistedState{});
+        ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+    }
+    CommitUnmount(pool, segment, client);
+}
+
+TEST(SegmentPoolTest, SnapshotRoundTripPreservesCatalogAndHost) {
+    SegmentPool source(Drivers());
+    const UUID client = generate_uuid();
+    auto segment = MakeSegment(0, "snapshot", "tcp", "host-a");
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(source, LocalSsdPersistedState{});
+    ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+    SegmentPool restored(Drivers());
+    auto stale = MakeSegment(1, "stale");
+    ASSERT_EQ(restored.AcquireWriteAccess().MountSegment(stale, client),
+              ErrorCode::OK);
+    // Replacement must also allow an existing UUID and a different old owner.
+    ASSERT_EQ(
+        restored.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+        ErrorCode::OK);
+    auto decoded = DecodeAndRestore(restored, *encoded, false);
+    ASSERT_TRUE(decoded.has_value()) << decoded.error().message;
+
+    {
+        auto view = restored.AcquireReadAccess();
+        EXPECT_EQ(view.Catalog().Find(stale.id), nullptr);
+        const auto* mounted = view.Catalog().Find(segment.id);
+        ASSERT_NE(mounted, nullptr);
+        EXPECT_EQ(mounted->segment.host_id, segment.host_id);
+        EXPECT_EQ(mounted->client_id, client);
+        EXPECT_EQ(mounted->status, SegmentStatus::OK);
+    }
+
+    restored.AcquireWriteAccess().Clear();
+    CommitUnmount(source, segment, client);
+}
+
+TEST(SegmentPoolTest, RestoreSnapshotRejectsConflictsBeforeReplacingPool) {
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "restore-conflict");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto allocator = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto snapshot = pool.CaptureSnapshot();
+    auto duplicate = pool.CaptureSnapshot();
+    ASSERT_TRUE(snapshot);
+    ASSERT_TRUE(duplicate);
+    snapshot->regions.push_back(std::move(duplicate->regions.front()));
+    EXPECT_FALSE(pool.RestoreSnapshot(std::move(*snapshot), true));
+    EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), allocator);
+
+    auto invalid = pool.CaptureSnapshot();
+    ASSERT_TRUE(invalid);
+    invalid->regions.front().allocator.allocation_state.layout.reset();
+    EXPECT_FALSE(pool.RestoreSnapshot(std::move(*invalid), true));
+    EXPECT_EQ(pool.AcquireReadAccess().GetAllocator(segment.id), allocator);
+}
+
+TEST(SegmentPoolTest, SnapshotReplacementPreservesAllocatedMetrics) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline = metrics.get_allocated_mem_size();
+
+    for (bool account_capacity : {false, true}) {
+        SegmentPool pool(Drivers());
+        const UUID client = generate_uuid();
+        auto segment = MakeSegment(0, "snapshot-allocated-metrics");
+        ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, client),
+                  ErrorCode::OK);
+        auto buffer =
+            pool.AcquireReadAccess().GetAllocator(segment.id)->allocate(4096);
+        ASSERT_NE(buffer, nullptr);
+        auto encoded = CaptureAndEncode(pool, LocalSsdPersistedState{});
+        ASSERT_TRUE(encoded.has_value()) << encoded.error().message;
+
+        auto decoded = DecodeAndRestore(pool, *encoded, account_capacity);
+        ASSERT_TRUE(decoded.has_value()) << decoded.error().message;
+        buffer.reset();  // The replaced allocator is no longer live.
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline + 4096);
+        EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 4096);
+        EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
+                  account_capacity ? kRegionSize : 0);
+        {
+            auto next = pool.AcquireReadAccess()
+                            .GetAllocator(segment.id)
+                            ->allocate(4096);
+            ASSERT_NE(next, nullptr);
+            EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name),
+                      8192);
+        }
+        EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 4096);
+        pool.AcquireWriteAccess().Clear();
+        EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+        EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
+    }
+}
+
+TEST(SegmentPoolTest, SnapshotRestoresPlacementAndEveryLifecycleStatus) {
+    SegmentPool source(Drivers());
+    const UUID client = generate_uuid();
+    std::vector<Segment> segments;
+    const std::vector<SegmentStatus> statuses{
+        SegmentStatus::OK,        SegmentStatus::OK,
+        SegmentStatus::UNDEFINED, SegmentStatus::DRAINING,
+        SegmentStatus::DRAINED,   SegmentStatus::GRACEFULLY_UNMOUNTING,
+        SegmentStatus::UNMOUNTING};
+    for (size_t i = 0; i < statuses.size(); ++i) {
+        segments.push_back(MakeSegment(i, "lifecycle-" + std::to_string(i),
+                                       "tcp", "host-" + std::to_string(i)));
+        auto access = source.AcquireWriteAccess();
+        ASSERT_EQ(
+            access.MountSegment(segments.back(), i == 1 ? UUID{8, 9} : client),
+            ErrorCode::OK);
+        ASSERT_EQ(
+            access.SetSegmentStatusByName(segments.back().name, statuses[i]),
+            ErrorCode::OK);
+    }
+
+    // Same-name regions must all survive; only their logical name is
+    // deduplicated.
+    auto sibling = MakeSegment(8, segments[0].name, "tcp", segments[0].host_id);
+    ASSERT_EQ(source.AcquireWriteAccess().MountSegment(sibling, client),
+              ErrorCode::OK);
+    auto encoded = CaptureAndEncode(source, {});
+    ASSERT_TRUE(encoded.has_value());
+    SegmentPool restored(Drivers());
+    ASSERT_TRUE(DecodeAndRestore(restored, *encoded, false).has_value());
+    {
+        auto access = restored.AcquireReadAccess();
+        EXPECT_EQ(access.Catalog().Regions().size(), segments.size() + 1);
+        for (size_t i = 0; i < segments.size(); ++i) {
+            const auto* region = access.Catalog().Find(segments[i].id);
+            ASSERT_NE(region, nullptr);
+            EXPECT_EQ(region->status, statuses[i]);
+            EXPECT_EQ(region->client_id, i == 1 ? (UUID{8, 9}) : client);
+            EXPECT_EQ(access.Placement().Contains(
+                          segments[i].name, AllocationCandidateKind::NATIVE),
+                      statuses[i] == SegmentStatus::OK);
+            EXPECT_NE(access.GetAllocator(segments[i].id), nullptr);
+        }
+        std::vector<std::string> names;
+        access.Placement().GetActiveSegmentNames(
+            AllocationCandidateKind::NATIVE, names);
+        EXPECT_EQ(names, (std::vector<std::string>{segments[0].name,
+                                                   segments[1].name}));
+        std::vector<std::string> by_host;
+        access.Placement().VisitHostOrderedSegmentNames(
+            segments[1].host_id, "key", [&](auto name) {
+                by_host.emplace_back(name);
+                return false;
+            });
+        ASSERT_EQ(by_host.size(), 2U);
+        EXPECT_EQ(by_host.front(), segments[1].name);
+        const auto* entry = access.Placement().Find(
+            segments[0].name, AllocationCandidateKind::NATIVE);
+        ASSERT_NE(entry, nullptr);
+        EXPECT_EQ(entry->candidates.size(), 2U);
+    }
+
+    CommitUnmount(restored, segments[0], client);
+    EXPECT_TRUE(restored.AcquireReadAccess().Placement().Contains(
+        sibling.name, AllocationCandidateKind::NATIVE));
+    CommitUnmount(restored, sibling, client);
+    EXPECT_FALSE(restored.AcquireReadAccess().Placement().Contains(
+        sibling.name, AllocationCandidateKind::NATIVE));
+    auto buffer = restored.AcquireReadAccess()
+                      .GetAllocator(segments[1].id)
+                      ->allocate(4096);
+    ASSERT_NE(buffer, nullptr);
+}
+
+TEST(SegmentPoolTest,
+     SnapshotPreservesFragmentationAndLegacyAllocationHandles) {
+    SegmentManager legacy(BufferAllocatorType::OFFSET);
+    const UUID client = generate_uuid();
+    const auto segment = MakeSegment(0, "snapshot-handles");
+    const auto client_liveness = std::make_shared<ClientLivenessRecord>(
+        ClientLivenessRecord::Clock::now());
+    ASSERT_EQ(legacy.getSegmentAccess().MountSegment(segment, client,
+                                                     client_liveness),
+              ErrorCode::OK);
+
+    // SegmentManager does not release capacity in its destructor.
+    legacy.releaseCapacityMetrics();
+    auto allocator = legacy.getSegmentAccess().GetAllocator(segment.id);
+    auto first = allocator->allocate(4096);
+    auto hole = allocator->allocate(4096);
+    auto last = allocator->allocate(4096);
+    ASSERT_NE(first, nullptr);
+    ASSERT_NE(hole, nullptr);
+    ASSERT_NE(last, nullptr);
+    hole.reset();
+
+    msgpack::sbuffer handles;
+    MsgpackPacker packer(&handles);
+    packer.pack_array(2);
+    ASSERT_TRUE(
+        Serializer<AllocatedBuffer>::serialize(*first, legacy.getView(), packer)
+            .has_value());
+    ASSERT_TRUE(
+        Serializer<AllocatedBuffer>::serialize(*last, legacy.getView(), packer)
+            .has_value());
+
+    auto encoded = SegmentSerializer(&legacy).Serialize({});
+    ASSERT_TRUE(encoded.has_value());
+    SegmentPool restored(Drivers());
+    ASSERT_TRUE(DecodeAndRestore(restored, *encoded, false).has_value());
+    auto target = std::dynamic_pointer_cast<OffsetBufferAllocator>(
+        restored.AcquireReadAccess().GetAllocator(segment.id));
+    ASSERT_NE(target, nullptr);
+    EXPECT_EQ(restored.GetMemoryUsage().used_bytes, 8192U);
+
+    auto next = target->allocate(4096);
+    ASSERT_NE(next, nullptr);
+    EXPECT_NE(next->data(), first->data());
+    EXPECT_NE(next->data(), last->data());
+    next.reset();
+
+    auto objects = msgpack::unpack(handles.data(), handles.size());
+    for (uint32_t i = 0; i < 2; ++i) {
+        const auto& fields = objects.get().via.array.ptr[i].via.array;
+        auto handle =
+            Serializer<offset_allocator::OffsetAllocationHandle>::deserialize(
+                fields.ptr[4], target->getOffsetAllocator());
+        ASSERT_TRUE(handle.has_value());
+        auto buffer = std::make_unique<AllocatedBuffer>(
+            target, reinterpret_cast<void*>(fields.ptr[1].as<uint64_t>()),
+            fields.ptr[0].as<uint64_t>(), std::move(**handle));
+        buffer.reset();
+        EXPECT_EQ(restored.GetMemoryUsage().used_bytes, (1U - i) * 4096U);
+    }
+
+    // Restored handles released and coalesced every block.
+    auto all = target->allocate(kRegionSize);
+    ASSERT_NE(all, nullptr);
+}
+
+TEST(SegmentPoolTest, SnapshotReadersAndEmptyReplacementBalanceMetrics) {
+    auto& metrics = MasterMetricManager::instance();
+    SegmentPool source(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-reader");
+    ASSERT_EQ(
+        source.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+        ErrorCode::OK);
+    auto live =
+        source.AcquireReadAccess().GetAllocator(segment.id)->allocate(4096);
+    ASSERT_NE(live, nullptr);
+    auto encoded = CaptureAndEncode(source, {});
+    ASSERT_TRUE(encoded.has_value());
+
+    SegmentPool empty(Drivers());
+    auto empty_encoded = CaptureAndEncode(empty, {});
+    ASSERT_TRUE(empty_encoded.has_value());
+    const auto baseline_used = metrics.get_allocated_mem_size();
+    const auto baseline_capacity = metrics.get_total_mem_capacity();
+
+    for (bool account_capacity : {false, true}) {
+        for (bool clear_with_empty : {false, true}) {
+            {
+                SegmentPool reader(Drivers());
+                for (int i = 0; i < 3; ++i) {
+                    ASSERT_TRUE(
+                        DecodeAndRestore(reader, *encoded, account_capacity)
+                            .has_value());
+                    EXPECT_EQ(reader.GetMemoryUsage().used_bytes, 4096U);
+                    EXPECT_EQ(reader.GetMemoryUsage().capacity_bytes,
+                              kRegionSize);
+                    EXPECT_EQ(metrics.get_allocated_mem_size(),
+                              baseline_used + 4096);
+                    EXPECT_EQ(metrics.get_total_mem_capacity(),
+                              baseline_capacity +
+                                  (account_capacity ? kRegionSize : 0));
+                }
+
+                if (clear_with_empty) {
+                    ASSERT_TRUE(DecodeAndRestore(reader, *empty_encoded,
+                                                 account_capacity)
+                                    .has_value());
+                    EXPECT_TRUE(
+                        reader.AcquireReadAccess().Catalog().Regions().empty());
+                    EXPECT_EQ(reader.GetMemoryUsage().used_bytes, 0U);
+                    EXPECT_EQ(reader.GetMemoryUsage().capacity_bytes, 0U);
+                    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline_used);
+                }
+            }
+            EXPECT_EQ(metrics.get_allocated_mem_size(), baseline_used);
+            EXPECT_EQ(metrics.get_total_mem_capacity(), baseline_capacity);
+            EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name),
+                      4096);
+            EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
+                      kRegionSize);
+        }
+    }
+}
+
+TEST(SegmentPoolTest, SnapshotReplacementBalancesExternallyRetainedAllocator) {
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline = metrics.get_allocated_mem_size();
+    SegmentPool pool(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-retained");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+              ErrorCode::OK);
+    auto retained = pool.AcquireReadAccess().GetAllocator(segment.id);
+    auto old_buffer = retained->allocate(4096);
+    ASSERT_NE(old_buffer, nullptr);
+    auto encoded = CaptureAndEncode(pool, {});
+    ASSERT_TRUE(encoded.has_value());
+    ASSERT_TRUE(DecodeAndRestore(pool, *encoded, true).has_value());
+    EXPECT_NE(pool.AcquireReadAccess().GetAllocator(segment.id), retained);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline + 8192);
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 8192);
+
+    // Clearing the replacement must not erase the old allocator's usage label.
+    pool.AcquireWriteAccess().Clear();
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name), 0);
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 4096);
+
+    old_buffer.reset();
+    retained.reset();
+    EXPECT_EQ(metrics.get_segment_allocated_mem_size(segment.name), 0);
+    EXPECT_EQ(metrics.get_allocated_mem_size(), baseline);
+    EXPECT_EQ(pool.GetMemoryUsage().used_bytes, 0U);
+}
+
+TEST(SegmentPoolTest, DestroyedPoolAndRetainedAllocatorRemoveMetricLabels) {
+    auto& metrics = MasterMetricManager::instance();
+    for (bool retain_allocator : {false, true}) {
+        SCOPED_TRACE(retain_allocator);
+        const std::string name = "snapshot-label-cleanup";
+        const std::string label = "segment=\"" + name + "\"";
+        std::shared_ptr<BufferAllocatorBase> retained;
+        {
+            SegmentPool source(Drivers());
+            auto segment = MakeSegment(0, name);
+            ASSERT_EQ(source.AcquireWriteAccess().MountSegment(segment,
+                                                               generate_uuid()),
+                      ErrorCode::OK);
+            auto live = source.AcquireReadAccess()
+                            .GetAllocator(segment.id)
+                            ->allocate(4096);
+            ASSERT_NE(live, nullptr);
+            auto encoded = CaptureAndEncode(source, {});
+            ASSERT_TRUE(encoded.has_value());
+            SegmentPool restored(Drivers());
+            ASSERT_TRUE(DecodeAndRestore(restored, *encoded, true).has_value());
+            if (retain_allocator) {
+                retained =
+                    restored.AcquireReadAccess().GetAllocator(segment.id);
+            }
+            EXPECT_NE(metrics.serialize_metrics().find(label),
+                      std::string::npos);
+        }
+        if (retain_allocator) {
+            EXPECT_EQ(metrics.get_segment_allocated_mem_size(name), 4096);
+            EXPECT_NE(metrics.serialize_metrics().find(label),
+                      std::string::npos);
+        }
+        retained.reset();
+        EXPECT_EQ(metrics.get_segment_allocated_mem_size(name), 0);
+        EXPECT_EQ(metrics.get_segment_total_mem_capacity(name), 0);
+        EXPECT_EQ(metrics.serialize_metrics().find(label), std::string::npos);
+    }
+}
+
+TEST(SegmentPoolTest, EmptySnapshotAllocatorKeepsOtherPoolsCapacityLabels) {
+    SegmentPool source(Drivers());
+    const auto segment = MakeSegment(0, "snapshot-shared-capacity");
+    ASSERT_EQ(
+        source.AcquireWriteAccess().MountSegment(segment, generate_uuid()),
+        ErrorCode::OK);
+    auto encoded = CaptureAndEncode(source, {});
+    ASSERT_TRUE(encoded.has_value());
+    auto& metrics = MasterMetricManager::instance();
+    const auto baseline = metrics.get_total_mem_capacity();
+    {
+        SegmentPool reader(Drivers());
+        ASSERT_TRUE(DecodeAndRestore(reader, *encoded, true).has_value());
+        EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
+                  2 * kRegionSize);
+        reader.AcquireWriteAccess().Clear();
+    }
+    EXPECT_EQ(metrics.get_total_mem_capacity(), baseline);
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name),
+              kRegionSize);
+    source.AcquireWriteAccess().Clear();
+    EXPECT_EQ(metrics.get_segment_total_mem_capacity(segment.name), 0);
+}
+
+TEST(SegmentPoolTest, ForkedSnapshotEncodesWhileAnotherThreadOwnsPoolLock) {
+    SegmentPool pool(Drivers());
+    const UUID client = generate_uuid();
+    const auto segment = MakeSegment(0, "real-fork");
+    ASSERT_EQ(pool.AcquireWriteAccess().MountSegment(segment, client),
+              ErrorCode::OK);
+    auto live =
+        pool.AcquireReadAccess().GetAllocator(segment.id)->allocate(4096);
+    ASSERT_NE(live, nullptr);
+
+    int fds[2];
+    ASSERT_EQ(pipe(fds), 0);
+    std::promise<void> locked, release;
+    auto released = release.get_future();
+    std::thread holder([&] {
+        auto access = pool.AcquireWriteAccess();
+        locked.set_value();
+        released.wait();
+    });
+    locked.get_future().wait();
+
+    const pid_t child = fork();
+    if (child == 0) {
+        close(fds[0]);
+        alarm(10);  // A lock regression must fail, not hang the test suite.
+        auto encoded = CaptureAndEncode(pool, {});
+        if (!encoded) {
+            _exit(1);
+        }
+
+        size_t offset = 0;
+        while (offset < encoded->size()) {
+            const auto n = write(fds[1], encoded->data() + offset,
+                                 encoded->size() - offset);
+            if (n < 0 && errno == EINTR) {
+                continue;
+            }
+            if (n <= 0) {
+                _exit(2);
+            }
+            offset += static_cast<size_t>(n);
+        }
+        _exit(0);
+    }
+
+    close(fds[1]);
+    release.set_value();
+    holder.join();
+
+    std::vector<uint8_t> bytes;
+    uint8_t chunk[4096];
+    ssize_t n;
+    while ((n = read(fds[0], chunk, sizeof(chunk))) != 0) {
+        if (n < 0 && errno == EINTR) {
+            continue;
+        }
+        if (n < 0) {
+            break;
+        }
+        bytes.insert(bytes.end(), chunk, chunk + n);
+    }
+    close(fds[0]);
+    ASSERT_GT(child, 0);
+
+    int status = 0;
+    pid_t waited;
+    do {
+        waited = waitpid(child, &status, 0);
+    } while (waited < 0 && errno == EINTR);
+    ASSERT_EQ(waited, child);
+    ASSERT_TRUE(WIFEXITED(status)) << status;
+    ASSERT_EQ(WEXITSTATUS(status), 0);
+
+    SegmentPool restored(Drivers());
+    ASSERT_TRUE(DecodeAndRestore(restored, bytes, false).has_value());
+    EXPECT_EQ(restored.GetMemoryUsage().used_bytes, 4096U);
+    EXPECT_NE(restored.AcquireReadAccess().Catalog().Find(segment.id), nullptr);
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/segment_test.cpp b/mooncake-store/tests/segment_test.cpp
index 60b7362061..942acf7fba 100644
--- a/mooncake-store/tests/segment_test.cpp
+++ b/mooncake-store/tests/segment_test.cpp
@@ -1,20 +1,71 @@
 #include "segment.h"
 
+#include "master_metric_manager.h"
+
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
 #include <boost/functional/hash.hpp>
 
 #include <algorithm>
+#include <atomic>
+#include <chrono>
 #include <functional>
+#include <future>
+#include <mutex>
+#include <semaphore>
 #include <string>
+#include <thread>
 #include <vector>
 
 namespace mooncake {
 
+namespace {
+
+class BlockingOffsetBufferAllocator : public OffsetBufferAllocator {
+   public:
+    BlockingOffsetBufferAllocator(std::string segment_name, size_t base,
+                                  size_t size, std::string transport_endpoint)
+        : OffsetBufferAllocator(std::move(segment_name), base, size,
+                                std::move(transport_endpoint)) {}
+
+    void deallocate(AllocatedBuffer* handle) override {
+        entered_.release();
+        resume_.acquire();
+        OffsetBufferAllocator::deallocate(handle);
+    }
+
+    std::binary_semaphore entered_{0};
+    std::binary_semaphore resume_{0};
+};
+
+class BlockingAllocateOffsetBufferAllocator : public OffsetBufferAllocator {
+   public:
+    BlockingAllocateOffsetBufferAllocator(std::string segment_name, size_t base,
+                                          size_t size,
+                                          std::string transport_endpoint)
+        : OffsetBufferAllocator(std::move(segment_name), base, size,
+                                std::move(transport_endpoint)) {}
+
+    std::unique_ptr<AllocatedBuffer> allocate(size_t size) override {
+        entered_.release();
+        resume_.acquire();
+        return OffsetBufferAllocator::allocate(size);
+    }
+
+    std::binary_semaphore entered_{0};
+    std::binary_semaphore resume_{0};
+};
+
+}  // namespace
+
 // Test fixture for Segment tests
 class SegmentTest : public ::testing::Test {
    protected:
+    std::shared_ptr<ClientLivenessRecord> client_liveness_ =
+        std::make_shared<ClientLivenessRecord>(
+            ClientLivenessRecord::Clock::now());
+
     void SetUp() override {
         // Initialize glog for logging
         google::InitGoogleLogging("EvictionStrategyTest");
@@ -77,9 +128,8 @@ class SegmentTest : public ::testing::Test {
             // validate allocator exist in allocator_manager
             MountedSegment mounted_segment =
                 segment_manager.mounted_segments_.at(segment.id);
-            auto allocator = mounted_segment.buf_allocator;
             ASSERT_NE(std::find(allocators->begin(), allocators->end(),
-                                mounted_segment.buf_allocator),
+                                mounted_segment.allocator_registration),
                       allocators->end());
         }
     }
@@ -110,36 +160,35 @@ class SegmentTest : public ::testing::Test {
         }
 
         return std::find(allocators->begin(), allocators->end(),
-                         mounted_segment.buf_allocator) != allocators->end();
+                         mounted_segment.allocator_registration) !=
+               allocators->end();
     }
-
-    void ValidateMountedLocalDiskSegments(
-        const SegmentManager& segment_manager,
-        const std::vector<std::shared_ptr<LocalDiskSegment>>& segments,
-        const std::vector<UUID>& client_ids) {
-        size_t total_num = segment_manager.client_local_disk_segment_.size();
-        ASSERT_EQ(total_num, segments.size());
-        for (size_t i = 0; i < client_ids.size(); i++) {
-            LOG(INFO) << "Mounted local disk segment " << client_ids[i];
-            auto client_it =
-                segment_manager.client_local_disk_segment_.find(client_ids[i]);
-            ASSERT_NE(client_it,
-                      segment_manager.client_local_disk_segment_.end());
-            const auto& segment = segments.at(i);
-            ASSERT_EQ(client_it->second->enable_offloading,
-                      segment->enable_offloading);
+    void InstallSharedCxlAllocatorForTesting(
+        SegmentManager& segment_manager,
+        const std::shared_ptr<BufferAllocatorBase>& allocator,
+        const std::vector<Segment>& segments) {
+        if (segment_manager.cxl_global_allocator_ != allocator) {
+            allocator->AttachUsageTracker(segment_manager.usage_tracker_);
+            segment_manager.cxl_global_allocator_ = allocator;
+        }
+        for (const auto& segment : segments) {
+            segment_manager.mounted_segments_[segment.id] = {
+                segment, SegmentStatus::OK, allocator, nullptr};
         }
     }
 
-    void ValidateMountedLocalDiskSegments(
-        const SegmentManager& segment_manager,
-        const std::shared_ptr<LocalDiskSegment>& segment,
-        const UUID& client_id) {
-        std::vector<std::shared_ptr<LocalDiskSegment>> segments;
-        segments.push_back(segment);
-        std::vector<UUID> client_ids;
-        client_ids.push_back(client_id);
-        ValidateMountedLocalDiskSegments(segment_manager, segments, client_ids);
+    std::unique_lock<std::shared_mutex> HoldSegmentMutexForTesting(
+        SegmentManager& segment_manager) {
+        return std::unique_lock<std::shared_mutex>(
+            segment_manager.segment_mutex_);
+    }
+
+    std::shared_ptr<BufferAllocatorBase> GetNoFAllocatorForTesting(
+        NoFSegmentManager& segment_manager, const UUID& segment_id) {
+        auto it = segment_manager.mounted_segments_.find(segment_id);
+        return it == segment_manager.mounted_segments_.end()
+                   ? nullptr
+                   : it->second.buf_allocator;
     }
 };
 
@@ -157,18 +206,326 @@ TEST_F(SegmentTest, MountSegmentSuccess) {
 
     // Get segment access and attempt to mount
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
 
     // Verify segment is properly mounted
     ValidateMountedSegment(segment_manager, segment, client_id);
 }
 
+TEST_F(SegmentTest, MemoryUsageSnapshotTracksMountedAllocatorState) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kAllocationSize = 4 * 1024 * 1024;
+
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "usage_snapshot_segment";
+    segment.size = kSegmentSize;
+    segment.base = 0x100000000;
+    UUID client_id = generate_uuid();
+
+    std::shared_ptr<BufferAllocatorBase> allocator;
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
+        allocator = segment_access.GetAllocator(segment.id);
+    }
+    ASSERT_NE(allocator, nullptr);
+
+    auto buffer = allocator->allocate(kAllocationSize);
+    ASSERT_NE(buffer, nullptr);
+
+    auto snapshot = segment_manager.GetMemoryUsageSnapshot();
+    auto usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(snapshot.used_ratio(), 0.25);
+    EXPECT_EQ(usage.used_bytes, kAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(usage.used_ratio(), 0.25);
+    ASSERT_EQ(snapshot.segments.size(), 1u);
+    EXPECT_EQ(snapshot.segments.at(segment.name).used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.segments.at(segment.name).capacity_bytes, kSegmentSize);
+
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(segment_access.SetSegmentStatusByName(
+                      segment.name, SegmentStatus::DRAINING),
+                  ErrorCode::OK);
+    }
+    snapshot = segment_manager.GetMemoryUsageSnapshot();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+
+    buffer.reset();
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        size_t metrics_dec_capacity = 0;
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment.id,
+                                                       metrics_dec_capacity),
+                  ErrorCode::OK);
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment.id, client_id,
+                                                      metrics_dec_capacity),
+                  ErrorCode::OK);
+    }
+    allocator.reset();
+
+    snapshot = segment_manager.GetMemoryUsageSnapshot();
+    usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(snapshot.used_bytes, 0u);
+    EXPECT_EQ(snapshot.capacity_bytes, 0u);
+    EXPECT_DOUBLE_EQ(snapshot.used_ratio(), 0.0);
+    EXPECT_EQ(usage.used_bytes, 0u);
+    EXPECT_EQ(usage.capacity_bytes, 0u);
+}
+
+TEST_F(SegmentTest, AggregateMemoryUsageDoesNotTakeSegmentMutex) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    auto segment_lock = HoldSegmentMutexForTesting(segment_manager);
+    auto usage = std::async(std::launch::async, [&segment_manager] {
+        return segment_manager.GetMemoryUsage();
+    });
+
+    const auto status = usage.wait_for(std::chrono::seconds(1));
+    segment_lock.unlock();
+
+    ASSERT_EQ(status, std::future_status::ready);
+    EXPECT_EQ(usage.get().capacity_bytes, 0u);
+}
+
+TEST_F(SegmentTest, AggregateUsageSurvivesConcurrentUnmountAndDeallocate) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kAllocationSize = 4 * 1024 * 1024;
+
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "usage_race_segment";
+    segment.size = kSegmentSize;
+    segment.base = 0x1C0000000;
+    UUID client_id = generate_uuid();
+
+    auto blocking = std::make_shared<BlockingOffsetBufferAllocator>(
+        segment.name, segment.base, segment.size, segment.te_endpoint);
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
+        auto original = segment_access.GetAllocator(segment.id);
+        ASSERT_NE(original, nullptr);
+        ASSERT_TRUE(segment_access.ReplaceAllocators(
+            {{segment.id, original, blocking}}));
+    }
+    auto buffer = blocking->allocate(kAllocationSize);
+    ASSERT_NE(buffer, nullptr);
+
+    {
+        std::thread dealloc_thread([&buffer] { buffer.reset(); });
+        struct ResumeAndJoin {
+            BlockingOffsetBufferAllocator& blocking;
+            std::thread& thread;
+            ~ResumeAndJoin() {
+                blocking.resume_.release();
+                if (thread.joinable()) {
+                    thread.join();
+                }
+            }
+        } resume_and_join{*blocking, dealloc_thread};
+
+        ASSERT_TRUE(blocking->entered_.try_acquire_for(std::chrono::seconds(5)))
+            << "deallocate did not enter BlockingOffsetBufferAllocator";
+
+        auto segment_access = segment_manager.getSegmentAccess();
+        size_t metrics_dec_capacity = 0;
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment.id,
+                                                       metrics_dec_capacity),
+                  ErrorCode::OK);
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment.id, client_id,
+                                                      metrics_dec_capacity),
+                  ErrorCode::OK);
+    }
+    blocking.reset();
+
+    const auto usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(usage.used_bytes, 0u);
+    EXPECT_EQ(usage.capacity_bytes, 0u);
+}
+
+TEST_F(SegmentTest, AggregateMemoryUsageFollowsAllocatorReplacement) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kOldAllocationSize = 4 * 1024 * 1024;
+    constexpr size_t kRestoredAllocationSize = 8 * 1024 * 1024;
+
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "usage_replacement_segment";
+    segment.size = kSegmentSize;
+    segment.base = 0x180000000;
+    UUID client_id = generate_uuid();
+
+    std::shared_ptr<BufferAllocatorBase> old_allocator;
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
+        old_allocator = segment_access.GetAllocator(segment.id);
+    }
+    ASSERT_NE(old_allocator, nullptr);
+    auto old_buffer = old_allocator->allocate(kOldAllocationSize);
+    ASSERT_NE(old_buffer, nullptr);
+
+    auto replacement = std::make_shared<OffsetBufferAllocator>(
+        segment.name, segment.base, segment.size, segment.te_endpoint);
+    auto restored_buffer = replacement->allocate(kRestoredAllocationSize);
+    ASSERT_NE(restored_buffer, nullptr);
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_TRUE(segment_access.ReplaceAllocators(
+            {{segment.id, old_allocator, replacement}}));
+    }
+    old_allocator.reset();
+
+    auto usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(usage.used_bytes, kRestoredAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+
+    old_buffer.reset();
+    usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(usage.used_bytes, kRestoredAllocationSize);
+
+    restored_buffer.reset();
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        size_t metrics_dec_capacity = 0;
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment.id,
+                                                       metrics_dec_capacity),
+                  ErrorCode::OK);
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment.id, client_id,
+                                                      metrics_dec_capacity),
+                  ErrorCode::OK);
+    }
+    replacement.reset();
+    EXPECT_EQ(segment_manager.GetMemoryUsage().capacity_bytes, 0u);
+}
+
+TEST_F(SegmentTest, MemoryUsageSnapshotCountsSharedCxlAllocatorOnce) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET,
+                                   /*enable_cxl=*/true);
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kAllocationSize = 4 * 1024 * 1024;
+    auto allocator = std::make_shared<OffsetBufferAllocator>(
+        "cxl_pool", 0x200000000, kSegmentSize, "cxl_pool");
+    InstallSharedCxlAllocatorForTesting(segment_manager, allocator, {});
+
+    auto buffer = allocator->allocate(kAllocationSize);
+    ASSERT_NE(buffer, nullptr);
+
+    auto snapshot = segment_manager.GetMemoryUsageSnapshot();
+    auto usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+    EXPECT_EQ(usage.used_bytes, kAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+
+    Segment first;
+    first.id = generate_uuid();
+    first.name = "cxl_client_a";
+    first.protocol = "cxl";
+    Segment second;
+    second.id = generate_uuid();
+    second.name = "cxl_client_b";
+    second.protocol = "cxl";
+    InstallSharedCxlAllocatorForTesting(segment_manager, allocator,
+                                        {first, second});
+
+    snapshot = segment_manager.GetMemoryUsageSnapshot();
+    usage = segment_manager.GetMemoryUsage();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+    EXPECT_EQ(usage.used_bytes, kAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+    ASSERT_EQ(snapshot.segments.size(), 1u);
+    EXPECT_EQ(snapshot.segments.at("cxl_pool").used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.segments.at("cxl_pool").capacity_bytes, kSegmentSize);
+}
+
+TEST_F(SegmentTest, NoFUsageSnapshotSurvivesMetricsReset) {
+    NoFSegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    constexpr size_t kSegmentSize = 16 * 1024 * 1024;
+    constexpr size_t kAllocationSize = 4 * 1024 * 1024;
+
+    NoFSegment segment;
+    segment.id = generate_uuid();
+    segment.name = "nof_usage_snapshot_segment";
+    segment.size = kSegmentSize;
+    segment.base = 0x300000000;
+    segment.te_endpoint = "nof_usage_snapshot_endpoint";
+    UUID client_id = generate_uuid();
+
+    {
+        auto segment_access = segment_manager.getNoFSegmentAccess();
+        ASSERT_EQ(segment_access.MountSegment(segment, client_id),
+                  ErrorCode::OK);
+    }
+    auto allocator = GetNoFAllocatorForTesting(segment_manager, segment.id);
+    ASSERT_NE(allocator, nullptr);
+    auto buffer = allocator->allocate(kAllocationSize);
+    ASSERT_NE(buffer, nullptr);
+
+    auto snapshot = segment_manager.GetUsageSnapshot();
+    auto usage = segment_manager.GetUsage();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(snapshot.used_ratio(), 0.25);
+    EXPECT_EQ(usage.used_bytes, kAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(usage.used_ratio(), 0.25);
+
+    auto& metrics = MasterMetricManager::instance();
+    metrics.reset_allocated_nof_size();
+    metrics.reset_total_nof_capacity();
+    EXPECT_EQ(metrics.get_allocated_nof_size(), 0);
+    EXPECT_EQ(metrics.get_total_nof_capacity(), 0);
+
+    snapshot = segment_manager.GetUsageSnapshot();
+    usage = segment_manager.GetUsage();
+    EXPECT_EQ(snapshot.used_bytes, kAllocationSize);
+    EXPECT_EQ(snapshot.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(snapshot.used_ratio(), 0.25);
+    EXPECT_EQ(usage.used_bytes, kAllocationSize);
+    EXPECT_EQ(usage.capacity_bytes, kSegmentSize);
+    EXPECT_DOUBLE_EQ(usage.used_ratio(), 0.25);
+
+    // Restore global gauges before teardown because allocator and segment
+    // cleanup still emit their matching decrements.
+    metrics.inc_allocated_nof_size("", kAllocationSize);
+    metrics.inc_total_nof_capacity("", kSegmentSize);
+    buffer.reset();
+    {
+        auto segment_access = segment_manager.getNoFSegmentAccess();
+        size_t metrics_dec_capacity = 0;
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment.id,
+                                                       metrics_dec_capacity),
+                  ErrorCode::OK);
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment.id, client_id,
+                                                      metrics_dec_capacity),
+                  ErrorCode::OK);
+    }
+    allocator.reset();
+    EXPECT_EQ(segment_manager.GetUsage().used_bytes, 0u);
+    EXPECT_EQ(segment_manager.GetUsage().capacity_bytes, 0u);
+}
+
 // MountSegmentDuplicate Tests:
 // 1. MountSegment with the same segment id. The second mount operation return
 // SEGMENT_ALREADY_EXISTS.
-// 2. MountSegment with different segment id and the same segment name should be
-// considered as different segments. Validate the status of SegmentManager use
-// ValidateMountedSegments function.
+// 2. Different segment ids may share the client hostname as their name.
 TEST_F(SegmentTest, MountSegmentDuplicate) {
     SegmentManager segment_manager;
     // Create a valid segment and client ID
@@ -182,13 +539,14 @@ TEST_F(SegmentTest, MountSegmentDuplicate) {
 
     // Get segment access and mount first time
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
 
     // Verify first mount
     ValidateMountedSegment(segment_manager, segment, client_id);
 
     // Test duplicate mount - mount the same segment again
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id),
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
               ErrorCode::SEGMENT_ALREADY_EXISTS);
 
     // Verify state remains the same after duplicate mount
@@ -201,13 +559,14 @@ TEST_F(SegmentTest, MountSegmentDuplicate) {
     segment2.size = segment.size * 2;
     segment2.base = segment.base + segment.size;
 
-    // Mount the second segment
-    ASSERT_EQ(segment_access.MountSegment(segment2, client_id), ErrorCode::OK);
+    // RealClient may split one allocation into several segments, all named
+    // after the same client hostname.
+    ASSERT_EQ(
+        segment_access.MountSegment(segment2, client_id, client_liveness_),
+        ErrorCode::OK);
 
-    // Verify both segments are mounted correctly
-    std::vector<Segment> segments = {segment, segment2};
-    std::vector<UUID> client_ids = {client_id, client_id};
-    ValidateMountedSegments(segment_manager, segments, client_ids);
+    ValidateMountedSegments(segment_manager, {segment, segment2},
+                            {client_id, client_id});
 }
 
 // UnmountSegmentSuccess:
@@ -228,7 +587,8 @@ TEST_F(SegmentTest, UnmountSegmentSuccess) {
 
     // Get segment access and mount
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
 
     // Verify segment is mounted correctly
     ValidateMountedSegment(segment_manager, segment, client_id);
@@ -271,7 +631,8 @@ TEST_F(SegmentTest, UnmountSegmentDuplicate) {
 
     // Get segment access and mount
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
 
     // Verify initial mounted state
     ValidateMountedSegment(segment_manager, segment, client_id);
@@ -314,7 +675,8 @@ TEST_F(SegmentTest, SegmentLifecycleStatusControlsAllocation) {
     UUID client_id = generate_uuid();
 
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
 
     SegmentStatus status = SegmentStatus::UNDEFINED;
     ASSERT_EQ(segment_access.GetSegmentStatusByName(segment.name, status),
@@ -351,6 +713,62 @@ TEST_F(SegmentTest, SegmentLifecycleStatusControlsAllocation) {
     EXPECT_TRUE(HasAllocatorForSegment(segment_manager, segment.id));
 }
 
+TEST_F(SegmentTest,
+       GracefulUnmountStopsDetachedAllocationButKeepsExistingBuffers) {
+    SegmentManager segment_manager;
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "graceful_snapshot_segment";
+    segment.base = DEFAULT_CXL_BASE;
+    segment.size = 64 * 1024 * 1024;
+    segment.te_endpoint = "graceful_snapshot_endpoint";
+    const UUID client_id = generate_uuid();
+
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
+    }
+
+    AllocatorManager snapshot;
+    {
+        auto allocator_access = segment_manager.getAllocatorAccess();
+        snapshot = allocator_access.SnapshotAllocatorManager();
+    }
+    auto registrations = snapshot.getAllocators(segment.name);
+    ASSERT_NE(registrations, nullptr);
+    ASSERT_EQ(registrations->size(), 1u);
+    auto existing_buffer = registrations->front()->Allocate(1024);
+    ASSERT_NE(existing_buffer, nullptr);
+    EXPECT_TRUE(existing_buffer->isAvailable());
+
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(segment_access.PrepareGracefulUnmountSegment(segment.id),
+                  ErrorCode::OK);
+    }
+
+    RandomAllocationStrategy strategy;
+    auto allocation = strategy.AllocateFrom(snapshot, 1024, segment.name);
+    ASSERT_FALSE(allocation.has_value());
+    EXPECT_EQ(allocation.error(), ErrorCode::NO_AVAILABLE_HANDLE);
+    EXPECT_TRUE(existing_buffer->isAvailable());
+
+    size_t metrics_dec_capacity = 0;
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment.id,
+                                                       metrics_dec_capacity),
+                  ErrorCode::OK);
+        EXPECT_FALSE(existing_buffer->isAvailable());
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment.id, client_id,
+                                                      metrics_dec_capacity),
+                  ErrorCode::OK);
+    }
+    EXPECT_FALSE(existing_buffer->isAvailable());
+}
+
 TEST_F(SegmentTest, HostOrderedSegmentsTracksMountStatusAndUnmount) {
     SegmentManager segment_manager;
 
@@ -372,10 +790,12 @@ TEST_F(SegmentTest, HostOrderedSegmentsTracksMountStatusAndUnmount) {
 
     {
         auto segment_access = segment_manager.getSegmentAccess();
-        ASSERT_EQ(segment_access.MountSegment(segment0, client_id),
-                  ErrorCode::OK);
-        ASSERT_EQ(segment_access.MountSegment(segment1, client_id),
-                  ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment0, client_id, client_liveness_),
+            ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment1, client_id, client_liveness_),
+            ErrorCode::OK);
     }
 
     {
@@ -424,7 +844,61 @@ TEST_F(SegmentTest, HostOrderedSegmentsTracksMountStatusAndUnmount) {
     }
 }
 
-TEST_F(SegmentTest, HostOrderedSegmentsKeepsNameUntilLastSameNameSegmentGone) {
+TEST_F(SegmentTest, DetachedAllocationDoesNotBlockLivenessTransition) {
+    SegmentManager segment_manager(BufferAllocatorType::OFFSET);
+    Segment segment;
+    segment.id = generate_uuid();
+    segment.name = "allocation_liveness_transition_segment";
+    segment.base = DEFAULT_CXL_BASE;
+    segment.size = 64 * 1024 * 1024;
+    segment.te_endpoint = "allocation_liveness_transition_endpoint";
+    const UUID client_id = generate_uuid();
+
+    auto blocking = std::make_shared<BlockingAllocateOffsetBufferAllocator>(
+        segment.name, segment.base, segment.size, segment.te_endpoint);
+    AllocatorManager snapshot;
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
+        auto original = segment_access.GetAllocator(segment.id);
+        ASSERT_TRUE(segment_access.ReplaceAllocators(
+            {{segment.id, original, blocking}}));
+    }
+    {
+        auto allocator_access = segment_manager.getAllocatorAccess();
+        snapshot = allocator_access.SnapshotAllocatorManager();
+    }
+    const auto* registrations = snapshot.getAllocators(segment.name);
+    ASSERT_NE(registrations, nullptr);
+    ASSERT_EQ(registrations->size(), 1u);
+
+    auto allocation = std::async(std::launch::async, [&] {
+        return registrations->front()->Allocate(1024);
+    });
+    const bool allocation_entered =
+        blocking->entered_.try_acquire_for(std::chrono::seconds(5));
+    if (!allocation_entered) {
+        blocking->resume_.release();
+    }
+    ASSERT_TRUE(allocation_entered);
+    auto transition = std::async(std::launch::async, [&] {
+        return client_liveness_->Evaluate(ClientLivenessRecord::Clock::now(),
+                                          std::chrono::seconds::zero(),
+                                          std::chrono::hours(1));
+    });
+    const bool transitioned_during_allocation =
+        transition.wait_for(std::chrono::seconds(1)) ==
+        std::future_status::ready;
+    blocking->resume_.release();
+
+    EXPECT_EQ(transition.get(), ClientLivenessTransition::BECAME_SUSPECTED);
+    EXPECT_TRUE(transitioned_during_allocation);
+    EXPECT_EQ(allocation.get(), nullptr);
+}
+
+TEST_F(SegmentTest, SharedNameIndexesSurviveReverseUnmountOrder) {
     SegmentManager segment_manager;
 
     Segment segment0;
@@ -444,10 +918,38 @@ TEST_F(SegmentTest, HostOrderedSegmentsKeepsNameUntilLastSameNameSegmentGone) {
     UUID client_id = generate_uuid();
     {
         auto segment_access = segment_manager.getSegmentAccess();
-        ASSERT_EQ(segment_access.MountSegment(segment0, client_id),
+        ASSERT_EQ(
+            segment_access.MountSegment(segment0, client_id, client_liveness_),
+            ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment1, client_id, client_liveness_),
+            ErrorCode::OK);
+    }
+
+    {
+        auto allocator_access = segment_manager.getAllocatorAccess();
+        auto ordered =
+            allocator_access.GetHostOrderedSegments("host1", "test_key");
+        ASSERT_EQ(ordered.size(), 1u);
+        EXPECT_EQ(ordered[0], segment0.name);
+    }
+
+    {
+        auto segment_access = segment_manager.getSegmentAccess();
+        size_t metrics_dec_capacity = 0;
+        ASSERT_EQ(segment_access.PrepareUnmountSegment(segment1.id,
+                                                       metrics_dec_capacity),
                   ErrorCode::OK);
-        ASSERT_EQ(segment_access.MountSegment(segment1, client_id),
+        ASSERT_EQ(segment_access.CommitUnmountSegment(segment1.id, client_id,
+                                                      metrics_dec_capacity),
                   ErrorCode::OK);
+        EXPECT_TRUE(segment_access.ExistsSegmentName(segment0.name));
+        EXPECT_TRUE(segment_access.IsSegmentAllocatable(segment0.name));
+        UUID indexed_owner;
+        ASSERT_EQ(segment_access.GetClientIdBySegmentName(segment0.name,
+                                                          indexed_owner),
+                  ErrorCode::OK);
+        EXPECT_EQ(indexed_owner, client_id);
     }
 
     {
@@ -467,15 +969,67 @@ TEST_F(SegmentTest, HostOrderedSegmentsKeepsNameUntilLastSameNameSegmentGone) {
         ASSERT_EQ(segment_access.CommitUnmountSegment(segment0.id, client_id,
                                                       metrics_dec_capacity),
                   ErrorCode::OK);
+        EXPECT_FALSE(segment_access.ExistsSegmentName(segment0.name));
     }
 
     {
         auto allocator_access = segment_manager.getAllocatorAccess();
         auto ordered =
             allocator_access.GetHostOrderedSegments("host1", "test_key");
-        ASSERT_EQ(ordered.size(), 1u);
-        EXPECT_EQ(ordered[0], segment1.name);
+        EXPECT_TRUE(ordered.empty());
+    }
+}
+
+TEST_F(SegmentTest, SharedNameRegistrationsSurviveSegmentSnapshotRestore) {
+    SegmentManager source(BufferAllocatorType::OFFSET);
+    Segment first;
+    first.id = generate_uuid();
+    first.name = "snapshot-shared-hostname";
+    first.base = DEFAULT_CXL_BASE;
+    first.size = 64 * 1024 * 1024;
+    first.te_endpoint = "snapshot-first-endpoint";
+    Segment second = first;
+    second.id = generate_uuid();
+    second.base += first.size;
+    second.te_endpoint = "snapshot-second-endpoint";
+    const UUID first_owner = generate_uuid();
+    const UUID second_owner = generate_uuid();
+
+    {
+        auto segment_access = source.getSegmentAccess();
+        ASSERT_EQ(
+            segment_access.MountSegment(first, first_owner, client_liveness_),
+            ErrorCode::OK);
+        ASSERT_EQ(segment_access.MountSegment(
+                      second, second_owner,
+                      std::make_shared<ClientLivenessRecord>(
+                          ClientLivenessRecord::Clock::now())),
+                  ErrorCode::OK);
+    }
+    auto serialized =
+        SegmentSerializer(&source).Serialize(LocalSsdPersistedState{});
+    ASSERT_TRUE(serialized.has_value());
+
+    SegmentManager restored(BufferAllocatorType::OFFSET);
+    auto restored_state = SegmentSerializer(&restored).Deserialize(*serialized);
+    ASSERT_TRUE(restored_state.has_value());
+    {
+        auto allocator_access = restored.getAllocatorAccess();
+        const auto* registrations =
+            allocator_access.getAllocatorManager().getAllocators(first.name);
+        ASSERT_NE(registrations, nullptr);
+        EXPECT_EQ(registrations->size(), 2u);
     }
+
+    std::vector<std::pair<Segment, UUID>> segments;
+    ASSERT_EQ(restored.getSegmentAccess().GetAllSegments(segments),
+              ErrorCode::OK);
+    std::unordered_map<UUID, UUID, boost::hash<UUID>> owners;
+    for (const auto& [segment, owner] : segments) {
+        owners.emplace(segment.id, owner);
+    }
+    EXPECT_EQ(owners.at(first.id), first_owner);
+    EXPECT_EQ(owners.at(second.id), second_owner);
 }
 
 TEST_F(SegmentTest, HostOrderedSegmentsRotateWithinSameHostByKey) {
@@ -498,10 +1052,12 @@ TEST_F(SegmentTest, HostOrderedSegmentsRotateWithinSameHostByKey) {
     UUID client_id = generate_uuid();
     {
         auto segment_access = segment_manager.getSegmentAccess();
-        ASSERT_EQ(segment_access.MountSegment(segment_a, client_id),
-                  ErrorCode::OK);
-        ASSERT_EQ(segment_access.MountSegment(segment_b, client_id),
-                  ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment_a, client_id, client_liveness_),
+            ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment_b, client_id, client_liveness_),
+            ErrorCode::OK);
     }
 
     const std::string key = "stable_rotation_key";
@@ -529,7 +1085,8 @@ TEST_F(SegmentTest, PrepareUnmountDrainedSegment) {
     UUID client_id = generate_uuid();
 
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment, client_id), ErrorCode::OK);
+    ASSERT_EQ(segment_access.MountSegment(segment, client_id, client_liveness_),
+              ErrorCode::OK);
     ASSERT_EQ(segment_access.SetSegmentStatusByName(segment.name,
                                                     SegmentStatus::DRAINED),
               ErrorCode::OK);
@@ -567,7 +1124,9 @@ TEST_F(SegmentTest, ReMountSegmentSuccess) {
 
     // Get segment access and mount segment A
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment_a, client_id), ErrorCode::OK);
+    ASSERT_EQ(
+        segment_access.MountSegment(segment_a, client_id, client_liveness_),
+        ErrorCode::OK);
 
     // Verify segment A is mounted correctly
     ValidateMountedSegment(segment_manager, segment_a, client_id);
@@ -581,7 +1140,8 @@ TEST_F(SegmentTest, ReMountSegmentSuccess) {
 
     // Remount both segments A and B
     std::vector<Segment> segments_to_remount = {segment_a, segment_b};
-    ASSERT_EQ(segment_access.ReMountSegment(segments_to_remount, client_id),
+    ASSERT_EQ(segment_access.ReMountSegment(segments_to_remount, client_id,
+                                            client_liveness_),
               ErrorCode::OK);
 
     // Verify both segments are mounted correctly
@@ -611,7 +1171,9 @@ TEST_F(SegmentTest, ReMountUnmountingSegment) {
 
     // Get segment access and mount segment A
     auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountSegment(segment_a, client_id), ErrorCode::OK);
+    ASSERT_EQ(
+        segment_access.MountSegment(segment_a, client_id, client_liveness_),
+        ErrorCode::OK);
 
     // Verify segment A is mounted correctly
     ValidateMountedSegment(segment_manager, segment_a, client_id);
@@ -624,7 +1186,8 @@ TEST_F(SegmentTest, ReMountUnmountingSegment) {
 
     // Attempt to remount segment A while it's in UNMOUNTING state
     std::vector<Segment> segments_to_remount = {segment_a};
-    ASSERT_EQ(segment_access.ReMountSegment(segments_to_remount, client_id),
+    ASSERT_EQ(segment_access.ReMountSegment(segments_to_remount, client_id,
+                                            client_liveness_),
               ErrorCode::UNAVAILABLE_IN_CURRENT_STATUS);
 
     // Complete the unmount process
@@ -667,8 +1230,9 @@ TEST_F(SegmentTest, QuerySegments) {
         UUID client_id = generate_uuid();
 
         // Mount segment
-        ASSERT_EQ(segment_access.MountSegment(segment, client_id),
-                  ErrorCode::OK);
+        ASSERT_EQ(
+            segment_access.MountSegment(segment, client_id, client_liveness_),
+            ErrorCode::OK);
 
         // Store for verification
         segments.push_back(segment);
@@ -730,62 +1294,4 @@ TEST_F(SegmentTest, QuerySegments) {
     ASSERT_EQ(capacity, 0);
 }
 
-// Mount Local Disk Segment Operations Tests:
-TEST_F(SegmentTest, MountLocalDiskSegmentSuccess) {
-    SegmentManager segment_manager;
-    // Create a valid local disk segment and client ID
-    auto segment = std::make_shared<LocalDiskSegment>(true);
-    UUID client_id = generate_uuid();
-
-    // Get segment access and attempt to mount
-    auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountLocalDiskSegment(client_id, true),
-              ErrorCode::OK);
-
-    // Verify segment is properly mounted
-    ValidateMountedLocalDiskSegments(segment_manager, segment, client_id);
-}
-
-// MountLocalDiskSegmentDuplicate Tests:
-// 1. MountLocalDiskSegment with the same segment id. The second mount operation
-// return SEGMENT_ALREADY_EXISTS.
-// 2. MountLocalDiskSegment with different segment id and the same segment name
-// should be considered as different segments. Validate the status of
-// SegmentManager use ValidateMountedLocalDiskSegments function.
-TEST_F(SegmentTest, MountLocalDiskSegmentDuplicate) {
-    SegmentManager segment_manager;
-    // Create a valid segment and client ID
-    auto segment = std::make_shared<LocalDiskSegment>(true);
-    UUID client_id = generate_uuid();
-
-    // Get segment access and mount first time
-    auto segment_access = segment_manager.getSegmentAccess();
-    ASSERT_EQ(segment_access.MountLocalDiskSegment(client_id, true),
-              ErrorCode::OK);
-
-    // Verify first mount
-    ValidateMountedLocalDiskSegments(segment_manager, segment, client_id);
-
-    // Test duplicate mount - mount the same segment again
-    ASSERT_EQ(segment_access.MountLocalDiskSegment(client_id, true),
-              ErrorCode::SEGMENT_ALREADY_EXISTS);
-
-    // Verify state remains the same after duplicate mount
-    ValidateMountedLocalDiskSegments(segment_manager, segment, client_id);
-
-    // Create a new segment with same name but different ID
-    auto segment2 = std::make_shared<LocalDiskSegment>(true);
-    UUID client_id2 = generate_uuid();
-
-    // Mount the second segment
-    ASSERT_EQ(segment_access.MountLocalDiskSegment(client_id2, true),
-              ErrorCode::OK);
-
-    // Verify both segments are mounted correctly
-    std::vector<std::shared_ptr<LocalDiskSegment>> segments = {segment,
-                                                               segment2};
-    std::vector<UUID> client_ids = {client_id, client_id2};
-    ValidateMountedLocalDiskSegments(segment_manager, segments, client_ids);
-}
-
 }  // namespace mooncake
diff --git a/mooncake-store/tests/spdk_controller_config_test.cpp b/mooncake-store/tests/spdk_controller_config_test.cpp
new file mode 100644
index 0000000000..903ac826d3
--- /dev/null
+++ b/mooncake-store/tests/spdk_controller_config_test.cpp
@@ -0,0 +1,166 @@
+#include "../src/config/spdk_controller_config.h"
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+
+namespace mooncake::test {
+namespace {
+
+class SpdkControllerConfigTest : public ::testing::Test {
+   protected:
+    static void SetUpTestSuite() {
+        google::InitGoogleLogging("SpdkControllerConfigTest");
+    }
+
+    static void TearDownTestSuite() { google::ShutdownGoogleLogging(); }
+
+    void SetUp() override {
+        original_logtostderr_ = FLAGS_logtostderr;
+        FLAGS_logtostderr = true;
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (const char* value = std::getenv(kVariables[i])) {
+                original_[i] = value;
+            }
+            ASSERT_EQ(unsetenv(kVariables[i]), 0);
+        }
+    }
+
+    void TearDown() override {
+        for (size_t i = 0; i < kVariables.size(); ++i) {
+            if (original_[i].has_value()) {
+                EXPECT_EQ(setenv(kVariables[i], original_[i]->c_str(), 1), 0);
+            } else {
+                EXPECT_EQ(unsetenv(kVariables[i]), 0);
+            }
+        }
+        FLAGS_logtostderr = original_logtostderr_;
+    }
+
+    inline static constexpr std::array<const char*, 8> kVariables = {
+        "MC_NVME_NUM_IO_QUEUES",     "MC_NVME_IO_QUEUE_SIZE",
+        "MC_NVME_IO_QUEUE_REQUESTS", "MC_NVME_TRANSPORT_ACK_TIMEOUT",
+        "MC_NVME_ADMIN_QUEUE_SIZE",  "MC_NVME_FABRICS_CONNECT_TIMEOUT_US",
+        "MC_NVME_HEADER_DIGEST",     "MC_NVME_DATA_DIGEST",
+    };
+    std::array<std::optional<std::string>, kVariables.size()> original_;
+    bool original_logtostderr_ = false;
+};
+
+TEST_F(SpdkControllerConfigTest, UnsetAndEmptyValuesLeaveOverridesAbsent) {
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_HEADER_DIGEST", "", 1), 0);
+
+    testing::internal::CaptureStderr();
+    const auto config = SpdkControllerConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.num_io_queues.has_value());
+    EXPECT_FALSE(config.io_queue_size.has_value());
+    EXPECT_FALSE(config.io_queue_requests.has_value());
+    EXPECT_FALSE(config.transport_ack_timeout.has_value());
+    EXPECT_FALSE(config.admin_queue_size.has_value());
+    EXPECT_FALSE(config.fabrics_connect_timeout_us.has_value());
+    EXPECT_FALSE(config.header_digest.has_value());
+    EXPECT_FALSE(config.data_digest.has_value());
+    EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+}
+
+TEST_F(SpdkControllerConfigTest, ReadsIndependentValidOverrides) {
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "11", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_SIZE", "22", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_REQUESTS", "33", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_TRANSPORT_ACK_TIMEOUT", "44", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_ADMIN_QUEUE_SIZE", "55", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_FABRICS_CONNECT_TIMEOUT_US", "66", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_HEADER_DIGEST", "false", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_DATA_DIGEST", "TRUE", 1), 0);
+
+    const auto config = SpdkControllerConfig::FromEnvironment();
+
+    EXPECT_EQ(config.num_io_queues, 11u);
+    EXPECT_EQ(config.io_queue_size, 22u);
+    EXPECT_EQ(config.io_queue_requests, 33u);
+    EXPECT_EQ(config.transport_ack_timeout, 44u);
+    EXPECT_EQ(config.admin_queue_size, 55u);
+    EXPECT_EQ(config.fabrics_connect_timeout_us, 66u);
+    EXPECT_EQ(config.header_digest, false);
+    EXPECT_EQ(config.data_digest, true);
+}
+
+TEST_F(SpdkControllerConfigTest, UsesTypedIntegerAndBooleanSyntax) {
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "  +42 ", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_SIZE", "010", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_REQUESTS", "4294967295", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_TRANSPORT_ACK_TIMEOUT", "255", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_ADMIN_QUEUE_SIZE", "65535", 1), 0);
+    ASSERT_EQ(
+        setenv("MC_NVME_FABRICS_CONNECT_TIMEOUT_US", "18446744073709551615", 1),
+        0);
+    ASSERT_EQ(setenv("MC_NVME_HEADER_DIGEST", "OFF", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_DATA_DIGEST", "enable", 1), 0);
+
+    const auto config = SpdkControllerConfig::FromEnvironment();
+
+    EXPECT_EQ(config.num_io_queues, 42u);
+    EXPECT_EQ(config.io_queue_size, 10u);
+    EXPECT_EQ(config.io_queue_requests, std::numeric_limits<uint32_t>::max());
+    EXPECT_EQ(config.transport_ack_timeout,
+              std::numeric_limits<uint8_t>::max());
+    EXPECT_EQ(config.admin_queue_size, std::numeric_limits<uint16_t>::max());
+    EXPECT_EQ(config.fabrics_connect_timeout_us,
+              std::numeric_limits<uint64_t>::max());
+    EXPECT_EQ(config.header_digest, false);
+    EXPECT_EQ(config.data_digest, true);
+}
+
+TEST_F(SpdkControllerConfigTest,
+       RejectsNegativeOutOfRangeAndNonCanonicalValues) {
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "4294967296", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_SIZE", "-1", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_IO_QUEUE_REQUESTS", "0x10", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_TRANSPORT_ACK_TIMEOUT", "256", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_ADMIN_QUEUE_SIZE", "65536", 1), 0);
+    ASSERT_EQ(
+        setenv("MC_NVME_FABRICS_CONNECT_TIMEOUT_US", "18446744073709551616", 1),
+        0);
+    ASSERT_EQ(setenv("MC_NVME_HEADER_DIGEST", "-0", 1), 0);
+    ASSERT_EQ(setenv("MC_NVME_DATA_DIGEST", "2", 1), 0);
+
+    testing::internal::CaptureStderr();
+    const auto config = SpdkControllerConfig::FromEnvironment();
+    const auto diagnostics = testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.num_io_queues.has_value());
+    EXPECT_FALSE(config.io_queue_size.has_value());
+    EXPECT_FALSE(config.io_queue_requests.has_value());
+    EXPECT_FALSE(config.transport_ack_timeout.has_value());
+    EXPECT_FALSE(config.admin_queue_size.has_value());
+    EXPECT_FALSE(config.fabrics_connect_timeout_us.has_value());
+    EXPECT_FALSE(config.header_digest.has_value());
+    EXPECT_FALSE(config.data_digest.has_value());
+
+    EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+}
+
+TEST_F(SpdkControllerConfigTest, EachConstructionReadsCurrentEnvironment) {
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "1", 1), 0);
+    const auto first = SpdkControllerConfig::FromEnvironment();
+    ASSERT_EQ(setenv("MC_NVME_NUM_IO_QUEUES", "2", 1), 0);
+    const auto second = SpdkControllerConfig::FromEnvironment();
+    ASSERT_EQ(unsetenv("MC_NVME_NUM_IO_QUEUES"), 0);
+    const auto third = SpdkControllerConfig::FromEnvironment();
+
+    EXPECT_EQ(first.num_io_queues, 1u);
+    EXPECT_EQ(second.num_io_queues, 2u);
+    EXPECT_FALSE(third.num_io_queues.has_value());
+}
+
+}  // namespace
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/ssd_metrics_test.cpp b/mooncake-store/tests/ssd_metrics_test.cpp
index 610e3f126d..5682798e50 100644
--- a/mooncake-store/tests/ssd_metrics_test.cpp
+++ b/mooncake-store/tests/ssd_metrics_test.cpp
@@ -2,8 +2,8 @@
 #include <gtest/gtest.h>
 
 #include <chrono>
+#include <map>
 #include <thread>
-#include <vector>
 
 #include "client_metric.h"
 
@@ -19,165 +19,6 @@ class SsdMetricsTest : public ::testing::Test {
     void TearDown() override { google::ShutdownGoogleLogging(); }
 };
 
-TEST_F(SsdMetricsTest, InitialValuesTest) {
-    SsdMetric metrics;
-
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 0);
-    ASSERT_EQ(metrics.ssd_write_bytes.value(), 0);
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_write_ops.value(), 0);
-
-    // Histogram bucket counts should all be 0
-    auto read_buckets = metrics.ssd_read_latency_us.get_bucket_counts();
-    for (auto& bucket : read_buckets) {
-        ASSERT_EQ(bucket->value(), 0);
-    }
-    auto write_buckets = metrics.ssd_write_latency_us.get_bucket_counts();
-    for (auto& bucket : write_buckets) {
-        ASSERT_EQ(bucket->value(), 0);
-    }
-
-    // Total metrics
-    ASSERT_EQ(metrics.ssd_total_bytes.value(), 0);
-    ASSERT_EQ(metrics.ssd_total_ops.value(), 0);
-}
-
-TEST_F(SsdMetricsTest, ReadMetricsTest) {
-    SsdMetric metrics;
-
-    // Simulate a successful BatchLoad of 3 keys totaling 1MB
-    metrics.ssd_read_ops.inc(3);
-    metrics.ssd_read_bytes.inc(1024 * 1024);
-    metrics.ssd_read_latency_us.observe(1500);  // 1.5ms
-
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 3);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 1024 * 1024);
-
-    // Simulate another BatchLoad of 5 keys totaling 2MB
-    metrics.ssd_read_ops.inc(5);
-    metrics.ssd_read_bytes.inc(2 * 1024 * 1024);
-    metrics.ssd_read_latency_us.observe(3000);  // 3ms
-
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 8);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 3 * 1024 * 1024);
-
-    // Write metrics should remain 0
-    ASSERT_EQ(metrics.ssd_write_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_write_bytes.value(), 0);
-}
-
-TEST_F(SsdMetricsTest, WriteMetricsTest) {
-    SsdMetric metrics;
-
-    // Simulate a successful BatchOffload of 10 keys totaling 5MB
-    metrics.ssd_write_ops.inc(10);
-    metrics.ssd_write_bytes.inc(5 * 1024 * 1024);
-    metrics.ssd_write_latency_us.observe(50000);  // 50ms
-
-    ASSERT_EQ(metrics.ssd_write_ops.value(), 10);
-    ASSERT_EQ(metrics.ssd_write_bytes.value(), 5 * 1024 * 1024);
-
-    // Read metrics should remain 0
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 0);
-}
-
-TEST_F(SsdMetricsTest, TotalMetricsTest) {
-    SsdMetric metrics;
-
-    // Simulate read: 3 keys, 1MB
-    metrics.ssd_read_ops.inc(3);
-    metrics.ssd_read_bytes.inc(1024 * 1024);
-    metrics.ssd_read_latency_us.observe(1500);
-    metrics.ssd_read_latency_summary.observe(1500);
-    metrics.ssd_total_ops.inc(3);
-    metrics.ssd_total_bytes.inc(1024 * 1024);
-    metrics.ssd_total_latency_us.observe(1500);
-    metrics.ssd_total_latency_summary.observe(1500);
-
-    // Simulate write: 5 keys, 2MB
-    metrics.ssd_write_ops.inc(5);
-    metrics.ssd_write_bytes.inc(2 * 1024 * 1024);
-    metrics.ssd_write_latency_us.observe(3000);
-    metrics.ssd_write_latency_summary.observe(3000);
-    metrics.ssd_total_ops.inc(5);
-    metrics.ssd_total_bytes.inc(2 * 1024 * 1024);
-    metrics.ssd_total_latency_us.observe(3000);
-    metrics.ssd_total_latency_summary.observe(3000);
-
-    // Verify totals = read + write
-    ASSERT_EQ(metrics.ssd_total_ops.value(), 3 + 5);
-    ASSERT_EQ(metrics.ssd_total_bytes.value(), 1024 * 1024 + 2 * 1024 * 1024);
-
-    // Total latency histogram should have 2 observations
-    auto buckets = metrics.ssd_total_latency_us.get_bucket_counts();
-    int64_t total_count = 0;
-    for (auto& b : buckets) total_count += b->value();
-    ASSERT_EQ(total_count, 2);
-
-    // Verify summary shows Total line
-    std::string summary = metrics.summary_metrics();
-    EXPECT_TRUE(summary.find("SSD Total:") != std::string::npos);
-    EXPECT_TRUE(summary.find("Total:") != std::string::npos);
-
-    std::cout << "Total Metrics Summary:\n" << summary << std::endl;
-}
-
-TEST_F(SsdMetricsTest, FailureNotCountedTest) {
-    SsdMetric metrics;
-
-    // Simulate: nothing recorded (as if BatchLoad failed and we skipped
-    // metrics) All metrics should remain 0
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 0);
-    ASSERT_EQ(metrics.ssd_write_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_write_bytes.value(), 0);
-
-    // Now simulate a success after a failure
-    metrics.ssd_read_ops.inc(1);
-    metrics.ssd_read_bytes.inc(4096);
-    metrics.ssd_read_latency_us.observe(100);
-
-    // Only the successful operation should be counted
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 1);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 4096);
-}
-
-TEST_F(SsdMetricsTest, ConcurrentTest) {
-    SsdMetric metrics;
-
-    const int num_threads = 8;
-    const int ops_per_thread = 1000;
-
-    std::vector<std::thread> threads;
-    for (int i = 0; i < num_threads; ++i) {
-        threads.emplace_back([&metrics, ops_per_thread]() {
-            for (int j = 0; j < ops_per_thread; ++j) {
-                metrics.ssd_read_ops.inc(1);
-                metrics.ssd_read_bytes.inc(4096);
-                metrics.ssd_read_latency_us.observe(500);
-                metrics.ssd_write_ops.inc(1);
-                metrics.ssd_write_bytes.inc(8192);
-                metrics.ssd_write_latency_us.observe(1000);
-                metrics.ssd_total_ops.inc(2);
-                metrics.ssd_total_bytes.inc(4096 + 8192);
-            }
-        });
-    }
-
-    for (auto& t : threads) {
-        t.join();
-    }
-
-    int64_t expected_ops = num_threads * ops_per_thread;
-    ASSERT_EQ(metrics.ssd_read_ops.value(), expected_ops);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), expected_ops * 4096);
-    ASSERT_EQ(metrics.ssd_write_ops.value(), expected_ops);
-    ASSERT_EQ(metrics.ssd_write_bytes.value(), expected_ops * 8192);
-    ASSERT_EQ(metrics.ssd_total_ops.value(), expected_ops * 2);
-    ASSERT_EQ(metrics.ssd_total_bytes.value(), expected_ops * (4096 + 8192));
-}
-
 TEST_F(SsdMetricsTest, SerializeTest) {
     SsdMetric metrics;
 
@@ -411,26 +252,4 @@ TEST_F(SsdMetricsTest, LatencyBucketBoundaryTest) {
               << serialized << std::endl;
 }
 
-TEST_F(SsdMetricsTest, EmptyBatchMetricsTest) {
-    SsdMetric metrics;
-
-    // Simulate recording metrics for an empty batch (0 keys, 0 bytes)
-    // This mirrors what happens if FileStorage::BatchLoad is called with
-    // an empty map and succeeds - the instrumentation code would compute
-    // total_bytes=0 and batch_object.size()=0
-    metrics.ssd_read_ops.inc(0);
-    metrics.ssd_read_bytes.inc(0);
-    metrics.ssd_read_latency_us.observe(10);  // Still takes some time
-
-    // Counters should remain 0 (inc(0) is a no-op for counters)
-    ASSERT_EQ(metrics.ssd_read_ops.value(), 0);
-    ASSERT_EQ(metrics.ssd_read_bytes.value(), 0);
-
-    // But latency histogram should record the observation
-    auto buckets = metrics.ssd_read_latency_us.get_bucket_counts();
-    int64_t total = 0;
-    for (auto& b : buckets) total += b->value();
-    EXPECT_EQ(total, 1);
-}
-
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/storage_backend_test.cpp b/mooncake-store/tests/storage_backend_test.cpp
index 1f3e1ae246..8795c63630 100644
--- a/mooncake-store/tests/storage_backend_test.cpp
+++ b/mooncake-store/tests/storage_backend_test.cpp
@@ -3,22 +3,32 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <cerrno>
+#include <chrono>
 #include <filesystem>
 #include <fstream>
+#include <future>
 #include <iostream>
 #include <limits>
+#include <optional>
 #include <ranges>
+#include <string>
+#include <string_view>
 #include <thread>
 #include <atomic>
 #include <algorithm>
 #include <cstring>
+#include <cstdlib>
 #include <mutex>
 #include <fcntl.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
 #include <unistd.h>
 #include <ylt/util/tl/expected.hpp>
 
 #include "allocator.h"
-#include "utils.h"
+#include "common/timestamp.h"
+#include "common/file_util.h"
 #include "utils/common.h"
 
 namespace fs = std::filesystem;
@@ -108,7 +118,9 @@ class StorageBackendTest : public ::testing::Test {
     void SetUp() override {
         google::InitGoogleLogging("StorageBackendTest");
         FLAGS_logtostderr = true;
-        data_path = std::filesystem::current_path().string() + "/data";
+        data_path =
+            (std::filesystem::current_path() / "storage_backend_test_data")
+                .string();
         // Remove all leftover files and subdirectories from previous runs
         if (fs::exists(data_path)) {
             for (const auto& entry : fs::directory_iterator(data_path)) {
@@ -189,6 +201,123 @@ TEST_F(StorageBackendTest, CreateAcceptsValidConfig) {
     EXPECT_NE(result.value(), nullptr);
 }
 
+TEST_F(StorageBackendTest, RemoveFileWaitsForStoreInWriteCriticalSection) {
+    StorageBackend backend(data_path, "unused", false);
+    ASSERT_TRUE(backend.Init(0));
+
+    const std::string path = data_path + "/concurrent_remove_fifo";
+    std::error_code cleanup_ec;
+    fs::remove(path, cleanup_ec);
+    ASSERT_FALSE(cleanup_ec);
+    ASSERT_EQ(mkfifo(path.c_str(), 0600), 0) << strerror(errno);
+
+    const int reader_fd = open(path.c_str(), O_RDONLY | O_NONBLOCK);
+    if (reader_fd < 0) {
+        fs::remove(path);
+        FAIL() << "Failed to open FIFO reader: " << strerror(errno);
+    }
+    const int pipe_capacity = fcntl(reader_fd, F_GETPIPE_SZ);
+    if (pipe_capacity <= 0) {
+        close(reader_fd);
+        fs::remove(path);
+        FAIL() << "Failed to query FIFO capacity: " << strerror(errno);
+    }
+
+    // With no reader draining the FIFO, this write fills the pipe and blocks
+    // after StoreObject has acquired the path mutex.
+    const std::string value(static_cast<size_t>(pipe_capacity) * 2, 'x');
+    std::atomic<bool> store_done{false};
+    auto store_future = std::async(std::launch::async, [&]() {
+        auto result = backend.StoreObject(path, value);
+        store_done.store(true, std::memory_order_release);
+        return result;
+    });
+
+    bool queue_probe_ok = true;
+    bool writer_blocked = false;
+    const auto write_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    while (std::chrono::steady_clock::now() < write_deadline) {
+        int queued_bytes = 0;
+        if (ioctl(reader_fd, FIONREAD, &queued_bytes) != 0) {
+            queue_probe_ok = false;
+            break;
+        }
+        const auto status = store_future.wait_for(std::chrono::milliseconds(0));
+        if (queued_bytes > 0 && status == std::future_status::timeout) {
+            writer_blocked = true;
+            break;
+        }
+        if (status == std::future_status::ready) {
+            break;
+        }
+        std::this_thread::yield();
+    }
+
+    bool remove_blocked = false;
+    std::optional<std::future<void>> remove_future;
+    if (writer_blocked) {
+        std::promise<void> remove_started_promise;
+        auto remove_started = remove_started_promise.get_future();
+        remove_future.emplace(std::async(std::launch::async, [&]() {
+            remove_started_promise.set_value();
+            backend.RemoveFile(path);
+        }));
+        remove_started.wait();
+        remove_blocked =
+            remove_future->wait_for(std::chrono::milliseconds(200)) ==
+            std::future_status::timeout;
+    }
+
+    // Drain the FIFO only after checking that RemoveFile is blocked. This
+    // lets StoreObject finish and release the path mutex.
+    auto drain_future = std::async(std::launch::async, [&]() {
+        std::vector<char> buffer(64 * 1024);
+        size_t drained_bytes = 0;
+        for (;;) {
+            const ssize_t n = read(reader_fd, buffer.data(), buffer.size());
+            if (n > 0) {
+                drained_bytes += static_cast<size_t>(n);
+                continue;
+            }
+            if (n == 0) {
+                if (store_done.load(std::memory_order_acquire)) {
+                    return std::optional<size_t>{drained_bytes};
+                }
+                std::this_thread::yield();
+                continue;
+            }
+            if (errno == EINTR || errno == EAGAIN) {
+                std::this_thread::yield();
+                continue;
+            }
+            return std::optional<size_t>{};
+        }
+    });
+
+    auto store_result = store_future.get();
+    auto drain_result = drain_future.get();
+    if (remove_future.has_value()) {
+        remove_future->get();
+    } else {
+        backend.RemoveFile(path);
+    }
+    close(reader_fd);
+
+    const bool path_exists = fs::exists(path);
+    if (path_exists) {
+        fs::remove(path);
+    }
+
+    EXPECT_TRUE(queue_probe_ok);
+    EXPECT_TRUE(writer_blocked);
+    EXPECT_TRUE(remove_blocked);
+    ASSERT_TRUE(store_result.has_value());
+    ASSERT_TRUE(drain_result.has_value());
+    EXPECT_EQ(drain_result.value(), value.size());
+    EXPECT_FALSE(path_exists);
+}
+
 // Regression tests for StorageBackendAdaptor::Init validation (issue #3134
 // follow-up): obviously invalid configuration must be reported as
 // INVALID_PARAMS, while a missing root directory is still auto-created.
@@ -474,16 +603,6 @@ TEST_F(StorageBackendTest, LargeNumberOfIds_NoOverflowInLifetime) {
 }
 
 TEST_F(StorageBackendTest, OrphanedBucketFileCleanup) {
-    std::string data_path = std::filesystem::current_path().string() + "/data";
-    fs::create_directories(data_path);
-
-    // Clean up any existing files
-    for (const auto& entry : fs::directory_iterator(data_path)) {
-        if (entry.is_regular_file()) {
-            fs::remove(entry.path());
-        }
-    }
-
     FileStorageConfig config;
     config.storage_filepath = data_path;
     BucketBackendConfig bucket_config;
@@ -1363,6 +1482,24 @@ TEST_F(StorageBackendTest, OffsetAllocatorStorageBackend_DoubleInit) {
     EXPECT_EQ(second_init.error(), ErrorCode::INTERNAL_ERROR);
 }
 
+#ifdef USE_URING
+TEST_F(StorageBackendTest,
+       OffsetAllocatorStorageBackend_RejectsUnalignedCapacityWithUring) {
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    config.storage_backend_type = StorageBackendType::kOffsetAllocator;
+    // 50 KiB is not a multiple of the 4 KiB O_DIRECT alignment.
+    config.total_size_limit = 50 * 1024;
+    config.total_keys_limit = 1000;
+    config.use_uring = true;
+
+    OffsetAllocatorStorageBackend storage_backend(config);
+    auto init = storage_backend.Init();
+    ASSERT_FALSE(init.has_value());
+    EXPECT_EQ(init.error(), ErrorCode::INVALID_PARAMS);
+}
+#endif
+
 //-----------------------------------------------------------------------------
 
 TEST_F(StorageBackendTest, OffsetAllocatorStorageBackend_BatchOffloadEmpty) {
@@ -1961,7 +2098,7 @@ TEST_F(StorageBackendTest,
 // BucketStorageBackend: Duplicate Key Detection Tests (Phase 0 - D0)
 //-----------------------------------------------------------------------------
 
-TEST_F(StorageBackendTest, BucketStorageBackend_DuplicateKeyRejected) {
+TEST_F(StorageBackendTest, BucketStorageBackend_DuplicateKeyIdempotentSkip) {
     FileStorageConfig config;
     config.storage_filepath = data_path;
     BucketBackendConfig bucket_config;
@@ -1983,7 +2120,8 @@ TEST_F(StorageBackendTest, BucketStorageBackend_DuplicateKeyRejected) {
            std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
     ASSERT_TRUE(result1.has_value()) << "First write should succeed";
 
-    // Attempt to write the same key again
+    // Re-offload the same key: an idempotent no-op (Put semantics), not an
+    // error. Nothing new is committed, so the complete handler must not fire.
     std::string value2 = "duplicate_value_data";
     auto buf2 = std::make_unique<char[]>(value2.size());
     std::memcpy(buf2.get(), value2.data(), value2.size());
@@ -1991,12 +2129,17 @@ TEST_F(StorageBackendTest, BucketStorageBackend_DuplicateKeyRejected) {
     std::unordered_map<std::string, std::vector<Slice>> batch2;
     batch2.emplace(key, std::vector<Slice>{Slice{buf2.get(), value2.size()}});
 
+    int handler_calls = 0;
     auto result2 = storage_backend.BatchOffload(
-        batch2,
-        [](const std::vector<std::string>&,
-           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
-    ASSERT_FALSE(result2.has_value()) << "Duplicate key should be rejected";
-    EXPECT_EQ(result2.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+        batch2, [&handler_calls](const std::vector<std::string>&,
+                                 std::vector<StorageObjectMetadata>&) {
+            handler_calls++;
+            return ErrorCode::OK;
+        });
+    ASSERT_TRUE(result2.has_value())
+        << "Re-offloading a persisted key should succeed idempotently";
+    EXPECT_EQ(handler_calls, 0)
+        << "Complete handler must not fire for an all-duplicate batch";
 
     // Verify original data is still readable and not corrupted
     auto is_exist = storage_backend.IsExist(key);
@@ -2063,8 +2206,8 @@ TEST_F(StorageBackendTest,
         batch2,
         [](const std::vector<std::string>&,
            std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
-    ASSERT_FALSE(result2.has_value());
-    EXPECT_EQ(result2.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+    ASSERT_TRUE(result2.has_value())
+        << "Duplicate re-offload should succeed as an idempotent no-op";
 
     // Count files after duplicate attempt - orphaned files should be cleaned up
     int file_count_after = 0;
@@ -2091,8 +2234,7 @@ TEST_F(StorageBackendTest,
 
 //-----------------------------------------------------------------------------
 
-TEST_F(StorageBackendTest,
-       BucketStorageBackend_DuplicateBatchPartialRejection) {
+TEST_F(StorageBackendTest, BucketStorageBackend_DuplicateBatchPartialSkip) {
     FileStorageConfig config;
     config.storage_filepath = data_path;
     BucketBackendConfig bucket_config;
@@ -2114,7 +2256,8 @@ TEST_F(StorageBackendTest,
            std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
     ASSERT_TRUE(result1.has_value());
 
-    // Attempt BatchOffload with batch containing ["keyA", "keyB"]
+    // BatchOffload a mix of ["keyA", "keyB"]: the duplicate is skipped, the
+    // new key is still committed.
     std::string keyB = "keyB";
     std::string valueA2 = "duplicate_value_A";
     std::string valueB = "value_for_keyB";
@@ -2129,20 +2272,29 @@ TEST_F(StorageBackendTest,
                    std::vector<Slice>{Slice{bufA2.get(), valueA2.size()}});
     batch2.emplace(keyB, std::vector<Slice>{Slice{bufB.get(), valueB.size()}});
 
+    std::vector<std::string> notified_keys;
     auto result2 = storage_backend.BatchOffload(
-        batch2,
-        [](const std::vector<std::string>&,
-           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
-
-    // Entire batch should be rejected
-    ASSERT_FALSE(result2.has_value());
-    EXPECT_EQ(result2.error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+        batch2, [&notified_keys](const std::vector<std::string>& keys,
+                                 std::vector<StorageObjectMetadata>&) {
+            notified_keys = keys;
+            return ErrorCode::OK;
+        });
+    ASSERT_TRUE(result2.has_value())
+        << "Duplicates should be skipped, not reject the whole batch";
+    ASSERT_EQ(notified_keys.size(), 1u);
+    EXPECT_EQ(notified_keys[0], keyB)
+        << "Only the newly committed key should be handed to the handler";
 
-    // Verify "keyB" was NOT written (batch is atomic)
+    // Verify "keyB" was committed and reads back its own value
     auto is_exist_B = storage_backend.IsExist(keyB);
     ASSERT_TRUE(is_exist_B.has_value());
-    EXPECT_FALSE(is_exist_B.value())
-        << "keyB should not exist - batch should be atomic";
+    EXPECT_TRUE(is_exist_B.value()) << "keyB should be committed";
+
+    auto read_buf_B = std::make_unique<char[]>(valueB.size());
+    std::unordered_map<std::string, Slice> load_B;
+    load_B.emplace(keyB, Slice{read_buf_B.get(), valueB.size()});
+    ASSERT_TRUE(storage_backend.BatchLoad(load_B).has_value());
+    EXPECT_EQ(std::string(read_buf_B.get(), valueB.size()), valueB);
 
     // Verify "keyA" still has original value
     auto read_buf = std::make_unique<char[]>(valueA.size());
@@ -2156,6 +2308,83 @@ TEST_F(StorageBackendTest,
     EXPECT_EQ(loaded, valueA) << "keyA should still have original value";
 }
 
+//-----------------------------------------------------------------------------
+
+TEST_F(StorageBackendTest, BucketEvictionDoesNotReportSkippedDuplicateKeys) {
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    BucketBackendConfig bucket_config;
+    bucket_config.bucket_keys_limit = 10;
+    bucket_config.bucket_size_limit = 8 * 1024;
+    bucket_config.max_total_size = 30 * 1024;
+    bucket_config.eviction_policy = BucketEvictionPolicy::LRU;
+    BucketStorageBackend storage_backend(config, bucket_config);
+    ASSERT_TRUE(storage_backend.Init());
+
+    // keyA is committed to the older bucket first.
+    std::string keyA = "keyA";
+    auto bufA = std::make_unique<char[]>(6 * 1024);
+    std::memset(bufA.get(), 'A', 6 * 1024);
+    std::unordered_map<std::string, std::vector<Slice>> batch1;
+    batch1.emplace(keyA, std::vector<Slice>{Slice{bufA.get(), 6 * 1024}});
+    auto result1 = storage_backend.BatchOffload(
+        batch1,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_TRUE(result1.has_value());
+
+    // Re-offload keyA (skipped as a duplicate) together with keyB. The new
+    // bucket's keys list physically carries keyA, but keyA's index entry
+    // still points at the older bucket.
+    std::string keyB = "keyB";
+    auto bufB = std::make_unique<char[]>(6 * 1024);
+    std::memset(bufB.get(), 'B', 6 * 1024);
+    std::unordered_map<std::string, std::vector<Slice>> batch2;
+    batch2.emplace(keyA, std::vector<Slice>{Slice{bufA.get(), 6 * 1024}});
+    batch2.emplace(keyB, std::vector<Slice>{Slice{bufB.get(), 6 * 1024}});
+    auto result2 = storage_backend.BatchOffload(
+        batch2,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_TRUE(result2.has_value());
+
+    // Read keyA so the older bucket is LRU-hotter than the new one.
+    auto read_buf = std::make_unique<char[]>(6 * 1024);
+    std::unordered_map<std::string, Slice> load;
+    load.emplace(keyA, Slice{read_buf.get(), 6 * 1024});
+    ASSERT_TRUE(storage_backend.BatchLoad(load).has_value());
+
+    // The new (now colder) bucket is evicted. keyA must NOT be reported to
+    // the master: its index entry points at the still-alive older bucket,
+    // and reporting it would drop a live replica record with no self-heal.
+    // The 0.30 watermark keeps the quota crossing under matched accounting:
+    // only committed keys credit total_size_, and 12K+meta clears 9K.
+    std::vector<std::string> notified_keys;
+    auto evict_result = storage_backend.EvictAboveDiskWatermark(
+        /*high_watermark_ratio=*/0.30, /*low_watermark_ratio=*/0.30,
+        [&](const std::vector<std::string>& evicted_keys) {
+            notified_keys.insert(notified_keys.end(), evicted_keys.begin(),
+                                 evicted_keys.end());
+            return tl::expected<void, ErrorCode>{};
+        });
+    ASSERT_TRUE(evict_result.has_value());
+    ASSERT_FALSE(evict_result.value().empty());
+    for (const auto& key : notified_keys) {
+        EXPECT_NE(key, keyA)
+            << "a key skipped as duplicate must not be reported as evicted";
+    }
+    EXPECT_NE(std::find(notified_keys.begin(), notified_keys.end(), keyB),
+              notified_keys.end());
+
+    // keyA still resolves from the older bucket; keyB is gone.
+    auto existA = storage_backend.IsExist(keyA);
+    ASSERT_TRUE(existA.has_value());
+    EXPECT_TRUE(existA.value());
+    auto existB = storage_backend.IsExist(keyB);
+    ASSERT_TRUE(existB.has_value());
+    EXPECT_FALSE(existB.value());
+}
+
 //-----------------------------------------------------------------------------
 // BucketReadGuard RAII Behavior Tests (Phase 1 - D2)
 //-----------------------------------------------------------------------------
@@ -3366,7 +3595,7 @@ TEST_F(StorageBackendTest,
                     .has_value());
 }
 
-TEST_F(StorageBackendTest, BucketPendingWriteRejectsReentrantDuplicate) {
+TEST_F(StorageBackendTest, BucketPendingWriteSkipsReentrantDuplicate) {
     FileStorageConfig config;
     config.storage_filepath = data_path;
 
@@ -3403,10 +3632,12 @@ TEST_F(StorageBackendTest, BucketPendingWriteRejectsReentrantDuplicate) {
             return ErrorCode::OK;
         });
 
+    // By the time the outer handler runs, shared_key is already committed,
+    // so the nested re-offload is an idempotent no-op, not an error.
     ASSERT_TRUE(outer_result.has_value());
     ASSERT_TRUE(nested_result.has_value());
-    ASSERT_FALSE(nested_result->has_value());
-    EXPECT_EQ(nested_result->error(), ErrorCode::OBJECT_ALREADY_EXISTS);
+    ASSERT_TRUE(nested_result->has_value())
+        << "Reentrant re-offload of a committed key should be skipped";
 
     std::vector<char> load_buffer(outer_value.size());
     std::unordered_map<std::string, Slice> load_batch;
@@ -4725,4 +4956,288 @@ TEST_F(StorageBackendTest,
               std::make_optional(value_b));
 }
 
+TEST_F(StorageBackendTest,
+       BucketStorageBackend_OffloadSetsBucketAccessTimestamp) {
+    // Regression test for "update bucket ts after offload": BatchOffload must
+    // stamp the new bucket's last_access_ns_ with the current time when
+    // committing metadata. The timestamp itself is private, so we verify it
+    // through LRU eviction behavior:
+    //   - Bucket A is offloaded and then read, so its timestamp is t1 > 0.
+    //   - Bucket B is offloaded afterwards; with the fix its timestamp is
+    //     t2 > t1, without the fix it stays 0.
+    //   - Offloading bucket C overflows the quota and evicts exactly one
+    //     bucket. The LRU victim must be A (oldest timestamp). If B's
+    //     timestamp were 0, B would be evicted immediately instead.
+    // Additionally, a failing complete_handler must roll back the committed
+    // bucket, including its lru_index_ entry (checked via
+    // GetLruIndexSizeForTest at every stage).
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    BucketBackendConfig bucket_config;
+    bucket_config.eviction_policy = BucketEvictionPolicy::LRU;
+    // Each bucket holds one 64 KB object (plus a small metadata blob); the
+    // quota fits two buckets but not three, so the third offload evicts
+    // exactly one bucket.
+    constexpr size_t kValueSize = 64 * 1024;
+    bucket_config.max_total_size = 150 * 1024;
+    BucketStorageBackend storage_backend(config, bucket_config);
+    ASSERT_TRUE(storage_backend.Init());
+
+    auto offload_one = [&](const std::string& key,
+                           std::vector<std::string>* evicted_keys) {
+        auto buf = std::make_unique<char[]>(kValueSize);
+        std::memset(buf.get(), 'x', kValueSize);
+        std::unordered_map<std::string, std::vector<Slice>> batch;
+        batch.emplace(key, std::vector<Slice>{Slice{buf.get(), kValueSize}});
+        auto result = storage_backend.BatchOffload(
+            batch,
+            [](const std::vector<std::string>&,
+               std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; },
+            [evicted_keys](const std::vector<std::string>& keys)
+                -> tl::expected<void, ErrorCode> {
+                if (evicted_keys != nullptr) {
+                    evicted_keys->insert(evicted_keys->end(), keys.begin(),
+                                         keys.end());
+                }
+                return {};
+            });
+        ASSERT_TRUE(result.has_value()) << "Offload failed for key " << key;
+    };
+
+    // Bucket A: offload, then read so its access timestamp becomes t1 > 0.
+    offload_one("lru_ts_key_a", nullptr);
+    EXPECT_EQ(storage_backend.GetLruIndexSizeForTest(), 1u);
+
+    // Rollback on complete_handler failure: the committed bucket must be
+    // rolled back and its lru_index_ entry removed. Use a small value so this
+    // offload stays under the quota and does not trigger eviction.
+    {
+        std::string rollback_key = "lru_ts_rollback_key";
+        std::string rollback_data = "rollback_data";
+        std::unordered_map<std::string, std::vector<Slice>> batch;
+        batch.emplace(rollback_key,
+                      std::vector<Slice>{
+                          Slice{rollback_data.data(), rollback_data.size()}});
+        auto rollback_res = storage_backend.BatchOffload(
+            batch, [](const std::vector<std::string>&,
+                      std::vector<StorageObjectMetadata>&) {
+                return ErrorCode::INTERNAL_ERROR;
+            });
+        ASSERT_FALSE(rollback_res.has_value());
+        EXPECT_EQ(rollback_res.error(), ErrorCode::INTERNAL_ERROR);
+
+        auto exist_res = storage_backend.IsExist(rollback_key);
+        ASSERT_TRUE(exist_res.has_value());
+        EXPECT_FALSE(exist_res.value()) << "Rolled-back key must not exist";
+
+        EXPECT_EQ(storage_backend.GetLruIndexSizeForTest(), 1u)
+            << "Rolled-back bucket's lru_index_ entry must be removed";
+    }
+
+    {
+        auto read_buf = std::make_unique<char[]>(kValueSize);
+        std::unordered_map<std::string, Slice> load_slices;
+        load_slices.emplace("lru_ts_key_a", Slice{read_buf.get(), kValueSize});
+        ASSERT_TRUE(storage_backend.BatchLoad(load_slices).has_value());
+    }
+    std::this_thread::sleep_for(std::chrono::milliseconds(2));
+
+    // Bucket B: freshly offloaded. Its timestamp must be t2 > t1 (it would
+    // be 0 without the timestamp update in BatchOffload).
+    offload_one("lru_ts_key_b", nullptr);
+    EXPECT_EQ(storage_backend.GetLruIndexSizeForTest(), 2u);
+
+    // Bucket C: overflows the quota and forces eviction of one bucket.
+    std::vector<std::string> evicted_keys;
+    offload_one("lru_ts_key_c", &evicted_keys);
+    EXPECT_EQ(storage_backend.GetLruIndexSizeForTest(), 2u)
+        << "lru_index_ must stay in sync with buckets_ after eviction";
+
+    ASSERT_EQ(evicted_keys.size(), 1u)
+        << "Exactly one bucket should be evicted";
+    EXPECT_EQ(evicted_keys[0], "lru_ts_key_a")
+        << "LRU victim should be the previously read bucket A, not the "
+           "freshly offloaded bucket B";
+
+    auto exist_b = storage_backend.IsExist("lru_ts_key_b");
+    ASSERT_TRUE(exist_b.has_value());
+    EXPECT_TRUE(exist_b.value())
+        << "Freshly offloaded bucket must not be evicted immediately "
+           "(its access timestamp must not be 0)";
+}
+
+#ifdef USE_URING
+TEST_F(StorageBackendTest, BucketBatchLoadUsesUringAcrossQueueDepth) {
+    constexpr int kKeyCount = 40;
+    constexpr size_t kValueSize = 1024;
+    constexpr size_t kReadBufferSize = 8192;
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    config.use_uring = true;
+
+    BucketBackendConfig bucket_config;
+    bucket_config.bucket_keys_limit = kKeyCount;
+    bucket_config.bucket_size_limit = 1024 * 1024;
+    bucket_config.max_total_size = 4 * 1024 * 1024;
+
+    BucketStorageBackend storage_backend(config, bucket_config);
+    ASSERT_TRUE(storage_backend.Init().has_value());
+
+    std::vector<std::string> keys(kKeyCount);
+    std::vector<std::string> values(kKeyCount);
+    std::unordered_map<std::string, std::vector<Slice>> offload_batch;
+    for (int i = 0; i < kKeyCount; ++i) {
+        keys[i] = "uring_batch_key_" + std::to_string(i);
+        values[i] = std::string(kValueSize, static_cast<char>('A' + i % 26));
+        offload_batch.emplace(
+            keys[i],
+            std::vector<Slice>{Slice{values[i].data(), values[i].size()}});
+    }
+
+    auto offload_result = storage_backend.BatchOffload(
+        offload_batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_TRUE(offload_result.has_value()) << offload_result.error();
+
+    using AlignedBuffer = std::unique_ptr<void, decltype(&std::free)>;
+    std::vector<AlignedBuffer> read_buffers;
+    std::unordered_map<std::string, Slice> load_batch;
+    read_buffers.reserve(kKeyCount);
+    for (int i = 0; i < kKeyCount; ++i) {
+        void* buffer = nullptr;
+        ASSERT_EQ(posix_memalign(&buffer, 4096, kReadBufferSize), 0);
+        read_buffers.emplace_back(buffer, &std::free);
+        load_batch.emplace(keys[i], Slice{buffer, kValueSize});
+    }
+
+    auto load_result = storage_backend.BatchLoad(load_batch);
+    ASSERT_TRUE(load_result.has_value()) << load_result.error();
+    for (int i = 0; i < kKeyCount; ++i) {
+        const auto& loaded = load_batch.at(keys[i]);
+        EXPECT_EQ(std::string_view(static_cast<char*>(loaded.ptr), loaded.size),
+                  values[i]);
+    }
+}
+
+TEST_F(StorageBackendTest, BucketBatchLoadRejectsShortRead) {
+    constexpr int kKeyCount = 2;
+    constexpr size_t kValueSize = 4096;
+    constexpr size_t kReadBufferSize = 8192;
+
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    config.use_uring = true;
+
+    BucketBackendConfig bucket_config;
+    bucket_config.bucket_keys_limit = kKeyCount;
+    bucket_config.bucket_size_limit = 64 * 1024;
+    bucket_config.max_total_size = 1024 * 1024;
+
+    BucketStorageBackend storage_backend(config, bucket_config);
+    ASSERT_TRUE(storage_backend.Init().has_value());
+
+    std::vector<std::string> keys{"short_read_key_0", "short_read_key_1"};
+    std::vector<std::string> values{std::string(kValueSize, 'A'),
+                                    std::string(kValueSize, 'B')};
+    std::unordered_map<std::string, std::vector<Slice>> offload_batch;
+    for (int i = 0; i < kKeyCount; ++i) {
+        offload_batch.emplace(
+            keys[i],
+            std::vector<Slice>{Slice{values[i].data(), values[i].size()}});
+    }
+
+    auto offload_result = storage_backend.BatchOffload(
+        offload_batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    ASSERT_TRUE(offload_result.has_value()) << offload_result.error();
+
+    std::filesystem::path bucket_path;
+    for (const auto& entry : std::filesystem::directory_iterator(data_path)) {
+        if (entry.path().extension() == ".bucket") {
+            bucket_path = entry.path();
+            break;
+        }
+    }
+    ASSERT_FALSE(bucket_path.empty());
+    auto bucket_size = std::filesystem::file_size(bucket_path);
+    ASSERT_GT(bucket_size, kValueSize / 2);
+    std::filesystem::resize_file(bucket_path, bucket_size - kValueSize / 2);
+
+    using AlignedBuffer = std::unique_ptr<void, decltype(&std::free)>;
+    std::vector<AlignedBuffer> read_buffers;
+    std::unordered_map<std::string, Slice> load_batch;
+    for (int i = 0; i < kKeyCount; ++i) {
+        void* buffer = nullptr;
+        ASSERT_EQ(posix_memalign(&buffer, 4096, kReadBufferSize), 0);
+        read_buffers.emplace_back(buffer, &std::free);
+        load_batch.emplace(keys[i], Slice{buffer, kValueSize});
+    }
+
+    auto load_result = storage_backend.BatchLoad(load_batch);
+    ASSERT_FALSE(load_result.has_value());
+    EXPECT_EQ(load_result.error(), ErrorCode::FILE_READ_FAIL);
+}
+
+#endif
+
+TEST_F(StorageBackendTest, DatasyncFailureRemovesOrphanBucketFile) {
+    FileStorageConfig config;
+    config.storage_filepath = data_path;
+    BucketBackendConfig bucket_config;
+    BucketStorageBackend storage_backend(config, bucket_config);
+    ASSERT_TRUE(storage_backend.Init());
+
+    // Enable datasync-failure injection: WriteBucket's datasync() call will
+    // return a failure, exercising the same !sync_result cleanup path as a
+    // real fdatasync() failure (CleanupOrphanedBucket + error return).
+    storage_backend.SetDatasyncFailureForTest(true);
+
+    std::string key = "datasync_fail_key";
+    std::string value = "datasync_fail_payload";
+    void* buf = nullptr;
+    ASSERT_EQ(posix_memalign(&buf, 4096, value.size()), 0);
+    std::unique_ptr<void, decltype(&std::free)> buf_guard(buf, &std::free);
+    memcpy(buf, value.data(), value.size());
+
+    std::unordered_map<std::string, std::vector<Slice>> batch;
+    batch.emplace(key, std::vector<Slice>{Slice{buf, value.size()}});
+
+    // BatchOffload must return an error (datasync was injected to fail).
+    auto offload_result = storage_backend.BatchOffload(
+        batch,
+        [](const std::vector<std::string>&,
+           std::vector<StorageObjectMetadata>&) { return ErrorCode::OK; });
+    EXPECT_FALSE(offload_result.has_value());
+    EXPECT_EQ(offload_result.error(), ErrorCode::FILE_WRITE_FAIL);
+
+    // The .bucket file must have been cleaned up by CleanupOrphanedBucket.
+    int orphan_bucket_count = 0;
+    for (const auto& entry : fs::directory_iterator(data_path)) {
+        if (entry.path().extension() == ".bucket") {
+            ++orphan_bucket_count;
+        }
+    }
+    EXPECT_EQ(orphan_bucket_count, 0)
+        << "datasync failure must not leave an orphan .bucket file on disk";
+
+    // No .meta file should have been written either (metadata commit comes
+    // after datasync, so it was never reached).
+    int meta_count = 0;
+    for (const auto& entry : fs::directory_iterator(data_path)) {
+        if (entry.path().extension() == ".meta") {
+            ++meta_count;
+        }
+    }
+    EXPECT_EQ(meta_count, 0)
+        << "metadata must not be committed when datasync fails";
+
+    // The key must not be queryable.
+    auto exists = storage_backend.IsExist(key);
+    ASSERT_TRUE(exists.has_value());
+    EXPECT_FALSE(exists.value());
+}
+
 }  // namespace mooncake::test
diff --git a/mooncake-store/tests/stress_workload_test.cpp b/mooncake-store/tests/stress_workload_test.cpp
index fe46b35070..e0d7d4d469 100644
--- a/mooncake-store/tests/stress_workload_test.cpp
+++ b/mooncake-store/tests/stress_workload_test.cpp
@@ -14,7 +14,7 @@
 #include "allocator.h"
 #include "client_service.h"
 #include "types.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
 
 // Configuration flags
 DEFINE_string(protocol, "rdma", "Transfer protocol: rdma|tcp");
diff --git a/mooncake-store/tests/task_executor_test.cpp b/mooncake-store/tests/task_executor_test.cpp
index 0f9b82e231..cb0c5e913e 100644
--- a/mooncake-store/tests/task_executor_test.cpp
+++ b/mooncake-store/tests/task_executor_test.cpp
@@ -1,499 +1,58 @@
-#include "client_service.h"
-#include "master_client.h"
 #include "task_manager.h"
-#include "rpc_types.h"
-#include "gtest/gtest.h"
-#include "glog/logging.h"
-#include <ylt/struct_json/json_writer.h>
+
+#include <gtest/gtest.h>
 #include <ylt/struct_json/json_reader.h>
-#include <memory>
-#include <thread>
-#include <chrono>
-#include <vector>
-#include <cstring>
-#include <map>
-#include <atomic>
-#include <set>
+#include <ylt/struct_json/json_writer.h>
+
 #include <string>
 
 namespace mooncake {
 
-// Test class for Client Copy/Move and task execution functionality
-// Note: TaskExecutor has been merged into Client class.
-// These are unit tests for the logic that can be tested without full
-// integration. Full end-to-end tests are in task_integration_test.cpp
-class TaskExecutorTest : public ::testing::Test {
-   protected:
-    void SetUp() override {
-        google::InitGoogleLogging("TaskExecutorTest");
-        FLAGS_logtostderr = 1;
-    }
-
-    void TearDown() override { google::ShutdownGoogleLogging(); }
-
-    // Helper to create a valid memory replica descriptor
-    Replica::Descriptor CreateMemoryReplicaDescriptor(
-        ReplicaID id, const std::string& segment_name, size_t size = 1024) {
-        Replica::Descriptor replica;
-        replica.id = id;
-        replica.status = ReplicaStatus::COMPLETE;
-        MemoryDescriptor mem_desc;
-        mem_desc.buffer_descriptor.size_ = size;
-        mem_desc.buffer_descriptor.buffer_address_ = 0x1000;
-        mem_desc.buffer_descriptor.transport_endpoint_ = segment_name;
-        replica.descriptor_variant = mem_desc;
-        return replica;
-    }
-
-    // Helper to create a query result with replicas
-    QueryResult CreateQueryResultWithReplicas(
-        const std::vector<Replica::Descriptor>& replicas) {
-        std::vector<Replica::Descriptor> replicas_copy =
-            replicas;  // Make a copy to move
-        std::chrono::steady_clock::time_point lease_timeout =
-            std::chrono::steady_clock::now() +
-            std::chrono::seconds(60);  // 60 second lease
-        return QueryResult(std::move(replicas_copy), lease_timeout);
-    }
-};
-
-// Payload Structure Tests
-TEST_F(TaskExecutorTest, ReplicaCopyPayloadStructure) {
+TEST(TaskPayloadSerializationTest, ReplicaCopyPayloadRoundTrip) {
     ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {"target1", "target2"};
+    payload.tenant_id = "tenant-a";
+    payload.key = "copy-key";
+    payload.source = "source-segment";
+    payload.targets = {"target-segment-1", "target-segment-2"};
+    payload.dynamic_replication_lease_id_high = 123;
+    payload.dynamic_replication_lease_id_low = 456;
+    payload.dynamic_replication_version_epoch = 789;
 
-    EXPECT_EQ(payload.key, "test_key");
-    EXPECT_EQ(payload.targets.size(), 2);
-    EXPECT_EQ(payload.targets[0], "target1");
-    EXPECT_EQ(payload.targets[1], "target2");
-}
-
-TEST_F(TaskExecutorTest, ReplicaCopyPayloadMultipleTargets) {
-    ReplicaCopyPayload payload;
-    payload.key = "test_multi_target_key";
-    payload.targets = {"segment1", "segment2", "segment3", "segment4"};
-
-    EXPECT_EQ(payload.key, "test_multi_target_key");
-    EXPECT_EQ(payload.targets.size(), 4);
-    EXPECT_EQ(payload.targets[0], "segment1");
-    EXPECT_EQ(payload.targets[1], "segment2");
-    EXPECT_EQ(payload.targets[2], "segment3");
-    EXPECT_EQ(payload.targets[3], "segment4");
-
-    // Test serialization and deserialization
     std::string json;
     struct_json::to_json(payload, json);
 
-    ReplicaCopyPayload deserialized_payload;
-    struct_json::from_json(deserialized_payload, json);
-
-    EXPECT_EQ(deserialized_payload.key, payload.key);
-    EXPECT_EQ(deserialized_payload.targets.size(), payload.targets.size());
-    for (size_t i = 0; i < payload.targets.size(); ++i) {
-        EXPECT_EQ(deserialized_payload.targets[i], payload.targets[i]);
-    }
-}
-
-TEST_F(TaskExecutorTest, ReplicaCopyPayloadEmptyTargets) {
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {};
-
-    EXPECT_EQ(payload.key, "test_key");
-    EXPECT_EQ(payload.targets.size(), 0);
-
-    // Serialization and deserialization should handle empty vector
-    std::string json;
-    struct_json::to_json(payload, json);
-
-    ReplicaCopyPayload deserialized_payload;
-    struct_json::from_json(deserialized_payload, json);
-
-    EXPECT_EQ(deserialized_payload.key, payload.key);
-    EXPECT_EQ(deserialized_payload.targets.size(), 0);
-}
-
-TEST_F(TaskExecutorTest, ReplicaCopyPayloadSingleTarget) {
-    ReplicaCopyPayload payload;
-    payload.key = "test_single_target_key";
-    payload.targets = {"target_segment"};
-
-    EXPECT_EQ(payload.key, "test_single_target_key");
-    EXPECT_EQ(payload.targets.size(), 1);
-    EXPECT_EQ(payload.targets[0], "target_segment");
-}
-
-TEST_F(TaskExecutorTest, ReplicaMovePayloadStructure) {
-    ReplicaMovePayload payload;
-    payload.key = "test_key";
-    payload.source = "source_segment";
-    payload.target = "target_segment";
-
-    EXPECT_EQ(payload.key, "test_key");
-    EXPECT_EQ(payload.source, "source_segment");
-    EXPECT_EQ(payload.target, "target_segment");
-}
-
-// Task Payload Tests
-TEST_F(TaskExecutorTest, TaskWithReplicaCopyPayload) {
-    Task task;
-    UUID test_id = generate_uuid();
-    task.id = test_id;
-    task.type = TaskType::REPLICA_COPY;
-    task.status = TaskStatus::PENDING;
-
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {"target1", "target2"};
+    ReplicaCopyPayload round_tripped;
+    struct_json::from_json(round_tripped, json);
 
-    struct_json::to_json(payload, task.payload);
-
-    EXPECT_EQ(task.id.first, test_id.first);
-    EXPECT_EQ(task.id.second, test_id.second);
-    EXPECT_EQ(task.type, TaskType::REPLICA_COPY);
-    EXPECT_EQ(task.status, TaskStatus::PENDING);
-    EXPECT_FALSE(task.payload.empty());
-
-    // Verify we can deserialize
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, task.payload);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_EQ(deserialized.targets.size(), 2);
+    EXPECT_EQ(round_tripped.tenant_id, payload.tenant_id);
+    EXPECT_EQ(round_tripped.key, payload.key);
+    EXPECT_EQ(round_tripped.source, payload.source);
+    EXPECT_EQ(round_tripped.targets, payload.targets);
+    EXPECT_EQ(round_tripped.dynamic_replication_lease_id_high,
+              payload.dynamic_replication_lease_id_high);
+    EXPECT_EQ(round_tripped.dynamic_replication_lease_id_low,
+              payload.dynamic_replication_lease_id_low);
+    EXPECT_EQ(round_tripped.dynamic_replication_version_epoch,
+              payload.dynamic_replication_version_epoch);
 }
 
-TEST_F(TaskExecutorTest, TaskWithReplicaMovePayload) {
-    Task task;
-    task.id = generate_uuid();
-    task.type = TaskType::REPLICA_MOVE;
-    task.status = TaskStatus::PENDING;
-
+TEST(TaskPayloadSerializationTest, ReplicaMovePayloadRoundTrip) {
     ReplicaMovePayload payload;
-    payload.key = "test_key";
-    payload.source = "source_segment";
-    payload.target = "target_segment";
-
-    struct_json::to_json(payload, task.payload);
-
-    EXPECT_EQ(task.type, TaskType::REPLICA_MOVE);
-    EXPECT_EQ(task.status, TaskStatus::PENDING);
-    EXPECT_FALSE(task.payload.empty());
-
-    // Verify we can deserialize
-    ReplicaMovePayload deserialized;
-    struct_json::from_json(deserialized, task.payload);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_EQ(deserialized.source, "source_segment");
-    EXPECT_EQ(deserialized.target, "target_segment");
-}
-
-// Replica Descriptor Tests
-TEST_F(TaskExecutorTest, MemoryReplicaDescriptorHandling) {
-    // Test creating memory replica descriptor
-    auto replica = CreateMemoryReplicaDescriptor(1, "test_segment:12345", 1024);
-
-    EXPECT_EQ(replica.id, 1);
-    EXPECT_EQ(replica.status, ReplicaStatus::COMPLETE);
-    EXPECT_TRUE(replica.is_memory_replica());
-
-    const auto& mem_desc = replica.get_memory_descriptor();
-    EXPECT_EQ(mem_desc.buffer_descriptor.size_, 1024);
-    EXPECT_EQ(mem_desc.buffer_descriptor.transport_endpoint_,
-              "test_segment:12345");
-}
-
-TEST_F(TaskExecutorTest, SourceSegmentExtraction) {
-    // Test source segment extraction logic:
-    // For memory replica: use buffer_descriptor.transport_endpoint_
-    // For disk replica: use payload.source (requires src_segment in payload)
-
-    auto memory_replica =
-        CreateMemoryReplicaDescriptor(1, "memory_seg:12345", 1024);
-    EXPECT_TRUE(memory_replica.is_memory_replica());
-
-    const auto& mem_desc = memory_replica.get_memory_descriptor();
-    std::string src_segment = mem_desc.buffer_descriptor.transport_endpoint_;
-    EXPECT_EQ(src_segment, "memory_seg:12345");
-}
-
-// ClientTask and TaskAssignment Tests
-TEST_F(TaskExecutorTest, ClientTaskStructure) {
-    // ClientTask is now a private struct in Client class, but we can test
-    // TaskAssignment which is used to construct ClientTask
-    TaskAssignment assignment;
-    assignment.id = generate_uuid();
-    assignment.type = TaskType::REPLICA_COPY;
-
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {"target1"};
-    struct_json::to_json(payload, assignment.payload);
-
-    EXPECT_EQ(assignment.type, TaskType::REPLICA_COPY);
-    EXPECT_FALSE(assignment.payload.empty());
-
-    // Verify we can deserialize
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, assignment.payload);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_EQ(deserialized.targets.size(), 1);
-}
-
-TEST_F(TaskExecutorTest, TaskAssignmentToClientTaskConversion) {
-    TaskAssignment assignment;
-    assignment.id = generate_uuid();
-    assignment.type = TaskType::REPLICA_COPY;
-
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {"target1", "target2"};
-    struct_json::to_json(payload, assignment.payload);
-
-    // Simulate ClientTask construction (ClientTask is private, so we test the
-    // pattern) In actual Client code: ClientTask client_task;
-    // client_task.assignment = assignment; client_task.retry_count = 0;
-    EXPECT_EQ(assignment.type, TaskType::REPLICA_COPY);
-    EXPECT_FALSE(assignment.payload.empty());
-
-    // Verify payload can be deserialized
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, assignment.payload);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_EQ(deserialized.targets.size(), 2);
-}
-
-// Copy/Move Method Parameter Validation Tests
-TEST_F(TaskExecutorTest, CopyMethodEmptyKey) {
-    // This test documents expected behavior for empty key
-    // Actual implementation will fail at Query stage
-    ReplicaCopyPayload payload;
-    payload.key = "";
-    payload.targets = {"target1"};
-
-    // Serialization should work even with empty key
-    std::string json;
-    struct_json::to_json(payload, json);
-    EXPECT_FALSE(json.empty());
-
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, json);
-    EXPECT_TRUE(deserialized.key.empty());
-    EXPECT_EQ(deserialized.targets.size(), 1);
-}
-
-TEST_F(TaskExecutorTest, CopyMethodEmptyTargets) {
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {};
-
-    // Serialization should handle empty targets
-    std::string json;
-    struct_json::to_json(payload, json);
-
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, json);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_TRUE(deserialized.targets.empty());
-}
-
-TEST_F(TaskExecutorTest, MoveMethodEmptyKey) {
-    ReplicaMovePayload payload;
-    payload.key = "";
-    payload.source = "source_segment";
-    payload.target = "target_segment";
+    payload.tenant_id = "tenant-b";
+    payload.key = "move-key";
+    payload.source = "source-segment";
+    payload.target = "target-segment";
 
     std::string json;
     struct_json::to_json(payload, json);
 
-    ReplicaMovePayload deserialized;
-    struct_json::from_json(deserialized, json);
-    EXPECT_TRUE(deserialized.key.empty());
-    EXPECT_EQ(deserialized.source, "source_segment");
-    EXPECT_EQ(deserialized.target, "target_segment");
-}
-
-TEST_F(TaskExecutorTest, MoveMethodEmptySegments) {
-    ReplicaMovePayload payload;
-    payload.key = "test_key";
-    payload.source = "";
-    payload.target = "target_segment";
-
-    std::string json;
-    struct_json::to_json(payload, json);
-
-    ReplicaMovePayload deserialized;
-    struct_json::from_json(deserialized, json);
-    EXPECT_EQ(deserialized.key, "test_key");
-    EXPECT_TRUE(deserialized.source.empty());
-    EXPECT_EQ(deserialized.target, "target_segment");
-}
-
-// Source Segment Selection Logic Tests
-TEST_F(TaskExecutorTest, SourceSegmentSelectionLogic) {
-    // Create multiple replicas with different segments
-    std::vector<Replica::Descriptor> replicas;
-    replicas.push_back(CreateMemoryReplicaDescriptor(1, "segment1", 1024));
-    replicas.push_back(CreateMemoryReplicaDescriptor(2, "segment2", 1024));
-    replicas.push_back(CreateMemoryReplicaDescriptor(3, "segment3", 1024));
-
-    // Test finding source when targets are segment2 and segment3
-    std::vector<std::string> targets = {"segment2", "segment3"};
-    std::set<std::string> target_set(targets.begin(), targets.end());
-
-    bool found_source = false;
-    std::string selected_segment;
-    for (const auto& replica : replicas) {
-        if (replica.is_memory_replica()) {
-            const auto& mem_desc = replica.get_memory_descriptor();
-            std::string replica_segment =
-                mem_desc.buffer_descriptor.transport_endpoint_;
-            if (target_set.find(replica_segment) == target_set.end()) {
-                selected_segment = replica_segment;
-                found_source = true;
-                break;
-            }
-        }
-    }
-
-    EXPECT_TRUE(found_source);
-    EXPECT_EQ(selected_segment, "segment1");
-}
-
-TEST_F(TaskExecutorTest, SourceSegmentSelectionAllInTargets) {
-    std::vector<Replica::Descriptor> replicas;
-    replicas.push_back(CreateMemoryReplicaDescriptor(1, "segment1", 1024));
-    replicas.push_back(CreateMemoryReplicaDescriptor(2, "segment2", 1024));
-
-    std::vector<std::string> targets = {"segment1", "segment2"};
-    std::set<std::string> target_set(targets.begin(), targets.end());
-
-    bool found_source = false;
-    for (const auto& replica : replicas) {
-        if (replica.is_memory_replica()) {
-            const auto& mem_desc = replica.get_memory_descriptor();
-            std::string replica_segment =
-                mem_desc.buffer_descriptor.transport_endpoint_;
-            if (target_set.find(replica_segment) == target_set.end()) {
-                found_source = true;
-                break;
-            }
-        }
-    }
-
-    EXPECT_FALSE(found_source);
-}
-
-// Retry Logic Tests
-TEST_F(TaskExecutorTest, RetryCountIncrement) {
-    // Simulate ClientTask retry logic
-    uint32_t retry_count = 0;
-    constexpr uint32_t MAX_RETRY_COUNT = 10;
-
-    // Test incrementing retry count
-    for (uint32_t i = 0; i < MAX_RETRY_COUNT; ++i) {
-        EXPECT_EQ(retry_count, i);
-        retry_count++;
-        EXPECT_EQ(retry_count, i + 1);
-    }
-
-    EXPECT_EQ(retry_count, MAX_RETRY_COUNT);
-
-    // Test that retry count can exceed MAX_RETRY_COUNT
-    retry_count++;
-    EXPECT_EQ(retry_count, MAX_RETRY_COUNT + 1);
-}
-
-TEST_F(TaskExecutorTest, RetryDecisionLogic) {
-    constexpr uint32_t MAX_RETRY_COUNT = 10;
-
-    // Test cases for retry decision
-    struct RetryTestCase {
-        ErrorCode error;
-        uint32_t retry_count;
-        bool should_retry;
-    };
-
-    std::vector<RetryTestCase> test_cases = {
-        {ErrorCode::NO_AVAILABLE_HANDLE, 0, true},    // Should retry
-        {ErrorCode::NO_AVAILABLE_HANDLE, 5, true},    // Should retry
-        {ErrorCode::NO_AVAILABLE_HANDLE, 9, true},    // Should retry
-        {ErrorCode::NO_AVAILABLE_HANDLE, 10, false},  // Max retries reached
-        {ErrorCode::NO_AVAILABLE_HANDLE, 11, false},  // Exceeded max
-        {ErrorCode::OBJECT_NOT_FOUND, 0, false},      // Should not retry
-        {ErrorCode::REPLICA_NOT_FOUND, 0, false},     // Should not retry
-        {ErrorCode::INTERNAL_ERROR, 0, false},        // Should not retry
-    };
-
-    for (const auto& test_case : test_cases) {
-        bool should_retry =
-            (test_case.error == ErrorCode::NO_AVAILABLE_HANDLE) &&
-            (test_case.retry_count < MAX_RETRY_COUNT);
-        EXPECT_EQ(should_retry, test_case.should_retry)
-            << "Error: " << static_cast<int>(test_case.error)
-            << ", Retry count: " << test_case.retry_count;
-    }
-}
-
-TEST_F(TaskExecutorTest, RetryDelayCalculation) {
-    constexpr uint32_t MAX_RETRY_COUNT = 10;
-
-    for (uint32_t retry_count = 0; retry_count < MAX_RETRY_COUNT;
-         ++retry_count) {
-        auto retry_delay = std::chrono::milliseconds(50 * (retry_count + 1));
-        EXPECT_EQ(retry_delay.count(), 50 * (retry_count + 1));
-    }
-}
-
-// Task Type and Error Handling Tests
-TEST_F(TaskExecutorTest, TaskTypeHandling) {
-    // Test valid task types
-    EXPECT_EQ(static_cast<int>(TaskType::REPLICA_COPY), 0);
-    EXPECT_EQ(static_cast<int>(TaskType::REPLICA_MOVE), 1);
-
-    // Test invalid task type (should be handled gracefully)
-    TaskType invalid_type = static_cast<TaskType>(999);
-    EXPECT_NE(invalid_type, TaskType::REPLICA_COPY);
-    EXPECT_NE(invalid_type, TaskType::REPLICA_MOVE);
-}
-
-TEST_F(TaskExecutorTest, PayloadDeserializationErrorHandling) {
-    TaskAssignment assignment;
-    assignment.id = generate_uuid();
-    assignment.type = TaskType::REPLICA_COPY;
-    assignment.payload = R"({"invalid": "json"})";  // Missing required fields
-
-    // This should be caught by exception handler in ExecuteTask
-    ReplicaCopyPayload payload;
-    bool exception_caught = false;
-    try {
-        struct_json::from_json(payload, assignment.payload);
-    } catch (const std::exception& e) {
-        exception_caught = true;
-    }
-
-    // struct_json does not throw, but field will be default
-    EXPECT_FALSE(exception_caught);
-    EXPECT_TRUE(payload.key.empty());
-    EXPECT_TRUE(payload.targets.empty());
-}
-
-// Multiple Target Segments Handling Tests
-TEST_F(TaskExecutorTest, MultipleTargetSegmentsHandling) {
-    ReplicaCopyPayload payload;
-    payload.key = "test_key";
-    payload.targets = {"target1", "target2", "target3", "target4", "target5"};
-
-    EXPECT_EQ(payload.targets.size(), 5);
-    EXPECT_EQ(payload.targets[0], "target1");
-    EXPECT_EQ(payload.targets[4], "target5");
-
-    // Test serialization with multiple targets
-    std::string json;
-    struct_json::to_json(payload, json);
+    ReplicaMovePayload round_tripped;
+    struct_json::from_json(round_tripped, json);
 
-    ReplicaCopyPayload deserialized;
-    struct_json::from_json(deserialized, json);
-    EXPECT_EQ(deserialized.targets.size(), 5);
+    EXPECT_EQ(round_tripped.tenant_id, payload.tenant_id);
+    EXPECT_EQ(round_tripped.key, payload.key);
+    EXPECT_EQ(round_tripped.source, payload.source);
+    EXPECT_EQ(round_tripped.target, payload.target);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-store/tests/task_integration_test.cpp b/mooncake-store/tests/task_integration_test.cpp
index a160cb58bb..f5c5e618ac 100644
--- a/mooncake-store/tests/task_integration_test.cpp
+++ b/mooncake-store/tests/task_integration_test.cpp
@@ -3,10 +3,11 @@
 #include <gtest/gtest.h>
 
 #include <csignal>
+#include <chrono>
 #include <memory>
+#include <set>
 #include <string>
 #include <thread>
-#include <chrono>
 #include <vector>
 
 #include <ylt/coro_http/coro_http_client.hpp>
@@ -18,7 +19,8 @@
 #include "master_client.h"
 #include "task_manager.h"
 #include "types.h"
-#include "utils.h"
+#include "common/client_buffer_allocation.h"
+#include "common/network.h"
 #include "test_server_helpers.h"
 #include "default_config.h"
 #include "allocator.h"
@@ -34,6 +36,10 @@ namespace testing {
 
 namespace {
 
+constexpr char kClient1Endpoint[] = "127.0.0.1:18001";
+constexpr char kClient2Endpoint[] = "127.0.0.1:18002";
+constexpr char kClient3Endpoint[] = "127.0.0.1:18003";
+
 struct HttpCreateDrainJobResponse {
     bool success{false};
     std::string job_id;
@@ -133,7 +139,7 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
     void SetUp() override {
         // Create client 1
         auto client1_opt = Client::Create(
-            "127.0.0.1:18001",
+            kClient1Endpoint,
             metadata_url_.empty() ? "P2PHANDSHAKE" : metadata_url_,
             FLAGS_protocol,
             FLAGS_device_name.empty() ? std::nullopt
@@ -144,7 +150,7 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
 
         // Create client 2
         auto client2_opt = Client::Create(
-            "127.0.0.1:18002",
+            kClient2Endpoint,
             metadata_url_.empty() ? "P2PHANDSHAKE" : metadata_url_,
             FLAGS_protocol,
             FLAGS_device_name.empty() ? std::nullopt
@@ -181,11 +187,6 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
 
         // Wait for segments to be registered and clients to ping master
         std::this_thread::sleep_for(std::chrono::milliseconds(1000));
-
-        // Client IDs will be extracted from task assignments when tasks are
-        // created For now, initialize with placeholder values
-        client1_id_ = generate_uuid();
-        client2_id_ = generate_uuid();
     }
 
     void TearDown() override {
@@ -197,21 +198,37 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
             free(client2_segment_ptr_);
             client2_segment_ptr_ = nullptr;
         }
+        if (client3_ && client3_segment_ptr_) {
+            free(client3_segment_ptr_);
+            client3_segment_ptr_ = nullptr;
+        }
     }
 
     static void CleanupClients() {
         // Clients will be cleaned up by shared_ptr
     }
 
-    // Helper to extract client_id from task assignment
-    // When a task is created, we can query it to see which client it's assigned
-    // to
-    UUID GetClientIdFromTask(const UUID& task_id) {
-        auto query_result = master_client_->QueryTask(task_id);
-        if (query_result.has_value()) {
-            return query_result.value().assigned_client;
-        }
-        return generate_uuid();  // Fallback
+    void MountThirdClientSegment() {
+        auto client3_opt = Client::Create(
+            kClient3Endpoint,
+            metadata_url_.empty() ? "P2PHANDSHAKE" : metadata_url_,
+            FLAGS_protocol,
+            FLAGS_device_name.empty() ? std::nullopt
+                                      : std::make_optional(FLAGS_device_name),
+            master_address_);
+        ASSERT_TRUE(client3_opt.has_value());
+        client3_ = client3_opt.value();
+
+        constexpr size_t kSegmentSize = 256 * 1024 * 1024;
+        client3_segment_ptr_ = allocate_buffer_allocator_memory(kSegmentSize);
+        ASSERT_NE(client3_segment_ptr_, nullptr);
+        auto mount_result =
+            client3_->MountSegment(client3_segment_ptr_, kSegmentSize);
+        ASSERT_TRUE(mount_result.has_value())
+            << "Failed to mount segment for client3: "
+            << toString(mount_result.error());
+
+        std::this_thread::sleep_for(std::chrono::milliseconds(1000));
     }
 
     // Wait for task to complete by polling task status
@@ -296,27 +313,25 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
         return false;
     }
 
-    // Get segment name from a query result
-    // Note: segment name is typically the client's hostname (e.g.,
-    // "127.0.0.1:18001")
-    std::string GetSegmentNameFromQuery(const QueryResult& query_result) {
-        if (query_result.replicas.empty()) {
-            return "";
-        }
+    void ExpectReplicaEndpoints(
+        const std::string& key,
+        const std::set<std::string>& expected_endpoints) {
+        auto query_result = client1_->Query(key);
+        ASSERT_TRUE(query_result.has_value())
+            << "Failed to query replicas for key=" << key << ": "
+            << toString(query_result.error());
+        ASSERT_EQ(query_result->replicas.size(), expected_endpoints.size())
+            << "Unexpected replica count for key=" << key;
 
-        const auto& replica = query_result.replicas[0];
-        if (replica.is_memory_replica()) {
-            // Try to get segment name from the replica descriptor
-            // For memory replicas, the segment name is stored in the buffer
-            // descriptor but transport_endpoint_ might not match segment name
-            // We need to extract it from the replica's segment information
-            const auto& mem_desc = replica.get_memory_descriptor();
-            // The segment name is typically embedded in the buffer descriptor
-            // For now, use transport_endpoint_ as a fallback, but we should
-            // verify it matches the actual segment name used during mount
-            return mem_desc.buffer_descriptor.transport_endpoint_;
+        std::set<std::string> actual_endpoints;
+        for (const auto& replica : query_result->replicas) {
+            ASSERT_TRUE(replica.is_memory_replica())
+                << "Expected memory replica for key=" << key;
+            actual_endpoints.insert(replica.get_memory_descriptor()
+                                        .buffer_descriptor.transport_endpoint_);
         }
-        return "";
+        EXPECT_EQ(actual_endpoints, expected_endpoints)
+            << "Unexpected replica placement for key=" << key;
     }
 
    protected:
@@ -326,13 +341,12 @@ class TaskExecutorIntegrationTest : public ::testing::Test {
 
     std::shared_ptr<Client> client1_;
     std::shared_ptr<Client> client2_;
+    std::shared_ptr<Client> client3_;
     std::unique_ptr<MasterClient> master_client_;
 
-    UUID client1_id_;
-    UUID client2_id_;
-
     void* client1_segment_ptr_ = nullptr;
     void* client2_segment_ptr_ = nullptr;
+    void* client3_segment_ptr_ = nullptr;
 };
 
 InProcMaster TaskExecutorIntegrationTest::master_;
@@ -353,7 +367,8 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaCopyCompleteFlow) {
     std::vector<Slice> slices;
     slices.emplace_back(test_data.data(), test_data.size());
     ReplicateConfig config;
-    config.replica_num = 1;  // Start with 1 replica on client1
+    config.replica_num = 1;
+    config.preferred_segment = kClient1Endpoint;
 
     auto put_result = client1_->Put(test_key, slices, config);
     ASSERT_TRUE(put_result.has_value())
@@ -362,66 +377,25 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaCopyCompleteFlow) {
     // Wait a bit for put to complete
     std::this_thread::sleep_for(std::chrono::milliseconds(200));
 
-    // Step 2: Verify that client1's data was put successfully and get actual
-    // segment name
-    auto client1_query_result = client1_->Query(test_key);
-    ASSERT_TRUE(client1_query_result.has_value())
-        << "Failed to query key for verification";
-    ASSERT_FALSE(client1_query_result.value().replicas.empty())
-        << "No replicas found after Put";
-
-    // Extract actual segment name from replica
-    std::string source_segment;
-    const auto& replica = client1_query_result.value().replicas[0];
-    ASSERT_TRUE(replica.is_memory_replica()) << "Expected memory replica";
-    source_segment =
-        replica.get_memory_descriptor().buffer_descriptor.transport_endpoint_;
-    ASSERT_FALSE(source_segment.empty())
-        << "Failed to extract source segment name";
-
-    // Step 3: Determine target segment dynamically (must be different from
-    // source) Choose the other client's segment as target to ensure source !=
-    // target
-    std::string target_segment;
-    if (source_segment == "127.0.0.1:18001") {
-        target_segment = "127.0.0.1:18002";
-    } else if (source_segment == "127.0.0.1:18002") {
-        target_segment = "127.0.0.1:18001";
-    } else {
-        // If source is neither, default to client2's segment
-        target_segment = "127.0.0.1:18002";
-    }
-
-    // Verify source and target are different - this test only covers
-    // inconsistent cases
-    ASSERT_NE(source_segment, target_segment)
-        << "Source and target segments must be different for this test. "
-        << "Source: " << source_segment << ", Target: " << target_segment;
+    ExpectReplicaEndpoints(test_key, {kClient1Endpoint});
 
-    // Step 4: Create copy task via master
-    std::vector<std::string> targets = {target_segment};
+    // Step 2: Create copy task via master
+    std::vector<std::string> targets = {kClient2Endpoint};
     auto copy_result = master_client_->CreateCopyTask(test_key, targets);
     ASSERT_TRUE(copy_result.has_value())
         << "Failed to create copy task: " << toString(copy_result.error());
 
     UUID task_id = copy_result.value();
 
-    // Step 5: Get the actual client_id from the task assignment
-    client1_id_ = GetClientIdFromTask(task_id);
-
-    // Step 6: Wait for task to be fetched and executed by the assigned client
+    // Step 3: Wait for task to be fetched and executed by the assigned client
     bool task_completed =
         WaitForTaskCompletion(task_id, std::chrono::seconds(30));
     ASSERT_TRUE(task_completed) << "Task did not complete within timeout";
 
-    // Step 7: Verify copy was successful by querying from client2
-    auto client2_query_result = client2_->Query(test_key);
-    ASSERT_TRUE(client2_query_result.has_value())
-        << "Failed to query copied key";
-    ASSERT_FALSE(client2_query_result.value().replicas.empty())
-        << "No replicas found for copied key";
+    // Step 4: Copy adds the target and preserves the source replica.
+    ExpectReplicaEndpoints(test_key, {kClient1Endpoint, kClient2Endpoint});
 
-    // Step 8: Verify data integrity by getting data from client2
+    // Step 5: Verify data integrity.
     std::vector<uint8_t> read_buffer(test_data.size());
     std::vector<Slice> read_slices;
     read_slices.emplace_back(read_buffer.data(), read_buffer.size());
@@ -449,7 +423,8 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaMoveCompleteFlow) {
     std::vector<Slice> slices;
     slices.emplace_back(test_data.data(), test_data.size());
     ReplicateConfig config;
-    config.replica_num = 1;  // Start with 1 replica on client1
+    config.replica_num = 1;
+    config.preferred_segment = kClient1Endpoint;
 
     auto put_result = client1_->Put(test_key, slices, config);
     ASSERT_TRUE(put_result.has_value())
@@ -458,67 +433,25 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaMoveCompleteFlow) {
     // Wait a bit for put to complete
     std::this_thread::sleep_for(std::chrono::milliseconds(200));
 
-    // Step 2: Verify that client1's data was put successfully and get actual
-    // segment name
-    auto query_result = client1_->Query(test_key);
-    ASSERT_TRUE(query_result.has_value())
-        << "Failed to query key for verification";
-    ASSERT_FALSE(query_result.value().replicas.empty())
-        << "No replicas found after Put";
-
-    // Extract actual segment name from replica
-    std::string source_segment;
-    const auto& replica = query_result.value().replicas[0];
-    ASSERT_TRUE(replica.is_memory_replica()) << "Expected memory replica";
-    source_segment =
-        replica.get_memory_descriptor().buffer_descriptor.transport_endpoint_;
-    ASSERT_FALSE(source_segment.empty())
-        << "Failed to extract source segment name";
-
-    // Step 3: Determine target segment dynamically (must be different from
-    // source) Choose the other client's segment as target to ensure source !=
-    // target
-    std::string target_segment;
-    if (source_segment == "127.0.0.1:18001") {
-        target_segment = "127.0.0.1:18002";
-    } else if (source_segment == "127.0.0.1:18002") {
-        target_segment = "127.0.0.1:18001";
-    } else {
-        // If source is neither, default to client2's segment
-        target_segment = "127.0.0.1:18002";
-    }
-
-    // Verify source and target are different - this test only covers
-    // inconsistent cases
-    ASSERT_NE(source_segment, target_segment)
-        << "Source and target segments must be different for this test. "
-        << "Source: " << source_segment << ", Target: " << target_segment;
+    ExpectReplicaEndpoints(test_key, {kClient1Endpoint});
 
-    // Step 4: Create move task via master
-    auto move_result = master_client_->CreateMoveTask(test_key, source_segment,
-                                                      target_segment);
+    // Step 2: Create move task via master
+    auto move_result = master_client_->CreateMoveTask(
+        test_key, kClient1Endpoint, kClient2Endpoint);
     ASSERT_TRUE(move_result.has_value())
         << "Failed to create move task: " << toString(move_result.error());
 
     UUID task_id = move_result.value();
 
-    // Step 5: Get the actual client_id from the task assignment
-    client1_id_ = GetClientIdFromTask(task_id);
-
-    // Step 6: Wait for task to be fetched and executed by the assigned client
+    // Step 3: Wait for task to be fetched and executed by the assigned client
     bool task_completed =
         WaitForTaskCompletion(task_id, std::chrono::seconds(30));
     ASSERT_TRUE(task_completed) << "Task did not complete within timeout";
 
-    // Step 7: Verify move was successful
-    // The replica should now be on client2, not client1
-    auto query_result_client2 = client2_->Query(test_key);
-    ASSERT_TRUE(query_result_client2.has_value())
-        << "Failed to query moved key from client2";
-    ASSERT_FALSE(query_result_client2.value().replicas.empty())
-        << "No replicas found on client2 after move";
+    // Step 4: Move adds the target and removes the source replica.
+    ExpectReplicaEndpoints(test_key, {kClient2Endpoint});
 
-    // Step 8: Verify data integrity
+    // Step 5: Verify data integrity.
     std::vector<uint8_t> read_buffer(test_data.size());
     std::vector<Slice> read_slices;
     read_slices.emplace_back(read_buffer.data(), read_buffer.size());
@@ -532,7 +465,7 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaMoveCompleteFlow) {
     ASSERT_EQ(read_data, test_data) << "Data mismatch after move";
 }
 
-// Test copy to multiple target segments
+// Test complete drain job flow
 TEST_F(TaskExecutorIntegrationTest, DrainJobCompleteFlow) {
     const std::string source_segment = "127.0.0.1:18001";
     const std::string target_segment = "127.0.0.1:18002";
@@ -725,7 +658,8 @@ TEST_F(TaskExecutorIntegrationTest, DrainJobCompleteFlow) {
 }
 
 TEST_F(TaskExecutorIntegrationTest, ReplicaCopyToMultipleTargets) {
-    // Step 1: Put data on client1
+    ASSERT_NO_FATAL_FAILURE(MountThirdClientSegment());
+
     std::string test_key =
         "test_multi_target_copy_key_" +
         std::to_string(
@@ -737,48 +671,17 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaCopyToMultipleTargets) {
     slices.emplace_back(test_data.data(), test_data.size());
     ReplicateConfig config;
     config.replica_num = 1;
+    config.preferred_segment = kClient1Endpoint;
 
     auto put_result = client1_->Put(test_key, slices, config);
     ASSERT_TRUE(put_result.has_value())
         << "Failed to put data: " << toString(put_result.error());
 
     std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    ExpectReplicaEndpoints(test_key, {kClient1Endpoint});
 
-    // Step 2: Get actual source segment
-    auto query_result = client1_->Query(test_key);
-    ASSERT_TRUE(query_result.has_value())
-        << "Failed to query key for verification";
-    ASSERT_FALSE(query_result.value().replicas.empty())
-        << "No replicas found after Put";
-
-    std::string source_segment;
-    const auto& replica = query_result.value().replicas[0];
-    ASSERT_TRUE(replica.is_memory_replica()) << "Expected memory replica";
-    source_segment =
-        replica.get_memory_descriptor().buffer_descriptor.transport_endpoint_;
-    ASSERT_FALSE(source_segment.empty())
-        << "Failed to extract source segment name";
-
-    // Step 3: Determine target segments (both client1 and client2, excluding
-    // source)
-    std::vector<std::string> target_segments;
-    if (source_segment == "127.0.0.1:18001") {
-        target_segments = {"127.0.0.1:18002"};  // Copy to client2 only
-    } else if (source_segment == "127.0.0.1:18002") {
-        target_segments = {"127.0.0.1:18001"};  // Copy to client1 only
-    } else {
-        // If source is neither, use both segments
-        target_segments = {"127.0.0.1:18001", "127.0.0.1:18002"};
-    }
-
-    // Ensure source is not in targets
-    for (const auto& target : target_segments) {
-        ASSERT_NE(source_segment, target)
-            << "Source segment must not be in target segments. "
-            << "Source: " << source_segment << ", Target: " << target;
-    }
-
-    // Step 4: Create copy task with multiple targets
+    const std::vector<std::string> target_segments = {kClient2Endpoint,
+                                                      kClient3Endpoint};
     auto copy_result =
         master_client_->CreateCopyTask(test_key, target_segments);
     ASSERT_TRUE(copy_result.has_value())
@@ -786,51 +689,35 @@ TEST_F(TaskExecutorIntegrationTest, ReplicaCopyToMultipleTargets) {
 
     UUID task_id = copy_result.value();
 
-    // Step 5: Wait for task to complete
     bool task_completed =
         WaitForTaskCompletion(task_id, std::chrono::seconds(30));
     ASSERT_TRUE(task_completed) << "Task did not complete within timeout";
 
-    // Step 6: Verify copy was successful on all target segments
-    for (const auto& target_segment : target_segments) {
-        std::shared_ptr<Client> target_client;
-        if (target_segment == "127.0.0.1:18001") {
-            target_client = client1_;
-        } else {
-            target_client = client2_;
-        }
+    ExpectReplicaEndpoints(
+        test_key, {kClient1Endpoint, kClient2Endpoint, kClient3Endpoint});
 
-        auto target_query_result = target_client->Query(test_key);
-        ASSERT_TRUE(target_query_result.has_value())
-            << "Failed to query copied key from target segment: "
-            << target_segment;
-        ASSERT_FALSE(target_query_result.value().replicas.empty())
-            << "No replicas found on target segment: " << target_segment;
-
-        // Verify data integrity
-        std::vector<uint8_t> read_buffer(test_data.size());
-        std::vector<Slice> read_slices;
-        read_slices.emplace_back(read_buffer.data(), read_buffer.size());
-
-        auto get_result = target_client->Get(test_key, read_slices);
-        ASSERT_TRUE(get_result.has_value())
-            << "Failed to get data from target segment: " << target_segment;
+    std::vector<uint8_t> read_buffer(test_data.size());
+    std::vector<Slice> read_slices;
+    read_slices.emplace_back(read_buffer.data(), read_buffer.size());
+    auto get_result = client1_->Get(test_key, read_slices);
+    ASSERT_TRUE(get_result.has_value())
+        << "Failed to get data after multi-target copy: "
+        << toString(get_result.error());
 
-        std::string read_data(reinterpret_cast<const char*>(read_buffer.data()),
-                              test_data.size());
-        ASSERT_EQ(read_data, test_data)
-            << "Data mismatch on target segment: " << target_segment;
-    }
+    std::string read_data(reinterpret_cast<const char*>(read_buffer.data()),
+                          test_data.size());
+    EXPECT_EQ(read_data, test_data);
 }
 
 // Test multiple copy tasks
 TEST_F(TaskExecutorIntegrationTest, MultipleCopyTasks) {
+    ASSERT_NO_FATAL_FAILURE(MountThirdClientSegment());
+
     const int num_keys = 3;
     std::vector<std::string> keys;
     std::vector<std::string> test_data_list;
     std::vector<UUID> task_ids;
 
-    // Step 1: Put multiple keys on client1
     for (int i = 0; i < num_keys; ++i) {
         std::string key =
             "test_multi_copy_key_" + std::to_string(i) + "_" +
@@ -844,6 +731,7 @@ TEST_F(TaskExecutorIntegrationTest, MultipleCopyTasks) {
         slices.emplace_back(data.data(), data.size());
         ReplicateConfig config;
         config.replica_num = 1;
+        config.preferred_segment = kClient1Endpoint;
 
         auto put_result = client1_->Put(key, slices, config);
         ASSERT_TRUE(put_result.has_value()) << "Failed to put key " << i;
@@ -851,75 +739,18 @@ TEST_F(TaskExecutorIntegrationTest, MultipleCopyTasks) {
 
     std::this_thread::sleep_for(std::chrono::milliseconds(300));
 
-    // Step 2: For each key, determine its source segment and create copy task
-    // with appropriate target Each key may be on a different segment, so we
-    // need to check each one individually
-    for (const auto& key : keys) {
-        // Query to get actual source segment for this key
-        auto query_result = client1_->Query(key);
-        ASSERT_TRUE(query_result.has_value()) << "Failed to query key: " << key;
-        ASSERT_FALSE(query_result.value().replicas.empty())
-            << "No replicas found for key: " << key;
-
-        // Extract actual source segment name from replica
-        std::string source_segment;
-        const auto& replica = query_result.value().replicas[0];
-        ASSERT_TRUE(replica.is_memory_replica())
-            << "Expected memory replica for key: " << key;
-        source_segment = replica.get_memory_descriptor()
-                             .buffer_descriptor.transport_endpoint_;
-        ASSERT_FALSE(source_segment.empty())
-            << "Failed to extract source segment name for key: " << key;
-
-        // Determine target segment dynamically (must be different from source)
-        // Choose the other client's segment as target to ensure source !=
-        // target
-        std::string target_segment;
-        if (source_segment == "127.0.0.1:18001") {
-            target_segment = "127.0.0.1:18002";
-        } else if (source_segment == "127.0.0.1:18002") {
-            target_segment = "127.0.0.1:18001";
-        } else {
-            // If source is neither, default to client2's segment
-            target_segment = "127.0.0.1:18002";
-        }
-
-        // Verify source and target are different - this test only covers
-        // inconsistent cases
-        ASSERT_NE(source_segment, target_segment)
-            << "Source and target segments must be different for key: " << key
-            << ". "
-            << "Source: " << source_segment << ", Target: " << target_segment;
-
-        // Step 3: Create copy task for this key
-        // For the last key, use multiple target segments to test multi-target
-        // copy
-        std::vector<std::string> targets;
-        size_t key_index =
-            task_ids.size();  // Current index before adding this task
-        if (key_index == keys.size() - 1 && keys.size() >= 2) {
-            // Last key: use multiple targets if we have at least 2 clients
-            if (source_segment == "127.0.0.1:18001") {
-                targets = {
-                    "127.0.0.1:18002"};  // Only one other segment available
-            } else if (source_segment == "127.0.0.1:18002") {
-                targets = {
-                    "127.0.0.1:18001"};  // Only one other segment available
-            } else {
-                targets = {"127.0.0.1:18001", "127.0.0.1:18002"};
-            }
-        } else {
-            // Other keys: use single target
-            targets = {target_segment};
-        }
-
-        auto copy_result = master_client_->CreateCopyTask(key, targets);
+    for (size_t i = 0; i < keys.size(); ++i) {
+        ExpectReplicaEndpoints(keys[i], {kClient1Endpoint});
+        const std::vector<std::string> targets =
+            i == keys.size() - 1
+                ? std::vector<std::string>{kClient2Endpoint, kClient3Endpoint}
+                : std::vector<std::string>{kClient2Endpoint};
+        auto copy_result = master_client_->CreateCopyTask(keys[i], targets);
         ASSERT_TRUE(copy_result.has_value())
-            << "Failed to create copy task for " << key;
+            << "Failed to create copy task for " << keys[i];
         task_ids.push_back(copy_result.value());
     }
 
-    // Step 4: Wait for all tasks to complete
     for (size_t i = 0; i < task_ids.size(); ++i) {
         bool completed =
             WaitForTaskCompletion(task_ids[i], std::chrono::seconds(30));
@@ -935,98 +766,24 @@ TEST_F(TaskExecutorIntegrationTest, MultipleCopyTasks) {
             << "Task " << i << " (key: " << keys[i] << ") did not complete";
     }
 
-    // Step 5: Verify all keys are accessible on their target segments
-    // For each key, we need to determine which client should have the replica
     for (size_t i = 0; i < keys.size(); ++i) {
-        // Determine source segment for this key
-        auto query_result = client1_->Query(keys[i]);
-        ASSERT_TRUE(query_result.has_value()) << "Failed to query key " << i;
-        ASSERT_FALSE(query_result.value().replicas.empty())
-            << "No replicas found for key " << i;
-
-        std::string source_segment;
-        const auto& replica = query_result.value().replicas[0];
-        ASSERT_TRUE(replica.is_memory_replica())
-            << "Expected memory replica for key " << i;
-        source_segment = replica.get_memory_descriptor()
-                             .buffer_descriptor.transport_endpoint_;
-
-        // For the last key with multiple targets, verify on all target segments
-        bool is_multi_target = (i == keys.size() - 1 && keys.size() >= 2);
-
-        if (is_multi_target) {
-            // Last key: verify on all target segments
-            std::vector<std::string> target_segments;
-            if (source_segment == "127.0.0.1:18001") {
-                target_segments = {"127.0.0.1:18002"};
-            } else if (source_segment == "127.0.0.1:18002") {
-                target_segments = {"127.0.0.1:18001"};
-            } else {
-                target_segments = {"127.0.0.1:18001", "127.0.0.1:18002"};
-            }
-
-            // Verify on each target segment
-            for (const auto& target_seg : target_segments) {
-                std::shared_ptr<Client> target_client =
-                    (target_seg == "127.0.0.1:18001") ? client1_ : client2_;
-
-                auto target_query = target_client->Query(keys[i]);
-                ASSERT_TRUE(target_query.has_value())
-                    << "Failed to query key " << i
-                    << " from target segment: " << target_seg;
-                ASSERT_FALSE(target_query.value().replicas.empty())
-                    << "No replicas found for key " << i
-                    << " on segment: " << target_seg;
-
-                // Verify data integrity
-                std::vector<uint8_t> read_buffer(test_data_list[i].size());
-                std::vector<Slice> read_slices;
-                read_slices.emplace_back(read_buffer.data(),
-                                         read_buffer.size());
-
-                auto get_result = target_client->Get(keys[i], read_slices);
-                ASSERT_TRUE(get_result.has_value())
-                    << "Failed to get key " << i
-                    << " from target segment: " << target_seg;
-
-                std::string read_data(
-                    reinterpret_cast<const char*>(read_buffer.data()),
-                    test_data_list[i].size());
-                ASSERT_EQ(read_data, test_data_list[i])
-                    << "Data mismatch for key " << i
-                    << " on segment: " << target_seg;
-            }
+        if (i == keys.size() - 1) {
+            ExpectReplicaEndpoints(keys[i], {kClient1Endpoint, kClient2Endpoint,
+                                             kClient3Endpoint});
         } else {
-            // Other keys: verify on single target segment
-            std::shared_ptr<Client> target_client;
-            if (source_segment == "127.0.0.1:18001") {
-                target_client = client2_;  // Copy to client2
-            } else {
-                target_client = client1_;  // Copy to client1
-            }
-
-            // Verify the copied replica is accessible
-            auto query_result_target = target_client->Query(keys[i]);
-            ASSERT_TRUE(query_result_target.has_value())
-                << "Failed to query copied key " << i << " from target client";
-            ASSERT_FALSE(query_result_target.value().replicas.empty())
-                << "No replicas found for copied key " << i;
-
-            // Verify data integrity
-            std::vector<uint8_t> read_buffer(test_data_list[i].size());
-            std::vector<Slice> read_slices;
-            read_slices.emplace_back(read_buffer.data(), read_buffer.size());
-
-            auto get_result = target_client->Get(keys[i], read_slices);
-            ASSERT_TRUE(get_result.has_value())
-                << "Failed to get key " << i << " from target client";
-
-            std::string read_data(
-                reinterpret_cast<const char*>(read_buffer.data()),
-                test_data_list[i].size());
-            ASSERT_EQ(read_data, test_data_list[i])
-                << "Data mismatch for key " << i;
+            ExpectReplicaEndpoints(keys[i],
+                                   {kClient1Endpoint, kClient2Endpoint});
         }
+
+        std::vector<uint8_t> read_buffer(test_data_list[i].size());
+        std::vector<Slice> read_slices;
+        read_slices.emplace_back(read_buffer.data(), read_buffer.size());
+        auto get_result = client1_->Get(keys[i], read_slices);
+        ASSERT_TRUE(get_result.has_value()) << "Failed to get copied key " << i;
+        std::string read_data(reinterpret_cast<const char*>(read_buffer.data()),
+                              test_data_list[i].size());
+        EXPECT_EQ(read_data, test_data_list[i])
+            << "Data mismatch for key " << i;
     }
 }
 
@@ -1051,6 +808,7 @@ TEST_F(TaskExecutorIntegrationTest, MultipleMoveTasks) {
         slices.emplace_back(data.data(), data.size());
         ReplicateConfig config;
         config.replica_num = 1;
+        config.preferred_segment = kClient1Endpoint;
 
         auto put_result = client1_->Put(key, slices, config);
         ASSERT_TRUE(put_result.has_value()) << "Failed to put key " << i;
@@ -1058,47 +816,15 @@ TEST_F(TaskExecutorIntegrationTest, MultipleMoveTasks) {
 
     std::this_thread::sleep_for(std::chrono::milliseconds(300));
 
-    // Step 2: For each key, determine source segment and create move task
     for (const auto& key : keys) {
-        // Query to get actual source segment for this key
-        auto query_result = client1_->Query(key);
-        ASSERT_TRUE(query_result.has_value()) << "Failed to query key: " << key;
-        ASSERT_FALSE(query_result.value().replicas.empty())
-            << "No replicas found for key: " << key;
-
-        std::string source_segment;
-        const auto& replica = query_result.value().replicas[0];
-        ASSERT_TRUE(replica.is_memory_replica())
-            << "Expected memory replica for key: " << key;
-        source_segment = replica.get_memory_descriptor()
-                             .buffer_descriptor.transport_endpoint_;
-        ASSERT_FALSE(source_segment.empty())
-            << "Failed to extract source segment name for key: " << key;
-
-        // Determine target segment (must be different from source)
-        std::string target_segment;
-        if (source_segment == "127.0.0.1:18001") {
-            target_segment = "127.0.0.1:18002";
-        } else if (source_segment == "127.0.0.1:18002") {
-            target_segment = "127.0.0.1:18001";
-        } else {
-            target_segment = "127.0.0.1:18002";
-        }
-
-        ASSERT_NE(source_segment, target_segment)
-            << "Source and target segments must be different for key: " << key
-            << ". "
-            << "Source: " << source_segment << ", Target: " << target_segment;
-
-        // Step 3: Create move task
-        auto move_result =
-            master_client_->CreateMoveTask(key, source_segment, target_segment);
+        ExpectReplicaEndpoints(key, {kClient1Endpoint});
+        auto move_result = master_client_->CreateMoveTask(key, kClient1Endpoint,
+                                                          kClient2Endpoint);
         ASSERT_TRUE(move_result.has_value())
             << "Failed to create move task for " << key;
         task_ids.push_back(move_result.value());
     }
 
-    // Step 4: Wait for all tasks to complete
     for (size_t i = 0; i < task_ids.size(); ++i) {
         bool completed =
             WaitForTaskCompletion(task_ids[i], std::chrono::seconds(30));
@@ -1113,45 +839,15 @@ TEST_F(TaskExecutorIntegrationTest, MultipleMoveTasks) {
             << "Task " << i << " (key: " << keys[i] << ") did not complete";
     }
 
-    // Step 5: Verify all keys are moved to target segments
     for (size_t i = 0; i < keys.size(); ++i) {
-        // Determine target client for this key
-        auto query_result = client1_->Query(keys[i]);
-        ASSERT_TRUE(query_result.has_value()) << "Failed to query key " << i;
-
-        std::string source_segment;
-        if (!query_result.value().replicas.empty()) {
-            const auto& replica = query_result.value().replicas[0];
-            if (replica.is_memory_replica()) {
-                source_segment = replica.get_memory_descriptor()
-                                     .buffer_descriptor.transport_endpoint_;
-            }
-        }
-
-        std::shared_ptr<Client> target_client;
-        if (source_segment == "127.0.0.1:18001" || source_segment.empty()) {
-            // Check client2 (may have moved from client1 or was originally on
-            // client1)
-            target_client = client2_;
-        } else {
-            target_client = client1_;
-        }
+        ExpectReplicaEndpoints(keys[i], {kClient2Endpoint});
 
-        // Verify the moved replica is accessible on target client
-        auto target_query_result = target_client->Query(keys[i]);
-        ASSERT_TRUE(target_query_result.has_value())
-            << "Failed to query moved key " << i << " from target client";
-        ASSERT_FALSE(target_query_result.value().replicas.empty())
-            << "No replicas found for moved key " << i;
-
-        // Verify data integrity
         std::vector<uint8_t> read_buffer(test_data_list[i].size());
         std::vector<Slice> read_slices;
         read_slices.emplace_back(read_buffer.data(), read_buffer.size());
 
-        auto get_result = target_client->Get(keys[i], read_slices);
-        ASSERT_TRUE(get_result.has_value())
-            << "Failed to get moved key " << i << " from target client";
+        auto get_result = client1_->Get(keys[i], read_slices);
+        ASSERT_TRUE(get_result.has_value()) << "Failed to get moved key " << i;
 
         std::string read_data(reinterpret_cast<const char*>(read_buffer.data()),
                               test_data_list[i].size());
@@ -1162,13 +858,13 @@ TEST_F(TaskExecutorIntegrationTest, MultipleMoveTasks) {
 
 // Test concurrent copy and move operations
 TEST_F(TaskExecutorIntegrationTest, ConcurrentCopyAndMoveOperations) {
+    ASSERT_NO_FATAL_FAILURE(MountThirdClientSegment());
+
     const int num_copy_keys = 2;
     const int num_move_keys = 2;
     std::vector<std::string> copy_keys, move_keys;
-    std::vector<std::string> copy_data_list, move_data_list;
     std::vector<UUID> copy_task_ids, move_task_ids;
 
-    // Step 1: Put keys for copy operations
     for (int i = 0; i < num_copy_keys; ++i) {
         std::string key =
             "test_concurrent_copy_key_" + std::to_string(i) + "_" +
@@ -1176,18 +872,17 @@ TEST_F(TaskExecutorIntegrationTest, ConcurrentCopyAndMoveOperations) {
                 std::chrono::steady_clock::now().time_since_epoch().count());
         std::string data = "Copy data " + std::to_string(i);
         copy_keys.push_back(key);
-        copy_data_list.push_back(data);
 
         std::vector<Slice> slices;
         slices.emplace_back(data.data(), data.size());
         ReplicateConfig config;
         config.replica_num = 1;
+        config.preferred_segment = kClient1Endpoint;
 
         auto put_result = client1_->Put(key, slices, config);
         ASSERT_TRUE(put_result.has_value()) << "Failed to put copy key " << i;
     }
 
-    // Step 2: Put keys for move operations
     for (int i = 0; i < num_move_keys; ++i) {
         std::string key =
             "test_concurrent_move_key_" + std::to_string(i) + "_" +
@@ -1195,12 +890,12 @@ TEST_F(TaskExecutorIntegrationTest, ConcurrentCopyAndMoveOperations) {
                 std::chrono::steady_clock::now().time_since_epoch().count());
         std::string data = "Move data " + std::to_string(i);
         move_keys.push_back(key);
-        move_data_list.push_back(data);
 
         std::vector<Slice> slices;
         slices.emplace_back(data.data(), data.size());
         ReplicateConfig config;
         config.replica_num = 1;
+        config.preferred_segment = kClient1Endpoint;
 
         auto put_result = client1_->Put(key, slices, config);
         ASSERT_TRUE(put_result.has_value()) << "Failed to put move key " << i;
@@ -1208,72 +903,28 @@ TEST_F(TaskExecutorIntegrationTest, ConcurrentCopyAndMoveOperations) {
 
     std::this_thread::sleep_for(std::chrono::milliseconds(300));
 
-    // Step 3: Create copy tasks concurrently
-    // Use multiple targets for the first copy task to test multi-target copy
-    for (size_t idx = 0; idx < copy_keys.size(); ++idx) {
-        const auto& key = copy_keys[idx];
-        auto query_result = client1_->Query(key);
-        ASSERT_TRUE(query_result.has_value())
-            << "Failed to query copy key: " << key;
-        ASSERT_FALSE(query_result.value().replicas.empty());
-
-        std::string source_segment;
-        const auto& replica = query_result.value().replicas[0];
-        ASSERT_TRUE(replica.is_memory_replica());
-        source_segment = replica.get_memory_descriptor()
-                             .buffer_descriptor.transport_endpoint_;
-
-        std::vector<std::string> targets;
-        if (idx == 0 && copy_keys.size() >= 1) {
-            // First copy task: use multiple targets
-            if (source_segment == "127.0.0.1:18001") {
-                targets = {
-                    "127.0.0.1:18002"};  // Only one other segment available
-            } else if (source_segment == "127.0.0.1:18002") {
-                targets = {
-                    "127.0.0.1:18001"};  // Only one other segment available
-            } else {
-                targets = {"127.0.0.1:18001", "127.0.0.1:18002"};
-            }
-        } else {
-            // Other copy tasks: use single target
-            std::string target_segment = (source_segment == "127.0.0.1:18001")
-                                             ? "127.0.0.1:18002"
-                                             : "127.0.0.1:18001";
-            targets = {target_segment};
-        }
-
-        auto copy_result = master_client_->CreateCopyTask(key, targets);
+    for (size_t i = 0; i < copy_keys.size(); ++i) {
+        ExpectReplicaEndpoints(copy_keys[i], {kClient1Endpoint});
+        const std::vector<std::string> targets =
+            i == 0
+                ? std::vector<std::string>{kClient2Endpoint, kClient3Endpoint}
+                : std::vector<std::string>{kClient2Endpoint};
+        auto copy_result =
+            master_client_->CreateCopyTask(copy_keys[i], targets);
         ASSERT_TRUE(copy_result.has_value())
-            << "Failed to create copy task for " << key;
+            << "Failed to create copy task for " << copy_keys[i];
         copy_task_ids.push_back(copy_result.value());
     }
 
-    // Step 4: Create move tasks concurrently
     for (const auto& key : move_keys) {
-        auto query_result = client1_->Query(key);
-        ASSERT_TRUE(query_result.has_value())
-            << "Failed to query move key: " << key;
-        ASSERT_FALSE(query_result.value().replicas.empty());
-
-        std::string source_segment;
-        const auto& replica = query_result.value().replicas[0];
-        ASSERT_TRUE(replica.is_memory_replica());
-        source_segment = replica.get_memory_descriptor()
-                             .buffer_descriptor.transport_endpoint_;
-
-        std::string target_segment = (source_segment == "127.0.0.1:18001")
-                                         ? "127.0.0.1:18002"
-                                         : "127.0.0.1:18001";
-
-        auto move_result =
-            master_client_->CreateMoveTask(key, source_segment, target_segment);
+        ExpectReplicaEndpoints(key, {kClient1Endpoint});
+        auto move_result = master_client_->CreateMoveTask(key, kClient1Endpoint,
+                                                          kClient2Endpoint);
         ASSERT_TRUE(move_result.has_value())
             << "Failed to create move task for " << key;
         move_task_ids.push_back(move_result.value());
     }
 
-    // Step 5: Wait for all tasks to complete
     for (size_t i = 0; i < copy_task_ids.size(); ++i) {
         bool completed =
             WaitForTaskCompletion(copy_task_ids[i], std::chrono::seconds(30));
@@ -1288,83 +939,19 @@ TEST_F(TaskExecutorIntegrationTest, ConcurrentCopyAndMoveOperations) {
                                << ") did not complete";
     }
 
-    // Step 6: Verify copy results
     for (size_t i = 0; i < copy_keys.size(); ++i) {
-        auto query_result = client1_->Query(copy_keys[i]);
-        ASSERT_TRUE(query_result.has_value());
-
-        std::string source_segment;
-        if (!query_result.value().replicas.empty()) {
-            const auto& replica = query_result.value().replicas[0];
-            if (replica.is_memory_replica()) {
-                source_segment = replica.get_memory_descriptor()
-                                     .buffer_descriptor.transport_endpoint_;
-            }
-        }
-
-        // First copy task uses multiple targets
-        bool is_multi_target = (i == 0 && copy_keys.size() >= 1);
-
-        if (is_multi_target) {
-            // Verify on all target segments
-            std::vector<std::string> target_segments;
-            if (source_segment == "127.0.0.1:18001") {
-                target_segments = {"127.0.0.1:18002"};
-            } else if (source_segment == "127.0.0.1:18002") {
-                target_segments = {"127.0.0.1:18001"};
-            } else {
-                target_segments = {"127.0.0.1:18001", "127.0.0.1:18002"};
-            }
-
-            for (const auto& target_seg : target_segments) {
-                std::shared_ptr<Client> target_client =
-                    (target_seg == "127.0.0.1:18001") ? client1_ : client2_;
-
-                auto target_query = target_client->Query(copy_keys[i]);
-                ASSERT_TRUE(target_query.has_value())
-                    << "Copy key " << i
-                    << " not found on target segment: " << target_seg;
-                ASSERT_FALSE(target_query.value().replicas.empty())
-                    << "No replicas for copy key " << i
-                    << " on segment: " << target_seg;
-            }
+        if (i == 0) {
+            ExpectReplicaEndpoints(
+                copy_keys[i],
+                {kClient1Endpoint, kClient2Endpoint, kClient3Endpoint});
         } else {
-            // Verify on single target segment
-            std::shared_ptr<Client> target_client =
-                (source_segment == "127.0.0.1:18001") ? client2_ : client1_;
-
-            auto target_query = target_client->Query(copy_keys[i]);
-            ASSERT_TRUE(target_query.has_value())
-                << "Copy key " << i << " not found on target";
-            ASSERT_FALSE(target_query.value().replicas.empty())
-                << "No replicas for copy key " << i;
+            ExpectReplicaEndpoints(copy_keys[i],
+                                   {kClient1Endpoint, kClient2Endpoint});
         }
     }
 
-    // Step 7: Verify move results
-    for (size_t i = 0; i < move_keys.size(); ++i) {
-        auto query_result = client1_->Query(move_keys[i]);
-
-        std::string source_segment;
-        if (query_result.has_value() &&
-            !query_result.value().replicas.empty()) {
-            const auto& replica = query_result.value().replicas[0];
-            if (replica.is_memory_replica()) {
-                source_segment = replica.get_memory_descriptor()
-                                     .buffer_descriptor.transport_endpoint_;
-            }
-        }
-
-        std::shared_ptr<Client> target_client =
-            (source_segment == "127.0.0.1:18001" || source_segment.empty())
-                ? client2_
-                : client1_;
-
-        auto target_query = target_client->Query(move_keys[i]);
-        ASSERT_TRUE(target_query.has_value())
-            << "Move key " << i << " not found on target";
-        ASSERT_FALSE(target_query.value().replicas.empty())
-            << "No replicas for move key " << i;
+    for (const auto& key : move_keys) {
+        ExpectReplicaEndpoints(key, {kClient2Endpoint});
     }
 }
 
diff --git a/mooncake-store/tests/task_manager_test.cpp b/mooncake-store/tests/task_manager_test.cpp
index 663a414436..0c0fd3d4dd 100644
--- a/mooncake-store/tests/task_manager_test.cpp
+++ b/mooncake-store/tests/task_manager_test.cpp
@@ -415,4 +415,25 @@ TEST_F(ClientTaskManagerTest, SerializerReset) {
     auto tasks = manager.get_read_access();
     EXPECT_EQ(tasks.size(), 0u);
 }
+
+TEST_F(ClientTaskManagerTest, FailPendingTaskSkipsQueuedAssignment) {
+    ClientTaskManager manager({10000, 10000, 10000, 0, 0, 3});
+    UUID client_id = generate_uuid();
+
+    auto task_id =
+        manager.get_write_access().submit_task_typed<TaskType::REPLICA_COPY>(
+            client_id, ReplicaCopyPayload{.tenant_id = "default",
+                                          .key = "failed-pending-key",
+                                          .source = "source",
+                                          .targets = {"target"}});
+    ASSERT_TRUE(task_id.has_value());
+
+    auto fail_result = manager.get_write_access().fail_task_if_pending(
+        *task_id, "test failure");
+    EXPECT_EQ(fail_result, ErrorCode::OK);
+
+    auto tasks = manager.get_write_access().pop_tasks(client_id, 10);
+    EXPECT_TRUE(tasks.empty());
+}
+
 }  // namespace mooncake
diff --git a/mooncake-store/tests/tenant_quota_ledger_test.cpp b/mooncake-store/tests/tenant_quota_ledger_test.cpp
new file mode 100644
index 0000000000..9ebdc1af02
--- /dev/null
+++ b/mooncake-store/tests/tenant_quota_ledger_test.cpp
@@ -0,0 +1,219 @@
+#include "tenant_quota_ledger.h"
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace {
+
+class TenantQuotaLedgerTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        ASSERT_TRUE(table_.UpsertTenantPolicy(
+            tenant_id_, TenantQuotaAccount::kMaxChargedBytes));
+        table_.RecomputeEffectiveQuotas(TenantQuotaAccount::kMaxChargedBytes);
+        account_ = table_.GetOrCreateTenantHandle(tenant_id_);
+    }
+
+    void Charge(uint64_t bytes) { ASSERT_TRUE(account_->TryCharge(bytes)); }
+
+    const TenantId tenant_id_{"ledger-test"};
+    TenantQuotaTable table_;
+    TenantQuotaHandle account_{nullptr};
+};
+
+TEST_F(TenantQuotaLedgerTest, PendingFullyCommits) {
+    TenantQuotaLedger ledger;
+    Charge(100);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 100));
+
+    EXPECT_TRUE(ledger.SettlePrimaryWrite(account_, 100));
+    EXPECT_EQ(ledger.PendingBytes(), 0);
+    EXPECT_EQ(ledger.CommittedBytes(), 100);
+    EXPECT_EQ(ledger.TotalChargedBytes(), 100);
+    EXPECT_EQ(account_->ChargedBytes(), 100);
+}
+
+TEST_F(TenantQuotaLedgerTest, PendingPartiallyCommits) {
+    TenantQuotaLedger ledger;
+    Charge(100);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 100));
+
+    EXPECT_TRUE(ledger.SettlePrimaryWrite(account_, 60));
+    EXPECT_EQ(ledger.PendingBytes(), 0);
+    EXPECT_EQ(ledger.CommittedBytes(), 60);
+    EXPECT_EQ(account_->ChargedBytes(), 60);
+}
+
+TEST_F(TenantQuotaLedgerTest, PendingFullyRefunds) {
+    TenantQuotaLedger ledger;
+    Charge(100);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 100));
+
+    EXPECT_TRUE(ledger.RefundPending(account_));
+    EXPECT_EQ(ledger.TotalChargedBytes(), 0);
+    EXPECT_EQ(account_->ChargedBytes(), 0);
+}
+
+TEST_F(TenantQuotaLedgerTest, SettlesAdditionalCharge) {
+    TenantQuotaLedger ledger;
+    Charge(40);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 40));
+    ASSERT_TRUE(ledger.SettlePrimaryWrite(account_, 40));
+    Charge(60);
+    uint64_t task_pending_bytes = 60;
+
+    EXPECT_TRUE(ledger.SettleAdditional(account_, task_pending_bytes, 35));
+    EXPECT_EQ(task_pending_bytes, 60);
+    EXPECT_EQ(ledger.CommittedBytes(), 75);
+    EXPECT_EQ(account_->ChargedBytes(), 75);
+}
+
+TEST_F(TenantQuotaLedgerTest, ReleasesCommittedBytesPartially) {
+    TenantQuotaLedger ledger;
+    Charge(100);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 100));
+    ASSERT_TRUE(ledger.SettlePrimaryWrite(account_, 100));
+
+    EXPECT_TRUE(ledger.ReleaseCommitted(account_, 40));
+    EXPECT_EQ(ledger.CommittedBytes(), 60);
+    EXPECT_EQ(account_->ChargedBytes(), 60);
+}
+
+TEST_F(TenantQuotaLedgerTest, PrimaryWriteSettlementReleasesReplacementCharge) {
+    TenantQuotaLedger old_ledger;
+    TenantQuotaLedger replacement_owner;
+    TenantQuotaLedger new_ledger;
+    Charge(80);
+    ASSERT_TRUE(old_ledger.AdoptPendingCharge(account_, 80));
+    ASSERT_TRUE(old_ledger.SettlePrimaryWrite(account_, 80));
+    Charge(120);
+    ASSERT_TRUE(new_ledger.AdoptPendingCharge(account_, 120));
+
+    ASSERT_TRUE(
+        old_ledger.TransferReplacementCharge(account_, replacement_owner));
+    ASSERT_TRUE(
+        replacement_owner.TransferReplacementCharge(account_, new_ledger));
+    ASSERT_TRUE(new_ledger.SettlePrimaryWrite(account_, 100));
+    EXPECT_EQ(new_ledger.PendingBytes(), 0);
+    EXPECT_EQ(new_ledger.CommittedBytes(), 100);
+    EXPECT_EQ(new_ledger.ReplacedBytes(), 0);
+    EXPECT_EQ(new_ledger.TotalChargedBytes(), 100);
+    EXPECT_EQ(account_->ChargedBytes(), 100);
+}
+
+TEST_F(TenantQuotaLedgerTest,
+       PrimaryWriteMismatchPreservesPendingAndReplacementCharge) {
+    TenantQuotaLedger old_ledger;
+    TenantQuotaLedger new_ledger;
+    Charge(30);
+    ASSERT_TRUE(old_ledger.AdoptPendingCharge(account_, 30));
+    ASSERT_TRUE(old_ledger.SettlePrimaryWrite(account_, 30));
+    ASSERT_TRUE(old_ledger.TransferReplacementCharge(account_, new_ledger));
+    Charge(70);
+    ASSERT_TRUE(new_ledger.AdoptPendingCharge(account_, 70));
+
+    auto settle_result = new_ledger.SettlePrimaryWrite(account_, 80);
+
+    ASSERT_FALSE(settle_result);
+    EXPECT_EQ(settle_result.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(new_ledger.PendingBytes(), 70);
+    EXPECT_EQ(new_ledger.CommittedBytes(), 0);
+    EXPECT_EQ(new_ledger.ReplacedBytes(), 30);
+    EXPECT_EQ(new_ledger.TotalChargedBytes(), 100);
+    EXPECT_EQ(account_->ChargedBytes(), 100);
+
+    ASSERT_TRUE(account_->Release(80));
+    auto account_mismatch = new_ledger.SettlePrimaryWrite(account_, 50);
+    ASSERT_FALSE(account_mismatch);
+    EXPECT_EQ(account_mismatch.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(new_ledger.PendingBytes(), 70);
+    EXPECT_EQ(new_ledger.CommittedBytes(), 0);
+    EXPECT_EQ(new_ledger.ReplacedBytes(), 30);
+    EXPECT_EQ(new_ledger.TotalChargedBytes(), 100);
+    EXPECT_EQ(account_->ChargedBytes(), 20);
+}
+
+TEST_F(TenantQuotaLedgerTest, RollsBackReplacementChargeOnFailure) {
+    TenantQuotaLedger old_ledger;
+    TenantQuotaLedger replacement_owner;
+    Charge(80);
+    ASSERT_TRUE(old_ledger.AdoptPendingCharge(account_, 80));
+    ASSERT_TRUE(old_ledger.SettlePrimaryWrite(account_, 80));
+    ASSERT_TRUE(
+        old_ledger.TransferReplacementCharge(account_, replacement_owner));
+
+    EXPECT_TRUE(replacement_owner.ReleaseReplacement(account_));
+    EXPECT_EQ(replacement_owner.TotalChargedBytes(), 0);
+    EXPECT_EQ(account_->ChargedBytes(), 0);
+}
+
+TEST_F(TenantQuotaLedgerTest, AccountingMismatchDoesNotMutateState) {
+    TenantQuotaLedger ledger;
+    Charge(50);
+    ASSERT_TRUE(ledger.AdoptPendingCharge(account_, 50));
+
+    auto settle_result = ledger.SettlePrimaryWrite(account_, 51);
+    ASSERT_FALSE(settle_result);
+    EXPECT_EQ(settle_result.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(ledger.PendingBytes(), 50);
+    EXPECT_EQ(account_->ChargedBytes(), 50);
+
+    ASSERT_TRUE(ledger.SettlePrimaryWrite(account_, 50));
+    auto release_result = ledger.ReleaseCommitted(account_, 51);
+    ASSERT_FALSE(release_result);
+    EXPECT_EQ(release_result.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(ledger.CommittedBytes(), 50);
+    EXPECT_EQ(account_->ChargedBytes(), 50);
+
+    ASSERT_TRUE(ledger.ReleaseAll(account_));
+    auto duplicate_release_all = ledger.ReleaseAll(account_);
+    ASSERT_FALSE(duplicate_release_all);
+    EXPECT_EQ(duplicate_release_all.error(),
+              TenantQuotaError::kAccountingMismatch);
+
+    TenantQuotaLedger inconsistent_ledger;
+    ASSERT_TRUE(inconsistent_ledger.Rebuild(account_, 10));
+    auto account_mismatch = inconsistent_ledger.ReleaseCommitted(account_, 10);
+    ASSERT_FALSE(account_mismatch);
+    EXPECT_EQ(account_mismatch.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(inconsistent_ledger.CommittedBytes(), 10);
+    EXPECT_EQ(account_->ChargedBytes(), 0);
+}
+
+TEST_F(TenantQuotaLedgerTest, DuplicateReplacementOperationsAreRejected) {
+    TenantQuotaLedger source;
+    TenantQuotaLedger destination;
+    Charge(30);
+    ASSERT_TRUE(source.AdoptPendingCharge(account_, 30));
+    ASSERT_TRUE(source.SettlePrimaryWrite(account_, 30));
+    ASSERT_TRUE(source.TransferReplacementCharge(account_, destination));
+
+    auto duplicate_transfer =
+        source.TransferReplacementCharge(account_, destination);
+    ASSERT_FALSE(duplicate_transfer);
+    EXPECT_EQ(duplicate_transfer.error(),
+              TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(destination.ReplacedBytes(), 30);
+    EXPECT_EQ(account_->ChargedBytes(), 30);
+
+    ASSERT_TRUE(destination.ReleaseReplacement(account_));
+    auto duplicate_release = destination.ReleaseReplacement(account_);
+    ASSERT_FALSE(duplicate_release);
+    EXPECT_EQ(duplicate_release.error(), TenantQuotaError::kAccountingMismatch);
+    EXPECT_EQ(destination.TotalChargedBytes(), 0);
+    EXPECT_EQ(account_->ChargedBytes(), 0);
+}
+
+TEST_F(TenantQuotaLedgerTest, RebuildMatchesGlobalChargedBytes) {
+    TenantQuotaLedger ledger;
+    ASSERT_TRUE(ledger.Rebuild(account_, 90));
+    ASSERT_TRUE(table_.RebuildUsage({{tenant_id_, 90}}));
+
+    EXPECT_EQ(ledger.PendingBytes(), 0);
+    EXPECT_EQ(ledger.CommittedBytes(), 90);
+    EXPECT_EQ(ledger.ReplacedBytes(), 0);
+    EXPECT_EQ(ledger.TotalChargedBytes(), account_->ChargedBytes());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/tenant_quota_test.cpp b/mooncake-store/tests/tenant_quota_test.cpp
index e88b9d90e6..eca64238a0 100644
--- a/mooncake-store/tests/tenant_quota_test.cpp
+++ b/mooncake-store/tests/tenant_quota_test.cpp
@@ -105,9 +105,10 @@ void MakeOrphanTenant(TenantQuotaTable* table, const std::string& tenant_id,
     const TenantId canonical_tenant(tenant_id);
     ASSERT_TRUE(table->UpsertTenantPolicy(canonical_tenant, bytes).has_value());
     table->RecomputeEffectiveQuotas(bytes);
-    ASSERT_TRUE(table->Reserve(canonical_tenant, bytes).has_value());
-    ASSERT_TRUE(table->Commit(canonical_tenant, bytes).has_value());
-    table->ApplyTenantPolicies({});
+    ASSERT_TRUE(table->GetOrCreateTenantHandle(canonical_tenant)
+                    ->TryCharge(bytes)
+                    .has_value());
+    ASSERT_TRUE(table->ApplyTenantPolicies({}));
 }
 
 TEST(TenantQuotaTableTest, NormalizesEmptyExplicitTenantIdToDefault) {
@@ -137,6 +138,23 @@ TEST(TenantQuotaTableTest, RejectsZeroExplicitQuotaWithoutChangingState) {
     EXPECT_EQ(snapshot.requested_quota_bytes, 100);
 }
 
+TEST(TenantQuotaTableTest, RejectsPolicyAboveAtomicAccountingRange) {
+    TenantQuotaTable table;
+    const TenantId tenant_id("tenant-a");
+    ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 100));
+
+    auto upsert = table.UpsertTenantPolicy(
+        tenant_id, TenantQuotaAccount::kMaxChargedBytes + 1);
+    auto replace = table.ApplyTenantPolicies(
+        {{tenant_id, TenantQuotaAccount::kMaxChargedBytes + 1}});
+
+    ASSERT_FALSE(upsert);
+    EXPECT_EQ(upsert.error(), TenantQuotaError::kInvalidArgument);
+    ASSERT_FALSE(replace);
+    EXPECT_EQ(replace.error(), TenantQuotaError::kInvalidArgument);
+    EXPECT_EQ(Snapshot(table, "tenant-a").requested_quota_bytes, 100);
+}
+
 TEST(TenantQuotaTableTest, ApplyPoliciesCreatesOrphanState) {
     TenantQuotaTable table;
     MakeOrphanTenant(&table, "tenant-a", 40);
@@ -146,18 +164,32 @@ TEST(TenantQuotaTableTest, ApplyPoliciesCreatesOrphanState) {
     EXPECT_FALSE(snapshot.has_explicit_policy);
     EXPECT_EQ(snapshot.requested_quota_bytes, 0);
     EXPECT_EQ(snapshot.effective_quota_bytes, 0);
-    EXPECT_EQ(snapshot.used_bytes, 40);
-    EXPECT_EQ(snapshot.committed_count, 1);
+    EXPECT_EQ(snapshot.charged_bytes, 40);
+    EXPECT_TRUE(snapshot.admission_closed);
     EXPECT_TRUE(snapshot.over_quota);
 }
 
+TEST(TenantQuotaTableTest, ClosedOrphanAccountCanDrain) {
+    TenantQuotaTable table;
+    const TenantId tenant_id("tenant-a");
+    MakeOrphanTenant(&table, tenant_id.value(), 40);
+    auto* handle = table.GetOrCreateTenantHandle(tenant_id);
+
+    ASSERT_TRUE(handle->Release(40));
+
+    EXPECT_EQ(handle->ChargedBytes(), 0);
+    EXPECT_TRUE(handle->AdmissionClosed());
+    EXPECT_FALSE(table.GetTenantSnapshot(tenant_id).has_value());
+}
+
 TEST(TenantQuotaTableTest, ApplyPoliciesReplacesCanonicalPolicySet) {
     TenantQuotaTable table;
     const TenantId tenant_a("tenant-a");
     const TenantId tenant_b("tenant-b");
     const TenantId tenant_c("tenant-c");
     table.ApplyTenantPolicies({{tenant_a, 100}, {tenant_b, 200}});
-    table.IncrementMetadataObjectCount(tenant_a);
+    table.RecomputeEffectiveQuotas(300);
+    ASSERT_TRUE(table.GetOrCreateTenantHandle(tenant_a)->TryCharge(1));
 
     table.ApplyTenantPolicies({{tenant_b, 300}, {tenant_c, 400}});
 
@@ -189,9 +221,11 @@ TEST(TenantQuotaTableTest, PolicyMutationDoesNotRecomputeEffectiveQuota) {
 
     ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 200).has_value());
     EXPECT_EQ(Snapshot(table, "tenant-a").effective_quota_bytes, 100);
+    EXPECT_TRUE(Snapshot(table, "tenant-a").admission_closed);
 
     table.RecomputeEffectiveQuotas(1000);
     EXPECT_EQ(Snapshot(table, "tenant-a").effective_quota_bytes, 200);
+    EXPECT_FALSE(Snapshot(table, "tenant-a").admission_closed);
 }
 
 TEST(TenantQuotaTableTest, ListSnapshotsSortedAndCleansLazyEmptyTenants) {
@@ -254,34 +288,32 @@ TEST(TenantQuotaTableTest, LazyEmptyOrphansDoNotAppearInList) {
     EXPECT_EQ(snapshots[0].tenant_id, TenantId("team-a"));
 }
 
-TEST(TenantQuotaTableTest, ReserveRequiresRegisteredTenantIncludingZeroBytes) {
+TEST(TenantQuotaTableTest, ChargeRequiresRegisteredTenantIncludingZeroBytes) {
     TenantQuotaTable table;
+    auto* account = table.GetOrCreateTenantHandle(TenantId("missing"));
 
-    auto regular = table.Reserve(TenantId("missing"), 1);
-    auto zero = table.Reserve(TenantId("missing"), 0);
+    auto regular = account->TryCharge(1);
+    auto zero = account->TryCharge(0);
 
     ASSERT_FALSE(regular.has_value());
     ASSERT_FALSE(zero.has_value());
-    EXPECT_EQ(regular.error(), TenantQuotaError::kTenantNotRegistered);
-    EXPECT_EQ(zero.error(), TenantQuotaError::kTenantNotRegistered);
+    EXPECT_EQ(regular.error().error, TenantQuotaError::kTenantNotRegistered);
+    EXPECT_EQ(zero.error().error, TenantQuotaError::kTenantNotRegistered);
 }
 
-TEST(TenantQuotaTableTest, TracksAdditionalCommitAndMetadataCount) {
+TEST(TenantQuotaTableTest, ChargeAndReleaseUpdateSingleCounter) {
     TenantQuotaTable table;
     const TenantId tenant_id("tenant-a");
     ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 300).has_value());
     table.RecomputeEffectiveQuotas(300);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
 
-    ASSERT_TRUE(table.Reserve(tenant_id, 200).has_value());
-    ASSERT_TRUE(table.Commit(tenant_id, 100).has_value());
-    ASSERT_TRUE(table.CommitAdditional(tenant_id, 100).has_value());
-    table.IncrementMetadataObjectCount(tenant_id);
+    ASSERT_TRUE(account->TryCharge(200).has_value());
+    ASSERT_TRUE(account->Release(50).has_value());
 
     auto snapshot = Snapshot(table, "tenant-a");
-    EXPECT_EQ(snapshot.used_bytes, 200);
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
-    EXPECT_EQ(snapshot.committed_count, 1);
-    EXPECT_EQ(snapshot.metadata_object_count, 1);
+    EXPECT_EQ(snapshot.charged_bytes, 150);
+    EXPECT_FALSE(snapshot.admission_closed);
 }
 
 TEST(TenantQuotaTableTest, AccountingMismatchDoesNotMutateState) {
@@ -289,40 +321,13 @@ TEST(TenantQuotaTableTest, AccountingMismatchDoesNotMutateState) {
     const TenantId tenant_id("tenant-a");
     ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 100).has_value());
     table.RecomputeEffectiveQuotas(100);
-    ASSERT_TRUE(table.Reserve(tenant_id, 10).has_value());
-
-    auto commit = table.Commit(tenant_id, 11);
-    auto abort = table.Abort(tenant_id, 11);
-    auto before_commit = Snapshot(table, "tenant-a");
-    ASSERT_FALSE(commit.has_value());
-    ASSERT_FALSE(abort.has_value());
-    EXPECT_EQ(commit.error(), TenantQuotaError::kAccountingMismatch);
-    EXPECT_EQ(abort.error(), TenantQuotaError::kAccountingMismatch);
-    EXPECT_EQ(before_commit.used_bytes, 0);
-    EXPECT_EQ(before_commit.reserved_bytes, 10);
-
-    ASSERT_TRUE(table.Commit(tenant_id, 10).has_value());
-    auto release = table.Release(tenant_id, 11);
-    auto partial = table.ReleasePartial(tenant_id, 11);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
+    ASSERT_TRUE(account->TryCharge(10).has_value());
+
+    auto release = account->Release(11);
     ASSERT_FALSE(release.has_value());
-    ASSERT_FALSE(partial.has_value());
     EXPECT_EQ(release.error(), TenantQuotaError::kAccountingMismatch);
-    EXPECT_EQ(partial.error(), TenantQuotaError::kAccountingMismatch);
-    auto after_commit = Snapshot(table, "tenant-a");
-    EXPECT_EQ(after_commit.used_bytes, 10);
-    EXPECT_EQ(after_commit.committed_count, 1);
-
-    table.RebuildUsage({{tenant_id,
-                         {.used_bytes = 10,
-                          .committed_count = 0,
-                          .metadata_object_count = 1}}});
-    auto inconsistent_release = table.Release(tenant_id, 5);
-    ASSERT_FALSE(inconsistent_release.has_value());
-    EXPECT_EQ(inconsistent_release.error(),
-              TenantQuotaError::kAccountingMismatch);
-    auto after_inconsistent_release = Snapshot(table, "tenant-a");
-    EXPECT_EQ(after_inconsistent_release.used_bytes, 10);
-    EXPECT_EQ(after_inconsistent_release.committed_count, 0);
+    EXPECT_EQ(Snapshot(table, "tenant-a").charged_bytes, 10);
 }
 
 TEST(TenantQuotaTableTest, DisablePolicyRejectsNonEmptyTenant) {
@@ -330,13 +335,36 @@ TEST(TenantQuotaTableTest, DisablePolicyRejectsNonEmptyTenant) {
     const TenantId tenant_id("tenant-a");
     ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 100).has_value());
     table.RecomputeEffectiveQuotas(100);
-    ASSERT_TRUE(table.Reserve(tenant_id, 1).has_value());
+    ASSERT_TRUE(
+        table.GetOrCreateTenantHandle(tenant_id)->TryCharge(1).has_value());
 
     auto result = table.DisableTenantPolicyIfEmpty(tenant_id);
 
     ASSERT_FALSE(result.has_value());
     EXPECT_EQ(result.error(), TenantQuotaError::kTenantNotEmpty);
     EXPECT_TRUE(table.IsTenantRegistered(tenant_id));
+    EXPECT_FALSE(Snapshot(table, "tenant-a").admission_closed);
+    EXPECT_TRUE(table.GetOrCreateTenantHandle(tenant_id)->TryCharge(1));
+}
+
+TEST(TenantQuotaTableTest, HandleRemainsStableAcrossPolicyLifecycle) {
+    TenantQuotaTable table;
+    const TenantId tenant_id("tenant-a");
+    ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 100));
+    table.RecomputeEffectiveQuotas(100);
+    auto* handle = table.GetOrCreateTenantHandle(tenant_id);
+
+    ASSERT_TRUE(handle->TryCharge(10));
+    ASSERT_TRUE(handle->Release(10));
+    ASSERT_TRUE(table.DisableTenantPolicyIfEmpty(tenant_id));
+    EXPECT_FALSE(handle->TryCharge(0));
+    EXPECT_FALSE(table.GetTenantSnapshot(tenant_id).has_value());
+
+    ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, 200));
+    table.RecomputeEffectiveQuotas(200);
+    EXPECT_EQ(table.GetOrCreateTenantHandle(tenant_id), handle);
+    EXPECT_TRUE(handle->TryCharge(200));
+    EXPECT_EQ(Snapshot(table, "tenant-a").charged_bytes, 200);
 }
 
 TEST(TenantQuotaTableTest, RebuildUsageCreatesAndRemovesOrphans) {
@@ -346,19 +374,17 @@ TEST(TenantQuotaTableTest, RebuildUsageCreatesAndRemovesOrphans) {
     ASSERT_TRUE(table.UpsertTenantPolicy(explicit_tenant, 100).has_value());
 
     TenantQuotaUsageMap usage{
-        {explicit_tenant,
-         {.used_bytes = 40, .committed_count = 1, .metadata_object_count = 1}},
-        {orphan,
-         {.used_bytes = 20, .committed_count = 1, .metadata_object_count = 1}},
+        {explicit_tenant, 40},
+        {orphan, 20},
     };
-    table.RebuildUsage(usage);
+    ASSERT_TRUE(table.RebuildUsage(usage));
     table.RecomputeEffectiveQuotas(100);
 
     EXPECT_TRUE(Snapshot(table, "tenant-a").has_explicit_policy);
     EXPECT_FALSE(Snapshot(table, "orphan").has_explicit_policy);
     EXPECT_TRUE(Snapshot(table, "orphan").over_quota);
 
-    table.RebuildUsage({});
+    ASSERT_TRUE(table.RebuildUsage({}));
     EXPECT_FALSE(table.GetTenantSnapshot(orphan).has_value());
     EXPECT_TRUE(table.GetTenantSnapshot(explicit_tenant).has_value());
 }
@@ -366,40 +392,34 @@ TEST(TenantQuotaTableTest, RebuildUsageCreatesAndRemovesOrphans) {
 TEST(TenantQuotaTableTest, OverflowChecksDoNotWrapAccounting) {
     TenantQuotaTable table;
     const TenantId tenant_id("tenant-a");
-    const uint64_t max = std::numeric_limits<uint64_t>::max();
+    const uint64_t max = TenantQuotaAccount::kMaxChargedBytes;
     ASSERT_TRUE(table.UpsertTenantPolicy(tenant_id, max).has_value());
-    table.RebuildUsage({{tenant_id,
-                         {.used_bytes = max - 5,
-                          .committed_count = max,
-                          .metadata_object_count = max}}});
+    ASSERT_TRUE(table.RebuildUsage({{tenant_id, max - 5}}));
     table.RecomputeEffectiveQuotas(max);
 
-    EXPECT_EQ(table.ComputeDeficit(tenant_id, 10), 5);
-    auto overflow_reserve = table.Reserve(tenant_id, 10);
-    ASSERT_FALSE(overflow_reserve.has_value());
-    EXPECT_EQ(overflow_reserve.error(), TenantQuotaError::kQuotaExceeded);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
+    auto overflow_charge = account->TryCharge(10);
+    ASSERT_FALSE(overflow_charge.has_value());
+    EXPECT_EQ(overflow_charge.error().error, TenantQuotaError::kQuotaExceeded);
+    EXPECT_EQ(overflow_charge.error().deficit_bytes, 5);
 
-    ASSERT_TRUE(table.Reserve(tenant_id, 5).has_value());
-    ASSERT_TRUE(table.Commit(tenant_id, 5).has_value());
-    table.IncrementMetadataObjectCount(tenant_id);
+    ASSERT_TRUE(account->TryCharge(5).has_value());
 
     auto snapshot = Snapshot(table, "tenant-a");
-    EXPECT_EQ(snapshot.used_bytes, max);
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
-    EXPECT_EQ(snapshot.committed_count, max);
-    EXPECT_EQ(snapshot.metadata_object_count, max);
+    EXPECT_EQ(snapshot.charged_bytes, max);
 }
 
-TEST(ShardedTenantQuotaTableTest, ConcurrentReserveNeverExceedsQuota) {
+TEST(ShardedTenantQuotaTableTest, ConcurrentChargeNeverExceedsQuota) {
     ShardedTenantQuotaTable<8> table;
     const TenantId tenant_id("tenant-a");
     table.ApplyTenantPolicies({{tenant_id, 1000}}, 1000);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
 
     std::atomic<int> successes = 0;
     std::vector<std::thread> workers;
     for (int i = 0; i < 20; ++i) {
         workers.emplace_back([&] {
-            if (table.Reserve(tenant_id, 100).has_value()) {
+            if (account->TryCharge(100).has_value()) {
                 ++successes;
             }
         });
@@ -409,7 +429,7 @@ TEST(ShardedTenantQuotaTableTest, ConcurrentReserveNeverExceedsQuota) {
     }
 
     EXPECT_EQ(successes.load(), 10);
-    EXPECT_EQ(Snapshot(table, "tenant-a").reserved_bytes, 1000);
+    EXPECT_EQ(Snapshot(table, "tenant-a").charged_bytes, 1000);
 }
 
 TEST(ShardedTenantQuotaTableTest, DifferentShardsUpdateIndependently) {
@@ -424,50 +444,84 @@ TEST(ShardedTenantQuotaTableTest, DifferentShardsUpdateIndependently) {
 
     TestTable table;
     table.ApplyTenantPolicies({{tenant_a, 1000}, {tenant_b, 1000}}, 2000);
+    auto* account_a = table.GetOrCreateTenantHandle(tenant_a);
+    auto* account_b = table.GetOrCreateTenantHandle(tenant_b);
 
     std::atomic<int> failures = 0;
-    auto update = [&](const TenantId& tenant_id) {
+    auto update = [&](TenantQuotaHandle account) {
         for (int i = 0; i < 1000; ++i) {
-            if (!table.Reserve(tenant_id, 1) || !table.Abort(tenant_id, 1)) {
+            if (!account->TryCharge(1) || !account->Release(1)) {
                 ++failures;
             }
         }
     };
-    std::thread first(update, std::cref(tenant_a));
-    std::thread second(update, std::cref(tenant_b));
+    std::thread first(update, account_a);
+    std::thread second(update, account_b);
     first.join();
     second.join();
 
     EXPECT_EQ(failures.load(), 0);
-    EXPECT_EQ(Snapshot(table, tenant_a.value()).reserved_bytes, 0);
-    EXPECT_EQ(Snapshot(table, tenant_b.value()).reserved_bytes, 0);
+    EXPECT_EQ(Snapshot(table, tenant_a.value()).charged_bytes, 0);
+    EXPECT_EQ(Snapshot(table, tenant_b.value()).charged_bytes, 0);
+}
+
+TEST(ShardedTenantQuotaTableTest,
+     CrossShardMutationsValidateEverythingBeforeUpdating) {
+    using TestTable = ShardedTenantQuotaTable<2>;
+    const TenantId tenant_a("tenant-a");
+    TenantId tenant_b("tenant-b");
+    for (int suffix = 0; TenantIdHash{}(tenant_a) % TestTable::kNumShards ==
+                         TenantIdHash{}(tenant_b) % TestTable::kNumShards;
+         ++suffix) {
+        tenant_b = TenantId("tenant-b-" + std::to_string(suffix));
+    }
+
+    TestTable table;
+    ASSERT_TRUE(
+        table.ApplyTenantPolicies({{tenant_a, 100}, {tenant_b, 200}}, 300));
+    auto invalid_policy = table.ApplyTenantPolicies(
+        {{tenant_a, 300}, {tenant_b, TenantQuotaAccount::kMaxChargedBytes + 1}},
+        500);
+    ASSERT_FALSE(invalid_policy);
+    EXPECT_EQ(Snapshot(table, tenant_a.value()).requested_quota_bytes, 100);
+    EXPECT_EQ(Snapshot(table, tenant_b.value()).requested_quota_bytes, 200);
+
+    ASSERT_TRUE(table.RebuildUsage({{tenant_a, 40}, {tenant_b, 50}}, 300));
+    auto invalid_usage = table.RebuildUsage(
+        {{tenant_a, 60}, {tenant_b, TenantQuotaAccount::kMaxChargedBytes + 1}},
+        300);
+    ASSERT_FALSE(invalid_usage);
+    EXPECT_EQ(Snapshot(table, tenant_a.value()).charged_bytes, 40);
+    EXPECT_EQ(Snapshot(table, tenant_b.value()).charged_bytes, 50);
 }
 
 TEST(ShardedTenantQuotaTableTest,
-     DisabledPolicyRejectsRegularAndZeroByteReservations) {
+     DisabledPolicyRejectsRegularAndZeroByteCharges) {
     ShardedTenantQuotaTable<8> table;
     const TenantId tenant_id("tenant-a");
     table.ApplyTenantPolicies({{tenant_id, 100}}, 100);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
     ASSERT_TRUE(table.DisableTenantPolicyIfEmpty(tenant_id).has_value());
 
-    auto regular = table.Reserve(tenant_id, 1);
-    auto zero = table.Reserve(tenant_id, 0);
+    auto regular = account->TryCharge(1);
+    auto zero = account->TryCharge(0);
 
     ASSERT_FALSE(regular.has_value());
     ASSERT_FALSE(zero.has_value());
-    EXPECT_EQ(regular.error(), TenantQuotaError::kTenantNotRegistered);
-    EXPECT_EQ(zero.error(), TenantQuotaError::kTenantNotRegistered);
+    EXPECT_EQ(regular.error().error, TenantQuotaError::kTenantNotRegistered);
+    EXPECT_EQ(zero.error().error, TenantQuotaError::kTenantNotRegistered);
 }
 
 TEST(ShardedTenantQuotaTableTest, RecomputeCanRunWithAccounting) {
     ShardedTenantQuotaTable<8> table;
     const TenantId tenant_id("tenant-a");
     table.ApplyTenantPolicies({{tenant_id, 1000}}, 1000);
+    auto* account = table.GetOrCreateTenantHandle(tenant_id);
 
     std::atomic<int> failures = 0;
     std::thread accounting([&] {
         for (int i = 0; i < 1000; ++i) {
-            if (!table.Reserve(tenant_id, 1) || !table.Abort(tenant_id, 1)) {
+            if (!account->TryCharge(1) || !account->Release(1)) {
                 ++failures;
             }
         }
@@ -483,7 +537,7 @@ TEST(ShardedTenantQuotaTableTest, RecomputeCanRunWithAccounting) {
 
     EXPECT_EQ(failures.load(), 0);
     auto snapshot = Snapshot(table, "tenant-a");
-    EXPECT_EQ(snapshot.reserved_bytes, 0);
+    EXPECT_EQ(snapshot.charged_bytes, 0);
     EXPECT_EQ(snapshot.effective_quota_bytes, 1000);
 }
 
@@ -524,6 +578,8 @@ TEST(TenantQuotaPolicyStoreTest, RejectsInvalidYamlPolicies) {
         "version: 1\n\ntenants:\n  - name: tenant-a\n    quota: 1KB\n  - name: "
         "tenant-a\n    quota: 2KB\n",
         "version: 1\n\ntenants:\n  - name: tenant-a\n    quota: "
+        "9223372036854775808\n",
+        "version: 1\n\ntenants:\n  - name: tenant-a\n    quota: "
         "18446744073709551616\n",
         "version: 1\n\ntenants:\n  - name: tenant-a\n    quota: "
         "18446744073709551615TB\n",
diff --git a/mooncake-store/tests/test_buffer_allocator.h b/mooncake-store/tests/test_buffer_allocator.h
new file mode 100644
index 0000000000..192f667f90
--- /dev/null
+++ b/mooncake-store/tests/test_buffer_allocator.h
@@ -0,0 +1,104 @@
+#pragma once
+
+#include <algorithm>
+#include <atomic>
+#include <future>
+#include <memory>
+#include <string>
+
+#include "allocator.h"
+#include "replica.h"
+
+namespace mooncake::test {
+
+class TestBufferAllocator final
+    : public BufferAllocatorBase,
+      public std::enable_shared_from_this<TestBufferAllocator> {
+   public:
+    TestBufferAllocator(std::string name, std::string endpoint, size_t capacity,
+                        uintptr_t base = 0x100000000ULL)
+        : name_(std::move(name)),
+          endpoint_(std::move(endpoint)),
+          capacity_(capacity),
+          base_(base),
+          allow_allocation_(allow_allocation_promise_.get_future().share()) {}
+
+    std::unique_ptr<AllocatedBuffer> allocate(size_t size) override {
+        allocation_calls_.fetch_add(1, std::memory_order_relaxed);
+        if (block_next_.exchange(false, std::memory_order_acq_rel)) {
+            allocation_started_promise_.set_value();
+            allow_allocation_.wait();
+        }
+        if (always_fail_.load(std::memory_order_relaxed) ||
+            fail_next_.exchange(false, std::memory_order_acq_rel)) {
+            return nullptr;
+        }
+        size_t current = used_.load(std::memory_order_relaxed);
+        while (size <= capacity_ - std::min(current, capacity_)) {
+            if (used_.compare_exchange_weak(current, current + size,
+                                            std::memory_order_relaxed)) {
+                const uintptr_t address =
+                    base_ +
+                    next_offset_.fetch_add(size, std::memory_order_relaxed);
+                return std::make_unique<AllocatedBuffer>(
+                    shared_from_this(), reinterpret_cast<void*>(address), size);
+            }
+        }
+        return nullptr;
+    }
+
+    void deallocate(AllocatedBuffer* handle) override {
+        used_.fetch_sub(handle->size(), std::memory_order_relaxed);
+    }
+    size_t capacity() const override { return capacity_; }
+    size_t size() const override {
+        return used_.load(std::memory_order_relaxed);
+    }
+    uintptr_t base() const override { return base_; }
+    std::string getSegmentName() const override { return name_; }
+    std::string getTransportEndpoint() const override { return endpoint_; }
+    size_t getLargestFreeRegion() const override {
+        return capacity_ - std::min(size(), capacity_);
+    }
+
+    void SetUsed(size_t used) { used_.store(used, std::memory_order_relaxed); }
+    void SetAlwaysFail(bool fail = true) {
+        always_fail_.store(fail, std::memory_order_relaxed);
+    }
+    void FailNext() { fail_next_.store(true, std::memory_order_relaxed); }
+    void BlockNext() { block_next_.store(true, std::memory_order_relaxed); }
+    std::future<void> AllocationStarted() {
+        return allocation_started_promise_.get_future();
+    }
+    void AllowAllocation() { allow_allocation_promise_.set_value(); }
+    size_t allocation_calls() const {
+        return allocation_calls_.load(std::memory_order_relaxed);
+    }
+
+   private:
+    std::string name_;
+    std::string endpoint_;
+    size_t capacity_;
+    uintptr_t base_;
+    std::atomic<size_t> used_{0};
+    std::atomic<uintptr_t> next_offset_{0};
+    std::atomic<size_t> allocation_calls_{0};
+    std::atomic<bool> always_fail_{false};
+    std::atomic<bool> fail_next_{false};
+    std::atomic<bool> block_next_{false};
+    std::promise<void> allocation_started_promise_;
+    std::promise<void> allow_allocation_promise_;
+    std::shared_future<void> allow_allocation_;
+};
+
+inline std::string ReplicaEndpoint(const Replica& replica) {
+    auto descriptor = replica.get_descriptor();
+    if (descriptor.is_memory_replica()) {
+        return descriptor.get_memory_descriptor()
+            .buffer_descriptor.transport_endpoint_;
+    }
+    return descriptor.get_nof_descriptor()
+        .buffer_descriptor.transport_endpoint_;
+}
+
+}  // namespace mooncake::test
diff --git a/mooncake-store/tests/test_server_helpers.h b/mooncake-store/tests/test_server_helpers.h
index 765eb4429c..759dac97c0 100644
--- a/mooncake-store/tests/test_server_helpers.h
+++ b/mooncake-store/tests/test_server_helpers.h
@@ -17,7 +17,7 @@
 #include "rpc_service.h"
 #include "types.h"
 #include <ylt/util/tl/expected.hpp>
-#include "utils.h"
+#include "common/network.h"
 
 namespace mooncake {
 namespace testing {
@@ -92,7 +92,12 @@ class InProcMaster {
                 std::chrono::seconds(0), /*tcp_no_delay=*/true);
             const char* value = std::getenv("MC_RPC_PROTOCOL");
             if (value && std::string_view(value) == "rdma") {
+#ifdef YLT_ENABLE_IBV
                 server_->init_ibv();
+#else
+                LOG(WARNING)
+                    << "RDMA RPC is disabled at compile time; using TCP RPC";
+#endif
             }
 
             uint64_t default_kv_lease_ttl = DEFAULT_DEFAULT_KV_LEASE_TTL;
@@ -222,6 +227,7 @@ class InProcMaster {
         return std::string("http://127.0.0.1:") +
                std::to_string(http_metrics_port_);
     }
+    std::shared_ptr<WrappedMasterService> service() const { return wrapped_; }
 
    private:
     std::unique_ptr<coro_rpc::coro_rpc_server> server_;
diff --git a/mooncake-store/tests/transfer_submitter_config_test.cpp b/mooncake-store/tests/transfer_submitter_config_test.cpp
new file mode 100644
index 0000000000..48012826d5
--- /dev/null
+++ b/mooncake-store/tests/transfer_submitter_config_test.cpp
@@ -0,0 +1,116 @@
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+#include "../src/config/transfer_submitter_config.h"
+
+namespace mooncake {
+namespace {
+
+class TransferSubmitterConfigTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        if (const char* value = std::getenv("MC_STORE_MEMCPY")) {
+            original_ = value;
+        }
+        google::InitGoogleLogging("TransferSubmitterConfigTest");
+        original_logtostderr_ = FLAGS_logtostderr;
+        FLAGS_logtostderr = true;
+        ASSERT_EQ(unsetenv("MC_STORE_MEMCPY"), 0);
+    }
+
+    void TearDown() override {
+        if (original_.has_value()) {
+            EXPECT_EQ(setenv("MC_STORE_MEMCPY", original_->c_str(), 1), 0);
+        } else {
+            EXPECT_EQ(unsetenv("MC_STORE_MEMCPY"), 0);
+        }
+        FLAGS_logtostderr = original_logtostderr_;
+        google::ShutdownGoogleLogging();
+    }
+
+   private:
+    std::optional<std::string> original_;
+    bool original_logtostderr_ = false;
+};
+
+TEST_F(TransferSubmitterConfigTest, UnsetMeansAutomatic) {
+    ::testing::internal::CaptureStderr();
+    const auto config = TransferSubmitterConfig::FromEnvironment();
+    const auto diagnostics = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_FALSE(config.memcpy_enabled_override.has_value());
+    EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+}
+
+TEST_F(TransferSubmitterConfigTest, PreservesLegacyTokensAndFallbacks) {
+    struct Case {
+        const char* value;
+        bool expected;
+        bool expect_warning;
+    };
+    const Case cases[] = {
+        {"1", true, false},        {"true", true, false},
+        {"TRUE", true, false},     {"yes", true, false},
+        {"YeS", true, false},      {"on", true, false},
+        {"On", true, false},       {"0", false, false},
+        {"false", false, false},   {"FALSE", false, false},
+        {"no", false, false},      {"nO", false, false},
+        {"off", false, false},     {"Off", false, false},
+        {"", true, true},          {" true", true, true},
+        {"false ", true, true},    {"\t0\n", true, true},
+        {"enable", true, true},    {"disable", true, true},
+        {"ENABLE", true, true},    {"DISABLE", true, true},
+        {"2", true, true},         {"-1", true, true},
+        {"+0", true, true},        {"00", true, true},
+        {"falsejunk", true, true}, {"invalid", true, true},
+    };
+
+    for (const auto& test_case : cases) {
+        SCOPED_TRACE(test_case.value);
+        ASSERT_EQ(setenv("MC_STORE_MEMCPY", test_case.value, 1), 0);
+        ::testing::internal::CaptureStderr();
+        const auto config = TransferSubmitterConfig::FromEnvironment();
+        const auto diagnostics = ::testing::internal::GetCapturedStderr();
+
+        EXPECT_EQ(config.memcpy_enabled_override,
+                  std::optional<bool>{test_case.expected});
+        if (test_case.expect_warning) {
+            EXPECT_NE(diagnostics.find("Invalid value for MC_STORE_MEMCPY:"),
+                      std::string::npos);
+        } else {
+            EXPECT_TRUE(diagnostics.empty()) << diagnostics;
+        }
+    }
+}
+
+TEST_F(TransferSubmitterConfigTest, InvalidValueWarningUsesLowercaseValue) {
+    ASSERT_EQ(setenv("MC_STORE_MEMCPY", "BAD", 1), 0);
+    ::testing::internal::CaptureStderr();
+    const auto config = TransferSubmitterConfig::FromEnvironment();
+    const auto diagnostics = ::testing::internal::GetCapturedStderr();
+
+    EXPECT_EQ(config.memcpy_enabled_override, std::optional<bool>{true});
+    EXPECT_NE(diagnostics.find("Invalid value for MC_STORE_MEMCPY: bad, "
+                               "defaulting to enabled"),
+              std::string::npos);
+}
+
+TEST_F(TransferSubmitterConfigTest, NewConfigsReadCurrentEnvironment) {
+    ASSERT_EQ(setenv("MC_STORE_MEMCPY", "0", 1), 0);
+    const auto first = TransferSubmitterConfig::FromEnvironment();
+    ASSERT_EQ(setenv("MC_STORE_MEMCPY", "1", 1), 0);
+    const auto second = TransferSubmitterConfig::FromEnvironment();
+    ASSERT_EQ(unsetenv("MC_STORE_MEMCPY"), 0);
+    const auto third = TransferSubmitterConfig::FromEnvironment();
+
+    EXPECT_EQ(first.memcpy_enabled_override, std::optional<bool>{false});
+    EXPECT_EQ(second.memcpy_enabled_override, std::optional<bool>{true});
+    EXPECT_FALSE(third.memcpy_enabled_override.has_value());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/transfer_task_test.cpp b/mooncake-store/tests/transfer_task_test.cpp
index 8753757ca0..0c5e59f57a 100644
--- a/mooncake-store/tests/transfer_task_test.cpp
+++ b/mooncake-store/tests/transfer_task_test.cpp
@@ -4,15 +4,18 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 
+#include <algorithm>
 #include <chrono>
-#include <cstring>
+#include <cstdlib>
+#include <limits>
 #include <memory>
 #include <numeric>
 #include <thread>
 #include <vector>
 
 #include "types.h"
-#ifdef USE_CUDA
+#include "pinned_buffer_pool.h"
+#if defined(USE_CUDA) || defined(MOONCAKE_TEST_CUDA_H2D)
 #include <cuda_runtime_api.h>
 #endif
 
@@ -21,44 +24,50 @@ namespace mooncake {
 // Test fixture for TransferTask tests
 // TODO: Currently, this test does not cover TransferSubmitter and
 // TransferEngine integration. Will add more tests in the future.
+class ScopedEnvVar {
+   public:
+    ScopedEnvVar(const char* name, const char* value) : name_(name) {
+        if (const char* old_value = std::getenv(name)) {
+            had_old_value_ = true;
+            old_value_ = old_value;
+        }
+        if (value) {
+            setenv(name_.c_str(), value, 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+    ~ScopedEnvVar() {
+        if (had_old_value_) {
+            setenv(name_.c_str(), old_value_.c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+   private:
+    std::string name_;
+    bool had_old_value_ = false;
+    std::string old_value_;
+};
+
 class TransferTaskTest : public ::testing::Test {
    protected:
     void SetUp() override {
         // Initialize glog for logging
         google::InitGoogleLogging("TransferTaskTest");
         FLAGS_logtostderr = 1;  // Output logs to stderr
+        unsetenv("MC_STORE_MEMCPY");
     }
 
     void TearDown() override {
+        unsetenv("MC_STORE_MEMCPY");
         // Cleanup glog
         google::ShutdownGoogleLogging();
     }
 };
 
-// Test basic MemcpyOperation functionality
-TEST_F(TransferTaskTest, MemcpyOperationBasic) {
-    const size_t data_size = 1024;
-    std::vector<char> src_data(data_size, 'A');
-    std::vector<char> dest_data(data_size, 'B');
-
-    // Create memcpy operation
-    MemcpyOperation op(dest_data.data(), src_data.data(), data_size);
-
-    // Verify operation parameters
-    EXPECT_EQ(op.dest, dest_data.data());
-    EXPECT_EQ(op.src, src_data.data());
-    EXPECT_EQ(op.size, data_size);
-
-    // Perform memcpy manually to test
-    std::memcpy(op.dest, op.src, op.size);
-
-    // Verify data was copied correctly
-    EXPECT_EQ(dest_data, src_data);
-    for (size_t i = 0; i < data_size; ++i) {
-        EXPECT_EQ(dest_data[i], 'A');
-    }
-}
-
 // Test MemcpyOperationState functionality
 TEST_F(TransferTaskTest, MemcpyOperationState) {
     auto state = std::make_shared<MemcpyOperationState>();
@@ -153,6 +162,7 @@ TEST_F(TransferTaskTest, TransferScatterHandlesFragmentedCpuBuffers) {
     constexpr size_t kFragmentCount = 128;
     std::vector<char> source(kBufferSize), destination(kBufferSize, 0);
     std::iota(source.begin(), source.end(), 0);
+    std::vector<size_t> completions(kFragmentCount, 0);
     std::vector<size_t> destination_offsets, source_offsets,
         lengths(kFragmentCount, 1);
     for (size_t i = 0; i < kFragmentCount; ++i) {
@@ -183,12 +193,17 @@ TEST_F(TransferTaskTest, TransferScatterHandlesFragmentedCpuBuffers) {
                         .local_offsets = destination_offsets,
                         .remote_offsets = source_offsets,
                         .lengths = lengths,
-                        .on_fragment_complete = {},
+                        .on_fragment_complete =
+                            [&](size_t i, const Status& status) {
+                                EXPECT_TRUE(status.ok());
+                                ++completions[i];
+                            },
                     }})
                     .ok());
     for (size_t i = 0; i < kFragmentCount; ++i) {
         EXPECT_EQ(destination[destination_offsets[i]],
                   source[source_offsets[i]]);
+        EXPECT_EQ(completions[i], 1u);
     }
 }
 
@@ -281,11 +296,7 @@ TEST_F(TransferTaskTest, TransferScatterHandlesFragmentedGpuBuffers) {
 }
 #endif
 
-// Test the locality decision used by TransferSubmitter::isLocalTransfer.
-// Same-host different-process pairs share an IP but have distinct ports;
-// they must NOT be treated as locally addressable, otherwise memcpy in the
-// caller process would dereference a virtual address belonging to a peer
-// process and segfault.
+// Same-host endpoints from different processes are not locally addressable.
 TEST_F(TransferTaskTest, IsSameProcessEndpoint) {
     // Empty inputs -> not same-process (cannot prove locality).
     EXPECT_FALSE(TransferSubmitter::isSameProcessEndpoint("", ""));
@@ -312,6 +323,200 @@ TEST_F(TransferTaskTest, IsSameProcessEndpoint) {
     EXPECT_FALSE(TransferSubmitter::isSameProcessEndpoint("host-a", "host-b"));
 }
 
+TEST_F(TransferTaskTest, BatchGetOffloadObjectHonorsLocalMemcpySetting) {
+    setenv("MC_STORE_MEMCPY", "1", 1);
+    TransferEngine engine(false);
+    ASSERT_EQ(engine.init("P2PHANDSHAKE", "localhost:17933"), 0);
+    const std::string endpoint = engine.getLocalIpAndPort();
+
+    std::vector<char> source(512, 'A');
+    std::vector<char> destination(512, 0);
+    const std::vector<std::string> keys{"key"};
+    const std::vector<uint64_t> pointers{
+        reinterpret_cast<uintptr_t>(source.data())};
+    const std::unordered_map<std::string, std::vector<Slice>> slices{
+        {"key", {{nullptr, 0}, {destination.data(), destination.size()}}}};
+
+    {
+        std::shared_ptr<StorageBackend> backend;
+        TransferSubmitter submitter(engine, backend, endpoint);
+        auto future = submitter.submit_batch_get_offload_object(
+            endpoint, keys, pointers, slices,
+            OffloadBufferAccess::kLocalAddress);
+        ASSERT_TRUE(future);
+        EXPECT_EQ(future->strategy(), TransferStrategy::LOCAL_MEMCPY);
+        EXPECT_EQ(future->get(), ErrorCode::OK);
+        EXPECT_FALSE(submitter.submit_batch_get_offload_object(
+            endpoint, keys, {std::numeric_limits<uint64_t>::max() - 7},
+            {{"key", {{destination.data(), 16}}}},
+            OffloadBufferAccess::kLocalAddress));
+    }
+    EXPECT_EQ(destination, source);
+
+    setenv("MC_STORE_MEMCPY", "0", 1);
+    std::shared_ptr<StorageBackend> backend;
+    TransferSubmitter submitter(engine, backend, endpoint);
+    EXPECT_FALSE(submitter.submit_batch_get_offload_object(
+        endpoint, keys, pointers, slices, OffloadBufferAccess::kLocalAddress));
+    EXPECT_EQ(engine.freeEngine(), 0);
+}
+
+#ifdef MOONCAKE_TEST_CUDA_H2D
+TEST_F(TransferTaskTest, BatchGetOffloadObjectCopiesPinnedHostToGpu) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count == 0) {
+        GTEST_SKIP() << "CUDA device is unavailable";
+    }
+
+    setenv("MC_STORE_MEMCPY", "1", 1);
+    constexpr size_t kSourceOffset = 128;
+    constexpr size_t kSize = 4096;
+    auto pinned_buffer =
+        PinnedBufferPool::AllocatePinned(kSourceOffset + kSize);
+    ASSERT_NE(pinned_buffer.pinned_host.addr, nullptr);
+    void* pinned_source = pinned_buffer.data;
+    void* gpu_destination = nullptr;
+    ASSERT_EQ(cudaMalloc(&gpu_destination, kSize), cudaSuccess);
+    std::memset(static_cast<char*>(pinned_source) + kSourceOffset, 0x5a, kSize);
+
+    TransferEngine engine(false);
+    ASSERT_EQ(engine.init("P2PHANDSHAKE", "localhost:17934"), 0);
+    const std::string endpoint = engine.getLocalIpAndPort();
+    {
+        std::shared_ptr<StorageBackend> backend;
+        TransferSubmitter submitter(engine, backend, endpoint);
+        auto future = submitter.submit_batch_get_offload_object(
+            endpoint, {"gpu"},
+            {reinterpret_cast<uintptr_t>(static_cast<char*>(pinned_source) +
+                                         kSourceOffset)},
+            {{"gpu", {{gpu_destination, kSize}}}},
+            OffloadBufferAccess::kLocalAddress);
+        ASSERT_TRUE(future);
+        EXPECT_EQ(future->get(), ErrorCode::OK);
+    }
+
+    std::vector<unsigned char> actual(kSize);
+    EXPECT_EQ(cudaMemcpy(actual.data(), gpu_destination, kSize,
+                         cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_EQ(actual, std::vector<unsigned char>(kSize, 0x5a));
+    EXPECT_EQ(engine.freeEngine(), 0);
+    EXPECT_EQ(cudaFree(gpu_destination), cudaSuccess);
+}
+#endif
+TEST_F(TransferTaskTest, CanUseLocalMemcpyRequiresSameProcessEndpoint) {
+    ScopedEnvVar memcpy_enabled("MC_STORE_MEMCPY", "1");
+
+    TransferEngine engine(false);
+    ASSERT_EQ(
+        engine.init("P2PHANDSHAKE", "127.0.0.1:30991", "127.0.0.1", 30991), 0);
+    ASSERT_NE(engine.installTransport("tcp", nullptr), nullptr);
+
+    std::shared_ptr<StorageBackend> storage_backend;
+    TransferSubmitter submitter(engine, storage_backend, "127.0.0.1:30991");
+
+    const auto local_endpoint = engine.getLocalIpAndPort();
+    ASSERT_FALSE(local_endpoint.empty());
+    EXPECT_TRUE(submitter.canUseLocalMemcpy(local_endpoint));
+
+    EXPECT_FALSE(submitter.canUseLocalMemcpy("127.0.0.1:30992"));
+    EXPECT_FALSE(submitter.canUseLocalMemcpy(""));
+}
+
+TEST_F(TransferTaskTest, CanUseLocalMemcpyHonorsMemcpyEnv) {
+    ScopedEnvVar memcpy_disabled("MC_STORE_MEMCPY", "0");
+
+    TransferEngine engine(false);
+    ASSERT_EQ(
+        engine.init("P2PHANDSHAKE", "127.0.0.1:30993", "127.0.0.1", 30993), 0);
+    ASSERT_NE(engine.installTransport("tcp", nullptr), nullptr);
+
+    std::shared_ptr<StorageBackend> storage_backend;
+    TransferSubmitter submitter(engine, storage_backend, "127.0.0.1:30993");
+
+    EXPECT_FALSE(submitter.canUseLocalMemcpy(engine.getLocalIpAndPort()));
+}
+
+TEST_F(TransferTaskTest, BatchWriteHonorsLocalMemcpySetting) {
+    ScopedEnvVar memcpy_enabled("MC_STORE_MEMCPY", "1");
+
+    TransferEngine engine(false);
+    ASSERT_EQ(
+        engine.init("P2PHANDSHAKE", "127.0.0.1:30995", "127.0.0.1", 30995), 0);
+
+    std::vector<char> source(512, 'A');
+    std::vector<char> destination(source.size(), 0);
+    MemoryDescriptor memory;
+    memory.buffer_descriptor.buffer_address_ =
+        reinterpret_cast<uintptr_t>(destination.data());
+    memory.buffer_descriptor.size_ = destination.size();
+    memory.buffer_descriptor.transport_endpoint_ = engine.getLocalIpAndPort();
+    memory.buffer_descriptor.protocol_ = "tcp";
+    Replica::Descriptor replica;
+    replica.descriptor_variant = memory;
+    replica.status = ReplicaStatus::PROCESSING;
+
+    std::shared_ptr<StorageBackend> storage_backend;
+    {
+        TransferSubmitter submitter(engine, storage_backend,
+                                    engine.getLocalIpAndPort());
+        std::vector<std::vector<Slice>> slices{
+            {{source.data(), source.size()}}};
+        auto future =
+            submitter.submit_batch({replica}, slices, TransferRequest::WRITE);
+
+        ASSERT_TRUE(future);
+        EXPECT_EQ(future->strategy(), TransferStrategy::LOCAL_MEMCPY);
+        EXPECT_EQ(future->get(), ErrorCode::OK);
+    }
+    EXPECT_EQ(destination, source);
+    EXPECT_EQ(engine.freeEngine(), 0);
+}
+
+TEST_F(TransferTaskTest, RemoteTransferWaitCompletesCorrectly) {
+    ScopedEnvVar memcpy_disabled("MC_STORE_MEMCPY", "0");
+    ScopedEnvVar tent_config("MC_TENT_CONF", nullptr);
+    constexpr size_t kSize = 16 * 1024 * 1024;
+    std::vector<char> local(kSize, 0), remote(kSize, 'A');
+    TransferEngine client(false), server(false);
+    ASSERT_EQ(client.init("P2PHANDSHAKE", "127.0.0.1:0", "", 0, "tcp"), 0);
+    ASSERT_EQ(server.init("P2PHANDSHAKE", "127.0.0.1:0", "", 0, "tcp"), 0);
+    if (!client.isUsingTent()) {
+        ASSERT_NE(client.installTransport("tcp", nullptr), nullptr);
+        ASSERT_NE(server.installTransport("tcp", nullptr), nullptr);
+    }
+    ASSERT_EQ(client.registerLocalMemory(local.data(), local.size(), "cpu:0"),
+              0);
+    ASSERT_EQ(server.registerLocalMemory(remote.data(), remote.size(), "cpu:0"),
+              0);
+
+    MemoryDescriptor memory;
+    memory.buffer_descriptor.buffer_address_ =
+        reinterpret_cast<uintptr_t>(remote.data());
+    memory.buffer_descriptor.size_ = remote.size();
+    memory.buffer_descriptor.transport_endpoint_ = server.getLocalIpAndPort();
+    memory.buffer_descriptor.protocol_ = "tcp";
+    Replica::Descriptor replica;
+    replica.descriptor_variant = memory;
+    replica.status = ReplicaStatus::COMPLETE;
+    std::shared_ptr<StorageBackend> backend;
+    TransferSubmitter submitter(client, backend, client.getLocalIpAndPort());
+    std::vector<Slice> slices{{local.data(), local.size()}};
+
+    for (auto opcode : {TransferRequest::READ, TransferRequest::WRITE}) {
+        if (opcode == TransferRequest::WRITE) {
+            std::fill(local.begin(), local.end(), 'B');
+        }
+        auto future = submitter.submit(replica, slices, opcode);
+        ASSERT_TRUE(future);
+        EXPECT_EQ(future->strategy(), TransferStrategy::TRANSFER_ENGINE);
+        ASSERT_EQ(future->get(), ErrorCode::OK);
+        EXPECT_EQ(local, remote);
+    }
+    EXPECT_EQ(client.unregisterLocalMemory(local.data()), 0);
+    EXPECT_EQ(server.unregisterLocalMemory(remote.data()), 0);
+}
+
 // Test TransferStrategy enum and stream operator
 TEST_F(TransferTaskTest, TransferStrategyEnum) {
     // Test enum values
diff --git a/mooncake-store/tests/weight_management_contract_test.cpp b/mooncake-store/tests/weight_management_contract_test.cpp
new file mode 100644
index 0000000000..74512ffa26
--- /dev/null
+++ b/mooncake-store/tests/weight_management_contract_test.cpp
@@ -0,0 +1,241 @@
+#include <gtest/gtest.h>
+
+#include <type_traits>
+
+#include "weight_management.h"
+#include "ylt/struct_pack.hpp"
+
+namespace mooncake {
+namespace {
+
+template <typename T>
+concept HasTensorsField = requires(T value) { value.tensors; };
+
+template <typename T>
+concept HasRuntimeEndpointField = requires(T value) { value.runtime_endpoint; };
+
+WeightRevisionIdentity ValidIdentity() {
+    return WeightRevisionIdentity{
+        .tenant_id = "tenant-a",
+        .name_space = "production",
+        .resource_id = "llama-70b",
+        .revision = "step-100",
+        .weight_generation = 7,
+    };
+}
+
+WeightManifestReference ValidManifest() {
+    const auto identity = ValidIdentity();
+    return WeightManifestReference{
+        .manifest_key = MakeWeightManifestKey(identity),
+        .manifest_sha256 = std::string(64, 'a'),
+        .payload_group_id = MakeWeightPayloadGroupId(identity),
+        .payload_keys_sha256 = std::string(64, 'b'),
+        .payload_count = 3,
+        .logical_bytes = 4096,
+    };
+}
+
+TEST(WeightManagementContractTest, ValidatesIdentityComponentsStrictly) {
+    auto identity = ValidIdentity();
+    EXPECT_TRUE(ValidateWeightRevisionIdentity(identity).ok());
+
+    identity.name_space.clear();
+    EXPECT_FALSE(ValidateWeightRevisionIdentity(identity).ok());
+    identity = ValidIdentity();
+    identity.resource_id.clear();
+    EXPECT_FALSE(ValidateWeightRevisionIdentity(identity).ok());
+    identity = ValidIdentity();
+    identity.revision.clear();
+    EXPECT_FALSE(ValidateWeightRevisionIdentity(identity).ok());
+    identity = ValidIdentity();
+    identity.weight_generation = 0;
+    EXPECT_FALSE(ValidateWeightRevisionIdentity(identity).ok());
+    identity = ValidIdentity();
+    identity.tenant_id = "_reserved";
+    EXPECT_FALSE(ValidateWeightRevisionIdentity(identity).ok());
+}
+
+TEST(WeightManagementContractTest, ValidatesSha256AndGeneration) {
+    auto manifest = ValidManifest();
+    EXPECT_TRUE(ValidateWeightManifestReference(manifest).ok());
+
+    manifest.manifest_sha256 = std::string(63, 'a');
+    EXPECT_FALSE(ValidateWeightManifestReference(manifest).ok());
+    manifest = ValidManifest();
+    manifest.manifest_sha256[4] = 'G';
+    EXPECT_FALSE(ValidateWeightManifestReference(manifest).ok());
+    manifest = ValidManifest();
+    manifest.payload_keys_sha256[9] = 'A';
+    EXPECT_FALSE(ValidateWeightManifestReference(manifest).ok());
+
+    WeightRevisionMetadata metadata{
+        .identity = ValidIdentity(),
+        .manifest = ValidManifest(),
+        .availability = WeightAvailabilityState::READY,
+        .residency = WeightResidencyState::HOT,
+        .operation = WeightOperationState::NONE,
+        .metadata_generation = 0,
+        .created_at_ms = 1,
+        .updated_at_ms = 1,
+    };
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.metadata_generation = 1;
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+    EXPECT_TRUE(CanAdvanceWeightMetadataGeneration(1));
+    EXPECT_FALSE(CanAdvanceWeightMetadataGeneration(0));
+    EXPECT_FALSE(CanAdvanceWeightMetadataGeneration(
+        std::numeric_limits<uint64_t>::max() - 1));
+}
+
+TEST(WeightManagementContractTest, RejectsNonCanonicalWeightObjectNames) {
+    WeightRevisionMetadata metadata{
+        .identity = ValidIdentity(),
+        .manifest = ValidManifest(),
+        .availability = WeightAvailabilityState::READY,
+        .residency = WeightResidencyState::HOT,
+        .operation = WeightOperationState::NONE,
+        .metadata_generation = 1,
+        .created_at_ms = 1,
+        .updated_at_ms = 1,
+    };
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.manifest.payload_group_id = "valid-but-non-canonical-group";
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.manifest = ValidManifest();
+    metadata.manifest.manifest_key = "valid-but-non-canonical-manifest";
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+}
+
+TEST(WeightManagementContractTest, EnforcesStateCombinationAndOperationIds) {
+    WeightRevisionMetadata metadata{
+        .identity = ValidIdentity(),
+        .manifest = ValidManifest(),
+        .availability = WeightAvailabilityState::READY,
+        .residency = WeightResidencyState::HOT,
+        .operation = WeightOperationState::EVICTING,
+        .operation_id = 0,
+        .metadata_generation = 1,
+        .created_at_ms = 1,
+        .updated_at_ms = 1,
+    };
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.operation_id = 10;
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.operation = WeightOperationState::NONE;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.operation_id = 0;
+    metadata.residency = WeightResidencyState::ABSENT;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.residency = WeightResidencyState::UNKNOWN;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.residency = WeightResidencyState::HOT;
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.availability = WeightAvailabilityState::DEGRADED;
+    metadata.residency = WeightResidencyState::UNKNOWN;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.residency = WeightResidencyState::ABSENT;
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.availability = WeightAvailabilityState::DELETED;
+    metadata.residency = WeightResidencyState::HOT;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.residency = WeightResidencyState::ABSENT;
+    EXPECT_TRUE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.availability = static_cast<WeightAvailabilityState>(255);
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.availability = WeightAvailabilityState::DELETED;
+    metadata.residency = static_cast<WeightResidencyState>(255);
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+    metadata.residency = WeightResidencyState::ABSENT;
+    metadata.operation = static_cast<WeightOperationState>(255);
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+
+    metadata.availability = WeightAvailabilityState::IMPORTING;
+    metadata.residency = WeightResidencyState::UNKNOWN;
+    metadata.operation = WeightOperationState::EVICTING;
+    metadata.operation_id = 1;
+    EXPECT_FALSE(ValidateWeightRevisionMetadata(metadata).ok());
+}
+
+TEST(WeightManagementContractTest, RestrictsAvailabilityTransitions) {
+    using State = WeightAvailabilityState;
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::IMPORTING, State::READY));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::IMPORTING, State::DELETING));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::READY, State::DEGRADED));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::READY, State::DELETING));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::DEGRADED, State::READY));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::DEGRADED, State::DELETING));
+    EXPECT_TRUE(
+        IsValidWeightAvailabilityTransition(State::DELETING, State::DELETED));
+
+    EXPECT_FALSE(
+        IsValidWeightAvailabilityTransition(State::IMPORTING, State::DEGRADED));
+    EXPECT_FALSE(
+        IsValidWeightAvailabilityTransition(State::READY, State::DELETED));
+    EXPECT_FALSE(
+        IsValidWeightAvailabilityTransition(State::DELETED, State::READY));
+    EXPECT_FALSE(
+        IsValidWeightAvailabilityTransition(State::READY, State::READY));
+}
+
+TEST(WeightManagementContractTest, RoundTripsWireEnumsAndMetadata) {
+    WeightRevisionMetadata metadata{
+        .identity = ValidIdentity(),
+        .manifest = ValidManifest(),
+        .availability = WeightAvailabilityState::DEGRADED,
+        .residency = WeightResidencyState::MIXED,
+        .operation = WeightOperationState::REPAIRING,
+        .operation_id = 42,
+        .metadata_generation = 9,
+        .created_at_ms = 100,
+        .updated_at_ms = 200,
+    };
+
+    auto encoded = struct_pack::serialize(metadata);
+    WeightRevisionMetadata decoded;
+    ASSERT_EQ(struct_pack::errc::ok,
+              struct_pack::deserialize_to(decoded, encoded));
+    EXPECT_EQ(metadata, decoded);
+}
+
+TEST(WeightManagementContractTest, CanonicalDigestsAreStableAndUnambiguous) {
+    EXPECT_EQ(
+        "ff2c110b8f18291ea676be2af036320944751c4b3e6a65b3c1153721c61c2b26",
+        ComputeWeightPayloadKeysSha256({"p2", "p1"}));
+
+    auto identity = ValidIdentity();
+    identity.tenant_id = "default";
+    EXPECT_EQ(
+        "weight:5dbbea14aa75c98a5b3fbb576a9c612d64fc6bc8f490f24a7ff0"
+        "17fcfe321b7d",
+        MakeWeightPayloadGroupId(identity));
+}
+
+TEST(WeightManagementContractTest, ManifestKeyUsesCanonicalUrlEncoding) {
+    auto identity = ValidIdentity();
+    identity.name_space = "prod east";
+    identity.resource_id = "family/model";
+    identity.revision = "v1%candidate";
+    EXPECT_EQ("weights/prod%20east/family%2Fmodel/v1%25candidate/7/manifest",
+              MakeWeightManifestKey(identity));
+}
+
+TEST(WeightManagementContractTest, MetadataDoesNotDuplicateManifestChildren) {
+    static_assert(!HasTensorsField<WeightRevisionMetadata>);
+    static_assert(!HasRuntimeEndpointField<WeightRevisionMetadata>);
+    SUCCEED();
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/weight_metadata_store_test.cpp b/mooncake-store/tests/weight_metadata_store_test.cpp
new file mode 100644
index 0000000000..9298e64e49
--- /dev/null
+++ b/mooncake-store/tests/weight_metadata_store_test.cpp
@@ -0,0 +1,775 @@
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <limits>
+#include <thread>
+#include <vector>
+
+#include "weight_metadata_store.h"
+
+namespace mooncake {
+namespace {
+
+WeightRevisionIdentity Identity(std::string revision = "step-100",
+                                uint64_t generation = 7) {
+    return WeightRevisionIdentity{
+        .tenant_id = "tenant-a",
+        .name_space = "production",
+        .resource_id = "llama-70b",
+        .revision = std::move(revision),
+        .weight_generation = generation,
+    };
+}
+
+BeginWeightImportRequest BeginRequest(
+    const WeightRevisionIdentity& identity = Identity()) {
+    return BeginWeightImportRequest{
+        .identity = identity,
+        .payload_group_id = MakeWeightPayloadGroupId(identity),
+        .expected_payload_count = 3,
+        .expected_logical_bytes = 4096,
+    };
+}
+
+WeightManifestReference Manifest() {
+    const auto identity = Identity();
+    return WeightManifestReference{
+        .manifest_key = MakeWeightManifestKey(identity),
+        .manifest_sha256 = std::string(64, 'a'),
+        .payload_group_id = MakeWeightPayloadGroupId(identity),
+        .payload_keys_sha256 = std::string(64, 'b'),
+        .payload_count = 3,
+        .logical_bytes = 4096,
+    };
+}
+
+WeightRevisionMetadata PublishBegin(WeightMetadataStore& metadata_store,
+                                    const BeginWeightImportRequest& request,
+                                    uint64_t now_ms = 100) {
+    auto candidate = metadata_store.PrepareBeginImport(request, now_ms);
+    EXPECT_TRUE(candidate.has_value());
+    auto published = metadata_store.Publish(*candidate);
+    EXPECT_TRUE(published.has_value());
+    return *published;
+}
+
+WeightRevisionMetadata PublishReady(WeightMetadataStore& metadata_store) {
+    auto importing = PublishBegin(metadata_store, BeginRequest());
+    auto candidate = metadata_store.PrepareCommitImport(
+        CommitWeightImportRequest{
+            .identity = importing.identity,
+            .expected_metadata_generation = importing.metadata_generation,
+            .manifest = Manifest(),
+        },
+        200);
+    EXPECT_TRUE(candidate.has_value());
+    auto published = metadata_store.Publish(*candidate);
+    EXPECT_TRUE(published.has_value());
+    return *published;
+}
+
+TEST(WeightMetadataStoreTest, BeginIsIdempotent) {
+    WeightMetadataStore metadata_store;
+    auto first = PublishBegin(metadata_store, BeginRequest());
+    EXPECT_EQ(WeightAvailabilityState::IMPORTING, first.availability);
+    EXPECT_EQ(1, first.metadata_generation);
+
+    auto retry = metadata_store.PrepareBeginImport(BeginRequest(), 150);
+    ASSERT_TRUE(retry.has_value());
+    EXPECT_TRUE(retry->no_op);
+    auto retried = metadata_store.Publish(*retry);
+    ASSERT_TRUE(retried.has_value());
+    EXPECT_EQ(first, *retried);
+}
+
+TEST(WeightMetadataStoreTest, RejectsNonCanonicalWeightObjectNames) {
+    WeightMetadataStore metadata_store;
+    auto noncanonical_begin = BeginRequest();
+    noncanonical_begin.payload_group_id = "valid-but-non-canonical-group";
+    auto rejected = metadata_store.PrepareBeginImport(noncanonical_begin, 100);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT, rejected.error());
+
+    auto importing = PublishBegin(metadata_store, BeginRequest());
+    auto noncanonical_manifest = Manifest();
+    noncanonical_manifest.manifest_key = "valid-but-non-canonical-manifest";
+    rejected = metadata_store.PrepareCommitImport(
+        CommitWeightImportRequest{
+            .identity = importing.identity,
+            .expected_metadata_generation = importing.metadata_generation,
+            .manifest = std::move(noncanonical_manifest),
+        },
+        200);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT, rejected.error());
+
+    auto ready = PublishReady(metadata_store);
+    auto snapshot = metadata_store.ExportSnapshot();
+    snapshot.metadata[0].manifest.payload_group_id =
+        "valid-but-non-canonical-group";
+    WeightMetadataStore restored;
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT,
+              restored.RestoreSnapshot(snapshot).error());
+
+    snapshot = metadata_store.ExportSnapshot();
+    snapshot.metadata[0].manifest.manifest_key =
+        "valid-but-non-canonical-manifest";
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT,
+              restored.RestoreSnapshot(snapshot).error());
+    EXPECT_EQ(ready, metadata_store.Get(ready.identity, 200)->metadata);
+}
+
+TEST(WeightMetadataStoreTest, CommitUsesCasAndIsRetryableAfterResponseLoss) {
+    WeightMetadataStore metadata_store;
+    auto importing = PublishBegin(metadata_store, BeginRequest());
+    auto request = CommitWeightImportRequest{
+        .identity = importing.identity,
+        .expected_metadata_generation = importing.metadata_generation,
+        .manifest = Manifest(),
+    };
+    auto candidate = metadata_store.PrepareCommitImport(request, 200);
+    ASSERT_TRUE(candidate.has_value());
+
+    auto stale = request;
+    stale.expected_metadata_generation = importing.metadata_generation + 1;
+    auto rejected = metadata_store.PrepareCommitImport(stale, 200);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(WeightManagementError::STALE_GENERATION, rejected.error());
+
+    auto published = metadata_store.Publish(*candidate);
+    ASSERT_TRUE(published.has_value());
+    EXPECT_EQ(WeightAvailabilityState::READY, published->availability);
+    EXPECT_EQ(2, published->metadata_generation);
+
+    auto response_lost_retry = metadata_store.PrepareCommitImport(request, 300);
+    ASSERT_TRUE(response_lost_retry.has_value());
+    EXPECT_TRUE(response_lost_retry->no_op);
+    auto retry_result = metadata_store.Publish(*response_lost_retry);
+    ASSERT_TRUE(retry_result.has_value());
+    EXPECT_EQ(*published, *retry_result);
+
+    auto unrelated_generation = request;
+    unrelated_generation.expected_metadata_generation = 99;
+    auto wrong_retry =
+        metadata_store.PrepareCommitImport(unrelated_generation, 301);
+    ASSERT_FALSE(wrong_retry.has_value());
+    EXPECT_EQ(WeightManagementError::STALE_GENERATION, wrong_retry.error());
+}
+
+TEST(WeightMetadataStoreTest, AbortRetryRequiresAdjacentGeneration) {
+    WeightMetadataStore metadata_store;
+    auto importing = PublishBegin(metadata_store, BeginRequest());
+    const AbortWeightImportRequest request{
+        .identity = importing.identity,
+        .expected_metadata_generation = importing.metadata_generation,
+    };
+    auto candidate = metadata_store.PrepareAbortImport(request, 200);
+    ASSERT_TRUE(candidate.has_value());
+    ASSERT_TRUE(metadata_store.Publish(*candidate).has_value());
+
+    auto retry = metadata_store.PrepareAbortImport(request, 201);
+    ASSERT_TRUE(retry.has_value());
+    EXPECT_TRUE(retry->no_op);
+
+    auto unrelated_generation = request;
+    unrelated_generation.expected_metadata_generation = 99;
+    auto rejected =
+        metadata_store.PrepareAbortImport(unrelated_generation, 202);
+    ASSERT_FALSE(rejected.has_value());
+    EXPECT_EQ(WeightManagementError::STALE_GENERATION, rejected.error());
+}
+
+TEST(WeightMetadataStoreTest, LookupAndPaginationAreExactAndDeterministic) {
+    WeightMetadataStore metadata_store;
+    for (const auto& [revision, generation] :
+         std::vector<std::pair<std::string, uint64_t>>{
+             {"step-20", 2}, {"step-10", 3}, {"step-10", 1}}) {
+        auto request = BeginRequest(Identity(revision, generation));
+        PublishBegin(metadata_store, request);
+    }
+
+    auto exact = metadata_store.Get(Identity("step-10", 3), 200);
+    ASSERT_TRUE(exact.has_value());
+    EXPECT_EQ(3, exact->metadata.identity.weight_generation);
+
+    ListWeightRevisionsRequest request{
+        .tenant_id = "tenant-a",
+        .name_space = "production",
+        .resource_id = "llama-70b",
+        .page_token = {},
+        .limit = 2,
+    };
+    auto first = metadata_store.List(request, 200);
+    ASSERT_TRUE(first.has_value());
+    ASSERT_EQ(2, first->revisions.size());
+    EXPECT_EQ("step-10", first->revisions[0].metadata.identity.revision);
+    EXPECT_EQ(1, first->revisions[0].metadata.identity.weight_generation);
+    EXPECT_EQ("step-10", first->revisions[1].metadata.identity.revision);
+    EXPECT_EQ(3, first->revisions[1].metadata.identity.weight_generation);
+    ASSERT_FALSE(first->next_page_token.empty());
+
+    request.page_token = first->next_page_token;
+    auto second = metadata_store.List(request, 200);
+    ASSERT_TRUE(second.has_value());
+    ASSERT_EQ(1, second->revisions.size());
+    EXPECT_EQ("step-20", second->revisions[0].metadata.identity.revision);
+    EXPECT_TRUE(second->next_page_token.empty());
+}
+
+TEST(WeightMetadataStoreTest, LeaseExpiryIsGenerationFencedAndIdempotent) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto candidate = metadata_store.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 50,
+        },
+        300);
+    ASSERT_TRUE(candidate.has_value());
+    auto lease = metadata_store.Publish(*candidate);
+    ASSERT_TRUE(lease.has_value());
+    EXPECT_TRUE(metadata_store.HasActiveLease(ready.identity,
+                                              ready.metadata_generation, 349));
+    EXPECT_TRUE(metadata_store.HasActiveLease(
+        ready.identity, ready.metadata_generation + 1, 349));
+
+    auto expired = metadata_store.PrepareExpireLeases(350);
+    ASSERT_EQ(1, expired.size());
+    ASSERT_TRUE(metadata_store.Publish(expired.front()).has_value());
+    EXPECT_FALSE(metadata_store.HasActiveLease(ready.identity,
+                                               ready.metadata_generation, 350));
+    EXPECT_TRUE(metadata_store.PrepareExpireLeases(350).empty());
+}
+
+TEST(WeightMetadataStoreTest, LeaseReplayAdvancesAllocatorWatermark) {
+    WeightMetadataStore source;
+    WeightMetadataStore replay_target;
+    auto source_ready = PublishReady(source);
+    auto target_ready = PublishReady(replay_target);
+    ASSERT_EQ(source_ready, target_ready);
+
+    auto replayed = source.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = source_ready.identity,
+            .expected_metadata_generation = source_ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 100,
+        },
+        300);
+    ASSERT_TRUE(replayed.has_value());
+    ASSERT_TRUE(replay_target.Publish(*replayed).has_value());
+
+    const auto snapshot = replay_target.ExportSnapshot();
+    EXPECT_EQ(replayed->lease_id + 1, snapshot.next_lease_id);
+    WeightMetadataStore restored;
+    EXPECT_TRUE(restored.RestoreSnapshot(snapshot).has_value());
+
+    auto next = replay_target.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = target_ready.identity,
+            .expected_metadata_generation = target_ready.metadata_generation,
+            .holder = "worker-2",
+            .ttl_ms = 100,
+        },
+        301);
+    ASSERT_TRUE(next.has_value());
+    EXPECT_NE(replayed->lease_id, next->lease_id);
+}
+
+TEST(WeightMetadataStoreTest, LeaseReplayRejectsExhaustedAllocatorId) {
+    WeightMetadataStore source;
+    WeightMetadataStore replay_target;
+    auto ready = PublishReady(source);
+    ASSERT_EQ(ready, PublishReady(replay_target));
+
+    auto replayed = source.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 100,
+        },
+        300);
+    ASSERT_TRUE(replayed.has_value());
+    replayed->lease_id = std::numeric_limits<uint64_t>::max();
+    replayed->next->lease_id = replayed->lease_id;
+
+    auto published = replay_target.Publish(*replayed);
+    ASSERT_FALSE(published.has_value());
+    EXPECT_EQ(WeightManagementError::GENERATION_EXHAUSTED, published.error());
+}
+
+TEST(WeightMetadataStoreTest, ExcludesConcurrentResidencyOperations) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto first = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(first.has_value());
+    auto operation = metadata_store.Publish(*first);
+    ASSERT_TRUE(operation.has_value());
+    EXPECT_EQ(WeightOperationState::EVICTING, operation->operation);
+
+    auto unrelated_generation = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = 99,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        301);
+    ASSERT_FALSE(unrelated_generation.has_value());
+    EXPECT_EQ(WeightManagementError::STALE_GENERATION,
+              unrelated_generation.error());
+
+    auto conflicting = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation + 1,
+            .target_residency = WeightResidencyState::HOT,
+        },
+        301);
+    ASSERT_FALSE(conflicting.has_value());
+    EXPECT_EQ(WeightManagementError::BUSY, conflicting.error());
+}
+
+TEST(WeightMetadataStoreTest, UnchangedOperationProgressIsIdempotent) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto started = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(started.has_value());
+    auto operation = metadata_store.Publish(*started);
+    ASSERT_TRUE(operation.has_value());
+
+    auto progress = metadata_store.PrepareUpdateOperationProgress(
+        operation->operation_id, 0, 4, {}, 400);
+    ASSERT_TRUE(progress.has_value());
+    EXPECT_FALSE(progress->no_op);
+    auto published = metadata_store.Publish(*progress);
+    ASSERT_TRUE(published.has_value());
+    EXPECT_EQ(400, published->updated_at_ms);
+
+    auto retry = metadata_store.PrepareUpdateOperationProgress(
+        operation->operation_id, 0, 4, {}, 500);
+    ASSERT_TRUE(retry.has_value());
+    EXPECT_TRUE(retry->no_op);
+    auto retried = metadata_store.Publish(*retry);
+    ASSERT_TRUE(retried.has_value());
+    EXPECT_EQ(400, retried->updated_at_ms);
+}
+
+TEST(WeightMetadataStoreTest, OperationTimestampsRemainMonotonic) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto start = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(start.has_value());
+    auto operation = metadata_store.Publish(*start);
+    ASSERT_TRUE(operation.has_value());
+
+    auto progress = metadata_store.PrepareUpdateOperationProgress(
+        operation->operation_id, 1, 2, "member-1", 250);
+    ASSERT_TRUE(progress.has_value());
+    operation = metadata_store.Publish(*progress);
+    ASSERT_TRUE(operation.has_value());
+    EXPECT_EQ(300, operation->updated_at_ms);
+    WeightMetadataStore restored;
+    EXPECT_TRUE(
+        restored.RestoreSnapshot(metadata_store.ExportSnapshot()).has_value());
+
+    auto finish = metadata_store.PrepareFinishOperation(
+        operation->operation_id, WeightResidencyState::COLD, 200);
+    ASSERT_TRUE(finish.has_value());
+    operation = metadata_store.Publish(*finish);
+    ASSERT_TRUE(operation.has_value());
+    EXPECT_EQ(300, operation->updated_at_ms);
+    EXPECT_TRUE(
+        restored.RestoreSnapshot(metadata_store.ExportSnapshot()).has_value());
+}
+
+TEST(WeightMetadataStoreTest, ActiveLeaseBlocksResidencyAndDelete) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto lease_mutation = metadata_store.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 100,
+        },
+        300);
+    ASSERT_TRUE(lease_mutation.has_value());
+    ASSERT_TRUE(metadata_store.Publish(*lease_mutation).has_value());
+
+    auto operation = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        301);
+    ASSERT_FALSE(operation.has_value());
+    EXPECT_EQ(WeightManagementError::BUSY, operation.error());
+
+    auto deletion = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+        },
+        301);
+    ASSERT_FALSE(deletion.has_value());
+    EXPECT_EQ(WeightManagementError::BUSY, deletion.error());
+}
+
+TEST(WeightMetadataStoreTest, LeasePublicationFencesPreparedDeletion) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto lease = metadata_store.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 100,
+        },
+        300);
+    auto deletion = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+        },
+        301);
+    ASSERT_TRUE(lease.has_value());
+    ASSERT_TRUE(deletion.has_value());
+    ASSERT_TRUE(metadata_store.Publish(*lease).has_value());
+
+    auto published = metadata_store.Publish(*deletion);
+    ASSERT_FALSE(published.has_value());
+    EXPECT_EQ(WeightManagementError::BUSY, published.error());
+    EXPECT_EQ(WeightAvailabilityState::READY,
+              metadata_store.Get(ready.identity, 301)->metadata.availability);
+}
+
+TEST(WeightMetadataStoreTest,
+     LeasePublicationFencesPreparedResidencyOperation) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto lease = metadata_store.PrepareAcquireLease(
+        AcquireWeightRevisionLeaseRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .holder = "worker-1",
+            .ttl_ms = 100,
+        },
+        300);
+    auto operation = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        301);
+    ASSERT_TRUE(lease.has_value());
+    ASSERT_TRUE(operation.has_value());
+    ASSERT_TRUE(metadata_store.Publish(*lease).has_value());
+
+    auto published = metadata_store.Publish(*operation);
+    ASSERT_FALSE(published.has_value());
+    EXPECT_EQ(WeightManagementError::BUSY, published.error());
+    EXPECT_EQ(WeightOperationState::NONE,
+              metadata_store.Get(ready.identity, 301)->metadata.operation);
+}
+
+TEST(WeightMetadataStoreTest, RejectsReadyRevisionWithoutReadableResidency) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto reconcile = metadata_store.PrepareReconcile(
+        ready.identity, ready.metadata_generation,
+        WeightAvailabilityState::READY, WeightResidencyState::ABSENT, 300);
+    ASSERT_TRUE(reconcile.has_value());
+
+    auto published = metadata_store.Publish(*reconcile);
+    ASSERT_FALSE(published.has_value());
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT, published.error());
+    EXPECT_EQ(WeightResidencyState::HOT,
+              metadata_store.Get(ready.identity, 300)->metadata.residency);
+}
+
+TEST(WeightMetadataStoreTest, CompletesResidencyOperationAndRetainsRecord) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto start = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(start.has_value());
+    auto operation = metadata_store.Publish(*start);
+    ASSERT_TRUE(operation.has_value());
+
+    auto finish = metadata_store.PrepareFinishOperation(
+        operation->operation_id, WeightResidencyState::COLD, 400);
+    ASSERT_TRUE(finish.has_value());
+    auto completed = metadata_store.Publish(*finish);
+    ASSERT_TRUE(completed.has_value());
+    EXPECT_EQ("completed", completed->message);
+
+    auto view = metadata_store.Get(ready.identity, 400);
+    ASSERT_TRUE(view.has_value());
+    EXPECT_EQ(WeightOperationState::NONE, view->metadata.operation);
+    EXPECT_EQ(0, view->metadata.operation_id);
+    EXPECT_EQ(WeightResidencyState::COLD, view->metadata.residency);
+    EXPECT_EQ(ready.metadata_generation + 2,
+              view->metadata.metadata_generation);
+    EXPECT_EQ(*completed,
+              *metadata_store.QueryOperation(completed->operation_id));
+}
+
+TEST(WeightMetadataStoreTest, OperationReplayAdvancesAllocatorWatermark) {
+    WeightMetadataStore source;
+    WeightMetadataStore replay_target;
+    auto source_ready = PublishReady(source);
+    auto target_ready = PublishReady(replay_target);
+    ASSERT_EQ(source_ready, target_ready);
+
+    auto replayed = source.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = source_ready.identity,
+            .expected_metadata_generation = source_ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(replayed.has_value());
+    ASSERT_TRUE(replay_target.Publish(*replayed).has_value());
+
+    const auto snapshot = replay_target.ExportSnapshot();
+    EXPECT_EQ(replayed->next->operation_id + 1, snapshot.next_operation_id);
+    WeightMetadataStore restored;
+    EXPECT_TRUE(restored.RestoreSnapshot(snapshot).has_value());
+
+    auto finished = replay_target.PrepareFinishOperation(
+        replayed->next->operation_id, WeightResidencyState::COLD, 400);
+    ASSERT_TRUE(finished.has_value());
+    ASSERT_TRUE(replay_target.Publish(*finished).has_value());
+    auto current = replay_target.Get(target_ready.identity, 400);
+    ASSERT_TRUE(current.has_value());
+    auto next = replay_target.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = target_ready.identity,
+            .expected_metadata_generation =
+                current->metadata.metadata_generation,
+            .target_residency = WeightResidencyState::HOT,
+        },
+        500);
+    ASSERT_TRUE(next.has_value());
+    EXPECT_NE(replayed->next->operation_id, next->next->operation_id);
+}
+
+TEST(WeightMetadataStoreTest, OperationReplayRejectsExhaustedAllocatorId) {
+    WeightMetadataStore source;
+    WeightMetadataStore replay_target;
+    auto ready = PublishReady(source);
+    ASSERT_EQ(ready, PublishReady(replay_target));
+
+    auto replayed = source.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(replayed.has_value());
+    const auto exhausted = std::numeric_limits<uint64_t>::max();
+    replayed->metadata.next->operation_id = exhausted;
+    replayed->next->operation_id = exhausted;
+
+    auto published = replay_target.Publish(*replayed);
+    ASSERT_FALSE(published.has_value());
+    EXPECT_EQ(WeightManagementError::GENERATION_EXHAUSTED, published.error());
+}
+
+TEST(WeightMetadataStoreTest, RestoresMultipleCompletedOperations) {
+    WeightMetadataStore metadata_store;
+    auto metadata = PublishReady(metadata_store);
+    for (const auto target :
+         {WeightResidencyState::COLD, WeightResidencyState::HOT}) {
+        auto start = metadata_store.PrepareStartOperation(
+            StartWeightResidencyOperationRequest{
+                .identity = metadata.identity,
+                .expected_metadata_generation = metadata.metadata_generation,
+                .target_residency = target,
+            },
+            300 + metadata.metadata_generation);
+        ASSERT_TRUE(start.has_value());
+        auto operation = metadata_store.Publish(*start);
+        ASSERT_TRUE(operation.has_value());
+        auto finish = metadata_store.PrepareFinishOperation(
+            operation->operation_id, target,
+            400 + metadata.metadata_generation);
+        ASSERT_TRUE(finish.has_value());
+        ASSERT_TRUE(metadata_store.Publish(*finish).has_value());
+        auto view = metadata_store.Get(metadata.identity, 500);
+        ASSERT_TRUE(view.has_value());
+        metadata = view->metadata;
+    }
+
+    WeightMetadataStore restored;
+    ASSERT_TRUE(
+        restored.RestoreSnapshot(metadata_store.ExportSnapshot()).has_value());
+    EXPECT_EQ(metadata, restored.Get(metadata.identity, 500)->metadata);
+    EXPECT_EQ("completed", restored.QueryOperation(1)->message);
+    EXPECT_EQ("completed", restored.QueryOperation(2)->message);
+}
+
+TEST(WeightMetadataStoreTest, RejectsUnknownSnapshotEnums) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto snapshot = metadata_store.ExportSnapshot();
+
+    snapshot.metadata[0].availability =
+        static_cast<WeightAvailabilityState>(255);
+    WeightMetadataStore restored;
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT,
+              restored.RestoreSnapshot(snapshot).error());
+
+    auto start = metadata_store.PrepareStartOperation(
+        StartWeightResidencyOperationRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+            .target_residency = WeightResidencyState::COLD,
+        },
+        300);
+    ASSERT_TRUE(start.has_value());
+    ASSERT_TRUE(metadata_store.Publish(*start).has_value());
+    snapshot = metadata_store.ExportSnapshot();
+    snapshot.operations[0].operation = static_cast<WeightOperationState>(255);
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT,
+              restored.RestoreSnapshot(snapshot).error());
+
+    snapshot = metadata_store.ExportSnapshot();
+    snapshot.operations[0].target_residency = WeightResidencyState::HOT;
+    EXPECT_EQ(WeightManagementError::INVALID_ARGUMENT,
+              restored.RestoreSnapshot(snapshot).error());
+}
+
+TEST(WeightMetadataStoreTest, DeleteRetainsAbsentTombstone) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto start = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+        },
+        300);
+    ASSERT_TRUE(start.has_value());
+    auto deleting = metadata_store.Publish(*start);
+    ASSERT_TRUE(deleting.has_value());
+    EXPECT_EQ(WeightAvailabilityState::DELETING, deleting->availability);
+
+    auto finish = metadata_store.PrepareFinishDelete(
+        ready.identity, deleting->metadata_generation, 400);
+    ASSERT_TRUE(finish.has_value());
+    auto deleted = metadata_store.Publish(*finish);
+    ASSERT_TRUE(deleted.has_value());
+    EXPECT_EQ(WeightAvailabilityState::DELETED, deleted->availability);
+    EXPECT_EQ(WeightResidencyState::ABSENT, deleted->residency);
+    EXPECT_TRUE(
+        metadata_store.IsManagedGroup(deleted->manifest.payload_group_id));
+}
+
+TEST(WeightMetadataStoreTest, DeletedTombstoneRetryRequiresGenerationFence) {
+    WeightMetadataStore metadata_store;
+    auto ready = PublishReady(metadata_store);
+    auto start = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = ready.metadata_generation,
+        },
+        300);
+    ASSERT_TRUE(start.has_value());
+    auto deleting = metadata_store.Publish(*start);
+    ASSERT_TRUE(deleting.has_value());
+    auto finish = metadata_store.PrepareFinishDelete(
+        ready.identity, deleting->metadata_generation, 400);
+    ASSERT_TRUE(finish.has_value());
+    auto deleted = metadata_store.Publish(*finish);
+    ASSERT_TRUE(deleted.has_value());
+
+    auto current = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = deleted->metadata_generation,
+        },
+        500);
+    ASSERT_TRUE(current.has_value());
+    EXPECT_TRUE(current->no_op);
+
+    auto adjacent = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = deleted->metadata_generation - 1,
+        },
+        500);
+    ASSERT_TRUE(adjacent.has_value());
+    EXPECT_TRUE(adjacent->no_op);
+
+    auto stale = metadata_store.PrepareDelete(
+        DeleteWeightRevisionRequest{
+            .identity = ready.identity,
+            .expected_metadata_generation = deleted->metadata_generation - 2,
+        },
+        500);
+    ASSERT_FALSE(stale.has_value());
+    EXPECT_EQ(WeightManagementError::STALE_GENERATION, stale.error());
+}
+
+TEST(WeightMetadataStoreTest, OnlyOneConcurrentCasCandidatePublishes) {
+    WeightMetadataStore metadata_store;
+    auto importing = PublishBegin(metadata_store, BeginRequest());
+    auto request = CommitWeightImportRequest{
+        .identity = importing.identity,
+        .expected_metadata_generation = importing.metadata_generation,
+        .manifest = Manifest(),
+    };
+    auto first = metadata_store.PrepareCommitImport(request, 200);
+    auto second = metadata_store.PrepareCommitImport(request, 201);
+    ASSERT_TRUE(first.has_value());
+    ASSERT_TRUE(second.has_value());
+
+    std::atomic<int> successes{0};
+    std::vector<std::thread> threads;
+    threads.emplace_back([&] {
+        if (metadata_store.Publish(*first).has_value()) {
+            ++successes;
+        }
+    });
+    threads.emplace_back([&] {
+        if (metadata_store.Publish(*second).has_value()) {
+            ++successes;
+        }
+    });
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    EXPECT_EQ(1, successes.load());
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-store/tests/zstd_util_test.cpp b/mooncake-store/tests/zstd_util_test.cpp
index 2edb5a0d41..9aba810082 100644
--- a/mooncake-store/tests/zstd_util_test.cpp
+++ b/mooncake-store/tests/zstd_util_test.cpp
@@ -5,7 +5,7 @@
 #include <string>
 #include <vector>
 
-#include "utils/zstd_util.h"
+#include "common/zstd_util.h"
 
 namespace mooncake::test {
 
diff --git a/mooncake-store/tools/oplog_batch_auditor.cpp b/mooncake-store/tools/oplog_batch_auditor.cpp
index fb3fea6a4b..e09360db1e 100644
--- a/mooncake-store/tools/oplog_batch_auditor.cpp
+++ b/mooncake-store/tools/oplog_batch_auditor.cpp
@@ -163,6 +163,7 @@ OpLogAuditReport AuditOpLogNamespace(const std::string& cluster_id,
             } else if (suffix.size() == kOpLogBatchIdWidth) {
                 AddError(&report, "malformed legacy key: " + kv.key);
             } else if (suffix != "latest" && !suffix.starts_with("snapshot/") &&
+                       !suffix.starts_with("producer_view") &&
                        !suffix.starts_with("cleanup/")) {
                 report.warnings.push_back("unknown OpLog key: " + kv.key);
             }
diff --git a/mooncake-transfer-engine/CMakeLists.txt b/mooncake-transfer-engine/CMakeLists.txt
index f43e814622..7d23d70dcb 100644
--- a/mooncake-transfer-engine/CMakeLists.txt
+++ b/mooncake-transfer-engine/CMakeLists.txt
@@ -10,6 +10,19 @@ if (NOT GLOBAL_CONFIG)
   include(../mooncake-common/FindJsonCpp.cmake)
   include(../mooncake-common/FindGLOG.cmake)
   include(../mooncake-common/common.cmake)
+  include(../cmake/Dependencies.cmake)
+
+  if(USE_REDIS)
+    mooncake_provide_hiredis(REQUIRED)
+  elseif(USE_TENT)
+    mooncake_provide_hiredis()
+  endif()
+  if(USE_TENT)
+    mooncake_provide_liburing()
+  endif()
+
+  add_subdirectory(../extern/pybind11
+                   ${CMAKE_CURRENT_BINARY_DIR}/extern/pybind11)
 
   # Build asio_shared in mooncake-common for standalone builds.
   # Set compile definitions before adding targets that include ASIO headers.
@@ -42,7 +55,6 @@ if (USE_CUDA)
       "CUDA IBGDA DMA-BUF DevX UMEM support disabled: the installed mlx5 headers or libmlx5 do not provide MLX5DV_UMEM_MASK_DMABUF, mlx5dv_devx_umem_in::dmabuf_fd, and mlx5dv_devx_umem_reg_ex. Update rdma-core/libmlx5 to enable DMA-BUF control memory; Device API will use GPU-VA and host-mapped fallback.")
   endif()
 endif()
-
 if (USE_ASCEND)
   include(../mooncake-common/FindMpi.cmake)
   file(GLOB ASCEND_TOOLKIT_ROOT "/usr/local/Ascend/ascend-toolkit/latest/*-linux")
diff --git a/mooncake-transfer-engine/benchmark/CMakeLists.txt b/mooncake-transfer-engine/benchmark/CMakeLists.txt
index e13773ec5b..43b41deda8 100644
--- a/mooncake-transfer-engine/benchmark/CMakeLists.txt
+++ b/mooncake-transfer-engine/benchmark/CMakeLists.txt
@@ -29,7 +29,8 @@ file(GLOB TEBENCH_SOURCES "*.cpp")
 # The TENT backend is only available when USE_TENT is enabled; drop its
 # translation unit (which pulls in tent/ headers) from non-TENT builds.
 if(NOT USE_TENT)
-  list(REMOVE_ITEM TEBENCH_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/tent_backend.cpp")
+  list(REMOVE_ITEM TEBENCH_SOURCES
+       "${CMAKE_CURRENT_SOURCE_DIR}/tent_backend.cpp")
   list(APPEND TEBENCH_SOURCES
        "${CMAKE_CURRENT_SOURCE_DIR}/../tent/src/common/qos_metrics.cpp")
 endif()
@@ -41,10 +42,11 @@ if(USE_TENT)
   target_link_libraries(tebench PUBLIC tent_link_group)
 else()
   # The classic backend still uses a couple of header-only helpers that live
-  # under tent/include (SimpleRandom in utils.h, bindToSocket in te_backend.cpp).
-  # Expose just the header path so tebench builds without the TENT library.
-  target_include_directories(tebench PRIVATE
-    "${CMAKE_CURRENT_SOURCE_DIR}/../tent/include")
+  # under tent/include (SimpleRandom in utils.h, bindToSocket in
+  # te_backend.cpp). Expose just the header path so tebench builds without the
+  # TENT library.
+  target_include_directories(
+    tebench PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/../tent/include")
 endif()
 if(USE_CUDA)
   target_link_libraries(tebench PUBLIC CUDA::cudart)
@@ -63,19 +65,21 @@ else()
   set(TANGRT_RPATH "")
 endif()
 set_target_properties(
-  tebench PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE
-                     INSTALL_RPATH "$ORIGIN/../lib:$ORIGIN/../../mooncake-common${TANGRT_RPATH}")
+  tebench
+  PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE
+             INSTALL_RPATH
+             "$ORIGIN/../lib:$ORIGIN/../../mooncake-common${TANGRT_RPATH}")
 
 if(BUILD_UNIT_TESTS)
-  add_executable(tebench_qos_metrics_test tests/qos_metrics_test.cpp
-                                          qos_metrics_adapter.cpp
-                                          workload_config.cpp utils.cpp)
+  add_executable(
+    tebench_qos_metrics_test tests/qos_metrics_test.cpp qos_metrics_adapter.cpp
+                             workload_config.cpp utils.cpp)
   if(NOT USE_TENT)
-    target_sources(tebench_qos_metrics_test PRIVATE
-                   ../tent/src/common/qos_metrics.cpp)
+    target_sources(tebench_qos_metrics_test
+                   PRIVATE ../tent/src/common/qos_metrics.cpp)
   endif()
-  target_link_libraries(tebench_qos_metrics_test
-                        PRIVATE transfer_engine gtest gtest_main)
+  target_link_libraries(tebench_qos_metrics_test PRIVATE transfer_engine gtest
+                                                         gtest_main)
   if(USE_TENT)
     target_link_libraries(tebench_qos_metrics_test PRIVATE tent_common)
   endif()
@@ -84,4 +88,24 @@ if(BUILD_UNIT_TESTS)
     PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}"
             "${CMAKE_CURRENT_SOURCE_DIR}/../tent/include")
   add_test(NAME tebench_qos_metrics_test COMMAND tebench_qos_metrics_test)
+
+  add_executable(tebench_target_metrics_test tests/target_metrics_test.cpp
+                                             target_metrics.cpp utils.cpp)
+  target_link_libraries(tebench_target_metrics_test PRIVATE transfer_engine
+                                                            gtest gtest_main)
+  if(USE_TENT)
+    target_link_libraries(tebench_target_metrics_test PRIVATE tent_common)
+  endif()
+  target_include_directories(
+    tebench_target_metrics_test
+    PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}"
+            "${CMAKE_CURRENT_SOURCE_DIR}/../tent/include")
+  add_test(NAME tebench_target_metrics_test COMMAND tebench_target_metrics_test)
+
+  add_executable(tebench_split_output_test tests/split_output_test.cpp
+                                           split_output.cpp)
+  target_link_libraries(tebench_split_output_test PRIVATE gtest gtest_main)
+  target_include_directories(tebench_split_output_test
+                             PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}")
+  add_test(NAME tebench_split_output_test COMMAND tebench_split_output_test)
 endif()
diff --git a/mooncake-transfer-engine/benchmark/bench_runner.h b/mooncake-transfer-engine/benchmark/bench_runner.h
index 0023ed0b72..2e66ef3210 100644
--- a/mooncake-transfer-engine/benchmark/bench_runner.h
+++ b/mooncake-transfer-engine/benchmark/bench_runner.h
@@ -54,12 +54,22 @@ class BenchRunner {
     virtual uint64_t getLocalBufferBase(int thread_id, uint64_t block_size,
                                         uint64_t batch_size) const = 0;
 
+    virtual size_t getTargetCount() const = 0;
+
+    virtual size_t getTargetIndex(int thread_id) const = 0;
+
+    virtual uint64_t getTargetSegmentId(int thread_id) const = 0;
+
     virtual uint64_t getTargetBufferBase(int thread_id, uint64_t block_size,
                                          uint64_t batch_size) const = 0;
 
-    virtual double runSingleTransfer(uint64_t local_addr, uint64_t target_addr,
-                                     uint64_t block_size, uint64_t batch_size,
-                                     OpCode opcode, uint64_t deadline_ns,
+    // Returns elapsed microseconds on success, or a negative value if the
+    // transfer failed. Implementations must not call exit() from worker
+    // threads.
+    virtual double runSingleTransfer(uint64_t local_addr, uint64_t target_id,
+                                     uint64_t target_addr, uint64_t block_size,
+                                     uint64_t batch_size, OpCode opcode,
+                                     uint64_t deadline_ns,
                                      IntentType intent_type) = 0;
 };
 
diff --git a/mooncake-transfer-engine/benchmark/main.cpp b/mooncake-transfer-engine/benchmark/main.cpp
index ad756e980b..adcefce123 100644
--- a/mooncake-transfer-engine/benchmark/main.cpp
+++ b/mooncake-transfer-engine/benchmark/main.cpp
@@ -13,56 +13,113 @@
 // limitations under the License.
 
 #include "utils.h"
+#include "split_output.h"
+#include "common.h"
 
 #include "bench_runner.h"
 #include "qos_metrics_adapter.h"
+#include "target_metrics.h"
 #include "te_backend.h"
 #include "workload_config.h"
 #ifdef USE_TENT
 #include "tent_backend.h"
 #endif
 
+#include <atomic>
+#include <mutex>
+#include <thread>
+
 using namespace mooncake::tent;
 
+uint64_t steadyClockNs() {
+    const auto now = std::chrono::steady_clock::now().time_since_epoch();
+    return std::chrono::duration_cast<std::chrono::nanoseconds>(now).count();
+}
+
+double gbPerSecond(uint64_t bytes, double duration_us) {
+    if (duration_us <= 0.0) return 0.0;
+    return static_cast<double>(bytes) / (1000.0 * duration_us);
+}
+
 int processBatchSizes(
     BenchRunner& runner, size_t block_size, size_t batch_size, int num_threads,
     const std::vector<QosClassConfig>& qos_classes,
     const std::vector<WorkloadClassConfig>& workload_classes = {}) {
     bool mixed_opcode = false;
+    bool write_seed = false;
+    bool read_verify = false;
     OpCode opcode = READ;
+    if (XferBenchConfig::check_consistency &&
+        (XferBenchConfig::op_type == "write_seed" ||
+         XferBenchConfig::op_type == "read_verify")) {
+        LOG(ERROR) << "--check_consistency cannot be combined with "
+                      "write_seed/read_verify";
+        exit(EXIT_FAILURE);
+    }
     if (XferBenchConfig::check_consistency || XferBenchConfig::op_type == "mix")
         mixed_opcode = true;
     else if (XferBenchConfig::op_type == "read")
         opcode = READ;
     else if (XferBenchConfig::op_type == "write")
         opcode = WRITE;
-    else {
-        LOG(ERROR) << "Invalid args: workload only support read|write|mix";
+    else if (XferBenchConfig::op_type == "write_seed") {
+        opcode = WRITE;
+        write_seed = true;
+    } else if (XferBenchConfig::op_type == "read_verify") {
+        opcode = READ;
+        read_verify = true;
+    } else {
+        LOG(ERROR) << "Invalid args: workload only support "
+                      "read|write|mix|write_seed|read_verify";
         exit(EXIT_FAILURE);
     }
 
     XferBenchStats stats;
     std::vector<XferBenchStats> qos_stats(qos_classes.size());
+    std::vector<TargetBenchStats> target_stats(runner.getTargetCount());
+    const auto target_names =
+        splitCommaSeparated(XferBenchConfig::target_seg_name);
+    LOG_ASSERT(target_names.size() == target_stats.size());
+    for (size_t i = 0; i < target_stats.size(); ++i)
+        target_stats[i].segment_name = target_names[i];
     XferBenchStats tight_stats;
     XferBenchStats loose_stats;
     std::mutex mutex;
+    std::atomic<int> measurement_ready{0};
+    std::atomic<bool> measurement_started{false};
+    auto paceRequest = [&]() {
+        if (XferBenchConfig::request_interval_us == 0) return;
+        const uint64_t interval_ns =
+            XferBenchConfig::request_interval_us * 1000ull;
+        const uint64_t target_ns = steadyClockNs() + interval_ns;
+        while (steadyClockNs() < target_ns) {
+            std::this_thread::yield();
+        }
+    };
     size_t address_stride_bytes =
         XferBenchConfig::max_block_size * XferBenchConfig::max_batch_size;
     if (!workload_classes.empty()) {
         address_stride_bytes = 0;
         for (const auto& config : workload_classes) {
-            address_stride_bytes = std::max(
-                address_stride_bytes, config.block_size * config.batch_size);
+            address_stride_bytes =
+                std::max(address_stride_bytes,
+                         checkedMul(config.block_size, config.batch_size,
+                                    "workload address stride"));
         }
     }
     int rc = runner.runInitiatorTasks([&](int thread_id) -> int {
         runner.pinThread(thread_id);
         auto local_gpu_offset = std::max(0, XferBenchConfig::local_gpu_id);
         auto target_gpu_offset = std::max(0, XferBenchConfig::target_gpu_id);
+        const int target_thread_id =
+            static_cast<int>(target_gpu_offset * runner.getTargetCount()) +
+            thread_id;
         uint64_t local_addr = runner.getLocalBufferBase(
             local_gpu_offset + thread_id, address_stride_bytes, 1);
         uint64_t target_addr = runner.getTargetBufferBase(
-            target_gpu_offset + thread_id, address_stride_bytes, 1);
+            target_thread_id, address_stride_bytes, 1);
+        uint64_t target_id = runner.getTargetSegmentId(target_thread_id);
+        const size_t target_index = runner.getTargetIndex(target_thread_id);
         const bool qos_enabled = !qos_classes.empty();
         const size_t qos_class =
             qos_enabled ? qosClassForThread(qos_classes, thread_id) : 0;
@@ -88,51 +145,111 @@ int processBatchSizes(
                    deadline_us * 1000ull;
         };
 
+        auto failTask = [&]() {
+            measurement_started.store(true, std::memory_order_release);
+            return -1;
+        };
+
         XferBenchTimer timer;
         while (timer.lap_us(false) < 1000000ull) {
-            runner.runSingleTransfer(local_addr, target_addr, thread_block_size,
-                                     thread_batch_size, opcode, deadlineNs(),
-                                     intent_type);
+            if (runner.runSingleTransfer(
+                    local_addr, target_id, target_addr, thread_block_size,
+                    thread_batch_size, opcode, deadlineNs(), intent_type) < 0) {
+                return failTask();
+            }
+        }
+        if (measurement_ready.fetch_add(1, std::memory_order_acq_rel) + 1 ==
+            num_threads) {
+            measurement_started.store(true, std::memory_order_release);
+        } else {
+            while (!measurement_started.load(std::memory_order_acquire)) {
+                std::this_thread::yield();
+            }
         }
         timer.reset();
         std::vector<double> transfer_duration;
+        std::vector<double> thread_instant_bandwidth;
         if (mixed_opcode) {
             while (timer.lap_us(false) <
                    XferBenchConfig::duration * 1000000ull) {
+                const size_t bytes =
+                    checkedMul(thread_block_size, thread_batch_size,
+                               "consistency payload size");
+                const uint64_t batch_bytes = bytes;
                 uint8_t pattern = 0;
                 if (XferBenchConfig::check_consistency)
-                    pattern = fillData((void*)local_addr,
-                                       thread_block_size * thread_batch_size);
+                    pattern = fillData((void*)local_addr, bytes);
+                paceRequest();
                 auto val = runner.runSingleTransfer(
-                    local_addr, target_addr, thread_block_size,
+                    local_addr, target_id, target_addr, thread_block_size,
                     thread_batch_size, WRITE, deadlineNs(), intent_type);
+                if (val < 0) return failTask();
+                thread_instant_bandwidth.push_back(
+                    gbPerSecond(batch_bytes, val));
                 transfer_duration.push_back(val);
-                fillData((void*)local_addr,
-                         thread_block_size * thread_batch_size);
+                fillData((void*)local_addr, bytes);
+                paceRequest();
                 val = runner.runSingleTransfer(
-                    local_addr, target_addr, thread_block_size,
+                    local_addr, target_id, target_addr, thread_block_size,
                     thread_batch_size, READ, deadlineNs(), intent_type);
+                if (val < 0) return failTask();
+                thread_instant_bandwidth.push_back(
+                    gbPerSecond(batch_bytes, val));
                 if (XferBenchConfig::check_consistency)
                     verifyData((void*)local_addr,
-                               thread_block_size * thread_batch_size, pattern);
+                               checkedMul(thread_block_size, thread_batch_size,
+                                          "consistency payload size"),
+                               pattern);
                 transfer_duration.push_back(val);
             }
         } else {
             while (timer.lap_us(false) <
                    XferBenchConfig::duration * 1000000ull) {
+                const size_t bytes =
+                    checkedMul(thread_block_size, thread_batch_size,
+                               "operation payload size");
+                const uint64_t batch_bytes = bytes;
+                if (write_seed) {
+                    fillData((void*)local_addr, bytes,
+                             stableDataSeed(target_addr));
+                }
+                paceRequest();
                 auto val = runner.runSingleTransfer(
-                    local_addr, target_addr, thread_block_size,
+                    local_addr, target_id, target_addr, thread_block_size,
                     thread_batch_size, opcode, deadlineNs(), intent_type);
+                if (val < 0) return failTask();
+                thread_instant_bandwidth.push_back(
+                    gbPerSecond(batch_bytes, val));
+                if (read_verify) {
+                    verifyData((void*)local_addr, bytes,
+                               stableDataSeed(target_addr));
+                }
                 transfer_duration.push_back(val);
             }
         }
         auto total_duration = timer.lap_us();
+        const uint64_t bytes_per_operation = checkedMul(
+            thread_block_size, thread_batch_size, "operation payload size");
+        const uint64_t transferred_bytes =
+            checkedMul(bytes_per_operation, transfer_duration.size(),
+                       "thread transferred bytes");
         std::lock_guard<std::mutex> lock(mutex);
         stats.total_duration.add(total_duration);
         stats.transfer_duration.add(transfer_duration);
+        stats.instant_bandwidth.add(thread_instant_bandwidth);
+        auto& target = target_stats[target_index];
+        ++target.threads;
+        target.transferred_bytes =
+            checkedAdd(target.transferred_bytes, transferred_bytes,
+                       "target transferred bytes");
+        target.stats.total_duration.add(total_duration);
+        target.stats.transfer_duration.add(transfer_duration);
+        target.stats.instant_bandwidth.add(thread_instant_bandwidth);
         if (qos_enabled) {
             qos_stats[qos_class].total_duration.add(total_duration);
             qos_stats[qos_class].transfer_duration.add(transfer_duration);
+            qos_stats[qos_class].instant_bandwidth.add(
+                thread_instant_bandwidth);
         }
         auto& group_stats = tight ? tight_stats : loose_stats;
         group_stats.total_duration.add(total_duration);
@@ -143,6 +260,18 @@ int processBatchSizes(
     if (rc != 0) return -1;
     if (workload_classes.empty())
         printStats(block_size, batch_size, stats, num_threads);
+    auto target_report = calculateTargetMetrics(
+        block_size, batch_size, num_threads, XferBenchConfig::backend,
+        XferBenchConfig::op_type, &target_stats);
+    if (runner.getTargetCount() > 1) printTargetMetrics(target_report);
+    if (!XferBenchConfig::result_output_jsonl.empty()) {
+        std::string error;
+        if (!appendTargetMetricsJsonl(XferBenchConfig::result_output_jsonl,
+                                      target_report, &error)) {
+            LOG(ERROR) << error;
+            return -1;
+        }
+    }
     if (!qos_classes.empty()) {
         std::vector<uint64_t> bytes_per_operation;
         for (const auto& config : workload_classes) {
@@ -179,6 +308,40 @@ int main(int argc, char* argv[]) {
         "Usage: ./tebench [options]");
     gflags::ParseCommandLineFlags(&argc, &argv, true);
     XferBenchConfig::loadFromFlags();
+    if (!XferBenchConfig::split_output_jsonl.empty()) {
+        std::string error;
+        if (!openSplitOutput(XferBenchConfig::split_output_jsonl, &error)) {
+            LOG(ERROR) << error;
+            return EXIT_FAILURE;
+        }
+    }
+    if (XferBenchConfig::use_hugepage) {
+        if (XferBenchConfig::backend != "classic" ||
+            (XferBenchConfig::xport_type != "shm" &&
+             XferBenchConfig::xport_type != "rdma")) {
+            LOG(ERROR) << "--use_hugepage requires --backend=classic and "
+                          "--xport_type=shm or rdma";
+            return EXIT_FAILURE;
+        }
+        if (XferBenchConfig::hugepage_size == static_cast<size_t>(-1)) {
+            LOG(ERROR) << "--hugepage_size must be 2MB, 512MB, 1GB, or a byte "
+                          "count (2097152, 536870912, 1073741824)";
+            return EXIT_FAILURE;
+        }
+        const size_t hp = XferBenchConfig::hugepage_size == 0
+                              ? mooncake::SharedMemoryOptions::kHugepage2MB
+                              : XferBenchConfig::hugepage_size;
+        if (!mooncake::SharedMemoryOptions::isSupportedHugepageSize(hp)) {
+            LOG(ERROR) << "--hugepage_size must be 2MB, 512MB, 1GB, or a byte "
+                          "count (2097152, 536870912, 1073741824)";
+            return EXIT_FAILURE;
+        }
+        if (XferBenchConfig::total_buffer_size % hp != 0) {
+            LOG(ERROR) << "--total_buffer_size must be a multiple of "
+                          "hugepage_size";
+            return EXIT_FAILURE;
+        }
+    }
     std::vector<WorkloadClassConfig> workload_classes;
     std::vector<QosClassConfig> qos_classes;
     if (!XferBenchConfig::workload_classes_json.empty() &&
@@ -321,8 +484,16 @@ int main(int argc, char* argv[]) {
             for (size_t batch_size = XferBenchConfig::start_batch_size;
                  !interrupted && batch_size <= XferBenchConfig::max_batch_size;
                  batch_size *= 2) {
-                if (block_size * batch_size * num_threads >
-                    XferBenchConfig::total_buffer_size) {
+                const size_t bytes_per_thread = checkedMul(
+                    block_size, batch_size, "benchmark operation size");
+                if (XferBenchConfig::target_range_size != 0 &&
+                    bytes_per_thread > XferBenchConfig::target_range_size) {
+                    LOG(ERROR) << "target range is smaller than one operation";
+                    interrupted = true;
+                } else if (num_threads != 0 &&
+                           bytes_per_thread >
+                               XferBenchConfig::total_buffer_size /
+                                   num_threads) {
                     LOG(INFO) << "Skipped for block_size " << block_size
                               << " batch_size " << batch_size;
                 } else {
@@ -334,5 +505,5 @@ int main(int argc, char* argv[]) {
         }
         runner->stopInitiator();
     }
-    return 0;
+    return interrupted ? EXIT_FAILURE : EXIT_SUCCESS;
 }
diff --git a/mooncake-transfer-engine/benchmark/split_output.cpp b/mooncake-transfer-engine/benchmark/split_output.cpp
new file mode 100644
index 0000000000..0c268c9cb3
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/split_output.cpp
@@ -0,0 +1,90 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "split_output.h"
+
+#include <cinttypes>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <memory>
+#include <mutex>
+
+namespace mooncake {
+namespace tent {
+
+bool g_split_output_enabled = false;
+
+namespace {
+
+std::unique_ptr<std::ofstream> g_split_output;
+std::mutex g_split_output_mu;
+
+}  // namespace
+
+bool formatSplitXferLine(char* buf, size_t cap, const SplitXferSample& sample,
+                         size_t* written) {
+    if (buf == nullptr || written == nullptr || cap == 0) return false;
+    const int n = std::snprintf(
+        buf, cap,
+        "{\"batch_size\":%" PRIu64 ",\"submit_us\":%" PRIu64
+        ",\"wait_us\":%" PRIu64 ",\"polls\":%" PRIu64 "}\n",
+        sample.batch_size, sample.submit_us, sample.wait_us, sample.polls);
+    if (n < 0 || static_cast<size_t>(n) >= cap) return false;
+    *written = static_cast<size_t>(n);
+    return true;
+}
+
+bool openSplitOutput(const std::string& path, std::string* error) {
+    closeSplitOutput();
+    auto out =
+        std::make_unique<std::ofstream>(path, std::ios::out | std::ios::app);
+    if (!*out) {
+        if (error != nullptr) {
+            *error = "failed to open split JSONL output: " + path;
+        }
+        return false;
+    }
+    std::lock_guard<std::mutex> lock(g_split_output_mu);
+    g_split_output = std::move(out);
+    g_split_output_enabled = true;
+    static bool registered_atexit = false;
+    if (!registered_atexit) {
+        std::atexit(closeSplitOutput);
+        registered_atexit = true;
+    }
+    return true;
+}
+
+void closeSplitOutput() {
+    std::lock_guard<std::mutex> lock(g_split_output_mu);
+    g_split_output_enabled = false;
+    if (g_split_output) {
+        g_split_output->flush();
+        g_split_output.reset();
+    }
+}
+
+void logSplitXfer(const SplitXferSample& sample) {
+    if (!g_split_output_enabled) return;
+    char buf[160];
+    size_t n = 0;
+    if (!formatSplitXferLine(buf, sizeof(buf), sample, &n)) return;
+    std::lock_guard<std::mutex> lock(g_split_output_mu);
+    if (!g_split_output || !*g_split_output) return;
+    g_split_output->write(buf, static_cast<std::streamsize>(n));
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/benchmark/split_output.h b/mooncake-transfer-engine/benchmark/split_output.h
new file mode 100644
index 0000000000..d8e63989e1
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/split_output.h
@@ -0,0 +1,51 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TEBENCH_SPLIT_OUTPUT_H
+#define TEBENCH_SPLIT_OUTPUT_H
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+
+namespace mooncake {
+namespace tent {
+
+struct SplitXferSample {
+    uint64_t batch_size;
+    uint64_t submit_us;
+    uint64_t wait_us;
+    uint64_t polls;
+};
+
+// False when --split_output_jsonl is unset. Check this in the transfer hot
+// path so a disabled log does not call getenv, open a file, or start extra
+// timers.
+extern bool g_split_output_enabled;
+
+inline bool splitOutputEnabled() noexcept { return g_split_output_enabled; }
+
+bool formatSplitXferLine(char* buf, size_t cap, const SplitXferSample& sample,
+                         size_t* written);
+
+bool openSplitOutput(const std::string& path, std::string* error);
+void closeSplitOutput();
+
+// One buffered write. Call only after splitOutputEnabled() is true.
+void logSplitXfer(const SplitXferSample& sample);
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif
diff --git a/mooncake-transfer-engine/benchmark/target_metrics.cpp b/mooncake-transfer-engine/benchmark/target_metrics.cpp
new file mode 100644
index 0000000000..adf471e755
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/target_metrics.cpp
@@ -0,0 +1,146 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "target_metrics.h"
+
+#include <fstream>
+#include <iomanip>
+#include <iostream>
+
+#include "tent/thirdparty/nlohmann/json.h"
+
+namespace mooncake {
+namespace tent {
+
+TargetMetricsReport calculateTargetMetrics(
+    size_t block_size, size_t batch_size, int num_threads,
+    const std::string& backend, const std::string& op_type,
+    std::vector<TargetBenchStats>* stats) {
+    TargetMetricsReport report;
+    report.block_size = block_size;
+    report.batch_size = batch_size;
+    report.num_threads = num_threads;
+    report.backend = backend;
+    report.op_type = op_type;
+    report.targets.reserve(stats->size());
+    double aggregate_duration_sum_us = 0.0;
+    int assigned_threads = 0;
+
+    for (size_t i = 0; i < stats->size(); ++i) {
+        auto& input = (*stats)[i];
+        TargetMetrics metrics;
+        metrics.index = i;
+        metrics.segment_name = input.segment_name;
+        metrics.threads = input.threads;
+        metrics.operations = input.stats.transfer_duration.count();
+        metrics.transferred_bytes = input.transferred_bytes;
+        metrics.total_duration_us = input.stats.total_duration.avg();
+        metrics.avg_transfer_us = input.stats.transfer_duration.avg();
+        metrics.p99_us = input.stats.transfer_duration.p99();
+        metrics.p999_us = input.stats.transfer_duration.p999();
+        metrics.avg_instant_gbps = input.stats.instant_bandwidth.avg();
+        if (metrics.operations != 0) {
+            metrics.avg_latency_us = metrics.total_duration_us *
+                                     metrics.threads / metrics.operations;
+        }
+        if (metrics.total_duration_us > 0.0) {
+            metrics.throughput_gbps =
+                static_cast<double>(metrics.transferred_bytes) / 1000.0 /
+                metrics.total_duration_us;
+        }
+        report.aggregate_operations =
+            checkedAdd(report.aggregate_operations, metrics.operations,
+                       "aggregate operations");
+        report.aggregate_transferred_bytes = checkedAdd(
+            report.aggregate_transferred_bytes, metrics.transferred_bytes,
+            "aggregate transferred bytes");
+        aggregate_duration_sum_us +=
+            metrics.total_duration_us * metrics.threads;
+        assigned_threads += metrics.threads;
+        report.targets.push_back(std::move(metrics));
+    }
+    if (assigned_threads > 0 && aggregate_duration_sum_us > 0.0) {
+        const double aggregate_duration_us =
+            aggregate_duration_sum_us / assigned_threads;
+        report.aggregate_throughput_gbps =
+            static_cast<double>(report.aggregate_transferred_bytes) / 1000.0 /
+            aggregate_duration_us;
+    }
+    return report;
+}
+
+void printTargetMetrics(const TargetMetricsReport& report) {
+    for (const auto& metrics : report.targets) {
+        std::cout << "  [target-summary] index=" << metrics.index
+                  << " name=" << metrics.segment_name
+                  << " threads=" << metrics.threads
+                  << " operations=" << metrics.operations
+                  << " transferred_bytes=" << metrics.transferred_bytes
+                  << " throughput=" << std::fixed << std::setprecision(6)
+                  << metrics.throughput_gbps
+                  << " GB/s p99_us=" << std::setprecision(1) << metrics.p99_us
+                  << std::endl;
+    }
+}
+
+bool appendTargetMetricsJsonl(const std::string& path,
+                              const TargetMetricsReport& report,
+                              std::string* error) {
+    nlohmann::json root = {
+        {"schema_version", 1},
+        {"record_type", "target_metrics"},
+        {"backend", report.backend},
+        {"op_type", report.op_type},
+        {"block_size", report.block_size},
+        {"batch_size", report.batch_size},
+        {"num_threads", report.num_threads},
+        {"aggregate_operations", report.aggregate_operations},
+        {"aggregate_transferred_bytes", report.aggregate_transferred_bytes},
+        {"aggregate_throughput_gbps", report.aggregate_throughput_gbps},
+        {"targets", nlohmann::json::array()},
+    };
+    for (const auto& metrics : report.targets) {
+        root["targets"].push_back({
+            {"index", metrics.index},
+            {"segment_name", metrics.segment_name},
+            {"threads", metrics.threads},
+            {"operations", metrics.operations},
+            {"transferred_bytes", metrics.transferred_bytes},
+            {"total_duration_us", metrics.total_duration_us},
+            {"throughput_gbps", metrics.throughput_gbps},
+            {"avg_latency_us", metrics.avg_latency_us},
+            {"avg_transfer_us", metrics.avg_transfer_us},
+            {"p99_us", metrics.p99_us},
+            {"p999_us", metrics.p999_us},
+            {"avg_instant_gbps", metrics.avg_instant_gbps},
+        });
+    }
+
+    std::ofstream output(path, std::ios::app);
+    if (!output) {
+        *error = "failed to open target JSONL output: " + path;
+        return false;
+    }
+    output << root.dump() << '\n';
+    // Closing flushes buffered output and can reveal delayed write errors.
+    output.close();
+    if (!output) {
+        *error = "failed to write target JSONL output: " + path;
+        return false;
+    }
+    return true;
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/benchmark/target_metrics.h b/mooncake-transfer-engine/benchmark/target_metrics.h
new file mode 100644
index 0000000000..333367edf6
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/target_metrics.h
@@ -0,0 +1,75 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TEBENCH_TARGET_METRICS_H
+#define TEBENCH_TARGET_METRICS_H
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "utils.h"
+
+namespace mooncake {
+namespace tent {
+
+struct TargetBenchStats {
+    std::string segment_name;
+    int threads = 0;
+    uint64_t transferred_bytes = 0;
+    XferBenchStats stats;
+};
+
+struct TargetMetrics {
+    size_t index = 0;
+    std::string segment_name;
+    int threads = 0;
+    uint64_t operations = 0;
+    uint64_t transferred_bytes = 0;
+    double total_duration_us = 0.0;
+    double throughput_gbps = 0.0;
+    double avg_latency_us = 0.0;
+    double avg_transfer_us = 0.0;
+    double p99_us = 0.0;
+    double p999_us = 0.0;
+    double avg_instant_gbps = 0.0;
+};
+
+struct TargetMetricsReport {
+    size_t block_size = 0;
+    size_t batch_size = 0;
+    int num_threads = 0;
+    std::string backend;
+    std::string op_type;
+    uint64_t aggregate_operations = 0;
+    uint64_t aggregate_transferred_bytes = 0;
+    double aggregate_throughput_gbps = 0.0;
+    std::vector<TargetMetrics> targets;
+};
+
+TargetMetricsReport calculateTargetMetrics(
+    size_t block_size, size_t batch_size, int num_threads,
+    const std::string& backend, const std::string& op_type,
+    std::vector<TargetBenchStats>* stats);
+
+void printTargetMetrics(const TargetMetricsReport& report);
+
+bool appendTargetMetricsJsonl(const std::string& path,
+                              const TargetMetricsReport& report,
+                              std::string* error);
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TEBENCH_TARGET_METRICS_H
diff --git a/mooncake-transfer-engine/benchmark/te_backend.cpp b/mooncake-transfer-engine/benchmark/te_backend.cpp
index 5e3632aa46..27e64e36a9 100644
--- a/mooncake-transfer-engine/benchmark/te_backend.cpp
+++ b/mooncake-transfer-engine/benchmark/te_backend.cpp
@@ -16,9 +16,13 @@
 
 #include "te_backend.h"
 #include "utils.h"
+#include "split_output.h"
 #include "common.h"
 #include "char_util.h"
 
+#include <linux/mman.h>
+#include <sys/mman.h>
+
 #if defined(USE_CUDA)
 #include <bits/stdint-uintn.h>
 #include <cuda.h>
@@ -125,6 +129,105 @@ static void* allocateMemoryPool(size_t size, int buffer_id,
     return numa_alloc_onnode(size, buffer_id);
 }
 
+static int parseIndex(const std::string& loc) {
+    auto pos = loc.find(':');
+    if (pos == std::string::npos || pos + 1 >= loc.size()) {
+        throw std::invalid_argument("Invalid loc format: " + loc);
+    }
+    return std::stoi(loc.substr(pos + 1));
+}
+
+// POSIX shm mmap does not place pages. Bind the mapping before first touch
+// so DRAM buffers land on the same node as numa_alloc_onnode(size, node).
+static void bindShmBufferToNode(void* addr, size_t size, int node) {
+    if (!addr || size == 0) return;
+    if (numa_available() < 0) {
+        LOG(WARNING)
+            << "tebench: NUMA unavailable; shm buffer not bound to cpu:"
+            << node;
+        return;
+    }
+    if (node < 0 || node >= numa_num_configured_nodes()) {
+        LOG(WARNING) << "tebench: invalid NUMA node " << node;
+        return;
+    }
+    numa_tonode_memory(addr, size, node);
+    const long page_size = sysconf(_SC_PAGESIZE);
+    auto* p = static_cast<char*>(addr);
+    if (page_size > 0) {
+        for (size_t off = 0; off < size; off += static_cast<size_t>(page_size))
+            p[off] = 0;
+    }
+    p[size - 1] = 0;
+}
+
+static std::string cpuLocationFromPages(void* addr, int expected_node) {
+    const auto expected = "cpu:" + std::to_string(expected_node);
+    const auto entries = getMemoryLocation(addr, 1, true);
+    if (entries.empty() || entries[0].location.rfind("cpu:", 0) != 0) {
+        LOG(WARNING) << "tebench: could not resolve NUMA node for shm buffer, "
+                        "registering as "
+                     << expected;
+        return expected;
+    }
+    if (parseIndex(entries[0].location) != expected_node) {
+        LOG(WARNING) << "tebench: shm buffer intended for " << expected
+                     << " is on " << entries[0].location;
+    }
+    return entries[0].location;
+}
+
+#ifndef MAP_HUGE_2MB
+#define MAP_HUGE_2MB (21 << 26)
+#endif
+#ifndef MAP_HUGE_1GB
+#define MAP_HUGE_1GB (30 << 26)
+#endif
+#ifndef MAP_HUGE_512MB
+#define MAP_HUGE_512MB (29 << 26)
+#endif
+
+static size_t hugepageBytes() {
+    return XferBenchConfig::hugepage_size == 0
+               ? mooncake::SharedMemoryOptions::kHugepage2MB
+               : XferBenchConfig::hugepage_size;
+}
+
+static int hugepageMmapFlags(size_t hp) {
+    int flags = MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB | MAP_POPULATE;
+    if (hp == mooncake::SharedMemoryOptions::kHugepage2MB)
+        flags |= MAP_HUGE_2MB;
+    else if (hp == mooncake::SharedMemoryOptions::kHugepage512MB)
+        flags |= MAP_HUGE_512MB;
+    else if (hp == mooncake::SharedMemoryOptions::kHugepage1GB)
+        flags |= MAP_HUGE_1GB;
+    return flags;
+}
+
+static void* allocateHugepageOnNode(size_t size, int node) {
+    const size_t hp = hugepageBytes();
+    if (hp == 0 || size % hp != 0) {
+        LOG(ERROR) << "RDMA hugepage buffer " << size
+                   << " is not a multiple of hugepage size " << hp;
+        return nullptr;
+    }
+    void* buf = mmap(nullptr, size, PROT_READ | PROT_WRITE,
+                     hugepageMmapFlags(hp), -1, 0);
+    if (buf == MAP_FAILED) {
+        PLOG(ERROR) << "MAP_HUGETLB mmap failed for " << size
+                    << " bytes (hp=" << hp
+                    << "); refusing 4K fallback to avoid blowing NIC PTEs";
+        return nullptr;
+    }
+    if (numa_available() >= 0 && node >= 0) {
+        numa_tonode_memory(buf, size, node);
+    }
+    auto* p = static_cast<char*>(buf);
+    for (size_t off = 0; off < size; off += hp) p[off] = 0;
+    if (size > 0) p[size - 1] = 0;
+    return buf;
+}
+
 static void freeMemoryPool(void* addr, size_t size) {
 #if defined(USE_CUDA) && defined(USE_MNNVL)
     CUmemGenericAllocationHandle handle;
@@ -153,16 +256,56 @@ static void freeMemoryPool(void* addr, size_t size) {
 
 int TEBenchRunner::allocateBuffers() {
     auto total_buffer_size = XferBenchConfig::total_buffer_size;
+    const bool use_shm = engine_->getTransport("shm") != nullptr;
     if (XferBenchConfig::seg_type == "DRAM") {
         int num_buffers = numa_num_configured_nodes();
         pinned_buffer_list_.resize(num_buffers, nullptr);
+        shm_backed_.assign(num_buffers, 0);
+        hugepage_backed_.assign(num_buffers, 0);
         for (int i = 0; i < num_buffers; ++i) {
-            auto location = "cpu:" + std::to_string(i);
-            pinned_buffer_list_[i] =
-                allocateMemoryPool(total_buffer_size, i, false);
+            std::string location = "cpu:" + std::to_string(i);
+            if (use_shm) {
+                mooncake::SharedMemoryOptions opt;
+                if (XferBenchConfig::use_hugepage) {
+                    opt.use_hugepage = true;
+                    opt.hugepage_size = XferBenchConfig::hugepage_size;
+                    opt.hugetlbfs_path = XferBenchConfig::hugetlbfs_path;
+                }
+                pinned_buffer_list_[i] =
+                    engine_->allocateSharedMemory(total_buffer_size, opt);
+                shm_backed_[i] = 1;
+                if (pinned_buffer_list_[i]) {
+                    bindShmBufferToNode(pinned_buffer_list_[i],
+                                        total_buffer_size, i);
+                    location = cpuLocationFromPages(pinned_buffer_list_[i], i);
+                }
+            } else if (XferBenchConfig::use_hugepage) {
+                pinned_buffer_list_[i] =
+                    allocateHugepageOnNode(total_buffer_size, i);
+                hugepage_backed_[i] = 1;
+                if (pinned_buffer_list_[i]) {
+                    location = cpuLocationFromPages(pinned_buffer_list_[i], i);
+                }
+            } else {
+                pinned_buffer_list_[i] =
+                    allocateMemoryPool(total_buffer_size, i, false);
+            }
             if (!pinned_buffer_list_[i]) return -1;
-            engine_->registerLocalMemory(pinned_buffer_list_[i],
-                                         total_buffer_size, location);
+            if (engine_->registerLocalMemory(pinned_buffer_list_[i],
+                                             total_buffer_size, location)) {
+                LOG(ERROR) << "Failed to register DRAM buffer " << i;
+                return -1;
+            }
+        }
+        if (use_shm) {
+            LOG(INFO) << "tebench: DRAM buffers allocated from "
+                      << (XferBenchConfig::use_hugepage ? "hugetlbfs"
+                                                        : "POSIX shm")
+                      << " and bound to NUMA nodes";
+        } else if (XferBenchConfig::use_hugepage) {
+            LOG(INFO) << "tebench: DRAM buffers allocated with MAP_HUGETLB "
+                         "hugepages (hp="
+                      << hugepageBytes() << ") for RDMA MR registration";
         }
 #if defined(USE_CUDA) || defined(USE_SUNRISE)
     } else if (XferBenchConfig::seg_type == "VRAM") {
@@ -197,21 +340,38 @@ int TEBenchRunner::freeBuffers() {
     auto total_buffer_size = XferBenchConfig::total_buffer_size;
     for (size_t i = 0; i < pinned_buffer_list_.size(); ++i) {
         if (!pinned_buffer_list_[i]) continue;
-        engine_->unregisterLocalMemory(pinned_buffer_list_[i]);
-        freeMemoryPool(pinned_buffer_list_[i], total_buffer_size);
+        if (i < shm_backed_.size() && shm_backed_[i]) {
+            engine_->freeSharedMemory(pinned_buffer_list_[i]);
+        } else {
+            engine_->unregisterLocalMemory(pinned_buffer_list_[i]);
+            if (i < hugepage_backed_.size() && hugepage_backed_[i]) {
+                if (munmap(pinned_buffer_list_[i], total_buffer_size) != 0) {
+                    PLOG(WARNING) << "munmap hugepage buffer failed";
+                }
+            } else {
+                freeMemoryPool(pinned_buffer_list_[i], total_buffer_size);
+            }
+        }
     }
     pinned_buffer_list_.clear();
+    shm_backed_.clear();
+    hugepage_backed_.clear();
     return 0;
 }
 
 TEBenchRunner::TEBenchRunner() {
     signal(SIGINT, signalHandlerV0);
     signal(SIGTERM, signalHandlerV0);
-    engine_ = std::make_unique<mooncake::TransferEngine>(true);
+    // Disable auto-discovery when an explicit non-RDMA xport is requested
+    // (e.g. flagcx, shm) so we can installTransport() ourselves below.
+    bool auto_disc = XferBenchConfig::xport_type != "flagcx" &&
+                     XferBenchConfig::xport_type != "shm";
+    engine_ = std::make_unique<mooncake::TransferEngine>(auto_disc);
     auto conn_str = XferBenchConfig::metadata_type == "p2p"
                         ? "P2PHANDSHAKE"
                         : XferBenchConfig::metadata_url_list;
-    auto seg_name = XferBenchConfig::metadata_type == "p2p"
+    auto seg_name = (XferBenchConfig::metadata_type == "p2p" &&
+                     XferBenchConfig::seg_name.empty())
                         ? mooncake::getHostname()
                         : XferBenchConfig::seg_name;
     engine_->init(conn_str, seg_name);
@@ -224,6 +384,18 @@ TEBenchRunner::TEBenchRunner() {
     LOG_ASSERT(sunrise_transport != nullptr)
         << "Failed to install SunriseLink transport";
 #endif
+    if (XferBenchConfig::xport_type == "flagcx") {
+        auto* xp = engine_->installTransport("flagcx", nullptr);
+        LOG_ASSERT(xp) << "installTransport(flagcx) failed";
+        LOG(INFO) << "tebench: FlagCX transport installed";
+    }
+    if (XferBenchConfig::xport_type == "shm") {
+        if (!engine_->getTransport("shm")) {
+            auto* shm = engine_->installTransport("shm", nullptr);
+            LOG_ASSERT(shm) << "installTransport(shm) failed";
+        }
+        LOG(INFO) << "tebench: SHM transport installed";
+    }
     init_ok_ = (allocateBuffers() == 0);
     if (!init_ok_) {
         LOG(ERROR) << "TEBenchRunner initialization failed";
@@ -242,17 +414,47 @@ int TEBenchRunner::runTarget() {
     return 0;
 }
 
+size_t TEBenchRunner::targetIndex(int thread_id) const {
+    LOG_ASSERT(!target_handles_.empty());
+    return static_cast<size_t>(thread_id) % target_handles_.size();
+}
+
+int TEBenchRunner::localTargetThreadId(int thread_id) const {
+    LOG_ASSERT(!target_handles_.empty());
+    return thread_id / static_cast<int>(target_handles_.size());
+}
+
+uint64_t TEBenchRunner::getTargetSegmentId(int thread_id) const {
+    return target_handles_[targetIndex(thread_id)];
+}
+
+size_t TEBenchRunner::getTargetCount() const {
+    return std::max<size_t>(target_handles_.size(), 1);
+}
+
 int TEBenchRunner::startInitiator(int num_threads) {
     if (!init_ok_) {
         LOG(ERROR) << "Initiator cannot start: initialization failed";
         return -1;
     }
-    handle_ = engine_->openSegment(XferBenchConfig::target_seg_name);
-    info_ = engine_->getMetadata()->getSegmentDescByID(handle_);
-    std::sort(
-        info_->buffers.begin(), info_->buffers.end(),
-        [](const TransferMetadata::BufferDesc& a,
-           const TransferMetadata::BufferDesc& b) { return a.name < b.name; });
+    auto names = splitCommaSeparated(XferBenchConfig::target_seg_name);
+    if (names.empty()) {
+        LOG(ERROR) << "No target segment name specified";
+        return -1;
+    }
+    target_handles_.clear();
+    target_infos_.clear();
+    for (const auto& name : names) {
+        SegmentID handle = engine_->openSegment(name);
+        auto info = engine_->getMetadata()->getSegmentDescByID(handle);
+        std::sort(info->buffers.begin(), info->buffers.end(),
+                  [](const TransferMetadata::BufferDesc& a,
+                     const TransferMetadata::BufferDesc& b) {
+                      return a.name < b.name;
+                  });
+        target_handles_.push_back(handle);
+        target_infos_.push_back(std::move(info));
+    }
     threads_.resize(num_threads);
     g_te_running = true;
     current_task_.resize(threads_.size());
@@ -274,14 +476,6 @@ int TEBenchRunner::stopInitiator() {
     return 0;
 }
 
-static int parseIndex(const std::string& loc) {
-    auto pos = loc.find(':');
-    if (pos == std::string::npos || pos + 1 >= loc.size()) {
-        throw std::invalid_argument("Invalid loc format: " + loc);
-    }
-    return std::stoi(loc.substr(pos + 1));
-}
-
 void TEBenchRunner::pinThread(int thread_id) {
 #ifdef USE_SUNRISE
     if (XferBenchConfig::seg_type == "VRAM" && !pinned_buffer_list_.empty()) {
@@ -346,7 +540,7 @@ int TEBenchRunner::runInitiatorTasks(
     return g_te_running ? 0 : -1;
 }
 
-double TEBenchRunner::runSingleTransfer(uint64_t local_addr,
+double TEBenchRunner::runSingleTransfer(uint64_t local_addr, uint64_t target_id,
                                         uint64_t target_addr,
                                         uint64_t block_size,
                                         uint64_t batch_size, OpCode opcode,
@@ -362,29 +556,61 @@ double TEBenchRunner::runSingleTransfer(uint64_t local_addr,
             opcode == READ ? TransferRequest::READ : TransferRequest::WRITE;
         entry.length = block_size;
         entry.source = (void*)(local_addr + block_size * i);
-        entry.target_id = handle_;
+        entry.target_id = target_id;
         entry.target_offset = target_addr + block_size * i;
         requests.emplace_back(entry);
     }
-    XferBenchTimer timer;
-    CHECK_FAIL(engine_->submitTransfer(batch_id, requests));
-    while (true) {
-        uint64_t success_count = 0;
-        for (uint64_t i = 0; i < batch_size; ++i) {
+    if (!splitOutputEnabled()) {
+        XferBenchTimer timer;
+        CHECK_FAIL(engine_->submitTransfer(batch_id, requests));
+        while (g_te_running) {
             mooncake::TransferStatus overall_status;
-            CHECK_FAIL(engine_->getTransferStatus(batch_id, i, overall_status));
+            CHECK_FAIL(
+                engine_->getBatchTransferStatus(batch_id, overall_status));
             if (overall_status.s == TransferStatusEnum::COMPLETED) {
-                success_count++;
-            } else if (overall_status.s == TransferStatusEnum::FAILED) {
+                auto duration = timer.lap_us();
+                CHECK_FAIL(engine_->freeBatchID(batch_id));
+                return duration;
+            }
+            if (overall_status.s == TransferStatusEnum::FAILED ||
+                overall_status.s == TransferStatusEnum::TIMEOUT ||
+                overall_status.s == TransferStatusEnum::CANCELED ||
+                overall_status.s == TransferStatusEnum::INVALID) {
                 LOG(ERROR) << "Failed transfer detected";
                 exit(EXIT_FAILURE);
             }
         }
-        if (success_count == batch_size) break;
+        (void)engine_->freeBatchID(batch_id);
+        return -1.0;
+    }
+
+    XferBenchTimer submit_timer;
+    CHECK_FAIL(engine_->submitTransfer(batch_id, requests));
+    const uint64_t submit_us = submit_timer.lap_us();
+    XferBenchTimer wait_timer;
+    uint64_t polls = 0;
+    while (g_te_running) {
+        mooncake::TransferStatus overall_status;
+        CHECK_FAIL(engine_->getBatchTransferStatus(batch_id, overall_status));
+        polls++;
+        if (overall_status.s == TransferStatusEnum::COMPLETED) {
+            const uint64_t wait_us = wait_timer.lap_us();
+            logSplitXfer({batch_size, submit_us, wait_us, polls});
+            CHECK_FAIL(engine_->freeBatchID(batch_id));
+            return static_cast<double>(submit_us + wait_us);
+        }
+        if (overall_status.s == TransferStatusEnum::FAILED ||
+            overall_status.s == TransferStatusEnum::TIMEOUT ||
+            overall_status.s == TransferStatusEnum::CANCELED ||
+            overall_status.s == TransferStatusEnum::INVALID) {
+            LOG(ERROR) << "Failed transfer detected";
+            exit(EXIT_FAILURE);
+        }
     }
-    auto duration = timer.lap_us();
-    CHECK_FAIL(engine_->freeBatchID(batch_id));
-    return duration;
+    // Stopped while the batch is still in flight. freeBatchID refuses
+    // unfinished batches, so this release is best-effort on the abort path.
+    (void)engine_->freeBatchID(batch_id);
+    return -1.0;
 }
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/benchmark/te_backend.h b/mooncake-transfer-engine/benchmark/te_backend.h
index 9685f37421..f9358d6e33 100644
--- a/mooncake-transfer-engine/benchmark/te_backend.h
+++ b/mooncake-transfer-engine/benchmark/te_backend.h
@@ -61,16 +61,46 @@ class TEBenchRunner : public BenchRunner {
                block_size * batch_size * (thread_id / num_buffers);
     }
 
+    size_t getTargetCount() const;
+
+    size_t getTargetIndex(int thread_id) const {
+        return targetIndex(thread_id);
+    }
+
+    uint64_t getTargetSegmentId(int thread_id) const;
+
     uint64_t getTargetBufferBase(int thread_id, uint64_t block_size,
                                  uint64_t batch_size) const {
-        return info_->buffers[thread_id % info_->buffers.size()].addr +
-               block_size * batch_size * (thread_id / info_->buffers.size());
+        const size_t target_idx = targetIndex(thread_id);
+        const int local_thread_id = localTargetThreadId(thread_id);
+        const auto& info = target_infos_[target_idx];
+        const size_t buffer_idx = local_thread_id % info->buffers.size();
+        const uint64_t bytes =
+            checkedMul(block_size, batch_size, "target operation size");
+        const uint64_t relative_offset =
+            checkedMul(bytes, local_thread_id / info->buffers.size(),
+                       "target relative offset");
+        const auto& buffer = info->buffers[buffer_idx];
+        if (XferBenchConfig::target_range_size != 0 &&
+            !rangeContains(relative_offset, bytes,
+                           XferBenchConfig::target_range_size)) {
+            LOG(FATAL) << "Target range too small for thread " << thread_id;
+        }
+        if (XferBenchConfig::target_offset > buffer.length ||
+            !rangeContains(relative_offset, bytes,
+                           buffer.length - XferBenchConfig::target_offset)) {
+            LOG(FATAL) << "Target buffer too small for thread " << thread_id;
+        }
+        return checkedAdd(buffer.addr,
+                          checkedAdd(XferBenchConfig::target_offset,
+                                     relative_offset, "target address offset"),
+                          "target address");
     }
 
-    double runSingleTransfer(uint64_t local_addr, uint64_t target_addr,
-                             uint64_t block_size, uint64_t batch_size,
-                             OpCode opcode, uint64_t deadline_ns,
-                             IntentType intent_type);
+    double runSingleTransfer(uint64_t local_addr, uint64_t target_id,
+                             uint64_t target_addr, uint64_t block_size,
+                             uint64_t batch_size, OpCode opcode,
+                             uint64_t deadline_ns, IntentType intent_type);
 
    private:
     int allocateBuffers();
@@ -79,11 +109,17 @@ class TEBenchRunner : public BenchRunner {
 
     int runner(int thread_id);
 
+    size_t targetIndex(int thread_id) const;
+
+    int localTargetThreadId(int thread_id) const;
+
    private:
     std::unique_ptr<mooncake::TransferEngine> engine_;
     std::vector<void*> pinned_buffer_list_;
-    SegmentID handle_;
-    std::shared_ptr<TransferMetadata::SegmentDesc> info_;
+    std::vector<char> shm_backed_;
+    std::vector<char> hugepage_backed_;
+    std::vector<SegmentID> target_handles_;
+    std::vector<std::shared_ptr<TransferMetadata::SegmentDesc>> target_infos_;
 
     std::vector<std::function<int(int)>> current_task_;
     std::vector<std::thread> threads_;
diff --git a/mooncake-transfer-engine/benchmark/tent_backend.cpp b/mooncake-transfer-engine/benchmark/tent_backend.cpp
index 12e6646cef..482d1accc1 100644
--- a/mooncake-transfer-engine/benchmark/tent_backend.cpp
+++ b/mooncake-transfer-engine/benchmark/tent_backend.cpp
@@ -14,7 +14,10 @@
 
 #include "tent_backend.h"
 #include "utils.h"
+#include "split_output.h"
 #include "char_util.h"
+
+#include <atomic>
 #include "tent/common/types.h"
 #include "tent/runtime/platform.h"
 #include "tent/runtime/topology.h"
@@ -31,18 +34,18 @@
 namespace mooncake {
 namespace tent {
 
-volatile bool g_tent_running = true;
-volatile bool g_tent_triggered_sig = false;
+std::atomic<bool> g_tent_running{true};
+std::atomic<bool> g_tent_triggered_sig{false};
 
 void signalHandlerV1(int signum) {
-    if (g_tent_triggered_sig) {
+    if (g_tent_triggered_sig.load()) {
         LOG(ERROR) << "Received signal " << signum
                    << " again, forcefully terminating...";
         std::exit(EXIT_FAILURE);
     }
     LOG(INFO) << "Received signal " << signum << ", stopping target server...";
-    g_tent_running = false;
-    g_tent_triggered_sig = true;
+    g_tent_running.store(false);
+    g_tent_triggered_sig.store(true);
 }
 
 std::shared_ptr<Config> loadConfig() {
@@ -60,13 +63,15 @@ std::shared_ptr<Config> loadConfig() {
         std::unordered_map<std::string, std::string> transport_map = {
             {"rdma", "rdma"},
             {"tcp", "tcp"},
+            {"hp_tcp", "hp_tcp"},
             {"shm", "shm"},
             {"iouring", "io_uring"},  // Note: iouring -> io_uring
             {"gds", "gds"},
             {"mnnvl", "mnnvl"},
             {"nvlink", "nvlink"},
             {"ub", "ub"},
-            {"sunrise_link", "sunrise_link"}};
+            {"sunrise_link", "sunrise_link"},
+            {"mpcomm", "mpcomm"}};
 
         // Disable all transports by default
         for (const auto& entry : transport_map) {
@@ -93,6 +98,8 @@ static TransportType getTransportType(const std::string& xport_type) {
     if (xport_type == "iouring") return IOURING;
     if (xport_type == "ub") return UB;
     if (xport_type == "sunrise_link") return SUNRISE_LINK;
+    if (xport_type == "mpcomm") return MPCOMM;
+    if (xport_type == "hp_tcp") return HP_TCP;
     return UNSPEC;
 }
 
@@ -142,7 +149,7 @@ static int resolveSegTypeParams(const std::string& seg_type,
         }
 #elif defined(USE_HIP)
     } else if (seg_type == "VRAM" || seg_type == "vram") {
-        device_prefix = "rocm";
+        device_prefix = "hip";
         int gpu_count = 0;
         hipGetDeviceCount(&gpu_count);
         start_idx = 0;
@@ -302,21 +309,55 @@ TENTBenchRunner::TENTBenchRunner() {
 TENTBenchRunner::~TENTBenchRunner() { freeBuffers(); }
 
 int TENTBenchRunner::runTarget() {
-    while (g_tent_running) sleep(1);
+    while (g_tent_running.load()) sleep(1);
     return 0;
 }
 
+size_t TENTBenchRunner::targetIndex(int thread_id) const {
+    LOG_ASSERT(!target_handles_.empty());
+    return static_cast<size_t>(thread_id) % target_handles_.size();
+}
+
+int TENTBenchRunner::localTargetThreadId(int thread_id) const {
+    LOG_ASSERT(!target_handles_.empty());
+    return thread_id / static_cast<int>(target_handles_.size());
+}
+
+uint64_t TENTBenchRunner::getTargetSegmentId(int thread_id) const {
+    return target_handles_[targetIndex(thread_id)];
+}
+
+size_t TENTBenchRunner::getTargetCount() const {
+    return std::max<size_t>(target_handles_.size(), 1);
+}
+
 int TENTBenchRunner::startInitiator(int num_threads) {
-    CHECK_FAIL(engine_->openSegment(handle_, XferBenchConfig::target_seg_name));
-    info_.buffers.clear();
-    CHECK_FAIL(engine_->getSegmentInfo(handle_, info_));
-    std::sort(info_.buffers.begin(), info_.buffers.end(),
-              [](const SegmentInfo::Buffer& a, const SegmentInfo::Buffer& b) {
-                  return a.location < b.location;
-              });
+    auto names = splitCommaSeparated(XferBenchConfig::target_seg_name);
+    if (names.empty()) {
+        LOG(ERROR) << "No target segment name specified";
+        return -1;
+    }
+    target_handles_.clear();
+    target_infos_.clear();
+    target_handles_.reserve(names.size());
+    target_infos_.reserve(names.size());
+    for (const auto& name : names) {
+        SegmentID handle = 0;
+        CHECK_FAIL(engine_->openSegment(handle, name));
+        SegmentInfo info;
+        CHECK_FAIL(engine_->getSegmentInfo(handle, info));
+        std::sort(
+            info.buffers.begin(), info.buffers.end(),
+            [](const SegmentInfo::Buffer& a, const SegmentInfo::Buffer& b) {
+                return a.location < b.location;
+            });
+        target_handles_.push_back(handle);
+        target_infos_.push_back(std::move(info));
+    }
+    LOG(INFO) << "Opened " << target_handles_.size() << " target segments";
     threads_.resize(num_threads);
     current_task_.resize(threads_.size());
-    g_tent_running = true;
+    g_tent_running.store(true);
     for (size_t i = 0; i < threads_.size(); ++i)
         threads_[i] = std::thread(&TENTBenchRunner::runner, this, i);
     return 0;
@@ -325,7 +366,7 @@ int TENTBenchRunner::startInitiator(int num_threads) {
 int TENTBenchRunner::stopInitiator() {
     {
         std::unique_lock<std::mutex> lk(mtx_);
-        g_tent_running = false;
+        g_tent_running.store(false);
         cv_task_.notify_all();
         cv_done_.notify_all();
     }
@@ -391,7 +432,8 @@ void TENTBenchRunner::pinThread(int thread_id) {
     if (location.type() == "cpu") {
         auto socket_id = location.index();
         bindToSocket(socket_id);
-    } else if (location.type() == "cuda" || location.type() == "rocm") {
+    } else if (location.type() == "cuda" ||
+               isAmdGpuLocationType(location.type())) {
         auto device_id = location.index();
         auto socket_id = getGpuDeviceNumaID(device_id);
         bindToSocket(socket_id);
@@ -399,14 +441,14 @@ void TENTBenchRunner::pinThread(int thread_id) {
 }
 
 int TENTBenchRunner::runner(int thread_id) {
-    while (g_tent_running) {
+    while (g_tent_running.load()) {
         std::function<int(int)> task;
         {
             std::unique_lock<std::mutex> lk(mtx_);
             cv_task_.wait(lk, [&] {
-                return !g_tent_running || current_task_[thread_id];
+                return !g_tent_running.load() || current_task_[thread_id];
             });
-            if (!g_tent_running) break;
+            if (!g_tent_running.load()) break;
             std::swap(task, current_task_[thread_id]);
         }
         if (task) task(thread_id);
@@ -425,24 +467,44 @@ int TENTBenchRunner::runInitiatorTasks(
         current_task_[id] = func;
     pending_ = (int)threads_.size();
     cv_task_.notify_all();
-    cv_done_.wait(lk, [&] { return !g_tent_running || pending_ == 0; });
-    return g_tent_running ? 0 : -1;
+    cv_done_.wait(lk, [&] { return !g_tent_running.load() || pending_ == 0; });
+    return g_tent_running.load() ? 0 : -1;
 }
 
-double TENTBenchRunner::runSingleTransfer(uint64_t local_addr,
-                                          uint64_t target_addr,
-                                          uint64_t block_size,
-                                          uint64_t batch_size, OpCode opcode,
-                                          uint64_t deadline_ns,
-                                          IntentType intent_type) {
+void TENTBenchRunner::noteTransferFailed() {
+    std::lock_guard<std::mutex> lk(mtx_);
+    g_tent_running.store(false);
+    cv_task_.notify_all();
+    cv_done_.notify_all();
+}
+
+double TENTBenchRunner::runSingleTransfer(
+    uint64_t local_addr, uint64_t target_id, uint64_t target_addr,
+    uint64_t block_size, uint64_t batch_size, OpCode opcode,
+    uint64_t deadline_ns, IntentType intent_type) {
+    if (!g_tent_running.load()) return -1.0;
+
+    auto abortTransfer = [&](const char* why) {
+        LOG(ERROR) << why;
+        noteTransferFailed();
+        return -1.0;
+    };
+
     auto batch_id = engine_->allocateBatch(batch_size);
+    if (!batch_id) return abortTransfer("Failed to allocate transfer batch");
+
+    auto finish = [&](double duration) {
+        (void)engine_->freeBatch(batch_id);
+        return duration;
+    };
+
     std::vector<Request> requests;
     for (uint64_t i = 0; i < batch_size; ++i) {
         Request entry;
         entry.opcode = opcode == READ ? Request::READ : Request::WRITE;
         entry.length = block_size;
         entry.source = (void*)(local_addr + block_size * i);
-        entry.target_id = handle_;
+        entry.target_id = target_id;
         entry.target_offset = target_addr + block_size * i;
         entry.transport_hint = transport_hint_;
         entry.deadline_ns = deadline_ns;
@@ -451,27 +513,83 @@ double TENTBenchRunner::runSingleTransfer(uint64_t local_addr,
                                 : intent_type;
         requests.emplace_back(entry);
     }
-    XferBenchTimer timer;
+    if (!splitOutputEnabled()) {
+        XferBenchTimer timer;
+        Status submitted;
+        if (XferBenchConfig::notifi) {
+            Notification notifi{"benchmark", std::to_string(target_addr)};
+            submitted = engine_->submitTransfer(batch_id, requests, notifi);
+        } else {
+            submitted = engine_->submitTransfer(batch_id, requests);
+        }
+        if (!submitted.ok()) {
+            LOG(ERROR) << "Failed to submit transfer: " << submitted.ToString();
+            noteTransferFailed();
+            return finish(-1.0);
+        }
+        while (g_tent_running.load()) {
+            TransferStatus overall_status;
+            auto polled = engine_->getTransferStatus(batch_id, overall_status);
+            if (!polled.ok()) {
+                LOG(ERROR) << "Failed to poll transfer: " << polled.ToString();
+                noteTransferFailed();
+                return finish(-1.0);
+            }
+            if (overall_status.s == TransferStatusEnum::COMPLETED) {
+                return finish(timer.lap_us());
+            }
+            if (overall_status.s == TransferStatusEnum::FAILED ||
+                overall_status.s == TransferStatusEnum::TIMEOUT ||
+                overall_status.s == TransferStatusEnum::CANCELED ||
+                overall_status.s == TransferStatusEnum::INVALID) {
+                LOG(ERROR) << "Failed transfer detected";
+                noteTransferFailed();
+                return finish(-1.0);
+            }
+        }
+        return finish(-1.0);
+    }
+
+    XferBenchTimer submit_timer;
+    Status submitted;
     if (XferBenchConfig::notifi) {
-        // Use target_addr as msg for verification by peer
         Notification notifi{"benchmark", std::to_string(target_addr)};
-        CHECK_FAIL(engine_->submitTransfer(batch_id, requests, notifi));
+        submitted = engine_->submitTransfer(batch_id, requests, notifi);
     } else {
-        CHECK_FAIL(engine_->submitTransfer(batch_id, requests));
+        submitted = engine_->submitTransfer(batch_id, requests);
+    }
+    if (!submitted.ok()) {
+        LOG(ERROR) << "Failed to submit transfer: " << submitted.ToString();
+        noteTransferFailed();
+        return finish(-1.0);
     }
-    while (true) {
+    const uint64_t submit_us = submit_timer.lap_us();
+    XferBenchTimer wait_timer;
+    uint64_t polls = 0;
+    while (g_tent_running.load()) {
         TransferStatus overall_status;
-        CHECK_FAIL(engine_->getTransferStatus(batch_id, overall_status));
+        auto polled = engine_->getTransferStatus(batch_id, overall_status);
+        polls++;
+        if (!polled.ok()) {
+            LOG(ERROR) << "Failed to poll transfer: " << polled.ToString();
+            noteTransferFailed();
+            return finish(-1.0);
+        }
         if (overall_status.s == TransferStatusEnum::COMPLETED) {
-            break;
-        } else if (overall_status.s == TransferStatusEnum::FAILED) {
+            const uint64_t wait_us = wait_timer.lap_us();
+            logSplitXfer({batch_size, submit_us, wait_us, polls});
+            return finish(static_cast<double>(submit_us + wait_us));
+        }
+        if (overall_status.s == TransferStatusEnum::FAILED ||
+            overall_status.s == TransferStatusEnum::TIMEOUT ||
+            overall_status.s == TransferStatusEnum::CANCELED ||
+            overall_status.s == TransferStatusEnum::INVALID) {
             LOG(ERROR) << "Failed transfer detected";
-            exit(EXIT_FAILURE);
+            noteTransferFailed();
+            return finish(-1.0);
         }
     }
-    auto duration = timer.lap_us();
-    CHECK_FAIL(engine_->freeBatch(batch_id));
-    return duration;
+    return finish(-1.0);
 }
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/benchmark/tent_backend.h b/mooncake-transfer-engine/benchmark/tent_backend.h
index 8f021cbb21..15e3202655 100644
--- a/mooncake-transfer-engine/benchmark/tent_backend.h
+++ b/mooncake-transfer-engine/benchmark/tent_backend.h
@@ -87,23 +87,56 @@ class TENTBenchRunner : public BenchRunner {
                    ((thread_id / seg_type_mix_.size()) / count);
     }
 
+    size_t getTargetCount() const;
+
+    size_t getTargetIndex(int thread_id) const {
+        return targetIndex(thread_id);
+    }
+
+    uint64_t getTargetSegmentId(int thread_id) const;
+
     uint64_t getTargetBufferBase(int thread_id, uint64_t block_size,
                                  uint64_t batch_size) const {
+        const size_t target_idx = targetIndex(thread_id);
+        const int local_thread_id = localTargetThreadId(thread_id);
+        const auto& info = target_infos_[target_idx];
         if (seg_type_mix_.empty()) {
             // Single seg_type mode: original behavior.
-            return info_.buffers[thread_id % info_.buffers.size()].base +
-                   block_size * batch_size * (thread_id / info_.buffers.size());
+            const size_t buffer_idx = local_thread_id % info.buffers.size();
+            const uint64_t bytes =
+                checkedMul(block_size, batch_size, "target operation size");
+            const uint64_t relative_offset =
+                checkedMul(bytes, local_thread_id / info.buffers.size(),
+                           "target relative offset");
+            const auto& buffer = info.buffers[buffer_idx];
+            if (XferBenchConfig::target_range_size != 0 &&
+                !rangeContains(relative_offset, bytes,
+                               XferBenchConfig::target_range_size)) {
+                LOG(FATAL) << "Target range too small for thread " << thread_id;
+            }
+            if (XferBenchConfig::target_offset > buffer.length ||
+                !rangeContains(
+                    relative_offset, bytes,
+                    buffer.length - XferBenchConfig::target_offset)) {
+                LOG(FATAL) << "Target buffer too small for thread "
+                           << thread_id;
+            }
+            return checkedAdd(
+                buffer.base,
+                checkedAdd(XferBenchConfig::target_offset, relative_offset,
+                           "target address offset"),
+                "target address");
         }
         // Mixed mode: pick this thread's seg_type, then index into the
         // subset of target segment buffers matching that seg_type. Use
         // LocationParser to classify each buffer as host (cpu) vs device
         // (cuda/rocm/supa/...) rather than hard-coding a vendor prefix.
         const std::string& seg_type =
-            seg_type_mix_[thread_id % seg_type_mix_.size()];
+            seg_type_mix_[local_thread_id % seg_type_mix_.size()];
         bool want_device = (seg_type == "vram");
         std::vector<size_t> matches;
-        for (size_t i = 0; i < info_.buffers.size(); ++i) {
-            const auto& loc = info_.buffers[i].location;
+        for (size_t i = 0; i < info.buffers.size(); ++i) {
+            const auto& loc = info.buffers[i].location;
             bool is_device =
                 LocationParser(loc).type() != "cpu" && loc != kWildcardLocation;
             if (is_device == want_device) {
@@ -114,16 +147,36 @@ class TENTBenchRunner : public BenchRunner {
             LOG(FATAL) << "No target buffer of seg_type " << seg_type
                        << " for thread " << thread_id;
         }
-        size_t slot = (thread_id / seg_type_mix_.size()) % matches.size();
-        return info_.buffers[matches[slot]].base +
-               block_size * batch_size *
-                   ((thread_id / seg_type_mix_.size()) / matches.size());
+        size_t slot = (local_thread_id / seg_type_mix_.size()) % matches.size();
+        const uint64_t bytes =
+            checkedMul(block_size, batch_size, "target operation size");
+        const uint64_t relative_offset = checkedMul(
+            bytes, (local_thread_id / seg_type_mix_.size()) / matches.size(),
+            "target relative offset");
+        const auto& buffer = info.buffers[matches[slot]];
+        if (XferBenchConfig::target_range_size != 0 &&
+            !rangeContains(relative_offset, bytes,
+                           XferBenchConfig::target_range_size)) {
+            LOG(FATAL) << "Target range too small for thread " << thread_id;
+        }
+        if (XferBenchConfig::target_offset > buffer.length ||
+            !rangeContains(relative_offset, bytes,
+                           buffer.length - XferBenchConfig::target_offset)) {
+            LOG(FATAL) << "Target buffer too small for thread " << thread_id;
+        }
+        return checkedAdd(buffer.base,
+                          checkedAdd(XferBenchConfig::target_offset,
+                                     relative_offset, "target address offset"),
+                          "target address");
     }
 
-    double runSingleTransfer(uint64_t local_addr, uint64_t target_addr,
-                             uint64_t block_size, uint64_t batch_size,
-                             OpCode opcode, uint64_t deadline_ns,
-                             IntentType intent_type);
+    // Returns elapsed microseconds on success, or a negative value if the
+    // transfer failed. Never calls exit() — workers set g_tent_running so
+    // main can join threads and stop the engine first.
+    double runSingleTransfer(uint64_t local_addr, uint64_t target_id,
+                             uint64_t target_addr, uint64_t block_size,
+                             uint64_t batch_size, OpCode opcode,
+                             uint64_t deadline_ns, IntentType intent_type);
 
    private:
     int allocateBuffers();
@@ -132,6 +185,12 @@ class TENTBenchRunner : public BenchRunner {
 
     int runner(int thread_id);
 
+    void noteTransferFailed();
+
+    size_t targetIndex(int thread_id) const;
+
+    int localTargetThreadId(int thread_id) const;
+
    private:
     std::unique_ptr<TransferEngine> engine_;
     std::vector<void*> pinned_buffer_list_;
@@ -142,8 +201,8 @@ class TENTBenchRunner : public BenchRunner {
     // Parsed --seg_type_mix (e.g. ["dram", "vram"]). Empty when --seg_type_mix
     // is not set → single-seg_type mode (existing behavior).
     std::vector<std::string> seg_type_mix_;
-    SegmentID handle_;
-    SegmentInfo info_;
+    std::vector<SegmentID> target_handles_;
+    std::vector<SegmentInfo> target_infos_;
     TransportType transport_hint_{UNSPEC};
     IntentType intent_type_{IntentType::INTENT_UNSPEC};
 
diff --git a/mooncake-transfer-engine/benchmark/tests/qos_metrics_test.cpp b/mooncake-transfer-engine/benchmark/tests/qos_metrics_test.cpp
index 0c890dab92..e8969bc1e0 100644
--- a/mooncake-transfer-engine/benchmark/tests/qos_metrics_test.cpp
+++ b/mooncake-transfer-engine/benchmark/tests/qos_metrics_test.cpp
@@ -14,9 +14,13 @@
 
 #include "qos_metrics_adapter.h"
 
+#include <csignal>
 #include <cstdio>
+#include <cstdlib>
 #include <fstream>
 #include <string>
+#include <sys/resource.h>
+#include <unistd.h>
 #include <vector>
 
 #include <gtest/gtest.h>
@@ -28,6 +32,38 @@ namespace mooncake {
 namespace tent {
 namespace {
 
+TEST(QosMetricsDeathTest, ReportsBufferedWriteFailure) {
+    std::string path = testing::TempDir() + "tebench-qos-jsonl-XXXXXX";
+    const int fd = mkstemp(path.data());
+    ASSERT_GE(fd, 0);
+    close(fd);
+
+    // Keep the file-size limit and signal handler out of the parent process.
+    EXPECT_EXIT(
+        {
+            if (std::signal(SIGXFSZ, SIG_IGN) == SIG_ERR) std::_Exit(2);
+            struct rlimit limit{};
+            if (setrlimit(RLIMIT_FSIZE, &limit) != 0) std::_Exit(3);
+            QosMetricsReport report;
+            std::string error;
+            const bool ok = appendQosMetricsJsonl(path, report, &error);
+            std::_Exit(!ok && error ==
+                                   "failed to write QoS JSONL output: " + path
+                           ? 0
+                           : 1);
+        },
+        testing::ExitedWithCode(0), "");
+    std::remove(path.c_str());
+}
+
+TEST(QosMetricsTest, ReportsOpenFailure) {
+    QosMetricsReport report;
+    std::string error;
+    const auto path = testing::TempDir();
+    EXPECT_FALSE(appendQosMetricsJsonl(path, report, &error));
+    EXPECT_EQ(error, "failed to open QoS JSONL output: " + path);
+}
+
 TEST(QosMetricsTest, SupportsBulkSamples) {
     XferMetricStats stats;
     stats.add(std::vector<double>{3.0, 1.0, 2.0});
@@ -203,6 +239,9 @@ TEST(QosMetricsTest, UsesNullForUnavailableJsonMetrics) {
     std::remove(path.c_str());
     std::string error;
     ASSERT_TRUE(appendQosMetricsJsonl(path, report, &error)) << error;
+    auto next_report = report;
+    next_report.batch_size = 2;
+    ASSERT_TRUE(appendQosMetricsJsonl(path, next_report, &error)) << error;
 
     std::ifstream input(path);
     nlohmann::json record;
@@ -214,6 +253,9 @@ TEST(QosMetricsTest, UsesNullForUnavailableJsonMetrics) {
     EXPECT_TRUE(record["classes"][0]["slo_attainment"].is_null());
     EXPECT_TRUE(record["classes"][0]["isolation_leakage"].is_null());
     EXPECT_TRUE(record["classes"][0]["isolated_throughput_gbps"].is_null());
+    EXPECT_EQ(record["batch_size"], 1);
+    ASSERT_NO_THROW(input >> record);
+    EXPECT_EQ(record["batch_size"], 2);
     std::remove(path.c_str());
 }
 
diff --git a/mooncake-transfer-engine/benchmark/tests/split_output_test.cpp b/mooncake-transfer-engine/benchmark/tests/split_output_test.cpp
new file mode 100644
index 0000000000..a7620e8f88
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/tests/split_output_test.cpp
@@ -0,0 +1,93 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "split_output.h"
+
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <unistd.h>
+
+#include <gtest/gtest.h>
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+std::string makeTempPath() {
+    std::string path = testing::TempDir() + "tebench-split-XXXXXX";
+    const int fd = mkstemp(path.data());
+    EXPECT_GE(fd, 0);
+    if (fd >= 0) close(fd);
+    return path;
+}
+
+TEST(SplitOutputTest, FormatsIntegerJsonLine) {
+    char buf[160];
+    size_t n = 0;
+    SplitXferSample sample{207360, 66874, 1152760, 201};
+    ASSERT_TRUE(formatSplitXferLine(buf, sizeof(buf), sample, &n));
+    EXPECT_EQ(std::string(buf, n),
+              "{\"batch_size\":207360,\"submit_us\":66874,\"wait_us\":1152760,"
+              "\"polls\":201}\n");
+}
+
+TEST(SplitOutputTest, RejectsTruncatedBuffer) {
+    char buf[8];
+    size_t n = 99;
+    SplitXferSample sample{1, 2, 3, 4};
+    EXPECT_FALSE(formatSplitXferLine(buf, sizeof(buf), sample, &n));
+}
+
+TEST(SplitOutputTest, DisabledLogIsNoOp) {
+    EXPECT_FALSE(splitOutputEnabled());
+    logSplitXfer({1, 2, 3, 4});
+    EXPECT_FALSE(splitOutputEnabled());
+}
+
+TEST(SplitOutputTest, AppendsOneLinePerTransfer) {
+    const std::string path = makeTempPath();
+    std::string error;
+    ASSERT_TRUE(openSplitOutput(path, &error)) << error;
+    EXPECT_TRUE(splitOutputEnabled());
+    logSplitXfer({4096, 10, 20, 3});
+    logSplitXfer({4096, 11, 21, 4});
+    closeSplitOutput();
+    EXPECT_FALSE(splitOutputEnabled());
+
+    std::ifstream in(path);
+    std::string line1, line2, extra;
+    ASSERT_TRUE(std::getline(in, line1));
+    ASSERT_TRUE(std::getline(in, line2));
+    EXPECT_FALSE(std::getline(in, extra));
+    EXPECT_EQ(line1,
+              "{\"batch_size\":4096,\"submit_us\":10,\"wait_us\":20,\"polls\":"
+              "3}");
+    EXPECT_EQ(line2,
+              "{\"batch_size\":4096,\"submit_us\":11,\"wait_us\":21,\"polls\":"
+              "4}");
+    std::remove(path.c_str());
+}
+
+TEST(SplitOutputTest, ReportsOpenFailure) {
+    std::string error;
+    EXPECT_FALSE(openSplitOutput(testing::TempDir(), &error));
+    EXPECT_EQ(error,
+              "failed to open split JSONL output: " + testing::TempDir());
+    EXPECT_FALSE(splitOutputEnabled());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/benchmark/tests/target_metrics_test.cpp b/mooncake-transfer-engine/benchmark/tests/target_metrics_test.cpp
new file mode 100644
index 0000000000..e5fc40f89e
--- /dev/null
+++ b/mooncake-transfer-engine/benchmark/tests/target_metrics_test.cpp
@@ -0,0 +1,129 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "target_metrics.h"
+
+#include <csignal>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <sys/resource.h>
+#include <unistd.h>
+
+#include <gtest/gtest.h>
+
+#include "tent/thirdparty/nlohmann/json.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+TEST(TargetMetricsDeathTest, ReportsBufferedWriteFailure) {
+    std::string path = testing::TempDir() + "tebench-target-jsonl-XXXXXX";
+    const int fd = mkstemp(path.data());
+    ASSERT_GE(fd, 0);
+    close(fd);
+
+    // Limit only the child: opening succeeds, but even a buffered write fails
+    // when the stream is flushed or closed.
+    EXPECT_EXIT(
+        {
+            if (std::signal(SIGXFSZ, SIG_IGN) == SIG_ERR) std::_Exit(2);
+            struct rlimit limit{};
+            if (setrlimit(RLIMIT_FSIZE, &limit) != 0) std::_Exit(3);
+            TargetMetricsReport report;
+            std::string error;
+            const bool ok = appendTargetMetricsJsonl(path, report, &error);
+            std::_Exit(!ok && error == "failed to write target JSONL output: " +
+                                           path
+                           ? 0
+                           : 1);
+        },
+        testing::ExitedWithCode(0), "");
+    std::remove(path.c_str());
+}
+
+TEST(TargetMetricsTest, ReportsOpenFailure) {
+    TargetMetricsReport report;
+    std::string error;
+    const auto path = testing::TempDir();
+    EXPECT_FALSE(appendTargetMetricsJsonl(path, report, &error));
+    EXPECT_EQ(error, "failed to open target JSONL output: " + path);
+}
+
+TEST(TargetMetricsTest, NonConstantPayloadOnlyForHpTcpConsistencyChecks) {
+    const auto saved_transport = XferBenchConfig::xport_type;
+    const bool saved_check = XferBenchConfig::check_consistency;
+    std::vector<uint8_t> data(4096);
+    for (const auto* transport : {"hp_tcp", "tcp"}) {
+        XferBenchConfig::xport_type = transport;
+        for (bool check : {false, true}) {
+            XferBenchConfig::check_consistency = check;
+            fillData(data.data(), data.size(), 37);
+            const bool constant = std::all_of(
+                data.begin(), data.end(), [](uint8_t b) { return b == 37; });
+            EXPECT_EQ(constant,
+                      !(check && XferBenchConfig::xport_type == "hp_tcp"));
+            verifyData(data.data(), data.size(), 37);
+        }
+    }
+    XferBenchConfig::xport_type = saved_transport;
+    XferBenchConfig::check_consistency = saved_check;
+}
+
+TEST(TargetMetricsTest, ReportsEachTargetAndWritesJsonl) {
+    std::vector<TargetBenchStats> stats(2);
+    stats[0].segment_name = "target-a";
+    stats[0].threads = 2;
+    stats[0].transferred_bytes = 6000;
+    stats[0].stats.total_duration.add(1000.0);
+    stats[0].stats.total_duration.add(1000.0);
+    stats[0].stats.transfer_duration.add({10.0, 20.0, 30.0});
+    stats[0].stats.instant_bandwidth.add({0.1, 0.2, 0.3});
+    stats[1].segment_name = "target-b";
+
+    const auto report =
+        calculateTargetMetrics(1000, 2, 2, "tent", "read", &stats);
+    ASSERT_EQ(report.targets.size(), 2u);
+    EXPECT_EQ(report.aggregate_operations, 3u);
+    EXPECT_EQ(report.aggregate_transferred_bytes, 6000u);
+    EXPECT_NEAR(report.aggregate_throughput_gbps, 0.006, 1e-12);
+    EXPECT_EQ(report.targets[0].threads, 2);
+    EXPECT_NEAR(report.targets[0].avg_latency_us, 2000.0 / 3.0, 1e-12);
+    EXPECT_DOUBLE_EQ(report.targets[1].throughput_gbps, 0.0);
+
+    const std::string path = "tebench_target_metrics_test.jsonl";
+    std::remove(path.c_str());
+    std::string error;
+    ASSERT_TRUE(appendTargetMetricsJsonl(path, report, &error)) << error;
+    auto next_report = report;
+    next_report.batch_size = 3;
+    ASSERT_TRUE(appendTargetMetricsJsonl(path, next_report, &error)) << error;
+    std::ifstream input(path);
+    nlohmann::json record;
+    ASSERT_NO_THROW(input >> record);
+    EXPECT_EQ(record["schema_version"], 1);
+    EXPECT_EQ(record["record_type"], "target_metrics");
+    ASSERT_EQ(record["targets"].size(), 2u);
+    EXPECT_EQ(record["targets"][0]["segment_name"], "target-a");
+    EXPECT_EQ(record["targets"][1]["operations"], 0);
+    EXPECT_EQ(record["batch_size"], 2);
+    ASSERT_NO_THROW(input >> record);
+    EXPECT_EQ(record["batch_size"], 3);
+    std::remove(path.c_str());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/benchmark/utils.cpp b/mooncake-transfer-engine/benchmark/utils.cpp
index 6708eeb7a2..8472992255 100644
--- a/mooncake-transfer-engine/benchmark/utils.cpp
+++ b/mooncake-transfer-engine/benchmark/utils.cpp
@@ -15,7 +15,11 @@
 #include "utils.h"
 
 #include <gflags/gflags.h>
+#include <cctype>
+#include <charconv>
 #include <iostream>
+#include <optional>
+#include <string_view>
 
 DEFINE_string(seg_name, "", "Memory segment name for the local side");
 DEFINE_string(seg_type, "DRAM",
@@ -29,8 +33,12 @@ DEFINE_string(
     "thus multiple transports — SHM for DRAM, NVLink for VRAM) "
     "concurrently. Empty falls back to --seg_type (single type, existing "
     "behavior). Requires transports to be enabled via MC_TENT_CONF.");
-DEFINE_string(target_seg_name, "", "Memory segment name for the target side");
-DEFINE_string(op_type, "read", "Operation type to benchmark: read|write|mix");
+DEFINE_string(target_seg_name, "",
+              "Target segment name for the initiator side. A comma-separated "
+              "list enables multi-target initiator mode.");
+DEFINE_string(
+    op_type, "read",
+    "Operation type to benchmark: read|write|mix|write_seed|read_verify");
 DEFINE_bool(check_consistency, false,
             "Enable data consistency check after transfer.");
 DEFINE_uint64(total_buffer_size, 1UL << 30,
@@ -44,6 +52,13 @@ DEFINE_int32(start_num_threads, 1,
              "Start number of concurrent worker threads.");
 DEFINE_int32(max_num_threads, 1,
              "Maximum number of concurrent worker threads.");
+DEFINE_uint64(target_offset, 0,
+              "Base offset added to every target buffer address. Useful when "
+              "multiple initiator processes share one target segment.");
+DEFINE_uint64(
+    target_range_size, 0,
+    "Per-initiator target range size. 0 disables range validation; "
+    "non-zero requires every target address to stay inside the range.");
 DEFINE_string(
     qos_classes, "",
     "QoS classes as name:threads:slo_us:weight[:isolated_gbps],...; "
@@ -60,6 +75,17 @@ DEFINE_double(qos_link_capacity_gbps, 0.0,
               "Link capacity in GB/s for total utilization (0 reports N/A).");
 DEFINE_string(qos_output_jsonl, "",
               "Append versioned QoS metric records to this JSONL file.");
+DEFINE_string(result_output_jsonl, "",
+              "Append versioned benchmark result records, including "
+              "per-target metrics, to this JSONL file.");
+DEFINE_string(
+    split_output_jsonl, "",
+    "Initiator only: append one JSONL line per transfer with submit_us, "
+    "wait_us, and polls. Empty (default) disables the log: no extra timers "
+    "and no I/O. Enable to split Avg Tx into submit vs completion wait.");
+DEFINE_uint64(request_interval_us, 0,
+              "Per-thread delay before issuing each transfer batch, in "
+              "microseconds. 0 disables pacing.");
 DEFINE_uint64(deadline_us, 0,
               "tent only: relative per-transfer deadline in microseconds for "
               "tight worker threads (0 disables deadline tagging); cannot be "
@@ -79,16 +105,30 @@ DEFINE_string(metadata_url_list, "",
 DEFINE_int32(
     rpc_server_port, 0,
     "RPC server port used for p2p metadata service (0 = auto-select).");
-DEFINE_string(
-    xport_type, "",
-    "Transport type: rdma|tcp|shm|mnnvl|nvlink|gds|iouring|ub|sunrise_link");
+DEFINE_string(xport_type, "",
+              "Transport type: "
+              "rdma|tcp|hp_tcp|shm|mnnvl|nvlink|gds|iouring|ub|sunrise_link|"
+              "mpcomm|flagcx");
 DEFINE_string(backend, "tent", "Transport backend: classic|tent");
+DEFINE_bool(use_hugepage, false,
+            "classic DRAM: SHM allocates on hugetlbfs; RDMA allocates with "
+            "MAP_HUGETLB so ibv_reg_mr does not explode NIC PTEs on 4K pages. "
+            "Length must be a multiple of hugepage_size. No 4K fallback.");
+DEFINE_string(hugepage_size, "0",
+              "Hugepage size: 2MB, 512MB, or 1GB (same as "
+              "MC_STORE_HUGEPAGE_SIZE), or the size in bytes "
+              "(2097152, 536870912, 1073741824). "
+              "0 defaults to 2MB when --use_hugepage is set.");
+DEFINE_string(
+    hugetlbfs_path, "",
+    "classic shm hugepage mount. Empty uses the size-specific "
+    "default (/dev/hugepages, /dev/hugepages-512M, /dev/hugepages-1G).");
 DEFINE_bool(notifi, false,
             "Enable RDMA notification for performance measurement.");
-DEFINE_string(
-    tent_transport_hint, "unspec",
-    "tent only: per-request transport_hint. "
-    "unspec|rdma|tcp|shm|nvlink|gds|io_uring|mnnvl|ascend|ub|sunrise_link");
+DEFINE_string(tent_transport_hint, "unspec",
+              "tent only: per-request transport_hint. "
+              "unspec|rdma|tcp|hp_tcp|shm|nvlink|gds|io_uring|mnnvl|ascend|"
+              "ub|sunrise_link|mpcomm");
 DEFINE_string(tent_intent_type, "unspec",
               "tent only: intent_type attached to every benchmark request. "
               "unspec|foreground_get|background_prefetch|migration|checkpoint|"
@@ -111,11 +151,16 @@ size_t XferBenchConfig::max_batch_size = 0;
 int XferBenchConfig::duration = 0;
 int XferBenchConfig::max_num_threads = 0;
 int XferBenchConfig::start_num_threads = 0;
+size_t XferBenchConfig::target_offset = 0;
+size_t XferBenchConfig::target_range_size = 0;
 std::string XferBenchConfig::qos_classes;
 std::string XferBenchConfig::qos_classes_json;
 std::string XferBenchConfig::workload_classes_json;
 double XferBenchConfig::qos_link_capacity_gbps = 0.0;
 std::string XferBenchConfig::qos_output_jsonl;
+std::string XferBenchConfig::result_output_jsonl;
+std::string XferBenchConfig::split_output_jsonl;
+uint64_t XferBenchConfig::request_interval_us = 0;
 uint64_t XferBenchConfig::deadline_us = 0;
 int XferBenchConfig::deadline_tight_threads = 0;
 bool XferBenchConfig::deadline_bw_arbitration = false;
@@ -125,6 +170,9 @@ std::string XferBenchConfig::metadata_url_list;
 int XferBenchConfig::rpc_server_port = 0;
 std::string XferBenchConfig::xport_type;
 std::string XferBenchConfig::backend;
+bool XferBenchConfig::use_hugepage = false;
+size_t XferBenchConfig::hugepage_size = 0;
+std::string XferBenchConfig::hugetlbfs_path;
 bool XferBenchConfig::notifi = false;
 std::string XferBenchConfig::tent_transport_hint;
 std::string XferBenchConfig::tent_intent_type;
@@ -132,6 +180,51 @@ std::string XferBenchConfig::tent_intent_type;
 int XferBenchConfig::local_gpu_id = 0;
 int XferBenchConfig::target_gpu_id = 0;
 
+namespace {
+
+std::string_view trimFlag(std::string_view text) {
+    while (!text.empty() &&
+           std::isspace(static_cast<unsigned char>(text.front()))) {
+        text.remove_prefix(1);
+    }
+    while (!text.empty() &&
+           std::isspace(static_cast<unsigned char>(text.back()))) {
+        text.remove_suffix(1);
+    }
+    return text;
+}
+
+bool equalsIgnoreCase(std::string_view a, std::string_view b) {
+    if (a.size() != b.size()) return false;
+    for (size_t i = 0; i < a.size(); ++i) {
+        unsigned char ca = static_cast<unsigned char>(a[i]);
+        unsigned char cb = static_cast<unsigned char>(b[i]);
+        if (ca >= 'A' && ca <= 'Z')
+            ca = static_cast<unsigned char>(ca - 'A' + 'a');
+        if (cb >= 'A' && cb <= 'Z')
+            cb = static_cast<unsigned char>(cb - 'A' + 'a');
+        if (ca != cb) return false;
+    }
+    return true;
+}
+
+// Store labels 2MB/512MB/1GB, or a raw byte count. Empty/"0" → 0.
+std::optional<size_t> parseHugepageSizeFlag(std::string_view raw) {
+    raw = trimFlag(raw);
+    if (raw.empty() || raw == "0") return 0;
+    if (equalsIgnoreCase(raw, "2MB")) return 2ULL << 20;
+    if (equalsIgnoreCase(raw, "512MB")) return 512ULL << 20;
+    if (equalsIgnoreCase(raw, "1GB")) return 1ULL << 30;
+    size_t bytes = 0;
+    const auto* first = raw.data();
+    const auto* last = raw.data() + raw.size();
+    const auto [ptr, ec] = std::from_chars(first, last, bytes);
+    if (ec == std::errc{} && ptr == last) return bytes;
+    return std::nullopt;
+}
+
+}  // namespace
+
 void XferBenchConfig::loadFromFlags() {
     seg_type = FLAGS_seg_type;
     seg_type_mix = FLAGS_seg_type_mix;
@@ -147,11 +240,16 @@ void XferBenchConfig::loadFromFlags() {
     max_batch_size = FLAGS_max_batch_size;
     start_num_threads = FLAGS_start_num_threads;
     max_num_threads = FLAGS_max_num_threads;
+    target_offset = FLAGS_target_offset;
+    target_range_size = FLAGS_target_range_size;
     qos_classes = FLAGS_qos_classes;
     qos_classes_json = FLAGS_qos_classes_json;
     workload_classes_json = FLAGS_workload_classes_json;
     qos_link_capacity_gbps = FLAGS_qos_link_capacity_gbps;
     qos_output_jsonl = FLAGS_qos_output_jsonl;
+    result_output_jsonl = FLAGS_result_output_jsonl;
+    split_output_jsonl = FLAGS_split_output_jsonl;
+    request_interval_us = FLAGS_request_interval_us;
     deadline_us = FLAGS_deadline_us;
     deadline_tight_threads = FLAGS_deadline_tight_threads;
     deadline_bw_arbitration = FLAGS_deadline_bw_arbitration;
@@ -163,6 +261,10 @@ void XferBenchConfig::loadFromFlags() {
 
     xport_type = FLAGS_xport_type;
     backend = FLAGS_backend;
+    use_hugepage = FLAGS_use_hugepage;
+    const auto parsed_hp = parseHugepageSizeFlag(FLAGS_hugepage_size);
+    hugepage_size = parsed_hp.value_or(static_cast<size_t>(-1));
+    hugetlbfs_path = FLAGS_hugetlbfs_path;
     notifi = FLAGS_notifi;
     tent_transport_hint = FLAGS_tent_transport_hint;
     tent_intent_type = FLAGS_tent_intent_type;
@@ -192,7 +294,8 @@ void printStatsHeader() {
     std::cout << std::left
               << std::setw(14) << "BlkSize (B)"
               << std::setw(8) << "Batch"
-              << std::setw(14) << "BW (GB/S)"
+              << std::setw(14) << "BW (GB/s)"
+              << std::setw(18) << "Avg Inst GB/s"
               << std::setw(14) << "Avg Lat (us)"
               << std::setw(14) << "Avg Tx (us)"
               << std::setw(14) << "P99 Tx (us)"
@@ -212,6 +315,7 @@ void printStats(size_t block_size, size_t batch_size, XferBenchStats& stats,
     avg_latency = (total_duration * num_threads / num_ops);
     throughput_gb = (((double)total_data_transferred / (1000 * 1000 * 1000)) /
                      (total_duration / 1e6));  // In GB/Sec
+    const double avg_instant_gbps = stats.instant_bandwidth.avg();
 
     // Tabulate print with fixed width for each string
     // clang-format off
@@ -219,6 +323,7 @@ void printStats(size_t block_size, size_t batch_size, XferBenchStats& stats,
               << std::setw(14) << block_size
               << std::setw(8)  << batch_size
               << std::setw(14) << throughput_gb
+              << std::setw(18) << avg_instant_gbps
               << std::setprecision(1)
               << std::setw(14) << avg_latency
               << std::setw(14) << stats.transfer_duration.avg()
@@ -243,5 +348,27 @@ void printDeadlineGroupStats(const char* group, size_t block_size,
               << throughput_gbs << " GB/s" << std::endl;
 }
 
+std::vector<std::string> splitCommaSeparated(const std::string& value) {
+    std::vector<std::string> result;
+    std::stringstream ss(value);
+    std::string token;
+    while (std::getline(ss, token, ',')) {
+        const size_t begin = token.find_first_not_of(" \t\r\n");
+        if (begin == std::string::npos) continue;
+        const size_t end = token.find_last_not_of(" \t\r\n");
+        result.push_back(token.substr(begin, end - begin + 1));
+    }
+    return result;
+}
+
+uint8_t stableDataSeed(uint64_t target_addr) {
+    uint64_t value = target_addr;
+    value ^= value >> 33;
+    value *= 0xff51afd7ed558ccdULL;
+    value ^= value >> 33;
+    uint8_t seed = static_cast<uint8_t>(value);
+    return seed == 0 ? 1 : seed;
+}
+
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/benchmark/utils.h b/mooncake-transfer-engine/benchmark/utils.h
index 9d6cab1e6c..1cb2c3f738 100644
--- a/mooncake-transfer-engine/benchmark/utils.h
+++ b/mooncake-transfer-engine/benchmark/utils.h
@@ -26,6 +26,8 @@
 #include <numeric>
 #include <stdexcept>
 #include <chrono>
+#include <limits>
+#include <random>
 
 #include "tent/common/utils/os.h"
 #include "tent/common/utils/random.h"
@@ -71,11 +73,16 @@ struct XferBenchConfig {
     static int duration;
     static int max_num_threads;
     static int start_num_threads;
+    static size_t target_offset;
+    static size_t target_range_size;
     static std::string qos_classes;
     static std::string qos_classes_json;
     static std::string workload_classes_json;
     static double qos_link_capacity_gbps;
     static std::string qos_output_jsonl;
+    static std::string result_output_jsonl;
+    static std::string split_output_jsonl;
+    static uint64_t request_interval_us;
     static uint64_t deadline_us;
     static int deadline_tight_threads;
     static bool deadline_bw_arbitration;
@@ -85,6 +92,9 @@ struct XferBenchConfig {
     static int rpc_server_port;
     static std::string xport_type;
     static std::string backend;
+    static bool use_hugepage;
+    static size_t hugepage_size;
+    static std::string hugetlbfs_path;
     static bool notifi;
     static std::string tent_transport_hint;
     static std::string tent_intent_type;
@@ -147,6 +157,7 @@ struct XferMetricStats {
 struct XferBenchStats {
     XferMetricStats total_duration;
     XferMetricStats transfer_duration;
+    XferMetricStats instant_bandwidth;
 };
 
 class XferBenchTimer {
@@ -181,6 +192,31 @@ void printDeadlineGroupStats(const char* group, size_t block_size,
                              size_t batch_size, XferBenchStats& stats,
                              int num_threads, uint64_t deadline_us);
 
+std::vector<std::string> splitCommaSeparated(const std::string& value);
+
+uint8_t stableDataSeed(uint64_t target_addr);
+
+static inline uint64_t checkedMul(uint64_t lhs, uint64_t rhs,
+                                  const char* label) {
+    if (rhs != 0 && lhs > std::numeric_limits<uint64_t>::max() / rhs) {
+        LOG(FATAL) << label << " overflows uint64_t: " << lhs << " * " << rhs;
+    }
+    return lhs * rhs;
+}
+
+static inline uint64_t checkedAdd(uint64_t lhs, uint64_t rhs,
+                                  const char* label) {
+    if (lhs > std::numeric_limits<uint64_t>::max() - rhs) {
+        LOG(FATAL) << label << " overflows uint64_t: " << lhs << " + " << rhs;
+    }
+    return lhs + rhs;
+}
+
+static inline bool rangeContains(uint64_t offset, uint64_t bytes,
+                                 uint64_t limit) {
+    return offset <= limit && bytes <= limit - offset;
+}
+
 #if defined(USE_CUDA) || defined(USE_SUNRISE)
 static inline bool isCudaMemory(void* ptr) {
     cudaPointerAttributes attr;
@@ -207,32 +243,46 @@ static inline bool isGpuMemory(void* ptr) {
     return false;
 }
 
-static inline uint8_t fillData(void* addr, size_t length) {
-    uint8_t seed = (uint8_t)SimpleRandom::Get().next(256);
+static inline void fillData(void* addr, size_t length, uint8_t seed) {
 #if defined(USE_CUDA)
     if (isCudaMemory(addr)) {
-        std::vector<uint8_t> ref_data(length, seed);
-        cudaMemcpy(addr, ref_data.data(), length, cudaMemcpyDefault);
-        return seed;
+        auto err = cudaMemset(addr, seed, length);
+        LOG_ASSERT(err == cudaSuccess)
+            << "cudaMemset failed: " << cudaGetErrorString(err);
+        return;
     }
 #elif defined(USE_SUNRISE)
     if (isCudaMemory(addr)) {
-        std::vector<uint8_t> ref_data(length, seed);
-        auto err =
-            cudaMemcpy(addr, ref_data.data(), length, cudaMemcpyHostToDevice);
+        auto err = cudaMemset(addr, seed, length);
         LOG_ASSERT(err == cudaSuccess)
-            << "cudaMemcpy failed: " << cudaGetErrorString(err);
-        return seed;
+            << "cudaMemset failed: " << cudaGetErrorString(err);
+        return;
     }
 #endif
 #ifdef USE_HIP
     if (isHipMemory(addr)) {
-        std::vector<uint8_t> ref_data(length, seed);
-        hipMemcpy(addr, ref_data.data(), length, hipMemcpyDefault);
-        return seed;
+        auto err = hipMemset(addr, seed, length);
+        LOG_ASSERT(err == hipSuccess)
+            << "hipMemset failed: " << hipGetErrorString(err);
+        return;
     }
 #endif
-    memset(addr, seed, length);
+    if (XferBenchConfig::xport_type != "hp_tcp" ||
+        !XferBenchConfig::check_consistency) {
+        memset(addr, seed, length);
+        return;
+    }
+    // A constant byte pattern cannot detect reordered or duplicated slices.
+    std::mt19937 data(seed);
+    auto* bytes = static_cast<uint8_t*>(addr);
+    for (size_t i = 0; i < length; ++i) {
+        bytes[i] = static_cast<uint8_t>(data());
+    }
+}
+
+static inline uint8_t fillData(void* addr, size_t length) {
+    uint8_t seed = (uint8_t)SimpleRandom::Get().next(256);
+    fillData(addr, length, seed);
     return seed;
 }
 
@@ -270,6 +320,10 @@ static inline void verifyData(void* addr, size_t length, uint8_t seed) {
         return;
     }
 #endif
+    if (XferBenchConfig::xport_type == "hp_tcp" &&
+        XferBenchConfig::check_consistency) {
+        fillData(ref_data.data(), length, seed);
+    }
     if (memcmp(addr, ref_data.data(), length)) {
         LOG(FATAL) << "Inconsistent data detected";
     }
diff --git a/mooncake-transfer-engine/example/CMakeLists.txt b/mooncake-transfer-engine/example/CMakeLists.txt
index cdd681ad67..d1eac4ed9e 100644
--- a/mooncake-transfer-engine/example/CMakeLists.txt
+++ b/mooncake-transfer-engine/example/CMakeLists.txt
@@ -67,7 +67,7 @@ if(USE_UBSHMEM)
   target_link_libraries(transfer_engine_bench PUBLIC transfer_engine)
 endif()
 
-# Device Transport Example — two-rank P2P write + signal via Device API.
+# Device Transport Example - two-rank P2P write + signal via Device API.
 # Requires 2 GPUs with P2P access.  Built but not registered with CTest
 # (manual execution only, like rdma_transport_test).
 #
@@ -107,8 +107,13 @@ if(USE_CUDA AND BUILD_DEVICE_TRANSPORT_EXAMPLE)
     set_target_properties(device_transport_example PROPERTIES
       CUDA_ARCHITECTURES "${_cuda_arch_list}")
   else()
-    set_target_properties(device_transport_example PROPERTIES
-      CUDA_ARCHITECTURES "80;90")
+    if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL "13.0")
+      set_target_properties(device_transport_example PROPERTIES
+        CUDA_ARCHITECTURES "80;90;103")
+    else()
+      set_target_properties(device_transport_example PROPERTIES
+        CUDA_ARCHITECTURES "80;90")
+    endif()
   endif()
 endif()
 
@@ -144,8 +149,13 @@ if(USE_NCCL_DEVICE AND BUILD_NCCL_DEVICE_TRANSPORT_EXAMPLE)
       set_target_properties(nccl_device_transport_example PROPERTIES
         CUDA_ARCHITECTURES "${_nccl_cuda_arch_list}")
     else()
-      set_target_properties(nccl_device_transport_example PROPERTIES
-        CUDA_ARCHITECTURES "80;90")
+      if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL "13.0")
+        set_target_properties(nccl_device_transport_example PROPERTIES
+          CUDA_ARCHITECTURES "80;90;103")
+      else()
+        set_target_properties(nccl_device_transport_example PROPERTIES
+          CUDA_ARCHITECTURES "80;90")
+      endif()
     endif()
   endif()
 endif()
diff --git a/mooncake-transfer-engine/example/transfer_engine_bench.cpp b/mooncake-transfer-engine/example/transfer_engine_bench.cpp
index 13e4b0f7bf..241212aae7 100644
--- a/mooncake-transfer-engine/example/transfer_engine_bench.cpp
+++ b/mooncake-transfer-engine/example/transfer_engine_bench.cpp
@@ -47,7 +47,7 @@
     defined(USE_UBSHMEM) || defined(USE_SUPA) || defined(USE_SUNRISE)
 #include <cassert>
 
-#if defined(USE_MNNVL) || defined(USE_UBSHMEM)
+#if defined(USE_MNNVL) || defined(USE_MUSA) || defined(USE_UBSHMEM)
 #include "gpu_vendor/mnnvl.h"
 #endif
 
@@ -90,7 +90,7 @@ DEFINE_string(operation, "read", "Operation type: read or write");
 
 DEFINE_string(protocol, "rdma",
               "Transfer protocol: "
-              "rdma|barex|tcp|efa|nvlink|nvlink_intra|hip|sunrise_link");
+              "rdma|barex|tcp|efa|nvlink|musa|nvlink_intra|hip|sunrise_link");
 
 DEFINE_string(device_name, "mlx5_2",
               "Device name to use, valid if protocol=rdma");
@@ -139,13 +139,14 @@ static void* allocateMemoryPool(size_t size, int buffer_id,
         LOG(INFO) << "Allocating memory on GPU " << gpu_id;
         checkCudaError(cudaSetDevice(gpu_id), "Failed to set device");
 #endif
-        if (FLAGS_protocol == "nvlink" || FLAGS_protocol == "hip") {
-#ifdef USE_MNNVL
+        if (FLAGS_protocol == "nvlink" || FLAGS_protocol == "musa" ||
+            FLAGS_protocol == "hip") {
+#if defined(USE_MNNVL) || defined(USE_MUSA)
             d_buf = allocateFabricMemory(size);
-            LOG(INFO) << "Using MNNVL fabric memory allocation";
+            LOG(INFO) << "Using GPU fabric/IPC memory allocation";
 #else
-            LOG(ERROR)
-                << "--protocol=nvlink or --protocol=hip requires USE_MNNVL=ON";
+            LOG(ERROR) << "--protocol=nvlink/musa/hip requires USE_MNNVL=ON or "
+                          "USE_MUSA=ON";
             return nullptr;
 #endif
         } else if (FLAGS_protocol == "nvlink_intra") {
@@ -196,13 +197,14 @@ static void freeMemoryPool(void* addr, size_t size) {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||    \
     defined(USE_MACA) || defined(USE_HYGON) || defined(USE_COREX) || \
     defined(USE_UBSHMEM) || defined(USE_SUPA) || defined(USE_SUNRISE)
-    if (FLAGS_protocol == "nvlink" || FLAGS_protocol == "hip") {
-#ifdef USE_MNNVL
+    if (FLAGS_protocol == "nvlink" || FLAGS_protocol == "musa" ||
+        FLAGS_protocol == "hip") {
+#if defined(USE_MNNVL) || defined(USE_MUSA)
         if (FLAGS_use_vram) {
             freeFabricMemory(addr);
             return;
         }
-#endif  // USE_MNNVL
+#endif  // USE_MNNVL || USE_MUSA
     } else if (FLAGS_protocol == "nvlink_intra") {
 #ifdef USE_INTRA_NVLINK
         if (FLAGS_use_vram) {
@@ -511,9 +513,10 @@ static Transport* installTransportFromFlags(TransferEngine* engine) {
         engine->getLocalTopology()->discover({});
         xport = engine->installTransport("efa", nullptr);
     } else if (FLAGS_protocol == "tcp" || FLAGS_protocol == "nvlink" ||
-               FLAGS_protocol == "hip" || FLAGS_protocol == "nvlink_intra" ||
+               FLAGS_protocol == "musa" || FLAGS_protocol == "hip" ||
+               FLAGS_protocol == "nvlink_intra" ||
                FLAGS_protocol == "ubshmem" ||
-               FLAGS_protocol == "sunrise_link") {
+               FLAGS_protocol == "sunrise_link" || FLAGS_protocol == "flagcx") {
         xport = engine->installTransport(FLAGS_protocol.c_str(), nullptr);
     } else {
         LOG(ERROR) << "Unsupported protocol: " << FLAGS_protocol;
diff --git a/mooncake-transfer-engine/example/transfer_engine_bench_with_notify.cpp b/mooncake-transfer-engine/example/transfer_engine_bench_with_notify.cpp
index 2d76210f65..3c1389bb6c 100644
--- a/mooncake-transfer-engine/example/transfer_engine_bench_with_notify.cpp
+++ b/mooncake-transfer-engine/example/transfer_engine_bench_with_notify.cpp
@@ -41,7 +41,7 @@
     defined(USE_MACA) || defined(USE_HYGON) || defined(USE_COREX)
 #include <cassert>
 
-#ifdef USE_MNNVL
+#if defined(USE_MNNVL) || defined(USE_MUSA)
 #include "gpu_vendor/mnnvl.h"
 #endif
 
@@ -74,7 +74,7 @@ DEFINE_string(mode, "initiator",
               "data blocks from target node");
 DEFINE_string(operation, "read", "Operation type: read or write");
 
-DEFINE_string(protocol, "rdma", "Transfer protocol: rdma|tcp|nvlink|hip");
+DEFINE_string(protocol, "rdma", "Transfer protocol: rdma|tcp|nvlink|musa|hip");
 
 DEFINE_string(device_name, "mlx5_2",
               "Device name to use, valid if protocol=rdma");
@@ -108,7 +108,7 @@ static void *allocateMemoryPool(size_t size, int socket_id,
         int gpu_id = FLAGS_gpu_id;
         void *d_buf;
         checkCudaError(cudaSetDevice(gpu_id), "Failed to set device");
-#ifdef USE_MNNVL
+#if defined(USE_MNNVL) || defined(USE_MUSA)
         d_buf = allocateFabricMemory(size);
 #else
         checkCudaError(cudaMalloc(&d_buf, size),
@@ -130,12 +130,12 @@ static void *allocateMemoryPool(size_t size, int socket_id,
 static void freeMemoryPool(void *addr, size_t size) {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
     defined(USE_MACA) || defined(USE_HYGON) || defined(USE_COREX)
-#ifdef USE_MNNVL
+#if defined(USE_MNNVL) || defined(USE_MUSA)
     if (FLAGS_use_vram) {
         freeFabricMemory(addr);
         return;
     }
-#endif  // USE_MNNVL
+#endif  // USE_MNNVL || USE_MUSA
 
     // check pointer on GPU
     cudaPointerAttributes attributes;
@@ -328,6 +328,8 @@ int initiator() {
             xport = engine->installTransport("tcp", nullptr);
         } else if (FLAGS_protocol == "nvlink") {
             xport = engine->installTransport("nvlink", nullptr);
+        } else if (FLAGS_protocol == "musa") {
+            xport = engine->installTransport("musa", nullptr);
         } else if (FLAGS_protocol == "nvlink_intra") {
             xport = engine->installTransport("nvlink_intra", nullptr);
         } else if (FLAGS_protocol == "hip") {
@@ -431,6 +433,8 @@ int target() {
             engine->installTransport("tcp", nullptr);
         } else if (FLAGS_protocol == "nvlink") {
             engine->installTransport("nvlink", nullptr);
+        } else if (FLAGS_protocol == "musa") {
+            engine->installTransport("musa", nullptr);
         } else if (FLAGS_protocol == "hip") {
             engine->installTransport("hip", nullptr);
         } else {
diff --git a/mooncake-transfer-engine/example/transfer_engine_validator.cpp b/mooncake-transfer-engine/example/transfer_engine_validator.cpp
index 0756012aa7..807dea3d5e 100644
--- a/mooncake-transfer-engine/example/transfer_engine_validator.cpp
+++ b/mooncake-transfer-engine/example/transfer_engine_validator.cpp
@@ -70,7 +70,8 @@ DEFINE_string(mode, "initiator",
               "Running mode: initiator or target. Initiator node read/write "
               "data blocks from target node");
 
-DEFINE_string(protocol, "rdma", "Transfer protocol: rdma|tcp|nvlink|hip");
+DEFINE_string(protocol, "rdma",
+              "Transfer protocol: rdma|tcp|nvlink|musa|maca|hip");
 
 DEFINE_string(device_name, "mlx5_2",
               "Device name to use, valid if protocol=rdma");
@@ -415,6 +416,8 @@ int initiator() {
             xport = engine->installTransport("nvlink_intra", nullptr);
         } else if (FLAGS_protocol == "maca") {
             xport = engine->installTransport("maca", nullptr);
+        } else if (FLAGS_protocol == "musa") {
+            xport = engine->installTransport("musa", nullptr);
         } else if (FLAGS_protocol == "hip") {
             xport = engine->installTransport("hip", nullptr);
         } else {
@@ -540,6 +543,8 @@ int target() {
             engine->installTransport("nvlink", nullptr);
         } else if (FLAGS_protocol == "maca") {
             engine->installTransport("maca", nullptr);
+        } else if (FLAGS_protocol == "musa") {
+            engine->installTransport("musa", nullptr);
         } else if (FLAGS_protocol == "hip") {
             engine->installTransport("hip", nullptr);
         } else {
diff --git a/mooncake-transfer-engine/include/CMakeLists.txt b/mooncake-transfer-engine/include/CMakeLists.txt
index 7d5444d452..8634964243 100644
--- a/mooncake-transfer-engine/include/CMakeLists.txt
+++ b/mooncake-transfer-engine/include/CMakeLists.txt
@@ -1,4 +1,5 @@
 install(FILES transfer_engine_c.h DESTINATION include)
+install(FILES buffer_range_index.h DESTINATION include)
 install(FILES common.h DESTINATION include)
 install(FILES config.h DESTINATION include)
 install(FILES error.h DESTINATION include)
@@ -12,17 +13,30 @@ install(FILES common/base/status.h DESTINATION include/common/base)
 install(FILES transport/transport.h DESTINATION include/transport)
 
 # Device API headers (header-only, consumed by EP kernel)
-install(FILES transport/device/device_transport.h DESTINATION include/transport/device)
-install(FILES transport/device/device_ops.cuh DESTINATION include/transport/device)
-install(FILES transport/device/comm_device.cuh DESTINATION include/transport/device)
-install(FILES transport/device/p2p_device.cuh DESTINATION include/transport/device)
-install(FILES transport/device/ibgda_device.cuh DESTINATION include/transport/device)
-install(FILES transport/device/nccl_device_transport.h DESTINATION include/transport/device)
-install(FILES transport/device/nccl_device.cuh DESTINATION include/transport/device)
-install(FILES transport/device/cuda/cuda_ops.cuh DESTINATION include/transport/device/cuda)
-install(FILES transport/device/musa/musa_ops.cuh DESTINATION include/transport/device/musa)
-install(FILES transport/device/maca/maca_ops.cuh DESTINATION include/transport/device/maca)
+install(FILES transport/device/device_transport.h
+        DESTINATION include/transport/device)
+install(FILES transport/device/device_ops.cuh
+        DESTINATION include/transport/device)
+install(FILES transport/device/comm_device.cuh
+        DESTINATION include/transport/device)
+install(FILES transport/device/p2p_device.cuh
+        DESTINATION include/transport/device)
+install(FILES transport/device/ibgda_device.cuh
+        DESTINATION include/transport/device)
+install(FILES transport/device/nccl_device_transport.h
+        DESTINATION include/transport/device)
+install(FILES transport/device/nccl_device.cuh
+        DESTINATION include/transport/device)
+install(FILES transport/device/cuda/cuda_ops.cuh
+        DESTINATION include/transport/device/cuda)
+install(FILES transport/device/musa/musa_ops.cuh
+        DESTINATION include/transport/device/musa)
+install(FILES transport/device/maca/maca_ops.cuh
+        DESTINATION include/transport/device/maca)
 
 # IBGDA library headers
-install(DIRECTORY transport/device/ibgda/ DESTINATION include/transport/device/ibgda
-        FILES_MATCHING PATTERN "*.h")
+install(
+  DIRECTORY transport/device/ibgda/
+  DESTINATION include/transport/device/ibgda
+  FILES_MATCHING
+  PATTERN "*.h")
diff --git a/mooncake-transfer-engine/include/ascend_allocator.h b/mooncake-transfer-engine/include/ascend_allocator.h
index 4f4c1f7392..a0ca20802d 100644
--- a/mooncake-transfer-engine/include/ascend_allocator.h
+++ b/mooncake-transfer-engine/include/ascend_allocator.h
@@ -9,19 +9,30 @@
 namespace mooncake {
 void* ascend_allocate_memory(size_t total_size, const std::string& protocol);
 
-// Fabric-mem best-effort: try 100%/90%/.../50% of target (1G-aligned).
-// Sets *actual_size on success; returns nullptr if 50% also fails.
-// Non-fabric paths fall back to exact-size ascend_allocate_memory.
+// Matches store allocate_buffer_mmap_memory(size, alignment, defer_populate).
+using AscendHostAllocFn = void* (*)(size_t, size_t, bool);
+
+// Allocate on the current agent-mode device (round-robin).
+// Fabric-mem: try 100%/90%/.../50% of target (1G-aligned); host_alloc is
+// ignored. Otherwise: exact-size via host_alloc, or aclrtMallocHost if
+// host_alloc is null. Sets *actual_size on success.
 void* ascend_allocate_memory_best_effort(size_t target_size,
                                          const std::string& protocol,
-                                         size_t* actual_size);
+                                         size_t* actual_size,
+                                         AscendHostAllocFn host_alloc = nullptr,
+                                         size_t host_alignment = 0,
+                                         bool defer_hugetlb_population = false);
 
 void ascend_free_memory(const std::string& protocol, void* ptr);
 
 // Check if [addr, addr+length) overlaps with any store memory range.
-// Used by registerLocalMemory to decide RoCE+store registration policy.
 bool ascend_is_store_memory(void* addr, size_t length);
 
+// Check whether addr starts inside a direct ACL VMM allocation (allocated via
+// ascend_allocate_vmm_memory_direct). Returns false for adxl::MallocMem
+// allocations and non-VMM host buffers.
+bool ascend_is_direct_vmm_memory(void* addr, size_t length);
+
 // Direct ACL VMM allocation, always bypasses adxl MallocMem.
 // For use by shm_helper when ascend_agent_mode && ascend_use_fabric_mem.
 // Requires size to be a multiple of 1GB. Returns nullptr on failure.
diff --git a/mooncake-transfer-engine/include/buffer_range_index.h b/mooncake-transfer-engine/include/buffer_range_index.h
new file mode 100644
index 0000000000..bc54b675a0
--- /dev/null
+++ b/mooncake-transfer-engine/include/buffer_range_index.h
@@ -0,0 +1,123 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef BUFFER_RANGE_INDEX_H_
+#define BUFFER_RANGE_INDEX_H_
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <vector>
+
+namespace mooncake {
+
+// Coverage predicates for BufferDesc-style {addr, length} records. A request
+// must sit entirely inside one MR. Length 0 degenerates to point containment,
+// so an address on the exclusive end of one buffer belongs to the next one
+// only.
+inline bool bufferCoversPoint(uint64_t buf_addr, uint64_t buf_len,
+                              uint64_t address) {
+    return address >= buf_addr && address - buf_addr < buf_len;
+}
+
+inline bool bufferCoversRange(uint64_t buf_addr, uint64_t buf_len,
+                              uint64_t offset, size_t length) {
+    if (length == 0) return bufferCoversPoint(buf_addr, buf_len, offset);
+    return offset >= buf_addr && length <= buf_len &&
+           offset - buf_addr <= buf_len - length;
+}
+
+// Address-sorted snapshot of a SegmentDesc buffer list, so a lookup that
+// misses the caller's last-hit cache does not rescan every registered MR.
+//
+// Lookups are answered for non-overlapping lists only. There a covering
+// buffer is unique, so the answer is necessarily the same one a linear scan
+// would have matched first. Overlapping lists report overlaps() and are left
+// to the plain original-order scan, which keeps first-match semantics true by
+// construction instead of by reconstruction.
+//
+// The snapshot is derived from `buffers`: rebuild it after every mutation of
+// that vector, before the descriptor is published.
+class BufferRangeIndex {
+   public:
+    BufferRangeIndex() = default;
+
+    template <typename Buffer>
+    explicit BufferRangeIndex(const std::vector<Buffer> &buffers) {
+        rebuild(buffers);
+    }
+
+    template <typename Buffer>
+    void rebuild(const std::vector<Buffer> &buffers) {
+        by_start_.clear();
+        by_start_.reserve(buffers.size());
+        for (size_t i = 0; i < buffers.size(); ++i) {
+            by_start_.push_back(
+                Entry{buffers[i].addr, buffers[i].length, static_cast<int>(i)});
+        }
+        std::sort(by_start_.begin(), by_start_.end(),
+                  [](const Entry &a, const Entry &b) {
+                      if (a.addr != b.addr) return a.addr < b.addr;
+                      return a.index < b.index;
+                  });
+        overlaps_ = false;
+        for (size_t i = 1; i < by_start_.size(); ++i) {
+            if (by_start_[i].addr < exclusiveEnd(by_start_[i - 1])) {
+                overlaps_ = true;
+                break;
+            }
+        }
+    }
+
+    bool empty() const { return by_start_.empty(); }
+    bool overlaps() const { return overlaps_; }
+    size_t size() const { return by_start_.size(); }
+
+    // Position in the original buffer list of the MR covering
+    // [addr, addr + length), or -1 when there is none. Overlapping lists
+    // always answer -1.
+    int findCovering(uint64_t addr, size_t length) const {
+        if (overlaps_ || by_start_.empty()) return -1;
+        const auto first_after =
+            std::upper_bound(by_start_.begin(), by_start_.end(), addr,
+                             [](uint64_t value, const Entry &entry) {
+                                 return value < entry.addr;
+                             });
+        if (first_after == by_start_.begin()) return -1;
+        const Entry &candidate = *std::prev(first_after);
+        return bufferCoversRange(candidate.addr, candidate.length, addr, length)
+                   ? candidate.index
+                   : -1;
+    }
+
+   private:
+    struct Entry {
+        uint64_t addr = 0;
+        uint64_t length = 0;
+        int index = 0;
+    };
+
+    static uint64_t exclusiveEnd(const Entry &entry) {
+        const uint64_t end = entry.addr + entry.length;
+        return end < entry.addr ? std::numeric_limits<uint64_t>::max() : end;
+    }
+
+    std::vector<Entry> by_start_;
+    bool overlaps_ = false;
+};
+
+}  // namespace mooncake
+
+#endif  // BUFFER_RANGE_INDEX_H_
diff --git a/mooncake-transfer-engine/include/common.h b/mooncake-transfer-engine/include/common.h
index 6ad2fb582e..1053b3813b 100644
--- a/mooncake-transfer-engine/include/common.h
+++ b/mooncake-transfer-engine/include/common.h
@@ -35,6 +35,7 @@
 #include <mutex>
 #include <optional>
 #include <sstream>
+#include <string>
 #include <string_view>
 #include <thread>
 #include <vector>
@@ -77,6 +78,61 @@ static inline std::string getHostname() {
     return hostname;
 }
 
+// Options for TransferEngine::allocateSharedMemory / ShmTransport.
+// Default path stays POSIX /dev/shm. Store production sets use_hugepage with
+// hugepage_size matching MC_STORE_HUGEPAGE_SIZE (2MB / 512MB / 1GB).
+//
+// Crash / SIGKILL leftovers: freeSharedMemory and ~ShmTransport unlink the
+// object. SIGKILL skips that, so POSIX names stay in /dev/shm and hugetlbfs
+// files stay on the mount. Hugetlbfs leftovers keep hugepages reserved until
+// the file is unlinked or the node reboots — worse than tmpfs leftovers.
+// There is no startup reaper (multiple processes share a mount; wiping
+// mooncake_* would delete live peers). Operators may remove files named
+// mooncake_<dead-pid>_* after confirming that pid is gone, e.g.
+//   rm /dev/hugepages/mooncake_<pid>_*
+struct SharedMemoryOptions {
+    bool use_hugepage = false;
+    size_t hugepage_size = 0;    // 0 → 2MB when use_hugepage
+    std::string hugetlbfs_path;  // empty → size-specific default mount
+    bool populate = true;        // Store passes false and populates itself
+
+    static constexpr size_t kHugepage2MB = 2ULL << 20;
+    static constexpr size_t kHugepage512MB = 512ULL << 20;
+    static constexpr size_t kHugepage1GB = 1ULL << 30;
+
+    static bool isSupportedHugepageSize(size_t size) {
+        return size == kHugepage2MB || size == kHugepage512MB ||
+               size == kHugepage1GB;
+    }
+
+    static const char *defaultHugetlbfsPathFor(size_t hugepage_size) {
+        if (hugepage_size == kHugepage1GB) return "/dev/hugepages-1G";
+        if (hugepage_size == kHugepage512MB) return "/dev/hugepages-512M";
+        return "/dev/hugepages";
+    }
+};
+
+// True when the variable is set to anything other than 0/false/no/off.
+// Used by MC_FORCE_SHM.
+inline bool envFlagEnabled(const char *name) {
+    const char *value = std::getenv(name);
+    if (!value || !*value) return false;
+    auto eqIgnoreCase = [](const char *a, const char *b) {
+        for (; *a && *b; ++a, ++b) {
+            unsigned char ca = static_cast<unsigned char>(*a);
+            unsigned char cb = static_cast<unsigned char>(*b);
+            if (ca >= 'A' && ca <= 'Z')
+                ca = static_cast<unsigned char>(ca - 'A' + 'a');
+            if (cb >= 'A' && cb <= 'Z')
+                cb = static_cast<unsigned char>(cb - 'A' + 'a');
+            if (ca != cb) return false;
+        }
+        return *a == *b;
+    };
+    return !eqIgnoreCase(value, "0") && !eqIgnoreCase(value, "false") &&
+           !eqIgnoreCase(value, "no") && !eqIgnoreCase(value, "off");
+}
+
 // libnuma fills the cache numa_node_to_cpus() reads lazily and without locking,
 // so concurrent first callers each allocate it and all but one are orphaned --
 // a leak LeakSanitizer fails the build on. Worker pools bind every thread at
@@ -146,6 +202,20 @@ static inline std::string getCurrentDateTime() {
     return oss.str();
 }
 
+static inline std::string formatEpochMicroseconds(uint64_t epoch_us) {
+    if (epoch_us == 0) return "legacy(0)";
+
+    const auto seconds = static_cast<std::time_t>(epoch_us / 1000000);
+    const auto micros = epoch_us % 1000000;
+    std::tm local_time{};
+    localtime_r(&seconds, &local_time);
+
+    std::ostringstream oss;
+    oss << std::put_time(&local_time, "%Y-%m-%d %H:%M:%S") << "."
+        << std::setw(6) << std::setfill('0') << micros;
+    return oss.str();
+}
+
 uint16_t getDefaultHandshakePort();
 
 template <typename T>
diff --git a/mooncake-transfer-engine/include/config.h b/mooncake-transfer-engine/include/config.h
index 6686e9de37..33c51eac77 100644
--- a/mooncake-transfer-engine/include/config.h
+++ b/mooncake-transfer-engine/include/config.h
@@ -91,6 +91,12 @@ struct GlobalConfig {
     // not-yet-posted slices fail/redispatch instead of hanging. 0 disables.
     // Override via MC_CONN_PAUSE_TTL_MS.
     int conn_pause_ttl_ms = 0;
+    // Context-level circuit-breaker pause. Repeated local WC failures
+    // deactivate the local RNIC context for this many milliseconds. The
+    // monitor then reactivates it with a reset failure count. Must be positive
+    // so a breaker trip cannot recreate the legacy permanent latch. Override
+    // via MC_CONTEXT_PAUSE_TTL_MS.
+    int context_pause_ttl_ms = 5000;
     uint16_t rpc_min_port = 15000;
     uint16_t rpc_max_port = 17000;
     bool use_ipv6 = false;
@@ -128,6 +134,26 @@ struct GlobalConfig {
     // + 1. num_lag_ports is queried from hardware; if the device is not in LAG
     // mode the setting is a no-op. Requires USE_MLX5DV.
     bool mlx5_qp_lag_port_balance = false;
+    // Install RdmaTwoSidedTransport (CtrlChannel notify) instead of classic
+    // one-sided RdmaTransport. MC_USE_RDMA_TWOSIDED.
+    bool use_rdma_twosided = false;
+    // RDMA notifications for rdma and rdma_twosided. MC_RDMA_NOTIFY_ENABLED.
+    bool rdma_notify_enabled = true;
+    // Ctrl recv/send slot count and slot size. MC_RDMA_NOTIFY_RECV_COUNT /
+    // MC_RDMA_NOTIFY_BUFFER_SIZE.
+    size_t rdma_notify_recv_count = 64;
+    size_t rdma_notify_buffer_size = 4096;
+    // Local pending SEND cap; actual cap is min(this, peer notify_rq_depth).
+    // MC_RDMA_NOTIFY_MAX_PENDING_SENDS.
+    size_t rdma_notify_max_pending_sends = 64;
+    // Allow OOB RPC fallback when the RDMA notification path is unavailable.
+    // MC_RDMA_NOTIFY_OOB_FALLBACK.
+    bool rdma_notify_oob_fallback = true;
+    // Upper bound for waiting on an in-flight CtrlChannel connect to the same
+    // peer. On expiry the notify falls back to OOB instead of blocking on a
+    // handshake that may never complete.
+    // MC_RDMA_NOTIFY_CONNECT_TIMEOUT_MS.
+    uint32_t rdma_notify_connect_timeout_ms = 10000;
     // ib_pci_relaxed_ordering_mode: 0: off, 1: on if supported, 2: auto
     int ib_pci_relaxed_ordering_mode = 1;
     bool ascend_use_fabric_mem = false;
diff --git a/mooncake-transfer-engine/include/cuda_alike.h b/mooncake-transfer-engine/include/cuda_alike.h
index bcec46db45..b9f62ef3e4 100644
--- a/mooncake-transfer-engine/include/cuda_alike.h
+++ b/mooncake-transfer-engine/include/cuda_alike.h
@@ -3,6 +3,7 @@
 #ifdef USE_CUDA
 #include <cuda.h>
 #include <cuda_runtime.h>
+#include "cuda_fabric_compat.h"
 #elif defined(USE_HIP)
 #include "gpu_vendor/hip.h"
 #elif defined(USE_MUSA)
@@ -20,9 +21,11 @@
 #elif defined(USE_HYGON)
 #include <cuda.h>
 #include <cuda_runtime.h>
+#include "cuda_fabric_compat.h"
 #elif defined(USE_COREX)
 #include <cuda.h>
 #include <cuda_runtime.h>
+#include "cuda_fabric_compat.h"
 #endif
 
 #if !defined(USE_HIP) && !defined(USE_MUSA) && !defined(USE_MLU) &&         \
diff --git a/mooncake-transfer-engine/include/cuda_fabric_compat.h b/mooncake-transfer-engine/include/cuda_fabric_compat.h
new file mode 100644
index 0000000000..bdb7759044
--- /dev/null
+++ b/mooncake-transfer-engine/include/cuda_fabric_compat.h
@@ -0,0 +1,3 @@
+#pragma once
+
+#include "../tent/include/tent/common/cuda_fabric_compat.h"
diff --git a/mooncake-transfer-engine/include/gpu_vendor/maca.h b/mooncake-transfer-engine/include/gpu_vendor/maca.h
index 04c96004de..962323cb4a 100644
--- a/mooncake-transfer-engine/include/gpu_vendor/maca.h
+++ b/mooncake-transfer-engine/include/gpu_vendor/maca.h
@@ -103,6 +103,7 @@ static inline CUresult cuGetErrorString(CUresult error, const char **err_str) {
 #define cudaHostAllocPortable mcMallocHostPortable
 #define cudaHostAllocWriteCombined mcMallocHostWriteCombined
 #define cudaHostRegister mcHostRegister
+#define cudaHostRegisterIoMemory mcHostRegisterIoMemory
 #define cudaHostRegisterMapped mcHostRegisterMapped
 #define cudaHostRegisterPortable mcHostRegisterPortable
 #define cudaHostUnregister mcHostUnregister
diff --git a/mooncake-transfer-engine/include/gpu_vendor/mnnvl.h b/mooncake-transfer-engine/include/gpu_vendor/mnnvl.h
index 72add585ae..2aa02d4071 100644
--- a/mooncake-transfer-engine/include/gpu_vendor/mnnvl.h
+++ b/mooncake-transfer-engine/include/gpu_vendor/mnnvl.h
@@ -26,6 +26,12 @@
     mooncake::UBShmemTransport::allocatePinnedLocalMemory(size)
 #define freeFabricMemory(addr) \
     mooncake::UBShmemTransport::freePinnedLocalMemory(addr)
+#elif defined(USE_MUSA)
+#include <transport/musa_transport/musa_transport.h>
+#define allocateFabricMemory(size) \
+    mooncake::MusaTransport::allocatePinnedLocalMemory(size)
+#define freeFabricMemory(addr) \
+    mooncake::MusaTransport::freePinnedLocalMemory(addr)
 #else
 #include <transport/nvlink_transport/nvlink_transport.h>
 #define allocateFabricMemory(size) \
diff --git a/mooncake-transfer-engine/include/gpu_vendor/musa.h b/mooncake-transfer-engine/include/gpu_vendor/musa.h
index 4fd47def0b..2cfe0bae65 100644
--- a/mooncake-transfer-engine/include/gpu_vendor/musa.h
+++ b/mooncake-transfer-engine/include/gpu_vendor/musa.h
@@ -2,6 +2,7 @@
 
 #include <string>
 #include <musa.h>
+#include <musa_bf16.h>
 #include <musa_runtime.h>
 
 const static std::string GPU_PREFIX = "musa:";
@@ -60,6 +61,7 @@ const static std::string GPU_PREFIX = "musa:";
 #define CUDA_ERROR_NOT_SUPPORTED MUSA_ERROR_NOT_SUPPORTED
 #define cudaDeviceCanAccessPeer musaDeviceCanAccessPeer
 #define cudaDeviceEnablePeerAccess musaDeviceEnablePeerAccess
+#define cudaDeviceGetStreamPriorityRange musaDeviceGetStreamPriorityRange
 #define cudaDeviceGetPCIBusId musaDeviceGetPCIBusId
 #define cudaErrorPeerAccessAlreadyEnabled musaErrorPeerAccessAlreadyEnabled
 #define cudaError_t musaError_t
@@ -67,10 +69,14 @@ const static std::string GPU_PREFIX = "musa:";
 #define cudaFreeHost musaFreeHost
 #define cudaGetDevice musaGetDevice
 #define cudaGetDeviceCount musaGetDeviceCount
+#define cudaGetErrorName musaGetErrorName
 #define cudaGetErrorString musaGetErrorString
 #define cudaGetLastError musaGetLastError
 #define cudaHostAlloc musaHostAlloc
+#define cudaHostAllocDefault musaHostAllocDefault
 #define cudaHostAllocMapped musaHostAllocMapped
+#define cudaHostAllocPortable musaHostAllocPortable
+#define cudaHostAllocWriteCombined musaHostAllocWriteCombined
 #define cudaHostRegister musaHostRegister
 #define cudaHostRegisterPortable musaHostRegisterPortable
 #define cudaHostUnregister musaHostUnregister
@@ -97,6 +103,7 @@ const static std::string GPU_PREFIX = "musa:";
 #define cudaSetDevice musaSetDevice
 #define cudaStreamCreate musaStreamCreate
 #define cudaStreamCreateWithFlags musaStreamCreateWithFlags
+#define cudaStreamCreateWithPriority musaStreamCreateWithPriority
 #define cudaStreamNonBlocking musaStreamNonBlocking
 #define cudaStreamDestroy musaStreamDestroy
 #define cudaStreamPerThread musaStreamPerThread
@@ -122,6 +129,11 @@ const static std::string GPU_PREFIX = "musa:";
 #define cudaGetDeviceProperties musaGetDeviceProperties
 #define cudaMemcpyDeviceToDevice musaMemcpyDeviceToDevice
 #define cudaDevAttrClockRate musaDevAttrClockRate
+#define cudaDevAttrMultiProcessorCount musaDevAttrMultiProcessorCount
+#define cudaDevAttrMaxSharedMemoryPerBlockOptin \
+    musaDevAttrMaxSharedMemoryPerBlockOptin
+#define cudaEventCreate musaEventCreate
+#define cudaEventElapsedTime musaEventElapsedTime
 #define cudaLaunchConfig_t musaLaunchConfig_t
 #define cudaLaunchAttribute musaLaunchAttribute
 #define cudaLaunchAttributeCooperative musaLaunchAttributeCooperative
@@ -129,6 +141,9 @@ const static std::string GPU_PREFIX = "musa:";
 #define CUDA_R_16BF MUSA_R_16BF
 #define CUDA_R_32F MUSA_R_32F
 
+#define nv_bfloat16 __mt_bfloat16
+#define nv_bfloat162 __mt_bfloat162
+
 // IBGDA-specific mappings
 #define cuInit muInit
 #define cuDevicePrimaryCtxRetain muDevicePrimaryCtxRetain
diff --git a/mooncake-transfer-engine/include/multi_transport.h b/mooncake-transfer-engine/include/multi_transport.h
index 541a7391ea..03144d5c18 100644
--- a/mooncake-transfer-engine/include/multi_transport.h
+++ b/mooncake-transfer-engine/include/multi_transport.h
@@ -15,20 +15,28 @@
 #ifndef MULTI_TRANSPORT_H_
 #define MULTI_TRANSPORT_H_
 
+#include <functional>
 #include <unordered_map>
 
 #include "transport/transport.h"
 
 namespace mooncake {
+class TransferEngineImpl;
 class TransferEngineImplTestPeer;
+class MultiTransportTestPeer;
+class MultiTransportBatchTestPeer;
 
 class MultiTransport {
+    friend class TransferEngineImpl;
     friend class TransferEngineImplTestPeer;
+    friend class MultiTransportTestPeer;
+    friend class MultiTransportBatchTestPeer;
 
    public:
     using BatchID = Transport::BatchID;
     using TransferRequest = Transport::TransferRequest;
     using TransferStatus = Transport::TransferStatus;
+    using TransferStatusEnum = Transport::TransferStatusEnum;
     using BatchDesc = Transport::BatchDesc;
 
     MultiTransport(std::shared_ptr<TransferMetadata> metadata,
@@ -36,6 +44,11 @@ class MultiTransport {
 
     ~MultiTransport();
 
+    struct ScatterSubmission {
+        BatchID batch_id = static_cast<BatchID>(-1);
+        std::vector<size_t> task_sizes;
+    };
+
     BatchID allocateBatchID(size_t batch_size);
 
     Status freeBatchID(BatchID batch_id);
@@ -43,6 +56,9 @@ class MultiTransport {
     Status submitTransfer(BatchID batch_id,
                           const std::vector<TransferRequest> &entries);
 
+    Status submitScatter(const std::vector<TransferRequest> &entries,
+                         ScatterSubmission &submission);
+
 #ifdef ENABLE_MULTI_PROTOCOL
     Status mp_submitTransfer(BatchID batch_id,
                              const std::vector<TransferRequest> &entries,
@@ -52,6 +68,10 @@ class MultiTransport {
     Status getTransferStatus(BatchID batch_id, size_t task_id,
                              TransferStatus &status);
 
+    Status getScatterRequestStatuses(
+        BatchID batch_id, size_t task_id,
+        std::vector<TransferStatusEnum> &request_statuses);
+
     Status getBatchTransferStatus(BatchID batch_id, TransferStatus &status);
 
     Transport *installTransport(const std::string &proto,
@@ -60,10 +80,11 @@ class MultiTransport {
     Transport *getTransport(const std::string &proto);
 
     /**
-     * @brief Check if TCP is the only installed transport.
+     * @brief Check if TCP is the only installed host transport.
      *
-     * When only TCP transport is available (no RDMA, NVLink, etc.),
-     * local memcpy is preferred over TCP loopback for same-host transfers.
+     * When only TCP is available (no RDMA, NVLink, etc.), local memcpy is
+     * preferred over TCP loopback for same-host transfers. POSIX SHM is
+     * intra-node only and does not change this classification.
      */
     bool isTcpOnly() const;
 
@@ -72,7 +93,23 @@ class MultiTransport {
     void *getBaseAddr();
 
    private:
-    Status selectTransport(const TransferRequest &entry, Transport *&transport);
+    Status freeBatchID(BatchID batch_id,
+                       const std::function<void()> &before_delete);
+
+    Status submitTransfer(BatchID batch_id,
+                          const std::vector<TransferRequest> &entries,
+                          std::vector<size_t> *task_sizes);
+
+    Status selectTransports(const std::vector<TransferRequest> &entries,
+                            std::vector<Transport *> &transports);
+
+    // If `allows_reuse` is non-null it is written on every return. True means
+    // this segment's transport is a function of `target_id` only, so the
+    // caller may reuse the returned pointer for later requests with the same
+    // `target_id`. False for mixed-protocol segments (comma in `protocol`) and
+    // invalid IDs. Passing nullptr skips the flag.
+    Status selectTransport(const TransferRequest &entry, Transport *&transport,
+                           bool *allows_reuse = nullptr);
 
 #ifdef ENABLE_MULTI_PROTOCOL
     Status mp_selectTransport(const TransferRequest &entry,
diff --git a/mooncake-transfer-engine/include/multi_transport_locality.h b/mooncake-transfer-engine/include/multi_transport_locality.h
index c298b4a702..6b9fe91bdc 100644
--- a/mooncake-transfer-engine/include/multi_transport_locality.h
+++ b/mooncake-transfer-engine/include/multi_transport_locality.h
@@ -65,18 +65,27 @@ inline bool hostEquals(const std::string& a, const std::string& b) {
     return true;
 }
 
-// The device KV pool is registered under both rdma and hip in a "rdma,hip"
-// multi-protocol segment. hip transport uses GPU IPC, which only works between
-// processes on the same physical host, so a hip buffer is a valid transport for
-// a target only when that target lives on the same host as the initiator.
-// A cross-host target must fall back to rdma. Two engines co-located on one
-// host share the host portion of their segment name (they differ only in port).
-inline bool isHipReachableTarget(const std::string& target_segment_name,
-                                 const std::string& local_server_name) {
+// Same-host IPC transports (HIP/MUSA GPU IPC and POSIX SHM) only work between
+// processes on the same physical host. A cross-host target must fall back to
+// RDMA/TCP. Two engines co-located on one host share the host portion of their
+// segment name (they differ only in port).
+inline bool isLocalIpcReachableTarget(const std::string& target_segment_name,
+                                      const std::string& local_server_name) {
     return hostEquals(segmentHost(target_segment_name),
                       segmentHost(local_server_name));
 }
 
+inline bool isGpuIpcReachableTarget(const std::string& target_segment_name,
+                                    const std::string& local_server_name) {
+    return isLocalIpcReachableTarget(target_segment_name, local_server_name);
+}
+
+// Compatibility name retained for existing callers/tests.
+inline bool isHipReachableTarget(const std::string& target_segment_name,
+                                 const std::string& local_server_name) {
+    return isGpuIpcReachableTarget(target_segment_name, local_server_name);
+}
+
 }  // namespace mooncake
 
 #endif  // MULTI_TRANSPORT_LOCALITY_H
diff --git a/mooncake-transfer-engine/include/shared_segment/shared_segment.h b/mooncake-transfer-engine/include/shared_segment/shared_segment.h
new file mode 100644
index 0000000000..4f93ccdc4f
--- /dev/null
+++ b/mooncake-transfer-engine/include/shared_segment/shared_segment.h
@@ -0,0 +1,119 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#ifndef SHARED_SEGMENT_H
+#define SHARED_SEGMENT_H
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "common/base/status.h"
+
+namespace mooncake {
+
+// A shared segment is one contiguous span of host memory whose physical pages
+// exist exactly once, in the process of `owner_rank`, while every rank of the
+// group maps them at a rank-local address. It targets the write-once/read-many
+// KV offload pattern: sizes are known before the first allocation, nothing is
+// ever freed, and addresses must stay fixed so they can be captured in a graph.
+//
+// Virtual addresses are deliberately *not* required to match across ranks.
+// Peers agree on the byte layout instead, so a rank locates data as
+// `local_base + offset`. That keeps the reserved address space equal to the
+// segment size rather than size x world_size. Layout (which offset holds which
+// tensor) is the caller's responsibility; this class only shares the raw span.
+//
+// Creation is two-phase because the only communicator in reach belongs to the
+// framework (a torch process group in practice), and driving it from C++ would
+// mean calling back into Python:
+//
+//   1. Create  - reserve the local address window; the owner also allocates and
+//                exports the physical pages. Returns a fixed-length blob.
+//   2. Complete - after the caller all-gathers the blobs, verify every rank
+//                asked for the same thing and, on non-owners, map the owner's
+//                pages into the reserved window.
+//
+// Peers are trusted: the checks catch a group that was configured
+// inconsistently, not a peer that lies. The owner's segment must outlive every
+// other rank's, because freeing its pages invalidates their mappings.
+
+struct SharedSegmentOptions {
+    uint32_t world_size = 1;
+    uint32_t rank_id = 0;
+    uint32_t owner_rank = 0;
+    // Accelerator that is granted access to the host pages (D2H/H2D).
+    int32_t device_id = 0;
+    // true: unnamed memfd + mmap. Prefer THP (MADV_HUGEPAGE) so the kernel
+    // can back the span with 2MiB pages; 4KiB pages if THP cannot allocate.
+    // Does not use the HugeTLB pool. Ranks share the pages through the memfd.
+    // false: platform VMM with a fabric shareable handle.
+    bool mmap = true;
+    // When mmap is true: HostRegister the pages for device_id (Ascend).
+    // Needed for TE location=npu ROCE D2rH; off by default.
+    bool host_register = false;
+};
+
+class SharedSegmentBackend;
+
+class SharedSegment {
+   public:
+    ~SharedSegment();
+
+    SharedSegment(const SharedSegment&) = delete;
+    SharedSegment& operator=(const SharedSegment&) = delete;
+
+    // Phase one. On success `segment` owns the reservation (and, on the owner,
+    // the allocation) and `out_blob` is ready for the caller's all-gather.
+    static Status Create(const std::string& name, uint64_t size,
+                         const SharedSegmentOptions& options,
+                         std::shared_ptr<SharedSegment>& segment,
+                         std::string& out_blob);
+
+    // Whether this build can share memory across processes. mmap uses an
+    // anonymous memfd (always available). host_register additionally needs
+    // Ascend. VMM (mmap=false) needs a platform fabric backend.
+    static bool Supported(bool mmap = true, bool host_register = false);
+
+    // Phase two. `blobs` is indexed by rank. After success, `ready()` is true
+    // and `base_addr()` is valid.
+    Status Complete(const std::vector<std::string>& blobs);
+
+    bool ready() const { return ready_; }
+    uintptr_t base_addr() const { return base_addr_; }
+    uint64_t size() const { return size_; }
+
+    // Address the accelerator sees, when the backend had to map the pages for
+    // it separately (mmap plus HostRegister on Ascend). Zero when
+    // `base_addr()` is already device-accessible.
+    uintptr_t device_addr() const;
+
+   private:
+    SharedSegment(std::string name, uint64_t size,
+                  SharedSegmentOptions options);
+
+    std::string name_;
+    uint64_t size_ = 0;
+    SharedSegmentOptions options_;
+    uint64_t fingerprint_ = 0;
+    uint64_t alloc_size_ = 0;
+    uintptr_t base_addr_ = 0;
+    bool ready_ = false;
+    std::unique_ptr<SharedSegmentBackend> backend_;
+};
+
+}  // namespace mooncake
+
+#endif  // SHARED_SEGMENT_H
diff --git a/mooncake-transfer-engine/include/transfer_engine.h b/mooncake-transfer-engine/include/transfer_engine.h
index cfb06d3d22..16f2cb4b6b 100644
--- a/mooncake-transfer-engine/include/transfer_engine.h
+++ b/mooncake-transfer-engine/include/transfer_engine.h
@@ -33,6 +33,7 @@ namespace mooncake {
 class ShutdownToken;
 class TransferEngineImpl;
 namespace tent {
+class Config;
 class TransferEngine;
 };
 #if (defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_MACA)) && \
@@ -57,6 +58,12 @@ const static BatchID INVALID_BATCH_ID = UINT64_MAX;
 using BufferEntry = Transport::BufferEntry;
 using NicLoadStats = Transport::NicLoadStats;
 
+struct SegmentBufferInfo {
+    uint64_t addr;
+    uint64_t length;
+    std::string location;
+};
+
 enum class PeerLiveness : uint8_t {
     Alive = 0,
     Unreachable = 1,
@@ -104,6 +111,11 @@ class TransferEngine {
              const std::string& ip_or_host_name = "",
              uint64_t rpc_port = 12345);
 
+    int init(const std::string& metadata_conn_string,
+             const std::string& local_server_name,
+             const std::string& ip_or_host_name, uint64_t rpc_port,
+             const std::string& protocol);
+
     int freeEngine();
 
     Transport* installTransport(const std::string& proto, void** args);
@@ -118,6 +130,12 @@ class TransferEngine {
 
     SegmentHandle openSegment(const std::string& segment_name);
 
+    // Replace buffers with a snapshot of the segment's memory buffers.
+    // Return 0 on success (including an empty segment), or a negative ERR_*.
+    // On error, buffers is empty. Does not close the segment handle.
+    int getSegmentBuffers(SegmentHandle handle,
+                          std::vector<SegmentBufferInfo>& buffers);
+
     Status CheckSegmentStatus(SegmentID sid);
 
     int closeSegment(SegmentHandle handle);
@@ -129,6 +147,17 @@ class TransferEngine {
                             bool remote_accessible = true,
                             bool update_metadata = true);
 
+    // Allocate shared memory that ShmTransport can export to same-host peers.
+    // Requires ShmTransport (MC_FORCE_SHM=1 or installTransport("shm")).
+    // Caller must registerLocalMemory before remote access. Returns nullptr
+    // on failure. Default: POSIX /dev/shm. With
+    // SharedMemoryOptions.use_hugepage and hugepage_size 2MB/512MB/1GB:
+    // matching hugetlbfs (no silent tmpfs fallback).
+    void* allocateSharedMemory(size_t length);
+    void* allocateSharedMemory(size_t length, const SharedMemoryOptions& opt);
+
+    int freeSharedMemory(void* addr);
+
     int unregisterLocalMemory(void* addr, bool update_metadata = true);
 
     Status submitTransfer(BatchID batch_id,
@@ -160,6 +189,8 @@ class TransferEngine {
         ScatterTransferOperation& operator=(const ScatterTransferOperation&) =
             delete;
 
+        // Single-consumer operation: do not wait concurrently or from a
+        // fragment completion callback.
         Status wait();
 
         // A wait timeout does not cancel the transfer. Keep this operation and
@@ -212,6 +243,8 @@ class TransferEngine {
 
     int getNotifies(std::vector<TransferMetadata::NotifyDesc>& notifies);
 
+    // RDMA success means queued on the notification QP, not remote delivery.
+    // Completion errors are processed asynchronously; TCP fallback is sync.
     int sendNotifyByID(SegmentID target_id,
                        TransferMetadata::NotifyDesc notify_msg);
 
@@ -245,10 +278,11 @@ class TransferEngine {
 #endif
 
     /**
-     * @brief Check if TCP is the only installed transport.
+     * @brief Check if TCP is the only installed host transport.
      *
-     * When only TCP transport is available (no RDMA, NVLink, etc.),
-     * local memcpy is preferred over TCP loopback for same-host transfers.
+     * When only TCP is available (no RDMA, NVLink, etc.), local memcpy is
+     * preferred over TCP loopback for same-host transfers. POSIX SHM is
+     * intra-node only and does not change this classification.
      */
     bool isTcpOnly() const;
 
@@ -269,14 +303,27 @@ class TransferEngine {
 
     std::shared_ptr<Topology> getLocalTopology();
 
+    // String dump of the live local topology. Under TENT this is the native
+    // {"nics","mems"} JSON (with rank0/1/2). Under classic TE it is the
+    // priority-matrix JSON.
+    std::string getLocalTopologyString();
+
     void enableGracefulShutdown();
     std::string showLinks(bool json = false) const;
 
    private:
+    std::shared_ptr<mooncake::tent::Config> buildTentConfig(
+        const std::string& metadata_conn_string,
+        const std::string& local_server_name) const;
+
     std::shared_ptr<TransferEngineImpl> impl_;
     std::shared_ptr<mooncake::tent::TransferEngine> impl_tent_;
     std::shared_ptr<ShutdownToken> shutdown_token_;
+    // Classic callers provide this through TransferEngine(auto_discover,
+    // filter) before init() creates the native TENT engine.
+    std::vector<std::string> tent_device_filter_;
     bool use_tent_{false};
+    friend class TransferEngineImplTestPeer;
 };
 }  // namespace mooncake
 
diff --git a/mooncake-transfer-engine/include/transfer_engine_impl.h b/mooncake-transfer-engine/include/transfer_engine_impl.h
index 12c0bbf8de..696f6b6cac 100644
--- a/mooncake-transfer-engine/include/transfer_engine_impl.h
+++ b/mooncake-transfer-engine/include/transfer_engine_impl.h
@@ -33,6 +33,7 @@
 #include "transfer_metadata.h"
 #include "transfer_engine.h"
 #include "transport/transport.h"
+#include "config.h"
 #if (defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_MACA)) && \
     !defined(USE_CXI)
 #include "transport/device/device_transport.h"
@@ -141,6 +142,23 @@ class TransferEngineImpl {
         return s;
     }
 
+    Status submitScatter(const std::vector<TransferRequest>& entries,
+                         MultiTransport::ScatterSubmission& submission) {
+        Status s = multi_transports_->submitScatter(entries, submission);
+#ifdef WITH_METRICS
+        if (metrics_enabled_ && s.ok()) {
+            auto& batch = Transport::toBatchDesc(submission.batch_id);
+            auto now = std::chrono::steady_clock::now();
+            for (auto& task : batch.task_list) {
+                if (task.start_time.time_since_epoch().count() == 0) {
+                    task.start_time = now;
+                }
+            }
+        }
+#endif
+        return s;
+    }
+
     Status submitTransferWithNotify(BatchID batch_id,
                                     const std::vector<TransferRequest>& entries,
                                     TransferMetadata::NotifyDesc notify_msg) {
@@ -245,7 +263,12 @@ class TransferEngineImpl {
     }
 
     Status freeBatchID(BatchID batch_id) {
-        return multi_transports_->freeBatchID(batch_id);
+        return multi_transports_->freeBatchID(batch_id, [this, batch_id] {
+            // BatchID is pointer-derived. Remove side-table state before the
+            // descriptor is deleted and its address can be reused.
+            RWSpinlock::WriteGuard guard(send_notifies_lock_);
+            notifies_to_send_.erase(batch_id);
+        });
     }
 
     int getNotifies(std::vector<TransferMetadata::NotifyDesc>& notifies);
@@ -321,6 +344,13 @@ class TransferEngineImpl {
         return result;
     }
 
+    Status getScatterRequestStatuses(
+        BatchID batch_id, size_t task_id,
+        std::vector<TransferStatusEnum>& request_statuses) {
+        return multi_transports_->getScatterRequestStatuses(batch_id, task_id,
+                                                            request_statuses);
+    }
+
     Status getBatchTransferStatus(BatchID batch_id, TransferStatus& status,
                                   bool skip_metrics = false) {
         Status result =
@@ -334,16 +364,19 @@ class TransferEngineImpl {
         }
 #endif
         if (result.ok() && status.s == TransferStatusEnum::COMPLETED) {
-            // send notify
-            RWSpinlock::WriteGuard guard(send_notifies_lock_);
-            if (!notifies_to_send_.count(batch_id)) return result;
-            auto value = notifies_to_send_[batch_id];
-            auto rc = sendNotifyByID(value.first, value.second);
+            std::pair<SegmentID, TransferMetadata::NotifyDesc> value;
+            {
+                RWSpinlock::WriteGuard guard(send_notifies_lock_);
+                auto notify = notifies_to_send_.find(batch_id);
+                if (notify == notifies_to_send_.end()) return result;
+                value = std::move(notify->second);
+                notifies_to_send_.erase(notify);
+            }
+            auto rc = sendNotifyByID(value.first, std::move(value.second));
             if (rc) {
                 LOG(ERROR) << "Failed to send notify message, error code: "
                            << rc;
             }
-            notifies_to_send_.erase(batch_id);
         }
         return result;
     }
@@ -395,6 +428,11 @@ class TransferEngineImpl {
 
     void* getBaseAddr() { return multi_transports_->getBaseAddr(); }
 
+    void* allocateSharedMemory(size_t length);
+    void* allocateSharedMemory(size_t length, const SharedMemoryOptions& opt);
+
+    int freeSharedMemory(void* addr);
+
     void setWhitelistFilters(std::vector<std::string>&& filters) {
         filter_ = std::move(filters);
     }
@@ -452,6 +490,9 @@ class TransferEngineImpl {
         if (auto_discover_config_.protocol == "efa") {
             return "efa";
         }
+        if (globalConfig().use_rdma_twosided) {
+            return "rdma_twosided";
+        }
         return "rdma";
     }
 
diff --git a/mooncake-transfer-engine/include/transfer_metadata.h b/mooncake-transfer-engine/include/transfer_metadata.h
index 69ce49da5f..b049bfc292 100644
--- a/mooncake-transfer-engine/include/transfer_metadata.h
+++ b/mooncake-transfer-engine/include/transfer_metadata.h
@@ -33,6 +33,7 @@
 #include <thread>
 #include <unordered_map>
 
+#include "buffer_range_index.h"
 #include "common.h"
 #include "topology.h"
 
@@ -40,13 +41,25 @@ namespace mooncake {
 struct MetadataStoragePlugin;
 struct HandShakePlugin;
 
+// Result of a metadata-backend lookup, distinguishing an authoritative
+// key absence (kNotFound — the master removed the segment key on peer
+// unmount/expiry) from a transient backend failure (kUnavailable — curl
+// timeout, etcd blip, connection drop). syncSegmentCache() advances its
+// invalidation streak only for kNotFound so a metadata-service outage
+// cannot purge the live cache.
+enum class GetResult {
+    kFound,
+    kNotFound,
+    kUnavailable,
+};
+
 #define P2PHANDSHAKE "P2PHANDSHAKE"
 
 class TransferMetadata {
    public:
     struct DeviceDesc {
         std::string name;
-        uint16_t lid;
+        uint32_t lid;
         std::string gid;
         std::string eid;  // for ub
 
@@ -57,7 +70,7 @@ class TransferMetadata {
         std::string name;
         uint64_t addr;
         uint64_t length;
-        int32_t device_id = -1;  // CUDA device for NCCL buffers
+        int32_t device_id = -1;  // CUDA device (NCCL) or Ascend engine index
 #ifdef ENABLE_MULTI_PROTOCOL
         std::string protocol;  // for multi-protocol mode (cxl/tcp/rdma)
 #endif
@@ -69,10 +82,10 @@ class TransferMetadata {
 #else
         using mr_key_t = uint32_t;
 #endif
-        std::vector<mr_key_t> lkey;         // for rdma/efa
-        std::vector<mr_key_t> rkey;         // for rdma/efa
-        std::string shm_name;               // for nvlink and hip
-        uint64_t offset;                    // for cxl
+        std::vector<mr_key_t> lkey;  // for rdma/efa
+        std::vector<mr_key_t> rkey;  // for rdma/efa
+        std::string shm_name;  // nvlink/hip IPC blob, or POSIX shm object name
+        uint64_t offset;       // for cxl
         std::vector<std::string> tseg;      // for ub/urma
         std::vector<uint32_t> l_seg_index;  // for ub/urma
 
@@ -107,10 +120,17 @@ class TransferMetadata {
     struct SegmentDesc {
         std::string name;
         std::string protocol;
+        uint64_t metadata_version{0};
         // this is for rdma/shm/urma
         std::vector<DeviceDesc> devices;
         Topology topology;
         std::vector<BufferDesc> buffers;
+        // Derived from `buffers`. Rebuild after every mutation of that
+        // vector, before the descriptor is published through a shared_ptr.
+        // Copying a SegmentDesc copies this snapshot; a subsequent
+        // push_back/erase must call rebuildBufferRangeIndex() again.
+        BufferRangeIndex buffer_range_index;
+        void rebuildBufferRangeIndex() { buffer_range_index.rebuild(buffers); }
         // this is for nvmeof.
         std::vector<NVMeoFBufferDesc> nvmeof_buffers;
         // this is for cxl.
@@ -121,7 +141,12 @@ class TransferMetadata {
         // this is for ascend
         RankInfoDesc rank_info;
 
-        int tcp_data_port;
+        // TCP data-plane endpoint. Keeping the routable host beside the port
+        // makes one SegmentDesc an immutable endpoint snapshot for clients.
+        // Older descriptors may omit tcp_data_host; getSegmentDesc() fills it
+        // once from legacy RPC metadata before caching the descriptor.
+        std::string tcp_data_host;
+        int tcp_data_port{0};
         // TCP data-plane protocol version advertised by this segment's
         // server. v2 adds acknowledged WRITE framing and status-prefixed
         // READ responses (#2086); absent/1 = legacy unacknowledged framing.
@@ -150,6 +175,7 @@ class TransferMetadata {
     struct RpcMetaDesc {
         std::string ip_or_host_name;
         uint16_t rpc_port;
+        uint64_t metadata_version{0};
 #ifdef USE_BAREX
         uint16_t barex_port;
 #endif
@@ -159,7 +185,7 @@ class TransferMetadata {
     struct HandShakeDesc {
         std::string payload;  // opaque transport-specific handshake data
         std::string local_nic_path;
-        uint16_t local_lid = 0;
+        uint32_t local_lid = 0;
         std::string local_gid;
         std::string peer_nic_path;
 #ifdef USE_UB
@@ -173,6 +199,12 @@ class TransferMetadata {
         // Capability marker. Encoded only by transports that opt into
         // ready_ack; decoded from field presence to detect peer support.
         bool ready_ack_supported = false;
+        // Per-peer RDMA CtrlChannel (notify QP). 0 = not supported / unused.
+        // When ctrl_channel is true, this handshake only sets up the control
+        // path (qp_num may be empty).
+        uint32_t notify_qp_num = 0;
+        uint16_t notify_rq_depth = 0;
+        bool ctrl_channel = false;
         std::string reply_msg;  // on error
 #ifdef USE_EFA
         std::string efa_addr;  // EFA endpoint address (hex encoded)
@@ -192,6 +224,16 @@ class TransferMetadata {
 
     ~TransferMetadata();
 
+   protected:
+    // Test-only seam: inject a storage plugin directly, bypassing the
+    // conn-string plugin factory (which LOG(FATAL)s without a real
+    // etcd/redis/http backend) and the P2P handshake daemon. Derived
+    // hardware-free unit tests substitute an in-memory
+    // MetadataStoragePlugin to exercise syncSegmentCache without RDMA/CUDA.
+    explicit TransferMetadata(
+        std::shared_ptr<MetadataStoragePlugin> storage_plugin);
+
+   public:
     std::shared_ptr<SegmentDesc> getSegmentDescByName(
         const std::string &segment_name, bool force_update = false);
 
@@ -203,8 +245,11 @@ class TransferMetadata {
     int updateSegmentDesc(const std::string &segment_name,
                           const SegmentDesc &desc);
 
-    std::shared_ptr<SegmentDesc> getSegmentDesc(
-        const std::string &segment_name);
+    // Fetch a segment descriptor from the metadata backend. When |status|
+    // is non-null it receives the GetResult so the caller (syncSegmentCache)
+    // can distinguish an authoritative key removal from a transient outage.
+    std::shared_ptr<SegmentDesc> getSegmentDesc(const std::string &segment_name,
+                                                GetResult *status = nullptr);
 
     SegmentID getSegmentID(const std::string &segment_name);
 
@@ -215,6 +260,10 @@ class TransferMetadata {
     int addLocalMemoryBuffer(const BufferDesc &buffer_desc,
                              bool update_metadata);
 
+    // Removes the local descriptor entry before optional metadata publication.
+    // If publication fails, the local removal remains committed; a retry must
+    // publish the updated descriptor rather than remove the entry again.
+    // ERR_ADDRESS_NOT_REGISTERED means no matching local entry was present.
     int removeLocalMemoryBuffer(void *addr, bool update_metadata);
 
     int addLocalSegment(SegmentID segment_id, const std::string &segment_name,
@@ -231,6 +280,8 @@ class TransferMetadata {
 
     int getRpcMetaEntry(const std::string &server_name, RpcMetaDesc &desc);
     int getNotifies(std::vector<NotifyDesc> &notifies);
+    // Push a notify received from an alternate path (e.g. RDMA CtrlChannel).
+    void pushNotify(const NotifyDesc &notify);
 
     const RpcMetaDesc &localRpcMeta() const { return local_rpc_meta_; }
 
@@ -253,6 +304,13 @@ class TransferMetadata {
     void dumpMetadataContentUnlocked();
 
    private:
+    std::shared_ptr<SegmentDesc> getSegmentDescInternal(
+        const std::string &segment_name, bool force_rpc_update,
+        GetResult *status = nullptr);
+    int getRpcMetaEntryInternal(const std::string &server_name,
+                                RpcMetaDesc &desc, bool force_update);
+    int publishSegmentDesc(const std::string &segment_name,
+                           const SegmentDesc &desc);
     int encodeSegmentDesc(const SegmentDesc &desc, Json::Value &segmentJSON);
     std::shared_ptr<TransferMetadata::SegmentDesc> decodeSegmentDesc(
         Json::Value &segmentJSON, const std::string &segment_name);
@@ -274,6 +332,11 @@ class TransferMetadata {
     std::unordered_map<uint64_t, std::shared_ptr<SegmentDesc>>
         segment_id_to_desc_map_;
     std::unordered_map<std::string, uint64_t> segment_name_to_id_map_;
+    // Per-REMOTE-segment consecutive fetch-failure streak, guarded by
+    // segment_lock_. Bumped in syncSegmentCache's apply phase when a cached
+    // segment's backend fetch fails; reset to 0 on a successful fetch. Once it
+    // reaches kStaleSegmentFailureThreshold the cached entry is invalidated.
+    std::unordered_map<std::string, int> segment_failure_counts_;
 
     RWSpinlock notify_lock_;
     std::vector<NotifyDesc> notifys;
diff --git a/mooncake-transfer-engine/include/transfer_metadata_plugin.h b/mooncake-transfer-engine/include/transfer_metadata_plugin.h
index 997d46612c..dd87af766e 100644
--- a/mooncake-transfer-engine/include/transfer_metadata_plugin.h
+++ b/mooncake-transfer-engine/include/transfer_metadata_plugin.h
@@ -26,6 +26,19 @@ struct MetadataStoragePlugin {
     virtual ~MetadataStoragePlugin() {}
 
     virtual bool get(const std::string &key, Json::Value &value) = 0;
+    // Error-aware lookup: same contract as get() but reports whether a
+    // non-found result is an authoritative key absence (kNotFound) or a
+    // transient backend failure (kUnavailable). Plugins that can tell the
+    // two apart (etcd key-absent response, Redis nil reply, HTTP 404 vs 5xx)
+    // must override this; the default delegates to get() and maps any
+    // failure to kUnavailable. Failing closed is deliberate: a plugin that
+    // cannot distinguish absence from an outage must never report kNotFound,
+    // because syncSegmentCache() would then evict a still-live cache entry
+    // on a backend outage.
+    virtual GetResult getWithStatus(const std::string &key,
+                                    Json::Value &value) {
+        return get(key, value) ? GetResult::kFound : GetResult::kUnavailable;
+    }
     virtual bool set(const std::string &key, const Json::Value &value) = 0;
     virtual bool remove(const std::string &key) = 0;
 };
diff --git a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/adxl_compat.h b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/adxl_compat.h
index 1c40901bcc..cf70c629bd 100644
--- a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/adxl_compat.h
+++ b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/adxl_compat.h
@@ -18,6 +18,8 @@
 
 #include <graph/ascend_string.h>
 
+#include <acl/acl.h>
+
 #include <cstddef>
 #include <cstdint>
 #include <map>
@@ -75,90 +77,91 @@ enum FeatureType : int32_t {
     CLIENT_SERVER_COMM = 1,
 };
 
+using ShareableHandle = aclrtMemFabricHandle;
+
 class ASCEND_FUNC_VISIBILITY AdxlEngine {
    public:
     /**
-     * @brief 构造函数
+     * @brief Constructs an AdxlEngine instance.
      */
     AdxlEngine();
 
     /**
-     * @brief 析构函数
+     * @brief Destroys the AdxlEngine instance.
      */
     ~AdxlEngine();
 
     /**
-     * @brief 初始化AdxlEngine, 在调用其他接口前需要先调用该接口
-     * @param [in] local_engine
-     * AdxlEngine的唯一标识，如果是ipv4格式为host_ip:host_port或host_ip,
-     * 如果是ipv6格式为[host_ip]:host_port或[host_ip],
-     * 当设置host_port且host_port >
-     * 0时代表当前AdxlEngine作为server端，需要对配置端口进行监听
-     * @param [in] options 初始化所需的选项
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Initializes AdxlEngine before any other operation.
+     * @param [in] local_engine Unique engine identifier. IPv4 identifiers use
+     * host_ip or host_ip:host_port; IPv6 identifiers use [host_ip] or
+     * [host_ip]:host_port. A positive host_port makes this engine listen as a
+     * server.
+     * @param [in] options Initialization options.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status Initialize(const AscendString& local_engine,
                       const std::map<AscendString, AscendString>& options);
 
     /**
-     * @brief AdxlEngine资源清理函数
+     * @brief Releases resources owned by AdxlEngine.
      */
     void Finalize();
 
     /**
-     * @brief 注册内存
-     * @param [in] mem 需要注册的内存的描述信息
-     * @param [in] type 需要注册的内存的类型
-     * @param [out] mem_handle 注册成功返回的内存handle, 可用于内存解注册
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Registers memory with the engine.
+     * @param [in] mem Description of the memory to register.
+     * @param [in] type Type of the memory to register.
+     * @param [out] mem_handle Handle used to deregister the memory.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status RegisterMem(const MemDesc& mem, MemType type, MemHandle& mem_handle);
 
     /**
-     * @brief 解注册内存
-     * @param [in] mem_handle 注册内存返回的内存handle
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Deregisters memory from the engine.
+     * @param [in] mem_handle Handle returned by RegisterMem.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status DeregisterMem(MemHandle mem_handle);
 
     /**
-     * @brief 与远端AdxlEngine进行建链
-     * @param [in] remote_engine 远端AdxlEngine的唯一标识
-     * @param [in] timeout_in_millis 建链的超时时间，单位ms
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Connects to a remote AdxlEngine.
+     * @param [in] remote_engine Unique identifier of the remote engine.
+     * @param [in] timeout_in_millis Connection timeout in milliseconds.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status Connect(const AscendString& remote_engine,
                    int32_t timeout_in_millis = 1000);
 
     /**
-     * @brief 与远端AdxlEngine进行断链
-     * @param [in] remote_engine 远端AdxlEngine的唯一标识
-     * @param [in] timeout_in_millis 断链的超时时间，单位ms
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Disconnects from a remote AdxlEngine.
+     * @param [in] remote_engine Unique identifier of the remote engine.
+     * @param [in] timeout_in_millis Disconnection timeout in milliseconds.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status Disconnect(const AscendString& remote_engine,
                       int32_t timeout_in_millis = 1000);
 
     /**
-     * @brief 与远端AdxlEngine进行内存传输
-     * @param [in] remote_engine 远端AdxlEngine的唯一标识
-     * @param [in] operation 将远端内存读到本地或者将本地内存写到远端
-     * @param [in] op_descs 批量操作的本地以及远端地址
-     * @param [in] timeout_in_millis 断链的超时时间，单位ms
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Transfers memory synchronously with a remote AdxlEngine.
+     * @param [in] remote_engine Unique identifier of the remote engine.
+     * @param [in] operation Reads remote memory or writes local memory.
+     * @param [in] op_descs Local and remote addresses for the batch.
+     * @param [in] timeout_in_millis Transfer timeout in milliseconds.
+     * @return SUCCESS on success, or another status on failure.
      */
     Status TransferSync(const AscendString& remote_engine, TransferOp operation,
                         const std::vector<TransferOpDesc>& op_descs,
                         int32_t timeout_in_millis = 1000);
 
     /**
-     * @brief 批量异步传输，下发传输请求
-     * @param [in] remote_engine 远端Hixl的唯一标识
-     * @param [in] operation 将远端内存读到本地或者将本地内存写到远端
-     * @param [in] op_descs 批量操作的本地以及远端地址
-     * @param [in] optional_args 可选参数，预留
-     * @param [out] req 请求的handle，用于查询请求状态
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Submits a batch of asynchronous transfers.
+     * @param [in] remote_engine Unique identifier of the remote engine.
+     * @param [in] operation Reads remote memory or writes local memory.
+     * @param [in] op_descs Local and remote addresses for the batch.
+     * @param [in] optional_args Reserved optional arguments.
+     * @param [out] req Request handle used to query transfer status.
+     * @return SUCCESS on success, or another status on failure.
      */
     __attribute__((weak)) Status
     TransferAsync(const AscendString& remote_engine, TransferOp operation,
@@ -166,36 +169,52 @@ class ASCEND_FUNC_VISIBILITY AdxlEngine {
                   const TransferArgs& optional_args, TransferReq& req);
 
     /**
-     * @brief 获取请求状态
-     * @param [in] req 请求handle，由TransferAsync API调用产生
-     * @param [out] status 传输状态
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Gets the status of an asynchronous transfer request.
+     * @param [in] req Request handle returned by TransferAsync.
+     * @param [out] status Current transfer status.
+     * @return SUCCESS on success, or another status on failure.
      */
     __attribute__((weak)) Status GetTransferStatus(const TransferReq& req,
                                                    TransferStatus& status);
 
     /**
-     * @brief 使用acl VMM机制申请内存
-     * @param [in] type 内存类型
-     * @param [in] size 内存大小
-     * @param [out] ptr 申请的虚拟内存ptr
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Allocates memory through ACL virtual memory management.
+     * @param [in] type Type of memory to allocate.
+     * @param [in] size Allocation size in bytes.
+     * @param [out] ptr Virtual address of the allocation.
+     * @return SUCCESS on success, or another status on failure.
      */
     __attribute__((weak)) static Status MallocMem(MemType type, size_t size,
                                                   void** ptr);
 
     /**
-     * @brief 释放MallocMem申请的内存内存
-     * @param [in] ptr 释放的虚拟内存ptr
-     * @return 成功:SUCCESS, 失败:其它.
+     * @brief Exports memory allocated by MallocMem as a fabric shareable
+     * handle.
+     *
+     * Each allocation is exported through ACL at most once. The first call
+     * exports and caches the handle; subsequent calls return the cached handle.
+     *
+     * @param [in] addr Virtual address returned by MallocMem.
+     * @param [out] handle Exported fabric shareable handle.
+     * @return SUCCESS on success, PARAM_INVALID if addr was not returned by
+     * MallocMem or has already been freed, and another error status otherwise.
+     */
+    __attribute__((weak)) static Status ExportToShareableHandle(
+        void* addr, ShareableHandle& handle);
+
+    /**
+     * @brief Frees memory allocated by MallocMem.
+     * @param [in] ptr Virtual address returned by MallocMem.
+     * @return SUCCESS on success, or another status on failure.
      */
     __attribute__((weak)) static Status FreeMem(void* ptr);
 
     /**
-     * @brief 查询库能力特性
-     * @param [in] feature_type 特性类型
-     * @param [out] value 1=支持，0=不支持
-     * @return 成功:SUCCESS；未知特性:UNSUPPORTED；参数非法:PARAM_INVALID
+     * @brief Queries a library capability.
+     * @param [in] feature_type Capability to query.
+     * @param [out] value 1 when supported, or 0 when unsupported.
+     * @return SUCCESS on success, UNSUPPORTED for an unknown capability, or
+     * PARAM_INVALID for an invalid argument.
      */
     __attribute__((weak)) static Status GetCapability(FeatureType feature_type,
                                                       int32_t& value);
diff --git a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/local_copy_engine.h b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/local_copy_engine.h
index f7e77f2c36..928fdc19ee 100644
--- a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/local_copy_engine.h
+++ b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/local_copy_engine.h
@@ -16,6 +16,8 @@
 #ifndef LOCAL_COPY_ENGINE_H
 #define LOCAL_COPY_ENGINE_H
 
+#include <mutex>
+#include <unordered_map>
 #include <vector>
 
 #include <acl/acl.h>
@@ -35,8 +37,8 @@ class LocalCopyEngine {
 
     ~LocalCopyEngine();
 
-    // Initialize the local copy engine. Creates and owns its own ACL stream
-    // for async operations internally.
+    // Initialize the local copy engine. Streams are created lazily per device
+    // under that device's current ACL context (not at Initialize time).
     // transfer_timeout: timeout in milliseconds for sync operations
     // Returns 0 on success, non-zero on failure
     int Initialize(int32_t transfer_timeout);
@@ -76,8 +78,25 @@ class LocalCopyEngine {
                                          aclrtPtrAttributes &src_attrs,
                                          aclrtPtrAttributes &dst_attrs);
 
+    // Return (or lazily create) a stream belonging to the current ACL device
+    // context. The stream must be created while that device's context is
+    // current so aclrtMemcpyAsync does not return 107003.
+    aclrtStream GetOrCreateStreamForCurrentDevice();
+
    private:
-    aclrtStream stream_;
+    // Stream plus the ACL context it was created under. Destroying a stream
+    // requires that same context to be current, otherwise aclrtDestroyStream
+    // can return 107003 (ACL_ERROR_RT_STREAM_CONTEXT).
+    struct DeviceStream {
+        aclrtStream stream = nullptr;
+        aclrtContext context = nullptr;
+    };
+
+    // Per-device streams keyed by ACL device id. A single shared stream is
+    // unsafe across devices because Initialize() may run under device0
+    // context while workers later copy under other device contexts.
+    std::unordered_map<int32_t, DeviceStream> streams_;
+    mutable std::mutex streams_mu_;
     int32_t transfer_timeout_;
     bool initialized_;
 };
diff --git a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.h b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.h
index e07e97162e..d28cbe7613 100644
--- a/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.h
+++ b/mooncake-transfer-engine/include/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.h
@@ -60,6 +60,7 @@ class TransferExecutorBase {
         bool agent_mode = false;
         bool roce_mode = false;
         bool use_fabric_mem = false;
+        bool client_server_mode = false;
     };
 
     explicit TransferExecutorBase(const InitParams& params);
@@ -78,7 +79,7 @@ class TransferExecutorBase {
     void processSliceList(const std::vector<Transport::Slice*>& slice_list);
 
     int registerMem(void* addr, size_t length, adxl::MemType mem_type,
-                    bool use_buffer_pool, bool roce_mode, bool agent_mode);
+                    bool use_buffer_pool);
     int deregisterMem(void* addr);
 
     const size_t getNumEngines() const { return adxl_engines_.size(); }
@@ -104,7 +105,9 @@ class TransferExecutorBase {
                    int32_t timeout_in_millis);
     std::string resolveTargetAdxlEngineName(
         const std::shared_ptr<TransferMetadata::SegmentDesc>& segment_desc,
-        size_t engine_idx) const;
+        uint64_t dest_addr) const;
+    void processHomogeneousSliceList(
+        const std::vector<Transport::Slice*>& slice_list);
 
     InitParams params_;
     std::unique_ptr<LocalCopyEngine> local_copy_engine_;
diff --git a/mooncake-transfer-engine/include/transport/batch_registration.h b/mooncake-transfer-engine/include/transport/batch_registration.h
new file mode 100644
index 0000000000..a1736ccb07
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/batch_registration.h
@@ -0,0 +1,63 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#pragma once
+
+#include <algorithm>
+#include <atomic>
+#include <cstddef>
+#include <limits>
+#include <thread>
+#include <vector>
+
+#include "config.h"
+
+namespace mooncake {
+
+inline size_t maxConcurrentRegMr() {
+    size_t configured = globalConfig().max_concurrent_reg_mr;
+    return configured > 0 ? configured : std::numeric_limits<size_t>::max();
+}
+
+// Run every item while bounding thread creation when
+// MC_MAX_CONCURRENT_REG_MR is configured. With the default value, this keeps
+// the historical one-worker-per-buffer behavior.
+template <typename Function>
+int runBoundedRegMrBatch(size_t count, Function &&function) {
+    if (count == 0) return 0;
+
+    const size_t workers = std::min(count, maxConcurrentRegMr());
+    std::atomic<size_t> next{0};
+    std::atomic<int> first_error{0};
+
+    auto worker = [&]() {
+        for (size_t i = next.fetch_add(1); i < count; i = next.fetch_add(1)) {
+            int ret = function(i);
+            if (ret) {
+                int expected = 0;
+                first_error.compare_exchange_strong(expected, ret);
+            }
+        }
+    };
+
+    std::vector<std::thread> threads;
+    threads.reserve(workers - 1);
+    for (size_t i = 1; i < workers; ++i) threads.emplace_back(worker);
+    worker();
+    for (auto &thread : threads) thread.join();
+
+    return first_error.load();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/include/transport/device/comm_device.cuh b/mooncake-transfer-engine/include/transport/device/comm_device.cuh
index a3be4bd619..3771013db5 100644
--- a/mooncake-transfer-engine/include/transport/device/comm_device.cuh
+++ b/mooncake-transfer-engine/include/transport/device/comm_device.cuh
@@ -23,7 +23,7 @@ struct CommCtx {
 };
 
 // Construct CommCtx from the raw kernel arguments.
-// raddrs/rkeys/qp_devctxs may be nullptr on MUSA (ignored).
+// RDMA tables may be nullptr when only the P2P path is used.
 __device__ __forceinline__ CommCtx make_comm_ctx(
     void* gdr_buffer, const int32_t* nvlink_available,
     void* const* ipc_peer_ptrs, void* raddrs, void* rkeys, void* qp_devctxs,
@@ -36,11 +36,7 @@ __device__ __forceinline__ CommCtx make_comm_ctx(
     ctx.p2p.peer_ptrs = ipc_peer_ptrs;
     ctx.p2p.local_base = gdr_buffer;
 
-#ifdef MOONCAKE_EP_USE_MACA
-    ctx.ibgda.qp_devctxs = qp_devctxs;
-#else
     ctx.ibgda.qp_devctxs = reinterpret_cast<mlx5gda_qp_devctx*>(qp_devctxs);
-#endif
     ctx.ibgda.raddrs = reinterpret_cast<const uint64_t*>(raddrs);
     ctx.ibgda.rkeys = reinterpret_cast<const uint32_t*>(rkeys);
     ctx.ibgda.local_atomic_base = rdma_send_signal_buffer;
diff --git a/mooncake-transfer-engine/include/transport/device/ibgda/mlx5gda.h b/mooncake-transfer-engine/include/transport/device/ibgda/mlx5gda.h
index 24154e6bf1..6fa7b5c887 100644
--- a/mooncake-transfer-engine/include/transport/device/ibgda/mlx5gda.h
+++ b/mooncake-transfer-engine/include/transport/device/ibgda/mlx5gda.h
@@ -3,12 +3,7 @@
 
 #include <stddef.h>
 #include <stdint.h>
-#ifdef USE_MUSA
-#include <musa_runtime.h>
-#define cudaStream_t musaStream_t
-#else
-#include <cuda_runtime.h>
-#endif
+#include "cuda_alike.h"
 #include <infiniband/verbs.h>
 #include <infiniband/mlx5dv.h>
 
@@ -40,6 +35,13 @@ struct mlx5gda_control_region_allocator {
     void (*release)(void *context, struct mlx5gda_control_region *region);
 };
 
+struct mlx5gda_control_buffer {
+    void *addr;
+    void *dev_addr;
+    struct mlx5dv_devx_umem *umem;
+    struct memheap *heap;
+};
+
 struct mlx5gda_rdma_write_wqe {
     struct mlx5_wqe_ctrl_seg ctrl;
     struct mlx5_wqe_raddr_seg raddr;
@@ -58,6 +60,9 @@ struct mlx5gda_cq {
     struct mlx5dv_devx_uar *uar;  // uar is allocated but not used
     uint32_t cqn;
     uint32_t cqe;
+    void *dev_base;
+    void *dev_cq_buf;
+    struct memheap *heap;
     size_t cq_offset;
     size_t dbr_offset;
     void *cq_buf;
@@ -70,9 +75,10 @@ struct mlx5gda_cq {
 struct mlx5gda_cq *mlx5gda_create_cq(
     void *ctrl_buf, struct mlx5dv_devx_umem *ctrl_buf_umem,
     struct memheap *ctrl_buf_heap, struct ibv_pd *pd, int num_cqe,
-    cudaStream_t stream,
-    const struct mlx5gda_control_region_allocator *region_allocator);
-void mlx5gda_destroy_cq(struct memheap *ctrl_buf_heap, struct mlx5gda_cq *cq);
+    cudaStream_t stream, void *cq_buf, void *cq_buf_dev,
+    struct mlx5dv_devx_umem *cq_buf_umem, struct memheap *cq_buf_heap,
+    const struct mlx5gda_control_region_allocator *cq_region_allocator);
+void mlx5gda_destroy_cq(struct mlx5gda_cq *cq);
 
 static const size_t MLX5GDA_BF_SIZE = 256;
 
@@ -80,6 +86,9 @@ struct mlx5gda_qp {
     struct mlx5dv_devx_obj *mqp;
     struct mlx5gda_cq *send_cq;
     struct mlx5dv_devx_uar *uar;
+    void *bf_host_base;
+    char *bf_device_addr;
+    bool bf_host_registration_owner;
 
     uint8_t port_num;
     struct ibv_port_attr port_attr;
@@ -90,8 +99,11 @@ struct mlx5gda_qp {
     uint32_t num_wqebb;
     size_t wq_offset;
     size_t dbr_offset;
+    struct memheap *wq_heap;
     void *wq;
     void *dbr;
+    void *dev_wq;
+    void *dev_dbr;
     struct mlx5gda_control_region wq_region;
     struct mlx5gda_control_region dbr_region;
     struct mlx5gda_control_region_allocator region_allocator;
@@ -121,11 +133,12 @@ void mlx5gda_reset_create_qp_failure();
 mlx5gda_create_qp_failure mlx5gda_last_create_qp_failure();
 
 struct mlx5gda_qp *mlx5gda_create_rc_qp(
-    struct mlx5dv_pd mpd, void *ctrl_buf,
-    struct mlx5dv_devx_umem *ctrl_buf_umem, struct memheap *ctrl_buf_heap,
-    struct ibv_pd *pd, int wqe, uint8_t port_num, cudaStream_t stream,
-    const struct mlx5gda_control_region_allocator *region_allocator);
-void mlx5gda_destroy_qp(struct memheap *ctrl_buf_heap, struct mlx5gda_qp *qp);
+    struct mlx5dv_pd mpd, const struct mlx5gda_control_buffer *ctrl,
+    const struct mlx5gda_control_buffer *cq, struct ibv_pd *pd, int wqe,
+    uint8_t port_num, cudaStream_t stream,
+    const struct mlx5gda_control_region_allocator *cq_region_allocator,
+    const struct mlx5gda_control_region_allocator *qp_region_allocator);
+void mlx5gda_destroy_qp(struct mlx5gda_qp *qp);
 
 int mlx5gda_modify_rc_qp_rst2init(struct mlx5gda_qp *qp, uint16_t pkey_index);
 int mlx5gda_modify_rc_qp_init2rtr(struct mlx5gda_qp *qp,
diff --git a/mooncake-transfer-engine/include/transport/device/ibgda/os.h b/mooncake-transfer-engine/include/transport/device/ibgda/os.h
index bf8bfd4b5c..4cfbd64276 100644
--- a/mooncake-transfer-engine/include/transport/device/ibgda/os.h
+++ b/mooncake-transfer-engine/include/transport/device/ibgda/os.h
@@ -20,7 +20,7 @@ static inline int close_ret(int fd) {
 static inline ssize_t read_all(int fd, void *buf, size_t len) {
     size_t total = 0;
     while (total < len) {
-        ssize_t n = read(fd, buf + total, len - total);
+        ssize_t n = read(fd, static_cast<char *>(buf) + total, len - total);
         if (n == -1) {
             return -1;
         }
@@ -35,7 +35,8 @@ static inline ssize_t read_all(int fd, void *buf, size_t len) {
 static inline ssize_t write_all(int fd, const void *buf, size_t len) {
     size_t total = 0;
     while (total < len) {
-        ssize_t n = write(fd, buf + total, len - total);
+        ssize_t n =
+            write(fd, static_cast<const char *>(buf) + total, len - total);
         if (n == -1) {
             return -1;
         }
diff --git a/mooncake-transfer-engine/include/transport/device/ibgda_device.cuh b/mooncake-transfer-engine/include/transport/device/ibgda_device.cuh
index 2376f3b42e..91923b5169 100644
--- a/mooncake-transfer-engine/include/transport/device/ibgda_device.cuh
+++ b/mooncake-transfer-engine/include/transport/device/ibgda_device.cuh
@@ -3,41 +3,14 @@
 // Wraps mlx5gda_qp_devctx and issues RDMA writes/atomics via
 // device-side WQE construction.
 //
-// On MUSA: BF (Blue Flame) doorbell is not available (musaHostRegisterIoMemory
-// doesn't support MMIO), so qp->bf is NULL and the kernel uses DBR-only mode.
-// All other IBGDA logic (WQE construction, CQ polling, DBR write) is shared.
+// WQE construction and CQ polling are shared across CUDA, MUSA and MACA.
+// Platform memory operations publish the DBR and mapped BF doorbell.
 #pragma once
 
 #include <cstdint>
 #include "transport/device/device_ops.cuh"
 
-#ifdef MOONCAKE_EP_USE_MACA
-
-namespace mooncake {
-namespace device {
-
-struct IbgdaContext {
-    void* qp_devctxs;
-    const uint64_t* raddrs;
-    const uint32_t* rkeys;
-    const void* local_atomic_base;
-    const void* remote_atomic_base;
-};
-
-__device__ __forceinline__ void mc_ibgda_put(const IbgdaContext&, int, int, int,
-                                             int, const void*, uint64_t,
-                                             uint32_t) {}
-
-__device__ __forceinline__ void mc_ibgda_red_add(const IbgdaContext&, int, int,
-                                                 int, int, uint64_t, uint64_t,
-                                                 int32_t) {}
-
-}  // namespace device
-}  // namespace mooncake
-
-#else  // !MOONCAKE_EP_USE_MACA
-
-#ifndef MOONCAKE_EP_USE_MUSA
+#if !defined(MOONCAKE_EP_USE_MUSA) && !defined(MOONCAKE_EP_USE_MACA)
 #include <cuda/atomic>
 #endif
 #include <transport/device/ibgda/mlx5gda.h>
@@ -76,7 +49,7 @@ __device__ __forceinline__ mlx5gda_qp_devctx* mc_ibgda_channel(
 }
 
 __device__ __forceinline__ void mc_ibgda_lock(mlx5gda_qp_devctx* qp) {
-#ifdef MOONCAKE_EP_USE_MUSA
+#if defined(MOONCAKE_EP_USE_MUSA) || defined(MOONCAKE_EP_USE_MACA)
     uint32_t old;
     do {
         old = atomicCAS(&qp->mutex, 0u, 1u);
@@ -88,7 +61,7 @@ __device__ __forceinline__ void mc_ibgda_lock(mlx5gda_qp_devctx* qp) {
 }
 
 __device__ __forceinline__ void mc_ibgda_unlock(mlx5gda_qp_devctx* qp) {
-#ifdef MOONCAKE_EP_USE_MUSA
+#if defined(MOONCAKE_EP_USE_MUSA) || defined(MOONCAKE_EP_USE_MACA)
     mc_st_release_u32(&qp->mutex, 0u);
 #else
     cuda::atomic_ref<uint32_t, cuda::thread_scope_system> lock(qp->mutex);
@@ -104,8 +77,8 @@ __device__ __forceinline__ void mc_ibgda_poll_cq(mlx5gda_qp_devctx* qp,
             *reinterpret_cast<volatile uint16_t*>(&qp->cq->wqe_counter);
         uint8_t opcode = qp->cq->op_own >> 4;
         if (opcode == 0xD)
-            printf("[EP IBGDA] Requester error: syndrome=0x%lx\n",
-                   qp->cq->timestamp >> 56);
+            printf("[EP IBGDA] Requester error: syndrome=0x%llx\n",
+                   static_cast<unsigned long long>(qp->cq->timestamp >> 56));
         if (!(opcode == 0x0 || opcode == 0xF)) {
             printf("[EP IBGDA] Unexpected CQE opcode=0x%x, trapping\n", opcode);
             __trap();
@@ -118,16 +91,41 @@ __device__ __forceinline__ void mc_ibgda_poll_cq(mlx5gda_qp_devctx* qp,
 __device__ __forceinline__ void mc_ibgda_post_send_db(mlx5gda_qp_devctx* qp) {
     uint32_t num_posted = static_cast<uint32_t>(qp->wq_head);
     // DBR write — always done (NIC polls doorbell record in GPU memory)
+#if defined(MOONCAKE_EP_USE_MUSA) && __MUSA_ARCH__ == 310
+    // Match mtshmem's IBGDA publish sequence. The bypass atomic exchange makes
+    // the GPU-memory doorbell record visible to the NIC rather than retaining
+    // the write in the GPU cache hierarchy.
+    const uint32_t dbr_value = mc_bswap32(num_posted);
+    __threadfence_system_noflush();
+    asm volatile("LSU.ATOM_32.XCHG %0, %1, slc=byp;"
+                 :
+                 : "R"(reinterpret_cast<uint32_t*>(&qp->dbr->send_counter)),
+                   "R"(dbr_value));
+#else
     mc_st_release_u32(reinterpret_cast<uint32_t*>(&qp->dbr->send_counter),
                       mc_bswap32(num_posted));
+#endif
     // BF (Blue Flame) doorbell — only if BF register is mapped into GPU VA.
-    // On MUSA, musaHostRegisterIoMemory fails for MMIO addresses, so bf is
-    // NULL and we rely on DBR-only mode (slightly higher latency).
     if (qp->bf != nullptr) {
+#if defined(MOONCAKE_EP_USE_MUSA) && __MUSA_ARCH__ == 310
+        struct {
+            __be32 opmod_idx_opcode;
+            __be32 qpn_ds;
+        } doorbell{
+            mc_bswap32(num_posted << 8),
+            mc_bswap32(qp->qpn << 8),
+        };
+        __threadfence_system_noflush();
+        asm volatile("LSU.ATOM_64.XCHG %0, %1, slc=byp;"
+                     :
+                     : "R"(reinterpret_cast<uint64_t*>(qp->bf)),
+                       "R"(*reinterpret_cast<uint64_t*>(&doorbell)));
+#else
         auto* last_wqe = qp->wq + ((num_posted - 1) & qp->wqeid_mask);
         mc_st_release_u64(reinterpret_cast<uint64_t*>(qp->bf + qp->bf_offset),
                           *reinterpret_cast<uint64_t*>(last_wqe));
         qp->bf_offset ^= MLX5GDA_BF_SIZE;
+#endif
     }
 }
 
@@ -230,5 +228,3 @@ __device__ __forceinline__ void mc_ibgda_red_add(
 
 }  // namespace device
 }  // namespace mooncake
-
-#endif  // MOONCAKE_EP_USE_MACA
diff --git a/mooncake-transfer-engine/include/transport/device/nccl_device.cuh b/mooncake-transfer-engine/include/transport/device/nccl_device.cuh
index ce84adba15..74315b28bd 100644
--- a/mooncake-transfer-engine/include/transport/device/nccl_device.cuh
+++ b/mooncake-transfer-engine/include/transport/device/nccl_device.cuh
@@ -23,6 +23,7 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <type_traits>
 
 #include "transport/device/nccl_device_transport.h"
 
@@ -38,12 +39,33 @@
 
 namespace mooncake {
 namespace device {
+
+enum class NcclGinTeam : uint8_t {
+    kWorld = 0,
+    kRail,
+};
+
+// Values intentionally match Mooncake EP's backend-neutral sharing-mode
+// contract, not NCCL's enum values. Keep this to the GPU and CTA modes that
+// exist in every supported NCCL release; EP does not require thread mode.
+enum class NcclGinResourceSharing : uint8_t {
+    kCta = 0,
+    kGpu = 1,
+};
+
 namespace detail {
 
 struct NcclDeviceContextAccess {
     __device__ __forceinline__ static const ncclDevComm_t& comm(
         const NcclDeviceContext& ctx) {
-        return *static_cast<const ncclDevComm_t*>(ctx.native_comm_);
+        static_assert(
+            sizeof(ncclDevComm_t) <= NcclDeviceContext::kNativeCommCapacity,
+            "Increase NcclDeviceContext communicator capacity");
+        static_assert(
+            alignof(ncclDevComm_t) <= NcclDeviceContext::kNativeCommAlignment,
+            "Increase NcclDeviceContext communicator alignment");
+        return *reinterpret_cast<const ncclDevComm_t*>(
+            ctx.native_comm_storage_);
     }
 
     __device__ __forceinline__ static ncclWindow_t window(
@@ -71,6 +93,11 @@ struct NcclDeviceContextAccess {
         return ctx.gin_enabled_;
     }
 
+    __device__ __forceinline__ static bool ginConnectionsRailed(
+        const NcclDeviceContext& ctx) {
+        return ctx.gin_connections_railed_;
+    }
+
     __device__ __forceinline__ static bool lsaMultimemEnabled(
         const NcclDeviceContext& ctx) {
         return ctx.lsa_multimem_enabled_;
@@ -89,6 +116,34 @@ __device__ __forceinline__ int mc_nccl_gin_context(const NcclDeviceContext& ctx,
     return static_cast<int>(channel % static_cast<unsigned int>(count));
 }
 
+template <NcclGinTeam Team>
+__device__ __forceinline__ ncclTeam
+mc_nccl_gin_team(const ncclDevComm_t& comm) {
+    if constexpr (Team == NcclGinTeam::kRail) {
+        return ncclTeamRail(comm);
+    } else {
+        return ncclTeamWorld(comm);
+    }
+}
+
+__device__ __forceinline__ ncclGinResourceSharingMode
+mc_nccl_gin_sharing_mode(NcclGinResourceSharing mode) {
+    switch (mode) {
+        case NcclGinResourceSharing::kCta:
+            return NCCL_GIN_RESOURCE_SHARING_CTA;
+        case NcclGinResourceSharing::kGpu:
+        default:
+            return NCCL_GIN_RESOURCE_SHARING_GPU;
+    }
+}
+
+#if NCCL_VERSION_CODE >= NCCL_VERSION(2, 30, 5)
+using NcclStrongVaSignalAdd = ncclGin_StrongVASignalAdd;
+#else
+// NCCL 2.30.4 exposes only the legacy spelling, whose semantics are strong.
+using NcclStrongVaSignalAdd = ncclGin_VASignalAdd;
+#endif
+
 }  // namespace detail
 
 // Device operations in this header are intentionally unchecked, matching the
@@ -98,6 +153,154 @@ __device__ __forceinline__ int mc_nccl_gin_context(const NcclDeviceContext& ctx,
 // precondition is undefined behavior. Hoist capability and route queries out of
 // hot loops when the route is already known.
 
+// Pre-bound GIN state for hot device loops. Construct this once per issuing
+// thread/warp and reuse it for every operation on the same logical channel.
+// Unlike the lane-selected compatibility helpers below, these methods do not
+// check a lane id: the caller must elect exactly the threads required by the
+// selected NCCL cooperative operation.
+class NcclGinHandle {
+   public:
+    __device__ __forceinline__
+    NcclGinHandle(const NcclDeviceContext& ctx, unsigned int channel,
+                  NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu)
+        : comm_(detail::NcclDeviceContextAccess::comm(ctx)),
+          gin_(comm_, detail::mc_nccl_gin_context(ctx, channel),
+               detail::mc_nccl_gin_sharing_mode(sharing)),
+          window_(detail::NcclDeviceContextAccess::window(ctx)),
+          local_base_(detail::NcclDeviceContextAccess::localBase(ctx)),
+          team_world_(ncclTeamWorld(comm_)),
+          team_lsa_(ncclTeamLsa(comm_)),
+          team_rail_(ncclTeamRail(comm_)) {}
+
+    __device__ __forceinline__ int worldRank() const {
+        return team_world_.rank;
+    }
+
+    __device__ __forceinline__ int lsaRank() const { return team_lsa_.rank; }
+
+    __device__ __forceinline__ int railRank() const { return team_rail_.rank; }
+
+    __device__ __forceinline__ bool worldRankInLsa(int peer) const {
+        const int first = team_rail_.rank * team_lsa_.nRanks;
+        return first <= peer && peer < first + team_lsa_.nRanks;
+    }
+
+    __device__ __forceinline__ int contextCount() const {
+        return comm_.ginContextCount;
+    }
+
+    __device__ __forceinline__ size_t pointerOffset(const void* ptr) const {
+        return static_cast<size_t>(static_cast<const char*>(ptr) - local_base_);
+    }
+
+    __device__ __forceinline__ void* worldPeerPointer(int peer,
+                                                      const void* ptr) const {
+        if (peer == team_world_.rank) return const_cast<void*>(ptr);
+        return ncclGetPeerPointer(window_, pointerOffset(ptr), peer);
+    }
+
+    __device__ __forceinline__ void* lsaPeerPointer(int peer,
+                                                    const void* ptr) const {
+        if (peer == team_lsa_.rank) return const_cast<void*>(ptr);
+        return ncclGetLsaPointer(window_, pointerOffset(ptr), peer);
+    }
+
+    template <NcclGinTeam Team>
+    __device__ __forceinline__ void put(
+        int dst_rank, const void* send_ptr, void* recv_ptr, uint32_t nbytes,
+        uint32_t opt_flags = ncclGinOptFlagsDefault) const {
+        gin_.put(team<Team>(), dst_rank, window_, pointerOffset(recv_ptr),
+                 window_, pointerOffset(send_ptr), nbytes, ncclGin_None{},
+                 ncclGin_None{}, ncclCoopThread{}, ncclGin_None{},
+                 cuda::thread_scope_thread, cuda::thread_scope_device,
+                 opt_flags);
+    }
+
+    template <NcclGinTeam Team, typename T>
+    __device__ __forceinline__ void putValue(
+        int dst_rank, T* recv_ptr, T value,
+        uint32_t opt_flags = ncclGinOptFlagsDefault) const {
+        static_assert(
+            std::is_scalar<T>::value && std::is_trivially_copyable<T>::value,
+            "NcclGinHandle::putValue requires a scalar");
+        static_assert(sizeof(T) == 1 || sizeof(T) == 2 || sizeof(T) == 4 ||
+                          sizeof(T) == 8,
+                      "NcclGinHandle::putValue supports 1, 2, 4, or 8 bytes");
+        gin_.putValue(team<Team>(), dst_rank, window_, pointerOffset(recv_ptr),
+                      value, ncclGin_None{}, ncclCoopThread{}, ncclGin_None{},
+                      cuda::thread_scope_thread, cuda::thread_scope_device,
+                      opt_flags);
+    }
+
+    template <NcclGinTeam Team>
+    __device__ __forceinline__ void signalAdd(int dst_rank,
+                                              uint64_t* signal_ptr,
+                                              uint64_t value) const {
+        gin_.signal(team<Team>(), dst_rank,
+                    detail::NcclStrongVaSignalAdd{
+                        window_, pointerOffset(signal_ptr), value},
+                    ncclCoopThread{});
+    }
+
+    __device__ __forceinline__ void resetSignal(uint64_t* signal_ptr) const {
+        gin_.resetSignal(window_, pointerOffset(signal_ptr));
+    }
+
+    __device__ __forceinline__ uint64_t
+    readSignal(const uint64_t* signal_ptr) const {
+        return gin_.readSignal(window_, pointerOffset(signal_ptr));
+    }
+
+    __device__ __forceinline__ void flushWarp() const {
+        gin_.flush(ncclCoopWarp{});
+    }
+
+    __device__ __forceinline__ void flushContextWarp(int context) const {
+        ncclGin(comm_, context, NCCL_GIN_RESOURCE_SHARING_CTA)
+            .flush(ncclCoopWarp{});
+    }
+
+    template <NcclGinTeam Team>
+    __device__ __forceinline__ void signalIncContext0(int dst_rank,
+                                                      int signal_id) const {
+        ncclGin(comm_, 0, NCCL_GIN_RESOURCE_SHARING_CTA)
+            .signal(team<Team>(), dst_rank,
+                    ncclGin_SignalInc{static_cast<ncclGinSignal_t>(signal_id)},
+                    ncclCoopThread{});
+    }
+
+    __device__ __forceinline__ uint64_t
+    advanceSignalShadowContext0(int signal_id) const {
+        ncclGin barrier(comm_, 0, NCCL_GIN_RESOURCE_SHARING_CTA);
+        return ++(*barrier.getSignalShadowPtr(
+            static_cast<ncclGinSignal_t>(signal_id)));
+    }
+
+    __device__ __forceinline__ uint64_t
+    readSignalContext0(int signal_id) const {
+        return ncclGin(comm_, 0, NCCL_GIN_RESOURCE_SHARING_CTA)
+            .readSignal(static_cast<ncclGinSignal_t>(signal_id));
+    }
+
+   private:
+    template <NcclGinTeam Team>
+    __device__ __forceinline__ ncclTeam team() const {
+        if constexpr (Team == NcclGinTeam::kRail) {
+            return team_rail_;
+        } else {
+            return team_world_;
+        }
+    }
+
+    const ncclDevComm_t& comm_;
+    ncclGin gin_;
+    ncclWindow_t window_;
+    const char* local_base_;
+    ncclTeam team_world_;
+    ncclTeam team_lsa_;
+    ncclTeam team_rail_;
+};
+
 // Pointer and route queries are per-thread operations. peer must be a valid
 // world rank.
 __device__ __forceinline__ bool mc_nccl_lsa_available(
@@ -111,6 +314,13 @@ __device__ __forceinline__ bool mc_nccl_gin_available(
     return detail::NcclDeviceContextAccess::ginEnabled(ctx);
 }
 
+// Return the number of GIN contexts configured for ctx. Like the other device
+// helpers, this is unchecked: ctx must be live and GIN must be enabled.
+__device__ __forceinline__ int mc_nccl_gin_context_count(
+    const NcclDeviceContext& ctx) {
+    return detail::NcclDeviceContextAccess::ginContextCount(ctx);
+}
+
 __device__ __forceinline__ NcclDeviceRoute
 mc_nccl_route(const NcclDeviceContext& ctx, int peer) {
     if (peer == detail::NcclDeviceContextAccess::rank(ctx))
@@ -169,6 +379,29 @@ __device__ __forceinline__ void mc_nccl_lsa_barrier(
 // nonnegative channel. Signal pointers must be naturally aligned uint64_t
 // objects inside the registration.
 
+template <NcclGinTeam Team>
+__device__ __forceinline__ void mc_nccl_put_team(
+    const NcclDeviceContext& ctx, int channel, int dst_rank, int qps_per_rank,
+    const void* send_ptr, void* recv_ptr, uint32_t nbytes, int lane_id,
+    uint32_t opt_flags = ncclGinOptFlagsDefault,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    (void)qps_per_rank;
+    if (lane_id != 0) return;
+
+    const size_t src_offset = detail::mc_nccl_pointer_offset(ctx, send_ptr);
+    const size_t dst_offset = detail::mc_nccl_pointer_offset(ctx, recv_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.put(detail::mc_nccl_gin_team<Team>(comm), dst_rank, window, dst_offset,
+            window, src_offset, nbytes, ncclGin_None{}, ncclGin_None{},
+            ncclCoopThread{}, ncclGin_None{}, cuda::thread_scope_thread,
+            cuda::thread_scope_device, opt_flags);
+}
+
 __device__ __forceinline__ void mc_nccl_put(
     const NcclDeviceContext& ctx, int channel, int dst_rank, int qps_per_rank,
     const void* send_ptr, void* recv_ptr, uint32_t nbytes, int lane_id) {
@@ -206,10 +439,177 @@ __device__ __forceinline__ void mc_nccl_put_with_signal(
                           ctx, static_cast<unsigned int>(channel))};
     gin.put(ncclTeamWorld(comm), dst_rank, window, dst_offset, window,
             src_offset, nbytes,
-            ncclGin_VASignalAdd{window, completion_offset, completion_delta},
+            detail::NcclStrongVaSignalAdd{window, completion_offset,
+                                          completion_delta},
             ncclGin_None{}, ncclCoopThread{});
 }
 
+// Assign a 1-, 2-, 4-, or 8-byte scalar in the destination's matching
+// registered buffer using GIN inline data. recv_ptr is interpreted as an offset
+// in the peer's window; it is not a directly dereferenceable peer pointer.
+// The destination must be naturally aligned for T and wholly contained in the
+// symmetric registration bound to ctx. This operation does not signal remote
+// completion; pair ordered traffic with a strong GIN signal and receiver wait.
+template <NcclGinTeam Team, typename T>
+__device__ __forceinline__ void mc_nccl_put_value_team(
+    const NcclDeviceContext& ctx, int channel, int dst_rank, int qps_per_rank,
+    T* recv_ptr, T value, int lane_id,
+    uint32_t opt_flags = ncclGinOptFlagsDefault,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    static_assert(std::is_scalar<T>::value,
+                  "mc_nccl_put_value_team requires a scalar type");
+    static_assert(std::is_trivially_copyable<T>::value,
+                  "mc_nccl_put_value_team requires a trivially copyable type");
+    static_assert(
+        sizeof(T) == 1 || sizeof(T) == 2 || sizeof(T) == 4 || sizeof(T) == 8,
+        "mc_nccl_put_value_team supports only 1, 2, 4, or 8 bytes");
+    (void)qps_per_rank;
+    if (lane_id != 0) return;
+
+    const size_t dst_offset = detail::mc_nccl_pointer_offset(ctx, recv_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.putValue(detail::mc_nccl_gin_team<Team>(comm), dst_rank, window,
+                 dst_offset, value, ncclGin_None{}, ncclCoopThread{},
+                 ncclGin_None{}, cuda::thread_scope_thread,
+                 cuda::thread_scope_device, opt_flags);
+}
+
+template <typename T>
+__device__ __forceinline__ void mc_nccl_put_value(const NcclDeviceContext& ctx,
+                                                  int channel, int dst_rank,
+                                                  int qps_per_rank, T* recv_ptr,
+                                                  T value, int lane_id) {
+    static_assert(std::is_scalar<T>::value,
+                  "mc_nccl_put_value requires a scalar type");
+    static_assert(std::is_trivially_copyable<T>::value,
+                  "mc_nccl_put_value requires a trivially copyable type");
+    static_assert(
+        sizeof(T) == 1 || sizeof(T) == 2 || sizeof(T) == 4 || sizeof(T) == 8,
+        "mc_nccl_put_value supports only 1, 2, 4, or 8 bytes");
+    (void)qps_per_rank;
+    if (lane_id != 0) return;
+
+    const size_t dst_offset = detail::mc_nccl_pointer_offset(ctx, recv_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{comm, detail::mc_nccl_gin_context(
+                          ctx, static_cast<unsigned int>(channel))};
+    gin.putValue(ncclTeamWorld(comm), dst_rank, window, dst_offset, value,
+                 ncclGin_None{}, ncclCoopThread{});
+}
+
+// Add value to a GIN VA signal in the destination's matching buffer. Unlike
+// mc_nccl_signal_add(), this helper never routes through local/LSA atomics.
+// Signal visibility has strong semantics: it implies settlement of preceding
+// puts issued to the same peer on this context. signal_ptr must identify a
+// naturally aligned uint64_t wholly contained in the registration bound to ctx.
+template <NcclGinTeam Team>
+__device__ __forceinline__ void mc_nccl_gin_signal_add_team(
+    const NcclDeviceContext& ctx, int dst_rank, int channel, int qps_per_rank,
+    uint64_t* signal_ptr, uint64_t value, int lane_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    (void)qps_per_rank;
+    if (lane_id != 0) return;
+
+    const size_t signal_offset =
+        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.signal(detail::mc_nccl_gin_team<Team>(comm), dst_rank,
+               detail::NcclStrongVaSignalAdd{window, signal_offset, value},
+               ncclCoopThread{});
+}
+
+// Increment one of the communicator-owned GIN signals. These signals avoid a
+// symmetric-memory address calculation and are intended for compact control
+// protocols such as a device barrier. signal_id must be smaller than the
+// gin_signal_count requested when the device communicator was created.
+template <NcclGinTeam Team>
+__device__ __forceinline__ void mc_nccl_gin_signal_inc_team(
+    const NcclDeviceContext& ctx, int dst_rank, int channel, int signal_id,
+    int lane_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    if (lane_id != 0) return;
+
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.signal(detail::mc_nccl_gin_team<Team>(comm), dst_rank,
+               ncclGin_SignalInc{static_cast<ncclGinSignal_t>(signal_id)},
+               ncclCoopThread{});
+}
+
+// Advance the caller-managed shadow for a communicator-owned GIN signal and
+// return the value that a matching receive must reach.
+__device__ __forceinline__ uint64_t mc_nccl_gin_advance_signal_shadow(
+    const NcclDeviceContext& ctx, int channel, int signal_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    return ++(*gin.getSignalShadowPtr(static_cast<ncclGinSignal_t>(signal_id)));
+}
+
+__device__ __forceinline__ uint64_t mc_nccl_gin_read_signal_id(
+    const NcclDeviceContext& ctx, int channel, int signal_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    return gin.readSignal(static_cast<ncclGinSignal_t>(signal_id));
+}
+
+__device__ __forceinline__ void mc_nccl_gin_signal_add(
+    const NcclDeviceContext& ctx, int dst_rank, int channel, int qps_per_rank,
+    uint64_t* signal_ptr, uint64_t value, int lane_id) {
+    (void)qps_per_rank;
+    if (lane_id != 0) return;
+
+    const size_t signal_offset =
+        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{comm, detail::mc_nccl_gin_context(
+                          ctx, static_cast<unsigned int>(channel))};
+    gin.signal(ncclTeamWorld(comm), dst_rank,
+               detail::NcclStrongVaSignalAdd{window, signal_offset, value},
+               ncclCoopThread{});
+}
+
+// Reset a local GIN VA signal through the context that owns it. The caller must
+// ensure that no remote signal operation can race this reset. Only lane 0 acts.
+__device__ __forceinline__ void mc_nccl_gin_reset_signal(
+    const NcclDeviceContext& ctx, int channel, uint64_t* signal_ptr,
+    int lane_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    if (lane_id != 0) return;
+
+    const size_t signal_offset =
+        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    const auto window = detail::NcclDeviceContextAccess::window(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.resetSignal(window, signal_offset);
+}
+
 // Add value to a 64-bit signal in the destination's matching buffer. This is
 // explicitly increment semantics, not assignment. Local/LSA routes use a
 // system-scope atomic; GIN uses a VA signal on the selected context.
@@ -238,25 +638,51 @@ __device__ __forceinline__ void mc_nccl_signal_add(
         return;
     }
 
-    const size_t signal_offset =
-        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
-    const auto window = detail::NcclDeviceContextAccess::window(ctx);
-    ncclGin gin{comm, detail::mc_nccl_gin_context(
-                          ctx, static_cast<unsigned int>(channel))};
-    gin.signal(ncclTeamWorld(comm), dst_rank,
-               ncclGin_VASignalAdd{window, signal_offset, value},
-               ncclCoopThread{});
+    mc_nccl_gin_signal_add(ctx, dst_rank, channel, qps_per_rank, signal_ptr,
+                           value, 0);
 }
 
-__device__ __forceinline__ void mc_nccl_flush(const NcclDeviceContext& ctx,
-                                              int channel, int lane_id) {
+__device__ __forceinline__ void mc_nccl_flush(
+    const NcclDeviceContext& ctx, int channel, int lane_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
     if (lane_id != 0) return;
     const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
-    ncclGin gin{comm, detail::mc_nccl_gin_context(
-                          ctx, static_cast<unsigned int>(channel))};
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
     gin.flush(ncclCoopThread{});
 }
 
+__device__ __forceinline__ void mc_nccl_flush_warp(
+    const NcclDeviceContext& ctx, int channel,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kCta) {
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.flush(ncclCoopWarp{});
+}
+
+// Read a GIN VA signal from the local matching window. This helper never falls
+// back to an ordinary CUDA atomic load. signal_ptr must be an aligned uint64_t
+// inside the registration bound to ctx, and channel must select the same GIN
+// context used by the remote producer.
+__device__ __forceinline__ uint64_t mc_nccl_gin_read_signal(
+    const NcclDeviceContext& ctx, int channel, const uint64_t* signal_ptr,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    const size_t signal_offset =
+        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
+    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    return gin.readSignal(detail::NcclDeviceContextAccess::window(ctx),
+                          signal_offset);
+}
+
 __device__ __forceinline__ uint64_t mc_nccl_read_signal(
     const NcclDeviceContext& ctx, int channel, const uint64_t* signal_ptr) {
     if (!mc_nccl_gin_available(ctx)) {
@@ -265,13 +691,28 @@ __device__ __forceinline__ uint64_t mc_nccl_read_signal(
         return signal.load(cuda::memory_order_acquire);
     }
 
+    return mc_nccl_gin_read_signal(ctx, channel, signal_ptr);
+}
+
+// Wait on a GIN VA signal in the local matching window. This helper never
+// falls back to an ordinary CUDA atomic load. Only lane 0 waits; callers that
+// need a warp-wide dependency must synchronize after it returns. signal_ptr
+// and channel have the same preconditions as mc_nccl_gin_read_signal().
+__device__ __forceinline__ void mc_nccl_gin_wait_signal(
+    const NcclDeviceContext& ctx, int channel, const uint64_t* signal_ptr,
+    uint64_t least, int lane_id,
+    NcclGinResourceSharing sharing = NcclGinResourceSharing::kGpu) {
+    if (lane_id != 0) return;
     const size_t signal_offset =
         detail::mc_nccl_pointer_offset(ctx, signal_ptr);
     const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
-    ncclGin gin{comm, detail::mc_nccl_gin_context(
-                          ctx, static_cast<unsigned int>(channel))};
-    return gin.readSignal(detail::NcclDeviceContextAccess::window(ctx),
-                          signal_offset);
+    ncclGin gin{
+        comm,
+        detail::mc_nccl_gin_context(ctx, static_cast<unsigned int>(channel)),
+        detail::mc_nccl_gin_sharing_mode(sharing)};
+    gin.waitSignal(ncclCoopThread{},
+                   detail::NcclDeviceContextAccess::window(ctx), signal_offset,
+                   least);
 }
 
 // Only lane 0 waits. Callers that need a warp-wide dependency must synchronize
@@ -288,14 +729,7 @@ __device__ __forceinline__ void mc_nccl_wait_signal(
         return;
     }
 
-    const size_t signal_offset =
-        detail::mc_nccl_pointer_offset(ctx, signal_ptr);
-    const auto& comm = detail::NcclDeviceContextAccess::comm(ctx);
-    ncclGin gin{comm, detail::mc_nccl_gin_context(
-                          ctx, static_cast<unsigned int>(channel))};
-    gin.waitSignal(ncclCoopThread{},
-                   detail::NcclDeviceContextAccess::window(ctx), signal_offset,
-                   least);
+    mc_nccl_gin_wait_signal(ctx, channel, signal_ptr, least, 0);
 }
 
 }  // namespace device
diff --git a/mooncake-transfer-engine/include/transport/device/nccl_device_transport.h b/mooncake-transfer-engine/include/transport/device/nccl_device_transport.h
index a32fd5a543..25fcbbf6d8 100644
--- a/mooncake-transfer-engine/include/transport/device/nccl_device_transport.h
+++ b/mooncake-transfer-engine/include/transport/device/nccl_device_transport.h
@@ -36,16 +36,27 @@ enum class NcclDeviceRoute : uint8_t {
     kGin,
 };
 
+enum class NcclGinConnectionType : uint8_t {
+    kNone = 0,
+    kFull,
+    kRail,
+};
+
 struct NcclTransportConfig {
     int rank = -1;
     int num_ranks = 0;
 
-    // Mooncake currently supports either full world-team GIN connectivity or
-    // no GIN. Rail connectivity is deferred until Mooncake has a rail-team
-    // rank contract.
+    // enable_gin=false overrides gin_connection_type. Rail connectivity uses
+    // NCCL's rail team: peers are addressed by their rail-team rank rather
+    // than by world rank.
     bool enable_gin = true;
+    NcclGinConnectionType gin_connection_type = NcclGinConnectionType::kFull;
     int gin_context_count = 4;
     bool gin_exclusive_contexts = false;
+    int gin_queue_depth = 0;
+    int gin_signal_count = 0;
+    // A negative value leaves NCCL's default traffic class unchanged.
+    int gin_traffic_class = -1;
 
     // LSA barriers synchronize only the local LSA team. Cross-LSA/world
     // synchronization remains the caller's responsibility.
@@ -64,11 +75,21 @@ struct NcclTransportProperties {
     int lsa_team_count = 0;
     int lsa_barrier_count = 0;
     bool gin_enabled = false;
+    NcclGinConnectionType gin_connection_type = NcclGinConnectionType::kNone;
     NcclGinBackend gin_backend = NcclGinBackend::kNone;
     int gin_connection_count = 0;
     int gin_context_count = 0;
 };
 
+// Coordinates of this rank in its contiguous LSA team. Kept separate from
+// NcclTransportProperties so extending the experimental API does not change
+// the size of the existing by-value properties return type.
+struct NcclLsaTopology {
+    int rank = -1;
+    int size = 0;
+    int first_rank = -1;
+};
+
 namespace detail {
 struct NcclDeviceContextAccess;
 }  // namespace detail
@@ -91,15 +112,25 @@ class NcclBufferRegistration {
 // communicators and windows remain behind opaque pointers.
 class NcclDeviceContext {
    public:
+    // ncclDevComm is embedded so kernels read its hot fields from parameter
+    // memory instead of chasing a global-memory pointer. Keep a small amount of
+    // headroom because the version-specific NCCL structure can grow between
+    // releases; nccl_device.cuh verifies that the headers in use still fit.
+    static constexpr size_t kNativeCommCapacity = 256;
+    static constexpr size_t kNativeCommAlignment = 8;
+
     bool valid() const { return native_comm_ != nullptr; }
 
    private:
     const void* native_comm_ = nullptr;
+    alignas(kNativeCommAlignment) unsigned char native_comm_storage_
+        [kNativeCommCapacity]{};
     const void* native_window_ = nullptr;
     const void* local_base_ = nullptr;
     int rank_ = -1;
     int gin_context_count_ = 0;
     bool gin_enabled_ = false;
+    bool gin_connections_railed_ = false;
     bool lsa_multimem_enabled_ = false;
 
     friend class NcclDeviceTransportImpl;
@@ -132,17 +163,20 @@ class NcclTransport {
     virtual void* allocateBuffer(size_t bytes) = 0;
     virtual int freeBuffer(void* ptr) = 0;
 
-    // Collectively register a symmetric buffer. Calls must occur in the same
-    // order on every rank. Deregistration is local after all device work and
-    // remote access have completed. The registration is invalidated on
-    // successful deregistration.
+    // Collectively register a symmetric, strictly ordered NCCL window. Calls
+    // must occur in the same order on every rank. Every pointer passed to a
+    // GIN helper through the returned context must be wholly contained in this
+    // buffer. Deregistration is local after all device work and remote access
+    // have completed. The registration is invalidated on successful
+    // deregistration.
     virtual int registerBuffer(void* ptr, size_t bytes,
                                NcclBufferRegistration* registration) = 0;
     virtual int deregisterBuffer(NcclBufferRegistration* registration) = 0;
 
-    // Safe common path: every rank allocates, collectively checks that all
-    // allocations succeeded, and only then enters registration. All ranks
-    // must call this method in the same order.
+    // Coordinated common path: every rank allocates and collectively checks all
+    // allocations, zero-initializes the allocation before it can contain GIN
+    // VA signals, and only then enters registration. All ranks must call this
+    // method in the same order.
     virtual int allocateAndRegisterBuffer(
         size_t bytes, void** ptr, NcclBufferRegistration* registration) = 0;
 
@@ -155,8 +189,28 @@ class NcclTransport {
     virtual bool initialized() const = 0;
 
     // The caller must first ensure that no kernel can access the context or
-    // any registered buffer.
+    // any registered buffer, then call shutdown in coordinated order on every
+    // communicator rank. Rank-local destructor cleanup is not a substitute for
+    // coordinated NCCL communicator teardown.
     virtual int shutdown() = 0;
+
+    // Host-side collective status agreement. Every rank must call this in the
+    // same order after initialize(), while the CUDA stream and NCCL
+    // communicator remain healthy. It returns true only when local_success is
+    // true on every communicator rank. This coordinates application status; it
+    // is not recovery from a CUDA/NCCL control-path failure. Use it before any
+    // rank throws from a collectively constructed object. Kept at the end to
+    // preserve the vtable slots of the interface introduced by the initial
+    // NCCL backend.
+    virtual bool allRanksSucceeded(bool local_success) = 0;
+    virtual NcclLsaTopology lsaTopology() const = 0;
+
+    // Failure path for an obsolete communicator generation. The caller must
+    // first ensure that no Mooncake kernel can still access its device context.
+    // Unlike shutdown(), an implementation may release it without healthy peer
+    // participation. The default preserves source compatibility for external
+    // transports that do not need a distinct local-abort path.
+    virtual int abort() { return shutdown(); }
 };
 
 // Create the CUDA-only NCCL LSA/GIN device transport.
diff --git a/mooncake-transfer-engine/include/transport/flagcx_transport/flagcx_transport.h b/mooncake-transfer-engine/include/transport/flagcx_transport/flagcx_transport.h
new file mode 100644
index 0000000000..88df3ada98
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/flagcx_transport/flagcx_transport.h
@@ -0,0 +1,135 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#ifndef FLAGCX_TRANSPORT_H_
+#define FLAGCX_TRANSPORT_H_
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <atomic>
+#include <condition_variable>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <flagcx_p2p.h>
+
+#include "transfer_metadata.h"
+#include "transport/transport.h"
+
+namespace mooncake {
+
+// FlagCX-backed transport built on the FlagCX P2P engine API
+// (flagcx_p2p.h).  Unlike the earlier OneSide/collective proof of
+// concept, this version maps one-to-one onto Mooncake's per-SegmentID
+// point-to-point model:
+//
+//   - install() creates a single FlagcxP2pEngine and starts its RPC
+//     accept daemon.  The engine's "ip:rpc_port" handshake endpoint is
+//     advertised to peers via the segment descriptor (rdma_server_name).
+//   - registerLocalMemory() registers the *user* buffer directly with
+//     the engine (flagcxP2pEngineReg) -- no staging window, no copy.
+//     Incoming RDMA lands straight in the registered buffer.
+//   - The data path resolves a cached connection per target segment
+//     (flagcxP2pEngineGetConn), looks up the remote rkey by absolute
+//     virtual address (flagcxP2pEngineMakeDesc -- the FlagCX equivalent
+//     of Mooncake's "rkey by dst_ptr"), then issues a non-blocking one-sided
+//     WriteVector (WRITE) or ReadVector (READ).
+//
+// A lightweight completion thread polls submitted FlagCX transfer IDs and
+// reports completion through the usual TransferTask slice counters.
+//
+// Required runtime env: the FlagCX engine honours the standard FlagCX
+// knobs (FLAGCX_SOCKET_IFNAME selects the NIC the RPC endpoint binds /
+// advertises).  No MC_FLAGCX_RANK / NRANKS / UID file / window size are
+// needed anymore.
+class FlagCxTransport : public Transport {
+   public:
+    FlagCxTransport();
+    ~FlagCxTransport() override;
+
+    Status submitTransfer(BatchID batch_id,
+                          const std::vector<TransferRequest> &entries) override;
+
+    Status submitTransferTask(
+        const std::vector<TransferTask *> &task_list) override;
+
+    Status getTransferStatus(BatchID batch_id, size_t task_id,
+                             TransferStatus &status) override;
+
+   private:
+    int install(std::string &local_server_name,
+                std::shared_ptr<TransferMetadata> meta,
+                std::shared_ptr<Topology> topo) override;
+
+    int registerLocalMemory(void *addr, size_t length,
+                            const std::string &location, bool remote_accessible,
+                            bool update_metadata) override;
+
+    int unregisterLocalMemory(void *addr,
+                              bool update_metadata = false) override;
+
+    int registerLocalMemoryBatch(const std::vector<BufferEntry> &buffer_list,
+                                 const std::string &location) override;
+
+    int unregisterLocalMemoryBatch(
+        const std::vector<void *> &addr_list) override;
+
+    const char *getName() const override { return "flagcx"; }
+
+    int allocateLocalSegment();
+    // Issue a group of same-target, same-opcode slices as one multi-iov
+    // (multi-rail) transfer and record its transfer id for status checks.
+    void runSliceGroup(const std::vector<Slice *> &group);
+    void submitSlices(const std::vector<Slice *> &slices);
+    bool pollPendingTransfers();
+    void completionLoop();
+
+    // Find the engine MR handle whose registered region fully contains
+    // [addr, addr+length).  Returns false if the source is unregistered.
+    bool resolveLocalMr(void *addr, size_t length, FlagcxP2pMr &mr_out);
+
+    // Resolve (and lazily establish + cache) a connection to the engine
+    // serving `target_id`, using the flagcx endpoint published in that
+    // segment's descriptor.
+    FlagcxP2pConn *connForSegment(SegmentID target_id);
+
+    FlagcxP2pEngine *engine_ = nullptr;
+    // "ip:rpc_port" handshake endpoint advertised to peers.
+    std::string flagcx_endpoint_;
+
+    struct Reg {
+        void *addr;
+        size_t length;
+        FlagcxP2pMr mr;
+    };
+    std::mutex reg_mu_;
+    std::vector<Reg> regs_;
+
+    struct PendingTransfer {
+        FlagcxP2pConn *conn;
+        uint64_t transfer_id;
+        std::vector<Slice *> slices;
+        std::chrono::steady_clock::time_point deadline;
+    };
+
+    std::mutex flagcx_mu_;
+    std::mutex submit_mu_;
+    std::mutex pending_mu_;
+    std::condition_variable pending_cv_;
+    std::vector<PendingTransfer> pending_;
+    std::atomic<bool> completion_running_{false};
+    std::thread completion_thread_;
+};
+
+}  // namespace mooncake
+
+#endif  // FLAGCX_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/include/transport/musa_transport/musa_transport.h b/mooncake-transfer-engine/include/transport/musa_transport/musa_transport.h
new file mode 100644
index 0000000000..ce8e6ee886
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/musa_transport/musa_transport.h
@@ -0,0 +1,37 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+
+#ifndef MUSA_TRANSPORT_H_
+#define MUSA_TRANSPORT_H_
+
+#include "transport/nvlink_transport/nvlink_transport.h"
+
+namespace mooncake {
+
+// MUSA's IPC context and copy-stream rules differ from CUDA's.  The actual
+// transfer algorithm is shared with NvlinkTransport through its policy hook;
+// this class only selects the MUSA runtime policy and exposes the allocator
+// used by the GPU-vendor compatibility header.
+class MusaTransport final : public NvlinkTransport {
+   public:
+    MusaTransport();
+    ~MusaTransport() override = default;
+
+    static void* allocatePinnedLocalMemory(size_t length);
+    static void freePinnedLocalMemory(void* addr);
+};
+
+}  // namespace mooncake
+
+#endif  // MUSA_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_host_numa_allocation.h b/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_host_numa_allocation.h
new file mode 100644
index 0000000000..c6f5ce49b8
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_host_numa_allocation.h
@@ -0,0 +1,165 @@
+// Copyright 2024 KVCache.AI
+
+#ifndef NVLINK_HOST_NUMA_ALLOCATION_H_
+#define NVLINK_HOST_NUMA_ALLOCATION_H_
+
+#include "cuda_alike.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <vector>
+
+#include "common/base/status.h"
+
+#if defined(USE_MNNVL) && defined(USE_CUDA) && CUDA_VERSION >= 12030
+#define MOONCAKE_NVLINK_HOST_NUMA_ENABLED 1
+#else
+#define MOONCAKE_NVLINK_HOST_NUMA_ENABLED 0
+#endif
+
+namespace mooncake {
+
+class NvlinkHostNumaAllocationTestPeer;
+class NvlinkTransport;
+class NvlinkTransportTestPeer;
+
+class NvlinkHostNumaAllocation {
+   public:
+    NvlinkHostNumaAllocation(const NvlinkHostNumaAllocation&) = delete;
+    NvlinkHostNumaAllocation& operator=(const NvlinkHostNumaAllocation&) =
+        delete;
+
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    ~NvlinkHostNumaAllocation();
+
+    static Status DiscoverHostNumaNodes(std::vector<int>& numa_nodes);
+    static Status GetAllocationGranularity(int numa_node, size_t& granularity);
+    // The output must be empty. On failure, a nonempty output owns incomplete
+    // rollback state: do not use/register it; retain it and retry Release().
+    static Status Create(int numa_node, size_t requested_length,
+                         size_t required_va_alignment,
+                         std::unique_ptr<NvlinkHostNumaAllocation>& allocation);
+
+    // Caller serializes owner operations and completes transport unregister
+    // before release. On failure retain the owner and retry; destruction is
+    // best-effort only. Completed release stages are not repeated.
+    [[nodiscard]] Status Release();
+#else
+    ~NvlinkHostNumaAllocation() = default;
+
+    static Status DiscoverHostNumaNodes(std::vector<int>& numa_nodes) {
+        numa_nodes.clear();
+        return Unsupported();
+    }
+    static Status GetAllocationGranularity(int, size_t& granularity) {
+        granularity = 0;
+        return Unsupported();
+    }
+    static Status Create(
+        int, size_t, size_t,
+        std::unique_ptr<NvlinkHostNumaAllocation>& allocation) {
+        if (allocation)
+            return Status::InvalidArgument("allocation output must be empty");
+        return Unsupported();
+    }
+    [[nodiscard]] Status Release() { return Status::OK(); }
+#endif
+
+    void* base() const { return base_; }
+    size_t length() const { return length_; }
+    int numaNode() const { return numa_node_; }
+
+   private:
+    friend class NvlinkHostNumaAllocationTestPeer;
+    friend class NvlinkTransport;
+    friend class NvlinkTransportTestPeer;
+
+    NvlinkHostNumaAllocation() = default;
+
+    static Status Unsupported() {
+        return Status::NotSupportedTransport(
+            "HOST_NUMA Fabric VMM requires USE_MNNVL, USE_CUDA, and CUDA "
+            "Toolkit 12.3 or newer");
+    }
+
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    struct DriverApi {
+        std::function<CUresult(int*)> device_get_count;
+        std::function<CUresult(CUdevice*, int)> device_get;
+        std::function<CUresult(int*, CUdevice_attribute, CUdevice)>
+            device_get_attribute;
+        std::function<CUresult(size_t*, const CUmemAllocationProp*,
+                               CUmemAllocationGranularity_flags)>
+            mem_get_allocation_granularity;
+        std::function<CUresult(CUmemGenericAllocationHandle*, size_t,
+                               const CUmemAllocationProp*, unsigned long long)>
+            mem_create;
+        std::function<CUresult(CUdeviceptr*, size_t, size_t, CUdeviceptr,
+                               unsigned long long)>
+            mem_address_reserve;
+        std::function<CUresult(CUdeviceptr, size_t, size_t,
+                               CUmemGenericAllocationHandle,
+                               unsigned long long)>
+            mem_map;
+        std::function<CUresult(CUdeviceptr, size_t, const CUmemAccessDesc*,
+                               size_t)>
+            mem_set_access;
+        std::function<CUresult(CUdeviceptr, size_t)> mem_unmap;
+        std::function<CUresult(CUdeviceptr, size_t)> mem_address_free;
+        std::function<CUresult(CUmemGenericAllocationHandle)> mem_release;
+        std::function<CUresult(CUmemGenericAllocationHandle*, void*)>
+            mem_retain_allocation_handle;
+        std::function<CUresult(void*, CUmemGenericAllocationHandle,
+                               CUmemAllocationHandleType, unsigned long long)>
+            mem_export_to_shareable_handle;
+    };
+    struct OwnedRangeRegistry;
+
+    static DriverApi ProductionDriverApi();
+    static Status ValidateVisibleGpuFabricSupportWithDriverApi(
+        const DriverApi& api, std::vector<CUdevice>& visible_devices);
+    static Status DiscoverHostNumaNodesWithDriverApi(
+        const DriverApi& api, std::vector<int>& numa_nodes);
+    static Status GetAllocationGranularityWithDriverApi(int numa_node,
+                                                        const DriverApi& api,
+                                                        size_t& granularity);
+    static Status CreateWithDriverApi(
+        int numa_node, size_t requested_length, size_t required_va_alignment,
+        const DriverApi& api,
+        std::unique_ptr<NvlinkHostNumaAllocation>& allocation);
+
+    static bool RegisterOwnedRange(void* base, size_t length,
+                                   const DriverApi& api);
+    enum class OwnedRangeResult {
+        kNotOwned,
+        kPinned,
+        kInvalid,
+        kUnavailable,
+        kError
+    };
+    // Classify and pin atomically; only kNotOwned may use legacy registration.
+    static OwnedRangeResult AcquireOwnedRange(void* base, size_t length,
+                                              DriverApi* api);
+    static bool ReleaseOwnedRange(void* base, size_t length);
+    static bool IsOwnedRangeBase(void* base);
+    static OwnedRangeRegistry& OwnedRanges();
+#endif
+
+    void* base_ = nullptr;
+    size_t length_ = 0;
+    int numa_node_ = -1;
+    bool mapped_ = false;
+    bool address_reserved_ = false;
+    bool handle_owned_ = false;
+    uint64_t allocation_handle_ = 0;
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    bool owned_range_registered_ = false;
+    DriverApi driver_api_;
+#endif
+};
+
+}  // namespace mooncake
+
+#endif  // NVLINK_HOST_NUMA_ALLOCATION_H_
diff --git a/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_transport.h b/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_transport.h
index 95601689a1..859734e295 100644
--- a/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_transport.h
+++ b/mooncake-transfer-engine/include/transport/nvlink_transport/nvlink_transport.h
@@ -11,18 +11,87 @@
 #include <mutex>
 #include <queue>
 #include <string>
+#include <unordered_map>
 #include <vector>
 #include <utility>
+#include <optional>
 
 #include "common/hash_utils.h"
 #include "topology.h"
 #include "transfer_metadata.h"
+#include "transport/nvlink_transport/nvlink_host_numa_allocation.h"
 #include "transport/transport.h"
 
 namespace mooncake {
 
 class TransferMetadata;
 
+// Backend-specific hooks for the CUDA-compatible IPC transport core.  The
+// transfer bookkeeping and batched-copy algorithm stay in NvlinkTransport;
+// vendors only decide which device owns an imported IPC mapping and which
+// device stream submits a copy.
+class GpuIpcTransportPolicy {
+   public:
+    virtual ~GpuIpcTransportPolicy() = default;
+
+    virtual const char* protocol() const = 0;
+    virtual const char* displayName() const = 0;
+
+    virtual int selectStreamDevice(const void* local_buffer, const void* source,
+                                   const void* destination) const = 0;
+
+    // The legacy NVLink path submits one homogeneous batch on the stream
+    // selected from its first local buffer.  MUSA can opt into per-device
+    // grouping because its destination-owned stream rule may select a
+    // different device for each entry.
+    virtual bool groupTransfersByDevice() const { return false; }
+
+    // CUDA's legacy path already runs with the caller's active device.  MUSA
+    // needs an explicit guard around submit/query because the destination
+    // stream can belong to another logical device.
+    virtual bool requiresStreamDeviceGuard() const { return false; }
+
+    // MUSA participates in the multi-protocol metadata format used alongside
+    // TCP/RDMA.  Keep NVLink's legacy segment replacement behavior unchanged.
+    virtual bool preserveExistingMetadata() const { return false; }
+
+    // Resolve wildcard registrations to a vendor-specific location when the
+    // runtime can identify the owning device. Legacy policies keep the
+    // caller-provided location unchanged.
+    virtual std::string normalizeMemoryLocation(
+        const void* addr, const std::string& location) const {
+        (void)addr;
+        return location;
+    }
+
+    virtual cudaError_t openIpcMemHandle(void** address,
+                                         cudaIpcMemHandle_t handle,
+                                         const std::string& location,
+                                         int& opened_device) const = 0;
+
+    virtual cudaError_t closeIpcMemHandle(void* address,
+                                          int opened_device) const = 0;
+
+    // Return true when the policy submitted the whole copy group itself.  A
+    // false return asks the shared core to use its CUDA-compatible fallback.
+    // On a handled call, fail_index is count on success, an index when the
+    // backend reports a partial parse failure, or SIZE_MAX for an unknown
+    // failure.  Keeping this hook here lets MUSA use its low-CPU driver batch
+    // API without duplicating the transfer bookkeeping in a second transport.
+    virtual bool submitBatchCopies(const std::vector<void*>& srcs,
+                                   const std::vector<void*>& dsts,
+                                   const std::vector<size_t>& sizes,
+                                   cudaStream_t stream,
+                                   size_t& fail_index) const {
+        (void)srcs;
+        (void)dsts;
+        (void)sizes;
+        (void)stream;
+        (void)fail_index;
+        return false;
+    }
+};
+
 class NvlinkTransport : public Transport {
    public:
     NvlinkTransport();
@@ -43,6 +112,9 @@ class NvlinkTransport : public Transport {
     static void freePinnedLocalMemory(void* addr);
 
    protected:
+    NvlinkTransport(std::shared_ptr<GpuIpcTransportPolicy> policy,
+                    bool use_fabric_mem);
+
     int install(std::string& local_server_name,
                 std::shared_ptr<TransferMetadata> meta,
                 std::shared_ptr<Topology> topo) override;
@@ -51,33 +123,72 @@ class NvlinkTransport : public Transport {
                             const std::string& location, bool remote_accessible,
                             bool update_metadata = true) override;
 
+    // HOST_NUMA: false only removes the local descriptor. Complete cleanup
+    // with true or a batch before releasing the owner. Drain transfers first.
     int unregisterLocalMemory(void* addr, bool update_metadata = true) override;
 
     int registerLocalMemoryBatch(const std::vector<BufferEntry>& buffer_list,
                                  const std::string& location) override;
 
+    // Keep HOST_NUMA owners and their address ranges until the batch succeeds.
     int unregisterLocalMemoryBatch(
         const std::vector<void*>& addr_list) override;
 
     int relocateSharedMemoryAddress(uint64_t& dest_addr, uint64_t length,
                                     uint64_t target_id);
 
-    const char* getName() const override { return "nvlink"; }
+    const char* getName() const override { return policy_->protocol(); }
 
    private:
+    friend class NvlinkTransportTestPeer;
+
     std::atomic_bool running_;
 
     struct OpenedShmEntry {
         void* shm_addr;
         uint64_t length;
+        int device_id{-1};
     };
 
     std::unordered_map<std::pair<uint64_t, uint64_t>, OpenedShmEntry, PairHash>
         remap_entries_;
     RWSpinlock remap_lock_;
     bool use_fabric_mem_;
+    std::shared_ptr<GpuIpcTransportPolicy> policy_;
 
     std::mutex register_mutex_;
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    using AddLocalMemoryBufferOp = std::function<int(const BufferDesc&, bool)>;
+    using RemoveLocalMemoryBufferOp = std::function<int(void*, bool)>;
+    using UpdateLocalSegmentDescOp = std::function<int()>;
+
+    struct HostNumaRegistration {
+        CUmemGenericAllocationHandle handle{};
+        NvlinkHostNumaAllocation::DriverApi api;
+        size_t length = 0;
+        bool registration_succeeded = false;
+        bool handle_owned = false;
+        bool metadata_removed_locally = true;
+        bool metadata_cleanup_complete = true;
+    };
+    std::unordered_map<void*, HostNumaRegistration>
+        host_numa_registration_handles_;
+
+    // A missing result means the range belongs to the legacy path.
+    std::optional<int> registerHostNumaMemoryLocked(
+        void* addr, size_t length, const std::string& location,
+        bool update_metadata, const AddLocalMemoryBufferOp& add_buffer,
+        const RemoveLocalMemoryBufferOp& remove_buffer,
+        const UpdateLocalSegmentDescOp& update_segment);
+    int unregisterHostNumaMemoryBatchLocked(
+        const std::vector<void*>& addr_list,
+        const RemoveLocalMemoryBufferOp& remove_buffer,
+        const UpdateLocalSegmentDescOp& update_segment);
+    int unregisterHostNumaMemoryLocked(
+        void* addr, bool update_metadata,
+        const RemoveLocalMemoryBufferOp& remove_buffer,
+        const UpdateLocalSegmentDescOp& update_segment);
+#endif
 };
 
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/endpoint_store.h b/mooncake-transfer-engine/include/transport/rdma_transport/endpoint_store.h
index f3bd20dd01..2ea3b754b0 100644
--- a/mooncake-transfer-engine/include/transport/rdma_transport/endpoint_store.h
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/endpoint_store.h
@@ -41,7 +41,7 @@ class EndpointStore {
     virtual std::shared_ptr<RdmaEndPoint> getEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr) = 0;
     virtual std::shared_ptr<RdmaEndPoint> insertEndpoint(
-        const std::string &peer_nic_path, RdmaContext *context) = 0;
+        const std::string &peer_nic_path, RdmaContext *context, ibv_cq *cq) = 0;
     virtual int deleteEndpoint(const std::string &peer_nic_path) = 0;
     // Deletes the endpoint matching endpoint_ptr (by pointer identity, under
     // the store lock -- the pointer is never dereferenced, so a stale/freed
@@ -83,7 +83,8 @@ class FIFOEndpointStore : public EndpointStore {
     std::shared_ptr<RdmaEndPoint> getEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr) override;
     std::shared_ptr<RdmaEndPoint> insertEndpoint(
-        const std::string &peer_nic_path, RdmaContext *context) override;
+        const std::string &peer_nic_path, RdmaContext *context,
+        ibv_cq *cq) override;
     int deleteEndpoint(const std::string &peer_nic_path) override;
     int deleteEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr,
@@ -125,7 +126,8 @@ class SIEVEEndpointStore : public EndpointStore {
     std::shared_ptr<RdmaEndPoint> getEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr) override;
     std::shared_ptr<RdmaEndPoint> insertEndpoint(
-        const std::string &peer_nic_path, RdmaContext *context) override;
+        const std::string &peer_nic_path, RdmaContext *context,
+        ibv_cq *cq) override;
     int deleteEndpoint(const std::string &peer_nic_path) override;
     int deleteEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr,
@@ -143,6 +145,11 @@ class SIEVEEndpointStore : public EndpointStore {
     }
 
     void testOnlyInsertWaiting(std::shared_ptr<RdmaEndPoint> ep) override;
+    // Test-only: push a pre-constructed endpoint into the active map so
+    // pointer-identity lookup/delete paths can be exercised without standing up
+    // an RDMA device.
+    void testOnlyInsertEndpoint(const std::string &peer_nic_path,
+                                std::shared_ptr<RdmaEndPoint> ep);
 
    private:
     RWSpinlock endpoint_map_lock_;
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_batch_cache.h b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_batch_cache.h
new file mode 100644
index 0000000000..68dd5a7032
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_batch_cache.h
@@ -0,0 +1,68 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+#pragma once
+
+#include <memory>
+
+#include "buffer_range_index.h"
+#include "memory_location.h"
+#include "transport/rdma_transport/rdma_transport.h"
+
+namespace mooncake {
+// Function-local cache for successful first-attempt selection. The caller
+// keeps the selection policy (local/peer and affinity hint) fixed and must not
+// use this cache on retries. Multi-device and offset-dependent topology retain
+// their original per-request selection. As with the uncached submit path,
+// registrations must remain valid while transfers are in flight.
+class BatchRdmaDeviceCache {
+   public:
+    void invalidate() { snapshot_.reset(); }
+
+    template <typename Resolve>
+    int select(const std::shared_ptr<TransferMetadata::SegmentDesc> &desc,
+               uint64_t addr, size_t length, int &buffer_id, int &device_id,
+               Resolve &&resolve) {
+        if (desc && desc == snapshot_ &&
+            bufferCoversRange(addr_, length_, addr, length)) {
+            buffer_id = buffer_id_;
+            device_id = device_id_;
+            return 0;
+        }
+        snapshot_.reset();
+        buffer_id = -1;
+        device_id = -1;
+        const int rc = resolve();
+        if (rc) return rc;
+        if (!desc || buffer_id < 0 || device_id < 0 ||
+            static_cast<size_t>(buffer_id) >= desc->buffers.size() ||
+            desc->topology.getHcaList().size() != 1 ||
+            desc->buffer_range_index.size() != desc->buffers.size() ||
+            desc->buffer_range_index.overlaps())
+            return rc;
+        const auto &buffer = desc->buffers[buffer_id];
+        if (buffer.name.starts_with(kSegmentsLocationPrefix)) return rc;
+        snapshot_ = desc;
+        addr_ = buffer.addr;
+        length_ = buffer.length;
+        buffer_id_ = buffer_id;
+        device_id_ = device_id;
+        return rc;
+    }
+
+   private:
+    std::shared_ptr<TransferMetadata::SegmentDesc> snapshot_;
+    uint64_t addr_ = 0, length_ = 0;
+    int buffer_id_ = -1, device_id_ = -1;
+};
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_context.h b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_context.h
index 370d6c2660..30ff2f54af 100644
--- a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_context.h
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_context.h
@@ -107,6 +107,8 @@ class RdmaContext {
    public:
     friend class RdmaContextTestPeer;
     friend class WorkerPool;
+    friend class RdmaEndPoint;
+    friend class RdmaTransport;
 
     RdmaContext(RdmaTransport &engine, const std::string &device_name);
 
@@ -131,14 +133,18 @@ class RdmaContext {
     int registerMemoryRegion(void *addr, size_t length, int access,
                              const DmabufExport &exp);
 
-    // Exports a single dma_buf fd for the allocation backing addr. GPU device
+    // Exports a single dma_buf fd covering [addr, addr + length). GPU device
     // memory yields kDmabufReg with a live fd; host memory and the
     // nvidia-peermem path yield kHostReg with no fd. Any fd placed in out.fd
     // MUST be closed by the caller (via closeDmabufExport) AFTER every
     // registerMemoryRegion() call consuming it has returned — each successful
     // registration takes its own reference, so closing earlier would invalidate
     // the fd for the remaining NICs.
-    static int exportDmabuf(void *addr, DmabufExport &out);
+    // `length` is the length of the whole buffer the caller is going to
+    // register (chunked registrations derive their own offset from out.offset),
+    // and is used to guarantee the exported dma_buf really covers that range —
+    // see the VMM note in exportDmabuf().
+    static int exportDmabuf(void *addr, size_t length, DmabufExport &out);
 
     // Closes the fd held by a DmabufExport, if any. Idempotent.
     static void closeDmabufExport(DmabufExport &exp);
@@ -171,8 +177,14 @@ class RdmaContext {
     }
 
    public:
+    bool nativeNotifyEnabled() const { return native_notify_enabled_; }
+
     // EndPoint Management
     std::shared_ptr<RdmaEndPoint> endpoint(const std::string &peer_nic_path);
+    std::shared_ptr<RdmaEndPoint> endpoint(const std::string &peer_nic_path,
+                                           int cq_index);
+    std::shared_ptr<RdmaEndPoint> findEndpoint(
+        const std::string &peer_nic_path);
 
     std::shared_ptr<RdmaEndPoint> getEndpointByPtr(
         const RdmaEndPoint *endpoint_ptr);
@@ -218,7 +230,7 @@ class RdmaContext {
     std::string nicPath() const;
 
    public:
-    uint16_t lid() const { return lid_; }
+    uint32_t lid() const { return lid_; }
 
     std::string gid() const;
 
@@ -260,13 +272,20 @@ class RdmaContext {
 
     int eventFd() const { return event_fd_; }
 
-    ibv_cq *cq();
+    ibv_cq *cq(int cq_index);
 
     std::atomic<int> *cqOutstandingCount(int cq_index) {
         return &cq_list_[cq_index].outstanding;
     }
 
     int cqCount() const { return cq_list_.size(); }
+    int postingThreadForPeer(const std::string &peer_nic_path) const;
+    int cqIndexForPostingThread(int thread_id) const;
+    int cqIndexForPeer(const std::string &peer_nic_path) const;
+    int transferWorkerCount() const { return transfer_worker_count_; }
+    std::unique_lock<std::mutex> lockEndpointLifecycle(
+        const std::string &peer_nic_path) const;
+    std::vector<std::unique_lock<std::mutex>> lockAllEndpointLifecycles() const;
 
     int poll(int num_entries, ibv_wc *wc, int cq_index = 0);
 
@@ -304,7 +323,7 @@ class RdmaContext {
     ibv_comp_channel **comp_channel_ = nullptr;
 
     uint8_t port_ = 0;
-    uint16_t lid_ = 0;
+    uint32_t lid_ = 0;
     int gid_index_ = -1;
     int active_speed_ = -1;
     int active_width_ = 1;
@@ -320,6 +339,17 @@ class RdmaContext {
     std::vector<RdmaCq> cq_list_;
 
     std::shared_ptr<EndpointStore> endpoint_store_;
+    bool native_notify_enabled_ = false;
+    std::mutex notify_mutex_;
+    // One fixed-size notification CQ per device, separate from the data CQs.
+    ibv_cq *notify_cq_ = nullptr;
+    std::unordered_map<uint32_t, std::weak_ptr<RdmaEndPoint>> notify_endpoints_;
+    void registerNotifyQp(uint32_t qp_num,
+                          const std::weak_ptr<RdmaEndPoint> &endpoint);
+    void unregisterNotifyQp(uint32_t qp_num);
+    int pollNotificationCq();
+    void dispatchNotificationCompletion(
+        const ibv_wc &wc, std::vector<TransferMetadata::NotifyDesc> &received);
 
     // Active-connect circuit-breaker (keyed by peer server name).
     ConnectPauseTracker connect_pause_;
@@ -329,7 +359,9 @@ class RdmaContext {
 
     std::atomic<int> next_comp_channel_index_;
     std::atomic<int> next_comp_vector_index_;
-    std::atomic<int> next_cq_list_index_;
+
+    int transfer_worker_count_ = 0;
+    std::vector<std::unique_ptr<std::mutex>> endpoint_lifecycle_locks_;
 
     std::shared_ptr<WorkerPool> worker_pool_;
 
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_endpoint.h b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_endpoint.h
index 255ae8efda..1c91aaffe9 100644
--- a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_endpoint.h
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_endpoint.h
@@ -16,6 +16,9 @@
 #define RDMA_ENDPOINT_H
 
 #include <atomic>
+#include <condition_variable>
+#include <memory>
+#include <mutex>
 #include <queue>
 
 #include "rdma_context.h"
@@ -41,7 +44,7 @@ class RdmaEndPointTestPeer;
 // If the user initiates a disconnect() call or an error is detected internally,
 // the connection is closed and the RdmaEndPoint state is set to UNCONNECTED.
 // The handshake can be restarted at this point.
-class RdmaEndPoint {
+class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
    public:
     enum Status {
         INITIALIZING,
@@ -54,6 +57,9 @@ class RdmaEndPoint {
     };
 
     friend class RdmaEndPointTestPeer;
+    friend class RdmaNotificationTestPeer;
+    friend class RdmaContext;
+    friend class RdmaTransport;
 
    public:
     RdmaEndPoint(RdmaContext &context);
@@ -71,6 +77,7 @@ class RdmaEndPoint {
 
    public:
     void setPeerNicPath(const std::string &peer_nic_path);
+    std::string peerNicPath() const;
 
     int setupConnectionsByActive();
 
@@ -83,6 +90,9 @@ class RdmaEndPoint {
     int setupConnectionsByPassive(const HandShakeDesc &peer_desc,
                                   HandShakeDesc &local_desc);
 
+    int sendNotification(const TransferMetadata::NotifyDesc &notify);
+    bool notificationNeedsReconnect() const;
+
     bool active() const { return active_.load(std::memory_order_acquire); }
 
     void set_active(bool flag) {
@@ -133,6 +143,26 @@ class RdmaEndPoint {
     bool finishDestroy();
 
    private:
+    // Match TENT: fixed capacity and native-endian length-prefixed strings.
+    // Layout: uint32 name_length, name, uint32 message_length, message.
+    static constexpr size_t kNotifySlots = 256;
+    static constexpr size_t kNotifySlotBytes = 65536;
+    static constexpr size_t kNotifyHeaderBytes = 8;
+    static bool notificationFits(const TransferMetadata::NotifyDesc &notify);
+    static size_t encodeNotification(
+        char *slot, const TransferMetadata::NotifyDesc &notify);
+    static bool decodeNotification(const char *slot, size_t bytes,
+                                   TransferMetadata::NotifyDesc &notify);
+    int constructNotification();
+    int connectNotification(const ibv_gid &gid, uint32_t lid, uint32_t peer_qp,
+                            int local_gid_index);
+    uint32_t notificationQpNum() const;
+    int postNotificationReceive(size_t slot);
+    void handleNotificationCompletion(
+        const ibv_wc &wc, std::vector<TransferMetadata::NotifyDesc> &received);
+    void stopNotification();
+    int closeNotification();
+    void describeNotification(HandShakeDesc &desc) const;
     int disconnectUnlocked();
 
     // Resets only pre-connected handshake attempts. Once an endpoint has ever
@@ -177,14 +207,15 @@ class RdmaEndPoint {
 
     std::vector<uint32_t> qpNum() const;
 
-    int doSetupConnection(const std::string &peer_gid, uint16_t peer_lid,
+    int doSetupConnection(const std::string &peer_gid, uint32_t peer_lid,
                           std::vector<uint32_t> peer_qp_num_list,
                           Status connected_status = CONNECTED,
                           std::string *reply_msg = nullptr,
-                          SetupConnectionFailureInfo *failure_info = nullptr);
+                          SetupConnectionFailureInfo *failure_info = nullptr,
+                          uint32_t notify_qp_num = 0);
 
     int doSetupConnection(int qp_index, const ibv_gid &peer_gid,
-                          uint16_t peer_lid, uint32_t peer_qp_num,
+                          uint32_t peer_lid, uint32_t peer_qp_num,
                           int local_gid_index, std::string *reply_msg = nullptr,
                           SetupConnectionFailureInfo *failure_info = nullptr);
 
@@ -197,9 +228,10 @@ class RdmaEndPoint {
     static constexpr uint32_t kWaitExistingHandshakeInitialSleepUs = 50;
     static constexpr uint32_t kWaitExistingHandshakeMaxSleepUs = 2000;
 
-    // Maximum time (in seconds) to wait for outstanding WRs to drain in
-    // finishDestroy before forcing QP destruction. This guards against
-    // ibv_modify_qp-to-ERR failures that prevent WR flushing.
+    // Maximum time (in seconds) to wait for outstanding WRs to drain before
+    // treating the endpoint as leaked. Timed-out endpoints stay in the
+    // EndpointStore waiting list so stale in-flight references cannot turn
+    // into UAF.
     static constexpr double kFinishDestroyTimeoutSec = 30.0;
 
     // Maximum number of deconstructLocked retries in finishDestroy before
@@ -210,8 +242,30 @@ class RdmaEndPoint {
     RdmaContext &context_;
     std::atomic<Status> status_;
 
-    RWSpinlock lock_;
+    mutable RWSpinlock lock_;
     std::vector<ibv_qp *> qp_list_;
+    uint64_t qp_generation_;
+    // Protected by its own mutex so send-slot waits never hold lock_.
+    struct NotifyState {
+        int fail(int code, bool reconnect = false) {
+            if (!error) error = code;
+            reconnect_needed = reconnect_needed || reconnect;
+            connected = false;
+            cv.notify_all();
+            return error;
+        }
+        mutable std::mutex mutex;
+        std::condition_variable cv;
+        ibv_qp *qp = nullptr;
+        ibv_mr *send_mr = nullptr, *recv_mr = nullptr;
+        std::unique_ptr<char[]> send_buffer, recv_buffer;
+        uint64_t next_send = 0;
+        size_t pending = 0;
+        uint32_t peer_qp = 0, inline_bytes = 0;
+        int error = 0;
+        bool enabled = false, connected = false, reconnect_needed = false;
+    } notify_;
+    uint32_t peer_notify_qp_num_ = 0;
 
     std::string peer_nic_path_;
     std::vector<uint32_t> peer_qp_num_list_;
@@ -224,8 +278,10 @@ class RdmaEndPoint {
     size_t max_inline_bytes_;
 
     std::atomic<bool> active_;
+    ibv_cq *cq_;
     std::atomic<int> *cq_outstanding_;
     std::atomic<uint64_t> inactive_time_;
+    bool finish_destroy_timeout_logged_ = false;
     int finish_destroy_retries_ = 0;
 };
 
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_transport.h b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_transport.h
index d5d8b3b5e5..b4f1eec00f 100644
--- a/mooncake-transfer-engine/include/transport/rdma_transport/rdma_transport.h
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/rdma_transport.h
@@ -23,6 +23,8 @@
 #include <memory>
 #include <mutex>
 #include <string>
+#include <thread>
+#include <string_view>
 #include <unordered_map>
 #include <unordered_set>
 #include <vector>
@@ -43,6 +45,7 @@ class RdmaTransport : public Transport {
     friend class RdmaContext;
     friend class RdmaEndPoint;
     friend class RdmaTransportTestPeer;
+    friend class RdmaNotificationTestPeer;
     friend class WorkerPool;
 
    public:
@@ -61,6 +64,11 @@ class RdmaTransport : public Transport {
 
     const char *getName() const override { return "rdma"; }
 
+    // Ordinary RDMA's native notification channel. Success means the SEND
+    // was posted locally, not that the remote application consumed it.
+    int sendNativeNotify(const std::string &peer_server_name,
+                         const TransferMetadata::NotifyDesc &notify);
+
     int registerLocalMemory(void *addr, size_t length,
                             const std::string &location, bool remote_accessible,
                             bool update_metadata) override;
@@ -92,6 +100,8 @@ class RdmaTransport : public Transport {
     Status submitTransferTask(
         const std::vector<TransferTask *> &task_list) override;
 
+    bool supportsGroupedScatter() const override { return true; }
+
     Status getTransferStatus(BatchID batch_id,
                              std::vector<TransferStatus> &status);
 
@@ -103,18 +113,18 @@ class RdmaTransport : public Transport {
    private:
     int allocateLocalSegmentID();
 
-    int refreshLocalDeviceDesc(const std::string &device_name, uint16_t lid,
+    int refreshLocalDeviceDesc(const std::string &device_name, uint32_t lid,
                                const std::string &gid);
 
     int preTouchMemory(void *addr, size_t length);
 
    public:
-    int onSetupRdmaConnections(const HandShakeDesc &peer_desc,
-                               HandShakeDesc &local_desc);
+    virtual int onSetupRdmaConnections(const HandShakeDesc &peer_desc,
+                                       HandShakeDesc &local_desc);
 
-    int sendHandshake(const std::string &peer_server_name,
-                      const HandShakeDesc &local_desc,
-                      HandShakeDesc &peer_desc) {
+    virtual int sendHandshake(const std::string &peer_server_name,
+                              const HandShakeDesc &local_desc,
+                              HandShakeDesc &peer_desc) {
         return metadata_->sendHandshake(peer_server_name, local_desc,
                                         peer_desc);
     }
@@ -124,16 +134,22 @@ class RdmaTransport : public Transport {
 
     int startHandshakeDaemon(std::string &local_server_name);
 
+    void notifyWorkerThread();
+
    public:
     static int selectDevice(SegmentDesc *desc, uint64_t offset, size_t length,
-                            int &buffer_id, int &device_id, int retry_cnt = 0);
+                            int &buffer_id, int &device_id, int retry_cnt = 0,
+                            int hint_buffer_id = -1, int hint_device_id = -1);
     static int selectDevice(SegmentDesc *desc, uint64_t offset, size_t length,
                             std::string_view hint, int &buffer_id,
-                            int &device_id, int retry_cnt = 0);
+                            int &device_id, int retry_cnt = 0,
+                            int hint_buffer_id = -1, int hint_device_id = -1);
     static int selectDeviceByLocalHca(SegmentDesc *desc, uint64_t offset,
                                       size_t length, std::string_view local_hca,
                                       int &buffer_id, int &device_id,
-                                      int retry_cnt = 0);
+                                      int retry_cnt = 0,
+                                      int hint_buffer_id = -1,
+                                      int hint_device_id = -1);
 
     const std::vector<std::shared_ptr<RdmaContext>> &getContextList() const {
         return context_list_;
@@ -141,6 +157,8 @@ class RdmaTransport : public Transport {
 
    private:
     std::vector<std::shared_ptr<RdmaContext>> context_list_;
+    std::atomic<bool> notify_running_{false};
+    std::thread notify_worker_;
     std::shared_ptr<Topology> local_topology_;
     // When MC_RDMA_BIND_ADDRESS is set in a dual-NIC environment,
     // rdma_server_name_ holds the RDMA-reachable address (e.g.
diff --git a/mooncake-transfer-engine/include/transport/rdma_transport/worker_pool.h b/mooncake-transfer-engine/include/transport/rdma_transport/worker_pool.h
index 3ce036217b..aeb6b287b8 100644
--- a/mooncake-transfer-engine/include/transport/rdma_transport/worker_pool.h
+++ b/mooncake-transfer-engine/include/transport/rdma_transport/worker_pool.h
@@ -15,8 +15,13 @@
 #ifndef WORKER_H
 #define WORKER_H
 
-#include <queue>
+#include <atomic>
+#include <condition_variable>
+#include <mutex>
+#include <thread>
+#include <unordered_map>
 #include <unordered_set>
+#include <vector>
 
 #include "config.h"
 #include "rdma_context.h"
@@ -41,7 +46,6 @@ class WorkerPool {
 
    private:
     using SliceList = std::vector<Transport::Slice *>;
-    const static int kShardCount = 8;
 
     // Enqueue slices that were prepared by another WorkerPool. Used for
     // local-NIC failure handoff: the original worker keeps the remote path
@@ -49,15 +53,22 @@ class WorkerPool {
     // worker queue.
     int submitPreparedPostSend(
         const std::vector<Transport::Slice *> &slice_list);
-    void enqueuePreparedSlices(SliceList (&slice_list_map)[kShardCount],
+    void enqueuePreparedSlices(const SliceList &slice_list,
                                uint64_t submitted_slice_count);
+    void enqueueSliceToOwner(Transport::Slice *slice);
+    void enqueueSlicesToOwner(int owner_thread, const SliceList &slices);
+    int postingThreadForPeer(const std::string &peer_nic_path) const;
+    int cqIndexForPostingThread(int thread_id) const;
 
     void performPostSend(int thread_id);
 
-    void performPollCq(int thread_id);
+    int performPollCq(int thread_id, bool defer_local_redispatch = false);
+    void processCompletions(int thread_id, const std::vector<ibv_wc> &wc_list,
+                            bool defer_local_redispatch = false);
 
     void redispatch(std::vector<Transport::Slice *> &slice_list, int thread_id,
-                    bool handoff_to_local_worker = false);
+                    bool handoff_to_local_worker = false,
+                    bool defer_local_redispatch = false);
 
     void transferWorker(int thread_id);
 
@@ -72,6 +83,7 @@ class WorkerPool {
     struct RailState {
         int error_count = 0;
         uint64_t pause_until_ns = 0;  // Timestamp (ns) when pause expires
+        uint64_t last_error_ns = 0;   // Timestamp (ns) of the last error
     };
 
     void markRailFailed(const std::string &peer_nic_path,
@@ -99,36 +111,20 @@ class WorkerPool {
 
     bool tryHandoffToAnotherLocalWorker(Transport::Slice *slice);
 
-    // Context-level health tracking for catastrophic hardware failure.
-    // When all rails through a local RNIC are unavailable, increment the
-    // failure counter. Reset on any success. Mark context inactive after
-    // consecutive failures exceed threshold.
-    bool contextHealthy() const {
-        return context_failure_count_.load(std::memory_order_relaxed) <
-               kContextFailureThreshold;
-    }
-    void markContextSuccess() {
-        context_failure_count_.store(0, std::memory_order_relaxed);
-    }
-    bool markContextFailure() {
-        auto failure_count =
-            context_failure_count_.fetch_add(1, std::memory_order_relaxed) + 1;
-        if (failure_count >= kContextFailureThreshold) {
-            if (context_.active()) {
-                LOG(WARNING)
-                    << "All rails failed for context " << context_.deviceName()
-                    << " for " << failure_count
-                    << " consecutive attempts, marking inactive";
-                context_.set_active(false);
-                return true;
-            }
-        }
-        return false;
-    }
+    // Only direct local completion errors charge the context breaker.
+    // Submit-side all-rails-unavailable failures remain peer/rail scoped.
+    bool markLocalContextFailure();
+    void markContextSuccess();
+    bool tryReactivateContext(uint64_t now_ns);
+    void maybeReactivateContext();
+    // Serialize breaker transitions with physical-event recovery so a late
+    // completion cannot arm TTL recovery after a fatal event.
+    void resetContextBreaker(bool context_active);
 
    private:
     RdmaContext &context_;
     const int numa_socket_id_;
+    const int worker_count_;
 
     std::vector<std::thread> worker_thread_;
     std::atomic<bool> workers_running_;
@@ -150,12 +146,10 @@ class WorkerPool {
     std::mutex cond_mutex_;
     std::condition_variable cond_var_;
 
-    std::unordered_map<std::string, SliceList> slice_queue_[kShardCount];
-    std::atomic<uint64_t> slice_queue_count_[kShardCount];
-    TicketLock slice_queue_lock_[kShardCount];
-
     std::vector<std::unordered_map<std::string, SliceList>>
         collective_slice_queue_;
+    std::vector<std::unordered_map<std::string, SliceList>> worker_slice_queue_;
+    std::vector<std::mutex> worker_slice_queue_lock_;
 
     std::atomic<uint64_t> submitted_slice_count_, processed_slice_count_;
     std::atomic<uint64_t> recovery_activate_after_ns_{0};
@@ -163,16 +157,26 @@ class WorkerPool {
     // Rail state management: peer_nic_path -> RailState
     std::unordered_map<std::string, RailState> rail_states_;
     std::mutex rail_state_lock_;
+    // Number of rails with pause_until_ns in the future. The submit hot path
+    // skips rail_state_lock_ while this is zero. Expired pauses are cleared on
+    // the next locked isRailAvailable() for any path, not only the expired one.
+    std::atomic<int> paused_rail_count_{0};
 
     // Rail monitor configuration
     const static int kRailErrorThreshold = 5;  // Errors before pause
+    // Errors further apart than this are not consecutive, so error_count is
+    // restarted. Without it a long-lived process accumulates isolated failures
+    // until an otherwise healthy rail is paused.
+    const static uint64_t kRailErrorWindowNs = 5000000000ull;  // 5 seconds
     const static uint64_t kContextRecoveryDelayNs =
         30000000000ull;  // 30 seconds before a recovered local RNIC is reused
 
-    // Context-level health tracking
+    // Local-completion context breaker. Protected by context_state_lock_ so
+    // fatal events, GID recovery and TTL recovery have one state owner.
+    std::mutex context_state_lock_;
     std::atomic<int> context_failure_count_{0};
-    const static int kContextFailureThreshold =
-        32;  // consecutive all-rails-failed
+    uint64_t breaker_reactivate_after_ns_{0};
+    static constexpr int kLocalCompletionFailureThreshold = 32;
 };
 }  // namespace mooncake
 
diff --git a/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_channel.h b/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_channel.h
new file mode 100644
index 0000000000..3800e4835d
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_channel.h
@@ -0,0 +1,142 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef RDMA_CTRL_CHANNEL_H_
+#define RDMA_CTRL_CHANNEL_H_
+
+#include <infiniband/verbs.h>
+
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+#include "transfer_metadata.h"
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+namespace mooncake {
+
+class RdmaContext;
+class RdmaTwoSidedTransport;
+
+// Per-peer RDMA control channel: one RC QP dedicated to two-sided SEND/RECV
+// typed CtrlFrames. Owned by RdmaTwoSidedTransport; not part of EndpointStore.
+class CtrlChannel {
+   public:
+    using NotifyDesc = TransferMetadata::NotifyDesc;
+    using HandShakeDesc = TransferMetadata::HandShakeDesc;
+
+    CtrlChannel(RdmaTwoSidedTransport &transport, RdmaContext &context,
+                std::string peer_server_name);
+    ~CtrlChannel();
+
+    CtrlChannel(const CtrlChannel &) = delete;
+    CtrlChannel &operator=(const CtrlChannel &) = delete;
+
+    // Allocate QP/CQ/buffers and move QP to INIT. Does not connect.
+    int construct();
+
+    // Active: exchange ctrl handshake and bring QP to RTS.
+    int connectActive();
+
+    // Passive: complete ctrl handshake against peer_desc; fill local_desc.
+    int acceptPassive(const HandShakeDesc &peer_desc,
+                      HandShakeDesc &local_desc);
+
+    bool connected() const {
+        return connected_.load(std::memory_order_acquire);
+    }
+
+    uint32_t notifyQpNum() const { return qp_ ? qp_->qp_num : 0; }
+    uint16_t notifyRqDepth() const {
+        return static_cast<uint16_t>(recv_count_);
+    }
+
+    const std::string &peerServerName() const { return peer_server_name_; }
+    RdmaContext &context() const { return context_; }
+
+    // Fire-and-forget: encode and post a typed CtrlFrame SEND. Returns 0 once
+    // the frame is enqueued on the QP (or an error if it cannot be enqueued).
+    // Delivery is confirmed asynchronously by the SEND completion: a failed WC
+    // marks the channel unconnected, and the next ensureCtrlChannel() reclaims
+    // it and (if enabled) falls back to OOB notify. A 0 return therefore means
+    // "queued", not "delivered".
+    int sendCtrlFrame(const CtrlFrame &frame);
+
+    // Compatibility wrapper: encode NotifyDesc as NOTIFY_COMPAT frame. Shares
+    // the fire-and-forget delivery semantics of sendCtrlFrame().
+    int sendNotify(const NotifyDesc &notify);
+
+    // Poll notify CQ; dispatch inbound frames via transport callbacks.
+    // Returns number of WC processed.
+    int pollCompletions(int max_entries = 16);
+
+    void disconnect();
+
+   private:
+    int createResources();
+    // IB teardown only. Caller must hold resource_mutex_ (or be disconnect(),
+    // which acquires it). Must not acquire send_mutex_.
+    void releaseIbResources();
+    void destroyResources();
+    int postRecv(size_t idx);
+    int repostAllRecvs();
+    int connectQp(const std::string &peer_gid, uint32_t peer_lid,
+                  uint32_t peer_qp_num);
+    void dispatchRecvPayload(const uint8_t *data, size_t byte_len);
+    void handleSendComplete();
+    void handleRecvComplete(const ibv_wc &wc);
+    // Shared CQ drain for worker poll and send-path opportunistic poll.
+    // Returns successfully handled SEND/RECV count, or <0 on poll failure.
+    int drainCompletions(int max_entries, bool log_poll_error);
+    // Drain SEND (and any stolen RECV) WCs without blocking on send slots.
+    int pollSendCompletions(int max_entries = 16);
+    void fillLocalDesc(HandShakeDesc &local_desc) const;
+    int postSessionOpen();
+
+    RdmaTwoSidedTransport &transport_;
+    RdmaContext &context_;
+    std::string peer_server_name_;
+
+    ibv_cq *cq_ = nullptr;
+    ibv_qp *qp_ = nullptr;
+    ibv_mr *send_mr_ = nullptr;
+    std::vector<ibv_mr *> recv_mrs_;
+    std::vector<char> send_buffer_;
+    std::vector<std::vector<char>> recv_buffers_;
+
+    size_t recv_count_ = 0;
+    size_t buffer_size_ = 0;
+    size_t max_pending_sends_ = 0;
+
+    // send_mutex_ guards SQ slot accounting (pending_sends_, send_wr_id_).
+    // resource_mutex_ guards qp_/cq_/MRs. Nested order, when both are held,
+    // is send_mutex_ then resource_mutex_. disconnect() does not nest them:
+    // it wakes send waiters, drops send_mutex_, then tears down IB resources.
+    std::mutex send_mutex_;
+    std::condition_variable send_cv_;
+    size_t pending_sends_ = 0;
+    uint64_t send_wr_id_ = 0;
+    uint64_t next_frame_seq_ = 1;
+
+    std::mutex resource_mutex_;
+    std::atomic<bool> connected_{false};
+};
+
+}  // namespace mooncake
+
+#endif  // RDMA_CTRL_CHANNEL_H_
diff --git a/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_frame.h b/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_frame.h
new file mode 100644
index 0000000000..8acfb29cc9
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/rdma_twosided/ctrl_frame.h
@@ -0,0 +1,126 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef RDMA_CTRL_FRAME_H_
+#define RDMA_CTRL_FRAME_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "transfer_metadata.h"
+
+namespace mooncake {
+
+// Wire header (little-endian on the wire, host endian locally):
+// | magic:u32 | ver:u8 | type:u8 | flags:u16 | session:u64 | epoch:u64 |
+// | seq:u64 | ack_seq:u64 | payload_len:u32 | payload... |
+constexpr uint32_t kCtrlFrameMagic = 0x434B434Du;  // 'MCKC' LE
+// Wire compatibility: only version 1 is accepted. Unknown versions are
+// rejected (no silent forward compatibility).
+constexpr uint8_t kCtrlFrameVersion = 1;
+constexpr size_t kCtrlFrameHeaderSize = 44;
+
+enum class CtrlFrameType : uint8_t {
+    CREDIT_GRANT = 1,
+    CREDIT_PROGRESS = 2,
+    CREDIT_REQUEST = 3,
+    DATA_ACK = 4,
+    SESSION_OPEN = 5,
+    SESSION_CLOSE = 6,
+    FENCE = 7,
+    DRAIN_ACK = 8,
+    CTRL_ACK = 9,
+    NOTIFY_COMPAT = 10,
+};
+
+enum class CtrlFrameFlags : uint16_t {
+    None = 0,
+    NeedsAck = 1 << 0,
+};
+
+// Bits allowed in CtrlFrame::flags for version 1. Any other bit is rejected.
+constexpr uint16_t kCtrlFrameKnownFlagsMask =
+    static_cast<uint16_t>(CtrlFrameFlags::NeedsAck);
+
+inline bool isKnownCtrlFrameType(uint8_t type) {
+    return type >= static_cast<uint8_t>(CtrlFrameType::CREDIT_GRANT) &&
+           type <= static_cast<uint8_t>(CtrlFrameType::NOTIFY_COMPAT);
+}
+
+enum class CreditResource : uint16_t {
+    DataBytes = 1,
+    RequestSlots = 2,
+    BounceBytes = 3,
+    BounceSlots = 4,
+};
+
+struct CreditAmount {
+    CreditResource resource = CreditResource::DataBytes;
+    uint64_t grant_total = 0;
+};
+
+struct DataAckEntry {
+    uint64_t task_id = 0;
+    uint64_t acked_bytes = 0;
+};
+
+struct CtrlFrame {
+    uint8_t version = kCtrlFrameVersion;
+    CtrlFrameType type = CtrlFrameType::NOTIFY_COMPAT;
+    uint16_t flags = 0;
+    uint64_t session = 0;
+    uint64_t epoch = 0;
+    uint64_t seq = 0;
+    uint64_t ack_seq = 0;
+    std::vector<uint8_t> payload;
+};
+
+// Payload helpers -----------------------------------------------------------
+
+int encodeNotifyCompatPayload(const TransferMetadata::NotifyDesc &notify,
+                              std::vector<uint8_t> &out);
+int decodeNotifyCompatPayload(const uint8_t *data, size_t len,
+                              TransferMetadata::NotifyDesc &notify);
+
+int encodeCreditGrantPayload(const std::vector<CreditAmount> &grants,
+                             std::vector<uint8_t> &out);
+int decodeCreditGrantPayload(const uint8_t *data, size_t len,
+                             std::vector<CreditAmount> &grants);
+
+int encodeDataAckPayload(const std::vector<DataAckEntry> &acks,
+                         std::vector<uint8_t> &out);
+int decodeDataAckPayload(const uint8_t *data, size_t len,
+                         std::vector<DataAckEntry> &acks);
+
+// SESSION_OPEN payload: bounce_slots:u32 | bounce_slot_size:u32
+int encodeSessionOpenPayload(uint32_t bounce_slots, uint32_t bounce_slot_size,
+                             std::vector<uint8_t> &out);
+int decodeSessionOpenPayload(const uint8_t *data, size_t len,
+                             uint32_t &bounce_slots,
+                             uint32_t &bounce_slot_size);
+
+// Full frame ---------------------------------------------------------------
+
+bool isCtrlFrameMagic(const uint8_t *data, size_t len);
+
+// Encode frame into out. Returns 0 on success.
+int encodeCtrlFrame(const CtrlFrame &frame, std::vector<uint8_t> &out);
+
+// Decode frame from buffer. Returns 0 on success.
+int decodeCtrlFrame(const uint8_t *data, size_t len, CtrlFrame &frame);
+
+}  // namespace mooncake
+
+#endif  // RDMA_CTRL_FRAME_H_
diff --git a/mooncake-transfer-engine/include/transport/rdma_twosided/rdma_twosided_transport.h b/mooncake-transfer-engine/include/transport/rdma_twosided/rdma_twosided_transport.h
new file mode 100644
index 0000000000..d82280bbf2
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/rdma_twosided/rdma_twosided_transport.h
@@ -0,0 +1,119 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef RDMA_TWOSIDED_TRANSPORT_H_
+#define RDMA_TWOSIDED_TRANSPORT_H_
+
+#include <atomic>
+#include <condition_variable>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <unordered_map>
+
+#include "transport/rdma_transport/rdma_transport.h"
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+namespace mooncake {
+
+class CtrlChannel;
+
+// RDMA transport with a dedicated CtrlChannel for typed notify frames.
+// One-sided data path is inherited from RdmaTransport; install name is
+// "rdma_twosided" (mutually exclusive with classic "rdma" in MultiTransport).
+class RdmaTwoSidedTransport : public RdmaTransport {
+    friend class CtrlChannel;
+
+   public:
+    using NotifyDesc = TransferMetadata::NotifyDesc;
+    using HandShakeDesc = TransferMetadata::HandShakeDesc;
+
+    RdmaTwoSidedTransport();
+    ~RdmaTwoSidedTransport() override;
+
+    int install(std::string &local_server_name,
+                std::shared_ptr<TransferMetadata> meta,
+                std::shared_ptr<Topology> topo) override;
+
+    const char *getName() const override { return "rdma_twosided"; }
+
+    int onSetupRdmaConnections(const HandShakeDesc &peer_desc,
+                               HandShakeDesc &local_desc) override;
+
+    int sendRdmaNotify(const std::string &peer_server_name,
+                       const NotifyDesc &notify);
+
+    void onCtrlNotifyReceived(const NotifyDesc &notify);
+    void onCtrlFrameReceived(const std::string &peer_server_name,
+                             const CtrlFrame &frame);
+
+    uint64_t localCtrlSessionId() const { return local_ctrl_session_id_; }
+
+   private:
+    int onSetupCtrlChannel(const HandShakeDesc &peer_desc,
+                           HandShakeDesc &local_desc);
+    std::shared_ptr<CtrlChannel> ensureCtrlChannel(
+        const std::string &peer_server_name);
+
+    // RAII publisher for one connect attempt. On construction it installs the
+    // placeholder entry and marks the peer as having a connect in flight; on
+    // destruction it always retracts the marker and wakes waiters, and drops
+    // the placeholder unless markSuccess() was called. Callers must hold
+    // ctrl_mutex_ for the whole lifetime of the scope, so a blocking handshake
+    // has to be wrapped in an UnlockGuard rather than releasing the lock by
+    // hand.
+    class ConnectScope {
+       public:
+        ConnectScope(RdmaTwoSidedTransport &transport, std::string peer,
+                     std::shared_ptr<CtrlChannel> channel);
+        ~ConnectScope();
+
+        ConnectScope(const ConnectScope &) = delete;
+        ConnectScope &operator=(const ConnectScope &) = delete;
+
+        void markSuccess() { success_ = true; }
+
+       private:
+        RdmaTwoSidedTransport &transport_;
+        std::string peer_;
+        std::shared_ptr<CtrlChannel> channel_;
+        bool success_ = false;
+    };
+
+    void startCtrlWorker();
+    void stopCtrlWorker();
+    void ctrlWorkerLoop();
+
+    std::mutex ctrl_mutex_;
+    std::condition_variable ctrl_cv_;
+    std::unordered_map<std::string, std::shared_ptr<CtrlChannel>>
+        ctrl_channels_;
+    // Peers with a connect handshake in flight. Only such peers are worth
+    // waiting for: an entry in ctrl_channels_ that is not connected and not
+    // listed here is a dead channel, which the next caller reclaims instead of
+    // waiting for a wakeup that never comes. Refcounted because an active and
+    // a passive connect to the same peer can overlap.
+    std::unordered_map<std::string, int> ctrl_connecting_;
+    // Set once by stopCtrlWorker() to release waiters during shutdown.
+    // Guarded by ctrl_mutex_.
+    bool ctrl_stopping_ = false;
+    std::thread ctrl_worker_;
+    std::atomic<bool> ctrl_worker_running_{false};
+    uint64_t local_ctrl_session_id_ = 0;
+};
+
+}  // namespace mooncake
+
+#endif  // RDMA_TWOSIDED_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/include/transport/rdma_twosided/sender_credit.h b/mooncake-transfer-engine/include/transport/rdma_twosided/sender_credit.h
new file mode 100644
index 0000000000..fe5cc8efab
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/rdma_twosided/sender_credit.h
@@ -0,0 +1,101 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef RDMA_SENDER_CREDIT_H_
+#define RDMA_SENDER_CREDIT_H_
+
+#include <array>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+namespace mooncake {
+
+// Sender-side credit ledger keyed by (peer, session). Every mutator/query that
+// touches a session entry takes an epoch and rejects mismatches so stale work
+// from a prior generation cannot consume or roll back the new epoch's credits.
+// Cumulative grants; tryReserve fails with ERR_TOO_MANY_REQUESTS when short.
+class SenderCreditLedger {
+   public:
+    explicit SenderCreditLedger(size_t max_entries = 1024)
+        : max_entries_(max_entries) {}
+
+    int activate(const std::string &peer, uint64_t session, uint64_t epoch);
+    int deactivate(const std::string &peer, uint64_t session, uint64_t epoch);
+
+    // Apply cumulative CREDIT_GRANT. disposition: 0=applied, 1=dup/old, 2=gap.
+    int applyGrant(const std::string &peer, uint64_t session, uint64_t epoch,
+                   uint64_t seq, const std::vector<CreditAmount> &grants,
+                   int &disposition);
+
+    int tryReserve(
+        const std::string &peer, uint64_t session, uint64_t epoch,
+        const std::vector<std::pair<CreditResource, uint64_t>> &charge);
+    int rollbackReservation(
+        const std::string &peer, uint64_t session, uint64_t epoch,
+        const std::vector<std::pair<CreditResource, uint64_t>> &charge);
+
+    int available(const std::string &peer, uint64_t session, uint64_t epoch,
+                  CreditResource resource, uint64_t &out) const;
+
+    // Sum available units of `resource` across all sessions for peer.
+    uint64_t availableForPeer(const std::string &peer,
+                              CreditResource resource) const;
+
+    bool hasPeer(const std::string &peer) const;
+
+   private:
+    static constexpr size_t kResourceCount = 4;
+
+    struct Key {
+        std::string peer;
+        uint64_t session = 0;
+        bool operator==(const Key &o) const {
+            return session == o.session && peer == o.peer;
+        }
+    };
+    struct KeyHash {
+        size_t operator()(const Key &k) const noexcept {
+            size_t h = std::hash<std::string>{}(k.peer);
+            h ^= std::hash<uint64_t>{}(k.session) + 0x9e3779b97f4a7c15ULL +
+                 (h << 6) + (h >> 2);
+            return h;
+        }
+    };
+    struct Entry {
+        uint64_t epoch = 0;
+        uint64_t last_sequence = 0;
+        bool has_update = false;
+        std::array<uint64_t, kResourceCount> grants{};
+        std::array<uint64_t, kResourceCount> consumed{};
+    };
+
+    static int resourceIndex(CreditResource r, size_t &idx);
+    static int normalize(
+        const std::vector<std::pair<CreditResource, uint64_t>> &charge,
+        std::array<uint64_t, kResourceCount> &out);
+
+    mutable std::mutex mutex_;
+    const size_t max_entries_;
+    std::unordered_map<Key, Entry, KeyHash> entries_;
+};
+
+}  // namespace mooncake
+
+#endif  // RDMA_SENDER_CREDIT_H_
diff --git a/mooncake-transfer-engine/include/transport/shm_transport/shm_transport.h b/mooncake-transfer-engine/include/transport/shm_transport/shm_transport.h
new file mode 100644
index 0000000000..87af9fbff2
--- /dev/null
+++ b/mooncake-transfer-engine/include/transport/shm_transport/shm_transport.h
@@ -0,0 +1,202 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef SHM_TRANSPORT_H_
+#define SHM_TRANSPORT_H_
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "common.h"
+#include "transfer_metadata.h"
+#include "transport/transport.h"
+
+namespace mooncake {
+
+class ShmTransportTestPeer;
+
+// POSIX shm_open requires a name that begins with '/'. The object itself is
+// still "mooncake_*" so routing can distinguish it from GPU IPC blobs.
+// Hugetlbfs exports use absolute paths such as /dev/hugepages/mooncake_*.
+inline constexpr char kPosixShmNamePrefix[] = "/mooncake_";
+
+inline bool isPosixShmName(const std::string& name) {
+    std::string_view key = name;
+    // Basename so /dev/hugepages/mooncake_* matches as well as /mooncake_*.
+    const auto slash = key.rfind('/');
+    if (slash != std::string_view::npos) key.remove_prefix(slash + 1);
+    constexpr std::string_view bare = "mooncake_";
+    return key.size() > bare.size() && key.substr(0, bare.size()) == bare;
+}
+
+inline bool pathHasDotDotComponent(const std::string& path) {
+    std::string_view rest = path;
+    while (!rest.empty()) {
+        if (rest.front() == '/') {
+            rest.remove_prefix(1);
+            continue;
+        }
+        const auto slash = rest.find('/');
+        const auto part = rest.substr(0, slash);
+        if (part == "..") return true;
+        if (slash == std::string_view::npos) break;
+        rest.remove_prefix(slash);
+    }
+    return false;
+}
+
+// Absolute filesystem path (hugetlbfs), not a POSIX shm object "/mooncake_...".
+// Rejects ".." so a poisoned name like /dev/hugepages/../../tmp/mooncake_x
+// is not treated as a valid export path.
+inline bool isFilesystemShmPath(const std::string& name) {
+    return name.size() > 1 && name.front() == '/' &&
+           name.find('/', 1) != std::string::npos &&
+           !pathHasDotDotComponent(name);
+}
+
+class ShmTransport : public Transport {
+   public:
+    ShmTransport();
+
+    ~ShmTransport() override;
+
+    Status submitTransfer(BatchID batch_id,
+                          const std::vector<TransferRequest>& entries) override;
+
+    Status submitTransferTask(
+        const std::vector<TransferTask*>& task_list) override;
+
+    Status getTransferStatus(BatchID batch_id, size_t task_id,
+                             TransferStatus& status) override;
+
+    void* allocateSharedMemory(size_t length);
+    void* allocateSharedMemory(size_t length, const SharedMemoryOptions& opt);
+
+    // Unlinks the POSIX or hugetlbfs object. SIGKILL skips this; leftovers
+    // are documented on SharedMemoryOptions.
+    int freeSharedMemory(void* addr);
+
+    bool getShmName(void* addr, std::string* name) const;
+
+   private:
+    struct OpenedShmEntry {
+        void* shm_addr = nullptr;
+        uint64_t length = 0;
+        std::string shm_name;
+        std::atomic<uint32_t> pin_count{0};
+        std::atomic<bool> stale{false};
+    };
+
+   public:
+    // Holds a relocate-cache mmap until memcpy finishes so prune/cap cannot
+    // munmap it out from under an in-flight copy.
+    class MappingPin {
+       public:
+        MappingPin() = default;
+        MappingPin(MappingPin&& other) noexcept;
+        MappingPin& operator=(MappingPin&& other) noexcept;
+        ~MappingPin();
+        MappingPin(const MappingPin&) = delete;
+        MappingPin& operator=(const MappingPin&) = delete;
+        void reset();
+        explicit operator bool() const { return static_cast<bool>(entry_); }
+
+       private:
+        friend class ShmTransport;
+        MappingPin(ShmTransport* transport,
+                   std::shared_ptr<OpenedShmEntry> entry);
+        ShmTransport* transport_ = nullptr;
+        std::shared_ptr<OpenedShmEntry> entry_;
+    };
+
+   private:
+    int install(std::string& local_server_name,
+                std::shared_ptr<TransferMetadata> meta,
+                std::shared_ptr<Topology> topo) override;
+
+    int registerLocalMemory(void* addr, size_t length,
+                            const std::string& location, bool remote_accessible,
+                            bool update_metadata) override;
+
+    int unregisterLocalMemory(void* addr, bool update_metadata) override;
+
+    int registerLocalMemoryBatch(
+        const std::vector<Transport::BufferEntry>& buffer_list,
+        const std::string& location) override;
+
+    int unregisterLocalMemoryBatch(
+        const std::vector<void*>& addr_list) override;
+
+    const char* getName() const override { return "shm"; }
+
+    friend class ShmTransportTestPeer;
+
+    struct AllocatedShmEntry {
+        std::string name;
+        size_t length = 0;
+    };
+
+    using RelocateMap =
+        std::unordered_map<uint64_t, std::shared_ptr<OpenedShmEntry>>;
+    using PendingUnmap = std::vector<std::pair<void*, uint64_t>>;
+
+    void* createSharedMemory(const std::string& path, size_t size,
+                             int* error = nullptr, bool populate = false);
+    static void unlinkShmEntry(const AllocatedShmEntry& entry);
+
+    Status relocateSharedMemoryAddress(uint64_t& dest_addr, uint64_t length,
+                                       uint64_t target_id,
+                                       MappingPin* pin = nullptr);
+
+    static bool tryResolve(const RelocateMap& relocate_map, uint64_t& dest_addr,
+                           uint64_t length, const std::string& shm_name,
+                           std::shared_ptr<OpenedShmEntry>* out_entry);
+
+    static void queueUnmap(OpenedShmEntry& entry, PendingUnmap* pending);
+    static void unpinLocked(OpenedShmEntry& entry, PendingUnmap* pending);
+    static void flushUnmaps(PendingUnmap& pending);
+    void pruneAndCapLocked(RelocateMap& mappings,
+                           const TransferMetadata::SegmentDesc& desc,
+                           uint64_t keep_addr, PendingUnmap* pending);
+    void pruneIfNeeded(SegmentID target_id,
+                       const TransferMetadata::SegmentDesc& desc,
+                       uint64_t keep_addr);
+    void adoptPin(std::shared_ptr<OpenedShmEntry> entry, MappingPin* pin);
+
+    Status copySlice(TransferTask& task, const TransferRequest& request,
+                     uint64_t dest_addr);
+
+    void failSlice(TransferTask& task, const TransferRequest& request);
+
+    RWSpinlock relocate_lock_;
+    std::unordered_map<SegmentID, RelocateMap> relocate_map_;
+
+    mutable std::mutex shm_path_mutex_;
+    std::unordered_map<void*, AllocatedShmEntry> shm_path_map_;
+
+    static constexpr int kShmCreateMaxRetries = 8;
+    static constexpr size_t kMaxMappingsPerTarget = 32;
+};
+
+}  // namespace mooncake
+
+#endif  // SHM_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/include/transport/tcp_transport/tcp_transport.h b/mooncake-transfer-engine/include/transport/tcp_transport/tcp_transport.h
index 88b51c9169..1da3e33a38 100644
--- a/mooncake-transfer-engine/include/transport/tcp_transport/tcp_transport.h
+++ b/mooncake-transfer-engine/include/transport/tcp_transport/tcp_transport.h
@@ -19,19 +19,30 @@
 
 #include <atomic>
 #include <chrono>
+#include <csignal>
 #include <cstddef>
+#include <cstdint>
 #include <deque>
 #include <functional>
 #include <map>
 #include <memory>
 #include <mutex>
+#include <optional>
 #include <string>
+#include <thread>
+#include <type_traits>
 #include <unordered_map>
-#include <unordered_set>
+#include <utility>
 #include <vector>
-#include <csignal>
 
+#include <asio/dispatch.hpp>
+#include <asio/executor_work_guard.hpp>
+#include <asio/io_context.hpp>
 #include <asio/ip/tcp.hpp>
+#include <asio/post.hpp>
+#include <asio/steady_timer.hpp>
+#include <glog/logging.h>
+#include <pthread.h>
 
 #include "transfer_metadata.h"
 #include "transport/transport.h"
@@ -39,24 +50,103 @@
 
 namespace mooncake {
 class TransferMetadata;
+struct ClientSession;
 class TcpContext;
 class TcpTransport;
 
-// Pooled connection for reusing client-side connections
-struct PooledConnection {
-    std::shared_ptr<asio::ip::tcp::socket> socket;
-    std::string host;
-    uint16_t port;
-    std::chrono::steady_clock::time_point last_used;
-    bool in_use;
-
-    PooledConnection(std::shared_ptr<asio::ip::tcp::socket> s,
-                     const std::string &h, uint16_t p)
-        : socket(std::move(s)),
-          host(h),
-          port(p),
-          last_used(std::chrono::steady_clock::now()),
-          in_use(true) {}
+// A bounded pool of asio::io_context instances, each driven by its own thread.
+// TCP lanes and accepted server sockets are round-robin distributed across the
+// shards so a single hot peer can use more than one CPU core. With size 1 the
+// behavior is identical to the historical single-io_context transport.
+class TcpIoPool {
+   public:
+    explicit TcpIoPool(size_t num_threads) {
+        if (num_threads < 1) num_threads = 1;
+        contexts_.reserve(num_threads);
+        guards_.reserve(num_threads);
+        for (size_t i = 0; i < num_threads; ++i) {
+            contexts_.push_back(std::make_unique<asio::io_context>());
+            guards_.push_back(
+                std::make_unique<work_guard_t>(contexts_[i]->get_executor()));
+        }
+    }
+
+    ~TcpIoPool() { stop(); }
+
+    size_t size() const { return contexts_.size(); }
+
+    asio::io_context &context(size_t i) {
+        return *contexts_[i % contexts_.size()];
+    }
+
+    asio::io_context::executor_type executor(size_t i) {
+        return contexts_[i % contexts_.size()]->get_executor();
+    }
+
+    // Group coordination (pump/admission/retry/retirement timers) is pinned to
+    // one shard chosen by hash, so a group's serialized state stays on a single
+    // executor while its lanes spread across shards.
+    asio::io_context::executor_type coordinatorExecutor(size_t hash) {
+        return executor(hash % contexts_.size());
+    }
+
+    // Round-robin executor for a new lane / accepted socket.
+    asio::io_context::executor_type nextLaneExecutor() {
+        return executor(rr_.fetch_add(1, std::memory_order_relaxed));
+    }
+
+    size_t nextShardIndex() {
+        return rr_.fetch_add(1, std::memory_order_relaxed) % contexts_.size();
+    }
+
+    // Spawns one thread per shard. before_run(i) runs on shard i's thread
+    // before each io_context.run() (used to arm the acceptor on shard 0 and to
+    // re-arm it after an exception-driven restart).
+    void start(std::function<void(size_t)> before_run) {
+        for (size_t i = 0; i < contexts_.size(); ++i) {
+            threads_.emplace_back([this, i, before_run] {
+#ifdef __linux__
+                std::string name = "mc-tcp-io-" + std::to_string(i);
+                pthread_setname_np(pthread_self(), name.c_str());
+#endif
+                while (!stopping_.load(std::memory_order_acquire)) {
+                    try {
+                        if (before_run) before_run(i);
+                        contexts_[i]->run();
+                        break;
+                    } catch (const std::exception &e) {
+                        LOG(ERROR) << "TcpIoPool shard " << i
+                                   << " encountered an exception during run: "
+                                   << e.what();
+                        // Do not restart once stop() has published its intent:
+                        // re-arming (e.g. shard 0's async_accept) after stop()
+                        // stopped the context would keep run() alive and hang
+                        // join().
+                        if (stopping_.load(std::memory_order_acquire)) break;
+                        contexts_[i]->restart();
+                    }
+                }
+            });
+        }
+    }
+
+    void stop() {
+        stopping_.store(true, std::memory_order_release);
+        guards_.clear();
+        for (auto &c : contexts_) c->stop();
+        for (auto &t : threads_)
+            if (t.joinable()) t.join();
+        threads_.clear();
+    }
+
+   private:
+    using work_guard_t =
+        asio::executor_work_guard<asio::io_context::executor_type>;
+    std::vector<std::unique_ptr<asio::io_context>> contexts_;
+    std::vector<std::unique_ptr<work_guard_t>> guards_;
+    std::vector<std::thread> threads_;
+    std::atomic<size_t> rr_{0};
+    std::atomic<bool> stopping_{false};
 };
 
 class TcpTransport : public Transport {
@@ -79,6 +169,8 @@ class TcpTransport : public Transport {
     Status submitTransferTaskGroup(
         const std::vector<TransferTask *> &task_list) override;
 
+    bool supportsGroupedScatter() const override { return true; }
+
     Status getTransferStatus(BatchID batch_id, size_t task_id,
                              TransferStatus &status) override;
 
@@ -104,8 +196,6 @@ class TcpTransport : public Transport {
     int unregisterLocalMemoryBatch(
         const std::vector<void *> &addr_list) override;
 
-    void worker();
-
     Slice *prepareTransfer(TransferTask *task, const TransferRequest &request);
 
     void startTransfer(Slice *slice,
@@ -121,11 +211,11 @@ class TcpTransport : public Transport {
    private:
     TcpContext *context_;
     std::atomic_bool running_;
-    std::thread thread_;
-    bool enable_connection_pool_ =
-        false;  // Use MC_TCP_ENABLE_CONNECTION_POOL=1 to enable connection pool
+    std::unique_ptr<TcpIoPool> io_pool_;
+    size_t num_io_threads_ = 1;
+    bool enable_connection_pool_ = true;
 
-    // Client-side connection pool
+    // Client-side bounded work queues and fixed connection lanes.
     struct ConnectionKey {
         std::string host;
         uint16_t port;
@@ -142,23 +232,280 @@ class TcpTransport : public Transport {
         }
     };
 
-    std::unordered_map<ConnectionKey,
-                       std::deque<std::shared_ptr<PooledConnection>>,
-                       ConnectionKeyHash>
-        connection_pool_;
-    std::mutex pool_mutex_;
+    enum class WorkFailureReason {
+        QUEUE_FULL,
+        QUEUE_TIMEOUT,
+        RUNTIME_UNAVAILABLE,
+        CONNECT_FAILED,
+        SESSION_FAILED,
+        SHUTDOWN,
+    };
+
+    struct FailureCounters {
+        std::atomic<uint64_t> queue_full{0};
+        std::atomic<uint64_t> queue_timeout{0};
+        std::atomic<uint64_t> connect_failed{0};
+        std::atomic<uint64_t> runtime_unavailable{0};
+        std::atomic<uint64_t> session_failed{0};
+        std::atomic<uint64_t> shutdown{0};
+    };
+
+    struct TcpWorkItem {
+        Slice *slice = nullptr;
+        bool use_v2 = false;
+        std::function<void()> continuation;
+        std::chrono::steady_clock::time_point admission_deadline;
+
+        TcpWorkItem() = default;
+        TcpWorkItem(Slice *slice_arg, bool use_v2_arg,
+                    std::function<void()> continuation_arg = nullptr)
+            : slice(slice_arg),
+              use_v2(use_v2_arg),
+              continuation(std::move(continuation_arg)) {}
+        TcpWorkItem(TcpWorkItem &&other) noexcept
+            : slice(other.slice),
+              use_v2(other.use_v2),
+              continuation(std::move(other.continuation)),
+              admission_deadline(other.admission_deadline) {
+            other.slice = nullptr;
+        }
+        TcpWorkItem &operator=(TcpWorkItem &&) = delete;
+        TcpWorkItem(const TcpWorkItem &) = delete;
+        TcpWorkItem &operator=(const TcpWorkItem &) = delete;
+    };
+
+    struct TerminalAction {
+        TcpWorkItem work;
+        TransferStatusEnum status;
+        bool connection_clean;
+
+        TerminalAction(TcpWorkItem &&work_arg, TransferStatusEnum status_arg,
+                       bool clean_arg)
+            : work(std::move(work_arg)),
+              status(status_arg),
+              connection_clean(clean_arg) {}
+        TerminalAction(TerminalAction &&) noexcept = default;
+        TerminalAction &operator=(TerminalAction &&) = delete;
+        TerminalAction(const TerminalAction &) = delete;
+        TerminalAction &operator=(const TerminalAction &) = delete;
+    };
+
+    static_assert(!std::is_copy_constructible<TcpWorkItem>::value,
+                  "TcpWorkItem must remain move-only");
+    static_assert(!std::is_copy_assignable<TcpWorkItem>::value,
+                  "TcpWorkItem must remain move-only");
+    static_assert(!std::is_copy_constructible<TerminalAction>::value,
+                  "TerminalAction must remain move-only");
+    static_assert(!std::is_copy_assignable<TerminalAction>::value,
+                  "TerminalAction must remain move-only");
+
+    enum class GroupState { OPEN, CLOSING, CLOSED };
+    enum class LaneState {
+        DISCONNECTED,
+        CONNECTING,
+        IDLE,
+        BUSY,
+        COMPLETING,
+        CLOSING,
+        CLOSED,
+    };
+    enum class LaneConnectStage { NONE, RESOLVING, CONNECTING };
+
+    struct ConnectionLaneRuntime {
+        explicit ConnectionLaneRuntime(TcpIoPool &pool_arg) : pool(&pool_arg) {}
+
+        asio::io_context::executor_type coordinatorExecutor(size_t hash) {
+            return pool->coordinatorExecutor(hash);
+        }
+        asio::io_context::executor_type nextLaneExecutor() {
+            return pool->nextLaneExecutor();
+        }
+
+        TcpIoPool *pool;
+    };
+
+    struct ConnectionLaneState;
+    struct PeerConnectionGroup;
+
+    struct ConnectionLane {
+        ConnectionLane(size_t lane_id_arg,
+                       const std::shared_ptr<PeerConnectionGroup> &group_arg,
+                       const asio::io_context::executor_type &executor_arg)
+            : lane_id(lane_id_arg), group(group_arg), executor(executor_arg) {}
+
+        size_t lane_id;
+        std::weak_ptr<PeerConnectionGroup> group;
+        // Shard executor this lane's socket/resolver/session/timers are bound
+        // to. Round-robin assigned so a group's lanes spread across io threads.
+        asio::io_context::executor_type executor;
+        LaneState state = LaneState::DISCONNECTED;
+        LaneConnectStage connect_stage = LaneConnectStage::NONE;
+        uint64_t operation_epoch = 0;
+        uint64_t last_connect_round = 0;
+        std::shared_ptr<asio::ip::tcp::resolver> resolver;
+        std::shared_ptr<asio::ip::tcp::socket> socket;
+        std::shared_ptr<ClientSession> session;
+        std::optional<TcpWorkItem> current;
+    };
+
+    struct PeerConnectionGroup {
+        PeerConnectionGroup(ConnectionKey key_arg,
+                            const asio::io_context::executor_type &executor_arg,
+                            size_t queue_capacity_arg,
+                            size_t pending_admission_capacity_arg,
+                            std::chrono::milliseconds admission_timeout_arg,
+                            std::shared_ptr<FailureCounters> counters_arg)
+            : key(std::move(key_arg)),
+              executor(executor_arg),
+              queue_capacity(queue_capacity_arg),
+              pending_admission_capacity(pending_admission_capacity_arg),
+              admission_timeout(admission_timeout_arg),
+              failure_counters(std::move(counters_arg)) {}
+
+        std::mutex mutex;
+        GroupState state = GroupState::OPEN;
+        ConnectionKey key;
+        asio::io_context::executor_type executor;
+        size_t queue_capacity;
+        std::deque<TcpWorkItem> queue;
+        std::deque<TcpWorkItem> pending_admissions;
+        size_t pending_admission_capacity;
+        std::chrono::milliseconds admission_timeout;
+        std::shared_ptr<asio::steady_timer> admission_timer;
+        uint64_t admission_epoch = 0;
+        uint64_t queued_bytes = 0;
+        bool queued_bytes_saturated = false;
+        std::vector<std::shared_ptr<ConnectionLane>> lanes;
+        bool pump_scheduled = false;
+        uint64_t pump_epoch = 0;
+        uint64_t connect_round = 1;
+        size_t probes_in_flight = 0;
+        bool connect_round_had_success = false;
+        std::chrono::steady_clock::time_point next_probe_not_before{};
+        std::shared_ptr<asio::steady_timer> retry_timer;
+        uint64_t retry_epoch = 0;
+        uint64_t connect_failure_log_count = 0;
+        bool retiring = false;
+        bool retirement_scheduled = false;
+        std::weak_ptr<ConnectionLaneState> owner_state;
+        std::shared_ptr<FailureCounters> failure_counters;
+    };
+
+    struct ConnectionLaneState {
+        std::mutex mutex;
+        bool shutting_down = false;
+        size_t lanes_per_peer = 4;
+        size_t max_queued_transfers_per_peer = 1024;
+        size_t max_pending_admissions_per_peer = 1024;
+        std::chrono::milliseconds admission_timeout{1000};
+        std::unordered_map<ConnectionKey, std::shared_ptr<PeerConnectionGroup>,
+                           ConnectionKeyHash>
+            groups;
+        std::unordered_map<std::string, ConnectionKey> current_key_by_peer;
+        std::vector<std::shared_ptr<PeerConnectionGroup>> retiring_groups;
+        std::weak_ptr<ConnectionLaneRuntime> runtime;
+        std::shared_ptr<FailureCounters> failure_counters =
+            std::make_shared<FailureCounters>();
+    };
+
+    std::shared_ptr<ConnectionLaneRuntime> lane_runtime_;
+    std::shared_ptr<ConnectionLaneState> lane_state_;
+
+    // TODO(#2930): The queue item bound does not bound queued source bytes,
+    // and a connected payload without a progress deadline can still stall a
+    // lane indefinitely. Peer-generation recovery is also a separate phase.
 
     std::shared_ptr<asio::ip::tcp::socket> getConnection(
-        const std::string &host, uint16_t port, bool use_pool);
-    void returnConnection(const std::string &host, uint16_t port,
-                          std::shared_ptr<asio::ip::tcp::socket> socket);
-    // Close `socket` and drop it from the pool: used for requests that did
-    // not terminate in a well-defined protocol state (#2086).
-    void discardConnection(const std::string &host, uint16_t port,
-                           std::shared_ptr<asio::ip::tcp::socket> socket);
-    void cleanupIdleConnections();
-
-    static constexpr std::chrono::seconds kConnectionIdleTimeout{60};
+        const std::string &host, uint16_t port);
+    void enqueuePooledTransfer(const std::string &logical_peer,
+                               const ConnectionKey &key, TcpWorkItem work);
+    static uint64_t requestGroupPumpLocked(PeerConnectionGroup &group);
+    static void postGroupPump(const std::shared_ptr<PeerConnectionGroup> &group,
+                              uint64_t pump_epoch);
+    static bool requestGroupRetirementLocked(PeerConnectionGroup &group);
+    static void postGroupRetirement(
+        const std::shared_ptr<PeerConnectionGroup> &group);
+    static void scheduleGroupRetirement(
+        const std::shared_ptr<PeerConnectionGroup> &group);
+    static void runGroupRetirement(
+        const std::shared_ptr<PeerConnectionGroup> &group);
+    static void runGroupPump(const std::shared_ptr<PeerConnectionGroup> &group,
+                             uint64_t pump_epoch);
+    static void startLaneConnect(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch);
+    static void handleLaneResolved(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch,
+        asio::error_code ec, asio::ip::tcp::resolver::results_type results);
+    static void handleLaneConnected(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch,
+        asio::error_code ec);
+    static void handleLaneConnectFailure(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch,
+        const std::string &error);
+    static bool armRetryTimerLocked(
+        const std::shared_ptr<PeerConnectionGroup> &group);
+    static void handleRetryTimer(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<asio::steady_timer> &timer, uint64_t retry_epoch,
+        asio::error_code ec);
+    static size_t expirePendingAdmissionsLocked(
+        PeerConnectionGroup &group, std::chrono::steady_clock::time_point now,
+        std::deque<TcpWorkItem> &expired);
+    static size_t promotePendingAdmissionsLocked(PeerConnectionGroup &group);
+    static void refreshAdmissionTimerLocked(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        std::deque<TcpWorkItem> &runtime_failed,
+        std::shared_ptr<asio::steady_timer> &timer_to_cancel,
+        bool &timer_armed);
+    static void handleAdmissionTimer(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<asio::steady_timer> &timer,
+        uint64_t admission_epoch, asio::error_code ec);
+    static void startLaneSession(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch);
+    static void handleLaneTerminal(
+        const std::shared_ptr<PeerConnectionGroup> &group,
+        const std::shared_ptr<ConnectionLane> &lane, uint64_t epoch,
+        TransferStatusEnum status, bool connection_clean) noexcept;
+    static void completeTerminalAction(TerminalAction action) noexcept;
+    static void failWorkItem(
+        TcpWorkItem work, WorkFailureReason reason,
+        const std::shared_ptr<FailureCounters> &counters) noexcept;
+    static void failWorkItems(
+        std::deque<TcpWorkItem> work, WorkFailureReason reason,
+        const std::shared_ptr<FailureCounters> &counters) noexcept;
+    static uint64_t recordWorkFailure(
+        WorkFailureReason reason,
+        const std::shared_ptr<FailureCounters> &counters) noexcept;
+    static bool hasUsableLaneLocked(const PeerConnectionGroup &group);
+    static bool hasDisconnectedLaneLocked(const PeerConnectionGroup &group);
+    static bool hasUntriedDisconnectedLaneLocked(
+        const PeerConnectionGroup &group);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    static size_t activeSocketCountLocked(const PeerConnectionGroup &group);
+#endif
+    static void beginConnectRoundLocked(PeerConnectionGroup &group);
+    static void enterReconnectCooldownLocked(PeerConnectionGroup &group);
+    static void addQueuedBytesLocked(PeerConnectionGroup &group,
+                                     uint64_t length);
+    static void removeQueuedBytesLocked(PeerConnectionGroup &group,
+                                        uint64_t length);
+    static void clearQueuedBytesLocked(PeerConnectionGroup &group);
+    static void closeSocketNoThrow(
+        const std::shared_ptr<asio::ip::tcp::socket> &socket) noexcept;
+    void shutdownConnectionLanes();
+    void startTransferWithSocket(
+        TcpWorkItem work,
+        std::shared_ptr<asio::ip::tcp::socket> socket) noexcept;
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    friend bool tcpTransportLaneTypesAreMoveOnlyForTest() noexcept;
+#endif
 };
 }  // namespace mooncake
 
diff --git a/mooncake-transfer-engine/include/transport/transport.h b/mooncake-transfer-engine/include/transport/transport.h
index 4233705e26..975adeb840 100644
--- a/mooncake-transfer-engine/include/transport/transport.h
+++ b/mooncake-transfer-engine/include/transport/transport.h
@@ -59,6 +59,7 @@ class Transport {
 
     struct TransferRequest {
         enum OpCode { READ, WRITE };
+        enum Priority { PRIO_HIGH = 0, PRIO_MEDIUM = 1, PRIO_LOW = 2 };
 
         static constexpr uint64_t kNoTaskGroup = 0;
 
@@ -70,8 +71,10 @@ class Transport {
         int advise_retry_cnt = 0;
         // Per-request transport pin, TENT only.
         int transport_hint = 0;
-        // Adjacent requests in the same group are one transport submission.
+        // Adjacent requests in a group may be scheduled as one unit.
         uint64_t task_group_id = kNoTaskGroup;
+        // TENT transport selection priority; ignored by classic TE.
+        int priority = PRIO_MEDIUM;
     };
 
     enum TransferStatusEnum {
@@ -167,6 +170,7 @@ class Transport {
                 void *dest_addr;
                 void *cuda_stream;  // cudaStream_t, used by async NVLink
                                     // transport
+                int cuda_device;    // device that owns cuda_stream
             } local;
             struct {
                 void *event;  // cudaEvent_t
@@ -196,6 +200,9 @@ class Transport {
             struct {
                 uint64_t dest_addr;
             } ubshmem;
+            struct {
+                uint64_t dest_offset;
+            } flagcx;
         };
 
        public:
@@ -203,37 +210,47 @@ class Transport {
             status = Slice::SUCCESS;
             __atomic_fetch_add(&task->transferred_bytes, length,
                                __ATOMIC_RELAXED);
-            __atomic_fetch_add(&task->success_slice_count, 1, __ATOMIC_RELAXED);
+            __atomic_fetch_add(&task->success_slice_count, 1, __ATOMIC_ACQ_REL);
 
-            check_batch_completion(false);
+            check_batch_completion(task, false);
         }
 
         void markFailed() {
             status = Slice::FAILED;
-            __atomic_fetch_add(&task->failed_slice_count, 1, __ATOMIC_RELAXED);
+            __atomic_fetch_add(&task->failed_slice_count, 1, __ATOMIC_ACQ_REL);
 
-            check_batch_completion(true);
+            check_batch_completion(task, true);
         }
 
+#ifdef USE_EVENT_DRIVEN_COMPLETION
+        static void sealTaskSubmission(TransferTask *task) {
+            __atomic_store_n(&task->submission_sealed, true, __ATOMIC_RELEASE);
+            check_batch_completion(task, false, false);
+        }
+#endif
+
         volatile int64_t ts;
 
        private:
-        inline void check_batch_completion(bool is_failed) {
+        static inline void check_batch_completion(TransferTask *task,
+                                                  bool is_failed,
+                                                  bool count_slice = true) {
 #ifdef USE_EVENT_DRIVEN_COMPLETION
             auto &batch_desc = toBatchDesc(task->batch_id);
             if (is_failed) {
                 batch_desc.has_failure.store(true, std::memory_order_relaxed);
             }
 
-            // When the last slice of a task completes, check if the entire task
-            // is done using a single atomic counter to avoid reading
-            // inconsistent results.
-            uint64_t prev_completed = __atomic_fetch_add(
-                &task->completed_slice_count, 1, __ATOMIC_RELAXED);
-
-            // Only the thread completing the final slice will see prev+1 ==
-            // slice_count.
-            if (prev_completed + 1 == task->slice_count) {
+            uint64_t completed =
+                count_slice ? __atomic_add_fetch(&task->completed_slice_count,
+                                                 1, __ATOMIC_ACQ_REL)
+                            : __atomic_load_n(&task->completed_slice_count,
+                                              __ATOMIC_ACQUIRE);
+            if (__atomic_load_n(&task->submission_sealed, __ATOMIC_ACQUIRE) &&
+                completed ==
+                    __atomic_load_n(&task->slice_count, __ATOMIC_ACQUIRE) &&
+                !__atomic_exchange_n(&task->completion_published, true,
+                                     __ATOMIC_ACQ_REL)) {
                 __atomic_store_n(&task->is_finished, true, __ATOMIC_RELAXED);
 
                 // Increment the number of finished tasks in the batch
@@ -341,6 +358,8 @@ class Transport {
 
 #ifdef USE_EVENT_DRIVEN_COMPLETION
         volatile uint64_t completed_slice_count = 0;
+        volatile bool submission_sealed = true;
+        volatile bool completion_published = false;
 #endif
 
         // record the origin request
@@ -351,6 +370,7 @@ class Transport {
 #else
         const TransferRequest *request = nullptr;
 #endif
+        size_t request_count = 1;
         // record the slice list for freeing objects
         std::vector<Slice *> slice_list;
         ~TransferTask() {
@@ -370,6 +390,8 @@ class Transport {
         std::atomic<bool> has_failure{false};
         std::atomic<bool> is_finished{
             false};  // Completion flag for wait predicate
+        // Completion events do not populate the status-query byte cache.
+        std::atomic<bool> status_cached{false};
         std::atomic<uint64_t> finished_transfer_bytes{0};
 
 #ifdef USE_EVENT_DRIVEN_COMPLETION
@@ -408,6 +430,10 @@ class Transport {
         return submitTransferTask(task_list);
     }
 
+    // Grouped transports must append slices in request order so scatter can
+    // recover per-request status after a grouped task fails.
+    virtual bool supportsGroupedScatter() const { return false; }
+
     /// @brief Get the status of a submitted transfer. This function shall not
     /// be called again after completion.
     /// @return Return 1 on completed (either success or failure); 0 if still in
diff --git a/mooncake-transfer-engine/rust/CMakeLists.txt b/mooncake-transfer-engine/rust/CMakeLists.txt
index 22a24fea5e..61ad956701 100644
--- a/mooncake-transfer-engine/rust/CMakeLists.txt
+++ b/mooncake-transfer-engine/rust/CMakeLists.txt
@@ -1,7 +1,53 @@
+# CMake integration for the transfer_engine_rust package.
+#
+# Added when the parent CMakeLists.txt sets WITH_RUST_EXAMPLE=ON. Depends on the
+# transfer_engine C++ target so libtransfer_engine is available before cargo
+# links against it.
+
+set(_te_rust_env
+    CARGO_TARGET_DIR=${CMAKE_CURRENT_BINARY_DIR}
+    MOONCAKE_BUILD_DIR=${CMAKE_BINARY_DIR}
+    MOONCAKE_TE_LIB_DIR=${CMAKE_CURRENT_BINARY_DIR}/../src
+    MOONCAKE_TE_INCLUDE_DIR=${CMAKE_CURRENT_SOURCE_DIR}/../include)
+if(USE_ETCD)
+  list(APPEND _te_rust_env MOONCAKE_WITH_ETCD=1)
+endif()
+if(USE_CUDA)
+  list(APPEND _te_rust_env MOONCAKE_WITH_CUDA=1)
+endif()
+if(NOT USE_EFA)
+  list(APPEND _te_rust_env MOONCAKE_WITHOUT_LIBFABRIC=1)
+endif()
+if(USE_TENT)
+  list(APPEND _te_rust_env MOONCAKE_WITH_TENT=1)
+endif()
+if(ENABLE_ASAN)
+  list(APPEND _te_rust_env MOONCAKE_LINK_ASAN=1)
+endif()
+
 add_custom_target(build_transfer_engine_rust DEPENDS transfer_engine)
 add_custom_command(
-    TARGET build_transfer_engine_rust
-    COMMAND ${CMAKE_COMMAND} -E env CARGO_TARGET_DIR=${CMAKE_CURRENT_BINARY_DIR} cargo build --release
-    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-)
+  TARGET build_transfer_engine_rust
+  COMMAND ${CMAKE_COMMAND} -E env ${_te_rust_env} cargo build --release
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  COMMENT "Building transfer_engine_rust library"
+  VERBATIM)
 set_property(TARGET build_transfer_engine_rust PROPERTY EXCLUDE_FROM_ALL FALSE)
+
+add_custom_target(build_transfer_engine_rust_example DEPENDS transfer_engine)
+add_custom_command(
+  TARGET build_transfer_engine_rust_example
+  COMMAND ${CMAKE_COMMAND} -E env ${_te_rust_env} cargo build --examples
+          --release
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  COMMENT "Building transfer_engine_rust examples"
+  VERBATIM)
+
+add_custom_target(build_transfer_engine_rust_tests DEPENDS transfer_engine)
+add_custom_command(
+  TARGET build_transfer_engine_rust_tests
+  COMMAND ${CMAKE_COMMAND} -E env ${_te_rust_env} cargo test --tests --no-run
+          --release
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  COMMENT "Building transfer_engine_rust tests"
+  VERBATIM)
diff --git a/mooncake-transfer-engine/rust/Cargo.lock b/mooncake-transfer-engine/rust/Cargo.lock
index 2997895bd1..d63ba74f6f 100644
--- a/mooncake-transfer-engine/rust/Cargo.lock
+++ b/mooncake-transfer-engine/rust/Cargo.lock
@@ -4,18 +4,18 @@ version = 4
 
 [[package]]
 name = "aho-corasick"
-version = "1.1.3"
+version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
 dependencies = [
  "memchr",
 ]
 
 [[package]]
 name = "anstream"
-version = "0.6.15"
+version = "0.6.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "64e15c1ab1f89faffbf04a634d5e1962e9074f2741eef6d97f3c4e322426d526"
+checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
 dependencies = [
  "anstyle",
  "anstyle-parse",
@@ -28,43 +28,44 @@ dependencies = [
 
 [[package]]
 name = "anstyle"
-version = "1.0.8"
+version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1bec1de6f59aedf83baf9ff929c98f2ad654b97c9510f4e70cf6f661d49fd5b1"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
 
 [[package]]
 name = "anstyle-parse"
-version = "0.2.5"
+version = "0.2.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eb47de1e80c2b463c735db5b217a0ddc39d612e7ac9e2e96a5aed1f57616c1cb"
+checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
 dependencies = [
  "utf8parse",
 ]
 
 [[package]]
 name = "anstyle-query"
-version = "1.1.1"
+version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6d36fc52c7f6c869915e99412912f22093507da8d9e942ceaf66fe4b7c14422a"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
  "windows-sys",
 ]
 
 [[package]]
 name = "anstyle-wincon"
-version = "3.0.4"
+version = "3.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5bf74e1b6e971609db8ca7a9ce79fd5768ab6ae46441c572e46cf596f59e57f8"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
 dependencies = [
  "anstyle",
+ "once_cell_polyfill",
  "windows-sys",
 ]
 
 [[package]]
 name = "anyhow"
-version = "1.0.90"
+version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37bf3594c4c988a53154954629820791dde498571819ae4ca50ca811e060cc95"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
 [[package]]
 name = "bindgen"
@@ -83,23 +84,14 @@ dependencies = [
  "regex",
  "rustc-hash",
  "shlex",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "bitflags"
-version = "2.6.0"
+version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de"
-
-[[package]]
-name = "cc"
-version = "1.1.31"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c2e7962b54006dcfcc61cb72735f4d89bb97061dd6a7ed882ec6b8ee53714c6f"
-dependencies = [
- "shlex",
-]
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 
 [[package]]
 name = "cexpr"
@@ -112,15 +104,15 @@ dependencies = [
 
 [[package]]
 name = "cfg-if"
-version = "1.0.0"
+version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clang-sys"
-version = "1.8.1"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
 dependencies = [
  "glob",
  "libc",
@@ -129,9 +121,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.5.20"
+version = "4.4.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b97f376d85a664d5837dbae44bf546e6477a679ff6610010f17276f686d867e8"
+checksum = "1e578d6ec4194633722ccf9544794b71b1385c3c027efe0c55db226fc880865c"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -139,9 +131,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.5.20"
+version = "4.4.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19bc80abd44e4bed93ca373a0704ccbd1b710dc5749406201bb018272808dc54"
+checksum = "4df4df40ec50c46000231c914968278b1eb05098cf8f1b3a518a95030e71d1c7"
 dependencies = [
  "anstream",
  "anstyle",
@@ -151,36 +143,27 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.5.18"
+version = "4.4.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ac6a0c7b1a9e9a5186361f67dfa1b88213572f427fb9ab038efb2bd8c582dab"
+checksum = "cf9804afaaf59a91e75b022a30fb7229a7901f60c755489cc61c9b423b836442"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "clap_lex"
-version = "0.7.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1462739cb27611015575c0c11df5df7601141071f07518d56fcc1be504cbec97"
-
-[[package]]
-name = "cmake"
-version = "0.1.51"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fb1e43aa7fd152b1f968787f7dbcdeb306d1867ff373c69955211876c053f91a"
-dependencies = [
- "cc",
-]
+checksum = "702fc72eb24e5a1e48ce58027a675bc24edd52096d5397d4aea7c6dd9eca0bd1"
 
 [[package]]
 name = "colorchoice"
-version = "1.0.2"
+version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3fd119d74b830634cea2a0f58bbd0d54540518a14397557951e79340abc28c0"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
 [[package]]
 name = "dns-lookup"
@@ -196,21 +179,21 @@ dependencies = [
 
 [[package]]
 name = "either"
-version = "1.13.0"
+version = "1.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "60b1af1c220855b6ceac025d3f6ecdd2b7c4894bfe9cd9bda4fbb4bc7c0d4cf0"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
 
 [[package]]
 name = "glob"
-version = "0.3.1"
+version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
 [[package]]
 name = "heck"
-version = "0.5.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
 
 [[package]]
 name = "hostname"
@@ -225,9 +208,9 @@ dependencies = [
 
 [[package]]
 name = "is_terminal_polyfill"
-version = "1.70.1"
+version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
 [[package]]
 name = "itertools"
@@ -246,25 +229,25 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
 name = "libc"
-version = "0.2.161"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e9489c2807c139ffd9c1794f4af0ebe86a828db53ecdc7fea2111d0fed085d1"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "libloading"
-version = "0.8.5"
+version = "0.8.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4979f22fdb869068da03c9f7528f8297c6fd2606bc3a4affe42e6a823fdb8da4"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
 dependencies = [
  "cfg-if",
- "windows-targets",
+ "windows-link",
 ]
 
 [[package]]
 name = "log"
-version = "0.4.22"
+version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "match_cfg"
@@ -274,9 +257,9 @@ checksum = "ffbee8634e0d45d258acb448e7eaab3fce7a0a467395d4d9f228e3c1f01fb2e4"
 
 [[package]]
 name = "memchr"
-version = "2.7.4"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "minimal-lexical"
@@ -296,58 +279,64 @@ dependencies = [
 
 [[package]]
 name = "nu-ansi-term"
-version = "0.50.1"
+version = "0.50.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4a28e057d01f97e61255210fcff094d74ed0466038633e95017f5beb68e4399"
+checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
 dependencies = [
  "windows-sys",
 ]
 
 [[package]]
 name = "once_cell"
-version = "1.20.2"
+version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1261fe7e33c73b354eab43b1273a57c8f967d0391e80353e51f764ac02cf6775"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
 [[package]]
 name = "pin-project-lite"
-version = "0.2.14"
+version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bda66fc9667c18cb2758a2ac84d1167245054bcf85d5d1aaa6923f45801bdd02"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "prettyplease"
-version = "0.2.25"
+version = "0.2.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "64d1ec885c64d0457d564db4ec299b2dae3f9c02808b8ad9c3a089c591b18033"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
 dependencies = [
  "proc-macro2",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.88"
+version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c3a7fc5db1e57d5a779a352c8cdb57b29aa4c40cc69c3a68a7fedc815fbf2f9"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
  "unicode-ident",
 ]
 
 [[package]]
 name = "quote"
-version = "1.0.37"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
 ]
 
 [[package]]
 name = "regex"
-version = "1.11.0"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "38200e5ee88914975b69f657f0801b6f6dccafd44fd9326302a4aaeecfacb1d8"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -357,9 +346,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.8"
+version = "0.4.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "368758f23274712b504848e9d5a6f010445cc8b87a7cdb4d7cbee666c1288da3"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -368,9 +357,9 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.8.5"
+version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rustc-hash"
@@ -395,9 +384,9 @@ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
 [[package]]
 name = "smallvec"
-version = "1.13.2"
+version = "1.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c5e1a9a646d36c3599cd173a41282daf47c44583ad367b8e6837255952e5c67"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
 
 [[package]]
 name = "socket2"
@@ -411,36 +400,66 @@ dependencies = [
 
 [[package]]
 name = "strsim"
-version = "0.11.1"
+version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
 
 [[package]]
 name = "syn"
-version = "2.0.82"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83540f837a8afc019423a8edb95b52a8effe46957ee402287f4292fae35be021"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "thread_local"
-version = "1.1.8"
+version = "1.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b9ef9bad013ada3808854ceac7b46812a6465ba368859a37e2100283d2d719c"
+checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070"
 dependencies = [
  "cfg-if",
- "once_cell",
 ]
 
 [[package]]
 name = "tracing"
-version = "0.1.40"
+version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3523ab5a71916ccf420eebdf5521fcef02141234bbc0b8a49f2fdc4544364ef"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
  "pin-project-lite",
  "tracing-attributes",
@@ -449,20 +468,20 @@ dependencies = [
 
 [[package]]
 name = "tracing-attributes"
-version = "0.1.27"
+version = "0.1.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34704c8d6ebcbc939824180af020566b01a7c01f80641264eba0999f6c2b6be7"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "tracing-core"
-version = "0.1.34"
+version = "0.1.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9d12581f227e93f094d3af2ae690a574abb8a2b9b7a96e7cfe9647b2b617678"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
  "once_cell",
  "valuable",
@@ -481,9 +500,9 @@ dependencies = [
 
 [[package]]
 name = "tracing-subscriber"
-version = "0.3.20"
+version = "0.3.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2054a14f5307d601f88daf0553e1cbf472acc4f2c51afab632431cdcd72124d5"
+checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
 dependencies = [
  "nu-ansi-term",
  "sharded-slab",
@@ -500,19 +519,18 @@ dependencies = [
  "anyhow",
  "bindgen",
  "clap",
- "cmake",
  "dns-lookup",
  "hostname",
- "libc",
+ "thiserror",
  "tracing",
  "tracing-subscriber",
 ]
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.13"
+version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e91b56cd4cadaeb79bbf1a5645f6b4f8dc5bde8834ad5894a8db35fda9efa1fe"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
 name = "utf8parse"
@@ -522,9 +540,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "valuable"
-version = "0.1.0"
+version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "830b7e5d4d90034032940e4ace0d9a9a057e7a45cd94e6c007832e39edb82f6d"
+checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
 [[package]]
 name = "winapi"
@@ -549,74 +567,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
 [[package]]
-name = "windows-sys"
-version = "0.52.0"
+name = "windows-link"
+version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
-dependencies = [
- "windows-targets",
-]
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
 [[package]]
-name = "windows-targets"
-version = "0.52.6"
+name = "windows-sys"
+version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
- "windows_aarch64_gnullvm",
- "windows_aarch64_msvc",
- "windows_i686_gnu",
- "windows_i686_gnullvm",
- "windows_i686_msvc",
- "windows_x86_64_gnu",
- "windows_x86_64_gnullvm",
- "windows_x86_64_msvc",
+ "windows-link",
 ]
-
-[[package]]
-name = "windows_aarch64_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
-
-[[package]]
-name = "windows_aarch64_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
-
-[[package]]
-name = "windows_i686_gnu"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
-
-[[package]]
-name = "windows_i686_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
-
-[[package]]
-name = "windows_i686_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
-
-[[package]]
-name = "windows_x86_64_gnu"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
-
-[[package]]
-name = "windows_x86_64_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
-
-[[package]]
-name = "windows_x86_64_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
diff --git a/mooncake-transfer-engine/rust/Cargo.toml b/mooncake-transfer-engine/rust/Cargo.toml
index e001f291da..639c55e492 100644
--- a/mooncake-transfer-engine/rust/Cargo.toml
+++ b/mooncake-transfer-engine/rust/Cargo.toml
@@ -2,11 +2,23 @@
 name = "transfer_engine_rust"
 version = "0.1.0"
 edition = "2021"
+description = "High-performance Rust bindings for the Mooncake Transfer Engine"
+license = "Apache-2.0"
+
+[lib]
+name = "transfer_engine_rust"
+crate-type = ["rlib"]
+
+[[example]]
+name = "transfer_engine_bench"
+path = "examples/transfer_engine_bench.rs"
 
 [dependencies]
+thiserror = "2.0"
+
+[dev-dependencies]
 anyhow = "1.0.79"
-libc = "0.2"
-clap = { version = "4.4", features = ["derive"] }
+clap = { version = "~4.4.18", features = ["derive"] }
 tracing = "0.1"
 tracing-subscriber = "0.3.20"
 hostname = "0.3"
@@ -14,4 +26,3 @@ dns-lookup = "1.0"
 
 [build-dependencies]
 bindgen = "0.70"
-cmake = "0.1.50"
\ No newline at end of file
diff --git a/mooncake-transfer-engine/rust/README.md b/mooncake-transfer-engine/rust/README.md
new file mode 100644
index 0000000000..5a3000a588
--- /dev/null
+++ b/mooncake-transfer-engine/rust/README.md
@@ -0,0 +1,119 @@
+# Transfer Engine Rust Bindings
+
+This directory contains high-performance Rust bindings for the Mooncake
+Transfer Engine C API (`transfer_engine_c.h`), plus a throughput-benchmark
+example analogous to `example/transfer_engine_bench.cpp`.
+
+The crate (`transfer_engine_rust`) is a **library**. Hot-path types
+(`TransferRequest`, `BufferEntry`, `TransferStatus`) are `#[repr(C)]` and
+layout-checked against the C ABI, so `submit_transfer` / `get_transfer_status`
+pass slices and stack structs to C with no heap allocation on the Rust side.
+
+## Prerequisites
+
+Install the Rust toolchain and libclang (bindgen):
+
+```bash
+sudo apt-get install libclang-dev clang
+```
+
+## Build With CMake
+
+```bash
+cmake -S . -B build -G Ninja -DWITH_RUST_EXAMPLE=ON
+cmake --build build --target build_transfer_engine_rust
+cmake --build build --target build_transfer_engine_rust_example
+cmake --build build --target build_transfer_engine_rust_tests
+```
+
+## Build With Cargo
+
+```bash
+cd mooncake-transfer-engine/rust
+
+export MOONCAKE_BUILD_DIR=/path/to/Mooncake/build
+export MOONCAKE_TE_LIB_DIR=$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src
+export MOONCAKE_TE_INCLUDE_DIR=/path/to/Mooncake/mooncake-transfer-engine/include
+
+cargo test --lib --release
+cargo build --examples --release
+```
+
+If Transfer Engine was built with etcd, CUDA, or TENT, `build.rs` auto-detects
+the extra archives (`etcd_wrapper`, `cudart`, `libtent.a` / `libtent_xport_*.a`)
+when `MOONCAKE_BUILD_DIR` points at the CMake build tree. You can also force
+this with `MOONCAKE_WITH_ETCD=1`, `MOONCAKE_WITH_CUDA=1`, and
+`MOONCAKE_WITH_TENT=1`.
+
+At runtime, add CMake outputs to `LD_LIBRARY_PATH` if they are not installed:
+
+```bash
+export LD_LIBRARY_PATH=$MOONCAKE_BUILD_DIR/mooncake-asio:\
+$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src:\
+$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src/common/base:\
+${LD_LIBRARY_PATH:-}
+```
+
+## Quick start
+
+```rust
+use transfer_engine_rust::{MemoryPool, TransferEngine, TransferRequest, WILDCARD_LOCATION};
+
+fn main() -> Result<(), transfer_engine_rust::EngineError> {
+    let engine = TransferEngine::initialize(
+        "127.0.0.1:12345",
+        "http://127.0.0.1:8080/metadata",
+        "tcp",
+        "",
+    )?;
+
+    let pool = MemoryPool::new(1 << 20);
+    unsafe {
+        engine.register_local_memory(pool.as_void_ptr(), pool.len(), WILDCARD_LOCATION)?;
+
+        let seg = engine.open_segment("peer:12345")?;
+        let req = TransferRequest::write(pool.as_void_ptr(), seg, 0, 4096);
+        engine.submit_and_wait(&[req], None)?;
+
+        engine.unregister_local_memory(pool.as_void_ptr())?;
+    }
+    Ok(())
+}
+```
+
+`initialize` matches the Python `TransferEngine.initialize(local_hostname,
+metadata_server, protocol, device_name)` shape. The lower-level
+`TransferEngine::new` / `create` constructors map 1:1 onto
+`createTransferEngine`.
+
+Device filtering is not part of the C ABI; set `MC_TE_FILTERS` if you need to
+restrict NICs.
+
+## Integration smoke test
+
+Unit tests (`cargo test --lib`) do not start an engine. The env-gated
+`minimal_smoke` test initializes TCP, registers an 8KiB pool, and does a
+loopback WRITE/READ of 4KiB on the local segment. It defaults to
+`P2PHANDSHAKE` so no HTTP metadata server is required.
+
+```bash
+cd mooncake-transfer-engine/rust
+
+MC_RUST_TE_RUN_INTEGRATION=1 \
+MC_METADATA_SERVER=P2PHANDSHAKE \
+MC_RUST_TE_PROTOCOL=tcp \
+cargo test --test minimal_smoke -- --nocapture
+```
+
+GitHub Actions runs the same smoke (plus `cargo test --lib`) from
+`scripts/ci/run_transfer_engine_rust_smoke.sh` after the C++ build. ASan
+jobs set `MOONCAKE_TE_RUST_LINK_ASAN=1`; nightly Release jobs leave it at
+`0`. CI points `MC_METADATA_SERVER` at the HTTP metadata bootstrap server.
+
+## Benchmark example
+
+```bash
+cargo run --example transfer_engine_bench --release -- --mode target
+cargo run --example transfer_engine_bench --release -- \
+  --mode initiator --segment-id <target-ip> --protocol tcp
+```
diff --git a/mooncake-transfer-engine/rust/build.rs b/mooncake-transfer-engine/rust/build.rs
index 84edf4bb06..674507ce34 100644
--- a/mooncake-transfer-engine/rust/build.rs
+++ b/mooncake-transfer-engine/rust/build.rs
@@ -12,44 +12,288 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use std::cmp::Ordering;
 use std::env;
-use std::path::PathBuf;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn flag_on(name: &str) -> bool {
+    env::var(name)
+        .map(|v| v == "1" || v.eq_ignore_ascii_case("on") || v.eq_ignore_ascii_case("true"))
+        .unwrap_or(false)
+}
+
+fn push_dir(dirs: &mut Vec<PathBuf>, dir: PathBuf) {
+    if dir.is_dir() && !dirs.iter().any(|existing| existing == &dir) {
+        dirs.push(dir);
+    }
+}
+
+fn emit_link_searches(dirs: &[PathBuf]) {
+    for dir in dirs {
+        println!("cargo:rustc-link-search=native={}", dir.display());
+        println!("cargo:rustc-link-arg=-Wl,-rpath,{}", dir.display());
+    }
+}
+
+fn has_library(search_dirs: &[PathBuf], name: &str) -> bool {
+    let file_names = [
+        format!("lib{name}.so"),
+        format!("lib{name}.a"),
+        format!("lib{name}.dylib"),
+    ];
+    search_dirs
+        .iter()
+        .any(|dir| file_names.iter().any(|file| dir.join(file).exists()))
+        || ["/usr/lib/x86_64-linux-gnu", "/usr/lib64", "/usr/local/lib"]
+            .into_iter()
+            .any(|dir| {
+                file_names
+                    .iter()
+                    .any(|file| Path::new(dir).join(file).exists())
+            })
+}
+
+fn has_static_library(search_dirs: &[PathBuf], name: &str) -> bool {
+    let file_name = format!("lib{name}.a");
+    search_dirs.iter().any(|dir| dir.join(&file_name).exists())
+        || ["/usr/lib/x86_64-linux-gnu", "/usr/lib64", "/usr/local/lib"]
+            .into_iter()
+            .any(|dir| Path::new(dir).join(&file_name).exists())
+}
+
+fn is_tent_archive(lib: &str) -> bool {
+    lib == "tent"
+        || lib.starts_with("tent_")
+        || lib.starts_with("metastore_")
+        || lib.starts_with("platform_")
+}
+
+/// Collect TENT static archives (`libtent.a`, `libtent_xport_*.a`, …).
+/// `USE_TENT=ON` compiles those into `libtransfer_engine.a` as undefined
+/// `mooncake::tent::*` symbols; CMake wraps them in `--start-group`.
+fn collect_tent_archives(root: &Path, libs: &mut Vec<(PathBuf, String)>) {
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(entries) = fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
+                continue;
+            };
+            if path.is_dir() {
+                if matches!(name, "CMakeFiles" | "target" | ".git") {
+                    continue;
+                }
+                stack.push(path);
+                continue;
+            }
+            let Some(lib) = name.strip_prefix("lib").and_then(|n| n.strip_suffix(".a")) else {
+                continue;
+            };
+            if !is_tent_archive(lib) || libs.iter().any(|(_, existing)| existing == lib) {
+                continue;
+            }
+            if let Some(parent) = path.parent() {
+                libs.push((parent.to_path_buf(), lib.to_string()));
+            }
+        }
+    }
+}
+
+fn tent_archive_sort(a: &(PathBuf, String), b: &(PathBuf, String)) -> Ordering {
+    match (a.1.as_str() == "tent", b.1.as_str() == "tent") {
+        (true, false) => Ordering::Less,
+        (false, true) => Ordering::Greater,
+        _ => a.1.cmp(&b.1),
+    }
+}
+
+fn compiler_print_file_name(file_name: &str) -> Option<PathBuf> {
+    for tool in ["cc", "gcc", "clang", "c++"] {
+        let output = match Command::new(tool)
+            .arg(format!("-print-file-name={file_name}"))
+            .output()
+        {
+            Ok(output) if output.status.success() => output,
+            _ => continue,
+        };
+        let Ok(path) = String::from_utf8(output.stdout) else {
+            continue;
+        };
+        let path = PathBuf::from(path.trim());
+        if path.as_os_str().is_empty() || path == PathBuf::from(file_name) || !path.exists() {
+            continue;
+        }
+        return Some(path);
+    }
+    None
+}
+
+fn emit_compiler_runtime_search(file_name: &str) -> bool {
+    let Some(path) = compiler_print_file_name(file_name) else {
+        return false;
+    };
+    let Some(parent) = path.parent() else {
+        return false;
+    };
+
+    println!("cargo:rustc-link-search=native={}", parent.display());
+    true
+}
 
 fn main() {
-    println!("cargo:rustc-link-search=native=../build/src");
-    println!("cargo:rustc-link-search=native=../../build/mooncake-transfer-engine/src");
-    println!("cargo:rustc-link-lib=static=transfer_engine");
-
-    // libbase.a holds mooncake::Status, which libtransfer_engine.a references.
-    println!("cargo:rustc-link-search=native=../build/src/common/base");
-    println!("cargo:rustc-link-search=native=../../build/mooncake-transfer-engine/src/common/base");
-    println!("cargo:rustc-link-lib=static=base");
-
-    // The transfer_engine build uses ASIO_SEPARATE_COMPILATION + ASIO_DYN_LINK,
-    // so the asio symbols live in mooncake-asio/libasio.so.  Link it whenever
-    // we can find it (standalone cmake build places it alongside src/).
-    println!("cargo:rustc-link-search=native=../build/mooncake-asio");
-    println!("cargo:rustc-link-search=native=../../build/mooncake-asio");
-    println!("cargo:rustc-link-lib=asio");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_BUILD_DIR");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_TE_LIB_DIR");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_TE_INCLUDE_DIR");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_WITH_ETCD");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_WITH_CUDA");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_WITHOUT_LIBFABRIC");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_WITH_TENT");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_LINK_ASAN");
+    println!("cargo:rerun-if-env-changed=CUDA_HOME");
+    println!("cargo:rerun-if-env-changed=CUDA_PATH");
+    println!("cargo:rerun-if-env-changed=CUDART_LIB_DIR");
+
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let mut search_dirs = Vec::new();
+    let mut tent_libs: Vec<(PathBuf, String)> = Vec::new();
 
-    // EFA on AWS installs libfabric under /opt/amazon/efa/lib.
-    if std::path::Path::new("/opt/amazon/efa/lib").exists() {
-        println!("cargo:rustc-link-search=native=/opt/amazon/efa/lib");
+    if let Ok(dir) = env::var("MOONCAKE_TE_LIB_DIR") {
+        push_dir(&mut search_dirs, PathBuf::from(dir));
     }
 
-    println!("cargo:rustc-link-lib=stdc++");
-    println!("cargo:rustc-link-lib=ibverbs");
-    // libfabric (fi_*): only needed for EFA transport, but harmless when
-    // the system has it installed; required on AWS EFA hosts.  Opt-out by
-    // setting MOONCAKE_WITHOUT_LIBFABRIC=1 if building on a box without it.
-    if env::var("MOONCAKE_WITHOUT_LIBFABRIC")
-        .map(|v| v == "1" || v.eq_ignore_ascii_case("on") || v.eq_ignore_ascii_case("true"))
-        .unwrap_or(false)
-    {
-        // skip
+    if let Ok(build_dir) = env::var("MOONCAKE_BUILD_DIR") {
+        let build_dir = PathBuf::from(build_dir);
+        for dir in [
+            build_dir.join("mooncake-transfer-engine/src"),
+            build_dir.join("mooncake-transfer-engine/src/common/base"),
+            build_dir.join("mooncake-asio"),
+            build_dir.join("mooncake-common"),
+            build_dir.join("mooncake-common/src"),
+            build_dir.join("mooncake-common/etcd"),
+            build_dir.join("mooncake-transfer-engine/tent/src"),
+            // libtent_metrics.so is a SHARED lib built under tent/src/metrics.
+            // collect_tent_archives skips it (only .a), and has_library's
+            // /usr/local/lib fallback only gates the -l emit, not the -L search
+            // path — so the linker still needs this directory explicitly.
+            build_dir.join("mooncake-transfer-engine/tent/src/metrics"),
+            build_dir.join("src"),
+            build_dir.join("src/common/base"),
+        ] {
+            push_dir(&mut search_dirs, dir);
+        }
+        collect_tent_archives(
+            &build_dir.join("mooncake-transfer-engine/tent"),
+            &mut tent_libs,
+        );
+        collect_tent_archives(&build_dir.join("tent"), &mut tent_libs);
+    }
+
+    // Standalone cargo from mooncake-transfer-engine/rust, after a top-level
+    // or in-tree CMake build.
+    for dir in [
+        manifest_dir.join("../build/src"),
+        manifest_dir.join("../build/src/common/base"),
+        manifest_dir.join("../build/mooncake-asio"),
+        manifest_dir.join("../../build/mooncake-transfer-engine/src"),
+        manifest_dir.join("../../build/mooncake-transfer-engine/src/common/base"),
+        manifest_dir.join("../../build/mooncake-asio"),
+        manifest_dir.join("../../build/mooncake-common"),
+        manifest_dir.join("../../build/mooncake-common/etcd"),
+        manifest_dir.join("../../build/mooncake-transfer-engine/tent/src"),
+        manifest_dir.join("../../build/mooncake-transfer-engine/tent/src/metrics"),
+        manifest_dir.join("../tent/build/src"),
+    ] {
+        push_dir(&mut search_dirs, dir);
+    }
+
+    collect_tent_archives(
+        &manifest_dir.join("../../build/mooncake-transfer-engine/tent"),
+        &mut tent_libs,
+    );
+    collect_tent_archives(&manifest_dir.join("../build"), &mut tent_libs);
+
+    tent_libs.sort_by(tent_archive_sort);
+    for (dir, _) in &tent_libs {
+        push_dir(&mut search_dirs, dir.clone());
+    }
+
+    if Path::new("/opt/amazon/efa/lib").exists() {
+        push_dir(&mut search_dirs, PathBuf::from("/opt/amazon/efa/lib"));
+    }
+
+    if let Ok(dir) = env::var("CUDART_LIB_DIR") {
+        push_dir(&mut search_dirs, PathBuf::from(dir));
+    }
+    let cuda_home = env::var("CUDA_HOME")
+        .or_else(|_| env::var("CUDA_PATH"))
+        .unwrap_or_else(|_| "/usr/local/cuda".to_string());
+    for dir in [
+        PathBuf::from(&cuda_home).join("lib64/stubs"),
+        PathBuf::from(&cuda_home).join("lib64"),
+        PathBuf::from(&cuda_home).join("lib/stubs"),
+        PathBuf::from(&cuda_home).join("lib"),
+    ] {
+        push_dir(&mut search_dirs, dir);
+    }
+
+    emit_link_searches(&search_dirs);
+
+    // Only link the AddressSanitizer runtime when explicitly requested.
+    // Sanitized CI libraries need libasan first; Release builds must not
+    // pull it in (see mooncake-store/rust/build.rs).
+    if flag_on("MOONCAKE_LINK_ASAN") {
+        if let Some(path) = compiler_print_file_name("libasan.so") {
+            if let Some(parent) = path.parent() {
+                println!("cargo:rustc-link-search=native={}", parent.display());
+            }
+        }
+        println!("cargo:rustc-link-lib=asan");
+    }
+
+    let has_mooncake_common = has_library(&search_dirs, "mooncake_common");
+    let link_tent =
+        flag_on("MOONCAKE_WITH_TENT") || tent_libs.iter().any(|(_, name)| name == "tent");
+    if link_tent {
+        // USE_TENT compiles mooncake::tent::* refs into libtransfer_engine.a.
+        // Keep transfer_engine inside the same GNU ld rescan group as CMake's
+        // tent_link_group so archive order cannot drop those symbols.
+        println!("cargo:rustc-link-arg=-Wl,--start-group");
+        println!("cargo:rustc-link-arg=-ltransfer_engine");
+        println!("cargo:rustc-link-arg=-lbase");
+        if tent_libs.is_empty() {
+            println!("cargo:rustc-link-arg=-ltent");
+        } else {
+            for (_, name) in &tent_libs {
+                println!("cargo:rustc-link-arg=-l{name}");
+            }
+        }
+        if has_mooncake_common {
+            println!("cargo:rustc-link-arg=-lmooncake_common");
+        }
+        if has_library(&search_dirs, "tent_metrics") {
+            println!("cargo:rustc-link-arg=-ltent_metrics");
+        }
+        println!("cargo:rustc-link-arg=-Wl,--end-group");
+        println!("cargo:rustc-link-lib=dl");
+        if has_library(&search_dirs, "uring") {
+            println!("cargo:rustc-link-lib=uring");
+        }
     } else {
-        println!("cargo:rustc-link-lib=fabric");
+        println!("cargo:rustc-link-lib=static=transfer_engine");
+        println!("cargo:rustc-link-lib=static=base");
+        if has_mooncake_common {
+            println!("cargo:rustc-link-lib=static=mooncake_common");
+        }
     }
+
+    println!("cargo:rustc-link-lib=asio");
+    println!("cargo:rustc-link-lib=stdc++");
+    println!("cargo:rustc-link-lib=ibverbs");
     println!("cargo:rustc-link-lib=glog");
     println!("cargo:rustc-link-lib=gflags");
     println!("cargo:rustc-link-lib=pthread");
@@ -57,52 +301,93 @@ fn main() {
     println!("cargo:rustc-link-lib=numa");
     println!("cargo:rustc-link-lib=curl");
 
-    let flag_on = |name: &str| {
-        env::var(name)
-            .map(|v| v == "1" || v.eq_ignore_ascii_case("on") || v.eq_ignore_ascii_case("true"))
-            .unwrap_or(false)
-    };
+    if flag_on("MOONCAKE_WITHOUT_LIBFABRIC") {
+        // skip
+    } else if flag_on("MOONCAKE_WITH_LIBFABRIC")
+        || search_dirs.iter().any(|dir| {
+            ["so", "a", "dylib"]
+                .into_iter()
+                .any(|ext| dir.join(format!("libfabric.{ext}")).exists())
+        })
+        || [
+            "/usr/lib/x86_64-linux-gnu/libfabric.so",
+            "/usr/lib64/libfabric.so",
+            "/usr/local/lib/libfabric.so",
+            "/opt/amazon/efa/lib/libfabric.so",
+        ]
+        .into_iter()
+        .any(|path| Path::new(path).exists())
+    {
+        println!("cargo:rustc-link-lib=fabric");
+    }
 
-    // etcd-cpp-api: only needed when transfer_engine was built with
-    // USE_ETCD=ON.  Opt-in via MOONCAKE_WITH_ETCD=1 to keep non-etcd builds
-    // (e.g. EFA-only on AWS) linkable.
-    if flag_on("MOONCAKE_WITH_ETCD") {
-        println!("cargo:rustc-link-lib=etcd-cpp-api");
-    }
-
-    // CUDA runtime: libtransfer_engine.a built with USE_CUDA=ON pulls in
-    // cudaMemcpy/cudaStream* symbols.  The Rust demos themselves don't call
-    // CUDA — this is purely a transitive archive dep.  Enable with
-    // MOONCAKE_WITH_CUDA=1 and optional CUDA_HOME override for lib path.
-    if flag_on("MOONCAKE_WITH_CUDA") {
-        // Accept either a CUDA_HOME (append lib64/lib) or an explicit
-        // CUDART_LIB_DIR that already points at the directory containing
-        // libcudart.so.  This covers both /usr/local/cuda installs and
-        // pip-wheel layouts like .../nvidia/cu13/lib.
-        if let Ok(dir) = env::var("CUDART_LIB_DIR") {
-            println!("cargo:rustc-link-search=native={}", dir);
-        } else if let Ok(cuda_home) = env::var("CUDA_HOME") {
-            let lib64 = PathBuf::from(&cuda_home).join("lib64");
-            let lib = PathBuf::from(&cuda_home).join("lib");
-            if lib64.exists() {
-                println!("cargo:rustc-link-search=native={}", lib64.display());
-            }
-            if lib.exists() {
-                println!("cargo:rustc-link-search=native={}", lib.display());
-            }
-        } else {
-            println!("cargo:rustc-link-search=native=/usr/local/cuda/lib64");
+    println!("cargo:rerun-if-env-changed=MOONCAKE_WITH_LIBFABRIC");
+
+    if has_library(&search_dirs, "yaml-cpp") {
+        println!("cargo:rustc-link-lib=yaml-cpp");
+    }
+
+    // Default CMake USE_ETCD=ON links etcd_wrapper, not etcd-cpp-api.
+    if flag_on("MOONCAKE_WITH_ETCD")
+        || has_library(&search_dirs, "etcd_wrapper")
+        || has_library(&search_dirs, "etcd-cpp-api")
+    {
+        if has_library(&search_dirs, "etcd_wrapper") {
+            println!("cargo:rustc-link-lib=etcd_wrapper");
+        } else if has_library(&search_dirs, "etcd-cpp-api") {
+            println!("cargo:rustc-link-lib=etcd-cpp-api");
+            println!("cargo:rustc-link-lib=cpprest");
+            println!("cargo:rustc-link-lib=ssl");
+            println!("cargo:rustc-link-lib=crypto");
         }
+    }
+
+    if flag_on("MOONCAKE_WITH_CUDA")
+        || has_library(&search_dirs, "cudart")
+        || has_library(&search_dirs, "cuda")
+    {
         println!("cargo:rustc-link-lib=cudart");
+        if has_library(&search_dirs, "cuda") {
+            println!("cargo:rustc-link-lib=cuda");
+        }
+        println!("cargo:rustc-link-lib=rt");
+    }
+
+    for name in ["hiredis", "mlx5"] {
+        if has_library(&search_dirs, name) {
+            println!("cargo:rustc-link-lib={name}");
+        }
+    }
+
+    // Coverage-instrumented C++ archives reference __gcov_* symbols. Cargo
+    // links the Rust test binary directly, so add GCC's static gcov runtime
+    // when it is available. Keep this last: libgcov.a must follow the
+    // instrumented archives on the link line. Non-coverage builds have no
+    // __gcov_* references, so the static archive contributes no objects.
+    if emit_compiler_runtime_search("libgcov.a") || has_static_library(&search_dirs, "gcov") {
+        if link_tent {
+            println!("cargo:rustc-link-arg=-lgcov");
+        } else {
+            println!("cargo:rustc-link-lib=gcov");
+        }
     }
 
-    let bindings = bindgen::builder()
-        .header("../include/transfer_engine_c.h")
+    let include_dir = env::var("MOONCAKE_TE_INCLUDE_DIR").unwrap_or_else(|_| {
+        manifest_dir
+            .join("../include")
+            .to_string_lossy()
+            .into_owned()
+    });
+    let header = format!("{include_dir}/transfer_engine_c.h");
+    println!("cargo:rerun-if-changed={header}");
+
+    let bindings = bindgen::Builder::default()
+        .header(&header)
         .generate()
-        .expect("Unable to generate bindings");
+        .expect("Unable to generate Transfer Engine bindings");
 
     let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
     bindings
         .write_to_file(out_path.join("bindings.rs"))
-        .expect("Couldn't write bindings!");
+        .expect("Couldn't write bindings");
 }
diff --git a/mooncake-transfer-engine/rust/src/main.rs b/mooncake-transfer-engine/rust/examples/transfer_engine_bench.rs
similarity index 74%
rename from mooncake-transfer-engine/rust/src/main.rs
rename to mooncake-transfer-engine/rust/examples/transfer_engine_bench.rs
index cc3a7290e8..6f0dba42d4 100644
--- a/mooncake-transfer-engine/rust/src/main.rs
+++ b/mooncake-transfer-engine/rust/examples/transfer_engine_bench.rs
@@ -12,31 +12,42 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-mod memory_pool;
-mod transfer_engine;
+//! Transfer Engine throughput benchmark (initiator / target), analogous to
+//! `transfer_engine_bench.cpp`.
+//!
+//! ```bash
+//! cargo run --example transfer_engine_bench --release -- \
+//!   --metadata-server http://127.0.0.1:8080/metadata \
+//!   --mode target
+//! cargo run --example transfer_engine_bench --release -- \
+//!   --metadata-server http://127.0.0.1:8080/metadata \
+//!   --mode initiator --segment-id <target-ip>
+//! ```
 
 use anyhow::{anyhow, bail, Result};
 use clap::Parser;
 use dns_lookup::{get_hostname, getaddrinfo, AddrInfoHints, SockType};
+use std::net::IpAddr;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::Arc;
 use std::thread;
-use std::time::Duration;
-use std::{net::IpAddr, time::Instant};
+use std::time::{Duration, Instant};
 use tracing::{error, info};
-use transfer_engine::{OpcodeEnum, TransferEngine, TransferRequest, TransferStatusEnum};
+use transfer_engine_rust::{
+    MemoryPool, Opcode, TransferEngine, TransferRequest, TransferStatusCode,
+};
 
 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None)]
 pub struct Args {
-    #[clap(long, default_value_t = String::from("localhost:2379"), help = "etcd server host address")]
+    #[clap(long, default_value_t = String::from("localhost:2379"), help = "etcd / metadata server address")]
     pub metadata_server: String,
 
-    #[clap(long, default_value_t = String::from("initiator"), value_parser = ["initiator", "target"], 
+    #[clap(long, default_value_t = String::from("initiator"), value_parser = ["initiator", "target"],
     help = "Running mode: initiator or target. Initiator node read/write data blocks from target node")]
     pub mode: String,
 
-    #[clap(long, default_value_t = String::from("read"), value_parser = ["read", "write"], 
+    #[clap(long, default_value_t = String::from("read"), value_parser = ["read", "write"],
     help = "Operation type: read or write")]
     pub operation: String,
 
@@ -61,6 +72,9 @@ pub struct Args {
 
     #[clap(long, default_value_t = 4, help = "Task submission threads")]
     pub threads: i32,
+
+    #[clap(long, default_value_t = String::from("tcp"), help = "Transport protocol (tcp, rdma, efa)")]
+    pub protocol: String,
 }
 
 fn get_host_ip() -> Result<String> {
@@ -88,7 +102,6 @@ fn get_host_ip() -> Result<String> {
     bail!("No non-loopback IP address found")
 }
 
-/// Allocate memory pool of the given size.
 fn allocate_memory_pool(size: usize) -> *mut u8 {
     let mut buffer = vec![0u8; size].into_boxed_slice();
     let ptr = buffer.as_mut_ptr();
@@ -96,7 +109,6 @@ fn allocate_memory_pool(size: usize) -> *mut u8 {
     ptr
 }
 
-/// Free the allocated memory pool.
 unsafe fn free_memory_pool(ptr: *mut u8, size: usize) {
     if !ptr.is_null() {
         let _buffer = Vec::from_raw_parts(ptr, size, size);
@@ -110,12 +122,12 @@ fn initiator_worker(
     engine: Arc<TransferEngine>,
     segment_id: i32,
     thread_id: i32,
-    pool: Arc<memory_pool::MemoryPool>,
+    pool: Arc<MemoryPool>,
     total_batch_count: Arc<AtomicUsize>,
 ) -> Result<()> {
     let opcode = match args.operation.as_str() {
-        "read" => OpcodeEnum::Read,
-        "write" => OpcodeEnum::Write,
+        "read" => Opcode::Read,
+        "write" => Opcode::Write,
         _ => bail!("Unsupported operation: must be 'read' or 'write'"),
     };
     while RUNNING.load(Ordering::SeqCst) {
@@ -125,23 +137,22 @@ fn initiator_worker(
             let source_offset = args.block_size * (i * args.threads + thread_id);
             requests.push(TransferRequest {
                 opcode,
-                source: pool.offset(source_offset as isize) as *mut _,
+                source: pool.offset(source_offset as usize) as *mut _,
                 target_id: segment_id,
                 target_offset: args.target_base + source_offset as u64,
                 length: args.block_size as u64,
             });
         }
 
-        engine.submit_transfer(batch_id, &mut requests)?;
+        unsafe { engine.submit_transfer(batch_id, &requests)? };
 
-        for task_id in 0..args.batch_size {
-            let mut completed = false;
-            while !completed {
-                let (status, _) = engine.get_transfer_status(batch_id, task_id as u64)?;
-                if status == TransferStatusEnum::Completed as i32
-                    || status == TransferStatusEnum::Failed as i32
+        for task_id in 0..args.batch_size as usize {
+            loop {
+                let status = engine.get_transfer_status(batch_id, task_id)?;
+                if status.status == TransferStatusCode::Completed
+                    || status.status == TransferStatusCode::Failed
                 {
-                    completed = true;
+                    break;
                 }
             }
         }
@@ -155,17 +166,21 @@ fn initiator_worker(
 
 fn initiator(args: Args) -> Result<()> {
     let args = Arc::new(args);
-    let engine = Arc::new(TransferEngine::new(
+    let local = get_host_ip()?;
+    let engine = Arc::new(TransferEngine::initialize(
+        &format!("{local}:12345"),
         &args.metadata_server,
-        &get_host_ip()?,
-        12345,
+        &args.protocol,
+        "",
     )?);
 
     let dram_buffer_size = 1 << 30;
-    let pool = Arc::new(memory_pool::MemoryPool::new(dram_buffer_size));
-    engine.register_local_memory(pool.offset(0) as *mut _, dram_buffer_size, "cpu:0")?;
+    let pool = Arc::new(MemoryPool::new(dram_buffer_size));
+    unsafe {
+        engine.register_local_memory(pool.as_void_ptr(), dram_buffer_size, "cpu:0")?;
+    }
 
-    let segment_id = engine.open_segment(args.segment_id.clone())?;
+    let segment_id = engine.open_segment(&args.segment_id)?;
     let total_batch_count = Arc::new(AtomicUsize::new(0));
     let start_time = Instant::now();
     let mut workers = vec![];
@@ -187,7 +202,7 @@ fn initiator(args: Args) -> Result<()> {
     }
 
     thread::sleep(Duration::from_secs(args.duration as u64));
-    RUNNING.store(false, std::sync::atomic::Ordering::SeqCst);
+    RUNNING.store(false, Ordering::SeqCst);
 
     for worker in workers {
         worker.join().unwrap()?;
@@ -203,22 +218,28 @@ fn initiator(args: Args) -> Result<()> {
         (batch_count * args.batch_size as usize * args.block_size as usize) as f64 / duration / 1e9
     );
 
-    engine.unregister_local_memory(pool.offset(0) as *mut _)?;
+    unsafe {
+        engine.unregister_local_memory(pool.as_void_ptr())?;
+    }
 
     Ok(())
 }
 
 fn target(args: Args) -> Result<()> {
-    let engine = TransferEngine::new(
+    let local = get_host_ip()?;
+    let engine = TransferEngine::initialize(
+        &format!("{local}:12345"),
         &args.metadata_server,
-        &get_host_ip()?,
-        12345,
+        &args.protocol,
+        "",
     )?;
 
     let dram_buffer_size = 1 << 30;
     let addr = allocate_memory_pool(dram_buffer_size);
 
-    engine.register_local_memory(addr as *mut _, dram_buffer_size, "cpu:0")?;
+    unsafe {
+        engine.register_local_memory(addr as *mut _, dram_buffer_size, "cpu:0")?;
+    }
 
     loop {
         thread::sleep(Duration::from_secs(1));
@@ -226,8 +247,8 @@ fn target(args: Args) -> Result<()> {
 
     #[allow(unreachable_code)]
     {
-        engine.unregister_local_memory(addr as *mut _)?;
         unsafe {
+            engine.unregister_local_memory(addr as *mut _)?;
             free_memory_pool(addr, dram_buffer_size);
         }
         Ok(())
@@ -235,6 +256,7 @@ fn target(args: Args) -> Result<()> {
 }
 
 fn main() {
+    tracing_subscriber::fmt::init();
     let args = Args::parse();
     info!("args: {:?}", args);
 
diff --git a/mooncake-transfer-engine/rust/src/engine.rs b/mooncake-transfer-engine/rust/src/engine.rs
new file mode 100644
index 0000000000..9ede348290
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/engine.rs
@@ -0,0 +1,780 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! Safe, zero-copy wrapper around the Transfer Engine C API.
+
+use std::collections::HashMap;
+use std::ffi::{c_void, CStr, CString};
+use std::os::raw::c_char;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use crate::error::EngineError;
+use crate::ffi;
+use crate::types::{
+    BatchId, BufferEntry, NicLoadStat, NotifyMsg, Opcode, SegmentId, TransferRequest,
+    TransferStatus, TransferStatusCode, INVALID_BATCH, WILDCARD_LOCATION,
+};
+
+/// Options for [`TransferEngine::create`].
+#[derive(Debug, Clone)]
+pub struct TransferEngineOptions<'a> {
+    pub metadata_uri: &'a str,
+    pub local_server_name: &'a str,
+    pub ip_or_host_name: &'a str,
+    pub rpc_port: u64,
+    pub auto_discover: bool,
+}
+
+impl<'a> TransferEngineOptions<'a> {
+    pub fn new(metadata_uri: &'a str, local_server_name: &'a str) -> Self {
+        Self {
+            metadata_uri,
+            local_server_name,
+            ip_or_host_name: local_server_name,
+            rpc_port: 0,
+            auto_discover: false,
+        }
+    }
+
+    pub fn ip_or_host_name(mut self, value: &'a str) -> Self {
+        self.ip_or_host_name = value;
+        self
+    }
+
+    pub fn rpc_port(mut self, value: u64) -> Self {
+        self.rpc_port = value;
+        self
+    }
+
+    pub fn auto_discover(mut self, value: bool) -> Self {
+        self.auto_discover = value;
+        self
+    }
+}
+
+/// Handle to a Transfer Engine instance.
+///
+/// The underlying C object is internally synchronized, so the handle is
+/// `Send + Sync`. Registered memory must remain valid until unregistered.
+///
+/// Hot-path methods (`submit_transfer`, `get_transfer_status`, `wait_all`)
+/// do not allocate.
+pub struct TransferEngine {
+    engine: ffi::transfer_engine_t,
+    segments: Mutex<HashMap<String, SegmentId>>,
+}
+
+// The C++ Transfer Engine serializes metadata and completion internally.
+unsafe impl Send for TransferEngine {}
+unsafe impl Sync for TransferEngine {}
+
+impl TransferEngine {
+    /// Create an engine with `auto_discover` disabled. `local_server_name` is
+    /// also used as `ip_or_host_name`.
+    pub fn new(
+        metadata_uri: &str,
+        local_server_name: &str,
+        rpc_port: u64,
+    ) -> Result<Self, EngineError> {
+        Self::create(TransferEngineOptions::new(metadata_uri, local_server_name).rpc_port(rpc_port))
+    }
+
+    /// Create an engine from explicit options.
+    pub fn create(opts: TransferEngineOptions<'_>) -> Result<Self, EngineError> {
+        let metadata_uri_c = CString::new(opts.metadata_uri)?;
+        let local_server_name_c = CString::new(opts.local_server_name)?;
+        let ip_or_host_name_c = CString::new(opts.ip_or_host_name)?;
+        let engine = unsafe {
+            ffi::createTransferEngine(
+                metadata_uri_c.as_ptr(),
+                local_server_name_c.as_ptr(),
+                ip_or_host_name_c.as_ptr(),
+                opts.rpc_port,
+                i32::from(opts.auto_discover),
+            )
+        };
+        if engine.is_null() {
+            return Err(EngineError::NullHandle);
+        }
+        Ok(Self {
+            engine,
+            segments: Mutex::new(HashMap::new()),
+        })
+    }
+
+    /// Python-style constructor: create the engine and install `protocol`.
+    ///
+    /// `local_hostname` may be `"host:port"`. For `"rdma"`, topology
+    /// auto-discovery is enabled and no extra transport is installed. For
+    /// `"tcp"` / `"efa"` / `"cxi"`, the named transport is installed
+    /// explicitly. `device_name` is accepted for API compatibility; set
+    /// `MC_TE_FILTERS` to restrict NICs (the C ABI has no device-name argument).
+    pub fn initialize(
+        local_hostname: &str,
+        metadata_server: &str,
+        protocol: &str,
+        _device_name: &str,
+    ) -> Result<Self, EngineError> {
+        let (host, port) = parse_host_port(local_hostname);
+        let auto = protocol.eq_ignore_ascii_case("rdma");
+        let engine = Self::create(
+            TransferEngineOptions::new(metadata_server, local_hostname)
+                .ip_or_host_name(&host)
+                .rpc_port(port)
+                .auto_discover(auto),
+        )?;
+        if !auto {
+            if protocol.eq_ignore_ascii_case("efa") || protocol.eq_ignore_ascii_case("cxi") {
+                engine.discover_topology()?;
+            }
+            engine.install_transport(protocol)?;
+        }
+        Ok(engine)
+    }
+
+    fn check_rc(rc: i32) -> Result<(), EngineError> {
+        if rc != 0 {
+            Err(EngineError::OperationFailed(rc))
+        } else {
+            Ok(())
+        }
+    }
+
+    fn check_nonneg(rc: i32) -> Result<i32, EngineError> {
+        if rc < 0 {
+            Err(EngineError::OperationFailed(rc))
+        } else {
+            Ok(rc)
+        }
+    }
+
+    pub fn discover_topology(&self) -> Result<(), EngineError> {
+        let rc = unsafe { ffi::discoverTopology(self.engine) };
+        Self::check_rc(rc)
+    }
+
+    pub fn local_ip_and_port(&self) -> Result<String, EngineError> {
+        let mut buf = [0u8; 256];
+        let rc = unsafe {
+            ffi::getLocalIpAndPort(self.engine, buf.as_mut_ptr() as *mut c_char, buf.len())
+        };
+        Self::check_rc(rc)?;
+        let cstr = unsafe { CStr::from_ptr(buf.as_ptr() as *const c_char) };
+        Ok(cstr.to_string_lossy().into_owned())
+    }
+
+    pub fn install_transport(&self, proto: &str) -> Result<(), EngineError> {
+        let proto_c = CString::new(proto)?;
+        let handle =
+            unsafe { ffi::installTransport(self.engine, proto_c.as_ptr(), std::ptr::null_mut()) };
+        if handle.is_null() {
+            Err(EngineError::OperationFailed(-1))
+        } else {
+            Ok(())
+        }
+    }
+
+    pub fn uninstall_transport(&self, proto: &str) -> Result<(), EngineError> {
+        let proto_c = CString::new(proto)?;
+        let rc = unsafe { ffi::uninstallTransport(self.engine, proto_c.as_ptr()) };
+        Self::check_rc(rc)
+    }
+
+    pub fn open_segment(&self, name: &str) -> Result<SegmentId, EngineError> {
+        let name_c = CString::new(name)?;
+        let id = unsafe { ffi::openSegment(self.engine, name_c.as_ptr()) };
+        Self::check_nonneg(id)
+    }
+
+    pub fn open_segment_no_cache(&self, name: &str) -> Result<SegmentId, EngineError> {
+        let name_c = CString::new(name)?;
+        let id = unsafe { ffi::openSegmentNoCache(self.engine, name_c.as_ptr()) };
+        Self::check_nonneg(id)
+    }
+
+    /// Open `name`, caching the segment id for later [`Self::segment`] lookups.
+    pub fn open_segment_cached(&self, name: &str) -> Result<SegmentId, EngineError> {
+        {
+            let guard = self.segments.lock().unwrap_or_else(|e| e.into_inner());
+            if let Some(&id) = guard.get(name) {
+                return Ok(id);
+            }
+        }
+        let id = self.open_segment(name)?;
+        let mut guard = self.segments.lock().unwrap_or_else(|e| e.into_inner());
+        guard.insert(name.to_string(), id);
+        Ok(id)
+    }
+
+    pub fn close_segment(&self, segment_id: SegmentId) -> Result<(), EngineError> {
+        let rc = unsafe { ffi::closeSegment(self.engine, segment_id) };
+        Self::check_rc(rc)
+    }
+
+    pub fn warmup_efa_segment(&self, name: &str) -> Result<(), EngineError> {
+        let name_c = CString::new(name)?;
+        let rc = unsafe { ffi::warmupEfaSegment(self.engine, name_c.as_ptr()) };
+        Self::check_rc(rc)
+    }
+
+    pub fn remove_local_segment(&self, name: &str) -> Result<(), EngineError> {
+        let name_c = CString::new(name)?;
+        let rc = unsafe { ffi::removeLocalSegment(self.engine, name_c.as_ptr()) };
+        Self::check_rc(rc)
+    }
+
+    /// Register `addr..addr+length` for transfers. `location` is typically
+    /// `"cpu:0"` or [`WILDCARD_LOCATION`].
+    ///
+    /// # Safety
+    ///
+    /// `addr` must point to at least `length` bytes that remain valid until
+    /// [`Self::unregister_local_memory`].
+    pub unsafe fn register_local_memory(
+        &self,
+        addr: *mut c_void,
+        length: usize,
+        location: &str,
+    ) -> Result<(), EngineError> {
+        self.register_local_memory_ex(addr, length, location, true)
+    }
+
+    /// Like [`Self::register_local_memory`], with an explicit `remote_accessible` flag.
+    ///
+    /// # Safety
+    ///
+    /// Same requirements as [`Self::register_local_memory`].
+    pub unsafe fn register_local_memory_ex(
+        &self,
+        addr: *mut c_void,
+        length: usize,
+        location: &str,
+        remote_accessible: bool,
+    ) -> Result<(), EngineError> {
+        let location_c = CString::new(location)?;
+        let rc = ffi::registerLocalMemory(
+            self.engine,
+            addr,
+            length,
+            location_c.as_ptr(),
+            i32::from(remote_accessible),
+        );
+        Self::check_rc(rc)
+    }
+
+    /// Python-compatible alias of [`Self::register_local_memory`] using
+    /// [`WILDCARD_LOCATION`].
+    ///
+    /// # Safety
+    ///
+    /// Same requirements as [`Self::register_local_memory`].
+    pub unsafe fn register_memory(
+        &self,
+        addr: *mut c_void,
+        length: usize,
+    ) -> Result<(), EngineError> {
+        self.register_local_memory(addr, length, WILDCARD_LOCATION)
+    }
+
+    /// # Safety
+    ///
+    /// `addr` must be a pointer previously passed to `register_local_memory`.
+    pub unsafe fn unregister_local_memory(&self, addr: *mut c_void) -> Result<(), EngineError> {
+        let rc = ffi::unregisterLocalMemory(self.engine, addr);
+        Self::check_rc(rc)
+    }
+
+    /// # Safety
+    ///
+    /// Same as [`Self::unregister_local_memory`].
+    pub unsafe fn unregister_memory(&self, addr: *mut c_void) -> Result<(), EngineError> {
+        self.unregister_local_memory(addr)
+    }
+
+    /// Batch-register buffers. Zero-copy: `buffer_list` is passed to C as-is.
+    ///
+    /// # Safety
+    ///
+    /// Each entry must satisfy [`Self::register_local_memory`].
+    pub unsafe fn register_local_memory_batch(
+        &self,
+        buffer_list: &[BufferEntry],
+        location: &str,
+    ) -> Result<(), EngineError> {
+        if buffer_list.is_empty() {
+            return Ok(());
+        }
+        let location_c = CString::new(location)?;
+        let rc = ffi::registerLocalMemoryBatch(
+            self.engine,
+            buffer_list.as_ptr() as *mut ffi::buffer_entry_t,
+            buffer_list.len(),
+            location_c.as_ptr(),
+        );
+        Self::check_rc(rc)
+    }
+
+    /// # Safety
+    ///
+    /// Each address must have been registered.
+    pub unsafe fn unregister_local_memory_batch(
+        &self,
+        addrs: &[*mut c_void],
+    ) -> Result<(), EngineError> {
+        if addrs.is_empty() {
+            return Ok(());
+        }
+        let mut addr_list = addrs.to_vec();
+        let rc =
+            ffi::unregisterLocalMemoryBatch(self.engine, addr_list.as_mut_ptr(), addr_list.len());
+        Self::check_rc(rc)
+    }
+
+    pub fn allocate_batch_id(&self, batch_size: usize) -> Result<BatchId, EngineError> {
+        let id = unsafe { ffi::allocateBatchID(self.engine, batch_size) };
+        if id == INVALID_BATCH {
+            Err(EngineError::OperationFailed(-1))
+        } else {
+            Ok(BatchId(id))
+        }
+    }
+
+    /// Submit `requests` without allocating. `TransferRequest` is `#[repr(C)]`
+    /// and matches `transfer_request_t`.
+    ///
+    /// # Safety
+    ///
+    /// Every `source` pointer must refer to registered memory that stays valid
+    /// until the batch completes.
+    pub unsafe fn submit_transfer(
+        &self,
+        batch_id: BatchId,
+        requests: &[TransferRequest],
+    ) -> Result<(), EngineError> {
+        if requests.is_empty() {
+            return Ok(());
+        }
+        let rc = ffi::submitTransfer(
+            self.engine,
+            batch_id.0,
+            requests.as_ptr() as *mut ffi::transfer_request_t,
+            requests.len(),
+        );
+        Self::check_rc(rc)
+    }
+
+    /// Submit plus a completion notification to the peer.
+    ///
+    /// # Safety
+    ///
+    /// Same requirements as [`Self::submit_transfer`].
+    pub unsafe fn submit_transfer_with_notify(
+        &self,
+        batch_id: BatchId,
+        requests: &[TransferRequest],
+        notify: &NotifyMsg,
+    ) -> Result<(), EngineError> {
+        if requests.is_empty() {
+            return Ok(());
+        }
+        let name_c = CString::new(notify.name.as_str())?;
+        let msg_c = CString::new(notify.msg.as_str())?;
+        let notify_c = ffi::notify_msg_t {
+            name: name_c.as_ptr() as *mut c_char,
+            msg: msg_c.as_ptr() as *mut c_char,
+        };
+        let rc = ffi::submitTransferWithNotify(
+            self.engine,
+            batch_id.0,
+            requests.as_ptr() as *mut ffi::transfer_request_t,
+            requests.len(),
+            notify_c,
+        );
+        Self::check_rc(rc)
+    }
+
+    pub fn get_transfer_status(
+        &self,
+        batch_id: BatchId,
+        task_id: usize,
+    ) -> Result<TransferStatus, EngineError> {
+        let mut status = TransferStatus {
+            status: TransferStatusCode::Waiting,
+            transferred_bytes: 0,
+        };
+        let rc = unsafe {
+            ffi::getTransferStatus(
+                self.engine,
+                batch_id.0,
+                task_id,
+                &mut status as *mut TransferStatus as *mut ffi::transfer_status_t,
+            )
+        };
+        Self::check_rc(rc)?;
+        Ok(status)
+    }
+
+    /// Poll every task in `0..count` until all are terminal, or `timeout`.
+    /// Does not allocate. Does not free the batch id.
+    pub fn wait_all(
+        &self,
+        batch_id: BatchId,
+        count: usize,
+        timeout: Option<Duration>,
+    ) -> Result<(), EngineError> {
+        let deadline = timeout.map(|d| Instant::now() + d);
+        for task_id in 0..count {
+            loop {
+                let status = self.get_transfer_status(batch_id, task_id)?;
+                match status.status {
+                    TransferStatusCode::Completed => break,
+                    TransferStatusCode::Failed
+                    | TransferStatusCode::Timeout
+                    | TransferStatusCode::Canceled
+                    | TransferStatusCode::Invalid => {
+                        return Err(EngineError::TransferFailed);
+                    }
+                    _ => {
+                        if deadline.is_some_and(|d| Instant::now() >= d) {
+                            return Err(EngineError::Timeout);
+                        }
+                        std::hint::spin_loop();
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Allocate a batch, submit `requests`, wait, then free the batch.
+    ///
+    /// # Safety
+    ///
+    /// Same requirements as [`Self::submit_transfer`].
+    pub unsafe fn submit_and_wait(
+        &self,
+        requests: &[TransferRequest],
+        timeout: Option<Duration>,
+    ) -> Result<(), EngineError> {
+        if requests.is_empty() {
+            return Ok(());
+        }
+        let batch_id = self.allocate_batch_id(requests.len())?;
+        let result = (|| {
+            self.submit_transfer(batch_id, requests)?;
+            self.wait_all(batch_id, requests.len(), timeout)
+        })();
+        let _ = self.free_batch_id(batch_id);
+        result
+    }
+
+    pub fn free_batch_id(&self, batch_id: BatchId) -> Result<(), EngineError> {
+        let rc = unsafe { ffi::freeBatchID(self.engine, batch_id.0) };
+        Self::check_rc(rc)
+    }
+
+    pub fn sync_segment_cache(&self) -> Result<(), EngineError> {
+        let rc = unsafe { ffi::syncSegmentCache(self.engine) };
+        Self::check_rc(rc)
+    }
+
+    pub fn take_notifies(&self) -> Result<Vec<NotifyMsg>, EngineError> {
+        let mut size: i32 = 0;
+        let ptr = unsafe { ffi::getNotifsFromEngine(self.engine, &mut size) };
+        if ptr.is_null() {
+            return Ok(Vec::new());
+        }
+        let slice = unsafe { std::slice::from_raw_parts(ptr, size as usize) };
+        let mut out = Vec::with_capacity(slice.len());
+        for msg in slice {
+            let name = unsafe { CStr::from_ptr(msg.name) }
+                .to_string_lossy()
+                .into_owned();
+            let text = unsafe { CStr::from_ptr(msg.msg) }
+                .to_string_lossy()
+                .into_owned();
+            out.push(NotifyMsg { name, msg: text });
+        }
+        unsafe {
+            ffi::freeNotifsMsgBuf(ptr, size);
+        }
+        Ok(out)
+    }
+
+    pub fn send_notify(&self, target_id: u64, notify: &NotifyMsg) -> Result<(), EngineError> {
+        let name_c = CString::new(notify.name.as_str())?;
+        let msg_c = CString::new(notify.msg.as_str())?;
+        let notify_c = ffi::notify_msg_t {
+            name: name_c.as_ptr() as *mut c_char,
+            msg: msg_c.as_ptr() as *mut c_char,
+        };
+        let rc = unsafe { ffi::genNotifyInEngine(self.engine, target_id, notify_c) };
+        Self::check_rc(rc)
+    }
+
+    pub fn nic_load_stats(&self) -> Result<Vec<NicLoadStat>, EngineError> {
+        const FIRST: usize = 32;
+        let mut stats: Vec<ffi::nic_load_stat_t> =
+            (0..FIRST).map(|_| unsafe { std::mem::zeroed() }).collect();
+        let mut count = FIRST;
+        let rc = unsafe { ffi::getNicLoadStats(self.engine, stats.as_mut_ptr(), &mut count) };
+        Self::check_rc(rc)?;
+        if count > FIRST {
+            stats.resize_with(count, || unsafe { std::mem::zeroed() });
+            let mut recount = count;
+            let rc = unsafe { ffi::getNicLoadStats(self.engine, stats.as_mut_ptr(), &mut recount) };
+            Self::check_rc(rc)?;
+            count = recount.min(stats.len());
+        }
+        Ok(stats
+            .into_iter()
+            .take(count)
+            .map(|s| {
+                let name = unsafe { CStr::from_ptr(s.device_name.as_ptr()) }
+                    .to_string_lossy()
+                    .into_owned();
+                NicLoadStat {
+                    device_name: name,
+                    inflight_bytes: s.inflight_bytes,
+                    ewma_bandwidth_bps: s.ewma_bandwidth_bps,
+                }
+            })
+            .collect())
+    }
+
+    pub fn enable_graceful_shutdown(&self) {
+        unsafe { ffi::enableGracefulShutdown(self.engine) };
+    }
+
+    pub fn show_links(&self, json: bool) -> Result<String, EngineError> {
+        let mut buf = vec![0u8; 65_536];
+        let rc = unsafe {
+            ffi::showLinks(
+                self.engine,
+                buf.as_mut_ptr() as *mut c_char,
+                buf.len(),
+                i32::from(json),
+            )
+        };
+        Self::check_rc(rc)?;
+        let cstr = unsafe { CStr::from_ptr(buf.as_ptr() as *const c_char) };
+        Ok(cstr.to_string_lossy().into_owned())
+    }
+
+    // -----------------------------------------------------------------------
+    // Python-shaped convenience transfers (hostname → cached segment id)
+    // -----------------------------------------------------------------------
+
+    /// Synchronous write of `length` bytes from `local` to `remote_offset` on
+    /// `target_hostname`.
+    ///
+    /// # Safety
+    ///
+    /// `local` must be registered and remain valid for the duration of the call.
+    pub unsafe fn transfer_sync_write(
+        &self,
+        target_hostname: &str,
+        local: *mut c_void,
+        remote_offset: u64,
+        length: u64,
+    ) -> Result<(), EngineError> {
+        self.transfer_sync(target_hostname, local, remote_offset, length, Opcode::Write)
+    }
+
+    /// Synchronous read of `length` bytes from `remote_offset` on
+    /// `target_hostname` into `local`.
+    ///
+    /// # Safety
+    ///
+    /// `local` must be registered and remain valid for the duration of the call.
+    pub unsafe fn transfer_sync_read(
+        &self,
+        target_hostname: &str,
+        local: *mut c_void,
+        remote_offset: u64,
+        length: u64,
+    ) -> Result<(), EngineError> {
+        self.transfer_sync(target_hostname, local, remote_offset, length, Opcode::Read)
+    }
+
+    /// # Safety
+    ///
+    /// `local` must be registered and remain valid for the duration of the call.
+    pub unsafe fn transfer_sync(
+        &self,
+        target_hostname: &str,
+        local: *mut c_void,
+        remote_offset: u64,
+        length: u64,
+        opcode: Opcode,
+    ) -> Result<(), EngineError> {
+        let target_id = self.open_segment_cached(target_hostname)?;
+        let req = TransferRequest {
+            opcode,
+            source: local,
+            target_id,
+            target_offset: remote_offset,
+            length,
+        };
+        self.submit_and_wait(&[req], None)
+    }
+
+    /// Batch synchronous transfer. Slice lengths must match.
+    ///
+    /// # Safety
+    ///
+    /// Every local pointer must be registered and remain valid.
+    pub unsafe fn batch_transfer_sync(
+        &self,
+        target_hostname: &str,
+        locals: &[*mut c_void],
+        remote_offsets: &[u64],
+        lengths: &[u64],
+        opcode: Opcode,
+    ) -> Result<(), EngineError> {
+        if locals.len() != remote_offsets.len() || locals.len() != lengths.len() {
+            return Err(EngineError::InvalidArgument(
+                "locals, remote_offsets, and lengths must have the same length",
+            ));
+        }
+        if locals.is_empty() {
+            return Ok(());
+        }
+        let target_id = self.open_segment_cached(target_hostname)?;
+        let mut reqs = Vec::with_capacity(locals.len());
+        for i in 0..locals.len() {
+            reqs.push(TransferRequest {
+                opcode,
+                source: locals[i],
+                target_id,
+                target_offset: remote_offsets[i],
+                length: lengths[i],
+            });
+        }
+        self.submit_and_wait(&reqs, None)
+    }
+
+    pub unsafe fn batch_transfer_sync_write(
+        &self,
+        target_hostname: &str,
+        locals: &[*mut c_void],
+        remote_offsets: &[u64],
+        lengths: &[u64],
+    ) -> Result<(), EngineError> {
+        self.batch_transfer_sync(
+            target_hostname,
+            locals,
+            remote_offsets,
+            lengths,
+            Opcode::Write,
+        )
+    }
+
+    pub unsafe fn batch_transfer_sync_read(
+        &self,
+        target_hostname: &str,
+        locals: &[*mut c_void],
+        remote_offsets: &[u64],
+        lengths: &[u64],
+    ) -> Result<(), EngineError> {
+        self.batch_transfer_sync(
+            target_hostname,
+            locals,
+            remote_offsets,
+            lengths,
+            Opcode::Read,
+        )
+    }
+
+    /// Submit an async write and return the batch id. Caller must
+    /// [`Self::free_batch_id`] after completion.
+    ///
+    /// # Safety
+    ///
+    /// `local` must be registered until the batch completes.
+    pub unsafe fn transfer_submit_write(
+        &self,
+        target_hostname: &str,
+        local: *mut c_void,
+        remote_offset: u64,
+        length: u64,
+    ) -> Result<BatchId, EngineError> {
+        let target_id = self.open_segment_cached(target_hostname)?;
+        let batch_id = self.allocate_batch_id(1)?;
+        let req = TransferRequest::write(local, target_id, remote_offset, length);
+        if let Err(e) = self.submit_transfer(batch_id, &[req]) {
+            let _ = self.free_batch_id(batch_id);
+            return Err(e);
+        }
+        Ok(batch_id)
+    }
+
+    /// Python-compatible status poll: `Completed`, `Failed`/`Timeout`/`Invalid`
+    /// are terminal. Does **not** free the batch (unlike the Python wrapper);
+    /// call [`Self::free_batch_id`] after a terminal status.
+    pub fn transfer_check_status(
+        &self,
+        batch_id: BatchId,
+    ) -> Result<TransferStatusCode, EngineError> {
+        Ok(self.get_transfer_status(batch_id, 0)?.status)
+    }
+}
+
+impl Drop for TransferEngine {
+    fn drop(&mut self) {
+        if !self.engine.is_null() {
+            unsafe { ffi::destroyTransferEngine(self.engine) };
+            self.engine = std::ptr::null_mut();
+        }
+    }
+}
+
+fn parse_host_port(local_hostname: &str) -> (String, u64) {
+    if let Some(stripped) = local_hostname.strip_prefix('[') {
+        if let Some((host, rest)) = stripped.split_once("]:") {
+            if let Ok(port) = rest.parse::<u64>() {
+                return (host.to_string(), port);
+            }
+        }
+        return (local_hostname.to_string(), 0);
+    }
+    if let Some((host, port)) = local_hostname.rsplit_once(':') {
+        if !host.is_empty() {
+            if let Ok(p) = port.parse::<u64>() {
+                return (host.to_string(), p);
+            }
+        }
+    }
+    (local_hostname.to_string(), 0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::parse_host_port;
+
+    #[test]
+    fn parse_host_port_splits_ipv4() {
+        assert_eq!(
+            parse_host_port("127.0.0.1:12345"),
+            ("127.0.0.1".into(), 12345)
+        );
+        assert_eq!(parse_host_port("localhost"), ("localhost".into(), 0));
+        assert_eq!(
+            parse_host_port("host:notaport"),
+            ("host:notaport".into(), 0)
+        );
+        assert_eq!(parse_host_port("[::1]:12345"), ("::1".into(), 12345));
+    }
+}
diff --git a/mooncake-transfer-engine/rust/src/error.rs b/mooncake-transfer-engine/rust/src/error.rs
new file mode 100644
index 0000000000..f9ffd39416
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/error.rs
@@ -0,0 +1,48 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+use std::ffi::NulError;
+
+/// Errors returned by Transfer Engine operations.
+///
+/// `#[non_exhaustive]` so adding variants is not a breaking change; downstream
+/// matches must include a wildcard arm.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum EngineError {
+    /// The C layer failed to allocate a Transfer Engine handle.
+    #[error("failed to create Transfer Engine handle")]
+    NullHandle,
+
+    /// A C string could not be constructed because the input contains an
+    /// interior null byte.
+    #[error("string argument contains null byte: {0}")]
+    InvalidString(#[from] NulError),
+
+    /// The C layer returned a non-zero status code.
+    #[error("transfer engine operation failed with code {0}")]
+    OperationFailed(i32),
+
+    /// One or more arguments are invalid (e.g. mismatched slice lengths).
+    #[error("invalid argument: {0}")]
+    InvalidArgument(&'static str),
+
+    /// A transfer finished in a failed or timed-out state.
+    #[error("transfer did not complete successfully")]
+    TransferFailed,
+
+    /// Waiting for a transfer exceeded the caller-supplied timeout.
+    #[error("transfer timed out")]
+    Timeout,
+}
diff --git a/mooncake-transfer-engine/rust/src/ffi.rs b/mooncake-transfer-engine/rust/src/ffi.rs
new file mode 100644
index 0000000000..4853c71179
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/ffi.rs
@@ -0,0 +1,25 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! Bindgen-generated bindings for `transfer_engine_c.h`.
+
+#![allow(dead_code)]
+#![allow(non_snake_case)]
+#![allow(non_camel_case_types)]
+#![allow(non_upper_case_globals)]
+#![allow(clippy::missing_safety_doc)]
+#![allow(clippy::too_many_arguments)]
+#![allow(clippy::useless_transmute)]
+
+include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
diff --git a/mooncake-transfer-engine/rust/src/lib.rs b/mooncake-transfer-engine/rust/src/lib.rs
new file mode 100644
index 0000000000..d08d335b4b
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/lib.rs
@@ -0,0 +1,55 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! # transfer_engine_rust
+//!
+//! High-performance Rust bindings for the Mooncake Transfer Engine C API
+//! (`transfer_engine_c.h`).
+//!
+//! Hot-path types (`TransferRequest`, `BufferEntry`, `TransferStatus`) are
+//! `#[repr(C)]` and layout-checked against the C ABI, so
+//! [`TransferEngine::submit_transfer`] passes slices to C with no heap
+//! allocation or per-request copy on the Rust side.
+//!
+//! ```ignore
+//! use transfer_engine_rust::{MemoryPool, Opcode, TransferEngine, TransferRequest};
+//!
+//! let engine = TransferEngine::initialize(
+//!     "127.0.0.1:12345",
+//!     "http://127.0.0.1:8080/metadata",
+//!     "tcp",
+//!     "",
+//! )?;
+//! let mut pool = MemoryPool::new(1 << 20);
+//! unsafe {
+//!     engine.register_local_memory(pool.as_void_ptr(), pool.len(), "cpu:0")?;
+//!     engine.transfer_sync_write("peer:12345", pool.as_void_ptr(), 0, 4096)?;
+//!     engine.unregister_local_memory(pool.as_void_ptr())?;
+//! }
+//! # Ok::<(), transfer_engine_rust::EngineError>(())
+//! ```
+
+mod engine;
+mod error;
+mod ffi;
+mod memory;
+mod types;
+
+pub use engine::{TransferEngine, TransferEngineOptions};
+pub use error::EngineError;
+pub use memory::MemoryPool;
+pub use types::{
+    BatchId, BufferEntry, NicLoadStat, NotifyMsg, Opcode, SegmentId, TransferRequest,
+    TransferStatus, TransferStatusCode, INVALID_BATCH, LOCAL_SEGMENT, WILDCARD_LOCATION,
+};
diff --git a/mooncake-transfer-engine/rust/src/memory.rs b/mooncake-transfer-engine/rust/src/memory.rs
new file mode 100644
index 0000000000..6733456ef9
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/memory.rs
@@ -0,0 +1,123 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! Page-aligned host buffer for RDMA/TCP registration.
+
+use std::alloc::{alloc_zeroed, dealloc, Layout};
+use std::ptr::NonNull;
+
+/// Page-aligned, zeroed host memory suitable for `register_local_memory`.
+///
+/// Alignment is 4096 bytes so the region can be registered with RDMA NICs
+/// without an extra copy. The pool is `Send + Sync`; concurrent access to
+/// disjoint offsets is the caller's responsibility.
+pub struct MemoryPool {
+    ptr: NonNull<u8>,
+    size: usize,
+    align: usize,
+}
+
+impl MemoryPool {
+    /// Allocate `size` bytes, page-aligned and zero-filled.
+    pub fn new(size: usize) -> Self {
+        Self::with_align(size, 4096)
+    }
+
+    /// Allocate `size` bytes with an explicit alignment (must be a power of two).
+    pub fn with_align(size: usize, align: usize) -> Self {
+        assert!(size > 0, "MemoryPool size must be non-zero");
+        let layout = Layout::from_size_align(size, align).expect("invalid MemoryPool layout");
+        let ptr = unsafe { alloc_zeroed(layout) };
+        MemoryPool {
+            ptr: NonNull::new(ptr).expect("failed to allocate MemoryPool"),
+            size,
+            align,
+        }
+    }
+
+    #[inline]
+    pub fn as_ptr(&self) -> *mut u8 {
+        self.ptr.as_ptr()
+    }
+
+    #[inline]
+    pub fn as_void_ptr(&self) -> *mut std::ffi::c_void {
+        self.ptr.as_ptr() as *mut std::ffi::c_void
+    }
+
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.size
+    }
+
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.size == 0
+    }
+
+    /// Pointer at byte `offset`. Panics if `offset` is out of range.
+    #[inline]
+    pub fn offset(&self, offset: usize) -> *mut u8 {
+        assert!(offset < self.size, "MemoryPool offset out of range");
+        unsafe { self.ptr.as_ptr().add(offset) }
+    }
+
+    /// Borrow the whole region as a slice. The caller must not register the
+    /// same bytes for a concurrent RDMA write while this borrow is live.
+    #[inline]
+    pub fn as_slice(&self) -> &[u8] {
+        unsafe { std::slice::from_raw_parts(self.ptr.as_ptr(), self.size) }
+    }
+
+    /// Mutable view of the whole region.
+    #[inline]
+    pub fn as_mut_slice(&mut self) -> &mut [u8] {
+        unsafe { std::slice::from_raw_parts_mut(self.ptr.as_ptr(), self.size) }
+    }
+}
+
+impl Drop for MemoryPool {
+    fn drop(&mut self) {
+        let layout = Layout::from_size_align(self.size, self.align).expect("invalid layout");
+        unsafe {
+            dealloc(self.ptr.as_ptr(), layout);
+        }
+    }
+}
+
+unsafe impl Send for MemoryPool {}
+unsafe impl Sync for MemoryPool {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn allocates_zeroed_page_aligned_region() {
+        let mut pool = MemoryPool::new(8192);
+        assert_eq!(pool.len(), 8192);
+        assert_eq!(pool.as_ptr() as usize % 4096, 0);
+        assert!(pool.as_slice().iter().all(|&b| b == 0));
+        pool.as_mut_slice()[0] = 0xAB;
+        assert_eq!(pool.as_slice()[0], 0xAB);
+        assert!(!pool.offset(4096).is_null());
+    }
+
+    #[test]
+    #[should_panic]
+    fn offset_out_of_range_panics() {
+        let pool = MemoryPool::new(64);
+        let _ = pool.offset(64);
+    }
+}
diff --git a/mooncake-transfer-engine/rust/src/memory_pool.rs b/mooncake-transfer-engine/rust/src/memory_pool.rs
deleted file mode 100644
index 30f92dfa08..0000000000
--- a/mooncake-transfer-engine/rust/src/memory_pool.rs
+++ /dev/null
@@ -1,48 +0,0 @@
-// Copyright 2024 KVCache.AI
-//
-// 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.
-
-use std::alloc::{alloc, dealloc, Layout};
-use std::ptr::NonNull;
-
-pub struct MemoryPool {
-    ptr: NonNull<u8>,
-    size: usize,
-}
-
-impl MemoryPool {
-    pub fn new(size: usize) -> Self {
-        let layout = Layout::from_size_align(size, 1).unwrap();
-        let ptr = unsafe { alloc(layout) };
-        MemoryPool {
-            ptr: NonNull::new(ptr).expect("Failed to allocate memory"),
-            size,
-        }
-    }
-
-    pub fn offset(&self, offset: isize) -> *mut u8 {
-        unsafe { self.ptr.as_ptr().offset(offset) }
-    }
-}
-
-impl Drop for MemoryPool {
-    fn drop(&mut self) {
-        let layout = Layout::from_size_align(self.size, 1).unwrap();
-        unsafe {
-            dealloc(self.ptr.as_ptr(), layout);
-        }
-    }
-}
-
-unsafe impl Send for MemoryPool {}
-unsafe impl Sync for MemoryPool {}
diff --git a/mooncake-transfer-engine/rust/src/transfer_engine.rs b/mooncake-transfer-engine/rust/src/transfer_engine.rs
deleted file mode 100644
index 8c6186df29..0000000000
--- a/mooncake-transfer-engine/rust/src/transfer_engine.rs
+++ /dev/null
@@ -1,306 +0,0 @@
-// Copyright 2024 KVCache.AI
-//
-// 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.
-
-#![allow(dead_code)]
-
-mod bindings {
-    #![allow(dead_code)]
-    #![allow(non_snake_case)]
-    #![allow(non_camel_case_types)]
-    #![allow(non_upper_case_globals)]
-    #![allow(clippy::const_static_lifetime)]
-    #![allow(clippy::unreadable_literal)]
-    #![allow(clippy::cyclomatic_complexity)]
-    #![allow(clippy::useless_transmute)]
-    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
-}
-
-use anyhow::{anyhow, bail, Result};
-use std::ffi::{c_void, CString};
-type BatchID = u64;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum OpcodeEnum {
-    Read = 0,
-    Write,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TransferStatusEnum {
-    Waiting = 0,
-    Pending,
-    Invalid,
-    Canceled,
-    Completed,
-    Timeout,
-    Failed,
-}
-
-pub struct TransferRequest {
-    pub opcode: OpcodeEnum,
-    pub source: *mut c_void,
-    pub target_id: i32,
-    pub target_offset: u64,
-    pub length: u64,
-}
-
-pub struct BufferEntry {
-    pub addr: *mut c_void,
-    pub length: u64,
-}
-
-pub struct TransferEngine {
-    engine: bindings::transfer_engine_t,
-}
-
-impl TransferEngine {
-    pub fn new(
-        metadata_uri: &str,
-        local_server_name: &str,
-        rpc_port: u64,
-    ) -> Result<Self> {
-        let metadata_uri_c =
-            CString::new(metadata_uri).map_err(|_| anyhow!("CString::new failed"))?;
-        let local_server_name_c =
-            CString::new(local_server_name).map_err(|_| anyhow!("CString::new failed"))?;
-
-        let engine = unsafe {
-            bindings::createTransferEngine(
-                metadata_uri_c.as_ptr(),
-                local_server_name_c.as_ptr(),
-                local_server_name_c.as_ptr(),
-                rpc_port,
-                0, // disable auto_discover
-            )
-        };
-        if engine.is_null() {
-            bail!("Failed to create TransferEngine")
-        }
-
-        Ok(Self { engine })
-    }
-
-    pub fn discover_topology(&self) -> Result<()> {
-        let ret = unsafe { bindings::discoverTopology(self.engine) };
-        if ret != 0 {
-            bail!("Failed to discover topology")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn install_transport(&self, proto: &str) -> Result<()> {
-        let proto_c = CString::new(proto).map_err(|_| anyhow!("CString::new failed"))?;
-        let ret = unsafe {
-            bindings::installTransport(self.engine, proto_c.as_ptr(), std::ptr::null_mut())
-        };
-        if ret.is_null() {
-            bail!("Failed to install transport '{}'", proto)
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn close(&mut self) -> Result<()> {
-        unsafe {
-            bindings::destroyTransferEngine(self.engine);
-        }
-        Ok(())
-    }
-
-    pub fn register_local_memory(
-        &self,
-        addr: *mut c_void,
-        length: usize,
-        location: &str,
-    ) -> Result<()> {
-        let location_c = CString::new(location).map_err(|_| anyhow!("CString::new failed"))?;
-        let ret = unsafe {
-            bindings::registerLocalMemory(self.engine, addr, length, location_c.as_ptr(), 1)
-        };
-        if ret < 0 {
-            bail!("Failed to register local memory")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn unregister_local_memory(&self, addr: *mut c_void) -> Result<()> {
-        let ret = unsafe { bindings::unregisterLocalMemory(self.engine, addr) };
-        if ret < 0 {
-            bail!("Failed to unregister local memory")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn register_local_memory_batch(
-        &self,
-        buffer_list: &[BufferEntry],
-        location: &str,
-    ) -> Result<()> {
-        if buffer_list.is_empty() {
-            return Ok(());
-        }
-        let location_c = CString::new(location).map_err(|_| anyhow!("CString::new failed"))?;
-        let mut buffer_list_c: Vec<bindings::buffer_entry_t> = vec![];
-        let buffer_len_c = buffer_list.len();
-        for i in 0..buffer_list.len() {
-            buffer_list_c.push(bindings::buffer_entry_t {
-                addr: buffer_list[i].addr,
-                length: buffer_list[i].length as usize,
-            });
-        }
-        let ret = unsafe {
-            bindings::registerLocalMemoryBatch(
-                self.engine,
-                buffer_list_c.as_mut_ptr(),
-                buffer_len_c,
-                location_c.as_ptr(),
-            )
-        };
-        if ret < 0 {
-            bail!("Failed to register local memory")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn unregister_local_memory_batch(&self, buffer_list: &[BufferEntry]) -> Result<()> {
-        if buffer_list.is_empty() {
-            return Ok(());
-        }
-        let mut addr_list: Vec<*mut c_void> = buffer_list.iter().map(|entry| entry.addr).collect();
-        let addr_len = buffer_list.len();
-        let ret = unsafe {
-            bindings::unregisterLocalMemoryBatch(self.engine, addr_list.as_mut_ptr(), addr_len)
-        };
-        if ret < 0 {
-            bail!("Failed to unregister local memory")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn allocate_batch_id(&self, batch_size: usize) -> Result<BatchID> {
-        let ret = unsafe { bindings::allocateBatchID(self.engine, batch_size) };
-        if ret == u64::MAX {
-            bail!("Failed to allocate batch ID")
-        } else {
-            Ok(ret as BatchID)
-        }
-    }
-
-    pub fn submit_transfer(
-        &self,
-        batch_id: BatchID,
-        requests: &mut [TransferRequest],
-    ) -> Result<()> {
-        if requests.is_empty() {
-            return Ok(());
-        }
-        let mut requests_c: Vec<bindings::transfer_request_t> = vec![];
-        for i in 0..requests.len() {
-            requests_c.push(bindings::transfer_request_t {
-                opcode: requests[i].opcode as i32,
-                source: requests[i].source,
-                target_id: requests[i].target_id,
-                target_offset: requests[i].target_offset,
-                length: requests[i].length,
-            })
-        }
-        let ret = unsafe {
-            bindings::submitTransfer(self.engine, batch_id, requests_c.as_mut_ptr(), requests.len())
-        };
-        if ret != 0 {
-            bail!("Failed to submit transfer")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn get_transfer_status(&self, batch_id: BatchID, task_id: u64) -> Result<(i32, u64)> {
-        let mut status = bindings::transfer_status_t {
-            status: 0,
-            transferred_bytes: 0,
-        };
-        let ret =
-            unsafe { bindings::getTransferStatus(self.engine, batch_id, task_id as usize, &mut status) };
-        if ret != 0 {
-            bail!("Failed to get transfer status")
-        } else {
-            Ok((status.status, status.transferred_bytes))
-        }
-    }
-
-    pub fn free_batch_id(&self, batch_id: BatchID) -> Result<()> {
-        let ret = unsafe { bindings::freeBatchID(self.engine, batch_id) };
-        if ret != 0 {
-            bail!("Failed to free batch ID")
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn open_segment(&self, name: String) -> Result<i32> {
-        let name_c = CString::new(name).map_err(|_| anyhow!("CString::new failed"))?;
-        let ret = unsafe { bindings::openSegment(self.engine, name_c.as_ptr()) };
-        if ret < 0 {
-            bail!("Failed to get segment ID")
-        } else {
-            Ok(ret)
-        }
-    }
-
-    pub fn close_segment(&self, segment_id: i32) -> Result<()> {
-        let ret = unsafe { bindings::closeSegment(self.engine, segment_id) };
-        if ret < 0 {
-            bail!("Failed to close segment with ID {}", segment_id)
-        } else {
-            Ok(())
-        }
-    }
-
-    /// Eagerly establish EFA endpoints to `segment_name` so the first
-    /// `submit_transfer` doesn't pay the serial fi_av_insert cost. No-op on
-    /// non-EFA transports. Call after `open_segment` (and after the metadata
-    /// has the peer's NIC list published).
-    pub fn warmup_efa_segment(&self, name: &str) -> Result<()> {
-        let name_c = CString::new(name).map_err(|_| anyhow!("CString::new failed"))?;
-        let ret = unsafe { bindings::warmupEfaSegment(self.engine, name_c.as_ptr()) };
-        if ret < 0 {
-            bail!("warmupEfaSegment failed for {}: {}", name, ret)
-        } else {
-            Ok(())
-        }
-    }
-
-    pub fn sync_segment_cache(&self) -> Result<()> {
-        let ret = unsafe { bindings::syncSegmentCache(self.engine) };
-        if ret < 0 {
-            bail!("Failed to synchronize segment cache")
-        } else {
-            Ok(())
-        }
-    }
-}
-
-impl Drop for TransferEngine {
-    fn drop(&mut self) {
-        self.close().expect("Failed to close transfer engine");
-    }
-}
-
-unsafe impl Send for TransferEngine {}
-unsafe impl Sync for TransferEngine {}
diff --git a/mooncake-transfer-engine/rust/src/types.rs b/mooncake-transfer-engine/rust/src/types.rs
new file mode 100644
index 0000000000..af9ba9eef4
--- /dev/null
+++ b/mooncake-transfer-engine/rust/src/types.rs
@@ -0,0 +1,271 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! Public types that match the Transfer Engine C ABI (`transfer_engine_c.h`).
+//!
+//! `TransferRequest`, `BufferEntry`, and `TransferStatus` are `#[repr(C)]` and
+//! layout-checked against the bindgen types so hot-path calls can pass Rust
+//! slices to the C API without allocating or copying.
+
+use std::ffi::c_void;
+
+use crate::ffi;
+
+/// Wildcard memory location accepted by `registerLocalMemory` (`"*"`).
+pub const WILDCARD_LOCATION: &str = "*";
+
+/// Local-segment handle (`LOCAL_SEGMENT` in the C header).
+pub const LOCAL_SEGMENT: SegmentId = 0;
+
+/// Sentinel returned by `allocateBatchID` on failure (`INVALID_BATCH`).
+pub const INVALID_BATCH: u64 = u64::MAX;
+
+/// Integer handle for an opened remote (or local) segment.
+pub type SegmentId = i32;
+
+/// Opaque batch identifier returned by [`crate::TransferEngine::allocate_batch_id`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(transparent)]
+pub struct BatchId(pub u64);
+
+impl BatchId {
+    /// Returns `true` when this value is the C `INVALID_BATCH` sentinel.
+    #[inline]
+    pub fn is_invalid(self) -> bool {
+        self.0 == INVALID_BATCH
+    }
+}
+
+/// Transfer opcode. Numeric values match `OPCODE_READ` / `OPCODE_WRITE`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(i32)]
+pub enum Opcode {
+    Read = 0,
+    Write = 1,
+}
+
+/// Transfer completion state. Numeric values match `STATUS_*` in the C header.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(i32)]
+pub enum TransferStatusCode {
+    Waiting = 0,
+    Pending = 1,
+    Invalid = 2,
+    Canceled = 3,
+    Completed = 4,
+    Timeout = 5,
+    Failed = 6,
+}
+
+impl TransferStatusCode {
+    /// Convert a raw C status integer. Unknown values map to [`Self::Invalid`].
+    #[inline]
+    pub fn from_raw(raw: i32) -> Self {
+        match raw {
+            0 => Self::Waiting,
+            1 => Self::Pending,
+            2 => Self::Invalid,
+            3 => Self::Canceled,
+            4 => Self::Completed,
+            5 => Self::Timeout,
+            6 => Self::Failed,
+            _ => Self::Invalid,
+        }
+    }
+
+    /// `true` when the task has reached a terminal success or failure state.
+    #[inline]
+    pub fn is_terminal(self) -> bool {
+        matches!(
+            self,
+            Self::Completed | Self::Failed | Self::Timeout | Self::Canceled | Self::Invalid
+        )
+    }
+
+    /// `true` when the task completed successfully.
+    #[inline]
+    pub fn is_completed(self) -> bool {
+        self == Self::Completed
+    }
+}
+
+/// One transfer operation. Layout matches `transfer_request_t`.
+///
+/// Passing a `&[TransferRequest]` to
+/// [`crate::TransferEngine::submit_transfer`] is a zero-copy FFI call.
+#[derive(Debug, Clone, Copy)]
+#[repr(C)]
+pub struct TransferRequest {
+    pub opcode: Opcode,
+    pub source: *mut c_void,
+    pub target_id: SegmentId,
+    pub target_offset: u64,
+    pub length: u64,
+}
+
+impl TransferRequest {
+    /// Build a READ request (remote → local).
+    #[inline]
+    pub fn read(local: *mut c_void, target_id: SegmentId, target_offset: u64, length: u64) -> Self {
+        Self {
+            opcode: Opcode::Read,
+            source: local,
+            target_id,
+            target_offset,
+            length,
+        }
+    }
+
+    /// Build a WRITE request (local → remote).
+    #[inline]
+    pub fn write(
+        local: *mut c_void,
+        target_id: SegmentId,
+        target_offset: u64,
+        length: u64,
+    ) -> Self {
+        Self {
+            opcode: Opcode::Write,
+            source: local,
+            target_id,
+            target_offset,
+            length,
+        }
+    }
+}
+
+// SAFETY: TransferRequest is a C POD of pointers and integers. Sending the
+// descriptor across threads is safe; the caller still owns the pointed-to
+// memory and must keep it valid for the transfer.
+unsafe impl Send for TransferRequest {}
+unsafe impl Sync for TransferRequest {}
+
+/// One registered buffer. Layout matches `buffer_entry_t`.
+#[derive(Debug, Clone, Copy)]
+#[repr(C)]
+pub struct BufferEntry {
+    pub addr: *mut c_void,
+    pub length: usize,
+}
+
+impl BufferEntry {
+    #[inline]
+    pub fn new(addr: *mut c_void, length: usize) -> Self {
+        Self { addr, length }
+    }
+}
+
+unsafe impl Send for BufferEntry {}
+unsafe impl Sync for BufferEntry {}
+
+/// Per-task status. Layout matches `transfer_status_t`.
+#[derive(Debug, Clone, Copy)]
+#[repr(C)]
+pub struct TransferStatus {
+    pub status: TransferStatusCode,
+    pub transferred_bytes: u64,
+}
+
+impl TransferStatus {
+    #[inline]
+    pub fn is_completed(&self) -> bool {
+        self.status.is_completed()
+    }
+
+    #[inline]
+    pub fn is_terminal(&self) -> bool {
+        self.status.is_terminal()
+    }
+}
+
+/// Notification payload used by `submitTransferWithNotify` / `getNotifsFromEngine`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NotifyMsg {
+    pub name: String,
+    pub msg: String,
+}
+
+impl NotifyMsg {
+    pub fn new(name: impl Into<String>, msg: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            msg: msg.into(),
+        }
+    }
+}
+
+/// One NIC's load snapshot from `getNicLoadStats`.
+#[derive(Debug, Clone)]
+pub struct NicLoadStat {
+    pub device_name: String,
+    pub inflight_bytes: u64,
+    pub ewma_bandwidth_bps: f64,
+}
+
+// Compile-time layout checks against bindgen so submit_transfer can pass
+// slices through without converting element-by-element.
+const _: () = {
+    assert!(
+        std::mem::size_of::<TransferRequest>() == std::mem::size_of::<ffi::transfer_request_t>()
+    );
+    assert!(
+        std::mem::align_of::<TransferRequest>() == std::mem::align_of::<ffi::transfer_request_t>()
+    );
+    assert!(std::mem::size_of::<BufferEntry>() == std::mem::size_of::<ffi::buffer_entry_t>());
+    assert!(std::mem::align_of::<BufferEntry>() == std::mem::align_of::<ffi::buffer_entry_t>());
+    assert!(std::mem::size_of::<TransferStatus>() == std::mem::size_of::<ffi::transfer_status_t>());
+    assert!(
+        std::mem::align_of::<TransferStatus>() == std::mem::align_of::<ffi::transfer_status_t>()
+    );
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn request_field_offsets_match_c() {
+        assert_eq!(
+            std::mem::offset_of!(TransferRequest, opcode),
+            std::mem::offset_of!(ffi::transfer_request, opcode)
+        );
+        assert_eq!(
+            std::mem::offset_of!(TransferRequest, source),
+            std::mem::offset_of!(ffi::transfer_request, source)
+        );
+        assert_eq!(
+            std::mem::offset_of!(TransferRequest, target_id),
+            std::mem::offset_of!(ffi::transfer_request, target_id)
+        );
+        assert_eq!(
+            std::mem::offset_of!(TransferRequest, target_offset),
+            std::mem::offset_of!(ffi::transfer_request, target_offset)
+        );
+        assert_eq!(
+            std::mem::offset_of!(TransferRequest, length),
+            std::mem::offset_of!(ffi::transfer_request, length)
+        );
+    }
+
+    #[test]
+    fn opcode_and_status_raw_values() {
+        assert_eq!(Opcode::Read as i32, 0);
+        assert_eq!(Opcode::Write as i32, 1);
+        assert_eq!(TransferStatusCode::Completed as i32, 4);
+        assert_eq!(TransferStatusCode::Failed as i32, 6);
+        assert!(TransferStatusCode::from_raw(4).is_completed());
+        assert!(TransferStatusCode::from_raw(6).is_terminal());
+        assert!(!TransferStatusCode::Pending.is_terminal());
+    }
+}
diff --git a/mooncake-transfer-engine/rust/tests/minimal_smoke.rs b/mooncake-transfer-engine/rust/tests/minimal_smoke.rs
new file mode 100644
index 0000000000..fbc2051a4a
--- /dev/null
+++ b/mooncake-transfer-engine/rust/tests/minimal_smoke.rs
@@ -0,0 +1,121 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+//! Env-gated Transfer Engine smoke test.
+//!
+//! Defaults to `P2PHANDSHAKE` so it can run without an HTTP metadata server.
+//! CI sets `MC_METADATA_SERVER=http://127.0.0.1:8080/metadata`.
+//!
+//! ```bash
+//! MC_RUST_TE_RUN_INTEGRATION=1 cargo test --test minimal_smoke -- --nocapture
+//! ```
+
+use std::time::Duration;
+
+use transfer_engine_rust::{MemoryPool, TransferEngine, TransferRequest, WILDCARD_LOCATION};
+
+const CHUNK: usize = 4096;
+const TRANSFER_TIMEOUT: Duration = Duration::from_secs(30);
+
+fn env_or_default(key: &str, default: &str) -> String {
+    std::env::var(key).unwrap_or_else(|_| default.to_string())
+}
+
+fn should_run_integration() -> bool {
+    matches!(
+        std::env::var("MC_RUST_TE_RUN_INTEGRATION").as_deref(),
+        Ok("1") | Ok("true") | Ok("TRUE")
+    )
+}
+
+fn local_hostname() -> String {
+    env_or_default(
+        "MC_RUST_TE_LOCAL_HOSTNAME",
+        &format!("127.0.0.1:{}", 20_000 + std::process::id() % 10_000),
+    )
+}
+
+#[test]
+fn tcp_loopback_write_and_read() -> Result<(), Box<dyn std::error::Error>> {
+    if !should_run_integration() {
+        eprintln!(
+            "skipping Transfer Engine Rust smoke test; set MC_RUST_TE_RUN_INTEGRATION=1 to enable"
+        );
+        return Ok(());
+    }
+
+    let metadata_server = env_or_default("MC_METADATA_SERVER", "P2PHANDSHAKE");
+    let local_hostname = local_hostname();
+    let protocol = env_or_default("MC_RUST_TE_PROTOCOL", "tcp");
+
+    let engine = TransferEngine::initialize(&local_hostname, &metadata_server, &protocol, "")?;
+    let advertised = engine.local_ip_and_port()?;
+    assert!(
+        !advertised.is_empty(),
+        "local_ip_and_port must be non-empty after initialize"
+    );
+
+    // P2PHANDSHAKE rewrites the RPC port; HTTP metadata keeps the name we
+    // registered. Match tcp_write_visibility_test.cpp.
+    let segment_name = if metadata_server == "P2PHANDSHAKE" {
+        advertised
+    } else {
+        local_hostname.clone()
+    };
+
+    let mut pool = MemoryPool::new(CHUNK * 2);
+    pool.as_mut_slice()[..CHUNK].fill(0xA5);
+    pool.as_mut_slice()[CHUNK..].fill(0x00);
+
+    unsafe {
+        engine.register_local_memory(pool.as_void_ptr(), pool.len(), WILDCARD_LOCATION)?;
+
+        let segment = engine.open_segment(&segment_name)?;
+        let src = pool.as_void_ptr();
+        let dst = pool.offset(CHUNK) as *mut std::ffi::c_void;
+
+        engine.submit_and_wait(
+            &[TransferRequest::write(
+                src,
+                segment,
+                dst as u64,
+                CHUNK as u64,
+            )],
+            Some(TRANSFER_TIMEOUT),
+        )?;
+        assert_eq!(
+            &pool.as_slice()[..CHUNK],
+            &pool.as_slice()[CHUNK..],
+            "loopback WRITE must copy the first 4KiB onto the second 4KiB"
+        );
+
+        pool.as_mut_slice()[..CHUNK].fill(0x00);
+        engine.submit_and_wait(
+            &[TransferRequest::read(
+                src,
+                segment,
+                dst as u64,
+                CHUNK as u64,
+            )],
+            Some(TRANSFER_TIMEOUT),
+        )?;
+        assert!(
+            pool.as_slice()[..CHUNK].iter().all(|&b| b == 0xA5),
+            "loopback READ must restore the pattern from the destination region"
+        );
+
+        engine.unregister_local_memory(pool.as_void_ptr())?;
+    }
+    Ok(())
+}
diff --git a/mooncake-transfer-engine/src/CMakeLists.txt b/mooncake-transfer-engine/src/CMakeLists.txt
index c91b02147f..05c5eb542e 100644
--- a/mooncake-transfer-engine/src/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/CMakeLists.txt
@@ -1,4 +1,19 @@
-file(GLOB ENGINE_SOURCES "*.cpp")
+file(GLOB ENGINE_SOURCES "*.cpp" "shared_segment/*.cpp")
+set(TRANSFER_METADATA_PLUGIN_SOURCES config.cpp transfer_metadata_plugin.cpp)
+list(REMOVE_ITEM ENGINE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/config.cpp"
+     "${CMAKE_CURRENT_SOURCE_DIR}/transfer_metadata_plugin.cpp")
+# ibv_port_attr::active_speed is a uint8_t and reads 0 for XDR (encoding 256);
+# newer rdma-core adds active_speed_ex to carry it. TENT probes the same cache
+# variable in tent/src; this definition covers the classic RdmaContext under
+# transport/ so both decode the port speed the same way.
+include(CheckStructHasMember)
+check_struct_has_member(
+  "struct ibv_port_attr" active_speed_ex infiniband/verbs.h
+  HAVE_IBV_ACTIVE_SPEED_EX LANGUAGE CXX)
+if(HAVE_IBV_ACTIVE_SPEED_EX)
+  add_compile_definitions(HAVE_IBV_ACTIVE_SPEED_EX)
+endif()
+
 add_subdirectory(common)
 add_subdirectory(transport)
 
@@ -10,12 +25,19 @@ if(USE_HIP)
   hipify_files(ENGINE_SOURCES)
 endif()
 
-add_library(transfer_engine ${ENGINE_SOURCES} $<TARGET_OBJECTS:transport>)
-if(BUILD_SHARED_LIBS)
-  install(TARGETS transfer_engine DESTINATION lib)
-endif()
-
-add_compile_definitions(transfer_engine PUBLIC MOONCAKE_USE_ETCD CMAKE_INCLUDE)
+add_library(transfer_metadata_plugin OBJECT ${TRANSFER_METADATA_PLUGIN_SOURCES})
+set_target_properties(transfer_metadata_plugin
+                      PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_include_directories(
+  transfer_metadata_plugin
+  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
+         $<INSTALL_INTERFACE:include>)
+target_compile_definitions(transfer_metadata_plugin PRIVATE MOONCAKE_USE_ETCD
+                                                            CMAKE_INCLUDE)
+target_link_libraries(
+  transfer_metadata_plugin
+  PUBLIC glog::glog JsonCpp::JsonCpp
+  PRIVATE pthread)
 if(USE_ETCD)
   if(USE_ETCD_LEGACY)
     if(USE_STATIC_ETCD_CPP_API)
@@ -23,31 +45,40 @@ if(USE_ETCD)
       pkg_check_modules(GRPCPP REQUIRED grpc++)
       pkg_check_modules(GRPC REQUIRED grpc)
       target_link_libraries(
-        transfer_engine PUBLIC etcd-cpp-api-core protobuf ${GRPC_LDFLAGS}
-                               ${GRPCPP_LDFLAGS})
+        transfer_metadata_plugin PRIVATE etcd-cpp-api-core protobuf
+                                         ${GRPC_LDFLAGS} ${GRPCPP_LDFLAGS})
     else()
-      target_link_libraries(transfer_engine PUBLIC etcd-cpp-api)
+      target_link_libraries(transfer_metadata_plugin PRIVATE etcd-cpp-api)
     endif()
   else()
-    add_dependencies(transfer_engine build_etcd_wrapper)
+    add_dependencies(transfer_metadata_plugin build_etcd_wrapper)
     set(ETCD_WRAPPER_LIB
         ${CMAKE_CURRENT_BINARY_DIR}/../../mooncake-common/etcd/libetcd_wrapper.so
     )
-    target_link_libraries(transfer_engine PRIVATE ${ETCD_WRAPPER_LIB})
+    target_link_libraries(transfer_metadata_plugin PRIVATE ${ETCD_WRAPPER_LIB})
   endif()
 endif()
 if(USE_REDIS)
-  target_link_libraries(transfer_engine PUBLIC hiredis)
+  target_link_libraries(transfer_metadata_plugin PRIVATE Mooncake::hiredis)
 endif()
 if(USE_HTTP)
   find_package(CURL REQUIRED)
-  target_link_libraries(transfer_engine PUBLIC ${CURL_LIBRARIES})
+  target_link_libraries(transfer_metadata_plugin PRIVATE ${CURL_LIBRARIES})
 endif()
+
+add_library(transfer_engine ${ENGINE_SOURCES} $<TARGET_OBJECTS:transport>)
+target_include_directories(
+  transfer_engine
+  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
+         $<INSTALL_INTERFACE:include>
+  PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/shared_segment)
+target_compile_definitions(transfer_engine PRIVATE MOONCAKE_USE_ETCD
+                                                   CMAKE_INCLUDE)
 target_link_libraries(
   transfer_engine
   PUBLIC base
-         transport
          rdma_transport
+         rdma_twosided
          mooncake_common
          ibverbs
          glog::glog
@@ -56,18 +87,30 @@ target_link_libraries(
          JsonCpp::JsonCpp
          numa
          asio_shared
-         yalantinglibs::yalantinglibs)
+         yalantinglibs::yalantinglibs
+  PRIVATE transport transfer_metadata_plugin)
+if(UNIX AND NOT APPLE)
+  # shm_open/shm_unlink live in librt on glibc; OBJECT-library PRIVATE deps do
+  # not propagate through $<TARGET_OBJECTS:shm_transport>.
+  target_link_libraries(transfer_engine PRIVATE rt)
+endif()
+if(BUILD_SHARED_LIBS)
+  install(TARGETS transfer_engine DESTINATION lib)
+endif()
 
 if(USE_BAREX)
   target_link_libraries(transfer_engine PUBLIC barex_transport)
 endif()
 
 if(USE_CUDA)
-  target_include_directories(transfer_engine PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
+  target_include_directories(transfer_engine
+                             PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
   if(USE_CXI)
-    target_link_libraries(transfer_engine PUBLIC CUDA::cuda_driver CUDA::cudart rt)
+    target_link_libraries(transfer_engine PUBLIC CUDA::cuda_driver CUDA::cudart
+                                                 rt)
   else()
-    target_link_libraries(transfer_engine PUBLIC CUDA::cuda_driver CUDA::cudart rt mlx5)
+    target_link_libraries(transfer_engine PUBLIC CUDA::cuda_driver CUDA::cudart
+                                                 rt mlx5)
   endif()
   if(USE_NVMEOF)
     target_link_libraries(transfer_engine PUBLIC nvmeof_transport cufile)
@@ -119,9 +162,9 @@ if(USE_HIP)
       # compiled in the rdma_transport OBJECT library and pulled into
       # transfer_engine via $<TARGET_OBJECTS:transport>. A PRIVATE define on
       # transfer_engine never reaches that object compilation, so the dmabuf
-      # path is silently compiled out and GPU MRs fall back to plain
-      # ibv_reg_mr (EINVAL on device memory). Put the define (and the hsa
-      # include/link usage requirements) on the target that actually compiles
+      # path is silently compiled out and GPU MRs fall back to plain ibv_reg_mr
+      # (EINVAL on device memory). Put the define (and the hsa include/link
+      # usage requirements) on the target that actually compiles
       # rdma_context.cpp.
       target_compile_definitions(rdma_transport PRIVATE USE_HIP_DMABUF)
       target_link_libraries(rdma_transport PUBLIC hsa-runtime64::hsa-runtime64)
@@ -187,5 +230,8 @@ endif()
 
 if(USE_UB)
   message(STATUS "Enabled USE_UB protocol support")
-  target_link_libraries(transfer_engine PUBLIC ub_transport)
+  target_link_libraries(
+    transfer_engine
+    PUBLIC ub_transport
+    PRIVATE ub_allocator)
 endif()
diff --git a/mooncake-transfer-engine/src/common/base/CMakeLists.txt b/mooncake-transfer-engine/src/common/base/CMakeLists.txt
index de7e35db20..ad766f1b24 100644
--- a/mooncake-transfer-engine/src/common/base/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/common/base/CMakeLists.txt
@@ -9,4 +9,5 @@ list(
   ${CMAKE_CURRENT_LIST_DIR}/status.cpp)
 
 # # Build all the source files of base dir into a static lib('base')
-add_library(base STATIC ${SRC})
\ No newline at end of file
+add_library(base STATIC ${SRC})
+target_link_libraries(base PRIVATE glog::glog)
diff --git a/mooncake-transfer-engine/src/config.cpp b/mooncake-transfer-engine/src/config.cpp
index e3b0154659..bb679259c7 100644
--- a/mooncake-transfer-engine/src/config.cpp
+++ b/mooncake-transfer-engine/src/config.cpp
@@ -14,6 +14,35 @@
 
 #include "config.h"
 
+// MOONCAKE_GLOG_HAS_IS_INITIALIZED is defined by FindGLOG.cmake via the
+// glog::glog INTERFACE compile definitions. It is set to 1 only when the
+// detected glog version is >= 0.6.0, where google::IsGoogleLoggingInitialized()
+// is publicly exported as a top-level symbol. This defensive fallback keeps the
+// file buildable even if the macro was not propagated for some reason.
+#ifndef MOONCAKE_GLOG_HAS_IS_INITIALIZED
+#define MOONCAKE_GLOG_HAS_IS_INITIALIZED 0
+#endif
+
+#if !MOONCAKE_GLOG_HAS_IS_INITIALIZED
+// glog < 0.6.0 does NOT export google::IsGoogleLoggingInitialized() at the
+// top level; the public declaration was only added in 0.6.0. However, the same
+// function has always existed in these older versions inside the internal
+// namespace google::glog_internal_namespace_ (declared in glog's private
+// header src/utilities.h, which is not installed). The symbol is exported by
+// libglog, so we forward-declare it here to reuse it without depending on any
+// private header. This lets old glog perform a real "already initialized"
+// check instead of blindly re-initializing.
+//
+// NOTE: In glog >= 0.6.0 this internal symbol no longer exists (it was moved
+// to the top-level google:: namespace), which is exactly why this branch is
+// only compiled when MOONCAKE_GLOG_HAS_IS_INITIALIZED == 0.
+namespace google {
+namespace glog_internal_namespace_ {
+bool IsGoogleLoggingInitialized();
+}  // namespace glog_internal_namespace_
+}  // namespace google
+#endif
+
 #include <charconv>
 #include <cstring>
 #include <cstdio>
@@ -128,7 +157,9 @@ void loadGlobalConfig(GlobalConfig& config) {
     const char* port_env = std::getenv("MC_IB_PORT");
     if (port_env) {
         int val = atoi(port_env);
-        if (val >= 0 && val < 256)
+        // IB port numbers are 1-based. Accepting 0 made ibv_query_port fail on
+        // every device, disabling the whole topology.
+        if (val > 0 && val < 256)
             config.port = uint8_t(val);
         else
             LOG(WARNING) << "Ignore value from environment variable MC_IB_PORT";
@@ -439,9 +470,50 @@ void loadGlobalConfig(GlobalConfig& config) {
         }
     }
 
+    const char* context_pause_ttl_env = std::getenv("MC_CONTEXT_PAUSE_TTL_MS");
+    if (context_pause_ttl_env) {
+        // Robust parse (not atoi): a non-numeric typo must keep the default
+        // rather than silently resolve to 0 and re-enable the legacy latch.
+        // Non-positive, out-of-range and garbage values are rejected.
+        int val = 0;
+        const char* end = context_pause_ttl_env + strlen(context_pause_ttl_env);
+        auto [ptr, ec] = std::from_chars(context_pause_ttl_env, end, val);
+        if (ec == std::errc() && ptr == end) {
+            if (val >= 1 && val <= 600000) {
+                config.context_pause_ttl_ms = val;
+            } else {
+                LOG(WARNING) << "Ignore value from environment variable "
+                                "MC_CONTEXT_PAUSE_TTL_MS, value "
+                             << context_pause_ttl_env
+                             << " out of range (should be 1-600000)";
+            }
+        } else {
+            LOG(WARNING)
+                << "Invalid MC_CONTEXT_PAUSE_TTL_MS environment value: "
+                << context_pause_ttl_env
+                << ". Expected an integer in range 1-600000";
+        }
+    }
+
     const char* log_dir_path = std::getenv("MC_LOG_DIR");
     if (log_dir_path) {
-        google::InitGoogleLogging("mooncake-transfer-engine");
+        // Only initialize when the caller (upstream program) has not already
+        // initialized glog, to avoid double initialization. On both new and old
+        // glog versions this performs a real "already initialized" check:
+        //   - glog >= 0.6.0: public google::IsGoogleLoggingInitialized()
+        //   - glog <  0.6.0: the equivalent function that lives in the internal
+        //     namespace google::glog_internal_namespace_ (forward-declared at
+        //     the top of this file).
+        // The using-declaration below selects the right overload for the
+        // detected version, so the call site stays identical.
+#if MOONCAKE_GLOG_HAS_IS_INITIALIZED
+        using google::IsGoogleLoggingInitialized;
+#else
+        using google::glog_internal_namespace_::IsGoogleLoggingInitialized;
+#endif
+        if (!IsGoogleLoggingInitialized()) {
+            google::InitGoogleLogging("mooncake-transfer-engine");
+        }
         std::error_code ec;
         if (!std::filesystem::is_directory(log_dir_path, ec)) {
             LOG(WARNING)
@@ -528,6 +600,65 @@ void loadGlobalConfig(GlobalConfig& config) {
                            config.track_rdma_posted_slices);
     }
 
+    const char* use_rdma_twosided_env = std::getenv("MC_USE_RDMA_TWOSIDED");
+    if (use_rdma_twosided_env) {
+        parseBoolConfigEnv(use_rdma_twosided_env, "MC_USE_RDMA_TWOSIDED",
+                           config.use_rdma_twosided);
+    }
+
+    const char* rdma_notify_enabled_env = std::getenv("MC_RDMA_NOTIFY_ENABLED");
+    if (rdma_notify_enabled_env) {
+        parseBoolConfigEnv(rdma_notify_enabled_env, "MC_RDMA_NOTIFY_ENABLED",
+                           config.rdma_notify_enabled);
+    }
+    const char* rdma_notify_recv_count_env =
+        std::getenv("MC_RDMA_NOTIFY_RECV_COUNT");
+    if (rdma_notify_recv_count_env) {
+        int val = atoi(rdma_notify_recv_count_env);
+        if (val > 0 && val <= 4096)
+            config.rdma_notify_recv_count = static_cast<size_t>(val);
+        else
+            LOG(WARNING) << "Ignore value from environment variable "
+                            "MC_RDMA_NOTIFY_RECV_COUNT";
+    }
+    const char* rdma_notify_buffer_size_env =
+        std::getenv("MC_RDMA_NOTIFY_BUFFER_SIZE");
+    if (rdma_notify_buffer_size_env) {
+        int val = atoi(rdma_notify_buffer_size_env);
+        if (val >= 256 && val <= 65536)
+            config.rdma_notify_buffer_size = static_cast<size_t>(val);
+        else
+            LOG(WARNING) << "Ignore value from environment variable "
+                            "MC_RDMA_NOTIFY_BUFFER_SIZE";
+    }
+    const char* rdma_notify_max_pending_sends_env =
+        std::getenv("MC_RDMA_NOTIFY_MAX_PENDING_SENDS");
+    if (rdma_notify_max_pending_sends_env) {
+        int val = atoi(rdma_notify_max_pending_sends_env);
+        if (val > 0 && val <= 4096)
+            config.rdma_notify_max_pending_sends = static_cast<size_t>(val);
+        else
+            LOG(WARNING) << "Ignore value from environment variable "
+                            "MC_RDMA_NOTIFY_MAX_PENDING_SENDS";
+    }
+    const char* rdma_notify_oob_fallback_env =
+        std::getenv("MC_RDMA_NOTIFY_OOB_FALLBACK");
+    if (rdma_notify_oob_fallback_env) {
+        parseBoolConfigEnv(rdma_notify_oob_fallback_env,
+                           "MC_RDMA_NOTIFY_OOB_FALLBACK",
+                           config.rdma_notify_oob_fallback);
+    }
+    const char* rdma_notify_connect_timeout_env =
+        std::getenv("MC_RDMA_NOTIFY_CONNECT_TIMEOUT_MS");
+    if (rdma_notify_connect_timeout_env) {
+        int val = atoi(rdma_notify_connect_timeout_env);
+        if (val >= 100 && val <= 600000)
+            config.rdma_notify_connect_timeout_ms = static_cast<uint32_t>(val);
+        else
+            LOG(WARNING) << "Ignore value from environment variable "
+                            "MC_RDMA_NOTIFY_CONNECT_TIMEOUT_MS";
+    }
+
     const char* enable_parallel_reg_mr =
         std::getenv("MC_ENABLE_PARALLEL_REG_MR");
     if (enable_parallel_reg_mr) {
@@ -760,6 +891,16 @@ void dumpGlobalConfig() {
               << (config.log_rdma_slice_affinity ? "true" : "false");
     LOG(INFO) << "track_rdma_posted_slices = "
               << (config.track_rdma_posted_slices ? "true" : "false");
+    LOG(INFO) << "use_rdma_twosided = "
+              << (config.use_rdma_twosided ? "true" : "false");
+    LOG(INFO) << "rdma_notify_enabled = "
+              << (config.rdma_notify_enabled ? "true" : "false");
+    LOG(INFO) << "rdma_notify_recv_count = " << config.rdma_notify_recv_count;
+    LOG(INFO) << "rdma_notify_buffer_size = " << config.rdma_notify_buffer_size;
+    LOG(INFO) << "rdma_notify_max_pending_sends = "
+              << config.rdma_notify_max_pending_sends;
+    LOG(INFO) << "rdma_notify_oob_fallback = "
+              << (config.rdma_notify_oob_fallback ? "true" : "false");
 }
 
 GlobalConfig& globalConfig() {
diff --git a/mooncake-transfer-engine/src/graceful_shutdown.cpp b/mooncake-transfer-engine/src/graceful_shutdown.cpp
index 39187add49..dd77b5b44b 100644
--- a/mooncake-transfer-engine/src/graceful_shutdown.cpp
+++ b/mooncake-transfer-engine/src/graceful_shutdown.cpp
@@ -95,7 +95,10 @@ void signalWatcher() {
     _Exit(1);
 }
 
-bool startSignalWatcherLocked(pid_t current_pid) {
+bool startSignalWatcherLocked(pid_t current_pid, sigset_t* saved_mask,
+                              bool* mask_blocked) {
+    *mask_blocked = false;
+
     if (g_signal_pipe[0] >= 0) close(g_signal_pipe[0]);
     if (g_signal_pipe[1] >= 0) close(g_signal_pipe[1]);
     g_signal_pipe[0] = -1;
@@ -107,16 +110,16 @@ bool startSignalWatcherLocked(pid_t current_pid) {
     // The watcher must never take SIGTERM/SIGINT itself: the handler writes
     // to the pipe and then pauses forever, so if it ran on the watcher
     // thread no reader would be left and cleanup would never run. Block both
-    // signals around thread creation so the watcher inherits the mask, and
-    // restore the caller's original mask on every path (it may have had its
-    // own reasons to block these signals).
+    // signals before creating the watcher so it inherits the mask; the caller
+    // restores the original mask once sigaction() has installed the handlers,
+    // so a signal arriving mid-install is not delivered while the disposition
+    // is still SIG_DFL.
     sigset_t watcher_block_set;
-    sigset_t saved_mask;
     sigemptyset(&watcher_block_set);
     sigaddset(&watcher_block_set, SIGTERM);
     sigaddset(&watcher_block_set, SIGINT);
-    const bool mask_blocked =
-        pthread_sigmask(SIG_BLOCK, &watcher_block_set, &saved_mask) == 0;
+    *mask_blocked =
+        pthread_sigmask(SIG_BLOCK, &watcher_block_set, saved_mask) == 0;
 
     bool watcher_started = false;
     try {
@@ -128,8 +131,6 @@ bool startSignalWatcherLocked(pid_t current_pid) {
     } catch (...) {
     }
 
-    if (mask_blocked) pthread_sigmask(SIG_SETMASK, &saved_mask, nullptr);
-
     if (!watcher_started) {
         close(g_signal_pipe[0]);
         close(g_signal_pipe[1]);
@@ -189,18 +190,24 @@ void installGracefulShutdownHandlers() {
         g_atexit_registered = true;
     }
 
-    if (!startSignalWatcherLocked(current_pid)) return;
-
-    struct sigaction sa{};
-    sa.sa_handler = shutdownSignalHandler;
-    sigemptyset(&sa.sa_mask);
-    sigaddset(&sa.sa_mask, SIGTERM);
-    sigaddset(&sa.sa_mask, SIGINT);
-    sa.sa_flags = 0;
-    sigaction(SIGTERM, &sa, nullptr);
-    sigaction(SIGINT, &sa, nullptr);
+    sigset_t saved_mask;
+    bool mask_blocked = false;
+    if (startSignalWatcherLocked(current_pid, &saved_mask, &mask_blocked)) {
+        struct sigaction sa{};
+        sa.sa_handler = shutdownSignalHandler;
+        sigemptyset(&sa.sa_mask);
+        sigaddset(&sa.sa_mask, SIGTERM);
+        sigaddset(&sa.sa_mask, SIGINT);
+        sa.sa_flags = 0;
+        sigaction(SIGTERM, &sa, nullptr);
+        sigaction(SIGINT, &sa, nullptr);
+
+        g_handlers_installed = true;
+    }
 
-    g_handlers_installed = true;
+    // Restore last: a signal that arrived mid-install stays pending until the
+    // handlers above are in place.
+    if (mask_blocked) pthread_sigmask(SIG_SETMASK, &saved_mask, nullptr);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/multi_transport.cpp b/mooncake-transfer-engine/src/multi_transport.cpp
index cfb13ca637..21e4d255b9 100644
--- a/mooncake-transfer-engine/src/multi_transport.cpp
+++ b/mooncake-transfer-engine/src/multi_transport.cpp
@@ -21,6 +21,7 @@
 #include "config.h"
 #include "multi_transport_locality.h"
 #include "transport/rdma_transport/rdma_transport.h"
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
 #ifdef USE_BAREX
 #include "transport/barex_transport/barex_transport.h"
 #endif
@@ -52,15 +53,22 @@
 #ifdef USE_MACA
 #include "transport/maca_transport/maca_transport.h"
 #endif
+#ifdef USE_MUSA
+#include "transport/musa_transport/musa_transport.h"
+#endif
 #ifdef USE_MNNVL
 #include "transport/nvlink_transport/nvlink_transport.h"
 #endif
 #ifdef USE_CXL
 #include "transport/cxl_transport/cxl_transport.h"
 #endif
+#include "transport/shm_transport/shm_transport.h"
 #ifdef USE_UBSHMEM
 #include "transport/ascend_transport/ubshmem_transport/ubshmem_transport.h"
 #endif
+#ifdef USE_FLAGCX
+#include "transport/flagcx_transport/flagcx_transport.h"
+#endif
 #ifdef USE_EFA
 #include "transport/efa_transport/efa_transport.h"
 #endif
@@ -99,6 +107,11 @@ MultiTransport::BatchID MultiTransport::allocateBatchID(size_t batch_size) {
 }
 
 Status MultiTransport::freeBatchID(BatchID batch_id) {
+    return freeBatchID(batch_id, std::function<void()>());
+}
+
+Status MultiTransport::freeBatchID(BatchID batch_id,
+                                   const std::function<void()>& before_delete) {
     auto& batch_desc = *((BatchDesc*)(batch_id));
     const size_t task_count = batch_desc.task_list.size();
     for (size_t task_id = 0; task_id < task_count; task_id++) {
@@ -107,6 +120,9 @@ Status MultiTransport::freeBatchID(BatchID batch_id) {
                 "BatchID cannot be freed until all tasks are done");
         }
     }
+    if (before_delete) {
+        before_delete();
+    }
     delete &batch_desc;
 #ifdef CONFIG_USE_BATCH_DESC_SET
     RWSpinlock::WriteGuard guard(batch_desc_lock_);
@@ -117,71 +133,85 @@ Status MultiTransport::freeBatchID(BatchID batch_id) {
 
 Status MultiTransport::submitTransfer(
     BatchID batch_id, const std::vector<TransferRequest>& entries) {
+    return submitTransfer(batch_id, entries, nullptr);
+}
+
+Status MultiTransport::submitTransfer(
+    BatchID batch_id, const std::vector<TransferRequest>& entries,
+    std::vector<size_t>* task_sizes) {
     auto& batch_desc = *((BatchDesc*)(batch_id));
-    if (batch_desc.task_list.size() + entries.size() > batch_desc.batch_size) {
+    if (!task_sizes &&
+        batch_desc.task_list.size() + entries.size() > batch_desc.batch_size) {
         return Status::TooManyRequests(
             "Exceed the limitation of batch capacity");
     }
 
     std::vector<Transport*> transports;
-    transports.reserve(entries.size());
-    for (const auto& request : entries) {
-        Transport* transport = nullptr;
-        auto status = selectTransport(request, transport);
-        if (!status.ok()) return status;
-        assert(transport);
-        transports.push_back(transport);
-    }
+    auto select_status = selectTransports(entries, transports);
+    if (!select_status.ok()) return select_status;
 
-    size_t task_id = batch_desc.task_list.size();
-    batch_desc.task_list.resize(task_id + entries.size());
-
-    struct TaskGroup {
-        uint64_t id;
-        Transport* transport;
-        std::vector<Transport::TransferTask*> tasks;
-    };
+    auto& task_list = batch_desc.task_list;
+    task_list.reserve(task_list.size() + entries.size());
     std::unordered_map<Transport*, std::vector<Transport::TransferTask*> >
         submit_tasks;
-    std::vector<TaskGroup> task_groups;
-    for (size_t i = 0; i < entries.size(); ++i) {
-        const auto& request = entries[i];
-        auto* transport = transports[i];
-        auto& task = batch_desc.task_list[task_id];
+    if (task_sizes) task_sizes->reserve(entries.size());
+    for (size_t i = 0; i < entries.size();) {
+        size_t count = 1;
+        const auto group_id = entries[i].task_group_id;
+        if (task_sizes && group_id != TransferRequest::kNoTaskGroup &&
+            transports[i]->supportsGroupedScatter()) {
+            while (i + count < entries.size() &&
+                   entries[i + count].task_group_id == group_id &&
+                   transports[i + count] == transports[i])
+                ++count;
+        }
+        auto& task = task_list.emplace_back();
         task.batch_id = batch_id;
-        task.transport_ = transport;
+        task.transport_ = transports[i];
 #ifdef USE_ASCEND_HETEROGENEOUS
-        task.request = const_cast<Transport::TransferRequest*>(&request);
+        task.request = const_cast<Transport::TransferRequest*>(&entries[i]);
 #else
-        task.request = &request;
+        task.request = &entries[i];
 #endif
-        ++task_id;
-        if (request.task_group_id == TransferRequest::kNoTaskGroup) {
-            submit_tasks[transport].push_back(&task);
-        } else if (!task_groups.empty() &&
-                   task_groups.back().id == request.task_group_id &&
-                   task_groups.back().transport == transport) {
-            task_groups.back().tasks.push_back(&task);
-        } else {
-            task_groups.push_back({request.task_group_id, transport, {&task}});
-        }
+        task.request_count = count;
+#ifdef USE_EVENT_DRIVEN_COMPLETION
+        if (count > 1) task.submission_sealed = false;
+#endif
+        submit_tasks[transports[i]].push_back(&task);
+        if (task_sizes) task_sizes->push_back(count);
+        i += count;
     }
+    if (task_sizes) batch_desc.batch_size = task_list.size();
     Status overall_status = Status::OK();
     for (auto& entry : submit_tasks) {
         auto status = entry.first->submitTransferTask(entry.second);
+#ifdef USE_EVENT_DRIVEN_COMPLETION
+        for (auto* task : entry.second)
+            if (task->request_count > 1)
+                Transport::Slice::sealTaskSubmission(task);
+#endif
         if (!status.ok()) {
             // LOG(ERROR) << "Failed to submit transfer task to "
             //            << entry.first->getName();
             overall_status = status;
         }
     }
-    for (auto& group : task_groups) {
-        auto status = group.transport->submitTransferTaskGroup(group.tasks);
-        if (!status.ok()) overall_status = status;
-    }
     return overall_status;
 }
 
+Status MultiTransport::submitScatter(
+    const std::vector<TransferRequest>& entries,
+    ScatterSubmission& submission) {
+    submission = {};
+    if (entries.empty())
+        return Status::InvalidArgument("scatter transfer is empty");
+    submission.batch_id = allocateBatchID(0);
+    if (submission.batch_id == static_cast<BatchID>(-1))
+        return Status::InvalidArgument(
+            "failed to allocate scatter transfer batch");
+    return submitTransfer(submission.batch_id, entries, &submission.task_sizes);
+}
+
 #ifdef ENABLE_MULTI_PROTOCOL
 Status MultiTransport::mp_submitTransfer(
     BatchID batch_id, const std::vector<TransferRequest>& entries,
@@ -273,9 +303,14 @@ Status MultiTransport::getTransferStatus(BatchID batch_id, size_t task_id,
     }
 
     // Fallback for tasks without a transport pointer (legacy path)
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the byte updates made by
+    // Slice::markSuccess().
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     assert(task.slice_count);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
@@ -294,13 +329,50 @@ Status MultiTransport::getTransferStatus(BatchID batch_id, size_t task_id,
     return Status::OK();
 }
 
+Status MultiTransport::getScatterRequestStatuses(
+    BatchID batch_id, size_t task_id,
+    std::vector<TransferStatusEnum>& request_statuses) {
+    auto& batch_desc = *((BatchDesc*)(batch_id));
+    if (task_id >= batch_desc.task_list.size())
+        return Status::InvalidArgument("Task ID out of range");
+
+    const auto& task = batch_desc.task_list[task_id];
+    if (!task.request || task.request_count == 0)
+        return Status::InvalidArgument("Invalid grouped scatter task");
+    const auto success_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    const auto failed_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    if (success_count + failed_count != task.slice_count)
+        return Status::InvalidArgument("Grouped scatter task is not complete");
+
+    request_statuses.assign(task.request_count, TransferStatusEnum::COMPLETED);
+    size_t slice_index = 0;
+    for (size_t i = 0; i < task.request_count; ++i) {
+        size_t remaining = task.request[i].length;
+        while (remaining != 0 && slice_index < task.slice_list.size()) {
+            const auto* slice = task.slice_list[slice_index++];
+            if (slice->length > remaining)
+                return Status::InvalidArgument(
+                    "Invalid grouped scatter slice layout");
+            remaining -= slice->length;
+            if (slice->status != Transport::Slice::SUCCESS)
+                request_statuses[i] = TransferStatusEnum::FAILED;
+        }
+        if (remaining != 0) request_statuses[i] = TransferStatusEnum::FAILED;
+    }
+    if (slice_index != task.slice_list.size())
+        return Status::InvalidArgument("Invalid grouped scatter slice layout");
+    return Status::OK();
+}
+
 Status MultiTransport::getBatchTransferStatus(BatchID batch_id,
                                               TransferStatus& status) {
     auto& batch_desc = *((BatchDesc*)(batch_id));
     const size_t task_count = batch_desc.task_list.size();
     status.transferred_bytes = 0;
 
-    if (batch_desc.is_finished.load(std::memory_order_acquire) ||
+    if (batch_desc.status_cached.load(std::memory_order_acquire) ||
         task_count == 0) {
         status.s = Transport::TransferStatusEnum::COMPLETED;
         status.transferred_bytes =
@@ -332,9 +404,10 @@ Status MultiTransport::getBatchTransferStatus(BatchID batch_id,
                    ? Transport::TransferStatusEnum::COMPLETED
                    : Transport::TransferStatusEnum::WAITING;
     if (status.s == Transport::TransferStatusEnum::COMPLETED) {
-        batch_desc.is_finished.store(true, std::memory_order_release);
         batch_desc.finished_transfer_bytes.store(status.transferred_bytes,
-                                                 std::memory_order_release);
+                                                 std::memory_order_relaxed);
+        batch_desc.status_cached.store(true, std::memory_order_release);
+        batch_desc.is_finished.store(true, std::memory_order_release);
     } else if (status.s == Transport::TransferStatusEnum::FAILED) {
         batch_desc.has_failure.store(true, std::memory_order_release);
     }
@@ -352,8 +425,18 @@ Transport* MultiTransport::installTransport(const std::string& proto,
     }
 #endif
     Transport* transport = nullptr;
-    if (std::string(proto) == "rdma") {
-        transport = new RdmaTransport();
+    if (std::string(proto) == "rdma" || std::string(proto) == "rdma_twosided") {
+        if ((proto == "rdma" && transport_map_.count("rdma_twosided")) ||
+            (proto == "rdma_twosided" && transport_map_.count("rdma"))) {
+            LOG(ERROR) << "Cannot install both rdma and rdma_twosided "
+                          "transports in the same Transfer Engine instance";
+            return nullptr;
+        }
+        if (std::string(proto) == "rdma") {
+            transport = new RdmaTransport();
+        } else {
+            transport = new RdmaTwoSidedTransport();
+        }
     }
 #ifdef USE_UB
     else if (std::string(proto) == "ub") {
@@ -412,6 +495,11 @@ Transport* MultiTransport::installTransport(const std::string& proto,
         transport = new MacaTransport();
     }
 #endif
+#ifdef USE_MUSA
+    else if (std::string(proto) == "musa") {
+        transport = new MusaTransport();
+    }
+#endif
 #ifdef USE_MNNVL
     else if (std::string(proto) == "nvlink") {
         transport = new NvlinkTransport();
@@ -422,11 +510,19 @@ Transport* MultiTransport::installTransport(const std::string& proto,
         transport = new CxlTransport();
     }
 #endif
+    else if (std::string(proto) == "shm") {
+        transport = new ShmTransport();
+    }
 #ifdef USE_UBSHMEM
     else if (std::string(proto) == "ubshmem") {
         transport = new UBShmemTransport();
     }
 #endif
+#ifdef USE_FLAGCX
+    else if (std::string(proto) == "flagcx") {
+        transport = new FlagCxTransport();
+    }
+#endif
 #ifdef USE_EFA
     else if (std::string(proto) == "efa") {
         transport = new EfaTransport();
@@ -492,13 +588,58 @@ Transport* MultiTransport::installTransport(const std::string& proto,
     return transport;
 }
 
+Status MultiTransport::selectTransports(
+    const std::vector<TransferRequest>& entries,
+    std::vector<Transport*>& transports) {
+    transports.clear();
+    transports.reserve(entries.size());
+    Transport* reused_transport = nullptr;
+    Transport::SegmentID reused_target = 0;
+    bool reuse_allowed = false;
+    const bool metacache = globalConfig().metacache;
+    for (const auto& request : entries) {
+        Transport* transport = nullptr;
+        // Reuse only address-independent routes within this submission. Mixed
+        // protocol segments must still resolve each address independently, and
+        // disabling the metadata cache must retain the explicit refresh
+        // behavior. This restores MultiTransport routing (protocol to
+        // Transport*), not RDMA's per-target SegmentDesc fetch inside
+        // submitTransferTask.
+        if (reuse_allowed && reused_transport && metacache &&
+            request.target_id == reused_target) {
+            transport = reused_transport;
+        } else {
+            auto status = selectTransport(request, transport, &reuse_allowed);
+            if (!status.ok()) return status;
+            assert(transport);
+            reused_transport = transport;
+            reused_target = request.target_id;
+        }
+        transports.push_back(transport);
+    }
+    return Status::OK();
+}
+
 Status MultiTransport::selectTransport(const TransferRequest& entry,
-                                       Transport*& transport) {
+                                       Transport*& transport,
+                                       bool* allows_reuse) {
     auto target_segment_desc = metadata_->getSegmentDescByID(entry.target_id);
     if (!target_segment_desc) {
+        if (allows_reuse) *allows_reuse = false;
         return Status::InvalidArgument("Invalid target segment ID " +
                                        std::to_string(entry.target_id));
     }
+#ifdef ENABLE_MULTI_PROTOCOL
+    // Offset-based routing is only compiled for mixed-protocol segments.
+    // A homogeneous batch can reuse this Transport*.
+    if (allows_reuse) {
+        *allows_reuse =
+            target_segment_desc->protocol.find(',') == std::string::npos;
+    }
+#else
+    if (allows_reuse) *allows_reuse = true;
+#endif
+
     auto proto = target_segment_desc->protocol;
 #ifdef ENABLE_MULTI_PROTOCOL
     // Multi-protocol segment (e.g. "rdma,hip"): a single batch may target
@@ -515,6 +656,8 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
             // that know they need the cross-node path to de-prioritize hip.
             if (p == "hip") return std::getenv("MC_DISABLE_HIP") ? 0 : 4;
             if (p == "maca") return std::getenv("MC_DISABLE_MACA") ? 0 : 4;
+            if (p == "musa") return std::getenv("MC_DISABLE_MUSA") ? 0 : 4;
+            if (p == "shm") return 4;
             if (p == "cxl") return 3;
             if (p == "rdma") return 2;
             if (p == "tcp") return 1;
@@ -526,8 +669,8 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
         // This makes the intra-node fast path (hip) and the cross-node path
         // (rdma) work automatically from a single multi-protocol segment,
         // without requiring the operator to set MC_DISABLE_HIP.
-        const bool hip_reachable =
-            isHipReachableTarget(target_segment_desc->name, local_server_name_);
+        const bool local_ipc_reachable = isLocalIpcReachableTarget(
+            target_segment_desc->name, local_server_name_);
         std::string chosen;
         int chosen_priority = -1;
         for (const auto& buffer : target_segment_desc->buffers) {
@@ -539,7 +682,11 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
                     : buffer.addr;
             if (entry.target_offset >= start &&
                 entry.target_offset < start + buffer.length) {
-                if (buffer.protocol == "hip" && !hip_reachable) continue;
+                if ((buffer.protocol == "hip" || buffer.protocol == "musa" ||
+                     buffer.protocol == "shm") &&
+                    !local_ipc_reachable) {
+                    continue;
+                }
                 int priority = protocol_priority(buffer.protocol);
                 if (priority > chosen_priority) {
                     chosen = buffer.protocol;
@@ -553,6 +700,10 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
                 "segment " +
                 std::to_string(entry.target_id));
         }
+        if (!transport_map_.count(chosen) && chosen == "rdma" &&
+            transport_map_.count("rdma_twosided")) {
+            chosen = "rdma_twosided";
+        }
         if (!transport_map_.count(chosen)) {
             return Status::NotSupportedTransport("Transport " + chosen +
                                                  " not installed");
@@ -560,7 +711,7 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
         if (globalConfig().trace) {
             LOG(INFO) << "MultiTransport::selectTransport route: target_id="
                       << entry.target_id << " segment_protocol=\"" << proto
-                      << "\" hip_reachable=" << hip_reachable
+                      << "\" local_ipc_reachable=" << local_ipc_reachable
                       << " chosen=" << chosen;
         }
         transport = transport_map_[chosen].get();
@@ -575,6 +726,13 @@ Status MultiTransport::selectTransport(const TransferRequest& entry,
         proto = "ascend";
     }
 #endif
+    // RdmaTwoSidedTransport still publishes segment protocol "rdma" (one-sided
+    // memory path). Route those segments to the installed twosided transport.
+    if (!transport_map_.count(proto) && proto == "rdma" &&
+        transport_map_.count("rdma_twosided")) {
+        transport = transport_map_["rdma_twosided"].get();
+        return Status::OK();
+    }
     if (!transport_map_.count(proto)) {
         return Status::NotSupportedTransport("Transport " + proto +
                                              " not installed");
@@ -600,11 +758,13 @@ Status MultiTransport::mp_selectTransport(const TransferRequest& entry,
         if (!item.empty()) protos.push_back(item);
     }
 
-    // hip GPU IPC cannot reach a remote host; downgrade an explicit hip
-    // preference to a cross-host-capable transport for a cross-host target
+    // hip GPU IPC and POSIX SHM cannot reach a remote host; downgrade an
+    // explicit intra-node preference to a cross-host-capable transport
     // (mirrors the locality gate in selectTransport). Prefer rdma, then tcp.
-    if (preferred_proto == "hip" &&
-        !isHipReachableTarget(target_segment_desc->name, local_server_name_)) {
+    if ((preferred_proto == "hip" || preferred_proto == "musa" ||
+         preferred_proto == "shm") &&
+        !isLocalIpcReachableTarget(target_segment_desc->name,
+                                   local_server_name_)) {
         std::string fallback;
         for (const char* candidate : {"rdma", "tcp"}) {
             if (std::find(protos.begin(), protos.end(), candidate) !=
@@ -615,7 +775,7 @@ Status MultiTransport::mp_selectTransport(const TransferRequest& entry,
         }
         if (fallback.empty()) {
             return Status::NotSupportedTransport(
-                "hip target is cross-host but segment " +
+                preferred_proto + " target is cross-host but segment " +
                 std::to_string(entry.target_id) +
                 " offers no cross-host transport (rdma/tcp)");
         }
@@ -631,11 +791,18 @@ Status MultiTransport::mp_selectTransport(const TransferRequest& entry,
         preferred_proto = "ascend";
     }
 #endif
+    if (!transport_map_.count(preferred_proto) && preferred_proto == "rdma" &&
+        transport_map_.count("rdma_twosided")) {
+        preferred_proto = "rdma_twosided";
+    }
     if (!transport_map_.count(preferred_proto)) {
         return Status::NotSupportedTransport("Transport " + preferred_proto +
                                              " not installed");
     }
-    if (std::find(protos.begin(), protos.end(), preferred_proto) ==
+    // Segment metadata still advertises "rdma" for the twosided install.
+    const std::string segment_proto =
+        (preferred_proto == "rdma_twosided") ? "rdma" : preferred_proto;
+    if (std::find(protos.begin(), protos.end(), segment_proto) ==
         protos.end()) {
         return Status::NotSupportedTransport(
             "Transport " + preferred_proto +
@@ -652,7 +819,11 @@ Transport* MultiTransport::getTransport(const std::string& proto) {
 }
 
 bool MultiTransport::isTcpOnly() const {
-    return transport_map_.size() == 1 && transport_map_.count("tcp") == 1;
+    // SHM is intra-node DRAM IPC, not a cross-host fabric. Ignore it so a
+    // tcp+shm engine still auto-enables Store same-process memcpy.
+    size_t n = transport_map_.size();
+    if (transport_map_.count("shm")) --n;
+    return n == 1 && transport_map_.count("tcp") == 1;
 }
 
 std::vector<Transport*> MultiTransport::listTransports() {
diff --git a/mooncake-transfer-engine/src/shared_segment/ascend_shared_segment.cpp b/mooncake-transfer-engine/src/shared_segment/ascend_shared_segment.cpp
new file mode 100644
index 0000000000..6cd8c32de9
--- /dev/null
+++ b/mooncake-transfer-engine/src/shared_segment/ascend_shared_segment.cpp
@@ -0,0 +1,305 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#ifdef USE_ASCEND_DIRECT
+
+#include <acl/acl.h>
+#include <glog/logging.h>
+
+#include <cstring>
+
+#include "shared_segment_internal.h"
+#include "transport/ascend_transport/ascend_direct_transport/adxl_compat.h"
+
+namespace mooncake {
+namespace {
+constexpr uint16_t kAscendBackendId = 1;
+// Used when the runtime cannot report a granularity; matches the smallest huge
+// page ACL falls back to for host allocations.
+constexpr uint64_t kFallbackGranularity = 2ULL * 1024 * 1024;
+constexpr size_t kMemAccessDescCount = 1;
+// The owner's pages are huge pages, so a peer's reservation has to be huge-page
+// backed too.
+constexpr uint64_t kReserveHugePageFlag = 1;
+constexpr size_t kBytesPerTB = 1024ULL * 1024ULL * 1024ULL * 1024ULL;
+// HIXL fabric mem defaults to [40TB, 72TB). Reserve at 78TB on A3 so the
+// shared-segment NoUCMemory window stays past that range.
+constexpr uintptr_t kA3ReserveStartAddr = 78ULL * kBytesPerTB;
+
+static_assert(sizeof(aclrtMemFabricHandle) <= kMaxHandleBytes,
+              "Fabric handle must fit into a shared segment blob");
+
+// Older AscendCL headers omit this symbol; a weak stub keeps the binary
+// loadable when the runtime has not shipped NoUCMemory yet.
+extern "C" __attribute__((weak)) aclError
+aclrtReserveMemAddressNoUCMemory(void** virPtr, size_t size, size_t alignment,
+                                 void* expectPtr, uint64_t flags);
+
+// Weak symbols resolve to null on older adxl shared objects instead of failing
+// to load; presence of ExportToShareableHandle gates the Ascend shared-segment
+// path.
+bool IsAdxlExportShareableHandleAvailable() {
+    return &adxl::AdxlEngine::ExportToShareableHandle != nullptr;
+}
+
+// Matches HIXL's A3 (V3) SoC set used for NoUCMemory reservations.
+bool IsA3Soc() {
+    const char* soc_name = aclrtGetSocName();
+    if (soc_name == nullptr || soc_name[0] == '\0') {
+        return false;
+    }
+    static constexpr const char* kA3SocNames[] = {
+        "Ascend910_9391", "Ascend910_9381", "Ascend910_9392",
+        "Ascend910_9382", "Ascend910_9372", "Ascend910_9362"};
+    for (const char* name : kA3SocNames) {
+        if (std::strcmp(soc_name, name) == 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+aclrtPhysicalMemProp BuildHostMemProp() {
+    aclrtPhysicalMemProp prop = {};
+    prop.handleType = ACL_MEM_HANDLE_TYPE_NONE;
+    prop.allocationType = ACL_MEM_ALLOCATION_TYPE_PINNED;
+    prop.reserve = 0;
+    prop.memAttr = ACL_MEM_P2P_HUGE;
+    prop.location.type = ACL_MEM_LOCATION_TYPE_HOST;
+    prop.location.id = 0;
+    return prop;
+}
+
+// Host pages are only bound to the host by Map; the NPU needs an explicit grant
+// before kernels can touch them. AdxlEngine::MallocMem already does this for
+// the owner. location.id is a driver logical id; aclrtGetDevice returns a user
+// id (ASCEND_RT_VISIBLE_DEVICES), so convert before SetAccess.
+Status GrantDeviceAccess(void* addr, uint64_t size) {
+    int32_t user_id = -1;
+    int32_t driver_id = -1;
+    auto ret = aclrtGetDevice(&user_id);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory("aclrtGetDevice failed for MemSetAccess, ret " +
+                              std::to_string(ret));
+    }
+    ret = aclrtGetLogicDevIdByUserDevId(user_id, &driver_id);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory(
+            "aclrtGetLogicDevIdByUserDevId failed for MemSetAccess, ret " +
+            std::to_string(ret));
+    }
+    aclrtMemAccessDesc desc{};
+    desc.flags = ACL_RT_MEM_ACCESS_FLAGS_READWRITE;
+    desc.location.type = ACL_MEM_LOCATION_TYPE_DEVICE;
+    desc.location.id = static_cast<uint32_t>(driver_id);
+    ret = aclrtMemSetAccess(addr, size, &desc, kMemAccessDescCount);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory(
+            "aclrtMemSetAccess failed for the imported shared segment, ret " +
+            std::to_string(ret));
+    }
+    return Status::OK();
+}
+
+class AscendSharedSegmentBackend : public SharedSegmentBackend {
+   public:
+    ~AscendSharedSegmentBackend() override { Release(); }
+
+    uint64_t Granularity(const SharedSegmentOptions& options) const override;
+
+    Status CreateOwner(uint64_t size, const SharedSegmentOptions& options,
+                       uintptr_t& base_addr,
+                       std::vector<uint8_t>& handle) override;
+
+    Status ReserveLocal(uint64_t size, const SharedSegmentOptions& options,
+                        uintptr_t& base_addr) override;
+
+    Status ImportAndMap(uint64_t size, const SharedSegmentOptions& options,
+                        const std::vector<uint8_t>& handle) override;
+
+    // After MemSetAccess the host SVM VA is device-accessible; expose it so
+    // Python can wrap NPU tensors (owner via MallocMem, peer via ImportAndMap).
+    uintptr_t DeviceAddr() const override {
+        if (owner_addr_ != nullptr) {
+            return reinterpret_cast<uintptr_t>(owner_addr_);
+        }
+        if (mapped_ && reserved_addr_ != nullptr) {
+            return reinterpret_cast<uintptr_t>(reserved_addr_);
+        }
+        return 0;
+    }
+
+    uint16_t BackendId() const override { return kAscendBackendId; }
+
+   private:
+    void Release();
+
+    void* owner_addr_ = nullptr;
+    void* reserved_addr_ = nullptr;
+    aclrtDrvMemHandle imported_handle_ = nullptr;
+    bool mapped_ = false;
+};
+
+uint64_t AscendSharedSegmentBackend::Granularity(
+    const SharedSegmentOptions&) const {
+    // adxl may still fall back to smaller pages than the property asks for;
+    // that only wastes a little address space, whereas an allocation size below
+    // the granularity is rejected outright.
+    auto prop = BuildHostMemProp();
+    size_t granularity = 0;
+    auto ret = aclrtMemGetAllocationGranularity(
+        &prop, ACL_RT_MEM_ALLOC_GRANULARITY_MINIMUM, &granularity);
+    if (ret != ACL_ERROR_NONE || granularity == 0) {
+        return kFallbackGranularity;
+    }
+    return granularity;
+}
+
+Status AscendSharedSegmentBackend::CreateOwner(
+    uint64_t size, const SharedSegmentOptions& options, uintptr_t& base_addr,
+    std::vector<uint8_t>& handle) {
+    // MallocMem takes the device from the calling thread rather than an
+    // argument, so a mismatch would hand peers memory pinned to the wrong NUMA
+    // node and granted to the wrong device.
+    int32_t current_device = -1;
+    auto ret = aclrtGetDevice(&current_device);
+    if (ret != ACL_ERROR_NONE || current_device != options.device_id) {
+        return Status::InvalidArgument(
+            "Shared segment owner must run on device " +
+            std::to_string(options.device_id) + ", but the current device is " +
+            std::to_string(current_device));
+    }
+    void* addr = nullptr;
+    auto status = adxl::AdxlEngine::MallocMem(adxl::MEM_HOST, size, &addr);
+    if (status != adxl::SUCCESS) {
+        return Status::Memory(
+            "AdxlEngine::MallocMem failed for a shared segment of " +
+            std::to_string(size) + " bytes, status " + std::to_string(status));
+    }
+    adxl::ShareableHandle exported{};
+    status = adxl::AdxlEngine::ExportToShareableHandle(addr, exported);
+    if (status != adxl::SUCCESS) {
+        (void)adxl::AdxlEngine::FreeMem(addr);
+        return Status::Memory(
+            "AdxlEngine::ExportToShareableHandle failed for the shared "
+            "segment, status " +
+            std::to_string(status));
+    }
+
+    owner_addr_ = addr;
+    base_addr = reinterpret_cast<uintptr_t>(addr);
+    handle.assign(exported.data, exported.data + sizeof(exported.data));
+    return Status::OK();
+}
+
+Status AscendSharedSegmentBackend::ReserveLocal(
+    uint64_t size, const SharedSegmentOptions& options, uintptr_t& base_addr) {
+    (void)options;
+    void* addr = nullptr;
+    // Same policy as HIXL VirtualMemoryManager::ReserveMemAddress: on A3 try
+    // NoUCMemory at a fixed start VA first, then fall back when unsupported.
+    if (IsA3Soc() && &aclrtReserveMemAddressNoUCMemory != nullptr) {
+        void* start_va = reinterpret_cast<void*>(kA3ReserveStartAddr);
+        auto ret = aclrtReserveMemAddressNoUCMemory(&addr, size, 0, start_va,
+                                                    kReserveHugePageFlag);
+        if (ret == ACL_ERROR_NONE) {
+            reserved_addr_ = addr;
+            base_addr = reinterpret_cast<uintptr_t>(addr);
+            return Status::OK();
+        }
+        if (ret != ACL_ERROR_RT_FEATURE_NOT_SUPPORT) {
+            return Status::Memory(
+                "aclrtReserveMemAddressNoUCMemory failed for " +
+                std::to_string(size) + " bytes, ret " + std::to_string(ret));
+        }
+    }
+    auto ret =
+        aclrtReserveMemAddress(&addr, size, 0, nullptr, kReserveHugePageFlag);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory("aclrtReserveMemAddress failed for " +
+                              std::to_string(size) + " bytes, ret " +
+                              std::to_string(ret));
+    }
+    reserved_addr_ = addr;
+    base_addr = reinterpret_cast<uintptr_t>(addr);
+    return Status::OK();
+}
+
+Status AscendSharedSegmentBackend::ImportAndMap(
+    uint64_t size, const SharedSegmentOptions& options,
+    const std::vector<uint8_t>& handle) {
+    (void)options;
+    if (reserved_addr_ == nullptr) {
+        return Status::InvalidArgument(
+            "Shared segment import needs a reserved address window");
+    }
+    if (handle.size() != sizeof(aclrtMemFabricHandle)) {
+        return Status::InvalidArgument(
+            "Shared segment owner handle has an unexpected length");
+    }
+    aclrtMemFabricHandle share_handle{};
+    memcpy(share_handle.data, handle.data(), handle.size());
+    auto ret = aclrtMemImportFromShareableHandleV2(
+        &share_handle, ACL_MEM_SHARE_HANDLE_TYPE_FABRIC, 0, &imported_handle_);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory(
+            "aclrtMemImportFromShareableHandleV2 failed for the shared "
+            "segment, ret " +
+            std::to_string(ret));
+    }
+    auto* addr = reserved_addr_;
+    ret = aclrtMapMem(addr, size, 0, imported_handle_, 0);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory(
+            "aclrtMapMem failed for the shared segment, ret " +
+            std::to_string(ret));
+    }
+    mapped_ = true;
+    return GrantDeviceAccess(addr, size);
+}
+
+void AscendSharedSegmentBackend::Release() {
+    if (owner_addr_ != nullptr) {
+        (void)adxl::AdxlEngine::FreeMem(owner_addr_);
+        owner_addr_ = nullptr;
+    }
+    if (mapped_) {
+        (void)aclrtUnmapMem(reserved_addr_);
+        mapped_ = false;
+    }
+    if (imported_handle_ != nullptr) {
+        (void)aclrtFreePhysical(imported_handle_);
+        imported_handle_ = nullptr;
+    }
+    if (reserved_addr_ != nullptr) {
+        (void)aclrtReleaseMemAddress(reserved_addr_);
+        reserved_addr_ = nullptr;
+    }
+}
+}  // namespace
+
+std::unique_ptr<SharedSegmentBackend> CreateAscendSharedSegmentBackend() {
+    if (!IsAdxlExportShareableHandleAvailable()) {
+        // Callers probe support before every attempt, so say this only once.
+        LOG_FIRST_N(WARNING, 1)
+            << "Shared segments need an adxl runtime that supports "
+               "ExportToShareableHandle";
+        return nullptr;
+    }
+    return std::make_unique<AscendSharedSegmentBackend>();
+}
+
+}  // namespace mooncake
+
+#endif  // USE_ASCEND_DIRECT
diff --git a/mooncake-transfer-engine/src/shared_segment/mmap_shared_segment.cpp b/mooncake-transfer-engine/src/shared_segment/mmap_shared_segment.cpp
new file mode 100644
index 0000000000..b5e7117034
--- /dev/null
+++ b/mooncake-transfer-engine/src/shared_segment/mmap_shared_segment.cpp
@@ -0,0 +1,446 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif
+
+#include <glog/logging.h>
+
+#include <cerrno>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <fcntl.h>
+#include <string>
+#include <sys/mman.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#ifdef __has_include
+#if __has_include(<linux/memfd.h>)
+#include <linux/memfd.h>
+#endif
+#endif
+
+#include "shared_segment_internal.h"
+
+#if defined(USE_ASCEND_DIRECT)
+#include <acl/acl.h>
+#endif
+
+#ifndef MFD_CLOEXEC
+#define MFD_CLOEXEC 0x0001U
+#endif
+
+namespace mooncake {
+namespace {
+constexpr uint16_t kMmapBackendId = 3;
+// Matches the common PMD THP size when sysfs is unavailable.
+constexpr uint64_t kFallbackHugePageSize = 2ULL * 1024 * 1024;
+constexpr const char* kThpPmdSizePath =
+    "/sys/kernel/mm/transparent_hugepage/hpage_pmd_size";
+constexpr const char* kShmemThpEnabledPath =
+    "/sys/kernel/mm/transparent_hugepage/shmem_enabled";
+
+// memfd without MFD_HUGETLB is a tmpfs/shmem inode, so shmem THP applies.
+// Sysfs looks like "always within_size [advise] never deny force".
+bool ShmemThpEnabled() {
+    static const bool kEnabled = []() -> bool {
+        FILE* fp = std::fopen(kShmemThpEnabledPath, "r");
+        if (fp == nullptr) {
+            return false;
+        }
+        char buf[256];
+        const char* line = std::fgets(buf, sizeof(buf), fp);
+        std::fclose(fp);
+        if (line == nullptr) {
+            return false;
+        }
+        const char* open = std::strchr(buf, '[');
+        if (open == nullptr) {
+            return false;
+        }
+        const char* close = std::strchr(open + 1, ']');
+        if (close == nullptr || close <= open + 1) {
+            return false;
+        }
+        const std::string mode(open + 1, close);
+        return mode != "never" && mode != "deny";
+    }();
+    return kEnabled;
+}
+
+uint64_t HugePageSize() {
+    static const uint64_t kSize = []() -> uint64_t {
+        FILE* fp = std::fopen(kThpPmdSizePath, "r");
+        if (fp != nullptr) {
+            unsigned long long value = 0;
+            const int matched = std::fscanf(fp, "%llu", &value);
+            std::fclose(fp);
+            if (matched == 1 && value > 0 && (value & (value - 1)) == 0) {
+                return static_cast<uint64_t>(value);
+            }
+        }
+        return kFallbackHugePageSize;
+    }();
+    return kSize;
+}
+
+void AdviseTransparentHugePages(void* addr, uint64_t size) {
+#ifdef MADV_HUGEPAGE
+    if (addr == nullptr || size == 0) {
+        return;
+    }
+    if (madvise(addr, size, MADV_HUGEPAGE) != 0) {
+        VLOG(1) << "madvise(MADV_HUGEPAGE) failed for shared segment mmap: "
+                << std::strerror(errno);
+    }
+#else
+    (void)addr;
+    (void)size;
+#endif
+}
+
+void AdviseDontFork(void* addr, uint64_t size) {
+#ifdef MADV_DONTFORK
+    if (addr == nullptr || size == 0) {
+        return;
+    }
+    if (madvise(addr, size, MADV_DONTFORK) != 0) {
+        LOG(WARNING) << "madvise(MADV_DONTFORK) failed for shared segment: "
+                     << std::strerror(errno);
+    }
+#else
+    (void)addr;
+    (void)size;
+#endif
+}
+
+int CreateAnonymousMemFd() {
+#ifdef __NR_memfd_create
+    return static_cast<int>(syscall(__NR_memfd_create, "mcss", MFD_CLOEXEC));
+#else
+    errno = ENOSYS;
+    return -1;
+#endif
+}
+
+// Leave a PROT_NONE window whose address is aligned to the THP PMD size so a
+// later MAP_FIXED memfd map can use 2MiB pages. Falls back to an unaligned
+// reservation if the oversized mmap fails.
+void* ReserveAlignedWindow(uint64_t size, uint64_t align) {
+    if (align == 0 || (align & (align - 1)) != 0) {
+        align = HugePageSize();
+    }
+    const uint64_t span = size + align;
+    void* raw =
+        mmap(nullptr, span, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    if (raw != MAP_FAILED) {
+        const auto start = reinterpret_cast<uintptr_t>(raw);
+        const auto aligned = (start + static_cast<uintptr_t>(align) - 1) &
+                             ~(static_cast<uintptr_t>(align) - 1);
+        const auto end = aligned + size;
+        const auto raw_end = start + span;
+        if (aligned > start) {
+            (void)munmap(raw, aligned - start);
+        }
+        if (raw_end > end) {
+            (void)munmap(reinterpret_cast<void*>(end), raw_end - end);
+        }
+        return reinterpret_cast<void*>(aligned);
+    }
+    return mmap(nullptr, size, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+}
+
+// Touch one byte per PMD so THP can back the range with 2MiB pages. If THP
+// cannot allocate, the kernel leaves 4KiB pages. Never uses the HugeTLB pool.
+void PrefaultAnonymousRange(void* addr, uint64_t size, uint64_t stride) {
+    if (addr == nullptr || size == 0 || stride == 0) {
+        return;
+    }
+    auto* bytes = static_cast<volatile uint8_t*>(addr);
+    for (uint64_t off = 0; off < size; off += stride) {
+        bytes[off] = 0;
+    }
+    bytes[size - 1] = 0;
+}
+
+Status MapMemFd(int fd, uint64_t size, void* hint, void*& addr) {
+    int map_flags = MAP_SHARED;
+    if (hint != nullptr) {
+        map_flags |= MAP_FIXED;
+    }
+    void* mapped = mmap(hint, size, PROT_READ | PROT_WRITE, map_flags, fd, 0);
+    if (mapped == MAP_FAILED) {
+        return Status::Memory(std::string("mmap failed: ") +
+                              std::strerror(errno));
+    }
+    addr = mapped;
+    return Status::OK();
+}
+
+// Unnamed memfd (no MFD_HUGETLB, no nr_hugepages). MADV_HUGEPAGE is applied
+// before any page is faulted so the kernel can use THP; otherwise 4KiB pages.
+Status CreateAndMapMemFd(uint64_t size, int& fd, void*& addr) {
+    fd = CreateAnonymousMemFd();
+    if (fd < 0) {
+        return Status::Memory(std::string("memfd_create failed: ") +
+                              std::strerror(errno));
+    }
+    if (ftruncate(fd, static_cast<off_t>(size)) != 0) {
+        const int err = errno;
+        close(fd);
+        fd = -1;
+        return Status::Memory(std::string("ftruncate failed: ") +
+                              std::strerror(err));
+    }
+    void* hint = ReserveAlignedWindow(size, HugePageSize());
+    if (hint == MAP_FAILED) {
+        hint = nullptr;
+    }
+    auto status = MapMemFd(fd, size, hint, addr);
+    if (!status.ok() && hint != nullptr) {
+        (void)munmap(hint, size);
+        hint = nullptr;
+        status = MapMemFd(fd, size, nullptr, addr);
+    }
+    if (!status.ok()) {
+        close(fd);
+        fd = -1;
+        return status;
+    }
+    AdviseTransparentHugePages(addr, size);
+    PrefaultAnonymousRange(addr, size, HugePageSize());
+    AdviseDontFork(addr, size);
+    return Status::OK();
+}
+
+std::string EncodeMemFdHandle(int fd) {
+    char name[64];
+    std::snprintf(name, sizeof(name), "/proc/%d/fd/%d",
+                  static_cast<int>(getpid()), fd);
+    return name;
+}
+
+bool IsMemFdHandle(const std::string& name) {
+    return name.rfind("/proc/", 0) == 0 &&
+           name.find("/fd/") != std::string::npos;
+}
+
+Status HostRegister(void* addr, uint64_t size, int32_t device_id,
+                    void** ascend_dev_ptr) {
+#if defined(USE_ASCEND_DIRECT)
+    // The registration follows the calling thread's device, so the caller has
+    // to already be on the one the segment is granted to. Switching it here
+    // would leave the caller on a device it never asked for.
+    int32_t current_device = -1;
+    auto ret = aclrtGetDevice(&current_device);
+    if (ret != ACL_ERROR_NONE || current_device != device_id) {
+        return Status::InvalidArgument(
+            "Shared segment mmap must run on device " +
+            std::to_string(device_id) + ", but the current device is " +
+            std::to_string(current_device));
+    }
+    void* dev_ptr = nullptr;
+    ret = aclrtHostRegister(addr, size, ACL_HOST_REGISTER_MAPPED, &dev_ptr);
+    if (ret != ACL_ERROR_NONE) {
+        return Status::Memory(
+            "aclrtHostRegister failed for shared segment mmap, ret " +
+            std::to_string(ret));
+    }
+    if (ascend_dev_ptr != nullptr) {
+        *ascend_dev_ptr = dev_ptr;
+    }
+    return Status::OK();
+#else
+    (void)addr;
+    (void)size;
+    (void)device_id;
+    (void)ascend_dev_ptr;
+    return Status::NotImplemented(
+        "Shared segment mmap needs Ascend for HostRegister");
+#endif
+}
+
+void HostUnregister(void* addr, void* /*ascend_dev_ptr*/) {
+#if defined(USE_ASCEND_DIRECT)
+    if (addr != nullptr) {
+        (void)aclrtHostUnregister(addr);
+    }
+#else
+    (void)addr;
+#endif
+}
+
+class MmapSharedSegmentBackend : public SharedSegmentBackend {
+   public:
+    ~MmapSharedSegmentBackend() override { Release(); }
+
+    uint64_t Granularity(
+        const SharedSegmentOptions& /*options*/) const override {
+        // Align length to the THP PMD size so MADV_HUGEPAGE can use 2MiB
+        // pages. 4KiB fallback still accepts a PMD-aligned length.
+        return HugePageSize();
+    }
+
+    Status CreateOwner(uint64_t size, const SharedSegmentOptions& options,
+                       uintptr_t& base_addr,
+                       std::vector<uint8_t>& handle) override;
+
+    Status ReserveLocal(uint64_t size, const SharedSegmentOptions& options,
+                        uintptr_t& base_addr) override;
+
+    Status ImportAndMap(uint64_t size, const SharedSegmentOptions& options,
+                        const std::vector<uint8_t>& handle) override;
+
+    uint16_t BackendId() const override { return kMmapBackendId; }
+
+    uintptr_t DeviceAddr() const override {
+        return reinterpret_cast<uintptr_t>(ascend_dev_ptr_);
+    }
+
+   private:
+    Status RegisterMapped(const SharedSegmentOptions& options);
+    void Release();
+
+    void* addr_ = nullptr;
+    uint64_t size_ = 0;
+    int memfd_ = -1;
+    bool registered_ = false;
+    void* ascend_dev_ptr_ = nullptr;
+};
+
+Status MmapSharedSegmentBackend::RegisterMapped(
+    const SharedSegmentOptions& options) {
+    if (!options.host_register) {
+        return Status::OK();
+    }
+    auto status =
+        HostRegister(addr_, size_, options.device_id, &ascend_dev_ptr_);
+    if (!status.ok()) {
+        return status;
+    }
+    registered_ = true;
+    return Status::OK();
+}
+
+Status MmapSharedSegmentBackend::CreateOwner(
+    uint64_t size, const SharedSegmentOptions& options, uintptr_t& base_addr,
+    std::vector<uint8_t>& handle) {
+    int fd = -1;
+    void* mapped = nullptr;
+    auto status = CreateAndMapMemFd(size, fd, mapped);
+    if (!status.ok()) {
+        return status;
+    }
+    LOG(INFO) << "Shared segment mmap: unnamed memfd + THP hint (no HugeTLB), "
+              << "size " << size
+              << ", shmem_thp=" << (ShmemThpEnabled() ? "on" : "off");
+
+    addr_ = mapped;
+    size_ = size;
+    memfd_ = fd;
+    status = RegisterMapped(options);
+    if (!status.ok()) {
+        return status;
+    }
+    base_addr = reinterpret_cast<uintptr_t>(addr_);
+    const std::string name = EncodeMemFdHandle(memfd_);
+    handle.assign(name.begin(), name.end());
+    return Status::OK();
+}
+
+Status MmapSharedSegmentBackend::ReserveLocal(
+    uint64_t size, const SharedSegmentOptions& /*options*/,
+    uintptr_t& base_addr) {
+    void* reserved = ReserveAlignedWindow(size, HugePageSize());
+    if (reserved == MAP_FAILED) {
+        return Status::Memory(std::string("mmap reserve failed: ") +
+                              std::strerror(errno));
+    }
+    addr_ = reserved;
+    size_ = size;
+    base_addr = reinterpret_cast<uintptr_t>(addr_);
+    return Status::OK();
+}
+
+Status MmapSharedSegmentBackend::ImportAndMap(
+    uint64_t size, const SharedSegmentOptions& options,
+    const std::vector<uint8_t>& handle) {
+    if (addr_ == nullptr || size_ == 0) {
+        return Status::InvalidArgument(
+            "Shared segment import needs a reserved address window");
+    }
+    if (size != size_) {
+        return Status::InvalidArgument(
+            "Shared segment import size does not match the reservation");
+    }
+    if (handle.empty() || handle.size() > kMaxHandleBytes) {
+        return Status::InvalidArgument(
+            "Shared segment owner handle has an unexpected length");
+    }
+    const std::string name(handle.begin(), handle.end());
+    if (!IsMemFdHandle(name)) {
+        return Status::InvalidArgument(
+            "Shared segment owner handle is not a memfd /proc/<pid>/fd path");
+    }
+
+    int fd = open(name.c_str(), O_RDWR);
+    if (fd < 0) {
+        return Status::Memory(std::string("open memfd handle failed: ") +
+                              std::strerror(errno) + " (" + name + ")");
+    }
+
+    void* mapped = addr_;
+    auto status = MapMemFd(fd, size, mapped, mapped);
+    close(fd);
+    if (!status.ok()) {
+        return status;
+    }
+    addr_ = mapped;
+    AdviseTransparentHugePages(addr_, size);
+    AdviseDontFork(addr_, size);
+    status = RegisterMapped(options);
+    if (!status.ok()) {
+        return status;
+    }
+    return Status::OK();
+}
+
+void MmapSharedSegmentBackend::Release() {
+    if (registered_) {
+        HostUnregister(addr_, ascend_dev_ptr_);
+        registered_ = false;
+        ascend_dev_ptr_ = nullptr;
+    }
+    if (addr_ != nullptr) {
+        (void)munmap(addr_, size_);
+        addr_ = nullptr;
+    }
+    if (memfd_ >= 0) {
+        close(memfd_);
+        memfd_ = -1;
+    }
+    size_ = 0;
+}
+}  // namespace
+
+std::unique_ptr<SharedSegmentBackend> CreateMmapSharedSegmentBackend() {
+    // Anonymous memfd + mmap is always available. HostRegister is optional and
+    // is checked when SharedSegmentOptions::host_register is set.
+    return std::make_unique<MmapSharedSegmentBackend>();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/shared_segment/shared_segment.cpp b/mooncake-transfer-engine/src/shared_segment/shared_segment.cpp
new file mode 100644
index 0000000000..21b0fe6ee8
--- /dev/null
+++ b/mooncake-transfer-engine/src/shared_segment/shared_segment.cpp
@@ -0,0 +1,328 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#include "shared_segment/shared_segment.h"
+
+#include <cstring>
+#include <glog/logging.h>
+
+#include "shared_segment_internal.h"
+
+namespace mooncake {
+
+// Backend-specific creators are implementation details of the generic factory
+// below and are intentionally not exposed through the internal header.
+std::unique_ptr<SharedSegmentBackend> CreateMmapSharedSegmentBackend();
+
+#ifdef USE_ASCEND_DIRECT
+std::unique_ptr<SharedSegmentBackend> CreateAscendSharedSegmentBackend();
+#endif
+
+namespace {
+constexpr uint32_t kSegmentBlobMagic = 0x4D435353;  // "MCSS"
+constexpr uint16_t kSegmentBlobVersion = 1;
+constexpr uint64_t kFnvOffsetBasis = 1469598103934665603ULL;
+constexpr uint64_t kFnvPrime = 1099511628211ULL;
+// A segment that does not fit in the virtual address space several times over
+// is a declaration bug.
+constexpr uint64_t kMaxSegmentBytes = 1ULL << 46;
+
+std::string SelectSharedSegmentBackend(bool mmap) {
+    if (mmap) {
+        return "mmap";
+    }
+#if defined(USE_ASCEND_DIRECT)
+    return "ascend";
+#else
+    return {};
+#endif
+}
+
+uint64_t HashBytes(uint64_t seed, const void* data, size_t length) {
+    const auto* bytes = static_cast<const uint8_t*>(data);
+    uint64_t hash = seed;
+    for (size_t i = 0; i < length; ++i) {
+        hash = (hash ^ bytes[i]) * kFnvPrime;
+    }
+    return hash;
+}
+
+uint64_t HashValue(uint64_t seed, uint64_t value) {
+    return HashBytes(seed, &value, sizeof(value));
+}
+
+Status ValidateOptions(const SharedSegmentOptions& options) {
+    if (options.world_size == 0) {
+        return Status::InvalidArgument(
+            "Shared segment world_size must not be zero");
+    }
+    if (options.rank_id >= options.world_size ||
+        options.owner_rank >= options.world_size) {
+        return Status::InvalidArgument(
+            "Shared segment rank_id and owner_rank must be below world_size");
+    }
+    if (options.host_register && !options.mmap) {
+        return Status::InvalidArgument(
+            "Shared segment host_register requires mmap=true");
+    }
+    return Status::OK();
+}
+
+Status CheckPeerBlob(uint32_t rank, uint16_t backend_id, uint64_t fingerprint,
+                     uint64_t alloc_size, const std::string& blob,
+                     SegmentBlobHeader& header, std::vector<uint8_t>& handle) {
+    auto status = DecodeSegmentBlob(blob, header, handle);
+    if (!status.ok()) {
+        return status;
+    }
+    if (header.rank_id != rank) {
+        return Status::InvalidArgument("Shared segment blob of rank " +
+                                       std::to_string(rank) +
+                                       " carries a different rank id");
+    }
+    if (header.backend_id != backend_id) {
+        return Status::InvalidArgument("Shared segment backend of rank " +
+                                       std::to_string(rank) + " differs");
+    }
+    if (header.fingerprint != fingerprint) {
+        return Status::InvalidArgument("Shared segment declaration of rank " +
+                                       std::to_string(rank) +
+                                       " differs from the local one");
+    }
+    if (header.alloc_size != alloc_size) {
+        return Status::InvalidArgument(
+            "Shared segment allocation size of rank " + std::to_string(rank) +
+            " differs from the local one");
+    }
+    return Status::OK();
+}
+
+Status ExtractOwnerHandle(const SharedSegmentOptions& options,
+                          uint16_t backend_id, uint64_t fingerprint,
+                          uint64_t alloc_size,
+                          const std::vector<std::string>& blobs,
+                          std::vector<uint8_t>& owner_handle) {
+    if (blobs.size() != options.world_size) {
+        return Status::InvalidArgument(
+            "Shared segment expects one blob per rank, got " +
+            std::to_string(blobs.size()));
+    }
+    for (uint32_t rank = 0; rank < blobs.size(); ++rank) {
+        SegmentBlobHeader header{};
+        std::vector<uint8_t> handle;
+        auto status = CheckPeerBlob(rank, backend_id, fingerprint, alloc_size,
+                                    blobs[rank], header, handle);
+        if (!status.ok()) {
+            return status;
+        }
+        if (rank == options.owner_rank) {
+            owner_handle = std::move(handle);
+        }
+    }
+    if (owner_handle.empty()) {
+        return Status::InvalidArgument(
+            "Shared segment owner rank did not export a handle");
+    }
+    return Status::OK();
+}
+}  // namespace
+
+uint64_t AlignUp(uint64_t value, uint64_t alignment) {
+    return (value + alignment - 1) / alignment * alignment;
+}
+
+uint64_t ComputeSegmentFingerprint(const std::string& name, uint64_t size,
+                                   const SharedSegmentOptions& options) {
+    uint64_t hash = HashBytes(kFnvOffsetBasis, name.data(), name.size());
+    hash = HashValue(hash, size);
+    hash = HashValue(hash, options.world_size);
+    hash = HashValue(hash, options.owner_rank);
+    hash = HashValue(hash, options.mmap ? 1ULL : 0ULL);
+    hash = HashValue(hash, options.host_register ? 1ULL : 0ULL);
+    return hash;
+}
+
+Status EncodeSegmentBlob(const SegmentBlobHeader& header,
+                         const std::vector<uint8_t>& handle,
+                         std::string& blob) {
+    if (handle.size() > kMaxHandleBytes) {
+        return Status::InvalidArgument("Shared segment handle of " +
+                                       std::to_string(handle.size()) +
+                                       " bytes does not fit in a blob");
+    }
+    blob.assign(kSegmentBlobBytes, '\0');
+    SegmentBlobHeader stamped = header;
+    stamped.magic = kSegmentBlobMagic;
+    stamped.version = kSegmentBlobVersion;
+    stamped.handle_bytes = static_cast<uint32_t>(handle.size());
+    memcpy(blob.data(), &stamped, sizeof(stamped));
+    if (!handle.empty()) {
+        memcpy(blob.data() + sizeof(stamped), handle.data(), handle.size());
+    }
+    return Status::OK();
+}
+
+Status DecodeSegmentBlob(const std::string& blob, SegmentBlobHeader& header,
+                         std::vector<uint8_t>& handle) {
+    if (blob.size() != kSegmentBlobBytes) {
+        return Status::InvalidArgument(
+            "Shared segment blob has an unexpected length");
+    }
+    memcpy(&header, blob.data(), sizeof(header));
+    if (header.magic != kSegmentBlobMagic) {
+        return Status::InvalidArgument("Shared segment blob magic mismatch");
+    }
+    if (header.version != kSegmentBlobVersion) {
+        return Status::InvalidArgument(
+            "Shared segment blob version mismatch, peers run different builds");
+    }
+    if (header.handle_bytes > kMaxHandleBytes) {
+        return Status::InvalidArgument(
+            "Shared segment blob declares an oversized handle");
+    }
+    const auto* payload =
+        reinterpret_cast<const uint8_t*>(blob.data()) + sizeof(header);
+    handle.assign(payload, payload + header.handle_bytes);
+    return Status::OK();
+}
+
+std::unique_ptr<SharedSegmentBackend> CreateSharedSegmentBackend(
+    const std::string& impl) {
+    if (impl == "mmap") {
+        return CreateMmapSharedSegmentBackend();
+    }
+#if defined(USE_ASCEND_DIRECT)
+    if (impl == "ascend") {
+        return CreateAscendSharedSegmentBackend();
+    }
+#endif
+    return nullptr;
+}
+
+SharedSegment::SharedSegment(std::string name, uint64_t size,
+                             SharedSegmentOptions options)
+    : name_(std::move(name)), size_(size), options_(options) {}
+
+SharedSegment::~SharedSegment() = default;
+
+uintptr_t SharedSegment::device_addr() const {
+    return backend_ == nullptr ? 0 : backend_->DeviceAddr();
+}
+
+bool SharedSegment::Supported(bool mmap, bool host_register) {
+    if (host_register && !mmap) {
+        return false;
+    }
+    if (!mmap) {
+        return CreateSharedSegmentBackend(SelectSharedSegmentBackend(false)) !=
+               nullptr;
+    }
+    if (host_register) {
+#if defined(USE_ASCEND_DIRECT)
+        return true;
+#else
+        return false;
+#endif
+    }
+    // mmap without HostRegister only needs an anonymous memfd.
+    return true;
+}
+
+Status SharedSegment::Create(const std::string& name, uint64_t size,
+                             const SharedSegmentOptions& options,
+                             std::shared_ptr<SharedSegment>& segment,
+                             std::string& out_blob) {
+    auto status = ValidateOptions(options);
+    if (!status.ok()) {
+        return status;
+    }
+    if (size == 0 || size > kMaxSegmentBytes) {
+        return Status::InvalidArgument("Shared segment size must be in (0, " +
+                                       std::to_string(kMaxSegmentBytes) + "]");
+    }
+
+    auto candidate =
+        std::shared_ptr<SharedSegment>(new SharedSegment(name, size, options));
+    candidate->backend_ =
+        CreateSharedSegmentBackend(SelectSharedSegmentBackend(options.mmap));
+    if (candidate->backend_ == nullptr) {
+        return Status::NotImplemented(
+            options.mmap ? "This build has no mmap shared-segment backend"
+                         : "This build has no VMM backend for shared segments");
+    }
+
+    candidate->fingerprint_ = ComputeSegmentFingerprint(name, size, options);
+    const uint64_t granularity = candidate->backend_->Granularity(options);
+    candidate->alloc_size_ = AlignUp(size, granularity);
+
+    SegmentBlobHeader header{};
+    header.backend_id = candidate->backend_->BackendId();
+    header.rank_id = options.rank_id;
+    header.fingerprint = candidate->fingerprint_;
+    header.alloc_size = candidate->alloc_size_;
+
+    std::vector<uint8_t> handle;
+    if (options.rank_id == options.owner_rank) {
+        status = candidate->backend_->CreateOwner(
+            candidate->alloc_size_, options, candidate->base_addr_, handle);
+    } else {
+        status = candidate->backend_->ReserveLocal(
+            candidate->alloc_size_, options, candidate->base_addr_);
+    }
+    if (!status.ok()) {
+        return status;
+    }
+
+    status = EncodeSegmentBlob(header, handle, out_blob);
+    if (!status.ok()) {
+        return status;
+    }
+    // Python may fold a layout tag after '|'; log the bare name only.
+    const auto bare_name = name.substr(0, name.find('|'));
+    LOG(INFO) << "Shared segment " << bare_name << " create: rank "
+              << options.rank_id << " of " << options.world_size << ", base 0x"
+              << std::hex << candidate->base_addr_ << std::dec << ", "
+              << candidate->alloc_size_ << " bytes";
+    segment = std::move(candidate);
+    return Status::OK();
+}
+
+Status SharedSegment::Complete(const std::vector<std::string>& blobs) {
+    if (ready_) {
+        return Status::InvalidArgument(
+            "SharedSegment::Complete has already been called");
+    }
+    if (backend_ == nullptr) {
+        return Status::InvalidArgument(
+            "SharedSegment::Complete needs a segment returned by Create");
+    }
+    std::vector<uint8_t> owner_handle;
+    auto status =
+        ExtractOwnerHandle(options_, backend_->BackendId(), fingerprint_,
+                           alloc_size_, blobs, owner_handle);
+    if (!status.ok()) {
+        return status;
+    }
+
+    if (options_.rank_id != options_.owner_rank) {
+        status = backend_->ImportAndMap(alloc_size_, options_, owner_handle);
+        if (!status.ok()) {
+            return status;
+        }
+    }
+    ready_ = true;
+    return Status::OK();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/shared_segment/shared_segment_internal.h b/mooncake-transfer-engine/src/shared_segment/shared_segment_internal.h
new file mode 100644
index 0000000000..54645c02c6
--- /dev/null
+++ b/mooncake-transfer-engine/src/shared_segment/shared_segment_internal.h
@@ -0,0 +1,115 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#ifndef SHARED_SEGMENT_INTERNAL_H
+#define SHARED_SEGMENT_INTERNAL_H
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "shared_segment/shared_segment.h"
+
+namespace mooncake {
+
+// Platform VMM operations behind a shared segment. One instance owns the
+// resources of exactly one segment in one process and releases them on
+// destruction.
+class SharedSegmentBackend {
+   public:
+    virtual ~SharedSegmentBackend() = default;
+
+    // Allocation size must be a multiple of this, and the reserved base address
+    // is aligned to it. It depends on the options because the host NUMA node is
+    // derived from device_id.
+    virtual uint64_t Granularity(const SharedSegmentOptions& options) const = 0;
+
+    // Owner path: allocate physical memory, map it at a fresh local address,
+    // and export a handle that peers can import. The handle is opaque bytes and
+    // must fit in kMaxHandleBytes.
+    virtual Status CreateOwner(uint64_t size,
+                               const SharedSegmentOptions& options,
+                               uintptr_t& base_addr,
+                               std::vector<uint8_t>& handle) = 0;
+
+    // Non-owner path, phase one: reserve an address window. Done before the
+    // handle exchange so the segment base is known as early as on the owner.
+    virtual Status ReserveLocal(uint64_t size,
+                                const SharedSegmentOptions& options,
+                                uintptr_t& base_addr) = 0;
+
+    // Non-owner path, phase two: map the owner's physical pages into the window
+    // this instance reserved.
+    virtual Status ImportAndMap(uint64_t size,
+                                const SharedSegmentOptions& options,
+                                const std::vector<uint8_t>& handle) = 0;
+
+    // Identifies the backend in the exchanged blob, so a mismatched peer build
+    // is rejected instead of importing garbage.
+    virtual uint16_t BackendId() const = 0;
+
+    // Accelerator address of the same pages when the backend had to map them
+    // separately for the device. Zero when the base address is already
+    // device-accessible, which is the case for every VMM backend.
+    virtual uintptr_t DeviceAddr() const { return 0; }
+};
+
+// Creates the requested backend implementation. Supported implementation names
+// are "mmap" and "ascend". Returns nullptr when the implementation is
+// unknown, unavailable in this build, or unsupported by the running system.
+std::unique_ptr<SharedSegmentBackend> CreateSharedSegmentBackend(
+    const std::string& impl);
+
+// Largest platform handle carried in a blob: aclrtMemFabricHandle is 128 bytes.
+constexpr size_t kMaxHandleBytes = 128;
+
+// Every rank contributes a blob of the same length, so the exchange is a plain
+// fixed-size all-gather with no serialization framework involved. Only the
+// owner fills in a handle.
+struct SegmentBlobHeader {
+    uint32_t magic;
+    uint16_t version;
+    uint16_t backend_id;
+    uint32_t rank_id;
+    uint32_t handle_bytes;
+    uint64_t fingerprint;
+    uint64_t alloc_size;
+};
+
+// The header is memcpy'd raw into the blob, so its layout is part of the wire
+// format.
+static_assert(sizeof(SegmentBlobHeader) == 32,
+              "SegmentBlobHeader layout is part of the exchanged blob");
+
+constexpr size_t kSegmentBlobBytes =
+    sizeof(SegmentBlobHeader) + kMaxHandleBytes;
+
+Status EncodeSegmentBlob(const SegmentBlobHeader& header,
+                         const std::vector<uint8_t>& handle, std::string& blob);
+
+Status DecodeSegmentBlob(const std::string& blob, SegmentBlobHeader& header,
+                         std::vector<uint8_t>& handle);
+
+uint64_t AlignUp(uint64_t value, uint64_t alignment);
+
+// Digest of everything the ranks must agree on. Ranks compare digests instead
+// of exchanging the full spec, which keeps the blob fixed-length. Callers that
+// care about a richer layout should fold that declaration into `name`.
+uint64_t ComputeSegmentFingerprint(const std::string& name, uint64_t size,
+                                   const SharedSegmentOptions& options);
+
+}  // namespace mooncake
+
+#endif  // SHARED_SEGMENT_INTERNAL_H
diff --git a/mooncake-transfer-engine/src/show_links.cpp b/mooncake-transfer-engine/src/show_links.cpp
index b50b8bfccd..c5c1407257 100644
--- a/mooncake-transfer-engine/src/show_links.cpp
+++ b/mooncake-transfer-engine/src/show_links.cpp
@@ -16,7 +16,8 @@
 
 #include <json/json.h>
 
-#include <algorithm>
+#include "ib_link_speed.h"
+
 #include <sstream>
 
 #include "transfer_engine_impl.h"
@@ -64,64 +65,9 @@ static bool hasTransportDetails(const NicDiagInfo& nic) {
     return nic.gid_index >= 0;
 }
 
+// Truncated to whole Gbps so the diagnostic output keeps its integer shape.
 static int computeSpeedGbps(int active_speed, int active_width) {
-    if (active_width <= 0) return 0;
-
-    int lane_gbps = 0;
-    switch (active_speed) {
-        case 1:
-            lane_gbps = 2;
-            break;
-        case 2:
-            lane_gbps = 5;
-            break;
-        case 4:
-            lane_gbps = 10;
-            break;
-        case 8:
-            lane_gbps = 10;
-            break;
-        case 16:
-            lane_gbps = 14;
-            break;
-        case 32:
-            lane_gbps = 25;
-            break;
-        case 64:
-            lane_gbps = 50;
-            break;
-        case 128:
-            lane_gbps = 100;
-            break;
-        case 256:
-            lane_gbps = 200;
-            break;
-        default:
-            lane_gbps = std::max(0, active_speed);
-            break;
-    }
-    int lanes = 1;
-    switch (active_width) {
-        case 1:
-            lanes = 1;
-            break;
-        case 2:
-            lanes = 4;
-            break;
-        case 4:
-            lanes = 8;
-            break;
-        case 8:
-            lanes = 12;
-            break;
-        case 16:
-            lanes = 2;
-            break;
-        default:
-            lanes = 1;
-            break;
-    }
-    return lane_gbps * lanes;
+    return static_cast<int>(ibLinkSpeedGbps(active_speed, active_width));
 }
 
 std::string buildShowLinksJson(TransferEngineImpl* impl) {
diff --git a/mooncake-transfer-engine/src/transfer_engine.cpp b/mooncake-transfer-engine/src/transfer_engine.cpp
index 1f6ef80007..7ac9313f16 100644
--- a/mooncake-transfer-engine/src/transfer_engine.cpp
+++ b/mooncake-transfer-engine/src/transfer_engine.cpp
@@ -13,9 +13,11 @@
 // limitations under the License.
 
 #include <chrono>
+#include <cassert>
 #include <limits>
 #include <thread>
 #include <unordered_map>
+#include "error.h"
 
 #ifndef USE_TENT
 #include "transfer_engine.h"
@@ -92,6 +94,7 @@ TransferEngine& TransferEngine::operator=(TransferEngine&& other) noexcept {
     freeEngine();
     impl_ = std::move(other.impl_);
     impl_tent_ = std::move(other.impl_tent_);
+    tent_device_filter_ = std::move(other.tent_device_filter_);
     use_tent_ = other.use_tent_;
     const bool shutdown_enabled = static_cast<bool>(other.shutdown_token_);
     detachShutdownToken(other.shutdown_token_);
@@ -112,6 +115,15 @@ int TransferEngine::init(const std::string& metadata_conn_string,
                        rpc_port);
 }
 
+int TransferEngine::init(const std::string& metadata_conn_string,
+                         const std::string& local_server_name,
+                         const std::string& ip_or_host_name, uint64_t rpc_port,
+                         const std::string& protocol) {
+    (void)protocol;
+    return init(metadata_conn_string, local_server_name, ip_or_host_name,
+                rpc_port);
+}
+
 int TransferEngine::freeEngine() {
     detachShutdownToken(shutdown_token_);
     if (impl_) {
@@ -164,6 +176,19 @@ int TransferEngine::unregisterLocalMemory(void* addr, bool update_metadata) {
     return impl_->unregisterLocalMemory(addr, update_metadata);
 }
 
+void* TransferEngine::allocateSharedMemory(size_t length) {
+    return impl_->allocateSharedMemory(length);
+}
+
+void* TransferEngine::allocateSharedMemory(size_t length,
+                                           const SharedMemoryOptions& opt) {
+    return impl_->allocateSharedMemory(length, opt);
+}
+
+int TransferEngine::freeSharedMemory(void* addr) {
+    return impl_->freeSharedMemory(addr);
+}
+
 Status TransferEngine::submitTransfer(
     BatchID batch_id, const std::vector<TransferRequest>& entries) {
     return impl_->submitTransfer(batch_id, entries);
@@ -313,6 +338,11 @@ std::shared_ptr<Topology> TransferEngine::getLocalTopology() {
     return impl_->getLocalTopology();
 }
 
+std::string TransferEngine::getLocalTopologyString() {
+    auto topo = impl_->getLocalTopology();
+    return topo ? topo->toString() : "{}";
+}
+
 void TransferEngine::enableGracefulShutdown() {
     if (!shutdown_token_) {
         shutdown_token_ = registerTransferEngineShutdownToken(this);
@@ -328,10 +358,17 @@ std::string TransferEngine::showLinks(bool json) const {
 
 }  // namespace mooncake
 #else
+#include "error.h"
 #include "transfer_engine.h"
 #include "transfer_engine_impl.h"
 #include "tent/transfer_engine.h"
 #include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/topology.h"
+#include "topology.h"
+#if defined(USE_ASCEND) || defined(USE_ASCEND_DIRECT)
+#include "config.h"
+#endif
 
 #include <mutex>
 #include <utility>
@@ -341,6 +378,40 @@ std::string TransferEngine::showLinks(bool json) const {
 namespace mooncake {
 namespace {
 
+int tentToClassicError(tent::Status::Code code) {
+    using Code = tent::Status::Code;
+    // Integer-returning classic APIs use ERR_*, whose values do not match
+    // TENT's status codes even after negation.
+    switch (code) {
+        case Code::kOk:
+            return 0;
+        case Code::kInvalidArgument:
+        case Code::kInvalidEntry:
+            return ERR_INVALID_ARGUMENT;
+        case Code::kTooManyRequests:
+            return ERR_TOO_MANY_REQUESTS;
+        case Code::kAddressNotRegistered:
+            return ERR_ADDRESS_NOT_REGISTERED;
+        case Code::kDeviceNotFound:
+            return ERR_DEVICE_NOT_FOUND;
+        case Code::kInvalidMetadataType:
+        case Code::kNeedsRefreshCache:
+        case Code::kMetadataError:
+            return ERR_METADATA;
+        case Code::kRpcServiceError:
+        case Code::kRpcConnectionError:
+            return ERR_SOCKET;
+        case Code::kMalformedJson:
+            return ERR_MALFORMED_JSON;
+        case Code::kNotImplemented:
+            return ERR_NOT_IMPLEMENTED;
+        default:
+            // Broad transport/internal errors and future codes have no exact
+            // classic equivalent; keep them negative without guessing a cause.
+            return ERR_CONTEXT;
+    }
+}
+
 class TransferEngineShutdownToken : public ShutdownToken {
    public:
     explicit TransferEngineShutdownToken(TransferEngine* engine)
@@ -395,7 +466,9 @@ TransferEngine::TransferEngine(bool auto_discover,
     if (getenv("MC_USE_TENT") || getenv("MC_USE_TEV1")) {
         use_tent_ = true;
     }
-    if (!use_tent_) {
+    if (use_tent_) {
+        tent_device_filter_ = filter;
+    } else {
         impl_ = std::make_shared<TransferEngineImpl>(auto_discover, filter);
     }
 }
@@ -404,6 +477,7 @@ TransferEngine::TransferEngine(TransferEngine&& other) noexcept
     : impl_(std::move(other.impl_)),
       impl_tent_(std::move(other.impl_tent_)),
       shutdown_token_(nullptr),
+      tent_device_filter_(std::move(other.tent_device_filter_)),
       use_tent_(other.use_tent_) {
     const bool shutdown_enabled = static_cast<bool>(other.shutdown_token_);
     detachShutdownToken(other.shutdown_token_);
@@ -418,6 +492,7 @@ TransferEngine& TransferEngine::operator=(TransferEngine&& other) noexcept {
     freeEngine();
     impl_ = std::move(other.impl_);
     impl_tent_ = std::move(other.impl_tent_);
+    tent_device_filter_ = std::move(other.tent_device_filter_);
     use_tent_ = other.use_tent_;
     const bool shutdown_enabled = static_cast<bool>(other.shutdown_token_);
     detachShutdownToken(other.shutdown_token_);
@@ -452,27 +527,66 @@ static std::pair<std::string, std::string> parseConnectionStringInternal(
     return result;
 }
 
+std::shared_ptr<mooncake::tent::Config> TransferEngine::buildTentConfig(
+    const std::string& metadata_conn_string,
+    const std::string& local_server_name) const {
+    auto config = std::make_shared<mooncake::tent::Config>();
+    if (!local_server_name.empty())
+        config->set("local_segment_name", local_server_name);
+    if (metadata_conn_string == P2PHANDSHAKE) {
+        config->set("metadata_type", "p2p");
+    } else {
+        auto [type, servers] =
+            parseConnectionStringInternal(metadata_conn_string);
+        if (!type.empty()) config->set("metadata_type", type);
+        if (!servers.empty()) config->set("metadata_servers", servers);
+    }
+    if (!tent_device_filter_.empty()) {
+        config->set("topology/rdma_whitelist", tent_device_filter_);
+    }
+    return config;
+}
+
 int TransferEngine::init(const std::string& metadata_conn_string,
                          const std::string& local_server_name,
                          const std::string& ip_or_host_name,
                          uint64_t rpc_port) {
+    return init(metadata_conn_string, local_server_name, ip_or_host_name,
+                rpc_port, "");
+}
+
+int TransferEngine::init(const std::string& metadata_conn_string,
+                         const std::string& local_server_name,
+                         const std::string& ip_or_host_name, uint64_t rpc_port,
+                         const std::string& protocol) {
     if (!use_tent_) {
         return impl_->init(metadata_conn_string, local_server_name,
                            ip_or_host_name, rpc_port);
     } else {
-        auto config = std::make_shared<mooncake::tent::Config>();
-        if (!local_server_name.empty())
-            config->set("local_segment_name", local_server_name);
-        if (metadata_conn_string == P2PHANDSHAKE) {
-            config->set("metadata_type", "p2p");
-        } else {
-            auto [type, servers] =
-                parseConnectionStringInternal(metadata_conn_string);
-            if (!type.empty()) config->set("metadata_type", type);
-            if (!servers.empty()) config->set("metadata_servers", servers);
+        auto config = buildTentConfig(metadata_conn_string, local_server_name);
+        if (protocol == "tcp") {
+            mooncake::tent::ConfigHelper::forceTcp(*config);
+            if (!std::getenv("MC_FORCE_TCP")) {
+                LOG(INFO) << "protocol=tcp, forcing TENT memory transfers to "
+                             "use TCP";
+            }
+        }
+#if defined(USE_ASCEND) || defined(USE_ASCEND_DIRECT)
+        // Store still constructs TENT through this classic init() shim, not
+        // tent::TransferEngine(Config) directly. Copy Dummy-real flags until
+        // Store creates the native engine itself.
+        if (globalConfig().ascend_agent_mode) {
+            config->set("transports/ascend_direct/agent_mode", true);
+        }
+        if (globalConfig().ascend_store_te_init) {
+            config->set("transports/ascend_direct/store_te_init", true);
+            if (globalConfig().ascend_use_fabric_mem) {
+                config->set("transports/ascend_direct/fabric_mem", true);
+            }
         }
+#endif
         impl_tent_ = std::make_shared<mooncake::tent::TransferEngine>(config);
-        return impl_tent_->available() ? 0 : 1;
+        return impl_tent_->available() ? 0 : ERR_CONTEXT;
     }
 }
 
@@ -510,6 +624,12 @@ int TransferEngine::uninstallTransport(const std::string& proto) {
 
 std::string TransferEngine::getLocalIpAndPort() {
     if (use_tent_) {
+        // Store handshake and openSegment must use the advertised segment
+        // name, not a reconstructed host:port that can disagree with it.
+        auto name = impl_tent_->getSegmentName();
+        if (!name.empty()) {
+            return name;
+        }
         return impl_tent_->getRpcServerAddress() + ":" +
                std::to_string(impl_tent_->getRpcServerPort());
     } else
@@ -535,16 +655,27 @@ SegmentHandle TransferEngine::openSegment(const std::string& segment_name) {
 }
 
 Status TransferEngine::CheckSegmentStatus(SegmentID sid) {
-    if (use_tent_)
-        return Status::OK();
-    else
+    if (use_tent_) {
+        // TENT owns its segment cache, so actively probe the peer instead of
+        // reporting OK unconditionally. Returning OK here left classic callers
+        // (e.g. the Python wrapper's handle_map_) holding a dead peer's cached
+        // handle forever, because they only evict the handle on a non-OK
+        // status. A stale/unknown handle or an unreachable peer makes
+        // probePeerAliveByID fail (invalid handle, empty RPC address, or RPC
+        // error); surface that as a non-OK status so the caller closes and
+        // re-opens the segment on the next transfer. Refs #3995
+        // (P0-stale-handle).
+        auto probe_status = impl_tent_->probePeerAliveByID(sid);
+        if (probe_status.ok()) return Status::OK();
+        return Status::Endpoint(std::string(probe_status.message()));
+    } else
         return impl_->CheckSegmentStatus(sid);
 }
 
 int TransferEngine::closeSegment(SegmentHandle handle) {
     if (use_tent_) {
         auto status = impl_tent_->closeSegment(handle);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->closeSegment(handle);
 }
@@ -562,10 +693,12 @@ int TransferEngine::registerLocalMemory(void* addr, size_t length,
                                         bool update_metadata) {
     if (use_tent_) {
         mooncake::tent::MemoryOptions option;
+        option.perm = remote_accessible ? mooncake::tent::kGlobalReadWrite
+                                        : mooncake::tent::kLocalReadWrite;
         if (!location.empty() && location != kWildcardLocation)
             option.location = location;
         auto status = impl_tent_->registerLocalMemory(addr, length, option);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->registerLocalMemory(addr, length, location,
                                           remote_accessible, update_metadata);
@@ -574,11 +707,35 @@ int TransferEngine::registerLocalMemory(void* addr, size_t length,
 int TransferEngine::unregisterLocalMemory(void* addr, bool update_metadata) {
     if (use_tent_) {
         auto status = impl_tent_->unregisterLocalMemory(addr);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->unregisterLocalMemory(addr, update_metadata);
 }
 
+void* TransferEngine::allocateSharedMemory(size_t length) {
+    if (use_tent_) {
+        LOG(WARNING) << "allocateSharedMemory is classic TE only; use TENT "
+                        "allocateLocalMemory with SHM enabled";
+        return nullptr;
+    }
+    return impl_->allocateSharedMemory(length);
+}
+
+void* TransferEngine::allocateSharedMemory(size_t length,
+                                           const SharedMemoryOptions& opt) {
+    if (use_tent_) {
+        LOG(WARNING) << "allocateSharedMemory is classic TE only; use TENT "
+                        "allocateLocalMemory with SHM enabled";
+        return nullptr;
+    }
+    return impl_->allocateSharedMemory(length, opt);
+}
+
+int TransferEngine::freeSharedMemory(void* addr) {
+    if (use_tent_) return ERR_NOT_IMPLEMENTED;
+    return impl_->freeSharedMemory(addr);
+}
+
 int TransferEngine::registerLocalMemoryBatch(
     const std::vector<BufferEntry>& buffer_list, const std::string& location) {
     if (use_tent_) {
@@ -593,7 +750,7 @@ int TransferEngine::registerLocalMemoryBatch(
         }
         auto status =
             impl_tent_->registerLocalMemory(addr_list, size_list, option);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else {
         return impl_->registerLocalMemoryBatch(buffer_list, location);
     }
@@ -603,7 +760,7 @@ int TransferEngine::unregisterLocalMemoryBatch(
     const std::vector<void*>& addr_list) {
     if (use_tent_) {
         auto status = impl_tent_->unregisterLocalMemory(addr_list);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else {
         return impl_->unregisterLocalMemoryBatch(addr_list);
     }
@@ -641,6 +798,7 @@ Status TransferEngine::submitTransfer(
             req.source = item.source;
             req.target_id = item.target_id;
             req.target_offset = item.target_offset;
+            req.priority = item.priority;
             req.transport_hint =
                 mooncake::tent::c_to_transport_hint(item.transport_hint);
             requests.push_back(req);
@@ -667,6 +825,7 @@ Status TransferEngine::submitTransferWithNotify(
             req.source = item.source;
             req.target_id = item.target_id;
             req.target_offset = item.target_offset;
+            req.priority = item.priority;
             req.transport_hint =
                 mooncake::tent::c_to_transport_hint(item.transport_hint);
             requests.push_back(req);
@@ -695,7 +854,7 @@ int TransferEngine::getNotifies(
             desc.notify_msg = entry.msg;
             notifies.push_back(desc);
         }
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->getNotifies(notifies);
 }
@@ -707,7 +866,7 @@ int TransferEngine::sendNotifyByID(SegmentID target_id,
         notifi.name = notify_msg.name;
         notifi.msg = notify_msg.notify_msg;
         auto status = impl_tent_->sendNotification(target_id, notifi);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->sendNotifyByID(target_id, notify_msg);
 }
@@ -720,10 +879,10 @@ int TransferEngine::sendNotifyByName(std::string remote_agent,
         notifi.msg = notify_msg.notify_msg;
         SegmentHandle handle;
         auto status = impl_tent_->openSegment(handle, remote_agent);
-        if (!status.ok()) return (int)status.code();
+        if (!status.ok()) return tentToClassicError(status.code());
         status = impl_tent_->sendNotification(handle, notifi);
         impl_tent_->closeSegment(handle);
-        return (int)status.code();
+        return tentToClassicError(status.code());
     } else
         return impl_->sendNotifyByName(std::move(remote_agent), notify_msg);
 }
@@ -853,7 +1012,13 @@ void TransferEngine::setAutoDiscover(const AutoDiscoverConfig& config) {
 }
 
 void TransferEngine::setWhitelistFilters(std::vector<std::string>&& filters) {
-    if (!use_tent_) impl_->setWhitelistFilters(std::move(filters));
+    if (!use_tent_) {
+        impl_->setWhitelistFilters(std::move(filters));
+    } else if (!impl_tent_) {
+        tent_device_filter_ = std::move(filters);
+    } else {
+        LOG(WARNING) << "Cannot change the TENT RDMA device filter after init";
+    }
 }
 
 int TransferEngine::numContexts() const {
@@ -865,10 +1030,61 @@ int TransferEngine::numContexts() const {
 
 std::shared_ptr<Topology> TransferEngine::getLocalTopology() {
     if (use_tent_) {
-        LOG(WARNING) << "API deprecated in Mooncake TENT";
-        return std::make_shared<Topology>();
-    } else
+        // Classic Topology only supports a 2-tier priority matrix. Prefer
+        // getLocalTopologyString() for the full TENT nics/mems (rank0/1/2)
+        // representation. This method still projects into the classic format
+        // for existing C++ callers.
+        auto classic = std::make_shared<Topology>();
+        if (!impl_tent_ || !impl_tent_->available()) return classic;
+        auto tent_topo = impl_tent_->getLocalTopology();
+        if (!tent_topo) return classic;
+
+        Json::Value root(Json::objectValue);
+        for (size_t mi = 0; mi < tent_topo->getMemCount(); ++mi) {
+            const auto* mem =
+                tent_topo->getMemEntry(static_cast<tent::Topology::MemID>(mi));
+            if (!mem) continue;
+            if (mem->name.empty() || mem->name == tent::kWildcardLocation) {
+                continue;
+            }
+            Json::Value preferred(Json::arrayValue);
+            Json::Value avail(Json::arrayValue);
+            for (auto id : mem->device_list[0]) {
+                preferred.append(tent_topo->getNicName(id));
+            }
+            for (size_t rank = 1; rank < tent::Topology::DevicePriorityRanks;
+                 ++rank) {
+                for (auto id : mem->device_list[rank]) {
+                    avail.append(tent_topo->getNicName(id));
+                }
+            }
+            Json::Value entry(Json::arrayValue);
+            entry.append(preferred);
+            entry.append(avail);
+            root[mem->name] = entry;
+        }
+
+        Json::StreamWriterBuilder builder;
+        builder["indentation"] = "";
+        const std::string json = Json::writeString(builder, root);
+        if (classic->parse(json)) {
+            LOG(WARNING) << "Failed to translate TENT topology to classic "
+                            "priority matrix";
+            classic->clear();
+        }
+        return classic;
+    } else {
         return impl_->getLocalTopology();
+    }
+}
+
+std::string TransferEngine::getLocalTopologyString() {
+    if (use_tent_) {
+        if (!impl_tent_ || !impl_tent_->available()) return "{}";
+        return impl_tent_->getLocalTopologyString();
+    }
+    auto topo = impl_ ? impl_->getLocalTopology() : nullptr;
+    return topo ? topo->toString() : "{}";
 }
 
 void* TransferEngine::getBaseAddr() {
@@ -899,6 +1115,31 @@ std::string TransferEngine::showLinks(bool json) const {
 
 namespace mooncake {
 
+int TransferEngine::getSegmentBuffers(SegmentHandle handle,
+                                      std::vector<SegmentBufferInfo>& buffers) {
+    buffers.clear();
+#ifdef USE_TENT
+    if (use_tent_) {
+        tent::SegmentInfo info;
+        if (!impl_tent_->getSegmentInfo(handle, info).ok()) return ERR_METADATA;
+        if (info.type != tent::SegmentInfo::Memory) return ERR_NOT_IMPLEMENTED;
+        buffers.reserve(info.buffers.size());
+        for (const auto& entry : info.buffers) {
+            buffers.push_back({entry.base, entry.length, entry.location});
+        }
+        return 0;
+    }
+#endif
+    auto desc = impl_->getMetadata()->getSegmentDescByID(handle);
+    if (!desc) return ERR_METADATA;
+    if (desc->protocol == "nvmeof") return ERR_NOT_IMPLEMENTED;
+    buffers.reserve(desc->buffers.size());
+    for (const auto& entry : desc->buffers) {
+        buffers.push_back({entry.addr, entry.length, entry.name});
+    }
+    return 0;
+}
+
 class TransferEngine::ScatterTransferOperation::Impl {
    public:
     struct Backend {
@@ -912,8 +1153,13 @@ class TransferEngine::ScatterTransferOperation::Impl {
          const std::vector<ScatterTransferRange>& ranges)
         : backend_(std::move(backend)) {
         callbacks_.reserve(ranges.size());
-        for (const auto& range : ranges)
+        size_t fragment_count = 0;
+        for (const auto& range : ranges) {
             callbacks_.push_back(range.on_fragment_complete);
+            fragment_count += range.lengths.size();
+        }
+        requests_.reserve(fragment_count);
+        request_fragments_.reserve(fragment_count);
         build(engine, ranges);
     }
 
@@ -963,7 +1209,8 @@ class TransferEngine::ScatterTransferOperation::Impl {
     int closeSegment(SegmentHandle handle) {
 #ifdef USE_TENT
         if (backend_.tent)
-            return static_cast<int>(backend_.tent->closeSegment(handle).code());
+            return tentToClassicError(
+                backend_.tent->closeSegment(handle).code());
 #endif
         return backend_.legacy->closeSegment(handle);
     }
@@ -1018,6 +1265,7 @@ class TransferEngine::ScatterTransferOperation::Impl {
         requests_.clear();
         request_fragments_.clear();
         done_.clear();
+        task_sizes_.clear();
         backend_ = {};
     }
 
@@ -1034,14 +1282,18 @@ class TransferEngine::ScatterTransferOperation::Impl {
         }
     }
 
+    void completeRequest(size_t request_index, const Status& status) {
+        const auto [range_index, fragment_index] =
+            request_fragments_[request_index];
+        done_[request_index] = true;
+        complete(range_index, fragment_index, status);
+    }
+
     void failPending(const Status& status) {
         for (size_t i = 0; i < request_fragments_.size(); ++i) {
-            if (done_[i]) continue;
-            const auto [range_index, fragment_index] = request_fragments_[i];
-            complete(range_index, fragment_index, status);
-            done_[i] = true;
-            --remaining_;
+            if (!done_[i]) completeRequest(i, status);
         }
+        remaining_ = 0;
     }
 
     void requestAbort(const Status& status) {
@@ -1067,6 +1319,7 @@ class TransferEngine::ScatterTransferOperation::Impl {
              ++range_index) {
             const auto& range = ranges[range_index];
             const size_t fragment_count = range.local_offsets.size();
+            SegmentHandle* segment_handle = nullptr;
             if (range.remote_offsets.size() != fragment_count ||
                 range.lengths.size() != fragment_count ||
                 range.local_buffer == nullptr || range.remote_segment.empty()) {
@@ -1103,12 +1356,16 @@ class TransferEngine::ScatterTransferOperation::Impl {
                     continue;
                 }
 
-                auto [segment, inserted] = segment_handles_.emplace(
-                    range.remote_segment,
-                    static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT));
-                if (inserted)
-                    segment->second = engine.openSegment(range.remote_segment);
-                if (segment->second ==
+                if (!segment_handle) {
+                    auto [segment, inserted] = segment_handles_.emplace(
+                        range.remote_segment,
+                        static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT));
+                    if (inserted)
+                        segment->second =
+                            engine.openSegment(range.remote_segment);
+                    segment_handle = &segment->second;
+                }
+                if (*segment_handle ==
                     static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT)) {
                     complete(range_index, fragment_index,
                              Status::InvalidArgument(
@@ -1120,10 +1377,10 @@ class TransferEngine::ScatterTransferOperation::Impl {
                     .opcode = range.opcode,
                     .source =
                         static_cast<char*>(range.local_buffer) + local_offset,
-                    .target_id = segment->second,
+                    .target_id = *segment_handle,
                     .target_offset = range.remote_base_offset + remote_offset,
                     .length = length,
-                    .task_group_id = range_index + 1,
+                    .task_group_id = 1,
                 });
                 request_fragments_.emplace_back(range_index, fragment_index);
             }
@@ -1135,22 +1392,37 @@ class TransferEngine::ScatterTransferOperation::Impl {
         }
 
         done_.assign(requests_.size(), false);
-        remaining_ = requests_.size();
-        batch_id_ = engine.allocateBatchID(requests_.size());
+        Status submit_status = Status::OK();
+        if (useTent()) {
+            task_sizes_.assign(requests_.size(), 1);
+            batch_id_ = engine.allocateBatchID(requests_.size());
+            if (batch_id_ != INVALID_BATCH_ID)
+                submit_status = engine.submitTransfer(batch_id_, requests_);
+        } else {
+            MultiTransport::ScatterSubmission submission;
+            submit_status =
+                backend_.legacy->submitScatter(requests_, submission);
+            batch_id_ = submission.batch_id;
+            task_sizes_ = std::move(submission.task_sizes);
+        }
+        remaining_ = task_sizes_.size();
         if (batch_id_ == INVALID_BATCH_ID) {
-            failPending(Status::InvalidArgument(
-                "failed to allocate scatter transfer batch"));
+            failPending(submit_status.ok()
+                            ? Status::InvalidArgument(
+                                  "failed to allocate scatter transfer batch")
+                            : submit_status);
             finish();
             return;
         }
 
-        auto submit_status = engine.submitTransfer(batch_id_, requests_);
         if (submit_status.ok()) return;
 
 #ifdef USE_TENT
         if (backend_.tent) {
-            // TENT publishes all task slots together. Drain them if a rare
-            // post-publication error escapes submitTransfer().
+            // TENT prepare failures publish no task slots, while committed
+            // submissions publish all slots and report transport failures in
+            // task status. On a live batch, task 0 being out of range thus
+            // identifies the unpublished case.
             mooncake::tent::TransferStatus status;
             auto probe = backend_.tent->getTransferStatus(batch_id_, 0, status);
             if (probe.ok() || !probe.IsInvalidArgument()) {
@@ -1167,27 +1439,55 @@ class TransferEngine::ScatterTransferOperation::Impl {
 #endif
 
         requestAbort(submit_status);
-        auto free_status = freeBatch(batch_id_);
-        if (free_status.ok()) {
-            batch_id_ = INVALID_BATCH_ID;
-            failPending(submit_status);
-            finish();
-        } else if (!free_status.IsBatchBusy()) {
-            remember(free_status);
-        }
+        // Published tasks own the exact fragment results, even when submit
+        // itself reports an error. Poll them to physical completion.
+        if (!task_sizes_.empty()) return;
+        remember(freeBatch(batch_id_));
+        batch_id_ = INVALID_BATCH_ID;
+        failPending(submit_status);
+        finish();
     }
 
     void poll() {
-        for (size_t i = 0; i < requests_.size(); ++i) {
-            if (done_[i]) continue;
+        size_t request_index = 0;
+        for (size_t task_id = 0; task_id < task_sizes_.size(); ++task_id) {
+            const size_t request_start = request_index;
+            request_index += task_sizes_[task_id];
+            if (done_[request_start]) continue;
             TransferStatus status;
-            auto result = getStatus(batch_id_, i, status);
+            auto result = getStatus(batch_id_, task_id, status);
             if (!result.ok()) {
                 requestAbort(result);
                 continue;
             }
 
-            const auto [range_index, fragment_index] = request_fragments_[i];
+            if (!useTent() && status.s == TransferStatusEnum::FAILED &&
+                task_sizes_[task_id] > 1) {
+                std::vector<TransferStatusEnum> request_statuses;
+                auto detail_status = backend_.legacy->getScatterRequestStatuses(
+                    batch_id_, task_id, request_statuses);
+                if (detail_status.ok() &&
+                    request_statuses.size() == task_sizes_[task_id]) {
+                    for (size_t i = request_start; i < request_index; ++i) {
+                        const auto fragment_status =
+                            request_statuses[i - request_start] ==
+                                    TransferStatusEnum::COMPLETED
+                                ? Status::OK()
+                                : Status::Socket(
+                                      "scatter transfer fragment failed");
+                        if (!fragment_status.ok())
+                            requestAbort(fragment_status);
+                        completeRequest(i, fragment_status);
+                    }
+                    --remaining_;
+                    continue;
+                }
+                remember(detail_status.ok()
+                             ? Status::Context(
+                                   "invalid grouped scatter status count")
+                             : detail_status);
+            }
+
             Status fragment_status;
             if (status.s == TransferStatusEnum::COMPLETED) {
                 fragment_status = Status::OK();
@@ -1204,10 +1504,11 @@ class TransferEngine::ScatterTransferOperation::Impl {
                     Status::Socket("scatter transfer fragment failed");
             }
             if (!fragment_status.ok()) requestAbort(fragment_status);
-            complete(range_index, fragment_index, fragment_status);
-            done_[i] = true;
+            for (size_t i = request_start; i < request_index; ++i)
+                completeRequest(i, fragment_status);
             --remaining_;
         }
+        assert(request_index == requests_.size());
 
         if (remaining_ != 0) return;
         auto free_status = freeBatch(batch_id_);
@@ -1223,6 +1524,7 @@ class TransferEngine::ScatterTransferOperation::Impl {
     std::vector<std::function<void(size_t, const Status&)>> callbacks_;
     std::unordered_map<std::string, SegmentHandle> segment_handles_;
     std::vector<uint8_t> done_;
+    std::vector<size_t> task_sizes_;
     BatchID batch_id_ = INVALID_BATCH_ID;
     size_t remaining_ = 0;
     Status aggregate_status_;
diff --git a/mooncake-transfer-engine/src/transfer_engine_impl.cpp b/mooncake-transfer-engine/src/transfer_engine_impl.cpp
index a7930021f5..9250fa3f0f 100644
--- a/mooncake-transfer-engine/src/transfer_engine_impl.cpp
+++ b/mooncake-transfer-engine/src/transfer_engine_impl.cpp
@@ -28,7 +28,10 @@
 #endif
 
 #include "transfer_metadata_plugin.h"
+#include "common.h"
 #include "transport/transport.h"
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
+#include "transport/shm_transport/shm_transport.h"
 #ifdef USE_BAREX
 #include "transport/barex_transport/barex_transport.h"
 #endif
@@ -41,6 +44,34 @@ bool overlapWithRegion(uintptr_t addr, uint64_t length, void* region_addr,
     return overlap(reinterpret_cast<void*>(addr), length, region_addr,
                    region_length);
 }
+
+Transport* tryInstallShmTransport(MultiTransport* multi_transports,
+                                  std::shared_ptr<Topology> topology) {
+    if (!multi_transports) return nullptr;
+    if (Transport* existing = multi_transports->getTransport("shm")) {
+        return existing;
+    }
+    return multi_transports->installTransport("shm", topology);
+}
+
+int maybeInstallShmTransport(MultiTransport* multi_transports,
+                             std::shared_ptr<Topology> topology) {
+#ifdef ENABLE_MULTI_PROTOCOL
+    if (!multi_transports || !envFlagEnabled("MC_FORCE_SHM")) return 0;
+    Transport* shm = tryInstallShmTransport(multi_transports, topology);
+    if (!shm) {
+        LOG(WARNING) << "MC_FORCE_SHM is set but failed to install SHM "
+                        "transport; continuing without it";
+        return 0;
+    }
+    LOG(INFO) << "SHM transport installed for same-host DRAM copies";
+    return 0;
+#else
+    (void)multi_transports;
+    (void)topology;
+    return 0;
+#endif
+}
 }  // namespace
 
 static bool setFilesLimit() {
@@ -223,6 +254,25 @@ int TransferEngineImpl::init(const std::string& metadata_conn_string,
 #endif
     }
 
+    // MC_FORCE_SHM:
+    // - Without ENABLE_MULTI_PROTOCOL: SHM-only (skip RDMA/TCP), like
+    //   MC_FORCE_TCP.
+    // - With ENABLE_MULTI_PROTOCOL: fall through so auto-discover still
+    //   installs RDMA/TCP, then maybeInstallShmTransport appends SHM.
+#ifndef ENABLE_MULTI_PROTOCOL
+    if (envFlagEnabled("MC_FORCE_SHM")) {
+        Transport* shm_transport =
+            tryInstallShmTransport(multi_transports_.get(), local_topology_);
+        if (!shm_transport) {
+            LOG(ERROR)
+                << "MC_FORCE_SHM is set but failed to install SHM transport";
+            return -1;
+        }
+        LOG(INFO) << "MC_FORCE_SHM is set, using SHM transport only";
+        return 0;
+    }
+#endif
+
 #if defined(USE_ASCEND) || defined(USE_ASCEND_DIRECT)
     Transport* ascend_transport =
         multi_transports_->installTransport("ascend", local_topology_);
@@ -326,10 +376,37 @@ int TransferEngineImpl::init(const std::string& metadata_conn_string,
             LOG(INFO) << "Using MACA transport";
         }
 
-#elif defined(USE_MNNVL) || defined(USE_INTRA_NVLINK)
+#elif defined(USE_MNNVL) || defined(USE_INTRA_NVLINK) || defined(USE_MUSA)
 
         const char* force_mnnvl = getenv("MC_FORCE_MNNVL");
         const char* intra_env = getenv("MC_INTRANODE_NVLINK");
+#ifdef USE_MUSA
+        const char* gpu_p2p_protocol = "musa";
+        const char* gpu_p2p_name = "MUSA";
+        const bool force_gpu_p2p = force_mnnvl || getenv("MC_FORCE_MUSA");
+#else
+        const char* gpu_p2p_protocol = "nvlink";
+        const char* gpu_p2p_name = "NVLink";
+        const bool force_gpu_p2p = force_mnnvl;
+#endif
+        // The cross-node GPU P2P transport is only constructible when its own
+        // build flag is set, so a build that enables USE_INTRA_NVLINK alone
+        // must keep the RDMA/TCP fallback instead of requesting a protocol
+        // MultiTransport cannot create.
+#if defined(USE_MNNVL) || defined(USE_MUSA)
+        constexpr bool kGpuP2PCompiled = true;
+#else
+        constexpr bool kGpuP2PCompiled = false;
+#endif
+        const bool no_hca = local_topology_->getHcaList().empty();
+        // MC_FORCE_HCA keeps the same meaning as on the non-NVLink path:
+        // install RDMA even when topology discovery found no HCA.
+        const bool force_hca = getenv("MC_FORCE_HCA") != nullptr;
+        if (force_gpu_p2p && !kGpuP2PCompiled) {
+            LOG(WARNING) << gpu_p2p_name
+                         << " transport was requested but is not compiled in, "
+                            "falling back to RDMA/TCP";
+        }
         // Explicit env var overrides take priority over HCA auto-detection
         if (intra_env) {
             Transport* t =
@@ -340,16 +417,20 @@ int TransferEngineImpl::init(const std::string& metadata_conn_string,
             }
             LOG(INFO) << "Using Intra-Node NVLink transport "
                          "(MC_INTRANODE_NVLINK set)";
-        } else if (force_mnnvl || local_topology_->getHcaList().empty()) {
+        } else if (kGpuP2PCompiled &&
+                   (force_gpu_p2p || (no_hca && !force_hca))) {
+            // MC_FORCE_HCA suppresses automatic no-HCA fallback, but keeps
+            // explicitly requested GPU P2P transport precedence unchanged.
             Transport* t =
-                multi_transports_->installTransport("nvlink", nullptr);
+                multi_transports_->installTransport(gpu_p2p_protocol, nullptr);
             if (!t) {
-                LOG(ERROR) << "Failed to install NVLink transport";
+                LOG(ERROR) << "Failed to install " << gpu_p2p_name
+                           << " transport";
                 return -1;
             }
-            LOG(INFO) << "Using cross-node NVLink transport "
-                      << "(MC_FORCE_MNNVL or no HCA detected)";
-        } else {
+            LOG(INFO) << "Using " << gpu_p2p_name << " transport "
+                      << "(forced or no HCA detected)";
+        } else if (!no_hca || force_hca) {
             Transport* t =
                 multi_transports_->installTransport("rdma", local_topology_);
             if (!t) {
@@ -357,6 +438,19 @@ int TransferEngineImpl::init(const std::string& metadata_conn_string,
                 return -1;
             }
             LOG(INFO) << "Using RDMA transport (RoCE/iWARP)";
+        } else {
+#ifdef USE_TCP
+            Transport* t = multi_transports_->installTransport("tcp", nullptr);
+            if (!t) {
+                LOG(ERROR) << "Failed to install TCP transport";
+                return -1;
+            }
+            LOG(INFO) << "Using TCP transport (no HCA detected)";
+#else
+            LOG(ERROR) << "No HCA detected and neither " << gpu_p2p_name
+                       << " nor TCP transport is compiled in";
+            return -1;
+#endif
         }
 
 #elif !defined(USE_SUNRISE)
@@ -415,6 +509,7 @@ int TransferEngineImpl::init(const std::string& metadata_conn_string,
     }
 #endif
 
+    maybeInstallShmTransport(multi_transports_.get(), local_topology_);
     return 0;
 }
 
@@ -471,6 +566,38 @@ int TransferEngineImpl::uninstallTransport(const std::string& proto) {
     return 0;
 }
 
+void* TransferEngineImpl::allocateSharedMemory(size_t length) {
+    return allocateSharedMemory(length, SharedMemoryOptions{});
+}
+
+void* TransferEngineImpl::allocateSharedMemory(size_t length,
+                                               const SharedMemoryOptions& opt) {
+    auto* shm =
+        dynamic_cast<ShmTransport*>(multi_transports_->getTransport("shm"));
+    if (!shm) {
+        LOG(ERROR) << "allocateSharedMemory requires ShmTransport "
+                      "(set MC_FORCE_SHM=1 or installTransport(\"shm\"))";
+        return nullptr;
+    }
+    return shm->allocateSharedMemory(length, opt);
+}
+
+int TransferEngineImpl::freeSharedMemory(void* addr) {
+    if (!addr) return ERR_INVALID_ARGUMENT;
+    auto* shm =
+        dynamic_cast<ShmTransport*>(multi_transports_->getTransport("shm"));
+    if (!shm) return ERR_INVALID_ARGUMENT;
+    std::string shm_name;
+    if (!shm->getShmName(addr, &shm_name)) return ERR_INVALID_ARGUMENT;
+    int uret = unregisterLocalMemory(addr, true);
+    if (uret && uret != ERR_ADDRESS_NOT_REGISTERED) {
+        LOG(WARNING) << "unregisterLocalMemory failed before freeSharedMemory, "
+                        "ret="
+                     << uret;
+    }
+    return shm->freeSharedMemory(addr);
+}
+
 #if (defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_MACA)) && \
     !defined(USE_CXI)
 device::P2pTransport* TransferEngineImpl::getOrCreateP2pTransport(
@@ -520,16 +647,39 @@ int TransferEngineImpl::sendNotifyByID(
         LOG(ERROR) << "sendNotifyByID: invalid segment ID " << target_id;
         return ERR_METADATA;
     }
-    Transport::NotifyDesc peer_desc;
-    int ret = metadata_->sendNotify(desc->name, notify_msg, peer_desc);
-    return ret;
+    return sendNotifyByName(desc->name, std::move(notify_msg));
 }
 
 int TransferEngineImpl::sendNotifyByName(
     std::string remote_agent, TransferMetadata::NotifyDesc notify_msg) {
+    if (globalConfig().rdma_notify_enabled) {
+        Transport* transport = getTransport("rdma_twosided");
+        if (!transport) transport = getTransport("rdma");
+        auto* rdma_twosided = dynamic_cast<RdmaTwoSidedTransport*>(transport);
+        if (rdma_twosided) {
+            int ret = rdma_twosided->sendRdmaNotify(remote_agent, notify_msg);
+            if (ret == 0) return 0;
+            if (!globalConfig().rdma_notify_oob_fallback) {
+                LOG(ERROR) << "sendNotifyByName: RDMA notify failed for "
+                           << remote_agent << " ret=" << ret
+                           << " (OOB fallback disabled)";
+                return ret;
+            }
+            VLOG(1) << "sendNotifyByName: RDMA notify unavailable for "
+                    << remote_agent << ", falling back to OOB";
+        } else if (auto* rdma = dynamic_cast<RdmaTransport*>(transport)) {
+            int ret = rdma->sendNativeNotify(remote_agent, notify_msg);
+            if (ret == 0) return 0;
+            // Only unsupported peers/oversized payloads may use OOB. A QP
+            // failure must remain visible, and accepted SENDs are never
+            // replayed.
+            if (ret != ERR_NOT_IMPLEMENTED ||
+                !globalConfig().rdma_notify_oob_fallback)
+                return ret;
+        }
+    }
     Transport::NotifyDesc peer_desc;
-    int ret = metadata_->sendNotify(remote_agent, notify_msg, peer_desc);
-    return ret;
+    return metadata_->sendNotify(remote_agent, notify_msg, peer_desc);
 }
 
 int TransferEngineImpl::probePeerAliveByID(SegmentID target_id) {
diff --git a/mooncake-transfer-engine/src/transfer_metadata.cpp b/mooncake-transfer-engine/src/transfer_metadata.cpp
index 48bb44fef7..a086cb383a 100644
--- a/mooncake-transfer-engine/src/transfer_metadata.cpp
+++ b/mooncake-transfer-engine/src/transfer_metadata.cpp
@@ -28,6 +28,99 @@
 #include "transfer_metadata_plugin.h"
 
 namespace mooncake {
+static uint64_t currentWallTimeInMicroseconds() {
+    const int64_t now_ns = getCurrentTimeInNano();
+    if (now_ns <= 0) return 1;
+    return static_cast<uint64_t>(now_ns / 1000);
+}
+
+static uint64_t nextWallTimeMetadataVersion(uint64_t local_version,
+                                            uint64_t published_version) {
+    uint64_t version = currentWallTimeInMicroseconds();
+    if (published_version >= version) version = published_version + 1;
+    if (local_version >= version) version = local_version + 1;
+    if (version == 0) version = 1;
+    return version;
+}
+
+static bool sameRpcMetaDesc(const TransferMetadata::RpcMetaDesc &lhs,
+                            const TransferMetadata::RpcMetaDesc &rhs) {
+    if (lhs.ip_or_host_name != rhs.ip_or_host_name ||
+        lhs.rpc_port != rhs.rpc_port) {
+        return false;
+    }
+#ifdef USE_BAREX
+    if (lhs.barex_port != rhs.barex_port) return false;
+#endif
+    return true;
+}
+
+static bool shouldInstallFetchedRpcMetaDesc(
+    const std::string &server_name,
+    const std::optional<TransferMetadata::RpcMetaDesc> &old_desc,
+    const TransferMetadata::RpcMetaDesc &new_desc) {
+    if (!old_desc) return true;
+
+    const uint64_t old_version = old_desc->metadata_version;
+    const uint64_t new_version = new_desc.metadata_version;
+    if (old_version == 0 || new_version == 0) return true;
+
+    if (new_version < old_version) {
+        LOG(WARNING) << "Rejecting stale RPC metadata, server_name="
+                     << server_name << ", cached_version=" << old_version
+                     << " (" << formatEpochMicroseconds(old_version) << ")"
+                     << ", fetched_version=" << new_version << " ("
+                     << formatEpochMicroseconds(new_version) << ")";
+        return false;
+    }
+
+    if (new_version == old_version && !sameRpcMetaDesc(*old_desc, new_desc)) {
+        LOG(ERROR) << "Rejecting conflicting RPC metadata with unchanged "
+                      "version, server_name="
+                   << server_name << ", metadata_version=" << new_version
+                   << " (" << formatEpochMicroseconds(new_version) << ")"
+                   << ". This may indicate concurrent publishers or a missing "
+                      "metadata_version bump.";
+        return false;
+    }
+
+    return true;
+}
+
+static bool shouldInstallFetchedSegmentDesc(
+    const std::string &segment_name, TransferMetadata::SegmentID segment_id,
+    const std::shared_ptr<TransferMetadata::SegmentDesc> &old_desc,
+    const std::shared_ptr<TransferMetadata::SegmentDesc> &new_desc) {
+    if (!old_desc || !new_desc) return true;
+
+    const uint64_t old_version = old_desc->metadata_version;
+    const uint64_t new_version = new_desc->metadata_version;
+    if (old_version == 0 || new_version == 0) return true;
+
+    if (new_version < old_version) {
+        LOG(WARNING) << "Rejecting stale segment metadata, name="
+                     << segment_name << ", segment_id=" << segment_id
+                     << ", cached_version=" << old_version << " ("
+                     << formatEpochMicroseconds(old_version) << ")"
+                     << ", fetched_version=" << new_version << " ("
+                     << formatEpochMicroseconds(new_version) << ")";
+        return false;
+    }
+
+    if (new_version == old_version && *old_desc != *new_desc) {
+        LOG(ERROR) << "Rejecting conflicting segment metadata with unchanged "
+                      "version, name="
+                   << segment_name << ", segment_id=" << segment_id
+                   << ", metadata_version=" << new_version << " ("
+                   << formatEpochMicroseconds(new_version) << ")"
+                   << ". This may indicate concurrent publishers or a missing "
+                      "metadata_version bump.";
+        return false;
+    }
+
+    return true;
+}
+
 #ifdef ENABLE_MULTI_PROTOCOL
 // Split comma-separated protocol string into vector
 static std::vector<std::string> splitProtocols(const std::string &protocols) {
@@ -50,6 +143,14 @@ static inline std::string extractProtocolFromConnString(
     return "etcd";
 }
 
+// A cached REMOTE segment whose backend fetch keeps failing this many
+// consecutive sync cycles is treated as gone (peer unmounted / master expiry
+// cleanup removed its key) and invalidated from the local cache. The plugin
+// get() collapses "not found" and "transient error" into a single false, so a
+// single blip must not trigger a purge -- only a streak that persists across
+// cycles does.
+static constexpr int kStaleSegmentFailureThreshold = 2;
+
 struct TransferNotifyUtil {
     static Json::Value encode(const TransferMetadata::NotifyDesc &desc) {
         Json::Value root;
@@ -81,6 +182,11 @@ struct TransferHandshakeUtil {
         root["qp_num"] = qpNums;
         if (desc.ready_ack_supported || desc.ready_ack)
             root["ready_ack"] = desc.ready_ack;
+        if (desc.notify_qp_num != 0 || desc.ctrl_channel) {
+            root["notify_qp_num"] = Json::UInt(desc.notify_qp_num);
+            root["notify_rq_depth"] = Json::UInt(desc.notify_rq_depth);
+            root["ctrl_channel"] = desc.ctrl_channel;
+        }
         root["reply_msg"] = desc.reply_msg;
 #ifdef USE_EFA
         root["efa_addr"] = desc.efa_addr;  // EFA endpoint address
@@ -125,6 +231,21 @@ struct TransferHandshakeUtil {
         } else {
             desc.ready_ack = false;
         }
+        desc.notify_qp_num = 0;
+        desc.notify_rq_depth = 0;
+        desc.ctrl_channel = false;
+        if (root.isMember("notify_qp_num") && root["notify_qp_num"].isUInt()) {
+            desc.notify_qp_num = root["notify_qp_num"].asUInt();
+        }
+        if (root.isMember("notify_rq_depth") &&
+            root["notify_rq_depth"].isUInt()) {
+            unsigned int depth = root["notify_rq_depth"].asUInt();
+            if (depth > 0xFFFFu) return ERR_INVALID_ARGUMENT;
+            desc.notify_rq_depth = static_cast<uint16_t>(depth);
+        }
+        if (root.isMember("ctrl_channel") && root["ctrl_channel"].isBool()) {
+            desc.ctrl_channel = root["ctrl_channel"].asBool();
+        }
         desc.reply_msg = root["reply_msg"].asString();
 #ifdef USE_EFA
         desc.efa_addr = root["efa_addr"].asString();  // EFA endpoint address
@@ -185,6 +306,20 @@ TransferMetadata::TransferMetadata(const std::string &conn_string) {
     startMetadataRefreshPollingIfNeeded();
 }
 
+TransferMetadata::TransferMetadata(
+    std::shared_ptr<MetadataStoragePlugin> storage_plugin) {
+    // Test-only seam (see header). Mirrors the conn-string ctor's key-prefix
+    // setup so getFullMetadataKey() yields "mooncake/ram/<name>" keys, but
+    // skips the plugin factory (no etcd/redis/http needed) and the P2P
+    // handshake daemon. The background refresh poller stays disabled when the
+    // caller configures a zero refresh interval.
+    next_segment_id_.store(1);
+    common_key_prefix_ = "mooncake/";
+    rpc_meta_prefix_ = common_key_prefix_ + "rpc_meta/";
+    storage_plugin_ = std::move(storage_plugin);
+    startMetadataRefreshPollingIfNeeded();
+}
+
 TransferMetadata::~TransferMetadata() {
     stopMetadataRefreshPollingThread();
     handshake_plugin_.reset();
@@ -292,12 +427,19 @@ int TransferMetadata::getNotifies(std::vector<NotifyDesc> &notifies) {
     return 0;
 }
 
+void TransferMetadata::pushNotify(const NotifyDesc &notify) {
+    RWSpinlock::WriteGuard guard(notify_lock_);
+    notifys.push_back(notify);
+}
+
 #ifdef ENABLE_MULTI_PROTOCOL
 static int encodeMultiProtocolSegmentDesc(
     const std::vector<std::string> &protocols,
     const TransferMetadata::SegmentDesc &desc, Json::Value &segmentJSON) {
     // Multi-protocol encoding for CXL+TCP or CXL+RDMA combination
     segmentJSON["name"] = desc.name;
+    segmentJSON["metadata_version"] =
+        static_cast<Json::UInt64>(desc.metadata_version);
     if (!desc.rdma_server_name.empty()) {
         segmentJSON["rdma_server_name"] = desc.rdma_server_name;
     }
@@ -339,9 +481,17 @@ static int encodeMultiProtocolSegmentDesc(
             Json::Value lkeyJSON(Json::arrayValue);
             for (auto &entry : buffer.lkey) lkeyJSON.append(entry);
             bufferJSON["lkey"] = lkeyJSON;
+            if (!buffer.shm_name.empty())
+                bufferJSON["shm_name"] = buffer.shm_name;
         } else if (buffer.protocol == "tcp") {
             bufferJSON["addr"] = static_cast<Json::UInt64>(buffer.addr);
-        } else if (buffer.protocol == "hip" || buffer.protocol == "maca") {
+            if (!buffer.shm_name.empty())
+                bufferJSON["shm_name"] = buffer.shm_name;
+        } else if (buffer.protocol == "shm") {
+            bufferJSON["addr"] = static_cast<Json::UInt64>(buffer.addr);
+            bufferJSON["shm_name"] = buffer.shm_name;
+        } else if (buffer.protocol == "hip" || buffer.protocol == "maca" ||
+                   buffer.protocol == "musa") {
             bufferJSON["addr"] = static_cast<Json::UInt64>(buffer.addr);
             bufferJSON["shm_name"] = buffer.shm_name;
         }
@@ -349,6 +499,9 @@ static int encodeMultiProtocolSegmentDesc(
     }
     segmentJSON["buffers"] = buffersJSON;
     segmentJSON["protocol"] = protocolJSON;
+    if (!desc.tcp_data_host.empty()) {
+        segmentJSON["tcp_data_host"] = desc.tcp_data_host;
+    }
     segmentJSON["tcp_data_port"] = desc.tcp_data_port;
     segmentJSON["tcp_proto_version"] = desc.tcp_proto_version;
     segmentJSON["timestamp"] = getCurrentDateTime();
@@ -370,7 +523,8 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
         is_multi_protocol = true;
         for (const auto &proto : protocols) {
             if (proto != "cxl" && proto != "tcp" && proto != "rdma" &&
-                proto != "hip" && proto != "maca") {
+                proto != "hip" && proto != "maca" && proto != "musa" &&
+                proto != "shm") {
                 is_multi_protocol = false;
                 break;
             }
@@ -378,8 +532,8 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
         if (!is_multi_protocol) {
             LOG(ERROR) << "Unsupported multi-protocol combination: "
                        << desc.protocol
-                       << ". Only cxl, tcp, rdma, hip and maca may be "
-                          "combined.";
+                       << ". Only cxl, tcp, rdma, hip, maca, musa and shm may "
+                          "be combined.";
             return ERR_INVALID_ARGUMENT;
         }
     }
@@ -392,6 +546,11 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
 
     segmentJSON["name"] = desc.name;
     segmentJSON["protocol"] = desc.protocol;
+    segmentJSON["metadata_version"] =
+        static_cast<Json::UInt64>(desc.metadata_version);
+    if (!desc.tcp_data_host.empty()) {
+        segmentJSON["tcp_data_host"] = desc.tcp_data_host;
+    }
     segmentJSON["tcp_data_port"] = desc.tcp_data_port;
     segmentJSON["tcp_proto_version"] = desc.tcp_proto_version;
     segmentJSON["timestamp"] = getCurrentDateTime();
@@ -424,6 +583,8 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
             Json::Value lkeyJSON(Json::arrayValue);
             for (auto &entry : buffer.lkey) lkeyJSON.append(entry);
             bufferJSON["lkey"] = lkeyJSON;
+            if (!buffer.shm_name.empty())
+                bufferJSON["shm_name"] = buffer.shm_name;
             buffersJSON.append(bufferJSON);
         }
         segmentJSON["buffers"] = buffersJSON;
@@ -451,16 +612,20 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
         }
         segmentJSON["buffers"] = buffersJSON;
         segmentJSON["priority_matrix"] = desc.topology.toJson();
-    } else if (segmentJSON["protocol"] == "tcp") {
+    } else if (segmentJSON["protocol"] == "tcp" ||
+               segmentJSON["protocol"] == "flagcx") {
         Json::Value buffersJSON(Json::arrayValue);
         for (const auto &buffer : desc.buffers) {
             Json::Value bufferJSON;
             bufferJSON["name"] = buffer.name;
             bufferJSON["addr"] = static_cast<Json::UInt64>(buffer.addr);
             bufferJSON["length"] = static_cast<Json::UInt64>(buffer.length);
+            if (!buffer.shm_name.empty())
+                bufferJSON["shm_name"] = buffer.shm_name;
             buffersJSON.append(bufferJSON);
         }
         segmentJSON["buffers"] = buffersJSON;
+        segmentJSON["rdma_server_name"] = desc.rdma_server_name;
     } else if (segmentJSON["protocol"] == "nccl") {
         Json::Value buffersJSON(Json::arrayValue);
         for (const auto &buffer : desc.buffers) {
@@ -487,6 +652,7 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
             bufferJSON["name"] = buffer.name;
             bufferJSON["addr"] = static_cast<Json::UInt64>(buffer.addr);
             bufferJSON["length"] = static_cast<Json::UInt64>(buffer.length);
+            bufferJSON["device_id"] = buffer.device_id;
             buffersJSON.append(bufferJSON);
         }
         segmentJSON["buffers"] = buffersJSON;
@@ -518,8 +684,10 @@ int TransferMetadata::encodeSegmentDesc(const SegmentDesc &desc,
                segmentJSON["protocol"] == "nvlink_intra" ||
                segmentJSON["protocol"] == "hip" ||
                segmentJSON["protocol"] == "maca" ||
+               segmentJSON["protocol"] == "musa" ||
                segmentJSON["protocol"] == "ubshmem" ||
-               segmentJSON["protocol"] == "sunrise_link") {
+               segmentJSON["protocol"] == "sunrise_link" ||
+               segmentJSON["protocol"] == "shm") {
         Json::Value buffersJSON(Json::arrayValue);
         for (const auto &buffer : desc.buffers) {
             Json::Value bufferJSON;
@@ -557,6 +725,27 @@ int TransferMetadata::updateSegmentDesc(const std::string &segment_name,
         return 0;
     }
 
+    uint64_t published_version = 0;
+    Json::Value existing;
+    if (storage_plugin_->get(getFullMetadataKey(segment_name), existing) &&
+        existing.isMember("metadata_version") &&
+        existing["metadata_version"].isUInt64()) {
+        published_version = existing["metadata_version"].asUInt64();
+    }
+
+    SegmentDesc versioned_desc = desc;
+    versioned_desc.metadata_version = nextWallTimeMetadataVersion(
+        versioned_desc.metadata_version, published_version);
+
+    return publishSegmentDesc(segment_name, versioned_desc);
+}
+
+int TransferMetadata::publishSegmentDesc(const std::string &segment_name,
+                                         const SegmentDesc &desc) {
+    if (p2p_handshake_mode_) {
+        return 0;
+    }
+
     Json::Value segmentJSON;
     int ret = encodeSegmentDesc(desc, segmentJSON);
     if (ret) {
@@ -600,6 +789,14 @@ decodeMultiProtocolSegmentDesc(Json::Value &segmentJSON,
                                const std::string &segment_name) {
     auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
     desc->name = segmentJSON["name"].asString();
+    if (segmentJSON.isMember("metadata_version") &&
+        segmentJSON["metadata_version"].isUInt64()) {
+        desc->metadata_version = segmentJSON["metadata_version"].asUInt64();
+    }
+    if (segmentJSON.isMember("tcp_data_host") &&
+        segmentJSON["tcp_data_host"].isString()) {
+        desc->tcp_data_host = segmentJSON["tcp_data_host"].asString();
+    }
     desc->tcp_data_port = segmentJSON["tcp_data_port"].asInt();
     desc->tcp_proto_version = segmentJSON.isMember("tcp_proto_version")
                                   ? segmentJSON["tcp_proto_version"].asInt()
@@ -688,6 +885,10 @@ decodeMultiProtocolSegmentDesc(Json::Value &segmentJSON,
                     << buffer.lkey.size() << ", " << desc->devices.size();
                 return nullptr;
             }
+            if (bufferJSON.isMember("shm_name") &&
+                bufferJSON["shm_name"].isString()) {
+                buffer.shm_name = bufferJSON["shm_name"].asString();
+            }
             desc->buffers.push_back(buffer);
         } else if (buffer_protocol == "tcp") {
             TransferMetadata::BufferDesc buffer;
@@ -701,8 +902,31 @@ decodeMultiProtocolSegmentDesc(Json::Value &segmentJSON,
                     << " buffer_protocol " << buffer_protocol;
                 return nullptr;
             }
+            if (bufferJSON.isMember("shm_name") &&
+                bufferJSON["shm_name"].isString()) {
+                buffer.shm_name = bufferJSON["shm_name"].asString();
+            }
+            desc->buffers.push_back(buffer);
+        } else if (buffer_protocol == "shm") {
+            TransferMetadata::BufferDesc buffer;
+            buffer.name = bufferJSON["name"].asString();
+            buffer.addr = bufferJSON["addr"].asUInt64();
+            buffer.length = bufferJSON["length"].asUInt64();
+            buffer.protocol = buffer_protocol;
+            if (bufferJSON.isMember("shm_name") &&
+                bufferJSON["shm_name"].isString()) {
+                buffer.shm_name = bufferJSON["shm_name"].asString();
+            }
+            if (buffer.name.empty() || !buffer.addr || !buffer.length ||
+                buffer.shm_name.empty()) {
+                LOG(WARNING)
+                    << "Corrupted segment descriptor, name " << segment_name
+                    << " buffer_protocol " << buffer_protocol;
+                return nullptr;
+            }
             desc->buffers.push_back(buffer);
-        } else if (buffer_protocol == "hip" || buffer_protocol == "maca") {
+        } else if (buffer_protocol == "hip" || buffer_protocol == "maca" ||
+                   buffer_protocol == "musa") {
             TransferMetadata::BufferDesc buffer;
             buffer.name = bufferJSON["name"].asString();
             buffer.addr = bufferJSON["addr"].asUInt64();
@@ -739,17 +963,18 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
             for (const auto &protocolStr : segmentJSON["protocol"]) {
                 std::string proto = protocolStr.asString();
                 if (proto != "cxl" && proto != "tcp" && proto != "rdma" &&
-                    proto != "hip" && proto != "maca") {
+                    proto != "hip" && proto != "maca" && proto != "musa" &&
+                    proto != "shm") {
                     is_multi_protocol = false;
                     break;
                 }
             }
             if (!is_multi_protocol) {
-                LOG(ERROR) << "Unsupported multi-protocol combination in "
-                              "segment: "
-                           << segment_name
-                           << ". Only cxl, tcp, rdma, hip and maca may be "
-                              "combined.";
+                LOG(ERROR)
+                    << "Unsupported multi-protocol combination in segment: "
+                    << segment_name
+                    << ". Only cxl, tcp, rdma, hip, maca, musa and shm may be "
+                       "combined.";
                 return nullptr;
             }
         }
@@ -757,13 +982,23 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
 
     // If multi-protocol scenario, use multi-protocol decoding
     if (is_multi_protocol) {
-        return decodeMultiProtocolSegmentDesc(segmentJSON, segment_name);
+        auto desc = decodeMultiProtocolSegmentDesc(segmentJSON, segment_name);
+        if (desc) desc->rebuildBufferRangeIndex();
+        return desc;
     }
 #endif
 
     auto desc = std::make_shared<SegmentDesc>();
     desc->name = segmentJSON["name"].asString();
     desc->protocol = segmentJSON["protocol"].asString();
+    if (segmentJSON.isMember("metadata_version") &&
+        segmentJSON["metadata_version"].isUInt64()) {
+        desc->metadata_version = segmentJSON["metadata_version"].asUInt64();
+    }
+    if (segmentJSON.isMember("tcp_data_host") &&
+        segmentJSON["tcp_data_host"].isString()) {
+        desc->tcp_data_host = segmentJSON["tcp_data_host"].asString();
+    }
     desc->tcp_data_port = segmentJSON["tcp_data_port"].asInt();
     desc->tcp_proto_version = segmentJSON.isMember("tcp_proto_version")
                                   ? segmentJSON["tcp_proto_version"].asInt()
@@ -827,6 +1062,10 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
                     << desc->devices.size();
                 return nullptr;
             }
+            if (bufferJSON.isMember("shm_name") &&
+                bufferJSON["shm_name"].isString()) {
+                buffer.shm_name = bufferJSON["shm_name"].asString();
+            }
             desc->buffers.push_back(buffer);
         }
 
@@ -872,7 +1111,7 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
             LOG(WARNING) << "Corrupted segment descriptor, name "
                          << segment_name << " protocol " << desc->protocol;
         }
-    } else if (desc->protocol == "tcp") {
+    } else if (desc->protocol == "tcp" || desc->protocol == "flagcx") {
         for (const auto &bufferJSON : segmentJSON["buffers"]) {
             BufferDesc buffer;
             buffer.name = bufferJSON["name"].asString();
@@ -883,8 +1122,13 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
                              << segment_name << " protocol " << desc->protocol;
                 return nullptr;
             }
+            if (bufferJSON.isMember("shm_name") &&
+                bufferJSON["shm_name"].isString()) {
+                buffer.shm_name = bufferJSON["shm_name"].asString();
+            }
             desc->buffers.push_back(buffer);
         }
+        desc->rdma_server_name = segmentJSON["rdma_server_name"].asString();
     } else if (desc->protocol == "nccl") {
         for (const auto &bufferJSON : segmentJSON["buffers"]) {
             BufferDesc buffer;
@@ -904,8 +1148,8 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
         }
     } else if (desc->protocol == "nvlink" || desc->protocol == "nvlink_intra" ||
                desc->protocol == "hip" || desc->protocol == "maca" ||
-               desc->protocol == "ubshmem" ||
-               desc->protocol == "sunrise_link") {
+               desc->protocol == "musa" || desc->protocol == "ubshmem" ||
+               desc->protocol == "sunrise_link" || desc->protocol == "shm") {
         for (const auto &bufferJSON : segmentJSON["buffers"]) {
             BufferDesc buffer;
             buffer.name = bufferJSON["name"].asString();
@@ -959,6 +1203,9 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
             buffer.name = bufferJSON["name"].asString();
             buffer.addr = bufferJSON["addr"].asUInt64();
             buffer.length = bufferJSON["length"].asUInt64();
+            buffer.device_id = bufferJSON.isMember("device_id")
+                                   ? bufferJSON["device_id"].asInt()
+                                   : -1;
             if (buffer.name.empty() || !buffer.addr || !buffer.length) {
                 LOG(WARNING) << "Corrupted segment descriptor, name "
                              << segment_name << " protocol " << desc->protocol;
@@ -1006,6 +1253,7 @@ TransferMetadata::decodeSegmentDesc(Json::Value &segmentJSON,
                    << " protocol " << desc->protocol;
         return nullptr;
     }
+    desc->rebuildBufferRangeIndex();
     return desc;
 }
 
@@ -1029,7 +1277,14 @@ int TransferMetadata::receivePeerMetadata(const Json::Value &peer_json,
 }
 
 std::shared_ptr<TransferMetadata::SegmentDesc> TransferMetadata::getSegmentDesc(
-    const std::string &segment_name) {
+    const std::string &segment_name, GetResult *status) {
+    return getSegmentDescInternal(segment_name, false, status);
+}
+
+std::shared_ptr<TransferMetadata::SegmentDesc>
+TransferMetadata::getSegmentDescInternal(const std::string &segment_name,
+                                         bool force_rpc_update,
+                                         GetResult *status) {
     Json::Value peer_json;
 
     if (p2p_handshake_mode_) {
@@ -1041,22 +1296,27 @@ std::shared_ptr<TransferMetadata::SegmentDesc> TransferMetadata::getSegmentDesc(
             auto it = segment_id_to_desc_map_.find(LOCAL_SEGMENT_ID);
             if (it == segment_id_to_desc_map_.end() || !it->second) {
                 LOG(ERROR) << "Local segment descriptor not found";
+                if (status) *status = GetResult::kUnavailable;
                 return nullptr;
             }
             desc = it->second;
         }
         int ret = encodeSegmentDesc(*desc.get(), local_json);
         if (ret) {
+            if (status) *status = GetResult::kUnavailable;
             return nullptr;
         }
         ret = handshake_plugin_->exchangeMetadata(ip, port, local_json,
                                                   peer_json);
         if (ret) {
+            if (status) *status = GetResult::kUnavailable;
             return nullptr;
         }
     } else {
-        if (!storage_plugin_->get(getFullMetadataKey(segment_name),
-                                  peer_json)) {
+        GetResult result = storage_plugin_->getWithStatus(
+            getFullMetadataKey(segment_name), peer_json);
+        if (result != GetResult::kFound) {
+            if (status) *status = result;
             LOG(WARNING) << "Failed to retrieve segment descriptor, name "
                          << segment_name;
             return nullptr;
@@ -1064,6 +1324,26 @@ std::shared_ptr<TransferMetadata::SegmentDesc> TransferMetadata::getSegmentDesc(
     }
 
     auto result = decodeSegmentDesc(peer_json, segment_name);
+    if (!result) {
+        if (status) *status = GetResult::kUnavailable;
+        return nullptr;
+    }
+    if (status) *status = GetResult::kFound;
+
+    // Compatibility for descriptors published before tcp_data_host was part
+    // of SegmentDesc. Freeze the legacy RPC location into this descriptor
+    // before it enters the segment cache, so startTransfer() still consumes a
+    // single local snapshot. New publishers carry host and port atomically in
+    // the descriptor and do not take this fallback path.
+    if (result && result->tcp_data_host.empty() && result->tcp_data_port > 0) {
+        RpcMetaDesc rpc_meta;
+        if (getRpcMetaEntryInternal(segment_name, rpc_meta, force_rpc_update)) {
+            LOG(ERROR) << "Failed to resolve legacy TCP data host for segment "
+                       << segment_name;
+            return nullptr;
+        }
+        result->tcp_data_host = rpc_meta.ip_or_host_name;
+    }
 
     // In P2P mode with dual-NIC setups (MC_RDMA_BIND_ADDRESS), the peer's
     // segment descriptor may contain an rdma_server_name that differs from
@@ -1090,13 +1370,15 @@ std::shared_ptr<TransferMetadata::SegmentDesc> TransferMetadata::getSegmentDesc(
 }
 
 bool TransferMetadata::SegmentDesc::operator==(const SegmentDesc &other) const {
-    // timestamp is intentionally excluded: metadata encoding may refresh it
-    // even when the operational descriptor is unchanged.
+    // timestamp, metadata_version, and buffer_range_index are excluded:
+    // publication may refresh timestamps, and the index is derived from
+    // `buffers`.
     return name == other.name && protocol == other.protocol &&
            devices == other.devices && topology == other.topology &&
            buffers == other.buffers && nvmeof_buffers == other.nvmeof_buffers &&
            cxl_name == other.cxl_name && cxl_base_addr == other.cxl_base_addr &&
            rank_info == other.rank_info &&
+           tcp_data_host == other.tcp_data_host &&
            tcp_data_port == other.tcp_data_port &&
            rdma_server_name == other.rdma_server_name;
 }
@@ -1121,17 +1403,36 @@ int TransferMetadata::syncSegmentCache(const std::string &segment_name) {
     size_t updated_count = 0;
     size_t unchanged_count = 0;
     size_t skipped_count = 0;
+    std::vector<std::string> updated_names;
+    size_t invalidated_count = 0;
+    size_t unavailable_count = 0;
 
     // Fetch updates without holding lock (may involve network I/O)
     std::vector<std::pair<std::string, std::shared_ptr<SegmentDesc>>> updates;
+    // Cached REMOTE segment names whose backend lookup returned kNotFound
+    // (authoritative key absence -- the master removed the key on peer
+    // unmount/expiry). Resolved into per-segment failure streaks under the
+    // write lock below, so no shared state (segment_failure_counts_) is
+    // touched during network I/O. Transient failures (kUnavailable) do NOT
+    // enter this list -- they must not advance the streak.
+    std::vector<std::string> failed_names;
     for (const auto &name : names_to_sync) {
-        auto segment_desc = getSegmentDesc(name);
+        GetResult status = GetResult::kUnavailable;
+        auto segment_desc = getSegmentDescInternal(name, true, &status);
         if (segment_desc) {
             updates.emplace_back(name, segment_desc);
             ++fetched_count;
-        } else {
+        } else if (status == GetResult::kNotFound) {
             ++failed_count;
+            failed_names.push_back(name);
             LOG(WARNING) << "segment " << name << " is now invalid";
+        } else {
+            // Transient backend failure (kUnavailable): the key may still
+            // exist; do NOT advance the invalidation streak. The cached
+            // entry survives and is retried next sync cycle.
+            ++unavailable_count;
+            LOG(WARNING) << "segment " << name
+                         << " backend unavailable (transient)";
         }
     }
 
@@ -1139,6 +1440,10 @@ int TransferMetadata::syncSegmentCache(const std::string &segment_name) {
         // Apply updates with write lock
         RWSpinlock::WriteGuard guard(segment_lock_);
         for (const auto &[name, desc] : updates) {
+            // A successful fetch ends any prior failure streak for this
+            // segment; the entry stays cached. Done under the write lock
+            // because segment_failure_counts_ is guarded by segment_lock_.
+            segment_failure_counts_[name] = 0;
             auto it = segment_name_to_id_map_.find(name);
             if (it == segment_name_to_id_map_.end()) {
                 ++skipped_count;
@@ -1150,17 +1455,29 @@ int TransferMetadata::syncSegmentCache(const std::string &segment_name) {
             const auto old_desc = current_it == segment_id_to_desc_map_.end()
                                       ? nullptr
                                       : current_it->second;
+            if (!shouldInstallFetchedSegmentDesc(name, segment_id, old_desc,
+                                                 desc)) {
+                ++skipped_count;
+                continue;
+            }
+
             bool changed = true;
             if (old_desc) {
                 changed = *old_desc != *desc;
             }
 
             if (!changed) {
+                if (old_desc &&
+                    desc->metadata_version > old_desc->metadata_version) {
+                    segment_id_to_desc_map_[segment_id] = desc;
+                    updated_names.push_back(name);
+                }
                 ++unchanged_count;
                 continue;
             }
 
             segment_id_to_desc_map_[segment_id] = desc;
+            updated_names.push_back(name);
             ++updated_count;
             LOG(WARNING) << "Segment cache descriptor changed, name=" << name
                          << ", segment_id=" << segment_id;
@@ -1173,7 +1490,52 @@ int TransferMetadata::syncSegmentCache(const std::string &segment_name) {
             LOG(INFO) << "New segment descriptor:";
             desc->dump();
         }
+
+        // Invalidate stale REMOTE segments. Only authoritative key-absence
+        // results (kNotFound -- the master removed the key on peer
+        // unmount/expiry) enter failed_names and advance the streak.
+        // Transient backend failures (kUnavailable) are excluded above, so
+        // a metadata-service outage cannot purge the cache and strand
+        // in-flight transfers whose callers still hold a shared_ptr copy
+        // of the descriptor. A consecutive-failure streak that persists
+        // across sync cycles is the signal that the segment is genuinely
+        // gone; only then do we drop the cached entry, mirroring the erase
+        // pattern in removeSegmentDesc() (segment_id_to_desc_map_ + name map).
+        for (const auto &name : failed_names) {
+            ++segment_failure_counts_[name];
+        }
+        for (auto fit = segment_failure_counts_.begin();
+             fit != segment_failure_counts_.end();) {
+            if (fit->second < kStaleSegmentFailureThreshold) {
+                ++fit;
+                continue;
+            }
+            const auto &name = fit->first;
+            auto name_it = segment_name_to_id_map_.find(name);
+            // Only invalidate cached remote entries; LOCAL_SEGMENT_ID is
+            // skipped by the collect phase and must never be purged here.
+            if (name_it != segment_name_to_id_map_.end() &&
+                name_it->second != LOCAL_SEGMENT_ID) {
+                segment_id_to_desc_map_.erase(name_it->second);
+                segment_name_to_id_map_.erase(name_it);
+                ++invalidated_count;
+                LOG(WARNING)
+                    << "Invalidated stale segment cache entry, name=" << name;
+            }
+            fit = segment_failure_counts_.erase(fit);
+        }
+    }
+
+    // RPC locations are cached independently from segment descriptors under
+    // the same logical segment name. Invalidate them only after a descriptor
+    // update passes version checks.
+    {
+        RWSpinlock::WriteGuard guard(rpc_meta_lock_);
+        for (const auto &name : updated_names) {
+            rpc_meta_map_.erase(name);
+        }
     }
+
     const auto sync_duration_ms =
         std::chrono::duration_cast<std::chrono::milliseconds>(
             std::chrono::steady_clock::now() - sync_start)
@@ -1183,7 +1545,10 @@ int TransferMetadata::syncSegmentCache(const std::string &segment_name) {
               << ", scanned=" << names_to_sync.size()
               << ", fetched=" << fetched_count << ", updated=" << updated_count
               << ", unchanged=" << unchanged_count
-              << ", failed=" << failed_count << ", skipped=" << skipped_count
+              << ", failed=" << failed_count
+              << ", unavailable=" << unavailable_count
+              << ", skipped=" << skipped_count
+              << ", invalidated=" << invalidated_count
               << ", sync_duration_ms=" << sync_duration_ms;
     return 0;
 }
@@ -1218,6 +1583,14 @@ TransferMetadata::getSegmentDescByName(const std::string &segment_name,
     SegmentID segment_id;
     if (iter != segment_name_to_id_map_.end()) {
         segment_id = iter->second;
+        auto old_iter = segment_id_to_desc_map_.find(segment_id);
+        auto old_desc = old_iter == segment_id_to_desc_map_.end()
+                            ? nullptr
+                            : old_iter->second;
+        if (!shouldInstallFetchedSegmentDesc(segment_name, segment_id, old_desc,
+                                             segment_desc)) {
+            return old_desc;
+        }
     } else {
         segment_id = next_segment_id_.fetch_add(1);
     }
@@ -1245,6 +1618,14 @@ TransferMetadata::getSegmentDescByID(SegmentID segment_id, bool force_update) {
 
         // Update cache with write lock
         RWSpinlock::WriteGuard guard(segment_lock_);
+        auto old_iter = segment_id_to_desc_map_.find(segment_id);
+        auto old_desc = old_iter == segment_id_to_desc_map_.end()
+                            ? nullptr
+                            : old_iter->second;
+        if (!shouldInstallFetchedSegmentDesc(segment_name, segment_id, old_desc,
+                                             segment_desc)) {
+            return old_desc;
+        }
         segment_id_to_desc_map_[segment_id] = segment_desc;
         return segment_id_to_desc_map_[segment_id];
     } else {
@@ -1277,7 +1658,8 @@ TransferMetadata::SegmentID TransferMetadata::getSegmentID(
 }
 
 int TransferMetadata::updateLocalSegmentDesc(uint64_t segment_id) {
-    std::shared_ptr<SegmentDesc> desc;
+    uint64_t published_version = 0;
+    std::string segment_name;
     {
         RWSpinlock::ReadGuard guard(segment_lock_);
         auto it = segment_id_to_desc_map_.find(segment_id);
@@ -1285,9 +1667,34 @@ int TransferMetadata::updateLocalSegmentDesc(uint64_t segment_id) {
             LOG(ERROR) << "Segment descriptor " << segment_id << " not found";
             return ERR_METADATA;
         }
-        desc = it->second;
+        segment_name = it->second->name;
+    }
+
+    if (p2p_handshake_mode_) {
+        return 0;
+    }
+
+    Json::Value existing;
+    if (storage_plugin_->get(getFullMetadataKey(segment_name), existing) &&
+        existing.isMember("metadata_version") &&
+        existing["metadata_version"].isUInt64()) {
+        published_version = existing["metadata_version"].asUInt64();
+    }
+
+    std::shared_ptr<SegmentDesc> desc;
+    {
+        RWSpinlock::WriteGuard guard(segment_lock_);
+        auto it = segment_id_to_desc_map_.find(segment_id);
+        if (it == segment_id_to_desc_map_.end() || !it->second) {
+            LOG(ERROR) << "Segment descriptor " << segment_id << " not found";
+            return ERR_METADATA;
+        }
+        desc = std::make_shared<SegmentDesc>(*it->second);
+        desc->metadata_version = nextWallTimeMetadataVersion(
+            it->second->metadata_version, published_version);
+        it->second = desc;
     }
-    return this->updateSegmentDesc(desc->name, *desc);
+    return this->publishSegmentDesc(desc->name, *desc);
 }
 
 int TransferMetadata::addLocalSegment(SegmentID segment_id,
@@ -1318,6 +1725,7 @@ int TransferMetadata::addLocalMemoryBuffer(const BufferDesc &buffer_desc,
         *new_segment_desc = *segment_desc;
         segment_desc = new_segment_desc;
         segment_desc->buffers.push_back(buffer_desc);
+        segment_desc->rebuildBufferRangeIndex();
     }
     if (update_metadata) return updateLocalSegmentDesc();
     return 0;
@@ -1342,6 +1750,7 @@ int TransferMetadata::removeLocalMemoryBuffer(void *addr,
             ) {
                 segment_desc->buffers.erase(iter);
                 addr_exist = true;
+                segment_desc->rebuildBufferRangeIndex();
                 break;
             }
         }
@@ -1355,6 +1764,19 @@ int TransferMetadata::removeLocalMemoryBuffer(void *addr,
 
 int TransferMetadata::addRpcMetaEntry(const std::string &server_name,
                                       RpcMetaDesc &desc) {
+    uint64_t published_version = 0;
+    if (p2p_handshake_mode_) {
+        desc.metadata_version = 0;
+    } else {
+        Json::Value existing;
+        if (storage_plugin_->get(rpc_meta_prefix_ + server_name, existing) &&
+            existing.isMember("metadata_version") &&
+            existing["metadata_version"].isUInt64()) {
+            published_version = existing["metadata_version"].asUInt64();
+        }
+        desc.metadata_version = nextWallTimeMetadataVersion(
+            desc.metadata_version, published_version);
+    }
     local_rpc_meta_ = desc;
 
     if (p2p_handshake_mode_) {
@@ -1382,6 +1804,8 @@ int TransferMetadata::addRpcMetaEntry(const std::string &server_name,
     Json::Value rpcMetaJSON;
     rpcMetaJSON["ip_or_host_name"] = desc.ip_or_host_name;
     rpcMetaJSON["rpc_port"] = static_cast<Json::UInt>(desc.rpc_port);
+    rpcMetaJSON["metadata_version"] =
+        static_cast<Json::UInt64>(desc.metadata_version);
     if (!storage_plugin_->set(rpc_meta_prefix_ + server_name, rpcMetaJSON)) {
         LOG(ERROR) << "Failed to set location of " << server_name;
         return ERR_METADATA;
@@ -1407,18 +1831,32 @@ int TransferMetadata::rePublishRpcMetaEntry(const std::string &server_name) {
     const std::string full_key = rpc_meta_prefix_ + server_name;
 
     Json::Value existing;
+    uint64_t published_version = 0;
     if (storage_plugin_->get(full_key, existing)) {
+        const bool existing_has_version =
+            existing.isMember("metadata_version") &&
+            existing["metadata_version"].isUInt64();
+        if (existing_has_version) {
+            published_version = existing["metadata_version"].asUInt64();
+        }
         if (existing["ip_or_host_name"].asString() ==
                 local_rpc_meta_.ip_or_host_name &&
-            existing["rpc_port"].asUInt() == local_rpc_meta_.rpc_port) {
+            existing["rpc_port"].asUInt() == local_rpc_meta_.rpc_port &&
+            existing_has_version) {
+            local_rpc_meta_.metadata_version =
+                std::max(local_rpc_meta_.metadata_version, published_version);
             return 0;
         }
     }
 
     LOG(INFO) << "Re-publishing RPC meta entry for " << server_name;
+    local_rpc_meta_.metadata_version = nextWallTimeMetadataVersion(
+        local_rpc_meta_.metadata_version, published_version);
     Json::Value rpcMetaJSON;
     rpcMetaJSON["ip_or_host_name"] = local_rpc_meta_.ip_or_host_name;
     rpcMetaJSON["rpc_port"] = static_cast<Json::UInt>(local_rpc_meta_.rpc_port);
+    rpcMetaJSON["metadata_version"] =
+        static_cast<Json::UInt64>(local_rpc_meta_.metadata_version);
     if (!storage_plugin_->set(full_key, rpcMetaJSON)) {
         LOG(ERROR) << "Failed to re-publish RPC meta entry for " << server_name;
         return ERR_METADATA;
@@ -1428,7 +1866,13 @@ int TransferMetadata::rePublishRpcMetaEntry(const std::string &server_name) {
 
 int TransferMetadata::getRpcMetaEntry(const std::string &server_name,
                                       RpcMetaDesc &desc) {
-    {
+    return getRpcMetaEntryInternal(server_name, desc, false);
+}
+
+int TransferMetadata::getRpcMetaEntryInternal(const std::string &server_name,
+                                              RpcMetaDesc &desc,
+                                              bool force_update) {
+    if (!force_update) {
         RWSpinlock::ReadGuard guard(rpc_meta_lock_);
         if (rpc_meta_map_.count(server_name)) {
             desc = rpc_meta_map_[server_name];
@@ -1436,10 +1880,16 @@ int TransferMetadata::getRpcMetaEntry(const std::string &server_name,
         }
     }
     RWSpinlock::WriteGuard guard(rpc_meta_lock_);
+    std::optional<RpcMetaDesc> old_desc;
+    if (auto iter = rpc_meta_map_.find(server_name);
+        iter != rpc_meta_map_.end()) {
+        old_desc = iter->second;
+    }
     if (p2p_handshake_mode_) {
         auto [ip, port] = parseHostNameWithPort(server_name);
         desc.ip_or_host_name = ip;
         desc.rpc_port = port;
+        desc.metadata_version = 0;
     } else {
         Json::Value rpcMetaJSON;
         if (!storage_plugin_->get(rpc_meta_prefix_ + server_name,
@@ -1449,6 +1899,16 @@ int TransferMetadata::getRpcMetaEntry(const std::string &server_name,
         }
         desc.ip_or_host_name = rpcMetaJSON["ip_or_host_name"].asString();
         desc.rpc_port = (uint16_t)rpcMetaJSON["rpc_port"].asUInt();
+        if (rpcMetaJSON.isMember("metadata_version") &&
+            rpcMetaJSON["metadata_version"].isUInt64()) {
+            desc.metadata_version = rpcMetaJSON["metadata_version"].asUInt64();
+        } else {
+            desc.metadata_version = 0;
+        }
+    }
+    if (!shouldInstallFetchedRpcMetaDesc(server_name, old_desc, desc)) {
+        desc = *old_desc;
+        return 0;
     }
     rpc_meta_map_[server_name] = desc;
     return 0;
@@ -1460,7 +1920,11 @@ int TransferMetadata::startHandshakeDaemon(
         [on_receive_handshake](const Json::Value &peer,
                                Json::Value &local) -> int {
             HandShakeDesc local_desc, peer_desc;
-            TransferHandshakeUtil::decode(peer, peer_desc);
+            if (TransferHandshakeUtil::decode(peer, peer_desc)) {
+                local_desc.reply_msg = "Invalid handshake notify_rq_depth";
+                local = TransferHandshakeUtil::encode(local_desc);
+                return 0;
+            }
             if (on_receive_handshake) {
                 int ret = on_receive_handshake(peer_desc, local_desc);
                 if (ret) {
@@ -1507,7 +1971,11 @@ int TransferMetadata::sendHandshake(const std::string &peer_server_name,
     int ret = handshake_plugin_->send(peer_location.ip_or_host_name,
                                       peer_location.rpc_port, local, peer);
     if (ret) return ret;
-    TransferHandshakeUtil::decode(peer, peer_desc);
+    if (TransferHandshakeUtil::decode(peer, peer_desc)) {
+        LOG(ERROR) << "Handshake from " << peer_server_name
+                   << " has invalid notify_rq_depth";
+        return ERR_INVALID_ARGUMENT;
+    }
     if (!peer_desc.reply_msg.empty()) {
         LOG(ERROR) << "Handshake rejected by " << peer_server_name << ": "
                    << peer_desc.reply_msg;
diff --git a/mooncake-transfer-engine/src/transfer_metadata_dump.cpp b/mooncake-transfer-engine/src/transfer_metadata_dump.cpp
index 093cd50284..d8e1946e6f 100644
--- a/mooncake-transfer-engine/src/transfer_metadata_dump.cpp
+++ b/mooncake-transfer-engine/src/transfer_metadata_dump.cpp
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "config.h"
+#include "common.h"
 #include "transfer_metadata.h"
 
 namespace mooncake {
@@ -22,6 +23,12 @@ void TransferMetadata::SegmentDesc::dump() const {
         LOG(INFO) << "  rdma server name: " << rdma_server_name;
     }
     LOG(INFO) << "  protocol: " << protocol;
+    LOG(INFO) << "  metadata version: " << metadata_version << " ("
+              << formatEpochMicroseconds(metadata_version) << ")";
+    if (!tcp_data_host.empty()) {
+        LOG(INFO) << "  tcp data endpoint: " << tcp_data_host << ":"
+                  << tcp_data_port;
+    }
     LOG(INFO) << "  topology: " << topology.toString();
     LOG(INFO) << "  devices: ";
     for (auto& device : devices) {
@@ -81,12 +88,20 @@ void TransferMetadata::dumpMetadataContentUnlocked() {
     }
     LOG(INFO) << "=== Local RPC Route ===";
     LOG(INFO) << "location: " << local_rpc_meta_.ip_or_host_name << ":"
-              << local_rpc_meta_.rpc_port;
+              << local_rpc_meta_.rpc_port
+              << ", metadata version: " << local_rpc_meta_.metadata_version
+              << " ("
+              << formatEpochMicroseconds(local_rpc_meta_.metadata_version)
+              << ")";
     LOG(INFO) << "=== Remote RPC Routes ===";
     for (auto& entry : rpc_meta_map_) {
         LOG(INFO) << "segment name: " << entry.first
                   << ", location: " << entry.second.ip_or_host_name << ":"
-                  << entry.second.rpc_port;
+                  << entry.second.rpc_port
+                  << ", metadata version: " << entry.second.metadata_version
+                  << " ("
+                  << formatEpochMicroseconds(entry.second.metadata_version)
+                  << ")";
     }
 }
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transfer_metadata_plugin.cpp b/mooncake-transfer-engine/src/transfer_metadata_plugin.cpp
index 10e99e7e64..95d4cd05a9 100644
--- a/mooncake-transfer-engine/src/transfer_metadata_plugin.cpp
+++ b/mooncake-transfer-engine/src/transfer_metadata_plugin.cpp
@@ -150,6 +150,13 @@ struct RedisStoragePlugin : public MetadataStoragePlugin {
                        << " from " << metadata_uri_;
             return false;
         }
+        if (resp->type == REDIS_REPLY_ERROR) {
+            LOG(ERROR) << "RedisStoragePlugin: get " << key << " rejected by "
+                       << metadata_uri_ << ": "
+                       << (resp->str ? resp->str : "unknown error");
+            freeReplyObject(resp);
+            return false;
+        }
         if (!resp->str) {
             LOG(ERROR) << "RedisStoragePlugin: unable to get " << key
                        << " from " << metadata_uri_;
@@ -168,6 +175,44 @@ struct RedisStoragePlugin : public MetadataStoragePlugin {
         return true;
     }
 
+    // Distinguishes a nil reply (key absent — kNotFound) from a connection
+    // or command error (kUnavailable) so syncSegmentCache does not purge the
+    // cache during a Redis outage.
+    GetResult getWithStatus(const std::string &key,
+                            Json::Value &value) override {
+        std::lock_guard<std::mutex> lock(access_client_mutex_);
+        if (!client_) return GetResult::kUnavailable;
+
+        redisReply *resp =
+            (redisReply *)redisCommand(client_, "GET %s", key.c_str());
+        if (!resp) {
+            LOG(ERROR) << "RedisStoragePlugin: unable to get " << key
+                       << " from " << metadata_uri_;
+            return GetResult::kUnavailable;
+        }
+        if (resp->type == REDIS_REPLY_ERROR) {
+            LOG(ERROR) << "RedisStoragePlugin: get " << key << " rejected by "
+                       << metadata_uri_ << ": "
+                       << (resp->str ? resp->str : "unknown error");
+            freeReplyObject(resp);
+            return GetResult::kUnavailable;
+        }
+        if (!resp->str) {
+            freeReplyObject(resp);
+            return GetResult::kNotFound;
+        }
+
+        auto json_file = std::string(resp->str);
+        freeReplyObject(resp);
+
+        std::string errs;
+        if (!parseJsonString(json_file, value, &errs)) {
+            LOG(ERROR) << "RedisStoragePlugin: JSON parse error: " << errs;
+            return GetResult::kUnavailable;
+        }
+        return GetResult::kFound;
+    }
+
     virtual bool set(const std::string &key, const Json::Value &value) {
         std::lock_guard<std::mutex> lock(access_client_mutex_);
         if (!client_) return false;
@@ -181,6 +226,17 @@ struct RedisStoragePlugin : public MetadataStoragePlugin {
                        << " from " << metadata_uri_;
             return false;
         }
+        if (resp->type == REDIS_REPLY_ERROR) {
+            // The server received and rejected the write (READONLY after a
+            // failover, OOM at maxmemory, MISCONF, NOAUTH). Reporting success
+            // loses the write silently; the constructor already treats the
+            // same reply type as failure for AUTH/SELECT.
+            LOG(ERROR) << "RedisStoragePlugin: put " << key << " rejected by "
+                       << metadata_uri_ << ": "
+                       << (resp->str ? resp->str : "unknown error");
+            freeReplyObject(resp);
+            return false;
+        }
         freeReplyObject(resp);
         return true;
     }
@@ -196,6 +252,13 @@ struct RedisStoragePlugin : public MetadataStoragePlugin {
                        << " from " << metadata_uri_;
             return false;
         }
+        if (resp->type == REDIS_REPLY_ERROR) {
+            LOG(ERROR) << "RedisStoragePlugin: remove " << key
+                       << " rejected by " << metadata_uri_ << ": "
+                       << (resp->str ? resp->str : "unknown error");
+            freeReplyObject(resp);
+            return false;
+        }
         freeReplyObject(resp);
         return true;
     }
@@ -305,6 +368,54 @@ struct HTTPStoragePlugin : public MetadataStoragePlugin {
         return true;
     }
 
+    // Distinguishes HTTP 404 (key absent — kNotFound) from curl/network
+    // errors and server-side 5xx (kUnavailable) so syncSegmentCache does not
+    // purge the cache during an etcd/master outage.
+    GetResult getWithStatus(const std::string &key,
+                            Json::Value &value) override {
+        CURL *h = tl_easy();
+        curl_easy_reset(h);
+
+        std::string readBody;
+        char errbuf[CURL_ERROR_SIZE] = {0};
+
+        curl_easy_setopt(h, CURLOPT_TIMEOUT_MS, 3000L);
+        curl_easy_setopt(h, CURLOPT_CONNECTTIMEOUT_MS, 1500L);
+
+        const std::string url = encodeUrl(key);
+        curl_easy_setopt(h, CURLOPT_URL, url.c_str());
+        curl_easy_setopt(h, CURLOPT_HTTPGET, 1L);
+        curl_easy_setopt(h, CURLOPT_WRITEFUNCTION, writeCallback);
+        curl_easy_setopt(h, CURLOPT_WRITEDATA, &readBody);
+        curl_easy_setopt(h, CURLOPT_ERRORBUFFER, errbuf);
+
+        CURLcode rc = curl_easy_perform(h);
+        if (rc != CURLE_OK) {
+            LOG(ERROR) << "GET " << url << " curl: " << curl_easy_strerror(rc)
+                       << " err: " << errbuf;
+            return GetResult::kUnavailable;
+        }
+
+        long code = 0;
+        curl_easy_getinfo(h, CURLINFO_RESPONSE_CODE, &code);
+        if (code == 404) return GetResult::kNotFound;
+        if (!is_200(code)) {
+            LOG(ERROR) << "GET " << url << " http=" << code
+                       << " body: " << readBody;
+            return GetResult::kUnavailable;
+        }
+
+        Json::CharReaderBuilder b;
+        std::string errs;
+        std::unique_ptr<Json::CharReader> r(b.newCharReader());
+        if (!r->parse(readBody.data(), readBody.data() + readBody.size(),
+                      &value, &errs)) {
+            LOG(ERROR) << "GET " << url << " json parse error: " << errs;
+            return GetResult::kUnavailable;
+        }
+        return GetResult::kFound;
+    }
+
     bool set(const std::string &key, const Json::Value &value) override {
         CURL *h = tl_easy();
         curl_easy_reset(h);
@@ -419,6 +530,29 @@ struct EtcdStoragePlugin : public MetadataStoragePlugin {
         return true;
     }
 
+    // etcd v3 answers a range request for a missing key with an OK response
+    // carrying no value, so an empty payload is an authoritative absence;
+    // everything else that fails (RPC error, timeout, malformed payload) is
+    // reported as unavailability, never as absence.
+    GetResult getWithStatus(const std::string &key,
+                            Json::Value &value) override {
+        auto resp = client_.get(key);
+        if (!resp.is_ok()) {
+            LOG(ERROR) << "EtcdStoragePlugin: unable to get " << key << " from "
+                       << metadata_uri_ << ": " << resp.error_message();
+            return GetResult::kUnavailable;
+        }
+        auto json_file = resp.value().as_string();
+        if (json_file.empty()) return GetResult::kNotFound;
+
+        std::string errs;
+        if (!parseJsonString(json_file, value, &errs)) {
+            LOG(ERROR) << "EtcdStoragePlugin: JSON parse error: " << errs;
+            return GetResult::kUnavailable;
+        }
+        return GetResult::kFound;
+    }
+
     virtual bool set(const std::string &key, const Json::Value &value) {
         Json::FastWriter writer;
         const std::string json_file = writer.write(value);
@@ -487,6 +621,36 @@ struct EtcdStoragePlugin : public MetadataStoragePlugin {
         return true;
     }
 
+    // EtcdGetWrapper reports a missing key as ret == 0 with no payload, so
+    // that combination is an authoritative absence; a non-zero return (RPC
+    // error, timeout) is unavailability, never absence.
+    GetResult getWithStatus(const std::string &key,
+                            Json::Value &value) override {
+        char *json_data = nullptr;
+        auto ret = EtcdGetWrapper((char *)key.c_str(), &json_data, &err_msg_);
+        if (ret) {
+            LOG(ERROR) << "EtcdStoragePlugin: unable to get " << key << " in "
+                       << metadata_uri_ << ": " << err_msg_;
+            // free the memory for storing error message
+            free(err_msg_);
+            err_msg_ = nullptr;
+            return GetResult::kUnavailable;
+        }
+        if (!json_data) {
+            return GetResult::kNotFound;
+        }
+        auto json_file = std::string(json_data);
+        // free the memory allocated by EtcdGetWrapper
+        free(json_data);
+
+        std::string errs;
+        if (!parseJsonString(json_file, value, &errs)) {
+            LOG(ERROR) << "EtcdStoragePlugin: JSON parse error: " << errs;
+            return GetResult::kUnavailable;
+        }
+        return GetResult::kFound;
+    }
+
     virtual bool set(const std::string &key, const Json::Value &value) {
         Json::FastWriter writer;
         const std::string json_file = writer.write(value);
diff --git a/mooncake-transfer-engine/src/transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/CMakeLists.txt
index 43baa24cc8..3ed009c4d6 100644
--- a/mooncake-transfer-engine/src/transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/CMakeLists.txt
@@ -1,9 +1,12 @@
 file(GLOB XPORT_SOURCES "*.cpp")
 
 add_subdirectory(rdma_transport)
+add_subdirectory(rdma_twosided)
 add_subdirectory(rpc_communicator)
-add_library(transport OBJECT ${XPORT_SOURCES} $<TARGET_OBJECTS:rdma_transport>
-                             $<TARGET_OBJECTS:rpc_communicator>)
+add_library(
+  transport OBJECT
+  ${XPORT_SOURCES} $<TARGET_OBJECTS:rdma_transport>
+  $<TARGET_OBJECTS:rdma_twosided> $<TARGET_OBJECTS:rpc_communicator>)
 target_link_libraries(
   transport PRIVATE JsonCpp::JsonCpp yalantinglibs::yalantinglibs glog::glog
                     pthread)
@@ -38,6 +41,9 @@ if(USE_CXL)
   target_sources(transport PUBLIC $<TARGET_OBJECTS:cxl_transport>)
 endif()
 
+add_subdirectory(shm_transport)
+target_sources(transport PUBLIC $<TARGET_OBJECTS:shm_transport>)
+
 if(USE_ASCEND_DIRECT)
   add_subdirectory(ascend_transport)
 elseif(USE_ASCEND)
@@ -60,12 +66,17 @@ if(USE_MACA)
   target_sources(transport PUBLIC $<TARGET_OBJECTS:maca_transport>)
 endif()
 
+if(USE_MUSA)
+  add_subdirectory(musa_transport)
+  target_sources(transport PUBLIC $<TARGET_OBJECTS:musa_transport>)
+endif()
+
 if(USE_SUNRISE)
   add_subdirectory(sunrise_link)
   target_sources(transport PUBLIC $<TARGET_OBJECTS:sunrise_link_transport>)
 endif()
 
-if(USE_MNNVL AND NOT USE_HIP)
+if(USE_MUSA OR (USE_MNNVL AND NOT USE_HIP))
   add_subdirectory(nvlink_transport)
   target_sources(transport PUBLIC $<TARGET_OBJECTS:nvlink_transport>)
 endif()
@@ -92,12 +103,14 @@ if(USE_CXI)
   target_link_libraries(transport PRIVATE fabric)
 endif()
 
-if(USE_CUDA OR USE_MUSA OR USE_MACA)
+if(USE_CUDA
+   OR USE_MUSA
+   OR USE_MACA)
   add_subdirectory(device)
   target_sources(transport PUBLIC $<TARGET_OBJECTS:device_transport>)
   # device_transport (ibgda_device_transport.cpp / mlx5gda.cpp) calls libmlx5
   # DevX symbols (mlx5dv_devx_*, mlx5dv_init_obj) directly.
-  if((USE_CUDA OR USE_MUSA) AND NOT USE_CXI)
+  if((USE_CUDA OR USE_MUSA OR USE_MACA) AND NOT USE_CXI)
     target_link_libraries(transport PUBLIC mlx5)
   endif()
   if(USE_CUDA AND MOONCAKE_HAVE_MLX5_DMABUF_UMEM)
@@ -105,3 +118,9 @@ if(USE_CUDA OR USE_MUSA OR USE_MACA)
     target_link_libraries(transport PUBLIC ${CMAKE_DL_LIBS})
   endif()
 endif()
+
+if(USE_FLAGCX)
+  add_subdirectory(flagcx_transport)
+  target_sources(transport PUBLIC $<TARGET_OBJECTS:flagcx_transport>)
+  target_link_libraries(transport PRIVATE FlagCX::flagcx)
+endif()
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/ascend_transport/CMakeLists.txt
index 351526e18f..dacf3ebd77 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/CMakeLists.txt
@@ -41,6 +41,8 @@ else()
     add_library(ascend_transport OBJECT ${ASCEND_SOURCES})
 endif()
 
+target_link_libraries(ascend_transport PRIVATE glog::glog)
+
 if (USE_ASCEND)
     target_link_libraries(ascend_transport PRIVATE ascend_transport_mem)
 endif()
@@ -56,7 +58,7 @@ set_target_properties(ascend_transport
 
 target_compile_options(ascend_transport PRIVATE
                        -O2
-                       -Xlinker -export-dynamic     
+                       -Xlinker -export-dynamic
                     )
 
 target_link_options(ascend_transport PRIVATE
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_allocator.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_allocator.cpp
index 76adc636e9..c5cbbfdd1a 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_allocator.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_allocator.cpp
@@ -1,4 +1,5 @@
 #include <algorithm>
+#include <atomic>
 #include <mutex>
 #include <unordered_map>
 #include <vector>
@@ -8,14 +9,49 @@
 #include "config.h"
 #include "acl/acl.h"
 #include "transport/ascend_transport/ascend_direct_transport/adxl_compat.h"
+#include "transport/ascend_transport/ascend_direct_transport/context_manager.h"
 
 namespace mooncake {
 namespace {
 constexpr size_t kFabricMemPageSize = 1024ULL * 1024 * 1024;  // 1G
+constexpr size_t kMemAccessDescCount = 1;
 constexpr int kBestEffortStartPercent = 100;
 constexpr int kBestEffortMinPercent = 50;
 constexpr int kBestEffortPercentStep = 10;
 
+std::atomic<uint32_t> g_agent_alloc_next{0};
+
+bool BindNextAgentDevice() {
+    if (!globalConfig().ascend_agent_mode) {
+        return true;
+    }
+    auto &mgr = ContextManager::getInstance();
+    if (!mgr.isInitialized()) {
+        return true;
+    }
+    const uint32_t n = mgr.getDeviceCount();
+    if (n == 0) {
+        return true;
+    }
+    const uint32_t idx = g_agent_alloc_next.load(std::memory_order_relaxed) % n;
+    if (!mgr.setCurrentContext(static_cast<int32_t>(idx))) {
+        LOG(ERROR) << "Failed to set agent-mode alloc context for device "
+                   << idx;
+        return false;
+    }
+    return true;
+}
+
+void CommitAgentDeviceSlot() {
+    if (!globalConfig().ascend_agent_mode) {
+        return;
+    }
+    if (!ContextManager::getInstance().isInitialized()) {
+        return;
+    }
+    g_agent_alloc_next.fetch_add(1, std::memory_order_relaxed);
+}
+
 size_t align_down_1g(size_t n) {
     return (n / kFabricMemPageSize) * kFabricMemPageSize;
 }
@@ -39,6 +75,7 @@ void remove_store_memory_range(void *ptr) {
 struct AllocRecord {
     aclrtDrvMemHandle handle;
     bool is_direct_alloc;
+    size_t size;
 };
 std::mutex g_vmm_alloc_mutex;
 std::unordered_map<void *, AllocRecord> g_vmm_alloc_records;
@@ -100,6 +137,44 @@ int allocate_physical_memory(size_t total_size, aclrtDrvMemHandle &handle,
     return 0;
 }
 
+// Host physical pages mapped behind a VA are only bound to the host by
+// aclrtMapMem; the NPU needs an explicit grant before SDMA/HCCS can touch them.
+// adxl::MallocMem grants it internally for its own allocations, so the direct
+// ACL VMM path has to do the same. location.id is a driver logical id while
+// aclrtGetDevice returns a user id (ASCEND_RT_VISIBLE_DEVICES), so convert.
+int grant_current_device_access(void *va, size_t total_size, bool quiet) {
+    int32_t user_dev_id = -1;
+    auto ret = aclrtGetDevice(&user_dev_id);
+    if (ret != ACL_ERROR_NONE) {
+        if (!quiet) {
+            LOG(ERROR) << "Failed to get device for MemSetAccess: " << ret;
+        }
+        return -1;
+    }
+    int32_t driver_dev_id = -1;
+    ret = aclrtGetLogicDevIdByUserDevId(user_dev_id, &driver_dev_id);
+    if (ret != ACL_ERROR_NONE) {
+        if (!quiet) {
+            LOG(ERROR) << "Failed to get logical device id for MemSetAccess: "
+                       << ret;
+        }
+        return -1;
+    }
+
+    aclrtMemAccessDesc desc = {};
+    desc.flags = ACL_RT_MEM_ACCESS_FLAGS_READWRITE;
+    desc.location.type = ACL_MEM_LOCATION_TYPE_DEVICE;
+    desc.location.id = static_cast<uint32_t>(driver_dev_id);
+    ret = aclrtMemSetAccess(va, total_size, &desc, kMemAccessDescCount);
+    if (ret != ACL_ERROR_NONE) {
+        if (!quiet) {
+            LOG(ERROR) << "Failed to set memory access: " << ret;
+        }
+        return -1;
+    }
+    return 0;
+}
+
 // Direct ACL VMM allocation (always bypasses adxl MallocMem).
 // Used by shm_helper when ascend_agent_mode && ascend_use_fabric_mem.
 void *allocate_vmm_memory_direct_impl(size_t total_size, bool quiet = false) {
@@ -125,8 +200,14 @@ void *allocate_vmm_memory_direct_impl(size_t total_size, bool quiet = false) {
         (void)aclrtFreePhysical(handle);
         return nullptr;
     }
+    if (grant_current_device_access(va, total_size, quiet) != 0) {
+        (void)aclrtUnmapMem(va);
+        (void)aclrtReleaseMemAddress(va);
+        (void)aclrtFreePhysical(handle);
+        return nullptr;
+    }
     std::lock_guard<std::mutex> lock(g_vmm_alloc_mutex);
-    g_vmm_alloc_records.emplace(va, AllocRecord{handle, true});
+    g_vmm_alloc_records.emplace(va, AllocRecord{handle, true, total_size});
     return va;
 }
 
@@ -149,7 +230,8 @@ void *allocate_fabric_exact(size_t total_size, bool quiet = false) {
         LOG(INFO) << "Call adxl MallocMem suc, va:" << va
                   << ", size:" << total_size;
         std::lock_guard<std::mutex> lock(g_vmm_alloc_mutex);
-        g_vmm_alloc_records.emplace(va, AllocRecord{nullptr, false});
+        g_vmm_alloc_records.emplace(va,
+                                    AllocRecord{nullptr, false, total_size});
         return va;
     }
     va = allocate_vmm_memory_direct_impl(total_size, quiet);
@@ -160,32 +242,8 @@ void *allocate_fabric_exact(size_t total_size, bool quiet = false) {
     return va;
 }
 #endif
-}  // namespace
 
-void *ascend_allocate_vmm_memory_direct(size_t total_size) {
-#ifdef ASCEND_SUPPORT_FABRIC_MEM
-    return allocate_vmm_memory_direct_impl(total_size);
-#else
-    (void)total_size;
-    return nullptr;
-#endif
-}
-
-aclrtDrvMemHandle ascend_get_physical_handle_from_va(void *va) {
-#ifdef ASCEND_SUPPORT_FABRIC_MEM
-    std::lock_guard<std::mutex> lock(g_vmm_alloc_mutex);
-    auto it = g_vmm_alloc_records.find(va);
-    if (it == g_vmm_alloc_records.end() || !it->second.is_direct_alloc) {
-        return nullptr;
-    }
-    return it->second.handle;
-#else
-    (void)va;
-    return nullptr;
-#endif
-}
-
-void *ascend_allocate_memory(size_t total_size, const std::string &protocol) {
+void *AllocateStoreMemoryImpl(size_t total_size, const std::string &protocol) {
     if (globalConfig().ascend_use_fabric_mem) {
 #ifdef ASCEND_SUPPORT_FABRIC_MEM
         return allocate_fabric_exact(total_size);
@@ -216,25 +274,25 @@ void *ascend_allocate_memory(size_t total_size, const std::string &protocol) {
     return buffer;
 }
 
-void *ascend_allocate_memory_best_effort(size_t target_size,
-                                         const std::string &protocol,
-                                         size_t *actual_size) {
-    if (actual_size == nullptr) {
-        LOG(ERROR) << "ascend_allocate_memory_best_effort: actual_size is null";
+void *AllocateExactOnBoundDevice(size_t total_size, const std::string &protocol,
+                                 size_t *actual_size,
+                                 AscendHostAllocFn host_alloc,
+                                 size_t host_alignment,
+                                 bool defer_hugetlb_population) {
+    void *ptr =
+        host_alloc != nullptr
+            ? host_alloc(total_size, host_alignment, defer_hugetlb_population)
+            : AllocateStoreMemoryImpl(total_size, protocol);
+    if (ptr == nullptr) {
         return nullptr;
     }
-    *actual_size = 0;
-
-    if (!globalConfig().ascend_use_fabric_mem) {
-        void *ptr = ascend_allocate_memory(target_size, protocol);
-        if (ptr) {
-            *actual_size = target_size;
-        }
-        return ptr;
-    }
+    *actual_size = total_size;
+    CommitAgentDeviceSlot();
+    return ptr;
+}
 
 #ifdef ASCEND_SUPPORT_FABRIC_MEM
-    (void)protocol;
+void *AllocateFabricBestEffort(size_t target_size, size_t *actual_size) {
     // Try 100%, 90%, ... down to 50% of configured size (1G-aligned).
     // Skip candidates that fall below the unaligned 50% floor after round-down
     // (e.g. 2.1 GiB target → 50% is 1.05 GiB → 1 GiB must not be accepted).
@@ -255,6 +313,7 @@ void *ascend_allocate_memory_best_effort(size_t target_size,
         void *ptr = allocate_fabric_exact(sz, /*quiet=*/true);
         if (ptr != nullptr) {
             *actual_size = sz;
+            CommitAgentDeviceSlot();
             if (sz < target_size) {
                 LOG(WARNING) << "Fabric mem best-effort: target=" << target_size
                              << ", actual=" << sz << " (" << pct << "%)";
@@ -262,12 +321,73 @@ void *ascend_allocate_memory_best_effort(size_t target_size,
             return ptr;
         }
     }
-
     LOG(ERROR) << "Fabric mem best-effort failed: cannot allocate at least "
                << kBestEffortMinPercent << "% of target=" << target_size;
     return nullptr;
+}
+#endif
+}  // namespace
+
+void *ascend_allocate_vmm_memory_direct(size_t total_size) {
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+    return allocate_vmm_memory_direct_impl(total_size);
 #else
+    (void)total_size;
+    return nullptr;
+#endif
+}
+
+aclrtDrvMemHandle ascend_get_physical_handle_from_va(void *va) {
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+    std::lock_guard<std::mutex> lock(g_vmm_alloc_mutex);
+    auto it = g_vmm_alloc_records.find(va);
+    if (it == g_vmm_alloc_records.end() || !it->second.is_direct_alloc) {
+        return nullptr;
+    }
+    return it->second.handle;
+#else
+    (void)va;
+    return nullptr;
+#endif
+}
+
+void *ascend_allocate_memory(size_t total_size, const std::string &protocol) {
+    if (!BindNextAgentDevice()) {
+        return nullptr;
+    }
+    void *ptr = AllocateStoreMemoryImpl(total_size, protocol);
+    if (ptr) {
+        CommitAgentDeviceSlot();
+    }
+    return ptr;
+}
+
+void *ascend_allocate_memory_best_effort(size_t target_size,
+                                         const std::string &protocol,
+                                         size_t *actual_size,
+                                         AscendHostAllocFn host_alloc,
+                                         size_t host_alignment,
+                                         bool defer_hugetlb_population) {
+    if (actual_size == nullptr) {
+        LOG(ERROR) << "ascend_allocate_memory_best_effort: actual_size is null";
+        return nullptr;
+    }
+    *actual_size = 0;
+    if (!BindNextAgentDevice()) {
+        return nullptr;
+    }
+    if (!globalConfig().ascend_use_fabric_mem) {
+        return AllocateExactOnBoundDevice(target_size, protocol, actual_size,
+                                          host_alloc, host_alignment,
+                                          defer_hugetlb_population);
+    }
     (void)protocol;
+    (void)host_alloc;
+    (void)host_alignment;
+    (void)defer_hugetlb_population;
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+    return AllocateFabricBestEffort(target_size, actual_size);
+#else
     LOG(ERROR) << "Fabric mem mode is not supported, please upgrade Ascend "
                   "HDK and CANN.";
     return nullptr;
@@ -289,6 +409,31 @@ bool ascend_is_store_memory(void *addr, size_t length) {
     return false;
 }
 
+bool ascend_is_direct_vmm_memory(void *addr, size_t length) {
+    if (!addr || length == 0) return false;
+    const auto addr_start = reinterpret_cast<uintptr_t>(addr);
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+    std::lock_guard<std::mutex> lock(g_vmm_alloc_mutex);
+    for (const auto &[base, record] : g_vmm_alloc_records) {
+        if (!record.is_direct_alloc) {
+            continue;
+        }
+        // Only the start address identifies the allocation. A caller may hand
+        // over a longer range than was allocated - a store segment is mounted
+        // at its requested size while best-effort fabric allocation can return
+        // less - and demanding full containment would silently keep that
+        // buffer as MEM_HOST.
+        const auto base_start = reinterpret_cast<uintptr_t>(base);
+        if (addr_start >= base_start && addr_start < base_start + record.size) {
+            return true;
+        }
+    }
+#else
+    (void)addr_start;
+#endif
+    return false;
+}
+
 void ascend_free_memory(const std::string &protocol, void *ptr) {
     // Route by the per-allocation record, not the process-global fabric flag:
     // ascend_use_fabric_mem can differ between alloc time and free time (it is
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/ascend_direct_transport.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/ascend_direct_transport.cpp
index 365505cbb0..6672a73a73 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/ascend_direct_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/ascend_direct_transport.cpp
@@ -47,6 +47,41 @@ int32_t ResolveCurrentEngineId(bool agent_mode) {
     return current_device_id;
 }
 
+int ResolveAscendMemType(const std::string &location, void *addr,
+                         adxl::MemType &mem_type) {
+    if (location.starts_with("cpu")) {
+        mem_type = adxl::MEM_HOST;
+        return 0;
+    }
+    if (location.starts_with("npu")) {
+        mem_type = adxl::MEM_DEVICE;
+        return 0;
+    }
+    if (location != kWildcardLocation) {
+        LOG(ERROR) << "location:" << location << " is not supported.";
+        return ERR_INVALID_ARGUMENT;
+    }
+    aclrtPtrAttributes attributes;
+    CHECK_ACL(aclrtPointerGetAttributes(addr, &attributes));
+    if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
+        mem_type = adxl::MEM_HOST;
+    } else if (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
+        mem_type = adxl::MEM_DEVICE;
+    } else {
+        LOG(INFO) << "mem addr:" << addr
+                  << " can not be recognized, try set to host mem.";
+        mem_type = adxl::MEM_HOST;
+    }
+    return 0;
+}
+
+int StampBufferDeviceId(TransferMetadata::BufferDesc &buffer_desc) {
+    int32_t device_id = -1;
+    CHECK_ACL(aclrtGetDevice(&device_id));
+    buffer_desc.device_id = device_id;
+    return 0;
+}
+
 void InitializeSlice(const Transport::TransferRequest &request,
                      int32_t current_engine_id, Transport::TransferTask *task,
                      Transport::Slice *slice) {
@@ -295,9 +330,13 @@ Status AscendDirectTransport::getTransferStatus(BatchID batch_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
@@ -329,27 +368,25 @@ int AscendDirectTransport::registerLocalMemory(void *addr, size_t length,
     buffer_desc.name = location;
     buffer_desc.addr = (uint64_t)addr;
     buffer_desc.length = (uint64_t)length;
+    int stamp_ret = StampBufferDeviceId(buffer_desc);
+    if (stamp_ret != 0) {
+        return stamp_ret;
+    }
 
     adxl::MemType mem_type;
-    if (location.starts_with("cpu")) {
-        mem_type = adxl::MEM_HOST;
-    } else if (location.starts_with("npu")) {
+    int type_ret = ResolveAscendMemType(location, addr, mem_type);
+    if (type_ret != 0) {
+        return type_ret;
+    }
+    if (use_fabric_mem_ && ascend_is_direct_vmm_memory(addr, length)) {
+        // Direct ACL VMM allocations bypass adxl::MallocMem and are not known
+        // to ADXL's allocation bookkeeping, so they must be registered as
+        // device memory. adxl::MallocMem allocations keep MEM_HOST: ADXL
+        // exports them through its own host-memory path. The gate is this TE's
+        // own fabric flag, not the process-wide allocation table: a co-located
+        // non-fabric TE has no fabric-enabled ADXL engine, so it must keep
+        // treating that memory as host.
         mem_type = adxl::MEM_DEVICE;
-    } else if (location == kWildcardLocation) {
-        aclrtPtrAttributes attributes;
-        CHECK_ACL(aclrtPointerGetAttributes(addr, &attributes));
-        if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
-            mem_type = adxl::MEM_HOST;
-        } else if (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
-            mem_type = adxl::MEM_DEVICE;
-        } else {
-            LOG(INFO) << "mem addr:" << addr
-                      << " can not be recognized, try set to host mem.";
-            mem_type = adxl::MEM_HOST;
-        }
-    } else {
-        LOG(ERROR) << "location:" << location << " is not supported.";
-        return ERR_INVALID_ARGUMENT;
     }
 
     int ret = metadata_->addLocalMemoryBuffer(buffer_desc, update_metadata);
@@ -359,8 +396,7 @@ int AscendDirectTransport::registerLocalMemory(void *addr, size_t length,
     }
 
     const int register_ret = transfer_executor_->registerMem(
-        addr, length, mem_type, transfer_executor_->getUseBufferPool(),
-        roce_mode_, agent_mode_);
+        addr, length, mem_type, transfer_executor_->getUseBufferPool());
     if (register_ret == 0) {
         return 0;
     }
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/local_copy_engine.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/local_copy_engine.cpp
index e752f2e9e0..67a0cabdde 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/local_copy_engine.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/local_copy_engine.cpp
@@ -33,30 +33,96 @@ constexpr uint32_t kStreamFlags = ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC;
 }  // namespace
 
 LocalCopyEngine::LocalCopyEngine()
-    : stream_(nullptr), transfer_timeout_(10000), initialized_(false) {}
+    : transfer_timeout_(10000), initialized_(false) {}
 
 LocalCopyEngine::~LocalCopyEngine() { Finalize(); }
 
 int LocalCopyEngine::Initialize(int32_t transfer_timeout) {
     transfer_timeout_ = transfer_timeout;
-    auto ret = aclrtCreateStreamWithConfig(&stream_, 0, kStreamFlags);
-    if (ret != ACL_ERROR_NONE) {
-        LOG(ERROR) << "aclrtCreateStreamWithConfig failed, ret:" << ret
-                   << ", errmsg:" << aclGetRecentErrMsg();
-        return -1;
-    }
+    // Do not create a stream here: initEngines() may still be under a
+    // different device context than the worker threads that later call Copy.
+    // Streams are created lazily in GetOrCreateStreamForCurrentDevice().
     initialized_ = true;
     return 0;
 }
 
 void LocalCopyEngine::Finalize() {
-    if (initialized_ && stream_ != nullptr) {
-        (void)aclrtDestroyStream(stream_);
-        stream_ = nullptr;
+    std::lock_guard<std::mutex> lock(streams_mu_);
+    aclrtContext saved_ctx = nullptr;
+    if (aclrtGetCurrentContext(&saved_ctx) != ACL_ERROR_NONE) {
+        saved_ctx = nullptr;
+    }
+    // Capture only saved_ctx: MAKE_GUARD is a 2-arg macro, so a
+    // multi-capture lambda would be split on the comma in [].
+    MAKE_GUARD(ctx_restore, [saved_ctx]() {
+        if (saved_ctx != nullptr) {
+            (void)aclrtSetCurrentContext(saved_ctx);
+        }
+    });
+
+    for (auto &kv : streams_) {
+        auto &info = kv.second;
+        if (info.stream == nullptr) {
+            continue;
+        }
+        aclError ret = ACL_ERROR_NONE;
+        if (info.context != nullptr) {
+            ret = aclrtSetCurrentContext(info.context);
+        } else {
+            ret = aclrtSetDevice(kv.first);
+        }
+        if (ret != ACL_ERROR_NONE) {
+            LOG(ERROR)
+                << "Failed to switch to device " << kv.first
+                << " context before destroying LocalCopyEngine stream, ret:"
+                << ret << ", errmsg:" << aclGetRecentErrMsg();
+        }
+        (void)aclrtDestroyStream(info.stream);
+        info.stream = nullptr;
+        info.context = nullptr;
     }
+    streams_.clear();
     initialized_ = false;
 }
 
+aclrtStream LocalCopyEngine::GetOrCreateStreamForCurrentDevice() {
+    int32_t device_id = 0;
+    auto ret = aclrtGetDevice(&device_id);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtGetDevice failed, ret:" << ret
+                   << ", errmsg:" << aclGetRecentErrMsg();
+        return nullptr;
+    }
+
+    std::lock_guard<std::mutex> lock(streams_mu_);
+    auto it = streams_.find(device_id);
+    if (it != streams_.end() && it->second.stream != nullptr) {
+        return it->second.stream;
+    }
+
+    aclrtStream stream = nullptr;
+    ret = aclrtCreateStreamWithConfig(&stream, 0, kStreamFlags);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtCreateStreamWithConfig failed for device "
+                   << device_id << ", ret:" << ret
+                   << ", errmsg:" << aclGetRecentErrMsg();
+        return nullptr;
+    }
+
+    aclrtContext ctx = nullptr;
+    ret = aclrtGetCurrentContext(&ctx);
+    if (ret != ACL_ERROR_NONE || ctx == nullptr) {
+        LOG(ERROR) << "aclrtGetCurrentContext failed after creating stream for "
+                      "device "
+                   << device_id << ", ret:" << ret
+                   << ", errmsg:" << aclGetRecentErrMsg();
+        ctx = nullptr;
+    }
+    streams_[device_id] = DeviceStream{stream, ctx};
+    VLOG(1) << "Created LocalCopyEngine stream for device " << device_id;
+    return stream;
+}
+
 void LocalCopyEngine::Copy(TransferRequest::OpCode opcode,
                            const std::vector<Slice *> &slice_list) {
     if (slice_list.empty()) {
@@ -118,6 +184,8 @@ void LocalCopyEngine::Copy(TransferRequest::OpCode opcode,
         ret = CopyWithBatch(opcode, slice_list, kind, batch_num, slice_index);
         if (ret == ACL_ERROR_RT_FEATURE_NOT_SUPPORT) {
             // Fallback to async copy if batch copy is not supported
+            VLOG(1) << "aclrtMemcpyBatch FEATURE_NOT_SUPPORT (207000); "
+                       "falling back to CopyWithAsync";
             CopyWithAsync(opcode, slice_list, kind);
             return;
         }
@@ -243,6 +311,14 @@ void LocalCopyEngine::CopyWithSync(TransferRequest::OpCode opcode,
 void LocalCopyEngine::CopyWithAsync(TransferRequest::OpCode opcode,
                                     const std::vector<Slice *> &slice_list,
                                     aclrtMemcpyKind kind) {
+    aclrtStream stream = GetOrCreateStreamForCurrentDevice();
+    if (stream == nullptr) {
+        for (auto &slice : slice_list) {
+            slice->markFailed();
+        }
+        return;
+    }
+
     std::vector<Slice *> async_list;
     async_list.reserve(slice_list.size());
 
@@ -254,11 +330,11 @@ void LocalCopyEngine::CopyWithAsync(TransferRequest::OpCode opcode,
 
         aclError ret;
         if (opcode == TransferRequest::WRITE) {
-            ret = aclrtMemcpyAsync(remote_ptr, len, local_ptr, len, kind,
-                                   stream_);
+            ret =
+                aclrtMemcpyAsync(remote_ptr, len, local_ptr, len, kind, stream);
         } else {
-            ret = aclrtMemcpyAsync(local_ptr, len, remote_ptr, len, kind,
-                                   stream_);
+            ret =
+                aclrtMemcpyAsync(local_ptr, len, remote_ptr, len, kind, stream);
         }
 
         if (ret != ACL_ERROR_NONE) {
@@ -273,8 +349,7 @@ void LocalCopyEngine::CopyWithAsync(TransferRequest::OpCode opcode,
         return;
     }
 
-    aclError ret =
-        aclrtSynchronizeStreamWithTimeout(stream_, transfer_timeout_);
+    aclError ret = aclrtSynchronizeStreamWithTimeout(stream, transfer_timeout_);
     if (ret == ACL_ERROR_NONE) {
         VLOG(1) << "Copy with aclrtMemcpyAsync suc.";
         for (auto &slice : async_list) {
@@ -282,7 +357,7 @@ void LocalCopyEngine::CopyWithAsync(TransferRequest::OpCode opcode,
         }
     } else {
         LOG(ERROR) << "Memory copy failed, ret:" << ret;
-        (void)aclrtStreamAbort(stream_);
+        (void)aclrtStreamAbort(stream);
         for (auto &slice : async_list) {
             slice->markFailed();
         }
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/slice_dispatcher.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/slice_dispatcher.cpp
index 16f1be202f..caf478671b 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/slice_dispatcher.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/slice_dispatcher.cpp
@@ -24,6 +24,7 @@
 #include <cstdlib>
 #include <cstring>
 #include <map>
+#include <tuple>
 #include <utility>
 
 #include <acl/acl.h>
@@ -63,15 +64,17 @@ DefaultSliceDispatcher::DefaultSliceDispatcher(
 
 void DefaultSliceDispatcher::enqueue(
     std::vector<Transport::Slice *> slice_list) {
-    std::unordered_map<Transport::SegmentID, std::vector<Transport::Slice *>>
+    std::map<
+        std::pair<Transport::SegmentID, Transport::TransferRequest::OpCode>,
+        std::vector<Transport::Slice *>>
         seg_to_slices;
     for (auto slice : slice_list) {
-        seg_to_slices[slice->target_id].push_back(slice);
+        seg_to_slices[{slice->target_id, slice->opcode}].push_back(slice);
     }
     auto *executor = transfer_executor_;
     auto contexts = local_engine_contexts_;
     auto *pool = thread_pool_.get();
-    for (auto &[seg_id, slices] : seg_to_slices) {
+    for (auto &[key, slices] : seg_to_slices) {
         pool->enqueue([executor, contexts, moved_slices = std::move(slices)] {
             size_t engine_idx = 0;
             if (!moved_slices.empty() &&
@@ -127,7 +130,8 @@ RoceDummyRealSliceDispatcher::~RoceDummyRealSliceDispatcher() {
 
 void RoceDummyRealSliceDispatcher::enqueue(
     std::vector<Transport::Slice *> slice_list) {
-    std::map<std::pair<size_t, Transport::SegmentID>,
+    std::map<std::tuple<size_t, Transport::SegmentID,
+                        Transport::TransferRequest::OpCode>,
              std::vector<Transport::Slice *>>
         grouped;
     for (auto slice : slice_list) {
@@ -144,10 +148,10 @@ void RoceDummyRealSliceDispatcher::enqueue(
             slice->markFailed();
             continue;
         }
-        grouped[{engine_idx, slice->target_id}].push_back(slice);
+        grouped[{engine_idx, slice->target_id, slice->opcode}].push_back(slice);
     }
     for (auto &[key, slices] : grouped) {
-        size_t engine_idx = key.first;
+        size_t engine_idx = std::get<0>(key);
         SliceTask task{std::move(slices)};
         {
             std::lock_guard<std::mutex> lock(queue_mutexes_[engine_idx]);
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.cpp
index 6f08a3257c..8eb186657e 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/transfer_executor_base.cpp
@@ -24,10 +24,9 @@
 #include <chrono>
 #include <cstdlib>
 #include <cstring>
-#include <numeric>
+#include <map>
 #include <unistd.h>
 
-#include "ascend_allocator.h"
 #include "common.h"
 #include "config.h"
 #include "transfer_metadata.h"
@@ -44,6 +43,54 @@ void markSlicesFailed(const std::vector<Transport::Slice*>& slice_list) {
         slice->markFailed();
     }
 }
+
+std::string EngineNameForDestAddr(
+    const std::vector<TransferMetadata::BufferDesc>& buffers,
+    const std::vector<std::string>& endpoints, uint64_t dest_addr) {
+    // A single-engine TE (embedded/standalone) publishes one endpoint at
+    // index 0, while buffer device_id is the logical NPU id and is often
+    // >= 1. That id is not an engine index.
+    if (endpoints.size() == 1) {
+        return endpoints.front();
+    }
+    for (const auto& buf : buffers) {
+        if (dest_addr < buf.addr || dest_addr - buf.addr >= buf.length) {
+            continue;
+        }
+        if (buf.device_id < 0) {
+            LOG(WARNING) << "Dest buffer at " << dest_addr
+                         << " has device_id=" << buf.device_id
+                         << ", falling back to " << endpoints.front();
+            return endpoints.front();
+        }
+        const auto idx = static_cast<size_t>(buf.device_id);
+        if (idx < endpoints.size()) {
+            return endpoints[idx];
+        }
+        LOG(WARNING) << "Dest buffer device_id=" << buf.device_id
+                     << " >= endpoint count " << endpoints.size()
+                     << ", falling back to " << endpoints.front();
+        return endpoints.front();
+    }
+    LOG(WARNING) << "Dest addr " << dest_addr
+                 << " matches no buffer, falling back to " << endpoints.front();
+    return endpoints.front();
+}
+
+int CurrentEngineIndex(size_t engine_count, size_t& engine_idx) {
+    if (engine_count == 1) {
+        engine_idx = 0;
+        return 0;
+    }
+    int32_t current_device_id = 0;
+    CHECK_ACL(aclrtGetDevice(&current_device_id));
+    engine_idx = static_cast<size_t>(current_device_id);
+    if (engine_idx >= engine_count) {
+        LOG(ERROR) << "Invalid device id:" << current_device_id;
+        return -1;
+    }
+    return 0;
+}
 }  // namespace
 
 TransferExecutorBase::TransferExecutorBase(const InitParams& params)
@@ -111,6 +158,8 @@ void TransferExecutorBase::ParseExecutorEnvIntoInitParams(InitParams& params) {
         params.auto_connect = true;
         LOG(INFO) << "AutoConnect enabled by capability probe";
     }
+    params.client_server_mode =
+        adxl::IsAdxlFeatureSupported(adxl::CLIENT_SERVER_COMM);
     char* buffer_pool = std::getenv("ASCEND_BUFFER_POOL");
     if (buffer_pool && std::strcmp(buffer_pool, "0:0") != 0) {
         params.use_buffer_pool = true;
@@ -173,6 +222,10 @@ int TransferExecutorBase::initEngines() {
     if (local_comm_res) {
         options["adxl.LocalCommRes"] = local_comm_res;
         LOG(INFO) << "Set LocalCommRes to:" << local_comm_res;
+    } else if (params_.client_server_mode) {
+        options["adxl.LocalCommRes"] = R"({"version":"1.3"})";
+        LOG(INFO) << "Client-Server mode enabled, set LocalCommRes to "
+                     "{\"version\":\"1.3\"}";
     }
 
     options[kAutoConnect] = params_.auto_connect ? kEnabled : kDisabled;
@@ -218,7 +271,10 @@ int TransferExecutorBase::initEngines() {
     const auto& endpoints = local_segment_desc->rank_info.endpoints;
     for (size_t idx = 0; idx < endpoints.size(); ++idx) {
         if (idx >= local_engine_contexts_.size()) {
-            LOG(ERROR) << "Endpoint count exceeds local_engine_contexts size";
+            LOG(ERROR) << "Endpoint count exceeds local_engine_contexts size, "
+                       << "idx: " << idx << ", endpoints: " << endpoints.size()
+                       << ", local_engine_contexts: "
+                       << local_engine_contexts_.size();
             return -1;
         }
         CHECK_ACL(aclrtSetCurrentContext(local_engine_contexts_[idx]));
@@ -421,8 +477,7 @@ void TransferExecutorBase::rollbackRegisteredMem(
 
 int TransferExecutorBase::registerMem(void* addr, size_t length,
                                       adxl::MemType mem_type,
-                                      bool use_buffer_pool, bool roce_mode,
-                                      bool agent_mode) {
+                                      bool use_buffer_pool) {
     if (mem_type == adxl::MEM_HOST && use_buffer_pool) {
         LOG(INFO) << "Ignore register host mem:" << addr
                   << " when buffer pool is enabled.";
@@ -443,21 +498,11 @@ int TransferExecutorBase::registerMem(void* addr, size_t length,
                [saved_ctx]() { (void)aclrtSetCurrentContext(saved_ctx); });
 
     std::vector<size_t> engine_indices;
-    bool register_to_all =
-        (roce_mode && agent_mode && ascend_is_store_memory(addr, length));
-    if (register_to_all || adxl_engines_.size() == 1U) {
-        engine_indices.resize(adxl_engines_.size());
-        std::iota(engine_indices.begin(), engine_indices.end(), 0);
-    } else {
-        int32_t current_device_id = 0;
-        CHECK_ACL(aclrtGetDevice(&current_device_id));
-        size_t engine_idx = static_cast<size_t>(current_device_id);
-        if (engine_idx >= adxl_engines_.size()) {
-            LOG(ERROR) << "Invalid device id:" << current_device_id;
-            return -1;
-        }
-        engine_indices = {engine_idx};
+    size_t engine_idx = 0;
+    if (CurrentEngineIndex(adxl_engines_.size(), engine_idx) != 0) {
+        return -1;
     }
+    engine_indices = {engine_idx};
 
     adxl::MemDesc mem_desc{};
     mem_desc.addr = reinterpret_cast<uintptr_t>(addr);
@@ -484,7 +529,9 @@ int TransferExecutorBase::registerMem(void* addr, size_t length,
         auto adxl_ret = adxl_engines_[engine_idx]->RegisterMem(
             mem_desc, mem_type, mem_handle);
         if (adxl_ret != adxl::SUCCESS) {
-            LOG(ERROR) << "Register mem ret: " << adxl_ret
+            LOG(ERROR) << "Register mem ret: " << adxl_ret << ", addr: " << addr
+                       << ", length: " << length
+                       << ", engine index: " << engine_idx
                        << ", errmsg: " << aclGetRecentErrMsg();
             rollbackRegisteredMem(registered_mem_handles);
             return -1;
@@ -548,79 +595,38 @@ int TransferExecutorBase::deregisterMem(void* addr) {
 
 std::string TransferExecutorBase::resolveTargetAdxlEngineName(
     const std::shared_ptr<TransferMetadata::SegmentDesc>& segment_desc,
-    size_t engine_idx) const {
+    uint64_t dest_addr) const {
     const auto& endpoints = segment_desc->rank_info.endpoints;
     if (endpoints.empty()) return {};
+    return EngineNameForDestAddr(segment_desc->buffers, endpoints, dest_addr);
+}
 
-    // Standard dummy-real RoCE: same-index pairing (unchanged)
-    if (params_.agent_mode && params_.roce_mode) {
-        if (engine_idx >= endpoints.size()) return {};
-        return endpoints[engine_idx];
+void TransferExecutorBase::processSliceList(
+    const std::vector<Transport::Slice*>& slice_list) {
+    if (slice_list.empty()) {
+        return;
     }
-
-    // Standalone mode: non-dummy-real thin client without fabric mem.
-    // RoCE/HCCS all use phy_dev mapping; same-host offset +1 avoids
-    // connecting to the same physical device across processes.
-    if (!params_.agent_mode && !params_.use_fabric_mem) {
-        aclrtContext saved_ctx = nullptr;
-        if (aclrtGetCurrentContext(&saved_ctx) != ACL_ERROR_NONE) {
-            LOG(ERROR) << "aclrtGetCurrentContext failed in standalone resolve";
-            return endpoints.front();
-        }
-        MAKE_GUARD(ctx_restore,
-                   [saved_ctx]() { (void)aclrtSetCurrentContext(saved_ctx); });
-
-        int32_t logic_dev = 0;
-        if (engine_idx < local_engine_contexts_.size() &&
-            local_engine_contexts_[engine_idx] != nullptr) {
-            if (aclrtSetCurrentContext(local_engine_contexts_[engine_idx]) !=
-                ACL_ERROR_NONE) {
-                LOG(ERROR) << "aclrtSetCurrentContext failed in standalone "
-                              "resolve, engine_idx="
-                           << engine_idx;
-                return endpoints.front();
-            }
-        }
-        if (aclrtGetDevice(&logic_dev) != ACL_ERROR_NONE) {
-            LOG(ERROR) << "aclrtGetDevice failed in standalone resolve";
-            return endpoints.front();
-        }
-        if (logic_dev < 0) {
-            LOG(ERROR) << "Invalid logic device ID: " << logic_dev;
-            return endpoints.front();
-        }
-
-        int32_t phy_dev = logic_dev;
-        auto acl_ret = aclrtGetPhyDevIdByLogicDevId(logic_dev, &phy_dev);
-        if (acl_ret != ACL_ERROR_NONE) {
-            LOG(WARNING)
-                << "aclrtGetPhyDevIdByLogicDevId failed, using logic dev id";
-        }
-        if (phy_dev < 0) {
-            LOG(ERROR) << "Invalid physical device ID: " << phy_dev;
-            return endpoints.front();
-        }
-        size_t base_idx = static_cast<size_t>(phy_dev);
-
-        auto local_desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
-        const auto& remote_host_ip = segment_desc->rank_info.hostIp;
-        if (local_desc && !local_desc->rank_info.hostIp.empty() &&
-            !remote_host_ip.empty() &&
-            local_desc->rank_info.hostIp == remote_host_ip &&
-            endpoints.size() > 1) {
-            base_idx = (base_idx + 1) % endpoints.size();
-            VLOG(1) << "Standalone same-host offset: phy_dev=" << phy_dev
-                    << " -> target_idx=" << base_idx;
-        }
-        if (base_idx >= endpoints.size()) return endpoints.front();
-        return endpoints[base_idx];
+    auto target_segment_desc =
+        metadata_->getSegmentDescByID(slice_list[0]->target_id);
+    if (!target_segment_desc) {
+        LOG(ERROR) << "Cannot find segment descriptor for target_id: "
+                   << slice_list[0]->target_id;
+        markSlicesFailed(slice_list);
+        return;
     }
 
-    // Default: dummy-real non-RoCE or fabric-mem standalone
-    return endpoints.front();
+    std::map<std::string, std::vector<Transport::Slice*>> groups;
+    for (auto* slice : slice_list) {
+        groups[resolveTargetAdxlEngineName(target_segment_desc,
+                                           slice->ascend_direct.dest_addr)]
+            .push_back(slice);
+    }
+    for (auto& [_, group] : groups) {
+        processHomogeneousSliceList(group);
+    }
 }
 
-void TransferExecutorBase::processSliceList(
+void TransferExecutorBase::processHomogeneousSliceList(
     const std::vector<Transport::Slice*>& slice_list) {
     if (slice_list.empty()) {
         return;
@@ -661,8 +667,8 @@ void TransferExecutorBase::processSliceList(
             markSlicesFailed(slice_list);
             return;
         }
-        target_adxl_engine_name =
-            resolveTargetAdxlEngineName(target_segment_desc, local_engine_idx);
+        target_adxl_engine_name = resolveTargetAdxlEngineName(
+            target_segment_desc, slice_list[0]->ascend_direct.dest_addr);
         if (target_adxl_engine_name.empty()) {
             LOG(ERROR) << "Invalid local_engine_idx: " << local_engine_idx
                        << " target endpoint size:"
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/utils.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/utils.cpp
index e1e623722e..8ff846ace7 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/utils.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ascend_direct_transport/utils.cpp
@@ -76,15 +76,14 @@ const Json::Value* FindProtocolDescValue(const Json::Value& root) {
     }
     return nullptr;
 }
-}  // namespace
 
-bool HasRoceProtocolDescInGlobalResourceConfig(const char* config_str) {
+bool ParseGlobalResourceConfigObject(const char* config_str,
+                                     Json::Value& root) {
     if (config_str == nullptr || config_str[0] == '\0') {
         return false;
     }
     Json::CharReaderBuilder builder;
     builder["collectComments"] = false;
-    Json::Value root;
     std::string errs;
     const std::unique_ptr<Json::CharReader> reader(builder.newCharReader());
     if (!reader->parse(config_str, config_str + std::strlen(config_str), &root,
@@ -98,6 +97,15 @@ bool HasRoceProtocolDescInGlobalResourceConfig(const char* config_str) {
         LOG(WARNING) << "ASCEND_GLOBAL_RESOURCE_CONFIG must be a JSON object";
         return false;
     }
+    return true;
+}
+}  // namespace
+
+bool HasRoceProtocolDescInGlobalResourceConfig(const char* config_str) {
+    Json::Value root;
+    if (!ParseGlobalResourceConfigObject(config_str, root)) {
+        return false;
+    }
     const Json::Value* protocol_desc = FindProtocolDescValue(root);
     if (protocol_desc == nullptr) {
         return false;
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/ascend_transport_c/CMakeLists.txt b/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/ascend_transport_c/CMakeLists.txt
index 06ea0ff599..9900e4a03e 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/ascend_transport_c/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/ascend_transport_c/CMakeLists.txt
@@ -7,7 +7,7 @@ string(REPLACE "-O3" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
 
 add_library(ascend_transport_mem SHARED  ${ASCEND_TRANSPORT_MEM_SOURCES})
 set_target_properties(ascend_transport_mem PROPERTIES POSITION_INDEPENDENT_CODE ON)
-target_link_libraries(ascend_transport_mem PRIVATE hccl ascendcl glog gflags)
+target_link_libraries(ascend_transport_mem PRIVATE hccl ascendcl glog::glog gflags::gflags)
 
 target_compile_options(ascend_transport_mem BEFORE PRIVATE "-std=c++11" "-fstack-protector-strong" "-s" "-Wl,-z,relro" "-Wl,-z,now" "-Wl,-z,noexecstack" "-Wl,--copy-dt-needed-entries" "-DOPEN_BUILD_PROJECT" "-DLOG_CPP" "-D_GLIBCXX_USE_CXX11_ABI=0")
 target_link_options(ascend_transport_mem BEFORE PRIVATE "-std=c++11" "-fstack-protector-strong" "-s" "-Wl,-z,relro" "-Wl,-z,now" "-Wl,-z,noexecstack" "-Wl,--copy-dt-needed-entries" "-DOPEN_BUILD_PROJECT" "-DLOG_CPP" "-D_GLIBCXX_USE_CXX11_ABI=0")
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/hccl_transport.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/hccl_transport.cpp
index ef81cb6f30..5e3a1df24e 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/hccl_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/hccl_transport/hccl_transport.cpp
@@ -224,7 +224,6 @@ void HcclTransport::initiatorLoop(int deviceLogicId, int selfIdx) {
         for (auto slice : slice_list) {
             if (slice->status != Slice::SliceStatus::FAILED) {
                 slice->markSuccess();
-                slice->task->transferred_bytes = slice->length;
             }
         }
         (void)start;
@@ -538,9 +537,13 @@ Status HcclTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/ascend_transport/ubshmem_transport/ubshmem_transport.cpp b/mooncake-transfer-engine/src/transport/ascend_transport/ubshmem_transport/ubshmem_transport.cpp
index 1125e5d466..259bbb0044 100644
--- a/mooncake-transfer-engine/src/transport/ascend_transport/ubshmem_transport/ubshmem_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/ascend_transport/ubshmem_transport/ubshmem_transport.cpp
@@ -523,9 +523,13 @@ Status UBShmemTransport::getTransferStatus(BatchID batch_id, size_t task_id,
 
     // Get task and status info
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
 
     // Determine completion status
     if (success_slice_count + failed_slice_count == task.slice_count) {
diff --git a/mooncake-transfer-engine/src/transport/barex_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/barex_transport/CMakeLists.txt
index f5df7ce9bf..ed9c1e220c 100644
--- a/mooncake-transfer-engine/src/transport/barex_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/barex_transport/CMakeLists.txt
@@ -1,5 +1,5 @@
 file(GLOB BAREX_SOURCES "*.cpp")
 
 add_library(barex_transport OBJECT ${BAREX_SOURCES})
-target_link_libraries(barex_transport PRIVATE pthread accl_barex)
-target_compile_definitions(barex_transport PRIVATE CMAKE_INCLUDE=1)
\ No newline at end of file
+target_link_libraries(barex_transport PRIVATE glog::glog pthread accl_barex)
+target_compile_definitions(barex_transport PRIVATE CMAKE_INCLUDE=1)
diff --git a/mooncake-transfer-engine/src/transport/barex_transport/barex_transport.cpp b/mooncake-transfer-engine/src/transport/barex_transport/barex_transport.cpp
index 567bef44af..0efa0c94ea 100644
--- a/mooncake-transfer-engine/src/transport/barex_transport/barex_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/barex_transport/barex_transport.cpp
@@ -1205,9 +1205,13 @@ Status BarexTransport::getTransferStatus(BatchID batch_id,
     status.resize(task_count);
     for (size_t task_id = 0; task_id < task_count; task_id++) {
         auto &task = batch_desc.task_list[task_id];
-        status[task_id].transferred_bytes = task.transferred_bytes;
-        uint64_t success_slice_count = task.success_slice_count;
-        uint64_t failed_slice_count = task.failed_slice_count;
+        uint64_t success_slice_count =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+        uint64_t failed_slice_count =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+        // Completion counters publish the preceding byte updates.
+        status[task_id].transferred_bytes =
+            __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
         if (success_slice_count + failed_slice_count == task.slice_count) {
             if (failed_slice_count) {
                 status[task_id].s = TransferStatusEnum::FAILED;
@@ -1232,9 +1236,13 @@ Status BarexTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count)
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/cxi_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/cxi_transport/CMakeLists.txt
index 51d4197776..8772da6e4a 100644
--- a/mooncake-transfer-engine/src/transport/cxi_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/cxi_transport/CMakeLists.txt
@@ -2,7 +2,10 @@ file(GLOB CXI_SOURCES "*.cpp")
 add_library(cxi_transport OBJECT ${CXI_SOURCES})
 
 # Link against libfabric (fabric) instead of ibverbs for AWS EFA
-target_link_libraries(cxi_transport PRIVATE fabric glog::glog)
+target_link_libraries(
+  cxi_transport
+  PUBLIC glog::glog gflags::gflags
+  PRIVATE fabric)
 
 target_include_directories(
   cxi_transport
diff --git a/mooncake-transfer-engine/src/transport/cxi_transport/cxi_transport.cpp b/mooncake-transfer-engine/src/transport/cxi_transport/cxi_transport.cpp
index 3c42fe66da..4773866603 100644
--- a/mooncake-transfer-engine/src/transport/cxi_transport/cxi_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/cxi_transport/cxi_transport.cpp
@@ -839,9 +839,13 @@ Status CxiTransport::getTransferStatus(BatchID batch_id,
     status.resize(task_count);
     for (size_t task_id = 0; task_id < task_count; task_id++) {
         auto& task = batch_desc.task_list[task_id];
-        status[task_id].transferred_bytes = task.transferred_bytes;
-        uint64_t success_slice_count = task.success_slice_count;
-        uint64_t failed_slice_count = task.failed_slice_count;
+        uint64_t success_slice_count =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+        uint64_t failed_slice_count =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+        // Completion counters publish the preceding byte updates.
+        status[task_id].transferred_bytes =
+            __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
         if (success_slice_count + failed_slice_count == task.slice_count) {
             if (failed_slice_count)
                 status[task_id].s = TransferStatusEnum::FAILED;
@@ -865,9 +869,13 @@ Status CxiTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count)
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/cxl_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/cxl_transport/CMakeLists.txt
index eef9051ff1..2b4a5c50af 100644
--- a/mooncake-transfer-engine/src/transport/cxl_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/cxl_transport/CMakeLists.txt
@@ -1,4 +1,5 @@
 file(GLOB CXL_SOURCES "*.cpp")
 
 add_library(cxl_transport OBJECT ${CXL_SOURCES})
-# target_link_libraries(rdma_transport PUBLIC transport)
\ No newline at end of file
+target_link_libraries(cxl_transport PRIVATE glog::glog)
+# target_link_libraries(rdma_transport PUBLIC transport)
diff --git a/mooncake-transfer-engine/src/transport/cxl_transport/cxl_transport.cpp b/mooncake-transfer-engine/src/transport/cxl_transport/cxl_transport.cpp
index 23984f7d47..d46bb2d25a 100644
--- a/mooncake-transfer-engine/src/transport/cxl_transport/cxl_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/cxl_transport/cxl_transport.cpp
@@ -301,9 +301,13 @@ Status CxlTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/device/CMakeLists.txt b/mooncake-transfer-engine/src/transport/device/CMakeLists.txt
index 8e13979486..c5358d4e33 100644
--- a/mooncake-transfer-engine/src/transport/device/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/device/CMakeLists.txt
@@ -5,10 +5,8 @@
 # consumers that link transfer_engine via hand- written ldflags (Go p2p-store /
 # mooncake-store), which bypass CMake's target_link_libraries propagation.
 set(DEVICE_TRANSPORT_SOURCES p2p_device_transport.cpp)
-if((USE_CUDA OR USE_MUSA) AND NOT USE_CXI)
+if((USE_CUDA OR USE_MUSA OR USE_MACA) AND NOT USE_CXI)
     list(APPEND DEVICE_TRANSPORT_SOURCES ibgda_device_transport.cpp mlx5gda.cpp)
-elseif(USE_MACA)
-    list(APPEND DEVICE_TRANSPORT_SOURCES ibgda_device_transport_maca_stub.cpp)
 endif()
 if(USE_NCCL_DEVICE)
     list(APPEND DEVICE_TRANSPORT_SOURCES nccl_device_transport.cpp)
@@ -16,6 +14,7 @@ endif()
 
 add_library(device_transport OBJECT ${DEVICE_TRANSPORT_SOURCES})
 target_include_directories(device_transport PRIVATE ${CMAKE_SOURCE_DIR}/include)
+target_link_libraries(device_transport PRIVATE glog::glog)
 
 if(USE_CUDA)
   target_include_directories(device_transport PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
diff --git a/mooncake-transfer-engine/src/transport/device/ibgda_device_transport.cpp b/mooncake-transfer-engine/src/transport/device/ibgda_device_transport.cpp
index 18533b0fee..17e7629e91 100644
--- a/mooncake-transfer-engine/src/transport/device/ibgda_device_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/device/ibgda_device_transport.cpp
@@ -26,6 +26,7 @@
 #include <infiniband/mlx5dv.h>
 #include <infiniband/verbs.h>
 
+#include <algorithm>
 #include <cerrno>
 #include <cstdlib>
 #include <cstring>
@@ -42,11 +43,14 @@ namespace mooncake {
 namespace device {
 
 static constexpr size_t kCtrlBufSize = 1024ULL * 1024 * 1024;  // 1 GiB
+static constexpr size_t kHostMappedCqMinSize = 256ULL * 1024 * 1024;
+static constexpr size_t kIbgdaQpWqebbCount = 16384;
 
 enum class ControlMemoryMode {
     kGpuDmabuf,
     kGpuVa,
     kHostMapped,
+    kPerQpGpuVaHostMappedCq,
 };
 
 static const char* controlMemoryModeName(ControlMemoryMode mode) {
@@ -57,6 +61,8 @@ static const char* controlMemoryModeName(ControlMemoryMode mode) {
             return "gpu-va";
         case ControlMemoryMode::kHostMapped:
             return "host-mapped";
+        case ControlMemoryMode::kPerQpGpuVaHostMappedCq:
+            return "per-qp-gpu-va-host-mapped-cq";
     }
     return "unknown";
 }
@@ -256,23 +262,57 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
                "trying GPU-VA control buffer";
         return allocateGpuVaOrHostControlBuffer();
 #endif
+#if defined(USE_MUSA)
+        return allocatePerQpGpuVaControlBuffers();
+#elif defined(USE_MACA)
+        // MACA C500 currently rejects the GPU-VA control UMEM at CREATE_QP;
+        // start with the host-mapped control layout used by the fallback path.
+        return allocateControlBuffer(ControlMemoryMode::kHostMapped);
+#else
         return allocateControlBuffer(ControlMemoryMode::kGpuVa);
+#endif
     }
 
     int createQueuePairs(void* stream_ptr) override {
         auto stream = static_cast<cudaStream_t>(stream_ptr);
-        mlx5gda_control_region_allocator region_allocator{
+        mlx5gda_control_region_allocator dmabuf_region_allocator{
             .context = this,
             .allocate = allocateDmabufControlRegionThunk,
             .release = releaseDmabufControlRegionThunk,
         };
-        const mlx5gda_control_region_allocator* allocator =
-            ctrl_buf_mode_ == ControlMemoryMode::kGpuDmabuf ? &region_allocator
-                                                            : nullptr;
+        mlx5gda_control_region_allocator gpu_va_region_allocator{
+            .context = this,
+            .allocate = allocateGpuVaControlRegionThunk,
+            .release = releaseGpuVaControlRegionThunk,
+        };
+        const mlx5gda_control_region_allocator* cq_region_allocator =
+            ctrl_buf_mode_ == ControlMemoryMode::kGpuDmabuf
+                ? &dmabuf_region_allocator
+                : nullptr;
+        const mlx5gda_control_region_allocator* qp_region_allocator =
+            ctrl_buf_mode_ == ControlMemoryMode::kGpuDmabuf
+                ? &dmabuf_region_allocator
+            : ctrl_buf_mode_ == ControlMemoryMode::kPerQpGpuVaHostMappedCq
+                ? &gpu_va_region_allocator
+                : nullptr;
+        const mlx5gda_control_buffer ctrl{
+            .addr = ctrl_buf_,
+            .dev_addr = ctrl_buf_dev_,
+            .umem = ctrl_buf_umem_,
+            .heap = ctrl_buf_heap_,
+        };
+        const mlx5gda_control_buffer cq =
+            cq_buf_ ? mlx5gda_control_buffer{
+                          .addr = cq_buf_,
+                          .dev_addr = cq_buf_dev_,
+                          .umem = cq_buf_umem_,
+                          .heap = cq_buf_heap_,
+                      }
+                    : ctrl;
         for (int i = 0; i < num_qps_; ++i) {
             mlx5gda_qp* qp = mlx5gda_create_rc_qp(
-                mpd_, ctrl_buf_, ctrl_buf_umem_, ctrl_buf_heap_, pd_, 16384, 1,
-                stream, allocator);
+                mpd_, &ctrl, &cq, pd_, kIbgdaQpWqebbCount, 1, stream,
+                cq_region_allocator, qp_region_allocator);
             if (!qp) {
                 const int qp_errno = errno;
                 LOG(ERROR) << "[EP IBGDA] mlx5gda_create_rc_qp failed at " << i;
@@ -282,30 +322,21 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
             }
             if (mlx5gda_modify_rc_qp_rst2init(qp, 0)) {
                 LOG(ERROR) << "[EP IBGDA] rst2init failed at " << i;
-                mlx5gda_destroy_qp(ctrl_buf_heap_, qp);
+                mlx5gda_destroy_qp(qp);
                 return -1;
             }
             cudaStreamSynchronize(stream);
-            const bool split_regions =
-                ctrl_buf_mode_ == ControlMemoryMode::kGpuDmabuf;
             mlx5gda_qp_devctx devctx{
                 .qpn = qp->qpn,
                 .wqeid_mask = qp->num_wqebb - 1,
-                .wq = split_regions ? reinterpret_cast<mlx5gda_wqebb*>(qp->wq)
-                                    : reinterpret_cast<mlx5gda_wqebb*>(
-                                          static_cast<char*>(ctrl_buf_dev_) +
-                                          qp->wq_offset),
-                .cq = split_regions
-                          ? reinterpret_cast<mlx5_cqe64*>(qp->send_cq->cq_buf)
-                          : reinterpret_cast<mlx5_cqe64*>(
-                                static_cast<char*>(ctrl_buf_dev_) +
-                                qp->send_cq->cq_offset),
-                .dbr = split_regions
-                           ? reinterpret_cast<mlx5gda_wq_dbr*>(qp->dbr)
-                           : reinterpret_cast<mlx5gda_wq_dbr*>(
-                                 static_cast<char*>(ctrl_buf_dev_) +
-                                 qp->dbr_offset),
-                .bf = static_cast<char*>(qp->uar->reg_addr),
+                .mutex = 0,
+                .wq = reinterpret_cast<mlx5gda_wqebb*>(qp->dev_wq),
+                .cq = reinterpret_cast<mlx5_cqe64*>(qp->send_cq->dev_cq_buf),
+                .dbr = reinterpret_cast<mlx5gda_wq_dbr*>(qp->dev_dbr),
+                .bf = qp->bf_device_addr,
+                .bf_offset = 0,
+                .wq_head = 0,
+                .wq_tail = 0,
             };
             cudaMemcpy(
                 static_cast<char*>(qp_devctxs_) + i * sizeof(mlx5gda_qp_devctx),
@@ -488,7 +519,7 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
             LOG(ERROR) << "[EP IBGDA] cudaMalloc failed for DMA-BUF control "
                           "region size="
                        << size << ": " << cudaGetErrorString(cuda_error);
-            errno = cuda_error == cudaErrorMemoryAllocation ? ENOMEM : EIO;
+            errno = EIO;
             return -1;
         }
 
@@ -561,6 +592,54 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
         *region = {};
     }
 
+    int allocateGpuVaControlRegion(size_t requested_size,
+                                   mlx5gda_control_region* region) {
+        if (!region || requested_size == 0) {
+            errno = EINVAL;
+            return -1;
+        }
+
+        const long page_size = sysconf(_SC_PAGESIZE);
+        if (page_size <= 0) {
+            errno = EIO;
+            return -1;
+        }
+        const size_t page_mask = static_cast<size_t>(page_size) - 1;
+        const size_t size = (requested_size + page_mask) & ~page_mask;
+
+        void* addr = nullptr;
+        const cudaError_t cuda_error = cudaMalloc(&addr, size);
+        if (cuda_error != cudaSuccess) {
+            LOG(ERROR) << "[EP IBGDA] cudaMalloc failed for per-QP GPU-VA "
+                          "control region size="
+                       << size << ": " << cudaGetErrorString(cuda_error);
+            errno = EIO;
+            return -1;
+        }
+
+        mlx5dv_devx_umem* umem =
+            mlx5dv_devx_umem_reg(ctx_, addr, size, IBV_ACCESS_LOCAL_WRITE);
+        if (!umem) {
+            PLOG(ERROR) << "[EP IBGDA] Control UMEM registration failed for "
+                           "per-QP GPU-VA region";
+            cudaFree(addr);
+            return -1;
+        }
+        *region = mlx5gda_control_region{
+            .addr = addr,
+            .size = size,
+            .umem = umem,
+        };
+        return 0;
+    }
+
+    void releaseGpuVaControlRegion(mlx5gda_control_region* region) {
+        if (!region) return;
+        if (region->umem) mlx5dv_devx_umem_dereg(region->umem);
+        if (region->addr) cudaFree(region->addr);
+        *region = {};
+    }
+
     static int allocateDmabufControlRegionThunk(
         void* context, size_t size, mlx5gda_control_region* region) {
         return static_cast<IbgdaDeviceTransportImpl*>(context)
@@ -573,6 +652,18 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
             ->releaseDmabufControlRegion(region);
     }
 
+    static int allocateGpuVaControlRegionThunk(void* context, size_t size,
+                                               mlx5gda_control_region* region) {
+        return static_cast<IbgdaDeviceTransportImpl*>(context)
+            ->allocateGpuVaControlRegion(size, region);
+    }
+
+    static void releaseGpuVaControlRegionThunk(void* context,
+                                               mlx5gda_control_region* region) {
+        static_cast<IbgdaDeviceTransportImpl*>(context)
+            ->releaseGpuVaControlRegion(region);
+    }
+
     int allocateControlBuffer(ControlMemoryMode mode) {
         ctrl_buf_mode_ = mode;
         if (mode == ControlMemoryMode::kHostMapped) {
@@ -640,6 +731,79 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
         return 0;
     }
 
+    int allocatePerQpGpuVaControlBuffers() {
+        ctrl_buf_mode_ = ControlMemoryMode::kPerQpGpuVaHostMappedCq;
+        if (allocateHostMappedCqBuffer() != 0) {
+            freeControlBuffer();
+            return -1;
+        }
+        LOG(INFO) << "[EP IBGDA] Using per-QP GPU WQ/DBR regions and "
+                     "host-backed mapped CQ buffer";
+        return 0;
+    }
+
+    int allocateHostMappedCqBuffer() {
+        // Each QP owns a 16K-entry CQ.  A CQ consumes exactly 1 MiB, but its
+        // trailing DBR makes the next CQ start on a fresh adapter page.  The
+        // fixed 256 MiB baseline therefore cannot hold 256 QPs.
+        constexpr size_t kAdapterPageSize = 4096;
+        constexpr size_t kCqBytesPerQp =
+            kIbgdaQpWqebbCount * sizeof(mlx5_cqe64) + kAdapterPageSize;
+        const size_t cq_buf_size =
+            std::max(kHostMappedCqMinSize,
+                     static_cast<size_t>(num_qps_) * kCqBytesPerQp);
+        void* ptr = nullptr;
+        const int ret = posix_memalign(&ptr, 4096, cq_buf_size);
+        if (ret != 0) {
+            LOG(ERROR) << "[EP IBGDA] posix_memalign cq_buf failed: " << ret;
+            return -1;
+        }
+        cq_buf_ = ptr;
+        std::memset(cq_buf_, 0, cq_buf_size);
+        cudaError_t err =
+            cudaHostRegister(cq_buf_, cq_buf_size,
+                             cudaHostRegisterPortable | cudaHostRegisterMapped);
+        if (err != cudaSuccess) {
+            LOG(ERROR) << "[EP IBGDA] cudaHostRegister cq_buf failed: "
+                       << cudaGetErrorString(err);
+            free(cq_buf_);
+            cq_buf_ = nullptr;
+            return -1;
+        }
+        err = cudaHostGetDevicePointer(&cq_buf_dev_, cq_buf_, 0);
+        if (err != cudaSuccess) {
+            LOG(ERROR) << "[EP IBGDA] cudaHostGetDevicePointer cq_buf failed: "
+                       << cudaGetErrorString(err);
+            cudaHostUnregister(cq_buf_);
+            free(cq_buf_);
+            cq_buf_ = nullptr;
+            return -1;
+        }
+        cq_buf_umem_ = mlx5dv_devx_umem_reg(ctx_, cq_buf_, cq_buf_size,
+                                            IBV_ACCESS_LOCAL_WRITE);
+        if (!cq_buf_umem_) {
+            LOG(ERROR) << "[EP IBGDA] CQ UMEM registration failed (errno="
+                       << errno << ")";
+            cudaHostUnregister(cq_buf_);
+            free(cq_buf_);
+            cq_buf_ = nullptr;
+            cq_buf_dev_ = nullptr;
+            return -1;
+        }
+        cq_buf_heap_ = memheap_create(cq_buf_size);
+        if (!cq_buf_heap_) {
+            LOG(ERROR) << "[EP IBGDA] memheap_create cq_buf failed";
+            mlx5dv_devx_umem_dereg(cq_buf_umem_);
+            cq_buf_umem_ = nullptr;
+            cudaHostUnregister(cq_buf_);
+            free(cq_buf_);
+            cq_buf_ = nullptr;
+            cq_buf_dev_ = nullptr;
+            return -1;
+        }
+        return 0;
+    }
+
     int allocateGpuVaOrHostControlBuffer() {
         if (allocateControlBuffer(ControlMemoryMode::kGpuVa) == 0) return 0;
 
@@ -653,6 +817,7 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
         const bool using_dmabuf_control_regions =
             ctrl_buf_mode_ == ControlMemoryMode::kGpuDmabuf;
         if (ctrl_buf_mode_ == ControlMemoryMode::kHostMapped ||
+            ctrl_buf_mode_ == ControlMemoryMode::kPerQpGpuVaHostMappedCq ||
             (!isCreateQpBadParam(failure) && !using_dmabuf_control_regions))
             return false;
 
@@ -681,12 +846,26 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
 
     void destroyQueuePairs() {
         for (auto* qp : qps_) {
-            if (qp) mlx5gda_destroy_qp(ctrl_buf_heap_, qp);
+            if (qp) mlx5gda_destroy_qp(qp);
         }
         qps_.clear();
     }
 
     void freeControlBuffer() {
+        if (cq_buf_heap_) {
+            memheap_destroy(cq_buf_heap_);
+            cq_buf_heap_ = nullptr;
+        }
+        if (cq_buf_umem_) {
+            mlx5dv_devx_umem_dereg(cq_buf_umem_);
+            cq_buf_umem_ = nullptr;
+        }
+        if (cq_buf_) {
+            cudaHostUnregister(cq_buf_);
+            free(cq_buf_);
+            cq_buf_ = nullptr;
+            cq_buf_dev_ = nullptr;
+        }
         if (ctrl_buf_heap_) {
             memheap_destroy(ctrl_buf_heap_);
             ctrl_buf_heap_ = nullptr;
@@ -756,6 +935,10 @@ class IbgdaDeviceTransportImpl : public RdmaTransport {
     ControlMemoryMode ctrl_buf_mode_ = ControlMemoryMode::kGpuVa;
     mlx5dv_devx_umem* ctrl_buf_umem_ = nullptr;
     memheap* ctrl_buf_heap_ = nullptr;
+    void* cq_buf_ = nullptr;
+    void* cq_buf_dev_ = nullptr;
+    mlx5dv_devx_umem* cq_buf_umem_ = nullptr;
+    memheap* cq_buf_heap_ = nullptr;
 
     // QPs
     std::vector<mlx5gda_qp*> qps_;
diff --git a/mooncake-transfer-engine/src/transport/device/ibgda_device_transport_maca_stub.cpp b/mooncake-transfer-engine/src/transport/device/ibgda_device_transport_maca_stub.cpp
deleted file mode 100644
index d59f8409e6..0000000000
--- a/mooncake-transfer-engine/src/transport/device/ibgda_device_transport_maca_stub.cpp
+++ /dev/null
@@ -1,34 +0,0 @@
-#include "transport/device/device_transport.h"
-
-namespace mooncake {
-namespace device {
-
-class NullRdmaTransport : public RdmaTransport {
-   public:
-    int initialize(const std::string&, int, int) override { return -1; }
-    int registerMemory(void*, size_t) override { return -1; }
-    int allocateControlBuffer() override { return -1; }
-    int createQueuePairs(void*) override { return -1; }
-    int recreateQueuePairs(void*) override { return -1; }
-    int connectPeers(int, bool, const std::vector<int64_t>&,
-                     const std::vector<int32_t>&, const std::vector<int32_t>&,
-                     const std::vector<int32_t>&, const std::vector<int64_t>&,
-                     const std::vector<int64_t>&,
-                     const std::vector<int>&) override {
-        return -1;
-    }
-    RdmaLocalMetadata localMetadata() const override { return {}; }
-    void* raddrsPtr() override { return nullptr; }
-    void* rkeysPtr() override { return nullptr; }
-    void* qpDevCtxsPtr() override { return nullptr; }
-    bool isRoce() const override { return false; }
-    int gidIndex() const override { return -1; }
-};
-
-std::unique_ptr<RdmaTransport> createIbgdaDeviceTransport(
-    const std::vector<std::string>&) {
-    return std::make_unique<NullRdmaTransport>();
-}
-
-}  // namespace device
-}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/device/mlx5gda.cpp b/mooncake-transfer-engine/src/transport/device/mlx5gda.cpp
index 37b22c0853..c48396322d 100644
--- a/mooncake-transfer-engine/src/transport/device/mlx5gda.cpp
+++ b/mooncake-transfer-engine/src/transport/device/mlx5gda.cpp
@@ -1,4 +1,6 @@
 #include <cmath>
+#include <cstdint>
+#include <unistd.h>
 
 #include "cuda_alike.h"
 
@@ -31,11 +33,7 @@ constexpr T round_up_pow2(T n) {
 #define IBGDA_ROUND_UP_POW2_OR_0(_n) (((_n) == 0) ? 0 : round_up_pow2(_n))
 
 static void print_cuda_error(const char* msg) {
-#ifdef USE_MUSA
-    const char* err_str = musaGetErrorString(musaGetLastError());
-#else
     const char* err_str = cudaGetErrorString(cudaGetLastError());
-#endif
     fprintf(stderr, "%s: %s\n", msg, err_str);
 }
 
@@ -81,14 +79,6 @@ static void print_devx_create_qp_failure(const uint8_t* cmd_out,
             dbr_offset);
 }
 
-// Create UAR for BF (Blue Flame) doorbell ringing.
-// On CUDA: registers the BF MMIO region into GPU address space so the
-//          GPU kernel can directly write the doorbell (lowest latency).
-// On MUSA: musaHostRegisterIoMemory is not supported for MMIO addresses,
-//          so we skip BF registration and return a UAR with reg_addr=NULL.
-//          The GPU kernel will use DBR-only mode (write to memory-mapped
-//          doorbell record, NIC polls it) — slightly higher latency but
-//          functionally correct.
 static struct mlx5dv_devx_uar* create_uar(struct ibv_context* ctx) {
     struct mlx5dv_devx_uar* uar =
         mlx5dv_devx_alloc_uar(ctx, MLX5DV_UAR_ALLOC_TYPE_BF);
@@ -96,25 +86,35 @@ static struct mlx5dv_devx_uar* create_uar(struct ibv_context* ctx) {
         errno = EIO;
         return NULL;
     }
-#ifdef USE_MUSA
-    // MUSA cannot map MMIO addresses into GPU VA.  Skip the
-    // musaHostRegister(IoMemory) call entirely — attempting it
-    // corrupts the MUSA runtime, causing all subsequent device-side
-    // fill operations to fail with "illegal memory access".
-    // Use DBR-only mode: the kernel writes to the doorbell record
-    // in GPU memory instead of the BF MMIO register.
-    uar->reg_addr = NULL;
-#else
-    if (cudaHostRegister(uar->reg_addr, MLX5GDA_BF_SIZE * 2,
-                         cudaHostRegisterPortable | cudaHostRegisterMapped |
-                             cudaHostRegisterIoMemory) != cudaSuccess) {
-        print_cuda_error("Failed to register MMIO memory");
+    return uar;
+}
+
+static int map_uar_for_device(struct mlx5dv_devx_uar* uar,
+                              struct mlx5gda_qp* qp) {
+    const cudaError_t register_result =
+        cudaHostRegister(uar->reg_addr, MLX5GDA_BF_SIZE * 2,
+                         cudaHostRegisterMapped | cudaHostRegisterIoMemory);
+    void* device_base = nullptr;
+    if (cudaHostGetDevicePointer(&device_base, uar->reg_addr, 0) !=
+        cudaSuccess) {
+        if (register_result == cudaSuccess) cudaHostUnregister(uar->reg_addr);
+        print_cuda_error("Failed to map BF MMIO page");
         errno = EIO;
-        mlx5dv_devx_free_uar(uar);
-        return NULL;
+        return -1;
     }
-#endif
-    return uar;
+    qp->bf_host_base = uar->reg_addr;
+    qp->bf_device_addr = static_cast<char*>(device_base);
+    qp->bf_host_registration_owner = register_result == cudaSuccess;
+    return 0;
+}
+
+static void unmap_uar_for_device(struct mlx5gda_qp* qp) {
+    if (qp->bf_host_registration_owner) {
+        cudaHostUnregister(qp->bf_host_base);
+        qp->bf_host_registration_owner = false;
+    }
+    qp->bf_host_base = nullptr;
+    qp->bf_device_addr = nullptr;
 }
 
 static bool uses_control_regions(
@@ -133,19 +133,15 @@ static void release_control_region(
 
 static void destroy_uar(struct mlx5dv_devx_uar* uar) {
     if (!uar) return;
-    if (uar->reg_addr) {
-        if (cudaHostUnregister(uar->reg_addr) != cudaSuccess) {
-            print_cuda_error("Failed to unregister MMIO memory");
-        }
-    }
     mlx5dv_devx_free_uar(uar);
 }
 
 struct mlx5gda_cq* mlx5gda_create_cq(
     void* ctrl_buf, struct mlx5dv_devx_umem* ctrl_buf_umem,
     struct memheap* ctrl_buf_heap, struct ibv_pd* pd, int cqe,
-    cudaStream_t stream,
-    const struct mlx5gda_control_region_allocator* region_allocator) {
+    cudaStream_t stream, void* cq_buf_arg, void* cq_buf_dev,
+    struct mlx5dv_devx_umem* cq_buf_umem, struct memheap* cq_buf_heap,
+    const struct mlx5gda_control_region_allocator* cq_region_allocator) {
     struct mlx5gda_cq* cq = NULL;
     struct mlx5dv_devx_uar* uar = NULL;
     uint32_t eqn = 0;
@@ -153,15 +149,17 @@ struct mlx5gda_cq* mlx5gda_create_cq(
     size_t dbr_offset = -1;
     struct mlx5dv_devx_obj* mlx5_cq = NULL;
     uint32_t cqn = 0;
-    void* cq_buf = ctrl_buf;
-    void* dbr = ctrl_buf;
-    struct mlx5dv_devx_umem* cq_umem = ctrl_buf_umem;
-    struct mlx5dv_devx_umem* dbr_umem = ctrl_buf_umem;
-    const bool split_regions = uses_control_regions(region_allocator);
+    void* cq_buf = cq_buf_arg ? cq_buf_arg : ctrl_buf;
+    void* dbr = cq_buf;
+    struct mlx5dv_devx_umem* cq_umem =
+        cq_buf_umem ? cq_buf_umem : ctrl_buf_umem;
+    struct mlx5dv_devx_umem* dbr_umem = cq_umem;
+    struct memheap* cq_heap = cq_buf_heap ? cq_buf_heap : ctrl_buf_heap;
+    const bool split_regions = uses_control_regions(cq_region_allocator);
 
     struct ibv_context* ctx = pd->context;
     void* cq_context = NULL;
-    bool ctrl_host = !split_regions && is_host_control_buffer(ctrl_buf);
+    bool ctrl_host = !split_regions && is_host_control_buffer(cq_buf);
 
     if (cqe <= 0) {
         errno = EINVAL;
@@ -176,16 +174,16 @@ struct mlx5gda_cq* mlx5gda_create_cq(
     if (!cq) goto fail;
 
     if (split_regions) {
-        cq->region_allocator = *region_allocator;
-        if (region_allocator->allocate(region_allocator->context,
-                                       num_cqe * sizeof(struct mlx5_cqe64),
-                                       &cq->cq_region) != 0) {
+        cq->region_allocator = *cq_region_allocator;
+        if (cq_region_allocator->allocate(cq_region_allocator->context,
+                                          num_cqe * sizeof(struct mlx5_cqe64),
+                                          &cq->cq_region) != 0) {
             perror("Failed to allocate CQ control region");
             goto fail;
         }
-        if (region_allocator->allocate(region_allocator->context,
-                                       sizeof(struct mlx5gda_cq_dbr),
-                                       &cq->dbr_region) != 0) {
+        if (cq_region_allocator->allocate(cq_region_allocator->context,
+                                          sizeof(struct mlx5gda_cq_dbr),
+                                          &cq->dbr_region) != 0) {
             perror("Failed to allocate CQ DBR control region");
             goto fail;
         }
@@ -196,16 +194,15 @@ struct mlx5gda_cq* mlx5gda_create_cq(
         cq_offset = 0;
         dbr_offset = 0;
     } else {
-        cq_offset = memheap_aligned_alloc(ctrl_buf_heap,
-                                          num_cqe * sizeof(struct mlx5_cqe64),
-                                          (size_t)1 << MLX5_ADAPTER_PAGE_SHIFT);
-        if (cq_offset == -1) {
+        cq_offset =
+            memheap_aligned_alloc(cq_heap, num_cqe * sizeof(struct mlx5_cqe64),
+                                  (size_t)1 << MLX5_ADAPTER_PAGE_SHIFT);
+        if (cq_offset == (size_t)-1) {
             perror("Failed to allocate CQ memory");
             goto fail;
         }
-        dbr_offset =
-            memheap_alloc(ctrl_buf_heap, sizeof(struct mlx5gda_cq_dbr));
-        if (dbr_offset == -1) {
+        dbr_offset = memheap_alloc(cq_heap, sizeof(struct mlx5gda_cq_dbr));
+        if (dbr_offset == (size_t)-1) {
             perror("Failed to allocate CQ DBR memory");
             goto fail;
         }
@@ -271,7 +268,12 @@ struct mlx5gda_cq* mlx5gda_create_cq(
 
     cq->cq_offset = cq_offset;
     cq->dbr_offset = dbr_offset;
+    cq->dev_base = cq_buf_dev ? cq_buf_dev : ctrl_buf;
+    cq->heap = cq_heap;
     cq->cq_buf = static_cast<char*>(cq_buf) + cq_offset;
+    cq->dev_cq_buf = split_regions
+                         ? cq->cq_buf
+                         : static_cast<char*>(cq->dev_base) + cq_offset;
     cq->dbr = static_cast<char*>(dbr) + dbr_offset;
     cq->cqe = num_cqe;
     cq->cqn = cqn;
@@ -287,14 +289,14 @@ struct mlx5gda_cq* mlx5gda_create_cq(
         free(cq);
     }
     if (!split_regions) {
-        if (cq_offset != -1) memheap_free(ctrl_buf_heap, cq_offset);
-        if (dbr_offset != -1) memheap_free(ctrl_buf_heap, dbr_offset);
+        if (cq_offset != (size_t)-1) memheap_free(cq_heap, cq_offset);
+        if (dbr_offset != (size_t)-1) memheap_free(cq_heap, dbr_offset);
     }
     errno = saved_errno;
     return NULL;
 }
 
-void mlx5gda_destroy_cq(struct memheap* ctrl_buf_heap, struct mlx5gda_cq* cq) {
+void mlx5gda_destroy_cq(struct mlx5gda_cq* cq) {
     if (!cq) return;
     if (cq->mcq) {
         mlx5dv_devx_obj_destroy(cq->mcq);
@@ -306,17 +308,18 @@ void mlx5gda_destroy_cq(struct memheap* ctrl_buf_heap, struct mlx5gda_cq* cq) {
         release_control_region(&cq->region_allocator, &cq->dbr_region);
         release_control_region(&cq->region_allocator, &cq->cq_region);
     } else {
-        memheap_free(ctrl_buf_heap, cq->cq_offset);
-        memheap_free(ctrl_buf_heap, cq->dbr_offset);
+        memheap_free(cq->heap, cq->cq_offset);
+        memheap_free(cq->heap, cq->dbr_offset);
     }
     free(cq);
 }
 
 struct mlx5gda_qp* mlx5gda_create_rc_qp(
-    struct mlx5dv_pd mpd, void* ctrl_buf,
-    struct mlx5dv_devx_umem* ctrl_buf_umem, struct memheap* ctrl_buf_heap,
-    struct ibv_pd* pd, int wqe, uint8_t port_num, cudaStream_t stream,
-    const struct mlx5gda_control_region_allocator* region_allocator) {
+    struct mlx5dv_pd mpd, const struct mlx5gda_control_buffer* ctrl,
+    const struct mlx5gda_control_buffer* cq, struct ibv_pd* pd, int wqe,
+    uint8_t port_num, cudaStream_t stream,
+    const struct mlx5gda_control_region_allocator* cq_region_allocator,
+    const struct mlx5gda_control_region_allocator* qp_region_allocator) {
     mlx5gda_reset_create_qp_failure();
 
     struct mlx5gda_qp* qp = NULL;
@@ -325,17 +328,17 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
     struct mlx5dv_devx_obj* mlx5_qp = NULL;
     size_t wq_offset = -1;
     size_t dbr_offset = -1;
-    void* wq = ctrl_buf;
-    void* dbr = ctrl_buf;
-    struct mlx5dv_devx_umem* wq_umem = ctrl_buf_umem;
-    struct mlx5dv_devx_umem* dbr_umem = ctrl_buf_umem;
-    const bool split_regions = uses_control_regions(region_allocator);
+    void* wq = ctrl->addr;
+    void* dbr = ctrl->addr;
+    struct mlx5dv_devx_umem* wq_umem = ctrl->umem;
+    struct mlx5dv_devx_umem* dbr_umem = ctrl->umem;
+    const bool split_regions = uses_control_regions(qp_region_allocator);
 
     struct ibv_context* ctx = pd->context;
     void* qp_context = NULL;
     void* cap = NULL;
     uint32_t cqe_version = 0;
-    bool ctrl_host = !split_regions && is_host_control_buffer(ctrl_buf);
+    bool ctrl_host = !split_regions && is_host_control_buffer(ctrl->addr);
 
     if (wqe <= 0) {
         errno = EINVAL;
@@ -354,7 +357,7 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
         perror("Failed to allocate QP memory");
         goto fail;
     }
-    if (split_regions) qp->region_allocator = *region_allocator;
+    if (split_regions) qp->region_allocator = *qp_region_allocator;
 
     qp->port_num = port_num;
     if (ibv_query_port(ctx, port_num, &qp->port_attr) != 0) {
@@ -382,8 +385,9 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
     }
 
     // Create send_cq on GPU memory.
-    send_cq = mlx5gda_create_cq(ctrl_buf, ctrl_buf_umem, ctrl_buf_heap, pd, wqe,
-                                stream, region_allocator);
+    send_cq = mlx5gda_create_cq(ctrl->addr, ctrl->umem, ctrl->heap, pd, wqe,
+                                stream, cq->addr, cq->dev_addr, cq->umem,
+                                cq->heap, cq_region_allocator);
     if (send_cq == NULL) {
         perror("mlx5gda_create_cq failed");
         goto fail;
@@ -394,17 +398,19 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
         perror("Failed to create UAR");
         goto fail;
     }
+    if (map_uar_for_device(uar, qp) != 0) goto fail;
 
     if (split_regions) {
-        if (region_allocator->allocate(region_allocator->context,
-                                       num_wqebb * sizeof(struct mlx5gda_wqebb),
-                                       &qp->wq_region) != 0) {
+        if (qp_region_allocator->allocate(
+                qp_region_allocator->context,
+                num_wqebb * sizeof(struct mlx5gda_wqebb),
+                &qp->wq_region) != 0) {
             perror("Failed to allocate WQ control region");
             goto fail;
         }
-        if (region_allocator->allocate(region_allocator->context,
-                                       sizeof(struct mlx5gda_wq_dbr),
-                                       &qp->dbr_region) != 0) {
+        if (qp_region_allocator->allocate(qp_region_allocator->context,
+                                          sizeof(struct mlx5gda_wq_dbr),
+                                          &qp->dbr_region) != 0) {
             perror("Failed to allocate QP DBR control region");
             goto fail;
         }
@@ -416,16 +422,15 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
         dbr_offset = 0;
     } else {
         wq_offset = memheap_aligned_alloc(
-            ctrl_buf_heap, num_wqebb * sizeof(struct mlx5gda_wqebb),
+            ctrl->heap, num_wqebb * sizeof(struct mlx5gda_wqebb),
             (size_t)1 << MLX5_ADAPTER_PAGE_SHIFT);
-        if (wq_offset == -1) {
+        if (wq_offset == (size_t)-1) {
             perror("Failed to allocate WQ memory");
             goto fail;
         }
 
-        dbr_offset =
-            memheap_alloc(ctrl_buf_heap, sizeof(struct mlx5gda_wq_dbr));
-        if (dbr_offset == -1) {
+        dbr_offset = memheap_alloc(ctrl->heap, sizeof(struct mlx5gda_wq_dbr));
+        if (dbr_offset == (size_t)-1) {
             perror("Failed to allocate DBR memory");
             goto fail;
         }
@@ -496,8 +501,14 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
     qp->num_wqebb = num_wqebb;
     qp->wq_offset = wq_offset;
     qp->dbr_offset = dbr_offset;
+    qp->wq_heap = ctrl->heap;
     qp->wq = static_cast<char*>(wq) + wq_offset;
     qp->dbr = static_cast<char*>(dbr) + dbr_offset;
+    qp->dev_wq =
+        split_regions ? qp->wq : static_cast<char*>(ctrl->dev_addr) + wq_offset;
+    qp->dev_dbr = split_regions
+                      ? qp->dbr
+                      : static_cast<char*>(ctrl->dev_addr) + dbr_offset;
     return qp;
 
 fail:
@@ -506,10 +517,11 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
         mlx5dv_devx_obj_destroy(mlx5_qp);
     }
     if (uar) {
+        if (qp) unmap_uar_for_device(qp);
         destroy_uar(uar);
     }
     if (send_cq) {
-        mlx5gda_destroy_cq(ctrl_buf_heap, send_cq);
+        mlx5gda_destroy_cq(send_cq);
     }
     if (qp) {
         release_control_region(&qp->region_allocator, &qp->dbr_region);
@@ -518,35 +530,36 @@ struct mlx5gda_qp* mlx5gda_create_rc_qp(
     if (qp) {
         free(qp);
     }
-    if (!split_regions && wq_offset != -1) {
-        memheap_free(ctrl_buf_heap, wq_offset);
+    if (!split_regions && wq_offset != (size_t)-1) {
+        memheap_free(ctrl->heap, wq_offset);
     }
-    if (!split_regions && dbr_offset != -1) {
-        memheap_free(ctrl_buf_heap, dbr_offset);
+    if (!split_regions && dbr_offset != (size_t)-1) {
+        memheap_free(ctrl->heap, dbr_offset);
     }
     errno = saved_errno;
     return NULL;
 }
 
-void mlx5gda_destroy_qp(struct memheap* ctrl_buf_heap, struct mlx5gda_qp* qp) {
+void mlx5gda_destroy_qp(struct mlx5gda_qp* qp) {
     if (qp->mqp) {
         mlx5dv_devx_obj_destroy(qp->mqp);
     }
     if (qp->uar) {
+        unmap_uar_for_device(qp);
         destroy_uar(qp->uar);
     }
     if (qp->send_cq) {
-        mlx5gda_destroy_cq(ctrl_buf_heap, qp->send_cq);
+        mlx5gda_destroy_cq(qp->send_cq);
     }
     if (uses_control_regions(&qp->region_allocator)) {
         release_control_region(&qp->region_allocator, &qp->dbr_region);
         release_control_region(&qp->region_allocator, &qp->wq_region);
     } else {
-        if (qp->wq_offset != -1) {
-            memheap_free(ctrl_buf_heap, qp->wq_offset);
+        if (qp->wq_offset != (size_t)-1) {
+            memheap_free(qp->wq_heap, qp->wq_offset);
         }
-        if (qp->dbr_offset != -1) {
-            memheap_free(ctrl_buf_heap, qp->dbr_offset);
+        if (qp->dbr_offset != (size_t)-1) {
+            memheap_free(qp->wq_heap, qp->dbr_offset);
         }
     }
     if (qp) {
diff --git a/mooncake-transfer-engine/src/transport/device/nccl_device_transport.cpp b/mooncake-transfer-engine/src/transport/device/nccl_device_transport.cpp
index 62638780d6..fe50c858fa 100644
--- a/mooncake-transfer-engine/src/transport/device/nccl_device_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/device/nccl_device_transport.cpp
@@ -76,6 +76,36 @@ const char* ginBackendName(NcclGinBackend backend) {
     }
 }
 
+bool validGinConnectionType(NcclGinConnectionType type) {
+    return type == NcclGinConnectionType::kNone ||
+           type == NcclGinConnectionType::kFull ||
+           type == NcclGinConnectionType::kRail;
+}
+
+ncclGinConnectionType_t toNativeGinConnectionType(NcclGinConnectionType type) {
+    switch (type) {
+        case NcclGinConnectionType::kFull:
+            return NCCL_GIN_CONNECTION_FULL;
+        case NcclGinConnectionType::kRail:
+            return NCCL_GIN_CONNECTION_RAIL;
+        case NcclGinConnectionType::kNone:
+        default:
+            return NCCL_GIN_CONNECTION_NONE;
+    }
+}
+
+const char* ginConnectionTypeName(NcclGinConnectionType type) {
+    switch (type) {
+        case NcclGinConnectionType::kFull:
+            return "full";
+        case NcclGinConnectionType::kRail:
+            return "rail";
+        case NcclGinConnectionType::kNone:
+        default:
+            return "none";
+    }
+}
+
 bool decodeUniqueId(const std::vector<int32_t>& encoded, ncclUniqueId* id) {
     const size_t words =
         (sizeof(ncclUniqueId) + sizeof(int32_t) - 1) / sizeof(int32_t);
@@ -88,7 +118,7 @@ bool decodeUniqueId(const std::vector<int32_t>& encoded, ncclUniqueId* id) {
 
 class NcclDeviceTransportImpl final : public NcclTransport {
    public:
-    ~NcclDeviceTransportImpl() override { shutdown(); }
+    ~NcclDeviceTransportImpl() override { abort(); }
 
     std::vector<int32_t> createUniqueId() override {
         ncclUniqueId id{};
@@ -112,8 +142,12 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         if (config.num_ranks <= 0 || config.rank < 0 ||
             config.rank >= config.num_ranks || config.gin_context_count < 0 ||
             (config.enable_gin && config.gin_context_count == 0) ||
+            (config.enable_gin &&
+             config.gin_connection_type == NcclGinConnectionType::kNone) ||
+            !validGinConnectionType(config.gin_connection_type) ||
             config.gin_context_count > std::numeric_limits<int>::max() / 2 ||
-            config.lsa_barrier_count < 0) {
+            config.gin_queue_depth < 0 || config.gin_signal_count < 0 ||
+            config.gin_traffic_class < -1 || config.lsa_barrier_count < 0) {
             LOG(ERROR) << "[Device NCCL] invalid communicator configuration";
             return -1;
         }
@@ -153,28 +187,49 @@ class NcclDeviceTransportImpl final : public NcclTransport {
             return -1;
         }
 
-        ncclCommProperties_t comm_properties = NCCL_COMM_PROPERTIES_INITIALIZER;
-        if (reportNcclError(ncclCommQueryProperties(comm_, &comm_properties),
-                            "ncclCommQueryProperties") != 0) {
+        // Establish the smallest possible rank-wide status path immediately
+        // after communicator creation. While this CUDA/NCCL control path stays
+        // healthy, subsequent capability decisions can be made uniformly.
+        if (reportCudaError(cudaStreamCreateWithFlags(&control_stream_,
+                                                      cudaStreamNonBlocking),
+                            "cudaStreamCreateWithFlags(control)") != 0 ||
+            reportCudaError(
+                cudaMalloc(reinterpret_cast<void**>(&collective_status_),
+                           sizeof(int)),
+                "cudaMalloc(collective status)") != 0) {
             abortPartialInitialization();
             return -1;
         }
-        if (!comm_properties.deviceApiSupport) {
+
+        ncclCommProperties_t comm_properties = NCCL_COMM_PROPERTIES_INITIALIZER;
+        bool local_capabilities_valid =
+            reportNcclError(ncclCommQueryProperties(comm_, &comm_properties),
+                            "ncclCommQueryProperties") == 0;
+        if (local_capabilities_valid && !comm_properties.deviceApiSupport) {
             LOG(ERROR) << "[Device NCCL] communicator does not support the "
                           "device API";
-            abortPartialInitialization();
-            return -1;
+            local_capabilities_valid = false;
         }
-        if (config.require_lsa_multimem && !comm_properties.multimemSupport) {
+        if (local_capabilities_valid && config.require_lsa_multimem &&
+            !comm_properties.multimemSupport) {
             LOG(ERROR) << "[Device NCCL] LSA multimem was required but is "
                           "not supported";
-            abortPartialInitialization();
-            return -1;
-        }
-        if (config.enable_gin &&
-            comm_properties.ginType == NCCL_GIN_TYPE_NONE) {
-            LOG(ERROR) << "[Device NCCL] full GIN connectivity was requested "
-                          "but GIN is unavailable";
+            local_capabilities_valid = false;
+        }
+        const ncclGinType_t selected_gin_type =
+            config.gin_connection_type == NcclGinConnectionType::kRail
+                ? comm_properties.railedGinType
+                : comm_properties.ginType;
+        if (local_capabilities_valid && config.enable_gin &&
+            selected_gin_type == NCCL_GIN_TYPE_NONE) {
+            LOG(ERROR) << "[Device NCCL] "
+                       << ginConnectionTypeName(config.gin_connection_type)
+                       << " GIN connectivity was requested but is unavailable";
+            local_capabilities_valid = false;
+        }
+        if (!collectiveAllSucceeded(local_capabilities_valid)) {
+            LOG(ERROR) << "[Device NCCL] required Device API capabilities are "
+                          "unavailable on one or more ranks";
             abortPartialInitialization();
             return -1;
         }
@@ -185,49 +240,64 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         requirements.lsaBarrierCount = config.lsa_barrier_count;
         requirements.ginContextCount =
             config.enable_gin ? config.gin_context_count : 0;
-        requirements.ginConnectionType = config.enable_gin
-                                             ? NCCL_GIN_CONNECTION_FULL
-                                             : NCCL_GIN_CONNECTION_NONE;
+        requirements.ginConnectionType =
+            config.enable_gin
+                ? toNativeGinConnectionType(config.gin_connection_type)
+                : NCCL_GIN_CONNECTION_NONE;
         requirements.ginExclusiveContexts =
             config.enable_gin && config.gin_exclusive_contexts;
-
-        ncclResult_t start_result = ncclGroupStart();
-        ncclResult_t create_result = ncclSuccess;
-        ncclResult_t end_result = ncclSuccess;
-        if (start_result == ncclSuccess) {
-            create_result = ncclDevCommCreate(comm_, &requirements, &dev_comm_);
-            end_result = ncclGroupEnd();
-        }
-        if (reportNcclError(start_result, "ncclGroupStart") != 0 ||
-            reportNcclError(create_result, "ncclDevCommCreate") != 0 ||
-            reportNcclError(end_result, "ncclGroupEnd") != 0) {
+        requirements.ginQueueDepth =
+            config.enable_gin ? config.gin_queue_depth : 0;
+        requirements.ginSignalCount =
+            config.enable_gin ? config.gin_signal_count : 0;
+        if (config.enable_gin && config.gin_traffic_class >= 0) {
+            requirements.ginTrafficClass = config.gin_traffic_class;
+        }
+
+        const bool local_dev_comm_valid =
+            reportNcclError(ncclDevCommCreate(comm_, &requirements, &dev_comm_),
+                            "ncclDevCommCreate") == 0;
+        // Record rank-local ownership before group agreement so the abort path
+        // destroys a successful local create even if another rank failed.
+        dev_comm_created_ = local_dev_comm_valid;
+        if (!collectiveAllSucceeded(local_dev_comm_valid)) {
+            LOG(ERROR) << "[Device NCCL] device communicator creation failed "
+                          "on one or more ranks";
             abortPartialInitialization();
             return -1;
         }
-        dev_comm_created_ = true;
 
-        if (config.enable_gin && (dev_comm_.ginConnectionCount == 0 ||
-                                  dev_comm_.ginContextCount == 0)) {
+        const bool local_gin_resources_valid =
+            !config.enable_gin ||
+            (dev_comm_.ginConnectionCount > 0 && dev_comm_.ginContextCount > 0);
+        if (!local_gin_resources_valid) {
             LOG(ERROR) << "[Device NCCL] communicator did not provide the "
-                          "requested full GIN resources";
+                       << "requested "
+                       << ginConnectionTypeName(config.gin_connection_type)
+                       << " GIN resources";
+        }
+        if (!collectiveAllSucceeded(local_gin_resources_valid)) {
+            LOG(ERROR) << "[Device NCCL] requested GIN resources are missing "
+                          "on one or more ranks";
             abortPartialInitialization();
             return -1;
         }
 
-        if (reportCudaError(cudaMalloc(reinterpret_cast<void**>(&device_comm_),
+        bool local_device_comm_ready =
+            reportCudaError(cudaMalloc(reinterpret_cast<void**>(&device_comm_),
                                        sizeof(dev_comm_)),
-                            "cudaMalloc(device communicator)") != 0 ||
-            reportCudaError(
-                cudaMemcpy(device_comm_, &dev_comm_, sizeof(dev_comm_),
-                           cudaMemcpyHostToDevice),
-                "cudaMemcpy(device communicator)") != 0 ||
-            reportCudaError(cudaStreamCreateWithFlags(&control_stream_,
-                                                      cudaStreamNonBlocking),
-                            "cudaStreamCreateWithFlags(control)") != 0 ||
-            reportCudaError(
-                cudaMalloc(reinterpret_cast<void**>(&collective_status_),
-                           sizeof(int)),
-                "cudaMalloc(collective status)") != 0) {
+                            "cudaMalloc(device communicator)") == 0;
+        if (local_device_comm_ready) {
+            local_device_comm_ready =
+                reportCudaError(
+                    cudaMemcpy(device_comm_, &dev_comm_, sizeof(dev_comm_),
+                               cudaMemcpyHostToDevice),
+                    "cudaMemcpy(device communicator)") == 0;
+        }
+
+        if (!collectiveAllSucceeded(local_device_comm_ready)) {
+            LOG(ERROR) << "[Device NCCL] device communicator setup failed on "
+                          "one or more ranks";
             abortPartialInitialization();
             return -1;
         }
@@ -240,9 +310,16 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         properties_.multimem_supported = comm_properties.multimemSupport;
         properties_.lsa_multimem_enabled = config.require_lsa_multimem;
         properties_.lsa_team_count = comm_properties.nLsaTeams;
+        lsa_topology_.rank = dev_comm_.lsaRank;
+        lsa_topology_.size = dev_comm_.lsaSize;
+        lsa_topology_.first_rank = dev_comm_.rank - dev_comm_.lsaRank;
         properties_.lsa_barrier_count = config.lsa_barrier_count;
         properties_.gin_enabled = config.enable_gin;
-        properties_.gin_backend = toGinBackend(comm_properties.ginType);
+        properties_.gin_connection_type = config.enable_gin
+                                              ? config.gin_connection_type
+                                              : NcclGinConnectionType::kNone;
+        properties_.gin_backend = toGinBackend(
+            config.enable_gin ? selected_gin_type : NCCL_GIN_TYPE_NONE);
         properties_.gin_connection_count = dev_comm_.ginConnectionCount;
         properties_.gin_context_count =
             static_cast<int>(dev_comm_.ginContextCount);
@@ -252,14 +329,28 @@ class NcclDeviceTransportImpl final : public NcclTransport {
                   << "/" << properties_.num_ranks
                   << " cuda_device=" << properties_.cuda_device
                   << " lsa_teams=" << properties_.lsa_team_count
+                  << " lsa_rank=" << lsa_topology_.rank << "/"
+                  << lsa_topology_.size
+                  << " lsa_first_rank=" << lsa_topology_.first_rank
                   << " multimem=" << properties_.lsa_multimem_enabled
                   << " lsa_barriers=" << properties_.lsa_barrier_count
                   << " gin_backend=" << ginBackendName(properties_.gin_backend)
+                  << " gin_connection_type="
+                  << ginConnectionTypeName(properties_.gin_connection_type)
                   << " gin_connections=" << properties_.gin_connection_count
                   << " gin_contexts=" << properties_.gin_context_count;
         return 0;
     }
 
+    bool allRanksSucceeded(bool local_success) override {
+        if (!initialized_) {
+            LOG(ERROR) << "[Device NCCL] collective status agreement requires "
+                          "initialization";
+            return false;
+        }
+        return collectiveAllSucceeded(local_success);
+    }
+
     void* allocateBuffer(size_t bytes) override {
         if (bytes == 0) {
             LOG(ERROR) << "[Device NCCL] cannot allocate a zero-sized buffer";
@@ -312,9 +403,11 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         }
 
         ncclWindow_t window = nullptr;
-        if (reportNcclError(ncclCommWindowRegister(comm_, ptr, bytes, &window,
-                                                   NCCL_WIN_COLL_SYMMETRIC),
-                            "ncclCommWindowRegister") != 0) {
+        if (reportNcclError(
+                ncclCommWindowRegister(
+                    comm_, ptr, bytes, &window,
+                    NCCL_WIN_COLL_SYMMETRIC | NCCL_WIN_STRICT_ORDERING),
+                "ncclCommWindowRegister") != 0) {
             return -1;
         }
 
@@ -357,17 +450,29 @@ class NcclDeviceTransportImpl final : public NcclTransport {
 
         *ptr = nullptr;
         void* local_ptr = allocateBuffer(bytes);
-        const bool all_allocated = collectiveAllSucceeded(local_ptr != nullptr);
+        const bool all_allocated = allRanksSucceeded(local_ptr != nullptr);
         if (!all_allocated) {
             if (local_ptr) freeBuffer(local_ptr);
             return -1;
         }
 
+        // A GIN VA-signal address must not be accessed through ordinary CUDA
+        // loads or stores after its window has been registered. Initialize the
+        // entire allocation while it is still plain NCCL memory so callers can
+        // safely reserve any subrange for GIN-only signals.
+        const int zero_status = reportCudaError(
+            cudaMemsetAsync(local_ptr, 0, bytes, control_stream_),
+            "cudaMemsetAsync(collective buffer)");
+        const bool all_zeroed = allRanksSucceeded(zero_status == 0);
+        if (!all_zeroed) {
+            freeBuffer(local_ptr);
+            return -1;
+        }
+
         NcclBufferRegistration local_registration;
         const int register_status =
             registerBuffer(local_ptr, bytes, &local_registration);
-        const bool all_registered =
-            collectiveAllSucceeded(register_status == 0);
+        const bool all_registered = allRanksSucceeded(register_status == 0);
         if (!all_registered) {
             if (local_registration.valid())
                 deregisterBuffer(&local_registration);
@@ -392,17 +497,29 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         }
 
         context.native_comm_ = device_comm_;
+        static_assert(
+            sizeof(dev_comm_) <= NcclDeviceContext::kNativeCommCapacity,
+            "Increase embedded NCCL device communicator capacity");
+        static_assert(
+            alignof(ncclDevComm_t) <= NcclDeviceContext::kNativeCommAlignment,
+            "Update embedded NCCL device communicator alignment");
+        std::memcpy(context.native_comm_storage_, &dev_comm_,
+                    sizeof(dev_comm_));
         context.native_window_ = it->second.window;
         context.local_base_ = it->second.ptr;
         context.rank_ = properties_.rank;
         context.gin_context_count_ = properties_.gin_context_count;
         context.gin_enabled_ = properties_.gin_enabled;
+        context.gin_connections_railed_ =
+            properties_.gin_connection_type == NcclGinConnectionType::kRail;
         context.lsa_multimem_enabled_ = properties_.lsa_multimem_enabled;
         return context;
     }
 
     NcclTransportProperties properties() const override { return properties_; }
 
+    NcclLsaTopology lsaTopology() const override { return lsa_topology_; }
+
     bool initialized() const override { return initialized_; }
 
     int shutdown() override {
@@ -463,10 +580,79 @@ class NcclDeviceTransportImpl final : public NcclTransport {
             }
             comm_ = nullptr;
         }
+        initialized_ = false;
+        next_registration_id_ = 1;
+        properties_ = {};
+        lsa_topology_ = {};
+        return status;
+    }
+
+    int abort() override {
+        int status = 0;
+
+        // Window and device-communicator resources are local to this rank, but
+        // still require the host communicator handle. Release them before
+        // aborting that handle. Errors are best effort here: an obsolete
+        // generation must never keep recovery waiting on failed peers.
+        if (comm_) {
+            for (const auto& entry : registrations_) {
+                if (reportNcclError(
+                        ncclCommWindowDeregister(comm_, entry.second.window),
+                        "ncclCommWindowDeregister(abort)") != 0) {
+                    status = -1;
+                }
+            }
+        }
+        registrations_.clear();
+
+        if (dev_comm_created_) {
+            if (reportNcclError(ncclDevCommDestroy(comm_, &dev_comm_),
+                                "ncclDevCommDestroy(abort)") != 0) {
+                status = -1;
+            }
+            dev_comm_created_ = false;
+            dev_comm_ = {};
+        }
+        if (comm_) {
+            if (reportNcclError(ncclCommAbort(comm_), "ncclCommAbort") != 0) {
+                status = -1;
+            }
+            comm_ = nullptr;
+        }
+
+        for (void* ptr : allocations_) {
+            if (reportNcclError(ncclMemFree(ptr), "ncclMemFree(abort)") != 0) {
+                status = -1;
+            }
+        }
+        allocations_.clear();
+
+        if (collective_status_) {
+            if (reportCudaError(cudaFree(collective_status_),
+                                "cudaFree(collective status, abort)") != 0) {
+                status = -1;
+            }
+            collective_status_ = nullptr;
+        }
+        if (control_stream_) {
+            if (reportCudaError(cudaStreamDestroy(control_stream_),
+                                "cudaStreamDestroy(control, abort)") != 0) {
+                status = -1;
+            }
+            control_stream_ = nullptr;
+        }
+        if (device_comm_) {
+            if (reportCudaError(cudaFree(device_comm_),
+                                "cudaFree(device communicator, abort)") != 0) {
+                status = -1;
+            }
+            device_comm_ = nullptr;
+        }
 
         initialized_ = false;
         next_registration_id_ = 1;
         properties_ = {};
+        lsa_topology_ = {};
         return status;
     }
 
@@ -498,29 +684,7 @@ class NcclDeviceTransportImpl final : public NcclTransport {
         return value != 0;
     }
 
-    void abortPartialInitialization() {
-        if (collective_status_) {
-            cudaFree(collective_status_);
-            collective_status_ = nullptr;
-        }
-        if (control_stream_) {
-            cudaStreamDestroy(control_stream_);
-            control_stream_ = nullptr;
-        }
-        if (device_comm_) {
-            cudaFree(device_comm_);
-            device_comm_ = nullptr;
-        }
-        if (dev_comm_created_) {
-            ncclDevCommDestroy(comm_, &dev_comm_);
-            dev_comm_created_ = false;
-            dev_comm_ = {};
-        }
-        if (comm_) {
-            ncclCommAbort(comm_);
-            comm_ = nullptr;
-        }
-    }
+    void abortPartialInitialization() { (void)abort(); }
 
     ncclComm_t comm_ = nullptr;
     ncclDevComm_t dev_comm_{};
@@ -535,6 +699,7 @@ class NcclDeviceTransportImpl final : public NcclTransport {
     std::unordered_map<uint64_t, WindowRecord> registrations_;
     std::unordered_set<void*> allocations_;
     NcclTransportProperties properties_;
+    NcclLsaTopology lsa_topology_;
 };
 
 std::unique_ptr<NcclTransport> createNcclDeviceTransport() {
diff --git a/mooncake-transfer-engine/src/transport/device/p2p_device_transport.cpp b/mooncake-transfer-engine/src/transport/device/p2p_device_transport.cpp
index 31661e1371..b9dec3c0cb 100644
--- a/mooncake-transfer-engine/src/transport/device/p2p_device_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/device/p2p_device_transport.cpp
@@ -30,6 +30,7 @@
 #include <vector>
 
 #include "cuda_alike.h"
+#include "common.h"
 
 namespace mooncake {
 namespace device {
diff --git a/mooncake-transfer-engine/src/transport/efa_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/efa_transport/CMakeLists.txt
index ff32f6ebee..6055690176 100644
--- a/mooncake-transfer-engine/src/transport/efa_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/efa_transport/CMakeLists.txt
@@ -2,13 +2,16 @@ file(GLOB EFA_SOURCES "*.cpp")
 add_library(efa_transport OBJECT ${EFA_SOURCES})
 
 # Link against libfabric (fabric) instead of ibverbs for AWS EFA
-target_link_libraries(efa_transport PRIVATE fabric glog::glog)
+target_link_libraries(
+  efa_transport
+  PUBLIC glog::glog gflags::gflags
+  PRIVATE fabric)
 
-target_include_directories(efa_transport PRIVATE
+target_include_directories(
+  efa_transport
+  PRIVATE
     ${CMAKE_SOURCE_DIR}/mooncake-transfer-engine/include
     ${CMAKE_SOURCE_DIR}/mooncake-transfer-engine/include/transport/efa_transport
-    ${CMAKE_SOURCE_DIR}/mooncake-common/include
-    ${LIBFABRIC_INCLUDE_DIR}
-)
+    ${CMAKE_SOURCE_DIR}/mooncake-common/include ${LIBFABRIC_INCLUDE_DIR})
 
 # libfabric library path is set globally via common.cmake (LIBFABRIC_LIB_DIR)
diff --git a/mooncake-transfer-engine/src/transport/efa_transport/efa_context.cpp b/mooncake-transfer-engine/src/transport/efa_transport/efa_context.cpp
index c06a202240..fd323c2368 100644
--- a/mooncake-transfer-engine/src/transport/efa_transport/efa_context.cpp
+++ b/mooncake-transfer-engine/src/transport/efa_transport/efa_context.cpp
@@ -408,63 +408,109 @@ int EfaContext::deconstruct() {
 }
 
 #if defined(USE_CUDA)
-// A silent failure here resurfaces as the provider's opaque "Operation not
-// supported" from fi_mr_regattr(), which is the attribution problem this whole
-// helper exists to remove -- so name the driver call that actually failed.
+// A silent failure here resurfaces as an opaque provider error, so name the
+// driver call that actually failed.
 static void logCudaFailure(const char* call, CUresult ret, int device_ordinal) {
     const char* err = nullptr;
     cuGetErrorString(ret, &err);
-    LOG(WARNING) << "EFA: " << call << " failed for CUDA device "
-                 << device_ordinal << ": " << (err ? err : "unknown") << " ("
-                 << ret
-                 << "); GPU memory registration may fail with a bare"
-                    " \"Operation not supported\"";
+    LOG(WARNING) << "EFA: " << call << " failed"
+                 << (device_ordinal >= 0
+                         ? " for CUDA device " + std::to_string(device_ordinal)
+                         : "")
+                 << ": " << (err ? err : "unknown") << " (" << ret
+                 << "); GPU memory registration or a GPU-aware copy may fail"
+                    " with a bare \"Operation not supported\"";
 }
 
-// Make `device_ordinal`'s primary context current on the calling thread, unless
-// a context for that same device already is.
-//
-// Why a context is needed at all: fi_mr_regattr() on FI_HMEM_CUDA memory
-// reaches libfabric's cuda_get_dmabuf_fd(), which calls the driver API
-// cuMemGetHandleForAddressRange() and does no context management of its own.
-// The export also runs against the CURRENT context, so a context belonging to
-// another device is no better than none -- both end up as a bare "Operation not
-// supported" from the provider.
-//
-// Who arrives here without the right context: registerLocalMemoryBatch() runs
-// one std::async(std::launch::async) per buffer and registerLocalMemory() can
-// fan out one std::thread per NIC, so a registering thread may have touched no
-// CUDA API at all; and since std::async may reuse threads, one thread can
-// register buffers on several devices in turn.
-//
-// cuDevicePrimaryCtxRetain() returns the same primary context the CUDA runtime
-// uses, so this attaches to the process's existing context rather than creating
-// another.  The retain is intentionally not released: the primary context
-// outlives every registration, and dropping the last reference here would tear
-// down the context the rest of the process is using.
-static void bindCudaContextIfNeeded(int device_ordinal) {
-    CUdevice want;
-    CUresult ret = cuDeviceGet(&want, device_ordinal);
-    if (ret != CUDA_SUCCESS) {
-        logCudaFailure("cuDeviceGet", ret, device_ordinal);
-        return;
+// RAII guard: temporarily make a device's primary context current, then restore
+// the caller's original context and release the retain on destruction.
+class ScopedCudaContext {
+   public:
+    ScopedCudaContext() {
+        CUresult ret = cuCtxGetCurrent(&previous_);
+        if (ret != CUDA_SUCCESS) {
+            logCudaFailure("cuCtxGetCurrent", ret, -1);
+            return;
+        }
+        valid_ = true;
     }
 
-    CUcontext cur = nullptr;
-    CUdevice cur_dev;
-    if (cuCtxGetCurrent(&cur) == CUDA_SUCCESS && cur != nullptr &&
-        cuCtxGetDevice(&cur_dev) == CUDA_SUCCESS && cur_dev == want)
-        return;
-
-    CUcontext primary = nullptr;
-    ret = cuDevicePrimaryCtxRetain(&primary, want);
-    if (ret != CUDA_SUCCESS) {
-        logCudaFailure("cuDevicePrimaryCtxRetain", ret, device_ordinal);
-        return;
+    ScopedCudaContext(const ScopedCudaContext&) = delete;
+    ScopedCudaContext& operator=(const ScopedCudaContext&) = delete;
+
+    ~ScopedCudaContext() {
+        if (!restored_) restore();
+    }
+
+    bool valid() const { return valid_; }
+
+    bool bind(int device_ordinal) {
+        if (!valid_ || retained_) return false;
+        device_ordinal_ = device_ordinal;
+
+        CUresult ret = cuDeviceGet(&device_, device_ordinal_);
+        if (ret != CUDA_SUCCESS) {
+            logCudaFailure("cuDeviceGet", ret, device_ordinal_);
+            return false;
+        }
+
+        CUcontext primary = nullptr;
+        ret = cuDevicePrimaryCtxRetain(&primary, device_);
+        if (ret != CUDA_SUCCESS) {
+            logCudaFailure("cuDevicePrimaryCtxRetain", ret, device_ordinal_);
+            return false;
+        }
+        retained_ = true;
+
+        ret = cuCtxSetCurrent(primary);
+        if (ret != CUDA_SUCCESS) {
+            logCudaFailure("cuCtxSetCurrent", ret, device_ordinal_);
+            return false;
+        }
+        return true;
     }
-    ret = cuCtxSetCurrent(primary);
-    if (ret != CUDA_SUCCESS)
-        logCudaFailure("cuCtxSetCurrent", ret, device_ordinal);
+
+    bool restore() {
+        if (restored_) return restore_ok_;
+        restored_ = true;
+        if (!valid_) return false;
+
+        CUresult ret = cuCtxSetCurrent(previous_);
+        restore_ok_ = ret == CUDA_SUCCESS;
+        if (!restore_ok_) {
+            logCudaFailure("cuCtxSetCurrent (restore)", ret, device_ordinal_);
+        }
+
+        if (retained_) {
+            ret = cuDevicePrimaryCtxRelease(device_);
+            if (ret != CUDA_SUCCESS) {
+                logCudaFailure("cuDevicePrimaryCtxRelease", ret,
+                               device_ordinal_);
+                restore_ok_ = false;
+            }
+        }
+        return restore_ok_;
+    }
+
+   private:
+    CUcontext previous_ = nullptr;
+    CUdevice device_ = 0;
+    int device_ordinal_ = -1;
+    bool valid_ = false;
+    bool retained_ = false;
+    bool restored_ = false;
+    bool restore_ok_ = false;
+};
+
+static int getCudaDeviceForPointer(const void* ptr, cudaError_t& status) {
+    cudaPointerAttributes attributes;
+    status = cudaPointerGetAttributes(&attributes, ptr);
+    if (status != cudaSuccess) return -1;
+    if (attributes.type == cudaMemoryTypeDevice ||
+        attributes.type == cudaMemoryTypeManaged) {
+        return attributes.device;
+    }
+    return -1;
 }
 #endif
 
@@ -513,7 +559,9 @@ int EfaContext::registerMemoryRegionInternal(void* addr, size_t length,
     int ret;
     if (iface != FI_HMEM_SYSTEM) {
 #if defined(USE_CUDA)
-        bindCudaContextIfNeeded(device_ordinal);
+        ScopedCudaContext reg_context;
+        if (!reg_context.valid() || !reg_context.bind(device_ordinal))
+            return ERR_CONTEXT;
 #endif
         // GPU memory: use fi_mr_regattr with explicit iface and device
         struct iovec iov = {.iov_base = addr, .iov_len = length};
@@ -806,18 +854,49 @@ bool EfaContext::tryLoopbackCopy(Transport::Slice* slice) {
     // including non-EFA GPU backends such as MUSA/MLU/MACA, which never run
     // on AWS EFA hardware — registers loopback buffers as host memory, so a
     // plain memcpy is both correct and the only portable option (those
-    // backends do not expose the cuda* symbols).  *MemcpyDefault picks
-    // H2H/H2D/D2H/D2D from the pointer attributes.
+    // backends do not expose the cuda* symbols).  CUDA host-only copies also
+    // use memcpy; copies involving device memory use cudaMemcpyDefault after
+    // binding the destination device, or the source device for D2H copies.
+    // The caller's context is restored afterward, and CUDA copies synchronize
+    // before the slice is reported complete.
 #if defined(USE_CUDA)
-    auto rc = cudaMemcpy(dst, src, len, cudaMemcpyDefault);
-    if (rc != cudaSuccess) {
-        LOG(ERROR) << "EFA loopback cudaMemcpy failed: "
+    cudaError_t dst_status;
+    cudaError_t src_status;
+    int dst_device = getCudaDeviceForPointer(dst, dst_status);
+    int src_device = getCudaDeviceForPointer(src, src_status);
+    if (dst_status != cudaSuccess || src_status != cudaSuccess) {
+        cudaError_t rc = dst_status != cudaSuccess ? dst_status : src_status;
+        LOG(ERROR) << "EFA loopback cudaPointerGetAttributes failed: "
                    << cudaGetErrorString(rc) << " (dst=" << dst
                    << ", src=" << src << ", len=" << len << ")";
         slice->markFailed();
         return true;
     }
+
+    int device = dst_device >= 0 ? dst_device : src_device;
+    if (device < 0) {
+        memcpy(dst, src, len);
+    } else {
+        ScopedCudaContext context;
+        if (!context.valid() || !context.bind(device)) {
+            slice->markFailed();
+            return true;
+        }
+
+        cudaError_t rc = cudaMemcpy(dst, src, len, cudaMemcpyDefault);
+        if (rc == cudaSuccess) rc = cudaStreamSynchronize(0);
+        context.restore();
+        if (rc != cudaSuccess) {
+            LOG(ERROR) << "EFA loopback CUDA copy failed: "
+                       << cudaGetErrorString(rc) << " (dst=" << dst
+                       << ", src=" << src << ", len=" << len << ")";
+            slice->markFailed();
+            return true;
+        }
+    }
 #elif defined(USE_HIP)
+    // EFA is not deployed with HIP, so CUDA context binding is intentionally
+    // not mirrored here.
     auto rc = hipMemcpy(dst, src, len, hipMemcpyDefault);
     if (rc != hipSuccess) {
         LOG(ERROR) << "EFA loopback hipMemcpy failed: " << hipGetErrorString(rc)
diff --git a/mooncake-transfer-engine/src/transport/efa_transport/efa_transport.cpp b/mooncake-transfer-engine/src/transport/efa_transport/efa_transport.cpp
index 9178915af3..64c5335d98 100644
--- a/mooncake-transfer-engine/src/transport/efa_transport/efa_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/efa_transport/efa_transport.cpp
@@ -20,15 +20,12 @@
 #include <unistd.h>
 
 #include <algorithm>
-#include <atomic>
 #include <cassert>
 #include <chrono>
 #include <cstddef>
 #include <cstdlib>
 #include <fstream>
-#include <functional>
 #include <future>
-#include <limits>
 #include <set>
 #include <thread>
 
@@ -39,6 +36,7 @@
 #include "environ.h"
 #include "memory_location.h"
 #include "topology.h"
+#include "transport/batch_registration.h"
 #include "transport/efa_transport/efa_context.h"
 #include "transport/efa_transport/efa_endpoint.h"
 
@@ -682,56 +680,6 @@ int EfaTransport::allocateLocalSegmentID() {
 // (99-128 s) since nothing queues. Largest-first being worst is backwards from
 // longest-processing-time scheduling and is unexplained, so no sort is applied
 // here yet -- another reason the cap stays opt-in rather than a default.
-static size_t maxConcurrentRegMr() {
-    size_t configured = globalConfig().max_concurrent_reg_mr;
-    // 0 (unset) means unbounded, i.e. one thread per buffer as before.
-    return configured > 0 ? configured : std::numeric_limits<size_t>::max();
-}
-
-// Run `fn(i)` for i in [0, count) on at most maxConcurrentRegMr() threads,
-// returning the first non-zero result (all items are still attempted).
-//
-// With no cap set this spawns count-1 threads and runs the caller as a worker,
-// which reproduces what both batch entry points did before: one
-// std::async(std::launch::async) per buffer, which libstdc++ honours literally
-// as one fresh thread each. Kimi-K3 registers ~1450 KV buffers at once, so a
-// 192-core node peaks at ~1400 runnable threads inside fi_mr_regattr, and the
-// per-buffer duration this logs inflates with the queueing delay of the ones
-// ahead of it -- on 2x p6-b300 the median reached 106 s while the whole batch
-// took 138 s. That inflation is not by itself a reason to cap: a badly chosen
-// cap is slower still, see maxConcurrentRegMr().
-//
-// A plain thread pool rather than a semaphore over std::async, because if a cap
-// is set the point is to avoid the thread *creation*, not just to gate entry
-// into the provider -- admission control after the thread already exists would
-// leave that cost in place.
-static int runBoundedParallel(size_t count,
-                              const std::function<int(size_t)>& fn) {
-    if (count == 0) return 0;
-
-    size_t workers = std::min(count, maxConcurrentRegMr());
-    std::atomic<size_t> next{0};
-    std::atomic<int> first_error{0};
-
-    auto worker = [&]() {
-        for (size_t i = next.fetch_add(1); i < count; i = next.fetch_add(1)) {
-            int ret = fn(i);
-            if (ret) {
-                int expected = 0;
-                first_error.compare_exchange_strong(expected, ret);
-            }
-        }
-    };
-
-    std::vector<std::thread> threads;
-    threads.reserve(workers - 1);
-    for (size_t w = 1; w < workers; ++w) threads.emplace_back(worker);
-    worker();  // the caller is a worker too
-    for (auto& t : threads) t.join();
-
-    return first_error.load();
-}
-
 // Invert the topology's per-location preferred_hca lists into indices into the
 // NIC set the transport actually opened. `Topology::discover()` already
 // computes what matters here: for a "cuda:N" entry, preferred_hca holds the
@@ -772,7 +720,7 @@ int EfaTransport::registerLocalMemoryBatch(
     const std::string& location) {
     auto start = std::chrono::steady_clock::now();
 
-    int first_error = runBoundedParallel(buffer_list.size(), [&](size_t i) {
+    int first_error = runBoundedRegMrBatch(buffer_list.size(), [&](size_t i) {
         int ret = registerLocalMemoryInternal(buffer_list[i].addr,
                                               buffer_list[i].length, location,
                                               true, false, true);
@@ -799,7 +747,7 @@ int EfaTransport::registerLocalMemoryBatch(
 
 int EfaTransport::unregisterLocalMemoryBatch(
     const std::vector<void*>& addr_list) {
-    int first_error = runBoundedParallel(addr_list.size(), [&](size_t i) {
+    int first_error = runBoundedRegMrBatch(addr_list.size(), [&](size_t i) {
         int ret = unregisterLocalMemoryInternal(addr_list[i], false, true);
         if (ret) {
             LOG(WARNING) << "EfaTransport: Failed to unregister memory: addr "
@@ -939,14 +887,103 @@ Status EfaTransport::submitTransfer(
     return submitTransferTask(task_list);
 }
 
+// Bytes from `address` to the end of the registered chunk that covers it, or 0
+// if no chunk does.  `last_buffer_idx` caches the previous hit so that slicing
+// one request across a seam does not rescan the buffer list per slice.
+//
+// registerLocalMemoryInternal() splits a buffer larger than
+// min(max_mr_size, per-NIC PTE budget) into several chunks and publishes one
+// BufferDesc per chunk, so what the caller registered as a single contiguous
+// range can be several MRs here -- on either side of the transfer.
+static uint64_t efaBytesUntilChunkEnd(
+    const TransferMetadata::SegmentDesc* segment_desc, uint64_t address,
+    bool require_remote_key, size_t& last_buffer_idx) {
+    if (!segment_desc || segment_desc->buffers.empty()) return 0;
+
+    auto is_valid_buffer = [&](const TransferMetadata::BufferDesc& buffer) {
+        const auto& keys = require_remote_key ? buffer.rkey : buffer.lkey;
+        if (keys.empty()) return false;
+        if (address < buffer.addr || address - buffer.addr >= buffer.length)
+            return false;
+        // A chunk under the disjoint per-NIC partition carries a zero key for
+        // every NIC it was not registered on (see the nic_assignments fan-out
+        // in registerLocalMemoryInternal).  All-zero means no NIC can serve it
+        // and selectDevice() will reject it, so capping a slice at such a chunk
+        // would only turn one miss into several.
+        for (auto key : keys)
+            if (key != 0) return true;
+        return false;
+    };
+
+    if (last_buffer_idx < segment_desc->buffers.size()) {
+        const auto& buffer = segment_desc->buffers[last_buffer_idx];
+        if (is_valid_buffer(buffer)) {
+            return buffer.length - (address - buffer.addr);
+        }
+    }
+
+    uint64_t max_remaining = 0;
+    for (size_t i = 0; i < segment_desc->buffers.size(); ++i) {
+        const auto& buffer = segment_desc->buffers[i];
+        if (is_valid_buffer(buffer)) {
+            uint64_t remaining = buffer.length - (address - buffer.addr);
+            if (remaining > max_remaining) {
+                max_remaining = remaining;
+                last_buffer_idx = i;
+            }
+        }
+    }
+    return max_remaining;
+}
+
+// Slice length for a request, capped at the nearest registration boundary.
+//
+// Unlike RDMA this deliberately does not cut at globalConfig().slice_size: EFA
+// posts one WR per slice and SRD handles multi-MB messages natively, so a
+// request that stays inside one chunk on both sides still becomes exactly one
+// slice, as before.  The one thing that does force a split is an MR boundary --
+// a single fi_write/fi_read carries one lkey and one rkey, so a slice may not
+// straddle two chunks on either side.
+struct EfaSliceLengthCalculator {
+    const Transport::TransferRequest& request;
+    const TransferMetadata::SegmentDesc* local_desc;
+    const TransferMetadata::SegmentDesc* target_desc;
+
+    size_t src_buffer_idx = 0;
+    size_t tgt_buffer_idx = 0;
+
+    inline size_t calculate(uint64_t offset) {
+        uint64_t slice_length = request.length - offset;
+
+        const uint64_t src_rem = efaBytesUntilChunkEnd(
+            local_desc, reinterpret_cast<uint64_t>(request.source) + offset,
+            false, src_buffer_idx);
+        if (src_rem > 0) slice_length = std::min(slice_length, src_rem);
+
+        const uint64_t tgt_rem = efaBytesUntilChunkEnd(
+            target_desc, request.target_offset + offset, true, tgt_buffer_idx);
+        if (tgt_rem > 0) slice_length = std::min(slice_length, tgt_rem);
+
+        return static_cast<size_t>(slice_length);
+    }
+};
+
 Status EfaTransport::submitTransferTask(
     const std::vector<TransferTask*>& task_list) {
     std::unordered_map<std::shared_ptr<EfaContext>, std::vector<Slice*>>
         slices_to_post;
+    std::unordered_map<SegmentID, std::shared_ptr<SegmentDesc>>
+        target_segment_descs;
     auto local_segment_desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
     assert(local_segment_desc.get());
     const int kMaxRetryCount = globalConfig().retry_cnt;
 
+    auto fail_unposted_slices = [&]() {
+        for (auto& entry : slices_to_post)
+            for (auto* slice : entry.second) slice->markFailed();
+        slices_to_post.clear();
+    };
+
     for (size_t index = 0; index < task_list.size(); ++index) {
         assert(task_list[index]);
         auto& task = *task_list[index];
@@ -955,7 +992,24 @@ Status EfaTransport::submitTransferTask(
 
         if (request.length == 0) continue;
 
-        // Find which buffer and preferred device covers this request
+        // The slice length is capped against the peer's chunk boundaries too,
+        // so the target descriptor is needed here and not only in
+        // EfaContext::submitPostSend().  Cache it per target_id: a batch
+        // normally aims every request at the same segment.
+        auto target_desc_it = target_segment_descs.find(request.target_id);
+        if (target_desc_it == target_segment_descs.end()) {
+            target_desc_it =
+                target_segment_descs
+                    .emplace(request.target_id,
+                             metadata_->getSegmentDescByID(request.target_id))
+                    .first;
+        }
+        const auto& target_segment_desc = target_desc_it->second;
+
+        // Find which buffer and preferred device covers this request.  This can
+        // only succeed when the whole request fits in one local chunk, which is
+        // the common case; a request that straddles a seam falls through to the
+        // per-slice selection in the loop below.
         int request_buffer_id = -1, request_device_id = -1;
         if (selectDevice(local_segment_desc.get(), (uint64_t)request.source,
                          request.length, request_buffer_id,
@@ -963,53 +1017,40 @@ Status EfaTransport::submitTransferTask(
             request_buffer_id = -1;
             request_device_id = -1;
         }
+        // selectDevice() returns an index into the HCA space and validates it
+        // against buffer.rkey only, so bound it before indexing context_list_.
+        // Dropping to the retry path is the right recovery: it re-selects, and
+        // its own check covers context_list_ as well.
+        if (request_device_id >= 0 &&
+            (static_cast<size_t>(request_device_id) >= context_list_.size() ||
+             !context_list_[request_device_id] ||
+             !context_list_[request_device_id]->active())) {
+            request_buffer_id = -1;
+            request_device_id = -1;
+        }
 
-        if (request_buffer_id >= 0 && request_device_id >= 0) {
-            // One slice per request.  Round-robin NIC selection is
-            // handled by selectDevice above.
-            auto& context = context_list_[request_device_id];
-            if (!context || !context->active()) {
-                LOG(ERROR) << "EFA Device " << request_device_id
-                           << " is not active";
-                return Status::InvalidArgument(
-                    "EFA Device " + std::to_string(request_device_id) +
-                    " is not active");
-            }
-
-            Slice* slice = getSliceCache().allocate();
-            assert(slice);
-            slice->peer_nic_path.clear();
-            slice->rdma.dest_rkey = 0;
-
-            slice->source_addr = (char*)request.source;
-            slice->length = request.length;
-            slice->opcode = request.opcode;
-            slice->rdma.dest_addr = request.target_offset;
-            slice->rdma.retry_cnt = request.advise_retry_cnt;
-            slice->rdma.max_retry_cnt = kMaxRetryCount;
-            slice->task = &task;
-            slice->target_id = request.target_id;
-            slice->status = Slice::PENDING;
-            slice->ts = 0;
-            task.slice_list.push_back(slice);
-
-            slice->rdma.source_lkey =
-                local_segment_desc->buffers[request_buffer_id]
-                    .lkey[request_device_id];
-            slices_to_post[context].push_back(slice);
-            __sync_fetch_and_add(&task.total_bytes, slice->length);
-            __sync_fetch_and_add(&task.slice_count, 1);
-        } else {
-            // FALLBACK: device not found via initial selectDevice.
-            // Try per-slice retry with increasing retry_cnt to find any
-            // available device (handles edge cases like multi-buffer spans).
-            int buffer_id = -1, device_id = -1;
+        EfaSliceLengthCalculator slice_calc{request, local_segment_desc.get(),
+                                            target_segment_desc.get()};
+        for (uint64_t offset = 0; offset < request.length;) {
+            size_t slice_length = slice_calc.calculate(offset);
+            // Neither side reported a covering chunk (nothing registered at
+            // this address): keep the old whole-request behavior and let the
+            // selection below produce the ERR_ADDRESS_NOT_REGISTERED.  A zero
+            // here would otherwise spin forever.
+            if (slice_length == 0) slice_length = request.length - offset;
+
+            char* source_addr = (char*)request.source + offset;
+
+            // The whole-request selection covers every slice when it succeeded:
+            // it means one local chunk spans the entire request, and only the
+            // target side is forcing the split.
+            int buffer_id = request_buffer_id, device_id = request_device_id;
+            bool found_device = (buffer_id >= 0 && device_id >= 0);
             int retry_cnt = request.advise_retry_cnt;
-            bool found_device = false;
             while (retry_cnt < kMaxRetryCount && !found_device) {
                 if (selectDevice(local_segment_desc.get(),
-                                 (uint64_t)request.source, request.length,
-                                 buffer_id, device_id, retry_cnt++))
+                                 (uint64_t)source_addr, slice_length, buffer_id,
+                                 device_id, retry_cnt++))
                     continue;
                 if (device_id >= 0 &&
                     static_cast<size_t>(device_id) < context_list_.size() &&
@@ -1022,26 +1063,23 @@ Status EfaTransport::submitTransferTask(
             if (!found_device) {
                 LOG(ERROR) << "Memory region not registered by any active EFA "
                               "device(s): "
-                           << request.source;
-                for (auto& entry : slices_to_post)
-                    for (auto s : entry.second) s->markFailed();
+                           << (void*)source_addr;
+                fail_unposted_slices();
                 return Status::AddressNotRegistered(
                     "Memory region not registered by any active EFA "
                     "device(s): " +
-                    std::to_string(
-                        reinterpret_cast<uintptr_t>(request.source)));
+                    std::to_string(reinterpret_cast<uintptr_t>(source_addr)));
             }
 
-            // Found a device via retry — create single slice
             Slice* slice = getSliceCache().allocate();
             assert(slice);
             slice->peer_nic_path.clear();
             slice->rdma.dest_rkey = 0;
 
-            slice->source_addr = (char*)request.source;
-            slice->length = request.length;
+            slice->source_addr = source_addr;
+            slice->length = slice_length;
             slice->opcode = request.opcode;
-            slice->rdma.dest_addr = request.target_offset;
+            slice->rdma.dest_addr = request.target_offset + offset;
             slice->rdma.retry_cnt = request.advise_retry_cnt;
             slice->rdma.max_retry_cnt = kMaxRetryCount;
             slice->task = &task;
@@ -1050,12 +1088,13 @@ Status EfaTransport::submitTransferTask(
             slice->ts = 0;
             task.slice_list.push_back(slice);
 
-            auto& context = context_list_[device_id];
             slice->rdma.source_lkey =
                 local_segment_desc->buffers[buffer_id].lkey[device_id];
-            slices_to_post[context].push_back(slice);
+            slices_to_post[context_list_[device_id]].push_back(slice);
             __sync_fetch_and_add(&task.total_bytes, slice->length);
             __sync_fetch_and_add(&task.slice_count, 1);
+
+            offset += slice_length;
         }
     }
 
@@ -1071,9 +1110,13 @@ Status EfaTransport::getTransferStatus(BatchID batch_id,
     status.resize(task_count);
     for (size_t task_id = 0; task_id < task_count; task_id++) {
         auto& task = batch_desc.task_list[task_id];
-        status[task_id].transferred_bytes = task.transferred_bytes;
-        uint64_t success_slice_count = task.success_slice_count;
-        uint64_t failed_slice_count = task.failed_slice_count;
+        uint64_t success_slice_count =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+        uint64_t failed_slice_count =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+        // Completion counters publish the preceding byte updates.
+        status[task_id].transferred_bytes =
+            __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
         if (success_slice_count + failed_slice_count == task.slice_count) {
             if (failed_slice_count)
                 status[task_id].s = TransferStatusEnum::FAILED;
@@ -1097,9 +1140,13 @@ Status EfaTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count)
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/flagcx_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/flagcx_transport/CMakeLists.txt
new file mode 100644
index 0000000000..5326e37b4e
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/flagcx_transport/CMakeLists.txt
@@ -0,0 +1,4 @@
+file(GLOB FLAGCX_SOURCES "*.cpp")
+add_library(flagcx_transport OBJECT ${FLAGCX_SOURCES})
+target_link_libraries(flagcx_transport PRIVATE FlagCX::flagcx JsonCpp::JsonCpp
+                                               yalantinglibs::yalantinglibs)
diff --git a/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport.cpp b/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport.cpp
new file mode 100644
index 0000000000..a4ea9dc419
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport.cpp
@@ -0,0 +1,477 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#include "transport/flagcx_transport/flagcx_transport.h"
+
+#include "transport/flagcx_transport/flagcx_transport_internal.h"
+
+#include <glog/logging.h>
+
+#include <cassert>
+#include <chrono>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "common.h"
+#include "transfer_engine.h"
+#include "transfer_metadata.h"
+
+namespace mooncake {
+
+FlagCxTransport::FlagCxTransport() {}
+
+FlagCxTransport::~FlagCxTransport() {
+    completion_running_.store(false, std::memory_order_release);
+    pending_cv_.notify_all();
+    if (completion_thread_.joinable()) completion_thread_.join();
+
+    {
+        std::lock_guard<std::mutex> lk(pending_mu_);
+        for (auto &p : pending_) {
+            for (auto *s : p.slices) s->markFailed();
+        }
+        pending_.clear();
+    }
+
+    if (engine_) {
+        // Deregister everything still registered, then tear the engine down.
+        {
+            std::lock_guard<std::mutex> lk(reg_mu_);
+            for (auto &r : regs_) flagcxP2pEngineMrDestroy(engine_, r.mr);
+            regs_.clear();
+        }
+        flagcxP2pEngineStopAccept(engine_);
+        flagcxP2pEngineDestroy(engine_);
+        engine_ = nullptr;
+    }
+    if (metadata_) metadata_->removeSegmentDesc(local_server_name_);
+}
+
+int FlagCxTransport::install(std::string &local_server_name,
+                             std::shared_ptr<TransferMetadata> meta,
+                             std::shared_ptr<Topology> topo) {
+    (void)topo;
+    local_server_name_ = local_server_name;
+    metadata_ = meta;
+
+    engine_ = flagcxP2pEngineCreate();
+    if (!engine_) {
+        LOG(ERROR) << "FlagCxTransport: flagcxP2pEngineCreate failed";
+        return -1;
+    }
+
+    bool rpc_server_started = false;
+    auto cleanup_engine = [this, &rpc_server_started]() {
+        if (!engine_) return;
+        if (rpc_server_started) flagcxP2pEngineStopAccept(engine_);
+        flagcxP2pEngineDestroy(engine_);
+        engine_ = nullptr;
+        flagcx_endpoint_.clear();
+    };
+
+    // Bring up the accept daemon so peers can RDMA into our registered
+    // regions.  Idempotent; safe even though buffers register later.
+    if (flagcxP2pEngineStartRpcServer(engine_) != 0) {
+        LOG(ERROR) << "FlagCxTransport: flagcxP2pEngineStartRpcServer failed";
+        cleanup_engine();
+        return -1;
+    }
+    rpc_server_started = true;
+
+    // The engine metadata string is "ip:rdma_port?gpu_index?notif_port";
+    // the leading "ip:rdma_port" doubles as the GetConn session id, and
+    // rdma_port == the RPC/handshake port (flagcxP2pEngineGetRpcPort).
+    char *meta_str = nullptr;
+    const int metadata_rc = flagcxP2pEngineGetMetadata(engine_, &meta_str);
+    std::unique_ptr<char[]> meta_owner(meta_str);
+    if (metadata_rc != 0 || !meta_owner) {
+        LOG(ERROR) << "FlagCxTransport: flagcxP2pEngineGetMetadata failed";
+        cleanup_engine();
+        return -1;
+    }
+    std::string md(meta_owner.get());
+    auto q = md.find('?');
+    flagcx_endpoint_ = (q == std::string::npos) ? md : md.substr(0, q);
+    if (flagcx_endpoint_.empty()) {
+        LOG(ERROR) << "FlagCxTransport: empty flagcx endpoint from metadata '"
+                   << md << "'";
+        cleanup_engine();
+        return -1;
+    }
+
+    LOG(INFO) << "FlagCxTransport: engine up, endpoint=" << flagcx_endpoint_
+              << " (rpc_port=" << flagcxP2pEngineGetRpcPort(engine_) << ")";
+
+    if (allocateLocalSegment() != 0) {
+        cleanup_engine();
+        return -1;
+    }
+
+    completion_running_.store(true, std::memory_order_release);
+    completion_thread_ = std::thread(&FlagCxTransport::completionLoop, this);
+
+    LOG(INFO) << "FlagCxTransport: install OK (direct submit)";
+    return 0;
+}
+
+// Issue one batch of slices that all target the same segment and share an
+// opcode as a SINGLE multi-iov transfer. The engine fans the iovs out across
+// the conn's rails (NICs), so a deep batch keeps every NIC busy instead of one
+// block-at-a-time. Completion is marked by the completion polling thread.
+void FlagCxTransport::runSliceGroup(const std::vector<Slice *> &group) {
+    if (group.empty()) return;
+    bool ok = true;
+    FlagcxP2pConn *conn = nullptr;
+    {
+        std::lock_guard<std::mutex> lk(flagcx_mu_);
+        conn = connForSegment(group.front()->target_id);
+    }
+    const bool isWrite = group.front()->opcode == TransferRequest::WRITE;
+
+    std::vector<FlagcxP2pMr> mrs;
+    std::vector<void *> bufs;
+    std::vector<size_t> sizes;
+    std::vector<FlagcxP2pRdmaDesc> descs;
+    mrs.reserve(group.size());
+    bufs.reserve(group.size());
+    sizes.reserve(group.size());
+    descs.reserve(group.size());
+
+    if (conn == nullptr) ok = false;
+    for (Slice *s : group) {
+        if (!ok) break;
+        FlagcxP2pMr local_mr = 0;
+        if (!resolveLocalMr(s->source_addr, s->length, local_mr)) {
+            LOG(ERROR) << "FlagCxTransport: source not registered "
+                       << s->source_addr;
+            ok = false;
+            break;
+        }
+        FlagcxP2pRdmaDesc desc;
+        const uint32_t descriptor_length =
+            flagcx_internal::descriptorLength(s->length);
+        if (flagcxP2pEngineMakeDesc(conn, s->flagcx.dest_offset,
+                                    descriptor_length, &desc) != 0) {
+            LOG(ERROR) << "FlagCxTransport: MakeDesc failed for remote VA 0x"
+                       << std::hex << s->flagcx.dest_offset << std::dec;
+            ok = false;
+            break;
+        }
+        mrs.push_back(local_mr);
+        bufs.push_back(s->source_addr);
+        sizes.push_back(s->length);
+        descs.push_back(desc);
+    }
+
+    if (ok) {
+        uint64_t transfer_id = 0;
+        if (isWrite) {
+            std::lock_guard<std::mutex> lk(flagcx_mu_);
+            ok = flagcxP2pEngineWriteVector(conn, mrs, bufs, sizes, descs,
+                                            static_cast<int>(group.size()),
+                                            &transfer_id) == 0;
+        } else {
+            std::lock_guard<std::mutex> lk(flagcx_mu_);
+            ok = flagcxP2pEngineReadVector(conn, mrs, bufs, sizes, descs,
+                                           static_cast<int>(group.size()),
+                                           &transfer_id) == 0;
+        }
+        if (ok) {
+            const auto now = std::chrono::steady_clock::now();
+            for (Slice *s : group) {
+                s->status = Slice::POSTED;
+                s->ts = getCurrentTimeInNano();
+            }
+            {
+                std::lock_guard<std::mutex> lk(pending_mu_);
+                pending_.push_back(
+                    {conn, transfer_id, group, now + std::chrono::seconds(30)});
+            }
+            pending_cv_.notify_one();
+        }
+    }
+
+    if (!ok) {
+        for (Slice *s : group) s->markFailed();
+    }
+}
+
+void FlagCxTransport::submitSlices(const std::vector<Slice *> &slices) {
+    std::lock_guard<std::mutex> lk(submit_mu_);
+    std::unordered_map<uint64_t, std::vector<Slice *>> groups;
+    for (Slice *s : slices) {
+        const uint64_t key = (static_cast<uint64_t>(s->target_id) << 1) |
+                             (s->opcode == TransferRequest::WRITE ? 0u : 1u);
+        groups[key].push_back(s);
+    }
+    for (auto &kv : groups) runSliceGroup(kv.second);
+}
+
+bool FlagCxTransport::pollPendingTransfers() {
+    std::vector<PendingTransfer> local;
+    {
+        std::lock_guard<std::mutex> lk(pending_mu_);
+        local.swap(pending_);
+    }
+
+    if (local.empty()) return false;
+
+    std::vector<PendingTransfer> still_pending;
+    const auto now = std::chrono::steady_clock::now();
+    for (auto &p : local) {
+        bool done = false;
+        {
+            std::lock_guard<std::mutex> lk(flagcx_mu_);
+            done = flagcxP2pEngineXferStatus(p.conn, p.transfer_id);
+        }
+        if (done) {
+            for (auto *s : p.slices) s->markSuccess();
+        } else if (now > p.deadline) {
+            LOG(ERROR) << "FlagCxTransport: transfer timeout, tid="
+                       << p.transfer_id;
+            for (auto *s : p.slices) s->markFailed();
+        } else {
+            still_pending.push_back(std::move(p));
+        }
+    }
+
+    if (!still_pending.empty()) {
+        std::lock_guard<std::mutex> lk(pending_mu_);
+        for (auto &p : still_pending) pending_.push_back(std::move(p));
+        return true;
+    }
+    return false;
+}
+
+void FlagCxTransport::completionLoop() {
+    unsigned active_polls = 0;
+    while (completion_running_.load(std::memory_order_acquire)) {
+        if (pollPendingTransfers()) {
+            if (++active_polls >= 64) {
+                active_polls = 0;
+                std::this_thread::yield();
+            }
+            continue;
+        }
+
+        active_polls = 0;
+        std::unique_lock<std::mutex> lk(pending_mu_);
+        pending_cv_.wait(lk, [this] {
+            return !completion_running_.load(std::memory_order_acquire) ||
+                   !pending_.empty();
+        });
+    }
+}
+
+int FlagCxTransport::allocateLocalSegment() {
+    auto desc = metadata_->getSegmentDesc(local_server_name_);
+    if (!desc) desc = std::make_shared<SegmentDesc>();
+    desc->name = local_server_name_;
+#ifdef ENABLE_MULTI_PROTOCOL
+    if (!desc->protocol.empty()) desc->protocol += ",";
+    desc->protocol += "flagcx";
+#else
+    desc->protocol = "flagcx";
+#endif
+    // Advertise the flagcx RPC/handshake endpoint ("ip:rpc_port"); peers
+    // read it back from the segment descriptor to open a connection.  The
+    // RDMA-reachable endpoint legitimately differs from the TCP-routable
+    // segment name, which is exactly what rdma_server_name is meant for.
+    desc->rdma_server_name = flagcx_endpoint_;
+    metadata_->addLocalSegment(LOCAL_SEGMENT_ID, local_server_name_,
+                               std::move(desc));
+    return metadata_->updateLocalSegmentDesc();
+}
+
+int FlagCxTransport::registerLocalMemory(void *addr, size_t length,
+                                         const std::string &location,
+                                         bool remote_accessible,
+                                         bool update_metadata) {
+    (void)location;
+    (void)remote_accessible;
+    FlagcxP2pMr mr = 0;
+    if (flagcxP2pEngineReg(engine_, reinterpret_cast<uintptr_t>(addr), length,
+                           mr) != 0) {
+        LOG(ERROR) << "FlagCxTransport: flagcxP2pEngineReg failed addr=" << addr
+                   << " len=" << length;
+        return -1;
+    }
+    {
+        std::lock_guard<std::mutex> lk(reg_mu_);
+        regs_.push_back({addr, length, mr});
+    }
+    BufferDesc buf_desc;
+    buf_desc.name = local_server_name_;
+    buf_desc.addr = reinterpret_cast<uint64_t>(addr);
+    buf_desc.length = length;
+#ifdef ENABLE_MULTI_PROTOCOL
+    buf_desc.protocol = "flagcx";
+#endif
+    return metadata_->addLocalMemoryBuffer(buf_desc, update_metadata);
+}
+
+int FlagCxTransport::unregisterLocalMemory(void *addr, bool update_metadata) {
+    {
+        std::lock_guard<std::mutex> lk(reg_mu_);
+        for (auto it = regs_.begin(); it != regs_.end(); ++it) {
+            if (it->addr == addr) {
+                if (engine_) flagcxP2pEngineMrDestroy(engine_, it->mr);
+                regs_.erase(it);
+                break;
+            }
+        }
+    }
+    return metadata_->removeLocalMemoryBuffer(addr, update_metadata);
+}
+
+int FlagCxTransport::registerLocalMemoryBatch(
+    const std::vector<BufferEntry> &buffer_list, const std::string &location) {
+    int first_error = 0;
+    for (const auto &b : buffer_list) {
+        int rc = registerLocalMemory(b.addr, b.length, location, true, false);
+        if (first_error == 0 && rc != 0) first_error = rc;
+    }
+    int metadata_rc = metadata_->updateLocalSegmentDesc();
+    return first_error != 0 ? first_error : metadata_rc;
+}
+
+int FlagCxTransport::unregisterLocalMemoryBatch(
+    const std::vector<void *> &addr_list) {
+    int first_error = 0;
+    for (auto a : addr_list) {
+        int rc = unregisterLocalMemory(a, false);
+        if (first_error == 0 && rc != 0) first_error = rc;
+    }
+    int metadata_rc = metadata_->updateLocalSegmentDesc();
+    return first_error != 0 ? first_error : metadata_rc;
+}
+
+bool FlagCxTransport::resolveLocalMr(void *addr, size_t length,
+                                     FlagcxP2pMr &mr_out) {
+    std::lock_guard<std::mutex> lk(reg_mu_);
+    for (const auto &r : regs_) {
+        const uintptr_t base = reinterpret_cast<uintptr_t>(r.addr);
+        const uintptr_t hit = reinterpret_cast<uintptr_t>(addr);
+        if (flagcx_internal::containsRange(base, r.length, hit, length)) {
+            mr_out = r.mr;
+            return true;
+        }
+    }
+    return false;
+}
+
+FlagcxP2pConn *FlagCxTransport::connForSegment(SegmentID target_id) {
+    auto desc = metadata_->getSegmentDescByID(target_id);
+    if (!desc) {
+        LOG(ERROR) << "FlagCxTransport: no segment desc for id " << target_id;
+        return nullptr;
+    }
+    if (desc->rdma_server_name.empty()) {
+        LOG(ERROR) << "FlagCxTransport: segment " << desc->name
+                   << " has no flagcx endpoint (rdma_server_name empty)";
+        return nullptr;
+    }
+    // The engine caches connections by session string, so calling this on
+    // every slice is cheap after the first handshake.
+    FlagcxP2pConn *conn =
+        flagcxP2pEngineGetConn(engine_, desc->rdma_server_name.c_str());
+    if (!conn) {
+        LOG(ERROR) << "FlagCxTransport: GetConn failed for "
+                   << desc->rdma_server_name;
+    }
+    return conn;
+}
+
+Status FlagCxTransport::submitTransfer(
+    BatchID batch_id, const std::vector<TransferRequest> &entries) {
+    auto &batch_desc = *reinterpret_cast<BatchDesc *>(batch_id);
+    if (batch_desc.task_list.size() + entries.size() > batch_desc.batch_size) {
+        return Status::InvalidArgument(
+            "FlagCxTransport: exceeds batch capacity");
+    }
+    size_t task_id = batch_desc.task_list.size();
+    batch_desc.task_list.resize(task_id + entries.size());
+    std::vector<Slice *> to_post;
+    to_post.reserve(entries.size());
+    for (const auto &request : entries) {
+        TransferTask &task = batch_desc.task_list[task_id++];
+        task.total_bytes = request.length;
+        Slice *slice = getSliceCache().allocate();
+        slice->source_addr = request.source;
+        slice->length = request.length;
+        slice->opcode = request.opcode;
+        slice->target_id = request.target_id;
+        slice->flagcx.dest_offset = request.target_offset;
+        slice->task = &task;
+        slice->status = Slice::PENDING;
+        slice->ts = 0;
+        task.slice_list.push_back(slice);
+        __sync_fetch_and_add(&task.slice_count, 1);
+        to_post.push_back(slice);
+    }
+    submitSlices(to_post);
+    return Status::OK();
+}
+
+Status FlagCxTransport::submitTransferTask(
+    const std::vector<TransferTask *> &task_list) {
+    std::vector<Slice *> to_post;
+    to_post.reserve(task_list.size());
+    for (auto *tp : task_list) {
+        assert(tp && tp->request);
+        TransferTask &task = *tp;
+        const auto &request = *task.request;
+        task.total_bytes = request.length;
+        Slice *slice = getSliceCache().allocate();
+        slice->source_addr = request.source;
+        slice->length = request.length;
+        slice->opcode = request.opcode;
+        slice->target_id = request.target_id;
+        slice->flagcx.dest_offset = request.target_offset;
+        slice->task = &task;
+        slice->status = Slice::PENDING;
+        slice->ts = 0;
+        task.slice_list.push_back(slice);
+        __sync_fetch_and_add(&task.slice_count, 1);
+        to_post.push_back(slice);
+    }
+    submitSlices(to_post);
+    return Status::OK();
+}
+
+Status FlagCxTransport::getTransferStatus(BatchID batch_id, size_t task_id,
+                                          TransferStatus &status) {
+    auto &batch_desc = *reinterpret_cast<BatchDesc *>(batch_id);
+    if (task_id >= batch_desc.task_list.size()) {
+        return Status::InvalidArgument(
+            "FlagCxTransport::getTransferStatus task_id out of range");
+    }
+    auto &task = batch_desc.task_list[task_id];
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
+    if (success_slice_count + failed_slice_count == task.slice_count) {
+        status.s = failed_slice_count ? TransferStatusEnum::FAILED
+                                      : TransferStatusEnum::COMPLETED;
+        task.is_finished = true;
+    } else {
+        status.s = TransferStatusEnum::WAITING;
+    }
+    return Status::OK();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport_internal.h b/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport_internal.h
new file mode 100644
index 0000000000..ed7d81cb5b
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/flagcx_transport/flagcx_transport_internal.h
@@ -0,0 +1,35 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#ifndef FLAGCX_TRANSPORT_INTERNAL_H_
+#define FLAGCX_TRANSPORT_INTERNAL_H_
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+
+namespace mooncake::flagcx_internal {
+
+inline bool containsRange(uintptr_t region_start, size_t region_length,
+                          uintptr_t range_start, size_t range_length) {
+    if (range_start < region_start) return false;
+
+    const uintptr_t offset = range_start - region_start;
+    return offset <= region_length &&
+           range_length <= region_length - static_cast<size_t>(offset);
+}
+
+inline uint32_t descriptorLength(size_t transfer_length) {
+    return static_cast<uint32_t>(std::min<size_t>(
+        transfer_length, std::numeric_limits<uint32_t>::max()));
+}
+
+}  // namespace mooncake::flagcx_internal
+
+#endif  // FLAGCX_TRANSPORT_INTERNAL_H_
diff --git a/mooncake-transfer-engine/src/transport/hip_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/hip_transport/CMakeLists.txt
index 1213ba2ded..3962b2d80a 100644
--- a/mooncake-transfer-engine/src/transport/hip_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/hip_transport/CMakeLists.txt
@@ -1,10 +1,11 @@
 file(GLOB HIP_TRANSPORT_SOURCES "*.cpp")
 
 add_library(hip_transport OBJECT ${HIP_TRANSPORT_SOURCES})
+target_link_libraries(hip_transport PRIVATE glog::glog)
 
 target_include_directories(hip_transport PUBLIC ${HIP_INCLUDE_DIRS})
 
 # Treat warnings as errors for hip_transport
-target_compile_options(hip_transport PRIVATE 
+target_compile_options(hip_transport PRIVATE
     -Werror
 )
diff --git a/mooncake-transfer-engine/src/transport/hip_transport/hip_transport.cpp b/mooncake-transfer-engine/src/transport/hip_transport/hip_transport.cpp
index 71031c3b9f..e24978bc42 100644
--- a/mooncake-transfer-engine/src/transport/hip_transport/hip_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/hip_transport/hip_transport.cpp
@@ -603,9 +603,13 @@ Status HipTransport::getTransferStatus(BatchID batch_id, size_t task_id,
 
     // Get task and status info
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
 
     // Determine completion status
     if (success_slice_count + failed_slice_count == task.slice_count) {
diff --git a/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/CMakeLists.txt
index 5485952429..2df09461f2 100644
--- a/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/CMakeLists.txt
@@ -1,6 +1,7 @@
 file(GLOB INTRANODE_NVLINK_SOURCES "*.cpp")
 
 add_library(intranode_nvlink_transport OBJECT ${INTRANODE_NVLINK_SOURCES})
+target_link_libraries(intranode_nvlink_transport PRIVATE glog::glog)
 
 if (USE_CUDA)
 target_include_directories(intranode_nvlink_transport PUBLIC ${CUDAToolkit_INCLUDE_DIRS})
diff --git a/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/intranode_nvlink_transport.cpp b/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/intranode_nvlink_transport.cpp
index 52ca987add..35b919b153 100644
--- a/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/intranode_nvlink_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/intranode_nvlink_transport/intranode_nvlink_transport.cpp
@@ -533,9 +533,13 @@ Status IntraNodeNvlinkTransport::getTransferStatus(BatchID batch_id,
             }
         }
     }
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/kunpeng_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/kunpeng_transport/CMakeLists.txt
index e8fae49d54..8fc2709f2c 100644
--- a/mooncake-transfer-engine/src/transport/kunpeng_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/kunpeng_transport/CMakeLists.txt
@@ -1,4 +1,12 @@
-file(GLOB UB_SOURCES "*.cpp" "urma/urma_endpoint.cpp" "ub_allocator.cpp")
+set(UB_ALLOCATOR_SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/ub_allocator.cpp")
+file(GLOB UB_SOURCES "*.cpp" "urma/urma_endpoint.cpp")
+list(REMOVE_ITEM UB_SOURCES "${UB_ALLOCATOR_SOURCE}")
+
+add_library(ub_allocator OBJECT "${UB_ALLOCATOR_SOURCE}")
+target_include_directories(
+  ub_allocator PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+                      $<INSTALL_INTERFACE:include>)
+target_link_libraries(ub_allocator PRIVATE glog::glog numa)
 
 # Build ub_transport with real URMA library if available Never include
 # mock_urma_api.cpp in ub_transport library For test, we will use
diff --git a/mooncake-transfer-engine/src/transport/kunpeng_transport/ub_transport.cpp b/mooncake-transfer-engine/src/transport/kunpeng_transport/ub_transport.cpp
index cf443a0ba5..a6aae36ba2 100644
--- a/mooncake-transfer-engine/src/transport/kunpeng_transport/ub_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/kunpeng_transport/ub_transport.cpp
@@ -342,9 +342,13 @@ Status UbTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count)
             status.s = FAILED;
diff --git a/mooncake-transfer-engine/src/transport/maca_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/maca_transport/CMakeLists.txt
index eb1b41ece4..0905f62d9c 100644
--- a/mooncake-transfer-engine/src/transport/maca_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/maca_transport/CMakeLists.txt
@@ -1,5 +1,6 @@
 file(GLOB MACA_TRANSPORT_SOURCES "*.cpp")
 
 add_library(maca_transport OBJECT ${MACA_TRANSPORT_SOURCES})
+target_link_libraries(maca_transport PRIVATE glog::glog)
 
 target_include_directories(maca_transport PUBLIC ${MACA_INCLUDE_DIR})
diff --git a/mooncake-transfer-engine/src/transport/maca_transport/maca_transport.cpp b/mooncake-transfer-engine/src/transport/maca_transport/maca_transport.cpp
index c769a9f53b..675ea026ac 100644
--- a/mooncake-transfer-engine/src/transport/maca_transport/maca_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/maca_transport/maca_transport.cpp
@@ -518,9 +518,13 @@ Status MacaTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             }
         }
     }
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
diff --git a/mooncake-transfer-engine/src/transport/musa_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/musa_transport/CMakeLists.txt
new file mode 100644
index 0000000000..e2b37e1595
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/musa_transport/CMakeLists.txt
@@ -0,0 +1,5 @@
+file(GLOB MUSA_TRANSPORT_SOURCES "*.cpp")
+
+add_library(musa_transport OBJECT ${MUSA_TRANSPORT_SOURCES})
+
+target_include_directories(musa_transport PUBLIC /usr/local/musa/include)
diff --git a/mooncake-transfer-engine/src/transport/musa_transport/musa_transport.cpp b/mooncake-transfer-engine/src/transport/musa_transport/musa_transport.cpp
new file mode 100644
index 0000000000..3f6eb8a675
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/musa_transport/musa_transport.cpp
@@ -0,0 +1,327 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+
+#include "transport/musa_transport/musa_transport.h"
+
+#include <cerrno>
+#include <cstdlib>
+#include <limits>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include <glog/logging.h>
+
+#include "cuda_alike.h"
+#include "memory_location.h"
+
+namespace mooncake {
+namespace {
+
+int deviceForPointer(const void* ptr) {
+    cudaPointerAttributes attr;
+    if (!ptr || cudaPointerGetAttributes(&attr, ptr) != cudaSuccess) {
+        cudaGetLastError();
+        return -1;
+    }
+    return attr.type == cudaMemoryTypeDevice ? attr.device : -1;
+}
+
+int deviceFromLocation(const std::string& location) {
+    if (location.rfind(GPU_PREFIX, 0) != 0) return -1;
+    const char* begin = location.c_str() + GPU_PREFIX.size();
+    if (*begin == '\0') return -1;
+
+    errno = 0;
+    char* end = nullptr;
+    long value = std::strtol(begin, &end, 10);
+    if (errno == ERANGE || end == begin || *end != '\0' || value < 0 ||
+        value > std::numeric_limits<int>::max()) {
+        return -1;
+    }
+
+    int count = 0;
+    if (cudaGetDeviceCount(&count) != cudaSuccess || value >= count) return -1;
+    return static_cast<int>(value);
+}
+
+bool openOnMetadataDevice() {
+    static const bool enabled = [] {
+        const char* value = std::getenv("MC_MUSA_IPC_OPEN_DEVICE");
+        if (value && std::string(value) == "metadata") {
+            const char* musa_visible = std::getenv("MUSA_VISIBLE_DEVICES");
+            LOG(INFO) << "MusaTransport: opening IPC handles on the metadata "
+                         "device; peers must use identical runtime-visible "
+                         "logical device mappings (MUSA_VISIBLE_DEVICES="
+                      << (musa_visible ? musa_visible : "(not set)") << ")";
+            return true;
+        }
+        if (!value || std::string(value) == "current") {
+            LOG(INFO) << "MusaTransport: opening IPC handles on the current "
+                         "device";
+            return false;
+        }
+        LOG(WARNING) << "MusaTransport: unknown MC_MUSA_IPC_OPEN_DEVICE="
+                     << value << ", using current";
+        return false;
+    }();
+    return enabled;
+}
+
+enum class MusaCopyApi { Auto, Default, TransferBatch };
+
+MusaCopyApi copyApi() {
+    static const MusaCopyApi api = [] {
+        const char* value = std::getenv("MC_MUSA_COPY_API");
+        if (!value || std::string(value) == "auto") return MusaCopyApi::Auto;
+        if (std::string(value) == "default") return MusaCopyApi::Default;
+        if (std::string(value) == "transfer_batch")
+            return MusaCopyApi::TransferBatch;
+        LOG(WARNING) << "MusaTransport: unknown MC_MUSA_COPY_API=" << value
+                     << ", using auto";
+        return MusaCopyApi::Auto;
+    }();
+    return api;
+}
+
+const char* copyApiName(MusaCopyApi api) {
+    switch (api) {
+        case MusaCopyApi::Auto:
+            return "auto";
+        case MusaCopyApi::Default:
+            return "default";
+        case MusaCopyApi::TransferBatch:
+            return "transfer_batch";
+    }
+    return "unknown";
+}
+
+size_t transferBatchMinBytes() {
+    static const size_t min_bytes = [] {
+        constexpr size_t kDefaultMinBytes = 1024ULL * 1024ULL;
+        const char* value = std::getenv("MC_MUSA_TRANSFER_BATCH_MIN_BYTES");
+        if (!value) return kDefaultMinBytes;
+
+        errno = 0;
+        char* end = nullptr;
+        unsigned long long parsed = std::strtoull(value, &end, 0);
+        if (errno == ERANGE || end == value || *end != '\0' ||
+            parsed > std::numeric_limits<size_t>::max()) {
+            LOG(WARNING)
+                << "MusaTransport: invalid MC_MUSA_TRANSFER_BATCH_MIN_BYTES="
+                << value << ", using " << kDefaultMinBytes;
+            return kDefaultMinBytes;
+        }
+        return static_cast<size_t>(parsed);
+    }();
+    return min_bytes;
+}
+
+bool shouldUseTransferBatch(MusaCopyApi api, const std::vector<size_t>& sizes) {
+    if (api == MusaCopyApi::Default) return false;
+    if (api == MusaCopyApi::TransferBatch) return true;
+    const size_t min_bytes = transferBatchMinBytes();
+    for (size_t size : sizes) {
+        if (size < min_bytes) return false;
+    }
+    return true;
+}
+
+class MusaTransportPolicy final : public GpuIpcTransportPolicy {
+   public:
+    const char* protocol() const override { return "musa"; }
+    const char* displayName() const override { return "MusaTransport"; }
+
+    bool groupTransfersByDevice() const override { return true; }
+    bool requiresStreamDeviceGuard() const override { return true; }
+    bool preserveExistingMetadata() const override { return true; }
+
+    std::string normalizeMemoryLocation(
+        const void* addr, const std::string& location) const override {
+        if (location.rfind(GPU_PREFIX, 0) == 0 ||
+            location != kWildcardLocation) {
+            return location;
+        }
+
+        cudaPointerAttributes attr{};
+        cudaError_t err = cudaPointerGetAttributes(&attr, addr);
+        if (err == cudaSuccess && attr.type == cudaMemoryTypeDevice &&
+            attr.device >= 0) {
+            return GPU_PREFIX + std::to_string(attr.device);
+        }
+
+        int current_device = -1;
+        if (cudaGetDevice(&current_device) == cudaSuccess &&
+            current_device >= 0) {
+            LOG(WARNING)
+                << "MusaTransport: could not query wildcard buffer owner; "
+                   "using current device "
+                << current_device;
+            return GPU_PREFIX + std::to_string(current_device);
+        }
+        LOG(ERROR) << "MusaTransport: could not resolve wildcard buffer "
+                      "location for IPC registration";
+        return location;
+    }
+
+    int selectStreamDevice(const void* /*local_buffer*/, const void* /*source*/,
+                           const void* destination) const override {
+        // MUSA P2P IPC reaches the best path when the DMA stream belongs to
+        // the copy destination: remote device for WRITE and local device for
+        // READ.  The destination is already relocated by the shared core.
+        int device_id = deviceForPointer(destination);
+        if (device_id < 0) cudaGetDevice(&device_id);
+        return device_id < 0 ? 0 : device_id;
+    }
+
+    bool submitBatchCopies(const std::vector<void*>& srcs,
+                           const std::vector<void*>& dsts,
+                           const std::vector<size_t>& sizes,
+                           cudaStream_t stream,
+                           size_t& fail_index) const override {
+        const MusaCopyApi api = copyApi();
+        static const bool logged_api = [api] {
+            LOG(INFO) << "MusaTransport: copy API " << copyApiName(api)
+                      << ", transfer-batch min bytes "
+                      << transferBatchMinBytes();
+            return true;
+        }();
+        (void)logged_api;
+        if (!shouldUseTransferBatch(api, sizes)) return false;
+
+        if (srcs.empty() || srcs.size() != dsts.size() ||
+            srcs.size() != sizes.size()) {
+            fail_index = std::numeric_limits<size_t>::max();
+            LOG(ERROR) << "MusaTransport: invalid batch-copy vectors";
+            return true;
+        }
+
+#if defined(MUSA_VERSION) && MUSA_VERSION >= 50200
+        std::vector<MUdeviceptr> driver_srcs(srcs.size());
+        std::vector<MUdeviceptr> driver_dsts(dsts.size());
+        std::vector<size_t> driver_sizes(sizes.begin(), sizes.end());
+        for (size_t i = 0; i < srcs.size(); ++i) {
+            driver_srcs[i] = reinterpret_cast<MUdeviceptr>(srcs[i]);
+            driver_dsts[i] = reinterpret_cast<MUdeviceptr>(dsts[i]);
+        }
+
+        MUmemcpyAttributes attributes{};
+        attributes.srcAccessOrder = MU_MEMCPY_SRC_ACCESS_ORDER_STREAM;
+        size_t attributes_index = 0;
+        fail_index = std::numeric_limits<size_t>::max();
+        MUresult result = muMemoryTransferBatchAsync(
+            driver_dsts.data(), driver_srcs.data(), driver_sizes.data(),
+            driver_srcs.size(), &attributes, &attributes_index, 1, &fail_index,
+            reinterpret_cast<MUstream>(stream));
+        if (result != MUSA_SUCCESS) {
+            LOG(ERROR) << "MusaTransport: muMemoryTransferBatchAsync failed: "
+                       << result;
+            return true;
+        }
+        fail_index = srcs.size();
+        return true;
+#else
+        static const bool warned_once = [] {
+            LOG(WARNING)
+                << "MusaTransport: muMemoryTransferBatchAsync requires MUSA "
+                   "SDK 5.2 or newer; using per-slice copies";
+            return true;
+        }();
+        (void)warned_once;
+        return false;
+#endif
+    }
+
+    cudaError_t openIpcMemHandle(void** address, cudaIpcMemHandle_t handle,
+                                 const std::string& location,
+                                 int& opened_device) const override {
+        int saved_device = -1;
+        cudaError_t saved_err = cudaGetDevice(&saved_device);
+        if (saved_err != cudaSuccess) return saved_err;
+
+        opened_device = saved_device;
+        if (openOnMetadataDevice()) {
+            const int metadata_device = deviceFromLocation(location);
+            if (metadata_device >= 0) {
+                opened_device = metadata_device;
+            } else if (location == kWildcardLocation) {
+                // Older peers may still advertise the wildcard location. A
+                // current-device open is compatible, though it intentionally
+                // gives up the metadata-device optimization for that buffer.
+                LOG(WARNING)
+                    << "MusaTransport: wildcard IPC location; opening on "
+                       "the current device for compatibility";
+            } else {
+                LOG(ERROR) << "MusaTransport: invalid metadata device in "
+                           << location;
+                return musaErrorInvalidDevice;
+            }
+            if (opened_device != saved_device) {
+                cudaError_t set_err = cudaSetDevice(opened_device);
+                if (set_err != cudaSuccess) return set_err;
+            }
+        }
+
+        cudaError_t open_err = cudaIpcOpenMemHandle(
+            address, handle, cudaIpcMemLazyEnablePeerAccess);
+        cudaError_t restore_err = cudaSuccess;
+        if (opened_device != saved_device)
+            restore_err = cudaSetDevice(saved_device);
+
+        if (restore_err != cudaSuccess) {
+            if (open_err == cudaSuccess) {
+                cudaError_t close_err = cudaSetDevice(opened_device);
+                if (close_err == cudaSuccess) {
+                    cudaIpcCloseMemHandle(*address);
+                    cudaSetDevice(saved_device);
+                }
+            }
+            return restore_err;
+        }
+        return open_err;
+    }
+
+    cudaError_t closeIpcMemHandle(void* address,
+                                  int opened_device) const override {
+        int saved_device = -1;
+        cudaError_t saved_err = cudaGetDevice(&saved_device);
+        if (saved_err != cudaSuccess) return saved_err;
+
+        if (opened_device >= 0 && opened_device != saved_device) {
+            cudaError_t set_err = cudaSetDevice(opened_device);
+            if (set_err != cudaSuccess) return set_err;
+        }
+        cudaError_t close_err = cudaIpcCloseMemHandle(address);
+        if (opened_device >= 0 && opened_device != saved_device) {
+            cudaError_t restore_err = cudaSetDevice(saved_device);
+            if (close_err == cudaSuccess) close_err = restore_err;
+        }
+        return close_err;
+    }
+};
+
+}  // namespace
+
+MusaTransport::MusaTransport()
+    : NvlinkTransport(std::make_shared<MusaTransportPolicy>(), false) {}
+
+void* MusaTransport::allocatePinnedLocalMemory(size_t length) {
+    void* ptr = nullptr;
+    if (cudaMalloc(&ptr, length) != cudaSuccess) return nullptr;
+    return ptr;
+}
+
+void MusaTransport::freePinnedLocalMemory(void* addr) { cudaFree(addr); }
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/nccl_transport/nccl_transport.cpp b/mooncake-transfer-engine/src/transport/nccl_transport/nccl_transport.cpp
index a28a7b0248..f3b1ea11ab 100644
--- a/mooncake-transfer-engine/src/transport/nccl_transport/nccl_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/nccl_transport/nccl_transport.cpp
@@ -775,11 +775,16 @@ class NcclHostTransport::Impl {
             if (saved_device >= 0) cudaSetDevice(saved_device);
         }
 
-        status.transferred_bytes = task.transferred_bytes;
-        if (task.success_slice_count + task.failed_slice_count ==
-            task.slice_count) {
-            status.s = task.failed_slice_count ? TransferStatusEnum::FAILED
-                                               : TransferStatusEnum::COMPLETED;
+        uint64_t success_slice_count =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+        uint64_t failed_slice_count =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+        // Completion counters publish the preceding byte updates.
+        status.transferred_bytes =
+            __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
+        if (success_slice_count + failed_slice_count == task.slice_count) {
+            status.s = failed_slice_count ? TransferStatusEnum::FAILED
+                                          : TransferStatusEnum::COMPLETED;
             task.is_finished = true;
         } else {
             status.s = TransferStatusEnum::WAITING;
diff --git a/mooncake-transfer-engine/src/transport/nvlink_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/nvlink_transport/CMakeLists.txt
index 47067f5dd7..96c0ea634c 100644
--- a/mooncake-transfer-engine/src/transport/nvlink_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/nvlink_transport/CMakeLists.txt
@@ -1,6 +1,7 @@
 file(GLOB NVLINK_SOURCES "*.cpp")
 
 add_library(nvlink_transport OBJECT ${NVLINK_SOURCES})
+target_link_libraries(nvlink_transport PRIVATE glog::glog)
 
 if (USE_CUDA)
 target_include_directories(nvlink_transport PUBLIC ${CUDAToolkit_INCLUDE_DIRS})
diff --git a/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_host_numa_allocation.cpp b/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_host_numa_allocation.cpp
new file mode 100644
index 0000000000..faa95061d7
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_host_numa_allocation.cpp
@@ -0,0 +1,451 @@
+// Copyright 2024 KVCache.AI
+
+#include "transport/nvlink_transport/nvlink_host_numa_allocation.h"
+
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+
+#include <algorithm>
+#include <cstdlib>
+#include <limits>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <utility>
+
+#include <glog/logging.h>
+
+namespace mooncake {
+namespace {
+
+Status cudaFailure(const char* stage, CUresult result) {
+    return Status::Memory(std::string(stage) + " failed with CUDA result " +
+                          std::to_string(static_cast<int>(result)));
+}
+
+Status missingDriverFunction(const char* name) {
+    return Status::InvalidArgument(
+        std::string("missing CUDA driver adapter: ") + name);
+}
+
+bool isPowerOfTwo(size_t value) {
+    return value != 0 && (value & (value - 1)) == 0;
+}
+
+CUmemAllocationProp hostNumaProp(int numa_node) {
+    CUmemAllocationProp prop = {};
+    prop.type = CU_MEM_ALLOCATION_TYPE_PINNED;
+    prop.location.type = CU_MEM_LOCATION_TYPE_HOST_NUMA;
+    prop.location.id = numa_node;
+    prop.requestedHandleTypes = CU_MEM_HANDLE_TYPE_FABRIC;
+    return prop;
+}
+
+}  // namespace
+
+struct NvlinkHostNumaAllocation::OwnedRangeRegistry {
+    struct Entry {
+        size_t length;
+        DriverApi api;
+        bool releasing = false;
+        size_t registration_pins = 0;
+    };
+
+    std::mutex mutex;
+    std::unordered_map<void*, Entry> ranges;
+};
+
+NvlinkHostNumaAllocation::OwnedRangeRegistry&
+NvlinkHostNumaAllocation::OwnedRanges() {
+    static auto* registry = new OwnedRangeRegistry();
+    return *registry;
+}
+
+NvlinkHostNumaAllocation::DriverApi
+NvlinkHostNumaAllocation::ProductionDriverApi() {
+    return DriverApi{
+        cuDeviceGetCount,
+        cuDeviceGet,
+        cuDeviceGetAttribute,
+        cuMemGetAllocationGranularity,
+        cuMemCreate,
+        cuMemAddressReserve,
+        cuMemMap,
+        cuMemSetAccess,
+        cuMemUnmap,
+        cuMemAddressFree,
+        cuMemRelease,
+        cuMemRetainAllocationHandle,
+        cuMemExportToShareableHandle,
+    };
+}
+
+bool NvlinkHostNumaAllocation::RegisterOwnedRange(void* base, size_t length,
+                                                  const DriverApi& api) {
+    if (base == nullptr || length == 0) return false;
+    auto& registry = OwnedRanges();
+    std::lock_guard<std::mutex> lock(registry.mutex);
+    try {
+        return registry.ranges
+            .emplace(base, OwnedRangeRegistry::Entry{length, api})
+            .second;
+    } catch (...) {
+        return false;
+    }
+}
+
+bool NvlinkHostNumaAllocation::ReleaseOwnedRange(void* base, size_t length) {
+    auto& registry = OwnedRanges();
+    std::lock_guard<std::mutex> lock(registry.mutex);
+    auto entry = registry.ranges.find(base);
+    if (entry == registry.ranges.end() || entry->second.length != length ||
+        entry->second.registration_pins == 0)
+        return false;
+    --entry->second.registration_pins;
+    return true;
+}
+
+NvlinkHostNumaAllocation::OwnedRangeResult
+NvlinkHostNumaAllocation::AcquireOwnedRange(void* base, size_t length,
+                                            DriverApi* api) {
+    const uintptr_t begin = reinterpret_cast<uintptr_t>(base);
+    if (!api || !base || !length ||
+        length > std::numeric_limits<uintptr_t>::max() - begin)
+        return OwnedRangeResult::kInvalid;
+    auto& registry = OwnedRanges();
+    std::lock_guard<std::mutex> lock(registry.mutex);
+    auto entry = registry.ranges.find(base);
+    if (entry != registry.ranges.end()) {
+        if (entry->second.length != length) return OwnedRangeResult::kInvalid;
+        if (entry->second.releasing) return OwnedRangeResult::kUnavailable;
+        if (entry->second.registration_pins ==
+            std::numeric_limits<size_t>::max())
+            return OwnedRangeResult::kError;
+        try {
+            *api = entry->second.api;
+        } catch (...) {
+            return OwnedRangeResult::kError;
+        }
+        ++entry->second.registration_pins;
+        return OwnedRangeResult::kPinned;
+    }
+    const uintptr_t end = begin + length;
+    for (const auto& [owned_base, entry] : registry.ranges) {
+        const uintptr_t owned_begin = reinterpret_cast<uintptr_t>(owned_base);
+        const uintptr_t owned_end = owned_begin + entry.length;
+        if (begin < owned_end && owned_begin < end)
+            return OwnedRangeResult::kInvalid;
+    }
+    return OwnedRangeResult::kNotOwned;
+}
+
+bool NvlinkHostNumaAllocation::IsOwnedRangeBase(void* base) {
+    auto& registry = OwnedRanges();
+    std::lock_guard<std::mutex> lock(registry.mutex);
+    return registry.ranges.count(base) != 0;
+}
+
+Status NvlinkHostNumaAllocation::DiscoverHostNumaNodes(
+    std::vector<int>& numa_nodes) {
+    return DiscoverHostNumaNodesWithDriverApi(ProductionDriverApi(),
+                                              numa_nodes);
+}
+
+Status NvlinkHostNumaAllocation::ValidateVisibleGpuFabricSupportWithDriverApi(
+    const DriverApi& api, std::vector<CUdevice>& visible_devices) {
+    visible_devices.clear();
+    if (std::getenv("MC_USE_NVLINK_IPC") != nullptr)
+        return Status::NotSupportedTransport(
+            "MC_USE_NVLINK_IPC disables Fabric allocations");
+    if (!api.device_get_count) return missingDriverFunction("cuDeviceGetCount");
+    if (!api.device_get) return missingDriverFunction("cuDeviceGet");
+    if (!api.device_get_attribute)
+        return missingDriverFunction("cuDeviceGetAttribute");
+
+    int device_count = 0;
+    CUresult result = api.device_get_count(&device_count);
+    if (result != CUDA_SUCCESS) return cudaFailure("cuDeviceGetCount", result);
+    if (device_count <= 0)
+        return Status::DeviceNotFound("no visible CUDA device");
+
+    try {
+        visible_devices.reserve(static_cast<size_t>(device_count));
+    } catch (...) {
+        return Status::Memory("failed to record visible CUDA devices");
+    }
+    for (int ordinal = 0; ordinal < device_count; ++ordinal) {
+        CUdevice device;
+        result = api.device_get(&device, ordinal);
+        if (result != CUDA_SUCCESS) return cudaFailure("cuDeviceGet", result);
+
+        int vmm_supported = 0;
+        result = api.device_get_attribute(
+            &vmm_supported,
+            CU_DEVICE_ATTRIBUTE_VIRTUAL_MEMORY_MANAGEMENT_SUPPORTED, device);
+        if (result != CUDA_SUCCESS)
+            return cudaFailure("cuDeviceGetAttribute(VMM)", result);
+
+        int fabric_supported = 0;
+        result = api.device_get_attribute(
+            &fabric_supported, CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED,
+            device);
+        if (result != CUDA_SUCCESS)
+            return cudaFailure("cuDeviceGetAttribute(Fabric)", result);
+        if (!vmm_supported || !fabric_supported)
+            return Status::NotSupportedTransport(
+                "a visible CUDA device lacks VMM or Fabric handle support");
+
+#if CUDA_VERSION >= 12090
+        int host_numa_vmm_supported = 0;
+        result = api.device_get_attribute(
+            &host_numa_vmm_supported,
+            CU_DEVICE_ATTRIBUTE_HOST_NUMA_VIRTUAL_MEMORY_MANAGEMENT_SUPPORTED,
+            device);
+        if (result != CUDA_SUCCESS)
+            return cudaFailure("cuDeviceGetAttribute(HOST_NUMA VMM)", result);
+        if (!host_numa_vmm_supported)
+            return Status::NotSupportedTransport(
+                "a visible CUDA device lacks HOST_NUMA VMM support");
+#endif
+
+        visible_devices.push_back(device);
+    }
+    return Status::OK();
+}
+
+Status NvlinkHostNumaAllocation::DiscoverHostNumaNodesWithDriverApi(
+    const DriverApi& api, std::vector<int>& numa_nodes) {
+    numa_nodes.clear();
+    std::vector<CUdevice> visible_devices;
+    Status status =
+        ValidateVisibleGpuFabricSupportWithDriverApi(api, visible_devices);
+    if (!status.ok()) return status;
+
+    for (CUdevice device : visible_devices) {
+        int numa_node = -1;
+        CUresult result = api.device_get_attribute(
+            &numa_node, CU_DEVICE_ATTRIBUTE_HOST_NUMA_ID, device);
+        if (result != CUDA_SUCCESS)
+            return cudaFailure("cuDeviceGetAttribute(HOST_NUMA_ID)", result);
+        if (numa_node < 0)
+            return Status::Numa(
+                "a visible CUDA device has no GPU-local host NUMA node");
+        numa_nodes.push_back(numa_node);
+    }
+
+    std::sort(numa_nodes.begin(), numa_nodes.end());
+    numa_nodes.erase(std::unique(numa_nodes.begin(), numa_nodes.end()),
+                     numa_nodes.end());
+    for (int numa_node : numa_nodes) {
+        size_t ignored = 0;
+        status = GetAllocationGranularityWithDriverApi(numa_node, api, ignored);
+        if (!status.ok()) {
+            numa_nodes.clear();
+            return status;
+        }
+    }
+    return Status::OK();
+}
+
+Status NvlinkHostNumaAllocation::GetAllocationGranularity(int numa_node,
+                                                          size_t& granularity) {
+    return GetAllocationGranularityWithDriverApi(
+        numa_node, ProductionDriverApi(), granularity);
+}
+
+Status NvlinkHostNumaAllocation::GetAllocationGranularityWithDriverApi(
+    int numa_node, const DriverApi& api, size_t& granularity) {
+    granularity = 0;
+    if (numa_node < 0)
+        return Status::InvalidArgument("host NUMA node must be non-negative");
+    if (!api.mem_get_allocation_granularity)
+        return missingDriverFunction("cuMemGetAllocationGranularity");
+
+    CUmemAllocationProp prop = hostNumaProp(numa_node);
+    CUresult result = api.mem_get_allocation_granularity(
+        &granularity, &prop, CU_MEM_ALLOC_GRANULARITY_MINIMUM);
+    if (result != CUDA_SUCCESS)
+        return cudaFailure("cuMemGetAllocationGranularity(HOST_NUMA)", result);
+    if (!isPowerOfTwo(granularity)) {
+        granularity = 0;
+        return Status::Memory(
+            "HOST_NUMA allocation granularity is not a power of two");
+    }
+    return Status::OK();
+}
+
+Status NvlinkHostNumaAllocation::Create(
+    int numa_node, size_t requested_length, size_t required_va_alignment,
+    std::unique_ptr<NvlinkHostNumaAllocation>& allocation) {
+    return CreateWithDriverApi(numa_node, requested_length,
+                               required_va_alignment, ProductionDriverApi(),
+                               allocation);
+}
+
+Status NvlinkHostNumaAllocation::CreateWithDriverApi(
+    int numa_node, size_t requested_length, size_t required_va_alignment,
+    const DriverApi& api,
+    std::unique_ptr<NvlinkHostNumaAllocation>& allocation) {
+    if (allocation)
+        return Status::InvalidArgument("allocation output must be empty");
+    if (requested_length == 0)
+        return Status::InvalidArgument(
+            "HOST_NUMA allocation length must be greater than zero");
+    if (!api.mem_create) return missingDriverFunction("cuMemCreate");
+    if (!api.mem_address_reserve)
+        return missingDriverFunction("cuMemAddressReserve");
+    if (!api.mem_map) return missingDriverFunction("cuMemMap");
+    if (!api.mem_set_access) return missingDriverFunction("cuMemSetAccess");
+    if (!api.mem_unmap) return missingDriverFunction("cuMemUnmap");
+    if (!api.mem_address_free) return missingDriverFunction("cuMemAddressFree");
+    if (!api.mem_release) return missingDriverFunction("cuMemRelease");
+
+    std::vector<CUdevice> visible_devices;
+    Status status =
+        ValidateVisibleGpuFabricSupportWithDriverApi(api, visible_devices);
+    if (!status.ok()) return status;
+
+    size_t granularity = 0;
+    status = GetAllocationGranularityWithDriverApi(numa_node, api, granularity);
+    if (!status.ok()) return status;
+
+    size_t alignment =
+        required_va_alignment == 0 ? granularity : required_va_alignment;
+    if (!isPowerOfTwo(alignment) || alignment < granularity ||
+        alignment % granularity != 0) {
+        return Status::InvalidArgument(
+            "required VA alignment must be a power-of-two multiple of CUDA "
+            "granularity");
+    }
+    const size_t remainder = requested_length % alignment;
+    size_t length = requested_length;
+    if (remainder != 0) {
+        const size_t padding = alignment - remainder;
+        if (length > std::numeric_limits<size_t>::max() - padding)
+            return Status::InvalidArgument(
+                "HOST_NUMA allocation length overflows during alignment");
+        length += padding;
+    }
+
+    std::vector<CUmemAccessDesc> access_descs;
+    try {
+        access_descs.reserve(visible_devices.size() + 1);
+    } catch (...) {
+        return Status::Memory("failed to allocate CUDA access descriptors");
+    }
+    CUmemAccessDesc host_access = {};
+    host_access.location.type = CU_MEM_LOCATION_TYPE_HOST_NUMA;
+    host_access.location.id = numa_node;
+    host_access.flags = CU_MEM_ACCESS_FLAGS_PROT_READWRITE;
+    access_descs.push_back(host_access);
+    for (CUdevice device : visible_devices) {
+        CUmemAccessDesc device_access = {};
+        device_access.location.type = CU_MEM_LOCATION_TYPE_DEVICE;
+        device_access.location.id = device;
+        device_access.flags = CU_MEM_ACCESS_FLAGS_PROT_READWRITE;
+        access_descs.push_back(device_access);
+    }
+
+    auto owner = std::unique_ptr<NvlinkHostNumaAllocation>(
+        new NvlinkHostNumaAllocation());
+    owner->length_ = length;
+    owner->numa_node_ = numa_node;
+    owner->driver_api_ = api;
+
+    auto rollback = [&](Status cause) {
+        Status cleanup = owner->Release();
+        if (!cleanup.ok()) {
+            allocation = std::move(owner);
+            return Status::Memory(cause.ToString() + "; rollback incomplete: " +
+                                  cleanup.ToString());
+        }
+        return cause;
+    };
+
+    CUmemAllocationProp prop = hostNumaProp(numa_node);
+    CUmemGenericAllocationHandle handle;
+    CUresult result = api.mem_create(&handle, length, &prop, 0);
+    if (result != CUDA_SUCCESS) return cudaFailure("cuMemCreate", result);
+    owner->allocation_handle_ = static_cast<uint64_t>(handle);
+    owner->handle_owned_ = true;
+
+    CUdeviceptr ptr = 0;
+    result = api.mem_address_reserve(&ptr, length, alignment, 0, 0);
+    if (result != CUDA_SUCCESS)
+        return rollback(cudaFailure("cuMemAddressReserve", result));
+    owner->base_ = reinterpret_cast<void*>(ptr);
+    owner->address_reserved_ = true;
+
+    result = api.mem_map(ptr, length, 0, handle, 0);
+    if (result != CUDA_SUCCESS)
+        return rollback(cudaFailure("cuMemMap", result));
+    owner->mapped_ = true;
+
+    result = api.mem_set_access(ptr, length, access_descs.data(),
+                                access_descs.size());
+    if (result != CUDA_SUCCESS)
+        return rollback(cudaFailure("cuMemSetAccess", result));
+
+    if (!RegisterOwnedRange(owner->base_, owner->length_, api))
+        return rollback(
+            Status::Memory("failed to register HOST_NUMA owned range"));
+    owner->owned_range_registered_ = true;
+    allocation = std::move(owner);
+    return Status::OK();
+}
+
+NvlinkHostNumaAllocation::~NvlinkHostNumaAllocation() {
+    Status status = Release();
+    if (!status.ok())
+        LOG(ERROR) << "NvlinkHostNumaAllocation cleanup failed: " << status;
+}
+
+Status NvlinkHostNumaAllocation::Release() {
+    const CUdeviceptr ptr = reinterpret_cast<CUdeviceptr>(base_);
+    auto& registry = OwnedRanges();
+    std::unique_lock<std::mutex> registry_lock(registry.mutex, std::defer_lock);
+    if (owned_range_registered_) {
+        registry_lock.lock();
+        auto entry = registry.ranges.find(base_);
+        if (entry == registry.ranges.end() || entry->second.length != length_)
+            return Status::Memory("HOST_NUMA owned-range provenance missing");
+        if (entry->second.registration_pins != 0)
+            return Status::Memory("HOST_NUMA allocation is still registered");
+        entry->second.releasing = true;
+    }
+    if (mapped_) {
+        CUresult result = driver_api_.mem_unmap(ptr, length_);
+        if (result != CUDA_SUCCESS) return cudaFailure("cuMemUnmap", result);
+        mapped_ = false;
+    }
+    if (address_reserved_) {
+        CUresult result = driver_api_.mem_address_free(ptr, length_);
+        if (result != CUDA_SUCCESS)
+            return cudaFailure("cuMemAddressFree", result);
+        address_reserved_ = false;
+        base_ = nullptr;
+    }
+    if (owned_range_registered_) {
+        // Keep address-free and provenance removal atomic to new owners that
+        // may reserve the same VA. A later handle-release retry owns no VA.
+        registry.ranges.erase(reinterpret_cast<void*>(ptr));
+        owned_range_registered_ = false;
+    }
+    if (registry_lock.owns_lock()) registry_lock.unlock();
+    if (handle_owned_) {
+        const auto handle =
+            static_cast<CUmemGenericAllocationHandle>(allocation_handle_);
+        // Project policy treats a non-success result as retaining ownership,
+        // so a later close can retry the same release stage.
+        CUresult result = driver_api_.mem_release(handle);
+        if (result != CUDA_SUCCESS) return cudaFailure("cuMemRelease", result);
+        handle_owned_ = false;
+        allocation_handle_ = 0;
+    }
+    length_ = 0;
+    numa_node_ = -1;
+    return Status::OK();
+}
+
+}  // namespace mooncake
+
+#endif  // MOONCAKE_NVLINK_HOST_NUMA_ENABLED
diff --git a/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_transport.cpp b/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_transport.cpp
index bac4d625cd..1804f9a45d 100644
--- a/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/nvlink_transport/nvlink_transport.cpp
@@ -20,10 +20,15 @@
 
 #include <algorithm>
 #include <cassert>
+#include <cerrno>
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <iomanip>
+#include <limits>
+#include <map>
 #include <memory>
+#include <unordered_set>
 #include <vector>
 
 #include "common.h"
@@ -84,11 +89,18 @@ class PerDeviceStreamPool {
                   std::to_string(prop.pciBusID) + ":" +
                   std::to_string(prop.pciDeviceID);
         }
-        const char *visible = getenv("CUDA_VISIBLE_DEVICES");
+        const char *visible =
+#ifdef USE_MUSA
+            getenv("MUSA_VISIBLE_DEVICES");
+        constexpr const char *visible_name = "MUSA_VISIBLE_DEVICES";
+#else
+            getenv("CUDA_VISIBLE_DEVICES");
+        constexpr const char *visible_name = "CUDA_VISIBLE_DEVICES";
+#endif
         LOG(INFO) << "NvlinkTransport: NVLink CUDA stream created on device "
-                  << device_id << " [physical: " << pci
-                  << "] CUDA_VISIBLE_DEVICES="
-                  << (visible ? visible : "(not set)") << " pid=" << getpid();
+                  << device_id << " [physical: " << pci << "] " << visible_name
+                  << "=" << (visible ? visible : "(not set)")
+                  << " pid=" << getpid();
         pool_[device_id] = entry;
         return entry;
     }
@@ -155,6 +167,37 @@ static cudaEvent_t getCallerSyncEvent() {
     return tl_device_event_pool.getOrCreate(current_device);
 }
 
+// cudaMemcpyAsync is issued against the current device context on MUSA.  Keep
+// the caller's device intact while submitting work to a per-device stream.
+class ScopedCudaDevice {
+   public:
+    explicit ScopedCudaDevice(int device) {
+        status_ = cudaGetDevice(&saved_device_);
+        if (status_ != cudaSuccess) return;
+        if (saved_device_ != device) {
+            status_ = cudaSetDevice(device);
+            changed_ = status_ == cudaSuccess;
+        }
+    }
+
+    ~ScopedCudaDevice() {
+        if (changed_) {
+            cudaError_t err = cudaSetDevice(saved_device_);
+            if (err != cudaSuccess) {
+                LOG(ERROR) << "NvlinkTransport: failed to restore device "
+                           << saved_device_ << ": " << cudaGetErrorString(err);
+            }
+        }
+    }
+
+    bool ok() const { return status_ == cudaSuccess; }
+
+   private:
+    int saved_device_{-1};
+    cudaError_t status_{cudaSuccess};
+    bool changed_{false};
+};
+
 static int getDeviceForPointer(const void *ptr) {
     cudaPointerAttributes attr;
     if (cudaPointerGetAttributes(&attr, ptr) != cudaSuccess) {
@@ -164,13 +207,39 @@ static int getDeviceForPointer(const void *ptr) {
     return (attr.type == cudaMemoryTypeDevice) ? attr.device : -1;
 }
 
-static CudaStreamEntry getStreamForRequest(const void *source) {
-    int device_id = getDeviceForPointer(source);
-    if (device_id < 0) {
-        cudaGetDevice(&device_id);
-        if (device_id < 0) device_id = 0;
+class DefaultNvlinkTransportPolicy final : public GpuIpcTransportPolicy {
+   public:
+    const char *protocol() const override { return "nvlink"; }
+    const char *displayName() const override { return "NvlinkTransport"; }
+
+    int selectStreamDevice(const void *local_buffer, const void * /*source*/,
+                           const void * /*destination*/) const override {
+        int device_id = getDeviceForPointer(local_buffer);
+        if (device_id < 0) cudaGetDevice(&device_id);
+        return device_id < 0 ? 0 : device_id;
+    }
+
+    cudaError_t openIpcMemHandle(void **address, cudaIpcMemHandle_t handle,
+                                 const std::string & /*location*/,
+                                 int &opened_device) const override {
+        // Keep the legacy CUDA path byte-for-byte in terms of context
+        // ownership.  The recorded device is only needed by policies (MUSA)
+        // whose IPC close operation is context-sensitive.
+        opened_device = -1;
+        return cudaIpcOpenMemHandle(address, handle,
+                                    cudaIpcMemLazyEnablePeerAccess);
+    }
+
+    cudaError_t closeIpcMemHandle(void *address,
+                                  int /*opened_device*/) const override {
+        return cudaIpcCloseMemHandle(address);
     }
-    return tl_device_stream_pool.getOrCreate(device_id);
+};
+
+static std::shared_ptr<GpuIpcTransportPolicy> makeDefaultNvlinkPolicy() {
+    static std::shared_ptr<GpuIpcTransportPolicy> policy =
+        std::make_shared<DefaultNvlinkTransportPolicy>();
+    return policy;
 }
 
 }  // anonymous namespace
@@ -190,11 +259,42 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
                               const std::vector<void *> &srcs,
                               const std::vector<void *> &dsts,
                               const std::vector<size_t> &sizes,
-                              cudaStream_t stream) {
+                              const GpuIpcTransportPolicy *policy,
+                              cudaStream_t stream, int stream_device) {
     if (slices.empty()) return;
 
     const size_t count = slices.size();
-    cudaError_t err = cudaSuccess;
+
+    // A vendor policy may provide a lower-CPU batch primitive.  MUSA uses
+    // muMemoryTransferBatchAsync here; CUDA keeps the existing runtime paths
+    // below.  A handled failure is terminal for this group: retrying with
+    // per-slice copies could duplicate operations already accepted by the
+    // driver.
+    if (policy) {
+        size_t fail_index = std::numeric_limits<size_t>::max();
+        if (policy->submitBatchCopies(srcs, dsts, sizes, stream, fail_index)) {
+            if (fail_index == count) {
+                for (size_t i = 0; i < count; ++i) {
+                    slices[i]->status = Slice::POSTED;
+                    slices[i]->local.cuda_stream = (void *)stream;
+                    slices[i]->local.cuda_device = stream_device;
+                }
+            } else {
+                const size_t posted = fail_index < count ? fail_index : 0;
+                for (size_t i = 0; i < posted; ++i) {
+                    slices[i]->status = Slice::POSTED;
+                    slices[i]->local.cuda_stream = (void *)stream;
+                    slices[i]->local.cuda_device = stream_device;
+                }
+                for (size_t i = posted; i < count; ++i) {
+                    if (slices[i]->status == Slice::PENDING) {
+                        slices[i]->markFailed();
+                    }
+                }
+            }
+            return;
+        }
+    }
 
     // Log the active memcpy path once per process lifetime
     static const bool logged_once = [] {
@@ -213,6 +313,7 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
     (void)logged_once;
 
 #if CUDART_VERSION >= 12080
+    cudaError_t err = cudaSuccess;
     // srcAccessOrderStream is REQUIRED for P2P copies — without it, the GPU
     // does not insert necessary memory barriers for cross-device access,
     // resulting in segmentation faults. The caller also establishes a
@@ -246,6 +347,7 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
         for (size_t i = 0; i < count; ++i) {
             slices[i]->status = Slice::POSTED;
             slices[i]->local.cuda_stream = (void *)stream;
+            slices[i]->local.cuda_device = stream_device;
         }
     }
 #elif CUDART_VERSION >= 12080
@@ -265,14 +367,19 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
             LOG(ERROR) << "NvlinkTransport: cudaMemcpyBatchAsync "
                        << "failed: " << cudaGetErrorString(err);
         }
-        // Copies [0, fail_idx) were submitted successfully → POSTED.
+        // Copies [0, fail_idx) were submitted successfully → POSTED.  The
+        // runtime does not guarantee a useful index on every error; an
+        // out-of-range value therefore means that no slice is safe to mark
+        // POSTED.
         // Copy [fail_idx] failed → FAILED.
         // Copies (fail_idx, count) were never submitted → FAILED.
-        for (size_t i = 0; i < fail_idx; ++i) {
+        const size_t posted = fail_idx < count ? fail_idx : 0;
+        for (size_t i = 0; i < posted; ++i) {
             slices[i]->status = Slice::POSTED;
             slices[i]->local.cuda_stream = (void *)stream;
+            slices[i]->local.cuda_device = stream_device;
         }
-        for (size_t i = fail_idx; i < count; ++i) {
+        for (size_t i = posted; i < count; ++i) {
             if (slices[i]->status == Slice::PENDING) {
                 slices[i]->markFailed();
             }
@@ -281,6 +388,7 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
         for (size_t i = 0; i < count; ++i) {
             slices[i]->status = Slice::POSTED;
             slices[i]->local.cuda_stream = (void *)stream;
+            slices[i]->local.cuda_device = stream_device;
         }
     }
 #else
@@ -297,11 +405,156 @@ static void submitBatchMemcpy(const std::vector<Slice *> &slices,
         }
         slices[i]->status = Slice::POSTED;
         slices[i]->local.cuda_stream = (void *)stream;
+        slices[i]->local.cuda_device = stream_device;
     }
     return;  // Slice states already set above
 #endif
 }
 
+struct CopyGroup {
+    std::vector<Slice *> slices;
+    std::vector<void *> srcs;
+    std::vector<void *> dsts;
+    std::vector<size_t> sizes;
+    cudaStream_t stream{nullptr};
+};
+
+// A single Mooncake batch may contain requests targeting different GPU
+// ordinals.  MUSA groups by its policy-selected destination device so every
+// copy uses the matching stream/context.  NVIDIA intentionally keeps its
+// legacy behavior: one stream selected from the first request-local buffer.
+static bool submitBatchMemcpyByDevice(
+    const std::shared_ptr<GpuIpcTransportPolicy> &policy,
+    const std::vector<Slice *> &slices, const std::vector<void *> &srcs,
+    const std::vector<void *> &dsts, const std::vector<size_t> &sizes,
+    std::string &error) {
+    if (slices.empty()) return true;
+    if (srcs.size() != slices.size() || dsts.size() != slices.size() ||
+        sizes.size() != slices.size()) {
+        error =
+            std::string(policy->displayName()) + ": invalid copy vector sizes";
+        return false;
+    }
+
+    auto fail_pending = [](const std::vector<Slice *> &failed_slices) {
+        for (Slice *slice : failed_slices) {
+            if (slice && slice->status == Slice::PENDING) slice->markFailed();
+        }
+    };
+
+    auto prepare_stream = [&](int device, cudaStream_t &stream) {
+        CudaStreamEntry stream_entry =
+            tl_device_stream_pool.getOrCreate(device);
+        if (!stream_entry.stream) {
+            error = std::string(policy->displayName()) +
+                    ": failed to create transfer stream on device " +
+                    std::to_string(device);
+            return false;
+        }
+        if (policy->requiresStreamDeviceGuard()) {
+            ScopedCudaDevice guard(device);
+            if (!guard.ok()) {
+                error = std::string(policy->displayName()) +
+                        ": failed to select transfer device " +
+                        std::to_string(device);
+                return false;
+            }
+        }
+        stream = stream_entry.stream;
+        return true;
+    };
+
+    auto submit_group =
+        [&](int device, const std::vector<Slice *> &group_slices,
+            const std::vector<void *> &group_srcs,
+            const std::vector<void *> &group_dsts,
+            const std::vector<size_t> &group_sizes, cudaStream_t stream) {
+            if (policy->requiresStreamDeviceGuard()) {
+                ScopedCudaDevice guard(device);
+                if (!guard.ok()) {
+                    error = std::string(policy->displayName()) +
+                            ": failed to select transfer device " +
+                            std::to_string(device);
+                    return false;
+                }
+                submitBatchMemcpy(group_slices, group_srcs, group_dsts,
+                                  group_sizes, policy.get(), stream, device);
+                return true;
+            }
+            submitBatchMemcpy(group_slices, group_srcs, group_dsts, group_sizes,
+                              policy.get(), stream, device);
+            return true;
+        };
+
+    // Preserve the NVLink hot path and avoid allocation/copy overhead for the
+    // common MUSA case where every entry selects the same destination device.
+    int first_device = policy->selectStreamDevice(slices.front()->source_addr,
+                                                  srcs.front(), dsts.front());
+    if (first_device < 0) {
+        error = std::string(policy->displayName()) +
+                ": policy returned an invalid stream device";
+        fail_pending(slices);
+        return false;
+    }
+
+    bool homogeneous = true;
+    std::vector<int> devices;
+    if (policy->groupTransfersByDevice()) {
+        devices.reserve(slices.size());
+        devices.push_back(first_device);
+        for (size_t i = 1; i < slices.size(); ++i) {
+            int device = policy->selectStreamDevice(slices[i]->source_addr,
+                                                    srcs[i], dsts[i]);
+            if (device < 0) {
+                error = std::string(policy->displayName()) +
+                        ": policy returned an invalid stream device";
+                fail_pending(slices);
+                return false;
+            }
+            devices.push_back(device);
+            homogeneous = homogeneous && device == first_device;
+        }
+    }
+
+    if (!policy->groupTransfersByDevice() || homogeneous) {
+        cudaStream_t stream = nullptr;
+        if (!prepare_stream(first_device, stream) ||
+            !submit_group(first_device, slices, srcs, dsts, sizes, stream)) {
+            fail_pending(slices);
+            return false;
+        }
+        return true;
+    }
+
+    std::map<int, CopyGroup> groups;
+    auto append_to_group = [&](size_t i, int device) {
+        auto &group = groups[device];
+        group.slices.push_back(slices[i]);
+        group.srcs.push_back(srcs[i]);
+        group.dsts.push_back(dsts[i]);
+        group.sizes.push_back(sizes[i]);
+    };
+    for (size_t i = 0; i < slices.size(); ++i) append_to_group(i, devices[i]);
+
+    // Preflight every stream/context before submitting any group, so a setup
+    // failure cannot leave a mixed-device task half POSTED and half PENDING.
+    for (auto &[device, group] : groups) {
+        if (!prepare_stream(device, group.stream)) {
+            fail_pending(slices);
+            return false;
+        }
+    }
+
+    for (auto &[device, group] : groups) {
+        if (!submit_group(device, group.slices, group.srcs, group.dsts,
+                          group.sizes, group.stream)) {
+            fail_pending(slices);
+            return false;
+        }
+    }
+    return true;
+}
+
 static int getNumDevices() {
     static int cached_num_devices = -1;
     if (cached_num_devices == -1) {
@@ -392,7 +645,14 @@ static bool enableP2PAccess(int src_device_id, int dst_device_id) {
     return true;
 }
 
-NvlinkTransport::NvlinkTransport() : use_fabric_mem_(supportFabricMem()) {}
+NvlinkTransport::NvlinkTransport()
+    : NvlinkTransport(makeDefaultNvlinkPolicy(), supportFabricMem()) {}
+
+NvlinkTransport::NvlinkTransport(std::shared_ptr<GpuIpcTransportPolicy> policy,
+                                 bool use_fabric_mem)
+    : use_fabric_mem_(use_fabric_mem), policy_(std::move(policy)) {
+    if (!policy_) LOG(FATAL) << "NvlinkTransport requires a runtime policy";
+}
 //     int num_devices = getNumDevices();
 //     if (globalConfig().trace) {
 //         LOG(INFO) << "NvlinkTransport: use_fabric_mem_:" << use_fabric_mem_
@@ -427,10 +687,41 @@ NvlinkTransport::~NvlinkTransport() {
         }
     } else {
         for (auto &entry : remap_entries_) {
-            cudaIpcCloseMemHandle(entry.second.shm_addr);
+            cudaError_t close_err = policy_->closeIpcMemHandle(
+                entry.second.shm_addr, entry.second.device_id);
+            if (close_err != cudaSuccess) {
+                LOG(ERROR) << policy_->displayName()
+                           << ": cudaIpcCloseMemHandle failed: "
+                           << cudaGetErrorString(close_err);
+            }
         }
     }
     remap_entries_.clear();
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    std::lock_guard<std::mutex> lock(register_mutex_);
+    for (auto it = host_numa_registration_handles_.begin();
+         it != host_numa_registration_handles_.end();) {
+        void *address = (it++)->first;
+        const int rc = unregisterHostNumaMemoryLocked(
+            address, true,
+            [this](void *base, bool update) {
+                return metadata_
+                           ? metadata_->removeLocalMemoryBuffer(base, update)
+                           : ERR_METADATA;
+            },
+            [this]() {
+                return metadata_ ? metadata_->updateLocalSegmentDesc()
+                                 : ERR_METADATA;
+            });
+        if (rc != 0) {
+            // Destruction cannot offer a retry. Keep the registry pin so the
+            // allocation cannot unmap a range whose cleanup is incomplete.
+            LOG(ERROR) << "NvlinkTransport: HOST_NUMA cleanup incomplete for "
+                       << address << ": " << rc
+                       << "; unregister before destroying the transport";
+        }
+    }
+#endif
 }
 
 int NvlinkTransport::install(std::string &local_server_name,
@@ -442,7 +733,24 @@ int NvlinkTransport::install(std::string &local_server_name,
     auto desc = std::make_shared<SegmentDesc>();
     if (!desc) return ERR_MEMORY;
     desc->name = local_server_name_;
-    desc->protocol = "nvlink";
+#ifdef ENABLE_MULTI_PROTOCOL
+    if (policy_->preserveExistingMetadata()) {
+        auto old_desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
+        if (old_desc) *desc = *old_desc;
+        desc->name = local_server_name_;
+        if (desc->protocol.empty()) {
+            desc->protocol = policy_->protocol();
+        } else if (desc->protocol.find(policy_->protocol()) ==
+                   std::string::npos) {
+            desc->protocol += ",";
+            desc->protocol += policy_->protocol();
+        }
+    } else {
+        desc->protocol = policy_->protocol();
+    }
+#else
+    desc->protocol = policy_->protocol();
+#endif
     metadata_->addLocalSegment(LOCAL_SEGMENT_ID, local_server_name_,
                                std::move(desc));
     return 0;
@@ -463,12 +771,6 @@ Status NvlinkTransport::submitTransfer(
     size_t task_id = batch_desc.task_list.size();
     batch_desc.task_list.resize(task_id + entries.size());
 
-    // Get per-device transfer stream for the source buffer's device.
-    CudaStreamEntry stream_entry =
-        getStreamForRequest(entries.empty() ? nullptr : entries[0].source);
-    cudaStream_t stream = stream_entry.stream;
-    if (!stream) return Status::Context("Failed to create NVLink CUDA stream");
-
     // Synchronize with the caller's GPU work (e.g., PyTorch gather operations)
     // that produced the source data. We use cudaEventSynchronize (CPU-blocking)
     // instead of cudaStreamWaitEvent to avoid expensive cross-device event
@@ -529,8 +831,13 @@ Status NvlinkTransport::submitTransfer(
         slices.push_back(slice);
     }
 
-    // Phase 2: Submit all memcpy operations
-    submitBatchMemcpy(slices, srcs, dsts, sizes, stream);
+    // Phase 2: Let the backend choose the submission device after IPC address
+    // relocation, grouping a mixed-target batch by the selected device.
+    std::string submit_error;
+    if (!submitBatchMemcpyByDevice(policy_, slices, srcs, dsts, sizes,
+                                   submit_error)) {
+        return Status::Context(submit_error);
+    }
 
     return Status::OK();
 }
@@ -545,20 +852,31 @@ Status NvlinkTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    // Poll POSTED slices for async completion via cudaStreamQuery.
-    // Cache the query result per stream to avoid redundant driver calls.
-    // With SGLang-side torch.cuda.device(gpu_id), the calling thread's
-    // active device matches the stream's device, so no device switching
-    // is needed.
-    std::unordered_map<cudaStream_t, cudaError_t> stream_status_cache;
+    // Poll POSTED slices for async completion via cudaStreamQuery.  MUSA's
+    // destination-owned stream may differ from the caller's current device;
+    // its policy switches context for the query while CUDA keeps the legacy
+    // direct-query behavior.
+    std::map<int, std::unordered_map<cudaStream_t, cudaError_t>>
+        stream_status_cache;
     for (auto *slice : task.slice_list) {
         if (slice && slice->status == Slice::POSTED) {
             cudaStream_t stream = (cudaStream_t)slice->local.cuda_stream;
-            auto it = stream_status_cache.find(stream);
+            const int stream_device = slice->local.cuda_device;
+            auto &device_cache = stream_status_cache[stream_device];
+            auto it = device_cache.find(stream);
             cudaError_t cuda_err;
-            if (it == stream_status_cache.end()) {
-                cuda_err = cudaStreamQuery(stream);
-                stream_status_cache[stream] = cuda_err;
+            if (it == device_cache.end()) {
+                if (policy_->requiresStreamDeviceGuard()) {
+                    ScopedCudaDevice guard(stream_device);
+                    if (!guard.ok()) {
+                        slice->markFailed();
+                        continue;
+                    }
+                    cuda_err = cudaStreamQuery(stream);
+                } else {
+                    cuda_err = cudaStreamQuery(stream);
+                }
+                device_cache[stream] = cuda_err;
             } else {
                 cuda_err = it->second;
             }
@@ -569,9 +887,13 @@ Status NvlinkTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             }
         }
     }
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
@@ -587,11 +909,6 @@ Status NvlinkTransport::getTransferStatus(BatchID batch_id, size_t task_id,
 
 Status NvlinkTransport::submitTransferTask(
     const std::vector<TransferTask *> &task_list) {
-    // Get per-device transfer stream. See submitTransfer() for rationale.
-    CudaStreamEntry stream_entry = getStreamForRequest(
-        task_list.empty() ? nullptr : task_list[0]->request->source);
-    cudaStream_t stream = stream_entry.stream;
-    if (!stream) return Status::Context("Failed to create NVLink CUDA stream");
     // Synchronize with caller's GPU work via cudaEventSynchronize.
     cudaEvent_t sync_event = getCallerSyncEvent();
     cudaError_t sync_err = cudaEventRecord(sync_event, cudaStreamPerThread);
@@ -650,8 +967,12 @@ Status NvlinkTransport::submitTransferTask(
         slices.push_back(slice);
     }
 
-    // Phase 2: Submit all memcpy operations
-    submitBatchMemcpy(slices, srcs, dsts, sizes, stream);
+    // Phase 2: See submitTransfer() for backend-specific stream grouping.
+    std::string submit_error;
+    if (!submitBatchMemcpyByDevice(policy_, slices, srcs, dsts, sizes,
+                                   submit_error)) {
+        return Status::Context(submit_error);
+    }
 
     return Status::OK();
 }
@@ -689,11 +1010,28 @@ int NvlinkTransport::registerLocalMemory(void *addr, size_t length,
         BufferDesc desc;
         desc.addr = (uint64_t)addr;
         desc.length = length;
-        desc.name = location;
+        desc.name = policy_->normalizeMemoryLocation(addr, location);
         desc.shm_name =
             serializeBinaryData(&handle, sizeof(cudaIpcMemHandle_t));
+#ifdef ENABLE_MULTI_PROTOCOL
+        if (policy_->preserveExistingMetadata())
+            desc.protocol = policy_->protocol();
+#endif
         return metadata_->addLocalMemoryBuffer(desc, true);
     } else {
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+        const auto host_numa_result = registerHostNumaMemoryLocked(
+            addr, length, location, update_metadata,
+            [this](const BufferDesc &desc, bool update) {
+                return metadata_->addLocalMemoryBuffer(desc, update);
+            },
+            [this](void *base, bool update) {
+                return metadata_->removeLocalMemoryBuffer(base, update);
+            },
+            [this]() { return metadata_->updateLocalSegmentDesc(); });
+        if (host_numa_result) return *host_numa_result;
+#endif
+
         CUmemGenericAllocationHandle handle;
         auto result = cuMemRetainAllocationHandle(&handle, addr);
         if (result != CUDA_SUCCESS) {
@@ -730,15 +1068,252 @@ int NvlinkTransport::registerLocalMemory(void *addr, size_t length,
         BufferDesc desc;
         desc.addr = (uint64_t)real_addr;  // (uint64_t)addr;
         desc.length = real_size;          // length;
-        desc.name = location;
+        desc.name = policy_->normalizeMemoryLocation(addr, location);
         desc.shm_name =
             serializeBinaryData(&export_handle, sizeof(CUmemFabricHandle));
+#ifdef ENABLE_MULTI_PROTOCOL
+        if (policy_->preserveExistingMetadata())
+            desc.protocol = policy_->protocol();
+#endif
         return metadata_->addLocalMemoryBuffer(desc, true);
     }
 }
 
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+std::optional<int> NvlinkTransport::registerHostNumaMemoryLocked(
+    void *addr, size_t length, const std::string &location,
+    bool update_metadata, const AddLocalMemoryBufferOp &add_buffer,
+    const RemoveLocalMemoryBufferOp &remove_buffer,
+    const UpdateLocalSegmentDescOp &update_segment) {
+    auto previous = host_numa_registration_handles_.find(addr);
+    if (previous != host_numa_registration_handles_.end()) {
+        if (previous->second.registration_succeeded ||
+            previous->second.length != length)
+            return ERR_ADDRESS_OVERLAPPED;
+    }
+
+    NvlinkHostNumaAllocation::DriverApi driver_api;
+    using OwnedRangeResult = NvlinkHostNumaAllocation::OwnedRangeResult;
+    const auto range =
+        NvlinkHostNumaAllocation::AcquireOwnedRange(addr, length, &driver_api);
+    if (range == OwnedRangeResult::kNotOwned) {
+        if (previous != host_numa_registration_handles_.end())
+            return ERR_INVALID_ARGUMENT;
+        return std::nullopt;
+    }
+    if (range == OwnedRangeResult::kError) return ERR_MEMORY;
+    if (range != OwnedRangeResult::kPinned) return ERR_INVALID_ARGUMENT;
+
+    if (previous != host_numa_registration_handles_.end()) {
+        // Keep the new pin across old cleanup, so Release cannot recycle the
+        // VA between attempts. Deferred publication cannot waive old cleanup.
+        const int rc = unregisterHostNumaMemoryLocked(addr, true, remove_buffer,
+                                                      update_segment);
+        if (rc != 0) {
+            NvlinkHostNumaAllocation::ReleaseOwnedRange(addr, length);
+            return rc;
+        }
+    }
+
+    try {
+        HostNumaRegistration pending;
+        pending.api = std::move(driver_api);
+        pending.length = length;
+        const bool inserted =
+            host_numa_registration_handles_.emplace(addr, std::move(pending))
+                .second;
+        if (!inserted) {
+            NvlinkHostNumaAllocation::ReleaseOwnedRange(addr, length);
+            return ERR_ADDRESS_OVERLAPPED;
+        }
+    } catch (...) {
+        NvlinkHostNumaAllocation::ReleaseOwnedRange(addr, length);
+        return ERR_MEMORY;
+    }
+
+    auto registration = host_numa_registration_handles_.find(addr);
+    CUmemGenericAllocationHandle handle;
+    const auto &api = registration->second.api;
+    CUresult result = api.mem_retain_allocation_handle(&handle, addr);
+    if (result != CUDA_SUCCESS) {
+        LOG(WARNING) << "NvlinkTransport: failed to retain the exact HOST_NUMA "
+                        "allocation handle for "
+                     << addr << ": " << result;
+        const int cleanup_rc = unregisterHostNumaMemoryLocked(
+            addr, false, remove_buffer, update_segment);
+        if (cleanup_rc != 0)
+            LOG(ERROR) << "NvlinkTransport: HOST_NUMA pin cleanup failed: "
+                       << cleanup_rc;
+        return ERR_MEMORY;
+    }
+    registration->second.handle = handle;
+    registration->second.handle_owned = true;
+
+    CUmemFabricHandle export_handle;
+    result = api.mem_export_to_shareable_handle(&export_handle, handle,
+                                                CU_MEM_HANDLE_TYPE_FABRIC, 0);
+    if (result != CUDA_SUCCESS) {
+        LOG(ERROR) << "NvlinkTransport: failed to export the exact HOST_NUMA "
+                      "allocation handle for "
+                   << addr << ": " << result;
+        const int cleanup_rc = unregisterHostNumaMemoryLocked(
+            addr, false, remove_buffer, update_segment);
+        if (cleanup_rc != 0) {
+            LOG(ERROR) << "NvlinkTransport: failed to release retained "
+                          "HOST_NUMA handle after export failure for "
+                       << addr << ": " << cleanup_rc;
+        }
+        return ERR_MEMORY;
+    }
+
+    BufferDesc desc;
+    desc.addr = reinterpret_cast<uint64_t>(addr);
+    desc.length = length;
+    desc.name = location;
+    desc.shm_name =
+        serializeBinaryData(&export_handle, sizeof(CUmemFabricHandle));
+    registration->second.metadata_removed_locally = false;
+    registration->second.metadata_cleanup_complete = false;
+
+    const int publication_rc = add_buffer(desc, update_metadata);
+    if (publication_rc == 0) {
+        registration->second.registration_succeeded = true;
+        return 0;
+    }
+
+    const int rollback_rc = unregisterHostNumaMemoryLocked(
+        addr, update_metadata, remove_buffer, update_segment);
+    if (rollback_rc != 0) {
+        LOG(ERROR) << "NvlinkTransport: failed to roll back exact HOST_NUMA "
+                      "registration for "
+                   << addr << ": " << rollback_rc;
+    }
+    return publication_rc;
+}
+
+int NvlinkTransport::unregisterHostNumaMemoryLocked(
+    void *addr, bool update_metadata,
+    const RemoveLocalMemoryBufferOp &remove_buffer,
+    const UpdateLocalSegmentDescOp &update_segment) {
+    auto registration = host_numa_registration_handles_.find(addr);
+    if (registration == host_numa_registration_handles_.end())
+        return ERR_ADDRESS_NOT_REGISTERED;
+
+    if (!registration->second.metadata_removed_locally) {
+        const int rc = remove_buffer(addr, update_metadata);
+        if (rc == ERR_ADDRESS_NOT_REGISTERED) {
+            registration->second.metadata_removed_locally = true;
+            if (update_metadata) {
+                const int update_rc = update_segment();
+                if (update_rc != 0) return update_rc;
+            }
+            registration->second.metadata_cleanup_complete = update_metadata;
+        } else if (rc != 0) {
+            // removeLocalMemoryBuffer updates the local descriptor before it
+            // attempts external publication.
+            registration->second.metadata_removed_locally = true;
+            return rc;
+        } else {
+            registration->second.metadata_removed_locally = true;
+            registration->second.metadata_cleanup_complete = update_metadata;
+        }
+    } else if (!registration->second.metadata_cleanup_complete) {
+        if (!update_metadata) return 0;
+        const int rc = update_segment();
+        if (rc != 0) return rc;
+        registration->second.metadata_cleanup_complete = true;
+    }
+
+    // Deferred deletion is not permission to unmap the allocation. The batch
+    // publisher (or a later unregister with update_metadata=true) completes it.
+    if (!registration->second.metadata_cleanup_complete) return 0;
+
+    // Project policy treats a non-success result as retaining this reference,
+    // so the registration record remains available for a later retry.
+    if (registration->second.handle_owned) {
+        CUresult result =
+            registration->second.api.mem_release(registration->second.handle);
+        if (result != CUDA_SUCCESS) {
+            LOG(ERROR)
+                << "NvlinkTransport: failed to release retained HOST_NUMA "
+                   "registration handle for "
+                << addr << ": " << result;
+            return ERR_MEMORY;
+        }
+        registration->second.handle_owned = false;
+    }
+    if (!NvlinkHostNumaAllocation::ReleaseOwnedRange(
+            addr, registration->second.length))
+        return ERR_MEMORY;
+    host_numa_registration_handles_.erase(registration);
+    return 0;
+}
+
+int NvlinkTransport::unregisterHostNumaMemoryBatchLocked(
+    const std::vector<void *> &addr_list,
+    const RemoveLocalMemoryBufferOp &remove_buffer,
+    const UpdateLocalSegmentDescOp &update_segment) {
+    int first_error = 0;
+    bool needs_publication = false;
+    for (void *addr : addr_list) {
+        auto registration = host_numa_registration_handles_.find(addr);
+        int rc = 0;
+        if (registration != host_numa_registration_handles_.end()) {
+            // Completed publication need not be repeated after a release
+            // failure. Other records wait for the single batch publication.
+            if (!registration->second.metadata_cleanup_complete) {
+                rc = unregisterHostNumaMemoryLocked(addr, false, remove_buffer,
+                                                    update_segment);
+                needs_publication = true;
+            }
+        } else if (!NvlinkHostNumaAllocation::IsOwnedRangeBase(addr)) {
+            // Keep legacy address/error semantics. Owned addresses without a
+            // record are already done, including on a partial-batch retry.
+            rc = remove_buffer(addr, false);
+            needs_publication = true;
+        }
+        if (rc != 0 && first_error == 0) first_error = rc;
+    }
+
+    if (needs_publication) {
+        const int rc = update_segment();
+        if (rc != 0) return first_error ? first_error : rc;
+        for (void *addr : addr_list) {
+            auto registration = host_numa_registration_handles_.find(addr);
+            if (registration != host_numa_registration_handles_.end() &&
+                registration->second.metadata_removed_locally)
+                registration->second.metadata_cleanup_complete = true;
+        }
+    }
+
+    std::unordered_set<void *> finalized;
+    for (void *addr : addr_list) {
+        if (!finalized.insert(addr).second) continue;
+        if (host_numa_registration_handles_.count(addr) == 0) continue;
+        const int rc = unregisterHostNumaMemoryLocked(
+            addr, false, remove_buffer, update_segment);
+        if (rc != 0 && first_error == 0) first_error = rc;
+    }
+    return first_error;
+}
+#endif
+
 int NvlinkTransport::unregisterLocalMemory(void *addr, bool update_metadata) {
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    std::unique_lock<std::mutex> lock(register_mutex_);
+    if (host_numa_registration_handles_.count(addr) == 0) {
+        lock.unlock();
+        return metadata_->removeLocalMemoryBuffer(addr, update_metadata);
+    }
+    return unregisterHostNumaMemoryLocked(
+        addr, update_metadata,
+        [this](void *base, bool update) {
+            return metadata_->removeLocalMemoryBuffer(base, update);
+        },
+        [this]() { return metadata_->updateLocalSegmentDesc(); });
+#else
     return metadata_->removeLocalMemoryBuffer(addr, update_metadata);
+#endif
 }
 
 int NvlinkTransport::relocateSharedMemoryAddress(uint64_t &dest_addr,
@@ -768,17 +1343,21 @@ int NvlinkTransport::relocateSharedMemoryAddress(uint64_t &dest_addr,
                     cudaIpcMemHandle_t handle;
                     memcpy(&handle, output_buffer.data(), sizeof(handle));
                     void *shm_addr = nullptr;
-                    cudaError_t err = cudaIpcOpenMemHandle(
-                        &shm_addr, handle, cudaIpcMemLazyEnablePeerAccess);
+                    int ipc_device = -1;
+                    cudaError_t err = policy_->openIpcMemHandle(
+                        &shm_addr, handle, entry.name, ipc_device);
                     if (err != cudaSuccess) {
-                        LOG(ERROR)
-                            << "NvlinkTransport: cudaIpcOpenMemHandle failed: "
-                            << cudaGetErrorString(err);
+                        LOG(ERROR) << policy_->displayName()
+                                   << ": cudaIpcOpenMemHandle failed: "
+                                   << cudaGetErrorString(err);
                         return -1;
                     }
                     OpenedShmEntry shm_entry;
                     shm_entry.shm_addr = shm_addr;
                     shm_entry.length = entry.length;
+#ifdef USE_MUSA
+                    shm_entry.device_id = ipc_device;
+#endif
                     remap_entries_[std::make_pair(target_id, entry.addr)] =
                         shm_entry;
                 } else if (output_buffer.size() == sizeof(CUmemFabricHandle) &&
@@ -865,6 +1444,15 @@ int NvlinkTransport::registerLocalMemoryBatch(
 
 int NvlinkTransport::unregisterLocalMemoryBatch(
     const std::vector<void *> &addr_list) {
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+    std::lock_guard<std::mutex> lock(register_mutex_);
+    return unregisterHostNumaMemoryBatchLocked(
+        addr_list,
+        [this](void *base, bool update) {
+            return metadata_->removeLocalMemoryBuffer(base, update);
+        },
+        [this]() { return metadata_->updateLocalSegmentDesc(); });
+#else
     int first_error = 0;
     for (auto &addr : addr_list) {
         int ret = unregisterLocalMemory(addr, false);
@@ -872,6 +1460,7 @@ int NvlinkTransport::unregisterLocalMemoryBatch(
     }
     int metadata_ret = metadata_->updateLocalSegmentDesc();
     return first_error ? first_error : metadata_ret;
+#endif
 }
 
 void *NvlinkTransport::allocatePinnedLocalMemory(size_t size) {
diff --git a/mooncake-transfer-engine/src/transport/nvmeof_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/nvmeof_transport/CMakeLists.txt
index 51c1982283..8cb041f412 100644
--- a/mooncake-transfer-engine/src/transport/nvmeof_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/nvmeof_transport/CMakeLists.txt
@@ -2,4 +2,5 @@ file(GLOB NVMEOF_SOURCES "*.cpp")
 
 add_library(nvmeof_transport OBJECT ${NVMEOF_SOURCES})
 target_include_directories(nvmeof_transport PUBLIC ${CUDAToolkit_INCLUDE_DIRS})
-# target_link_libraries(nvmeof_transport PUBLIC transport)
\ No newline at end of file
+target_link_libraries(nvmeof_transport PUBLIC glog::glog)
+# target_link_libraries(nvmeof_transport PUBLIC transport)
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/rdma_transport/CMakeLists.txt
index dc2c10eab1..6bb67f495d 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/CMakeLists.txt
@@ -1,8 +1,15 @@
 file(GLOB RDMA_SOURCES "*.cpp")
 
 add_library(rdma_transport OBJECT ${RDMA_SOURCES})
-target_link_libraries(rdma_transport PRIVATE JsonCpp::JsonCpp glog::glog
-                                             pthread)
+target_link_libraries(
+  rdma_transport
+  PUBLIC gflags::gflags glog::glog
+  PRIVATE JsonCpp::JsonCpp pthread)
+
+if(USE_CUDA)
+  target_compile_definitions(rdma_transport PRIVATE _GNU_SOURCE)
+  target_link_libraries(rdma_transport PUBLIC ${CMAKE_DL_LIBS})
+endif()
 
 if(USE_MLX5DV)
   target_compile_definitions(rdma_transport PRIVATE USE_MLX5DV)
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/endpoint_store.cpp b/mooncake-transfer-engine/src/transport/rdma_transport/endpoint_store.cpp
index 54db6de43a..4385983c1f 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/endpoint_store.cpp
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/endpoint_store.cpp
@@ -47,22 +47,26 @@ std::shared_ptr<RdmaEndPoint> FIFOEndpointStore::getEndpointByPtr(
 }
 
 std::shared_ptr<RdmaEndPoint> FIFOEndpointStore::insertEndpoint(
-    const std::string &peer_nic_path, RdmaContext *context) {
+    const std::string &peer_nic_path, RdmaContext *context, ibv_cq *cq) {
     RWSpinlock::WriteGuard guard(endpoint_map_lock_);
     if (endpoint_map_.find(peer_nic_path) != endpoint_map_.end()) {
         LOG(INFO) << "Endpoint " << peer_nic_path
                   << " already exists in FIFOEndpointStore";
         return endpoint_map_[peer_nic_path];
     }
+    if (!cq) {
+        LOG(ERROR) << "Cannot insert endpoint " << peer_nic_path
+                   << ": completion queue is null";
+        return nullptr;
+    }
     auto endpoint = std::make_shared<RdmaEndPoint>(*context);
     if (!endpoint) {
         LOG(ERROR) << "Failed to allocate memory for RdmaEndPoint";
         return nullptr;
     }
     auto &config = globalConfig();
-    int ret =
-        endpoint->construct(context->cq(), config.num_qp_per_ep, config.max_sge,
-                            config.max_wr, config.max_inline);
+    int ret = endpoint->construct(cq, config.num_qp_per_ep, config.max_sge,
+                                  config.max_wr, config.max_inline);
     if (ret) return nullptr;
 
     while (this->getSize() >= max_size_) evictEndpoint();
@@ -80,8 +84,9 @@ int FIFOEndpointStore::deleteEndpoint(const std::string &peer_nic_path) {
     auto iter = endpoint_map_.find(peer_nic_path);
     // Begin two-phase destruction: mark endpoint as destroying and move QPs
     // to ERR state so inflight WRs are flushed to CQ. The endpoint is moved
-    // to waiting_list_ and will be fully destroyed by reclaimEndpoint() once
-    // all outstanding WRs have been drained.
+    // to waiting_list_ and will be fully destroyed by reclaimEndpoint() only
+    // after all outstanding WRs have been drained. Timed-out endpoints remain
+    // retired in waiting_list_ rather than being force-freed.
     if (iter != endpoint_map_.end()) {
         waiting_list_len_++;
         iter->second->beginDestroy();
@@ -220,22 +225,26 @@ std::shared_ptr<RdmaEndPoint> SIEVEEndpointStore::getEndpointByPtr(
 }
 
 std::shared_ptr<RdmaEndPoint> SIEVEEndpointStore::insertEndpoint(
-    const std::string &peer_nic_path, RdmaContext *context) {
+    const std::string &peer_nic_path, RdmaContext *context, ibv_cq *cq) {
     RWSpinlock::WriteGuard guard(endpoint_map_lock_);
     if (endpoint_map_.find(peer_nic_path) != endpoint_map_.end()) {
         LOG(INFO) << "Endpoint " << peer_nic_path
                   << " already exists in SIEVEEndpointStore";
         return endpoint_map_[peer_nic_path].first;
     }
+    if (!cq) {
+        LOG(ERROR) << "Cannot insert endpoint " << peer_nic_path
+                   << ": completion queue is null";
+        return nullptr;
+    }
     auto endpoint = std::make_shared<RdmaEndPoint>(*context);
     if (!endpoint) {
         LOG(ERROR) << "Failed to allocate memory for RdmaEndPoint";
         return nullptr;
     }
     auto &config = globalConfig();
-    int ret =
-        endpoint->construct(context->cq(), config.num_qp_per_ep, config.max_sge,
-                            config.max_wr, config.max_inline);
+    int ret = endpoint->construct(cq, config.num_qp_per_ep, config.max_sge,
+                                  config.max_wr, config.max_inline);
     if (ret) return nullptr;
 
     while (this->getSize() >= max_size_) evictEndpoint();
@@ -252,8 +261,9 @@ int SIEVEEndpointStore::deleteEndpoint(const std::string &peer_nic_path) {
     auto iter = endpoint_map_.find(peer_nic_path);
     // Begin two-phase destruction: mark endpoint as destroying and move QPs
     // to ERR state so inflight WRs are flushed to CQ. The endpoint is moved
-    // to waiting_list_ and will be fully destroyed by reclaimEndpoint() once
-    // all outstanding WRs have been drained.
+    // to waiting_list_ and will be fully destroyed by reclaimEndpoint() only
+    // after all outstanding WRs have been drained. Timed-out endpoints remain
+    // retired in waiting_list_ rather than being force-freed.
     if (iter != endpoint_map_.end()) {
         iter->second.first->beginDestroy();
         waiting_list_len_++;
@@ -377,6 +387,14 @@ void SIEVEEndpointStore::testOnlyInsertWaiting(
     waiting_list_len_++;
 }
 
+void SIEVEEndpointStore::testOnlyInsertEndpoint(
+    const std::string &peer_nic_path, std::shared_ptr<RdmaEndPoint> ep) {
+    RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+    endpoint_map_[peer_nic_path] = std::make_pair(ep, true);
+    fifo_list_.push_front(peer_nic_path);
+    fifo_map_[peer_nic_path] = fifo_list_.begin();
+}
+
 size_t SIEVEEndpointStore::getTotalQPNumber() {
     RWSpinlock::ReadGuard guard(endpoint_map_lock_);
     size_t total_qps = 0;
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_context.cpp b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_context.cpp
index a8e395fbd3..e95d7da242 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_context.cpp
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_context.cpp
@@ -20,12 +20,21 @@
 #include <fcntl.h>
 #include <netinet/in.h>
 #include <sys/epoll.h>
+#include <sys/mman.h>
 #include <unistd.h>
+#ifdef USE_CUDA
+#include <dlfcn.h>
+#include <infiniband/mlx5dv.h>
+#endif
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
 
 #include <atomic>
 #include <cassert>
 #include <exception>
 #include <fstream>
+#include <functional>
 #include <memory>
 #include <thread>
 
@@ -57,6 +66,39 @@ static int isNullGid(union ibv_gid *gid) {
 }
 
 namespace {
+#ifdef USE_CUDA
+#if CUDA_VERSION < 12080
+#define CU_MEM_RANGE_FLAG_DMA_BUF_MAPPING_TYPE_PCIE 0x1
+#endif
+#ifndef MLX5DV_REG_DMABUF_ACCESS_DATA_DIRECT
+#define MLX5DV_REG_DMABUF_ACCESS_DATA_DIRECT (1 << 0)
+#endif
+using Mlx5RegDmabufMr = ibv_mr *(*)(ibv_pd *, uint64_t, size_t, uint64_t, int,
+                                    int, int);
+
+static Mlx5RegDmabufMr dataDirectRegMr() {
+    static const Mlx5RegDmabufMr reg_mr = []() -> Mlx5RegDmabufMr {
+        dlerror();
+        void *handle = dlopen("libmlx5.so.1", RTLD_NOW | RTLD_LOCAL);
+        if (!handle) {
+            LOG(ERROR) << "MC_RDMA_DATA_DIRECT cannot load libmlx5: "
+                       << dlerror();
+            return nullptr;
+        }
+        void *symbol = dlvsym(handle, "mlx5dv_reg_dmabuf_mr", "MLX5_1.25");
+        if (!symbol) {
+            const char *error = dlerror();
+            LOG(ERROR) << "MC_RDMA_DATA_DIRECT requires "
+                          "mlx5dv_reg_dmabuf_mr@MLX5_1.25 in libmlx5"
+                       << (error ? std::string(": ") + error : "");
+            dlclose(handle);
+        }
+        return reinterpret_cast<Mlx5RegDmabufMr>(symbol);
+    }();
+    return reg_mr;
+}
+#endif
+
 bool containsAddress(const MemoryRegionMeta &region, uintptr_t addr) {
     const auto region_start = reinterpret_cast<uintptr_t>(region.addr);
     const auto region_length = static_cast<uintptr_t>(region.mr->length);
@@ -165,7 +207,6 @@ RdmaContext::RdmaContext(RdmaTransport &engine, const std::string &device_name)
           [] { return static_cast<uint64_t>(getCurrentTimeInNano()); }),
       next_comp_channel_index_(0),
       next_comp_vector_index_(0),
-      next_cq_list_index_(0),
       worker_pool_(nullptr),
       active_(true) {
     static std::once_flag g_once_flag;
@@ -194,6 +235,23 @@ int RdmaContext::construct(size_t num_cq_list, size_t num_comp_channels,
 
     // Create endpoint store based on configuration
     auto &config = globalConfig();
+    if (config.workers_per_ctx <= 0) {
+        LOG(ERROR) << "Invalid workers_per_ctx=" << config.workers_per_ctx
+                   << " for device " << device_name_;
+        return ERR_INVALID_ARGUMENT;
+    }
+    transfer_worker_count_ = config.workers_per_ctx;
+    if (num_cq_list < static_cast<size_t>(transfer_worker_count_)) {
+        LOG(INFO) << "Increasing RDMA CQ count for " << device_name_ << " from "
+                  << num_cq_list << " to " << transfer_worker_count_
+                  << " to keep each transfer worker on a dedicated CQ";
+        num_cq_list = static_cast<size_t>(transfer_worker_count_);
+    }
+    endpoint_lifecycle_locks_.clear();
+    endpoint_lifecycle_locks_.reserve(
+        static_cast<size_t>(transfer_worker_count_));
+    for (int i = 0; i < transfer_worker_count_; ++i)
+        endpoint_lifecycle_locks_.push_back(std::make_unique<std::mutex>());
     switch (config.endpoint_store_type) {
         case EndpointStoreType::FIFO:
             endpoint_store_ =
@@ -209,7 +267,7 @@ int RdmaContext::construct(size_t num_cq_list, size_t num_comp_channels,
     }
     if (openRdmaDevice(device_name_, port, gid_index)) {
         LOG(ERROR) << "Failed to open device " << device_name_ << " on port "
-                   << port << " with GID " << gid_index;
+                   << static_cast<int>(port) << " with GID " << gid_index;
         return ERR_CONTEXT;
     }
 
@@ -274,6 +332,16 @@ int RdmaContext::construct(size_t num_cq_list, size_t num_comp_channels,
         cq_list_[i].native = cq;
     }
 
+    native_notify_enabled_ = globalConfig().rdma_notify_enabled &&
+                             std::string(engine_.getName()) == "rdma";
+    if (native_notify_enabled_) {
+        notify_cq_ = ibv_create_cq(context_, globalConfig().max_cqe, nullptr,
+                                   nullptr, 0);
+        if (!notify_cq_) {
+            PLOG(ERROR) << "Failed to create notification completion queue";
+            return ERR_CONTEXT;
+        }
+    }
     worker_pool_ = std::make_shared<WorkerPool>(*this, socketId());
 
 #ifdef USE_MLX5DV
@@ -294,6 +362,45 @@ int RdmaContext::construct(size_t num_cq_list, size_t num_comp_channels,
     return 0;
 }
 
+void RdmaContext::registerNotifyQp(
+    uint32_t qp_num, const std::weak_ptr<RdmaEndPoint> &endpoint) {
+    std::lock_guard<std::mutex> guard(notify_mutex_);
+    notify_endpoints_[qp_num] = endpoint;
+}
+
+void RdmaContext::unregisterNotifyQp(uint32_t qp_num) {
+    std::lock_guard<std::mutex> guard(notify_mutex_);
+    notify_endpoints_.erase(qp_num);
+}
+
+void RdmaContext::dispatchNotificationCompletion(
+    const ibv_wc &wc, std::vector<TransferMetadata::NotifyDesc> &received) {
+    std::shared_ptr<RdmaEndPoint> endpoint;
+    {
+        std::lock_guard<std::mutex> guard(notify_mutex_);
+        auto it = notify_endpoints_.find(wc.qp_num);
+        if (it != notify_endpoints_.end()) endpoint = it->second.lock();
+    }
+    // Never acquire endpoint locks under notify_mutex_. Teardown takes them
+    // in the opposite direction. The strong reference protects this callback.
+    if (endpoint) endpoint->handleNotificationCompletion(wc, received);
+}
+
+int RdmaContext::pollNotificationCq() {
+    if (!notify_cq_) return 0;
+    ibv_wc completions[32];
+    const int count = ibv_poll_cq(notify_cq_, 32, completions);
+    if (count < 0) {
+        PLOG(ERROR) << "Failed to poll notification completion queue";
+        return count;
+    }
+    std::vector<TransferMetadata::NotifyDesc> received;
+    for (int i = 0; i < count; ++i)
+        dispatchNotificationCompletion(completions[i], received);
+    for (const auto &message : received) engine_.meta()->pushNotify(message);
+    return count;
+}
+
 int RdmaContext::socketId() {
     std::string path =
         "/sys/class/infiniband/" + device_name_ + "/device/numa_node";
@@ -334,6 +441,16 @@ int RdmaContext::deconstruct() {
         }
     }
 
+    // All endpoint QPs must be destroyed before the shared notification CQ.
+    if (notify_cq_) {
+        if (ibv_destroy_cq(notify_cq_)) {
+            LOG(ERROR) << "Failed to destroy shared notification CQ";
+        } else {
+            notify_cq_ = nullptr;
+        }
+    }
+    notify_endpoints_.clear();
+
     for (auto &[_, entry] : memory_region_map_) {
         int ret = ibv_dereg_mr(entry.mr);
         if (ret) {
@@ -389,9 +506,19 @@ int RdmaContext::deconstruct() {
     return 0;
 }
 
-int RdmaContext::exportDmabuf(void *addr, DmabufExport &out) {
+int RdmaContext::exportDmabuf(void *addr, size_t length, DmabufExport &out) {
     out = DmabufExport{};
     (void)addr;  // unused on the host-only (#else) build
+    (void)length;
+    const bool data_direct = Environ::Get().GetRdmaDataDirect();
+    if (data_direct) {
+#ifdef USE_CUDA
+        if (!dataDirectRegMr()) return ERR_CONTEXT;
+#else
+        LOG(ERROR) << "MC_RDMA_DATA_DIRECT requires a CUDA build";
+        return ERR_CONTEXT;
+#endif
+    }
 #if defined(USE_MLU) || defined(USE_MACA) || defined(USE_CUDA) || \
     defined(USE_SUPA)
     // Decide host vs GPU without assuming the presence of nvidia-peermem. Host
@@ -406,7 +533,7 @@ int RdmaContext::exportDmabuf(void *addr, DmabufExport &out) {
         out.method = DmabufExport::Method::kHostReg;
 #if defined(USE_CUDA) || defined(USE_SUPA)
     } else if (memType == CU_MEMORYTYPE_DEVICE &&
-               Environ::Get().GetWithNvidiaPeermem()) {
+               Environ::Get().GetWithNvidiaPeermem() && !data_direct) {
         // WITH_NVIDIA_PEERMEM env var is set: use ibv_reg_mr() directly for
         // GPU memory (requires the nvidia-peermem kernel module to be loaded).
         out.method = DmabufExport::Method::kHostReg;
@@ -446,17 +573,62 @@ int RdmaContext::exportDmabuf(void *addr, DmabufExport &out) {
         }
 
         int dmabuf_fd;
-        // flags must be 0: the PCIE-BAR1 mapping flag is rejected (error 801)
-        // on some GPU/driver combinations (e.g. B200).
+        // cuMemGetAddressRange() only reports the mapping that contains addr.
+        // For memory allocated through the CUDA virtual memory management API
+        // (cuMemCreate + cuMemMap), as used by PyTorch's
+        // PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True, that mapping is a
+        // single growth chunk — 20 MiB by default, see c10's
+        // large_segment_size / large_segment_size_mb — even though the
+        // surrounding VA reservation is contiguous and orders of magnitude
+        // larger. Exporting only that chunk makes offset + length exceed the
+        // resulting dma_buf, and ibv_reg_dmabuf_mr() below then fails with
+        // EINVAL for every buffer larger than one chunk (Mooncake#2511).
+        //
+        // When the reported allocation does not cover the range the caller is
+        // about to register, export exactly [addr, addr + length) instead.
+        // cuMemGetHandleForAddressRange() accepts a range spanning several
+        // mappings as long as they are contiguously mapped, which is precisely
+        // the expandable-segment layout. The export base is page-aligned so
+        // that offset % page_size == iova % page_size, which
+        // ibv_reg_dmabuf_mr() requires.
+        CUdeviceptr exportBase = allocBase;
+        size_t exportSize = allocSize;
+        uint64_t exportOffset = (uintptr_t)addr - (uintptr_t)allocBase;
+        if (exportOffset + length > allocSize) {
+            const size_t page = (size_t)sysconf(_SC_PAGESIZE);
+            uintptr_t aligned = (uintptr_t)addr & ~(uintptr_t)(page - 1);
+            if (aligned < (uintptr_t)allocBase) aligned = (uintptr_t)allocBase;
+            exportBase = (CUdeviceptr)aligned;
+            exportOffset = (uintptr_t)addr - aligned;
+            exportSize =
+                (exportOffset + length + page - 1) & ~(size_t)(page - 1);
+            VLOG(1) << "dma_buf: reported allocation for " << (uintptr_t)addr
+                    << " (base=" << (uintptr_t)allocBase
+                    << " size=" << allocSize << ") does not cover length "
+                    << length << "; exporting the requested range instead"
+                    << " (base=" << (uintptr_t)exportBase
+                    << " size=" << exportSize
+                    << "). Expected for CUDA VMM allocations such as PyTorch"
+                       " expandable_segments.";
+        }
+
+        // Without Data Direct, flags must be 0: the PCIE-BAR1 mapping flag is
+        // rejected (error 801) on some GPU/driver combinations (e.g. B200).
+        unsigned long long export_flags = 0;
+#ifdef USE_CUDA
+        if (data_direct)
+            export_flags = CU_MEM_RANGE_FLAG_DMA_BUF_MAPPING_TYPE_PCIE;
+#endif
         result = cuMemGetHandleForAddressRange(
-            &dmabuf_fd, allocBase, allocSize,
-            CU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD, 0);
+            &dmabuf_fd, exportBase, exportSize,
+            CU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD, export_flags);
         if (result != CUDA_SUCCESS) {
             const char *errStr;
             cuGetErrorString(result, &errStr);
             LOG(ERROR) << "Failed to retrieve dmabuf for " << (uintptr_t)addr
-                       << " base=" << (uintptr_t)allocBase
-                       << " size=" << allocSize << " cuda error=" << errStr;
+                       << " base=" << (uintptr_t)exportBase
+                       << " size=" << exportSize << " flags=" << export_flags
+                       << " cuda error=" << errStr;
 #if defined(USE_CUDA) || defined(USE_SUPA)
             cuDevicePrimaryCtxRelease(cuDev);
 #endif
@@ -464,7 +636,7 @@ int RdmaContext::exportDmabuf(void *addr, DmabufExport &out) {
         }
         out.method = DmabufExport::Method::kDmabufReg;
         out.fd = dmabuf_fd;
-        out.offset = (uintptr_t)addr - (uintptr_t)allocBase;
+        out.offset = exportOffset;
 #if defined(USE_CUDA) || defined(USE_SUPA)
         cuDevicePrimaryCtxRelease(cuDev);
 #endif
@@ -589,8 +761,18 @@ int RdmaContext::registerMemoryRegionInternal(void *addr, size_t length,
         // by the caller until every NIC has registered; this MR takes its own
         // reference, so all NICs share one dma_buf object (and one BAR1
         // window).
-        mrMeta.mr = ibv_reg_dmabuf_mr(pd_, exp.offset, length, (uintptr_t)addr,
-                                      exp.fd, access);
+#ifdef USE_CUDA
+        if (Environ::Get().GetRdmaDataDirect()) {
+            auto reg_mr = dataDirectRegMr();
+            if (!reg_mr) return ERR_CONTEXT;
+            mrMeta.mr = reg_mr(pd_, exp.offset, length, (uintptr_t)addr, exp.fd,
+                               access, MLX5DV_REG_DMABUF_ACCESS_DATA_DIRECT);
+        } else
+#endif
+        {
+            mrMeta.mr = ibv_reg_dmabuf_mr(pd_, exp.offset, length,
+                                          (uintptr_t)addr, exp.fd, access);
+        }
     } else {
         mrMeta.mr = ibv_reg_mr(pd_, addr, length, access);
     }
@@ -599,7 +781,10 @@ int RdmaContext::registerMemoryRegionInternal(void *addr, size_t length,
     mrMeta.mr = ibv_reg_mr(pd_, addr, length, access);
 #endif
     if (!mrMeta.mr) {
-        PLOG(ERROR) << "Failed to register memory " << addr;
+        PLOG(ERROR) << "Failed to register memory " << addr << " length "
+                    << length << " dmabuf_offset " << exp.offset << " on "
+                    << device_name_ << " MC_RDMA_DATA_DIRECT="
+                    << Environ::Get().GetRdmaDataDirect();
         return ERR_CONTEXT;
     }
     return 0;
@@ -625,7 +810,7 @@ int RdmaContext::registerMemoryRegion(void *addr, size_t length, int access) {
     // The shared-fd benefit only matters when a buffer is registered against
     // multiple NICs (see RdmaTransport::registerLocalMemoryInternal).
     DmabufExport exp;
-    int ret = exportDmabuf(addr, exp);
+    int ret = exportDmabuf(addr, length, exp);
     if (ret != 0) {
         return ret;
     }
@@ -640,10 +825,21 @@ int RdmaContext::unregisterMemoryRegion(void *addr) {
     if (iter == memory_region_map_.end()) {
         return 0;
     }
+    // Cache addr/length before ibv_dereg_mr: the MR is freed by dereg_mr, so
+    // reading mr->length (or the cached region length) afterwards is a use-
+    // after-free. We restore fork state on the same range to undo the
+    // MADV_DONTFORK applied at register time (see issue #3639).
+    void *region_addr = iter->second.addr;
+    size_t region_length = iter->second.mr->length;
     if (ibv_dereg_mr(iter->second.mr)) {
         LOG(ERROR) << "Failed to unregister memory " << addr;
         return ERR_CONTEXT;
     }
+    if (madvise(region_addr, region_length, MADV_DOFORK) != 0) {
+        PLOG(WARNING) << "Failed to restore fork state for memory region at "
+                      << region_addr << " (" << region_length
+                      << " bytes), deregister already succeeded";
+    }
     memory_region_map_.erase(iter);
     return 0;
 }
@@ -651,7 +847,7 @@ int RdmaContext::unregisterMemoryRegion(void *addr) {
 int RdmaContext::preTouchMemory(void *addr, size_t length) {
     if (!pd_) return 0;  // placeholder context
     DmabufExport exp;
-    int ret = exportDmabuf(addr, exp);
+    int ret = exportDmabuf(addr, length, exp);
     if (ret != 0) {
         return ret;
     }
@@ -712,6 +908,18 @@ RdmaContext::findMemoryRegionContaining(uintptr_t addr) const {
 
 std::shared_ptr<RdmaEndPoint> RdmaContext::endpoint(
     const std::string &peer_nic_path) {
+    int cq_index = cqIndexForPeer(peer_nic_path);
+    if (cq_index < 0) return nullptr;
+    return endpoint(peer_nic_path, cq_index);
+}
+
+std::shared_ptr<RdmaEndPoint> RdmaContext::endpoint(
+    const std::string &peer_nic_path, int cq_index) {
+    if (cq_list_.empty()) {
+        LOG(ERROR) << "No CQ available for endpoint on " << deviceName();
+        return nullptr;
+    }
+
     if (!active_.load(std::memory_order_acquire)) {
         LOG(ERROR) << "Context is not active: " << deviceName();
         return nullptr;
@@ -727,11 +935,18 @@ std::shared_ptr<RdmaEndPoint> RdmaContext::endpoint(
         return endpoint;
     }
 
-    endpoint = endpoint_store_->insertEndpoint(peer_nic_path, this);
+    endpoint =
+        endpoint_store_->insertEndpoint(peer_nic_path, this, cq(cq_index));
     endpoint_store_->reclaimEndpoint();
     return endpoint;
 }
 
+std::shared_ptr<RdmaEndPoint> RdmaContext::findEndpoint(
+    const std::string &peer_nic_path) {
+    if (!endpoint_store_) return nullptr;
+    return endpoint_store_->getEndpoint(peer_nic_path);
+}
+
 std::shared_ptr<RdmaEndPoint> RdmaContext::getEndpointByPtr(
     const RdmaEndPoint *endpoint_ptr) {
     return endpoint_store_->getEndpointByPtr(endpoint_ptr);
@@ -810,9 +1025,53 @@ int RdmaContext::gidIndex() const {
     return gid_index_;
 }
 
-ibv_cq *RdmaContext::cq() {
-    int index = (next_cq_list_index_++) % cq_list_.size();
-    return cq_list_[index].native;
+ibv_cq *RdmaContext::cq(int cq_index) {
+    if (cq_list_.empty()) return nullptr;
+    if (cq_index < 0) return nullptr;
+    return cq_list_[static_cast<size_t>(cq_index) % cq_list_.size()].native;
+}
+
+int RdmaContext::postingThreadForPeer(const std::string &peer_nic_path) const {
+    if (transfer_worker_count_ <= 0) {
+        LOG(ERROR) << "Invalid transfer_worker_count_="
+                   << transfer_worker_count_ << " for endpoint on "
+                   << deviceName();
+        return -1;
+    }
+    return static_cast<int>(std::hash<std::string>{}(peer_nic_path) %
+                            static_cast<size_t>(transfer_worker_count_));
+}
+
+int RdmaContext::cqIndexForPostingThread(int thread_id) const {
+    const int cq_count = cqCount();
+    if (cq_count <= 0 || thread_id < 0) return -1;
+    if (thread_id < cq_count) return thread_id;
+    return thread_id % cq_count;
+}
+
+int RdmaContext::cqIndexForPeer(const std::string &peer_nic_path) const {
+    return cqIndexForPostingThread(postingThreadForPeer(peer_nic_path));
+}
+
+std::unique_lock<std::mutex> RdmaContext::lockEndpointLifecycle(
+    const std::string &peer_nic_path) const {
+    const int owner_thread = postingThreadForPeer(peer_nic_path);
+    if (owner_thread < 0 ||
+        static_cast<size_t>(owner_thread) >= endpoint_lifecycle_locks_.size()) {
+        return std::unique_lock<std::mutex>();
+    }
+    return std::unique_lock<std::mutex>(
+        *endpoint_lifecycle_locks_[owner_thread]);
+}
+
+std::vector<std::unique_lock<std::mutex>>
+RdmaContext::lockAllEndpointLifecycles() const {
+    std::vector<std::unique_lock<std::mutex>> locks;
+    locks.reserve(endpoint_lifecycle_locks_.size());
+    for (auto &lifecycle_lock : endpoint_lifecycle_locks_) {
+        locks.emplace_back(*lifecycle_lock);
+    }
+    return locks;
 }
 
 ibv_comp_channel *RdmaContext::compChannel() {
@@ -955,7 +1214,7 @@ bool RdmaContext::reprobeAutoGid(
     std::string next_gid_string;
     int current_gid_index = -1;
     int next_gid_index = -1;
-    uint16_t current_lid = 0;
+    uint32_t current_lid = 0;
     ibv_context *current_context = nullptr;
     uint8_t current_port = 0;
     AutoGidCandidateClass next_candidate_class =
@@ -1075,7 +1334,7 @@ GidRefreshResult RdmaContext::refreshCurrentGid(std::string *previous_gid,
     std::string current_gid_string;
     int current_gid_index = -1;
     int next_gid_index = -1;
-    uint16_t current_lid = 0;
+    uint32_t current_lid = 0;
     ibv_context *current_context = nullptr;
     uint8_t current_port = 0;
     bool auto_gid_selection_enabled = false;
@@ -1213,8 +1472,8 @@ int RdmaContext::openRdmaDevice(const std::string &device_name, uint8_t port,
         ibv_port_attr attr;
         int ret = ibv_query_port(context, port, &attr);
         if (ret) {
-            LOG(ERROR) << "Failed to query port " << port << " on "
-                       << device_name << ": " << strerror(ret);
+            LOG(ERROR) << "Failed to query port " << static_cast<int>(port)
+                       << " on " << device_name << ": " << strerror(ret);
             int close_ret = ibv_close_device(context);
             if (close_ret) {
                 LOG(ERROR) << "ibv_close_device(" << device_name
@@ -1341,7 +1600,8 @@ int RdmaContext::openRdmaDevice(const std::string &device_name, uint8_t port,
         ret = ibv_query_port(context, port, &port_attr);
         if (ret) {
             LOG(WARNING) << "Failed to query port attributes on " << device_name
-                         << "/" << port << ": " << strerror(ret);
+                         << "/" << static_cast<int>(port) << ": "
+                         << strerror(ret);
             int close_ret = ibv_close_device(context);
             if (close_ret) {
                 LOG(ERROR) << "ibv_close_device(" << device_name
@@ -1360,34 +1620,37 @@ int RdmaContext::openRdmaDevice(const std::string &device_name, uint8_t port,
                                          found_gid_index);
             if (gid_state != GidNetworkState::GID_NOT_FOUND) {
                 LOG(INFO) << "Find best gid index: " << found_gid_index
-                          << " on " << device_name << "/" << port
-                          << " (network state: "
+                          << " on " << device_name << "/"
+                          << static_cast<int>(port) << " (network state: "
                           << GidNetworkStateToString(gid_state) << ")";
                 gid_index = found_gid_index;
             } else {
                 LOG(WARNING) << "No suitable GID found on " << device_name
-                             << "/" << port;
+                             << "/" << static_cast<int>(port);
                 goto cleanup_context_and_devices;
             }
         } else {
             // Also check network state for user-specified GID
             bool has_ndev = !readGidNdev(device_name, port, gid_index).empty();
             if (!has_ndev) {
-                LOG(WARNING) << "User-specified GID index " << gid_index
-                             << " on " << device_name << "/" << port
-                             << " has no associated network device, "
-                             << "may not be optimal for RDMA operations";
+                LOG(WARNING)
+                    << "User-specified GID index " << gid_index << " on "
+                    << device_name << "/" << static_cast<int>(port)
+                    << " has no associated network device, "
+                    << "may not be optimal for RDMA operations";
             }
             LOG(INFO) << "Using user-specified GID index: " << gid_index
-                      << " on " << device_name << "/" << port << " ("
-                      << (has_ndev ? "with" : "without") << " network device)";
+                      << " on " << device_name << "/" << static_cast<int>(port)
+                      << " (" << (has_ndev ? "with" : "without")
+                      << " network device)";
         }
 
         // Continue with GID validation
         ret = ibv_query_gid(context, port, gid_index, &gid_);
         if (ret) {
             LOG(ERROR) << "Failed to query GID " << gid_index << " on "
-                       << device_name << "/" << port << ": " << strerror(ret);
+                       << device_name << "/" << static_cast<int>(port) << ": "
+                       << strerror(ret);
             goto cleanup_context_and_devices;
         }
 
@@ -1402,9 +1665,19 @@ int RdmaContext::openRdmaDevice(const std::string &device_name, uint8_t port,
         // All checks passed, assign member variables
         context_ = context;
         port_ = port;
+#ifdef USE_SHCA
+        lid_ = u17_to_32(attr.lid);
+#else
         lid_ = attr.lid;
+#endif
         active_mtu_ = attr.active_mtu;
         active_speed_ = attr.active_speed;
+#ifdef HAVE_IBV_ACTIVE_SPEED_EX
+        // XDR (encoding 256) overflows the uint8_t field above, which then
+        // reads 0; the extended field carries it on rdma-core builds that
+        // have one.
+        if (attr.active_speed_ex) active_speed_ = attr.active_speed_ex;
+#endif
         active_width_ = attr.active_width;
         {
             std::lock_guard<std::mutex> guard(gid_lock_);
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_endpoint.cpp b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_endpoint.cpp
index 04baa0be2a..38e660937b 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_endpoint.cpp
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_endpoint.cpp
@@ -16,7 +16,9 @@
 
 #include <glog/logging.h>
 
+#include <algorithm>
 #include <cassert>
+#include <cstring>
 #include <cerrno>
 #include <cstddef>
 #include <chrono>
@@ -26,6 +28,9 @@
 #ifdef USE_MLX5DV
 #include <infiniband/mlx5dv.h>
 #endif
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
 
 #include "common.h"
 #include "config.h"
@@ -92,19 +97,30 @@ static std::string gidToString(const ibv_gid &gid) {
 RdmaEndPoint::RdmaEndPoint(RdmaContext &context)
     : context_(context),
       status_(INITIALIZING),
+      qp_generation_(0),
       has_connected_(false),
       ready_wait_start_ts_(0),
       wr_depth_list_(nullptr),
       active_(true),
+      cq_(nullptr),
       cq_outstanding_(nullptr) {}
 
 RdmaEndPoint::~RdmaEndPoint() {
-    if (!qp_list_.empty()) {
-        // In normal flow, beginDestroy()+finishDestroy() should have been
-        // called already via endpoint_store. This is a fallback for abnormal
-        // shutdown (e.g., process exit).
+    // In normal flow, beginDestroy()+finishDestroy() should have been
+    // called already via endpoint_store. This is a fallback for abnormal
+    // shutdown (e.g., process exit). Keyed on wr_depth_list_ as well:
+    // construct() allocates it even for a zero-QP endpoint, whose qp_list_
+    // is empty, and skipping deconstructLocked() would leak it.
+    if (!qp_list_.empty() || wr_depth_list_ || notify_.enabled) {
         RWSpinlock::WriteGuard guard(lock_);
-        deconstructLocked();
+        if (deconstructLocked()) {
+            // Preserve DMA buffers if QP destruction or MR deregistration
+            // fails.
+            LOG(ERROR)
+                << "Retaining notification buffers after teardown failure";
+            (void)notify_.send_buffer.release();
+            (void)notify_.recv_buffer.release();
+        }
     }
 }
 
@@ -117,6 +133,7 @@ int RdmaEndPoint::construct(ibv_cq *cq, size_t num_qp_list,
     }
 
     qp_list_.resize(num_qp_list);
+    cq_ = cq;
     cq_outstanding_ = static_cast<std::atomic<int> *>(cq->cq_context);
 
     max_wr_depth_ = (int)max_wr_depth;
@@ -147,12 +164,22 @@ int RdmaEndPoint::construct(ibv_cq *cq, size_t num_qp_list,
         }
     }
 
+    if (context_.nativeNotifyEnabled()) {
+        int ret = constructNotification();
+        if (ret) {
+            LOG(ERROR) << "Notification QP initialization failed: " << ret;
+        }
+    }
     ready_wait_start_ts_.store(0, std::memory_order_relaxed);
     status_.store(UNCONNECTED, std::memory_order_relaxed);
     return 0;
 }
 
 int RdmaEndPoint::reconstruct() {
+    // Invalidate any handshake that captured the previous QP set, even when
+    // reconstruction fails before fresh QPs can be created.
+    ++qp_generation_;
+
     // Save original construction parameters
     size_t num_qp = qp_list_.size();
     auto max_wr_depth = max_wr_depth_;
@@ -167,9 +194,7 @@ int RdmaEndPoint::reconstruct() {
         return ret;
     }
 
-    // Get CQ from context for reconstruction
-    ibv_cq *cq = context_.cq();
-    if (!cq) {
+    if (!cq_) {
         LOG(ERROR) << "No CQ available for endpoint reconstruction";
         return ERR_ENDPOINT;
     }
@@ -179,7 +204,7 @@ int RdmaEndPoint::reconstruct() {
     ready_wait_start_ts_.store(0, std::memory_order_relaxed);
     active_.store(true, std::memory_order_release);
 
-    return construct(cq, num_qp, max_sge_per_wr, max_wr_depth,
+    return construct(cq_, num_qp, max_sge_per_wr, max_wr_depth,
                      max_inline_bytes);
 }
 
@@ -189,6 +214,11 @@ int RdmaEndPoint::deconstruct() {
 }
 
 int RdmaEndPoint::deconstructLocked() {
+    if (notify_.enabled) {
+        int ret = closeNotification();
+        if (ret) return ret;
+    }
+    peer_notify_qp_num_ = 0;
     // Adjust cq_outstanding_ before destroying QPs, so the counter is
     // always corrected even if ibv_destroy_qp fails and we return early.
     bool displayed = false;
@@ -213,7 +243,8 @@ int RdmaEndPoint::deconstructLocked() {
         if (!qp_list_[i]) continue;  // already destroyed in a previous call
         int ret = ibv_destroy_qp(qp_list_[i]);
         if (ret) {
-            LOG(ERROR) << "Failed to destroy QP[" << i << "]: " << strerror(ret);
+            LOG(ERROR) << "Failed to destroy QP[" << i
+                       << "]: " << strerror(ret);
             result = ERR_ENDPOINT;
         } else {
             qp_list_[i] = nullptr;
@@ -243,6 +274,7 @@ void RdmaEndPoint::beginDestroyLocked() {
     inactive_time_.store(getCurrentTimeInNano(), std::memory_order_relaxed);
     active_.store(false, std::memory_order_release);
     status_.store(DESTROYING, std::memory_order_release);
+    if (notify_.enabled) stopNotification();
     ready_wait_start_ts_.store(0, std::memory_order_relaxed);
 
     // Only endpoints that reached CONNECTED can have user WRs to flush. For
@@ -294,8 +326,9 @@ bool RdmaEndPoint::finishDestroy() {
         // Fall through to the unified destroy path.
     } else {
         // Gate 3: two-phase path. Wait for inflight WRs to drain via CQ
-        // polling. If ibv_modify_qp-to-ERR failed in beginDestroy, WRs may
-        // never be flushed; enforce a timeout to avoid leaking forever.
+        // polling. If they never drain, keep the retired endpoint alive in
+        // the waiting list. Leaking this object is safer than forcing QP
+        // destruction while stale slice references may still exist.
         bool has_outstanding = false;
         for (size_t i = 0; i < qp_list_.size(); ++i) {
             if (wr_depth_list_[i].load(std::memory_order_relaxed) != 0) {
@@ -308,8 +341,13 @@ bool RdmaEndPoint::finishDestroy() {
                               inactive_time_.load(std::memory_order_relaxed)) /
                              1e9;
             if (elapsed < kFinishDestroyTimeoutSec) return false;
-            LOG(WARNING) << "finishDestroy timed out after " << elapsed
-                         << "s with outstanding WRs, forcing destruction";
+            if (!finish_destroy_timeout_logged_) {
+                LOG(ERROR) << "finishDestroy timed out after " << elapsed
+                           << "s with outstanding WRs; keeping retired "
+                              "endpoint alive to avoid UAF";
+                finish_destroy_timeout_logged_ = true;
+            }
+            return false;
         }
     }
 
@@ -342,9 +380,272 @@ void RdmaEndPoint::setPeerNicPath(const std::string &peer_nic_path) {
     peer_nic_path_ = peer_nic_path;
 }
 
+std::string RdmaEndPoint::peerNicPath() const {
+    RWSpinlock::ReadGuard guard(lock_);
+    return peer_nic_path_;
+}
+
+namespace {
+bool isLocalNotificationFault(ibv_wc_status status) {
+    return status == IBV_WC_LOC_LEN_ERR || status == IBV_WC_LOC_QP_OP_ERR ||
+           status == IBV_WC_LOC_PROT_ERR || status == IBV_WC_LOC_ACCESS_ERR ||
+           status == IBV_WC_MW_BIND_ERR;
+}
+}  // namespace
+
+bool RdmaEndPoint::notificationFits(const TransferMetadata::NotifyDesc &msg) {
+    return msg.name.size() <= kNotifySlotBytes - kNotifyHeaderBytes &&
+           msg.notify_msg.size() <=
+               kNotifySlotBytes - kNotifyHeaderBytes - msg.name.size();
+}
+size_t RdmaEndPoint::encodeNotification(
+    char *slot, const TransferMetadata::NotifyDesc &msg) {
+    if (!notificationFits(msg)) return 0;
+    uint32_t name_size = msg.name.size(), msg_size = msg.notify_msg.size();
+    std::memcpy(slot, &name_size, 4);
+    std::memcpy(slot + 4, msg.name.data(), name_size);
+    std::memcpy(slot + 4 + name_size, &msg_size, 4);
+    std::memcpy(slot + kNotifyHeaderBytes + name_size, msg.notify_msg.data(),
+                msg_size);
+    return kNotifyHeaderBytes + name_size + msg_size;
+}
+bool RdmaEndPoint::decodeNotification(const char *slot, size_t bytes,
+                                      TransferMetadata::NotifyDesc &msg) {
+    if (bytes < kNotifyHeaderBytes || bytes > kNotifySlotBytes) return false;
+    uint32_t name_size = 0, msg_size = 0;
+    std::memcpy(&name_size, slot, 4);
+    if (name_size > bytes - kNotifyHeaderBytes) return false;
+    std::memcpy(&msg_size, slot + 4 + name_size, 4);
+    if (msg_size != bytes - kNotifyHeaderBytes - name_size) return false;
+    msg.name.assign(slot + 4, name_size);
+    msg.notify_msg.assign(slot + kNotifyHeaderBytes + name_size, msg_size);
+    return true;
+}
+
+int RdmaEndPoint::postNotificationReceive(size_t slot) {
+    auto &s = notify_;
+    ibv_sge sge{};
+    sge.addr = reinterpret_cast<uint64_t>(s.recv_buffer.get() +
+                                          slot * kNotifySlotBytes);
+    sge.length = kNotifySlotBytes;
+    sge.lkey = s.recv_mr->lkey;
+    ibv_recv_wr wr{}, *bad = nullptr;
+    wr.wr_id = slot;
+    wr.sg_list = &sge;
+    wr.num_sge = 1;
+    return ibv_post_recv(s.qp, &wr, &bad) ? ERR_ENDPOINT : 0;
+}
+int RdmaEndPoint::constructNotification() {
+    auto &s = notify_;
+    std::lock_guard<std::mutex> guard(s.mutex);
+    s.enabled = true;
+    s.error = 0;
+    s.connected = s.reconnect_needed = false;
+    s.pending = s.next_send = s.peer_qp = 0;
+    if (!context_.notify_cq_) return s.fail(ERR_CONTEXT);
+    ibv_qp_init_attr init{};
+    init.send_cq = init.recv_cq = context_.notify_cq_;
+    init.qp_type = IBV_QPT_RC;
+    init.cap.max_send_wr = init.cap.max_recv_wr = kNotifySlots;
+    init.cap.max_send_sge = init.cap.max_recv_sge = 1;
+    init.cap.max_inline_data = globalConfig().max_inline;
+    s.qp = ibv_create_qp(context_.pd(), &init);
+    if (!s.qp) return s.fail(ERR_ENDPOINT);
+    s.inline_bytes = init.cap.max_inline_data;
+    ibv_qp_attr attr{};
+    attr.qp_state = IBV_QPS_INIT;
+    attr.port_num = context_.portNum();
+    attr.pkey_index = globalConfig().pkey_index;
+    attr.qp_access_flags = IBV_ACCESS_LOCAL_WRITE;
+    if (ibv_modify_qp(s.qp, &attr,
+                      IBV_QP_STATE | IBV_QP_PORT | IBV_QP_PKEY_INDEX |
+                          IBV_QP_ACCESS_FLAGS))
+        return s.fail(ERR_ENDPOINT);
+    s.send_buffer = std::make_unique<char[]>(kNotifySlots * kNotifySlotBytes);
+    s.recv_buffer = std::make_unique<char[]>(kNotifySlots * kNotifySlotBytes);
+    s.send_mr =
+        ibv_reg_mr(context_.pd(), s.send_buffer.get(),
+                   kNotifySlots * kNotifySlotBytes, IBV_ACCESS_LOCAL_WRITE);
+    s.recv_mr =
+        ibv_reg_mr(context_.pd(), s.recv_buffer.get(),
+                   kNotifySlots * kNotifySlotBytes, IBV_ACCESS_LOCAL_WRITE);
+    if (!s.send_mr || !s.recv_mr) return s.fail(ERR_MEMORY);
+    for (size_t slot = 0; slot < kNotifySlots; ++slot)
+        if (postNotificationReceive(slot)) return s.fail(ERR_ENDPOINT);
+    context_.registerNotifyQp(s.qp->qp_num, weak_from_this());
+    return 0;
+}
+uint32_t RdmaEndPoint::notificationQpNum() const {
+    std::lock_guard<std::mutex> guard(notify_.mutex);
+    return notify_.qp && !notify_.error ? notify_.qp->qp_num : 0;
+}
+int RdmaEndPoint::connectNotification(const ibv_gid &gid, uint32_t lid,
+                                      uint32_t peer_qp, int local_gid_index) {
+    auto &s = notify_;
+    std::lock_guard<std::mutex> guard(s.mutex);
+    if (s.error) return s.error;
+    if (s.connected)
+        return s.peer_qp == peer_qp ? 0 : s.fail(ERR_ENDPOINT, true);
+    if (!peer_qp) return s.fail(ERR_NOT_IMPLEMENTED);
+    auto &cfg = globalConfig();
+    ibv_qp_attr attr{};
+    attr.qp_state = IBV_QPS_RTR;
+    attr.path_mtu = std::min(context_.activeMTU(), cfg.mtu_length);
+    attr.dest_qp_num = peer_qp;
+    attr.rq_psn = 0;
+    attr.max_dest_rd_atomic = 1;
+    attr.min_rnr_timer = 12;
+    attr.ah_attr.is_global = 1;
+    attr.ah_attr.grh.dgid = gid;
+    attr.ah_attr.grh.sgid_index = local_gid_index;
+    attr.ah_attr.grh.hop_limit = 255;
+    attr.ah_attr.grh.traffic_class =
+        cfg.ib_traffic_class >= 0 ? cfg.ib_traffic_class : 0;
+#ifdef USE_SHCA
+    attr.ah_attr.dlid = u32_to_17(lid);
+#else
+    attr.ah_attr.dlid = static_cast<uint16_t>(lid);
+#endif
+    attr.ah_attr.sl = cfg.ib_service_level >= 0 ? cfg.ib_service_level : 0;
+    attr.ah_attr.port_num = context_.portNum();
+    if (ibv_modify_qp(s.qp, &attr,
+                      IBV_QP_STATE | IBV_QP_PATH_MTU | IBV_QP_DEST_QPN |
+                          IBV_QP_RQ_PSN | IBV_QP_MAX_DEST_RD_ATOMIC |
+                          IBV_QP_MIN_RNR_TIMER | IBV_QP_AV))
+        return s.fail(ERR_ENDPOINT);
+    attr = {};
+    attr.qp_state = IBV_QPS_RTS;
+    attr.sq_psn = 0;
+    attr.timeout = 14;
+    attr.retry_cnt = 3;
+    attr.rnr_retry =
+        7;  // Like TENT, receiver backpressure is not a link fault.
+    attr.max_rd_atomic = 1;
+    if (ibv_modify_qp(s.qp, &attr,
+                      IBV_QP_STATE | IBV_QP_SQ_PSN | IBV_QP_TIMEOUT |
+                          IBV_QP_RETRY_CNT | IBV_QP_RNR_RETRY |
+                          IBV_QP_MAX_QP_RD_ATOMIC))
+        return s.fail(ERR_ENDPOINT);
+    s.peer_qp = peer_qp;
+    s.connected = true;
+    return 0;
+}
+int RdmaEndPoint::sendNotification(
+    const TransferMetadata::NotifyDesc &message) {
+    if (!notificationFits(message)) return ERR_NOT_IMPLEMENTED;
+    auto started = getCurrentTimeInNano();
+    while (connected() && !readyToSend()) {
+        if (static_cast<uint64_t>(getCurrentTimeInNano() - started) >
+            kWaitExistingHandshakeTimeoutNano)
+            return ERR_ENDPOINT;
+        std::this_thread::sleep_for(std::chrono::microseconds(50));
+    }
+    auto &s = notify_;
+    std::unique_lock<std::mutex> lock(s.mutex, std::defer_lock);
+    {
+        RWSpinlock::ReadGuard guard(lock_);
+        if (!readyToSend()) return ERR_ENDPOINT;
+        lock.lock();
+    }
+    if (!s.enabled) return ERR_NOT_IMPLEMENTED;
+    // Retirement needs the endpoint write lock; do not hold it while waiting.
+    s.cv.wait(lock, [&s] {
+        return s.error || !s.connected || s.pending < kNotifySlots;
+    });
+    if (s.error) return s.error;
+    if (!s.connected) return ERR_NOT_IMPLEMENTED;
+    char *data =
+        s.send_buffer.get() + (s.next_send % kNotifySlots) * kNotifySlotBytes;
+    size_t bytes = encodeNotification(data, message);
+    ibv_sge sge{};
+    sge.addr = reinterpret_cast<uint64_t>(data);
+    sge.length = bytes;
+    sge.lkey = s.send_mr->lkey;
+    ibv_send_wr wr{}, *bad = nullptr;
+    wr.wr_id = s.next_send % kNotifySlots;
+    wr.sg_list = &sge;
+    wr.num_sge = 1;
+    wr.opcode = IBV_WR_SEND;
+    wr.send_flags = IBV_SEND_SIGNALED;
+    if (bytes <= s.inline_bytes) wr.send_flags |= IBV_SEND_INLINE;
+    if (ibv_post_send(s.qp, &wr, &bad)) return s.fail(ERR_ENDPOINT);
+    ++s.next_send;
+    ++s.pending;
+    return 0;
+}
+void RdmaEndPoint::handleNotificationCompletion(
+    const ibv_wc &wc, std::vector<TransferMetadata::NotifyDesc> &received) {
+    auto &s = notify_;
+    std::lock_guard<std::mutex> guard(s.mutex);
+    if (!s.qp || wc.qp_num != s.qp->qp_num || s.error) return;
+    if (wc.status != IBV_WC_SUCCESS) {
+        LOG(ERROR) << "Native RDMA notify completion: "
+                   << ibv_wc_status_str(wc.status);
+        s.fail(ERR_ENDPOINT, !isLocalNotificationFault(wc.status));
+        return;
+    }
+    const size_t slot = wc.wr_id % kNotifySlots;
+    if (wc.opcode == IBV_WC_SEND && s.pending) {
+        --s.pending;
+        s.cv.notify_all();
+    } else if (wc.opcode == IBV_WC_RECV) {
+        TransferMetadata::NotifyDesc message;
+        if (!decodeNotification(s.recv_buffer.get() + slot * kNotifySlotBytes,
+                                wc.byte_len, message)) {
+            s.fail(ERR_ENDPOINT);
+            return;
+        }
+        received.push_back(std::move(message));
+        if (postNotificationReceive(slot)) s.fail(ERR_ENDPOINT);
+    } else {
+        s.fail(ERR_ENDPOINT);
+    }
+}
+void RdmaEndPoint::stopNotification() {
+    std::lock_guard<std::mutex> guard(notify_.mutex);
+    notify_.fail(ERR_ENDPOINT);
+    if (notify_.qp) {
+        ibv_qp_attr attr{};
+        attr.qp_state = IBV_QPS_ERR;
+        ibv_modify_qp(notify_.qp, &attr, IBV_QP_STATE);
+    }
+}
+int RdmaEndPoint::closeNotification() {
+    auto &s = notify_;
+    std::lock_guard<std::mutex> guard(s.mutex);
+    s.fail(ERR_ENDPOINT);
+    if (s.qp) {
+        context_.unregisterNotifyQp(s.qp->qp_num);
+        if (ibv_destroy_qp(s.qp)) return ERR_ENDPOINT;
+        s.qp = nullptr;
+    }
+    if (s.send_mr) {
+        if (ibv_dereg_mr(s.send_mr)) return ERR_MEMORY;
+        s.send_mr = nullptr;
+    }
+    if (s.recv_mr) {
+        if (ibv_dereg_mr(s.recv_mr)) return ERR_MEMORY;
+        s.recv_mr = nullptr;
+    }
+    s.send_buffer.reset();
+    s.recv_buffer.reset();
+    s.enabled = false;
+    return 0;
+}
+bool RdmaEndPoint::notificationNeedsReconnect() const {
+    std::lock_guard<std::mutex> guard(notify_.mutex);
+    return notify_.reconnect_needed;
+}
+
+void RdmaEndPoint::describeNotification(HandShakeDesc &desc) const {
+    desc.notify_qp_num = notificationQpNum();
+    desc.ctrl_channel = false;
+}
+
 int RdmaEndPoint::setupConnectionsByActive() {
     HandShakeDesc local_desc, peer_desc;
     std::string peer_server_name, peer_nic_name;
+    uint64_t qp_generation = 0;
     bool do_rpc = false;
     int auto_gid_retry_count = 0;
     std::vector<AutoGidSelectionIdentity> attempted_auto_gid_selections;
@@ -356,10 +657,13 @@ int RdmaEndPoint::setupConnectionsByActive() {
             return 0;
         }
 
+        qp_generation = qp_generation_;
+
         // loopback mode
         if (context_.nicPath() == peer_nic_path_) {
-            int ret =
-                doSetupConnection(context_.gid(), context_.lid(), qpNum());
+            int ret = doSetupConnection(context_.gid(), context_.lid(), qpNum(),
+                                        CONNECTED, nullptr, nullptr,
+                                        notificationQpNum());
             if (ret == 0) {
                 ready_wait_start_ts_.store(0, std::memory_order_relaxed);
             }
@@ -407,6 +711,12 @@ int RdmaEndPoint::setupConnectionsByActive() {
                 // The QP state on this endpoint may have changed; therefore,
                 // reset the connection so that subsequent callers can retry.
                 RWSpinlock::WriteGuard write_guard(lock_);
+                if (qp_generation != qp_generation_) {
+                    return connected() ? 0 : ERR_ENDPOINT;
+                }
+                auto current_status = status_.load(std::memory_order_relaxed);
+                if (isConnectedStatus(current_status)) return 0;
+                if (current_status != CONNECTING) return ERR_ENDPOINT;
                 resetConnection("wait existing handshake timeout");
                 return ERR_ENDPOINT;
             }
@@ -418,12 +728,22 @@ int RdmaEndPoint::setupConnectionsByActive() {
 
     for (;;) {
         std::vector<uint32_t> local_qp_num;
+        GidSelectionSnapshot local_gid_selection;
         {
             RWSpinlock::ReadGuard guard(lock_);
+            if (qp_generation != qp_generation_) {
+                return connected() ? 0 : ERR_ENDPOINT;
+            }
+            auto current_status = status_.load(std::memory_order_relaxed);
+            if (current_status != CONNECTING &&
+                !isConnectedStatus(current_status)) {
+                return ERR_ENDPOINT;
+            }
             local_qp_num = qpNum();
+            local_gid_selection = fillLocalHandshakeDesc(
+                context_, peer_nic_path_, local_qp_num, local_desc);
+            describeNotification(local_desc);
         }
-        auto local_gid_selection = fillLocalHandshakeDesc(
-            context_, peer_nic_path_, local_qp_num, local_desc);
         rememberAutoGidSelection(attempted_auto_gid_selections,
                                  local_gid_selection);
         peer_desc = HandShakeDesc();
@@ -433,53 +753,83 @@ int RdmaEndPoint::setupConnectionsByActive() {
         int rc = context_.engine().sendHandshake(peer_server_name, local_desc,
                                                  peer_desc);
 
-        // We should check the RPC return code before comparing
-        // `peer_qp_num_list_` with `peer_desc.qp_num`, since a failed RPC may
-        // result in an invalid `peer_desc.qp_num`.
-        //
-        // If the RPC failed but simultaneous-open passive setup has already
-        // made this endpoint CONNECTED with the same local QPs used by this
-        // RPC, reuse that connection. Otherwise reset because
-        // `peer_desc.qp_num` is invalid and we cannot safely infer the peer
-        // state.
-        if (rc) {
-            RWSpinlock::WriteGuard write_guard(lock_);
-            if (connected()) {
-                auto current_qp_num = qpNum();
-                if (current_qp_num == local_desc.qp_num) {
-                    LOG(WARNING)
-                        << "Active handshake RPC failed, but simultaneous-open "
-                           "passive setup already connected this endpoint. "
-                           "Reusing existing connection. rc="
-                        << rc << ", local_desc.qp_num="
-                        << qpListToString(local_desc.qp_num)
-                        << ", current_qp_num=" << qpListToString(current_qp_num)
-                        << ", endpoint=" << toString();
-                    return 0;
-                }
-            }
-
-            LOG(ERROR) << "Active handshake RPC failed; resetting endpoint. rc="
-                       << rc << ", local_desc.qp_num="
-                       << qpListToString(local_desc.qp_num)
-                       << ", endpoint=" << toString();
-            resetConnection("handshake RPC failure");
-            return rc;
-        }
-
         bool retry_with_new_gid = false;
         bool should_send_ready_ack = false;
         HandShakeDesc ready_ack_desc;
         {
-            // Re-acquire lock after RPC to finalize state transition
+            // Re-acquire lock before inspecting either the RPC result or
+            // endpoint state. A waiter may have reconstructed this endpoint
+            // with fresh QPs while the RPC was in flight.
             RWSpinlock::WriteGuard guard(lock_);
+            if (qp_generation != qp_generation_) {
+                if (connected()) {
+                    LOG(INFO) << "Discarding stale active handshake reply and "
+                                 "reusing "
+                                 "the newer passive connection: "
+                              << toString();
+                    return 0;
+                }
+                LOG(WARNING)
+                    << "Discarding stale active handshake reply after local "
+                       "QP reconstruction: "
+                    << toString();
+                return ERR_ENDPOINT;
+            }
+
+            auto current_status = status_.load(std::memory_order_relaxed);
+            if (current_status != CONNECTING &&
+                !isConnectedStatus(current_status)) {
+                LOG(WARNING)
+                    << "Discarding active handshake reply for endpoint "
+                       "in state "
+                    << current_status << ": " << toString();
+                return ERR_ENDPOINT;
+            }
+
+            // We should check the RPC return code before comparing
+            // `peer_qp_num_list_` with `peer_desc.qp_num`, since a failed RPC
+            // may result in an invalid `peer_desc.qp_num`.
+            //
+            // If the RPC failed but simultaneous-open passive setup has
+            // already connected this endpoint with the same local QPs used by
+            // this RPC, reuse that connection. Otherwise reset because
+            // `peer_desc.qp_num` is invalid and we cannot safely infer the peer
+            // state.
+            if (rc) {
+                if (connected()) {
+                    auto current_qp_num = qpNum();
+                    if (current_qp_num == local_desc.qp_num) {
+                        LOG(WARNING)
+                            << "Active handshake RPC failed, but "
+                               "simultaneous-open passive setup already "
+                               "connected this endpoint. Reusing existing "
+                               "connection. rc="
+                            << rc << ", local_desc.qp_num="
+                            << qpListToString(local_desc.qp_num)
+                            << ", current_qp_num="
+                            << qpListToString(current_qp_num)
+                            << ", endpoint=" << toString();
+                        return 0;
+                    }
+                }
+
+                LOG(ERROR)
+                    << "Active handshake RPC failed; resetting endpoint. rc="
+                    << rc << ", local_desc.qp_num="
+                    << qpListToString(local_desc.qp_num)
+                    << ", endpoint=" << toString();
+                resetConnection("handshake RPC failure");
+                return rc;
+            }
 
             // Handle simultaneous open: if the peer initiates a connection
             // during our RPC and it is passively established in
             // setupConnectionsByPassive, send an explicit ready ACK after this
             // active RPC confirms that the peer's passive QPs are ready.
             if (connected()) {
-                if (peer_qp_num_list_ == peer_desc.qp_num) {
+                if ((peer_qp_num_list_ == peer_desc.qp_num &&
+                     (!notify_.enabled ||
+                      peer_notify_qp_num_ == peer_desc.notify_qp_num))) {
                     if (peer_desc.ready_ack_supported) {
                         should_send_ready_ack = true;
                         ready_ack_desc = local_desc;
@@ -537,10 +887,10 @@ int RdmaEndPoint::setupConnectionsByActive() {
                                             ? CONNECTED_WAIT_READY_ACK
                                             : CONNECTED;
                 if (!peer_desc.local_gid.empty()) {
-                    ret = doSetupConnection(peer_desc.local_gid,
-                                            peer_desc.local_lid,
-                                            peer_desc.qp_num, connected_status,
-                                            &failure_message, &failure_info);
+                    ret = doSetupConnection(
+                        peer_desc.local_gid, peer_desc.local_lid,
+                        peer_desc.qp_num, connected_status, &failure_message,
+                        &failure_info, peer_desc.notify_qp_num);
                 } else {
                     auto segment_desc =
                         context_.engine().meta()->getSegmentDescByName(
@@ -551,7 +901,7 @@ int RdmaEndPoint::setupConnectionsByActive() {
                                 ret = doSetupConnection(
                                     nic.gid, nic.lid, peer_desc.qp_num,
                                     connected_status, &failure_message,
-                                    &failure_info);
+                                    &failure_info, peer_desc.notify_qp_num);
                                 break;
                             }
                         }
@@ -595,6 +945,7 @@ int RdmaEndPoint::setupConnectionsByActive() {
                                     : "retry with externally reprobed GID "
                                       "(active)");
                             if (reset_ret) return reset_ret;
+                            qp_generation = qp_generation_;
                             status_.store(CONNECTING,
                                           std::memory_order_relaxed);
                             ++auto_gid_retry_count;
@@ -655,7 +1006,9 @@ int RdmaEndPoint::setupConnectionsByPassive(const HandShakeDesc &peer_desc,
             return ERR_REJECT_HANDSHAKE;
         }
 
-        if (peer_qp_num_list_ != peer_desc.qp_num) {
+        if (peer_qp_num_list_ != peer_desc.qp_num ||
+            (notify_.enabled &&
+             peer_notify_qp_num_ != peer_desc.notify_qp_num)) {
             local_desc.reply_msg =
                 "Received stale RDMA ready ACK with mismatched peer QP numbers";
             LOG(WARNING) << local_desc.reply_msg << ", ack_peer_qp_num="
@@ -674,9 +1027,12 @@ int RdmaEndPoint::setupConnectionsByPassive(const HandShakeDesc &peer_desc,
 
     if (connected()) {
         // If already connected with the same peer QP info, return success
-        if (peer_qp_num_list_ == peer_desc.qp_num) {
+        if ((peer_qp_num_list_ == peer_desc.qp_num &&
+             (!notify_.enabled ||
+              peer_notify_qp_num_ == peer_desc.notify_qp_num))) {
             fillLocalHandshakeDesc(context_, peer_nic_path_, qpNum(),
                                    local_desc);
+            describeNotification(local_desc);
             if (!peer_desc.ready_ack_supported) {
                 ready_wait_start_ts_.store(0, std::memory_order_relaxed);
                 status_.store(CONNECTED, std::memory_order_relaxed);
@@ -725,12 +1081,13 @@ int RdmaEndPoint::setupConnectionsByPassive(const HandShakeDesc &peer_desc,
     status_.store(CONNECTING, std::memory_order_relaxed);
 
     auto attempt_setup_with_peer = [&](const std::string &peer_gid,
-                                       uint16_t peer_lid) -> int {
+                                       uint32_t peer_lid) -> int {
         int auto_gid_retry_count = 0;
         std::vector<AutoGidSelectionIdentity> attempted_auto_gid_selections;
         for (;;) {
             auto local_gid_selection = fillLocalHandshakeDesc(
                 context_, peer_nic_path_, qpNum(), local_desc);
+            describeNotification(local_desc);
             rememberAutoGidSelection(attempted_auto_gid_selections,
                                      local_gid_selection);
 
@@ -740,8 +1097,9 @@ int RdmaEndPoint::setupConnectionsByPassive(const HandShakeDesc &peer_desc,
                                         : CONNECTED;
             int ret = doSetupConnection(peer_gid, peer_lid, peer_desc.qp_num,
                                         connected_status, &local_desc.reply_msg,
-                                        &failure_info);
+                                        &failure_info, peer_desc.notify_qp_num);
             if (ret == 0) {
+                describeNotification(local_desc);
                 if (peer_desc.ready_ack_supported) {
                     ready_wait_start_ts_.store(getCurrentTimeInNano(),
                                                std::memory_order_relaxed);
@@ -1063,11 +1421,12 @@ static int parseGidString(const std::string &gid_str, ibv_gid &gid_out) {
 }
 
 int RdmaEndPoint::doSetupConnection(const std::string &peer_gid,
-                                    uint16_t peer_lid,
+                                    uint32_t peer_lid,
                                     std::vector<uint32_t> peer_qp_num_list,
                                     Status connected_status,
                                     std::string *reply_msg,
-                                    SetupConnectionFailureInfo *failure_info) {
+                                    SetupConnectionFailureInfo *failure_info,
+                                    uint32_t notify_qp_num) {
     if (qp_list_.size() != peer_qp_num_list.size()) {
         std::string message =
             "QP count mismatch in peer and local endpoints, check "
@@ -1103,6 +1462,14 @@ int RdmaEndPoint::doSetupConnection(const std::string &peer_gid,
         if (ret) return ret;
     }
 
+    if (notify_.enabled) {
+        int notify_ret = connectNotification(peer_gid_raw, peer_lid,
+                                             notify_qp_num, local_gid_index);
+        if (notify_ret && notify_ret != ERR_NOT_IMPLEMENTED)
+            LOG(ERROR) << "Notification connection setup failed: "
+                       << notify_ret;
+    }
+    peer_notify_qp_num_ = notify_qp_num;
     peer_qp_num_list_ = std::move(peer_qp_num_list);
     has_connected_ = true;
     status_.store(connected_status, std::memory_order_relaxed);
@@ -1110,7 +1477,7 @@ int RdmaEndPoint::doSetupConnection(const std::string &peer_gid,
 }
 
 int RdmaEndPoint::doSetupConnection(int qp_index, const ibv_gid &peer_gid,
-                                    uint16_t peer_lid, uint32_t peer_qp_num,
+                                    uint32_t peer_lid, uint32_t peer_qp_num,
                                     int local_gid_index, std::string *reply_msg,
                                     SetupConnectionFailureInfo *failure_info) {
     if (qp_index < 0 || qp_index >= (int)qp_list_.size())
@@ -1170,7 +1537,11 @@ int RdmaEndPoint::doSetupConnection(int qp_index, const ibv_gid &peer_gid,
         attr.ah_attr.grh.traffic_class =
             static_cast<uint8_t>(globalConfig().ib_traffic_class);
     }
-    attr.ah_attr.dlid = peer_lid;
+#ifdef USE_SHCA
+    attr.ah_attr.dlid = u32_to_17(peer_lid);
+#else
+    attr.ah_attr.dlid = static_cast<uint16_t>(peer_lid);
+#endif
     // Set service level if configured (-1 means use default)
     attr.ah_attr.sl = 0;
     if (globalConfig().ib_service_level >= 0) {
@@ -1194,8 +1565,7 @@ int RdmaEndPoint::doSetupConnection(int qp_index, const ibv_gid &peer_gid,
         LOG(ERROR) << "[Handshake] " << message
                    << ": local=" << context_.nicPath()
                    << ", peer=" << peer_nic_path_ << ", qp_index=" << qp_index
-                   << ", local_qp=" << qp->qp_num
-                   << ", peer_qp=" << peer_qp_num
+                   << ", local_qp=" << qp->qp_num << ", peer_qp=" << peer_qp_num
                    << ", local_gid=" << context_.gid()
                    << ", local_gid_index=" << local_gid_index
                    << ", peer_gid=" << gidToString(peer_gid)
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_transport.cpp b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_transport.cpp
index e444b38b29..138aa4fb54 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/rdma_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/rdma_transport.cpp
@@ -23,18 +23,22 @@
 #include <chrono>
 #include <cstddef>
 #include <cstdlib>
-#include <future>
+#include <memory>
 #include <set>
 #include <thread>
+#include <unordered_map>
 #include <utility>
 
 #include <dlfcn.h>
 
+#include "buffer_range_index.h"
 #include "common.h"
 #include "config.h"
 #include "environ.h"
 #include "memory_location.h"
 #include "topology.h"
+#include "transport/batch_registration.h"
+#include "transport/rdma_transport/rdma_batch_cache.h"
 #include "transport/rdma_transport/rdma_context.h"
 #include "transport/rdma_transport/rdma_endpoint.h"
 
@@ -54,57 +58,76 @@ static std::string resolveBufferLocation(
     return location;
 }
 
-// Calculate remaining bytes in buffer for 'address'.
-// Caches 'last_buffer_idx' across sequential slices to avoid rescanning
-// buffers.
+// The last-hit shortcut and the index lookup both assume the MR covering an
+// address is unique; only then do they answer what a first-match scan would.
+// Descriptors with overlapping MRs, or whose index is out of sync with
+// `buffers`, keep the plain scan, which is first-match by construction.
+static const BufferRangeIndex *uniqueCoverageIndex(
+    const TransferMetadata::SegmentDesc *desc) {
+    if (!desc) return nullptr;
+    const BufferRangeIndex &index = desc->buffer_range_index;
+    if (index.size() != desc->buffers.size() || index.overlaps())
+        return nullptr;
+    return &index;
+}
+
+// Calculate remaining bytes in buffer for 'address'. 'last_buffer_idx' carries
+// the previous hit across slices of one request and across consecutive
+// requests in the same MR; -1 means no hit yet.
 static uint64_t bytesUntilBufferEnd(
     const TransferMetadata::SegmentDesc *segment_desc, uint64_t address,
-    bool require_remote_key, size_t *last_buffer_idx = nullptr) {
+    bool require_remote_key, int *last_buffer_idx = nullptr) {
     if (!segment_desc || segment_desc->buffers.empty()) return 0;
+    const auto &buffers = segment_desc->buffers;
 
-    auto is_valid_buffer = [&](const TransferMetadata::BufferDesc &buffer) {
+    auto is_valid_buffer = [&](int i) {
+        if (i < 0 || static_cast<size_t>(i) >= buffers.size()) return false;
+        const auto &buffer = buffers[static_cast<size_t>(i)];
 #ifdef ENABLE_MULTI_PROTOCOL
         if (!buffer.protocol.empty() && buffer.protocol != "rdma") return false;
 #endif
         if (require_remote_key ? buffer.rkey.empty() : buffer.lkey.empty())
             return false;
-        if (address < buffer.addr || address - buffer.addr >= buffer.length)
-            return false;
-        return true;
+        return bufferCoversPoint(buffer.addr, buffer.length, address);
     };
 
-    if (last_buffer_idx && *last_buffer_idx < segment_desc->buffers.size()) {
-        const auto &buffer = segment_desc->buffers[*last_buffer_idx];
-        if (is_valid_buffer(buffer)) {
-            return buffer.length - (address - buffer.addr);
-        }
+    auto remaining_in = [&](int i) {
+        const auto &buffer = buffers[static_cast<size_t>(i)];
+        return buffer.length - (address - buffer.addr);
+    };
+
+    if (const BufferRangeIndex *index = uniqueCoverageIndex(segment_desc)) {
+        if (last_buffer_idx && is_valid_buffer(*last_buffer_idx))
+            return remaining_in(*last_buffer_idx);
+        const int found = index->findCovering(address, 0);
+        if (!is_valid_buffer(found)) return 0;
+        if (last_buffer_idx) *last_buffer_idx = found;
+        return remaining_in(found);
     }
 
     uint64_t max_remaining = 0;
-    for (size_t i = 0; i < segment_desc->buffers.size(); ++i) {
-        const auto &buffer = segment_desc->buffers[i];
-        if (is_valid_buffer(buffer)) {
-            uint64_t remaining = buffer.length - (address - buffer.addr);
-            if (remaining > max_remaining) {
-                max_remaining = remaining;
-                if (last_buffer_idx) *last_buffer_idx = i;
-            }
+    for (int i = 0; i < static_cast<int>(buffers.size()); ++i) {
+        if (!is_valid_buffer(i)) continue;
+        const uint64_t remaining = remaining_in(i);
+        if (remaining > max_remaining) {
+            max_remaining = remaining;
+            if (last_buffer_idx) *last_buffer_idx = i;
         }
     }
     return max_remaining;
 }
 
 // Calculate slice length capped at MR boundary to avoid multi-MR WRs.
-// Caches source and target buffer indices across slices for a single request.
 struct SliceLengthCalculator {
     const Transport::TransferRequest &request;
     size_t block_size;
     size_t fragment_size;
     const TransferMetadata::SegmentDesc *local_desc;
     const TransferMetadata::SegmentDesc *target_desc;
-
-    size_t src_buffer_idx = 0;
-    size_t tgt_buffer_idx = 0;
+    // Last-hit MR per side. The caller owns the storage so a hit survives
+    // across the consecutive requests that share an MR.
+    int *src_buffer_idx;
+    int *tgt_buffer_idx;
 
     inline size_t calculate(uint64_t offset) {
         const size_t remaining = request.length - offset;
@@ -113,12 +136,12 @@ struct SliceLengthCalculator {
 
         const uint64_t src_rem = bytesUntilBufferEnd(
             local_desc, reinterpret_cast<uint64_t>(request.source) + offset,
-            false, &src_buffer_idx);
+            false, src_buffer_idx);
         if (src_rem > 0)
             slice_length = std::min<uint64_t>(slice_length, src_rem);
 
         const uint64_t tgt_rem = bytesUntilBufferEnd(
-            target_desc, request.target_offset + offset, true, &tgt_buffer_idx);
+            target_desc, request.target_offset + offset, true, tgt_buffer_idx);
         if (tgt_rem > 0)
             slice_length = std::min<uint64_t>(slice_length, tgt_rem);
 
@@ -167,6 +190,8 @@ RdmaTransport::RdmaTransport() {
 }
 
 RdmaTransport::~RdmaTransport() {
+    notify_running_.store(false, std::memory_order_release);
+    if (notify_worker_.joinable()) notify_worker_.join();
 #ifdef CONFIG_USE_BATCH_DESC_SET
     for (auto &entry : batch_desc_set_) delete entry.second;
     batch_desc_set_.clear();
@@ -228,9 +253,26 @@ int RdmaTransport::install(std::string &local_server_name,
         return ret;
     }
 
+    if (std::any_of(context_list_.begin(), context_list_.end(),
+                    [](const auto &context) {
+                        return context->nativeNotifyEnabled();
+                    })) {
+        notify_running_.store(true, std::memory_order_release);
+        notify_worker_ = std::thread(&RdmaTransport::notifyWorkerThread, this);
+    }
     return 0;
 }
 
+void RdmaTransport::notifyWorkerThread() {
+    while (notify_running_.load(std::memory_order_acquire)) {
+        int completed = 0;
+        for (const auto &context : context_list_)
+            completed += std::max(0, context->pollNotificationCq());
+        if (!completed)
+            std::this_thread::sleep_for(std::chrono::microseconds(10));
+    }
+}
+
 int RdmaTransport::preTouchMemory(void *addr, size_t length) {
     if (context_list_.size() == 0) {
         // At least one context is required for pre-touch.
@@ -337,7 +379,7 @@ int RdmaTransport::registerLocalMemoryInternal(void *addr, size_t length,
     // the RAII guard below.
     DmabufExport dmabuf_exp;
     if (!context_list_.empty()) {
-        int eret = RdmaContext::exportDmabuf(addr, dmabuf_exp);
+        int eret = RdmaContext::exportDmabuf(addr, length, dmabuf_exp);
         if (eret != 0) {
             LOG(ERROR) << "Failed to export dma_buf for addr=" << addr;
             return eret;
@@ -693,7 +735,7 @@ int RdmaTransport::allocateLocalSegmentID() {
 }
 
 int RdmaTransport::refreshLocalDeviceDesc(const std::string &device_name,
-                                          uint16_t lid,
+                                          uint32_t lid,
                                           const std::string &gid) {
     std::lock_guard<std::mutex> guard(local_desc_lock_);
     auto original_desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
@@ -737,28 +779,29 @@ int RdmaTransport::registerLocalMemoryBatch(
         }
     } else {
 #endif
-        std::vector<std::future<int>> results;
-        for (auto &buffer : buffer_list) {
-            results.emplace_back(std::async(
-                std::launch::async, [this, buffer, location]() -> int {
-                    // Use force_sequential=true to avoid nested parallelism
-                    return registerLocalMemoryInternal(buffer.addr,
-                                                       buffer.length, location,
-                                                       true, false, true);
-                }));
-        }
+        auto start = std::chrono::steady_clock::now();
+        int first_error =
+            runBoundedRegMrBatch(buffer_list.size(), [&](size_t i) {
+                int ret = registerLocalMemoryInternal(
+                    buffer_list[i].addr, buffer_list[i].length, location, true,
+                    false, true);
+                if (ret) {
+                    LOG(WARNING)
+                        << "RdmaTransport: Failed to register memory: addr "
+                        << buffer_list[i].addr << " length "
+                        << buffer_list[i].length;
+                }
+                return ret;
+            });
+
+        auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+                           std::chrono::steady_clock::now() - start)
+                           .count();
+        LOG(INFO) << "RdmaTransport: registered " << buffer_list.size()
+                  << " buffers on "
+                  << std::min(buffer_list.size(), maxConcurrentRegMr())
+                  << " threads in " << elapsed << "ms";
 
-        int first_error = 0;
-        for (size_t i = 0; i < buffer_list.size(); ++i) {
-            int ret = results[i].get();
-            if (ret) {
-                LOG(WARNING)
-                    << "RdmaTransport: Failed to register memory: addr "
-                    << buffer_list[i].addr << " length "
-                    << buffer_list[i].length;
-                if (!first_error) first_error = ret;
-            }
-        }
         if (first_error) return first_error;
 #if defined(USE_CUDA) || defined(USE_SUPA)
     }  // Environ::Get().GetWithNvidiaPeermem()
@@ -769,24 +812,15 @@ int RdmaTransport::registerLocalMemoryBatch(
 
 int RdmaTransport::unregisterLocalMemoryBatch(
     const std::vector<void *> &addr_list) {
-    std::vector<std::future<int>> results;
-    for (auto &addr : addr_list) {
-        results.emplace_back(
-            std::async(std::launch::async, [this, addr]() -> int {
-                // Use force_sequential=true to avoid nested parallelism
-                return unregisterLocalMemoryInternal(addr, false, true);
-            }));
-    }
-
-    int first_error = 0;
-    for (size_t i = 0; i < addr_list.size(); ++i) {
-        int ret = results[i].get();
+    int first_error = runBoundedRegMrBatch(addr_list.size(), [&](size_t i) {
+        int ret = unregisterLocalMemoryInternal(addr_list[i], false, true);
         if (ret) {
             LOG(WARNING) << "RdmaTransport: Failed to unregister memory: addr "
                          << addr_list[i];
-            if (!first_error) first_error = ret;
         }
-    }
+        return ret;
+    });
+
     int metadata_ret = metadata_->updateLocalSegmentDesc();
     return first_error ? first_error : metadata_ret;
 }
@@ -865,12 +899,24 @@ Status RdmaTransport::submitTransferTask(
         fail_unstarted_tasks(task_index + 1);
     };
     uint64_t nr_slices;
-    for (size_t index = 0; index < task_list.size(); ++index) {
-        assert(task_list[index]);
-        auto &task = *task_list[index];
+    size_t task_index = 0, request_index = 0;
+    BatchRdmaDeviceCache local_device_cache;
+    int last_local_buffer_id = -1;
+    int last_local_device_id = -1;
+    int last_local_device_buffer_id = -1;
+    int last_remote_buffer_id = -1;
+    SegmentID last_remote_target_id = static_cast<SegmentID>(-1);
+    while (task_index < task_list.size()) {
+        assert(task_list[task_index]);
+        auto &task = *task_list[task_index];
+        const size_t current_task_index = task_index;
         nr_slices = 0;
         assert(task.request);
-        auto &request = *task.request;
+        auto &request = task.request[request_index++];
+        if (request_index == task.request_count) {
+            ++task_index;
+            request_index = 0;
+        }
         auto target_desc_it = target_segment_descs.find(request.target_id);
         if (target_desc_it == target_segment_descs.end()) {
             target_desc_it =
@@ -880,18 +926,39 @@ Status RdmaTransport::submitTransferTask(
                     .first;
         }
         const auto &target_segment_desc = target_desc_it->second;
+        if (request.target_id != last_remote_target_id) {
+            last_remote_buffer_id = -1;
+            last_remote_target_id = request.target_id;
+        }
 
         auto request_buffer_id = -1, request_device_id = -1;
-        if (selectDevice(local_segment_desc.get(), (uint64_t)request.source,
-                         request.length, request_buffer_id,
-                         request_device_id)) {
+        const int local_hint_device_id =
+            last_local_device_buffer_id == last_local_buffer_id
+                ? last_local_device_id
+                : -1;
+        if (local_device_cache.select(
+                local_segment_desc, (uint64_t)request.source, request.length,
+                request_buffer_id, request_device_id, [&] {
+                    return selectDevice(
+                        local_segment_desc.get(), (uint64_t)request.source,
+                        request.length, request_buffer_id, request_device_id, 0,
+                        last_local_buffer_id, local_hint_device_id);
+                })) {
             request_buffer_id = -1;
             request_device_id = -1;
+        } else {
+            last_local_buffer_id = request_buffer_id;
+            last_local_device_id = request_device_id;
+            last_local_device_buffer_id = request_buffer_id;
         }
 
-        SliceLengthCalculator slice_calc{request, kBlockSize, kFragmentSize,
+        SliceLengthCalculator slice_calc{request,
+                                         kBlockSize,
+                                         kFragmentSize,
                                          local_segment_desc.get(),
-                                         target_segment_desc.get()};
+                                         target_segment_desc.get(),
+                                         &last_local_buffer_id,
+                                         &last_remote_buffer_id};
         for (uint64_t offset = 0; offset < request.length;) {
             size_t slice_length = slice_calc.calculate(offset);
 
@@ -926,9 +993,14 @@ Status RdmaTransport::submitTransferTask(
                 }
             }
             while (retry_cnt < kMaxRetryCount && !found_device) {
+                const int slice_hint_device_id =
+                    last_local_device_buffer_id == last_local_buffer_id
+                        ? last_local_device_id
+                        : -1;
                 if (selectDevice(local_segment_desc.get(),
                                  (uint64_t)slice->source_addr, slice->length,
-                                 buffer_id, device_id, retry_cnt++))
+                                 buffer_id, device_id, retry_cnt++,
+                                 last_local_buffer_id, slice_hint_device_id))
                     continue;
                 assert(device_id >= 0 &&
                        static_cast<size_t>(device_id) < context_list_.size());
@@ -941,11 +1013,14 @@ Status RdmaTransport::submitTransferTask(
                 assert(local_segment_desc->buffers[buffer_id].lkey.size() ==
                        context_list_.size());
                 found_device = true;
+                last_local_buffer_id = buffer_id;
+                last_local_device_id = device_id;
+                last_local_device_buffer_id = buffer_id;
                 break;
             }
             if (!found_device) {
                 auto source_addr = slice->source_addr;
-                fail_task_and_cleanup(task, slice, index);
+                fail_task_and_cleanup(task, slice, current_task_index);
                 LOG(ERROR)
                     << "Memory region not registered by any active device(s): "
                     << source_addr;
@@ -955,7 +1030,7 @@ Status RdmaTransport::submitTransferTask(
             } else {
                 auto &context = context_list_[device_id];
                 if (!context->active()) {
-                    fail_task_and_cleanup(task, slice, index);
+                    fail_task_and_cleanup(task, slice, current_task_index);
                     LOG(ERROR) << "Device " << device_id << " is not active";
                     return Status::InvalidArgument("Device " +
                                                    std::to_string(device_id) +
@@ -996,9 +1071,14 @@ Status RdmaTransport::getTransferStatus(BatchID batch_id,
     status.resize(task_count);
     for (size_t task_id = 0; task_id < task_count; task_id++) {
         auto &task = batch_desc.task_list[task_id];
-        status[task_id].transferred_bytes = task.transferred_bytes;
-        uint64_t success_slice_count = task.success_slice_count;
-        uint64_t failed_slice_count = task.failed_slice_count;
+        uint64_t success_slice_count =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+        uint64_t failed_slice_count =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+        // Completion counters publish the preceding byte updates. Read bytes
+        // afterwards so a terminal status cannot carry a stale byte count.
+        status[task_id].transferred_bytes =
+            __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
         if (success_slice_count + failed_slice_count == task.slice_count) {
             if (failed_slice_count)
                 status[task_id].s = TransferStatusEnum::FAILED;
@@ -1022,9 +1102,13 @@ Status RdmaTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto &task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Pair with Slice::markSuccess(): observe completion before reading bytes.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count)
             status.s = TransferStatusEnum::FAILED;
@@ -1042,6 +1126,46 @@ RdmaTransport::SegmentID RdmaTransport::getSegmentID(
     return metadata_->getSegmentID(segment_name);
 }
 
+int RdmaTransport::sendNativeNotify(
+    const std::string &peer_server_name,
+    const TransferMetadata::NotifyDesc &notify) {
+    if (!RdmaEndPoint::notificationFits(notify)) return ERR_NOT_IMPLEMENTED;
+    if (context_list_.empty() || !context_list_.front()->nativeNotifyEnabled())
+        return ERR_NOT_IMPLEMENTED;
+    auto peer = metadata_->getSegmentDescByName(peer_server_name);
+    if (!peer) return ERR_METADATA;
+    if (peer->devices.empty()) return ERR_NOT_IMPLEMENTED;
+    auto context = context_list_.front();
+    const auto *device = &peer->devices.front();
+    for (const auto &candidate : peer->devices)
+        if (candidate.name == context->deviceName()) {
+            device = &candidate;
+            break;
+        }
+    auto path = MakeNicPath(peer->nicPathServerName(), device->name);
+    auto lifecycle_lock = context->lockEndpointLifecycle(path);
+    if (!context->active() || context->isConnectPaused(path))
+        return ERR_ENDPOINT;
+    auto endpoint = context->endpoint(path);
+    if (!endpoint) return ERR_ENDPOINT;
+    // Neither handshake RPCs nor send-slot waits may hold the lifecycle gate:
+    // passive setup and retirement need it to make progress.
+    lifecycle_lock.unlock();
+    int ret =
+        endpoint->readyToSend() ? 0 : endpoint->setupConnectionsByActive();
+    lifecycle_lock.lock();
+    if (context->findEndpoint(path) != endpoint || !context->active())
+        return ERR_ENDPOINT;
+    lifecycle_lock.unlock();
+    if (!ret) ret = endpoint->sendNotification(notify);
+    // Never replay a send whose delivery is uncertain. A later call may
+    // create a fresh endpoint after a link fault, using the normal lifecycle.
+    lifecycle_lock.lock();
+    if (endpoint->retired() || endpoint->notificationNeedsReconnect())
+        context->deleteEndpointByPtr(endpoint.get());
+    return ret;
+}
+
 int RdmaTransport::onSetupRdmaConnections(const HandShakeDesc &peer_desc,
                                           HandShakeDesc &local_desc) {
     auto local_nic_name = getNicNameFromNicPath(peer_desc.peer_nic_path);
@@ -1067,6 +1191,8 @@ int RdmaTransport::onSetupRdmaConnections(const HandShakeDesc &peer_desc,
     }
 
     // Use existing endpoint or create new one.
+    auto endpoint_lifecycle_lock =
+        context->lockEndpointLifecycle(peer_desc.local_nic_path);
     auto endpoint = context->endpoint(peer_desc.local_nic_path);
     if (!endpoint) {
         local_desc.reply_msg = "Local RDMA endpoint unavailable for " +
@@ -1104,10 +1230,16 @@ int RdmaTransport::initializeRdmaResources() {
     for (auto &device_name : hca_list) {
         auto context = std::make_shared<RdmaContext>(*this, device_name);
         auto &config = globalConfig();
-        int ret = context->construct(config.num_cq_per_ctx,
-                                     config.num_comp_channels_per_ctx,
-                                     config.port, config.gid_index,
-                                     config.max_cqe, config.max_ep_per_ctx);
+        size_t cq_per_ctx = config.num_cq_per_ctx;
+        if (cq_per_ctx < static_cast<size_t>(config.workers_per_ctx)) {
+            cq_per_ctx = static_cast<size_t>(config.workers_per_ctx);
+            LOG(INFO) << "Increasing RDMA CQ count for " << device_name
+                      << " to match workers_per_ctx=" << config.workers_per_ctx
+                      << " for worker-owned endpoint polling";
+        }
+        int ret = context->construct(
+            cq_per_ctx, config.num_comp_channels_per_ctx, config.port,
+            config.gid_index, config.max_cqe, config.max_ep_per_ctx);
         if (ret) {
             local_topology_->disableDevice(device_name);
             LOG(WARNING) << "Disable device " << device_name;
@@ -1142,92 +1274,132 @@ int RdmaTransport::startHandshakeDaemon(std::string &local_server_name) {
 // According to the request desc, offset and length information, find proper
 // buffer_id and device_id as output.
 // Return 0 if successful, ERR_ADDRESS_NOT_REGISTERED otherwise.
-int RdmaTransport::selectDevice(SegmentDesc *desc, uint64_t offset,
-                                size_t length, std::string_view hint,
-                                int &buffer_id, int &device_id,
-                                int retry_count) {
-    if (desc == nullptr) return ERR_ADDRESS_NOT_REGISTERED;
-    const auto &buffers = desc->buffers;
-    for (buffer_id = 0; buffer_id < static_cast<int>(buffers.size());
-         ++buffer_id) {
-        const auto &buffer = buffers[buffer_id];
+namespace {
 
+bool isSelectableRdmaBuffer(
+    [[maybe_unused]] const TransferMetadata::BufferDesc &buffer) {
 #ifdef ENABLE_MULTI_PROTOCOL
-        // The RDMA transport must only bind buffers registered under the rdma
-        // protocol. Device (hip) buffers alias the same GPU addresses but carry
-        // no lkey/rkey, so picking one yields an empty-lkey out-of-bounds read
-        // in the submit path. The !empty() guard leaves legacy single-protocol
-        // descriptors (empty protocol field) unaffected.
-        if (!buffer.protocol.empty() && buffer.protocol != "rdma") {
-            continue;
-        }
+    // The RDMA transport must only bind buffers registered under the rdma
+    // protocol. Device (hip) buffers alias the same GPU addresses but carry
+    // no lkey/rkey, so picking one yields an empty-lkey out-of-bounds read
+    // in the submit path. The !empty() guard leaves legacy single-protocol
+    // descriptors (empty protocol field) unaffected.
+    if (!buffer.protocol.empty() && buffer.protocol != "rdma") return false;
 #endif
+    return true;
+}
 
-        // Check if offset is within buffer range
-        if (offset < buffer.addr || length > buffer.length ||
-            offset - buffer.addr > buffer.length - length) {
-            continue;
-        }
-
-        // Resolve NUMA-aware location for segmented buffers
-        std::string location = buffer.name;
-        SegmentsLocationInfo seg_info;
-        if (parseSegmentsLocation(buffer.name, seg_info)) {
-            location = resolveSegmentsLocation(seg_info, buffer.length,
-                                               offset - buffer.addr);
-        }
+int pickTopologyDevice(RdmaTransport::SegmentDesc *desc,
+                       const TransferMetadata::BufferDesc &buffer,
+                       uint64_t offset, std::string_view hint,
+                       std::string_view local_hca, int retry_count,
+                       bool by_local_hca) {
+    if (by_local_hca) {
+        const auto location = resolveBufferLocation(buffer, offset);
+        int device_id = desc->topology.selectDeviceByLocalHca(
+            location, local_hca, retry_count);
+        if (device_id >= 0) return device_id;
+        return desc->topology.selectDeviceByLocalHca(kWildcardLocation,
+                                                     local_hca, retry_count);
+    }
 
-        device_id =
-            hint.empty()
-                ? desc->topology.selectDevice(location, retry_count)
-                : desc->topology.selectDevice(location, hint, retry_count);
-        if (device_id >= 0) return 0;
-        device_id = hint.empty() ? desc->topology.selectDevice(
-                                       kWildcardLocation, retry_count)
-                                 : desc->topology.selectDevice(
-                                       kWildcardLocation, hint, retry_count);
-        if (device_id >= 0) return 0;
+    std::string location = buffer.name;
+    SegmentsLocationInfo seg_info;
+    if (parseSegmentsLocation(buffer.name, seg_info)) {
+        location = resolveSegmentsLocation(seg_info, buffer.length,
+                                           offset - buffer.addr);
     }
-    return ERR_ADDRESS_NOT_REGISTERED;
+    int device_id =
+        hint.empty() ? desc->topology.selectDevice(location, retry_count)
+                     : desc->topology.selectDevice(location, hint, retry_count);
+    if (device_id >= 0) return device_id;
+    return hint.empty()
+               ? desc->topology.selectDevice(kWildcardLocation, retry_count)
+               : desc->topology.selectDevice(kWildcardLocation, hint,
+                                             retry_count);
 }
 
-int RdmaTransport::selectDeviceByLocalHca(SegmentDesc *desc, uint64_t offset,
-                                          size_t length,
-                                          std::string_view local_hca,
-                                          int &buffer_id, int &device_id,
-                                          int retry_count) {
+int selectDeviceImpl(RdmaTransport::SegmentDesc *desc, uint64_t offset,
+                     size_t length, std::string_view hint,
+                     std::string_view local_hca, bool by_local_hca,
+                     int &buffer_id, int &device_id, int retry_count,
+                     int hint_buffer_id, int hint_device_id) {
     if (desc == nullptr) return ERR_ADDRESS_NOT_REGISTERED;
     const auto &buffers = desc->buffers;
-    for (buffer_id = 0; buffer_id < static_cast<int>(buffers.size());
-         ++buffer_id) {
-        const auto &buffer = buffers[buffer_id];
 
-#ifdef ENABLE_MULTI_PROTOCOL
-        if (!buffer.protocol.empty() && buffer.protocol != "rdma") {
-            continue;
+    auto try_buffer = [&](int candidate, bool allow_device_reuse) -> bool {
+        if (candidate < 0 || static_cast<size_t>(candidate) >= buffers.size())
+            return false;
+        const auto &buffer = buffers[candidate];
+        if (!isSelectableRdmaBuffer(buffer) ||
+            !bufferCoversRange(buffer.addr, buffer.length, offset, length)) {
+            return false;
         }
-#endif
-
-        if (offset < buffer.addr || length > buffer.length ||
-            offset - buffer.addr > buffer.length - length) {
-            continue;
+        int selected = -1;
+        // Consecutive hits in the same offset-independent MR (typical GPU
+        // "cuda:N" buffers) keep the previous topology pick. retry_count > 0
+        // is a failover walk and must re-run selectDevice.
+        if (allow_device_reuse && retry_count == 0 && hint_device_id >= 0 &&
+            buffer.name.rfind(kSegmentsLocationPrefix, 0) != 0) {
+            const size_t nkeys =
+                by_local_hca ? buffer.lkey.size() : buffer.rkey.size();
+            if (static_cast<size_t>(hint_device_id) < nkeys &&
+                (desc->devices.empty() ||
+                 static_cast<size_t>(hint_device_id) < desc->devices.size())) {
+                selected = hint_device_id;
+            }
         }
+        if (selected < 0) {
+            selected = pickTopologyDevice(desc, buffer, offset, hint, local_hca,
+                                          retry_count, by_local_hca);
+        }
+        if (selected < 0) return false;
+        buffer_id = candidate;
+        device_id = selected;
+        return true;
+    };
 
-        const auto location = resolveBufferLocation(buffer, offset);
-        device_id = desc->topology.selectDeviceByLocalHca(location, local_hca,
-                                                          retry_count);
-        if (device_id >= 0) return 0;
-        device_id = desc->topology.selectDeviceByLocalHca(
-            kWildcardLocation, local_hca, retry_count);
-        if (device_id >= 0) return 0;
+    if (const BufferRangeIndex *index = uniqueCoverageIndex(desc)) {
+        if (try_buffer(hint_buffer_id, true)) return 0;
+        const int found = index->findCovering(offset, length);
+        if (found != hint_buffer_id && try_buffer(found, false)) return 0;
+        return ERR_ADDRESS_NOT_REGISTERED;
+    }
+
+    for (int candidate = 0; candidate < static_cast<int>(buffers.size());
+         ++candidate) {
+        if (try_buffer(candidate, candidate == hint_buffer_id)) return 0;
     }
     return ERR_ADDRESS_NOT_REGISTERED;
 }
 
+}  // namespace
+
+int RdmaTransport::selectDevice(SegmentDesc *desc, uint64_t offset,
+                                size_t length, std::string_view hint,
+                                int &buffer_id, int &device_id, int retry_count,
+                                int hint_buffer_id, int hint_device_id) {
+    return selectDeviceImpl(desc, offset, length, hint, {}, false, buffer_id,
+                            device_id, retry_count, hint_buffer_id,
+                            hint_device_id);
+}
+
+int RdmaTransport::selectDeviceByLocalHca(SegmentDesc *desc, uint64_t offset,
+                                          size_t length,
+                                          std::string_view local_hca,
+                                          int &buffer_id, int &device_id,
+                                          int retry_count, int hint_buffer_id,
+                                          int hint_device_id) {
+    return selectDeviceImpl(desc, offset, length, {}, local_hca, true,
+                            buffer_id, device_id, retry_count, hint_buffer_id,
+                            hint_device_id);
+}
+
 int RdmaTransport::selectDevice(SegmentDesc *desc, uint64_t offset,
                                 size_t length, int &buffer_id, int &device_id,
-                                int retry_count) {
+                                int retry_count, int hint_buffer_id,
+                                int hint_device_id) {
     return selectDevice(desc, offset, length, "", buffer_id, device_id,
-                        retry_count);
+                        retry_count, hint_buffer_id, hint_device_id);
 }
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rdma_transport/worker_pool.cpp b/mooncake-transfer-engine/src/transport/rdma_transport/worker_pool.cpp
index abd24be303..93cef91f09 100644
--- a/mooncake-transfer-engine/src/transport/rdma_transport/worker_pool.cpp
+++ b/mooncake-transfer-engine/src/transport/rdma_transport/worker_pool.cpp
@@ -16,11 +16,19 @@
 
 #include <sys/epoll.h>
 
+#include <algorithm>
 #include <cassert>
+#include <chrono>
+#include <condition_variable>
+#include <exception>
 #include <functional>
+#include <future>
+#include <queue>
+#include <thread>
 
 #include "config.h"
 #include "memory_location.h"
+#include "transport/rdma_transport/rdma_batch_cache.h"
 #include "transport/rdma_transport/rdma_context.h"
 #include "transport/rdma_transport/rdma_endpoint.h"
 #include "transport/rdma_transport/rdma_transport.h"
@@ -31,8 +39,6 @@
 
 namespace mooncake {
 
-const static int kTransferWorkerCount = globalConfig().workers_per_ctx;
-
 static std::string resolveBufferLocation(
     const TransferMetadata::BufferDesc &buffer, uint64_t offset) {
     std::string location = buffer.name;
@@ -49,23 +55,146 @@ static const std::string &sourceLocationOrUnknown(Transport::Slice *slice) {
     return slice->source_location.empty() ? kUnknown : slice->source_location;
 }
 
+struct ActiveEndpointSetupResult {
+    int ret = 0;
+    bool endpoint_current = false;
+};
+
+class ActiveEndpointSetupExecutor {
+   public:
+    explicit ActiveEndpointSetupExecutor(size_t thread_count) : running_(true) {
+        workers_.reserve(thread_count);
+        for (size_t i = 0; i < thread_count; ++i) {
+            workers_.emplace_back([this] { run(); });
+        }
+    }
+
+    ~ActiveEndpointSetupExecutor() {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            running_ = false;
+        }
+        cv_.notify_all();
+        for (auto &worker : workers_) {
+            if (worker.joinable()) worker.join();
+        }
+    }
+
+    std::future<int> submit(const std::shared_ptr<RdmaEndPoint> &endpoint) {
+        std::packaged_task<int()> task(
+            [endpoint] { return endpoint->setupConnectionsByActive(); });
+        auto future = task.get_future();
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            if (!running_) {
+                task();
+                return future;
+            }
+            tasks_.emplace(std::move(task));
+        }
+        cv_.notify_one();
+        return future;
+    }
+
+   private:
+    void run() {
+        while (true) {
+            std::packaged_task<int()> task;
+            {
+                std::unique_lock<std::mutex> lock(mutex_);
+                cv_.wait(lock, [this] { return !running_ || !tasks_.empty(); });
+                if (!running_ && tasks_.empty()) return;
+                task = std::move(tasks_.front());
+                tasks_.pop();
+            }
+            task();
+        }
+    }
+
+    std::vector<std::thread> workers_;
+    std::queue<std::packaged_task<int()>> tasks_;
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    bool running_;
+};
+
+static ActiveEndpointSetupExecutor &activeEndpointSetupExecutor() {
+    constexpr size_t kActiveEndpointSetupThreadCount = 8;
+    static ActiveEndpointSetupExecutor executor(
+        kActiveEndpointSetupThreadCount);
+    return executor;
+}
+
+static ActiveEndpointSetupResult setupEndpointByActiveOutsideLifecycleGate(
+    RdmaContext &context, const std::string &peer_nic_path,
+    const std::shared_ptr<RdmaEndPoint> &endpoint,
+    std::unique_lock<std::mutex> &endpoint_lifecycle_lock,
+    const std::function<int()> &drain_cq_while_waiting) {
+    const bool had_lifecycle_gate = endpoint_lifecycle_lock.owns_lock();
+    if (had_lifecycle_gate) endpoint_lifecycle_lock.unlock();
+
+    // The owner worker also polls this peer's CQ. Keep it draining while the
+    // active handshake can block on TCP connect/read timeouts.
+    int ret = ERR_ENDPOINT;
+    try {
+        auto setup_future = activeEndpointSetupExecutor().submit(endpoint);
+        auto wait_period = std::chrono::milliseconds(1);
+        constexpr auto kMaxWaitPeriod = std::chrono::milliseconds(25);
+        while (setup_future.wait_for(std::chrono::milliseconds(0)) !=
+               std::future_status::ready) {
+            bool made_progress = false;
+            while (setup_future.wait_for(std::chrono::milliseconds(0)) !=
+                   std::future_status::ready) {
+                const int drained = drain_cq_while_waiting();
+                if (drained <= 0) break;
+                made_progress = true;
+            }
+            if (setup_future.wait_for(std::chrono::milliseconds(0)) ==
+                std::future_status::ready) {
+                break;
+            }
+            if (made_progress) {
+                wait_period = std::chrono::milliseconds(1);
+            } else {
+                if (setup_future.wait_for(wait_period) ==
+                    std::future_status::ready) {
+                    break;
+                }
+                wait_period = std::min(wait_period * 2, kMaxWaitPeriod);
+            }
+        }
+        ret = setup_future.get();
+    } catch (const std::exception &ex) {
+        LOG(ERROR) << "Worker: Active endpoint setup threw: " << ex.what();
+    } catch (...) {
+        LOG(ERROR)
+            << "Worker: Active endpoint setup threw an unknown exception";
+    }
+
+    if (had_lifecycle_gate) endpoint_lifecycle_lock.lock();
+    auto current_endpoint = context.findEndpoint(peer_nic_path);
+    return {ret, current_endpoint.get() == endpoint.get() &&
+                     endpoint->active() && !endpoint->retired()};
+}
+
 static int selectPeerDevice(RdmaTransport::SegmentDesc *peer_segment_desc,
                             uint64_t offset, size_t length,
                             const std::string &local_hca, int &buffer_id,
-                            int &device_id, int retry_count = 0) {
+                            int &device_id, int retry_count = 0,
+                            int hint_buffer_id = -1, int hint_device_id = -1) {
     const auto &config = globalConfig();
     int ret = 0;
     if (config.enable_hca_peer_affinity) {
         ret = RdmaTransport::selectDeviceByLocalHca(
             peer_segment_desc, offset, length, local_hca, buffer_id, device_id,
-            retry_count);
+            retry_count, hint_buffer_id, hint_device_id);
     } else {
         auto hint = config.enable_dest_device_affinity
                         ? std::string_view(local_hca)
                         : std::string_view();
-        ret =
-            RdmaTransport::selectDevice(peer_segment_desc, offset, length, hint,
-                                        buffer_id, device_id, retry_count);
+        ret = RdmaTransport::selectDevice(
+            peer_segment_desc, offset, length, hint, buffer_id, device_id,
+            retry_count, hint_buffer_id, hint_device_id);
     }
     if (ret) return ret;
 
@@ -95,44 +224,67 @@ static int selectPeerDevice(RdmaTransport::SegmentDesc *peer_segment_desc,
     return 0;
 }
 
-static bool workerCanPost(int thread_id) {
-    return kTransferWorkerCount == 1 || thread_id != 0;
-}
-
-static bool workerCanPoll(int thread_id) {
-    return kTransferWorkerCount == 1 || thread_id == 0;
-}
-
-static void getPostingShardAssignment(int thread_id, int &post_tid,
-                                      int &post_count) {
-    assert(workerCanPost(thread_id));
-    if (kTransferWorkerCount > 1) {
-        post_tid = thread_id - 1;
-        post_count = kTransferWorkerCount - 1;
-    } else {
-        post_tid = thread_id;
-        post_count = kTransferWorkerCount;
-    }
-}
-
 WorkerPool::WorkerPool(RdmaContext &context, int numa_socket_id)
     : context_(context),
       numa_socket_id_(numa_socket_id),
+      worker_count_(context.transferWorkerCount()),
       workers_running_(true),
       parked_worker_count_(0),
       redispatch_counter_(0),
+      worker_slice_queue_(worker_count_),
+      worker_slice_queue_lock_(worker_count_),
       submitted_slice_count_(0),
       processed_slice_count_(0) {
-    for (int i = 0; i < kShardCount; ++i)
-        slice_queue_count_[i].store(0, std::memory_order_relaxed);
-    collective_slice_queue_.resize(kTransferWorkerCount);
-    for (int i = 0; i < kTransferWorkerCount; ++i)
+    collective_slice_queue_.resize(worker_count_);
+    for (int i = 0; i < worker_count_; ++i)
         worker_thread_.emplace_back(
             std::thread(std::bind(&WorkerPool::transferWorker, this, i)));
     worker_thread_.emplace_back(
         std::thread(std::bind(&WorkerPool::monitorWorker, this)));
 }
 
+int WorkerPool::postingThreadForPeer(const std::string &peer_nic_path) const {
+    return context_.postingThreadForPeer(peer_nic_path);
+}
+
+int WorkerPool::cqIndexForPostingThread(int thread_id) const {
+    return context_.cqIndexForPostingThread(thread_id);
+}
+
+void WorkerPool::enqueueSlicesToOwner(int owner_thread,
+                                      const SliceList &slices) {
+    if (slices.empty()) return;
+    std::lock_guard<std::mutex> lock(worker_slice_queue_lock_[owner_thread]);
+    auto &queues = worker_slice_queue_[owner_thread];
+    const std::string *last_path = nullptr;
+    SliceList *dst = nullptr;
+    for (auto *slice : slices) {
+        const std::string &path = slice->peer_nic_path;
+        if (dst == nullptr || *last_path != path) {
+            last_path = &path;
+            dst = &queues[path];
+        }
+        dst->push_back(slice);
+    }
+}
+
+void WorkerPool::enqueueSliceToOwner(Transport::Slice *slice) {
+    const int owner_thread = postingThreadForPeer(slice->peer_nic_path);
+    if (owner_thread < 0 || owner_thread >= worker_count_) {
+        LOG(ERROR) << "Invalid RDMA worker owner " << owner_thread
+                   << " for peer " << slice->peer_nic_path;
+        slice->markFailed();
+        processed_slice_count_.fetch_add(1);
+        return;
+    }
+    {
+        std::lock_guard<std::mutex> lock(
+            worker_slice_queue_lock_[owner_thread]);
+        worker_slice_queue_[owner_thread][slice->peer_nic_path].push_back(
+            slice);
+    }
+}
+
 WorkerPool::~WorkerPool() {
     if (workers_running_) {
         cond_var_.notify_all();
@@ -179,10 +331,13 @@ int WorkerPool::submitPostSend(
     }
 #endif  // CONFIG_CACHE_SEGMENT_DESC
 
-    SliceList slice_list_map[kShardCount];
+    SliceList prepared_slice_list;
     uint64_t submitted_slice_count = 0;
-    int all_rails_failed_count = 0;
     thread_local std::unordered_map<int, uint64_t> failed_target_ids;
+    BatchRdmaDeviceCache peer_device_cache;
+    int last_buffer_id = -1;
+    int last_device_id = -1;
+    SegmentID last_target_id = static_cast<SegmentID>(-1);
     for (auto &slice : slice_list) {
         if (failed_target_ids.count(slice->target_id)) {
             auto ts = failed_target_ids[slice->target_id];
@@ -195,9 +350,19 @@ int WorkerPool::submitPostSend(
         }
         auto &peer_segment_desc = segment_desc_map[slice->target_id];
         int buffer_id, device_id;
-        if (selectPeerDevice(peer_segment_desc.get(), slice->rdma.dest_addr,
-                             slice->length, context_.deviceName(), buffer_id,
-                             device_id)) {
+        if (slice->target_id != last_target_id) {
+            last_buffer_id = -1;
+            last_device_id = -1;
+            last_target_id = slice->target_id;
+        }
+        if (peer_device_cache.select(
+                peer_segment_desc, slice->rdma.dest_addr, slice->length,
+                buffer_id, device_id, [&] {
+                    return selectPeerDevice(
+                        peer_segment_desc.get(), slice->rdma.dest_addr,
+                        slice->length, context_.deviceName(), buffer_id,
+                        device_id, 0, last_buffer_id, last_device_id);
+                })) {
             peer_segment_desc = context_.engine().meta()->getSegmentDescByID(
                 slice->target_id, true);
             if (!peer_segment_desc) {
@@ -207,10 +372,13 @@ int WorkerPool::submitPostSend(
                 failed_target_ids[slice->target_id] = getCurrentTimeInNano();
                 continue;
             }
+            last_buffer_id = -1;
+            last_device_id = -1;
 
             if (selectPeerDevice(peer_segment_desc.get(), slice->rdma.dest_addr,
                                  slice->length, context_.deviceName(),
-                                 buffer_id, device_id)) {
+                                 buffer_id, device_id, 0, last_buffer_id,
+                                 last_device_id)) {
                 slice->markFailed();
                 context_.engine().meta()->dumpMetadataContent(
                     peer_segment_desc->name, slice->rdma.dest_addr,
@@ -218,6 +386,8 @@ int WorkerPool::submitPostSend(
                 continue;
             }
         }
+        last_buffer_id = buffer_id;
+        last_device_id = device_id;
         if (!peer_segment_desc) {
             slice->markFailed();
             continue;
@@ -243,16 +413,17 @@ int WorkerPool::submitPostSend(
                                 peer_segment_desc->devices[alt_dev_id].name);
                 if (isRailAvailable(alt_path)) {
                     device_id = alt_dev_id;
+                    last_device_id = device_id;
                     slice->rdma.dest_rkey =
                         peer_segment_desc->buffers[buffer_id].rkey[device_id];
                     peer_nic_path = alt_path;
+                    peer_device_cache.invalidate();
                     found = true;
                     break;
                 }
             }
             if (!found) {
                 slice->markFailed();  // All rails unavailable
-                all_rails_failed_count++;
                 continue;
             }
         }
@@ -272,34 +443,32 @@ int WorkerPool::submitPostSend(
                     << reinterpret_cast<void *>(slice->rdma.dest_addr)
                     << ", length=" << slice->length;
         }
-        int shard_id = (slice->target_id * 10007 + device_id) % kShardCount;
-        slice_list_map[shard_id].push_back(slice);
+        prepared_slice_list.push_back(slice);
         submitted_slice_count++;
     }
 
-    enqueuePreparedSlices(slice_list_map, submitted_slice_count);
-
-    // Context-level health tracking: if all slices failed due to no available
-    // rails, increment the context failure counter. This detects catastrophic
-    // local RNIC hardware failure where all paths through the RNIC are down.
-    if (submitted_slice_count == 0 &&
-        all_rails_failed_count == (int)slice_list.size()) {
-        if (markContextFailure()) refreshPublishedLocalTopology();
-    }
+    enqueuePreparedSlices(prepared_slice_list, submitted_slice_count);
 
     return 0;
 }
 
-void WorkerPool::enqueuePreparedSlices(SliceList (&slice_list_map)[kShardCount],
+void WorkerPool::enqueuePreparedSlices(const SliceList &slice_list,
                                        uint64_t submitted_slice_count) {
-    for (int shard_id = 0; shard_id < kShardCount; ++shard_id) {
-        if (slice_list_map[shard_id].empty()) continue;
-        slice_queue_lock_[shard_id].lock();
-        for (auto &slice : slice_list_map[shard_id])
-            slice_queue_[shard_id][slice->peer_nic_path].push_back(slice);
-        slice_queue_count_[shard_id].fetch_add(slice_list_map[shard_id].size(),
-                                               std::memory_order_relaxed);
-        slice_queue_lock_[shard_id].unlock();
+    std::vector<SliceList> by_owner(static_cast<size_t>(worker_count_));
+    for (auto *slice : slice_list) {
+        const int owner_thread = postingThreadForPeer(slice->peer_nic_path);
+        if (owner_thread < 0 || owner_thread >= worker_count_) {
+            LOG(ERROR) << "Invalid RDMA worker owner " << owner_thread
+                       << " for peer " << slice->peer_nic_path;
+            slice->markFailed();
+            processed_slice_count_.fetch_add(1);
+            continue;
+        }
+        by_owner[static_cast<size_t>(owner_thread)].push_back(slice);
+    }
+    for (int owner_thread = 0; owner_thread < worker_count_; ++owner_thread) {
+        enqueueSlicesToOwner(owner_thread,
+                             by_owner[static_cast<size_t>(owner_thread)]);
     }
 
     submitted_slice_count_.fetch_add(submitted_slice_count);
@@ -315,7 +484,7 @@ int WorkerPool::submitPreparedPostSend(
     // Called by a different local RNIC's worker during local failover. The
     // slice already carries the chosen peer_nic_path and refreshed local lkey,
     // so enqueue it directly instead of running remote-path selection again.
-    SliceList slice_list_map[kShardCount];
+    SliceList prepared_slice_list;
     uint64_t submitted_slice_count = 0;
 
     for (auto &slice : slice_list) {
@@ -323,17 +492,73 @@ int WorkerPool::submitPreparedPostSend(
             slice->markFailed();
             continue;
         }
-        auto shard_id = static_cast<int>(
-            std::hash<std::string>{}(slice->peer_nic_path) % kShardCount);
-        slice_list_map[shard_id].push_back(slice);
+        prepared_slice_list.push_back(slice);
         submitted_slice_count++;
     }
 
-    enqueuePreparedSlices(slice_list_map, submitted_slice_count);
+    enqueuePreparedSlices(prepared_slice_list, submitted_slice_count);
 
     return 0;
 }
 
+bool WorkerPool::markLocalContextFailure() {
+    std::lock_guard<std::mutex> lock(context_state_lock_);
+    // Fatal events and an already-tripped breaker leave the context inactive.
+    // Ignore late CQEs in either state so they cannot arm a new TTL after a
+    // fatal event took ownership of recovery.
+    if (!context_.active()) return false;
+
+    int failure_count =
+        context_failure_count_.fetch_add(1, std::memory_order_relaxed) + 1;
+    if (failure_count < kLocalCompletionFailureThreshold) return false;
+
+    context_.set_active(false);
+    breaker_reactivate_after_ns_ =
+        static_cast<uint64_t>(getCurrentTimeInNano()) +
+        static_cast<uint64_t>(globalConfig().context_pause_ttl_ms) * 1000000ull;
+    LOG(WARNING) << "Context breaker tripped: context " << context_.deviceName()
+                 << " pausing after " << failure_count
+                 << " consecutive local completion-failure batches, "
+                 << "pause_ttl_ms=" << globalConfig().context_pause_ttl_ms;
+    return true;
+}
+
+void WorkerPool::markContextSuccess() {
+    if (context_failure_count_.load(std::memory_order_relaxed) == 0) return;
+    std::lock_guard<std::mutex> lock(context_state_lock_);
+    if (breaker_reactivate_after_ns_ == 0)
+        context_failure_count_.store(0, std::memory_order_relaxed);
+}
+
+bool WorkerPool::tryReactivateContext(uint64_t now_ns) {
+    std::lock_guard<std::mutex> lock(context_state_lock_);
+    if (breaker_reactivate_after_ns_ == 0 ||
+        now_ns < breaker_reactivate_after_ns_ ||
+        recovery_activate_after_ns_.load(std::memory_order_relaxed) != 0) {
+        return false;
+    }
+    breaker_reactivate_after_ns_ = 0;
+    context_failure_count_.store(0, std::memory_order_relaxed);
+    context_.set_active(true);
+    return true;
+}
+
+void WorkerPool::maybeReactivateContext() {
+    if (tryReactivateContext(static_cast<uint64_t>(getCurrentTimeInNano()))) {
+        refreshPublishedLocalTopology();
+        LOG(INFO) << "Context breaker pause expired: context "
+                  << context_.deviceName()
+                  << " reactivating (half-open, streak reset)";
+    }
+}
+
+void WorkerPool::resetContextBreaker(bool context_active) {
+    std::lock_guard<std::mutex> lock(context_state_lock_);
+    breaker_reactivate_after_ns_ = 0;
+    context_failure_count_.store(0, std::memory_order_relaxed);
+    context_.set_active(context_active);
+}
+
 void WorkerPool::trackPostedSlices(
     const std::vector<Transport::Slice *> &slice_list, size_t first,
     size_t count) {
@@ -355,51 +580,29 @@ void WorkerPool::untrackPostedSlices(
 }
 
 void WorkerPool::performPostSend(int thread_id) {
-    int post_tid = 0;
-    int post_count = 0;
-    getPostingShardAssignment(thread_id, post_tid, post_count);
     auto &local_slice_queue = collective_slice_queue_[thread_id];
+    {
+        std::lock_guard<std::mutex> lock(worker_slice_queue_lock_[thread_id]);
+        for (auto &entry : worker_slice_queue_[thread_id]) {
+            if (entry.second.empty()) continue;
+            auto &local_entry = local_slice_queue[entry.first];
+            local_entry.insert(local_entry.end(), entry.second.begin(),
+                               entry.second.end());
+        }
+        worker_slice_queue_[thread_id].clear();
+    }
 
     // If this local RNIC is inactive/unhealthy, the remote rail is not the
     // problem. Move queued work to another local RNIC while preserving the
     // already selected peer rail.
-    if (!context_.active() || !contextHealthy()) {
+    if (!context_.active()) {
         auto local_slice_queue_clone = local_slice_queue;
         local_slice_queue.clear();
         for (auto &entry : local_slice_queue_clone)
             redispatch(entry.second, thread_id, true);
-
-        for (int shard_id = post_tid; shard_id < kShardCount;
-             shard_id += post_count) {
-            if (slice_queue_count_[shard_id].load(std::memory_order_relaxed) ==
-                0)
-                continue;
-            slice_queue_lock_[shard_id].lock();
-            auto slice_queue_clone = slice_queue_[shard_id];
-            slice_queue_[shard_id].clear();
-            slice_queue_count_[shard_id].store(0, std::memory_order_relaxed);
-            slice_queue_lock_[shard_id].unlock();
-            for (auto &entry : slice_queue_clone)
-                redispatch(entry.second, thread_id, true);
-        }
         return;
     }
 
-    for (int shard_id = post_tid; shard_id < kShardCount;
-         shard_id += post_count) {
-        if (slice_queue_count_[shard_id].load(std::memory_order_relaxed) == 0)
-            continue;
-
-        slice_queue_lock_[shard_id].lock();
-        for (auto &entry : slice_queue_[shard_id]) {
-            for (auto &slice : entry.second)
-                local_slice_queue[entry.first].push_back(slice);
-            entry.second.clear();
-        }
-        slice_queue_count_[shard_id].store(0, std::memory_order_relaxed);
-        slice_queue_lock_[shard_id].unlock();
-    }
-
     // Redispatch slices to other endpoints, for temporary failures
     thread_local int tl_redispatch_counter = 0;
     if (tl_redispatch_counter <
@@ -408,7 +611,7 @@ void WorkerPool::performPostSend(int thread_id) {
             redispatch_counter_.load(std::memory_order_relaxed);
         auto local_slice_queue_clone = local_slice_queue;
         local_slice_queue.clear();
-        bool handoff_to_local_worker = !context_.active() || !contextHealthy();
+        bool handoff_to_local_worker = !context_.active();
         for (auto &entry : local_slice_queue_clone)
             redispatch(entry.second, thread_id, handoff_to_local_worker);
         return;
@@ -446,12 +649,16 @@ void WorkerPool::performPostSend(int thread_id) {
             entry.second.clear();
             continue;
         }
+        auto endpoint_lifecycle_lock =
+            context_.lockEndpointLifecycle(entry.first);
 #ifdef CONFIG_CACHE_ENDPOINT
         auto &endpoint = endpoint_map[entry.first];
         if (endpoint == nullptr || !endpoint->active())
-            endpoint = context_.endpoint(entry.first);
+            endpoint = context_.endpoint(entry.first,
+                                         cqIndexForPostingThread(thread_id));
 #else
-        auto endpoint = context_.endpoint(entry.first);
+        auto endpoint =
+            context_.endpoint(entry.first, cqIndexForPostingThread(thread_id));
 #endif
         if (!endpoint) {
             for (auto &slice : entry.second) failed_slice_list.push_back(slice);
@@ -459,7 +666,26 @@ void WorkerPool::performPostSend(int thread_id) {
             continue;
         }
         if (!endpoint->connected()) {
-            int setup_ret = endpoint->setupConnectionsByActive();
+            auto setup_result = setupEndpointByActiveOutsideLifecycleGate(
+                context_, entry.first, endpoint, endpoint_lifecycle_lock,
+                [this, thread_id] {
+                    if (!hasOutstandingCq(thread_id)) return 0;
+                    return performPollCq(thread_id, true);
+                });
+            if (!setup_result.endpoint_current) {
+                LOG(WARNING)
+                    << "Worker: Endpoint changed while active handshake was "
+                       "outstanding: "
+                    << entry.first << ", retrying queued slices";
+#ifdef CONFIG_CACHE_ENDPOINT
+                endpoint.reset();
+#endif
+                for (auto &slice : entry.second)
+                    failed_slice_list.push_back(slice);
+                entry.second.clear();
+                continue;
+            }
+            int setup_ret = setup_result.ret;
             if (setup_ret) {
                 // Active handshake setup failures are ambiguous: the failed
                 // side may be the peer rail, or this local RNIC may have just
@@ -549,10 +775,14 @@ void WorkerPool::performPostSend(int thread_id) {
     }
 }
 
-void WorkerPool::performPollCq(int thread_id) {
+int WorkerPool::performPollCq(int thread_id, bool defer_local_redispatch) {
+    if (context_.cqCount() <= 0) return 0;
+    if (thread_id < 0 || thread_id >= worker_count_) return 0;
+
     const uint64_t poll_ts = getCurrentTimeInNano();
     const uint64_t previous_poll_ts =
-        last_poll_ts_ns_.exchange(poll_ts, std::memory_order_relaxed);
+        last_poll_ts_ns_.exchange(poll_ts, std::memory_order_release);
+    last_poll_ts_ns_.notify_all();
     if (previous_poll_ts > 0 && poll_ts > previous_poll_ts) {
         const uint64_t interval = poll_ts - previous_poll_ts;
         last_poll_interval_ns_.store(interval, std::memory_order_relaxed);
@@ -564,7 +794,53 @@ void WorkerPool::performPollCq(int thread_id) {
         }
     }
 
-    // Slices this loop drove to a terminal state, successes and
+    const static size_t kPollCount = 64;
+    std::unordered_map<std::atomic<int> *, int> qp_depth_set;
+    std::vector<ibv_wc> wc_list;
+    const int cq_index = cqIndexForPostingThread(thread_id);
+    if (cq_index < 0) return 0;
+    if (!context_.cq(cq_index)) return 0;
+    ibv_wc wc[kPollCount];
+    int nr_poll = context_.poll(kPollCount, wc, cq_index);
+    if (nr_poll < 0) {
+        LOG(ERROR) << "Worker: Failed to poll completion queues";
+        return nr_poll;
+    }
+
+    if (nr_poll > 0 && globalConfig().track_rdma_posted_slices) {
+        std::lock_guard<std::mutex> lock(posted_slices_mutex_);
+        for (int i = 0; i < nr_poll; ++i) {
+            auto *slice = reinterpret_cast<Transport::Slice *>(wc[i].wr_id);
+            posted_slices_.erase(slice);
+        }
+    }
+
+    for (int i = 0; i < nr_poll; ++i) {
+        Transport::Slice *slice = (Transport::Slice *)wc[i].wr_id;
+        assert(slice);
+        assert(postingThreadForPeer(slice->peer_nic_path) == thread_id);
+        if (qp_depth_set.count(slice->rdma.qp_depth))
+            qp_depth_set[slice->rdma.qp_depth]++;
+        else
+            qp_depth_set[slice->rdma.qp_depth] = 1;
+        wc_list.push_back(wc[i]);
+    }
+    if (nr_poll)
+        context_.cqOutstandingCount(cq_index)->fetch_sub(
+            nr_poll, std::memory_order_acq_rel);
+
+    for (auto &entry : qp_depth_set)
+        entry.first->fetch_sub(entry.second, std::memory_order_acq_rel);
+
+    if (!wc_list.empty())
+        processCompletions(thread_id, wc_list, defer_local_redispatch);
+    return nr_poll;
+}
+
+void WorkerPool::processCompletions(int thread_id,
+                                    const std::vector<ibv_wc> &wc_list,
+                                    bool defer_local_redispatch) {
+    // Slices this call drove to a terminal state, successes and
     // retry-exhausted failures alike; folded into processed_slice_count_,
     // which gates worker parking. Every terminal outcome below goes through
     // finalize_slice() so it is counted exactly once. Slices handed to
@@ -572,8 +848,8 @@ void WorkerPool::performPollCq(int thread_id) {
     int processed_slice_count = 0;
     // Successful completions only, kept apart because it clears the context
     // health counter. A completion error is no evidence that this RNIC can
-    // still move data -- including IBV_WC_WR_FLUSH_ERR, which only reports
-    // WRs the hardware discarded after the QP had already entered ERR.
+    // still move data, including IBV_WC_WR_FLUSH_ERR, which only reports WRs
+    // the hardware discarded after the QP had already entered ERR.
     int succeeded_slice_count = 0;
     auto finalize_slice = [&](Transport::Slice *slice, bool success) {
         if (success) {
@@ -584,122 +860,115 @@ void WorkerPool::performPollCq(int thread_id) {
         }
         processed_slice_count++;
     };
-    const static size_t kPollCount = 64;
-    std::unordered_map<std::atomic<int> *, int> qp_depth_set;
     std::unordered_set<RdmaEndPoint *> local_failed_endpoints;
+    // Peer NIC paths already charged a local-fault error this pass. A QP that
+    // takes a local fault completes every WR it still holds, so one burst must
+    // count as one error against the path, not one per slice.
+    std::unordered_set<std::string> local_failed_peer_paths;
     bool recorded_local_context_failure = false;
     SliceList failed_slice_list;
     SliceList local_failed_slice_list;
-    for (int cq_index = 0; cq_index < context_.cqCount(); cq_index++) {
-        ibv_wc wc[kPollCount];
-        int nr_poll = context_.poll(kPollCount, wc, cq_index);
-        if (nr_poll < 0) {
-            LOG(ERROR) << "Worker: Failed to poll completion queues";
-            continue;
-        }
 
-        if (nr_poll > 0 && globalConfig().track_rdma_posted_slices) {
-            std::lock_guard<std::mutex> lock(posted_slices_mutex_);
-            for (int i = 0; i < nr_poll; ++i) {
-                auto *slice = reinterpret_cast<Transport::Slice *>(wc[i].wr_id);
-                posted_slices_.erase(slice);
+    for (const auto &wc : wc_list) {
+        Transport::Slice *slice = (Transport::Slice *)wc.wr_id;
+        assert(slice);
+        if (wc.status != IBV_WC_SUCCESS) {
+            // Flush errors are generated when QPs transition to ERR state
+            // during normal endpoint destruction (beginDestroy). They are not
+            // real network errors and should not trigger rail failure handling
+            // or endpoint deletion.
+            if (wc.status == IBV_WC_WR_FLUSH_ERR) {
+                if (!context_.active()) {
+                    if (globalConfig().trace)
+                        LOG(INFO) << "Worker: WR flush error on inactive "
+                                  << "local context " << context_.deviceName()
+                                  << " (peer_nic: " << slice->peer_nic_path
+                                  << "), handing off if retry allows";
+                    if (shouldRetrySlice(slice))
+                        local_failed_slice_list.push_back(slice);
+                    else
+                        finalize_slice(slice, false);
+                } else {
+                    if (globalConfig().trace)
+                        LOG(INFO) << "Worker: WR flush error (peer_nic: "
+                                  << slice->peer_nic_path
+                                  << "), redispatching if retry allows";
+                    if (shouldRetrySlice(slice))
+                        failed_slice_list.push_back(slice);
+                    else
+                        finalize_slice(slice, false);
+                }
+                continue;
             }
-        }
 
-        for (int i = 0; i < nr_poll; ++i) {
-            Transport::Slice *slice = (Transport::Slice *)wc[i].wr_id;
-            assert(slice);
-            if (qp_depth_set.count(slice->rdma.qp_depth))
-                qp_depth_set[slice->rdma.qp_depth]++;
-            else
-                qp_depth_set[slice->rdma.qp_depth] = 1;
-            // __sync_fetch_and_sub(slice->rdma.qp_depth, 1);
-            if (wc[i].status != IBV_WC_SUCCESS) {
-                // Flush errors are generated when QPs transition to ERR state
-                // during normal endpoint destruction (beginDestroy). They are
-                // not real network errors and should not trigger rail failure
-                // handling or endpoint deletion.
-                if (wc[i].status == IBV_WC_WR_FLUSH_ERR) {
-                    if (!context_.active()) {
-                        if (globalConfig().trace)
-                            LOG(INFO)
-                                << "Worker: WR flush error on inactive "
-                                << "local context " << context_.deviceName()
-                                << " (peer_nic: " << slice->peer_nic_path
-                                << "), handing off if retry allows";
-                        if (shouldRetrySlice(slice))
-                            local_failed_slice_list.push_back(slice);
-                        else
-                            finalize_slice(slice, false);
-                    } else {
-                        if (globalConfig().trace)
-                            LOG(INFO) << "Worker: WR flush error (peer_nic: "
-                                      << slice->peer_nic_path
-                                      << "), redispatching if retry allows";
-                        if (shouldRetrySlice(slice))
-                            failed_slice_list.push_back(slice);
-                        else
-                            finalize_slice(slice, false);
-                    }
-                    continue;
+            auto endpoint_lifecycle_lock =
+                context_.lockEndpointLifecycle(slice->peer_nic_path);
+
+            // Completion errors are split by local context health. Local faults
+            // hand off to another local RNIC; remote/default faults keep this
+            // local context and switch peer rails.
+            LOG(ERROR) << "Worker: Process failed for slice (opcode: "
+                       << slice->opcode
+                       << ", source_addr: " << slice->source_addr
+                       << ", length: " << slice->length
+                       << ", dest_addr: " << (void *)slice->rdma.dest_addr
+                       << ", local_nic: " << context_.deviceName()
+                       << ", peer_nic: " << slice->peer_nic_path
+                       << ", dest_rkey: " << slice->rdma.dest_rkey
+                       << ", retry_cnt: " << slice->rdma.retry_cnt
+                       << ", max_retry_cnt: " << slice->rdma.max_retry_cnt
+                       << "): " << ibv_wc_status_str(wc.status);
+            auto *retry_list = &failed_slice_list;
+            const bool local_wc_failure = isLocalWcFailure(wc);
+            if (!context_.active() || local_wc_failure) {
+                // A local completion fault retires the endpoint, and the slice
+                // is handed to another local RNIC that rebuilds its own
+                // endpoint to the same peer NIC. If the fault keeps recurring
+                // nothing throttles that cycle: the rail is deliberately not
+                // paused on the local path, and the context failure counter is
+                // cleared by any concurrent success, so both RNICs re-handshake
+                // the same peer as fast as the workers spin. Charge the path an
+                // error instead -- without an immediate pause, so a one-off
+                // fault still costs nothing -- and let kRailErrorThreshold stop
+                // the rebuild loop from this context. See issue #3299.
+                if (local_wc_failure &&
+                    local_failed_peer_paths.insert(slice->peer_nic_path)
+                        .second) {
+                    markRailFailed(slice->peer_nic_path);
                 }
-
-                // Completion errors are split by local context health. Local
-                // faults hand off to another local RNIC; remote/default faults
-                // keep this local context and switch peer rails.
-                LOG(ERROR) << "Worker: Process failed for slice (opcode: "
-                           << slice->opcode
-                           << ", source_addr: " << slice->source_addr
-                           << ", length: " << slice->length
-                           << ", dest_addr: " << (void *)slice->rdma.dest_addr
-                           << ", local_nic: " << context_.deviceName()
-                           << ", peer_nic: " << slice->peer_nic_path
-                           << ", dest_rkey: " << slice->rdma.dest_rkey
-                           << ", retry_cnt: " << slice->rdma.retry_cnt
-                           << ", max_retry_cnt: " << slice->rdma.max_retry_cnt
-                           << "): " << ibv_wc_status_str(wc[i].status);
-                auto *retry_list = &failed_slice_list;
-                if (!context_.active() || isLocalWcFailure(wc[i])) {
-                    if (!recorded_local_context_failure) {
-                        handleLocalFailure(slice->peer_nic_path,
-                                           slice->rdma.endpoint);
-                        recorded_local_context_failure = true;
-                        if (slice->rdma.endpoint)
-                            local_failed_endpoints.insert(slice->rdma.endpoint);
-                    } else if (slice->rdma.endpoint &&
-                               !local_failed_endpoints.count(
-                                   slice->rdma.endpoint)) {
-                        context_.deleteEndpointByPtr(slice->rdma.endpoint);
+                if (!recorded_local_context_failure) {
+                    handleLocalFailure(slice->peer_nic_path,
+                                       slice->rdma.endpoint);
+                    recorded_local_context_failure = true;
+                    if (slice->rdma.endpoint)
                         local_failed_endpoints.insert(slice->rdma.endpoint);
-                    }
-                    retry_list = &local_failed_slice_list;
-                } else {
-                    if (hasAvailablePeerRailAlternative(slice,
-                                                        slice->peer_nic_path)) {
-                        markRailFailed(slice->peer_nic_path, true);
-                        redispatch_counter_++;
-                    }
-                    if (slice->rdma.endpoint) {
-                        context_.deleteEndpointByPtr(slice->rdma.endpoint);
-                    }
+                } else if (slice->rdma.endpoint &&
+                           !local_failed_endpoints.count(
+                               slice->rdma.endpoint)) {
+                    context_.deleteEndpointByPtr(slice->rdma.endpoint);
+                    local_failed_endpoints.insert(slice->rdma.endpoint);
                 }
-                if (shouldRetrySlice(slice)) {
-                    retry_list->push_back(slice);
-                } else {
-                    finalize_slice(slice, false);
+                retry_list = &local_failed_slice_list;
+            } else {
+                if (hasAvailablePeerRailAlternative(slice,
+                                                    slice->peer_nic_path)) {
+                    markRailFailed(slice->peer_nic_path, true);
+                    redispatch_counter_++;
                 }
+                if (slice->rdma.endpoint) {
+                    context_.deleteEndpointByPtr(slice->rdma.endpoint);
+                }
+            }
+            if (shouldRetrySlice(slice)) {
+                retry_list->push_back(slice);
             } else {
-                finalize_slice(slice, true);
+                finalize_slice(slice, false);
             }
+        } else {
+            finalize_slice(slice, true);
         }
-        if (nr_poll)
-            context_.cqOutstandingCount(cq_index)->fetch_sub(
-                nr_poll, std::memory_order_acq_rel);
     }
 
-    for (auto &entry : qp_depth_set)
-        entry.first->fetch_sub(entry.second, std::memory_order_acq_rel);
-
     if (processed_slice_count)
         processed_slice_count_.fetch_add(processed_slice_count);
     // Clear the consecutive-failure counter only on proven data movement, so
@@ -708,18 +977,19 @@ void WorkerPool::performPollCq(int thread_id) {
     if (succeeded_slice_count) markContextSuccess();
 
     if (!local_failed_slice_list.empty()) {
-        redispatch(local_failed_slice_list, thread_id, true);
+        redispatch(local_failed_slice_list, thread_id, true,
+                   defer_local_redispatch);
     }
     if (!failed_slice_list.empty()) {
-        redispatch(failed_slice_list, thread_id);
+        redispatch(failed_slice_list, thread_id, false, defer_local_redispatch);
     }
 }
 
 void WorkerPool::redispatch(std::vector<Transport::Slice *> &slice_list,
-                            int thread_id, bool handoff_to_local_worker) {
+                            int thread_id, bool handoff_to_local_worker,
+                            bool defer_local_redispatch) {
     std::unordered_map<SegmentID, std::shared_ptr<Transport::SegmentDesc>>
         segment_desc_map;
-    const bool use_local_queue = workerCanPost(thread_id);
     int shared_redispatch_count = 0;
     // Remote redispatch needs target metadata to choose a new peer RNIC.
     // Local handoff keeps the peer RNIC fixed and only switches source RNIC, so
@@ -830,17 +1100,12 @@ void WorkerPool::redispatch(std::vector<Transport::Slice *> &slice_list,
                         << ", retry_cnt=" << slice->rdma.retry_cnt;
             }
             slice->ts = 0;
-            if (use_local_queue) {
+            const int owner_thread = postingThreadForPeer(peer_nic_path);
+            if (owner_thread == thread_id && !defer_local_redispatch) {
                 collective_slice_queue_[thread_id][peer_nic_path].push_back(
                     slice);
             } else {
-                int shard_id =
-                    (slice->target_id * 10007 + device_id) % kShardCount;
-                slice_queue_lock_[shard_id].lock();
-                slice_queue_[shard_id][peer_nic_path].push_back(slice);
-                slice_queue_count_[shard_id].fetch_add(
-                    1, std::memory_order_relaxed);
-                slice_queue_lock_[shard_id].unlock();
+                enqueueSliceToOwner(slice);
                 shared_redispatch_count++;
             }
         }
@@ -924,21 +1189,17 @@ bool WorkerPool::tryHandoffToAnotherLocalWorker(Transport::Slice *slice) {
 }
 
 bool WorkerPool::hasOutstandingCq(int thread_id) {
-    if (!workerCanPoll(thread_id)) return false;
-    for (int cq_index = 0; cq_index < context_.cqCount(); ++cq_index) {
-        if (context_.cqOutstandingCount(cq_index)->load(
-                std::memory_order_relaxed) > 0)
-            return true;
-    }
-    return false;
+    if (context_.cqCount() <= 0) return false;
+    const int cq_index = cqIndexForPostingThread(thread_id);
+    if (cq_index < 0) return false;
+    return context_.cqOutstandingCount(cq_index)->load(
+               std::memory_order_relaxed) > 0;
 }
 
 void WorkerPool::transferWorker(int thread_id) {
     bindToSocket(numa_socket_id_);
     const static uint64_t kWaitPeriodInNano = 100000000;  // 100ms
     uint64_t last_wait_ts = getCurrentTimeInNano();
-    const bool can_post = workerCanPost(thread_id);
-    const bool can_poll = workerCanPoll(thread_id);
     while (workers_running_.load(std::memory_order_relaxed)) {
         auto processed_slice_count =
             processed_slice_count_.load(std::memory_order_relaxed);
@@ -963,13 +1224,9 @@ void WorkerPool::transferWorker(int thread_id) {
             }
             continue;
         }
-        if (can_post) {
-            performPostSend(thread_id);
-        }
+        performPostSend(thread_id);
 #ifndef USE_FAKE_POST_SEND
-        if (can_poll) {
-            performPollCq(thread_id);
-        }
+        performPollCq(thread_id);
 #endif
         last_wait_ts = getCurrentTimeInNano();
     }
@@ -995,6 +1252,7 @@ int WorkerPool::doProcessContextEvents() {
                      << context_.deviceName();
         if (event.event_type == IBV_EVENT_QP_FATAL) {
             auto endpoint_ptr = (RdmaEndPoint *)event.element.qp->qp_context;
+            auto endpoint = context_.getEndpointByPtr(endpoint_ptr);
 
             /**
              * There might be a deadlock if we call endpoint->set_active(false)
@@ -1012,13 +1270,17 @@ int WorkerPool::doProcessContextEvents() {
             event_acked = true;
 
             /**
-             * After ack the event, the endpoint might be destroyed if it
-             * happened to be destroying event.element.qp. Therefore, we cannot
-             * just dereference endpoint_ptr. Instead, we need to get the
-             * shared_ptr of the endpoint from context_ and use that shared_ptr
-             * to access the endpoint.
+             * After ack the event, use the tracked endpoint's peer path to
+             * serialize deletion with the same lifecycle gate as post/send and
+             * passive setup.
              */
-            context_.deleteEndpointByPtr(endpoint_ptr);
+            if (endpoint) {
+                auto endpoint_lifecycle_lock =
+                    context_.lockEndpointLifecycle(endpoint->peerNicPath());
+                context_.deleteEndpointByPtr(endpoint.get());
+            } else {
+                LOG(WARNING) << "QP fatal event endpoint is no longer tracked";
+            }
         } else if (handleContextEvent(event.event_type, false, &event)) {
             event_acked = true;
         }
@@ -1045,7 +1307,10 @@ bool WorkerPool::handleContextEvent(ibv_event_type event_type,
         event_type == IBV_EVENT_PORT_ERR ||
         event_type == IBV_EVENT_LID_CHANGE) {
         recovery_activate_after_ns_.store(0, std::memory_order_relaxed);
-        context_.set_active(false);
+        // The async event now owns this context's inactive state. Clear the
+        // local-WC breaker deadline so its TTL cannot resurrect a context that
+        // a DEVICE_FATAL/PORT_ERR took down.
+        resetContextBreaker(false);
         refreshPublishedLocalTopology();
 
         /**
@@ -1062,6 +1327,7 @@ bool WorkerPool::handleContextEvent(ibv_event_type event_type,
          */
         if (event != nullptr) ibv_ack_async_event(event);
 
+        auto endpoint_lifecycle_locks = context_.lockAllEndpointLifecycles();
         context_.disconnectAllEndpoints();
         LOG(INFO) << "Worker: Context " << context_.deviceName()
                   << " is now inactive due to "
@@ -1073,6 +1339,8 @@ bool WorkerPool::handleContextEvent(ibv_event_type event_type,
         if (event != nullptr) ibv_ack_async_event(event);
 
         if (gid_refresh_result != GidRefreshResult::UNCHANGED) {
+            auto endpoint_lifecycle_locks =
+                context_.lockAllEndpointLifecycles();
             context_.disconnectAllEndpoints();
             LOG(INFO) << "Worker: Context " << context_.deviceName()
                       << (injected_for_test ? " injected GID refresh result="
@@ -1083,8 +1351,7 @@ bool WorkerPool::handleContextEvent(ibv_event_type event_type,
     } else if (event_type == IBV_EVENT_PORT_ACTIVE) {
         // PORT_ACTIVE only means the link started coming back. Real mlx5/RoCE
         // data path can still reject RTR for a while after link-up, so delay
-        // publishing this local RNIC back to metadata. Injected tests follow
-        // the same path.
+        // publishing an inactive local RNIC back to metadata.
         scheduleContextRecovery();
         if (event != nullptr) ibv_ack_async_event(event);
     } else {
@@ -1095,6 +1362,15 @@ bool WorkerPool::handleContextEvent(ibv_event_type event_type,
 }
 
 void WorkerPool::scheduleContextRecovery(uint64_t delay_ns) {
+    std::lock_guard<std::mutex> lock(context_state_lock_);
+    // A redundant PORT_ACTIVE on an in-service context is not recovery
+    // evidence: preserve its local-WC streak and do not arm a probe that
+    // could later override a new local-WC trip.
+    if (context_.active()) return;
+
+    // Event recovery owns this inactive period. Cancel only the breaker
+    // deadline; a successful GID probe below resets the failure count.
+    breaker_reactivate_after_ns_ = 0;
     uint64_t activate_after = getCurrentTimeInNano() + delay_ns;
     recovery_activate_after_ns_.store(activate_after,
                                       std::memory_order_relaxed);
@@ -1110,15 +1386,12 @@ void WorkerPool::maybeActivateRecoveredContext() {
         static_cast<uint64_t>(getCurrentTimeInNano()) < activate_after)
         return;
 
-    uint64_t expected = activate_after;
-    if (!recovery_activate_after_ns_.compare_exchange_strong(
-            expected, 0, std::memory_order_relaxed)) {
-        return;
-    }
-
+    // Recovery probes and async events run on the same monitor thread.
+    // Keep the deadline armed throughout GID I/O: event recovery still owns
+    // the inactive context, and late CQEs must not arm breaker recovery.
     auto gid_refresh_result = refreshPublishedLocalGid();
     if (gid_refresh_result == GidRefreshResult::FAILED) {
-        context_.set_active(false);
+        resetContextBreaker(false);
         refreshPublishedLocalTopology();
         scheduleContextRecovery();
         LOG(WARNING) << "Worker: Context " << context_.deviceName()
@@ -1127,14 +1400,15 @@ void WorkerPool::maybeActivateRecoveredContext() {
         return;
     }
     if (gid_refresh_result == GidRefreshResult::CHANGED) {
+        auto endpoint_lifecycle_locks = context_.lockAllEndpointLifecycles();
         context_.disconnectAllEndpoints();
         LOG(INFO) << "Worker: Context " << context_.deviceName()
                   << " GID changed during recovery, disconnected all endpoints";
     }
 
-    context_.set_active(true);
+    resetContextBreaker(true);
+    recovery_activate_after_ns_.store(0, std::memory_order_relaxed);
     refreshPublishedLocalTopology();
-    context_failure_count_.store(0, std::memory_order_relaxed);
     LOG(INFO) << "Worker: Context " << context_.deviceName()
               << " is now active after recovery delay";
 }
@@ -1225,6 +1499,8 @@ void WorkerPool::monitorWorker() {
         const uint64_t current_ts =
             static_cast<uint64_t>(getCurrentTimeInNano());
         maybeActivateRecoveredContext();
+        // Check short breaker TTLs on every loop, like GID recovery.
+        maybeReactivateContext();
         if (current_ts - last_reset_ts > 1000000000ll) {
             // Drain endpoint_store_->waiting_list_ even when no new
             // insertions are happening. Without this, reclaim only runs
@@ -1357,6 +1633,12 @@ void WorkerPool::markRailFailed(const std::string &peer_nic_path,
     std::lock_guard<std::mutex> lock(rail_state_lock_);
     auto &state = rail_states_[peer_nic_path];
     uint64_t now = getCurrentTimeInNano();
+    // Only errors close together are consecutive. error_count is otherwise
+    // never cleared until a pause expires, so isolated failures spread over
+    // hours would eventually pause a rail that is working fine.
+    if (state.last_error_ns && now - state.last_error_ns > kRailErrorWindowNs)
+        state.error_count = 0;
+    state.last_error_ns = now;
     state.error_count++;
     if (immediate_pause && state.error_count < kRailErrorThreshold) {
         state.error_count = kRailErrorThreshold;
@@ -1364,7 +1646,11 @@ void WorkerPool::markRailFailed(const std::string &peer_nic_path,
     if (state.error_count >= kRailErrorThreshold) {
         const uint64_t rail_pause_ns =
             globalConfig().rdma_rail_pause_seconds * 1000000000ull;
+        const bool newly_paused = state.pause_until_ns == 0;
         state.pause_until_ns = now + rail_pause_ns;
+        if (newly_paused) {
+            paused_rail_count_.fetch_add(1, std::memory_order_release);
+        }
         LOG(WARNING) << "Rail paused: peer=" << peer_nic_path
                      << " error_count=" << state.error_count
                      << " pause_ms=" << rail_pause_ns / 1000000ull;
@@ -1372,19 +1658,27 @@ void WorkerPool::markRailFailed(const std::string &peer_nic_path,
 }
 
 bool WorkerPool::isRailAvailable(const std::string &peer_nic_path) {
+    if (paused_rail_count_.load(std::memory_order_acquire) == 0) return true;
     std::lock_guard<std::mutex> lock(rail_state_lock_);
+    // Drop every expired pause while the lock is already held. Otherwise a
+    // dest that is never queried again would leave paused_rail_count_ > 0 and
+    // force every later healthy-path check through this lock.
+    const uint64_t now = getCurrentTimeInNano();
+    int expired = 0;
+    for (auto &entry : rail_states_) {
+        auto &state = entry.second;
+        if (state.pause_until_ns != 0 && now >= state.pause_until_ns) {
+            state.error_count = 0;
+            state.pause_until_ns = 0;
+            ++expired;
+        }
+    }
+    if (expired)
+        paused_rail_count_.fetch_sub(expired, std::memory_order_release);
+
     auto it = rail_states_.find(peer_nic_path);
     if (it == rail_states_.end()) return true;
-    auto &state = it->second;
-    if (state.pause_until_ns == 0) return true;
-    uint64_t now = getCurrentTimeInNano();
-    if (now >= state.pause_until_ns) {
-        // Auto-recover: pause expired
-        state.error_count = 0;
-        state.pause_until_ns = 0;
-        return true;
-    }
-    return false;
+    return it->second.pause_until_ns == 0;
 }
 
 // Unified retry logic: increment retry count and return whether retry is
@@ -1426,7 +1720,10 @@ void WorkerPool::handleLocalFailure(const std::string &peer_nic_path,
     // Local completion faults can be caused by a poisoned QP/MR as well as a
     // bad RNIC. Retry this slice elsewhere, but only disable the whole context
     // after repeated local failures or an async port/device event.
-    bool context_disabled = markContextFailure();
+    // A local WC status is direct evidence about this RNIC. Submit-side
+    // all-rails-unavailable failures remain peer scoped and never contribute
+    // to this counter.
+    bool context_disabled = markLocalContextFailure();
     if (context_disabled) refreshPublishedLocalTopology();
     redispatch_counter_++;
 
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/CMakeLists.txt b/mooncake-transfer-engine/src/transport/rdma_twosided/CMakeLists.txt
new file mode 100644
index 0000000000..9a61f0607e
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/CMakeLists.txt
@@ -0,0 +1,4 @@
+file(GLOB RDMA_TWOSIDED_SOURCES "*.cpp")
+
+add_library(rdma_twosided OBJECT ${RDMA_TWOSIDED_SOURCES})
+target_link_libraries(rdma_twosided PRIVATE JsonCpp::JsonCpp glog::glog pthread)
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_channel.cpp b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_channel.cpp
new file mode 100644
index 0000000000..98401d6b54
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_channel.cpp
@@ -0,0 +1,606 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/rdma_twosided/ctrl_channel.h"
+
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <sstream>
+
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
+
+#include "common.h"
+#include "config.h"
+#include "error.h"
+#include "transport/rdma_twosided/ctrl_frame.h"
+#include "transport/rdma_transport/rdma_context.h"
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
+
+namespace mooncake {
+
+namespace {
+
+constexpr int kCtrlHopLimit = 16;
+constexpr int kCtrlTimeout = 14;
+constexpr int kCtrlRetryCount = 7;
+
+int parseGidString(const std::string &gid_str, ibv_gid &gid_out) {
+    if (gid_str.empty()) return ERR_INVALID_ARGUMENT;
+    std::istringstream iss(":" + gid_str);
+    for (size_t i = 0; i < sizeof(gid_out.raw); i++) {
+        if (iss.get() != ':') return ERR_INVALID_ARGUMENT;
+        uint32_t byte = 0;
+        iss >> std::hex >> byte;
+        if (iss.fail() || byte > 0xFF) return ERR_INVALID_ARGUMENT;
+        gid_out.raw[i] = static_cast<uint8_t>(byte);
+    }
+    char extra;
+    if (iss.get(extra)) return ERR_INVALID_ARGUMENT;
+    return 0;
+}
+
+}  // namespace
+
+CtrlChannel::CtrlChannel(RdmaTwoSidedTransport &transport, RdmaContext &context,
+                         std::string peer_server_name)
+    : transport_(transport),
+      context_(context),
+      peer_server_name_(std::move(peer_server_name)) {
+    auto &cfg = globalConfig();
+    recv_count_ = cfg.rdma_notify_recv_count;
+    buffer_size_ = cfg.rdma_notify_buffer_size;
+    max_pending_sends_ = cfg.rdma_notify_max_pending_sends;
+}
+
+CtrlChannel::~CtrlChannel() { disconnect(); }
+
+int CtrlChannel::construct() {
+    std::lock_guard<std::mutex> lock(resource_mutex_);
+    if (qp_) return 0;
+    return createResources();
+}
+
+int CtrlChannel::createResources() {
+    auto &cfg = globalConfig();
+    recv_count_ = cfg.rdma_notify_recv_count;
+    buffer_size_ = cfg.rdma_notify_buffer_size;
+    max_pending_sends_ = cfg.rdma_notify_max_pending_sends;
+    if (recv_count_ == 0 || buffer_size_ == 0 || max_pending_sends_ == 0) {
+        return ERR_INVALID_ARGUMENT;
+    }
+
+    cq_ = ibv_create_cq(context_.context(), static_cast<int>(cfg.max_cqe),
+                        nullptr, nullptr, 0);
+    if (!cq_) {
+        PLOG(ERROR) << "CtrlChannel: failed to create CQ for peer "
+                    << peer_server_name_;
+        return ERR_ENDPOINT;
+    }
+
+    ibv_qp_init_attr attr{};
+    attr.send_cq = cq_;
+    attr.recv_cq = cq_;
+    attr.qp_type = IBV_QPT_RC;
+    attr.sq_sig_all = 0;
+    attr.cap.max_send_wr = static_cast<uint32_t>(max_pending_sends_);
+    attr.cap.max_recv_wr = static_cast<uint32_t>(recv_count_);
+    attr.cap.max_send_sge = 1;
+    attr.cap.max_recv_sge = 1;
+    attr.cap.max_inline_data = static_cast<uint32_t>(cfg.max_inline);
+
+    qp_ = ibv_create_qp(context_.pd(), &attr);
+    if (!qp_) {
+        PLOG(ERROR) << "CtrlChannel: failed to create QP for peer "
+                    << peer_server_name_;
+        destroyResources();
+        return ERR_ENDPOINT;
+    }
+
+    ibv_qp_attr qp_attr{};
+    qp_attr.qp_state = IBV_QPS_INIT;
+    qp_attr.port_num = context_.portNum();
+    qp_attr.pkey_index = cfg.pkey_index;
+    qp_attr.qp_access_flags = IBV_ACCESS_LOCAL_WRITE;
+    if (ibv_modify_qp(qp_, &qp_attr,
+                      IBV_QP_STATE | IBV_QP_PKEY_INDEX | IBV_QP_PORT |
+                          IBV_QP_ACCESS_FLAGS)) {
+        PLOG(ERROR) << "CtrlChannel: failed to modify QP to INIT";
+        destroyResources();
+        return ERR_ENDPOINT;
+    }
+
+    send_buffer_.assign(buffer_size_ * max_pending_sends_, 0);
+    send_mr_ = ibv_reg_mr(context_.pd(), send_buffer_.data(),
+                          send_buffer_.size(), IBV_ACCESS_LOCAL_WRITE);
+    if (!send_mr_) {
+        PLOG(ERROR) << "CtrlChannel: failed to register send buffer";
+        destroyResources();
+        return ERR_ENDPOINT;
+    }
+
+    recv_buffers_.resize(recv_count_);
+    recv_mrs_.assign(recv_count_, nullptr);
+    for (size_t i = 0; i < recv_count_; ++i) {
+        recv_buffers_[i].assign(buffer_size_, 0);
+        recv_mrs_[i] = ibv_reg_mr(context_.pd(), recv_buffers_[i].data(),
+                                  buffer_size_, IBV_ACCESS_LOCAL_WRITE);
+        if (!recv_mrs_[i]) {
+            PLOG(ERROR) << "CtrlChannel: failed to register recv buffer " << i;
+            destroyResources();
+            return ERR_ENDPOINT;
+        }
+    }
+
+    if (repostAllRecvs()) {
+        destroyResources();
+        return ERR_ENDPOINT;
+    }
+    return 0;
+}
+
+void CtrlChannel::releaseIbResources() {
+    if (qp_) {
+        ibv_destroy_qp(qp_);
+        qp_ = nullptr;
+    }
+    if (cq_) {
+        ibv_destroy_cq(cq_);
+        cq_ = nullptr;
+    }
+    if (send_mr_) {
+        ibv_dereg_mr(send_mr_);
+        send_mr_ = nullptr;
+    }
+    for (auto *mr : recv_mrs_) {
+        if (mr) ibv_dereg_mr(mr);
+    }
+    recv_mrs_.clear();
+    recv_buffers_.clear();
+    send_buffer_.clear();
+}
+
+void CtrlChannel::destroyResources() {
+    // Called from createResources() while resource_mutex_ is already held.
+    // Do not acquire send_mutex_ here (lock-order inversion with
+    // sendCtrlFrame).
+    connected_.store(false, std::memory_order_release);
+    releaseIbResources();
+}
+
+void CtrlChannel::disconnect() {
+    connected_.store(false, std::memory_order_release);
+    {
+        std::lock_guard<std::mutex> lock(send_mutex_);
+        pending_sends_ = 0;
+        send_cv_.notify_all();
+    }
+    std::lock_guard<std::mutex> lock(resource_mutex_);
+    releaseIbResources();
+}
+
+int CtrlChannel::postRecv(size_t idx) {
+    if (!qp_ || idx >= recv_buffers_.size() || !recv_mrs_[idx]) {
+        return ERR_ENDPOINT;
+    }
+    ibv_sge sge{};
+    sge.addr = reinterpret_cast<uint64_t>(recv_buffers_[idx].data());
+    sge.length = static_cast<uint32_t>(buffer_size_);
+    sge.lkey = recv_mrs_[idx]->lkey;
+
+    ibv_recv_wr wr{};
+    wr.wr_id = idx;
+    wr.sg_list = &sge;
+    wr.num_sge = 1;
+
+    ibv_recv_wr *bad = nullptr;
+    int ret = ibv_post_recv(qp_, &wr, &bad);
+    if (ret) {
+        // ibv_post_recv returns errno value on failure (errno itself may be 0).
+        LOG(ERROR) << "CtrlChannel: ibv_post_recv failed idx=" << idx << ": "
+                   << strerror(std::abs(ret)) << " [" << ret << "]";
+        return ERR_ENDPOINT;
+    }
+    return 0;
+}
+
+int CtrlChannel::repostAllRecvs() {
+    for (size_t i = 0; i < recv_count_; ++i) {
+        if (postRecv(i)) return ERR_ENDPOINT;
+    }
+    return 0;
+}
+
+void CtrlChannel::fillLocalDesc(HandShakeDesc &local_desc) const {
+    local_desc = HandShakeDesc();
+    local_desc.local_nic_path = context_.nicPath();
+    local_desc.local_lid = context_.lid();
+    local_desc.local_gid = context_.gid();
+    local_desc.peer_nic_path = "__ctrl__";
+    local_desc.ctrl_channel = true;
+    local_desc.notify_qp_num = notifyQpNum();
+    local_desc.notify_rq_depth = notifyRqDepth();
+}
+
+int CtrlChannel::connectQp(const std::string &peer_gid, uint32_t peer_lid,
+                           uint32_t peer_qp_num) {
+    if (!qp_ || peer_qp_num == 0) return ERR_INVALID_ARGUMENT;
+
+    ibv_gid peer_gid_raw{};
+    if (parseGidString(peer_gid, peer_gid_raw)) {
+        LOG(ERROR) << "CtrlChannel: invalid peer GID " << peer_gid;
+        return ERR_INVALID_ARGUMENT;
+    }
+
+    // First connect leaves the QP in INIT with recv WRs already posted by
+    // createResources(). Only RESET/repost on reconnect; some providers
+    // (e.g. eRDMA) do not clear the RQ on RESET, so re-posting after an
+    // unnecessary RESET fails with ENOMEM.
+    ibv_qp_attr query_attr{};
+    ibv_qp_init_attr query_init_attr{};
+    if (ibv_query_qp(qp_, &query_attr, IBV_QP_STATE, &query_init_attr)) {
+        PLOG(ERROR) << "CtrlChannel: ibv_query_qp failed";
+        return ERR_ENDPOINT;
+    }
+
+    ibv_qp_attr attr{};
+    if (query_attr.qp_state != IBV_QPS_INIT) {
+        attr.qp_state = IBV_QPS_RESET;
+        if (ibv_modify_qp(qp_, &attr, IBV_QP_STATE)) {
+            PLOG(ERROR) << "CtrlChannel: QP RESET failed";
+            return ERR_ENDPOINT;
+        }
+
+        memset(&attr, 0, sizeof(attr));
+        attr.qp_state = IBV_QPS_INIT;
+        attr.port_num = context_.portNum();
+        attr.pkey_index = globalConfig().pkey_index;
+        attr.qp_access_flags = IBV_ACCESS_LOCAL_WRITE;
+        if (ibv_modify_qp(qp_, &attr,
+                          IBV_QP_STATE | IBV_QP_PKEY_INDEX | IBV_QP_PORT |
+                              IBV_QP_ACCESS_FLAGS)) {
+            PLOG(ERROR) << "CtrlChannel: QP INIT failed";
+            return ERR_ENDPOINT;
+        }
+
+        if (repostAllRecvs()) return ERR_ENDPOINT;
+    }
+
+    memset(&attr, 0, sizeof(attr));
+    attr.qp_state = IBV_QPS_RTR;
+    attr.path_mtu = context_.activeMTU();
+    if (globalConfig().mtu_length < attr.path_mtu)
+        attr.path_mtu = globalConfig().mtu_length;
+    attr.ah_attr.is_global = 1;
+    attr.ah_attr.grh.dgid = peer_gid_raw;
+    attr.ah_attr.grh.sgid_index = context_.gidIndex();
+    attr.ah_attr.grh.hop_limit = kCtrlHopLimit;
+    if (globalConfig().ib_traffic_class >= 0) {
+        attr.ah_attr.grh.traffic_class =
+            static_cast<uint8_t>(globalConfig().ib_traffic_class);
+    }
+#ifdef USE_SHCA
+    attr.ah_attr.dlid = u32_to_17(peer_lid);
+#else
+    attr.ah_attr.dlid = static_cast<uint16_t>(peer_lid);
+#endif
+    attr.ah_attr.sl = 0;
+    if (globalConfig().ib_service_level >= 0) {
+        attr.ah_attr.sl = static_cast<uint8_t>(globalConfig().ib_service_level);
+    }
+    attr.ah_attr.port_num = context_.portNum();
+    attr.dest_qp_num = peer_qp_num;
+    attr.rq_psn = 0;
+    attr.max_dest_rd_atomic = 1;
+    attr.min_rnr_timer = 12;
+    if (ibv_modify_qp(qp_, &attr,
+                      IBV_QP_STATE | IBV_QP_PATH_MTU | IBV_QP_MIN_RNR_TIMER |
+                          IBV_QP_AV | IBV_QP_MAX_DEST_RD_ATOMIC |
+                          IBV_QP_DEST_QPN | IBV_QP_RQ_PSN)) {
+        PLOG(ERROR) << "CtrlChannel: QP RTR failed peer_qp=" << peer_qp_num;
+        return ERR_ENDPOINT;
+    }
+
+    memset(&attr, 0, sizeof(attr));
+    attr.qp_state = IBV_QPS_RTS;
+    attr.timeout = kCtrlTimeout;
+    attr.retry_cnt = kCtrlRetryCount;
+    attr.rnr_retry = 7;
+    attr.sq_psn = 0;
+    attr.max_rd_atomic = 1;
+    if (ibv_modify_qp(qp_, &attr,
+                      IBV_QP_STATE | IBV_QP_TIMEOUT | IBV_QP_RETRY_CNT |
+                          IBV_QP_RNR_RETRY | IBV_QP_SQ_PSN |
+                          IBV_QP_MAX_QP_RD_ATOMIC)) {
+        PLOG(ERROR) << "CtrlChannel: QP RTS failed";
+        return ERR_ENDPOINT;
+    }
+
+    connected_.store(true, std::memory_order_release);
+    return 0;
+}
+
+int CtrlChannel::connectActive() {
+    if (construct()) return ERR_ENDPOINT;
+
+    HandShakeDesc local_desc, peer_desc;
+    fillLocalDesc(local_desc);
+
+    int ret =
+        transport_.sendHandshake(peer_server_name_, local_desc, peer_desc);
+    if (ret) {
+        LOG(ERROR) << "CtrlChannel: active handshake failed to "
+                   << peer_server_name_ << " ret=" << ret;
+        return ret;
+    }
+    if (peer_desc.notify_qp_num == 0) {
+        LOG(ERROR) << "CtrlChannel: peer " << peer_server_name_
+                   << " has no notify_qp_num";
+        return ERR_ENDPOINT;
+    }
+
+    max_pending_sends_ = std::min(
+        max_pending_sends_, peer_desc.notify_rq_depth
+                                ? static_cast<size_t>(peer_desc.notify_rq_depth)
+                                : max_pending_sends_);
+
+    {
+        std::lock_guard<std::mutex> lock(resource_mutex_);
+        ret = connectQp(peer_desc.local_gid, peer_desc.local_lid,
+                        peer_desc.notify_qp_num);
+    }
+    if (ret == 0) {
+        LOG(INFO) << "CtrlChannel: connected to " << peer_server_name_
+                  << " local_qp=" << notifyQpNum()
+                  << " peer_qp=" << peer_desc.notify_qp_num;
+        // SESSION_OPEN only here; CREDIT_GRANT is sent after we receive the
+        // peer's SESSION_OPEN (both QPs are RTS by then).
+        (void)postSessionOpen();
+    }
+    return ret;
+}
+
+int CtrlChannel::acceptPassive(const HandShakeDesc &peer_desc,
+                               HandShakeDesc &local_desc) {
+    if (construct()) {
+        local_desc.reply_msg = "CtrlChannel construct failed";
+        return ERR_ENDPOINT;
+    }
+    if (peer_desc.notify_qp_num == 0) {
+        local_desc.reply_msg = "Peer notify_qp_num missing";
+        return ERR_INVALID_ARGUMENT;
+    }
+
+    max_pending_sends_ = std::min(
+        max_pending_sends_, peer_desc.notify_rq_depth
+                                ? static_cast<size_t>(peer_desc.notify_rq_depth)
+                                : max_pending_sends_);
+
+    int ret = 0;
+    {
+        std::lock_guard<std::mutex> lock(resource_mutex_);
+        fillLocalDesc(local_desc);
+        ret = connectQp(peer_desc.local_gid, peer_desc.local_lid,
+                        peer_desc.notify_qp_num);
+    }
+    if (ret) {
+        local_desc.reply_msg = "CtrlChannel connectQp failed";
+        return ret;
+    }
+    LOG(INFO) << "CtrlChannel: accepted from " << peer_server_name_
+              << " local_qp=" << notifyQpNum()
+              << " peer_qp=" << peer_desc.notify_qp_num;
+    (void)postSessionOpen();
+    return 0;
+}
+
+int CtrlChannel::postSessionOpen() {
+    // PR2: SESSION_OPEN / credit / MsgChannel deferred to later PRs.
+    (void)transport_;
+    return 0;
+}
+
+int CtrlChannel::sendCtrlFrame(const CtrlFrame &frame_in) {
+    if (!connected_.load(std::memory_order_acquire)) return ERR_ENDPOINT;
+
+    CtrlFrame frame = frame_in;
+    if (frame.version == 0) frame.version = kCtrlFrameVersion;
+    if (frame.session == 0) frame.session = transport_.localCtrlSessionId();
+
+    std::vector<uint8_t> wired;
+    {
+        std::unique_lock<std::mutex> lock(send_mutex_);
+        if (frame.seq == 0) frame.seq = next_frame_seq_++;
+        if (encodeCtrlFrame(frame, wired)) return ERR_INVALID_ARGUMENT;
+        if (wired.size() > buffer_size_) {
+            LOG(ERROR) << "CtrlChannel: frame too large (" << wired.size()
+                       << " > " << buffer_size_
+                       << ") type=" << static_cast<int>(frame.type);
+            return ERR_INVALID_ARGUMENT;
+        }
+
+        // Poll SEND completions while waiting so a full SQ cannot deadlock
+        // when the caller is (or contends with) the ctrl worker.
+        while (connected_.load(std::memory_order_acquire) &&
+               pending_sends_ >= max_pending_sends_) {
+            lock.unlock();
+            pollSendCompletions(16);
+            lock.lock();
+            if (pending_sends_ < max_pending_sends_) break;
+            send_cv_.wait_for(lock, std::chrono::microseconds(50));
+        }
+        if (!connected_.load(std::memory_order_acquire)) return ERR_ENDPOINT;
+
+        std::lock_guard<std::mutex> resource_guard(resource_mutex_);
+        if (!qp_ || !send_mr_) return ERR_ENDPOINT;
+
+        size_t slot = send_wr_id_ % max_pending_sends_;
+        char *slot_ptr = send_buffer_.data() + slot * buffer_size_;
+        std::memcpy(slot_ptr, wired.data(), wired.size());
+
+        ibv_sge sge{};
+        sge.addr = reinterpret_cast<uint64_t>(slot_ptr);
+        sge.length = static_cast<uint32_t>(wired.size());
+        sge.lkey = send_mr_->lkey;
+
+        ibv_send_wr wr{};
+        wr.wr_id = send_wr_id_++;
+        wr.sg_list = &sge;
+        wr.num_sge = 1;
+        wr.opcode = IBV_WR_SEND;
+        wr.send_flags = IBV_SEND_SIGNALED;
+        if (wired.size() <= globalConfig().max_inline) {
+            wr.send_flags |= IBV_SEND_INLINE;
+        }
+
+        ibv_send_wr *bad = nullptr;
+        int ret = ibv_post_send(qp_, &wr, &bad);
+        if (ret) {
+            LOG(ERROR) << "CtrlChannel: ibv_post_send failed to "
+                       << peer_server_name_ << ": " << strerror(std::abs(ret))
+                       << " [" << ret << "]";
+            return ERR_ENDPOINT;
+        }
+        pending_sends_++;
+    }
+    // Queued, not delivered: the SEND completion (handled in drainCompletions)
+    // decides actual success. A failed WC drops connected_, which routes the
+    // next notify to a fresh channel or to OOB fallback.
+    return 0;
+}
+
+int CtrlChannel::sendNotify(const NotifyDesc &notify) {
+    CtrlFrame frame;
+    frame.type = CtrlFrameType::NOTIFY_COMPAT;
+    if (encodeNotifyCompatPayload(notify, frame.payload))
+        return ERR_INVALID_ARGUMENT;
+    return sendCtrlFrame(frame);
+}
+
+void CtrlChannel::dispatchRecvPayload(const uint8_t *data, size_t byte_len) {
+    // Typed CtrlFrame path (Phase 2+).
+    if (isCtrlFrameMagic(data, byte_len)) {
+        CtrlFrame frame;
+        if (decodeCtrlFrame(data, byte_len, frame)) {
+            LOG(ERROR) << "CtrlChannel: malformed typed frame from "
+                       << peer_server_name_ << " len=" << byte_len;
+            return;
+        }
+        transport_.onCtrlFrameReceived(peer_server_name_, frame);
+        return;
+    }
+
+    // Legacy Phase-1 raw notify wire: [name_len][name][msg_len][msg].
+    if (byte_len < 8) {
+        LOG(ERROR) << "CtrlChannel: short notify message len=" << byte_len;
+        return;
+    }
+    NotifyDesc notify;
+    if (decodeNotifyCompatPayload(data, byte_len, notify)) {
+        LOG(ERROR) << "CtrlChannel: invalid legacy notify from "
+                   << peer_server_name_;
+        return;
+    }
+    transport_.onCtrlNotifyReceived(notify);
+}
+
+void CtrlChannel::handleSendComplete() {
+    std::lock_guard<std::mutex> lock(send_mutex_);
+    if (pending_sends_ > 0) pending_sends_--;
+    send_cv_.notify_one();
+}
+
+void CtrlChannel::handleRecvComplete(const ibv_wc &wc) {
+    // Copy payload then release resources before dispatching callbacks.
+    // Callbacks may sendCtrlFrame (e.g. CREDIT_GRANT) which needs
+    // resource_mutex_ / send_mutex_ — must not hold them here.
+    const size_t idx = static_cast<size_t>(wc.wr_id);
+    const size_t byte_len = wc.byte_len;
+    std::vector<uint8_t> payload;
+    {
+        std::lock_guard<std::mutex> lock(resource_mutex_);
+        if (idx < recv_buffers_.size() && byte_len > 0) {
+            auto *data =
+                reinterpret_cast<const uint8_t *>(recv_buffers_[idx].data());
+            payload.assign(data, data + byte_len);
+        }
+    }
+    if (!payload.empty()) {
+        dispatchRecvPayload(payload.data(), payload.size());
+    }
+    {
+        std::lock_guard<std::mutex> lock(resource_mutex_);
+        postRecv(idx);
+    }
+}
+
+int CtrlChannel::drainCompletions(int max_entries, bool log_poll_error) {
+    std::vector<ibv_wc> wc(static_cast<size_t>(max_entries));
+    int n = 0;
+    {
+        std::lock_guard<std::mutex> lock(resource_mutex_);
+        if (!cq_) return 0;
+        n = ibv_poll_cq(cq_, max_entries, wc.data());
+    }
+    if (n < 0) {
+        if (log_poll_error) {
+            LOG(ERROR) << "CtrlChannel: ibv_poll_cq failed";
+        }
+        return n;
+    }
+    int handled = 0;
+    for (int i = 0; i < n; ++i) {
+        if (wc[i].status != IBV_WC_SUCCESS) {
+            LOG(ERROR) << "CtrlChannel: WC error status=" << wc[i].status
+                       << " opcode=" << wc[i].opcode
+                       << " peer=" << peer_server_name_;
+            connected_.store(false, std::memory_order_release);
+            // The channel is dead, so every outstanding SEND is now void.
+            // Clear the in-flight count here (error WCs may not carry a
+            // reliable opcode/wr_id) and wake SQ-full waiters, which re-check
+            // connected_ and bail with ERR_ENDPOINT. Delivery failures thus
+            // surface as the channel going unconnected rather than as a
+            // per-frame return code.
+            std::lock_guard<std::mutex> lock(send_mutex_);
+            pending_sends_ = 0;
+            send_cv_.notify_all();
+            continue;
+        }
+        if (wc[i].opcode == IBV_WC_SEND) {
+            handleSendComplete();
+            handled++;
+        } else if (wc[i].opcode == IBV_WC_RECV) {
+            // Also required on send-path poll: opportunistic SEND polling must
+            // not drop RECV WCs stolen from the ctrl worker.
+            handleRecvComplete(wc[i]);
+            handled++;
+        }
+    }
+    return handled;
+}
+
+int CtrlChannel::pollSendCompletions(int max_entries) {
+    return drainCompletions(max_entries, /*log_poll_error=*/false);
+}
+
+int CtrlChannel::pollCompletions(int max_entries) {
+    return drainCompletions(max_entries, /*log_poll_error=*/true);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_frame.cpp b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_frame.cpp
new file mode 100644
index 0000000000..0d271b9526
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_frame.cpp
@@ -0,0 +1,252 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+#include <cstring>
+
+#include "error.h"
+
+namespace mooncake {
+
+namespace {
+
+template <typename T>
+void appendPod(std::vector<uint8_t> &out, const T &v) {
+    const auto *p = reinterpret_cast<const uint8_t *>(&v);
+    out.insert(out.end(), p, p + sizeof(T));
+}
+
+template <typename T>
+int readPod(const uint8_t *&ptr, const uint8_t *end, T &v) {
+    if (static_cast<size_t>(end - ptr) < sizeof(T)) return ERR_INVALID_ARGUMENT;
+    std::memcpy(&v, ptr, sizeof(T));
+    ptr += sizeof(T);
+    return 0;
+}
+
+int requireExactEnd(const uint8_t *ptr, const uint8_t *end) {
+    return ptr == end ? 0 : ERR_INVALID_ARGUMENT;
+}
+
+}  // namespace
+
+int encodeNotifyCompatPayload(const TransferMetadata::NotifyDesc &notify,
+                              std::vector<uint8_t> &out) {
+    if (notify.name.size() > UINT32_MAX ||
+        notify.notify_msg.size() > UINT32_MAX)
+        return ERR_INVALID_ARGUMENT;
+    uint32_t name_len = static_cast<uint32_t>(notify.name.size());
+    uint32_t msg_len = static_cast<uint32_t>(notify.notify_msg.size());
+    out.clear();
+    out.reserve(8 + name_len + msg_len);
+    appendPod(out, name_len);
+    out.insert(out.end(), notify.name.begin(), notify.name.end());
+    appendPod(out, msg_len);
+    out.insert(out.end(), notify.notify_msg.begin(), notify.notify_msg.end());
+    return 0;
+}
+
+int decodeNotifyCompatPayload(const uint8_t *data, size_t len,
+                              TransferMetadata::NotifyDesc &notify) {
+    if (!data || len < 8) return ERR_INVALID_ARGUMENT;
+    const uint8_t *ptr = data;
+    const uint8_t *end = data + len;
+    uint32_t name_len = 0, msg_len = 0;
+    if (readPod(ptr, end, name_len)) return ERR_INVALID_ARGUMENT;
+    if (static_cast<size_t>(end - ptr) < name_len) return ERR_INVALID_ARGUMENT;
+    // Preflight remaining length before mutating `notify`.
+    const uint8_t *name_ptr = ptr;
+    ptr += name_len;
+    if (readPod(ptr, end, msg_len)) return ERR_INVALID_ARGUMENT;
+    if (static_cast<size_t>(end - ptr) < msg_len) return ERR_INVALID_ARGUMENT;
+    const uint8_t *msg_ptr = ptr;
+    ptr += msg_len;
+    if (requireExactEnd(ptr, end)) return ERR_INVALID_ARGUMENT;
+
+    TransferMetadata::NotifyDesc decoded;
+    decoded.name.assign(reinterpret_cast<const char *>(name_ptr), name_len);
+    decoded.notify_msg.assign(reinterpret_cast<const char *>(msg_ptr), msg_len);
+    notify = std::move(decoded);
+    return 0;
+}
+
+int encodeCreditGrantPayload(const std::vector<CreditAmount> &grants,
+                             std::vector<uint8_t> &out) {
+    if (grants.size() > UINT16_MAX) return ERR_INVALID_ARGUMENT;
+    out.clear();
+    uint16_t count = static_cast<uint16_t>(grants.size());
+    appendPod(out, count);
+    for (const auto &g : grants) {
+        appendPod(out, static_cast<uint16_t>(g.resource));
+        appendPod(out, g.grant_total);
+    }
+    return 0;
+}
+
+int decodeCreditGrantPayload(const uint8_t *data, size_t len,
+                             std::vector<CreditAmount> &grants) {
+    if (!data || len < sizeof(uint16_t)) return ERR_INVALID_ARGUMENT;
+    const uint8_t *ptr = data;
+    const uint8_t *end = data + len;
+    uint16_t count = 0;
+    if (readPod(ptr, end, count)) return ERR_INVALID_ARGUMENT;
+    constexpr size_t kEntrySize = sizeof(uint16_t) + sizeof(uint64_t);
+    if (count > 4) return ERR_INVALID_ARGUMENT;
+    const size_t need = static_cast<size_t>(count) * kEntrySize;
+    if (static_cast<size_t>(end - ptr) != need) return ERR_INVALID_ARGUMENT;
+
+    std::vector<CreditAmount> decoded;
+    decoded.reserve(count);
+    for (uint16_t i = 0; i < count; ++i) {
+        uint16_t resource = 0;
+        uint64_t total = 0;
+        if (readPod(ptr, end, resource) || readPod(ptr, end, total))
+            return ERR_INVALID_ARGUMENT;
+        if (resource < 1 || resource > 4) return ERR_INVALID_ARGUMENT;
+        decoded.push_back({static_cast<CreditResource>(resource), total});
+    }
+    if (requireExactEnd(ptr, end)) return ERR_INVALID_ARGUMENT;
+    grants = std::move(decoded);
+    return 0;
+}
+
+int encodeDataAckPayload(const std::vector<DataAckEntry> &acks,
+                         std::vector<uint8_t> &out) {
+    if (acks.size() > UINT16_MAX) return ERR_INVALID_ARGUMENT;
+    out.clear();
+    uint16_t count = static_cast<uint16_t>(acks.size());
+    appendPod(out, count);
+    for (const auto &a : acks) {
+        appendPod(out, a.task_id);
+        appendPod(out, a.acked_bytes);
+    }
+    return 0;
+}
+
+int decodeDataAckPayload(const uint8_t *data, size_t len,
+                         std::vector<DataAckEntry> &acks) {
+    if (!data || len < sizeof(uint16_t)) return ERR_INVALID_ARGUMENT;
+    const uint8_t *ptr = data;
+    const uint8_t *end = data + len;
+    uint16_t count = 0;
+    if (readPod(ptr, end, count)) return ERR_INVALID_ARGUMENT;
+    constexpr size_t kEntrySize = sizeof(uint64_t) * 2;
+    const size_t need = static_cast<size_t>(count) * kEntrySize;
+    if (need / kEntrySize != count) return ERR_INVALID_ARGUMENT;  // overflow
+    if (static_cast<size_t>(end - ptr) != need) return ERR_INVALID_ARGUMENT;
+
+    std::vector<DataAckEntry> decoded;
+    decoded.reserve(count);
+    for (uint16_t i = 0; i < count; ++i) {
+        DataAckEntry e;
+        if (readPod(ptr, end, e.task_id) || readPod(ptr, end, e.acked_bytes))
+            return ERR_INVALID_ARGUMENT;
+        decoded.push_back(e);
+    }
+    if (requireExactEnd(ptr, end)) return ERR_INVALID_ARGUMENT;
+    acks = std::move(decoded);
+    return 0;
+}
+
+int encodeSessionOpenPayload(uint32_t bounce_slots, uint32_t bounce_slot_size,
+                             std::vector<uint8_t> &out) {
+    out.clear();
+    appendPod(out, bounce_slots);
+    appendPod(out, bounce_slot_size);
+    return 0;
+}
+
+int decodeSessionOpenPayload(const uint8_t *data, size_t len,
+                             uint32_t &bounce_slots,
+                             uint32_t &bounce_slot_size) {
+    if (!data || len != 8) return ERR_INVALID_ARGUMENT;
+    const uint8_t *ptr = data;
+    const uint8_t *end = data + len;
+    uint32_t slots = 0, size = 0;
+    if (readPod(ptr, end, slots) || readPod(ptr, end, size))
+        return ERR_INVALID_ARGUMENT;
+    if (requireExactEnd(ptr, end)) return ERR_INVALID_ARGUMENT;
+    bounce_slots = slots;
+    bounce_slot_size = size;
+    return 0;
+}
+
+bool isCtrlFrameMagic(const uint8_t *data, size_t len) {
+    if (!data || len < sizeof(uint32_t)) return false;
+    uint32_t magic = 0;
+    std::memcpy(&magic, data, sizeof(magic));
+    return magic == kCtrlFrameMagic;
+}
+
+int encodeCtrlFrame(const CtrlFrame &frame, std::vector<uint8_t> &out) {
+    if (frame.version != kCtrlFrameVersion) return ERR_INVALID_ARGUMENT;
+    if (!isKnownCtrlFrameType(static_cast<uint8_t>(frame.type)))
+        return ERR_INVALID_ARGUMENT;
+    if ((frame.flags & ~kCtrlFrameKnownFlagsMask) != 0)
+        return ERR_INVALID_ARGUMENT;
+    if (frame.payload.size() > UINT32_MAX) return ERR_INVALID_ARGUMENT;
+    out.clear();
+    out.reserve(kCtrlFrameHeaderSize + frame.payload.size());
+    appendPod(out, kCtrlFrameMagic);
+    appendPod(out, frame.version);
+    appendPod(out, static_cast<uint8_t>(frame.type));
+    appendPod(out, frame.flags);
+    appendPod(out, frame.session);
+    appendPod(out, frame.epoch);
+    appendPod(out, frame.seq);
+    appendPod(out, frame.ack_seq);
+    uint32_t payload_len = static_cast<uint32_t>(frame.payload.size());
+    appendPod(out, payload_len);
+    out.insert(out.end(), frame.payload.begin(), frame.payload.end());
+    return 0;
+}
+
+int decodeCtrlFrame(const uint8_t *data, size_t len, CtrlFrame &frame) {
+    if (!data || len < kCtrlFrameHeaderSize) return ERR_INVALID_ARGUMENT;
+    const uint8_t *ptr = data;
+    const uint8_t *end = data + len;
+    uint32_t magic = 0;
+    uint8_t version = 0;
+    uint8_t type = 0;
+    uint16_t flags = 0;
+    uint64_t session = 0, epoch = 0, seq = 0, ack_seq = 0;
+    uint32_t payload_len = 0;
+    if (readPod(ptr, end, magic) || magic != kCtrlFrameMagic)
+        return ERR_INVALID_ARGUMENT;
+    if (readPod(ptr, end, version) || readPod(ptr, end, type) ||
+        readPod(ptr, end, flags) || readPod(ptr, end, session) ||
+        readPod(ptr, end, epoch) || readPod(ptr, end, seq) ||
+        readPod(ptr, end, ack_seq) || readPod(ptr, end, payload_len))
+        return ERR_INVALID_ARGUMENT;
+    if (version != kCtrlFrameVersion) return ERR_INVALID_ARGUMENT;
+    if (!isKnownCtrlFrameType(type)) return ERR_INVALID_ARGUMENT;
+    if ((flags & ~kCtrlFrameKnownFlagsMask) != 0) return ERR_INVALID_ARGUMENT;
+    if (static_cast<size_t>(end - ptr) != payload_len)
+        return ERR_INVALID_ARGUMENT;
+
+    CtrlFrame decoded;
+    decoded.version = version;
+    decoded.type = static_cast<CtrlFrameType>(type);
+    decoded.flags = flags;
+    decoded.session = session;
+    decoded.epoch = epoch;
+    decoded.seq = seq;
+    decoded.ack_seq = ack_seq;
+    decoded.payload.assign(ptr, ptr + payload_len);
+    frame = std::move(decoded);
+    return 0;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_plane.cpp b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_plane.cpp
new file mode 100644
index 0000000000..7bd902cfd3
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/ctrl_plane.cpp
@@ -0,0 +1,279 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
+
+#include <glog/logging.h>
+
+#include <chrono>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "common.h"
+#include "config.h"
+#include "error.h"
+#include "transport/rdma_twosided/ctrl_channel.h"
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+namespace mooncake {
+
+namespace {
+
+// Releases an already-held lock for the duration of a blocking call and
+// reacquires it on scope exit, including when that call throws. Keeps the
+// lock state uniform for the enclosing ConnectScope, whose destructor may
+// then assume the lock is held.
+class UnlockGuard {
+   public:
+    explicit UnlockGuard(std::unique_lock<std::mutex> &lock) : lock_(lock) {
+        DCHECK(lock_.owns_lock());
+        lock_.unlock();
+    }
+    ~UnlockGuard() { lock_.lock(); }
+
+    UnlockGuard(const UnlockGuard &) = delete;
+    UnlockGuard &operator=(const UnlockGuard &) = delete;
+
+   private:
+    std::unique_lock<std::mutex> &lock_;
+};
+
+}  // namespace
+
+RdmaTwoSidedTransport::ConnectScope::ConnectScope(
+    RdmaTwoSidedTransport &transport, std::string peer,
+    std::shared_ptr<CtrlChannel> channel)
+    : transport_(transport),
+      peer_(std::move(peer)),
+      channel_(std::move(channel)) {
+    transport_.ctrl_channels_[peer_] = channel_;
+    transport_.ctrl_connecting_[peer_]++;
+}
+
+RdmaTwoSidedTransport::ConnectScope::~ConnectScope() {
+    auto in_flight = transport_.ctrl_connecting_.find(peer_);
+    if (in_flight != transport_.ctrl_connecting_.end() &&
+        --in_flight->second <= 0) {
+        transport_.ctrl_connecting_.erase(in_flight);
+    }
+    if (!success_) {
+        auto it = transport_.ctrl_channels_.find(peer_);
+        if (it != transport_.ctrl_channels_.end() && it->second == channel_) {
+            transport_.ctrl_channels_.erase(it);
+        }
+    }
+    transport_.ctrl_cv_.notify_all();
+}
+
+int RdmaTwoSidedTransport::onSetupCtrlChannel(const HandShakeDesc &peer_desc,
+                                              HandShakeDesc &local_desc) {
+    if (!globalConfig().rdma_notify_enabled) {
+        local_desc.reply_msg = "RDMA notify disabled";
+        return ERR_INVALID_ARGUMENT;
+    }
+    const auto &contexts = getContextList();
+    if (contexts.empty()) {
+        local_desc.reply_msg = "No local RDMA context for CtrlChannel";
+        return ERR_DEVICE_NOT_FOUND;
+    }
+
+    std::string peer_server_name =
+        getServerNameFromNicPath(peer_desc.local_nic_path);
+    if (peer_server_name.empty()) {
+        local_desc.reply_msg = "Cannot derive peer server name from handshake";
+        return ERR_INVALID_ARGUMENT;
+    }
+
+    std::unique_lock<std::mutex> lock(ctrl_mutex_);
+    if (ctrl_stopping_) {
+        local_desc.reply_msg = "CtrlChannel plane is shutting down";
+        return ERR_ENDPOINT;
+    }
+
+    std::shared_ptr<CtrlChannel> old;
+    auto it = ctrl_channels_.find(peer_server_name);
+    if (it != ctrl_channels_.end()) old = it->second;
+
+    auto channel =
+        std::make_shared<CtrlChannel>(*this, *contexts[0], peer_server_name);
+    // Publishes the placeholder; retracted automatically unless we succeed.
+    ConnectScope scope(*this, peer_server_name, channel);
+    int ret = 0;
+    {
+        UnlockGuard unlocked(lock);
+        if (old) old->disconnect();
+        ret = channel->acceptPassive(peer_desc, local_desc);
+    }
+    if (ret == 0) scope.markSuccess();
+    return ret;
+}
+
+std::shared_ptr<CtrlChannel> RdmaTwoSidedTransport::ensureCtrlChannel(
+    const std::string &peer_server_name) {
+    const auto &contexts = getContextList();
+    if (!globalConfig().rdma_notify_enabled || contexts.empty()) {
+        return nullptr;
+    }
+
+    // Absolute deadline for the whole call, so retries and repeated waits
+    // cannot extend it. On expiry we return nullptr and the caller falls back
+    // to OOB notify instead of blocking forever.
+    const auto deadline = std::chrono::steady_clock::now() +
+                          std::chrono::milliseconds(
+                              globalConfig().rdma_notify_connect_timeout_ms);
+
+    std::unique_lock<std::mutex> lock(ctrl_mutex_);
+    while (true) {
+        if (ctrl_stopping_) return nullptr;
+
+        auto it = ctrl_channels_.find(peer_server_name);
+        const bool connect_in_flight =
+            ctrl_connecting_.find(peer_server_name) != ctrl_connecting_.end();
+        if (it != ctrl_channels_.end() && it->second) {
+            if (it->second->connected()) return it->second;
+            if (!connect_in_flight) {
+                // Channel died after connect (error WC, disconnect). Nobody
+                // republishes or wakes waiters for it, so reclaim it here and
+                // rebuild on the next iteration.
+                auto dead = it->second;
+                ctrl_channels_.erase(it);
+                UnlockGuard unlocked(lock);
+                dead->disconnect();
+                continue;
+            }
+        } else if (!connect_in_flight) {
+            auto channel = std::make_shared<CtrlChannel>(*this, *contexts[0],
+                                                         peer_server_name);
+            ConnectScope scope(*this, peer_server_name, channel);
+            int ret = 0;
+            {
+                UnlockGuard unlocked(lock);
+                ret = channel->connectActive();
+            }
+            if (ret) {
+                // Report our own failure rather than retrying until the
+                // deadline; the caller decides whether to use OOB notify.
+                return nullptr;
+            }
+            auto again = ctrl_channels_.find(peer_server_name);
+            if (again == ctrl_channels_.end() || again->second != channel) {
+                // A passive accept superseded us while the lock was released.
+                UnlockGuard unlocked(lock);
+                channel->disconnect();
+                continue;
+            }
+            scope.markSuccess();
+            return channel;
+        }
+
+        // A connect really is in flight for this peer: wait for its owner to
+        // publish or retract it, bounded by the deadline.
+        if (ctrl_cv_.wait_until(lock, deadline) == std::cv_status::timeout) {
+            LOG(WARNING) << "CtrlChannel: timed out waiting for in-flight "
+                            "connect to "
+                         << peer_server_name;
+            return nullptr;
+        }
+    }
+}
+
+int RdmaTwoSidedTransport::sendRdmaNotify(const std::string &peer_server_name,
+                                          const NotifyDesc &notify) {
+    auto channel = ensureCtrlChannel(peer_server_name);
+    if (!channel) return ERR_ENDPOINT;
+    return channel->sendNotify(notify);
+}
+
+void RdmaTwoSidedTransport::onCtrlNotifyReceived(const NotifyDesc &notify) {
+    if (meta()) meta()->pushNotify(notify);
+}
+
+void RdmaTwoSidedTransport::onCtrlFrameReceived(
+    const std::string &peer_server_name, const CtrlFrame &frame) {
+    switch (frame.type) {
+        case CtrlFrameType::NOTIFY_COMPAT: {
+            NotifyDesc notify;
+            if (decodeNotifyCompatPayload(frame.payload.data(),
+                                          frame.payload.size(), notify) == 0) {
+                onCtrlNotifyReceived(notify);
+            } else {
+                LOG(ERROR) << "CtrlChannel: bad NOTIFY_COMPAT from "
+                           << peer_server_name;
+            }
+            break;
+        }
+        case CtrlFrameType::SESSION_OPEN:
+        case CtrlFrameType::SESSION_CLOSE:
+        case CtrlFrameType::CREDIT_GRANT:
+        case CtrlFrameType::CREDIT_REQUEST:
+        case CtrlFrameType::CREDIT_PROGRESS:
+        case CtrlFrameType::DATA_ACK:
+        case CtrlFrameType::FENCE:
+        case CtrlFrameType::DRAIN_ACK:
+        case CtrlFrameType::CTRL_ACK:
+            VLOG(1) << "CtrlChannel: ignoring frame type "
+                    << static_cast<int>(frame.type) << " from "
+                    << peer_server_name << " (PR2 notify-only)";
+            break;
+        default:
+            LOG(WARNING) << "CtrlChannel: unknown frame type "
+                         << static_cast<int>(frame.type) << " from "
+                         << peer_server_name;
+            break;
+    }
+}
+
+void RdmaTwoSidedTransport::startCtrlWorker() {
+    if (ctrl_worker_running_.exchange(true)) return;
+    ctrl_worker_ = std::thread([this] { ctrlWorkerLoop(); });
+}
+
+void RdmaTwoSidedTransport::stopCtrlWorker() {
+    {
+        // Release waiters before joining: a thread parked on ctrl_cv_ must not
+        // outlive the plane it is waiting on. Notify under the lock so a waiter
+        // that has not parked yet cannot miss the wakeup.
+        std::lock_guard<std::mutex> lock(ctrl_mutex_);
+        ctrl_stopping_ = true;
+        ctrl_cv_.notify_all();
+    }
+    if (!ctrl_worker_running_.exchange(false)) return;
+    if (ctrl_worker_.joinable()) ctrl_worker_.join();
+}
+
+void RdmaTwoSidedTransport::ctrlWorkerLoop() {
+    while (ctrl_worker_running_.load(std::memory_order_acquire)) {
+        std::vector<std::shared_ptr<CtrlChannel>> channels;
+        {
+            std::lock_guard<std::mutex> lock(ctrl_mutex_);
+            channels.reserve(ctrl_channels_.size());
+            for (auto &entry : ctrl_channels_) {
+                if (entry.second) channels.push_back(entry.second);
+            }
+        }
+        int processed = 0;
+        for (auto &channel : channels) {
+            int ret = channel->pollCompletions(16);
+            if (ret > 0) processed += ret;
+        }
+        if (processed == 0) {
+            std::this_thread::sleep_for(std::chrono::microseconds(100));
+        }
+    }
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/rdma_twosided_transport.cpp b/mooncake-transfer-engine/src/transport/rdma_twosided/rdma_twosided_transport.cpp
new file mode 100644
index 0000000000..b2b463de99
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/rdma_twosided_transport.cpp
@@ -0,0 +1,63 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
+
+#include <glog/logging.h>
+
+#include <mutex>
+#include <random>
+
+#include "config.h"
+#include "transport/rdma_twosided/ctrl_channel.h"
+
+namespace mooncake {
+
+RdmaTwoSidedTransport::RdmaTwoSidedTransport() {
+    std::random_device rd;
+    std::mt19937_64 gen(rd());
+    local_ctrl_session_id_ = gen();
+    if (local_ctrl_session_id_ == 0) local_ctrl_session_id_ = 1;
+}
+
+RdmaTwoSidedTransport::~RdmaTwoSidedTransport() {
+    stopCtrlWorker();
+    std::lock_guard<std::mutex> lock(ctrl_mutex_);
+    for (auto &entry : ctrl_channels_) {
+        if (entry.second) entry.second->disconnect();
+    }
+    ctrl_channels_.clear();
+    ctrl_cv_.notify_all();
+}
+
+int RdmaTwoSidedTransport::install(std::string &local_server_name,
+                                   std::shared_ptr<TransferMetadata> meta,
+                                   std::shared_ptr<Topology> topo) {
+    int ret = RdmaTransport::install(local_server_name, meta, topo);
+    if (ret) return ret;
+    if (globalConfig().rdma_notify_enabled) {
+        startCtrlWorker();
+    }
+    return 0;
+}
+
+int RdmaTwoSidedTransport::onSetupRdmaConnections(
+    const HandShakeDesc &peer_desc, HandShakeDesc &local_desc) {
+    if (peer_desc.ctrl_channel) {
+        return onSetupCtrlChannel(peer_desc, local_desc);
+    }
+    return RdmaTransport::onSetupRdmaConnections(peer_desc, local_desc);
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rdma_twosided/sender_credit.cpp b/mooncake-transfer-engine/src/transport/rdma_twosided/sender_credit.cpp
new file mode 100644
index 0000000000..4b53741c9f
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/rdma_twosided/sender_credit.cpp
@@ -0,0 +1,193 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/rdma_twosided/sender_credit.h"
+
+#include "error.h"
+
+namespace mooncake {
+
+int SenderCreditLedger::resourceIndex(CreditResource r, size_t &idx) {
+    auto raw = static_cast<uint16_t>(r);
+    if (raw < 1 || raw > kResourceCount) return ERR_INVALID_ARGUMENT;
+    idx = raw - 1;
+    return 0;
+}
+
+int SenderCreditLedger::normalize(
+    const std::vector<std::pair<CreditResource, uint64_t>> &charge,
+    std::array<uint64_t, kResourceCount> &out) {
+    out.fill(0);
+    if (charge.empty()) return ERR_INVALID_ARGUMENT;
+    for (const auto &item : charge) {
+        size_t i = 0;
+        if (resourceIndex(item.first, i)) return ERR_INVALID_ARGUMENT;
+        if (item.second == 0 || out[i] != 0) return ERR_INVALID_ARGUMENT;
+        out[i] = item.second;
+    }
+    return 0;
+}
+
+int SenderCreditLedger::activate(const std::string &peer, uint64_t session,
+                                 uint64_t epoch) {
+    if (peer.empty() || epoch == 0) return ERR_INVALID_ARGUMENT;
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it != entries_.end()) {
+        if (epoch < it->second.epoch) return ERR_INVALID_ARGUMENT;
+        if (epoch == it->second.epoch) return 0;
+        Entry replacement;
+        replacement.epoch = epoch;
+        it->second = replacement;
+        return 0;
+    }
+    if (entries_.size() >= max_entries_) return ERR_TOO_MANY_REQUESTS;
+    Entry e;
+    e.epoch = epoch;
+    entries_.emplace(std::move(key), e);
+    return 0;
+}
+
+int SenderCreditLedger::deactivate(const std::string &peer, uint64_t session,
+                                   uint64_t epoch) {
+    if (epoch == 0) return ERR_INVALID_ARGUMENT;
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it == entries_.end()) return 0;
+    if (it->second.epoch != epoch) return ERR_INVALID_ARGUMENT;
+    entries_.erase(it);
+    return 0;
+}
+
+int SenderCreditLedger::applyGrant(const std::string &peer, uint64_t session,
+                                   uint64_t epoch, uint64_t seq,
+                                   const std::vector<CreditAmount> &grants,
+                                   int &disposition) {
+    disposition = 0;
+    if (epoch == 0 || seq == 0 || grants.size() > kResourceCount)
+        return ERR_INVALID_ARGUMENT;
+    std::array<uint64_t, kResourceCount> proposed{};
+    std::array<bool, kResourceCount> present{};
+    for (const auto &g : grants) {
+        size_t i = 0;
+        if (resourceIndex(g.resource, i)) return ERR_INVALID_ARGUMENT;
+        if (present[i]) return ERR_INVALID_ARGUMENT;
+        present[i] = true;
+        proposed[i] = g.grant_total;
+    }
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it == entries_.end() || it->second.epoch != epoch)
+        return ERR_INVALID_ARGUMENT;
+    auto &e = it->second;
+    if (e.has_update && seq <= e.last_sequence) {
+        disposition = 1;  // duplicate/old
+        return 0;
+    }
+    for (size_t i = 0; i < kResourceCount; ++i) {
+        if (present[i] &&
+            (proposed[i] < e.grants[i] || proposed[i] < e.consumed[i]))
+            return ERR_INVALID_ARGUMENT;
+    }
+    bool gap = e.has_update && seq > e.last_sequence + 1;
+    for (size_t i = 0; i < kResourceCount; ++i)
+        if (present[i]) e.grants[i] = proposed[i];
+    e.last_sequence = seq;
+    e.has_update = true;
+    disposition = gap ? 2 : 0;
+    return 0;
+}
+
+int SenderCreditLedger::tryReserve(
+    const std::string &peer, uint64_t session, uint64_t epoch,
+    const std::vector<std::pair<CreditResource, uint64_t>> &charge) {
+    if (epoch == 0) return ERR_INVALID_ARGUMENT;
+    std::array<uint64_t, kResourceCount> n{};
+    if (normalize(charge, n)) return ERR_INVALID_ARGUMENT;
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it == entries_.end() || it->second.epoch != epoch)
+        return ERR_INVALID_ARGUMENT;
+    if (!it->second.has_update) return ERR_TOO_MANY_REQUESTS;
+    auto &e = it->second;
+    for (size_t i = 0; i < kResourceCount; ++i) {
+        if (e.consumed[i] > e.grants[i] || n[i] > e.grants[i] - e.consumed[i])
+            return ERR_TOO_MANY_REQUESTS;
+    }
+    for (size_t i = 0; i < kResourceCount; ++i) e.consumed[i] += n[i];
+    return 0;
+}
+
+int SenderCreditLedger::rollbackReservation(
+    const std::string &peer, uint64_t session, uint64_t epoch,
+    const std::vector<std::pair<CreditResource, uint64_t>> &charge) {
+    if (epoch == 0) return ERR_INVALID_ARGUMENT;
+    std::array<uint64_t, kResourceCount> n{};
+    if (normalize(charge, n)) return ERR_INVALID_ARGUMENT;
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it == entries_.end() || it->second.epoch != epoch)
+        return ERR_INVALID_ARGUMENT;
+    for (size_t i = 0; i < kResourceCount; ++i) {
+        if (n[i] > it->second.consumed[i]) return ERR_INVALID_ARGUMENT;
+    }
+    for (size_t i = 0; i < kResourceCount; ++i) it->second.consumed[i] -= n[i];
+    return 0;
+}
+
+int SenderCreditLedger::available(const std::string &peer, uint64_t session,
+                                  uint64_t epoch, CreditResource resource,
+                                  uint64_t &out) const {
+    if (epoch == 0) return ERR_INVALID_ARGUMENT;
+    size_t i = 0;
+    if (resourceIndex(resource, i)) return ERR_INVALID_ARGUMENT;
+    std::lock_guard<std::mutex> lock(mutex_);
+    Key key{peer, session};
+    auto it = entries_.find(key);
+    if (it == entries_.end() || it->second.epoch != epoch)
+        return ERR_INVALID_ARGUMENT;
+    const auto &e = it->second;
+    out = (e.grants[i] > e.consumed[i]) ? (e.grants[i] - e.consumed[i]) : 0;
+    return 0;
+}
+
+uint64_t SenderCreditLedger::availableForPeer(const std::string &peer,
+                                              CreditResource resource) const {
+    size_t i = 0;
+    if (resourceIndex(resource, i)) return 0;
+    std::lock_guard<std::mutex> lock(mutex_);
+    uint64_t total = 0;
+    for (const auto &entry : entries_) {
+        if (entry.first.peer != peer) continue;
+        const auto &e = entry.second;
+        if (!e.has_update) continue;
+        if (e.grants[i] > e.consumed[i]) total += e.grants[i] - e.consumed[i];
+    }
+    return total;
+}
+
+bool SenderCreditLedger::hasPeer(const std::string &peer) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    for (const auto &entry : entries_) {
+        if (entry.first.peer == peer) return true;
+    }
+    return false;
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/rpc_communicator/CMakeLists.txt b/mooncake-transfer-engine/src/transport/rpc_communicator/CMakeLists.txt
index 3b6bf0cd25..f9d459c29a 100644
--- a/mooncake-transfer-engine/src/transport/rpc_communicator/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/rpc_communicator/CMakeLists.txt
@@ -4,37 +4,16 @@ find_package(Python3 COMPONENTS Interpreter Development.Module REQUIRED)
 
 add_library(rpc_communicator OBJECT ${CORO_RPC_SOURCES})
 
-target_link_libraries(rpc_communicator 
-    PRIVATE 
-    JsonCpp::JsonCpp 
-    yalantinglibs::yalantinglibs 
-    glog::glog 
-    pthread 
+target_link_libraries(rpc_communicator
+    PUBLIC
+    pybind11::headers
+    yalantinglibs::yalantinglibs
+    PRIVATE
+    glog::glog
+    pthread
 )
 
-target_include_directories(rpc_communicator 
-    PRIVATE 
+target_include_directories(rpc_communicator
+    PRIVATE
     ${Python3_INCLUDE_DIRS}
 )
-
-if(TARGET pybind11::headers)
-    target_link_libraries(rpc_communicator PRIVATE pybind11::headers)
-elseif(DEFINED pybind11_INCLUDE_DIR)
-    target_include_directories(rpc_communicator PRIVATE ${pybind11_INCLUDE_DIR})
-else()
-    set(_PYBIND11_DIR "")
-    if(EXISTS "${CMAKE_SOURCE_DIR}/extern/pybind11/include/pybind11/pybind11.h")
-        set(_PYBIND11_DIR "${CMAKE_SOURCE_DIR}/extern/pybind11/include")
-    else()
-        get_filename_component(_PROJECT_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../../" ABSOLUTE)
-        set(_PYBIND11_DIR "${_PROJECT_ROOT}/extern/pybind11/include")
-        if(NOT EXISTS "${_PYBIND11_DIR}/pybind11/pybind11.h")
-            set(_PYBIND11_DIR "")
-        endif()
-    endif()
-    if(_PYBIND11_DIR)
-        target_include_directories(rpc_communicator PRIVATE "${_PYBIND11_DIR}")
-    else()
-        message(FATAL_ERROR "Could not find pybind11")
-    endif()
-endif()
\ No newline at end of file
diff --git a/mooncake-transfer-engine/src/transport/rpc_communicator/rpc_communicator.cpp b/mooncake-transfer-engine/src/transport/rpc_communicator/rpc_communicator.cpp
index 18d3c2ad03..832a73e194 100644
--- a/mooncake-transfer-engine/src/transport/rpc_communicator/rpc_communicator.cpp
+++ b/mooncake-transfer-engine/src/transport/rpc_communicator/rpc_communicator.cpp
@@ -58,10 +58,12 @@ bool RpcCommunicator::initialize(const RpcCommunicatorConfig& config) {
     // Initialize client pools with proper configuration
     coro_io::client_pool<coro_rpc::coro_rpc_client>::pool_config pool_conf{};
     const char* value = std::getenv("MC_RPC_PROTOCOL");
+#ifdef YLT_ENABLE_IBV
     if (value && std::string_view(value) == "rdma") {
         pool_conf.client_config.socket_config =
             coro_io::ib_socket_t::config_t{};
     }
+#endif
     if (config.pool_size > 0 &&
         config.pool_size <= std::numeric_limits<uint32_t>::max()) {
         pool_conf.max_connection = static_cast<uint32_t>(config.pool_size);
@@ -83,6 +85,7 @@ bool RpcCommunicator::initialize(const RpcCommunicatorConfig& config) {
             config.thread_count, config.listen_address,
             std::chrono::seconds(config.timeout_seconds));
 
+#ifdef YLT_ENABLE_IBV
         if (value && std::string_view(value) == "rdma") {
             if (server_) {
                 try {
@@ -103,6 +106,7 @@ bool RpcCommunicator::initialize(const RpcCommunicatorConfig& config) {
                 LOG(WARNING) << "Falling back to TCP mode";
             }
         }
+#endif
 
         server_->register_handler<&RpcCommunicator::handleDataTransfer,
                                   &RpcCommunicator::handleTensorTransfer>(this);
@@ -110,7 +114,12 @@ bool RpcCommunicator::initialize(const RpcCommunicatorConfig& config) {
     LOG(INFO) << "Environment variable MC_RPC_PROTOCOL is set to "
               << (value ? value : "not set");
     if (value && std::string_view(value) == "rdma") {
+#ifdef YLT_ENABLE_IBV
         LOG(INFO) << "Using RDMA transport for RPC communication";
+#else
+        LOG(WARNING) << "RDMA RPC is disabled at compile time; using TCP "
+                        "transport for RPC communication";
+#endif
     } else {
         LOG(INFO) << "Using TCP transport for RPC communication";
     }
diff --git a/mooncake-transfer-engine/src/transport/shm_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/shm_transport/CMakeLists.txt
new file mode 100644
index 0000000000..2e0a2f9115
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/shm_transport/CMakeLists.txt
@@ -0,0 +1,7 @@
+file(GLOB SHM_SOURCES "*.cpp")
+
+add_library(shm_transport OBJECT ${SHM_SOURCES})
+target_link_libraries(shm_transport PRIVATE glog::glog)
+if(UNIX AND NOT APPLE)
+  target_link_libraries(shm_transport PRIVATE rt)
+endif()
diff --git a/mooncake-transfer-engine/src/transport/shm_transport/shm_transport.cpp b/mooncake-transfer-engine/src/transport/shm_transport/shm_transport.cpp
new file mode 100644
index 0000000000..6ff1cfe596
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/shm_transport/shm_transport.cpp
@@ -0,0 +1,1065 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "transport/shm_transport/shm_transport.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/magic.h>
+#include <stdlib.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/vfs.h>
+#include <unistd.h>
+
+#include <cassert>
+#include <cstdint>
+#include <cstring>
+#include <glog/logging.h>
+#include <limits>
+#include <memory>
+#include <sstream>
+#include <utility>
+#include <vector>
+
+#include "error.h"
+
+namespace mooncake {
+namespace {
+
+std::string randomShmName() {
+    std::string result = std::string(kPosixShmNamePrefix) +
+                         std::to_string(static_cast<long>(getpid())) + "_";
+    for (int i = 0; i < 8; ++i) result += 'a' + SimpleRandom::Get().next(26);
+    return result;
+}
+
+// POSIX: "/mooncake_<pid>_<rand>". Hugetlbfs: dir + that same name.
+std::string randomShmPath(const std::string& dir = {}) {
+    if (dir.empty()) return randomShmName();
+    std::string result = dir;
+    if (result.back() == '/') result.pop_back();
+    result += randomShmName();
+    return result;
+}
+
+bool rangeContains(uint64_t start, uint64_t span, uint64_t addr,
+                   uint64_t length) {
+    if (addr < start) return false;
+    const uint64_t offset = addr - start;
+    return offset <= span && span - offset >= length;
+}
+
+bool needsHugetlbfsPeerOpen(const std::string& shm_name) {
+    return shm_name.find('/', 1) != std::string::npos ||
+           pathHasDotDotComponent(shm_name);
+}
+
+std::string realpathExisting(const std::string& path, std::string* err) {
+    char* resolved = realpath(path.c_str(), nullptr);
+    if (!resolved) {
+        if (err) {
+            *err = "realpath(" + path + ") failed: " + std::strerror(errno);
+        }
+        return {};
+    }
+    std::string out(resolved);
+    free(resolved);
+    return out;
+}
+
+bool isHugetlbfsFd(int fd) {
+    struct statfs sfs;
+    return fstatfs(fd, &sfs) == 0 && sfs.f_type == HUGETLBFS_MAGIC;
+}
+
+// Peer must never create the owner's object, follow a symlink, or open a
+// path that escapes the hugetlbfs mount (e.g. /dev/hugepages/../../tmp/...).
+int openHugetlbfsPeerFd(const std::string& shm_name, std::string* err) {
+    if (shm_name.size() < 2 || shm_name.front() != '/' ||
+        pathHasDotDotComponent(shm_name) || !isPosixShmName(shm_name)) {
+        if (err) {
+            *err = "invalid hugetlbfs shm path: " + shm_name;
+        }
+        errno = EINVAL;
+        return -1;
+    }
+
+    std::string resolved = realpathExisting(shm_name, err);
+    if (resolved.empty()) return -1;
+    if (pathHasDotDotComponent(resolved) || !isPosixShmName(resolved) ||
+        resolved.front() != '/') {
+        if (err) {
+            *err = "resolved shm path is not a mooncake hugetlbfs object: " +
+                   resolved;
+        }
+        errno = EINVAL;
+        return -1;
+    }
+
+    struct statfs sfs;
+    if (statfs(resolved.c_str(), &sfs) != 0 || sfs.f_type != HUGETLBFS_MAGIC) {
+        if (err) {
+            *err = "resolved shm path is not on hugetlbfs: " + resolved;
+        }
+        errno = EINVAL;
+        return -1;
+    }
+
+    const int fd = open(resolved.c_str(), O_RDWR | O_CLOEXEC | O_NOFOLLOW);
+    if (fd < 0) {
+        if (err) {
+            *err = "open(" + resolved + ") failed: " + std::strerror(errno);
+        }
+        return -1;
+    }
+    if (!isHugetlbfsFd(fd)) {
+        close(fd);
+        if (err) {
+            *err = "opened fd is not hugetlbfs: " + resolved;
+        }
+        errno = EINVAL;
+        return -1;
+    }
+    return fd;
+}
+
+bool shmObjectExists(const std::string& shm_name) {
+    int fd = -1;
+    if (needsHugetlbfsPeerOpen(shm_name)) {
+        fd = openHugetlbfsPeerFd(shm_name, nullptr);
+    } else {
+        fd = shm_open(shm_name.c_str(), O_RDWR, 0);
+    }
+    if (fd < 0) return false;
+    close(fd);
+    return true;
+}
+
+uint64_t rangeEnd(uint64_t start, uint64_t span) {
+    if (span == 0) return start;
+    if (start > std::numeric_limits<uint64_t>::max() - span) {
+        return std::numeric_limits<uint64_t>::max();
+    }
+    return start + span;
+}
+
+bool rangesOverlap(uint64_t a, uint64_t a_len, uint64_t b, uint64_t b_len) {
+    return a < rangeEnd(b, b_len) && b < rangeEnd(a, a_len);
+}
+
+bool protocolListContains(const std::string& protocol,
+                          const std::string& token) {
+    std::stringstream ss(protocol);
+    std::string item;
+    while (std::getline(ss, item, ',')) {
+        if (item == token) return true;
+    }
+    return false;
+}
+
+Status mapSharedMemory(const std::string& shm_name, uint64_t length, void** out,
+                       uint64_t* mapped_length) {
+    int shm_fd = -1;
+    if (needsHugetlbfsPeerOpen(shm_name)) {
+        std::string open_err;
+        shm_fd = openHugetlbfsPeerFd(shm_name, &open_err);
+        if (shm_fd < 0) {
+            return Status::Memory(open_err.empty()
+                                      ? (std::string("Failed to open shared "
+                                                     "memory ") +
+                                         shm_name)
+                                      : open_err);
+        }
+    } else {
+        shm_fd = shm_open(shm_name.c_str(), O_RDWR, 0600);
+    }
+    if (shm_fd < 0) {
+        return Status::Memory(std::string("Failed to open shared memory ") +
+                              shm_name);
+    }
+    struct stat st;
+    if (fstat(shm_fd, &st) != 0) {
+        close(shm_fd);
+        return Status::Memory(std::string("Failed to fstat shared memory ") +
+                              shm_name);
+    }
+    // Map the full file (st_size). Owner may publish a shorter logical prefix
+    // in BufferDesc.length; hugetlbfs mmap/munmap must still be page-aligned.
+    if (st.st_size <= 0 || static_cast<uint64_t>(st.st_size) < length) {
+        close(shm_fd);
+        return Status::Memory(
+            std::string("Shared memory file shorter than registered "
+                        "buffer length: ") +
+            shm_name);
+    }
+    const uint64_t map_len = static_cast<uint64_t>(st.st_size);
+    void* mapped =
+        mmap(nullptr, map_len, PROT_READ | PROT_WRITE, MAP_SHARED, shm_fd, 0);
+    close(shm_fd);
+    if (mapped == MAP_FAILED) {
+        return Status::Memory("Failed to map shared memory");
+    }
+    *out = mapped;
+    if (mapped_length) *mapped_length = map_len;
+    return Status::OK();
+}
+
+size_t posixBufferCount(const TransferMetadata::SegmentDesc& desc) {
+    size_t count = 0;
+    for (const auto& entry : desc.buffers) {
+        if (isPosixShmName(entry.shm_name)) ++count;
+    }
+    return count;
+}
+
+bool posixBufferAddrListed(const TransferMetadata::SegmentDesc& desc,
+                           uint64_t addr) {
+    for (const auto& entry : desc.buffers) {
+        if (isPosixShmName(entry.shm_name) && entry.addr == addr) return true;
+    }
+    return false;
+}
+
+bool resolveHugetlbfsMount(const std::string& dir, size_t hugepage_size,
+                           std::string* canonical, std::string* err) {
+    if (dir.empty() || dir.front() != '/') {
+        if (err) *err = "hugetlbfs_path must be an absolute path";
+        return false;
+    }
+    if (pathHasDotDotComponent(dir)) {
+        if (err) *err = "hugetlbfs_path must not contain '..'";
+        return false;
+    }
+    std::string resolved = realpathExisting(dir, err);
+    if (resolved.empty()) return false;
+
+    struct statfs sfs;
+    if (statfs(resolved.c_str(), &sfs) != 0) {
+        if (err) {
+            *err = "statfs(" + resolved + ") failed: " + std::strerror(errno);
+        }
+        return false;
+    }
+    if (sfs.f_type != HUGETLBFS_MAGIC) {
+        if (err) {
+            *err = resolved + " is not a hugetlbfs mount";
+        }
+        return false;
+    }
+    if (static_cast<size_t>(sfs.f_bsize) != hugepage_size) {
+        if (err) {
+            *err = resolved + " hugepage size is " +
+                   std::to_string(sfs.f_bsize) + ", expected " +
+                   std::to_string(hugepage_size);
+        }
+        return false;
+    }
+    if (canonical) *canonical = std::move(resolved);
+    return true;
+}
+
+bool prepareHugetlbfsAllocate(const SharedMemoryOptions& opt, size_t length,
+                              std::string* dir, int* error) {
+    auto fail = [&](int err) {
+        if (error) *error = err;
+        return false;
+    };
+    const size_t hp = opt.hugepage_size == 0 ? SharedMemoryOptions::kHugepage2MB
+                                             : opt.hugepage_size;
+    if (!SharedMemoryOptions::isSupportedHugepageSize(hp)) {
+        LOG(ERROR) << "ShmTransport hugepage SHM supports only 2MB, 512MB, or "
+                      "1GB, got "
+                   << hp;
+        return fail(EINVAL);
+    }
+    if (length % hp != 0) {
+        LOG(ERROR) << "ShmTransport hugepage allocation length " << length
+                   << " is not a multiple of hugepage size " << hp;
+        return fail(EINVAL);
+    }
+    const std::string requested_dir =
+        opt.hugetlbfs_path.empty()
+            ? SharedMemoryOptions::defaultHugetlbfsPathFor(hp)
+            : opt.hugetlbfs_path;
+    std::string mount_err;
+    if (!resolveHugetlbfsMount(requested_dir, hp, dir, &mount_err)) {
+        const int err =
+            (requested_dir.empty() || requested_dir.front() != '/' ||
+             pathHasDotDotComponent(requested_dir))
+                ? EINVAL
+                : ENODEV;
+        LOG(ERROR) << "ShmTransport hugetlbfs allocate failed: " << mount_err
+                   << " (no tmpfs fallback)";
+        return fail(err);
+    }
+    if (error) *error = 0;
+    return true;
+}
+
+}  // namespace
+
+ShmTransport::ShmTransport() = default;
+
+void ShmTransport::unlinkShmEntry(const AllocatedShmEntry& entry) {
+    // Not reached on SIGKILL; leftovers and manual cleanup:
+    // SharedMemoryOptions.
+    if (entry.name.empty()) return;
+    if (isFilesystemShmPath(entry.name)) {
+        if (unlink(entry.name.c_str()) != 0 && errno != ENOENT) {
+            PLOG(WARNING) << "Failed to unlink hugetlbfs shm " << entry.name;
+        }
+    } else if (shm_unlink(entry.name.c_str()) != 0 && errno != ENOENT) {
+        PLOG(WARNING) << "Failed to shm_unlink " << entry.name;
+    }
+}
+
+ShmTransport::~ShmTransport() {
+    PendingUnmap pending;
+    {
+        RWSpinlock::WriteGuard guard(relocate_lock_);
+        for (auto& relocate_map : relocate_map_) {
+            for (auto& entry : relocate_map.second) {
+                if (!entry.second || !entry.second->shm_addr ||
+                    !entry.second->length) {
+                    continue;
+                }
+                pending.emplace_back(entry.second->shm_addr,
+                                     entry.second->length);
+                entry.second->shm_addr = nullptr;
+                entry.second->length = 0;
+            }
+        }
+        relocate_map_.clear();
+    }
+    flushUnmaps(pending);
+    {
+        std::lock_guard<std::mutex> lock(shm_path_mutex_);
+        for (auto& entry : shm_path_map_) {
+            if (entry.first && entry.second.length) {
+                munmap(entry.first, entry.second.length);
+            }
+            unlinkShmEntry(entry.second);
+        }
+        shm_path_map_.clear();
+    }
+    if (metadata_ && !local_server_name_.empty()) {
+        metadata_->removeSegmentDesc(local_server_name_);
+    }
+}
+
+int ShmTransport::install(std::string& local_server_name,
+                          std::shared_ptr<TransferMetadata> meta,
+                          std::shared_ptr<Topology> topo) {
+    (void)topo;
+    metadata_ = meta;
+    local_server_name_ = local_server_name;
+
+    auto old_desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    if (!desc) return ERR_MEMORY;
+    if (old_desc) *desc = *old_desc;
+
+    desc->name = local_server_name_;
+#ifdef ENABLE_MULTI_PROTOCOL
+    if (desc->protocol.empty()) {
+        desc->protocol = "shm";
+    } else if (!protocolListContains(desc->protocol, "shm")) {
+        desc->protocol += ",shm";
+    }
+#else
+    if (!desc->protocol.empty() && desc->protocol != "shm") {
+        LOG(WARNING) << "ShmTransport::install replaces segment protocol '"
+                     << desc->protocol
+                     << "' with 'shm'. Rebuild with "
+                        "-DENABLE_MULTI_PROTOCOL=ON to keep RDMA/TCP "
+                        "alongside SHM";
+    }
+    desc->protocol = "shm";
+#endif
+
+    metadata_->addLocalSegment(LOCAL_SEGMENT_ID, local_server_name_,
+                               std::move(desc));
+    return 0;
+}
+
+void* ShmTransport::createSharedMemory(const std::string& path, size_t size,
+                                       int* error, bool populate) {
+    auto fail = [&](int err) -> void* {
+        if (error) *error = err;
+        return nullptr;
+    };
+    auto unlink_created = [&]() {
+        if (isFilesystemShmPath(path)) {
+            unlink(path.c_str());
+        } else {
+            shm_unlink(path.c_str());
+        }
+    };
+
+    // O_EXCL prevents silently opening and truncating an existing object.
+    const bool hugetlbfs = isFilesystemShmPath(path);
+    int shm_fd = -1;
+    if (hugetlbfs) {
+        shm_fd = open(path.c_str(),
+                      O_CREAT | O_EXCL | O_RDWR | O_CLOEXEC | O_NOFOLLOW, 0600);
+    } else {
+        shm_fd = shm_open(path.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600);
+    }
+    if (shm_fd == -1) {
+        const int err = errno;
+        if (err != EEXIST) {
+            PLOG(ERROR) << "Failed to open shared memory file " << path;
+        }
+        return fail(err);
+    }
+
+    if (ftruncate(shm_fd, static_cast<off_t>(size)) == -1) {
+        const int err = errno;
+        PLOG(ERROR) << "Failed to truncate shared memory file " << path;
+        close(shm_fd);
+        unlink_created();
+        return fail(err);
+    }
+
+    int mmap_flags = MAP_SHARED;
+    if (populate) mmap_flags |= MAP_POPULATE;
+    void* mapped_addr =
+        mmap(nullptr, size, PROT_READ | PROT_WRITE, mmap_flags, shm_fd, 0);
+    if (mapped_addr == MAP_FAILED) {
+        const int err = errno;
+        PLOG(ERROR) << "Failed to map shared memory file " << path;
+        close(shm_fd);
+        unlink_created();
+        return fail(err);
+    }
+
+    close(shm_fd);
+    std::lock_guard<std::mutex> lock(shm_path_mutex_);
+    shm_path_map_[mapped_addr] = AllocatedShmEntry{path, size};
+    if (error) *error = 0;
+    return mapped_addr;
+}
+
+void* ShmTransport::allocateSharedMemory(size_t length) {
+    return allocateSharedMemory(length, SharedMemoryOptions{});
+}
+
+void* ShmTransport::allocateSharedMemory(size_t length,
+                                         const SharedMemoryOptions& opt) {
+    if (length == 0) {
+        LOG(ERROR) << "ShmTransport does not support zero-length allocation";
+        return nullptr;
+    }
+    std::string dir;
+    if (opt.use_hugepage) {
+        int error = 0;
+        if (!prepareHugetlbfsAllocate(opt, length, &dir, &error)) {
+            return nullptr;
+        }
+    }
+    for (int attempt = 0; attempt < kShmCreateMaxRetries; ++attempt) {
+        const std::string name = randomShmPath(dir);
+        int error = 0;
+        void* addr = createSharedMemory(name, length, &error,
+                                        opt.use_hugepage && opt.populate);
+        if (addr) return addr;
+        if (error != EEXIST) break;
+    }
+    LOG(ERROR) << "Failed to allocate "
+               << (opt.use_hugepage ? "hugetlbfs " : "")
+               << "shared memory of size " << length;
+    return nullptr;
+}
+
+int ShmTransport::freeSharedMemory(void* addr) {
+    std::lock_guard<std::mutex> lock(shm_path_mutex_);
+    auto it = shm_path_map_.find(addr);
+    if (it == shm_path_map_.end()) {
+        return ERR_INVALID_ARGUMENT;
+    }
+    munmap(addr, it->second.length);
+    unlinkShmEntry(it->second);
+    shm_path_map_.erase(it);
+    return 0;
+}
+
+bool ShmTransport::getShmName(void* addr, std::string* name) const {
+    if (!name) return false;
+    std::lock_guard<std::mutex> lock(shm_path_mutex_);
+    auto it = shm_path_map_.find(addr);
+    if (it == shm_path_map_.end()) return false;
+    *name = it->second.name;
+    return true;
+}
+
+int ShmTransport::registerLocalMemory(void* addr, size_t length,
+                                      const std::string& location,
+                                      bool remote_accessible,
+                                      bool update_metadata) {
+    (void)remote_accessible;
+    std::string shm_name;
+    size_t alloc_length = 0;
+    bool exact_base = false;
+    bool inside_or_overlapping = false;
+    {
+        std::lock_guard<std::mutex> lock(shm_path_mutex_);
+        auto it = shm_path_map_.find(addr);
+        if (it != shm_path_map_.end()) {
+            exact_base = true;
+            shm_name = it->second.name;
+            alloc_length = it->second.length;
+        } else {
+            const uint64_t range_addr = reinterpret_cast<uint64_t>(addr);
+            for (const auto& entry : shm_path_map_) {
+                const uint64_t base = reinterpret_cast<uint64_t>(entry.first);
+                if (rangeContains(base, entry.second.length, range_addr,
+                                  length) ||
+                    rangesOverlap(range_addr, length, base,
+                                  entry.second.length)) {
+                    inside_or_overlapping = true;
+                    break;
+                }
+            }
+        }
+    }
+    if (inside_or_overlapping) {
+        LOG(ERROR) << "registerLocalMemory must use the pointer returned by "
+                      "allocateSharedMemory, not a sub-range inside it: addr="
+                   << addr << " length=" << length;
+        return ERR_INVALID_ARGUMENT;
+    }
+    if (!exact_base) return 0;
+    if (length > alloc_length) {
+        LOG(ERROR) << "registerLocalMemory length " << length
+                   << " exceeds shm allocation " << alloc_length << " at "
+                   << addr;
+        return ERR_INVALID_ARGUMENT;
+    }
+
+    TransferMetadata::BufferDesc desc;
+    desc.addr = reinterpret_cast<uint64_t>(addr);
+    desc.length = length;
+    desc.name = location.empty() ? local_server_name_ : location;
+    desc.shm_name = shm_name;
+#ifdef ENABLE_MULTI_PROTOCOL
+    desc.protocol = "shm";
+#endif
+    return metadata_->addLocalMemoryBuffer(desc, update_metadata);
+}
+
+int ShmTransport::unregisterLocalMemory(void* addr, bool update_metadata) {
+    std::string shm_name;
+    if (!getShmName(addr, &shm_name)) return 0;
+    return metadata_->removeLocalMemoryBuffer(addr, update_metadata);
+}
+
+int ShmTransport::registerLocalMemoryBatch(
+    const std::vector<Transport::BufferEntry>& buffer_list,
+    const std::string& location) {
+    bool exported = false;
+    for (const auto& buffer : buffer_list) {
+        std::string name;
+        const bool owned = getShmName(buffer.addr, &name);
+        int ret = registerLocalMemory(buffer.addr, buffer.length, location,
+                                      true, false);
+        if (ret) return ret;
+        if (owned) exported = true;
+    }
+    if (!exported) return 0;
+    return metadata_->updateLocalSegmentDesc();
+}
+
+int ShmTransport::unregisterLocalMemoryBatch(
+    const std::vector<void*>& addr_list) {
+    int first_error = 0;
+    bool owned_any = false;
+    for (auto* addr : addr_list) {
+        std::string name;
+        if (getShmName(addr, &name)) owned_any = true;
+        int ret = unregisterLocalMemory(addr, false);
+        if (ret && !first_error) first_error = ret;
+    }
+    if (!owned_any) return first_error;
+    int metadata_ret = metadata_->updateLocalSegmentDesc();
+    return first_error ? first_error : metadata_ret;
+}
+
+bool ShmTransport::tryResolve(const RelocateMap& relocate_map,
+                              uint64_t& dest_addr, uint64_t length,
+                              const std::string& shm_name,
+                              std::shared_ptr<OpenedShmEntry>* out_entry) {
+    for (const auto& entry : relocate_map) {
+        if (!entry.second ||
+            entry.second->stale.load(std::memory_order_acquire))
+            continue;
+        if (entry.second->shm_name != shm_name) continue;
+        if (!entry.second->shm_addr) continue;
+        if (rangeContains(entry.first, entry.second->length, dest_addr,
+                          length)) {
+            dest_addr = dest_addr - entry.first +
+                        reinterpret_cast<uint64_t>(entry.second->shm_addr);
+            if (out_entry) *out_entry = entry.second;
+            return true;
+        }
+    }
+    return false;
+}
+
+void ShmTransport::queueUnmap(OpenedShmEntry& entry, PendingUnmap* pending) {
+    if (entry.pin_count.load(std::memory_order_acquire) > 0) {
+        entry.stale.store(true, std::memory_order_release);
+        return;
+    }
+    if (!pending) return;
+    if (entry.shm_addr && entry.length) {
+        pending->emplace_back(entry.shm_addr, entry.length);
+    }
+    entry.shm_addr = nullptr;
+    entry.length = 0;
+    entry.stale.store(true, std::memory_order_release);
+}
+
+void ShmTransport::unpinLocked(OpenedShmEntry& entry, PendingUnmap* pending) {
+    const uint32_t prev =
+        entry.pin_count.fetch_sub(1, std::memory_order_acq_rel);
+    if (prev == 1 && entry.stale.load(std::memory_order_acquire) &&
+        entry.shm_addr && entry.length) {
+        if (pending) pending->emplace_back(entry.shm_addr, entry.length);
+        entry.shm_addr = nullptr;
+        entry.length = 0;
+    }
+}
+
+void ShmTransport::flushUnmaps(PendingUnmap& pending) {
+    for (auto& entry : pending) {
+        if (entry.first && entry.second) munmap(entry.first, entry.second);
+    }
+    pending.clear();
+}
+
+void ShmTransport::pruneAndCapLocked(RelocateMap& mappings,
+                                     const TransferMetadata::SegmentDesc& desc,
+                                     uint64_t keep_addr,
+                                     PendingUnmap* pending) {
+    for (auto it = mappings.begin(); it != mappings.end();) {
+        if (it->first != keep_addr &&
+            (!it->second || !posixBufferAddrListed(desc, it->first))) {
+            if (it->second) queueUnmap(*it->second, pending);
+            it = mappings.erase(it);
+        } else {
+            ++it;
+        }
+    }
+    while (mappings.size() > kMaxMappingsPerTarget) {
+        auto victim = mappings.end();
+        for (auto it = mappings.begin(); it != mappings.end(); ++it) {
+            if (it->first == keep_addr || !it->second) continue;
+            if (it->second->pin_count.load(std::memory_order_acquire) == 0) {
+                victim = it;
+                break;
+            }
+        }
+        if (victim == mappings.end()) {
+            for (auto it = mappings.begin(); it != mappings.end(); ++it) {
+                if (it->first == keep_addr) continue;
+                victim = it;
+                break;
+            }
+        }
+        if (victim == mappings.end()) break;
+        if (victim->second) queueUnmap(*victim->second, pending);
+        mappings.erase(victim);
+    }
+}
+
+void ShmTransport::pruneIfNeeded(SegmentID target_id,
+                                 const TransferMetadata::SegmentDesc& desc,
+                                 uint64_t keep_addr) {
+    const size_t live = posixBufferCount(desc);
+    bool need = false;
+    {
+        RWSpinlock::ReadGuard guard(relocate_lock_);
+        auto target = relocate_map_.find(target_id);
+        if (target == relocate_map_.end()) return;
+        need = target->second.size() > live ||
+               target->second.size() > kMaxMappingsPerTarget;
+    }
+    if (!need) return;
+    PendingUnmap pending;
+    {
+        RWSpinlock::WriteGuard guard(relocate_lock_);
+        auto target = relocate_map_.find(target_id);
+        if (target != relocate_map_.end()) {
+            pruneAndCapLocked(target->second, desc, keep_addr, &pending);
+        }
+    }
+    flushUnmaps(pending);
+}
+
+ShmTransport::MappingPin::MappingPin(ShmTransport* transport,
+                                     std::shared_ptr<OpenedShmEntry> entry)
+    : transport_(transport), entry_(std::move(entry)) {}
+
+ShmTransport::MappingPin::MappingPin(MappingPin&& other) noexcept
+    : transport_(other.transport_), entry_(std::move(other.entry_)) {
+    other.transport_ = nullptr;
+}
+
+ShmTransport::MappingPin& ShmTransport::MappingPin::operator=(
+    MappingPin&& other) noexcept {
+    if (this != &other) {
+        reset();
+        transport_ = other.transport_;
+        entry_ = std::move(other.entry_);
+        other.transport_ = nullptr;
+    }
+    return *this;
+}
+
+ShmTransport::MappingPin::~MappingPin() { reset(); }
+
+void ShmTransport::MappingPin::reset() {
+    if (!transport_ || !entry_) {
+        transport_ = nullptr;
+        entry_.reset();
+        return;
+    }
+    PendingUnmap pending;
+    {
+        RWSpinlock::WriteGuard guard(transport_->relocate_lock_);
+        unpinLocked(*entry_, &pending);
+    }
+    flushUnmaps(pending);
+    transport_ = nullptr;
+    entry_.reset();
+}
+
+void ShmTransport::adoptPin(std::shared_ptr<OpenedShmEntry> entry,
+                            MappingPin* pin) {
+    if (!pin || !entry) return;
+    *pin = MappingPin(this, std::move(entry));
+}
+
+Status ShmTransport::relocateSharedMemoryAddress(uint64_t& dest_addr,
+                                                 uint64_t length,
+                                                 uint64_t target_id,
+                                                 MappingPin* pin) {
+    if (pin) pin->reset();
+    if (!metadata_) {
+        return Status::InvalidArgument("SHM transport is not installed");
+    }
+    const uint64_t requested_addr = dest_addr;
+    auto attempt = [&](bool force_update) -> Status {
+        dest_addr = requested_addr;
+        auto desc = metadata_->getSegmentDescByID(target_id, force_update);
+        if (!desc) {
+            return Status::AddressNotRegistered("Invalid target segment ID");
+        }
+
+        const BufferDesc* buffer = nullptr;
+        for (const auto& entry : desc->buffers) {
+            if (!isPosixShmName(entry.shm_name)) continue;
+            if (rangeContains(entry.addr, entry.length, dest_addr, length)) {
+                buffer = &entry;
+                break;
+            }
+        }
+        if (!buffer) {
+            return Status::AddressNotRegistered(
+                "Requested address is not in a POSIX shm buffer");
+        }
+
+        std::shared_ptr<OpenedShmEntry> hit;
+        {
+            RWSpinlock::ReadGuard guard(relocate_lock_);
+            auto target = relocate_map_.find(target_id);
+            uint64_t candidate = requested_addr;
+            if (target == relocate_map_.end() ||
+                !tryResolve(target->second, candidate, length, buffer->shm_name,
+                            &hit) ||
+                !hit) {
+                hit.reset();
+            }
+        }
+        if (hit && pin) {
+            bool pinned = false;
+            {
+                RWSpinlock::WriteGuard guard(relocate_lock_);
+                if (!hit->stale.load(std::memory_order_acquire) &&
+                    hit->shm_addr) {
+                    hit->pin_count.fetch_add(1, std::memory_order_acq_rel);
+                    pinned = true;
+                }
+            }
+            if (!pinned) hit.reset();
+        }
+        if (hit) {
+            // Cached mmap stays valid after shm_unlink. Probe the name so a
+            // peer free+realloc cannot silently write into the orphaned object.
+            if (shmObjectExists(buffer->shm_name)) {
+                dest_addr = requested_addr - buffer->addr +
+                            reinterpret_cast<uint64_t>(hit->shm_addr);
+                adoptPin(hit, pin);
+                pruneIfNeeded(target_id, *desc, buffer->addr);
+                return Status::OK();
+            }
+            if (pin) {
+                PendingUnmap drop;
+                {
+                    RWSpinlock::WriteGuard guard(relocate_lock_);
+                    unpinLocked(*hit, &drop);
+                }
+                flushUnmaps(drop);
+            }
+        }
+
+        PendingUnmap pending;
+        std::shared_ptr<OpenedShmEntry> reused;
+        {
+            RWSpinlock::WriteGuard guard(relocate_lock_);
+            RelocateMap& mappings = relocate_map_[target_id];
+            pruneAndCapLocked(mappings, *desc, buffer->addr, &pending);
+            auto mapping = mappings.find(buffer->addr);
+            if (mapping != mappings.end() && mapping->second &&
+                mapping->second->shm_name == buffer->shm_name &&
+                mapping->second->shm_addr) {
+                reused = mapping->second;
+                if (pin)
+                    reused->pin_count.fetch_add(1, std::memory_order_acq_rel);
+            } else if (mapping != mappings.end()) {
+                if (mapping->second) queueUnmap(*mapping->second, &pending);
+                mappings.erase(mapping);
+            }
+        }
+        flushUnmaps(pending);
+
+        if (reused && shmObjectExists(buffer->shm_name)) {
+            dest_addr = requested_addr - buffer->addr +
+                        reinterpret_cast<uint64_t>(reused->shm_addr);
+            adoptPin(reused, pin);
+            return Status::OK();
+        }
+        if (reused) {
+            {
+                RWSpinlock::WriteGuard guard(relocate_lock_);
+                if (pin) unpinLocked(*reused, &pending);
+                auto target = relocate_map_.find(target_id);
+                if (target != relocate_map_.end()) {
+                    auto mapping = target->second.find(buffer->addr);
+                    if (mapping != target->second.end() && mapping->second &&
+                        mapping->second->shm_name == buffer->shm_name) {
+                        queueUnmap(*mapping->second, &pending);
+                        target->second.erase(mapping);
+                    }
+                }
+            }
+            flushUnmaps(pending);
+        }
+
+        void* shm_addr = nullptr;
+        uint64_t mapped_length = 0;
+        Status mapped = mapSharedMemory(buffer->shm_name, buffer->length,
+                                        &shm_addr, &mapped_length);
+        if (!mapped.ok()) return mapped;
+        LOG(INFO) << "Original shared memory: " << (void*)buffer->addr << "--"
+                  << (void*)(buffer->addr + buffer->length);
+        LOG(INFO) << "Remapped shared memory: " << shm_addr << "--"
+                  << (void*)((uintptr_t)shm_addr + mapped_length);
+
+        std::shared_ptr<OpenedShmEntry> installed;
+        {
+            RWSpinlock::WriteGuard guard(relocate_lock_);
+            RelocateMap& mappings = relocate_map_[target_id];
+            auto mapping = mappings.find(buffer->addr);
+            if (mapping != mappings.end() && mapping->second &&
+                mapping->second->shm_name == buffer->shm_name &&
+                mapping->second->shm_addr) {
+                pending.emplace_back(shm_addr, mapped_length);
+                shm_addr = mapping->second->shm_addr;
+                installed = mapping->second;
+            } else {
+                if (mapping != mappings.end()) {
+                    if (mapping->second) queueUnmap(*mapping->second, &pending);
+                    mappings.erase(mapping);
+                }
+                installed = std::make_shared<OpenedShmEntry>();
+                installed->shm_addr = shm_addr;
+                installed->length = mapped_length;
+                installed->shm_name = buffer->shm_name;
+                mappings[buffer->addr] = installed;
+            }
+            if (pin && installed)
+                installed->pin_count.fetch_add(1, std::memory_order_acq_rel);
+            pruneAndCapLocked(mappings, *desc, buffer->addr, &pending);
+        }
+        flushUnmaps(pending);
+
+        dest_addr = requested_addr - buffer->addr +
+                    reinterpret_cast<uint64_t>(shm_addr);
+        adoptPin(installed, pin);
+        return Status::OK();
+    };
+
+    Status status = attempt(false);
+    if (status.ok() || !status.IsMemory()) return status;
+    if (pin) pin->reset();
+    // The cached segment desc still named an object that is gone (peer
+    // free/realloc). Refetch once so the same virtual address can remap.
+    return attempt(true);
+}
+
+Status ShmTransport::copySlice(TransferTask& task,
+                               const TransferRequest& request,
+                               uint64_t dest_addr) {
+    task.total_bytes = request.length;
+    Slice* slice = getSliceCache().allocate();
+    slice->source_addr = (char*)request.source;
+    slice->local.dest_addr = (char*)dest_addr;
+    slice->length = request.length;
+    slice->opcode = request.opcode;
+    slice->task = &task;
+    slice->target_id = request.target_id;
+    slice->status = Slice::PENDING;
+    task.slice_list.push_back(slice);
+    __sync_fetch_and_add(&task.slice_count, 1);
+
+    if (!slice->source_addr || !slice->local.dest_addr) {
+        slice->markFailed();
+        return Status::InvalidArgument("SHM copy with null pointer");
+    }
+
+    void* src = (request.opcode == TransferRequest::READ)
+                    ? (void*)slice->local.dest_addr
+                    : slice->source_addr;
+    void* dst = (request.opcode == TransferRequest::READ)
+                    ? slice->source_addr
+                    : (void*)slice->local.dest_addr;
+    std::memcpy(dst, src, slice->length);
+    slice->markSuccess();
+    return Status::OK();
+}
+
+void ShmTransport::failSlice(TransferTask& task,
+                             const TransferRequest& request) {
+    Slice* slice = getSliceCache().allocate();
+    slice->source_addr = (char*)request.source;
+    slice->local.dest_addr = nullptr;
+    slice->length = request.length;
+    slice->opcode = request.opcode;
+    slice->task = &task;
+    slice->target_id = request.target_id;
+    slice->status = Slice::PENDING;
+    task.slice_list.push_back(slice);
+    __sync_fetch_and_add(&task.slice_count, 1);
+    slice->markFailed();
+}
+
+Status ShmTransport::submitTransfer(
+    BatchID batch_id, const std::vector<TransferRequest>& entries) {
+    auto& batch_desc = *((BatchDesc*)(batch_id));
+    if (batch_desc.task_list.size() + entries.size() > batch_desc.batch_size) {
+        return Status::InvalidArgument(
+            "ShmTransport: Exceed the limitation of capacity");
+    }
+
+    std::vector<uint64_t> dest_addrs;
+    dest_addrs.reserve(entries.size());
+    std::vector<MappingPin> pins(entries.size());
+    for (size_t i = 0; i < entries.size(); ++i) {
+        const auto& request = entries[i];
+        uint64_t dest_addr = request.target_offset;
+        if (request.target_id != LOCAL_SEGMENT_ID) {
+            Status status = relocateSharedMemoryAddress(
+                dest_addr, request.length, request.target_id, &pins[i]);
+            if (!status.ok()) return status;
+        }
+        dest_addrs.push_back(dest_addr);
+    }
+
+    size_t task_id = batch_desc.task_list.size();
+    batch_desc.task_list.resize(task_id + entries.size());
+    for (size_t i = 0; i < entries.size(); ++i) {
+        TransferTask& task = batch_desc.task_list[task_id++];
+        task.batch_id = batch_id;
+        Status status = copySlice(task, entries[i], dest_addrs[i]);
+        if (!status.ok()) return status;
+    }
+    return Status::OK();
+}
+
+Status ShmTransport::submitTransferTask(
+    const std::vector<TransferTask*>& task_list) {
+    std::vector<uint64_t> dest_addrs;
+    dest_addrs.reserve(task_list.size());
+    std::vector<MappingPin> pins(task_list.size());
+    Status first_error = Status::OK();
+    for (size_t i = 0; i < task_list.size(); ++i) {
+        auto* task = task_list[i];
+        assert(task);
+        assert(task->request);
+        const auto& request = *task->request;
+        uint64_t dest_addr = request.target_offset;
+        if (request.target_id != LOCAL_SEGMENT_ID) {
+            Status status = relocateSharedMemoryAddress(
+                dest_addr, request.length, request.target_id, &pins[i]);
+            if (!status.ok()) {
+                if (first_error.ok()) first_error = status;
+                dest_addrs.push_back(0);
+                continue;
+            }
+        }
+        dest_addrs.push_back(dest_addr);
+    }
+
+    if (!first_error.ok()) {
+        for (auto* task : task_list) failSlice(*task, *task->request);
+        return first_error;
+    }
+
+    for (size_t i = 0; i < task_list.size(); ++i) {
+        Status status =
+            copySlice(*task_list[i], *task_list[i]->request, dest_addrs[i]);
+        if (!status.ok()) return status;
+    }
+    return Status::OK();
+}
+
+Status ShmTransport::getTransferStatus(BatchID batch_id, size_t task_id,
+                                       TransferStatus& status) {
+    auto& batch_desc = *((BatchDesc*)(batch_id));
+    const size_t task_count = batch_desc.task_list.size();
+    if (task_id >= task_count) {
+        return Status::InvalidArgument(
+            "ShmTransport::getTransferStatus invalid argument, batch id: " +
+            std::to_string(batch_id));
+    }
+    auto& task = batch_desc.task_list[task_id];
+    status.transferred_bytes = task.transferred_bytes;
+    uint64_t success_slice_count = task.success_slice_count;
+    uint64_t failed_slice_count = task.failed_slice_count;
+    if (success_slice_count + failed_slice_count == task.slice_count) {
+        if (failed_slice_count) {
+            status.s = TransferStatusEnum::FAILED;
+        } else {
+            status.s = TransferStatusEnum::COMPLETED;
+        }
+        task.is_finished = true;
+    } else {
+        status.s = TransferStatusEnum::WAITING;
+    }
+    return Status::OK();
+}
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/src/transport/sunrise_link/sunrise_link_transport.cpp b/mooncake-transfer-engine/src/transport/sunrise_link/sunrise_link_transport.cpp
index ebf3f654b7..602e114b2a 100644
--- a/mooncake-transfer-engine/src/transport/sunrise_link/sunrise_link_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/sunrise_link/sunrise_link_transport.cpp
@@ -748,9 +748,13 @@ Status SunriseLinkTransport::getTransferStatus(BatchID batch_id, size_t task_id,
     }
 
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Completion counters publish the preceding byte updates.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         status.s = failed_slice_count ? TransferStatusEnum::FAILED
                                       : TransferStatusEnum::COMPLETED;
diff --git a/mooncake-transfer-engine/src/transport/tcp_transport/CMakeLists.txt b/mooncake-transfer-engine/src/transport/tcp_transport/CMakeLists.txt
index f2c21ea006..8345b000f5 100644
--- a/mooncake-transfer-engine/src/transport/tcp_transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/transport/tcp_transport/CMakeLists.txt
@@ -1,8 +1,18 @@
 file(GLOB TCP_SOURCES "*.cpp")
+file(GLOB TCP_IMPL_HEADERS "*_impl.h")
 
 if (USE_HIP)
+  list(APPEND TCP_SOURCES ${TCP_IMPL_HEADERS})
   hipify_files(TCP_SOURCES)
 endif()
 
 add_library(tcp_transport OBJECT ${TCP_SOURCES})
-target_link_libraries(tcp_transport PRIVATE JsonCpp::JsonCpp yalantinglibs::yalantinglibs)
+target_link_libraries(
+  tcp_transport
+  PUBLIC asio_shared JsonCpp::JsonCpp yalantinglibs::yalantinglibs
+  PRIVATE glog::glog)
+
+if(BUILD_UNIT_TESTS)
+  target_compile_definitions(tcp_transport
+                             PRIVATE MOONCAKE_TCP_TRANSPORT_TEST_HOOKS)
+endif()
diff --git a/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport.cpp b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport.cpp
index c2aa41bbcd..11953cdd79 100644
--- a/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport.cpp
+++ b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport.cpp
@@ -17,18 +17,27 @@
 #include <bits/stdint-uintn.h>
 #include <glog/logging.h>
 #include <asio/ip/v6_only.hpp>
+#include <asio/post.hpp>
 #include <asio/steady_timer.hpp>
 
 #include <algorithm>
+#include <array>
+#include <atomic>
 #include <cassert>
 #include <cctype>
 #include <chrono>
+#include <condition_variable>
 #include <cstddef>
 #include <cstdint>
 #include <cstdlib>
+#include <deque>
+#include <functional>
+#include <limits>
 #include <memory>
+#include <mutex>
 #include <optional>
-#include <random>
+#include <type_traits>
+#include <vector>
 
 #include "common.h"
 #include "transfer_engine.h"
@@ -40,807 +49,274 @@
 
 namespace mooncake {
 using tcpsocket = asio::ip::tcp::socket;
-static size_t getChunkSize() {
-    static const size_t val = [] {
-        const char* env = std::getenv("MC_TCP_SLICE_SIZE");
-        if (env) {
-            try {
-                size_t v = std::stoull(env);
-                if (v > 0) return v;
-                LOG(WARNING)
-                    << "Ignore non-positive MC_TCP_SLICE_SIZE value: " << env
-                    << ", using default 65536";
-            } catch (const std::exception& e) {
-                // A non-numeric or out-of-range value makes std::stoull throw;
-                // fall through to the default instead of letting the exception
-                // propagate out of this static initializer and abort the
-                // transfer that first reads the chunk size.
-                LOG(WARNING)
-                    << "Invalid MC_TCP_SLICE_SIZE value: " << env
-                    << ". Error: " << e.what() << ", using default 65536";
-            }
-        }
-        return size_t(65536);  // 64KB default
-    }();
-    return val;
-}
 
-struct SessionHeader {
-    uint64_t size;
-    uint64_t addr;
-    uint8_t opcode;
-};
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+namespace {
+using LaneConnectHandlerHook = void (*)() noexcept;
+using LaneConnectFailureInjectionHook = bool (*)(size_t) noexcept;
+using LaneRetryHandlerHook = void (*)() noexcept;
+using LaneAdmissionHandlerHook = void (*)() noexcept;
+using LaneObserverHook = void (*)(int, size_t, uint64_t, size_t, bool) noexcept;
+using LaneFailureReasonHook = void (*)(int) noexcept;
+using SessionProgressHook = int (*)(int, bool) noexcept;
+using StartTransferMetadataHook = void (*)() noexcept;
+
+std::mutex lane_test_hook_mutex;
+LaneConnectHandlerHook lane_connect_handler_hook = nullptr;
+LaneConnectFailureInjectionHook lane_connect_failure_injection_hook = nullptr;
+LaneRetryHandlerHook lane_retry_handler_hook = nullptr;
+LaneAdmissionHandlerHook lane_admission_handler_hook = nullptr;
+LaneObserverHook lane_observer_hook = nullptr;
+LaneFailureReasonHook lane_failure_reason_hook = nullptr;
+SessionProgressHook session_progress_hook = nullptr;
+StartTransferMetadataHook start_transfer_metadata_hook = nullptr;
+std::atomic<size_t> staging_buffer_allocation_count{0};
+std::atomic<size_t> staging_device_query_count{0};
 
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
     defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
     defined(USE_COREX)
-static bool isCudaMemory(void* addr) {
-    cudaPointerAttributes attributes;
-    auto status = cudaPointerGetAttributes(&attributes, addr);
-    if (status != cudaSuccess) return false;
-    return attributes.type == cudaMemoryTypeDevice;
+void recordStagingBufferAllocationForTest() noexcept {
+    staging_buffer_allocation_count.fetch_add(1, std::memory_order_relaxed);
 }
 
-// Returns the CUDA device ordinal if addr is device memory, or -1 otherwise.
-// Callers must call cudaSetDevice before any cudaMemcpy to avoid implicit
-// GPU 0 context creation.
-static int getCudaDeviceId(void* addr) {
-    cudaPointerAttributes attributes;
-    auto status = cudaPointerGetAttributes(&attributes, addr);
-    if (status != cudaSuccess) return -1;
-    if (attributes.type == cudaMemoryTypeDevice) return attributes.device;
-    return -1;
+void recordStagingDeviceQueryForTest() noexcept {
+    staging_device_query_count.fetch_add(1, std::memory_order_relaxed);
 }
+#endif
 
-#ifdef USE_MACA
-static cudaError_t copyTcpCudaMemory(void* dst, const void* src, size_t size) {
-    cudaStream_t stream;
-    cudaError_t status =
-        cudaStreamCreateWithFlags(&stream, cudaStreamNonBlocking);
-    if (status != cudaSuccess) return status;
+enum LaneTestEvent {
+    kLaneQueueAdmitted = 1,
+    kLaneQueueRejected = 2,
+    kLaneConnecting = 3,
+    kLaneBusy = 4,
+    kLaneTerminal = 5,
+    kLaneShutdownClean = 6,
+    kLaneLateHandler = 7,
+    kLaneRetryArmed = 8,
+    kLaneRetryFired = 9,
+    kLaneRetryLate = 10,
+    kLaneCooldownStarted = 11,
+    kLaneAdmissionPending = 12,
+    kLaneAdmissionPromoted = 13,
+    kLaneAdmissionTimerArmed = 14,
+    kLaneAdmissionTimerFired = 15,
+    kLaneAdmissionTimerLate = 16,
+    kLaneAdmissionHardRejected = 17,
+};
 
-    status = cudaMemcpyAsync(dst, src, size, cudaMemcpyDefault, stream);
-    if (status == cudaSuccess) {
-        status = cudaStreamSynchronize(stream);
-    }
+enum SessionProgressTestEvent {
+    kSessionReadBodySuccess = 1,
+    kSessionWriteAckSuccess = 2,
+    kSessionTimeoutCommitted = 3,
+    kSessionTimeoutStale = 4,
+    kSessionTerminal = 5,
+};
 
-    cudaError_t destroy_status = cudaStreamDestroy(stream);
-    return status == cudaSuccess ? destroy_status : status;
-}
-#endif
-#endif
+enum SessionProgressTestAction {
+    kSessionProgressNoAction = 0,
+    kSessionCommitTimeoutBeforeProgress = 1,
+    kSessionReplayPreviousTimeoutAfterProgress = 2,
+};
 
-// Forward declaration
-class TcpTransport;
-
-using ValidateAddrFn = std::function<bool(uint64_t, uint64_t)>;
-
-// --- Acknowledged framing (protocol v2, #2086) ------------------------------
-// v1 framing gives the initiator no channel to learn whether the receiver
-// applied (or even accepted) a WRITE: COMPLETED fires when the final chunk
-// enters the initiator's kernel socket buffer, while megabytes may still be
-// in flight toward destination memory, and a rejected request is silently
-// "successful". v2 requests set the high bit of the opcode; the server then
-// (a) prefixes every READ response with an 8-byte status frame and (b) sends
-// an 8-byte status frame for WRITE only after the final chunk has been
-// applied to destination memory. Initiators enable v2 only when the target
-// segment advertises tcp_proto_version >= 2, so old servers never see
-// flagged opcodes and old initiators keep receiving v1 framing.
-static constexpr uint8_t kOpcodeV2Flag = 0x80;
-// Status frames carry a magic in the high 32 bits so that a v2 initiator
-// which reaches a v1 server through a stale descriptor (v1 treats unknown
-// opcodes as READ and immediately streams payload bytes) fails fast on the
-// first frame instead of misinterpreting the stream. Residual risk: payload
-// bytes that happen to equal a valid frame (2^-64 per request, data
-// dependent) are indistinguishable in-band; eliminating that would need a
-// nonce/checksum handshake, which this deliberately avoids.
-static constexpr uint64_t kStatusMagic = 0x4D435456ull << 32;  // "MCTV"
-static constexpr uint64_t kStatusOk = kStatusMagic | 0;
-static constexpr uint64_t kStatusAddrRejected = kStatusMagic | 1;
-static inline bool statusFrameValid(uint64_t frame) {
-    return (frame & 0xFFFFFFFF00000000ull) == kStatusMagic;
+void invokeLaneConnectHandlerHook() noexcept {
+    LaneConnectHandlerHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_connect_handler_hook;
+    }
+    if (hook) hook();
 }
 
-// Operational escape hatch: MC_TCP_PROTO=1 forces initiators to speak the
-// legacy unacknowledged framing even to v2-capable servers. Also used by
-// tests to cover the mixed-version matrix in one process.
-static bool forceLegacyTcpProto() {
-    // Read per call (startTransfer already does metadata lookups; getenv is
-    // noise) so tests can cover both protocol modes in one process.
-    const char* env = std::getenv("MC_TCP_PROTO");
-    return env && env[0] == '1' && env[1] == '\0';
+bool invokeLaneConnectFailureInjectionHook(size_t lane_id) noexcept {
+    LaneConnectFailureInjectionHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_connect_failure_injection_hook;
+    }
+    return hook && hook(lane_id);
 }
 
-// Server-side session: handles transfer requests on a persistent connection.
-// The session owns the socket; ending the callback chain without rearming
-// (start()/next handler) drops the last reference and closes the connection.
-struct ServerSession : public std::enable_shared_from_this<ServerSession> {
-    explicit ServerSession(std::shared_ptr<tcpsocket> socket,
-                           ValidateAddrFn validate_addr)
-        : socket_(std::move(socket)),
-          validate_addr_(std::move(validate_addr)) {}
-
-    std::shared_ptr<tcpsocket> socket_;
-    ValidateAddrFn validate_addr_;
-    SessionHeader header_;
-    uint64_t total_transferred_bytes_;
-    char* local_buffer_;
-    bool v2_ = false;
-    uint64_t status_frame_;
-
-    void start() {
-        total_transferred_bytes_ = 0;
-        readHeader();
+void invokeLaneRetryHandlerHook() noexcept {
+    LaneRetryHandlerHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_retry_handler_hook;
     }
+    if (hook) hook();
+}
 
-   private:
-    // Send an 8-byte status frame, then run `next` (or end the session —
-    // closing the connection — when `next` is empty or the send fails).
-    void sendStatus(uint64_t status, std::function<void()> next) {
-        status_frame_ = htole64(status);
-        auto self(shared_from_this());
-        asio::async_write(*socket_,
-                          asio::buffer(&status_frame_, sizeof(status_frame_)),
-                          [this, self, next = std::move(next)](
-                              const asio::error_code& ec, std::size_t) {
-                              if (ec)
-                                  return;  // connection closes with the session
-                              if (next) next();
-                          });
+void invokeLaneAdmissionHandlerHook() noexcept {
+    LaneAdmissionHandlerHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_admission_handler_hook;
     }
+    if (hook) hook();
+}
 
-    void readHeader() {
-        auto self(shared_from_this());
-        asio::async_read(
-            *socket_, asio::buffer(&header_, sizeof(SessionHeader)),
-            [this, self](const asio::error_code& ec, std::size_t len) {
-                if (ec || len != sizeof(SessionHeader)) {
-                    if (ec.value() != asio::error::eof) {
-                        LOG(WARNING)
-                            << "ServerSession::readHeader failed. Error: "
-                            << ec.message() << " (value: " << ec.value() << ")"
-                            << ", bytes read: " << len;
-                    }
-                    return;
-                }
-
-                v2_ = (header_.opcode & kOpcodeV2Flag) != 0;
-                const uint8_t opcode = header_.opcode & ~kOpcodeV2Flag;
-                local_buffer_ = (char*)(le64toh(header_.addr));
-                uint64_t size = le64toh(header_.size);
-                if (validate_addr_ &&
-                    !validate_addr_((uint64_t)local_buffer_, size)) {
-                    LOG(ERROR) << "ServerSession: remote-supplied address 0x"
-                               << std::hex << (uint64_t)local_buffer_
-                               << std::dec << " with size " << size
-                               << " is not within any registered buffer";
-                    // v2 initiators learn of the rejection; v1 initiators
-                    // only see the connection close (and, for small WRITEs,
-                    // may have already reported success — the defect v2
-                    // exists to fix).
-                    if (v2_) sendStatus(kStatusAddrRejected, nullptr);
-                    return;
-                }
-                if (opcode == (uint8_t)TransferRequest::WRITE) {
-                    readBody();
-                } else if (v2_) {
-                    // READ, v2: status frame precedes the data.
-                    sendStatus(kStatusOk, [this] { writeBody(); });
-                } else {
-                    writeBody();
-                }
-            });
+void invokeLaneObserverHook(int event, size_t queue_depth,
+                            uint64_t queued_bytes, size_t active_sockets,
+                            bool lane_has_current) noexcept {
+    LaneObserverHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_observer_hook;
     }
+    if (hook)
+        hook(event, queue_depth, queued_bytes, active_sockets,
+             lane_has_current);
+}
 
-    void writeBody() {
-        auto self(shared_from_this());
-        uint64_t size = le64toh(header_.size);
-        char* addr = local_buffer_;
-
-        size_t buffer_size =
-            std::min(getChunkSize(), size - total_transferred_bytes_);
-        if (buffer_size == 0) {
-            // Transfer complete, wait for next request on this connection
-            start();
-            return;
-        }
-
-        char* dram_buffer = addr + total_transferred_bytes_;
-        int cuda_device = -1;
-
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-        cuda_device = getCudaDeviceId(addr);
-        if (cuda_device >= 0) {
-            dram_buffer = new char[buffer_size];
-            cudaSetDevice(cuda_device);
-#ifdef USE_MACA
-            cudaError_t cuda_status = copyTcpCudaMemory(
-                dram_buffer, addr + total_transferred_bytes_, buffer_size);
-#else
-            cudaError_t cuda_status =
-                cudaMemcpy(dram_buffer, addr + total_transferred_bytes_,
-                           buffer_size, cudaMemcpyDefault);
-#endif
-            if (cuda_status != cudaSuccess) {
-                LOG(ERROR) << "ServerSession::writeBody failed to copy from "
-                              "CUDA memory. "
-                           << "Error: " << cudaGetErrorString(cuda_status);
-                delete[] dram_buffer;
-                return;  // Connection will be closed
-            }
-        }
-#endif
-
-        asio::async_write(
-            *socket_, asio::buffer(dram_buffer, buffer_size),
-            [this, addr, dram_buffer, cuda_device, self](
-                const asio::error_code& ec, std::size_t transferred_bytes) {
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-                if (cuda_device >= 0) {
-                    delete[] dram_buffer;
-                }
-#endif
-                if (ec) {
-                    LOG(ERROR)
-                        << "ServerSession::writeBody failed. "
-                        << "Attempt to write data " << static_cast<void*>(addr)
-                        << " using buffer " << static_cast<void*>(dram_buffer)
-                        << ". Error: " << ec.message()
-                        << " (value: " << ec.value() << ")";
-                    return;  // Connection will be closed
-                }
-                total_transferred_bytes_ += transferred_bytes;
-                writeBody();
-            });
+void invokeLaneFailureReasonHook(int reason) noexcept {
+    LaneFailureReasonHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = lane_failure_reason_hook;
     }
+    if (hook) hook(reason);
+}
 
-    void readBody() {
-        auto self(shared_from_this());
-        uint64_t size = le64toh(header_.size);
-        char* addr = local_buffer_;
-
-        size_t buffer_size =
-            std::min(getChunkSize(), size - total_transferred_bytes_);
-        if (buffer_size == 0) {
-            // Destination memory now holds the complete payload. Under v2,
-            // acknowledge before accepting the next request — this is what
-            // makes the initiator's COMPLETED mean "applied at the
-            // destination" rather than "left my socket buffer".
-            if (v2_) {
-                sendStatus(kStatusOk, [this] { start(); });
-            } else {
-                start();
-            }
-            return;
-        }
-
-        char* dram_buffer = addr + total_transferred_bytes_;
-        int cuda_device = -1;
-
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-        cuda_device = getCudaDeviceId(addr);
-        if (cuda_device >= 0) {
-            dram_buffer = new char[buffer_size];
-        }
-#endif
-
-        asio::async_read(
-            *socket_, asio::buffer(dram_buffer, buffer_size),
-            [this, addr, dram_buffer, cuda_device, self](
-                const asio::error_code& ec, std::size_t transferred_bytes) {
-                if (ec) {
-                    // If client closed connection (EOF), this is normal - don't
-                    // log
-                    if (ec.value() != asio::error::eof) {
-                        LOG(WARNING)
-                            << "ServerSession::readBody failed. "
-                            << "Attempt to read data "
-                            << static_cast<void*>(addr) << " using buffer "
-                            << static_cast<void*>(dram_buffer)
-                            << ". Error: " << ec.message()
-                            << " (value: " << ec.value() << ")";
-                    }
-                    if (cuda_device >= 0) delete[] dram_buffer;
-                    return;  // Connection will be closed
-                }
-
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-                if (cuda_device >= 0) {
-                    cudaSetDevice(cuda_device);
-#ifdef USE_MACA
-                    cudaError_t cuda_status =
-                        copyTcpCudaMemory(addr + total_transferred_bytes_,
-                                          dram_buffer, transferred_bytes);
-#else
-                    cudaError_t cuda_status =
-                        cudaMemcpy(addr + total_transferred_bytes_, dram_buffer,
-                                   transferred_bytes, cudaMemcpyDefault);
-#endif
-                    if (cuda_status != cudaSuccess) {
-                        LOG(ERROR)
-                            << "ServerSession::readBody failed to copy to CUDA "
-                               "memory. "
-                            << "Error: " << cudaGetErrorString(cuda_status);
-                        delete[] dram_buffer;
-                        return;  // Connection will be closed
-                    }
-                    delete[] dram_buffer;
-                }
-#endif
-                total_transferred_bytes_ += transferred_bytes;
-                readBody();
-            });
+int invokeSessionProgressHook(int event, bool detail) noexcept {
+    SessionProgressHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = session_progress_hook;
     }
-};
+    return hook ? hook(event, detail) : kSessionProgressNoAction;
+}
 
-// Client-side session: initiates one transfer request
-struct ClientSession : public std::enable_shared_from_this<ClientSession> {
-    explicit ClientSession(std::shared_ptr<tcpsocket> socket, bool use_v2,
-                           std::function<void(bool)> on_complete = nullptr)
-        : socket_(std::move(socket)),
-          v2_(use_v2),
-          on_complete_(std::move(on_complete)) {}
-
-    std::shared_ptr<tcpsocket> socket_;
-    SessionHeader header_;
-    uint64_t total_transferred_bytes_;
-    char* local_buffer_;
-    bool v2_;
-    uint64_t status_frame_;
-    // v2 WRITE runs the body stream and the ack read concurrently (one
-    // async op per direction; handlers serialize on the io thread). The
-    // concurrent read lets a rejection — or a v1 server's bogus payload —
-    // abort a large in-flight WRITE instead of deadlocking on mutually
-    // full socket buffers, and delivers rejection frames before the close.
-    bool write_body_done_ = false;
-    bool write_acked_ok_ = false;
-    // An early negative/malformed ack can arrive while asio::async_write still
-    // owns a buffer pointing into the caller's source memory. Do not publish a
-    // terminal status until that body operation has completed or been
-    // cancelled: callers are allowed to release the source buffer as soon as
-    // the transfer becomes terminal.
-    bool write_body_in_flight_ = false;
-    bool write_abort_requested_ = false;
-    // A v2 status frame is prompt by construction: a READ status precedes
-    // any payload, and a WRITE ack follows at most one chunk's apply after
-    // the body is done. The only peer that never sends one is a legacy
-    // server reached through a stale v2 descriptor — and for requests
-    // shorter than a frame it also keeps the connection open (it streamed
-    // size < 8 bytes of "READ payload" and is waiting for our next header),
-    // so without a deadline both sides wait forever. Bound that wait; the
-    // default is generous so no healthy slow path can trip it, since it only
-    // covers the frame itself, never payload streaming.
-    static int statusFrameTimeoutSec() {
-        const char* env = std::getenv("MC_TCP_STATUS_TIMEOUT_SEC");
-        if (env) {
-            int v = std::atoi(env);
-            if (v > 0) return v;
-        }
-        return 30;
-    }
-    std::optional<asio::steady_timer> status_timer_;
-    bool status_deadline_disarmed_ = false;
-    std::function<void(TransferStatusEnum)> on_finalize_;
-    // Invoked exactly once per request with clean=true iff the protocol
-    // exchange terminated in a well-defined connection state. A socket whose
-    // request did not end cleanly must not be reused: the server-side session
-    // may be mid-frame, and the next request's header would be consumed as
-    // body bytes.
-    std::function<void(bool)> on_complete_;
-
-    void initiate(void* buffer, uint64_t dest_addr, size_t size,
-                  TransferRequest::OpCode opcode) {
-        local_buffer_ = (char*)buffer;
-        header_.addr = htole64(dest_addr);
-        header_.size = htole64(size);
-        header_.opcode = (uint8_t)opcode | (v2_ ? kOpcodeV2Flag : 0);
-        total_transferred_bytes_ = 0;
-        writeHeader();
+void invokeStartTransferMetadataHook() noexcept {
+    StartTransferMetadataHook hook;
+    {
+        std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+        hook = start_transfer_metadata_hook;
     }
+    if (hook) hook();
+}
+}  // namespace
 
-   private:
-    // All handlers run on the transport's single io thread, so arm/cancel
-    // and the expiry handler never race. Expiry only closes the socket: the
-    // pending status read then completes with an error and its handler owns
-    // the failure path (including source-buffer quiescence for WRITE).
-    void armStatusDeadline() {
-        auto self(shared_from_this());
-        status_deadline_disarmed_ = false;
-        status_timer_.emplace(socket_->get_executor());
-        status_timer_->expires_after(
-            std::chrono::seconds(statusFrameTimeoutSec()));
-        status_timer_->async_wait([this, self](const asio::error_code& ec) {
-            // The disarmed flag also covers an expiry that was already
-            // queued when cancel() ran (cancel cannot revoke those, and by
-            // then the socket may have been re-pooled).
-            if (ec == asio::error::operation_aborted ||
-                status_deadline_disarmed_) {
-                return;
-            }
-            LOG(ERROR) << "ClientSession: no status frame within "
-                       << statusFrameTimeoutSec()
-                       << "s (peer likely speaks the legacy protocol); "
-                          "dropping connection";
-            if (socket_ && socket_->is_open()) {
-                asio::error_code cec;
-                socket_->close(cec);
-            }
-        });
-    }
+void tcpTransportSetLaneConnectHandlerHookForTest(
+    LaneConnectHandlerHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_connect_handler_hook = hook;
+}
 
-    void cancelStatusDeadline() {
-        status_deadline_disarmed_ = true;
-        if (status_timer_) status_timer_->cancel();
-    }
+void tcpTransportSetLaneConnectFailureInjectionHookForTest(
+    LaneConnectFailureInjectionHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_connect_failure_injection_hook = hook;
+}
 
-    // Single terminal path: finish connection ownership, then report the
-    // outcome. Posted so it runs after the invoking callback returns.
-    void finalize(TransferStatusEnum status, bool clean) {
-        cancelStatusDeadline();
-        auto self(shared_from_this());
-        asio::post(
-            socket_->get_executor(),
-            [this, self, status, clean, on_finalize = std::move(on_finalize_),
-             on_complete = std::move(on_complete_)]() {
-                // Finish connection ownership before publishing terminal
-                // status. Once on_finalize marks the slice, the caller may
-                // immediately free the batch or destroy the transport.
-                if (on_complete) on_complete(clean);
-                if (on_finalize) on_finalize(status);
-            });
-    }
+void tcpTransportSetLaneObserverHookForTest(LaneObserverHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_observer_hook = hook;
+}
 
-    // Abort a v2 WRITE and cancel any body operation. If asio still owns the
-    // current source buffer, its completion handler is responsible for
-    // finalizing after the buffer is quiescent.
-    void abortWrite() {
-        write_abort_requested_ = true;
-        if (socket_ && socket_->is_open()) {
-            asio::error_code ec;
-            socket_->close(ec);
-        }
-        if (!write_body_in_flight_) finalize(TransferStatusEnum::FAILED, false);
-    }
+void tcpTransportSetLaneRetryHandlerHookForTest(
+    LaneRetryHandlerHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_retry_handler_hook = hook;
+}
 
-    void writeHeader() {
-        auto self(shared_from_this());
-        asio::async_write(
-            *socket_, asio::buffer(&header_, sizeof(SessionHeader)),
-            [this, self](const asio::error_code& ec, std::size_t len) {
-                if (ec || len != sizeof(SessionHeader)) {
-                    LOG(ERROR)
-                        << "ClientSession::writeHeader failed. Error: "
-                        << ec.message() << " (value: " << ec.value() << ")"
-                        << ", bytes written: " << len;
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                if ((header_.opcode & ~kOpcodeV2Flag) ==
-                    (uint8_t)TransferRequest::WRITE) {
-                    if (v2_) readWriteAck();  // concurrent with the body
-                    writeBody();
-                } else if (v2_) {
-                    readReadStatus();
-                } else {
-                    readBody();
-                }
-            });
-    }
+void tcpTransportSetLaneAdmissionHandlerHookForTest(
+    LaneAdmissionHandlerHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_admission_handler_hook = hook;
+}
 
-    // v2 READ: the server prefixes the data with a status frame.
-    void readReadStatus() {
-        auto self(shared_from_this());
-        armStatusDeadline();
-        asio::async_read(
-            *socket_, asio::buffer(&status_frame_, sizeof(status_frame_)),
-            [this, self](const asio::error_code& ec, std::size_t len) {
-                cancelStatusDeadline();
-                if (ec || len != sizeof(status_frame_)) {
-                    LOG(ERROR)
-                        << "ClientSession: failed to read READ status "
-                           "frame. Error: "
-                        << ec.message() << " (value: " << ec.value() << ")";
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                uint64_t frame = le64toh(status_frame_);
-                if (!statusFrameValid(frame)) {
-                    LOG(ERROR) << "ClientSession: malformed READ status "
-                                  "frame (peer likely speaks the legacy "
-                                  "protocol); dropping connection";
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                if (frame != kStatusOk) {
-                    LOG(ERROR) << "ClientSession: READ rejected by server, "
-                                  "status "
-                               << (frame & 0xFFFFFFFFull);
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                readBody();
-            });
-    }
+void tcpTransportSetLaneFailureReasonHookForTest(
+    LaneFailureReasonHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    lane_failure_reason_hook = hook;
+}
 
-    // v2 WRITE: completion is the server's acknowledgment that the payload
-    // has been applied to destination memory. Armed concurrently with the
-    // body stream; a well-behaved v2 server only sends the frame after the
-    // final chunk, so a frame arriving before the body is done is either a
-    // rejection or a legacy peer's payload — both close the socket immediately
-    // and publish failure only after the outstanding body write is quiescent.
-    void readWriteAck() {
-        auto self(shared_from_this());
-        asio::async_read(
-            *socket_, asio::buffer(&status_frame_, sizeof(status_frame_)),
-            [this, self](const asio::error_code& ec, std::size_t len) {
-                cancelStatusDeadline();
-                if (ec || len != sizeof(status_frame_)) {
-                    // The body path may have already finalized a failure and
-                    // closed the socket; finalize() is idempotent (moved-from
-                    // callbacks are null-checked).
-                    if (ec != asio::error::operation_aborted) {
-                        LOG(ERROR)
-                            << "ClientSession: failed to read WRITE "
-                               "ack frame. Error: "
-                            << ec.message() << " (value: " << ec.value() << ")";
-                    }
-                    abortWrite();
-                    return;
-                }
-                uint64_t frame = le64toh(status_frame_);
-                if (!statusFrameValid(frame)) {
-                    LOG(ERROR) << "ClientSession: malformed WRITE ack frame "
-                                  "(peer likely speaks the legacy protocol); "
-                                  "dropping connection";
-                    abortWrite();
-                    return;
-                }
-                if (frame != kStatusOk) {
-                    LOG(ERROR) << "ClientSession: WRITE rejected by server, "
-                                  "status "
-                               << (frame & 0xFFFFFFFFull);
-                    abortWrite();
-                    return;
-                }
-                if (!write_body_done_) {
-                    // The server's ack can legitimately overtake the final
-                    // local write-completion handler (both become ready
-                    // together for small writes; the io thread may run this
-                    // handler first). Record it; the body path finalizes.
-                    write_acked_ok_ = true;
-                    return;
-                }
-                finalize(TransferStatusEnum::COMPLETED, true);
-            });
-    }
+void tcpTransportSetSessionProgressHookForTest(
+    SessionProgressHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    session_progress_hook = hook;
+}
 
-    void readBody() {
-        auto self(shared_from_this());
-        uint64_t size = le64toh(header_.size);
-        char* addr = local_buffer_;
+void tcpTransportSetStartTransferMetadataHookForTest(
+    StartTransferMetadataHook hook) noexcept {
+    std::lock_guard<std::mutex> lock(lane_test_hook_mutex);
+    start_transfer_metadata_hook = hook;
+}
 
-        size_t buffer_size =
-            std::min(getChunkSize(), size - total_transferred_bytes_);
-        if (buffer_size == 0) {
-            finalize(TransferStatusEnum::COMPLETED, true);
-            return;
-        }
+bool tcpTransportLaneTypesAreMoveOnlyForTest() noexcept {
+    return std::is_move_constructible<TcpTransport::TcpWorkItem>::value &&
+           !std::is_copy_constructible<TcpTransport::TcpWorkItem>::value &&
+           !std::is_copy_assignable<TcpTransport::TcpWorkItem>::value &&
+           std::is_move_constructible<TcpTransport::TerminalAction>::value &&
+           !std::is_copy_constructible<TcpTransport::TerminalAction>::value &&
+           !std::is_copy_assignable<TcpTransport::TerminalAction>::value;
+}
 
-        char* dram_buffer = addr + total_transferred_bytes_;
-        int cuda_device = -1;
+void tcpTransportResetStagingStatsForTest() noexcept {
+    staging_buffer_allocation_count.store(0, std::memory_order_relaxed);
+    staging_device_query_count.store(0, std::memory_order_relaxed);
+}
 
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-        cuda_device = getCudaDeviceId(addr);
-        if (cuda_device >= 0) {
-            dram_buffer = new char[buffer_size];
-        }
-#endif
+size_t tcpTransportStagingBufferAllocationCountForTest() noexcept {
+    return staging_buffer_allocation_count.load(std::memory_order_relaxed);
+}
 
-        asio::async_read(
-            *socket_, asio::buffer(dram_buffer, buffer_size),
-            [this, addr, dram_buffer, cuda_device, self](
-                const asio::error_code& ec, std::size_t transferred_bytes) {
-                if (ec) {
-                    LOG(ERROR)
-                        << "ClientSession::readBody failed. "
-                        << "Attempt to read data " << static_cast<void*>(addr)
-                        << " using buffer " << static_cast<void*>(dram_buffer)
-                        << ". Error: " << ec.message()
-                        << " (value: " << ec.value() << ")";
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-                    if (cuda_device >= 0) delete[] dram_buffer;
+size_t tcpTransportStagingDeviceQueryCountForTest() noexcept {
+    return staging_device_query_count.load(std::memory_order_relaxed);
+}
 #endif
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
 
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-                if (cuda_device >= 0) {
-                    cudaSetDevice(cuda_device);
-#ifdef USE_MACA
-                    cudaError_t cuda_status =
-                        copyTcpCudaMemory(addr + total_transferred_bytes_,
-                                          dram_buffer, transferred_bytes);
-#else
-                    cudaError_t cuda_status =
-                        cudaMemcpy(addr + total_transferred_bytes_, dram_buffer,
-                                   transferred_bytes, cudaMemcpyDefault);
-#endif
-                    if (cuda_status != cudaSuccess) {
-                        LOG(ERROR)
-                            << "ClientSession::readBody failed to copy to CUDA "
-                               "memory. "
-                            << "Error: " << cudaGetErrorString(cuda_status);
-                        delete[] dram_buffer;
-                        finalize(TransferStatusEnum::FAILED, false);
-                        return;
-                    }
-                    delete[] dram_buffer;
-                }
-#endif
-                total_transferred_bytes_ += transferred_bytes;
-                readBody();
-            });
-    }
+#include "tcp_transport_session_impl.h"
 
-    void writeBody() {
-        auto self(shared_from_this());
-        uint64_t size = le64toh(header_.size);
-        char* addr = local_buffer_;
-
-        size_t buffer_size =
-            std::min(getChunkSize(), size - total_transferred_bytes_);
-        if (buffer_size == 0) {
-            if (v2_) {
-                if (write_abort_requested_) {
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                // Completion comes from the server's acknowledgment, whose
-                // read is already in flight (armed in writeHeader) and may
-                // have finished first.
-                write_body_done_ = true;
-                if (write_acked_ok_) {
-                    finalize(TransferStatusEnum::COMPLETED, true);
-                } else {
-                    // From here a well-behaved server owes at most one
-                    // chunk's apply plus the frame; a legacy peer behind a
-                    // stale descriptor may owe nothing, ever.
-                    armStatusDeadline();
-                }
-            } else {
-                // v1: no acknowledgment exists in the protocol; this only
-                // means the payload left the initiator (#2086).
-                finalize(TransferStatusEnum::COMPLETED, true);
-            }
-            return;
-        }
+namespace {
+constexpr size_t kMaxTcpLanesPerPeer = 16;
 
-        char* dram_buffer = addr + total_transferred_bytes_;
-        int cuda_device = -1;
+size_t parseBoundedTcpSetting(const char* name, const char* value,
+                              size_t default_value, size_t minimum,
+                              size_t maximum) {
+    if (!value) return default_value;
 
-#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
-    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
-    defined(USE_COREX)
-        cuda_device = getCudaDeviceId(addr);
-        if (cuda_device >= 0) {
-            dram_buffer = new char[buffer_size];
-            cudaSetDevice(cuda_device);
-#ifdef USE_MACA
-            cudaError_t cuda_status = copyTcpCudaMemory(
-                dram_buffer, addr + total_transferred_bytes_, buffer_size);
-#else
-            cudaError_t cuda_status =
-                cudaMemcpy(dram_buffer, addr + total_transferred_bytes_,
-                           buffer_size, cudaMemcpyDefault);
-#endif
-            if (cuda_status != cudaSuccess) {
-                LOG(ERROR) << "ClientSession::writeBody failed to copy from "
-                              "CUDA memory. "
-                           << "Error: " << cudaGetErrorString(cuda_status);
-                delete[] dram_buffer;
-                abortWrite();
-                return;
-            }
+    const std::string text(value);
+    size_t parsed = 0;
+    bool valid = !text.empty();
+    for (char c : text) {
+        if (c < '0' || c > '9') {
+            valid = false;
+            break;
         }
-#endif
-
-        write_body_in_flight_ = true;
-        asio::async_write(
-            *socket_, asio::buffer(dram_buffer, buffer_size),
-            [this, addr, dram_buffer, cuda_device, self](
-                const asio::error_code& ec, std::size_t transferred_bytes) {
-                write_body_in_flight_ = false;
-                if (cuda_device >= 0) {
-                    delete[] dram_buffer;
-                }
-                if (ec) {
-                    LOG(ERROR)
-                        << "ClientSession::writeBody failed. "
-                        << "Attempt to write data " << static_cast<void*>(addr)
-                        << " using buffer " << static_cast<void*>(dram_buffer)
-                        << ". Error: " << ec.message()
-                        << " (value: " << ec.value() << ")";
-                    abortWrite();
-                    return;
-                }
-                if (write_abort_requested_) {
-                    // The early ack path closed the socket while this
-                    // operation still owned the caller's source buffer. It is
-                    // safe to publish failure now that the handler has run.
-                    finalize(TransferStatusEnum::FAILED, false);
-                    return;
-                }
-                total_transferred_bytes_ += transferred_bytes;
-                writeBody();
-            });
-    }
-};
-
-struct TcpContext {
-    TcpContext(short port, ValidateAddrFn validate_addr)
-        : acceptor(io_context), validate_addr_(std::move(validate_addr)) {
-        std::error_code ec;
-        asio::ip::tcp::endpoint endpoint(asio::ip::tcp::v6(), port);
-
-        acceptor.open(endpoint.protocol(), ec);
-        if (!ec) {
-            acceptor.set_option(asio::ip::v6_only(false), ec);
-            if (!ec) {
-                acceptor.set_option(
-                    asio::ip::tcp::acceptor::reuse_address(true));
-                acceptor.bind(endpoint, ec);
-                if (!ec) {
-                    acceptor.listen();
-                    return;
-                }
-            }
-            acceptor.close();
+        const size_t digit = static_cast<size_t>(c - '0');
+        if (parsed > (maximum - digit) / size_t(10)) {
+            valid = false;
+            break;
         }
-        LOG(ERROR) << "Failed to set up IPv6 dual-stack listener: "
-                   << ec.message() << " (error code: " << ec.value() << ")";
-        asio::ip::tcp::endpoint endpoint_v4(asio::ip::tcp::v4(), port);
-        acceptor.open(endpoint_v4.protocol());
-        acceptor.set_option(asio::ip::tcp::acceptor::reuse_address(true));
-        acceptor.bind(endpoint_v4);
-        acceptor.listen();
+        parsed = parsed * 10 + digit;
     }
+    if (valid && parsed >= minimum && parsed <= maximum) return parsed;
 
-    void doAccept() {
-        acceptor.async_accept([this](asio::error_code ec, tcpsocket socket) {
-            if (!ec) {
-                asio::error_code nodelay_ec;
-                socket.set_option(asio::ip::tcp::no_delay(true), nodelay_ec);
-                auto socket_ptr =
-                    std::make_shared<tcpsocket>(std::move(socket));
-                auto session =
-                    std::make_shared<ServerSession>(socket_ptr, validate_addr_);
-                session->start();
-            }
-            doAccept();
-        });
-    }
+    LOG(WARNING) << "Invalid " << name << " value: " << text
+                 << ", using default " << default_value;
+    return default_value;
+}
 
-    asio::io_context io_context;
-    asio::ip::tcp::acceptor acceptor;
-    ValidateAddrFn validate_addr_;
-};
+bool validateTcpAddress(const std::shared_ptr<TransferMetadata>& metadata,
+                        uint64_t addr, uint64_t size) {
+    if (size == 0 || addr + size < addr) return false;
+
+    auto desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    if (!desc) return false;
+    for (const auto& buffer : desc->buffers) {
+        if (buffer.addr + buffer.length < buffer.addr) continue;
+        if (buffer.addr <= addr && addr + size <= buffer.addr + buffer.length)
+            return true;
+    }
+    return false;
+}
+}  // namespace
 
-TcpTransport::TcpTransport() : context_(nullptr), running_(false) {
+TcpTransport::TcpTransport()
+    : context_(nullptr),
+      running_(false),
+      lane_state_(std::make_shared<ConnectionLaneState>()) {
     if (getenv("MC_TCP_ENABLE_CONNECTION_POOL") != nullptr) {
         std::string val(getenv("MC_TCP_ENABLE_CONNECTION_POOL"));
         std::transform(val.begin(), val.end(), val.begin(),
@@ -851,22 +327,55 @@ TcpTransport::TcpTransport() : context_(nullptr), running_(false) {
             enable_connection_pool_ = true;
         }
     }
-}
 
-TcpTransport::~TcpTransport() {
-    if (running_) {
-        running_ = false;
-        context_->io_context.stop();
-        thread_.join();
-    }
+    constexpr size_t kDefaultLanesPerPeer = 4;
+    constexpr size_t kDefaultQueuedTransfersPerPeer = 65535;
+    constexpr size_t kMaxQueuedTransfersPerPeer = 1048576;
+    constexpr size_t kDefaultPendingAdmissionsPerPeer = 65535;
+    constexpr size_t kMaxPendingAdmissionsPerPeer = 1048576;
+    constexpr size_t kDefaultAdmissionTimeoutMs = 1000;
+    constexpr size_t kMaxAdmissionTimeoutMs = 600000;
 
-    // Clear connection pool BEFORE deleting context
-    // because sockets in the pool reference io_context
-    {
-        std::lock_guard<std::mutex> lock(pool_mutex_);
-        connection_pool_.clear();
+    const char* lanes_env = getenv("MC_TCP_LANES_PER_PEER");
+    if (lanes_env) {
+        lane_state_->lanes_per_peer = parseBoundedTcpSetting(
+            "MC_TCP_LANES_PER_PEER", lanes_env, kDefaultLanesPerPeer, 1,
+            kMaxTcpLanesPerPeer);
+    } else {
+        const char* deprecated_env = getenv("MC_TCP_MAX_CONNECTIONS_PER_PEER");
+        if (deprecated_env) {
+            LOG(WARNING) << "MC_TCP_MAX_CONNECTIONS_PER_PEER is deprecated; "
+                            "use MC_TCP_LANES_PER_PEER";
+            lane_state_->lanes_per_peer = parseBoundedTcpSetting(
+                "MC_TCP_MAX_CONNECTIONS_PER_PEER", deprecated_env,
+                kDefaultLanesPerPeer, 1, kMaxTcpLanesPerPeer);
+        }
     }
 
+    lane_state_->max_queued_transfers_per_peer = parseBoundedTcpSetting(
+        "MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER",
+        getenv("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER"),
+        kDefaultQueuedTransfersPerPeer, 1, kMaxQueuedTransfersPerPeer);
+    lane_state_->max_pending_admissions_per_peer = parseBoundedTcpSetting(
+        "MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+        getenv("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER"),
+        kDefaultPendingAdmissionsPerPeer, 1, kMaxPendingAdmissionsPerPeer);
+    lane_state_->admission_timeout =
+        std::chrono::milliseconds(parseBoundedTcpSetting(
+            "MC_TCP_ADMISSION_TIMEOUT_MS",
+            getenv("MC_TCP_ADMISSION_TIMEOUT_MS"), kDefaultAdmissionTimeoutMs,
+            1, kMaxAdmissionTimeoutMs));
+
+    constexpr size_t kDefaultNumIoThreads = 1;
+    constexpr size_t kMaxNumIoThreads = 32;
+    num_io_threads_ = parseBoundedTcpSetting(
+        "MC_NUM_TCP_IO_THREADS", getenv("MC_NUM_TCP_IO_THREADS"),
+        kDefaultNumIoThreads, 1, kMaxNumIoThreads);
+}
+
+TcpTransport::~TcpTransport() {
+    shutdownConnectionLanes();
+
     if (context_) {
         delete context_;
         context_ = nullptr;
@@ -915,11 +424,23 @@ int TcpTransport::install(std::string& local_server_name,
 
     close(sockfd);  // the above function has opened a socket
     LOG(INFO) << "TcpTransport: listen on port " << tcp_port;
-    context_ = new TcpContext(tcp_port, [this](uint64_t addr, uint64_t size) {
-        return validateAddress(addr, size);
-    });
+    auto metadata = metadata_;
+    io_pool_ = std::make_unique<TcpIoPool>(num_io_threads_);
+    context_ = new TcpContext(
+        *io_pool_, tcp_port,
+        [metadata = std::move(metadata)](uint64_t addr, uint64_t size) {
+            return validateTcpAddress(metadata, addr, size);
+        });
+    lane_runtime_ = std::make_shared<ConnectionLaneRuntime>(*io_pool_);
+    lane_state_->runtime = lane_runtime_;
     running_ = true;
-    thread_ = std::thread(&TcpTransport::worker, this);
+    // Shard 0 owns the acceptor; arm (and re-arm after a restart) doAccept on
+    // its own thread. Other shards just drain their io_context.
+    io_pool_->start([this](size_t shard) {
+        if (shard == 0) context_->doAccept();
+    });
+    LOG(INFO) << "TcpTransport: I/O pool started with " << num_io_threads_
+              << " thread(s)";
     return 0;
 }
 
@@ -933,6 +454,7 @@ int TcpTransport::allocateLocalSegmentID(int tcp_data_port) {
 #else
     desc->protocol = "tcp";
 #endif
+    desc->tcp_data_host = metadata_->localRpcMeta().ip_or_host_name;
     desc->tcp_data_port = tcp_data_port;
     // Advertise acknowledged framing (#2086); initiators fall back to v1
     // against descriptors that do not carry the field.
@@ -993,9 +515,13 @@ Status TcpTransport::getTransferStatus(BatchID batch_id, size_t task_id,
             std::to_string(batch_id));
     }
     auto& task = batch_desc.task_list[task_id];
-    status.transferred_bytes = task.transferred_bytes;
-    uint64_t success_slice_count = task.success_slice_count;
-    uint64_t failed_slice_count = task.failed_slice_count;
+    uint64_t success_slice_count =
+        __atomic_load_n(&task.success_slice_count, __ATOMIC_ACQUIRE);
+    uint64_t failed_slice_count =
+        __atomic_load_n(&task.failed_slice_count, __ATOMIC_ACQUIRE);
+    // Acquire completion counters before reading the bytes they publish.
+    status.transferred_bytes =
+        __atomic_load_n(&task.transferred_bytes, __ATOMIC_RELAXED);
     if (success_slice_count + failed_slice_count == task.slice_count) {
         if (failed_slice_count) {
             status.s = TransferStatusEnum::FAILED;
@@ -1034,9 +560,28 @@ Status TcpTransport::submitTransfer(
 
 Status TcpTransport::submitTransferTask(
     const std::vector<TransferTask*>& task_list) {
-    for (auto* task : task_list) {
+    for (size_t i = 0; i < task_list.size();) {
+        auto* task = task_list[i];
         assert(task && task->request);
-        startTransfer(prepareTransfer(task, *task->request));
+        const auto group_id = task->request->task_group_id;
+        if (group_id == TransferRequest::kNoTaskGroup) {
+            startTransfer(prepareTransfer(task, *task->request));
+            ++i;
+            continue;
+        }
+
+        std::vector<Slice*> slices;
+        do {
+            task = task_list[i];
+            assert(task && task->request);
+            for (size_t j = 0; j < task->request_count; ++j)
+                slices.push_back(prepareTransfer(task, task->request[j]));
+            ++i;
+        } while (i < task_list.size() && task_list[i]->request &&
+                 task_list[i]->request->task_group_id == group_id &&
+                 task_list[i - 1]->request + task_list[i - 1]->request_count ==
+                     task_list[i]->request);
+        startTransferSequence(std::move(slices));
     }
     return Status::OK();
 }
@@ -1047,7 +592,8 @@ Status TcpTransport::submitTransferTaskGroup(
     slices.reserve(task_list.size());
     for (auto* task : task_list) {
         assert(task && task->request);
-        slices.push_back(prepareTransfer(task, *task->request));
+        for (size_t j = 0; j < task->request_count; ++j)
+            slices.push_back(prepareTransfer(task, task->request[j]));
     }
     startTransferSequence(std::move(slices));
     return Status::OK();
@@ -1055,7 +601,7 @@ Status TcpTransport::submitTransferTaskGroup(
 
 Transport::Slice* TcpTransport::prepareTransfer(
     TransferTask* task, const TransferRequest& request) {
-    task->total_bytes = request.length;
+    task->total_bytes += request.length;
     Slice* slice = getSliceCache().allocate();
     slice->source_addr = static_cast<char*>(request.source);
     slice->length = request.length;
@@ -1072,254 +618,108 @@ Transport::Slice* TcpTransport::prepareTransfer(
 
 void TcpTransport::startTransferSequence(std::vector<Slice*> slices) {
     struct Sequence {
+        std::mutex mutex;
         std::vector<Slice*> slices;
         size_t next = 0;
+        bool advancing = false;
+        bool resume_requested = false;
     };
+
     auto sequence = std::make_shared<Sequence>();
     sequence->slices = std::move(slices);
+
     auto advance = std::make_shared<std::function<void()>>();
     std::weak_ptr<std::function<void()>> weak_advance = advance;
+
     *advance = [this, sequence, weak_advance]() {
         auto advance = weak_advance.lock();
-        if (!advance || sequence->next == sequence->slices.size()) return;
-        auto* slice = sequence->slices[sequence->next++];
-        std::function<void()> continuation;
-        if (sequence->next < sequence->slices.size())
-            continuation = [advance]() { (*advance)(); };
-        startTransfer(slice, std::move(continuation), true);
-    };
-    (*advance)();
-}
+        if (!advance) return;
 
-void TcpTransport::worker() {
-    while (running_) {
-        try {
-            context_->doAccept();
-            context_->io_context.run();
-        } catch (std::exception& e) {
-            LOG(ERROR) << "TcpTransport::worker encountered an exception "
-                          "during doAccept/run: "
-                       << e.what();
-            context_->io_context.restart();
+        {
+            std::lock_guard<std::mutex> lock(sequence->mutex);
+            if (sequence->next == sequence->slices.size()) return;
+            if (sequence->advancing) {
+                sequence->resume_requested = true;
+                return;
+            }
+            sequence->advancing = true;
         }
-    }
-}
 
-std::shared_ptr<asio::ip::tcp::socket> TcpTransport::getConnection(
-    const std::string& host, uint16_t port, bool use_pool) {
-    // Ungrouped transfers keep the configured connection-pool behavior.
-    if (!use_pool) {
-        try {
-            asio::ip::tcp::resolver resolver(context_->io_context);
-            auto endpoint_iterator =
-                resolver.resolve(host, std::to_string(port));
-            auto socket_ptr =
-                std::make_shared<asio::ip::tcp::socket>(context_->io_context);
-            asio::connect(*socket_ptr, endpoint_iterator);
-            socket_ptr->set_option(asio::ip::tcp::no_delay(true));
-            return socket_ptr;
-        } catch (std::exception& e) {
-            LOG(ERROR)
-                << "TcpTransport::getConnection failed to create connection to "
-                << host << ":" << port << ". Error: " << e.what();
-            return nullptr;
-        }
-    }
+        while (true) {
+            Slice* slice = nullptr;
+            bool has_more = false;
+            {
+                std::lock_guard<std::mutex> lock(sequence->mutex);
+                if (sequence->next == sequence->slices.size()) {
+                    sequence->advancing = false;
+                    return;
+                }
+                slice = sequence->slices[sequence->next++];
+                has_more = sequence->next < sequence->slices.size();
+                sequence->resume_requested = false;
+            }
 
-    ConnectionKey key{host, port};
+            std::function<void()> continuation;
+            if (has_more) {
+                continuation = [advance]() { (*advance)(); };
+            }
 
-    // First phase: search for available connection while holding the lock
-    {
-        std::lock_guard<std::mutex> lock(pool_mutex_);
-
-        // Cleanup idle and dead connections
-        cleanupIdleConnections();
-
-        auto it = connection_pool_.find(key);
-        if (it != connection_pool_.end()) {
-            auto& queue = it->second;
-
-            // Find an available connection
-            for (auto queue_it = queue.begin(); queue_it != queue.end();) {
-                auto& entry = *queue_it;
-                if (!entry->in_use) {
-                    // Check if connection is still alive
-                    if (entry->socket->is_open()) {
-                        entry->in_use = true;
-                        entry->last_used = std::chrono::steady_clock::now();
-                        return entry->socket;
-                    } else {
-                        // Remove dead connection immediately
-                        queue_it = queue.erase(queue_it);
-                        continue;
-                    }
+            // startTransfer may fail synchronously (including during shutdown).
+            // The trampoline above turns a synchronous continuation into
+            // another loop iteration rather than recursive calls. For an
+            // asynchronous completion, this invocation returns and the
+            // continuation becomes the next runner.
+            startTransfer(slice, std::move(continuation), true);
+
+            {
+                std::lock_guard<std::mutex> lock(sequence->mutex);
+                if (!sequence->resume_requested) {
+                    sequence->advancing = false;
+                    return;
                 }
-                ++queue_it;
             }
         }
-    }
+    };
 
-    // No available connection, create a new one (pool grows dynamically)
-    // Release lock before creating new connection to avoid blocking other
-    // threads during slow DNS resolution and TCP handshake
-    std::shared_ptr<asio::ip::tcp::socket> new_socket;
+    (*advance)();
+}
+
+std::shared_ptr<asio::ip::tcp::socket> TcpTransport::getConnection(
+    const std::string& host, uint16_t port) {
+    // The reusable path is owned by fixed connection lanes. This helper is
+    // only for the connection-pool-disabled one-shot path.
     try {
         asio::ip::tcp::resolver resolver(context_->io_context);
         auto endpoint_iterator = resolver.resolve(host, std::to_string(port));
-        new_socket =
+        auto socket_ptr =
             std::make_shared<asio::ip::tcp::socket>(context_->io_context);
-        asio::connect(*new_socket, endpoint_iterator);
-        new_socket->set_option(asio::ip::tcp::no_delay(true));
+        asio::connect(*socket_ptr, endpoint_iterator);
+        socket_ptr->set_option(asio::ip::tcp::no_delay(true));
+        return socket_ptr;
     } catch (std::exception& e) {
         LOG(ERROR)
             << "TcpTransport::getConnection failed to create connection to "
             << host << ":" << port << ". Error: " << e.what();
         return nullptr;
     }
-
-    // Re-acquire lock to add the new connection to the pool
-    std::shared_ptr<PooledConnection> entry;
-    {
-        std::lock_guard<std::mutex> lock(pool_mutex_);
-        // Re-check if another thread already added a connection while we were
-        // creating this one
-        auto& queue = connection_pool_[key];
-        for (auto it = queue.begin(); it != queue.end(); ++it) {
-            auto& existing_entry = *it;
-            if (!existing_entry->in_use && existing_entry->socket->is_open()) {
-                // Another thread added an available connection, use that
-                // instead and close the one we just created
-                if (new_socket && new_socket->is_open()) {
-                    asio::error_code ec;
-                    new_socket->close(ec);
-                }
-                existing_entry->in_use = true;
-                existing_entry->last_used = std::chrono::steady_clock::now();
-                return existing_entry->socket;
-            }
-        }
-
-        // No other connection available, add the one we created to the pool
-        entry = std::make_shared<PooledConnection>(new_socket, host, port);
-        queue.push_back(entry);
-    }
-
-    return entry->socket;
-}
-
-void TcpTransport::returnConnection(
-    const std::string& host, uint16_t port,
-    std::shared_ptr<asio::ip::tcp::socket> socket) {
-    ConnectionKey key{host, port};
-
-    std::lock_guard<std::mutex> lock(pool_mutex_);
-
-    auto it = connection_pool_.find(key);
-    if (it != connection_pool_.end()) {
-        for (auto entry_it = it->second.begin(); entry_it != it->second.end();
-             ++entry_it) {
-            if ((*entry_it)->socket == socket) {
-                if (socket->is_open()) {
-                    (*entry_it)->in_use = false;
-                    (*entry_it)->last_used = std::chrono::steady_clock::now();
-                } else {
-                    // Connection is dead, remove from pool
-                    it->second.erase(entry_it);
-                }
-                return;
-            }
-        }
-    }
-
-    // Connection not found in pool (might be temporary), close it
-    if (socket && socket->is_open()) {
-        asio::error_code ec;
-        socket->close(ec);
-    }
-}
-
-void TcpTransport::cleanupIdleConnections() {
-    auto now = std::chrono::steady_clock::now();
-
-    for (auto it = connection_pool_.begin(); it != connection_pool_.end();) {
-        auto& queue = it->second;
-
-        for (auto entry_it = queue.begin(); entry_it != queue.end();) {
-            auto& entry = *entry_it;
-            if (!entry->in_use) {
-                auto idle_duration =
-                    std::chrono::duration_cast<std::chrono::seconds>(
-                        now - entry->last_used)
-                        .count();
-                if (idle_duration > kConnectionIdleTimeout.count()) {
-                    if (entry->socket && entry->socket->is_open()) {
-                        asio::error_code ec;
-                        entry->socket->close(ec);
-                    }
-                    entry_it = queue.erase(entry_it);
-                    continue;
-                }
-            }
-            ++entry_it;
-        }
-
-        if (queue.empty()) {
-            it = connection_pool_.erase(it);
-        } else {
-            ++it;
-        }
-    }
 }
 
-bool TcpTransport::validateAddress(uint64_t addr, uint64_t size) const {
-    if (size == 0) return false;
-    if (addr + size < addr) return false;
-
-    auto desc = metadata_->getSegmentDescByID(LOCAL_SEGMENT_ID);
-    if (!desc) return false;
-
-    for (const auto& buffer : desc->buffers) {
-        if (buffer.addr + buffer.length < buffer.addr) continue;
-        if (buffer.addr <= addr && addr + size <= buffer.addr + buffer.length)
-            return true;
-    }
-    return false;
-}
-
-void TcpTransport::discardConnection(
-    const std::string& host, uint16_t port,
-    std::shared_ptr<asio::ip::tcp::socket> socket) {
-    if (socket && socket->is_open()) {
-        asio::error_code ec;
-        socket->close(ec);
-    }
-    std::lock_guard<std::mutex> lock(pool_mutex_);
-    auto it = connection_pool_.find(ConnectionKey{host, port});
-    if (it != connection_pool_.end()) {
-        auto& queue = it->second;
-        for (auto queue_it = queue.begin(); queue_it != queue.end();
-             ++queue_it) {
-            if ((*queue_it)->socket == socket) {
-                queue.erase(queue_it);
-                break;
-            }
-        }
-        if (queue.empty()) connection_pool_.erase(it);
-    }
-}
+#include "tcp_transport_lane_impl.h"
 
 void TcpTransport::startTransfer(Slice* slice,
                                  std::function<void()> continuation,
                                  bool reuse_connection) {
-    auto finish = [this, slice, continuation = std::move(continuation)](
-                      TransferStatusEnum status) mutable {
+    auto finish = [slice, &continuation](TransferStatusEnum status) mutable {
         if (status == TransferStatusEnum::COMPLETED)
             slice->markSuccess();
         else
             slice->markFailed();
-        if (continuation)
-            asio::post(context_->io_context, std::move(continuation));
+        if (continuation) {
+            auto next = std::move(continuation);
+            next();
+        }
     };
+
     auto desc = metadata_->getSegmentDescByID(slice->target_id);
     if (!desc) {
         LOG(ERROR) << "TcpTransport::startTransfer failed to get segment "
@@ -1329,10 +729,13 @@ void TcpTransport::startTransfer(Slice* slice,
         return;
     }
 
-    TransferMetadata::RpcMetaDesc meta_entry;
-    if (metadata_->getRpcMetaEntry(desc->name, meta_entry)) {
-        LOG(ERROR) << "TcpTransport::startTransfer failed to get RPC meta "
-                      "entry for segment name: "
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    invokeStartTransferMetadataHook();
+#endif
+
+    if (desc->tcp_data_host.empty()) {
+        LOG(ERROR) << "TcpTransport::startTransfer found no TCP data host for "
+                      "segment name: "
                    << desc->name;
         finish(TransferStatusEnum::FAILED);
         return;
@@ -1340,68 +743,91 @@ void TcpTransport::startTransfer(Slice* slice,
 
     // Zero-length requests are complete by definition. v1 reported them
     // COMPLETED while the server silently rejected size==0 in address
-    // validation; short-circuiting keeps that outcome (rather than turning
-    // no-ops into v2 rejection failures) without the pointless round trip.
+    // validation; preserve that outcome without a round trip.
     if (slice->length == 0) {
         finish(TransferStatusEnum::COMPLETED);
         return;
     }
 
-    const bool use_pool = enable_connection_pool_ || reuse_connection;
-    auto socket = getConnection(meta_entry.ip_or_host_name, desc->tcp_data_port,
-                                use_pool);
+    const ConnectionKey key{desc->tcp_data_host,
+                            static_cast<uint16_t>(desc->tcp_data_port)};
+    const bool use_v2 = desc->tcp_proto_version >= 2 && !forceLegacyTcpProto();
+    TcpWorkItem work(slice, use_v2, std::move(continuation));
+
+    // Scatter task groups request reuse even when the general pool setting is
+    // disabled. Fixed lanes provide the same serial socket reuse without
+    // reviving the old unbounded dynamic pool.
+    if (enable_connection_pool_ || reuse_connection) {
+        enqueuePooledTransfer(desc->name, key, std::move(work));
+        return;
+    }
+
+    // Preserve the connection-pool-disabled synchronous one-shot path.
+    auto socket = getConnection(key.host, key.port);
     if (!socket) {
         LOG(ERROR) << "TcpTransport::startTransfer failed to get connection to "
-                   << meta_entry.ip_or_host_name << ":" << desc->tcp_data_port;
-        finish(TransferStatusEnum::FAILED);
+                   << key.host << ":" << key.port;
+        completeTerminalAction(
+            TerminalAction(std::move(work), TransferStatusEnum::FAILED, false));
         return;
     }
+    startTransferWithSocket(std::move(work), std::move(socket));
+}
 
+void TcpTransport::startTransferWithSocket(
+    TcpWorkItem work, std::shared_ptr<asio::ip::tcp::socket> socket) noexcept {
+    const Slice* slice = work.slice;
+    std::shared_ptr<std::optional<TcpWorkItem>> terminal_work;
     try {
-        const bool use_v2 =
-            desc->tcp_proto_version >= 2 && !forceLegacyTcpProto();
-        auto session = std::make_shared<ClientSession>(socket, use_v2);
-
-        session->on_finalize_ = finish;
-
-        // Return connection to pool when the request terminated cleanly;
-        // otherwise the server-side session state is unknown (it may be
-        // mid-frame), so reusing the socket would desynchronize the next
-        // request. Discard it instead.
-        if (use_pool) {
-            session->on_complete_ = [this, host = meta_entry.ip_or_host_name,
-                                     port = desc->tcp_data_port,
-                                     socket](bool clean) {
-                if (clean)
-                    returnConnection(host, port, socket);
-                else
-                    discardConnection(host, port, socket);
-            };
-        } else {
-            session->on_complete_ = [socket](bool) {
-                // Close connection immediately after transfer
-                if (socket && socket->is_open()) {
-                    asio::error_code ec;
-                    socket->close(ec);
-                }
-            };
-        }
-
-        session->initiate(slice->source_addr, slice->tcp.dest_addr,
-                          slice->length, slice->opcode);
-    } catch (std::exception& e) {
+        terminal_work =
+            std::make_shared<std::optional<TcpWorkItem>>(std::move(work));
+        auto session = std::make_shared<ClientSession>(
+            socket, terminal_work->value().use_v2,
+            [terminal_work, socket](TransferStatusEnum status, bool) noexcept {
+                closeSocketNoThrow(socket);
+                if (!terminal_work->has_value()) return;
+                auto completed = std::move(terminal_work->value());
+                terminal_work->reset();
+                completeTerminalAction(
+                    TerminalAction(std::move(completed), status, false));
+            });
+        session->initiate(terminal_work->value().slice->source_addr,
+                          terminal_work->value().slice->tcp.dest_addr,
+                          terminal_work->value().slice->length,
+                          terminal_work->value().slice->opcode);
+    } catch (const std::exception& e) {
         LOG(ERROR) << "TcpTransport::startTransfer encountered an exception. "
                       "Slice details - source_addr: "
                    << slice->source_addr << ", length: " << slice->length
                    << ", opcode: " << (int)slice->opcode
                    << ", target_id: " << slice->target_id
                    << ". Exception: " << e.what();
-        // On exception, always close the socket and remove from pool if
-        // present. Don't return it to the pool as it may be in an
-        // inconsistent state.
-        discardConnection(meta_entry.ip_or_host_name,
-                          static_cast<uint16_t>(desc->tcp_data_port), socket);
-        finish(TransferStatusEnum::FAILED);
+        closeSocketNoThrow(socket);
+        if (terminal_work && terminal_work->has_value()) {
+            auto failed = std::move(terminal_work->value());
+            terminal_work->reset();
+            failWorkItem(std::move(failed), WorkFailureReason::SESSION_FAILED,
+                         lane_state_->failure_counters);
+        } else if (work.slice) {
+            failWorkItem(std::move(work), WorkFailureReason::SESSION_FAILED,
+                         lane_state_->failure_counters);
+        }
+    } catch (...) {
+        LOG(ERROR) << "TcpTransport::startTransfer encountered an unknown "
+                      "exception. Slice details - source_addr: "
+                   << slice->source_addr << ", length: " << slice->length
+                   << ", opcode: " << (int)slice->opcode
+                   << ", target_id: " << slice->target_id;
+        closeSocketNoThrow(socket);
+        if (terminal_work && terminal_work->has_value()) {
+            auto failed = std::move(terminal_work->value());
+            terminal_work->reset();
+            failWorkItem(std::move(failed), WorkFailureReason::SESSION_FAILED,
+                         lane_state_->failure_counters);
+        } else if (work.slice) {
+            failWorkItem(std::move(work), WorkFailureReason::SESSION_FAILED,
+                         lane_state_->failure_counters);
+        }
     }
 }
 
diff --git a/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_lane_impl.h b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_lane_impl.h
new file mode 100644
index 0000000000..09412e1663
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_lane_impl.h
@@ -0,0 +1,1596 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+// Private implementation fragment included by tcp_transport.cpp from inside
+// namespace mooncake. This file contains the bounded connection-lane state
+// machine and its test hooks; it is intentionally not a standalone translation
+// unit so this review-only split does not change linkage or initialization.
+
+namespace {
+constexpr size_t kMaxConcurrentLaneProbes = 1;
+// Conservative fixed policy for the first rate-limited implementation. The
+// exact cooldown/backoff policy remains subject to maintainer review.
+constexpr auto kReconnectRoundCooldown = std::chrono::seconds(1);
+constexpr auto kShutdownCancellationWait = std::chrono::seconds(2);
+
+bool shouldLogOccurrence(uint64_t occurrence) {
+    return occurrence != 0 && (occurrence & (occurrence - 1)) == 0;
+}
+
+void cancelTimerNoThrow(
+    const std::shared_ptr<asio::steady_timer>& timer) noexcept {
+    if (!timer) return;
+    asio::error_code ec;
+    timer->cancel(ec);
+}
+
+// Tracks only whether executor-posted cancellation actions ran. It is not an
+// asynchronous-handler quiescence barrier; stop/join provides that boundary.
+struct LaneCancellationPostTracker {
+    std::mutex mutex;
+    std::condition_variable cv;
+    size_t pending = 0;
+
+    void add() {
+        std::lock_guard<std::mutex> lock(mutex);
+        ++pending;
+    }
+
+    void done() {
+        {
+            std::lock_guard<std::mutex> lock(mutex);
+            if (pending != 0) --pending;
+        }
+        cv.notify_all();
+    }
+
+    void waitUntil(std::chrono::steady_clock::time_point deadline) {
+        std::unique_lock<std::mutex> lock(mutex);
+        cv.wait_until(lock, deadline, [this] { return pending == 0; });
+    }
+};
+}  // namespace
+
+bool TcpTransport::hasUsableLaneLocked(const PeerConnectionGroup& group) {
+    for (const auto& lane : group.lanes) {
+        if ((lane->state == LaneState::IDLE || lane->state == LaneState::BUSY ||
+             lane->state == LaneState::COMPLETING) &&
+            lane->socket && lane->socket->is_open()) {
+            return true;
+        }
+    }
+    return false;
+}
+
+bool TcpTransport::hasDisconnectedLaneLocked(const PeerConnectionGroup& group) {
+    return std::any_of(group.lanes.begin(), group.lanes.end(),
+                       [](const auto& lane) {
+                           return lane->state == LaneState::DISCONNECTED;
+                       });
+}
+
+bool TcpTransport::hasUntriedDisconnectedLaneLocked(
+    const PeerConnectionGroup& group) {
+    return std::any_of(
+        group.lanes.begin(), group.lanes.end(), [&group](const auto& lane) {
+            return lane->state == LaneState::DISCONNECTED &&
+                   lane->last_connect_round != group.connect_round;
+        });
+}
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+size_t TcpTransport::activeSocketCountLocked(const PeerConnectionGroup& group) {
+    size_t count = 0;
+    for (const auto& lane : group.lanes) {
+        if (lane->resolver || lane->socket) ++count;
+    }
+    return count;
+}
+#endif
+
+void TcpTransport::beginConnectRoundLocked(PeerConnectionGroup& group) {
+    ++group.connect_round;
+    if (group.connect_round == 0) group.connect_round = 1;
+    group.connect_round_had_success = false;
+    group.next_probe_not_before = {};
+}
+
+void TcpTransport::enterReconnectCooldownLocked(PeerConnectionGroup& group) {
+    group.next_probe_not_before =
+        std::chrono::steady_clock::now() + kReconnectRoundCooldown;
+}
+
+void TcpTransport::addQueuedBytesLocked(PeerConnectionGroup& group,
+                                        uint64_t length) {
+    if (group.queued_bytes_saturated) return;
+    if (group.queued_bytes > std::numeric_limits<uint64_t>::max() - length) {
+        group.queued_bytes = std::numeric_limits<uint64_t>::max();
+        group.queued_bytes_saturated = true;
+        return;
+    }
+    group.queued_bytes += length;
+}
+
+void TcpTransport::removeQueuedBytesLocked(PeerConnectionGroup& group,
+                                           uint64_t length) {
+    if (!group.queued_bytes_saturated) {
+        group.queued_bytes =
+            group.queued_bytes >= length ? group.queued_bytes - length : 0;
+        return;
+    }
+
+    // Once saturated, UINT64_MAX is only an explicit lower-fidelity marker,
+    // not an exact sum. Recompute after removal so exact accounting resumes as
+    // soon as the remaining queue fits in uint64_t.
+    group.queued_bytes = 0;
+    group.queued_bytes_saturated = false;
+    for (const auto& item : group.queue) {
+        addQueuedBytesLocked(group, item.slice->length);
+        if (group.queued_bytes_saturated) break;
+    }
+}
+
+void TcpTransport::clearQueuedBytesLocked(PeerConnectionGroup& group) {
+    group.queued_bytes = 0;
+    group.queued_bytes_saturated = false;
+}
+
+size_t TcpTransport::expirePendingAdmissionsLocked(
+    PeerConnectionGroup& group, std::chrono::steady_clock::time_point now,
+    std::deque<TcpWorkItem>& expired) {
+    size_t count = 0;
+    while (!group.pending_admissions.empty() &&
+           group.pending_admissions.front().admission_deadline <= now) {
+        expired.emplace_back(std::move(group.pending_admissions.front()));
+        group.pending_admissions.pop_front();
+        ++count;
+    }
+    return count;
+}
+
+size_t TcpTransport::promotePendingAdmissionsLocked(
+    PeerConnectionGroup& group) {
+    size_t count = 0;
+    while (group.queue.size() < group.queue_capacity &&
+           !group.pending_admissions.empty()) {
+        group.queue.emplace_back(std::move(group.pending_admissions.front()));
+        group.pending_admissions.pop_front();
+        addQueuedBytesLocked(group, group.queue.back().slice->length);
+        ++count;
+    }
+    return count;
+}
+
+void TcpTransport::refreshAdmissionTimerLocked(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    std::deque<TcpWorkItem>& runtime_failed,
+    std::shared_ptr<asio::steady_timer>& timer_to_cancel, bool& timer_armed) {
+    timer_armed = false;
+    if (group->pending_admissions.empty()) {
+        if (group->admission_timer) {
+            ++group->admission_epoch;
+            if (group->admission_epoch == 0) ++group->admission_epoch;
+            timer_to_cancel = std::move(group->admission_timer);
+        }
+        return;
+    }
+
+    if (group->admission_timer) return;
+
+    try {
+        auto timer = std::make_shared<asio::steady_timer>(group->executor);
+        timer->expires_at(group->pending_admissions.front().admission_deadline);
+        ++group->admission_epoch;
+        if (group->admission_epoch == 0) ++group->admission_epoch;
+        const uint64_t admission_epoch = group->admission_epoch;
+        group->admission_timer = timer;
+        timer->async_wait([group, timer, admission_epoch](asio::error_code ec) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+            invokeLaneAdmissionHandlerHook();
+#endif
+            handleAdmissionTimer(group, timer, admission_epoch, ec);
+        });
+        timer_armed = true;
+        return;
+    } catch (...) {
+        ++group->admission_epoch;
+        if (group->admission_epoch == 0) ++group->admission_epoch;
+        if (group->admission_timer)
+            timer_to_cancel = std::move(group->admission_timer);
+        while (!group->pending_admissions.empty()) {
+            runtime_failed.emplace_back(
+                std::move(group->pending_admissions.front()));
+            group->pending_admissions.pop_front();
+        }
+        return;
+    }
+}
+
+void TcpTransport::handleAdmissionTimer(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<asio::steady_timer>& timer, uint64_t admission_epoch,
+    asio::error_code ec) {
+    std::deque<TcpWorkItem> expired;
+    std::deque<TcpWorkItem> runtime_failed;
+    std::shared_ptr<asio::steady_timer> timer_to_cancel;
+    uint64_t pump_epoch = 0;
+    size_t promoted = 0;
+    [[maybe_unused]] size_t pending_depth = 0;
+    bool timer_armed = false;
+    [[maybe_unused]] bool fired = false;
+    [[maybe_unused]] bool late = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            group->admission_epoch != admission_epoch ||
+            group->admission_timer != timer) {
+            late = true;
+        } else {
+            group->admission_timer.reset();
+            fired = true;
+            if (ec) {
+                // Cancellation normally increments admission_epoch first and
+                // is therefore stale. Keep this guard for other Asio timer
+                // errors delivered while the matching timer is still active.
+                while (!group->pending_admissions.empty()) {
+                    runtime_failed.emplace_back(
+                        std::move(group->pending_admissions.front()));
+                    group->pending_admissions.pop_front();
+                }
+            } else {
+                expirePendingAdmissionsLocked(
+                    *group, std::chrono::steady_clock::now(), expired);
+                promoted = promotePendingAdmissionsLocked(*group);
+                refreshAdmissionTimerLocked(group, runtime_failed,
+                                            timer_to_cancel, timer_armed);
+                if (promoted != 0) pump_epoch = requestGroupPumpLocked(*group);
+            }
+            pending_depth = group->pending_admissions.size();
+        }
+    }
+
+    cancelTimerNoThrow(timer_to_cancel);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (late) {
+        invokeLaneObserverHook(kLaneAdmissionTimerLate, 0, 0, 0, false);
+    } else if (fired) {
+        invokeLaneObserverHook(kLaneAdmissionTimerFired, pending_depth, 0, 0,
+                               false);
+    }
+    if (promoted != 0)
+        invokeLaneObserverHook(kLaneAdmissionPromoted, pending_depth, promoted,
+                               0, false);
+    if (timer_armed)
+        invokeLaneObserverHook(kLaneAdmissionTimerArmed, pending_depth, 0, 0,
+                               false);
+#endif
+    failWorkItems(std::move(expired), WorkFailureReason::QUEUE_TIMEOUT,
+                  group->failure_counters);
+    failWorkItems(std::move(runtime_failed),
+                  WorkFailureReason::RUNTIME_UNAVAILABLE,
+                  group->failure_counters);
+    if (pump_epoch != 0) postGroupPump(group, pump_epoch);
+}
+
+bool TcpTransport::armRetryTimerLocked(
+    const std::shared_ptr<PeerConnectionGroup>& group) {
+    if (group->retry_timer || group->state != GroupState::OPEN ||
+        group->queue.empty()) {
+        return true;
+    }
+
+    try {
+        auto timer = std::make_shared<asio::steady_timer>(group->executor);
+        timer->expires_at(group->next_probe_not_before);
+        ++group->retry_epoch;
+        if (group->retry_epoch == 0) ++group->retry_epoch;
+        const uint64_t retry_epoch = group->retry_epoch;
+        group->retry_timer = timer;
+        // A handler abandoned by io_context.stop() is harmless: it holds only
+        // group/timer shared state and can only request a new connection round.
+        timer->async_wait([group, timer, retry_epoch](asio::error_code ec) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+            invokeLaneRetryHandlerHook();
+#endif
+            handleRetryTimer(group, timer, retry_epoch, ec);
+        });
+        return true;
+    } catch (...) {
+        group->retry_timer.reset();
+        ++group->retry_epoch;
+        if (group->retry_epoch == 0) ++group->retry_epoch;
+        return false;
+    }
+}
+
+void TcpTransport::handleRetryTimer(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<asio::steady_timer>& timer, uint64_t retry_epoch,
+    asio::error_code ec) {
+    uint64_t pump_epoch = 0;
+    [[maybe_unused]] bool fired = false;
+    [[maybe_unused]] bool late = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->retry_epoch != retry_epoch || group->retry_timer != timer) {
+            late = true;
+        } else {
+            group->retry_timer.reset();
+            if (group->state != GroupState::OPEN) {
+                // Shutdown also bumps retry_epoch, so this is normally caught
+                // by the identity check above. Retain the state guard for a
+                // handler that observes the transition at this boundary.
+                late = group->state != GroupState::OPEN;
+            } else if (!group->queue.empty() && !ec &&
+                       group->probes_in_flight == 0 &&
+                       hasDisconnectedLaneLocked(*group) &&
+                       !hasUntriedDisconnectedLaneLocked(*group)) {
+                beginConnectRoundLocked(*group);
+                pump_epoch = requestGroupPumpLocked(*group);
+                fired = true;
+            } else if (!group->queue.empty() && group->probes_in_flight == 0) {
+                pump_epoch = requestGroupPumpLocked(*group);
+            }
+        }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (late)
+        invokeLaneObserverHook(kLaneRetryLate, 0, 0, 0, false);
+    else if (fired)
+        invokeLaneObserverHook(kLaneRetryFired, 0, 0, 0, false);
+#endif
+    if (pump_epoch != 0) postGroupPump(group, pump_epoch);
+}
+
+uint64_t TcpTransport::requestGroupPumpLocked(PeerConnectionGroup& group) {
+    if (group.state != GroupState::OPEN || group.pump_scheduled ||
+        group.queue.empty()) {
+        return 0;
+    }
+    group.pump_scheduled = true;
+    ++group.pump_epoch;
+    if (group.pump_epoch == 0) ++group.pump_epoch;
+    return group.pump_epoch;
+}
+
+bool TcpTransport::requestGroupRetirementLocked(PeerConnectionGroup& group) {
+    if (!group.retiring || group.retirement_scheduled ||
+        group.state != GroupState::OPEN) {
+        return false;
+    }
+    group.retirement_scheduled = true;
+    return true;
+}
+
+void TcpTransport::postGroupRetirement(
+    const std::shared_ptr<PeerConnectionGroup>& group) {
+    try {
+        asio::post(group->executor, [group] { runGroupRetirement(group); });
+    } catch (...) {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        group->retirement_scheduled = false;
+    }
+}
+
+void TcpTransport::scheduleGroupRetirement(
+    const std::shared_ptr<PeerConnectionGroup>& group) {
+    bool scheduled = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        scheduled = requestGroupRetirementLocked(*group);
+    }
+    if (scheduled) postGroupRetirement(group);
+}
+
+void TcpTransport::runGroupRetirement(
+    const std::shared_ptr<PeerConnectionGroup>& group) {
+    std::shared_ptr<asio::steady_timer> retry_timer;
+    std::shared_ptr<asio::steady_timer> admission_timer;
+    // Each lane's asio objects live on that lane's shard executor; collect them
+    // together with the executor so teardown can run on the owning shard.
+    struct LaneTeardown {
+        asio::io_context::executor_type executor;
+        std::shared_ptr<ClientSession> session;
+        std::shared_ptr<asio::ip::tcp::resolver> resolver;
+        std::shared_ptr<asio::ip::tcp::socket> socket;
+    };
+    std::vector<LaneTeardown> teardowns;
+    uint64_t pump_epoch = 0;
+    bool retired = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        group->retirement_scheduled = false;
+        if (!group->retiring || group->state != GroupState::OPEN) return;
+
+        if (!group->queue.empty() || !group->pending_admissions.empty()) {
+            pump_epoch = requestGroupPumpLocked(*group);
+        } else {
+            const bool owned_work = std::any_of(
+                group->lanes.begin(), group->lanes.end(), [](const auto& lane) {
+                    return lane->state == LaneState::BUSY ||
+                           lane->state == LaneState::COMPLETING ||
+                           lane->current.has_value();
+                });
+            if (owned_work) return;
+
+            group->state = GroupState::CLOSING;
+            group->pump_scheduled = false;
+            ++group->pump_epoch;
+            ++group->retry_epoch;
+            if (group->retry_epoch == 0) ++group->retry_epoch;
+            ++group->admission_epoch;
+            if (group->admission_epoch == 0) ++group->admission_epoch;
+            retry_timer = std::move(group->retry_timer);
+            admission_timer = std::move(group->admission_timer);
+            for (const auto& lane : group->lanes) {
+                ++lane->operation_epoch;
+                if (lane->operation_epoch == 0) ++lane->operation_epoch;
+                if (lane->session || lane->resolver || lane->socket)
+                    teardowns.push_back(
+                        {lane->executor, std::move(lane->session),
+                         std::move(lane->resolver), std::move(lane->socket)});
+                lane->connect_stage = LaneConnectStage::NONE;
+                lane->state = LaneState::CLOSED;
+            }
+            group->probes_in_flight = 0;
+            group->state = GroupState::CLOSED;
+            retired = true;
+        }
+    }
+
+    if (pump_epoch != 0) {
+        postGroupPump(group, pump_epoch);
+        return;
+    }
+    if (!retired) return;
+
+    // Cancel/close each lane's socket, session and resolver ON ITS OWN SHARD
+    // so these asio objects are only touched by their owning io thread. With
+    // MC_NUM_TCP_IO_THREADS == 1 asio::dispatch runs inline (unchanged
+    // behavior); with more shards it hops to the lane's io thread, avoiding
+    // concurrent close()/cancel() against an outstanding async op.
+    for (auto& teardown : teardowns) {
+        auto session = std::move(teardown.session);
+        auto resolver = std::move(teardown.resolver);
+        auto socket = std::move(teardown.socket);
+        asio::dispatch(teardown.executor, [session, resolver, socket] {
+            if (session) session->cancel();
+            if (resolver) {
+                try {
+                    resolver->cancel();
+                } catch (...) {
+                }
+            }
+            closeSocketNoThrow(socket);
+        });
+    }
+    // Retry/admission timers are group->executor objects and we are running on
+    // that executor, so cancel them here.
+    cancelTimerNoThrow(retry_timer);
+    cancelTimerNoThrow(admission_timer);
+
+    if (auto state = group->owner_state.lock()) {
+        std::lock_guard<std::mutex> state_lock(state->mutex);
+        auto it = std::find(state->retiring_groups.begin(),
+                            state->retiring_groups.end(), group);
+        if (it != state->retiring_groups.end())
+            state->retiring_groups.erase(it);
+    }
+}
+
+void TcpTransport::enqueuePooledTransfer(const std::string& logical_peer,
+                                         const ConnectionKey& key,
+                                         TcpWorkItem work) {
+    const auto state = lane_state_;
+    std::shared_ptr<PeerConnectionGroup> group;
+    std::optional<TcpWorkItem> rejected;
+    std::deque<TcpWorkItem> expired;
+    std::deque<TcpWorkItem> runtime_failed;
+    std::shared_ptr<asio::steady_timer> timer_to_cancel;
+    std::shared_ptr<PeerConnectionGroup> retiring_group;
+    WorkFailureReason rejection_reason = WorkFailureReason::QUEUE_FULL;
+    uint64_t pump_epoch = 0;
+    [[maybe_unused]] size_t promoted = 0;
+    [[maybe_unused]] size_t pending_depth = 0;
+    [[maybe_unused]] bool direct_admission = false;
+    [[maybe_unused]] bool pending_admission = false;
+    [[maybe_unused]] bool hard_rejection = false;
+    bool timer_armed = false;
+    bool retirement_scheduled = false;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    size_t queue_depth = 0;
+    uint64_t queued_bytes = 0;
+    size_t active_sockets = 0;
+#endif
+
+    try {
+        std::lock_guard<std::mutex> state_lock(state->mutex);
+        if (state->shutting_down) {
+            rejected.emplace(std::move(work));
+            rejection_reason = WorkFailureReason::SHUTDOWN;
+        } else {
+            auto runtime = state->runtime.lock();
+            if (!runtime) {
+                rejected.emplace(std::move(work));
+                rejection_reason = WorkFailureReason::RUNTIME_UNAVAILABLE;
+            } else {
+                auto current_it = state->current_key_by_peer.find(logical_peer);
+                if (current_it == state->current_key_by_peer.end()) {
+                    state->current_key_by_peer.emplace(logical_peer, key);
+                } else if (!(current_it->second == key)) {
+                    const ConnectionKey old_key = current_it->second;
+                    current_it->second = key;
+                    const bool old_key_still_current =
+                        std::any_of(state->current_key_by_peer.begin(),
+                                    state->current_key_by_peer.end(),
+                                    [&old_key](const auto& entry) {
+                                        return entry.second == old_key;
+                                    });
+                    if (!old_key_still_current) {
+                        auto old_group_it = state->groups.find(old_key);
+                        if (old_group_it != state->groups.end()) {
+                            retiring_group = old_group_it->second;
+                            state->retiring_groups.push_back(retiring_group);
+                            state->groups.erase(old_group_it);
+                            std::lock_guard<std::mutex> old_group_lock(
+                                retiring_group->mutex);
+                            retiring_group->retiring = true;
+                            retirement_scheduled =
+                                requestGroupRetirementLocked(*retiring_group);
+                        }
+                    }
+                }
+
+                auto group_it = state->groups.find(key);
+                if (group_it == state->groups.end()) {
+                    group = std::make_shared<PeerConnectionGroup>(
+                        key,
+                        runtime->coordinatorExecutor(ConnectionKeyHash{}(key)),
+                        state->max_queued_transfers_per_peer,
+                        state->max_pending_admissions_per_peer,
+                        state->admission_timeout, state->failure_counters);
+                    group->lanes.reserve(state->lanes_per_peer);
+                    for (size_t i = 0; i < state->lanes_per_peer; ++i) {
+                        group->lanes.push_back(std::make_shared<ConnectionLane>(
+                            i, group, runtime->nextLaneExecutor()));
+                    }
+                    auto [inserted_it, inserted] =
+                        state->groups.emplace(key, group);
+                    if (!inserted) group = inserted_it->second;
+                    group->owner_state = state;
+                } else {
+                    group = group_it->second;
+                }
+
+                std::lock_guard<std::mutex> group_lock(group->mutex);
+                if (group->state != GroupState::OPEN) {
+                    rejected.emplace(std::move(work));
+                    rejection_reason = WorkFailureReason::SHUTDOWN;
+                } else {
+                    // Submissions arriving during cooldown remain subject to
+                    // the bounded queue and wait until the retry timer expires
+                    // and a new round begins, so their added latency is bounded
+                    // by the cooldown length.
+                    const auto admission_time =
+                        std::chrono::steady_clock::now();
+                    expirePendingAdmissionsLocked(*group, admission_time,
+                                                  expired);
+                    promoted = promotePendingAdmissionsLocked(*group);
+
+                    if (group->pending_admissions.empty() &&
+                        group->queue.size() < group->queue_capacity) {
+                        group->queue.emplace_back(std::move(work));
+                        addQueuedBytesLocked(*group,
+                                             group->queue.back().slice->length);
+                        direct_admission = true;
+                    } else if (group->pending_admissions.size() <
+                               group->pending_admission_capacity) {
+                        work.admission_deadline =
+                            admission_time + group->admission_timeout;
+                        group->pending_admissions.emplace_back(std::move(work));
+                        pending_admission = true;
+                    } else {
+                        rejected.emplace(std::move(work));
+                        hard_rejection = true;
+                    }
+
+                    refreshAdmissionTimerLocked(group, runtime_failed,
+                                                timer_to_cancel, timer_armed);
+                    pump_epoch = requestGroupPumpLocked(*group);
+                    pending_depth = group->pending_admissions.size();
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                    queue_depth = group->queue.size();
+                    queued_bytes = group->queued_bytes;
+                    active_sockets = activeSocketCountLocked(*group);
+#endif
+                }
+            }
+        }
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "Failed to admit TCP work for " << key.host << ":"
+                   << key.port << ". Error: " << e.what();
+        if (work.slice) rejected.emplace(std::move(work));
+        rejection_reason = WorkFailureReason::RUNTIME_UNAVAILABLE;
+    } catch (...) {
+        LOG(ERROR) << "Failed to admit TCP work for " << key.host << ":"
+                   << key.port << ". Error: unknown exception";
+        if (work.slice) rejected.emplace(std::move(work));
+        rejection_reason = WorkFailureReason::RUNTIME_UNAVAILABLE;
+    }
+
+    cancelTimerNoThrow(timer_to_cancel);
+    if (retirement_scheduled) postGroupRetirement(retiring_group);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (rejected) {
+        invokeLaneObserverHook(kLaneQueueRejected, queue_depth, queued_bytes,
+                               active_sockets, false);
+    } else if (direct_admission) {
+        invokeLaneObserverHook(kLaneQueueAdmitted, queue_depth, queued_bytes,
+                               active_sockets, false);
+    }
+    if (pending_admission)
+        invokeLaneObserverHook(kLaneAdmissionPending, pending_depth, 0, 0,
+                               false);
+    if (promoted != 0)
+        invokeLaneObserverHook(kLaneAdmissionPromoted, pending_depth, promoted,
+                               0, false);
+    if (timer_armed)
+        invokeLaneObserverHook(kLaneAdmissionTimerArmed, pending_depth, 0, 0,
+                               false);
+    if (hard_rejection)
+        invokeLaneObserverHook(kLaneAdmissionHardRejected, pending_depth, 0, 0,
+                               false);
+#endif
+
+    failWorkItems(std::move(expired), WorkFailureReason::QUEUE_TIMEOUT,
+                  state->failure_counters);
+    failWorkItems(std::move(runtime_failed),
+                  WorkFailureReason::RUNTIME_UNAVAILABLE,
+                  state->failure_counters);
+    if (rejected)
+        failWorkItem(std::move(*rejected), rejection_reason,
+                     state->failure_counters);
+    else if (pump_epoch != 0)
+        postGroupPump(group, pump_epoch);
+}
+
+void TcpTransport::postGroupPump(
+    const std::shared_ptr<PeerConnectionGroup>& group, uint64_t pump_epoch) {
+    auto fail_posted_work = [&](const char* error) {
+        std::deque<TcpWorkItem> failed_queue;
+        std::deque<TcpWorkItem> failed_pending;
+        std::shared_ptr<asio::steady_timer> admission_timer;
+        {
+            std::lock_guard<std::mutex> lock(group->mutex);
+            if (group->pump_scheduled && group->pump_epoch == pump_epoch) {
+                group->pump_scheduled = false;
+                failed_queue.swap(group->queue);
+                clearQueuedBytesLocked(*group);
+                failed_pending.swap(group->pending_admissions);
+                ++group->admission_epoch;
+                if (group->admission_epoch == 0) ++group->admission_epoch;
+                admission_timer = std::move(group->admission_timer);
+            }
+        }
+        cancelTimerNoThrow(admission_timer);
+        failWorkItems(std::move(failed_queue),
+                      WorkFailureReason::RUNTIME_UNAVAILABLE,
+                      group->failure_counters);
+        failWorkItems(std::move(failed_pending),
+                      WorkFailureReason::RUNTIME_UNAVAILABLE,
+                      group->failure_counters);
+        LOG(ERROR) << "Failed to schedule TCP lane pump for " << group->key.host
+                   << ":" << group->key.port
+                   << (error && *error ? ". Error: " : "")
+                   << (error && *error ? error : "");
+        scheduleGroupRetirement(group);
+    };
+
+    try {
+        asio::post(group->executor,
+                   [group, pump_epoch] { runGroupPump(group, pump_epoch); });
+    } catch (const std::exception& e) {
+        fail_posted_work(e.what());
+    } catch (...) {
+        fail_posted_work(nullptr);
+    }
+}
+
+void TcpTransport::runGroupPump(
+    const std::shared_ptr<PeerConnectionGroup>& group, uint64_t pump_epoch) {
+    struct LaneStart {
+        std::shared_ptr<ConnectionLane> lane;
+        uint64_t epoch;
+    };
+    std::array<LaneStart, kMaxTcpLanesPerPeer> sessions;
+    std::array<LaneStart, kMaxTcpLanesPerPeer> connects;
+    size_t session_count = 0;
+    size_t connect_count = 0;
+    std::deque<TcpWorkItem> failed;
+    std::deque<TcpWorkItem> expired;
+    std::deque<TcpWorkItem> runtime_failed;
+    std::shared_ptr<asio::steady_timer> admission_timer_to_cancel;
+    WorkFailureReason failure_reason = WorkFailureReason::CONNECT_FAILED;
+    uint64_t followup_pump_epoch = 0;
+    [[maybe_unused]] size_t promoted = 0;
+    [[maybe_unused]] size_t pending_depth = 0;
+    bool queue_detached_after_scheduling = false;
+    [[maybe_unused]] bool retry_armed = false;
+    [[maybe_unused]] bool cooldown_started = false;
+    [[maybe_unused]] bool admission_timer_armed = false;
+
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (!group->pump_scheduled || group->pump_epoch != pump_epoch) return;
+        group->pump_scheduled = false;
+        if (group->state != GroupState::OPEN) return;
+
+        expirePendingAdmissionsLocked(*group, std::chrono::steady_clock::now(),
+                                      expired);
+        promoted += promotePendingAdmissionsLocked(*group);
+
+        for (const auto& lane : group->lanes) {
+            if (group->queue.empty()) break;
+            if (lane->state != LaneState::IDLE) continue;
+            if (!lane->socket || !lane->socket->is_open()) {
+                lane->socket.reset();
+                lane->state = LaneState::DISCONNECTED;
+                continue;
+            }
+
+            lane->current.emplace(std::move(group->queue.front()));
+            const uint64_t length = lane->current->slice->length;
+            group->queue.pop_front();
+            removeQueuedBytesLocked(*group, length);
+            if (group->queue.empty()) clearQueuedBytesLocked(*group);
+            promoted += promotePendingAdmissionsLocked(*group);
+            lane->state = LaneState::BUSY;
+            ++lane->operation_epoch;
+            if (lane->operation_epoch == 0) ++lane->operation_epoch;
+            sessions[session_count++] = {lane, lane->operation_epoch};
+        }
+
+        // Once armed, the retry timer exclusively owns the transition out of
+        // cooldown. A delayed pump must not reset round accounting or start a
+        // probe before the matching timer handler validates the group.
+        bool waiting_for_cooldown = group->retry_timer != nullptr;
+        const bool round_exhausted = hasDisconnectedLaneLocked(*group) &&
+                                     !hasUntriedDisconnectedLaneLocked(*group);
+        if (!waiting_for_cooldown && !group->queue.empty() &&
+            group->probes_in_flight == 0 && round_exhausted) {
+            const bool cooldown_already_started =
+                group->next_probe_not_before !=
+                std::chrono::steady_clock::time_point{};
+            if (!hasUsableLaneLocked(*group) && !cooldown_already_started) {
+                failed.swap(group->queue);
+                clearQueuedBytesLocked(*group);
+                enterReconnectCooldownLocked(*group);
+                failure_reason = WorkFailureReason::CONNECT_FAILED;
+                queue_detached_after_scheduling = true;
+            } else if (group->next_probe_not_before ==
+                       std::chrono::steady_clock::time_point{}) {
+                enterReconnectCooldownLocked(*group);
+            }
+            if (std::chrono::steady_clock::now() <
+                group->next_probe_not_before) {
+                if (armRetryTimerLocked(group)) {
+                    waiting_for_cooldown = true;
+                    retry_armed = group->retry_timer != nullptr;
+                } else {
+                    failed.swap(group->queue);
+                    clearQueuedBytesLocked(*group);
+                    failure_reason = WorkFailureReason::RUNTIME_UNAVAILABLE;
+                    queue_detached_after_scheduling = true;
+                }
+            } else {
+                beginConnectRoundLocked(*group);
+            }
+        }
+
+        // A lane-local failure may defer only connection probes while healthy
+        // siblings continue pulling work above. Reuse the per-group timer so
+        // repeated failures cannot create a tight reconnect loop.
+        if (!waiting_for_cooldown && failed.empty() && !group->queue.empty() &&
+            group->probes_in_flight == 0 &&
+            std::chrono::steady_clock::now() < group->next_probe_not_before &&
+            armRetryTimerLocked(group)) {
+            waiting_for_cooldown = group->retry_timer != nullptr;
+            retry_armed = waiting_for_cooldown;
+        }
+
+        if (!waiting_for_cooldown && failed.empty()) {
+            const size_t probe_limit =
+                std::min(group->lanes.size(), kMaxConcurrentLaneProbes);
+            while (!group->queue.empty() &&
+                   group->probes_in_flight < probe_limit) {
+                auto lane_it = std::find_if(
+                    group->lanes.begin(), group->lanes.end(),
+                    [&group](const auto& lane) {
+                        return lane->state == LaneState::DISCONNECTED &&
+                               lane->last_connect_round != group->connect_round;
+                    });
+                if (lane_it == group->lanes.end()) break;
+
+                auto lane = *lane_it;
+                lane->state = LaneState::CONNECTING;
+                lane->connect_stage = LaneConnectStage::NONE;
+                lane->last_connect_round = group->connect_round;
+                ++lane->operation_epoch;
+                if (lane->operation_epoch == 0) ++lane->operation_epoch;
+                ++group->probes_in_flight;
+                connects[connect_count++] = {lane, lane->operation_epoch};
+            }
+
+            if (!group->queue.empty() && group->probes_in_flight == 0 &&
+                hasDisconnectedLaneLocked(*group) &&
+                !hasUntriedDisconnectedLaneLocked(*group)) {
+                if (!hasUsableLaneLocked(*group)) {
+                    failed.swap(group->queue);
+                    clearQueuedBytesLocked(*group);
+                    enterReconnectCooldownLocked(*group);
+                    queue_detached_after_scheduling = true;
+                } else {
+                    enterReconnectCooldownLocked(*group);
+                }
+                cooldown_started = true;
+            }
+        }
+
+        promoted += promotePendingAdmissionsLocked(*group);
+        refreshAdmissionTimerLocked(group, runtime_failed,
+                                    admission_timer_to_cancel,
+                                    admission_timer_armed);
+        pending_depth = group->pending_admissions.size();
+        if (queue_detached_after_scheduling && !group->queue.empty())
+            followup_pump_epoch = requestGroupPumpLocked(*group);
+    }
+
+    cancelTimerNoThrow(admission_timer_to_cancel);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (retry_armed) invokeLaneObserverHook(kLaneRetryArmed, 0, 0, 0, false);
+    if (cooldown_started)
+        invokeLaneObserverHook(kLaneCooldownStarted, 0, 0, 0, false);
+    if (promoted != 0)
+        invokeLaneObserverHook(kLaneAdmissionPromoted, pending_depth, promoted,
+                               0, false);
+    if (admission_timer_armed)
+        invokeLaneObserverHook(kLaneAdmissionTimerArmed, pending_depth, 0, 0,
+                               false);
+#endif
+    // Dispatch each lane's connect/session onto that lane's shard executor so
+    // its socket I/O runs on the owning io thread. asio::dispatch runs inline
+    // when already on the target executor (the single-shard/N=1 case stays
+    // identical to the historical inline calls) and hops otherwise.
+    for (size_t i = 0; i < connect_count; ++i) {
+        auto connect_lane = connects[i].lane;
+        uint64_t connect_epoch = connects[i].epoch;
+        asio::dispatch(connect_lane->executor,
+                       [group, connect_lane, connect_epoch] {
+                           startLaneConnect(group, connect_lane, connect_epoch);
+                       });
+    }
+    for (size_t i = 0; i < session_count; ++i) {
+        auto session_lane = sessions[i].lane;
+        uint64_t session_epoch = sessions[i].epoch;
+        asio::dispatch(session_lane->executor,
+                       [group, session_lane, session_epoch] {
+                           startLaneSession(group, session_lane, session_epoch);
+                       });
+    }
+    failWorkItems(std::move(failed), failure_reason, group->failure_counters);
+    failWorkItems(std::move(expired), WorkFailureReason::QUEUE_TIMEOUT,
+                  group->failure_counters);
+    failWorkItems(std::move(runtime_failed),
+                  WorkFailureReason::RUNTIME_UNAVAILABLE,
+                  group->failure_counters);
+    if (followup_pump_epoch != 0) postGroupPump(group, followup_pump_epoch);
+    scheduleGroupRetirement(group);
+}
+
+void TcpTransport::startLaneConnect(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch) {
+    std::string initiation_error;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    size_t queue_depth = 0;
+    uint64_t queued_bytes = 0;
+    size_t active_sockets = 0;
+#endif
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            lane->state != LaneState::CONNECTING ||
+            lane->operation_epoch != epoch) {
+            return;
+        }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        if (invokeLaneConnectFailureInjectionHook(lane->lane_id)) {
+            initiation_error = "injected lane connect failure";
+        } else
+#endif
+            try {
+                lane->resolver =
+                    std::make_shared<asio::ip::tcp::resolver>(lane->executor);
+                lane->socket =
+                    std::make_shared<asio::ip::tcp::socket>(lane->executor);
+                lane->connect_stage = LaneConnectStage::RESOLVING;
+                lane->resolver->async_resolve(
+                    group->key.host, std::to_string(group->key.port),
+                    [group, lane, epoch](
+                        asio::error_code ec,
+                        asio::ip::tcp::resolver::results_type results) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                        invokeLaneConnectHandlerHook();
+#endif
+                        handleLaneResolved(group, lane, epoch, ec,
+                                           std::move(results));
+                    });
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                queue_depth = group->queue.size();
+                queued_bytes = group->queued_bytes;
+                active_sockets = activeSocketCountLocked(*group);
+#endif
+            } catch (const std::exception& e) {
+                initiation_error = e.what();
+            } catch (...) {
+                initiation_error = "unknown exception";
+            }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (initiation_error.empty()) {
+        invokeLaneObserverHook(kLaneConnecting, queue_depth, queued_bytes,
+                               active_sockets, false);
+    }
+#endif
+    if (!initiation_error.empty())
+        handleLaneConnectFailure(group, lane, epoch, initiation_error);
+}
+
+void TcpTransport::handleLaneResolved(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch,
+    asio::error_code ec, asio::ip::tcp::resolver::results_type results) {
+    if (ec) {
+        handleLaneConnectFailure(group, lane, epoch, ec.message());
+        return;
+    }
+
+    std::string initiation_error;
+    [[maybe_unused]] bool stale = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            lane->state != LaneState::CONNECTING ||
+            lane->connect_stage != LaneConnectStage::RESOLVING ||
+            lane->operation_epoch != epoch || !lane->socket) {
+            stale = true;
+        } else {
+            lane->connect_stage = LaneConnectStage::CONNECTING;
+            try {
+                asio::async_connect(
+                    *lane->socket, results,
+                    [group, lane, epoch](asio::error_code connect_ec,
+                                         const asio::ip::tcp::endpoint&) {
+                        handleLaneConnected(group, lane, epoch, connect_ec);
+                    });
+            } catch (const std::exception& e) {
+                initiation_error = e.what();
+            } catch (...) {
+                initiation_error = "unknown exception";
+            }
+        }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (stale) invokeLaneObserverHook(kLaneLateHandler, 0, 0, 0, false);
+#endif
+    if (!initiation_error.empty())
+        handleLaneConnectFailure(group, lane, epoch, initiation_error);
+}
+
+void TcpTransport::handleLaneConnected(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch,
+    asio::error_code ec) {
+    if (ec) {
+        handleLaneConnectFailure(group, lane, epoch, ec.message());
+        return;
+    }
+
+    uint64_t pump_epoch = 0;
+    [[maybe_unused]] bool stale = false;
+    std::string option_error;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            lane->state != LaneState::CONNECTING ||
+            lane->connect_stage != LaneConnectStage::CONNECTING ||
+            lane->operation_epoch != epoch || !lane->socket) {
+            stale = true;
+        } else {
+            asio::error_code option_ec;
+            lane->socket->set_option(asio::ip::tcp::no_delay(true), option_ec);
+            if (option_ec) {
+                option_error = option_ec.message();
+            } else {
+                if (group->probes_in_flight != 0) --group->probes_in_flight;
+                group->connect_round_had_success = true;
+                lane->resolver.reset();
+                lane->connect_stage = LaneConnectStage::NONE;
+                lane->state = LaneState::IDLE;
+                pump_epoch = requestGroupPumpLocked(*group);
+            }
+        }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (stale) invokeLaneObserverHook(kLaneLateHandler, 0, 0, 0, false);
+#endif
+    if (!option_error.empty()) {
+        handleLaneConnectFailure(group, lane, epoch, option_error);
+    } else if (pump_epoch != 0) {
+        postGroupPump(group, pump_epoch);
+    }
+    scheduleGroupRetirement(group);
+}
+
+void TcpTransport::handleLaneConnectFailure(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch,
+    const std::string& error) {
+    std::shared_ptr<asio::ip::tcp::resolver> resolver;
+    std::shared_ptr<asio::ip::tcp::socket> socket;
+    std::deque<TcpWorkItem> failed;
+    std::deque<TcpWorkItem> expired;
+    std::deque<TcpWorkItem> runtime_failed;
+    std::shared_ptr<asio::steady_timer> admission_timer_to_cancel;
+    uint64_t pump_epoch = 0;
+    [[maybe_unused]] size_t promoted = 0;
+    [[maybe_unused]] size_t pending_depth = 0;
+    bool stale = false;
+    [[maybe_unused]] bool cooldown_started = false;
+    [[maybe_unused]] bool admission_timer_armed = false;
+    uint64_t connect_failure_log_count = 0;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (lane->state != LaneState::CONNECTING ||
+            lane->operation_epoch != epoch) {
+            stale = true;
+        } else {
+            connect_failure_log_count = ++group->connect_failure_log_count;
+            if (group->probes_in_flight != 0) --group->probes_in_flight;
+            resolver = std::move(lane->resolver);
+            socket = std::move(lane->socket);
+            lane->connect_stage = LaneConnectStage::NONE;
+            lane->state = group->state == GroupState::OPEN
+                              ? LaneState::DISCONNECTED
+                              : LaneState::CLOSING;
+
+            const bool sibling_usable =
+                group->state == GroupState::OPEN && hasUsableLaneLocked(*group);
+
+            if (group->state == GroupState::OPEN && !group->queue.empty() &&
+                !sibling_usable && group->probes_in_flight == 0 &&
+                !hasUntriedDisconnectedLaneLocked(*group)) {
+                failed.swap(group->queue);
+                clearQueuedBytesLocked(*group);
+                enterReconnectCooldownLocked(*group);
+                cooldown_started = true;
+                expirePendingAdmissionsLocked(
+                    *group, std::chrono::steady_clock::now(), expired);
+                promoted = promotePendingAdmissionsLocked(*group);
+                refreshAdmissionTimerLocked(group, runtime_failed,
+                                            admission_timer_to_cancel,
+                                            admission_timer_armed);
+                pending_depth = group->pending_admissions.size();
+                pump_epoch = requestGroupPumpLocked(*group);
+            } else {
+                pump_epoch = requestGroupPumpLocked(*group);
+            }
+        }
+    }
+
+    if (resolver) {
+        try {
+            resolver->cancel();
+        } catch (...) {
+        }
+    }
+    closeSocketNoThrow(socket);
+    cancelTimerNoThrow(admission_timer_to_cancel);
+    if (!stale && shouldLogOccurrence(connect_failure_log_count)) {
+        LOG(ERROR) << "TCP lane connection to " << group->key.host << ":"
+                   << group->key.port << " failed: " << error
+                   << " (attempt failure " << connect_failure_log_count << ")";
+    }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (stale) invokeLaneObserverHook(kLaneLateHandler, 0, 0, 0, false);
+    if (cooldown_started)
+        invokeLaneObserverHook(kLaneCooldownStarted, 0, 0, 0, false);
+    if (promoted != 0)
+        invokeLaneObserverHook(kLaneAdmissionPromoted, pending_depth, promoted,
+                               0, false);
+    if (admission_timer_armed)
+        invokeLaneObserverHook(kLaneAdmissionTimerArmed, pending_depth, 0, 0,
+                               false);
+#endif
+    failWorkItems(std::move(failed), WorkFailureReason::CONNECT_FAILED,
+                  group->failure_counters);
+    failWorkItems(std::move(expired), WorkFailureReason::QUEUE_TIMEOUT,
+                  group->failure_counters);
+    failWorkItems(std::move(runtime_failed),
+                  WorkFailureReason::RUNTIME_UNAVAILABLE,
+                  group->failure_counters);
+    if (pump_epoch != 0) postGroupPump(group, pump_epoch);
+    scheduleGroupRetirement(group);
+}
+
+void TcpTransport::startLaneSession(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch) {
+    std::string initiation_error;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    size_t queue_depth = 0;
+    uint64_t queued_bytes = 0;
+    size_t active_sockets = 0;
+#endif
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            lane->state != LaneState::BUSY || lane->operation_epoch != epoch ||
+            !lane->current) {
+            return;
+        }
+        if (!lane->socket || !lane->socket->is_open()) {
+            initiation_error = "lane socket is not open";
+        } else {
+            // This function runs on the TCP executor. Keep construction and
+            // initial Asio initiation under the group lock so shutdown cannot
+            // invalidate the checked epoch between validation and initiation.
+            // Asio initiating functions do not invoke their completion handler
+            // inline, so this cannot call lane terminal completion under the
+            // mutex.
+            try {
+                std::weak_ptr<PeerConnectionGroup> weak_group(group);
+                std::weak_ptr<ConnectionLane> weak_lane(lane);
+                auto session = std::make_shared<ClientSession>(
+                    lane->socket, lane->current->use_v2,
+                    [weak_group, weak_lane, epoch](TransferStatusEnum status,
+                                                   bool clean) noexcept {
+                        auto callback_group = weak_group.lock();
+                        auto callback_lane = weak_lane.lock();
+                        if (!callback_group || !callback_lane) return;
+                        handleLaneTerminal(callback_group, callback_lane, epoch,
+                                           status, clean);
+                    });
+                lane->session = session;
+                session->initiate(lane->current->slice->source_addr,
+                                  lane->current->slice->tcp.dest_addr,
+                                  lane->current->slice->length,
+                                  lane->current->slice->opcode);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                queue_depth = group->queue.size();
+                queued_bytes = group->queued_bytes;
+                active_sockets = activeSocketCountLocked(*group);
+#endif
+            } catch (const std::exception& e) {
+                lane->session.reset();
+                initiation_error = e.what();
+            } catch (...) {
+                lane->session.reset();
+                initiation_error = "unknown exception";
+            }
+        }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (initiation_error.empty()) {
+        invokeLaneObserverHook(kLaneBusy, queue_depth, queued_bytes,
+                               active_sockets, true);
+    }
+#endif
+    if (!initiation_error.empty()) {
+        LOG(ERROR) << "Failed to start TCP lane session for " << group->key.host
+                   << ":" << group->key.port << ". Error: " << initiation_error;
+        handleLaneTerminal(group, lane, epoch, TransferStatusEnum::FAILED,
+                           false);
+    }
+}
+
+void TcpTransport::handleLaneTerminal(
+    const std::shared_ptr<PeerConnectionGroup>& group,
+    const std::shared_ptr<ConnectionLane>& lane, uint64_t epoch,
+    TransferStatusEnum status, bool connection_clean) noexcept {
+    std::optional<TerminalAction> action;
+    std::shared_ptr<asio::ip::tcp::socket> socket_to_close;
+    bool stale = false;
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (lane->operation_epoch != epoch || lane->state != LaneState::BUSY ||
+            !lane->current) {
+            stale = true;
+        } else {
+            action.emplace(std::move(*lane->current), status, connection_clean);
+            lane->current.reset();
+            lane->session.reset();
+            lane->state = LaneState::COMPLETING;
+            if (!connection_clean || group->state != GroupState::OPEN)
+                socket_to_close = std::move(lane->socket);
+        }
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    if (stale) {
+        invokeLaneObserverHook(kLaneLateHandler, 0, 0, 0, false);
+    }
+#endif
+    if (stale) return;
+
+    if (status != TransferStatusEnum::COMPLETED) {
+        recordWorkFailure(WorkFailureReason::SESSION_FAILED,
+                          group->failure_counters);
+    }
+
+    // A dirty protocol stream must be closed before terminal Slice status is
+    // visible to the caller.
+    closeSocketNoThrow(socket_to_close);
+    completeTerminalAction(std::move(*action));
+
+    uint64_t pump_epoch = 0;
+    std::shared_ptr<asio::ip::tcp::socket> shutdown_socket;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    size_t queue_depth = 0;
+    uint64_t queued_bytes = 0;
+    size_t active_sockets = 0;
+#endif
+    {
+        std::lock_guard<std::mutex> lock(group->mutex);
+        if (group->state != GroupState::OPEN ||
+            lane->operation_epoch != epoch) {
+            lane->state = LaneState::CLOSING;
+            shutdown_socket = std::move(lane->socket);
+        } else if (connection_clean && lane->socket &&
+                   lane->socket->is_open()) {
+            lane->state = LaneState::IDLE;
+        } else {
+            lane->socket.reset();
+            lane->state = LaneState::DISCONNECTED;
+            // Keep this lane marked as tried in the current round. If another
+            // lane is still usable, wait for the group cooldown before a new
+            // round can retry disconnected lanes. If this was the last usable
+            // lane and the round had previously connected successfully, start
+            // a fresh round immediately so queued work is not mistaken for an
+            // all-probes-failed round.
+            const bool sibling_usable = hasUsableLaneLocked(*group);
+            if (sibling_usable) {
+                enterReconnectCooldownLocked(*group);
+            } else if (!group->queue.empty() && group->probes_in_flight == 0 &&
+                       group->connect_round_had_success) {
+                beginConnectRoundLocked(*group);
+            }
+        }
+        pump_epoch = requestGroupPumpLocked(*group);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        queue_depth = group->queue.size();
+        queued_bytes = group->queued_bytes;
+        active_sockets = activeSocketCountLocked(*group);
+#endif
+    }
+    closeSocketNoThrow(shutdown_socket);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    invokeLaneObserverHook(kLaneTerminal, queue_depth, queued_bytes,
+                           active_sockets, false);
+#endif
+    if (pump_epoch != 0) postGroupPump(group, pump_epoch);
+    scheduleGroupRetirement(group);
+}
+
+void TcpTransport::completeTerminalAction(TerminalAction action) noexcept {
+    auto continuation = std::move(action.work.continuation);
+    try {
+        if (action.status == TransferStatusEnum::COMPLETED)
+            action.work.slice->markSuccess();
+        else
+            action.work.slice->markFailed();
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "TCP Slice terminal completion threw: " << e.what();
+    } catch (...) {
+        LOG(ERROR) << "TCP Slice terminal completion threw";
+    }
+
+    if (continuation) {
+        try {
+            continuation();
+        } catch (const std::exception& e) {
+            LOG(ERROR) << "TCP Slice continuation threw: " << e.what();
+        } catch (...) {
+            LOG(ERROR) << "TCP Slice continuation threw";
+        }
+    }
+}
+
+uint64_t TcpTransport::recordWorkFailure(
+    WorkFailureReason reason,
+    const std::shared_ptr<FailureCounters>& counters) noexcept {
+    if (!counters) return 0;
+
+    std::atomic<uint64_t>* counter = nullptr;
+    switch (reason) {
+        case WorkFailureReason::QUEUE_FULL:
+            counter = &counters->queue_full;
+            break;
+        case WorkFailureReason::QUEUE_TIMEOUT:
+            counter = &counters->queue_timeout;
+            break;
+        case WorkFailureReason::RUNTIME_UNAVAILABLE:
+            counter = &counters->runtime_unavailable;
+            break;
+        case WorkFailureReason::CONNECT_FAILED:
+            counter = &counters->connect_failed;
+            break;
+        case WorkFailureReason::SESSION_FAILED:
+            counter = &counters->session_failed;
+            break;
+        case WorkFailureReason::SHUTDOWN:
+            counter = &counters->shutdown;
+            break;
+    }
+    if (!counter) return 0;
+
+    const uint64_t occurrence =
+        counter->fetch_add(1, std::memory_order_relaxed) + 1;
+    if (reason == WorkFailureReason::QUEUE_FULL &&
+        shouldLogOccurrence(occurrence)) {
+        LOG(WARNING) << "TCP lane queue-full rejection count: " << occurrence;
+    }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    invokeLaneFailureReasonHook(static_cast<int>(reason));
+#endif
+    return occurrence;
+}
+
+void TcpTransport::failWorkItem(
+    TcpWorkItem work, WorkFailureReason reason,
+    const std::shared_ptr<FailureCounters>& counters) noexcept {
+    recordWorkFailure(reason, counters);
+    completeTerminalAction(
+        TerminalAction(std::move(work), TransferStatusEnum::FAILED, false));
+}
+
+void TcpTransport::failWorkItems(
+    std::deque<TcpWorkItem> work, WorkFailureReason reason,
+    const std::shared_ptr<FailureCounters>& counters) noexcept {
+    while (!work.empty()) {
+        auto item = std::move(work.front());
+        work.pop_front();
+        failWorkItem(std::move(item), reason, counters);
+    }
+}
+
+void TcpTransport::closeSocketNoThrow(
+    const std::shared_ptr<asio::ip::tcp::socket>& socket) noexcept {
+    if (!socket) return;
+    asio::error_code error;
+    socket->cancel(error);
+    socket->close(error);
+}
+
+void TcpTransport::shutdownConnectionLanes() {
+    const auto state = lane_state_;
+    std::vector<std::shared_ptr<PeerConnectionGroup>> groups;
+    {
+        std::lock_guard<std::mutex> state_lock(state->mutex);
+        if (state->shutting_down) return;
+        state->shutting_down = true;
+        groups.reserve(state->groups.size() + state->retiring_groups.size());
+        for (const auto& entry : state->groups) groups.push_back(entry.second);
+        for (const auto& group : state->retiring_groups)
+            groups.push_back(group);
+    }
+
+    for (const auto& group : groups) {
+        std::deque<TcpWorkItem> accepted_queue;
+        std::deque<TcpWorkItem> accepted_pending;
+        {
+            std::lock_guard<std::mutex> lock(group->mutex);
+            group->state = GroupState::CLOSING;
+            group->pump_scheduled = false;
+            ++group->pump_epoch;
+            accepted_queue.swap(group->queue);
+            accepted_pending.swap(group->pending_admissions);
+            clearQueuedBytesLocked(*group);
+            ++group->retry_epoch;
+            if (group->retry_epoch == 0) ++group->retry_epoch;
+            ++group->admission_epoch;
+            if (group->admission_epoch == 0) ++group->admission_epoch;
+            for (const auto& lane : group->lanes) {
+                ++lane->operation_epoch;
+                if (lane->operation_epoch == 0) ++lane->operation_epoch;
+                if (lane->state != LaneState::CLOSED)
+                    lane->state = LaneState::CLOSING;
+            }
+        }
+        failWorkItems(std::move(accepted_queue), WorkFailureReason::SHUTDOWN,
+                      state->failure_counters);
+        failWorkItems(std::move(accepted_pending), WorkFailureReason::SHUTDOWN,
+                      state->failure_counters);
+    }
+
+    auto cancellation_posts = std::make_shared<LaneCancellationPostTracker>();
+    if (io_pool_ && running_) {
+        struct LaneTeardown {
+            asio::io_context::executor_type executor;
+            std::shared_ptr<ClientSession> session;
+            std::shared_ptr<asio::ip::tcp::resolver> resolver;
+            std::shared_ptr<asio::ip::tcp::socket> socket;
+        };
+        for (const auto& group : groups) {
+            std::vector<LaneTeardown> teardowns;
+            std::shared_ptr<asio::steady_timer> retry_timer;
+            std::shared_ptr<asio::steady_timer> admission_timer;
+            {
+                std::lock_guard<std::mutex> lock(group->mutex);
+                retry_timer = group->retry_timer;
+                admission_timer = group->admission_timer;
+                for (const auto& lane : group->lanes) {
+                    if (lane->session || lane->resolver || lane->socket)
+                        teardowns.push_back({lane->executor, lane->session,
+                                             lane->resolver, lane->socket});
+                }
+            }
+            // Cancel/close each lane's asio objects on the lane's own shard;
+            // the group timers stay on the coordinator (group) executor. Each
+            // post is tracked so waitUntil() waits for all of them. At N=1
+            // asio::dispatch runs inline on the single io thread.
+            for (auto& teardown : teardowns) {
+                cancellation_posts->add();
+                auto session = teardown.session;
+                auto resolver = teardown.resolver;
+                auto socket = teardown.socket;
+                try {
+                    asio::dispatch(
+                        teardown.executor,
+                        [session, resolver, socket, cancellation_posts] {
+                            if (session) session->cancel();
+                            if (resolver) {
+                                try {
+                                    resolver->cancel();
+                                } catch (...) {
+                                }
+                            }
+                            closeSocketNoThrow(socket);
+                            cancellation_posts->done();
+                        });
+                } catch (...) {
+                    cancellation_posts->done();
+                }
+            }
+            if (retry_timer || admission_timer) {
+                cancellation_posts->add();
+                try {
+                    asio::dispatch(
+                        group->executor,
+                        [retry_timer, admission_timer, cancellation_posts] {
+                            if (retry_timer) {
+                                asio::error_code timer_ec;
+                                retry_timer->cancel(timer_ec);
+                            }
+                            cancelTimerNoThrow(admission_timer);
+                            cancellation_posts->done();
+                        });
+                } catch (...) {
+                    cancellation_posts->done();
+                }
+            }
+        }
+        cancellation_posts->waitUntil(std::chrono::steady_clock::now() +
+                                      kShutdownCancellationWait);
+    }
+
+    running_ = false;
+    // Stopping the pool stops every shard io_context and joins every io
+    // thread; after this returns no handler can run, which is the quiescence
+    // barrier for the synchronous teardown below.
+    if (io_pool_) io_pool_->stop();
+
+    std::deque<TcpWorkItem> deferred;
+    std::vector<std::shared_ptr<ClientSession>> sessions;
+    std::vector<std::shared_ptr<asio::ip::tcp::resolver>> resolvers;
+    std::vector<std::shared_ptr<asio::ip::tcp::socket>> sockets;
+    std::vector<std::shared_ptr<asio::steady_timer>> retry_timers;
+    std::vector<std::shared_ptr<asio::steady_timer>> admission_timers;
+
+    for (const auto& group : groups) {
+        {
+            std::lock_guard<std::mutex> lock(group->mutex);
+            if (group->retry_timer)
+                retry_timers.push_back(std::move(group->retry_timer));
+            if (group->admission_timer)
+                admission_timers.push_back(std::move(group->admission_timer));
+            for (const auto& lane : group->lanes) {
+                if (lane->current) {
+                    deferred.emplace_back(std::move(*lane->current));
+                    lane->current.reset();
+                }
+                if (lane->session) sessions.push_back(std::move(lane->session));
+                if (lane->resolver)
+                    resolvers.push_back(std::move(lane->resolver));
+                if (lane->socket) sockets.push_back(std::move(lane->socket));
+                lane->connect_stage = LaneConnectStage::NONE;
+                lane->state = LaneState::CLOSED;
+            }
+            group->probes_in_flight = 0;
+            group->state = GroupState::CLOSED;
+        }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        invokeLaneObserverHook(kLaneShutdownClean, 0, 0, 0, false);
+#endif
+    }
+
+    // No handler is running after join. Reset every Asio-owning field while
+    // TcpContext and its execution_context are still alive, then publish
+    // terminal failure for work that had been BUSY.
+    for (const auto& session : sessions)
+        if (session) session->cancel();
+    for (const auto& resolver : resolvers) {
+        if (!resolver) continue;
+        try {
+            resolver->cancel();
+        } catch (...) {
+        }
+    }
+    for (const auto& socket : sockets) closeSocketNoThrow(socket);
+    for (const auto& timer : retry_timers) {
+        cancelTimerNoThrow(timer);
+    }
+    for (const auto& timer : admission_timers) cancelTimerNoThrow(timer);
+    sessions.clear();
+    resolvers.clear();
+    sockets.clear();
+    retry_timers.clear();
+    admission_timers.clear();
+
+    failWorkItems(std::move(deferred), WorkFailureReason::SHUTDOWN,
+                  state->failure_counters);
+
+    const auto& counters = state->failure_counters;
+    VLOG(1) << "TCP lane failure totals: queue_full="
+            << counters->queue_full.load(std::memory_order_relaxed)
+            << ", queue_timeout="
+            << counters->queue_timeout.load(std::memory_order_relaxed)
+            << ", connect_failed="
+            << counters->connect_failed.load(std::memory_order_relaxed)
+            << ", runtime_unavailable="
+            << counters->runtime_unavailable.load(std::memory_order_relaxed)
+            << ", session_failed="
+            << counters->session_failed.load(std::memory_order_relaxed)
+            << ", shutdown="
+            << counters->shutdown.load(std::memory_order_relaxed);
+
+    {
+        std::lock_guard<std::mutex> state_lock(state->mutex);
+        state->groups.clear();
+        state->current_key_by_peer.clear();
+        state->retiring_groups.clear();
+        state->runtime.reset();
+    }
+    groups.clear();
+    lane_runtime_.reset();
+}
+
+bool TcpTransport::validateAddress(uint64_t addr, uint64_t size) const {
+    return validateTcpAddress(metadata_, addr, size);
+}
diff --git a/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_session_impl.h b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_session_impl.h
new file mode 100644
index 0000000000..40a1c4c3ca
--- /dev/null
+++ b/mooncake-transfer-engine/src/transport/tcp_transport/tcp_transport_session_impl.h
@@ -0,0 +1,982 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+// Private implementation fragment included by tcp_transport.cpp from inside
+// namespace mooncake. Keeping the protocol/session state here makes the public
+// transport entry points and the lane scheduler independently reviewable
+// without changing linkage or lifetime behavior.
+
+static size_t getChunkSize() {
+    static const size_t val = [] {
+        const char* env = std::getenv("MC_TCP_SLICE_SIZE");
+        if (env) {
+            try {
+                size_t v = std::stoull(env);
+                if (v > 0) return v;
+                LOG(WARNING)
+                    << "Ignore non-positive MC_TCP_SLICE_SIZE value: " << env
+                    << ", using default 65536";
+            } catch (const std::exception& e) {
+                // A non-numeric or out-of-range value makes std::stoull throw;
+                // fall through to the default instead of letting the exception
+                // propagate out of this static initializer and abort the
+                // transfer that first reads the chunk size.
+                LOG(WARNING)
+                    << "Invalid MC_TCP_SLICE_SIZE value: " << env
+                    << ". Error: " << e.what() << ", using default 65536";
+            }
+        }
+        return size_t(65536);  // 64KB default
+    }();
+    return val;
+}
+
+struct SessionHeader {
+    uint64_t size;
+    uint64_t addr;
+    uint8_t opcode;
+};
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+// Returns the CUDA device ordinal if addr is device memory, or -1 otherwise.
+// Callers must call cudaSetDevice before any cudaMemcpy to avoid implicit
+// GPU 0 context creation.
+static int getCudaDeviceId(void* addr) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    recordStagingDeviceQueryForTest();
+#endif
+    cudaPointerAttributes attributes;
+    auto status = cudaPointerGetAttributes(&attributes, addr);
+    if (status != cudaSuccess) return -1;
+    if (attributes.type == cudaMemoryTypeDevice) return attributes.device;
+    return -1;
+}
+
+class TcpStagingBuffer {
+   public:
+    char* ensure(size_t size) {
+        if (buffer_.size() < size) {
+            buffer_.resize(size);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+            recordStagingBufferAllocationForTest();
+#endif
+        }
+        return buffer_.data();
+    }
+
+   private:
+    std::vector<char> buffer_;
+};
+
+#ifdef USE_MACA
+static cudaError_t copyTcpCudaMemory(void* dst, const void* src, size_t size) {
+    cudaStream_t stream;
+    cudaError_t status =
+        cudaStreamCreateWithFlags(&stream, cudaStreamNonBlocking);
+    if (status != cudaSuccess) return status;
+
+    status = cudaMemcpyAsync(dst, src, size, cudaMemcpyDefault, stream);
+    if (status == cudaSuccess) {
+        status = cudaStreamSynchronize(stream);
+    }
+
+    cudaError_t destroy_status = cudaStreamDestroy(stream);
+    return status == cudaSuccess ? destroy_status : status;
+}
+#endif
+#endif
+
+// Forward declaration
+class TcpTransport;
+
+using ValidateAddrFn = std::function<bool(uint64_t, uint64_t)>;
+
+// --- Acknowledged framing (protocol v2, #2086) ------------------------------
+// v1 framing gives the initiator no channel to learn whether the receiver
+// applied (or even accepted) a WRITE: COMPLETED fires when the final chunk
+// enters the initiator's kernel socket buffer, while megabytes may still be
+// in flight toward destination memory, and a rejected request is silently
+// "successful". v2 requests set the high bit of the opcode; the server then
+// (a) prefixes every READ response with an 8-byte status frame and (b) sends
+// an 8-byte status frame for WRITE only after the final chunk has been
+// applied to destination memory. Initiators enable v2 only when the target
+// segment advertises tcp_proto_version >= 2, so old servers never see
+// flagged opcodes and old initiators keep receiving v1 framing.
+static constexpr uint8_t kOpcodeV2Flag = 0x80;
+// Status frames carry a magic in the high 32 bits so that a v2 initiator
+// which reaches a v1 server through a stale descriptor (v1 treats unknown
+// opcodes as READ and immediately streams payload bytes) fails fast on the
+// first frame instead of misinterpreting the stream. Residual risk: payload
+// bytes that happen to equal a valid frame (2^-64 per request, data
+// dependent) are indistinguishable in-band; eliminating that would need a
+// nonce/checksum handshake, which this deliberately avoids.
+static constexpr uint64_t kStatusMagic = 0x4D435456ull << 32;  // "MCTV"
+static constexpr uint64_t kStatusOk = kStatusMagic | 0;
+static constexpr uint64_t kStatusAddrRejected = kStatusMagic | 1;
+static inline bool statusFrameValid(uint64_t frame) {
+    return (frame & 0xFFFFFFFF00000000ull) == kStatusMagic;
+}
+
+// Operational escape hatch: MC_TCP_PROTO=1 forces initiators to speak the
+// legacy unacknowledged framing even to v2-capable servers. Also used by
+// tests to cover the mixed-version matrix in one process.
+static bool forceLegacyTcpProto() {
+    // Read per call (startTransfer already does metadata lookups; getenv is
+    // noise) so tests can cover both protocol modes in one process.
+    const char* env = std::getenv("MC_TCP_PROTO");
+    return env && env[0] == '1' && env[1] == '\0';
+}
+
+// Server-side session: handles transfer requests on a persistent connection.
+// The session owns the socket; ending the callback chain without rearming
+// (start()/next handler) drops the last reference and closes the connection.
+struct ServerSession : public std::enable_shared_from_this<ServerSession> {
+    explicit ServerSession(std::shared_ptr<tcpsocket> socket,
+                           ValidateAddrFn validate_addr)
+        : socket_(std::move(socket)),
+          validate_addr_(std::move(validate_addr)) {}
+
+    std::shared_ptr<tcpsocket> socket_;
+    ValidateAddrFn validate_addr_;
+    SessionHeader header_;
+    uint64_t total_transferred_bytes_;
+    char* local_buffer_;
+    bool v2_ = false;
+    uint64_t status_frame_;
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+    int cuda_device_ = -1;
+    TcpStagingBuffer staging_buffer_;
+#endif
+
+    void start() {
+        total_transferred_bytes_ = 0;
+        readHeader();
+    }
+
+   private:
+    // Send an 8-byte status frame, then run `next` (or end the session —
+    // closing the connection — when `next` is empty or the send fails).
+    void sendStatus(uint64_t status, std::function<void()> next) {
+        status_frame_ = htole64(status);
+        auto self(shared_from_this());
+        asio::async_write(*socket_,
+                          asio::buffer(&status_frame_, sizeof(status_frame_)),
+                          [this, self, next = std::move(next)](
+                              const asio::error_code& ec, std::size_t) {
+                              if (ec)
+                                  return;  // connection closes with the session
+                              if (next) next();
+                          });
+    }
+
+    void readHeader() {
+        auto self(shared_from_this());
+        asio::async_read(
+            *socket_, asio::buffer(&header_, sizeof(SessionHeader)),
+            [this, self](const asio::error_code& ec, std::size_t len) {
+                if (ec || len != sizeof(SessionHeader)) {
+                    if (ec.value() != asio::error::eof) {
+                        LOG(WARNING)
+                            << "ServerSession::readHeader failed. Error: "
+                            << ec.message() << " (value: " << ec.value() << ")"
+                            << ", bytes read: " << len;
+                    }
+                    return;
+                }
+
+                v2_ = (header_.opcode & kOpcodeV2Flag) != 0;
+                const uint8_t opcode = header_.opcode & ~kOpcodeV2Flag;
+                local_buffer_ = (char*)(le64toh(header_.addr));
+                uint64_t size = le64toh(header_.size);
+                if (validate_addr_ &&
+                    !validate_addr_((uint64_t)local_buffer_, size)) {
+                    LOG(ERROR) << "ServerSession: remote-supplied address 0x"
+                               << std::hex << (uint64_t)local_buffer_
+                               << std::dec << " with size " << size
+                               << " is not within any registered buffer";
+                    // v2 initiators learn of the rejection; v1 initiators
+                    // only see the connection close (and, for small WRITEs,
+                    // may have already reported success — the defect v2
+                    // exists to fix).
+                    if (v2_) sendStatus(kStatusAddrRejected, nullptr);
+                    return;
+                }
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+                cuda_device_ = getCudaDeviceId(local_buffer_);
+#endif
+                if (opcode == (uint8_t)TransferRequest::WRITE) {
+                    readBody();
+                } else if (v2_) {
+                    // READ, v2: status frame precedes the data.
+                    sendStatus(kStatusOk, [this] { writeBody(); });
+                } else {
+                    writeBody();
+                }
+            });
+    }
+
+    void writeBody() {
+        auto self(shared_from_this());
+        uint64_t size = le64toh(header_.size);
+        char* addr = local_buffer_;
+
+        size_t buffer_size =
+            std::min(getChunkSize(), size - total_transferred_bytes_);
+        if (buffer_size == 0) {
+            // Transfer complete, wait for next request on this connection
+            start();
+            return;
+        }
+
+        char* dram_buffer = addr + total_transferred_bytes_;
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+        if (cuda_device_ >= 0) {
+            dram_buffer = staging_buffer_.ensure(buffer_size);
+            cudaSetDevice(cuda_device_);
+#ifdef USE_MACA
+            cudaError_t cuda_status = copyTcpCudaMemory(
+                dram_buffer, addr + total_transferred_bytes_, buffer_size);
+#else
+            cudaError_t cuda_status =
+                cudaMemcpy(dram_buffer, addr + total_transferred_bytes_,
+                           buffer_size, cudaMemcpyDefault);
+#endif
+            if (cuda_status != cudaSuccess) {
+                LOG(ERROR) << "ServerSession::writeBody failed to copy from "
+                              "CUDA memory. "
+                           << "Error: " << cudaGetErrorString(cuda_status);
+                return;  // Connection will be closed
+            }
+        }
+#endif
+
+        asio::async_write(
+            *socket_, asio::buffer(dram_buffer, buffer_size),
+            [this, addr, dram_buffer, self](const asio::error_code& ec,
+                                            std::size_t transferred_bytes) {
+                if (ec) {
+                    LOG(ERROR)
+                        << "ServerSession::writeBody failed. "
+                        << "Attempt to write data " << static_cast<void*>(addr)
+                        << " using buffer " << static_cast<void*>(dram_buffer)
+                        << ". Error: " << ec.message()
+                        << " (value: " << ec.value() << ")";
+                    return;  // Connection will be closed
+                }
+                total_transferred_bytes_ += transferred_bytes;
+                writeBody();
+            });
+    }
+
+    void readBody() {
+        auto self(shared_from_this());
+        uint64_t size = le64toh(header_.size);
+        char* addr = local_buffer_;
+
+        size_t buffer_size =
+            std::min(getChunkSize(), size - total_transferred_bytes_);
+        if (buffer_size == 0) {
+            // Destination memory now holds the complete payload. Under v2,
+            // acknowledge before accepting the next request — this is what
+            // makes the initiator's COMPLETED mean "applied at the
+            // destination" rather than "left my socket buffer".
+            if (v2_) {
+                sendStatus(kStatusOk, [this] { start(); });
+            } else {
+                start();
+            }
+            return;
+        }
+
+        char* dram_buffer = addr + total_transferred_bytes_;
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+        if (cuda_device_ >= 0) {
+            dram_buffer = staging_buffer_.ensure(buffer_size);
+        }
+#endif
+
+        asio::async_read(
+            *socket_, asio::buffer(dram_buffer, buffer_size),
+            [this, addr, dram_buffer, self](const asio::error_code& ec,
+                                            std::size_t transferred_bytes) {
+                if (ec) {
+                    // If client closed connection (EOF), this is normal - don't
+                    // log
+                    if (ec.value() != asio::error::eof) {
+                        LOG(WARNING)
+                            << "ServerSession::readBody failed. "
+                            << "Attempt to read data "
+                            << static_cast<void*>(addr) << " using buffer "
+                            << static_cast<void*>(dram_buffer)
+                            << ". Error: " << ec.message()
+                            << " (value: " << ec.value() << ")";
+                    }
+                    return;  // Connection will be closed
+                }
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+                if (cuda_device_ >= 0) {
+                    cudaSetDevice(cuda_device_);
+#ifdef USE_MACA
+                    cudaError_t cuda_status =
+                        copyTcpCudaMemory(addr + total_transferred_bytes_,
+                                          dram_buffer, transferred_bytes);
+#else
+                    cudaError_t cuda_status =
+                        cudaMemcpy(addr + total_transferred_bytes_, dram_buffer,
+                                   transferred_bytes, cudaMemcpyDefault);
+#endif
+                    if (cuda_status != cudaSuccess) {
+                        LOG(ERROR)
+                            << "ServerSession::readBody failed to copy to CUDA "
+                               "memory. "
+                            << "Error: " << cudaGetErrorString(cuda_status);
+                        return;  // Connection will be closed
+                    }
+                }
+#endif
+                total_transferred_bytes_ += transferred_bytes;
+                readBody();
+            });
+    }
+};
+
+// Client-side session: initiates one transfer request
+struct ClientSession : public std::enable_shared_from_this<ClientSession> {
+    using OnTerminal =
+        std::function<void(TransferStatusEnum, bool connection_clean)>;
+
+    explicit ClientSession(std::shared_ptr<tcpsocket> socket, bool use_v2,
+                           OnTerminal on_terminal)
+        : socket_(std::move(socket)),
+          v2_(use_v2),
+          on_terminal_(std::move(on_terminal)) {}
+
+    std::shared_ptr<tcpsocket> socket_;
+    SessionHeader header_;
+    uint64_t total_transferred_bytes_;
+    char* local_buffer_;
+    bool v2_;
+    uint64_t status_frame_;
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+    int cuda_device_ = -1;
+    TcpStagingBuffer staging_buffer_;
+#endif
+    // v2 WRITE runs the body stream and the ack read concurrently (one
+    // async op per direction; handlers serialize on the io thread). The
+    // concurrent read lets a rejection — or a v1 server's bogus payload —
+    // abort a large in-flight WRITE instead of deadlocking on mutually
+    // full socket buffers, and delivers rejection frames before the close.
+    bool write_body_done_ = false;
+    bool write_acked_ok_ = false;
+    // An early negative/malformed ack can arrive while asio::async_write still
+    // owns a buffer pointing into the caller's source memory. Do not publish a
+    // terminal status until that body operation has completed or been
+    // cancelled: callers are allowed to release the source buffer as soon as
+    // the transfer becomes terminal.
+    bool write_body_in_flight_ = false;
+    bool write_abort_requested_ = false;
+    // A v2 status frame is prompt by construction: a READ status precedes
+    // any payload, and a WRITE ack follows at most one chunk's apply after
+    // the body is done. The only peer that never sends one is a legacy
+    // server reached through a stale v2 descriptor — and for requests
+    // shorter than a frame it also keeps the connection open (it streamed
+    // size < 8 bytes of "READ payload" and is waiting for our next header),
+    // so without a deadline both sides wait forever. Bound that wait; the
+    // default is generous so no healthy slow path can trip it, since it only
+    // covers the frame itself, never payload streaming.
+    static int statusFrameTimeoutSec() {
+        const char* env = std::getenv("MC_TCP_STATUS_TIMEOUT_SEC");
+        if (env) {
+            int v = std::atoi(env);
+            if (v > 0) return v;
+        }
+        return 30;
+    }
+    std::optional<asio::steady_timer> status_timer_;
+    bool status_deadline_disarmed_ = false;
+    // Unlike the status-frame deadline above, this is a sliding liveness
+    // deadline for the whole request. It is refreshed only after an Asio
+    // completion reports actual protocol or payload progress.
+    static int progressTimeoutSec() {
+        const char* env = std::getenv("MC_TCP_PROGRESS_TIMEOUT_SEC");
+        if (env) {
+            int v = std::atoi(env);
+            if (v > 0) return v;
+        }
+        return 30;
+    }
+    std::optional<asio::steady_timer> progress_timer_;
+    uint64_t progress_epoch_ = 0;
+    bool progress_deadline_disarmed_ = true;
+    bool progress_timeout_committed_ = false;
+    bool terminal_reported_ = false;
+    OnTerminal on_terminal_;
+
+    void initiate(void* buffer, uint64_t dest_addr, size_t size,
+                  TransferRequest::OpCode opcode) {
+        local_buffer_ = (char*)buffer;
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+        cuda_device_ = getCudaDeviceId(local_buffer_);
+#endif
+        header_.addr = htole64(dest_addr);
+        header_.size = htole64(size);
+        header_.opcode = (uint8_t)opcode | (v2_ ? kOpcodeV2Flag : 0);
+        total_transferred_bytes_ = 0;
+        writeHeader();
+    }
+
+    void cancel() noexcept {
+        cancelStatusDeadline();
+        cancelProgressDeadline();
+        if (!socket_) return;
+        asio::error_code cancel_ec;
+        socket_->cancel(cancel_ec);
+        asio::error_code close_ec;
+        socket_->close(close_ec);
+    }
+
+   private:
+    // The status-frame deadline is separate from the sliding progress
+    // deadline below. Its expiry closes the socket, but a status completion
+    // already ready in the executor queue retains its original result; the
+    // status handler still owns the terminal path.
+    void armStatusDeadline() {
+        auto self(shared_from_this());
+        status_deadline_disarmed_ = false;
+        status_timer_.emplace(socket_->get_executor());
+        status_timer_->expires_after(
+            std::chrono::seconds(statusFrameTimeoutSec()));
+        status_timer_->async_wait([this, self](const asio::error_code& ec) {
+            // The disarmed flag also covers an expiry that was already
+            // queued when cancel() ran (cancel cannot revoke those, and by
+            // then the socket may have been re-pooled).
+            if (ec == asio::error::operation_aborted ||
+                status_deadline_disarmed_) {
+                return;
+            }
+            LOG(ERROR) << "ClientSession: no status frame within "
+                       << statusFrameTimeoutSec()
+                       << "s (peer likely speaks the legacy protocol); "
+                          "dropping connection";
+            if (socket_ && socket_->is_open()) {
+                asio::error_code cec;
+                socket_->close(cec);
+            }
+        });
+    }
+
+    void cancelStatusDeadline() {
+        status_deadline_disarmed_ = true;
+        if (status_timer_) {
+            asio::error_code ec;
+            status_timer_->cancel(ec);
+        }
+    }
+
+    void refreshProgressDeadline() {
+        if (terminal_reported_ || progress_timeout_committed_) return;
+        auto self(shared_from_this());
+        progress_deadline_disarmed_ = false;
+        ++progress_epoch_;
+        if (progress_epoch_ == 0) ++progress_epoch_;
+        const uint64_t progress_epoch = progress_epoch_;
+        if (!progress_timer_) progress_timer_.emplace(socket_->get_executor());
+        progress_timer_->expires_after(
+            std::chrono::seconds(progressTimeoutSec()));
+        progress_timer_->async_wait(
+            [this, self, progress_epoch](const asio::error_code& ec) {
+                handleProgressDeadline(progress_epoch, ec);
+            });
+    }
+
+    void handleProgressDeadline(uint64_t progress_epoch,
+                                const asio::error_code& ec) {
+        if (ec == asio::error::operation_aborted ||
+            progress_deadline_disarmed_ || terminal_reported_ ||
+            progress_epoch != progress_epoch_) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+            (void)invokeSessionProgressHook(kSessionTimeoutStale, false);
+#endif
+            return;
+        }
+        progress_timeout_committed_ = true;
+        progress_deadline_disarmed_ = true;
+        ++progress_epoch_;
+        if (progress_epoch_ == 0) ++progress_epoch_;
+        if ((header_.opcode & ~kOpcodeV2Flag) ==
+            static_cast<uint8_t>(TransferRequest::WRITE)) {
+            write_abort_requested_ = true;
+        }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        (void)invokeSessionProgressHook(kSessionTimeoutCommitted,
+                                        write_body_in_flight_);
+#endif
+        LOG(ERROR) << "ClientSession: no transfer progress within "
+                   << progressTimeoutSec() << "s; dropping connection";
+        if (socket_ && socket_->is_open()) {
+            asio::error_code cancel_ec;
+            socket_->cancel(cancel_ec);
+            asio::error_code close_ec;
+            socket_->close(close_ec);
+        }
+    }
+
+    bool acceptProgress() {
+        if (progress_timeout_committed_) return false;
+        refreshProgressDeadline();
+        return !progress_timeout_committed_;
+    }
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    bool acceptProgressForTest(int event) {
+        const uint64_t previous_epoch = progress_epoch_;
+        const int action = invokeSessionProgressHook(event, false);
+        if (action == kSessionCommitTimeoutBeforeProgress)
+            handleProgressDeadline(previous_epoch, asio::error_code{});
+        if (!acceptProgress()) return false;
+        if (action == kSessionReplayPreviousTimeoutAfterProgress)
+            handleProgressDeadline(previous_epoch, asio::error_code{});
+        return !progress_timeout_committed_;
+    }
+#endif
+
+    void cancelProgressDeadline() {
+        progress_deadline_disarmed_ = true;
+        ++progress_epoch_;
+        if (progress_epoch_ == 0) ++progress_epoch_;
+        if (progress_timer_) {
+            asio::error_code ec;
+            progress_timer_->cancel(ec);
+        }
+    }
+
+    // Single terminal path. The invoking Asio operation has already released
+    // its buffer before entering its completion handler. The lane posts any
+    // follow-up pump, so a clean socket cannot be reused inline here.
+    void finalize(TransferStatusEnum status, bool clean) {
+        if (terminal_reported_) return;
+        terminal_reported_ = true;
+        cancelStatusDeadline();
+        cancelProgressDeadline();
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        (void)invokeSessionProgressHook(kSessionTerminal, clean);
+#endif
+        auto on_terminal = std::move(on_terminal_);
+        if (on_terminal) on_terminal(status, clean);
+    }
+
+    // Abort a v2 WRITE and cancel any body operation. If asio still owns the
+    // current source buffer, its completion handler is responsible for
+    // finalizing after the buffer is quiescent.
+    void abortWrite() {
+        write_abort_requested_ = true;
+        if (socket_ && socket_->is_open()) {
+            asio::error_code ec;
+            socket_->close(ec);
+        }
+        if (!write_body_in_flight_) finalize(TransferStatusEnum::FAILED, false);
+    }
+
+    void writeHeader() {
+        auto self(shared_from_this());
+        asio::async_write(
+            *socket_, asio::buffer(&header_, sizeof(SessionHeader)),
+            [this, self](const asio::error_code& ec, std::size_t len) {
+                if (ec || len != sizeof(SessionHeader)) {
+                    LOG(ERROR)
+                        << "ClientSession::writeHeader failed. Error: "
+                        << ec.message() << " (value: " << ec.value() << ")"
+                        << ", bytes written: " << len;
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                if (!acceptProgress()) {
+                    if ((header_.opcode & ~kOpcodeV2Flag) ==
+                        static_cast<uint8_t>(TransferRequest::WRITE)) {
+                        abortWrite();
+                    } else {
+                        finalize(TransferStatusEnum::FAILED, false);
+                    }
+                    return;
+                }
+                if ((header_.opcode & ~kOpcodeV2Flag) ==
+                    (uint8_t)TransferRequest::WRITE) {
+                    if (v2_) readWriteAck();  // concurrent with the body
+                    writeBody();
+                } else if (v2_) {
+                    readReadStatus();
+                } else {
+                    readBody();
+                }
+            });
+        // Asio does not invoke the completion handler inline. Arm only after
+        // initiation succeeds so a synchronous initiation exception cannot
+        // leave a timer handler retaining this otherwise-abandoned session.
+        refreshProgressDeadline();
+    }
+
+    // v2 READ: the server prefixes the data with a status frame.
+    void readReadStatus() {
+        auto self(shared_from_this());
+        armStatusDeadline();
+        asio::async_read(
+            *socket_, asio::buffer(&status_frame_, sizeof(status_frame_)),
+            [this, self](const asio::error_code& ec, std::size_t len) {
+                cancelStatusDeadline();
+                if (ec || len != sizeof(status_frame_)) {
+                    LOG(ERROR)
+                        << "ClientSession: failed to read READ status "
+                           "frame. Error: "
+                        << ec.message() << " (value: " << ec.value() << ")";
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                if (!acceptProgress()) {
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                uint64_t frame = le64toh(status_frame_);
+                if (!statusFrameValid(frame)) {
+                    LOG(ERROR) << "ClientSession: malformed READ status "
+                                  "frame (peer likely speaks the legacy "
+                                  "protocol); dropping connection";
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                if (frame != kStatusOk) {
+                    LOG(ERROR) << "ClientSession: READ rejected by server, "
+                                  "status "
+                               << (frame & 0xFFFFFFFFull);
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                readBody();
+            });
+    }
+
+    // v2 WRITE: completion is the server's acknowledgment that the payload
+    // has been applied to destination memory. Armed concurrently with the
+    // body stream; a well-behaved v2 server only sends the frame after the
+    // final chunk, so a frame arriving before the body is done is either a
+    // rejection or a legacy peer's payload — both close the socket immediately
+    // and publish failure only after the outstanding body write is quiescent.
+    void readWriteAck() {
+        auto self(shared_from_this());
+        asio::async_read(
+            *socket_, asio::buffer(&status_frame_, sizeof(status_frame_)),
+            [this, self](const asio::error_code& ec, std::size_t len) {
+                cancelStatusDeadline();
+                if (ec || len != sizeof(status_frame_)) {
+                    // The body path may have already finalized a failure and
+                    // closed the socket; finalize() is idempotent (moved-from
+                    // callbacks are null-checked).
+                    if (ec != asio::error::operation_aborted) {
+                        LOG(ERROR)
+                            << "ClientSession: failed to read WRITE "
+                               "ack frame. Error: "
+                            << ec.message() << " (value: " << ec.value() << ")";
+                    }
+                    abortWrite();
+                    return;
+                }
+                bool progress_accepted = false;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                progress_accepted =
+                    acceptProgressForTest(kSessionWriteAckSuccess);
+#else
+                progress_accepted = acceptProgress();
+#endif
+                if (!progress_accepted) {
+                    abortWrite();
+                    return;
+                }
+                uint64_t frame = le64toh(status_frame_);
+                if (!statusFrameValid(frame)) {
+                    LOG(ERROR) << "ClientSession: malformed WRITE ack frame "
+                                  "(peer likely speaks the legacy protocol); "
+                                  "dropping connection";
+                    abortWrite();
+                    return;
+                }
+                if (frame != kStatusOk) {
+                    LOG(ERROR) << "ClientSession: WRITE rejected by server, "
+                                  "status "
+                               << (frame & 0xFFFFFFFFull);
+                    abortWrite();
+                    return;
+                }
+                if (!write_body_done_) {
+                    // The server's ack can legitimately overtake the final
+                    // local write-completion handler (both become ready
+                    // together for small writes; the io thread may run this
+                    // handler first). Record it; the body path finalizes.
+                    write_acked_ok_ = true;
+                    return;
+                }
+                finalize(TransferStatusEnum::COMPLETED, true);
+            });
+    }
+
+    void readBody() {
+        auto self(shared_from_this());
+        uint64_t size = le64toh(header_.size);
+        char* addr = local_buffer_;
+
+        size_t buffer_size =
+            std::min(getChunkSize(), size - total_transferred_bytes_);
+        if (buffer_size == 0) {
+            finalize(TransferStatusEnum::COMPLETED, true);
+            return;
+        }
+
+        char* dram_buffer = addr + total_transferred_bytes_;
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+        if (cuda_device_ >= 0) {
+            dram_buffer = staging_buffer_.ensure(buffer_size);
+        }
+#endif
+
+        asio::async_read(
+            *socket_, asio::buffer(dram_buffer, buffer_size),
+            [this, addr, dram_buffer, self](const asio::error_code& ec,
+                                            std::size_t transferred_bytes) {
+                if (ec) {
+                    LOG(ERROR)
+                        << "ClientSession::readBody failed. "
+                        << "Attempt to read data " << static_cast<void*>(addr)
+                        << " using buffer " << static_cast<void*>(dram_buffer)
+                        << ". Error: " << ec.message()
+                        << " (value: " << ec.value() << ")";
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+
+                bool progress_accepted = !progress_timeout_committed_;
+                if (progress_accepted && transferred_bytes > 0) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+                    progress_accepted =
+                        acceptProgressForTest(kSessionReadBodySuccess);
+#else
+                    progress_accepted = acceptProgress();
+#endif
+                }
+                if (!progress_accepted) {
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+                if (cuda_device_ >= 0) {
+                    cudaSetDevice(cuda_device_);
+#ifdef USE_MACA
+                    cudaError_t cuda_status =
+                        copyTcpCudaMemory(addr + total_transferred_bytes_,
+                                          dram_buffer, transferred_bytes);
+#else
+                    cudaError_t cuda_status =
+                        cudaMemcpy(addr + total_transferred_bytes_, dram_buffer,
+                                   transferred_bytes, cudaMemcpyDefault);
+#endif
+                    if (cuda_status != cudaSuccess) {
+                        LOG(ERROR)
+                            << "ClientSession::readBody failed to copy to CUDA "
+                               "memory. "
+                            << "Error: " << cudaGetErrorString(cuda_status);
+                        finalize(TransferStatusEnum::FAILED, false);
+                        return;
+                    }
+                }
+#endif
+                total_transferred_bytes_ += transferred_bytes;
+                readBody();
+            });
+    }
+
+    void writeBody() {
+        auto self(shared_from_this());
+        uint64_t size = le64toh(header_.size);
+        char* addr = local_buffer_;
+
+        size_t buffer_size =
+            std::min(getChunkSize(), size - total_transferred_bytes_);
+        if (buffer_size == 0) {
+            if (v2_) {
+                if (write_abort_requested_) {
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                // Completion comes from the server's acknowledgment, whose
+                // read is already in flight (armed in writeHeader) and may
+                // have finished first.
+                write_body_done_ = true;
+                if (write_acked_ok_) {
+                    finalize(TransferStatusEnum::COMPLETED, true);
+                } else {
+                    // From here a well-behaved server owes at most one
+                    // chunk's apply plus the frame; a legacy peer behind a
+                    // stale descriptor may owe nothing, ever.
+                    armStatusDeadline();
+                }
+            } else {
+                // v1: no acknowledgment exists in the protocol; this only
+                // means the payload left the initiator (#2086).
+                finalize(TransferStatusEnum::COMPLETED, true);
+            }
+            return;
+        }
+
+        char* dram_buffer = addr + total_transferred_bytes_;
+
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) ||  \
+    defined(USE_MLU) || defined(USE_MACA) || defined(USE_HYGON) || \
+    defined(USE_COREX)
+        if (cuda_device_ >= 0) {
+            dram_buffer = staging_buffer_.ensure(buffer_size);
+            cudaSetDevice(cuda_device_);
+#ifdef USE_MACA
+            cudaError_t cuda_status = copyTcpCudaMemory(
+                dram_buffer, addr + total_transferred_bytes_, buffer_size);
+#else
+            cudaError_t cuda_status =
+                cudaMemcpy(dram_buffer, addr + total_transferred_bytes_,
+                           buffer_size, cudaMemcpyDefault);
+#endif
+            if (cuda_status != cudaSuccess) {
+                LOG(ERROR) << "ClientSession::writeBody failed to copy from "
+                              "CUDA memory. "
+                           << "Error: " << cudaGetErrorString(cuda_status);
+                abortWrite();
+                return;
+            }
+        }
+#endif
+
+        write_body_in_flight_ = true;
+        asio::async_write(
+            *socket_, asio::buffer(dram_buffer, buffer_size),
+            [this, addr, dram_buffer, self](const asio::error_code& ec,
+                                            std::size_t transferred_bytes) {
+                write_body_in_flight_ = false;
+                if (ec) {
+                    LOG(ERROR)
+                        << "ClientSession::writeBody failed. "
+                        << "Attempt to write data " << static_cast<void*>(addr)
+                        << " using buffer " << static_cast<void*>(dram_buffer)
+                        << ". Error: " << ec.message()
+                        << " (value: " << ec.value() << ")";
+                    abortWrite();
+                    return;
+                }
+                if (write_abort_requested_) {
+                    // An early ACK failure or a committed progress timeout
+                    // closed the socket while this operation still owned the
+                    // caller's source buffer. It is safe to publish failure
+                    // now that the handler has run.
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                if (transferred_bytes > 0 && !acceptProgress()) {
+                    finalize(TransferStatusEnum::FAILED, false);
+                    return;
+                }
+                total_transferred_bytes_ += transferred_bytes;
+                writeBody();
+            });
+    }
+};
+
+struct TcpContext {
+    TcpContext(TcpIoPool& pool, short port, ValidateAddrFn validate_addr)
+        : pool_(pool),
+          io_context(pool.context(0)),
+          acceptor(io_context),
+          validate_addr_(std::move(validate_addr)) {
+        std::error_code ec;
+        asio::ip::tcp::endpoint endpoint(asio::ip::tcp::v6(), port);
+
+        acceptor.open(endpoint.protocol(), ec);
+        if (!ec) {
+            acceptor.set_option(asio::ip::v6_only(false), ec);
+            if (!ec) {
+                acceptor.set_option(
+                    asio::ip::tcp::acceptor::reuse_address(true));
+                acceptor.bind(endpoint, ec);
+                if (!ec) {
+                    acceptor.listen();
+                    return;
+                }
+            }
+            acceptor.close();
+        }
+        LOG(ERROR) << "Failed to set up IPv6 dual-stack listener: "
+                   << ec.message() << " (error code: " << ec.value() << ")";
+        asio::ip::tcp::endpoint endpoint_v4(asio::ip::tcp::v4(), port);
+        acceptor.open(endpoint_v4.protocol());
+        acceptor.set_option(asio::ip::tcp::acceptor::reuse_address(true));
+        acceptor.bind(endpoint_v4);
+        acceptor.listen();
+    }
+
+    void doAccept() {
+        // Round-robin each accepted connection onto a shard so ServerSession
+        // I/O spreads across io threads. The accept handler runs on shard 0
+        // (the acceptor's context); the accepted socket lives on the target
+        // shard, so start its session there.
+        acceptor.async_accept(
+            pool_.context(pool_.nextShardIndex()),
+            [this](asio::error_code ec, tcpsocket socket) {
+                if (!ec) {
+                    asio::error_code nodelay_ec;
+                    socket.set_option(asio::ip::tcp::no_delay(true),
+                                      nodelay_ec);
+                    auto socket_ptr =
+                        std::make_shared<tcpsocket>(std::move(socket));
+                    auto session = std::make_shared<ServerSession>(
+                        socket_ptr, validate_addr_);
+                    asio::post(socket_ptr->get_executor(),
+                               [session] { session->start(); });
+                }
+                doAccept();
+            });
+    }
+
+    TcpIoPool& pool_;
+    asio::io_context& io_context;
+    asio::ip::tcp::acceptor acceptor;
+    ValidateAddrFn validate_addr_;
+};
diff --git a/mooncake-transfer-engine/tent/CMakeLists.txt b/mooncake-transfer-engine/tent/CMakeLists.txt
index f7970376a4..7fc5db5832 100644
--- a/mooncake-transfer-engine/tent/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/CMakeLists.txt
@@ -2,6 +2,9 @@ cmake_minimum_required(VERSION 3.16)
 
 if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
   project(mc_tent LANGUAGES CXX)
+  include(../../cmake/Dependencies.cmake)
+  mooncake_provide_liburing()
+  mooncake_provide_hiredis()
 endif()
 
 if(BUILD_UNIT_TESTS AND NOT TARGET gtest)
diff --git a/mooncake-transfer-engine/tent/tests/hip_bandwidth_bench.cpp b/mooncake-transfer-engine/tent/benchmark/hip_bandwidth_bench.cpp
similarity index 99%
rename from mooncake-transfer-engine/tent/tests/hip_bandwidth_bench.cpp
rename to mooncake-transfer-engine/tent/benchmark/hip_bandwidth_bench.cpp
index a265a80863..7d95bae52e 100644
--- a/mooncake-transfer-engine/tent/tests/hip_bandwidth_bench.cpp
+++ b/mooncake-transfer-engine/tent/benchmark/hip_bandwidth_bench.cpp
@@ -4,7 +4,7 @@
 // Measures H2D, D2H, D2D (same GPU), and GPU-to-GPU (P2P via XGMI)
 // bandwidth across a sweep of transfer sizes.
 //
-// Build:
+// Build (from this directory):
 //   hipcc -O3 -o hip_bandwidth_bench hip_bandwidth_bench.cpp
 //
 // Run:
diff --git a/mooncake-transfer-engine/tent/config/transfer-engine.json b/mooncake-transfer-engine/tent/config/transfer-engine.json
index 632346afb5..41b4b13d80 100644
--- a/mooncake-transfer-engine/tent/config/transfer-engine.json
+++ b/mooncake-transfer-engine/tent/config/transfer-engine.json
@@ -82,6 +82,20 @@
             "retry_max_delay_ms": 2000,
             "max_concurrent_tasks": 16
         },
+        "hp_tcp": {
+            "enable": false,
+            "bind_address": "",
+            "advertise_address": "",
+            "rail_addresses": [],
+            "port": 0,
+            "worker_count": 16,
+            "connections_per_peer": 4,
+            "max_outstanding_tasks": 4096,
+            "max_outstanding_bytes": 4294967296,
+            "max_transfer_bytes": 1073741824,
+            "connect_timeout_ms": 2000,
+            "progress_timeout_ms": 30000
+        },
         "gds": {
             "enable" : true
         },
@@ -91,6 +105,15 @@
         },
         "mnnvl": {
             "enable" : false
+        },
+        "ascend_direct": {
+            "enable": true,
+            "transfer_timeout_ms": 10000,
+            "rdma_tc": "",
+            "rdma_sl": "",
+            "fabric_mem": false,
+            "global_resource_config": "",
+            "agent_mode": false
         }
     },
     "policy": [
@@ -98,7 +121,7 @@
             "name": "default_memory",
             "segment_type": "memory",
             "devices": ["mlx5_0", "mlx5_2"],
-            "transports": ["nvlink", "rdma", "shm"]
+            "transports": ["nvlink", "rdma", "shm", "hp_tcp"]
         },
         {
             "name": "file_storage",
diff --git a/mooncake-transfer-engine/tent/include/tent/common/concurrent/bounded_mpsc_queue.h b/mooncake-transfer-engine/tent/include/tent/common/concurrent/bounded_mpsc_queue.h
index 17d7458a29..2760c523dc 100644
--- a/mooncake-transfer-engine/tent/include/tent/common/concurrent/bounded_mpsc_queue.h
+++ b/mooncake-transfer-engine/tent/include/tent/common/concurrent/bounded_mpsc_queue.h
@@ -18,6 +18,7 @@
 #include <atomic>
 #include <thread>
 #include <unordered_set>
+#include <vector>
 
 namespace mooncake {
 namespace tent {
@@ -43,27 +44,29 @@ struct BoundedMPSCQueue {
     ~BoundedMPSCQueue() = default;
 
     void push(T &slice_list) {
-        if (slice_list.num_slices == 0) return;
-        uint64_t pos;
-        while (true) {
-            pos = tail.load(std::memory_order_relaxed);
-            Cell *cell = &buffer[pos % Capacity];
+        while (!try_push(slice_list)) {
+            std::this_thread::yield();
+        }
+    }
 
-            uint64_t seq = cell->sequence.load(std::memory_order_acquire);
-            intptr_t dif =
-                static_cast<intptr_t>(seq) - static_cast<intptr_t>(pos);
-            if (dif == 0) {
-                if (tail.compare_exchange_weak(pos, pos + 1,
-                                               std::memory_order_acq_rel,
-                                               std::memory_order_relaxed)) {
-                    cell->data = slice_list;
-                    cell->sequence.store(pos + 1, std::memory_order_release);
-                    return;
-                }
-            } else if (dif < 0) {
-                std::this_thread::yield();
-            }
+    // Non-blocking push: returns false when the queue is full. The worker
+    // thread re-enqueues through this so a full queue parks the entry in a
+    // local overflow instead of wedging the only consumer (issue #3637).
+    bool try_push(T &slice_list) {
+        if (slice_list.num_slices == 0) return true;
+        uint64_t pos = tail.load(std::memory_order_relaxed);
+        Cell *cell = &buffer[pos % Capacity];
+
+        uint64_t seq = cell->sequence.load(std::memory_order_acquire);
+        intptr_t dif = static_cast<intptr_t>(seq) - static_cast<intptr_t>(pos);
+        if (dif != 0) return false;
+        if (!tail.compare_exchange_weak(pos, pos + 1, std::memory_order_acq_rel,
+                                        std::memory_order_relaxed)) {
+            return false;
         }
+        cell->data = slice_list;
+        cell->sequence.store(pos + 1, std::memory_order_release);
+        return true;
     }
 
     T pop() {
@@ -106,4 +109,4 @@ struct BoundedMPSCQueue {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // TENT_BOUNDED_MPSC_QUEUE_H
\ No newline at end of file
+#endif  // TENT_BOUNDED_MPSC_QUEUE_H
diff --git a/mooncake-transfer-engine/tent/include/tent/common/concurrent/ticket_lock.h b/mooncake-transfer-engine/tent/include/tent/common/concurrent/ticket_lock.h
index 67a7a47a20..66a89f4802 100644
--- a/mooncake-transfer-engine/tent/include/tent/common/concurrent/ticket_lock.h
+++ b/mooncake-transfer-engine/tent/include/tent/common/concurrent/ticket_lock.h
@@ -16,26 +16,44 @@
 #define TENT_TICKET_LOCK_H
 
 #include <atomic>
+#include <cstdint>
 #include <thread>
 
 #include "tent/common/types.h"
+#include "tent/common/utils/os.h"
 
 namespace mooncake {
 namespace tent {
+// FIFO spinlock for short, bounded critical sections: arrivals take a ticket
+// and are served in order, so no waiter can be starved by a re-acquiring
+// holder. Not reentrant, no try_lock.
 class TicketLock {
    public:
     TicketLock() : next_ticket_(0), now_serving_(0) {}
 
     void lock() {
-        int my_ticket = next_ticket_.fetch_add(1, std::memory_order_relaxed);
+        const int my_ticket =
+            next_ticket_.fetch_add(1, std::memory_order_relaxed);
+        // A running holder leaves a short critical section well within the
+        // spin budget, and pause keeps the loop from clogging the pipeline.
+        // Past the budget the holder is most likely preempted, so the CPU is
+        // better given away than burned; same policy as RWSpinlock.
+        uint32_t spins = 0;
         while (now_serving_.load(std::memory_order_acquire) != my_ticket) {
-            std::this_thread::yield();
+            if (++spins < kSpinsBeforeYield)
+                PAUSE();
+            else
+                std::this_thread::yield();
         }
     }
 
     void unlock() { now_serving_.fetch_add(1, std::memory_order_release); }
 
    private:
+    friend class TicketLockTestPeer;  // tests read the ticket counters
+
+    static constexpr uint32_t kSpinsBeforeYield = 1000;
+
     std::atomic<int> next_ticket_;
     std::atomic<int> now_serving_;
     uint64_t padding_[14];
@@ -43,4 +61,4 @@ class TicketLock {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // TENT_TICKET_LOCK_H
\ No newline at end of file
+#endif  // TENT_TICKET_LOCK_H
diff --git a/mooncake-transfer-engine/tent/include/tent/common/config.h b/mooncake-transfer-engine/tent/include/tent/common/config.h
index decdebde68..516d6445bc 100644
--- a/mooncake-transfer-engine/tent/include/tent/common/config.h
+++ b/mooncake-transfer-engine/tent/include/tent/common/config.h
@@ -22,6 +22,7 @@
 #include <algorithm>
 #include <filesystem>
 #include <fstream>
+#include <memory>
 #include <mutex>
 #include <string>
 #include <vector>
@@ -165,6 +166,18 @@ class Config {
 
     std::string dump(int indent = 2) const;
 
+    // If key_path resolves to a JSON value, dump it into *out and return true.
+    bool dumpSubtree(const std::string& key_path, std::string* out) const;
+
+    // Capture the complete configuration while holding a single lock. The
+    // returned object is independently owned and exposed as const so readers
+    // can share one coherent, immutable view of the configuration.
+    std::shared_ptr<const Config> freeze() const;
+
+    // Return canonical slash-delimited paths for every configured value.
+    // Arrays and empty objects are treated as values rather than traversed.
+    std::vector<std::string> paths() const;
+
    private:
     json config_data_;
     mutable std::mutex mutex_;
@@ -173,6 +186,8 @@ class Config {
 struct ConfigHelper {
     Status loadFromEnv(Config& config);
 
+    static void forceTcp(Config& config);
+
     // Common parsing utilities for environment variable values
     static bool parseBool(const std::string& str, bool default_value = false);
     static int parseInt(const std::string& str, int default_value = 0);
diff --git a/mooncake-transfer-engine/tent/include/tent/common/config_lifecycle.h b/mooncake-transfer-engine/tent/include/tent/common/config_lifecycle.h
new file mode 100644
index 0000000000..e3be7177ae
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/common/config_lifecycle.h
@@ -0,0 +1,153 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_CONFIG_LIFECYCLE_H
+#define TENT_CONFIG_LIFECYCLE_H
+
+#include <tent/common/config.h>
+
+#include <cstdint>
+#include <memory>
+#include <span>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace mooncake {
+namespace tent {
+
+// This classification describes whether a field may participate in a future
+// runtime update. kRuntimeCandidate does not mean that live application is
+// implemented yet; it only records that the field is eligible for that work.
+enum class ConfigLifecycle : uint8_t {
+    kBootstrapOnly,
+    kRuntimeCandidate,
+};
+
+enum class ConfigFieldMatch : uint8_t {
+    kExact,
+    kSubtree,
+};
+
+struct ConfigFieldSpec {
+    std::string_view path;
+    ConfigFieldMatch match;
+};
+
+// Return the TENT runtime-candidate allowlist. When more than one entry matches
+// a path, the most specific (longest) path wins. Unmatched paths are
+// bootstrap-only.
+std::span<const ConfigFieldSpec> configFieldInventory();
+
+ConfigLifecycle classifyConfigPath(std::string_view path);
+
+const char* configLifecycleName(ConfigLifecycle lifecycle);
+
+enum class ConfigDiagnosticCode : uint8_t {
+    kInvalidRoot,
+};
+
+struct ConfigDiagnostic {
+    ConfigDiagnosticCode code;
+    std::string path;
+    std::string message;
+};
+
+// A lifecycle-restricted view over a frozen Config. Both bootstrap and runtime
+// views share the same immutable backing object, so one bundle always
+// represents one coherent capture of the legacy configuration.
+// Read paths must be non-empty and contain no empty slash-delimited segments.
+// Noncanonical paths are rejected with the default value or false.
+class LifecycleConfigView {
+   public:
+    template <typename T>
+    T get(const std::string& key_path, const T& default_value) const {
+        if (!canRead(key_path)) return default_value;
+        return values_->get<T>(key_path, default_value);
+    }
+
+    std::string get(const std::string& key_path,
+                    const char* default_value) const {
+        return get<std::string>(key_path, std::string(default_value));
+    }
+
+    template <typename T>
+    std::vector<T> getArray(const std::string& key_path) const {
+        return get<std::vector<T>>(key_path, {});
+    }
+
+    bool contains(const std::string& key_path) const;
+
+    bool dumpSubtree(const std::string& key_path, std::string* out) const;
+
+    ConfigLifecycle lifecycle() const { return lifecycle_; }
+
+   protected:
+    LifecycleConfigView(std::shared_ptr<const Config> values,
+                        ConfigLifecycle lifecycle)
+        : values_(std::move(values)), lifecycle_(lifecycle) {
+        if (values_) configured_paths_ = values_->paths();
+    }
+    ~LifecycleConfigView() = default;
+
+   private:
+    bool allows(std::string_view key_path) const;
+    bool canRead(std::string_view key_path) const;
+
+    std::shared_ptr<const Config> values_;
+    ConfigLifecycle lifecycle_;
+    std::vector<std::string> configured_paths_;
+};
+
+class BootstrapConfig final : public LifecycleConfigView {
+   public:
+    explicit BootstrapConfig(std::shared_ptr<const Config> values)
+        : LifecycleConfigView(std::move(values),
+                              ConfigLifecycle::kBootstrapOnly) {}
+};
+
+class RuntimeConfig final : public LifecycleConfigView {
+   public:
+    explicit RuntimeConfig(std::shared_ptr<const Config> values)
+        : LifecycleConfigView(std::move(values),
+                              ConfigLifecycle::kRuntimeCandidate) {}
+};
+
+inline constexpr int kDefaultMaxFailoverAttempts = 3;
+inline constexpr bool kDefaultAutoFailoverOnPoll = true;
+
+struct RuntimeConfigSnapshot {
+    uint64_t generation{0};
+    std::shared_ptr<const RuntimeConfig> config;
+    int max_failover_attempts{kDefaultMaxFailoverAttempts};
+    bool enable_auto_failover_on_poll{kDefaultAutoFailoverOnPoll};
+};
+
+struct TentConfigBundle {
+    std::shared_ptr<const BootstrapConfig> bootstrap;
+    std::shared_ptr<const RuntimeConfigSnapshot> runtime;
+    std::vector<ConfigDiagnostic> diagnostics;
+};
+
+// Adapt an already-merged legacy Config into the canonical lifecycle bundle.
+// This deliberately does not load files or environment variables, preserving
+// the precedence rules of the caller that produced effective_config.
+TentConfigBundle buildTentConfigBundle(const Config& effective_config,
+                                       uint64_t generation = 0);
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_CONFIG_LIFECYCLE_H
diff --git a/mooncake-transfer-engine/tent/include/tent/common/cuda_fabric_compat.h b/mooncake-transfer-engine/tent/include/tent/common/cuda_fabric_compat.h
new file mode 100644
index 0000000000..3a8a83c90e
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/common/cuda_fabric_compat.h
@@ -0,0 +1,29 @@
+#pragma once
+
+// CUDA introduced the Fabric memory handle declarations in CUDA 12.3.  The
+// driver entry points are present in older headers, but the declarations below
+// are still needed to compile code that probes the optional capability.  Keep
+// the compatibility definitions limited to old CUDA headers; newer toolkits
+// provide the canonical declarations themselves.
+#if (defined(USE_CUDA) || defined(USE_HYGON) || defined(USE_COREX)) && \
+    defined(CUDA_VERSION) && CUDA_VERSION < 12030
+
+#ifndef CU_IPC_HANDLE_SIZE
+#define CU_IPC_HANDLE_SIZE 64
+#endif
+
+#ifndef CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED
+#define CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED \
+    ((CUdevice_attribute)128)
+#endif
+
+#ifndef CU_MEM_HANDLE_TYPE_FABRIC
+#define CU_MEM_HANDLE_TYPE_FABRIC ((CUmemAllocationHandleType)0x8)
+#endif
+
+typedef struct CUmemFabricHandle_st {
+    unsigned char data[CU_IPC_HANDLE_SIZE];
+} CUmemFabricHandle_v1;
+typedef CUmemFabricHandle_v1 CUmemFabricHandle;
+
+#endif
diff --git a/mooncake-transfer-engine/tent/include/tent/common/status.h b/mooncake-transfer-engine/tent/include/tent/common/status.h
index 6704982124..d90742cb48 100644
--- a/mooncake-transfer-engine/tent/include/tent/common/status.h
+++ b/mooncake-transfer-engine/tent/include/tent/common/status.h
@@ -42,21 +42,28 @@
     } while (0)
 
 #ifdef USE_CUDA
+#include <glog/logging.h>
+
 #define CHECK_CUDA(call)                                                      \
     do {                                                                      \
         auto err = call;                                                      \
-        if (err != cudaSuccess)                                               \
-            return Status::InternalError(std::string(#call) + ": " +          \
-                                         cudaGetErrorString(err) + LOC_MARK); \
+        if (err != cudaSuccess) {                                             \
+            auto _msg = std::string(#call) + ": " + cudaGetErrorString(err) + \
+                        LOC_MARK;                                             \
+            LOG(ERROR) << "CUDA error: " << _msg;                             \
+            return Status::InternalError(std::move(_msg));                    \
+        }                                                                     \
     } while (0)
 
-#define CHECK_CU(call)                                                        \
-    do {                                                                      \
-        auto err = call;                                                      \
-        if (err != CUDA_SUCCESS) {                                            \
-            return Status::InternalError(std::string(#call) + ": cuResult " + \
-                                         std::to_string(err) + LOC_MARK);     \
-        }                                                                     \
+#define CHECK_CU(call)                                       \
+    do {                                                     \
+        auto err = call;                                     \
+        if (err != CUDA_SUCCESS) {                           \
+            auto _msg = std::string(#call) + ": cuResult " + \
+                        std::to_string(err) + LOC_MARK;      \
+            LOG(ERROR) << "CUDA driver error: " << _msg;     \
+            return Status::InternalError(std::move(_msg));   \
+        }                                                    \
     } while (0)
 #endif
 
@@ -101,6 +108,7 @@ class Status final {
         kMetadataError = 131,
         kRpcServiceError = 132,
         kMalformedJson = 133,
+        kRpcConnectionError = 134,  // Failed before dispatching the request.
         kInternalError = 199,
 
         kNotImplemented = 200,
@@ -154,7 +162,13 @@ class Status final {
     TYPE_CHECK(RdmaError);
     TYPE_CHECK(CudaError);
     TYPE_CHECK(MetadataError);
-    TYPE_CHECK(RpcServiceError);
+    TYPE_CHECK(RpcConnectionError);
+    [[nodiscard]] bool IsRpcServiceError() const {
+        return code_ == Code::kRpcServiceError || IsRpcConnectionError();
+    }
+    static Status RpcServiceError(std::string_view msg) {
+        return Status(Code::kRpcServiceError, msg);
+    }
     TYPE_CHECK(MalformedJson);
     TYPE_CHECK(InternalError);
 
diff --git a/mooncake-transfer-engine/tent/include/tent/common/types.h b/mooncake-transfer-engine/tent/include/tent/common/types.h
index 088f0b3128..938613046d 100644
--- a/mooncake-transfer-engine/tent/include/tent/common/types.h
+++ b/mooncake-transfer-engine/tent/include/tent/common/types.h
@@ -56,6 +56,9 @@ enum TransportType : int {
     SUNRISE_LINK,
     TPU,
     UB,
+    MPCOMM,
+    HP_TCP,
+    XPU,
     // Sentinel: must remain the last enumerator.
     kNumTransportTypes,
 };
@@ -93,6 +96,12 @@ inline const char* transportTypeName(TransportType type) {
             return "tpu";
         case UB:
             return "ub";
+        case MPCOMM:
+            return "mpcomm";
+        case HP_TCP:
+            return "hp_tcp";
+        case XPU:
+            return "xpu";
         case kNumTransportTypes:
             return "unknown";
     }
@@ -112,6 +121,9 @@ inline TransportType parseTransportType(const std::string& str) {
     if (str == "sunrise_link") return SUNRISE_LINK;
     if (str == "tpu") return TPU;
     if (str == "ub") return UB;
+    if (str == "mpcomm") return MPCOMM;
+    if (str == "hp_tcp") return HP_TCP;
+    if (str == "xpu") return XPU;
     return UNSPEC;
 }
 
@@ -141,9 +153,12 @@ struct Request {
                  // name transport.
     // Optional SLO deadline as an absolute steady_clock timestamp in
     // nanoseconds. 0 = no deadline (default), behaves exactly as today.
-    // When set, the engine emits an observability-only feasibility metric
-    // (MLU = actual transfer time / available window) on completion; it does
-    // not yet drive any admission or scheduling decision. See RFC #2519.
+    // When set, the engine records the feasibility metric (MLU = actual
+    // transfer time / available window) on completion, and -- each opt-in --
+    // the admission queue orders, promotes and may cancel the request by it
+    // (runtime_queue/*) and the RDMA workers order posts by it
+    // (transports/rdma/deadline_bw_arbitration). See RFC #2519, RFC #2792
+    // and docs/source/design/tent/deadline-scheduling.md.
     uint64_t deadline_ns = 0;
     IntentType intent_type = IntentType::INTENT_UNSPEC;
 };
@@ -158,11 +173,35 @@ enum TransferStatusEnum {
     FAILED
 };
 
+// Rank for aggregating batch status. Unknown values rank with FAILED so
+// getBatchStatus never throws from unordered_map::at during teardown.
+inline int transferStatusSeverity(TransferStatusEnum s) {
+    switch (s) {
+        case INITIAL:
+        case PENDING:
+        case COMPLETED:
+            return 0;
+        case INVALID:
+            return 1;
+        case CANCELED:
+            return 2;
+        case TIMEOUT:
+            return 3;
+        case FAILED:
+            return 4;
+        default:
+            return 4;
+    }
+}
+
 struct TransferStatus {
     TransferStatusEnum s;
     size_t transferred_bytes;
 };
 
+// One RDMA NIC's load snapshot. Only NICs currently able to carry traffic
+// are reported: a NIC whose context failed to construct or whose port is
+// down is omitted rather than listed with a meaningless bandwidth.
 struct NicLoadStats {
     std::string device_name;
     uint64_t inflight_bytes{0};
diff --git a/mooncake-transfer-engine/tent/include/tent/metastore/http.h b/mooncake-transfer-engine/tent/include/tent/metastore/http.h
index 8d764dd4c4..bc5bb98264 100644
--- a/mooncake-transfer-engine/tent/include/tent/metastore/http.h
+++ b/mooncake-transfer-engine/tent/include/tent/metastore/http.h
@@ -18,6 +18,7 @@
 #include "tent/runtime/metastore.h"
 
 #include <atomic>
+#include <mutex>
 #include <curl/curl.h>
 
 namespace mooncake {
@@ -55,6 +56,9 @@ class HttpMetaStore : public MetaStore {
 
    private:
     std::atomic<bool> connected_;
+    // Each op uses its own local curl handle (ScopedCurl), so nothing curl is
+    // shared; this lock only serializes ops defensively.
+    std::mutex client_mutex_;
     std::string endpoint_;
 };
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/include/tent/metastore/redis.h b/mooncake-transfer-engine/tent/include/tent/metastore/redis.h
index 02ad204b0e..36496c5d6b 100644
--- a/mooncake-transfer-engine/tent/include/tent/metastore/redis.h
+++ b/mooncake-transfer-engine/tent/include/tent/metastore/redis.h
@@ -19,6 +19,8 @@
 #include <hiredis/hiredis.h>
 
 #include <atomic>
+#include <cstdarg>
+#include <mutex>
 
 #include "tent/runtime/metastore.h"
 #include "tent/common/utils/ip.h"
@@ -53,9 +55,23 @@ class RedisMetaStore : public MetaStore {
 
     virtual Status remove(const std::string &key);
 
-   private:
+   protected:
+    // Test seam: run a Redis command on client_. Virtual so tests can inject a
+    // fake that fabricates replies without a live server.
+    virtual redisReply *runCommand(const char *format, va_list ap);
+
     std::atomic<bool> connected_;
+
+   private:
+    // Variadic forwarder to runCommand().
+    redisReply *command(const char *format, ...);
+
     redisContext *client_;
+    // hiredis' synchronous redisContext is NOT thread-safe: concurrent
+    // redisCommand() calls corrupt its shared command/reply buffers. tent's
+    // RDMA workers call get() concurrently, so serialize client_ with this
+    // lock.
+    std::mutex client_mutex_;
 
     // Helper function for handling Redis replies
     Status handleRedisReply(redisReply *reply,
diff --git a/mooncake-transfer-engine/tent/include/tent/metrics/cached_metric.h b/mooncake-transfer-engine/tent/include/tent/metrics/cached_metric.h
new file mode 100644
index 0000000000..5b1e4636bb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/metrics/cached_metric.h
@@ -0,0 +1,197 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cstddef>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "ylt/metric.hpp"
+
+namespace mooncake {
+namespace tent {
+namespace metrics {
+
+// Movable acquire/release cell-pointer slot. std::atomic is not movable, so
+// it cannot live in a resizeable vector; moves only happen while the vector
+// is being built (before any recording).
+class CellSlot {
+   public:
+    CellSlot() = default;
+    CellSlot(const CellSlot&) = delete;
+    CellSlot& operator=(const CellSlot&) = delete;
+    CellSlot(CellSlot&& other) noexcept
+        : cell_(other.cell_.load(std::memory_order_relaxed)) {}
+    CellSlot& operator=(CellSlot&& other) noexcept {
+        cell_.store(other.cell_.load(std::memory_order_relaxed),
+                    std::memory_order_relaxed);
+        return *this;
+    }
+
+    std::atomic<int64_t>* load() const {
+        return cell_.load(std::memory_order_acquire);
+    }
+    void store(std::atomic<int64_t>* c) {
+        cell_.store(c, std::memory_order_release);
+    }
+
+   private:
+    std::atomic<std::atomic<int64_t>*> cell_{nullptr};
+};
+
+// Metrics primitives with pre-resolved label cells. ylt's dynamic counter
+// inc() / histogram observe() take a mutex-protected map lookup per call, and
+// because TENT labels come from small fixed enums, all updates for a label
+// land on the same shard mutex. These primitives resolve the atomic cell
+// backing a label once and cache it in a per-label-index slot, reducing the
+// steady-state update to relaxed atomic adds.
+//
+// Labels are never erased by TentMetrics, so resolved cells stay valid for
+// the process lifetime. Slot publication uses release/acquire, so
+// concurrent first-use resolutions are race free.
+
+template <uint8_t N>
+class CachedDynamicCounter
+    : public ylt::metric::basic_dynamic_counter<int64_t, N> {
+   public:
+    using Base = ylt::metric::basic_dynamic_counter<int64_t, N>;
+    using Label = std::array<std::string, N>;
+
+    // label_domain_size: number of distinct label values ever recorded; the
+    // caller maps each label to a stable index < this size.
+    CachedDynamicCounter(std::string name, std::string help,
+                         std::array<std::string, N> labels_name,
+                         size_t label_domain_size)
+        : Base(std::move(name), std::move(help), std::move(labels_name)),
+          slots_(label_domain_size) {}
+
+    // Resolve (creating on first use) the atomic cell backing a label.
+    std::atomic<int64_t>* resolve(const Label& label) {
+        auto cell = Base::try_emplace(label).first;
+        return &cell->value;
+    }
+
+    // Increment via the cached cell; make_label runs only on first use.
+    template <typename LabelFn>
+    void incCached(size_t label_index, LabelFn&& make_label,
+                   int64_t value = 1) {
+        std::atomic<int64_t>* cell = slots_[label_index].load();
+        if (cell == nullptr) [[unlikely]] {
+            cell = resolve(make_label());
+            slots_[label_index].store(cell);
+        }
+        cell->fetch_add(value, std::memory_order_relaxed);
+    }
+
+   private:
+    std::vector<CellSlot> slots_;
+};
+
+// Histogram composed of CachedDynamicCounter buckets and a sum counter.
+// Same bucketing semantics as ylt's basic_dynamic_histogram (inclusive upper
+// bounds, trailing +Inf bucket), but observe goes through cached cells.
+template <uint8_t N>
+class CachedDynamicHistogram {
+   public:
+    using Label = std::array<std::string, N>;
+    using Counter = CachedDynamicCounter<N>;
+
+    CachedDynamicHistogram(const std::string& name, const std::string& help,
+                           const std::vector<double>& boundaries,
+                           const std::array<std::string, N>& labels_name,
+                           size_t label_domain_size)
+        : name_(name),
+          help_(help),
+          labels_name_(labels_name),
+          boundaries_(boundaries),
+          sum_(std::make_unique<Counter>(name + "_sum", help, labels_name,
+                                         label_domain_size)) {
+        for (size_t i = 0; i < boundaries_.size() + 1; ++i) {
+            buckets_.push_back(std::make_unique<Counter>(
+                name, help, labels_name, label_domain_size));
+        }
+        bucket_slots_.resize(label_domain_size * buckets_.size());
+        sum_slots_.resize(label_domain_size);
+    }
+
+    // Observation via cached bucket and sum cells.
+    template <typename LabelFn>
+    void observeCached(size_t label_index, LabelFn&& make_label,
+                       int64_t value) {
+        const size_t bucket = bucketIndex(value);
+        const size_t slot = label_index * buckets_.size() + bucket;
+        std::atomic<int64_t>* cell = bucket_slots_[slot].load();
+        if (cell == nullptr) [[unlikely]] {
+            cell = buckets_[bucket]->resolve(make_label());
+            bucket_slots_[slot].store(cell);
+        }
+        cell->fetch_add(1, std::memory_order_relaxed);
+
+        std::atomic<int64_t>* sum_cell = sum_slots_[label_index].load();
+        if (sum_cell == nullptr) [[unlikely]] {
+            sum_cell = sum_->resolve(make_label());
+            sum_slots_[label_index].store(sum_cell);
+        }
+        sum_cell->fetch_add(value, std::memory_order_relaxed);
+    }
+
+    // Scrape-time accessors, typed as the ylt base for copy()/value().
+    std::vector<ylt::metric::basic_dynamic_counter<int64_t, N>*>
+    bucketCounters() const {
+        std::vector<ylt::metric::basic_dynamic_counter<int64_t, N>*> counters;
+        counters.reserve(buckets_.size());
+        for (auto& bucket : buckets_) {
+            counters.push_back(bucket.get());
+        }
+        return counters;
+    }
+
+    ylt::metric::basic_dynamic_counter<int64_t, N>* sumCounter() {
+        return sum_.get();
+    }
+
+    const std::string& name() const { return name_; }
+    const std::string& help() const { return help_; }
+    const std::array<std::string, N>& labelsName() const {
+        return labels_name_;
+    }
+    const std::vector<double>& boundaries() const { return boundaries_; }
+
+   private:
+    // Index of the first boundary >= value (ylt bucketing); values above the
+    // last boundary land in the trailing +Inf bucket.
+    size_t bucketIndex(int64_t value) const {
+        return static_cast<size_t>(std::distance(
+            boundaries_.begin(),
+            std::lower_bound(boundaries_.begin(), boundaries_.end(), value)));
+    }
+
+    std::string name_;
+    std::string help_;
+    std::array<std::string, N> labels_name_;
+    std::vector<double> boundaries_;
+    std::vector<std::unique_ptr<Counter>> buckets_;
+    std::unique_ptr<Counter> sum_;
+    std::vector<CellSlot> bucket_slots_;
+    std::vector<CellSlot> sum_slots_;
+};
+
+}  // namespace metrics
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/metrics/tent_metrics.h b/mooncake-transfer-engine/tent/include/tent/metrics/tent_metrics.h
index b23e9d4a8f..9b6b352915 100644
--- a/mooncake-transfer-engine/tent/include/tent/metrics/tent_metrics.h
+++ b/mooncake-transfer-engine/tent/include/tent/metrics/tent_metrics.h
@@ -25,6 +25,7 @@
 
 #include "tent/common/status.h"
 #include "tent/common/types.h"
+#include "tent/metrics/cached_metric.h"
 #include "tent/metrics/config_loader.h"
 
 // Compile-time metrics enable/disable switch
@@ -56,6 +57,11 @@ constexpr size_t kPrometheusBufferSize = 4096;
  * - Optional periodic logging of metrics summary
  * - Compile-time disable option (TENT_METRICS_ENABLED=0) for zero overhead
  * - Runtime disable option via setEnabled(false) for minimal overhead
+ *
+ * Hot-path counters and histograms record through pre-resolved label cells
+ * (see cached_metric.h): TransportType and Request::OpCode label domains are
+ * small fixed enums, so each label's atomic cell is resolved once and cached,
+ * turning the steady-state update into relaxed atomic adds with no locks.
  */
 class TentMetrics {
    public:
@@ -112,6 +118,37 @@ class TentMetrics {
     // distinguishable from genuine MLU samples in the histogram above.
     void recordDeadlineInfeasible(TransportType tp);
 
+    // Record a batch abandoned by lazyFreeBatch after repeated failed reclaim
+    // attempts. Such a batch stays on the freelist without further retries and
+    // is only reclaimed at engine teardown, so a nonzero value means resources
+    // are parked until shutdown and the last reclaim error is in the log.
+    void recordBatchQuarantined();
+
+    // Why a task failed. "submit" failures were observed synchronously at
+    // submission (the transport rejected the request); "poll" failures were
+    // observed by polling after the request had been accepted; timeout and
+    // canceled come from the terminal status itself.
+    enum class TaskFailureReason { Submit, Poll, Timeout, Canceled };
+
+    // Record a task-level failure with its reason. Additive to the legacy
+    // read/write_failures_total counters (which stay label-compatible); also
+    // the only failure metric that records TIMEOUT/CANCELED outcomes.
+    void recordTaskFailure(TransportType tp, TaskFailureReason reason);
+
+    // In-flight transport attempts (gauge): incremented when an attempt is
+    // submitted, decremented when it finishes. Reflects how much work is
+    // sitting in the engine right now — a persistently high or stuck value
+    // is the signature of a stalled pipeline. Gauge updates are paired
+    // add/sub operations, so they execute whenever initialized and ignore
+    // setEnabled(): skipping one half of a pair across an enable/disable
+    // transition would permanently corrupt the gauge.
+    void recordInflightAttemptStarted(TransportType tp);
+    void recordInflightAttemptFinished(TransportType tp);
+
+    // Registered buffer bytes per transport (gauge), maintained on
+    // register/unregisterLocalMemory. Same pairing rule as above.
+    void recordRegisteredBufferBytes(TransportType tp, int64_t delta);
+
     enum class Stage {
         QueueWait,
         Dispatch,
@@ -187,162 +224,163 @@ class TentMetrics {
                                                                    "to"};
     static inline const std::array<std::string, 2> kAttemptLabels{"transport",
                                                                   "operation"};
+    static inline const std::array<std::string, 2> kTaskFailureLabels{
+        "transport", "reason"};
+
+    // Hot-path metrics record through pre-resolved label cells (see
+    // cached_metric.h). Label domain sizes: TransportType has
+    // kNumTransportTypes values; attempt metrics are additionally labeled by
+    // the 2-valued Request::OpCode.
+    static constexpr size_t kTransportDomain =
+        static_cast<size_t>(kNumTransportTypes);
+    static constexpr size_t kAttemptDomain = kTransportDomain * 2;
+    static constexpr size_t kTaskFailureDomain = kTransportDomain * 4;
+
+    // Stable slot indices into the cached-cell label domain.
+    static size_t transportSlot(TransportType tp) {
+        return static_cast<size_t>(tp);
+    }
+    static size_t attemptSlot(TransportType tp, Request::OpCode op) {
+        return static_cast<size_t>(tp) * 2 + (op == Request::READ ? 0u : 1u);
+    }
+    static size_t taskFailureSlot(TransportType tp, TaskFailureReason reason) {
+        return static_cast<size_t>(tp) * 4 + static_cast<size_t>(reason);
+    }
 
     // Per-transport counters (label: transport). Values are int64_t.
-    ylt::metric::basic_dynamic_counter<int64_t, 1> read_bytes_total_{
-        "tent_read_bytes_total", "Total bytes read via TENT", kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> write_bytes_total_{
+    metrics::CachedDynamicCounter<1> read_bytes_total_{
+        "tent_read_bytes_total", "Total bytes read via TENT", kTransportLabel,
+        kTransportDomain};
+    metrics::CachedDynamicCounter<1> write_bytes_total_{
         "tent_write_bytes_total", "Total bytes written via TENT",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> read_requests_total_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicCounter<1> read_requests_total_{
         "tent_read_requests_total", "Total read requests via TENT",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> write_requests_total_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicCounter<1> write_requests_total_{
         "tent_write_requests_total", "Total write requests via TENT",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> read_failures_total_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicCounter<1> read_failures_total_{
         "tent_read_failures_total", "Total read failures via TENT",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> write_failures_total_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicCounter<1> write_failures_total_{
         "tent_write_failures_total", "Total write failures via TENT",
-        kTransportLabel};
-    // Failover counter has two labels (from, to) so failover flows are
-    // queryable as e.g. tent_transport_failover_total{from="rdma",to="tcp"}.
+        kTransportLabel, kTransportDomain};
+    // Failover is a rare event and its label domain is the cross product of
+    // transports, so it stays on the plain locked path.
     ylt::metric::basic_dynamic_counter<int64_t, 2> failover_total_{
         "tent_transport_failover_total",
         "Total cross-transport failover events", kFailoverLabels};
-    ylt::metric::basic_dynamic_counter<int64_t, 2> transport_attempts_total_{
+    metrics::CachedDynamicCounter<2> transport_attempts_total_{
         "tent_transport_attempts_total",
         "Total physical transport attempts submitted for execution",
-        kAttemptLabels};
-    ylt::metric::basic_dynamic_counter<int64_t, 2>
-        transport_attempt_failures_total_{
-            "tent_transport_attempt_failures_total",
-            "Physical transport attempts that terminated with FAILED",
-            kAttemptLabels};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> deadline_infeasible_total_{
+        kAttemptLabels, kAttemptDomain};
+    metrics::CachedDynamicCounter<2> transport_attempt_failures_total_{
+        "tent_transport_attempt_failures_total",
+        "Physical transport attempts that terminated with FAILED",
+        kAttemptLabels, kAttemptDomain};
+    // Task-level failures with a reason label, so Grafana can alert on the
+    // failure signature (submit vs poll vs timeout vs canceled) without log
+    // scraping. Additive to the legacy read/write_failures_total counters.
+    metrics::CachedDynamicCounter<2> task_failures_total_{
+        "tent_task_failures_total",
+        "Task-level failures by terminal transport and failure reason",
+        kTaskFailureLabels, kTaskFailureDomain};
+    metrics::CachedDynamicCounter<1> deadline_infeasible_total_{
         "tent_deadline_infeasible_total",
         "Transfers whose deadline was already in the past at submit",
-        kTransportLabel};
-
-    // Histograms - paired with their bucket boundaries in a single vector so
-    // the two cannot drift out of sync (ylt histogram doesn't expose its
-    // boundaries publicly, so we hold them alongside the pointer).
-    // Each entry also carries a parallel counter used to track the per-label
-    // sum, because ylt's basic_dynamic_histogram keeps sum_ private with no
-    // public accessor — without this counter, _sum could only be emitted as 0
-    // in the Prometheus endpoint, breaking _sum / _count queries.
-    // Only N=1 (per-transport) histograms live here; the N=2
-    // transport_attempt_latency_ histogram is serialized separately (see
-    // getPrometheusMetrics / getJsonMetrics) via the same templated helpers.
-    struct HistogramEntry {
-        ylt::metric::basic_dynamic_histogram<int64_t, 1>* h;
-        const std::vector<double>* boundaries;
-        ylt::metric::basic_dynamic_counter<int64_t, 1>* sum;
-    };
-    std::vector<HistogramEntry> histograms_;
+        kTransportLabel, kTransportDomain};
+    // Label-less: quarantine is a batch-lifecycle event, not a per-transport
+    // one (a batch may hold SubBatches on several transports).
+    ylt::metric::counter_t quarantined_batches_total_{
+        "tent_quarantined_batches_total",
+        "Batches abandoned by lazyFreeBatch after repeated failed reclaim "
+        "attempts; reclaimed only at engine teardown"};
+
+    // Gauges, backed by cached cells and updated with add/sub. Serialized as
+    // Prometheus gauges (current value per label), NOT via the counters_
+    // vector.
+    metrics::CachedDynamicCounter<1> inflight_attempts_{
+        "tent_inflight_attempts",
+        "In-flight transport attempts (submitted, not yet finished)",
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicCounter<1> registered_buffer_bytes_{
+        "tent_registered_buffer_bytes", "Registered local buffer bytes",
+        kTransportLabel, kTransportDomain};
+    std::vector<metrics::CachedDynamicCounter<1>*> gauges_;
 
     // Latency histograms use microseconds (us) as unit
     // Default buckets: 100us, 500us, 1ms, 5ms, 10ms, 50ms, 100ms, 500ms, 1s
     static inline const std::vector<double> kLatencyBuckets{
         100, 500, 1000, 5000, 10000, 50000, 100000, 500000, 1000000};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> read_latency_{
-        "tent_read_latency_us", "Read latency distribution in microseconds",
-        kLatencyBuckets, kTransportLabel};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> write_latency_{
-        "tent_write_latency_us", "Write latency distribution in microseconds",
-        kLatencyBuckets, kTransportLabel};
     // Size histograms for request size distribution (in bytes)
     // Default buckets: 1KB, 4KB, 16KB, 64KB, 256KB, 1MB, 4MB, 16MB, 64MB,
     // 256MB, 1GB
     static inline const std::vector<double> kSizeBuckets{
         1024,    4096,     16384,    65536,     262144,    1048576,
         4194304, 16777216, 67108864, 268435456, 1073741824};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> read_size_{
-        "tent_read_size_bytes", "Read request size distribution in bytes",
-        kSizeBuckets, kTransportLabel};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> write_size_{
-        "tent_write_size_bytes", "Write request size distribution in bytes",
-        kSizeBuckets, kTransportLabel};
-
     // Deadline feasibility ratio (MLU) distribution for transfers that carried
     // a deadline. Stored in per-mille (MLU x 1000) so the histogram can use
     // integer observe() like the others; the 1000 boundary is MLU == 1.0, the
     // feasible/infeasible line (< 1000 met the deadline, >= 1000 missed it).
     static inline const std::vector<double> kMluPerMilleBuckets{
         100, 250, 500, 750, 900, 1000, 1250, 1500, 2000, 5000};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> deadline_mlu_{
-        "tent_deadline_mlu_permille",
-        "Deadline feasibility ratio (MLU x 1000) distribution",
-        kMluPerMilleBuckets, kTransportLabel};
-
     // Causal chain stage latency histograms (microseconds)
     // Buckets span 10us to 500ms to capture both fast RDMA and slower TCP.
     static inline const std::vector<double> kStageBuckets{
         10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000, 500000};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> stage_queue_wait_{
+
+    // Histograms are composed of cached-cell counters: one counter per bucket
+    // plus a sum counter. The sum is part of the histogram itself, so no
+    // parallel standalone sum counter is needed.
+    metrics::CachedDynamicHistogram<1> read_latency_{
+        "tent_read_latency_us", "Read latency distribution in microseconds",
+        kLatencyBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> write_latency_{
+        "tent_write_latency_us", "Write latency distribution in microseconds",
+        kLatencyBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> read_size_{
+        "tent_read_size_bytes", "Read request size distribution in bytes",
+        kSizeBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> write_size_{
+        "tent_write_size_bytes", "Write request size distribution in bytes",
+        kSizeBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> deadline_mlu_{
+        "tent_deadline_mlu_permille",
+        "Deadline feasibility ratio (MLU x 1000) distribution",
+        kMluPerMilleBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> stage_queue_wait_{
         "tent_stage_queue_wait_us",
         "Causal chain: queue wait latency in microseconds", kStageBuckets,
-        kTransportLabel};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> stage_dispatch_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> stage_dispatch_{
         "tent_stage_dispatch_us",
         "Causal chain: dispatch latency in microseconds", kStageBuckets,
-        kTransportLabel};
-    ylt::metric::basic_dynamic_histogram<int64_t, 1> stage_transport_{
+        kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<1> stage_transport_{
         "tent_stage_transport_us",
         "Causal chain: transport execution latency in microseconds",
-        kStageBuckets, kTransportLabel};
-    ylt::metric::basic_dynamic_histogram<int64_t, 2> transport_attempt_latency_{
+        kStageBuckets, kTransportLabel, kTransportDomain};
+    metrics::CachedDynamicHistogram<2> transport_attempt_latency_{
         "tent_transport_attempt_latency_us",
         "Observed physical transport attempt latency in microseconds",
-        kLatencyBuckets, kAttemptLabels};
-
-    // Parallel counters tracking per-label sum for each histogram. ylt's
-    // basic_dynamic_histogram keeps sum_ private with no public accessor, so
-    // we maintain these alongside observe() calls and read them back via
-    // copy() in the Prometheus serializer. Each counter's str_name is the
-    // histogram name suffixed with "_sum" so it emits as <name>_sum{...} in
-    // Prometheus output.
-    ylt::metric::basic_dynamic_counter<int64_t, 1> read_latency_sum_{
-        "tent_read_latency_us_sum",
-        "Sum of read latency observations (microseconds)", kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> write_latency_sum_{
-        "tent_write_latency_us_sum",
-        "Sum of write latency observations (microseconds)", kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> read_size_sum_{
-        "tent_read_size_bytes_sum", "Sum of read request sizes (bytes)",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> write_size_sum_{
-        "tent_write_size_bytes_sum", "Sum of write request sizes (bytes)",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> deadline_mlu_sum_{
-        "tent_deadline_mlu_permille_sum",
-        "Sum of deadline MLU (permille) observations", kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> stage_queue_wait_sum_{
-        "tent_stage_queue_wait_us_sum",
-        "Sum of queue wait latency observations (microseconds)",
-        kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> stage_dispatch_sum_{
-        "tent_stage_dispatch_us_sum",
-        "Sum of dispatch latency observations (microseconds)", kTransportLabel};
-    ylt::metric::basic_dynamic_counter<int64_t, 1> stage_transport_sum_{
-        "tent_stage_transport_us_sum",
-        "Sum of transport execution latency observations (microseconds)",
-        kTransportLabel};
-    // Parallel sum counter for the N=2 transport-attempt latency histogram
-    // (labels: transport, operation). Same rationale as the N=1 sum counters
-    // above — ylt keeps the histogram's sum_ private.
-    ylt::metric::basic_dynamic_counter<int64_t, 2>
-        transport_attempt_latency_sum_{"tent_transport_attempt_latency_us_sum",
-                                       "Sum of physical transport attempt "
-                                       "latency observations (microseconds)",
-                                       kAttemptLabels};
+        kLatencyBuckets, kAttemptLabels, kAttemptDomain};
+
+    // Per-transport (N=1) histograms for unified serialization; the N=2
+    // transport_attempt_latency_ histogram is serialized separately (see
+    // getPrometheusMetrics / getJsonMetrics) via the same templated helpers.
+    std::vector<metrics::CachedDynamicHistogram<1>*> histograms_;
+
+    // Serialize a gauge backed by a cached-cell counter: emits the current
+    // value per label with # TYPE ... gauge.
+    void serializeGaugePrometheus(metrics::CachedDynamicCounter<1>& gauge,
+                                  std::string& out) const;
 
     // Helper to register all metrics to the vectors
     void registerMetrics();
 
-    // Serialize a single histogram in Prometheus text format. Walks the
-    // same get_bucket_counts() / copy() data the JSON path uses, so the two
+    // Serialize a single histogram in Prometheus text format. Walks the same
+    // bucket-counter / sum-counter data the JSON path uses, so the two
     // endpoints can never drift. Unlike ylt's serialize(), this never
     // silently drops a histogram that has observed >=1 sample — even when
     // every observation landed in the first bucket (which makes sum_==0
@@ -350,17 +388,11 @@ class TentMetrics {
     // # HELP / # TYPE header with it). Reachable in production when
     // sub-microsecond latencies truncate to 0 under int64_t observation.
     //
-    // `boundaries` is the compile-time bucket boundary vector paired with
-    // the histogram in HistogramEntry. The caller (getPrometheusMetrics)
-    // emits the # HELP / # TYPE header so the format stays identical to ylt.
     // Templated over label arity N so both the per-transport (N=1) histograms
     // and the transport-attempt (N=2) histogram share one implementation.
     template <uint8_t N>
-    void serializeHistogramPrometheus(
-        ylt::metric::basic_dynamic_histogram<int64_t, N>* hist,
-        const std::vector<double>& boundaries,
-        ylt::metric::basic_dynamic_counter<int64_t, N>& sum,
-        std::string& out) const;
+    void serializeHistogramPrometheus(metrics::CachedDynamicHistogram<N>& hist,
+                                      std::string& out) const;
 #endif  // TENT_METRICS_ENABLED
 };
 
@@ -457,6 +489,14 @@ class ScopedLatencyRecorder {
         }                                                                      \
     } while (0)
 
+#define TENT_RECORD_BATCH_QUARANTINED()                   \
+    do {                                                  \
+        if (::mooncake::tent::TentMetrics::isEnabled()) { \
+            ::mooncake::tent::TentMetrics::instance()     \
+                .recordBatchQuarantined();                \
+        }                                                 \
+    } while (0)
+
 #define TENT_SCOPED_READ_LATENCY(tp, bytes)                               \
     ::mooncake::tent::ScopedLatencyRecorder _tent_latency_recorder_(      \
         ::mooncake::tent::ScopedLatencyRecorder::OperationType::Read, tp, \
@@ -491,6 +531,7 @@ class ScopedLatencyRecorder {
 #define TENT_RECORD_READ_FAILED(tp) ((void)0)
 #define TENT_RECORD_WRITE_FAILED(tp) ((void)0)
 #define TENT_RECORD_TRANSPORT_FAILOVER(from, to) ((void)0)
+#define TENT_RECORD_BATCH_QUARANTINED() ((void)0)
 #define TENT_SCOPED_READ_LATENCY(tp, bytes) ((void)0)
 #define TENT_SCOPED_WRITE_LATENCY(tp, bytes) ((void)0)
 #define TENT_RECORD_STAGE_LATENCY(stage, tp, latency_us) ((void)0)
diff --git a/mooncake-transfer-engine/tent/include/tent/platform/cuda.h b/mooncake-transfer-engine/tent/include/tent/platform/cuda.h
index a808a2b6f0..4037dd476c 100644
--- a/mooncake-transfer-engine/tent/include/tent/platform/cuda.h
+++ b/mooncake-transfer-engine/tent/include/tent/platform/cuda.h
@@ -122,10 +122,15 @@ class CudaPlatform : public Platform {
 
     virtual const std::string type() const { return "cuda"; }
 
+    Status synchronizeDevices(const Topology* topology) override;
+
     Status getStreamFromPool(CUDAStreamHandle& outHandle,
                              int deviceId = CUDAStreamPool::kCurrentDevice);
 
    private:
+    // Device owning `addr`, or kCurrentDevice when `addr` is not device memory.
+    int getPointerDeviceId(void* addr);
+
     std::shared_ptr<Config> conf;
     CUDAStreamPool stream_pool;
 };
@@ -133,4 +138,4 @@ class CudaPlatform : public Platform {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // CUDA_H
\ No newline at end of file
+#endif  // CUDA_H
diff --git a/mooncake-transfer-engine/tent/include/tent/platform/cuda_utils.h b/mooncake-transfer-engine/tent/include/tent/platform/cuda_utils.h
new file mode 100644
index 0000000000..d388f12070
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/platform/cuda_utils.h
@@ -0,0 +1,53 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_PLATFORM_CUDA_UTILS_H
+#define TENT_PLATFORM_CUDA_UTILS_H
+
+#include <cuda.h>
+
+#include <mutex>
+
+namespace mooncake {
+namespace tent {
+
+// cuInit() is idempotent and creates no context; the driver API does not
+// initialize itself lazily, so it must run before any driver query.
+inline bool ensureCudaDriverInit() {
+    static std::once_flag flag;
+    static CUresult result = CUDA_ERROR_NOT_INITIALIZED;
+    std::call_once(flag, []() { result = cuInit(0); });
+    return result == CUDA_SUCCESS;
+}
+
+// Device ordinal owning `ptr`, or -1 for host memory. Unlike the runtime
+// cudaPointerGetAttributes(), this never implicitly initializes the calling
+// thread's current device and its primary context (default GPU 0).
+inline int getCudaDeviceForPtr(const void* ptr) {
+    if (!ensureCudaDriverInit()) return -1;
+    unsigned int mem_type = 0;
+    CUresult res = cuPointerGetAttribute(
+        &mem_type, CU_POINTER_ATTRIBUTE_MEMORY_TYPE, (CUdeviceptr)ptr);
+    if (res != CUDA_SUCCESS || mem_type != CU_MEMORYTYPE_DEVICE) return -1;
+    unsigned int dev_ordinal = 0;
+    res = cuPointerGetAttribute(
+        &dev_ordinal, CU_POINTER_ATTRIBUTE_DEVICE_ORDINAL, (CUdeviceptr)ptr);
+    if (res != CUDA_SUCCESS) return -1;
+    return static_cast<int>(dev_ordinal);
+}
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_PLATFORM_CUDA_UTILS_H
diff --git a/mooncake-transfer-engine/tent/include/tent/platform/rocm.h b/mooncake-transfer-engine/tent/include/tent/platform/rocm.h
index 5ef0a35671..3c1d4e82ae 100644
--- a/mooncake-transfer-engine/tent/include/tent/platform/rocm.h
+++ b/mooncake-transfer-engine/tent/include/tent/platform/rocm.h
@@ -115,12 +115,17 @@ class RocmPlatform : public Platform {
     virtual const std::vector<RangeLocation> getLocation(
         void* start, size_t len, bool skip_prefault = false);
 
-    virtual const std::string type() const { return "rocm"; }
+    virtual const std::string type() const { return kAmdGpuLocationType; }
+
+    Status synchronizeDevices(const Topology* topology) override;
 
     Status getStreamFromPool(HIPStreamHandle& outHandle,
                              int deviceId = HIPStreamPool::kCurrentDevice);
 
    private:
+    // Device owning `addr`, or kCurrentDevice when `addr` is not device memory.
+    int getPointerDeviceId(void* addr);
+
     std::shared_ptr<Config> conf;
     HIPStreamPool stream_pool_;
 };
diff --git a/mooncake-transfer-engine/tent/include/tent/platform/xpu.h b/mooncake-transfer-engine/tent/include/tent/platform/xpu.h
new file mode 100644
index 0000000000..6876361686
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/platform/xpu.h
@@ -0,0 +1,76 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_PLATFORM_XPU_H_
+#define TENT_PLATFORM_XPU_H_
+
+#include "tent/common/config.h"
+#include "tent/platform/cpu.h"
+#include "tent/runtime/platform.h"
+
+namespace mooncake {
+namespace tent {
+
+// XpuPlatform models an Intel XPU host: the host DRAM and RDMA topology are
+// identical to CpuPlatform, so those paths (host allocation, NUMA probing,
+// host<->host copy) are inherited unchanged. Only the XPU-device-aware
+// operations are overridden, and every one of them is delegated to the SYCL
+// backend (XpuSyclBackend). That backend links libsycl directly, so the XPU
+// platform sources are compiled with the Intel DPC++ compiler (icpx); the SYCL
+// dependency is confined to platform_xpu and never leaks into this header.
+//
+// In the MVP, XPU VRAM cannot be reached by the NIC, so there is no direct
+// device transport. This platform provides the device-side building blocks:
+// USM allocation ("xpu:N"), pointer classification, and the VRAM<->host copy()
+// primitive. These are wired into the transport-layer staging path so
+// getTypeEnum / isGpuType / findStagingPolicy let ProxyManager chain the
+// VRAM<->host hop (executed by XpuTransport via copy()) and the host<->host hop
+// end-to-end over the network. Direct VRAM RDMA (dma-buf) and PCIe P2P are
+// future work.
+class XpuPlatform : public CpuPlatform {
+   public:
+    explicit XpuPlatform(std::shared_ptr<Config> config)
+        : CpuPlatform(config) {}
+
+    ~XpuPlatform() override {}
+
+    // Host + RDMA discovery from CpuPlatform, plus one MemEntry per XPU device
+    // ("xpu:N") so findNearMem() can resolve a device to its nearest host node.
+    Status probe(std::vector<Topology::NicEntry> &nic_list,
+                 std::vector<Topology::MemEntry> &mem_list) override;
+
+    // Device USM allocation ("xpu:N") via sycl::malloc_device; host allocation
+    // is inherited from CpuPlatform.
+    Status allocate(void **pptr, size_t size, MemoryOptions &options) override;
+
+    // Routes device pointers to the SYCL backend's free; host pointers use the
+    // inherited host deallocator.
+    Status free(void *ptr, size_t size) override;
+
+    // VRAM<->host copy via the SYCL backend when either side is XPU memory;
+    // otherwise the inherited host memcpy.
+    Status copy(void *dst, void *src, size_t length) override;
+
+    MemoryType getMemoryType(void *addr) override;
+
+    const std::vector<RangeLocation> getLocation(
+        void *start, size_t len, bool skip_prefault = false) override;
+
+    const std::string type() const override { return "xpu"; }
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_PLATFORM_XPU_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/rpc/rpc.h b/mooncake-transfer-engine/tent/include/tent/rpc/rpc.h
index cffcbe2276..379704544b 100644
--- a/mooncake-transfer-engine/tent/include/tent/rpc/rpc.h
+++ b/mooncake-transfer-engine/tent/include/tent/rpc/rpc.h
@@ -65,15 +65,37 @@ class CoroRpcAgent {
    public:
     using Function = std::function<void(const std::string_view & /* request */,
                                         std::string & /* response */)>;
-    Status registerFunction(int func_id, const Function &func);
 
-    Status start(uint16_t &port, bool ipv6 = false);
+    // Handlers run on the server io_context thread pool (the threads
+    // argument of start(), 1 by default), so a blocking one stalls every
+    // connection sharing its thread, not just its own.
+    //
+    // offload=false (default): inline, no thread hop. Right for anything that
+    // returns promptly.
+    // offload=true: runs on ylt's blocking executor while the connection
+    // coroutine suspends, keeping the io_context free. Callers see the same
+    // request/response, but ordering within a connection is no longer
+    // guaranteed.
+    Status registerFunction(int func_id, const Function &func,
+                            bool offload = false);
+
+    // threads: number of io_context worker threads (default 1, the
+    // historical RDMA-only behavior). TCP SendData/RecvData copies are
+    // offloaded off this pool, but attachments are still read here; when
+    // TCP is enabled the engine defaults rpc_server_threads higher so
+    // concurrent bulk transfers are not serialized on one io_context.
+    Status start(uint16_t &port, bool ipv6 = false, size_t threads = 1);
 
     Status stop();
 
     Status call(const std::string &server_addr, int func_id,
                 const std::string_view &request, std::string &response);
 
+    // Same as call(), but moves the request into the coroutine instead of
+    // copying it, for large payloads.
+    Status callOwned(const std::string &server_addr, int func_id,
+                     std::string request, std::string &response);
+
     using AsyncCallback = std::function<void(Status, std::string)>;
     void callAsync(const std::string &server_addr, int func_id,
                    const std::string &request, AsyncCallback callback);
@@ -82,21 +104,25 @@ class CoroRpcAgent {
         std::string server_addr, int func_id, std::string request);
 
    private:
-    void process(int func_id);
+    async_simple::coro::Lazy<void> process(int func_id);
 
     std::shared_ptr<ClientPool> getOrCreatePool(const std::string &server_addr);
 
    private:
+    struct Handler {
+        Function func;
+        bool offload = false;
+    };
+
     coro_rpc::coro_rpc_server *server_ = nullptr;
 
     std::mutex pools_mutex_;
     std::unordered_map<std::string, std::shared_ptr<ClientPool>> pools_;
 
     std::mutex func_map_mutex_;
-    std::unordered_map<int, Function> func_map_;
+    std::unordered_map<int, Handler> func_map_;
 
     std::atomic<bool> running_{false};
-    constexpr static size_t kRpcThreads = 1;
 };
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/admission_queue.h b/mooncake-transfer-engine/tent/include/tent/runtime/admission_queue.h
index f0aabbd8a4..5623e9194e 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/admission_queue.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/admission_queue.h
@@ -51,12 +51,13 @@ struct QueueLimits {
     // it does not admit/reject or otherwise change what gets dispatched.
     bool deadline_aware{false};
     // Opt-in deadline-infeasible drop (RFC #2519 step 3). Local-decode MLU
-    // threshold θ_local. 0 (default) disables drop entirely — behavior is the
-    // step-2 EDF ordering (or FIFO). When > 0 (e.g. 1.5) and a bandwidth
-    // provider is set, an owner whose predicted MLU
-    // (= predicted_transfer_time / remaining_window) reaches this threshold is
-    // dropped instead of dispatched, and on_local_decode_suggested is raised so
-    // the caller can recompute locally. Requires deadline_aware = true.
+    // threshold θ_local. <= 0 (default 0) disables drop entirely — behavior is
+    // the step-2 EDF ordering (or FIFO). When > 0 (e.g. 1.5) and a bandwidth
+    // provider is set, an owner whose predicted MLU (see DeadlineMlu:
+    // (eligible bytes already dispatched + length) / bandwidth, over the
+    // remaining window) reaches this threshold is dropped instead of
+    // dispatched, and on_local_decode_suggested is raised so the caller can
+    // recompute locally. Requires deadline_aware = true.
     double mlu_local_threshold{0.0};
     // Opt-in deadline proximity promotion. When > 0, pickForDispatch promotes
     // queued owners whose remaining slack (deadline_ns - now) is below this
@@ -79,9 +80,11 @@ struct QueueOwnerInput {
     // process-wide aggregate across unrelated transports.
     TransportType transport{UNSPEC};
     // True only when the caller has established that this owner's transfer
-    // time is governed by the installed bandwidth provider. Default false
-    // keeps degradation explicitly opt-in so a new enqueue path cannot
-    // accidentally apply an RDMA EWMA to MNNVL/TCP/staging paths.
+    // time is governed by the installed bandwidth provider -- for the RDMA
+    // wiring, the aggregate transmit estimate over the local NICs. Default
+    // false keeps degradation explicitly opt-in so a new enqueue path cannot
+    // accidentally predict an MNNVL/TCP/staging transfer, whose completion
+    // time that estimate says nothing about, from an RDMA wire rate.
     bool degradation_eligible{false};
 };
 
@@ -100,9 +103,13 @@ struct DegradationHooks {
     std::function<void(const Request&)> on_local_decode_suggested;
 };
 
-// Returns the predicted transfer bandwidth in bytes/second, or <= 0 if unknown
-// (in which case the drop decision is skipped). Injected by the owner so the
-// admission queue does not depend on the device-selection layer directly.
+// Returns the rate at which the bytes of a degradation-eligible owner move on
+// the wire, in bytes/second, or <= 0 if unknown (in which case the drop
+// decision is skipped). This is a transmit rate, not a rate that folds in the
+// wait behind other work: queueing enters the prediction separately, as
+// DeadlineMlu's `bytes_ahead`. The RDMA wiring supplies the sum of the local
+// NICs' transmit estimates. Injected by the owner so the admission queue does
+// not depend on the device-selection layer directly.
 using BandwidthProvider = std::function<double()>;
 
 // Transport-aware variant used when more than one network transport can be
@@ -169,6 +176,9 @@ class LocalTransferAdmissionQueue {
 
     size_t outstandingBytes() const;
 
+    // Bytes of degradation-eligible owners currently Dispatching.
+    size_t dispatchingBytes() const;
+
    private:
     enum class QueueState {
         Queued,
@@ -196,6 +206,10 @@ class LocalTransferAdmissionQueue {
     size_t outstanding_bytes_{0};
     size_t outstanding_user_owners_{0};
     size_t outstanding_user_bytes_{0};
+    // Bytes of degradation-eligible owners dispatched and not yet completed:
+    // the queue-ahead term of the step-3 drop prediction. Owners on other
+    // transports share the queue but not the provider's bandwidth.
+    size_t dispatching_bytes_{0};
 
     // RFC #2519 step 3 degradation policy (all optional / opt-in).
     BandwidthProvider bandwidth_provider_;
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/amd_location.h b/mooncake-transfer-engine/tent/include/tent/runtime/amd_location.h
new file mode 100644
index 0000000000..fee25ef5cc
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/amd_location.h
@@ -0,0 +1,41 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+
+// Self-contained AMD GPU location-prefix helpers, shared by the TENT
+// runtime (topology.h) and the out-of-tree rocm device plugin, which
+// cannot pull in the full runtime headers.
+#ifndef TENT_RUNTIME_AMD_LOCATION_H
+#define TENT_RUNTIME_AMD_LOCATION_H
+
+#include <string>
+
+namespace mooncake {
+namespace tent {
+
+// Canonical AMD GPU location type — the component before ':' in location
+// strings such as "hip:0" (no trailing colon in the constant itself).
+// Matches classic TE GPU_PREFIX ("hip:") so location strings and custom NIC
+// matrices can be shared across backends.
+// "rocm" remains a parse-only alias for existing TENT configs.
+inline constexpr const char kAmdGpuLocationType[] = "hip";
+inline constexpr const char kAmdGpuLocationTypeAlias[] = "rocm";
+
+inline bool isAmdGpuLocationType(const std::string& type) {
+    return type == kAmdGpuLocationType || type == kAmdGpuLocationTypeAlias;
+}
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_RUNTIME_AMD_LOCATION_H
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/control_plane.h b/mooncake-transfer-engine/tent/include/tent/runtime/control_plane.h
index 72822a0f5c..ab1ce5f3e1 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/control_plane.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/control_plane.h
@@ -19,6 +19,8 @@
 #include <netdb.h>
 
 #include <atomic>
+#include <chrono>
+#include <condition_variable>
 #include <cstdint>
 #include <functional>
 #include <memory>
@@ -28,6 +30,7 @@
 #include <thread>
 #include <unordered_map>
 #include <variant>
+#include <limits>
 
 #include "tent/runtime/metastore.h"
 #include "tent/runtime/segment.h"
@@ -45,7 +48,7 @@ struct BootstrapDesc {
     std::string peer_nic_path;
     std::vector<uint32_t> qp_num;
     // RDMA address of local_nic_path.
-    uint16_t local_lid = 0;
+    uint32_t local_lid = 0;
     std::string local_gid;
     std::string reply_msg;       // on error
     uint32_t notify_qp_num = 0;  // Notification QP number (0 = not supported)
@@ -120,6 +123,16 @@ struct XferDataDesc {
     size_t length;
 };
 
+// Standard TCP RPC payload boundaries. READ retains the server's 1 GiB cap;
+// WRITE uses a 32-bit RPC attachment that includes XferDataDesc.
+inline constexpr size_t kTcpMaxReadBytes = size_t{1} << 30;
+inline constexpr size_t kTcpMaxWriteBytes =
+    std::numeric_limits<uint32_t>::max() - sizeof(XferDataDesc);
+
+inline constexpr size_t tcpMaxTransferBytes(Request::OpCode opcode) {
+    return opcode == Request::READ ? kTcpMaxReadBytes : kTcpMaxWriteBytes;
+}
+
 using OnReceiveBootstrap =
     std::function<int(const BootstrapDesc& request, BootstrapDesc& response)>;
 
@@ -142,6 +155,11 @@ class ControlClient {
                             const BootstrapDesc& request,
                             BootstrapDesc& response);
 
+    // Parse a BootstrapRdma RPC body. A non-empty reply_msg or missing GID is
+    // a handshake failure even when the RPC transport itself succeeded.
+    static Status decodeBootstrapResponse(const std::string& response_raw,
+                                          BootstrapDesc& response);
+
     static Status bootstrapUb(const std::string& server_addr,
                               const UbBootstrapDesc& request,
                               UbBootstrapDesc& response);
@@ -162,12 +180,22 @@ class ControlClient {
     static Status delegate(const std::string& server_addr,
                            const Request& request);
 
+    using DelegateCallback = std::function<void(Status, bool confirmed)>;
+    static void delegateAsync(const std::string& server_addr,
+                              const Request& request,
+                              DelegateCallback callback);
+
     static Status pinStageBuffer(const std::string& server_addr,
                                  const std::string& location, uint64_t& addr);
 
     static Status unpinStageBuffer(const std::string& server_addr,
                                    uint64_t addr);
 
+    using UnpinStageBufferCallback = std::function<void(Status)>;
+    static void unpinStageBufferAsync(const std::string& server_addr,
+                                      uint64_t addr,
+                                      UnpinStageBufferCallback callback);
+
     static void subscribeSegmentUpdateAsync(const std::string& server_addr,
                                             const std::string& subscriber_addr);
 
@@ -189,20 +217,16 @@ class ControlService {
 
     SegmentManager& segmentManager() { return *manager_.get(); }
 
-    void setBootstrapRdmaCallback(const OnReceiveBootstrap& callback) {
-        bootstrap_callback_ = callback;
-    }
+    void setBootstrapRdmaCallback(const OnReceiveBootstrap& callback);
 
     void setBootstrapUbCallback(const OnReceiveUbBootstrap& callback) {
         std::lock_guard<std::mutex> lock(ub_bootstrap_callback_mutex_);
         ub_bootstrap_callback_ = callback;
     }
 
-    void setNotifyCallback(const OnNotify& callback) {
-        notify_callback_ = callback;
-    }
+    void setNotifyCallback(const OnNotify& callback);
 
-    Status start(uint16_t& port, bool ipv6_ = false);
+    Status start(uint16_t& port, bool ipv6_ = false, size_t threads = 1);
 
    private:
     void onGetSegmentDesc(const std::string_view& request,
@@ -235,14 +259,30 @@ class ControlService {
     void onSegmentUpdated(const std::string_view& request,
                           std::string& response);
 
+    void finishBootstrapCallback();
+
+    void finishNotifyCallback();
+
    private:
     std::unique_ptr<SegmentManager> manager_;
     std::shared_ptr<CoroRpcAgent> rpc_server_;
 
+    std::mutex bootstrap_cb_mutex_;
+    std::condition_variable bootstrap_cb_cv_;
+    size_t bootstrap_callbacks_in_flight_ = 0;
+    std::chrono::milliseconds callback_drain_timeout_{std::chrono::seconds(5)};
     OnReceiveBootstrap bootstrap_callback_;
+    static thread_local const ControlService* active_bootstrap_service_;
+
     std::mutex ub_bootstrap_callback_mutex_;
     OnReceiveUbBootstrap ub_bootstrap_callback_;
+
+    std::mutex notify_cb_mutex_;
+    std::condition_variable notify_cb_cv_;
+    size_t notify_callbacks_in_flight_ = 0;
     OnNotify notify_callback_;
+    static thread_local const ControlService* active_notify_service_;
+
     TransferEngineImpl* impl_;
 };
 
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/deadline_mlu.h b/mooncake-transfer-engine/tent/include/tent/runtime/deadline_mlu.h
new file mode 100644
index 0000000000..b19d41b6a9
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/deadline_mlu.h
@@ -0,0 +1,69 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+//
+// The one definition of a request's predicted deadline feasibility (MLU),
+// shared by the admission queue's drop predictor (RFC #2519 step 3) and the
+// RDMA workers' bandwidth arbitration (RFC #2792). Both must apply the same
+// formula to the same bandwidth series, or the admission layer can drop a
+// flow the NIC layer just promoted.
+//
+// The two layers deliberately do NOT read the same `bytes_ahead`. Each counts
+// the bytes it can actually see ahead of the request at its decision point:
+//   * admission decides before the request reaches a worker, so everything
+//     dispatched and not yet completed precedes it (`dispatching_bytes_`,
+//     which includes slices still sitting in worker queues);
+//   * arbitration decides at posting time, when the worker-queue slices are
+//     its own contenders, so only the hardware backlog (`getPostedBytes`)
+//     plus the slots already ordered ahead of it precede a slot.
+// The drop side therefore reads the wider set. That is the intended way
+// round: the drop is the irreversible decision, so it is the conservative
+// one. Weigh the necessity carefully before changing this asymmetry in
+// either direction.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+
+namespace mooncake {
+namespace tent {
+
+// Predicted MLU = predicted completion time / remaining deadline window,
+// where predicted completion time = (bytes_ahead + length) / bw_bps.
+//
+// The deadline is absolute, so the request must first wait for the bytes
+// already in the pipeline ahead of it (`bytes_ahead`: whatever the calling
+// layer can see ahead of the request, see the file comment) and then spend
+// its own wire time. Queueing is therefore an additive term over the wire
+// rate -- not folded into a slower bandwidth, which would scale the wait by
+// the request's size.
+//
+// Higher == more urgent. No deadline (deadline_ns == 0) or no usable
+// bandwidth (bw_bps <= 0) yields 0: nothing to predict, so never urgent and
+// never dropped. A deadline already reached is infinitely urgent.
+inline double DeadlineMlu(size_t bytes_ahead, size_t length,
+                          uint64_t deadline_ns, uint64_t now_ns,
+                          double bw_bps) {
+    if (deadline_ns == 0 || bw_bps <= 0.0) return 0.0;
+    if (deadline_ns <= now_ns) return std::numeric_limits<double>::max();
+    const double window_s = (deadline_ns - now_ns) / 1e9;
+    const double predicted_time_s =
+        (static_cast<double>(bytes_ahead) + static_cast<double>(length)) /
+        bw_bps;
+    return predicted_time_s / window_s;
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/hp_tcp_transport_config.h b/mooncake-transfer-engine/tent/include/tent/runtime/hp_tcp_transport_config.h
new file mode 100644
index 0000000000..789c2bd0bb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/hp_tcp_transport_config.h
@@ -0,0 +1,43 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_RUNTIME_HP_TCP_TRANSPORT_CONFIG_H_
+#define TENT_RUNTIME_HP_TCP_TRANSPORT_CONFIG_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+
+namespace mooncake::tent {
+
+struct HighPerformanceTcpParams {
+    std::string bind_address;
+    std::string advertise_address;
+    // Ordered local rail addresses; peers must publish the same rail count.
+    std::vector<std::string> rail_addresses;
+    uint16_t port{0};
+    size_t worker_count{16};
+    size_t connections_per_peer{4};
+    uint64_t max_outstanding_tasks{4096};
+    uint64_t max_outstanding_bytes{1ULL << 32};
+    uint64_t max_transfer_bytes{1ULL << 30};
+    uint64_t connect_timeout_ms{2000};
+    uint64_t progress_timeout_ms{30000};
+    // Release pooled sockets only when the client has no work on the lane.
+    uint64_t idle_connection_timeout_ms{60000};
+};
+
+struct HpTcpTransportConfig {
+    bool enabled{false};
+    HighPerformanceTcpParams params;
+};
+
+// This is intentionally the sole parser for transports/hp_tcp. Config::get()
+// silently substitutes defaults for type mismatches and is not suitable here.
+Status ParseHpTcpTransportConfig(const Config& config,
+                                 HpTcpTransportConfig* out);
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_RUNTIME_HP_TCP_TRANSPORT_CONFIG_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/platform.h b/mooncake-transfer-engine/tent/include/tent/runtime/platform.h
index e53265adb0..fa13b0414a 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/platform.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/platform.h
@@ -20,10 +20,32 @@
 namespace mooncake {
 namespace tent {
 
-// MTYPE_TPU is appended last so the numeric values of the existing entries are
-// preserved. TPU HBM is not NIC-addressable, so transfers touching it are
-// staged through host DRAM by ProxyManager (see findStagingPolicy).
-enum MemoryType { MTYPE_UNKNOWN, MTYPE_CPU, MTYPE_CUDA, MTYPE_ROCM, MTYPE_TPU };
+// New device memory types are appended last so the numeric values of the
+// existing entries are preserved. TPU HBM and Intel XPU VRAM are not
+// NIC-addressable in the MVP, so transfers touching them are staged through
+// host DRAM by ProxyManager (see findStagingPolicy). Any device memory type
+// added here must also be reported by isGpuMemoryType() below, so the
+// selector's routing predicate and the staging capability checks stay in
+// agreement.
+enum MemoryType {
+    MTYPE_UNKNOWN,
+    MTYPE_CPU,
+    MTYPE_CUDA,
+    MTYPE_ROCM,
+    MTYPE_TPU,
+    MTYPE_XPU
+};
+
+// Single source of truth for "is this a device (GPU/NPU/TPU/XPU) memory type?".
+// Both the selector's routing predicate and the staging capability checks
+// consult this, so a device memory type can never be classified as a device on
+// one path and as host on the other. Device types stage their device<->host hop
+// through the matching transport (gpu_to_dram / dram_to_gpu) and never satisfy
+// gpu_to_gpu in the MVP.
+inline bool isGpuMemoryType(MemoryType t) {
+    return t == MTYPE_CUDA || t == MTYPE_ROCM || t == MTYPE_TPU ||
+           t == MTYPE_XPU;
+}
 
 class Platform {
    public:
@@ -49,9 +71,18 @@ class Platform {
         void *start, size_t len, bool skip_prefault = false) = 0;
 
     virtual const std::string type() const = 0;
+
+    // Make GPUDirect / device DMA visible on devices named in `topology`.
+    // GPU platforms flush those devices; CPU and others no-op. Failures are
+    // logged and still return OK so teardown can continue.
+    virtual Status synchronizeDevices(const Topology *topology);
+
+   protected:
+    static std::vector<int> topologyDeviceIndices(const Topology *topology,
+                                                  Topology::MemType mem_type);
 };
 
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // PLATFORM_H
\ No newline at end of file
+#endif  // PLATFORM_H
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/proxy_manager.h b/mooncake-transfer-engine/tent/include/tent/runtime/proxy_manager.h
index 959197cac3..31bb52882c 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/proxy_manager.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/proxy_manager.h
@@ -15,9 +15,12 @@
 #ifndef PROXY_MANAGER_H_
 #define PROXY_MANAGER_H_
 
+#include <chrono>
+#include <memory>
+#include <shared_mutex>
+
 #include "tent/common/types.h"
 #include "tent/common/status.h"
-#include "tent/common/concurrent/thread_pool.h"
 
 #include "tent/runtime/transport.h"
 
@@ -28,6 +31,9 @@ namespace tent {
 class TransferEngineImpl;
 class TaskInfo;
 struct StageBufferCache;
+namespace internal {
+class RemoteStageOperation;
+}
 
 struct StagingTask {
     TaskInfo* native{nullptr};
@@ -64,7 +70,11 @@ class ProxyManager {
    private:
     void runner(size_t id);
 
-    Status transferEventLoop(StagingTask& task, StageBufferCache* cache);
+    Status transferEventLoop(
+        StagingTask& task, StageBufferCache* cache,
+        bool& buffers_safe_to_release, std::vector<BatchID>& undrained_batches,
+        std::vector<std::shared_ptr<internal::RemoteStageOperation>>&
+            undrained_remote_operations);
 
     Status transferSync(StagingTask& task, StageBufferCache* cache);
 
@@ -91,16 +101,40 @@ class ProxyManager {
                            const Request& request, uint64_t remote_stage_buffer,
                            uint64_t chunk_length, uint64_t offset);
 
-    void submitRemoteStage(const std::string& server_addr,
-                           const Request& request, uint64_t remote_stage_buffer,
-                           uint64_t chunk_length, uint64_t offset,
-                           std::future<Status>& handle);
+    void submitRemoteStage(
+        const std::string& server_addr, const Request& request,
+        uint64_t remote_stage_buffer, uint64_t chunk_length, uint64_t offset,
+        std::shared_ptr<internal::RemoteStageOperation>& operation);
+
+    void flushPendingCleanups(bool unpin_remote_buffers = true);
 
    private:
+    struct PendingBufferCleanup {
+        std::vector<uint64_t> local_addrs;
+        std::vector<std::pair<std::string, uint64_t>> remote_addrs;
+        std::vector<BatchID> batches;
+        std::vector<std::shared_ptr<internal::RemoteStageOperation>>
+            remote_operations;
+    };
+
     const size_t chunk_size_;
     const size_t chunk_count_;
     TransferEngineImpl* impl_;
+    // How long deconstruct() waits for in-flight staging batches to reach a
+    // terminal state before handing the survivors to the engine for deferred
+    // teardown. Read from "staging/shutdown_drain_timeout_ms" so a regression
+    // test can exercise the timeout path without the 30s default.
+    const std::chrono::milliseconds shutdown_drain_timeout_;
+    // Guards the map, not the chunk bitmaps in it: those are atomic_flags and
+    // stay lock-free under a shared lock. Exclusive only to insert or erase an
+    // entry, at most once per location. Reached by the kShards staging workers
+    // via StageBufferCache and by the RPC thread via Pin/Unpin.
+    mutable std::shared_mutex stage_buffers_mutex_;
     std::unordered_map<std::string, StageBuffers> stage_buffers_;
+    std::recursive_mutex stage_buffers_mu_;
+    std::vector<PendingBufferCleanup> pending_cleanups_;
+    std::mutex pending_cleanups_mu_;
+    std::atomic<bool> has_pending_cleanups_{false};
     std::atomic<bool> running_;
     struct WorkerShard {
         std::thread thread;
@@ -110,7 +144,6 @@ class ProxyManager {
     };
     const static size_t kShards = 8;
     WorkerShard shards_[kShards];
-    ThreadPool delegate_pool_;
 };
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/segment.h b/mooncake-transfer-engine/tent/include/tent/runtime/segment.h
index e913abe9d2..63d73df312 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/segment.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/segment.h
@@ -47,7 +47,7 @@ struct DeviceDesc {
     std::unordered_map<TransportType, std::string> transport_attrs;
 
     // backward compatilble
-    uint16_t lid;
+    uint32_t lid;
     std::string gid;
 
    public:
@@ -79,6 +79,8 @@ struct BufferDesc {
     std::vector<uint32_t> lkey;  // not uploaded, available in local only
 
     bool internal{false};
+    // Local registration policy, deliberately excluded from JSON metadata.
+    Permission permission{kGlobalReadWrite};
 
    public:
     NLOHMANN_DEFINE_TYPE_INTRUSIVE(BufferDesc, addr, length, location,
@@ -295,4 +297,4 @@ inline std::vector<Region> coalesceRegions(
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // SEGMENT_H
\ No newline at end of file
+#endif  // SEGMENT_H
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/segment_tracker.h b/mooncake-transfer-engine/tent/include/tent/runtime/segment_tracker.h
index a32aec8d27..db46e32059 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/segment_tracker.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/segment_tracker.h
@@ -48,8 +48,10 @@ class SegmentTracker {
     SegmentTracker& operator==(const SegmentTracker&) = delete;
 
    public:
+    // on_removed runs after rollback publication, outside the writer lock.
     Status addInBatch(std::vector<BufferDesc>& desc_list,
-                      std::function<Status(std::vector<BufferDesc>&)> callback);
+                      std::function<Status(std::vector<BufferDesc>&)> callback,
+                      std::function<void(BufferDesc&)> on_removed = {});
 
     Status add(uint64_t base, size_t length,
                std::function<Status(BufferDesc&)> callback);
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/topology.h b/mooncake-transfer-engine/tent/include/tent/runtime/topology.h
index d0c8d0524a..01f23c8182 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/topology.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/topology.h
@@ -31,6 +31,7 @@
 
 #include "tent/common/config.h"
 #include "tent/common/status.h"
+#include "tent/runtime/amd_location.h"
 namespace mooncake {
 namespace tent {
 class Platform;
@@ -79,14 +80,22 @@ class Topology {
 
     void clear();
 
-    // Preserve the original one-argument symbol for source and binary
-    // compatibility with callers that do not opt into UB discovery.
     Status discover(const std::vector<Platform*>& platforms);
 
-    Status discover(const std::vector<Platform*>& platforms, bool discover_ub);
-
     Status parse(const std::string& json_content);
 
+    // Parse classic TE NIC priority matrix:
+    // {"cpu:0": [["mlx5_0"], ["mlx5_1"]], ...}
+    // preferred → device_list[rank0], avail → device_list[rank1].
+    Status parsePriorityMatrix(const std::string& json_content);
+
+    // Auto-detect native {"nics","mems"} JSON vs classic priority matrix.
+    Status parseCustomTopology(const std::string& json_content);
+
+    // Load topology from Config (inline matrix / file path) or discover.
+    Status loadFromConfig(const Config& conf,
+                          const std::vector<Platform*>& platforms);
+
     std::string toString() const;
 
     void print() const;
@@ -103,6 +112,10 @@ class Topology {
 
     const MemEntry* getMemEntry(const std::string& name) const;
 
+    // True only when both NUMA ids are known and differ. Unknown (-1) is not
+    // treated as remote; rank is ignored because probes disagree on placement.
+    bool isCrossNuma(const MemEntry& mem, NicID nic_id) const;
+
     NicID getNicId(const std::string& name) const;
 
     MemID getMemId(const std::string& name) const;
@@ -147,6 +160,35 @@ class LocationParser {
     int index_;
 };
 
+// Canonical AMD GPU location prefix and alias handling live in
+// amd_location.h, shared with the rocm device plugin.
+
+inline std::string makeAmdGpuLocation(int device) {
+    return std::string(kAmdGpuLocationType) + ":" + std::to_string(device);
+}
+
+// Canonicalize the legacy AMD alias: "rocm:N" becomes "hip:N". All other
+// location strings (including malformed ones) are returned unchanged.
+// Applied where names enter or leave topology storage so entries stored
+// under a legacy matrix key remain reachable via canonical names.
+inline std::string canonicalizeLocation(const std::string& location) {
+    LocationParser parser(location);
+    if (isAmdGpuLocationType(parser.type()) && parser.index() >= 0) {
+        return makeAmdGpuLocation(parser.index());
+    }
+    return location;
+}
+
+inline Topology::MemType memTypeFromLocation(const std::string& location) {
+    LocationParser parser(location);
+    const auto type = parser.type();
+    if (type == "cpu") return Topology::MEM_HOST;
+    if (type == "cuda" || type == "gpu") return Topology::MEM_CUDA;
+    if (isAmdGpuLocationType(type)) return Topology::MEM_ROCM;
+    if (type == "ascend" || type == "npu") return Topology::MEM_ASCEND;
+    return Topology::MEM_UNKNOWN;
+}
+
 struct RangeLocation {
     uint64_t start;
     size_t len;
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/transfer_engine_impl.h b/mooncake-transfer-engine/tent/include/tent/runtime/transfer_engine_impl.h
index 38b1189987..bb1417fef2 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/transfer_engine_impl.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/transfer_engine_impl.h
@@ -28,13 +28,16 @@
 #include <vector>
 
 #include "tent/common/config.h"
+#include "tent/common/config_lifecycle.h"
 #include "tent/common/status.h"
 #include "tent/common/types.h"
 #include "tent/runtime/admission_queue.h"
 #include "tent/runtime/transport.h"
 #include "tent/runtime/transport_selector.h"
+#include "tent/runtime/hp_tcp_transport_config.h"
 
 namespace mooncake {
+class TransferEngineImplTestPeer;
 namespace tent {
 
 class Batch;
@@ -48,19 +51,41 @@ class Platform;
 class ProxyManager;
 class ProgressWorker;
 
+// How long a poll loop should pause before polling again. Zero means poll
+// immediately.
+//
+// progressBatch takes progress_mutex_ every call, so an unthrottled loop does
+// not just burn a core -- it contends with every other thread's submit and
+// poll path. Hot for the first iterations so short transfers keep their
+// latency, then exponential backoff to a cap.
+std::chrono::microseconds nextPollDelay(uint64_t poll_count);
+
+// One backoff step: yields while nextPollDelay is zero, sleeps after that.
+void waitBeforeNextPoll(uint64_t poll_count);
+
+struct LogicalTransferRuntimePolicy {
+    uint64_t config_generation{0};
+    int max_failover_attempts{kDefaultMaxFailoverAttempts};
+    bool enable_auto_failover_on_poll{kDefaultAutoFailoverOnPoll};
+};
+
 struct TaskInfo {
     TransportType type{UNSPEC};
     int sub_task_id{-1};
-    bool derived{false};          // merged by other tasks
-    int xport_priority{0};        // transport priority (for fallback)
-    int failover_count{0};        // number of failover attempts
+    bool derived{false};                  // merged by other tasks
+    int xport_priority{0};                // transport priority (for fallback)
+    int failover_count{0};                // number of failover attempts
+    int metadata_refresh_retry_count{0};  // same-transport stale-cache retries
+    bool suppress_failover{false};        // permanent transport result
+    LogicalTransferRuntimePolicy runtime_policy;
     uint64_t device_mask{~0ULL};  // Device mask for quota allocation
     std::string qp_pool;          // Named QP pool (RFC #2568 step 3), "" = none
     Request request;
+    size_t public_length{0};  // Original API request; request may be merged.
     bool staging{false};
     bool cancel_requested{false};
     TransferStatusEnum status{TransferStatusEnum::PENDING};
-    volatile TransferStatusEnum staging_status{TransferStatusEnum::PENDING};
+    std::atomic<TransferStatusEnum> staging_status{TransferStatusEnum::PENDING};
     std::chrono::steady_clock::time_point start_time{};     // Request submit
     std::chrono::steady_clock::time_point dispatch_time{};  // Initial dispatch
     std::chrono::steady_clock::time_point post_time{};      // Initial post
@@ -72,10 +97,133 @@ struct TaskInfo {
     std::chrono::steady_clock::time_point attempt_post_time{};
     TransportType attempt_type{UNSPEC};
     bool attempt_active{false};
+    // Failure attribution for tent_task_failures_total (first failure wins):
+    // -1 = none, 0 = submit-stage, 1 = poll-stage. Set where the failure
+    // originates and never overwritten, so a poll-observed failure stays
+    // "poll" even when a later failover resubmit is synchronously rejected.
+    // Invariant for integrators: mark submit failures before any recovery
+    // attempt, so a task that recovers and later fails at poll still
+    // attributes its root cause to submit.
+    int8_t failure_stage{-1};
+
+    TaskInfo() = default;
+
+    TaskInfo(const TaskInfo& other)
+        : type(other.type),
+          sub_task_id(other.sub_task_id),
+          derived(other.derived),
+          xport_priority(other.xport_priority),
+          failover_count(other.failover_count),
+          metadata_refresh_retry_count(other.metadata_refresh_retry_count),
+          suppress_failover(other.suppress_failover),
+          runtime_policy(other.runtime_policy),
+          device_mask(other.device_mask),
+          qp_pool(other.qp_pool),
+          request(other.request),
+          public_length(other.public_length),
+          staging(other.staging),
+          cancel_requested(other.cancel_requested),
+          status(other.status),
+          staging_status(other.staging_status.load(std::memory_order_relaxed)),
+          start_time(other.start_time),
+          dispatch_time(other.dispatch_time),
+          post_time(other.post_time),
+          attempt_post_time(other.attempt_post_time),
+          attempt_type(other.attempt_type),
+          attempt_active(other.attempt_active),
+          failure_stage(other.failure_stage) {}
+
+    TaskInfo(TaskInfo&& other) noexcept
+        : type(other.type),
+          sub_task_id(other.sub_task_id),
+          derived(other.derived),
+          xport_priority(other.xport_priority),
+          failover_count(other.failover_count),
+          metadata_refresh_retry_count(other.metadata_refresh_retry_count),
+          suppress_failover(other.suppress_failover),
+          runtime_policy(other.runtime_policy),
+          device_mask(other.device_mask),
+          qp_pool(std::move(other.qp_pool)),
+          request(std::move(other.request)),
+          public_length(other.public_length),
+          staging(other.staging),
+          cancel_requested(other.cancel_requested),
+          status(other.status),
+          staging_status(other.staging_status.load(std::memory_order_relaxed)),
+          start_time(other.start_time),
+          dispatch_time(other.dispatch_time),
+          post_time(other.post_time),
+          attempt_post_time(other.attempt_post_time),
+          attempt_type(other.attempt_type),
+          attempt_active(other.attempt_active),
+          failure_stage(other.failure_stage) {}
+
+    TaskInfo& operator=(const TaskInfo& other) {
+        if (this != &other) {
+            type = other.type;
+            sub_task_id = other.sub_task_id;
+            derived = other.derived;
+            xport_priority = other.xport_priority;
+            failover_count = other.failover_count;
+            metadata_refresh_retry_count = other.metadata_refresh_retry_count;
+            suppress_failover = other.suppress_failover;
+            runtime_policy = other.runtime_policy;
+            device_mask = other.device_mask;
+            qp_pool = other.qp_pool;
+            request = other.request;
+            public_length = other.public_length;
+            staging = other.staging;
+            cancel_requested = other.cancel_requested;
+            status = other.status;
+            staging_status.store(
+                other.staging_status.load(std::memory_order_relaxed),
+                std::memory_order_relaxed);
+            start_time = other.start_time;
+            dispatch_time = other.dispatch_time;
+            post_time = other.post_time;
+            attempt_post_time = other.attempt_post_time;
+            attempt_type = other.attempt_type;
+            attempt_active = other.attempt_active;
+            failure_stage = other.failure_stage;
+        }
+        return *this;
+    }
+
+    TaskInfo& operator=(TaskInfo&& other) noexcept {
+        if (this != &other) {
+            type = other.type;
+            sub_task_id = other.sub_task_id;
+            derived = other.derived;
+            xport_priority = other.xport_priority;
+            failover_count = other.failover_count;
+            metadata_refresh_retry_count = other.metadata_refresh_retry_count;
+            suppress_failover = other.suppress_failover;
+            runtime_policy = other.runtime_policy;
+            device_mask = other.device_mask;
+            qp_pool = std::move(other.qp_pool);
+            request = std::move(other.request);
+            public_length = other.public_length;
+            staging = other.staging;
+            cancel_requested = other.cancel_requested;
+            status = other.status;
+            staging_status.store(
+                other.staging_status.load(std::memory_order_relaxed),
+                std::memory_order_relaxed);
+            start_time = other.start_time;
+            dispatch_time = other.dispatch_time;
+            post_time = other.post_time;
+            attempt_post_time = other.attempt_post_time;
+            attempt_type = other.attempt_type;
+            attempt_active = other.attempt_active;
+            failure_stage = other.failure_stage;
+        }
+        return *this;
+    }
 };
 
 class TransferEngineImpl {
     friend class ProxyManager;
+    friend class ::mooncake::TransferEngineImplTestPeer;
 
    public:
     TransferEngineImpl();
@@ -97,6 +245,9 @@ class TransferEngineImpl {
 
     uint16_t getRpcServerPort() const;
 
+    // Local topology discovered (or loaded from custom matrix) at construct.
+    std::shared_ptr<Topology> getLocalTopology() const;
+
    public:
     Status exportLocalSegment(std::string& shared_handle);
 
@@ -153,8 +304,18 @@ class TransferEngineImpl {
 
     Status cancelTransfer(BatchID batch_id, size_t task_id);
 
+    // Tries every loaded notification transport in slot order. A transport
+    // whose channel is unavailable (endpoint down, no notify QP) is skipped
+    // for the next one, and when all are, the notification goes over the
+    // control-plane RPC the peer answers bootstrap on. Any other error is
+    // returned as is. notification/rpc_fallback=false restores the
+    // first-transport-only behavior.
     Status sendNotification(SegmentID target_id, const Notification& notifi);
 
+    // Drains every loaded notification transport plus the in-process queue,
+    // so a notification lands with the caller no matter which path carried
+    // it. Order is kept within one path only: in a poll, notifications that
+    // took the RPC fallback come after the ones the notify QP carried.
     Status receiveNotification(std::vector<Notification>& notifi_list);
 
     Status probePeerAliveByID(SegmentID target_id);
@@ -191,6 +352,38 @@ class TransferEngineImpl {
         }
     }
 
+    Status publishRuntimeConfigForTest(
+        std::shared_ptr<const RuntimeConfigSnapshot> snapshot) {
+        if (!snapshot) {
+            return Status::InvalidArgument(
+                "Runtime config snapshot must not be null" LOC_MARK);
+        }
+        std::atomic_store_explicit(&runtime_config_snapshot_,
+                                   std::move(snapshot),
+                                   std::memory_order_release);
+        return Status::OK();
+    }
+
+    // Test-only hook: how many batches are still alive. Lets a test assert
+    // that a failed transfer released its batch rather than leaking it.
+    size_t aliveBatchCountForTest() {
+        size_t count = 0;
+        for (auto& shard : batch_shards_) {
+            std::lock_guard<std::recursive_mutex> lk(shard.mtx);
+            count += shard.alive_batches.size();
+        }
+        return count;
+    }
+
+    // Test-only hook: how many undrained staging batches the ProxyManager
+    // handed over for deferred teardown. Lets a regression test assert the
+    // ownership-transfer path ran instead of freeing memory the transport
+    // workers could still touch.
+    size_t deferredStageTeardownBatchCountForTest() {
+        std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
+        return deferred_stage_teardown_.batches.size();
+    }
+
     // Wake the optional event-driven progress worker for `batch_id`. No-op if
     // enable_progress_worker is false. Transport completion paths use this as
     // an idempotent "maybe ready" signal.
@@ -213,12 +406,33 @@ class TransferEngineImpl {
     std::vector<TransportType> getSupportedTransports(
         TransportType request_type);
 
+    void deregisterRemovedBuffer(BufferDesc& desc);
+
     Status resubmitTransferTask(Batch* batch, size_t task_id);
 
+    // Submit-stage failover: recover a task whose synchronous
+    // submitTransferTasks() failed by walking the remaining candidate
+    // transports (bounded by the task's pinned limit), mirroring the poll-time
+    // failover in updateTaskStatusAfterPoll. Returns true when the task is
+    // PENDING again on a fallback transport; otherwise the task is
+    // terminally FAILED with task.type left at the last attempted transport
+    // so failure metrics attribute to a real transport instead of UNSPEC.
+    bool attemptSubmitStageFailover(Batch* batch, size_t task_id);
+
     Status retainBatch(BatchID batch_id, Batch*& batch);
 
     Status releaseBatch(Batch* batch);
 
+    // Called by ProxyManager when its shutdown drain deadline expires: takes
+    // ownership of the batches (and the local stage buffers they target) that
+    // never reached a terminal state, detaching them from batch_set_ /
+    // alive_batches_ so deconstruct() does not hand their SubBatch/Slice
+    // objects back to the Slab while transport workers may still complete
+    // them. Released only after the transports quiesce.
+    struct DeferredStageTeardown;
+
+    void adoptDeferredStageTeardown(DeferredStageTeardown&& deferred);
+
     class BatchRef;
 
     struct PreparedSubmit;
@@ -273,7 +487,7 @@ class TransferEngineImpl {
                                    bool allow_failover);
 
     Status getBatchStatus(BatchID batch_id, TransferStatus& overall_status,
-                          bool allow_failover);
+                          bool force_failover);
 
     SelectionResult resolveTransport(const Request& req, int transport_index,
                                      bool invalidate_on_fail = true);
@@ -283,6 +497,12 @@ class TransferEngineImpl {
 
     Status loadTransports();
 
+    // Control-plane delivery used by sendNotification() once every loaded
+    // notification transport has reported its channel unavailable. Same
+    // wire path as TcpTransport::sendNotification().
+    Status sendNotificationViaRpc(SegmentID target_id,
+                                  const Notification& notifi);
+
     void findStagingPolicy(const Request& req,
                            std::vector<std::string>& policy);
 
@@ -310,9 +530,19 @@ class TransferEngineImpl {
         MemoryOptions options;
     };
 
-    struct BatchSet {
-        std::unordered_set<Batch*> active;
-        std::vector<Batch*> freelist;
+    // Staging resources that ProxyManager could not drain before its shutdown
+    // deadline. Their slices may still be written by transport workers, so
+    // nothing here may be freed before transport_list_ is reset (which joins
+    // the workers and drains the completion queues).
+    struct DeferredStageTeardown {
+        struct StageBuffers {
+            std::string location;
+            void* chunks{nullptr};
+            std::atomic_flag* bitmap{nullptr};
+        };
+        std::vector<BatchID> batches;
+        std::vector<StageBuffers> stage_buffers;
+        bool empty() const { return batches.empty() && stage_buffers.empty(); }
     };
 
     struct RuntimeQueueConfig {
@@ -333,6 +563,7 @@ class TransferEngineImpl {
 
    private:
     std::shared_ptr<Config> conf_;
+    HpTcpTransportConfig hp_tcp_transport_config_;
     std::shared_ptr<ControlService> metadata_;
     std::shared_ptr<Topology> topology_;
     std::unique_ptr<TransportSelector> transport_selector_;
@@ -342,11 +573,14 @@ class TransferEngineImpl {
         transport_list_;
     std::unique_ptr<SegmentTracker> local_segment_tracker_;
 
-    BatchSet batch_set_;
-
     std::vector<AllocatedMemory> allocated_memory_;
     std::mutex mutex_;
 
+    // Self-targeted notifications (target == LOCAL_SEGMENT_ID) are delivered
+    // in-process rather than through a transport; see sendNotification().
+    std::mutex local_notifi_mutex_;
+    std::vector<Notification> local_notifi_list_;
+
     std::string hostname_;
     uint16_t port_;
     bool ipv6_;
@@ -354,8 +588,8 @@ class TransferEngineImpl {
 
     std::unique_ptr<ProxyManager> staging_proxy_;
     bool merge_requests_;
-    int max_failover_attempts_{3};
-    bool enable_auto_failover_on_poll_{true};
+    std::shared_ptr<const RuntimeConfigSnapshot> runtime_config_snapshot_;
+    bool notify_rpc_fallback_{true};
     bool enable_progress_worker_{false};
     RuntimeQueueConfig runtime_queue_config_;
     std::unique_ptr<LocalTransferAdmissionQueue> runtime_queue_;
@@ -364,13 +598,67 @@ class TransferEngineImpl {
     size_t dispatch_inflight_bytes_{0};
     uint64_t next_batch_token_{1};
 
-    // Guards alive_batches_ and serializes pollTaskStatus /
-    // updateTaskStatusAfterPoll / lazyFreeBatch against the optional
-    // ProgressWorker thread. Recursive because freeBatch -> lazyFreeBatch ->
-    // getTransferStatus can re-enter on the same thread. See issue #2116.
+    // Serializes engine-global progress: runtime queue, lazyFreeBatch
+    // freelist, and ProgressWorker. Recursive because freeBatch ->
+    // lazyFreeBatch -> getTransferStatus can re-enter. See issue #2116.
     std::recursive_mutex progress_mutex_;
-    std::unordered_set<BatchID> alive_batches_;
+    // Guarded by progress_mutex_. Emptied (abandoned on purpose) at the end of
+    // deconstruct(), after the transports have been destroyed.
+    DeferredStageTeardown deferred_stage_teardown_;
     std::unique_ptr<ProgressWorker> progress_worker_;
+
+    // Per-batch hot paths (poll / free / retain) lock only the shard for
+    // that BatchID instead of progress_mutex_, so N threads polling N
+    // independent batches do not serialize.
+    //
+    // Exception: enable_runtime_queue=true keeps those paths on
+    // progress_mutex_ because queued_owners_ / dispatch window are
+    // engine-global. The runtime queue is off by default.
+    //
+    // The batch registry (alive / active membership) lives INSIDE the same
+    // shard: membership changes and lookups are O(1) set ops taken while
+    // already holding the shard lock, so no separate global registry lock
+    // sits on the poll/alloc/free hot path.
+    //
+    // Lock order (never reversed):
+    //   progress_mutex_ -> shard
+    // With the runtime queue enabled, hot paths hold progress_mutex_ and
+    // take the shard only for membership ops:
+    //   progress_mutex_ -> shard (membership only)
+    static constexpr size_t kBatchLockShards = 64;
+    struct BatchShard {
+        std::recursive_mutex mtx;
+        std::unordered_set<Batch*> active_batches;
+        std::unordered_set<BatchID> alive_batches;
+    };
+    BatchShard& batchShard(BatchID batch_id) {
+        return batch_shards_[reinterpret_cast<uintptr_t>(batch_id) %
+                             kBatchLockShards];
+    }
+    std::recursive_mutex& batchShardMutex(BatchID batch_id) {
+        return batchShard(batch_id).mtx;
+    }
+    std::recursive_mutex& progressLockFor(BatchID batch_id) {
+        if (runtime_queue_config_.enabled) return progress_mutex_;
+        return batchShardMutex(batch_id);
+    }
+    // Caller must hold progressLockFor(batch_id). In default mode that is
+    // the shard itself, so the membership check is a lock-free read under
+    // an already-held lock. In queue mode the caller holds progress_mutex_
+    // and we take the shard briefly (progress -> shard order is allowed).
+    bool isBatchAlive(BatchID batch_id) {
+        BatchShard& shard = batchShard(batch_id);
+        if (runtime_queue_config_.enabled) {
+            std::lock_guard<std::recursive_mutex> lk(shard.mtx);
+            return shard.alive_batches.count(batch_id) != 0;
+        }
+        return shard.alive_batches.count(batch_id) != 0;
+    }
+    std::array<BatchShard, kBatchLockShards> batch_shards_;
+    // Deferred-free queue, guarded by progress_mutex_. Only used when the
+    // fast path cannot free inline (tasks still in flight, runtime refs,
+    // or runtime queue enabled).
+    std::vector<Batch*> batch_freelist_;
 };
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/transport.h b/mooncake-transfer-engine/tent/include/tent/runtime/transport.h
index 93bf585a9c..0299475a7a 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/transport.h
@@ -79,6 +79,11 @@ class Transport {
 
     virtual Status uninstall() { return Status::OK(); }
 
+    // Called before registered ranges and sub-batches are reclaimed.  Most
+    // transports have no background work; transports with async I/O use this
+    // barrier to settle work while their buffer registry is still alive.
+    virtual Status quiesce() { return Status::OK(); }
+
     virtual const Capabilities capabilities() const { return caps; }
 
     virtual Status allocateSubBatch(SubBatchRef& batch, size_t max_size) {
@@ -90,6 +95,15 @@ class Transport {
         return Status::NotImplemented("freeSubBatch not implemented" LOC_MARK);
     }
 
+    // Submission contract (all-or-nothing): on an error return, no request
+    // from request_list may have been dispatched and the sub-batch must be
+    // left exactly as it was before the call (no tasks appended, no work
+    // queued). A transport that starts accepting requests and then hits an
+    // error must roll back its partial state before returning. This lets the
+    // engine fail the whole submission over to another transport without
+    // double-executing an accepted prefix or losing track of the original
+    // sub-batch. Transports that validate requests incrementally must
+    // validate every request before dispatching any of them.
     virtual Status submitTransferTasks(
         SubBatchRef batch, const std::vector<Request>& request_list) {
         return Status::NotImplemented(
@@ -102,6 +116,12 @@ class Transport {
             "getTransferStatus not implemented" LOC_MARK);
     }
 
+    virtual Status retryTransferTask(SubBatchRef batch, int task_id,
+                                     const Request& request) {
+        return Status::NotImplemented(
+            "retryTransferTask not implemented" LOC_MARK);
+    }
+
     // Cancellation is best effort: implementations must prevent work that has
     // not reached the device from being submitted, but work already posted to
     // a device may still complete. Callers must continue polling until the
@@ -146,6 +166,10 @@ class Transport {
             "removeMemoryBuffer not implemented" LOC_MARK);
     }
 
+    // Some transports keep private local-only registrations that must not be
+    // advertised through BufferDesc::transports.
+    virtual bool tracksLocalBuffer(const BufferDesc&) const { return false; }
+
     virtual bool supportNotification() const { return false; }
 
     virtual Status sendNotification(SegmentID target_id,
diff --git a/mooncake-transfer-engine/tent/include/tent/runtime/transport_selector.h b/mooncake-transfer-engine/tent/include/tent/runtime/transport_selector.h
index 63773ceeb2..3cb7fa14b8 100644
--- a/mooncake-transfer-engine/tent/include/tent/runtime/transport_selector.h
+++ b/mooncake-transfer-engine/tent/include/tent/runtime/transport_selector.h
@@ -84,6 +84,11 @@ struct SelectionContext {
         policy_name;  // Optional: bind to specific policy by name
     IntentType intent_type{
         IntentType::INTENT_UNSPEC};  // Business intent for policy matching
+    // A peer on the same machine still has a different address space.
+    bool local_segment{false};
+    // Match policy against the original memory types, but select a network
+    // transport for the host-to-host leg of a staged request.
+    bool host_staging{false};
 };
 
 /**
@@ -120,17 +125,28 @@ struct SelectionPolicy {
     // Transport preference list (evaluated in order)
     std::vector<TransportType> transports;
 
-    // Per-policy link-layer QoS. nullopt = fall back to the global RdmaParams
-    // value. InfiniBand Service Level (0-15) and Traffic Class / DSCP (0-255).
+    // Superseded, and read by nothing: link-layer QoS is a property of the QP
+    // a transfer lands on, so it is defined per pool in
+    // transports/rdma/endpoint/qp_pools and applied at QP setup
+    // (endpoint.cpp, setupOneQP). Still parsed so a config that sets them here
+    // is reported rather than silently ignored.
     std::optional<int> service_level;
     std::optional<int> traffic_class;
-    // Named QP pool this policy's traffic should land on; parsed and stored for
-    // now, routing to be wired later. Unset = the current single "data QP".
+    // Named QP pool this policy's traffic lands on. Routed end to end:
+    // SelectionResult -> TaskInfo -> SubBatch -> RdmaTask -> selectQpInPool().
+    // Unset (or a name no configured pool matches) sprays across *all* QPs --
+    // there is no reserved default pool, so once qp_pools is configured such
+    // traffic also lands on the named pools' QPs and inherits their SL/TC.
     std::optional<std::string> qp_pool;
 
     // Optional business-intent filter. nullopt preserves the historical
     // catch-all behavior; otherwise the request intent must match exactly.
     std::optional<IntentType> intent_type;
+
+    // `devices` resolved against the topology by setTopology(), so select()
+    // does not repeat a name lookup per request. ~0ULL means "all devices":
+    // no device filter, no topology yet, or a filter that resolved to nothing.
+    uint64_t resolved_device_mask{~0ULL};
 };
 
 /**
@@ -139,10 +155,14 @@ struct SelectionPolicy {
 struct SelectionResult {
     TransportType transport = UNSPEC;
     uint64_t device_mask = ~0ULL;  // Bitmask of allowed devices (~0 = all)
-    // Resolved link-layer QoS from the matched policy (nullopt = default).
+    // Copied from the matched policy for diagnostics only; QP setup takes
+    // SL/TC from the QP pool, not from here. See SelectionPolicy.
     std::optional<int> service_level;
     std::optional<int> traffic_class;
+    // Consumed: names the QP pool the transfer is routed to.
     std::optional<std::string> qp_pool;
+    // Filled by the engine for XPU orchestration, never by select() itself.
+    std::vector<std::string> staging_params;
 };
 
 /**
@@ -154,10 +174,12 @@ class TransportSelector {
 
     /**
      * @brief Set topology for device name to ID conversion
+     *
+     * Resolves every policy's `devices` list into a mask here, once, and
+     * reports what did not resolve. Safe to call again if the topology is
+     * replaced.
      */
-    void setTopology(std::shared_ptr<Topology> topology) {
-        topology_ = topology;
-    }
+    void setTopology(std::shared_ptr<Topology> topology);
 
     /**
      * @brief Select the best transport for a given context
@@ -185,12 +207,19 @@ class TransportSelector {
      */
     bool isLegacyMode() const { return legacy_mode_; }
 
+    bool isForceTcp() const { return force_tcp_; }
+
     static std::optional<std::vector<TransportType>> reorderWithHint(
         const std::vector<TransportType>& raw, TransportType hint);
 
    private:
+    // Width of SelectionResult::device_mask; a NIC past this index cannot be
+    // named by a policy at all.
+    static constexpr int kDeviceMaskBits = 64;
+
     std::vector<SelectionPolicy> getDefaultPolicies();
     void loadPolicies();
+    void resolveDeviceMasks();
     bool matchesMemoryPattern(const std::string& pattern,
                               MemoryType type) const;
     bool matchesPolicy(const SelectionPolicy& policy,
@@ -203,6 +232,7 @@ class TransportSelector {
     std::shared_ptr<Config> config_;
     std::shared_ptr<Topology> topology_;
     std::vector<SelectionPolicy> policies_;
+    bool force_tcp_{false};
     bool legacy_mode_{false};  // If true, skip selector and return empty result
 };
 
diff --git a/mooncake-transfer-engine/tent/include/tent/transfer_engine.h b/mooncake-transfer-engine/tent/include/tent/transfer_engine.h
index c13c74564c..272c0fea29 100644
--- a/mooncake-transfer-engine/tent/include/tent/transfer_engine.h
+++ b/mooncake-transfer-engine/tent/include/tent/transfer_engine.h
@@ -111,6 +111,9 @@ typedef struct tent_notifi_info tent_notifi_info;
 #define TRANSPORT_SUNRISE_LINK (9)
 #define TRANSPORT_TPU (10)
 #define TRANSPORT_UB (11)
+#define TRANSPORT_MPCOMM (12)
+#define TRANSPORT_HP_TCP (13)
+#define TRANSPORT_XPU (14)
 
 struct tent_memory_options {
     char location[64];
@@ -206,6 +209,7 @@ int tent_register_memory_batch_ex(tent_engine_t engine, void** addrs,
 int tent_task_status_list(tent_engine_t engine, tent_batch_id_t batch_id,
                           tent_status_t* statuses, size_t* count);
 
+// Only NICs currently able to carry traffic are reported (see NicLoadStats).
 struct tent_nic_load_stat {
     char device_name[64];
     uint64_t inflight_bytes;
@@ -236,9 +240,11 @@ int tent_get_nic_load_stats(tent_engine_t engine, tent_nic_load_stat_t* stats,
 #include "tent/common/types.h"
 
 namespace mooncake {
+class TransferEngineImplTestPeer;
 namespace tent {
 class TransferEngineImpl;
 class Config;
+class Topology;
 class TransferEngine {
    public:
     TransferEngine();
@@ -262,6 +268,12 @@ class TransferEngine {
 
     uint16_t getRpcServerPort() const;
 
+    // Returns the live local topology (nics/mems). Empty if engine unavailable.
+    std::shared_ptr<Topology> getLocalTopology() const;
+
+    // Native {"nics","mems"} JSON dump (includes rank0/1/2). "{}" if empty.
+    std::string getLocalTopologyString() const;
+
    public:
     Status exportLocalSegment(std::string& shared_handle);
 
@@ -346,6 +358,7 @@ class TransferEngine {
 
    private:
     std::unique_ptr<TransferEngineImpl> impl_;
+    friend class ::mooncake::TransferEngineImplTestPeer;
 };
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ascend/ascend_direct_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/ascend/ascend_direct_transport.h
index 8b55c24e83..a4277e2768 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/ascend/ascend_direct_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ascend/ascend_direct_transport.h
@@ -1,4 +1,4 @@
-// Copyright 2025 KVCache.AI
+// Copyright 2026 KVCache.AI
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -15,120 +15,167 @@
 #ifndef ASCEND_DIRECT_TRANSPORT_H_
 #define ASCEND_DIRECT_TRANSPORT_H_
 
-#include <functional>
-#include <iostream>
+#include <atomic>
+#include <condition_variable>
+#include <map>
+#include <memory>
+#include <mutex>
 #include <string>
-
-#include <acl/acl.h>
-#include <hixl/hixl.h>
+#include <unordered_map>
+#include <utility>
+#include <vector>
 
 #include "tent/runtime/control_plane.h"
 #include "tent/runtime/transport.h"
+#include "tent/transport/ascend/hixl_engine.h"
+#include "tent/transport/ascend/local_copy_engine.h"
+#include "tent/transport/ascend/resource_config.h"
 
 namespace mooncake {
 namespace tent {
 
 struct HixlTask {
     Request request;
-    volatile TransferStatusEnum status_word;
-    volatile size_t transferred_bytes;
-    uint64_t target_addr = 0;
-    hixl::TransferReq req_handle = nullptr;
+    volatile TransferStatusEnum status_word = TransferStatusEnum::PENDING;
+    volatile size_t transferred_bytes = 0;
+    void* req_handle = nullptr;
     uint64_t batch_size = 0;
     std::string remote_hixl;
-    uint64_t start_time = 0;
+    int64_t start_time_ns = 0;
+    size_t local_engine_idx = 0;
+    bool local_copy = false;
 };
 
 struct HixlSubBatch : public Transport::SubBatch {
     std::vector<HixlTask> task_list;
-    size_t max_size;
-    virtual size_t size() const { return task_list.size(); }
+    size_t max_size = 0;
+    size_t size() const override { return task_list.size(); }
 };
 
+class AscendDirectTransportTestPeer;
+
 class AscendDirectTransport : public Transport {
    public:
     AscendDirectTransport();
+    ~AscendDirectTransport() override;
 
-    ~AscendDirectTransport();
-
-    virtual Status install(std::string &local_segment_name,
-                           std::shared_ptr<ControlService> metadata,
-                           std::shared_ptr<Topology> local_topology,
-                           std::shared_ptr<Config> conf = nullptr);
-
-    virtual Status uninstall();
-
-    virtual Status allocateSubBatch(SubBatchRef &batch, size_t max_size);
+    Status install(std::string& local_segment_name,
+                   std::shared_ptr<ControlService> metadata,
+                   std::shared_ptr<Topology> local_topology,
+                   std::shared_ptr<Config> conf = nullptr) override;
 
-    virtual Status freeSubBatch(SubBatchRef &batch);
+    Status uninstall() override;
+    Status quiesce() override;
 
-    virtual Status submitTransferTasks(
-        SubBatchRef batch, const std::vector<Request> &request_list);
+    Status allocateSubBatch(SubBatchRef& batch, size_t max_size) override;
+    Status freeSubBatch(SubBatchRef& batch) override;
 
-    virtual Status getTransferStatus(SubBatchRef batch, int task_id,
-                                     TransferStatus &status);
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request>& request_list) override;
 
-    virtual Status addMemoryBuffer(BufferDesc &desc,
-                                   const MemoryOptions &options);
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override;
 
-    virtual Status removeMemoryBuffer(BufferDesc &desc);
+    Status addMemoryBuffer(BufferDesc& desc,
+                           const MemoryOptions& options) override;
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override;
+    Status removeMemoryBuffer(BufferDesc& desc) override;
 
-    virtual const char *getName() const { return "ascend_direct"; }
+    const char* getName() const override { return "ascend_direct"; }
+    bool supportNotification() const override { return false; }
 
    private:
-    Status initHixl(const std::shared_ptr<Config> &conf);
-
-    Status checkAndConnect(const std::string &remote_hixl);
-
-    void disconnect(const std::string &remote_hixl, int32_t timeout_in_millis);
-
-    void startTransfer(SegmentID target_id, Request::OpCode opcode,
-                       const std::vector<HixlTask *> &tasks);
-
-    void localCopy(Request::OpCode opcode,
-                   const std::vector<HixlTask *> &tasks);
-
-    aclError copyWithBatch(Request::OpCode opcode,
-                           const std::vector<HixlTask *> &tasks,
-                           aclrtMemcpyKind kind, size_t batch_num,
-                           size_t task_index) const;
-
-    static void copyWithSync(Request::OpCode opcode,
-                             const std::vector<HixlTask *> &tasks,
-                             aclrtMemcpyKind kind);
-
-    void copyWithAsync(Request::OpCode opcode,
-                       const std::vector<HixlTask *> &tasks,
-                       aclrtMemcpyKind kind);
-
-   private:
-    bool installed_;
+    struct PreparedRequest {
+        Request request;
+        size_t local_engine_idx = 0;
+        std::string remote_hixl;
+    };
+
+    struct GroupState {
+        TransferStatusEnum status = TransferStatusEnum::PENDING;
+        int remaining = 0;
+        size_t engine_idx = 0;
+        std::string remote;
+        bool counted = false;
+        bool local_copy = false;
+    };
+
+    Status initEngines();
+    void finalizeEngines();
+    Status publishLocalEngines();
+    size_t currentEngineIndex() const;
+    Status resolveRequest(const Request& request,
+                          PreparedRequest& prepared) const;
+    void startGroup(const std::string& remote_hixl, size_t local_engine_idx,
+                    bool write, const std::vector<HixlTask*>& tasks);
+    void startLocalCopy(size_t local_engine_idx, bool write,
+                        const std::vector<HixlTask*>& tasks);
+    void failLocalCopyStream(size_t engine_idx, TransferStatusEnum status);
+    void markGroupHandles(const std::vector<void*>& handles,
+                          TransferStatusEnum status);
+    void failEntireRoute(size_t engine_idx, const std::string& remote,
+                         TransferStatusEnum status, bool disconnect);
+    bool applyGroupStatus(HixlTask& task, GroupState& group);
+    bool finishTaskLocked(HixlTask& task, void** local_release_handle,
+                          size_t* local_release_engine);
+    void completePolledTask(HixlTask& task);
+    void releaseInflight(int n = 1);
+
+    friend class AscendDirectTransportTestPeer;
+
+    bool installed_{false};
     std::string local_segment_name_;
     std::shared_ptr<Topology> local_topology_;
     std::shared_ptr<ControlService> metadata_;
+    std::shared_ptr<Config> conf_;
+    AscendDirectOptions options_;
+    std::map<std::string, std::string> init_options_;
+    int64_t transfer_timeout_ns_{0};
 
-    int32_t device_logic_id_{};
-    aclrtContext rt_context_{nullptr};
-    std::unique_ptr<hixl::Hixl> hixl_;
-    bool auto_connect_{true};
-    uint64_t connect_timeout_;
-    uint64_t transfer_timeout_;
-    std::string local_hixl_name_{};
-    aclrtStream stream_{};
+    std::vector<std::unique_ptr<HixlEngine>> engines_;
+    std::vector<std::unique_ptr<LocalCopyEngine>> local_copies_;
 
     std::mutex req_mutex_;
-    std::unordered_map<hixl::TransferReq,
-                       std::pair<TransferStatusEnum, uint64_t>>
-        req_map_;
+    std::unordered_map<void*, GroupState> groups_;
+    std::map<std::pair<size_t, std::string>, std::vector<void*>> route_groups_;
 
-    // Connection management for segment connections
-    std::set<std::string> connected_segments_;
-    std::mutex connection_mutex_;
+    std::mutex inflight_mu_;
+    std::condition_variable inflight_cv_;
+    std::atomic<int> inflight_{0};
+};
 
-    std::map<uint64_t, hixl::MemHandle> addr_to_mem_handle_;
-    std::mutex mem_handle_mutex_;
+class AscendDirectTransportTestPeer {
+   public:
+    static const AscendDirectOptions& options(
+        const AscendDirectTransport& transport) {
+        return transport.options_;
+    }
+
+    static const std::map<std::string, std::string>& initOptions(
+        const AscendDirectTransport& transport) {
+        return transport.init_options_;
+    }
+
+    static size_t engineCount(const AscendDirectTransport& transport) {
+        return transport.engines_.size();
+    }
+
+    static const std::string& engineName(const AscendDirectTransport& transport,
+                                         size_t idx) {
+        return transport.engines_.at(idx)->name();
+    }
+
+    static int inflight(const AscendDirectTransport& transport) {
+        return transport.inflight_.load();
+    }
+
+    static bool installed(const AscendDirectTransport& transport) {
+        return transport.installed_;
+    }
 };
+
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // ASCEND_DIRECT_TRANSPORT_H_
\ No newline at end of file
+#endif  // ASCEND_DIRECT_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ascend/hixl_engine.h b/mooncake-transfer-engine/tent/include/tent/transport/ascend/hixl_engine.h
new file mode 100644
index 0000000000..d338234ffa
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ascend/hixl_engine.h
@@ -0,0 +1,142 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_HIXL_ENGINE_H_
+#define TENT_HIXL_ENGINE_H_
+
+#include <acl/acl.h>
+
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+#include "tent/common/status.h"
+
+namespace mooncake {
+namespace tent {
+
+constexpr uint32_t kHixlOk = 0;
+constexpr uint32_t kHixlNotConnected = 103902;
+
+enum class HixlXferState {
+    Waiting,
+    Completed,
+    Timeout,
+    Failed,
+};
+
+struct HixlOpDesc {
+    uintptr_t local_addr = 0;
+    uintptr_t remote_addr = 0;
+    size_t len = 0;
+};
+
+// One HIXL instance per NPU: ACL context, registered handles, and a mutex so
+// dummy-real workers cannot race the same engine. Vendor is the hixl::Hixl
+// call surface so tests can inject a fake without a live CANN process.
+class HixlEngine {
+   public:
+    class Vendor {
+       public:
+        virtual ~Vendor() = default;
+
+        virtual uint32_t Initialize(
+            const std::string& local_name,
+            const std::map<std::string, std::string>& options) = 0;
+
+        virtual void Finalize() = 0;
+
+        virtual uint32_t RegisterMem(uint64_t addr, size_t len, bool host,
+                                     void*& handle) = 0;
+
+        virtual uint32_t DeregisterMem(void* handle) = 0;
+
+        virtual uint32_t TransferAsync(const std::string& remote, bool write,
+                                       const std::vector<HixlOpDesc>& descs,
+                                       void*& req) = 0;
+
+        virtual uint32_t GetTransferStatus(void* req,
+                                           HixlXferState& status) = 0;
+
+        virtual uint32_t Disconnect(const std::string& remote,
+                                    int32_t timeout_ms) = 0;
+
+        // Kept so tests can assert AutoConnect-only never calls Connect.
+        virtual uint32_t Connect(const std::string& remote,
+                                 int32_t timeout_ms) = 0;
+    };
+
+    using VendorFactory = std::function<std::unique_ptr<Vendor>()>;
+
+    static void SetVendorFactory(VendorFactory factory);
+
+    HixlEngine() = default;
+    ~HixlEngine();
+
+    HixlEngine(const HixlEngine&) = delete;
+    HixlEngine& operator=(const HixlEngine&) = delete;
+
+    Status initialize(const std::string& name, aclrtContext context,
+                      int32_t device_id,
+                      const std::map<std::string, std::string>& options);
+
+    void finalize();
+
+    Status registerMem(void* addr, size_t length, bool host);
+    Status deregisterMem(void* addr);
+    void rollbackMem(void* addr);
+
+    Status transferAsync(const std::string& remote, bool write,
+                         const std::vector<HixlOpDesc>& descs, void*& req);
+    Status getTransferStatus(void* req, HixlXferState& status);
+    Status disconnectOnTimeout(const std::string& remote, int32_t timeout_ms);
+
+    const std::string& name() const { return name_; }
+    int32_t deviceId() const { return device_id_; }
+    aclrtContext context() const { return context_; }
+    bool initialized() const { return initialized_; }
+
+   private:
+    class ContextGuard {
+       public:
+        explicit ContextGuard(aclrtContext target);
+        ~ContextGuard();
+        bool ok() const { return ok_; }
+
+       private:
+        aclrtContext saved_{nullptr};
+        bool ok_{false};
+    };
+
+    static VendorFactory GetVendorFactory();
+    static std::unique_ptr<Vendor> CreateVendor();
+
+    std::mutex mutex_;
+    std::unique_ptr<Vendor> vendor_;
+    std::map<void*, void*> addr_to_handle_;
+    std::vector<std::string> remotes_;
+    std::string name_;
+    aclrtContext context_{nullptr};
+    int32_t device_id_{-1};
+    bool initialized_{false};
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_HIXL_ENGINE_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ascend/local_copy_engine.h b/mooncake-transfer-engine/tent/include/tent/transport/ascend/local_copy_engine.h
new file mode 100644
index 0000000000..0ecb9203e9
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ascend/local_copy_engine.h
@@ -0,0 +1,90 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_ASCEND_LOCAL_COPY_ENGINE_H_
+#define TENT_ASCEND_LOCAL_COPY_ENGINE_H_
+
+#include <acl/acl.h>
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+
+#include "tent/common/status.h"
+#include "tent/common/types.h"
+#include "tent/transport/ascend/hixl_engine.h"
+
+namespace mooncake {
+namespace tent {
+
+// Same-engine copies: one aclrtMemcpyAsync per slice plus a D2H of a host
+// completion flag. Poll success as *host_flag == 1. Any submit/timeout
+// failure destroys the stream, recreates it, and fails every in-flight group
+// on that stream.
+class LocalCopyEngine {
+   public:
+    LocalCopyEngine() = default;
+    ~LocalCopyEngine();
+
+    LocalCopyEngine(const LocalCopyEngine&) = delete;
+    LocalCopyEngine& operator=(const LocalCopyEngine&) = delete;
+
+    Status initialize(aclrtContext context, int32_t device_id);
+    void finalize();
+
+    Status submit(bool write, const std::vector<HixlOpDesc>& ops, void*& req,
+                  std::vector<void*>& failed_handles);
+
+    TransferStatusEnum poll(void* req);
+    void release(void* req);
+    std::vector<void*> failAndRecreate();
+
+   private:
+    struct Group {
+        volatile uint32_t* host_flag = nullptr;
+        bool failed = false;
+    };
+
+    class ContextGuard {
+       public:
+        explicit ContextGuard(aclrtContext target);
+        ~ContextGuard();
+        bool ok() const { return ok_; }
+
+       private:
+        aclrtContext saved_{nullptr};
+        bool ok_{false};
+    };
+
+    Status createStreamLocked();
+    Status allocHostFlag(volatile uint32_t*& flag);
+    void freeHostFlag(volatile uint32_t* flag);
+    std::vector<void*> failAndRecreateLocked();
+    static aclrtMemcpyKind memcpyKind(void* src, void* dst);
+
+    mutable std::mutex mutex_;
+    aclrtContext context_{nullptr};
+    int32_t device_id_{-1};
+    aclrtStream stream_{nullptr};
+    void* device_one_{nullptr};
+    std::unordered_map<void*, std::unique_ptr<Group>> groups_;
+    bool initialized_{false};
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_ASCEND_LOCAL_COPY_ENGINE_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ascend/resource_config.h b/mooncake-transfer-engine/tent/include/tent/transport/ascend/resource_config.h
new file mode 100644
index 0000000000..d8a67419ca
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ascend/resource_config.h
@@ -0,0 +1,76 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_ASCEND_RESOURCE_CONFIG_H_
+#define TENT_ASCEND_RESOURCE_CONFIG_H_
+
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/segment.h"
+
+namespace mooncake {
+namespace tent {
+
+constexpr int32_t kAscendDefaultTransferTimeoutMs = 10000;
+constexpr int32_t kAscendDefaultBasePort = 20000;
+constexpr int32_t kAscendTimeoutDisconnectMs = 1000;
+constexpr const char* kDefaultLocalCommRes = R"({"version":"1.3"})";
+constexpr const char* kHixlNameAttr = "hixl_name";
+constexpr const char* kHixlNamesAttr = "hixl_names";
+
+struct AscendDirectOptions {
+    int32_t transfer_timeout_ms = kAscendDefaultTransferTimeoutMs;
+    int32_t base_port = kAscendDefaultBasePort;
+    bool agent_mode = false;
+    bool store_te_init = false;
+    bool use_fabric_mem = false;
+    bool roce_mode = false;
+    std::string rdma_tc;
+    std::string rdma_sl;
+    std::string local_comm_res = kDefaultLocalCommRes;
+    std::string global_resource_config;
+};
+
+bool ParseEnvEnabled(const char* name);
+
+AscendDirectOptions LoadAscendDirectOptions(
+    const std::shared_ptr<Config>& conf);
+
+std::map<std::string, std::string> BuildHixlInitOptions(
+    const AscendDirectOptions& options);
+
+// RoCE/HCCS dataplane listen port. Distinct from the HIXL engine TCP name.
+uint16_t HixlRoceListenPort(uint16_t hixl_port);
+
+// Copy HIXL init options and set comm_resource_config.listen_port.
+std::map<std::string, std::string> WithHixlListenPort(
+    const std::map<std::string, std::string>& init, uint16_t listen_port);
+
+std::string HostIpFromSegmentName(const std::string& segment_name);
+std::string MakeHixlEngineName(const std::string& host_ip, uint16_t port);
+uint16_t FindHixlListenPort(int32_t base_port, int32_t device_id);
+
+std::vector<std::string> ParseHixlNames(const MemorySegmentDesc& detail);
+std::string ResolveRemoteHixlName(const MemorySegmentDesc& detail,
+                                  uint64_t dest_addr);
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_ASCEND_RESOURCE_CONFIG_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/gds/gds_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/gds/gds_transport.h
index d63c42bfe6..2b48f399cf 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/gds/gds_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/gds/gds_transport.h
@@ -34,13 +34,17 @@ namespace mooncake {
 namespace tent {
 
 class GdsFileContext;
+class GdsTransportTestPeer;
 
 struct IOParamRange {
     size_t base = 0;
     size_t count = 0;
-    size_t complete_count = 0;
     size_t transferred_bytes = 0;
     TransferStatusEnum status = TransferStatusEnum::PENDING;
+    // Public status stays PENDING until every slice in this range is
+    // physically terminal. Preserve the first observed failure while sibling
+    // slices drain so cancellation cannot mask the original result.
+    TransferStatusEnum known_failure = TransferStatusEnum::PENDING;
 };
 
 // Wrapper for reusable CUfileBatchHandle_t
@@ -55,7 +59,13 @@ struct GdsSubBatch : public Transport::SubBatch {
     BatchHandle* batch_handle;  // Pointer to reusable handle from pool
     std::vector<IOParamRange> io_param_ranges;
     std::vector<CUfileIOParams_t> io_params;
+    // Scratch buffer populated by cuFileBatchIOGetStatus().
     std::vector<CUfileIOEvents_t> io_events;
+    // Stable per-slice status cache indexed by the cookie carried in each IO.
+    std::vector<CUfileIOEvents_t> cached_events;
+    bool reusable = true;
+    bool cancel_requested = false;
+    std::mutex status_mutex;
     virtual size_t size() const { return io_param_ranges.size(); }
 };
 
@@ -90,6 +100,24 @@ class GdsTransport : public Transport {
     virtual const char* getName() const { return "gds"; }
 
    private:
+    friend class GdsTransportTestPeer;
+
+    static TransferStatus aggregateTransferStatus(
+        const std::vector<CUfileIOEvents_t>& events, size_t base, size_t count,
+        bool& all_terminal);
+
+    Status updateBatchStatus(GdsSubBatch* batch);
+
+    Status cancelBatch(GdsSubBatch* batch);
+
+    static bool allBatchIOsTerminal(const GdsSubBatch* batch);
+
+    static bool isTerminalFailure(TransferStatusEnum status);
+
+    static void destroySubBatch(GdsSubBatch* batch);
+
+    void cleanupQuarantinedBatches();
+
     std::string getGdsFilePath(SegmentID handle);
 
     GdsFileContext* findFileContext(SegmentID target_id);
@@ -115,8 +143,13 @@ class GdsTransport : public Transport {
     // Track all allocated sub-batches to clean up on uninstall
     std::vector<GdsSubBatch*> allocated_batches_;
     std::mutex allocated_batches_lock_;
+
+    // Failed batches may still be referenced by cuFile after cancellation.
+    // Keep their handle and IO storage alive until every slice is terminal.
+    std::vector<GdsSubBatch*> quarantined_batches_;
+    std::mutex quarantined_batches_lock_;
 };
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // GDS_TRANSPORT_H_
\ No newline at end of file
+#endif  // GDS_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_buffer_registry.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_buffer_registry.h
new file mode 100644
index 0000000000..7c22b3b510
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_buffer_registry.h
@@ -0,0 +1,90 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_BUFFER_REGISTRY_H_
+#define TENT_HP_TCP_BUFFER_REGISTRY_H_
+
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <mutex>
+
+#include "tent/common/status.h"
+#include "tent/common/types.h"
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+
+namespace mooncake::tent {
+
+class HighPerformanceTcpBufferRegistry {
+   public:
+    HighPerformanceTcpBufferRegistry();
+
+    struct Entry {
+        uint64_t base{0};
+        uint64_t length{0};
+        uint64_t registration_id{0};
+        Permission permission{kLocalReadWrite};
+
+        std::mutex mutex;
+        std::condition_variable drained;
+        uint64_t active_leases{0};
+    };
+
+    class Lease {
+       public:
+        Lease() = default;
+        Lease(const Lease&) = delete;
+        Lease& operator=(const Lease&) = delete;
+        Lease(Lease&& other) noexcept;
+        Lease& operator=(Lease&& other) noexcept;
+        ~Lease();
+
+        void reset();
+        void* data() const;
+        uint64_t base() const;
+        uint64_t length() const;
+        explicit operator bool() const { return entry_ != nullptr; }
+
+       private:
+        friend class HighPerformanceTcpBufferRegistry;
+        explicit Lease(std::shared_ptr<Entry> entry);
+        std::shared_ptr<Entry> entry_;
+    };
+
+    Status add(uint64_t base, uint64_t length, Permission permission,
+               uint64_t* registration_id);
+    Status remove(uint64_t base, uint64_t length);
+
+    // Prevent new registrations and leases during quiesce. Existing leases
+    // remain valid and drain through normal unregister/session completion.
+    void close();
+    Status reopen();
+
+    // Local access checks lifetime/range only. MemoryOptions::perm is a remote
+    // authorization policy and must not reject the local side of a transfer.
+    Status acquireLocalLease(uint64_t addr, uint64_t length, Lease* lease);
+
+    Status acquireRemoteLease(uint64_t addr, uint64_t length,
+                              uint64_t registration_id,
+                              HighPerformanceTcpOpcode opcode, Lease* lease,
+                              HighPerformanceTcpStatus* failure = nullptr);
+
+    bool tracks(uint64_t base, uint64_t length) const;
+
+   private:
+    Status acquire(uint64_t addr, uint64_t length, uint64_t registration_id,
+                   HighPerformanceTcpOpcode opcode, bool remote, Lease* lease,
+                   HighPerformanceTcpStatus* failure);
+
+    mutable std::mutex registry_mutex_;
+    std::map<uint64_t, std::shared_ptr<Entry>> entries_;
+    // Fence stale capabilities from an earlier registry incarnation while the
+    // sequence prevents reuse within this incarnation.
+    const uint64_t registration_namespace_;
+    uint64_t next_registration_sequence_{1};
+    bool closing_{false};
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_BUFFER_REGISTRY_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_client.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_client.h
new file mode 100644
index 0000000000..4c39983109
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_client.h
@@ -0,0 +1,125 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_CLIENT_H_
+#define TENT_HP_TCP_CLIENT_H_
+
+#include <asio.hpp>
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "tent/common/status.h"
+#include "tent/common/types.h"
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+namespace mooncake::tent {
+
+// Process-wide client runtime for the HP TCP transport. It owns no thread of
+// its own: every lane is created, queued, connected and driven exclusively on
+// the worker selected by AffinityKey.
+class HighPerformanceTcpClient {
+   public:
+    struct Config {
+        uint64_t max_transfer_bytes{1ULL << 30};
+        size_t chunk_size{1ULL << 20};
+        uint64_t connect_timeout_ms{2000};
+        uint64_t progress_timeout_ms{30000};
+        size_t connections_per_peer{4};
+        uint64_t idle_connection_timeout_ms{60000};
+    };
+
+    struct Operation {
+        SegmentID peer_id{0};
+        std::string incarnation;
+        std::string host;
+        std::string local_host;
+        uint16_t port{0};
+        uint32_t lane_id{0};
+        uint64_t registration_id{0};
+        uint64_t remote_addr{0};
+        void* local_addr{nullptr};
+        uint64_t length{0};
+        HighPerformanceTcpOpcode opcode{HighPerformanceTcpOpcode::kRead};
+        uint64_t request_id{0};
+        std::function<void(TransferStatusEnum, size_t,
+                           std::optional<HighPerformanceTcpStatus>)>
+            complete;
+    };
+
+    HighPerformanceTcpClient(Config config, HighPerformanceTcpWorkers* workers);
+    ~HighPerformanceTcpClient();
+
+    HighPerformanceTcpClient(const HighPerformanceTcpClient&) = delete;
+    HighPerformanceTcpClient& operator=(const HighPerformanceTcpClient&) =
+        delete;
+
+    // Must execute on owner_worker. The transport reaches this method through
+    // the owner's ASIO event queue after global admission succeeds.
+    void enqueueOnOwner(size_t owner_worker, Operation operation);
+
+    // Non-worker quiesce barrier. Cancels every queued/connecting/in-flight
+    // operation and waits until all operation callbacks have retired.
+    Status cancelAll(TransferStatusEnum terminal = CANCELED);
+
+    // Best-effort cancellation for one logical request. If the request is
+    // still in the transport dispatch queue, the adapter's cancel flag settles
+    // it; otherwise cancellation is posted to every worker that may own one of
+    // its slices.
+    Status cancelRequest(uint64_t request_id);
+
+    uint64_t connectionsCreatedForTest() const {
+        return connections_created_.load(std::memory_order_acquire);
+    }
+    uint64_t activeOperations() const {
+        return active_operations_.load(std::memory_order_acquire);
+    }
+
+   private:
+    struct LaneKey {
+        SegmentID peer_id{0};
+        std::string incarnation;
+        std::string host;
+        uint16_t port{0};
+        uint32_t lane_id{0};
+
+        bool operator==(const LaneKey& other) const;
+    };
+
+    struct LaneKeyHash {
+        size_t operator()(const LaneKey& key) const;
+    };
+
+    class Lane;
+
+    struct WorkerState {
+        std::unordered_map<LaneKey, std::shared_ptr<Lane>, LaneKeyHash> lanes;
+    };
+
+    void cancelWorker(size_t worker_id, TransferStatusEnum terminal);
+    void cancelRequestOnWorker(size_t worker_id, uint64_t request_id);
+    void operationStarted();
+    void operationFinished();
+
+    Config config_;
+    HighPerformanceTcpWorkers* workers_{nullptr};
+    std::vector<WorkerState> worker_states_;
+    std::atomic<bool> stopping_{false};
+
+    std::atomic<uint64_t> connections_created_{0};
+    std::atomic<uint64_t> active_operations_{0};
+    mutable std::mutex active_mutex_;
+    std::condition_variable active_cv_;
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_CLIENT_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_protocol.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_protocol.h
new file mode 100644
index 0000000000..30bb628ecd
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_protocol.h
@@ -0,0 +1,94 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_PROTOCOL_H_
+#define TENT_HP_TCP_PROTOCOL_H_
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "tent/common/status.h"
+#include "tent/common/types.h"
+
+namespace mooncake::tent {
+
+constexpr uint32_t kHighPerformanceTcpMagic = 0x4d435450;  // "MCTP"
+constexpr uint16_t kHighPerformanceTcpVersion = 1;
+constexpr size_t kHighPerformanceTcpRequestSize = 48;
+constexpr size_t kHighPerformanceTcpResponseSize = 32;
+
+enum class HighPerformanceTcpOpcode : uint8_t {
+    kRead = 1,
+    kWrite = 2,
+};
+
+enum class HighPerformanceTcpStatus : uint16_t {
+    kOk = 0,
+    kBadVersion = 1,
+    kBadOpcode = 2,
+    kBadLength = 3,
+    kRangeRejected = 4,
+    kPermissionDenied = 5,
+    kStaleRegistration = 6,
+    kShuttingDown = 7,
+    kInternalError = 8,
+};
+
+struct HighPerformanceTcpRequestFrame {
+    HighPerformanceTcpOpcode opcode{HighPerformanceTcpOpcode::kRead};
+    uint64_t request_id{0};
+    uint64_t registration_id{0};
+    uint64_t remote_addr{0};
+    uint64_t length{0};
+};
+
+struct HighPerformanceTcpResponseFrame {
+    HighPerformanceTcpStatus status{HighPerformanceTcpStatus::kOk};
+    uint64_t request_id{0};
+    uint64_t committed_bytes{0};
+};
+
+std::array<uint8_t, kHighPerformanceTcpRequestSize>
+EncodeHighPerformanceTcpRequest(const HighPerformanceTcpRequestFrame& frame);
+
+Status DecodeHighPerformanceTcpRequest(
+    const uint8_t* bytes, size_t size, HighPerformanceTcpRequestFrame* frame,
+    HighPerformanceTcpStatus* wire_error = nullptr);
+
+std::array<uint8_t, kHighPerformanceTcpResponseSize>
+EncodeHighPerformanceTcpResponse(const HighPerformanceTcpResponseFrame& frame);
+
+Status DecodeHighPerformanceTcpResponse(const uint8_t* bytes, size_t size,
+                                        HighPerformanceTcpResponseFrame* frame);
+
+struct HighPerformanceTcpEndpoint {
+    std::string host;
+    uint16_t port{0};
+};
+
+struct HighPerformanceTcpEndpointAttr {
+    std::string incarnation;
+    std::vector<HighPerformanceTcpEndpoint> endpoints;
+    uint64_t max_transfer_bytes{0};
+};
+
+struct HighPerformanceTcpBufferAttr {
+    uint64_t registration_id{0};
+    std::string permission;
+};
+
+Status EncodeHighPerformanceTcpEndpointAttr(
+    const HighPerformanceTcpEndpointAttr& attr, std::string* encoded);
+Status DecodeHighPerformanceTcpEndpointAttr(
+    const std::string& encoded, HighPerformanceTcpEndpointAttr* attr);
+Status EncodeHighPerformanceTcpBufferAttr(
+    const HighPerformanceTcpBufferAttr& attr, std::string* encoded);
+Status DecodeHighPerformanceTcpBufferAttr(const std::string& encoded,
+                                          HighPerformanceTcpBufferAttr* attr);
+
+const char* HighPerformanceTcpPermissionName(Permission permission);
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_PROTOCOL_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_server.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_server.h
new file mode 100644
index 0000000000..c1b65e3e94
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_server.h
@@ -0,0 +1,87 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_SERVER_H_
+#define TENT_HP_TCP_SERVER_H_
+
+#include <asio.hpp>
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+#include <unordered_set>
+#include <vector>
+
+#include "tent/common/status.h"
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+namespace mooncake::tent {
+
+class HighPerformanceTcpServer {
+   public:
+    struct Config {
+        std::string bind_address;
+        uint16_t port{0};
+        uint64_t max_transfer_bytes{1ULL << 30};
+        size_t chunk_size{1ULL << 20};
+        uint64_t progress_timeout_ms{30000};
+        size_t max_connections{4096};
+    };
+
+    HighPerformanceTcpServer(Config config,
+                             HighPerformanceTcpBufferRegistry* registry,
+                             HighPerformanceTcpWorkers* workers);
+    ~HighPerformanceTcpServer();
+
+    HighPerformanceTcpServer(const HighPerformanceTcpServer&) = delete;
+    HighPerformanceTcpServer& operator=(const HighPerformanceTcpServer&) =
+        delete;
+
+    Status start(uint16_t* bound_port);
+    Status stopAccepting();
+    Status cancelAll();
+    Status stop();
+
+    size_t activeSessionsForTest() const {
+        return active_sessions_.load(std::memory_order_acquire);
+    }
+
+   private:
+    class Session;
+
+    Status startAccept();
+    void installAcceptedSocket(size_t worker_id,
+                               std::shared_ptr<asio::ip::tcp::socket> socket);
+    bool reserveConnection();
+    void onSessionClosed(size_t worker_id,
+                         const std::shared_ptr<Session>& session);
+    void cancelWorkerSessions(size_t worker_id);
+
+    Config config_;
+    HighPerformanceTcpBufferRegistry* registry_{nullptr};
+    HighPerformanceTcpWorkers* workers_{nullptr};
+
+    asio::io_context accept_io_;
+    std::optional<asio::executor_work_guard<asio::io_context::executor_type>>
+        accept_guard_;
+    std::unique_ptr<asio::ip::tcp::acceptor> acceptor_;
+    std::thread accept_thread_;
+    std::atomic<bool> started_{false};
+    std::atomic<bool> stopping_{false};
+    std::atomic<size_t> next_worker_{0};
+    std::atomic<size_t> active_sessions_{0};
+
+    // Each set is touched only on the corresponding worker context.
+    std::vector<std::unordered_set<std::shared_ptr<Session>>> sessions_;
+    mutable std::mutex sessions_wait_mutex_;
+    std::condition_variable sessions_wait_cv_;
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_SERVER_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_task.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_task.h
new file mode 100644
index 0000000000..39be438af1
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_task.h
@@ -0,0 +1,88 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_TASK_H_
+#define TENT_HP_TCP_TASK_H_
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <utility>
+
+#include "tent/common/types.h"
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+namespace mooncake::tent {
+
+// TENT-visible task shell. Socket callbacks never own the SubBatch; they hold a
+// shared_ptr to this state instead. A task becomes admission-reserved only in
+// the no-throw batch commit section.
+class HighPerformanceTcpTaskState {
+   public:
+    HighPerformanceTcpTaskState(
+        uint64_t reserved_bytes, BatchID progress_batch_id,
+        std::function<void(BatchID)> notify_progress,
+        HighPerformanceTcpBufferRegistry::Lease local_lease,
+        size_t slice_count = 1)
+        : progress_batch_id_(progress_batch_id),
+          notify_progress_(std::move(notify_progress)),
+          local_lease_(std::move(local_lease)),
+          reserved_bytes_(reserved_bytes),
+          remaining_slices_(slice_count) {}
+
+    HighPerformanceTcpTaskState(const HighPerformanceTcpTaskState&) = delete;
+    HighPerformanceTcpTaskState& operator=(const HighPerformanceTcpTaskState&) =
+        delete;
+
+    void activateReservation(
+        HighPerformanceTcpAdmissionController* admission) noexcept {
+        admission_ = admission;
+        reservation_active_.store(true, std::memory_order_release);
+    }
+
+    bool completeOnce(TransferStatusEnum terminal, size_t bytes,
+                      std::optional<HighPerformanceTcpStatus> remote_status =
+                          std::nullopt) noexcept;
+    bool completeSlice(TransferStatusEnum terminal,
+                       std::optional<HighPerformanceTcpStatus> remote_status =
+                           std::nullopt) noexcept;
+    TransferStatus snapshot() const noexcept;
+    std::optional<HighPerformanceTcpStatus> remoteStatus() const noexcept;
+
+    void setRequestId(uint64_t request_id) noexcept {
+        request_id_ = request_id;
+    }
+    uint64_t requestId() const noexcept { return request_id_; }
+
+    bool requestCancel() noexcept {
+        return !cancel_requested_.exchange(true, std::memory_order_acq_rel);
+    }
+    bool cancelRequested() const noexcept {
+        return cancel_requested_.load(std::memory_order_acquire);
+    }
+
+   private:
+    std::atomic<TransferStatusEnum> status_{PENDING};
+    std::atomic<size_t> bytes_{0};
+    std::atomic<HighPerformanceTcpStatus> remote_status_{
+        HighPerformanceTcpStatus::kOk};
+    std::atomic<bool> completion_claimed_{false};
+    std::atomic<bool> cancel_requested_{false};
+
+    BatchID progress_batch_id_{0};
+    std::function<void(BatchID)> notify_progress_;
+    HighPerformanceTcpBufferRegistry::Lease local_lease_;
+
+    HighPerformanceTcpAdmissionController* admission_{nullptr};
+    uint64_t reserved_bytes_{0};
+    std::atomic<bool> reservation_active_{false};
+
+    std::atomic<size_t> remaining_slices_{1};
+    std::atomic<TransferStatusEnum> slice_status_{COMPLETED};
+    uint64_t request_id_{0};
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_TASK_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_transport.h
new file mode 100644
index 0000000000..302a1e41ae
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_transport.h
@@ -0,0 +1,108 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_TRANSPORT_H_
+#define TENT_HP_TCP_TRANSPORT_H_
+
+#include <atomic>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "tent/runtime/hp_tcp_transport_config.h"
+#include "tent/runtime/transport.h"
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+#include "tent/transport/hp_tcp/hp_tcp_client.h"
+#include "tent/transport/hp_tcp/hp_tcp_server.h"
+#include "tent/transport/hp_tcp/hp_tcp_task.h"
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+namespace mooncake::tent {
+
+struct HighPerformanceTcpSubBatch : Transport::SubBatch {
+    std::vector<std::shared_ptr<HighPerformanceTcpTaskState>> tasks;
+    size_t max_size{0};
+
+    size_t size() const override { return tasks.size(); }
+};
+
+class HighPerformanceTcpTransport final : public Transport {
+   public:
+    HighPerformanceTcpTransport();
+    explicit HighPerformanceTcpTransport(HighPerformanceTcpParams params);
+    ~HighPerformanceTcpTransport() override;
+
+    Status install(std::string& local_segment_name,
+                   std::shared_ptr<ControlService> metadata,
+                   std::shared_ptr<Topology> local_topology,
+                   std::shared_ptr<Config> config) override;
+    Status uninstall() override;
+    Status quiesce() override;
+
+    Status allocateSubBatch(SubBatchRef& batch, size_t max_size) override;
+    Status freeSubBatch(SubBatchRef& batch) override;
+    Status submitTransferTasks(SubBatchRef batch,
+                               const std::vector<Request>& requests) override;
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override;
+    Status retryTransferTask(SubBatchRef batch, int task_id,
+                             const Request& request) override;
+
+    bool supportsCancellation() const override { return true; }
+    Status cancelTransferTask(SubBatchRef batch, int task_id) override;
+
+    Status addMemoryBuffer(BufferDesc& desc,
+                           const MemoryOptions& options) override;
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override;
+    Status removeMemoryBuffer(BufferDesc& desc) override;
+    bool tracksLocalBuffer(const BufferDesc& desc) const override {
+        return registry_.tracks(desc.addr, desc.length);
+    }
+
+    bool supportNotification() const override { return true; }
+    Status sendNotification(SegmentID target_id,
+                            const Notification& notification) override;
+    Status receiveNotification(
+        std::vector<Notification>& notifications) override;
+
+    const char* getName() const override { return "hp_tcp"; }
+
+   private:
+    friend class HighPerformanceTcpTransportTestPeer;
+
+    Status validateParams() const;
+    Status planTask(const Request& request, HighPerformanceTcpSubBatch& batch,
+                    std::shared_ptr<HighPerformanceTcpTaskState>& task,
+                    std::vector<HighPerformanceTcpWorkers::Command>& commands);
+    Status rollbackPublishedEndpoint(
+        const std::optional<std::string>& previous_attr);
+    Status stopRuntime();
+    std::string makeIncarnation() const;
+
+    HighPerformanceTcpParams params_;
+    std::shared_ptr<ControlService> metadata_;
+
+    std::unique_ptr<HighPerformanceTcpAdmissionController> admission_;
+    std::unique_ptr<HighPerformanceTcpWorkers> workers_;
+    std::unique_ptr<HighPerformanceTcpClient> client_;
+    std::unique_ptr<HighPerformanceTcpServer> server_;
+    HighPerformanceTcpBufferRegistry registry_;
+
+    std::atomic<uint64_t> next_request_id_{1};
+    // Request IDs are global; lane rotation must advance independently per
+    // peer so periodic fan-out cannot pin a peer to one lane or rail.
+    std::mutex lane_sequence_mutex_;
+    std::map<SegmentID, uint64_t> next_lane_sequence_;
+    std::atomic<bool> installed_{false};
+    std::atomic<bool> stopping_{false};
+    mutable std::mutex lifecycle_mutex_;
+
+    RWSpinlock notify_lock_;
+    std::vector<Notification> notifications_;
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_workers.h b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_workers.h
new file mode 100644
index 0000000000..8ebf5f675a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/hp_tcp/hp_tcp_workers.h
@@ -0,0 +1,119 @@
+// Copyright 2026 KVCache.AI
+#ifndef TENT_HP_TCP_WORKERS_H_
+#define TENT_HP_TCP_WORKERS_H_
+
+#include <asio.hpp>
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+#include "tent/common/status.h"
+
+namespace mooncake::tent {
+
+// A single process-wide bound for accepted HP TCP work. Reservations remain
+// active until the corresponding task reaches a terminal state.
+class HighPerformanceTcpAdmissionController {
+   public:
+    HighPerformanceTcpAdmissionController(uint64_t max_tasks,
+                                          uint64_t max_bytes)
+        : max_tasks_(max_tasks), max_bytes_(max_bytes) {}
+
+    Status tryReserve(uint64_t tasks, uint64_t bytes);
+    void release(uint64_t tasks, uint64_t bytes);
+    void close();
+    // Returns an error rather than waiting forever if accounting was
+    // corrupted. The counters are intentionally left unchanged in that case.
+    Status waitForZero();
+    bool failed() const;
+    uint64_t outstandingTasks() const;
+    uint64_t outstandingBytes() const;
+
+   private:
+    const uint64_t max_tasks_;
+    const uint64_t max_bytes_;
+    mutable std::mutex mutex_;
+    std::condition_variable zero_cv_;
+    uint64_t tasks_{0};
+    uint64_t bytes_{0};
+    bool accepting_{true};
+    std::atomic<bool> failed_{false};
+};
+
+// Thin owner-thread pool for sockets. ASIO is the queue; this class adds
+// deterministic affinity and lifecycle management. Accepted transfer work is
+// bounded by HighPerformanceTcpAdmissionController.
+class HighPerformanceTcpWorkers {
+   public:
+    struct Config {
+        size_t worker_count{16};
+    };
+
+    using Task = std::function<void(size_t)>;
+    struct Command {
+        size_t worker_id{0};
+        Task run;
+        std::function<void()> cancel;
+    };
+
+    HighPerformanceTcpWorkers();
+    explicit HighPerformanceTcpWorkers(Config config);
+    ~HighPerformanceTcpWorkers();
+
+    HighPerformanceTcpWorkers(const HighPerformanceTcpWorkers&) = delete;
+    HighPerformanceTcpWorkers& operator=(const HighPerformanceTcpWorkers&) =
+        delete;
+
+    Status start();
+    Status stop();
+    Status tryCommitBatch(std::vector<Command>& commands,
+                          HighPerformanceTcpAdmissionController* admission,
+                          uint64_t reserve_tasks, uint64_t reserve_bytes,
+                          const std::function<void()>& on_commit);
+
+    Status barrier();
+    size_t affinityOwner(uint64_t peer, uint32_t lane) const;
+    bool running() const { return running_.load(std::memory_order_acquire); }
+    bool hasFailedWorker() const {
+        return failed_.load(std::memory_order_acquire);
+    }
+    // A stopped context is kept alive until client and server teardown has
+    // destroyed every socket and resolver that uses it, but it cannot run
+    // control work anymore.
+    bool controlContextAvailable() const {
+        return running() && !workers_.empty();
+    }
+    size_t workerCount() const { return config_.worker_count; }
+    asio::io_context& ioContext(size_t worker_id);
+    bool onWorkerThread() const;
+
+   private:
+    struct WorkerContext {
+        WorkerContext() : guard(asio::make_work_guard(io)) {}
+        asio::io_context io;
+        asio::executor_work_guard<asio::io_context::executor_type> guard;
+        std::thread thread;
+    };
+
+    void runCommand(Command command);
+    void markWorkerFailed() noexcept;
+
+    Config config_;
+    std::vector<std::unique_ptr<WorkerContext>> workers_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> failed_{false};
+    bool started_{false};
+    mutable std::mutex lifecycle_mutex_;
+    mutable std::mutex submit_mutex_;
+};
+
+}  // namespace mooncake::tent
+
+#endif  // TENT_HP_TCP_WORKERS_H_
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/io_uring/io_uring_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/io_uring/io_uring_transport.h
index ae9cf24288..ffb51c76f1 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/io_uring/io_uring_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/io_uring/io_uring_transport.h
@@ -37,6 +37,9 @@ struct IOUringTask {
     volatile TransferStatusEnum status_word;
     volatile size_t transferred_bytes;
     void *buffer = nullptr;
+    // The kernel may read the iovec asynchronously at execution time, so it
+    // must live as long as the task (i.e. until the completion is reaped).
+    struct iovec iov{};
 
     ~IOUringTask() {
         if (buffer) free(buffer);
@@ -80,6 +83,15 @@ class IOUringTransport : public Transport {
 
     virtual const char *getName() const { return "io-uring"; }
 
+   protected:
+    // Thin seam over io_uring_submit() so tests can simulate a positive
+    // short submission (0 < rc < number of prepared SQEs) — the case where
+    // part of the batch is already dispatched and an error return would
+    // make the engine's submit-stage failover re-execute it.
+    virtual int submitSqes(struct io_uring *ring) {
+        return io_uring_submit(ring);
+    }
+
    private:
     std::string getIOUringFilePath(SegmentID handle);
 
@@ -103,4 +115,4 @@ class IOUringTransport : public Transport {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // TENT_IO_URING_TRANSPORT_H
\ No newline at end of file
+#endif  // TENT_IO_URING_TRANSPORT_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/mnnvl/mnnvl_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/mnnvl/mnnvl_transport.h
index 762a0dc9a5..b9565b0044 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/mnnvl/mnnvl_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/mnnvl/mnnvl_transport.h
@@ -17,13 +17,14 @@
 
 #include <cuda.h>
 #include <cuda_runtime.h>
+#include "tent/common/cuda_fabric_compat.h"
 
 #include <functional>
 #include <iostream>
 #include <mutex>
 #include <queue>
 #include <string>
-#include <unordered_set>
+#include <unordered_map>
 #include <vector>
 
 #include "tent/runtime/control_plane.h"
@@ -126,12 +127,17 @@ class MnnvlTransport : public Transport {
     std::string machine_id_;
 
     std::mutex allocate_mutex_;
-    std::unordered_set<void *> allocate_set_;
+    // VMM allocations owned by this transport: base address -> mapped extent
+    // (rounded to the allocation granularity), needed to unmap on free.
+    std::unordered_map<void *, size_t> allocate_set_;
     uint64_t async_memcpy_threshold_;
     bool supported_;
     CUmemAllocationHandleType handle_type_;
 
     bool host_register_;
+    // transports/mnnvl/egm: export HOST_NUMA (EGM) allocations so peers can
+    // read/write host memory over NVLink; adds dram_to_dram / gpu_to_dram.
+    bool egm_enabled_ = false;
 };
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_adapter.h b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_adapter.h
new file mode 100644
index 0000000000..623d57aeb7
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_adapter.h
@@ -0,0 +1,144 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_TRANSPORT_MPCOMM_MPCOMM_ADAPTER_H
+#define TENT_TRANSPORT_MPCOMM_MPCOMM_ADAPTER_H
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include "tent/common/status.h"
+
+namespace mooncake {
+namespace tent {
+
+// A transfer issued to the MPComm data plane. Zero is never a valid handle,
+// matching MPComm's own convention for an invalid one.
+using MpcommTransferHandle = uint64_t;
+constexpr MpcommTransferHandle kInvalidMpcommTransferHandle = 0;
+
+// Outcome of a transfer that has reached a terminal state, in adapter-neutral
+// terms so that nothing above this boundary needs the provider's headers.
+struct MpcommTransferOutcome {
+    // Whether the provider reported success. MPComm only reports success once
+    // every chunk of the transfer has completed, so this implies the full
+    // request length was moved.
+    bool ok = false;
+    // Bytes the provider accounted for. MPComm counts bytes at post time, so
+    // on success this equals the request length.
+    size_t bytes_transferred = 0;
+    // Provider status, kept for diagnostics only. Zero means success.
+    int native_status = 0;
+};
+
+// Injectable MPComm boundary.
+//
+// This interface deliberately knows nothing about TENT Request, SubBatch,
+// MpcommTask, SegmentDesc or the peer cache: everything above this line is
+// TENT's own logic, and keeping it behind an interface is what lets that logic
+// be tested without RDMA hardware or a real libmpcomm - the same reason
+// UrmaAdapter and TpuPjrtShim exist for their providers.
+//
+// It is a thin pass-through rather than a device abstraction. MPComm owns its
+// own slicing, NIC and QP selection and worker threads, so there is no
+// scheduling here to model; the operations map one to one onto the provider.
+//
+// Threading: implementations must tolerate concurrent calls, because TENT
+// submits and polls transfers from several threads. MPComm itself is
+// thread-safe, so the real adapter adds no locking of its own.
+class MpcommAdapter {
+   public:
+    virtual ~MpcommAdapter() = default;
+
+    // False when the provider is not usable at all - for example when this
+    // build has no libmpcomm. install() must fail in that case rather than
+    // advertise a transport that cannot move data.
+    [[nodiscard]] virtual bool available() const noexcept = 0;
+
+    // --- Lifecycle -------------------------------------------------------
+
+    virtual Status init(const std::string &host_id,
+                        const std::string &device_names, int tcp_port) = 0;
+
+    // The port actually bound for the metadata handshake, which may differ
+    // from the one requested by init().
+    [[nodiscard]] virtual int tcpPort() const = 0;
+
+    virtual Status startAcceptThread() = 0;
+
+    // Teardown is best effort and must be safe to call when init() was never
+    // called or failed part way, since uninstall() runs unconditionally.
+    virtual void stopAcceptThread() = 0;
+    virtual void shutdown() = 0;
+
+    // --- Memory ----------------------------------------------------------
+
+    virtual Status registerMemory(void *addr, size_t length) = 0;
+    virtual void unregisterMemory(void *addr) = 0;
+    virtual Status publishBuffer(void *addr, size_t length, int numa_node) = 0;
+    virtual void unpublishBuffer(void *addr) = 0;
+
+    // --- Peers -----------------------------------------------------------
+
+    // Establishes the provider-level connection to a peer. MPComm keys its
+    // connections by host id and offers no way to close one, so callers must
+    // not call this twice for the same host id: a second call replaces the
+    // connection record wholesale, dropping the remote keys it carries and
+    // leaking the previous queue pairs.
+    virtual Status connect(const std::string &host_id,
+                           const std::string &tcp_addr, int tcp_port) = 0;
+
+    // Fetches the peer's memory keys into the provider's own cache. Idempotent
+    // and safe to repeat: the provider replaces the whole key set atomically,
+    // which is what makes a refresh possible without reconnecting.
+    virtual Status queryRemoteBuffer(const std::string &host_id,
+                                     const std::string &tcp_addr,
+                                     int tcp_port) = 0;
+
+    // --- Data path -------------------------------------------------------
+
+    // Returns kInvalidMpcommTransferHandle when the transfer could not be
+    // issued. A valid handle must eventually be passed to releaseTransfer()
+    // exactly once.
+    virtual MpcommTransferHandle putAsync(uintptr_t local_addr,
+                                          const std::string &host_id,
+                                          uintptr_t remote_addr,
+                                          size_t length) = 0;
+    virtual MpcommTransferHandle getAsync(uintptr_t local_addr,
+                                          const std::string &host_id,
+                                          uintptr_t remote_addr,
+                                          size_t length) = 0;
+
+    [[nodiscard]] virtual bool isTransferComplete(
+        MpcommTransferHandle handle) = 0;
+    virtual MpcommTransferOutcome getTransferResult(
+        MpcommTransferHandle handle) = 0;
+    virtual void releaseTransfer(MpcommTransferHandle handle) = 0;
+};
+
+// Returns the libmpcomm-backed adapter when this build has the provider,
+// otherwise an unavailable stub whose operations fail with an explicit
+// message. Tests inject their own implementation instead of calling this.
+//
+// Shared rather than unique because uninstall() drops the transport's
+// reference: a test that injected an adapter keeps its own so that it can
+// still inspect what the transport did during teardown.
+std::shared_ptr<MpcommAdapter> createDefaultMpcommAdapter();
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_TRANSPORT_MPCOMM_MPCOMM_ADAPTER_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_peer_registry.h b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_peer_registry.h
new file mode 100644
index 0000000000..3bc5a9f6a7
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_peer_registry.h
@@ -0,0 +1,161 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_TRANSPORT_MPCOMM_MPCOMM_PEER_REGISTRY_H
+#define TENT_TRANSPORT_MPCOMM_MPCOMM_PEER_REGISTRY_H
+
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "tent/common/status.h"
+#include "tent/transport/mpcomm/mpcomm_adapter.h"
+
+namespace mooncake {
+namespace tent {
+
+// Endpoint attribute published in the segment descriptor:
+//   "v1:<ipv4>:<port>"
+// The version prefix makes a later format change detectable instead of being
+// silently misparsed by an older peer. An attribute without a prefix is read
+// as v1 so that a peer predating the prefix still interoperates.
+inline constexpr char kMpcommEndpointAttrPrefix[] = "v1:";
+
+// Parses a decimal TCP port. Rejects everything atoi() would quietly turn into
+// 0 or a truncated value, which would then be used as if it were a real port.
+Status parseMpcommTcpPort(const std::string &text, int &port);
+
+// Splits "[v1:]<ipv4>:<port>" into address and port.
+Status parseMpcommEndpointAttr(const std::string &attr, std::string &addr,
+                               int &port);
+
+// Builds the attribute a peer will read, from the local segment name (which is
+// "host:rpc_port") and the port MPComm actually bound. Paired with
+// parseMpcommEndpointAttr so that the published and parsed formats cannot drift
+// apart unnoticed.
+std::string buildMpcommEndpointAttr(const std::string &local_segment_name,
+                                    int tcp_port);
+
+// One buffer range as published by a peer.
+struct MpcommBufferRange {
+    uint64_t addr{0};
+    uint64_t length{0};
+};
+
+// Lifecycle of a cached peer. The connection and the remote memory keys are
+// tracked separately because they are not equally recoverable: MPComm offers no
+// way to close a connection, so a live one must be kept and reused, whereas the
+// keys can be fetched again at any time.
+enum class MpcommPeerState {
+    // No connection yet; the owning caller is establishing one.
+    CONNECTING,
+    // The connection is established but the keys are absent or stale.
+    // Recoverable by querying again - never by reconnecting.
+    CONNECTED_NO_KEYS,
+    // Connection and keys are both valid, the keys covering covered_buffers.
+    READY,
+};
+
+// Cached state of one MPComm peer, keyed by its host id (the segment name).
+struct MpcommPeerInfo {
+    // Endpoint of the live connection. Retained so that a key refresh reaches
+    // the process we are actually connected to, even if the peer has since
+    // started advertising a different endpoint.
+    std::string tcp_addr;
+    int tcp_port{0};
+    MpcommPeerState state{MpcommPeerState::CONNECTING};
+    // Fingerprint of the peer's buffer set when its keys were last fetched,
+    // used as a cheap equality check on the hot path.
+    uint64_t buffers_epoch{0};
+    // The ranges those keys are known to cover. A differing fingerprint alone
+    // is not a reason to refetch: descriptors are cached per thread and expire
+    // independently, so two threads routinely observe different buffer sets for
+    // the same peer during a refresh window. Comparing coverage instead of
+    // equality keeps the decision monotonic - keys are refetched only when a
+    // range appears that they do not cover - which stops threads from
+    // alternately invalidating each other's work and issuing a blocking query
+    // every time. It also avoids refetching when the peer merely unregistered
+    // memory, since keys the peer no longer publishes are harmless.
+    std::vector<MpcommBufferRange> covered_buffers;
+    // Non-zero while a caller is connecting or refetching keys. Kept separate
+    // from the state so that a refresh never has to invalidate keys that are
+    // still usable: a request whose ranges the current keys cover proceeds
+    // while the refresh runs, instead of blocking behind it. The value also
+    // identifies the owner, so that a late cleanup cannot touch the work of a
+    // later one.
+    uint64_t owner_generation{0};
+};
+
+// Owns the MPComm peer cache: which peers are connected, whose keys are
+// current, and who is allowed to talk to a peer at any moment.
+//
+// Split out of MpcommTransport for two reasons. It is the part of the transport
+// with non-trivial concurrency, and it depends only on MpcommAdapter - not on
+// SegmentDesc, ControlService or the TENT runtime - so it can be constructed
+// directly and driven against an injected adapter without RDMA hardware.
+//
+// Keyed by MPComm host id rather than SegmentID because that is what MPComm
+// keys connections by: closing and reopening a segment yields a fresh
+// SegmentID for the same peer, and a second connect() to an already connected
+// peer replaces its connection record wholesale, discarding the remote keys it
+// carries and leaking the queue pairs of the previous one.
+class MpcommPeerRegistry {
+   public:
+    explicit MpcommPeerRegistry(std::shared_ptr<MpcommAdapter> adapter);
+
+    MpcommPeerRegistry(const MpcommPeerRegistry &) = delete;
+    MpcommPeerRegistry &operator=(const MpcommPeerRegistry &) = delete;
+
+    // Makes the peer usable for transfers touching `buffers`: connects if it
+    // has never been connected, and fetches its keys if they are missing or do
+    // not cover those ranges. Concurrent callers for the same peer wait for the
+    // one that owns it rather than contacting the peer a second time.
+    //
+    // `tcp_addr` / `tcp_port` are the endpoint the peer currently advertises.
+    // They are used for a first connection only; afterwards the endpoint the
+    // connection was actually made to is used, since that is the process the
+    // keys must come from.
+    Status ensure(const std::string &host_id, const std::string &tcp_addr,
+                  int tcp_port, const std::vector<MpcommBufferRange> &buffers);
+
+    // Drops every entry and wakes every waiter. Used by uninstall(): a caller
+    // released this way finds its entry gone and fails through the adapter,
+    // which by then reports that the provider is no longer initialised.
+    void clear();
+
+    // Diagnostics. Also what the hardware-free tests assert on, since the
+    // observable effect of this class is which peers it keeps and in what
+    // state.
+    [[nodiscard]] size_t size() const;
+    [[nodiscard]] bool contains(const std::string &host_id) const;
+    // Returns false when the peer is not cached at all.
+    [[nodiscard]] bool stateOf(const std::string &host_id,
+                               MpcommPeerState &state) const;
+
+   private:
+    std::shared_ptr<MpcommAdapter> adapter_;
+    std::unordered_map<std::string, MpcommPeerInfo> peers_;
+    mutable std::mutex mutex_;
+    std::condition_variable cv_;
+    uint64_t next_generation_{0};
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_TRANSPORT_MPCOMM_MPCOMM_PEER_REGISTRY_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_task_mapping.h b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_task_mapping.h
new file mode 100644
index 0000000000..c7cec6dd5a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_task_mapping.h
@@ -0,0 +1,64 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_TRANSPORT_MPCOMM_MPCOMM_TASK_MAPPING_H
+#define TENT_TRANSPORT_MPCOMM_MPCOMM_TASK_MAPPING_H
+
+#include <cstddef>
+#include <string>
+#include <vector>
+
+#include "tent/common/types.h"
+#include "tent/runtime/transport.h"
+#include "tent/transport/mpcomm/mpcomm_adapter.h"
+
+namespace mooncake {
+namespace tent {
+
+// Per-task state for tracking mpcomm async transfers
+struct MpcommTask {
+    Request request;
+    volatile TransferStatusEnum status_word{TransferStatusEnum::PENDING};
+    size_t transferred_bytes{0};
+    MpcommTransferHandle mpcomm_handle{kInvalidMpcommTransferHandle};
+};
+
+// SubBatch implementation for mpcomm transport
+struct MpcommSubBatch : public Transport::SubBatch {
+    std::vector<MpcommTask> task_list;
+    size_t max_size{0};
+    size_t size() const override { return task_list.size(); }
+};
+
+// Issues one request on the adapter, returning the provider handle or
+// kInvalidMpcommTransferHandle.
+//
+// This and pollMpcommTask() are free functions in their own translation unit
+// rather than private methods so that the request/completion mapping can be
+// driven against an injected adapter. That keeps the WRITE/READ mapping, the
+// short-transfer guard and releasing each handle exactly once under test in a
+// build that has neither RDMA hardware nor libmpcomm.
+MpcommTransferHandle issueMpcommTransfer(MpcommAdapter &adapter,
+                                         const Request &request,
+                                         const std::string &host_id);
+
+// Polls one task once and, if the transfer reached a terminal state, records
+// the outcome and releases the handle. A task that is not pending, or that has
+// no outstanding handle, is left untouched.
+void pollMpcommTask(MpcommAdapter &adapter, MpcommTask &task);
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_TRANSPORT_MPCOMM_MPCOMM_TASK_MAPPING_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_transport.h
new file mode 100644
index 0000000000..028ad72acc
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/mpcomm/mpcomm_transport.h
@@ -0,0 +1,94 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_MPCOMM_TRANSPORT_H
+#define TENT_MPCOMM_TRANSPORT_H
+
+#include <cstddef>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/concurrent/rw_spinlock.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/transport.h"
+#include "tent/transport/mpcomm/mpcomm_adapter.h"
+#include "tent/transport/mpcomm/mpcomm_peer_registry.h"
+#include "tent/transport/mpcomm/mpcomm_task_mapping.h"
+
+namespace mooncake {
+namespace tent {
+
+// Maps TENT requests onto MPComm transfers.
+//
+// The transport keeps only what needs the TENT runtime: resolving a SegmentID
+// to a peer, reading the endpoint that peer advertises, and driving batches.
+// Everything that talks to MPComm goes through MpcommAdapter, the peer cache
+// lives in MpcommPeerRegistry and the request/completion mapping in
+// mpcomm_task_mapping - which is what lets all three be exercised in a build
+// with neither RDMA hardware nor libmpcomm.
+class MpcommTransport : public Transport {
+   public:
+    MpcommTransport();
+
+    // Test seam: runs against the supplied MPComm boundary instead of the real
+    // provider. The adapter is shared so that a test still observes what the
+    // transport did after uninstall() has dropped the transport's reference.
+    explicit MpcommTransport(std::shared_ptr<MpcommAdapter> adapter);
+
+    ~MpcommTransport() override;
+
+    Status install(std::string &local_segment_name,
+                   std::shared_ptr<ControlService> metadata,
+                   std::shared_ptr<Topology> local_topology,
+                   std::shared_ptr<Config> conf = nullptr) override;
+
+    Status uninstall() override;
+
+    Status allocateSubBatch(SubBatchRef &batch, size_t max_size) override;
+
+    Status freeSubBatch(SubBatchRef &batch) override;
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request> &request_list) override;
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus &status) override;
+
+    Status addMemoryBuffer(BufferDesc &desc,
+                           const MemoryOptions &options) override;
+
+    Status removeMemoryBuffer(BufferDesc &desc) override;
+
+    const char *getName() const override { return "mpcomm"; }
+
+   private:
+    // Resolve remote segment ID to mpcomm host_id, connecting if needed
+    Status ensurePeerConnected(SegmentID target_id, std::string &host_id);
+
+   private:
+    bool installed_{false};
+    std::string local_segment_name_;
+    std::shared_ptr<ControlService> metadata_;
+    std::shared_ptr<Topology> local_topology_;
+
+    std::shared_ptr<MpcommAdapter> adapter_;
+    std::unique_ptr<MpcommPeerRegistry> peers_;
+    int tcp_port_{0};
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_MPCOMM_TRANSPORT_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/nvlink/nvlink_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/nvlink/nvlink_transport.h
index fd786f08b2..19057290f8 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/nvlink/nvlink_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/nvlink/nvlink_transport.h
@@ -20,6 +20,7 @@
 #include <mutex>
 #include <queue>
 #include <string>
+#include <unordered_map>
 #include <unordered_set>
 #include <vector>
 
@@ -99,6 +100,8 @@ class NVLinkTransport : public Transport {
 
     Status setPeerAccess();
 
+    friend class NVLinkTransportTestPeer;
+
    private:
     bool installed_;
     std::string local_segment_name_;
@@ -125,7 +128,11 @@ class NVLinkTransport : public Transport {
     bool host_register_;
 
     mutable std::mutex register_mutex_;
-    std::unordered_set<uint64_t> registered_base_addrs_;
+    // cudaMalloc base address -> serialized cudaIpcMemHandle_t for that
+    // segment. Multiple BufferDescs can sub-allocate within one cudaMalloc
+    // segment (torch caching allocator); every one of them must carry the
+    // segment's IPC handle or NVLink submission for that buffer fails.
+    std::unordered_map<uint64_t, std::string> registered_base_addrs_;
 };
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/bw_arbitration.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/bw_arbitration.h
index 046ff6a341..3f05733e83 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/bw_arbitration.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/bw_arbitration.h
@@ -32,10 +32,10 @@
 #include <algorithm>
 #include <cstddef>
 #include <cstdint>
-#include <limits>
-#include <numeric>
 #include <vector>
 
+#include "tent/runtime/deadline_mlu.h"
+
 namespace mooncake {
 namespace tent {
 
@@ -46,37 +46,73 @@ struct ArbFlow {
     size_t length;         // bytes to transfer
 };
 
-// Predicted Missed-Latency-per-Unit: predicted transfer time / remaining
-// deadline window. Higher == more urgent (closer to / past its deadline).
-// A flow with no deadline (deadline_ns == 0) is least urgent (MLU 0). A flow
-// already past its deadline, or that cannot fit its window at the given
-// bandwidth, gets a very high MLU so it sorts first. bw_bps <= 0 disables
-// prediction (returns 0 for everyone == no reordering).
-inline double PredictedMlu(const ArbFlow& f, uint64_t now_ns, double bw_bps) {
-    if (f.deadline_ns == 0 || bw_bps <= 0.0) return 0.0;
-    if (f.deadline_ns <= now_ns) return std::numeric_limits<double>::max();
-    const double window_s = (f.deadline_ns - now_ns) / 1e9;
-    const double predicted_time_s = static_cast<double>(f.length) / bw_bps;
-    return predicted_time_s / window_s;
+// Predicted MLU for one contending flow; see DeadlineMlu for the semantics.
+// `bytes_ahead` is what the NIC has to move before this flow: the bytes
+// already posted to it, plus those of the flows OrderByUrgency has placed
+// ahead of this one. Higher == more urgent (closer to / past its deadline).
+// bw_bps <= 0 disables prediction (returns 0 for everyone == no reordering).
+inline double PredictedMlu(const ArbFlow& f, uint64_t now_ns, double bw_bps,
+                           size_t bytes_ahead = 0) {
+    return DeadlineMlu(bytes_ahead, f.length, f.deadline_ns, now_ns, bw_bps);
 }
 
 // Return the indices of `flows` ordered most-urgent-first (highest predicted
-// MLU first). Ties and the no-deadline case keep original (FIFO) order — a
-// stable sort — so a symmetric set degrades to today's behavior. This does not
-// drop or admit anything; it only reorders selection among already-eligible,
-// same-tier flows.
+// MLU first). Ties keep the original relative order, so with no deadlines
+// anywhere the input order is preserved exactly. This never drops or admits
+// anything; it only reorders selection among already-eligible, same-tier
+// flows.
+//
+// The order is built one slot at a time: the flow that takes a slot is then
+// part of what the remaining flows wait behind, so its bytes join
+// `bytes_ahead` before the next slot is scored. `bytes_ahead` on entry is
+// what the NIC owes that is *not* in `flows`. Scoring every flow once
+// against the same value would instead treat all of them as simultaneous.
+//
+// Cost is O(n * kGreedySlots). Callers post a prefix of this order (the QP
+// budget decides how long), so only the head is worth resolving exactly;
+// past kGreedySlots the remainder is ranked in one pass against the bytes
+// accumulated so far.
+inline constexpr size_t kGreedySlots = 64;
+
 inline std::vector<size_t> OrderByUrgency(const std::vector<ArbFlow>& flows,
-                                          uint64_t now_ns, double bw_bps) {
-    std::vector<size_t> idx(flows.size());
-    std::iota(idx.begin(), idx.end(), size_t{0});
-    std::vector<double> mlu(flows.size());
-    for (size_t i = 0; i < flows.size(); ++i) {
-        mlu[i] = PredictedMlu(flows[i], now_ns, bw_bps);
+                                          uint64_t now_ns, double bw_bps,
+                                          size_t bytes_ahead = 0) {
+    const size_t n = flows.size();
+    std::vector<size_t> order;
+    order.reserve(n);
+    std::vector<bool> taken(n, false);
+
+    const size_t greedy = std::min(n, kGreedySlots);
+    for (size_t slot = 0; slot < greedy; ++slot) {
+        size_t best = n;
+        double best_mlu = 0.0;
+        for (size_t i = 0; i < n; ++i) {
+            if (taken[i]) continue;
+            const double mlu =
+                PredictedMlu(flows[i], now_ns, bw_bps, bytes_ahead);
+            // Strictly greater keeps the lowest index on ties (FIFO).
+            if (best == n || mlu > best_mlu) {
+                best = i;
+                best_mlu = mlu;
+            }
+        }
+        taken[best] = true;
+        order.push_back(best);
+        bytes_ahead += flows[best].length;
     }
-    std::stable_sort(idx.begin(), idx.end(), [&](size_t a, size_t b) {
-        return mlu[a] > mlu[b];  // higher MLU first; stable keeps FIFO on ties
-    });
-    return idx;
+    if (order.size() == n) return order;
+
+    std::vector<size_t> rest;
+    rest.reserve(n - order.size());
+    for (size_t i = 0; i < n; ++i)
+        if (!taken[i]) rest.push_back(i);
+    std::vector<double> mlu(n, 0.0);
+    for (size_t i : rest)
+        mlu[i] = PredictedMlu(flows[i], now_ns, bw_bps, bytes_ahead);
+    std::stable_sort(rest.begin(), rest.end(),
+                     [&](size_t a, size_t b) { return mlu[a] > mlu[b]; });
+    order.insert(order.end(), rest.begin(), rest.end());
+    return order;
 }
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/context.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/context.h
index 2c010872e6..6d91bf3822 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/context.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/context.h
@@ -24,6 +24,7 @@
 #include <cstdint>
 #include <list>
 #include <memory>
+#include <mutex>
 #include <string>
 #include <thread>
 #include <unordered_map>
@@ -42,9 +43,22 @@ class RdmaEndPoint;
 class EndpointStore;
 class RdmaTransport;
 
+struct RdmaAddressSnapshot {
+    uint32_t lid = 0;
+    std::string gid;
+    int gid_index = -1;
+};
+
+enum class RdmaAddressRefreshResult {
+    UNCHANGED = 0,
+    CHANGED = 1,
+    FAILED = 2,
+};
+
 class RdmaContext {
     friend class RdmaCQ;
     friend class RdmaEndPoint;
+    friend class RdmaContextTestPeer;
 
    public:
     RdmaContext(RdmaTransport &transport);
@@ -63,6 +77,11 @@ class RdmaContext {
 
     int resume();
 
+    // Evict all cached endpoints so they are rebuilt with fresh QPs.
+    // Called on port recovery (IBV_EVENT_PORT_ACTIVE): QPs that entered
+    // IBV_QPS_ERR while the link was down are stale and must be torn down.
+    void evictEndpoints();
+
     enum DeviceStatus {
         DEVICE_UNINIT,
         DEVICE_DISABLED,
@@ -94,17 +113,50 @@ class RdmaContext {
     const std::string name() const { return device_name_; }
 
    public:
-    uint16_t lid() const { return lid_; }
+    // Take lid/gid/index under one lock so a bootstrap never mixes values from
+    // two address generations while the monitor thread refreshes the port.
+    RdmaAddressSnapshot address() const;
+
+    uint32_t lid() const { return address().lid; }
 
-    std::string gid() const;
+    std::string gid() const { return address().gid; }
 
-    int gidIndex() const { return gid_index_; }
+    int gidIndex() const { return address().gid_index; }
+
+    // Re-query the port's LID and GID. Auto-GID mode repeats the initial
+    // selection; an explicit gid_index keeps that index and refreshes its
+    // value. The new address is published before it becomes visible locally.
+    RdmaAddressRefreshResult refreshAddress(
+        RdmaAddressSnapshot *previous = nullptr,
+        RdmaAddressSnapshot *current = nullptr);
 
     ibv_context *nativeContext() const { return native_context_; }
 
     ibv_pd *nativePD() const { return native_pd_; }
 
-    uint8_t portNum() const { return params_->device.port; }
+    // The one port this context opened; 0 for a slot that never constructed.
+    uint8_t portNum() const { return params_ ? params_->device.port : 0; }
+
+    // Port speed in Gbps: the effective speed from ibv_query_port_speed()
+    // where the library provides it (LAG-aware), otherwise the negotiated
+    // link rate. 0 when neither could be determined.
+    double linkSpeedGbps() const;
+
+    // Re-read the port's negotiated speed and width from the hardware, so
+    // linkSpeedGbps() reflects a renegotiated link. Called from the monitor
+    // thread on IBV_EVENT_PORT_ACTIVE / IBV_EVENT_DEVICE_SPEED_CHANGE.
+    // Returns -1 and leaves the cached values untouched if no device is
+    // open or the query fails.
+    int refreshPortAttributes();
+
+    // Read the port's current state from the hardware. The monitor thread
+    // polls this for paused contexts so a link that came back without a
+    // usable IBV_EVENT_PORT_ACTIVE is still noticed. Deliberately leaves the
+    // cached speed/width alone: refreshLinkSpeed() diffs against them, so
+    // refreshing here would hide a renegotiated rate from the selector.
+    // Returns -1 and leaves *state untouched if no device is open or the
+    // query fails.
+    int queryPortState(ibv_port_state *state) const;
 
     int eventFd() const { return event_fd_; }
 
@@ -114,6 +166,18 @@ class RdmaContext {
 
     RdmaParams &params() const { return *params_.get(); }
 
+    // True while linkSpeedGbps() is derived from ibv_query_port_speed()
+    // rather than the encoded speed x width.
+    bool effectiveSpeedKnown() const {
+        return effective_speed_mbps_.load(std::memory_order_relaxed) > 0;
+    }
+
+    // ibv_query_port_speed() errors since the device was opened. The verb
+    // being absent, or reporting 0, is not an error.
+    uint64_t effectiveSpeedQueryFailures() const {
+        return effective_speed_query_failures_.load(std::memory_order_relaxed);
+    }
+
     // PCIe Relaxed Ordering support
     bool isRelaxedOrderingEnabled() const { return relaxed_ordering_enabled_; }
 
@@ -122,6 +186,19 @@ class RdmaContext {
 
    private:
     int openDevice(const std::string &device_name, uint8_t port);
+    // Decode one ibv_query_port result into active_speed_/active_width_.
+    void recordPortSpeed(const ibv_port_attr &port_attr);
+    // Ask ibv_query_port_speed() for the effective speed when the library
+    // has it; records 0 when the verb is absent or reports nothing, so
+    // linkSpeedGbps() falls back. A verb *error* keeps the last known value
+    // instead: on a degraded LAG, falling back would briefly restore the
+    // higher encoded rate. Failures are counted and logged on transition.
+    void queryEffectiveSpeed();
+
+    // Release every resource currently owned by this context. This is
+    // intentionally state-independent so it can clean up a partially completed
+    // enable() and can safely be retried.
+    void cleanupResources();
 
    private:
     // initialized during ctor, will never be changed during the context's
@@ -139,7 +216,22 @@ class RdmaContext {
     size_t num_comp_channel_ = 0;
     std::vector<ibv_comp_channel *> comp_channel_;
 
-    uint16_t lid_ = 0;
+    // The monitor thread may refresh these while bootstrap handlers read
+    // them. address_mutex_ keeps each lid/gid/index snapshot self-consistent;
+    // address_refresh_mutex_ serializes hardware reprobes and publication.
+    mutable std::mutex address_mutex_;
+    std::mutex address_refresh_mutex_;
+    uint32_t lid_ = 0;
+    // Set by openDevice() and refreshed by refreshPortAttributes() on the
+    // monitor thread. Today every runtime reader is that same thread;
+    // atomic so a reader added elsewhere stays well-defined.
+    std::atomic<int> active_speed_{0};
+    std::atomic<int> active_width_{0};
+    // From ibv_query_port_speed(), converted to Mb/s; 0 = unavailable.
+    std::atomic<uint64_t> effective_speed_mbps_{0};
+    std::atomic<uint64_t> effective_speed_query_failures_{0};
+    // Whether the last query errored; drives the transition logging.
+    std::atomic<bool> effective_speed_query_failing_{false};
     int gid_index_ = -1;
     ibv_gid gid_;
 
@@ -155,7 +247,11 @@ class RdmaContext {
     // PCIe Relaxed Ordering support
     bool relaxed_ordering_enabled_ = false;
 
-    const IbvSymbols &verbs_;
+    // The context's own copy of the loader's verbs table (copied once at
+    // construction, read-only afterwards). A copy rather than a reference so
+    // tests can substitute individual entries and drive the port-attribute
+    // and event paths without an RNIC.
+    IbvSymbols verbs_;
 };
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint.h
index 79e3bafa48..470dd9a6b7 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint.h
@@ -16,12 +16,14 @@
 #define TENT_ENDPOINT_H
 
 #include <atomic>
+#include <functional>
 #include <memory>
 #include <queue>
 #include <unordered_set>
 #include <vector>
 
 #include "context.h"
+#include "tent/common/concurrent/ticket_lock.h"
 
 namespace mooncake {
 namespace tent {
@@ -31,6 +33,8 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
         uint64_t padding[7];
     };
 
+    // Not synchronized: every access goes through queue_lock_list_[qp_index]
+    // (submitSlices / acknowledge) or the endpoint write lock (teardown).
     struct BoundedSliceQueue {
         size_t head, tail, capacity, count;
         std::vector<RdmaSlice*> entries;
@@ -132,6 +136,46 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
 
     bool sendNotification(const std::string& name, const std::string& msg);
 
+    // Whether the notify QP is connected and not disabled after a fault.
+    bool notifyConnected() const {
+        return notify_connected_.load(std::memory_order_acquire);
+    }
+
+    // One notification WR (send or receive) left the CQ. Called by the
+    // transport for every completion of this endpoint's notify QP.
+    void noteNotifyCompletion() {
+        uint32_t inflight = notify_inflight_.load(std::memory_order_relaxed);
+        while (inflight > 0 &&
+               !notify_inflight_.compare_exchange_weak(
+                   inflight, inflight - 1, std::memory_order_acq_rel,
+                   std::memory_order_relaxed)) {
+        }
+    }
+
+    uint32_t notifyInflight() const {
+        return notify_inflight_.load(std::memory_order_acquire);
+    }
+
+    // Whether a consumed notify RECV slot is posted again. Only while the
+    // endpoint is ready and its notify QP connected: a retiring endpoint's
+    // QP is in ERR, and so is the QP of an endpoint whose notifications were
+    // disabled, because the local completion error that disables them has
+    // already moved the RC QP to ERR. A post on either is wasted work - this
+    // provider accepts it and flushes it straight back, one that checks the
+    // state rejects it and logs - and the initial posting in connect() /
+    // accept() does not go through here.
+    static bool shouldRearmNotifyRecv(EndPointStatus status,
+                                      bool notify_connected) {
+        return status == EP_READY && notify_connected;
+    }
+
+    // Turns notifications off after a fault confined to the notify QP,
+    // leaving the data QPs and the endpoint lifecycle untouched.
+    // Notifications stay off for the remaining lifetime of the endpoint. The
+    // QP itself stays published until deconstruct(), so completions already
+    // in the CQ are still delivered.
+    void disableNotification(const std::string& reason);
+
     // Process RECV completion: parse message and add to transport queue
     // directly
     bool handleNotifyRecv(size_t buffer_idx, size_t byte_len);
@@ -155,23 +199,38 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
         bool failed;
     };
 
-    int submitSlices(std::vector<RdmaSlice*>& slice_list, int qp_index);
+    // Post as many of `slice_list` as the queue pair's budget allows and
+    // return how many were taken (posted or marked `failed`). `on_post`,
+    // when given, runs for each of those before ibv_post_send: on a shared
+    // queue pair another lane can poll a completion before this call
+    // returns, so whatever the poller must find in place (the posted
+    // device, the set entry) has to be written first. Slices the hardware
+    // rejects come back with `failed` set; the caller undoes what it did for
+    // them.
+    int submitSlices(std::vector<RdmaSlice*>& slice_list, int qp_index,
+                     const std::function<void(RdmaSlice*)>& on_post = {});
 
     int submitRecvImmDataRequest(int qp_index, uint64_t id);
 
-    size_t acknowledge(RdmaSlice* slice, TransferStatusEnum status);
+    // Pop `slice` and every slice queued before it on the same QP, giving
+    // them `status`. `on_each` is invoked for every popped slice so the
+    // caller can return per-slice accounting (the worker's selector charge)
+    // for slices it never sees otherwise.
+    size_t acknowledge(RdmaSlice* slice, TransferStatusEnum status,
+                       const std::function<void(RdmaSlice*)>& on_each = {});
 
     std::atomic<int>* getQuotaCounter(int qp_index) const {
         return &wr_depth_list_[qp_index].value;
     }
 
    private:
-    int setupAllQPs(const std::string& peer_gid, uint16_t peer_lid,
-                    std::vector<uint32_t> peer_qp_num_list,
+    int setupAllQPs(const std::string& peer_gid, uint32_t peer_lid,
+                    std::vector<uint32_t> peer_qp_num_list, int local_gid_index,
                     std::string* reply_msg = nullptr);
 
-    int setupOneQP(int qp_index, const std::string& peer_gid, uint16_t peer_lid,
-                   uint32_t peer_qp_num, std::string* reply_msg = nullptr);
+    int setupOneQP(int qp_index, const std::string& peer_gid, uint32_t peer_lid,
+                   uint32_t peer_qp_num, int local_gid_index,
+                   std::string* reply_msg = nullptr);
 
     // Returns the pool segment owning qp_index, or nullptr when no pools are
     // configured (the default single-pool case). Read-only after construct().
@@ -189,24 +248,42 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
     void resetInflightSlices();
 
     void postNotifyRecv(size_t idx);
+    // postNotifyRecv() for a slot that has just been consumed, subject to
+    // shouldRearmNotifyRecv().
+    void rearmNotifyRecv(size_t idx);
     void repostAllNotifyRecvs();
 
+    static char* notifySlotPtr(char* base, size_t idx);
+    static bool encodeNotifyPayload(char* slot, const std::string& name,
+                                    const std::string& msg, uint32_t* out_len);
+    static bool decodeNotifyPayload(const char* data, size_t byte_len,
+                                    std::string* name, std::string* msg);
+
    private:
     friend class EndpointTestAccess;
+    friend class RdmaEndPointTestPeer;
 
     std::atomic<EndPointStatus> status_;
     RdmaContext* context_;
     EndPointParams* params_;
     std::string endpoint_name_;
+    // Immutable address generation used to create this endpoint's QPs and
+    // bootstrap descriptors. A context refresh evicts the whole endpoint.
+    RdmaAddressSnapshot local_address_;
 
     std::vector<ibv_qp*> qp_list_;
     // Per-pool QP layout, resolved once in construct() from params_->qp_pools.
     // Empty = default single pool spanning all of qp_list_. Each segment's
     // [begin, begin+num_qp) indexes into qp_list_. Read-only after construct().
     std::vector<QpPoolSegment> qp_pool_segments_;
-    // Each data QP queue is owned by exactly one worker lane; reset/deconstruct
-    // are synchronized by the endpoint lifecycle lock.
+    // One queue per data QP, in posting order, so acknowledge() can retire
+    // everything up to a completed slice. A qp_pools layout with fewer QPs
+    // than lanes lets several lanes reach one queue under the shared read
+    // guard; queue_lock_list_[i] serializes posting and acknowledging on
+    // QP i, and is uncontended in the default one-lane-per-QP layout.
+    // reset/deconstruct are synchronized by the endpoint lifecycle lock.
     std::vector<BoundedSliceQueue> slice_queue_;
+    TicketLock* queue_lock_list_;
     WrDepthBlock* wr_depth_list_;
     std::atomic<int> inflight_slices_;
     uint32_t padding_[7];
@@ -221,13 +298,14 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
     // Notification QP (one per endpoint for control plane operations)
     ibv_qp* notify_qp_ = nullptr;
 
-    // Notification buffers
+    // Notification buffers. Send and recv each use one contiguous host buffer
+    // split into kNotifyMaxPendingSends slots, registered with a single MR.
     static constexpr size_t kNotifyBufferSize = 65536;  // 64 KB
     static constexpr size_t kNotifyMaxPendingSends = 256;
-    std::vector<std::vector<char>> notify_recv_buffers_;
-    std::vector<ibv_mr*> notify_recv_mrs_;  // Memory regions for recv buffers
-    std::vector<char> notify_send_buffer_;  // Single contiguous send buffer
-    ibv_mr* notify_send_mr_ = nullptr;      // Single MR for all send slots
+    std::vector<char> notify_recv_buffer_;
+    ibv_mr* notify_recv_mr_ = nullptr;
+    std::vector<char> notify_send_buffer_;
+    ibv_mr* notify_send_mr_ = nullptr;
     // Serializes notification buffer/QP access against deconstruction.
     std::mutex notify_resource_mutex_;
     std::mutex notify_send_mutex_;
@@ -235,6 +313,11 @@ class RdmaEndPoint : public std::enable_shared_from_this<RdmaEndPoint> {
     size_t notify_pending_count_ = 0;  // Number of pending sends
     uint64_t notify_send_wr_id_ = 0;   // Circular counter for wr_id
     std::atomic<bool> notify_connected_{false};
+    // Notification WRs posted on the notify QP whose completion has not been
+    // polled yet. finishDestroy() waits for it: the QP must not be destroyed
+    // while completions the peer already saw acknowledged are still in the CQ,
+    // because the provider drops them with the QP.
+    std::atomic<uint32_t> notify_inflight_{0};
 
     // Two-phase destruction constants (matching TE)
     static constexpr double kFinishDestroyTimeoutSec = 30.0;
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint_store.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint_store.h
index 48f656d0f7..d341a76b9c 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint_store.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/endpoint_store.h
@@ -48,6 +48,13 @@ class EndpointStore {
     virtual size_t size() = 0;
 
     virtual void evictOne() = 0;
+
+    // Evict all endpoints: move every entry to the waiting list and begin
+    // destroying it.  Called on port recovery so that QPs that entered
+    // IBV_QPS_ERR while the link was down are torn down and rebuilt on the
+    // next getOrInsert().
+    virtual void evictAll() = 0;
+
     virtual void reclaim() = 0;
 };
 
@@ -67,6 +74,7 @@ class FIFOEndpointStore : public EndpointStore {
 
     size_t size() override;
 
+    void evictAll() override;
     void evictOne() override;
     void reclaim() override;
 
@@ -100,6 +108,7 @@ class SIEVEEndpointStore : public EndpointStore {
     size_t size() override;
 
     int remove(RdmaEndPoint *ep) override;
+    void evictAll() override;
     void evictOne() override;
     void reclaim() override;
 
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/ibv_loader.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/ibv_loader.h
index 4b0f68d719..7b5575319c 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/ibv_loader.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/ibv_loader.h
@@ -29,8 +29,20 @@ struct IbvSymbols {
                             struct ibv_device_attr* device_attr);
     int (*ibv_query_gid)(struct ibv_context* context, uint8_t port_num,
                          int index, union ibv_gid* gid);
+    // The entry point behind the ibv_query_gid_ex() header inline. Taken
+    // through the table like the rest so GID scanning can be stood in for;
+    // call it through QueryGidEx() below rather than passing entry_size by
+    // hand.
+    int (*ibv_query_gid_ex)(struct ibv_context* context, uint32_t port_num,
+                            uint32_t gid_index, struct ibv_gid_entry* entry,
+                            uint32_t flags, size_t entry_size);
     int (*ibv_query_port_default)(ibv_context* context, uint8_t port_num,
                                   ibv_port_attr* port_attr);
+    // Optional (rdma-core >= 62): effective port speed in 100 Mb/s units,
+    // LAG-aware. nullptr on older libraries; callers fall back to the
+    // ibv_port_attr encodings.
+    int (*ibv_query_port_speed)(ibv_context* context, uint32_t port_num,
+                                uint64_t* port_speed);
     const char* (*ibv_get_device_name)(struct ibv_device* device);
 
     ibv_pd* (*ibv_alloc_pd)(ibv_context* context);
@@ -61,6 +73,15 @@ struct IbvSymbols {
     int (*ibv_fork_init)(void);
 };
 
+// ibv_query_gid_ex() as the header defines it, but dispatched through a
+// context's own symbol table.
+inline int QueryGidEx(const IbvSymbols& verbs, ibv_context* context,
+                      uint32_t port_num, uint32_t gid_index,
+                      ibv_gid_entry* entry) {
+    return verbs.ibv_query_gid_ex(context, port_num, gid_index, entry,
+                                  /*flags=*/0, sizeof(*entry));
+}
+
 class IbvLoader {
    public:
     static IbvLoader& Instance();
@@ -84,4 +105,4 @@ class IbvLoader {
 
 }  // namespace tent
 }  // namespace mooncake
-#endif
\ No newline at end of file
+#endif
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/params.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/params.h
index b438281dd6..b54c03997f 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/params.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/params.h
@@ -147,6 +147,45 @@ inline int selectQpInPool(const std::vector<QpPoolSegment>& segments,
     return candidate % total_qp;
 }
 
+// Attributes the notification QP takes on its INIT->RTR and RTR->RTS
+// transitions. The data QPs of the same endpoint read these from
+// EndPointParams (RdmaEndPoint::setupOneQP); the notify QP used to hard-code
+// the verbs tutorial values instead, so its retry budget could not be tuned
+// and a dead peer path nominally took 4.096us * 2^18 * 8 ~= 8.6 s to report
+// (about 15 s measured on ConnectX-7) while the data QPs nominally give up in
+// ~0.5 s (about 3.7 s measured). Kept free-standing (no verbs handles) so the
+// mapping can be unit-tested without a device.
+struct NotifyQpRtrAttrs {
+    ibv_mtu path_mtu;
+    uint8_t min_rnr_timer;
+    uint8_t max_dest_rd_atomic;
+};
+
+struct NotifyQpRtsAttrs {
+    uint8_t timeout;
+    uint8_t retry_cnt;
+    uint8_t rnr_retry;
+    uint8_t max_rd_atomic;
+};
+
+// The notify QP only carries SEND/RECV, so one outstanding RDMA read/atomic
+// is all it ever needs; that part stays at 1 regardless of the data-QP value.
+inline NotifyQpRtrAttrs buildNotifyQpRtrAttrs(const EndPointParams& params) {
+    return {params.path_mtu, params.min_rnr_timer, /*max_dest_rd_atomic=*/1};
+}
+
+// The notify QP is the endpoint's only SEND/RECV QP, so it is the only QP
+// that can see RNR NAKs: a burst larger than the receiver's posted RECV slots
+// (kNotifyMaxPendingSends) is ordinary flow control there, not a fault, and
+// must never exhaust a retry budget and retire the endpoint together with its
+// data QPs. rnr_retry therefore stays at 7 (infinite) regardless of
+// send_rnr_count; the RNR *timer* still follows params so a stalled receiver
+// is re-polled as quickly as the data QPs would be.
+inline NotifyQpRtsAttrs buildNotifyQpRtsAttrs(const EndPointParams& params) {
+    return {params.send_timeout, params.send_retry_count,
+            /*rnr_retry=*/7, /*max_rd_atomic=*/1};
+}
+
 struct WorkerParams {
     int num_workers = 6;  // Derived from RdmaParams::num_lanes.
     int max_retry_count = 8;
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/promotion_policy.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/promotion_policy.h
index a5d3a92549..ecdcbf043a 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/promotion_policy.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/promotion_policy.h
@@ -37,10 +37,10 @@ struct PromotionDecision {
     bool promoted_any() const { return !promote_indices.empty(); }
 };
 
-// Historical policy (as implemented in Workers::promoteTimedOutRequests today):
-// the pass drains the whole queue, inspects ONLY the head entry, and if the
-// head has timed out it promotes EVERY entry in the queue. This is the behavior
-// #2528 flags as unintended:
+// Default policy (Workers::promoteTimedOutRequests when
+// transports/rdma/priority_promotion_per_entry is false): the pass drains the
+// whole queue, inspects ONLY the head entry, and if the head has timed out it
+// promotes EVERY entry in the queue. Issue #2528 flags this as unintended:
 //   * decision is head-only but applied to the whole queue -> freshly enqueued
 //     entries that are not starving get promoted alongside the starving head;
 //   * if the head has NOT timed out, later timed-out entries are not promoted.
@@ -68,10 +68,10 @@ inline PromotionDecision DecidePromotionHeadOnly(
     return d;
 }
 
-// Per-entry policy: promote exactly the entries that have themselves timed out,
-// leaving freshly enqueued entries in place. This is the behavior #2528
-// proposes; kept here next to the historical policy so a test can contrast the
-// two and a follow-up fix can switch Workers over to it.
+// Opt-in per-entry policy (transports/rdma/priority_promotion_per_entry=true):
+// promote exactly the entries that have themselves timed out, leaving freshly
+// enqueued entries in place. Workers::promoteTimedOutRequests selects this or
+// DecidePromotionHeadOnly from the config flag.
 inline PromotionDecision DecidePromotionPerEntry(
     const std::vector<uint64_t>& enqueue_ts, uint64_t current_ts,
     uint64_t promotion_timeout_ns) {
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/quota.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/quota.h
index 9273e507d7..055f04b67c 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/quota.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/quota.h
@@ -30,11 +30,6 @@
 namespace mooncake {
 namespace tent {
 
-// Bandwidth constants (Gbps)
-static constexpr double kDefaultBwGbps = 400.0;
-static constexpr double kMinBwGbps = 10.0;
-static constexpr double kMaxBwGbps = 800.0;
-
 class SharedSlotManager;
 
 /**
@@ -56,6 +51,19 @@ class SharedSlotManager;
  * EWMA update:
  *     ewma_bandwidth <- alpha * ewma_bandwidth + (1 - alpha) *
  * observed_bandwidth
+ *
+ * Besides the selection EWMA, each device carries a transmit estimate for
+ * the deadline predictors (admission drop, NIC arbitration): the same update
+ * rule and clamp, but fed from a meter -- bytes completed over the time the
+ * NIC spent with work posted to it, so idle gaps inside an interval are not
+ * charged -- rather than from any one completion's latency. Per-completion
+ * timing cannot answer "how fast does this NIC move bytes": work requests
+ * are posted in batches whose timestamps are effectively one, and a poll
+ * pass timestamps their completions together, so a slice's own
+ * post-to-completion grows with the depth of the batch it travelled in. The
+ * selection EWMA goes on learning from each successful completion's own
+ * post-to-completion time on purpose, so that a NIC backed up behind
+ * earlier work requests scores worse.
  */
 class DeviceSelector {
    public:
@@ -66,17 +74,59 @@ class DeviceSelector {
         bool is_cross_numa;
     };
 
-    struct DeviceInfo {
+    // 64-byte aligned so the padding below really does put each hot atomic
+    // on a cache line of its own (the map's nodes would otherwise place the
+    // struct at any 8-byte boundary).
+    struct alignas(64) DeviceInfo {
         int dev_id;
-        double bw_gbps;
+        // Negotiated link speed in Gbps. setDeviceBandwidth() may rewrite it
+        // after traffic has started while workers read it in release(), so
+        // it is atomic.
+        std::atomic<double> bw_gbps{0.0};
         int numa_id;
+        // False for a NIC that cannot carry traffic: context never
+        // constructed, or port down. Excluded from candidate construction
+        // and from every aggregate; the bandwidth fields are meaningless
+        // while false. Fits the alignment hole after numa_id, so the padding
+        // below still puts inflight_bytes on its own cache line.
+        std::atomic<bool> available{true};
         uint64_t padding0[5];
         std::atomic<uint64_t> inflight_bytes{0};
         uint64_t padding1[7];
         std::atomic<double> ewma_bandwidth_bps{50e9};
         uint64_t padding2[7];
+        std::atomic<double> ewma_transmit_bps{50e9};
+        uint64_t padding4[7];
         std::atomic<uint64_t> total_bytes{0};
-        uint64_t padding3[5];
+        uint64_t padding3[7];
+        // Bytes handed to the hardware: charged when a WR is posted and
+        // returned when it leaves the queue pair. Unlike inflight_bytes
+        // (charged at allocation) this is the NIC's own backlog.
+        std::atomic<uint64_t> posted_bytes{0};
+        uint64_t padding5[7];
+        // Bytes that completed successfully, monotonic.
+        std::atomic<uint64_t> completed_bytes{0};
+        uint64_t padding6[7];
+        // Transmit meter: the counters as of the last sample, which the
+        // next one measures against. Whichever worker wins the CAS on
+        // meter_ts owns that sample and is the only one touching the other
+        // two. resetTransmitMeter only zeroes meter_ts, so the next sample
+        // rebuilds both baselines under its own CAS instead of learning; a
+        // sampler that had already won before the reset finishes on the
+        // baselines it took, which are at least consistent with each other.
+        std::atomic<uint64_t> meter_ts{0};
+        std::atomic<uint64_t> meter_completed{0};
+        std::atomic<uint64_t> meter_busy_ns{0};
+        // Time this NIC has spent with something posted to it, and when the
+        // stretch in progress began. Advanced only on the posted_bytes
+        // 0 <-> non-zero transitions, so the cost is one timestamp per burst
+        // edge rather than per slice. busy_since is never cleared: a stale
+        // value can only over-count busy time, which reads the link slow,
+        // whereas a zero would charge it the whole clock and read it as
+        // stopped.
+        std::atomic<uint64_t> busy_ns{0};
+        std::atomic<uint64_t> busy_since{0};
+        uint64_t padding7[3];
 
         uint64_t getInflightBytes() const {
             return inflight_bytes.load(std::memory_order_relaxed);
@@ -94,10 +144,12 @@ class DeviceSelector {
             return ewma_bandwidth_bps.load(std::memory_order_relaxed);
         }
 
-        double getTheoreticalBandwidth() const {
-            if (bw_gbps >= kMinBwGbps && bw_gbps <= kMaxBwGbps)
-                return bw_gbps * 1e9 / 8.0;
-            return kDefaultBwGbps * 1e9 / 8.0;
+        double getTransmitBandwidth() const {
+            return ewma_transmit_bps.load(std::memory_order_relaxed);
+        }
+
+        uint64_t getPostedBytes() const {
+            return posted_bytes.load(std::memory_order_relaxed);
         }
     };
 
@@ -110,6 +162,22 @@ class DeviceSelector {
 
     Status loadTopology(std::shared_ptr<Topology> &local_topology);
 
+    // Record the link speed ibv_query_port reported for dev_id and re-seed
+    // its EWMA from it, replacing whatever was learned and re-deriving the
+    // clamp. A value outside [min, max]_bandwidth_gbps (including 0 =
+    // unknown) falls back to default_bandwidth_gbps. Call after
+    // setSchedulingParams; may be called again at runtime when the link
+    // renegotiates.
+    Status setDeviceBandwidth(int dev_id, double gbps);
+
+    // Mark dev_id able (or unable) to carry traffic. Unavailable devices are
+    // never selected and do not count toward the aggregate bandwidth. May be
+    // called from the monitor thread while workers allocate; readers see the
+    // flag on their next allocate/aggregate.
+    Status setDeviceAvailable(int dev_id, bool available);
+    // False for an unknown device.
+    bool isDeviceAvailable(int dev_id) const;
+
     std::shared_ptr<Topology> getTopology() const { return local_topology_; }
 
     Status enableSharedQuota(const std::string &shm_name);
@@ -120,7 +188,15 @@ class DeviceSelector {
 
     // Allocate devices for a request (new API)
     // slice_bytes: pre-calculated slice size from rdma_transport to ensure
-    // consistency
+    // consistency.
+    //
+    // The slices partition the request: the first num_slices - 1 carry
+    // slice_bytes each and the last carries what is left, which is a block
+    // plus a folded-in tail when planRdmaSlices() folded one -- so it can be
+    // longer than slice_bytes. Each device is charged what its slices
+    // actually carry, so release(), which returns a slice's real length,
+    // balances. Charging every slice slice_bytes would leave the folded tail
+    // released but never charged, and inflight_bytes is unsigned.
     Status allocate(uint64_t total_length, uint32_t num_slices,
                     uint64_t slice_bytes, const std::string &location,
                     std::vector<int> &slice_dev_ids, int priority = PRIO_HIGH,
@@ -129,6 +205,58 @@ class DeviceSelector {
     Status allocate(uint64_t length, const std::string &location,
                     int &chosen_dev_id);
 
+    // Allocate one device for the per-slice path. Small requests do not go
+    // through the aggregate allocator, but must still honor the request
+    // priority and transport policy's device mask. Keep the three-argument
+    // overload above for source and binary compatibility.
+    Status allocate(uint64_t length, const std::string &location,
+                    int &chosen_dev_id, int priority, uint64_t device_mask);
+
+    // The NIC's own backlog: `notePosted` when a WR reaches the hardware,
+    // `notePostEnded` when it leaves the queue pair (completion, sweep or
+    // cancellation). This is the queue a slice posted now waits behind --
+    // work still sitting in a worker queue is not part of it. `now_ns` marks
+    // the transitions between an idle and a busy NIC, which is the time the
+    // transmit meter charges its bytes to.
+    void notePosted(int dev_id, uint64_t bytes, uint64_t now_ns);
+    void notePostEnded(int dev_id, uint64_t bytes, uint64_t now_ns);
+    uint64_t getPostedBytes(int dev_id) const;
+    // Nanoseconds this device has spent with something posted to it.
+    uint64_t getBusyNs(int dev_id) const;
+
+    // A successful completion moved `bytes` on the wire.
+    void noteCompleted(int dev_id, uint64_t bytes);
+
+    // Abandon the meter's current interval without learning from it. Busy
+    // time is only worth dividing into bytes that the NIC spent it moving,
+    // so a posted slice that ends without its bytes being counted -- failed,
+    // flushed, timed out -- makes the stretch it belonged to unusable. The
+    // next sample starts over from fresh baselines. A NIC that keeps
+    // producing such slices faster than the meter interval therefore never
+    // closes an interval and keeps its last estimate.
+    void resetTransmitMeter(int dev_id);
+
+    // Feed the transmit estimate one throughput sample -- bytes completed
+    // over the busy time accrued since the last sample -- if this device's
+    // meter interval has passed. Per-completion latency cannot serve here:
+    // work requests are posted in batches whose timestamps are effectively
+    // one, and a poll pass timestamps every completion it reaps alike, so a
+    // slice's own "post to completion" grows with the batch depth. Bytes
+    // over busy time does not care how the work was batched, and charges
+    // nothing for the gaps in which the NIC had nothing posted.
+    void maybeSampleTransmit(int dev_id, uint64_t now_ns);
+
+    // Charge `length` bytes to one device without running device selection,
+    // for a caller that has already settled on it: a retry re-posting a
+    // slice whose charge the failure path returned, or a first attempt
+    // falling back from the NIC the allocator picked. release() balances
+    // it. Fails only for a device the selector does not know.
+    Status chargeDevice(int dev_id, uint64_t length);
+
+    // Return a slice's inflight charge and learn from its completion.
+    // `latency` is a successful attempt's post->completion time and feeds
+    // the selection EWMA; <= 0 means no sample. The transmit estimate is
+    // fed by the meter instead, see maybeSampleTransmit().
     Status release(int dev_id, uint64_t length, double latency);
 
     Status getNicLoadStats(std::vector<NicLoadStats> &stats) const;
@@ -153,6 +281,13 @@ class DeviceSelector {
 
     double getAggregateEwmaBandwidth() const;
 
+    // Bytes charged to one device and not yet released, or 0 if unknown.
+    uint64_t getInflightBytes(int dev_id) const;
+    // Transmit estimate (bytes/s) for one device, or -1 if unknown.
+    double getTransmitBandwidth(int dev_id) const;
+    // Sum of the transmit estimates over all devices, or -1 if none.
+    double getAggregateTransmitBandwidth() const;
+
     void fillDevicePriorities();
     int getDevicePriority(int dev_id) const;
 
@@ -161,10 +296,28 @@ class DeviceSelector {
         double numa_tier_weights[Topology::DevicePriorityRanks] = {1.0, 5.0,
                                                                    10.0};
 
+        // Hard-exclude known cross-NUMA NICs; unknown NUMA keeps
+        // numa_tier_weights.
+        bool strict_local_numa = false;
+
         // EWMA bandwidth learning rate (0.0 = full adaptation, 1.0 = no
         // learning)
         double bandwidth_learning_rate = 0.01;
 
+        // Transmit estimate learning rate, same convention. One sample per
+        // meter interval below, so 0.9 is ~10 intervals (100 ms) to follow a
+        // change -- slow enough that one odd interval cannot flip an
+        // irreversible drop decision.
+        double transmit_bandwidth_learning_rate = 0.9;
+
+        // How often a device's throughput is sampled, and how far back a
+        // sample may reach before it is dropped instead of learned from: the
+        // meter charges bytes to busy time, so idle gaps do not spoil an
+        // interval, but a sample spanning this much wall clock describes a
+        // link too far in the past to attribute to the link as it is now.
+        uint64_t transmit_meter_interval_ns = 10'000'000;      // 10 ms
+        uint64_t transmit_meter_max_interval_ns = 50'000'000;  // 50 ms
+
         // Enable priority-based filtering
         bool enable_priority_filtering = true;
 
@@ -181,10 +334,11 @@ class DeviceSelector {
         double ewma_min_multiplier = 0.1;   // 10% of theoretical
         double ewma_max_multiplier = 10.0;  // 1000% of theoretical
 
-        // Default bandwidth (Gbps) when topology info unavailable
-        double default_bandwidth_gbps = 400.0;  // Default NIC bandwidth
-        double min_bandwidth_gbps = 10.0;       // Minimum valid NIC bandwidth
-        double max_bandwidth_gbps = 800.0;      // Maximum valid NIC bandwidth
+        // Bandwidth (Gbps) assumed for a device whose link speed is unknown
+        // or outside [min, max]
+        double default_bandwidth_gbps = 400.0;
+        double min_bandwidth_gbps = 10.0;   // Minimum valid NIC bandwidth
+        double max_bandwidth_gbps = 800.0;  // Maximum valid NIC bandwidth
 
         // Shared slot rotation interval (milliseconds)
         int slot_rotation_interval_ms = 2;
@@ -194,12 +348,26 @@ class DeviceSelector {
 
     void setSchedulingParams(const SchedulingParams &params) {
         sched_params_ = params;
+        // Both are weights on the old EWMA value; outside [0, 1] the update
+        // is meaningless (negative or runaway estimates).
+        sched_params_.bandwidth_learning_rate =
+            std::clamp(params.bandwidth_learning_rate, 0.0, 1.0);
+        sched_params_.transmit_bandwidth_learning_rate =
+            std::clamp(params.transmit_bandwidth_learning_rate, 0.0, 1.0);
+        // A staleness bound shorter than the sampling interval would reject
+        // every sample, silently freezing the estimate on its seed.
+        sched_params_.transmit_meter_max_interval_ns =
+            std::max(params.transmit_meter_max_interval_ns,
+                     params.transmit_meter_interval_ns);
     }
 
     const SchedulingParams &getSchedulingParams() const {
         return sched_params_;
     }
 
+    // Startup warning if the flag excludes every NIC or classifies none.
+    void auditStrictLocalNuma() const;
+
    private:
     std::shared_ptr<Topology> local_topology_;
     std::unordered_map<int, DeviceInfo> devices_;
@@ -207,6 +375,40 @@ class DeviceSelector {
     bool smart_selection_enabled_ = true;
     SchedulingParams sched_params_;
 
+    // Bytes/s the device is rated for: bw_gbps when it is inside the
+    // configured [min, max], default_bandwidth_gbps otherwise.
+    double theoreticalBandwidth(const DeviceInfo &dev) const;
+
+    // Nanoseconds `dev` has spent with work posted, up to `now_ns`: the
+    // stretches that have ended plus the one still open. Both the sample
+    // and the reset measure against this, so they cannot drift apart.
+    static uint64_t busyNsAt(const DeviceInfo &dev, uint64_t now_ns);
+
+    // EWMA step with the [min, max] x theoretical clamp: new = alpha * old
+    // + (1 - alpha) * observed.
+    void learnRate(const DeviceInfo &dev, std::atomic<double> &series,
+                   double alpha, double observed_bps) const;
+
+    // Known to the selector and currently able to carry traffic.
+    bool usable(int dev_id) const {
+        auto it = devices_.find(dev_id);
+        return it != devices_.end() &&
+               it->second.available.load(std::memory_order_relaxed);
+    }
+
+    const char *noEligibleDeviceReason() const {
+        return sched_params_.strict_local_numa
+                   ? "no eligible devices (strict_local_numa excludes "
+                     "cross-NUMA NICs)"
+                   : "no eligible devices";
+    }
+
+    bool isNumaEligible(const Topology::MemEntry *entry, int dev_id) const {
+        if (!sched_params_.strict_local_numa) return true;
+        if (!entry || !local_topology_) return true;
+        return !local_topology_->isCrossNuma(*entry, dev_id);
+    }
+
     Status buildCandidates(const Topology::MemEntry *entry,
                            uint64_t slice_bytes, uint64_t device_mask,
                            std::vector<Candidate> &candidates,
@@ -216,9 +418,12 @@ class DeviceSelector {
                           uint32_t num_slices, uint64_t total_length,
                           std::vector<int> &slice_dev_ids);
 
+    // `slice_bytes` is the caller's block size: slice i carries
+    // min(slice_bytes, total_length - i * slice_bytes), and that is what
+    // release() will return, so it is also what gets charged.
     void selectMultiPath(const std::vector<Candidate> &candidates,
                          uint32_t num_slices, uint64_t total_length,
-                         std::vector<int> &slice_dev_ids,
+                         uint64_t slice_bytes, std::vector<int> &slice_dev_ids,
                          bool probe_mode = false);
 };
 
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/rail_monitor.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/rail_monitor.h
index f69e453c29..4ef853af9c 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/rail_monitor.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/rail_monitor.h
@@ -51,11 +51,17 @@ class RailMonitor {
     RailMonitor &operator=(const RailMonitor &) = delete;
 
    public:
+    // The shared topology references keep segment snapshots alive while rail
+    // failure handling uses their derived mappings.
     // rail_topo_json: optional JSON string describing rail topology.
     // conf: optional Config pointer; when non-null, overrides the default
     //   error_threshold / error_window_secs / cooldown_secs values via
     //   kCfgErrorThreshold / kCfgErrorWindowSecs / kCfgCooldownSecs.
-    Status load(const Topology *local, const Topology *remote,
+    // A later call with the same NIC/memory layout only refreshes the pins
+    // (segment COW snapshots); it does not rebuild rail_states_ or reprint
+    // the config banner.
+    Status load(std::shared_ptr<const Topology> local,
+                std::shared_ptr<const Topology> remote,
                 const std::string &rail_topo_json = "",
                 const Config *conf = nullptr);
 
@@ -69,7 +75,9 @@ class RailMonitor {
 
     int findBestRemoteDevice(int local_nic, int remote_numa);
 
-    const Topology *remote() { return remote_; }
+    const Topology *local() const { return local_.get(); }
+
+    const Topology *remote() const { return remote_.get(); }
 
    private:
     Status loadFromJson(const std::string &rail_topo_json);
@@ -80,8 +88,8 @@ class RailMonitor {
 
    private:
     bool ready_{false};
-    const Topology *local_{nullptr};
-    const Topology *remote_{nullptr};
+    std::shared_ptr<const Topology> local_;
+    std::shared_ptr<const Topology> remote_;
 
     struct PairHash {
         std::size_t operator()(const std::pair<int, int> &p) const noexcept {
@@ -114,4 +122,4 @@ class RailMonitor {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // TENT_RAIL_MONITOR_H
\ No newline at end of file
+#endif  // TENT_RAIL_MONITOR_H
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/rdma_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/rdma_transport.h
index 6ff05db7b8..408c998c87 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/rdma_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/rdma_transport.h
@@ -70,6 +70,8 @@ class RdmaTransport : public Transport {
 
     virtual Status uninstall();
 
+    Status quiesce() override;
+
     virtual Status allocateSubBatch(SubBatchRef& batch, size_t max_size);
 
     virtual Status freeSubBatch(SubBatchRef& batch);
@@ -122,6 +124,11 @@ class RdmaTransport : public Transport {
    public:
     Status setupLocalSegment();
 
+    // Update one RNIC's published address after a GID/LID change. The local
+    // descriptor is rolled back if registry synchronization fails.
+    Status refreshLocalDeviceDesc(const std::string& device_name, uint32_t lid,
+                                  const std::string& gid);
+
     std::shared_ptr<Config> config() const { return conf_; }
 
    private:
@@ -129,6 +136,16 @@ class RdmaTransport : public Transport {
     // came up. Remaining slots hold inert contexts.
     size_t initializeContexts();
 
+    // Free orphaned slices whose completion has been handled, or whose
+    // endpoint is gone. Driven by the monitor tick and, so a straggler is
+    // not held for a whole second, by freeSubBatch(). Two callers at once
+    // are fine: each takes the list whole, so they scan disjoint sets.
+    // uninstall()'s drain runs after the monitor is joined and takes the
+    // same mutex as a reap from a batch free. Only the monitor's call
+    // passes `on_tick`: it alone ages an orphan toward its warning, since
+    // batch frees come as fast as the caller likes.
+    void reapOrphanSlices(bool on_tick);
+
    private:
     bool installed_;
     std::shared_ptr<Config> conf_;
@@ -151,17 +168,66 @@ class RdmaTransport : public Transport {
     std::vector<Notification> notify_list_;
     std::condition_variable notify_cv_;
 
+    // Slices outliving the batch they belonged to because the completion
+    // queue can still name them. Owned here until that is no longer true.
+    // `passes` counts reap ticks survived: an orphan is only ever held while
+    // its endpoint is alive, so one that lingers means a queue pair is not
+    // being destroyed, and that is reported once per slice.
+    struct OrphanSlice {
+        RdmaSlice* slice;
+        uint32_t passes;
+    };
+    std::mutex orphan_slice_mutex_;
+    std::vector<OrphanSlice> orphan_slices_;
+    // Whether orphan_slices_ has anything in it, published under the mutex
+    // above. freeSubBatch() reads it on every batch free and would put every
+    // caller thread on that one mutex for what is almost always an empty
+    // list.
+    std::atomic<bool> orphans_pending_{false};
+    uint32_t orphan_warn_after_passes_{60};  // ~60 s at the 1 Hz tick
+    size_t orphan_warnings_{0};              // reaper-owned; test-visible
+
     // Map QP number to Endpoint for notification processing
     RWSpinlock notify_endpoint_map_lock_;
     std::unordered_map<uint32_t, std::weak_ptr<RdmaEndPoint>>
         notify_qp_to_endpoint_;
 
+    enum class NotifyCompletionAction {
+        SkipSilently,         // expected flush from a retiring or gone endpoint
+        ReportOnly,           // no live endpoint left to act on
+        DisableNotification,  // fault confined to the notify QP
+        RetireEndpoint,       // the peer or the path may be gone
+    };
+
+    // Decides what a failed notification completion costs. Only defined for
+    // error completions; endpoint_ready means the endpoint is still EP_READY
+    // and its notifications are still connected (a retiring or disabled
+    // notify QP only flushes from then on).
+    static NotifyCompletionAction classifyNotifyCompletion(ibv_wc_status status,
+                                                           bool endpoint_alive,
+                                                           bool endpoint_ready);
+
     // Register/unregister notification QP (called by Endpoint)
     void registerNotifyQp(uint32_t qp_num,
                           const std::shared_ptr<RdmaEndPoint>& endpoint);
     void unregisterNotifyQp(uint32_t qp_num);
+    // Returns nullptr when no ready endpoint to the peer's device could be
+    // handed out; `failure`, when given, receives why (the segment lookup or
+    // connect() status as is, DeviceNotFound for no enabled context,
+    // InternalError for an allocation failure).
     std::shared_ptr<RdmaEndPoint> getEndpoint(SegmentID target_id,
-                                              int device_id);
+                                              int device_id,
+                                              Status* failure = nullptr);
+
+    // Maps the reason getEndpoint() could not hand out a notify-capable
+    // endpoint to what sendNotification() reports. A bootstrap RPC that
+    // failed means the peer's control plane is unreachable, so the RPC
+    // fallback would only wait out a second timeout on the polling thread:
+    // report RpcServiceError, which TransferEngineImpl does not fall back
+    // on. Everything else (no context, allocation, QP setup) leaves the
+    // control plane reachable and stays DeviceNotFound, i.e. eligible for
+    // the RPC leg.
+    static Status notifyStatusForEndpointFailure(const Status& failure);
 
     // Notification worker thread
     void notifyWorkerThread();
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/slice.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/slice.h
index 17fa125fa9..4c410b81e1 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/slice.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/slice.h
@@ -41,6 +41,54 @@ struct RdmaSliceList {
     int num_slices = 0;
 };
 
+// `count` slices: the first count - 1 of `block_size` bytes and the last
+// holding what remains, which is a short tail folded in when one was worth
+// folding -- so up to `block_size` more than a block, never less than one
+// byte.
+struct RdmaSlicePlan {
+    uint64_t block_size = 0;
+    uint64_t count = 0;
+};
+
+// Cut `length` into at most `max_slices` slices, each a whole number of
+// `base_block` bytes. Rounding the block up covers the request in fewer
+// slices than were asked for, so the count comes from the block and not the
+// other way round: an empty slice would still cost a work request, a CQE, a
+// path selection and a completion.
+//
+// A last slice shorter than `merge_ratio` of a block is given to the slice
+// before it instead of being posted on its own, trading a fraction of a
+// block of extra work on that one slice for a work request, a CQE and a
+// completion. This has to happen after the block is chosen: asking for one
+// slice fewer up front only makes the block round up to the next whole one,
+// which leaves the short tail as its own slice anyway and spreads the
+// request over half as many slices. A ratio of 0 never folds.
+//
+// Zero length keeps one slice -- task accounting counts slices, and a task
+// with none never reaches a terminal status.
+inline RdmaSlicePlan planRdmaSlices(uint64_t length, uint64_t base_block,
+                                    uint64_t max_slices,
+                                    double merge_ratio = 0.25) {
+    if (base_block == 0) base_block = 1;
+    if (max_slices == 0) max_slices = 1;
+    if (length == 0) return {base_block, 1};
+
+    uint64_t count = (length + base_block - 1) / base_block;
+    if (count > max_slices) count = max_slices;
+
+    const uint64_t per_slice = (length + count - 1) / count;
+    const uint64_t block_size = (per_slice % base_block == 0)
+                                    ? per_slice
+                                    : (per_slice / base_block + 1) * base_block;
+
+    count = (length + block_size - 1) / block_size;
+    if (count > 1) {
+        const uint64_t tail = length - (count - 1) * block_size;
+        if (static_cast<double>(tail) < merge_ratio * block_size) --count;
+    }
+    return {block_size, count};
+}
+
 // Forward declarations
 class RdmaEndPoint;
 struct RdmaTask;
@@ -51,6 +99,10 @@ using RdmaTaskStorage = Slab<RdmaTask>;
 struct RdmaTask {
     int num_slices;
     Request request;
+    // Resolved by TransportSelector and copied from RdmaSubBatch. The
+    // per-slice path runs later on worker threads, so it must carry the same
+    // device policy as the aggregate allocation path.
+    uint64_t device_mask{~0ULL};
     // Named QP pool this task's slices should use (RFC #2568 step 3). Empty =
     // no pool selected: slices spray across all data QPs as before. Resolved
     // from SelectionResult.qp_pool at task creation.
@@ -101,17 +153,51 @@ struct RdmaSlice {
     const std::string* target_machine_id = nullptr;
 
     std::weak_ptr<RdmaEndPoint> ep_weak_ptr;
+    // Posted work requests whose completion has not been polled and fully
+    // handled yet; every work request is signalled, so each accepted post
+    // owes one. The status cannot stand in for this -- a timeout or a
+    // teardown resolves a slice while its work request is live. Above zero,
+    // the completion queue can still hand this address back, or a handler
+    // can still be reading the slice, so the storage must outlive the
+    // batch: see RdmaTransport::freeSubBatch() and Workers::handleCompletion().
+    std::atomic<int> completions_owed{0};
     TransferStatusEnum word = TransferStatusEnum::INITIAL;
     int qp_index = 0;
+    // Worker lane that enqueued this slice: the one whose inflight_slice_set
+    // holds it. Whichever lane later sweeps the slice off a queue pair must
+    // hand the set entry back to this one -- with qp_pools several lanes can
+    // share a queue pair, so the sweeper is often somebody else. -1 until
+    // Workers::submit() picks a lane. Atomic because a retry re-points it to
+    // the lane that re-queued the slice (Workers::submitFromTick) while the
+    // lane it is leaving may still hold a set entry it has not drained, and
+    // reads that entry to route the removal home.
+    std::atomic<int> owner_worker{-1};
+    // Worker lane whose inflight_slices counts this slice, -1 while none
+    // does. Each accounting the slice carries names the counter it sits in,
+    // so whichever path takes it out -- its own completion, another lane's
+    // sweep of the queue pair they share, the timeout pass that finds it
+    // already terminal -- exchanges the field for -1 and pays back exactly
+    // what it read; a second path reads -1 and does nothing. Usually the
+    // owner lane, but a retry moves the count in one exchange
+    // (Workers::submitFromTick) while the old set entry drains later.
+    std::atomic<int> counted_lane{-1};
     int retry_count = 0;
     // Flat (source,target) combination index last tried by
     // selectFallbackDevice; the next fallback resumes just past it so retries
     // rotate through all combinations with wraparound instead of hammering one.
     int last_fallback_idx = -1;
     bool failed = false;
-    // True while DeviceSelector accounts this slice against source_dev_id.
-    // The worker clears it exactly once on completion, failure, or cancel.
-    bool quota_charged = false;
+    // Device DeviceSelector accounts this slice against, -1 while none.
+    // Same discipline as counted_lane: whoever releases the charge --
+    // completion, failure, timeout or cancel -- exchanges it for -1 and
+    // pays that device, so a fallback that has already rewritten
+    // source_dev_id cannot misdirect the release. Atomic because on a pooled
+    // QP the timeout sweep and the CQ poller run on different workers.
+    std::atomic<int> charged_dev{-1};
+    // Device whose posted backlog counts this slice: set when the work
+    // request reaches the hardware, -1 again once the slice leaves the queue
+    // pair. A charged slice waiting in a worker queue is not posted.
+    std::atomic<int> posted_dev{-1};
     uint64_t enqueue_ts = 0;
     uint64_t submit_ts = 0;
     // Non-owning pointer to the per-worker RailMonitor for this slice's
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/rdma/workers.h b/mooncake-transfer-engine/tent/include/tent/transport/rdma/workers.h
index e9578d0843..860b9aaafb 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/rdma/workers.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/rdma/workers.h
@@ -37,6 +37,19 @@ namespace tent {
 class RdmaTransport;
 class DeviceSelector;
 
+// IBV_EVENT_DEVICE_SPEED_CHANGE: a port speed changed without a link flap
+// (a VF over LAG losing a PF, say). Newer rdma-core names it; the async
+// event ABI is append-only, so an older header means only that the
+// enumerator is missing, never that the kernel cannot raise the event.
+// Naming it here keeps the branch that handles it -- and its test --
+// compiled everywhere, so an old userspace on a new kernel still reacts.
+inline constexpr int kIbvEventDeviceSpeedChange = 20;  // after WQ_FATAL (19)
+#ifdef HAVE_IBV_EVENT_DEVICE_SPEED_CHANGE
+// A build against a header that names it pins the value above.
+static_assert(kIbvEventDeviceSpeedChange == IBV_EVENT_DEVICE_SPEED_CHANGE,
+              "verbs async-event values are append-only; update the fallback");
+#endif
+
 class Workers {
     friend class RdmaTransportTestPeer;
 
@@ -53,6 +66,12 @@ class Workers {
 
     Status stop();
 
+    // Stop accepting new submits and wait until every worker's inflight
+    // count hits 0. Workers keep polling CQ so in-flight GPUDirect writes
+    // can complete. timeout_ns bounds the wait so teardown cannot hang.
+    static constexpr uint64_t kDefaultQuiesceTimeoutNs = 10000000000ull;
+    Status quiesce(uint64_t timeout_ns = kDefaultQuiesceTimeoutNs);
+
     Status submit(RdmaSlice* slice);
 
     Status submit(RdmaSliceList& slice_list, int worker_id = -1);
@@ -71,9 +90,101 @@ class Workers {
 
     void asyncPollCq();
 
-    bool cancelUnpostedSlice(WorkerContext& worker, RdmaSlice* slice);
-
-    void releaseSliceQuota(RdmaSlice* slice, double latency = 0.0);
+    // Resolve one completion: give back what the slice's lane accounts for,
+    // feed the transmit meter, and either finish, retry or fail it. Split
+    // from asyncPollCq so a test can drive it with a synthesized ibv_wc.
+    // `last_in_pass` is true for the final work completion of a poll pass:
+    // the meter is only offered a sample there, so an interval never ends
+    // partway through a group of completions that share one timestamp.
+    void handleCompletion(WorkerContext& worker, RdmaContext& context,
+                          const ibv_wc& wc, uint64_t poll_ts,
+                          bool last_in_pass = true);
+
+    // The lane whose inflight_slice_set holds `slice`'s entry, or nullptr
+    // when it cannot be resolved (no lane recorded, or the worker array is
+    // not up yet).
+    WorkerContext* ownerContext(const RdmaSlice* slice);
+
+    // Index of `worker` in the lane array, or -1 when that array is not up
+    // yet: the inverse of ownerContext().
+    int laneIndex(const WorkerContext& worker) const;
+
+    // Give back everything a slice swept off a queue pair with a terminal
+    // status still holds: its selector charge, its place in whichever
+    // lane's inflight count has it, and its entry in whichever lane's set.
+    // Unless `bytes_moved` (the sweep finished it with COMPLETED and its own
+    // completion will credit the bytes), a posted slice also ends a stretch
+    // of busy time with nothing to show for it, so the transmit meter
+    // starts over. `deferred`, when given, collects the entries `self` is
+    // to erase, so the caller can do it after it stops iterating that set.
+    void retireSweptSlice(WorkerContext& self, RdmaSlice* slice,
+                          uint64_t now_ns, std::vector<RdmaSlice*>* deferred,
+                          bool bytes_moved = false);
+
+    // Take `slice` out of whichever lane's inflight count holds it, exactly
+    // once (`counted_lane` comes back -1 for everyone after): for a slice
+    // popped off a queue pair that is still in flight, for one dropped
+    // before it was posted, and for one finished by any path that leaves
+    // the count to be settled here. A re-submit needs no prior discount;
+    // submitFromTick moves the count itself.
+    void discountFromOwner(WorkerContext& self, RdmaSlice* slice);
+
+    // Decide who takes `slice` out of an inflight set. Returns true when the
+    // entry is `self`'s to erase -- because `self` holds it, or because
+    // nobody else does -- and false when it has been handed to the owning
+    // lane's reclaim list instead.
+    bool routeSetRemoval(WorkerContext& self, RdmaSlice* slice);
+
+    // Take out the slices other lanes swept on this lane's behalf.
+    void drainReclaimed(WorkerContext& worker);
+
+    // This lane's pass over its inflight set: take out what other lanes
+    // handed back, retire entries that turned terminal behind its back, and
+    // fail every slice that has waited longer than slice_timeout_ns_ since
+    // it was enqueued (software timeout). Split from asyncPollCq so it can
+    // be driven with a synthetic clock in tests.
+    void expireTimedOutSlices(WorkerContext& worker, uint64_t now_ns);
+
+    // Reorder `slices` (all contending for one NIC path) most-urgent-first
+    // by predicted MLU, RFC #2792. Split from asyncPostSend so a test can
+    // drive it with a live DeviceSelector and no endpoint.
+    void orderByDeadline(std::vector<RdmaSlice*>& slices, int dev_id,
+                         uint64_t now_ns);
+
+    // Charge `slice` to `dev_id`, moving or establishing the selector's
+    // accounting for it. Called when a retry or a fallback settles on a
+    // device: a retry's charge was returned by the failure path that
+    // re-submitted it, a fallback's still sits on the NIC the allocator
+    // picked. A device the selector does not know cannot be charged; the
+    // slice then keeps whatever charge it has, so the release still balances.
+    void rechargeSlice(RdmaSlice* slice, int dev_id);
+
+    // True when `slice` must not be posted -- the transfer was cancelled, or
+    // another lane resolved the slice while it waited for a re-post. Retires
+    // it like a sweep would (retireSweptSlice), so the caller can simply
+    // skip it.
+    bool dropUnpostableSlice(WorkerContext& worker, RdmaSlice* slice);
+
+    // Hand back everything the selector accounts for this slice: its
+    // allocation charge and, if it reached the hardware, its share of the
+    // NIC's posted backlog. `now_ns` closes the NIC's busy stretch when
+    // that share was the last of it, so it must come from the same clock as
+    // the timestamps the slice was posted with. `latency` is a successful
+    // attempt's post->completion time in seconds; 0 = no sample. See
+    // DeviceSelector::release.
+    void releaseSliceQuota(RdmaSlice* slice, uint64_t now_ns,
+                           double latency = 0.0);
+
+    // Record that `slice` has reached its source device's hardware. Its
+    // submit_ts opens the device's busy stretch when nothing else was
+    // posted to it.
+    void notePostedSlice(RdmaSlice* slice);
+
+    // What a posting lane writes for a slice the moment it goes on the
+    // wire: the post timestamp, the device's posted backlog and the lane's
+    // set entry. Runs inside submitSlices, before ibv_post_send, so a
+    // completion polled on a shared queue pair finds all three in place.
+    void markPosted(WorkerContext& worker, RdmaSlice* slice, uint64_t post_ts);
 
     void monitorThread();
 
@@ -82,7 +193,42 @@ class Workers {
     // failure load.
     void reclaimEndpoints();
 
-    int handleContextEvents(std::shared_ptr<RdmaContext>& context);
+    // dev_id is the NicID (context_set_ index), which is also the
+    // DeviceSelector id, so port events can flip that device's availability.
+    // Drains the whole async event queue: the async fd is edge-triggered and
+    // ibv_get_async_event() dequeues one record per call, so an event left
+    // behind waits for an unrelated later event to release it.
+    int handleContextEvents(int dev_id, std::shared_ptr<RdmaContext>& context);
+
+    // The decision half of handleContextEvents, kept apart from
+    // ibv_get_async_event/ibv_ack_async_event so a synthesized event can
+    // drive it in tests. Port events (PORT_ERR/PORT_ACTIVE) name their port;
+    // a device's async fd delivers them for every port of the device, and a
+    // context opens exactly one, so events for another port are ignored.
+    void applyContextEvent(int dev_id, RdmaContext& context,
+                           const ibv_async_event& event);
+
+    // Re-query and publish one context's GID/LID.
+    RdmaAddressRefreshResult refreshAddress(RdmaContext& context);
+
+    // Everything a recovered port needs: refresh its address, resume the
+    // context, re-seed its bandwidth and make it selectable again. Shared by
+    // the IBV_EVENT_PORT_ACTIVE path and by resumePausedContexts(). Returns
+    // false when the address cannot be refreshed, keeping the context paused.
+    bool activateContext(int dev_id, RdmaContext& context);
+
+    // Re-read the link speed after a port event and re-seed the selector if
+    // it changed; a link that returns at the same speed keeps what it
+    // learned.
+    void refreshLinkSpeed(int dev_id, RdmaContext& context);
+
+    // 1 Hz heartbeat from monitorThread(): safety net for a lost
+    // IBV_EVENT_PORT_ACTIVE. Nothing else ever leaves DEVICE_PAUSED, so a
+    // context whose recovery event was dropped (edge-triggered fd, event
+    // queue overflow, ...) would fail every transfer on that NIC forever.
+    // Polls the port state of paused contexts and activates the ones the
+    // hardware reports as up.
+    void resumePausedContexts();
 
     Status generatePostPath(RdmaSlice* slice);
 
@@ -109,6 +255,8 @@ class Workers {
 
     int getDeviceByFlatIndex(const RouteHint& hint, size_t flat_idx);
 
+    bool strictLocalNuma() const;
+
     // True if the (sdev -> tdev) NIC pair is known-unable to GPUDirect-DMA to
     // the source/target GPU (learned from prior completion errors). Used to
     // steer selection away from dead rails before posting.
@@ -125,6 +273,7 @@ class Workers {
     std::thread monitor_;
 
     std::atomic<bool> running_;
+    std::atomic<bool> accepting_submits_{true};
 
     struct PostPath {
         int local_device_id;
@@ -209,7 +358,13 @@ class Workers {
         std::thread thread;
         BoundedSliceQueue queues[kNumPriorityLevels];  // Priority queues
         GroupedRequests requests;
+        // Only this lane may touch its own set, so slices swept by another
+        // lane are handed over here and erased on this lane's next pass.
+        // Empty unless queue pairs are shared (qp_pools), so the mutex is
+        // cold.
         std::unordered_set<RdmaSlice*> inflight_slice_set;
+        std::mutex reclaim_mutex;
+        std::vector<RdmaSlice*> reclaimed;
         std::atomic<int64_t> inflight_slices = 0;
 
         std::mutex mutex;
@@ -219,6 +374,14 @@ class Workers {
         // Next time to check for priority promotions (nanoseconds)
         uint64_t next_promotion_check_ns = 0;
 
+        // Tick-internal re-enqueues that found their target queue full
+        // (target priority, entry). Parked items stay counted in
+        // inflight_slices, which both keeps the accounting continuous and
+        // keeps the worker from suspending while they are pending. The
+        // asyncPostSend drain consumes this list before the shared queues,
+        // so parked entries can never starve behind contending producers.
+        std::vector<std::pair<int, RdmaSliceList>> requeue_overflow;
+
         // Values are held via unique_ptr so that map rehashing does not
         // invalidate pointers into RailMonitor stored on in-flight slices
         // (see RdmaSlice::rail_monitor).
@@ -230,13 +393,18 @@ class Workers {
     // Promote timed-out low priority requests to higher priority queues
     void promoteTimedOutRequests(WorkerContext& worker);
 
+    // Tick-internal re-enqueue: the worker thread must never block on its own
+    // queue (issue #3637), so these park into requeue_overflow on a full queue
+    // and the asyncPostSend drain consumes them first. Moves the slice's
+    // inflight count to `worker` from whichever lane still holds it.
+    void submitFromTick(WorkerContext& worker, RdmaSlice* slice);
+
     WorkerContext* worker_context_;
     uint64_t slice_timeout_ns_;
     uint64_t priority_promotion_timeout_ns_;  // Timeout for priority promotion
     // Opt-in (issue #2528): when true, a promotion pass promotes exactly the
-    // entries that have themselves timed out, instead of promoting the whole
-    // queue whenever only the head has timed out. Default false keeps the
-    // historical "flush the tier" behavior.
+    // entries that have themselves timed out (DecidePromotionPerEntry).
+    // Default false keeps DecidePromotionHeadOnly ("flush the tier").
     bool priority_promotion_per_entry_ = false;
 
     std::unique_ptr<DeviceSelector> device_selector_;
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/tcp/tcp_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/tcp/tcp_transport.h
index 3d5f2ebedd..1f0fc77d9a 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/tcp/tcp_transport.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/tcp/tcp_transport.h
@@ -15,10 +15,13 @@
 #ifndef TCP_TRANSPORT_H_
 #define TCP_TRANSPORT_H_
 
+#include <algorithm>
 #include <atomic>
+#include <cstdint>
 #include <functional>
 #include <iostream>
 #include <memory>
+#include <mutex>
 #include <queue>
 #include <string>
 
@@ -36,12 +39,21 @@ struct TcpParams {
     size_t max_concurrent_tasks = 16;     // worker thread pool size
 };
 
+// Next sleep used by doTransferWithRetry after a failed attempt. Kept as a
+// pure function so the cap is unit-testable without standing up a peer.
+inline uint64_t nextTcpRetryDelay(uint64_t delay_ms, uint64_t cap) {
+    return std::min(delay_ms * 2, cap);
+}
+
+class TcpTransportTestPeer;
+
 struct TcpTask {
     Request request;
     BatchID progress_batch_id{0};
     std::function<void(BatchID)> notify_progress;
     std::atomic<TransferStatusEnum> status_word{TransferStatusEnum::PENDING};
     std::atomic<size_t> transferred_bytes{0};
+    bool non_replayable_failure{false};  // Published by status_word.
     uint64_t target_addr = 0;
 
     TcpTask() = default;
@@ -52,6 +64,7 @@ struct TcpTask {
           status_word(other.status_word.load(std::memory_order_relaxed)),
           transferred_bytes(
               other.transferred_bytes.load(std::memory_order_relaxed)),
+          non_replayable_failure(other.non_replayable_failure),
           target_addr(other.target_addr) {}
     TcpTask(const TcpTask &) = delete;
     TcpTask &operator=(const TcpTask &) = delete;
@@ -64,6 +77,8 @@ struct TcpSubBatch : public Transport::SubBatch {
 };
 
 class TcpTransport : public Transport {
+    friend class TcpTransportTestPeer;
+
    public:
     TcpTransport();
 
@@ -76,6 +91,8 @@ class TcpTransport : public Transport {
 
     virtual Status uninstall();
 
+    virtual Status quiesce() override;
+
     virtual Status allocateSubBatch(SubBatchRef &batch, size_t max_size);
 
     virtual Status freeSubBatch(SubBatchRef &batch);
@@ -114,6 +131,7 @@ class TcpTransport : public Transport {
     std::shared_ptr<Topology> local_topology_;
     std::shared_ptr<ControlService> metadata_;
     TcpParams params_;
+    std::mutex lifecycle_mutex_;
     std::unique_ptr<ThreadPool> thread_pool_;
     std::atomic<bool> shutting_down_{false};
 
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ub/endpoint_store.h b/mooncake-transfer-engine/tent/include/tent/transport/ub/endpoint_store.h
index 12b0dc9a6d..cebc879dda 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/ub/endpoint_store.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ub/endpoint_store.h
@@ -4,8 +4,10 @@
 #ifndef TENT_TRANSPORT_UB_ENDPOINT_STORE_H_
 #define TENT_TRANSPORT_UB_ENDPOINT_STORE_H_
 
+#include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <functional>
 #include <memory>
 #include <mutex>
 #include <unordered_map>
@@ -23,8 +25,14 @@ namespace mooncake::tent::ub {
 // generation and can never resurrect a failed Jetty set.
 class EndpointStore final {
    public:
+    // Time source for the quarantine-sweep throttle. Production leaves this
+    // empty and uses steady_clock; tests inject a controllable clock so the
+    // throttle is not sensitive to scheduler stalls.
+    using SteadyClock = std::function<std::chrono::steady_clock::time_point()>;
+
     EndpointStore(std::shared_ptr<UrmaAdapter> adapter, size_t max_size,
-                  uint32_t jetty_count, JettyOptions jetty_options = {});
+                  uint32_t jetty_count, JettyOptions jetty_options = {},
+                  SteadyClock clock = {});
     ~EndpointStore();
 
     EndpointStore(const EndpointStore&) = delete;
@@ -60,6 +68,7 @@ class EndpointStore final {
     const size_t max_size_;
     const uint32_t jetty_count_;
     const JettyOptions jetty_options_;
+    const SteadyClock clock_;
     mutable std::mutex mutex_;
     std::unordered_map<UbEndpointKey, Entry, UbEndpointKeyHash> endpoints_;
     // Unpublished endpoints whose native cleanup failed remain owned until a
@@ -67,6 +76,9 @@ class EndpointStore final {
     // while an ERROR Jetty still lacks its flush fence.
     std::vector<std::shared_ptr<UbEndpoint>> quarantined_;
     uint64_t next_insertion_order_{1};
+    // Earliest time the next quarantine sweep may run. Default initialized so
+    // the first sweep is always allowed.
+    std::chrono::steady_clock::time_point next_quarantine_sweep_{};
 };
 
 using UbEndpointStore = EndpointStore;
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ub/params.h b/mooncake-transfer-engine/tent/include/tent/transport/ub/params.h
index 175dc8739c..d34074f7ed 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/ub/params.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ub/params.h
@@ -40,6 +40,7 @@ struct UbParams {
     uint32_t jetty_per_endpoint = 6;
     uint32_t max_endpoints = 65536;
     size_t slice_size = 64 * 1024;
+    size_t max_slices_per_task = 64 * 1024;
     uint32_t max_retries = 8;
     uint32_t slice_timeout_ms = 5000;
     uint32_t endpoint_cooldown_ms = 1000;
@@ -78,6 +79,15 @@ struct UbParams {
         }
         parsed.slice_size = static_cast<size_t>(slice_size);
 
+        uint64_t max_slices_per_task = parsed.max_slices_per_task;
+        CHECK_STATUS(readPositive(config, "transports/ub/max_slices_per_task",
+                                  max_slices_per_task, max_slices_per_task));
+        if (max_slices_per_task > std::numeric_limits<size_t>::max()) {
+            return Status::InvalidArgument(
+                "transports/ub/max_slices_per_task exceeds size_t");
+        }
+        parsed.max_slices_per_task = static_cast<size_t>(max_slices_per_task);
+
         CHECK_STATUS(readNonNegative(config, "transports/ub/max_retries",
                                      parsed.max_retries, parsed.max_retries));
         CHECK_STATUS(readPositive(config, "transports/ub/slice_timeout_ms",
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ub/rail_monitor.h b/mooncake-transfer-engine/tent/include/tent/transport/ub/rail_monitor.h
index 1dbf0fd6bf..4efb183a7b 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/ub/rail_monitor.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ub/rail_monitor.h
@@ -113,10 +113,21 @@ class RailMonitor {
     void recordError(const UbPostPath& path, uint64_t now_ns = 0);
     void recordTimeout(const UbPostPath& path, uint64_t now_ns = 0);
     // Records at most one rebuild for each endpoint generation on a physical
-    // rail. Returns true when telemetry advanced, allowing EndpointStore to
-    // call this safely from converging/retried rebuild paths.
+    // rail. The first generation observed on a rail establishes the baseline
+    // and is not itself a rebuild, so a freshly bootstrapped endpoint does not
+    // look like a recovery. Returns true when telemetry advanced, allowing
+    // EndpointStore to call this safely from converging/retried rebuild paths.
     bool recordEndpointRebuild(const UbPostPath& path, uint64_t now_ns = 0);
 
+    // Non-inserting counterpart of stats(): an unknown rail is reported with
+    // defaults and is NOT added to the map. Path-selection probes use this so
+    // ranking every local x remote combination cannot grow the rail map or seed
+    // generations for rails that are never posted to. Like stats(), it still
+    // advances the time watermark and cooldown state of a rail that does exist.
+    [[nodiscard]] RailStats statsIfPresent(const UbPostPath& path,
+                                           uint64_t now_ns = 0);
+    // Creates the rail on demand, so the returned stats always reflect a real
+    // entry.
     [[nodiscard]] RailStats stats(const UbPostPath& path, uint64_t now_ns = 0);
     [[nodiscard]] std::vector<RailStats> allStats(uint64_t now_ns = 0);
 
@@ -139,6 +150,11 @@ class RailMonitor {
         // watermark from latest_endpoint_generation because path registration
         // may observe the replacement before rebuild telemetry is emitted.
         uint64_t recorded_rebuild_generation{0};
+        // False until the first ready generation seeds
+        // recorded_rebuild_generation. The initial build on a rail is not a
+        // rebuild, so it must not be counted even though the watermark starts
+        // at zero.
+        bool has_rebuild_baseline{false};
     };
 
     using RailMap = std::unordered_map<UbRailKey, RailState, UbRailKeyHash>;
@@ -146,6 +162,8 @@ class RailMonitor {
     static uint64_t normalizedNow(uint64_t now_ns);
     static uint64_t deadlineAfter(uint64_t now_ns, uint64_t duration_ns);
     static uint64_t observeTimeLocked(RailState& state, uint64_t event_ns);
+    // Refreshes time-dependent rail state and returns a consistent snapshot.
+    RailStats snapshotLocked(RailState& state, uint64_t now_ns);
     RailState& getOrCreateLocked(const UbPostPath& path);
     static void insertErrorLocked(RailState& state, uint64_t event_ns);
     void pruneErrorsLocked(RailState& state, uint64_t now_ns);
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/ub/workers.h b/mooncake-transfer-engine/tent/include/tent/transport/ub/workers.h
index 3b5015fec6..a2e9031fe8 100644
--- a/mooncake-transfer-engine/tent/include/tent/transport/ub/workers.h
+++ b/mooncake-transfer-engine/tent/include/tent/transport/ub/workers.h
@@ -93,6 +93,40 @@ struct UbPathSelectionScore {
     return lhs.remote_device_id < rhs.remote_device_id;
 }
 
+// Orders pre-scored rails for lazy endpoint resolution. `local_topology_ids`
+// holds each rail's local device in pre-score order, and the returned values
+// are indices into it.
+//
+// Pass one takes the highest-scoring rail of every local device, so the
+// candidates that actually get resolved span devices instead of piling onto
+// whichever device ranks best. Pass two appends the remaining rails, so a
+// caller that still needs candidates - a single-device topology, or a rail that
+// failed to resolve - can fill its floor without attempting a rail twice.
+[[nodiscard]] inline std::vector<size_t> ubResolutionAttemptOrder(
+    const std::vector<Topology::NicID>& local_topology_ids) {
+    const size_t count = local_topology_ids.size();
+    std::vector<bool> taken(count, false);
+    std::vector<size_t> order;
+    order.reserve(count);
+    for (size_t index = 0; index < count; ++index) {
+        const auto id = local_topology_ids[index];
+        bool known_device = false;
+        for (size_t earlier : order) {
+            if (local_topology_ids[earlier] == id) {
+                known_device = true;
+                break;
+            }
+        }
+        if (known_device) continue;
+        order.push_back(index);
+        taken[index] = true;
+    }
+    for (size_t index = 0; index < count; ++index) {
+        if (!taken[index]) order.push_back(index);
+    }
+    return order;
+}
+
 // Native UB scheduler. Posting lanes own request selection and URMA post;
 // poller lanes own completion dispatch. A monotonic numeric token, never a raw
 // UbSlice pointer, crosses the adapter boundary.
diff --git a/mooncake-transfer-engine/tent/include/tent/transport/xpu/xpu_transport.h b/mooncake-transfer-engine/tent/include/tent/transport/xpu/xpu_transport.h
new file mode 100644
index 0000000000..bba571370a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/include/tent/transport/xpu/xpu_transport.h
@@ -0,0 +1,120 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef TENT_XPU_TRANSPORT_H_
+#define TENT_XPU_TRANSPORT_H_
+
+#include <atomic>
+#include <string>
+#include <vector>
+
+#include "tent/platform/xpu.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/transport.h"
+
+namespace mooncake {
+namespace tent {
+
+struct XpuTask {
+    Request request;
+    // Atomic so the polling getTransferStatus() reads a consistent, visible
+    // value for the completion written by startTransfer()/notifyProgress().
+    std::atomic<TransferStatusEnum> status_word{TransferStatusEnum::PENDING};
+    std::atomic<size_t> transferred_bytes{0};
+
+    XpuTask() = default;
+    // std::atomic is neither copyable nor movable, but XpuTask instances live
+    // in a std::vector, whose element type must be move-insertable. These
+    // special members transfer the atomic *values*; they run only during
+    // single-threaded sub-batch construction, never concurrently with polling.
+    XpuTask(const XpuTask &other)
+        : request(other.request),
+          status_word(other.status_word.load()),
+          transferred_bytes(other.transferred_bytes.load()) {}
+    XpuTask &operator=(const XpuTask &other) {
+        request = other.request;
+        status_word.store(other.status_word.load());
+        transferred_bytes.store(other.transferred_bytes.load());
+        return *this;
+    }
+};
+
+struct XpuSubBatch : public Transport::SubBatch {
+    std::vector<XpuTask> task_list;
+    size_t max_size;
+    size_t size() const override { return task_list.size(); }
+};
+
+// XpuTransport is the Intel-XPU vendor transport, the oneAPI/SYCL analog of
+// NVLinkTransport. For the correctness-first MVP (PR2) it implements only the
+// local VRAM<->host-DRAM staging hop: it advertises the device<->host
+// capabilities (gpu_to_dram / dram_to_gpu) and runs the copy through the active
+// XpuPlatform for LOCAL_SEGMENT_ID requests, while the host<->host hop is
+// carried by RDMA/TCP and ProxyManager chains the two stages (see
+// findStagingPolicy). gpu_to_gpu is left false so the engine always stages
+// cross-node traffic through host DRAM; direct VRAM RDMA (dma-buf) and PCIe
+// peer-to-peer arrive later, exactly as NVLinkTransport already exposes them
+// for CUDA.
+//
+// Like NVLinkTransport binds to CudaPlatform, this transport binds to the
+// concrete XpuPlatform in install() and drives every device operation -- USM
+// pointer classification and the VRAM<->host copy -- through it. The active
+// XpuPlatform resolves both base and interior USM pointers via its backend
+// registry, and the SYCL dependency stays confined to platform_xpu.
+class XpuTransport : public Transport {
+   public:
+    XpuTransport();
+
+    ~XpuTransport();
+
+    Status install(std::string &local_segment_name,
+                   std::shared_ptr<ControlService> metadata,
+                   std::shared_ptr<Topology> local_topology,
+                   std::shared_ptr<Config> conf = nullptr) override;
+
+    Status uninstall() override;
+
+    Status allocateSubBatch(SubBatchRef &batch, size_t max_size) override;
+
+    Status freeSubBatch(SubBatchRef &batch) override;
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request> &request_list) override;
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus &status) override;
+
+    Status addMemoryBuffer(BufferDesc &desc,
+                           const MemoryOptions &options) override;
+
+    Status removeMemoryBuffer(BufferDesc &desc) override;
+
+    const char *getName() const override { return "xpu"; }
+
+   private:
+    void startTransfer(XpuTask *task, XpuSubBatch *batch);
+
+   private:
+    bool installed_;
+    std::string local_segment_name_;
+    std::shared_ptr<Topology> local_topology_;
+    std::shared_ptr<ControlService> metadata_;
+    std::shared_ptr<Config> conf_;
+    XpuPlatform *platform_;
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_XPU_TRANSPORT_H_
diff --git a/mooncake-transfer-engine/tent/plugins/cuda/CMakeLists.txt b/mooncake-transfer-engine/tent/plugins/cuda/CMakeLists.txt
index 467a4daec5..80dbc907ca 100644
--- a/mooncake-transfer-engine/tent/plugins/cuda/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/plugins/cuda/CMakeLists.txt
@@ -14,7 +14,7 @@ set(TENT_CUDA_PLUGIN_SOURCES
 add_library(tent_cuda_plugin SHARED ${TENT_CUDA_PLUGIN_SOURCES})
 
 target_link_libraries(tent_cuda_plugin
-    PRIVATE CUDA::cudart tent_plugin
+    PRIVATE CUDA::cudart CUDA::cuda_driver tent_plugin
 )
 
 set_target_properties(tent_cuda_plugin PROPERTIES
diff --git a/mooncake-transfer-engine/tent/plugins/cuda/cuda_plugin.cpp b/mooncake-transfer-engine/tent/plugins/cuda/cuda_plugin.cpp
index 5cc7237389..160410158b 100644
--- a/mooncake-transfer-engine/tent/plugins/cuda/cuda_plugin.cpp
+++ b/mooncake-transfer-engine/tent/plugins/cuda/cuda_plugin.cpp
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "tent/device_plugin.h"
+#include "tent/platform/cuda_utils.h"
 
 #include <cuda_runtime.h>
 #include <string.h>
@@ -20,6 +21,8 @@
 #include <string>
 #include <glog/logging.h>
 
+using mooncake::tent::getCudaDeviceForPtr;
+
 struct cuda_plugin_ctx_t {
     // reserved
 };
@@ -86,17 +89,18 @@ static int cuda_alloc(void* ctx_, void** pptr, size_t size, const char* loc) {
 static int cuda_free(void* ctx_, void* ptr, size_t size) {
     (void)ctx_;
     (void)size;
-    cudaPointerAttributes attrs;
-    CHECK_CUDA(cudaPointerGetAttributes(&attrs, ptr));
-    if (attrs.type == cudaMemoryTypeDevice) {
-        CHECK_CUDA(cudaFree(ptr));
-        return 0;
-    }
-    return -2;
+    if (getCudaDeviceForPtr(ptr) < 0) return -2;
+    CHECK_CUDA(cudaFree(ptr));
+    return 0;
 }
 
 static int cuda_memcpy_sync(void* ctx_, void* dst, void* src, size_t length) {
     (void)ctx_;
+    // Pin the owning device so the runtime does not default to GPU 0.
+    int dev = getCudaDeviceForPtr(src);
+    if (dev < 0) dev = getCudaDeviceForPtr(dst);
+    if (dev < 0) return -1;  // host-to-host; let the caller fall back
+    CHECK_CUDA(cudaSetDevice(dev));
     CHECK_CUDA(cudaMemcpy(dst, src, length, cudaMemcpyDefault));
     return 0;
 }
@@ -105,12 +109,11 @@ static int cuda_query_location(void* ctx_, void* addr, size_t size,
                                location_t* buf, size_t buf_count) {
     (void)ctx_;
     if (buf_count == 0) return -1;
-    cudaPointerAttributes attr{};
-    cudaError_t err = cudaPointerGetAttributes(&attr, addr);
-    if (err != cudaSuccess || attr.type != cudaMemoryTypeDevice) return 0;
+    int dev = getCudaDeviceForPtr(addr);
+    if (dev < 0) return 0;
     buf[0].start = addr;
     buf[0].length = size;
-    snprintf(buf[0].location, LOCATION_LEN, "cuda:%d", attr.device);
+    snprintf(buf[0].location, LOCATION_LEN, "cuda:%d", dev);
     return 1;
 }
 
diff --git a/mooncake-transfer-engine/tent/plugins/rocm/rocm_plugin.cpp b/mooncake-transfer-engine/tent/plugins/rocm/rocm_plugin.cpp
index 63d264901a..5fee72dfa5 100644
--- a/mooncake-transfer-engine/tent/plugins/rocm/rocm_plugin.cpp
+++ b/mooncake-transfer-engine/tent/plugins/rocm/rocm_plugin.cpp
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "tent/device_plugin.h"
+#include "tent/runtime/amd_location.h"
 
 #include <hip/hip_runtime.h>
 #include <string.h>
@@ -20,6 +21,9 @@
 #include <string>
 #include <glog/logging.h>
 
+using mooncake::tent::isAmdGpuLocationType;
+using mooncake::tent::kAmdGpuLocationType;
+
 struct rocm_plugin_ctx_t {
     // reserved
 };
@@ -73,7 +77,7 @@ static int rocm_destroy_plugin(void* handle) {
 static int rocm_alloc(void* ctx_, void** pptr, size_t size, const char* loc) {
     (void)ctx_;
     LocationParser location(loc);
-    if (location.type() != "rocm") return -1;
+    if (!isAmdGpuLocationType(location.type())) return -1;
     int hip_dev = 0;
     CHECK_HIP(hipGetDevice(&hip_dev));
     CHECK_HIP(hipSetDevice(location.index()));
@@ -109,7 +113,8 @@ static int rocm_query_location(void* ctx_, void* addr, size_t size,
     if (err != hipSuccess || attr.type != hipMemoryTypeDevice) return 0;
     buf[0].start = addr;
     buf[0].length = size;
-    snprintf(buf[0].location, LOCATION_LEN, "rocm:%d", attr.device);
+    snprintf(buf[0].location, LOCATION_LEN, "%s:%d", kAmdGpuLocationType,
+             attr.device);
     return 1;
 }
 
@@ -133,7 +138,7 @@ static int rocm_get_device_pci_bus_id(void* ctx_, int device_index,
 extern "C" int tent_register_device_plugin(device_plugin_t* out) {
     if (!out) return -1;
     memset(out, 0, sizeof(*out));
-    out->class_name = "rocm";
+    out->class_name = kAmdGpuLocationType;
     out->create_plugin = rocm_create_plugin;
     out->destroy_plugin = rocm_destroy_plugin;
     out->alloc = rocm_alloc;
diff --git a/mooncake-transfer-engine/tent/src/CMakeLists.txt b/mooncake-transfer-engine/tent/src/CMakeLists.txt
index 6fe7ff3559..1a2368476e 100644
--- a/mooncake-transfer-engine/tent/src/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/CMakeLists.txt
@@ -61,19 +61,40 @@ if(IBVERBS_LIB AND IBVERBS_INCLUDE)
   target_compile_definitions(tent_interface INTERFACE USE_RDMA)
   target_include_directories(tent_interface INTERFACE ${IBVERBS_INCLUDE})
   target_link_libraries(tent_interface INTERFACE ${IBVERBS_LIB})
+  # ibv_port_attr::active_speed is a uint8_t and reads 0 for XDR (encoding 256);
+  # newer rdma-core adds active_speed_ex to carry it.
+  include(CheckStructHasMember)
+  set(CMAKE_REQUIRED_INCLUDES ${IBVERBS_INCLUDE})
+  check_struct_has_member(
+    "struct ibv_port_attr" active_speed_ex infiniband/verbs.h
+    HAVE_IBV_ACTIVE_SPEED_EX LANGUAGE CXX)
+  unset(CMAKE_REQUIRED_INCLUDES)
+  if(HAVE_IBV_ACTIVE_SPEED_EX)
+    target_compile_definitions(tent_interface
+                               INTERFACE HAVE_IBV_ACTIVE_SPEED_EX)
+  endif()
+  # IBV_EVENT_DEVICE_SPEED_CHANGE (rdma-core >= 62) reports a port speed change
+  # without a link flap. It is an enumerator, so probe by compiling.
+  include(CheckCXXSourceCompiles)
+  set(CMAKE_REQUIRED_INCLUDES ${IBVERBS_INCLUDE})
+  check_cxx_source_compiles(
+    "#include <infiniband/verbs.h>
+     int main() { return IBV_EVENT_DEVICE_SPEED_CHANGE == IBV_EVENT_PORT_ACTIVE; }"
+    HAVE_IBV_EVENT_DEVICE_SPEED_CHANGE)
+  unset(CMAKE_REQUIRED_INCLUDES)
+  if(HAVE_IBV_EVENT_DEVICE_SPEED_CHANGE)
+    target_compile_definitions(tent_interface
+                               INTERFACE HAVE_IBV_EVENT_DEVICE_SPEED_CHANGE)
+  endif()
 else()
   message(STATUS "RDMA: Disabled")
 endif()
 
 # io_uring
-find_library(URING_LIB uring PATHS /usr/lib /usr/lib64 /usr/local/lib
-                                   /usr/local/lib64)
-find_path(URING_INCLUDE liburing.h PATHS /usr/include /usr/local/include)
-if(URING_LIB AND URING_INCLUDE)
+if(TARGET Mooncake::liburing)
   message(STATUS "Uring: Enabled")
   target_compile_definitions(tent_interface INTERFACE USE_URING)
-  target_include_directories(tent_interface INTERFACE ${URING_INCLUDE})
-  target_link_libraries(tent_interface INTERFACE ${URING_LIB})
+  target_link_libraries(tent_interface INTERFACE Mooncake::liburing)
 else()
   message(STATUS "Uring: Disabled")
 endif()
@@ -87,15 +108,6 @@ if(USE_SUNRISE)
   target_link_libraries(tent_interface INTERFACE tangrt_shared ptml_shared dl)
 endif()
 
-set(YALANTING_TARGET yalantinglibs::yalantinglibs)
-if(NOT TARGET ${YALANTING_TARGET})
-  if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
-    find_package(yalantinglibs CONFIG REQUIRED)
-  else()
-    message(FATAL_ERROR "yalantinglibs::yalantinglibs target not found")
-  endif()
-endif()
-
 add_subdirectory(common)
 add_subdirectory(rpc)
 add_subdirectory(metastore)
@@ -119,6 +131,7 @@ target_link_libraries(tent PUBLIC tent_runtime tent_interface)
 
 add_library(tent_shared SHARED ${TENT_ENGINE_SOURCES})
 target_link_libraries(tent_shared PUBLIC tent_runtime tent_interface)
+set_target_properties(tent_shared PROPERTIES INSTALL_RPATH "$ORIGIN")
 
 add_library(tent_link_group INTERFACE)
 target_link_libraries(tent_link_group INTERFACE "-Wl,--start-group" tent)
@@ -133,6 +146,7 @@ foreach(
   platform_ascend
   platform_sunrise
   platform_tpu
+  platform_xpu
   tent_xport_gds
   tent_xport_uring
   tent_xport_bufio
@@ -141,10 +155,14 @@ foreach(
   tent_xport_rdma
   tent_xport_shm
   tent_xport_tcp
+  tent_xport_hp_tcp
+  tent_xport_hp_tcp_core
   tent_xport_ub
   tent_xport_ascend_direct
   tent_xport_sunrise_link
   tent_xport_tpu
+  tent_xport_xpu
+  tent_xport_mpcomm
   tent_metrics)
   if(TARGET ${tgt})
     target_link_libraries(tent_link_group INTERFACE ${tgt})
diff --git a/mooncake-transfer-engine/tent/src/common/CMakeLists.txt b/mooncake-transfer-engine/tent/src/common/CMakeLists.txt
index 6ebf8cb0f7..9422398fd1 100644
--- a/mooncake-transfer-engine/tent/src/common/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/common/CMakeLists.txt
@@ -1,3 +1,3 @@
 file(GLOB TENT_COMMON_SOURCES "*.cpp")
 add_library(tent_common OBJECT ${TENT_COMMON_SOURCES})
-target_link_libraries(tent_common PUBLIC glog pthread numa tent_interface)
\ No newline at end of file
+target_link_libraries(tent_common PUBLIC glog::glog pthread numa tent_interface)
diff --git a/mooncake-transfer-engine/tent/src/common/config.cpp b/mooncake-transfer-engine/tent/src/common/config.cpp
index 7ddbc89ca9..1e4bee3618 100644
--- a/mooncake-transfer-engine/tent/src/common/config.cpp
+++ b/mooncake-transfer-engine/tent/src/common/config.cpp
@@ -22,6 +22,30 @@
 
 namespace mooncake {
 namespace tent {
+namespace {
+
+void collectConfigPaths(const json& node, const std::string& prefix,
+                        std::vector<std::string>& paths) {
+    // A default-constructed Config has a null root and represents an empty
+    // configuration whose callers rely entirely on defaults.
+    if (prefix.empty() && node.is_null()) return;
+    if (!node.is_object()) {
+        paths.push_back(prefix);
+        return;
+    }
+    if (node.empty()) {
+        if (!prefix.empty()) paths.push_back(prefix);
+        return;
+    }
+
+    for (auto it = node.begin(); it != node.end(); ++it) {
+        std::string path = prefix.empty() ? it.key() : prefix + "/" + it.key();
+        collectConfigPaths(it.value(), path, paths);
+    }
+}
+
+}  // namespace
+
 Status Config::load(const std::string& content) {
     std::lock_guard<std::mutex> lock(mutex_);
     try {
@@ -49,12 +73,70 @@ std::string Config::dump(int indent) const {
     return config_data_.dump(indent);
 }
 
+bool Config::dumpSubtree(const std::string& key_path, std::string* out) const {
+    if (!out || key_path.empty()) return false;
+    std::lock_guard<std::mutex> lock(mutex_);
+    const json* node = &config_data_;
+    std::string::size_type start = 0;
+    bool nested_found = true;
+    while (start < key_path.size()) {
+        auto pos = key_path.find(kDelimiter, start);
+        auto segment = key_path.substr(start, pos - start);
+        start = (pos == std::string::npos) ? key_path.size() : pos + 1;
+        if (segment.empty()) continue;
+        auto it = node->find(segment);
+        if (it == node->end()) {
+            nested_found = false;
+            break;
+        }
+        node = &(*it);
+    }
+    if (nested_found && !node->is_null()) {
+        *out = node->dump();
+        return true;
+    }
+    auto flat_it = config_data_.find(key_path);
+    if (flat_it != config_data_.end() && !flat_it->is_null()) {
+        *out = flat_it->dump();
+        return true;
+    }
+    return false;
+}
+
+std::shared_ptr<const Config> Config::freeze() const {
+    auto frozen = std::make_shared<Config>();
+    std::lock_guard<std::mutex> lock(mutex_);
+    frozen->config_data_ = config_data_;
+    return frozen;
+}
+
+std::vector<std::string> Config::paths() const {
+    std::vector<std::string> paths;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        collectConfigPaths(config_data_, "", paths);
+    }
+    std::sort(paths.begin(), paths.end());
+    paths.erase(std::unique(paths.begin(), paths.end()), paths.end());
+    return paths;
+}
+
 static inline void setConfig(Config& config, const std::string& env_key,
                              const std::string& config_key) {
     const char* val = std::getenv(env_key.c_str());
     if (val) config.setFromString(config_key, std::string(val));
 }
 
+// Bool env vars: setFromString() stores "1" as int, so get(..., false) misses
+// it.
+static inline void setBoolConfig(Config& config, const std::string& env_key,
+                                 const std::string& config_key) {
+    const char* val = std::getenv(env_key.c_str());
+    if (!val) return;
+    config.set(config_key,
+               ConfigHelper::parseBool(val, config.get(config_key, false)));
+}
+
 // Like setConfig, but parses the env value as a comma-separated list and
 // stores it as a string array. Empty/whitespace-only items are dropped so a
 // trailing comma or spaces around names are tolerated (e.g. "mlx5_0, mlx5_1").
@@ -73,6 +155,13 @@ static inline void setArrayConfig(Config& config, const std::string& env_key,
     if (!items.empty()) config.set(config_key, items);
 }
 
+void ConfigHelper::forceTcp(Config& config) {
+    config.set("transports/force_tcp", true);
+    config.set("transports/tcp/enable", true);
+    config.set("transports/rdma/enable", false);
+    config.set("transports/hp_tcp/enable", false);
+}
+
 Status ConfigHelper::loadFromEnv(Config& config) {
     const char* conf_str = std::getenv("MC_TENT_CONF");
     Status status = Status::OK();
@@ -105,6 +194,13 @@ Status ConfigHelper::loadFromEnv(Config& config) {
     }
 
     // Legacy keys for backward compatibility (MC_* env vars)
+    setConfig(config, "MOONCAKE_LOCAL_HOSTNAME", "rpc_server_hostname");
+    if (std::getenv("MC_FORCE_TCP")) {
+        forceTcp(config);
+        LOG(INFO)
+            << "MC_FORCE_TCP is set, forcing TENT memory transfers to use TCP";
+    }
+    setBoolConfig(config, "MC_MNNVL_EGM", "transports/mnnvl/egm");
     setConfig(config, "MC_RDMA_BIND_ADDRESS", "transports/rdma/bind_address");
     setConfig(config, "MC_NUM_CQ_PER_CTX",
               "transports/rdma/device/num_cq_list");
@@ -137,6 +233,8 @@ Status ConfigHelper::loadFromEnv(Config& config) {
               "transports/rdma/disable_gpu_direct_rdma");
     setConfig(config, "MC_LOG_RDMA_SLICE_AFFINITY",
               "transports/rdma/log_slice_affinity");
+    setBoolConfig(config, "MC_STRICT_LOCAL_NUMA",
+                  "transports/rdma/strict_local_numa");
     // Restrict which RDMA NICs the engine discovers/uses (comma-separated
     // device names). MC_TE_FILTERS is an allow-list — same name and semantics
     // as the legacy Transfer Engine's device whitelist, so a single env works
@@ -145,6 +243,16 @@ Status ConfigHelper::loadFromEnv(Config& config) {
     // Consumed by filterInfiniBandDevices() in the platform probes.
     setArrayConfig(config, "MC_TE_FILTERS", "topology/rdma_whitelist");
     setArrayConfig(config, "MC_TE_FILTERS_EXCLUDE", "topology/rdma_blacklist");
+    // Classic TE custom topology file path. Maps into TENT config so the same
+    // MC_CUSTOM_TOPO_JSON works under MC_USE_TENT. Inline
+    // topology/priority_matrix in MC_TENT_CONF still takes precedence.
+    setConfig(config, "MC_CUSTOM_TOPO_JSON", "topology/custom_json_path");
+    // TENT RPC server io_context threads. TCP SendData/RecvData copies are
+    // offloaded onto the blocking executor; this pool still reads the RPC
+    // attachments. When TCP is enabled and this key is unset, the engine
+    // defaults to several threads so concurrent bulk transfers are not
+    // serialized on one io_context.
+    setConfig(config, "MC_TENT_RPC_THREADS", "rpc_server_threads");
     return status;
 }
 
diff --git a/mooncake-transfer-engine/tent/src/common/config_lifecycle.cpp b/mooncake-transfer-engine/tent/src/common/config_lifecycle.cpp
new file mode 100644
index 0000000000..6d3b07464d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/common/config_lifecycle.cpp
@@ -0,0 +1,156 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/common/config_lifecycle.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// Only runtime candidates need explicit entries. Everything else is
+// bootstrap-only, including new transport namespaces and unknown keys.
+constexpr ConfigFieldSpec kConfigFields[] = {
+    // Fields that can be represented by an immutable runtime generation.
+    {"log_level", ConfigFieldMatch::kExact},
+    {"merge_requests", ConfigFieldMatch::kExact},
+    {"max_failover_attempts", ConfigFieldMatch::kExact},
+    {"enable_auto_failover_on_poll", ConfigFieldMatch::kExact},
+    {"runtime_queue", ConfigFieldMatch::kSubtree},
+    {"policy", ConfigFieldMatch::kSubtree},
+    {"qos", ConfigFieldMatch::kSubtree},
+    {"metrics/report_interval_seconds", ConfigFieldMatch::kExact},
+
+    // RDMA policy and health knobs do not allocate devices, CQs, or QPs and
+    // are candidates for a later staged apply handler.
+    {"transports/rdma/enable_smart_scheduling", ConfigFieldMatch::kExact},
+    {"transports/rdma/numa_penalties", ConfigFieldMatch::kExact},
+    {"transports/rdma/strict_local_numa", ConfigFieldMatch::kExact},
+    {"transports/rdma/bandwidth_learning_rate", ConfigFieldMatch::kExact},
+    {"transports/rdma/ewma_min_bandwidth_multiplier", ConfigFieldMatch::kExact},
+    {"transports/rdma/ewma_max_bandwidth_multiplier", ConfigFieldMatch::kExact},
+    {"transports/rdma/score_jitter_range", ConfigFieldMatch::kExact},
+    {"transports/rdma/score_epsilon", ConfigFieldMatch::kExact},
+    {"transports/rdma/enable_priority_filtering", ConfigFieldMatch::kExact},
+    {"transports/rdma/local_rotation_interval_us", ConfigFieldMatch::kExact},
+    {"transports/rdma/priority_promotion_timeout_us", ConfigFieldMatch::kExact},
+    {"transports/rdma/deadline_bw_arbitration", ConfigFieldMatch::kExact},
+    {"transports/rdma/priority_promotion_per_entry", ConfigFieldMatch::kExact},
+    {"transports/rdma/slot_rotation_interval_ms", ConfigFieldMatch::kExact},
+    {"transports/rdma/default_bandwidth_gbps", ConfigFieldMatch::kExact},
+    {"transports/rdma/min_bandwidth_gbps", ConfigFieldMatch::kExact},
+    {"transports/rdma/max_bandwidth_gbps", ConfigFieldMatch::kExact},
+    {"transports/rdma/rail_error_threshold", ConfigFieldMatch::kExact},
+    {"transports/rdma/rail_error_window_secs", ConfigFieldMatch::kExact},
+    {"transports/rdma/rail_cooldown_secs", ConfigFieldMatch::kExact},
+    {"transports/rdma/gdr_error_threshold", ConfigFieldMatch::kExact},
+    {"transports/rdma/gdr_error_window_secs", ConfigFieldMatch::kExact},
+    {"transports/rdma/gdr_cooldown_secs", ConfigFieldMatch::kExact},
+};
+
+bool matches(const ConfigFieldSpec& spec, std::string_view path) {
+    if (path == spec.path) return true;
+    return spec.match == ConfigFieldMatch::kSubtree &&
+           path.size() > spec.path.size() &&
+           path.compare(0, spec.path.size(), spec.path) == 0 &&
+           path[spec.path.size()] == '/';
+}
+
+}  // namespace
+
+std::span<const ConfigFieldSpec> configFieldInventory() {
+    return kConfigFields;
+}
+
+ConfigLifecycle classifyConfigPath(std::string_view path) {
+    const ConfigFieldSpec* best_match = nullptr;
+    for (const auto& field : kConfigFields) {
+        if (!matches(field, path)) continue;
+        if (!best_match || field.path.size() > best_match->path.size()) {
+            best_match = &field;
+        }
+    }
+    return best_match ? ConfigLifecycle::kRuntimeCandidate
+                      : ConfigLifecycle::kBootstrapOnly;
+}
+
+const char* configLifecycleName(ConfigLifecycle lifecycle) {
+    switch (lifecycle) {
+        case ConfigLifecycle::kBootstrapOnly:
+            return "bootstrap-only";
+        case ConfigLifecycle::kRuntimeCandidate:
+            return "runtime-candidate";
+    }
+    return "unknown";
+}
+
+bool LifecycleConfigView::allows(std::string_view key_path) const {
+    return classifyConfigPath(key_path) == lifecycle_;
+}
+
+bool LifecycleConfigView::canRead(std::string_view key_path) const {
+    // Config skips empty segments; reject aliases before lifecycle and
+    // descendant checks so they apply to the same path as the lookup.
+    if (key_path.empty() || key_path.front() == '/' || key_path.back() == '/' ||
+        key_path.find("//") != std::string_view::npos) {
+        return false;
+    }
+    if (!values_ || !allows(key_path)) return false;
+
+    for (const auto& configured_path : configured_paths_) {
+        if (configured_path.size() <= key_path.size() ||
+            configured_path.compare(0, key_path.size(), key_path) != 0 ||
+            configured_path[key_path.size()] != '/') {
+            continue;
+        }
+        if (!allows(configured_path)) return false;
+    }
+    return true;
+}
+
+bool LifecycleConfigView::contains(const std::string& key_path) const {
+    return canRead(key_path) && values_->contains(key_path);
+}
+
+bool LifecycleConfigView::dumpSubtree(const std::string& key_path,
+                                      std::string* out) const {
+    return canRead(key_path) && values_->dumpSubtree(key_path, out);
+}
+
+TentConfigBundle buildTentConfigBundle(const Config& effective_config,
+                                       uint64_t generation) {
+    TentConfigBundle bundle;
+    auto frozen = effective_config.freeze();
+    bundle.bootstrap = std::make_shared<const BootstrapConfig>(frozen);
+
+    auto runtime_config = std::make_shared<const RuntimeConfig>(frozen);
+    bundle.runtime =
+        std::make_shared<const RuntimeConfigSnapshot>(RuntimeConfigSnapshot{
+            generation, runtime_config,
+            runtime_config->get("max_failover_attempts",
+                                kDefaultMaxFailoverAttempts),
+            runtime_config->get("enable_auto_failover_on_poll",
+                                kDefaultAutoFailoverOnPoll)});
+
+    for (const auto& path : frozen->paths()) {
+        if (path.empty()) {
+            bundle.diagnostics.push_back(
+                {ConfigDiagnosticCode::kInvalidRoot, "$",
+                 "TENT configuration root must be a JSON object"});
+        }
+    }
+    return bundle;
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/common/qos_metrics.cpp b/mooncake-transfer-engine/tent/src/common/qos_metrics.cpp
index 961c826efb..c75d52956e 100644
--- a/mooncake-transfer-engine/tent/src/common/qos_metrics.cpp
+++ b/mooncake-transfer-engine/tent/src/common/qos_metrics.cpp
@@ -368,6 +368,8 @@ bool appendQosMetricsJsonl(const std::string& path,
         return false;
     }
     output << root.dump() << '\n';
+    // Closing flushes buffered output and can reveal delayed write errors.
+    output.close();
     if (!output) {
         *error = "failed to write QoS JSONL output: " + path;
         return false;
diff --git a/mooncake-transfer-engine/tent/src/common/status.cpp b/mooncake-transfer-engine/tent/src/common/status.cpp
index f364efe862..d18a99145d 100644
--- a/mooncake-transfer-engine/tent/src/common/status.cpp
+++ b/mooncake-transfer-engine/tent/src/common/status.cpp
@@ -73,6 +73,8 @@ std::string_view Status::CodeToString(Status::Code code) {
             return "MetadataError";
         case Code::kRpcServiceError:
             return "RpcServiceError";
+        case Code::kRpcConnectionError:
+            return "RpcConnectionError";
         case Code::kMalformedJson:
             return "MalformedJson";
         case Code::kInternalError:
diff --git a/mooncake-transfer-engine/tent/src/metastore/CMakeLists.txt b/mooncake-transfer-engine/tent/src/metastore/CMakeLists.txt
index 9755a01a81..20a9f82581 100644
--- a/mooncake-transfer-engine/tent/src/metastore/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/metastore/CMakeLists.txt
@@ -29,10 +29,9 @@ else()
     message(STATUS "Http metastore support: Disabled")
 endif()
 
-find_library(HIREDIS_LIB hiredis)
-if(HIREDIS_LIB)
+if(TARGET Mooncake::hiredis)
     message(STATUS "Redis metastore support: Enabled")
-    add_metastore_module(redis DEPS ${HIREDIS_LIB})
+    add_metastore_module(redis DEPS Mooncake::hiredis)
 else()
     message(STATUS "Redis metastore support: Disabled")
-endif()
\ No newline at end of file
+endif()
diff --git a/mooncake-transfer-engine/tent/src/metastore/http.cpp b/mooncake-transfer-engine/tent/src/metastore/http.cpp
index 071d3603d1..d9281dd9f9 100644
--- a/mooncake-transfer-engine/tent/src/metastore/http.cpp
+++ b/mooncake-transfer-engine/tent/src/metastore/http.cpp
@@ -65,6 +65,7 @@ struct ScopedCurl {
 }  // namespace
 
 Status HttpMetaStore::get(const std::string &key, std::string &value) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("HTTP connection not available" LOC_MARK);
     }
@@ -106,6 +107,7 @@ Status HttpMetaStore::get(const std::string &key, std::string &value) {
 }
 
 Status HttpMetaStore::set(const std::string &key, const std::string &value) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("HTTP connection not available" LOC_MARK);
     }
@@ -153,6 +155,7 @@ Status HttpMetaStore::set(const std::string &key, const std::string &value) {
 }
 
 Status HttpMetaStore::remove(const std::string &key) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("HTTP connection not available" LOC_MARK);
     }
diff --git a/mooncake-transfer-engine/tent/src/metastore/redis.cpp b/mooncake-transfer-engine/tent/src/metastore/redis.cpp
index 0774acefbf..74df2897b7 100644
--- a/mooncake-transfer-engine/tent/src/metastore/redis.cpp
+++ b/mooncake-transfer-engine/tent/src/metastore/redis.cpp
@@ -40,7 +40,19 @@ class RedisReplyGuard {
     redisReply *reply_;
 };
 
-RedisMetaStore::RedisMetaStore() {}
+RedisMetaStore::RedisMetaStore() : connected_(false), client_(nullptr) {}
+
+redisReply *RedisMetaStore::command(const char *format, ...) {
+    va_list ap;
+    va_start(ap, format);
+    redisReply *reply = runCommand(format, ap);
+    va_end(ap);
+    return reply;
+}
+
+redisReply *RedisMetaStore::runCommand(const char *format, va_list ap) {
+    return static_cast<redisReply *>(redisvCommand(client_, format, ap));
+}
 
 RedisMetaStore::~RedisMetaStore() { disconnect(); }
 
@@ -171,13 +183,13 @@ Status RedisMetaStore::handleRedisReply(redisReply *reply,
 }
 
 Status RedisMetaStore::get(const std::string &key, std::string &value) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("Redis connection not available" LOC_MARK);
     }
 
     // Use binary-safe formatting to prevent command injection
-    redisReply *resp =
-        (redisReply *)redisCommand(client_, "GET %b", key.data(), key.size());
+    redisReply *resp = command("GET %b", key.data(), key.size());
     RedisReplyGuard reply_guard(resp);
 
     Status status = handleRedisReply(resp, "GET '" + key + "'");
@@ -189,32 +201,33 @@ Status RedisMetaStore::get(const std::string &key, std::string &value) {
         return Status::InvalidEntry(key);
     }
 
-    value = std::string(resp->str);
+    // Use (str, len): redis values are binary-safe and may contain NULs.
+    value = std::string(resp->str, resp->len);
     return Status::OK();
 }
 
 Status RedisMetaStore::set(const std::string &key, const std::string &value) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("Redis connection not available" LOC_MARK);
     }
 
     // Use binary-safe formatting to prevent command injection
-    redisReply *resp =
-        (redisReply *)redisCommand(client_, "SET %b %b", key.data(), key.size(),
-                                   value.data(), value.size());
+    redisReply *resp = command("SET %b %b", key.data(), key.size(),
+                               value.data(), value.size());
     RedisReplyGuard reply_guard(resp);
 
     return handleRedisReply(resp, "SET '" + key + "'");
 }
 
 Status RedisMetaStore::remove(const std::string &key) {
+    std::lock_guard<std::mutex> lock(client_mutex_);
     if (!connected_) {
         return Status::MetadataError("Redis connection not available" LOC_MARK);
     }
 
     // Use binary-safe formatting to prevent command injection
-    redisReply *resp =
-        (redisReply *)redisCommand(client_, "DEL %b", key.data(), key.size());
+    redisReply *resp = command("DEL %b", key.data(), key.size());
     RedisReplyGuard reply_guard(resp);
 
     return handleRedisReply(resp, "DEL '" + key + "'");
diff --git a/mooncake-transfer-engine/tent/src/metrics/CMakeLists.txt b/mooncake-transfer-engine/tent/src/metrics/CMakeLists.txt
index 5b8720e05d..e92044e0cf 100644
--- a/mooncake-transfer-engine/tent/src/metrics/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/metrics/CMakeLists.txt
@@ -1,6 +1,27 @@
 # TENT_METRICS_ENABLED option is declared in tent/CMakeLists.txt.
 file(GLOB TENT_METRICS_SOURCES "*.cpp")
-add_library(tent_metrics STATIC ${TENT_METRICS_SOURCES})
+# Build as a SHARED library so the TentMetrics singleton (the function-local
+# `static TentMetrics instance` in TentMetrics::instance()) is not duplicated
+# across DSOs. When statically linked, the metrics code is copied into every
+# consumer .so (engine.so and store.so), giving each its own TentMetrics
+# instance: a process that loads both modules ends up with two independent
+# metrics singletons, two periodic report threads ("TENT Metrics:" logged
+# twice per interval), and a metrics HTTP port clash (both default to 9100,
+# so only one binds and the other silently degrades to log-only). As a shared
+# library, both modules take a single DT_NEEDED on libtent_metrics.so and
+# share the one process-wide singleton. PIC is already on for the whole tent
+# tree (tent/CMakeLists.txt sets CMAKE_POSITION_INDEPENDENT_CODE ON), so the
+# tent_common OBJECT dependency links cleanly into the shared object.
+add_library(tent_metrics SHARED ${TENT_METRICS_SOURCES})
+# Installed libtent_metrics.so sits next to libasio.so / libtent_common.so in
+# lib/, so $ORIGIN resolves its sibling dependencies at runtime regardless of
+# install prefix. Do NOT set BUILD_WITH_INSTALL_RPATH here: that would replace
+# CMake's build-tree RPATH (which records full paths to the build-tree siblings
+# like libasio.so) with $ORIGIN alone, and ctest would fail to load
+# libtent_metrics.so before `cmake --install` (libasio.so lives in a different
+# build subdir). CMake falls back to INSTALL_RPATH automatically at install
+# time, mirroring asio_shared in mooncake-common/src/CMakeLists.txt.
+set_target_properties(tent_metrics PROPERTIES INSTALL_RPATH "$ORIGIN")
 # Link yalantinglibs::yalantinglibs for metrics and HTTP server (ylt headers +
 # transitive deps). ODR safety: yalantinglibs bundles ASIO headers but does NOT
 # compile ASIO inline because ASIO_SEPARATE_COMPILATION is set globally. All
@@ -10,7 +31,7 @@ add_library(tent_metrics STATIC ${TENT_METRICS_SOURCES})
 # ODR violations")
 target_link_libraries(
   tent_metrics PUBLIC tent_common tent_interface yalantinglibs::yalantinglibs
-                      glog pthread)
+                      glog::glog pthread)
 
 # Pass compile definition based on option
 if(TENT_METRICS_ENABLED)
@@ -20,3 +41,11 @@ else()
   target_compile_definitions(tent_metrics PUBLIC TENT_METRICS_ENABLED=0)
   message(STATUS "TENT metrics: DISABLED (zero overhead)")
 endif()
+
+# Install to lib/ for libtent_shared.so / system consumers. The python C
+# extensions (engine.so, store.so) resolve it via $ORIGIN, so a second
+# install lands libtent_metrics.so next to them — see
+# mooncake-integration/CMakeLists.txt.
+install(
+  TARGETS tent_metrics
+  LIBRARY DESTINATION lib)
diff --git a/mooncake-transfer-engine/tent/src/metrics/tent_metrics.cpp b/mooncake-transfer-engine/tent/src/metrics/tent_metrics.cpp
index 4c279314df..82db575d28 100644
--- a/mooncake-transfer-engine/tent/src/metrics/tent_metrics.cpp
+++ b/mooncake-transfer-engine/tent/src/metrics/tent_metrics.cpp
@@ -35,6 +35,20 @@ namespace {
 const char* operationName(Request::OpCode operation) {
     return operation == Request::READ ? "read" : "write";
 }
+
+const char* taskFailureReasonName(TentMetrics::TaskFailureReason reason) {
+    switch (reason) {
+        case TentMetrics::TaskFailureReason::Submit:
+            return "submit";
+        case TentMetrics::TaskFailureReason::Poll:
+            return "poll";
+        case TentMetrics::TaskFailureReason::Timeout:
+            return "timeout";
+        case TentMetrics::TaskFailureReason::Canceled:
+            return "canceled";
+    }
+    return "unknown";
+}
 }  // namespace
 
 Status TentMetrics::initialize(const MetricsConfig& config) {
@@ -195,6 +209,7 @@ void TentMetrics::shutdown() {
     // Clear metric vectors
     counters_.clear();
     histograms_.clear();
+    gauges_.clear();
 
     // Reset bound port so httpPort() returns 0 after shutdown, not a stale
     // port from a previous initialization. Without this, a re-initialize
@@ -209,7 +224,8 @@ void TentMetrics::registerMetrics() {
     // Register all counters as base metric_t* pointers so that counters with
     // different label arities (N=1 per-transport, N=2 failover from→to and
     // transport-attempt operation labels) share one vector for Prometheus
-    // serialize().
+    // serialize(). CachedDynamicCounter is-a basic_dynamic_counter, so its
+    // ylt serialize() output is unchanged.
     counters_ = {
         &read_bytes_total_,
         &write_bytes_total_,
@@ -220,25 +236,23 @@ void TentMetrics::registerMetrics() {
         &failover_total_,
         &transport_attempts_total_,
         &transport_attempt_failures_total_,
+        &task_failures_total_,
         &deadline_infeasible_total_,
+        &quarantined_batches_total_,
+    };
+
+    gauges_ = {
+        &inflight_attempts_,
+        &registered_buffer_bytes_,
     };
 
-    // Register the N=1 per-transport histograms with their bucket boundaries
-    // and parallel sum counters. Each entry keeps the histogram, its
-    // compile-time boundaries, and its sum counter in sync so both the
-    // Prometheus and JSON serializers cannot mislabel buckets or drop _sum.
+    // Register the N=1 per-transport histograms for unified serialization.
     // The N=2 transport_attempt_latency_ histogram is serialized separately
     // (it can't share this N=1-typed vector); see getPrometheusMetrics /
     // getJsonMetrics.
     histograms_ = {
-        {&read_latency_, &kLatencyBuckets, &read_latency_sum_},
-        {&write_latency_, &kLatencyBuckets, &write_latency_sum_},
-        {&read_size_, &kSizeBuckets, &read_size_sum_},
-        {&write_size_, &kSizeBuckets, &write_size_sum_},
-        {&deadline_mlu_, &kMluPerMilleBuckets, &deadline_mlu_sum_},
-        {&stage_queue_wait_, &kStageBuckets, &stage_queue_wait_sum_},
-        {&stage_dispatch_, &kStageBuckets, &stage_dispatch_sum_},
-        {&stage_transport_, &kStageBuckets, &stage_transport_sum_},
+        &read_latency_, &write_latency_,    &read_size_,      &write_size_,
+        &deadline_mlu_, &stage_queue_wait_, &stage_dispatch_, &stage_transport_,
     };
 }
 
@@ -247,16 +261,19 @@ void TentMetrics::recordReadCompleted(TransportType tp, size_t bytes,
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
 
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
-    read_bytes_total_.inc(label, static_cast<int64_t>(bytes));
-    read_requests_total_.inc(label);
+    const size_t slot = transportSlot(tp);
+    // The label is only constructed on the first use of this slot (cache
+    // miss); the steady state is a relaxed atomic add.
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
     auto bytes_val = static_cast<int64_t>(bytes);
-    read_size_.observe(label, bytes_val);
-    read_size_sum_.inc(label, bytes_val);
+    read_bytes_total_.incCached(slot, label, bytes_val);
+    read_requests_total_.incCached(slot, label);
+    read_size_.observeCached(slot, label, bytes_val);
     if (latency_seconds > 0.0) {
         int64_t latency_us = static_cast<int64_t>(latency_seconds * 1000000.0);
-        read_latency_.observe(label, latency_us);
-        read_latency_sum_.inc(label, latency_us);
+        read_latency_.observeCached(slot, label, latency_us);
     }
 }
 
@@ -265,16 +282,17 @@ void TentMetrics::recordWriteCompleted(TransportType tp, size_t bytes,
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
 
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
-    write_bytes_total_.inc(label, static_cast<int64_t>(bytes));
-    write_requests_total_.inc(label);
+    const size_t slot = transportSlot(tp);
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
     auto bytes_val = static_cast<int64_t>(bytes);
-    write_size_.observe(label, bytes_val);
-    write_size_sum_.inc(label, bytes_val);
+    write_bytes_total_.incCached(slot, label, bytes_val);
+    write_requests_total_.incCached(slot, label);
+    write_size_.observeCached(slot, label, bytes_val);
     if (latency_seconds > 0.0) {
         int64_t latency_us = static_cast<int64_t>(latency_seconds * 1000000.0);
-        write_latency_.observe(label, latency_us);
-        write_latency_sum_.inc(label, latency_us);
+        write_latency_.observeCached(slot, label, latency_us);
     }
 }
 
@@ -282,17 +300,63 @@ void TentMetrics::recordDeadlineMLU(TransportType tp, double mlu) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
     if (mlu < 0.0) return;
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
+    const size_t slot = transportSlot(tp);
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
     auto mlu_permille = static_cast<int64_t>(mlu * 1000.0);
-    deadline_mlu_.observe(label, mlu_permille);
-    deadline_mlu_sum_.inc(label, mlu_permille);
+    deadline_mlu_.observeCached(slot, label, mlu_permille);
 }
 
 void TentMetrics::recordDeadlineInfeasible(TransportType tp) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
-    deadline_infeasible_total_.inc(
-        std::array<std::string, 1>{transportTypeName(tp)});
+    deadline_infeasible_total_.incCached(transportSlot(tp), [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    });
+}
+
+void TentMetrics::recordBatchQuarantined() {
+    if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
+        return;
+    quarantined_batches_total_.inc();
+}
+
+void TentMetrics::recordTaskFailure(TransportType tp,
+                                    TaskFailureReason reason) {
+    if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
+        return;
+    task_failures_total_.incCached(taskFailureSlot(tp, reason), [tp, reason] {
+        return std::array<std::string, 2>{transportTypeName(tp),
+                                          taskFailureReasonName(reason)};
+    });
+}
+
+// Gauge updates below deliberately ignore runtime_enabled_: gauges track
+// engine state through paired add/sub operations (attempt start/finish,
+// register/unregister), and skipping one half of a pair across a
+// setEnabled() transition would permanently corrupt the value. Counters and
+// histograms are samples and may be dropped while disabled; gauges are not.
+void TentMetrics::recordInflightAttemptStarted(TransportType tp) {
+    if (!initialized_) return;
+    inflight_attempts_.incCached(transportSlot(tp), [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    });
+}
+
+void TentMetrics::recordInflightAttemptFinished(TransportType tp) {
+    if (!initialized_) return;
+    inflight_attempts_.incCached(
+        transportSlot(tp),
+        [tp] { return std::array<std::string, 1>{transportTypeName(tp)}; }, -1);
+}
+
+void TentMetrics::recordRegisteredBufferBytes(TransportType tp, int64_t delta) {
+    if (!initialized_) return;
+    registered_buffer_bytes_.incCached(
+        transportSlot(tp),
+        [tp] { return std::array<std::string, 1>{transportTypeName(tp)}; },
+        delta);
 }
 
 void TentMetrics::recordStageLatency(Stage stage, TransportType tp,
@@ -300,20 +364,20 @@ void TentMetrics::recordStageLatency(Stage stage, TransportType tp,
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
     if (latency_us < 0.0) return;
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
+    const size_t slot = transportSlot(tp);
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
     int64_t val = static_cast<int64_t>(latency_us);
     switch (stage) {
         case Stage::QueueWait:
-            stage_queue_wait_.observe(label, val);
-            stage_queue_wait_sum_.inc(label, val);
+            stage_queue_wait_.observeCached(slot, label, val);
             break;
         case Stage::Dispatch:
-            stage_dispatch_.observe(label, val);
-            stage_dispatch_sum_.inc(label, val);
+            stage_dispatch_.observeCached(slot, label, val);
             break;
         case Stage::Transport:
-            stage_transport_.observe(label, val);
-            stage_transport_sum_.inc(label, val);
+            stage_transport_.observeCached(slot, label, val);
             break;
     }
 }
@@ -321,23 +385,31 @@ void TentMetrics::recordStageLatency(Stage stage, TransportType tp,
 void TentMetrics::recordReadFailed(TransportType tp) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
-    read_failures_total_.inc(label);
-    read_requests_total_.inc(label);
+    const size_t slot = transportSlot(tp);
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
+    read_failures_total_.incCached(slot, label);
+    read_requests_total_.incCached(slot, label);
 }
 
 void TentMetrics::recordWriteFailed(TransportType tp) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
-    auto label = std::array<std::string, 1>{transportTypeName(tp)};
-    write_failures_total_.inc(label);
-    write_requests_total_.inc(label);
+    const size_t slot = transportSlot(tp);
+    auto label = [tp] {
+        return std::array<std::string, 1>{transportTypeName(tp)};
+    };
+    write_failures_total_.incCached(slot, label);
+    write_requests_total_.incCached(slot, label);
 }
 
 void TentMetrics::recordTransportFailover(TransportType from,
                                           TransportType to) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
+    // Rare event on a large (transport × transport) label domain: plain
+    // locked path, no cached cells.
     failover_total_.inc(std::array<std::string, 2>{transportTypeName(from),
                                                    transportTypeName(to)});
 }
@@ -346,8 +418,11 @@ void TentMetrics::recordTransportAttemptStarted(TransportType tp,
                                                 Request::OpCode operation) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
-    transport_attempts_total_.inc(std::array<std::string, 2>{
-        transportTypeName(tp), operationName(operation)});
+    const size_t slot = attemptSlot(tp, operation);
+    transport_attempts_total_.incCached(slot, [tp, operation] {
+        return std::array<std::string, 2>{transportTypeName(tp),
+                                          operationName(operation)};
+    });
 }
 
 void TentMetrics::recordTransportAttemptFinished(TransportType tp,
@@ -356,15 +431,17 @@ void TentMetrics::recordTransportAttemptFinished(TransportType tp,
                                                  double latency_us) {
     if (!initialized_ || !runtime_enabled_.load(std::memory_order_relaxed))
         return;
-    auto label = std::array<std::string, 2>{transportTypeName(tp),
-                                            operationName(operation)};
+    const size_t slot = attemptSlot(tp, operation);
+    auto label = [tp, operation] {
+        return std::array<std::string, 2>{transportTypeName(tp),
+                                          operationName(operation)};
+    };
     if (status == FAILED) {
-        transport_attempt_failures_total_.inc(label);
+        transport_attempt_failures_total_.incCached(slot, label);
     }
     if (latency_us >= 0.0) {
         auto latency_val = static_cast<int64_t>(latency_us);
-        transport_attempt_latency_.observe(label, latency_val);
-        transport_attempt_latency_sum_.inc(label, latency_val);
+        transport_attempt_latency_.observeCached(slot, label, latency_val);
     }
 }
 
@@ -393,15 +470,17 @@ std::string TentMetrics::getPrometheusMetrics() {
         // walks get_bucket_counts() directly and is unaffected, which is why
         // /metrics/json reported count=4846 while /metrics omitted the metric
         // entirely. Using the same bucket-walk here closes that drift.
-        for (const auto& entry : histograms_) {
-            serializeHistogramPrometheus(entry.h, *entry.boundaries, *entry.sum,
-                                         result);
+        for (const auto& hist : histograms_) {
+            serializeHistogramPrometheus(*hist, result);
         }
         // N=2 transport-attempt latency histogram (labels: transport,
         // operation) goes through the same helper, instantiated for N=2.
-        serializeHistogramPrometheus(&transport_attempt_latency_,
-                                     kLatencyBuckets,
-                                     transport_attempt_latency_sum_, result);
+        serializeHistogramPrometheus(transport_attempt_latency_, result);
+
+        // Gauges: current value per label.
+        for (auto* gauge : gauges_) {
+            serializeGaugePrometheus(*gauge, result);
+        }
 
         return result;
     } catch (const std::exception& e) {
@@ -423,44 +502,39 @@ int64_t sumCounterValues(CounterPtr counter) {
 }
 
 template <uint8_t N>
-void serializeHistogramToJson(
-    nlohmann::json& root,
-    ylt::metric::basic_dynamic_histogram<int64_t, N>* hist,
-    const std::vector<double>& boundaries,
-    ylt::metric::basic_dynamic_counter<int64_t, N>* sum) {
-    auto bucket_counts = hist->get_bucket_counts();
+void serializeHistogramToJson(nlohmann::json& root,
+                              metrics::CachedDynamicHistogram<N>& hist) {
+    auto bucket_counters = hist.bucketCounters();
+    const auto& boundaries = hist.boundaries();
     int64_t total_count = 0;
     int64_t total_sum = 0;
     nlohmann::json buckets_obj;
-    for (size_t i = 0; i < bucket_counts.size(); ++i) {
-        int64_t bucket_total = sumCounterValues(bucket_counts[i]);
+    for (size_t i = 0; i < bucket_counters.size(); ++i) {
+        int64_t bucket_total = sumCounterValues(bucket_counters[i]);
         total_count += bucket_total;
         if (i < boundaries.size()) {
             buckets_obj[std::to_string(static_cast<int64_t>(boundaries[i]))] =
                 bucket_total;
         }
     }
-    // ylt keeps the histogram's sum_ private, so read the parallel sum counter
-    // maintained alongside each observe() call (matches the Prometheus path).
-    for (auto& e : sum->copy()) {
+    // The sum counter is maintained by the histogram itself (one add per
+    // observe), matching the Prometheus path.
+    for (auto& e : hist.sumCounter()->copy()) {
         total_sum += e->value.load();
     }
     nlohmann::json hist_obj;
     hist_obj["count"] = total_count;
     hist_obj["sum"] = total_sum;
     hist_obj["buckets"] = buckets_obj;
-    root[hist->str_name()] = hist_obj;
+    root[hist.name()] = hist_obj;
 }
 }  // namespace
 
 template <uint8_t N>
 void TentMetrics::serializeHistogramPrometheus(
-    ylt::metric::basic_dynamic_histogram<int64_t, N>* hist,
-    const std::vector<double>& boundaries,
-    ylt::metric::basic_dynamic_counter<int64_t, N>& sum,
-    std::string& out) const {
-    // Walk the same data the JSON path uses (get_bucket_counts() + copy()),
-    // so the two endpoints cannot drift. Unlike ylt's serialize() this never
+    metrics::CachedDynamicHistogram<N>& hist, std::string& out) const {
+    // Walk the same bucket-counter / sum-counter data the JSON path uses, so
+    // the two endpoints cannot drift. Unlike ylt's serialize() this never
     // silently drops a histogram that has observed >=1 sample: ylt clears its
     // output string (taking the # HELP / # TYPE header with it) whenever
     // every label combo has sum_==0, which is reachable in production when
@@ -469,10 +543,11 @@ void TentMetrics::serializeHistogramPrometheus(
     // Templated over label arity N: the per-transport histograms are N=1 and
     // the transport-attempt latency histogram is N=2. For N=1 the emitted
     // text is byte-identical to the original single-label implementation.
-    auto bucket_counts = hist->get_bucket_counts();
-    if (bucket_counts.empty()) return;
+    auto bucket_counters = hist.bucketCounters();
+    if (bucket_counters.empty()) return;
 
-    const auto& label_names = hist->labels_name();
+    const auto& boundaries = hist.boundaries();
+    const auto& label_names = hist.labelsName();
 
     // A unique key per label tuple, used to dedup combos and look up the sum.
     auto combo_key = [](const std::array<std::string, N>& lv) {
@@ -492,16 +567,15 @@ void TentMetrics::serializeHistogramPrometheus(
         }
     };
 
-    // Build the union of label combos across ALL buckets. ylt's observe()
-    // increments exactly one bucket per observation (the bucket containing
-    // the value), so no single bucket sees every combo: e.g. queue_wait
-    // (sub-us -> bucket[0]) and transport_us (>=100us -> higher buckets) live
-    // in disjoint buckets. ylt itself uses sum_->copy() for this, but sum_ is
-    // private. Unioning across buckets gives the same set without needing sum_.
+    // Build the union of label combos across ALL buckets. A bucket counter
+    // only sees a combo after that combo has been observed in that bucket,
+    // so no single bucket sees every combo: e.g. queue_wait (sub-us ->
+    // bucket[0]) and transport_us (>=100us -> higher buckets) live in
+    // disjoint buckets. Unioning across buckets recovers the full set.
     std::vector<const std::array<std::string, N>*> label_combos;
     std::unordered_set<std::string> seen;
-    for (auto& bc : bucket_counts) {
-        for (auto& e : bc->copy()) {
+    for (auto* bucket_counter : bucket_counters) {
+        for (auto& e : bucket_counter->copy()) {
             if (seen.insert(combo_key(e->label)).second) {
                 label_combos.push_back(&e->label);
             }
@@ -511,15 +585,13 @@ void TentMetrics::serializeHistogramPrometheus(
 
     // Pre-compute per-combo total counts so we can (a) skip totally-empty
     // combos and (b) decide whether to emit the # HELP / # TYPE header at
-    // all. This mirrors ylt's "emit head only if value_map non-empty" but
-    // uses bucket counts instead of sum, so a combo with sum==0 but real
-    // observations is still emitted.
+    // all. A combo with sum==0 but real observations is still emitted.
     std::vector<std::pair<const std::array<std::string, N>*, int64_t>>
         active_combos;
     for (auto* labels_value : label_combos) {
         int64_t total_count = 0;
-        for (auto& bc : bucket_counts) {
-            total_count += bc->value(*labels_value);
+        for (auto* bucket_counter : bucket_counters) {
+            total_count += bucket_counter->value(*labels_value);
         }
         if (total_count > 0) {
             active_combos.emplace_back(labels_value, total_count);
@@ -527,17 +599,16 @@ void TentMetrics::serializeHistogramPrometheus(
     }
     if (active_combos.empty()) return;
 
-    // Read back the per-combo sum from the parallel counter. ylt's histogram
-    // keeps sum_ private with no accessor, so we maintain a separate counter
-    // incremented alongside each observe() call. copy() returns a vector of
+    // Read back the per-combo sum from the histogram's sum counter
+    // (maintained alongside each observe() call). copy() returns a vector of
     // {label, value} pairs; build a lookup map for O(1) access per combo.
     std::unordered_map<std::string, int64_t> sum_by_combo;
-    for (auto& e : sum.copy()) {
+    for (auto& e : hist.sumCounter()->copy()) {
         sum_by_combo[combo_key(e->label)] = e->value.load();
     }
 
-    const std::string& name = hist->str_name();
-    const std::string help_str{hist->help()};
+    const std::string& name = hist.name();
+    const std::string help_str{hist.help()};
 
     // Emit the header once per metric (matches ylt's serialize_head()).
     out.append("# HELP ").append(name).append(" ").append(help_str).append(
@@ -546,8 +617,8 @@ void TentMetrics::serializeHistogramPrometheus(
 
     for (auto& [labels_value, total_count] : active_combos) {
         int64_t cumulative = 0;
-        for (size_t i = 0; i < bucket_counts.size(); ++i) {
-            cumulative += bucket_counts[i]->value(*labels_value);
+        for (size_t i = 0; i < bucket_counters.size(); ++i) {
+            cumulative += bucket_counters[i]->value(*labels_value);
             out.append(name).append("_bucket{");
             append_labels(out, *labels_value);
             out.append(",");
@@ -561,9 +632,9 @@ void TentMetrics::serializeHistogramPrometheus(
             out.append(std::to_string(cumulative)).append("\n");
         }
 
-        // _sum: read from the parallel counter maintained alongside each
-        // observe() call. Falls back to 0 if the combo is not yet in the
-        // counter (should not happen for active combos, but defensive).
+        // _sum: read from the sum counter maintained by each observe() call.
+        // Falls back to 0 if the combo is not yet in the counter (should not
+        // happen for active combos, but defensive).
         int64_t total_sum = 0;
         auto it = sum_by_combo.find(combo_key(*labels_value));
         if (it != sum_by_combo.end()) {
@@ -579,6 +650,29 @@ void TentMetrics::serializeHistogramPrometheus(
     }
 }
 
+void TentMetrics::serializeGaugePrometheus(
+    metrics::CachedDynamicCounter<1>& gauge, std::string& out) const {
+    auto cells = gauge.copy();
+    if (cells.empty()) return;
+    const std::string& name = gauge.str_name();
+    out.append("# HELP ")
+        .append(name)
+        .append(" ")
+        .append(gauge.help())
+        .append("\n");
+    out.append("# TYPE ").append(name).append(" gauge\n");
+    for (auto& e : cells) {
+        out.append(name)
+            .append("{")
+            .append(gauge.labels_name()[0])
+            .append("=\"")
+            .append(e->label[0])
+            .append("\"} ")
+            .append(std::to_string(e->value.load(std::memory_order_relaxed)))
+            .append("\n");
+    }
+}
+
 std::string TentMetrics::getJsonMetrics() {
     if (!initialized_) return "{}";
 
@@ -607,30 +701,30 @@ std::string TentMetrics::getJsonMetrics() {
             sumCounterValues(&transport_attempt_failures_total_);
         root[deadline_infeasible_total_.str_name()] =
             sumCounterValues(&deadline_infeasible_total_);
+        root[quarantined_batches_total_.str_name()] =
+            static_cast<int64_t>(quarantined_batches_total_.value());
+
+        // Gauges: aggregate across transport labels (total in-flight attempts
+        // / total registered bytes). Per-transport breakdown is via the
+        // Prometheus endpoint.
+        root[inflight_attempts_.str_name()] =
+            sumCounterValues(&inflight_attempts_);
+        root[registered_buffer_bytes_.str_name()] =
+            sumCounterValues(&registered_buffer_bytes_);
 
         // Histograms: sum bucket counts across all transport labels. The
-        // templated helper also reads back the parallel sum counter so the
+        // templated helper also reads back the histogram's sum counter so the
         // JSON endpoint emits "sum" alongside "count" (and stays in sync with
         // the Prometheus endpoint).
-        serializeHistogramToJson(root, &read_latency_, kLatencyBuckets,
-                                 &read_latency_sum_);
-        serializeHistogramToJson(root, &write_latency_, kLatencyBuckets,
-                                 &write_latency_sum_);
-        serializeHistogramToJson(root, &read_size_, kSizeBuckets,
-                                 &read_size_sum_);
-        serializeHistogramToJson(root, &write_size_, kSizeBuckets,
-                                 &write_size_sum_);
-        serializeHistogramToJson(root, &deadline_mlu_, kMluPerMilleBuckets,
-                                 &deadline_mlu_sum_);
-        serializeHistogramToJson(root, &stage_queue_wait_, kStageBuckets,
-                                 &stage_queue_wait_sum_);
-        serializeHistogramToJson(root, &stage_dispatch_, kStageBuckets,
-                                 &stage_dispatch_sum_);
-        serializeHistogramToJson(root, &stage_transport_, kStageBuckets,
-                                 &stage_transport_sum_);
-        serializeHistogramToJson(root, &transport_attempt_latency_,
-                                 kLatencyBuckets,
-                                 &transport_attempt_latency_sum_);
+        serializeHistogramToJson(root, read_latency_);
+        serializeHistogramToJson(root, write_latency_);
+        serializeHistogramToJson(root, read_size_);
+        serializeHistogramToJson(root, write_size_);
+        serializeHistogramToJson(root, deadline_mlu_);
+        serializeHistogramToJson(root, stage_queue_wait_);
+        serializeHistogramToJson(root, stage_dispatch_);
+        serializeHistogramToJson(root, stage_transport_);
+        serializeHistogramToJson(root, transport_attempt_latency_);
 
         return root.dump(2);  // Pretty print with 2-space indent
     } catch (const std::exception& e) {
@@ -679,7 +773,9 @@ std::string TentMetrics::getSummaryString() {
         << "Write: " << formatBytes(write_bytes) << " ("
         << static_cast<uint64_t>(write_reqs) << " reqs, "
         << static_cast<uint64_t>(write_fails) << " fails) | "
-        << "Failovers: " << static_cast<uint64_t>(failovers);
+        << "Failovers: " << static_cast<uint64_t>(failovers)
+        << " | Quarantined batches: "
+        << static_cast<uint64_t>(quarantined_batches_total_.value());
 
     return oss.str();
 }
@@ -708,6 +804,11 @@ void TentMetrics::recordTransportAttemptFinished(TransportType, Request::OpCode,
                                                  TransferStatusEnum, double) {}
 void TentMetrics::recordDeadlineMLU(TransportType, double) {}
 void TentMetrics::recordDeadlineInfeasible(TransportType) {}
+void TentMetrics::recordBatchQuarantined() {}
+void TentMetrics::recordTaskFailure(TransportType, TaskFailureReason) {}
+void TentMetrics::recordInflightAttemptStarted(TransportType) {}
+void TentMetrics::recordInflightAttemptFinished(TransportType) {}
+void TentMetrics::recordRegisteredBufferBytes(TransportType, int64_t) {}
 void TentMetrics::recordStageLatency(Stage, TransportType, double) {}
 
 std::string TentMetrics::getPrometheusMetrics() {
diff --git a/mooncake-transfer-engine/tent/src/platform/CMakeLists.txt b/mooncake-transfer-engine/tent/src/platform/CMakeLists.txt
index 11b7bbd9ac..d66e13290a 100644
--- a/mooncake-transfer-engine/tent/src/platform/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/platform/CMakeLists.txt
@@ -3,6 +3,7 @@ add_subdirectory(rocm)
 add_subdirectory(ascend)
 add_subdirectory(sunrise)
 add_subdirectory(tpu)
+add_subdirectory(xpu)
 
 file(GLOB PLATFORM_SOURCES "*.cpp")
 add_library(tent_platform_all STATIC ${PLATFORM_SOURCES})
@@ -22,3 +23,6 @@ endif()
 if(TARGET platform_tpu)
   target_link_libraries(tent_platform_all PUBLIC platform_tpu)
 endif()
+if(TARGET platform_xpu)
+  target_link_libraries(tent_platform_all PUBLIC platform_xpu)
+endif()
diff --git a/mooncake-transfer-engine/tent/src/platform/ascend/CMakeLists.txt b/mooncake-transfer-engine/tent/src/platform/ascend/CMakeLists.txt
index 508a4c6828..7a382ab284 100644
--- a/mooncake-transfer-engine/tent/src/platform/ascend/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/platform/ascend/CMakeLists.txt
@@ -1,10 +1,30 @@
-if (USE_ASCEND OR USE_ASCEND_DIRECT)
-    file(GLOB TENT_PLATFORM_ASCEND_SOURCES "*.cpp")
-    add_library(platform_ascend STATIC ${TENT_PLATFORM_ASCEND_SOURCES})
-    target_link_libraries(platform_ascend PUBLIC tent_common ascendcl)
+if(USE_ASCEND OR USE_ASCEND_DIRECT)
+  file(GLOB TENT_PLATFORM_ASCEND_SOURCES "*.cpp")
+  add_library(platform_ascend STATIC ${TENT_PLATFORM_ASCEND_SOURCES})
+  target_link_libraries(platform_ascend PUBLIC tent_common ascendcl)
+  if(USE_ASCEND_DIRECT OR USE_UBSHMEM)
+    # adxl::AdxlEngine::MallocMem / FreeMem live in llm_datadist (weak in
+    # adxl_compat.h). Keep this dependency out of classic USE_ASCEND builds.
+    target_link_libraries(platform_ascend PRIVATE llm_datadist)
 
-    install(TARGETS platform_ascend
-            ARCHIVE DESTINATION lib/platform
-            LIBRARY DESTINATION lib/platform
-            RUNTIME DESTINATION bin)
+    set(ACL_RUNTIME_HEADER_PATH "${ASCEND_INCLUDE_DIR}/acl/acl_rt.h")
+    if(EXISTS "${ACL_RUNTIME_HEADER_PATH}")
+      file(READ "${ACL_RUNTIME_HEADER_PATH}" ACL_RUNTIME_CONTENT)
+      if("${ACL_RUNTIME_CONTENT}" MATCHES "aclrtMemRetainAllocationHandle")
+        message(STATUS "TENT Ascend platform: fabric mem supported")
+        target_compile_definitions(platform_ascend
+                                   PRIVATE ASCEND_SUPPORT_FABRIC_MEM)
+      else()
+        message(STATUS "TENT Ascend platform: fabric mem not supported")
+      endif()
+    else()
+      message(WARNING "Acl runtime header file is not exist")
+    endif()
+  endif()
+
+  install(
+    TARGETS platform_ascend
+    ARCHIVE DESTINATION lib/platform
+    LIBRARY DESTINATION lib/platform
+    RUNTIME DESTINATION bin)
 endif()
diff --git a/mooncake-transfer-engine/tent/src/platform/ascend/ascend_allocator.cpp b/mooncake-transfer-engine/tent/src/platform/ascend/ascend_allocator.cpp
index b7bd61d608..54bf53ff84 100644
--- a/mooncake-transfer-engine/tent/src/platform/ascend/ascend_allocator.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/ascend/ascend_allocator.cpp
@@ -20,11 +20,176 @@
 #include <glog/logging.h>
 #include <acl/acl.h>
 
+#include <cstdlib>
+#include <cstring>
+#include <mutex>
+#include <unordered_map>
+
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+#include "transport/ascend_transport/ascend_direct_transport/adxl_compat.h"
+#endif
+
 namespace mooncake {
 namespace tent {
+namespace {
+
+bool WantFabricMem(const std::shared_ptr<Config>& conf,
+                   const MemoryOptions& options) {
+    if (!conf) {
+        return false;
+    }
+    LocationParser location(options.location);
+    if (location.type() == "npu") {
+        return false;
+    }
+    if (conf->get("transports/ascend_direct/fabric_mem", false)) {
+        return true;
+    }
+    if (!conf->get("transports/ascend_direct/store_te_init", false)) {
+        return false;
+    }
+    const char* env = std::getenv("ASCEND_ENABLE_USE_FABRIC_MEM");
+    return env && std::strcmp(env, "1") == 0;
+}
+
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+struct VmmRecord {
+    aclrtDrvMemHandle handle = nullptr;
+    bool is_adxl = false;
+};
+
+std::mutex g_vmm_mu;
+std::unordered_map<void*, VmmRecord> g_vmm_records;
+
+int AllocatePhysical(size_t total_size, aclrtDrvMemHandle& handle) {
+    int32_t user_dev_id = 0;
+    auto ret = aclrtGetDevice(&user_dev_id);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "Failed to get device: " << ret;
+        return -1;
+    }
+    int32_t physical_dev_id = 0;
+    ret = aclrtGetPhyDevIdByLogicDevId(user_dev_id, &physical_dev_id);
+    if (ret != ACL_ERROR_NONE) {
+        physical_dev_id = user_dev_id;
+    }
+    aclrtPhysicalMemProp prop{};
+    prop.handleType = ACL_MEM_HANDLE_TYPE_NONE;
+    prop.allocationType = ACL_MEM_ALLOCATION_TYPE_PINNED;
+    prop.memAttr = ACL_MEM_P2P_HUGE1G;
+    prop.location.type = ACL_MEM_LOCATION_TYPE_HOST_NUMA;
+    constexpr int32_t kDevicesPerChip = 4;
+    constexpr int32_t kNumaNodeStep = 2;
+    prop.location.id = (physical_dev_id / kDevicesPerChip) * kNumaNodeStep;
+    prop.reserve = 0;
+    ret = aclrtMallocPhysical(&handle, total_size, &prop, 0);
+    if (ret != ACL_ERROR_NONE) {
+        prop.location.type = ACL_MEM_LOCATION_TYPE_HOST;
+        prop.location.id = 0;
+        ret = aclrtMallocPhysical(&handle, total_size, &prop, 0);
+        if (ret != ACL_ERROR_NONE) {
+            prop.memAttr = ACL_MEM_P2P_HUGE;
+            ret = aclrtMallocPhysical(&handle, total_size, &prop, 0);
+            if (ret != ACL_ERROR_NONE) {
+                LOG(ERROR) << "Failed to allocate fabric physical memory: "
+                           << ret;
+                return -1;
+            }
+        }
+    }
+    return 0;
+}
+
+void* AllocateVmm(size_t total_size) {
+    aclrtDrvMemHandle handle = nullptr;
+    if (AllocatePhysical(total_size, handle) != 0) {
+        return nullptr;
+    }
+    void* va = nullptr;
+    auto ret = aclrtReserveMemAddress(&va, total_size, 0, nullptr, 1);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "Failed to reserve fabric memory: " << ret;
+        (void)aclrtFreePhysical(handle);
+        return nullptr;
+    }
+    ret = aclrtMapMem(va, total_size, 0, handle, 0);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "Failed to map fabric memory: " << ret;
+        (void)aclrtReleaseMemAddress(va);
+        (void)aclrtFreePhysical(handle);
+        return nullptr;
+    }
+    std::lock_guard<std::mutex> lock(g_vmm_mu);
+    g_vmm_records.emplace(va, VmmRecord{handle, false});
+    return va;
+}
+
+// Prefer adxl::MallocMem when the weak symbol is present. Failure does not
+// fall back to ACL VMM — same contract as classic TE allocate_fabric_exact.
+void* AllocateFabric(size_t total_size) {
+    if (&adxl::AdxlEngine::MallocMem != nullptr) {
+        void* va = nullptr;
+        auto status = adxl::AdxlEngine::MallocMem(adxl::MemType::MEM_HOST,
+                                                  total_size, &va);
+        if (status != adxl::SUCCESS) {
+            LOG(ERROR) << "Failed to allocate fabric memory, errmsg: "
+                       << aclGetRecentErrMsg();
+            return nullptr;
+        }
+        LOG(INFO) << "Call adxl MallocMem suc, va:" << va
+                  << ", size:" << total_size;
+        std::lock_guard<std::mutex> lock(g_vmm_mu);
+        g_vmm_records.emplace(va, VmmRecord{nullptr, true});
+        return va;
+    }
+    return AllocateVmm(total_size);
+}
+
+bool FreeVmm(void* ptr) {
+    std::unique_lock<std::mutex> lock(g_vmm_mu);
+    auto it = g_vmm_records.find(ptr);
+    if (it == g_vmm_records.end()) {
+        return false;
+    }
+    const VmmRecord record = it->second;
+    g_vmm_records.erase(it);
+    lock.unlock();
+    if (record.is_adxl) {
+        if (&adxl::AdxlEngine::FreeMem != nullptr) {
+            auto status = adxl::AdxlEngine::FreeMem(ptr);
+            if (status != adxl::SUCCESS) {
+                LOG(ERROR) << "Failed to free fabric memory, errmsg: "
+                           << aclGetRecentErrMsg();
+            }
+        }
+        return true;
+    }
+    (void)aclrtUnmapMem(ptr);
+    (void)aclrtReleaseMemAddress(ptr);
+    (void)aclrtFreePhysical(record.handle);
+    return true;
+}
+#endif
+
+}  // namespace
+
 Status AscendPlatform::allocate(void** pptr, size_t size,
                                 MemoryOptions& options) {
     LocationParser location(options.location);
+    if (WantFabricMem(conf, options)) {
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+        *pptr = AllocateFabric(size);
+        if (!(*pptr)) {
+            return Status::InternalError(
+                "Unable to allocate fabric host memory" LOC_MARK);
+        }
+        return Status::OK();
+#else
+        return Status::InternalError(
+            "Fabric mem mode is not supported, please upgrade Ascend HDK and "
+            "CANN." LOC_MARK);
+#endif
+    }
     if (location.type() == "npu") {
         int deviceLogicId = 0;
         CHECK_ASCEND(aclrtGetDevice(&deviceLogicId));
@@ -40,6 +205,11 @@ Status AscendPlatform::allocate(void** pptr, size_t size,
 }
 
 Status AscendPlatform::free(void* ptr, size_t size) {
+#ifdef ASCEND_SUPPORT_FABRIC_MEM
+    if (FreeVmm(ptr)) {
+        return Status::OK();
+    }
+#endif
     aclrtPtrAttributes attributes;
     CHECK_ASCEND(aclrtPointerGetAttributes(ptr, &attributes));
     if (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
@@ -51,6 +221,12 @@ Status AscendPlatform::free(void* ptr, size_t size) {
 }
 
 Status AscendPlatform::copy(void* dst, void* src, size_t length) {
+    // Unlike CUDA/ROCm, the copy is not routed to the device owning the
+    // buffer; aclrtMemcpy runs in the caller thread's ACL context. Routing it
+    // needs a driver-id -> user-id lookup ACL does not expose: location.id is
+    // a driver id, aclrtSetDevice takes an ASCEND_RT_VISIBLE_DEVICES user id.
+    // TODO: left to someone with Ascend expertise and NPU hardware to verify;
+    // getting that id mapping wrong picks the wrong device silently.
     CHECK_ASCEND(aclrtMemcpy(dst, length, src, length, ACL_MEMCPY_DEFAULT));
     return Status::OK();
 }
diff --git a/mooncake-transfer-engine/tent/src/platform/ascend/ascend_probe.cpp b/mooncake-transfer-engine/tent/src/platform/ascend/ascend_probe.cpp
index 416690ba5c..f6eb236b43 100644
--- a/mooncake-transfer-engine/tent/src/platform/ascend/ascend_probe.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/ascend/ascend_probe.cpp
@@ -185,7 +185,12 @@ const std::vector<RangeLocation> AscendPlatform::getLocation(
         return entries;
     }
     if (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
-        entries.push_back({(uint64_t)start, len, "npu:0"});
+        int device_id = 0;
+        if (aclrtGetDevice(&device_id) != ACL_ERROR_NONE) {
+            device_id = 0;
+        }
+        entries.push_back(
+            {(uint64_t)start, len, "npu:" + std::to_string(device_id)});
         return entries;
     } else if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
         entries.push_back({(uint64_t)start, len, "cpu:0"});
diff --git a/mooncake-transfer-engine/tent/src/platform/cpu_allocator.cpp b/mooncake-transfer-engine/tent/src/platform/cpu_allocator.cpp
index e7926b2b40..b431c5193e 100644
--- a/mooncake-transfer-engine/tent/src/platform/cpu_allocator.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/cpu_allocator.cpp
@@ -22,9 +22,9 @@ namespace mooncake {
 namespace tent {
 Status CpuPlatform::allocate(void** pptr, size_t size, MemoryOptions& options) {
     LocationParser location(options.location);
-    if (location.type() == "cuda") {
+    if (location.type() == "cuda" || isAmdGpuLocationType(location.type())) {
         return Status::NotImplemented(
-            "CUDA not supported in cpu platform" LOC_MARK);
+            "GPU locations are not supported in cpu platform" LOC_MARK);
     }
     int socket_id = 0;
     if (location.type() == "cpu") socket_id = location.index();
diff --git a/mooncake-transfer-engine/tent/src/platform/cuda/cuda_allocator.cpp b/mooncake-transfer-engine/tent/src/platform/cuda/cuda_allocator.cpp
index d60ddffa2f..7701bd82c3 100644
--- a/mooncake-transfer-engine/tent/src/platform/cuda/cuda_allocator.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/cuda/cuda_allocator.cpp
@@ -13,15 +13,48 @@
 // limitations under the License.
 
 #include "tent/platform/cuda.h"
+#include "tent/platform/cuda_utils.h"
 #include "tent/common/status.h"
 
 #include <bits/stdint-uintn.h>
+#include <cuda.h>
 #include <cuda_runtime.h>
-#include <numa.h>
 #include <glog/logging.h>
+#include <mutex>
+#include <numa.h>
+#include <vector>
+#include <cstring>
 
 namespace mooncake {
 namespace tent {
+namespace {
+
+// Driver-API probe: true iff this process already has a primary context on
+// `device`. Does not create one. Topology lists every visible GPU for NIC
+// affinity; cudaSetDevice on those names would allocate idle-card contexts
+// when the process can see more GPUs than this rank uses.
+bool cudaPrimaryContextIsActive(int device) {
+    if (!ensureCudaDriverInit()) return false;
+    CUdevice cu_dev = 0;
+    if (cuDeviceGet(&cu_dev, device) != CUDA_SUCCESS) return false;
+    unsigned int flags = 0;
+    int active = 0;
+    if (cuDevicePrimaryCtxGetState(cu_dev, &flags, &active) != CUDA_SUCCESS) {
+        return false;
+    }
+    return active != 0;
+}
+
+// Bare cudaGetDevice() can implicitly create GPU 0 when this thread has no
+// current context. Only save/restore the caller's device when one exists.
+bool cudaHasCurrentContext() {
+    if (!ensureCudaDriverInit()) return false;
+    CUcontext ctx = nullptr;
+    return cuCtxGetCurrent(&ctx) == CUDA_SUCCESS && ctx != nullptr;
+}
+
+}  // namespace
+
 Status CudaPlatform::allocate(void** pptr, size_t size,
                               MemoryOptions& options) {
     LocationParser location(options.location);
@@ -42,15 +75,10 @@ Status CudaPlatform::allocate(void** pptr, size_t size,
 }
 
 Status CudaPlatform::free(void* ptr, size_t size) {
-    cudaPointerAttributes attributes;
-    CHECK_CUDA(cudaPointerGetAttributes(&attributes, ptr));
-    if (attributes.type == cudaMemoryTypeDevice) {
+    if (getCudaDeviceForPtr(ptr) >= 0) {
         CHECK_CUDA(cudaFree(ptr));
-    } else if (attributes.type == cudaMemoryTypeHost ||
-               attributes.type == cudaMemoryTypeUnregistered) {
-        numa_free(ptr, size);
     } else {
-        LOG(ERROR) << "Unknown memory type, " << ptr << " " << attributes.type;
+        numa_free(ptr, size);
     }
     return Status::OK();
 }
@@ -60,11 +88,94 @@ Status CudaPlatform::copy(void* dst, void* src, size_t length) {
     // as the latter relies on the legacy default stream and can introduce
     // unintended synchronization or even deadlocks in downstream
     // components (e.g. mooncake-pg).
+    //
+    // cudaMemcpyAsync routes the copy through its stream's device context, so
+    // the stream must live on the device owning the device-side buffer.
+    // Control-plane RPC worker threads sit on cuda:0 while a registered buffer
+    // may live on cuda:R; taking the stream from the buffer's device routes the
+    // copy correctly without mutating the calling thread's current device.
+    // Host-only copies keep the current device.
+    int device_id = getPointerDeviceId(dst);
+    if (device_id == CUDAStreamPool::kCurrentDevice) {
+        device_id = getPointerDeviceId(src);
+    }
+    if (device_id == CUDAStreamPool::kCurrentDevice) {
+        // Host-to-host: plain memcpy. The stream pool would create a primary
+        // context on the thread's default device (GPU 0).
+        ::memcpy(dst, src, length);
+        return Status::OK();
+    }
+
+    // cudaMemcpyAsync() validates the stream against the current device's
+    // context; pin the buffer's device for the copy and restore the caller's
+    // binding only when the thread already had a context.
+    int saved_device = 0;
+    const bool have_saved =
+        cudaHasCurrentContext() && cudaGetDevice(&saved_device) == cudaSuccess;
+    if (!have_saved) (void)cudaGetLastError();
+
+    CHECK_CUDA(cudaSetDevice(device_id));
     CUDAStreamHandle stream;
-    CHECK_STATUS(getStreamFromPool(stream));
+    CHECK_STATUS(getStreamFromPool(stream, device_id));
     CHECK_CUDA(
         cudaMemcpyAsync(dst, src, length, cudaMemcpyDefault, stream.get()));
     CHECK_CUDA(cudaStreamSynchronize(stream.get()));
+    if (have_saved) {
+        CHECK_CUDA(cudaSetDevice(saved_device));
+    }
+    return Status::OK();
+}
+
+Status CudaPlatform::synchronizeDevices(const Topology* topology) {
+    const std::vector<int> devices =
+        topologyDeviceIndices(topology, Topology::MEM_CUDA);
+    if (devices.empty()) return Status::OK();
+
+    int device_count = 0;
+    cudaError_t err = cudaGetDeviceCount(&device_count);
+    if (err != cudaSuccess || device_count <= 0) {
+        if (err != cudaSuccess) {
+            LOG(WARNING) << "CudaPlatform::synchronizeDevices "
+                            "cudaGetDeviceCount failed: "
+                         << cudaGetErrorString(err);
+            (void)cudaGetLastError();
+        }
+        return Status::OK();
+    }
+
+    int saved = 0;
+    const bool have_saved =
+        cudaHasCurrentContext() && cudaGetDevice(&saved) == cudaSuccess;
+    if (!have_saved) (void)cudaGetLastError();
+
+    for (int device : devices) {
+        if (device >= device_count) continue;
+        if (!cudaPrimaryContextIsActive(device)) continue;
+        err = cudaSetDevice(device);
+        if (err != cudaSuccess) {
+            LOG(WARNING) << "CudaPlatform::synchronizeDevices cudaSetDevice("
+                         << device << ") failed: " << cudaGetErrorString(err);
+            (void)cudaGetLastError();
+            continue;
+        }
+        err = cudaDeviceSynchronize();
+        if (err != cudaSuccess) {
+            LOG(WARNING)
+                << "CudaPlatform::synchronizeDevices cudaDeviceSynchronize "
+                   "device "
+                << device << " failed: " << cudaGetErrorString(err);
+            (void)cudaGetLastError();
+        }
+    }
+    if (have_saved) {
+        err = cudaSetDevice(saved);
+        if (err != cudaSuccess) {
+            LOG(WARNING)
+                << "CudaPlatform::synchronizeDevices restore cudaSetDevice("
+                << saved << ") failed: " << cudaGetErrorString(err);
+            (void)cudaGetLastError();
+        }
+    }
     return Status::OK();
 }
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/src/platform/cuda/cuda_probe.cpp b/mooncake-transfer-engine/tent/src/platform/cuda/cuda_probe.cpp
index 6a52601c9a..8cba5d290d 100644
--- a/mooncake-transfer-engine/tent/src/platform/cuda/cuda_probe.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/cuda/cuda_probe.cpp
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "tent/platform/cuda.h"
+#include "tent/platform/cuda_utils.h"
 #include "tent/common/status.h"
 #include "tent/common/utils/prefault.h"
 #include "tent/common/utils/random.h"
@@ -299,15 +300,17 @@ bool cudaAbiMatches() {
 MemoryType CudaPlatform::getMemoryType(void* addr) {
     if (!cudaDevicePresent()) return MTYPE_CPU;
     if (!cudaAbiMatches()) return MTYPE_UNKNOWN;
-    cudaPointerAttributes attributes{};
-    cudaError_t result = cudaPointerGetAttributes(&attributes, addr);
-    if (result != cudaSuccess) {
-        LOG(WARNING) << "cudaPointerGetAttributes: "
-                     << cudaGetErrorString(result);
-        return MTYPE_UNKNOWN;
+    return getCudaDeviceForPtr(addr) >= 0 ? MTYPE_CUDA : MTYPE_CPU;
+}
+
+int CudaPlatform::getPointerDeviceId(void* addr) {
+    // Same guards as getMemoryType().
+    if (!cudaDevicePresent() || !cudaAbiMatches()) {
+        return CUDAStreamPool::kCurrentDevice;
     }
-    if (attributes.type == cudaMemoryTypeDevice) return MTYPE_CUDA;
-    return MTYPE_CPU;
+    int device = getCudaDeviceForPtr(addr);
+    if (device < 0) return CUDAStreamPool::kCurrentDevice;
+    return device;
 }
 
 static inline uintptr_t alignPage(uintptr_t address) {
@@ -336,17 +339,11 @@ const std::vector<RangeLocation> CudaPlatform::getLocation(void* start,
         return entries;
     }
     if (cudaDevicePresent()) {
-        cudaPointerAttributes attributes{};
-        cudaError_t result = cudaPointerGetAttributes(&attributes, start);
-        if (result != cudaSuccess) {
-            LOG(WARNING) << "cudaPointerGetAttributes: "
-                         << cudaGetErrorString(result);
-            entries.push_back({(uint64_t)start, len, kWildcardLocation});
-            return entries;
-        }
-        if (attributes.type == cudaMemoryTypeDevice) {
+        // Unregistered pointers fall through to the NUMA probe below.
+        int cuda_dev = getCudaDeviceForPtr(start);
+        if (cuda_dev >= 0) {
             entries.push_back(
-                {(uint64_t)start, len, genCudaNodeName(attributes.device)});
+                {(uint64_t)start, len, genCudaNodeName(cuda_dev)});
             return entries;
         }
     }
diff --git a/mooncake-transfer-engine/tent/src/platform/rocm/rocm_allocator.cpp b/mooncake-transfer-engine/tent/src/platform/rocm/rocm_allocator.cpp
index 11aa5bc251..da53cee9ee 100644
--- a/mooncake-transfer-engine/tent/src/platform/rocm/rocm_allocator.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/rocm/rocm_allocator.cpp
@@ -18,6 +18,7 @@
 #include <hip/hip_runtime.h>
 #include <numa.h>
 #include <glog/logging.h>
+#include <vector>
 
 namespace mooncake {
 namespace tent {
@@ -25,7 +26,7 @@ namespace tent {
 Status RocmPlatform::allocate(void** pptr, size_t size,
                               MemoryOptions& options) {
     LocationParser location(options.location);
-    if (location.type() == "rocm") {
+    if (isAmdGpuLocationType(location.type())) {
         int hip_dev = 0;
         CHECK_HIP(hipGetDevice(&hip_dev));
         CHECK_HIP(hipSetDevice(location.index()));
@@ -56,12 +57,74 @@ Status RocmPlatform::free(void* ptr, size_t size) {
 }
 
 Status RocmPlatform::copy(void* dst, void* src, size_t length) {
+    // hipMemcpyAsync routes the copy through its stream's device context, so
+    // the stream must live on the device owning the device-side buffer.
+    // Control-plane RPC worker threads sit on device 0 while a registered
+    // buffer may live on device R; taking the stream from the buffer's device
+    // routes the copy correctly without mutating the calling thread's current
+    // device. Host-only copies keep the current device.
+    int device_id = getPointerDeviceId(dst);
+    if (device_id == HIPStreamPool::kCurrentDevice) {
+        device_id = getPointerDeviceId(src);
+    }
+
     HIPStreamHandle stream;
-    CHECK_STATUS(getStreamFromPool(stream));
+    CHECK_STATUS(getStreamFromPool(stream, device_id));
     CHECK_HIP(hipMemcpyAsync(dst, src, length, hipMemcpyDefault, stream.get()));
     CHECK_HIP(hipStreamSynchronize(stream.get()));
     return Status::OK();
 }
 
+Status RocmPlatform::synchronizeDevices(const Topology* topology) {
+    const std::vector<int> devices =
+        topologyDeviceIndices(topology, Topology::MEM_ROCM);
+    if (devices.empty()) return Status::OK();
+
+    int device_count = 0;
+    hipError_t err = hipGetDeviceCount(&device_count);
+    if (err != hipSuccess || device_count <= 0) {
+        if (err != hipSuccess) {
+            LOG(WARNING) << "RocmPlatform::synchronizeDevices "
+                            "hipGetDeviceCount failed: "
+                         << hipGetErrorString(err);
+            (void)hipGetLastError();
+        }
+        return Status::OK();
+    }
+
+    int saved = 0;
+    const bool have_saved = hipGetDevice(&saved) == hipSuccess;
+    if (!have_saved) (void)hipGetLastError();
+
+    for (int device : devices) {
+        if (device >= device_count) continue;
+        err = hipSetDevice(device);
+        if (err != hipSuccess) {
+            LOG(WARNING) << "RocmPlatform::synchronizeDevices hipSetDevice("
+                         << device << ") failed: " << hipGetErrorString(err);
+            (void)hipGetLastError();
+            continue;
+        }
+        err = hipDeviceSynchronize();
+        if (err != hipSuccess) {
+            LOG(WARNING)
+                << "RocmPlatform::synchronizeDevices hipDeviceSynchronize "
+                   "device "
+                << device << " failed: " << hipGetErrorString(err);
+            (void)hipGetLastError();
+        }
+    }
+    if (have_saved) {
+        err = hipSetDevice(saved);
+        if (err != hipSuccess) {
+            LOG(WARNING)
+                << "RocmPlatform::synchronizeDevices restore hipSetDevice("
+                << saved << ") failed: " << hipGetErrorString(err);
+            (void)hipGetLastError();
+        }
+    }
+    return Status::OK();
+}
+
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/platform/rocm/rocm_probe.cpp b/mooncake-transfer-engine/tent/src/platform/rocm/rocm_probe.cpp
index 2e5bc762db..50f6de1bf1 100644
--- a/mooncake-transfer-engine/tent/src/platform/rocm/rocm_probe.cpp
+++ b/mooncake-transfer-engine/tent/src/platform/rocm/rocm_probe.cpp
@@ -194,7 +194,7 @@ static void discoverRocmTopology(std::vector<Topology::NicEntry>& nic_list,
         }
 
         Topology::MemEntry entry;
-        entry.name = "rocm:" + std::to_string(i);
+        entry.name = makeAmdGpuLocation(i);
         entry.numa_node = numa_node;
         entry.pci_bus_id = pci_bus_id;
         entry.type = Topology::MEM_ROCM;
@@ -263,6 +263,20 @@ MemoryType RocmPlatform::getMemoryType(void* addr) {
     return MTYPE_CPU;
 }
 
+int RocmPlatform::getPointerDeviceId(void* addr) {
+    hipPointerAttribute_t attributes{};
+    if (hipPointerGetAttributes(&attributes, addr) != hipSuccess) {
+        // Clear the latched error so it cannot surface at an unrelated
+        // hipGetLastError() call site.
+        hipGetLastError();
+        return HIPStreamPool::kCurrentDevice;
+    }
+    if (attributes.type != hipMemoryTypeDevice) {
+        return HIPStreamPool::kCurrentDevice;
+    }
+    return attributes.device;
+}
+
 static inline uintptr_t alignPage(uintptr_t address) {
     const static size_t kPageSize = 4096;
     return address & ~(kPageSize - 1);
@@ -274,7 +288,7 @@ static inline std::string genCpuNodeName(int node) {
 }
 
 static inline std::string genRocmNodeName(int node) {
-    if (node >= 0) return "rocm:" + std::to_string(node);
+    if (node >= 0) return makeAmdGpuLocation(node);
     return kWildcardLocation;
 }
 
diff --git a/mooncake-transfer-engine/tent/src/platform/xpu/CMakeLists.txt b/mooncake-transfer-engine/tent/src/platform/xpu/CMakeLists.txt
new file mode 100644
index 0000000000..a3b8f1671d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/platform/xpu/CMakeLists.txt
@@ -0,0 +1,13 @@
+if(USE_XPU)
+  file(GLOB TENT_PLATFORM_XPU_SOURCES "*.cpp")
+  add_library(platform_xpu STATIC ${TENT_PLATFORM_XPU_SOURCES})
+  target_link_libraries(platform_xpu PUBLIC tent_common)
+
+  # Native / direct-link SYCL: these sources include <sycl/sycl.hpp> and call
+  # libsycl directly, so they must be compiled by the Intel DPC++ compiler
+  # (icpx) with -fsycl. common.cmake enforces that CMAKE_CXX_COMPILER is a SYCL
+  # compiler when USE_XPU=ON. -fsycl is PUBLIC so every target that links
+  # platform_xpu also links libsycl and runs the SYCL device-link step.
+  target_compile_options(platform_xpu PUBLIC -fsycl)
+  target_link_options(platform_xpu PUBLIC -fsycl)
+endif()
diff --git a/mooncake-transfer-engine/tent/src/platform/xpu/xpu_platform.cpp b/mooncake-transfer-engine/tent/src/platform/xpu/xpu_platform.cpp
new file mode 100644
index 0000000000..3bef3806d0
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/platform/xpu/xpu_platform.cpp
@@ -0,0 +1,155 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// This translation unit links SYCL directly and therefore MUST be compiled by
+// the Intel DPC++ compiler (icpx / clang with -fsycl); see xpu_sycl_backend.h.
+
+#include "tent/platform/xpu.h"
+
+#include <glog/logging.h>
+
+#include <string>
+
+#include "tent/common/status.h"
+#include "xpu_sycl_backend.h"
+
+namespace mooncake {
+namespace tent {
+
+namespace {
+// The SYCL backend is created and initialized lazily on first use. init() is
+// idempotent and cheap after the first call.
+XpuSyclBackend& backend() {
+    XpuSyclBackend& be = XpuSyclBackend::instance();
+    be.init();
+    return be;
+}
+}  // namespace
+
+Status XpuPlatform::probe(std::vector<Topology::NicEntry>& nic_list,
+                          std::vector<Topology::MemEntry>& mem_list) {
+    // Host DRAM + RDMA topology is identical to a CPU host.
+    CHECK_STATUS(CpuPlatform::probe(nic_list, mem_list));
+
+    // Register one memory node per visible XPU device so findNearMem("xpu:N")
+    // resolves to the nearest host NUMA node for staging. Device I/O never
+    // touches the NIC directly in the MVP, so these entries only carry NIC
+    // affinity used to place the host staging buffers.
+    auto& be = backend();
+    int device_count = be.deviceCount();
+    for (int i = 0; i < device_count; ++i) {
+        Topology::MemEntry entry;
+        entry.name = "xpu:" + std::to_string(i);
+        entry.numa_node = be.deviceNumaNode(i);
+        entry.type = Topology::MEM_UNKNOWN;
+        int nic_id = 0;
+        for (const auto& nic : nic_list) {
+            if (entry.numa_node >= 0 && nic.numa_node == entry.numa_node)
+                entry.device_list[0].push_back(nic_id);
+            else
+                entry.device_list[2].push_back(nic_id);
+            nic_id++;
+        }
+        mem_list.push_back(std::move(entry));
+    }
+    return Status::OK();
+}
+
+Status XpuPlatform::allocate(void** pptr, size_t size, MemoryOptions& options) {
+    LocationParser location(options.location);
+    // A bare "xpu" location has no ':' and therefore parses as the wildcard
+    // type, so match the raw string as well and treat it as device 0.
+    const bool bare_xpu = options.location == "xpu";
+    if (bare_xpu || location.type() == "xpu") {
+        // XPU VRAM is allocated via sycl::malloc_device.
+        int device_index;
+        if (bare_xpu) {
+            device_index = 0;
+        } else if (location.index() >= 0) {
+            device_index = location.index();
+        } else {
+            // "xpu:<garbage>" -- a malformed ordinal must not silently fall
+            // back to device 0.
+            return Status::InvalidArgument(
+                "XPU location has a malformed device ordinal: " +
+                options.location + LOC_MARK);
+        }
+        if (backend().allocDevice(pptr, size, device_index) != 0)
+            return Status::InternalError(
+                "XPU device allocation failed" LOC_MARK);
+        return Status::OK();
+    }
+    // Host DRAM staging buffers use the inherited NUMA-aware allocator.
+    return CpuPlatform::allocate(pptr, size, options);
+}
+
+Status XpuPlatform::free(void* ptr, size_t size) {
+    auto& be = backend();
+    if (be.isDevicePtr(ptr)) {
+        if (be.freeDevice(ptr) != 0)
+            return Status::InternalError("XPU device free failed" LOC_MARK);
+        return Status::OK();
+    }
+    return CpuPlatform::free(ptr, size);
+}
+
+Status XpuPlatform::copy(void* dst, void* src, size_t length) {
+    auto& be = backend();
+    bool src_is_device = be.isDevicePtr(src);
+    bool dst_is_device = be.isDevicePtr(dst);
+    if (src_is_device && dst_is_device) {
+        return Status::NotImplemented(
+            "XpuPlatform: device-to-device copy is not supported in the MVP; "
+            "transfers are staged through host DRAM" LOC_MARK);
+    }
+    if (src_is_device) {
+        if (be.copyD2H(dst, src, length) != 0)
+            return Status::InternalError(
+                "XPU device->host copy failed" LOC_MARK);
+        return Status::OK();
+    }
+    if (dst_is_device) {
+        if (be.copyH2D(dst, src, length) != 0)
+            return Status::InternalError(
+                "XPU host->device copy failed" LOC_MARK);
+        return Status::OK();
+    }
+    // Neither side is XPU memory: plain host copy.
+    return CpuPlatform::copy(dst, src, length);
+}
+
+MemoryType XpuPlatform::getMemoryType(void* addr) {
+    // USM device memory is classified whether it was allocated through this
+    // platform or externally (e.g. a PyTorch XPU tensor registered via
+    // registerLocalMemory); see XpuSyclBackend::classifyLocked.
+    if (backend().isDevicePtr(addr)) return MTYPE_XPU;
+    return CpuPlatform::getMemoryType(addr);
+}
+
+const std::vector<RangeLocation> XpuPlatform::getLocation(void* start,
+                                                          size_t len,
+                                                          bool skip_prefault) {
+    auto& be = backend();
+    if (be.isDevicePtr(start)) {
+        int index = be.deviceIndex(start);
+        std::string location =
+            index >= 0 ? "xpu:" + std::to_string(index) : kWildcardLocation;
+        return {RangeLocation{reinterpret_cast<uint64_t>(start), len,
+                              std::move(location)}};
+    }
+    return CpuPlatform::getLocation(start, len, skip_prefault);
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/platform/xpu/xpu_sycl_backend.h b/mooncake-transfer-engine/tent/src/platform/xpu/xpu_sycl_backend.h
new file mode 100644
index 0000000000..5c194e9990
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/platform/xpu/xpu_sycl_backend.h
@@ -0,0 +1,266 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Real oneAPI SYCL backend for the Intel XPU platform.
+//
+// USE_XPU is a direct-link (native) build: XpuPlatform calls this backend
+// directly and libsycl is linked into the binary -- there is no dlopen shim and
+// no C ABI boundary. Because this header includes <sycl/sycl.hpp>, every
+// translation unit that pulls it in MUST be compiled by the Intel DPC++
+// compiler (icpx / clang with -fsycl); plain g++ cannot parse the SYCL headers.
+// It is therefore a private header of platform_xpu (kept under src/, not the
+// public include tree) and is included only by xpu_platform.cpp.
+//
+// Device selection prefers Intel GPUs but falls back to any available SYCL
+// device (e.g. the OpenCL CPU runtime shipped in the oneAPI images), so the USM
+// alloc/copy path is exercisable even on a host with no Intel GPU.
+
+#ifndef TENT_SRC_PLATFORM_XPU_SYCL_BACKEND_H_
+#define TENT_SRC_PLATFORM_XPU_SYCL_BACKEND_H_
+
+#include <sycl/sycl.hpp>
+
+#include <cstddef>
+#include <cstdint>
+#include <mutex>
+#include <optional>
+#include <vector>
+
+namespace mooncake {
+namespace tent {
+
+// Minimal USM-device backend with an interior-pointer registry.
+//
+// Two classification paths are combined:
+//  1. Allocations made through this backend are tracked in a [base, base+size)
+//    interval registry, so interior addresses (staging hands the backend
+//    base + chunk_offset) resolve without touching the SYCL runtime.
+//  2. Anything else is classified with sycl::get_pointer_type against the
+//    platform default context. That is the context PyTorch's XPU allocator
+//    uses (device.get_platform().ext_oneapi_get_default_context()), so a
+//    PyTorch XPU tensor handed to registerLocalMemory is recognised as device
+//    memory and can be copied. Queues are created on that same default
+//    context so queue::memcpy on foreign USM is legal. Only usm::alloc::device
+//    is reported as device memory; host/shared USM is host-accessible and is
+//    treated as ordinary host memory.
+//
+// Every method returns 0 on success and non-zero on failure (classification
+// helpers return bool / an ordinal); XpuPlatform maps these to Status.
+class XpuSyclBackend {
+   public:
+    static XpuSyclBackend &instance() {
+        // Intentionally leaked: SYCL queues/contexts must not be destroyed
+        // during static teardown, after the SYCL runtime may already be gone.
+        static XpuSyclBackend *g = new XpuSyclBackend();
+        return *g;
+    }
+
+    // Enumerate devices and build one in-order queue per device on the
+    // platform default context. Idempotent.
+    int init() {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (initialized_) return 0;
+        try {
+            // Only keep devices that support USM device allocations; a device
+            // that lacks this aspect would make probe() advertise an XPU memory
+            // node whose every subsequent allocation then fails.
+            auto usable = [](const sycl::device &d) {
+                return d.has(sycl::aspect::usm_device_allocations);
+            };
+            std::vector<sycl::device> devices;
+            for (const auto &d : sycl::device::get_devices()) {
+                if (d.is_gpu() && usable(d)) devices.push_back(d);
+            }
+            if (devices.empty()) {
+                // No usable Intel GPU visible -- fall back to any device that
+                // still supports USM device allocations (e.g. the OpenCL CPU
+                // runtime shipped in the oneAPI images) so the USM path stays
+                // exercisable.
+                for (const auto &d : sycl::device::get_devices()) {
+                    if (usable(d)) devices.push_back(d);
+                }
+            }
+            if (devices.empty()) return 1;
+            for (auto &d : devices) {
+                sycl::context ctx =
+                    d.get_platform().ext_oneapi_get_default_context();
+                bool known = false;
+                for (const auto &c : contexts_) {
+                    if (c == ctx) {
+                        known = true;
+                        break;
+                    }
+                }
+                if (!known) contexts_.push_back(ctx);
+                queues_.emplace_back(ctx, d, sycl::property::queue::in_order());
+            }
+            initialized_ = true;
+            return 0;
+        } catch (const sycl::exception &) {
+            // Leave no partially-built state: a later init() retry must start
+            // from an empty queue list, not resume with duplicate ordinals.
+            queues_.clear();
+            contexts_.clear();
+            return 1;
+        }
+    }
+
+    int allocDevice(void **pptr, size_t size, int device_index) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!initialized_ || device_index < 0 ||
+            device_index >= static_cast<int>(queues_.size()) || !pptr)
+            return 1;
+        try {
+            void *p = sycl::malloc_device(size, queues_[device_index]);
+            if (!p) return 1;
+            allocs_.push_back(
+                Alloc{reinterpret_cast<uintptr_t>(p), size, device_index});
+            *pptr = p;
+            return 0;
+        } catch (const sycl::exception &) {
+            return 1;
+        }
+    }
+
+    int freeDevice(void *ptr) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!ptr) return 1;
+        const uintptr_t addr = reinterpret_cast<uintptr_t>(ptr);
+        for (size_t i = 0; i < allocs_.size(); ++i) {
+            if (allocs_[i].base == addr) {
+                try {
+                    sycl::free(ptr, queues_[allocs_[i].device]);
+                } catch (const sycl::exception &) {
+                    return 1;
+                }
+                allocs_.erase(allocs_.begin() + i);
+                return 0;
+            }
+        }
+        return 1;  // not a base pointer we handed out
+    }
+
+    bool isDevicePtr(const void *addr) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return classifyLocked(addr) >= 0;
+    }
+
+    int deviceIndex(const void *addr) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return classifyLocked(addr);
+    }
+
+    int copyD2H(void *host_dst, const void *device_src, size_t len) {
+        return copy(host_dst, device_src, len, /*to_host=*/true);
+    }
+
+    int copyH2D(void *device_dst, const void *host_src, size_t len) {
+        return copy(device_dst, host_src, len, /*to_host=*/false);
+    }
+
+    int deviceCount() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return static_cast<int>(queues_.size());
+    }
+
+    // NUMA affinity of the device's PCIe root. Returning -1 means "unknown",
+    // which the topology layer treats as "not cross-NUMA" (isCrossNuma), so
+    // staging still works -- just without NUMA-local placement of the host
+    // bounce buffer. A real value would come from the device's PCI address
+    // (Intel's pci_address device-info extension) resolved against
+    // /sys/bus/pci/devices/<bdf>/numa_node; that lookup is deferred.
+    int deviceNumaNode(int /*index*/) { return -1; }
+
+   private:
+    struct Alloc {
+        uintptr_t base;
+        size_t size;
+        int device;
+    };
+
+    // Resolve an address (base or interior) to its owning allocation.
+    const Alloc *findLocked(const void *addr) const {
+        const uintptr_t a = reinterpret_cast<uintptr_t>(addr);
+        for (const auto &al : allocs_) {
+            if (a >= al.base && a < al.base + al.size) return &al;
+        }
+        return nullptr;
+    }
+
+    // Device ordinal owning `addr`, or -1 when it is not USM device memory.
+    // Own allocations resolve through the registry; anything else is asked of
+    // the SYCL runtime against every default context we hold.
+    int classifyLocked(const void *addr) const {
+        if (const Alloc *a = findLocked(addr)) return a->device;
+        for (const auto &ctx : contexts_) {
+            try {
+                if (sycl::get_pointer_type(addr, ctx) !=
+                    sycl::usm::alloc::device)
+                    continue;
+                sycl::device owner = sycl::get_pointer_device(addr, ctx);
+                for (size_t i = 0; i < queues_.size(); ++i) {
+                    if (queues_[i].get_device() == owner)
+                        return static_cast<int>(i);
+                }
+                // Device memory on a GPU we did not enumerate: still device
+                // memory; the context is shared, so device 0's queue can copy.
+                return 0;
+            } catch (const sycl::exception &) {
+                // Not a pointer this context knows about.
+            }
+        }
+        return -1;
+    }
+
+    int copy(void *dst, const void *src, size_t len, bool to_host) {
+        // Validate and resolve the target queue under the lock, but run the
+        // blocking memcpy().wait() outside it so copies on different devices
+        // are not serialized against one another. queues_ is only appended
+        // during init() and never erased, so the queue handle stays valid after
+        // the lock is released.
+        std::optional<sycl::queue> q;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            const void *dev = to_host ? src : dst;
+            const Alloc *a = findLocked(dev);
+            int device_index;
+            if (a) {
+                const uintptr_t start = reinterpret_cast<uintptr_t>(dev);
+                if (start + len > a->base + a->size) return 1;  // runs past end
+                device_index = a->device;
+            } else {
+                device_index = classifyLocked(dev);
+                if (device_index < 0) return 1;  // not device memory
+            }
+            q = queues_[device_index];
+        }
+        try {
+            q->memcpy(dst, src, len).wait();
+            return 0;
+        } catch (const sycl::exception &) {
+            return 1;
+        }
+    }
+
+    std::mutex mu_;
+    bool initialized_ = false;
+    std::vector<sycl::context> contexts_;
+    std::vector<sycl::queue> queues_;
+    std::vector<Alloc> allocs_;
+};
+
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // TENT_SRC_PLATFORM_XPU_SYCL_BACKEND_H_
diff --git a/mooncake-transfer-engine/tent/src/python/CMakeLists.txt b/mooncake-transfer-engine/tent/src/python/CMakeLists.txt
index 5d8ea378b0..73a137e9b4 100644
--- a/mooncake-transfer-engine/tent/src/python/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/python/CMakeLists.txt
@@ -27,3 +27,13 @@ find_package(
   REQUIRED)
 target_include_directories(tentpy PRIVATE ${Python3_INCLUDE_DIRS})
 target_link_libraries(tentpy PUBLIC tent_link_group)
+
+if(BUILD_UNIT_TESTS)
+  add_test(
+    NAME tent_python_guards_test
+    COMMAND
+      ${CMAKE_COMMAND} -E env "PYTHONPATH=$<TARGET_FILE_DIR:tentpy>"
+      "LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/mooncake-common:$<TARGET_FILE_DIR:tent_metrics>:$ENV{LD_LIBRARY_PATH}"
+      ${Python3_EXECUTABLE}
+      ${CMAKE_CURRENT_SOURCE_DIR}/../../tests/test_python_guards.py)
+endif()
diff --git a/mooncake-transfer-engine/tent/src/python/pybind.cpp b/mooncake-transfer-engine/tent/src/python/pybind.cpp
index 6c81c90aff..de20b549f2 100644
--- a/mooncake-transfer-engine/tent/src/python/pybind.cpp
+++ b/mooncake-transfer-engine/tent/src/python/pybind.cpp
@@ -29,6 +29,19 @@
 namespace py = pybind11;
 using namespace mooncake::tent;
 
+// The enumerators below are exposed to Python as plain integers, so their
+// values are a compatibility contract shared with the C API macros. Pin them
+// here so that any divergence is a build failure instead of a protocol break
+// that only shows up between mismatched peers.
+static_assert(static_cast<int>(TransportType::UB) == TRANSPORT_UB,
+              "UB wire value must match the C API macro");
+static_assert(static_cast<int>(TransportType::MPCOMM) == TRANSPORT_MPCOMM,
+              "MPCOMM wire value must match the C API macro");
+static_assert(static_cast<int>(TransportType::HP_TCP) == TRANSPORT_HP_TCP,
+              "HP_TCP wire value must match the C API macro");
+static_assert(static_cast<int>(TransportType::XPU) == TRANSPORT_XPU,
+              "XPU wire value must match the C API macro");
+
 // =============================================================================
 // Custom Exception Hierarchy
 // =============================================================================
@@ -86,6 +99,7 @@ static void ThrowStatus(const Status& s, const char* where) {
         case Status::Code::kMetadataError:
             throw MetadataError(full_msg);
         case Status::Code::kRpcServiceError:
+        case Status::Code::kRpcConnectionError:
             throw RpcServiceError(full_msg);
         case Status::Code::kNotImplemented:
             throw NotImplementedError(full_msg);
@@ -302,6 +316,9 @@ PYBIND11_MODULE(tent, m) {
         .value("SUNRISE_LINK", TransportType::SUNRISE_LINK)
         .value("TPU", TransportType::TPU)
         .value("UB", TransportType::UB)
+        .value("MPCOMM", TransportType::MPCOMM)
+        .value("HP_TCP", TransportType::HP_TCP)
+        .value("XPU", TransportType::XPU)
         .export_values();
 
     py::enum_<IntentType>(m, "IntentType")
@@ -408,7 +425,6 @@ PYBIND11_MODULE(tent, m) {
         .def("__exit__", [](MemoryGuard& self, py::args) {
             py::gil_scoped_release release;
             self.release();
-            return py::none();
         });
 
     py::class_<BatchGuard>(m, "BatchGuard")
@@ -420,7 +436,6 @@ PYBIND11_MODULE(tent, m) {
         .def("__exit__", [](BatchGuard& self, py::args) {
             py::gil_scoped_release release;
             self.release();
-            return py::none();
         });
 
     // -------------------------------------------------------------------------
@@ -436,6 +451,9 @@ PYBIND11_MODULE(tent, m) {
         .def("get_segment_name", &TransferEngine::getSegmentName)
         .def("get_rpc_server_address", &TransferEngine::getRpcServerAddress)
         .def("get_rpc_server_port", &TransferEngine::getRpcServerPort)
+        .def("get_local_topology", &TransferEngine::getLocalTopologyString,
+             "Dump local topology as native TENT JSON (nics/mems with "
+             "rank0/1/2)")
 
         // ---------------------------------------------------------------------
         // export/import: out param -> return
@@ -546,7 +564,8 @@ PYBIND11_MODULE(tent, m) {
                 ThrowStatus(s, "allocate_memory_guard");
                 return std::make_unique<MemoryGuard>(&self, addr, size);
             },
-            py::arg("size"), py::arg("location") = kWildcardLocation)
+            py::arg("size"), py::arg("location") = kWildcardLocation,
+            py::keep_alive<0, 1>())
 
         .def(
             "allocate_memory_guard_ex",
@@ -558,7 +577,7 @@ PYBIND11_MODULE(tent, m) {
                 ThrowStatus(s, "allocate_memory_guard_ex");
                 return std::make_unique<MemoryGuard>(&self, addr, size);
             },
-            py::arg("size"), py::arg("options"))
+            py::arg("size"), py::arg("options"), py::keep_alive<0, 1>())
 
         // ---------------------------------------------------------------------
         // register/unregister single
@@ -663,7 +682,7 @@ PYBIND11_MODULE(tent, m) {
                 }
                 return std::make_unique<BatchGuard>(&self, batch_id);
             },
-            py::arg("batch_size"))
+            py::arg("batch_size"), py::keep_alive<0, 1>())
 
         // ---------------------------------------------------------------------
         // submitTransfer overloads
diff --git a/mooncake-transfer-engine/tent/src/rpc/rpc.cpp b/mooncake-transfer-engine/tent/src/rpc/rpc.cpp
index e1721188ae..569b4aefca 100644
--- a/mooncake-transfer-engine/tent/src/rpc/rpc.cpp
+++ b/mooncake-transfer-engine/tent/src/rpc/rpc.cpp
@@ -16,6 +16,8 @@
 #include <glog/logging.h>
 #include <async_simple/executors/SimpleExecutor.h>
 
+#include <stdexcept>
+
 #include "transfer_engine_rpc_client_io_context.h"
 #include "tent/common/utils/ip.h"
 #include "tent/common/utils/random.h"
@@ -43,29 +45,52 @@ struct RpcHandlerScope {
 
 class ClientPool {
    public:
-    std::unique_ptr<coro_rpc_client> acquire() {
+    struct Lease {
+        std::unique_ptr<coro_rpc_client> client;
+        // Which generation the client was drawn from. Flushing is keyed on
+        // this: see clearIfCurrent().
+        uint64_t generation = 0;
+    };
+
+    Lease acquire() {
         std::lock_guard<std::mutex> guard(lock_);
         if (!idle_clients_.empty()) {
             auto client = std::move(idle_clients_.back());
             idle_clients_.pop_back();
-            return client;
+            return Lease{std::move(client), generation_};
         }
-        return nullptr;
+        return Lease{nullptr, generation_};
     }
 
+    // A client is only released after a call succeeded on it, which proves it
+    // is alive, so it goes back regardless of which generation it came from.
     void release(std::unique_ptr<coro_rpc_client> client) {
         if (!client) return;
         std::lock_guard<std::mutex> guard(lock_);
         idle_clients_.push_back(std::move(client));
     }
 
+    // Drop every idle client, but only on behalf of a caller that is still
+    // looking at the generation it drew from. Several callers notice a peer
+    // restart at once; without this, the second one to fail would throw away
+    // the connections the first one has already re-established, and the pool
+    // would churn for as long as stale clients keep surfacing.
+    void clearIfCurrent(uint64_t generation) {
+        std::lock_guard<std::mutex> guard(lock_);
+        if (generation != generation_) return;
+        ++generation_;
+        idle_clients_.clear();
+    }
+
     void clear() {
         std::lock_guard<std::mutex> guard(lock_);
+        ++generation_;
         idle_clients_.clear();
     }
 
    private:
     std::mutex lock_;
+    uint64_t generation_ = 0;
     std::vector<std::unique_ptr<coro_rpc_client>> idle_clients_;
 };
 
@@ -87,25 +112,27 @@ CoroRpcAgent::CoroRpcAgent() = default;
 
 CoroRpcAgent::~CoroRpcAgent() { stop(); }
 
-Status CoroRpcAgent::registerFunction(int func_id, const Function& func) {
-    func_map_mutex_.lock();
-    func_map_[func_id] = func;
-    func_map_mutex_.unlock();
+Status CoroRpcAgent::registerFunction(int func_id, const Function& func,
+                                      bool offload) {
+    std::lock_guard<std::mutex> guard(func_map_mutex_);
+    func_map_[func_id] = Handler{func, offload};
     return Status::OK();
 }
 
-Status CoroRpcAgent::start(uint16_t& port, bool ipv6) {
+Status CoroRpcAgent::start(uint16_t& port, bool ipv6, size_t threads) {
     const static uint16_t kStartPort = 15000;
     const static uint16_t kPortRange = 2000;
     const static int kMaxRetry = 10;
     if (running_)
         return Status::InvalidArgument("RPC server already started" LOC_MARK);
     easylog::set_min_severity(easylog::Severity::FATAL);
+    if (threads > 1)
+        LOG(INFO) << "CoroRpcAgent: RPC server threads set to " << threads;
     for (int retry = 0; retry < kMaxRetry; ++retry) {
         try {
             if (port == 0)
                 port = kStartPort + SimpleRandom::Get().next(kPortRange);
-            server_ = new coro_rpc::coro_rpc_server(kRpcThreads, port,
+            server_ = new coro_rpc::coro_rpc_server(threads, port,
                                                     ipv6 ? "::" : "0.0.0.0");
             server_->register_handler<&CoroRpcAgent::process>(this);
             server_->async_start();
@@ -145,16 +172,43 @@ Status CoroRpcAgent::stop() {
     return Status::OK();
 }
 
-void CoroRpcAgent::process(int func_id) {
-    RpcHandlerScope handler_scope(tl_inside_rpc_handler);
-    auto ctx = coro_rpc::get_context();
-    if (func_map_.count(func_id)) {
-        auto request = ctx->get_request_attachment();
-        std::string response;
-        auto func = func_map_.at(func_id);
-        func(request, response);
-        ctx->set_response_attachment(response);
+Lazy<void> CoroRpcAgent::process(int func_id) {
+    auto* ctx = co_await coro_rpc::get_context_in_coro();
+    // registerFunction() may run while the server is serving, and a rehash
+    // under a bare find() is a data race. The handler is copied out and the
+    // lock released before the coroutine can suspend below.
+    Handler handler;
+    {
+        std::lock_guard<std::mutex> guard(func_map_mutex_);
+        auto it = func_map_.find(func_id);
+        if (it == func_map_.end()) {
+            throw std::runtime_error("Unknown TENT RPC function: " +
+                                     std::to_string(func_id));
+        }
+        handler = it->second;
+    }
+
+    auto request = ctx->get_request_attachment();
+    std::string response;
+    if (handler.offload) {
+        // Suspends this coroutine, freeing the io_context thread. The request
+        // buffer belongs to the context_info this coroutine keeps alive, so
+        // the view survives the hop. tl_inside_rpc_handler is deliberately
+        // not set: it guards against deadlocking the RPC thread, which an
+        // offloaded handler no longer occupies.
+        //
+        // post() reports a throwing handler through the Try instead of
+        // unwinding, so rethrow here: the router turns that into the same
+        // rpc_throw_exception an inline handler would produce. Dropping it
+        // would answer a malformed request with an empty success.
+        auto result =
+            co_await coro_io::post([&] { handler.func(request, response); });
+        result.value();
+    } else {
+        RpcHandlerScope handler_scope(tl_inside_rpc_handler);
+        handler.func(request, response);
     }
+    ctx->set_response_attachment(std::move(response));
 }
 
 std::shared_ptr<ClientPool> CoroRpcAgent::getOrCreatePool(
@@ -167,6 +221,26 @@ std::shared_ptr<ClientPool> CoroRpcAgent::getOrCreatePool(
     return it->second;
 }
 
+namespace {
+
+// True when the failure came back from the peer as a reply, which means the
+// connection carried a full round trip and is still usable. Every other
+// failure leaves the connection in an unknown state.
+bool peerAnswered(coro_rpc::errc ec) {
+    switch (ec) {
+        case coro_rpc::errc::rpc_throw_exception:
+        case coro_rpc::errc::function_not_registered:
+        case coro_rpc::errc::invalid_rpc_arguments:
+        case coro_rpc::errc::invalid_rpc_result:
+        case coro_rpc::errc::message_too_large:
+            return true;
+        default:
+            return false;
+    }
+}
+
+}  // namespace
+
 Lazy<std::pair<Status, std::string>> CoroRpcAgent::callCoroutine(
     std::string server_addr, int func_id, std::string request) {
     if (tl_inside_rpc_handler) {
@@ -177,7 +251,10 @@ Lazy<std::pair<Status, std::string>> CoroRpcAgent::callCoroutine(
     }
 
     auto pool = getOrCreatePool(server_addr);
-    ClientLease lease{pool->acquire(), pool, false};
+    auto acquired = pool->acquire();
+    const uint64_t generation = acquired.generation;
+    ClientLease lease{std::move(acquired.client), pool, false};
+    const bool from_pool = lease.client != nullptr;
 
     if (!lease.client) {
         lease.client = std::make_unique<coro_rpc_client>(
@@ -188,7 +265,7 @@ Lazy<std::pair<Status, std::string>> CoroRpcAgent::callCoroutine(
             auto msg = "Failed to connect RPC server. server: " + server_addr +
                        ", func_id: " + std::to_string(func_id) +
                        ", message: " + std::string{conn_result.message()};
-            co_return std::make_pair(Status::RpcServiceError(msg + LOC_MARK),
+            co_return std::make_pair(Status::RpcConnectionError(msg + LOC_MARK),
                                      "");
         }
     }
@@ -199,14 +276,32 @@ Lazy<std::pair<Status, std::string>> CoroRpcAgent::callCoroutine(
 
     if (!call_result.has_value()) {
         lease.broken = true;
+        // An idle pooled connection only learns that its peer restarted when
+        // it is next used, and every other connection pooled for that peer is
+        // just as stale. Discarding only this one leaves the rest to fail the
+        // same way, one wasted attempt each, and callers above get few
+        // attempts: TcpTransport allows max_retry_count, so a peer that is
+        // already back up can still fail a transfer outright. Drop the whole
+        // pool instead, so the next attempt starts from a fresh connection.
+        //
+        // Only for failures that leave the connection unusable. If the peer
+        // answered -- a handler exception, an unknown function id, a rejected
+        // argument -- the socket is fine, and so are the connections the other
+        // callers of this address are holding.
+        if (from_pool && !peerAnswered(call_result.error().code)) {
+            pool->clearIfCurrent(generation);
+        }
         auto msg = "Failed to call RPC function. server: " + server_addr +
                    ", func_id: " + std::to_string(func_id) +
                    ", message: " + std::string{call_result.error().msg};
         co_return std::make_pair(Status::RpcServiceError(msg + LOC_MARK), "");
     }
 
-    std::string response{lease->get_resp_attachment()};
-    lease->release_resp_attachment();
+    // The internal buffer is padded for small attachments; trim the moved
+    // string to the real attachment length from the view.
+    const size_t len = lease->get_resp_attachment().size();
+    std::string response = lease->release_resp_attachment();
+    response.resize(len);
 
     co_return std::make_pair(Status::OK(), std::move(response));
 }
@@ -223,6 +318,17 @@ Status CoroRpcAgent::call(const std::string& server_addr, int func_id,
     return status;
 }
 
+Status CoroRpcAgent::callOwned(const std::string& server_addr, int func_id,
+                               std::string request, std::string& response) {
+    auto [status, resp] = async_simple::coro::syncAwait(
+        callCoroutine(server_addr, func_id, std::move(request)));
+
+    if (status.ok()) {
+        response = std::move(resp);
+    }
+    return status;
+}
+
 void CoroRpcAgent::callAsync(const std::string& server_addr, int func_id,
                              const std::string& request,
                              AsyncCallback callback) {
diff --git a/mooncake-transfer-engine/tent/src/runtime/CMakeLists.txt b/mooncake-transfer-engine/tent/src/runtime/CMakeLists.txt
index 53f2dbc26a..3cd0b86c37 100644
--- a/mooncake-transfer-engine/tent/src/runtime/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/runtime/CMakeLists.txt
@@ -17,3 +17,13 @@ if (TARGET metastore_etcd)
 endif()
 
 target_link_libraries(tent_runtime PUBLIC tent_common tent_rpc tent_platform_all tent_transport_all tent_metrics)
+# The runtime references the Transfer Engine client I/O pool accessor
+# (mooncake::CreateRpcClientIoContextPool / mooncake::Environ) from the common
+# library. Declaring the dependency here keeps the shared library link ordered
+# correctly; otherwise libtent_shared.so is emitted with dangling undefined
+# symbols (Ubuntu's default --as-needed drops libmooncake_common.so because it
+# is placed before the archives that reference it), and consumers linking only
+# against libtent_shared.so (e.g. the NIXL Mooncake plugin) fail at load time.
+if(TARGET mooncake_common)
+  target_link_libraries(tent_runtime PUBLIC mooncake_common)
+endif()
diff --git a/mooncake-transfer-engine/tent/src/runtime/admission_queue.cpp b/mooncake-transfer-engine/tent/src/runtime/admission_queue.cpp
index ac8471b41d..74c19416ad 100644
--- a/mooncake-transfer-engine/tent/src/runtime/admission_queue.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/admission_queue.cpp
@@ -13,8 +13,10 @@
 // limitations under the License.
 
 #include "tent/runtime/admission_queue.h"
+#include "tent/runtime/deadline_mlu.h"
 
 #include <algorithm>
+#include <array>
 #include <chrono>
 #include <limits>
 #include <set>
@@ -285,21 +287,45 @@ std::vector<QueueOwnerId> LocalTransferAdmissionQueue::pickForDispatch(
         });
     }
 
-    // Predicted MLU = predicted_transfer_time / remaining_window. Returns true
-    // if the owner is predicted to miss its deadline hard enough to drop.
-    auto shouldDrop = [&](const QueueOwner& owner) -> bool {
+    // True if the owner is predicted to miss its deadline hard enough to
+    // drop, by the same DeadlineMlu the RDMA workers order QP slots with.
+    // `bytes_ahead`: eligible bytes dispatched and still in flight,
+    // including what this call already picked. No deadline or no bandwidth
+    // (<= 0) means nothing to predict from, so never a drop -- not even
+    // past the deadline; DeadlineMlu yields 0 there too, the explicit
+    // checks just keep the rule readable here.
+    //
+    // The rate stays per transport so transports that report their own
+    // bandwidth are not averaged into a process-wide aggregate, but the
+    // provider is resolved at most once per transport per scan: it reads live
+    // link state behind the transport lifecycle lock, and only RDMA and UB can
+    // carry degradation-eligible owners.
+    std::array<double, kSupportedTransportTypes> bandwidth_by_transport{};
+    std::array<bool, kSupportedTransportTypes> bandwidth_resolved{};
+    bandwidth_resolved.fill(false);
+    auto bandwidthFor = [&](TransportType type) -> double {
+        const int index = static_cast<int>(type);
+        if (index < 0 || index >= kSupportedTransportTypes) {
+            return transport_bandwidth_provider_
+                       ? transport_bandwidth_provider_(type)
+                       : bandwidth_provider_();
+        }
+        if (!bandwidth_resolved[index]) {
+            bandwidth_resolved[index] = true;
+            bandwidth_by_transport[index] =
+                transport_bandwidth_provider_
+                    ? transport_bandwidth_provider_(type)
+                    : bandwidth_provider_();
+        }
+        return bandwidth_by_transport[index];
+    };
+    auto shouldDrop = [&](const QueueOwner& owner, size_t bytes_ahead) {
         if (!drop_enabled || !owner.degradation_eligible) return false;
-        const double bw_bps =
-            transport_bandwidth_provider_
-                ? transport_bandwidth_provider_(owner.transport)
-                : bandwidth_provider_();
-        if (bw_bps <= 0.0) return false;
-        const uint64_t deadline_ns = owner.request.deadline_ns;
-        if (deadline_ns == 0) return false;      // no deadline
-        if (deadline_ns <= now_ns) return true;  // already past
-        const double window_s = (deadline_ns - now_ns) / 1e9;
-        const double predicted_time_s = owner.request.length / bw_bps;
-        const double mlu = predicted_time_s / window_s;
+        const double bw_bps = bandwidthFor(owner.transport);
+        if (owner.request.deadline_ns == 0 || bw_bps <= 0.0) return false;
+        const double mlu =
+            DeadlineMlu(bytes_ahead, owner.request.length,
+                        owner.request.deadline_ns, now_ns, bw_bps);
         return mlu >= limits_.mlu_local_threshold;
     };
 
@@ -336,7 +362,7 @@ std::vector<QueueOwnerId> LocalTransferAdmissionQueue::pickForDispatch(
         // dispatched) and does not consume the dispatch budget. Because the
         // queue is EDF-ordered, later owners have looser deadlines, so we keep
         // scanning rather than stopping.
-        if (shouldDrop(owner_it->second)) {
+        if (shouldDrop(owner_it->second, dispatching_bytes_)) {
             fifo_.pop_front();
             dropOwner(owner_id, owner_it->second);
             continue;
@@ -348,6 +374,8 @@ std::vector<QueueOwnerId> LocalTransferAdmissionQueue::pickForDispatch(
 
         fifo_.pop_front();
         owner_it->second.state = QueueState::Dispatching;
+        if (owner.degradation_eligible)
+            dispatching_bytes_ += owner.request.length;
         picked.push_back(owner_id);
         ++used_owners;
         used_bytes += owner.request.length;
@@ -375,6 +403,7 @@ Status LocalTransferAdmissionQueue::complete(
 
     owner.state = QueueState::Terminal;
     owner.terminal_status = terminal_status;
+    if (owner.degradation_eligible) dispatching_bytes_ -= owner.request.length;
     --outstanding_owners_;
     outstanding_bytes_ -= owner.request.length;
     if (owner.kind == QueueOwnerKind::User) {
@@ -498,5 +527,9 @@ size_t LocalTransferAdmissionQueue::outstandingBytes() const {
     return outstanding_bytes_;
 }
 
+size_t LocalTransferAdmissionQueue::dispatchingBytes() const {
+    return dispatching_bytes_;
+}
+
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/runtime/control_plane.cpp b/mooncake-transfer-engine/tent/src/runtime/control_plane.cpp
index 1dffe4e17e..29b2b6cd08 100644
--- a/mooncake-transfer-engine/tent/src/runtime/control_plane.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/control_plane.cpp
@@ -16,7 +16,9 @@
 #include "tent/runtime/transfer_engine_impl.h"
 
 #include <cassert>
+#include <exception>
 #include <set>
+#include <utility>
 
 #include "tent/common/status.h"
 #include "tent/common/utils/os.h"
@@ -25,12 +27,61 @@
 
 namespace mooncake {
 namespace tent {
+namespace {
+
+template <typename Fn>
+class CallbackInvocationGuard {
+   public:
+    explicit CallbackInvocationGuard(Fn on_exit)
+        : on_exit_(std::move(on_exit)) {}
+
+    ~CallbackInvocationGuard() { on_exit_(); }
+
+    CallbackInvocationGuard(const CallbackInvocationGuard&) = delete;
+    CallbackInvocationGuard& operator=(const CallbackInvocationGuard&) = delete;
+
+   private:
+    Fn on_exit_;
+};
+
+}  // namespace
+
+thread_local const ControlService* ControlService::active_bootstrap_service_ =
+    nullptr;
+thread_local const ControlService* ControlService::active_notify_service_ =
+    nullptr;
 thread_local CoroRpcAgent tl_rpc_agent;
 
 Status ControlClient::getSegmentDesc(const std::string& server_addr,
                                      std::string& response) {
     std::string request;
-    return tl_rpc_agent.call(server_addr, GetSegmentDesc, request, response);
+    auto status =
+        tl_rpc_agent.call(server_addr, GetSegmentDesc, request, response);
+    if (status.IsRpcServiceError()) {
+        // A failed stale connection is discarded by the RPC agent. Retry this
+        // read-only operation once; other control RPCs may have side effects.
+        return tl_rpc_agent.call(server_addr, GetSegmentDesc, request,
+                                 response);
+    }
+    return status;
+}
+
+Status ControlClient::decodeBootstrapResponse(const std::string& response_raw,
+                                              BootstrapDesc& response) {
+    try {
+        response = json::parse(response_raw).get<BootstrapDesc>();
+    } catch (const std::exception& e) {
+        return Status::MalformedJson(
+            std::string("Invalid bootstrap response: ") + e.what() + LOC_MARK);
+    }
+    if (!response.reply_msg.empty()) {
+        return Status::RpcServiceError(response.reply_msg);
+    }
+    if (response.local_gid.empty()) {
+        return Status::InvalidArgument(
+            "Missing peer GID in bootstrap" LOC_MARK);
+    }
+    return Status::OK();
 }
 
 Status ControlClient::bootstrap(const std::string& server_addr,
@@ -41,8 +92,7 @@ Status ControlClient::bootstrap(const std::string& server_addr,
     request_raw = j.dump();
     CHECK_STATUS(tl_rpc_agent.call(server_addr, BootstrapRdma, request_raw,
                                    response_raw));
-    response = json::parse(response_raw).get<BootstrapDesc>();
-    return Status::OK();
+    return decodeBootstrapResponse(response_raw, response);
 }
 
 Status ControlClient::bootstrapUb(const std::string& server_addr,
@@ -66,12 +116,29 @@ Status ControlClient::bootstrapUb(const std::string& server_addr,
 Status ControlClient::sendData(const std::string& server_addr,
                                uint64_t peer_mem_addr, void* local_mem_addr,
                                size_t length) {
-    std::string request, response;
+    // Check before addition/allocation or reading the caller's source buffer.
+    if (length > kTcpMaxWriteBytes)
+        return Status::InvalidArgument("TCP WRITE exceeds RPC payload limit");
+    std::string response;
     XferDataDesc desc{htole64(peer_mem_addr), htole64(length)};
-    request.resize(sizeof(XferDataDesc) + length);
-    memcpy(&request[0], &desc, sizeof(desc));
-    Platform::getLoader().copy(&request[sizeof(desc)], local_mem_addr, length);
-    auto status = tl_rpc_agent.call(server_addr, SendData, request, response);
+    std::string request;
+    request.reserve(sizeof(XferDataDesc) + length);
+    request.resize(sizeof(XferDataDesc));
+    memcpy(request.data(), &desc, sizeof(desc));
+    auto& loader = Platform::getLoader();
+    if (loader.getMemoryType(local_mem_addr) == MTYPE_CPU) {
+        // Single copy into the RPC attachment; avoids the resize() zero-fill
+        // and the extra copy in call().
+        request.append(reinterpret_cast<const char*>(local_mem_addr), length);
+    } else {
+        // resize() zero-fills the payload, so an unchecked copy failure would
+        // ship zeros that the peer stores successfully and reports COMPLETED.
+        request.resize(sizeof(XferDataDesc) + length);
+        CHECK_STATUS(
+            loader.copy(request.data() + sizeof(desc), local_mem_addr, length));
+    }
+    auto status = tl_rpc_agent.callOwned(server_addr, SendData,
+                                         std::move(request), response);
     if (!status.ok()) return status;
     if (!response.empty()) return Status::RpcServiceError(response);
     return Status::OK();
@@ -80,6 +147,8 @@ Status ControlClient::sendData(const std::string& server_addr,
 Status ControlClient::recvData(const std::string& server_addr,
                                uint64_t peer_mem_addr, void* local_mem_addr,
                                size_t length) {
+    if (length > kTcpMaxReadBytes)
+        return Status::InvalidArgument("TCP READ exceeds RPC payload limit");
     std::string request, response;
     XferDataDesc desc{htole64(peer_mem_addr), htole64(length)};
     request.resize(sizeof(XferDataDesc));
@@ -88,9 +157,8 @@ Status ControlClient::recvData(const std::string& server_addr,
     if (!status.ok()) return status;
     if (response.size() != length)
         return Status::RpcServiceError(
-            "RecvData failed: target address not in registered buffer");
-    Platform::getLoader().copy(local_mem_addr, response.data(), length);
-    return Status::OK();
+            response.empty() ? "RecvData failed: empty response" : response);
+    return Platform::getLoader().copy(local_mem_addr, response.data(), length);
 }
 
 inline void to_json(nlohmann::json& j, const Notification& n) {
@@ -149,6 +217,26 @@ Status ControlClient::delegate(const std::string& server_addr,
                                 : Status::RpcServiceError(response_raw);
 }
 
+void ControlClient::delegateAsync(const std::string& server_addr,
+                                  const Request& request,
+                                  DelegateCallback callback) {
+    json j = request;
+    std::string request_raw = j.dump();
+    tl_rpc_agent.callAsync(
+        server_addr, Delegate, request_raw,
+        [callback = std::move(callback)](Status status,
+                                         std::string response_raw) mutable {
+            if (!status.ok()) {
+                callback(std::move(status), false);
+                return;
+            }
+            callback(response_raw.empty()
+                         ? Status::OK()
+                         : Status::RpcServiceError(response_raw),
+                     true);
+        });
+}
+
 Status ControlClient::pinStageBuffer(const std::string& server_addr,
                                      const std::string& location,
                                      uint64_t& addr) {
@@ -171,6 +259,25 @@ Status ControlClient::unpinStageBuffer(const std::string& server_addr,
     return Status::OK();
 }
 
+void ControlClient::unpinStageBufferAsync(const std::string& server_addr,
+                                          uint64_t addr,
+                                          UnpinStageBufferCallback callback) {
+    json j = addr;
+    std::string request_raw = j.dump();
+    tl_rpc_agent.callAsync(
+        server_addr, Unpin, request_raw,
+        [callback = std::move(callback)](Status status,
+                                         std::string response_raw) mutable {
+            if (!status.ok()) {
+                callback(std::move(status));
+                return;
+            }
+            callback(response_raw.empty()
+                         ? Status::OK()
+                         : Status::RpcServiceError(response_raw));
+        });
+}
+
 ControlService::ControlService(const std::string& type,
                                const std::string& servers,
                                TransferEngineImpl* impl)
@@ -193,6 +300,10 @@ ControlService::ControlService(const std::string& type,
         [this](const std::string_view& request, std::string& response) {
             onBootstrapRdma(request, response);
         });
+    // SendData/RecvData copy the full TCP payload. Running them inline on the
+    // io_context serializes every bulk transfer and stalls Probe/Bootstrap
+    // on the same thread. Offload matches Delegate: the connection coroutine
+    // suspends, copies run on the blocking executor, and other RPCs proceed.
     rpc_server_->registerFunction(
         BootstrapUb,
         [this](const std::string_view& request, std::string& response) {
@@ -202,12 +313,14 @@ ControlService::ControlService(const std::string& type,
         SendData,
         [this](const std::string_view& request, std::string& response) {
             onSendData(request, response);
-        });
+        },
+        /*offload=*/true);
     rpc_server_->registerFunction(
         RecvData,
         [this](const std::string_view& request, std::string& response) {
             onRecvData(request, response);
-        });
+        },
+        /*offload=*/true);
     rpc_server_->registerFunction(
         Notify, [this](const std::string_view& request, std::string& response) {
             onNotify(request, response);
@@ -216,11 +329,14 @@ ControlService::ControlService(const std::string& type,
         Probe, [this](const std::string_view& request, std::string& response) {
             onProbe(request, response);
         });
+    // onDelegate runs a whole transfer to completion; holding the io_context
+    // thread for that long blocked every other RPC on this node.
     rpc_server_->registerFunction(
         Delegate,
         [this](const std::string_view& request, std::string& response) {
             onDelegate(request, response);
-        });
+        },
+        /*offload=*/true);
     rpc_server_->registerFunction(
         Pin, [this](const std::string_view& request, std::string& response) {
             onPinStageBuffer(request, response);
@@ -242,20 +358,68 @@ ControlService::ControlService(const std::string& type,
 }
 
 ControlService::~ControlService() {
-    // Registered RPC closures capture this. Stop and join the server while
-    // every callback and its synchronization primitive are still alive;
-    // relying on reverse member destruction would destroy them first.
-    if (rpc_server_) (void)rpc_server_->stop();
+    // Stop RPC workers while callback state and synchronization primitives are
+    // still alive. Member destruction would otherwise tear them down first.
     {
         std::lock_guard<std::mutex> lock(ub_bootstrap_callback_mutex_);
         ub_bootstrap_callback_ = {};
     }
-    bootstrap_callback_ = {};
-    notify_callback_ = {};
+    rpc_server_.reset();
 }
 
-Status ControlService::start(uint16_t& port, bool ipv6_) {
-    return rpc_server_->start(port, ipv6_);
+void ControlService::setBootstrapRdmaCallback(
+    const OnReceiveBootstrap& callback) {
+    std::unique_lock<std::mutex> guard(bootstrap_cb_mutex_);
+    if (active_bootstrap_service_ == this) {
+        bootstrap_callback_ = callback;
+        return;
+    }
+    bootstrap_callback_ = nullptr;
+    if (!bootstrap_cb_cv_.wait_for(guard, callback_drain_timeout_, [this] {
+            return bootstrap_callbacks_in_flight_ == 0;
+        })) {
+        LOG(ERROR)
+            << "Timed out waiting for BootstrapRdma callbacks to drain, "
+            << "in_flight=" << bootstrap_callbacks_in_flight_
+            << ", timeout_ms=" << callback_drain_timeout_.count()
+            << ". Continue replacing the callback to keep shutdown bounded.";
+    }
+    bootstrap_callback_ = callback;
+}
+
+void ControlService::setNotifyCallback(const OnNotify& callback) {
+    std::unique_lock<std::mutex> guard(notify_cb_mutex_);
+    if (active_notify_service_ == this) {
+        notify_callback_ = callback;
+        return;
+    }
+    notify_callback_ = nullptr;
+    if (!notify_cb_cv_.wait_for(guard, callback_drain_timeout_, [this] {
+            return notify_callbacks_in_flight_ == 0;
+        })) {
+        LOG(ERROR) << "Timed out waiting for Notify callbacks to drain, "
+                   << "in_flight=" << notify_callbacks_in_flight_
+                   << ", timeout_ms=" << callback_drain_timeout_.count()
+                   << ". Continue replacing the callback to keep shutdown "
+                   << "bounded.";
+    }
+    notify_callback_ = callback;
+}
+
+void ControlService::finishBootstrapCallback() {
+    std::lock_guard<std::mutex> guard(bootstrap_cb_mutex_);
+    --bootstrap_callbacks_in_flight_;
+    bootstrap_cb_cv_.notify_all();
+}
+
+void ControlService::finishNotifyCallback() {
+    std::lock_guard<std::mutex> guard(notify_cb_mutex_);
+    --notify_callbacks_in_flight_;
+    notify_cb_cv_.notify_all();
+}
+
+Status ControlService::start(uint16_t& port, bool ipv6_, size_t threads) {
+    return rpc_server_->start(port, ipv6_, threads);
 }
 
 void ControlService::onGetSegmentDesc(const std::string_view& request,
@@ -268,10 +432,46 @@ void ControlService::onGetSegmentDesc(const std::string_view& request,
 void ControlService::onBootstrapRdma(const std::string_view& request,
                                      std::string& response) {
     std::string mutable_request(request);
-    BootstrapDesc request_desc =
-        json::parse(std::string(request)).get<BootstrapDesc>();
+    OnReceiveBootstrap callback;
+    {
+        std::lock_guard<std::mutex> guard(bootstrap_cb_mutex_);
+        if (!bootstrap_callback_) {
+            BootstrapDesc response_desc;
+            response_desc.reply_msg = "NOT_READY: transport not initialized";
+            json j = response_desc;
+            response = j.dump();
+            return;
+        }
+        callback = bootstrap_callback_;
+        ++bootstrap_callbacks_in_flight_;
+    }
+
     BootstrapDesc response_desc;
-    if (bootstrap_callback_) bootstrap_callback_(request_desc, response_desc);
+    {
+        const ControlService* previous_service = active_bootstrap_service_;
+        active_bootstrap_service_ = this;
+        CallbackInvocationGuard invocation_guard([this, previous_service] {
+            active_bootstrap_service_ = previous_service;
+            finishBootstrapCallback();
+        });
+
+        try {
+            BootstrapDesc request_desc =
+                json::parse(mutable_request).get<BootstrapDesc>();
+            int rc = callback(request_desc, response_desc);
+            if (rc != 0 && response_desc.reply_msg.empty()) {
+                response_desc.reply_msg = "BootstrapRdma callback failed";
+            }
+        } catch (const std::exception& e) {
+            LOG(ERROR) << "onBootstrapRdma failed: " << e.what();
+            response_desc.reply_msg =
+                std::string("BootstrapRdma callback failed: ") + e.what();
+        } catch (...) {
+            LOG(ERROR) << "onBootstrapRdma failed with unknown exception";
+            response_desc.reply_msg = "BootstrapRdma callback failed";
+        }
+    }
+
     json j = response_desc;
     response = j.dump();
 }
@@ -319,13 +519,26 @@ void ControlService::onSendData(const std::string_view& request,
     auto length = le64toh(desc->length);
 
     // Validate request size to prevent buffer over-read
-    if (request.size() < sizeof(XferDataDesc) + length) {
+    if (length > kTcpMaxWriteBytes ||
+        length > request.size() - sizeof(XferDataDesc)) {
         response = "SendData failed: invalid request size";
         return;
     }
 
-    if (local_desc->findBuffer(peer_mem_addr, length)) {
-        Platform::getLoader().copy((void*)peer_mem_addr, &desc[1], length);
+    if (auto* buffer = local_desc->findBuffer(peer_mem_addr, length)) {
+        if (buffer->permission != kGlobalReadWrite) {
+            response = "SendData failed: remote write permission denied";
+            return;
+        }
+        auto status =
+            Platform::getLoader().copy((void*)peer_mem_addr, &desc[1], length);
+        if (!status.ok()) {
+            // A non-empty response is interpreted as an RPC error by the
+            // client (see ControlClient::sendData). Without this the sender's
+            // transfer would be reported COMPLETED even though the destination
+            // buffer was never written.
+            response = "SendData failed: copy: " + status.ToString();
+        }
     } else {
         response = "SendData failed: target address not in registered buffer";
     }
@@ -342,26 +555,70 @@ void ControlService::onRecvData(const std::string_view& request,
     auto peer_mem_addr = le64toh(desc->peer_mem_addr);
     auto length = le64toh(desc->length);
 
+    // The client accepts any response of exactly `length` bytes as payload (see
+    // ControlClient::recvData), so an error of that size must be padded or it
+    // would be copied into the caller's buffer and reported as success.
+    auto fail = [&response, length](std::string message) {
+        response = std::move(message);
+        if (response.size() == length) response.push_back(' ');
+    };
+
     // Validate length to prevent DoS via excessive memory allocation
-    constexpr size_t kMaxTransferSize = 1ULL << 30;  // 1GB max per RPC
-    if (length > kMaxTransferSize) {
-        response = "RecvData failed: length exceeds maximum allowed";
+    if (length > kTcpMaxReadBytes) {
+        fail("RecvData failed: length exceeds maximum allowed");
         return;
     }
 
-    if (local_desc->findBuffer(peer_mem_addr, length)) {
-        response.resize(length);
-        Platform::getLoader().copy(response.data(), (void*)peer_mem_addr,
-                                   length);
+    if (auto* buffer = local_desc->findBuffer(peer_mem_addr, length)) {
+        if (buffer->permission != kGlobalReadOnly &&
+            buffer->permission != kGlobalReadWrite) {
+            fail("RecvData failed: remote read permission denied");
+            return;
+        }
+        auto& loader = Platform::getLoader();
+        if (loader.getMemoryType((void*)peer_mem_addr) == MTYPE_CPU) {
+            // assign() skips the resize() zero-fill pass.
+            response.assign(reinterpret_cast<const char*>(peer_mem_addr),
+                            length);
+        } else {
+            response.resize(length);
+            auto status =
+                loader.copy(response.data(), (void*)peer_mem_addr, length);
+            if (!status.ok()) {
+                fail("RecvData failed: copy: " + status.ToString());
+            }
+        }
     } else {
-        response = "RecvData failed: target address not in registered buffer";
+        fail("RecvData failed: target address not in registered buffer");
     }
 }
 
 void ControlService::onNotify(const std::string_view& request,
                               std::string& response) {
-    Notification message = json::parse(request).get<Notification>();
-    if (notify_callback_) notify_callback_(message);
+    (void)response;
+    OnNotify callback;
+    {
+        std::lock_guard<std::mutex> guard(notify_cb_mutex_);
+        if (!notify_callback_) return;
+        callback = notify_callback_;
+        ++notify_callbacks_in_flight_;
+    }
+
+    const ControlService* previous_service = active_notify_service_;
+    active_notify_service_ = this;
+    CallbackInvocationGuard invocation_guard([this, previous_service] {
+        active_notify_service_ = previous_service;
+        finishNotifyCallback();
+    });
+
+    try {
+        Notification message = json::parse(request).get<Notification>();
+        callback(message);
+    } catch (const std::exception& e) {
+        LOG(ERROR) << "onNotify failed: " << e.what();
+    } catch (...) {
+        LOG(ERROR) << "onNotify failed with unknown exception";
+    }
 }
 
 void ControlService::onProbe(const std::string_view& request,
@@ -417,8 +674,11 @@ void ControlClient::subscribeSegmentUpdateAsync(
         server_addr, SubscribeSegmentUpdate, request,
         [](const Status& status, const std::string&) {
             if (!status.ok()) {
-                LOG(ERROR) << "SubscribeSegmentUpdate RPC failed with: "
-                           << status.ToString();
+                VLOG(1) << "SubscribeSegmentUpdate RPC failed with: "
+                        << status.ToString();
+                LOG_EVERY_N(ERROR, 100)
+                    << "SubscribeSegmentUpdate RPC failed with: "
+                    << status.ToString();
             }
         });
 }
diff --git a/mooncake-transfer-engine/tent/src/runtime/hp_tcp_transport_config.cpp b/mooncake-transfer-engine/tent/src/runtime/hp_tcp_transport_config.cpp
new file mode 100644
index 0000000000..0b5ddde268
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/runtime/hp_tcp_transport_config.cpp
@@ -0,0 +1,145 @@
+// Copyright 2026 KVCache.AI
+#include "tent/runtime/hp_tcp_transport_config.h"
+
+#include <limits>
+#include <string_view>
+
+namespace mooncake::tent {
+namespace {
+
+Status Invalid(const std::string& path, const std::string& detail) {
+    return Status::InvalidArgument(path + " " + detail + LOC_MARK);
+}
+
+template <typename T>
+Status ReadUnsigned(const json& object, std::string_view key, T* output) {
+    auto it = object.find(std::string(key));
+    if (it == object.end()) return Status::OK();
+    uint64_t value = 0;
+    if (it->is_number_unsigned()) {
+        value = it->get<uint64_t>();
+    } else if (it->is_number_integer()) {
+        const auto signed_value = it->get<int64_t>();
+        if (signed_value < 0) {
+            return Invalid("transports/hp_tcp/" + std::string(key),
+                           "must be non-negative");
+        }
+        value = static_cast<uint64_t>(signed_value);
+    } else {
+        return Invalid("transports/hp_tcp/" + std::string(key),
+                       "must be an integer");
+    }
+    if (value > std::numeric_limits<T>::max()) {
+        return Invalid("transports/hp_tcp/" + std::string(key),
+                       "is out of range");
+    }
+    *output = static_cast<T>(value);
+    return Status::OK();
+}
+
+Status ReadString(const json& object, std::string_view key,
+                  std::string* output) {
+    auto it = object.find(std::string(key));
+    if (it == object.end()) return Status::OK();
+    if (!it->is_string()) {
+        return Invalid("transports/hp_tcp/" + std::string(key),
+                       "must be a string");
+    }
+    *output = it->get<std::string>();
+    return Status::OK();
+}
+
+Status ReadStringList(const json& object, std::string_view key,
+                      std::vector<std::string>* output) {
+    auto it = object.find(std::string(key));
+    if (it == object.end()) return Status::OK();
+    if (!it->is_array()) {
+        return Invalid("transports/hp_tcp/" + std::string(key),
+                       "must be an array of strings");
+    }
+    for (const auto& item : *it) {
+        if (!item.is_string()) {
+            return Invalid("transports/hp_tcp/" + std::string(key),
+                           "must be an array of strings");
+        }
+        output->push_back(item.get<std::string>());
+    }
+    return Status::OK();
+}
+
+}  // namespace
+
+Status ParseHpTcpTransportConfig(const Config& config,
+                                 HpTcpTransportConfig* out) {
+    if (out == nullptr) {
+        return Status::InvalidArgument(
+            "HP TCP configuration output is null" LOC_MARK);
+    }
+
+    HpTcpTransportConfig parsed;
+    std::string subtree;
+    if (!config.dumpSubtree("transports/hp_tcp", &subtree)) {
+        *out = std::move(parsed);
+        return Status::OK();
+    }
+
+    json hp_tcp;
+    try {
+        hp_tcp = json::parse(subtree);
+    } catch (const std::exception& error) {
+        return Status::MalformedJson(
+            std::string("Invalid transports/hp_tcp configuration: ") +
+            error.what() + LOC_MARK);
+    }
+    if (!hp_tcp.is_object()) {
+        return Invalid("transports/hp_tcp", "must be an object");
+    }
+
+    if (auto it = hp_tcp.find("enable"); it != hp_tcp.end()) {
+        if (!it->is_boolean())
+            return Invalid("transports/hp_tcp/enable", "must be a boolean");
+        parsed.enabled = it->get<bool>();
+    }
+    CHECK_STATUS(
+        ReadString(hp_tcp, "bind_address", &parsed.params.bind_address));
+    CHECK_STATUS(ReadString(hp_tcp, "advertise_address",
+                            &parsed.params.advertise_address));
+    CHECK_STATUS(ReadStringList(hp_tcp, "rail_addresses",
+                                &parsed.params.rail_addresses));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "port", &parsed.params.port));
+    CHECK_STATUS(
+        ReadUnsigned(hp_tcp, "worker_count", &parsed.params.worker_count));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "connections_per_peer",
+                              &parsed.params.connections_per_peer));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "max_outstanding_tasks",
+                              &parsed.params.max_outstanding_tasks));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "max_outstanding_bytes",
+                              &parsed.params.max_outstanding_bytes));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "max_transfer_bytes",
+                              &parsed.params.max_transfer_bytes));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "connect_timeout_ms",
+                              &parsed.params.connect_timeout_ms));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "progress_timeout_ms",
+                              &parsed.params.progress_timeout_ms));
+    CHECK_STATUS(ReadUnsigned(hp_tcp, "idle_connection_timeout_ms",
+                              &parsed.params.idle_connection_timeout_ms));
+
+    const auto& hp = parsed.params;
+    if (parsed.enabled &&
+        (hp.worker_count == 0 || hp.connections_per_peer == 0 ||
+         hp.max_outstanding_tasks == 0 || hp.max_outstanding_bytes == 0 ||
+         hp.max_transfer_bytes == 0 || hp.connect_timeout_ms == 0 ||
+         hp.progress_timeout_ms == 0 || hp.idle_connection_timeout_ms == 0)) {
+        return Invalid("transports/hp_tcp",
+                       "contains zero or inconsistent limits");
+    }
+    if (parsed.enabled && config.get("transports/tcp/enable", true)) {
+        return Invalid("transports",
+                       "tcp and hp_tcp cannot be enabled together");
+    }
+
+    *out = std::move(parsed);
+    return Status::OK();
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/runtime/memory_prober.cpp b/mooncake-transfer-engine/tent/src/runtime/memory_prober.cpp
index c4da931c4b..ab3545f597 100644
--- a/mooncake-transfer-engine/tent/src/runtime/memory_prober.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/memory_prober.cpp
@@ -93,6 +93,13 @@ Status MemoryProber::loadPlugins(const std::string& path) {
     return Status::OK();
 }
 
+static bool pluginHandlesLocationType(const char* class_name,
+                                      const std::string& type) {
+    if (!class_name) return false;
+    if (class_name == type) return true;
+    return isAmdGpuLocationType(class_name) && isAmdGpuLocationType(type);
+}
+
 void MemoryProber::unloadPlugins() {
     for (auto& p : plugins_) {
         if (p.iface.destroy_plugin && p.ctx) {
@@ -132,7 +139,9 @@ Status MemoryProber::alloc(void** pptr, size_t size, const std::string& loc) {
     }
 
     for (auto& p : plugins_) {
-        if (!(p.iface.class_name == type) || !p.iface.alloc) continue;
+        if (!pluginHandlesLocationType(p.iface.class_name, type) ||
+            !p.iface.alloc)
+            continue;
         int rc = p.iface.alloc(p.ctx, pptr, size, loc.c_str());
         if (rc == 0) {
             std::lock_guard<std::mutex> lock(mu_);
@@ -157,7 +166,9 @@ Status MemoryProber::free(void* ptr, size_t size) {
     }
 
     for (auto& p : plugins_) {
-        if (!(p.iface.class_name == type) || !p.iface.free) continue;
+        if (!pluginHandlesLocationType(p.iface.class_name, type) ||
+            !p.iface.free)
+            continue;
         int rc = p.iface.free(p.ctx, ptr, size);
         if (rc == 0) {
             memory_type_map_.erase(ptr);
@@ -364,7 +375,8 @@ void MemoryProber::probeDeviceMemory(
     MemoryProber::LoadedPlugin& plugin,
     const std::vector<Topology::NicEntry>& nic_list,
     std::vector<Topology::MemEntry>& mem_list) {
-    if (!plugin.iface.get_device_count || !plugin.iface.get_device_pci_bus_id) {
+    if (!plugin.iface.class_name || !plugin.iface.get_device_count ||
+        !plugin.iface.get_device_pci_bus_id) {
         return;
     }
     int device_count = plugin.iface.get_device_count(plugin.ctx);
@@ -386,11 +398,20 @@ void MemoryProber::probeDeviceMemory(
         }
 
         Topology::MemEntry entry;
-        entry.name =
-            std::string(plugin.iface.class_name) + ":" + std::to_string(i);
+        // Canonicalize the AMD alias so legacy plugins registering
+        // class_name "rocm" still emit the canonical "hip:N" names.
+        const bool is_amd = isAmdGpuLocationType(plugin.iface.class_name);
+        entry.name = (is_amd ? std::string(kAmdGpuLocationType)
+                             : std::string(plugin.iface.class_name)) +
+                     ":" + std::to_string(i);
         entry.numa_node = numa_node;
         entry.pci_bus_id = pci_bus_id;
-        entry.type = Topology::MEM_CUDA;
+        entry.type = memTypeFromLocation(entry.name);
+        if (entry.type == Topology::MEM_UNKNOWN) {
+            // Non-AMD device plugins historically defaulted to CUDA-class
+            // memory (e.g. npu). Keep that fallback.
+            entry.type = Topology::MEM_CUDA;
+        }
         if (distance_map.count(0)) {
             // Prefer NICs with distance 0 (e.g. same PCIe switch/RC)
             entry.device_list[0] = std::move(distance_map[0]);
diff --git a/mooncake-transfer-engine/tent/src/runtime/platform.cpp b/mooncake-transfer-engine/tent/src/runtime/platform.cpp
index 611737f532..3d1438d304 100644
--- a/mooncake-transfer-engine/tent/src/runtime/platform.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/platform.cpp
@@ -14,6 +14,10 @@
 
 #include "tent/runtime/platform.h"
 
+#include <mutex>
+#include <unordered_set>
+#include <vector>
+
 #ifdef USE_CUDA
 #include "tent/platform/cuda.h"
 #elif defined(USE_HIP)
@@ -24,6 +28,8 @@
 #include "tent/platform/ascend.h"
 #elif defined(USE_TPU)
 #include "tent/platform/tpu.h"
+#elif defined(USE_XPU)
+#include "tent/platform/xpu.h"
 #else
 #include "tent/platform/cpu.h"
 #endif
@@ -45,11 +51,37 @@ Platform& Platform::getLoader(std::shared_ptr<Config> conf) {
         g_instance = std::make_shared<AscendPlatform>(conf);
 #elif defined(USE_TPU)
         g_instance = std::make_shared<TpuPlatform>(conf);
+#elif defined(USE_XPU)
+            g_instance = std::make_shared<XpuPlatform>(conf);
 #else
         g_instance = std::make_shared<CpuPlatform>(conf);
 #endif
     });
     return *g_instance;
 }
+
+Status Platform::synchronizeDevices(const Topology* topology) {
+    (void)topology;
+    return Status::OK();
+}
+
+std::vector<int> Platform::topologyDeviceIndices(const Topology* topology,
+                                                 Topology::MemType mem_type) {
+    std::vector<int> devices;
+    if (!topology) return devices;
+
+    std::unordered_set<int> seen;
+    const size_t mem_count = topology->getMemCount();
+    for (size_t i = 0; i < mem_count; ++i) {
+        const auto* mem =
+            topology->getMemEntry(static_cast<Topology::MemID>(i));
+        if (!mem || mem->type != mem_type) continue;
+        LocationParser parser(mem->name);
+        const int device = parser.index();
+        if (device < 0 || !seen.insert(device).second) continue;
+        devices.push_back(device);
+    }
+    return devices;
+}
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/runtime/progress_worker.cpp b/mooncake-transfer-engine/tent/src/runtime/progress_worker.cpp
index 49a6e470e5..d3c9fc543f 100644
--- a/mooncake-transfer-engine/tent/src/runtime/progress_worker.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/progress_worker.cpp
@@ -96,6 +96,9 @@ void ProgressWorker::runner() {
                 queued_.erase(batch_id);
             }
         }
+        // lazyFreeBatch reports the first batch it could not reclaim and logs
+        // the skip itself (rate-limited); the worker only sweeps, so the
+        // status is intentionally dropped at these call sites.
         if (queue_ready) {
             (void)impl_->progressRuntimeQueue();
             (void)impl_->lazyFreeBatch();
diff --git a/mooncake-transfer-engine/tent/src/runtime/proxy_manager.cpp b/mooncake-transfer-engine/tent/src/runtime/proxy_manager.cpp
index 53a7953757..545eca753d 100644
--- a/mooncake-transfer-engine/tent/src/runtime/proxy_manager.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/proxy_manager.cpp
@@ -14,6 +14,7 @@
 
 #include "tent/runtime/proxy_manager.h"
 #include "tent/runtime/transfer_engine_impl.h"
+#include "remote_stage_operation.h"
 #include <algorithm>
 #include <cstring>
 #include <sstream>
@@ -23,7 +24,11 @@ namespace mooncake {
 namespace tent {
 ProxyManager::ProxyManager(TransferEngineImpl* impl, size_t chunk_size,
                            size_t chunk_count)
-    : chunk_size_(chunk_size), chunk_count_(chunk_count), impl_(impl) {
+    : chunk_size_(chunk_size),
+      chunk_count_(chunk_count),
+      impl_(impl),
+      shutdown_drain_timeout_(std::chrono::milliseconds(
+          impl->conf_->get("staging/shutdown_drain_timeout_ms", 30000L))) {
     running_ = true;
     for (size_t i = 0; i < kShards; ++i) {
         shards_[i].thread = std::thread(&ProxyManager::runner, this, i);
@@ -32,18 +37,189 @@ ProxyManager::ProxyManager(TransferEngineImpl* impl, size_t chunk_size,
 
 ProxyManager::~ProxyManager() { deconstruct(); }
 
+void ProxyManager::flushPendingCleanups(bool unpin_remote_buffers) {
+    if (!has_pending_cleanups_.load(std::memory_order_relaxed)) return;
+    std::vector<Batch*> batches_to_release;
+    std::vector<uint64_t> local_addrs_to_unpin;
+    std::vector<std::pair<std::string, uint64_t>> remote_addrs_to_unpin;
+    {
+        std::lock_guard<std::mutex> lk(pending_cleanups_mu_);
+        if (pending_cleanups_.empty()) {
+            has_pending_cleanups_.store(false, std::memory_order_relaxed);
+            return;
+        }
+        for (auto it = pending_cleanups_.begin();
+             it != pending_cleanups_.end();) {
+            for (auto batch_it = it->batches.begin();
+                 batch_it != it->batches.end();) {
+                TransferStatus status;
+                auto poll_status = impl_->progressBatch(*batch_it, status);
+                if (!poll_status.ok()) {
+                    LOG_EVERY_N(WARNING, 100)
+                        << "Failed to poll deferred staging batch: "
+                        << poll_status;
+                    ++batch_it;
+                    continue;
+                }
+                if (status.s == PENDING) {
+                    ++batch_it;
+                    continue;
+                }
+                batches_to_release.push_back((Batch*)*batch_it);
+                batch_it = it->batches.erase(batch_it);
+            }
+
+            internal::pollRemoteOperations(it->remote_operations);
+            if (it->batches.empty()) {
+                local_addrs_to_unpin.insert(local_addrs_to_unpin.end(),
+                                            it->local_addrs.begin(),
+                                            it->local_addrs.end());
+                it->local_addrs.clear();
+                if (it->remote_operations.empty() && unpin_remote_buffers) {
+                    remote_addrs_to_unpin.insert(remote_addrs_to_unpin.end(),
+                                                 it->remote_addrs.begin(),
+                                                 it->remote_addrs.end());
+                    it->remote_addrs.clear();
+                }
+            }
+
+            if (it->local_addrs.empty() && it->remote_addrs.empty() &&
+                it->batches.empty() && it->remote_operations.empty()) {
+                it = pending_cleanups_.erase(it);
+                continue;
+            }
+            ++it;
+        }
+        if (pending_cleanups_.empty()) {
+            has_pending_cleanups_.store(false, std::memory_order_relaxed);
+        }
+    }
+
+    for (auto batch : batches_to_release) impl_->releaseBatch(batch);
+    for (auto addr : local_addrs_to_unpin) unpinStageBuffer(addr);
+    for (auto& [server, addr] : remote_addrs_to_unpin) {
+        ControlClient::unpinStageBuffer(server, addr);
+    }
+}
+
 Status ProxyManager::deconstruct() {
-    running_ = false;
+    if (!running_.exchange(false, std::memory_order_acq_rel)) {
+        return Status::OK();
+    }
     for (size_t i = 0; i < kShards; ++i) {
         shards_[i].cv.notify_all();
-        shards_[i].thread.join();
+        if (shards_[i].thread.joinable()) shards_[i].thread.join();
     }
+
+    auto has_pending_batches = [this]() {
+        std::lock_guard<std::mutex> lk(pending_cleanups_mu_);
+        return std::any_of(
+            pending_cleanups_.begin(), pending_cleanups_.end(),
+            [](const PendingBufferCleanup& p) { return !p.batches.empty(); });
+    };
+
+    flushPendingCleanups(false);
+    const auto drain_deadline =
+        std::chrono::steady_clock::now() + shutdown_drain_timeout_;
+    while (has_pending_batches()) {
+        if (std::chrono::steady_clock::now() >= drain_deadline) {
+            LOG(WARNING) << "Timed out waiting for in-flight staging batches "
+                            "to reach a terminal state during shutdown; "
+                            "leaving the remaining cleanups pinned";
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        flushPendingCleanups(false);
+    }
+
+    flushPendingCleanups(false);
+    std::vector<PendingBufferCleanup> remaining;
+    std::vector<BatchID> deferred_batches;
+    std::vector<uint64_t> deferred_local_addrs;
+    {
+        std::lock_guard<std::mutex> lk(pending_cleanups_mu_);
+        remaining = std::move(pending_cleanups_);
+        pending_cleanups_.clear();
+        has_pending_cleanups_.store(false, std::memory_order_relaxed);
+    }
+    for (auto& pending : remaining) {
+        if (!pending.batches.empty()) {
+            // The drain deadline above makes non-terminal batches reachable
+            // here. A transport worker may still complete these batches and
+            // their slices target the local stage buffers pinned in
+            // local_addrs, so keep the remote pins held (the deferred unpin
+            // path below assumes the batches already drained) and collect
+            // both so they outlive the transports (see below).
+            LOG(WARNING) << "Leaving " << pending.remote_addrs.size()
+                         << " remote stage buffers pinned because "
+                         << pending.remote_operations.size()
+                         << " remote staging requests and "
+                         << pending.batches.size()
+                         << " staging batches have not reached a confirmed "
+                            "terminal state";
+            deferred_batches.insert(deferred_batches.end(),
+                                    pending.batches.begin(),
+                                    pending.batches.end());
+            deferred_local_addrs.insert(deferred_local_addrs.end(),
+                                        pending.local_addrs.begin(),
+                                        pending.local_addrs.end());
+            continue;
+        }
+        size_t deferred_remote_buffers = 0;
+        for (auto& operation : pending.remote_operations) {
+            if (!operation) continue;
+            operation->abandonForCleanup();
+            ++deferred_remote_buffers;
+        }
+        if (deferred_remote_buffers != 0) {
+            LOG(WARNING)
+                << "Deferring cleanup of " << deferred_remote_buffers
+                << " remote stage buffers until their staging requests "
+                   "reach a terminal state";
+        }
+        for (auto& [server, addr] : pending.remote_addrs) {
+            const bool owned_by_pending_operation = std::any_of(
+                pending.remote_operations.begin(),
+                pending.remote_operations.end(), [&](const auto& operation) {
+                    return operation &&
+                           operation->ownsRemoteBuffer(server, addr);
+                });
+            if (!owned_by_pending_operation) {
+                ControlClient::unpinStageBuffer(server, addr);
+            }
+        }
+    }
+    // Undrained batches and the stage buffer arenas they write into must not
+    // be freed here: the engine releases (or intentionally abandons) them
+    // only after the transports have quiesced. Everything else is freed as
+    // before.
+    TransferEngineImpl::DeferredStageTeardown deferred;
+    deferred.batches = std::move(deferred_batches);
+    std::unique_lock<std::shared_mutex> guard(stage_buffers_mutex_);
     for (auto entry : stage_buffers_) {
+        const auto base = reinterpret_cast<uint64_t>(entry.second.chunks);
+        const auto end = base + chunk_size_ * chunk_count_;
+        const bool referenced_by_undrained_batch = std::any_of(
+            deferred_local_addrs.begin(), deferred_local_addrs.end(),
+            [&](uint64_t addr) { return addr >= base && addr < end; });
+        if (referenced_by_undrained_batch) {
+            deferred.stage_buffers.push_back(
+                {entry.first, entry.second.chunks, entry.second.bitmap});
+            continue;
+        }
         impl_->unregisterLocalMemory(entry.second.chunks);
         impl_->freeLocalMemory(entry.second.chunks);
         delete[] entry.second.bitmap;
     }
     stage_buffers_.clear();
+    if (!deferred.empty()) {
+        LOG(WARNING) << "Handing " << deferred.batches.size()
+                     << " undrained staging batches and "
+                     << deferred.stage_buffers.size()
+                     << " local stage buffer arenas to the engine for "
+                        "deferred teardown";
+        impl_->adoptDeferredStageTeardown(std::move(deferred));
+    }
     return Status::OK();
 }
 
@@ -110,20 +286,33 @@ Status ProxyManager::waitRemoteStage(const std::string& server_addr,
     return ControlClient::delegate(server_addr, remote_stage);
 }
 
-void ProxyManager::submitRemoteStage(const std::string& server_addr,
-                                     const Request& request,
-                                     uint64_t remote_stage_buffer,
-                                     uint64_t chunk_length, uint64_t offset,
-                                     std::future<Status>& handle) {
+void ProxyManager::submitRemoteStage(
+    const std::string& server_addr, const Request& request,
+    uint64_t remote_stage_buffer, uint64_t chunk_length, uint64_t offset,
+    std::shared_ptr<internal::RemoteStageOperation>& operation) {
     Request remote_stage;
     remote_stage.opcode = request.opcode;
     remote_stage.source = (void*)remote_stage_buffer;
     remote_stage.length = chunk_length;
     remote_stage.target_id = LOCAL_SEGMENT_ID;
     remote_stage.target_offset = request.target_offset + offset;
-    handle = delegate_pool_.enqueue([server_addr, remote_stage]() {
-        return ControlClient::delegate(server_addr, remote_stage);
-    });
+    operation = std::make_shared<internal::RemoteStageOperation>(
+        server_addr, remote_stage_buffer, [server_addr, remote_stage_buffer] {
+            ControlClient::unpinStageBufferAsync(
+                server_addr, remote_stage_buffer,
+                [server_addr, remote_stage_buffer](Status status) {
+                    if (!status.ok()) {
+                        LOG(WARNING)
+                            << "Failed to unpin deferred remote stage buffer "
+                            << remote_stage_buffer << " on " << server_addr
+                            << ": " << status;
+                    }
+                });
+        });
+    ControlClient::delegateAsync(
+        server_addr, remote_stage, [operation](Status status, bool confirmed) {
+            operation->complete(std::move(status), confirmed);
+        });
 }
 
 Status ProxyManager::waitCrossStage(const Request& request,
@@ -142,7 +331,7 @@ Status ProxyManager::submit(TaskInfo* task, BatchID batch,
     staging_task.native = task;
     staging_task.batch = batch;
     staging_task.params = params;
-    task->staging_status = PENDING;
+    task->staging_status.store(PENDING, std::memory_order_relaxed);
     static std::atomic<size_t> next_queue_index(0);
     thread_local size_t id = next_queue_index.fetch_add(1) % kShards;
     {
@@ -155,10 +344,9 @@ Status ProxyManager::submit(TaskInfo* task, BatchID batch,
 
 Status ProxyManager::getStatus(TaskInfo* task, TransferStatus& task_status) {
     if (!task || !task->staging) return Status::InvalidArgument("Invalid task");
-    task_status.s = task->staging_status;
-    if (task_status.s == COMPLETED) {
-        task_status.transferred_bytes = task->request.length;
-    }
+    task_status.s = task->staging_status.load(std::memory_order_acquire);
+    task_status.transferred_bytes =
+        task_status.s == COMPLETED ? task->request.length : 0;
     return Status::OK();
 }
 
@@ -173,7 +361,7 @@ struct StageBufferCache {
         uint64_t addr = 0;
         auto status = mgr.pinStageBuffer(location, addr);
         if (!status.ok()) {
-            LOG(FATAL) << "Failed to pin local stage buffer: " << status
+            LOG(ERROR) << "Failed to pin local stage buffer: " << status
                        << ", location " << location;
             return 0;
         }
@@ -191,7 +379,7 @@ struct StageBufferCache {
         auto status =
             ControlClient::pinStageBuffer(server_addr, location, addr);
         if (!status.ok()) {
-            LOG(FATAL) << "Failed to pin remote stage buffer: " << status
+            LOG(ERROR) << "Failed to pin remote stage buffer: " << status
                        << ", location " << location;
             return 0;
         }
@@ -220,9 +408,8 @@ struct StageBufferCache {
 };
 
 void ProxyManager::runner(size_t id) {
-    StageBufferCache cache(*this);
     auto& shard = shards_[id];
-    while (running_) {
+    while (running_.load(std::memory_order_acquire)) {
         StagingTask task;
         {
             std::unique_lock<std::mutex> lk(shard.mu);
@@ -239,17 +426,50 @@ void ProxyManager::runner(size_t id) {
         }
 
         if (!task.native) continue;
-        auto status = transferEventLoop(task, &cache);
-        auto staging_status = status.ok() ? COMPLETED : FAILED;
-        __atomic_store(&task.native->staging_status, &staging_status,
-                       __ATOMIC_RELEASE);
+        flushPendingCleanups();
+        StageBufferCache cache(*this);
+        bool buffers_safe_to_release = true;
+        std::vector<BatchID> undrained_batches;
+        std::vector<std::shared_ptr<internal::RemoteStageOperation>>
+            undrained_remote_operations;
+        auto status =
+            transferEventLoop(task, &cache, buffers_safe_to_release,
+                              undrained_batches, undrained_remote_operations);
+        if (buffers_safe_to_release) {
+            cache.reset();
+        } else {
+            LOG(WARNING) << "Staging cleanup could not drain all in-flight "
+                            "operations; deferring stage buffer cleanup";
+            PendingBufferCleanup pending;
+            for (auto& entry : cache.local_stage_buffers) {
+                pending.local_addrs.push_back(entry.second);
+            }
+            for (auto& server_entry : cache.remote_stage_buffers) {
+                for (auto& entry : server_entry.second) {
+                    pending.remote_addrs.push_back(
+                        {server_entry.first, entry.second});
+                }
+            }
+            pending.batches = std::move(undrained_batches);
+            pending.remote_operations = std::move(undrained_remote_operations);
+            {
+                std::lock_guard<std::mutex> lk(pending_cleanups_mu_);
+                pending_cleanups_.push_back(std::move(pending));
+                has_pending_cleanups_.store(true, std::memory_order_relaxed);
+            }
+        }
+        task.native->staging_status.store(status.ok() ? COMPLETED : FAILED,
+                                          std::memory_order_release);
         impl_->notifyBatchMaybeReady(task.batch);
     }
-    cache.reset();
 }
 
-Status ProxyManager::transferEventLoop(StagingTask& task,
-                                       StageBufferCache* cache) {
+Status ProxyManager::transferEventLoop(
+    StagingTask& task, StageBufferCache* cache, bool& buffers_safe_to_release,
+    std::vector<BatchID>& undrained_batches,
+    std::vector<std::shared_ptr<internal::RemoteStageOperation>>&
+        undrained_remote_operations) {
+    buffers_safe_to_release = true;
     auto& request = task.native->request;
     auto server_addr = task.params[0];
     bool local_staging = !task.params[1].empty();
@@ -317,11 +537,87 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
     }
 
     for (size_t i = 0; i < chunks.size(); ++i) event_queue.push(i);
-    std::vector<std::future<Status>> remote_futures(chunks.size());
+    std::vector<std::shared_ptr<internal::RemoteStageOperation>>
+        remote_operations(chunks.size());
+    auto drain_batch = [&](BatchID batch) {
+        TransferStatus xfer_status;
+        auto status = impl_->progressBatch(batch, xfer_status);
+        if (!status.ok()) {
+            LOG(ERROR) << "Failed to poll in-flight staging batch: " << status;
+            impl_->freeBatch(batch);
+            return false;
+        }
+        auto free_status = impl_->freeBatch(batch);
+        if (!free_status.ok()) {
+            LOG(WARNING) << "Failed to free drained staging batch: "
+                         << free_status;
+        }
+        return xfer_status.s != PENDING;
+    };
+    auto cleanup_inflight = [&]() {
+        bool all_drained = true;
+        for (auto& chunk : chunks) {
+            if (!chunk.batch) continue;
+            Batch* bptr = nullptr;
+            auto retain_status = impl_->retainBatch(chunk.batch, bptr);
+            if (drain_batch(chunk.batch)) {
+                if (retain_status.ok() && bptr) {
+                    impl_->releaseBatch(bptr);
+                }
+                chunk.batch = 0;
+            } else {
+                all_drained = false;
+                if (retain_status.ok() && bptr) {
+                    undrained_batches.push_back(chunk.batch);
+                }
+            }
+        }
+        if (!internal::pollRemoteOperations(remote_operations)) {
+            all_drained = false;
+            for (auto& operation : remote_operations) {
+                if (operation) {
+                    undrained_remote_operations.push_back(std::move(operation));
+                }
+            }
+            remote_operations.clear();
+        }
+        return all_drained;
+    };
+
+    // The loop below can leave through the CHECK_STATUS on progressBatch or
+    // through the FAILED branch, which only drains the queue. Either way the
+    // chunks still in flight own a batch that nobody would free.
+    struct PendingBatches {
+        TransferEngineImpl* impl;
+        std::vector<Chunk>& chunks;
+        ~PendingBatches() {
+            for (auto& chunk : chunks) {
+                if (!chunk.batch) continue;
+                auto status = impl->freeBatch(chunk.batch);
+                if (!status.ok())
+                    LOG(WARNING)
+                        << "failed to free chunk batch: " << status.ToString();
+                chunk.batch = 0;
+            }
+        }
+    } pending_batches{impl_, chunks};
+
+    // An in-flight chunk goes straight back on the queue, so this loop spins
+    // with nothing to do -- and the INFLIGHT case takes progress_mutex_ every
+    // pass. Back off only after a whole sweep advanced no chunk, so a queue
+    // that is progressing still runs at full speed.
+    size_t sweep_remaining = event_queue.size();
+    bool swept_progress = false;
+    uint64_t idle_sweeps = 0;
 
     while (!event_queue.empty()) {
+        if (!running_.load(std::memory_order_acquire)) {
+            buffers_safe_to_release = cleanup_inflight();
+            return Status::InternalError("Proxy manager is shutting down");
+        }
         auto id = event_queue.front();
         auto& chunk = chunks[id];
+        const auto state_before = chunk.state;
         event_queue.pop();
         switch (chunk.state) {
             case StageState::PRE: {
@@ -349,7 +645,7 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
                     remote_locked.insert(chunk.remote_buf);
                     submitRemoteStage(server_addr, request, chunk.remote_buf,
                                       chunk.length, chunk.offset,
-                                      remote_futures[id]);
+                                      remote_operations[id]);
                     chunk.prev_state = chunk.state;
                     chunk.state = StageState::INFLIGHT_REMOTE;
                     event_queue.push(id);
@@ -392,7 +688,7 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
                 if (request.opcode == Request::WRITE && remote_staging) {
                     submitRemoteStage(server_addr, request, chunk.remote_buf,
                                       chunk.length, chunk.offset,
-                                      remote_futures[id]);
+                                      remote_operations[id]);
                     chunk.prev_state = chunk.state;
                     chunk.state = StageState::INFLIGHT_REMOTE;
                     event_queue.push(id);
@@ -416,7 +712,11 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
 
             case StageState::INFLIGHT: {
                 TransferStatus xfer_status;
-                CHECK_STATUS(impl_->progressBatch(chunk.batch, xfer_status));
+                auto status = impl_->progressBatch(chunk.batch, xfer_status);
+                if (!status.ok()) {
+                    buffers_safe_to_release = cleanup_inflight();
+                    return status;
+                }
                 if (xfer_status.s == PENDING) {
                     event_queue.push(id);
                     break;
@@ -453,25 +753,27 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
             }
 
             case StageState::FAILED: {
-                // Drain the queue to avoid losing chunks
-                while (!event_queue.empty()) {
-                    event_queue.pop();
-                }
+                buffers_safe_to_release = cleanup_inflight();
                 return Status::InternalError(
                     "Proxy event loop in failed state");
             }
 
             case StageState::INFLIGHT_REMOTE: {
-                auto& fut = remote_futures[id];
-                if (!fut.valid()) {
+                auto& operation = remote_operations[id];
+                if (!operation) {
                     chunk.state = StageState::FAILED;
                     event_queue.push(id);
                     break;
                 }
-                if (fut.wait_for(std::chrono::seconds(0)) ==
-                    std::future_status::ready) {
-                    Status rs = fut.get();
-                    if (!rs.ok()) {
+                auto result = operation->tryTakeResult();
+                if (result) {
+                    if (!result->confirmed) {
+                        chunk.state = StageState::FAILED;
+                        event_queue.push(id);
+                        break;
+                    }
+                    operation.reset();
+                    if (!result->status.ok()) {
                         chunk.state = StageState::FAILED;
                         event_queue.push(id);
                         break;
@@ -493,6 +795,17 @@ Status ProxyManager::transferEventLoop(StagingTask& task,
                 break;
             }
         }
+
+        if (chunk.state != state_before) swept_progress = true;
+        if (sweep_remaining > 0) --sweep_remaining;
+        if (sweep_remaining == 0) {
+            if (swept_progress)
+                idle_sweeps = 0;
+            else
+                waitBeforeNextPoll(idle_sweeps++);
+            swept_progress = false;
+            sweep_remaining = event_queue.size();
+        }
     }
 
     return Status::OK();
@@ -561,6 +874,10 @@ Status ProxyManager::transferSync(StagingTask& task, StageBufferCache* cache) {
 }
 
 Status ProxyManager::allocateStageBuffers(const std::string& location) {
+    // Held across the slow allocate + register, which run once per location.
+    // Racing instead would register the same hundreds of MB twice, then throw
+    // one away.
+    std::unique_lock<std::shared_mutex> guard(stage_buffers_mutex_);
     if (stage_buffers_.count(location)) return Status::OK();
     StageBuffers buf;
     auto total_size = chunk_size_ * chunk_count_;
@@ -575,6 +892,7 @@ Status ProxyManager::allocateStageBuffers(const std::string& location) {
 }
 
 Status ProxyManager::freeStageBuffers(const std::string& location) {
+    std::unique_lock<std::shared_mutex> guard(stage_buffers_mutex_);
     auto it = stage_buffers_.find(location);
     if (it == stage_buffers_.end())
         return Status::InvalidArgument("Stage buffer not allocated" LOC_MARK);
@@ -587,24 +905,50 @@ Status ProxyManager::freeStageBuffers(const std::string& location) {
 
 Status ProxyManager::pinStageBuffer(const std::string& location,
                                     uint64_t& addr) {
-    auto it = stage_buffers_.find(location);
-    if (it == stage_buffers_.end()) {
-        CHECK_STATUS(allocateStageBuffers(location));
-        it = stage_buffers_.find(location);
+    {
+        std::shared_lock<std::shared_mutex> guard(stage_buffers_mutex_);
+        auto it = stage_buffers_.find(location);
+        if (it == stage_buffers_.end()) {
+            guard.unlock();
+            CHECK_STATUS(allocateStageBuffers(location));
+            guard.lock();
+            it = stage_buffers_.find(location);
+            if (it == stage_buffers_.end())
+                return Status::InternalError(
+                    "Stage buffer disappeared" LOC_MARK);
+        }
+
+        auto& buf = it->second;
+        for (size_t i = 0; i < chunk_count_; ++i) {
+            if (!buf.bitmap[i].test_and_set(std::memory_order_acquire)) {
+                addr = reinterpret_cast<uint64_t>(
+                    static_cast<char*>(buf.chunks) + i * chunk_size_);
+                return Status::OK();
+            }
+        }
     }
 
-    auto& buf = it->second;
-    for (size_t i = 0; i < chunk_count_; ++i) {
-        if (!buf.bitmap[i].test_and_set(std::memory_order_acquire)) {
-            addr = reinterpret_cast<uint64_t>(static_cast<char*>(buf.chunks) +
-                                              i * chunk_size_);
-            return Status::OK();
+    if (has_pending_cleanups_.load(std::memory_order_relaxed)) {
+        flushPendingCleanups();
+        std::shared_lock<std::shared_mutex> guard(stage_buffers_mutex_);
+        auto it = stage_buffers_.find(location);
+        if (it != stage_buffers_.end()) {
+            auto& buf = it->second;
+            for (size_t i = 0; i < chunk_count_; ++i) {
+                if (!buf.bitmap[i].test_and_set(std::memory_order_acquire)) {
+                    addr = reinterpret_cast<uint64_t>(
+                        static_cast<char*>(buf.chunks) + i * chunk_size_);
+                    return Status::OK();
+                }
+            }
         }
     }
+
     return Status::TooManyRequests("No available stage buffer in " + location);
 }
 
 Status ProxyManager::unpinStageBuffer(uint64_t addr) {
+    std::shared_lock<std::shared_mutex> guard(stage_buffers_mutex_);
     for (auto& [location, buf] : stage_buffers_) {
         auto base = reinterpret_cast<uint64_t>(buf.chunks);
         auto end = base + chunk_size_ * chunk_count_;
diff --git a/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.cpp b/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.cpp
new file mode 100644
index 0000000000..24ee4a3119
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.cpp
@@ -0,0 +1,107 @@
+#include "remote_stage_operation.h"
+
+#include <exception>
+#include <utility>
+
+#include <glog/logging.h>
+
+namespace mooncake {
+namespace tent {
+namespace internal {
+namespace {
+
+void runDeferredCleanup(RemoteStageOperation::DeferredCleanup cleanup) {
+    if (!cleanup) return;
+    try {
+        cleanup();
+    } catch (const std::exception& ex) {
+        LOG(WARNING) << "Failed to start deferred remote buffer cleanup: "
+                     << ex.what();
+    } catch (...) {
+        LOG(WARNING)
+            << "Failed to start deferred remote buffer cleanup: unknown error";
+    }
+}
+
+}  // namespace
+
+RemoteStageOperation::RemoteStageOperation(std::string server_addr,
+                                           uint64_t remote_buffer,
+                                           DeferredCleanup deferred_cleanup)
+    : server_addr_(std::move(server_addr)),
+      remote_buffer_(remote_buffer),
+      deferred_cleanup_(std::move(deferred_cleanup)) {}
+
+void RemoteStageOperation::complete(Status status, bool confirmed) {
+    DeferredCleanup cleanup;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        result_ = RemoteStageResult{std::move(status), confirmed};
+        cleanup = takeCleanupIfReadyLocked();
+    }
+    runDeferredCleanup(std::move(cleanup));
+}
+
+std::optional<RemoteStageResult> RemoteStageOperation::tryTakeResult() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (abandoned_ || !result_) return std::nullopt;
+    auto result = std::move(result_);
+    result_.reset();
+    return result;
+}
+
+void RemoteStageOperation::abandonForCleanup() {
+    DeferredCleanup cleanup;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        abandoned_ = true;
+        cleanup = takeCleanupIfReadyLocked();
+    }
+    runDeferredCleanup(std::move(cleanup));
+}
+
+bool RemoteStageOperation::ownsRemoteBuffer(const std::string& server_addr,
+                                            uint64_t remote_buffer) const {
+    return server_addr_ == server_addr && remote_buffer_ == remote_buffer;
+}
+
+RemoteStageOperation::DeferredCleanup
+RemoteStageOperation::takeCleanupIfReadyLocked() {
+    if (!abandoned_ || !result_ || !result_->confirmed || cleanup_started_ ||
+        !deferred_cleanup_) {
+        return {};
+    }
+    cleanup_started_ = true;
+    return deferred_cleanup_;
+}
+
+bool pollRemoteOperations(
+    std::vector<RemoteStageOperationPtr>& remote_operations) {
+    for (auto it = remote_operations.begin(); it != remote_operations.end();) {
+        if (!*it) {
+            it = remote_operations.erase(it);
+            continue;
+        }
+        auto result = (*it)->tryTakeResult();
+        if (!result) {
+            ++it;
+            continue;
+        }
+        if (!result->confirmed) {
+            LOG(WARNING) << "Remote staging completion is unconfirmed: "
+                         << result->status;
+            ++it;
+            continue;
+        }
+        if (!result->status.ok()) {
+            LOG(WARNING) << "Failed to drain remote staging request: "
+                         << result->status;
+        }
+        it = remote_operations.erase(it);
+    }
+    return remote_operations.empty();
+}
+
+}  // namespace internal
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.h b/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.h
new file mode 100644
index 0000000000..1a73bf56aa
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/runtime/remote_stage_operation.h
@@ -0,0 +1,61 @@
+#ifndef REMOTE_STAGE_OPERATION_H_
+#define REMOTE_STAGE_OPERATION_H_
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "tent/common/status.h"
+
+namespace mooncake {
+namespace tent {
+namespace internal {
+
+struct RemoteStageResult {
+    Status status;
+    bool confirmed;
+};
+
+class RemoteStageOperation {
+   public:
+    using DeferredCleanup = std::function<void()>;
+
+    RemoteStageOperation() = default;
+    RemoteStageOperation(std::string server_addr, uint64_t remote_buffer,
+                         DeferredCleanup deferred_cleanup);
+
+    void complete(Status status, bool confirmed);
+
+    std::optional<RemoteStageResult> tryTakeResult();
+
+    void abandonForCleanup();
+
+    bool ownsRemoteBuffer(const std::string& server_addr,
+                          uint64_t remote_buffer) const;
+
+   private:
+    DeferredCleanup takeCleanupIfReadyLocked();
+
+    std::string server_addr_;
+    uint64_t remote_buffer_{0};
+    DeferredCleanup deferred_cleanup_;
+    std::mutex mutex_;
+    std::optional<RemoteStageResult> result_;
+    bool abandoned_{false};
+    bool cleanup_started_{false};
+};
+
+using RemoteStageOperationPtr = std::shared_ptr<RemoteStageOperation>;
+
+bool pollRemoteOperations(
+    std::vector<RemoteStageOperationPtr>& remote_operations);
+
+}  // namespace internal
+}  // namespace tent
+}  // namespace mooncake
+
+#endif  // REMOTE_STAGE_OPERATION_H_
diff --git a/mooncake-transfer-engine/tent/src/runtime/segment_tracker.cpp b/mooncake-transfer-engine/tent/src/runtime/segment_tracker.cpp
index 0faf27ba25..a52a9f4716 100644
--- a/mooncake-transfer-engine/tent/src/runtime/segment_tracker.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/segment_tracker.cpp
@@ -90,7 +90,8 @@ Status SegmentTracker::add(uint64_t base, size_t length,
 
 Status SegmentTracker::addInBatch(
     std::vector<BufferDesc>& desc_list,
-    std::function<Status(std::vector<BufferDesc>&)> callback) {
+    std::function<Status(std::vector<BufferDesc>&)> callback,
+    std::function<void(BufferDesc&)> on_removed) {
     std::vector<BufferDesc> new_desc_list;
     // Read-only pre-scan (see add()): skip the ref-count publication when no
     // entry duplicates an already-registered range.
@@ -139,24 +140,34 @@ Status SegmentTracker::addInBatch(
         // Roll back the duplicate ref-counts so a failed registration does
         // not leave buffers pinned forever.
         if (!bumped.empty()) {
-            manager_.updateLocal([&](SegmentDesc& desc) -> Status {
-                auto& detail = std::get<MemorySegmentDesc>(desc.detail);
-                for (auto& range : bumped) {
-                    for (auto it = detail.buffers.begin();
-                         it != detail.buffers.end(); ++it) {
-                        if (it->addr == range.first &&
-                            it->length == range.second) {
-                            it->ref_count--;
-                            // The original owner unregistered while we held
-                            // the extra reference; drop the entry so it is
-                            // no longer advertised.
-                            if (it->ref_count == 0) detail.buffers.erase(it);
-                            break;
+            std::vector<BufferDesc> removed;
+            auto rollback_status =
+                manager_.updateLocal([&](SegmentDesc& desc) -> Status {
+                    auto& detail = std::get<MemorySegmentDesc>(desc.detail);
+                    for (auto& range : bumped) {
+                        for (auto it = detail.buffers.begin();
+                             it != detail.buffers.end(); ++it) {
+                            if (it->addr == range.first &&
+                                it->length == range.second) {
+                                it->ref_count--;
+                                // The original owner unregistered while we held
+                                // the extra reference; drop the entry so it is
+                                // no longer advertised.
+                                if (it->ref_count == 0) {
+                                    removed.push_back(*it);
+                                    detail.buffers.erase(it);
+                                }
+                                break;
+                            }
                         }
                     }
-                }
-                return Status::OK();
-            });
+                    return Status::OK();
+                });
+            if (!rollback_status.ok()) {
+                LOG(WARNING) << rollback_status.ToString();
+            } else if (on_removed) {
+                for (auto& buffer : removed) on_removed(buffer);
+            }
         }
         return status;
     }
diff --git a/mooncake-transfer-engine/tent/src/runtime/topology.cpp b/mooncake-transfer-engine/tent/src/runtime/topology.cpp
index 8892ebdaea..2bf81b1664 100644
--- a/mooncake-transfer-engine/tent/src/runtime/topology.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/topology.cpp
@@ -19,6 +19,7 @@
 #include <iostream>
 #include <map>
 #include <set>
+#include <sstream>
 #include <string>
 #include <unordered_map>
 #include <unordered_set>
@@ -107,11 +108,6 @@ void Topology::print() const {
 }
 
 Status Topology::discover(const std::vector<Platform*>& platforms) {
-    return discover(platforms, false);
-}
-
-Status Topology::discover(const std::vector<Platform*>& platforms,
-                          bool discover_ub) {
     clear();
     for (auto& entry : platforms) {
         CHECK_STATUS(entry->probe(nic_list_, mem_list_));
@@ -120,7 +116,7 @@ Status Topology::discover(const std::vector<Platform*>& platforms,
     // UB discovery is intentionally adapter-backed instead of inferring UB
     // devices from verbs/sysfs names. One topology NIC is emitted per EID and
     // carries both the globally serialized identity and the native URMA name.
-    auto adapter = discover_ub ? ub::createDefaultUrmaAdapter() : nullptr;
+    auto adapter = ub::createDefaultUrmaAdapter();
     if (adapter && adapter->available()) {
         auto status = adapter->initialize();
         if (status.ok()) {
@@ -181,7 +177,6 @@ Status Topology::discover(const std::vector<Platform*>& platforms,
         }
     }
 #endif
-    (void)discover_ub;
     return Status::OK();
 }
 
@@ -234,6 +229,167 @@ Status Topology::parse(const std::string& json_content) {
     return Status::OK();
 }
 
+namespace {
+
+Topology::NicID ensureNic(
+    Topology& topo, const std::string& name,
+    std::unordered_map<std::string, Topology::NicID>* ids) {
+    auto it = ids->find(name);
+    if (it != ids->end()) return it->second;
+    Topology::NicID id = static_cast<Topology::NicID>(topo.nic_list_.size());
+    Topology::NicEntry nic;
+    nic.name = name;
+    nic.type = Topology::NIC_RDMA;
+    nic.numa_node = -1;
+    topo.nic_list_.push_back(std::move(nic));
+    (*ids)[name] = id;
+    return id;
+}
+
+}  // namespace
+
+Status Topology::parsePriorityMatrix(const std::string& json_content) {
+    try {
+        clear();
+        if (json_content.empty()) {
+            return Status::MalformedJson("empty priority matrix" LOC_MARK);
+        }
+        nlohmann::json root = nlohmann::json::parse(json_content);
+        if (!root.is_object()) {
+            return Status::MalformedJson(
+                "priority matrix must be a JSON object" LOC_MARK);
+        }
+
+        std::unordered_map<std::string, NicID> nic_ids;
+        std::vector<NicID> all_preferred;
+        std::vector<NicID> all_avail;
+        std::unordered_set<NicID> seen_preferred;
+        std::unordered_set<NicID> seen_avail;
+        // Canonical mem names, to reject configs that specify the same
+        // device twice via the "rocm:N" alias and the canonical "hip:N".
+        std::unordered_set<std::string> seen_mem_names;
+
+        for (auto it = root.begin(); it != root.end(); ++it) {
+            const auto& value = it.value();
+            if (!value.is_array() || value.size() != 2 ||
+                !value[0].is_array() || !value[1].is_array()) {
+                return Status::MalformedJson(
+                    "each priority matrix entry must be "
+                    "[[preferred...],[avail...]]" LOC_MARK);
+            }
+
+            MemEntry mem;
+            // Store canonical names: a legacy "rocm:N" key becomes "hip:N"
+            // so runtime lookups with canonical names match.
+            mem.name = canonicalizeLocation(it.key());
+            if (!seen_mem_names.insert(mem.name).second) {
+                return Status::MalformedJson(
+                    "duplicate location key \"" + mem.name +
+                    "\" (the rocm:N alias and hip:N key refer to the same "
+                    "device)" LOC_MARK);
+            }
+            mem.pci_bus_id = "";
+            mem.type = memTypeFromLocation(mem.name);
+            mem.numa_node = -1;
+
+            for (const auto& hca : value[0]) {
+                if (!hca.is_string()) {
+                    return Status::MalformedJson(
+                        "HCA names must be strings" LOC_MARK);
+                }
+                NicID id = ensureNic(*this, hca.get<std::string>(), &nic_ids);
+                mem.device_list[0].push_back(id);
+                if (seen_preferred.insert(id).second) {
+                    all_preferred.push_back(id);
+                }
+            }
+            for (const auto& hca : value[1]) {
+                if (!hca.is_string()) {
+                    return Status::MalformedJson(
+                        "HCA names must be strings" LOC_MARK);
+                }
+                NicID id = ensureNic(*this, hca.get<std::string>(), &nic_ids);
+                mem.device_list[1].push_back(id);
+                if (seen_avail.insert(id).second) {
+                    all_avail.push_back(id);
+                }
+            }
+            mem_list_.push_back(std::move(mem));
+        }
+
+        // Wildcard entry used when memory location is unknown.
+        MemEntry wildcard;
+        wildcard.name = kWildcardLocation;
+        wildcard.pci_bus_id = "";
+        wildcard.type = MEM_UNKNOWN;
+        wildcard.numa_node = -1;
+        wildcard.device_list[0] = all_preferred;
+        wildcard.device_list[1] = all_avail;
+        mem_list_.push_back(std::move(wildcard));
+    } catch (std::exception& e) {
+        clear();
+        return Status::MalformedJson(std::string(e.what()) + LOC_MARK);
+    }
+    return Status::OK();
+}
+
+Status Topology::parseCustomTopology(const std::string& json_content) {
+    nlohmann::json j;
+    try {
+        j = nlohmann::json::parse(json_content);
+    } catch (std::exception& e) {
+        return Status::MalformedJson(std::string(e.what()) + LOC_MARK);
+    }
+    if (j.is_object() && (j.contains("nics") || j.contains("mems"))) {
+        return parse(json_content);
+    }
+    return parsePriorityMatrix(json_content);
+}
+
+Status Topology::loadFromConfig(const Config& conf,
+                                const std::vector<Platform*>& platforms) {
+    if (conf.contains("topology/priority_matrix")) {
+        std::string matrix_json;
+        if (conf.dumpSubtree("topology/priority_matrix", &matrix_json)) {
+            auto status = parsePriorityMatrix(matrix_json);
+            if (status.ok()) {
+                LOG(INFO) << "Using custom NIC priority matrix from config";
+                return Status::OK();
+            }
+            LOG(WARNING) << "Failed to parse topology/priority_matrix: "
+                         << status.ToString()
+                         << ", falling back to auto-discover";
+            return discover(platforms);
+        }
+    }
+
+    auto path = conf.get("topology/custom_json_path", std::string());
+    if (!path.empty()) {
+        LOG(INFO) << "Using custom topology from: " << path;
+        std::ifstream file(path);
+        if (!file.is_open()) {
+            LOG(WARNING) << "Failed to load custom topology from " << path
+                         << ", falling back to auto-detect.";
+            return discover(platforms);
+        }
+        std::stringstream buffer;
+        buffer << file.rdbuf();
+        std::string content = buffer.str();
+        if (content.empty()) {
+            LOG(WARNING) << "Failed to load custom topology from " << path
+                         << ", falling back to auto-detect.";
+            return discover(platforms);
+        }
+        auto status = parseCustomTopology(content);
+        if (status.ok()) return Status::OK();
+        LOG(WARNING) << "Failed to parse custom topology from " << path << ": "
+                     << status.ToString() << ", falling back to auto-detect.";
+        return discover(platforms);
+    }
+
+    return discover(platforms);
+}
+
 size_t Topology::getNicCount(NicType type) const {
     if (type == NIC_UNKNOWN) return nic_list_.size();
     size_t count = 0;
@@ -257,6 +413,13 @@ const Topology::NicEntry* Topology::getNicEntry(NicID id) const {
     return &nic_list_[id];
 }
 
+bool Topology::isCrossNuma(const MemEntry& mem, NicID nic_id) const {
+    if (mem.numa_node < 0) return false;
+    const auto* nic = getNicEntry(nic_id);
+    if (!nic || nic->numa_node < 0) return false;
+    return nic->numa_node != mem.numa_node;
+}
+
 const Topology::MemEntry* Topology::getMemEntry(MemID id) const {
     if (id < 0 || id >= (int)mem_list_.size()) return nullptr;
     return &mem_list_[id];
@@ -270,8 +433,9 @@ const Topology::NicEntry* Topology::getNicEntry(const std::string& name) const {
 }
 
 const Topology::MemEntry* Topology::getMemEntry(const std::string& name) const {
+    const auto canonical = canonicalizeLocation(name);
     for (size_t i = 0; i < mem_list_.size(); ++i) {
-        if (mem_list_[i].name == name) return &mem_list_[i];
+        if (mem_list_[i].name == canonical) return &mem_list_[i];
     }
     return nullptr;
 }
@@ -284,8 +448,9 @@ Topology::NicID Topology::getNicId(const std::string& name) const {
 }
 
 Topology::MemID Topology::getMemId(const std::string& name) const {
+    const auto canonical = canonicalizeLocation(name);
     for (size_t i = 0; i < mem_list_.size(); ++i) {
-        if (mem_list_[i].name == name) return (MemID)i;
+        if (mem_list_[i].name == canonical) return (MemID)i;
     }
     return -1;
 }
diff --git a/mooncake-transfer-engine/tent/src/runtime/transfer_engine_impl.cpp b/mooncake-transfer-engine/tent/src/runtime/transfer_engine_impl.cpp
index a45c0459c1..76c8c6d15a 100644
--- a/mooncake-transfer-engine/tent/src/runtime/transfer_engine_impl.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/transfer_engine_impl.cpp
@@ -16,6 +16,7 @@
 #include "tent/runtime/control_plane.h"
 
 #include <algorithm>
+#include <chrono>
 #include <cstdlib>
 #include <fstream>
 #include <limits>
@@ -23,6 +24,8 @@
 #include <optional>
 #include <random>
 #include <stdexcept>
+#include <thread>
+#include <unordered_set>
 
 #include "tent/common/config.h"
 #include "tent/common/status.h"
@@ -39,6 +42,7 @@
 #include "tent/common/utils/random.h"
 #include "tent/metrics/tent_metrics.h"
 #include "tent/metrics/config_loader.h"
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
 
 namespace mooncake {
 namespace tent {
@@ -46,6 +50,13 @@ namespace tent {
 namespace {
 constexpr uint8_t kRedisMaxDbIndex = 255;
 constexpr uint8_t kRedisDefaultDbIndex = 0;
+
+// After this many consecutive failed reclaim attempts, lazyFreeBatch stops
+// retrying a batch (see Batch::reclaim_abandoned). Transient errors heal in a
+// pass or two and a healthy-but-inflight batch reports PENDING (which resets
+// the counter), so only a permanently failing poll or queue retire gets here.
+constexpr size_t kMaxReclaimAttempts = 4096;
+constexpr int kMaxHpTcpMetadataRefreshRetries = 1;
 }  // namespace
 
 struct Batch {
@@ -59,6 +70,13 @@ struct Batch {
     size_t runtime_refs{0};
     bool free_requested{false};
     uint64_t queue_token{0};
+    // Consecutive lazyFreeBatch passes that failed to reclaim this batch
+    // (poll error or queue retire error). Reset when a pass observes the
+    // batch healthy (PENDING). At kMaxReclaimAttempts the batch is marked
+    // reclaim_abandoned: the sweep stops retrying (and warning) and leaves
+    // it for deconstruct(), which reclaims the freelist unconditionally.
+    size_t reclaim_failures{0};
+    bool reclaim_abandoned{false};
 
     struct SubmitHook {
         size_t start_task_id{0};
@@ -76,6 +94,13 @@ struct PreservedTentConfigOverrides {
     std::optional<std::string> local_segment_name;
     std::optional<std::string> rpc_server_hostname;
     std::optional<json> rpc_server_port;
+    bool force_tcp{false};
+    std::optional<std::vector<std::string>> rdma_whitelist;
+    // Classic TE shim writes these nested leaves before construct(). Keep
+    // them on the existing identity whitelist instead of growing Config.
+    std::optional<bool> ascend_agent_mode;
+    std::optional<bool> ascend_store_te_init;
+    std::optional<bool> ascend_fabric_mem;
 };
 
 template <typename T>
@@ -145,6 +170,47 @@ Status getRpcServerPortFromConfig(const Config& config, uint16_t default_value,
         "rpc_server_port must be an integer or integer string" LOC_MARK);
 }
 
+Status getRpcServerThreadsFromConfig(const Config& config, size_t default_value,
+                                     size_t& threads) {
+    constexpr const char* kKey = "rpc_server_threads";
+    constexpr long long kMinThreads = 1;
+    constexpr long long kMaxThreads = 1024;
+    auto validate = [&](long long value, const std::string& source) -> Status {
+        if (value < kMinThreads || value > kMaxThreads) {
+            return Status::InvalidArgument(
+                "Invalid rpc_server_threads '" + source +
+                "', expected value in range [1, " +
+                std::to_string(kMaxThreads) + "]" LOC_MARK);
+        }
+        threads = static_cast<size_t>(value);
+        return Status::OK();
+    };
+    if (!config.contains(kKey)) {
+        threads = default_value;
+        return Status::OK();
+    }
+
+    json raw_value = config.get<json>(kKey, json());
+    if (raw_value.is_number_integer() || raw_value.is_number_unsigned()) {
+        long long numeric_value = raw_value.get<long long>();
+        return validate(numeric_value, std::to_string(numeric_value));
+    }
+    if (raw_value.is_string()) {
+        auto string_value = raw_value.get<std::string>();
+        auto parsed_value = tryParseConfigIntString(string_value);
+        if (!parsed_value.has_value()) {
+            return Status::InvalidArgument(
+                "Invalid rpc_server_threads '" + string_value +
+                "', expected integer in range [1, " +
+                std::to_string(kMaxThreads) + "]" LOC_MARK);
+        }
+        return validate(*parsed_value, string_value);
+    }
+
+    return Status::InvalidArgument(
+        "rpc_server_threads must be an integer or integer string" LOC_MARK);
+}
+
 PreservedTentConfigOverrides captureExplicitTransferEngineConfig(
     const Config& config) {
     PreservedTentConfigOverrides preserved;
@@ -156,8 +222,17 @@ PreservedTentConfigOverrides captureExplicitTransferEngineConfig(
         captureExplicitConfigValue(config, "local_segment_name", std::string());
     preserved.rpc_server_hostname = captureExplicitConfigValue(
         config, "rpc_server_hostname", std::string());
+    preserved.force_tcp = config.get("transports/force_tcp", false);
     preserved.rpc_server_port =
         captureExplicitConfigValue(config, "rpc_server_port", json());
+    preserved.rdma_whitelist = captureExplicitConfigValue(
+        config, "topology/rdma_whitelist", std::vector<std::string>());
+    preserved.ascend_agent_mode = captureExplicitConfigValue(
+        config, "transports/ascend_direct/agent_mode", false);
+    preserved.ascend_store_te_init = captureExplicitConfigValue(
+        config, "transports/ascend_direct/store_te_init", false);
+    preserved.ascend_fabric_mem = captureExplicitConfigValue(
+        config, "transports/ascend_direct/fabric_mem", false);
     return preserved;
 }
 
@@ -181,6 +256,17 @@ void restoreExplicitTransferEngineConfig(
                                preserved.rpc_server_hostname);
     restoreExplicitConfigValue(config, "rpc_server_port",
                                preserved.rpc_server_port);
+    if (preserved.force_tcp) {
+        ConfigHelper::forceTcp(config);
+    }
+    restoreExplicitConfigValue(config, "topology/rdma_whitelist",
+                               preserved.rdma_whitelist);
+    restoreExplicitConfigValue(config, "transports/ascend_direct/agent_mode",
+                               preserved.ascend_agent_mode);
+    restoreExplicitConfigValue(config, "transports/ascend_direct/store_te_init",
+                               preserved.ascend_store_te_init);
+    restoreExplicitConfigValue(config, "transports/ascend_direct/fabric_mem",
+                               preserved.ascend_fabric_mem);
 }
 
 TransferEngineImpl::TransferEngineImpl()
@@ -279,6 +365,11 @@ Status TransferEngineImpl::setupLocalSegment() {
 }
 
 Status TransferEngineImpl::construct() {
+    // Publish the snapshot before any setup step can return an error.
+    std::atomic_store_explicit(&runtime_config_snapshot_,
+                               buildTentConfigBundle(*conf_).runtime,
+                               std::memory_order_relaxed);
+    CHECK_STATUS(ParseHpTcpTransportConfig(*conf_, &hp_tcp_transport_config_));
     auto metadata_type = conf_->get("metadata_type", "p2p");
     auto metadata_servers = conf_->get("metadata_servers", "");
 
@@ -286,10 +377,20 @@ Status TransferEngineImpl::construct() {
     hostname_ = conf_->get("rpc_server_hostname", "");
     local_segment_name_ = conf_->get("local_segment_name", "");
     CHECK_STATUS(getRpcServerPortFromConfig(*conf_, 0, port_));
+    // TCP SendData/RecvData copies are offloaded, but the RPC io_context still
+    // reads the full attachment. One thread serializes concurrent bulk TCP.
+    // Leave RDMA-only at 1; when TCP is on and the user did not set
+    // rpc_server_threads, use several so attachments can be read in parallel.
+    size_t rpc_server_threads = 1;
+    const size_t rpc_threads_default =
+        conf_->get("transports/tcp/enable", false)
+            ? std::min<size_t>(
+                  8, std::max<size_t>(4, std::thread::hardware_concurrency()))
+            : 1;
+    CHECK_STATUS(getRpcServerThreadsFromConfig(*conf_, rpc_threads_default,
+                                               rpc_server_threads));
     merge_requests_ = conf_->get("merge_requests", true);
-    max_failover_attempts_ = conf_->get("max_failover_attempts", 3);
-    enable_auto_failover_on_poll_ =
-        conf_->get("enable_auto_failover_on_poll", true);
+    notify_rpc_fallback_ = conf_->get("notification/rpc_fallback", true);
     enable_progress_worker_ = conf_->get("enable_progress_worker", false);
     runtime_queue_config_.enabled = conf_->get("enable_runtime_queue", false);
     if (runtime_queue_config_.enabled) enable_progress_worker_ = true;
@@ -329,13 +430,12 @@ Status TransferEngineImpl::construct() {
 
     topology_ = std::make_shared<Topology>();
     auto loader = &Platform::getLoader(conf_);
-    CHECK_STATUS(topology_->discover(
-        {loader}, conf_->get("transports/ub/enable", false)));
+    CHECK_STATUS(topology_->loadFromConfig(*conf_, {loader}));
 
     metadata_ =
         std::make_shared<ControlService>(metadata_type, metadata_servers, this);
 
-    CHECK_STATUS(metadata_->start(port_, ipv6_));
+    CHECK_STATUS(metadata_->start(port_, ipv6_, rpc_server_threads));
 
     if (metadata_type == "p2p")
         local_segment_name_ = buildIpAddrWithPort(hostname_, port_, ipv6_);
@@ -357,12 +457,43 @@ Status TransferEngineImpl::construct() {
 
     CHECK_STATUS(loadTransports());
 
+    // A notification that arrives over the control plane - the RPC fallback
+    // in sendNotification(), or a peer whose only notification path is RPC -
+    // reaches ControlService::onNotify(), which drops it unless a callback is
+    // registered. Queue such notifications in-process so receiveNotification()
+    // hands them out. ControlService keeps a single callback: the TCP
+    // transports register their own in install() below and take over.
+    metadata_->setNotifyCallback([this](const Notification& notifi) -> int {
+        std::lock_guard<std::mutex> lk(local_notifi_mutex_);
+        local_notifi_list_.push_back(notifi);
+        return 0;
+    });
+
     std::string transport_string;
-    for (auto& transport : transport_list_) {
+    for (size_t transport_index = 0; transport_index < transport_list_.size();
+         ++transport_index) {
+        auto& transport = transport_list_[transport_index];
         if (transport) {
             auto status = transport->install(local_segment_name_, metadata_,
                                              topology_, conf_);
             if (!status.ok()) {
+                if (hp_tcp_transport_config_.enabled &&
+                    transport_index ==
+                        static_cast<size_t>(TransportType::HP_TCP)) {
+                    // HP TCP is explicitly required, so a failed install is a
+                    // construction failure rather than an optional-transport
+                    // skip. Unwind the already-started control service and
+                    // any preceding transports immediately; the destructor's
+                    // later deconstruct() call is intentionally idempotent.
+                    const Status cleanup = deconstruct();
+                    if (!cleanup.ok()) {
+                        LOG(ERROR)
+                            << "Failed to unwind TENT after required HP TCP "
+                               "install failure: "
+                            << cleanup.ToString();
+                    }
+                    return status;
+                }
                 LOG(WARNING) << "Transport " << transport->getName()
                              << " skipped: " << status.ToString();
                 transport = nullptr;
@@ -468,6 +599,16 @@ Status TransferEngineImpl::deconstruct() {
         progress_worker_->stop();
     }
 
+    for (auto& transport : transport_list_) {
+        if (!transport) continue;
+        const Status status = transport->quiesce();
+        if (!status.ok()) {
+            LOG(ERROR) << "Transport " << transport->getName()
+                       << " quiesce failed during teardown: "
+                       << status.ToString();
+        }
+    }
+
     // Destroy staging_proxy_ first: its destructor calls back into
     // unregisterLocalMemory/freeLocalMemory, which require
     // local_segment_tracker_ and metadata_ to be alive.
@@ -507,18 +648,61 @@ Status TransferEngineImpl::deconstruct() {
             }
             Slab<Batch>::Get().deallocate(batch);
         };
-        for (auto& batch : batch_set_.active) release_batch(batch);
-        for (auto& batch : batch_set_.freelist) release_batch(batch);
-        batch_set_.active.clear();
-        batch_set_.freelist.clear();
-        alive_batches_.clear();
+        // Registry state is sharded; collect members under each shard.
+        // Shutdown is quiesced (progress_mutex_ held, no pollers expected),
+        // so a brief per-shard lock per batch is sufficient.
+        for (auto& shard : batch_shards_) {
+            std::lock_guard<std::recursive_mutex> shard_lk(shard.mtx);
+            for (auto* batch : shard.active_batches) release_batch(batch);
+            shard.active_batches.clear();
+            shard.alive_batches.clear();
+        }
+        for (auto* batch : batch_freelist_) release_batch(batch);
+        batch_freelist_.clear();
     }
 
     // Now safe to destroy transports (workers join here)
     for (auto& transport : transport_list_) transport.reset();
+
+    // Staging resources adopted from a timed-out ProxyManager drain may only
+    // be touched now that the workers above have joined and their completion
+    // queues are drained. Reclaiming them cleanly is not possible here:
+    // freeSubBatch() is a virtual on the transports just destroyed, and
+    // freeLocalMemory()/unregisterLocalMemory() route through raw Transport
+    // pointers captured in allocated_memory_. Following the
+    // resource_abandoned_ precedent in mooncake-pg, leak them on purpose
+    // until process exit instead of risking a use-after-free. The abandoned
+    // holder is kept reachable from a static registry (and the Batch shells
+    // stay inside the Slab arenas) so LeakSanitizer stays quiet.
+    {
+        std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
+        if (!deferred_stage_teardown_.empty()) {
+            LOG(WARNING) << "Abandoning "
+                         << deferred_stage_teardown_.batches.size()
+                         << " undrained staging batches and "
+                         << deferred_stage_teardown_.stage_buffers.size()
+                         << " local stage buffer arenas until process exit";
+            for (auto& entry : deferred_stage_teardown_.stage_buffers) {
+                // The bitmap is plain host memory only the (already joined)
+                // staging workers touched; the chunks are what the transport
+                // slices pointed at, so only they must be kept.
+                delete[] entry.bitmap;
+                entry.bitmap = nullptr;
+            }
+            static std::mutex abandoned_mu;
+            static auto* abandoned = new std::vector<DeferredStageTeardown>();
+            std::lock_guard<std::mutex> alk(abandoned_mu);
+            abandoned->push_back(std::move(deferred_stage_teardown_));
+            deferred_stage_teardown_ = DeferredStageTeardown();
+        }
+    }
+
     progress_worker_.reset();
     local_segment_tracker_.reset();
     if (metadata_) {
+        // The in-process notify callback registered by construct() captures
+        // this engine; the transports already dropped theirs.
+        metadata_->setNotifyCallback(nullptr);
         metadata_->segmentManager().deleteLocal();
         metadata_.reset();
     }
@@ -535,6 +719,10 @@ const std::string TransferEngineImpl::getRpcServerAddress() const {
 
 uint16_t TransferEngineImpl::getRpcServerPort() const { return port_; }
 
+std::shared_ptr<Topology> TransferEngineImpl::getLocalTopology() const {
+    return topology_;
+}
+
 Status TransferEngineImpl::exportLocalSegment(std::string& shared_handle) {
     return Status::NotImplemented(
         "exportLocalSegment not implemented" LOC_MARK);
@@ -568,6 +756,7 @@ Status TransferEngineImpl::getSegmentInfo(SegmentID handle, SegmentInfo& info) {
     } else {
         CHECK_STATUS(metadata_->segmentManager().getRemoteCached(desc, handle));
     }
+    info.buffers.clear();
     if (desc->type == SegmentType::File) {
         info.type = SegmentInfo::File;
         auto& detail = std::get<FileSegmentDesc>(desc->detail);
@@ -605,14 +794,19 @@ Status TransferEngineImpl::allocateLocalMemory(void** addr, size_t size,
     options.internal = internal;
     if (location == kWildcardLocation ||
         LocationParser(location).type() == "cpu") {
-        if (transport_list_[SHM])
+        if (transport_list_[MNNVL] &&
+            transport_list_[MNNVL]->capabilities().dram_to_dram)
+            options.type = MNNVL;  // EGM: host memory NVLink peers can address
+        else if (transport_list_[SHM])
             options.type = SHM;
         else if (transport_list_[RDMA])
             options.type = RDMA;
         else if (transport_list_[UB])
             options.type = UB;
-        else
+        else if (transport_list_[TCP])
             options.type = TCP;
+        else
+            options.type = HP_TCP;
     } else {
         if (transport_list_[MNNVL])
             options.type = MNNVL;
@@ -620,8 +814,10 @@ Status TransferEngineImpl::allocateLocalMemory(void** addr, size_t size,
             options.type = RDMA;
         else if (transport_list_[UB])
             options.type = UB;
-        else
+        else if (transport_list_[TCP])
             options.type = TCP;
+        else
+            options.type = HP_TCP;
     }
     return allocateLocalMemory(addr, size, options);
 }
@@ -629,12 +825,22 @@ Status TransferEngineImpl::allocateLocalMemory(void** addr, size_t size,
 Status TransferEngineImpl::allocateLocalMemory(void** addr, size_t size,
                                                MemoryOptions& options) {
     if (options.type == UNSPEC) {
-        if (transport_list_[RDMA])
+        auto location_type = LocationParser(options.location).type();
+        bool host_location =
+            options.location == kWildcardLocation || location_type == "cpu";
+        if (host_location && transport_list_[MNNVL] &&
+            transport_list_[MNNVL]->capabilities().dram_to_dram)
+            options.type = MNNVL;  // EGM: host memory NVLink peers can address
+        else if (transport_list_[RDMA])
             options.type = RDMA;
         else if (transport_list_[UB])
             options.type = UB;
         else if (transport_list_[TCP])
             options.type = TCP;
+        else if (transport_list_[HP_TCP])
+            options.type = HP_TCP;
+        else if (host_location && transport_list_[SHM])
+            options.type = SHM;
         else
             return Status::InvalidArgument(
                 "Not supported type in memory options" LOC_MARK);
@@ -643,7 +849,13 @@ Status TransferEngineImpl::allocateLocalMemory(void** addr, size_t size,
     if (!transport)
         return Status::InvalidArgument(
             "Not supported type in memory options" LOC_MARK);
-    CHECK_STATUS(transport->allocateLocalMemory(addr, size, options));
+    const bool default_shm =
+        options.type == SHM && options.location == kWildcardLocation;
+    if (default_shm) options.location = "cpu:0";
+    auto status = transport->allocateLocalMemory(addr, size, options);
+    // Keep wildcard registration based on the actual memory-location probe.
+    if (default_shm) options.location = kWildcardLocation;
+    if (!status.ok()) return status;
     std::lock_guard<std::mutex> lock(mutex_);
     AllocatedMemory entry{.addr = *addr,
                           .size = size,
@@ -659,13 +871,23 @@ Status TransferEngineImpl::freeLocalMemory(void* addr) {
          ++it) {
         if (it->addr == addr) {
             auto status = it->transport->freeLocalMemory(addr, it->size);
+            if (!status.ok()) {
+                LOG(WARNING)
+                    << "Failed to free local memory, addr=" << addr
+                    << ", size=" << it->size << ": " << status.ToString();
+                return status;
+            }
             allocated_memory_.erase(it);
-            return status;
+            return Status::OK();
         }
     }
     return Status::InvalidArgument("Address region not registered" LOC_MARK);
 }
 
+// Forward declaration: getTypeEnum() is defined below but is needed by the
+// registerLocalMemory location-override validation.
+static MemoryType getTypeEnum(const std::string& type);
+
 Status TransferEngineImpl::registerLocalMemory(void* addr, size_t size,
                                                Permission permission) {
     MemoryOptions options;
@@ -693,13 +915,18 @@ std::vector<TransportType> TransferEngineImpl::getSupportedTransports(
     }
     if (transport_list_[MNNVL]) result.push_back(MNNVL);
     if (transport_list_[NVLINK]) result.push_back(NVLINK);
+    // Prefer the local XPU copy over TCP's device-copy fallback. XPU does
+    // not advertise host-to-host capability, so host network order is intact.
+    if (transport_list_[XPU]) result.push_back(XPU);
     if (transport_list_[RDMA]) result.push_back(RDMA);
     if (transport_list_[UB]) result.push_back(UB);
     if (transport_list_[SUNRISE_LINK]) result.push_back(SUNRISE_LINK);
     if (transport_list_[AscendDirect]) result.push_back(AscendDirect);
     if (transport_list_[SHM]) result.push_back(SHM);
     if (transport_list_[TCP]) result.push_back(TCP);
+    if (transport_list_[HP_TCP]) result.push_back(HP_TCP);
     if (transport_list_[GDS]) result.push_back(GDS);
+    if (transport_list_[MPCOMM]) result.push_back(MPCOMM);
     if (transport_list_[TPU]) result.push_back(TPU);
     return result;
 }
@@ -746,22 +973,55 @@ Status TransferEngineImpl::registerLocalMemory(std::vector<void*> addr_list,
             desc.regions = coalesceRegions(entries);
         }
         desc.ref_count = 1;
-        if (options.location != kWildcardLocation)
-            desc.location = options.location;
+        // The probe is the source of truth for transport selection: it
+        // classifies the memory (cpu/cuda/...). A caller-supplied location
+        // may refine the probe within the SAME memory type (e.g. probe
+        // "cpu:0" -> caller "cpu:1"), but must not replace it with an
+        // incompatible or unknown type. Classic TE encodes NUMA-segmented
+        // host DRAM as "segments:4096:0,1"; that is a TE dialect TENT's
+        // type system does not understand, and blindly adopting it would
+        // make getTypeEnum() return MTYPE_UNKNOWN and break transport
+        // selection. Validate before overriding: keep the probe when the
+        // caller is a wildcard, unknown, or a different type.
+        if (options.location != kWildcardLocation &&
+            !options.location.empty()) {
+            auto probed_type =
+                getTypeEnum(LocationParser(desc.location).type());
+            auto caller_type =
+                getTypeEnum(LocationParser(options.location).type());
+            if (caller_type == MTYPE_UNKNOWN) {
+                LOG(WARNING)
+                    << "Ignoring unknown caller location '" << options.location
+                    << "' for registered memory at " << addr_list[i]
+                    << " (probed '" << desc.location
+                    << "'); keeping probed location";
+            } else if (caller_type != probed_type) {
+                LOG(WARNING) << "Ignoring caller location '" << options.location
+                             << "' (type mismatch with probed '"
+                             << desc.location << "') for registered memory at "
+                             << addr_list[i] << "; keeping probed location";
+            } else {
+                desc.location = options.location;
+            }
+        }
         if (options.internal) desc.internal = options.internal;
+        desc.permission = options.perm;
         desc_list.push_back(std::move(desc));
     }
 
+    bool need_sync = false;
     auto status = local_segment_tracker_->addInBatch(
-        desc_list, [&](std::vector<BufferDesc>& descs) -> Status {
+        desc_list,
+        [&](std::vector<BufferDesc>& descs) -> Status {
+            const bool hp_tcp_required =
+                options.type == HP_TCP ||
+                (options.type == UNSPEC && transports.size() == 1 &&
+                 transports.front() == HP_TCP);
             std::vector<TransportType> registered_transports;
             Status first_error = Status::OK();
             for (auto type : transports) {
                 auto s = transport_list_[type]->addMemoryBuffer(descs, options);
                 if (!s.ok()) {
-                    LOG(WARNING) << "Failed to register memory with "
-                                 << transport_list_[type]->getName() << ": "
-                                 << s.ToString();
                     // addMemoryBuffer implementations are required to be
                     // transactional, but invoke remove on the failing
                     // transport as defensive cleanup for a partially
@@ -772,6 +1032,8 @@ Status TransferEngineImpl::registerLocalMemory(std::vector<void*> addr_list,
                         if (!cleanup.ok()) LOG(WARNING) << cleanup.ToString();
                     }
                     if (first_error.ok()) first_error = s;
+                    if (type == HP_TCP && hp_tcp_required) return s;
+                    LOG(WARNING) << s.ToString();
                     // Explicit transport registration is strict. UNSPEC keeps
                     // the long-standing best-effort behavior across several
                     // installed transports, but may not publish a buffer for
@@ -784,12 +1046,28 @@ Status TransferEngineImpl::registerLocalMemory(std::vector<void*> addr_list,
             if (registered_transports.empty() && !first_error.ok()) {
                 return first_error;
             }
+            // desc.transports lists the transports that actually registered
+            // the buffer (each transport appends itself on success).
+            for (auto& desc : descs) {
+                for (auto type : desc.transports) {
+                    TentMetrics::instance().recordRegisteredBufferBytes(
+                        type, static_cast<int64_t>(desc.length));
+                }
+            }
             return Status::OK();
+        },
+        [&](BufferDesc& desc) {
+            need_sync = true;
+            deregisterRemovedBuffer(desc);
         });
-    if (!status.ok()) return status;
     // Synchronize local segment to metadata server so remote peers can see the
     // new buffers
-    return metadata_->segmentManager().synchronizeLocal();
+    if (status.ok()) return metadata_->segmentManager().synchronizeLocal();
+    if (need_sync) {
+        auto sync_status = metadata_->segmentManager().synchronizeLocal();
+        if (!sync_status.ok()) LOG(WARNING) << sync_status.ToString();
+    }
+    return status;
 }
 
 // WARNING: before exiting TE, make sure that all local memory are
@@ -799,14 +1077,7 @@ Status TransferEngineImpl::unregisterLocalMemory(void* addr, size_t size) {
     auto status = local_segment_tracker_->remove(
         (uint64_t)addr, size, [&](BufferDesc& desc) -> Status {
             removed = true;
-            // Backends may scrub their own metadata from desc, including the
-            // transports vector. Iterate a snapshot so every backend that
-            // registered the buffer is still called exactly once.
-            const auto transports = desc.transports;
-            for (auto type : transports) {
-                auto status = transport_list_[type]->removeMemoryBuffer(desc);
-                if (!status.ok()) LOG(WARNING) << status.ToString();
-            }
+            deregisterRemovedBuffer(desc);
             return Status::OK();
         });
     if (!status.ok()) return status;
@@ -827,11 +1098,7 @@ Status TransferEngineImpl::unregisterLocalMemory(
             (uint64_t)addr_list[i], size_list.empty() ? 0 : size_list[i],
             [&](BufferDesc& desc) -> Status {
                 removed = true;
-                const auto transports = desc.transports;
-                for (auto type : transports) {
-                    auto s = transport_list_[type]->removeMemoryBuffer(desc);
-                    if (!s.ok()) LOG(WARNING) << s.ToString();
-                }
+                deregisterRemovedBuffer(desc);
                 return Status::OK();
             });
         if (!status.ok()) return status;
@@ -841,74 +1108,217 @@ Status TransferEngineImpl::unregisterLocalMemory(
     return metadata_->segmentManager().synchronizeLocal();
 }
 
+void TransferEngineImpl::deregisterRemovedBuffer(BufferDesc& desc) {
+    const BufferDesc original_desc = desc;
+    const auto& registered_transports = original_desc.transports;
+    for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
+        auto& transport = transport_list_[type];
+        if (!transport) continue;
+        const auto transport_type = static_cast<TransportType>(type);
+        const bool advertised =
+            std::find(registered_transports.begin(),
+                      registered_transports.end(),
+                      transport_type) != registered_transports.end();
+        BufferDesc transport_desc = original_desc;
+        if (!advertised && !transport->tracksLocalBuffer(transport_desc))
+            continue;
+        auto status = transport->removeMemoryBuffer(transport_desc);
+        if (!status.ok()) LOG(WARNING) << status.ToString();
+    }
+    for (auto type : registered_transports) {
+        TentMetrics::instance().recordRegisteredBufferBytes(
+            type, -static_cast<int64_t>(original_desc.length));
+    }
+}
+
 BatchID TransferEngineImpl::allocateBatch(size_t batch_size) {
     Batch* batch = Slab<Batch>::Get().allocate();
     if (!batch) return (BatchID)0;
     batch->max_size = batch_size;
+    batch->task_list.reserve(batch_size);
     BatchID batch_id = (BatchID)batch;
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    batch_set_.active.insert(batch);
-    alive_batches_.insert(batch_id);
+    // Registry insert under the batch's own shard; no global lock.
+    {
+        BatchShard& shard = batchShard(batch_id);
+        std::lock_guard<std::recursive_mutex> lk(shard.mtx);
+        shard.active_batches.insert(batch);
+        shard.alive_batches.insert(batch_id);
+    }
     return batch_id;
 }
 
 Status TransferEngineImpl::freeBatch(BatchID batch_id) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
     Batch* batch = (Batch*)(batch_id);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id))
-        return Status::InvalidArgument("Batch is not alive" LOC_MARK);
-    if (runtime_queue_config_.enabled && batch->queue_token != 0) {
-        auto retire_status = retireQueueForBatch(batch);
-        if (!retire_status.ok() && !retire_status.IsInvalidEntry()) {
-            return retire_status;
+    // Fast path (queue off, no refs, tasks terminal): free under the batch
+    // shard only. tebench / sglang take this path. Shard is released before
+    // the deferred path takes progress_mutex_ (lock-order safety).
+    bool already_requested = false;
+    bool deferred = false;
+    {
+        std::lock_guard<std::recursive_mutex> shard_lk(
+            progressLockFor(batch_id));
+        if (!isBatchAlive(batch_id))
+            return Status::InvalidArgument("Batch is not alive" LOC_MARK);
+        if (!runtime_queue_config_.enabled && batch->runtime_refs == 0 &&
+            !batch->free_requested) {
+            // Only free inline when the final poll succeeds and reports a
+            // terminal state. A poll error defers the batch instead of
+            // failing freeBatch(): the lazy sweep retries, rate-limits and
+            // eventually quarantines a permanently stuck batch.
+            TransferStatus overall_status;
+            auto status = getTransferStatus(batch_id, overall_status);
+            if (status.ok() && overall_status.s != PENDING) {
+                for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
+                    auto& transport = transport_list_[type];
+                    auto& sub_batch = batch->sub_batch[type];
+                    if (transport && sub_batch)
+                        transport->freeSubBatch(sub_batch);
+                }
+                {
+                    BatchShard& shard = batchShard(batch_id);
+                    std::lock_guard<std::recursive_mutex> shard_reg_lk(
+                        shard.mtx);
+                    shard.active_batches.erase(batch);
+                    shard.alive_batches.erase(batch_id);
+                }
+                Slab<Batch>::Get().deallocate(batch);
+                return Status::OK();
+            }
         }
+        already_requested = batch->free_requested;
+        batch->free_requested = true;
+        deferred = true;
     }
-    if (batch->free_requested) {
+
+    if (deferred) {
+        std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
+        // The shard lock was released before taking progress_mutex_ to keep
+        // the lock order one-way. In the default queue-off mode,
+        // progress_mutex_ does not protect the per-shard registry, so
+        // reacquire that shard before reading alive_batches_. Queue mode
+        // already makes progress_mutex_ the caller's lock and isBatchAlive()
+        // takes the shard for this check.
+        bool batch_alive = false;
+        if (runtime_queue_config_.enabled) {
+            batch_alive = isBatchAlive(batch_id);
+        } else {
+            std::lock_guard<std::recursive_mutex> shard_lk(
+                batchShardMutex(batch_id));
+            batch_alive = isBatchAlive(batch_id);
+        }
+        if (!batch_alive) {
+            // We marked free_requested; another thread already reaped it.
+            return Status::OK();
+        }
+        if (runtime_queue_config_.enabled && batch->queue_token != 0) {
+            auto retire_status = retireQueueForBatch(batch);
+            if (!retire_status.ok() && !retire_status.IsInvalidEntry()) {
+                return retire_status;
+            }
+        }
+        if (!already_requested) {
+            // First free request: accepted unconditionally; the lazy sweep
+            // result is dropped (retry/quarantine happens in background).
+            batch_freelist_.push_back(batch);
+            lazyFreeBatch();
+            return Status::OK();
+        }
+        // Re-free of an already-requested batch: surface the sweep status —
+        // callers polling a stuck batch observe the reclaim error until the
+        // batch is quarantined or reclaimed.
         CHECK_STATUS(lazyFreeBatch());
         return Status::OK();
     }
-    batch->free_requested = true;
-    batch_set_.freelist.push_back(batch);
-    lazyFreeBatch();
     return Status::OK();
 }
 
 Status TransferEngineImpl::lazyFreeBatch() {
     std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    for (auto it = batch_set_.freelist.begin();
-         it != batch_set_.freelist.end();) {
+    // freelist is insertion-ordered. A batch that cannot be reclaimed on this
+    // pass (poll error, queue owners not yet terminal) must not stop the sweep:
+    // returning early would strand every batch queued behind it, and a
+    // permanent error would strand them for good. Skip it, keep going, and
+    // report the first error once the pass is complete. Most callers drop the
+    // returned status (the ProgressWorker sweeps on every step), so the skip is
+    // also logged here, rate-limited, or a permanently stuck batch would be
+    // re-polled forever without a trace.
+    Status first_error = Status::OK();
+    for (auto it = batch_freelist_.begin(); it != batch_freelist_.end();) {
         auto& batch = *it;
-        if (batch->runtime_refs > 0) {
-            it++;
-            continue;
-        }
-        TransferStatus overall_status;
-        CHECK_STATUS(getTransferStatus((BatchID)batch, overall_status));
-        if (overall_status.s == PENDING) {
+        if (batch->reclaim_abandoned) {
             it++;
             continue;
         }
-        if (runtime_queue_config_.enabled && batch->queue_token != 0) {
-            CHECK_STATUS(retireQueueForBatch(batch));
-        }
-        for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
-            auto& transport = transport_list_[type];
-            auto& sub_batch = batch->sub_batch[type];
-            if (transport && sub_batch) transport->freeSubBatch(sub_batch);
+        BatchID batch_id = (BatchID)batch;
+        // Hold the shard through deallocate so a poller waiting on the
+        // same shard cannot observe a dangling Batch*. runtime_refs is
+        // read under the shard because retain/release mutate it there.
+        {
+            std::lock_guard<std::recursive_mutex> shard_lk(
+                progressLockFor(batch_id));
+            if (!isBatchAlive(batch_id)) {
+                // Another thread already reaped this batch.
+                it = batch_freelist_.erase(it);
+                continue;
+            }
+            if (batch->runtime_refs > 0) {
+                it++;
+                continue;
+            }
+            TransferStatus overall_status;
+            auto status = getTransferStatus(batch_id, overall_status);
+            if (status.ok() && overall_status.s == PENDING) {
+                batch->reclaim_failures = 0;
+                it++;
+                continue;
+            }
+            if (status.ok() && runtime_queue_config_.enabled &&
+                batch->queue_token != 0) {
+                status = retireQueueForBatch(batch);
+            }
+            if (!status.ok()) {
+                if (++batch->reclaim_failures >= kMaxReclaimAttempts) {
+                    batch->reclaim_abandoned = true;
+                    TENT_RECORD_BATCH_QUARANTINED();
+                    LOG(ERROR) << "lazyFreeBatch: batch " << batch << " failed "
+                               << batch->reclaim_failures
+                               << " consecutive reclaim attempts; giving up "
+                                  "until engine teardown reclaims it "
+                                  "unconditionally. Last error: "
+                               << status.ToString();
+                } else {
+                    LOG_EVERY_N(WARNING, 100)
+                        << "lazyFreeBatch: batch " << batch
+                        << " cannot be reclaimed yet, left in freelist: "
+                        << status.ToString();
+                }
+                if (first_error.ok()) first_error = status;
+                it++;
+                continue;
+            }
+            for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
+                auto& transport = transport_list_[type];
+                auto& sub_batch = batch->sub_batch[type];
+                if (transport && sub_batch) transport->freeSubBatch(sub_batch);
+            }
+            {
+                BatchShard& shard = batchShard(batch_id);
+                std::lock_guard<std::recursive_mutex> shard_reg_lk(shard.mtx);
+                shard.active_batches.erase(batch);
+                shard.alive_batches.erase(batch_id);
+            }
+            Slab<Batch>::Get().deallocate(batch);
         }
-        batch_set_.active.erase(batch);
-        alive_batches_.erase((BatchID)batch);
-        Slab<Batch>::Get().deallocate(batch);
-        it = batch_set_.freelist.erase(it);
+        it = batch_freelist_.erase(it);
     }
-    return Status::OK();
+    return first_error;
 }
 
 Status TransferEngineImpl::retainBatch(BatchID batch_id, Batch*& batch) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id)) {
+    std::lock_guard<std::recursive_mutex> shard_lk(progressLockFor(batch_id));
+    if (!isBatchAlive(batch_id)) {
         return Status::InvalidArgument("Batch is not alive" LOC_MARK);
     }
     batch = (Batch*)batch_id;
@@ -921,17 +1331,51 @@ Status TransferEngineImpl::retainBatch(BatchID batch_id, Batch*& batch) {
 
 Status TransferEngineImpl::releaseBatch(Batch* batch) {
     if (!batch) return Status::InvalidArgument("Invalid batch" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (batch->runtime_refs == 0) {
-        return Status::InternalError("Batch runtime ref underflow" LOC_MARK);
+    // Refcount under the batch lock; deferred free runs on the global path
+    // after that lock is released (lock-order safety).
+    bool deferred_free = false;
+    {
+        std::lock_guard<std::recursive_mutex> shard_lk(
+            progressLockFor((BatchID)batch));
+        if (batch->runtime_refs == 0) {
+            return Status::InternalError(
+                "Batch runtime ref underflow" LOC_MARK);
+        }
+        --batch->runtime_refs;
+        deferred_free = (batch->runtime_refs == 0 && batch->free_requested);
     }
-    --batch->runtime_refs;
-    if (batch->runtime_refs == 0 && batch->free_requested) {
+    if (deferred_free) {
         CHECK_STATUS(lazyFreeBatch());
     }
     return Status::OK();
 }
 
+void TransferEngineImpl::adoptDeferredStageTeardown(
+    DeferredStageTeardown&& deferred) {
+    if (deferred.empty()) return;
+    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
+    for (auto batch_id : deferred.batches) {
+        Batch* batch = (Batch*)batch_id;
+        // Detach from the normal lifecycle: an undrained batch sits in its
+        // shard's active_batches / alive_batches and possibly
+        // batch_freelist_ (free_requested, still referenced), so the sweep
+        // in deconstruct() would hand its SubBatch/Slice objects back to
+        // the Slab while a transport worker can still write their status.
+        BatchShard& shard = batchShard(batch_id);
+        std::lock_guard<std::recursive_mutex> shard_lk(shard.mtx);
+        shard.active_batches.erase(batch);
+        shard.alive_batches.erase(batch_id);
+        auto it =
+            std::find(batch_freelist_.begin(), batch_freelist_.end(), batch);
+        if (it != batch_freelist_.end()) batch_freelist_.erase(it);
+        deferred_stage_teardown_.batches.push_back(batch_id);
+    }
+    deferred_stage_teardown_.stage_buffers.insert(
+        deferred_stage_teardown_.stage_buffers.end(),
+        std::make_move_iterator(deferred.stage_buffers.begin()),
+        std::make_move_iterator(deferred.stage_buffers.end()));
+}
+
 class TransferEngineImpl::BatchRef {
    public:
     BatchRef(TransferEngineImpl& engine, Batch* batch)
@@ -964,12 +1408,13 @@ class TransferEngineImpl::BatchRef {
 };
 
 static bool isGpuType(MemoryType t) {
-    // TPU HBM behaves like a GPU that lacks NIC access: it is a device-side
-    // memory that can only reach the network by staging through host DRAM.
-    // Treating it as a "gpu type" makes the capability checks route its
-    // device<->host hop to TpuTransport (gpu_to_dram / dram_to_gpu) while
-    // leaving gpu_to_gpu unsatisfiable, which forces host-DRAM staging.
-    return t == MTYPE_CUDA || t == MTYPE_ROCM || t == MTYPE_TPU;
+    // Delegates to the single isGpuMemoryType() in platform.h so this staging
+    // path and the selector's routing predicate share one device-type list and
+    // cannot disagree. TPU HBM and Intel XPU VRAM behave like a GPU without NIC
+    // access: their device<->host hop routes to the matching staging transport
+    // (gpu_to_dram / dram_to_gpu) while gpu_to_gpu stays unsatisfiable, forcing
+    // host-DRAM staging.
+    return isGpuMemoryType(t);
 }
 
 static bool checkAvailability(const std::shared_ptr<Transport>& xport,
@@ -996,8 +1441,9 @@ static MemoryType getTypeEnum(const std::string& type) {
     if (type == "cpu" || type == "*") return MTYPE_CPU;
     if (type == "cuda") return MTYPE_CUDA;
     if (type == "npu") return MTYPE_CUDA;
-    if (type == "rocm") return MTYPE_ROCM;
+    if (isAmdGpuLocationType(type)) return MTYPE_ROCM;
     if (type == "tpu") return MTYPE_TPU;
+    if (type == "xpu") return MTYPE_XPU;
     return MTYPE_UNKNOWN;
 }
 
@@ -1035,8 +1481,50 @@ SelectionResult TransferEngineImpl::getTransportType(const Request& request,
 
     const TransportType hint = request.transport_hint;
 
+    // XPU has no direct peer-memory path. Plan staging before requiring a
+    // direct device route: HP TCP (and non-GDR RDMA) only advertises DRAM
+    // capability. Keep the original memory types for policy matching.
+    std::vector<std::string> xpu_staging_params;
+    std::vector<TransportType> staging_transports;
+    if (desc->type == SegmentType::Memory &&
+        request.target_id != LOCAL_SEGMENT_ID && transport_list_[XPU]) {
+        auto* entry = desc->findBuffer(request.target_offset, request.length);
+        if (!entry) return SelectionResult{};
+        auto remote_mtype = getTypeEnum(LocationParser(entry->location).type());
+        if (local_mtype == MTYPE_XPU || remote_mtype == MTYPE_XPU) {
+            findStagingPolicy(request, xpu_staging_params);
+            if (xpu_staging_params.empty()) return SelectionResult{};
+            // A staged side is replaced by a freshly registered host stage
+            // buffer, so its own tags are irrelevant. An unstaged host buffer
+            // on either side is used as-is and must already carry the
+            // network transport.
+            const BufferDesc* local_entry = nullptr;
+            if (xpu_staging_params[1].empty()) {
+                auto local_desc = metadata_->segmentManager().getLocal();
+                if (local_desc)
+                    local_entry = local_desc->findBuffer(
+                        (uint64_t)request.source, request.length);
+            }
+            const BufferDesc* remote_entry =
+                xpu_staging_params[2].empty() ? entry : nullptr;
+            auto carries = [](const BufferDesc* buffer, TransportType type) {
+                return !buffer || std::find(buffer->transports.begin(),
+                                            buffer->transports.end(),
+                                            type) != buffer->transports.end();
+            };
+            for (auto type : {RDMA, TCP, HP_TCP}) {
+                if (transport_list_[type] && carries(local_entry, type) &&
+                    carries(remote_entry, type)) {
+                    staging_transports.push_back(type);
+                }
+            }
+        }
+    }
+    const bool xpu_staging = !xpu_staging_params.empty();
+
     // Legacy mode: use original logic (before TransportSelector)
-    if (transport_selector_ && transport_selector_->isLegacyMode()) {
+    if (transport_selector_ && transport_selector_->isLegacyMode() &&
+        !transport_selector_->isForceTcp()) {
         SelectionResult result;
         std::vector<TransportType> raw;
         if (desc->type == SegmentType::File) {
@@ -1057,15 +1545,21 @@ SelectionResult TransferEngineImpl::getTransportType(const Request& request,
                 }
                 auto remote_mtype =
                     getTypeEnum(LocationParser(entry->location).type());
-                for (auto type : entry->transports) {
-                    // NVLINK/SHM are same-machine only; TPU is a
-                    // local-stage-only executor and must never carry a remote
+                const auto& candidates =
+                    xpu_staging ? staging_transports : entry->transports;
+                for (auto type : candidates) {
+                    // NVLINK/SHM are same-machine only; TPU and Intel XPU are
+                    // local-stage-only executors and must never carry a remote
                     // hop.
+                    if (type == XPU && request.target_id != LOCAL_SEGMENT_ID)
+                        continue;
                     if ((type == NVLINK || type == SHM || type == TPU) &&
                         !same_machine)
                         continue;
-                    if (checkAvailability(transport_list_[type], local_mtype,
-                                          remote_mtype)) {
+                    if (checkAvailability(
+                            transport_list_[type],
+                            xpu_staging ? MTYPE_CPU : local_mtype,
+                            xpu_staging ? MTYPE_CPU : remote_mtype)) {
                         raw.push_back(type);
                     }
                 }
@@ -1079,6 +1573,7 @@ SelectionResult TransferEngineImpl::getTransportType(const Request& request,
         if (transport_index >= 0 &&
             (size_t)transport_index < candidates->size()) {
             result.transport = (*candidates)[transport_index];
+            result.staging_params = std::move(xpu_staging_params);
         }
         return result;
     }
@@ -1091,6 +1586,8 @@ SelectionResult TransferEngineImpl::getTransportType(const Request& request,
         request.priority;  // Use request priority for selection
     ctx.policy_name = request.policy_name;  // Optional: bind to specific policy
     ctx.intent_type = request.intent_type;  // Business intent policy filter
+    ctx.local_segment = request.target_id == LOCAL_SEGMENT_ID;
+    ctx.host_staging = xpu_staging;
 
     if (desc->type == SegmentType::File) {
         // File segment: use selector with empty buffer_transports
@@ -1112,11 +1609,15 @@ SelectionResult TransferEngineImpl::getTransportType(const Request& request,
         ctx.same_machine = same_machine;
         ctx.local_memory_type = local_mtype;
         ctx.remote_memory_type = remote_mtype;
-        ctx.buffer_transports = &entry->transports;
+        ctx.buffer_transports =
+            xpu_staging ? &staging_transports : &entry->transports;
     }
 
-    return transport_selector_->select(ctx, transport_list_, transport_index,
-                                       hint);
+    auto result = transport_selector_->select(ctx, transport_list_,
+                                              transport_index, hint);
+    if (result.transport != UNSPEC)
+        result.staging_params = std::move(xpu_staging_params);
+    return result;
 }
 
 std::string printRequest(const Request& request) {
@@ -1138,6 +1639,7 @@ struct BufferKey {
 struct RequestBoundaryInfo {
     std::optional<BufferKey> source_key;
     std::optional<BufferKey> target_key;
+    uint64_t max_merge_bytes{std::numeric_limits<uint64_t>::max()};
 };
 
 struct MergeResult {
@@ -1149,6 +1651,7 @@ struct TransferEngineImpl::PreparedSubmit {
     struct Task {
         size_t merged_task_index{0};
         size_t task_id{0};
+        size_t public_length{0};
     };
 
     struct Owner {
@@ -1162,6 +1665,7 @@ struct TransferEngineImpl::PreparedSubmit {
     };
 
     std::chrono::steady_clock::time_point submit_time{};
+    LogicalTransferRuntimePolicy runtime_policy;
     std::vector<Task> tasks;
     std::vector<Owner> owners;
 };
@@ -1230,6 +1734,14 @@ MergeResult mergeRequests(const std::vector<Request>& requests,
         if (last.req.transport_hint != curr.req.transport_hint) {
             return false;
         }
+        // These fields affect transport selection. Merging
+        // requests with different values would silently apply the first
+        // request's policy to the whole combined transfer.
+        if (last.req.priority != curr.req.priority ||
+            last.req.policy_name != curr.req.policy_name ||
+            last.req.intent_type != curr.req.intent_type) {
+            return false;
+        }
         if (!last.boundary.source_key || !curr.boundary.source_key ||
             !last.boundary.target_key || !curr.boundary.target_key) {
             return false;
@@ -1242,6 +1754,10 @@ MergeResult mergeRequests(const std::vector<Request>& requests,
             std::numeric_limits<size_t>::max() - last.req.length) {
             return false;
         }
+        // Requests to the same peer share the resolved transfer-size limit.
+        if (last.req.length + curr.req.length > last.boundary.max_merge_bytes) {
+            return false;
+        }
 
         uint64_t last_source_end = 0;
         uint64_t last_target_end = 0;
@@ -1281,7 +1797,8 @@ std::optional<BufferKey> toBufferKey(BufferDesc* buffer) {
 }
 
 std::vector<RequestBoundaryInfo> resolveRequestBoundaries(
-    ControlService* metadata, const std::vector<Request>& requests) {
+    ControlService* metadata, const std::vector<Request>& requests,
+    const HpTcpTransportConfig& hp_tcp_config) {
     // Group requests by target_id so withCachedSegment fires at most once per
     // peer.
     std::vector<RequestBoundaryInfo> boundaries(requests.size());
@@ -1305,9 +1822,28 @@ std::vector<RequestBoundaryInfo> resolveRequestBoundaries(
     for (auto& [target_id, idxs] : by_target) {
         metadata->segmentManager().withCachedSegment(
             target_id, [&](SegmentDesc* target_desc) {
+                auto hp_tcp_limit = hp_tcp_config.params.max_transfer_bytes;
+                if (hp_tcp_config.enabled && idxs.size() > 1 &&
+                    target_desc->type == SegmentType::Memory) {
+                    const auto* encoded =
+                        target_desc->getMemory().getTransportAttrs(HP_TCP);
+                    HighPerformanceTcpEndpointAttr endpoint;
+                    if (encoded && DecodeHighPerformanceTcpEndpointAttr(
+                                       *encoded, &endpoint)
+                                       .ok()) {
+                        hp_tcp_limit =
+                            std::min(hp_tcp_limit, endpoint.max_transfer_bytes);
+                    }
+                }
                 bool any_missing = false;
                 for (size_t i : idxs) {
                     const auto& r = requests[i];
+                    // UNSPEC may select HP TCP after merging. Respect both
+                    // endpoints' limits without changing explicit other hints.
+                    if (hp_tcp_config.enabled && (r.transport_hint == HP_TCP ||
+                                                  r.transport_hint == UNSPEC)) {
+                        boundaries[i].max_merge_bytes = hp_tcp_limit;
+                    }
                     auto* buffer =
                         target_desc->findBuffer(r.target_offset, r.length);
                     if (!buffer) {
@@ -1391,13 +1927,19 @@ void TransferEngineImpl::findStagingPolicy(const Request& request,
     if (transport_list_[MNNVL] && transport_list_[NVLINK]) {
         auto& xport = transport_list_[MNNVL];
         auto& caps = xport->capabilities();
+        // A remote host buffer is directly addressable only when the peer
+        // exported it over MNNVL (EGM); plain host memory still needs the
+        // staging path even if this side advertises dram_to_dram.
+        const bool remote_mnnvl =
+            std::find(entry->transports.begin(), entry->transports.end(),
+                      MNNVL) != entry->transports.end();
         if (local_mtype == MTYPE_CPU && remote_mtype == MTYPE_CPU &&
-            !caps.dram_to_dram) {
+            !(caps.dram_to_dram && remote_mnnvl)) {
             policy.push_back(server_addr);
             policy.push_back(topology_->findNearMem(local, Topology::MEM_CUDA));
             policy.push_back("");  // remote stage
         } else if (local_mtype == MTYPE_CUDA && remote_mtype == MTYPE_CPU &&
-                   !caps.gpu_to_dram) {
+                   !(caps.gpu_to_dram && remote_mnnvl)) {
             policy.push_back(server_addr);
             policy.push_back("");  // no local stage
             policy.push_back(desc->getMemory().topology.findNearMem(
@@ -1413,8 +1955,9 @@ void TransferEngineImpl::findStagingPolicy(const Request& request,
     // so TCP is selected when RDMA is absent. We also require TpuTransport (the
     // local HBM<->host executor), mirroring how the CUDA cases gate on NVLINK.
     // An empty stage location means "no staging needed on that side".
-    if (transport_list_[TPU] && (transport_list_[RDMA] || transport_list_[UB] ||
-                                 transport_list_[TCP])) {
+    if (transport_list_[TPU] &&
+        (transport_list_[RDMA] || transport_list_[UB] || transport_list_[TCP] ||
+         transport_list_[HP_TCP])) {
         if (local_mtype == MTYPE_TPU && remote_mtype == MTYPE_TPU) {
             policy.clear();
             policy.push_back(server_addr);
@@ -1432,6 +1975,46 @@ void TransferEngineImpl::findStagingPolicy(const Request& request,
             policy.push_back(desc->getMemory().topology.findNearMem(remote));
         }
     }
+    // case 4: Intel XPU. VRAM is not NIC-addressable, so any hop touching XPU
+    // memory is staged through host DRAM: XpuTransport performs the local
+    // VRAM<->host copy (via the SYCL backend) and the host<->host hop is
+    // carried by whatever host-DRAM network transport is present. We gate on
+    // RDMA/TCP/HP_TCP (the cross stage is routed by capability, so TCP is
+    // selected when RDMA is absent) and require XpuTransport (the local
+    // VRAM<->host executor), mirroring how the CUDA cases gate on NVLINK.
+    // Every device side is staged, including a mixed CUDA/ROCm/TPU peer whose
+    // direct-DMA capability is unknown here; a host DRAM side is not (empty
+    // stage location). A device side without a host DRAM stage location in
+    // its topology leaves the policy empty so the request fails closed rather
+    // than handing VRAM to a host-only transport.
+    if ((local_mtype == MTYPE_XPU || remote_mtype == MTYPE_XPU) &&
+        transport_list_[XPU] &&
+        (transport_list_[RDMA] || transport_list_[TCP] ||
+         transport_list_[HP_TCP])) {
+        std::string local_stage, remote_stage;
+        if (isGpuType(local_mtype)) {
+            local_stage = topology_->findNearMem(local);
+            if (local_stage.empty()) {
+                LOG(WARNING) << "No host DRAM stage location for local "
+                             << local << "; refusing to route device memory";
+                policy.clear();
+                return;
+            }
+        }
+        if (isGpuType(remote_mtype)) {
+            remote_stage = desc->getMemory().topology.findNearMem(remote);
+            if (remote_stage.empty()) {
+                LOG(WARNING) << "No host DRAM stage location for remote "
+                             << remote << "; refusing to route device memory";
+                policy.clear();
+                return;
+            }
+        }
+        policy.clear();
+        policy.push_back(server_addr);
+        policy.push_back(local_stage);
+        policy.push_back(remote_stage);
+    }
 }
 
 SelectionResult TransferEngineImpl::resolveTransport(const Request& req,
@@ -1455,24 +2038,66 @@ Status TransferEngineImpl::prepareSubmit(
     }
 
     prepared = PreparedSubmit{};
+    auto runtime_config = std::atomic_load_explicit(&runtime_config_snapshot_,
+                                                    std::memory_order_acquire);
+    prepared.runtime_policy.config_generation = runtime_config->generation;
+    prepared.runtime_policy.max_failover_attempts =
+        runtime_config->max_failover_attempts;
+    prepared.runtime_policy.enable_auto_failover_on_poll =
+        runtime_config->enable_auto_failover_on_poll;
     const size_t start_task_id = batch->task_list.size();
     prepared.submit_time = std::chrono::steady_clock::now();
     auto merge_boundaries =
         merge_requests_
-            ? resolveRequestBoundaries(metadata_.get(), request_list)
+            ? resolveRequestBoundaries(metadata_.get(), request_list,
+                                       hp_tcp_transport_config_)
             : std::vector<RequestBoundaryInfo>{};
     auto merged =
         mergeRequests(request_list, merge_boundaries, merge_requests_);
 
+    // Limit only oversized merges that would use standard TCP. In
+    // particular, an UNSPEC request selected for RDMA/HP TCP keeps its own
+    // transport's limits. Ordinary-size submissions need no extra route lookup
+    // or allocation here, and a too-large single request remains independent.
+    // This bounds initial TCP selection only. A later route change/failover
+    // to TCP can still reject an oversized owner; it is not split on retry.
+    if (merged.request_list.size() < request_list.size()) {
+        std::vector<bool> tcp_limited;
+        for (size_t i = 0; i < merged.request_list.size(); ++i) {
+            const auto& request = merged.request_list[i];
+            if (request.length <= tcpMaxTransferBytes(request.opcode)) continue;
+            if (request.transport_hint == TCP ||
+                (request.transport_hint == UNSPEC &&
+                 getTransportType(request, 0).transport == TCP)) {
+                if (tcp_limited.empty())
+                    tcp_limited.resize(merged.request_list.size(), false);
+                tcp_limited[i] = true;
+            }
+        }
+        if (!tcp_limited.empty()) {
+            for (const auto& [public_id, owner_id] : merged.task_lookup) {
+                if (tcp_limited[owner_id]) {
+                    auto& limit = merge_boundaries[public_id].max_merge_bytes;
+                    limit = std::min<uint64_t>(
+                        limit,
+                        tcpMaxTransferBytes(request_list[public_id].opcode));
+                }
+            }
+            merged = mergeRequests(request_list, merge_boundaries, true);
+        }
+    }
+
     prepared.owners.reserve(merged.request_list.size());
     for (const auto& request : merged.request_list) {
         PreparedSubmit::Owner owner;
         owner.request = request;
         owner.route = resolveTransport(owner.request, 0);
-        if (owner.route.transport == TCP) {
+        owner.staging_params = owner.route.staging_params;
+        if (owner.staging_params.empty() &&
+            (owner.route.transport == TCP || owner.route.transport == HP_TCP)) {
             findStagingPolicy(owner.request, owner.staging_params);
-            owner.staging = !owner.staging_params.empty() && staging_proxy_;
         }
+        owner.staging = !owner.staging_params.empty() && staging_proxy_;
         prepared.owners.push_back(std::move(owner));
     }
 
@@ -1488,7 +2113,8 @@ Status TransferEngineImpl::prepareSubmit(
         } else {
             owner.derived_task_ids.push_back(task_id);
         }
-        prepared.tasks.push_back({merged_task_index, task_id});
+        prepared.tasks.push_back({merged_task_index, task_id,
+                                  request_list[public_task_index].length});
     }
     return Status::OK();
 }
@@ -1507,15 +2133,21 @@ void TransferEngineImpl::attachProgressNotifier(
 Status TransferEngineImpl::commitPreparedSubmit(
     Batch* batch, const PreparedSubmit& prepared) {
     if (!batch) return Status::InvalidArgument("Invalid batch" LOC_MARK);
+    if (batch->task_list.size() > batch->max_size ||
+        prepared.tasks.size() > batch->max_size - batch->task_list.size()) {
+        return Status::TooManyRequests(
+            "batch public task capacity exceeded" LOC_MARK);
+    }
 
-    std::vector<Request> classified_request_list[kSupportedTransportTypes];
-    std::vector<size_t> task_id_list[kSupportedTransportTypes];
+    std::vector<size_t> physical_task_id_list[kSupportedTransportTypes];
     std::unordered_map<size_t, TaskInfo> merged_task_id_map;
 
     batch->task_list.insert(batch->task_list.end(), prepared.tasks.size(),
                             TaskInfo{});
 
-    std::unordered_map<TransportType, size_t> next_sub_task_id;
+    std::unordered_map<size_t, size_t> owner_task_id_by_merged_task;
+    std::unordered_map<size_t, std::vector<size_t>>
+        public_tasks_by_physical_owner;
     for (const auto& task_plan : prepared.tasks) {
         size_t task_id = task_plan.task_id;
         size_t merged_task_id = task_plan.merged_task_index;
@@ -1525,14 +2157,24 @@ Status TransferEngineImpl::commitPreparedSubmit(
         if (merged_task_id_map.count(merged_task_id)) {
             task = merged_task_id_map[merged_task_id];
             task.derived = true;
-            if (task.type != UNSPEC) task_id_list[task.type].push_back(task_id);
+            task.public_length = task_plan.public_length;
+            if (task.type != UNSPEC) {
+                auto owner_it =
+                    owner_task_id_by_merged_task.find(merged_task_id);
+                if (owner_it != owner_task_id_by_merged_task.end()) {
+                    public_tasks_by_physical_owner[owner_it->second].push_back(
+                        task_id);
+                }
+            }
             continue;
         }
 
         task.failover_count = 0;
         task.xport_priority = 0;
+        task.runtime_policy = prepared.runtime_policy;
         task.status = PENDING;
         task.request = merged_request;
+        task.public_length = task_plan.public_length;
         task.staging = false;
         task.start_time =
             prepared.submit_time;  // Record start time for latency tracking
@@ -1578,49 +2220,114 @@ Status TransferEngineImpl::commitPreparedSubmit(
             attachProgressNotifier(batch, batch->sub_batch[task.type]);
         }
 
-        if (!next_sub_task_id.count(task.type))
-            next_sub_task_id[task.type] = batch->sub_batch[task.type]->size();
-        size_t sub_task_id = next_sub_task_id[task.type];
-        next_sub_task_id[task.type]++;
-
-        classified_request_list[task.type].push_back(merged_request);
-        task.sub_task_id = sub_task_id;
+        task.sub_task_id = -1;
         task.derived = false;
-        task_id_list[task.type].push_back(task_id);
+        physical_task_id_list[task.type].push_back(task_id);
+        owner_task_id_by_merged_task[merged_task_id] = task_id;
+        public_tasks_by_physical_owner[task_id].push_back(task_id);
         merged_task_id_map[merged_task_id] = task;
     }
 
     for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
-        if (classified_request_list[type].empty()) continue;
+        if (physical_task_id_list[type].empty()) continue;
         auto& transport = transport_list_[type];
         auto& sub_batch = batch->sub_batch[type];
 
-        // RDMA and UB both spray slices across topology-selected NICs.
-        if ((type == RDMA || type == UB) && !task_id_list[type].empty()) {
-            // Use the device_mask from the first task (we assume all tasks in
-            // this batch should have the same policy)
-            sub_batch->device_mask =
-                batch->task_list[task_id_list[type][0]].device_mask;
-            if (type == RDMA) {
-                sub_batch->qp_pool =
-                    batch->task_list[task_id_list[type][0]].qp_pool;
+        // SubBatch carries one policy per submit call. Requests using the
+        // same transport may still resolve to different device masks or QP
+        // pools, so RDMA and UB owners must be submitted in homogeneous
+        // groups. RdmaTransport copies these scalar fields into each RdmaTask
+        // before returning, so groups can safely share one SubBatch.
+        std::vector<std::vector<size_t>> submit_groups;
+        if (type == RDMA || type == UB) {
+            std::map<std::pair<uint64_t, std::string>, size_t> group_by_policy;
+            for (const auto task_id : physical_task_id_list[type]) {
+                const auto& task = batch->task_list[task_id];
+                auto key = std::make_pair(task.device_mask, task.qp_pool);
+                auto [it, inserted] = group_by_policy.emplace(
+                    std::move(key), submit_groups.size());
+                if (inserted) submit_groups.emplace_back();
+                submit_groups[it->second].push_back(task_id);
             }
+        } else {
+            submit_groups.push_back(physical_task_id_list[type]);
         }
 
-        auto attempt_start = std::chrono::steady_clock::now();
-        for (auto& task_id : task_id_list[type]) {
-            startTransportAttempt(batch->task_list[task_id],
-                                  static_cast<TransportType>(type),
-                                  attempt_start);
-        }
-        auto status = transport->submitTransferTasks(
-            sub_batch, classified_request_list[type]);
-        if (!status.ok()) {
-            auto attempt_end = std::chrono::steady_clock::now();
-            for (auto& task_id : task_id_list[type]) {
-                finishTransportAttempt(batch->task_list[task_id], FAILED,
-                                       attempt_end);
-                batch->task_list[task_id].type = UNSPEC;
+        for (const auto& group : submit_groups) {
+            if (group.empty()) continue;
+
+            // A synchronous failure is allowed to return without appending
+            // anything to the SubBatch. Resolve IDs from the actual current
+            // size for each group so a failed earlier group cannot leave a gap
+            // in the IDs assigned to a later successful group. Propagate the
+            // physical ID to every merged public alias before submission so
+            // synchronous failure handling still sees a consistent mapping.
+            int next_sub_task_id = static_cast<int>(sub_batch->size());
+            for (const auto physical_task_id : group) {
+                for (const auto public_task_id :
+                     public_tasks_by_physical_owner.at(physical_task_id)) {
+                    batch->task_list[public_task_id].sub_task_id =
+                        next_sub_task_id;
+                }
+                ++next_sub_task_id;
+            }
+
+            if (type == RDMA || type == UB) {
+                const auto& first_task = batch->task_list[group.front()];
+                sub_batch->device_mask = first_task.device_mask;
+                if (type == RDMA) sub_batch->qp_pool = first_task.qp_pool;
+            }
+
+            std::vector<Request> requests;
+            requests.reserve(group.size());
+            for (const auto task_id : group)
+                requests.push_back(batch->task_list[task_id].request);
+
+            auto attempt_start = std::chrono::steady_clock::now();
+            for (const auto task_id : group) {
+                startTransportAttempt(batch->task_list[task_id],
+                                      static_cast<TransportType>(type),
+                                      attempt_start);
+            }
+            auto status = transport->submitTransferTasks(sub_batch, requests);
+            if (!status.ok()) {
+                auto attempt_end = std::chrono::steady_clock::now();
+                // failure_stage must be marked in this first segment, before
+                // any recovery/failover attempt on the failure: a task that
+                // recovers and later fails at poll must still attribute its
+                // root cause to submit.
+                for (const auto physical_task_id : group) {
+                    for (const auto public_task_id :
+                         public_tasks_by_physical_owner.at(physical_task_id)) {
+                        auto& task = batch->task_list[public_task_id];
+                        if (task.failure_stage < 0) task.failure_stage = 0;
+                        finishTransportAttempt(task, FAILED, attempt_end);
+                    }
+                }
+                // Recover by failing over to the remaining candidate
+                // transports instead of terminal-failing the tasks. Only
+                // physical (owner) tasks carry a submission: resubmitting a
+                // public alias would re-post the merged transfer (see
+                // docs/source/design/tent/failover.md, hazard 1).
+                for (const auto physical_task_id : group) {
+                    attemptSubmitStageFailover(batch, physical_task_id);
+                }
+                // Public aliases mirror their owner's recovered (or
+                // terminally failed) route so per-task status queries observe
+                // the same transport and sub-batch slot as the owner.
+                for (const auto physical_task_id : group) {
+                    const auto& owner_task = batch->task_list[physical_task_id];
+                    for (const auto public_task_id :
+                         public_tasks_by_physical_owner.at(physical_task_id)) {
+                        if (public_task_id == physical_task_id) continue;
+                        auto& task = batch->task_list[public_task_id];
+                        task.type = owner_task.type;
+                        task.sub_task_id = owner_task.sub_task_id;
+                        task.status = owner_task.status;
+                        task.failover_count = owner_task.failover_count;
+                        task.xport_priority = owner_task.xport_priority;
+                    }
+                }
             }
         }
     }
@@ -1654,6 +2361,11 @@ Status TransferEngineImpl::enqueuePreparedSubmit(Batch* batch,
         input.derived_task_ids = owner.derived_task_ids;
         input.request = owner.request;
         input.kind = owner_kind;
+        // The transport is snapshotted with the admission decision, so the
+        // degradation prediction reads the bandwidth of the transport selected
+        // here. A later transport failover does not revisit this owner: the
+        // prediction is a pre-dispatch heuristic, and re-scoring an admitted
+        // owner would let the drop decision change underneath it.
         input.transport = owner.route.transport;
         input.degradation_eligible =
             (owner.route.transport == RDMA || owner.route.transport == UB) &&
@@ -1672,8 +2384,10 @@ Status TransferEngineImpl::enqueuePreparedSubmit(Batch* batch,
         const auto& owner = prepared.owners[task_plan.merged_task_index];
         task.failover_count = 0;
         task.xport_priority = 0;
+        task.runtime_policy = prepared.runtime_policy;
         task.status = PENDING;
         task.request = owner.request;
+        task.public_length = task_plan.public_length;
         task.staging = false;
         task.start_time = prepared.submit_time;
         task.type = UNSPEC;
@@ -1778,14 +2492,16 @@ Status TransferEngineImpl::dispatchQueuedOwner(QueueOwnerId owner_id) {
     auto route = resolveTransport(task.request, 0);
     task.type = route.transport;
     task.device_mask = route.device_mask;
-    if (route.qp_pool) task.qp_pool = *route.qp_pool;
+    task.qp_pool = route.qp_pool.value_or("");
     if (task.type == UNSPEC) {
         return finishQueuedOwner(owner_id, FAILED);
     }
 
-    if (task.type == TCP) {
-        std::vector<std::string> staging_params;
-        findStagingPolicy(task.request, staging_params);
+    if (!route.staging_params.empty() || task.type == TCP ||
+        task.type == HP_TCP) {
+        auto staging_params = route.staging_params;
+        if (staging_params.empty())
+            findStagingPolicy(task.request, staging_params);
         if (!staging_params.empty() && staging_proxy_) {
             task.staging = true;
             // Orchestration only; the real transport submissions issued by
@@ -1819,16 +2535,23 @@ Status TransferEngineImpl::dispatchQueuedOwner(QueueOwnerId owner_id) {
     startTransportAttempt(task, task.type, std::chrono::steady_clock::now());
     auto status = transport->submitTransferTasks(sub_batch, {task.request});
     if (!status.ok()) {
+        if (task.failure_stage < 0) task.failure_stage = 0;
         finishTransportAttempt(task, FAILED, std::chrono::steady_clock::now());
-        task.type = UNSPEC;
+        // Submit-stage failover: walk the remaining candidate transports
+        // before giving up (the queued path dispatches one owner task at a
+        // time, so there are no derived aliases to mirror here).
+        if (attemptSubmitStageFailover(batch, queued.owner_task_id)) {
+            return markQueuedOwnerSubmitted(owner_id);
+        }
         return finishQueuedOwner(owner_id, FAILED);
     }
     return markQueuedOwnerSubmitted(owner_id);
 }
 
 Status TransferEngineImpl::refillDispatchWindow() {
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
+    // Queue is off by default; skip the global lock on the poll hot path.
     if (!runtime_queue_config_.enabled) return Status::OK();
+    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
     if (dispatch_inflight_owners_ >=
             runtime_queue_config_.max_dispatch_owners ||
         dispatch_inflight_bytes_ >= runtime_queue_config_.max_dispatch_bytes) {
@@ -1866,7 +2589,7 @@ Status TransferEngineImpl::progressRuntimeQueue() {
         auto& queued = queued_it->second;
         if (!queued.in_dispatch_window) continue;
         auto* batch = queued.batch;
-        if (!batch || !alive_batches_.count((BatchID)batch)) continue;
+        if (!batch || !isBatchAlive((BatchID)batch)) continue;
         if (queued.owner_task_id >= batch->task_list.size()) {
             return Status::InternalError(
                 "queued owner task id out of range" LOC_MARK);
@@ -1968,10 +2691,11 @@ Status TransferEngineImpl::maybeFireSubmitHooks(Batch* batch, bool check) {
             for (size_t tid = hook.start_task_id; tid < hook.end_task_id;
                  ++tid) {
                 auto& t = batch->task_list[tid];
-                if (t.status == PENDING) {
-                    all_completed = false;
-                    break;
-                }
+                // Merged requests are carried by one owning task; the derived
+                // ones keep their initial status forever, so checking them
+                // would make this hook never fire. getBatchStatus() skips them
+                // for the same reason.
+                if (t.derived) continue;
                 if (t.status != COMPLETED) {
                     all_completed = false;
                     break;
@@ -1979,15 +2703,26 @@ Status TransferEngineImpl::maybeFireSubmitHooks(Batch* batch, bool check) {
             }
         }
         if (!all_completed) continue;
-        Status last = Status::OK();
-        for (auto target_id : hook.targets) {
-            last = sendNotification(target_id, hook.notifi);
-            if (!last.ok()) {
-                LOG(WARNING) << "sendNotification failed: " << last.ToString();
-                break;
+        // Drop each target as it takes delivery and carry the rest to a later
+        // poll. The hook is only marked fired once every target has, so the
+        // ones that already succeeded must not be notified again.
+        //
+        // Every remaining target is attempted on every pass, including the
+        // ones after a failure. targets is an unordered_set, so stopping at
+        // the first failure would make delivery to the others depend on
+        // iteration order: an unreachable peer visited first would hold back
+        // a self-targeted notification that cannot fail, and its receiver
+        // would block until that unrelated peer came back.
+        for (auto it = hook.targets.begin(); it != hook.targets.end();) {
+            auto status = sendNotification(*it, hook.notifi);
+            if (status.ok()) {
+                it = hook.targets.erase(it);
+                continue;
             }
+            LOG(WARNING) << "sendNotification failed: " << status.ToString();
+            ++it;
         }
-        if (last.ok()) hook.fired = true;
+        if (hook.targets.empty()) hook.fired = true;
     }
     return Status::OK();
 }
@@ -2001,8 +2736,8 @@ Status TransferEngineImpl::submitTransfer(
 
 Status TransferEngineImpl::cancelTransfer(BatchID batch_id, size_t task_id) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id)) {
+    std::lock_guard<std::recursive_mutex> lk(progressLockFor(batch_id));
+    if (!isBatchAlive(batch_id)) {
         return Status::InvalidArgument("Batch is not alive" LOC_MARK);
     }
     auto* batch = reinterpret_cast<Batch*>(batch_id);
@@ -2072,9 +2807,9 @@ Status TransferEngineImpl::resubmitTransferTask(Batch* batch, size_t task_id) {
     auto& task = batch->task_list[task_id];
     auto prev_type = task.type;
 
-    if (++task.failover_count > max_failover_attempts_) {
+    if (++task.failover_count > task.runtime_policy.max_failover_attempts) {
         LOG(WARNING) << "Task failover limit reached ("
-                     << max_failover_attempts_
+                     << task.runtime_policy.max_failover_attempts
                      << "), last transport=" << transportTypeName(prev_type);
         return Status::InvalidEntry(
             "Failover limit exceeded, all transports exhausted");
@@ -2088,16 +2823,35 @@ Status TransferEngineImpl::resubmitTransferTask(Batch* batch, size_t task_id) {
     auto result = resolveTransport(task.request, task.xport_priority);
     auto type = result.transport;
     if (type == UNSPEC) {
-        LOG(WARNING) << "No more transports available after "
-                     << transportTypeName(prev_type) << " failed";
+        VLOG(1) << "No more transports available after "
+                << transportTypeName(prev_type) << " failed";
+        LOG_EVERY_N(WARNING, 100) << "No more transports available after "
+                                  << transportTypeName(prev_type) << " failed";
         return Status::InvalidEntry("All available transports are failed");
     }
 
-    LOG(INFO) << "Transport failover: " << transportTypeName(prev_type)
-              << " -> " << transportTypeName(type) << " (attempt "
-              << task.failover_count << "/" << max_failover_attempts_ << ")";
+    LOG_EVERY_N(INFO, 1000)
+        << "Transport failover: " << transportTypeName(prev_type) << " -> "
+        << transportTypeName(type) << " (attempt " << task.failover_count << "/"
+        << task.runtime_policy.max_failover_attempts << ", generation "
+        << task.runtime_policy.config_generation << ")";
+    VLOG(1) << "Transport failover: " << transportTypeName(prev_type) << " -> "
+            << transportTypeName(type) << " (attempt " << task.failover_count
+            << "/" << task.runtime_policy.max_failover_attempts
+            << ", generation " << task.runtime_policy.config_generation << ")";
     TENT_RECORD_TRANSPORT_FAILOVER(prev_type, type);
 
+    // A failed XPU staging operation must never fall through to submitting
+    // the original VRAM addresses to a host-only network transport.
+    if (!result.staging_params.empty()) {
+        task.type = type;
+        task.device_mask = result.device_mask;
+        task.qp_pool = result.qp_pool.value_or("");
+        task.staging = true;
+        return staging_proxy_->submit(&task, (BatchID)batch,
+                                      result.staging_params);
+    }
+
     auto& transport = transport_list_[type];
     if (!batch->sub_batch[type]) {
         CHECK_STATUS(transport->allocateSubBatch(batch->sub_batch[type],
@@ -2105,16 +2859,54 @@ Status TransferEngineImpl::resubmitTransferTask(Batch* batch, size_t task_id) {
         attachProgressNotifier(batch, batch->sub_batch[type]);
     }
     auto& sub_batch = batch->sub_batch[type];
+    task.device_mask = result.device_mask;
+    task.qp_pool = result.qp_pool.value_or("");
+    if (type == RDMA) {
+        sub_batch->device_mask = task.device_mask;
+        sub_batch->qp_pool = task.qp_pool;
+    }
     task.sub_task_id = sub_batch->size();
     task.type = type;
     startTransportAttempt(task, type, std::chrono::steady_clock::now());
     auto status = transport->submitTransferTasks(sub_batch, {task.request});
     if (!status.ok()) {
+        if (task.failure_stage < 0) task.failure_stage = 0;
         finishTransportAttempt(task, FAILED, std::chrono::steady_clock::now());
     }
     return status;
 }
 
+bool TransferEngineImpl::attemptSubmitStageFailover(Batch* batch,
+                                                    size_t task_id) {
+    auto& task = batch->task_list[task_id];
+    // Mark terminal first so a concurrent poll cannot observe a task that is
+    // half-migrated to its fallback transport (mirrors the poll-time
+    // failover in updateTaskStatusAfterPoll, which sets task.status = FAILED
+    // before calling resubmitTransferTask).
+    task.status = FAILED;
+    for (int attempt = 0; attempt < task.runtime_policy.max_failover_attempts;
+         ++attempt) {
+        if (resubmitTransferTask(batch, task_id).ok()) {
+            task.status = PENDING;
+            return true;
+        }
+        // resubmitTransferTask() already finished the failed attempt, logged
+        // the reason and advanced the candidate cursor; the next iteration
+        // tries the following transport until the candidates or the failover
+        // budget are exhausted.
+    }
+    // Terminally failed: record the logical outcome here. The poll paths only
+    // record tasks transitioning out of PENDING, so they would never observe
+    // this task's PENDING -> FAILED transition. Record BEFORE resetting
+    // task.type so the failure is attributed to the last attempted transport.
+    recordTaskCompletionMetrics(task, PENDING, FAILED);
+    // Reset to UNSPEC so pollTaskStatus()'s UNSPEC short-circuit applies: the
+    // last failed submit never created a sub-batch entry for this task, so
+    // there is nothing to poll on the transport.
+    task.type = UNSPEC;
+    return false;
+}
+
 Status TransferEngineImpl::pollTaskStatus(Batch* batch, size_t task_id,
                                           TransferStatus& task_status) {
     auto& task = batch->task_list[task_id];
@@ -2133,8 +2925,66 @@ Status TransferEngineImpl::pollTaskStatus(Batch* batch, size_t task_id,
     if (!transport || !sub_batch) {
         return Status::InvalidArgument("Transport not available" LOC_MARK);
     }
-    return transport->getTransferStatus(sub_batch, task.sub_task_id,
-                                        task_status);
+    // HP TCP classifies transport errors using the terminal output. Other
+    // transports retain their existing error-output contract.
+    if (task.type == HP_TCP) task_status = {PENDING, 0};
+    Status result =
+        transport->getTransferStatus(sub_batch, task.sub_task_id, task_status);
+    if (task.type == TCP && task_status.s == FAILED &&
+        result.IsRpcServiceError()) {
+        // Standard TCP reports an uncertain WRITE through this error result.
+        finishTransportAttempt(task, FAILED, std::chrono::steady_clock::now());
+        task.suppress_failover = true;
+        return Status::OK();
+    }
+    if (result.ok() || task.type != HP_TCP || task_status.s != FAILED) {
+        return result;
+    }
+
+    if (result.IsNeedsRefreshCache()) {
+        finishTransportAttempt(task, FAILED, std::chrono::steady_clock::now());
+        if (task.metadata_refresh_retry_count >=
+            kMaxHpTcpMetadataRefreshRetries) {
+            task.suppress_failover = true;
+            return Status::OK();
+        }
+        ++task.metadata_refresh_retry_count;
+        Status invalidated = metadata_->segmentManager().invalidateRemote(
+            task.request.target_id);
+        if (!invalidated.ok()) {
+            task.suppress_failover = true;
+            LOG(WARNING) << "HP TCP metadata cache invalidation failed: "
+                         << invalidated.ToString();
+            return Status::OK();
+        }
+
+        const auto retry_start = std::chrono::steady_clock::now();
+        startTransportAttempt(task, HP_TCP, retry_start);
+        Status retried = transport->retryTransferTask(
+            sub_batch, task.sub_task_id, task.request);
+        if (!retried.ok()) {
+            finishTransportAttempt(task, FAILED,
+                                   std::chrono::steady_clock::now());
+            task.suppress_failover = true;
+            LOG(WARNING) << "HP TCP metadata refresh retry failed: "
+                         << retried.ToString();
+            return Status::OK();
+        }
+        task.status = PENDING;
+        task_status.s = PENDING;
+        task_status.transferred_bytes = 0;
+        return Status::OK();
+    }
+
+    // A valid remote permission/range/protocol rejection, or a WRITE whose
+    // remote outcome is unknown because its ACK was lost, is permanent for
+    // this logical request. ShuttingDown maps to TooManyRequests and remains
+    // transient, so the existing failover policy may act on it.
+    if (!result.IsTooManyRequests()) {
+        finishTransportAttempt(task, FAILED, std::chrono::steady_clock::now());
+        task.suppress_failover = true;
+    }
+    return Status::OK();
 }
 
 void TransferEngineImpl::updateTaskStatusAfterPoll(Batch* batch, size_t task_id,
@@ -2142,8 +2992,16 @@ void TransferEngineImpl::updateTaskStatusAfterPoll(Batch* batch, size_t task_id,
                                                    bool allow_failover) {
     auto& task = batch->task_list[task_id];
     task.status = task_status.s;
-    if (!allow_failover || task.cancel_requested || task_status.s != FAILED ||
-        task.type == UNSPEC)
+    // First-failure attribution: a terminal failure observed by polling marks
+    // the poll stage. Submit-stage failures were already marked at their
+    // origin and are not overwritten (a poll failure followed by a rejected
+    // failover resubmit still counts as poll).
+    if (task_status.s == FAILED || task_status.s == TIMEOUT ||
+        task_status.s == CANCELED) {
+        if (task.failure_stage < 0) task.failure_stage = 1;
+    }
+    if (!allow_failover || task.cancel_requested || task.suppress_failover ||
+        task_status.s != FAILED || task.type == UNSPEC)
         return;
 
     // The current physical transport attempt has failed even if the logical
@@ -2158,12 +3016,72 @@ void TransferEngineImpl::updateTaskStatusAfterPoll(Batch* batch, size_t task_id,
 
 Status TransferEngineImpl::sendNotification(SegmentID target_id,
                                             const Notification& notifi) {
+    if (target_id == LOCAL_SEGMENT_ID) {
+        // Self-targeted notification: deliver in-process. The data plane
+        // already short-circuits LOCAL_SEGMENT_ID transfers to the local
+        // path; notifications need the same treatment. Routing them through
+        // a transport cannot work: the RDMA local pseudo-endpoint never
+        // establishes a notification QP, so sending fails and the receiver
+        // polls forever.
+        std::lock_guard<std::mutex> lk(local_notifi_mutex_);
+        local_notifi_list_.push_back(notifi);
+        return Status::OK();
+    }
+    // Transports are tried in slot order, RDMA before TCP, so with TCP loaded
+    // the fallback is its own RPC-based sendNotification(); the explicit RPC
+    // below is for engines without one. Only a transport whose channel is
+    // unavailable is skipped - the endpoint could not be brought up or the
+    // notification channel on it is gone, so nothing left this host. Any
+    // other error (bad argument, stale cache) is the caller's to see, and a
+    // notification that was posted but lost in flight is out of scope here:
+    // resending it would need receiver-side deduplication first.
+    bool attempted = false;
+    Status status;
     for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
         auto& transport = transport_list_[type];
         if (!transport || !transport->supportNotification()) continue;
-        return transport->sendNotification(target_id, notifi);
+        Status attempt = transport->sendNotification(target_id, notifi);
+        // A transport that advertises notifications without implementing
+        // them (SunriseLink) is not a channel at all.
+        if (attempt.IsNotImplemented()) continue;
+        attempted = true;
+        status = attempt;
+        if (status.ok()) return status;
+        if (!notify_rpc_fallback_ ||
+            !(status.IsRdmaError() || status.IsDeviceNotFound())) {
+            return status;
+        }
+        LOG_EVERY_N(WARNING, 100)
+            << "Notification transport " << transport->getName()
+            << " unavailable for segment " << target_id
+            << ", falling back to the next path (" << google::COUNTER
+            << " so far): " << status.ToString();
     }
-    return Status::InvalidArgument("Notification not supported" LOC_MARK);
+    if (!attempted)
+        return Status::InvalidArgument("Notification not supported" LOC_MARK);
+    // Every loaded notification transport reported its channel unavailable;
+    // the control plane the peer answers bootstrap on is still there.
+    return sendNotificationViaRpc(target_id, notifi);
+}
+
+Status TransferEngineImpl::sendNotificationViaRpc(SegmentID target_id,
+                                                  const Notification& notifi) {
+    return metadata_->segmentManager().withCachedSegment(
+        target_id, [&](SegmentDesc* segment) {
+            auto rpc_server_addr = segment->rpc_server_addr;
+            if (rpc_server_addr.empty()) {
+                return Status::NeedsRefreshCache(
+                    "Empty RPC server addr" LOC_MARK);
+            }
+            auto status = ControlClient::notify(rpc_server_addr, notifi);
+            if (status.IsRpcServiceError()) {
+                // Perhaps rpc_server_addr can be updated in the future
+                return Status::NeedsRefreshCache(
+                    "RPC service error: " + std::string{status.message()} +
+                    LOC_MARK);
+            }
+            return status;
+        });
 }
 
 Status TransferEngineImpl::probePeerAliveByID(SegmentID target_id) {
@@ -2187,19 +3105,64 @@ Status TransferEngineImpl::probePeerAliveByID(SegmentID target_id) {
 
 Status TransferEngineImpl::receiveNotification(
     std::vector<Notification>& notifi_list) {
+    // Each poll reports what this poll delivered. Callers reuse one vector
+    // across polls, and appending to leftovers would redeliver what the
+    // caller already handled.
+    notifi_list.clear();
+    Status status = Status::OK();
+    bool has_transport = false;
+    // A notification is queued by whichever transport carried it: the RDMA
+    // transport for its notify QP, the TCP transport for anything that came
+    // over the control plane. Draining only the first transport would strand
+    // the rest. Each one is polled into its own vector because
+    // TcpTransport::receiveNotification() clears its argument first.
     for (size_t type = 0; type < kSupportedTransportTypes; ++type) {
         auto& transport = transport_list_[type];
         if (!transport || !transport->supportNotification()) continue;
-        return transport->receiveNotification(notifi_list);
+        std::vector<Notification> part;
+        Status part_status = transport->receiveNotification(part);
+        // Advertised but not implemented (SunriseLink): no queue to drain.
+        if (part_status.IsNotImplemented()) continue;
+        has_transport = true;
+        if (!part_status.ok()) {
+            status = part_status;
+            continue;
+        }
+        if (notifi_list.empty()) {
+            notifi_list.swap(part);
+        } else {
+            notifi_list.insert(notifi_list.end(),
+                               std::make_move_iterator(part.begin()),
+                               std::make_move_iterator(part.end()));
+        }
     }
-    return Status::InvalidArgument("Notification not supported" LOC_MARK);
+    // Append self-targeted notifications queued by sendNotification(). They
+    // are deliverable even when no transport supports notifications at all,
+    // and they do not depend on the transport poll having succeeded.
+    {
+        std::lock_guard<std::mutex> lk(local_notifi_mutex_);
+        if (!local_notifi_list_.empty()) {
+            notifi_list.insert(
+                notifi_list.end(),
+                std::make_move_iterator(local_notifi_list_.begin()),
+                std::make_move_iterator(local_notifi_list_.end()));
+            local_notifi_list_.clear();
+        }
+    }
+    // Whatever landed in the list has been consumed from its queue, so the
+    // caller has to see it: report success here and let a later poll -- which
+    // comes back empty -- surface a persistent transport error.
+    if (!notifi_list.empty()) return Status::OK();
+    if (!has_transport)
+        return Status::InvalidArgument("Notification not supported" LOC_MARK);
+    return status;
 }
 
 Status TransferEngineImpl::getTransferStatus(BatchID batch_id, size_t task_id,
                                              TransferStatus& task_status) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id))
+    std::lock_guard<std::recursive_mutex> lk(progressLockFor(batch_id));
+    if (!isBatchAlive(batch_id))
         return Status::InvalidArgument("Batch is not alive" LOC_MARK);
     Batch* batch = (Batch*)(batch_id);
     if (task_id >= batch->task_list.size())
@@ -2222,7 +3185,7 @@ Status TransferEngineImpl::getTransferStatus(BatchID batch_id, size_t task_id,
                 task_status.s = public_status;
                 task_status.transferred_bytes =
                     public_status == COMPLETED
-                        ? batch->task_list[public_task_id].request.length
+                        ? batch->task_list[public_task_id].public_length
                         : 0;
                 return Status::OK();
             }
@@ -2236,7 +3199,7 @@ Status TransferEngineImpl::getTransferStatus(BatchID batch_id, size_t task_id,
     auto prev_status = task.status;
     CHECK_STATUS(pollTaskStatus(batch, poll_task_id, task_status));
     updateTaskStatusAfterPoll(batch, poll_task_id, task_status,
-                              enable_auto_failover_on_poll_);
+                              task.runtime_policy.enable_auto_failover_on_poll);
     if (runtime_queue_config_.enabled && batch->queue_token != 0 &&
         task_status.s != PENDING) {
         QueueOwnerId owner_id = 0;
@@ -2252,15 +3215,19 @@ Status TransferEngineImpl::getTransferStatus(BatchID batch_id, size_t task_id,
     recordTaskCompletionMetrics(batch->task_list[poll_task_id], prev_status,
                                 task_status.s);
 
-    if (task_status.s == COMPLETED) CHECK_STATUS(maybeFireSubmitHooks(batch));
+    if (task_status.s == COMPLETED) {
+        task_status.transferred_bytes =
+            batch->task_list[public_task_id].public_length;
+        CHECK_STATUS(maybeFireSubmitHooks(batch));
+    }
     return Status::OK();
 }
 
 Status TransferEngineImpl::getTransferStatus(
     BatchID batch_id, std::vector<TransferStatus>& status_list) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id))
+    std::lock_guard<std::recursive_mutex> lk(progressLockFor(batch_id));
+    if (!isBatchAlive(batch_id))
         return Status::InvalidArgument("Batch is not alive" LOC_MARK);
     Batch* batch = (Batch*)(batch_id);
     status_list.clear();
@@ -2274,10 +3241,10 @@ Status TransferEngineImpl::getTransferStatus(
 
 Status TransferEngineImpl::getBatchStatus(BatchID batch_id,
                                           TransferStatus& overall_status,
-                                          bool allow_failover) {
+                                          bool force_failover) {
     if (!batch_id) return Status::InvalidArgument("Invalid batch ID" LOC_MARK);
-    std::lock_guard<std::recursive_mutex> lk(progress_mutex_);
-    if (!alive_batches_.count(batch_id))
+    std::lock_guard<std::recursive_mutex> lk(progressLockFor(batch_id));
+    if (!isBatchAlive(batch_id))
         return Status::InvalidArgument("Batch is not alive" LOC_MARK);
     CHECK_STATUS(refillDispatchWindow());
     Batch* batch = (Batch*)(batch_id);
@@ -2288,11 +3255,7 @@ Status TransferEngineImpl::getBatchStatus(BatchID batch_id,
     size_t total_tasks = 0;
     TransferStatusEnum worst_failure = PENDING;
     auto isWorse = [](TransferStatusEnum cur, TransferStatusEnum best) {
-        static const std::unordered_map<TransferStatusEnum, int> severity = {
-            {INITIAL, 0},  {PENDING, 0}, {COMPLETED, 0}, {INVALID, 1},
-            {CANCELED, 2}, {TIMEOUT, 3}, {FAILED, 4},
-        };
-        return severity.at(cur) > severity.at(best);
+        return transferStatusSeverity(cur) > transferStatusSeverity(best);
     };
     for (size_t task_id = 0; task_id < batch->task_list.size(); ++task_id) {
         auto& task = batch->task_list[task_id];
@@ -2340,7 +3303,9 @@ Status TransferEngineImpl::getBatchStatus(BatchID batch_id,
         }
         auto prev_status = task.status;
         CHECK_STATUS(pollTaskStatus(batch, task_id, task_status));
-        updateTaskStatusAfterPoll(batch, task_id, task_status, allow_failover);
+        updateTaskStatusAfterPoll(
+            batch, task_id, task_status,
+            force_failover || task.runtime_policy.enable_auto_failover_on_poll);
         if (runtime_queue_config_.enabled && batch->queue_token != 0 &&
             task_status.s != PENDING) {
             QueueOwnerId owner_id = 0;
@@ -2374,14 +3339,15 @@ Status TransferEngineImpl::getBatchStatus(BatchID batch_id,
         overall_status.s = worst_failure;
     }
     // else: some tasks still PENDING → overall_status.s stays PENDING
-    CHECK_STATUS(maybeFireSubmitHooks(batch, overall_status.s == COMPLETED));
+    // A hook belongs to its own submit interval. Other intervals can still
+    // be pending or failed without withholding this interval's notification.
+    CHECK_STATUS(maybeFireSubmitHooks(batch));
     return Status::OK();
 }
 
 Status TransferEngineImpl::getTransferStatus(BatchID batch_id,
                                              TransferStatus& overall_status) {
-    return getBatchStatus(batch_id, overall_status,
-                          enable_auto_failover_on_poll_);
+    return getBatchStatus(batch_id, overall_status, false);
 }
 
 Status TransferEngineImpl::progressBatch(BatchID batch_id,
@@ -2408,37 +3374,93 @@ void TransferEngineImpl::notifyRuntimeQueueReady() {
     if (progress_worker_) progress_worker_->notifyRuntimeQueueReady();
 }
 
+std::chrono::microseconds nextPollDelay(uint64_t poll_count) {
+    // Covers a fast completion, so short transfers usually finish before the
+    // sleeping phase.
+    constexpr uint64_t kHotPolls = 128;
+    constexpr auto kMaxDelay = std::chrono::microseconds(200);
+    if (poll_count < kHotPolls) return std::chrono::microseconds(0);
+    const uint64_t shift = std::min<uint64_t>(poll_count - kHotPolls, 20);
+    const auto delay = std::chrono::microseconds(uint64_t(1) << shift);
+    return delay < kMaxDelay ? delay : kMaxDelay;
+}
+
+void waitBeforeNextPoll(uint64_t poll_count) {
+    const auto delay = nextPollDelay(poll_count);
+    if (delay.count() == 0)
+        std::this_thread::yield();
+    else
+        std::this_thread::sleep_for(delay);
+}
+
+namespace {
+// Frees the batch on every exit unless reset() already did. The wait loops
+// below leave through CHECK_STATUS early returns that used to skip freeBatch()
+// and leak the Batch slab with whatever SubBatches it held.
+class BatchGuard {
+   public:
+    BatchGuard(TransferEngineImpl& engine, BatchID batch_id)
+        : engine_(engine), batch_id_(batch_id) {}
+
+    ~BatchGuard() {
+        auto status = reset();
+        if (!status.ok())
+            LOG(WARNING) << "failed to free batch: " << status.ToString();
+    }
+
+    BatchGuard(const BatchGuard&) = delete;
+    BatchGuard& operator=(const BatchGuard&) = delete;
+
+    Status reset() {
+        if (!batch_id_) return Status::OK();
+        auto batch_id = batch_id_;
+        batch_id_ = 0;
+        return engine_.freeBatch(batch_id);
+    }
+
+   private:
+    TransferEngineImpl& engine_;
+    BatchID batch_id_;
+};
+}  // namespace
+
 Status TransferEngineImpl::waitTransferCompletion(BatchID batch_id) {
+    BatchGuard batch_guard(*this, batch_id);
     TransferStatus xfer_status;
-    while (true) {
+    for (uint64_t poll_count = 0;; ++poll_count) {
         CHECK_STATUS(progressBatch(batch_id, xfer_status));
         if (xfer_status.s != PENDING) {
-            freeBatch(batch_id);
+            // Deliberately dropping the free status, as the pre-existing code
+            // did: callers of this path get the transfer outcome, not the
+            // cleanup outcome. transferSync() propagates it instead.
+            (void)batch_guard.reset();
             return xfer_status.s == COMPLETED
                        ? Status::OK()
                        : Status::InternalError(
                              "Transfer failed: " +
                              std::to_string((int)xfer_status.s));
         }
+        waitBeforeNextPoll(poll_count);
     }
 }
 
 Status TransferEngineImpl::transferSync(
     const std::vector<Request>& request_list) {
     auto batch_id = allocateBatch(request_list.size());
+    BatchGuard batch_guard(*this, batch_id);
     CHECK_STATUS(submitTransfer(batch_id, request_list));
-    while (true) {
+    for (uint64_t poll_count = 0;; ++poll_count) {
         TransferStatus xfer_status;
         CHECK_STATUS(progressBatch(batch_id, xfer_status));
         if (xfer_status.s == COMPLETED) break;
         if (xfer_status.s != PENDING) {
-            CHECK_STATUS(freeBatch(batch_id));
+            CHECK_STATUS(batch_guard.reset());
             return Status::InternalError(
                 "Transfer via stage buffer failed" LOC_MARK);
         }
+        waitBeforeNextPoll(poll_count);
     }
-    CHECK_STATUS(freeBatch(batch_id));
-    return Status::OK();
+    return batch_guard.reset();
 }
 
 uint64_t TransferEngineImpl::lockStageBuffer(const std::string& location) {
@@ -2458,6 +3480,35 @@ void TransferEngineImpl::recordTaskCompletionMetrics(
 #if TENT_METRICS_ENABLED
     if (prev_status == PENDING && new_status != PENDING && !task.derived) {
         auto end_time = std::chrono::steady_clock::now();
+        // Failure reason: task.failure_stage marks where the first failure
+        // originated (0 = submit, 1 = poll), set at the failure site — a
+        // poll-observed failure stays "poll" even when the failover resubmit
+        // is synchronously rejected. TIMEOUT/CANCELED come from the status
+        // itself and were previously not recorded anywhere.
+        if (new_status == FAILED || new_status == TIMEOUT ||
+            new_status == CANCELED) {
+            TentMetrics::TaskFailureReason reason;
+            if (new_status == TIMEOUT) {
+                reason = TentMetrics::TaskFailureReason::Timeout;
+            } else if (new_status == CANCELED) {
+                reason = TentMetrics::TaskFailureReason::Canceled;
+            } else if (task.failure_stage == 0) {
+                reason = TentMetrics::TaskFailureReason::Submit;
+            } else if (task.failure_stage == 1) {
+                reason = TentMetrics::TaskFailureReason::Poll;
+            } else {
+                // Unmarked path: an attempt still in flight means the
+                // failure was observed by polling.
+                reason = task.attempt_active
+                             ? TentMetrics::TaskFailureReason::Poll
+                             : TentMetrics::TaskFailureReason::Submit;
+            }
+            // Prefer the attempt transport: task.type may already be UNSPEC
+            // after a submit-stage failure.
+            TransportType failure_tp =
+                task.attempt_type != UNSPEC ? task.attempt_type : task.type;
+            TentMetrics::instance().recordTaskFailure(failure_tp, reason);
+        }
         finishTransportAttempt(task, new_status, end_time);
         auto start_time = task.start_time;
         if (start_time.time_since_epoch().count() > 0) {
@@ -2499,10 +3550,17 @@ void TransferEngineImpl::recordTaskCompletionMetrics(
                     }
                 }
             } else if (new_status == FAILED) {
+                // A task whose type is UNSPEC (no candidate ever resolved,
+                // or a legacy submit-stage failure clobbered it) has lost its
+                // transport attribution; fall back to the last physical
+                // attempt's transport so terminal failures are not
+                // mislabeled "unspec".
+                const auto attributed_type =
+                    task.type != UNSPEC ? task.type : task.attempt_type;
                 if (task.request.opcode == Request::READ) {
-                    TentMetrics::instance().recordReadFailed(task.type);
+                    TentMetrics::instance().recordReadFailed(attributed_type);
                 } else {
-                    TentMetrics::instance().recordWriteFailed(task.type);
+                    TentMetrics::instance().recordWriteFailed(attributed_type);
                 }
             }
             // Observability only (RFC #2519): deadline feasibility. The
@@ -2552,6 +3610,7 @@ void TransferEngineImpl::startTransportAttempt(
 #if TENT_METRICS_ENABLED
     TentMetrics::instance().recordTransportAttemptStarted(type,
                                                           task.request.opcode);
+    TentMetrics::instance().recordInflightAttemptStarted(type);
 #else
     (void)type;
 #endif
@@ -2563,6 +3622,10 @@ void TransferEngineImpl::finishTransportAttempt(
     if (!task.attempt_active) return;
     task.attempt_active = false;
 #if TENT_METRICS_ENABLED
+    // Decrement before the early return below so the in-flight gauge stays
+    // symmetric with recordInflightAttemptStarted() for every attempt that
+    // actually started.
+    TentMetrics::instance().recordInflightAttemptFinished(task.attempt_type);
     auto post_time = task.attempt_post_time;
     if (post_time.time_since_epoch().count() == 0) return;
     double latency_us =
diff --git a/mooncake-transfer-engine/tent/src/runtime/transport_loader.cpp b/mooncake-transfer-engine/tent/src/runtime/transport_loader.cpp
index 2a3b9236f7..08a0b75eff 100644
--- a/mooncake-transfer-engine/tent/src/runtime/transport_loader.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/transport_loader.cpp
@@ -15,6 +15,7 @@
 #include "tent/runtime/transfer_engine_impl.h"
 #include "tent/transport/shm/shm_transport.h"
 #include "tent/transport/tcp/tcp_transport.h"
+#include "tent/transport/hp_tcp/hp_tcp_transport.h"
 
 #ifdef USE_RDMA
 #include "tent/transport/rdma/rdma_transport.h"
@@ -49,6 +50,14 @@
 #include "tent/transport/tpu/tpu_transport.h"
 #endif
 
+#ifdef USE_XPU
+#include "tent/transport/xpu/xpu_transport.h"
+#endif
+
+#ifdef USE_MPCOMM
+#include "tent/transport/mpcomm/mpcomm_transport.h"
+#endif
+
 namespace mooncake {
 namespace tent {
 
@@ -56,6 +65,10 @@ Status TransferEngineImpl::loadTransports() {
     if (conf_->get("transports/tcp/enable", true))
         transport_list_[TCP] = std::make_shared<TcpTransport>();
 
+    if (hp_tcp_transport_config_.enabled)
+        transport_list_[HP_TCP] = std::make_shared<HighPerformanceTcpTransport>(
+            hp_tcp_transport_config_.params);
+
     // SHM is opt-in: default false because the current path is not NUMA-aware
     // (see tent/config/transfer-engine.json for an example that enables it).
     if (conf_->get("transports/shm/enable", false))
@@ -115,6 +128,16 @@ Status TransferEngineImpl::loadTransports() {
         transport_list_[TPU] = std::make_shared<TpuTransport>();
 #endif
 
+#ifdef USE_XPU
+    if (conf_->get("transports/xpu/enable", true))
+        transport_list_[XPU] = std::make_shared<XpuTransport>();
+#endif
+
+#ifdef USE_MPCOMM
+    if (conf_->get("transports/mpcomm/enable", true))
+        transport_list_[MPCOMM] = std::make_shared<MpcommTransport>();
+#endif
+
     return Status::OK();
 }
 
diff --git a/mooncake-transfer-engine/tent/src/runtime/transport_selector.cpp b/mooncake-transfer-engine/tent/src/runtime/transport_selector.cpp
index 5e380c9a07..d98e1cf806 100644
--- a/mooncake-transfer-engine/tent/src/runtime/transport_selector.cpp
+++ b/mooncake-transfer-engine/tent/src/runtime/transport_selector.cpp
@@ -15,6 +15,7 @@
 #include "tent/runtime/transport_selector.h"
 #include "tent/runtime/transport.h"
 #include "tent/runtime/platform.h"
+#include "tent/runtime/topology.h"
 #include "tent/thirdparty/nlohmann/json.h"
 
 #include <algorithm>
@@ -42,6 +43,15 @@ static const std::unordered_map<std::string, IntentType> kIntentTypeNameMap = {
     {"staging_internal", IntentType::STAGING_INTERNAL},
 };
 
+static std::string joinNames(const std::vector<std::string>& names) {
+    std::string out;
+    for (const auto& name : names) {
+        if (!out.empty()) out += ", ";
+        out += name;
+    }
+    return out;
+}
+
 static std::optional<IntentType> parseIntentType(const json& value) {
     if (value.is_string()) {
         auto name = value.get<std::string>();
@@ -269,18 +279,86 @@ void TransportSelector::loadPolicies() {
             }
         }
 
-        policies_.push_back(std::move(policy));
+        // Link-layer QoS is defined on the QP pool, not on the policy: a QP
+        // carries the SL/TC of the pool it was created in, and a policy only
+        // selects a pool by name. These fields are a superseded duplicate that
+        // nothing reads, so say where the values actually belong.
+        if (policy.service_level || policy.traffic_class) {
+            LOG(WARNING)
+                << "Transport policy " << policy.name
+                << " sets service_level/traffic_class, which have NO effect "
+                   "here. Link-layer QoS belongs to the QP pool: define it in "
+                   "transports/rdma/endpoint/qp_pools and point this policy at "
+                   "it with \"qp_pool\": \"<name>\". Otherwise its traffic "
+                   "runs with the global transports/rdma SL/TC.";
+        }
+
         LOG(INFO) << "Loaded transport policy: " << policy.name
                   << " (segment_type=" << segment_type_str
                   << ", transports_count=" << policy.transports.size() << ")";
+        policies_.push_back(std::move(policy));
     }
 }
 
 TransportSelector::TransportSelector(std::shared_ptr<Config> config)
-    : config_(config) {
+    : config_(config), force_tcp_(config_->get("transports/force_tcp", false)) {
     loadPolicies();
 }
 
+void TransportSelector::resolveDeviceMasks() {
+    for (auto& policy : policies_) {
+        // Unconditional: a mask resolved against a topology we no longer hold
+        // would keep naming NIC ids that now mean something else.
+        if (!topology_ || policy.devices.empty()) {
+            policy.resolved_device_mask = ~0ULL;
+            continue;
+        }
+        uint64_t mask = 0;
+        std::vector<std::string> unresolved;
+        for (const auto& name : policy.devices) {
+            int dev_id = topology_->getNicId(name);
+            if (dev_id < 0) {
+                unresolved.push_back(name + " (no such device)");
+            } else if (dev_id >= kDeviceMaskBits) {
+                // The NIC exists but sits past the mask width, so no policy
+                // can ever name it. Say so explicitly: "not found" would send
+                // the operator looking for a typo that is not there.
+                unresolved.push_back(
+                    name + " (index " + std::to_string(dev_id) +
+                    " >= " + std::to_string(kDeviceMaskBits) + ")");
+            } else {
+                mask |= (1ULL << dev_id);
+            }
+        }
+
+        if (mask == 0) {
+            // Fail open, as before — a typo must not stop transfers. But an
+            // ignored device filter is the opposite of what it was written
+            // for, so it is an error, reported once with every name that
+            // failed rather than once per request.
+            policy.resolved_device_mask = ~0ULL;
+            LOG(ERROR) << "Transport policy " << policy.name
+                       << ": no device in its list resolved, so the device "
+                          "restriction is IGNORED and all devices are allowed. "
+                          "Unresolved: "
+                       << joinNames(unresolved);
+            continue;
+        }
+
+        policy.resolved_device_mask = mask;
+        if (!unresolved.empty()) {
+            LOG(WARNING) << "Transport policy " << policy.name
+                         << ": ignoring unresolved devices: "
+                         << joinNames(unresolved);
+        }
+    }
+}
+
+void TransportSelector::setTopology(std::shared_ptr<Topology> topology) {
+    topology_ = std::move(topology);
+    resolveDeviceMasks();
+}
+
 bool TransportSelector::matchesMemoryPattern(const std::string& pattern,
                                              MemoryType type) const {
     if (pattern == kMemoryTypeWildcard) {
@@ -297,11 +375,13 @@ bool TransportSelector::matchesMemoryPattern(const std::string& pattern,
             type_str = kMemoryTypeCuda;
             break;
         case MTYPE_ROCM:
-            type_str = "rocm";
-            break;
+            return isAmdGpuLocationType(pattern);
         case MTYPE_TPU:
             type_str = "tpu";
             break;
+        case MTYPE_XPU:
+            type_str = "xpu";
+            break;
         default:
             type_str = "unknown";
             break;
@@ -392,22 +472,28 @@ bool TransportSelector::isTransportAvailable(
     }
 
     // Special constraints
+    if (type == XPU && !context.local_segment) return false;
     if ((type == NVLINK || type == SHM || type == TPU) &&
         !context.same_machine) {
-        // NVLINK/SHM only work on same machine; TPU is a local-stage-only
-        // executor (HBM<->host), so it must never be picked for a remote hop.
+        // These transports require machine locality. XPU additionally needs
+        // process-local addresses, checked separately above.
         return false;
     }
 
     const auto& caps = transport->capabilities();
+    if (context.host_staging) {
+        return (type == RDMA || type == TCP || type == HP_TCP) &&
+               caps.dram_to_dram;
+    }
 
-    // Helper to check if memory type is a device (GPU/NPU/TPU). TPU is included
-    // so its device<->host staging hop routes to TpuTransport (gpu_to_dram /
-    // dram_to_gpu); it never satisfies gpu_to_gpu, so cross-node TPU traffic is
-    // always staged through host DRAM.
-    auto is_gpu = [](MemoryType t) {
-        return t == MTYPE_CUDA || t == MTYPE_ROCM || t == MTYPE_TPU;
-    };
+    // Helper to check if memory type is a device (GPU/NPU/TPU/XPU). Delegates
+    // to the single isGpuMemoryType() in platform.h so this routing predicate
+    // and the staging capability checks share one device-type list and cannot
+    // disagree. TPU and Intel XPU are included so their device<->host staging
+    // hop routes to the matching staging transport (gpu_to_dram / dram_to_gpu);
+    // they never satisfy gpu_to_gpu, so cross-node device traffic is always
+    // staged through host DRAM.
+    auto is_gpu = [](MemoryType t) { return isGpuMemoryType(t); };
 
     // For file segments, check file-specific capabilities (original logic)
     if (context.segment_type == SegmentType::File) {
@@ -463,38 +549,28 @@ SelectionResult TransportSelector::select(
         return result;  // UNSPEC, all devices
     }
 
-    // Carry the matched policy's link-layer QoS out to the caller (RFC #2519 /
-    // #2568, step 1). These are plumbed but not yet applied at QP setup; that
-    // is the per-class QP pool follow-up (step 2).
+    // qp_pool is what actually routes: it picks the QP pool, and the pool's
+    // own SL/TC were applied when those QPs were set up. The two SL/TC fields
+    // below are carried for diagnostics only (see SelectionPolicy).
     result.service_level = matching_policy->service_level;
     result.traffic_class = matching_policy->traffic_class;
     result.qp_pool = matching_policy->qp_pool;
 
-    // Convert device names to mask
-    result.device_mask = ~0ULL;  // Default: all devices
-    if (!matching_policy->devices.empty() && topology_) {
-        result.device_mask = 0;
-        for (const auto& name : matching_policy->devices) {
-            int dev_id = topology_->getNicId(name);
-            if (dev_id >= 0 && dev_id < 64) {
-                result.device_mask |= (1ULL << dev_id);
-            } else {
-                LOG(WARNING) << "RDMA device not found or ID >= 64: " << name;
-            }
-        }
-        if (result.device_mask == 0) {
-            result.device_mask = ~0ULL;  // Fallback to all if none found
-        }
-    }
+    // Resolved once by setTopology(), not per request: the names and the
+    // topology are both fixed by then, and repeating the lookup here also
+    // repeated its diagnostics on every single select().
+    result.device_mask = matching_policy->resolved_device_mask;
 
     // The "raw" candidate set is whatever the matching policy authorizes:
     // the policy's explicit transports list, or the buffer's registered
     // transports as a fallback.
     static const std::vector<TransportType> kEmpty;
-    const auto& raw = !matching_policy->transports.empty()
-                          ? matching_policy->transports
-                      : context.buffer_transports ? *context.buffer_transports
-                                                  : kEmpty;
+    static const std::vector<TransportType> kTcpOnly{TCP};
+    const auto& raw =
+        force_tcp_ && context.segment_type == SegmentType::Memory ? kTcpOnly
+        : !matching_policy->transports.empty() ? matching_policy->transports
+        : context.buffer_transports            ? *context.buffer_transports
+                                               : kEmpty;
 
     if (transport_index < 0) return result;
     const int original_index = transport_index;
diff --git a/mooncake-transfer-engine/tent/src/transfer_engine.cpp b/mooncake-transfer-engine/tent/src/transfer_engine.cpp
index 3b8a6387d9..53a759f686 100644
--- a/mooncake-transfer-engine/tent/src/transfer_engine.cpp
+++ b/mooncake-transfer-engine/tent/src/transfer_engine.cpp
@@ -15,6 +15,7 @@
 #include "tent/transfer_engine.h"
 #include "tent/common/config.h"
 #include "tent/runtime/transfer_engine_impl.h"
+#include "tent/runtime/topology.h"
 #include <glog/logging.h>
 
 namespace mooncake {
@@ -51,6 +52,15 @@ uint16_t TransferEngine::getRpcServerPort() const {
     return impl_->getRpcServerPort();
 }
 
+std::shared_ptr<Topology> TransferEngine::getLocalTopology() const {
+    return impl_->getLocalTopology();
+}
+
+std::string TransferEngine::getLocalTopologyString() const {
+    auto topo = impl_->getLocalTopology();
+    return topo ? topo->toString() : "{}";
+}
+
 Status TransferEngine::exportLocalSegment(std::string& shared_handle) {
     return impl_->exportLocalSegment(shared_handle);
 }
diff --git a/mooncake-transfer-engine/tent/src/transport/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/CMakeLists.txt
index 825f3544b9..4f192dfafd 100644
--- a/mooncake-transfer-engine/tent/src/transport/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/transport/CMakeLists.txt
@@ -1,4 +1,5 @@
 add_subdirectory(tcp)
+add_subdirectory(hp_tcp)
 add_subdirectory(rdma)
 add_subdirectory(shm)
 add_subdirectory(nvlink)
@@ -9,7 +10,9 @@ add_subdirectory(bufio)
 add_subdirectory(ascend)
 add_subdirectory(sunrise_link)
 add_subdirectory(tpu)
+add_subdirectory(xpu)
 add_subdirectory(ub)
+add_subdirectory(mpcomm)
 
 add_library(tent_transport_all INTERFACE)
 foreach(
@@ -22,10 +25,13 @@ foreach(
   tent_xport_rdma
   tent_xport_shm
   tent_xport_tcp
+  tent_xport_hp_tcp
   tent_xport_ub
   tent_xport_ascend_direct
   tent_xport_sunrise_link
-  tent_xport_tpu)
+  tent_xport_tpu
+  tent_xport_xpu
+  tent_xport_mpcomm)
   if(TARGET ${tgt})
     target_link_libraries(tent_transport_all INTERFACE ${tgt})
   endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/ascend/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/ascend/CMakeLists.txt
index a020049a78..72c8fe3b1a 100644
--- a/mooncake-transfer-engine/tent/src/transport/ascend/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/transport/ascend/CMakeLists.txt
@@ -1,6 +1,8 @@
-if (USE_ASCEND OR USE_ASCEND_DIRECT)
-    file(GLOB TEV1_XPORT_ASCEND_DIRECT_SOURCES "*.cpp")
-    add_library(tent_xport_ascend_direct STATIC ${TEV1_XPORT_ASCEND_DIRECT_SOURCES})
-    target_link_libraries(tent_xport_ascend_direct PUBLIC tent_common)
-    target_link_libraries(tent_xport_ascend_direct PUBLIC ascendcl cann_hixl metadef)
+if(USE_ASCEND OR USE_ASCEND_DIRECT)
+  file(GLOB TEV1_XPORT_ASCEND_DIRECT_SOURCES "*.cpp")
+  add_library(tent_xport_ascend_direct STATIC
+              ${TEV1_XPORT_ASCEND_DIRECT_SOURCES})
+  target_link_libraries(tent_xport_ascend_direct PUBLIC tent_common)
+  target_link_libraries(tent_xport_ascend_direct PRIVATE ascendcl cann_hixl
+                                                         metadef)
 endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/ascend/ascend_direct_transport.cpp b/mooncake-transfer-engine/tent/src/transport/ascend/ascend_direct_transport.cpp
index dd93a23254..e12185351d 100644
--- a/mooncake-transfer-engine/tent/src/transport/ascend/ascend_direct_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ascend/ascend_direct_transport.cpp
@@ -1,4 +1,4 @@
-// Copyright 2024 KVCache.AI
+// Copyright 2026 KVCache.AI
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -13,723 +13,826 @@
 // limitations under the License.
 
 #include "tent/transport/ascend/ascend_direct_transport.h"
+#include "tent/transport/ascend/hixl_engine.h"
+#include "tent/transport/ascend/local_copy_engine.h"
+#include "tent/transport/ascend/resource_config.h"
 
 #include <algorithm>
-#include <cstddef>
-#include <cstdint>
-#include <iomanip>
-#include <memory>
-#include <random>
-#include <string>
-
-#include <bits/stdint-uintn.h>
+#include <chrono>
+#include <map>
+#include <utility>
+#include <variant>
+
+#include <acl/acl.h>
 #include <glog/logging.h>
 
 #include "tent/common/status.h"
+#include "tent/common/utils/os.h"
 #include "tent/runtime/slab.h"
-#include "tent/runtime/control_plane.h"
+#include "tent/thirdparty/nlohmann/json.h"
 
 namespace mooncake {
 namespace tent {
 namespace {
-constexpr size_t MEM_CPY_LIMIT = 4096;
-constexpr int BASE_PORT = 20000;
-std::string hixlTransferStatusToString(hixl::TransferStatus status) {
-    switch (status) {
-        case hixl::TransferStatus::WAITING:
-            return "WAITING";
-        case hixl::TransferStatus::COMPLETED:
-            return "COMPLETED";
-        case hixl::TransferStatus::TIMEOUT:
-            return "TIMEOUT";
-        case hixl::TransferStatus::FAILED:
-            return "FAILED";
-        default:
-            return "UNKNOWN(" + std::to_string(static_cast<int>(status)) + ")";
+
+constexpr int64_t kMillisToNano = 1000000;
+constexpr int kMaxInflightReqs = 100;
+
+bool IsHostMem(const std::string& location, void* addr) {
+    if (location.rfind("cpu", 0) == 0) {
+        return true;
     }
-}
-uint16_t findListenPort(int32_t dev_id) {
-    char *rt_visible_devices = std::getenv("ASCEND_RT_VISIBLE_DEVICES");
-    if (rt_visible_devices) {
-        std::vector<std::string> device_list;
-        std::stringstream ss(rt_visible_devices);
-        std::string item;
-        while (std::getline(ss, item, ',')) {
-            device_list.push_back(item);
-        }
-        if (dev_id < static_cast<int32_t>(device_list.size())) {
-            try {
-                dev_id = std::stoi(device_list[dev_id]);
-            } catch (const std::exception &e) {
-                LOG(WARNING) << "ASCEND_RT_VISIBLE_DEVICES is not valid, value:"
-                             << rt_visible_devices;
-            }
-        } else {
-            LOG(WARNING) << "Device id is " << dev_id
-                         << ", ASCEND_RT_VISIBLE_DEVICES is "
-                         << rt_visible_devices << ", which is unexpected.";
-        }
+    if (location.rfind("npu", 0) == 0) {
+        return false;
     }
-    static std::random_device rand_gen;
-    const int min_port = BASE_PORT + dev_id * 1000;
-    const int max_port = BASE_PORT + (dev_id + 1) * 1000;
-    LOG(INFO) << "Find available between " << min_port << " and " << max_port;
-    const int max_attempts = 500;
-    std::uniform_int_distribution<> rand_dist(min_port, max_port);
-    int sockfd;
-    for (int attempt = 0; attempt < max_attempts; ++attempt) {
-        int port = rand_dist(rand_gen);
-        sockfd = socket(AF_INET, SOCK_STREAM, 0);
-        if (sockfd == -1) {
-            continue;
-        }
-        struct timeval timeout;
-        timeout.tv_sec = 1;
-        timeout.tv_usec = 0;
-        if (setsockopt(sockfd, SOL_SOCKET, SO_RCVTIMEO, &timeout,
-                       sizeof(timeout))) {
-            close(sockfd);
-            sockfd = -1;
-            continue;
-        }
-        sockaddr_in bind_address;
-        memset(&bind_address, 0, sizeof(sockaddr_in));
-        bind_address.sin_family = AF_INET;
-        bind_address.sin_port = htons(port);
-        bind_address.sin_addr.s_addr = INADDR_ANY;
-        if (bind(sockfd, (sockaddr *)&bind_address, sizeof(sockaddr_in)) < 0) {
-            close(sockfd);
-            sockfd = -1;
-            continue;
-        }
-        close(sockfd);
-        return port;
+    aclrtPtrAttributes attributes{};
+    if (aclrtPointerGetAttributes(addr, &attributes) != ACL_SUCCESS) {
+        LOG(ERROR) << "aclrtPointerGetAttributes failed, errmsg: "
+                   << aclGetRecentErrMsg();
+        return true;
     }
-    return 0;
+    return attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST;
 }
-}  // namespace
-AscendDirectTransport::AscendDirectTransport() : installed_(false) {}
 
-AscendDirectTransport::~AscendDirectTransport() {
-    hixl_->Finalize();
-    uninstall();
+TransferStatusEnum FromHixlState(HixlXferState state) {
+    switch (state) {
+        case HixlXferState::Completed:
+            return TransferStatusEnum::COMPLETED;
+        case HixlXferState::Timeout:
+            return TransferStatusEnum::TIMEOUT;
+        case HixlXferState::Failed:
+            return TransferStatusEnum::FAILED;
+        case HixlXferState::Waiting:
+        default:
+            return TransferStatusEnum::PENDING;
+    }
 }
 
-Status AscendDirectTransport::install(std::string &local_segment_name,
+}  // namespace
+
+AscendDirectTransport::AscendDirectTransport() = default;
+
+AscendDirectTransport::~AscendDirectTransport() { (void)uninstall(); }
+
+Status AscendDirectTransport::install(std::string& local_segment_name,
                                       std::shared_ptr<ControlService> metadata,
                                       std::shared_ptr<Topology> local_topology,
                                       std::shared_ptr<Config> conf) {
     if (installed_) {
         return Status::InvalidArgument(
-            "Hixl transport has been installed" LOC_MARK);
+            "AscendDirectTransport has been installed" LOC_MARK);
     }
-
     metadata_ = metadata;
     local_segment_name_ = local_segment_name;
     local_topology_ = local_topology;
-    installed_ = true;
+    conf_ = conf;
+    options_ = LoadAscendDirectOptions(conf_);
+    init_options_ = BuildHixlInitOptions(options_);
+    transfer_timeout_ns_ =
+        static_cast<int64_t>(options_.transfer_timeout_ms) * kMillisToNano;
     caps.dram_to_dram = true;
     caps.dram_to_gpu = true;
     caps.gpu_to_dram = true;
     caps.gpu_to_gpu = true;
-    transfer_timeout_ =
-        conf->get("transports/ascend_direct/transfer_timeout_ns", 3000000UL);
-    connect_timeout_ =
-        conf->get("transports/ascend_direct/connect_timeout_ns", 3000000UL);
-    return initHixl(conf);
+    auto status = initEngines();
+    if (!status.ok()) {
+        finalizeEngines();
+        return status;
+    }
+    status = publishLocalEngines();
+    if (!status.ok()) {
+        finalizeEngines();
+        return status;
+    }
+    installed_ = true;
+    LOG(INFO) << "Installed AscendDirectTransport engines=" << engines_.size()
+              << " agent_mode=" << options_.agent_mode
+              << " fabric_mem=" << options_.use_fabric_mem
+              << " roce_mode=" << options_.roce_mode
+              << " timeout_ms=" << options_.transfer_timeout_ms;
+    return Status::OK();
 }
 
-Status AscendDirectTransport::initHixl(const std::shared_ptr<Config> &conf) {
-    auto ret = aclrtGetDevice(&device_logic_id_);
-    if (ret) {
-        LOG(ERROR) << "Call aclrtGetDevice failed, ret: " << ret;
-        return Status::InvalidArgument(
-            "Get device id failed, device id may be not set.");
-    }
-    ret = aclrtGetCurrentContext(&rt_context_);
-    if (ret) {
-        LOG(ERROR) << "Call aclrtGetCurrentContext failed, ret: " << ret;
-        return Status::InternalError("Get rt context failed.");
-    }
-    auto host_ip = local_segment_name_;
-    const size_t colon_pos = local_segment_name_.find(':');
-    if (colon_pos != std::string::npos) {
-        host_ip = local_segment_name_.substr(0, colon_pos);
-    }
-    auto port = findListenPort(device_logic_id_);
-    auto hixl_name = host_ip + ":" + std::to_string(port);
-    local_hixl_name_ = hixl_name;
-
-    CHECK_STATUS(metadata_->segmentManager().updateLocal(
-        [&](SegmentDesc &segment) -> Status {
-            auto &detail = std::get<MemorySegmentDesc>(segment.detail);
-            detail.device_attrs["hixl_name"] = hixl_name;
-            return Status::OK();
-        }));
-
-    hixl_ = std::make_unique<hixl::Hixl>();
-    if (!hixl_) return Status::InternalError("Create hixl failed.");
-    std::map<hixl::AscendString, hixl::AscendString> options;
-    std::string rdma_tc = conf->get("transports/ascend_direct/rdma_tc", "");
-    if (!rdma_tc.empty()) {
-        options["RdmaTrafficClass"] = rdma_tc.c_str();
-        LOG(INFO) << "Set RdmaTrafficClass to:" << rdma_tc;
+Status AscendDirectTransport::initEngines() {
+    // A failed install may be retried. Release any engines left by that
+    // attempt before rebuilding the per-device set.
+    finalizeEngines();
+    aclrtContext saved = nullptr;
+    if (aclrtGetCurrentContext(&saved) != ACL_ERROR_NONE) {
+        return Status::InternalError(
+            "Get device context failed, device may be not set." LOC_MARK);
+    }
+
+    std::vector<std::pair<int32_t, aclrtContext>> devices;
+    if (options_.agent_mode) {
+        uint32_t device_count = 0;
+        if (aclrtGetDeviceCount(&device_count) != ACL_ERROR_NONE ||
+            device_count == 0) {
+            return Status::InternalError(
+                "aclrtGetDeviceCount failed in agent mode" LOC_MARK);
+        }
+        for (uint32_t i = 0; i < device_count; ++i) {
+            auto device_id = static_cast<int32_t>(i);
+            if (aclrtSetDevice(device_id) != ACL_ERROR_NONE) {
+                LOG(ERROR) << "aclrtSetDevice failed for device " << device_id
+                           << ", errmsg: " << aclGetRecentErrMsg();
+                (void)aclrtSetCurrentContext(saved);
+                return Status::InternalError("aclrtSetDevice failed" LOC_MARK);
+            }
+            aclrtContext context = nullptr;
+            if (aclrtGetCurrentContext(&context) != ACL_ERROR_NONE) {
+                (void)aclrtSetCurrentContext(saved);
+                return Status::InternalError(
+                    "aclrtGetCurrentContext failed" LOC_MARK);
+            }
+            devices.emplace_back(device_id, context);
+        }
+        (void)aclrtSetCurrentContext(saved);
     } else {
-        auto rdma_tc_env = std::getenv("HCCL_RDMA_TC");
-        if (rdma_tc_env) {
-            options["RdmaTrafficClass"] = rdma_tc_env;
-            LOG(INFO) << "Set RdmaTrafficClass to:" << rdma_tc_env;
+        int32_t device_id = 0;
+        if (aclrtGetDevice(&device_id) != ACL_ERROR_NONE) {
+            return Status::InvalidArgument(
+                "Get device id failed, device id may be not set." LOC_MARK);
         }
+        devices.emplace_back(device_id, saved);
     }
-    std::string rdma_sl = conf->get("transports/ascend_direct/rdma_sl", "");
-    if (!rdma_sl.empty()) {
-        options["RdmaServiceLevel"] = rdma_sl.c_str();
-        LOG(INFO) << "Set RdmaServiceLevel to:" << rdma_sl;
-    } else {
-        auto rdma_sl_env = std::getenv("HCCL_RDMA_SL");
-        if (rdma_sl_env) {
-            options["RdmaServiceLevel"] = rdma_sl_env;
-            LOG(INFO) << "Set RdmaServiceLevel to:" << rdma_sl_env;
+
+    const auto host_ip = HostIpFromSegmentName(local_segment_name_);
+    for (const auto& [device_id, context] : devices) {
+        auto port = FindHixlListenPort(options_.base_port, device_id);
+        if (port == 0) {
+            return Status::InternalError("Find available port failed" LOC_MARK);
+        }
+        auto engine = std::make_unique<HixlEngine>();
+        const auto name = MakeHixlEngineName(host_ip, port);
+        auto init = init_options_;
+        if (options_.roce_mode) {
+            const auto roce_listen = HixlRoceListenPort(port);
+            init = WithHixlListenPort(init_options_, roce_listen);
+            LOG(INFO) << "HIXL engine " << name
+                      << " roce listen_port=" << roce_listen;
+        } else {
+            LOG(INFO) << "HIXL engine " << name;
+        }
+        auto status = engine->initialize(name, context, device_id, init);
+        if (!status.ok()) {
+            engine->finalize();
+            return status;
+        }
+        auto local_copy = std::make_unique<LocalCopyEngine>();
+        auto copy_status = local_copy->initialize(engine->context(), device_id);
+        if (!copy_status.ok()) {
+            engine->finalize();
+            return copy_status;
         }
+        engines_.push_back(std::move(engine));
+        local_copies_.push_back(std::move(local_copy));
     }
-    std::string auto_connect =
-        conf->get("transports/ascend_direct/auto_connect", "");
-    if (!auto_connect.empty()) {
-        auto_connect_ = (auto_connect == "1");
-        options["AutoConnect"] = auto_connect_ ? "1" : "0";
-        LOG(INFO) << "Set AutoConnect to: " << auto_connect;
-    } else {
-        options["AutoConnect"] = "1";
-        auto_connect_ = true;
-        LOG(INFO) << "Set AutoConnect to default: 1";
-    }
-    auto status =
-        hixl_->Initialize(hixl::AscendString(hixl_name.c_str()), options);
-    if (status != hixl::SUCCESS) {
-        LOG(ERROR) << "Failed to initialize AdxlEngine, status: " << status
-                   << ", errmsg: " << aclGetRecentErrMsg();
-        return Status::InternalError("Initialize hixl failed.");
-    }
-    ret = aclrtCreateStreamWithConfig(
-        &stream_, 0, ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC);
-    if (ret != ACL_ERROR_NONE) {
-        LOG(ERROR) << "AscendDirectTransport: cannot create stream, ret: "
-                   << ret;
-        return Status::InternalError("Create stream failed.");
-    }
-    LOG(INFO) << "Success to initialize hixl engine:" << hixl_name
-              << " with device_id:" << device_logic_id_;
     return Status::OK();
 }
 
+void AscendDirectTransport::finalizeEngines() {
+    // Local copy streams may still have ACL work queued, so tear them down
+    // before dropping the HIXL engines and their contexts.
+    for (auto& local_copy : local_copies_) {
+        if (local_copy) {
+            local_copy->finalize();
+        }
+    }
+    local_copies_.clear();
+    for (auto& engine : engines_) {
+        if (engine) {
+            engine->finalize();
+        }
+    }
+    engines_.clear();
+}
+
+Status AscendDirectTransport::publishLocalEngines() {
+    if (!metadata_) {
+        return Status::InvalidArgument("metadata is null" LOC_MARK);
+    }
+    nlohmann::json names = nlohmann::json::array();
+    for (const auto& engine : engines_) {
+        names.push_back(engine->name());
+    }
+    return metadata_->segmentManager().updateLocal(
+        [&](SegmentDesc& segment) -> Status {
+            if (!std::holds_alternative<MemorySegmentDesc>(segment.detail)) {
+                segment.detail = MemorySegmentDesc{};
+            }
+            auto& detail = std::get<MemorySegmentDesc>(segment.detail);
+            if (!names.empty()) {
+                detail.device_attrs[kHixlNameAttr] =
+                    names.front().get<std::string>();
+            }
+            detail.device_attrs[kHixlNamesAttr] = names.dump();
+            return Status::OK();
+        });
+}
+
+size_t AscendDirectTransport::currentEngineIndex() const {
+    if (engines_.size() <= 1) {
+        return 0;
+    }
+    int32_t device_id = 0;
+    if (aclrtGetDevice(&device_id) != ACL_ERROR_NONE) {
+        return 0;
+    }
+    auto idx = static_cast<size_t>(device_id);
+    if (idx >= engines_.size()) {
+        return 0;
+    }
+    return idx;
+}
+
 Status AscendDirectTransport::uninstall() {
-    if (installed_) {
-        metadata_.reset();
-        installed_ = false;
+    (void)quiesce();
+    finalizeEngines();
+    {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        groups_.clear();
+        route_groups_.clear();
     }
+    inflight_.store(0, std::memory_order_release);
+    inflight_cv_.notify_all();
+    installed_ = false;
+    metadata_.reset();
     return Status::OK();
 }
 
-Status AscendDirectTransport::allocateSubBatch(SubBatchRef &batch,
+Status AscendDirectTransport::quiesce() {
+    const auto deadline =
+        std::chrono::steady_clock::now() +
+        std::chrono::milliseconds(options_.transfer_timeout_ms);
+    std::unique_lock<std::mutex> lock(inflight_mu_);
+    while (inflight_.load(std::memory_order_acquire) > 0) {
+        if (inflight_cv_.wait_until(lock, deadline) ==
+            std::cv_status::timeout) {
+            LOG(WARNING) << "AscendDirectTransport quiesce timed out with "
+                         << inflight_.load() << " in-flight requests";
+            break;
+        }
+    }
+    return Status::OK();
+}
+
+Status AscendDirectTransport::allocateSubBatch(SubBatchRef& batch,
                                                size_t max_size) {
-    auto hixl_batch = Slab<HixlSubBatch>::Get().allocate();
-    if (!hixl_batch)
-        return Status::InternalError("Unable to allocate TCP sub-batch");
-    batch = hixl_batch;
+    auto* hixl_batch = Slab<HixlSubBatch>::Get().allocate();
+    if (!hixl_batch) {
+        return Status::InternalError("Unable to allocate HIXL sub-batch");
+    }
+    hixl_batch->task_list.clear();
     hixl_batch->task_list.reserve(max_size);
     hixl_batch->max_size = max_size;
+    batch = hixl_batch;
     return Status::OK();
 }
 
-Status AscendDirectTransport::freeSubBatch(SubBatchRef &batch) {
-    auto hixl_batch = dynamic_cast<HixlSubBatch *>(batch);
-    if (!hixl_batch)
-        return Status::InvalidArgument("Invalid TCP sub-batch" LOC_MARK);
+Status AscendDirectTransport::freeSubBatch(SubBatchRef& batch) {
+    auto* hixl_batch = dynamic_cast<HixlSubBatch*>(batch);
+    if (!hixl_batch) {
+        return Status::InvalidArgument("Invalid HIXL sub-batch" LOC_MARK);
+    }
     Slab<HixlSubBatch>::Get().deallocate(hixl_batch);
     batch = nullptr;
     return Status::OK();
 }
 
+Status AscendDirectTransport::resolveRequest(const Request& request,
+                                             PreparedRequest& prepared) const {
+    if (engines_.empty()) {
+        return Status::InternalError(
+            "HIXL engines are not initialized" LOC_MARK);
+    }
+    if (!metadata_) {
+        return Status::InvalidArgument("metadata is null" LOC_MARK);
+    }
+    SegmentDescRef pin;
+    SegmentDesc* desc = nullptr;
+    auto status = metadata_->segmentManager().withCachedSegment(
+        request.target_id, pin, [&](SegmentDesc* cached) {
+            desc = cached;
+            return Status::OK();
+        });
+    if (!status.ok() || desc == nullptr) {
+        return Status::InvalidArgument("Cannot find target segment" LOC_MARK);
+    }
+    if (!std::holds_alternative<MemorySegmentDesc>(desc->detail)) {
+        return Status::InvalidArgument(
+            "Target is not a memory segment" LOC_MARK);
+    }
+    const auto& detail = std::get<MemorySegmentDesc>(desc->detail);
+    prepared.request = request;
+    prepared.local_engine_idx = currentEngineIndex();
+    prepared.remote_hixl = ResolveRemoteHixlName(detail, request.target_offset);
+    if (prepared.remote_hixl.empty()) {
+        return Status::InvalidArgument("Missing remote hixl_name" LOC_MARK);
+    }
+    if (request.target_id != LOCAL_SEGMENT_ID &&
+        prepared.local_engine_idx < engines_.size() &&
+        engines_[prepared.local_engine_idx] &&
+        prepared.remote_hixl == engines_[prepared.local_engine_idx]->name()) {
+        LOG(WARNING) << "Remote segment id=" << request.target_id
+                     << " resolved to local HIXL name " << prepared.remote_hixl;
+    }
+    return Status::OK();
+}
+
 Status AscendDirectTransport::submitTransferTasks(
-    SubBatchRef batch, const std::vector<Request> &request_list) {
-    auto hixl_batch = dynamic_cast<HixlSubBatch *>(batch);
-    if (!hixl_batch)
-        return Status::InvalidArgument("Invalid TCP sub-batch" LOC_MARK);
+    SubBatchRef batch, const std::vector<Request>& request_list) {
+    auto* hixl_batch = dynamic_cast<HixlSubBatch*>(batch);
+    if (!hixl_batch) {
+        return Status::InvalidArgument("Invalid HIXL sub-batch" LOC_MARK);
+    }
     if (request_list.size() + hixl_batch->task_list.size() >
-        hixl_batch->max_size)
+        hixl_batch->max_size) {
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
-    std::map<SegmentID, std::map<Request::OpCode, std::vector<HixlTask *>>>
-        seg_to_tasks;
-    for (auto &request : request_list) {
-        hixl_batch->task_list.push_back(HixlTask{});
-        auto &task = hixl_batch->task_list[hixl_batch->task_list.size() - 1];
-        uint64_t target_addr = request.target_offset;
-        task.target_addr = target_addr;
-        task.request = request;
+    }
+
+    std::vector<PreparedRequest> prepared;
+    prepared.reserve(request_list.size());
+    for (const auto& request : request_list) {
+        PreparedRequest item;
+        CHECK_STATUS(resolveRequest(request, item));
+        prepared.push_back(std::move(item));
+    }
+
+    const size_t start = hixl_batch->task_list.size();
+    hixl_batch->task_list.resize(start + prepared.size());
+    using GroupKey = std::pair<size_t, std::pair<std::string, bool>>;
+    std::map<GroupKey, std::vector<HixlTask*>> groups;
+    for (size_t i = 0; i < prepared.size(); ++i) {
+        auto& task = hixl_batch->task_list[start + i];
+        task.request = prepared[i].request;
         task.status_word = TransferStatusEnum::PENDING;
         task.transferred_bytes = 0;
-        seg_to_tasks[task.request.target_id][task.request.opcode].push_back(
+        task.req_handle = nullptr;
+        task.local_engine_idx = prepared[i].local_engine_idx;
+        task.remote_hixl = prepared[i].remote_hixl;
+        const bool write = task.request.opcode == Request::WRITE;
+        groups[{task.local_engine_idx, {task.remote_hixl, write}}].push_back(
             &task);
     }
-    for (auto &[seg_id, op_to_tasks] : seg_to_tasks) {
-        for (auto &[opcode, tasks] : op_to_tasks) {
-            startTransfer(seg_id, opcode, tasks);
-        }
-    }
-    return Status::OK();
-}
-
-Status AscendDirectTransport::checkAndConnect(const std::string &remote_hixl) {
-    std::lock_guard<std::mutex> lock(connection_mutex_);
-    auto it = connected_segments_.find(remote_hixl);
-    if (it != connected_segments_.end()) {
-        VLOG(1) << "Already connected to target hixl engine: " << remote_hixl;
-    } else {
-        auto status = hixl_->Connect(
-            remote_hixl.c_str(), static_cast<int32_t>(connect_timeout_ / 1000));
-        if (status == hixl::TIMEOUT) {
-            LOG(ERROR) << "Connect timeout to: " << remote_hixl
-                       << ", you can increase the timeout duration to reduce "
-                          "the failure rate by configuring "
-                          "the ASCEND_CONNECT_TIMEOUT environment variable"
-                       << ", errmsg: " << aclGetRecentErrMsg();
-            return Status::InternalError("Connect to target timed out.");
-        } else if (status != hixl::SUCCESS) {
-            LOG(ERROR) << "Failed to connect to target: " << remote_hixl
-                       << ", status: " << status
-                       << ", errmsg: " << aclGetRecentErrMsg();
-            return Status::InternalError("Connect to target failed.");
-        }
-        connected_segments_.emplace(remote_hixl);
-        LOG(INFO) << "Connected to segment: " << remote_hixl;
+    for (auto& [key, tasks] : groups) {
+        startGroup(key.second.first, key.first, key.second.second, tasks);
     }
     return Status::OK();
 }
 
-void AscendDirectTransport::startTransfer(
-    SegmentID target_id, Request::OpCode opcode,
-    const std::vector<HixlTask *> &tasks) {
-    std::string rpc_server_addr;
-    SegmentDesc *desc = nullptr;
-    auto status = metadata_->segmentManager().getRemoteCached(desc, target_id);
-    if (!status.ok()) {
-        for (auto &task : tasks) {
+void AscendDirectTransport::startGroup(const std::string& remote_hixl,
+                                       size_t local_engine_idx, bool write,
+                                       const std::vector<HixlTask*>& tasks) {
+    auto fail_all = [&]() {
+        for (auto* task : tasks) {
             task->status_word = TransferStatusEnum::FAILED;
         }
+    };
+    if (local_engine_idx >= engines_.size() || !engines_[local_engine_idx]) {
+        fail_all();
         return;
     }
-    auto &detail = std::get<MemorySegmentDesc>(desc->detail);
-    auto remote_hixl = detail.device_attrs["hixl_name"];
-    if (remote_hixl == local_hixl_name_) {
-        VLOG(1) << "Target is local.";
-        auto start = std::chrono::steady_clock::now();
-        localCopy(opcode, tasks);
-        LOG(INFO) << "Local copy cost: "
-                  << std::chrono::duration_cast<std::chrono::microseconds>(
-                         std::chrono::steady_clock::now() - start)
-                         .count()
-                  << " us.";
+    if (remote_hixl == engines_[local_engine_idx]->name()) {
+        startLocalCopy(local_engine_idx, write, tasks);
         return;
-    } else {
-        if (!auto_connect_) {
-            auto ret = checkAndConnect(remote_hixl);
-            if (!ret.ok()) {
+    }
+
+    {
+        std::unique_lock<std::mutex> lock(inflight_mu_);
+        const auto deadline =
+            std::chrono::steady_clock::now() +
+            std::chrono::milliseconds(options_.transfer_timeout_ms);
+        while (inflight_.load(std::memory_order_acquire) >= kMaxInflightReqs) {
+            if (inflight_cv_.wait_until(lock, deadline) ==
+                std::cv_status::timeout) {
+                fail_all();
                 return;
             }
-        } else {
-            std::lock_guard<std::mutex> lock(connection_mutex_);
-            connected_segments_.emplace(remote_hixl);
         }
+        inflight_.fetch_add(1, std::memory_order_acq_rel);
     }
-    auto op = (opcode == Request::WRITE) ? hixl::WRITE : hixl::READ;
-    std::vector<hixl::TransferOpDesc> op_descs;
+
+    std::vector<HixlOpDesc> op_descs;
     op_descs.reserve(tasks.size());
-    for (auto &task : tasks) {
-        hixl::TransferOpDesc op_desc{};
-        op_desc.local_addr = reinterpret_cast<uintptr_t>(task->request.source);
-        op_desc.remote_addr =
-            reinterpret_cast<uintptr_t>(task->request.target_offset);
-        op_desc.len = task->request.length;
-        op_descs.emplace_back(op_desc);
-    }
-    hixl::Status hixl_ret;
-    hixl::TransferReq req_handle;
-    hixl_ret = hixl_->TransferAsync(hixl::AscendString(remote_hixl.c_str()), op,
-                                    op_descs, hixl::TransferArgs(), req_handle);
-    if (hixl_ret != hixl::SUCCESS) {
-        LOG(ERROR) << "Failed to transfer to: " << remote_hixl
-                   << ", status: " << hixl_ret
-                   << ", errmsg: " << aclGetRecentErrMsg();
-        // disconnect to remote when transfer fail
-        disconnect(remote_hixl, 10);
-        for (auto &task : tasks) {
-            task->status_word = TransferStatusEnum::FAILED;
-        }
+    for (auto* task : tasks) {
+        HixlOpDesc desc{};
+        desc.local_addr = reinterpret_cast<uintptr_t>(task->request.source);
+        desc.remote_addr = task->request.target_offset;
+        desc.len = task->request.length;
+        op_descs.push_back(desc);
+    }
+    void* req = nullptr;
+    auto status = engines_[local_engine_idx]->transferAsync(remote_hixl, write,
+                                                            op_descs, req);
+    if (!status.ok() || req == nullptr) {
+        releaseInflight();
+        // AutoConnect already tore down the failed route inside HIXL.
+        fail_all();
         return;
     }
-    for (auto &task : tasks) {
-        task->start_time = getCurrentTimeInNano();
-        task->req_handle = req_handle;
+    const auto now = getCurrentTimeInNano();
+    {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        GroupState group;
+        group.status = TransferStatusEnum::PENDING;
+        group.remaining = static_cast<int>(tasks.size());
+        group.engine_idx = local_engine_idx;
+        group.remote = remote_hixl;
+        group.counted = true;
+        groups_[req] = std::move(group);
+        route_groups_[{local_engine_idx, remote_hixl}].push_back(req);
+    }
+    for (auto* task : tasks) {
+        task->req_handle = req;
         task->batch_size = tasks.size();
-        task->remote_hixl = remote_hixl;
+        task->start_time_ns = now;
         task->status_word = TransferStatusEnum::PENDING;
     }
 }
 
-Status AscendDirectTransport::getTransferStatus(SubBatchRef batch, int task_id,
-                                                TransferStatus &status) {
-    auto hixl_batch = dynamic_cast<HixlSubBatch *>(batch);
-    if (task_id < 0 || task_id >= (int)hixl_batch->task_list.size()) {
-        return Status::InvalidArgument("Invalid task id" LOC_MARK);
-    }
-    auto &task = hixl_batch->task_list[task_id];
-    if (task.status_word == TransferStatusEnum::PENDING) {
-        if (task.req_handle == nullptr) {
-            status = TransferStatus{task.status_word, task.transferred_bytes};
-            return Status::OK();
-        }
+void AscendDirectTransport::markGroupHandles(const std::vector<void*>& handles,
+                                             TransferStatusEnum status) {
+    int inflight_dec = 0;
+    {
         std::lock_guard<std::mutex> lock(req_mutex_);
-        auto it = req_map_.find(task.req_handle);
-        if (it != req_map_.end()) {
-            auto xfer_status = it->second.first;
-            task.status_word = xfer_status;
-            if (xfer_status == TransferStatusEnum::COMPLETED) {
-                task.transferred_bytes = task.request.length;
+        for (void* handle : handles) {
+            auto git = groups_.find(handle);
+            if (git == groups_.end()) {
+                continue;
             }
-            if (--req_map_[task.req_handle].second == 0) {
-                req_map_.erase(task.req_handle);
+            if (git->second.status == TransferStatusEnum::PENDING) {
+                git->second.status = status;
             }
-            status = TransferStatus{task.status_word, task.transferred_bytes};
-            return Status::OK();
-        }
-        uint64_t current_ts = getCurrentTimeInNano();
-        if ((current_ts - task.start_time) > transfer_timeout_) {
-            disconnect(task.remote_hixl, 10);
-            task.status_word = TransferStatusEnum::TIMEOUT;
-            if (task.batch_size > 1) {
-                req_map_[task.req_handle] =
-                    std::make_pair(task.status_word, task.batch_size - 1);
+            if (git->second.counted) {
+                git->second.counted = false;
+                inflight_dec++;
             }
-            status = TransferStatus{task.status_word, task.transferred_bytes};
-            return Status::OK();
-        }
-        hixl::TransferStatus xfer_status;
-        auto err = hixl_->GetTransferStatus(task.req_handle, xfer_status);
-        if (err != hixl::SUCCESS) {
-            // call failed equal to transfer failed;
-            xfer_status = hixl::TransferStatus::FAILED;
-        }
-        if (xfer_status == hixl::TransferStatus::WAITING) {
-            status = TransferStatus{task.status_word, task.transferred_bytes};
-            return Status::OK();
-        }
-        if (xfer_status == hixl::TransferStatus::COMPLETED) {
-            task.transferred_bytes = task.request.length;
-            task.status_word = TransferStatusEnum::COMPLETED;
-        } else if (xfer_status == hixl::TransferStatus::FAILED) {
-            LOG(ERROR) << "Get transfer status failed, ret: "
-                       << hixlTransferStatusToString(xfer_status)
-                       << ", errmsg: " << aclGetRecentErrMsg();
-            disconnect(task.remote_hixl, 10);
-            task.status_word = TransferStatusEnum::FAILED;
-        }
-        if (task.batch_size > 1) {
-            req_map_[task.req_handle] =
-                std::make_pair(task.status_word, task.batch_size - 1);
         }
     }
-    // Read status AFTER the poll so a just-observed completion/failure is
-    // reported on this call rather than one poll cycle late.
-    status = TransferStatus{task.status_word, task.transferred_bytes};
-    return Status::OK();
+    releaseInflight(inflight_dec);
 }
 
-void AscendDirectTransport::disconnect(const std::string &remote_hixl,
-                                       int32_t timeout_in_millis) {
-    if (auto_connect_) {
-        auto status = hixl_->Disconnect(remote_hixl.c_str(), timeout_in_millis);
-        if (status != hixl::SUCCESS) {
-            LOG(ERROR) << "Failed to disconnect to: " << remote_hixl
-                       << ", status: " << status
-                       << ", errmsg: " << aclGetRecentErrMsg();
-        } else {
-            std::lock_guard<std::mutex> lock(connection_mutex_);
-            connected_segments_.erase(remote_hixl);
-        }
+void AscendDirectTransport::failLocalCopyStream(size_t engine_idx,
+                                                TransferStatusEnum status) {
+    if (engine_idx >= local_copies_.size() || !local_copies_[engine_idx]) {
         return;
     }
-    std::lock_guard<std::mutex> lock(connection_mutex_);
-    auto it = connected_segments_.find(remote_hixl);
-    if (it == connected_segments_.end()) {
-        LOG(INFO) << "Target hixl engine: " << remote_hixl
-                  << " is not connected.";
-    } else {
-        auto status = hixl_->Disconnect(remote_hixl.c_str(), timeout_in_millis);
-        connected_segments_.erase(remote_hixl);
-        if (status != hixl::SUCCESS) {
-            LOG(ERROR) << "Failed to disconnect to: " << remote_hixl
-                       << ", status: " << status
-                       << ", errmsg: " << aclGetRecentErrMsg();
-        }
-    }
+    auto handles = local_copies_[engine_idx]->failAndRecreate();
+    markGroupHandles(handles, status);
 }
 
-Status AscendDirectTransport::addMemoryBuffer(BufferDesc &desc,
-                                              const MemoryOptions &options) {
-    desc.transports.push_back(TransportType::AscendDirect);
-    hixl::MemDesc mem_desc{};
-    mem_desc.addr =
-        static_cast<uint64_t>(reinterpret_cast<uintptr_t>(desc.addr));
-    mem_desc.len = desc.length;
-    hixl::MemType mem_type;
-    if (desc.location.starts_with("cpu")) {
-        mem_type = hixl::MEM_HOST;
-    } else if (desc.location.starts_with("npu")) {
-        mem_type = hixl::MEM_DEVICE;
-    } else if (desc.location == kWildcardLocation) {
-        aclrtPtrAttributes attributes;
-        auto ret = aclrtPointerGetAttributes(
-            reinterpret_cast<void *>(desc.addr), &attributes);
-        if (ret != ACL_SUCCESS) {
-            LOG(ERROR) << "aclrtPointerGetAttributes failed, ret:" << ret;
-            return Status::InvalidArgument("Invalid location of addr:" +
-                                           std::to_string(desc.addr));
+void AscendDirectTransport::startLocalCopy(
+    size_t local_engine_idx, bool write, const std::vector<HixlTask*>& tasks) {
+    auto fail_all = [&]() {
+        for (auto* task : tasks) {
+            task->status_word = TransferStatusEnum::FAILED;
+            task->local_copy = true;
         }
-        if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
-            mem_type = hixl::MEM_HOST;
-        } else {
-            mem_type = hixl::MEM_DEVICE;
+    };
+    if (local_engine_idx >= local_copies_.size() ||
+        !local_copies_[local_engine_idx]) {
+        fail_all();
+        return;
+    }
+
+    {
+        std::unique_lock<std::mutex> lock(inflight_mu_);
+        const auto deadline =
+            std::chrono::steady_clock::now() +
+            std::chrono::milliseconds(options_.transfer_timeout_ms);
+        while (inflight_.load(std::memory_order_acquire) >= kMaxInflightReqs) {
+            if (inflight_cv_.wait_until(lock, deadline) ==
+                std::cv_status::timeout) {
+                fail_all();
+                return;
+            }
         }
-    } else {
-        LOG(ERROR) << "location:" << desc.location << " is not supported.";
-        return Status::InvalidArgument("Invalid location of addr:" +
-                                       std::to_string(desc.addr));
-    }
-    hixl::MemHandle mem_handle;
-    auto hixl_ret = hixl_->RegisterMem(mem_desc, mem_type, mem_handle);
-    if (hixl_ret != hixl::SUCCESS) {
-        LOG(ERROR) << "hixl_ret:" << hixl_ret
-                   << ", errmsg: " << aclGetRecentErrMsg();
-        return Status::InternalError("Register failed for addr:" +
-                                     std::to_string(desc.addr));
-    }
-    LOG(INFO) << "AscendDirectTransport register mem addr:" << desc.addr
-              << ", length:" << desc.length << ", location:" << desc.location
-              << ", mem type:"
-              << (mem_type == hixl::MEM_HOST ? "host" : "device");
-    std::lock_guard<std::mutex> lock(mem_handle_mutex_);
-    addr_to_mem_handle_[desc.addr] = mem_handle;
-    return Status::OK();
+        inflight_.fetch_add(1, std::memory_order_acq_rel);
+    }
+
+    std::vector<HixlOpDesc> op_descs;
+    op_descs.reserve(tasks.size());
+    for (auto* task : tasks) {
+        HixlOpDesc desc{};
+        desc.local_addr = reinterpret_cast<uintptr_t>(task->request.source);
+        desc.remote_addr = task->request.target_offset;
+        desc.len = task->request.length;
+        op_descs.push_back(desc);
+    }
+
+    void* req = nullptr;
+    std::vector<void*> failed_handles;
+    auto status = local_copies_[local_engine_idx]->submit(write, op_descs, req,
+                                                          failed_handles);
+    if (!failed_handles.empty()) {
+        markGroupHandles(failed_handles, TransferStatusEnum::FAILED);
+    }
+    if (!status.ok() || req == nullptr) {
+        releaseInflight();
+        fail_all();
+        return;
+    }
+
+    const auto now = getCurrentTimeInNano();
+    {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        GroupState group;
+        group.status = TransferStatusEnum::PENDING;
+        group.remaining = static_cast<int>(tasks.size());
+        group.engine_idx = local_engine_idx;
+        group.remote = engines_[local_engine_idx]->name();
+        group.counted = true;
+        group.local_copy = true;
+        groups_[req] = std::move(group);
+    }
+    for (auto* task : tasks) {
+        task->req_handle = req;
+        task->batch_size = tasks.size();
+        task->start_time_ns = now;
+        task->status_word = TransferStatusEnum::PENDING;
+        task->local_copy = true;
+        task->local_engine_idx = local_engine_idx;
+    }
 }
 
-Status AscendDirectTransport::removeMemoryBuffer(BufferDesc &desc) {
-    std::vector<std::string> remote_hixls;
+void AscendDirectTransport::releaseInflight(int n) {
+    if (n <= 0) {
+        return;
+    }
     {
-        std::lock_guard<std::mutex> lock(connection_mutex_);
-        remote_hixls.assign(connected_segments_.begin(),
-                            connected_segments_.end());
+        std::lock_guard<std::mutex> lock(inflight_mu_);
+        const int cur = inflight_.load(std::memory_order_acquire);
+        inflight_.store(std::max(0, cur - n), std::memory_order_release);
     }
-    for (const auto &remote_hixl : remote_hixls) {
-        disconnect(remote_hixl, 10);
+    inflight_cv_.notify_all();
+}
+
+bool AscendDirectTransport::applyGroupStatus(HixlTask& task,
+                                             GroupState& group) {
+    task.status_word = group.status;
+    if (group.status == TransferStatusEnum::COMPLETED) {
+        task.transferred_bytes = task.request.length;
     }
-    std::lock_guard<std::mutex> lock(mem_handle_mutex_);
-    auto addr = desc.addr;
-    if (addr_to_mem_handle_.find(addr) != addr_to_mem_handle_.end()) {
-        (void)hixl_->DeregisterMem(addr_to_mem_handle_[addr]);
-        addr_to_mem_handle_.erase(addr);
+    if (group.remaining > 0) {
+        group.remaining--;
     }
-    return Status::OK();
+    if (group.counted && group.status != TransferStatusEnum::PENDING) {
+        group.counted = false;
+        return true;
+    }
+    return false;
 }
 
-void AscendDirectTransport::localCopy(Request::OpCode opcode,
-                                      const std::vector<HixlTask *> &tasks) {
-    aclrtMemcpyKind kind;
-    auto &first_task = tasks[0];
-    auto remote_ptr =
-        reinterpret_cast<void *>(first_task->request.target_offset);
-    aclrtPtrAttributes attributes;
-    auto ret =
-        aclrtPointerGetAttributes(first_task->request.source, &attributes);
-    if (ret != ACL_ERROR_NONE) {
-        LOG(ERROR) << "aclrtPointerGetAttributes failed, ret:" << ret;
-        for (auto &task : tasks) {
-            task->status_word = TransferStatusEnum::FAILED;
+void AscendDirectTransport::failEntireRoute(size_t engine_idx,
+                                            const std::string& remote,
+                                            TransferStatusEnum status,
+                                            bool disconnect) {
+    int inflight_dec = 0;
+    {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        auto it = route_groups_.find({engine_idx, remote});
+        std::vector<void*> handles;
+        if (it != route_groups_.end()) {
+            handles = it->second;
+        }
+        for (void* handle : handles) {
+            auto git = groups_.find(handle);
+            if (git == groups_.end()) {
+                continue;
+            }
+            if (git->second.status == TransferStatusEnum::PENDING) {
+                git->second.status = status;
+            }
+            if (git->second.counted) {
+                git->second.counted = false;
+                inflight_dec++;
+            }
         }
-        return;
     }
-    aclrtPtrAttributes dst_attributes;
-    ret = aclrtPointerGetAttributes(remote_ptr, &dst_attributes);
-    if (ret != ACL_ERROR_NONE) {
-        LOG(ERROR) << "aclrtPointerGetAttributes failed, ret:" << ret;
-        for (auto &task : tasks) {
-            task->status_word = TransferStatusEnum::FAILED;
-        }
-        return;
+    // Never acquire inflight_mu_ while holding req_mutex_: submit waits on
+    // inflight_mu_ and later takes req_mutex_.
+    releaseInflight(inflight_dec);
+    if (disconnect && engine_idx < engines_.size() && engines_[engine_idx]) {
+        (void)engines_[engine_idx]->disconnectOnTimeout(
+            remote, kAscendTimeoutDisconnectMs);
     }
-    if (attributes.location.type != ACL_MEM_LOCATION_TYPE_HOST &&
-        attributes.location.type != ACL_MEM_LOCATION_TYPE_DEVICE) {
-        LOG(ERROR) << "location of local addr is not supported.";
-        for (auto &task : tasks) {
-            task->status_word = TransferStatusEnum::FAILED;
+}
+
+bool AscendDirectTransport::finishTaskLocked(HixlTask& task,
+                                             void** local_release_handle,
+                                             size_t* local_release_engine) {
+    auto git = groups_.find(task.req_handle);
+    if (git == groups_.end()) {
+        return false;
+    }
+    const bool release = applyGroupStatus(task, git->second);
+    if (git->second.remaining > 0) {
+        return release;
+    }
+    auto route_it =
+        route_groups_.find({git->second.engine_idx, git->second.remote});
+    if (route_it != route_groups_.end()) {
+        auto& handles = route_it->second;
+        handles.erase(
+            std::remove(handles.begin(), handles.end(), task.req_handle),
+            handles.end());
+        if (handles.empty()) {
+            route_groups_.erase(route_it);
+        }
+    }
+    if (local_release_handle != nullptr && local_release_engine != nullptr &&
+        git->second.local_copy) {
+        *local_release_handle = task.req_handle;
+        *local_release_engine = git->second.engine_idx;
+    }
+    groups_.erase(git);
+    return release;
+}
+
+void AscendDirectTransport::completePolledTask(HixlTask& task) {
+    bool release = false;
+    void* local_handle = nullptr;
+    size_t local_engine = 0;
+    {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        auto git = groups_.find(task.req_handle);
+        if (git != groups_.end() &&
+            git->second.status != TransferStatusEnum::PENDING) {
+            release = finishTaskLocked(task, &local_handle, &local_engine);
         }
-        return;
     }
-    if (dst_attributes.location.type != ACL_MEM_LOCATION_TYPE_HOST &&
-        dst_attributes.location.type != ACL_MEM_LOCATION_TYPE_DEVICE) {
-        LOG(ERROR) << "location of remote addr is not supported.";
-        for (auto &task : tasks) {
-            task->status_word = TransferStatusEnum::FAILED;
-        }
-        return;
+    // Release host flags outside req_mutex_ so timeout rebuild
+    // (LocalCopyEngine mutex -> req_mutex_) cannot deadlock.
+    if (local_handle != nullptr && local_engine < local_copies_.size() &&
+        local_copies_[local_engine]) {
+        local_copies_[local_engine]->release(local_handle);
     }
-    if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST &&
-        dst_attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
-        kind = ACL_MEMCPY_HOST_TO_HOST;
-    } else if (attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE &&
-               dst_attributes.location.type == ACL_MEM_LOCATION_TYPE_DEVICE) {
-        kind = ACL_MEMCPY_DEVICE_TO_DEVICE;
-    } else if (attributes.location.type == ACL_MEM_LOCATION_TYPE_HOST) {
-        kind = (opcode == Request::OpCode::WRITE) ? ACL_MEMCPY_HOST_TO_DEVICE
-                                                  : ACL_MEMCPY_DEVICE_TO_HOST;
-    } else {
-        kind = (opcode == Request::OpCode::WRITE) ? ACL_MEMCPY_DEVICE_TO_HOST
-                                                  : ACL_MEMCPY_HOST_TO_DEVICE;
-    }
-    if (kind == ACL_MEMCPY_HOST_TO_HOST) {
-        return copyWithSync(opcode, tasks, kind);
-    }
-    if (kind == ACL_MEMCPY_DEVICE_TO_DEVICE) {
-        return copyWithAsync(opcode, tasks, kind);
-    }
-    auto left_num = tasks.size();
-    size_t task_index = 0;
-    while (left_num > 0) {
-        auto batch_num = std::min(left_num, MEM_CPY_LIMIT);
-        ret = copyWithBatch(opcode, tasks, kind, batch_num, task_index);
-        if (ret == ACL_ERROR_RT_FEATURE_NOT_SUPPORT) {
-            return copyWithAsync(opcode, tasks, kind);
-        }
-        left_num -= batch_num;
-        task_index += batch_num;
+    if (release) {
+        releaseInflight();
     }
 }
 
-aclError AscendDirectTransport::copyWithBatch(
-    Request::OpCode opcode, const std::vector<HixlTask *> &tasks,
-    aclrtMemcpyKind kind, size_t batch_num, size_t task_index) const {
-    std::vector<void *> void_remote_addrs(batch_num);
-    std::vector<void *> void_local_addrs(batch_num);
-    std::vector<aclrtMemcpyBatchAttr> attrs(batch_num);
-    std::vector<size_t> attrsIds(batch_num);
-    std::vector<size_t> sizes(batch_num);
-    size_t idx = 0;
-    for (size_t i = 0; i < batch_num; i++) {
-        auto device_loc = aclrtMemLocation{
-            static_cast<uint32_t>(device_logic_id_),
-            aclrtMemLocationType::ACL_MEM_LOCATION_TYPE_DEVICE};
-        auto host_loc = aclrtMemLocation{
-            0, aclrtMemLocationType::ACL_MEM_LOCATION_TYPE_HOST};
-        if (kind == ACL_MEMCPY_DEVICE_TO_HOST) {
-            attrs[i] = aclrtMemcpyBatchAttr{host_loc, device_loc, {}};
+Status AscendDirectTransport::getTransferStatus(SubBatchRef batch, int task_id,
+                                                TransferStatus& status) {
+    auto* hixl_batch = dynamic_cast<HixlSubBatch*>(batch);
+    if (!hixl_batch) {
+        return Status::InvalidArgument("Invalid HIXL sub-batch" LOC_MARK);
+    }
+    if (task_id < 0 ||
+        task_id >= static_cast<int>(hixl_batch->task_list.size())) {
+        return Status::InvalidArgument("Invalid task id" LOC_MARK);
+    }
+    auto& task = hixl_batch->task_list[task_id];
+    if (task.status_word != TransferStatusEnum::PENDING) {
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
+    }
+    if (task.req_handle == nullptr) {
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
+    }
+
+    completePolledTask(task);
+    if (task.status_word != TransferStatusEnum::PENDING) {
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
+    }
+
+    const auto now = getCurrentTimeInNano();
+    if (now >= 0 && task.start_time_ns >= 0 &&
+        (now - task.start_time_ns) > transfer_timeout_ns_) {
+        if (task.local_copy) {
+            failLocalCopyStream(task.local_engine_idx,
+                                TransferStatusEnum::TIMEOUT);
         } else {
-            attrs[i] = aclrtMemcpyBatchAttr{device_loc, host_loc, {}};
+            failEntireRoute(task.local_engine_idx, task.remote_hixl,
+                            TransferStatusEnum::TIMEOUT, /*disconnect=*/true);
         }
-        attrsIds[i] = idx++;
-        auto &task = tasks[task_index + i];
-        void_local_addrs[i] = task->request.source;
-        void_remote_addrs[i] =
-            reinterpret_cast<void *>(task->request.target_offset);
-        sizes[i] = task->request.length;
-    }
-    size_t fail_idx;
-    aclError ret;
-    if (opcode == Request::OpCode::WRITE) {
-        ret = aclrtMemcpyBatch(void_remote_addrs.data(), sizes.data(),
-                               void_local_addrs.data(), sizes.data(),
-                               sizes.size(), attrs.data(), attrsIds.data(),
-                               attrs.size(), &fail_idx);
-    } else {
-        ret = aclrtMemcpyBatch(void_local_addrs.data(), sizes.data(),
-                               void_remote_addrs.data(), sizes.data(),
-                               sizes.size(), attrs.data(), attrsIds.data(),
-                               attrs.size(), &fail_idx);
-    }
-    if (ret != ACL_ERROR_RT_FEATURE_NOT_SUPPORT) {
-        if (ret == ACL_ERROR_NONE) {
-            VLOG(1) << "Copy with aclrtMemcpyBatch suc.";
-            for (size_t i = 0; i < batch_num; i++) {
-                auto &task = tasks[task_index + i];
-                task->status_word = TransferStatusEnum::COMPLETED;
-            }
+        completePolledTask(task);
+        if (task.status_word == TransferStatusEnum::PENDING) {
+            task.status_word = TransferStatusEnum::TIMEOUT;
+        }
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
+    }
+
+    if (task.local_copy) {
+        if (task.local_engine_idx >= local_copies_.size() ||
+            !local_copies_[task.local_engine_idx]) {
+            failLocalCopyStream(task.local_engine_idx,
+                                TransferStatusEnum::FAILED);
         } else {
-            for (size_t i = 0; i < batch_num; i++) {
-                auto &task = tasks[task_index + i];
-                task->status_word = TransferStatusEnum::FAILED;
+            const auto mapped =
+                local_copies_[task.local_engine_idx]->poll(task.req_handle);
+            if (mapped == TransferStatusEnum::COMPLETED ||
+                mapped == TransferStatusEnum::FAILED) {
+                std::lock_guard<std::mutex> lock(req_mutex_);
+                auto git = groups_.find(task.req_handle);
+                if (git != groups_.end() &&
+                    git->second.status == TransferStatusEnum::PENDING) {
+                    git->second.status = mapped;
+                }
             }
         }
+        completePolledTask(task);
+        if (task.status_word == TransferStatusEnum::PENDING &&
+            (task.local_engine_idx >= local_copies_.size() ||
+             !local_copies_[task.local_engine_idx])) {
+            task.status_word = TransferStatusEnum::FAILED;
+        }
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
     }
-    return ret;
-}
 
-void AscendDirectTransport::copyWithSync(Request::OpCode opcode,
-                                         const std::vector<HixlTask *> &tasks,
-                                         aclrtMemcpyKind kind) {
-    for (auto &task : tasks) {
-        auto local_ptr = task->request.source;
-        auto remote_ptr = reinterpret_cast<void *>(task->request.target_offset);
-        auto len = task->request.length;
-        aclError ret;
-        if (opcode == Request::OpCode::WRITE) {
-            ret = aclrtMemcpy(remote_ptr, len, local_ptr, len, kind);
-        } else {
-            ret = aclrtMemcpy(local_ptr, len, remote_ptr, len, kind);
+    if (task.local_engine_idx >= engines_.size() ||
+        !engines_[task.local_engine_idx]) {
+        failEntireRoute(task.local_engine_idx, task.remote_hixl,
+                        TransferStatusEnum::FAILED, /*disconnect=*/false);
+        completePolledTask(task);
+        if (task.status_word == TransferStatusEnum::PENDING) {
+            task.status_word = TransferStatusEnum::FAILED;
         }
-        if (ret == ACL_ERROR_NONE) {
-            VLOG(1) << "Copy with aclrtMemcpy suc.";
-            task->status_word = TransferStatusEnum::COMPLETED;
-        } else {
-            LOG(ERROR) << "aclrtMemcpy failed, ret:" << ret;
-            task->status_word = TransferStatusEnum::FAILED;
+        status = TransferStatus{task.status_word, task.transferred_bytes};
+        return Status::OK();
+    }
+
+    HixlXferState xfer_status = HixlXferState::Waiting;
+    auto err = engines_[task.local_engine_idx]->getTransferStatus(
+        task.req_handle, xfer_status);
+    const auto mapped = FromHixlState(xfer_status);
+    if (!err.ok() || mapped == TransferStatusEnum::FAILED) {
+        failEntireRoute(task.local_engine_idx, task.remote_hixl,
+                        TransferStatusEnum::FAILED, /*disconnect=*/false);
+    } else if (mapped == TransferStatusEnum::TIMEOUT) {
+        failEntireRoute(task.local_engine_idx, task.remote_hixl,
+                        TransferStatusEnum::TIMEOUT, /*disconnect=*/true);
+    } else if (mapped == TransferStatusEnum::COMPLETED) {
+        std::lock_guard<std::mutex> lock(req_mutex_);
+        auto git = groups_.find(task.req_handle);
+        if (git != groups_.end() &&
+            git->second.status == TransferStatusEnum::PENDING) {
+            git->second.status = TransferStatusEnum::COMPLETED;
         }
     }
+
+    completePolledTask(task);
+    status = TransferStatus{task.status_word, task.transferred_bytes};
+    return Status::OK();
 }
-void AscendDirectTransport::copyWithAsync(Request::OpCode opcode,
-                                          const std::vector<HixlTask *> &tasks,
-                                          aclrtMemcpyKind kind) {
-    std::vector<HixlTask *> async_list;
-    aclError ret;
-    for (auto &task : tasks) {
-        auto local_ptr = task->request.source;
-        auto remote_ptr = reinterpret_cast<void *>(task->request.target_offset);
-        auto len = task->request.length;
-        if (opcode == Request::OpCode::WRITE) {
-            ret = aclrtMemcpyAsync(remote_ptr, len, local_ptr, len, kind,
-                                   stream_);
-        } else {
-            ret = aclrtMemcpyAsync(local_ptr, len, remote_ptr, len, kind,
-                                   stream_);
+
+Status AscendDirectTransport::addMemoryBuffer(BufferDesc& desc,
+                                              const MemoryOptions& options) {
+    (void)options;
+    if (engines_.empty()) {
+        return Status::InternalError(
+            "HIXL engines are not initialized" LOC_MARK);
+    }
+    const size_t engine_idx = currentEngineIndex();
+    const bool host =
+        IsHostMem(desc.location, reinterpret_cast<void*>(desc.addr));
+    if (engine_idx >= engines_.size() || !engines_[engine_idx]) {
+        return Status::InternalError("Invalid HIXL engine index" LOC_MARK);
+    }
+    CHECK_STATUS(engines_[engine_idx]->registerMem(
+        reinterpret_cast<void*>(desc.addr), desc.length, host));
+    desc.transports.push_back(TransportType::AscendDirect);
+    desc.transport_attrs[TransportType::AscendDirect] =
+        std::to_string(engine_idx);
+    return Status::OK();
+}
+
+Status AscendDirectTransport::addMemoryBuffer(
+    std::vector<BufferDesc>& desc_list, const MemoryOptions& options) {
+    std::vector<void*> registered;
+    registered.reserve(desc_list.size());
+    for (auto& desc : desc_list) {
+        auto status = addMemoryBuffer(desc, options);
+        if (!status.ok()) {
+            for (void* addr : registered) {
+                BufferDesc rollback{};
+                rollback.addr = reinterpret_cast<uint64_t>(addr);
+                (void)removeMemoryBuffer(rollback);
+            }
+            return status;
         }
-        if (ret != ACL_ERROR_NONE) {
-            LOG(ERROR) << "aclrtMemcpyAsync failed, ret:" << ret;
-            task->status_word = TransferStatusEnum::FAILED;
+        registered.push_back(reinterpret_cast<void*>(desc.addr));
+    }
+    return Status::OK();
+}
+
+Status AscendDirectTransport::removeMemoryBuffer(BufferDesc& desc) {
+    Status first_error = Status::OK();
+    for (auto& engine : engines_) {
+        if (!engine) {
             continue;
         }
-        async_list.emplace_back(task);
-    }
-    ret = aclrtSynchronizeStreamWithTimeout(
-        stream_, static_cast<int32_t>(transfer_timeout_));
-    if (ret == ACL_ERROR_NONE) {
-        VLOG(1) << "Copy with aclrtMemcpyAsync suc.";
-        for (auto &task : async_list) {
-            task->status_word = TransferStatusEnum::COMPLETED;
-        }
-    } else {
-        LOG(ERROR) << "Memory copy failed.";
-        (void)aclrtStreamAbort(stream_);
-        for (auto &task : async_list) {
-            task->status_word = TransferStatusEnum::FAILED;
+        auto status = engine->deregisterMem(reinterpret_cast<void*>(desc.addr));
+        if (!status.ok() && first_error.ok()) {
+            first_error = status;
         }
     }
+    return first_error;
 }
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/src/transport/ascend/hixl_engine.cpp b/mooncake-transfer-engine/tent/src/transport/ascend/hixl_engine.cpp
new file mode 100644
index 0000000000..0b10897908
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/ascend/hixl_engine.cpp
@@ -0,0 +1,355 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/ascend/hixl_engine.h"
+
+#include <algorithm>
+#include <utility>
+
+#include <glog/logging.h>
+#include <hixl/hixl.h>
+
+#include "tent/common/status.h"
+#include "tent/transport/ascend/resource_config.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class RealHixlVendor final : public HixlEngine::Vendor {
+   public:
+    uint32_t Initialize(
+        const std::string& local_name,
+        const std::map<std::string, std::string>& options) override {
+        std::map<hixl::AscendString, hixl::AscendString> hixl_options;
+        for (const auto& [key, value] : options) {
+            hixl_options[key.c_str()] = value.c_str();
+        }
+        return hixl_.Initialize(hixl::AscendString(local_name.c_str()),
+                                hixl_options);
+    }
+
+    void Finalize() override { hixl_.Finalize(); }
+
+    uint32_t RegisterMem(uint64_t addr, size_t len, bool host,
+                         void*& handle) override {
+        hixl::MemDesc mem_desc{};
+        mem_desc.addr = addr;
+        mem_desc.len = len;
+        hixl::MemHandle mem_handle = nullptr;
+        auto status = hixl_.RegisterMem(
+            mem_desc, host ? hixl::MEM_HOST : hixl::MEM_DEVICE, mem_handle);
+        handle = mem_handle;
+        return status;
+    }
+
+    uint32_t DeregisterMem(void* handle) override {
+        return hixl_.DeregisterMem(handle);
+    }
+
+    uint32_t TransferAsync(const std::string& remote, bool write,
+                           const std::vector<HixlOpDesc>& descs,
+                           void*& req) override {
+        std::vector<hixl::TransferOpDesc> op_descs;
+        op_descs.reserve(descs.size());
+        for (const auto& desc : descs) {
+            hixl::TransferOpDesc op{};
+            op.local_addr = desc.local_addr;
+            op.remote_addr = desc.remote_addr;
+            op.len = desc.len;
+            op_descs.push_back(op);
+        }
+        hixl::TransferReq handle = nullptr;
+        auto status =
+            hixl_.TransferAsync(hixl::AscendString(remote.c_str()),
+                                write ? hixl::WRITE : hixl::READ, op_descs,
+                                hixl::TransferArgs(), handle);
+        req = handle;
+        return status;
+    }
+
+    uint32_t GetTransferStatus(void* req, HixlXferState& status) override {
+        hixl::TransferStatus xfer_status = hixl::TransferStatus::WAITING;
+        auto err = hixl_.GetTransferStatus(req, xfer_status);
+        if (err != hixl::SUCCESS) {
+            status = HixlXferState::Failed;
+            return err;
+        }
+        switch (xfer_status) {
+            case hixl::TransferStatus::COMPLETED:
+                status = HixlXferState::Completed;
+                break;
+            case hixl::TransferStatus::TIMEOUT:
+                status = HixlXferState::Timeout;
+                break;
+            case hixl::TransferStatus::FAILED:
+                status = HixlXferState::Failed;
+                break;
+            case hixl::TransferStatus::WAITING:
+            default:
+                status = HixlXferState::Waiting;
+                break;
+        }
+        return hixl::SUCCESS;
+    }
+
+    uint32_t Disconnect(const std::string& remote,
+                        int32_t timeout_ms) override {
+        return hixl_.Disconnect(hixl::AscendString(remote.c_str()), timeout_ms);
+    }
+
+    uint32_t Connect(const std::string& remote, int32_t timeout_ms) override {
+        return hixl_.Connect(hixl::AscendString(remote.c_str()), timeout_ms);
+    }
+
+   private:
+    hixl::Hixl hixl_;
+};
+
+std::mutex g_vendor_factory_mu;
+HixlEngine::VendorFactory g_vendor_factory =
+    []() -> std::unique_ptr<HixlEngine::Vendor> {
+    return std::make_unique<RealHixlVendor>();
+};
+
+void DisconnectRemotes(HixlEngine::Vendor& vendor,
+                       std::vector<std::string>& remotes) {
+    for (const auto& remote : remotes) {
+        const auto status =
+            vendor.Disconnect(remote, kAscendTimeoutDisconnectMs);
+        if (status != kHixlOk && status != kHixlNotConnected) {
+            LOG(WARNING) << "Disconnect " << remote
+                         << " before teardown failed, status=" << status;
+        }
+    }
+    remotes.clear();
+}
+
+}  // namespace
+
+void HixlEngine::SetVendorFactory(VendorFactory factory) {
+    std::lock_guard<std::mutex> lock(g_vendor_factory_mu);
+    if (factory) {
+        g_vendor_factory = std::move(factory);
+    } else {
+        g_vendor_factory = []() -> std::unique_ptr<Vendor> {
+            return std::make_unique<RealHixlVendor>();
+        };
+    }
+}
+
+HixlEngine::VendorFactory HixlEngine::GetVendorFactory() {
+    std::lock_guard<std::mutex> lock(g_vendor_factory_mu);
+    return g_vendor_factory;
+}
+
+std::unique_ptr<HixlEngine::Vendor> HixlEngine::CreateVendor() {
+    return GetVendorFactory()();
+}
+
+HixlEngine::ContextGuard::ContextGuard(aclrtContext target) {
+    ok_ = (aclrtGetCurrentContext(&saved_) == ACL_ERROR_NONE);
+    if (!ok_) {
+        LOG(ERROR) << "aclrtGetCurrentContext failed, errmsg: "
+                   << aclGetRecentErrMsg();
+        return;
+    }
+    if (target != nullptr && aclrtSetCurrentContext(target) != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtSetCurrentContext failed, errmsg: "
+                   << aclGetRecentErrMsg();
+        ok_ = false;
+    }
+}
+
+HixlEngine::ContextGuard::~ContextGuard() {
+    if (ok_ && saved_ != nullptr) {
+        (void)aclrtSetCurrentContext(saved_);
+    }
+}
+
+HixlEngine::~HixlEngine() { finalize(); }
+
+Status HixlEngine::initialize(
+    const std::string& name, aclrtContext context, int32_t device_id,
+    const std::map<std::string, std::string>& options) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    name_ = name;
+    context_ = context;
+    device_id_ = device_id;
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    vendor_ = CreateVendor();
+    if (!vendor_) {
+        return Status::InternalError("Create HIXL vendor failed" LOC_MARK);
+    }
+    auto status = vendor_->Initialize(name_, options);
+    if (status != kHixlOk) {
+        LOG(ERROR) << "Failed to initialize HIXL engine " << name_
+                   << ", status: " << status
+                   << ", errmsg: " << aclGetRecentErrMsg();
+        vendor_.reset();
+        return Status::InternalError("Initialize hixl failed" LOC_MARK);
+    }
+    initialized_ = true;
+    LOG(INFO) << "Initialized HIXL engine " << name_
+              << " device_id=" << device_id_;
+    return Status::OK();
+}
+
+void HixlEngine::finalize() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!vendor_) {
+        addr_to_handle_.clear();
+        remotes_.clear();
+        initialized_ = false;
+        return;
+    }
+    ContextGuard guard(context_);
+    // AutoConnect leaves sessions up on the success path. HIXL requires
+    // those sessions to be gone before DeregisterMem / Finalize.
+    DisconnectRemotes(*vendor_, remotes_);
+    for (auto& [addr, handle] : addr_to_handle_) {
+        (void)addr;
+        (void)vendor_->DeregisterMem(handle);
+    }
+    addr_to_handle_.clear();
+    vendor_->Finalize();
+    vendor_.reset();
+    initialized_ = false;
+}
+
+Status HixlEngine::registerMem(void* addr, size_t length, bool host) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!vendor_) {
+        return Status::InternalError("HIXL engine is not initialized" LOC_MARK);
+    }
+    if (addr == nullptr || length == 0) {
+        return Status::InvalidArgument(
+            "Cannot register an empty HIXL memory range" LOC_MARK);
+    }
+    if (addr_to_handle_.find(addr) != addr_to_handle_.end()) {
+        return Status::InvalidArgument(
+            "HIXL memory range is already registered" LOC_MARK);
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    void* handle = nullptr;
+    auto status = vendor_->RegisterMem(reinterpret_cast<uint64_t>(addr), length,
+                                       host, handle);
+    if (status != kHixlOk) {
+        LOG(ERROR) << "RegisterMem failed, addr: " << addr
+                   << ", length: " << length
+                   << ", mem type: " << (host ? "host" : "device")
+                   << ", device_id: " << device_id_ << ", status: " << status
+                   << ", errmsg: " << aclGetRecentErrMsg();
+        return Status::InternalError("Register failed" LOC_MARK);
+    }
+    addr_to_handle_[addr] = handle;
+    return Status::OK();
+}
+
+Status HixlEngine::deregisterMem(void* addr) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = addr_to_handle_.find(addr);
+    if (!vendor_ || it == addr_to_handle_.end()) {
+        return Status::OK();
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    DisconnectRemotes(*vendor_, remotes_);
+    auto status = vendor_->DeregisterMem(it->second);
+    addr_to_handle_.erase(it);
+    if (status != kHixlOk) {
+        LOG(ERROR) << "DeregisterMem failed for " << addr
+                   << ", status: " << status
+                   << ", errmsg: " << aclGetRecentErrMsg();
+        return Status::InternalError("Deregister failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+void HixlEngine::rollbackMem(void* addr) { (void)deregisterMem(addr); }
+
+Status HixlEngine::transferAsync(const std::string& remote, bool write,
+                                 const std::vector<HixlOpDesc>& descs,
+                                 void*& req) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    req = nullptr;
+    if (!vendor_) {
+        return Status::InternalError("HIXL engine is not initialized" LOC_MARK);
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    auto status = vendor_->TransferAsync(remote, write, descs, req);
+    if (status != kHixlOk) {
+        LOG(ERROR) << "TransferAsync failed to " << remote
+                   << ", status: " << status
+                   << ", errmsg: " << aclGetRecentErrMsg();
+        return Status::InternalError("TransferAsync failed" LOC_MARK);
+    }
+    if (std::find(remotes_.begin(), remotes_.end(), remote) == remotes_.end()) {
+        remotes_.push_back(remote);
+    }
+    return Status::OK();
+}
+
+Status HixlEngine::getTransferStatus(void* req, HixlXferState& status) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!vendor_) {
+        status = HixlXferState::Failed;
+        return Status::InternalError("HIXL engine is not initialized" LOC_MARK);
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        status = HixlXferState::Failed;
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    auto err = vendor_->GetTransferStatus(req, status);
+    if (err != kHixlOk) {
+        status = HixlXferState::Failed;
+        return Status::InternalError("GetTransferStatus failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+Status HixlEngine::disconnectOnTimeout(const std::string& remote,
+                                       int32_t timeout_ms) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!vendor_) {
+        return Status::OK();
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    auto status = vendor_->Disconnect(remote, timeout_ms);
+    if (status != kHixlOk && status != kHixlNotConnected) {
+        LOG(ERROR) << "Disconnect after timeout failed for " << remote
+                   << ", status: " << status
+                   << ", errmsg: " << aclGetRecentErrMsg();
+        return Status::InternalError("Disconnect failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/ascend/local_copy_engine.cpp b/mooncake-transfer-engine/tent/src/transport/ascend/local_copy_engine.cpp
new file mode 100644
index 0000000000..ce9c543bc8
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/ascend/local_copy_engine.cpp
@@ -0,0 +1,280 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/ascend/local_copy_engine.h"
+
+#include <glog/logging.h>
+
+#include "tent/common/utils/os.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+constexpr uint32_t kStreamFlags = ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC;
+constexpr uint32_t kDoneFlag = 1;
+constexpr size_t kFlagBytes = sizeof(uint32_t);
+}  // namespace
+
+LocalCopyEngine::ContextGuard::ContextGuard(aclrtContext target) {
+    ok_ = (aclrtGetCurrentContext(&saved_) == ACL_ERROR_NONE);
+    if (!ok_) {
+        LOG(ERROR) << "aclrtGetCurrentContext failed, errmsg: "
+                   << aclGetRecentErrMsg();
+        return;
+    }
+    if (target != nullptr && aclrtSetCurrentContext(target) != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtSetCurrentContext failed, errmsg: "
+                   << aclGetRecentErrMsg();
+        ok_ = false;
+    }
+}
+
+LocalCopyEngine::ContextGuard::~ContextGuard() {
+    if (ok_ && saved_ != nullptr) {
+        (void)aclrtSetCurrentContext(saved_);
+    }
+}
+
+LocalCopyEngine::~LocalCopyEngine() { finalize(); }
+
+Status LocalCopyEngine::createStreamLocked() {
+    if (stream_ != nullptr) {
+        // A failed submit or timeout can leave work queued on the old stream.
+        // Abort it before destroying the stream so a later device copy cannot
+        // observe stale work from the previous generation.
+        (void)aclrtStreamAbort(stream_);
+        (void)aclrtDestroyStream(stream_);
+        stream_ = nullptr;
+    }
+    auto ret = aclrtCreateStreamWithConfig(&stream_, 0, kStreamFlags);
+    if (ret != ACL_ERROR_NONE || stream_ == nullptr) {
+        stream_ = nullptr;
+        LOG(ERROR) << "aclrtCreateStreamWithConfig failed, ret:" << ret
+                   << ", errmsg:" << aclGetRecentErrMsg();
+        return Status::InternalError(
+            "Create local copy stream failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+Status LocalCopyEngine::initialize(aclrtContext context, int32_t device_id) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    context_ = context;
+    device_id_ = device_id;
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+    CHECK_STATUS(createStreamLocked());
+    auto tear_down = [this]() {
+        if (stream_ != nullptr) {
+            (void)aclrtStreamAbort(stream_);
+            (void)aclrtDestroyStream(stream_);
+            stream_ = nullptr;
+        }
+        if (device_one_ != nullptr) {
+            (void)aclrtFree(device_one_);
+            device_one_ = nullptr;
+        }
+    };
+    auto ret = aclrtMalloc(&device_one_, kFlagBytes, ACL_MEM_MALLOC_HUGE_FIRST);
+    if (ret != ACL_ERROR_NONE || device_one_ == nullptr) {
+        device_one_ = nullptr;
+        LOG(ERROR) << "aclrtMalloc device flag failed, ret:" << ret;
+        tear_down();
+        return Status::InternalError(
+            "Alloc local copy device flag failed" LOC_MARK);
+    }
+    uint32_t one = kDoneFlag;
+    ret = aclrtMemcpy(device_one_, kFlagBytes, &one, kFlagBytes,
+                      ACL_MEMCPY_HOST_TO_DEVICE);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtMemcpy device flag failed, ret:" << ret;
+        tear_down();
+        return Status::InternalError(
+            "Init local copy device flag failed" LOC_MARK);
+    }
+    initialized_ = true;
+    return Status::OK();
+}
+
+void LocalCopyEngine::finalize() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    ContextGuard guard(context_);
+    for (auto& [handle, group] : groups_) {
+        (void)handle;
+        if (group) {
+            freeHostFlag(group->host_flag);
+        }
+    }
+    groups_.clear();
+    if (stream_ != nullptr) {
+        (void)aclrtStreamAbort(stream_);
+        (void)aclrtDestroyStream(stream_);
+        stream_ = nullptr;
+    }
+    if (device_one_ != nullptr) {
+        (void)aclrtFree(device_one_);
+        device_one_ = nullptr;
+    }
+    initialized_ = false;
+}
+
+Status LocalCopyEngine::allocHostFlag(volatile uint32_t*& flag) {
+    void* ptr = nullptr;
+    auto ret = aclrtMallocHost(&ptr, kFlagBytes);
+    if (ret != ACL_ERROR_NONE || ptr == nullptr) {
+        flag = nullptr;
+        return Status::InternalError(
+            "Alloc local copy host flag failed" LOC_MARK);
+    }
+    flag = static_cast<volatile uint32_t*>(ptr);
+    *flag = 0;
+    return Status::OK();
+}
+
+void LocalCopyEngine::freeHostFlag(volatile uint32_t* flag) {
+    if (flag != nullptr) {
+        (void)aclrtFreeHost(const_cast<uint32_t*>(flag));
+    }
+}
+
+aclrtMemcpyKind LocalCopyEngine::memcpyKind(void* src, void* dst) {
+    aclrtPtrAttributes src_attrs{};
+    aclrtPtrAttributes dst_attrs{};
+    if (aclrtPointerGetAttributes(src, &src_attrs) != ACL_ERROR_NONE ||
+        aclrtPointerGetAttributes(dst, &dst_attrs) != ACL_ERROR_NONE) {
+        return ACL_MEMCPY_DEFAULT;
+    }
+    const bool src_host = src_attrs.location.type == ACL_MEM_LOCATION_TYPE_HOST;
+    const bool dst_host = dst_attrs.location.type == ACL_MEM_LOCATION_TYPE_HOST;
+    if (src_host && dst_host) {
+        return ACL_MEMCPY_HOST_TO_HOST;
+    }
+    if (!src_host && !dst_host) {
+        return ACL_MEMCPY_DEVICE_TO_DEVICE;
+    }
+    if (src_host) {
+        return ACL_MEMCPY_HOST_TO_DEVICE;
+    }
+    return ACL_MEMCPY_DEVICE_TO_HOST;
+}
+
+std::vector<void*> LocalCopyEngine::failAndRecreateLocked() {
+    std::vector<void*> handles;
+    handles.reserve(groups_.size());
+    for (auto& [handle, group] : groups_) {
+        if (group) {
+            group->failed = true;
+        }
+        handles.push_back(handle);
+    }
+    auto status = createStreamLocked();
+    if (!status.ok()) {
+        LOG(ERROR) << "Recreate local copy stream failed: "
+                   << status.ToString();
+    }
+    return handles;
+}
+
+std::vector<void*> LocalCopyEngine::failAndRecreate() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    ContextGuard guard(context_);
+    return failAndRecreateLocked();
+}
+
+Status LocalCopyEngine::submit(bool write, const std::vector<HixlOpDesc>& ops,
+                               void*& req, std::vector<void*>& failed_handles) {
+    req = nullptr;
+    failed_handles.clear();
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!initialized_ || stream_ == nullptr || device_one_ == nullptr) {
+        return Status::InternalError(
+            "Local copy engine is not initialized" LOC_MARK);
+    }
+    ContextGuard guard(context_);
+    if (!guard.ok()) {
+        return Status::InternalError("Set ACL context failed" LOC_MARK);
+    }
+
+    auto group = std::make_unique<Group>();
+    CHECK_STATUS(allocHostFlag(group->host_flag));
+
+    auto fail_stream = [&]() {
+        freeHostFlag(group->host_flag);
+        group->host_flag = nullptr;
+        failed_handles = failAndRecreateLocked();
+    };
+
+    for (const auto& op : ops) {
+        void* local = reinterpret_cast<void*>(op.local_addr);
+        void* remote = reinterpret_cast<void*>(op.remote_addr);
+        void* src = write ? local : remote;
+        void* dst = write ? remote : local;
+        auto ret = aclrtMemcpyAsync(dst, op.len, src, op.len,
+                                    memcpyKind(src, dst), stream_);
+        if (ret != ACL_ERROR_NONE) {
+            LOG(ERROR) << "aclrtMemcpyAsync failed, ret:" << ret
+                       << ", errmsg:" << aclGetRecentErrMsg();
+            fail_stream();
+            return Status::InternalError("aclrtMemcpyAsync failed" LOC_MARK);
+        }
+    }
+
+    auto* host_flag = const_cast<uint32_t*>(group->host_flag);
+    auto ret = aclrtMemcpyAsync(host_flag, kFlagBytes, device_one_, kFlagBytes,
+                                ACL_MEMCPY_DEVICE_TO_HOST, stream_);
+    if (ret != ACL_ERROR_NONE) {
+        LOG(ERROR) << "aclrtMemcpyAsync host flag failed, ret:" << ret
+                   << ", errmsg:" << aclGetRecentErrMsg();
+        fail_stream();
+        return Status::InternalError(
+            "aclrtMemcpyAsync host flag failed" LOC_MARK);
+    }
+
+    req = group.get();
+    groups_[req] = std::move(group);
+    return Status::OK();
+}
+
+TransferStatusEnum LocalCopyEngine::poll(void* req) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = groups_.find(req);
+    if (it == groups_.end() || !it->second) {
+        return TransferStatusEnum::FAILED;
+    }
+    if (it->second->failed) {
+        return TransferStatusEnum::FAILED;
+    }
+    if (it->second->host_flag != nullptr &&
+        *it->second->host_flag == kDoneFlag) {
+        return TransferStatusEnum::COMPLETED;
+    }
+    return TransferStatusEnum::PENDING;
+}
+
+void LocalCopyEngine::release(void* req) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = groups_.find(req);
+    if (it == groups_.end()) {
+        return;
+    }
+    if (it->second) {
+        freeHostFlag(it->second->host_flag);
+    }
+    groups_.erase(it);
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/ascend/resource_config.cpp b/mooncake-transfer-engine/tent/src/transport/ascend/resource_config.cpp
new file mode 100644
index 0000000000..3de263a65c
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/ascend/resource_config.cpp
@@ -0,0 +1,429 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/ascend/resource_config.h"
+
+#include <netinet/in.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <cstdlib>
+#include <cstring>
+#include <utility>
+#include <exception>
+#include <limits>
+#include <random>
+#include <stdexcept>
+
+#include <glog/logging.h>
+#include <acl/acl.h>
+
+#include "tent/common/types.h"
+#include "tent/thirdparty/nlohmann/json.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr int32_t kPortRange = 100;
+constexpr int32_t kMaxPortAttempts = 500;
+constexpr int32_t kMinListenPort = 1024;
+constexpr int32_t kMaxListenPort = 65535;
+constexpr const char* kStoreKey = "store";
+constexpr const char* kFabricKey = "fabric_memory";
+constexpr const char* kFabricFlatPrefix = "fabric_memory.";
+constexpr const char* kRocePrefix = "roce:";
+
+using json = nlohmann::json;
+
+bool EnvFlagIsOne(const char* value) {
+    return value && std::strcmp(value, "1") == 0;
+}
+
+int32_t ParseEnvInt(const char* name, int32_t fallback) {
+    const char* raw = std::getenv(name);
+    if (!raw || raw[0] == '\0') {
+        return fallback;
+    }
+    try {
+        size_t parsed = 0;
+        const auto value = std::stoll(raw, &parsed);
+        if (parsed != std::strlen(raw) ||
+            value < std::numeric_limits<int32_t>::min() ||
+            value > std::numeric_limits<int32_t>::max()) {
+            throw std::out_of_range("integer range");
+        }
+        return static_cast<int32_t>(value);
+    } catch (const std::exception&) {
+        LOG(WARNING) << name << " is not a valid integer: " << raw;
+        return fallback;
+    }
+}
+
+bool ValidBasePort(int32_t base_port) {
+    return base_port >= kMinListenPort &&
+           base_port <= kMaxListenPort - kPortRange;
+}
+
+std::string EnvOrEmpty(const char* name) {
+    const char* raw = std::getenv(name);
+    return raw ? std::string(raw) : std::string();
+}
+
+bool HasRoceProtocolDesc(const json& root) {
+    json protocol;
+    if (root.contains("comm_resource_config.protocol_desc")) {
+        protocol = root["comm_resource_config.protocol_desc"];
+    } else if (root.contains("comm_resource_config") &&
+               root["comm_resource_config"].is_object() &&
+               root["comm_resource_config"].contains("protocol_desc")) {
+        protocol = root["comm_resource_config"]["protocol_desc"];
+    } else {
+        return false;
+    }
+    auto is_roce = [](const std::string& desc) {
+        return desc.rfind(kRocePrefix, 0) == 0;
+    };
+    if (protocol.is_string()) {
+        return is_roce(protocol.get<std::string>());
+    }
+    if (protocol.is_array()) {
+        for (const auto& item : protocol) {
+            if (item.is_string() && is_roce(item.get<std::string>())) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+bool HasFabricMemory(const json& root) {
+    if (!root.is_object()) {
+        return false;
+    }
+    if (root.contains(kFabricKey)) {
+        return true;
+    }
+    for (auto it = root.begin(); it != root.end(); ++it) {
+        const auto& key = it.key();
+        if (key.rfind(kFabricFlatPrefix, 0) == 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+json ParseResourceJson(const std::string& raw) {
+    if (raw.empty()) {
+        return json();
+    }
+    json parsed = json::parse(raw, nullptr, false);
+    if (parsed.is_discarded() || !parsed.is_object()) {
+        return json();
+    }
+    return parsed;
+}
+
+std::string ResolveGlobalResourceConfig(const std::string& raw,
+                                        bool store_te_init) {
+    if (raw.empty()) {
+        return {};
+    }
+    json root = json::parse(raw, nullptr, false);
+    if (root.is_discarded() || !root.is_object() || !root.contains(kStoreKey)) {
+        return raw;
+    }
+    if (store_te_init) {
+        return root[kStoreKey].dump();
+    }
+    json normal = root;
+    normal.erase(kStoreKey);
+    return normal.dump();
+}
+
+}  // namespace
+
+bool ParseEnvEnabled(const char* name) {
+    return EnvFlagIsOne(std::getenv(name));
+}
+
+AscendDirectOptions LoadAscendDirectOptions(
+    const std::shared_ptr<Config>& conf) {
+    AscendDirectOptions options;
+    options.store_te_init =
+        conf && conf->get("transports/ascend_direct/store_te_init", false);
+    options.agent_mode =
+        conf && conf->get("transports/ascend_direct/agent_mode", false);
+
+    options.transfer_timeout_ms = kAscendDefaultTransferTimeoutMs;
+    if (conf &&
+        conf->contains("transports/ascend_direct/transfer_timeout_ms")) {
+        options.transfer_timeout_ms = static_cast<int32_t>(
+            conf->get("transports/ascend_direct/transfer_timeout_ms",
+                      static_cast<long long>(kAscendDefaultTransferTimeoutMs)));
+    }
+    options.transfer_timeout_ms =
+        ParseEnvInt("ASCEND_TRANSFER_TIMEOUT", options.transfer_timeout_ms);
+    if (options.transfer_timeout_ms <= 0) {
+        options.transfer_timeout_ms = kAscendDefaultTransferTimeoutMs;
+    }
+
+    options.base_port = ParseEnvInt("ASCEND_BASE_PORT", kAscendDefaultBasePort);
+    if (conf && conf->contains("transports/ascend_direct/base_port")) {
+        options.base_port = static_cast<int32_t>(
+            conf->get("transports/ascend_direct/base_port",
+                      static_cast<long long>(options.base_port)));
+    }
+    if (!ValidBasePort(options.base_port)) {
+        LOG(WARNING) << "Invalid ASCEND_BASE_PORT/base_port="
+                     << options.base_port << ", using "
+                     << kAscendDefaultBasePort;
+        options.base_port = kAscendDefaultBasePort;
+    }
+
+    if (conf) {
+        options.rdma_tc = conf->get("transports/ascend_direct/rdma_tc", "");
+        options.rdma_sl = conf->get("transports/ascend_direct/rdma_sl", "");
+    }
+    if (options.rdma_tc.empty()) {
+        options.rdma_tc = EnvOrEmpty("ASCEND_RDMA_TC");
+    }
+    if (options.rdma_tc.empty()) {
+        options.rdma_tc = EnvOrEmpty("HCCL_RDMA_TC");
+    }
+    if (options.rdma_sl.empty()) {
+        options.rdma_sl = EnvOrEmpty("ASCEND_RDMA_SL");
+    }
+    if (options.rdma_sl.empty()) {
+        options.rdma_sl = EnvOrEmpty("HCCL_RDMA_SL");
+    }
+
+    const char* local_comm = std::getenv("ASCEND_LOCAL_COMM_RES");
+    options.local_comm_res = (local_comm && local_comm[0] != '\0')
+                                 ? local_comm
+                                 : kDefaultLocalCommRes;
+
+    std::string raw_resource;
+    if (conf &&
+        conf->contains("transports/ascend_direct/global_resource_config")) {
+        raw_resource =
+            conf->get("transports/ascend_direct/global_resource_config", "");
+    }
+    if (raw_resource.empty()) {
+        raw_resource = EnvOrEmpty("ASCEND_GLOBAL_RESOURCE_CONFIG");
+    }
+    options.global_resource_config =
+        ResolveGlobalResourceConfig(raw_resource, options.store_te_init);
+
+    bool conf_fabric =
+        conf && conf->get("transports/ascend_direct/fabric_mem", false);
+    json resolved = ParseResourceJson(options.global_resource_config);
+    // Store isolation: the TENT shim copies fabric_mem onto Config only when
+    // this engine is a Store TE. P2P TENT in the same process does not inherit
+    // ASCEND_ENABLE_USE_FABRIC_MEM unless store_te_init is set on this Config.
+    options.use_fabric_mem =
+        conf_fabric ||
+        (options.store_te_init &&
+         ParseEnvEnabled("ASCEND_ENABLE_USE_FABRIC_MEM")) ||
+        HasFabricMemory(resolved);
+
+    options.roce_mode = ParseEnvEnabled("HCCL_INTRA_ROCE_ENABLE") ||
+                        HasRoceProtocolDesc(resolved);
+    return options;
+}
+
+std::map<std::string, std::string> BuildHixlInitOptions(
+    const AscendDirectOptions& options) {
+    std::map<std::string, std::string> init;
+    init["AutoConnect"] = "1";
+    init["LocalCommRes"] = options.local_comm_res;
+    if (!options.rdma_tc.empty()) {
+        init["RdmaTrafficClass"] = options.rdma_tc;
+    }
+    if (!options.rdma_sl.empty()) {
+        init["RdmaServiceLevel"] = options.rdma_sl;
+    }
+    if (options.use_fabric_mem) {
+        init["EnableUseFabricMem"] = "1";
+    }
+    if (!options.global_resource_config.empty()) {
+        init["GlobalResourceConfig"] = options.global_resource_config;
+    }
+    return init;
+}
+
+uint16_t HixlRoceListenPort(uint16_t hixl_port) {
+    constexpr int kShift = 10000;
+    if (hixl_port <= static_cast<uint16_t>(65535 - kShift)) {
+        return static_cast<uint16_t>(hixl_port + kShift);
+    }
+    return static_cast<uint16_t>(hixl_port - kShift);
+}
+
+std::map<std::string, std::string> WithHixlListenPort(
+    const std::map<std::string, std::string>& init, uint16_t listen_port) {
+    auto out = init;
+    json root = json::object();
+    auto it = out.find("GlobalResourceConfig");
+    if (it != out.end() && !it->second.empty()) {
+        json parsed = json::parse(it->second, nullptr, false);
+        if (parsed.is_object()) {
+            root = std::move(parsed);
+        }
+    }
+    if (root.contains("comm_resource_config") &&
+        root["comm_resource_config"].is_object()) {
+        root["comm_resource_config"]["listen_port"] =
+            static_cast<int>(listen_port);
+        root.erase("comm_resource_config.listen_port");
+    } else {
+        // The environment commonly uses the flat-key form. Replace an
+        // existing value instead of leaving two representations with
+        // different ports for the HIXL parser to resolve ambiguously.
+        root.erase("comm_resource_config.listen_port");
+        root["comm_resource_config.listen_port"] =
+            static_cast<int>(listen_port);
+    }
+    out["GlobalResourceConfig"] = root.dump();
+    return out;
+}
+
+std::string HostIpFromSegmentName(const std::string& segment_name) {
+    if (!segment_name.empty() && segment_name.front() == '[') {
+        auto end = segment_name.find(']');
+        if (end != std::string::npos) {
+            return segment_name.substr(1, end - 1);
+        }
+    }
+    auto pos = segment_name.rfind(':');
+    if (pos != std::string::npos) {
+        return segment_name.substr(0, pos);
+    }
+    return segment_name;
+}
+
+std::string MakeHixlEngineName(const std::string& host_ip, uint16_t port) {
+    if (host_ip.find(':') != std::string::npos &&
+        (host_ip.empty() || host_ip.front() != '[')) {
+        return "[" + host_ip + "]:" + std::to_string(port);
+    }
+    return host_ip + ":" + std::to_string(port);
+}
+
+uint16_t FindHixlListenPort(int32_t base_port, int32_t device_id) {
+    if (device_id < 0 || !ValidBasePort(base_port)) {
+        LOG(ERROR) << "Invalid HIXL port range: base_port=" << base_port
+                   << ", device_id=" << device_id;
+        return 0;
+    }
+    int32_t physical_dev_id = device_id;
+    if (aclrtGetPhyDevIdByLogicDevId(device_id, &physical_dev_id) !=
+        ACL_ERROR_NONE) {
+        physical_dev_id = device_id;
+    }
+    static std::random_device rand_gen;
+    const int64_t min_port = static_cast<int64_t>(base_port) +
+                             static_cast<int64_t>(physical_dev_id) * kPortRange;
+    const int64_t max_port =
+        static_cast<int64_t>(base_port) +
+        (static_cast<int64_t>(physical_dev_id) + 1) * kPortRange;
+    if (min_port < kMinListenPort || max_port > kMaxListenPort) {
+        LOG(ERROR) << "HIXL port range exceeds TCP port space: [" << min_port
+                   << ", " << max_port << "]";
+        return 0;
+    }
+    LOG(INFO) << "Find HIXL listen port between " << min_port << " and "
+              << max_port;
+    std::uniform_int_distribution<int64_t> rand_dist(min_port, max_port);
+    for (int attempt = 0; attempt < kMaxPortAttempts; ++attempt) {
+        const int port = static_cast<int>(rand_dist(rand_gen));
+        int sockfd = socket(AF_INET, SOCK_STREAM, 0);
+        if (sockfd == -1) {
+            continue;
+        }
+        sockaddr_in bind_address{};
+        bind_address.sin_family = AF_INET;
+        bind_address.sin_port = htons(static_cast<uint16_t>(port));
+        bind_address.sin_addr.s_addr = INADDR_ANY;
+        if (bind(sockfd, reinterpret_cast<sockaddr*>(&bind_address),
+                 sizeof(bind_address)) < 0) {
+            close(sockfd);
+            continue;
+        }
+        close(sockfd);
+        return static_cast<uint16_t>(port);
+    }
+    return 0;
+}
+
+std::vector<std::string> ParseHixlNames(const MemorySegmentDesc& detail) {
+    auto names_it = detail.device_attrs.find(kHixlNamesAttr);
+    if (names_it != detail.device_attrs.end() && !names_it->second.empty()) {
+        json parsed = json::parse(names_it->second, nullptr, false);
+        if (parsed.is_array()) {
+            std::vector<std::string> names;
+            for (const auto& item : parsed) {
+                if (item.is_string()) {
+                    names.push_back(item.get<std::string>());
+                }
+            }
+            if (!names.empty()) {
+                return names;
+            }
+        }
+    }
+    auto name_it = detail.device_attrs.find(kHixlNameAttr);
+    if (name_it != detail.device_attrs.end() && !name_it->second.empty()) {
+        return {name_it->second};
+    }
+    return {};
+}
+
+std::string ResolveRemoteHixlName(const MemorySegmentDesc& detail,
+                                  uint64_t dest_addr) {
+    auto names = ParseHixlNames(detail);
+    if (names.empty()) {
+        return {};
+    }
+    if (names.size() == 1) {
+        return names.front();
+    }
+    for (const auto& buf : detail.buffers) {
+        if (dest_addr < buf.addr || dest_addr - buf.addr >= buf.length) {
+            continue;
+        }
+        auto attr = buf.transport_attrs.find(AscendDirect);
+        if (attr != buf.transport_attrs.end() && !attr->second.empty()) {
+            try {
+                const auto idx = static_cast<size_t>(std::stoul(attr->second));
+                if (idx < names.size()) {
+                    return names[idx];
+                }
+            } catch (const std::exception&) {
+            }
+        }
+        LocationParser location(buf.location);
+        if (location.type() == "npu" && location.index() >= 0) {
+            const auto idx = static_cast<size_t>(location.index());
+            if (idx < names.size()) {
+                return names[idx];
+            }
+        }
+        return names.front();
+    }
+    return names.front();
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/gds/gds_transport.cpp b/mooncake-transfer-engine/tent/src/transport/gds/gds_transport.cpp
index 6980d98c15..9961b192cd 100644
--- a/mooncake-transfer-engine/tent/src/transport/gds/gds_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/gds/gds_transport.cpp
@@ -87,6 +87,158 @@ TransferStatusEnum parseTransferStatus(CUfileStatus_t status) {
     }
 }
 
+bool isTerminalCuFileStatus(CUfileStatus_t status) {
+    return status != CUFILE_WAITING && status != CUFILE_PENDING;
+}
+
+TransferStatus GdsTransport::aggregateTransferStatus(
+    const std::vector<CUfileIOEvents_t>& events, size_t base, size_t count,
+    bool& all_terminal) {
+    all_terminal = true;
+    TransferStatus result{COMPLETED, 0};
+    if (count == 0 || base > events.size() || count > events.size() - base) {
+        result.s = INVALID;
+        return result;
+    }
+
+    // Use a fixed precedence so completion order does not change the result.
+    int failure_priority = 0;
+    for (size_t i = base; i < base + count; ++i) {
+        const auto& event = events[i];
+        const auto slice_status = parseTransferStatus(event.status);
+        switch (slice_status) {
+            case PENDING:
+                all_terminal = false;
+                break;
+            case COMPLETED:
+                if (event.ret > 0) {
+                    result.transferred_bytes += static_cast<size_t>(event.ret);
+                }
+                break;
+            case INVALID:
+                if (failure_priority < 1) {
+                    result.s = INVALID;
+                    failure_priority = 1;
+                }
+                break;
+            case CANCELED:
+                if (failure_priority < 2) {
+                    result.s = CANCELED;
+                    failure_priority = 2;
+                }
+                break;
+            case TIMEOUT:
+                if (failure_priority < 3) {
+                    result.s = TIMEOUT;
+                    failure_priority = 3;
+                }
+                break;
+            case FAILED:
+                result.s = FAILED;
+                failure_priority = 4;
+                break;
+            case INITIAL:
+                all_terminal = false;
+                break;
+        }
+    }
+
+    if (!all_terminal && failure_priority == 0) {
+        result.s = PENDING;
+    }
+    return result;
+}
+
+Status GdsTransport::updateBatchStatus(GdsSubBatch* batch) {
+    if (batch->io_events.size() < batch->io_params.size() ||
+        batch->cached_events.size() < batch->io_params.size()) {
+        return Status::InternalError(
+            "GDS completion buffers are smaller than the submitted IO "
+            "set" LOC_MARK);
+    }
+
+    unsigned num_events = static_cast<unsigned>(batch->io_params.size());
+    if (num_events == 0) return Status::OK();
+
+    auto result =
+        cuFileBatchIOGetStatus(batch->batch_handle->handle, 0, &num_events,
+                               batch->io_events.data(), nullptr);
+    if (result.err != CU_FILE_SUCCESS) {
+        return Status::InternalError(
+            std::string("Failed to get GDS batch status: Code ") +
+            std::to_string(result.err) + LOC_MARK);
+    }
+
+    for (size_t index = 0; index < num_events; ++index) {
+        const auto& event = batch->io_events[index];
+        const auto cookie = reinterpret_cast<std::uintptr_t>(event.cookie);
+        if (cookie == 0 || cookie > batch->cached_events.size()) {
+            LOG(ERROR) << "Invalid GDS batch IO cookie: " << cookie;
+            continue;
+        }
+
+        auto& cached_event = batch->cached_events[cookie - 1];
+        if (!isTerminalCuFileStatus(cached_event.status) ||
+            isTerminalCuFileStatus(event.status)) {
+            cached_event = event;
+        }
+    }
+    return Status::OK();
+}
+
+Status GdsTransport::cancelBatch(GdsSubBatch* batch) {
+    auto result = cuFileBatchIOCancel(batch->batch_handle->handle);
+    if (result.err != CU_FILE_SUCCESS) {
+        return Status::InternalError(
+            std::string("Failed to cancel GDS batch IO: Code ") +
+            std::to_string(result.err) + LOC_MARK);
+    }
+    return Status::OK();
+}
+
+bool GdsTransport::allBatchIOsTerminal(const GdsSubBatch* batch) {
+    if (batch->cached_events.size() < batch->io_params.size()) return false;
+    return std::all_of(batch->cached_events.begin(),
+                       batch->cached_events.begin() + batch->io_params.size(),
+                       [](const CUfileIOEvents_t& event) {
+                           return isTerminalCuFileStatus(event.status);
+                       });
+}
+
+bool GdsTransport::isTerminalFailure(TransferStatusEnum status) {
+    return status == INVALID || status == CANCELED || status == TIMEOUT ||
+           status == FAILED;
+}
+
+void GdsTransport::destroySubBatch(GdsSubBatch* batch) {
+    if (batch->batch_handle) {
+        cuFileBatchIODestroy(batch->batch_handle->handle);
+        delete batch->batch_handle;
+        batch->batch_handle = nullptr;
+    }
+    Slab<GdsSubBatch>::Get().deallocate(batch);
+}
+
+void GdsTransport::cleanupQuarantinedBatches() {
+    std::lock_guard<std::mutex> lock(quarantined_batches_lock_);
+    auto it = quarantined_batches_.begin();
+    while (it != quarantined_batches_.end()) {
+        auto* batch = *it;
+        bool ready_to_destroy = false;
+        {
+            std::lock_guard<std::mutex> status_lock(batch->status_mutex);
+            auto status = updateBatchStatus(batch);
+            ready_to_destroy = status.ok() && allBatchIOsTerminal(batch);
+        }
+        if (!ready_to_destroy) {
+            ++it;
+            continue;
+        }
+        destroySubBatch(batch);
+        it = quarantined_batches_.erase(it);
+    }
+}
+
 GdsTransport::GdsTransport() : installed_(false) {
     static std::once_flag g_once_flag;
     auto fork_init = []() { cuFileDriverOpen(); };
@@ -121,16 +273,19 @@ Status GdsTransport::uninstall() {
         {
             std::lock_guard<std::mutex> lock(allocated_batches_lock_);
             for (auto* gds_batch : allocated_batches_) {
-                // Destroy the batch handle (don't return to pool since we're
-                // shutting down)
-                cuFileBatchIODestroy(gds_batch->batch_handle->handle);
-                delete gds_batch->batch_handle;
-                // Deallocate the sub-batch
-                Slab<GdsSubBatch>::Get().deallocate(gds_batch);
+                destroySubBatch(gds_batch);
             }
             allocated_batches_.clear();
         }
 
+        {
+            std::lock_guard<std::mutex> lock(quarantined_batches_lock_);
+            for (auto* gds_batch : quarantined_batches_) {
+                destroySubBatch(gds_batch);
+            }
+            quarantined_batches_.clear();
+        }
+
         // Clean up all handles in the pool
         std::lock_guard<std::mutex> lock(handle_pool_lock_);
         for (auto* batch_handle : handle_pool_) {
@@ -146,6 +301,8 @@ Status GdsTransport::uninstall() {
 }
 
 Status GdsTransport::allocateSubBatch(SubBatchRef& batch, size_t max_size) {
+    cleanupQuarantinedBatches();
+
     auto gds_batch = Slab<GdsSubBatch>::Get().allocate();
     if (!gds_batch)
         return Status::InternalError("Unable to allocate GDS sub-batch");
@@ -189,6 +346,10 @@ Status GdsTransport::allocateSubBatch(SubBatchRef& batch, size_t max_size) {
     gds_batch->io_params.clear();
     gds_batch->io_params.reserve(io_batch_depth_);
     gds_batch->io_param_ranges.clear();
+    gds_batch->cached_events.clear();
+    gds_batch->cached_events.reserve(io_batch_depth_);
+    gds_batch->reusable = true;
+    gds_batch->cancel_requested = false;
 
     // Track this batch for cleanup on uninstall
     {
@@ -215,18 +376,28 @@ Status GdsTransport::freeSubBatch(SubBatchRef& batch) {
         }
     }
 
-    // Return the handle to pool for reuse (avoid expensive
-    // cuFileBatchIODestroy) Note: Caller should ensure all IOs are completed
-    // (via getTransferStatus) before calling freeSubBatch, as cuFile may still
-    // access io_params otherwise
+    // A normal batch is returned to the handle pool only after callers have
+    // observed terminal status for every task. A failed batch with active
+    // slices retains both its handle and parameter storage until cuFile no
+    // longer references them.
+    bool reusable = false;
     {
-        std::lock_guard<std::mutex> lock(handle_pool_lock_);
-        handle_pool_.push_back(gds_batch->batch_handle);
+        std::lock_guard<std::mutex> lock(gds_batch->status_mutex);
+        reusable = gds_batch->reusable;
+    }
+    if (reusable) {
+        {
+            std::lock_guard<std::mutex> lock(handle_pool_lock_);
+            handle_pool_.push_back(gds_batch->batch_handle);
+        }
+        gds_batch->batch_handle = nullptr;
+        Slab<GdsSubBatch>::Get().deallocate(gds_batch);
+    } else {
+        std::lock_guard<std::mutex> lock(quarantined_batches_lock_);
+        quarantined_batches_.push_back(gds_batch);
     }
-
-    // Deallocate the GdsSubBatch (each allocation gets a fresh one)
-    Slab<GdsSubBatch>::Get().deallocate(gds_batch);
     batch = nullptr;
+    cleanupQuarantinedBatches();
     return Status::OK();
 }
 
@@ -279,24 +450,30 @@ Status GdsTransport::submitTransferTasks(
         GdsFileContext* context = findFileContext(request.target_id);
         if (!context || !context->ready())
             return Status::InvalidArgument("Invalid remote segment" LOC_MARK);
-        size_t task_id = gds_batch->io_param_ranges.size();
         IOParamRange range;
         range.base = gds_batch->io_params.size();
         for (size_t offset = 0; offset < request.length;
              offset += kMaxSliceSize) {
             size_t length = std::min(kMaxSliceSize, request.length - offset);
+            const size_t slice_id = gds_batch->io_params.size();
             CUfileIOParams_t params;
             params.mode = CUFILE_BATCH;
             params.opcode =
                 (request.opcode == Request::READ) ? CUFILE_READ : CUFILE_WRITE;
-            params.cookie =
-                reinterpret_cast<void*>(static_cast<std::uintptr_t>(task_id));
+            // Use a one-based slice index so every completion can be cached
+            // independently, including the first slice (cookie 0 is avoided).
+            params.cookie = reinterpret_cast<void*>(
+                static_cast<std::uintptr_t>(slice_id + 1));
             params.u.batch.devPtr_base = request.source;
             params.u.batch.devPtr_offset = offset;
             params.u.batch.file_offset = request.target_offset + offset;
             params.u.batch.size = length;
             params.fh = context->getHandle();
             gds_batch->io_params.push_back(params);
+            CUfileIOEvents_t cached_event{};
+            cached_event.cookie = params.cookie;
+            cached_event.status = CUFILE_PENDING;
+            gds_batch->cached_events.push_back(cached_event);
             range.count++;
         }
         gds_batch->io_param_ranges.push_back(range);
@@ -315,39 +492,70 @@ Status GdsTransport::submitTransferTasks(
 Status GdsTransport::getTransferStatus(SubBatchRef batch, int task_id,
                                        TransferStatus& status) {
     auto gds_batch = dynamic_cast<GdsSubBatch*>(batch);
+    if (!gds_batch)
+        return Status::InvalidArgument("Invalid GDS sub-batch" LOC_MARK);
     unsigned num_tasks = gds_batch->io_param_ranges.size();
     if (task_id < 0 || task_id >= (int)num_tasks)
         return Status::InvalidArgument("Invalid task ID");
-    unsigned num_events = static_cast<unsigned>(gds_batch->io_params.size());
-    auto result =
-        cuFileBatchIOGetStatus(gds_batch->batch_handle->handle, 0, &num_events,
-                               gds_batch->io_events.data(), nullptr);
-    if (result.err != CU_FILE_SUCCESS)
-        return Status::InternalError(
-            std::string("Failed to get GDS batch status: Code ") +
-            std::to_string(result.err) + LOC_MARK);
+    std::lock_guard<std::mutex> lock(gds_batch->status_mutex);
+    auto& range = gds_batch->io_param_ranges[task_id];
+    if (range.status != PENDING) {
+        status = TransferStatus{range.status, range.transferred_bytes};
+        return Status::OK();
+    }
 
-    for (size_t index = 0; index < num_events; ++index) {
-        auto& event = gds_batch->io_events[index];
-        auto event_task_id = reinterpret_cast<std::uintptr_t>(event.cookie);
-        if (event_task_id >= gds_batch->io_param_ranges.size()) {
-            LOG(ERROR) << "Invalid GDS batch IO cookie: " << event_task_id;
-            continue;
+    auto update_status = updateBatchStatus(gds_batch);
+    if (!update_status.ok()) {
+        // The runtime may release the sub-batch after a polling error. Keep
+        // cuFile-owned storage out of the reusable pool unless we observed a
+        // terminal event for every submitted slice.
+        gds_batch->reusable = false;
+        if (!gds_batch->cancel_requested) {
+            gds_batch->cancel_requested = true;
+            auto cancel_status = cancelBatch(gds_batch);
+            if (!cancel_status.ok()) {
+                LOG(WARNING) << cancel_status.ToString();
+            }
         }
+        return update_status;
+    }
+    bool all_terminal = false;
+    auto task_status = aggregateTransferStatus(
+        gds_batch->cached_events, range.base, range.count, all_terminal);
+    if (range.known_failure == PENDING && isTerminalFailure(task_status.s)) {
+        range.known_failure = task_status.s;
+    }
 
-        auto& range = gds_batch->io_param_ranges[event_task_id];
-        auto s = parseTransferStatus(event.status);
-        if (s == COMPLETED) {
-            range.complete_count++;
-            range.transferred_bytes += event.ret;
-        } else if (s != PENDING) {
-            range.status = s;
+    if (range.known_failure != PENDING && !all_terminal) {
+        if (!gds_batch->cancel_requested) {
+            gds_batch->cancel_requested = true;
+            auto cancel_status = cancelBatch(gds_batch);
+            if (!cancel_status.ok()) {
+                LOG(WARNING) << cancel_status.ToString();
+            }
+        }
+
+        // Cancellation is best effort. Poll once more, but do not publish a
+        // terminal status while cuFile may still access the user buffer.
+        auto repoll_status = updateBatchStatus(gds_batch);
+        if (!repoll_status.ok()) {
+            LOG(WARNING) << repoll_status.ToString();
+        }
+        task_status = aggregateTransferStatus(
+            gds_batch->cached_events, range.base, range.count, all_terminal);
+        if (!all_terminal) {
+            gds_batch->reusable = false;
         }
     }
 
-    auto& range = gds_batch->io_param_ranges[task_id];
-    if (range.complete_count == range.count) {
-        range.status = COMPLETED;
+    // Expose partial progress while the task is still pending, and keep the
+    // reported byte count monotonic across repeated polls.
+    range.transferred_bytes =
+        std::max(range.transferred_bytes, task_status.transferred_bytes);
+    if (all_terminal) {
+        range.status = range.known_failure != PENDING ? range.known_failure
+                                                      : task_status.s;
+        gds_batch->reusable = allBatchIOsTerminal(gds_batch);
     }
     status = TransferStatus{range.status, range.transferred_bytes};
     return Status::OK();
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/hp_tcp/CMakeLists.txt
new file mode 100644
index 0000000000..937a1e4839
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/CMakeLists.txt
@@ -0,0 +1,9 @@
+add_library(
+  tent_xport_hp_tcp_core STATIC
+  hp_tcp_protocol.cpp hp_tcp_workers.cpp hp_tcp_task.cpp
+  hp_tcp_buffer_registry.cpp hp_tcp_client.cpp hp_tcp_server.cpp)
+target_link_libraries(tent_xport_hp_tcp_core PUBLIC tent_common tent_interface)
+
+add_library(tent_xport_hp_tcp STATIC hp_tcp_transport.cpp)
+target_link_libraries(tent_xport_hp_tcp PUBLIC tent_rpc tent_common
+                                               tent_xport_hp_tcp_core)
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_buffer_registry.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_buffer_registry.cpp
new file mode 100644
index 0000000000..d4f39d5ca5
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_buffer_registry.cpp
@@ -0,0 +1,265 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+
+#include <limits>
+#include <random>
+#include <string>
+#include <utility>
+
+namespace mooncake::tent {
+namespace {
+
+bool RangeEnd(uint64_t base, uint64_t length, uint64_t* end) {
+    if (end == nullptr || length == 0 ||
+        base > std::numeric_limits<uint64_t>::max() - length) {
+        return false;
+    }
+    *end = base + length;
+    return true;
+}
+
+uint64_t MakeRegistrationNamespace() {
+    std::random_device device;
+    std::seed_seq seed{device(), device(), device(), device(),
+                       device(), device(), device(), device()};
+    std::mt19937_64 random(seed);
+    return random();
+}
+
+Status LeaseError(HighPerformanceTcpStatus failure, const char* message) {
+    switch (failure) {
+        case HighPerformanceTcpStatus::kStaleRegistration:
+            return Status::NeedsRefreshCache(std::string(message) + LOC_MARK);
+        case HighPerformanceTcpStatus::kShuttingDown:
+            return Status::TooManyRequests(std::string(message) + LOC_MARK);
+        case HighPerformanceTcpStatus::kPermissionDenied:
+        case HighPerformanceTcpStatus::kRangeRejected:
+            return Status::AddressNotRegistered(std::string(message) +
+                                                LOC_MARK);
+        default:
+            return Status::InternalError(std::string(message) + LOC_MARK);
+    }
+}
+
+}  // namespace
+
+HighPerformanceTcpBufferRegistry::HighPerformanceTcpBufferRegistry()
+    : registration_namespace_(MakeRegistrationNamespace()) {}
+
+HighPerformanceTcpBufferRegistry::Lease::Lease(std::shared_ptr<Entry> entry)
+    : entry_(std::move(entry)) {}
+
+HighPerformanceTcpBufferRegistry::Lease::Lease(Lease&& other) noexcept
+    : entry_(std::move(other.entry_)) {}
+
+HighPerformanceTcpBufferRegistry::Lease&
+HighPerformanceTcpBufferRegistry::Lease::operator=(Lease&& other) noexcept {
+    if (this != &other) {
+        reset();
+        entry_ = std::move(other.entry_);
+    }
+    return *this;
+}
+
+HighPerformanceTcpBufferRegistry::Lease::~Lease() { reset(); }
+
+void HighPerformanceTcpBufferRegistry::Lease::reset() {
+    if (!entry_) return;
+    {
+        std::lock_guard<std::mutex> lock(entry_->mutex);
+        if (entry_->active_leases > 0) --entry_->active_leases;
+    }
+    entry_->drained.notify_all();
+    entry_.reset();
+}
+
+void* HighPerformanceTcpBufferRegistry::Lease::data() const {
+    return entry_ ? reinterpret_cast<void*>(entry_->base) : nullptr;
+}
+
+uint64_t HighPerformanceTcpBufferRegistry::Lease::base() const {
+    return entry_ ? entry_->base : 0;
+}
+
+uint64_t HighPerformanceTcpBufferRegistry::Lease::length() const {
+    return entry_ ? entry_->length : 0;
+}
+
+Status HighPerformanceTcpBufferRegistry::add(uint64_t base, uint64_t length,
+                                             Permission permission,
+                                             uint64_t* registration_id) {
+    uint64_t end = 0;
+    if (!RangeEnd(base, length, &end)) {
+        return Status::InvalidArgument("invalid HP TCP buffer range" LOC_MARK);
+    }
+    if (permission != kLocalReadWrite && permission != kGlobalReadOnly &&
+        permission != kGlobalReadWrite) {
+        return Status::InvalidArgument(
+            "invalid HP TCP buffer permission" LOC_MARK);
+    }
+
+    std::lock_guard<std::mutex> lock(registry_mutex_);
+    if (closing_) {
+        return Status::TooManyRequests(
+            "HP TCP buffer registry is shutting down" LOC_MARK);
+    }
+    const auto next = entries_.upper_bound(base);
+    if (next != entries_.end() && end > next->second->base) {
+        return Status::InvalidArgument("overlapping HP TCP buffer" LOC_MARK);
+    }
+    if (next != entries_.begin()) {
+        const auto previous = std::prev(next);
+        uint64_t previous_end = 0;
+        if (!RangeEnd(previous->second->base, previous->second->length,
+                      &previous_end) ||
+            previous_end > base) {
+            return Status::InvalidArgument(
+                "overlapping HP TCP buffer" LOC_MARK);
+        }
+    }
+
+    if (next_registration_sequence_ == 0 ||
+        next_registration_sequence_ == std::numeric_limits<uint64_t>::max()) {
+        return Status::InternalError(
+            "HP TCP registration id space exhausted" LOC_MARK);
+    }
+    uint64_t id = registration_namespace_ ^ next_registration_sequence_++;
+    if (id == 0) {
+        if (next_registration_sequence_ ==
+            std::numeric_limits<uint64_t>::max()) {
+            return Status::InternalError(
+                "HP TCP registration id space exhausted" LOC_MARK);
+        }
+        id = registration_namespace_ ^ next_registration_sequence_++;
+    }
+
+    auto entry = std::make_shared<Entry>();
+    entry->base = base;
+    entry->length = length;
+    entry->permission = permission;
+    entry->registration_id = id;
+    entries_.emplace(base, entry);
+    if (registration_id != nullptr) *registration_id = id;
+    return Status::OK();
+}
+
+Status HighPerformanceTcpBufferRegistry::remove(uint64_t base,
+                                                uint64_t length) {
+    std::shared_ptr<Entry> entry;
+    {
+        std::lock_guard<std::mutex> registry_lock(registry_mutex_);
+        const auto it = entries_.find(base);
+        if (it == entries_.end() || it->second->length != length) {
+            return Status::AddressNotRegistered(
+                "HP TCP buffer not registered" LOC_MARK);
+        }
+        entry = it->second;
+        // Hide the range before waiting so no new lease can race in.
+        entries_.erase(it);
+    }
+
+    std::unique_lock<std::mutex> entry_lock(entry->mutex);
+    entry->drained.wait(entry_lock, [&] { return entry->active_leases == 0; });
+    return Status::OK();
+}
+
+void HighPerformanceTcpBufferRegistry::close() {
+    std::lock_guard<std::mutex> lock(registry_mutex_);
+    closing_ = true;
+}
+
+Status HighPerformanceTcpBufferRegistry::reopen() {
+    std::lock_guard<std::mutex> lock(registry_mutex_);
+    if (!entries_.empty()) {
+        return Status::InvalidArgument(
+            "cannot reopen HP TCP buffer registry while buffers remain "
+            "registered" LOC_MARK);
+    }
+    closing_ = false;
+    return Status::OK();
+}
+
+Status HighPerformanceTcpBufferRegistry::acquireLocalLease(uint64_t addr,
+                                                           uint64_t length,
+                                                           Lease* lease) {
+    return acquire(addr, length, 0, HighPerformanceTcpOpcode::kRead, false,
+                   lease, nullptr);
+}
+
+Status HighPerformanceTcpBufferRegistry::acquireRemoteLease(
+    uint64_t addr, uint64_t length, uint64_t registration_id,
+    HighPerformanceTcpOpcode opcode, Lease* lease,
+    HighPerformanceTcpStatus* failure) {
+    return acquire(addr, length, registration_id, opcode, true, lease, failure);
+}
+
+Status HighPerformanceTcpBufferRegistry::acquire(
+    uint64_t addr, uint64_t length, uint64_t registration_id,
+    HighPerformanceTcpOpcode opcode, bool remote, Lease* lease,
+    HighPerformanceTcpStatus* failure) {
+    if (failure != nullptr) *failure = HighPerformanceTcpStatus::kOk;
+    if (lease == nullptr) {
+        return Status::InvalidArgument("HP TCP lease output is null" LOC_MARK);
+    }
+    lease->reset();
+
+    uint64_t end = 0;
+    if (!RangeEnd(addr, length, &end)) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kRangeRejected;
+        return Status::InvalidArgument("invalid HP TCP lease range" LOC_MARK);
+    }
+
+    std::lock_guard<std::mutex> registry_lock(registry_mutex_);
+    if (closing_) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kShuttingDown;
+        return LeaseError(HighPerformanceTcpStatus::kShuttingDown,
+                          "HP TCP buffer registry is shutting down");
+    }
+    const auto next = entries_.upper_bound(addr);
+    if (next == entries_.begin()) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kRangeRejected;
+        return LeaseError(HighPerformanceTcpStatus::kRangeRejected,
+                          "HP TCP range not registered");
+    }
+    const auto entry = std::prev(next)->second;
+    uint64_t entry_end = 0;
+    if (!RangeEnd(entry->base, entry->length, &entry_end) ||
+        addr < entry->base || end > entry_end) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kRangeRejected;
+        return LeaseError(HighPerformanceTcpStatus::kRangeRejected,
+                          "HP TCP range not registered");
+    }
+
+    std::lock_guard<std::mutex> entry_lock(entry->mutex);
+    if (remote && entry->registration_id != registration_id) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kStaleRegistration;
+        return LeaseError(HighPerformanceTcpStatus::kStaleRegistration,
+                          "stale HP TCP registration");
+    }
+    if (remote && (entry->permission == kLocalReadWrite ||
+                   (opcode == HighPerformanceTcpOpcode::kWrite &&
+                    entry->permission != kGlobalReadWrite))) {
+        if (failure != nullptr)
+            *failure = HighPerformanceTcpStatus::kPermissionDenied;
+        return LeaseError(HighPerformanceTcpStatus::kPermissionDenied,
+                          "HP TCP permission denied");
+    }
+
+    ++entry->active_leases;
+    *lease = Lease(entry);
+    return Status::OK();
+}
+
+bool HighPerformanceTcpBufferRegistry::tracks(uint64_t base,
+                                              uint64_t length) const {
+    std::lock_guard<std::mutex> lock(registry_mutex_);
+    const auto it = entries_.find(base);
+    return it != entries_.end() && it->second->length == length;
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_client.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_client.cpp
new file mode 100644
index 0000000000..57b8311cbc
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_client.cpp
@@ -0,0 +1,673 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_client.h"
+
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <deque>
+#include <limits>
+#include <optional>
+#include <utility>
+
+#include <glog/logging.h>
+
+namespace mooncake::tent {
+class HighPerformanceTcpClient::Lane
+    : public std::enable_shared_from_this<HighPerformanceTcpClient::Lane> {
+   public:
+    Lane(HighPerformanceTcpClient* parent, asio::io_context& io, Config config,
+         LaneKey key)
+        : parent_(parent),
+          config_(std::move(config)),
+          key_(std::move(key)),
+          resolver_(io),
+          socket_(io),
+          timer_(io) {}
+
+    void enqueue(Operation operation) {
+        try {
+            queue_.push_back(std::move(operation));
+        } catch (const std::exception& error) {
+            LOG(ERROR) << "HP TCP lane enqueue failed: " << error.what();
+            completeStandalone(std::move(operation), FAILED, 0);
+            return;
+        } catch (...) {
+            LOG(ERROR) << "HP TCP lane enqueue failed";
+            completeStandalone(std::move(operation), FAILED, 0);
+            return;
+        }
+        if (!current_) startNext();
+    }
+
+    void cancelAll(TransferStatusEnum terminal) {
+        cancelTimer();
+        while (!queue_.empty()) {
+            Operation operation = std::move(queue_.front());
+            queue_.pop_front();
+            completeStandalone(std::move(operation), terminal, 0);
+        }
+        if (!current_) {
+            closeDirty();
+            return;
+        }
+        forced_terminal_ = terminal;
+        resolver_.cancel();
+        closeDirty();
+        // The outstanding async callback owns the final completion. Releasing
+        // the operation (and its memory lease in the adapter) here would be a
+        // use-after-free risk because Asio still owns the user buffer.
+    }
+
+    bool cancelRequest(uint64_t request_id) {
+        for (auto it = queue_.begin(); it != queue_.end(); ++it) {
+            if (it->request_id != request_id) continue;
+            Operation operation = std::move(*it);
+            queue_.erase(it);
+            completeStandalone(std::move(operation), CANCELED, 0);
+            return true;
+        }
+        if (!current_ || current_->request_id != request_id) return false;
+        forced_terminal_ = CANCELED;
+        cancelTimer();
+        resolver_.cancel();
+        closeDirty();
+        // The live Asio callback owns final completion and buffer retirement.
+        return true;
+    }
+
+   private:
+    template <typename Function>
+    void runHandler(uint64_t epoch, Function&& function) noexcept {
+        if (!matches(epoch)) return;
+        try {
+            function();
+        } catch (const std::exception& error) {
+            LOG(ERROR) << "HP TCP client handler failed: " << error.what();
+            if (matches(epoch)) {
+                finishCurrent(FAILED, 0, false);
+            }
+        } catch (...) {
+            LOG(ERROR) << "HP TCP client handler failed";
+            if (matches(epoch)) {
+                finishCurrent(FAILED, 0, false);
+            }
+        }
+    }
+
+    void startNext() {
+        if (current_ || queue_.empty()) return;
+        current_.emplace(std::move(queue_.front()));
+        queue_.pop_front();
+        ++operation_epoch_;
+        forced_terminal_.reset();
+        body_offset_ = 0;
+        remote_write_outcome_unknown_ = false;
+        request_bytes_ = EncodeHighPerformanceTcpRequest(
+            {current_->opcode, current_->request_id, current_->registration_id,
+             current_->remote_addr, current_->length});
+
+        try {
+            if (socket_.is_open()) {
+                writeHeader(operation_epoch_);
+            } else {
+                resolve(operation_epoch_);
+            }
+        } catch (const std::exception& error) {
+            LOG(ERROR) << "HP TCP async initiation failed: " << error.what();
+            finishCurrent(FAILED, 0, false);
+        } catch (...) {
+            LOG(ERROR) << "HP TCP async initiation failed";
+            finishCurrent(FAILED, 0, false);
+        }
+    }
+
+    void resolve(uint64_t epoch) {
+        armTimer(config_.connect_timeout_ms, epoch);
+        auto self = shared_from_this();
+        resolver_.async_resolve(
+            key_.host, std::to_string(key_.port),
+            [self, epoch](const std::error_code& error,
+                          asio::ip::tcp::resolver::results_type results) {
+                self->runHandler(epoch, [&] {
+                    if (self->finishForcedIfAny()) return;
+                    if (error) {
+                        if (error == asio::error::host_not_found)
+                            self->finishCurrent(
+                                FAILED, 0, false,
+                                HighPerformanceTcpStatus::kStaleRegistration);
+                        else
+                            self->finishIoError(error);
+                        return;
+                    }
+                    self->connect(epoch, std::move(results));
+                });
+            });
+    }
+
+    void connect(uint64_t epoch,
+                 asio::ip::tcp::resolver::results_type results) {
+        std::error_code ignored;
+        socket_.close(ignored);
+        if (!current_->local_host.empty()) {
+            if (results.empty()) {
+                finishCurrent(FAILED, 0, false,
+                              HighPerformanceTcpStatus::kStaleRegistration);
+                return;
+            }
+            std::error_code error;
+            socket_.open(results.begin()->endpoint().protocol(), error);
+            if (error) {
+                finishIoError(error);
+                return;
+            }
+            const auto source =
+                asio::ip::make_address(current_->local_host, error);
+            if (error) {
+                finishIoError(error);
+                return;
+            }
+            socket_.bind(asio::ip::tcp::endpoint(source, 0), error);
+            if (error) {
+                finishIoError(error);
+                return;
+            }
+        }
+        auto self = shared_from_this();
+        const auto connected = [self, epoch](const std::error_code& error) {
+            self->runHandler(epoch, [&] {
+                if (self->finishForcedIfAny()) return;
+                if (error) {
+                    if (error == asio::error::connection_refused)
+                        self->finishCurrent(
+                            FAILED, 0, false,
+                            HighPerformanceTcpStatus::kStaleRegistration);
+                    else
+                        self->finishIoError(error);
+                    return;
+                }
+                std::error_code option_error;
+                self->socket_.set_option(asio::ip::tcp::no_delay(true),
+                                         option_error);
+                if (option_error) {
+                    self->finishIoError(option_error);
+                    return;
+                }
+                self->cancelTimer();
+                self->parent_->connections_created_.fetch_add(
+                    1, std::memory_order_relaxed);
+                self->writeHeader(epoch);
+            });
+        };
+        if (!current_->local_host.empty()) {
+            // The endpoint-range overload closes and reopens the socket while
+            // trying endpoints, which discards the source bind above.
+            socket_.async_connect(results.begin()->endpoint(), connected);
+        } else {
+            asio::async_connect(socket_, results,
+                                [connected](const std::error_code& error,
+                                            const asio::ip::tcp::endpoint&) {
+                                    connected(error);
+                                });
+        }
+    }
+
+    void writeHeader(uint64_t epoch) {
+        armTimer(config_.progress_timeout_ms, epoch);
+        auto self = shared_from_this();
+        asio::async_write(
+            socket_, asio::buffer(request_bytes_),
+            [self, epoch](const std::error_code& error, size_t bytes) {
+                self->runHandler(epoch, [&] {
+                    if (self->current_->opcode ==
+                        HighPerformanceTcpOpcode::kWrite) {
+                        // Any reported header byte makes replay conservative:
+                        // the peer may subsequently observe a complete request.
+                        self->remote_write_outcome_unknown_ = bytes > 0;
+                    }
+                    if (self->finishForcedIfAny()) return;
+                    if (error || bytes != kHighPerformanceTcpRequestSize) {
+                        self->finishIoError(
+                            error ? error : asio::error::operation_aborted);
+                        return;
+                    }
+                    self->armTimer(self->config_.progress_timeout_ms, epoch);
+                    if (self->current_->opcode ==
+                        HighPerformanceTcpOpcode::kWrite) {
+                        self->body_offset_ = 0;
+                        self->writeBodyChunk(epoch);
+                    } else {
+                        self->readResponse(epoch);
+                    }
+                });
+            });
+    }
+
+    void writeBodyChunk(uint64_t epoch) {
+        if (body_offset_ == current_->length) {
+            readResponse(epoch);
+            return;
+        }
+        const size_t chunk = static_cast<size_t>(std::min<uint64_t>(
+            config_.chunk_size, current_->length - body_offset_));
+        auto* data = static_cast<uint8_t*>(current_->local_addr) + body_offset_;
+        auto self = shared_from_this();
+        asio::async_write(
+            socket_, asio::buffer(data, chunk),
+            [self, epoch, chunk](const std::error_code& error, size_t bytes) {
+                self->runHandler(epoch, [&] {
+                    if (self->finishForcedIfAny()) return;
+                    if (error || bytes != chunk) {
+                        self->finishIoError(
+                            error ? error : asio::error::operation_aborted);
+                        return;
+                    }
+                    self->body_offset_ += bytes;
+                    self->armTimer(self->config_.progress_timeout_ms, epoch);
+                    self->writeBodyChunk(epoch);
+                });
+            });
+    }
+
+    void readResponse(uint64_t epoch) {
+        auto self = shared_from_this();
+        asio::async_read(
+            socket_, asio::buffer(response_bytes_),
+            [self, epoch](const std::error_code& error, size_t bytes) {
+                self->runHandler(epoch, [&] {
+                    if (self->finishForcedIfAny()) return;
+                    if (error || bytes != kHighPerformanceTcpResponseSize) {
+                        self->finishIoError(
+                            error ? error : asio::error::operation_aborted);
+                        return;
+                    }
+                    self->armTimer(self->config_.progress_timeout_ms, epoch);
+                    HighPerformanceTcpResponseFrame response;
+                    const Status decoded = DecodeHighPerformanceTcpResponse(
+                        self->response_bytes_.data(),
+                        self->response_bytes_.size(), &response);
+                    if (!decoded.ok()) {
+                        self->finishProtocolError();
+                        return;
+                    }
+                    if (response.request_id != self->current_->request_id) {
+                        self->finishProtocolError();
+                        return;
+                    }
+                    if (response.status != HighPerformanceTcpStatus::kOk) {
+                        self->finishRemoteError(response.status);
+                        return;
+                    }
+                    if (response.committed_bytes != self->current_->length) {
+                        self->finishProtocolError();
+                        return;
+                    }
+                    if (self->current_->opcode ==
+                        HighPerformanceTcpOpcode::kWrite) {
+                        self->finishClean();
+                    } else {
+                        self->body_offset_ = 0;
+                        self->readBodyChunk(epoch);
+                    }
+                });
+            });
+    }
+
+    void readBodyChunk(uint64_t epoch) {
+        if (body_offset_ == current_->length) {
+            finishClean();
+            return;
+        }
+        const size_t chunk = static_cast<size_t>(std::min<uint64_t>(
+            config_.chunk_size, current_->length - body_offset_));
+        auto* data = static_cast<uint8_t*>(current_->local_addr) + body_offset_;
+        auto self = shared_from_this();
+        asio::async_read(
+            socket_, asio::buffer(data, chunk),
+            [chunk](const std::error_code& error, size_t received) -> size_t {
+                return error ? 0 : chunk - received;
+            },
+            [self, epoch, chunk](const std::error_code& error, size_t bytes) {
+                self->runHandler(epoch, [&] {
+                    if (self->finishForcedIfAny()) return;
+                    if (error || bytes != chunk) {
+                        self->finishIoError(
+                            error ? error : asio::error::operation_aborted);
+                        return;
+                    }
+                    self->body_offset_ += bytes;
+                    self->armTimer(self->config_.progress_timeout_ms, epoch);
+                    self->readBodyChunk(epoch);
+                });
+            });
+    }
+
+    void armTimer(uint64_t timeout_ms, uint64_t epoch) {
+        const uint64_t generation = ++timer_generation_;
+        timer_.expires_after(std::chrono::milliseconds(timeout_ms));
+        auto self = shared_from_this();
+        timer_.async_wait(
+            [self, epoch, generation](const std::error_code& error) {
+                if (error == asio::error::operation_aborted) return;
+                if (error || !self->matches(epoch) ||
+                    generation != self->timer_generation_) {
+                    return;
+                }
+                self->forced_terminal_ = TIMEOUT;
+                self->resolver_.cancel();
+                self->closeDirty();
+                // The active resolve/socket callback completes the operation.
+                // This makes timeout sticky without releasing the caller buffer
+                // before the canceled I/O handler has quiesced.
+            });
+    }
+
+    void cancelTimer() {
+        ++timer_generation_;
+        std::error_code ignored;
+        timer_.cancel(ignored);
+    }
+
+    void armIdleTimer() {
+        if (current_ || !queue_.empty() || !socket_.is_open()) return;
+        const uint64_t generation = ++timer_generation_;
+        timer_.expires_after(
+            std::chrono::milliseconds(config_.idle_connection_timeout_ms));
+        auto self = shared_from_this();
+        timer_.async_wait([self, generation](const std::error_code& error) {
+            if (error || generation != self->timer_generation_ ||
+                self->current_ || !self->queue_.empty()) {
+                return;
+            }
+            // Only the client knows that no request is in transit. Closing
+            // here releases receiver capacity without racing a reused WRITE
+            // against server-side eviction. The next operation reconnects.
+            self->closeDirty();
+        });
+    }
+
+    bool matches(uint64_t epoch) const {
+        return current_.has_value() && epoch == operation_epoch_;
+    }
+
+    bool finishForcedIfAny() {
+        if (!forced_terminal_.has_value()) return false;
+        const TransferStatusEnum terminal = *forced_terminal_;
+        finishCurrent(terminal, 0, false);
+        return true;
+    }
+
+    void closeDirty() {
+        std::error_code ignored;
+        if (socket_.is_open()) {
+            socket_.cancel(ignored);
+            socket_.shutdown(asio::ip::tcp::socket::shutdown_both, ignored);
+            socket_.close(ignored);
+        }
+    }
+
+    void finishProtocolError() { finishCurrent(FAILED, 0, false); }
+
+    void finishRemoteError(HighPerformanceTcpStatus status) {
+        finishCurrent(FAILED, 0, false, status);
+    }
+
+    void finishIoError(const std::error_code&) {
+        const TransferStatusEnum terminal = forced_terminal_.value_or(FAILED);
+        finishCurrent(terminal, 0, false);
+    }
+
+    void finishClean() {
+        cancelTimer();
+        remote_write_outcome_unknown_ = false;
+        finishCurrent(COMPLETED, current_->length, true);
+    }
+
+    void finishCurrent(
+        TransferStatusEnum terminal, size_t bytes, bool keep_stream,
+        std::optional<HighPerformanceTcpStatus> remote_status = std::nullopt) {
+        cancelTimer();
+        if (!keep_stream) closeDirty();
+        Operation operation = std::move(*current_);
+        if (terminal == FAILED && remote_write_outcome_unknown_ &&
+            !remote_status.has_value()) {
+            // A WRITE may have reached the peer without a valid ACK. Reuse the
+            // existing terminal protocol classification so it cannot be
+            // replayed through another transport.
+            remote_status = HighPerformanceTcpStatus::kInternalError;
+        }
+        current_.reset();
+        ++operation_epoch_;  // invalidate late timer/cancel callbacks
+        forced_terminal_.reset();
+        remote_write_outcome_unknown_ = false;
+        completeStandalone(std::move(operation), terminal, bytes,
+                           remote_status);
+        startNext();
+        armIdleTimer();
+    }
+
+    void completeStandalone(
+        Operation operation, TransferStatusEnum terminal, size_t bytes,
+        std::optional<HighPerformanceTcpStatus> remote_status = std::nullopt) {
+        try {
+            if (operation.complete)
+                operation.complete(terminal, bytes, remote_status);
+        } catch (const std::exception& error) {
+            LOG(ERROR) << "HP TCP completion callback threw: " << error.what();
+        } catch (...) {
+            LOG(ERROR) << "HP TCP completion callback threw";
+        }
+        parent_->operationFinished();
+    }
+
+    HighPerformanceTcpClient* parent_;
+    Config config_;
+    LaneKey key_;
+    asio::ip::tcp::resolver resolver_;
+    asio::ip::tcp::socket socket_;
+    asio::steady_timer timer_;
+    std::deque<Operation> queue_;
+    std::optional<Operation> current_;
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> request_bytes_{};
+    std::array<uint8_t, kHighPerformanceTcpResponseSize> response_bytes_{};
+    uint64_t operation_epoch_{0};
+    uint64_t timer_generation_{0};
+    uint64_t body_offset_{0};
+    bool remote_write_outcome_unknown_{false};
+    std::optional<TransferStatusEnum> forced_terminal_;
+};
+
+bool HighPerformanceTcpClient::LaneKey::operator==(const LaneKey& other) const {
+    return peer_id == other.peer_id && incarnation == other.incarnation &&
+           host == other.host && port == other.port && lane_id == other.lane_id;
+}
+
+size_t HighPerformanceTcpClient::LaneKeyHash::operator()(
+    const LaneKey& key) const {
+    size_t hash = std::hash<uint64_t>{}(key.peer_id);
+    const auto mix = [&hash](size_t value) {
+        hash ^= value + static_cast<size_t>(0x9e3779b97f4a7c15ULL) +
+                (hash << 6U) + (hash >> 2U);
+    };
+    mix(std::hash<std::string>{}(key.incarnation));
+    mix(std::hash<std::string>{}(key.host));
+    mix(std::hash<uint16_t>{}(key.port));
+    mix(std::hash<uint32_t>{}(key.lane_id));
+    return hash;
+}
+
+HighPerformanceTcpClient::HighPerformanceTcpClient(
+    Config config, HighPerformanceTcpWorkers* workers)
+    : config_(std::move(config)), workers_(workers) {
+    if (workers_ != nullptr) worker_states_.resize(workers_->workerCount());
+}
+
+HighPerformanceTcpClient::~HighPerformanceTcpClient() {
+    if (workers_ != nullptr && workers_->controlContextAvailable() &&
+        !workers_->onWorkerThread()) {
+        (void)cancelAll(CANCELED);
+    }
+    DCHECK(workers_ == nullptr ||
+           active_operations_.load(std::memory_order_acquire) == 0)
+        << "HP TCP client destroyed with active operations";
+}
+
+void HighPerformanceTcpClient::operationStarted() {
+    active_operations_.fetch_add(1, std::memory_order_acq_rel);
+}
+
+void HighPerformanceTcpClient::operationFinished() {
+    const uint64_t previous =
+        active_operations_.fetch_sub(1, std::memory_order_acq_rel);
+    if (previous == 1) {
+        std::lock_guard<std::mutex> lock(active_mutex_);
+        active_cv_.notify_all();
+    }
+}
+
+void HighPerformanceTcpClient::enqueueOnOwner(size_t owner_worker,
+                                              Operation operation) {
+    if (workers_ == nullptr || owner_worker >= worker_states_.size() ||
+        !operation.complete) {
+        if (operation.complete) {
+            try {
+                operation.complete(FAILED, 0, std::nullopt);
+            } catch (...) {
+                LOG(ERROR) << "HP TCP rejected-operation callback threw";
+            }
+        }
+        return;
+    }
+
+    operationStarted();
+    try {
+        if (stopping_.load(std::memory_order_acquire) ||
+            operation.local_addr == nullptr || operation.length == 0 ||
+            operation.length > config_.max_transfer_bytes ||
+            operation.host.empty() || operation.port == 0 ||
+            operation.lane_id >= config_.connections_per_peer) {
+            try {
+                operation.complete(CANCELED, 0, std::nullopt);
+            } catch (...) {
+                LOG(ERROR) << "HP TCP rejected-operation callback threw";
+            }
+            operationFinished();
+            return;
+        }
+
+        auto& lanes = worker_states_[owner_worker].lanes;
+        for (auto it = lanes.begin(); it != lanes.end();) {
+            if (it->first.peer_id == operation.peer_id &&
+                it->first.incarnation != operation.incarnation) {
+                it->second->cancelAll(CANCELED);
+                it = lanes.erase(it);
+            } else {
+                ++it;
+            }
+        }
+
+        LaneKey key{operation.peer_id, operation.incarnation, operation.host,
+                    operation.port, operation.lane_id};
+        auto it = lanes.find(key);
+        if (it == lanes.end()) {
+            auto lane = std::make_shared<Lane>(
+                this, workers_->ioContext(owner_worker), config_, key);
+            it = lanes.emplace(std::move(key), std::move(lane)).first;
+        }
+        // Lane::enqueue owns completion + active-operation retirement from
+        // this point forward, including allocation/initiation failures.
+        it->second->enqueue(std::move(operation));
+    } catch (const std::exception& error) {
+        LOG(ERROR) << "HP TCP lane setup failed: " << error.what();
+        try {
+            operation.complete(FAILED, 0, std::nullopt);
+        } catch (...) {
+            LOG(ERROR) << "HP TCP failed-operation callback threw";
+        }
+        operationFinished();
+    } catch (...) {
+        LOG(ERROR) << "HP TCP lane setup failed";
+        try {
+            operation.complete(FAILED, 0, std::nullopt);
+        } catch (...) {
+            LOG(ERROR) << "HP TCP failed-operation callback threw";
+        }
+        operationFinished();
+    }
+}
+
+void HighPerformanceTcpClient::cancelWorker(size_t worker_id,
+                                            TransferStatusEnum terminal) {
+    if (worker_id >= worker_states_.size()) return;
+    auto& lanes = worker_states_[worker_id].lanes;
+    for (auto& [key, lane] : lanes) {
+        (void)key;
+        lane->cancelAll(terminal);
+    }
+    lanes.clear();
+}
+
+void HighPerformanceTcpClient::cancelRequestOnWorker(size_t worker_id,
+                                                     uint64_t request_id) {
+    if (worker_id >= worker_states_.size()) return;
+    for (auto& [key, lane] : worker_states_[worker_id].lanes) {
+        (void)key;
+        (void)lane->cancelRequest(request_id);
+    }
+}
+
+Status HighPerformanceTcpClient::cancelRequest(uint64_t request_id) {
+    if (workers_ == nullptr || request_id == 0) {
+        return Status::InvalidArgument(
+            "invalid HP TCP cancellation request" LOC_MARK);
+    }
+    if (!workers_->controlContextAvailable()) {
+        return Status::InternalError(
+            "HP TCP worker contexts are unavailable" LOC_MARK);
+    }
+    try {
+        for (size_t worker_id = 0; worker_id < worker_states_.size();
+             ++worker_id) {
+            asio::post(workers_->ioContext(worker_id),
+                       [this, worker_id, request_id] {
+                           cancelRequestOnWorker(worker_id, request_id);
+                       });
+        }
+    } catch (const std::exception& error) {
+        return Status::InternalError(
+            std::string("HP TCP cancellation post failed: ") + error.what() +
+            LOC_MARK);
+    }
+    return Status::OK();
+}
+
+Status HighPerformanceTcpClient::cancelAll(TransferStatusEnum terminal) {
+    if (workers_ == nullptr) return Status::OK();
+    if (workers_->onWorkerThread()) {
+        return Status::InvalidArgument(
+            "HP TCP client cancelAll cannot block a worker" LOC_MARK);
+    }
+    stopping_.store(true, std::memory_order_release);
+
+    if (workers_->controlContextAvailable()) {
+        try {
+            // Post cancellation to every owner before waiting for active I/O.
+            for (size_t i = 0; i < workers_->workerCount(); ++i) {
+                asio::post(workers_->ioContext(i),
+                           [this, i, terminal] { cancelWorker(i, terminal); });
+            }
+        } catch (const std::exception& error) {
+            return Status::InternalError(
+                std::string("HP TCP client cancellation post failed: ") +
+                error.what() + LOC_MARK);
+        }
+        CHECK_STATUS(workers_->barrier());
+    }
+
+    std::unique_lock<std::mutex> lock(active_mutex_);
+    active_cv_.wait(lock, [&] {
+        return active_operations_.load(std::memory_order_acquire) == 0;
+    });
+    return Status::OK();
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_protocol.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_protocol.cpp
new file mode 100644
index 0000000000..c7e488c4e1
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_protocol.cpp
@@ -0,0 +1,305 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+
+#include <algorithm>
+#include <cctype>
+#include <limits>
+#include <string>
+
+#include "tent/thirdparty/nlohmann/json.h"
+
+namespace mooncake::tent {
+namespace {
+
+using json = nlohmann::json;
+
+void Put16(uint8_t* out, uint16_t value) {
+    out[0] = static_cast<uint8_t>(value >> 8U);
+    out[1] = static_cast<uint8_t>(value);
+}
+
+void Put32(uint8_t* out, uint32_t value) {
+    for (size_t i = 0; i < 4; ++i) {
+        out[i] = static_cast<uint8_t>(value >> ((3U - i) * 8U));
+    }
+}
+
+void Put64(uint8_t* out, uint64_t value) {
+    for (size_t i = 0; i < 8; ++i) {
+        out[i] = static_cast<uint8_t>(value >> ((7U - i) * 8U));
+    }
+}
+
+uint16_t Get16(const uint8_t* in) {
+    return static_cast<uint16_t>((static_cast<uint16_t>(in[0]) << 8U) |
+                                 static_cast<uint16_t>(in[1]));
+}
+
+uint32_t Get32(const uint8_t* in) {
+    uint32_t value = 0;
+    for (size_t i = 0; i < 4; ++i) {
+        value = (value << 8U) | in[i];
+    }
+    return value;
+}
+
+uint64_t Get64(const uint8_t* in) {
+    uint64_t value = 0;
+    for (size_t i = 0; i < 8; ++i) {
+        value = (value << 8U) | in[i];
+    }
+    return value;
+}
+
+Status InvalidFrame(const std::string& detail, HighPerformanceTcpStatus error,
+                    HighPerformanceTcpStatus* wire_error) {
+    if (wire_error != nullptr) *wire_error = error;
+    return Status::InvalidArgument(
+        "Invalid high-performance TCP frame: " + detail + LOC_MARK);
+}
+
+bool IsHex128(const std::string& value) {
+    return value.size() == 32 &&
+           std::all_of(value.begin(), value.end(),
+                       [](unsigned char ch) { return std::isxdigit(ch) != 0; });
+}
+
+Status InvalidAttr(const std::string& detail) {
+    return Status::InvalidArgument("Invalid HP TCP attribute: " + detail +
+                                   LOC_MARK);
+}
+
+bool ReadPositiveUint64(const json& object, const char* key, uint64_t* out) {
+    auto it = object.find(key);
+    if (it == object.end()) return false;
+    if (it->is_number_unsigned()) {
+        const auto value = it->get<uint64_t>();
+        if (value == 0) return false;
+        *out = value;
+        return true;
+    }
+    if (!it->is_number_integer()) return false;
+    const auto value = it->get<int64_t>();
+    if (value <= 0) return false;
+    *out = static_cast<uint64_t>(value);
+    return true;
+}
+
+}  // namespace
+
+std::array<uint8_t, kHighPerformanceTcpRequestSize>
+EncodeHighPerformanceTcpRequest(const HighPerformanceTcpRequestFrame& frame) {
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> bytes{};
+    Put32(bytes.data(), kHighPerformanceTcpMagic);
+    Put16(bytes.data() + 4, kHighPerformanceTcpVersion);
+    bytes[6] = static_cast<uint8_t>(frame.opcode);
+    bytes[7] = 0;  // flags, reserved in v1
+    Put64(bytes.data() + 8, frame.request_id);
+    Put64(bytes.data() + 16, frame.registration_id);
+    Put64(bytes.data() + 24, frame.remote_addr);
+    Put64(bytes.data() + 32, frame.length);
+    Put64(bytes.data() + 40, 0);  // reserved
+    return bytes;
+}
+
+Status DecodeHighPerformanceTcpRequest(const uint8_t* bytes, size_t size,
+                                       HighPerformanceTcpRequestFrame* frame,
+                                       HighPerformanceTcpStatus* wire_error) {
+    if (wire_error != nullptr) {
+        *wire_error = HighPerformanceTcpStatus::kInternalError;
+    }
+    if (bytes == nullptr || frame == nullptr ||
+        size != kHighPerformanceTcpRequestSize) {
+        return InvalidFrame("request size",
+                            HighPerformanceTcpStatus::kInternalError,
+                            wire_error);
+    }
+    if (Get32(bytes) != kHighPerformanceTcpMagic) {
+        return InvalidFrame("magic", HighPerformanceTcpStatus::kInternalError,
+                            wire_error);
+    }
+    if (Get16(bytes + 4) != kHighPerformanceTcpVersion) {
+        return InvalidFrame("version", HighPerformanceTcpStatus::kBadVersion,
+                            wire_error);
+    }
+    if (bytes[7] != 0 || Get64(bytes + 40) != 0) {
+        return InvalidFrame("flags/reserved",
+                            HighPerformanceTcpStatus::kInternalError,
+                            wire_error);
+    }
+    if (bytes[6] != static_cast<uint8_t>(HighPerformanceTcpOpcode::kRead) &&
+        bytes[6] != static_cast<uint8_t>(HighPerformanceTcpOpcode::kWrite)) {
+        return InvalidFrame("opcode", HighPerformanceTcpStatus::kBadOpcode,
+                            wire_error);
+    }
+
+    const uint64_t remote_addr = Get64(bytes + 24);
+    const uint64_t length = Get64(bytes + 32);
+    if (length == 0 ||
+        remote_addr > std::numeric_limits<uint64_t>::max() - length) {
+        return InvalidFrame("length/range",
+                            HighPerformanceTcpStatus::kBadLength, wire_error);
+    }
+
+    frame->opcode = static_cast<HighPerformanceTcpOpcode>(bytes[6]);
+    frame->request_id = Get64(bytes + 8);
+    frame->registration_id = Get64(bytes + 16);
+    frame->remote_addr = remote_addr;
+    frame->length = length;
+    return Status::OK();
+}
+
+std::array<uint8_t, kHighPerformanceTcpResponseSize>
+EncodeHighPerformanceTcpResponse(const HighPerformanceTcpResponseFrame& frame) {
+    std::array<uint8_t, kHighPerformanceTcpResponseSize> bytes{};
+    Put32(bytes.data(), kHighPerformanceTcpMagic);
+    Put16(bytes.data() + 4, kHighPerformanceTcpVersion);
+    Put16(bytes.data() + 6, static_cast<uint16_t>(frame.status));
+    Put64(bytes.data() + 8, frame.request_id);
+    Put64(bytes.data() + 16, frame.committed_bytes);
+    Put64(bytes.data() + 24, 0);
+    return bytes;
+}
+
+Status DecodeHighPerformanceTcpResponse(
+    const uint8_t* bytes, size_t size, HighPerformanceTcpResponseFrame* frame) {
+    if (bytes == nullptr || frame == nullptr ||
+        size != kHighPerformanceTcpResponseSize) {
+        return Status::InvalidArgument(
+            "Invalid high-performance TCP response size" LOC_MARK);
+    }
+    if (Get32(bytes) != kHighPerformanceTcpMagic ||
+        Get16(bytes + 4) != kHighPerformanceTcpVersion ||
+        Get64(bytes + 24) != 0) {
+        return Status::InvalidArgument(
+            "Invalid high-performance TCP response header" LOC_MARK);
+    }
+    const uint16_t status = Get16(bytes + 6);
+    if (status >
+        static_cast<uint16_t>(HighPerformanceTcpStatus::kInternalError)) {
+        return Status::InvalidArgument(
+            "Invalid high-performance TCP response status" LOC_MARK);
+    }
+    frame->status = static_cast<HighPerformanceTcpStatus>(status);
+    frame->request_id = Get64(bytes + 8);
+    frame->committed_bytes = Get64(bytes + 16);
+    return Status::OK();
+}
+
+const char* HighPerformanceTcpPermissionName(Permission permission) {
+    switch (permission) {
+        case kLocalReadWrite:
+            return "local_read_write";
+        case kGlobalReadOnly:
+            return "global_read_only";
+        case kGlobalReadWrite:
+            return "global_read_write";
+    }
+    return "unknown";
+}
+
+Status EncodeHighPerformanceTcpEndpointAttr(
+    const HighPerformanceTcpEndpointAttr& attr, std::string* encoded) {
+    if (encoded == nullptr || !IsHex128(attr.incarnation) ||
+        attr.endpoints.empty() || attr.max_transfer_bytes == 0) {
+        return InvalidAttr("endpoint");
+    }
+
+    json endpoints = json::array();
+    for (const auto& endpoint : attr.endpoints) {
+        if (endpoint.host.empty() || endpoint.port == 0) {
+            return InvalidAttr("endpoint");
+        }
+        endpoints.push_back({{"host", endpoint.host}, {"port", endpoint.port}});
+    }
+    *encoded = json{{"protocol", "tent_hp_tcp"},
+                    {"version", kHighPerformanceTcpVersion},
+                    {"incarnation", attr.incarnation},
+                    {"endpoints", std::move(endpoints)},
+                    {"max_transfer_bytes", attr.max_transfer_bytes}}
+                   .dump();
+    return Status::OK();
+}
+
+Status DecodeHighPerformanceTcpEndpointAttr(
+    const std::string& encoded, HighPerformanceTcpEndpointAttr* attr) {
+    if (attr == nullptr) return InvalidAttr("null endpoint output");
+    try {
+        const json object = json::parse(encoded);
+        if (!object.is_object() ||
+            object.value("protocol", "") != "tent_hp_tcp" ||
+            object.value("version", 0) != kHighPerformanceTcpVersion) {
+            return InvalidAttr("endpoint protocol/version");
+        }
+        const std::string incarnation = object.value("incarnation", "");
+        const auto endpoints = object.find("endpoints");
+        if (!IsHex128(incarnation) || endpoints == object.end() ||
+            !endpoints->is_array() || endpoints->empty())
+            return InvalidAttr("endpoint identity/list");
+
+        std::vector<HighPerformanceTcpEndpoint> decoded_endpoints;
+        decoded_endpoints.reserve(endpoints->size());
+        for (const auto& endpoint : *endpoints) {
+            if (!endpoint.is_object()) return InvalidAttr("endpoint address");
+            const std::string host = endpoint.value("host", "");
+            uint64_t port = 0;
+            if (host.empty() || !ReadPositiveUint64(endpoint, "port", &port) ||
+                port > 65535) {
+                return InvalidAttr("endpoint address");
+            }
+            decoded_endpoints.push_back({host, static_cast<uint16_t>(port)});
+        }
+
+        uint64_t max_transfer_bytes = 0;
+        if (!ReadPositiveUint64(object, "max_transfer_bytes",
+                                &max_transfer_bytes))
+            return InvalidAttr("endpoint address/limit");
+        *attr = {incarnation, std::move(decoded_endpoints), max_transfer_bytes};
+        return Status::OK();
+    } catch (const std::exception& error) {
+        return Status::MalformedJson(
+            std::string("Invalid HP TCP endpoint attribute: ") + error.what() +
+            LOC_MARK);
+    }
+}
+
+Status EncodeHighPerformanceTcpBufferAttr(
+    const HighPerformanceTcpBufferAttr& attr, std::string* encoded) {
+    if (encoded == nullptr || attr.registration_id == 0 ||
+        (attr.permission != "global_read_only" &&
+         attr.permission != "global_read_write")) {
+        return InvalidAttr("buffer");
+    }
+    *encoded = json{{"protocol", "tent_hp_tcp"},
+                    {"version", kHighPerformanceTcpVersion},
+                    {"registration_id", attr.registration_id},
+                    {"permission", attr.permission}}
+                   .dump();
+    return Status::OK();
+}
+
+Status DecodeHighPerformanceTcpBufferAttr(const std::string& encoded,
+                                          HighPerformanceTcpBufferAttr* attr) {
+    if (attr == nullptr) return InvalidAttr("null buffer output");
+    try {
+        const json object = json::parse(encoded);
+        if (!object.is_object() ||
+            object.value("protocol", "") != "tent_hp_tcp" ||
+            object.value("version", 0) != kHighPerformanceTcpVersion)
+            return InvalidAttr("buffer protocol/version");
+        uint64_t registration = 0;
+        const std::string permission = object.value("permission", "");
+        if (!ReadPositiveUint64(object, "registration_id", &registration) ||
+            (permission != "global_read_only" &&
+             permission != "global_read_write"))
+            return InvalidAttr("buffer registration/permission");
+        *attr = {registration, permission};
+        return Status::OK();
+    } catch (const std::exception& error) {
+        return Status::MalformedJson(
+            std::string("Invalid HP TCP buffer attribute: ") + error.what() +
+            LOC_MARK);
+    }
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_server.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_server.cpp
new file mode 100644
index 0000000000..c3fb5ffafb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_server.cpp
@@ -0,0 +1,630 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_server.h"
+
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <functional>
+#include <future>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+
+namespace mooncake::tent {
+
+class HighPerformanceTcpServer::Session
+    : public std::enable_shared_from_this<HighPerformanceTcpServer::Session> {
+   public:
+    Session(HighPerformanceTcpServer* parent, size_t worker_id,
+            std::shared_ptr<asio::ip::tcp::socket> socket, Config config,
+            HighPerformanceTcpBufferRegistry* registry)
+        : parent_(parent),
+          worker_id_(worker_id),
+          socket_(std::move(socket)),
+          config_(std::move(config)),
+          registry_(registry),
+          timer_(socket_->get_executor()) {}
+
+    void start() { readHeader(); }
+
+    void cancel() {
+        forced_close_ = true;
+        cancelTimer();
+        std::error_code ignored;
+        socket_->cancel(ignored);
+        socket_->shutdown(asio::ip::tcp::socket::shutdown_both, ignored);
+        socket_->close(ignored);
+        // Every live session always has exactly one async socket operation
+        // outstanding. Its callback performs the final lease release and
+        // registry removal, so cancel() never publishes closure early.
+    }
+
+   private:
+    template <typename Function>
+    void runHandler(Function&& function) noexcept {
+        try {
+            function();
+        } catch (const std::exception& error) {
+            LOG(ERROR) << "HP TCP server handler failed: " << error.what();
+            finishClosed();
+        } catch (...) {
+            LOG(ERROR) << "HP TCP server handler failed";
+            finishClosed();
+        }
+    }
+
+    void readHeader() {
+        if (forced_close_) {
+            finishClosed();
+            return;
+        }
+        lease_.reset();
+        body_offset_ = 0;
+        header_offset_ = 0;
+        ++request_epoch_;
+        cancelTimer();
+        // A newly accepted peer must send its first byte within the progress
+        // deadline so an empty connection cannot hold a bounded session slot.
+        // Once a request has completed, waiting for the next request is
+        // connection-pool idle time rather than stalled I/O.
+        if (request_epoch_ == 1) armProgressTimer(request_epoch_);
+        readHeaderChunk();
+    }
+
+    void readHeaderChunk() {
+        auto self = shared_from_this();
+        socket_->async_read_some(
+            asio::buffer(request_bytes_.data() + header_offset_,
+                         request_bytes_.size() - header_offset_),
+            [self](const std::error_code& error, size_t bytes) {
+                self->runHandler([&] {
+                    if (self->forced_close_) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (error || bytes == 0) {
+                        self->finishClosed();
+                        return;
+                    }
+                    self->header_offset_ += bytes;
+                    // A reused stream may remain idle indefinitely. Once any
+                    // byte of its next frame arrives, each partial read must
+                    // make progress before the deadline.
+                    if (self->header_offset_ == self->request_bytes_.size()) {
+                        self->handleHeader();
+                    } else {
+                        self->armProgressTimer(self->request_epoch_);
+                        self->readHeaderChunk();
+                    }
+                });
+            });
+    }
+
+    void handleHeader() {
+        HighPerformanceTcpStatus wire_error =
+            HighPerformanceTcpStatus::kInternalError;
+        const Status decoded = DecodeHighPerformanceTcpRequest(
+            request_bytes_.data(), request_bytes_.size(), &request_,
+            &wire_error);
+        if (!decoded.ok()) {
+            request_.request_id = 0;
+            sendResponse(wire_error, 0, true);
+            return;
+        }
+        if (request_.length > config_.max_transfer_bytes) {
+            sendResponse(HighPerformanceTcpStatus::kBadLength, 0, true);
+            return;
+        }
+
+        HighPerformanceTcpStatus wire_status =
+            HighPerformanceTcpStatus::kInternalError;
+        const Status lease_status = registry_->acquireRemoteLease(
+            request_.remote_addr, request_.length, request_.registration_id,
+            request_.opcode, &lease_, &wire_status);
+        if (!lease_status.ok()) {
+            if (request_.opcode == HighPerformanceTcpOpcode::kWrite) {
+                // The client sends the complete WRITE body before reading the
+                // response. Consume exactly this rejected frame under the
+                // normal progress deadline, then reply and close the stream.
+                body_offset_ = 0;
+                discardRejectedWriteBody(wire_status);
+            } else {
+                sendResponse(wire_status, 0, true);
+            }
+            return;
+        }
+
+        armProgressTimer(request_epoch_);
+        if (request_.opcode == HighPerformanceTcpOpcode::kRead) {
+            // The response says the entire requested range is valid. The
+            // client still completes only after all payload bytes arrive.
+            sendResponse(HighPerformanceTcpStatus::kOk, request_.length, false,
+                         [self = shared_from_this()] {
+                             self->body_offset_ = 0;
+                             self->writeReadBodyChunk();
+                         });
+        } else {
+            body_offset_ = 0;
+            readWriteBodyChunk();
+        }
+    }
+
+    void discardRejectedWriteBody(HighPerformanceTcpStatus status) {
+        if (body_offset_ == request_.length) {
+            sendResponse(status, 0, true);
+            return;
+        }
+        const size_t chunk = static_cast<size_t>(std::min<uint64_t>(
+            discard_bytes_.size(), request_.length - body_offset_));
+        armProgressTimer(request_epoch_);
+        auto self = shared_from_this();
+        asio::async_read(
+            *socket_, asio::buffer(discard_bytes_.data(), chunk),
+            [self, status, chunk](const std::error_code& error, size_t bytes) {
+                self->runHandler([&] {
+                    if (self->forced_close_) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (error || bytes != chunk) {
+                        self->finishClosed();
+                        return;
+                    }
+                    self->body_offset_ += bytes;
+                    self->discardRejectedWriteBody(status);
+                });
+            });
+    }
+
+    uint8_t* remoteDataAt(uint64_t offset) {
+        return static_cast<uint8_t*>(lease_.data()) +
+               (request_.remote_addr - lease_.base()) + offset;
+    }
+
+    void writeReadBodyChunk() {
+        if (body_offset_ == request_.length) {
+            lease_.reset();
+            readHeader();
+            return;
+        }
+        const size_t chunk = static_cast<size_t>(std::min<uint64_t>(
+            config_.chunk_size, request_.length - body_offset_));
+        auto self = shared_from_this();
+        asio::async_write(
+            *socket_, asio::buffer(remoteDataAt(body_offset_), chunk),
+            [self, chunk](const std::error_code& error, size_t bytes) {
+                self->runHandler([&] {
+                    if (self->forced_close_) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (error || bytes != chunk) {
+                        self->finishClosed();
+                        return;
+                    }
+                    self->body_offset_ += bytes;
+                    self->armProgressTimer(self->request_epoch_);
+                    self->writeReadBodyChunk();
+                });
+            });
+    }
+
+    void readWriteBodyChunk() {
+        if (body_offset_ == request_.length) {
+            // The final async_read callback has returned: every byte is now in
+            // destination DRAM and no socket callback can touch the range.
+            lease_.reset();
+            armProgressTimer(request_epoch_);
+            sendResponse(HighPerformanceTcpStatus::kOk, request_.length, false,
+                         [self = shared_from_this()] { self->readHeader(); });
+            return;
+        }
+        const size_t chunk = static_cast<size_t>(std::min<uint64_t>(
+            config_.chunk_size, request_.length - body_offset_));
+        auto self = shared_from_this();
+        asio::async_read(
+            *socket_, asio::buffer(remoteDataAt(body_offset_), chunk),
+            [self, chunk](const std::error_code& error, size_t bytes) {
+                self->runHandler([&] {
+                    if (self->forced_close_) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (error || bytes != chunk) {
+                        self->finishClosed();
+                        return;
+                    }
+                    self->body_offset_ += bytes;
+                    self->armProgressTimer(self->request_epoch_);
+                    self->readWriteBodyChunk();
+                });
+            });
+    }
+
+    void sendResponse(HighPerformanceTcpStatus status, uint64_t committed,
+                      bool close_after,
+                      std::function<void()> continuation = {}) {
+        response_bytes_ = EncodeHighPerformanceTcpResponse(
+            {status, request_.request_id, committed});
+        // Error responses are I/O too: arm a deadline even when request
+        // validation failed before a lease was acquired.
+        armProgressTimer(request_epoch_);
+        auto self = shared_from_this();
+        asio::async_write(
+            *socket_, asio::buffer(response_bytes_),
+            [self, close_after, continuation = std::move(continuation)](
+                const std::error_code& error, size_t bytes) mutable {
+                self->runHandler([&] {
+                    if (self->forced_close_) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (error || bytes != kHighPerformanceTcpResponseSize) {
+                        self->finishClosed();
+                        return;
+                    }
+                    if (close_after) {
+                        self->finishClosed();
+                        return;
+                    }
+                    self->armProgressTimer(self->request_epoch_);
+                    if (continuation) {
+                        continuation();
+                    } else {
+                        self->readHeader();
+                    }
+                });
+            });
+    }
+
+    void armProgressTimer(uint64_t epoch) {
+        const uint64_t generation = ++timer_generation_;
+        timer_.expires_after(
+            std::chrono::milliseconds(config_.progress_timeout_ms));
+        auto self = shared_from_this();
+        timer_.async_wait(
+            [self, epoch, generation](const std::error_code& error) {
+                if (error == asio::error::operation_aborted) return;
+                if (error || epoch != self->request_epoch_ ||
+                    generation != self->timer_generation_) {
+                    return;
+                }
+                self->forced_close_ = true;
+                std::error_code ignored;
+                self->socket_->cancel(ignored);
+                self->socket_->shutdown(asio::ip::tcp::socket::shutdown_both,
+                                        ignored);
+                self->socket_->close(ignored);
+                // Finalization waits for the canceled body/response callback.
+            });
+    }
+
+    void cancelTimer() {
+        ++timer_generation_;
+        std::error_code ignored;
+        timer_.cancel(ignored);
+    }
+
+    void finishClosed() {
+        if (closed_) return;
+        closed_ = true;
+        cancelTimer();
+        std::error_code ignored;
+        socket_->cancel(ignored);
+        socket_->shutdown(asio::ip::tcp::socket::shutdown_both, ignored);
+        socket_->close(ignored);
+        lease_.reset();
+        parent_->onSessionClosed(worker_id_, shared_from_this());
+    }
+
+    HighPerformanceTcpServer* parent_;
+    size_t worker_id_;
+    std::shared_ptr<asio::ip::tcp::socket> socket_;
+    Config config_;
+    HighPerformanceTcpBufferRegistry* registry_;
+    asio::steady_timer timer_;
+
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> request_bytes_{};
+    std::array<uint8_t, kHighPerformanceTcpResponseSize> response_bytes_{};
+    std::array<uint8_t, 4096> discard_bytes_{};
+    HighPerformanceTcpRequestFrame request_;
+    HighPerformanceTcpBufferRegistry::Lease lease_;
+    size_t header_offset_{0};
+    uint64_t body_offset_{0};
+    uint64_t request_epoch_{0};
+    uint64_t timer_generation_{0};
+    bool forced_close_{false};
+    bool closed_{false};
+};
+
+HighPerformanceTcpServer::HighPerformanceTcpServer(
+    Config config, HighPerformanceTcpBufferRegistry* registry,
+    HighPerformanceTcpWorkers* workers)
+    : config_(std::move(config)), registry_(registry), workers_(workers) {
+    if (workers_ != nullptr) sessions_.resize(workers_->workerCount());
+}
+
+HighPerformanceTcpServer::~HighPerformanceTcpServer() {
+    (void)stop();
+    DCHECK(workers_ == nullptr ||
+           active_sessions_.load(std::memory_order_acquire) == 0)
+        << "HP TCP server destroyed with active sessions";
+}
+
+bool HighPerformanceTcpServer::reserveConnection() {
+    size_t current = active_sessions_.load(std::memory_order_acquire);
+    while (current < config_.max_connections) {
+        if (active_sessions_.compare_exchange_weak(current, current + 1,
+                                                   std::memory_order_acq_rel,
+                                                   std::memory_order_acquire)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+Status HighPerformanceTcpServer::start(uint16_t* bound_port) {
+    if (bound_port == nullptr || registry_ == nullptr || workers_ == nullptr ||
+        workers_->workerCount() == 0 || config_.chunk_size == 0 ||
+        config_.max_transfer_bytes == 0 || config_.progress_timeout_ms == 0 ||
+        config_.max_connections == 0) {
+        return Status::InvalidArgument(
+            "invalid HP TCP server configuration" LOC_MARK);
+    }
+    if (started_.exchange(true, std::memory_order_acq_rel)) {
+        return Status::InvalidArgument(
+            "HP TCP server already started" LOC_MARK);
+    }
+
+    try {
+        asio::ip::tcp::endpoint endpoint;
+        if (config_.bind_address.empty()) {
+            endpoint =
+                asio::ip::tcp::endpoint(asio::ip::tcp::v4(), config_.port);
+        } else {
+            endpoint = asio::ip::tcp::endpoint(
+                asio::ip::make_address(config_.bind_address), config_.port);
+        }
+        acceptor_ = std::make_unique<asio::ip::tcp::acceptor>(accept_io_);
+        acceptor_->open(endpoint.protocol());
+        acceptor_->set_option(asio::socket_base::reuse_address(true));
+        acceptor_->bind(endpoint);
+        acceptor_->listen(asio::socket_base::max_listen_connections);
+        *bound_port = acceptor_->local_endpoint().port();
+        accept_guard_.emplace(asio::make_work_guard(accept_io_));
+        stopping_.store(false, std::memory_order_release);
+        Status accept_status = startAccept();
+        if (!accept_status.ok()) {
+            std::error_code ignored;
+            acceptor_->close(ignored);
+            accept_guard_->reset();
+            started_.store(false, std::memory_order_release);
+            acceptor_.reset();
+            accept_guard_.reset();
+            return accept_status;
+        }
+        accept_thread_ = std::thread([this] {
+            try {
+                accept_io_.run();
+            } catch (const std::exception& error) {
+                LOG(ERROR) << "HP TCP accept loop failed: " << error.what();
+                stopping_.store(true, std::memory_order_release);
+            } catch (...) {
+                LOG(ERROR) << "HP TCP accept loop failed";
+                stopping_.store(true, std::memory_order_release);
+            }
+        });
+        return Status::OK();
+    } catch (const std::exception& error) {
+        started_.store(false, std::memory_order_release);
+        acceptor_.reset();
+        accept_guard_.reset();
+        return Status::InternalError(
+            std::string("HP TCP listener start failed: ") + error.what() +
+            LOC_MARK);
+    }
+}
+
+Status HighPerformanceTcpServer::startAccept() {
+    if (stopping_.load(std::memory_order_acquire) || !acceptor_ ||
+        !acceptor_->is_open()) {
+        return Status::OK();
+    }
+    try {
+        const size_t worker_id =
+            next_worker_.fetch_add(1, std::memory_order_relaxed) %
+            workers_->workerCount();
+        auto socket = std::make_shared<asio::ip::tcp::socket>(
+            workers_->ioContext(worker_id));
+        acceptor_->async_accept(*socket, [this, worker_id, socket](
+                                             const std::error_code& error) {
+            if (!error && !stopping_.load(std::memory_order_acquire)) {
+                if (reserveConnection()) {
+                    try {
+                        asio::post(workers_->ioContext(worker_id),
+                                   [this, worker_id, socket] {
+                                       installAcceptedSocket(worker_id, socket);
+                                   });
+                    } catch (const std::exception& post_error) {
+                        LOG(ERROR) << "HP TCP accepted-socket dispatch failed: "
+                                   << post_error.what();
+                        if (active_sessions_.fetch_sub(
+                                1, std::memory_order_acq_rel) == 1) {
+                            sessions_wait_cv_.notify_all();
+                        }
+                        std::error_code ignored;
+                        socket->close(ignored);
+                    } catch (...) {
+                        LOG(ERROR) << "HP TCP accepted-socket dispatch failed";
+                        if (active_sessions_.fetch_sub(
+                                1, std::memory_order_acq_rel) == 1) {
+                            sessions_wait_cv_.notify_all();
+                        }
+                        std::error_code ignored;
+                        socket->close(ignored);
+                    }
+                } else {
+                    std::error_code ignored;
+                    socket->close(ignored);
+                }
+            }
+            if (!stopping_.load(std::memory_order_acquire)) {
+                Status next = startAccept();
+                if (!next.ok()) {
+                    LOG(ERROR)
+                        << "HP TCP accept re-arm failed: " << next.ToString();
+                    stopping_.store(true, std::memory_order_release);
+                    std::error_code ignored;
+                    if (acceptor_) acceptor_->close(ignored);
+                    if (accept_guard_) accept_guard_->reset();
+                }
+            }
+        });
+        return Status::OK();
+    } catch (const std::exception& error) {
+        return Status::InternalError(
+            std::string("HP TCP accept initiation failed: ") + error.what() +
+            LOC_MARK);
+    } catch (...) {
+        return Status::InternalError(
+            "HP TCP accept initiation failed" LOC_MARK);
+    }
+}
+
+void HighPerformanceTcpServer::installAcceptedSocket(
+    size_t worker_id, std::shared_ptr<asio::ip::tcp::socket> socket) {
+    if (stopping_.load(std::memory_order_acquire)) {
+        std::error_code ignored;
+        socket->close(ignored);
+        if (active_sessions_.fetch_sub(1, std::memory_order_acq_rel) == 1) {
+            sessions_wait_cv_.notify_all();
+        }
+        return;
+    }
+    std::shared_ptr<Session> session;
+    try {
+        // READ response headers and payloads are separate writes. Do not wait
+        // for a delayed ACK before sending a short payload on a reused socket.
+        socket->set_option(asio::ip::tcp::no_delay(true));
+        session = std::make_shared<Session>(this, worker_id, socket, config_,
+                                            registry_);
+        sessions_[worker_id].insert(session);
+        session->start();
+    } catch (const std::exception& start_error) {
+        LOG(ERROR) << "HP TCP server session start failed: "
+                   << start_error.what();
+        if (session) sessions_[worker_id].erase(session);
+        std::error_code ignored;
+        socket->cancel(ignored);
+        socket->close(ignored);
+        if (active_sessions_.fetch_sub(1, std::memory_order_acq_rel) == 1) {
+            sessions_wait_cv_.notify_all();
+        }
+    } catch (...) {
+        LOG(ERROR) << "HP TCP server session start failed";
+        if (session) sessions_[worker_id].erase(session);
+        std::error_code ignored;
+        socket->cancel(ignored);
+        socket->close(ignored);
+        if (active_sessions_.fetch_sub(1, std::memory_order_acq_rel) == 1) {
+            sessions_wait_cv_.notify_all();
+        }
+    }
+}
+
+void HighPerformanceTcpServer::onSessionClosed(
+    size_t worker_id, const std::shared_ptr<Session>& session) {
+    if (worker_id < sessions_.size()) sessions_[worker_id].erase(session);
+    if (active_sessions_.fetch_sub(1, std::memory_order_acq_rel) == 1) {
+        std::lock_guard<std::mutex> lock(sessions_wait_mutex_);
+        sessions_wait_cv_.notify_all();
+    }
+}
+
+Status HighPerformanceTcpServer::stopAccepting() {
+    if (!started_.load(std::memory_order_acquire)) return Status::OK();
+    if (stopping_.exchange(true, std::memory_order_acq_rel)) {
+        if (accept_thread_.joinable()) accept_thread_.join();
+        return Status::OK();
+    }
+
+    if (accept_thread_.joinable()) {
+        auto done = std::make_shared<std::promise<void>>();
+        auto future = done->get_future();
+        try {
+            asio::post(accept_io_, [this, done] {
+                std::error_code ignored;
+                if (acceptor_) {
+                    acceptor_->cancel(ignored);
+                    acceptor_->close(ignored);
+                }
+                if (accept_guard_) accept_guard_->reset();
+                done->set_value();
+            });
+            future.wait();
+        } catch (...) {
+            std::error_code ignored;
+            if (acceptor_) acceptor_->close(ignored);
+            if (accept_guard_) accept_guard_->reset();
+        }
+        accept_thread_.join();
+    }
+    return Status::OK();
+}
+
+void HighPerformanceTcpServer::cancelWorkerSessions(size_t worker_id) {
+    if (worker_id >= sessions_.size()) return;
+    // Copy because Session::finishClosed erases from this set later.
+    std::vector<std::shared_ptr<Session>> copy(sessions_[worker_id].begin(),
+                                               sessions_[worker_id].end());
+    for (const auto& session : copy) session->cancel();
+}
+
+Status HighPerformanceTcpServer::cancelAll() {
+    if (workers_ == nullptr || active_sessions_.load() == 0) {
+        return Status::OK();
+    }
+    if (workers_->onWorkerThread()) {
+        return Status::InvalidArgument(
+            "HP TCP server cancelAll cannot block a worker" LOC_MARK);
+    }
+    if (!workers_->controlContextAvailable()) {
+        return active_sessions_.load() == 0
+                   ? Status::OK()
+                   : Status::InternalError(
+                         "HP TCP worker contexts unavailable with live "
+                         "sessions" LOC_MARK);
+    }
+
+    try {
+        for (size_t i = 0; i < workers_->workerCount(); ++i) {
+            asio::post(workers_->ioContext(i),
+                       [this, i] { cancelWorkerSessions(i); });
+        }
+    } catch (const std::exception& error) {
+        return Status::InternalError(
+            std::string("HP TCP server cancellation post failed: ") +
+            error.what() + LOC_MARK);
+    }
+    CHECK_STATUS(workers_->barrier());
+
+    std::unique_lock<std::mutex> lock(sessions_wait_mutex_);
+    sessions_wait_cv_.wait(lock, [&] {
+        return active_sessions_.load(std::memory_order_acquire) == 0;
+    });
+    return Status::OK();
+}
+
+Status HighPerformanceTcpServer::stop() {
+    Status first = stopAccepting();
+    Status canceled = cancelAll();
+    acceptor_.reset();
+    accept_guard_.reset();
+    started_.store(false, std::memory_order_release);
+    if (!first.ok()) return first;
+    return canceled;
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_task.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_task.cpp
new file mode 100644
index 0000000000..65397102c7
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_task.cpp
@@ -0,0 +1,95 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_task.h"
+
+#include <glog/logging.h>
+
+namespace mooncake::tent {
+
+bool HighPerformanceTcpTaskState::completeSlice(
+    TransferStatusEnum terminal,
+    std::optional<HighPerformanceTcpStatus> remote_status) noexcept {
+    if (terminal == INITIAL || terminal == PENDING || terminal == INVALID) {
+        terminal = FAILED;
+    }
+    if (terminal != COMPLETED) {
+        TransferStatusEnum aggregate =
+            slice_status_.load(std::memory_order_relaxed);
+        while (transferStatusSeverity(terminal) >
+                   transferStatusSeverity(aggregate) &&
+               !slice_status_.compare_exchange_weak(
+                   aggregate, terminal, std::memory_order_relaxed)) {
+        }
+    }
+
+    if (remote_status.has_value() &&
+        *remote_status != HighPerformanceTcpStatus::kOk) {
+        HighPerformanceTcpStatus expected = HighPerformanceTcpStatus::kOk;
+        (void)remote_status_.compare_exchange_strong(expected, *remote_status,
+                                                     std::memory_order_relaxed);
+    }
+
+    if (remaining_slices_.fetch_sub(1, std::memory_order_acq_rel) != 1) {
+        return false;
+    }
+
+    terminal = slice_status_.load(std::memory_order_acquire);
+    return completeOnce(terminal, terminal == COMPLETED ? reserved_bytes_ : 0);
+}
+
+bool HighPerformanceTcpTaskState::completeOnce(
+    TransferStatusEnum terminal, size_t bytes,
+    std::optional<HighPerformanceTcpStatus> remote_status) noexcept {
+    if (terminal == INITIAL || terminal == PENDING || terminal == INVALID) {
+        terminal = FAILED;
+        bytes = 0;
+    }
+
+    bool expected = false;
+    if (!completion_claimed_.compare_exchange_strong(
+            expected, true, std::memory_order_acq_rel,
+            std::memory_order_acquire)) {
+        return false;
+    }
+
+    // This function is called only after the final socket callback that could
+    // touch the local user buffer has retired (or before the operation reached
+    // a socket). Retire memory ownership and budget before publishing terminal
+    // status so teardown observing terminal cannot race unregister/free.
+    bytes_.store(bytes, std::memory_order_relaxed);
+    if (remote_status.has_value() &&
+        *remote_status != HighPerformanceTcpStatus::kOk) {
+        remote_status_.store(*remote_status, std::memory_order_relaxed);
+    }
+    local_lease_.reset();
+
+    if (reservation_active_.exchange(false, std::memory_order_acq_rel)) {
+        if (admission_ != nullptr) admission_->release(1, reserved_bytes_);
+    }
+
+    status_.store(terminal, std::memory_order_release);
+
+    try {
+        if (notify_progress_) notify_progress_(progress_batch_id_);
+    } catch (const std::exception& error) {
+        LOG(ERROR) << "HP TCP progress notification threw: " << error.what();
+    } catch (...) {
+        LOG(ERROR) << "HP TCP progress notification threw";
+    }
+    return true;
+}
+
+TransferStatus HighPerformanceTcpTaskState::snapshot() const noexcept {
+    TransferStatus result;
+    result.s = status_.load(std::memory_order_acquire);
+    result.transferred_bytes = bytes_.load(std::memory_order_acquire);
+    return result;
+}
+
+std::optional<HighPerformanceTcpStatus>
+HighPerformanceTcpTaskState::remoteStatus() const noexcept {
+    const auto status = remote_status_.load(std::memory_order_acquire);
+    if (status == HighPerformanceTcpStatus::kOk) return std::nullopt;
+    return status;
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_transport.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_transport.cpp
new file mode 100644
index 0000000000..978bd7d934
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_transport.cpp
@@ -0,0 +1,902 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_transport.h"
+
+#include <algorithm>
+#include <iomanip>
+#include <limits>
+#include <random>
+#include <sstream>
+#include <utility>
+
+#include <glog/logging.h>
+
+#include "tent/common/config.h"
+#include "tent/runtime/platform.h"
+#include "tent/runtime/slab.h"
+
+namespace mooncake::tent {
+namespace {
+
+constexpr uint64_t kIoProgressStepBytes = 1ULL << 20;
+
+std::string HostFromRpc(const std::string& address) {
+    if (address.empty()) return {};
+    if (address.front() == '[') {
+        const auto close = address.find(']');
+        return close == std::string::npos ? std::string{}
+                                          : address.substr(1, close - 1);
+    }
+    const auto colon = address.rfind(':');
+    if (colon == std::string::npos) return address;
+    // An unbracketed address with multiple colons is IPv6 and cannot be
+    // safely split as host:port. RPC addresses produced by TENT are bracketed,
+    // so reject rather than guessing.
+    if (address.find(':') != colon) return {};
+    return address.substr(0, colon);
+}
+
+bool HasTransport(const BufferDesc& buffer, TransportType type) {
+    return std::find(buffer.transports.begin(), buffer.transports.end(),
+                     type) != buffer.transports.end();
+}
+
+bool RemotePermissionAllows(const HighPerformanceTcpBufferAttr& attr,
+                            Request::OpCode opcode) {
+    if (opcode == Request::READ) {
+        return attr.permission == "global_read_only" ||
+               attr.permission == "global_read_write";
+    }
+    return attr.permission == "global_read_write";
+}
+
+Status FirstError(Status first, const Status& next) {
+    if (first.ok() && !next.ok()) return next;
+    return first;
+}
+
+Status NeedsRefresh(const std::string& message) {
+    return Status::NeedsRefreshCache(message + LOC_MARK);
+}
+
+Status CheckRuntimeHealth(
+    const HighPerformanceTcpWorkers* workers,
+    const HighPerformanceTcpAdmissionController* admission) {
+    if (workers != nullptr && workers->hasFailedWorker()) {
+        return Status::InternalError(
+            "HP TCP worker runtime has failed" LOC_MARK);
+    }
+    if (admission != nullptr && admission->failed()) {
+        return Status::InternalError(
+            "HP TCP admission accounting has failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+Status RemoteWireStatus(HighPerformanceTcpStatus status) {
+    switch (status) {
+        case HighPerformanceTcpStatus::kStaleRegistration:
+            return Status::NeedsRefreshCache(
+                "remote HP TCP registration is stale" LOC_MARK);
+        case HighPerformanceTcpStatus::kPermissionDenied:
+            return Status::AddressNotRegistered(
+                "remote HP TCP permission denied" LOC_MARK);
+        case HighPerformanceTcpStatus::kRangeRejected:
+            return Status::AddressNotRegistered(
+                "remote HP TCP range rejected" LOC_MARK);
+        case HighPerformanceTcpStatus::kShuttingDown:
+            return Status::TooManyRequests(
+                "remote HP TCP transport is shutting down" LOC_MARK);
+        case HighPerformanceTcpStatus::kOk:
+            return Status::OK();
+        default:
+            return Status::InvalidEntry(
+                "remote HP TCP protocol status " +
+                std::to_string(static_cast<uint16_t>(status)) + LOC_MARK);
+    }
+}
+
+}  // namespace
+
+HighPerformanceTcpTransport::HighPerformanceTcpTransport()
+    : HighPerformanceTcpTransport(HighPerformanceTcpParams{}) {}
+
+HighPerformanceTcpTransport::HighPerformanceTcpTransport(
+    HighPerformanceTcpParams params)
+    : params_(std::move(params)) {
+    caps.dram_to_dram = true;
+}
+
+HighPerformanceTcpTransport::~HighPerformanceTcpTransport() {
+    const Status status = uninstall();
+    if (!status.ok()) {
+        LOG(ERROR) << "HP TCP destructor uninstall failed: "
+                   << status.ToString();
+    }
+}
+
+Status HighPerformanceTcpTransport::validateParams() const {
+    if (params_.worker_count == 0 || params_.connections_per_peer == 0 ||
+        params_.max_outstanding_tasks == 0 ||
+        params_.max_outstanding_bytes == 0 || params_.max_transfer_bytes == 0 ||
+        params_.connect_timeout_ms == 0 || params_.progress_timeout_ms == 0 ||
+        params_.idle_connection_timeout_ms == 0) {
+        return Status::InvalidArgument(
+            "invalid high-performance TCP limits" LOC_MARK);
+    }
+    if (!params_.rail_addresses.empty()) {
+        if (params_.rail_addresses.size() > params_.connections_per_peer) {
+            return Status::InvalidArgument(
+                "HP TCP rails require at least one lane per address" LOC_MARK);
+        }
+        const bool wildcard_listener =
+            params_.bind_address.empty() || params_.bind_address == "0.0.0.0";
+        if (!wildcard_listener &&
+            (params_.rail_addresses.size() != 1 ||
+             params_.bind_address != params_.rail_addresses.front())) {
+            return Status::InvalidArgument(
+                "HP TCP listener must be wildcard or match the sole rail "
+                "address" LOC_MARK);
+        }
+        for (size_t i = 0; i < params_.rail_addresses.size(); ++i) {
+            std::error_code error;
+            const auto address =
+                asio::ip::make_address(params_.rail_addresses[i], error);
+            if (error || !address.is_v4() ||
+                std::find(params_.rail_addresses.begin() + i + 1,
+                          params_.rail_addresses.end(),
+                          params_.rail_addresses[i]) !=
+                    params_.rail_addresses.end()) {
+                return Status::InvalidArgument(
+                    "HP TCP rail addresses must be unique numeric IPv4 "
+                    "addresses" LOC_MARK);
+            }
+        }
+    }
+    return Status::OK();
+}
+
+std::string HighPerformanceTcpTransport::makeIncarnation() const {
+    std::random_device device;
+    std::mt19937_64 random(device());
+    std::ostringstream out;
+    for (int i = 0; i < 2; ++i) {
+        out << std::hex << std::setw(16) << std::setfill('0') << random();
+    }
+    return out.str();
+}
+
+Status HighPerformanceTcpTransport::rollbackPublishedEndpoint(
+    const std::optional<std::string>& previous_attr) {
+    if (!metadata_) return Status::OK();
+    Status first = metadata_->segmentManager().updateLocal(
+        [&](SegmentDesc& desc) -> Status {
+            if (desc.type != SegmentType::Memory) {
+                return Status::InvalidMetadataType(
+                    "local segment is not memory while rolling back HP "
+                    "TCP" LOC_MARK);
+            }
+            auto& attrs =
+                std::get<MemorySegmentDesc>(desc.detail).transport_attrs;
+            if (previous_attr.has_value()) {
+                attrs[static_cast<int>(TransportType::HP_TCP)] = *previous_attr;
+            } else {
+                attrs.erase(static_cast<int>(TransportType::HP_TCP));
+            }
+            return Status::OK();
+        });
+    if (first.ok()) {
+        first = metadata_->segmentManager().synchronizeLocal();
+    }
+    return first;
+}
+
+Status HighPerformanceTcpTransport::install(
+    std::string&, std::shared_ptr<ControlService> metadata,
+    std::shared_ptr<Topology>, std::shared_ptr<Config>) {
+    std::lock_guard<std::mutex> lifecycle_lock(lifecycle_mutex_);
+    if (installed_.load(std::memory_order_acquire) || workers_ || server_ ||
+        client_ || admission_) {
+        return Status::InvalidArgument(
+            "HP TCP transport is already installed or was not fully torn "
+            "down" LOC_MARK);
+    }
+    CHECK_STATUS(validateParams());
+    CHECK_STATUS(registry_.reopen());
+    if (!metadata) {
+        return Status::InvalidArgument("HP TCP metadata is null" LOC_MARK);
+    }
+
+    metadata_ = std::move(metadata);
+    stopping_.store(false, std::memory_order_release);
+
+    std::optional<std::string> previous_attr;
+    {
+        const SegmentDescRef local = metadata_->segmentManager().getLocal();
+        if (!local || local->type != SegmentType::Memory) {
+            metadata_.reset();
+            return Status::InvalidMetadataType(
+                "HP TCP requires a local memory segment" LOC_MARK);
+        }
+        const auto& attrs = local->getMemory().transport_attrs;
+        const auto it = attrs.find(static_cast<int>(TransportType::HP_TCP));
+        if (it != attrs.end()) previous_attr = it->second;
+    }
+
+    admission_ = std::make_unique<HighPerformanceTcpAdmissionController>(
+        params_.max_outstanding_tasks, params_.max_outstanding_bytes);
+    workers_ = std::make_unique<HighPerformanceTcpWorkers>(
+        HighPerformanceTcpWorkers::Config{params_.worker_count});
+
+    Status status = workers_->start();
+    if (!status.ok()) {
+        admission_.reset();
+        workers_.reset();
+        metadata_.reset();
+        return status;
+    }
+
+    client_ = std::make_unique<HighPerformanceTcpClient>(
+        HighPerformanceTcpClient::Config{
+            params_.max_transfer_bytes,
+            static_cast<size_t>(std::min<uint64_t>(kIoProgressStepBytes,
+                                                   params_.max_transfer_bytes)),
+            params_.connect_timeout_ms, params_.progress_timeout_ms,
+            params_.connections_per_peer, params_.idle_connection_timeout_ms},
+        workers_.get());
+
+    const uint64_t max_connections_u64 = std::max<uint64_t>(
+        params_.connections_per_peer, params_.max_outstanding_tasks);
+    const size_t max_connections = static_cast<size_t>(std::min<uint64_t>(
+        max_connections_u64, std::numeric_limits<size_t>::max()));
+    server_ = std::make_unique<HighPerformanceTcpServer>(
+        HighPerformanceTcpServer::Config{
+            params_.bind_address, params_.port, params_.max_transfer_bytes,
+            static_cast<size_t>(std::min<uint64_t>(kIoProgressStepBytes,
+                                                   params_.max_transfer_bytes)),
+            params_.progress_timeout_ms, max_connections},
+        &registry_, workers_.get());
+
+    uint16_t bound_port = 0;
+    status = server_->start(&bound_port);
+    if (!status.ok()) {
+        (void)server_->stop();
+        (void)client_->cancelAll(CANCELED);
+        (void)workers_->stop();
+        server_.reset();
+        client_.reset();
+        workers_.reset();
+        admission_.reset();
+        metadata_.reset();
+        return status;
+    }
+
+    const SegmentDescRef local = metadata_->segmentManager().getLocal();
+    std::vector<HighPerformanceTcpEndpoint> endpoints;
+    if (!params_.rail_addresses.empty()) {
+        for (const auto& address : params_.rail_addresses) {
+            endpoints.push_back({address, bound_port});
+        }
+    } else {
+        const std::string host = params_.advertise_address.empty()
+                                     ? HostFromRpc(local->rpc_server_addr)
+                                     : params_.advertise_address;
+        if (!host.empty()) endpoints.push_back({host, bound_port});
+    }
+    if (endpoints.empty()) {
+        status = Status::InvalidArgument(
+            "unable to derive HP TCP advertise address" LOC_MARK);
+    } else {
+        const std::string incarnation = makeIncarnation();
+        std::string encoded;
+        status = EncodeHighPerformanceTcpEndpointAttr(
+            {incarnation, std::move(endpoints), params_.max_transfer_bytes},
+            &encoded);
+        if (status.ok()) {
+            status = metadata_->segmentManager().updateLocal(
+                [&](SegmentDesc& desc) -> Status {
+                    if (desc.type != SegmentType::Memory) {
+                        return Status::InvalidMetadataType(
+                            "HP TCP local segment changed type" LOC_MARK);
+                    }
+                    std::get<MemorySegmentDesc>(desc.detail)
+                        .transport_attrs[static_cast<int>(
+                            TransportType::HP_TCP)] = encoded;
+                    return Status::OK();
+                });
+        }
+        if (status.ok()) {
+            status = metadata_->segmentManager().synchronizeLocal();
+        }
+    }
+
+    if (!status.ok()) {
+        const Status rollback = rollbackPublishedEndpoint(previous_attr);
+        if (!rollback.ok()) {
+            LOG(ERROR) << "HP TCP install metadata rollback failed: "
+                       << rollback.ToString();
+        }
+        (void)server_->stopAccepting();
+        (void)client_->cancelAll(CANCELED);
+        (void)server_->cancelAll();
+        (void)server_->stop();
+        (void)workers_->stop();
+        server_.reset();
+        client_.reset();
+        workers_.reset();
+        admission_.reset();
+        metadata_.reset();
+        return status;
+    }
+
+    metadata_->setNotifyCallback([this](const Notification& notification) {
+        RWSpinlock::WriteGuard guard(notify_lock_);
+        notifications_.push_back(notification);
+        return 0;
+    });
+    installed_.store(true, std::memory_order_release);
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::stopRuntime() {
+    // Lifecycle invariant: this is the sole normal teardown order. Client and
+    // server async callbacks hold raw parent pointers, so they must quiesce
+    // before their owners are destroyed and before worker contexts disappear.
+    Status first = Status::OK();
+    if (admission_) admission_->close();
+    if (server_) first = FirstError(std::move(first), server_->stopAccepting());
+    registry_.close();
+
+    if (workers_) first = FirstError(std::move(first), workers_->barrier());
+    if (client_)
+        first = FirstError(std::move(first), client_->cancelAll(CANCELED));
+    if (server_) first = FirstError(std::move(first), server_->cancelAll());
+
+    if (admission_) {
+        if (workers_ && workers_->hasFailedWorker() &&
+            (admission_->outstandingTasks() != 0 ||
+             admission_->outstandingBytes() != 0)) {
+            first = FirstError(
+                std::move(first),
+                Status::InternalError("HP TCP admission cannot drain after "
+                                      "worker failure" LOC_MARK));
+        } else {
+            first = FirstError(std::move(first), admission_->waitForZero());
+        }
+    }
+    if (server_) first = FirstError(std::move(first), server_->stop());
+    if (first.ok()) {
+        DCHECK(!admission_ || (admission_->outstandingTasks() == 0 &&
+                               admission_->outstandingBytes() == 0));
+        DCHECK(!client_ || client_->activeOperations() == 0);
+        DCHECK(!server_ || server_->activeSessionsForTest() == 0);
+    }
+    if (workers_) first = FirstError(std::move(first), workers_->stop());
+    return first;
+}
+
+Status HighPerformanceTcpTransport::quiesce() {
+    std::lock_guard<std::mutex> lifecycle_lock(lifecycle_mutex_);
+    if (!workers_ && !server_ && !client_ && !admission_) return Status::OK();
+    if (stopping_.exchange(true, std::memory_order_acq_rel)) {
+        // A previous quiesce under the same lifecycle lock completed all
+        // cancellation/join work before returning.
+        return Status::OK();
+    }
+    return stopRuntime();
+}
+
+Status HighPerformanceTcpTransport::uninstall() {
+    std::lock_guard<std::mutex> lifecycle_lock(lifecycle_mutex_);
+    if (!installed_.load(std::memory_order_acquire) && !workers_ && !server_ &&
+        !client_ && !admission_) {
+        return Status::OK();
+    }
+
+    Status first = Status::OK();
+    if (!stopping_.exchange(true, std::memory_order_acq_rel)) {
+        first = stopRuntime();
+    }
+
+    if (metadata_) {
+        metadata_->setNotifyCallback(nullptr);
+        Status removed = metadata_->segmentManager().updateLocal(
+            [](SegmentDesc& desc) -> Status {
+                if (desc.type != SegmentType::Memory) {
+                    return Status::InvalidMetadataType(
+                        "HP TCP local segment is not memory during "
+                        "uninstall" LOC_MARK);
+                }
+                std::get<MemorySegmentDesc>(desc.detail)
+                    .transport_attrs.erase(
+                        static_cast<int>(TransportType::HP_TCP));
+                return Status::OK();
+            });
+        first = FirstError(std::move(first), removed);
+        if (removed.ok()) {
+            first = FirstError(std::move(first),
+                               metadata_->segmentManager().synchronizeLocal());
+        }
+    }
+
+    server_.reset();
+    client_.reset();
+    workers_.reset();
+    admission_.reset();
+    metadata_.reset();
+    {
+        std::lock_guard<std::mutex> lock(lane_sequence_mutex_);
+        next_lane_sequence_.clear();
+    }
+    installed_.store(false, std::memory_order_release);
+    return first;
+}
+
+Status HighPerformanceTcpTransport::allocateSubBatch(SubBatchRef& batch,
+                                                     size_t max_size) {
+    if (batch != nullptr) {
+        return Status::InvalidArgument(
+            "HP TCP SubBatch output must be null" LOC_MARK);
+    }
+    auto* result = Slab<HighPerformanceTcpSubBatch>::Get().allocate();
+    if (result == nullptr) {
+        return Status::InternalError(
+            "unable to allocate HP TCP SubBatch" LOC_MARK);
+    }
+    result->max_size = max_size;
+    result->tasks.clear();
+    try {
+        result->tasks.reserve(max_size);
+    } catch (...) {
+        Slab<HighPerformanceTcpSubBatch>::Get().deallocate(result);
+        return Status::InternalError(
+            "unable to reserve HP TCP SubBatch storage" LOC_MARK);
+    }
+    batch = result;
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::freeSubBatch(SubBatchRef& batch) {
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    if (hp_batch == nullptr) {
+        return Status::InvalidArgument("invalid HP TCP SubBatch" LOC_MARK);
+    }
+    for (const auto& task : hp_batch->tasks) {
+        const TransferStatusEnum state = task->snapshot().s;
+        if (state == INITIAL || state == PENDING) {
+            return Status::InvalidArgument(
+                "cannot free an HP TCP SubBatch with pending tasks" LOC_MARK);
+        }
+    }
+    hp_batch->tasks.clear();
+    hp_batch->max_size = 0;
+    Slab<HighPerformanceTcpSubBatch>::Get().deallocate(hp_batch);
+    batch = nullptr;
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::planTask(
+    const Request& request, HighPerformanceTcpSubBatch& batch,
+    std::shared_ptr<HighPerformanceTcpTaskState>& planned_task,
+    std::vector<HighPerformanceTcpWorkers::Command>& commands) {
+    if (request.source == nullptr || request.length == 0 ||
+        request.length > params_.max_transfer_bytes ||
+        (request.opcode != Request::READ && request.opcode != Request::WRITE)) {
+        return Status::InvalidArgument("invalid HP TCP request" LOC_MARK);
+    }
+
+    HighPerformanceTcpBufferRegistry::Lease local_lease;
+    const uint64_t local_addr =
+        static_cast<uint64_t>(reinterpret_cast<uintptr_t>(request.source));
+    CHECK_STATUS(
+        registry_.acquireLocalLease(local_addr, request.length, &local_lease));
+
+    HighPerformanceTcpEndpointAttr endpoint_attr;
+    HighPerformanceTcpBufferAttr buffer_attr;
+    SegmentDescRef pin;
+    const size_t endpoint_count =
+        params_.rail_addresses.empty() ? 1 : params_.rail_addresses.size();
+    Status resolved = metadata_->segmentManager().withCachedSegment(
+        request.target_id, pin, [&](SegmentDesc* segment) -> Status {
+            if (segment == nullptr || segment->type != SegmentType::Memory) {
+                return NeedsRefresh("HP TCP target is not a memory segment");
+            }
+            BufferDesc* buffer =
+                segment->findBuffer(request.target_offset, request.length);
+            if (buffer == nullptr ||
+                !HasTransport(*buffer, TransportType::HP_TCP)) {
+                return NeedsRefresh("HP TCP target buffer is not advertised");
+            }
+            const auto endpoint_it = segment->getMemory().transport_attrs.find(
+                static_cast<int>(TransportType::HP_TCP));
+            if (endpoint_it == segment->getMemory().transport_attrs.end()) {
+                return NeedsRefresh("HP TCP endpoint metadata is missing");
+            }
+            Status decoded = DecodeHighPerformanceTcpEndpointAttr(
+                endpoint_it->second, &endpoint_attr);
+            if (!decoded.ok()) {
+                return NeedsRefresh("HP TCP endpoint metadata is incompatible");
+            }
+            if (endpoint_attr.endpoints.size() != endpoint_count) {
+                return NeedsRefresh(
+                    "HP TCP local and remote rail counts differ");
+            }
+            const auto registration_it =
+                buffer->transport_attrs.find(TransportType::HP_TCP);
+            if (registration_it == buffer->transport_attrs.end()) {
+                return NeedsRefresh("HP TCP buffer registration is missing");
+            }
+            decoded = DecodeHighPerformanceTcpBufferAttr(
+                registration_it->second, &buffer_attr);
+            if (!decoded.ok()) {
+                return NeedsRefresh("HP TCP buffer metadata is incompatible");
+            }
+            return Status::OK();
+        });
+    if (!resolved.ok()) return resolved;
+
+    if (request.length > endpoint_attr.max_transfer_bytes) {
+        return Status::InvalidArgument(
+            "HP TCP request exceeds remote endpoint capability" LOC_MARK);
+    }
+    if (!RemotePermissionAllows(buffer_attr, request.opcode)) {
+        return Status::AddressNotRegistered(
+            "HP TCP remote permission does not allow requested "
+            "operation" LOC_MARK);
+    }
+
+    // A partial READ can be overwritten by retry; a partial WRITE cannot.
+    // Split only when every rail receives at least one normal I/O step.
+    const size_t slice_count =
+        request.opcode == Request::READ && endpoint_count > 1 &&
+                request.length / endpoint_count >= kIoProgressStepBytes
+            ? endpoint_count
+            : 1;
+    uint64_t request_id =
+        next_request_id_.fetch_add(1, std::memory_order_relaxed);
+    if (request_id == 0) {
+        return Status::InternalError(
+            "HP TCP request id space exhausted" LOC_MARK);
+    }
+
+    auto task = std::make_shared<HighPerformanceTcpTaskState>(
+        request.length, batch.progress_batch_id, batch.notify_progress,
+        std::move(local_lease), slice_count);
+    task->setRequestId(request_id);
+    planned_task = task;
+
+    uint64_t lane_sequence;
+    {
+        std::lock_guard<std::mutex> lock(lane_sequence_mutex_);
+        // Preserve the first lane choice, then advance independently.
+        auto it = next_lane_sequence_.try_emplace(request.target_id, request_id)
+                      .first;
+        lane_sequence = it->second++;
+    }
+    uint64_t slice_offset = 0;
+    for (size_t slice = 0; slice < slice_count; ++slice) {
+        const uint64_t slice_length =
+            request.length / slice_count +
+            (slice < request.length % slice_count ? 1 : 0);
+        uint32_t lane_id = 0;
+        uint32_t endpoint_id = 0;
+        if (slice_count == 1) {
+            lane_id = static_cast<uint32_t>(
+                lane_sequence %
+                static_cast<uint64_t>(params_.connections_per_peer));
+            endpoint_id = static_cast<uint32_t>(lane_id % endpoint_count);
+        } else {
+            endpoint_id = static_cast<uint32_t>(slice);
+            const size_t lanes_for_endpoint =
+                1 + (params_.connections_per_peer - 1 - endpoint_id) /
+                        endpoint_count;
+            lane_id = static_cast<uint32_t>(
+                endpoint_id +
+                (lane_sequence % lanes_for_endpoint) * endpoint_count);
+        }
+        const auto& endpoint = endpoint_attr.endpoints[endpoint_id];
+        const size_t owner_worker =
+            workers_->affinityOwner(request.target_id, lane_id);
+
+        HighPerformanceTcpClient::Operation operation;
+        operation.peer_id = request.target_id;
+        operation.incarnation = endpoint_attr.incarnation;
+        operation.host = endpoint.host;
+        if (!params_.rail_addresses.empty()) {
+            operation.local_host = params_.rail_addresses[endpoint_id];
+        }
+        operation.port = endpoint.port;
+        operation.lane_id = lane_id;
+        operation.registration_id = buffer_attr.registration_id;
+        operation.remote_addr = request.target_offset + slice_offset;
+        operation.local_addr =
+            static_cast<uint8_t*>(request.source) + slice_offset;
+        operation.length = slice_length;
+        operation.opcode = request.opcode == Request::READ
+                               ? HighPerformanceTcpOpcode::kRead
+                               : HighPerformanceTcpOpcode::kWrite;
+        operation.request_id = request_id;
+        if (slice_count == 1) {
+            operation.complete =
+                [task](TransferStatusEnum terminal, size_t bytes,
+                       std::optional<HighPerformanceTcpStatus> remote_status) {
+                    (void)task->completeOnce(terminal, bytes, remote_status);
+                };
+        } else {
+            operation.complete =
+                [this, task](
+                    TransferStatusEnum terminal, size_t,
+                    std::optional<HighPerformanceTcpStatus> remote_status) {
+                    const bool cancel_siblings =
+                        terminal != COMPLETED && task->requestCancel();
+                    const bool finished =
+                        task->completeSlice(terminal, remote_status);
+                    if (cancel_siblings && !finished &&
+                        !stopping_.load(std::memory_order_acquire)) {
+                        (void)client_->cancelRequest(task->requestId());
+                    }
+                };
+        }
+
+        HighPerformanceTcpWorkers::Command command;
+        command.worker_id = owner_worker;
+        command.run = [this, task, slice_count,
+                       operation =
+                           std::move(operation)](size_t worker_id) mutable {
+            if (task->cancelRequested() ||
+                stopping_.load(std::memory_order_acquire)) {
+                if (slice_count == 1) {
+                    (void)task->completeOnce(CANCELED, 0);
+                } else {
+                    (void)task->completeSlice(CANCELED);
+                }
+                return;
+            }
+            client_->enqueueOnOwner(worker_id, std::move(operation));
+        };
+        command.cancel = [task, slice_count] {
+            if (slice_count == 1) {
+                (void)task->completeOnce(CANCELED, 0);
+            } else {
+                (void)task->completeSlice(CANCELED);
+            }
+        };
+        commands.push_back(std::move(command));
+        slice_offset += slice_length;
+    }
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::submitTransferTasks(
+    SubBatchRef batch, const std::vector<Request>& requests) {
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    if (hp_batch == nullptr) {
+        return Status::InvalidArgument("invalid HP TCP SubBatch" LOC_MARK);
+    }
+    if (!installed_.load(std::memory_order_acquire) ||
+        stopping_.load(std::memory_order_acquire) || workers_ == nullptr ||
+        client_ == nullptr || admission_ == nullptr) {
+        return Status::InvalidArgument(
+            "HP TCP transport is unavailable" LOC_MARK);
+    }
+    CHECK_STATUS(CheckRuntimeHealth(workers_.get(), admission_.get()));
+    if (requests.empty()) return Status::OK();
+    if (requests.size() > hp_batch->max_size - hp_batch->tasks.size()) {
+        return Status::TooManyRequests(
+            "HP TCP SubBatch capacity exceeded" LOC_MARK);
+    }
+
+    uint64_t total_bytes = 0;
+    for (const Request& request : requests) {
+        if (request.length >
+                std::numeric_limits<uint64_t>::max() - total_bytes ||
+            request.length == 0) {
+            return Status::InvalidArgument(
+                "HP TCP batch byte count overflow" LOC_MARK);
+        }
+        total_bytes += request.length;
+    }
+
+    std::vector<std::shared_ptr<HighPerformanceTcpTaskState>> planned_tasks;
+    std::vector<HighPerformanceTcpWorkers::Command> commands;
+    try {
+        planned_tasks.resize(requests.size());
+        commands.reserve(requests.size());
+    } catch (...) {
+        return Status::InternalError(
+            "unable to allocate HP TCP task planning storage" LOC_MARK);
+    }
+
+    for (size_t i = 0; i < requests.size(); ++i) {
+        CHECK_STATUS(
+            planTask(requests[i], *hp_batch, planned_tasks[i], commands));
+    }
+
+    // SubBatch capacity was reserved at allocateSubBatch(). The callback below
+    // therefore performs only noexcept shared_ptr moves and reservation flag
+    // stores while dispatch ownership is being committed.
+    const size_t old_size = hp_batch->tasks.size();
+    Status committed = workers_->tryCommitBatch(
+        commands, admission_.get(), requests.size(), total_bytes, [&] {
+            for (auto& task : planned_tasks) {
+                task->activateReservation(admission_.get());
+                hp_batch->tasks.push_back(std::move(task));
+            }
+        });
+    if (!committed.ok()) {
+        // The worker transaction promises not to invoke on_commit on failure.
+        // Keep a defensive assertion in debug logs without mutating the batch.
+        if (hp_batch->tasks.size() != old_size) {
+            LOG(FATAL) << "HP TCP atomic admission violated SubBatch rollback";
+        }
+        return committed;
+    }
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::getTransferStatus(SubBatchRef batch,
+                                                      int task_id,
+                                                      TransferStatus& status) {
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    if (hp_batch == nullptr || task_id < 0 ||
+        static_cast<size_t>(task_id) >= hp_batch->tasks.size()) {
+        return Status::InvalidArgument("invalid HP TCP task id" LOC_MARK);
+    }
+    const auto& task = hp_batch->tasks[static_cast<size_t>(task_id)];
+    status = task->snapshot();
+    if (status.s == PENDING) {
+        return CheckRuntimeHealth(workers_.get(), admission_.get());
+    }
+    const auto remote_status = task->remoteStatus();
+    if (remote_status.has_value()) return RemoteWireStatus(*remote_status);
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::retryTransferTask(SubBatchRef batch,
+                                                      int task_id,
+                                                      const Request& request) {
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    if (hp_batch == nullptr || task_id < 0 ||
+        static_cast<size_t>(task_id) >= hp_batch->tasks.size()) {
+        return Status::InvalidArgument("invalid HP TCP retry task id" LOC_MARK);
+    }
+    CHECK_STATUS(CheckRuntimeHealth(workers_.get(), admission_.get()));
+    if (hp_batch->tasks[static_cast<size_t>(task_id)]->snapshot().s != FAILED) {
+        return Status::InvalidArgument(
+            "HP TCP retry requires a failed attempt" LOC_MARK);
+    }
+
+    std::shared_ptr<HighPerformanceTcpTaskState> planned_task;
+    std::vector<HighPerformanceTcpWorkers::Command> commands;
+    commands.reserve(1);
+    CHECK_STATUS(planTask(request, *hp_batch, planned_task, commands));
+
+    Status committed = workers_->tryCommitBatch(
+        commands, admission_.get(), 1, request.length, [&] {
+            planned_task->activateReservation(admission_.get());
+            hp_batch->tasks[static_cast<size_t>(task_id)] =
+                std::move(planned_task);
+        });
+    return committed;
+}
+
+Status HighPerformanceTcpTransport::cancelTransferTask(SubBatchRef batch,
+                                                       int task_id) {
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    if (hp_batch == nullptr || task_id < 0 ||
+        static_cast<size_t>(task_id) >= hp_batch->tasks.size()) {
+        return Status::InvalidArgument("invalid HP TCP task id" LOC_MARK);
+    }
+    const auto& task = hp_batch->tasks[static_cast<size_t>(task_id)];
+    const TransferStatusEnum state = task->snapshot().s;
+    if (state != INITIAL && state != PENDING) return Status::OK();
+
+    if (!task->requestCancel()) return Status::OK();
+    if (client_ == nullptr || workers_ == nullptr) return Status::OK();
+    const Status canceled = client_->cancelRequest(task->requestId());
+    // A request still in the worker dispatch queue has no client lane yet;
+    // its command observes cancelRequested() and settles it. Treat inability
+    // to find/post a lane cancellation during shutdown as best effort.
+    if (canceled.IsInternalError() &&
+        stopping_.load(std::memory_order_acquire)) {
+        return Status::OK();
+    }
+    return canceled;
+}
+
+Status HighPerformanceTcpTransport::addMemoryBuffer(
+    BufferDesc& desc, const MemoryOptions& options) {
+    if (stopping_.load(std::memory_order_acquire)) {
+        return Status::TooManyRequests(
+            "HP TCP transport is shutting down" LOC_MARK);
+    }
+    const LocationParser location(desc.location);
+    if ((location.type() != "cpu" && location.type() != kWildcardLocation) ||
+        Platform::getLoader().getMemoryType(
+            reinterpret_cast<void*>(desc.addr)) != MTYPE_CPU) {
+        return Status::InvalidArgument(
+            "HP TCP v1 supports CPU DRAM only" LOC_MARK);
+    }
+
+    uint64_t registration_id = 0;
+    CHECK_STATUS(
+        registry_.add(desc.addr, desc.length, options.perm, &registration_id));
+    if (options.perm == kLocalReadWrite) return Status::OK();
+
+    std::string encoded;
+    Status status = EncodeHighPerformanceTcpBufferAttr(
+        {registration_id, HighPerformanceTcpPermissionName(options.perm)},
+        &encoded);
+    if (!status.ok()) {
+        (void)registry_.remove(desc.addr, desc.length);
+        return status;
+    }
+    desc.transport_attrs[TransportType::HP_TCP] = std::move(encoded);
+    if (!HasTransport(desc, TransportType::HP_TCP)) {
+        desc.transports.push_back(TransportType::HP_TCP);
+    }
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::addMemoryBuffer(
+    std::vector<BufferDesc>& desc_list, const MemoryOptions& options) {
+    std::vector<size_t> created;
+    try {
+        created.reserve(desc_list.size());
+    } catch (...) {
+        return Status::InternalError(
+            "unable to allocate HP TCP registration rollback state" LOC_MARK);
+    }
+
+    for (size_t i = 0; i < desc_list.size(); ++i) {
+        const bool tracked_before =
+            registry_.tracks(desc_list[i].addr, desc_list[i].length);
+        Status status = addMemoryBuffer(desc_list[i], options);
+        if (status.ok()) {
+            if (!tracked_before) created.push_back(i);
+            continue;
+        }
+        for (auto it = created.rbegin(); it != created.rend(); ++it) {
+            const Status rollback = removeMemoryBuffer(desc_list[*it]);
+            if (!rollback.ok()) {
+                LOG(ERROR) << "HP TCP registration rollback failed: "
+                           << rollback.ToString();
+            }
+        }
+        return status;
+    }
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::removeMemoryBuffer(BufferDesc& desc) {
+    if (!registry_.tracks(desc.addr, desc.length)) return Status::OK();
+    Status status = registry_.remove(desc.addr, desc.length);
+    if (!status.ok()) return status;
+    desc.transport_attrs.erase(TransportType::HP_TCP);
+    desc.transports.erase(
+        std::remove(desc.transports.begin(), desc.transports.end(),
+                    TransportType::HP_TCP),
+        desc.transports.end());
+    return Status::OK();
+}
+
+Status HighPerformanceTcpTransport::sendNotification(
+    SegmentID target_id, const Notification& notification) {
+    if (!metadata_) {
+        return Status::InternalError("HP TCP metadata is unavailable" LOC_MARK);
+    }
+    return metadata_->segmentManager().withCachedSegment(
+        target_id, [&](SegmentDesc* segment) {
+            return ControlClient::notify(segment->rpc_server_addr,
+                                         notification);
+        });
+}
+
+Status HighPerformanceTcpTransport::receiveNotification(
+    std::vector<Notification>& notifications) {
+    RWSpinlock::WriteGuard guard(notify_lock_);
+    notifications.clear();
+    notifications.swap(notifications_);
+    return Status::OK();
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_workers.cpp b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_workers.cpp
new file mode 100644
index 0000000000..00264ae9f4
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/hp_tcp/hp_tcp_workers.cpp
@@ -0,0 +1,307 @@
+// Copyright 2026 KVCache.AI
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+#include <algorithm>
+#include <exception>
+#include <utility>
+
+#include <glog/logging.h>
+
+namespace mooncake::tent {
+
+Status HighPerformanceTcpAdmissionController::tryReserve(uint64_t tasks,
+                                                         uint64_t bytes) {
+    if (tasks == 0 || bytes == 0) {
+        return Status::InvalidArgument(
+            "HP TCP admission reservation must be non-zero" LOC_MARK);
+    }
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (failed_.load(std::memory_order_acquire)) {
+        return Status::InternalError(
+            "HP TCP admission accounting is failed" LOC_MARK);
+    }
+    if (!accepting_) {
+        return Status::TooManyRequests("HP TCP admission is closed" LOC_MARK);
+    }
+    if (tasks > max_tasks_ || bytes > max_bytes_ ||
+        tasks_ > max_tasks_ - tasks || bytes_ > max_bytes_ - bytes) {
+        return Status::TooManyRequests(
+            "HP TCP admission limit exceeded" LOC_MARK);
+    }
+    tasks_ += tasks;
+    bytes_ += bytes;
+    return Status::OK();
+}
+
+void HighPerformanceTcpAdmissionController::release(uint64_t tasks,
+                                                    uint64_t bytes) {
+    bool notify_waiters = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (tasks > tasks_ || bytes > bytes_) {
+            LOG(ERROR) << "HP TCP admission release underflow";
+            // Do not manufacture a drained state. A double release is a
+            // lifecycle invariant violation; preserving the counters keeps
+            // shutdown from treating live work as retired.
+            failed_.store(true, std::memory_order_release);
+            notify_waiters = true;
+        } else {
+            tasks_ -= tasks;
+            bytes_ -= bytes;
+            notify_waiters = tasks_ == 0 && bytes_ == 0;
+        }
+    }
+    if (notify_waiters) zero_cv_.notify_all();
+}
+
+void HighPerformanceTcpAdmissionController::close() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    accepting_ = false;
+}
+
+Status HighPerformanceTcpAdmissionController::waitForZero() {
+    std::unique_lock<std::mutex> lock(mutex_);
+    zero_cv_.wait(lock, [&] {
+        return failed_.load(std::memory_order_acquire) ||
+               (tasks_ == 0 && bytes_ == 0);
+    });
+    if (failed_.load(std::memory_order_acquire)) {
+        return Status::InternalError(
+            "HP TCP admission accounting is failed" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+bool HighPerformanceTcpAdmissionController::failed() const {
+    return failed_.load(std::memory_order_acquire);
+}
+
+uint64_t HighPerformanceTcpAdmissionController::outstandingTasks() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return tasks_;
+}
+
+uint64_t HighPerformanceTcpAdmissionController::outstandingBytes() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return bytes_;
+}
+
+HighPerformanceTcpWorkers::HighPerformanceTcpWorkers()
+    : HighPerformanceTcpWorkers(Config{}) {}
+
+HighPerformanceTcpWorkers::HighPerformanceTcpWorkers(Config config)
+    : config_(config) {}
+
+HighPerformanceTcpWorkers::~HighPerformanceTcpWorkers() { (void)stop(); }
+
+Status HighPerformanceTcpWorkers::start() {
+    std::lock_guard<std::mutex> lock(lifecycle_mutex_);
+    if (running()) return Status::OK();
+    if (started_ || !workers_.empty() || config_.worker_count == 0) {
+        return Status::InvalidArgument("invalid HP TCP worker state" LOC_MARK);
+    }
+
+    try {
+        started_ = true;
+        failed_.store(false, std::memory_order_release);
+        workers_.reserve(config_.worker_count);
+        for (size_t i = 0; i < config_.worker_count; ++i) {
+            workers_.push_back(std::make_unique<WorkerContext>());
+        }
+        running_.store(true, std::memory_order_release);
+        for (auto& worker : workers_) {
+            worker->thread = std::thread([this, context = worker.get()] {
+                for (;;) {
+                    try {
+                        context->io.run();
+                        break;
+                    } catch (const std::exception& error) {
+                        LOG(ERROR) << "HP TCP io_context handler failed: "
+                                   << error.what();
+                        markWorkerFailed();
+                    } catch (...) {
+                        LOG(ERROR) << "HP TCP io_context handler failed";
+                        markWorkerFailed();
+                    }
+                }
+            });
+        }
+    } catch (const std::exception& error) {
+        running_.store(false, std::memory_order_release);
+        for (auto& worker : workers_) {
+            worker->guard.reset();
+            worker->io.stop();
+            if (worker->thread.joinable()) worker->thread.join();
+        }
+        workers_.clear();
+        return Status::InternalError(
+            std::string("failed to start HP TCP workers: ") + error.what() +
+            LOC_MARK);
+    }
+    return Status::OK();
+}
+
+void HighPerformanceTcpWorkers::markWorkerFailed() noexcept {
+    failed_.store(true, std::memory_order_release);
+    // New batches observe failed_ and are rejected. The owner loop deliberately
+    // keeps running so already-committed work and teardown cancellation retain
+    // their original affinity and can retire every task, session and lease.
+}
+
+bool HighPerformanceTcpWorkers::onWorkerThread() const {
+    const auto current = std::this_thread::get_id();
+    return std::any_of(workers_.begin(), workers_.end(), [&](const auto& w) {
+        return w->thread.joinable() && w->thread.get_id() == current;
+    });
+}
+
+Status HighPerformanceTcpWorkers::stop() {
+    std::lock_guard<std::mutex> lock(lifecycle_mutex_);
+    if (workers_.empty()) return Status::OK();
+    if (onWorkerThread()) {
+        return Status::InvalidArgument(
+            "HP TCP worker cannot synchronously stop itself" LOC_MARK);
+    }
+    const bool failed = hasFailedWorker();
+    running_.store(false, std::memory_order_release);
+    for (auto& worker : workers_) worker->guard.reset();
+    for (auto& worker : workers_) worker->io.stop();
+    for (auto& worker : workers_) {
+        if (worker->thread.joinable()) worker->thread.join();
+    }
+    // Keep stopped contexts alive until their client/server owners are
+    // destroyed. Those owners contain socket objects and cancellation handlers
+    // that refer to these contexts, even after no worker can execute them.
+    if (failed) {
+        return Status::InternalError(
+            "HP TCP workers stopped after an owner thread failure" LOC_MARK);
+    }
+    return Status::OK();
+}
+
+size_t HighPerformanceTcpWorkers::affinityOwner(uint64_t peer,
+                                                uint32_t lane) const {
+    size_t hash = std::hash<uint64_t>{}(peer);
+    const auto mix = [&hash](size_t value) {
+        hash ^= value + static_cast<size_t>(0x9e3779b97f4a7c15ULL) +
+                (hash << 6U) + (hash >> 2U);
+    };
+    // A lane keeps the same worker owner regardless of its rail.
+    mix(std::hash<uint32_t>{}(0));
+    mix(std::hash<uint32_t>{}(lane));
+    return config_.worker_count == 0 ? 0 : hash % config_.worker_count;
+}
+
+Status HighPerformanceTcpWorkers::tryCommitBatch(
+    std::vector<Command>& commands,
+    HighPerformanceTcpAdmissionController* admission, uint64_t reserve_tasks,
+    uint64_t reserve_bytes, const std::function<void()>& on_commit) {
+    if (commands.empty()) return Status::OK();
+
+    std::lock_guard<std::mutex> submit_lock(submit_mutex_);
+    if (hasFailedWorker()) {
+        return Status::InternalError(
+            "HP TCP worker owner thread has failed" LOC_MARK);
+    }
+    if (!running()) {
+        return Status::InternalError("HP TCP workers are not running" LOC_MARK);
+    }
+
+    for (const auto& command : commands) {
+        if (!command.run || command.worker_id >= workers_.size()) {
+            return Status::InvalidArgument(
+                "invalid HP TCP worker command" LOC_MARK);
+        }
+    }
+
+    bool reserved = false;
+    if (admission != nullptr) {
+        CHECK_STATUS(admission->tryReserve(reserve_tasks, reserve_bytes));
+        reserved = true;
+    }
+    try {
+        if (on_commit) on_commit();
+    } catch (...) {
+        if (reserved) admission->release(reserve_tasks, reserve_bytes);
+        return Status::InternalError("HP TCP ownership commit failed" LOC_MARK);
+    }
+
+    for (size_t i = 0; i < commands.size(); ++i) {
+        Command command = std::move(commands[i]);
+        const size_t owner = command.worker_id;
+        const auto cancel = command.cancel;
+        try {
+            asio::post(workers_[owner]->io,
+                       [this, command = std::move(command)]() mutable {
+                           runCommand(std::move(command));
+                       });
+        } catch (...) {
+            if (cancel) cancel();
+            for (++i; i < commands.size(); ++i) {
+                auto& pending = commands[i];
+                if (pending.cancel) pending.cancel();
+            }
+            return Status::OK();
+        }
+    }
+    return Status::OK();
+}
+
+void HighPerformanceTcpWorkers::runCommand(Command command) {
+    const size_t owner = command.worker_id;
+    try {
+        if (running()) {
+            command.run(owner);
+        } else if (command.cancel) {
+            command.cancel();
+        }
+    } catch (const std::exception& error) {
+        LOG(ERROR) << "HP TCP worker command failed: " << error.what();
+        if (command.cancel) command.cancel();
+    } catch (...) {
+        LOG(ERROR) << "HP TCP worker command failed";
+        if (command.cancel) command.cancel();
+    }
+}
+
+Status HighPerformanceTcpWorkers::barrier() {
+    if (onWorkerThread()) {
+        return Status::InvalidArgument(
+            "HP TCP barrier cannot run on a worker thread" LOC_MARK);
+    }
+    if (workers_.empty()) return Status::OK();
+    if (!running()) {
+        return Status::InternalError(
+            "HP TCP barrier cannot run after workers stop" LOC_MARK);
+    }
+
+    struct Latch {
+        std::mutex mutex;
+        std::condition_variable cv;
+        size_t remaining{0};
+    };
+    auto latch = std::make_shared<Latch>();
+    latch->remaining = workers_.size();
+    try {
+        for (auto& worker : workers_) {
+            asio::post(worker->io, [latch] {
+                std::lock_guard<std::mutex> lock(latch->mutex);
+                if (--latch->remaining == 0) latch->cv.notify_all();
+            });
+        }
+    } catch (...) {
+        return Status::InternalError("HP TCP barrier post failed" LOC_MARK);
+    }
+    std::unique_lock<std::mutex> lock(latch->mutex);
+    latch->cv.wait(lock, [&] { return latch->remaining == 0; });
+    return Status::OK();
+}
+
+asio::io_context& HighPerformanceTcpWorkers::ioContext(size_t worker_id) {
+    if (worker_id >= workers_.size()) {
+        throw std::out_of_range("HP TCP worker id out of range");
+    }
+    return workers_[worker_id]->io;
+}
+
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/src/transport/io_uring/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/io_uring/CMakeLists.txt
index ed7294f999..f4fe8327f1 100644
--- a/mooncake-transfer-engine/tent/src/transport/io_uring/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/transport/io_uring/CMakeLists.txt
@@ -1,10 +1,9 @@
-if (URING_LIB AND URING_INCLUDE)
+if(TARGET Mooncake::liburing)
     file(GLOB TEV1_XPORT_URING_SOURCES "*.cpp")
     add_library(tent_xport_uring STATIC ${TEV1_XPORT_URING_SOURCES})
-    target_include_directories(tent_xport_uring PUBLIC ${URING_INCLUDE})
-    target_link_libraries(tent_xport_uring PUBLIC ${URING_LIB} tent_common)
+    target_link_libraries(tent_xport_uring PUBLIC Mooncake::liburing tent_common)
     if (CUDAToolkit_FOUND)
-        target_link_libraries(tent_xport_uring PUBLIC 
+        target_link_libraries(tent_xport_uring PUBLIC
             CUDA::cudart CUDA::cuda_driver)
     endif()
 endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/io_uring/io_uring_transport.cpp b/mooncake-transfer-engine/tent/src/transport/io_uring/io_uring_transport.cpp
index 35e8c0927c..7304d23cca 100644
--- a/mooncake-transfer-engine/tent/src/transport/io_uring/io_uring_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/io_uring/io_uring_transport.cpp
@@ -182,52 +182,106 @@ Status IOUringTransport::submitTransferTasks(
     if (request_list.size() + (int)io_uring_batch->task_list.size() >
         io_uring_batch->max_size)
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
+
+    const size_t kPageSize = 4096;
+
+    // Phase 1: validate every request and stage alignment-fixing buffers
+    // before touching the sub-batch or the SQ ring (all-or-nothing
+    // submission contract, see Transport::submitTransferTasks). Any failure
+    // here returns with the sub-batch, the SQ ring and the file untouched;
+    // staging buffers allocated for earlier requests are freed.
+    std::vector<IOUringFileContext*> contexts;
+    contexts.reserve(request_list.size());
+    std::vector<void*> staging_buffers;
+    staging_buffers.reserve(request_list.size());
     for (auto& request : request_list) {
-        io_uring_batch->task_list.push_back(IOUringTask{});
-        auto& task =
-            io_uring_batch->task_list[io_uring_batch->task_list.size() - 1];
-        task.request = request;
-        task.status_word = TransferStatusEnum::PENDING;
+        if (request.opcode != Request::READ &&
+            request.opcode != Request::WRITE) {
+            for (void* buffer : staging_buffers) free(buffer);
+            return Status::InvalidArgument("Unsupported opcode" LOC_MARK);
+        }
 
         IOUringFileContext* context = findFileContext(request.target_id);
-        if (!context || !context->ready())
+        if (!context || !context->ready()) {
+            for (void* buffer : staging_buffers) free(buffer);
             return Status::InvalidArgument("Invalid remote segment" LOC_MARK);
+        }
+        contexts.push_back(context);
 
-        struct io_uring_sqe* sqe = io_uring_get_sqe(&io_uring_batch->ring);
-        if (!sqe)
-            return Status::InternalError("io_uring_get_sqe failed" LOC_MARK);
-
-        const size_t kPageSize = 4096;
         if (Platform::getLoader().getMemoryType(request.source) == MTYPE_CUDA ||
             (uint64_t)request.source % kPageSize) {
-            int rc = posix_memalign(&task.buffer, kPageSize, request.length);
-            if (rc)
+            void* buffer = nullptr;
+            int rc = posix_memalign(&buffer, kPageSize, request.length);
+            if (rc) {
+                for (void* staged : staging_buffers) free(staged);
                 return Status::InternalError("posix_memalign failed" LOC_MARK);
+            }
+            staging_buffers.push_back(buffer);
+        } else {
+            staging_buffers.push_back(nullptr);
+        }
+    }
 
-            if (request.opcode == Request::READ)
-                io_uring_prep_read(sqe, context->getHandle(), task.buffer,
-                                   request.length, request.target_offset);
-            else if (request.opcode == Request::WRITE) {
+    // The capacity check above bounds the task count, but SQEs left queued
+    // by a deferred submission (see below) may still occupy the ring.
+    if (io_uring_sq_space_left(&io_uring_batch->ring) <
+        (int)request_list.size()) {
+        for (void* buffer : staging_buffers) free(buffer);
+        return Status::TooManyRequests("Insufficient SQE space" LOC_MARK);
+    }
+
+    // Phase 2: commit. Tasks are appended and SQEs prepared; from here on
+    // this call must not return an error. A positive short io_uring_submit()
+    // means part of the batch is already in flight, and an error return
+    // would make the engine's failover re-execute it. Keep flushing the
+    // remainder instead; a persistent failure defers the flush of the
+    // queued SQEs to the next submit attempt from getTransferStatus()'s
+    // PENDING path while the tasks stay PENDING.
+    for (size_t i = 0; i < request_list.size(); ++i) {
+        const auto& request = request_list[i];
+        io_uring_batch->task_list.push_back(IOUringTask{});
+        auto& task =
+            io_uring_batch->task_list[io_uring_batch->task_list.size() - 1];
+        task.request = request;
+        task.status_word = TransferStatusEnum::PENDING;
+        task.buffer = staging_buffers[i];
+        // Vectored ops with a single iovec: IORING_OP_READV/WRITEV have
+        // existed since kernel 5.1, while the non-vectored READ/WRITE
+        // opcodes used by io_uring_prep_read()/io_uring_prep_write() require
+        // kernel 5.6+.
+        task.iov = {task.buffer ? task.buffer : request.source, request.length};
+
+        struct io_uring_sqe* sqe = io_uring_get_sqe(&io_uring_batch->ring);
+        CHECK(sqe) << "SQE space was verified before preparation";
+
+        if (request.opcode == Request::READ) {
+            io_uring_prep_readv(sqe, contexts[i]->getHandle(), &task.iov, 1,
+                                request.target_offset);
+        } else {
+            if (task.buffer)
                 Platform::getLoader().copy(task.buffer, request.source,
                                            request.length);
-                io_uring_prep_write(sqe, context->getHandle(), task.buffer,
-                                    request.length, request.target_offset);
-            }
-        } else {
-            if (request.opcode == Request::READ)
-                io_uring_prep_read(sqe, context->getHandle(), request.source,
-                                   request.length, request.target_offset);
-            else if (request.opcode == Request::WRITE)
-                io_uring_prep_write(sqe, context->getHandle(), request.source,
-                                    request.length, request.target_offset);
+            io_uring_prep_writev(sqe, contexts[i]->getHandle(), &task.iov, 1,
+                                 request.target_offset);
         }
         sqe->user_data = (uintptr_t)&task;
     }
 
-    int rc = io_uring_submit(&io_uring_batch->ring);
-    if (rc != (int32_t)request_list.size())
-        return Status::InternalError(std::string("io_uring_submit failed: ") +
-                                     strerror(-rc) + LOC_MARK);
+    int submitted = 0;
+    int transient_retries = 0;
+    while (submitted < (int)request_list.size()) {
+        int rc = submitSqes(&io_uring_batch->ring);
+        if ((rc == -EINTR || rc == -EAGAIN) && transient_retries++ < 3)
+            continue;
+        if (rc <= 0) {
+            LOG(ERROR) << "IOUringTransport: io_uring_submit "
+                       << (rc < 0 ? strerror(-rc) : "made no progress")
+                       << "; deferring " << request_list.size() - submitted
+                       << " SQE(s) to the poll path";
+            break;
+        }
+        submitted += rc;
+    }
 
     return Status::OK();
 }
@@ -240,6 +294,9 @@ Status IOUringTransport::getTransferStatus(SubBatchRef batch, int task_id,
     auto& task = io_uring_batch->task_list[task_id];
     status = TransferStatus{task.status_word, task.transferred_bytes};
     if (task.status_word == TransferStatusEnum::PENDING) {
+        // Flush SQEs left queued by a deferred submission failure: calling
+        // io_uring_submit() on an empty SQ ring is a no-op.
+        submitSqes(&io_uring_batch->ring);
         struct io_uring_cqe* cqe = nullptr;
         int err = io_uring_peek_cqe(&io_uring_batch->ring, &cqe);
         if (err == -EAGAIN) return Status::OK();
diff --git a/mooncake-transfer-engine/tent/src/transport/mnnvl/mnnvl_transport.cpp b/mooncake-transfer-engine/tent/src/transport/mnnvl/mnnvl_transport.cpp
index 2e869018ea..0aee78d122 100644
--- a/mooncake-transfer-engine/tent/src/transport/mnnvl/mnnvl_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/mnnvl/mnnvl_transport.cpp
@@ -23,6 +23,7 @@
 #include <cstdint>
 #include <iomanip>
 #include <memory>
+#include <unordered_map>
 
 #include <cuda.h>
 #include <cuda_runtime.h>
@@ -61,6 +62,50 @@ static Status roundGranularity(CUmemAllocationProp &prop, size_t granularity,
     return Status::OK();
 }
 
+// Extended GPU Memory (EGM): host DRAM allocated through the CUDA VMM API
+// with a HOST_NUMA location. Such allocations can be exported as fabric
+// handles and read/written by GPUs on other nodes of a multi-node NVLink
+// domain, so host-resident data (e.g. a CPU-side weight or KV cache) moves
+// over NVLink instead of the NIC.
+static Status buildEgmAllocationProp(CUmemAllocationHandleType handle_type,
+                                     CUmemAllocationProp &prop, int numa_node) {
+    prop.type = CU_MEM_ALLOCATION_TYPE_PINNED;
+    prop.location.type = CU_MEM_LOCATION_TYPE_HOST_NUMA;
+    prop.location.id = numa_node;
+    prop.requestedHandleTypes = handle_type;
+    return Status::OK();
+}
+
+// True when `handle` is a host-NUMA (EGM) allocation exportable with
+// `handle_type`; used to tell EGM buffers apart from plain host memory that
+// only supports cudaHostRegister.
+static bool isEgmAllocation(CUmemGenericAllocationHandle handle,
+                            CUmemAllocationHandleType handle_type) {
+    CUmemAllocationProp prop = {};
+    if (cuMemGetAllocationPropertiesFromHandle(&prop, handle) != CUDA_SUCCESS)
+        return false;
+    return prop.location.type == CU_MEM_LOCATION_TYPE_HOST_NUMA &&
+           (prop.requestedHandleTypes & handle_type);
+}
+
+// First CUDA device attached to `numa_node` (-1 when unknown). Copies to or
+// from EGM memory should run on a GPU of the owning socket: the path is
+// bounded by that socket's C2C link, and a GPU on the other socket adds a
+// CPU-to-CPU hop.
+static int findDeviceOnNuma(int numa_node) {
+    if (numa_node < 0) return -1;
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess) return -1;
+    for (int device_id = 0; device_id < device_count; ++device_id) {
+        int host_numa = -1;
+        if (cudaDeviceGetAttribute(&host_numa, cudaDevAttrHostNumaId,
+                                   device_id) == cudaSuccess &&
+            host_numa == numa_node)
+            return device_id;
+    }
+    return -1;
+}
+
 static bool supportFabricMem() {
     int num_devices = 0;
     cudaError_t err = cudaGetDeviceCount(&num_devices);
@@ -83,6 +128,63 @@ static bool supportFabricMem() {
     return true;
 }
 
+namespace {
+
+/// Thread-local cache of one caller-sync event per device. Events are
+/// created lazily and released at thread exit; the destructor restores the
+/// device around each destroy because event teardown must run on the
+/// event's device on some CUDA-compatible runtimes.
+class CallerSyncEventPool {
+   public:
+    cudaEvent_t getOrCreate(int device_id) {
+        auto it = events_.find(device_id);
+        if (it != events_.end()) return it->second;
+        cudaEvent_t event = nullptr;
+        if (cudaEventCreateWithFlags(&event, cudaEventDisableTiming) !=
+            cudaSuccess) {
+            return nullptr;
+        }
+        events_[device_id] = event;
+        return event;
+    }
+    ~CallerSyncEventPool() {
+        int saved_device = 0;
+        cudaGetDevice(&saved_device);
+        for (auto &entry : events_) {
+            cudaSetDevice(entry.first);
+            if (entry.second) cudaEventDestroy(entry.second);
+        }
+        cudaSetDevice(saved_device);
+    }
+
+   private:
+    std::unordered_map<int, cudaEvent_t> events_;
+};
+
+thread_local CallerSyncEventPool tl_caller_sync_events;
+
+/// Waits for producer work already queued on the caller's per-thread stream
+/// so the copy submitted on the transport's internal stream cannot read the
+/// source buffer before that work has executed. CPU-blocking
+/// cudaEventSynchronize mirrors IntraNodeNvlinkTransport and avoids the
+/// expensive cross-device cudaStreamWaitEvent on non-NVIDIA GPUs; it is
+/// complementary to (not a replacement for) the
+/// cudaMemcpySrcAccessOrderStream attribute applied at copy submission.
+Status syncWithCallerStream() {
+    int device_id = 0;
+    CHECK_CUDA(cudaGetDevice(&device_id));
+    cudaEvent_t event = tl_caller_sync_events.getOrCreate(device_id);
+    if (!event) {
+        return Status::InternalError(
+            "unable to create caller-sync event" LOC_MARK);
+    }
+    CHECK_CUDA(cudaEventRecord(event, cudaStreamPerThread));
+    CHECK_CUDA(cudaEventSynchronize(event));
+    return Status::OK();
+}
+
+}  // namespace
+
 MnnvlTransport::MnnvlTransport() : installed_(false) {}
 
 MnnvlTransport::~MnnvlTransport() { uninstall(); }
@@ -125,6 +227,15 @@ Status MnnvlTransport::install(std::string &local_segment_name,
     else
         handle_type_ = CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR;
     host_register_ = conf_->get("transports/nvlink/host_register", true);
+    egm_enabled_ = conf_->get("transports/mnnvl/egm", false);
+    if (egm_enabled_) {
+        // Host buffers allocated through allocateLocalMemory() (or any
+        // HOST_NUMA VMM allocation registered by the caller) are exported
+        // like device memory, so peers can address them directly.
+        caps.dram_to_dram = true;
+        caps.gpu_to_dram = true;
+        LOG(INFO) << "MnnvlTransport: EGM host memory over NVLink enabled";
+    }
     return setPeerAccess();
 }
 
@@ -172,6 +283,12 @@ Status MnnvlTransport::submitTransferTasks(
         mnnvl_batch->max_size)
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
 
+    // Producer work already queued on the caller's per-thread stream must be
+    // visible before the batched copy runs on the transport's internal
+    // stream; without this the copy races with (and can read the source
+    // before) that work. Same contract as IntraNodeNvlinkTransport.
+    CHECK_STATUS(syncWithCallerStream());
+
     // Get local segment for buffer lookup
     auto &segment_manager = metadata_->segmentManager();
     // Owning reference: keeps the snapshot alive while we read through it.
@@ -193,9 +310,13 @@ Status MnnvlTransport::submitTransferTasks(
                 "buffer" LOC_MARK);
         }
 
-        // Parse device ID from buffer location (e.g., "cuda:0" -> 0, "cpu" ->
-        // -1)
-        int device_id = LocationParser(buf->location).index();
+        // Device for the copy stream: the buffer's GPU for "cuda:N"; for host
+        // buffers ("cpu:N") a GPU attached to NUMA node N, so EGM traffic
+        // stays on the owning socket's C2C link (-1 if unknown).
+        LocationParser buf_location(buf->location);
+        int device_id = buf_location.type() == "cuda"
+                            ? buf_location.index()
+                            : findDeviceOnNuma(buf_location.index());
 
         // Capture the first GPU device encountered for stream creation.
         // Mixed-GPU batches use the first GPU's stream and rely on CUDA P2P
@@ -396,19 +517,28 @@ Status MnnvlTransport::getTransferStatus(SubBatchRef batch, int task_id,
 Status MnnvlTransport::addMemoryBuffer(BufferDesc &desc,
                                        const MemoryOptions &options) {
     LocationParser location(desc.location);
-    if (location.type() == "cpu" || location.type() == kWildcardLocation) {
-        if (host_register_) {
-            CHECK_CUDA(cudaHostRegister(((void *)desc.addr), desc.length,
-                                        cudaHostRegisterDefault));
-        }
-        return Status::OK();
-    } else if (location.type() != "cuda")
+    bool is_host =
+        location.type() == "cpu" || location.type() == kWildcardLocation;
+    if (!is_host && location.type() != "cuda")
         return Status::InvalidArgument(
             "Unrecognized location - neither cpu or cuda: " + location.type());
 
     CUmemGenericAllocationHandle handle;
     auto result = cuMemRetainAllocationHandle(&handle, (void *)desc.addr);
-    if (result != CUDA_SUCCESS) {
+    if (is_host) {
+        bool egm = egm_enabled_ && result == CUDA_SUCCESS &&
+                   isEgmAllocation(handle, handle_type_);
+        if (result == CUDA_SUCCESS && !egm) cuMemRelease(handle);
+        if (!egm) {
+            // Plain host memory: usable as the local side of a transfer
+            // (dram_to_gpu) but not addressable by peers.
+            if (host_register_) {
+                CHECK_CUDA(cudaHostRegister(((void *)desc.addr), desc.length,
+                                            cudaHostRegisterDefault));
+            }
+            return Status::OK();
+        }
+    } else if (result != CUDA_SUCCESS) {
         LOG(INFO) << "Memory region " << (void *)desc.addr
                   << "  will not be registered for MNNVL transport.";
         return Status::OK();
@@ -416,23 +546,39 @@ Status MnnvlTransport::addMemoryBuffer(BufferDesc &desc,
 
     CUmemAllocationProp prop = {};
     size_t granularity = 0;
-    CHECK_STATUS(
-        buildCUmemAllocationProp(handle_type_, prop, location.index()));
+    if (is_host) {
+        // EGM buffer: take the properties (NUMA node, handle types) from
+        // the allocation itself; the probed location may be a wildcard.
+        CHECK_CU(cuMemGetAllocationPropertiesFromHandle(&prop, handle));
+    } else {
+        CHECK_STATUS(
+            buildCUmemAllocationProp(handle_type_, prop, location.index()));
+    }
     CHECK_STATUS(roundGranularity(prop, granularity, desc.length));
 
     if (handle_type_ == CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR) {
         int shared_fd;
-        CHECK_CU(
-            cuMemExportToShareableHandle(&shared_fd, handle, handle_type_, 0));
-        desc.mnnvl_handle =
-            std::to_string(getpid()) + "-" + std::to_string(shared_fd);
+        result =
+            cuMemExportToShareableHandle(&shared_fd, handle, handle_type_, 0);
+        if (result == CUDA_SUCCESS)
+            desc.mnnvl_handle =
+                std::to_string(getpid()) + "-" + std::to_string(shared_fd);
     } else {
         CUmemFabricHandle export_handle;
-        CHECK_CU(cuMemExportToShareableHandle(&export_handle, handle,
-                                              handle_type_, 0));
-        desc.mnnvl_handle =
-            serializeBinaryData(&export_handle, sizeof(CUmemFabricHandle));
-    }
+        result = cuMemExportToShareableHandle(&export_handle, handle,
+                                              handle_type_, 0);
+        if (result == CUDA_SUCCESS)
+            desc.mnnvl_handle =
+                serializeBinaryData(&export_handle, sizeof(CUmemFabricHandle));
+    }
+    // The exported handle stays valid for the lifetime of the allocation;
+    // drop the reference taken by cuMemRetainAllocationHandle so the memory
+    // can actually be freed once the buffer is unregistered and released.
+    cuMemRelease(handle);
+    if (result != CUDA_SUCCESS)
+        return Status::InternalError(
+            std::string("cuMemExportToShareableHandle: cuResult ") +
+            std::to_string(result) + LOC_MARK);
 
     void *real_addr;
     size_t real_size;
@@ -453,9 +599,10 @@ Status MnnvlTransport::addMemoryBuffer(BufferDesc &desc,
 }
 
 Status MnnvlTransport::removeMemoryBuffer(BufferDesc &desc) {
+    bool exported = !desc.mnnvl_handle.empty();
     desc.mnnvl_handle.clear();
     LocationParser location(desc.location);
-    if (location.type() == "cpu" && host_register_) {
+    if (location.type() == "cpu" && host_register_ && !exported) {
         CHECK_CUDA(cudaHostUnregister((void *)desc.addr));
     }
     return Status::OK();
@@ -464,14 +611,22 @@ Status MnnvlTransport::removeMemoryBuffer(BufferDesc &desc) {
 Status MnnvlTransport::allocateLocalMemory(void **addr, size_t size,
                                            MemoryOptions &options) {
     LocationParser location(options.location);
-    if (location.type() != "cuda") {
+    bool is_host = location.type() != "cuda";
+    if (is_host && !egm_enabled_) {
         return Platform::getLoader().allocate(addr, size, options);
     }
 
     CUmemAllocationProp prop = {};
     size_t granularity = 0;
-    CHECK_STATUS(
-        buildCUmemAllocationProp(handle_type_, prop, location.index()));
+    int numa_node = -1;
+    if (is_host) {
+        numa_node = location.type() == "cpu" ? location.index() : 0;
+        if (numa_node < 0) numa_node = 0;
+        CHECK_STATUS(buildEgmAllocationProp(handle_type_, prop, numa_node));
+    } else {
+        CHECK_STATUS(
+            buildCUmemAllocationProp(handle_type_, prop, location.index()));
+    }
     CHECK_STATUS(roundGranularity(prop, granularity, size));
 
     CUmemGenericAllocationHandle handle;
@@ -480,8 +635,11 @@ Status MnnvlTransport::allocateLocalMemory(void **addr, size_t size,
     if (result != CUDA_SUCCESS) {
         // return Status::InternalError(std::string("cuMemCreate: ") +
         //                              std::to_string(result) + LOC_MARK);
-        LOG(WARNING) << "Fallback to cudaMalloc because the platform does not "
-                        "support fabric";
+        LOG(WARNING) << "Fallback to "
+                     << (is_host ? "numa_alloc" : "cudaMalloc")
+                     << " because the platform does not support fabric"
+                     << (is_host ? " EGM" : "") << " memory: cuResult "
+                     << result;
         return Platform::getLoader().allocate(addr, size, options);
     }
 
@@ -501,41 +659,74 @@ Status MnnvlTransport::allocateLocalMemory(void **addr, size_t size,
                                      std::to_string(result) + LOC_MARK);
     }
 
-    int device_count;
-    cudaGetDeviceCount(&device_count);
-    CUmemAccessDesc accessDesc[device_count];
+    int device_count = 0;
+    auto cuda_err = cudaGetDeviceCount(&device_count);
+    if (cuda_err != cudaSuccess) {
+        // Teardown order: unmap, release, then free VA range.
+        cuMemUnmap((CUdeviceptr)ptr, size);
+        cuMemRelease(handle);
+        cuMemAddressFree((CUdeviceptr)ptr, size);
+        return Status::InternalError(std::string("cudaGetDeviceCount: ") +
+                                     cudaGetErrorString(cuda_err) + LOC_MARK);
+    }
+    std::vector<CUmemAccessDesc> accessDesc(device_count);
     for (int device_id = 0; device_id < device_count; ++device_id) {
         accessDesc[device_id].location.type = CU_MEM_LOCATION_TYPE_DEVICE;
         accessDesc[device_id].location.id = device_id;
         accessDesc[device_id].flags = CU_MEM_ACCESS_FLAGS_PROT_READWRITE;
     }
+    if (is_host) {
+        // Host memory is filled and consumed by the CPU as well.
+        CUmemAccessDesc host_access = {};
+        host_access.location.type = CU_MEM_LOCATION_TYPE_HOST_NUMA;
+        host_access.location.id = numa_node;
+        host_access.flags = CU_MEM_ACCESS_FLAGS_PROT_READWRITE;
+        accessDesc.push_back(host_access);
+    }
 
-    result = cuMemSetAccess((CUdeviceptr)ptr, size, accessDesc, device_count);
+    result = cuMemSetAccess((CUdeviceptr)ptr, size, accessDesc.data(),
+                            accessDesc.size());
     if (result != CUDA_SUCCESS) {
+        // Teardown order: unmap, release, then free VA range.
         cuMemUnmap((CUdeviceptr)ptr, size);
-        cuMemAddressFree((CUdeviceptr)ptr, size);
         cuMemRelease(handle);
+        cuMemAddressFree((CUdeviceptr)ptr, size);
         return Status::InternalError(std::string("cuMemSetAccess: cuResult ") +
                                      std::to_string(result) + LOC_MARK);
     }
 
+    // The mapping holds its own reference to the physical allocation; drop
+    // the creator reference so freeLocalMemory's unmap + release actually
+    // returns the memory instead of leaking one reference per allocation.
+    result = cuMemRelease(handle);
+    if (result != CUDA_SUCCESS) {
+        LOG(WARNING) << "MnnvlTransport: cuMemRelease after mapping failed: "
+                     << result;
+    }
+
     *addr = ptr;
     std::lock_guard<std::mutex> lock(allocate_mutex_);
-    allocate_set_.insert(*addr);
+    allocate_set_[*addr] = size;
     return Status::OK();
 }
 
 Status MnnvlTransport::freeLocalMemory(void *addr, size_t size) {
     std::lock_guard<std::mutex> lock(allocate_mutex_);
-    if (!allocate_set_.count(addr)) {
+    auto it = allocate_set_.find(addr);
+    if (it == allocate_set_.end()) {
         return Platform::getLoader().free(addr, size);
     }
+    // Use the mapped extent recorded at allocation time: callers pass the
+    // size they requested, which may be smaller than the granularity-rounded
+    // mapping, and cuMemUnmap/cuMemAddressFree need the full range.
+    size_t mapped_size = it->second;
     CUmemGenericAllocationHandle handle;
-    cuMemRetainAllocationHandle(&handle, addr);
-    cuMemUnmap((CUdeviceptr)addr, size);
-    cuMemAddressFree((CUdeviceptr)addr, size);
-    cuMemRelease(handle);
-    allocate_set_.erase(addr);
+    CHECK_CU(cuMemRetainAllocationHandle(&handle, addr));
+    // Teardown order: unmap, release, then free VA range.
+    CHECK_CU(cuMemUnmap((CUdeviceptr)addr, mapped_size));
+    CHECK_CU(cuMemRelease(handle));
+    CHECK_CU(cuMemAddressFree((CUdeviceptr)addr, mapped_size));
+    allocate_set_.erase(it);
     return Status::OK();
 }
 
@@ -608,15 +799,16 @@ Status MnnvlTransport::relocateSharedMemoryAddress(uint64_t &dest_addr,
     if (!relocate_map_[target_id].count(buffer->addr)) {
         CUmemGenericAllocationHandle handle;
         void *mnnvl_addr = nullptr;
-        LocationParser location(buffer->location);
-        if (location.type() != "cuda") {
-            return Status::InvalidArgument(
-                "Requested address is not in registered CUDA buffer" LOC_MARK);
-        }
-
-        int cuda_dev = 0;
-        CHECK_CUDA(cudaGetDevice(&cuda_dev));
-        cudaSetDevice(location.index());
+        // A non-empty mnnvl_handle (checked above) means the peer exported
+        // this buffer, whether it is device memory or EGM host memory.
+
+        // Do NOT switch to buffer->location's device index: that ordinal is
+        // the PEER's device index, relative to the peer's
+        // CUDA_VISIBLE_DEVICES. In the local process it may be an invalid
+        // ordinal, and even when numerically valid it may denote a different
+        // physical GPU. The driver calls below are device-agnostic: the VA
+        // mapping is process-wide and cuMemSetAccess grants read/write
+        // access to ALL local devices.
         if (handle_type_ == CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR) {
             auto [pid, remote_fd] = parsePidFd(buffer->mnnvl_handle);
             int local_fd = importFdFromProcess(pid, remote_fd);
@@ -654,9 +846,10 @@ Status MnnvlTransport::relocateSharedMemoryAddress(uint64_t &dest_addr,
         OpenedMnnvlEntry mnnvl_entry;
         mnnvl_entry.mnnvl_addr = mnnvl_addr;
         mnnvl_entry.length = buffer->length;
-        mnnvl_entry.cuda_id = location.index();
+        int cuda_dev = 0;
+        CHECK_CUDA(cudaGetDevice(&cuda_dev));
+        mnnvl_entry.cuda_id = cuda_dev;
         relocate_map_[target_id][buffer->addr] = mnnvl_entry;
-        cudaSetDevice(cuda_dev);
     }
 
     auto mnnvl_addr = relocate_map_[target_id][buffer->addr].mnnvl_addr;
diff --git a/mooncake-transfer-engine/tent/src/transport/mpcomm/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/mpcomm/CMakeLists.txt
new file mode 100644
index 0000000000..3da79cadcb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/mpcomm/CMakeLists.txt
@@ -0,0 +1,34 @@
+# Copyright 2026 KVCache.AI
+#
+# 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.
+
+# Built in every configuration. Only mpcomm_adapter.cpp includes mpcomm.h, and
+# it compiles to an unavailable stub when the provider is absent; the remaining
+# translation units reach MPComm solely through MpcommAdapter. That is what
+# keeps the TENT-side logic - peer caching, endpoint parsing, request and
+# completion mapping - unit-testable in a build without libmpcomm, the same
+# arrangement TpuPjrtShim and UrmaAdapter use for their providers.
+#
+# When USE_MPCOMM is off the transport is not registered by transport_loader, so
+# these objects are simply never pulled out of the archive.
+add_library(
+  tent_xport_mpcomm STATIC mpcomm_adapter.cpp mpcomm_peer_registry.cpp
+                           mpcomm_task_mapping.cpp mpcomm_transport.cpp)
+target_link_libraries(tent_xport_mpcomm PUBLIC tent_common tent_rpc)
+
+if(USE_MPCOMM)
+  # MPCOMM_INCLUDE_DIR / MPCOMM_LIBRARY are resolved in
+  # mooncake-common/common.cmake.
+  target_include_directories(tent_xport_mpcomm PRIVATE ${MPCOMM_INCLUDE_DIR})
+  target_link_libraries(tent_xport_mpcomm PUBLIC ${MPCOMM_LIBRARY})
+endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_adapter.cpp b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_adapter.cpp
new file mode 100644
index 0000000000..20d50226bc
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_adapter.cpp
@@ -0,0 +1,253 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/mpcomm/mpcomm_adapter.h"
+
+#ifdef USE_MPCOMM
+#include "mpcomm.h"
+#endif
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// The provider's numeric status is kept in the message: MPComm logs the same
+// code, which is how a user correlates a TENT failure with the library's own
+// output.
+Status providerMissing(const char *op) {
+    return Status::InternalError(
+        "MPComm " + std::string(op) +
+        " unavailable: this build was compiled without USE_MPCOMM");
+}
+
+#ifdef USE_MPCOMM
+
+Status providerFailed(const char *op, int code) {
+    return Status::InternalError(
+        "MPComm " + std::string(op) +
+        " failed, provider status=" + std::to_string(code));
+}
+
+// Thin pass-through onto libmpcomm. It adds no locking of its own because
+// MPComm is thread-safe, and no policy: every decision that could be made
+// differently lives above this boundary so that it can be tested there.
+class LibMpcommAdapter final : public MpcommAdapter {
+   public:
+    bool available() const noexcept override { return true; }
+
+    Status init(const std::string &host_id, const std::string &device_names,
+                int tcp_port) override {
+        // Constructed here rather than in the constructor so that merely
+        // creating the transport does not touch the provider, matching the
+        // lifetime the transport had before this boundary existed.
+        impl_ = std::make_unique<mpcomm::MPComm>();
+        int rc = impl_->init(host_id, device_names, tcp_port);
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            impl_.reset();
+            return providerFailed("init", rc);
+        }
+        return Status::OK();
+    }
+
+    int tcpPort() const override { return impl_ ? impl_->getTcpPort() : 0; }
+
+    Status startAcceptThread() override {
+        if (!impl_) return notInitialized("startAcceptThread");
+        int rc = impl_->startAcceptThread();
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            return providerFailed("startAcceptThread", rc);
+        }
+        return Status::OK();
+    }
+
+    void stopAcceptThread() override {
+        if (impl_) impl_->stopAcceptThread();
+    }
+
+    void shutdown() override {
+        if (!impl_) return;
+        impl_->shutdown();
+        impl_.reset();
+    }
+
+    Status registerMemory(void *addr, size_t length) override {
+        if (!impl_) return notInitialized("registerMemory");
+        int rc = impl_->registerMemory(addr, length);
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            return providerFailed("registerMemory", rc);
+        }
+        return Status::OK();
+    }
+
+    void unregisterMemory(void *addr) override {
+        if (impl_) impl_->unregisterMemory(addr);
+    }
+
+    Status publishBuffer(void *addr, size_t length, int numa_node) override {
+        if (!impl_) return notInitialized("publishBuffer");
+        int rc = impl_->publishBuffer(addr, length, numa_node);
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            return providerFailed("publishBuffer", rc);
+        }
+        return Status::OK();
+    }
+
+    void unpublishBuffer(void *addr) override {
+        if (impl_) impl_->unpublishBuffer(addr);
+    }
+
+    Status connect(const std::string &host_id, const std::string &tcp_addr,
+                   int tcp_port) override {
+        if (!impl_) return notInitialized("connect");
+        int rc = impl_->connect(host_id, tcp_addr, tcp_port);
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            return providerFailed("connect", rc);
+        }
+        return Status::OK();
+    }
+
+    Status queryRemoteBuffer(const std::string &host_id,
+                             const std::string &tcp_addr,
+                             int tcp_port) override {
+        if (!impl_) return notInitialized("queryRemoteBuffer");
+        // The provider stores the keys in its own connection record; the
+        // returned description is of no use above this boundary.
+        mpcomm::RemoteBufferInfo unused;
+        int rc = impl_->queryRemoteBuffer(host_id, tcp_addr, tcp_port, unused);
+        if (rc != mpcomm::MPCOMM_SUCCESS) {
+            return providerFailed("queryRemoteBuffer", rc);
+        }
+        return Status::OK();
+    }
+
+    MpcommTransferHandle putAsync(uintptr_t local_addr,
+                                  const std::string &host_id,
+                                  uintptr_t remote_addr,
+                                  size_t length) override {
+        if (!impl_) return kInvalidMpcommTransferHandle;
+        return toHandle(
+            impl_->putAsync(local_addr, host_id, remote_addr, length));
+    }
+
+    MpcommTransferHandle getAsync(uintptr_t local_addr,
+                                  const std::string &host_id,
+                                  uintptr_t remote_addr,
+                                  size_t length) override {
+        if (!impl_) return kInvalidMpcommTransferHandle;
+        return toHandle(
+            impl_->getAsync(local_addr, host_id, remote_addr, length));
+    }
+
+    bool isTransferComplete(MpcommTransferHandle handle) override {
+        if (!impl_ || handle == kInvalidMpcommTransferHandle) return false;
+        return impl_->isTransferComplete(handle);
+    }
+
+    MpcommTransferOutcome getTransferResult(
+        MpcommTransferHandle handle) override {
+        MpcommTransferOutcome outcome;
+        if (!impl_ || handle == kInvalidMpcommTransferHandle) return outcome;
+        auto result = impl_->getTransferResult(handle);
+        outcome.ok = result.error_code == mpcomm::MPCOMM_SUCCESS;
+        outcome.bytes_transferred = result.bytes_transferred;
+        outcome.native_status = result.error_code;
+        return outcome;
+    }
+
+    void releaseTransfer(MpcommTransferHandle handle) override {
+        if (impl_ && handle != kInvalidMpcommTransferHandle) {
+            impl_->releaseTransfer(handle);
+        }
+    }
+
+   private:
+    static Status notInitialized(const char *op) {
+        return Status::InternalError("MPComm " + std::string(op) +
+                                     " called before init()");
+    }
+
+    // MPComm's invalid handle is normalised to this boundary's own, so that
+    // nothing above needs the provider's constant.
+    static MpcommTransferHandle toHandle(mpcomm::TransferHandle handle) {
+        return handle == mpcomm::INVALID_TRANSFER_HANDLE
+                   ? kInvalidMpcommTransferHandle
+                   : static_cast<MpcommTransferHandle>(handle);
+    }
+
+    std::unique_ptr<mpcomm::MPComm> impl_;
+};
+
+#endif  // USE_MPCOMM
+
+// Used when the provider was not compiled in. It keeps a USE_MPCOMM=OFF build
+// linkable and lets the transport report a clear reason instead of failing at
+// an arbitrary later point.
+class UnavailableMpcommAdapter final : public MpcommAdapter {
+   public:
+    bool available() const noexcept override { return false; }
+
+    Status init(const std::string &, const std::string &, int) override {
+        return providerMissing("init");
+    }
+    int tcpPort() const override { return 0; }
+    Status startAcceptThread() override {
+        return providerMissing("startAcceptThread");
+    }
+    void stopAcceptThread() override {}
+    void shutdown() override {}
+
+    Status registerMemory(void *, size_t) override {
+        return providerMissing("registerMemory");
+    }
+    void unregisterMemory(void *) override {}
+    Status publishBuffer(void *, size_t, int) override {
+        return providerMissing("publishBuffer");
+    }
+    void unpublishBuffer(void *) override {}
+
+    Status connect(const std::string &, const std::string &, int) override {
+        return providerMissing("connect");
+    }
+    Status queryRemoteBuffer(const std::string &, const std::string &,
+                             int) override {
+        return providerMissing("queryRemoteBuffer");
+    }
+
+    MpcommTransferHandle putAsync(uintptr_t, const std::string &, uintptr_t,
+                                  size_t) override {
+        return kInvalidMpcommTransferHandle;
+    }
+    MpcommTransferHandle getAsync(uintptr_t, const std::string &, uintptr_t,
+                                  size_t) override {
+        return kInvalidMpcommTransferHandle;
+    }
+    bool isTransferComplete(MpcommTransferHandle) override { return false; }
+    MpcommTransferOutcome getTransferResult(MpcommTransferHandle) override {
+        return MpcommTransferOutcome{};
+    }
+    void releaseTransfer(MpcommTransferHandle) override {}
+};
+
+}  // namespace
+
+std::shared_ptr<MpcommAdapter> createDefaultMpcommAdapter() {
+#ifdef USE_MPCOMM
+    return std::make_shared<LibMpcommAdapter>();
+#else
+    return std::make_shared<UnavailableMpcommAdapter>();
+#endif
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_peer_registry.cpp b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_peer_registry.cpp
new file mode 100644
index 0000000000..b30a1b60bb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_peer_registry.cpp
@@ -0,0 +1,335 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/mpcomm/mpcomm_peer_registry.h"
+
+#include <glog/logging.h>
+
+#include <utility>
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// Fingerprint of a peer's published buffer set, used only as a cheap equality
+// check before the coverage comparison.
+uint64_t computeBuffersEpoch(const std::vector<MpcommBufferRange> &buffers) {
+    uint64_t hash = 1469598103934665603ULL;  // FNV-1a 64-bit offset basis
+    auto mix = [&hash](uint64_t value) {
+        hash ^= value;
+        hash *= 1099511628211ULL;  // FNV-1a 64-bit prime
+    };
+    mix(buffers.size());
+    for (const auto &buffer : buffers) {
+        mix(buffer.addr);
+        mix(buffer.length);
+    }
+    return hash;
+}
+
+// Whether the keys cached for a peer already cover every range the peer is
+// currently observed to publish. Ranges the peer has dropped are ignored: a key
+// for memory that is no longer published is never used.
+bool keysCoverBuffers(const MpcommPeerInfo &peer,
+                      const std::vector<MpcommBufferRange> &buffers) {
+    for (const auto &buffer : buffers) {
+        bool covered = false;
+        for (const auto &range : peer.covered_buffers) {
+            if (range.addr == buffer.addr && range.length == buffer.length) {
+                covered = true;
+                break;
+            }
+        }
+        if (!covered) return false;
+    }
+    return true;
+}
+
+}  // namespace
+
+Status parseMpcommTcpPort(const std::string &text, int &port) {
+    if (text.empty() || text.size() > 5) {
+        return Status::InvalidArgument("MpcommTransport: malformed port '" +
+                                       text + "'");
+    }
+    int value = 0;
+    for (char c : text) {
+        if (c < '0' || c > '9') {
+            return Status::InvalidArgument(
+                "MpcommTransport: non-numeric port '" + text + "'");
+        }
+        value = value * 10 + (c - '0');
+    }
+    if (value <= 0 || value > 65535) {
+        return Status::InvalidArgument("MpcommTransport: port out of range '" +
+                                       text + "'");
+    }
+    port = value;
+    return Status::OK();
+}
+
+Status parseMpcommEndpointAttr(const std::string &attr, std::string &addr,
+                               int &port) {
+    std::string body = attr;
+    // A version prefix is 'v', digits, then a colon. Host names may also begin
+    // with 'v', so require that exact shape before treating it as a version.
+    if (body.size() > 1 && body[0] == 'v') {
+        size_t i = 1;
+        while (i < body.size() && body[i] >= '0' && body[i] <= '9') ++i;
+        if (i > 1 && i < body.size() && body[i] == ':') {
+            if (body.compare(0, i + 1, kMpcommEndpointAttrPrefix) != 0) {
+                return Status::InvalidArgument(
+                    "MpcommTransport: unsupported endpoint attribute '" + attr +
+                    "', this build understands " + kMpcommEndpointAttrPrefix);
+            }
+            body.erase(0, i + 1);
+        }
+    }
+    auto sep = body.rfind(':');
+    if (sep == std::string::npos || sep == 0 || sep + 1 >= body.size()) {
+        return Status::InvalidArgument(
+            "MpcommTransport: malformed endpoint attribute '" + attr + "'");
+    }
+    addr = body.substr(0, sep);
+    if (addr.find(':') != std::string::npos) {
+        // MPComm's handshake sockets are AF_INET, and an IPv6 literal would
+        // additionally need bracket syntax to be unambiguous here.
+        return Status::InvalidArgument(
+            "MpcommTransport: only IPv4 endpoints are supported, got '" + attr +
+            "'");
+    }
+    return parseMpcommTcpPort(body.substr(sep + 1), port);
+}
+
+std::string buildMpcommEndpointAttr(const std::string &local_segment_name,
+                                    int tcp_port) {
+    // The segment name is "host:rpc_port"; only the host part identifies where
+    // this process can be reached, and the port is MPComm's own.
+    std::string host = local_segment_name;
+    auto sep = host.rfind(':');
+    if (sep != std::string::npos) host.erase(sep);
+    return std::string(kMpcommEndpointAttrPrefix) + host + ":" +
+           std::to_string(tcp_port);
+}
+
+MpcommPeerRegistry::MpcommPeerRegistry(std::shared_ptr<MpcommAdapter> adapter)
+    : adapter_(std::move(adapter)) {}
+
+Status MpcommPeerRegistry::ensure(
+    const std::string &host_id, const std::string &tcp_addr, int tcp_port,
+    const std::vector<MpcommBufferRange> &buffers) {
+    const uint64_t buffers_epoch = computeBuffersEpoch(buffers);
+
+    // Fast path: there is nothing to do while the peer is connected and its
+    // keys still describe the buffer set just observed. This runs once per
+    // submitted request, so it stays ahead of everything else.
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = peers_.find(host_id);
+        if (it != peers_.end() && it->second.state == MpcommPeerState::READY &&
+            (it->second.buffers_epoch == buffers_epoch ||
+             keysCoverBuffers(it->second, buffers))) {
+            return Status::OK();
+        }
+    }
+
+    uint64_t my_generation = 0;
+    bool needs_connect = false;
+    std::string endpoint_addr;
+    int endpoint_port = 0;
+
+    {
+        std::unique_lock<std::mutex> lock(mutex_);
+        for (;;) {
+            auto it = peers_.find(host_id);
+            if (it == peers_.end()) {
+                // Never connected: claim the entry and run the full handshake.
+                MpcommPeerInfo entry;
+                entry.tcp_addr = tcp_addr;
+                entry.tcp_port = tcp_port;
+                entry.state = MpcommPeerState::CONNECTING;
+                entry.owner_generation = ++next_generation_;
+                my_generation = entry.owner_generation;
+                endpoint_addr = tcp_addr;
+                endpoint_port = tcp_port;
+                needs_connect = true;
+                peers_.emplace(host_id, std::move(entry));
+                break;
+            }
+            // Keys that already cover the observed ranges are usable whatever
+            // another caller may be doing to this entry: the connection is live
+            // and those keys stay valid, so a refresh in progress must not
+            // block a request that does not need its result.
+            if (it->second.state == MpcommPeerState::READY &&
+                (it->second.buffers_epoch == buffers_epoch ||
+                 keysCoverBuffers(it->second, buffers))) {
+                return Status::OK();
+            }
+            if (it->second.owner_generation != 0) {
+                // Owned by another caller. Re-evaluate once it is done rather
+                // than trusting the outcome: it may have failed and left work.
+                cv_.wait(lock);
+                continue;
+            }
+            // Unowned, and the keys are missing or do not cover what this
+            // request needs. Take ownership of a key refresh over the existing
+            // connection - reconnecting would replace MPComm's record for this
+            // host, dropping the keys it carries and leaking its queue pairs.
+            // Query the endpoint the connection was made to rather than the
+            // newly advertised one, so the keys match the live connection.
+            needs_connect = it->second.state == MpcommPeerState::CONNECTING;
+            endpoint_addr = it->second.tcp_addr;
+            endpoint_port = it->second.tcp_port;
+            if (!needs_connect &&
+                (endpoint_addr != tcp_addr || endpoint_port != tcp_port)) {
+                LOG(WARNING)
+                    << "MpcommTransport: peer " << host_id << " now advertises "
+                    << tcp_addr << ":" << tcp_port
+                    << " but the live connection uses " << endpoint_addr << ":"
+                    << endpoint_port
+                    << "; MPComm cannot replace a connection, so this peer "
+                       "stays reachable only at the old endpoint";
+            }
+            it->second.owner_generation = ++next_generation_;
+            my_generation = it->second.owner_generation;
+            break;
+        }
+    }
+
+    // Every exit that does not publish usable keys has to release ownership, or
+    // later callers would wait on this entry forever. A guard covers early
+    // returns and exceptions alike, which a hand-written cleanup at each return
+    // would not. An established connection is kept rather than dropped: MPComm
+    // cannot close one, so discarding the entry would only cause a reconnect,
+    // which is exactly what has to be avoided.
+    struct PeerGuard {
+        MpcommPeerRegistry *self;
+        const std::string *host;
+        uint64_t generation;
+        bool committed{false};
+        ~PeerGuard() {
+            if (committed) return;
+            bool changed = false;
+            try {
+                std::lock_guard<std::mutex> lock(self->mutex_);
+                auto it = self->peers_.find(*host);
+                // Touch only our own claim: clear() may have emptied the map,
+                // and another caller may already own a newer entry.
+                if (it != self->peers_.end() &&
+                    it->second.owner_generation == generation) {
+                    if (it->second.state == MpcommPeerState::CONNECTING) {
+                        // No connection was established, nothing to keep.
+                        self->peers_.erase(it);
+                    } else {
+                        it->second.owner_generation = 0;
+                    }
+                    changed = true;
+                }
+            } catch (...) {
+                return;  // a destructor must not throw
+            }
+            if (changed) self->cv_.notify_all();
+        }
+    } guard{this, &host_id, my_generation};
+
+    if (needs_connect) {
+        auto status = adapter_->connect(host_id, endpoint_addr, endpoint_port);
+        if (!status.ok()) {
+            LOG(ERROR) << "MpcommTransport: Failed to connect to " << host_id
+                       << " at " << endpoint_addr << ":" << endpoint_port
+                       << ": " << status.ToString();
+            return status;
+        }
+        // Record that the connection now exists before the keys are fetched:
+        // if the query fails, the guard has to keep the connection rather than
+        // erase the entry and let the next caller reconnect.
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            auto it = peers_.find(host_id);
+            if (it != peers_.end() &&
+                it->second.owner_generation == my_generation) {
+                it->second.state = MpcommPeerState::CONNECTED_NO_KEYS;
+            }
+        }
+    }
+
+    // Fetch the peer's memory keys. This is the only source of its rkeys, so
+    // without them every transfer to this peer fails; report the failure rather
+    // than publish an entry that cannot work. The usual cause is a peer that
+    // has not finished registering its buffers, which a retry resolves - a
+    // retry of the query alone, since the entry stays CONNECTED_NO_KEYS.
+    auto status =
+        adapter_->queryRemoteBuffer(host_id, endpoint_addr, endpoint_port);
+    if (!status.ok()) {
+        LOG(ERROR) << "MpcommTransport: Failed to query remote buffers from "
+                   << host_id << ": " << status.ToString();
+        return status;
+    }
+
+    // Publish and release the waiters. Look the entry up rather than inserting
+    // it: if it is gone the registry was cleared while we worked, and
+    // re-creating it would resurrect a stale entry.
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = peers_.find(host_id);
+        if (it == peers_.end() ||
+            it->second.owner_generation != my_generation) {
+            return Status::InternalError(
+                "MpcommTransport: peer entry dropped during handshake");
+        }
+        it->second.state = MpcommPeerState::READY;
+        it->second.owner_generation = 0;
+        it->second.buffers_epoch = buffers_epoch;
+        it->second.covered_buffers = buffers;
+    }
+    guard.committed = true;
+    cv_.notify_all();
+
+    if (needs_connect) {
+        LOG(INFO) << "MpcommTransport: Connected to segment " << host_id
+                  << " at " << endpoint_addr << ":" << endpoint_port;
+    }
+    return Status::OK();
+}
+
+void MpcommPeerRegistry::clear() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        peers_.clear();
+    }
+    // Release anyone blocked waiting for work that will never finish.
+    cv_.notify_all();
+}
+
+size_t MpcommPeerRegistry::size() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return peers_.size();
+}
+
+bool MpcommPeerRegistry::contains(const std::string &host_id) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return peers_.find(host_id) != peers_.end();
+}
+
+bool MpcommPeerRegistry::stateOf(const std::string &host_id,
+                                 MpcommPeerState &state) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = peers_.find(host_id);
+    if (it == peers_.end()) return false;
+    state = it->second.state;
+    return true;
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_task_mapping.cpp b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_task_mapping.cpp
new file mode 100644
index 0000000000..41a2cc9576
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_task_mapping.cpp
@@ -0,0 +1,79 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/mpcomm/mpcomm_task_mapping.h"
+
+#include <glog/logging.h>
+
+namespace mooncake {
+namespace tent {
+
+MpcommTransferHandle issueMpcommTransfer(MpcommAdapter &adapter,
+                                         const Request &request,
+                                         const std::string &host_id) {
+    // MPComm performs its own slicing and NIC/QP selection, so one request maps
+    // onto exactly one provider transfer.
+    auto local_addr = reinterpret_cast<uintptr_t>(request.source);
+    auto remote_addr = static_cast<uintptr_t>(request.target_offset);
+    if (request.opcode == Request::WRITE) {
+        return adapter.putAsync(local_addr, host_id, remote_addr,
+                                request.length);
+    }
+    return adapter.getAsync(local_addr, host_id, remote_addr, request.length);
+}
+
+void pollMpcommTask(MpcommAdapter &adapter, MpcommTask &task) {
+    if (task.status_word != TransferStatusEnum::PENDING ||
+        task.mpcomm_handle == kInvalidMpcommTransferHandle) {
+        return;
+    }
+    if (!adapter.isTransferComplete(task.mpcomm_handle)) return;
+
+    auto outcome = adapter.getTransferResult(task.mpcomm_handle);
+    if (!outcome.ok) {
+        LOG(WARNING) << "MpcommTransport: Transfer failed, provider status="
+                     << outcome.native_status;
+        task.status_word = TransferStatusEnum::FAILED;
+        // The cached peer is deliberately kept even for connection errors:
+        // MPComm has no disconnect API, so a second connect() to the same host
+        // replaces its connection record wholesale, leaking the previous queue
+        // pairs and blanking the remote memory keys that concurrent transfers
+        // are still using. Recovering from a peer restart therefore needs
+        // library support and is left out of this version.
+    } else if (outcome.bytes_transferred < task.request.length) {
+        // Defensive: MPComm only reports success once every chunk has
+        // completed, so this is not expected to trigger. It is kept so that a
+        // future change in the library's success semantics cannot silently
+        // surface a partial copy as a full transfer, which matters because the
+        // engine accumulates request.length for completed tasks. Compared with
+        // '<' rather than '!=': the reported count is a posted-byte count, so
+        // it must never be trusted to be short, but a larger value is not an
+        // error.
+        LOG(WARNING) << "MpcommTransport: Short transfer, "
+                     << outcome.bytes_transferred << " of "
+                     << task.request.length << " bytes";
+        task.transferred_bytes = outcome.bytes_transferred;
+        task.status_word = TransferStatusEnum::FAILED;
+    } else {
+        task.status_word = TransferStatusEnum::COMPLETED;
+        task.transferred_bytes = outcome.bytes_transferred;
+    }
+    // Released on every terminal outcome, and the handle is cleared so that a
+    // repeated poll of the same task cannot release it a second time.
+    adapter.releaseTransfer(task.mpcomm_handle);
+    task.mpcomm_handle = kInvalidMpcommTransferHandle;
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_transport.cpp b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_transport.cpp
new file mode 100644
index 0000000000..49caca49e8
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/mpcomm/mpcomm_transport.cpp
@@ -0,0 +1,454 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/mpcomm/mpcomm_transport.h"
+
+#include <glog/logging.h>
+
+#include <cstdlib>
+#include <fstream>
+#include <utility>
+
+#include "tent/common/config.h"
+#include "tent/common/status.h"
+#include "tent/common/types.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/segment.h"
+#include "tent/runtime/slab.h"
+
+namespace mooncake {
+namespace tent {
+
+// MPComm registers device memory through the standard ibv_reg_mr path and
+// relies on the nvidia-peermem kernel module to pin GPU pages; it has no
+// dma-buf fallback. That is the same dependency RdmaTransport gates its GPU
+// capabilities on, so the same probe is applied here.
+static bool isGpuDirectRdmaSupported(const std::shared_ptr<Config> &conf) {
+    if (conf && conf->get("transports/mpcomm/disable_gpu_direct_rdma", false)) {
+        return false;
+    }
+    std::ifstream modules("/proc/modules");
+    std::string line;
+    while (std::getline(modules, line)) {
+        if (line.find("nvidia_peermem") != std::string::npos) {
+            return true;
+        }
+    }
+    return false;
+}
+
+MpcommTransport::MpcommTransport()
+    : MpcommTransport(createDefaultMpcommAdapter()) {}
+
+MpcommTransport::MpcommTransport(std::shared_ptr<MpcommAdapter> adapter)
+    : adapter_(std::move(adapter)),
+      peers_(std::make_unique<MpcommPeerRegistry>(adapter_)) {}
+
+MpcommTransport::~MpcommTransport() { uninstall(); }
+
+Status MpcommTransport::install(std::string &local_segment_name,
+                                std::shared_ptr<ControlService> metadata,
+                                std::shared_ptr<Topology> local_topology,
+                                std::shared_ptr<Config> conf) {
+    if (installed_) {
+        return Status::InvalidArgument(
+            "MpcommTransport has already been installed" LOC_MARK);
+    }
+    if (!adapter_ || !adapter_->available()) {
+        return Status::InternalError(
+            "MpcommTransport: MPComm provider is not available" LOC_MARK);
+    }
+
+    metadata_ = metadata;
+    local_segment_name_ = local_segment_name;
+    local_topology_ = local_topology;
+
+    // A previous uninstall() may have left entries behind if a handshake was
+    // still running; they refer to connections the provider has torn down.
+    peers_->clear();
+
+    // Resolve the listener port before initialising the provider, so that a
+    // malformed value fails with nothing to unwind. MPComm needs a non-zero
+    // port and does not fall back to an ephemeral one, so a value that atoi()
+    // would quietly turn into 0 has to be rejected rather than used.
+    tcp_port_ = 13579;
+    if (const char *env_port = std::getenv("MPCOMM_TCP_PORT")) {
+        auto status = parseMpcommTcpPort(env_port, tcp_port_);
+        if (!status.ok()) {
+            LOG(ERROR) << "MpcommTransport: invalid MPCOMM_TCP_PORT: "
+                       << status.ToString();
+            return status;
+        }
+    }
+
+    // Extract device names from TENT Topology
+    std::string device_names;
+    if (local_topology_) {
+        bool first = true;
+        for (size_t i = 0; i < local_topology_->nic_list_.size(); ++i) {
+            auto &nic = local_topology_->nic_list_[i];
+            if (nic.type == Topology::NIC_RDMA) {
+                if (!first) device_names += ",";
+                device_names += nic.name;
+                first = false;
+            }
+        }
+    }
+
+    // Initialize mpcomm with local_segment_name as host_id
+    // mpcomm manages its own topology discovery internally
+    auto status = adapter_->init(local_segment_name_, device_names, tcp_port_);
+    if (!status.ok()) {
+        LOG(ERROR) << "MpcommTransport: Failed to initialize mpcomm: "
+                   << status.ToString();
+        uninstall();
+        return status;
+    }
+
+    // Update tcp_port_ with the actual assigned port
+    tcp_port_ = adapter_->tcpPort();
+
+    // Start accept thread for incoming connections
+    status = adapter_->startAcceptThread();
+    if (!status.ok()) {
+        LOG(ERROR) << "MpcommTransport: Failed to start accept thread: "
+                   << status.ToString();
+        uninstall();
+        return status;
+    }
+
+    // MPComm always handles host DRAM. Device memory additionally requires the
+    // nvidia-peermem module (see isGpuDirectRdmaSupported above). Capabilities
+    // feed transport selection, so advertising them unconditionally would let
+    // routing pick MPComm on a host without the module for device memory
+    // published by a peer that has it, where local registration never
+    // succeeded.
+    caps.dram_to_dram = true;
+    if (isGpuDirectRdmaSupported(conf)) {
+        caps.dram_to_gpu = true;
+        caps.gpu_to_dram = true;
+        caps.gpu_to_gpu = true;
+    } else if (conf &&
+               conf->get("transports/mpcomm/disable_gpu_direct_rdma", false)) {
+        LOG(INFO) << "MpcommTransport: GPU memory support disabled by "
+                     "transports/mpcomm/disable_gpu_direct_rdma";
+    } else {
+        LOG(INFO) << "MpcommTransport: nvidia_peermem not detected, GPU memory "
+                     "support is disabled";
+    }
+
+    // Publish mpcomm connection info to segment transport_attrs so remote
+    // peers know how to connect via mpcomm. All mutations of the local
+    // SegmentDesc must go through updateLocal(): snapshots returned by
+    // getLocal() are copy-on-write and must never be written through.
+    {
+        std::string mpcomm_addr =
+            buildMpcommEndpointAttr(local_segment_name_, tcp_port_);
+
+        auto &manager = metadata_->segmentManager();
+        auto publish = manager.updateLocal([&](SegmentDesc &segment) -> Status {
+            auto &detail = std::get<MemorySegmentDesc>(segment.detail);
+            detail.transport_attrs[static_cast<int>(TransportType::MPCOMM)] =
+                mpcomm_addr;
+            return Status::OK();
+        });
+        if (publish.ok()) publish = manager.synchronizeLocal();
+        if (!publish.ok()) {
+            LOG(ERROR) << "MpcommTransport: Failed to publish transport attrs: "
+                       << publish.ToString();
+            uninstall();
+            return publish;
+        }
+    }
+
+    installed_ = true;
+
+    LOG(INFO) << "MpcommTransport: Installed successfully, host_id="
+              << local_segment_name_ << ", tcp_port=" << tcp_port_
+              << ", devices=" << device_names;
+
+    return Status::OK();
+}
+
+Status MpcommTransport::uninstall() {
+    // Tear down unconditionally rather than gating on installed_: install()
+    // may fail after the provider was initialised and its accept thread
+    // started, leaving installed_ false while resources still need releasing.
+    if (adapter_) {
+        adapter_->stopAcceptThread();
+        adapter_->shutdown();
+    }
+
+    // Entries describe connections the provider has just released. Clearing
+    // also wakes anyone waiting on a handshake that will never finish; such a
+    // caller then fails through the adapter, which now reports that the
+    // provider is no longer initialised.
+    if (peers_) peers_->clear();
+
+    installed_ = false;
+    return Status::OK();
+}
+
+Status MpcommTransport::allocateSubBatch(SubBatchRef &batch, size_t max_size) {
+    auto mpcomm_batch = Slab<MpcommSubBatch>::Get().allocate();
+    if (!mpcomm_batch)
+        return Status::InternalError(
+            "Unable to allocate mpcomm sub-batch" LOC_MARK);
+    batch = mpcomm_batch;
+    mpcomm_batch->task_list.reserve(max_size);
+    mpcomm_batch->max_size = max_size;
+    return Status::OK();
+}
+
+Status MpcommTransport::freeSubBatch(SubBatchRef &batch) {
+    auto mpcomm_batch = dynamic_cast<MpcommSubBatch *>(batch);
+    if (!mpcomm_batch)
+        return Status::InvalidArgument("Invalid mpcomm sub-batch" LOC_MARK);
+
+    // Handles are released in getTransferStatus() once a transfer reaches a
+    // terminal state. Do not call into MPComm from here: the engine documents
+    // that freeSubBatch() must not touch transport-internal state, and that
+    // callers ensure no transfer is in flight. A non-zero handle at this point
+    // means the transfer was not drained; the handle is reclaimed when MPComm
+    // shuts down. Logged as a warning rather than an error because the engine
+    // frees active batches during teardown without draining them first.
+    for (auto &task : mpcomm_batch->task_list) {
+        if (task.mpcomm_handle != kInvalidMpcommTransferHandle) {
+            LOG(WARNING) << "MpcommTransport: sub-batch freed while a transfer "
+                            "is still in flight (handle="
+                         << task.mpcomm_handle << ")";
+        }
+    }
+
+    Slab<MpcommSubBatch>::Get().deallocate(mpcomm_batch);
+    batch = nullptr;
+    return Status::OK();
+}
+
+Status MpcommTransport::submitTransferTasks(
+    SubBatchRef batch, const std::vector<Request> &request_list) {
+    if (!installed_ || !adapter_) {
+        return Status::InternalError(
+            "MpcommTransport: mpcomm not initialized" LOC_MARK);
+    }
+
+    auto mpcomm_batch = dynamic_cast<MpcommSubBatch *>(batch);
+    if (!mpcomm_batch)
+        return Status::InvalidArgument("Invalid mpcomm sub-batch" LOC_MARK);
+    if (request_list.size() + mpcomm_batch->task_list.size() >
+        mpcomm_batch->max_size)
+        return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
+
+    // Pre-allocate task slots to avoid vector reallocation during the loop,
+    // which would invalidate pointers/references to earlier tasks.
+    size_t base_index = mpcomm_batch->task_list.size();
+    mpcomm_batch->task_list.resize(base_index + request_list.size());
+
+    for (size_t i = 0; i < request_list.size(); ++i) {
+        auto &request = request_list[i];
+        size_t task_index = base_index + i;
+        auto &task = mpcomm_batch->task_list[task_index];
+        task.request = request;
+        task.status_word = TransferStatusEnum::PENDING;
+        task.transferred_bytes = 0;
+        task.mpcomm_handle = kInvalidMpcommTransferHandle;
+
+        // Resolve the remote host_id from SegmentID
+        std::string remote_host_id;
+        auto status = ensurePeerConnected(request.target_id, remote_host_id);
+        if (!status.ok()) {
+            LOG(ERROR) << "MpcommTransport: Failed to connect to target "
+                       << request.target_id << ": " << status.ToString();
+            task.status_word = TransferStatusEnum::FAILED;
+            continue;
+        }
+
+        task.mpcomm_handle =
+            issueMpcommTransfer(*adapter_, request, remote_host_id);
+        if (task.mpcomm_handle == kInvalidMpcommTransferHandle) {
+            LOG(ERROR) << "MpcommTransport: Async transfer failed for "
+                       << (request.opcode == Request::WRITE ? "WRITE" : "READ")
+                       << " to " << remote_host_id;
+            task.status_word = TransferStatusEnum::FAILED;
+        }
+    }
+
+    return Status::OK();
+}
+
+Status MpcommTransport::getTransferStatus(SubBatchRef batch, int task_id,
+                                          TransferStatus &status) {
+    auto mpcomm_batch = dynamic_cast<MpcommSubBatch *>(batch);
+    if (!mpcomm_batch)
+        return Status::InvalidArgument("Invalid mpcomm sub-batch" LOC_MARK);
+    if (task_id < 0 || task_id >= (int)mpcomm_batch->task_list.size()) {
+        return Status::InvalidArgument("Invalid task id" LOC_MARK);
+    }
+    auto &task = mpcomm_batch->task_list[task_id];
+
+    if (task.status_word == TransferStatusEnum::PENDING &&
+        task.mpcomm_handle != kInvalidMpcommTransferHandle) {
+        if (!installed_ || !adapter_) {
+            // uninstall() ran with this transfer still outstanding, so its
+            // outcome can no longer be learned. Fail it rather than leave the
+            // caller polling a task that can never reach a terminal state.
+            LOG(WARNING) << "MpcommTransport: transfer abandoned, transport "
+                            "was uninstalled";
+            task.status_word = TransferStatusEnum::FAILED;
+            task.mpcomm_handle = kInvalidMpcommTransferHandle;
+        } else {
+            // Lazy poll: check mpcomm completion status on demand.
+            pollMpcommTask(*adapter_, task);
+        }
+    }
+
+    status.s = task.status_word;
+    status.transferred_bytes = task.transferred_bytes;
+    return Status::OK();
+}
+
+Status MpcommTransport::addMemoryBuffer(BufferDesc &desc,
+                                        const MemoryOptions &options) {
+    if (!installed_ || !adapter_) {
+        return Status::InternalError(
+            "MpcommTransport: mpcomm not initialized" LOC_MARK);
+    }
+
+    void *addr = reinterpret_cast<void *>(desc.addr);
+    size_t length = desc.length;
+
+    auto status = adapter_->registerMemory(addr, length);
+    if (!status.ok()) {
+        LOG(ERROR) << "MpcommTransport: Failed to register memory at " << addr
+                   << " length=" << length << ": " << status.ToString();
+        return status;
+    }
+
+    // Publish buffer so remote peers can discover it
+    // mpcomm handles NUMA awareness internally
+    int numa_node = -1;  // Auto-detect
+    status = adapter_->publishBuffer(addr, length, numa_node);
+    if (!status.ok()) {
+        LOG(ERROR) << "MpcommTransport: Failed to publish buffer: "
+                   << status.ToString();
+        adapter_->unregisterMemory(addr);
+        return status;
+    }
+
+    // Mark this buffer as using MPCOMM transport
+    desc.transports.push_back(TransportType::MPCOMM);
+
+    return Status::OK();
+}
+
+Status MpcommTransport::removeMemoryBuffer(BufferDesc &desc) {
+    if (!installed_ || !adapter_) return Status::OK();
+
+    void *addr = reinterpret_cast<void *>(desc.addr);
+
+    // Unpublish and unregister from mpcomm
+    adapter_->unpublishBuffer(addr);
+    adapter_->unregisterMemory(addr);
+
+    return Status::OK();
+}
+
+Status MpcommTransport::ensurePeerConnected(SegmentID target_id,
+                                            std::string &host_id) {
+    // Pin the snapshot. getLocal() returns the owning reference by value, and
+    // the raw-pointer form of getRemoteCached() hands out a pointer into a
+    // per-thread snapshot cache; either pointer outlives its guarantee once the
+    // reference is dropped or the cache is refreshed. SegmentManager offers
+    // owning variants for exactly this, and the descriptor is read throughout
+    // this function, so hold the reference rather than a bare pointer.
+    SegmentDescRef desc_ref;
+    if (target_id == LOCAL_SEGMENT_ID) {
+        desc_ref = metadata_->segmentManager().getLocal();
+    } else {
+        auto status =
+            metadata_->segmentManager().getRemoteCached(desc_ref, target_id);
+        if (!status.ok()) {
+            return Status::InvalidArgument(
+                "MpcommTransport: Cannot find segment descriptor for sid=" +
+                std::to_string(target_id));
+        }
+    }
+    SegmentDesc *desc = desc_ref.get();
+    if (!desc) {
+        return Status::InvalidArgument(
+            "MpcommTransport: Null segment descriptor for sid=" +
+            std::to_string(target_id));
+    }
+    if (desc->type != SegmentType::Memory) {
+        // getMemory() would throw on a file segment. MPComm advertises no file
+        // capability, so reaching here means a selection bug upstream.
+        return Status::InvalidArgument(
+            "MpcommTransport: Not a memory segment, sid=" +
+            std::to_string(target_id));
+    }
+
+    // The segment name serves as the remote host_id
+    const std::string remote_host_id = desc->name;
+    const auto &mem_desc = desc->getMemory();
+
+    std::string advertised_addr;
+    int advertised_port = 0;
+    const auto *attr =
+        mem_desc.getTransportAttrs(static_cast<int>(TransportType::MPCOMM));
+    if (attr && !attr->empty()) {
+        auto status =
+            parseMpcommEndpointAttr(*attr, advertised_addr, advertised_port);
+        if (!status.ok()) return status;
+    } else {
+        // install() publishes this attribute, so its absence means the peer
+        // runs no MPComm transport. Deriving a port from our own would hand
+        // connect() an endpoint owned by an unrelated process, and MPComm's
+        // handshake has no timeout, so a wrong guess can block the submitting
+        // thread indefinitely. Require an explicit override instead.
+        const char *env_port = std::getenv("MPCOMM_REMOTE_TCP_PORT");
+        if (!env_port) {
+            return Status::InvalidArgument("MpcommTransport: segment " +
+                                           remote_host_id +
+                                           " publishes no mpcomm endpoint");
+        }
+        auto status = parseMpcommTcpPort(env_port, advertised_port);
+        if (!status.ok()) return status;
+        advertised_addr = remote_host_id;
+        auto sep = advertised_addr.rfind(':');
+        if (sep != std::string::npos) advertised_addr.erase(sep);
+        LOG(WARNING) << "MpcommTransport: segment " << remote_host_id
+                     << " publishes no mpcomm endpoint, using "
+                     << advertised_addr << ":" << advertised_port
+                     << " from MPCOMM_REMOTE_TCP_PORT";
+    }
+
+    // Reused per thread: this runs once per submitted request, so a fresh
+    // vector here would allocate on every transfer.
+    thread_local std::vector<MpcommBufferRange> buffers;
+    buffers.clear();
+    buffers.reserve(mem_desc.buffers.size());
+    for (const auto &buffer : mem_desc.buffers) {
+        buffers.push_back({buffer.addr, buffer.length});
+    }
+
+    auto status = peers_->ensure(remote_host_id, advertised_addr,
+                                 advertised_port, buffers);
+    if (!status.ok()) return status;
+
+    host_id = remote_host_id;
+    return Status::OK();
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/nvlink/nvlink_transport.cpp b/mooncake-transfer-engine/tent/src/transport/nvlink/nvlink_transport.cpp
index f3de90d7f3..c75d294103 100644
--- a/mooncake-transfer-engine/tent/src/transport/nvlink/nvlink_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/nvlink/nvlink_transport.cpp
@@ -24,6 +24,7 @@
 #include <cstdint>
 #include <iomanip>
 #include <memory>
+#include <unordered_map>
 
 #include "tent/common/status.h"
 #include "tent/runtime/slab.h"
@@ -54,6 +55,59 @@ Status restoreCudaDeviceForLocation(const LocationParser& location,
     return Status::OK();
 }
 
+/// Thread-local cache of one caller-sync event per device. Events are
+/// created lazily and released at thread exit; the destructor restores the
+/// device around each destroy because event teardown must run on the
+/// event's device on some CUDA-compatible runtimes.
+class CallerSyncEventPool {
+   public:
+    cudaEvent_t getOrCreate(int device_id) {
+        auto it = events_.find(device_id);
+        if (it != events_.end()) return it->second;
+        cudaEvent_t event = nullptr;
+        if (cudaEventCreateWithFlags(&event, cudaEventDisableTiming) !=
+            cudaSuccess) {
+            return nullptr;
+        }
+        events_[device_id] = event;
+        return event;
+    }
+    ~CallerSyncEventPool() {
+        int saved_device = 0;
+        cudaGetDevice(&saved_device);
+        for (auto& entry : events_) {
+            cudaSetDevice(entry.first);
+            if (entry.second) cudaEventDestroy(entry.second);
+        }
+        cudaSetDevice(saved_device);
+    }
+
+   private:
+    std::unordered_map<int, cudaEvent_t> events_;
+};
+
+thread_local CallerSyncEventPool tl_caller_sync_events;
+
+/// Waits for producer work already queued on the caller's per-thread stream
+/// so the copy submitted on the transport's internal stream cannot read the
+/// source buffer before that work has executed. CPU-blocking
+/// cudaEventSynchronize mirrors IntraNodeNvlinkTransport and avoids the
+/// expensive cross-device cudaStreamWaitEvent on non-NVIDIA GPUs; it is
+/// complementary to (not a replacement for) the
+/// cudaMemcpySrcAccessOrderStream attribute applied at copy submission.
+Status syncWithCallerStream() {
+    int device_id = 0;
+    CHECK_CUDA(cudaGetDevice(&device_id));
+    cudaEvent_t event = tl_caller_sync_events.getOrCreate(device_id);
+    if (!event) {
+        return Status::InternalError(
+            "unable to create caller-sync event" LOC_MARK);
+    }
+    CHECK_CUDA(cudaEventRecord(event, cudaStreamPerThread));
+    CHECK_CUDA(cudaEventSynchronize(event));
+    return Status::OK();
+}
+
 }  // namespace
 
 NVLinkTransport::NVLinkTransport() : installed_(false) {}
@@ -132,6 +186,12 @@ Status NVLinkTransport::submitTransferTasks(
     if (request_list.size() + shm_batch->task_list.size() > shm_batch->max_size)
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
 
+    // Producer work already queued on the caller's per-thread stream must be
+    // visible before the batched copy runs on the transport's internal
+    // stream; without this the copy races with (and can read the source
+    // before) that work. Same contract as IntraNodeNvlinkTransport.
+    CHECK_STATUS(syncWithCallerStream());
+
     // Get local segment for buffer lookup
     auto& segment_manager = metadata_->segmentManager();
     // Owning reference: keeps the snapshot alive while we read through it.
@@ -142,12 +202,21 @@ Status NVLinkTransport::submitTransferTasks(
     // Determine device for this batch and validate all requests
     int batch_device_id = -1;
     std::vector<NVLinkTask*> new_tasks;
+    // No I/O is started until startTransfer() below, so a synchronous
+    // failure must also roll back the half-appended task entries: the engine
+    // fails such tasks over to another transport, and stale never-started
+    // entries must not linger in the sub-batch (failover.md, hazard 2).
+    const size_t original_task_count = shm_batch->task_list.size();
+    auto rollback_tasks = [&shm_batch, original_task_count]() {
+        shm_batch->task_list.resize(original_task_count);
+    };
 
     for (auto& request : request_list) {
         // Find the buffer this source pointer belongs to
         BufferDesc* buf = local_segment->findBuffer(
             reinterpret_cast<uint64_t>(request.source), request.length);
         if (!buf) {
+            rollback_tasks();
             return Status::InvalidArgument(
                 "Unregistered buffer: source pointer not in any registered "
                 "buffer" LOC_MARK);
@@ -174,7 +243,10 @@ Status NVLinkTransport::submitTransferTasks(
         if (request.target_id != LOCAL_SEGMENT_ID) {
             auto status = relocateSharedMemoryAddress(
                 target_addr, request.length, request.target_id);
-            if (!status.ok()) return status;
+            if (!status.ok()) {
+                rollback_tasks();
+                return status;
+            }
         }
 
         task.target_addr = target_addr;
@@ -190,10 +262,16 @@ Status NVLinkTransport::submitTransferTasks(
             // CPU-only batch: use current CUDA device
             cudaGetDevice(&stream_device);
         }
-        CHECK_STATUS(platform_->getStreamFromPool(shm_batch->sync_stream,
-                                                  stream_device));
-        CHECK_STATUS(platform_->getStreamFromPool(shm_batch->async_stream,
-                                                  stream_device));
+        auto status =
+            platform_->getStreamFromPool(shm_batch->sync_stream, stream_device);
+        if (status.ok()) {
+            status = platform_->getStreamFromPool(shm_batch->async_stream,
+                                                  stream_device);
+        }
+        if (!status.ok()) {
+            rollback_tasks();
+            return status;
+        }
         shm_batch->stream_device_id = stream_device;
     }
 
@@ -396,10 +474,18 @@ Status NVLinkTransport::addMemoryBuffer(BufferDesc& desc,
 
         {
             std::lock_guard<std::mutex> lock(register_mutex_);
-            if (registered_base_addrs_.count((uint64_t)base_ptr)) {
-                // Already registered this cudaMalloc block, just tag transport
+            auto iter = registered_base_addrs_.find((uint64_t)base_ptr);
+            if (iter != registered_base_addrs_.end()) {
+                // Already registered this cudaMalloc block: expand to the
+                // segment granularity and REUSE its IPC handle. The handle
+                // must be stamped on this desc too -- torch's caching
+                // allocator sub-allocates many logical buffers (KV pool, aux
+                // pool, mamba state pool, ...) inside one cudaMalloc segment,
+                // and every desc covering the segment needs the handle or
+                // cross-process NVLink submission for that buffer fails.
                 desc.addr = (uint64_t)base_ptr;
                 desc.length = alloc_size;
+                desc.shm_path = iter->second;
                 desc.transports.push_back(TransportType::NVLINK);
                 CHECK_STATUS(restoreCudaDeviceForLocation(location, saved_dev));
                 return Status::OK();
@@ -426,7 +512,7 @@ Status NVLinkTransport::addMemoryBuffer(BufferDesc& desc,
 
         {
             std::lock_guard<std::mutex> lock(register_mutex_);
-            registered_base_addrs_.insert((uint64_t)base_ptr);
+            registered_base_addrs_.emplace((uint64_t)base_ptr, desc.shm_path);
         }
     } else if (location.type() == "cpu" ||
                location.type() == kWildcardLocation) {
@@ -505,9 +591,26 @@ Status NVLinkTransport::relocateSharedMemoryAddress(uint64_t& dest_addr,
     CHECK_STATUS(segment_manager.withCachedSegment(
         target_id, pin, [&](SegmentDesc* segment) {
             buffer = segment->findBuffer(dest_addr, length);
-            if (!buffer || buffer->shm_path.empty())
+            if (!buffer) {
+                LOG_EVERY_N(WARNING, 1000)
+                    << "NVLink relocation: no buffer covers target_addr=0x"
+                    << std::hex << dest_addr << std::dec << " length=" << length
+                    << " in segment " << target_id;
                 return Status::NeedsRefreshCache(
                     "Requested address is not in registered buffer" LOC_MARK);
+            }
+            if (buffer->shm_path.empty()) {
+                // cudaMalloc-segment dedup used to drop the IPC handle for
+                // every desc after the first one in the same segment; this
+                // log is the fingerprint of that (fixed) bug.
+                LOG_EVERY_N(WARNING, 1000)
+                    << "NVLink relocation: target buffer at 0x" << std::hex
+                    << buffer->addr << std::dec
+                    << " (location=" << buffer->location
+                    << ") has no CUDA IPC handle; NVLink unavailable for it";
+                return Status::NeedsRefreshCache(
+                    "Requested address is not in registered buffer" LOC_MARK);
+            }
             return Status::OK();
         }));
 
@@ -515,6 +618,9 @@ Status NVLinkTransport::relocateSharedMemoryAddress(uint64_t& dest_addr,
         void* shm_addr = nullptr;
         LocationParser location(buffer->location);
         if (location.type() != "cuda") {
+            LOG_EVERY_N(WARNING, 1000)
+                << "NVLink relocation: target buffer location "
+                << buffer->location << " is not cuda; NVLink unavailable";
             return Status::InvalidArgument(
                 "Requested address is not in registered CUDA buffer" LOC_MARK);
         }
@@ -522,16 +628,24 @@ Status NVLinkTransport::relocateSharedMemoryAddress(uint64_t& dest_addr,
         deserializeBinaryData(buffer->shm_path, output_buffer);
         cudaIpcMemHandle_t handle;
         memcpy(&handle, output_buffer.data(), sizeof(handle));
+        // Open the IPC handle on the CALLER's current device. Never switch to
+        // buffer->location's device index: that ordinal is the PEER's device
+        // index, relative to the peer's CUDA_VISIBLE_DEVICES. In the local
+        // process it may be an invalid ordinal (when the peer process sees
+        // more devices than we do), and even when numerically valid it may
+        // denote a different physical GPU. cudaIpcOpenMemHandle with
+        // cudaIpcMemLazyEnablePeerAccess is valid on the current device: the
+        // lazy flag enables peer access between the current device and the
+        // allocation's source device as needed, and subsequent copies already
+        // run cross-device via P2P (see startTransfer).
         int cuda_dev = 0;
         CHECK_CUDA(cudaGetDevice(&cuda_dev));
-        cudaSetDevice(location.index());
         CHECK_CUDA(cudaIpcOpenMemHandle(&shm_addr, handle,
                                         cudaIpcMemLazyEnablePeerAccess));
-        cudaSetDevice(cuda_dev);
         OpenedShmEntry shm_entry;
         shm_entry.shm_addr = shm_addr;
         shm_entry.length = buffer->length;
-        shm_entry.cuda_id = location.index();
+        shm_entry.cuda_id = cuda_dev;
         relocate_map_[target_id][buffer->addr] = shm_entry;
         tl_relocate_map = relocate_map_;
     }
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/context.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/context.cpp
index d96081dc6f..b5a3fea913 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/context.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/context.cpp
@@ -18,8 +18,12 @@
 #include <fcntl.h>
 #include <limits.h>
 #include <sys/epoll.h>
+#include <sys/mman.h>
 #include <sys/stat.h>
 #include <unistd.h>
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
 
 #include <atomic>
 #include <cassert>
@@ -34,6 +38,7 @@
 #include <cuda_runtime.h>
 #endif
 
+#include "ib_link_speed.h"
 #include "tent/common/status.h"
 #include "tent/transport/rdma/endpoint_store.h"
 
@@ -193,6 +198,7 @@ static inline std::string gidBytesToString(const uint8_t* raw) {
 // 3) RoCEv2/IB + no network device
 // 4) first non-zero GID (any type)
 static inline GidNetworkState getBestGidIndex(const std::string& device_name,
+                                              const IbvSymbols& verbs,
                                               struct ibv_context* context,
                                               ibv_port_attr& port_attr,
                                               uint8_t port, int& gid_index) {
@@ -208,7 +214,7 @@ static inline GidNetworkState getBestGidIndex(const std::string& device_name,
             << device_name << " port " << (int)port;
 
     for (i = 0; i < port_attr.gid_tbl_len; i++) {
-        if (ibv_query_gid_ex(context, port, i, &gid_entry, 0)) {
+        if (QueryGidEx(verbs, context, port, i, &gid_entry)) {
             continue;  // Skip invalid GID entries
         }
 
@@ -301,9 +307,7 @@ RdmaContext::RdmaContext(RdmaTransport& transport)
     std::call_once(g_once_flag, fork_init);
 }
 
-RdmaContext::~RdmaContext() {
-    if (status_ != DEVICE_UNINIT) disable();
-}
+RdmaContext::~RdmaContext() { disable(); }
 
 int RdmaContext::construct(const std::string& device_name,
                            std::shared_ptr<RdmaParams> params) {
@@ -320,10 +324,15 @@ int RdmaContext::construct(const std::string& device_name,
 }
 
 int RdmaContext::enable() {
-    if (status_ != DEVICE_DISABLED) {
+    if (status_ == DEVICE_ENABLED || status_ == DEVICE_PAUSED) {
         LOG(WARNING) << "RDMA context " << name() << " has been enabled";
         return 0;
     }
+    if (status_ != DEVICE_DISABLED) {
+        LOG(ERROR) << "RDMA context " << name() << " cannot be enabled from "
+                   << statusToString(status_);
+        return -1;
+    }
     if (openDevice(device_name_, params_->device.port)) {
         LOG(ERROR) << "Failed to open device [" << device_name_ << "] on port ["
                    << params_->device.port << "] with GID index ["
@@ -369,13 +378,13 @@ int RdmaContext::enable() {
     }
 
     for (int i = 0; i < params_->device.num_cq_list; ++i) {
-        auto cq = new RdmaCQ();
+        auto cq = std::make_unique<RdmaCQ>();
         int ret = cq->construct(this, params_->device.max_cqe, i);
         if (ret) {
             disable();
             return ret;
         }
-        cq_list_.push_back(cq);
+        cq_list_.push_back(cq.release());
     }
 
     // Create dedicated notification CQ
@@ -419,9 +428,7 @@ int RdmaContext::enable() {
     if (ret) {
         PLOG(ERROR) << "Failed to query port " << params_->device.port << " on "
                     << device_name_;
-        if (verbs_.ibv_close_device(native_context_)) {
-            PLOG(ERROR) << "ibv_close_device";
-        }
+        disable();
         return -1;
     }
 
@@ -439,21 +446,31 @@ int RdmaContext::enable() {
 }
 
 int RdmaContext::disable() {
-    if (status_ == DEVICE_UNINIT || status_ == DEVICE_DISABLED) {
+    if (!native_context_ && !native_pd_ && event_fd_ < 0 &&
+        comp_channel_.empty() && cq_list_.empty() && !notify_cq_) {
         LOG(WARNING) << "RDMA context " << name() << " has been deconstructed";
         return 0;
     }
-    if (endpoint_store_->clear()) {
+    if (endpoint_store_ && endpoint_store_->clear()) {
         LOG(ERROR) << "Failed to destroy all endpoints for context " << name()
                    << "; preserving CQ, PD and device resources for retry";
         return -1;
     }
 
-    for (auto& entry : mr_set_) {
-        int ret = verbs_.ibv_dereg_mr(entry);
-        if (ret) PLOG(ERROR) << "ibv_dereg_mr";
+    cleanupResources();
+    status_ = DEVICE_DISABLED;
+    return 0;
+}
+
+void RdmaContext::cleanupResources() {
+    {
+        std::lock_guard<std::mutex> lock(mr_set_mutex_);
+        for (auto& entry : mr_set_) {
+            int ret = verbs_.ibv_dereg_mr(entry);
+            if (ret) PLOG(ERROR) << "ibv_dereg_mr";
+        }
+        mr_set_.clear();
     }
-    mr_set_.clear();
     for (auto& entry : cq_list_) {
         delete entry;
     }
@@ -486,21 +503,36 @@ int RdmaContext::disable() {
             PLOG(ERROR) << "ibv_close_device";
         native_context_ = nullptr;
     }
-
-    status_ = DEVICE_DISABLED;
-    return 0;
 }
 
 int RdmaContext::pause() {
     DeviceStatus expected = DEVICE_ENABLED;
-    status_.compare_exchange_strong(expected, DEVICE_PAUSED);
-    return (expected == DEVICE_PAUSED) ? 0 : -1;
+    if (status_.compare_exchange_strong(expected, DEVICE_PAUSED,
+                                        std::memory_order_acq_rel,
+                                        std::memory_order_acquire)) {
+        return 0;
+    }
+    // Pausing is idempotent. Other states (UNINIT/DISABLED) must not proceed
+    // into hardware reprobe or metadata publication.
+    return expected == DEVICE_PAUSED ? 0 : -1;
+}
+
+void RdmaContext::evictEndpoints() {
+    if (endpoint_store_) endpoint_store_->evictAll();
 }
 
 int RdmaContext::resume() {
+    if (status_.load(std::memory_order_acquire) != DEVICE_PAUSED) return -1;
+    // Keep the context paused while old QPs are retired. Publishing ENABLED
+    // first lets a concurrent bootstrap reuse an EP_READY endpoint from the
+    // previous address generation.
+    evictEndpoints();
     DeviceStatus expected = DEVICE_PAUSED;
-    status_.compare_exchange_strong(expected, DEVICE_ENABLED);
-    return (expected == DEVICE_ENABLED) ? 0 : -1;
+    return status_.compare_exchange_strong(expected, DEVICE_ENABLED,
+                                           std::memory_order_release,
+                                           std::memory_order_relaxed)
+               ? 0
+               : -1;
 }
 
 RdmaContext::MemReg RdmaContext::registerMemReg(void* addr, size_t length,
@@ -612,28 +644,123 @@ int RdmaContext::unregisterMemReg(MemReg id) {
         return -1;
     }
     auto entry = (ibv_mr*)id;
+    // Cache addr/length before ibv_dereg_mr: entry is freed by dereg_mr, so
+    // reading entry->addr/entry->length afterwards is a use-after-free.
+    void* region_addr = entry->addr;
+    size_t region_length = entry->length;
     mr_set_mutex_.lock();
     mr_set_.erase(entry);
     mr_set_mutex_.unlock();
 
     if (verbs_.ibv_dereg_mr(entry)) {
-        const void* end = static_cast<const char*>(entry->addr) + entry->length;
-        LOG(ERROR) << "Failed to unregister memory from " << entry->addr
+        const void* end = static_cast<const char*>(region_addr) + region_length;
+        LOG(ERROR) << "Failed to unregister memory from " << region_addr
                    << " to " << end << " in RDMA device " << device_name_;
+        return -1;
+    }
+    // Restore mergeability after ibv_dereg_mr. ibv_reg_mr calls
+    // madvise(MADV_DONTFORK) on the registered range when fork protection
+    // is active; failing to undo this on unregister leaves VMAs permanently
+    // split, exhausting vm.max_map_count under high register/unregister churn.
+    // See issue #3639.
+    if (madvise(region_addr, region_length, MADV_DOFORK) != 0) {
+        PLOG(WARNING) << "Failed to restore fork state for memory region at "
+                      << region_addr << " (" << region_length
+                      << " bytes), deregister already succeeded";
     }
 
     return 0;
 }
 
-std::string RdmaContext::gid() const {
-    std::string gid_str;
-    char buf[16] = {0};
-    const static size_t kGidLength = 16;
-    for (size_t i = 0; i < kGidLength; ++i) {
-        sprintf(buf, "%02x", gid_.raw[i]);
-        gid_str += i == 0 ? buf : std::string(":") + buf;
+RdmaAddressSnapshot RdmaContext::address() const {
+    std::lock_guard<std::mutex> guard(address_mutex_);
+    return {lid_, gidBytesToString(gid_.raw), gid_index_};
+}
+
+RdmaAddressRefreshResult RdmaContext::refreshAddress(
+    RdmaAddressSnapshot* previous, RdmaAddressSnapshot* current) {
+    std::lock_guard<std::mutex> refresh_guard(address_refresh_mutex_);
+    const auto old_address = address();
+    if (previous) *previous = old_address;
+    if (!native_context_ || !params_) return RdmaAddressRefreshResult::FAILED;
+
+    ibv_port_attr port_attr{};
+    const uint8_t port = params_->device.port;
+    if (verbs_.ibv_query_port_default(native_context_, port, &port_attr)) {
+        PLOG(WARNING) << "Failed to refresh RDMA address on " << device_name_
+                      << "/" << static_cast<int>(port);
+        return RdmaAddressRefreshResult::FAILED;
     }
-    return gid_str;
+    if (port_attr.state != IBV_PORT_ACTIVE) {
+        LOG(WARNING) << "Cannot refresh RDMA address on " << device_name_ << "/"
+                     << static_cast<int>(port) << " while port state is "
+                     << port_attr.state;
+        return RdmaAddressRefreshResult::FAILED;
+    }
+
+    int next_gid_index = params_->device.gid_index;
+    if (next_gid_index < 0) {
+        if (getBestGidIndex(device_name_, verbs_, native_context_, port_attr,
+                            port,
+                            next_gid_index) == GidNetworkState::GID_NOT_FOUND) {
+            LOG(WARNING) << "No suitable GID found while refreshing "
+                         << device_name_ << "/" << static_cast<int>(port);
+            return RdmaAddressRefreshResult::FAILED;
+        }
+    }
+    if (next_gid_index < 0 || next_gid_index >= port_attr.gid_tbl_len) {
+        LOG(WARNING) << "Refreshed GID index " << next_gid_index
+                     << " is out of range [0, " << port_attr.gid_tbl_len
+                     << ") for " << device_name_;
+        return RdmaAddressRefreshResult::FAILED;
+    }
+
+    ibv_gid next_gid{};
+    if (verbs_.ibv_query_gid(native_context_, port, next_gid_index,
+                             &next_gid)) {
+        PLOG(WARNING) << "Failed to refresh GID " << next_gid_index << " on "
+                      << device_name_ << "/" << static_cast<int>(port);
+        return RdmaAddressRefreshResult::FAILED;
+    }
+    if (isNullGid(&next_gid)) {
+        LOG(WARNING) << "Refreshed GID " << next_gid_index << " on "
+                     << device_name_ << "/" << static_cast<int>(port)
+                     << " is empty";
+        return RdmaAddressRefreshResult::FAILED;
+    }
+
+#ifdef USE_SHCA
+    const uint32_t next_lid = u17_to_32(port_attr.lid);
+#else
+    const uint32_t next_lid = port_attr.lid;
+#endif
+    RdmaAddressSnapshot next_address{next_lid, gidBytesToString(next_gid.raw),
+                                     next_gid_index};
+    if (current) *current = next_address;
+    const bool changed = next_address.lid != old_address.lid ||
+                         next_address.gid != old_address.gid ||
+                         next_address.gid_index != old_address.gid_index;
+
+    // Publish even when the address is unchanged: a context whose port was
+    // down during setupLocalSegment() was omitted and must be inserted when
+    // it recovers.
+    auto status = transport_.refreshLocalDeviceDesc(
+        device_name_, next_address.lid, next_address.gid);
+    if (!status.ok()) {
+        LOG(ERROR) << "Failed to publish refreshed RDMA address for "
+                   << device_name_ << ": " << status.ToString();
+        return RdmaAddressRefreshResult::FAILED;
+    }
+
+    if (!changed) return RdmaAddressRefreshResult::UNCHANGED;
+
+    {
+        std::lock_guard<std::mutex> guard(address_mutex_);
+        lid_ = next_address.lid;
+        gid_ = next_gid;
+        gid_index_ = next_address.gid_index;
+    }
+    return RdmaAddressRefreshResult::CHANGED;
 }
 
 RdmaCQ* RdmaContext::cq(int index) {
@@ -714,7 +841,7 @@ int RdmaContext::openDevice(const std::string& device_name, uint8_t port) {
     if (params_->verbose) {
         for (int i = 0; i < port_attr.gid_tbl_len; i++) {
             struct ibv_gid_entry entry;
-            if (ibv_query_gid_ex(context.get(), port, i, &entry, 0)) {
+            if (QueryGidEx(verbs_, context.get(), port, i, &entry)) {
                 PLOG(WARNING)
                     << "Scan: Unable to query GID " << i << " on device "
                     << device_name << " port " << port;
@@ -733,8 +860,9 @@ int RdmaContext::openDevice(const std::string& device_name, uint8_t port) {
     if (gid_index_ < 0) {
         // Auto-select GID
         int found_gid_index = -1;
-        GidNetworkState gid_state = getBestGidIndex(
-            device_name, context.get(), port_attr, port, found_gid_index);
+        GidNetworkState gid_state =
+            getBestGidIndex(device_name, verbs_, context.get(), port_attr, port,
+                            found_gid_index);
         if (gid_state == GidNetworkState::GID_NOT_FOUND) {
             LOG(ERROR) << "No valid GID found for device " << device_name
                        << " port " << static_cast<int>(port);
@@ -769,8 +897,8 @@ int RdmaContext::openDevice(const std::string& device_name, uint8_t port) {
             has_issues = true;
         }
 
-        if (ibv_query_gid_ex(context.get(), port, gid_index_, &user_gid_entry,
-                             0) == 0) {
+        if (QueryGidEx(verbs_, context.get(), port, gid_index_,
+                       &user_gid_entry) == 0) {
             bool is_ipv4 =
                 ipv6_addr_v4mapped((struct in6_addr*)user_gid_entry.gid.raw);
             bool is_roce_v2 = user_gid_entry.gid_type == IBV_GID_TYPE_ROCE_V2;
@@ -815,8 +943,97 @@ int RdmaContext::openDevice(const std::string& device_name, uint8_t port) {
     }
 
     native_context_ = context.release();
+#ifdef USE_SHCA
+    lid_ = u17_to_32(port_attr.lid);
+#else
     lid_ = port_attr.lid;
+#endif
+    recordPortSpeed(port_attr);
+    queryEffectiveSpeed();
+    return 0;
+}
+
+void RdmaContext::recordPortSpeed(const ibv_port_attr& port_attr) {
+    int speed = port_attr.active_speed;
+#ifdef HAVE_IBV_ACTIVE_SPEED_EX
+    // XDR (encoding 256) overflows the uint8_t field above, which then
+    // reads 0; the extended field carries it on rdma-core builds that have
+    // one.
+    if (port_attr.active_speed_ex) speed = port_attr.active_speed_ex;
+#endif
+    active_speed_.store(speed, std::memory_order_relaxed);
+    active_width_.store(port_attr.active_width, std::memory_order_relaxed);
+}
+
+int RdmaContext::refreshPortAttributes() {
+    if (!native_context_) return -1;
+    ibv_port_attr port_attr;
+    if (verbs_.ibv_query_port_default(native_context_, params_->device.port,
+                                      &port_attr)) {
+        PLOG(WARNING) << "Failed to re-query port "
+                      << static_cast<int>(params_->device.port) << " on "
+                      << device_name_;
+        return -1;
+    }
+    recordPortSpeed(port_attr);
+    queryEffectiveSpeed();
+    return 0;
+}
+
+int RdmaContext::queryPortState(ibv_port_state* state) const {
+    if (!state || !native_context_ || !params_) return -1;
+    ibv_port_attr port_attr;
+    if (verbs_.ibv_query_port_default(native_context_, params_->device.port,
+                                      &port_attr)) {
+        PLOG(WARNING) << "Failed to query state of port "
+                      << static_cast<int>(params_->device.port) << " on "
+                      << device_name_;
+        return -1;
+    }
+    // No recordPortSpeed() here on purpose -- see the header.
+    *state = port_attr.state;
     return 0;
 }
+
+void RdmaContext::queryEffectiveSpeed() {
+    if (!native_context_ || !verbs_.ibv_query_port_speed) {
+        effective_speed_mbps_.store(0, std::memory_order_relaxed);
+        return;
+    }
+    uint64_t speed = 0;
+    int rc = verbs_.ibv_query_port_speed(native_context_, params_->device.port,
+                                         &speed);
+    if (rc != 0) {
+        // Keep the last known value: on a degraded LAG, dropping to the
+        // encoded rate would overstate the port until the next successful
+        // query. Log once per failure episode, not per query.
+        effective_speed_query_failures_.fetch_add(1, std::memory_order_relaxed);
+        if (!effective_speed_query_failing_.exchange(
+                true, std::memory_order_relaxed)) {
+            LOG(WARNING) << "ibv_query_port_speed failed on " << device_name_
+                         << " (rc " << rc << "), keeping "
+                         << effective_speed_mbps_.load(
+                                std::memory_order_relaxed)
+                         << " Mb/s ("
+                         << effective_speed_query_failures_.load(
+                                std::memory_order_relaxed)
+                         << " failures so far)";
+        }
+        return;
+    }
+    if (effective_speed_query_failing_.exchange(false,
+                                                std::memory_order_relaxed)) {
+        LOG(INFO) << "ibv_query_port_speed recovered on " << device_name_;
+    }
+    // The verb reports 100 Mb/s units; store plain Mb/s.
+    effective_speed_mbps_.store(speed * 100, std::memory_order_relaxed);
+}
+
+double RdmaContext::linkSpeedGbps() const {
+    return ibPortSpeedGbps(
+        effective_speed_mbps_.load(std::memory_order_relaxed),
+        active_speed_.load(std::memory_order_relaxed),
+        active_width_.load(std::memory_order_relaxed));
+}
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/endpoint.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/endpoint.cpp
index 4ce75a4620..23ec007632 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/endpoint.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/endpoint.cpp
@@ -15,22 +15,29 @@
 #include "tent/transport/rdma/endpoint.h"
 
 #include <glog/logging.h>
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
 
 #include <algorithm>
 #include <cassert>
 #include <cstddef>
-#include <sstream>
+#include <cstdint>
+#include <cstring>
 #include <iomanip>
-#include <queue>
 #include <mutex>
+#include <queue>
+#include <sstream>
+#include <string_view>
 
 #include "tent/common/status.h"
 #include "tent/common/types.h"
-#include "tent/transport/rdma/context.h"
-#include "tent/transport/rdma/endpoint_store.h"
 #include "tent/common/utils/os.h"
 #include "tent/common/utils/string_builder.h"
+#include "tent/runtime/control_plane.h"
 #include "tent/thirdparty/nlohmann/json.h"
+#include "tent/transport/rdma/context.h"
+#include "tent/transport/rdma/endpoint_store.h"
 
 namespace mooncake {
 namespace tent {
@@ -53,16 +60,28 @@ static inline const std::string statusToString(
 
 // Forward declaration for notification QP setup
 static int setupNotifyQpConnection(ibv_qp* qp, RdmaContext* ctx,
+                                   const EndPointParams& params,
+                                   int local_gid_index,
                                    const std::string& peer_gid_str,
-                                   uint16_t peer_lid, uint32_t peer_qp_num,
-                                   uint16_t pkey_index,
-                                   uint8_t service_level = 0,
-                                   uint8_t traffic_class = 0);
+                                   uint32_t peer_lid, uint32_t peer_qp_num);
+
+// A peer that reused the same nic path after restarting retires the stale
+// endpoint on the first bootstrap and expects a retry. Older peers also
+// returned success with an empty GID for that case.
+static bool isStaleEndpointBootstrapError(const Status& status) {
+    if (status.ok()) return false;
+    const std::string_view msg = status.message();
+    return msg.find("retired for reconnection") != std::string_view::npos ||
+           msg.find("Missing peer GID") != std::string_view::npos ||
+           msg.find("Endpoint not in handshaking state") !=
+               std::string_view::npos;
+}
 
 RdmaEndPoint::RdmaEndPoint()
     : status_(EP_UNINIT),
       context_(nullptr),
       params_(nullptr),
+      queue_lock_list_(nullptr),
       wr_depth_list_(nullptr),
       inflight_slices_(0),
       destroy_start_time_(0) {}
@@ -82,6 +101,7 @@ int RdmaEndPoint::construct(RdmaContext* context, EndPointParams* params,
     context_ = context;
     params_ = params;
     endpoint_name_ = endpoint_name;
+    local_address_ = context_->address();
     inflight_slices_.store(0, std::memory_order_relaxed);
 
     // Resolve the per-pool QP layout (see computeQpPoolSegments). Empty
@@ -103,6 +123,7 @@ int RdmaEndPoint::construct(RdmaContext* context, EndPointParams* params,
     // Value-initialize the full array because cleanup may run after only a
     // prefix of QPs has been created.
     wr_depth_list_ = new WrDepthBlock[total_qp]();
+    queue_lock_list_ = new TicketLock[total_qp];
 
     for (int i = 0; i < total_qp; ++i) {
         wr_depth_list_[i].value.store(0, std::memory_order_relaxed);
@@ -163,9 +184,18 @@ int RdmaEndPoint::construct(RdmaContext* context, EndPointParams* params,
         return -1;
     }
 
-    // Pre-post recv buffers for notification
-    notify_recv_buffers_.resize(kNotifyMaxPendingSends);
-    notify_recv_mrs_.resize(kNotifyMaxPendingSends);
+    // Allocate one contiguous recv buffer, logically split into
+    // kNotifyMaxPendingSends slots. One MR covers every slot so high
+    // endpoint counts do not explode ibv_reg_mr.
+    notify_recv_buffer_.resize(kNotifyBufferSize * kNotifyMaxPendingSends);
+    notify_recv_mr_ = context_->verbs_.ibv_reg_mr_default(
+        context_->nativePD(), notify_recv_buffer_.data(),
+        notify_recv_buffer_.size(), IBV_ACCESS_LOCAL_WRITE);
+    if (!notify_recv_mr_) {
+        PLOG(ERROR) << "Failed to register notification recv buffer";
+        deconstruct();
+        return -1;
+    }
 
     // Allocate one contiguous send buffer, logically split into
     // kNotifyMaxPendingSends slots to avoid DMA-vs-overwrite races.
@@ -179,20 +209,6 @@ int RdmaEndPoint::construct(RdmaContext* context, EndPointParams* params,
         return -1;
     }
 
-    for (size_t i = 0; i < kNotifyMaxPendingSends; ++i) {
-        notify_recv_buffers_[i].resize(kNotifyBufferSize);
-
-        // Register memory for recv buffer
-        notify_recv_mrs_[i] = context_->verbs_.ibv_reg_mr_default(
-            context_->nativePD(), notify_recv_buffers_[i].data(),
-            kNotifyBufferSize, IBV_ACCESS_LOCAL_WRITE);
-        if (!notify_recv_mrs_[i]) {
-            PLOG(ERROR) << "Failed to register notification recv buffer";
-            deconstruct();
-            return -1;
-        }
-    }
-
     return 0;
 }
 
@@ -240,20 +256,15 @@ int RdmaEndPoint::deconstructUnlocked() {
         // A live QP may still reference the notification MRs. Keep both MRs
         // and backing buffers intact until QP destruction succeeds.
         if (!notify_qp_) {
-            for (auto& mr : notify_recv_mrs_) {
-                if (!mr) continue;
-                if (context_->verbs_.ibv_dereg_mr(mr)) {
+            if (notify_recv_mr_) {
+                if (context_->verbs_.ibv_dereg_mr(notify_recv_mr_)) {
                     PLOG(ERROR) << "Failed to deregister notification recv MR";
                     result = -1;
                 } else {
-                    mr = nullptr;
+                    notify_recv_mr_ = nullptr;
                 }
             }
-            if (std::all_of(notify_recv_mrs_.begin(), notify_recv_mrs_.end(),
-                            [](ibv_mr* mr) { return mr == nullptr; })) {
-                notify_recv_mrs_.clear();
-                notify_recv_buffers_.clear();
-            }
+            if (!notify_recv_mr_) notify_recv_buffer_.clear();
 
             if (notify_send_mr_) {
                 if (context_->verbs_.ibv_dereg_mr(notify_send_mr_)) {
@@ -288,14 +299,18 @@ int RdmaEndPoint::deconstructUnlocked() {
     if (all_qps_destroyed) {
         qp_list_.clear();
         slice_queue_.clear();
+        delete[] queue_lock_list_;
+        queue_lock_list_ = nullptr;
         delete[] wr_depth_list_;
         wr_depth_list_ = nullptr;
     }
 
-    if (result == 0 && !notify_qp_ && notify_recv_mrs_.empty() &&
-        !notify_send_mr_ && qp_list_.empty()) {
-        peer_server_name_.clear();
-        peer_nic_name_.clear();
+    if (result == 0 && !notify_qp_ && !notify_recv_mr_ && !notify_send_mr_ &&
+        qp_list_.empty()) {
+        // peer_server_name_ / peer_nic_name_ are left alone: the notification
+        // worker reads them from a retiring endpoint it still holds (for the
+        // path health table) without taking lock_, and nothing needs them
+        // cleared - EP_DESTROYED already says the endpoint is gone.
         status_.store(EP_DESTROYED, std::memory_order_release);
         return 0;
     }
@@ -315,12 +330,12 @@ void RdmaEndPoint::beginDestroyNoLock() {
     destroy_start_time_ = getCurrentTimeInNano();
     status_.store(EP_DESTROYING, std::memory_order_release);
 
-    // Stop publishing the endpoint before QPs start flushing. A notification
-    // completion that already locked the weak_ptr may finish safely, while no
-    // later completion can acquire a retiring endpoint.
-    if (notify_qp_) {
-        context_->transport_.unregisterNotifyQp(notify_qp_->qp_num);
-    }
+    // The notify QP stays published until deconstruct(): notifications that
+    // already landed (the sender saw them acked) may still sit in the CQ
+    // unpolled, and the worker can only hand them out while it can find
+    // this endpoint. The flushes that follow the ERR transition stay quiet
+    // because the endpoint is no longer ready; deconstruct() unpublishes
+    // under notify_resource_mutex_ before it frees the buffers.
     {
         std::lock_guard<std::mutex> notify_guard(notify_send_mutex_);
         notify_connected_ = false;
@@ -373,6 +388,12 @@ bool RdmaEndPoint::finishDestroy() {
             break;
         }
     }
+    // The notify QP counts too. Destroying it takes its completions with it,
+    // including notifications the peer already saw acknowledged, so the ERR
+    // transition must be given the time to flush them out first. A QP that
+    // never completes them (a provider that drops WRs on RESET) is covered by
+    // the timeout below.
+    if (!has_outstanding && notifyInflight() != 0) has_outstanding = true;
     if (has_outstanding) {
         double elapsed = (getCurrentTimeInNano() - destroy_start_time_) / 1e9;
         if (elapsed < kFinishDestroyTimeoutSec) {
@@ -400,6 +421,7 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
     auto& transport = context_->transport_;
     std::vector<uint32_t> qp_num;
     BootstrapDesc local_desc, peer_desc;
+    const auto& local_address = local_address_;
     bool same_nic = false;
     bool is_self = false;
 
@@ -427,8 +449,8 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
         qp_num = qpNum();
         local_desc.qp_num = qp_num;
         local_desc.notify_qp_num = notifyQpNum();
-        local_desc.local_lid = context_->lid();
-        local_desc.local_gid = context_->gid();
+        local_desc.local_lid = local_address.lid;
+        local_desc.local_gid = local_address.gid;
 
         same_nic = (local_desc.local_nic_path == local_desc.peer_nic_path);
         is_self =
@@ -440,10 +462,10 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
     // Blocking operations (RPC / direct call) happen here without holding
     // lock_, so the RPC handler can freely acquire locks on peer endpoints.
     std::string peer_gid;
-    uint16_t peer_lid = 0;
+    uint32_t peer_lid = 0;
     if (same_nic) {
-        peer_gid = context_->gid();
-        peer_lid = context_->lid();
+        peer_gid = local_address.gid;
+        peer_lid = local_address.lid;
     } else if (is_self) {
         // Same server, different NIC: call handler directly, bypass RPC
         int rc = transport.onSetupRdmaConnections(local_desc, peer_desc);
@@ -470,25 +492,53 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
         }
         auto bootstrap_status =
             ControlClient::bootstrap(rpc_server_addr, local_desc, peer_desc);
+        auto simultaneousOpenReady = [&]() {
+            RWSpinlock::WriteGuard guard(lock_);
+            const bool same_peer = peer_server_name_ == peer_server_name &&
+                                   peer_nic_name_ == peer_nic_name;
+            const bool same_local_qps = qpNum() == local_desc.qp_num;
+            return status_.load(std::memory_order_relaxed) == EP_READY &&
+                   same_peer && same_local_qps;
+        };
         if (!bootstrap_status.ok()) {
             // With simultaneous open, the peer's bootstrap request may finish
             // our passive setup while this outbound RPC is still in flight.
             // A timeout therefore does not necessarily mean that connection
             // establishment failed. Reuse only the exact endpoint generation
             // that issued this RPC; EP_READY alone is not sufficient.
-            RWSpinlock::WriteGuard guard(lock_);
-            const bool same_peer = peer_server_name_ == peer_server_name &&
-                                   peer_nic_name_ == peer_nic_name;
-            const bool same_local_qps = qpNum() == local_desc.qp_num;
-            if (status_.load(std::memory_order_relaxed) == EP_READY &&
-                same_peer && same_local_qps) {
+            if (simultaneousOpenReady()) {
                 LOG(WARNING)
                     << "Bootstrap RPC failed after simultaneous-open passive "
                        "setup completed; reusing the established endpoint "
                     << endpoint_name_ << ": " << bootstrap_status.ToString();
                 return mooncake::tent::Status::OK();
             }
-            return bootstrap_status;
+            // Target retired a leftover endpoint from a previous peer process.
+            // The first RPC drops it; a second bootstrap creates a new one.
+            // Fixed targets also retry inside the same RPC, so this is the
+            // mixed-version / race fallback.
+            if (isStaleEndpointBootstrapError(bootstrap_status)) {
+                LOG(INFO)
+                    << "Retrying RDMA bootstrap after stale peer endpoint: "
+                    << bootstrap_status.ToString();
+                peer_desc = BootstrapDesc();
+                bootstrap_status = ControlClient::bootstrap(
+                    rpc_server_addr, local_desc, peer_desc);
+                if (!bootstrap_status.ok()) {
+                    if (simultaneousOpenReady()) {
+                        LOG(WARNING)
+                            << "Bootstrap retry failed after simultaneous-open "
+                               "passive setup completed; reusing the "
+                               "established endpoint "
+                            << endpoint_name_ << ": "
+                            << bootstrap_status.ToString();
+                        return mooncake::tent::Status::OK();
+                    }
+                    return bootstrap_status;
+                }
+            } else {
+                return bootstrap_status;
+            }
         }
         qp_num = peer_desc.qp_num;
         peer_gid = peer_desc.local_gid;
@@ -516,7 +566,8 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
         assert(qp_num.size());
         peer_server_name_ = peer_server_name;
         peer_nic_name_ = peer_nic_name;
-        int rc = setupAllQPs(peer_gid, peer_lid, qp_num);
+        int rc =
+            setupAllQPs(peer_gid, peer_lid, qp_num, local_address.gid_index);
         if (rc) {
             beginDestroyNoLock();
             return mooncake::tent::Status::InternalError(
@@ -526,19 +577,22 @@ Status RdmaEndPoint::connect(const std::string& peer_server_name,
 
         // Setup notification QP connection if peer supports it
         if (peer_desc.notify_qp_num != 0 && notify_qp_) {
-            rc = setupNotifyQpConnection(
-                notify_qp_, context_, peer_gid, peer_lid,
-                peer_desc.notify_qp_num, params_->pkey_index,
-                params_->service_level, params_->traffic_class);
+            rc = setupNotifyQpConnection(notify_qp_, context_, *params_,
+                                         local_address.gid_index, peer_gid,
+                                         peer_lid, peer_desc.notify_qp_num);
             if (rc) {
                 LOG(WARNING)
                     << "Failed to setup notification QP, notification disabled";
                 notify_connected_ = false;
             } else {
-                notify_connected_ = true;
-                repostAllNotifyRecvs();
+                // Published before the first RECV is posted: a peer that
+                // sends the moment its own handshake returns must find this
+                // endpoint, and a completion cannot arrive before the RECVs
+                // are there anyway.
                 context_->transport_.registerNotifyQp(notify_qp_->qp_num,
                                                       shared_from_this());
+                notify_connected_ = true;
+                repostAllNotifyRecvs();
             }
         }
     }
@@ -571,8 +625,8 @@ Status RdmaEndPoint::accept(const BootstrapDesc& peer_desc,
                 MakeNicPath(transport.rdma_server_name_, context_->name());
             local_desc.peer_nic_path = peer_desc.local_nic_path;
             local_desc.qp_num = qpNum();
-            local_desc.local_lid = context_->lid();
-            local_desc.local_gid = context_->gid();
+            local_desc.local_lid = local_address_.lid;
+            local_desc.local_gid = local_address_.gid;
             local_desc.notify_qp_num = notifyQpNum();
             return mooncake::tent::Status::OK();
         }
@@ -607,8 +661,8 @@ Status RdmaEndPoint::accept(const BootstrapDesc& peer_desc,
         MakeNicPath(transport.rdma_server_name_, context_->name());
     local_desc.peer_nic_path = peer_nic_path;
     local_desc.qp_num = qpNum();
-    local_desc.local_lid = context_->lid();
-    local_desc.local_gid = context_->gid();
+    local_desc.local_lid = local_address_.lid;
+    local_desc.local_gid = local_address_.gid;
     local_desc.notify_qp_num = notifyQpNum();  // Pass notification QP number
     if (peer_desc.local_gid.empty()) {
         return mooncake::tent::Status::InvalidArgument(
@@ -616,8 +670,8 @@ Status RdmaEndPoint::accept(const BootstrapDesc& peer_desc,
     }
     peer_server_name_ = peer_server_name;
     peer_nic_name_ = peer_nic_name;
-    int rc =
-        setupAllQPs(peer_desc.local_gid, peer_desc.local_lid, peer_desc.qp_num);
+    int rc = setupAllQPs(peer_desc.local_gid, peer_desc.local_lid,
+                         peer_desc.qp_num, local_address_.gid_index);
     if (rc) {
         beginDestroyNoLock();
         return mooncake::tent::Status::InternalError(
@@ -628,16 +682,15 @@ Status RdmaEndPoint::accept(const BootstrapDesc& peer_desc,
     // Setup notification QP connection if peer supports it
     if (peer_desc.notify_qp_num != 0 && notify_qp_) {
         rc = setupNotifyQpConnection(
-            notify_qp_, context_, peer_desc.local_gid, peer_desc.local_lid,
-            peer_desc.notify_qp_num, params_->pkey_index,
-            params_->service_level, params_->traffic_class);
+            notify_qp_, context_, *params_, local_address_.gid_index,
+            peer_desc.local_gid, peer_desc.local_lid, peer_desc.notify_qp_num);
         if (rc) {
             notify_connected_ = false;
         } else {
-            notify_connected_ = true;
-            repostAllNotifyRecvs();
             context_->transport_.registerNotifyQp(notify_qp_->qp_num,
                                                   shared_from_this());
+            notify_connected_ = true;
+            repostAllNotifyRecvs();
         }
     }
 
@@ -677,9 +730,9 @@ const QpPoolSegment* RdmaEndPoint::poolForQp(int qp_index) const {
     return nullptr;
 }
 
-int RdmaEndPoint::setupAllQPs(const std::string& peer_gid, uint16_t peer_lid,
+int RdmaEndPoint::setupAllQPs(const std::string& peer_gid, uint32_t peer_lid,
                               std::vector<uint32_t> peer_qp_num_list,
-                              std::string* reply_msg) {
+                              int local_gid_index, std::string* reply_msg) {
     if (status_.load(std::memory_order_relaxed) == EP_READY) {
         return -1;
     }
@@ -695,8 +748,9 @@ int RdmaEndPoint::setupAllQPs(const std::string& peer_gid, uint16_t peer_lid,
     }
 
     for (int qp_index = 0; qp_index < (int)qp_list_.size(); ++qp_index) {
-        int ret = setupOneQP(qp_index, peer_gid, peer_lid,
-                             peer_qp_num_list[qp_index], reply_msg);
+        int ret =
+            setupOneQP(qp_index, peer_gid, peer_lid, peer_qp_num_list[qp_index],
+                       local_gid_index, reply_msg);
         if (ret) {
             return ret;
         }
@@ -718,7 +772,8 @@ static ibv_wr_opcode getOpCode(RdmaSlice* slice) {
 }
 
 int RdmaEndPoint::submitSlices(std::vector<RdmaSlice*>& slice_list,
-                               int qp_index) {
+                               int qp_index,
+                               const std::function<void(RdmaSlice*)>& on_post) {
     const static int kSgeEntries = 1;
     RWSpinlock::ReadGuard guard(lock_);
     if (qp_list_.empty()) return 0;
@@ -764,6 +819,7 @@ int RdmaEndPoint::submitSlices(std::vector<RdmaSlice*>& slice_list,
         current->ep_weak_ptr = self;
         current->qp_index = qp_index;
         current->failed = false;
+        if (on_post) on_post(current);
         wr.wr_id = (uint64_t)current;
         wr.opcode = getOpCode(current);
         wr.num_sge = kSgeEntries;
@@ -779,24 +835,33 @@ int RdmaEndPoint::submitSlices(std::vector<RdmaSlice*>& slice_list,
         sge_idx += wr.num_sge;
     }
 
-    int rc = ibv_post_send(qp_list_[qp_index], wr_list.data(), &bad_wr);
-    if (rc) {
-        LOG(ERROR) << "ibv_post_send: " << strerror(abs(rc)) << " [" << rc
-                   << "]";
-        while (bad_wr) {
-            slice_list[bad_wr - wr_list.data()]->failed = true;
-            cancelQuota(qp_index, 1);
-            bad_wr = bad_wr->next;
+    int rc = 0;
+    {
+        // The queue mirrors the QP's posting order, so posting and
+        // enqueueing must not interleave with another lane's post or
+        // acknowledge on this QP.
+        std::lock_guard<TicketLock> qp_guard(queue_lock_list_[qp_index]);
+        rc = ibv_post_send(qp_list_[qp_index], wr_list.data(), &bad_wr);
+        if (rc) {
+            while (bad_wr) {
+                slice_list[bad_wr - wr_list.data()]->failed = true;
+                cancelQuota(qp_index, 1);
+                bad_wr = bad_wr->next;
+            }
         }
-    }
-
-    auto& queue = slice_queue_[qp_index];
-    for (int wr_idx = 0; wr_idx < wr_count; ++wr_idx) {
-        auto current = slice_list[wr_idx];
-        if (!current->failed) {
+        auto& queue = slice_queue_[qp_index];
+        for (int wr_idx = 0; wr_idx < wr_count; ++wr_idx) {
+            auto current = slice_list[wr_idx];
+            if (current->failed) continue;  // never reached the hardware
             queue.push(current);
+            // One signalled work request, one completion owed.
+            current->completions_owed.fetch_add(1, std::memory_order_acq_rel);
         }
     }
+    if (rc) {
+        LOG(ERROR) << "ibv_post_send: " << strerror(abs(rc)) << " [" << rc
+                   << "]";
+    }
     return wr_count;
 }
 
@@ -832,10 +897,15 @@ void RdmaEndPoint::resetInflightSlices() {
     }
 }
 
-size_t RdmaEndPoint::acknowledge(RdmaSlice* slice, TransferStatusEnum status) {
+size_t RdmaEndPoint::acknowledge(
+    RdmaSlice* slice, TransferStatusEnum status,
+    const std::function<void(RdmaSlice*)>& on_each) {
     RWSpinlock::ReadGuard guard(lock_);
     auto qp_index = slice->qp_index;
     if (qp_index < 0 || qp_index >= (int)slice_queue_.size()) return 0;
+    // Everything below, on_each and updateSliceStatus included, runs under
+    // the QP lock: keep the callbacks cheap and free of endpoint re-entry.
+    std::lock_guard<TicketLock> qp_guard(queue_lock_list_[qp_index]);
     auto& queue = slice_queue_[qp_index];
     if (!queue.contains(slice)) return 0;
     int num_entries = 0;
@@ -844,6 +914,7 @@ size_t RdmaEndPoint::acknowledge(RdmaSlice* slice, TransferStatusEnum status) {
         current = queue.pop();
         if (!current) break;
         num_entries++;
+        if (on_each) on_each(current);
         updateSliceStatus(current, status);
     } while (current != slice);
     cancelQuota(qp_index, num_entries);
@@ -885,8 +956,8 @@ void RdmaEndPoint::cancelQuota(int qp_index, int num_entries) {
 }
 
 int RdmaEndPoint::setupOneQP(int qp_index, const std::string& peer_gid,
-                             uint16_t peer_lid, uint32_t peer_qp_num,
-                             std::string* reply_msg) {
+                             uint32_t peer_lid, uint32_t peer_qp_num,
+                             int local_gid_index, std::string* reply_msg) {
     assert(qp_index >= 0 && qp_index < (int)qp_list_.size());
     auto& qp = qp_list_[qp_index];
 
@@ -939,11 +1010,15 @@ int RdmaEndPoint::setupOneQP(int qp_index, const std::string& peer_gid,
     }
 
     attr.ah_attr.grh.dgid = peer_gid_raw;
-    attr.ah_attr.grh.sgid_index = context().gidIndex();
+    attr.ah_attr.grh.sgid_index = local_gid_index;
     attr.ah_attr.grh.hop_limit = params_->hop_limit;
     attr.ah_attr.grh.flow_label = params_->flow_label;
     attr.ah_attr.grh.traffic_class = qp_traffic_class;
-    attr.ah_attr.dlid = peer_lid;
+#ifdef USE_SHCA
+    attr.ah_attr.dlid = u32_to_17(peer_lid);
+#else
+    attr.ah_attr.dlid = static_cast<uint16_t>(peer_lid);
+#endif
     attr.ah_attr.sl = qp_service_level;
     attr.ah_attr.src_path_bits = params_->src_path_bits;
     attr.ah_attr.static_rate = params_->static_rate;
@@ -994,14 +1069,57 @@ int RdmaEndPoint::setupOneQP(int qp_index, const std::string& peer_gid,
     return 0;
 }
 
+char* RdmaEndPoint::notifySlotPtr(char* base, size_t idx) {
+    return base + idx * kNotifyBufferSize;
+}
+
+bool RdmaEndPoint::encodeNotifyPayload(char* slot, const std::string& name,
+                                       const std::string& msg,
+                                       uint32_t* out_len) {
+    if (!slot || !out_len) return false;
+    if (name.size() > UINT32_MAX || msg.size() > UINT32_MAX) return false;
+    uint32_t name_len = static_cast<uint32_t>(name.size());
+    uint32_t msg_len = static_cast<uint32_t>(msg.size());
+    const size_t total_size =
+        sizeof(name_len) + name_len + sizeof(msg_len) + msg_len;
+    if (total_size > kNotifyBufferSize) return false;
+
+    auto* ptr = slot;
+    std::memcpy(ptr, &name_len, sizeof(name_len));
+    ptr += sizeof(name_len);
+    std::memcpy(ptr, name.data(), name_len);
+    ptr += name_len;
+    std::memcpy(ptr, &msg_len, sizeof(msg_len));
+    ptr += sizeof(msg_len);
+    std::memcpy(ptr, msg.data(), msg_len);
+    *out_len = static_cast<uint32_t>(total_size);
+    return true;
+}
+
+bool RdmaEndPoint::decodeNotifyPayload(const char* data, size_t byte_len,
+                                       std::string* name, std::string* msg) {
+    if (!data || !name || !msg || byte_len < 8) return false;
+    uint32_t name_len = 0;
+    std::memcpy(&name_len, data, sizeof(name_len));
+    if (name_len > byte_len - 8) return false;
+    uint32_t msg_len = 0;
+    std::memcpy(&msg_len, data + 4 + name_len, sizeof(msg_len));
+    if (msg_len > byte_len - 8 - name_len) return false;
+    name->assign(data + 4, name_len);
+    msg->assign(data + 4 + name_len + 4, msg_len);
+    return true;
+}
+
 void RdmaEndPoint::postNotifyRecv(size_t idx) {
-    if (idx >= notify_recv_buffers_.size() || idx >= notify_recv_mrs_.size())
+    if (!notify_qp_ || !notify_recv_mr_ || idx >= kNotifyMaxPendingSends ||
+        notify_recv_buffer_.size() < (idx + 1) * kNotifyBufferSize)
         return;
 
     ibv_sge sge = {};
-    sge.addr = reinterpret_cast<uint64_t>(notify_recv_buffers_[idx].data());
-    sge.length = notify_recv_buffers_[idx].size();
-    sge.lkey = notify_recv_mrs_[idx]->lkey;
+    sge.addr = reinterpret_cast<uint64_t>(
+        notifySlotPtr(notify_recv_buffer_.data(), idx));
+    sge.length = kNotifyBufferSize;
+    sge.lkey = notify_recv_mr_->lkey;
 
     ibv_recv_wr wr = {};
     wr.wr_id = idx;
@@ -1013,7 +1131,13 @@ void RdmaEndPoint::postNotifyRecv(size_t idx) {
     if (ret) {
         LOG(ERROR) << "Failed to post notification recv: " << strerror(abs(ret))
                    << " [" << ret << "]";
+        return;
     }
+    notify_inflight_.fetch_add(1, std::memory_order_release);
+}
+
+void RdmaEndPoint::rearmNotifyRecv(size_t idx) {
+    if (shouldRearmNotifyRecv(status(), notifyConnected())) postNotifyRecv(idx);
 }
 
 void RdmaEndPoint::repostAllNotifyRecvs() {
@@ -1022,11 +1146,17 @@ void RdmaEndPoint::repostAllNotifyRecvs() {
     }
 }
 
+// The path MTU, the RNR timer and the timeout/retry budget come from the
+// same EndPointParams the data QPs use (see setupOneQP), so a dead peer path
+// is reported on the notify QP in the time the data QPs take and tuning
+// send_timeout / the retry counts applies to both. The address-vector fields
+// (hop_limit, flow_label, src_path_bits, PSNs) deliberately keep the values
+// this function always used.
 static int setupNotifyQpConnection(ibv_qp* qp, RdmaContext* ctx,
+                                   const EndPointParams& params,
+                                   int local_gid_index,
                                    const std::string& peer_gid_str,
-                                   uint16_t peer_lid, uint32_t peer_qp_num,
-                                   uint16_t pkey_index, uint8_t service_level,
-                                   uint8_t traffic_class) {
+                                   uint32_t peer_lid, uint32_t peer_qp_num) {
     // Reconnect path may call this when QP is already in RTS; force a clean
     // state machine: RESET -> INIT -> RTR -> RTS.
     ibv_qp_attr qp_attr = {};
@@ -1039,7 +1169,7 @@ static int setupNotifyQpConnection(ibv_qp* qp, RdmaContext* ctx,
 
     memset(&qp_attr, 0, sizeof(qp_attr));
     qp_attr.qp_state = IBV_QPS_INIT;
-    qp_attr.pkey_index = pkey_index;
+    qp_attr.pkey_index = params.pkey_index;
     qp_attr.port_num = ctx->portNum();
     qp_attr.qp_access_flags = IBV_ACCESS_REMOTE_WRITE;
     ret = ibv_modify_qp(
@@ -1061,23 +1191,28 @@ static int setupNotifyQpConnection(ibv_qp* qp, RdmaContext* ctx,
     }
 
     // Modify to RTR
+    const NotifyQpRtrAttrs rtr = buildNotifyQpRtrAttrs(params);
     memset(&qp_attr, 0, sizeof(qp_attr));
     qp_attr.qp_state = IBV_QPS_RTR;
-    qp_attr.path_mtu = IBV_MTU_4096;
+    qp_attr.path_mtu = rtr.path_mtu;
     qp_attr.dest_qp_num = peer_qp_num;
     qp_attr.rq_psn = 0;
-    qp_attr.max_dest_rd_atomic = 1;
-    qp_attr.min_rnr_timer = 0x12;
+    qp_attr.max_dest_rd_atomic = rtr.max_dest_rd_atomic;
+    qp_attr.min_rnr_timer = rtr.min_rnr_timer;
     qp_attr.ah_attr.is_global = 1;
-    qp_attr.ah_attr.dlid = peer_lid;
-    qp_attr.ah_attr.sl = service_level;
+#ifdef USE_SHCA
+    qp_attr.ah_attr.dlid = u32_to_17(peer_lid);
+#else
+    qp_attr.ah_attr.dlid = static_cast<uint16_t>(peer_lid);
+#endif
+    qp_attr.ah_attr.sl = params.service_level;
     qp_attr.ah_attr.src_path_bits = 0;
     qp_attr.ah_attr.port_num = ctx->portNum();
     memcpy(&qp_attr.ah_attr.grh.dgid, &peer_gid, 16);
     qp_attr.ah_attr.grh.flow_label = 0;
-    qp_attr.ah_attr.grh.sgid_index = ctx->gidIndex();
+    qp_attr.ah_attr.grh.sgid_index = local_gid_index;
     qp_attr.ah_attr.grh.hop_limit = 255;
-    qp_attr.ah_attr.grh.traffic_class = traffic_class;
+    qp_attr.ah_attr.grh.traffic_class = params.traffic_class;
 
     ret = ibv_modify_qp(qp, &qp_attr,
                         IBV_QP_STATE | IBV_QP_PATH_MTU | IBV_QP_DEST_QPN |
@@ -1089,13 +1224,14 @@ static int setupNotifyQpConnection(ibv_qp* qp, RdmaContext* ctx,
     }
 
     // Modify to RTS
+    const NotifyQpRtsAttrs rts = buildNotifyQpRtsAttrs(params);
     memset(&qp_attr, 0, sizeof(qp_attr));
     qp_attr.qp_state = IBV_QPS_RTS;
     qp_attr.sq_psn = 0;
-    qp_attr.timeout = 0x12;
-    qp_attr.retry_cnt = 7;
-    qp_attr.rnr_retry = 7;
-    qp_attr.max_rd_atomic = 1;
+    qp_attr.timeout = rts.timeout;
+    qp_attr.retry_cnt = rts.retry_cnt;
+    qp_attr.rnr_retry = rts.rnr_retry;
+    qp_attr.max_rd_atomic = rts.max_rd_atomic;
 
     ret = ibv_modify_qp(qp, &qp_attr,
                         IBV_QP_STATE | IBV_QP_TIMEOUT | IBV_QP_RETRY_CNT |
@@ -1118,7 +1254,11 @@ bool RdmaEndPoint::sendNotification(const std::string& name,
                notify_pending_count_ < kNotifyMaxPendingSends;
     });
     if (!notify_connected_) {
-        LOG(ERROR) << "Notification QP not connected";
+        // Every send on this endpoint fails the same way until it is
+        // rebuilt, and the caller has a fallback path; one line per hundred
+        // is enough to show it is happening.
+        LOG_EVERY_N(WARNING, 100)
+            << "Notification QP not connected on endpoint " << endpoint_name_;
         return false;
     }
     std::lock_guard<std::mutex> resource_guard(notify_resource_mutex_);
@@ -1127,30 +1267,13 @@ bool RdmaEndPoint::sendNotification(const std::string& name,
     // Pick the next send slot — flow control guarantees this slot's previous
     // DMA has completed (at most kNotifyMaxPendingSends-1 in-flight).
     size_t slot = notify_send_wr_id_ % kNotifyMaxPendingSends;
-    char* slot_ptr = notify_send_buffer_.data() + slot * kNotifyBufferSize;
-
-    // Serialize: [name_len(4)][name][msg_len(4)][msg]
-    if (name.size() > UINT32_MAX || msg.size() > UINT32_MAX) {
-        LOG(ERROR) << "Notification field exceeds uint32 limit";
-        return false;
-    }
-    uint32_t name_len = static_cast<uint32_t>(name.size());
-    uint32_t msg_len = static_cast<uint32_t>(msg.size());
-    size_t total_size = sizeof(name_len) + name_len + sizeof(msg_len) + msg_len;
-    if (total_size > kNotifyBufferSize) {
-        LOG(ERROR) << "Notification message too large: " << total_size;
+    char* slot_ptr = notifySlotPtr(notify_send_buffer_.data(), slot);
+    uint32_t total_size = 0;
+    if (!encodeNotifyPayload(slot_ptr, name, msg, &total_size)) {
+        LOG(ERROR) << "Failed to encode notification payload";
         return false;
     }
 
-    auto* ptr = slot_ptr;
-    std::memcpy(ptr, &name_len, sizeof(name_len));
-    ptr += sizeof(name_len);
-    std::memcpy(ptr, name.data(), name_len);
-    ptr += name_len;
-    std::memcpy(ptr, &msg_len, sizeof(msg_len));
-    ptr += sizeof(msg_len);
-    std::memcpy(ptr, msg.data(), msg_len);
-
     // Post send
     ibv_sge sge = {};
     sge.addr = reinterpret_cast<uint64_t>(slot_ptr);
@@ -1176,54 +1299,47 @@ bool RdmaEndPoint::sendNotification(const std::string& name,
     }
 
     notify_pending_count_++;
+    notify_inflight_.fetch_add(1, std::memory_order_release);
     return true;
 }
 
 bool RdmaEndPoint::handleNotifyRecv(size_t buffer_idx, size_t byte_len) {
     std::lock_guard<std::mutex> resource_guard(notify_resource_mutex_);
-    if (buffer_idx >= notify_recv_buffers_.size()) {
+    if (!notify_recv_mr_) {
+        // The endpoint was deconstructed while this completion was in the
+        // worker's batch. Rare, and not a malformed completion.
+        LOG_EVERY_N(WARNING, 100)
+            << "Notification dropped: endpoint " << endpoint_name_
+            << " was torn down before the completion was handled";
+        return false;
+    }
+    if (buffer_idx >= kNotifyMaxPendingSends ||
+        notify_recv_buffer_.size() < (buffer_idx + 1) * kNotifyBufferSize) {
         LOG(ERROR) << "Invalid recv buffer index: " << buffer_idx;
         return false;
     }
 
     // Silent retry for byte_len == 0
     if (byte_len == 0) {
-        postNotifyRecv(buffer_idx);
+        rearmNotifyRecv(buffer_idx);
         return false;
     }
 
-    char* data = notify_recv_buffers_[buffer_idx].data();
-    size_t len = byte_len;
-
-    // Deserialize: [name_len(4)][name][msg_len(4)][msg]
-    if (len < 8) {
-        LOG(ERROR) << "Invalid notification message size: " << len;
-        postNotifyRecv(buffer_idx);
-        return false;
-    }
-
-    uint32_t name_len = *reinterpret_cast<uint32_t*>(data);
-    if (name_len > len - 8) {
-        LOG(ERROR) << "Invalid notification message format (name too long)";
-        postNotifyRecv(buffer_idx);
-        return false;
-    }
-
-    std::string name(data + 4, name_len);
-    uint32_t msg_len = *reinterpret_cast<uint32_t*>(data + 4 + name_len);
-    if (msg_len > len - 8 - name_len) {
-        LOG(ERROR) << "Invalid notification message format (msg too long)";
-        postNotifyRecv(buffer_idx);
+    char* data = notifySlotPtr(notify_recv_buffer_.data(), buffer_idx);
+    std::string name;
+    std::string msg;
+    if (!decodeNotifyPayload(data, byte_len, &name, &msg)) {
+        LOG(ERROR) << "Invalid notification message size or format: "
+                   << byte_len;
+        rearmNotifyRecv(buffer_idx);
         return false;
     }
 
-    std::string msg(data + 4 + name_len + 4, msg_len);
-
     // Add directly to transport queue (skip endpoint queue for lower latency)
     context_->transport_.addNotificationToQueue(name, msg);
 
     // Repost recv buffer
-    postNotifyRecv(buffer_idx);
+    rearmNotifyRecv(buffer_idx);
     return true;
 }
 
@@ -1234,5 +1350,19 @@ void RdmaEndPoint::handleNotifySendComplete(uint64_t wr_id) {
         notify_send_cv_.notify_one();
     }
 }
+
+void RdmaEndPoint::disableNotification(const std::string& reason) {
+    {
+        std::lock_guard<std::mutex> send_guard(notify_send_mutex_);
+        // A second failing completion on the same QP must not report again.
+        if (!notify_connected_.exchange(false)) return;
+        notify_send_cv_.notify_all();
+    }
+    LOG(WARNING) << "Notifications disabled on endpoint " << endpoint_name_
+                 << ", data path kept alive: " << reason;
+    // The QP stays published: notifications already in the CQ are still
+    // handed out, and the worker keeps the flushes of the posted WRs quiet
+    // now that notify_connected_ is off.
+}
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/endpoint_store.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/endpoint_store.cpp
index c5ea69921d..9d179d34aa 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/endpoint_store.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/endpoint_store.cpp
@@ -119,12 +119,49 @@ void FIFOEndpointStore::evictOne() {
     LOG(INFO) << victim << " evicted from FIFOEndpointStore";
 }
 
+void FIFOEndpointStore::evictAll() {
+    std::vector<std::shared_ptr<RdmaEndPoint>> to_evict;
+    {
+        RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+        to_evict.reserve(endpoint_map_.size());
+        for (auto& entry : endpoint_map_) {
+            to_evict.push_back(entry.second);
+            // Publish into waiting_list_ under the same lock: reclaim()
+            // iterates waiting_list_ under endpoint_map_lock_, so inserting
+            // here avoids an unsynchronized read/write on the unordered_set.
+            waiting_list_.insert(entry.second);
+        }
+        endpoint_map_.clear();
+        fifo_list_.clear();
+        fifo_map_.clear();
+    }
+    // beginDestroy() may call back into reclaim() (which takes
+    // endpoint_map_lock_), so it must run after the lock is released.
+    for (auto& ep : to_evict) {
+        ep->beginDestroy();
+    }
+    LOG(INFO) << "FIFOEndpointStore: evicted all " << to_evict.size()
+              << " endpoints on port recovery";
+}
+
 void FIFOEndpointStore::reclaim() {
-    RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+    std::vector<std::shared_ptr<RdmaEndPoint>> candidates;
+    {
+        // Only protect the waiting_list_ iteration. finishDestroy() may wait
+        // for CQ drain and take the endpoint lock, so it must run after this
+        // store lock has been released.
+        RWSpinlock::ReadGuard guard(endpoint_map_lock_);
+        candidates.reserve(waiting_list_.size());
+        for (auto& endpoint : waiting_list_) candidates.push_back(endpoint);
+    }
+
     std::vector<std::shared_ptr<RdmaEndPoint>> to_delete;
-    for (auto& endpoint : waiting_list_) {
+    for (auto& endpoint : candidates) {
         if (endpoint->finishDestroy()) to_delete.push_back(endpoint);
     }
+    if (to_delete.empty()) return;
+
+    RWSpinlock::WriteGuard guard(endpoint_map_lock_);
     for (auto& endpoint : to_delete) waiting_list_.erase(endpoint);
 }
 
@@ -288,15 +325,54 @@ void SIEVEEndpointStore::evictOne() {
     return;
 }
 
+void SIEVEEndpointStore::evictAll() {
+    std::vector<std::shared_ptr<RdmaEndPoint>> to_evict;
+    {
+        RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+        to_evict.reserve(endpoint_map_.size());
+        for (auto& entry : endpoint_map_) {
+            to_evict.push_back(entry.second.first);
+            // Publish into waiting_list_ under the same lock: reclaim()
+            // iterates waiting_list_ under endpoint_map_lock_, so inserting
+            // here avoids an unsynchronized read/write on the unordered_set.
+            waiting_list_.insert(entry.second.first);
+            waiting_list_len_.fetch_add(1, std::memory_order_relaxed);
+        }
+        endpoint_map_.clear();
+        fifo_list_.clear();
+        fifo_map_.clear();
+        hand_ = std::nullopt;
+    }
+    for (auto& ep : to_evict) {
+        ep->beginDestroy();
+    }
+    LOG(INFO) << "SIEVEEndpointStore: evicted all " << to_evict.size()
+              << " endpoints on port recovery";
+}
+
 void SIEVEEndpointStore::reclaim() {
     if (waiting_list_len_.load(std::memory_order_relaxed) == 0) return;
-    RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+
+    std::vector<std::shared_ptr<RdmaEndPoint>> candidates;
+    {
+        // Only protect the waiting_list_ iteration. finishDestroy() may wait
+        // for CQ drain and take the endpoint lock, so it must run after this
+        // store lock has been released.
+        RWSpinlock::ReadGuard guard(endpoint_map_lock_);
+        candidates.reserve(waiting_list_.size());
+        for (auto& endpoint : waiting_list_) candidates.push_back(endpoint);
+    }
+
     std::vector<std::shared_ptr<RdmaEndPoint>> to_delete;
-    for (auto& endpoint : waiting_list_) {
+    for (auto& endpoint : candidates) {
         if (endpoint->finishDestroy()) to_delete.push_back(endpoint);
     }
-    for (auto& endpoint : to_delete) waiting_list_.erase(endpoint);
-    waiting_list_len_ -= to_delete.size();
+    if (to_delete.empty()) return;
+
+    size_t erased = 0;
+    RWSpinlock::WriteGuard guard(endpoint_map_lock_);
+    for (auto& endpoint : to_delete) erased += waiting_list_.erase(endpoint);
+    waiting_list_len_.fetch_sub(erased, std::memory_order_relaxed);
 }
 
 size_t SIEVEEndpointStore::size() { return endpoint_map_.size(); }
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/ibv_loader.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/ibv_loader.cpp
index 9f4bee3c98..afff4fdf1d 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/ibv_loader.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/ibv_loader.cpp
@@ -32,6 +32,19 @@ bool LoadSymbol(void* handle, const char* name, Fn& out) {
     return true;
 }
 
+// A symbol newer libibverbs add; its absence must not disable RDMA.
+template <typename Fn>
+void LoadOptionalSymbol(void* handle, const char* name, Fn& out) {
+    void* sym = dlsym(handle, name);
+    if (!sym) {
+        LOG(INFO) << "libibverbs lacks optional symbol " << name
+                  << "; the fallback path will be used";
+        out = nullptr;
+        return;
+    }
+    out = reinterpret_cast<Fn>(sym);
+}
+
 IbvLoader& IbvLoader::Instance() {
     static IbvLoader instance;
     return instance;
@@ -53,8 +66,13 @@ IbvLoader::IbvLoader() {
     ok &= LoadSymbol(handle_, "ibv_close_device", symbols_.ibv_close_device);
     ok &= LoadSymbol(handle_, "ibv_query_device", symbols_.ibv_query_device);
     ok &= LoadSymbol(handle_, "ibv_query_gid", symbols_.ibv_query_gid);
+    // ibv_query_gid_ex() is a header inline over this entry point, which the
+    // binary already links, so requiring it here loses no host.
+    ok &= LoadSymbol(handle_, "_ibv_query_gid_ex", symbols_.ibv_query_gid_ex);
     ok &=
         LoadSymbol(handle_, "ibv_query_port", symbols_.ibv_query_port_default);
+    LoadOptionalSymbol(handle_, "ibv_query_port_speed",
+                       symbols_.ibv_query_port_speed);
     ok &= LoadSymbol(handle_, "ibv_get_device_name",
                      symbols_.ibv_get_device_name);
 
@@ -116,4 +134,4 @@ IbvLoader::~IbvLoader() {
     }
 }
 }  // namespace tent
-}  // namespace mooncake
\ No newline at end of file
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/quota.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/quota.cpp
index 9948d9b8d1..74004a772d 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/quota.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/quota.cpp
@@ -18,6 +18,8 @@
 #include "tent/common/utils/random.h"
 #include "tent/common/utils/os.h"
 
+#include <glog/logging.h>
+
 #include <algorithm>
 #include <iostream>
 #include <iomanip>
@@ -31,16 +33,58 @@ Status DeviceSelector::loadTopology(std::shared_ptr<Topology>& local_topology) {
         if (!entry || entry->type != Topology::NIC_RDMA) continue;
         DeviceInfo& info = devices_[dev_id];
         info.dev_id = dev_id;
-        info.bw_gbps = kDefaultBwGbps;
+        info.bw_gbps.store(0.0, std::memory_order_relaxed);  // unknown
         info.numa_id = entry->numa_node;
-        info.ewma_bandwidth_bps.store(info.getTheoreticalBandwidth(),
-                                      std::memory_order_relaxed);
+        const double seed = theoreticalBandwidth(info);
+        info.ewma_bandwidth_bps.store(seed, std::memory_order_relaxed);
+        info.ewma_transmit_bps.store(seed, std::memory_order_relaxed);
     }
     // Initialize device base priorities after all devices are loaded
     fillDevicePriorities();
     return Status::OK();
 }
 
+double DeviceSelector::theoreticalBandwidth(const DeviceInfo& dev) const {
+    const auto& p = sched_params_;
+    double gbps = dev.bw_gbps.load(std::memory_order_relaxed);
+    if (gbps < p.min_bandwidth_gbps || gbps > p.max_bandwidth_gbps)
+        gbps = p.default_bandwidth_gbps;
+    return gbps * 1e9 / 8.0;
+}
+
+Status DeviceSelector::setDeviceBandwidth(int dev_id, double gbps) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end())
+        return Status::InvalidArgument("device not found");
+    auto& dev = it->second;
+    const auto& p = sched_params_;
+    if (gbps < p.min_bandwidth_gbps || gbps > p.max_bandwidth_gbps) {
+        LOG(WARNING) << "Device " << local_topology_->getNicName(dev_id)
+                     << " link speed " << gbps << " Gbps is "
+                     << (gbps <= 0.0 ? "unknown" : "outside the valid range")
+                     << ", assuming " << p.default_bandwidth_gbps << " Gbps";
+    }
+    dev.bw_gbps.store(gbps, std::memory_order_relaxed);
+    // A worker completing between these stores clamps the old EWMA against
+    // the new rate once; the seeds below overwrite it.
+    const double seed = theoreticalBandwidth(dev);
+    dev.ewma_bandwidth_bps.store(seed, std::memory_order_relaxed);
+    dev.ewma_transmit_bps.store(seed, std::memory_order_relaxed);
+    return Status::OK();
+}
+
+Status DeviceSelector::setDeviceAvailable(int dev_id, bool available) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end())
+        return Status::InvalidArgument("device not found");
+    it->second.available.store(available, std::memory_order_relaxed);
+    return Status::OK();
+}
+
+bool DeviceSelector::isDeviceAvailable(int dev_id) const {
+    return usable(dev_id);
+}
+
 Status DeviceSelector::enableSharedQuota(const std::string& shm_name) {
     slot_manager_ = std::make_shared<SharedSlotManager>(this);
     slot_manager_->setRotationIntervalMs(
@@ -85,8 +129,9 @@ Status DeviceSelector::allocate(uint64_t total_length, uint32_t num_slices,
             thread_local std::vector<int> tl_eligible;
             tl_eligible.clear();
             for (int dev_id : entry->device_list[rank]) {
-                if (!devices_.count(dev_id)) continue;
+                if (!usable(dev_id)) continue;
                 if ((device_mask & (1ULL << dev_id)) == 0) continue;
+                if (!isNumaEligible(entry, dev_id)) continue;
                 tl_eligible.push_back(dev_id);
             }
             if (tl_eligible.empty()) continue;
@@ -97,15 +142,20 @@ Status DeviceSelector::allocate(uint64_t total_length, uint32_t num_slices,
                 int dev_id = tl_eligible[tl_rr_counter % tl_eligible.size()];
                 tl_rr_counter++;
                 slice_dev_ids.push_back(dev_id);
+                // Last slice takes what is left; see the header.
                 uint64_t this_slice_bytes =
-                    std::min(slice_bytes, total_length - offset);
+                    (i + 1 == num_slices)
+                        ? total_length - offset
+                        : std::min(slice_bytes, total_length - offset);
                 offset += this_slice_bytes;
+                // Baseline mode does not track inflight (release() and
+                // chargeDevice() skip it too); only lifetime traffic counts.
                 devices_[dev_id].total_bytes.fetch_add(
                     this_slice_bytes, std::memory_order_relaxed);
             }
             return Status::OK();
         }
-        return Status::DeviceNotFound("no eligible devices");
+        return Status::DeviceNotFound(noEligibleDeviceReason());
     }
 
     std::vector<DeviceSelector::Candidate> tl_candidates;
@@ -120,12 +170,45 @@ Status DeviceSelector::allocate(uint64_t total_length, uint32_t num_slices,
         // to ensure all devices are sampled for EWMA updates
         thread_local uint64_t tl_call_count = 0;
         bool probe_mode = ((++tl_call_count % 100) == 0);
-        selectMultiPath(tl_candidates, num_slices, total_length, slice_dev_ids,
-                        probe_mode);
+        selectMultiPath(tl_candidates, num_slices, total_length, slice_bytes,
+                        slice_dev_ids, probe_mode);
     }
     return Status::OK();
 }
 
+void DeviceSelector::auditStrictLocalNuma() const {
+    if (!sched_params_.strict_local_numa || !local_topology_) return;
+
+    size_t excludable = 0;
+    for (const auto& mem : local_topology_->mem_list_) {
+        bool has_nic = false, has_local_nic = false;
+        for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
+            for (int dev_id : mem.device_list[rank]) {
+                if (devices_.find(dev_id) == devices_.end()) continue;
+                has_nic = true;
+                if (local_topology_->isCrossNuma(mem, dev_id))
+                    excludable++;
+                else
+                    has_local_nic = true;
+            }
+        }
+        if (has_nic && !has_local_nic) {
+            LOG(WARNING) << "strict_local_numa: location " << mem.name
+                         << " (NUMA " << mem.numa_node
+                         << ") has no same-NUMA RDMA NIC; transfers from it "
+                            "will fail with DeviceNotFound";
+        }
+    }
+
+    if (excludable == 0) {
+        LOG(WARNING) << "strict_local_numa is enabled but no NIC can be "
+                        "classified as cross-NUMA on this host (custom "
+                        "priority matrix, VM, or sysfs without NUMA info), so "
+                        "the flag has no effect and cross-NUMA NICs keep the "
+                        "numa_penalties soft penalty";
+    }
+}
+
 int DeviceSelector::getDeviceRank(const std::string& location,
                                   int dev_id) const {
     auto entry = local_topology_->getMemEntry(location);
@@ -167,8 +250,9 @@ Status DeviceSelector::buildCandidates(const Topology::MemEntry* entry,
     // First pass: filter by device priority (QoS filtering)
     for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
         for (int dev_id : entry->device_list[rank]) {
-            if (!devices_.count(dev_id)) continue;
+            if (!usable(dev_id)) continue;
             if ((device_mask & (1ULL << dev_id)) == 0) continue;
+            if (!isNumaEligible(entry, dev_id)) continue;
             // QoS: Get device's current priority slot (local, per-process)
             // Device accepts request if dev_priority >= request_priority
             int dev_priority = PRIO_LOW;  // Default: accept all
@@ -180,19 +264,20 @@ Status DeviceSelector::buildCandidates(const Topology::MemEntry* entry,
         }
     }
 
-    // If no devices after filtering, fallback to all devices
+    // Retry without QoS filtering; availability and NUMA exclusion stay.
     if (candidates.empty()) {
         for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
             for (int dev_id : entry->device_list[rank]) {
-                if (!devices_.count(dev_id)) continue;
+                if (!usable(dev_id)) continue;
                 if ((device_mask & (1ULL << dev_id)) == 0) continue;
+                if (!isNumaEligible(entry, dev_id)) continue;
                 add_candidate(dev_id, rank);
             }
         }
     }
 
     if (candidates.empty()) {
-        return Status::DeviceNotFound("no eligible devices");
+        return Status::DeviceNotFound(noEligibleDeviceReason());
     }
 
     std::sort(
@@ -225,19 +310,17 @@ void DeviceSelector::selectSinglePath(const std::vector<Candidate>& candidates,
 
 void DeviceSelector::selectMultiPath(const std::vector<Candidate>& candidates,
                                      uint32_t num_slices, uint64_t total_length,
+                                     uint64_t slice_bytes,
                                      std::vector<int>& slice_dev_ids,
                                      bool probe_mode) {
     if (candidates.empty()) return;
-    uint64_t slice_bytes = (total_length + num_slices - 1) / num_slices;
+    const size_t first = slice_dev_ids.size();
     if (probe_mode) {
         // Probe mode: round-robin distribution to ensure all devices are
         // sampled Activates every 100th call to prevent EWMA starvation
         for (uint32_t i = 0; i < num_slices; ++i) {
             const Candidate& c = candidates[i % candidates.size()];
             slice_dev_ids.push_back(c.dev_id);
-            devices_[c.dev_id].addInflight(slice_bytes);
-            devices_[c.dev_id].total_bytes.fetch_add(slice_bytes,
-                                                     std::memory_order_relaxed);
         }
     } else {
         // Normal mode: weighted distribution based on inverse score
@@ -269,11 +352,6 @@ void DeviceSelector::selectMultiPath(const std::vector<Candidate>& candidates,
                 for (uint32_t s = 0; s < assigned; ++s) {
                     slice_dev_ids.push_back(c.dev_id);
                 }
-                uint64_t total_assigned_bytes =
-                    static_cast<uint64_t>(slice_bytes) * assigned;
-                devices_[c.dev_id].addInflight(total_assigned_bytes);
-                devices_[c.dev_id].total_bytes.fetch_add(
-                    total_assigned_bytes, std::memory_order_relaxed);
             }
         }
         if (remaining_slices > 0) {
@@ -281,19 +359,38 @@ void DeviceSelector::selectMultiPath(const std::vector<Candidate>& candidates,
             for (uint32_t s = 0; s < remaining_slices; ++s) {
                 slice_dev_ids.push_back(c.dev_id);
             }
-            uint64_t total_assigned_bytes =
-                static_cast<uint64_t>(slice_bytes) * remaining_slices;
-            devices_[c.dev_id].addInflight(total_assigned_bytes);
-            devices_[c.dev_id].total_bytes.fetch_add(total_assigned_bytes,
-                                                     std::memory_order_relaxed);
         }
     }
+    // Charge each device what its slices actually carry, in the caller's
+    // slice order, so release() (which returns the slice's length) balances
+    // per device; ceil(total / n) per slice would not. The last slice takes
+    // what is left rather than a whole block -- planRdmaSlices() folds a
+    // short tail into it -- so it can be longer than slice_bytes, and
+    // charging it a block would leave the fold released but never charged.
+    uint64_t offset = 0;
+    for (size_t i = first; i < slice_dev_ids.size(); ++i) {
+        const uint64_t bytes =
+            (i + 1 == slice_dev_ids.size())
+                ? total_length - offset
+                : std::min(slice_bytes, total_length - offset);
+        offset += bytes;
+        auto& dev = devices_[slice_dev_ids[i]];
+        dev.addInflight(bytes);
+        dev.total_bytes.fetch_add(bytes, std::memory_order_relaxed);
+    }
 }
 
 Status DeviceSelector::allocate(uint64_t length, const std::string& location,
                                 int& chosen_dev_id) {
+    return allocate(length, location, chosen_dev_id, PRIO_HIGH, ~0ULL);
+}
+
+Status DeviceSelector::allocate(uint64_t length, const std::string& location,
+                                int& chosen_dev_id, int priority,
+                                uint64_t device_mask) {
     std::vector<int> slice_dev_ids;
-    Status status = allocate(length, 1, length, location, slice_dev_ids, ~0ULL);
+    Status status = allocate(length, 1, length, location, slice_dev_ids,
+                             priority, device_mask);
     if (!status.ok()) return status;
     if (slice_dev_ids.empty()) {
         return Status::DeviceNotFound("allocation failed");
@@ -302,37 +399,160 @@ Status DeviceSelector::allocate(uint64_t length, const std::string& location,
     return Status::OK();
 }
 
-Status DeviceSelector::release(int dev_id, uint64_t length, double latency) {
+Status DeviceSelector::chargeDevice(int dev_id, uint64_t length) {
     auto it = devices_.find(dev_id);
     if (it == devices_.end())
         return Status::InvalidArgument("device not found");
+    // Inflight is only tracked in smart mode; see allocate() and release().
+    if (smart_selection_enabled_) it->second.addInflight(length);
+    // Each attempt is bytes this NIC is asked to move, so a retry -- or a
+    // first attempt that fell back to another NIC -- counts again here:
+    // total_bytes is a lifetime traffic figure, not a request count.
+    it->second.total_bytes.fetch_add(length, std::memory_order_relaxed);
+    return Status::OK();
+}
 
+void DeviceSelector::learnRate(const DeviceInfo& dev,
+                               std::atomic<double>& series, double alpha,
+                               double observed_bps) const {
+    // EWMA update: new = α × old + (1-α) × observed
+    // α = 0: always use observed (full adaptation)
+    // α = 1: never update (no learning)
+    // Clamped to [min_multiplier, max_multiplier] of theoretical bandwidth.
+    const double theoretical_bw = theoreticalBandwidth(dev);
+    const double current = series.load(std::memory_order_relaxed);
+    double updated = alpha * current + (1.0 - alpha) * observed_bps;
+    updated = std::max(
+        sched_params_.ewma_min_multiplier * theoretical_bw,
+        std::min(sched_params_.ewma_max_multiplier * theoretical_bw, updated));
+    series.store(updated, std::memory_order_relaxed);
+}
+
+void DeviceSelector::notePosted(int dev_id, uint64_t bytes, uint64_t now_ns) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return;
     auto& dev = it->second;
-    dev.releaseInflight(length);
+    // The read-modify-write picks exactly one thread to see each transition,
+    // so a busy stretch is opened once however many workers post at once.
+    if (dev.posted_bytes.fetch_add(bytes, std::memory_order_relaxed) == 0)
+        dev.busy_since.store(now_ns, std::memory_order_relaxed);
+}
+
+void DeviceSelector::notePostEnded(int dev_id, uint64_t bytes,
+                                   uint64_t now_ns) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return;
+    auto& dev = it->second;
+    if (dev.posted_bytes.fetch_sub(bytes, std::memory_order_relaxed) != bytes)
+        return;  // still busy
+    // Bank the stretch that just ended. A neighbour opening the next stretch
+    // between the subtraction above and this read would leave `since` ahead
+    // of `now_ns`; bank nothing rather than an underflowed interval. It
+    // costs one burst's busy time and reads the link fast, so it is bounded
+    // and the smoothing absorbs it.
+    const uint64_t since = dev.busy_since.load(std::memory_order_relaxed);
+    if (now_ns > since)
+        dev.busy_ns.fetch_add(now_ns - since, std::memory_order_relaxed);
+}
+
+uint64_t DeviceSelector::getBusyNs(int dev_id) const {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return 0;
+    return it->second.busy_ns.load(std::memory_order_relaxed);
+}
+
+uint64_t DeviceSelector::getPostedBytes(int dev_id) const {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return 0;
+    return it->second.getPostedBytes();
+}
 
-    // Cancellation of an unposted slice must release its inflight charge but
-    // has no latency sample from which to learn bandwidth.
-    if (!smart_selection_enabled_ || latency <= 0.0) {
-        return Status::OK();
+void DeviceSelector::noteCompleted(int dev_id, uint64_t bytes) {
+    auto it = devices_.find(dev_id);
+    if (it != devices_.end())
+        it->second.completed_bytes.fetch_add(bytes, std::memory_order_relaxed);
+}
+
+uint64_t DeviceSelector::busyNsAt(const DeviceInfo& dev, uint64_t now_ns) {
+    uint64_t busy = dev.busy_ns.load(std::memory_order_relaxed);
+    if (dev.posted_bytes.load(std::memory_order_relaxed) > 0) {
+        const uint64_t since = dev.busy_since.load(std::memory_order_relaxed);
+        if (now_ns > since) busy += now_ns - since;
     }
+    return busy;
+}
 
-    // Update EWMA bandwidth: new = α × old + (1-α) × observed
-    // α = 0: always use observed (full adaptation)
-    // α = 1: never update (no learning)
-    double observed_bw = static_cast<double>(length) / latency;
-    double current_ewma = dev.getEwmaBandwidth();
+void DeviceSelector::resetTransmitMeter(int dev_id) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return;
+    // One store, so it cannot interleave with a sampler's two baseline
+    // exchanges: the next maybeSampleTransmit sees prev == 0, takes both
+    // baselines itself under its CAS, and learns nothing from them.
+    it->second.meter_ts.store(0, std::memory_order_relaxed);
+}
 
-    double alpha = sched_params_.bandwidth_learning_rate;
-    double new_ewma = alpha * current_ewma + (1.0 - alpha) * observed_bw;
+void DeviceSelector::maybeSampleTransmit(int dev_id, uint64_t now_ns) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return;
+    auto& dev = it->second;
 
-    // Clamp to [min_multiplier, max_multiplier] of theoretical bandwidth
-    double theoretical_bw = dev.getTheoreticalBandwidth();
-    new_ewma = std::max(
-        sched_params_.ewma_min_multiplier * theoretical_bw,
-        std::min(sched_params_.ewma_max_multiplier * theoretical_bw, new_ewma));
+    uint64_t prev = dev.meter_ts.load(std::memory_order_relaxed);
+    // `now_ns <= prev`: a lane whose poll timestamp predates another lane's
+    // sample; letting it through would move the baseline backwards.
+    if (prev != 0 && (now_ns <= prev ||
+                      now_ns - prev < sched_params_.transmit_meter_interval_ns))
+        return;
+    // One sampler per interval: the loser leaves the counters alone.
+    if (!dev.meter_ts.compare_exchange_strong(
+            prev, now_ns, std::memory_order_acq_rel, std::memory_order_relaxed))
+        return;
+
+    const uint64_t completed =
+        dev.completed_bytes.load(std::memory_order_relaxed);
+    const uint64_t before =
+        dev.meter_completed.exchange(completed, std::memory_order_relaxed);
+
+    // Busy time up to now: what has been banked by the stretches that ended,
+    // plus the one still open. Charging the bytes to this instead of to
+    // elapsed wall time is what keeps a NIC that bursts and then waits from
+    // reading as a slow link -- the gap between bursts is not the link, and
+    // asking whether the NIC was busy when the interval opened cannot see it
+    // (a burst's first completion always has the rest of that burst behind
+    // it, so every interval opens busy).
+    const uint64_t busy = busyNsAt(dev, now_ns);
+    const uint64_t busy_before =
+        dev.meter_busy_ns.exchange(busy, std::memory_order_relaxed);
+
+    if (prev == 0) return;  // first sample: it only sets the baseline
+    // A sample spanning this much wall time describes a link too far back to
+    // attribute to the link as it is now, however busy it was.
+    if (now_ns - prev > sched_params_.transmit_meter_max_interval_ns) return;
+    if (completed <= before || busy <= busy_before) return;
+
+    learnRate(
+        dev, dev.ewma_transmit_bps,
+        sched_params_.transmit_bandwidth_learning_rate,
+        static_cast<double>(completed - before) / ((busy - busy_before) / 1e9));
+}
 
-    dev.ewma_bandwidth_bps.store(new_ewma, std::memory_order_relaxed);
+Status DeviceSelector::release(int dev_id, uint64_t length, double latency) {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end())
+        return Status::InvalidArgument("device not found");
 
+    auto& dev = it->second;
+    // Inflight is only ever charged in smart mode; releasing in baseline mode
+    // would drive the unsigned counter below zero.
+    if (!smart_selection_enabled_) return Status::OK();
+    dev.releaseInflight(length);
+
+    // A release with no latency sample -- cancelled, timed out, failed,
+    // swept off a queue pair, or moved to another device -- learns nothing.
+    if (latency <= 0.0) return Status::OK();
+
+    learnRate(dev, dev.ewma_bandwidth_bps,
+              sched_params_.bandwidth_learning_rate,
+              static_cast<double>(length) / latency);
     return Status::OK();
 }
 
@@ -341,6 +561,10 @@ Status DeviceSelector::getNicLoadStats(std::vector<NicLoadStats>& stats) const {
     // devices_ is populated during topology load and remains stable while
     // transfers update the per-device atomic counters below.
     for (const auto& [dev_id, dev] : devices_) {
+        // Same rule as the aggregate: a NIC that cannot carry traffic has
+        // no meaningful load or bandwidth to report, and with zero inflight
+        // it would score as the best NIC of the lot.
+        if (!dev.available.load(std::memory_order_relaxed)) continue;
         std::string device_name = local_topology_->getNicName(dev_id);
         if (device_name.empty()) device_name = std::to_string(dev_id);
         stats.push_back(NicLoadStats{
@@ -395,10 +619,32 @@ int DeviceSelector::getDevicePriority(int dev_id) const {
 double DeviceSelector::getAggregateEwmaBandwidth() const {
     double total = 0.0;
     for (const auto& [id, dev] : devices_) {
+        if (!dev.available.load(std::memory_order_relaxed)) continue;
         total += dev.getEwmaBandwidth();
     }
     return total > 0.0 ? total : -1.0;
 }
 
+uint64_t DeviceSelector::getInflightBytes(int dev_id) const {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return 0;
+    return it->second.getInflightBytes();
+}
+
+double DeviceSelector::getTransmitBandwidth(int dev_id) const {
+    auto it = devices_.find(dev_id);
+    if (it == devices_.end()) return -1.0;
+    return it->second.getTransmitBandwidth();
+}
+
+double DeviceSelector::getAggregateTransmitBandwidth() const {
+    double total = 0.0;
+    for (const auto& [id, dev] : devices_) {
+        if (!dev.available.load(std::memory_order_relaxed)) continue;
+        total += dev.getTransmitBandwidth();
+    }
+    return total > 0.0 ? total : -1.0;
+}
+
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/rail_monitor.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/rail_monitor.cpp
index 21e6f904f5..085abd0fa7 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/rail_monitor.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/rail_monitor.cpp
@@ -17,21 +17,75 @@
 namespace mooncake {
 namespace tent {
 
-Status RailMonitor::load(const Topology* local, const Topology* remote,
+namespace {
+
+bool sameNicLayout(const Topology::NicEntry& a, const Topology::NicEntry& b) {
+    return a.name == b.name && a.pci_bus_id == b.pci_bus_id &&
+           a.type == b.type && a.numa_node == b.numa_node;
+}
+
+bool sameMemLayout(const Topology::MemEntry& a, const Topology::MemEntry& b) {
+    if (a.name != b.name || a.pci_bus_id != b.pci_bus_id || a.type != b.type ||
+        a.numa_node != b.numa_node)
+        return false;
+    for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
+        if (a.device_list[rank] != b.device_list[rank]) return false;
+    }
+    return true;
+}
+
+// True when two snapshots describe the same NIC/memory wiring. Segment
+// metadata is copy-on-write, so a buffer register publishes a new Topology*
+// even when the rail map is unchanged. Comparing layout (not pointer
+// identity) lets load() refresh pins without rebuilding rail_states_.
+bool sameRailLayout(const Topology* a, const Topology* b) {
+    if (a == b) return true;
+    if (!a || !b) return false;
+    const size_t nic_count = a->getNicCount();
+    const size_t mem_count = a->getMemCount();
+    if (nic_count != b->getNicCount() || mem_count != b->getMemCount())
+        return false;
+    for (size_t i = 0; i < nic_count; ++i) {
+        auto* ea = a->getNicEntry(static_cast<int>(i));
+        auto* eb = b->getNicEntry(static_cast<int>(i));
+        if (!ea || !eb || !sameNicLayout(*ea, *eb)) return false;
+    }
+    for (size_t i = 0; i < mem_count; ++i) {
+        auto* ea = a->getMemEntry(static_cast<int>(i));
+        auto* eb = b->getMemEntry(static_cast<int>(i));
+        if (!ea || !eb || !sameMemLayout(*ea, *eb)) return false;
+    }
+    return true;
+}
+
+}  // namespace
+
+Status RailMonitor::load(std::shared_ptr<const Topology> local,
+                         std::shared_ptr<const Topology> remote,
                          const std::string& rail_topo_json,
                          const Config* conf) {
-    local_ = local;
-    remote_ = remote;
+    const bool first_load = !ready_;
+    const bool same_layout = ready_ &&
+                             sameRailLayout(local_.get(), local.get()) &&
+                             sameRailLayout(remote_.get(), remote.get());
+
+    local_ = std::move(local);
+    remote_ = std::move(remote);
     if (conf) {
         error_threshold_ = conf->get(kCfgErrorThreshold, error_threshold_);
         error_window_ = std::chrono::seconds(
             conf->get(kCfgErrorWindowSecs, (int)error_window_.count()));
         cooldown_ = std::chrono::seconds(
             conf->get(kCfgCooldownSecs, (int)cooldown_.count()));
-        LOG(INFO) << "RailMonitor: error_threshold=" << error_threshold_
-                  << " error_window=" << error_window_.count() << "s"
-                  << " cooldown=" << cooldown_.count() << "s";
+        // Config is identical on every COW snapshot refresh. Log once per
+        // monitor so PD/e2e does not reprint the banner per slice/worker.
+        if (first_load) {
+            LOG(INFO) << "RailMonitor: error_threshold=" << error_threshold_
+                      << " error_window=" << error_window_.count() << "s"
+                      << " cooldown=" << cooldown_.count() << "s";
+        }
     }
+    if (same_layout) return Status::OK();
     if (!rail_topo_json.empty()) {
         auto status = loadFromJson(rail_topo_json);
         if (status.ok()) return status;
@@ -45,9 +99,8 @@ bool RailMonitor::available(int local_nic, int remote_nic) {
     if (it == rail_states_.end()) return false;
     auto& st = it->second;
     if (!st.paused()) return true;
-    if (std::chrono::steady_clock::now() < st.resume_time) return false;
-    // Cooldown expired: clear all exponential-backoff memory so a fresh
-    // failure cycle starts from the initial cooldown_, not a doubled value.
+    auto now = std::chrono::steady_clock::now();
+    if (now < st.resume_time) return false;
     st.resume_time = {};
     st.error_count = 0;
     st.cooldown = std::chrono::seconds(0);
@@ -68,15 +121,45 @@ void RailMonitor::markFailed(int local_nic, int remote_nic) {
         st.error_count++;
     }
     st.last_error = now;
-    if (st.cooldown.count() == 0) {
-        st.cooldown = cooldown_;
-    } else {
-        st.cooldown *= 2;
-        if (st.cooldown > kMaxCooldown) st.cooldown = kMaxCooldown;
-    }
+
+    const bool was_paused = st.paused();
+
     if (st.error_count >= error_threshold_) {
-        st.resume_time = now + st.cooldown;
-        updateBestMapping();
+        if (!was_paused) {
+            // Escalate the cooldown only when a *fresh* pause arms (the rail
+            // was healthy at this instant), never within an ongoing burst.
+            // Previously cooldown was doubled on every markFailed call, so a
+            // single outage -- N error WQEs landing in one 10s window -- pushed
+            // a 30s pause straight to the 300s cap before the outage even
+            // cleared, forcing a ~5min TCP fallback after the peer had already
+            // recovered. Now the cooldown is set once per pause cycle; errors
+            // arriving while already paused do not multiply it.
+            //
+            // cooldown == 0: the previous cycle ended with a proven-healthy
+            //   recovery (markRecovered reset it), so start from the initial
+            //   value. cooldown != 0: left by a cooldown-expiry recovery (time
+            //   elapsed, health not proven); escalate to back off harder.
+            if (st.cooldown.count() == 0) {
+                st.cooldown = cooldown_;
+            } else {
+                st.cooldown *= 2;
+                if (st.cooldown > kMaxCooldown) st.cooldown = kMaxCooldown;
+            }
+            LOG(INFO) << "Rail paused: local_nic=" << local_nic
+                      << " remote_nic=" << remote_nic
+                      << " (errors=" << st.error_count << " in "
+                      << error_window_.count()
+                      << "s, cooldown=" << st.cooldown.count() << "s)";
+            st.resume_time = now + st.cooldown;
+            updateBestMapping();
+        }
+        // Already paused: leave resume_time and cooldown untouched. Re-arming
+        // or escalating here would let a sustained outage extend the pause
+        // indefinitely -- the original defect. The pause runs its course and
+        // available() reopens on cooldown expiry.
+        // Open-phase probing and Half-Open (admit one trial on expiry, escalate
+        // on trial failure) are follow-ups: they need available() split into a
+        // non-mutating predicate plus an admit() with in-flight tracking.
     }
 }
 
@@ -231,7 +314,8 @@ Status RailMonitor::loadDefault() {
         if (matched) continue;
 
         // Priority 2: CUDA memory topology matching (GPU-direct NIC)
-        int remote_nic = matchRemoteNicId(local_, remote_, local_nic);
+        int remote_nic =
+            matchRemoteNicId(local_.get(), remote_.get(), local_nic);
         if (remote_nic >= 0) {
             remote_load[remote_nic]++;
             direct_rails_[local_nic] = remote_nic;
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/rdma_transport.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/rdma_transport.cpp
index 6a82670d45..0a5ba7ce2f 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/rdma_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/rdma_transport.cpp
@@ -20,13 +20,13 @@
 #include <sys/mman.h>
 #include <sys/time.h>
 
+#include <algorithm>
 #include <cassert>
 #include <cerrno>
 #include <cstddef>
 #include <cstdlib>
 #include <future>
 #include <limits>
-#include <set>
 #include <sstream>
 
 #include "tent/common/status.h"
@@ -35,6 +35,7 @@
 #include "tent/transport/rdma/endpoint_store.h"
 #include "tent/transport/rdma/workers.h"
 #include "tent/common/utils/string_builder.h"
+#include "tent/runtime/platform.h"
 #include "tent/runtime/topology.h"
 #include "tent/common/utils/random.h"
 #include "tent/thirdparty/nlohmann/json.h"
@@ -53,6 +54,8 @@ namespace tent {
 
 namespace {
 
+constexpr uint64_t kDefaultRdmaQuiesceTimeoutNs = 10000000000ull;
+
 uint16_t getRdmaBindDefaultPort(const Config& config) {
     constexpr const char* kKey = "rpc_server_port";
     if (!config.contains(kKey)) return 0;
@@ -248,13 +251,14 @@ static bool isGpuDirectRdmaSupported(std::shared_ptr<Config> conf) {
     // Detect vendor GPUDirect/peer-memory drivers from /proc/modules.
     // NVIDIA: nvidia_peermem. AMD: peermem is built into amdgpu (linked with
     // ib_core), so the amdgpu module itself is the presence signal.
+    // Hygon: the hycu driver provides the same peer-memory support.
     std::ifstream modules("/proc/modules");
     std::string line;
     while (std::getline(modules, line)) {
         const auto name_end = line.find(' ');
         const auto name =
             name_end == std::string::npos ? line : line.substr(0, name_end);
-        if (name == "nvidia_peermem" || name == "amdgpu") {
+        if (name == "nvidia_peermem" || name == "amdgpu" || name == "hycu") {
             return true;
         }
     }
@@ -278,18 +282,22 @@ size_t RdmaTransport::initializeContexts() {
     size_t context_count = 0;
     for (size_t i = 0; i < local_topology_->getNicCount(); ++i) {
         auto entry = local_topology_->getNicEntry(i);
-        auto context = std::make_shared<RdmaContext>(*this);
-        context_set_.push_back(context);
-        if (entry->type != Topology::NIC_RDMA) continue;
-        int ret = context->construct(entry->name, params_);
-        if (ret) {
+        if (entry->type == Topology::NIC_RDMA) {
+            auto context = std::make_shared<RdmaContext>(*this);
+            if (context->construct(entry->name, params_) == 0) {
+                context_name_lookup_[entry->name] = i;
+                ++context_count;
+                local_buffer_manager_.addDevice(context.get());
+                context_set_.push_back(std::move(context));
+                continue;
+            }
             LOG(WARNING) << "Disable RDMA device " << entry->name << " because "
                          << "of initialization failure";
-            continue;
         }
-        context_name_lookup_[entry->name] = i;
-        ++context_count;
-        local_buffer_manager_.addDevice(context.get());
+        // A never-constructed context, not the one whose construct() failed:
+        // the slot only has to stand in for the NicID, so it should not carry
+        // a device name or an endpoint store it will never use.
+        context_set_.push_back(std::make_shared<RdmaContext>(*this));
     }
     return context_count;
 }
@@ -373,7 +381,38 @@ Status RdmaTransport::install(std::string& local_segment_name,
     return Status::OK();
 }
 
+Status RdmaTransport::quiesce() {
+    uint64_t timeout_ns = kDefaultRdmaQuiesceTimeoutNs;
+    if (conf_) {
+        timeout_ns = conf_->get("transports/rdma/max_timeout_ns", timeout_ns);
+    }
+    Status drain = Status::OK();
+    if (workers_) {
+        drain = workers_->quiesce(timeout_ns);
+        if (!drain.ok()) {
+            LOG(ERROR) << "RDMA workers quiesce failed: " << drain.ToString();
+        }
+    }
+    const Status sync =
+        Platform::getLoader().synchronizeDevices(local_topology_.get());
+    if (!sync.ok()) {
+        LOG(WARNING) << "RDMA dest-GPU sync during quiesce failed: "
+                     << sync.ToString();
+    }
+    return drain;
+}
+
 Status RdmaTransport::uninstall() {
+    // ControlService may still receive BootstrapRdma RPCs while uninstall is
+    // running. Unregister and drain the callback before destroying workers,
+    // contexts, and other state used by onSetupRdmaConnections(). Keep this
+    // outside installed_ so partially-installed transports are covered too.
+    if (metadata_) metadata_->setBootstrapRdmaCallback(nullptr);
+
+    // Drain CQ and dest-GPU visibility while MRs and QPs are still alive.
+    // Idempotent when deconstruct() already called quiesce().
+    (void)quiesce();
+
     if (installed_) {
         // Stop notification worker thread
         notify_worker_running_ = false;
@@ -382,6 +421,14 @@ Status RdmaTransport::uninstall() {
         }
 
         workers_.reset();
+        // Workers joined: nothing can name an orphan any more.
+        {
+            std::lock_guard<std::mutex> guard(orphan_slice_mutex_);
+            for (auto& orphan : orphan_slices_)
+                RdmaSliceStorage::Get().deallocate(orphan.slice);
+            orphan_slices_.clear();
+            orphans_pending_.store(false, std::memory_order_release);
+        }
         metadata_.reset();
         local_buffer_manager_.clear();
         context_set_.clear();
@@ -406,26 +453,45 @@ Status RdmaTransport::freeSubBatch(SubBatchRef& batch) {
     auto rdma_batch = dynamic_cast<RdmaSubBatch*>(batch);
     if (!rdma_batch)
         return Status::InvalidArgument("Invalid RDMA sub-batch" LOC_MARK);
+    // Settle what an earlier free left behind before adding to it: an orphan
+    // whose handler has since finished is freed here rather than waiting for
+    // the monitor's next second.
+    if (orphans_pending_.load(std::memory_order_acquire))
+        reapOrphanSlices(/*on_tick=*/false);
     for (auto* task : rdma_batch->task_list) {
         task->deref();  // Release batch's reference to the task
     }
     rdma_batch->task_list.clear();
+    // A slice still owed a completion cannot go back to the slab: its
+    // address is a live work-request id, and the next transfer would get
+    // that storage, so the stale completion would resolve somebody else's
+    // slice and report bytes that never moved. The batch being terminal
+    // does not rule this out -- a timeout resolves a slice while its work
+    // request is live. Hand those over; the batch itself is freed now.
+    std::vector<OrphanSlice> orphans;
     for (auto slice : rdma_batch->slice_chain) {
         while (slice) {
             auto next = slice->next;
-            RdmaSliceStorage::Get().deallocate(slice);
+            if (slice->completions_owed.load(std::memory_order_acquire) > 0) {
+                slice->next = nullptr;  // it leaves the chain behind
+                orphans.push_back({slice, 0});
+            } else {
+                RdmaSliceStorage::Get().deallocate(slice);
+            }
             slice = next;
         }
     }
+    if (!orphans.empty()) {
+        std::lock_guard<std::mutex> guard(orphan_slice_mutex_);
+        orphan_slices_.insert(orphan_slices_.end(), orphans.begin(),
+                              orphans.end());
+        orphans_pending_.store(true, std::memory_order_release);
+    }
     Slab<RdmaSubBatch>::Get().deallocate(rdma_batch);
     batch = nullptr;
     return Status::OK();
 }
 
-static inline uint64_t roundup(uint64_t a, uint64_t b) {
-    return (a % b == 0) ? a : (a / b + 1) * b;
-}
-
 Status RdmaTransport::submitTransferTasks(
     SubBatchRef batch, const std::vector<Request>& request_list) {
     auto rdma_batch = dynamic_cast<RdmaSubBatch*>(batch);
@@ -454,6 +520,7 @@ Status RdmaTransport::submitTransferTasks(
         auto* task = RdmaTaskStorage::Get().allocate();
         rdma_batch->task_list.push_back(task);
         task->request = request;
+        task->device_mask = rdma_batch->device_mask;
         task->qp_pool = rdma_batch->qp_pool;  // RFC #2568 step 3
         task->num_slices = 0;
         task->status_word = PENDING;
@@ -464,22 +531,10 @@ Status RdmaTransport::submitTransferTasks(
         task->cancel_requested.store(false, std::memory_order_relaxed);
         task->ref();  // Batch holds a reference to the task
 
-        const double merge_ratio = 0.25;
-        uint64_t base_block = default_block_size;
-        uint64_t num_slices = (request.length + base_block - 1) / base_block;
-        num_slices = std::max<uint64_t>(
-            1, std::min<uint64_t>(num_slices, max_slice_count));
-
-        if (num_slices > 1) {
-            uint64_t tail = request.length % base_block;
-            if (tail > 0 &&
-                tail < static_cast<uint64_t>(base_block * merge_ratio)) {
-                num_slices = std::max<uint64_t>(1, num_slices - 1);
-            }
-        }
-
-        uint64_t block_size = roundup(
-            (request.length + num_slices - 1) / num_slices, default_block_size);
+        const auto plan =
+            planRdmaSlices(request.length, default_block_size, max_slice_count);
+        const uint64_t block_size = plan.block_size;
+        const uint64_t num_slices = plan.count;
 
         std::vector<int> slice_dev_ids;
         // Only if a single request is enough, we perform aggregated allocation
@@ -505,8 +560,12 @@ Status RdmaTransport::submitTransferTasks(
 
         uint64_t offset = 0;
         for (uint64_t slice_idx = 0; slice_idx < num_slices; ++slice_idx) {
-            uint64_t length =
-                std::min<uint64_t>(request.length - offset, block_size);
+            // The last slice takes what is left, which is a block plus a
+            // folded-in tail when the plan folded one; every other slice is
+            // exactly a block. See planRdmaSlices().
+            uint64_t length = (slice_idx + 1 == num_slices)
+                                  ? request.length - offset
+                                  : block_size;
             auto slice = RdmaSliceStorage::Get().allocate();
             slice->source_addr = (char*)request.source + offset;
             slice->target_addr = request.target_offset + offset;
@@ -514,7 +573,9 @@ Status RdmaTransport::submitTransferTasks(
             slice->task = task;
             slice->retry_count = 0;
             slice->last_fallback_idx = -1;
-            slice->quota_charged = false;
+            slice->charged_dev = -1;
+            slice->posted_dev = -1;
+            slice->counted_lane = -1;
             slice->ep_weak_ptr.reset();
             slice->word = PENDING;
             slice->next = nullptr;
@@ -524,7 +585,7 @@ Status RdmaTransport::submitTransferTasks(
             task->ref();  // Each slice holds a reference to the task
             if (slice_idx < slice_dev_ids.size()) {
                 slice->source_dev_id = slice_dev_ids[slice_idx];
-                slice->quota_charged = true;
+                slice->charged_dev = slice->source_dev_id;
             }
             offset += length;
             int part_id = next_worker_idx % num_workers;
@@ -550,6 +611,60 @@ Status RdmaTransport::submitTransferTasks(
     return Status::OK();
 }
 
+void RdmaTransport::reapOrphanSlices(bool on_tick) {
+    // Taken whole so the scan runs outside the lock: expired() reaches the
+    // endpoint's control block, which is a cache miss per slice once a spell
+    // of timeouts has filled this up. Survivors are compacted in place and
+    // the same buffer goes back, so a tick allocates nothing. A batch freed
+    // meanwhile appends to the emptied vector; those are kept too, and
+    // nothing here reads the order.
+    std::vector<OrphanSlice> taken;
+    {
+        std::lock_guard<std::mutex> guard(orphan_slice_mutex_);
+        taken.swap(orphan_slices_);
+    }
+    if (taken.empty()) return;
+
+    size_t kept = 0;
+    size_t warned = 0;
+    for (auto& orphan : taken) {
+        auto* slice = orphan.slice;
+        // The completion has been handled, or its endpoint is gone -- a
+        // provider clears a queue pair's completions when it is destroyed
+        // (mlx5 and mlx4 do), so none can name this slice afterwards.
+        // Exactly zero: a handler pays on its way out and submitSlices()
+        // counts the post under the queue pair lock that handler needs, so
+        // the count never goes negative; if it ever did, holding on is the
+        // safe way to be wrong.
+        const int owed =
+            slice->completions_owed.load(std::memory_order_acquire);
+        if (owed == 0 || slice->ep_weak_ptr.expired()) {
+            RdmaSliceStorage::Get().deallocate(slice);
+            continue;
+        }
+        // Still held, so its endpoint is still alive: a queue pair the
+        // teardown has not destroyed. Say so once, then keep holding -- an
+        // age cap would free a slice the completion queue may yet name.
+        if (on_tick && ++orphan.passes == orphan_warn_after_passes_) {
+            ++warned;
+            LOG(WARNING) << "Orphaned slice " << slice << " still owes " << owed
+                         << " completion(s) after " << orphan.passes
+                         << " reap passes and its endpoint is still alive; "
+                            "held until the queue pair is destroyed -- see "
+                            "the endpoint teardown log for why it is not";
+        }
+        taken[kept++] = orphan;
+    }
+    taken.resize(kept);
+
+    std::lock_guard<std::mutex> guard(orphan_slice_mutex_);
+    orphan_warnings_ += warned;
+    if (!orphan_slices_.empty())
+        taken.insert(taken.end(), orphan_slices_.begin(), orphan_slices_.end());
+    orphan_slices_.swap(taken);
+    orphans_pending_.store(!orphan_slices_.empty(), std::memory_order_release);
+}
+
 Status RdmaTransport::getTransferStatus(SubBatchRef batch, int task_id,
                                         TransferStatus& status) {
     auto rdma_batch = dynamic_cast<RdmaSubBatch*>(batch);
@@ -620,6 +735,67 @@ Status RdmaTransport::removeMemoryBuffer(BufferDesc& desc) {
     return local_buffer_manager_.removeBuffer(desc);
 }
 
+Status RdmaTransport::refreshLocalDeviceDesc(const std::string& device_name,
+                                             uint32_t lid,
+                                             const std::string& gid) {
+    if (!metadata_)
+        return Status::InvalidArgument(
+            "RDMA metadata is not initialized" LOC_MARK);
+
+    auto& manager = metadata_->segmentManager();
+    bool existed = false;
+    uint32_t previous_lid = 0;
+    std::string previous_gid;
+    CHECK_STATUS(manager.updateLocal([&](SegmentDesc& segment) -> Status {
+        if (segment.type != SegmentType::Memory)
+            return Status::InvalidArgument(
+                "Local segment is not a memory segment" LOC_MARK);
+        auto* device = segment.findDevice(device_name);
+        if (!device) {
+            auto& detail = std::get<MemorySegmentDesc>(segment.detail);
+            DeviceDesc added;
+            added.name = device_name;
+            added.lid = lid;
+            added.gid = gid;
+            detail.devices.push_back(std::move(added));
+            return Status::OK();
+        }
+        existed = true;
+        previous_lid = device->lid;
+        previous_gid = device->gid;
+        device->lid = lid;
+        device->gid = gid;
+        return Status::OK();
+    }));
+
+    auto status = manager.synchronizeLocal();
+    if (status.ok()) return status;
+
+    auto rollback = manager.updateLocal([&](SegmentDesc& segment) -> Status {
+        if (segment.type != SegmentType::Memory)
+            return Status::InvalidArgument(
+                "Local segment is not a memory segment" LOC_MARK);
+        auto& devices = std::get<MemorySegmentDesc>(segment.detail).devices;
+        auto it = std::find_if(devices.begin(), devices.end(),
+                               [&](const DeviceDesc& device) {
+                                   return device.name == device_name;
+                               });
+        if (it == devices.end()) return Status::OK();
+        if (!existed) {
+            devices.erase(it);
+        } else {
+            it->lid = previous_lid;
+            it->gid = previous_gid;
+        }
+        return Status::OK();
+    });
+    if (!rollback.ok()) {
+        LOG(ERROR) << "Failed to roll back RDMA address metadata for "
+                   << device_name << ": " << rollback.ToString();
+    }
+    return status;
+}
+
 Status RdmaTransport::setupLocalSegment() {
     auto& manager = metadata_->segmentManager();
     CHECK_STATUS(manager.updateLocal([&](SegmentDesc& segment) -> Status {
@@ -633,8 +809,9 @@ Status RdmaTransport::setupLocalSegment() {
             if (context->status() != RdmaContext::DEVICE_ENABLED) continue;
             DeviceDesc device_desc;
             device_desc.name = context->name();
-            device_desc.lid = context->lid();
-            device_desc.gid = context->gid();
+            const auto address = context->address();
+            device_desc.lid = address.lid;
+            device_desc.gid = address.gid;
             detail.devices.push_back(device_desc);
         }
         return Status::OK();
@@ -654,38 +831,59 @@ int RdmaTransport::onSetupRdmaConnections(const BootstrapDesc& peer_desc,
     }
     auto index = context_name_lookup_[local_nic_name];
     auto context = context_set_[index];
-    if (context->status() == RdmaContext::DEVICE_DISABLED) {
-        std::stringstream ss;
-        ss << "Device is down: " << peer_desc.local_nic_path;
-        LOG(ERROR) << ss.str();
-        local_desc.reply_msg = ss.str();
-        return -1;
-    }
-    auto endpoint =
-        context->endpointStore()->getOrInsert(peer_desc.local_nic_path);
-    if (!endpoint) {
+    auto ctx_status = context->status();
+    if (ctx_status != RdmaContext::DEVICE_ENABLED) {
         std::stringstream ss;
-        ss << "Cannot allocate endpoint: " << peer_desc.local_nic_path;
+        ss << "Device is not ready: " << peer_desc.local_nic_path;
         LOG(ERROR) << ss.str();
         local_desc.reply_msg = ss.str();
         return -1;
     }
-    auto status = endpoint->accept(peer_desc, local_desc);
-    if (!status.ok()) {
-        if (endpoint->status() == RdmaEndPoint::EP_DESTROYING ||
-            endpoint->status() == RdmaEndPoint::EP_DESTROYED) {
-            context->endpointStore()->remove(endpoint.get());
+    // Endpoints are never reset. A peer process that reused the same nic path
+    // (same IP:port after a restart) hits an EP_READY endpoint whose QPs no
+    // longer exist. accept() retires it and the next getOrInsert() creates a
+    // fresh one. Do that retry inside this RPC so the initiator receives a
+    // valid GID instead of an empty bootstrap reply.
+    auto store = context->endpointStore();
+    constexpr int kMaxAcceptAttempts = 2;
+    for (int attempt = 0; attempt < kMaxAcceptAttempts; ++attempt) {
+        auto endpoint = store->getOrInsert(peer_desc.local_nic_path);
+        if (!endpoint) {
+            std::stringstream ss;
+            ss << "Cannot allocate endpoint: " << peer_desc.local_nic_path;
+            LOG(ERROR) << ss.str();
+            local_desc.reply_msg = ss.str();
+            return -1;
+        }
+        local_desc = BootstrapDesc();
+        auto status = endpoint->accept(peer_desc, local_desc);
+        if (status.ok()) {
+            local_desc.reply_msg.clear();
+            return 0;
+        }
+        const auto ep_status = endpoint->status();
+        const bool retired = ep_status == RdmaEndPoint::EP_DESTROYING ||
+                             ep_status == RdmaEndPoint::EP_DESTROYED;
+        if (retired) {
+            store->remove(endpoint.get());
+            if (attempt + 1 < kMaxAcceptAttempts) {
+                LOG(INFO) << "Retrying RDMA bootstrap after retiring stale "
+                             "endpoint for "
+                          << peer_desc.local_nic_path;
+                continue;
+            }
         }
         LOG(ERROR) << status.ToString();
         local_desc.reply_msg = status.ToString();
         return -1;
     }
 
-    return 0;
+    return -1;
 }
 
 std::shared_ptr<RdmaEndPoint> RdmaTransport::getEndpoint(SegmentID target_id,
-                                                         int device_id) {
+                                                         int device_id,
+                                                         Status* failure) {
     std::string rpc_server_addr, target_seg_name, target_dev_name,
         target_nic_path_name;
 
@@ -713,6 +911,7 @@ std::shared_ptr<RdmaEndPoint> RdmaTransport::getEndpoint(SegmentID target_id,
 
     if (!status.ok()) {
         LOG(ERROR) << status.ToString();
+        if (failure) *failure = status;
         return nullptr;
     }
 
@@ -726,6 +925,10 @@ std::shared_ptr<RdmaEndPoint> RdmaTransport::getEndpoint(SegmentID target_id,
         }
     }
     if (!context) {
+        if (failure) {
+            *failure =
+                Status::DeviceNotFound("No enabled RDMA context" LOC_MARK);
+        }
         return nullptr;
     }
     std::shared_ptr<RdmaEndPoint> endpoint;
@@ -733,6 +936,10 @@ std::shared_ptr<RdmaEndPoint> RdmaTransport::getEndpoint(SegmentID target_id,
     endpoint = context->endpointStore()->getOrInsert(peer_name);
     if (!endpoint) {
         LOG(ERROR) << "Cannot allocate endpoint " << peer_name;
+        if (failure) {
+            *failure =
+                Status::InternalError("Cannot allocate endpoint" LOC_MARK);
+        }
         return nullptr;
     }
     if (endpoint->status() != RdmaEndPoint::EP_READY) {
@@ -746,21 +953,39 @@ std::shared_ptr<RdmaEndPoint> RdmaTransport::getEndpoint(SegmentID target_id,
                 LOG(ERROR) << "Unable to connect endpoint " << peer_name << ": "
                            << status.ToString();
             }
+            if (failure) *failure = status;
             return nullptr;
         }
     }
     return endpoint;
 }
 
+Status RdmaTransport::notifyStatusForEndpointFailure(const Status& failure) {
+    if (failure.IsRpcServiceError()) {
+        return Status::RpcServiceError(
+            "RDMA notification endpoint bootstrap failed; peer control "
+            "plane unreachable, not falling back to RPC: " +
+            std::string{failure.message()} + LOC_MARK);
+    }
+    return Status::DeviceNotFound("RDMA notification endpoint unavailable: " +
+                                  std::string{failure.message()} + LOC_MARK);
+}
+
 Status RdmaTransport::sendNotification(SegmentID target_id,
                                        const Notification& notify) {
-    auto endpoint = getEndpoint(target_id, LOCAL_SEGMENT_ID);
-    if (!endpoint) {
-        return Status::InternalError(
-            "Endpoint not found for notification" LOC_MARK);
-    }
+    // Both failures below mean nothing left this host. Unless the bootstrap
+    // RPC itself failed (see notifyStatusForEndpointFailure), the engine may
+    // still reach the peer over the control plane, so they are reported with
+    // codes TransferEngineImpl::sendNotification() recognizes as "channel
+    // unavailable" rather than as a generic internal error.
+    Status failure;
+    auto endpoint = getEndpoint(target_id, LOCAL_SEGMENT_ID, &failure);
+    if (!endpoint) return notifyStatusForEndpointFailure(failure);
+    // Notify QP not connected (the peer has none, or it was disabled after a
+    // fault), or the post itself was refused.
     if (!endpoint->sendNotification(notify.name, notify.msg)) {
-        return Status::InternalError("Failed to send notification" LOC_MARK);
+        return Status::RdmaError(
+            "RDMA notification channel unavailable" LOC_MARK);
     }
     return Status::OK();
 }
@@ -782,6 +1007,38 @@ void RdmaTransport::addNotificationToQueue(const std::string& name,
     notify_list_.emplace_back(name, msg);
 }
 
+namespace {
+// The notify QP carries its own host-memory send/recv buffers, so a local
+// length/protection/WQE fault is confined to notification state. The data QPs
+// of the same endpoint use separate WRs and MRs.
+bool isNotifyLocalFault(ibv_wc_status status) {
+    switch (status) {
+        case IBV_WC_LOC_LEN_ERR:
+        case IBV_WC_LOC_QP_OP_ERR:
+        case IBV_WC_LOC_PROT_ERR:
+        case IBV_WC_LOC_ACCESS_ERR:
+        case IBV_WC_MW_BIND_ERR:
+            return true;
+        default:
+            return false;
+    }
+}
+}  // namespace
+
+RdmaTransport::NotifyCompletionAction RdmaTransport::classifyNotifyCompletion(
+    ibv_wc_status status, bool endpoint_alive, bool endpoint_ready) {
+    // Every WR still posted on a retiring endpoint's notify QP flushes, which
+    // is expected and must stay quiet.
+    if (status == IBV_WC_WR_FLUSH_ERR && !endpoint_ready) {
+        return NotifyCompletionAction::SkipSilently;
+    }
+    if (!endpoint_alive) return NotifyCompletionAction::ReportOnly;
+    if (isNotifyLocalFault(status)) {
+        return NotifyCompletionAction::DisableNotification;
+    }
+    return NotifyCompletionAction::RetireEndpoint;
+}
+
 int RdmaTransport::processNotifyCompletions() {
     int total_completions = 0;
 
@@ -802,9 +1059,10 @@ int RdmaTransport::processNotifyCompletions() {
 
         // Process each completion
         for (int i = 0; i < completed; ++i) {
-            // Find endpoint by QP number before interpreting errors. A flush
-            // completion after endpoint unpublication is expected during
-            // retirement and should not flood logs.
+            // Find endpoint by QP number before interpreting errors. The QP
+            // stays published while the endpoint retires, so notifications
+            // that landed before the retirement are still handed out; the
+            // flushes that follow are told apart by the endpoint's state.
             std::shared_ptr<RdmaEndPoint> endpoint;
             {
                 RWSpinlock::ReadGuard guard(notify_endpoint_map_lock_);
@@ -814,14 +1072,46 @@ int RdmaTransport::processNotifyCompletions() {
                 }
             }
 
-            if (wc[i].status != IBV_WC_SUCCESS) {
-                if (wc[i].status == IBV_WC_WR_FLUSH_ERR &&
-                    (!endpoint ||
-                     endpoint->status() != RdmaEndPoint::EP_READY)) {
-                    continue;
+            // Released only once this completion has been consumed: the
+            // recv payload copied out of its slot, or the send / error path
+            // finished. finishDestroy() waits for this count and
+            // deconstructUnlocked() then frees the recv MR, so releasing it
+            // earlier would let the buffers go while the CQE is still in
+            // this batch. The ring depth and the CQ's completion order keep
+            // that from happening today; this makes it hold by construction,
+            // the way acknowledge() releases wr_depth on the data QPs only
+            // after the completion is handled.
+            struct NotifyInflightRelease {
+                RdmaEndPoint* ep;
+                ~NotifyInflightRelease() {
+                    if (ep) ep->noteNotifyCompletion();
                 }
+            } inflight_release{endpoint.get()};
+
+            if (wc[i].status != IBV_WC_SUCCESS) {
+                // A failed completion leaves this notify QP unusable for good
+                // and only the endpoint lifecycle builds a new one, so left
+                // alone the endpoint stays EP_READY and every later
+                // sendNotification() silently flushes. Retiring it also moves
+                // the data QPs to ERR, so that is reserved for faults which may
+                // mean the peer restarted or the path died. A notify QP that
+                // is retiring or already disabled only flushes from here on,
+                // and those completions stay quiet.
+                const bool endpoint_ready =
+                    endpoint && endpoint->status() == RdmaEndPoint::EP_READY &&
+                    endpoint->notifyConnected();
+                auto action = classifyNotifyCompletion(
+                    wc[i].status, endpoint != nullptr, endpoint_ready);
+                if (action == NotifyCompletionAction::SkipSilently) continue;
+
                 LOG(ERROR) << "Notification completion failed: " << wc[i].status
                            << ", qp_num=" << wc[i].qp_num;
+                if (action == NotifyCompletionAction::DisableNotification) {
+                    endpoint->disableNotification(
+                        "notify QP local completion error");
+                } else if (action == NotifyCompletionAction::RetireEndpoint) {
+                    endpoint->resetConnection("notify QP completion error");
+                }
                 continue;
             }
 
@@ -866,7 +1156,11 @@ double RdmaTransport::getEstimatedBandwidth() const {
     if (!workers_) return -1.0;
     auto* sel = workers_->getDeviceSelector();
     if (!sel) return -1.0;
-    return sel->getAggregateEwmaBandwidth();
+    // The transmit estimate, not the selection EWMA: the admission queue
+    // asks "how fast do bytes move once they are sent", and adds the wait
+    // behind earlier work itself (DeadlineMlu's bytes_ahead), so the rate
+    // must not fold that wait in the way the selection sample does.
+    return sel->getAggregateTransmitBandwidth();
 }
 
 }  // namespace tent
diff --git a/mooncake-transfer-engine/tent/src/transport/rdma/workers.cpp b/mooncake-transfer-engine/tent/src/transport/rdma/workers.cpp
index 77317f8d92..132f985e4b 100644
--- a/mooncake-transfer-engine/tent/src/transport/rdma/workers.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/rdma/workers.cpp
@@ -20,8 +20,12 @@
 
 #include <algorithm>
 #include <cassert>
+#include <cerrno>
+#include <chrono>
 #include <fstream>
 #include <sstream>
+#include <string>
+#include <thread>
 
 #include "tent/transport/rdma/bw_arbitration.h"
 #include "tent/transport/rdma/endpoint_store.h"
@@ -37,12 +41,6 @@ namespace tent {
 thread_local int tl_wid = -1;
 
 namespace {
-struct ArbitrationEntry {
-    RdmaSlice* slice;
-    double mlu;
-    size_t order;
-};
-
 // Look up (or create) the RailMonitor for `machine_id` on this worker's
 // map. Returning a stable reference is safe because the map stores values
 // via unique_ptr -- rehashes move the pointer slot, not the RailMonitor.
@@ -60,6 +58,7 @@ Workers::Workers(RdmaTransport* transport)
     : transport_(transport),
       num_workers_(0),
       running_(false),
+      accepting_submits_(true),
       worker_context_(nullptr) {
     device_selector_ = std::make_unique<DeviceSelector>();
     device_selector_->loadTopology(transport_->local_topology_);
@@ -111,6 +110,9 @@ Workers::Workers(RdmaTransport* transport)
         }
     }
 
+    params.strict_local_numa =
+        conf->get("transports/rdma/strict_local_numa", false);
+
     // ============================================================
     // Bandwidth Estimation (EWMA)
     // ============================================================
@@ -119,6 +121,20 @@ Workers::Workers(RdmaTransport* transport)
     params.bandwidth_learning_rate =
         conf->get("transports/rdma/bandwidth_learning_rate", 0.01);
 
+    // Same convention for the transmit estimate the deadline predictors read
+    params.transmit_bandwidth_learning_rate =
+        conf->get("transports/rdma/transmit_bandwidth_learning_rate",
+                  params.transmit_bandwidth_learning_rate);
+
+    // How often that estimate is metered, and how stale an interval may be
+    // before it is re-baselined instead of learned from.
+    params.transmit_meter_interval_ns =
+        conf->get("transports/rdma/transmit_meter_interval_ns",
+                  params.transmit_meter_interval_ns);
+    params.transmit_meter_max_interval_ns =
+        conf->get("transports/rdma/transmit_meter_max_interval_ns",
+                  params.transmit_meter_max_interval_ns);
+
     // EWMA bounds as multipliers of theoretical bandwidth
     params.ewma_min_multiplier =
         conf->get("transports/rdma/ewma_min_bandwidth_multiplier", 0.1);
@@ -179,13 +195,45 @@ Workers::Workers(RdmaTransport* transport)
     // ============================================================
 
     params.default_bandwidth_gbps =
-        conf->get("transports/rdma/default_bandwidth_gbps", 400.0);
-    params.min_bandwidth_gbps =
-        conf->get("transports/rdma/min_bandwidth_gbps", 10.0);
-    params.max_bandwidth_gbps =
-        conf->get("transports/rdma/max_bandwidth_gbps", 800.0);
+        conf->get("transports/rdma/default_bandwidth_gbps",
+                  params.default_bandwidth_gbps);
+    params.min_bandwidth_gbps = conf->get("transports/rdma/min_bandwidth_gbps",
+                                          params.min_bandwidth_gbps);
+    params.max_bandwidth_gbps = conf->get("transports/rdma/max_bandwidth_gbps",
+                                          params.max_bandwidth_gbps);
 
     device_selector_->setSchedulingParams(params);
+    device_selector_->auditStrictLocalNuma();
+
+    // Seed each device from its context. context_set_ is indexed by NicID,
+    // the same id the selector uses. Three cases:
+    //   - no usable context (DEVICE_UNINIT: initializeContexts() replaced a
+    //     failed construct() with an inert slot; DEVICE_DISABLED handled the
+    //     same way defensively): the NIC cannot carry traffic, so it gets no
+    //     bandwidth at all -- not the default -- and leaves candidate
+    //     selection and the aggregate.
+    //   - port down at open (DEVICE_PAUSED): seeded from whatever the port
+    //     reports (possibly 0, i.e. the default), but unavailable until
+    //     IBV_EVENT_PORT_ACTIVE.
+    //   - DEVICE_ENABLED: seeded from the negotiated speed, or the configured
+    //     default (with a warning) when the speed could not be read.
+    for (size_t dev_id = 0; dev_id < transport_->context_set_.size();
+         ++dev_id) {
+        const auto* nic = transport_->local_topology_->getNicEntry(dev_id);
+        // Only NIC_RDMA entries have a selector slot (see loadTopology()).
+        if (!nic || nic->type != Topology::NIC_RDMA) continue;
+        const auto& context = transport_->context_set_[dev_id];
+        const auto status =
+            context ? context->status() : RdmaContext::DEVICE_UNINIT;
+        if (status == RdmaContext::DEVICE_UNINIT ||
+            status == RdmaContext::DEVICE_DISABLED) {
+            device_selector_->setDeviceAvailable(dev_id, false);
+            continue;
+        }
+        device_selector_->setDeviceBandwidth(dev_id, context->linkSpeedGbps());
+        device_selector_->setDeviceAvailable(
+            dev_id, status == RdmaContext::DEVICE_ENABLED);
+    }
 
     // ============================================================
     // Shared Memory Configuration
@@ -204,6 +252,7 @@ Workers::~Workers() {
 Status Workers::start() {
     const static uint64_t kDefaultMaxTimeoutNs = 10000000000ull;
     if (!running_) {
+        accepting_submits_.store(true, std::memory_order_release);
         running_ = true;
         monitor_ = std::thread([this] { monitorThread(); });
         num_workers_ = transport_->params_->workers.num_workers;
@@ -220,6 +269,7 @@ Status Workers::start() {
 
 Status Workers::stop() {
     if (!running_) return Status::OK();
+    accepting_submits_.store(false, std::memory_order_release);
     running_ = false;
     for (size_t id = 0; id < num_workers_; ++id) {
         auto& worker = worker_context_[id];
@@ -235,7 +285,45 @@ Status Workers::stop() {
     return Status::OK();
 }
 
+Status Workers::quiesce(uint64_t timeout_ns) {
+    accepting_submits_.store(false, std::memory_order_release);
+    if (!running_.load(std::memory_order_acquire) || !worker_context_ ||
+        num_workers_ == 0) {
+        return Status::OK();
+    }
+
+    for (size_t id = 0; id < num_workers_; ++id) {
+        auto& worker = worker_context_[id];
+        std::lock_guard<std::mutex> lock(worker.mutex);
+        if (worker.in_suspend) worker.cv.notify_all();
+    }
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::nanoseconds(timeout_ns);
+    while (true) {
+        int64_t inflight = 0;
+        for (size_t id = 0; id < num_workers_; ++id) {
+            inflight += worker_context_[id].inflight_slices.load(
+                std::memory_order_acquire);
+        }
+        if (inflight == 0) return Status::OK();
+        if (std::chrono::steady_clock::now() >= deadline) {
+            return Status::InternalError("RDMA quiesce timed out with " +
+                                         std::to_string(inflight) +
+                                         " inflight slices" LOC_MARK);
+        }
+        std::this_thread::sleep_for(std::chrono::microseconds(100));
+    }
+}
+
 Status Workers::submit(RdmaSliceList& slice_list, int worker_id) {
+    if (!accepting_submits_.load(std::memory_order_acquire)) {
+        return Status::InternalError("RDMA transport is quiescing" LOC_MARK);
+    }
+    if (!running_.load(std::memory_order_acquire) || !worker_context_ ||
+        num_workers_ == 0) {
+        return Status::InternalError("RDMA workers are not running" LOC_MARK);
+    }
     if (worker_id < 0 || worker_id >= (int)num_workers_) {
         // If caller didn't specify the worker, find the least loaded one
         long min_inflight = INT64_MAX;
@@ -252,6 +340,16 @@ Status Workers::submit(RdmaSliceList& slice_list, int worker_id) {
     }
     auto& worker = worker_context_[worker_id];
 
+    // This lane's set and counter now account for the slices, wherever they
+    // are later swept from. First entry only: a slice arriving here has
+    // never been counted, so there is nothing to move.
+    auto* owned = slice_list.first;
+    for (int i = 0; i < slice_list.num_slices && owned; ++i) {
+        owned->owner_worker.store(worker_id, std::memory_order_relaxed);
+        owned->counted_lane.store(worker_id, std::memory_order_relaxed);
+        owned = owned->next;
+    }
+
     // Get priority from first slice (all slices in list have same priority)
     int priority = PRIO_HIGH;
     if (slice_list.first && slice_list.first->task) {
@@ -273,6 +371,39 @@ Status Workers::submit(RdmaSlice* slice) {
     return submit(slice_list);
 }
 
+void Workers::submitFromTick(WorkerContext& worker, RdmaSlice* slice) {
+    RdmaSliceList slice_list;
+    slice_list.first = slice;
+    slice_list.num_slices = 1;
+    int priority = PRIO_HIGH;
+    if (slice && slice->task) {
+        priority = slice->priority;
+    }
+    // This lane's queue and counter are about to account for the slice, so
+    // move the count here before it is visible on the queue. With a shared
+    // queue pair the lane re-queueing the slice is the one that polled the
+    // completion, not necessarily the one that first enqueued it: whichever
+    // lane still counts it is paid back in the same exchange, so the slice
+    // is never in two counts or in none. A sweep that already discounted it
+    // left -1 behind and there is nothing to pay.
+    if (slice) {
+        const int lane = laneIndex(worker);
+        slice->owner_worker.store(lane, std::memory_order_relaxed);
+        const int prev =
+            slice->counted_lane.exchange(lane, std::memory_order_acq_rel);
+        if (prev >= 0 && prev != lane && prev < (int)num_workers_)
+            worker_context_[prev].inflight_slices.fetch_sub(1);
+        if (prev != lane) worker.inflight_slices.fetch_add(1);
+    }
+    // The worker must never block on its own queue (issue #3637): a full
+    // queue parks the slice in requeue_overflow and the next tick retries.
+    // Either way it stays counted as inflight, which keeps the worker from
+    // suspending while a parked flush is pending.
+    if (!worker.queues[priority].try_push(slice_list)) {
+        worker.requeue_overflow.emplace_back(priority, slice_list);
+    }
+}
+
 Status Workers::cancel(RdmaTask* task) {
     if (!task) return Status::InvalidArgument("Invalid RDMA task" LOC_MARK);
     if (task->cancel_requested.exchange(true, std::memory_order_acq_rel)) {
@@ -293,22 +424,184 @@ Status Workers::cancel(RdmaTask* task) {
     return Status::OK();
 }
 
-bool Workers::cancelUnpostedSlice(WorkerContext& worker, RdmaSlice* slice) {
-    if (!slice || !slice->task ||
+void Workers::orderByDeadline(std::vector<RdmaSlice*>& slices, int dev_id,
+                              uint64_t now_ns) {
+    if (!device_selector_ || slices.size() < 2) return;
+    // This NIC's transmit estimate answers "how fast do these bytes move";
+    // <= 0 means nothing to predict from, so the order stays as it is.
+    const double bw_bps = device_selector_->getTransmitBandwidth(dev_id);
+    if (bw_bps <= 0.0) return;
+
+    thread_local std::vector<ArbFlow> flows;
+    flows.clear();
+    flows.reserve(slices.size());
+    bool any_deadline = false;
+    for (const RdmaSlice* s : slices) {
+        flows.push_back(s && s->task
+                            ? ArbFlow{s->task->request.deadline_ns, s->length}
+                            : ArbFlow{0, 0});
+        any_deadline |= flows.back().deadline_ns != 0;
+    }
+    // Without a deadline anywhere every MLU is 0 and the order would come
+    // out as it went in; skip the greedy pass rather than run it for that.
+    if (!any_deadline) return;
+
+    // What actually precedes these slices: bytes already posted to the NIC.
+    // None of the candidates is in it -- they are about to be posted -- and
+    // neither is work still sitting in a worker queue.
+    const size_t bytes_ahead = device_selector_->getPostedBytes(dev_id);
+    const auto order = OrderByUrgency(flows, now_ns, bw_bps, bytes_ahead);
+
+    thread_local std::vector<RdmaSlice*> ordered;
+    ordered.clear();
+    ordered.reserve(order.size());
+    for (size_t i : order) ordered.push_back(slices[i]);
+    std::copy(ordered.begin(), ordered.end(), slices.begin());
+}
+
+void Workers::rechargeSlice(RdmaSlice* slice, int dev_id) {
+    if (!device_selector_ || !slice || dev_id < 0) return;
+    if (slice->charged_dev.load(std::memory_order_relaxed) == dev_id) return;
+    if (auto status = device_selector_->chargeDevice(dev_id, slice->length);
+        !status.ok()) {
+        // A device the selector does not track (a topology/quota mismatch).
+        // The transfer can still go, so the slice is not failed; it keeps
+        // the charge it has, if any, so the release stays balanced -- but
+        // this NIC's load is under-counted, so say so (rate-limited).
+        LOG_EVERY_N(WARNING, 100)
+            << "rechargeSlice: device " << dev_id
+            << " is not tracked by DeviceSelector; slice " << slice
+            << " keeps its previous charge: " << status.ToString();
+        return;
+    }
+    // Charge the new device before letting go of the old one, so a release
+    // racing in between pays back whichever device is on record and never
+    // both, and never one that has not been charged. No latency sample --
+    // this is not a completion.
+    const int prev =
+        slice->charged_dev.exchange(dev_id, std::memory_order_acq_rel);
+    if (prev >= 0) device_selector_->release(prev, slice->length, 0.0);
+}
+
+bool Workers::dropUnpostableSlice(WorkerContext& worker, RdmaSlice* slice) {
+    if (!slice || !slice->task) return false;
+    // Two reasons not to post. The caller cancelled the transfer; or another
+    // lane already resolved this slice while it waited here for a re-post --
+    // with a shared queue pair that lane's timeout sweep can still reach it
+    // through a set entry it has not drained. Posting a resolved slice would
+    // move bytes for a transfer that is already over.
+    if (slice->word == PENDING &&
         !slice->task->cancel_requested.load(std::memory_order_acquire))
         return false;
-    if (slice->word == PENDING) {
-        releaseSliceQuota(slice);
-        updateSliceStatus(slice, CANCELED);
-    }
-    worker.inflight_slices.fetch_sub(1);
+    // Retire it the way a sweep would -- charge, count and set entry all go
+    // back where they came from, each idempotently, since whichever path
+    // resolved the slice may already have run them -- and updateSliceStatus
+    // is a no-op once the slice is terminal.
+    retireSweptSlice(worker, slice, getCurrentTimeInNano(), nullptr);
+    updateSliceStatus(slice, CANCELED);
     return true;
 }
 
-void Workers::releaseSliceQuota(RdmaSlice* slice, double latency) {
-    if (!slice || !slice->quota_charged || !device_selector_) return;
-    device_selector_->release(slice->source_dev_id, slice->length, latency);
-    slice->quota_charged = false;
+void Workers::releaseSliceQuota(RdmaSlice* slice, uint64_t now_ns,
+                                double latency) {
+    if (!slice || !device_selector_) return;
+    // Each field names the device it was charged to, so the release goes
+    // there even if a fallback has since rewritten source_dev_id.
+    const int posted =
+        slice->posted_dev.exchange(-1, std::memory_order_acq_rel);
+    if (posted >= 0)
+        device_selector_->notePostEnded(posted, slice->length, now_ns);
+    const int charged =
+        slice->charged_dev.exchange(-1, std::memory_order_acq_rel);
+    if (charged >= 0)
+        device_selector_->release(charged, slice->length, latency);
+}
+
+Workers::WorkerContext* Workers::ownerContext(const RdmaSlice* slice) {
+    if (!worker_context_ || !slice) return nullptr;
+    const int lane = slice->owner_worker.load(std::memory_order_relaxed);
+    if (lane < 0 || lane >= (int)num_workers_) return nullptr;
+    return &worker_context_[lane];
+}
+
+int Workers::laneIndex(const WorkerContext& worker) const {
+    if (!worker_context_) return -1;
+    return static_cast<int>(&worker - worker_context_);
+}
+
+bool Workers::routeSetRemoval(WorkerContext& self, RdmaSlice* slice) {
+    // Two sets can hold an entry for one slice: a retry re-queued by another
+    // lane moves ownership while the lane it left still holds the old
+    // entry. So this lane takes out whatever it holds itself, and the
+    // owning lane, if it is somebody else, is handed the slice regardless --
+    // a hand-over for an entry it does not hold costs one erase of nothing.
+    const bool mine = self.inflight_slice_set.count(slice) > 0;
+    auto* owner = ownerContext(slice);
+    if (owner && owner != &self) {
+        std::lock_guard<std::mutex> lock(owner->reclaim_mutex);
+        owner->reclaimed.push_back(slice);
+    }
+    return mine || !owner || owner == &self;
+}
+
+void Workers::retireSweptSlice(WorkerContext& self, RdmaSlice* slice,
+                               uint64_t now_ns,
+                               std::vector<RdmaSlice*>* deferred,
+                               bool bytes_moved) {
+    if (!slice) return;
+    const int posted_dev = slice->posted_dev.load(std::memory_order_relaxed);
+    releaseSliceQuota(slice, now_ns);
+    // A slice swept off with FAILED or TIMEOUT leaves the hardware without
+    // its bytes being counted, so the stretch it was part of cannot be
+    // divided into the next sample. One swept with COMPLETED did move them;
+    // its own completion, still to be polled, credits them.
+    if (posted_dev >= 0 && !bytes_moved && device_selector_)
+        device_selector_->resetTransmitMeter(posted_dev);
+    discountFromOwner(self, slice);
+    if (!routeSetRemoval(self, slice)) return;
+    if (deferred)
+        deferred->push_back(slice);
+    else
+        self.inflight_slice_set.erase(slice);
+}
+
+void Workers::discountFromOwner(WorkerContext& self, RdmaSlice* slice) {
+    if (!slice) return;
+    // Several paths can reach one slice -- its own completion, another
+    // lane's sweep of a shared queue pair, this lane's timeout pass -- and
+    // only the first of them takes it out of the count: the field says
+    // which lane's, and comes back -1 for everyone after.
+    const int lane =
+        slice->counted_lane.exchange(-1, std::memory_order_acq_rel);
+    if (lane < 0) return;
+    const bool known = worker_context_ && lane < (int)num_workers_;
+    (known ? worker_context_[lane] : self).inflight_slices.fetch_sub(1);
+}
+
+void Workers::drainReclaimed(WorkerContext& worker) {
+    std::vector<RdmaSlice*> taken;
+    {
+        std::lock_guard<std::mutex> lock(worker.reclaim_mutex);
+        if (worker.reclaimed.empty()) return;
+        taken.swap(worker.reclaimed);
+    }
+    for (auto* slice : taken) worker.inflight_slice_set.erase(slice);
+}
+
+void Workers::notePostedSlice(RdmaSlice* slice) {
+    if (!slice || !device_selector_) return;
+    int none = -1;
+    if (slice->posted_dev.compare_exchange_strong(none, slice->source_dev_id,
+                                                  std::memory_order_acq_rel))
+        device_selector_->notePosted(slice->source_dev_id, slice->length,
+                                     slice->submit_ts);
+}
+
+void Workers::markPosted(WorkerContext& worker, RdmaSlice* slice,
+                         uint64_t post_ts) {
+    slice->submit_ts = post_ts;
+    notePostedSlice(slice);
+    worker.inflight_slice_set.insert(slice);
 }
 
 std::shared_ptr<RdmaEndPoint> Workers::getEndpoint(Workers::PostPath path) {
@@ -395,9 +688,21 @@ void Workers::asyncPostSend() {
     // Promote timed-out low priority requests
     promoteTimedOutRequests(worker);
 
-    // Priority selection: HIGH -> MEDIUM -> LOW
+    // Priority selection: HIGH -> MEDIUM -> LOW. The worker-local overflow is
+    // drained before the shared queues, so a parked retry can never starve
+    // behind producers that keep refilling freed slots (issue #3637).
+    auto& overflow = worker.requeue_overflow;
     for (int prio = PRIO_HIGH; prio < kNumPriorityLevels; ++prio) {
         if (shared_quota && !shared_quota->canSend(prio)) continue;
+        for (auto it = overflow.begin(); it != overflow.end();) {
+            if (it->first == prio) {
+                result.push_back(it->second);
+                it = overflow.erase(it);
+            } else {
+                ++it;
+            }
+        }
+        if (!result.empty()) break;
         worker.queues[prio].pop(result);
         if (!result.empty()) break;
     }
@@ -406,21 +711,25 @@ void Workers::asyncPostSend() {
         if (slice_list.num_slices == 0) continue;
         auto slice = slice_list.first;
         for (int id = 0; id < slice_list.num_slices; ++id) {
-            if (cancelUnpostedSlice(worker, slice)) {
+            if (dropUnpostableSlice(worker, slice)) {
                 slice = slice->next;
                 continue;
             }
             auto status = generatePostPath(slice);
             if (!status.ok()) {
-                LOG(ERROR) << "Failed to generate post path for slice " << slice
-                           << ": " << status.ToString();
-                releaseSliceQuota(slice);
+                VLOG(1) << "Failed to generate post path for slice " << slice
+                        << ": " << status.ToString();
+                LOG_EVERY_N(ERROR, 10000)
+                    << "Failed to generate post path for slice " << slice
+                    << ": " << status.ToString();
+                releaseSliceQuota(slice, getCurrentTimeInNano());
+                // Count first: resolving the slice lets the batch be freed.
+                discountFromOwner(worker, slice);
                 updateSliceStatus(slice, slice->task->cancel_requested.load(
                                              std::memory_order_acquire)
                                              ? CANCELED
                                              : FAILED);
-                worker.inflight_slices.fetch_sub(1);
-            } else if (cancelUnpostedSlice(worker, slice)) {
+            } else if (dropUnpostableSlice(worker, slice)) {
                 slice = slice->next;
                 continue;
             } else {
@@ -440,7 +749,7 @@ void Workers::asyncPostSend() {
         if (slices.empty()) continue;
         slices.erase(std::remove_if(slices.begin(), slices.end(),
                                     [&](RdmaSlice* slice) {
-                                        return cancelUnpostedSlice(worker,
+                                        return dropUnpostableSlice(worker,
                                                                    slice);
                                     }),
                      slices.end());
@@ -450,20 +759,22 @@ void Workers::asyncPostSend() {
             std::vector<RdmaSlice*> clone;
             slices.swap(clone);
             for (auto slice : clone) {
-                if (cancelUnpostedSlice(worker, slice)) continue;
+                if (dropUnpostableSlice(worker, slice)) continue;
                 slice->retry_count++;
+                releaseSliceQuota(slice, getCurrentTimeInNano());
                 if (slice->retry_count >=
                     transport_->params_->workers.max_retry_count) {
-                    LOG(WARNING)
+                    VLOG(1)
+                        << "Slice " << slice << " failed: retry count exceeded";
+                    LOG_EVERY_N(WARNING, 100)
                         << "Slice " << slice << " failed: retry count exceeded";
                     disableEndpoint(slice);
-                    releaseSliceQuota(slice);
+                    discountFromOwner(worker, slice);
                     updateSliceStatus(slice, FAILED);
                 } else {
-                    releaseSliceQuota(slice);
-                    submit(slice);
+                    // The re-submit moves the count to the lane it lands on.
+                    submitFromTick(worker, slice);
                 }
-                worker.inflight_slices.fetch_sub(1);
             }
             continue;
         }
@@ -475,66 +786,42 @@ void Workers::asyncPostSend() {
         // its deadline claims the shared NIC's QP slots ahead of looser flows.
         // Default (deadline_bw_arbitration_ == false) leaves order untouched,
         // so behavior is byte-identical to today's FIFO / equal split.
-        if (deadline_bw_arbitration_ && slices.size() > 1) {
-            const uint64_t now_ns = getCurrentTimeInNano();
-            const double bw_bps = device_selector_
-                                      ? device_selector_->getSchedulingParams()
-                                                .default_bandwidth_gbps *
-                                            1e9 / 8.0
-                                      : 0.0;
-            if (bw_bps > 0.0) {
-                thread_local std::vector<ArbitrationEntry> scratch;
-                scratch.clear();
-                scratch.reserve(slices.size());
-
-                for (size_t i = 0; i < slices.size(); ++i) {
-                    const RdmaSlice* s = slices[i];
-                    ArbFlow flow{0, 0};
-                    if (s && s->task) {
-                        flow = ArbFlow{s->task->request.deadline_ns, s->length};
-                    }
-                    scratch.push_back(ArbitrationEntry{
-                        slices[i], PredictedMlu(flow, now_ns, bw_bps), i});
-                }
-
-                std::sort(
-                    scratch.begin(), scratch.end(),
-                    [](const ArbitrationEntry& a, const ArbitrationEntry& b) {
-                        if (a.mlu > b.mlu) return true;
-                        if (a.mlu < b.mlu) return false;
-                        return a.order < b.order;
-                    });
-                for (size_t i = 0; i < scratch.size(); ++i) {
-                    slices[i] = scratch[i].slice;
-                }
-            }
+        if (deadline_bw_arbitration_) {
+            orderByDeadline(slices, path.local_device_id,
+                            getCurrentTimeInNano());
         }
 
-        int num_submitted = endpoint->submitSlices(slices, tl_wid);
+        // Everything a completion's poller must find is written before the
+        // work request can reach the wire: with a shared queue pair another
+        // lane may poll the completion before submitSlices returns, and a
+        // poller that finds no posted device on the slice would leave the
+        // device's backlog holding these bytes for good.
+        const uint64_t post_ts = getCurrentTimeInNano();
+        int num_submitted = endpoint->submitSlices(
+            slices, tl_wid,
+            [&](RdmaSlice* posted) { markPosted(worker, posted, post_ts); });
         for (int id = 0; id < num_submitted; ++id) {
             auto slice = slices[id];
-            if (slice->failed) {
-                releaseSliceQuota(slice);
-                if (slice->task->cancel_requested.load(
-                        std::memory_order_acquire)) {
-                    updateSliceStatus(slice, CANCELED);
-                    worker.inflight_slices.fetch_sub(1);
-                    continue;
-                }
-                slice->retry_count++;
-                if (slice->retry_count >=
-                    transport_->params_->workers.max_retry_count) {
-                    LOG(WARNING)
-                        << "Slice " << slice << " failed: retry count exceeded";
-                    disableEndpoint(slice);
-                    updateSliceStatus(slice, FAILED);
-                } else {
-                    submit(slice);
-                }
-                worker.inflight_slices.fetch_sub(1);
+            if (!slice->failed) continue;
+            // Rejected by the hardware: it never went on the wire, so take
+            // back what the hook put in place.
+            worker.inflight_slice_set.erase(slice);
+            releaseSliceQuota(slice, post_ts);
+            if (slice->task->cancel_requested.load(std::memory_order_acquire)) {
+                discountFromOwner(worker, slice);
+                updateSliceStatus(slice, CANCELED);
+                continue;
+            }
+            slice->retry_count++;
+            if (slice->retry_count >=
+                transport_->params_->workers.max_retry_count) {
+                LOG(WARNING)
+                    << "Slice " << slice << " failed: retry count exceeded";
+                disableEndpoint(slice);
+                discountFromOwner(worker, slice);
+                updateSliceStatus(slice, FAILED);
             } else {
-                slice->submit_ts = getCurrentTimeInNano();
-                worker.inflight_slice_set.insert(slice);
+                submitFromTick(worker, slice);
             }
         }
 
@@ -559,17 +846,14 @@ void Workers::promoteTimedOutRequests(WorkerContext& worker) {
         worker.queues[from].pop(drained);
         if (drained.empty()) return false;
 
-        if (!priority_promotion_per_entry_) {
-            auto* slice = drained.front().first;
-            const bool head_timed_out = slice && slice->enqueue_ts > 0 &&
-                                        current_ts >= slice->enqueue_ts &&
-                                        (current_ts - slice->enqueue_ts) >=
-                                            priority_promotion_timeout_ns_;
-            for (auto& slice_list : drained) {
-                worker.queues[head_timed_out ? to : from].push(slice_list);
+        // The worker must never block on its own queue: a full target parks
+        // the entry in requeue_overflow and the next tick retries (issue
+        // #3637). Parked entries stay counted as inflight throughout.
+        auto requeue = [&](int target, RdmaSliceList& slice_list) {
+            if (!worker.queues[target].try_push(slice_list)) {
+                worker.requeue_overflow.emplace_back(target, slice_list);
             }
-            return head_timed_out;
-        }
+        };
 
         std::vector<uint64_t> enqueue_ts;
         enqueue_ts.reserve(drained.size());
@@ -578,12 +862,15 @@ void Workers::promoteTimedOutRequests(WorkerContext& worker) {
             enqueue_ts.push_back(slice ? slice->enqueue_ts : 0);
         }
 
-        PromotionDecision decision = DecidePromotionPerEntry(
-            enqueue_ts, current_ts, priority_promotion_timeout_ns_);
+        PromotionDecision decision =
+            priority_promotion_per_entry_
+                ? DecidePromotionPerEntry(enqueue_ts, current_ts,
+                                          priority_promotion_timeout_ns_)
+                : DecidePromotionHeadOnly(enqueue_ts, current_ts,
+                                          priority_promotion_timeout_ns_);
 
         if (!decision.promoted_any()) {
-            for (auto& slice_list : drained)
-                worker.queues[from].push(slice_list);
+            for (auto& slice_list : drained) requeue(from, slice_list);
             return false;
         }
 
@@ -592,7 +879,7 @@ void Workers::promoteTimedOutRequests(WorkerContext& worker) {
             if (idx < drained.size()) promote[idx] = true;
         }
         for (size_t i = 0; i < drained.size(); ++i) {
-            worker.queues[promote[i] ? to : from].push(drained[i]);
+            requeue(promote[i] ? to : from, drained[i]);
         }
         return true;
     };
@@ -608,34 +895,240 @@ void Workers::promoteTimedOutRequests(WorkerContext& worker) {
     promote_level(PRIO_LOW, PRIO_MEDIUM);
 }
 
-void Workers::asyncPollCq() {
-    auto& worker = worker_context_[tl_wid];
-    const static size_t kPollCount = 64;
-    int num_contexts = (int)transport_->context_set_.size();
-    int num_cq_list = transport_->params_->device.num_cq_list;
-    int num_slices = 0;
-
-    uint64_t current_ts = getCurrentTimeInNano();
+void Workers::expireTimedOutSlices(WorkerContext& worker, uint64_t now_ns) {
+    drainReclaimed(worker);
     std::vector<RdmaSlice*> slice_to_remove;
+    // Erasing from this lane's set has to wait until the loop below is done
+    // with it; slices belonging to another lane are handed over instead.
+    // One captured reference keeps the std::function inside its small-buffer
+    // storage, so a sweep does not allocate.
+    struct Sweep {
+        Workers* self;
+        WorkerContext* worker;
+        uint64_t now_ns;
+        std::vector<RdmaSlice*>* deferred;
+    } sweep{this, &worker, now_ns, &slice_to_remove};
+    auto retire = [&sweep](RdmaSlice* swept) {
+        sweep.self->retireSweptSlice(*sweep.worker, swept, sweep.now_ns,
+                                     sweep.deferred);
+    };
     for (auto& slice : worker.inflight_slice_set) {
-        if (slice->word != PENDING) continue;
-        if (current_ts - slice->enqueue_ts > slice_timeout_ns_) {
+        if (slice->word != PENDING) {
+            // Terminal but still counted here: an endpoint teardown cancels
+            // whatever is queued on it without going through a sweep, so
+            // nothing has given this lane its slice back. Do it now, or the
+            // charge, the NIC's posted bytes and this lane's count carry it
+            // for the life of the process.
+            retire(slice);
+            continue;
+        }
+        if (now_ns - slice->enqueue_ts > slice_timeout_ns_) {
             auto ep = slice->ep_weak_ptr.lock();
             LOG(WARNING) << "Slice " << slice
                          << " failed: transfer timeout (software)";
+            // The slice turns terminal here, not on the CQ. Its flush
+            // completion may never be polled (acknowledge() zeroes wr_depth,
+            // so the endpoint destroys the QP and its unpolled CQEs), so
+            // return the selector charge now for it and every slice swept
+            // with it; releaseSliceQuota() is idempotent.
             if (!ep) {
+                retire(slice);
                 updateSliceStatus(slice, TIMEOUT);
-                slice_to_remove.push_back(slice);
-                worker.inflight_slices.fetch_sub(1);
                 continue;
             }
-            auto num_slices = ep->acknowledge(slice, TIMEOUT);
+            auto num_slices = ep->acknowledge(slice, TIMEOUT, retire);
             disableEndpoint(slice);
-            worker.inflight_slices.fetch_sub(num_slices);
-            slice_to_remove.push_back(slice);
+            if (num_slices == 0) {
+                // A neighbour's retry already popped it off the queue pair
+                // and discounted it there, so only its charge and its set
+                // entry are still outstanding.
+                releaseSliceQuota(slice, now_ns);
+                if (routeSetRemoval(worker, slice))
+                    slice_to_remove.push_back(slice);
+                updateSliceStatus(slice, TIMEOUT);
+            }
         }
     }
     for (auto& slice : slice_to_remove) worker.inflight_slice_set.erase(slice);
+}
+
+void Workers::handleCompletion(WorkerContext& worker, RdmaContext& context,
+                               const ibv_wc& wc, uint64_t poll_ts,
+                               bool last_in_pass) {
+    auto slice = (RdmaSlice*)wc.wr_id;
+    // The completion this post owed, paid back only once this handler is
+    // done with the slice. Paying it on entry is not enough: acknowledge()
+    // further down publishes the terminal status the caller is waiting for,
+    // so the batch can be freed, and the slice with it, while the lines
+    // after it still read the slice. Above zero, freeSubBatch() hands the
+    // slice to the orphan list instead of the slab and the reaper leaves it
+    // there.
+    struct CompletionPaid {
+        RdmaSlice* slice;
+        ~CompletionPaid() {
+            slice->completions_owed.fetch_sub(1, std::memory_order_acq_rel);
+        }
+    } completion_paid{slice};
+    // What the acknowledge callbacks below need, behind one reference so
+    // the std::function stays in its small-buffer storage (no allocation
+    // per completion).
+    struct Sweep {
+        Workers* self;
+        WorkerContext* worker;
+        uint64_t now_ns;
+    } sweep{this, &worker, poll_ts};
+    // The lane that enqueued this slice owns its set entry; with a
+    // shared queue pair that is not necessarily this one.
+    if (routeSetRemoval(worker, slice)) worker.inflight_slice_set.erase(slice);
+    auto ep = slice->ep_weak_ptr.lock();
+    double enqueue_lat = (slice->submit_ts - slice->enqueue_ts) / 1000.0;
+    double inflight_lat = (poll_ts - slice->submit_ts) / 1000.0;
+    // The selection EWMA learns only from a successful transfer, and only
+    // from this attempt's own post->completion time (#3511): the time since
+    // first enqueue folds in queueing and earlier failed attempts on other
+    // NICs. A failed or flushed work request, or a slice another path has
+    // already resolved, contributes no sample and only returns its charge.
+    const bool ewma_sample =
+        ep && slice->word == PENDING && wc.status == IBV_WC_SUCCESS;
+    const double sample_lat_sec =
+        ewma_sample ? (poll_ts - slice->submit_ts) / 1e9 : 0.0;
+    const int dev_id = slice->source_dev_id;
+    const uint64_t moved = slice->length;
+    releaseSliceQuota(slice, poll_ts, sample_lat_sec);
+    // The transmit estimate is metered from bytes completed over the time
+    // the NIC spent busy, so it needs the release above to have taken this
+    // slice out of the backlog first -- that is what closes the stretch.
+    // Only successful bytes moved on the wire.
+    if (device_selector_) {
+        if (wc.status == IBV_WC_SUCCESS) {
+            device_selector_->noteCompleted(dev_id, moved);
+            // Only once the whole poll pass has been counted. Every work
+            // request it reaps carries the same timestamp, so a sample taken
+            // partway through would end its interval at that timestamp while
+            // leaving the rest of the pass's bytes to the next one -- which
+            // then gets them for free. The estimate is an average of
+            // per-interval rates, so the short interval that is paid twice
+            // and the long one that is paid once do not cancel: at 2 GB/s
+            // with sixteen-deep polling that read 8% high.
+            if (last_in_pass)
+                device_selector_->maybeSampleTransmit(dev_id, poll_ts);
+        } else {
+            // The bytes of a failed or flushed work request never moved, but
+            // the stretch the NIC held it for did. Start over here rather
+            // than divide that time into whatever completes next.
+            device_selector_->resetTransmitMeter(dev_id);
+        }
+    }
+    if (slice->word != PENDING) {
+        // Resolved before its completion was polled -- swept off the queue
+        // pair by a neighbour, timed out, or cancelled by a teardown. The
+        // charge came back above; the lane count is settled here in case
+        // that path could not (idempotent, so a path that did is unharmed).
+        discountFromOwner(worker, slice);
+        return;
+    }
+    if (!ep) {
+        updateSliceStatus(slice, FAILED);
+        discountFromOwner(worker, slice);
+        return;
+    }
+    if (wc.status != IBV_WC_SUCCESS) {
+        if (wc.status != IBV_WC_WR_FLUSH_ERR) {
+            // TE handles them automatically
+            LOG(INFO) << "Detected error WQE for slice " << slice
+                      << " (opcode: " << slice->task->request.opcode
+                      << ", source_addr: " << (void*)slice->source_addr
+                      << ", dest_addr: " << (void*)slice->target_addr
+                      << ", length: " << slice->length
+                      << ", local_nic: " << context.name()
+                      << "): " << ibv_wc_status_str(wc.status);
+        }
+        // GPUDirect reachability learning: a protection/access error
+        // on a GPU buffer means the chosen NIC cannot P2P-DMA to that
+        // GPU (ibv_reg_mr succeeded but the PCIe path is unusable).
+        // Record it so selection avoids that NIC and converges onto a
+        // reachable rail instead of exhausting retries. The local side
+        // (source NIC -> source GPU) surfaces as LOC_PROT; the remote
+        // side (target NIC -> target GPU) as REM_ACCESS or, for a
+        // remote GDR-read failure, REM_OP (observed on strict fabrics).
+        bool local_gdr_err = (wc.status == IBV_WC_LOC_PROT_ERR);
+        bool remote_gdr_err = (wc.status == IBV_WC_REM_ACCESS_ERR ||
+                               wc.status == IBV_WC_REM_OP_ERR);
+        if (local_gdr_err && slice->source_gpu_ordinal >= 0 &&
+            slice->source_nic_name) {
+            GdrReachability::instance().reportLocalFailure(
+                slice->source_nic_name, slice->source_gpu_ordinal);
+        } else if (remote_gdr_err && slice->target_gpu_ordinal >= 0 &&
+                   slice->target_nic_name && slice->target_machine_id) {
+            GdrReachability::instance().reportRemoteFailure(
+                *slice->target_machine_id, slice->target_nic_name,
+                slice->target_gpu_ordinal);
+        }
+        slice->retry_count++;
+        if (slice->retry_count >=
+            transport_->params_->workers.max_retry_count) {
+            LOG(WARNING) << "Slice " << slice
+                         << " failed: retry count exceeded";
+            ep->acknowledge(slice, FAILED, [&sweep](RdmaSlice* swept) {
+                sweep.self->retireSweptSlice(*sweep.worker, swept, sweep.now_ns,
+                                             nullptr);
+            });
+            disableEndpoint(slice);
+        } else {
+            // Popped but still in flight: their work requests are
+            // live and their completions are still coming, so only
+            // the owning lane's count stops tracking them here.
+            ep->acknowledge(slice, PENDING, [&](RdmaSlice* swept) {
+                discountFromOwner(worker, swept);
+            });
+            disableEndpoint(slice);
+            if (slice->task->cancel_requested.load(std::memory_order_acquire)) {
+                updateSliceStatus(slice, CANCELED);
+            } else {
+                submitFromTick(worker, slice);
+            }
+        }
+    } else {
+        ep->acknowledge(slice, COMPLETED, [&sweep](RdmaSlice* swept) {
+            sweep.self->retireSweptSlice(*sweep.worker, swept, sweep.now_ns,
+                                         nullptr, /*bytes_moved=*/true);
+        });
+        // A successful GPU transfer re-admits any learned GDR
+        // unreachability for the (GPU, NIC) pair(s) it used, so a
+        // transient exclusion (or a recovered path) heals. Skipped
+        // entirely until something has actually been excluded.
+        if (GdrReachability::hasAnyExclusion()) {
+            auto& gdr = GdrReachability::instance();
+            if (slice->source_gpu_ordinal >= 0 && slice->source_nic_name)
+                gdr.reportLocalSuccess(slice->source_nic_name,
+                                       slice->source_gpu_ordinal);
+            if (slice->target_gpu_ordinal >= 0 && slice->target_nic_name &&
+                slice->target_machine_id)
+                gdr.reportRemoteSuccess(*slice->target_machine_id,
+                                        slice->target_nic_name,
+                                        slice->target_gpu_ordinal);
+        }
+        // A successful transfer proves this rail is healthy; clear
+        // any accumulated error count so a previously-cooled-down
+        // rail can be used again without waiting for the full
+        // cooldown to expire. The monitor pointer is resolved once
+        // in generatePostPath, so no map lookup is needed here.
+        if (auto* rail = slice->rail_monitor; rail && rail->ready())
+            rail->markRecovered(slice->source_dev_id, slice->target_dev_id);
+        if (transport_->params_->workers.show_latency_info) {
+            worker.perf.inflight_lat.add(inflight_lat);
+            worker.perf.enqueue_lat.add(enqueue_lat);
+        }
+    }
+}
+
+void Workers::asyncPollCq() {
+    auto& worker = worker_context_[tl_wid];
+    const static size_t kPollCount = 64;
+    int num_contexts = (int)transport_->context_set_.size();
+    int num_cq_list = transport_->params_->device.num_cq_list;
+
+    expireTimedOutSlices(worker, getCurrentTimeInNano());
 
     for (int index = 0; index < num_contexts; index++) {
         auto& context = transport_->context_set_[index];
@@ -645,103 +1138,9 @@ void Workers::asyncPollCq() {
         int nr_poll = cq->poll(kPollCount, wc);
         if (nr_poll < 0) continue;
         auto poll_ts = getCurrentTimeInNano();
-        for (int i = 0; i < nr_poll; ++i) {
-            auto slice = (RdmaSlice*)wc[i].wr_id;
-            worker.inflight_slice_set.erase(slice);
-            auto ep = slice->ep_weak_ptr.lock();
-            double enqueue_lat =
-                (slice->submit_ts - slice->enqueue_ts) / 1000.0;
-            double inflight_lat = (poll_ts - slice->submit_ts) / 1000.0;
-            double overall_lat_sec = (poll_ts - slice->enqueue_ts) / 1e9;
-            releaseSliceQuota(slice, overall_lat_sec);
-            if (slice->word != PENDING) continue;
-            if (!ep) {
-                updateSliceStatus(slice, FAILED);
-                num_slices++;
-                continue;
-            }
-            if (wc[i].status != IBV_WC_SUCCESS) {
-                if (wc[i].status != IBV_WC_WR_FLUSH_ERR) {
-                    // TE handles them automatically
-                    LOG(INFO) << "Detected error WQE for slice " << slice
-                              << " (opcode: " << slice->task->request.opcode
-                              << ", source_addr: " << (void*)slice->source_addr
-                              << ", dest_addr: " << (void*)slice->target_addr
-                              << ", length: " << slice->length
-                              << ", local_nic: " << context->name()
-                              << "): " << ibv_wc_status_str(wc[i].status);
-                }
-                // GPUDirect reachability learning: a protection/access error
-                // on a GPU buffer means the chosen NIC cannot P2P-DMA to that
-                // GPU (ibv_reg_mr succeeded but the PCIe path is unusable).
-                // Record it so selection avoids that NIC and converges onto a
-                // reachable rail instead of exhausting retries. The local side
-                // (source NIC -> source GPU) surfaces as LOC_PROT; the remote
-                // side (target NIC -> target GPU) as REM_ACCESS or, for a
-                // remote GDR-read failure, REM_OP (observed on strict fabrics).
-                bool local_gdr_err = (wc[i].status == IBV_WC_LOC_PROT_ERR);
-                bool remote_gdr_err = (wc[i].status == IBV_WC_REM_ACCESS_ERR ||
-                                       wc[i].status == IBV_WC_REM_OP_ERR);
-                if (local_gdr_err && slice->source_gpu_ordinal >= 0 &&
-                    slice->source_nic_name) {
-                    GdrReachability::instance().reportLocalFailure(
-                        slice->source_nic_name, slice->source_gpu_ordinal);
-                } else if (remote_gdr_err && slice->target_gpu_ordinal >= 0 &&
-                           slice->target_nic_name && slice->target_machine_id) {
-                    GdrReachability::instance().reportRemoteFailure(
-                        *slice->target_machine_id, slice->target_nic_name,
-                        slice->target_gpu_ordinal);
-                }
-                slice->retry_count++;
-                if (slice->retry_count >=
-                    transport_->params_->workers.max_retry_count) {
-                    LOG(WARNING)
-                        << "Slice " << slice << " failed: retry count exceeded";
-                    num_slices += ep->acknowledge(slice, FAILED);
-                    disableEndpoint(slice);
-                } else {
-                    num_slices += ep->acknowledge(slice, PENDING);
-                    disableEndpoint(slice);
-                    if (slice->task->cancel_requested.load(
-                            std::memory_order_acquire)) {
-                        updateSliceStatus(slice, CANCELED);
-                    } else {
-                        submit(slice);
-                    }
-                }
-            } else {
-                num_slices += ep->acknowledge(slice, COMPLETED);
-                // A successful GPU transfer re-admits any learned GDR
-                // unreachability for the (GPU, NIC) pair(s) it used, so a
-                // transient exclusion (or a recovered path) heals. Skipped
-                // entirely until something has actually been excluded.
-                if (GdrReachability::hasAnyExclusion()) {
-                    auto& gdr = GdrReachability::instance();
-                    if (slice->source_gpu_ordinal >= 0 &&
-                        slice->source_nic_name)
-                        gdr.reportLocalSuccess(slice->source_nic_name,
-                                               slice->source_gpu_ordinal);
-                    if (slice->target_gpu_ordinal >= 0 &&
-                        slice->target_nic_name && slice->target_machine_id)
-                        gdr.reportRemoteSuccess(*slice->target_machine_id,
-                                                slice->target_nic_name,
-                                                slice->target_gpu_ordinal);
-                }
-                // A successful transfer proves this rail is healthy; clear
-                // any accumulated error count so a previously-cooled-down
-                // rail can be used again without waiting for the full
-                // cooldown to expire. The monitor pointer is resolved once
-                // in generatePostPath, so no map lookup is needed here.
-                if (auto* rail = slice->rail_monitor; rail && rail->ready())
-                    rail->markRecovered(slice->source_dev_id,
-                                        slice->target_dev_id);
-                worker.perf.inflight_lat.add(inflight_lat);
-                worker.perf.enqueue_lat.add(enqueue_lat);
-            }
-        }
-    }
-    if (num_slices) {
-        worker.inflight_slices.fetch_sub(num_slices);
+        for (int i = 0; i < nr_poll; ++i)
+            handleCompletion(worker, *context, wc[i], poll_ts,
+                             i + 1 == nr_poll);
     }
 }
 
@@ -796,30 +1195,178 @@ void Workers::workerThread(int thread_id) {
     }
 }
 
-int Workers::handleContextEvents(std::shared_ptr<RdmaContext>& context) {
-    ibv_async_event event;
-    if (ibv_get_async_event(context->nativeContext(), &event) < 0) return -1;
-    LOG(WARNING) << "Received context async event "
-                 << ibv_event_type_str(event.event_type) << " for context "
-                 << context->name();
-    if (event.event_type == IBV_EVENT_QP_FATAL ||
-        event.event_type == IBV_EVENT_WQ_FATAL) {
-        auto endpoint = (RdmaEndPoint*)event.element.qp->qp_context;
-        context->endpointStore()->remove(endpoint);
-    } else if (event.event_type == IBV_EVENT_CQ_ERR) {
-        context->pause();
-        context->resume();
-        LOG(WARNING) << "Action: " << context->name() << " restarted";
-    } else if (event.event_type == IBV_EVENT_DEVICE_FATAL ||
-               event.event_type == IBV_EVENT_PORT_ERR) {
-        context->pause();
-        LOG(WARNING) << "Action: " << context->name() << " down";
-    } else if (event.event_type == IBV_EVENT_PORT_ACTIVE) {
-        context->resume();
-        LOG(WARNING) << "Action: " << context->name() << " up";
+int Workers::handleContextEvents(int dev_id,
+                                 std::shared_ptr<RdmaContext>& context) {
+    // The async fd is non-blocking and edge-triggered
+    // (joinNonblockingPollList), and ibv_get_async_event() dequeues one record
+    // per call, so every queued event has to be consumed here: epoll only
+    // reports readiness again once a *new* event arrives. Bursts are routine
+    // (IBV_EVENT_COMM_EST fires once per connection), and a PORT_ACTIVE
+    // stranded behind one keeps the context paused until some unrelated event
+    // happens to release it -- which may be never.
+    while (true) {
+        ibv_async_event event;
+        errno = 0;
+        if (ibv_get_async_event(context->nativeContext(), &event) < 0) {
+            if (errno == EAGAIN || errno == EWOULDBLOCK) return 0;  // drained
+            if (errno == EINTR) continue;
+            PLOG(ERROR) << "ibv_get_async_event for context "
+                        << context->name();
+            return -1;
+        }
+        if (event.event_type == IBV_EVENT_COMM_EST) {
+            VLOG(1) << "Received context async event "
+                    << ibv_event_type_str(event.event_type) << " for context "
+                    << context->name();
+        } else {
+            LOG(WARNING) << "Received context async event "
+                         << ibv_event_type_str(event.event_type)
+                         << " for context " << context->name();
+        }
+        applyContextEvent(dev_id, *context, event);
+        ibv_ack_async_event(&event);
+    }
+}
+
+void Workers::applyContextEvent(int dev_id, RdmaContext& context,
+                                const ibv_async_event& event) {
+    // Switched as an int, not as the enum: kIbvEventDeviceSpeedChange is not
+    // an enumerator on older headers, and the default below already covers
+    // every event this does not act on.
+    switch (static_cast<int>(event.event_type)) {
+        case IBV_EVENT_QP_FATAL:
+        case IBV_EVENT_WQ_FATAL: {
+            auto endpoint = (RdmaEndPoint*)event.element.qp->qp_context;
+            context.endpointStore()->remove(endpoint);
+            break;
+        }
+        case IBV_EVENT_CQ_ERR:
+            context.pause();
+            context.resume();
+            LOG(WARNING) << "Action: " << context.name() << " restarted";
+            break;
+        case IBV_EVENT_DEVICE_FATAL:
+            // Device-scoped: every port is gone.
+            context.pause();
+            device_selector_->setDeviceAvailable(dev_id, false);
+            LOG(WARNING) << "Action: " << context.name() << " down";
+            break;
+        case IBV_EVENT_PORT_ERR:
+        case IBV_EVENT_PORT_ACTIVE: {
+            if (event.element.port_num != context.portNum()) {
+                LOG(INFO) << context.name() << ": ignoring "
+                          << ibv_event_type_str(event.event_type)
+                          << " for port " << event.element.port_num
+                          << " (this context uses port "
+                          << static_cast<int>(context.portNum()) << ")";
+                break;
+            }
+            if (event.event_type == IBV_EVENT_PORT_ERR) {
+                context.pause();
+                // Out of selection and out of the aggregate until the port
+                // returns; its EWMA cannot learn anything while no traffic
+                // flows.
+                device_selector_->setDeviceAvailable(dev_id, false);
+                LOG(WARNING) << "Action: " << context.name() << " down";
+            } else if (activateContext(dev_id, context)) {
+                LOG(WARNING) << "Action: " << context.name() << " up";
+            }
+            break;
+        }
+        case IBV_EVENT_GID_CHANGE:
+        case IBV_EVENT_LID_CHANGE: {
+            if (event.element.port_num != context.portNum()) {
+                LOG(INFO) << context.name() << ": ignoring "
+                          << ibv_event_type_str(event.event_type)
+                          << " for port " << event.element.port_num
+                          << " (this context uses port "
+                          << static_cast<int>(context.portNum()) << ")";
+                break;
+            }
+            if (activateContext(dev_id, context)) {
+                LOG(WARNING)
+                    << "Action: " << context.name() << " refreshed after "
+                    << ibv_event_type_str(event.event_type);
+            }
+            break;
+        }
+        case kIbvEventDeviceSpeedChange:
+            // A port speed changed without a link flap (e.g. a VF over LAG
+            // losing a PF). Device-level, so the event names no port; each
+            // context opens exactly one, so re-query that one. See
+            // kIbvEventDeviceSpeedChange for why this is not behind an
+            // #ifdef on the header's enumerator.
+            refreshLinkSpeed(dev_id, context);
+            break;
+        default:
+            break;
+    }
+}
+
+RdmaAddressRefreshResult Workers::refreshAddress(RdmaContext& context) {
+    RdmaAddressSnapshot previous;
+    RdmaAddressSnapshot current;
+    auto result = context.refreshAddress(&previous, &current);
+    if (result == RdmaAddressRefreshResult::CHANGED) {
+        LOG(WARNING) << "Refreshed RDMA address for " << context.name()
+                     << ": LID " << previous.lid << " -> " << current.lid
+                     << ", GID[" << previous.gid_index << "] " << previous.gid
+                     << " -> GID[" << current.gid_index << "] " << current.gid;
+    } else if (result == RdmaAddressRefreshResult::UNCHANGED) {
+        VLOG(1) << "RDMA address for " << context.name() << " is unchanged";
     }
-    ibv_ack_async_event(&event);
-    return 0;
+    return result;
+}
+
+bool Workers::activateContext(int dev_id, RdmaContext& context) {
+    // Stop new work from selecting this NIC while its address generation is
+    // being replaced. Incoming bootstrap also rejects paused contexts.
+    if (context.pause() != 0 ||
+        context.status() != RdmaContext::DEVICE_PAUSED) {
+        if (device_selector_)
+            device_selector_->setDeviceAvailable(dev_id, false);
+        LOG(WARNING) << "Action: " << context.name()
+                     << " cannot refresh RDMA address from context state "
+                     << context.status();
+        return false;
+    }
+    if (device_selector_) device_selector_->setDeviceAvailable(dev_id, false);
+
+    auto result = refreshAddress(context);
+    if (result == RdmaAddressRefreshResult::FAILED) {
+        LOG(WARNING) << "Action: " << context.name()
+                     << " remains down because its RDMA address could not be "
+                        "refreshed";
+        return false;
+    }
+
+    // resume() evicts every endpoint built with the previous address before
+    // the NIC becomes selectable again. This is deliberately conservative for
+    // a spurious change event whose queried value is unchanged.
+    if (context.resume() != 0) return false;
+    // The link may have renegotiated while down: re-seed before the device
+    // becomes selectable so no worker scores it on the old rate.
+    refreshLinkSpeed(dev_id, context);
+    if (device_selector_) device_selector_->setDeviceAvailable(dev_id, true);
+    return true;
+}
+
+void Workers::refreshLinkSpeed(int dev_id, RdmaContext& context) {
+    if (!device_selector_) return;
+    const double before = context.linkSpeedGbps();
+    if (context.refreshPortAttributes() != 0) return;  // already logged
+    const double after = context.linkSpeedGbps();
+    // Both values decode from the same integer encodings, so exact
+    // comparison is meaningful. A speed that can no longer be read (0)
+    // counts as a change: setDeviceBandwidth() then falls back to the
+    // configured default and warns, the same as at startup.
+    if (after == before) return;
+    LOG(WARNING) << context.name() << " link speed " << before << " -> "
+                 << after << " Gbps ("
+                 << (context.effectiveSpeedKnown() ? "effective speed"
+                                                   : "encoded rate")
+                 << "), re-seeding its bandwidth estimate";
+    device_selector_->setDeviceBandwidth(dev_id, after);
 }
 
 void Workers::reclaimEndpoints() {
@@ -830,6 +1377,27 @@ void Workers::reclaimEndpoints() {
     }
 }
 
+void Workers::resumePausedContexts() {
+    for (size_t dev_id = 0; dev_id < transport_->context_set_.size();
+         ++dev_id) {
+        auto& context = transport_->context_set_[dev_id];
+        // Only a paused context is waiting for a recovery event; this also
+        // filters out inert slots, which never leave DEVICE_UNINIT.
+        if (!context || context->status() != RdmaContext::DEVICE_PAUSED)
+            continue;
+        ibv_port_state state;
+        if (context->queryPortState(&state) != 0) continue;  // already logged
+        // Only a fully active port carries traffic. Intermediate states
+        // (INIT/ARMED/ACTIVE_DEFER) mean the link is still settling, so leave
+        // the context paused and re-check on the next tick.
+        if (state != IBV_PORT_ACTIVE) continue;
+        LOG(WARNING) << "Action: " << context->name()
+                     << " up (port reports ACTIVE without an "
+                        "IBV_EVENT_PORT_ACTIVE event)";
+        activateContext(static_cast<int>(dev_id), *context);
+    }
+}
+
 void Workers::monitorThread() {
     // Track time for periodic endpoint reclaim (1 Hz heartbeat)
     auto last_reclaim_time = std::chrono::steady_clock::now();
@@ -845,10 +1413,16 @@ void Workers::monitorThread() {
 
         if (time_since_last_reclaim >= 1000) {  // 1 second = 1000 ms
             reclaimEndpoints();
+            // An endpoint destroyed above settles its orphans right here.
+            transport_->reapOrphanSlices(/*on_tick=*/true);
+            // Safety net for a recovery event that never reached us.
+            resumePausedContexts();
             last_reclaim_time = current_time;
         }
 
-        for (auto& context : transport_->context_set_) {
+        for (size_t dev_id = 0; dev_id < transport_->context_set_.size();
+             ++dev_id) {
+            auto& context = transport_->context_set_[dev_id];
             struct epoll_event event;
             if (context->eventFd() < 0) continue;
             int num_events = epoll_wait(context->eventFd(), &event, 1, 100);
@@ -859,7 +1433,7 @@ void Workers::monitorThread() {
             if (num_events == 0) continue;
             if (!(event.events & EPOLLIN)) continue;
             if (event.data.fd == context->nativeContext()->async_fd)
-                handleContextEvents(context);
+                handleContextEvents(static_cast<int>(dev_id), context);
         }
     }
 }
@@ -924,8 +1498,9 @@ Status Workers::selectOptimalDevice(RouteHint& source, RouteHint& target,
     auto& worker = worker_context_[tl_wid];
     if (slice->source_dev_id < 0) {
         CHECK_STATUS(device_selector_->allocate(
-            slice->length, source.buffer->location, slice->source_dev_id));
-        slice->quota_charged = true;
+            slice->length, source.buffer->location, slice->source_dev_id,
+            slice->priority, slice->task->device_mask));
+        slice->charged_dev = slice->source_dev_id;
     }
 
     if (slice->source_dev_id < 0)
@@ -934,8 +1509,9 @@ Status Workers::selectOptimalDevice(RouteHint& source, RouteHint& target,
 
     auto& rail = getOrCreateRail(worker.rails, target.segment->machine_id);
     if (!rail.ready() || target.topo != rail.remote())
-        rail.load(source.topo, target.topo, rail_topo_json_,
-                  transport_->conf_.get());
+        rail.load(std::shared_ptr<const Topology>(source.pin, source.topo),
+                  std::shared_ptr<const Topology>(target.pin, target.topo),
+                  rail_topo_json_, transport_->conf_.get());
     if (slice->target_dev_id < 0) {
         int mapped_dev_id = rail.findBestRemoteDevice(
             slice->source_dev_id, target.topo_entry->numa_node);
@@ -956,7 +1532,18 @@ Status Workers::selectOptimalDevice(RouteHint& source, RouteHint& target,
         for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
             const auto& list = target.topo_entry->device_list[rank];
             if (list.empty()) continue;
-            slice->target_dev_id = list[SimpleRandom::Get().next(list.size())];
+            size_t start = SimpleRandom::Get().next(list.size());
+            slice->target_dev_id = list[start];
+            // Prefer a same-NUMA peer NIC; do not fail if none exist.
+            if (strictLocalNuma()) {
+                for (size_t i = 0; i < list.size(); ++i) {
+                    int tdev = list[(start + i) % list.size()];
+                    if (!target.topo->isCrossNuma(*target.topo_entry, tdev)) {
+                        slice->target_dev_id = tdev;
+                        break;
+                    }
+                }
+            }
             break;
         }
     }
@@ -998,15 +1585,24 @@ Status Workers::selectOptimalDevice(RouteHint& source, RouteHint& target,
 
     if (gdr_excluded ||
         !rail.available(slice->source_dev_id, slice->target_dev_id)) {
-        LOG(INFO) << "Optimal device pair not available: source_dev_id "
-                  << slice->source_dev_id << ", target_dev_id "
-                  << slice->target_dev_id;
+        VLOG(1) << "Optimal device pair not available: source_dev_id "
+                << slice->source_dev_id << ", target_dev_id "
+                << slice->target_dev_id;
+        LOG_EVERY_N(WARNING, 10000)
+            << "Optimal device pair not available: source_dev_id "
+            << slice->source_dev_id << ", target_dev_id "
+            << slice->target_dev_id;
         return selectFallbackDevice(source, target, slice);
     }
 
     return Status::OK();
 }
 
+bool Workers::strictLocalNuma() const {
+    return device_selector_ &&
+           device_selector_->getSchedulingParams().strict_local_numa;
+}
+
 int Workers::getDeviceByFlatIndex(const RouteHint& hint, size_t flat_idx) {
     for (size_t rank = 0; rank < Topology::DevicePriorityRanks; ++rank) {
         auto& list = hint.topo_entry->device_list[rank];
@@ -1038,7 +1634,11 @@ bool Workers::gdrPairExcluded(const RouteHint& source, const RouteHint& target,
 
 Status Workers::selectFallbackDevice(RouteHint& source, RouteHint& target,
                                      RdmaSlice* slice) {
-    LOG_EVERY_N(INFO, 100) << "fallback device selection for slice " << slice;
+    // Mirrors selectOptimalDevice: a rare WARNING sample so a sustained
+    // fallback storm is visible without flooding; VLOG(1) for debugging.
+    VLOG(1) << "fallback device selection for slice " << slice;
+    LOG_EVERY_N(WARNING, 10000)
+        << "fallback device selection for slice " << slice;
     bool same_machine =
         (source.segment->machine_id == target.segment->machine_id);
 
@@ -1080,12 +1680,18 @@ Status Workers::selectFallbackDevice(RouteHint& source, RouteHint& target,
             : &getOrCreateRail(worker.rails, target.segment->machine_id);
     size_t start =
         static_cast<size_t>(slice->last_fallback_idx + 1) % total_combos;
+    const uint64_t device_mask = slice->task->device_mask;
     for (size_t k = 0; k < total_combos; ++k) {
         size_t idx = (start + k) % total_combos;
         size_t src_idx = idx / dst_total;
         size_t dst_idx = idx % dst_total;
         int sdev = getDeviceByFlatIndex(source, src_idx);
         int tdev = getDeviceByFlatIndex(target, dst_idx);
+        if (sdev < 0 || sdev >= 64 || (device_mask & (1ULL << sdev)) == 0)
+            continue;
+        if (strictLocalNuma() &&
+            source.topo->isCrossNuma(*source.topo_entry, sdev))
+            continue;
         bool reachable = same_machine ? (sdev == tdev)  // loopback is safe
                                       : rail_mon->available(sdev, tdev);
 
@@ -1095,6 +1701,11 @@ Status Workers::selectFallbackDevice(RouteHint& source, RouteHint& target,
             reachable = false;
 
         if (reachable) {
+            // A retry gets here after the failure path returned the slice's
+            // charge, so charge the device this attempt will actually use:
+            // otherwise the NIC's inflight bytes miss it and its completion
+            // teaches neither bandwidth estimate.
+            rechargeSlice(slice, sdev);
             slice->source_dev_id = sdev;
             slice->target_dev_id = tdev;
             // Keys are assigned by generatePostPath() once the device pair is
diff --git a/mooncake-transfer-engine/tent/src/transport/shm/shm_transport.cpp b/mooncake-transfer-engine/tent/src/transport/shm/shm_transport.cpp
index b13338462c..8dfc5c1bc3 100644
--- a/mooncake-transfer-engine/tent/src/transport/shm/shm_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/shm/shm_transport.cpp
@@ -103,17 +103,27 @@ Status ShmTransport::submitTransferTasks(
         return Status::InvalidArgument("Invalid SHM sub-batch" LOC_MARK);
     if (request_list.size() + shm_batch->task_list.size() > shm_batch->max_size)
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
+    // All-or-nothing submission (see Transport::submitTransferTasks):
+    // relocate every request first so any error is reported before a single
+    // transfer starts; otherwise a mid-batch relocate failure would leave the
+    // earlier requests already copied, and the engine's failover retry would
+    // execute them twice.
+    std::vector<uint64_t> target_addrs;
+    target_addrs.reserve(request_list.size());
     for (auto &request : request_list) {
-        shm_batch->task_list.push_back(ShmTask{});
-        auto &task = shm_batch->task_list[shm_batch->task_list.size() - 1];
         uint64_t target_addr = request.target_offset;
         if (request.target_id != LOCAL_SEGMENT_ID) {
             auto status = relocateSharedMemoryAddress(
                 target_addr, request.length, request.target_id);
             if (!status.ok()) return status;
         }
-        task.target_addr = target_addr;
-        task.request = request;
+        target_addrs.push_back(target_addr);
+    }
+    for (size_t i = 0; i < request_list.size(); ++i) {
+        shm_batch->task_list.push_back(ShmTask{});
+        auto &task = shm_batch->task_list[shm_batch->task_list.size() - 1];
+        task.target_addr = target_addrs[i];
+        task.request = request_list[i];
         task.status_word = TransferStatusEnum::PENDING;
         startTransfer(&task, shm_batch);
     }
diff --git a/mooncake-transfer-engine/tent/src/transport/sunrise_link/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/sunrise_link/CMakeLists.txt
index c0bfd59413..266fd62c7f 100644
--- a/mooncake-transfer-engine/tent/src/transport/sunrise_link/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/transport/sunrise_link/CMakeLists.txt
@@ -17,5 +17,5 @@ if(USE_SUNRISE)
   target_include_directories(tent_xport_sunrise_link
                               PUBLIC ${MC_TANGRT_ROOT}/include/)
   target_link_libraries(tent_xport_sunrise_link
-                        PUBLIC tent_common glog glog::glog ${SUNRISE_LIBRARIES})
+                        PUBLIC tent_common glog::glog ${SUNRISE_LIBRARIES})
 endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/tcp/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/tcp/CMakeLists.txt
index 3b49319c32..0942f9e522 100644
--- a/mooncake-transfer-engine/tent/src/transport/tcp/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/src/transport/tcp/CMakeLists.txt
@@ -1,3 +1,2 @@
-file(GLOB XPORT_SOURCES "*.cpp")
-add_library(tent_xport_tcp STATIC ${XPORT_SOURCES})
+add_library(tent_xport_tcp STATIC tcp_transport.cpp)
 target_link_libraries(tent_xport_tcp PUBLIC tent_rpc tent_common)
diff --git a/mooncake-transfer-engine/tent/src/transport/tcp/tcp_transport.cpp b/mooncake-transfer-engine/tent/src/transport/tcp/tcp_transport.cpp
index 973173ca72..d40c85e5b6 100644
--- a/mooncake-transfer-engine/tent/src/transport/tcp/tcp_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/tcp/tcp_transport.cpp
@@ -86,6 +86,7 @@ Status TcpTransport::install(std::string &local_segment_name,
                       params_.max_concurrent_tasks);
     }
 
+    shutting_down_.store(false, std::memory_order_release);
     thread_pool_ = std::make_unique<ThreadPool>(params_.max_concurrent_tasks);
 
     installed_ = true;
@@ -110,14 +111,25 @@ Status TcpTransport::install(std::string &local_segment_name,
 Status TcpTransport::uninstall() {
     if (installed_) {
         if (metadata_) metadata_->setNotifyCallback(nullptr);
-        shutting_down_.store(true, std::memory_order_release);
-        thread_pool_.reset();
+        quiesce();
         metadata_.reset();
         installed_ = false;
     }
     return Status::OK();
 }
 
+Status TcpTransport::quiesce() {
+    std::unique_ptr<ThreadPool> thread_pool;
+    {
+        std::lock_guard<std::mutex> guard(lifecycle_mutex_);
+        shutting_down_.store(true, std::memory_order_release);
+        thread_pool = std::move(thread_pool_);
+    }
+    // Join outside the admission lock so completion callbacks can return.
+    thread_pool.reset();
+    return Status::OK();
+}
+
 Status TcpTransport::allocateSubBatch(SubBatchRef &batch, size_t max_size) {
     auto tcp_batch = Slab<TcpSubBatch>::Get().allocate();
     if (!tcp_batch)
@@ -142,6 +154,10 @@ Status TcpTransport::submitTransferTasks(
     auto tcp_batch = dynamic_cast<TcpSubBatch *>(batch);
     if (!tcp_batch)
         return Status::InvalidArgument("Invalid TCP sub-batch" LOC_MARK);
+    std::lock_guard<std::mutex> guard(lifecycle_mutex_);
+    if (shutting_down_.load(std::memory_order_acquire)) {
+        return Status::InternalError("TCP transport is shutting down" LOC_MARK);
+    }
     if (request_list.size() + tcp_batch->task_list.size() > tcp_batch->max_size)
         return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
 
@@ -175,6 +191,8 @@ Status TcpTransport::getTransferStatus(SubBatchRef batch, int task_id,
     status.s = task.status_word.load(std::memory_order_acquire);
     status.transferred_bytes =
         task.transferred_bytes.load(std::memory_order_acquire);
+    if (status.s == TransferStatusEnum::FAILED && task.non_replayable_failure)
+        return Status::RpcServiceError("TCP WRITE outcome is unknown" LOC_MARK);
     return Status::OK();
 }
 
@@ -189,18 +207,37 @@ Status TcpTransport::removeMemoryBuffer(BufferDesc &desc) {
 }
 
 void TcpTransport::startTransfer(TcpTask *task) {
-    if (task->request.target_id == LOCAL_SEGMENT_ID &&
-        IsLoopbackEndpoint(local_segment_name_)) {
-        LOG_FIRST_N(WARNING, 1)
-            << "TCP transfer targets LOCAL_SEGMENT_ID on loopback endpoint "
-            << local_segment_name_
-            << ". When running multiple store instances on the same host with "
-               "MC_STORE_MEMCPY=0, TCP local transfers will fail. Enable "
-               "MC_STORE_MEMCPY or SHM, or use a non-loopback address.";
+    // Terminal publication allows freeBatch() to destroy task immediately.
+    // The worker must own the callback and keep no task accesses after it.
+    auto notify_progress = std::move(task->notify_progress);
+    const auto progress_batch_id = task->progress_batch_id;
+    bool completed = false;
+    try {
+        if (task->request.target_id == LOCAL_SEGMENT_ID &&
+            IsLoopbackEndpoint(local_segment_name_)) {
+            LOG_FIRST_N(WARNING, 1)
+                << "TCP transfer targets LOCAL_SEGMENT_ID on loopback endpoint "
+                << local_segment_name_
+                << ". When running multiple store instances on the same host "
+                   "with "
+                   "MC_STORE_MEMCPY=0, TCP local transfers will fail. Enable "
+                   "MC_STORE_MEMCPY or SHM, or use a non-loopback address.";
+        }
+        auto status = doTransferWithRetry(task);
+        completed = status.ok();
+        if (!completed) {
+            VLOG(1) << "TCP transfer failed: " << status.ToString();
+            LOG_EVERY_N(WARNING, 100)
+                << "TCP transfer failed: " << status.ToString();
+        }
+    } catch (const std::exception &error) {
+        // enqueue() stores exceptions in a future which the submit path does
+        // not consume. Convert failures here while task is still owned.
+        LOG(WARNING) << "TCP worker exception: " << error.what();
+    } catch (...) {
+        LOG(WARNING) << "TCP worker exception: unknown exception";
     }
-
-    auto status = doTransferWithRetry(task);
-    if (status.ok()) {
+    if (completed) {
         // Store bytes before status: a reader who acquires COMPLETED will
         // also see the final transferred_bytes value.
         task->transferred_bytes.store(task->request.length,
@@ -208,15 +245,16 @@ void TcpTransport::startTransfer(TcpTask *task) {
         task->status_word.store(TransferStatusEnum::COMPLETED,
                                 std::memory_order_release);
     } else {
-        LOG(WARNING) << "TCP transfer failed after " << params_.max_retry_count
-                     << " retries: " << status.ToString();
         task->status_word.store(TransferStatusEnum::FAILED,
                                 std::memory_order_release);
     }
-    if (task->notify_progress) task->notify_progress(task->progress_batch_id);
+    if (notify_progress) notify_progress(progress_batch_id);
 }
 
 Status TcpTransport::doTransferWithRetry(TcpTask *task) {
+    if (shutting_down_.load(std::memory_order_acquire))
+        return Status::InternalError("Transport shutting down");
+
     std::string rpc_server_addr;
     auto status =
         findRemoteSegment(task->request.target_offset, task->request.length,
@@ -231,9 +269,12 @@ Status TcpTransport::doTransferWithRetry(TcpTask *task) {
             return Status::InternalError("Transport shutting down");
 
         if (attempt > 0) {
-            LOG(INFO) << "TCP transfer retry attempt " << attempt << "/"
-                      << params_.max_retry_count << ", backoff " << delay_ms
-                      << "ms";
+            VLOG(1) << "TCP transfer retry attempt " << attempt << "/"
+                    << params_.max_retry_count << ", backoff " << delay_ms
+                    << "ms";
+            LOG_EVERY_N(INFO, 100)
+                << "TCP transfer retry attempt " << attempt << "/"
+                << params_.max_retry_count << ", backoff " << delay_ms << "ms";
             // Sleep in small increments so shutdown is not delayed
             for (uint64_t i = 0; i < delay_ms; i += 100) {
                 if (shutting_down_.load(std::memory_order_acquire))
@@ -241,7 +282,7 @@ Status TcpTransport::doTransferWithRetry(TcpTask *task) {
                 std::this_thread::sleep_for(std::chrono::milliseconds(
                     std::min(static_cast<uint64_t>(100), delay_ms - i)));
             }
-            delay_ms = std::min(delay_ms * 2, params_.retry_max_delay_ms);
+            delay_ms = nextTcpRetryDelay(delay_ms, params_.retry_max_delay_ms);
         }
 
         if (task->request.opcode == Request::WRITE) {
@@ -257,16 +298,27 @@ Status TcpTransport::doTransferWithRetry(TcpTask *task) {
         if (status.ok()) return Status::OK();
 
         last_error = status;
-        LOG(WARNING) << "TCP transfer attempt " << attempt
-                     << " failed: " << status.ToString();
+        VLOG(1) << "TCP transfer attempt " << attempt
+                << " failed: " << status.ToString();
+        LOG_EVERY_N(WARNING, 1000) << "TCP transfer attempt " << attempt
+                                   << " failed: " << status.ToString();
+
+        if (task->request.opcode == Request::WRITE &&
+            status.IsRpcServiceError() && !status.IsRpcConnectionError()) {
+            task->non_replayable_failure = true;
+            return status;
+        }
 
         if (!status.IsRpcServiceError() && !status.IsInternalError()) {
             return status;
         }
 
-        // Peer may have restarted with a new address; re-resolve before retry
-        if (status.IsRpcServiceError()) {
-            rpc_server_addr.clear();
+        // Only a pre-send connection failure permits an endpoint refresh
+        // followed by automatic WRITE replay.
+        if (status.IsRpcConnectionError()) {
+            CHECK_STATUS(metadata_->segmentManager().invalidateRemote(
+                task->request.target_id));
+            if (attempt == params_.max_retry_count) break;
             auto resolve = findRemoteSegment(
                 task->request.target_offset, task->request.length,
                 task->request.target_id, rpc_server_addr);
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/endpoint.cpp b/mooncake-transfer-engine/tent/src/transport/ub/endpoint.cpp
index 953cf6d4fe..665e9204d1 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/endpoint.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/endpoint.cpp
@@ -4,6 +4,7 @@
 #include "tent/transport/ub/endpoint.h"
 
 #include <algorithm>
+#include <cassert>
 #include <chrono>
 #include <exception>
 #include <iterator>
@@ -134,6 +135,11 @@ Status UbEndpoint::deleteJettysLocked() {
     retained_jfc_indices.reserve(jfc_indices_.size());
     for (size_t index = 0; index < jetties_.size(); ++index) {
         if (deleted[index]) continue;
+        // Both arrays are appended together, so a missing index means the
+        // bookkeeping is already corrupt. Fail loudly instead of silently
+        // rebinding a retained Jetty to JFC 0; the guard keeps release builds
+        // memory-safe.
+        assert(index < jfc_indices_.size());
         retained_jetties.push_back(std::move(jetties_[index]));
         retained_jfc_indices.push_back(
             index < jfc_indices_.size() ? jfc_indices_[index] : size_t{0});
@@ -216,7 +222,14 @@ Status UbEndpoint::prepare() {
             return failLocked(std::move(status));
         }
         if (!jetty || !jetty->valid() || jetty->id() == 0) {
-            if (jetty) jetties_.push_back(std::move(jetty));
+            if (jetty) {
+                // Adopt the invalid Jetty together with its JFC index: the
+                // cleanup path walks jetties_ and jfc_indices_ in lockstep, so
+                // appending to only one of them would misalign every later
+                // entry.
+                jetties_.push_back(std::move(jetty));
+                jfc_indices_.push_back(jfc_index);
+            }
             return failLocked(Status::InternalError(
                 "URMA adapter returned an invalid Jetty" LOC_MARK));
         }
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/endpoint_store.cpp b/mooncake-transfer-engine/tent/src/transport/ub/endpoint_store.cpp
index 9b64f9da34..d2c01c8f58 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/endpoint_store.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/endpoint_store.cpp
@@ -3,6 +3,7 @@
 
 #include "tent/transport/ub/endpoint_store.h"
 
+#include <chrono>
 #include <iterator>
 #include <limits>
 #include <utility>
@@ -11,6 +12,12 @@
 namespace mooncake::tent::ub {
 namespace {
 
+// Minimum spacing between quarantine sweeps. A sweep issues native retire
+// calls (resetJetty/deleteJetty) while the store lock is held, so an
+// unconditional retry would let one failing device serialize failing provider
+// operations across every posting thread.
+constexpr auto kQuarantineSweepInterval = std::chrono::milliseconds(250);
+
 bool retirementComplete(const std::shared_ptr<UbEndpoint>& endpoint) {
     return endpoint && endpoint->state() == UbEndpoint::State::kDestroyed;
 }
@@ -24,11 +31,12 @@ Status retirementPending() {
 
 EndpointStore::EndpointStore(std::shared_ptr<UrmaAdapter> adapter,
                              size_t max_size, uint32_t jetty_count,
-                             JettyOptions jetty_options)
+                             JettyOptions jetty_options, SteadyClock clock)
     : adapter_(std::move(adapter)),
       max_size_(max_size),
       jetty_count_(jetty_count),
-      jetty_options_(jetty_options) {}
+      jetty_options_(jetty_options),
+      clock_(std::move(clock)) {}
 
 EndpointStore::~EndpointStore() {
     auto status = clear();
@@ -76,10 +84,6 @@ Status EndpointStore::getOrCreate(const UbEndpointKey& key,
 
     {
         std::lock_guard<std::mutex> lock(mutex_);
-        // A transient provider busy/error must not permanently consume the
-        // cache. Retry unpublished ownership before deciding that no slot is
-        // available for a replacement generation.
-        (void)retryQuarantinedLocked();
         auto existing = endpoints_.find(key);
         if (existing != endpoints_.end()) {
             if (existing->second.endpoint &&
@@ -92,6 +96,19 @@ Status EndpointStore::getOrCreate(const UbEndpointKey& key,
             }
         }
 
+        // A transient provider busy/error must not permanently consume the
+        // cache, but sweeping quarantine is only worth its native calls when a
+        // slot is actually needed, and it is rate limited so a still-failing
+        // device cannot make every posting call pay for a full sweep.
+        if (!endpoint && endpoints_.size() + quarantined_.size() >= max_size_) {
+            const auto now =
+                clock_ ? clock_() : std::chrono::steady_clock::now();
+            if (now >= next_quarantine_sweep_) {
+                next_quarantine_sweep_ = now + kQuarantineSweepInterval;
+                (void)retryQuarantinedLocked();
+            }
+        }
+
         while (!endpoint &&
                endpoints_.size() + quarantined_.size() >= max_size_) {
             auto victim = endpoints_.end();
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/rail_monitor.cpp b/mooncake-transfer-engine/tent/src/transport/ub/rail_monitor.cpp
index 02ae248945..0434f4d4ee 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/rail_monitor.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/rail_monitor.cpp
@@ -115,6 +115,14 @@ bool RailMonitor::recordEndpointRebuild(const UbPostPath& path,
     auto& state = getOrCreateLocked(path);
     now_ns = observeTimeLocked(state, now_ns);
     refreshCooldownLocked(state, now_ns);
+    if (!state.has_rebuild_baseline) {
+        // The first generation to become ready is the rail's initial build.
+        // Seed the watermark without counting it so endpoint_rebuilds only
+        // advances on a real generation increase.
+        state.has_rebuild_baseline = true;
+        state.recorded_rebuild_generation = path.endpoint_generation;
+        return false;
+    }
     if (path.endpoint_generation <= state.recorded_rebuild_generation) {
         return false;
     }
@@ -123,6 +131,17 @@ bool RailMonitor::recordEndpointRebuild(const UbPostPath& path,
     return true;
 }
 
+RailStats RailMonitor::statsIfPresent(const UbPostPath& path, uint64_t now_ns) {
+    RailStats result;
+    result.key = UbRailKey::fromPath(path);
+    if (!path.valid()) return result;
+    now_ns = normalizedNow(now_ns);
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = rails_.find(result.key);
+    if (it == rails_.end()) return result;
+    return snapshotLocked(it->second, now_ns);
+}
+
 RailStats RailMonitor::stats(const UbPostPath& path, uint64_t now_ns) {
     RailStats result;
     result.key = UbRailKey::fromPath(path);
@@ -130,9 +149,12 @@ RailStats RailMonitor::stats(const UbPostPath& path, uint64_t now_ns) {
     now_ns = normalizedNow(now_ns);
     std::lock_guard<std::mutex> lock(mutex_);
     auto& state = getOrCreateLocked(path);
+    return snapshotLocked(state, now_ns);
+}
+
+RailStats RailMonitor::snapshotLocked(RailState& state, uint64_t now_ns) {
     now_ns = observeTimeLocked(state, now_ns);
     refreshCooldownLocked(state, now_ns);
-    pruneErrorsLocked(state, now_ns);
     state.stats.errors_in_window = static_cast<uint32_t>(std::min<size_t>(
         state.recent_errors.size(), std::numeric_limits<uint32_t>::max()));
     return state.stats;
@@ -144,12 +166,7 @@ std::vector<RailStats> RailMonitor::allStats(uint64_t now_ns) {
     std::vector<RailStats> result;
     result.reserve(rails_.size());
     for (auto& [key, state] : rails_) {
-        const uint64_t observed_ns = observeTimeLocked(state, now_ns);
-        refreshCooldownLocked(state, observed_ns);
-        pruneErrorsLocked(state, observed_ns);
-        state.stats.errors_in_window = static_cast<uint32_t>(std::min<size_t>(
-            state.recent_errors.size(), std::numeric_limits<uint32_t>::max()));
-        result.push_back(state.stats);
+        result.push_back(snapshotLocked(state, now_ns));
     }
     return result;
 }
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/ub_transport.cpp b/mooncake-transfer-engine/tent/src/transport/ub/ub_transport.cpp
index cfb5c41ce1..652b18c6d3 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/ub_transport.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/ub_transport.cpp
@@ -221,7 +221,8 @@ struct UbTransport::Impl {
             if (explicit_filter) {
                 selection_log << "UB device selection: mode=explicit-filter";
             } else if (prefer_bonding) {
-                selection_log << "UB device selection: mode=auto-prefer-bonding";
+                selection_log
+                    << "UB device selection: mode=auto-prefer-bonding";
             } else {
                 selection_log << "UB device selection: mode=all-devices";
             }
@@ -356,7 +357,17 @@ struct UbTransport::Impl {
     }
 
     Status failInstall(Status failure) {
-        (void)shutdownUnlocked();
+        // Install now fails fast, so a failed rollback can leave native
+        // resources owned by this object. Surface that instead of silently
+        // discarding it, otherwise the leak is only visible as a later
+        // install/uninstall failure.
+        auto cleanup = shutdownUnlocked();
+        if (!cleanup.ok()) {
+            LOG(WARNING)
+                << "UB transport rollback after a failed install could "
+                   "not release every native resource: "
+                << cleanup.ToString();
+        }
         return failure;
     }
 
@@ -421,10 +432,6 @@ struct UbTransport::Impl {
         local_topology.reset();
         conf.reset();
         local_segment_name.clear();
-        {
-            std::lock_guard<std::mutex> lock(endpoint_generation_mutex);
-            ready_endpoint_generations.clear();
-        }
         shutting_down.store(false, std::memory_order_release);
         return Status::OK();
     }
@@ -468,20 +475,16 @@ struct UbTransport::Impl {
     void recordReadyEndpoint(const std::shared_ptr<ub::UbEndpoint>& endpoint) {
         if (!endpoint || !endpoint->ready() || !rails) return;
 
-        const auto generation = endpoint->generation();
+        // RailMonitor keeps the per-rail generation watermark and ignores
+        // generations it has already seen, so this is safe to call from every
+        // resolve as well as from converging or retried rebuild paths. Keeping
+        // the watermark there also means no peer-keyed state accumulates here
+        // across peer restarts, and the posting hot path takes only
+        // RailMonitor's lock instead of a second transport-wide one.
         const auto& key = endpoint->key();
-        std::lock_guard<std::mutex> lock(endpoint_generation_mutex);
-        auto [it, inserted] =
-            ready_endpoint_generations.emplace(key, generation);
-        if (!inserted && generation > it->second) {
-            // Serialize the generation watermark with telemetry so a delayed
-            // callback for an older incarnation can neither roll the map back
-            // nor race a newer rebuild into a double count.
-            it->second = generation;
-            rails->recordEndpointRebuild(
-                ub::UbPostPath{key.local_topology_id, key.remote_segment_id,
-                               key.remote_topology_id, generation});
-        }
+        rails->recordEndpointRebuild(
+            ub::UbPostPath{key.local_topology_id, key.remote_segment_id,
+                           key.remote_topology_id, endpoint->generation()});
     }
 
     Status resolveEndpoint(const ub::EndpointResolveRequest& request,
@@ -587,7 +590,6 @@ struct UbTransport::Impl {
     }
 
     mutable std::mutex lifecycle_mutex;
-    mutable std::mutex endpoint_generation_mutex;
     std::shared_ptr<ub::UrmaAdapter> adapter;
     bool adapter_initialized{false};
     bool callback_installed{false};
@@ -608,8 +610,6 @@ struct UbTransport::Impl {
     std::unique_ptr<ub::RailMonitor> rails;
     std::unique_ptr<ub::QuotaManager> quota;
     std::unique_ptr<ub::UbWorkers> workers;
-    std::unordered_map<ub::UbEndpointKey, uint64_t, ub::UbEndpointKeyHash>
-        ready_endpoint_generations;
 };
 
 UbTransport::UbTransport(std::shared_ptr<ub::UrmaAdapter> adapter)
@@ -708,6 +708,14 @@ Status UbTransport::submitTransferTasks(
     std::vector<ub::UbTask::Ptr> new_tasks;
     new_tasks.reserve(request_list.size());
     for (const auto& request : request_list) {
+        const size_t slice_count =
+            request.length / impl_->params.slice_size +
+            (request.length % impl_->params.slice_size != 0 ? 1 : 0);
+        if (slice_count > impl_->params.max_slices_per_task) {
+            return Status::InvalidArgument(
+                "UB request exceeds "
+                "transports/ub/max_slices_per_task" LOC_MARK);
+        }
         auto task = ub::UbTask::create(
             request,
             [notify_progress, progress_batch_id](const TransferStatus&) {
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/urma_adapter.cpp b/mooncake-transfer-engine/tent/src/transport/ub/urma_adapter.cpp
index dec21df008..eaaac17088 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/urma_adapter.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/urma_adapter.cpp
@@ -672,9 +672,9 @@ class RealJetty final : public Jetty {
         config.flag.bs.share_jfr = 1;
         config.jfs_cfg.depth = options.depth;
         config.jfs_cfg.trans_mode = URMA_TM_RC;
-        config.jfs_cfg.priority =
-            context_->isBondingDevice() ? context_->ctpPriority()
-                                        : options.priority;
+        config.jfs_cfg.priority = context_->isBondingDevice()
+                                      ? context_->ctpPriority()
+                                      : options.priority;
         if (context_->isBondingDevice()) {
             config.jfs_cfg.flag.bs.multi_path = 1;
         }
@@ -1156,8 +1156,8 @@ class RealUrmaAdapter final : public UrmaAdapter {
                     urma_user_ctl(native_context, &ctl_in, &ctl_out);
                 if (ctl_rc != URMA_SUCCESS) {
                     (void)urma_delete_context(native_context);
-                    return nativeError(
-                        "urma_user_ctl(SET_BONDING_MODE)", ctl_rc);
+                    return nativeError("urma_user_ctl(SET_BONDING_MODE)",
+                                       ctl_rc);
                 }
             }
 
@@ -1192,9 +1192,9 @@ class RealUrmaAdapter final : public UrmaAdapter {
                                         ":eid" +
                                         std::to_string(current.eid_index);
             }
-            output = std::make_shared<RealContext>(std::move(runtime),
-                                                   std::move(current),
-                                                   native_context, ctp_priority);
+            output = std::make_shared<RealContext>(
+                std::move(runtime), std::move(current), native_context,
+                ctp_priority);
             return Status::OK();
         }
         return Status::DeviceNotFound("URMA device not found: " +
@@ -1265,8 +1265,7 @@ class RealUrmaAdapter final : public UrmaAdapter {
             return Status::InvalidArgument("invalid local segment range");
         }
 
-        urma_token_id_t* token_id =
-            urma_alloc_token_id(real_context->native());
+        urma_token_id_t* token_id = urma_alloc_token_id(real_context->native());
         if (token_id == nullptr) {
             return nativePointerError("urma_alloc_token_id");
         }
diff --git a/mooncake-transfer-engine/tent/src/transport/ub/workers.cpp b/mooncake-transfer-engine/tent/src/transport/ub/workers.cpp
index b5b5a75597..effe77fff2 100644
--- a/mooncake-transfer-engine/tent/src/transport/ub/workers.cpp
+++ b/mooncake-transfer-engine/tent/src/transport/ub/workers.cpp
@@ -29,6 +29,19 @@ bool retryableStatus(const Status& status) {
            status.IsRdmaError();
 }
 
+// Rail health and quota are keyed by the physical rail, which deliberately
+// excludes the endpoint generation (see UbRailKey). These read-only probes
+// therefore only need a generation that satisfies UbPostPath::valid(); real
+// endpoint generations are monotonic and never below this value.
+constexpr uint64_t kRailProbeEndpointGeneration = 1;
+
+// Number of candidates always taken in pre-score order, regardless of which
+// local device they belong to. Two is the floor that keeps tryAcquireFirst from
+// deferring a slice when its top pick is preempted by another worker, including
+// on a single-local-device topology where per-device coverage alone would leave
+// only one candidate.
+constexpr size_t kMinResolvedCandidates = 2;
+
 }  // namespace
 
 struct UbWorkers::Route {
@@ -579,6 +592,19 @@ Status UbWorkers::chooseAndResolveEndpoint(
         UbPathSelectionScore score;
     };
 
+    // One local x remote combination, scored from rail-level state before any
+    // endpoint is resolved. Endpoint-level load is deliberately absent: it is
+    // only available after resolution and is applied to the finalists below.
+    struct RailCandidate {
+        Topology::NicID local_id;
+        int remote_id;
+        size_t topology_rank;
+        size_t retry_order;
+        UbPostPath probe_path;
+        RailStats rail_stats;
+        QuotaAvailability capacity;
+    };
+
     const auto local_devices = orderedLocalDevices(pending);
     if (route.remote_devices.empty()) {
         return Status::DeviceNotFound("No usable UB posting path" LOC_MARK);
@@ -620,16 +646,73 @@ Status UbWorkers::chooseAndResolveEndpoint(
         combinations == 0 ? 0 : snapshot.retry_count % combinations;
     Status first_error = Status::DeviceNotFound(
         "No ready UB endpoint for any posting path" LOC_MARK);
-    std::vector<Candidate> candidates;
-    candidates.reserve(combinations);
+
+    auto railScore = [](const RailCandidate& candidate) {
+        return UbPathSelectionScore{
+            candidate.capacity.can_acquire,
+            candidate.topology_rank,
+            candidate.capacity.normalized_inflight,
+            candidate.capacity.normalized_outstanding_wrs,
+            0,
+            0,
+            candidate.rail_stats.ewma_bandwidth_bytes_per_second >= 0.0,
+            candidate.rail_stats.ewma_bandwidth_bytes_per_second,
+            candidate.retry_order,
+            candidate.local_id,
+            candidate.remote_id};
+    };
+
+    // Phase 1: rank every combination from rail-level state only. Resolving an
+    // uncached endpoint costs a bootstrap RPC to the peer, so this pass must
+    // not resolve anything.
+    std::vector<RailCandidate> rails;
+    rails.reserve(combinations);
     for (size_t flat = 0; flat < combinations; ++flat) {
         const auto& local = local_devices[flat / route.remote_devices.size()];
-        const auto local_id = local.id;
         const auto remote_id =
             route.remote_devices[flat % route.remote_devices.size()];
-        auto context = context_by_topology_id_.at(local_id);
+        const UbPostPath probe_path{local.id, pending.target_id, remote_id,
+                                    kRailProbeEndpointGeneration};
+        // A non-inserting lookup: an unknown rail scores as "no health history
+        // yet" without being added to the map, so probing every local x remote
+        // combination cannot grow the rail map or seed a generation for a rail
+        // that is never posted to.
+        auto rail_stats = rail_monitor_->statsIfPresent(probe_path);
+        if (rail_stats.paused) continue;
+        rails.push_back(RailCandidate{
+            local.id, remote_id, local.topology_rank,
+            (flat + combinations - start) % combinations, probe_path,
+            std::move(rail_stats),
+            quota_->availability(probe_path, pending.slice->spec().length)});
+    }
+    std::stable_sort(rails.begin(), rails.end(),
+                     [&](const RailCandidate& lhs, const RailCandidate& rhs) {
+                         return betterUbPathScore(railScore(lhs),
+                                                  railScore(rhs));
+                     });
+
+    // Phase 2: resolve lazily in the order produced by
+    // ubResolutionAttemptOrder(), which takes the best rail of each local
+    // device first and the remaining rails only after that. So the candidates
+    // span devices instead of piling onto whichever device ranks best, and a
+    // rail that cannot be resolved simply yields to the next attempt -
+    // including the remaining rails on its own device from pass two. The
+    // bootstrap fan-out is therefore bounded by the number of local devices -
+    // one endpoint per device on a cold peer - rather than by the local x
+    // remote combination count.
+    const size_t resolve_limit =
+        std::max(kMinResolvedCandidates, local_devices.size());
+    std::vector<Topology::NicID> rail_local_ids;
+    rail_local_ids.reserve(rails.size());
+    for (const auto& rail : rails) rail_local_ids.push_back(rail.local_id);
+    std::vector<Candidate> candidates;
+    candidates.reserve(std::min(rails.size(), resolve_limit));
+    for (size_t attempt : ubResolutionAttemptOrder(rail_local_ids)) {
+        if (candidates.size() >= resolve_limit) break;
+        const auto& rail = rails[attempt];
+        auto context = context_by_topology_id_.at(rail.local_id);
         EndpointResolveRequest request{context, pending.target_id,
-                                       route.pin.get(), remote_id,
+                                       route.pin.get(), rail.remote_id,
                                        route.metadata.generation};
         std::shared_ptr<UbEndpoint> candidate_endpoint;
         auto status = endpoint_resolver_(request, candidate_endpoint);
@@ -639,25 +722,27 @@ Status UbWorkers::chooseAndResolveEndpoint(
                 first_error = status;
             continue;
         }
-        UbPostPath candidate_path{local_id, pending.target_id, remote_id,
+        UbPostPath candidate_path{rail.local_id, pending.target_id,
+                                  rail.remote_id,
                                   candidate_endpoint->generation()};
+        // Re-read rail state under the real generation: the rail may only have
+        // been created by the resolution above.
         const auto rail_stats = rail_monitor_->stats(candidate_path);
         if (rail_stats.paused) continue;
         const auto capacity =
             quota_->availability(candidate_path, pending.slice->spec().length);
-        const size_t retry_order = (flat + combinations - start) % combinations;
         const uint64_t endpoint_wrs = candidate_endpoint->outstandingWrs();
         const uint64_t endpoint_bytes = candidate_endpoint->outstandingBytes();
         candidates.push_back(
             Candidate{std::move(candidate_endpoint), candidate_path,
                       UbPathSelectionScore{
-                          capacity.can_acquire, local.topology_rank,
+                          capacity.can_acquire, rail.topology_rank,
                           capacity.normalized_inflight,
                           capacity.normalized_outstanding_wrs, endpoint_wrs,
                           endpoint_bytes,
                           rail_stats.ewma_bandwidth_bytes_per_second >= 0.0,
                           rail_stats.ewma_bandwidth_bytes_per_second,
-                          retry_order, local_id, remote_id}});
+                          rail.retry_order, rail.local_id, rail.remote_id}});
     }
     if (candidates.empty()) {
         if (first_error.IsTooManyRequests()) {
@@ -882,11 +967,9 @@ void UbWorkers::progressLocalDeviceFailure(const UbContextPtr& context) {
         context->completeFailureCleanup();
         return;
     }
-    if (!status.ok()) {
-        LOG_EVERY_N(WARNING, 100)
-            << "UB endpoint retirement after local device failure is pending: "
-            << status.ToString();
-    }
+    LOG_EVERY_N(WARNING, 100)
+        << "UB endpoint retirement after local device failure is pending: "
+        << status.ToString();
 }
 
 void UbWorkers::handleCompletion(const Completion& completion) {
@@ -998,27 +1081,25 @@ void UbWorkers::scanTimeouts() {
             continue;
         }
         forgetEndpointDrain(inflight->endpoint);
-        // A successful native fence proves that this WR can no longer touch
-        // memory even when the provider did not return a matching completion.
-        // Reclaim the authoritative token and its quota before scheduling the
-        // retry. A completion racing after the erase is safely ignored as an
-        // unknown token; releaseInflight() is idempotent when the completion
-        // won the race instead.
-        bool reclaimed = false;
+        if (endpoint_retirer_) endpoint_retirer_(inflight->endpoint);
+        recordTimeoutOnce(inflight, now);
+        // quiesce() is the proof that retry cannot overlap old DMA. Reclaim a
+        // provider-lost token here: the successful fence proves the old WR can
+        // no longer touch memory, so releasing outstanding/quota accounting is
+        // safe. releaseInflight() is idempotent against a racing completion.
+        bool erased = false;
         {
             std::lock_guard<std::mutex> lock(inflight_mutex_);
             auto it = inflight_.find(inflight->completion_token);
             if (it != inflight_.end() && it->second == inflight) {
                 inflight_.erase(it);
-                reclaimed = true;
+                erased = true;
             }
         }
-        if (reclaimed) {
+        if (erased) {
             inflight_cv_.notify_all();
             releaseInflight(inflight);
         }
-        if (endpoint_retirer_) endpoint_retirer_(inflight->endpoint);
-        recordTimeoutOnce(inflight, now);
         resolveInflight(inflight, TIMEOUT, 0, true);
     }
 }
diff --git a/mooncake-transfer-engine/tent/src/transport/xpu/CMakeLists.txt b/mooncake-transfer-engine/tent/src/transport/xpu/CMakeLists.txt
new file mode 100644
index 0000000000..8221973d19
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/xpu/CMakeLists.txt
@@ -0,0 +1,8 @@
+if(USE_XPU)
+  add_library(tent_xport_xpu STATIC xpu_transport.cpp)
+  # XpuTransport binds to the concrete XpuPlatform (as NVLinkTransport binds to
+  # CudaPlatform) and drives USM classification and the VRAM<->host copy through
+  # it, so it links platform_xpu. The SYCL dependency stays confined to
+  # platform_xpu.
+  target_link_libraries(tent_xport_xpu PUBLIC tent_rpc tent_common platform_xpu)
+endif()
diff --git a/mooncake-transfer-engine/tent/src/transport/xpu/xpu_transport.cpp b/mooncake-transfer-engine/tent/src/transport/xpu/xpu_transport.cpp
new file mode 100644
index 0000000000..9704524772
--- /dev/null
+++ b/mooncake-transfer-engine/tent/src/transport/xpu/xpu_transport.cpp
@@ -0,0 +1,220 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include "tent/transport/xpu/xpu_transport.h"
+
+#include <glog/logging.h>
+
+#include <algorithm>
+
+#include "tent/common/status.h"
+#include "tent/runtime/platform.h"
+#include "tent/runtime/slab.h"
+
+namespace mooncake {
+namespace tent {
+
+XpuTransport::XpuTransport() : installed_(false), platform_(nullptr) {}
+
+XpuTransport::~XpuTransport() { uninstall(); }
+
+Status XpuTransport::install(std::string &local_segment_name,
+                             std::shared_ptr<ControlService> metadata,
+                             std::shared_ptr<Topology> local_topology,
+                             std::shared_ptr<Config> conf) {
+    if (installed_) {
+        return Status::InvalidArgument(
+            "XPU transport has been installed" LOC_MARK);
+    }
+    // Bind to the concrete XpuPlatform (as NVLinkTransport binds to
+    // CudaPlatform); every device operation is driven through it.
+    platform_ = dynamic_cast<XpuPlatform *>(&Platform::getLoader());
+    if (!platform_) {
+        return Status::InvalidArgument(
+            "XPU transport requires the XpuPlatform to be active" LOC_MARK);
+    }
+    metadata_ = metadata;
+    local_segment_name_ = local_segment_name;
+    local_topology_ = local_topology;
+    conf_ = conf;
+    installed_ = true;
+    // XPU VRAM is not NIC-addressable in the MVP: only the device<->host
+    // staging hop is supported here. gpu_to_gpu stays false so the engine
+    // always stages cross-node traffic through host DRAM (direct VRAM RDMA and
+    // PCIe P2P land in later PRs, as NVLinkTransport already exposes them).
+    caps.gpu_to_dram = true;
+    caps.dram_to_gpu = true;
+    return Status::OK();
+}
+
+Status XpuTransport::uninstall() {
+    if (installed_) {
+        metadata_.reset();
+        platform_ = nullptr;
+        installed_ = false;
+    }
+    return Status::OK();
+}
+
+Status XpuTransport::allocateSubBatch(SubBatchRef &batch, size_t max_size) {
+    auto xpu_batch = Slab<XpuSubBatch>::Get().allocate();
+    if (!xpu_batch)
+        return Status::InternalError(
+            "Unable to allocate XPU sub-batch" LOC_MARK);
+    batch = xpu_batch;
+    xpu_batch->task_list.reserve(max_size);
+    xpu_batch->max_size = max_size;
+    return Status::OK();
+}
+
+Status XpuTransport::freeSubBatch(SubBatchRef &batch) {
+    auto xpu_batch = dynamic_cast<XpuSubBatch *>(batch);
+    if (!xpu_batch)
+        return Status::InvalidArgument("Invalid XPU sub-batch" LOC_MARK);
+    Slab<XpuSubBatch>::Get().deallocate(xpu_batch);
+    batch = nullptr;
+    return Status::OK();
+}
+
+Status XpuTransport::submitTransferTasks(
+    SubBatchRef batch, const std::vector<Request> &request_list) {
+    auto xpu_batch = dynamic_cast<XpuSubBatch *>(batch);
+    if (!xpu_batch)
+        return Status::InvalidArgument("Invalid XPU sub-batch" LOC_MARK);
+    if (request_list.size() + xpu_batch->task_list.size() > xpu_batch->max_size)
+        return Status::TooManyRequests("Exceed batch capacity" LOC_MARK);
+    for (auto &request : request_list) {
+        // emplace_back default-constructs in place: XpuTask holds std::atomic
+        // members and is therefore non-movable, and the reserved capacity in
+        // allocateSubBatch guarantees no reallocation.
+        auto &task = xpu_batch->task_list.emplace_back();
+        task.request = request;
+        task.status_word = TransferStatusEnum::PENDING;
+        task.transferred_bytes = 0;
+        startTransfer(&task, xpu_batch);
+    }
+    return Status::OK();
+}
+
+void XpuTransport::startTransfer(XpuTask *task, XpuSubBatch *batch) {
+    // XpuTransport only handles the local device<->host staging hop, so the
+    // target is always the local staging buffer (LOCAL_SEGMENT_ID). Anything
+    // else indicates a routing bug: XPU VRAM cannot be a remote transfer peer.
+    if (task->request.target_id != LOCAL_SEGMENT_ID) {
+        LOG(ERROR) << "XpuTransport: unexpected non-local target "
+                   << task->request.target_id
+                   << "; XPU only supports local staging copies";
+        task->status_word = TransferStatusEnum::FAILED;
+        task->transferred_bytes = 0;
+        batch->notifyProgress();
+        return;
+    }
+
+    void *staging = reinterpret_cast<void *>(task->request.target_offset);
+
+    // Exactly one side of a staging hop is XPU VRAM: the local stage copies
+    // VRAM<->host staging buffer, and a delegated remote stage copies the
+    // peer's host staging buffer<->its VRAM (so `staging` is the device side
+    // there). Classify through the bound XpuPlatform, which resolves both base
+    // and interior USM pointers via its backend registry, so a device pointer
+    // handed to us as `base + chunk_offset` is still recognised. If neither (or
+    // both) side is device memory the request is malformed; fail loudly rather
+    // than let a plain host memcpy corrupt the transfer.
+    const bool source_is_device =
+        platform_->getMemoryType(task->request.source) == MTYPE_XPU;
+    const bool staging_is_device =
+        platform_->getMemoryType(staging) == MTYPE_XPU;
+    if (source_is_device == staging_is_device) {
+        LOG(ERROR) << "XpuTransport: a staging copy must have exactly one XPU "
+                      "device side, but source="
+                   << task->request.source << " (device=" << source_is_device
+                   << ") and target=" << staging
+                   << " (device=" << staging_is_device
+                   << "). This indicates a routing bug or an unclassified "
+                      "external USM pointer.";
+        task->status_word = TransferStatusEnum::FAILED;
+        task->transferred_bytes = 0;
+        batch->notifyProgress();
+        return;
+    }
+
+    // Which side is the device depends on the stage (see above), so the
+    // direction is expressed as dataflow: READ pulls `staging` into `source`,
+    // WRITE pushes `source` into `staging`. platform_->copy() derives H2D/D2H
+    // from the pointer classification.
+    Status status;
+    if (task->request.opcode == Request::READ)
+        // staging -> source
+        status = platform_->copy(task->request.source, staging,
+                                 task->request.length);
+    else
+        // source -> staging
+        status = platform_->copy(staging, task->request.source,
+                                 task->request.length);
+
+    if (status.ok()) {
+        task->transferred_bytes = task->request.length;
+        task->status_word = TransferStatusEnum::COMPLETED;
+    } else {
+        LOG(WARNING) << "XpuTransport: staging copy failed: "
+                     << status.ToString();
+        task->status_word = TransferStatusEnum::FAILED;
+    }
+    batch->notifyProgress();
+}
+
+Status XpuTransport::getTransferStatus(SubBatchRef batch, int task_id,
+                                       TransferStatus &status) {
+    auto xpu_batch = dynamic_cast<XpuSubBatch *>(batch);
+    if (!xpu_batch)
+        return Status::InvalidArgument("Invalid XPU sub-batch" LOC_MARK);
+    if (task_id < 0 || task_id >= (int)xpu_batch->task_list.size()) {
+        return Status::InvalidArgument("Invalid task id" LOC_MARK);
+    }
+    auto &task = xpu_batch->task_list[task_id];
+    status =
+        TransferStatus{task.status_word.load(), task.transferred_bytes.load()};
+    return Status::OK();
+}
+
+Status XpuTransport::addMemoryBuffer(BufferDesc &desc,
+                                     const MemoryOptions &options) {
+    LocationParser location(desc.location);
+    // Tag both XPU device buffers and host staging buffers so the staging
+    // policy can route the local VRAM<->host hop through this transport.
+    // Routing keys on the target (host) buffer's transports, so the host buffer
+    // must carry TransportType::XPU as well (mirrors NVLinkTransport).
+    if (location.type() != "xpu" && location.type() != "cpu" &&
+        location.type() != kWildcardLocation) {
+        return Status::OK();  // Not our buffer; leave it untagged.
+    }
+    // Idempotent: a buffer may be re-registered, so avoid duplicate XPU tags.
+    if (std::find(desc.transports.begin(), desc.transports.end(),
+                  TransportType::XPU) == desc.transports.end()) {
+        desc.transports.push_back(TransportType::XPU);
+    }
+    return Status::OK();
+}
+
+Status XpuTransport::removeMemoryBuffer(BufferDesc &desc) {
+    // Keep buffer metadata consistent with addMemoryBuffer by dropping the tag.
+    desc.transports.erase(
+        std::remove(desc.transports.begin(), desc.transports.end(),
+                    TransportType::XPU),
+        desc.transports.end());
+    return Status::OK();
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/CMakeLists.txt b/mooncake-transfer-engine/tent/tests/CMakeLists.txt
index 6db4b9b116..ad8b84d464 100644
--- a/mooncake-transfer-engine/tent/tests/CMakeLists.txt
+++ b/mooncake-transfer-engine/tent/tests/CMakeLists.txt
@@ -1,4 +1,6 @@
-# TENT Tests and Examples
+# TENT Tests and Examples tent_metrics_example and deadline_promotion_bench are
+# not add_test targets. tent/benchmark/hip_bandwidth_bench.cpp is a standalone
+# hipcc program.
 
 # TENT Metrics Example
 add_executable(tent_metrics_example tent_metrics_example.cpp)
@@ -7,25 +9,37 @@ add_executable(tent_metrics_example tent_metrics_example.cpp)
 # links against the shared asio implementation directly. Libraries
 # (tent_metrics, tent_interface) get it transitively; executables need it
 # explicit.
-target_link_libraries(tent_metrics_example PRIVATE tent_metrics tent_common
-                                                   asio_shared glog ibverbs)
+target_link_libraries(
+  tent_metrics_example PRIVATE tent_metrics tent_common asio_shared glog::glog
+                               ibverbs)
 target_include_directories(tent_metrics_example
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 
 # TENT Metrics Config Loader Unit Test
 add_executable(metrics_config_loader_test metrics_config_loader_test.cpp)
-target_link_libraries(metrics_config_loader_test
-                      PRIVATE tent_metrics tent_common gtest gtest_main glog)
+target_link_libraries(
+  metrics_config_loader_test PRIVATE tent_metrics tent_common gtest gtest_main
+                                     glog::glog)
 target_include_directories(metrics_config_loader_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME metrics_config_loader_test COMMAND metrics_config_loader_test)
 
+# TENT configuration lifecycle foundation test. This target deliberately links
+# only tent_common so it remains independent of transport hardware and runtime
+# services.
+add_executable(config_lifecycle_test config_lifecycle_test.cpp)
+target_link_libraries(config_lifecycle_test PRIVATE tent_common gtest
+                                                    gtest_main)
+target_include_directories(config_lifecycle_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME config_lifecycle_test COMMAND config_lifecycle_test)
+
 # TENT Metrics HTTP server test: validates that initialize() detects a busy
 # metrics port and degrades to log-only metrics instead of falsely reporting a
 # listening endpoint.
 add_executable(tent_metrics_http_server_test metrics_http_server_test.cpp)
 target_link_libraries(tent_metrics_http_server_test
-                      PRIVATE tent_metrics tent_common gtest gtest_main glog)
+                      PRIVATE tent_metrics tent_common gtest gtest_main)
 if(TARGET asio_shared)
   target_link_libraries(tent_metrics_http_server_test PRIVATE asio_shared)
 endif()
@@ -40,8 +54,8 @@ add_test(NAME tent_metrics_http_server_test
 # bucket invariants. Compiles to a stub test when metrics are disabled at
 # compile time.
 add_executable(tent_metrics_recording_test metrics_recording_test.cpp)
-target_link_libraries(tent_metrics_recording_test PRIVATE gtest gtest_main
-                                                          tent_link_group glog)
+target_link_libraries(tent_metrics_recording_test
+                      PRIVATE gtest gtest_main tent_link_group glog::glog)
 if(TARGET asio_shared)
   target_link_libraries(tent_metrics_recording_test PRIVATE asio_shared)
 endif()
@@ -84,6 +98,13 @@ target_include_directories(promotion_policy_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME promotion_policy_test COMMAND promotion_policy_test)
 
+add_executable(bounded_mpsc_queue_test bounded_mpsc_queue_test.cpp)
+target_link_libraries(bounded_mpsc_queue_test PRIVATE tent_common gtest
+                                                      gtest_main)
+target_include_directories(bounded_mpsc_queue_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME bounded_mpsc_queue_test COMMAND bounded_mpsc_queue_test)
+
 add_executable(rdma_cancel_test rdma_cancel_test.cpp ../src/runtime/slab.cpp)
 target_link_libraries(rdma_cancel_test PRIVATE tent_common gtest gtest_main)
 target_include_directories(rdma_cancel_test
@@ -108,6 +129,20 @@ target_include_directories(tent_ip_utils_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_ip_utils_test COMMAND tent_ip_utils_test)
 
+# RedisMetaStore thread-safety test: drives the real get()/set()/remove() code
+# paths against a fake command runner (no live Redis), asserting that
+# client_mutex_ serializes concurrent access and that get() preserves binary
+# values with embedded NULs. Only built when hiredis is available.
+if(TARGET metastore_redis)
+  add_executable(tent_redis_metastore_test redis_metastore_test.cpp)
+  target_link_libraries(
+    tent_redis_metastore_test PRIVATE metastore_redis tent_common gtest
+                                      gtest_main glog)
+  target_include_directories(tent_redis_metastore_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(NAME tent_redis_metastore_test COMMAND tent_redis_metastore_test)
+endif()
+
 add_executable(tent_qp_pool_layout_test qp_pool_layout_test.cpp)
 target_link_libraries(tent_qp_pool_layout_test PRIVATE tent_common gtest
                                                        gtest_main)
@@ -115,6 +150,13 @@ target_include_directories(tent_qp_pool_layout_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_qp_pool_layout_test COMMAND tent_qp_pool_layout_test)
 
+add_executable(tent_ticket_lock_test ticket_lock_test.cpp)
+target_link_libraries(tent_ticket_lock_test PRIVATE tent_common gtest
+                                                    gtest_main)
+target_include_directories(tent_ticket_lock_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_ticket_lock_test COMMAND tent_ticket_lock_test)
+
 add_executable(tent_coalesce_regions_test coalesce_regions_test.cpp)
 target_link_libraries(tent_coalesce_regions_test PRIVATE tent_common gtest
                                                          gtest_main)
@@ -139,6 +181,24 @@ target_include_directories(request_merge_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME request_merge_test COMMAND request_merge_test)
 
+add_executable(local_notification_test local_notification_test.cpp)
+target_link_libraries(local_notification_test PRIVATE gtest gtest_main
+                                                      tent_link_group)
+target_include_directories(local_notification_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME local_notification_test COMMAND local_notification_test)
+
+# Notification fallback: an unavailable RDMA notification channel falls back
+# to the next transport and then to the control-plane RPC, and receive drains
+# every transport. Loopback only, no NIC required.
+add_executable(tent_notification_fallback_test notification_fallback_test.cpp)
+target_link_libraries(tent_notification_fallback_test
+                      PRIVATE gtest gtest_main tent_link_group)
+target_include_directories(tent_notification_fallback_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_notification_fallback_test
+         COMMAND tent_notification_fallback_test)
+
 add_executable(transfer_engine_config_override_test
                transfer_engine_config_override_test.cpp)
 target_link_libraries(transfer_engine_config_override_test
@@ -159,6 +219,94 @@ target_include_directories(tent_tcp_transport_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_tcp_transport_test COMMAND tent_tcp_transport_test)
 
+add_executable(tent_tcp_regression_test tcp_regression_test.cpp)
+target_link_libraries(tent_tcp_regression_test PRIVATE gtest gtest_main
+                                                       tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_tcp_regression_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_tcp_regression_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_tcp_regression_test COMMAND tent_tcp_regression_test)
+
+add_executable(tent_hp_tcp_transport_config_test
+               hp_tcp_transport_config_test.cpp)
+target_link_libraries(tent_hp_tcp_transport_config_test
+                      PRIVATE gtest gtest_main tent_link_group)
+target_include_directories(tent_hp_tcp_transport_config_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_transport_config_test
+         COMMAND tent_hp_tcp_transport_config_test)
+
+add_executable(tent_hp_tcp_workers_test hp_tcp_workers_test.cpp)
+target_link_libraries(tent_hp_tcp_workers_test PRIVATE gtest gtest_main
+                                                       tent_xport_hp_tcp_core)
+target_include_directories(tent_hp_tcp_workers_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_workers_test COMMAND tent_hp_tcp_workers_test)
+
+add_executable(tent_hp_tcp_protocol_test hp_tcp_protocol_test.cpp)
+target_link_libraries(tent_hp_tcp_protocol_test PRIVATE gtest gtest_main
+                                                        tent_xport_hp_tcp_core)
+target_include_directories(tent_hp_tcp_protocol_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_protocol_test COMMAND tent_hp_tcp_protocol_test)
+
+add_executable(tent_hp_tcp_buffer_registry_test hp_tcp_buffer_registry_test.cpp)
+target_link_libraries(tent_hp_tcp_buffer_registry_test
+                      PRIVATE gtest gtest_main tent_xport_hp_tcp_core)
+target_include_directories(tent_hp_tcp_buffer_registry_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_buffer_registry_test
+         COMMAND tent_hp_tcp_buffer_registry_test)
+
+add_executable(tent_hp_tcp_socket_test hp_tcp_socket_test.cpp)
+target_link_libraries(tent_hp_tcp_socket_test PRIVATE gtest gtest_main
+                                                      tent_xport_hp_tcp_core)
+target_include_directories(tent_hp_tcp_socket_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_socket_test COMMAND tent_hp_tcp_socket_test)
+
+add_executable(tent_hp_tcp_transport_test hp_tcp_transport_test.cpp)
+target_link_libraries(tent_hp_tcp_transport_test PRIVATE gtest gtest_main
+                                                         tent_link_group)
+target_include_directories(tent_hp_tcp_transport_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_hp_tcp_transport_test COMMAND tent_hp_tcp_transport_test)
+
+add_executable(tent_hp_tcp_e2e_test hp_tcp_e2e_test.cpp)
+target_link_libraries(tent_hp_tcp_e2e_test PRIVATE gtest gtest_main
+                                                   tent_link_group)
+target_include_directories(tent_hp_tcp_e2e_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+# Each fork-based case starts before earlier cases can create runtime threads.
+foreach(case WriteThenReadConcurrency16 WriteThenReadAcrossTwoRails
+             UnevenSlicedReadAcrossProcesses)
+  add_test(NAME tent_hp_tcp_e2e_${case}
+           COMMAND tent_hp_tcp_e2e_test
+                   --gtest_filter=HighPerformanceTcpE2eTest.${case})
+  set_tests_properties(tent_hp_tcp_e2e_${case} PROPERTIES TIMEOUT 120)
+endforeach()
+
+add_executable(tent_tcp_datapath_roundtrip_test tcp_datapath_roundtrip_test.cpp)
+target_link_libraries(tent_tcp_datapath_roundtrip_test PRIVATE gtest gtest_main
+                                                               tent_link_group)
+target_include_directories(tent_tcp_datapath_roundtrip_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+# Each case runs in its own process: the test forks a server child, which must
+# happen before the client process initializes any engine state. The CUDA case
+# is built into the same binary but run manually on a GPU host.
+add_test(
+  NAME tent_tcp_datapath_roundtrip_test_single_threaded
+  COMMAND tent_tcp_datapath_roundtrip_test
+          --gtest_filter=TcpDataPathRoundtripTest.WriteThenReadAcrossProcesses)
+add_test(
+  NAME tent_tcp_datapath_roundtrip_test_multi_threaded_rpc
+  COMMAND
+    tent_tcp_datapath_roundtrip_test
+    --gtest_filter=TcpDataPathRoundtripTest.WriteThenReadAcrossProcessesMultiThreadedRpc
+)
+
 add_executable(tent_shm_transport_test shm_transport_test.cpp)
 target_link_libraries(tent_shm_transport_test PRIVATE gtest gtest_main
                                                       tent_link_group)
@@ -166,12 +314,44 @@ target_include_directories(tent_shm_transport_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_shm_transport_test COMMAND tent_shm_transport_test)
 
-add_executable(tent_failover_test failover_test.cpp)
-target_link_libraries(tent_failover_test PRIVATE gtest gtest_main
-                                                 tent_link_group)
-target_include_directories(tent_failover_test
-                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
-add_test(NAME tent_failover_test COMMAND tent_failover_test)
+# io_uring submission-contract tests (two-phase all-or-nothing submit,
+# short-submit handling). No special hardware needed; only built when liburing
+# was found, and skipped at runtime where the kernel blocks io_uring (e.g.
+# restrictive seccomp profiles). Each case runs in its own process: the
+# transport's thread-local file context cache is keyed by segment ID only, so
+# consecutive transports in one process (each backed by its own temp file) would
+# reuse the first test's file context.
+if(TARGET tent_xport_uring)
+  add_executable(tent_io_uring_transport_test io_uring_transport_test.cpp)
+  target_link_libraries(tent_io_uring_transport_test PRIVATE gtest gtest_main
+                                                             tent_link_group)
+  target_include_directories(tent_io_uring_transport_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(
+    NAME tent_io_uring_transport_test_short_submit
+    COMMAND
+      tent_io_uring_transport_test
+      --gtest_filter=IOUringTransportTest.ShortSubmitIsNotAnErrorAndExecutesExactlyOnce
+  )
+  add_test(
+    NAME tent_io_uring_transport_test_all_or_nothing
+    COMMAND
+      tent_io_uring_transport_test
+      --gtest_filter=IOUringTransportTest.SubmitIsAllOrNothingWhenSegmentLookupFailsMidBatch
+  )
+endif()
+
+# NOT registered via add_test: the test needs a real GPU (it opens a CUDA IPC
+# handle exported by a forked child). Run manually on a GPU box:
+# ./tent_nvlink_transport_test --gtest_filter='NVLinkTransportTest.*' Only built
+# when CUDA is enabled: the test includes CUDA headers directly.
+if(USE_CUDA)
+  add_executable(tent_nvlink_transport_test nvlink_transport_test.cpp)
+  target_link_libraries(tent_nvlink_transport_test PRIVATE gtest gtest_main
+                                                           tent_link_group)
+  target_include_directories(tent_nvlink_transport_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+endif()
 
 add_executable(tent_endpoint_lifecycle_test endpoint_lifecycle_test.cpp)
 target_link_libraries(tent_endpoint_lifecycle_test PRIVATE gtest gtest_main
@@ -180,6 +360,13 @@ target_include_directories(tent_endpoint_lifecycle_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_endpoint_lifecycle_test COMMAND tent_endpoint_lifecycle_test)
 
+add_executable(tent_bootstrap_response_test bootstrap_response_test.cpp)
+target_link_libraries(tent_bootstrap_response_test PRIVATE gtest gtest_main
+                                                           tent_link_group)
+target_include_directories(tent_bootstrap_response_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_bootstrap_response_test COMMAND tent_bootstrap_response_test)
+
 add_executable(tent_endpoint_store_test endpoint_store_test.cpp)
 target_link_libraries(tent_endpoint_store_test PRIVATE gtest gtest_main
                                                        tent_link_group)
@@ -187,6 +374,13 @@ target_include_directories(tent_endpoint_store_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_endpoint_store_test COMMAND tent_endpoint_store_test)
 
+add_executable(tent_device_selector_test device_selector_test.cpp)
+target_link_libraries(tent_device_selector_test PRIVATE gtest gtest_main
+                                                        tent_link_group)
+target_include_directories(tent_device_selector_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_device_selector_test COMMAND tent_device_selector_test)
+
 add_executable(tent_rdma_transport_test rdma_transport_test.cpp)
 target_link_libraries(tent_rdma_transport_test PRIVATE gtest gtest_main
                                                        tent_link_group ibverbs)
@@ -194,6 +388,25 @@ target_include_directories(tent_rdma_transport_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_rdma_transport_test COMMAND tent_rdma_transport_test)
 
+# Regression test for the edge-triggered async event fd: one epoll wakeup must
+# drain the whole queue. Wraps ibv_get_async_event to script the event source,
+# so it needs no RDMA device. -Wl,--wrap is a GNU ld / lld feature that Apple's
+# linker lacks, and the test is meaningless without it, so skip the target there
+# rather than build one that calls the real symbols.
+if(UNIX AND NOT APPLE)
+  add_executable(tent_rdma_async_event_drain_test
+                 rdma_async_event_drain_test.cpp)
+  target_link_libraries(tent_rdma_async_event_drain_test
+                        PRIVATE gtest gtest_main tent_link_group ibverbs)
+  target_include_directories(tent_rdma_async_event_drain_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  target_link_options(
+    tent_rdma_async_event_drain_test PRIVATE "-Wl,--wrap=ibv_get_async_event"
+    "-Wl,--wrap=ibv_ack_async_event")
+  add_test(NAME tent_rdma_async_event_drain_test
+           COMMAND tent_rdma_async_event_drain_test)
+endif()
+
 if(USE_HIP)
   find_package(HIP REQUIRED)
   add_executable(tent_rocm_platform_test rocm_platform_test.cpp)
@@ -204,6 +417,19 @@ if(USE_HIP)
   add_test(NAME tent_rocm_platform_test COMMAND tent_rocm_platform_test)
 endif()
 
+if(TARGET tent_xport_gds)
+  add_executable(tent_gds_transport_status_test gds_transport_status_test.cpp)
+  target_link_libraries(tent_gds_transport_status_test PRIVATE gtest gtest_main
+                                                               tent_link_group)
+  target_link_options(
+    tent_gds_transport_status_test PRIVATE "-Wl,--wrap=cuFileDriverOpen"
+    "-Wl,--wrap=cuFileBatchIOGetStatus" "-Wl,--wrap=cuFileBatchIOCancel")
+  target_include_directories(tent_gds_transport_status_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(NAME tent_gds_transport_status_test
+           COMMAND tent_gds_transport_status_test)
+endif()
+
 if(USE_SUNRISE)
   add_executable(tent_sunrise_link_transport_test
                  sunrise_link_transport_test.cpp)
@@ -216,6 +442,31 @@ if(USE_SUNRISE)
   add_test(NAME tent_sunrise_link_transport_test
            COMMAND tent_sunrise_link_transport_test)
 endif()
+
+if(USE_MPCOMM)
+  add_executable(tent_mpcomm_transport_test mpcomm_transport_test.cpp)
+  target_link_libraries(tent_mpcomm_transport_test PRIVATE gtest gtest_main
+                                                           tent_link_group)
+  target_include_directories(
+    tent_mpcomm_transport_test
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include
+            ${CMAKE_CURRENT_SOURCE_DIR}/../../include)
+  add_test(NAME tent_mpcomm_transport_test COMMAND tent_mpcomm_transport_test)
+endif()
+
+# Boundary tests of the TENT side of the mpcomm transport, driven through an
+# injected MpcommAdapter. Built unconditionally: nothing here includes mpcomm.h
+# and nothing needs an RDMA device, so these run wherever the rest of the suite
+# runs. The hardware data path stays in tent_mpcomm_transport_test above, which
+# skips itself when no device is present.
+add_executable(tent_mpcomm_boundary_test mpcomm_boundary_test.cpp)
+target_link_libraries(tent_mpcomm_boundary_test PRIVATE gtest gtest_main
+                                                        tent_link_group)
+target_include_directories(
+  tent_mpcomm_boundary_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include
+                                    ${CMAKE_CURRENT_SOURCE_DIR}/../../include)
+add_test(NAME tent_mpcomm_boundary_test COMMAND tent_mpcomm_boundary_test)
+
 add_executable(tent_fault_proxy_test fault_proxy_test.cpp)
 target_link_libraries(tent_fault_proxy_test PRIVATE gtest gtest_main
                                                     tent_link_group)
@@ -230,6 +481,15 @@ target_include_directories(tent_rail_monitor_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_rail_monitor_test COMMAND tent_rail_monitor_test)
 
+# DeviceSelector inflight quota accounting: per-slice charge/release balance,
+# chargeDevice, baseline no-underflow, EWMA gating, charge-failure.
+add_executable(tent_quota_accounting_test quota_accounting_test.cpp)
+target_link_libraries(tent_quota_accounting_test PRIVATE gtest gtest_main
+                                                         tent_link_group)
+target_include_directories(tent_quota_accounting_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_quota_accounting_test COMMAND tent_quota_accounting_test)
+
 # QoS Contract Schema Unit Test
 add_executable(tent_qos_contract_test qos_contract_test.cpp
                                       ../src/runtime/qos_contract.cpp)
@@ -246,6 +506,22 @@ target_include_directories(tent_transport_selector_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_transport_selector_test COMMAND tent_transport_selector_test)
 
+add_executable(tent_topology_priority_matrix_test
+               topology_priority_matrix_test.cpp)
+target_link_libraries(tent_topology_priority_matrix_test
+                      PRIVATE gtest gtest_main tent_link_group)
+target_include_directories(tent_topology_priority_matrix_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_topology_priority_matrix_test
+         COMMAND tent_topology_priority_matrix_test)
+
+add_executable(tent_strict_local_numa_test strict_local_numa_test.cpp)
+target_link_libraries(tent_strict_local_numa_test PRIVATE gtest gtest_main
+                                                          tent_link_group)
+target_include_directories(tent_strict_local_numa_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_strict_local_numa_test COMMAND tent_strict_local_numa_test)
+
 if(USE_UB)
   add_executable(
     tent_ub_core_test ub_core_test.cpp ../src/transport/ub/quota.cpp
@@ -300,13 +576,6 @@ target_include_directories(tent_transport_hint_test
                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
 add_test(NAME tent_transport_hint_test COMMAND tent_transport_hint_test)
 
-add_executable(tent_intent_type_test intent_type_test.cpp)
-target_link_libraries(tent_intent_type_test PRIVATE gtest gtest_main
-                                                    tent_common)
-target_include_directories(tent_intent_type_test
-                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
-add_test(NAME tent_intent_type_test COMMAND tent_intent_type_test)
-
 # ProgressWorker skeleton test: covers default-off behavior, event-driven
 # progress without poll-failover, and freeBatch races (issue #2116).
 add_executable(tent_progress_worker_test progress_worker_test.cpp)
@@ -315,10 +584,76 @@ target_link_libraries(tent_progress_worker_test PRIVATE gtest gtest_main
 if(TARGET asio_shared)
   target_link_libraries(tent_progress_worker_test PRIVATE asio_shared)
 endif()
-target_include_directories(tent_progress_worker_test
-                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+target_include_directories(
+  tent_progress_worker_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include
+                                    ${CMAKE_CURRENT_SOURCE_DIR}/../src/runtime)
 add_test(NAME tent_progress_worker_test COMMAND tent_progress_worker_test)
 
+# stage_buffers_ is reached from the staging workers and the RPC thread. Drives
+# a real ProxyManager concurrently; no RDMA device required.
+add_executable(tent_stage_buffer_concurrency_test
+               stage_buffer_concurrency_test.cpp)
+target_link_libraries(tent_stage_buffer_concurrency_test
+                      PRIVATE gtest gtest_main tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_stage_buffer_concurrency_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_stage_buffer_concurrency_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_stage_buffer_concurrency_test
+         COMMAND tent_stage_buffer_concurrency_test)
+
+# Regression test for PR #3526: a timed-out ProxyManager shutdown drain must
+# hand undrained batches and their stage buffers to the engine for deferred
+# teardown instead of freeing them. Pure CPU; no RDMA device required.
+add_executable(tent_proxy_shutdown_timeout_test proxy_shutdown_timeout_test.cpp)
+target_link_libraries(tent_proxy_shutdown_timeout_test PRIVATE gtest gtest_main
+                                                               tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_proxy_shutdown_timeout_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_proxy_shutdown_timeout_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_proxy_shutdown_timeout_test
+         COMMAND tent_proxy_shutdown_timeout_test)
+
+# Backoff policy for the synchronous wait loops. Pure function, no engine
+# required.
+add_executable(tent_poll_backoff_test poll_backoff_test.cpp)
+target_link_libraries(tent_poll_backoff_test PRIVATE gtest gtest_main
+                                                     tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_poll_backoff_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_poll_backoff_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_poll_backoff_test COMMAND tent_poll_backoff_test)
+
+# Delegate RPC end to end: ControlClient::delegate -> onDelegate ->
+# transferSync, against a real engine on loopback with a FakeTransport.
+add_executable(tent_delegate_rpc_test delegate_rpc_test.cpp)
+target_link_libraries(tent_delegate_rpc_test PRIVATE gtest gtest_main
+                                                     tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_delegate_rpc_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_delegate_rpc_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_delegate_rpc_test COMMAND tent_delegate_rpc_test)
+
+# A slow handler must not stall the single-io_context RPC server. Starts a real
+# CoroRpcAgent on loopback; no RDMA device required.
+add_executable(tent_rpc_handler_isolation_test rpc_handler_isolation_test.cpp)
+target_link_libraries(tent_rpc_handler_isolation_test PRIVATE gtest gtest_main
+                                                              tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_rpc_handler_isolation_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_rpc_handler_isolation_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_rpc_handler_isolation_test
+         COMMAND tent_rpc_handler_isolation_test)
+
 add_executable(tent_runtime_queue_dispatch_test runtime_queue_dispatch_test.cpp)
 target_link_libraries(tent_runtime_queue_dispatch_test PRIVATE gtest gtest_main
                                                                tent_link_group)
@@ -330,6 +665,17 @@ target_include_directories(tent_runtime_queue_dispatch_test
 add_test(NAME tent_runtime_queue_dispatch_test
          COMMAND tent_runtime_queue_dispatch_test)
 
+add_executable(tent_local_memory_lifecycle_test local_memory_lifecycle_test.cpp)
+target_link_libraries(tent_local_memory_lifecycle_test PRIVATE gtest gtest_main
+                                                               tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_local_memory_lifecycle_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_local_memory_lifecycle_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_local_memory_lifecycle_test
+         COMMAND tent_local_memory_lifecycle_test)
+
 # Causal chain stage decomposition: validates that dispatch_time and post_time
 # timestamps are populated on both queue and direct-commit paths.
 add_executable(causal_chain_test causal_chain_test.cpp)
@@ -378,3 +724,88 @@ if(USE_TPU)
     PRIVATE MOCK_TPU_PJRT_LIB="$<TARGET_FILE:mock_tpu_pjrt>")
   add_test(NAME tent_tpu_transport_test COMMAND tent_tpu_transport_test)
 endif()
+
+# XPU SYCL platform test: exercises XpuPlatform (device allocation, pointer
+# classification, VRAM<->host staging copy) against the real oneAPI SYCL
+# backend. USE_XPU is a direct-link build, so the test links libsycl (via
+# platform_xpu inside tent_link_group) and is compiled with -fsycl. It falls
+# back to the OpenCL CPU device when no Intel GPU is present, and skips itself
+# when no SYCL device is visible at all.
+if(USE_XPU)
+  add_executable(tent_xpu_platform_test xpu/xpu_platform_test.cpp)
+  target_link_libraries(tent_xpu_platform_test PRIVATE gtest gtest_main
+                                                       tent_link_group)
+  target_include_directories(tent_xpu_platform_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(NAME tent_xpu_platform_test COMMAND tent_xpu_platform_test)
+
+  # XPU staging transport test: drives XpuTransport's VRAM<->host staging hop
+  # through the active XpuPlatform (Platform::getLoader()). Like the platform
+  # test it links libsycl via tent_link_group and skips when no SYCL device is
+  # visible.
+  add_executable(tent_xpu_transport_test xpu/xpu_transport_test.cpp)
+  target_link_libraries(tent_xpu_transport_test PRIVATE gtest gtest_main
+                                                        tent_link_group)
+  target_include_directories(tent_xpu_transport_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(NAME tent_xpu_transport_test COMMAND tent_xpu_transport_test)
+
+  add_executable(tent_xpu_engine_test xpu/xpu_engine_test.cpp)
+  target_link_libraries(tent_xpu_engine_test PRIVATE gtest gtest_main
+                                                     tent_link_group)
+  target_include_directories(tent_xpu_engine_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  add_test(NAME tent_xpu_engine_test COMMAND tent_xpu_engine_test)
+  set_tests_properties(tent_xpu_engine_test PROPERTIES TIMEOUT 300)
+endif()
+
+# NOT registered via add_test: the test needs a real CUDA device (it exports a
+# real CUDA IPC handle), so it must be run manually on a GPU host. Only built
+# when CUDA is enabled: the test includes CUDA headers directly.
+if(USE_CUDA)
+  add_executable(tent_nvlink_ipc_handle_sharing_test
+                 nvlink_ipc_handle_sharing_test.cpp)
+  target_link_libraries(tent_nvlink_ipc_handle_sharing_test
+                        PRIVATE gtest gtest_main tent_link_group)
+  target_include_directories(tent_nvlink_ipc_handle_sharing_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+endif()
+
+# A peer restart invalidates every connection pooled for it; one failed call
+# must flush the whole pool. Loopback only, no NIC required.
+add_executable(tent_rpc_reconnect_test rpc_reconnect_test.cpp)
+target_link_libraries(tent_rpc_reconnect_test PRIVATE gtest gtest_main
+                                                      tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_rpc_reconnect_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_rpc_reconnect_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_rpc_reconnect_test COMMAND tent_rpc_reconnect_test)
+
+if(USE_ASCEND OR USE_ASCEND_DIRECT)
+  add_executable(tent_ascend_direct_transport_test
+                 ascend_direct_transport_test.cpp)
+  target_link_libraries(tent_ascend_direct_transport_test
+                        PRIVATE gtest gtest_main tent_link_group)
+  if(TARGET asio_shared)
+    target_link_libraries(tent_ascend_direct_transport_test PRIVATE asio_shared)
+  endif()
+  target_include_directories(tent_ascend_direct_transport_test
+                             PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+  set_target_properties(tent_ascend_direct_transport_test
+                        PROPERTIES LINK_FLAGS "-Wl,--allow-shlib-undefined")
+  add_test(NAME tent_ascend_direct_transport_test
+           COMMAND tent_ascend_direct_transport_test)
+endif()
+
+add_executable(tent_segment_desc_retry_test segment_desc_retry_test.cpp)
+target_link_libraries(tent_segment_desc_retry_test PRIVATE gtest gtest_main
+                                                           tent_link_group)
+if(TARGET asio_shared)
+  target_link_libraries(tent_segment_desc_retry_test PRIVATE asio_shared)
+endif()
+target_include_directories(tent_segment_desc_retry_test
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+add_test(NAME tent_segment_desc_retry_test COMMAND tent_segment_desc_retry_test)
+set_tests_properties(tent_segment_desc_retry_test PROPERTIES TIMEOUT 60)
diff --git a/mooncake-transfer-engine/tent/tests/admission_queue_test.cpp b/mooncake-transfer-engine/tent/tests/admission_queue_test.cpp
index 2cae89c5d0..ab404fff3c 100644
--- a/mooncake-transfer-engine/tent/tests/admission_queue_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/admission_queue_test.cpp
@@ -595,6 +595,239 @@ TEST(AdmissionQueueTest, Step3DropsInfeasibleAndKeepsFeasible) {
     EXPECT_EQ(queue.outstandingBytes(), 16u);
 }
 
+// The deadline is absolute, so an owner dispatched now still has to wait
+// behind everything already dispatched and not yet completed. That wait is
+// an additive delay charged from the queue's own dispatch accounting, not a
+// slower bandwidth.
+TEST(AdmissionQueueTest, Step3DropCountsBytesAlreadyDispatched) {
+    LocalTransferAdmissionQueue queue(step3Limits(1.0));
+    // now = 1e9 ns; bandwidth 1e9 B/s: 1 MB takes 1 ms.
+    queue.setDegradationPolicy([] { return 1e9; }, DegradationHooks{},
+                               [] { return uint64_t{1'000'000'000}; });
+
+    // owner 1: 1 MB, loose deadline; dispatched and still in flight.
+    std::vector<QueueOwnerId> ids;
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(1, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 1'000'000, 5'000'000'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    ASSERT_EQ(queue.pickForDispatch(4, 1 << 20), std::vector<QueueOwnerId>{1});
+
+    // owner 2: 16 B with a 500 us window. Alone it would take 16 ns
+    // (MLU ~3e-5); behind the 1 MB it completes at ~1 ms → MLU ~2 → drop.
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(2, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 16, 1'000'500'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    std::vector<QueueOwnerId> dropped;
+    EXPECT_TRUE(queue.pickForDispatch(4, 1 << 20, &dropped).empty());
+    EXPECT_EQ(dropped, std::vector<QueueOwnerId>{2});
+
+    // Once owner 1 completes nothing is ahead: the same request is feasible.
+    ASSERT_EQ(queue.complete(1, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(3, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 16, 1'000'500'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    dropped.clear();
+    EXPECT_EQ(queue.pickForDispatch(4, 1 << 20, &dropped),
+              std::vector<QueueOwnerId>{3});
+    EXPECT_TRUE(dropped.empty());
+}
+
+// Only provider-governed bytes wait ahead of an eligible owner: an owner on
+// another transport is neither counted when dispatched nor subtracted when
+// it completes.
+TEST(AdmissionQueueTest, Step3QueueAheadCountsOnlyProviderGovernedBytes) {
+    LocalTransferAdmissionQueue queue(step3Limits(1.0));
+    queue.setDegradationPolicy([] { return 1e9; }, DegradationHooks{},
+                               [] { return uint64_t{1'000'000'000}; });
+
+    // owner 1: 1 MB, not eligible (not governed by the provider); dispatched.
+    std::vector<QueueOwnerId> ids;
+    ASSERT_EQ(
+        queue
+            .tryAdmit(
+                makeSubmit(
+                    1, 1, {makeOwnerWithDeadline(0, 1'000'000, 5'000'000'000)}),
+                ids)
+            .code(),
+        Status::Code::kOk);
+    ASSERT_EQ(queue.pickForDispatch(4, 1 << 20), std::vector<QueueOwnerId>{1});
+
+    // owner 2: 16 B with a 500 us window, eligible. Nothing ahead of it is
+    // on the NIC, so it is feasible.
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(2, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 16, 1'000'500'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    std::vector<QueueOwnerId> dropped;
+    EXPECT_EQ(queue.pickForDispatch(4, 1 << 20, &dropped),
+              std::vector<QueueOwnerId>{2});
+    EXPECT_TRUE(dropped.empty());
+
+    // Completing the ungoverned owner must not disturb the count either:
+    // afterwards an eligible 1 MB owner still drops a tight owner behind it.
+    ASSERT_EQ(queue.complete(1, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);
+    ASSERT_EQ(queue.complete(2, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(3, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 1'000'000, 5'000'000'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    dropped.clear();
+    ASSERT_EQ(queue.pickForDispatch(4, 1 << 20, &dropped),
+              std::vector<QueueOwnerId>{3});
+    EXPECT_TRUE(dropped.empty());
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(4, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 16, 1'000'500'000)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    dropped.clear();
+    EXPECT_TRUE(queue.pickForDispatch(4, 1 << 20, &dropped).empty());
+    EXPECT_EQ(dropped, std::vector<QueueOwnerId>{4});
+}
+
+// Within one pick, `bytes_ahead` for a later owner is exactly the eligible
+// bytes picked before it: an ungoverned owner ahead adds nothing, and an
+// eligible one is counted once (dispatching_bytes_ already grows as owners
+// are picked).
+TEST(AdmissionQueueTest, Step3QueueAheadWithinOnePickIsExact) {
+    LocalTransferAdmissionQueue queue(step3Limits(1.0));
+    // now = 1e9 ns; bandwidth 1e9 B/s: 1 MB takes 1 ms.
+    queue.setDegradationPolicy([] { return 1e9; }, DegradationHooks{},
+                               [] { return uint64_t{1'000'000'000}; });
+
+    // EDF order: N (400 KB, not eligible, 560 us), A (400 KB, eligible,
+    // 600 us), B (16 B, eligible, 640 us); 400 KB takes 400 us.
+    //   A: nothing governed ahead -> 400 / 600 = 0.67 -> dispatch
+    //      (counting N: 800 / 600 = 1.33 -> drop)
+    //   B: A ahead -> ~400 / 640 = 0.63 -> dispatch
+    //      (counting A twice: 800 / 640 = 1.25 -> drop)
+    std::vector<QueueOwnerId> ids;
+    ASSERT_EQ(
+        queue
+            .tryAdmit(
+                makeSubmit(1, 3,
+                           {makeOwnerWithDeadline(0, 400'000, 1'000'560'000),
+                            makeDegradationEligibleOwnerWithDeadline(
+                                1, 400'000, 1'000'600'000),
+                            makeDegradationEligibleOwnerWithDeadline(
+                                2, 16, 1'000'640'000)}),
+                ids)
+            .code(),
+        Status::Code::kOk);
+    std::vector<QueueOwnerId> dropped;
+    const std::vector<QueueOwnerId> all{1, 2, 3};
+    EXPECT_EQ(queue.pickForDispatch(4, 1 << 20, &dropped), all);
+    EXPECT_TRUE(dropped.empty());
+}
+
+// dispatching_bytes_ is the drop prediction's queue-ahead term, so after
+// every owner state transition it must equal the bytes of the eligible
+// owners currently Dispatching: nothing more, nothing less.
+TEST(AdmissionQueueTest,
+     Step3DispatchingBytesEqualsEligibleBytesInDispatching) {
+    LocalTransferAdmissionQueue queue(step3Limits(1.0));
+    // now = 1e9 ns, bandwidth 1e9 B/s: 1 B per ns.
+    queue.setDegradationPolicy([] { return 1e9; }, DegradationHooks{},
+                               [] { return uint64_t{1'000'000'000}; });
+
+    // Distinct loose deadlines: EDF order == admission order, nothing drops.
+    // 1: eligible 1000 B; 2: not eligible 20000 B; 3: eligible 300 B;
+    // 4: eligible 40 B, stays queued.
+    std::vector<QueueOwnerId> ids;
+    ASSERT_EQ(queue
+                  .tryAdmit(makeSubmit(
+                                1, 4,
+                                {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 1000, 5'000'000'000),
+                                 makeOwnerWithDeadline(1, 20000, 6'000'000'000),
+                                 makeDegradationEligibleOwnerWithDeadline(
+                                     2, 300, 7'000'000'000),
+                                 makeDegradationEligibleOwnerWithDeadline(
+                                     3, 40, 8'000'000'000)}),
+                            ids)
+                  .code(),
+              Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 0u);  // admitted is not dispatching
+
+    // pick: eligible owners charge their length, the other charges nothing.
+    ASSERT_EQ(queue.pickForDispatch(3, 1 << 20),
+              (std::vector<QueueOwnerId>{1, 2, 3}));
+    EXPECT_EQ(queue.dispatchingBytes(), 1300u);
+
+    // Refused calls and a queued owner's cancel move nothing.
+    EXPECT_NE(queue.cancel(1).code(), Status::Code::kOk);  // dispatching
+    ASSERT_EQ(queue.cancel(4).code(), Status::Code::kOk);  // queued
+    ASSERT_EQ(queue.cancel(4).code(), Status::Code::kOk);  // idempotent
+    EXPECT_NE(queue.complete(4, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);  // not dispatching
+    EXPECT_EQ(queue.dispatchingBytes(), 1300u);
+
+    // complete: non-eligible returns nothing; eligible returns its length
+    // whatever the terminal status.
+    ASSERT_EQ(queue.complete(2, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 1300u);
+    ASSERT_EQ(queue.complete(1, TransferStatusEnum::FAILED).code(),
+              Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 300u);
+
+    // drop: 16 B, 10 ns window, 300 B ahead -> MLU 31.6. Queued -> Terminal
+    // without passing through Dispatching.
+    ASSERT_EQ(
+        queue
+            .tryAdmit(makeSubmit(2, 1,
+                                 {makeDegradationEligibleOwnerWithDeadline(
+                                     0, 16, 1'000'000'010)}),
+                      ids)
+            .code(),
+        Status::Code::kOk);
+    std::vector<QueueOwnerId> dropped;
+    EXPECT_TRUE(queue.pickForDispatch(4, 1 << 20, &dropped).empty());
+    EXPECT_EQ(dropped, std::vector<QueueOwnerId>{5});
+    EXPECT_EQ(queue.dispatchingBytes(), 300u);
+
+    // retireBatch: erasing terminal owners (batch 2) or being refused for a
+    // dispatching one (batch 1, owner 3) moves nothing.
+    ASSERT_EQ(queue.retireBatch(2).code(), Status::Code::kOk);
+    EXPECT_NE(queue.retireBatch(1).code(), Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 300u);
+
+    ASSERT_EQ(queue.complete(3, TransferStatusEnum::COMPLETED).code(),
+              Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 0u);
+    ASSERT_EQ(queue.retireBatch(1).code(), Status::Code::kOk);
+    EXPECT_EQ(queue.dispatchingBytes(), 0u);
+}
+
 TEST(AdmissionQueueTest, Step3DropsAlreadyExpiredDeadline) {
     LocalTransferAdmissionQueue queue(step3Limits(1.5));
     queue.setDegradationPolicy([] { return 1e9; }, DegradationHooks{},
@@ -653,6 +886,67 @@ TEST(AdmissionQueueTest, Step3NoDropWithoutBandwidthProvider) {
     EXPECT_TRUE(dropped.empty());
 }
 
+// A provider that cannot report bandwidth (<= 0, e.g. every RDMA NIC is
+// unavailable) disables the prediction outright: nothing is dropped, not
+// even an owner whose deadline has already passed, because "no estimate"
+// must not be read as "infeasible".
+TEST(AdmissionQueueTest, Step3NoDropWhenBandwidthIsUnknown) {
+    for (const double reported : {0.0, -1.0}) {
+        LocalTransferAdmissionQueue queue(step3Limits(1.5));
+        int hook_calls = 0;
+        DegradationHooks hooks;
+        hooks.on_local_decode_suggested = [&](const Request&) { ++hook_calls; };
+        queue.setDegradationPolicy([reported] { return reported; }, hooks,
+                                   [] { return uint64_t{2'000'000'000}; });
+
+        std::vector<QueueOwnerId> admitted_ids;
+        // Deadline 1e9 is already behind now = 2e9.
+        ASSERT_EQ(
+            queue
+                .tryAdmit(makeSubmit(1, 1,
+                                     {makeDegradationEligibleOwnerWithDeadline(
+                                         0, 16, 1'000'000'000)}),
+                          admitted_ids)
+                .code(),
+            Status::Code::kOk);
+
+        std::vector<QueueOwnerId> dropped;
+        auto picked = queue.pickForDispatch(4, 1 << 20, &dropped);
+        EXPECT_EQ(picked.size(), 1u) << "bandwidth " << reported;
+        EXPECT_TRUE(dropped.empty()) << "bandwidth " << reported;
+        EXPECT_EQ(hook_calls, 0) << "bandwidth " << reported;
+    }
+}
+
+// Drop enabled with a healthy bandwidth: an eligible owner that carries no
+// deadline has nothing to miss and is dispatched, whatever the threshold.
+TEST(AdmissionQueueTest, Step3NoDropWithoutDeadline) {
+    for (const double theta : {1.5, 1e-9}) {
+        LocalTransferAdmissionQueue queue(step3Limits(theta));
+        int hook_calls = 0;
+        DegradationHooks hooks;
+        hooks.on_local_decode_suggested = [&](const Request&) { ++hook_calls; };
+        queue.setDegradationPolicy([] { return 1e9; }, hooks,
+                                   [] { return uint64_t{1'000'000'000}; });
+
+        std::vector<QueueOwnerId> admitted_ids;
+        ASSERT_EQ(
+            queue
+                .tryAdmit(makeSubmit(1, 1,
+                                     {makeDegradationEligibleOwnerWithDeadline(
+                                         0, 1 << 20, /*deadline_ns=*/0)}),
+                          admitted_ids)
+                .code(),
+            Status::Code::kOk);
+
+        std::vector<QueueOwnerId> dropped;
+        auto picked = queue.pickForDispatch(4, 1 << 20, &dropped);
+        EXPECT_EQ(picked.size(), 1u) << "theta " << theta;
+        EXPECT_TRUE(dropped.empty()) << "theta " << theta;
+        EXPECT_EQ(hook_calls, 0) << "theta " << theta;
+    }
+}
+
 TEST(AdmissionQueueTest, Step3DynamicBandwidthProvider) {
     LocalTransferAdmissionQueue queue(step3Limits(1.5));
     std::atomic<double> live_bw{1e9};
diff --git a/mooncake-transfer-engine/tent/tests/ascend_direct_transport_test.cpp b/mooncake-transfer-engine/tent/tests/ascend_direct_transport_test.cpp
new file mode 100644
index 0000000000..e9c9a02493
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/ascend_direct_transport_test.cpp
@@ -0,0 +1,797 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <acl/acl.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/transport/ascend/ascend_direct_transport.h"
+#include "tent/transport/ascend/hixl_engine.h"
+#include "tent/transport/ascend/resource_config.h"
+
+namespace {
+
+thread_local int g_device_id = 0;
+thread_local aclrtContext g_context = reinterpret_cast<aclrtContext>(0x10000);
+int g_device_count = 1;
+int g_stream_creates = 0;
+int g_stream_destroys = 0;
+bool g_memcpy_async_fail = false;
+bool g_skip_memcpy_copy = false;
+uintptr_t g_next_stream = 0x3000;
+
+constexpr uintptr_t kContextBase = 0x10000;
+
+aclrtContext ContextForDevice(int device_id) {
+    return reinterpret_cast<aclrtContext>(kContextBase +
+                                          static_cast<uintptr_t>(device_id));
+}
+
+int DeviceForContext(aclrtContext context) {
+    const auto value = reinterpret_cast<uintptr_t>(context);
+    if (value >= kContextBase && value < kContextBase + 1024) {
+        return static_cast<int>(value - kContextBase);
+    }
+    return -1;
+}
+
+void ResetAcl() {
+    g_device_id = 0;
+    g_device_count = 1;
+    g_context = ContextForDevice(0);
+    g_stream_creates = 0;
+    g_stream_destroys = 0;
+    g_memcpy_async_fail = false;
+    g_skip_memcpy_copy = false;
+    g_next_stream = 0x3000;
+}
+
+}  // namespace
+
+extern "C" {
+
+aclError aclrtGetDeviceCount(uint32_t* count) {
+    *count = static_cast<uint32_t>(g_device_count);
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtGetDevice(int* deviceId) {
+    *deviceId = g_device_id;
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtSetDevice(int deviceId) {
+    if (deviceId >= g_device_count) {
+        return 1;
+    }
+    g_device_id = deviceId;
+    g_context = ContextForDevice(deviceId);
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtGetCurrentContext(aclrtContext* context) {
+    *context = g_context;
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtSetCurrentContext(aclrtContext context) {
+    g_context = context;
+    const int device_id = DeviceForContext(context);
+    if (device_id >= 0) {
+        g_device_id = device_id;
+    }
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtPointerGetAttributes(const void* ptr,
+                                   aclrtPtrAttributes* attributes) {
+    (void)ptr;
+    attributes->location.id = 0;
+    attributes->location.type = ACL_MEM_LOCATION_TYPE_HOST;
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtMemcpy(void* dst, size_t destMax, const void* src, size_t count,
+                     aclrtMemcpyKind kind) {
+    (void)kind;
+    if (dst == nullptr || src == nullptr || count == 0) {
+        return ACL_ERROR_NONE;
+    }
+    std::memcpy(dst, src, std::min(destMax, count));
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtMemcpyAsync(void* dst, size_t destMax, const void* src,
+                          size_t count, aclrtMemcpyKind kind,
+                          aclrtStream stream) {
+    (void)kind;
+    (void)stream;
+    if (g_memcpy_async_fail) {
+        return 1;
+    }
+    if (g_skip_memcpy_copy || dst == nullptr || src == nullptr || count == 0) {
+        return ACL_ERROR_NONE;
+    }
+    const auto dst_addr = reinterpret_cast<uintptr_t>(dst);
+    const auto src_addr = reinterpret_cast<uintptr_t>(src);
+    if (dst_addr < 0x10000 || src_addr < 0x10000) {
+        return ACL_ERROR_NONE;
+    }
+    std::memcpy(dst, src, std::min(destMax, count));
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtMalloc(void** devPtr, size_t size, aclrtMemMallocPolicy policy) {
+    (void)policy;
+    *devPtr = std::malloc(size);
+    return *devPtr != nullptr ? ACL_ERROR_NONE : 1;
+}
+
+aclError aclrtFree(void* devPtr) {
+    std::free(devPtr);
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtMallocHost(void** hostPtr, size_t size) {
+    *hostPtr = std::malloc(size);
+    return *hostPtr != nullptr ? ACL_ERROR_NONE : 1;
+}
+
+aclError aclrtFreeHost(void* hostPtr) {
+    std::free(hostPtr);
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtCreateStreamWithConfig(aclrtStream* stream, uint32_t priority,
+                                     uint32_t flag) {
+    (void)priority;
+    (void)flag;
+    *stream = reinterpret_cast<aclrtStream>(g_next_stream++);
+    g_stream_creates++;
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtDestroyStream(aclrtStream stream) {
+    (void)stream;
+    g_stream_destroys++;
+    return ACL_ERROR_NONE;
+}
+
+aclError aclrtStreamAbort(aclrtStream stream) {
+    (void)stream;
+    return ACL_ERROR_NONE;
+}
+
+const char* aclGetRecentErrMsg() { return "mock acl error message"; }
+
+aclError aclrtGetPhyDevIdByLogicDevId(int32_t logic_dev_id,
+                                      int32_t* physical_dev_id) {
+    *physical_dev_id = logic_dev_id;
+    return ACL_ERROR_NONE;
+}
+
+}  // extern "C"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+const char* kEnvKeys[] = {
+    "ASCEND_TRANSFER_TIMEOUT",
+    "ASCEND_LOCAL_COMM_RES",
+    "ASCEND_ENABLE_USE_FABRIC_MEM",
+    "ASCEND_GLOBAL_RESOURCE_CONFIG",
+    "ASCEND_RDMA_TC",
+    "ASCEND_RDMA_SL",
+    "HCCL_RDMA_TC",
+    "HCCL_RDMA_SL",
+    "HCCL_INTRA_ROCE_ENABLE",
+    "ASCEND_BASE_PORT",
+};
+
+void ClearAscendEnv() {
+    for (const char* key : kEnvKeys) {
+        unsetenv(key);
+    }
+}
+
+struct MockHixlState {
+    std::mutex mu;
+    int initialize_calls = 0;
+    int connect_calls = 0;
+    int disconnect_calls = 0;
+    int transfer_async_calls = 0;
+    int get_status_calls = 0;
+    int register_calls = 0;
+    int deregister_calls = 0;
+    int concurrent_transfer = 0;
+    int max_concurrent_transfer = 0;
+    bool fail_next_transfer = false;
+    int fail_register_on = -1;
+    HixlXferState xfer_state = HixlXferState::Completed;
+    std::map<std::string, std::string> last_options;
+    std::string last_remote;
+    std::vector<std::map<std::string, std::string>> all_options;
+    std::atomic<uintptr_t> next_handle{0x2000};
+};
+
+class MockHixlVendor final : public HixlEngine::Vendor {
+   public:
+    explicit MockHixlVendor(std::shared_ptr<MockHixlState> state)
+        : state_(std::move(state)) {}
+
+    uint32_t Initialize(
+        const std::string& local_name,
+        const std::map<std::string, std::string>& options) override {
+        (void)local_name;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->initialize_calls++;
+        state_->last_options = options;
+        state_->all_options.push_back(options);
+        return kHixlOk;
+    }
+
+    void Finalize() override {}
+
+    uint32_t RegisterMem(uint64_t addr, size_t len, bool host,
+                         void*& handle) override {
+        (void)addr;
+        (void)len;
+        (void)host;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->register_calls++;
+        if (state_->fail_register_on == state_->register_calls) {
+            handle = nullptr;
+            return 1;
+        }
+        handle = reinterpret_cast<void*>(
+            state_->next_handle.fetch_add(1, std::memory_order_relaxed));
+        return kHixlOk;
+    }
+
+    uint32_t DeregisterMem(void* handle) override {
+        (void)handle;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->deregister_calls++;
+        return kHixlOk;
+    }
+
+    uint32_t TransferAsync(const std::string& remote, bool write,
+                           const std::vector<HixlOpDesc>& descs,
+                           void*& req) override {
+        (void)write;
+        (void)descs;
+        {
+            std::lock_guard<std::mutex> lock(state_->mu);
+            state_->transfer_async_calls++;
+            state_->concurrent_transfer++;
+            state_->max_concurrent_transfer = std::max(
+                state_->max_concurrent_transfer, state_->concurrent_transfer);
+            state_->last_remote = remote;
+            if (state_->fail_next_transfer) {
+                state_->fail_next_transfer = false;
+                state_->concurrent_transfer--;
+                req = nullptr;
+                return 1;
+            }
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+        {
+            std::lock_guard<std::mutex> lock(state_->mu);
+            state_->concurrent_transfer--;
+            req = reinterpret_cast<void*>(
+                state_->next_handle.fetch_add(1, std::memory_order_relaxed));
+        }
+        return kHixlOk;
+    }
+
+    uint32_t GetTransferStatus(void* req, HixlXferState& status) override {
+        (void)req;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->get_status_calls++;
+        status = state_->xfer_state;
+        return kHixlOk;
+    }
+
+    uint32_t Disconnect(const std::string& remote,
+                        int32_t timeout_ms) override {
+        (void)remote;
+        (void)timeout_ms;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->disconnect_calls++;
+        return kHixlOk;
+    }
+
+    uint32_t Connect(const std::string& remote, int32_t timeout_ms) override {
+        (void)remote;
+        (void)timeout_ms;
+        std::lock_guard<std::mutex> lock(state_->mu);
+        state_->connect_calls++;
+        return kHixlOk;
+    }
+
+   private:
+    std::shared_ptr<MockHixlState> state_;
+};
+
+class AscendDirectTransportTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        ClearAscendEnv();
+        ResetAcl();
+        state_ = std::make_shared<MockHixlState>();
+        HixlEngine::SetVendorFactory([state = state_]() {
+            return std::make_unique<MockHixlVendor>(state);
+        });
+        metadata_ = std::make_shared<ControlService>("p2p", "", nullptr);
+        transport_ = std::make_unique<AscendDirectTransport>();
+    }
+
+    void TearDown() override {
+        if (batch_ != nullptr) {
+            (void)transport_->freeSubBatch(batch_);
+        }
+        if (transport_) {
+            (void)transport_->uninstall();
+        }
+        HixlEngine::SetVendorFactory(nullptr);
+        ClearAscendEnv();
+    }
+
+    Status Install(std::shared_ptr<Config> conf = nullptr) {
+        name_ = "127.0.0.1:23456";
+        return transport_->install(name_, metadata_, nullptr, conf);
+    }
+
+    Request MakeWrite(void* src, uint64_t dest, size_t len) {
+        Request request{};
+        request.opcode = Request::WRITE;
+        request.source = src;
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = dest;
+        request.length = len;
+        return request;
+    }
+
+    Status InstallAgentTwoEngines(std::shared_ptr<Config> extra = nullptr) {
+        g_device_count = 2;
+        g_device_id = 0;
+        auto conf = extra ? extra : std::make_shared<Config>();
+        conf->set("transports/ascend_direct/agent_mode", true);
+        return Install(conf);
+    }
+
+    void PublishEngineBuffers() {
+        BufferDesc buf0{};
+        buf0.addr = 0x10000;
+        buf0.length = 4096;
+        buf0.transport_attrs[AscendDirect] = "0";
+        BufferDesc buf1{};
+        buf1.addr = 0x20000;
+        buf1.length = 4096;
+        buf1.transport_attrs[AscendDirect] = "1";
+        ASSERT_TRUE(metadata_->segmentManager()
+                        .updateLocal([&](SegmentDesc& segment) {
+                            auto& mem =
+                                std::get<MemorySegmentDesc>(segment.detail);
+                            mem.buffers.push_back(buf0);
+                            mem.buffers.push_back(buf1);
+                            return Status::OK();
+                        })
+                        .ok());
+    }
+
+    Request MakeRemoteWrite(void* src, size_t len, uint64_t dest = 0x20010) {
+        return MakeWrite(src, dest, len);
+    }
+
+    std::shared_ptr<MockHixlState> state_;
+    std::shared_ptr<ControlService> metadata_;
+    std::unique_ptr<AscendDirectTransport> transport_;
+    Transport::SubBatchRef batch_{nullptr};
+    std::string name_;
+};
+
+TEST_F(AscendDirectTransportTest, InitializeIsAutoConnectOnly) {
+    ASSERT_TRUE(Install().ok());
+    const auto& opts = AscendDirectTransportTestPeer::initOptions(*transport_);
+    EXPECT_EQ(opts.at("AutoConnect"), "1");
+    EXPECT_EQ(opts.at("LocalCommRes"), kDefaultLocalCommRes);
+    EXPECT_EQ(opts.count("BufferPool"), 0u);
+    EXPECT_EQ(opts.count("ShortConnection"), 0u);
+    EXPECT_EQ(state_->connect_calls, 0);
+    EXPECT_FALSE(transport_->supportNotification());
+}
+
+TEST_F(AscendDirectTransportTest, LocalCommResEnvOverride) {
+    setenv("ASCEND_LOCAL_COMM_RES", R"({"version":"9.9"})", 1);
+    ASSERT_TRUE(Install().ok());
+    const auto& opts = AscendDirectTransportTestPeer::initOptions(*transport_);
+    EXPECT_EQ(opts.at("LocalCommRes"), R"({"version":"9.9"})");
+}
+
+TEST_F(AscendDirectTransportTest, FabricOptionInjectedFromConfig) {
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/fabric_mem", true);
+    ASSERT_TRUE(Install(conf).ok());
+    const auto& opts = AscendDirectTransportTestPeer::initOptions(*transport_);
+    EXPECT_EQ(opts.at("EnableUseFabricMem"), "1");
+    EXPECT_TRUE(
+        AscendDirectTransportTestPeer::options(*transport_).use_fabric_mem);
+}
+
+TEST_F(AscendDirectTransportTest, FabricEnvDoesNotLeakWithoutStoreTeInit) {
+    setenv("ASCEND_ENABLE_USE_FABRIC_MEM", "1", 1);
+    auto options = LoadAscendDirectOptions(nullptr);
+    EXPECT_FALSE(options.use_fabric_mem);
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/store_te_init", true);
+    options = LoadAscendDirectOptions(conf);
+    EXPECT_TRUE(options.use_fabric_mem);
+}
+
+TEST_F(AscendDirectTransportTest, TimeoutMsFromEnv) {
+    setenv("ASCEND_TRANSFER_TIMEOUT", "2500", 1);
+    auto options = LoadAscendDirectOptions(nullptr);
+    EXPECT_EQ(options.transfer_timeout_ms, 2500);
+}
+
+TEST_F(AscendDirectTransportTest, BuildHixlInitOptionsNeverSetsBufferPool) {
+    AscendDirectOptions options;
+    options.use_fabric_mem = true;
+    options.rdma_tc = "192";
+    auto init = BuildHixlInitOptions(options);
+    EXPECT_EQ(init.at("AutoConnect"), "1");
+    EXPECT_EQ(init.at("EnableUseFabricMem"), "1");
+    EXPECT_EQ(init.at("RdmaTrafficClass"), "192");
+    EXPECT_EQ(init.count("BufferPool"), 0u);
+    EXPECT_EQ(init.count("Connect"), 0u);
+}
+
+TEST_F(AscendDirectTransportTest, InitializeInjectsPerEngineListenPort) {
+    setenv("ASCEND_GLOBAL_RESOURCE_CONFIG",
+           R"({"comm_resource_config":{"protocol_desc":"roce:device"}})", 1);
+    ASSERT_TRUE(Install().ok());
+    ASSERT_EQ(state_->last_options.count("GlobalResourceConfig"), 1u);
+    const auto& cfg = state_->last_options.at("GlobalResourceConfig");
+    EXPECT_NE(cfg.find("listen_port"), std::string::npos);
+    EXPECT_NE(cfg.find("roce:device"), std::string::npos);
+}
+
+TEST_F(AscendDirectTransportTest, HccsInitDoesNotInjectRoceListenPort) {
+    setenv("ASCEND_GLOBAL_RESOURCE_CONFIG",
+           R"({"comm_resource_config":{"protocol_desc":"hccs:device"}})", 1);
+    ASSERT_TRUE(Install().ok());
+    ASSERT_EQ(state_->last_options.count("GlobalResourceConfig"), 1u);
+    const auto& cfg = state_->last_options.at("GlobalResourceConfig");
+    EXPECT_EQ(cfg.find("listen_port"), std::string::npos);
+    EXPECT_NE(cfg.find("hccs:device"), std::string::npos);
+}
+
+TEST_F(AscendDirectTransportTest, SubmitRollbackLeavesBatchUnchanged) {
+    ASSERT_TRUE(Install().ok());
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 8).ok());
+    char src[64]{};
+    std::vector<Request> requests = {MakeWrite(src, 0x1000, 64),
+                                     MakeWrite(src, 0x2000, 64)};
+    requests[1].target_id = 99;
+    auto status = transport_->submitTransferTasks(batch_, requests);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(batch_->size(), 0u);
+    EXPECT_EQ(state_->transfer_async_calls, 0);
+}
+
+TEST_F(AscendDirectTransportTest, SameEngineUsesLocalCopy) {
+    ASSERT_TRUE(Install().ok());
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 4).ok());
+    char src[32]{};
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeWrite(src, 0x1000, 32)})
+            .ok());
+    TransferStatus status{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, 32u);
+    EXPECT_EQ(state_->transfer_async_calls, 0);
+    EXPECT_EQ(state_->connect_calls, 0);
+    EXPECT_EQ(state_->disconnect_calls, 0);
+    EXPECT_EQ(AscendDirectTransportTestPeer::inflight(*transport_), 0);
+    EXPECT_GE(g_stream_creates, 1);
+}
+
+TEST_F(AscendDirectTransportTest, LocalCopyFailureFailsAllStreamTasks) {
+    ASSERT_TRUE(Install().ok());
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 4).ok());
+    char src[32]{};
+    g_skip_memcpy_copy = true;
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeWrite(src, 0x1000, 16)})
+            .ok());
+    TransferStatus pending{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, pending).ok());
+    EXPECT_EQ(pending.s, TransferStatusEnum::PENDING);
+
+    const int destroys_before = g_stream_destroys;
+    g_memcpy_async_fail = true;
+    Transport::SubBatchRef batch_b = nullptr;
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_b, 2).ok());
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_b, {MakeWrite(src, 0x2000, 16)})
+            .ok());
+    TransferStatus first{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, first).ok());
+    EXPECT_EQ(first.s, TransferStatusEnum::FAILED);
+    TransferStatus second{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_b, 0, second).ok());
+    EXPECT_EQ(second.s, TransferStatusEnum::FAILED);
+    EXPECT_GT(g_stream_destroys, destroys_before);
+    EXPECT_EQ(state_->transfer_async_calls, 0);
+    (void)transport_->freeSubBatch(batch_b);
+}
+
+TEST_F(AscendDirectTransportTest, LocalCopyTimeoutRecreatesStream) {
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/transfer_timeout_ms", 1);
+    ASSERT_TRUE(Install(conf).ok());
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 2).ok());
+    char src[16]{};
+    g_skip_memcpy_copy = true;
+    const int destroys_before = g_stream_destroys;
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeWrite(src, 0x1000, 16)})
+            .ok());
+    std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    TransferStatus status{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::TIMEOUT);
+    EXPECT_GT(g_stream_destroys, destroys_before);
+    EXPECT_EQ(state_->transfer_async_calls, 0);
+    EXPECT_EQ(state_->disconnect_calls, 0);
+}
+
+TEST_F(AscendDirectTransportTest, FailEntireRouteMarksSiblingTasks) {
+    state_->xfer_state = HixlXferState::Failed;
+    ASSERT_TRUE(InstallAgentTwoEngines().ok());
+    PublishEngineBuffers();
+    g_device_id = 0;
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 4).ok());
+    char src[64]{};
+    ASSERT_TRUE(
+        transport_
+            ->submitTransferTasks(batch_, {MakeRemoteWrite(src, 32, 0x20010),
+                                           MakeRemoteWrite(src, 32, 0x20020)})
+            .ok());
+    TransferStatus first{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, first).ok());
+    EXPECT_EQ(first.s, TransferStatusEnum::FAILED);
+    const int polls_after_first = state_->get_status_calls;
+    TransferStatus second{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 1, second).ok());
+    EXPECT_EQ(second.s, TransferStatusEnum::FAILED);
+    EXPECT_EQ(state_->get_status_calls, polls_after_first);
+    EXPECT_EQ(state_->disconnect_calls, 0);
+    EXPECT_EQ(state_->transfer_async_calls, 1);
+}
+
+TEST_F(AscendDirectTransportTest, TimeoutDisconnectsHungRoute) {
+    state_->xfer_state = HixlXferState::Waiting;
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/transfer_timeout_ms", 1);
+    ASSERT_TRUE(InstallAgentTwoEngines(conf).ok());
+    PublishEngineBuffers();
+    g_device_id = 0;
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 2).ok());
+    char src[16]{};
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeRemoteWrite(src, 16)})
+            .ok());
+    std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    TransferStatus status{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::TIMEOUT);
+    EXPECT_GE(state_->disconnect_calls, 1);
+    EXPECT_EQ(state_->connect_calls, 0);
+    EXPECT_EQ(state_->transfer_async_calls, 1);
+}
+
+TEST_F(AscendDirectTransportTest, MultiEnginePublishesNamesAndRoutesDest) {
+    ASSERT_TRUE(InstallAgentTwoEngines().ok());
+    ASSERT_EQ(AscendDirectTransportTestPeer::engineCount(*transport_), 2u);
+    const auto name0 =
+        AscendDirectTransportTestPeer::engineName(*transport_, 0);
+    const auto name1 =
+        AscendDirectTransportTestPeer::engineName(*transport_, 1);
+    EXPECT_NE(name0, name1);
+
+    auto local = metadata_->segmentManager().getLocal();
+    const auto& detail = std::get<MemorySegmentDesc>(local->detail);
+    EXPECT_EQ(detail.device_attrs.at(kHixlNameAttr), name0);
+    auto names = ParseHixlNames(detail);
+    ASSERT_EQ(names.size(), 2u);
+
+    PublishEngineBuffers();
+    g_device_id = 0;
+
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 2).ok());
+    char src[32]{};
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeRemoteWrite(src, 16)})
+            .ok());
+    EXPECT_EQ(state_->last_remote, name1);
+    TransferStatus status{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(state_->transfer_async_calls, 1);
+}
+
+TEST_F(AscendDirectTransportTest, DummyRealHostBuffersFollowCurrentDevice) {
+    g_device_count = 2;
+    g_device_id = 0;
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/agent_mode", true);
+    ASSERT_TRUE(Install(conf).ok());
+    MemoryOptions opts{};
+    BufferDesc on0{};
+    on0.addr = 0x30000;
+    on0.length = 4096;
+    on0.location = "cpu:0";
+    g_device_id = 0;
+    ASSERT_TRUE(transport_->addMemoryBuffer(on0, opts).ok());
+    EXPECT_EQ(on0.transport_attrs[AscendDirect], "0");
+    BufferDesc on1{};
+    on1.addr = 0x40000;
+    on1.length = 4096;
+    on1.location = "cpu:0";
+    g_device_id = 1;
+    ASSERT_TRUE(transport_->addMemoryBuffer(on1, opts).ok());
+    EXPECT_EQ(on1.transport_attrs[AscendDirect], "1");
+}
+
+TEST_F(AscendDirectTransportTest, RegisterRollbackUnregistersPrefix) {
+    ASSERT_TRUE(Install().ok());
+    state_->fail_register_on = 2;
+    std::vector<BufferDesc> desc_list(2);
+    desc_list[0].addr = 0x1000;
+    desc_list[0].length = 64;
+    desc_list[0].location = "cpu:0";
+    desc_list[1].addr = 0x2000;
+    desc_list[1].length = 64;
+    desc_list[1].location = "cpu:0";
+    MemoryOptions options;
+    auto status = transport_->addMemoryBuffer(desc_list, options);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(state_->register_calls, 2);
+    EXPECT_EQ(state_->deregister_calls, 1);
+}
+
+TEST_F(AscendDirectTransportTest, QuiesceWaitsForInflight) {
+    state_->xfer_state = HixlXferState::Waiting;
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/transfer_timeout_ms", 50);
+    ASSERT_TRUE(InstallAgentTwoEngines(conf).ok());
+    PublishEngineBuffers();
+    g_device_id = 0;
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_, 2).ok());
+    char src[16]{};
+    ASSERT_TRUE(
+        transport_->submitTransferTasks(batch_, {MakeRemoteWrite(src, 16)})
+            .ok());
+    EXPECT_EQ(AscendDirectTransportTestPeer::inflight(*transport_), 1);
+    state_->xfer_state = HixlXferState::Completed;
+    TransferStatus status{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED);
+    EXPECT_TRUE(transport_->quiesce().ok());
+    EXPECT_EQ(AscendDirectTransportTestPeer::inflight(*transport_), 0);
+}
+
+TEST_F(AscendDirectTransportTest, PerEngineMutexSerializesSubmit) {
+    ASSERT_TRUE(InstallAgentTwoEngines().ok());
+    PublishEngineBuffers();
+    g_device_id = 0;
+    char src_a[16]{};
+    char src_b[16]{};
+    Transport::SubBatchRef batch_a = nullptr;
+    Transport::SubBatchRef batch_b = nullptr;
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_a, 2).ok());
+    ASSERT_TRUE(transport_->allocateSubBatch(batch_b, 2).ok());
+    std::thread t1([&] {
+        (void)transport_->submitTransferTasks(batch_a,
+                                              {MakeRemoteWrite(src_a, 16)});
+    });
+    std::thread t2([&] {
+        (void)transport_->submitTransferTasks(
+            batch_b, {MakeRemoteWrite(src_b, 16, 0x20020)});
+    });
+    t1.join();
+    t2.join();
+    EXPECT_EQ(state_->max_concurrent_transfer, 1);
+    EXPECT_EQ(state_->connect_calls, 0);
+    TransferStatus status_a{};
+    TransferStatus status_b{};
+    ASSERT_TRUE(transport_->getTransferStatus(batch_a, 0, status_a).ok());
+    ASSERT_TRUE(transport_->getTransferStatus(batch_b, 0, status_b).ok());
+    EXPECT_EQ(status_a.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status_b.s, TransferStatusEnum::COMPLETED);
+    (void)transport_->freeSubBatch(batch_a);
+    (void)transport_->freeSubBatch(batch_b);
+}
+
+TEST(AscendDirectResourceConfigTest, StoreJsonIsolation) {
+    ClearAscendEnv();
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/ascend_direct/global_resource_config",
+              R"({"store":{"fabric_memory":{"a":1}},"other":1})");
+    auto p2p = LoadAscendDirectOptions(conf);
+    EXPECT_FALSE(p2p.use_fabric_mem);
+    conf->set("transports/ascend_direct/store_te_init", true);
+    auto store = LoadAscendDirectOptions(conf);
+    EXPECT_TRUE(store.use_fabric_mem);
+}
+
+TEST(AscendDirectResourceConfigTest, DestRoutingUsesBufferEngineIndex) {
+    MemorySegmentDesc detail;
+    detail.device_attrs[kHixlNamesAttr] = R"(["a:1","b:2"])";
+    BufferDesc buf{};
+    buf.addr = 100;
+    buf.length = 50;
+    buf.transport_attrs[AscendDirect] = "1";
+    detail.buffers.push_back(buf);
+    EXPECT_EQ(ResolveRemoteHixlName(detail, 120), "b:2");
+}
+
+TEST(AscendDirectResourceConfigTest, RoceListenPortAvoidsHixlControlPort) {
+    EXPECT_EQ(HixlRoceListenPort(20000), 30000);
+    EXPECT_EQ(HixlRoceListenPort(42067), 52067);
+    EXPECT_NE(HixlRoceListenPort(20000), 20000u);
+    EXPECT_EQ(HixlRoceListenPort(60000), 50000);
+}
+
+TEST(AscendDirectResourceConfigTest, WithHixlListenPortKeepsProtocolDesc) {
+    AscendDirectOptions options;
+    options.global_resource_config =
+        R"({"comm_resource_config":{"protocol_desc":"roce:device"}})";
+    auto init = WithHixlListenPort(BuildHixlInitOptions(options), 52067);
+    const auto& cfg = init.at("GlobalResourceConfig");
+    EXPECT_NE(cfg.find("\"listen_port\":52067"), std::string::npos);
+    EXPECT_NE(cfg.find("roce:device"), std::string::npos);
+}
+
+TEST(AscendDirectResourceConfigTest, WithHixlListenPortReplacesFlatPort) {
+    AscendDirectOptions options;
+    options.global_resource_config =
+        R"({"comm_resource_config.listen_port":26666,"comm_resource_config.protocol_desc":["roce:device"]})";
+    auto init = WithHixlListenPort(BuildHixlInitOptions(options), 52067);
+    const auto parsed = nlohmann::json::parse(init.at("GlobalResourceConfig"));
+    EXPECT_EQ(parsed.at("comm_resource_config.listen_port"), 52067);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/bootstrap_response_test.cpp b/mooncake-transfer-engine/tent/tests/bootstrap_response_test.cpp
new file mode 100644
index 0000000000..39b2ee4066
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/bootstrap_response_test.cpp
@@ -0,0 +1,67 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <string_view>
+
+#include "tent/runtime/control_plane.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+TEST(BootstrapResponseTest, ValidGidIsSuccess) {
+    BootstrapDesc desc;
+    desc.local_gid = "fe80::1";
+    desc.qp_num = {1, 2};
+    BootstrapDesc parsed;
+    auto status =
+        ControlClient::decodeBootstrapResponse(json(desc).dump(), parsed);
+    EXPECT_TRUE(status.ok());
+    EXPECT_EQ(parsed.local_gid, "fe80::1");
+    EXPECT_EQ(parsed.qp_num, desc.qp_num);
+}
+
+TEST(BootstrapResponseTest, ReplyMsgIsHandshakeFailure) {
+    BootstrapDesc desc;
+    desc.local_gid = "fe80::1";
+    desc.reply_msg = "Endpoint retired for reconnection from peer";
+    BootstrapDesc parsed;
+    auto status =
+        ControlClient::decodeBootstrapResponse(json(desc).dump(), parsed);
+    EXPECT_TRUE(status.IsRpcServiceError());
+    EXPECT_NE(status.message().find("retired for reconnection"),
+              std::string_view::npos);
+}
+
+TEST(BootstrapResponseTest, EmptyGidIsHandshakeFailure) {
+    BootstrapDesc desc;
+    BootstrapDesc parsed;
+    auto status =
+        ControlClient::decodeBootstrapResponse(json(desc).dump(), parsed);
+    EXPECT_TRUE(status.IsInvalidArgument());
+    EXPECT_NE(status.message().find("Missing peer GID"),
+              std::string_view::npos);
+}
+
+TEST(BootstrapResponseTest, InvalidJsonIsMalformed) {
+    BootstrapDesc parsed;
+    auto status = ControlClient::decodeBootstrapResponse("not-json", parsed);
+    EXPECT_TRUE(status.IsMalformedJson());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/bounded_mpsc_queue_test.cpp b/mooncake-transfer-engine/tent/tests/bounded_mpsc_queue_test.cpp
new file mode 100644
index 0000000000..58e5c667c5
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/bounded_mpsc_queue_test.cpp
@@ -0,0 +1,115 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+//
+// Regression coverage for issue #3637: a full queue used to spin push()
+// forever, so a worker re-enqueueing its own slices could wedge the only
+// consumer. try_push must report fullness instead, and the worker-local
+// overflow must drain before the shared queue so parked entries cannot
+// starve behind contending producers.
+
+#include "tent/common/concurrent/bounded_mpsc_queue.h"
+
+#include <gtest/gtest.h>
+
+#include <vector>
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// The queue is generic over T and only touches num_slices, so a stand-in keeps
+// this test buildable without the RDMA transport headers.
+struct SliceList {
+    void* first = nullptr;
+    int num_slices = 0;
+};
+
+using Queue = BoundedMPSCQueue<SliceList, 8>;
+
+SliceList entry(int n) {
+    SliceList list;
+    list.num_slices = n;
+    return list;
+}
+
+TEST(BoundedMPSCQueueTest, TryPushReportsFullInsteadOfSpinning) {
+    Queue queue;
+    for (int i = 0; i < 8; ++i) {
+        auto item = entry(1);
+        ASSERT_TRUE(queue.try_push(item));
+    }
+    auto extra = entry(1);
+    EXPECT_FALSE(queue.try_push(extra));
+}
+
+TEST(BoundedMPSCQueueTest, PopDrainsInOrderAfterFull) {
+    Queue queue;
+    for (int i = 1; i <= 8; ++i) {
+        auto item = entry(i);
+        ASSERT_TRUE(queue.try_push(item));
+    }
+    for (int i = 1; i <= 8; ++i) {
+        EXPECT_EQ(queue.pop().num_slices, i);
+    }
+    // Empty pop returns a zero-initialized entry.
+    EXPECT_EQ(queue.pop().num_slices, 0);
+}
+
+TEST(BoundedMPSCQueueTest, ParkedEntryIsDrainedBeforeContendingProducers) {
+    // Model the production drain order: the worker consumes its local overflow
+    // before popping the shared queue, so a parked retry makes progress even
+    // while producers keep refilling freed slots (review feedback on #3683).
+    Queue queue;
+    for (int i = 0; i < 8; ++i) {
+        auto item = entry(1);
+        ASSERT_TRUE(queue.try_push(item));
+    }
+    std::vector<SliceList> overflow;
+    auto parked = entry(7);
+    ASSERT_FALSE(queue.try_push(parked));
+    overflow.push_back(parked);
+
+    // First tick drains the shared queue fully; a producer instantly refills.
+    std::vector<SliceList> first_batch;
+    queue.pop(first_batch);
+    ASSERT_EQ(first_batch.size(), 8u);
+    auto fresh = entry(9);
+    ASSERT_TRUE(queue.try_push(fresh));
+
+    // Second tick: overflow first, then the shared queue.
+    std::vector<SliceList> batch;
+    for (auto it = overflow.begin(); it != overflow.end();) {
+        batch.push_back(*it);
+        it = overflow.erase(it);
+    }
+    queue.pop(batch);
+    ASSERT_EQ(batch.size(), 2u);
+    EXPECT_EQ(batch[0].num_slices, 7);
+    EXPECT_EQ(batch[1].num_slices, 9);
+    EXPECT_TRUE(overflow.empty());
+}
+
+TEST(BoundedMPSCQueueTest, PushStillAcceptsAndEmptyPushIsANoop) {
+    Queue queue;
+    auto empty = entry(0);
+    queue.push(empty);  // returns immediately for an empty list
+    auto item = entry(3);
+    queue.push(item);
+    EXPECT_EQ(queue.pop().num_slices, 3);
+    EXPECT_EQ(queue.pop().num_slices, 0);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/bw_arbitration_test.cpp b/mooncake-transfer-engine/tent/tests/bw_arbitration_test.cpp
index 3664362ba0..525db6ebbc 100644
--- a/mooncake-transfer-engine/tent/tests/bw_arbitration_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/bw_arbitration_test.cpp
@@ -15,10 +15,12 @@
 // Unit tests for the deadline-aware bandwidth arbitration ordering (#2792).
 
 #include "tent/transport/rdma/bw_arbitration.h"
+#include "tent/runtime/deadline_mlu.h"
 
 #include <gtest/gtest.h>
 
 #include <cstdint>
+#include <limits>
 #include <vector>
 
 namespace mooncake {
@@ -33,6 +35,78 @@ ArbFlow flow(uint64_t window_ns, size_t len) {
     return ArbFlow{kNow + window_ns, len};
 }
 
+// The admission queue's drop predictor and the NIC arbitration must compute
+// the same MLU from the same inputs; DeadlineMlu is that one definition.
+TEST(DeadlineMluTest, PredictedTimeOverWindow) {
+    // 16 B at 1 GB/s = 16 ns; a 32 ns window is half used.
+    EXPECT_DOUBLE_EQ(DeadlineMlu(0, 16, kNow + 32, kNow, kBw), 0.5);
+}
+
+// A deadline is absolute, so time spent behind bytes already in the pipeline
+// counts against the window: it is an additive delay, not a slower link.
+TEST(DeadlineMluTest, BytesAheadAddToPredictedTime) {
+    EXPECT_DOUBLE_EQ(DeadlineMlu(16, 16, kNow + 32, kNow, kBw), 1.0);
+    // Queueing alone can exhaust the window even for a tiny request.
+    EXPECT_DOUBLE_EQ(DeadlineMlu(64, 0, kNow + 32, kNow, kBw), 2.0);
+}
+
+TEST(DeadlineMluTest, NoDeadlineOrNoBandwidthIsNotUrgent) {
+    EXPECT_DOUBLE_EQ(DeadlineMlu(0, 16, 0, kNow, kBw), 0.0);
+    EXPECT_DOUBLE_EQ(DeadlineMlu(0, 16, kNow + 32, kNow, 0.0), 0.0);
+    EXPECT_DOUBLE_EQ(DeadlineMlu(0, 16, kNow + 32, kNow, -1.0), 0.0);
+}
+
+TEST(DeadlineMluTest, PastDeadlineIsInfinitelyUrgent) {
+    EXPECT_EQ(DeadlineMlu(0, 16, kNow, kNow, kBw),
+              std::numeric_limits<double>::max());
+    EXPECT_EQ(DeadlineMlu(0, 16, kNow - 1, kNow, kBw),
+              std::numeric_limits<double>::max());
+}
+
+TEST(DeadlineMluTest, ArbitrationUsesTheSameDefinition) {
+    const ArbFlow f = flow(32, 16);
+    EXPECT_DOUBLE_EQ(PredictedMlu(f, kNow, kBw),
+                     DeadlineMlu(0, f.length, f.deadline_ns, kNow, kBw));
+    EXPECT_DOUBLE_EQ(PredictedMlu(f, kNow, kBw, 48),
+                     DeadlineMlu(48, f.length, f.deadline_ns, kNow, kBw));
+}
+
+TEST(BwArbitrationTest, BytesAheadFavorTheTighterWindow) {
+    std::vector<ArbFlow> flows = {
+        flow(100'000, 4096),  // idx0: 4.1us of 100us  -> MLU 0.041
+        flow(30'000, 1024),   // idx1: 1.0us of 30us   -> MLU 0.034
+    };
+    // On an idle NIC the bigger request is (slightly) more urgent...
+    auto idle = OrderByUrgency(flows, kNow, kBw);
+    EXPECT_EQ(idle[0], 0u);
+    // ...but behind 64 KiB already queued (65.5us) the 30us window is gone
+    // while the 100us one still has room, so the small flow must go first.
+    auto busy = OrderByUrgency(flows, kNow, kBw, 65536);
+    EXPECT_EQ(busy[0], 1u);
+    EXPECT_EQ(busy[1], 0u);
+}
+
+// Ordering is decided one slot at a time: once a flow takes a slot, the
+// flows still waiting sit behind its bytes too, so the queue-ahead term
+// grows as the order is built. Scoring everyone once against the same value
+// would miss that.
+TEST(BwArbitrationTest, EachSlotIsScoredBehindTheOnesBeforeIt) {
+    // 1 GB/s: 1 byte == 1 ns of wire time.
+    std::vector<ArbFlow> flows = {
+        flow(40'000, 100'000),  // idx0: 100us of a 40us window -> 2.50
+        flow(100'000, 20'000),  // idx1: 20us of a 100us window -> 0.20
+        flow(50'000, 5'000),    // idx2: 5us of a 50us window   -> 0.10
+    };
+    // Scored once, the order would be its own MLU ranking: 0, 1, 2.
+    // Behind idx0's 100us, though, idx2's 50us window is blown (105/50 =
+    // 2.10) while idx1 still fits (120/100 = 1.20), so idx2 goes first.
+    auto order = OrderByUrgency(flows, kNow, kBw);
+    ASSERT_EQ(order.size(), 3u);
+    EXPECT_EQ(order[0], 0u);
+    EXPECT_EQ(order[1], 2u);
+    EXPECT_EQ(order[2], 1u);
+}
+
 TEST(BwArbitrationTest, TighterDeadlineSortsFirst) {
     std::vector<ArbFlow> flows = {
         flow(1'000'000, 4096),  // idx0: loose (1ms window)
diff --git a/mooncake-transfer-engine/tent/tests/config_lifecycle_test.cpp b/mooncake-transfer-engine/tent/tests/config_lifecycle_test.cpp
new file mode 100644
index 0000000000..a217944df5
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/config_lifecycle_test.cpp
@@ -0,0 +1,325 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <set>
+#include <string>
+
+#include "tent/common/config_lifecycle.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class EnvVarGuard {
+   public:
+    EnvVarGuard(const char* name, const char* value) : name_(name) {
+        const char* old = std::getenv(name);
+        if (old) {
+            old_value_ = old;
+            had_value_ = true;
+        }
+        setenv(name, value, 1);
+    }
+
+    ~EnvVarGuard() {
+        if (had_value_) {
+            setenv(name_.c_str(), old_value_.c_str(), 1);
+        } else {
+            unsetenv(name_.c_str());
+        }
+    }
+
+   private:
+    std::string name_;
+    std::string old_value_;
+    bool had_value_{false};
+};
+
+TEST(ConfigLifecycleTest, RuntimeAllowlistPathsAreUnique) {
+    std::set<std::string_view> paths;
+    for (const auto& field : configFieldInventory()) {
+        EXPECT_EQ(classifyConfigPath(field.path),
+                  ConfigLifecycle::kRuntimeCandidate);
+        EXPECT_FALSE(field.path.empty());
+        EXPECT_TRUE(paths.insert(field.path).second) << field.path;
+    }
+}
+
+TEST(ConfigLifecycleTest, ClassifiesRepresentativeFields) {
+    EXPECT_EQ(classifyConfigPath("rpc_server_port"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("topology/rdma_whitelist"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("transports/tcp/max_retry_count"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("transports/hp_tcp/worker_count"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("staging/shutdown_drain_timeout_ms"),
+              ConfigLifecycle::kBootstrapOnly);
+
+    EXPECT_EQ(classifyConfigPath("policy"), ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(classifyConfigPath("qos/tenants"),
+              ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(classifyConfigPath("runtime_queue/max_dispatch_bytes"),
+              ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(classifyConfigPath("metrics/report_interval_seconds"),
+              ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(classifyConfigPath("max_failover_attempts"),
+              ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(classifyConfigPath("enable_auto_failover_on_poll"),
+              ConfigLifecycle::kRuntimeCandidate);
+
+    EXPECT_EQ(classifyConfigPath("unknown/value"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("policy_extra/value"),
+              ConfigLifecycle::kBootstrapOnly);
+}
+
+TEST(ConfigLifecycleTest, AllowlistedFieldOverridesBootstrapDefault) {
+    EXPECT_EQ(classifyConfigPath("transports/rdma/device/max_cqe"),
+              ConfigLifecycle::kBootstrapOnly);
+    EXPECT_EQ(classifyConfigPath("transports/rdma/enable_smart_scheduling"),
+              ConfigLifecycle::kRuntimeCandidate);
+    EXPECT_EQ(
+        classifyConfigPath("transports/rdma/enable_smart_scheduling/extra"),
+        ConfigLifecycle::kBootstrapOnly);
+}
+
+TEST(ConfigLifecycleTest, BundleViewsEnforceLifecycleBoundaries) {
+    Config config;
+    config.set("rpc_server_port", 18080);
+    config.set("merge_requests", true);
+
+    auto bundle = buildTentConfigBundle(config, 17);
+    ASSERT_NE(bundle.bootstrap, nullptr);
+    ASSERT_NE(bundle.runtime, nullptr);
+    ASSERT_NE(bundle.runtime->config, nullptr);
+
+    EXPECT_EQ(bundle.bootstrap->get("rpc_server_port", 0), 18080);
+    EXPECT_FALSE(bundle.bootstrap->contains("merge_requests"));
+    EXPECT_FALSE(bundle.bootstrap->get("merge_requests", false));
+
+    EXPECT_TRUE(bundle.runtime->config->get("merge_requests", false));
+    EXPECT_FALSE(bundle.runtime->config->contains("rpc_server_port"));
+    EXPECT_EQ(bundle.runtime->config->get("rpc_server_port", 7), 7);
+    EXPECT_EQ(bundle.runtime->generation, 17);
+}
+
+TEST(ConfigLifecycleTest, RejectsMixedLifecycleSubtreeReads) {
+    Config config;
+    ASSERT_TRUE(config
+                    .load(R"({
+                        "metrics": {
+                            "enabled": true,
+                            "report_interval_seconds": 5
+                        },
+                        "staging": {"shutdown_drain_timeout_ms": 1000},
+                        "transports": {
+                            "rdma": {
+                                "device": {"max_cqe": 4096},
+                                "strict_local_numa": true
+                            }
+                        }
+                    })")
+                    .ok());
+
+    auto bundle = buildTentConfigBundle(config);
+    const json rejected_default = {{"rejected", true}};
+    std::string subtree = "unchanged";
+
+    EXPECT_FALSE(bundle.bootstrap->contains("metrics"));
+    EXPECT_FALSE(bundle.bootstrap->dumpSubtree("metrics", &subtree));
+    EXPECT_EQ(subtree, "unchanged");
+    EXPECT_EQ(bundle.bootstrap->get<json>("transports/rdma", rejected_default),
+              rejected_default);
+
+    EXPECT_TRUE(bundle.bootstrap->get("metrics/enabled", false));
+    EXPECT_EQ(bundle.runtime->config->get("metrics/report_interval_seconds", 0),
+              5);
+    EXPECT_TRUE(bundle.runtime->config->get("transports/rdma/strict_local_numa",
+                                            false));
+
+    EXPECT_EQ(bundle.bootstrap->get<json>("staging", json::object()),
+              json({{"shutdown_drain_timeout_ms", 1000}}));
+}
+
+TEST(ConfigLifecycleTest, RejectsNoncanonicalScalarPaths) {
+    Config config;
+    config.set("merge_requests", true);
+    auto bundle = buildTentConfigBundle(config);
+
+    EXPECT_TRUE(bundle.runtime->config->get("merge_requests", false));
+    for (const auto* path : {"/merge_requests", "merge_requests/"}) {
+        SCOPED_TRACE(path);
+        EXPECT_FALSE(bundle.bootstrap->get(path, false));
+        EXPECT_FALSE(bundle.bootstrap->contains(path));
+        EXPECT_FALSE(bundle.runtime->config->get(path, false));
+        EXPECT_FALSE(bundle.runtime->config->contains(path));
+    }
+}
+
+TEST(ConfigLifecycleTest, RejectsNoncanonicalMetricsPaths) {
+    Config config;
+    config.set("metrics/enabled", true);
+    config.set("metrics/report_interval_seconds", 5);
+    auto bundle = buildTentConfigBundle(config);
+
+    for (const auto* path :
+         {"metrics/", "/metrics", "metrics//report_interval_seconds"}) {
+        SCOPED_TRACE(path);
+        std::string output = "unchanged";
+        EXPECT_FALSE(bundle.bootstrap->dumpSubtree(path, &output));
+        EXPECT_EQ(output, "unchanged");
+        EXPECT_FALSE(bundle.bootstrap->contains(path));
+        EXPECT_EQ(bundle.bootstrap->get<json>(path, json::object()),
+                  json::object());
+    }
+}
+
+TEST(ConfigLifecycleTest, RejectsRootAliasesInBothViews) {
+    Config config;
+    config.set("rpc_server_port", 18080);
+    config.set("merge_requests", true);
+    auto bundle = buildTentConfigBundle(config);
+    const LifecycleConfigView* views[] = {bundle.bootstrap.get(),
+                                          bundle.runtime->config.get()};
+
+    for (const auto* view : views) {
+        SCOPED_TRACE(configLifecycleName(view->lifecycle()));
+        for (const auto* path : {"/", "//", ""}) {
+            SCOPED_TRACE(path);
+            std::string output = "unchanged";
+            EXPECT_FALSE(view->dumpSubtree(path, &output));
+            EXPECT_EQ(output, "unchanged");
+            EXPECT_FALSE(view->contains(path));
+            EXPECT_EQ(view->get<json>(path, json::object()), json::object());
+        }
+    }
+}
+
+TEST(ConfigLifecycleTest, SnapshotDoesNotChangeWithLegacyConfig) {
+    Config config;
+    config.set("rpc_server_port", 18080);
+    config.set("merge_requests", true);
+
+    auto generation_one = buildTentConfigBundle(config, 1);
+    config.set("rpc_server_port", 28080);
+    config.set("merge_requests", false);
+    auto generation_two = buildTentConfigBundle(config, 2);
+
+    EXPECT_EQ(generation_one.bootstrap->get("rpc_server_port", 0), 18080);
+    EXPECT_TRUE(generation_one.runtime->config->get("merge_requests", false));
+    EXPECT_EQ(generation_one.runtime->generation, 1);
+
+    EXPECT_EQ(generation_two.bootstrap->get("rpc_server_port", 0), 28080);
+    EXPECT_FALSE(generation_two.runtime->config->get("merge_requests", true));
+    EXPECT_EQ(generation_two.runtime->generation, 2);
+}
+
+TEST(ConfigLifecycleTest, PreservesNestedBeforeFlatLookupCompatibility) {
+    Config config;
+    ASSERT_TRUE(config
+                    .load(R"({
+                        "metrics": {"http_port": 9100},
+                        "metrics/http_port": 9200
+                    })")
+                    .ok());
+
+    auto bundle = buildTentConfigBundle(config);
+    EXPECT_EQ(bundle.bootstrap->get("metrics/http_port", 0), 9100);
+}
+
+TEST(ConfigLifecycleTest, UnmatchedFieldsAreBootstrapOnlyWithoutDiagnostics) {
+    Config config;
+    ASSERT_TRUE(config
+                    .load(R"({
+                        "mystery": 1,
+                        "transports": {"unknown": {"enable": true}}
+                    })")
+                    .ok());
+
+    auto bundle = buildTentConfigBundle(config);
+    EXPECT_TRUE(bundle.diagnostics.empty());
+    EXPECT_EQ(bundle.bootstrap->get("mystery", 0), 1);
+    EXPECT_TRUE(bundle.bootstrap->get("transports/unknown/enable", false));
+    EXPECT_FALSE(bundle.runtime->config->contains("mystery"));
+    EXPECT_FALSE(
+        bundle.runtime->config->get("transports/unknown/enable", false));
+}
+
+TEST(ConfigLifecycleTest, ReportsNonObjectRoot) {
+    Config config;
+    ASSERT_TRUE(config.load("[]").ok());
+
+    auto bundle = buildTentConfigBundle(config);
+    ASSERT_EQ(bundle.diagnostics.size(), 1);
+    EXPECT_EQ(bundle.diagnostics[0].code, ConfigDiagnosticCode::kInvalidRoot);
+    EXPECT_EQ(bundle.diagnostics[0].path, "$");
+}
+
+TEST(ConfigLifecycleTest, DefaultConfigIsAValidEmptyConfiguration) {
+    Config config;
+
+    auto bundle = buildTentConfigBundle(config);
+    EXPECT_TRUE(bundle.diagnostics.empty());
+}
+
+TEST(ConfigLifecycleTest, AcceptsEmptyKnownObjects) {
+    Config config;
+    ASSERT_TRUE(config.load(R"({"metrics": {}, "transports": {}})").ok());
+
+    auto bundle = buildTentConfigBundle(config);
+    EXPECT_TRUE(bundle.diagnostics.empty());
+}
+
+TEST(ConfigLifecycleTest, MnnvlEgmDefaultsOffAndFollowsEnv) {
+    {
+        Config config;
+        ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+        EXPECT_FALSE(config.get("transports/mnnvl/egm", false));
+    }
+    {
+        EnvVarGuard egm_guard("MC_MNNVL_EGM", "1");
+        Config config;
+        ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+        EXPECT_TRUE(config.get("transports/mnnvl/egm", false));
+    }
+    {
+        EnvVarGuard egm_guard("MC_MNNVL_EGM", "0");
+        Config config;
+        ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+        EXPECT_FALSE(config.get("transports/mnnvl/egm", true));
+    }
+}
+
+TEST(ConfigLifecycleTest, PreservesLegacyEnvironmentPrecedence) {
+    EnvVarGuard conf_guard(
+        "MC_TENT_CONF",
+        R"({"transports":{"rdma":{"bind_address":"10.0.0.1"}}})");
+    EnvVarGuard bind_guard("MC_RDMA_BIND_ADDRESS", "10.0.0.2");
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+    auto bundle = buildTentConfigBundle(config);
+
+    EXPECT_EQ(bundle.bootstrap->get("transports/rdma/bind_address", ""),
+              "10.0.0.2");
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/delegate_rpc_test.cpp b/mooncake-transfer-engine/tent/tests/delegate_rpc_test.cpp
new file mode 100644
index 0000000000..b1de40bd0b
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/delegate_rpc_test.cpp
@@ -0,0 +1,231 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// End-to-end coverage for the Delegate RPC, which had none:
+// ControlClient::delegate -> onDelegate -> TransferEngineImpl::transferSync.
+//
+// The engine runs in p2p mode on loopback, so getSegmentName() is the address
+// to delegate to, and a FakeTransport stands in for real hardware.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <cstdlib>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/segment.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/runtime/transport.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class FakeSubBatch : public Transport::SubBatch {
+   public:
+    size_t size() const override { return task_count; }
+    size_t task_count = 0;
+    std::vector<TransferStatus> statuses;
+};
+
+// Minimal always-succeeding transport: enough for checkAvailability() and
+// resolveTransport() to pick it, and it records how many submits it saw.
+class FakeTransport : public Transport {
+   public:
+    explicit FakeTransport(TransportType self_type) : self_type_(self_type) {
+        caps.dram_to_dram = true;
+    }
+
+    std::atomic<int> submit_calls{0};
+
+    Status install(std::string&, std::shared_ptr<ControlService>,
+                   std::shared_ptr<Topology>,
+                   std::shared_ptr<Config> = nullptr) override {
+        return Status::OK();
+    }
+
+    Status allocateSubBatch(SubBatchRef& batch, size_t) override {
+        batch = new FakeSubBatch();
+        return Status::OK();
+    }
+
+    Status freeSubBatch(SubBatchRef& batch) override {
+        delete batch;
+        batch = nullptr;
+        return Status::OK();
+    }
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request>& request_list) override {
+        ++submit_calls;
+        auto* fb = static_cast<FakeSubBatch*>(batch);
+        for (const auto& req : request_list) {
+            fb->statuses.push_back({TransferStatusEnum::COMPLETED, req.length});
+            fb->task_count++;
+        }
+        return Status::OK();
+    }
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        auto* fb = static_cast<FakeSubBatch*>(batch);
+        if (task_id < 0 || task_id >= (int)fb->statuses.size())
+            return Status::InvalidArgument("bad task_id" LOC_MARK);
+        status = fb->statuses[task_id];
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(BufferDesc& desc, const MemoryOptions&) override {
+        desc.transports.push_back(self_type_);
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override {
+        for (auto& d : desc_list) {
+            auto s = addMemoryBuffer(d, options);
+            if (!s.ok()) return s;
+        }
+        return Status::OK();
+    }
+
+    Status removeMemoryBuffer(BufferDesc&) override { return Status::OK(); }
+
+    Status allocateLocalMemory(void** addr, size_t size,
+                               MemoryOptions&) override {
+        *addr = std::malloc(size);
+        if (!*addr) return Status::InternalError("malloc failed" LOC_MARK);
+        return Status::OK();
+    }
+
+    Status freeLocalMemory(void* addr, size_t) override {
+        std::free(addr);
+        return Status::OK();
+    }
+
+    bool warmupMemory(void*, size_t) override { return false; }
+
+    const char* getName() const override { return "<fake>"; }
+
+   private:
+    TransportType self_type_;
+};
+
+std::shared_ptr<Config> makeLoopbackP2PConfig() {
+    auto cfg = std::make_shared<Config>();
+    // p2p metadata keeps this self-contained: no redis/etcd/http server, and
+    // the segment name becomes 127.0.0.1:<bound port>, which is exactly the
+    // address Delegate is sent to.
+    cfg->set("metadata_type", "p2p");
+    cfg->set("metadata_servers", "");
+    cfg->set("rpc_server_hostname", "127.0.0.1");
+    cfg->set("rpc_server_port", "0");
+    cfg->set("log_level", "warning");
+    cfg->set("merge_requests", false);
+    cfg->set("transports/tcp/enable", false);
+    cfg->set("transports/shm/enable", false);
+    cfg->set("transports/rdma/enable", false);
+    cfg->set("transports/io_uring/enable", false);
+    cfg->set("transports/nvlink/enable", false);
+    cfg->set("transports/mnnvl/enable", false);
+    cfg->set("transports/gds/enable", false);
+    cfg->set("transports/ascend_direct/enable", false);
+    return cfg;
+}
+
+constexpr size_t kBufLen = 4096;
+
+class DelegateRpcTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        engine_ = std::make_unique<TransferEngineImpl>(makeLoopbackP2PConfig());
+        ASSERT_TRUE(engine_->available());
+
+        fake_ = std::make_shared<FakeTransport>(RDMA);
+        std::string seg_name = engine_->getSegmentName();
+        ASSERT_TRUE(fake_->install(seg_name, nullptr, nullptr).ok());
+        engine_->swapTransportForTest(RDMA, fake_);
+
+        buffer_.assign(kBufLen, 0xC1);
+        ASSERT_TRUE(engine_->registerLocalMemory(buffer_.data(), kBufLen).ok());
+        addr_ = engine_->getSegmentName();
+    }
+
+    void TearDown() override {
+        if (engine_)
+            (void)engine_->unregisterLocalMemory(buffer_.data(), kBufLen);
+    }
+
+    // A self-targeted WRITE: the serving node is this same engine, so the
+    // pointers carried in the request are valid there.
+    Request makeRequest() const {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = const_cast<uint8_t*>(buffer_.data());
+        req.target_id = LOCAL_SEGMENT_ID;
+        req.target_offset = reinterpret_cast<uint64_t>(buffer_.data());
+        req.length = kBufLen;
+        return req;
+    }
+
+    std::unique_ptr<TransferEngineImpl> engine_;
+    std::shared_ptr<FakeTransport> fake_;
+    std::vector<uint8_t> buffer_;
+    std::string addr_;
+};
+
+TEST_F(DelegateRpcTest, DelegatedTransferRunsOnTheServingNode) {
+    ASSERT_TRUE(ControlClient::delegate(addr_, makeRequest()).ok());
+    EXPECT_EQ(fake_->submit_calls.load(), 1)
+        << "the delegated transfer never reached the transport";
+}
+
+TEST_F(DelegateRpcTest, DelegateReportsFailureBackToTheCaller) {
+    // Nothing is registered at this address, so submitTransfer must reject it
+    // and the error has to travel back over the RPC rather than being
+    // swallowed into an OK response.
+    Request req = makeRequest();
+    req.target_offset = 0;
+    req.source = nullptr;
+    EXPECT_FALSE(ControlClient::delegate(addr_, req).ok());
+}
+
+// onDelegate is registered with offload=true, so N delegates now run on N
+// executor threads instead of being serialized by the single RPC thread. Each
+// must still get its own batch and its own correct answer.
+TEST_F(DelegateRpcTest, ConcurrentDelegatesAllSucceed) {
+    constexpr int kConcurrency = 8;
+    std::vector<std::thread> threads;
+    std::atomic<int> succeeded{0};
+    for (int i = 0; i < kConcurrency; ++i) {
+        threads.emplace_back([&] {
+            if (ControlClient::delegate(addr_, makeRequest()).ok())
+                succeeded.fetch_add(1);
+        });
+    }
+    for (auto& t : threads) t.join();
+
+    EXPECT_EQ(succeeded.load(), kConcurrency);
+    EXPECT_EQ(fake_->submit_calls.load(), kConcurrency);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/device_selector_test.cpp b/mooncake-transfer-engine/tent/tests/device_selector_test.cpp
new file mode 100644
index 0000000000..b5f5f86d2d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/device_selector_test.cpp
@@ -0,0 +1,932 @@
+// Copyright 2025 KVCache.AI
+//
+// 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.
+//
+// DeviceSelector bandwidth calibration: the per-device link speed must drive
+// the EWMA seed and clamp instead of a one-size-fits-all constant.
+
+#include "tent/transport/rdma/quota.h"
+
+#include "tent/transport/rdma/bw_arbitration.h"
+
+#include <gtest/gtest.h>
+
+#include <memory>
+#include <sstream>
+#include <utility>
+#include <algorithm>
+#include <vector>
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr int kDev = 0;
+constexpr uint64_t kMiB = 1ull << 20;
+
+std::shared_ptr<Topology> oneRdmaNic() {
+    auto topo = std::make_shared<Topology>();
+    Topology::NicEntry nic;
+    nic.name = "mlx5_0";
+    nic.type = Topology::NIC_RDMA;
+    nic.numa_node = 0;
+    topo->nic_list_.push_back(nic);
+    return topo;
+}
+
+// A selector over one RDMA NIC, with scheduling params applied the way
+// Workers does it (topology first, then params).
+std::unique_ptr<DeviceSelector> makeSelector(
+    const DeviceSelector::SchedulingParams& params = {}) {
+    auto topo = oneRdmaNic();
+    auto sel = std::make_unique<DeviceSelector>();
+    EXPECT_TRUE(sel->loadTopology(topo).ok());
+    sel->setSchedulingParams(params);
+    return sel;
+}
+
+// Feed one completion whose observed bandwidth is `bytes_per_sec`.
+void observe(DeviceSelector& sel, double bytes_per_sec) {
+    ASSERT_TRUE(sel.release(kDev, kMiB, kMiB / bytes_per_sec).ok());
+}
+
+TEST(DeviceSelectorBandwidthTest, LinkSpeedSeedsEwma) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    // 25 Gbps = 3.125 GB/s, before a single byte has moved.
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 3.125e9);
+}
+
+TEST(DeviceSelectorBandwidthTest, UnknownLinkSpeedUsesConfiguredDefault) {
+    DeviceSelector::SchedulingParams params;
+    params.default_bandwidth_gbps = 100.0;
+    auto sel = makeSelector(params);
+    // 0 = the transport could not read the port speed.
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 0.0).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 12.5e9);
+}
+
+TEST(DeviceSelectorBandwidthTest, OutOfRangeLinkSpeedUsesConfiguredDefault) {
+    DeviceSelector::SchedulingParams params;
+    params.default_bandwidth_gbps = 100.0;
+    params.min_bandwidth_gbps = 10.0;
+    params.max_bandwidth_gbps = 800.0;
+    auto sel = makeSelector(params);
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 5.0).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 12.5e9);
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 1600.0).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 12.5e9);
+}
+
+TEST(DeviceSelectorBandwidthTest, UnknownDeviceIsRejected) {
+    auto sel = makeSelector();
+    EXPECT_FALSE(sel->setDeviceBandwidth(7, 100.0).ok());
+}
+
+// The bug this file exists for: with theoretical bandwidth fixed at 400 Gbps
+// the EWMA floor was 5 GB/s everywhere, so a 25G link (3.1 GB/s measured)
+// could never learn its real rate.
+TEST(DeviceSelectorBandwidthTest, EwmaLearnsRealRateOn25GLink) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    const double measured = 3.1e9;
+    for (int i = 0; i < 64; ++i) observe(*sel, measured);
+    EXPECT_NEAR(sel->getAggregateEwmaBandwidth(), measured, measured * 0.02);
+}
+
+TEST(DeviceSelectorBandwidthTest, EwmaClampScalesWithLinkSpeed) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    // One absurd sample: the ceiling must be 10x the 25G link, not 10x 400G.
+    observe(*sel, 1e13);
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 31.25e9);
+    // And absurdly slow ones: the floor is 0.1x the 25G link.
+    observe(*sel, 1e3);
+    observe(*sel, 1e3);
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 0.3125e9);
+}
+
+// ---------------------------------------------------------------------------
+// Availability: a NIC that cannot carry traffic (context never constructed,
+// construct() failed, port down) must not be a selection candidate and must
+// not count toward the aggregate the admission queue reads.
+// ---------------------------------------------------------------------------
+
+constexpr int kDev0 = 0;
+constexpr int kDev1 = 1;
+
+// Two RDMA NICs, both rank-0 for "cpu:0".
+std::shared_ptr<Topology> twoRdmaNics() {
+    auto topo = std::make_shared<Topology>();
+    for (const char* name : {"mlx5_0", "mlx5_1"}) {
+        Topology::NicEntry nic;
+        nic.name = name;
+        nic.type = Topology::NIC_RDMA;
+        nic.numa_node = 0;
+        topo->nic_list_.push_back(nic);
+    }
+    Topology::MemEntry mem;
+    mem.name = "cpu:0";
+    mem.type = Topology::MEM_HOST;
+    mem.numa_node = 0;
+    mem.device_list[0] = {kDev0, kDev1};
+    topo->mem_list_.push_back(mem);
+    return topo;
+}
+
+std::unique_ptr<DeviceSelector> makeTwoNicSelector(
+    const DeviceSelector::SchedulingParams& params = {}) {
+    auto topo = twoRdmaNics();
+    auto sel = std::make_unique<DeviceSelector>();
+    EXPECT_TRUE(sel->loadTopology(topo).ok());
+    sel->setSchedulingParams(params);
+    EXPECT_TRUE(sel->setDeviceBandwidth(kDev0, 100.0).ok());
+    EXPECT_TRUE(sel->setDeviceBandwidth(kDev1, 100.0).ok());
+    return sel;
+}
+
+// Allocate `rounds` single-slice requests and return how many landed on each
+// device, releasing each so inflight never skews the next choice.
+std::pair<int, int> countAllocations(DeviceSelector& sel, int rounds) {
+    std::pair<int, int> hits{0, 0};
+    for (int i = 0; i < rounds; ++i) {
+        int dev = -1;
+        if (!sel.allocate(kMiB, "cpu:0", dev).ok()) continue;
+        if (dev == kDev0) ++hits.first;
+        if (dev == kDev1) ++hits.second;
+        sel.release(dev, kMiB, 0.0);
+    }
+    return hits;
+}
+
+TEST(DeviceSelectorAvailabilityTest, DevicesStartAvailable) {
+    auto sel = makeTwoNicSelector();
+    EXPECT_TRUE(sel->isDeviceAvailable(kDev0));
+    EXPECT_TRUE(sel->isDeviceAvailable(kDev1));
+    EXPECT_FALSE(sel->isDeviceAvailable(7));  // unknown device
+    EXPECT_FALSE(sel->setDeviceAvailable(7, false).ok());
+}
+
+TEST(DeviceSelectorAvailabilityTest, UnavailableDeviceLeavesAggregate) {
+    auto sel = makeTwoNicSelector();
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 25e9);
+    EXPECT_DOUBLE_EQ(sel->getAggregateTransmitBandwidth(), 25e9);
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, false).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 12.5e9);
+    // The admission queue reads this series: a dead NIC must leave it too.
+    EXPECT_DOUBLE_EQ(sel->getAggregateTransmitBandwidth(), 12.5e9);
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, true).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 25e9);
+}
+
+// getNicLoadStats() is the load signal upper layers score NICs with
+// (#2996, for #2516). A NIC that cannot carry traffic must not appear in it
+// at all: its seed is meaningless and, with zero inflight, would look like
+// the best NIC of the lot -- the same bad pick the aggregate avoids.
+TEST(DeviceSelectorAvailabilityTest, UnavailableDeviceLeavesLoadStats) {
+    auto sel = makeTwoNicSelector();
+    std::vector<NicLoadStats> stats;
+    ASSERT_TRUE(sel->getNicLoadStats(stats).ok());
+    ASSERT_EQ(stats.size(), 2u);
+
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, false).ok());
+    stats.clear();
+    ASSERT_TRUE(sel->getNicLoadStats(stats).ok());
+    ASSERT_EQ(stats.size(), 1u);
+    EXPECT_EQ(stats[0].device_name, "mlx5_0");
+
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, true).ok());
+    stats.clear();
+    ASSERT_TRUE(sel->getNicLoadStats(stats).ok());
+    EXPECT_EQ(stats.size(), 2u);
+}
+
+TEST(DeviceSelectorAvailabilityTest, UnavailableDeviceIsNeverAllocated) {
+    auto sel = makeTwoNicSelector();
+    auto both = countAllocations(*sel, 64);
+    ASSERT_GT(both.first, 0);
+    ASSERT_GT(both.second, 0);  // sanity: both are picked when available
+
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, false).ok());
+    auto smart = countAllocations(*sel, 64);
+    EXPECT_EQ(smart.first, 64);
+    EXPECT_EQ(smart.second, 0);
+
+    sel->setSmartSelection(false);  // round-robin path has its own loop
+    auto rr = countAllocations(*sel, 64);
+    EXPECT_EQ(rr.first, 64);
+    EXPECT_EQ(rr.second, 0);
+}
+
+TEST(DeviceSelectorAvailabilityTest, AllDevicesUnavailable) {
+    auto sel = makeTwoNicSelector();
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev0, false).ok());
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, false).ok());
+    int dev = -1;
+    EXPECT_FALSE(sel->allocate(kMiB, "cpu:0", dev).ok());
+    // No usable bandwidth: the admission queue must not drop on it.
+    EXPECT_LT(sel->getAggregateEwmaBandwidth(), 0.0);
+}
+
+TEST(DeviceSelectorAvailabilityTest, PriorityFallbackKeepsUnavailableOut) {
+    // Priority filtering can reject every candidate, after which
+    // buildCandidates falls back to "all devices". That fallback must still
+    // honor availability.
+    DeviceSelector::SchedulingParams params;
+    params.enable_priority_filtering = true;
+    params.local_rotation_interval_us = 0;  // fixed priorities: dev0=0, dev1=1
+    auto sel = makeTwoNicSelector(params);
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev1, false).ok());
+    // Device priorities are 0 and 1, so request priority 2 rejects both in
+    // the first pass; the fallback must then offer dev0 only.
+    for (int i = 0; i < 16; ++i) {
+        std::vector<int> dev_ids;
+        ASSERT_TRUE(sel->allocate(kMiB, 1, kMiB, "cpu:0", dev_ids, 2).ok());
+        ASSERT_EQ(dev_ids, std::vector<int>{kDev0});
+        sel->release(kDev0, kMiB, 0.0);
+    }
+    ASSERT_TRUE(sel->setDeviceAvailable(kDev0, false).ok());
+    std::vector<int> dev_ids;
+    EXPECT_FALSE(sel->allocate(kMiB, 1, kMiB, "cpu:0", dev_ids, 2).ok());
+}
+
+// The reviewer's scenario for a link that renegotiates lower: the learned
+// EWMA and the clamp derived from the old speed must both be replaced.
+TEST(DeviceSelectorBandwidthTest, ReseedOnLinkSpeedChangeReleasesStaleClamp) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 400.0).ok());
+    for (int i = 0; i < 64; ++i) observe(*sel, 45e9);
+    ASSERT_NEAR(sel->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 3.125e9);
+    for (int i = 0; i < 64; ++i) observe(*sel, 3.1e9);
+    // With the 400G clamp still in place this would sit at the 5 GB/s floor.
+    EXPECT_NEAR(sel->getAggregateEwmaBandwidth(), 3.1e9, 3.1e9 * 0.02);
+}
+
+// ---------------------------------------------------------------------------
+// The transmit estimate: the series the admission queue's deadline-drop
+// predictor and the NIC arbitration read. It is metered from bytes completed
+// over the NIC's busy time -- never from a slice's own latency, which grows
+// with the batch it travelled in -- and smoothed hard enough that one odd
+// interval cannot flip a drop decision.
+// ---------------------------------------------------------------------------
+
+constexpr uint64_t kT0 = 1'000'000'000;  // 1s in ns
+
+// A selector whose meter samples on every call and adopts each sample
+// outright, so one interval is one observation. 25 Gbps seed = 3.125 GB/s.
+std::unique_ptr<DeviceSelector> makeMeteredSelector(double alpha = 0.0) {
+    DeviceSelector::SchedulingParams params;
+    params.transmit_bandwidth_learning_rate = alpha;
+    params.transmit_meter_interval_ns = 0;  // sample whenever asked
+    auto sel = makeSelector(params);
+    EXPECT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    return sel;
+}
+
+// Drive the meter the way the RDMA workers do: `n` slices of 1 MiB are
+// posted together (one submitSlices call, one timestamp), the NIC serves
+// them at `per_slice_ns` each, and completions are polled `poll_batch` at a
+// time (one poll pass timestamps its whole group alike).
+// Returns the timestamp of the last completion, so batches can be chained
+// on a clock that only moves forward (a sample whose timestamp is not past
+// the previous one is ignored, as the meter ignores it in production).
+uint64_t runBatch(DeviceSelector& sel, uint32_t n, uint64_t per_slice_ns,
+                  uint32_t poll_batch, uint64_t t0 = kT0) {
+    for (uint32_t i = 0; i < n; ++i) sel.notePosted(kDev, kMiB, t0);
+    sel.maybeSampleTransmit(kDev, t0);  // baseline: the NIC has a backlog
+    uint32_t done = 0;
+    uint64_t poll_ts = t0;
+    while (done < n) {
+        const uint32_t group = std::min(poll_batch, n - done);
+        poll_ts = t0 + (done + group) * per_slice_ns;
+        for (uint32_t i = 0; i < group; ++i) {
+            sel.notePostEnded(kDev, kMiB, poll_ts);
+            sel.noteCompleted(kDev, kMiB);
+        }
+        done += group;
+        sel.maybeSampleTransmit(kDev, poll_ts);
+    }
+    return poll_ts;
+}
+
+// The NIC arbitration needs "bytes already charged to this NIC" as the
+// queue-ahead term of its deadline prediction.
+TEST(DeviceSelectorTransmitTest, InflightBytesPerDevice) {
+    auto topo = oneRdmaNic();
+    Topology::MemEntry mem;
+    mem.name = "cpu:0";
+    mem.type = Topology::MEM_HOST;
+    mem.numa_node = 0;
+    mem.device_list[0].push_back(kDev);
+    topo->mem_list_.push_back(mem);
+    DeviceSelector sel;
+    ASSERT_TRUE(sel.loadTopology(topo).ok());
+
+    EXPECT_EQ(sel.getInflightBytes(kDev), 0u);
+    int chosen = -1;
+    ASSERT_TRUE(sel.allocate(kMiB, "cpu:0", chosen).ok());
+    ASSERT_EQ(chosen, kDev);
+    EXPECT_EQ(sel.getInflightBytes(kDev), kMiB);
+    EXPECT_EQ(sel.getInflightBytes(7), 0u);  // unknown device
+    ASSERT_TRUE(sel.release(kDev, kMiB, 0.0).ok());
+    EXPECT_EQ(sel.getInflightBytes(kDev), 0u);
+}
+
+// Smart-mode multi-path allocation must charge each device the bytes of the
+// slices it was assigned -- the caller cuts slices as min(block, remaining),
+// and release() returns exactly that -- not ceil(total / n) per slice, which
+// would drift per device (and wrap a device that receives less than it
+// released).
+TEST(DeviceSelectorTransmitTest, MultiPathChargesActualSliceBytes) {
+    auto topo = oneRdmaNic();
+    Topology::NicEntry nic;
+    nic.name = "mlx5_1";
+    nic.type = Topology::NIC_RDMA;
+    nic.numa_node = 0;
+    topo->nic_list_.push_back(nic);
+    Topology::MemEntry mem;
+    mem.name = "cpu:0";
+    mem.type = Topology::MEM_HOST;
+    mem.numa_node = 0;
+    mem.device_list[0].push_back(0);
+    mem.device_list[0].push_back(1);
+    topo->mem_list_.push_back(mem);
+    DeviceSelector sel;
+    ASSERT_TRUE(sel.loadTopology(topo).ok());
+    DeviceSelector::SchedulingParams params;
+    params.score_jitter_range = 0.0;
+    sel.setSchedulingParams(params);
+
+    // 1,000,001 B in 64 KiB blocks: 15 full slices and one of 16,961 B;
+    // ceil(total / 16) = 62,501 would charge 1,000,016 in total.
+    constexpr uint64_t kTotal = 1'000'001;
+    constexpr uint64_t kBlock = 65536;
+    constexpr uint32_t kSlices = 16;
+    std::vector<int> ids;
+    ASSERT_TRUE(
+        sel.allocate(kTotal, kSlices, kBlock, "cpu:0", ids, PRIO_HIGH, ~0ULL)
+            .ok());
+    ASSERT_EQ(ids.size(), kSlices);
+
+    uint64_t expected[2] = {0, 0};
+    for (uint32_t i = 0; i < kSlices; ++i) {
+        ASSERT_TRUE(ids[i] == 0 || ids[i] == 1);
+        expected[ids[i]] += std::min<uint64_t>(kBlock, kTotal - i * kBlock);
+    }
+    EXPECT_EQ(sel.getInflightBytes(0), expected[0]);
+    EXPECT_EQ(sel.getInflightBytes(1), expected[1]);
+
+    for (uint32_t i = 0; i < kSlices; ++i) {
+        const uint64_t len = std::min<uint64_t>(kBlock, kTotal - i * kBlock);
+        ASSERT_TRUE(sel.release(ids[i], len, 0.0).ok());
+    }
+    EXPECT_EQ(sel.getInflightBytes(0), 0u);
+    EXPECT_EQ(sel.getInflightBytes(1), 0u);
+}
+
+// A learning rate is a weight on the old value; anything outside [0, 1]
+// makes the EWMA update meaningless, so setSchedulingParams clamps both.
+TEST(DeviceSelectorTransmitTest, LearningRatesAreClampedToUnitInterval) {
+    DeviceSelector::SchedulingParams params;
+    params.bandwidth_learning_rate = 1.5;
+    params.transmit_bandwidth_learning_rate = -0.5;
+    params.transmit_meter_interval_ns = 0;
+    auto sel = makeSelector(params);
+    EXPECT_DOUBLE_EQ(sel->getSchedulingParams().bandwidth_learning_rate, 1.0);
+    EXPECT_DOUBLE_EQ(
+        sel->getSchedulingParams().transmit_bandwidth_learning_rate, 0.0);
+
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    ASSERT_TRUE(sel->release(kDev, kMiB, kMiB / 3.1e9).ok());
+    runBatch(*sel, 1, kMiB, 1);  // one interval at 1 GB/s
+    // alpha 1.0: the selection EWMA never learns; alpha 0.0: the transmit
+    // estimate adopts each interval outright.
+    EXPECT_DOUBLE_EQ(sel->getAggregateEwmaBandwidth(), 3.125e9);
+    EXPECT_NEAR(sel->getAggregateTransmitBandwidth(), 1e9, 1.0);
+}
+
+TEST(DeviceSelectorTransmitTest, SeededFromLinkSpeed) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 3.125e9);
+    EXPECT_DOUBLE_EQ(sel->getAggregateTransmitBandwidth(), 3.125e9);
+    EXPECT_LT(sel->getTransmitBandwidth(7), 0.0);  // unknown device
+}
+
+// The point of metering bytes over time rather than timing each slice: work
+// requested together is posted with one timestamp and completed under one
+// poll timestamp, so per-slice "post to completion" grows with the batch
+// while the NIC's rate does not.
+TEST(DeviceSelectorTransmitTest, RateIsIndependentOfBatchDepth) {
+    // 1 MiB every kMiB/8 nanoseconds == 8 bytes/ns == 8 GB/s. Even the
+    // 64-slice batch then fits well inside one meter window.
+    for (uint32_t n : {1u, 8u, 64u}) {
+        for (uint32_t poll_batch : {1u, 64u}) {
+            auto sel = makeMeteredSelector();
+            runBatch(*sel, n, kMiB / 8, poll_batch);
+            EXPECT_NEAR(sel->getTransmitBandwidth(kDev), 8e9, 1.0)
+                << "n=" << n << " poll_batch=" << poll_batch;
+        }
+    }
+}
+
+// Selection and transmit answer different questions from the same traffic:
+// each MiB queues on the NIC behind earlier work as long as it spends on
+// the wire.
+TEST(DeviceSelectorTransmitTest, SelectionKeepsQueueingThatTransmitDrops) {
+    auto sel = makeMeteredSelector();
+    const double wire_s = kMiB / 1e9;
+    for (int i = 0; i < 2000; ++i)
+        ASSERT_TRUE(sel->release(kDev, kMiB, 2.0 * wire_s).ok());
+    runBatch(*sel, 8, kMiB, 8);
+    // A backed-up NIC should look slow to device selection...
+    EXPECT_NEAR(sel->getAggregateEwmaBandwidth(), 0.5e9, 0.5e9 * 0.02);
+    // ...while the deadline predictors get the rate it moves bytes at.
+    EXPECT_NEAR(sel->getAggregateTransmitBandwidth(), 1e9, 1.0);
+}
+
+// The accumulator itself: time is banked only for stretches during which
+// something was posted, and a stretch already open is not restarted.
+TEST(DeviceSelectorTransmitTest, BusyTimeCountsOnlyStretchesWithWorkPosted) {
+    auto sel = makeSelector();
+    EXPECT_EQ(sel->getBusyNs(kDev), 0u);
+
+    sel->notePosted(kDev, kMiB, kT0);
+    sel->notePosted(kDev, kMiB, kT0 + 5);      // already busy: not a restart
+    sel->notePostEnded(kDev, kMiB, kT0 + 40);  // still busy
+    EXPECT_EQ(sel->getBusyNs(kDev), 0u);       // nothing banked until idle
+    sel->notePostEnded(kDev, kMiB, kT0 + 100);
+    EXPECT_EQ(sel->getBusyNs(kDev), 100u);
+
+    // The gap to the next stretch is not counted.
+    sel->notePosted(kDev, kMiB, kT0 + 1000);
+    sel->notePostEnded(kDev, kMiB, kT0 + 1010);
+    EXPECT_EQ(sel->getBusyNs(kDev), 110u);
+}
+
+// Two workers racing on one NIC can open the next stretch before the ending
+// one is banked, leaving busy_since ahead of the timestamp closing it. Bank
+// nothing rather than an underflowed interval.
+TEST(DeviceSelectorTransmitTest, OutOfOrderTransitionBanksNothing) {
+    auto sel = makeSelector();
+    sel->notePosted(kDev, kMiB, kT0 + 500);
+    sel->notePostEnded(kDev, kMiB, kT0 + 100);
+    EXPECT_EQ(sel->getBusyNs(kDev), 0u);
+}
+
+// An interval that opens with an empty queue pair still holds a usable
+// measurement: whatever the NIC did while it had work. Only the idle part is
+// dropped, not the whole interval.
+TEST(DeviceSelectorTransmitTest, OnlyTheBusyPartOfAnIntervalIsMeasured) {
+    auto sel = makeMeteredSelector();
+    sel->maybeSampleTransmit(kDev, kT0);  // opens idle
+    // Idle for 3 * kMiB ns, then 1 MiB moved in kMiB ns: 1 byte/ns.
+    sel->notePosted(kDev, kMiB, kT0 + 3 * kMiB);
+    sel->notePostEnded(kDev, kMiB, kT0 + 4 * kMiB);
+    sel->noteCompleted(kDev, kMiB);
+    sel->maybeSampleTransmit(kDev, kT0 + 4 * kMiB);
+    EXPECT_NEAR(sel->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// A sample spanning more wall time than transmit_meter_max_interval_ns is
+// dropped whatever its busy time says: the link it describes is too old to
+// attribute to the link as it is now.
+TEST(DeviceSelectorTransmitTest, StaleIntervalsAreNotSamples) {
+    auto sel = makeMeteredSelector();
+    sel->notePosted(kDev, kMiB, kT0);
+    sel->maybeSampleTransmit(kDev, kT0);
+    sel->notePostEnded(kDev, kMiB, kT0 + 1'000'000'000);
+    sel->noteCompleted(kDev, kMiB);
+    sel->maybeSampleTransmit(kDev, kT0 + 1'000'000'000);
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 3.125e9);
+}
+
+TEST(DeviceSelectorTransmitTest, MeterHonoursItsInterval) {
+    DeviceSelector::SchedulingParams params;
+    params.transmit_bandwidth_learning_rate = 0.0;
+    auto sel = makeSelector(params);  // default 10 ms interval
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+
+    sel->notePosted(kDev, 64 * kMiB, kT0);
+    sel->maybeSampleTransmit(kDev, kT0);
+    sel->noteCompleted(kDev, kMiB);
+    sel->maybeSampleTransmit(kDev, kT0 + 1'000'000);  // 1 ms: too soon
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 3.125e9);
+    sel->maybeSampleTransmit(kDev, kT0 + 10'000'000);  // 10 ms: sampled
+    EXPECT_NE(sel->getTransmitBandwidth(kDev), 3.125e9);
+}
+
+// One fast interval is one observation among many, not the new estimate.
+TEST(DeviceSelectorTransmitTest, SmoothsSingleOutlier) {
+    auto sel = makeMeteredSelector(0.9);  // the shipped learning rate
+    uint64_t t = kT0;
+    for (int i = 0; i < 200; ++i) t = runBatch(*sel, 8, kMiB, 8, t);
+    ASSERT_NEAR(sel->getTransmitBandwidth(kDev), 1e9, 1e9 * 0.02);
+
+    // An interval that moved 30x as fast moves the estimate by ~(1 - alpha).
+    sel->notePosted(kDev, kMiB, t);
+    sel->maybeSampleTransmit(kDev, t);
+    sel->notePostEnded(kDev, kMiB, t + kMiB / 30);
+    sel->noteCompleted(kDev, kMiB);
+    sel->maybeSampleTransmit(kDev, t + kMiB / 30);
+    EXPECT_LT(sel->getTransmitBandwidth(kDev), 5e9);
+    EXPECT_GT(sel->getTransmitBandwidth(kDev), 3e9);
+}
+
+// release() feeds the selection EWMA only; the transmit estimate has one
+// source, the meter.
+TEST(DeviceSelectorTransmitTest, ReleaseDoesNotFeedTheTransmitEstimate) {
+    auto sel = makeSelector();
+    ASSERT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    ASSERT_TRUE(sel->release(kDev, kMiB, kMiB / 1e9).ok());
+    EXPECT_NE(sel->getAggregateEwmaBandwidth(), 3.125e9);
+    EXPECT_DOUBLE_EQ(sel->getAggregateTransmitBandwidth(), 3.125e9);
+}
+
+TEST(DeviceSelectorTransmitTest, ClampScalesWithLinkSpeed) {
+    auto sel = makeMeteredSelector();
+    // 1 MiB in a nanosecond: capped at 10x the 3.125 GB/s link rate.
+    runBatch(*sel, 1, 1, 1);
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 31.25e9);
+    // 1 MiB in 40 ms: floored at 0.1x.
+    sel->notePosted(kDev, kMiB, kT0 + 1);
+    sel->maybeSampleTransmit(kDev, kT0 + 1);
+    sel->notePostEnded(kDev, kMiB, kT0 + 1 + 40'000'000);
+    sel->noteCompleted(kDev, kMiB);
+    sel->maybeSampleTransmit(kDev, kT0 + 1 + 40'000'000);
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 0.3125e9);
+}
+
+// ---------------------------------------------------------------------------
+// How closely the meter recovers a NIC's real rate in the SHIPPED
+// configuration -- 10 ms interval, alpha 0.9 -- rather than the
+// one-sample-per-call setup the mechanism tests above use. Each records the
+// figure it measured and pins it with a bound just above it, so a change in
+// what the meter is worth as a number shows up here rather than in
+// production. Every figure is the worst of ten readings taken over
+// successive stretches of the same traffic, not the value one run happened
+// to stop on.
+//
+//   steady 8 GB/s, polled 1, 16 or 64     4.8e-16, the last bit of a double
+//   steady 8 GB/s, 64 MiB slices          7.0e-13   (slice size cancels)
+//   steady 2 GB/s, polled 16 deep         5.8e-13   (one pass fills most of
+//                                                    a meter interval)
+//   bursty 4/12 GB/s, mean 8              1.2%      (the swing between the
+//                                                    halves, not an offset)
+//   21% duty cycle, 16 MiB per 10 ms      6.0e-16   (was -78% before the
+//                                                    meter charged busy time)
+//   8 -> 2 GB/s renegotiation             within 5% after 478 ms
+//   a real 50 GB/s wire                   pinned at 31.25 GB/s, the clamp
+//
+// Once the sample is taken at the end of a poll pass, how deep the polling
+// is does not enter the steady-state error at all. What it does change is
+// how often a sample can be taken, and therefore how fast the estimate
+// follows a change -- which is what the renegotiation figure measures.
+// ---------------------------------------------------------------------------
+
+// Default scheduling params (10 ms meter interval, alpha 0.9, 50 ms staleness
+// cut-off) over a 25 Gbps link: seed and clamp centre are 3.125 GB/s.
+std::unique_ptr<DeviceSelector> shippedSelector() {
+    auto sel = makeSelector();
+    EXPECT_TRUE(sel->setDeviceBandwidth(kDev, 25.0).ok());
+    return sel;
+}
+
+// A NIC transmitting steadily at `bytes_per_ns`, driven the way
+// handleCompletion drives the meter: a slice leaves the wire every
+// slice/rate nanoseconds, one poll pass picks up `poll_batch` of them and
+// stamps the whole group with a single timestamp, each completion offers the
+// meter a sample, and the queue pair is refilled so the NIC never goes idle.
+// Returns the estimate after `duration_ns` of traffic.
+double runWire(DeviceSelector& sel, double bytes_per_ns, uint64_t slice,
+               uint64_t poll_batch, uint64_t duration_ns, uint64_t& clock) {
+    const uint64_t per_slice_ns = static_cast<uint64_t>(slice / bytes_per_ns);
+    // Whole slices only, and the clock is advanced by exactly what was
+    // driven: a stretch left over at the end would be busy time with no
+    // completions in it, which is the harness lying to the meter rather
+    // than the meter being wrong.
+    const uint64_t n = duration_ns / per_slice_ns;
+    const uint64_t start_ns = clock;
+    for (uint64_t i = 0; i < poll_batch; ++i)
+        sel.notePosted(kDev, slice, start_ns);
+    sel.maybeSampleTransmit(kDev, start_ns);  // open an interval, NIC busy
+
+    uint64_t done = 0;
+    while (done < n) {
+        const uint64_t group = std::min<uint64_t>(poll_batch, n - done);
+        // One poll pass timestamps everything it reaps alike.
+        const uint64_t poll_ts = start_ns + (done + group) * per_slice_ns;
+        for (uint64_t i = 0; i < group; ++i) {
+            sel.notePostEnded(kDev, slice, poll_ts);
+            sel.noteCompleted(kDev, slice);
+            // Refill: the queue pair never drains, so the NIC stays busy.
+            sel.notePosted(kDev, slice, poll_ts);
+        }
+        sel.maybeSampleTransmit(kDev, poll_ts);  // once per pass, at its end
+        done += group;
+    }
+    clock = start_ns + n * per_slice_ns;
+    return sel.getTransmitBandwidth(kDev);
+}
+
+double relErr(double got, double want) { return std::abs(got - want) / want; }
+
+// The worst reading in a run, and where the readings sat. Each scenario is
+// judged over many meter intervals rather than at one endpoint: an estimate
+// that lands on the right number once but wanders between samples is not
+// worth what the deadline predictors spend it on.
+struct Spread {
+    double worst_rel_err = 0.0;
+    double lo = 0.0;
+    double hi = 0.0;
+
+    void add(double got, double want) {
+        if (lo == 0.0 || got < lo) lo = got;
+        if (got > hi) hi = got;
+        worst_rel_err = std::max(worst_rel_err, relErr(got, want));
+    }
+    std::string str() const {
+        std::ostringstream out;
+        out.precision(3);
+        out << "lo=" << std::fixed << lo << " hi=" << hi << std::scientific
+            << " worst_rel_err=" << worst_rel_err;
+        return out.str();
+    }
+};
+
+// A wire held at exactly 8 GB/s. Both ends of every meter interval are
+// completion timestamps, so each window measures the rate over a whole
+// number of slices -- there is no partial slice to misattribute, and the
+// EWMA of a constant is that constant. The residual is the poll group split
+// across an interval boundary, and it is ~1e-6 even at the deepest polling.
+TEST(DeviceSelectorTransmitAccuracyTest, SteadyRateIsRecovered) {
+    // Long enough for the seed to have washed out of the EWMA at every one
+    // of these depths: the deeper the polling the fewer samples a second of
+    // traffic offers, so a shorter warm-up leaves the shallowest converged
+    // and the deepest still on its way, which is a difference in how fast
+    // the estimate moves and not in what it settles on.
+    constexpr uint64_t kWarmUp = 8'000'000'000ull;
+    constexpr uint64_t kChunk = 200'000'000ull;  // ~20 meter intervals each
+    for (uint64_t poll_batch : {1ull, 16ull, 64ull}) {
+        auto sel = shippedSelector();
+        uint64_t at = kT0;
+        runWire(*sel, 8.0, kMiB, poll_batch, kWarmUp, at);
+        Spread spread;
+        for (int chunk = 0; chunk < 10; ++chunk)
+            spread.add(runWire(*sel, 8.0, kMiB, poll_batch, kChunk, at), 8e9);
+        RecordProperty("poll_batch_" + std::to_string(poll_batch),
+                       spread.str());
+        EXPECT_LT(spread.worst_rel_err, 1e-12)
+            << "poll_batch=" << poll_batch << " lo=" << spread.lo
+            << " hi=" << spread.hi;
+    }
+}
+
+// Slice size does not enter the error. 64 MiB slices leave barely one
+// completion per interval, but since an interval can only begin and end on a
+// completion, the window still holds whole slices: no phase error to average
+// out. This is what makes the estimate independent of how the caller carved
+// its transfer up.
+TEST(DeviceSelectorTransmitAccuracyTest, SliceSizeDoesNotSkewTheEstimate) {
+    auto sel = shippedSelector();  // 8 GB/s, an interval holds 76 MiB
+    uint64_t at = kT0;
+    runWire(*sel, 8.0, 64 * kMiB, 1, 4'000'000'000ull, at);
+    Spread spread;
+    for (int chunk = 0; chunk < 10; ++chunk)
+        spread.add(runWire(*sel, 8.0, 64 * kMiB, 1, 400'000'000ull, at), 8e9);
+    RecordProperty("estimate", spread.str());
+    EXPECT_LT(spread.worst_rel_err, 1e-9)
+        << "lo=" << spread.lo << " hi=" << spread.hi;
+}
+
+// The realistic case: the wire does not hold one rate. Alternating 5 ms
+// bursts of 4 and 12 GB/s carry the same bytes per 10 ms as a steady 8 GB/s
+// link, and each burst is short enough to fall inside a meter window. What
+// the estimate has to recover is the mean, not the burst it last saw.
+TEST(DeviceSelectorTransmitAccuracyTest, BurstyWireConvergesOnItsMean) {
+    auto sel = shippedSelector();
+    uint64_t at = kT0;
+    Spread spread;
+    for (int i = 0; i < 1200; ++i) {
+        runWire(*sel, (i % 2) ? 12.0 : 4.0, kMiB, 8, 5'000'000ull, at);
+        // Read it back on every burst boundary past the warm-up, so the
+        // swing between the fast and the slow half is inside the bound and
+        // not just the endpoint the run happens to stop on.
+        if (i >= 400) spread.add(sel->getTransmitBandwidth(kDev), 8e9);
+    }
+    RecordProperty("estimate", spread.str());
+    EXPECT_LT(spread.worst_rel_err, 0.015)
+        << "lo=" << spread.lo << " hi=" << spread.hi;
+}
+
+// A link that renegotiates down to a quarter of its rate. alpha 0.9 closes
+// 10% of the gap per SAMPLE, and ~39 samples are needed to get within 5%.
+// What that costs in wall time is set by how often a sample can be taken,
+// which is not the 10 ms interval but the poll rhythm: a sample only lands
+// on a completion timestamp, so the effective interval here is the first
+// poll pass at or after 10 ms. This measures the window in which the
+// admission queue's drop predicate still believes the old, faster link.
+TEST(DeviceSelectorTransmitAccuracyTest, FollowsALinkThatSlowsDown) {
+    auto sel = shippedSelector();
+    uint64_t at = kT0;
+    // Polled four at a time, so one pass is a fifth of a meter interval and
+    // the coarse-polling bias below stays out of the measurement.
+    ASSERT_LT(relErr(runWire(*sel, 8.0, kMiB, 4, 2'000'000'000ull, at), 8e9),
+              0.02);
+
+    constexpr uint64_t kStep = 10'000'000ull;  // 10 ms of traffic per step
+    const uint64_t slowdown_at = at;
+    while (relErr(sel->getTransmitBandwidth(kDev), 2e9) > 0.05 &&
+           at - slowdown_at < 5'000'000'000ull) {
+        runWire(*sel, 2.0, kMiB, 4, kStep, at);
+    }
+    const uint64_t elapsed_ns = at - slowdown_at;
+    RecordProperty("ms_to_within_5pct", std::to_string(elapsed_ns / 1'000'000));
+    // Both ends matter: too slow and the drop predicate believes the old
+    // link for longer, too fast and one odd interval could flip it.
+    EXPECT_GT(elapsed_ns, 300'000'000ull) << "ms=" << elapsed_ns / 1'000'000;
+    EXPECT_LT(elapsed_ns, 700'000'000ull) << "ms=" << elapsed_ns / 1'000'000;
+}
+
+// Nothing calls the meter while a NIC is idle: handleCompletion is its only
+// caller. A workload that bursts and then waits therefore does not close an
+// interval at the end of its burst -- it closes it at the NEXT burst, with
+// the idle gap inside the elapsed time. Drives only completions, the way
+// production does.
+double runDutyCycle(DeviceSelector& sel, double bytes_per_ns, uint64_t slice,
+                    uint64_t burst_slices, uint64_t period_ns, int bursts,
+                    uint64_t start_ns = kT0) {
+    const uint64_t per_slice_ns = static_cast<uint64_t>(slice / bytes_per_ns);
+    uint64_t at = start_ns;
+    for (int b = 0; b < bursts; ++b) {
+        for (uint64_t i = 0; i < burst_slices; ++i)
+            sel.notePosted(kDev, slice, at);
+        for (uint64_t i = 0; i < burst_slices; ++i) {
+            // One completion per poll pass here: the bursts are what is
+            // being measured, not the polling.
+            const uint64_t done_ts = at + (i + 1) * per_slice_ns;
+            sel.notePostEnded(kDev, slice, done_ts);
+            sel.noteCompleted(kDev, slice);
+            sel.maybeSampleTransmit(kDev, done_ts);
+        }
+        at += period_ns;
+    }
+    return sel.getTransmitBandwidth(kDev);
+}
+
+// A NIC that bursts and then waits. The gap between bursts is not the link
+// being slow, it is the link having nothing to do, so only the time the NIC
+// actually held work may be charged for the bytes it moved. Metered against
+// elapsed time this read 1.68 GB/s -- the period average, 4.8x below the
+// wire -- and the admission layer's absolute drop threshold was wrong by
+// that factor.
+TEST(DeviceSelectorTransmitAccuracyTest, IdleTimeIsNotChargedToTheLink) {
+    auto sel = shippedSelector();
+    // 16 MiB at 8 GB/s == 2 ms of wire time every 10 ms: 21% duty cycle.
+    uint64_t at = kT0;
+    runDutyCycle(*sel, 8.0, kMiB, 16, 10'000'000ull, 400, at);
+    at += 400ull * 10'000'000ull;
+    Spread spread;
+    for (int chunk = 0; chunk < 20; ++chunk) {
+        spread.add(runDutyCycle(*sel, 8.0, kMiB, 16, 10'000'000ull, 20, at),
+                   8e9);
+        at += 20ull * 10'000'000ull;
+    }
+    RecordProperty("estimate", spread.str());
+    EXPECT_LT(spread.worst_rel_err, 1e-6)
+        << "lo=" << spread.lo << " hi=" << spread.hi;
+}
+
+// Widen the gap past transmit_meter_max_interval_ns and the same workload is
+// rejected instead: the estimate keeps its seed. The protection is a cliff at
+// 50 ms, not a correction.
+TEST(DeviceSelectorTransmitAccuracyTest, DutyCyclePastTheCutOffIsRejected) {
+    auto sel = shippedSelector();
+    const double got = runDutyCycle(*sel, 8.0, kMiB, 16, 60'000'000ull, 100);
+    RecordProperty("estimate", std::to_string(got));
+    EXPECT_DOUBLE_EQ(got, 3.125e9);  // the 25 Gbps seed, never updated
+}
+
+// The ordering half of the estimate's job is immune to all of this: one
+// arbitration call scores every contender against the same bw, so scaling it
+// scales every MLU alike and the order is unchanged. Only the admission
+// layer's absolute threshold can be moved by a wrong rate.
+TEST(DeviceSelectorTransmitAccuracyTest, OrderingIsUnaffectedByARateError) {
+    const std::vector<ArbFlow> flows{
+        {kT0 + 40, 16}, {kT0 + 10, 8}, {kT0 + 80, 64}};
+    const auto truth = OrderByUrgency(flows, kT0, 8e9, 1024);
+    for (double wrong : {8e9 / 5, 8e9 / 2, 8e9 * 3}) {
+        EXPECT_EQ(OrderByUrgency(flows, kT0, wrong, 1024), truth)
+            << "bw=" << wrong;
+    }
+}
+
+// The worst case for the poll cadence: sixteen 1 MiB slices at 2 GB/s put one
+// pass at 8.4 ms against a 10 ms meter interval, so almost every interval
+// ends on the pass that fills it. Taking the sample at the end of a pass
+// rather than partway through is what makes this exact -- sampled from inside
+// a pass, the interval that closed lost the rest of the pass's bytes and the
+// next one got them for free, and since the estimate averages per-interval
+// rates over intervals of unequal length the two did not cancel: this read 8%
+// high and a 4x slowdown never converged at all.
+TEST(DeviceSelectorTransmitAccuracyTest, CoarsePollingDoesNotSkewTheEstimate) {
+    auto sel = shippedSelector();
+    uint64_t at = kT0;
+    runWire(*sel, 2.0, kMiB, 16, 4'000'000'000ull, at);
+    Spread spread;
+    for (int chunk = 0; chunk < 10; ++chunk)
+        spread.add(runWire(*sel, 2.0, kMiB, 16, 400'000'000ull, at), 2e9);
+    RecordProperty("estimate", spread.str());
+    EXPECT_LT(spread.worst_rel_err, 1e-9)
+        << "lo=" << spread.lo << " hi=" << spread.hi;
+}
+
+// The clamp is the hard ceiling on what can be measured at all: a link whose
+// real rate is more than ewma_max_multiplier times the seed reads as the
+// clamp, not as itself. Reachable when the seed came from
+// default_bandwidth_gbps because the port speed could not be read.
+TEST(DeviceSelectorTransmitAccuracyTest, RateAboveTheClampIsNotMeasurable) {
+    auto sel = shippedSelector();  // seed 3.125 GB/s, ceiling 31.25 GB/s
+    uint64_t at = kT0;
+    for (int chunk = 0; chunk < 10; ++chunk) {
+        const double got = runWire(*sel, 50.0, kMiB, 16, 200'000'000ull, at);
+        // Pinned at 10x, not the real 50 GB/s, and it stays pinned: more
+        // intervals of the same evidence never lift it past the clamp.
+        EXPECT_DOUBLE_EQ(got, 31.25e9) << "chunk=" << chunk;
+    }
+    RecordProperty("estimate", std::to_string(sel->getTransmitBandwidth(kDev)));
+}
+
+// A reset abandons the interval in progress without learning from it; the
+// sample after it rebuilds both baselines from scratch, so the bytes and
+// busy time it eventually divides come from the same window.
+TEST(DeviceSelectorTransmitTest, ResetStartsTheNextIntervalFresh) {
+    auto sel = makeMeteredSelector();
+    sel->notePosted(kDev, 2 * kMiB, kT0);  // one busy stretch, two slices
+    sel->maybeSampleTransmit(kDev, kT0);   // baseline
+    sel->noteCompleted(kDev, kMiB);
+    sel->resetTransmitMeter(kDev);
+    // Rebuilds the baselines (1 MiB done, 1 MiB ns busy) and learns nothing.
+    sel->maybeSampleTransmit(kDev, kT0 + kMiB);
+    EXPECT_DOUBLE_EQ(sel->getTransmitBandwidth(kDev), 3.125e9);
+    sel->noteCompleted(kDev, kMiB);
+    sel->notePostEnded(kDev, 2 * kMiB, kT0 + 2 * kMiB);
+    // 1 MiB over the 1 MiB ns of busy time since those baselines: 1 GB/s.
+    sel->maybeSampleTransmit(kDev, kT0 + 2 * kMiB);
+    EXPECT_NEAR(sel->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// The padding after each hot counter is only worth anything if the struct
+// itself starts on a cache line; otherwise two lanes' posts and completions
+// contend on the same line.
+TEST(DeviceSelectorLayoutTest, HotCountersSitOnTheirOwnCacheLines) {
+    DeviceSelector::DeviceInfo info;
+    const auto base = reinterpret_cast<uintptr_t>(&info);
+    auto line_of = [&](const void* p) {
+        return (reinterpret_cast<uintptr_t>(p) - base) / 64;
+    };
+    EXPECT_EQ(alignof(DeviceSelector::DeviceInfo), 64u);
+    EXPECT_EQ(sizeof(DeviceSelector::DeviceInfo) % 64, 0u);
+    const std::vector<const void*> hot = {
+        &info.inflight_bytes, &info.ewma_bandwidth_bps, &info.ewma_transmit_bps,
+        &info.total_bytes,    &info.posted_bytes,       &info.completed_bytes,
+        &info.meter_ts};
+    for (size_t i = 0; i < hot.size(); ++i) {
+        EXPECT_EQ((reinterpret_cast<uintptr_t>(hot[i]) - base) % 64, 0u)
+            << "field " << i;
+        for (size_t j = i + 1; j < hot.size(); ++j)
+            EXPECT_NE(line_of(hot[i]), line_of(hot[j])) << i << " vs " << j;
+    }
+}
+
+// The NIC's posted backlog is what a slice about to be posted waits behind:
+// charged when a WR reaches the hardware, returned when it leaves.
+TEST(DeviceSelectorTransmitTest, PostedBytesTrackTheHardwareBacklog) {
+    auto sel = makeSelector();
+    EXPECT_EQ(sel->getPostedBytes(kDev), 0u);
+    sel->notePosted(kDev, kMiB, kT0);
+    sel->notePosted(kDev, kMiB, kT0);
+    EXPECT_EQ(sel->getPostedBytes(kDev), 2 * kMiB);
+    sel->notePostEnded(kDev, kMiB, kT0);
+    EXPECT_EQ(sel->getPostedBytes(kDev), kMiB);
+    sel->notePostEnded(kDev, kMiB, kT0);
+    EXPECT_EQ(sel->getPostedBytes(kDev), 0u);
+    EXPECT_EQ(sel->getPostedBytes(7), 0u);  // unknown device
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/endpoint_lifecycle_test.cpp b/mooncake-transfer-engine/tent/tests/endpoint_lifecycle_test.cpp
index 3243203811..42d3b8a25f 100644
--- a/mooncake-transfer-engine/tent/tests/endpoint_lifecycle_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/endpoint_lifecycle_test.cpp
@@ -14,7 +14,10 @@
 
 #include <gtest/gtest.h>
 
+#include <cstdint>
 #include <memory>
+#include <string>
+#include <vector>
 
 #include "tent/common/utils/string_builder.h"
 #include "tent/transport/rdma/endpoint.h"
@@ -37,6 +40,46 @@ class EndpointTestAccess {
         endpoint.status_.store(RdmaEndPoint::EP_READY,
                                std::memory_order_relaxed);
     }
+
+    static void markNotifyConnected(RdmaEndPoint& endpoint) {
+        endpoint.notify_connected_.store(true, std::memory_order_relaxed);
+    }
+
+    static void beginDestroy(RdmaEndPoint& endpoint) {
+        endpoint.beginDestroy();
+    }
+
+    // Stands in for notification WRs posted on the notify QP whose
+    // completions the worker has not polled yet.
+    static void setNotifyInflight(RdmaEndPoint& endpoint, uint32_t count) {
+        endpoint.notify_inflight_.store(count, std::memory_order_release);
+    }
+
+    static bool notifyConnected(const RdmaEndPoint& endpoint) {
+        return endpoint.notify_connected_.load(std::memory_order_relaxed);
+    }
+
+    static constexpr size_t notifyBufferSize() {
+        return RdmaEndPoint::kNotifyBufferSize;
+    }
+
+    static constexpr size_t notifyMaxPendingSends() {
+        return RdmaEndPoint::kNotifyMaxPendingSends;
+    }
+
+    static char* notifySlotPtr(char* base, size_t idx) {
+        return RdmaEndPoint::notifySlotPtr(base, idx);
+    }
+
+    static bool encodeNotifyPayload(char* slot, const std::string& name,
+                                    const std::string& msg, uint32_t* out_len) {
+        return RdmaEndPoint::encodeNotifyPayload(slot, name, msg, out_len);
+    }
+
+    static bool decodeNotifyPayload(const char* data, size_t byte_len,
+                                    std::string* name, std::string* msg) {
+        return RdmaEndPoint::decodeNotifyPayload(data, byte_len, name, msg);
+    }
 };
 
 namespace {
@@ -105,6 +148,152 @@ TEST(EndpointLifecycleTest, NotificationFailsWhenEndpointIsNotConnected) {
     EXPECT_FALSE(endpoint.sendNotification("name", "message"));
 }
 
+TEST(EndpointLifecycleTest, NotifySlotsAreAdjacentAndNonOverlapping) {
+    std::vector<char> buf(EndpointTestAccess::notifyMaxPendingSends() *
+                          EndpointTestAccess::notifyBufferSize());
+    char* slot0 = EndpointTestAccess::notifySlotPtr(buf.data(), 0);
+    char* slot1 = EndpointTestAccess::notifySlotPtr(buf.data(), 1);
+    char* last = EndpointTestAccess::notifySlotPtr(
+        buf.data(), EndpointTestAccess::notifyMaxPendingSends() - 1);
+    EXPECT_EQ(slot0, buf.data());
+    EXPECT_EQ(static_cast<size_t>(slot1 - slot0),
+              EndpointTestAccess::notifyBufferSize());
+    EXPECT_EQ(static_cast<size_t>(last - slot0),
+              (EndpointTestAccess::notifyMaxPendingSends() - 1) *
+                  EndpointTestAccess::notifyBufferSize());
+    EXPECT_EQ(last + EndpointTestAccess::notifyBufferSize(),
+              buf.data() + buf.size());
+}
+
+TEST(EndpointLifecycleTest, NotifyAdjacentSlotsDoNotCrosstalk) {
+    // Recv used to be 256 independent vectors. After coalescing, a wrong
+    // offset would mix payload from a neighbor slot.
+    const size_t slot_size = EndpointTestAccess::notifyBufferSize();
+    const size_t nslots = EndpointTestAccess::notifyMaxPendingSends();
+    std::vector<char> buf(nslots * slot_size, '\xee');
+    const size_t indices[] = {0, 1, 2, 127, 254, 255};
+    uint32_t encoded[6] = {};
+    for (size_t i = 0; i < 6; ++i) {
+        const size_t idx = indices[i];
+        std::string name = "n" + std::to_string(idx);
+        std::string msg =
+            "payload-" + std::to_string(idx) + std::string(2048, 'x');
+        ASSERT_TRUE(EndpointTestAccess::encodeNotifyPayload(
+            EndpointTestAccess::notifySlotPtr(buf.data(), idx), name, msg,
+            &encoded[i]));
+        ASSERT_GT(encoded[i], 8u);
+        ASSERT_LE(encoded[i], slot_size);
+    }
+    for (size_t i = 0; i < 6; ++i) {
+        const size_t idx = indices[i];
+        std::string name;
+        std::string msg;
+        ASSERT_TRUE(EndpointTestAccess::decodeNotifyPayload(
+            EndpointTestAccess::notifySlotPtr(buf.data(), idx), encoded[i],
+            &name, &msg))
+            << "slot " << idx;
+        EXPECT_EQ(name, "n" + std::to_string(idx));
+        EXPECT_EQ(msg,
+                  "payload-" + std::to_string(idx) + std::string(2048, 'x'));
+        // Trailing bytes in the 64KiB slot stay the fill pattern, so a
+        // too-long read would have picked up 0xee as name_len.
+        ASSERT_TRUE(EndpointTestAccess::decodeNotifyPayload(
+            EndpointTestAccess::notifySlotPtr(buf.data(), idx), slot_size,
+            &name, &msg));
+        EXPECT_EQ(name, "n" + std::to_string(idx));
+    }
+    // Slot 3 was never written; decoding the fill pattern must fail rather
+    // than returning a neighbor's payload.
+    std::string name;
+    std::string msg;
+    EXPECT_FALSE(EndpointTestAccess::decodeNotifyPayload(
+        EndpointTestAccess::notifySlotPtr(buf.data(), 3), slot_size, &name,
+        &msg));
+}
+
+TEST(EndpointLifecycleTest, NotifyPayloadRejectedWhenLargerThanSlot) {
+    std::vector<char> slot(EndpointTestAccess::notifyBufferSize());
+    uint32_t encoded = 0;
+    std::string too_big(EndpointTestAccess::notifyBufferSize(), 'z');
+    EXPECT_FALSE(EndpointTestAccess::encodeNotifyPayload(slot.data(), "n",
+                                                         too_big, &encoded));
+}
+
+// The notify QP must take its path and retry attributes from EndPointParams
+// like the data QPs do (setupOneQP), not from hard-coded tutorial values:
+// with timeout=0x12 and retry_cnt=7 a dead peer path took ~8.6 s to report
+// on the notify QP while the data QPs of the same endpoint gave up in ~0.5 s,
+// and no configuration could change that.
+TEST(EndpointLifecycleTest, NotifyQpAttrsFollowEndpointParams) {
+    EndPointParams params;
+    params.path_mtu = IBV_MTU_1024;
+    params.min_rnr_timer = 5;
+    params.send_timeout = 20;
+    params.send_retry_count = 3;
+    params.send_rnr_count = 2;
+
+    const NotifyQpRtrAttrs rtr = buildNotifyQpRtrAttrs(params);
+    EXPECT_EQ(rtr.path_mtu, IBV_MTU_1024);
+    EXPECT_EQ(rtr.min_rnr_timer, 5);
+    // SEND/RECV only: one outstanding read/atomic, independent of the
+    // data-QP setting.
+    EXPECT_EQ(rtr.max_dest_rd_atomic, 1);
+
+    const NotifyQpRtsAttrs rts = buildNotifyQpRtsAttrs(params);
+    EXPECT_EQ(rts.timeout, 20);
+    EXPECT_EQ(rts.retry_cnt, 3);
+    // rnr_retry is pinned: RNR NAKs are flow control on the notify QP, not
+    // a fault, so send_rnr_count (2 above) must not reach it.
+    EXPECT_EQ(rts.rnr_retry, 7);
+    EXPECT_EQ(rts.max_rd_atomic, 1);
+}
+
+// With default EndPointParams the notify QP gets the data QPs' budget:
+// timeout 14 (4.096us * 2^14 ~= 67 ms per attempt), 7 retries and the
+// 0.64 ms RNR timer, plus the pinned unbounded RNR retry. The notify QP
+// follows these defaults now, so a change to them must show up here as a
+// deliberate decision.
+TEST(EndpointLifecycleTest, NotifyQpAttrsDefaultsMatchDataQp) {
+    EndPointParams defaults;
+    const NotifyQpRtrAttrs rtr = buildNotifyQpRtrAttrs(defaults);
+    EXPECT_EQ(rtr.path_mtu, IBV_MTU_4096);
+    EXPECT_EQ(rtr.min_rnr_timer, 12);
+    const NotifyQpRtsAttrs rts = buildNotifyQpRtsAttrs(defaults);
+    EXPECT_EQ(rts.timeout, 14);
+    EXPECT_EQ(rts.retry_cnt, 7);
+    EXPECT_EQ(rts.rnr_retry, 7);
+}
+
+TEST(EndpointLifecycleTest, NotifyLocalFaultKeepsEndpointServingData) {
+    // A fault confined to the notify QP must not retire the endpoint: doing so
+    // moves every data QP to ERR and flushes in-flight transfers.
+    RdmaEndPoint endpoint;
+    EndpointTestAccess::markConnected(endpoint, "10.0.0.1:12345", "mlx5_0",
+                                      {100, 101});
+    EndpointTestAccess::markNotifyConnected(endpoint);
+
+    endpoint.disableNotification("notify QP local completion error");
+
+    EXPECT_EQ(endpoint.status(), RdmaEndPoint::EP_READY);
+    EXPECT_FALSE(EndpointTestAccess::notifyConnected(endpoint));
+    // The caller now learns notifications are gone instead of silently posting
+    // to a dead QP.
+    EXPECT_FALSE(endpoint.sendNotification("name", "message"));
+}
+
+TEST(EndpointLifecycleTest, DisableNotificationIsIdempotent) {
+    RdmaEndPoint endpoint;
+    EndpointTestAccess::markConnected(endpoint, "10.0.0.1:12345", "mlx5_0",
+                                      {100, 101});
+    EndpointTestAccess::markNotifyConnected(endpoint);
+
+    endpoint.disableNotification("first");
+    endpoint.disableNotification("second");
+
+    EXPECT_EQ(endpoint.status(), RdmaEndPoint::EP_READY);
+    EXPECT_FALSE(EndpointTestAccess::notifyConnected(endpoint));
+}
+
 TEST(EndpointLifecycleTest, SharedFromThisUsesRealEndpointOwnership) {
     auto endpoint = std::make_shared<RdmaEndPoint>();
     std::weak_ptr<RdmaEndPoint> weak = endpoint->shared_from_this();
@@ -185,6 +374,10 @@ TEST(EndpointLifecycleTest, BootstrapWithNewPeerQpsRetiresEstablishedEndpoint) {
 
     EXPECT_FALSE(endpoint.accept(peer_desc, local_desc).ok());
     EXPECT_EQ(endpoint.status(), RdmaEndPoint::EP_DESTROYING);
+    // The failed accept does not populate a GID. The transport retries on a
+    // newly inserted endpoint in the same bootstrap RPC so the initiator is
+    // not left with an empty reply.
+    EXPECT_TRUE(local_desc.local_gid.empty());
 }
 
 TEST(EndpointLifecycleTest, ExternalOwnerCanReleaseAfterExplicitDeconstruct) {
@@ -198,6 +391,60 @@ TEST(EndpointLifecycleTest, ExternalOwnerCanReleaseAfterExplicitDeconstruct) {
     EXPECT_TRUE(weak.expired());
 }
 
+// Destroying the notify QP takes its completions with it, so an endpoint
+// whose notify CQ has not caught up is not finished yet. The data QPs have
+// their own counters; this is the notify side of the same gate.
+TEST(EndpointLifecycleTest, FinishDestroyWaitsForNotifyCompletions) {
+    RdmaEndPoint endpoint;
+    EndpointTestAccess::markConnected(endpoint, "10.0.0.1:12345", "mlx5_0",
+                                      {100, 101});
+    EndpointTestAccess::markNotifyConnected(endpoint);
+    EndpointTestAccess::setNotifyInflight(endpoint, 3);
+    EndpointTestAccess::beginDestroy(endpoint);
+
+    EXPECT_FALSE(endpoint.finishDestroy());
+    EXPECT_EQ(endpoint.status(), RdmaEndPoint::EP_DESTROYING);
+    endpoint.noteNotifyCompletion();
+    endpoint.noteNotifyCompletion();
+    EXPECT_FALSE(endpoint.finishDestroy());
+
+    endpoint.noteNotifyCompletion();
+    EXPECT_EQ(endpoint.notifyInflight(), 0u);
+    // Never below zero, whatever order the completions arrive in.
+    endpoint.noteNotifyCompletion();
+    EXPECT_EQ(endpoint.notifyInflight(), 0u);
+
+    EXPECT_TRUE(endpoint.finishDestroy());
+    EXPECT_EQ(endpoint.status(), RdmaEndPoint::EP_DESTROYED);
+}
+
+// A consumed notify RECV slot is posted again only while the endpoint is
+// ready and its notify QP connected. Retirement moves the QP to ERR, and so
+// does the local fault that disables notifications, so neither may re-arm.
+TEST(EndpointLifecycleTest, NotifyRecvIsRearmedOnlyWhileReady) {
+    using S = RdmaEndPoint;
+    EXPECT_TRUE(S::shouldRearmNotifyRecv(S::EP_READY, true));
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(S::EP_READY, false));
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(S::EP_DESTROYING, true));
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(S::EP_DESTROYED, false));
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(S::EP_HANDSHAKING, true));
+
+    // The states the endpoint actually passes through.
+    RdmaEndPoint endpoint;
+    EndpointTestAccess::markConnected(endpoint, "10.0.0.1:12345", "mlx5_0",
+                                      {100, 101});
+    EndpointTestAccess::markNotifyConnected(endpoint);
+    EXPECT_TRUE(S::shouldRearmNotifyRecv(endpoint.status(),
+                                         endpoint.notifyConnected()));
+    endpoint.disableNotification("test");
+    EXPECT_EQ(endpoint.status(), S::EP_READY);
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(endpoint.status(),
+                                          endpoint.notifyConnected()));
+    EndpointTestAccess::beginDestroy(endpoint);
+    EXPECT_FALSE(S::shouldRearmNotifyRecv(endpoint.status(),
+                                          endpoint.notifyConnected()));
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/engine_failover_e2e_test.cpp b/mooncake-transfer-engine/tent/tests/engine_failover_e2e_test.cpp
index 7100d9913d..e3cda0b9b6 100644
--- a/mooncake-transfer-engine/tent/tests/engine_failover_e2e_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/engine_failover_e2e_test.cpp
@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+// ---------------------------------------------------------------------------
 // End-to-end failover test: drives the real TransferEngineImpl through
 // submitTransfer() / getTransferStatus() / resubmitTransferTask() by swapping
 // two FakeTransports into the engine's transport_list_ and wrapping the
@@ -23,11 +24,11 @@
 //       (simulates WC error / QP error / peer drop mid-transfer).
 //       -> engine must failover to the secondary and succeed.
 //
-// Submit-stage failures are NOT tested here. Today submitTransferTasks
-// failures are marked UNSPEC and surface as FAILED without a failover
-// attempt -- see the "Known gaps" section of docs/source/design/tent/
-// failover.md for why. Tests for that path belong in a future change
-// that makes submit-stage recovery safe (see known gaps).
+//   S*: Primary fails synchronously inside submitTransferTasks() (simulates
+//       e.g. NVLink IPC relocation failure). The engine must fail the task
+//       over to the secondary transport instead of terminal-failing it with
+//       type=UNSPEC. Derived (merged) alias tasks follow their owner.
+// ---------------------------------------------------------------------------
 
 #include <gtest/gtest.h>
 
@@ -44,6 +45,7 @@
 #include <vector>
 
 #include "tent/common/config.h"
+#include "tent/common/config_lifecycle.h"
 #include "tent/common/types.h"
 #include "tent/runtime/segment.h"
 #include "tent/runtime/transfer_engine_impl.h"
@@ -78,15 +80,19 @@ class FakeTransport : public Transport {
 
     explicit FakeTransport(TransportType self_type,
                            StatusFactory status_factory = {},
-                           PollStatusFactory poll_status_factory = {})
+                           PollStatusFactory poll_status_factory = {},
+                           bool force_submit_fail = false)
         : self_type_(self_type),
           status_factory_(std::move(status_factory)),
-          poll_status_factory_(std::move(poll_status_factory)) {
+          poll_status_factory_(std::move(poll_status_factory)),
+          force_submit_fail_(force_submit_fail) {
         caps.dram_to_dram = true;  // so checkAvailability returns true
     }
 
     std::atomic<int> install_calls{0};
     std::atomic<int> submit_calls{0};
+    // Number of individual requests handed to submitTransferTasks().
+    std::atomic<int> submitted_request_count{0};
     std::atomic<int> status_calls{0};
     std::atomic<int> add_mem_calls{0};
 
@@ -112,6 +118,11 @@ class FakeTransport : public Transport {
     Status submitTransferTasks(
         SubBatchRef batch, const std::vector<Request>& request_list) override {
         ++submit_calls;
+        submitted_request_count += (int)request_list.size();
+        if (force_submit_fail_) {
+            return Status::InternalError(
+                "FakeTransport forced synchronous submit failure" LOC_MARK);
+        }
         auto* fb = static_cast<FakeSubBatch*>(batch);
         for (const auto& req : request_list) {
             if (status_factory_) {
@@ -189,6 +200,101 @@ class FakeTransport : public Transport {
     TransportType self_type_;
     StatusFactory status_factory_;
     PollStatusFactory poll_status_factory_;
+    bool force_submit_fail_;
+};
+
+class HpTcpRecoveryTransport : public FakeTransport {
+   public:
+    explicit HpTcpRecoveryTransport(bool permanent_failure = false)
+        : FakeTransport(HP_TCP), permanent_failure_(permanent_failure) {}
+
+    std::atomic<int> retry_calls{0};
+
+    Status addMemoryBuffer(BufferDesc& desc,
+                           const MemoryOptions& /*options*/) override {
+        if (std::find(desc.transports.begin(), desc.transports.end(), HP_TCP) ==
+            desc.transports.end()) {
+            // HP TCP is first so an unhinted request exercises the HP TCP
+            // failure classification before the fallback transport.
+            desc.transports.insert(desc.transports.begin(), HP_TCP);
+        }
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override {
+        for (auto& desc : desc_list) {
+            CHECK_STATUS(addMemoryBuffer(desc, options));
+        }
+        return Status::OK();
+    }
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        ++status_calls;
+        auto* hp_batch = static_cast<FakeSubBatch*>(batch);
+        if (task_id < 0 ||
+            task_id >= static_cast<int>(hp_batch->statuses.size())) {
+            return Status::InvalidArgument("bad HP TCP task_id" LOC_MARK);
+        }
+
+        if (permanent_failure_) {
+            status = {FAILED, 0};
+            return Status::InvalidArgument(
+                "HP TCP WRITE outcome is unknown" LOC_MARK);
+        }
+        if (retry_calls.load(std::memory_order_acquire) != 0) {
+            status = {COMPLETED, hp_batch->requests[task_id].length};
+            return Status::OK();
+        }
+
+        status = {FAILED, 0};
+        return Status::NeedsRefreshCache(
+            "remote HP TCP metadata is stale" LOC_MARK);
+    }
+
+    Status retryTransferTask(SubBatchRef batch, int task_id,
+                             const Request& request) override {
+        auto* hp_batch = static_cast<FakeSubBatch*>(batch);
+        if (task_id < 0 ||
+            task_id >= static_cast<int>(hp_batch->statuses.size())) {
+            return Status::InvalidArgument("bad HP TCP retry task_id" LOC_MARK);
+        }
+        if (request.source != hp_batch->requests[task_id].source ||
+            request.target_id != hp_batch->requests[task_id].target_id ||
+            request.target_offset !=
+                hp_batch->requests[task_id].target_offset ||
+            request.length != hp_batch->requests[task_id].length) {
+            return Status::InvalidArgument(
+                "HP TCP retry changed the logical request" LOC_MARK);
+        }
+        ++retry_calls;
+        return Status::OK();
+    }
+
+    const char* getName() const override { return "<fake-hp-tcp>"; }
+
+   private:
+    bool permanent_failure_;
+};
+
+class HpTcpStatusErrorOnceTransport : public FakeTransport {
+   public:
+    HpTcpStatusErrorOnceTransport() : FakeTransport(HP_TCP) {}
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        if (poll_count_.fetch_add(1, std::memory_order_relaxed) == 0) {
+            // Deliberately leave status untouched: Transport does not promise
+            // a valid output when it returns an error.
+            return Status::InternalError(
+                "injected HP TCP status poll failure" LOC_MARK);
+        }
+        return FakeTransport::getTransferStatus(batch, task_id, status);
+    }
+
+   private:
+    std::atomic<int> poll_count_{0};
 };
 
 // ---------------------------------------------------------------------------
@@ -244,6 +350,50 @@ TransferStatus pollUntilDone(
     return ts;
 }
 
+struct HpTcpRecoveryBatch {
+    std::shared_ptr<HpTcpRecoveryTransport> hp_tcp;
+    std::shared_ptr<FakeTransport> fallback_tcp;
+    std::vector<uint8_t> buffer;
+    BatchID batch_id{0};
+};
+
+void submitHpTcpRecoveryBatch(TransferEngineImpl& engine,
+                              HpTcpRecoveryBatch& batch,
+                              bool permanent_failure = false) {
+    batch.hp_tcp = std::make_shared<HpTcpRecoveryTransport>(permanent_failure);
+    batch.fallback_tcp = std::make_shared<FakeTransport>(TCP);
+
+    std::string segment_name = engine.getSegmentName();
+    ASSERT_TRUE(batch.hp_tcp->install(segment_name, nullptr, nullptr).ok());
+    ASSERT_TRUE(
+        batch.fallback_tcp->install(segment_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(HP_TCP, batch.hp_tcp);
+    engine.swapTransportForTest(TCP, batch.fallback_tcp);
+
+    batch.buffer.assign(4096, 0xA5);
+    ASSERT_TRUE(
+        engine.registerLocalMemory(batch.buffer.data(), batch.buffer.size())
+            .ok());
+    batch.batch_id = engine.allocateBatch(1);
+    ASSERT_NE(batch.batch_id, static_cast<BatchID>(0));
+
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = batch.buffer.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(batch.buffer.data());
+    request.length = batch.buffer.size();
+    ASSERT_TRUE(engine.submitTransfer(batch.batch_id, {request}).ok());
+}
+
+void releaseHpTcpRecoveryBatch(TransferEngineImpl& engine,
+                               HpTcpRecoveryBatch& batch) {
+    EXPECT_TRUE(engine.freeBatch(batch.batch_id).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(batch.buffer.data(), batch.buffer.size())
+            .ok());
+}
+
 struct CorruptedRdmaBatch {
     std::shared_ptr<FakeTransport> fake_rdma;
     std::shared_ptr<FakeTransport> fake_tcp;
@@ -290,6 +440,81 @@ void submitCorruptedRdmaBatch(TransferEngineImpl& engine,
 // mid-transfer). Engine must failover.
 // ---------------------------------------------------------------------------
 
+TEST(EngineFailoverE2E, HpTcpStaleMetadataRetriesSameTransportOnce) {
+    auto config = makeMinimalP2PConfig();
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+
+    HpTcpRecoveryBatch batch;
+    submitHpTcpRecoveryBatch(engine, batch);
+
+    const TransferStatus final_status =
+        pollUntilDone(engine, batch.batch_id, 0);
+    EXPECT_EQ(final_status.s, COMPLETED);
+    EXPECT_EQ(batch.hp_tcp->submit_calls.load(), 1);
+    EXPECT_EQ(batch.hp_tcp->retry_calls.load(), 1);
+    EXPECT_EQ(batch.fallback_tcp->submit_calls.load(), 0);
+
+    releaseHpTcpRecoveryBatch(engine, batch);
+}
+
+TEST(EngineFailoverE2E, HpTcpPermanentFailureDoesNotFailOver) {
+    auto config = makeMinimalP2PConfig();
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+
+    HpTcpRecoveryBatch batch;
+    submitHpTcpRecoveryBatch(engine, batch, /*permanent_failure=*/true);
+
+    const TransferStatus final_status =
+        pollUntilDone(engine, batch.batch_id, 0);
+    EXPECT_EQ(final_status.s, FAILED);
+    EXPECT_EQ(batch.hp_tcp->submit_calls.load(), 1);
+    EXPECT_EQ(batch.hp_tcp->retry_calls.load(), 0);
+    EXPECT_EQ(batch.fallback_tcp->submit_calls.load(), 0);
+
+    releaseHpTcpRecoveryBatch(engine, batch);
+}
+
+TEST(EngineFailoverE2E, HpTcpPollErrorDoesNotInspectStaleStatusOutput) {
+    auto config = makeMinimalP2PConfig();
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+
+    auto hp_tcp = std::make_shared<HpTcpStatusErrorOnceTransport>();
+    std::string segment_name = engine.getSegmentName();
+    ASSERT_TRUE(hp_tcp->install(segment_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(HP_TCP, hp_tcp);
+
+    std::vector<uint8_t> buffer(4096, 0x5A);
+    ASSERT_TRUE(engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+    const BatchID batch_id = engine.allocateBatch(1);
+    ASSERT_NE(batch_id, static_cast<BatchID>(0));
+
+    Request request{};
+    request.opcode = Request::WRITE;
+    request.source = buffer.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(buffer.data());
+    request.length = buffer.size();
+    request.transport_hint = HP_TCP;
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {request}).ok());
+
+    TransferStatus status{FAILED, 123};
+    const Status first = engine.getTransferStatus(batch_id, 0, status);
+    EXPECT_TRUE(first.IsInternalError()) << first.ToString();
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(status.transferred_bytes, 0U);
+
+    ASSERT_TRUE(engine.getTransferStatus(batch_id, 0, status).ok());
+    EXPECT_EQ(status.s, COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, request.length);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+}
+
 TEST(EngineFailoverE2E, StatusCorruptionTriggersFailoverToSecondary) {
     auto cfg = makeMinimalP2PConfig();
     TransferEngineImpl engine(cfg);
@@ -358,6 +583,57 @@ TEST(EngineFailoverE2E, AutoFailoverOnPollDisabledLeavesTaskFailed) {
         engine.unregisterLocalMemory(batch.buf.data(), batch.buf.size()).ok());
 }
 
+class PinnedFailoverPolicyTest : public ::testing::TestWithParam<bool> {};
+
+TEST_P(PinnedFailoverPolicyTest, PolicyIsPinnedAtSubmit) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("max_failover_attempts", 1);
+    cfg->set("enable_auto_failover_on_poll", true);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    CorruptedRdmaBatch old_generation;
+    submitCorruptedRdmaBatch(engine, old_generation, 0xB1);
+
+    auto next_cfg = makeMinimalP2PConfig();
+    // Change each field independently so one cannot mask the other.
+    next_cfg->set("max_failover_attempts", GetParam() ? 1 : 0);
+    next_cfg->set("enable_auto_failover_on_poll", !GetParam());
+    ASSERT_TRUE(engine
+                    .publishRuntimeConfigForTest(
+                        buildTentConfigBundle(*next_cfg, 1).runtime)
+                    .ok());
+    // Reject a null publication without replacing the active policy.
+    EXPECT_TRUE(
+        engine.publishRuntimeConfigForTest(nullptr).IsInvalidArgument());
+
+    auto old_status = pollUntilDone(engine, old_generation.batch_id, 0);
+    EXPECT_EQ(old_status.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(old_generation.fake_tcp->submit_calls.load(), 1);
+
+    CorruptedRdmaBatch new_generation;
+    submitCorruptedRdmaBatch(engine, new_generation, 0xB2);
+    TransferStatus new_status{};
+    ASSERT_TRUE(
+        engine.getTransferStatus(new_generation.batch_id, 0, new_status).ok());
+    EXPECT_EQ(new_status.s, TransferStatusEnum::FAILED);
+    EXPECT_EQ(new_generation.fake_tcp->submit_calls.load(), 0);
+
+    EXPECT_TRUE(engine.freeBatch(old_generation.batch_id).ok());
+    EXPECT_TRUE(engine
+                    .unregisterLocalMemory(old_generation.buf.data(),
+                                           old_generation.buf.size())
+                    .ok());
+    EXPECT_TRUE(engine.freeBatch(new_generation.batch_id).ok());
+    EXPECT_TRUE(engine
+                    .unregisterLocalMemory(new_generation.buf.data(),
+                                           new_generation.buf.size())
+                    .ok());
+}
+
+INSTANTIATE_TEST_SUITE_P(EngineFailoverE2E, PinnedFailoverPolicyTest,
+                         ::testing::Bool());
+
 TEST(EngineFailoverE2E, AutoFailoverOnPollDisabledAppliesToVectorStatus) {
     auto cfg = makeMinimalP2PConfig();
     cfg->set("enable_auto_failover_on_poll", false);
@@ -546,6 +822,87 @@ TEST(EngineFailoverE2E, ProgressBatchKeepsOverallPendingWithMixedOutcomes) {
     EXPECT_TRUE(engine.unregisterLocalMemory(pending_buf.data(), kBufLen).ok());
 }
 
+// A terminal TIMEOUT plus a COMPLETED sibling must report TIMEOUT overall,
+// not a generic FAILED. The old aggregation collapsed every non-success
+// terminal status into FAILED.
+TEST(EngineFailoverE2E, OverallStatusUsesWorstFailureNotGenericFailed) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("enable_auto_failover_on_poll", false);
+    cfg->set("max_failover_attempts", 0);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> timeout_buf(kBufLen, 0xB1);
+    std::vector<uint8_t> completed_buf(kBufLen, 0xB2);
+    const uint64_t timeout_addr =
+        reinterpret_cast<uint64_t>(timeout_buf.data());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, [timeout_addr](const Request& req) {
+            if (reinterpret_cast<uint64_t>(req.source) == timeout_addr) {
+                return TransferStatus{TransferStatusEnum::TIMEOUT, 0};
+            }
+            return TransferStatus{TransferStatusEnum::COMPLETED, req.length};
+        });
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(fake_rdma->install(seg_name, nullptr, nullptr).ok());
+    ASSERT_TRUE(fake_tcp->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, fake_rdma);
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    ASSERT_TRUE(engine.registerLocalMemory(timeout_buf.data(), kBufLen).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(completed_buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(2);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    Request timeout_req;
+    timeout_req.opcode = Request::WRITE;
+    timeout_req.source = timeout_buf.data();
+    timeout_req.target_id = LOCAL_SEGMENT_ID;
+    timeout_req.target_offset = timeout_addr;
+    timeout_req.length = kBufLen;
+
+    Request completed_req;
+    completed_req.opcode = Request::WRITE;
+    completed_req.source = completed_buf.data();
+    completed_req.target_id = LOCAL_SEGMENT_ID;
+    completed_req.target_offset =
+        reinterpret_cast<uint64_t>(completed_buf.data());
+    completed_req.length = kBufLen;
+
+    ASSERT_TRUE(
+        engine.submitTransfer(batch_id, {timeout_req, completed_req}).ok());
+
+    TransferStatus overall_status{};
+    ASSERT_TRUE(engine.getTransferStatus(batch_id, overall_status).ok());
+    EXPECT_EQ(overall_status.s, TransferStatusEnum::TIMEOUT);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(timeout_buf.data(), kBufLen).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(completed_buf.data(), kBufLen).ok());
+}
+
+TEST(TransferStatusSeverityTest, KnownRanksMatchFormerMap) {
+    EXPECT_EQ(transferStatusSeverity(INITIAL), 0);
+    EXPECT_EQ(transferStatusSeverity(PENDING), 0);
+    EXPECT_EQ(transferStatusSeverity(COMPLETED), 0);
+    EXPECT_EQ(transferStatusSeverity(INVALID), 1);
+    EXPECT_EQ(transferStatusSeverity(CANCELED), 2);
+    EXPECT_EQ(transferStatusSeverity(TIMEOUT), 3);
+    EXPECT_EQ(transferStatusSeverity(FAILED), 4);
+}
+
+TEST(TransferStatusSeverityTest, UnknownValueRanksWithFailedAndDoesNotThrow) {
+    auto unknown = static_cast<TransferStatusEnum>(99);
+    EXPECT_EQ(transferStatusSeverity(unknown), transferStatusSeverity(FAILED));
+    EXPECT_GT(transferStatusSeverity(unknown), transferStatusSeverity(TIMEOUT));
+}
+
 TEST(EngineFailoverE2E,
      WaitTransferCompletionUsesProgressBatchWhenPollDisabled) {
     auto cfg = makeMinimalP2PConfig();
@@ -601,6 +958,37 @@ TEST(EngineFailoverE2E, TransferSyncUsesProgressBatchWhenPollDisabled) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
 }
 
+// transferSync() allocates a batch before submitting, so every error path out
+// of it has to release that batch. submitTransfer() rejecting an unregistered
+// buffer is the reachable one; the poll-failure path leaves through the same
+// guard.
+TEST(EngineFailoverE2E, TransferSyncFreesBatchWhenSubmitFails) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(fake_rdma->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, fake_rdma);
+
+    const size_t alive_before = engine.aliveBatchCountForTest();
+
+    // Never registered, so submitTransfer() fails before anything is posted.
+    std::vector<uint8_t> unregistered(4096, 0xD3);
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = unregistered.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(unregistered.data());
+    req.length = unregistered.size();
+
+    EXPECT_FALSE(engine.transferSync({req}).ok());
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 0);
+    EXPECT_EQ(engine.aliveBatchCountForTest(), alive_before)
+        << "the batch allocated by transferSync outlived the failed submit";
+}
+
 TEST(EngineFailoverE2E, ProgressBatchAdvancesExactlyOneStepPerCall) {
     auto cfg = makeMinimalP2PConfig();
     cfg->set("enable_auto_failover_on_poll", false);
@@ -1036,6 +1424,323 @@ TEST(EngineFailoverE2E, PerTaskFailoverCountsAreIndependent) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf1.data(), kBufLen).ok());
 }
 
+// ---------------------------------------------------------------------------
+// S*: Submit-stage failover. The primary transport fails synchronously inside
+// submitTransferTasks() (e.g. NVLink IPC relocation error). The engine must
+// walk the remaining candidates instead of terminal-failing with type=UNSPEC.
+// ---------------------------------------------------------------------------
+
+namespace {
+
+void installFailingPrimaryWithSecondary(
+    TransferEngineImpl& engine, std::shared_ptr<FakeTransport>& primary,
+    std::shared_ptr<FakeTransport>& secondary) {
+    primary =
+        std::make_shared<FakeTransport>(RDMA, FakeTransport::StatusFactory{},
+                                        FakeTransport::PollStatusFactory{},
+                                        /*force_submit_fail=*/true);
+    secondary = std::make_shared<FakeTransport>(TCP);
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(primary->install(seg_name, nullptr, nullptr).ok());
+    ASSERT_TRUE(secondary->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, primary);
+    engine.swapTransportForTest(TCP, secondary);
+}
+
+}  // namespace
+
+TEST(EngineFailoverE2E, SubmitStageFailureFailsOverToSecondary) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma;
+    std::shared_ptr<FakeTransport> fake_tcp;
+    installFailingPrimaryWithSecondary(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen, 0x7e);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(8);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = buf.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(buf.data());
+    req.length = kBufLen;
+
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {req}).ok());
+
+    auto final_status = pollUntilDone(engine, batch_id, 0);
+    EXPECT_EQ(final_status.s, TransferStatusEnum::COMPLETED);
+
+    // One failed synchronous submit on RDMA, one successful submit on TCP.
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+TEST(EngineFailoverE2E, SubmitStageFailureExhaustsBudget) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma;
+    std::shared_ptr<FakeTransport> fake_tcp;
+    installFailingPrimaryWithSecondary(engine, fake_rdma, fake_tcp);
+    // The secondary fails synchronously too: every transport rejects the
+    // submit, so the task must end terminally FAILED.
+    auto failing_tcp = std::make_shared<FakeTransport>(
+        TCP, FakeTransport::StatusFactory{}, FakeTransport::PollStatusFactory{},
+        /*force_submit_fail=*/true);
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(failing_tcp->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, failing_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen, 0x5c);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(8);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = buf.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(buf.data());
+    req.length = kBufLen;
+
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {req}).ok());
+
+    auto final_status = pollUntilDone(engine, batch_id, 0);
+    EXPECT_EQ(final_status.s, TransferStatusEnum::FAILED);
+
+    // Initial submit on RDMA plus exactly one failover attempt on TCP.
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(failing_tcp->submit_calls.load(), 1);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+TEST(EngineFailoverE2E, SubmitStageFailoverWithDerivedTasks) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("merge_requests", true);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma;
+    std::shared_ptr<FakeTransport> fake_tcp;
+    installFailingPrimaryWithSecondary(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kHalf = 2048;
+    constexpr size_t kBufLen = kHalf * 2;
+    std::vector<uint8_t> buf(kBufLen, 0x3a);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(8);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    // Two adjacent requests with adjacent targets merge into one owner task
+    // plus one derived alias.
+    Request first;
+    first.opcode = Request::WRITE;
+    first.source = buf.data();
+    first.target_id = LOCAL_SEGMENT_ID;
+    first.target_offset = reinterpret_cast<uint64_t>(buf.data());
+    first.length = kHalf;
+
+    Request second = first;
+    second.source = buf.data() + kHalf;
+    second.target_offset = reinterpret_cast<uint64_t>(buf.data()) + kHalf;
+
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {first, second}).ok());
+
+    auto status0 = pollUntilDone(engine, batch_id, 0);
+    auto status1 = pollUntilDone(engine, batch_id, 1);
+    EXPECT_EQ(status0.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status1.s, TransferStatusEnum::COMPLETED);
+
+    // The merged transfer is re-posted exactly ONCE on the fallback: the
+    // derived alias must not cause a duplicate physical submission. Both the
+    // failed RDMA submit and the recovered TCP submit see the single merged
+    // (4096-byte) request.
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(fake_rdma->submitted_request_count.load(), 1);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+    EXPECT_EQ(fake_tcp->submitted_request_count.load(), 1);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+TEST(EngineFailoverE2E, QueuedPathSubmitStageFailover) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("enable_runtime_queue", true);
+    cfg->set("runtime_queue/max_outstanding_owners", 16UL);
+    cfg->set("runtime_queue/max_outstanding_bytes", 1UL << 20);
+    cfg->set("runtime_queue/max_dispatch_owners", 16UL);
+    cfg->set("runtime_queue/max_dispatch_bytes", 1UL << 20);
+    cfg->set("runtime_queue/staging_owner_reserve", 0UL);
+    cfg->set("runtime_queue/staging_byte_reserve", 0UL);
+    cfg->set("runtime_queue/progress_fallback_interval_us", 50000UL);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma;
+    std::shared_ptr<FakeTransport> fake_tcp;
+    installFailingPrimaryWithSecondary(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen, 0x99);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(8);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = buf.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(buf.data());
+    req.length = kBufLen;
+
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {req}).ok());
+
+    auto final_status = pollUntilDone(engine, batch_id, 0);
+    EXPECT_EQ(final_status.s, TransferStatusEnum::COMPLETED);
+
+    // The queued dispatch path submitted once on RDMA (failed synchronously)
+    // and recovered on TCP.
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+namespace {
+
+// Regression transport for the all-or-nothing submission contract (see
+// Transport::submitTransferTasks): on its first submit call it accepts the
+// first accept_count requests into its sub-batch, then hits an internal
+// error and rolls the appends back before returning the error — what a
+// contract-compliant transport must do when a partial submission fails
+// mid-batch. The engine must recover via submit-stage failover, every
+// request must execute exactly once, and the original attempt must settle
+// cleanly.
+class PartialAcceptThenFailTransport : public FakeTransport {
+   public:
+    PartialAcceptThenFailTransport(TransportType self_type, size_t accept_count)
+        : FakeTransport(self_type), accept_count_(accept_count) {}
+
+    std::atomic<int> rollback_count{0};
+    FakeSubBatch* last_sub_batch = nullptr;
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request>& request_list) override {
+        ++submit_calls;
+        if (failed_once_) {
+            return FakeTransport::submitTransferTasks(batch, request_list);
+        }
+        failed_once_ = true;
+        auto* fb = static_cast<FakeSubBatch*>(batch);
+        last_sub_batch = fb;
+        const size_t accepted = accept_count_ < request_list.size()
+                                    ? accept_count_
+                                    : request_list.size();
+        // Partially accept a prefix of the batch...
+        for (size_t i = 0; i < accepted; ++i) {
+            fb->requests.push_back(request_list[i]);
+            fb->statuses.push_back(
+                {TransferStatusEnum::COMPLETED, request_list[i].length});
+            fb->poll_counts.push_back(0);
+            fb->task_count++;
+        }
+        // ... then hit an error and roll the prefix back so the failed
+        // submission leaves the sub-batch unchanged.
+        for (size_t i = 0; i < accepted; ++i) {
+            fb->requests.pop_back();
+            fb->statuses.pop_back();
+            fb->poll_counts.pop_back();
+        }
+        fb->task_count -= (int)accepted;
+        rollback_count += (int)accepted;
+        return Status::InternalError("partial submission rolled back" LOC_MARK);
+    }
+
+   private:
+    size_t accept_count_;
+    bool failed_once_ = false;
+};
+
+}  // namespace
+
+TEST(EngineFailoverE2E, SubmitStagePartialAcceptanceExecutesExactlyOnce) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    constexpr size_t kNumRequests = 4;
+    constexpr size_t kAcceptPrefix = 2;
+    auto primary =
+        std::make_shared<PartialAcceptThenFailTransport>(RDMA, kAcceptPrefix);
+    auto secondary = std::make_shared<FakeTransport>(TCP);
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(primary->install(seg_name, nullptr, nullptr).ok());
+    ASSERT_TRUE(secondary->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, primary);
+    engine.swapTransportForTest(TCP, secondary);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen * kNumRequests, 0x6b);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    BatchID batch_id = engine.allocateBatch(8);
+    ASSERT_NE(batch_id, (BatchID)0);
+
+    std::vector<Request> requests;
+    requests.reserve(kNumRequests);
+    for (size_t i = 0; i < kNumRequests; ++i) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = buf.data() + i * kBufLen;
+        req.target_id = LOCAL_SEGMENT_ID;
+        req.target_offset =
+            reinterpret_cast<uint64_t>(buf.data() + i * kBufLen);
+        req.length = kBufLen;
+        requests.push_back(req);
+    }
+
+    ASSERT_TRUE(engine.submitTransfer(batch_id, requests).ok());
+
+    for (size_t i = 0; i < kNumRequests; ++i) {
+        auto status = pollUntilDone(engine, batch_id, i);
+        EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED);
+    }
+
+    // The failed RDMA submission rolled its accepted prefix back: the
+    // original attempt settled cleanly with no lingering tasks in the
+    // sub-batch.
+    EXPECT_EQ(primary->submit_calls.load(), 1);
+    EXPECT_EQ(primary->rollback_count.load(), (int)kAcceptPrefix);
+    ASSERT_NE(primary->last_sub_batch, nullptr);
+    EXPECT_EQ(primary->last_sub_batch->task_count, 0);
+    EXPECT_TRUE(primary->last_sub_batch->requests.empty());
+
+    // Every request executed exactly once, on the fallback transport.
+    EXPECT_EQ(secondary->submitted_request_count.load(), (int)kNumRequests);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/failover_test.cpp b/mooncake-transfer-engine/tent/tests/failover_test.cpp
deleted file mode 100644
index 6c5b9441e0..0000000000
--- a/mooncake-transfer-engine/tent/tests/failover_test.cpp
+++ /dev/null
@@ -1,308 +0,0 @@
-// Copyright 2026 KVCache.AI
-//
-// 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.
-
-#include <gtest/gtest.h>
-
-#include <memory>
-#include <string>
-
-#include "tent/common/config.h"
-#include "tent/common/types.h"
-#include "tent/runtime/transfer_engine_impl.h"
-
-namespace mooncake {
-namespace tent {
-namespace {
-
-// ---------------------------------------------------------------------------
-// TaskInfo failover_count field tests
-// ---------------------------------------------------------------------------
-
-TEST(TaskInfoTest, DefaultFailoverCount) {
-    TaskInfo task;
-    EXPECT_EQ(task.failover_count, 0);
-}
-
-TEST(TaskInfoTest, FailoverCountIncrement) {
-    TaskInfo task;
-    ++task.failover_count;
-    EXPECT_EQ(task.failover_count, 1);
-    ++task.failover_count;
-    ++task.failover_count;
-    EXPECT_EQ(task.failover_count, 3);
-}
-
-TEST(TaskInfoTest, FailoverCountLimitCheck) {
-    // Simulate the limit check pattern from resubmitTransferTask
-    constexpr int kMaxAttempts = 3;
-    TaskInfo task;
-
-    // Attempts 1..3 should pass
-    for (int i = 0; i < kMaxAttempts; ++i) {
-        ++task.failover_count;
-        EXPECT_LE(task.failover_count, kMaxAttempts)
-            << "Attempt " << task.failover_count << " should be within limit";
-    }
-
-    // Attempt 4 should exceed
-    ++task.failover_count;
-    EXPECT_GT(task.failover_count, kMaxAttempts);
-}
-
-// ---------------------------------------------------------------------------
-// TaskInfo preserves other fields after failover-related mutations
-// ---------------------------------------------------------------------------
-
-TEST(TaskInfoTest, FailoverFieldsIndependent) {
-    TaskInfo task;
-    task.type = RDMA;
-    task.xport_priority = 0;
-    task.status = TransferStatusEnum::PENDING;
-    task.failover_count = 0;
-
-    // Simulate failover: increment priority and failover_count, change type
-    task.xport_priority++;
-    task.failover_count++;
-    task.type = TCP;
-    task.status = TransferStatusEnum::PENDING;  // Reset to PENDING
-
-    EXPECT_EQ(task.xport_priority, 1);
-    EXPECT_EQ(task.failover_count, 1);
-    EXPECT_EQ(task.type, TCP);
-    EXPECT_EQ(task.status, TransferStatusEnum::PENDING);
-}
-
-// ---------------------------------------------------------------------------
-// Config loading for max_failover_attempts
-// ---------------------------------------------------------------------------
-
-TEST(FailoverConfigTest, DefaultValue) {
-    auto conf = std::make_shared<Config>();
-    // When not set, should return the default
-    EXPECT_EQ(conf->get("max_failover_attempts", 3), 3);
-}
-
-TEST(FailoverConfigTest, CustomValue) {
-    auto conf = std::make_shared<Config>();
-    conf->set("max_failover_attempts", 5);
-    EXPECT_EQ(conf->get("max_failover_attempts", 3), 5);
-}
-
-TEST(FailoverConfigTest, ZeroDisablesFailover) {
-    auto conf = std::make_shared<Config>();
-    conf->set("max_failover_attempts", 0);
-    int max_attempts = conf->get("max_failover_attempts", 3);
-    EXPECT_EQ(max_attempts, 0);
-
-    // With max=0, the very first ++failover_count > 0 check should fail
-    TaskInfo task;
-    ++task.failover_count;
-    EXPECT_GT(task.failover_count, max_attempts);
-}
-
-TEST(FailoverConfigTest, AutoFailoverOnPollDefaultEnabled) {
-    auto conf = std::make_shared<Config>();
-    EXPECT_TRUE(conf->get("enable_auto_failover_on_poll", true));
-}
-
-TEST(FailoverConfigTest, AutoFailoverOnPollCanBeDisabled) {
-    auto conf = std::make_shared<Config>();
-    conf->set("enable_auto_failover_on_poll", false);
-    EXPECT_FALSE(conf->get("enable_auto_failover_on_poll", true));
-}
-
-// ---------------------------------------------------------------------------
-// TransportType name coverage (tests the static helper indirectly via
-// the enum values — the function itself is file-local in the .cpp, so we
-// verify the enum values are well-defined and usable in switch)
-// ---------------------------------------------------------------------------
-
-TEST(TransportTypeTest, UnspecIsZeroSlot) {
-    // UNSPEC must be value 0 so that zero-initialized tent_request /
-    // tent_memory_options structs (the C ABI) default to UNSPEC
-    // rather than silently pinning to whichever transport happened
-    // to occupy slot 0.
-    EXPECT_EQ(static_cast<int>(UNSPEC), 0);
-    EXPECT_EQ(kSupportedTransportTypes, static_cast<int>(kNumTransportTypes));
-    EXPECT_GT(kSupportedTransportTypes, static_cast<int>(UNSPEC));
-}
-
-// ---------------------------------------------------------------------------
-// Failover state machine simulation (no real transport needed)
-// ---------------------------------------------------------------------------
-
-TEST(FailoverStateMachineTest, SimulateFullFailoverSequence) {
-    // Simulate the sequence: submit on RDMA → fail → failover to TCP → succeed
-    TaskInfo task;
-    task.type = RDMA;
-    task.xport_priority = 0;
-    task.status = TransferStatusEnum::PENDING;
-    task.failover_count = 0;
-
-    // Step 1: RDMA reports FAILED
-    task.status = TransferStatusEnum::FAILED;
-    EXPECT_EQ(task.status, TransferStatusEnum::FAILED);
-
-    // Step 2: resubmitTransferTask logic (simulated)
-    constexpr int kMaxAttempts = 3;
-    ++task.failover_count;
-    EXPECT_LE(task.failover_count, kMaxAttempts);  // Within limit
-
-    task.xport_priority++;
-    // Simulate resolveTransport returning TCP
-    task.type = TCP;
-    task.status = TransferStatusEnum::PENDING;
-
-    EXPECT_EQ(task.type, TCP);
-    EXPECT_EQ(task.xport_priority, 1);
-    EXPECT_EQ(task.failover_count, 1);
-    EXPECT_EQ(task.status, TransferStatusEnum::PENDING);
-
-    // Step 3: TCP succeeds
-    task.status = TransferStatusEnum::COMPLETED;
-    EXPECT_EQ(task.status, TransferStatusEnum::COMPLETED);
-}
-
-TEST(FailoverStateMachineTest, ExhaustAllTransports) {
-    // Simulate exhausting all failover attempts
-    constexpr int kMaxAttempts = 3;
-    TaskInfo task;
-    task.type = RDMA;
-    task.xport_priority = 0;
-
-    for (int i = 0; i < kMaxAttempts; ++i) {
-        task.status = TransferStatusEnum::FAILED;
-        ++task.failover_count;
-        EXPECT_LE(task.failover_count, kMaxAttempts);
-        task.xport_priority++;
-        task.status = TransferStatusEnum::PENDING;
-    }
-
-    // Next failure should exceed the limit
-    task.status = TransferStatusEnum::FAILED;
-    ++task.failover_count;
-    EXPECT_GT(task.failover_count, kMaxAttempts);
-
-    // Task stays FAILED — no more failover
-    EXPECT_EQ(task.status, TransferStatusEnum::FAILED);
-    EXPECT_EQ(task.failover_count, kMaxAttempts + 1);
-}
-
-TEST(FailoverStateMachineTest, StagingBypassesPriorityIncrement) {
-    // When task.staging is true, xport_priority should NOT increment
-    // (mirroring resubmitTransferTask logic)
-    TaskInfo task;
-    task.type = TCP;
-    task.xport_priority = 0;
-    task.staging = true;
-
-    // Simulate resubmit logic
-    if (task.staging)
-        task.staging = false;
-    else
-        task.xport_priority++;
-
-    EXPECT_FALSE(task.staging);
-    EXPECT_EQ(task.xport_priority, 0);  // Should NOT have incremented
-}
-
-// ---------------------------------------------------------------------------
-// Batch status aggregation correctness
-// ---------------------------------------------------------------------------
-
-// Verifies the invariant: a batch with one permanently-FAILED task and
-// another still-PENDING task must report PENDING (not FAILED) overall,
-// because the PENDING task may still complete.  The old code latched
-// overall_status to FAILED as soon as any task was terminal.
-TEST(BatchStatusAggregationTest, PendingTaskPreventsEarlyBatchFailure) {
-    // Two tasks in a batch scenario (simulated):
-    // Task A: permanently FAILED (exhausted failover budget)
-    // Task B: still PENDING (retrying on secondary transport)
-    //
-    // Expected overall status: PENDING (not FAILED), because Task B is
-    // still in-flight.  Only once Task B reaches a terminal state should
-    // the batch become terminal.
-
-    struct MockTask {
-        TransferStatusEnum status{PENDING};
-        bool derived{false};
-        size_t length{1024};
-    };
-
-    auto aggregateStatus =
-        [](const std::vector<MockTask>& tasks) -> TransferStatusEnum {
-        size_t success_tasks = 0;
-        size_t failed_tasks = 0;
-        size_t total_tasks = 0;
-        for (auto& t : tasks) {
-            if (t.derived) continue;
-            total_tasks++;
-            if (t.status == COMPLETED)
-                success_tasks++;
-            else if (t.status != PENDING)
-                failed_tasks++;
-        }
-        if (success_tasks == total_tasks) return COMPLETED;
-        if (success_tasks + failed_tasks == total_tasks) return FAILED;
-        return PENDING;
-    };
-
-    // Case 1: one FAILED + one PENDING → overall PENDING
-    {
-        std::vector<MockTask> tasks = {{FAILED, false, 1024},
-                                       {PENDING, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), PENDING);
-    }
-
-    // Case 2: one FAILED + one COMPLETED → overall FAILED
-    {
-        std::vector<MockTask> tasks = {{FAILED, false, 1024},
-                                       {COMPLETED, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), FAILED);
-    }
-
-    // Case 3: all COMPLETED → overall COMPLETED
-    {
-        std::vector<MockTask> tasks = {{COMPLETED, false, 1024},
-                                       {COMPLETED, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), COMPLETED);
-    }
-
-    // Case 4: all PENDING → overall PENDING
-    {
-        std::vector<MockTask> tasks = {{PENDING, false, 1024},
-                                       {PENDING, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), PENDING);
-    }
-
-    // Case 5: derived tasks are skipped
-    {
-        std::vector<MockTask> tasks = {{FAILED, false, 1024},
-                                       {FAILED, true, 1024},  // derived: skip
-                                       {PENDING, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), PENDING);
-    }
-
-    // Case 6: all non-derived are terminal with at least one failure
-    {
-        std::vector<MockTask> tasks = {{COMPLETED, false, 1024},
-                                       {FAILED, true, 1024},  // derived: skip
-                                       {FAILED, false, 1024}};
-        EXPECT_EQ(aggregateStatus(tasks), FAILED);
-    }
-}
-
-}  // namespace
-}  // namespace tent
-}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/gds_transport_status_test.cpp b/mooncake-transfer-engine/tent/tests/gds_transport_status_test.cpp
new file mode 100644
index 0000000000..a28df72b4c
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/gds_transport_status_test.cpp
@@ -0,0 +1,233 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <vector>
+
+#include "tent/transport/gds/gds_transport.h"
+
+namespace {
+
+std::vector<CUfileIOEvents_t> reported_events;
+size_t cancel_call_count = 0;
+
+}  // namespace
+
+extern "C" CUfileError_t __wrap_cuFileDriverOpen() {
+    CUfileError_t result{};
+    result.err = CU_FILE_SUCCESS;
+    return result;
+}
+
+extern "C" CUfileError_t __wrap_cuFileBatchIOGetStatus(CUfileBatchHandle_t,
+                                                       unsigned,
+                                                       unsigned* num_events,
+                                                       CUfileIOEvents_t* events,
+                                                       timespec*) {
+    const auto count = std::min<size_t>(*num_events, reported_events.size());
+    std::copy_n(reported_events.begin(), count, events);
+    *num_events = static_cast<unsigned>(count);
+
+    CUfileError_t result{};
+    result.err = CU_FILE_SUCCESS;
+    return result;
+}
+
+extern "C" CUfileError_t __wrap_cuFileBatchIOCancel(CUfileBatchHandle_t) {
+    ++cancel_call_count;
+    CUfileError_t result{};
+    result.err = CU_FILE_SUCCESS;
+    return result;
+}
+
+namespace mooncake {
+namespace tent {
+
+class GdsTransportTestPeer {
+   public:
+    static TransferStatus aggregate(const std::vector<CUfileIOEvents_t>& events,
+                                    bool& all_terminal) {
+        return GdsTransport::aggregateTransferStatus(events, 0, events.size(),
+                                                     all_terminal);
+    }
+};
+
+namespace {
+
+CUfileIOEvents_t makeEvent(CUfileStatus_t status, int64_t bytes = 0,
+                           size_t slice_id = 0) {
+    CUfileIOEvents_t event{};
+    event.status = status;
+    event.ret = bytes;
+    event.cookie = reinterpret_cast<void*>(slice_id + 1);
+    return event;
+}
+
+TEST(GdsTransportStatusTest, DetectsFailureWhileSiblingIsActive) {
+    bool all_terminal = true;
+    auto status = GdsTransportTestPeer::aggregate(
+        {makeEvent(CUFILE_FAILED), makeEvent(CUFILE_WAITING)}, all_terminal);
+
+    EXPECT_EQ(status.s, FAILED);
+    EXPECT_FALSE(all_terminal);
+}
+
+TEST(GdsTransportStatusTest, ReportsPendingWhenNoFailureIsKnown) {
+    bool all_terminal = true;
+    auto status = GdsTransportTestPeer::aggregate(
+        {makeEvent(CUFILE_COMPLETE, 1024), makeEvent(CUFILE_PENDING)},
+        all_terminal);
+
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(status.transferred_bytes, 1024);
+    EXPECT_FALSE(all_terminal);
+}
+
+TEST(GdsTransportStatusTest, PublicStatusReportsCompletedBytesWhilePending) {
+    GdsTransport transport;
+    GdsSubBatch batch;
+    BatchHandle batch_handle{};
+    batch.batch_handle = &batch_handle;
+    batch.io_params.resize(2);
+    batch.io_events.resize(2);
+    batch.cached_events = {makeEvent(CUFILE_PENDING, 0, 0),
+                           makeEvent(CUFILE_PENDING, 0, 1)};
+    batch.io_param_ranges.push_back(IOParamRange{0, 2, 0, PENDING, PENDING});
+    reported_events = {makeEvent(CUFILE_COMPLETE, 1024, 0),
+                       makeEvent(CUFILE_PENDING, 0, 1)};
+
+    TransferStatus status{INITIAL, 0};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(status.transferred_bytes, 1024);
+    EXPECT_EQ(batch.io_param_ranges[0].transferred_bytes, 1024);
+}
+
+TEST(GdsTransportStatusTest, KeepsFailurePendingUntilEverySliceIsTerminal) {
+    GdsTransport transport;
+    GdsSubBatch batch;
+    BatchHandle batch_handle{};
+    batch.batch_handle = &batch_handle;
+    batch.io_params.resize(2);
+    batch.io_events.resize(2);
+    batch.cached_events = {makeEvent(CUFILE_PENDING, 0, 0),
+                           makeEvent(CUFILE_PENDING, 0, 1)};
+    batch.io_param_ranges.push_back(IOParamRange{0, 2, 0, PENDING, PENDING});
+    reported_events = {makeEvent(CUFILE_FAILED, 0, 0),
+                       makeEvent(CUFILE_PENDING, 0, 1)};
+    cancel_call_count = 0;
+
+    TransferStatus status{INITIAL, 0};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(batch.io_param_ranges[0].known_failure, FAILED);
+    EXPECT_FALSE(batch.reusable);
+    EXPECT_EQ(cancel_call_count, 1);
+
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(cancel_call_count, 1);
+
+    reported_events = {makeEvent(CUFILE_FAILED, 0, 0),
+                       makeEvent(CUFILE_CANCELED, 0, 1)};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, FAILED);
+    EXPECT_TRUE(batch.reusable);
+    EXPECT_EQ(cancel_call_count, 1);
+}
+
+TEST(GdsTransportStatusTest, CancellationDoesNotMaskOriginalFailure) {
+    GdsTransport transport;
+    GdsSubBatch batch;
+    BatchHandle batch_handle{};
+    batch.batch_handle = &batch_handle;
+    batch.io_params.resize(2);
+    batch.io_events.resize(2);
+    batch.cached_events = {makeEvent(CUFILE_PENDING, 0, 0),
+                           makeEvent(CUFILE_PENDING, 0, 1)};
+    batch.io_param_ranges.push_back(IOParamRange{0, 2, 0, PENDING, PENDING});
+    reported_events = {makeEvent(CUFILE_INVALID, 0, 0),
+                       makeEvent(CUFILE_PENDING, 0, 1)};
+    cancel_call_count = 0;
+
+    TransferStatus status{INITIAL, 0};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, PENDING);
+    EXPECT_EQ(batch.io_param_ranges[0].known_failure, INVALID);
+
+    reported_events = {makeEvent(CUFILE_INVALID, 0, 0),
+                       makeEvent(CUFILE_CANCELED, 0, 1)};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, INVALID);
+    EXPECT_EQ(cancel_call_count, 1);
+}
+
+TEST(GdsTransportStatusTest, ReusesHandleOnlyAfterWholeBatchIsTerminal) {
+    GdsTransport transport;
+    GdsSubBatch batch;
+    BatchHandle batch_handle{};
+    batch.batch_handle = &batch_handle;
+    batch.io_params.resize(2);
+    batch.io_events.resize(2);
+    batch.cached_events = {makeEvent(CUFILE_PENDING, 0, 0),
+                           makeEvent(CUFILE_PENDING, 0, 1)};
+    batch.io_param_ranges = {IOParamRange{0, 1, 0, PENDING, PENDING},
+                             IOParamRange{1, 1, 0, PENDING, PENDING}};
+    reported_events = {makeEvent(CUFILE_FAILED, 0, 0),
+                       makeEvent(CUFILE_PENDING, 0, 1)};
+    cancel_call_count = 0;
+
+    TransferStatus status{INITIAL, 0};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 0, status).ok());
+    EXPECT_EQ(status.s, FAILED);
+    EXPECT_FALSE(batch.reusable);
+    EXPECT_EQ(cancel_call_count, 0);
+
+    reported_events = {makeEvent(CUFILE_FAILED, 0, 0),
+                       makeEvent(CUFILE_COMPLETE, 1024, 1)};
+    ASSERT_TRUE(transport.getTransferStatus(&batch, 1, status).ok());
+    EXPECT_EQ(status.s, COMPLETED);
+    EXPECT_TRUE(batch.reusable);
+}
+
+TEST(GdsTransportStatusTest, AggregatesCompletedBytes) {
+    bool all_terminal = false;
+    auto status = GdsTransportTestPeer::aggregate(
+        {makeEvent(CUFILE_COMPLETE, 1024), makeEvent(CUFILE_COMPLETE, 2048)},
+        all_terminal);
+
+    EXPECT_EQ(status.s, COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, 3072);
+    EXPECT_TRUE(all_terminal);
+}
+
+TEST(GdsTransportStatusTest, FailurePrecedenceIsCompletionOrderIndependent) {
+    bool all_terminal = false;
+    auto first = GdsTransportTestPeer::aggregate(
+        {makeEvent(CUFILE_CANCELED), makeEvent(CUFILE_FAILED)}, all_terminal);
+    EXPECT_EQ(first.s, FAILED);
+    EXPECT_TRUE(all_terminal);
+
+    auto second = GdsTransportTestPeer::aggregate(
+        {makeEvent(CUFILE_FAILED), makeEvent(CUFILE_CANCELED)}, all_terminal);
+    EXPECT_EQ(second.s, FAILED);
+    EXPECT_TRUE(all_terminal);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_buffer_registry_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_buffer_registry_test.cpp
new file mode 100644
index 0000000000..5a337bc6b6
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_buffer_registry_test.cpp
@@ -0,0 +1,111 @@
+// Copyright 2026 KVCache.AI
+#include <gtest/gtest.h>
+
+#include <array>
+#include <atomic>
+#include <thread>
+
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+
+namespace mooncake::tent {
+namespace {
+
+TEST(HighPerformanceTcpBufferRegistryTest, EnforcesPermissionAndRegistration) {
+    HighPerformanceTcpBufferRegistry registry;
+    std::array<uint8_t, 64> data{};
+    const uint64_t base = reinterpret_cast<uint64_t>(data.data());
+    uint64_t id = 0;
+    ASSERT_TRUE(registry.add(base, data.size(), kGlobalReadOnly, &id).ok());
+
+    HighPerformanceTcpBufferRegistry::Lease lease;
+    HighPerformanceTcpStatus failure;
+    ASSERT_TRUE(registry
+                    .acquireRemoteLease(base, data.size(), id,
+                                        HighPerformanceTcpOpcode::kRead, &lease,
+                                        &failure)
+                    .ok());
+    lease.reset();
+    EXPECT_FALSE(registry
+                     .acquireRemoteLease(base, data.size(), id,
+                                         HighPerformanceTcpOpcode::kWrite,
+                                         &lease, &failure)
+                     .ok());
+    EXPECT_EQ(failure, HighPerformanceTcpStatus::kPermissionDenied);
+    EXPECT_FALSE(registry
+                     .acquireRemoteLease(base, data.size(), id + 1,
+                                         HighPerformanceTcpOpcode::kRead,
+                                         &lease, &failure)
+                     .ok());
+    EXPECT_EQ(failure, HighPerformanceTcpStatus::kStaleRegistration);
+}
+
+TEST(HighPerformanceTcpBufferRegistryTest,
+     RejectsRegistrationFromPreviousRegistryIncarnation) {
+    std::array<uint8_t, 64> data{};
+    const uint64_t base = reinterpret_cast<uint64_t>(data.data());
+
+    uint64_t stale_id = 0;
+    {
+        HighPerformanceTcpBufferRegistry previous;
+        ASSERT_TRUE(
+            previous.add(base, data.size(), kGlobalReadWrite, &stale_id).ok());
+    }
+
+    HighPerformanceTcpBufferRegistry current;
+    uint64_t current_id = 0;
+    ASSERT_TRUE(
+        current.add(base, data.size(), kGlobalReadWrite, &current_id).ok());
+    ASSERT_NE(stale_id, current_id);
+
+    HighPerformanceTcpBufferRegistry::Lease lease;
+    HighPerformanceTcpStatus failure;
+    EXPECT_FALSE(current
+                     .acquireRemoteLease(base, data.size(), stale_id,
+                                         HighPerformanceTcpOpcode::kRead,
+                                         &lease, &failure)
+                     .ok());
+    EXPECT_EQ(failure, HighPerformanceTcpStatus::kStaleRegistration);
+    EXPECT_TRUE(current
+                    .acquireRemoteLease(base, data.size(), current_id,
+                                        HighPerformanceTcpOpcode::kRead, &lease,
+                                        &failure)
+                    .ok());
+}
+
+TEST(HighPerformanceTcpBufferRegistryTest, UnregisterWaitsForActiveLease) {
+    HighPerformanceTcpBufferRegistry registry;
+    std::array<uint8_t, 64> data{};
+    const uint64_t base = reinterpret_cast<uint64_t>(data.data());
+    uint64_t id = 0;
+    ASSERT_TRUE(registry.add(base, data.size(), kGlobalReadWrite, &id).ok());
+    HighPerformanceTcpBufferRegistry::Lease lease;
+    ASSERT_TRUE(registry.acquireLocalLease(base, data.size(), &lease).ok());
+
+    std::atomic<bool> done{false};
+    std::thread remover([&] {
+        EXPECT_TRUE(registry.remove(base, data.size()).ok());
+        done = true;
+    });
+    while (registry.tracks(base, data.size())) std::this_thread::yield();
+    EXPECT_FALSE(done.load());
+    lease.reset();
+    remover.join();
+    EXPECT_TRUE(done.load());
+}
+
+TEST(HighPerformanceTcpBufferRegistryTest, CloseRejectsNewWork) {
+    HighPerformanceTcpBufferRegistry registry;
+    std::array<uint8_t, 8> data{};
+    uint64_t id = 0;
+    ASSERT_TRUE(registry
+                    .add(reinterpret_cast<uint64_t>(data.data()), data.size(),
+                         kGlobalReadWrite, &id)
+                    .ok());
+    registry.close();
+    EXPECT_TRUE(
+        registry.add(0x1000, 8, kGlobalReadWrite, nullptr).IsTooManyRequests());
+    EXPECT_FALSE(registry.reopen().ok());
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_e2e_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_e2e_test.cpp
new file mode 100644
index 0000000000..60abaa76ed
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_e2e_test.cpp
@@ -0,0 +1,281 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#include <gtest/gtest.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <cerrno>
+#include <chrono>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <random>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/transfer_engine.h"
+
+namespace mooncake::tent {
+namespace {
+
+bool ReadExactly(int fd, void* buffer, size_t length) {
+    auto* cursor = static_cast<uint8_t*>(buffer);
+    size_t received = 0;
+    while (received < length) {
+        ssize_t read_result = 0;
+        do {
+            read_result = read(fd, cursor + received, length - received);
+        } while (read_result < 0 && errno == EINTR);
+        if (read_result <= 0) return false;
+        received += static_cast<size_t>(read_result);
+    }
+    return true;
+}
+
+class ChildProcessGuard {
+   public:
+    ChildProcessGuard(pid_t pid, int stop_fd) : pid_(pid), stop_fd_(stop_fd) {}
+
+    ~ChildProcessGuard() {
+        if (pid_ <= 0) return;
+        close(stop_fd_);
+        (void)waitpid(pid_, nullptr, 0);
+    }
+
+    int finish() {
+        close(stop_fd_);
+        int status = 0;
+        (void)waitpid(pid_, &status, 0);
+        pid_ = -1;
+        stop_fd_ = -1;
+        return status;
+    }
+
+   private:
+    pid_t pid_;
+    int stop_fd_;
+};
+
+std::shared_ptr<Config> MakeHpConfig(bool multi_rail) {
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("metadata_servers", "P2PHANDSHAKE");
+    config->set("transports/tcp/enable", false);
+    config->set("transports/hp_tcp/enable", true);
+    config->set("transports/hp_tcp/bind_address", "127.0.0.1");
+    config->set("transports/hp_tcp/advertise_address", "127.0.0.1");
+    config->set("transports/hp_tcp/port", 0);
+    config->set("transports/hp_tcp/worker_count", 4);
+    config->set("transports/hp_tcp/connections_per_peer", 4);
+    config->set("transports/hp_tcp/max_outstanding_tasks", 128);
+    config->set("transports/hp_tcp/max_outstanding_bytes", 64ULL << 20);
+    config->set("transports/hp_tcp/max_transfer_bytes", 8ULL << 20);
+    config->set("transports/hp_tcp/connect_timeout_ms", 2000);
+    config->set("transports/hp_tcp/progress_timeout_ms", 5000);
+    if (multi_rail) {
+        config->set("transports/hp_tcp/bind_address", "");
+        config->set("transports/hp_tcp/rail_addresses",
+                    std::vector<std::string>{"127.0.0.1", "127.0.0.2"});
+    }
+    config->set("transports/rdma/enable", false);
+    config->set("transports/shm/enable", false);
+    config->set("rpc_server_threads", 1);
+    return config;
+}
+
+bool WaitBatchDone(TransferEngine& engine, BatchID batch) {
+    TransferStatus status;
+    for (int i = 0; i < 10000; ++i) {
+        const Status result = engine.getTransferStatus(batch, status);
+        if (!result.ok() || status.s == FAILED || status.s == CANCELED ||
+            status.s == TIMEOUT || status.s == INVALID) {
+            return false;
+        }
+        if (status.s == COMPLETED) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return false;
+}
+
+void RunWriteThenReadAcrossProcesses(size_t task_count, bool multi_rail,
+                                     size_t data_length = 256 * 1024) {
+    const size_t remote_buffer_length = task_count * data_length;
+    const size_t local_buffer_length = 2 * remote_buffer_length;
+
+    int ready_pipe[2];
+    int stop_pipe[2];
+    ASSERT_EQ(pipe(ready_pipe), 0);
+    ASSERT_EQ(pipe(stop_pipe), 0);
+
+    const pid_t child = fork();
+    ASSERT_GE(child, 0);
+    if (child == 0) {
+        close(ready_pipe[0]);
+        close(stop_pipe[1]);
+
+        int exit_code = 0;
+        {
+            std::vector<uint8_t> remote(remote_buffer_length, 0);
+            TransferEngine server(MakeHpConfig(multi_rail));
+            if (!server.available()) {
+                exit_code = 2;
+            } else {
+                const Status registered = server.registerLocalMemory(
+                    remote.data(), remote.size(), kGlobalReadWrite);
+                if (!registered.ok()) {
+                    exit_code = 3;
+                } else {
+                    const std::string segment = server.getSegmentName();
+                    const uint32_t length =
+                        static_cast<uint32_t>(segment.size());
+                    if (write(ready_pipe[1], &length, sizeof(length)) !=
+                        static_cast<ssize_t>(sizeof(length))) {
+                        exit_code = 4;
+                    } else if (write(ready_pipe[1], segment.data(), length) !=
+                               static_cast<ssize_t>(length)) {
+                        exit_code = 5;
+                    } else {
+                        char stop = 0;
+                        (void)ReadExactly(stop_pipe[0], &stop, 1);
+                    }
+                    if (!server
+                             .unregisterLocalMemory(remote.data(),
+                                                    remote.size())
+                             .ok() &&
+                        exit_code == 0) {
+                        exit_code = 6;
+                    }
+                }
+            }
+        }
+        close(ready_pipe[1]);
+        close(stop_pipe[0]);
+        _exit(exit_code);
+    }
+
+    close(ready_pipe[1]);
+    close(stop_pipe[0]);
+    ChildProcessGuard child_guard(child, stop_pipe[1]);
+
+    uint32_t segment_length = 0;
+    if (!ReadExactly(ready_pipe[0], &segment_length, sizeof(segment_length))) {
+        close(ready_pipe[0]);
+        const int status = child_guard.finish();
+        FAIL() << "HP TCP server initialization failed, child status "
+               << status;
+    }
+    std::string server_segment(segment_length, '\0');
+    if (!ReadExactly(ready_pipe[0], server_segment.data(), segment_length)) {
+        close(ready_pipe[0]);
+        const int status = child_guard.finish();
+        FAIL() << "Failed to read the HP TCP server segment, child status "
+               << status;
+    }
+    close(ready_pipe[0]);
+
+    std::vector<uint8_t> local(local_buffer_length, 0);
+    auto client_config = MakeHpConfig(multi_rail);
+    // The remote limit (8 MiB), not just the local limit, must bound merging.
+    client_config->set("transports/hp_tcp/max_transfer_bytes", 16ULL << 20);
+    TransferEngine client(client_config);
+    ASSERT_TRUE(client.available());
+    std::mt19937 data(3834);
+    for (size_t task = 0; task < task_count; ++task) {
+        uint8_t* source = local.data() + task * data_length;
+        for (size_t i = 0; i < data_length; ++i) {
+            source[i] = static_cast<uint8_t>(data());
+        }
+    }
+    ASSERT_TRUE(
+        client.registerLocalMemory(local.data(), local.size(), kGlobalReadWrite)
+            .ok());
+
+    SegmentID segment = 0;
+    Status result;
+    for (int i = 0; i < 100; ++i) {
+        result = client.openSegment(segment, server_segment);
+        if (result.ok()) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(result.ok()) << result.ToString();
+
+    SegmentInfo info;
+    ASSERT_TRUE(client.getSegmentInfo(segment, info).ok());
+    ASSERT_FALSE(info.buffers.empty());
+
+    std::vector<Request> writes;
+    std::vector<Request> reads;
+    writes.reserve(task_count);
+    reads.reserve(task_count);
+    for (size_t task = 0; task < task_count; ++task) {
+        Request write_request{};
+        write_request.opcode = Request::WRITE;
+        write_request.source = local.data() + task * data_length;
+        write_request.target_id = segment;
+        write_request.target_offset = info.buffers[0].base + task * data_length;
+        write_request.length = data_length;
+        write_request.transport_hint = HP_TCP;
+        writes.push_back(write_request);
+
+        Request read_request{};
+        read_request.opcode = Request::READ;
+        read_request.source =
+            local.data() + remote_buffer_length + task * data_length;
+        read_request.target_id = segment;
+        read_request.target_offset = info.buffers[0].base + task * data_length;
+        read_request.length = data_length;
+        // With only HP TCP enabled, also cover its implicit selection.
+        read_request.transport_hint = UNSPEC;
+        reads.push_back(read_request);
+    }
+
+    BatchID batch = client.allocateBatch(task_count);
+    ASSERT_TRUE(client.submitTransfer(batch, writes).ok());
+    ASSERT_TRUE(WaitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    batch = client.allocateBatch(task_count);
+    ASSERT_TRUE(client.submitTransfer(batch, reads).ok());
+    ASSERT_TRUE(WaitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    for (size_t task = 0; task < task_count; ++task) {
+        const uint8_t* written = local.data() + task * data_length;
+        const uint8_t* read_back =
+            local.data() + remote_buffer_length + task * data_length;
+        EXPECT_EQ(std::memcmp(written, read_back, data_length), 0)
+            << "task " << task << " mismatch";
+    }
+
+    EXPECT_TRUE(client.closeSegment(segment).ok());
+    EXPECT_TRUE(client.unregisterLocalMemory(local.data(), local.size()).ok());
+
+    const int status = child_guard.finish();
+    ASSERT_TRUE(WIFEXITED(status));
+    EXPECT_EQ(WEXITSTATUS(status), 0);
+}
+
+TEST(HighPerformanceTcpE2eTest, WriteThenReadConcurrency16) {
+    RunWriteThenReadAcrossProcesses(16, false);
+}
+
+TEST(HighPerformanceTcpE2eTest, WriteThenReadAcrossTwoRails) {
+    RunWriteThenReadAcrossProcesses(16, true);
+}
+
+TEST(HighPerformanceTcpE2eTest, UnevenSlicedReadAcrossProcesses) {
+    RunWriteThenReadAcrossProcesses(4, true, (4ULL << 20) + 3);
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_protocol_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_protocol_test.cpp
new file mode 100644
index 0000000000..0573336396
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_protocol_test.cpp
@@ -0,0 +1,109 @@
+// Copyright 2026 KVCache.AI
+#include <gtest/gtest.h>
+
+#include <limits>
+
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+
+namespace mooncake::tent {
+namespace {
+
+TEST(HighPerformanceTcpProtocolTest, RequestAndResponseRoundTrip) {
+    const HighPerformanceTcpRequestFrame request{
+        HighPerformanceTcpOpcode::kWrite, 11, 22, 33, 44};
+    const auto request_bytes = EncodeHighPerformanceTcpRequest(request);
+    HighPerformanceTcpRequestFrame decoded_request;
+    ASSERT_TRUE(DecodeHighPerformanceTcpRequest(request_bytes.data(),
+                                                request_bytes.size(),
+                                                &decoded_request)
+                    .ok());
+    EXPECT_EQ(decoded_request.opcode, request.opcode);
+    EXPECT_EQ(decoded_request.request_id, request.request_id);
+    EXPECT_EQ(decoded_request.registration_id, request.registration_id);
+    EXPECT_EQ(decoded_request.remote_addr, request.remote_addr);
+    EXPECT_EQ(decoded_request.length, request.length);
+
+    const HighPerformanceTcpResponseFrame response{
+        HighPerformanceTcpStatus::kOk, request.request_id, request.length};
+    const auto response_bytes = EncodeHighPerformanceTcpResponse(response);
+    HighPerformanceTcpResponseFrame decoded_response;
+    ASSERT_TRUE(DecodeHighPerformanceTcpResponse(response_bytes.data(),
+                                                 response_bytes.size(),
+                                                 &decoded_response)
+                    .ok());
+    EXPECT_EQ(decoded_response.status, response.status);
+    EXPECT_EQ(decoded_response.request_id, response.request_id);
+    EXPECT_EQ(decoded_response.committed_bytes, response.committed_bytes);
+}
+
+TEST(HighPerformanceTcpProtocolTest, RejectsMalformedWireFrames) {
+    auto request = EncodeHighPerformanceTcpRequest(
+        {HighPerformanceTcpOpcode::kRead, 1, 2, 3, 4});
+    HighPerformanceTcpRequestFrame decoded;
+    HighPerformanceTcpStatus wire_error = HighPerformanceTcpStatus::kOk;
+    request[5] = 2;
+    EXPECT_FALSE(DecodeHighPerformanceTcpRequest(request.data(), request.size(),
+                                                 &decoded, &wire_error)
+                     .ok());
+    EXPECT_EQ(wire_error, HighPerformanceTcpStatus::kBadVersion);
+    request[5] = 1;
+    request[6] = 0xff;
+    EXPECT_FALSE(DecodeHighPerformanceTcpRequest(request.data(), request.size(),
+                                                 &decoded, &wire_error)
+                     .ok());
+    EXPECT_EQ(wire_error, HighPerformanceTcpStatus::kBadOpcode);
+}
+
+TEST(HighPerformanceTcpProtocolTest, MetadataAttributesRoundTrip) {
+    HighPerformanceTcpEndpointAttr endpoint{
+        "00112233445566778899aabbccddeeff", {{"127.0.0.1", 1234}}, 4096};
+    std::string encoded;
+    ASSERT_TRUE(EncodeHighPerformanceTcpEndpointAttr(endpoint, &encoded).ok());
+    HighPerformanceTcpEndpointAttr decoded_endpoint;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpEndpointAttr(encoded, &decoded_endpoint).ok());
+    EXPECT_EQ(decoded_endpoint.incarnation, endpoint.incarnation);
+    ASSERT_EQ(decoded_endpoint.endpoints.size(), 1U);
+    EXPECT_EQ(decoded_endpoint.endpoints[0].host, "127.0.0.1");
+    EXPECT_EQ(decoded_endpoint.endpoints[0].port, 1234);
+
+    ASSERT_TRUE(
+        EncodeHighPerformanceTcpBufferAttr({42, "global_read_write"}, &encoded)
+            .ok());
+    HighPerformanceTcpBufferAttr decoded_buffer;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpBufferAttr(encoded, &decoded_buffer).ok());
+    EXPECT_EQ(decoded_buffer.registration_id, 42u);
+    EXPECT_EQ(decoded_buffer.permission, "global_read_write");
+
+    const uint64_t max_registration_id = std::numeric_limits<uint64_t>::max();
+    ASSERT_TRUE(EncodeHighPerformanceTcpBufferAttr(
+                    {max_registration_id, "global_read_only"}, &encoded)
+                    .ok());
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpBufferAttr(encoded, &decoded_buffer).ok());
+    EXPECT_EQ(decoded_buffer.registration_id, max_registration_id);
+    EXPECT_EQ(decoded_buffer.permission, "global_read_only");
+
+    EXPECT_FALSE(
+        DecodeHighPerformanceTcpEndpointAttr("not-json", &decoded_endpoint)
+            .ok());
+}
+
+TEST(HighPerformanceTcpProtocolTest, MultiRailMetadataRoundTrip) {
+    HighPerformanceTcpEndpointAttr endpoint{
+        "00112233445566778899aabbccddeeff",
+        {{"127.0.0.1", 1234}, {"127.0.0.2", 1234}},
+        4096};
+    std::string encoded;
+    ASSERT_TRUE(EncodeHighPerformanceTcpEndpointAttr(endpoint, &encoded).ok());
+    HighPerformanceTcpEndpointAttr decoded;
+    ASSERT_TRUE(DecodeHighPerformanceTcpEndpointAttr(encoded, &decoded).ok());
+    ASSERT_EQ(decoded.endpoints.size(), 2U);
+    EXPECT_EQ(decoded.endpoints[0].host, "127.0.0.1");
+    EXPECT_EQ(decoded.endpoints[1].host, "127.0.0.2");
+    EXPECT_EQ(decoded.endpoints[1].port, 1234);
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_socket_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_socket_test.cpp
new file mode 100644
index 0000000000..7318cdd620
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_socket_test.cpp
@@ -0,0 +1,654 @@
+// Copyright 2026 KVCache.AI
+#include <gtest/gtest.h>
+
+#include <asio.hpp>
+
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <optional>
+#include <thread>
+
+#include "tent/transport/hp_tcp/hp_tcp_client.h"
+#include "tent/transport/hp_tcp/hp_tcp_server.h"
+
+namespace mooncake::tent {
+namespace {
+using namespace std::chrono_literals;
+constexpr char kIncarnation[] = "00112233445566778899aabbccddeeff";
+
+struct Completion {
+    std::atomic<bool> done{false};
+    TransferStatusEnum status{PENDING};
+    size_t bytes{0};
+    std::optional<HighPerformanceTcpStatus> protocol_status;
+
+    auto callback() {
+        return [this](TransferStatusEnum value, size_t count,
+                      std::optional<HighPerformanceTcpStatus> result) {
+            status = value;
+            bytes = count;
+            protocol_status = result;
+            done.store(true, std::memory_order_release);
+        };
+    }
+    bool wait() {
+        const auto deadline = std::chrono::steady_clock::now() + 2s;
+        while (!done.load(std::memory_order_acquire) &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::sleep_for(1ms);
+        }
+        return done.load(std::memory_order_acquire);
+    }
+};
+
+template <class Predicate>
+bool WaitUntil(Predicate predicate) {
+    const auto deadline = std::chrono::steady_clock::now() + 2s;
+    while (!predicate() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(1ms);
+    }
+    return predicate();
+}
+
+// Kernel TCP orders the remote write before its response, but that ordering is
+// not visible to ThreadSanitizer as a C++ happens-before edge.
+template <size_t N>
+__attribute__((no_sanitize("thread"))) bool SocketOrderedEqual(
+    const std::array<uint8_t, N>& left, const std::array<uint8_t, N>& right) {
+    return left == right;
+}
+
+class Runtime {
+   public:
+    explicit Runtime(size_t max_connections = 16, uint64_t timeout_ms = 500,
+                     uint64_t idle_timeout_ms = 60000)
+        : workers({.worker_count = 2}),
+          client({.max_transfer_bytes = 1 << 20,
+                  .chunk_size = 128,
+                  .connect_timeout_ms = 500,
+                  .progress_timeout_ms = timeout_ms,
+                  .connections_per_peer = 2,
+                  .idle_connection_timeout_ms = idle_timeout_ms},
+                 &workers),
+          server({.bind_address = "127.0.0.1",
+                  .port = 0,
+                  .max_transfer_bytes = 1 << 20,
+                  .chunk_size = 128,
+                  .progress_timeout_ms = timeout_ms,
+                  .max_connections = max_connections},
+                 &registry, &workers) {}
+
+    ~Runtime() {
+        (void)server.stopAccepting();
+        (void)client.cancelAll();
+        (void)server.stop();
+        (void)workers.stop();
+    }
+    void start() {
+        ASSERT_TRUE(workers.start().ok());
+        ASSERT_TRUE(server.start(&port).ok());
+    }
+    Status submit(HighPerformanceTcpClient::Operation operation) {
+        const size_t owner =
+            workers.affinityOwner(operation.peer_id, operation.lane_id);
+        std::vector<HighPerformanceTcpWorkers::Command> commands;
+        commands.push_back({.worker_id = owner,
+                            .run =
+                                [this, owner, operation = std::move(operation)](
+                                    size_t) mutable {
+                                    client.enqueueOnOwner(owner,
+                                                          std::move(operation));
+                                },
+                            .cancel = {}});
+        return workers.tryCommitBatch(commands, nullptr, 0, 0, [] {});
+    }
+
+    HighPerformanceTcpWorkers workers;
+    HighPerformanceTcpBufferRegistry registry;
+    HighPerformanceTcpClient client;
+    HighPerformanceTcpServer server;
+    uint16_t port{0};
+};
+
+HighPerformanceTcpClient::Operation Operation(
+    void* local, size_t length, uint64_t remote, uint64_t registration,
+    uint64_t request_id, HighPerformanceTcpOpcode opcode,
+    Completion* completion, uint16_t port) {
+    HighPerformanceTcpClient::Operation operation;
+    operation.peer_id = 7;
+    operation.incarnation = kIncarnation;
+    operation.host = "127.0.0.1";
+    operation.port = port;
+    operation.registration_id = registration;
+    operation.remote_addr = remote;
+    operation.local_addr = local;
+    operation.length = length;
+    operation.opcode = opcode;
+    operation.request_id = request_id;
+    operation.complete = completion->callback();
+    return operation;
+}
+
+TEST(HighPerformanceTcpSocketTest, WriteReadAndReuseConnection) {
+    Runtime runtime(/*max_connections=*/16, /*timeout_ms=*/100);
+    runtime.start();
+    std::array<uint8_t, 1024> remote{};
+    std::array<uint8_t, 1024> source{};
+    std::array<uint8_t, 1024> destination{};
+    source.fill(0x5a);
+    uint64_t registration = 0;
+    ASSERT_TRUE(runtime.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadWrite, &registration)
+                    .ok());
+
+    Completion write;
+    ASSERT_TRUE(
+        runtime
+            .submit(Operation(source.data(), source.size(),
+                              reinterpret_cast<uint64_t>(remote.data()),
+                              registration, 1, HighPerformanceTcpOpcode::kWrite,
+                              &write, runtime.port))
+            .ok());
+    ASSERT_TRUE(write.wait());
+    EXPECT_EQ(write.status, COMPLETED);
+    EXPECT_TRUE(SocketOrderedEqual(remote, source));
+
+    std::this_thread::sleep_for(300ms);
+    ASSERT_EQ(runtime.server.activeSessionsForTest(), 1u);
+
+    Completion read;
+    ASSERT_TRUE(
+        runtime
+            .submit(Operation(destination.data(), destination.size(),
+                              reinterpret_cast<uint64_t>(remote.data()),
+                              registration, 2, HighPerformanceTcpOpcode::kRead,
+                              &read, runtime.port))
+            .ok());
+    ASSERT_TRUE(read.wait());
+    EXPECT_EQ(read.status, COMPLETED);
+    EXPECT_TRUE(SocketOrderedEqual(destination, source));
+    EXPECT_EQ(runtime.client.connectionsCreatedForTest(), 1u);
+}
+
+TEST(HighPerformanceTcpSocketTest, IdleClientsReleaseCapacityAndReconnect) {
+    std::array<uint8_t, 4> remote{};
+    std::array<uint8_t, 4> source{1, 2, 3, 4};
+    Runtime runtime(/*max_connections=*/2, /*timeout_ms=*/500,
+                    /*idle_timeout_ms=*/500);
+    runtime.start();
+    uint64_t registration = 0;
+    ASSERT_TRUE(runtime.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadWrite, &registration)
+                    .ok());
+    uint64_t request_id = 1;
+    auto write = [&](SegmentID peer_id, Completion& completion) {
+        auto operation =
+            Operation(source.data(), source.size(),
+                      reinterpret_cast<uint64_t>(remote.data()), registration,
+                      request_id++, HighPerformanceTcpOpcode::kWrite,
+                      &completion, runtime.port);
+        operation.peer_id = peer_id;
+        return runtime.submit(std::move(operation));
+    };
+    for (SegmentID peer_id : {1, 2}) {
+        Completion completion;
+        ASSERT_TRUE(write(peer_id, completion).ok());
+        ASSERT_TRUE(completion.wait());
+        ASSERT_EQ(completion.status, COMPLETED);
+    }
+    ASSERT_EQ(runtime.server.activeSessionsForTest(), 2u);
+    Completion rejected;
+    ASSERT_TRUE(write(3, rejected).ok());
+    ASSERT_TRUE(rejected.wait());
+    EXPECT_EQ(rejected.status, FAILED);
+
+    // Completed historical traffic must eventually give up receiver slots.
+    // No server eviction or explicit client shutdown is needed.
+    ASSERT_TRUE(
+        WaitUntil([&] { return runtime.server.activeSessionsForTest() == 0; }));
+    Completion newcomer;
+    ASSERT_TRUE(write(3, newcomer).ok());
+    ASSERT_TRUE(newcomer.wait());
+    ASSERT_EQ(newcomer.status, COMPLETED);
+    EXPECT_TRUE(SocketOrderedEqual(remote, source));
+
+    // The original lane remains usable after its socket was reclaimed.
+    source.fill(0x5a);
+    Completion reconnect;
+    ASSERT_TRUE(write(1, reconnect).ok());
+    ASSERT_TRUE(reconnect.wait());
+    EXPECT_EQ(reconnect.status, COMPLETED);
+    EXPECT_EQ(reconnect.bytes, source.size());
+    EXPECT_FALSE(reconnect.protocol_status.has_value());
+    EXPECT_TRUE(SocketOrderedEqual(remote, source));
+}
+
+TEST(HighPerformanceTcpSocketTest, IdleTimerDoesNotExpireActiveOrQueuedWrites) {
+    std::array<uint8_t, 4> remote{};
+    std::array<uint8_t, 4> source{1, 2, 3, 4};
+    Runtime receiver(/*max_connections=*/16, /*timeout_ms=*/1000);
+    Runtime sender(/*max_connections=*/16, /*timeout_ms=*/1000,
+                   /*idle_timeout_ms=*/100);
+    receiver.start();
+    sender.start();
+    uint64_t registration = 0;
+    ASSERT_TRUE(receiver.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadWrite, &registration)
+                    .ok());
+    auto write = [&](uint64_t id, Completion& completion) {
+        return sender.submit(Operation(
+            source.data(), source.size(),
+            reinterpret_cast<uint64_t>(remote.data()), registration, id,
+            HighPerformanceTcpOpcode::kWrite, &completion, receiver.port));
+    };
+    Completion warm;
+    ASSERT_TRUE(write(1, warm).ok());
+    ASSERT_TRUE(warm.wait());
+    ASSERT_EQ(warm.status, COMPLETED);
+
+    // The first accepted session belongs to receiver worker 0. Hold it while
+    // the client's old idle deadline passes, with one WRITE awaiting its ACK
+    // and another queued. Sender workers and their timers keep running.
+    std::promise<void> entered;
+    std::promise<void> release;
+    auto resume = release.get_future().share();
+    asio::post(receiver.workers.ioContext(0), [&] {
+        entered.set_value();
+        resume.wait();
+    });
+    const auto entered_status = entered.get_future().wait_for(2s);
+    Completion first;
+    Completion second;
+    const Status submit_first = write(2, first);
+    const Status submit_second = write(3, second);
+    std::this_thread::sleep_for(200ms);
+    const bool prematurely_done = first.done.load(std::memory_order_acquire) ||
+                                  second.done.load(std::memory_order_acquire);
+    release.set_value();
+
+    ASSERT_EQ(entered_status, std::future_status::ready);
+    ASSERT_TRUE(submit_first.ok());
+    ASSERT_TRUE(submit_second.ok());
+    EXPECT_FALSE(prematurely_done);
+    ASSERT_TRUE(first.wait());
+    ASSERT_TRUE(second.wait());
+    EXPECT_EQ(first.status, COMPLETED);
+    EXPECT_EQ(second.status, COMPLETED);
+    EXPECT_EQ(sender.client.connectionsCreatedForTest(), 1u);
+    EXPECT_TRUE(SocketOrderedEqual(remote, source));
+}
+
+TEST(HighPerformanceTcpSocketTest, RejectedWriteBodyCannotBecomeNextFrame) {
+    Runtime runtime;
+    runtime.start();
+    std::array<uint8_t, 64> remote{};
+    uint64_t registration = 0;
+    ASSERT_TRUE(runtime.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadWrite, &registration)
+                    .ok());
+
+    asio::io_context io;
+    asio::ip::tcp::socket socket(io);
+    socket.connect({asio::ip::make_address("127.0.0.1"), runtime.port});
+    const auto rejected = EncodeHighPerformanceTcpRequest(
+        {HighPerformanceTcpOpcode::kWrite, 20, registration + 1,
+         reinterpret_cast<uint64_t>(remote.data()),
+         kHighPerformanceTcpRequestSize + 1});
+    const auto hidden = EncodeHighPerformanceTcpRequest(
+        {HighPerformanceTcpOpcode::kWrite, 21, registration,
+         reinterpret_cast<uint64_t>(remote.data()), 1});
+    const uint8_t hidden_body = 0x5a;
+    asio::write(socket, asio::buffer(rejected));
+    asio::write(socket, asio::buffer(hidden));
+    asio::write(socket, asio::buffer(&hidden_body, 1));
+
+    std::array<uint8_t, kHighPerformanceTcpResponseSize> response_bytes{};
+    ASSERT_EQ(asio::read(socket, asio::buffer(response_bytes)),
+              response_bytes.size());
+    HighPerformanceTcpResponseFrame response;
+    ASSERT_TRUE(DecodeHighPerformanceTcpResponse(
+                    response_bytes.data(), response_bytes.size(), &response)
+                    .ok());
+    EXPECT_EQ(response.status, HighPerformanceTcpStatus::kStaleRegistration);
+    EXPECT_EQ(response.request_id, 20u);
+    EXPECT_EQ(response.committed_bytes, 0u);
+    EXPECT_EQ(remote[0], 0u);
+    EXPECT_TRUE(
+        WaitUntil([&] { return runtime.server.activeSessionsForTest() == 0; }));
+}
+
+TEST(HighPerformanceTcpSocketTest,
+     RejectedWritePartialPayloadTimesOutAndReleasesSlot) {
+    Runtime runtime(/*max_connections=*/1, /*timeout_ms=*/100);
+    runtime.start();
+    std::array<uint8_t, 1> remote{};
+    uint64_t registration = 0;
+    ASSERT_TRUE(runtime.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadWrite, &registration)
+                    .ok());
+
+    asio::io_context io;
+    asio::ip::tcp::socket socket(io);
+    socket.connect({asio::ip::make_address("127.0.0.1"), runtime.port});
+    const auto rejected = EncodeHighPerformanceTcpRequest(
+        {HighPerformanceTcpOpcode::kWrite, 22, registration + 1,
+         reinterpret_cast<uint64_t>(remote.data()), 1024});
+    const uint8_t one_body_byte = 0;
+    asio::write(socket, asio::buffer(rejected));
+    asio::write(socket, asio::buffer(&one_body_byte, 1));
+    ASSERT_TRUE(
+        WaitUntil([&] { return runtime.server.activeSessionsForTest() == 1; }));
+    EXPECT_TRUE(
+        WaitUntil([&] { return runtime.server.activeSessionsForTest() == 0; }));
+    EXPECT_EQ(remote[0], 0u);
+}
+
+TEST(HighPerformanceTcpSocketTest, ClientProgressTimeoutCompletesTask) {
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io, {asio::ip::tcp::v4(), 0});
+    std::thread peer([&] {
+        asio::ip::tcp::socket socket(peer_io);
+        acceptor.accept(socket);
+        std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+        asio::read(socket, asio::buffer(request));
+        std::this_thread::sleep_for(200ms);
+    });
+
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({4096, 128, 100, 30, 1}, &workers);
+    std::array<uint8_t, 64> local{};
+    Completion completion;
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 3,
+                               HighPerformanceTcpOpcode::kRead, &completion,
+                               acceptor.local_endpoint().port());
+    std::vector<HighPerformanceTcpWorkers::Command> commands;
+    commands.push_back({.worker_id = 0,
+                        .run =
+                            [&](size_t) mutable {
+                                client.enqueueOnOwner(0, std::move(operation));
+                            },
+                        .cancel = {}});
+    ASSERT_TRUE(workers.tryCommitBatch(commands, nullptr, 0, 0, [] {}).ok());
+    ASSERT_TRUE(completion.wait());
+    EXPECT_EQ(completion.status, TIMEOUT);
+    EXPECT_FALSE(completion.protocol_status.has_value());
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    peer.join();
+}
+
+TEST(HighPerformanceTcpSocketTest, FragmentedReadBodyCompletesAcrossChunkTail) {
+    constexpr size_t kChunk = 1 << 20;
+    constexpr size_t kLength = kChunk + 17;
+    std::array<uint8_t, kLength> payload{};
+    std::array<uint8_t, kLength> local{};
+    for (size_t i = 0; i < payload.size(); ++i) payload[i] = i % 251;
+    Completion completion;
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io, {asio::ip::tcp::v4(), 0});
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({2 * kChunk, kChunk, 1000, 1000, 1},
+                                    &workers);
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 41,
+                               HighPerformanceTcpOpcode::kRead, &completion,
+                               acceptor.local_endpoint().port());
+    asio::post(workers.ioContext(0),
+               [&client, operation = std::move(operation)]() mutable {
+                   client.enqueueOnOwner(0, std::move(operation));
+               });
+
+    asio::ip::tcp::socket socket(peer_io);
+    acceptor.accept(socket);
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+    asio::read(socket, asio::buffer(request));
+    const auto response = EncodeHighPerformanceTcpResponse(
+        {HighPerformanceTcpStatus::kOk, 41, kLength});
+    asio::write(socket, asio::buffer(response));
+    asio::write(socket, asio::buffer(payload.data(), 65533));
+    std::this_thread::sleep_for(1ms);
+    EXPECT_FALSE(completion.done.load(std::memory_order_acquire));
+    asio::write(socket, asio::buffer(payload.data() + 65533, 29));
+    std::this_thread::sleep_for(1ms);
+    asio::write(socket, asio::buffer(payload.data() + 65562, kLength - 65562));
+    const bool completed = completion.wait();
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    ASSERT_TRUE(completed);
+    EXPECT_EQ(completion.status, COMPLETED);
+    EXPECT_EQ(completion.bytes, kLength);
+    EXPECT_FALSE(completion.protocol_status.has_value());
+    EXPECT_TRUE(SocketOrderedEqual(local, payload));
+}
+
+TEST(HighPerformanceTcpSocketTest,
+     TruncatedReadBodyTailFailsAfterValidResponse) {
+    constexpr size_t kChunk = 1 << 20;
+    constexpr size_t kLength = kChunk + 17;
+    std::array<uint8_t, kLength> payload{};
+    std::array<uint8_t, kLength> local{};
+    payload.fill(0x5a);
+    Completion completion;
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io, {asio::ip::tcp::v4(), 0});
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({2 * kChunk, kChunk, 1000, 1000, 1},
+                                    &workers);
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 42,
+                               HighPerformanceTcpOpcode::kRead, &completion,
+                               acceptor.local_endpoint().port());
+    asio::post(workers.ioContext(0),
+               [&client, operation = std::move(operation)]() mutable {
+                   client.enqueueOnOwner(0, std::move(operation));
+               });
+
+    asio::ip::tcp::socket socket(peer_io);
+    acceptor.accept(socket);
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+    asio::read(socket, asio::buffer(request));
+    const auto response = EncodeHighPerformanceTcpResponse(
+        {HighPerformanceTcpStatus::kOk, 42, kLength});
+    asio::write(socket, asio::buffer(response));
+    asio::write(socket, asio::buffer(payload.data(), kLength - 1));
+    socket.shutdown(asio::ip::tcp::socket::shutdown_send);
+    const bool completed = completion.wait();
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    ASSERT_TRUE(completed);
+    EXPECT_EQ(completion.status, FAILED);
+    EXPECT_EQ(completion.bytes, 0u);
+    EXPECT_FALSE(completion.protocol_status.has_value());
+}
+
+TEST(HighPerformanceTcpSocketTest,
+     StalledReadBodyTailTimesOutAfterValidResponse) {
+    constexpr size_t kChunk = 1 << 20;
+    constexpr size_t kLength = kChunk + 17;
+    std::array<uint8_t, kLength> payload{};
+    std::array<uint8_t, kLength> local{};
+    payload.fill(0x5a);
+    Completion completion;
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io, {asio::ip::tcp::v4(), 0});
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({2 * kChunk, kChunk, 1000, 100, 1},
+                                    &workers);
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 43,
+                               HighPerformanceTcpOpcode::kRead, &completion,
+                               acceptor.local_endpoint().port());
+    asio::post(workers.ioContext(0),
+               [&client, operation = std::move(operation)]() mutable {
+                   client.enqueueOnOwner(0, std::move(operation));
+               });
+
+    asio::ip::tcp::socket socket(peer_io);
+    acceptor.accept(socket);
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+    asio::read(socket, asio::buffer(request));
+    const auto response = EncodeHighPerformanceTcpResponse(
+        {HighPerformanceTcpStatus::kOk, 43, kLength});
+    asio::write(socket, asio::buffer(response));
+    asio::write(socket, asio::buffer(payload.data(), kChunk + 7));
+    // Leave the peer open without the last ten bytes: this must time out,
+    // rather than treating the successful response or first chunk as done.
+    const bool completed = completion.wait();
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    ASSERT_TRUE(completed);
+    EXPECT_EQ(completion.status, TIMEOUT);
+    EXPECT_EQ(completion.bytes, 0u);
+    EXPECT_FALSE(completion.protocol_status.has_value());
+}
+
+TEST(HighPerformanceTcpSocketTest, ClientBindsConfiguredSourceAddress) {
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io,
+                                     {asio::ip::make_address("127.0.0.1"), 0});
+    std::string peer_address;
+    std::thread peer([&] {
+        asio::ip::tcp::socket socket(peer_io);
+        acceptor.accept(socket);
+        peer_address = socket.remote_endpoint().address().to_string();
+        std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+        asio::read(socket, asio::buffer(request));
+        const auto response = EncodeHighPerformanceTcpResponse(
+            {HighPerformanceTcpStatus::kOk, 4, 1});
+        asio::write(socket, asio::buffer(response));
+        const uint8_t payload = 0x5a;
+        asio::write(socket, asio::buffer(&payload, 1));
+    });
+
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({4096, 128, 1000, 1000, 1}, &workers);
+    std::array<uint8_t, 1> local{};
+    Completion completion;
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 4,
+                               HighPerformanceTcpOpcode::kRead, &completion,
+                               acceptor.local_endpoint().port());
+    operation.local_host = "127.0.0.2";
+    std::vector<HighPerformanceTcpWorkers::Command> commands;
+    commands.push_back({.worker_id = 0,
+                        .run =
+                            [&](size_t) mutable {
+                                client.enqueueOnOwner(0, std::move(operation));
+                            },
+                        .cancel = {}});
+    ASSERT_TRUE(workers.tryCommitBatch(commands, nullptr, 0, 0, [] {}).ok());
+    ASSERT_TRUE(completion.wait());
+    EXPECT_EQ(completion.status, COMPLETED);
+    EXPECT_EQ(local[0], 0x5a);
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    peer.join();
+    EXPECT_EQ(peer_address, "127.0.0.2");
+}
+
+TEST(HighPerformanceTcpSocketTest,
+     WriteWithoutCompletionAckMarksRemoteOutcomeUnknown) {
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor acceptor(peer_io, {asio::ip::tcp::v4(), 0});
+    std::thread peer([&] {
+        asio::ip::tcp::socket socket(peer_io);
+        acceptor.accept(socket);
+        std::array<uint8_t, kHighPerformanceTcpRequestSize> request{};
+        std::array<uint8_t, 64> body{};
+        asio::read(socket, asio::buffer(request));
+        asio::read(socket, asio::buffer(body));
+        socket.close();  // The payload arrived, but no completion ACK did.
+    });
+
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpClient client({4096, 128, 100, 100, 1}, &workers);
+    std::array<uint8_t, 64> local{};
+    Completion completion;
+    auto operation = Operation(local.data(), local.size(), 0x1000, 1, 31,
+                               HighPerformanceTcpOpcode::kWrite, &completion,
+                               acceptor.local_endpoint().port());
+    std::vector<HighPerformanceTcpWorkers::Command> commands;
+    commands.push_back({.worker_id = 0,
+                        .run =
+                            [&](size_t) mutable {
+                                client.enqueueOnOwner(0, std::move(operation));
+                            },
+                        .cancel = {}});
+    ASSERT_TRUE(workers.tryCommitBatch(commands, nullptr, 0, 0, [] {}).ok());
+    ASSERT_TRUE(completion.wait());
+    EXPECT_EQ(completion.status, FAILED);
+    EXPECT_EQ(completion.protocol_status,
+              HighPerformanceTcpStatus::kInternalError);
+    EXPECT_TRUE(client.cancelAll().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    peer.join();
+}
+
+TEST(HighPerformanceTcpSocketTest, EmptyAndPartialHeadersReleaseSlot) {
+    Runtime runtime(/*max_connections=*/1, /*timeout_ms=*/100);
+    runtime.start();
+    asio::io_context io;
+    {
+        asio::ip::tcp::socket socket(io);
+        socket.connect({asio::ip::make_address("127.0.0.1"), runtime.port});
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 1; }));
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 0; }));
+    }
+    {
+        asio::ip::tcp::socket socket(io);
+        socket.connect({asio::ip::make_address("127.0.0.1"), runtime.port});
+        const uint8_t byte = 0;
+        asio::write(socket, asio::buffer(&byte, 1));
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 1; }));
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 0; }));
+    }
+
+    std::array<uint8_t, 8> remote{};
+    std::array<uint8_t, 8> local{};
+    uint64_t registration = 0;
+    ASSERT_TRUE(runtime.registry
+                    .add(reinterpret_cast<uint64_t>(remote.data()),
+                         remote.size(), kGlobalReadOnly, &registration)
+                    .ok());
+    Completion completion;
+    ASSERT_TRUE(
+        runtime
+            .submit(Operation(local.data(), local.size(),
+                              reinterpret_cast<uint64_t>(remote.data()),
+                              registration, 4, HighPerformanceTcpOpcode::kRead,
+                              &completion, runtime.port))
+            .ok());
+    ASSERT_TRUE(completion.wait());
+    EXPECT_EQ(completion.status, COMPLETED);
+}
+
+TEST(HighPerformanceTcpSocketTest, ClosedSessionsAreReaped) {
+    Runtime runtime(/*max_connections=*/2);
+    runtime.start();
+    for (int i = 0; i < 8; ++i) {
+        asio::io_context io;
+        asio::ip::tcp::socket socket(io);
+        socket.connect({asio::ip::make_address("127.0.0.1"), runtime.port});
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 1; }));
+        socket.close();
+        ASSERT_TRUE(WaitUntil(
+            [&] { return runtime.server.activeSessionsForTest() == 0; }));
+    }
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_transport_config_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_transport_config_test.cpp
new file mode 100644
index 0000000000..62d3f9c30a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_transport_config_test.cpp
@@ -0,0 +1,126 @@
+// Copyright 2026 KVCache.AI
+#include <limits>
+
+#include <gtest/gtest.h>
+
+#include "tent/common/config.h"
+#include "tent/runtime/hp_tcp_transport_config.h"
+
+namespace mooncake::tent {
+namespace {
+
+TEST(HpTcpTransportConfigTest, DefaultsToDisabled) {
+    Config config;
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    EXPECT_FALSE(parsed.enabled);
+    EXPECT_EQ(parsed.params.idle_connection_timeout_ms, 60000U);
+}
+
+TEST(HpTcpTransportConfigTest, RejectsWrongLeafTypes) {
+    Config config;
+    ASSERT_TRUE(
+        config.load(R"({"transports":{"hp_tcp":{"enable":"yes"}}})").ok());
+    HpTcpTransportConfig parsed;
+    EXPECT_TRUE(ParseHpTcpTransportConfig(config, &parsed).IsInvalidArgument());
+
+    ASSERT_TRUE(
+        config.load(R"({"transports":{"hp_tcp":{"worker_count":"16"}}})").ok());
+    EXPECT_TRUE(ParseHpTcpTransportConfig(config, &parsed).IsInvalidArgument());
+}
+
+TEST(HpTcpTransportConfigTest, ParsesAndValidatesLimits) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"port":0,"worker_count":4,"connections_per_peer":2,"max_outstanding_tasks":16,"max_outstanding_bytes":4096,"max_transfer_bytes":1024,"connect_timeout_ms":1,"progress_timeout_ms":2}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    EXPECT_TRUE(parsed.enabled);
+    EXPECT_EQ(parsed.params.worker_count, 4U);
+
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"max_transfer_bytes":0}}})")
+            .ok());
+    EXPECT_TRUE(ParseHpTcpTransportConfig(config, &parsed).IsInvalidArgument());
+}
+
+TEST(HpTcpTransportConfigTest, ParsesRailAddresses) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"connections_per_peer":4,"rail_addresses":["10.0.0.1","10.1.0.1"]}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    ASSERT_EQ(parsed.params.rail_addresses.size(), 2U);
+    EXPECT_EQ(parsed.params.rail_addresses[1], "10.1.0.1");
+}
+
+TEST(HpTcpTransportConfigTest, ParsesIndependentIdleConnectionTimeout) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"idle_connection_timeout_ms":1234}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    EXPECT_EQ(parsed.params.idle_connection_timeout_ms, 1234U);
+    EXPECT_EQ(parsed.params.progress_timeout_ms, 30000U);
+    for (const char* value : {"0", "-1", "1.5", "\"100\""}) {
+        ASSERT_TRUE(
+            config
+                .load(
+                    std::string(
+                        R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"idle_connection_timeout_ms":)") +
+                    value + "}}}")
+                .ok());
+        EXPECT_TRUE(
+            ParseHpTcpTransportConfig(config, &parsed).IsInvalidArgument());
+    }
+}
+
+TEST(HpTcpTransportConfigTest, AcceptsFullWidthUnsignedLimit) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":false},"hp_tcp":{"enable":true,"max_outstanding_bytes":18446744073709551615}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    EXPECT_EQ(parsed.params.max_outstanding_bytes,
+              std::numeric_limits<uint64_t>::max());
+}
+
+TEST(HpTcpTransportConfigTest, DisabledHpTcpIgnoresInactiveLimits) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"hp_tcp":{"enable":false,"worker_count":0}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    ASSERT_TRUE(ParseHpTcpTransportConfig(config, &parsed).ok());
+    EXPECT_FALSE(parsed.enabled);
+}
+
+TEST(HpTcpTransportConfigTest, RejectsTcpAndHpTcpTogether) {
+    Config config;
+    ASSERT_TRUE(
+        config
+            .load(
+                R"({"transports":{"tcp":{"enable":true},"hp_tcp":{"enable":true}}})")
+            .ok());
+    HpTcpTransportConfig parsed;
+    EXPECT_TRUE(ParseHpTcpTransportConfig(config, &parsed).IsInvalidArgument());
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_transport_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_transport_test.cpp
new file mode 100644
index 0000000000..b561cb8e82
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_transport_test.cpp
@@ -0,0 +1,920 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <random>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/platform.h"
+#include "tent/transfer_engine.h"
+#include "tent/transport/hp_tcp/hp_tcp_protocol.h"
+#include "tent/transport/hp_tcp/hp_tcp_transport.h"
+
+namespace mooncake::tent {
+
+class HighPerformanceTcpTransportTestPeer {
+   public:
+    static void failWorker(HighPerformanceTcpTransport& transport) {
+        asio::post(transport.workers_->ioContext(0), [] {
+            throw std::runtime_error("injected HP TCP worker failure");
+        });
+    }
+
+    static bool hasFailedWorker(const HighPerformanceTcpTransport& transport) {
+        return transport.workers_->hasFailedWorker();
+    }
+
+    static Status barrier(HighPerformanceTcpTransport& transport) {
+        return transport.workers_->barrier();
+    }
+
+    static uint64_t activeSessions(
+        const HighPerformanceTcpTransport& transport) {
+        return transport.server_->activeSessionsForTest();
+    }
+};
+
+namespace {
+
+template <class Predicate>
+bool WaitUntil(Predicate predicate,
+               std::chrono::milliseconds timeout = std::chrono::seconds(2)) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (!predicate() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::yield();
+    }
+    return predicate();
+}
+
+std::shared_ptr<ControlService> MakeLocalMetadata() {
+    // Standalone transports also use the process-wide platform loader.
+    // Initialize it with a config before the full-engine cases probe topology.
+    (void)Platform::getLoader(std::make_shared<Config>());
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    EXPECT_TRUE(metadata->segmentManager()
+                    .updateLocal([](SegmentDesc& segment) -> Status {
+                        segment.name = "hp_transport_test";
+                        segment.machine_id = "hp_transport_test_machine";
+                        segment.rpc_server_addr = "127.0.0.1:40000";
+                        segment.type = SegmentType::Memory;
+                        std::get<MemorySegmentDesc>(segment.detail) =
+                            MemorySegmentDesc{};
+                        return Status::OK();
+                    })
+                    .ok());
+    return metadata;
+}
+
+HighPerformanceTcpParams MakeParams() {
+    HighPerformanceTcpParams params;
+    params.bind_address = "127.0.0.1";
+    params.advertise_address = "127.0.0.1";
+    params.port = 0;
+    params.worker_count = 2;
+    params.connections_per_peer = 2;
+    params.max_outstanding_tasks = 16;
+    params.max_outstanding_bytes = 1 << 20;
+    params.max_transfer_bytes = 1 << 20;
+    params.connect_timeout_ms = 1000;
+    params.progress_timeout_ms = 1000;
+    return params;
+}
+
+bool ContainsTransport(const BufferDesc& desc, TransportType type) {
+    return std::find(desc.transports.begin(), desc.transports.end(), type) !=
+           desc.transports.end();
+}
+
+TEST(HighPerformanceTcpTransportTest,
+     WorkerFailureDoesNotHideCommittedTerminalStatus) {
+    auto metadata = MakeLocalMetadata();
+    HighPerformanceTcpTransport transport(MakeParams());
+    std::string segment_name = "hp_transport_test";
+    ASSERT_TRUE(
+        transport.install(segment_name, metadata, nullptr, nullptr).ok());
+
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(batch, 1).ok());
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    ASSERT_NE(hp_batch, nullptr);
+
+    Request request{};
+    request.length = 37;
+    auto task = std::make_shared<HighPerformanceTcpTaskState>(
+        request.length, 0, [](BatchID) {},
+        HighPerformanceTcpBufferRegistry::Lease{});
+    ASSERT_TRUE(task->completeOnce(COMPLETED, request.length));
+    hp_batch->tasks.push_back(std::move(task));
+
+    HighPerformanceTcpTransportTestPeer::failWorker(transport);
+    ASSERT_TRUE(WaitUntil([&] {
+        return HighPerformanceTcpTransportTestPeer::hasFailedWorker(transport);
+    }));
+
+    TransferStatus status{FAILED, 0};
+    const Status result = transport.getTransferStatus(batch, 0, status);
+    EXPECT_TRUE(result.ok()) << result.ToString();
+    EXPECT_EQ(status.s, COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, request.length);
+
+    EXPECT_TRUE(transport.freeSubBatch(batch).ok());
+    EXPECT_TRUE(transport.quiesce().IsInternalError());
+    EXPECT_TRUE(transport.uninstall().ok());
+}
+
+TEST(HighPerformanceTcpTransportTest, UnknownWriteOutcomeIsPermanent) {
+    HighPerformanceTcpTransport transport(MakeParams());
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(batch, 1).ok());
+    auto* hp_batch = dynamic_cast<HighPerformanceTcpSubBatch*>(batch);
+    ASSERT_NE(hp_batch, nullptr);
+
+    auto uncertain_write = std::make_shared<HighPerformanceTcpTaskState>(
+        0, 0, [](BatchID) {}, HighPerformanceTcpBufferRegistry::Lease{});
+    ASSERT_TRUE(uncertain_write->completeOnce(
+        FAILED, 0, HighPerformanceTcpStatus::kInternalError));
+    hp_batch->tasks.push_back(std::move(uncertain_write));
+
+    TransferStatus status{};
+    const Status unsafe_replay = transport.getTransferStatus(batch, 0, status);
+    EXPECT_TRUE(unsafe_replay.IsInvalidEntry()) << unsafe_replay.ToString();
+    EXPECT_EQ(status.s, FAILED);
+    EXPECT_TRUE(transport.freeSubBatch(batch).ok());
+}
+
+TEST(HighPerformanceTcpTransportTest,
+     PublishesEndpointAndSeparatesLocalOnlyCapabilities) {
+    auto metadata = MakeLocalMetadata();
+    auto params = MakeParams();
+    params.bind_address.clear();
+    params.rail_addresses = {"127.0.0.1", "127.0.0.2"};
+    HighPerformanceTcpTransport transport(std::move(params));
+    std::string segment_name = "hp_transport_test";
+    ASSERT_TRUE(
+        transport.install(segment_name, metadata, nullptr, nullptr).ok());
+
+    const SegmentDescRef local = metadata->segmentManager().getLocal();
+    const auto attr_it = local->getMemory().transport_attrs.find(
+        static_cast<int>(TransportType::HP_TCP));
+    ASSERT_NE(attr_it, local->getMemory().transport_attrs.end());
+    HighPerformanceTcpEndpointAttr endpoint;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpEndpointAttr(attr_it->second, &endpoint).ok());
+    ASSERT_EQ(endpoint.endpoints.size(), 2U);
+    EXPECT_EQ(endpoint.endpoints[0].host, "127.0.0.1");
+    EXPECT_EQ(endpoint.endpoints[1].host, "127.0.0.2");
+    EXPECT_NE(endpoint.endpoints[0].port, 0);
+    EXPECT_EQ(endpoint.endpoints[0].port, endpoint.endpoints[1].port);
+
+    std::array<uint8_t, 64> local_only_storage{};
+    BufferDesc local_only;
+    local_only.addr = reinterpret_cast<uint64_t>(local_only_storage.data());
+    local_only.length = local_only_storage.size();
+    local_only.location = "cpu:0";
+    MemoryOptions local_options;
+    local_options.perm = kLocalReadWrite;
+    ASSERT_TRUE(transport.addMemoryBuffer(local_only, local_options).ok());
+    EXPECT_TRUE(transport.tracksLocalBuffer(local_only));
+    EXPECT_FALSE(ContainsTransport(local_only, TransportType::HP_TCP));
+    EXPECT_EQ(local_only.transport_attrs.count(TransportType::HP_TCP), 0U);
+
+    std::array<uint8_t, 64> global_storage{};
+    BufferDesc global;
+    global.addr = reinterpret_cast<uint64_t>(global_storage.data());
+    global.length = global_storage.size();
+    global.location = "cpu:0";
+    MemoryOptions global_options;
+    global_options.perm = kGlobalReadWrite;
+    ASSERT_TRUE(transport.addMemoryBuffer(global, global_options).ok());
+    EXPECT_TRUE(ContainsTransport(global, TransportType::HP_TCP));
+    const auto buffer_attr = global.transport_attrs.find(TransportType::HP_TCP);
+    ASSERT_NE(buffer_attr, global.transport_attrs.end());
+    HighPerformanceTcpBufferAttr decoded_buffer;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpBufferAttr(buffer_attr->second, &decoded_buffer)
+            .ok());
+    EXPECT_NE(decoded_buffer.registration_id, 0U);
+    EXPECT_EQ(decoded_buffer.permission, "global_read_write");
+
+    ASSERT_TRUE(transport.quiesce().ok());
+    ASSERT_TRUE(transport.removeMemoryBuffer(local_only).ok());
+    ASSERT_TRUE(transport.removeMemoryBuffer(global).ok());
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+TEST(HighPerformanceTcpTransportTest, RejectsMismatchedSingleRailListener) {
+    auto params = MakeParams();
+    params.rail_addresses = {"127.0.0.2"};
+    HighPerformanceTcpTransport transport(std::move(params));
+    std::string segment_name = "hp_transport_test";
+    EXPECT_TRUE(
+        transport.install(segment_name, MakeLocalMetadata(), nullptr, nullptr)
+            .IsInvalidArgument());
+}
+
+Status PublishBuffers(const std::shared_ptr<ControlService>& metadata,
+                      const std::vector<BufferDesc>& buffers) {
+    return metadata->segmentManager().updateLocal(
+        [&](SegmentDesc& segment) -> Status {
+            std::get<MemorySegmentDesc>(segment.detail).buffers = buffers;
+            return Status::OK();
+        });
+}
+
+Status WaitForTransportResult(HighPerformanceTcpTransport& transport,
+                              Transport::SubBatchRef batch,
+                              TransferStatus& transfer_status) {
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    Status result = Status::OK();
+    while (std::chrono::steady_clock::now() < deadline) {
+        result = transport.getTransferStatus(batch, 0, transfer_status);
+        if (transfer_status.s != PENDING) return result;
+        std::this_thread::yield();
+    }
+    return Status::InternalError("HP TCP test transfer did not finish");
+}
+
+// Test-only relay: observe the wire request and forward it to the real server.
+// Pumped by the test thread; no transport worker waits for another callback.
+class RailRelay {
+   public:
+    struct Observation {
+        std::string source;
+        std::string destination;
+        HighPerformanceTcpRequestFrame request;
+    };
+
+    RailRelay(const std::string& address, uint16_t server_port)
+        : acceptor_(io_, {asio::ip::make_address(address), 0}),
+          backend_(asio::ip::make_address(address), server_port) {
+        asio::co_spawn(io_, accept(), [this](std::exception_ptr error) {
+            if (error) error_ = error;
+        });
+    }
+
+    uint16_t port() const { return acceptor_.local_endpoint().port(); }
+    void poll() {
+        io_.poll();
+        if (error_) std::rethrow_exception(error_);
+    }
+    size_t connections = 0;
+    std::vector<Observation> observations;
+
+   private:
+    asio::awaitable<void> accept() {
+        for (;;) {
+            auto socket = co_await acceptor_.async_accept(asio::use_awaitable);
+            ++connections;
+            asio::co_spawn(io_, forward(std::move(socket)),
+                           [this](std::exception_ptr error) {
+                               if (error) error_ = error;
+                           });
+        }
+    }
+
+    asio::awaitable<void> forward(asio::ip::tcp::socket socket) {
+        asio::ip::tcp::socket server(io_);
+        co_await server.async_connect(backend_, asio::use_awaitable);
+        for (;;) {
+            std::array<uint8_t, kHighPerformanceTcpRequestSize> header{};
+            co_await asio::async_read(socket, asio::buffer(header),
+                                      asio::use_awaitable);
+            HighPerformanceTcpRequestFrame request;
+            if (!DecodeHighPerformanceTcpRequest(header.data(), header.size(),
+                                                 &request)
+                     .ok()) {
+                throw std::runtime_error("invalid relayed HP TCP request");
+            }
+            co_await asio::async_write(server, asio::buffer(header),
+                                       asio::use_awaitable);
+            std::vector<uint8_t> payload(request.length);
+            if (request.opcode == HighPerformanceTcpOpcode::kWrite) {
+                co_await asio::async_read(socket, asio::buffer(payload),
+                                          asio::use_awaitable);
+                co_await asio::async_write(server, asio::buffer(payload),
+                                           asio::use_awaitable);
+            }
+            std::array<uint8_t, kHighPerformanceTcpResponseSize> response{};
+            co_await asio::async_read(server, asio::buffer(response),
+                                      asio::use_awaitable);
+            co_await asio::async_write(socket, asio::buffer(response),
+                                       asio::use_awaitable);
+            if (request.opcode == HighPerformanceTcpOpcode::kRead) {
+                co_await asio::async_read(server, asio::buffer(payload),
+                                          asio::use_awaitable);
+                co_await asio::async_write(socket, asio::buffer(payload),
+                                           asio::use_awaitable);
+            }
+            observations.push_back(
+                {socket.remote_endpoint().address().to_string(),
+                 socket.local_endpoint().address().to_string(), request});
+        }
+    }
+
+    asio::io_context io_;
+    asio::ip::tcp::acceptor acceptor_;
+    asio::ip::tcp::endpoint backend_;
+    std::exception_ptr error_;
+};
+
+void CheckRailPayloads(bool multi_rail) {
+    constexpr size_t kLength = (4ULL << 20) + 97;
+    constexpr size_t kOffset = 37;
+    std::vector<uint8_t> remote(kLength);
+    auto params = MakeParams();
+    params.bind_address.clear();
+    params.rail_addresses =
+        multi_rail ? std::vector<std::string>{"127.0.0.1", "127.0.0.2"}
+                   : std::vector<std::string>{"127.0.0.1"};
+    params.max_outstanding_bytes = 8ULL << 20;
+    params.max_transfer_bytes = 8ULL << 20;
+
+    auto server_metadata = MakeLocalMetadata();
+    uint16_t rpc_port = 0;
+    ASSERT_TRUE(server_metadata->start(rpc_port).ok());
+    const std::string server_name = "127.0.0.1:" + std::to_string(rpc_port);
+    ASSERT_TRUE(server_metadata->segmentManager()
+                    .updateLocal([&](SegmentDesc& segment) -> Status {
+                        segment.name = server_name;
+                        segment.rpc_server_addr = server_name;
+                        return Status::OK();
+                    })
+                    .ok());
+
+    HighPerformanceTcpTransport server(params);
+    std::string installed_server_name = server_name;
+    ASSERT_TRUE(
+        server.install(installed_server_name, server_metadata, nullptr, nullptr)
+            .ok());
+    std::mt19937 data(3689);
+    for (size_t i = 0; i < remote.size(); ++i) {
+        remote[i] = static_cast<uint8_t>(data());
+    }
+    auto expected = remote;
+    BufferDesc remote_desc;
+    remote_desc.addr = reinterpret_cast<uint64_t>(remote.data());
+    remote_desc.length = remote.size();
+    remote_desc.location = "cpu:0";
+    MemoryOptions remote_options;
+    remote_options.type = HP_TCP;
+    remote_options.perm = kGlobalReadWrite;
+    ASSERT_TRUE(server.addMemoryBuffer(remote_desc, remote_options).ok());
+    ASSERT_TRUE(PublishBuffers(server_metadata, {remote_desc}).ok());
+
+    HighPerformanceTcpEndpointAttr endpoint;
+    ASSERT_TRUE(DecodeHighPerformanceTcpEndpointAttr(
+                    server_metadata->segmentManager()
+                        .getLocal()
+                        ->getMemory()
+                        .transport_attrs.at(static_cast<int>(HP_TCP)),
+                    &endpoint)
+                    .ok());
+    std::vector<std::unique_ptr<RailRelay>> relays;
+    for (auto& rail : endpoint.endpoints) {
+        relays.push_back(std::make_unique<RailRelay>(rail.host, rail.port));
+        rail.port = relays.back()->port();
+    }
+    ASSERT_TRUE(server_metadata->segmentManager()
+                    .updateLocal([&](SegmentDesc& segment) {
+                        return EncodeHighPerformanceTcpEndpointAttr(
+                            endpoint,
+                            &std::get<MemorySegmentDesc>(segment.detail)
+                                 .transport_attrs[static_cast<int>(HP_TCP)]);
+                    })
+                    .ok());
+
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("transports/tcp/enable", false);
+    config->set("transports/rdma/enable", false);
+    config->set("transports/shm/enable", false);
+    config->set("transports/hp_tcp/enable", true);
+    config->set("transports/hp_tcp/bind_address", "");
+    config->set("transports/hp_tcp/rail_addresses", params.rail_addresses);
+    config->set("transports/hp_tcp/connections_per_peer", 2);
+    // A stalled peer must not block the healthy peer on this same worker.
+    config->set("transports/hp_tcp/worker_count", 1);
+    config->set("transports/hp_tcp/progress_timeout_ms", 5000);
+    std::vector<uint8_t> local(kLength, 0);
+    std::vector<uint8_t> stalled_buffer(kLength);
+    TransferEngine client(config);
+    ASSERT_TRUE(client.available());
+    SegmentID target = 0;
+    ASSERT_TRUE(client.openSegment(target, server_name).ok());
+
+    ASSERT_TRUE(client.registerLocalMemory(local.data(), local.size()).ok());
+    // The first two small READs create both lanes; later cases reuse them.
+    for (auto opcode : {Request::READ, Request::WRITE}) {
+        const auto lengths =
+            opcode == Request::READ
+                ? std::vector<size_t>{4096, (2ULL << 20) - 1, 2ULL << 20,
+                                      (4ULL << 20) + 3}
+                : std::vector<size_t>{4096, (4ULL << 20) + 3};
+        for (size_t length : lengths) {
+            SCOPED_TRACE(::testing::Message()
+                         << multi_rail << ":" << opcode << ":" << length);
+            std::fill(local.begin(), local.end(), 0xa5);
+            if (opcode == Request::WRITE) {
+                for (size_t i = kOffset; i < kOffset + length; ++i)
+                    expected[i] ^= 0xff;
+                std::copy_n(expected.data() + kOffset, length,
+                            local.data() + kOffset);
+            }
+            for (auto& relay : relays) relay->observations.clear();
+            Request request{};
+            request.opcode = opcode;
+            request.source = local.data() + kOffset;
+            request.target_id = target;
+            request.target_offset = remote_desc.addr + kOffset;
+            request.length = length;
+            request.transport_hint = HP_TCP;
+            const auto batch = client.allocateBatch(1);
+            ASSERT_TRUE(client.submitTransfer(batch, {request}).ok());
+            TransferStatus status{PENDING, 0};
+            ASSERT_TRUE(WaitUntil([&] {
+                for (auto& relay : relays) relay->poll();
+                EXPECT_TRUE(client.getTransferStatus(batch, status).ok());
+                return status.s != PENDING;
+            }));
+            ASSERT_EQ(status.s, COMPLETED);
+            EXPECT_EQ(status.transferred_bytes, length);
+            const size_t count =
+                multi_rail && opcode == Request::READ && length >= (2ULL << 20)
+                    ? 2
+                    : 1;
+            ASSERT_TRUE(WaitUntil([&] {
+                size_t observed = 0;
+                for (auto& relay : relays) {
+                    relay->poll();
+                    observed += relay->observations.size();
+                }
+                return observed == count;
+            }));
+            uint64_t cursor = request.target_offset;
+            for (size_t rail = 0; rail < relays.size(); ++rail) {
+                if (count == 2) {
+                    ASSERT_EQ(relays[rail]->observations.size(), 1U);
+                }
+                for (const auto& seen : relays[rail]->observations) {
+                    EXPECT_EQ(seen.source, params.rail_addresses[rail]);
+                    EXPECT_EQ(seen.destination, params.rail_addresses[rail]);
+                    EXPECT_EQ(seen.request.opcode,
+                              opcode == Request::READ
+                                  ? HighPerformanceTcpOpcode::kRead
+                                  : HighPerformanceTcpOpcode::kWrite);
+                    EXPECT_EQ(seen.request.remote_addr, cursor);
+                    EXPECT_EQ(seen.request.length,
+                              length / count + (rail < length % count ? 1 : 0));
+                    cursor += seen.request.length;
+                }
+            }
+            EXPECT_EQ(cursor, request.target_offset + length);
+            EXPECT_EQ(std::memcmp(local.data() + kOffset,
+                                  expected.data() + kOffset, length),
+                      0);
+            if (opcode == Request::WRITE) {
+                // After the ACK, synchronize with the server workers before
+                // inspecting their memory from this test thread.
+                ASSERT_TRUE(
+                    HighPerformanceTcpTransportTestPeer::barrier(server).ok());
+                EXPECT_EQ(remote, expected);
+            }
+            EXPECT_TRUE(std::all_of(local.begin(), local.begin() + kOffset,
+                                    [](uint8_t b) { return b == 0xa5; }));
+            EXPECT_TRUE(std::all_of(local.begin() + kOffset + length,
+                                    local.end(),
+                                    [](uint8_t b) { return b == 0xa5; }));
+            ASSERT_TRUE(client.freeBatch(batch).ok());
+            size_t connections = 0;
+            for (auto& relay : relays) connections += relay->connections;
+            EXPECT_EQ(connections,
+                      opcode == Request::READ && length == 4096 ? 1U : 2U);
+        }
+    }
+    if (multi_rail) {
+        // A second peer sends one payload byte per slice, then stalls. The
+        // original peer must still complete in this same engine and worker
+        // pool.
+        asio::io_context io;
+        asio::ip::tcp::acceptor stalled(io, {asio::ip::tcp::v4(), 0});
+        stalled.non_blocking(true);
+        auto stalled_metadata = MakeLocalMetadata();
+        uint16_t stalled_rpc_port = 0;
+        ASSERT_TRUE(stalled_metadata->start(stalled_rpc_port).ok());
+        const auto stalled_name =
+            "127.0.0.1:" + std::to_string(stalled_rpc_port);
+        auto stalled_endpoint = endpoint;
+        for (auto& rail : stalled_endpoint.endpoints)
+            rail.port = stalled.local_endpoint().port();
+        ASSERT_TRUE(
+            stalled_metadata->segmentManager()
+                .updateLocal([&](SegmentDesc& segment) {
+                    segment = *server_metadata->segmentManager().getLocal();
+                    segment.name = segment.rpc_server_addr = stalled_name;
+                    return EncodeHighPerformanceTcpEndpointAttr(
+                        stalled_endpoint,
+                        &std::get<MemorySegmentDesc>(segment.detail)
+                             .transport_attrs[static_cast<int>(HP_TCP)]);
+                })
+                .ok());
+        SegmentID stalled_target;
+        ASSERT_TRUE(client.openSegment(stalled_target, stalled_name).ok());
+        ASSERT_TRUE(
+            client.registerLocalMemory(stalled_buffer.data(), kLength).ok());
+        Request request{};
+        request.opcode = Request::READ;
+        request.source = stalled_buffer.data();
+        request.target_id = stalled_target;
+        request.target_offset = remote_desc.addr;
+        request.length = (4ULL << 20) + 3;
+        request.transport_hint = HP_TCP;
+        auto slow = client.allocateBatch(1);
+        ASSERT_TRUE(client.submitTransfer(slow, {request}).ok());
+        std::array<asio::ip::tcp::socket, 2> sockets{asio::ip::tcp::socket(io),
+                                                     asio::ip::tcp::socket(io)};
+        for (auto& socket : sockets) {
+            ASSERT_TRUE(WaitUntil([&] {
+                std::error_code error;
+                if (!socket.is_open()) stalled.accept(socket, error);
+                return socket.is_open();
+            }));
+            std::array<uint8_t, kHighPerformanceTcpRequestSize> header{};
+            asio::read(socket, asio::buffer(header));
+            HighPerformanceTcpRequestFrame frame;
+            ASSERT_TRUE(DecodeHighPerformanceTcpRequest(header.data(),
+                                                        header.size(), &frame)
+                            .ok());
+            const auto response = EncodeHighPerformanceTcpResponse(
+                {HighPerformanceTcpStatus::kOk, frame.request_id,
+                 frame.length});
+            asio::write(socket, asio::buffer(response));
+            asio::write(socket, asio::buffer(remote.data(), 1));
+        }
+        request.source = local.data();
+        request.target_id = target;
+        request.length = 4096;
+        auto healthy = client.allocateBatch(1);
+        ASSERT_TRUE(client.submitTransfer(healthy, {request}).ok());
+        TransferStatus status{PENDING, 0};
+        ASSERT_TRUE(WaitUntil([&] {
+            for (auto& relay : relays) relay->poll();
+            EXPECT_TRUE(client.getTransferStatus(healthy, status).ok());
+            return status.s != PENDING;
+        }));
+        EXPECT_EQ(status.s, COMPLETED);
+        EXPECT_EQ(std::memcmp(local.data(), expected.data(), 4096), 0);
+        ASSERT_TRUE(client.freeBatch(healthy).ok());
+        ASSERT_TRUE(client.getTransferStatus(slow, status).ok());
+        EXPECT_EQ(status.s, PENDING);
+        ASSERT_TRUE(WaitUntil(
+            [&] {
+                EXPECT_TRUE(client.getTransferStatus(slow, status).ok());
+                return status.s != PENDING;
+            },
+            std::chrono::seconds(6)));
+        EXPECT_EQ(status.s, TIMEOUT);
+        ASSERT_TRUE(client.freeBatch(slow).ok());
+        ASSERT_TRUE(
+            client.unregisterLocalMemory(stalled_buffer.data(), kLength).ok());
+    }
+    ASSERT_TRUE(client.unregisterLocalMemory(local.data(), local.size()).ok());
+    ASSERT_TRUE(server.removeMemoryBuffer(remote_desc).ok());
+    ASSERT_TRUE(server.quiesce().ok());
+    ASSERT_TRUE(server.uninstall().ok());
+}
+
+TEST(HighPerformanceTcpTransportTest, RailPayloadsAndConnectionReuse) {
+    CheckRailPayloads(true);
+}
+
+TEST(HighPerformanceTcpTransportTest, SingleRailPayloadsAndConnectionReuse) {
+    CheckRailPayloads(false);
+}
+
+TEST(HighPerformanceTcpTransportTest,
+     SlicedStaleRegistrationCancelsAndRetries) {
+    constexpr size_t kLength = 4ULL << 20;
+    std::vector<uint8_t> remote_storage(kLength, 0x5a);
+    std::vector<uint8_t> local_storage(kLength);
+    auto params = MakeParams();
+    params.bind_address.clear();
+    params.rail_addresses = {"127.0.0.1", "127.0.0.2"};
+    params.max_outstanding_bytes = 8ULL << 20;
+    params.max_transfer_bytes = 8ULL << 20;
+    params.worker_count = 1;
+    params.progress_timeout_ms = 5000;
+    asio::io_context peer_io;
+    asio::ip::tcp::acceptor peer(peer_io,
+                                 {asio::ip::make_address("127.0.0.1"), 0});
+    peer.non_blocking(true);
+
+    auto server_metadata = MakeLocalMetadata();
+    uint16_t rpc_port = 0;
+    ASSERT_TRUE(server_metadata->start(rpc_port).ok());
+    ASSERT_NE(rpc_port, 0);
+    const std::string server_name = "127.0.0.1:" + std::to_string(rpc_port);
+    ASSERT_TRUE(server_metadata->segmentManager()
+                    .updateLocal([&](SegmentDesc& segment) -> Status {
+                        segment.name = server_name;
+                        segment.rpc_server_addr = server_name;
+                        return Status::OK();
+                    })
+                    .ok());
+
+    HighPerformanceTcpTransport server(params);
+    std::string installed_server_name = server_name;
+    ASSERT_TRUE(
+        server.install(installed_server_name, server_metadata, nullptr, nullptr)
+            .ok());
+    BufferDesc registration_a;
+    registration_a.addr = reinterpret_cast<uint64_t>(remote_storage.data());
+    registration_a.length = remote_storage.size();
+    registration_a.location = "cpu:0";
+    MemoryOptions remote_options;
+    remote_options.type = HP_TCP;
+    remote_options.perm = kGlobalReadWrite;
+    ASSERT_TRUE(server.addMemoryBuffer(registration_a, remote_options).ok());
+    HighPerformanceTcpBufferAttr attr_a;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpBufferAttr(
+            registration_a.transport_attrs.at(TransportType::HP_TCP), &attr_a)
+            .ok());
+    ASSERT_TRUE(PublishBuffers(server_metadata, {registration_a}).ok());
+
+    auto client_metadata = MakeLocalMetadata();
+    ASSERT_TRUE(client_metadata->segmentManager()
+                    .updateLocal([](SegmentDesc& segment) -> Status {
+                        // Deliberately omit a callback address. The remote
+                        // cache stays on A until this test invalidates it.
+                        segment.rpc_server_addr.clear();
+                        return Status::OK();
+                    })
+                    .ok());
+    HighPerformanceTcpTransport client(params);
+    std::string client_name = "hp_transport_client";
+    ASSERT_TRUE(
+        client.install(client_name, client_metadata, nullptr, nullptr).ok());
+    SegmentID target = 0;
+    ASSERT_TRUE(
+        client_metadata->segmentManager().openRemote(target, server_name).ok());
+    SegmentDescRef cached_a;
+    ASSERT_TRUE(client_metadata->segmentManager()
+                    .getRemoteCached(cached_a, target)
+                    .ok());
+    const BufferDesc* cached_buffer_a =
+        cached_a->findBuffer(registration_a.addr, registration_a.length);
+    ASSERT_NE(cached_buffer_a, nullptr);
+    auto& cached_memory = std::get<MemorySegmentDesc>(cached_a->detail);
+    auto& encoded_endpoint = cached_memory.transport_attrs.at(
+        static_cast<int>(TransportType::HP_TCP));
+    HighPerformanceTcpEndpointAttr mixed_endpoint;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpEndpointAttr(encoded_endpoint, &mixed_endpoint)
+            .ok());
+    ASSERT_EQ(mixed_endpoint.endpoints.size(), 2U);
+    for (auto& endpoint : mixed_endpoint.endpoints) {
+        endpoint = {"127.0.0.1", peer.local_endpoint().port()};
+    }
+    ASSERT_TRUE(
+        EncodeHighPerformanceTcpEndpointAttr(mixed_endpoint, &encoded_endpoint)
+            .ok());
+
+    ASSERT_TRUE(server.removeMemoryBuffer(registration_a).ok());
+    BufferDesc registration_b;
+    registration_b.addr = reinterpret_cast<uint64_t>(remote_storage.data());
+    registration_b.length = remote_storage.size();
+    registration_b.location = "cpu:0";
+    ASSERT_TRUE(server.addMemoryBuffer(registration_b, remote_options).ok());
+    HighPerformanceTcpBufferAttr attr_b;
+    ASSERT_TRUE(
+        DecodeHighPerformanceTcpBufferAttr(
+            registration_b.transport_attrs.at(TransportType::HP_TCP), &attr_b)
+            .ok());
+    ASSERT_NE(attr_a.registration_id, attr_b.registration_id);
+    ASSERT_TRUE(PublishBuffers(server_metadata, {registration_b}).ok());
+
+    BufferDesc local;
+    local.addr = reinterpret_cast<uint64_t>(local_storage.data());
+    local.length = local_storage.size();
+    local.location = "cpu:0";
+    MemoryOptions local_options;
+    local_options.type = HP_TCP;
+    local_options.perm = kLocalReadWrite;
+    ASSERT_TRUE(client.addMemoryBuffer(local, local_options).ok());
+
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(client.allocateSubBatch(batch, 1).ok());
+    Request request{};
+    request.opcode = Request::READ;
+    request.source = local_storage.data();
+    request.target_id = target;
+    request.target_offset = registration_b.addr;
+    request.length = registration_b.length;
+    request.transport_hint = HP_TCP;
+
+    const Status submitted = client.submitTransferTasks(batch, {request});
+    ASSERT_TRUE(submitted.ok()) << submitted.ToString();
+    std::error_code error;
+    const auto accept = [&](asio::ip::tcp::socket& socket) {
+        return WaitUntil([&] {
+            if (socket.is_open()) return true;
+            peer.accept(socket, error);
+            return !error;
+        });
+    };
+    asio::ip::tcp::socket stale_socket(peer_io);
+    asio::ip::tcp::socket stalled_socket(peer_io);
+    ASSERT_TRUE(accept(stale_socket));
+    ASSERT_TRUE(accept(stalled_socket));
+
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> stale_request{};
+    asio::read(stale_socket, asio::buffer(stale_request), error);
+    ASSERT_FALSE(error);
+    std::array<uint8_t, kHighPerformanceTcpRequestSize> stalled_request{};
+    asio::read(stalled_socket, asio::buffer(stalled_request), error);
+    ASSERT_FALSE(error);
+
+    HighPerformanceTcpRequestFrame frame;
+    ASSERT_TRUE(DecodeHighPerformanceTcpRequest(stale_request.data(),
+                                                stale_request.size(), &frame)
+                    .ok());
+    const auto response = EncodeHighPerformanceTcpResponse(
+        {HighPerformanceTcpStatus::kStaleRegistration, frame.request_id, 0});
+    asio::write(stale_socket, asio::buffer(response), error);
+    ASSERT_FALSE(error);
+
+    TransferStatus transfer_status{PENDING, 0};
+    Status first_result =
+        WaitForTransportResult(client, batch, transfer_status);
+    if (transfer_status.s == PENDING) {
+        (void)client.quiesce();
+    }
+    uint8_t unexpected = 0;
+    (void)stalled_socket.read_some(asio::buffer(&unexpected, 1), error);
+    EXPECT_TRUE(error);
+    ASSERT_EQ(transfer_status.s, FAILED);
+    EXPECT_TRUE(first_result.IsNeedsRefreshCache()) << first_result.ToString();
+
+    ASSERT_TRUE(
+        client_metadata->segmentManager().invalidateRemote(target).ok());
+    ASSERT_TRUE(client.retryTransferTask(batch, 0, request).ok());
+
+    Status retry_result =
+        WaitForTransportResult(client, batch, transfer_status);
+    EXPECT_TRUE(retry_result.ok()) << retry_result.ToString();
+    EXPECT_EQ(transfer_status.s, COMPLETED);
+    EXPECT_EQ(transfer_status.transferred_bytes, request.length);
+
+    SegmentDescRef refreshed;
+    ASSERT_TRUE(client_metadata->segmentManager()
+                    .getRemoteCached(refreshed, target)
+                    .ok());
+    const BufferDesc* refreshed_buffer =
+        refreshed->findBuffer(registration_b.addr, registration_b.length);
+    ASSERT_NE(refreshed_buffer, nullptr);
+    HighPerformanceTcpBufferAttr refreshed_attr;
+    ASSERT_TRUE(DecodeHighPerformanceTcpBufferAttr(
+                    refreshed_buffer->transport_attrs.at(TransportType::HP_TCP),
+                    &refreshed_attr)
+                    .ok());
+    EXPECT_EQ(refreshed_attr.registration_id, attr_b.registration_id);
+
+    ASSERT_TRUE(client.freeSubBatch(batch).ok());
+    ASSERT_TRUE(client.removeMemoryBuffer(local).ok());
+    ASSERT_TRUE(server.removeMemoryBuffer(registration_b).ok());
+    ASSERT_TRUE(client.quiesce().ok());
+    ASSERT_TRUE(server.quiesce().ok());
+    ASSERT_TRUE(client.uninstall().ok());
+    ASSERT_TRUE(server.uninstall().ok());
+}
+
+class HighPerformanceTcpLaneDistributionTest
+    : public ::testing::TestWithParam<bool> {};
+
+TEST_P(HighPerformanceTcpLaneDistributionTest,
+       InterleavedPeersUseEveryConfiguredLane) {
+    const bool sliced_read = GetParam();
+    const size_t peer_count = sliced_read ? 2 : 4;
+    const size_t length = sliced_read ? 4ULL << 20 : 4;
+    auto params = MakeParams();
+    params.bind_address.clear();
+    params.rail_addresses = {"127.0.0.1", "127.0.0.2"};
+    params.connections_per_peer = 4;
+    params.max_outstanding_bytes = 8ULL << 20;
+    params.max_transfer_bytes = 8ULL << 20;
+
+    // Each peer has its own listener, making per-peer socket counts observable.
+    // Storage outlives the transports even if an assertion ends the test.
+    std::vector<std::vector<uint8_t>> remote(peer_count,
+                                             std::vector<uint8_t>(length, 0));
+    std::vector<uint8_t> local(length, 0x5a);
+    std::vector<std::shared_ptr<ControlService>> server_metadata;
+    std::vector<std::unique_ptr<HighPerformanceTcpTransport>> servers;
+    std::vector<SegmentID> targets;
+    auto client_metadata = MakeLocalMetadata();
+    HighPerformanceTcpTransport client(params);
+    std::string client_name = "hp_lane_distribution_client";
+    ASSERT_TRUE(
+        client.install(client_name, client_metadata, nullptr, nullptr).ok());
+    for (size_t peer = 0; peer < peer_count; ++peer) {
+        if (sliced_read) {
+            std::fill(remote[peer].begin(), remote[peer].end(),
+                      static_cast<uint8_t>(peer + 1));
+        }
+        auto metadata = MakeLocalMetadata();
+        server_metadata.push_back(metadata);
+        uint16_t rpc_port = 0;
+        ASSERT_TRUE(metadata->start(rpc_port).ok());
+        std::string name = "127.0.0.1:" + std::to_string(rpc_port);
+        ASSERT_TRUE(metadata->segmentManager()
+                        .updateLocal([&](SegmentDesc& segment) -> Status {
+                            segment.name = name;
+                            segment.rpc_server_addr = name;
+                            return Status::OK();
+                        })
+                        .ok());
+        servers.push_back(
+            std::make_unique<HighPerformanceTcpTransport>(params));
+        ASSERT_TRUE(
+            servers.back()->install(name, metadata, nullptr, nullptr).ok());
+        BufferDesc buffer;
+        buffer.addr = reinterpret_cast<uint64_t>(remote[peer].data());
+        buffer.length = length;
+        buffer.location = "cpu:0";
+        MemoryOptions options;
+        options.perm = kGlobalReadWrite;
+        ASSERT_TRUE(servers.back()->addMemoryBuffer(buffer, options).ok());
+        ASSERT_TRUE(PublishBuffers(metadata, {buffer}).ok());
+        SegmentID target = 0;
+        ASSERT_TRUE(
+            client_metadata->segmentManager().openRemote(target, name).ok());
+        targets.push_back(target);
+    }
+    BufferDesc buffer;
+    buffer.addr = reinterpret_cast<uint64_t>(local.data());
+    buffer.length = length;
+    buffer.location = "cpu:0";
+    MemoryOptions options;
+    options.perm = kLocalReadWrite;
+    ASSERT_TRUE(client.addMemoryBuffer(buffer, options).ok());
+
+    // One request per peer per round, across separate submissions. The old
+    // global request ID stride used one lane per peer for the WRITE case and
+    // one lane per rail per peer for sliced READs.
+    for (size_t round = 0; round < params.connections_per_peer; ++round) {
+        for (size_t peer = 0; peer < peer_count; ++peer) {
+            if (sliced_read) std::fill(local.begin(), local.end(), 0);
+            Transport::SubBatchRef batch = nullptr;
+            ASSERT_TRUE(client.allocateSubBatch(batch, 1).ok());
+            Request request{};
+            request.opcode = sliced_read ? Request::READ : Request::WRITE;
+            request.source = local.data();
+            request.target_id = targets[peer];
+            request.target_offset =
+                reinterpret_cast<uint64_t>(remote[peer].data());
+            request.length = length;
+            ASSERT_TRUE(client.submitTransferTasks(batch, {request}).ok());
+            TransferStatus status{};
+            ASSERT_TRUE(WaitForTransportResult(client, batch, status).ok());
+            ASSERT_EQ(status.s, COMPLETED);
+            EXPECT_EQ(status.transferred_bytes, length);
+            EXPECT_EQ(std::memcmp(local.data(), remote[peer].data(), length),
+                      0);
+            ASSERT_TRUE(client.freeSubBatch(batch).ok());
+        }
+    }
+    for (const auto& server : servers) {
+        EXPECT_EQ(HighPerformanceTcpTransportTestPeer::activeSessions(*server),
+                  params.connections_per_peer);
+    }
+    ASSERT_TRUE(client.quiesce().ok());
+    ASSERT_TRUE(client.uninstall().ok());
+    for (const auto& server : servers) {
+        ASSERT_TRUE(server->quiesce().ok());
+        ASSERT_TRUE(server->uninstall().ok());
+    }
+}
+
+INSTANTIATE_TEST_SUITE_P(WriteAndSlicedRead,
+                         HighPerformanceTcpLaneDistributionTest,
+                         ::testing::Bool());
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/hp_tcp_workers_test.cpp b/mooncake-transfer-engine/tent/tests/hp_tcp_workers_test.cpp
new file mode 100644
index 0000000000..bee6d24132
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/hp_tcp_workers_test.cpp
@@ -0,0 +1,154 @@
+// Copyright 2026 KVCache.AI
+#include <gtest/gtest.h>
+
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <stdexcept>
+#include <thread>
+
+#include "tent/transport/hp_tcp/hp_tcp_buffer_registry.h"
+#include "tent/transport/hp_tcp/hp_tcp_task.h"
+#include "tent/transport/hp_tcp/hp_tcp_workers.h"
+
+namespace mooncake::tent {
+namespace {
+using namespace std::chrono_literals;
+
+template <class Predicate>
+bool WaitUntil(Predicate predicate) {
+    const auto deadline = std::chrono::steady_clock::now() + 2s;
+    while (!predicate() && std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(1ms);
+    }
+    return predicate();
+}
+
+Status SubmitToWorker(HighPerformanceTcpWorkers& workers, size_t owner,
+                      HighPerformanceTcpWorkers::Task task) {
+    std::vector<HighPerformanceTcpWorkers::Command> commands{
+        {.worker_id = owner, .run = std::move(task), .cancel = {}}};
+    return workers.tryCommitBatch(commands, nullptr, 0, 0, [] {});
+}
+
+TEST(HighPerformanceTcpWorkersTest, PreservesAffinity) {
+    HighPerformanceTcpWorkers workers({.worker_count = 2});
+    ASSERT_TRUE(workers.start().ok());
+    std::atomic<size_t> completed{0};
+    for (size_t owner : {0u, 1u, 0u, 1u}) {
+        ASSERT_TRUE(SubmitToWorker(workers, owner, [&, owner](size_t actual) {
+                        EXPECT_EQ(actual, owner);
+                        ++completed;
+                    }).ok());
+    }
+    EXPECT_TRUE(WaitUntil([&] { return completed.load() == 4; }));
+    EXPECT_TRUE(workers.stop().ok());
+}
+
+TEST(HighPerformanceTcpWorkersTest, BatchAdmissionHasNoPartialCommit) {
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    HighPerformanceTcpAdmissionController admission(1, 512);
+    ASSERT_TRUE(admission.tryReserve(1, 512).ok());
+    bool committed = false;
+    std::vector<HighPerformanceTcpWorkers::Command> commands{
+        {.worker_id = 0, .run = [](size_t) {}, .cancel = [] {}}};
+    EXPECT_TRUE(workers
+                    .tryCommitBatch(commands, &admission, 1, 512,
+                                    [&] { committed = true; })
+                    .IsTooManyRequests());
+    EXPECT_FALSE(committed);
+    EXPECT_EQ(admission.outstandingTasks(), 1u);
+    admission.release(1, 512);
+    EXPECT_TRUE(workers.stop().ok());
+}
+
+TEST(HighPerformanceTcpAdmissionControllerTest,
+     UnderflowFailsClosedWithoutForgingDrain) {
+    HighPerformanceTcpAdmissionController admission(2, 1024);
+    ASSERT_TRUE(admission.tryReserve(1, 512).ok());
+
+    std::promise<bool> result;
+    auto result_future = result.get_future();
+    std::thread waiter(
+        [&] { result.set_value(admission.waitForZero().IsInternalError()); });
+
+    admission.release(2, 512);
+
+    EXPECT_TRUE(admission.failed());
+    EXPECT_EQ(admission.outstandingTasks(), 1u);
+    EXPECT_EQ(admission.outstandingBytes(), 512u);
+    const auto wait_status = result_future.wait_for(std::chrono::seconds(1));
+    if (wait_status != std::future_status::ready) {
+        // Ensure a broken implementation cannot strand the test thread.
+        admission.release(1, 512);
+    }
+    EXPECT_EQ(wait_status, std::future_status::ready);
+    EXPECT_TRUE(result_future.get());
+    waiter.join();
+    EXPECT_TRUE(admission.tryReserve(1, 1).IsInternalError());
+}
+
+TEST(HighPerformanceTcpWorkersTest,
+     FailedWorkerRejectsAdmissionButKeepsTeardownLive) {
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+
+    std::atomic<bool> owner_loop_continued{false};
+
+    asio::post(workers.ioContext(0),
+               [] { throw std::runtime_error("test worker failure"); });
+    asio::post(workers.ioContext(0), [&] { owner_loop_continued.store(true); });
+
+    ASSERT_TRUE(WaitUntil([&] { return workers.hasFailedWorker(); }));
+    EXPECT_TRUE(workers.barrier().ok());
+    EXPECT_TRUE(owner_loop_continued.load());
+    EXPECT_TRUE(SubmitToWorker(workers, 0, [](size_t) {}).IsInternalError());
+    EXPECT_TRUE(workers.stop().IsInternalError());
+}
+
+TEST(HighPerformanceTcpTaskTest, CompletionReleasesLeaseAndBudgetOnce) {
+    HighPerformanceTcpBufferRegistry registry;
+    std::array<uint8_t, 64> memory{};
+    uint64_t registration = 0;
+    ASSERT_TRUE(registry
+                    .add(reinterpret_cast<uint64_t>(memory.data()),
+                         memory.size(), kGlobalReadWrite, &registration)
+                    .ok());
+    HighPerformanceTcpBufferRegistry::Lease lease;
+    ASSERT_TRUE(
+        registry
+            .acquireLocalLease(reinterpret_cast<uint64_t>(memory.data()),
+                               memory.size(), &lease)
+            .ok());
+    HighPerformanceTcpAdmissionController admission(1, memory.size());
+    ASSERT_TRUE(admission.tryReserve(1, memory.size()).ok());
+
+    auto task = std::make_shared<HighPerformanceTcpTaskState>(
+        memory.size(), 1, [](BatchID) {}, std::move(lease), 2);
+    task->activateReservation(&admission);
+    EXPECT_FALSE(task->completeSlice(COMPLETED));
+    EXPECT_EQ(task->snapshot().s, PENDING);
+    EXPECT_EQ(admission.outstandingTasks(), 1u);
+    EXPECT_TRUE(task->completeSlice(COMPLETED));
+    EXPECT_FALSE(task->completeOnce(FAILED, 0));
+    EXPECT_EQ(task->snapshot().transferred_bytes, memory.size());
+    EXPECT_EQ(admission.outstandingTasks(), 0u);
+    EXPECT_TRUE(
+        registry
+            .remove(reinterpret_cast<uint64_t>(memory.data()), memory.size())
+            .ok());
+}
+
+TEST(HighPerformanceTcpWorkersTest, StopIsIdempotentAndNotRestartable) {
+    HighPerformanceTcpWorkers workers({.worker_count = 1});
+    ASSERT_TRUE(workers.start().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    EXPECT_TRUE(workers.stop().ok());
+    EXPECT_TRUE(workers.start().IsInvalidArgument());
+    EXPECT_TRUE(SubmitToWorker(workers, 0, [](size_t) {}).IsInternalError());
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/intent_type_test.cpp b/mooncake-transfer-engine/tent/tests/intent_type_test.cpp
deleted file mode 100644
index ac56a2852e..0000000000
--- a/mooncake-transfer-engine/tent/tests/intent_type_test.cpp
+++ /dev/null
@@ -1,95 +0,0 @@
-// Copyright 2026 KVCache.AI
-//
-// 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.
-//
-// Unit tests for IntentType enum and its integration with Request.
-
-#include <gtest/gtest.h>
-
-#include <vector>
-
-#include "tent/common/types.h"
-
-namespace mooncake {
-namespace tent {
-namespace {
-
-TEST(IntentTypeTest, DefaultIsUnspec) {
-    Request r{};
-    EXPECT_EQ(r.intent_type, IntentType::INTENT_UNSPEC);
-}
-
-TEST(IntentTypeTest, AllValuesAssignable) {
-    Request r{};
-    r.intent_type = IntentType::FOREGROUND_GET;
-    EXPECT_EQ(r.intent_type, IntentType::FOREGROUND_GET);
-    r.intent_type = IntentType::BACKGROUND_PREFETCH;
-    EXPECT_EQ(r.intent_type, IntentType::BACKGROUND_PREFETCH);
-    r.intent_type = IntentType::MIGRATION;
-    EXPECT_EQ(r.intent_type, IntentType::MIGRATION);
-    r.intent_type = IntentType::CHECKPOINT;
-    EXPECT_EQ(r.intent_type, IntentType::CHECKPOINT);
-    r.intent_type = IntentType::WEIGHT_LOADING;
-    EXPECT_EQ(r.intent_type, IntentType::WEIGHT_LOADING);
-    r.intent_type = IntentType::STAGING_INTERNAL;
-    EXPECT_EQ(r.intent_type, IntentType::STAGING_INTERNAL);
-}
-
-TEST(IntentTypeTest, IntegerValues) {
-    EXPECT_EQ(static_cast<int>(IntentType::INTENT_UNSPEC), 0);
-    EXPECT_EQ(static_cast<int>(IntentType::FOREGROUND_GET), 1);
-    EXPECT_EQ(static_cast<int>(IntentType::BACKGROUND_PREFETCH), 2);
-    EXPECT_EQ(static_cast<int>(IntentType::MIGRATION), 3);
-    EXPECT_EQ(static_cast<int>(IntentType::CHECKPOINT), 4);
-    EXPECT_EQ(static_cast<int>(IntentType::WEIGHT_LOADING), 5);
-    EXPECT_EQ(static_cast<int>(IntentType::STAGING_INTERNAL), 6);
-}
-
-TEST(IntentTypeTest, DoesNotAffectOtherFields) {
-    Request r{};
-    r.opcode = Request::READ;
-    r.priority = PRIO_LOW;
-    r.deadline_ns = 12345;
-    r.transport_hint = RDMA;
-    r.intent_type = IntentType::CHECKPOINT;
-
-    EXPECT_EQ(r.opcode, Request::READ);
-    EXPECT_EQ(r.priority, PRIO_LOW);
-    EXPECT_EQ(r.deadline_ns, 12345u);
-    EXPECT_EQ(r.transport_hint, RDMA);
-    EXPECT_EQ(r.intent_type, IntentType::CHECKPOINT);
-}
-
-TEST(IntentTypeTest, CopyPreservesIntentType) {
-    Request r{};
-    r.intent_type = IntentType::WEIGHT_LOADING;
-    Request copy = r;
-    EXPECT_EQ(copy.intent_type, IntentType::WEIGHT_LOADING);
-}
-
-TEST(IntentTypeTest, VectorOfRequests) {
-    std::vector<Request> batch(4);
-    batch[0].intent_type = IntentType::FOREGROUND_GET;
-    batch[1].intent_type = IntentType::BACKGROUND_PREFETCH;
-    batch[2].intent_type = IntentType::MIGRATION;
-    batch[3].intent_type = IntentType::INTENT_UNSPEC;
-
-    EXPECT_EQ(batch[0].intent_type, IntentType::FOREGROUND_GET);
-    EXPECT_EQ(batch[1].intent_type, IntentType::BACKGROUND_PREFETCH);
-    EXPECT_EQ(batch[2].intent_type, IntentType::MIGRATION);
-    EXPECT_EQ(batch[3].intent_type, IntentType::INTENT_UNSPEC);
-}
-
-}  // namespace
-}  // namespace tent
-}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/io_uring_transport_test.cpp b/mooncake-transfer-engine/tent/tests/io_uring_transport_test.cpp
new file mode 100644
index 0000000000..f9a34754e6
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/io_uring_transport_test.cpp
@@ -0,0 +1,288 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <fcntl.h>
+#include <unistd.h>
+
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/transport/io_uring/io_uring_transport.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr size_t kPageSize = 4096;
+constexpr SegmentID kUnknownSegment = 0x7fff;
+
+class ScopedTempFile {
+   public:
+    explicit ScopedTempFile(size_t length) {
+        // /dev/shm (tmpfs) rather than /tmp: on overlayfs-backed /tmp an
+        // O_DIRECT open succeeds but the io_uring operations fail with
+        // EINVAL on older kernels. On tmpfs the O_DIRECT open itself fails,
+        // so the transport falls back to buffered I/O and the requests
+        // succeed.
+        char tmpl[] = "/dev/shm/mooncake_tent_io_uring_test_XXXXXX";
+        fd_ = mkstemp(tmpl);
+        EXPECT_GE(fd_, 0);
+        if (fd_ >= 0) {
+            path_ = tmpl;
+            EXPECT_EQ(ftruncate(fd_, (off_t)length), 0);
+        }
+    }
+
+    ~ScopedTempFile() {
+        if (fd_ >= 0) close(fd_);
+        if (!path_.empty()) unlink(path_.c_str());
+    }
+
+    int fd() const { return fd_; }
+    const std::string& path() const { return path_; }
+
+   private:
+    int fd_{-1};
+    std::string path_;
+};
+
+Status installLocalFileSegment(ControlService& metadata,
+                               const std::string& path, size_t length) {
+    return metadata.segmentManager().updateLocal(
+        [&](SegmentDesc& segment) -> Status {
+            segment.name = "io_uring_test_segment";
+            segment.machine_id = "io_uring_test_machine";
+            segment.type = SegmentType::File;
+            segment.detail = FileSegmentDesc{};
+            auto& files = std::get<FileSegmentDesc>(segment.detail);
+            files.buffers.clear();
+            FileBufferDesc buffer;
+            buffer.path = path;
+            buffer.length = length;
+            buffer.offset = 0;
+            files.buffers.push_back(std::move(buffer));
+            return Status::OK();
+        });
+}
+
+// Reports a positive short submission result on the first successful call
+// while letting the real io_uring_submit() through, so the kernel-side
+// state matches a genuine short submission.
+class ShortSubmitIOUringTransport : public IOUringTransport {
+   public:
+    void injectShortSubmit(int reported) { short_report_ = reported; }
+
+    int submitCalls() const { return submit_calls_; }
+
+   protected:
+    int submitSqes(struct io_uring* ring) override {
+        int rc = IOUringTransport::submitSqes(ring);
+        ++submit_calls_;
+        if (short_report_ > 0 && rc > short_report_) {
+            deficit_ = rc - short_report_;
+            int reported = short_report_;
+            short_report_ = 0;
+            return reported;
+        }
+        if (deficit_ > 0) {
+            rc += deficit_;
+            deficit_ = 0;
+        }
+        return rc;
+    }
+
+   private:
+    int short_report_ = 0;
+    int deficit_ = 0;
+    int submit_calls_ = 0;
+};
+
+Status installTransport(IOUringTransport& transport,
+                        std::shared_ptr<ControlService>& metadata) {
+    std::string local_segment_name = "io_uring_test_segment";
+    return transport.install(local_segment_name, metadata, nullptr,
+                             std::make_shared<Config>());
+}
+
+TransferStatus pollUntilSettled(IOUringTransport& transport,
+                                Transport::SubBatchRef batch, int task_id) {
+    TransferStatus ts{};
+    for (int attempts = 0; attempts < 10000; ++attempts) {
+        EXPECT_TRUE(transport.getTransferStatus(batch, task_id, ts).ok());
+        if (ts.s != TransferStatusEnum::PENDING &&
+            ts.s != TransferStatusEnum::INITIAL)
+            return ts;
+        usleep(1000);
+    }
+    return ts;
+}
+
+// A positive short io_uring_submit() result must not fail the submission:
+// part of the batch is already dispatched, so an error return would make
+// the engine's submit-stage failover re-execute those requests.
+TEST(IOUringTransportTest, ShortSubmitIsNotAnErrorAndExecutesExactlyOnce) {
+    const size_t kFileLength = 4 * kPageSize;
+    const size_t kRequestCount = 3;
+
+    ScopedTempFile file(kFileLength);
+    ASSERT_GE(file.fd(), 0);
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    ASSERT_TRUE(
+        installLocalFileSegment(*metadata, file.path(), kFileLength).ok());
+
+    ShortSubmitIOUringTransport transport;
+    transport.injectShortSubmit(1);
+    auto install_status = installTransport(transport, metadata);
+    if (!install_status.ok()) {
+        GTEST_SKIP() << "io_uring unavailable: " << install_status.message();
+    }
+
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(batch, 8).ok());
+
+    // Page-aligned source keeps every request on the direct (non-staging)
+    // path and valid under O_DIRECT.
+    void* source = nullptr;
+    ASSERT_EQ(posix_memalign(&source, kPageSize, kRequestCount * kPageSize), 0);
+    auto* source_bytes = static_cast<uint8_t*>(source);
+
+    std::vector<Request> requests;
+    for (size_t i = 0; i < kRequestCount; ++i) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = source_bytes + i * kPageSize;
+        req.target_id = LOCAL_SEGMENT_ID;
+        req.target_offset = i * kPageSize;
+        req.length = kPageSize;
+        // Distinct pattern per request: verifies exactly-once placement.
+        std::memset(req.source, 0x10 + i, kPageSize);
+        requests.push_back(req);
+    }
+
+    auto status = transport.submitTransferTasks(batch, requests);
+    // The old code returned InternalError here while the SQEs were already
+    // in flight.
+    EXPECT_TRUE(status.ok());
+    // The flush loop retried after the short report.
+    EXPECT_GE(transport.submitCalls(), 2);
+
+    for (size_t i = 0; i < kRequestCount; ++i) {
+        auto ts = pollUntilSettled(transport, batch, (int)i);
+        EXPECT_EQ(ts.s, TransferStatusEnum::COMPLETED);
+    }
+
+    // Exactly-once: every page holds its own request's pattern.
+    std::vector<uint8_t> expected(kFileLength, 0);
+    for (size_t i = 0; i < kRequestCount; ++i)
+        std::memset(expected.data() + i * kPageSize, 0x10 + i, kPageSize);
+    std::vector<uint8_t> actual(kFileLength, 0);
+    ASSERT_EQ(pread(file.fd(), actual.data(), kFileLength, 0),
+              (ssize_t)kFileLength);
+    EXPECT_EQ(std::memcmp(actual.data(), expected.data(), kFileLength), 0);
+
+    free(source);
+    ASSERT_TRUE(transport.freeSubBatch(batch).ok());
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+// Regression for the all-or-nothing submission contract: a mid-batch
+// segment-lookup failure (the second of three requests targets an unknown
+// segment) must return an error without appending tasks, preparing SQEs or
+// executing anything. The old loop appended each task before validating it
+// and left the earlier requests' SQEs queued in the ring, so the next
+// submission on the same sub-batch would have flushed them.
+TEST(IOUringTransportTest, SubmitIsAllOrNothingWhenSegmentLookupFailsMidBatch) {
+    const size_t kFileLength = 2 * kPageSize;
+
+    ScopedTempFile file(kFileLength);
+    ASSERT_GE(file.fd(), 0);
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    ASSERT_TRUE(
+        installLocalFileSegment(*metadata, file.path(), kFileLength).ok());
+
+    IOUringTransport transport;
+    auto install_status = installTransport(transport, metadata);
+    if (!install_status.ok()) {
+        GTEST_SKIP() << "io_uring unavailable: " << install_status.message();
+    }
+
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(batch, 8).ok());
+    auto* uring_batch = dynamic_cast<IOUringSubBatch*>(batch);
+    ASSERT_NE(uring_batch, nullptr);
+    const int sq_space_before = io_uring_sq_space_left(&uring_batch->ring);
+
+    // Heap (page-unaligned) source exercises the staging-buffer allocation
+    // that must be rolled back on failure.
+    std::vector<uint8_t> source(kPageSize, 0xA5);
+    auto makeRequest = [&](SegmentID target_id, uint64_t target_offset) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = source.data();
+        req.target_id = target_id;
+        req.target_offset = target_offset;
+        req.length = kPageSize;
+        return req;
+    };
+    std::vector<Request> requests{
+        makeRequest(LOCAL_SEGMENT_ID, 0),
+        // Unknown target segment: lookup fails fast with an error.
+        makeRequest(kUnknownSegment, 0),
+        makeRequest(LOCAL_SEGMENT_ID, kPageSize)};
+
+    auto status = transport.submitTransferTasks(batch, requests);
+    EXPECT_FALSE(status.ok());
+
+    // Nothing was accepted: no tasks appended ...
+    EXPECT_EQ(uring_batch->task_list.size(), 0u);
+    // ... and no SQE was prepared for the rejected batch.
+    EXPECT_EQ(io_uring_sq_space_left(&uring_batch->ring), sq_space_before);
+
+    // Nothing was executed: the file stays zeroed.
+    std::vector<uint8_t> actual(kFileLength, 1);
+    ASSERT_EQ(pread(file.fd(), actual.data(), kFileLength, 0),
+              (ssize_t)kFileLength);
+    for (size_t i = 0; i < kFileLength; ++i) EXPECT_EQ(actual[i], 0u);
+
+    // The transport stays usable after the rejected batch: the valid
+    // requests (minus the bad one) submit and complete cleanly.
+    std::vector<Request> valid_requests{makeRequest(LOCAL_SEGMENT_ID, 0)};
+    EXPECT_TRUE(transport.submitTransferTasks(batch, valid_requests).ok());
+    EXPECT_EQ(uring_batch->task_list.size(), 1u);
+    auto ts = pollUntilSettled(transport, batch, 0);
+    EXPECT_EQ(ts.s, TransferStatusEnum::COMPLETED);
+
+    std::memset(actual.data(), 1, kFileLength);
+    ASSERT_EQ(pread(file.fd(), actual.data(), kFileLength, 0),
+              (ssize_t)kFileLength);
+    for (size_t i = 0; i < kPageSize; ++i) EXPECT_EQ(actual[i], 0xA5);
+    // The never-submitted second page stays zeroed: no phantom SQE from the
+    // rejected batch leaked into this submission.
+    for (size_t i = kPageSize; i < kFileLength; ++i) EXPECT_EQ(actual[i], 0u);
+
+    ASSERT_TRUE(transport.freeSubBatch(batch).ok());
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/local_memory_lifecycle_test.cpp b/mooncake-transfer-engine/tent/tests/local_memory_lifecycle_test.cpp
new file mode 100644
index 0000000000..81da103fef
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/local_memory_lifecycle_test.cpp
@@ -0,0 +1,185 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/runtime/transport.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class FailOnceFreeTransport : public Transport {
+   public:
+    Status allocateLocalMemory(void** addr, size_t size,
+                               MemoryOptions&) override {
+        *addr = std::malloc(size);
+        return *addr ? Status::OK()
+                     : Status::InternalError("malloc failed" LOC_MARK);
+    }
+
+    Status freeLocalMemory(void* addr, size_t) override {
+        ++free_calls;
+        if (free_calls == 1) {
+            return Status::InternalError("injected free failure" LOC_MARK);
+        }
+        std::free(addr);
+        return Status::OK();
+    }
+
+    const char* getName() const override { return "fail-once-free"; }
+
+    int free_calls{0};
+};
+
+std::shared_ptr<Config> makeConfig() {
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("metadata_servers", "");
+    config->set("rpc_server_hostname", "127.0.0.1");
+    config->set("rpc_server_port", "0");
+    config->set("log_level", "warning");
+
+    for (const char* transport : {"tcp", "shm", "rdma", "io_uring", "nvlink",
+                                  "mnnvl", "gds", "ascend_direct"}) {
+        config->set(std::string("transports/") + transport + "/enable", false);
+    }
+    return config;
+}
+
+TEST(LocalMemoryLifecycle, RetainsOwnershipWhenTransportFreeFails) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto transport = std::make_shared<FailOnceFreeTransport>();
+    engine.swapTransportForTest(RDMA, transport);
+
+    MemoryOptions options;
+    options.type = RDMA;
+    options.location = "cpu:0";
+    void* addr = nullptr;
+    ASSERT_TRUE(engine.allocateLocalMemory(&addr, 4096, options).ok());
+
+    auto first = engine.freeLocalMemory(addr);
+    EXPECT_FALSE(first.ok());
+    EXPECT_EQ(transport->free_calls, 1);
+
+    auto second = engine.freeLocalMemory(addr);
+    EXPECT_TRUE(second.ok()) << second.ToString();
+    EXPECT_EQ(transport->free_calls, 2);
+
+    auto third = engine.freeLocalMemory(addr);
+    EXPECT_TRUE(third.IsInvalidArgument());
+    EXPECT_EQ(transport->free_calls, 2);
+}
+
+TEST(LocalMemoryLifecycle, SegmentInfoReplacesPreviouslyReportedBuffers) {
+    auto config = makeConfig();
+    config->set("transports/tcp/enable", true);
+    std::vector<char> buffer(4096);
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+    ASSERT_TRUE(engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+
+    SegmentInfo info;
+    ASSERT_TRUE(engine.getSegmentInfo(LOCAL_SEGMENT_ID, info).ok());
+    ASSERT_EQ(info.buffers.size(), 1u);
+    EXPECT_EQ(info.buffers.front().base,
+              reinterpret_cast<uint64_t>(buffer.data()));
+    EXPECT_EQ(info.buffers.front().length, buffer.size());
+
+    // Reusing the output must not duplicate buffers from the previous call.
+    ASSERT_TRUE(engine.getSegmentInfo(LOCAL_SEGMENT_ID, info).ok());
+    EXPECT_EQ(info.buffers.size(), 1u);
+
+    ASSERT_TRUE(
+        engine.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+    ASSERT_TRUE(engine.getSegmentInfo(LOCAL_SEGMENT_ID, info).ok());
+    EXPECT_TRUE(info.buffers.empty())
+        << "An unregistered buffer must not survive a segment-info refresh";
+}
+
+TEST(LocalMemoryLifecycle, ShmAcceptsDefaultAllocationLocation) {
+    auto config = makeConfig();
+    config->set("transports/shm/enable", true);
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+
+    void* address = nullptr;
+    auto status = engine.allocateLocalMemory(&address, 4096, kWildcardLocation);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    std::memset(address, 0x5a, 4096);
+    EXPECT_TRUE(engine.freeLocalMemory(address).ok());
+}
+
+TEST(LocalMemoryLifecycle, DefaultHostOptionsAllocateUsableSharedMemory) {
+    auto config = makeConfig();
+    config->set("transports/shm/enable", true);
+    TransferEngineImpl target(config);
+    TransferEngineImpl initiator(config);
+    ASSERT_TRUE(target.available());
+    ASSERT_TRUE(initiator.available());
+
+    MemoryOptions target_options;
+    MemoryOptions source_options;
+    source_options.location = "cpu:0";
+    void* source = nullptr;
+    void* destination = nullptr;
+    constexpr size_t kSize = 4096;
+    auto status = target.allocateLocalMemory(&source, kSize, target_options);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    status = initiator.allocateLocalMemory(&destination, kSize, source_options);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(target_options.type, SHM);
+    EXPECT_EQ(source_options.type, SHM);
+    EXPECT_EQ(target_options.location, kWildcardLocation);
+    EXPECT_EQ(source_options.location, "cpu:0");
+    ASSERT_FALSE(target_options.shm_path.empty());
+    ASSERT_TRUE(
+        target.registerLocalMemory({source}, {kSize}, target_options).ok());
+    ASSERT_TRUE(
+        initiator.registerLocalMemory({destination}, {kSize}, source_options)
+            .ok());
+    std::memset(source, 0x6b, kSize);
+    std::memset(destination, 0, kSize);
+
+    SegmentID peer;
+    ASSERT_TRUE(initiator.openSegment(peer, target.getSegmentName()).ok());
+    Request request;
+    request.opcode = Request::READ;
+    request.source = destination;
+    request.target_id = peer;
+    request.target_offset = reinterpret_cast<uint64_t>(source);
+    request.length = kSize;
+    ASSERT_TRUE(initiator.transferSync({request}).ok());
+    EXPECT_EQ(std::memcmp(source, destination, kSize), 0);
+
+    EXPECT_TRUE(initiator.closeSegment(peer).ok());
+    EXPECT_TRUE(initiator.unregisterLocalMemory(destination).ok());
+    EXPECT_TRUE(target.unregisterLocalMemory(source).ok());
+    EXPECT_TRUE(initiator.freeLocalMemory(destination).ok());
+    EXPECT_TRUE(target.freeLocalMemory(source).ok());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/local_notification_test.cpp b/mooncake-transfer-engine/tent/tests/local_notification_test.cpp
new file mode 100644
index 0000000000..02060d2b1a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/local_notification_test.cpp
@@ -0,0 +1,473 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Self-targeted (intra-agent) notifications must be delivered in-process.
+//
+// The data plane short-circuits LOCAL_SEGMENT_ID transfers to the local
+// path, but notifications used to be routed unconditionally through the
+// first transport that supports them; over RDMA the local pseudo-endpoint
+// has no notification QP, so the send failed and a receiver polling for the
+// notification hung forever. These tests pin the in-process delivery
+// contract without requiring any NIC or a metadata server.
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/transfer_engine_impl.h"
+
+namespace mooncake {
+namespace tent {
+
+namespace {
+
+constexpr char kSegmentName[] = "local-notification-test-segment";
+
+std::shared_ptr<Config> makeConfig(bool enable_tcp,
+                                   const char* name = kSegmentName) {
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("local_segment_name", name);
+    config->set("rpc_server_hostname", "127.0.0.1");
+    config->set("rpc_server_port", "0");
+    config->set("log_level", "warning");
+    config->set("transports/tcp/enable", enable_tcp);
+    config->set("transports/shm/enable", false);
+    config->set("transports/rdma/enable", false);
+    config->set("transports/io_uring/enable", false);
+    config->set("transports/nvlink/enable", false);
+    config->set("transports/mnnvl/enable", false);
+    config->set("transports/gds/enable", false);
+    config->set("transports/ascend_direct/enable", false);
+    config->set("transports/sunrise_link/enable", false);
+    config->set("transports/mpcomm/enable", false);
+    config->set("transports/tpu/enable", false);
+    config->set("transports/ub/enable", false);
+    // The progress worker would fire submit hooks from its own thread while
+    // the test reads the stand-in transport's counter, and the runtime queue
+    // turns it on implicitly. Keep every poll on the calling thread.
+    config->set("enable_progress_worker", false);
+    config->set("enable_runtime_queue", false);
+    return config;
+}
+
+}  // namespace
+
+// Opening the local segment by the engine's own advertised name (or the
+// empty name) must resolve to LOCAL_SEGMENT_ID - that is the id the delivery
+// below keys on. Note: in p2p mode the advertised name is the normalized
+// "ip:port", not the configured local_segment_name.
+TEST(LocalNotificationTest, OwnNameResolvesToLocalSegmentId) {
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/true));
+    ASSERT_TRUE(engine.available());
+
+    SegmentID handle = ~0ull;
+    ASSERT_TRUE(engine.openSegment(handle, engine.getSegmentName()).ok());
+    EXPECT_EQ(handle, LOCAL_SEGMENT_ID);
+
+    handle = ~0ull;
+    ASSERT_TRUE(engine.openSegment(handle, "").ok());
+    EXPECT_EQ(handle, LOCAL_SEGMENT_ID);
+}
+
+// Notifications sent to LOCAL_SEGMENT_ID come back from the next
+// receiveNotification() poll, in order, exactly once.
+TEST(LocalNotificationTest, SelfNotificationIsDeliveredInProcess) {
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/true));
+    ASSERT_TRUE(engine.available());
+
+    const int kCount = 8;
+    for (int i = 0; i < kCount; ++i) {
+        Notification notifi;
+        notifi.name = kSegmentName;
+        notifi.msg = "payload-" + std::to_string(i);
+        ASSERT_TRUE(engine.sendNotification(LOCAL_SEGMENT_ID, notifi).ok());
+    }
+
+    std::vector<Notification> received;
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), static_cast<size_t>(kCount));
+    for (int i = 0; i < kCount; ++i) {
+        EXPECT_EQ(received[i].name, kSegmentName);
+        EXPECT_EQ(received[i].msg, "payload-" + std::to_string(i));
+    }
+
+    // Delivered exactly once. Poll again through the same vector the caller
+    // already used: a poll reports what that poll delivered, so the previous
+    // batch must not reappear just because the caller reused its buffer.
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    EXPECT_TRUE(received.empty());
+}
+
+// Self-delivery must not depend on any transport advertising notification
+// support: with every transport disabled the local queue still works, while
+// an empty poll keeps reporting the original "not supported" error.
+TEST(LocalNotificationTest, WorksWithoutAnyNotificationTransport) {
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/false));
+    ASSERT_TRUE(engine.available());
+
+    std::vector<Notification> received;
+    EXPECT_FALSE(engine.receiveNotification(received).ok());
+
+    Notification notifi;
+    notifi.name = kSegmentName;
+    notifi.msg = "no-transport-payload";
+    ASSERT_TRUE(engine.sendNotification(LOCAL_SEGMENT_ID, notifi).ok());
+
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), 1u);
+    EXPECT_EQ(received[0].msg, "no-transport-payload");
+
+    // Drained: the same vector comes back empty, and with nothing left to
+    // deliver the "not supported" error is reported again.
+    EXPECT_FALSE(engine.receiveNotification(received).ok());
+    EXPECT_TRUE(received.empty());
+}
+
+// Stands in for the RDMA transport on a self-addressed notification: it
+// advertises notification support, so the pre-fix routing picked it, but the
+// local pseudo-endpoint owns no notification QP and the send fails
+// ("Notification QP not connected"). Nothing is ever received from it.
+class LocalSendFailsTransport : public Transport {
+   public:
+    int send_attempts = 0;
+    // Lets a test stop failing, standing in for a peer that comes back.
+    bool fail_sends = true;
+
+    Status install(std::string&, std::shared_ptr<ControlService>,
+                   std::shared_ptr<Topology>,
+                   std::shared_ptr<Config>) override {
+        return Status::OK();
+    }
+
+    bool supportNotification() const override { return true; }
+
+    Status sendNotification(SegmentID, const Notification&) override {
+        ++send_attempts;
+        if (!fail_sends) return Status::OK();
+        return Status::InternalError("Notification QP not connected");
+    }
+
+    Status receiveNotification(std::vector<Notification>& out) override {
+        out.clear();
+        return Status::OK();
+    }
+
+    const char* getName() const override { return "<local-send-fails>"; }
+};
+
+// The failure this fix addresses: an intra-agent transfer that carries a
+// notification. submitTransfer() binds the notification to the batch, and the
+// completion poll fires it through maybeFireSubmitHooks() ->
+// sendNotification(LOCAL_SEGMENT_ID). Before the fix that call was handed to
+// the first notification-capable transport, whose local pseudo-endpoint has no
+// notification QP, so the notification never arrived and a receiver polling
+// for it hung.
+//
+// The stand-in transport above is what makes this a regression test rather
+// than a round trip: left to a real transport the engine's own RPC server
+// answers on loopback, so a self-addressed notification can reach itself over
+// the wire even without the local short-circuit. Needs no NIC, no peer
+// process and no metadata server.
+TEST(LocalNotificationTest, TransferBoundSelfNotificationIsDelivered) {
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/true));
+    ASSERT_TRUE(engine.available());
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> source(kBufLen, 0x5A);
+    std::vector<uint8_t> target(kBufLen, 0);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), kBufLen).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), kBufLen).ok());
+
+    // Registration is done, so the data path is set up; now put the
+    // can't-deliver-locally transport ahead of TCP for notification routing.
+    auto probe = std::make_shared<LocalSendFailsTransport>();
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(probe->install(seg_name, nullptr, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, probe);
+
+    Notification notifi;
+    notifi.name = kSegmentName;
+    notifi.msg = "transfer-bound-self";
+
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = source.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(target.data());
+    req.length = kBufLen;
+
+    BatchID batch = engine.allocateBatch(4);
+    ASSERT_TRUE(engine.submitTransfer(batch, {req}, notifi).ok());
+
+    TransferStatus overall{};
+    uint64_t polls = 0;
+    while (true) {
+        ASSERT_TRUE(engine.getTransferStatus(batch, overall).ok());
+        if (overall.s == TransferStatusEnum::COMPLETED) break;
+        ASSERT_NE(overall.s, TransferStatusEnum::FAILED);
+        waitBeforeNextPoll(polls++);
+        ASSERT_LT(polls, 100000u) << "local transfer did not complete";
+    }
+    EXPECT_EQ(target[0], 0x5A);
+    EXPECT_EQ(target[kBufLen - 1], 0x5A);
+
+    std::vector<Notification> received;
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), 1u);
+    EXPECT_EQ(received[0].msg, "transfer-bound-self");
+    // Delivered in-process: the transport was never asked to carry it.
+    EXPECT_EQ(probe->send_attempts, 0);
+
+    (void)engine.freeBatch(batch);
+    (void)engine.unregisterLocalMemory(source.data(), kBufLen);
+    (void)engine.unregisterLocalMemory(target.data(), kBufLen);
+}
+
+// A hook fires once per target, and it reruns from every later poll until all
+// of its targets have taken delivery. Self-targeted sends always succeed now,
+// so a peer that stays unreachable must not make the engine re-queue the local
+// copy on each of those polls: the receiver would see one "transfer complete"
+// per poll and the local queue would grow without bound.
+TEST(LocalNotificationTest, NotifiedTargetIsNotRedeliveredWhileAPeerFails) {
+    TransferEngineImpl peer(makeConfig(/*enable_tcp=*/true, "peer-segment"));
+    ASSERT_TRUE(peer.available());
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/true));
+    ASSERT_TRUE(engine.available());
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> source(kBufLen, 0x5A);
+    std::vector<uint8_t> local_target(kBufLen, 0);
+    std::vector<uint8_t> peer_target(kBufLen, 0);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), kBufLen).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(local_target.data(), kBufLen).ok());
+    ASSERT_TRUE(peer.registerLocalMemory(peer_target.data(), kBufLen).ok());
+
+    SegmentID remote = ~0ull;
+    ASSERT_TRUE(engine.openSegment(remote, peer.getSegmentName()).ok());
+    ASSERT_NE(remote, LOCAL_SEGMENT_ID);
+
+    // Notification routing goes to a transport that always fails, so the hook's
+    // remote leg never succeeds while the data path still completes.
+    auto probe = std::make_shared<LocalSendFailsTransport>();
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(probe->install(seg_name, nullptr, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, probe);
+
+    Notification notifi;
+    notifi.name = kSegmentName;
+    notifi.msg = "two-targets";
+
+    Request local_req;
+    local_req.opcode = Request::WRITE;
+    local_req.source = source.data();
+    local_req.target_id = LOCAL_SEGMENT_ID;
+    local_req.target_offset = reinterpret_cast<uint64_t>(local_target.data());
+    local_req.length = kBufLen;
+
+    Request remote_req;
+    remote_req.opcode = Request::WRITE;
+    remote_req.source = source.data();
+    remote_req.target_id = remote;
+    remote_req.target_offset = reinterpret_cast<uint64_t>(peer_target.data());
+    remote_req.length = kBufLen;
+
+    BatchID batch = engine.allocateBatch(4);
+    // Order does not matter any more: every remaining target is attempted on
+    // every pass. SelfNotificationIsNotHeldBackByAnUnreachablePeer below is
+    // the test that pins that; this one pins exactly-once delivery.
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {remote_req, local_req}, notifi).ok());
+
+    TransferStatus overall{};
+    uint64_t polls = 0;
+    while (true) {
+        ASSERT_TRUE(engine.getTransferStatus(batch, overall).ok());
+        if (overall.s == TransferStatusEnum::COMPLETED) break;
+        ASSERT_NE(overall.s, TransferStatusEnum::FAILED);
+        waitBeforeNextPoll(polls++);
+        ASSERT_LT(polls, 100000u) << "two-target transfer did not complete";
+    }
+
+    // Keep polling: every poll of a completed batch reruns the hook, and the
+    // remote target keeps failing, so the hook is never marked fired.
+    size_t delivered = 0;
+    for (int i = 0; i < 5; ++i) {
+        std::vector<Notification> received;
+        (void)engine.receiveNotification(received);
+        delivered += received.size();
+        TransferStatus again{};
+        (void)engine.getTransferStatus(batch, again);
+    }
+
+    // Let the peer recover. The hook can now complete, and whichever target
+    // was still outstanding is sent - but a target that already took delivery
+    // must not be sent a second time.
+    probe->fail_sends = false;
+    for (int i = 0; i < 3; ++i) {
+        std::vector<Notification> received;
+        (void)engine.receiveNotification(received);
+        delivered += received.size();
+        TransferStatus again{};
+        (void)engine.getTransferStatus(batch, again);
+    }
+
+    // Exactly once, across the failing phase and the recovery. Without
+    // per-target progress the failing phase re-queues the local copy on every
+    // poll and this is 7.
+    EXPECT_EQ(delivered, 1u)
+        << "self-notification delivered " << delivered << " times";
+    // The peer really was retried while it was down, so the guard above comes
+    // from per-target progress and not from the hook giving up.
+    EXPECT_GT(probe->send_attempts, 1);
+
+    (void)engine.freeBatch(batch);
+    (void)engine.unregisterLocalMemory(source.data(), kBufLen);
+    (void)engine.unregisterLocalMemory(local_target.data(), kBufLen);
+    (void)peer.unregisterLocalMemory(peer_target.data(), kBufLen);
+}
+
+// Delivery to one target must not depend on where an unreachable one happens
+// to sit in the iteration order. hook.targets is an unordered_set; a loop that
+// stopped at the first failure would leave every target behind it unattempted,
+// and because the order is stable across polls it would stay that way. A
+// self-targeted notification cannot fail, so an unrelated peer being down
+// would block a local receiver until that peer came back.
+//
+// Two unreachable peers are what makes the check order-independent: with the
+// fix every pass attempts both of them, without it a pass stops after one.
+// That count is the deterministic part. The first-poll delivery assertion is
+// the property callers actually care about, but on its own it only fails when
+// the iteration order happens to put a peer first.
+TEST(LocalNotificationTest, SelfNotificationIsNotHeldBackByAnUnreachablePeer) {
+    TransferEngineImpl peer_a(makeConfig(/*enable_tcp=*/true, "peer-a"));
+    ASSERT_TRUE(peer_a.available());
+    TransferEngineImpl peer_b(makeConfig(/*enable_tcp=*/true, "peer-b"));
+    ASSERT_TRUE(peer_b.available());
+    TransferEngineImpl engine(makeConfig(/*enable_tcp=*/true));
+    ASSERT_TRUE(engine.available());
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> source(kBufLen, 0x5A);
+    std::vector<uint8_t> local_target(kBufLen, 0);
+    std::vector<uint8_t> a_target(kBufLen, 0);
+    std::vector<uint8_t> b_target(kBufLen, 0);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), kBufLen).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(local_target.data(), kBufLen).ok());
+    ASSERT_TRUE(peer_a.registerLocalMemory(a_target.data(), kBufLen).ok());
+    ASSERT_TRUE(peer_b.registerLocalMemory(b_target.data(), kBufLen).ok());
+
+    SegmentID remote_a = ~0ull, remote_b = ~0ull;
+    ASSERT_TRUE(engine.openSegment(remote_a, peer_a.getSegmentName()).ok());
+    ASSERT_TRUE(engine.openSegment(remote_b, peer_b.getSegmentName()).ok());
+    ASSERT_NE(remote_a, LOCAL_SEGMENT_ID);
+    ASSERT_NE(remote_b, LOCAL_SEGMENT_ID);
+    ASSERT_NE(remote_a, remote_b);
+
+    // The data path stays real - all three writes complete, which is what
+    // lets the hook fire. Only notification routing is swapped for a
+    // transport that fails, standing in for peers that cannot take delivery.
+    auto probe = std::make_shared<LocalSendFailsTransport>();
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(probe->install(seg_name, nullptr, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, probe);
+
+    Notification notifi;
+    notifi.name = kSegmentName;
+    notifi.msg = "three-targets";
+
+    auto make_req = [&](SegmentID target, void* dst) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = source.data();
+        req.target_id = target;
+        req.target_offset = reinterpret_cast<uint64_t>(dst);
+        req.length = kBufLen;
+        return req;
+    };
+
+    BatchID batch = engine.allocateBatch(8);
+    ASSERT_TRUE(
+        engine
+            .submitTransfer(batch,
+                            {make_req(remote_a, a_target.data()),
+                             make_req(remote_b, b_target.data()),
+                             make_req(LOCAL_SEGMENT_ID, local_target.data())},
+                            notifi)
+            .ok());
+
+    TransferStatus overall{};
+    uint64_t polls = 0;
+    while (true) {
+        ASSERT_TRUE(engine.getTransferStatus(batch, overall).ok());
+        if (overall.s == TransferStatusEnum::COMPLETED) break;
+        ASSERT_NE(overall.s, TransferStatusEnum::FAILED);
+        waitBeforeNextPoll(polls++);
+        ASSERT_LT(polls, 100000u) << "three-target transfer did not complete";
+    }
+
+    // The poll that saw COMPLETED already ran the hook, so the local
+    // notification must be waiting now - while both peers are still down.
+    size_t delivered = 0;
+    std::vector<Notification> first;
+    ASSERT_TRUE(engine.receiveNotification(first).ok());
+    delivered += first.size();
+    EXPECT_EQ(first.size(), 1u)
+        << "the self-targeted notification was held back by an unreachable "
+           "peer";
+    if (!first.empty()) EXPECT_EQ(first[0].msg, "three-targets");
+
+    // Every pass must attempt both failing peers. This is the part that does
+    // not depend on iteration order: stopping at the first failure gives one
+    // attempt per pass instead of two.
+    constexpr int kPasses = 4;
+    const int before = probe->send_attempts;
+    for (int i = 0; i < kPasses; ++i) {
+        TransferStatus again{};
+        (void)engine.getTransferStatus(batch, again);
+        std::vector<Notification> more;
+        (void)engine.receiveNotification(more);
+        delivered += more.size();
+    }
+    EXPECT_EQ(probe->send_attempts - before, 2 * kPasses)
+        << "each pass must attempt both unreachable peers; got "
+        << (probe->send_attempts - before) << " attempts over " << kPasses
+        << " passes";
+
+    // Let both peers recover: the hook completes, and the target that already
+    // took delivery is not sent a second time.
+    probe->fail_sends = false;
+    for (int i = 0; i < 3; ++i) {
+        TransferStatus again{};
+        (void)engine.getTransferStatus(batch, again);
+        std::vector<Notification> more;
+        (void)engine.receiveNotification(more);
+        delivered += more.size();
+    }
+    EXPECT_EQ(delivered, 1u)
+        << "self-notification delivered " << delivered << " times";
+
+    (void)engine.freeBatch(batch);
+    (void)engine.unregisterLocalMemory(source.data(), kBufLen);
+    (void)engine.unregisterLocalMemory(local_target.data(), kBufLen);
+    (void)peer_a.unregisterLocalMemory(a_target.data(), kBufLen);
+    (void)peer_b.unregisterLocalMemory(b_target.data(), kBufLen);
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/metrics_recording_test.cpp b/mooncake-transfer-engine/tent/tests/metrics_recording_test.cpp
index a88f9735cc..051a1b533c 100644
--- a/mooncake-transfer-engine/tent/tests/metrics_recording_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/metrics_recording_test.cpp
@@ -260,7 +260,12 @@ class FakeTransport : public Transport {
         return Status::OK();
     }
 
-    Status removeMemoryBuffer(BufferDesc&) override { return Status::OK(); }
+    Status removeMemoryBuffer(BufferDesc& desc) override {
+        desc.transports.erase(std::remove(desc.transports.begin(),
+                                          desc.transports.end(), self_type_),
+                              desc.transports.end());
+        return Status::OK();
+    }
 
     Status allocateLocalMemory(void** addr, size_t size,
                                MemoryOptions&) override {
@@ -622,6 +627,132 @@ TEST_F(MetricsRecordingTest, FailoverResubmitSyncFailureRecordsBothAttempts) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
 }
 
+// ---------------------------------------------------------------------------
+// Submit-stage failover: the primary transport fails synchronously inside
+// submitTransferTasks() and the engine recovers on the secondary. The
+// failover counter must advance and the logical completion must be attributed
+// to the transport that completed the request.
+// ---------------------------------------------------------------------------
+TEST_F(MetricsRecordingTest, SubmitStageFailoverRecordsFailoverAndCompletion) {
+    auto cfg = makeMetricsTestConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, /*force_fail=*/false, /*force_submit_fail=*/true);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP, /*force_fail=*/false);
+    installFakeRdma(engine, fake_rdma);
+    installFakeTcp(engine, fake_tcp);
+
+    constexpr size_t kLen = 4096;
+    std::vector<uint8_t> buf(kLen, 0xB7);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    BatchID batch = engine.allocateBatch(4);
+    ASSERT_NE(batch, (BatchID)0);
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {makeLocalWrite(buf.data(), kLen)}).ok());
+    ASSERT_EQ(pollUntilTerminal(engine, batch, 0),
+              TransferStatusEnum::COMPLETED);
+    auto after = MetricsSnapshot(TentMetrics::instance());
+
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+
+    // Two attempts: RDMA failed synchronously, TCP completed.
+    EXPECT_EQ(after.counter("tent_transport_attempts_total") -
+                  before.counter("tent_transport_attempts_total"),
+              2);
+    EXPECT_EQ(after.counter("tent_transport_attempt_failures_total") -
+                  before.counter("tent_transport_attempt_failures_total"),
+              1);
+    const std::string rdma_attempt_failures =
+        "tent_transport_attempt_failures_total{transport=\"rdma\",operation="
+        "\"write\"}";
+    EXPECT_EQ(after.series(rdma_attempt_failures) -
+                  before.series(rdma_attempt_failures),
+              1);
+
+    // Exactly one cross-transport failover event rdma -> tcp.
+    const std::string failover =
+        "tent_transport_failover_total{from=\"rdma\",to=\"tcp\"}";
+    EXPECT_EQ(after.series(failover) - before.series(failover), 1);
+
+    // The logical write completed on the fallback transport, attributed to
+    // TCP rather than the failed primary.
+    const std::string tcp_writes =
+        "tent_write_requests_total{transport=\"tcp\"}";
+    EXPECT_EQ(after.series(tcp_writes) - before.series(tcp_writes), 1);
+    EXPECT_EQ(after.counter("tent_write_failures_total") -
+                  before.counter("tent_write_failures_total"),
+              0);
+
+    EXPECT_TRUE(engine.freeBatch(batch).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
+// ---------------------------------------------------------------------------
+// Submit-stage failover exhaustion: every candidate transport rejects the
+// submit synchronously. The terminal failure must be attributed to a real
+// transport (the last one attempted), never to "unspec".
+// ---------------------------------------------------------------------------
+TEST_F(MetricsRecordingTest, SubmitStageExhaustionAttributesToRealTransport) {
+    auto cfg = makeMetricsTestConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, /*force_fail=*/false, /*force_submit_fail=*/true);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP, /*force_fail=*/false,
+                                                    /*force_submit_fail=*/true);
+    installFakeRdma(engine, fake_rdma);
+    installFakeTcp(engine, fake_tcp);
+
+    constexpr size_t kLen = 4096;
+    std::vector<uint8_t> buf(kLen, 0x6D);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    BatchID batch = engine.allocateBatch(4);
+    ASSERT_NE(batch, (BatchID)0);
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {makeLocalWrite(buf.data(), kLen)}).ok());
+    ASSERT_EQ(pollUntilTerminal(engine, batch, 0), TransferStatusEnum::FAILED);
+    auto after = MetricsSnapshot(TentMetrics::instance());
+
+    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+
+    EXPECT_EQ(after.counter("tent_transport_attempts_total") -
+                  before.counter("tent_transport_attempts_total"),
+              2);
+    EXPECT_EQ(after.counter("tent_transport_attempt_failures_total") -
+                  before.counter("tent_transport_attempt_failures_total"),
+              2);
+
+    // The terminal write failure is attributed to the last attempted
+    // transport (tcp), NOT to "unspec".
+    const std::string tcp_write_failures =
+        "tent_write_failures_total{transport=\"tcp\"}";
+    const std::string unspec_write_failures =
+        "tent_write_failures_total{transport=\"unspec\"}";
+    EXPECT_EQ(
+        after.series(tcp_write_failures) - before.series(tcp_write_failures),
+        1);
+    EXPECT_EQ(after.series(unspec_write_failures) -
+                  before.series(unspec_write_failures),
+              0);
+    EXPECT_EQ(after.counter("tent_write_requests_total") -
+                  before.counter("tent_write_requests_total"),
+              1);
+
+    EXPECT_TRUE(engine.freeBatch(batch).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
 // ---------------------------------------------------------------------------
 // Failed transfer increments failures and requests but NOT bytes or size
 // histogram. Uses the direct API so the assertion is deterministic and does
@@ -709,6 +840,73 @@ TEST_F(MetricsRecordingTest, InfeasibleDeadlineRecordsSeparateCounter) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
 }
 
+// ---------------------------------------------------------------------------
+// A batch whose reclaim fails permanently is quarantined by lazyFreeBatch
+// after kMaxReclaimAttempts (4096) consecutive failures, and that event is
+// counted in tent_quarantined_batches_total. Drives the real sweep path.
+// ---------------------------------------------------------------------------
+
+// FakeTransport whose poll fails permanently once poisoned.
+class PoisonedPollFakeTransport : public FakeTransport {
+   public:
+    explicit PoisonedPollFakeTransport(TransportType type)
+        : FakeTransport(type) {}
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        if (poisoned.load(std::memory_order_acquire)) {
+            return Status::InternalError(
+                "injected permanent poll failure" LOC_MARK);
+        }
+        return FakeTransport::getTransferStatus(batch, task_id, status);
+    }
+
+    std::atomic<bool> poisoned{false};
+};
+
+TEST_F(MetricsRecordingTest, QuarantinedBatchIncrementsCounter) {
+    constexpr size_t kMaxReclaimAttempts = 4096;  // mirrors the impl constant
+    auto cfg = makeMetricsTestConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake = std::make_shared<PoisonedPollFakeTransport>(RDMA);
+    installFakeRdma(engine, fake);
+
+    constexpr size_t kLen = 4096;
+    std::vector<uint8_t> buf(kLen, 0xAB);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    BatchID batch = engine.allocateBatch(1);
+    ASSERT_NE(batch, (BatchID)0);
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {makeLocalWrite(buf.data(), kLen)}).ok());
+    fake->poisoned.store(true, std::memory_order_release);
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+    // Each freeBatch call on an already free-requested batch runs one sweep.
+    ASSERT_TRUE(engine.freeBatch(batch).ok());
+    for (size_t i = 0; i + 1 < kMaxReclaimAttempts; ++i) {
+        (void)engine.freeBatch(batch);
+    }
+    auto after = MetricsSnapshot(TentMetrics::instance());
+
+    EXPECT_EQ(after.counter("tent_quarantined_batches_total") -
+                  before.counter("tent_quarantined_batches_total"),
+              1)
+        << "quarantining a batch must increment "
+           "tent_quarantined_batches_total exactly once";
+    // Prometheus endpoint carries the series too.
+    EXPECT_EQ(after.series("tent_quarantined_batches_total") -
+                  before.series("tent_quarantined_batches_total"),
+              1);
+
+    // Unpoison so teardown drains cleanly; the batch itself is reclaimed by
+    // the engine destructor regardless.
+    fake->poisoned.store(false, std::memory_order_release);
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
 // ---------------------------------------------------------------------------
 // A transfer whose deadline is in the future records a genuine MLU sample
 // into the histogram (feasible or missed, but real).
@@ -867,6 +1065,253 @@ TEST_F(MetricsRecordingTest, BucketsAreCompileTimeDefaults) {
         << "latency buckets must be the compile-time defaults";
 }
 
+// Concurrency guard for the cached-cell hot path: several threads hammering
+// overlapping (transport, operation) labels must produce exactly the summed
+// counts — including the first-use window where multiple threads resolve the
+// same label cell concurrently. Exercises every hot-path metric family
+// (per-transport counters, N=2 attempt counters/histogram, stage histograms).
+TEST_F(MetricsRecordingTest, ConcurrentRecordsAcrossTransportsAreExact) {
+    constexpr int kThreads = 8;
+    constexpr int kIters = 2000;
+    constexpr size_t kBytes = 4096;
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+
+    std::vector<std::thread> threads;
+    for (int t = 0; t < kThreads; ++t) {
+        threads.emplace_back([t] {
+            for (int i = 0; i < kIters; ++i) {
+                // Even threads write to rdma, odd threads to nvlink, so both
+                // transports' cells are resolved concurrently.
+                TransportType tp = (t % 2 == 0) ? RDMA : NVLINK;
+                Request::OpCode op =
+                    (i % 2 == 0) ? Request::WRITE : Request::READ;
+                TentMetrics::instance().recordTransportAttemptStarted(tp, op);
+                TentMetrics::instance().recordTransportAttemptFinished(
+                    tp, op, TransferStatusEnum::COMPLETED, 150.0);
+                if (op == Request::WRITE) {
+                    TentMetrics::instance().recordWriteCompleted(tp, kBytes,
+                                                                 0.002);
+                } else {
+                    TentMetrics::instance().recordReadCompleted(tp, kBytes,
+                                                                0.002);
+                }
+                TentMetrics::instance().recordStageLatency(
+                    TentMetrics::Stage::Transport, tp, 120.0);
+            }
+        });
+    }
+    for (auto& thread : threads) {
+        thread.join();
+    }
+
+    auto after = MetricsSnapshot(TentMetrics::instance());
+    const int64_t total = kThreads * kIters;  // all attempts
+    const int64_t writes = total / 2;         // half the iterations
+    const int64_t bytes = writes * static_cast<int64_t>(kBytes);
+
+    EXPECT_EQ(after.counter("tent_write_bytes_total") -
+                  before.counter("tent_write_bytes_total"),
+              bytes);
+    EXPECT_EQ(after.counter("tent_read_bytes_total") -
+                  before.counter("tent_read_bytes_total"),
+              bytes);
+    EXPECT_EQ(after.counter("tent_write_requests_total") -
+                  before.counter("tent_write_requests_total"),
+              writes);
+    EXPECT_EQ(after.counter("tent_read_requests_total") -
+                  before.counter("tent_read_requests_total"),
+              writes);
+    EXPECT_EQ(after.counter("tent_transport_attempts_total") -
+                  before.counter("tent_transport_attempts_total"),
+              total);
+    EXPECT_EQ(after.histogramCount("tent_transport_attempt_latency_us") -
+                  before.histogramCount("tent_transport_attempt_latency_us"),
+              total);
+    EXPECT_EQ(after.histogramCount("tent_write_latency_us") -
+                  before.histogramCount("tent_write_latency_us"),
+              writes);
+    EXPECT_EQ(after.histogramCount("tent_stage_transport_us") -
+                  before.histogramCount("tent_stage_transport_us"),
+              total);
+    // Per-label Prometheus series must also be exact: 4 threads per transport,
+    // half of their iterations are writes.
+    const double per_transport_bytes =
+        static_cast<double>(kThreads / 2) * (kIters / 2) * kBytes;
+    EXPECT_EQ(after.series("tent_write_bytes_total{transport=\"rdma\"}") -
+                  before.series("tent_write_bytes_total{transport=\"rdma\"}"),
+              per_transport_bytes);
+    EXPECT_EQ(after.series("tent_write_bytes_total{transport=\"nvlink\"}") -
+                  before.series("tent_write_bytes_total{transport=\"nvlink\"}"),
+              per_transport_bytes);
+    EXPECT_EQ(after.series("tent_transport_attempts_total{transport=\"nvlink\","
+                           "operation=\"read\"}") -
+                  before.series("tent_transport_attempts_total{transport="
+                                "\"nvlink\",operation=\"read\"}"),
+              static_cast<double>(kThreads / 2) * (kIters / 2));
+    EXPECT_EQ(after.counter("tent_write_failures_total") -
+                  before.counter("tent_write_failures_total"),
+              0);
+    EXPECT_EQ(after.counter("tent_read_failures_total") -
+                  before.counter("tent_read_failures_total"),
+              0);
+}
+
+// Task failure with reason="submit": a synchronously rejected submit fails
+// the attempt at the submit site, so recordTaskCompletionMetrics sees
+// attempt_active == false. The counter must attribute the failure to the
+// attempt transport (rdma) even though task.type is UNSPEC by then — the
+// attribution leak the reason counter must not reproduce.
+TEST_F(MetricsRecordingTest, SubmitFailureRecordsTaskFailureWithSubmitReason) {
+    auto cfg = makeMetricsTestConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake = std::make_shared<FakeTransport>(RDMA, /*force_fail=*/false,
+                                                /*force_submit_fail=*/true);
+    installFakeRdma(engine, fake);
+
+    constexpr size_t kLen = 4096;
+    std::vector<uint8_t> buf(kLen, 0xCD);
+    auto before_register = MetricsSnapshot(TentMetrics::instance());
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kLen).ok());
+    auto after_register = MetricsSnapshot(TentMetrics::instance());
+    EXPECT_EQ(after_register.series(
+                  "tent_registered_buffer_bytes{transport=\"rdma\"}") -
+                  before_register.series(
+                      "tent_registered_buffer_bytes{transport=\"rdma\"}"),
+              static_cast<double>(kLen));
+
+    BatchID batch = engine.allocateBatch(4);
+    ASSERT_NE(batch, (BatchID)0);
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {makeLocalWrite(buf.data(), kLen)}).ok());
+    ASSERT_EQ(pollUntilTerminal(engine, batch, 0), TransferStatusEnum::FAILED);
+    auto after = MetricsSnapshot(TentMetrics::instance());
+
+    EXPECT_EQ(
+        after.series(
+            "tent_task_failures_total{transport=\"rdma\",reason=\"submit"
+            "\"}") -
+            before.series("tent_task_failures_total{transport=\"rdma\",reason="
+                          "\"submit\"}"),
+        1);
+    EXPECT_EQ(
+        after.series(
+            "tent_task_failures_total{transport=\"rdma\",reason=\"poll\"}") -
+            before.series(
+                "tent_task_failures_total{transport=\"rdma\",reason=\""
+                "poll\"}"),
+        0);
+    // In-flight gauge returns to zero after the terminal failure.
+    EXPECT_EQ(after.counter("tent_inflight_attempts") -
+                  before.counter("tent_inflight_attempts"),
+              0);
+
+    EXPECT_TRUE(engine.freeBatch(batch).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kLen).ok());
+    auto after_unregister = MetricsSnapshot(TentMetrics::instance());
+    EXPECT_EQ(after_unregister.series(
+                  "tent_registered_buffer_bytes{transport=\"rdma\"}"),
+              0);
+}
+
+// Task failure with reason="poll": the transport accepted the request and
+// reported FAILED from getTransferStatus, so the attempt is still active when
+// recordTaskCompletionMetrics runs.
+TEST_F(MetricsRecordingTest, PollFailureRecordsTaskFailureWithPollReason) {
+    auto cfg = makeMetricsTestConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake = std::make_shared<FakeTransport>(RDMA, /*force_fail=*/true,
+                                                /*force_submit_fail=*/false);
+    installFakeRdma(engine, fake);
+
+    constexpr size_t kLen = 4096;
+    std::vector<uint8_t> buf(kLen, 0xAB);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kLen).ok());
+
+    BatchID batch = engine.allocateBatch(4);
+    ASSERT_NE(batch, (BatchID)0);
+
+    auto before = MetricsSnapshot(TentMetrics::instance());
+    ASSERT_TRUE(
+        engine.submitTransfer(batch, {makeLocalWrite(buf.data(), kLen)}).ok());
+    ASSERT_EQ(pollUntilTerminal(engine, batch, 0), TransferStatusEnum::FAILED);
+    auto after = MetricsSnapshot(TentMetrics::instance());
+
+    EXPECT_EQ(
+        after.series(
+            "tent_task_failures_total{transport=\"rdma\",reason=\"poll\"}") -
+            before.series(
+                "tent_task_failures_total{transport=\"rdma\",reason=\""
+                "poll\"}"),
+        1);
+    EXPECT_EQ(
+        after.series(
+            "tent_task_failures_total{transport=\"rdma\",reason=\"submit"
+            "\"}") -
+            before.series("tent_task_failures_total{transport=\"rdma\",reason="
+                          "\"submit\"}"),
+        0);
+    EXPECT_EQ(after.counter("tent_inflight_attempts") -
+                  before.counter("tent_inflight_attempts"),
+              0);
+
+    EXPECT_TRUE(engine.freeBatch(batch).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kLen).ok());
+}
+
+// Gauges must stay symmetric across setEnabled() transitions: the runtime
+// switch governs statistical sampling, not state tracking. Skipping one half
+// of a paired add/sub would permanently corrupt the gauge (review feedback).
+TEST_F(MetricsRecordingTest, InflightGaugeSurvivesEnableToggle) {
+    auto& m = TentMetrics::instance();
+    auto before = MetricsSnapshot(m);
+
+    // Enabled at start, disabled before finish.
+    TentMetrics::setEnabled(true);
+    m.recordInflightAttemptStarted(RDMA);
+    TentMetrics::setEnabled(false);
+    m.recordInflightAttemptFinished(RDMA);
+
+    // Disabled at start, enabled before finish (reverse straddle).
+    m.recordInflightAttemptStarted(RDMA);
+    TentMetrics::setEnabled(true);
+    m.recordInflightAttemptFinished(RDMA);
+
+    auto after = MetricsSnapshot(m);
+    EXPECT_EQ(after.counter("tent_inflight_attempts") -
+                  before.counter("tent_inflight_attempts"),
+              0);
+    EXPECT_EQ(after.series("tent_inflight_attempts{transport=\"rdma\"}") -
+                  before.series("tent_inflight_attempts{transport=\"rdma\"}"),
+              0);
+}
+
+TEST_F(MetricsRecordingTest, RegisteredBytesGaugeSurvivesEnableToggle) {
+    auto& m = TentMetrics::instance();
+    auto before = MetricsSnapshot(m);
+
+    TentMetrics::setEnabled(true);
+    m.recordRegisteredBufferBytes(RDMA, 4096);
+    TentMetrics::setEnabled(false);
+    m.recordRegisteredBufferBytes(RDMA, -4096);
+    TentMetrics::setEnabled(true);
+
+    auto after = MetricsSnapshot(m);
+    EXPECT_EQ(after.counter("tent_registered_buffer_bytes") -
+                  before.counter("tent_registered_buffer_bytes"),
+              0);
+    EXPECT_EQ(
+        after.series("tent_registered_buffer_bytes{transport=\"rdma\"}") -
+            before.series("tent_registered_buffer_bytes{transport=\"rdma\"}"),
+        0);
+}
+
 // ---------------------------------------------------------------------------
 // L2 HTTP integration: scrape the real /metrics, /metrics/json, /health
 // endpoints via coro_http_client and assert on status + body. Validates the
diff --git a/mooncake-transfer-engine/tent/tests/mpcomm_boundary_test.cpp b/mooncake-transfer-engine/tent/tests/mpcomm_boundary_test.cpp
new file mode 100644
index 0000000000..57e72cfc09
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/mpcomm_boundary_test.cpp
@@ -0,0 +1,600 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+//
+// Hardware-free tests of the TENT side of the MPComm transport. Everything the
+// transport does to the provider goes through MpcommAdapter, so an injected
+// fake is enough to drive the boundary: endpoint publication and parsing,
+// single-flight connection, key-query retry, dynamic buffer refresh, the
+// request and completion mapping, short-transfer handling, releasing each
+// handle exactly once, and teardown.
+//
+// These need neither RDMA devices nor libmpcomm and therefore run in CI. What
+// they deliberately do not cover is MPComm's own behaviour - slicing, NIC and
+// QP selection, worker scheduling - which is the provider's responsibility and
+// is exercised by mpcomm_transport_test.cpp on real hardware.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <initializer_list>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "tent/transport/mpcomm/mpcomm_peer_registry.h"
+#include "tent/transport/mpcomm/mpcomm_task_mapping.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// Programmable stand-in for libmpcomm. Counts what the transport asked for and
+// can be told to fail a given number of times, which is how the recovery paths
+// are reached without a peer.
+class FakeMpcommAdapter final : public MpcommAdapter {
+   public:
+    bool available() const noexcept override { return true; }
+
+    Status init(const std::string &, const std::string &, int port) override {
+        bound_port = port;
+        return Status::OK();
+    }
+    int tcpPort() const override { return bound_port; }
+    Status startAcceptThread() override {
+        ++accept_thread_starts;
+        return Status::OK();
+    }
+    void stopAcceptThread() override { ++accept_thread_stops; }
+    void shutdown() override { ++shutdowns; }
+
+    Status registerMemory(void *, size_t) override { return Status::OK(); }
+    void unregisterMemory(void *) override {}
+    Status publishBuffer(void *, size_t, int) override { return Status::OK(); }
+    void unpublishBuffer(void *) override {}
+
+    Status connect(const std::string &host_id, const std::string &tcp_addr,
+                   int tcp_port) override {
+        {
+            std::lock_guard<std::mutex> lock(mutex);
+            ++connect_calls;
+            last_connect_host = host_id;
+            last_connect_addr = tcp_addr;
+            last_connect_port = tcp_port;
+        }
+        // Held open long enough that every thread in the single-flight test is
+        // inside ensure() while the first connect is still running.
+        if (connect_delay.count() > 0) {
+            std::this_thread::sleep_for(connect_delay);
+        }
+        if (connect_failures > 0) {
+            --connect_failures;
+            return Status::InternalError("injected connect failure");
+        }
+        return Status::OK();
+    }
+
+    Status queryRemoteBuffer(const std::string &host_id,
+                             const std::string &tcp_addr,
+                             int tcp_port) override {
+        std::lock_guard<std::mutex> lock(mutex);
+        ++query_calls;
+        last_query_host = host_id;
+        last_query_addr = tcp_addr;
+        last_query_port = tcp_port;
+        if (query_failures > 0) {
+            --query_failures;
+            return Status::InternalError("injected query failure");
+        }
+        return Status::OK();
+    }
+
+    MpcommTransferHandle putAsync(uintptr_t local_addr,
+                                  const std::string &host_id,
+                                  uintptr_t remote_addr,
+                                  size_t length) override {
+        ++put_calls;
+        return record(local_addr, host_id, remote_addr, length);
+    }
+    MpcommTransferHandle getAsync(uintptr_t local_addr,
+                                  const std::string &host_id,
+                                  uintptr_t remote_addr,
+                                  size_t length) override {
+        ++get_calls;
+        return record(local_addr, host_id, remote_addr, length);
+    }
+
+    bool isTransferComplete(MpcommTransferHandle) override {
+        return transfer_complete;
+    }
+    MpcommTransferOutcome getTransferResult(MpcommTransferHandle) override {
+        ++result_calls;
+        return outcome;
+    }
+    void releaseTransfer(MpcommTransferHandle handle) override {
+        ++release_calls;
+        last_released = handle;
+    }
+
+    // --- knobs ---
+    int connect_failures{0};
+    int query_failures{0};
+    std::chrono::milliseconds connect_delay{0};
+    bool issue_fails{false};
+    bool transfer_complete{true};
+    MpcommTransferOutcome outcome{};
+
+    // --- observations ---
+    mutable std::mutex mutex;
+    int connect_calls{0};
+    int query_calls{0};
+    int accept_thread_starts{0};
+    int accept_thread_stops{0};
+    int shutdowns{0};
+    int put_calls{0};
+    int get_calls{0};
+    int result_calls{0};
+    int release_calls{0};
+    int bound_port{0};
+    std::string last_connect_host;
+    std::string last_connect_addr;
+    int last_connect_port{0};
+    std::string last_query_host;
+    std::string last_query_addr;
+    int last_query_port{0};
+    uintptr_t last_local_addr{0};
+    uintptr_t last_remote_addr{0};
+    size_t last_length{0};
+    std::string last_transfer_host;
+    MpcommTransferHandle last_released{kInvalidMpcommTransferHandle};
+
+   private:
+    MpcommTransferHandle record(uintptr_t local_addr,
+                                const std::string &host_id,
+                                uintptr_t remote_addr, size_t length) {
+        last_local_addr = local_addr;
+        last_remote_addr = remote_addr;
+        last_length = length;
+        last_transfer_host = host_id;
+        if (issue_fails) return kInvalidMpcommTransferHandle;
+        return ++next_handle;
+    }
+
+    MpcommTransferHandle next_handle{0};
+};
+
+std::vector<MpcommBufferRange> makeRanges(
+    std::initializer_list<std::pair<uint64_t, uint64_t>> list) {
+    std::vector<MpcommBufferRange> out;
+    for (const auto &entry : list) {
+        out.push_back(MpcommBufferRange{entry.first, entry.second});
+    }
+    return out;
+}
+
+// MpcommTask::status_word is volatile, which cannot bind to the const
+// references gtest's matchers take, so read it out as a plain value first.
+TransferStatusEnum statusOf(const MpcommTask &task) { return task.status_word; }
+
+// ===================================================================
+// Endpoint publication and parsing
+// ===================================================================
+
+TEST(MpcommEndpointAttr, PublishedFormatRoundTripsThroughTheParser) {
+    // The published attribute is derived from the segment name, whose port is
+    // the tent RPC port and must not be mistaken for MPComm's.
+    auto attr = buildMpcommEndpointAttr("10.0.0.1:12345", 13579);
+    EXPECT_EQ(attr, "v1:10.0.0.1:13579");
+
+    std::string addr;
+    int port = 0;
+    ASSERT_TRUE(parseMpcommEndpointAttr(attr, addr, port).ok());
+    EXPECT_EQ(addr, "10.0.0.1");
+    EXPECT_EQ(port, 13579);
+}
+
+TEST(MpcommEndpointAttr, UnversionedAttributeIsReadAsV1) {
+    // Interoperability with a peer that predates the version prefix.
+    std::string addr;
+    int port = 0;
+    ASSERT_TRUE(parseMpcommEndpointAttr("10.0.0.1:13579", addr, port).ok());
+    EXPECT_EQ(addr, "10.0.0.1");
+    EXPECT_EQ(port, 13579);
+}
+
+TEST(MpcommEndpointAttr, UnknownVersionIsRejectedRatherThanMisparsed) {
+    std::string addr;
+    int port = 0;
+    EXPECT_FALSE(parseMpcommEndpointAttr("v2:10.0.0.1:13579", addr, port).ok());
+}
+
+TEST(MpcommEndpointAttr, HostnameStartingWithVIsNotTakenForAVersion) {
+    // The reason the prefix check requires 'v' + digits + ':' rather than just
+    // a leading 'v'.
+    std::string addr;
+    int port = 0;
+    ASSERT_TRUE(parseMpcommEndpointAttr("vm-node1:13579", addr, port).ok());
+    EXPECT_EQ(addr, "vm-node1");
+    EXPECT_EQ(port, 13579);
+
+    ASSERT_TRUE(parseMpcommEndpointAttr("v1:vm-node1:13579", addr, port).ok());
+    EXPECT_EQ(addr, "vm-node1");
+}
+
+TEST(MpcommEndpointAttr, Ipv6LiteralIsRejected) {
+    // MPComm's handshake sockets are AF_INET, and rfind(':') would otherwise
+    // split an IPv6 literal at the wrong colon.
+    std::string addr;
+    int port = 0;
+    EXPECT_FALSE(parseMpcommEndpointAttr("fe80::1:13579", addr, port).ok());
+    EXPECT_FALSE(parseMpcommEndpointAttr("v1:fe80::1:13579", addr, port).ok());
+}
+
+TEST(MpcommEndpointAttr, MalformedAttributesAreRejected) {
+    std::string addr;
+    int port = 0;
+    EXPECT_FALSE(parseMpcommEndpointAttr("", addr, port).ok());
+    EXPECT_FALSE(parseMpcommEndpointAttr("10.0.0.1", addr, port).ok());
+    EXPECT_FALSE(parseMpcommEndpointAttr(":13579", addr, port).ok());
+    EXPECT_FALSE(parseMpcommEndpointAttr("10.0.0.1:", addr, port).ok());
+}
+
+TEST(MpcommTcpPort, RejectsEverythingAtoiWouldAccept) {
+    // atoi() turns each of these into 0 or a truncated value, which MPComm
+    // would then try to bind.
+    int port = 0;
+    EXPECT_FALSE(parseMpcommTcpPort("", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("abc", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("13579x", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("0", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("-1", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("65536", port).ok());
+    EXPECT_FALSE(parseMpcommTcpPort("123456", port).ok());
+
+    ASSERT_TRUE(parseMpcommTcpPort("1", port).ok());
+    EXPECT_EQ(port, 1);
+    ASSERT_TRUE(parseMpcommTcpPort("65535", port).ok());
+    EXPECT_EQ(port, 65535);
+}
+
+// ===================================================================
+// Peer registry: single flight, retry, refresh, teardown
+// ===================================================================
+
+TEST(MpcommPeerRegistryTest, FirstEnsureConnectsThenQueries) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+
+    ASSERT_TRUE(
+        registry.ensure("peer", "10.0.0.1", 13579, makeRanges({{0x1000, 4096}}))
+            .ok());
+    EXPECT_EQ(adapter->connect_calls, 1);
+    EXPECT_EQ(adapter->query_calls, 1);
+    EXPECT_EQ(adapter->last_connect_addr, "10.0.0.1");
+    EXPECT_EQ(adapter->last_connect_port, 13579);
+
+    MpcommPeerState state{};
+    ASSERT_TRUE(registry.stateOf("peer", state));
+    EXPECT_EQ(state, MpcommPeerState::READY);
+}
+
+TEST(MpcommPeerRegistryTest, CachedPeerIsNotContactedAgain) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+
+    EXPECT_EQ(adapter->connect_calls, 1);
+    EXPECT_EQ(adapter->query_calls, 1);
+}
+
+TEST(MpcommPeerRegistryTest, ConcurrentCallersConnectThePeerOnce) {
+    // A second connect() to a connected host replaces MPComm's connection
+    // record wholesale, dropping its keys and leaking its queue pairs, so this
+    // is the property the whole ownership scheme exists to guarantee.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->connect_delay = std::chrono::milliseconds(100);
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    constexpr int kThreads = 8;
+    std::vector<std::thread> threads;
+    std::atomic<int> failures{0};
+    for (int i = 0; i < kThreads; ++i) {
+        threads.emplace_back([&] {
+            if (!registry.ensure("peer", "10.0.0.1", 13579, buffers).ok()) {
+                ++failures;
+            }
+        });
+    }
+    for (auto &thread : threads) thread.join();
+
+    EXPECT_EQ(failures.load(), 0);
+    EXPECT_EQ(adapter->connect_calls, 1);
+    EXPECT_EQ(adapter->query_calls, 1);
+    EXPECT_EQ(registry.size(), 1u);
+}
+
+TEST(MpcommPeerRegistryTest, ConnectFailureLeavesNothingCached) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->connect_failures = 1;
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    EXPECT_FALSE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    // Nothing was established, so the entry must not linger and block a later
+    // attempt from connecting.
+    EXPECT_FALSE(registry.contains("peer"));
+    EXPECT_EQ(adapter->query_calls, 0);
+
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    EXPECT_EQ(adapter->connect_calls, 2);
+}
+
+TEST(MpcommPeerRegistryTest, QueryFailureKeepsTheConnectionAndRetriesTheQuery) {
+    // The behaviour the CONNECTED_NO_KEYS state exists for: the connection
+    // cannot be closed, so a failed key query must not lead to a reconnect.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->query_failures = 1;
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    EXPECT_FALSE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    MpcommPeerState state{};
+    ASSERT_TRUE(registry.stateOf("peer", state));
+    EXPECT_EQ(state, MpcommPeerState::CONNECTED_NO_KEYS);
+
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    EXPECT_EQ(adapter->connect_calls, 1);  // not reconnected
+    EXPECT_EQ(adapter->query_calls, 2);    // query alone was retried
+    ASSERT_TRUE(registry.stateOf("peer", state));
+    EXPECT_EQ(state, MpcommPeerState::READY);
+}
+
+TEST(MpcommPeerRegistryTest, NewlyRegisteredRemoteBufferRefreshesKeys) {
+    // TENT allows a peer to register memory after a segment is opened, and the
+    // provider snapshots rkeys at query time, so the keys have to be refetched.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+
+    ASSERT_TRUE(
+        registry.ensure("peer", "10.0.0.1", 13579, makeRanges({{0x1000, 4096}}))
+            .ok());
+    ASSERT_EQ(adapter->query_calls, 1);
+
+    ASSERT_TRUE(registry
+                    .ensure("peer", "10.0.0.1", 13579,
+                            makeRanges({{0x1000, 4096}, {0x8000, 4096}}))
+                    .ok());
+    EXPECT_EQ(adapter->query_calls, 2);
+    EXPECT_EQ(adapter->connect_calls, 1);  // refreshed, not reconnected
+}
+
+TEST(MpcommPeerRegistryTest, UnregisteredRemoteBufferDoesNotRefreshKeys) {
+    // Keys for memory the peer no longer publishes are never used, and the
+    // decision has to stay monotonic: descriptors are cached per thread, so
+    // threads routinely observe smaller buffer sets than one another.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+
+    ASSERT_TRUE(registry
+                    .ensure("peer", "10.0.0.1", 13579,
+                            makeRanges({{0x1000, 4096}, {0x8000, 4096}}))
+                    .ok());
+    ASSERT_EQ(adapter->query_calls, 1);
+
+    ASSERT_TRUE(
+        registry.ensure("peer", "10.0.0.1", 13579, makeRanges({{0x1000, 4096}}))
+            .ok());
+    EXPECT_EQ(adapter->query_calls, 1);
+}
+
+TEST(MpcommPeerRegistryTest, RefreshQueriesTheConnectedEndpoint) {
+    // Keys must come from the process the connection was made to, not from
+    // whatever endpoint the peer advertises now.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+
+    ASSERT_TRUE(
+        registry.ensure("peer", "10.0.0.1", 13579, makeRanges({{0x1000, 4096}}))
+            .ok());
+    ASSERT_TRUE(registry
+                    .ensure("peer", "10.0.0.9", 20000,
+                            makeRanges({{0x1000, 4096}, {0x8000, 4096}}))
+                    .ok());
+
+    EXPECT_EQ(adapter->connect_calls, 1);
+    EXPECT_EQ(adapter->last_query_addr, "10.0.0.1");
+    EXPECT_EQ(adapter->last_query_port, 13579);
+}
+
+TEST(MpcommPeerRegistryTest, DistinctPeersAreConnectedIndependently) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    ASSERT_TRUE(registry.ensure("peer_a", "10.0.0.1", 13579, buffers).ok());
+    ASSERT_TRUE(registry.ensure("peer_b", "10.0.0.2", 13579, buffers).ok());
+
+    EXPECT_EQ(adapter->connect_calls, 2);
+    EXPECT_EQ(registry.size(), 2u);
+}
+
+TEST(MpcommPeerRegistryTest, ClearDropsEveryPeer) {
+    // uninstall() clears the cache after the provider has been shut down; a
+    // later install() must be able to connect again.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    MpcommPeerRegistry registry(adapter);
+    auto buffers = makeRanges({{0x1000, 4096}});
+
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    ASSERT_EQ(registry.size(), 1u);
+
+    registry.clear();
+    EXPECT_EQ(registry.size(), 0u);
+    EXPECT_FALSE(registry.contains("peer"));
+
+    ASSERT_TRUE(registry.ensure("peer", "10.0.0.1", 13579, buffers).ok());
+    EXPECT_EQ(adapter->connect_calls, 2);
+}
+
+// ===================================================================
+// Request and completion mapping
+// ===================================================================
+
+Request makeRequest(Request::OpCode opcode, size_t length) {
+    Request request{};
+    request.opcode = opcode;
+    request.source = reinterpret_cast<void *>(0x4000);
+    request.target_offset = 0x9000;
+    request.length = length;
+    return request;
+}
+
+TEST(MpcommTaskMapping, WriteBecomesPutAndReadBecomesGet) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+
+    auto write = makeRequest(Request::WRITE, 1024);
+    auto handle = issueMpcommTransfer(*adapter, write, "peer");
+    EXPECT_NE(handle, kInvalidMpcommTransferHandle);
+    EXPECT_EQ(adapter->put_calls, 1);
+    EXPECT_EQ(adapter->get_calls, 0);
+    EXPECT_EQ(adapter->last_local_addr, 0x4000u);
+    EXPECT_EQ(adapter->last_remote_addr, 0x9000u);
+    EXPECT_EQ(adapter->last_length, 1024u);
+    EXPECT_EQ(adapter->last_transfer_host, "peer");
+
+    auto read = makeRequest(Request::READ, 2048);
+    EXPECT_NE(issueMpcommTransfer(*adapter, read, "peer"),
+              kInvalidMpcommTransferHandle);
+    EXPECT_EQ(adapter->put_calls, 1);
+    EXPECT_EQ(adapter->get_calls, 1);
+    EXPECT_EQ(adapter->last_length, 2048u);
+}
+
+TEST(MpcommTaskMapping, RejectedIssueReportsAnInvalidHandle) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->issue_fails = true;
+    auto request = makeRequest(Request::WRITE, 1024);
+    EXPECT_EQ(issueMpcommTransfer(*adapter, request, "peer"),
+              kInvalidMpcommTransferHandle);
+}
+
+MpcommTask makeTask(size_t length, MpcommTransferHandle handle) {
+    MpcommTask task;
+    task.request = makeRequest(Request::WRITE, length);
+    task.status_word = TransferStatusEnum::PENDING;
+    task.mpcomm_handle = handle;
+    return task;
+}
+
+TEST(MpcommTaskMapping, FullTransferCompletesAndReportsItsBytes) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->outcome = MpcommTransferOutcome{true, 1024, 0};
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(task.transferred_bytes, 1024u);
+    EXPECT_EQ(task.mpcomm_handle, kInvalidMpcommTransferHandle);
+    EXPECT_EQ(adapter->release_calls, 1);
+}
+
+TEST(MpcommTaskMapping, ProviderFailureFailsTheTask) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->outcome = MpcommTransferOutcome{false, 0, -4};
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::FAILED);
+    EXPECT_EQ(adapter->release_calls, 1);
+}
+
+TEST(MpcommTaskMapping, SuccessfulButShortTransferIsDemotedToFailed) {
+    // The engine accumulates request.length for completed tasks, so a success
+    // that moved fewer bytes must not be reported as complete.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->outcome = MpcommTransferOutcome{true, 512, 0};
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::FAILED);
+    EXPECT_EQ(task.transferred_bytes, 512u);
+    EXPECT_EQ(adapter->release_calls, 1);
+}
+
+TEST(MpcommTaskMapping, ByteCountAboveRequestLengthStillCompletes) {
+    // The provider reports posted bytes, so a larger count is not an error;
+    // only a short one is.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->outcome = MpcommTransferOutcome{true, 2048, 0};
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::COMPLETED);
+}
+
+TEST(MpcommTaskMapping, IncompleteTransferIsLeftPendingAndNotReleased) {
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->transfer_complete = false;
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::PENDING);
+    EXPECT_EQ(task.mpcomm_handle, 7u);
+    EXPECT_EQ(adapter->release_calls, 0);
+}
+
+TEST(MpcommTaskMapping, HandleIsReleasedExactlyOnceAcrossRepeatedPolls) {
+    // getTransferStatus() may be called any number of times per task; a second
+    // release of the same handle would corrupt the provider's handle table.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    adapter->outcome = MpcommTransferOutcome{true, 1024, 0};
+    auto task = makeTask(1024, 7);
+
+    pollMpcommTask(*adapter, task);
+    pollMpcommTask(*adapter, task);
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(adapter->release_calls, 1);
+    EXPECT_EQ(adapter->result_calls, 1);
+    EXPECT_EQ(statusOf(task), TransferStatusEnum::COMPLETED);
+}
+
+TEST(MpcommTaskMapping, TaskWithoutHandleIsIgnored) {
+    // A task whose issue failed is already terminal and owns no handle.
+    auto adapter = std::make_shared<FakeMpcommAdapter>();
+    auto task = makeTask(1024, kInvalidMpcommTransferHandle);
+    task.status_word = TransferStatusEnum::FAILED;
+
+    pollMpcommTask(*adapter, task);
+
+    EXPECT_EQ(adapter->result_calls, 0);
+    EXPECT_EQ(adapter->release_calls, 0);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/mpcomm_transport_test.cpp b/mooncake-transfer-engine/tent/tests/mpcomm_transport_test.cpp
new file mode 100644
index 0000000000..45c99f0968
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/mpcomm_transport_test.cpp
@@ -0,0 +1,248 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Tests for MpcommTransport.
+//
+// TransportTypeMapping needs no hardware and always runs.
+//
+// WriteAndRead forks a target process and drives a WRITE followed by a READ
+// back over MPComm, verifying the payload. It requires RDMA devices and a
+// working MPComm installation, and is skipped when the engine cannot be
+// brought up. Parent and child use distinct MPCOMM_TCP_PORT values because
+// MPComm's metadata handshake listener would otherwise collide; the ports are
+// derived from the pid to keep concurrent runs apart, and are kept outside
+// 15000-17000 which CoroRpcAgent may pick at random for the tent RPC server.
+//
+// The target publishes its real segment name (host:port, assigned by the tent
+// RPC server) over a pipe, so no tent port has to be hardcoded here.
+
+#include <gtest/gtest.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <chrono>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/transfer_engine.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr size_t kDataLength = 4 * 1024 * 1024;
+constexpr size_t kPageSize = 4096;
+constexpr char kPattern = 'M';
+
+// Allocate page-aligned host memory directly instead of going through
+// TransferEngine::allocateLocalMemory(): that helper maps UNSPEC to RDMA or
+// TCP and fails outright when neither is enabled, and this test deliberately
+// leaves mpcomm as the only enabled transport.
+void* AllocAligned(size_t size) {
+    void* p = nullptr;
+    if (posix_memalign(&p, kPageSize, size) != 0) return nullptr;
+    return p;
+}
+
+std::shared_ptr<Config> makeConfig(const std::string& segment_name) {
+    auto conf = std::make_shared<Config>();
+    conf->set("metadata_type", "p2p");
+    conf->set("metadata_servers", "P2PHANDSHAKE");
+    conf->set("local_segment_name", segment_name);
+    // Enable mpcomm only: with every other transport disabled a routing
+    // regression fails the test instead of silently falling back to RDMA.
+    conf->set("transports/mpcomm/enable", true);
+    conf->set("transports/rdma/enable", false);
+    conf->set("transports/tcp/enable", false);
+    conf->set("transports/shm/enable", false);
+    conf->set("transports/nvlink/enable", false);
+    conf->set("transports/mnnvl/enable", false);
+    conf->set("transports/gds/enable", false);
+    conf->set("transports/io_uring/enable", false);
+    return conf;
+}
+
+void SetMpcommPort(int port) {
+    const std::string value = std::to_string(port);
+    setenv("MPCOMM_TCP_PORT", value.c_str(), 1);
+}
+
+void WaitBatchDone(TransferEngine* engine, BatchID batch_id) {
+    TransferStatus status;
+    for (int i = 0; i < 5000; ++i) {
+        auto s = engine->getTransferStatus(batch_id, status);
+        ASSERT_TRUE(s.ok()) << "getTransferStatus failed: " << s.ToString();
+        if (status.s == TransferStatusEnum::COMPLETED) return;
+        ASSERT_NE(status.s, TransferStatusEnum::FAILED);
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    FAIL() << "timeout waiting batch completion";
+}
+
+// Exercises the mpcomm-specific entries of the transport name mappings. A
+// missing entry would make policies naming "mpcomm" silently resolve to
+// UNSPEC, so keep this covered even though it needs no hardware.
+TEST(MpcommTransportTest, TransportTypeMapping) {
+    EXPECT_STREQ(transportTypeName(MPCOMM), "mpcomm");
+    EXPECT_EQ(parseTransportType("mpcomm"), MPCOMM);
+    EXPECT_LT(static_cast<int>(MPCOMM), kSupportedTransportTypes);
+}
+
+TEST(MpcommTransportTest, WriteAndRead) {
+    const int base_port = 23000 + static_cast<int>(getpid() % 1000);
+    const std::string target_name = "mpcomm_ut_target";
+
+    int ready_pipe[2];
+    int stop_pipe[2];
+    ASSERT_EQ(pipe(ready_pipe), 0);
+    ASSERT_EQ(pipe(stop_pipe), 0);
+
+    pid_t child = fork();
+    ASSERT_GE(child, 0);
+    if (child == 0) {
+        close(ready_pipe[0]);
+        close(stop_pipe[1]);
+        SetMpcommPort(base_port);
+        auto engine = std::make_unique<TransferEngine>(makeConfig(target_name));
+        if (!engine->available()) _exit(2);
+
+        void* buffer = AllocAligned(kDataLength);
+        if (buffer == nullptr) {
+            fprintf(stderr, "[target] posix_memalign failed\n");
+            _exit(3);
+        }
+        MemoryOptions options;
+        options.location = "cpu:0";
+        auto rs = engine->registerLocalMemory(buffer, kDataLength, options);
+        if (!rs.ok()) {
+            fprintf(stderr, "[target] registerLocalMemory failed: %s\n",
+                    rs.ToString().c_str());
+            _exit(4);
+        }
+
+        // The tent RPC port is assigned during construction, so the segment
+        // name is only final at this point.
+        const std::string segment = engine->getSegmentName();
+        const uint32_t len = static_cast<uint32_t>(segment.size());
+        if (write(ready_pipe[1], &len, sizeof(len)) != sizeof(len)) _exit(5);
+        if (write(ready_pipe[1], segment.data(), len) !=
+            static_cast<ssize_t>(len))
+            _exit(6);
+
+        char stop = 0;
+        (void)read(stop_pipe[0], &stop, 1);
+        (void)engine->unregisterLocalMemory(buffer, kDataLength);
+        free(buffer);
+        _exit(0);
+    }
+
+    close(ready_pipe[1]);
+    close(stop_pipe[0]);
+
+    uint32_t segment_len = 0;
+    const ssize_t got = read(ready_pipe[0], &segment_len, sizeof(segment_len));
+    if (got != static_cast<ssize_t>(sizeof(segment_len))) {
+        int wstatus = 0;
+        (void)waitpid(child, &wstatus, 0);
+        if (got == 0 && WIFEXITED(wstatus)) {
+            GTEST_SKIP() << "mpcomm target init failed, child exit="
+                         << WEXITSTATUS(wstatus)
+                         << " (2=engine unavailable, 3=alloc, 4=register;"
+                            " see [target] lines above for details)";
+        }
+        ASSERT_EQ(got, static_cast<ssize_t>(sizeof(segment_len)));
+    }
+    ASSERT_GT(segment_len, 0u);
+    std::string target_segment(segment_len, '\0');
+    ASSERT_EQ(read(ready_pipe[0], target_segment.data(), segment_len),
+              static_cast<ssize_t>(segment_len));
+
+    // Distinct handshake port: the target already listens on base_port.
+    SetMpcommPort(base_port + 1);
+    auto engine = std::make_unique<TransferEngine>(makeConfig("mpcomm_ut"));
+    ASSERT_TRUE(engine->available());
+
+    // Two halves: the first is written out, the second receives the read back.
+    void* buffer = AllocAligned(kDataLength * 2);
+    ASSERT_NE(buffer, nullptr);
+    MemoryOptions options;
+    options.location = "cpu:0";
+    auto s = engine->registerLocalMemory(buffer, kDataLength * 2, options);
+    ASSERT_TRUE(s.ok()) << s.ToString();
+
+    auto* bytes = static_cast<uint8_t*>(buffer);
+    memset(bytes, kPattern, kDataLength);
+    memset(bytes + kDataLength, 0, kDataLength);
+
+    SegmentID segment_id = 0;
+    for (int i = 0; i < 100; ++i) {
+        s = engine->openSegment(segment_id, target_segment);
+        if (s.ok()) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(s.ok()) << s.ToString();
+
+    SegmentInfo segment_info;
+    s = engine->getSegmentInfo(segment_id, segment_info);
+    ASSERT_TRUE(s.ok()) << s.ToString();
+    ASSERT_FALSE(segment_info.buffers.empty());
+    const uint64_t remote_base = segment_info.buffers[0].base;
+
+    BatchID batch = engine->allocateBatch(1);
+    Request request;
+    request.opcode = Request::WRITE;
+    request.length = kDataLength;
+    request.source = bytes;
+    request.target_id = segment_id;
+    request.target_offset = remote_base;
+    request.transport_hint = TransportType::MPCOMM;
+    s = engine->submitTransfer(batch, {request});
+    ASSERT_TRUE(s.ok()) << s.ToString();
+    WaitBatchDone(engine.get(), batch);
+    ASSERT_TRUE(engine->freeBatch(batch).ok());
+
+    batch = engine->allocateBatch(1);
+    request.opcode = Request::READ;
+    request.source = bytes + kDataLength;
+    s = engine->submitTransfer(batch, {request});
+    ASSERT_TRUE(s.ok()) << s.ToString();
+    WaitBatchDone(engine.get(), batch);
+    ASSERT_TRUE(engine->freeBatch(batch).ok());
+
+    for (size_t i = 0; i < kDataLength; ++i) {
+        ASSERT_EQ(bytes[kDataLength + i], kPattern) << "mismatch at " << i;
+    }
+
+    ASSERT_TRUE(engine->unregisterLocalMemory(buffer, kDataLength * 2).ok());
+    free(buffer);
+
+    const char stop = 'Q';
+    ASSERT_EQ(write(stop_pipe[1], &stop, 1), 1);
+    int wstatus = 0;
+    ASSERT_EQ(waitpid(child, &wstatus, 0), child);
+    ASSERT_TRUE(WIFEXITED(wstatus));
+    ASSERT_EQ(WEXITSTATUS(wstatus), 0);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/notification_fallback_test.cpp b/mooncake-transfer-engine/tent/tests/notification_fallback_test.cpp
new file mode 100644
index 0000000000..59ba1197f5
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/notification_fallback_test.cpp
@@ -0,0 +1,393 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// A notification the RDMA channel cannot carry - no endpoint could be
+// brought up, the peer has no notify QP, or the QP was disabled after a
+// fault - used to be dropped with an InternalError. These tests pin the
+// fallback: the engine tries the next notification transport and, with none
+// left, the control-plane RPC; receiveNotification() drains every transport
+// so a notification that arrived over RPC is not stranded in a queue nobody
+// polls. Stand-in transports keep this free of any NIC or metadata server.
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/transfer_engine_impl.h"
+
+namespace mooncake {
+namespace tent {
+
+namespace {
+
+std::shared_ptr<Config> makeConfig(bool rpc_fallback = true) {
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("rpc_server_hostname", "127.0.0.1");
+    config->set("rpc_server_port", "0");
+    config->set("log_level", "warning");
+    // No real transport: every notification transport in these tests is a
+    // stand-in swapped in after construction, so the fallback order and the
+    // RPC leg are exercised on their own.
+    config->set("transports/tcp/enable", false);
+    config->set("transports/shm/enable", false);
+    config->set("transports/rdma/enable", false);
+    config->set("transports/io_uring/enable", false);
+    config->set("transports/nvlink/enable", false);
+    config->set("transports/mnnvl/enable", false);
+    config->set("transports/gds/enable", false);
+    config->set("transports/ascend_direct/enable", false);
+    config->set("transports/sunrise_link/enable", false);
+    config->set("transports/mpcomm/enable", false);
+    config->set("transports/tpu/enable", false);
+    config->set("transports/ub/enable", false);
+    config->set("enable_progress_worker", false);
+    config->set("enable_runtime_queue", false);
+    config->set("notification/rpc_fallback", rpc_fallback);
+    return config;
+}
+
+// Stands in for a notification transport: sends answer with a fixed status
+// and are recorded, receives hand out whatever the test queued.
+class StubNotifyTransport : public Transport {
+   public:
+    StubNotifyTransport(const char* name, Status send_status)
+        : name_(name), send_status_(send_status) {}
+
+    Status install(std::string&, std::shared_ptr<ControlService>,
+                   std::shared_ptr<Topology>,
+                   std::shared_ptr<Config>) override {
+        return Status::OK();
+    }
+
+    bool supportNotification() const override { return true; }
+
+    Status sendNotification(SegmentID, const Notification& notifi) override {
+        ++send_calls;
+        sent.push_back(notifi);
+        return send_status_;
+    }
+
+    // Mirrors TcpTransport::receiveNotification(): the argument is cleared
+    // before the queue is swapped in. An engine that hands one vector to
+    // every transport in turn loses everything gathered before this one.
+    Status receiveNotification(std::vector<Notification>& out) override {
+        out.clear();
+        if (!recv_status.ok()) return recv_status;
+        out.swap(queued);
+        return Status::OK();
+    }
+
+    const char* getName() const override { return name_; }
+
+    int send_calls = 0;
+    std::vector<Notification> sent;
+    std::vector<Notification> queued;
+    Status recv_status = Status::OK();
+
+   private:
+    const char* name_;
+    Status send_status_;
+};
+
+Notification makeNotification(const std::string& msg) {
+    Notification notifi;
+    notifi.name = "notification-fallback-test";
+    notifi.msg = msg;
+    return notifi;
+}
+
+// Any non-local segment id. The stand-ins never look at it, and the tests
+// that use it stop before the RPC leg would need a real peer.
+constexpr SegmentID kRemote = 0x1234;
+
+std::shared_ptr<StubNotifyTransport> installStub(TransferEngineImpl& engine,
+                                                 TransportType slot,
+                                                 const char* name,
+                                                 Status send_status) {
+    auto stub = std::make_shared<StubNotifyTransport>(name, send_status);
+    std::string segment_name = engine.getSegmentName();
+    EXPECT_TRUE(stub->install(segment_name, nullptr, nullptr, nullptr).ok());
+    engine.swapTransportForTest(slot, stub);
+    return stub;
+}
+
+}  // namespace
+
+// The RDMA transport (slot RDMA, tried first) reports its channel
+// unavailable; the next notification transport carries the notification.
+// Both codes RdmaTransport::sendNotification() uses for "nothing was posted"
+// must be treated the same.
+TEST(NotificationFallbackTest, FallsBackToNextTransportWhenChannelUnavailable) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    const Status unavailable[] = {
+        Status::RdmaError("RDMA notification channel unavailable"),
+        Status::DeviceNotFound("RDMA notification endpoint unavailable"),
+    };
+    for (const auto& code : unavailable) {
+        auto rdma = installStub(engine, RDMA, "<rdma-unavailable>", code);
+        auto tcp = installStub(engine, TCP, "<tcp-ok>", Status::OK());
+
+        const Status status =
+            engine.sendNotification(kRemote, makeNotification("fallback"));
+        EXPECT_TRUE(status.ok()) << status.ToString();
+        EXPECT_EQ(rdma->send_calls, 1) << code.ToString();
+        ASSERT_EQ(tcp->send_calls, 1) << code.ToString();
+        EXPECT_EQ(tcp->sent[0].msg, "fallback");
+    }
+}
+
+// A transport that rejected the notification, as opposed to one that could
+// not carry it, is the caller's error to see: no other path is tried.
+TEST(NotificationFallbackTest, DoesNotFallBackOnInvalidArgument) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-rejects>",
+                            Status::InvalidArgument("payload too large"));
+    auto tcp = installStub(engine, TCP, "<tcp-ok>", Status::OK());
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("rejected"));
+    EXPECT_TRUE(status.IsInvalidArgument()) << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(tcp->send_calls, 0);
+}
+
+// The RDMA transport reports RpcServiceError when the bootstrap RPC to the
+// peer failed: its control plane is not answering, so neither the next
+// transport nor the engine's own RPC leg is tried - both would only wait
+// out another timeout against the same peer.
+TEST(NotificationFallbackTest, ControlPlaneUnreachableIsReturnedAsIs) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-bootstrap-rpc-failed>",
+                            Status::RpcServiceError("peer control plane "
+                                                    "unreachable"));
+    auto tcp = installStub(engine, TCP, "<tcp-ok>", Status::OK());
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("unreachable"));
+    EXPECT_TRUE(status.IsRpcServiceError()) << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(tcp->send_calls, 0);
+}
+
+// The production chain with TCP loaded is RDMA then TcpTransport, whose own
+// failures are RPC errors, never "channel unavailable". Such an error from
+// the last transport is returned as is; the engine's own RPC leg is not a
+// second attempt at the same peer.
+TEST(NotificationFallbackTest, ReturnsTheLastTransportsErrorInsteadOfRpc) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-unavailable>",
+                            Status::RdmaError("notify QP not connected"));
+    auto tcp = installStub(engine, TCP, "<tcp-rpc-fails>",
+                           Status::RpcServiceError("connection refused"));
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("tcp-failed"));
+    EXPECT_TRUE(status.IsRpcServiceError()) << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(tcp->send_calls, 1);
+}
+
+// Only when every loaded notification transport reports its channel
+// unavailable does the engine make the control-plane RPC itself. kRemote was
+// never opened, so reaching that leg shows up as the segment lookup failing
+// - which is how this test tells it apart from an early return.
+TEST(NotificationFallbackTest, AllTransportsUnavailableReachesTheRpcLeg) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-unavailable>",
+                            Status::RdmaError("notify QP not connected"));
+    auto tcp = installStub(engine, TCP, "<tcp-unavailable>",
+                           Status::DeviceNotFound("no endpoint"));
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("rpc-leg"));
+    EXPECT_TRUE(status.IsInvalidArgument()) << status.ToString();
+    EXPECT_NE(status.message().find("segment handle"), std::string::npos)
+        << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(tcp->send_calls, 1);
+}
+
+// SunriseLink advertises notification support but implements neither send
+// nor receive, so both come back NotImplemented. It must be skipped on the
+// send chain and ignored by the receive drain rather than stop the fallback
+// or turn every empty poll into an error.
+TEST(NotificationFallbackTest, SkipsTransportsThatDoNotImplementNotifications) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-unavailable>",
+                            Status::RdmaError("notify QP not connected"));
+    // Any slot between RDMA and TCP does; the real SunriseLink slot is after
+    // TCP, which would hide the send-chain part of this test.
+    auto stubbed = installStub(engine, SHM, "<advertised-only>",
+                               Status::NotImplemented("not implemented"));
+    stubbed->recv_status = Status::NotImplemented("not implemented");
+    auto tcp = installStub(engine, TCP, "<tcp-ok>", Status::OK());
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("skip"));
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(stubbed->send_calls, 1);
+    ASSERT_EQ(tcp->send_calls, 1);
+    EXPECT_EQ(tcp->sent[0].msg, "skip");
+
+    tcp->queued = {makeNotification("tcp-0")};
+    std::vector<Notification> received;
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), 1u);
+    EXPECT_EQ(received[0].msg, "tcp-0");
+
+    // An empty poll stays a successful empty poll.
+    EXPECT_TRUE(engine.receiveNotification(received).ok());
+    EXPECT_TRUE(received.empty());
+}
+
+// notification/rpc_fallback=false restores the first-transport-only
+// behavior: the unavailable channel's error is returned untouched.
+TEST(NotificationFallbackTest, FallbackCanBeDisabledByConfig) {
+    TransferEngineImpl engine(makeConfig(/*rpc_fallback=*/false));
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-unavailable>",
+                            Status::RdmaError("notify QP not connected"));
+    auto tcp = installStub(engine, TCP, "<tcp-ok>", Status::OK());
+
+    const Status status =
+        engine.sendNotification(kRemote, makeNotification("no-fallback"));
+    EXPECT_TRUE(status.IsRdmaError()) << status.ToString();
+    EXPECT_EQ(rdma->send_calls, 1);
+    EXPECT_EQ(tcp->send_calls, 0);
+}
+
+// One poll hands out what every notification transport queued plus the
+// in-process queue, in slot order, and each notification exactly once. The
+// second stand-in clears its argument the way TcpTransport does, so this
+// also pins that every transport is polled into its own vector.
+TEST(NotificationFallbackTest, ReceiveMergesAllNotificationTransports) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma>", Status::OK());
+    auto tcp = installStub(engine, TCP, "<tcp>", Status::OK());
+    rdma->queued = {makeNotification("rdma-0"), makeNotification("rdma-1")};
+    tcp->queued = {makeNotification("tcp-0"), makeNotification("tcp-1")};
+    ASSERT_TRUE(
+        engine.sendNotification(LOCAL_SEGMENT_ID, makeNotification("local"))
+            .ok());
+
+    std::vector<Notification> received;
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), 5u);
+    EXPECT_EQ(received[0].msg, "rdma-0");
+    EXPECT_EQ(received[1].msg, "rdma-1");
+    EXPECT_EQ(received[2].msg, "tcp-0");
+    EXPECT_EQ(received[3].msg, "tcp-1");
+    EXPECT_EQ(received[4].msg, "local");
+
+    // Drained: nothing comes back twice.
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    EXPECT_TRUE(received.empty());
+}
+
+// A transport whose queue cannot be read must not stop the drain: what the
+// other paths carried is still handed out, and the error only surfaces on a
+// poll that has nothing to deliver.
+TEST(NotificationFallbackTest, ReceiveKeepsDrainingPastAFailingTransport) {
+    TransferEngineImpl engine(makeConfig());
+    ASSERT_TRUE(engine.available());
+
+    auto rdma = installStub(engine, RDMA, "<rdma-broken>", Status::OK());
+    rdma->recv_status = Status::InternalError("notify CQ poll failed");
+    auto tcp = installStub(engine, TCP, "<tcp>", Status::OK());
+    tcp->queued = {makeNotification("tcp-0")};
+    ASSERT_TRUE(
+        engine.sendNotification(LOCAL_SEGMENT_ID, makeNotification("local"))
+            .ok());
+
+    std::vector<Notification> received;
+    ASSERT_TRUE(engine.receiveNotification(received).ok());
+    ASSERT_EQ(received.size(), 2u);
+    EXPECT_EQ(received[0].msg, "tcp-0");
+    EXPECT_EQ(received[1].msg, "local");
+
+    const Status empty = engine.receiveNotification(received);
+    EXPECT_TRUE(empty.IsInternalError()) << empty.ToString();
+    EXPECT_TRUE(received.empty());
+}
+
+// Two engines on loopback, neither with a TCP transport. The sender's only
+// notification transport reports its channel unavailable, so the engine
+// itself makes the control-plane RPC; the receiver, with nothing registered
+// to take RPC notifications, must still hand it out from its next poll.
+TEST(NotificationFallbackTest, RpcNotifyLandsWithoutTcpTransport) {
+    TransferEngineImpl receiver(makeConfig());
+    ASSERT_TRUE(receiver.available());
+    TransferEngineImpl sender(makeConfig());
+    ASSERT_TRUE(sender.available());
+
+    // The receiver has an RDMA transport that never delivers anything; the
+    // notification must not depend on it.
+    auto receiver_rdma =
+        installStub(receiver, RDMA, "<receiver-rdma>", Status::OK());
+    auto sender_rdma =
+        installStub(sender, RDMA, "<sender-rdma-unavailable>",
+                    Status::RdmaError("RDMA notification channel unavailable"));
+
+    SegmentID remote = ~0ull;
+    ASSERT_TRUE(sender.openSegment(remote, receiver.getSegmentName()).ok());
+    ASSERT_NE(remote, LOCAL_SEGMENT_ID);
+
+    const Status status =
+        sender.sendNotification(remote, makeNotification("over-rpc"));
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(sender_rdma->send_calls, 1);
+
+    // The RPC is synchronous, so the notification is queued by the time
+    // sendNotification() returns; the loop only guards against a scheduler
+    // hiccup between the reply and the poll.
+    std::vector<Notification> received;
+    for (int i = 0; i < 100 && received.empty(); ++i) {
+        (void)receiver.receiveNotification(received);
+        if (received.empty())
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+    ASSERT_EQ(received.size(), 1u);
+    EXPECT_EQ(received[0].name, "notification-fallback-test");
+    EXPECT_EQ(received[0].msg, "over-rpc");
+    EXPECT_TRUE(receiver_rdma->queued.empty());
+
+    // Delivered exactly once.
+    ASSERT_TRUE(receiver.receiveNotification(received).ok());
+    EXPECT_TRUE(received.empty());
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/nvlink_ipc_handle_sharing_test.cpp b/mooncake-transfer-engine/tent/tests/nvlink_ipc_handle_sharing_test.cpp
new file mode 100644
index 0000000000..769c03e44f
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/nvlink_ipc_handle_sharing_test.cpp
@@ -0,0 +1,112 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include <cuda.h>
+#include <cuda_runtime.h>
+
+#include "tent/common/config.h"
+#include "tent/common/utils/string_builder.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/segment.h"
+#include "tent/transport/nvlink/nvlink_transport.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// Regression test for the CUDA IPC handle-sharing bug: a caching allocator
+// (e.g. PyTorch) sub-allocates multiple logical buffers inside one cudaMalloc
+// segment. Registering the second buffer used to drop the segment's IPC
+// handle (empty shm_path) while still tagging the buffer NVLink-capable, so
+// cross-process NVLink submission for it failed. Every BufferDesc covering
+// the same cudaMalloc segment must receive the SAME serialized IPC handle.
+TEST(NVLinkIpcHandleSharingTest, TwoRangesInOneCudaMallocSegmentShareHandle) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count <= 0) {
+        GTEST_SKIP() << "No CUDA device available";
+    }
+
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    NVLinkTransport transport;
+    std::string local_segment_name = "nvlink_ipc_test_segment";
+    ASSERT_TRUE(transport
+                    .install(local_segment_name, metadata, nullptr,
+                             std::make_shared<Config>())
+                    .ok());
+
+    constexpr size_t kSegmentSize = 2 * 1024 * 1024;
+    void* base = nullptr;
+    ASSERT_EQ(cudaMalloc(&base, kSegmentSize), cudaSuccess);
+
+    // Two logical buffers sub-allocated inside the one cudaMalloc segment,
+    // as a caching allocator would produce.
+    MemoryOptions options;
+    BufferDesc first;
+    first.addr = reinterpret_cast<uint64_t>(base) + 4096;
+    first.length = 64 * 1024;
+    first.location = "cuda:0";
+    ASSERT_TRUE(transport.addMemoryBuffer(first, options).ok());
+
+    // Some environments back cudaMalloc with VMM allocations, which are not
+    // CUDA-IPC exportable and are skipped by design; nothing to test then.
+    if (first.shm_path.empty()) {
+        cudaFree(base);
+        transport.uninstall();
+        GTEST_SKIP() << "cudaMalloc allocation is VMM-backed; no IPC export";
+    }
+
+    BufferDesc second;
+    second.addr = reinterpret_cast<uint64_t>(base) + 1024 * 1024;
+    second.length = 128 * 1024;
+    second.location = "cuda:0";
+    ASSERT_TRUE(transport.addMemoryBuffer(second, options).ok());
+
+    // Both descs carry the same, non-empty serialized IPC handle.
+    EXPECT_FALSE(second.shm_path.empty());
+    EXPECT_EQ(first.shm_path, second.shm_path);
+
+    // Both are expanded to the full cudaMalloc segment.
+    EXPECT_EQ(first.addr, reinterpret_cast<uint64_t>(base));
+    EXPECT_EQ(second.addr, reinterpret_cast<uint64_t>(base));
+    EXPECT_EQ(first.length, kSegmentSize);
+    EXPECT_EQ(second.length, kSegmentSize);
+
+    // Both are tagged NVLink-capable.
+    EXPECT_NE(std::find(first.transports.begin(), first.transports.end(),
+                        TransportType::NVLINK),
+              first.transports.end());
+    EXPECT_NE(std::find(second.transports.begin(), second.transports.end(),
+                        TransportType::NVLINK),
+              second.transports.end());
+
+    // The shared handle equals a freshly exported one for the same segment.
+    cudaIpcMemHandle_t fresh;
+    ASSERT_EQ(cudaIpcGetMemHandle(&fresh, base), cudaSuccess);
+    EXPECT_EQ(first.shm_path,
+              serializeBinaryData(&fresh, sizeof(cudaIpcMemHandle_t)));
+
+    cudaFree(base);
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/nvlink_transport_test.cpp b/mooncake-transfer-engine/tent/tests/nvlink_transport_test.cpp
new file mode 100644
index 0000000000..67eee087d9
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/nvlink_transport_test.cpp
@@ -0,0 +1,311 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cerrno>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <cuda.h>
+#include <cuda_runtime.h>
+
+#include "tent/common/config.h"
+#include "tent/common/utils/string_builder.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/transport/nvlink/nvlink_transport.h"
+
+namespace mooncake {
+namespace tent {
+
+class NVLinkTransportTestPeer {
+   public:
+    static Status relocate(NVLinkTransport& transport, uint64_t& address,
+                           uint64_t length, SegmentID target_id) {
+        return transport.relocateSharedMemoryAddress(address, length,
+                                                     target_id);
+    }
+
+    static size_t mappingCount(NVLinkTransport& transport,
+                               SegmentID target_id) {
+        RWSpinlock::ReadGuard guard(transport.relocate_lock_);
+        auto it = transport.relocate_map_.find(target_id);
+        return it == transport.relocate_map_.end() ? 0 : it->second.size();
+    }
+};
+
+namespace {
+
+// A peer BufferDesc can carry a device ordinal that is invalid (or refers to
+// a different physical GPU) in the local process: ordinals are relative to
+// the PEER's CUDA_VISIBLE_DEVICES. Regression guard for the bug where
+// relocateSharedMemoryAddress switched to the peer ordinal before opening
+// the IPC handle.
+constexpr uint64_t kRemoteAddress = 0x10000000;
+constexpr size_t kBufferLength = 4096;
+constexpr uint32_t kPattern = 0x5a3c69e7;
+
+// CUDA IPC handles cannot be opened by the process that exported them, so
+// these tests obtain a handle from a forked child: the child allocates a
+// device buffer, fills it with a known pattern, exports the IPC handle and
+// stays alive (holding the allocation) until the parent is done.
+//
+// The parent must not call into CUDA before fork(): the child would inherit
+// the initialized runtime and its own CUDA calls would be unreliable. The
+// parent's first CUDA call therefore happens inside
+// relocateSharedMemoryAddress(), well after fork().
+class PeerExporter {
+   public:
+    PeerExporter() {
+        if (pipe(ready_pipe_) != 0 || pipe(stop_pipe_) != 0) return;
+
+        pid_t child = fork();
+        if (child < 0) return;
+        if (child == 0) {
+            // Child: allocate, fill, export, then block until the parent is
+            // done so the exported allocation stays alive.
+            close(ready_pipe_[0]);
+            close(stop_pipe_[1]);
+            _exit(childMain(ready_pipe_[1], stop_pipe_[0]));
+        }
+
+        close(ready_pipe_[1]);
+        close(stop_pipe_[0]);
+        child_pid_ = child;
+        valid_ = readExportResult();
+    }
+
+    ~PeerExporter() {
+        if (child_pid_ > 0) {
+            char done = 1;
+            (void)write(stop_pipe_[1], &done, sizeof(done));
+            (void)waitpid(child_pid_, nullptr, 0);
+        }
+        if (ready_pipe_[0] >= 0) close(ready_pipe_[0]);
+        if (stop_pipe_[1] >= 0) close(stop_pipe_[1]);
+    }
+
+    bool forkOk() const { return child_pid_ > 0; }
+    // 0 = handle exported fine; 1 = no CUDA device in the child.
+    int childStatus() const { return child_status_; }
+    const std::string& serializedHandle() const { return serialized_handle_; }
+
+   private:
+    static int childMain(int ready_fd, int stop_fd) {
+        int device_count = 0;
+        if (cudaGetDeviceCount(&device_count) != cudaSuccess ||
+            device_count <= 0) {
+            int32_t status = 1;
+            (void)write(ready_fd, &status, sizeof(status));
+            return 0;
+        }
+
+        void* ptr = nullptr;
+        if (cudaMalloc(&ptr, kBufferLength) != cudaSuccess) return 2;
+        std::vector<uint32_t> pattern(kBufferLength / sizeof(uint32_t),
+                                      kPattern);
+        if (cudaMemcpy(ptr, pattern.data(), kBufferLength,
+                       cudaMemcpyHostToDevice) != cudaSuccess)
+            return 3;
+        cudaIpcMemHandle_t handle;
+        if (cudaIpcGetMemHandle(&handle, ptr) != cudaSuccess) return 4;
+
+        int32_t status = 0;
+        size_t length = kBufferLength;
+        if (write(ready_fd, &status, sizeof(status)) != sizeof(status))
+            return 5;
+        if (write(ready_fd, &length, sizeof(length)) != sizeof(length))
+            return 6;
+        if (write(ready_fd, &handle, sizeof(handle)) != sizeof(handle))
+            return 7;
+
+        // Hold the allocation until the parent is done with the mapping.
+        char done = 0;
+        while (read(stop_fd, &done, sizeof(done)) < 0 && errno == EINTR) {
+        }
+        return 0;
+    }
+
+    bool readExportResult() {
+        int32_t status = -1;
+        if (read(ready_pipe_[0], &status, sizeof(status)) !=
+            (ssize_t)sizeof(status))
+            return false;
+        child_status_ = status;
+        if (status != 0) return true;  // no CUDA in child; skip, not fail
+
+        size_t length = 0;
+        cudaIpcMemHandle_t handle{};
+        if (read(ready_pipe_[0], &length, sizeof(length)) !=
+            (ssize_t)sizeof(length))
+            return false;
+        if (read(ready_pipe_[0], &handle, sizeof(handle)) !=
+            (ssize_t)sizeof(handle))
+            return false;
+        serialized_handle_ = serializeBinaryData(&handle, sizeof(handle));
+        return true;
+    }
+
+    int ready_pipe_[2]{-1, -1};
+    int stop_pipe_[2]{-1, -1};
+    pid_t child_pid_{-1};
+    int child_status_{-1};
+    std::string serialized_handle_;
+    bool valid_{false};
+
+   public:
+    bool valid() const { return valid_; }
+};
+
+Status installLocalSegmentWithIpcHandle(ControlService& metadata,
+                                        const std::string& serialized_handle,
+                                        const std::string& peer_location,
+                                        uint64_t remote_addr, size_t length) {
+    return metadata.segmentManager().updateLocal(
+        [&](SegmentDesc& segment) -> Status {
+            segment.name = "nvlink_test_segment";
+            segment.machine_id = "nvlink_test_machine";
+            segment.type = SegmentType::Memory;
+            auto& memory = std::get<MemorySegmentDesc>(segment.detail);
+            memory.buffers.clear();
+            BufferDesc buffer;
+            buffer.addr = remote_addr;
+            buffer.length = length;
+            buffer.location = peer_location;
+            buffer.shm_path = serialized_handle;
+            memory.buffers.push_back(std::move(buffer));
+            return Status::OK();
+        });
+}
+
+void verifyRelocatedData(uint64_t address, size_t length) {
+    ASSERT_LE(length, kBufferLength);
+    std::vector<uint32_t> readback(length / sizeof(uint32_t));
+    ASSERT_EQ(cudaMemcpy(readback.data(), reinterpret_cast<void*>(address),
+                         length, cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    for (uint32_t value : readback) {
+        EXPECT_EQ(value, kPattern);
+    }
+}
+
+}  // namespace
+
+TEST(NVLinkTransportTest, RelocateToleratesOutOfRangePeerDeviceOrdinal) {
+    PeerExporter exporter;
+    if (!exporter.forkOk() || !exporter.valid()) {
+        GTEST_SKIP() << "Peer export failed (fork/pipe error)";
+    }
+    if (exporter.childStatus() != 0) {
+        GTEST_SKIP() << "No CUDA device available";
+    }
+
+    // The peer claims its buffer lives on cuda:99 — an ordinal that is out
+    // of range in this process, exactly what a peer with a larger
+    // CUDA_VISIBLE_DEVICES produces.
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    ASSERT_TRUE(installLocalSegmentWithIpcHandle(
+                    *metadata, exporter.serializedHandle(), "cuda:99",
+                    kRemoteAddress, kBufferLength)
+                    .ok());
+
+    NVLinkTransport transport;
+    std::string local_segment_name = "nvlink_test_segment";
+    ASSERT_TRUE(transport
+                    .install(local_segment_name, metadata, nullptr,
+                             std::make_shared<Config>())
+                    .ok());
+
+    uint64_t dest_addr = kRemoteAddress + 64;
+    ASSERT_TRUE(NVLinkTransportTestPeer::relocate(
+                    transport, dest_addr, kBufferLength - 64, LOCAL_SEGMENT_ID)
+                    .ok());
+    EXPECT_EQ(
+        NVLinkTransportTestPeer::mappingCount(transport, LOCAL_SEGMENT_ID), 1u);
+    // The relocated address must alias the child's allocation: dest_addr is
+    // now mapped_base + 64.
+    verifyRelocatedData(dest_addr, kBufferLength - 64);
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+TEST(NVLinkTransportTest,
+     RelocateCachesSingleMappingForConcurrentPeersWithBogusOrdinal) {
+    PeerExporter exporter;
+    if (!exporter.forkOk() || !exporter.valid()) {
+        GTEST_SKIP() << "Peer export failed (fork/pipe error)";
+    }
+    if (exporter.childStatus() != 0) {
+        GTEST_SKIP() << "No CUDA device available";
+    }
+
+    int device_count = 0;
+    ASSERT_EQ(cudaGetDeviceCount(&device_count), cudaSuccess);
+    const std::string bogus_location =
+        "cuda:" + std::to_string(device_count + 8);
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    ASSERT_TRUE(installLocalSegmentWithIpcHandle(
+                    *metadata, exporter.serializedHandle(), bogus_location,
+                    kRemoteAddress, kBufferLength)
+                    .ok());
+
+    NVLinkTransport transport;
+    std::string local_segment_name = "nvlink_test_segment";
+    ASSERT_TRUE(transport
+                    .install(local_segment_name, metadata, nullptr,
+                             std::make_shared<Config>())
+                    .ok());
+
+    constexpr size_t kThreadCount = 8;
+    std::atomic<size_t> ready{0};
+    std::atomic<bool> start{false};
+    std::vector<uint64_t> relocated(kThreadCount, kRemoteAddress);
+    std::vector<uint8_t> succeeded(kThreadCount, 0);
+    std::vector<std::thread> threads;
+    threads.reserve(kThreadCount);
+    for (size_t i = 0; i < kThreadCount; ++i) {
+        threads.emplace_back([&, i] {
+            ready.fetch_add(1, std::memory_order_release);
+            while (!start.load(std::memory_order_acquire)) {
+                std::this_thread::yield();
+            }
+            succeeded[i] =
+                NVLinkTransportTestPeer::relocate(
+                    transport, relocated[i], kBufferLength, LOCAL_SEGMENT_ID)
+                    .ok();
+        });
+    }
+    while (ready.load(std::memory_order_acquire) != kThreadCount) {
+        std::this_thread::yield();
+    }
+    start.store(true, std::memory_order_release);
+    for (auto& thread : threads) thread.join();
+
+    for (uint8_t success : succeeded) EXPECT_TRUE(success);
+    for (uint64_t address : relocated) EXPECT_EQ(address, relocated.front());
+    EXPECT_EQ(
+        NVLinkTransportTestPeer::mappingCount(transport, LOCAL_SEGMENT_ID), 1u);
+    verifyRelocatedData(relocated.front(), kBufferLength);
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/poll_backoff_test.cpp b/mooncake-transfer-engine/tent/tests/poll_backoff_test.cpp
new file mode 100644
index 0000000000..5a2ec01c0d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/poll_backoff_test.cpp
@@ -0,0 +1,80 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Backoff policy for transferSync() / waitTransferCompletion().
+//
+// Both used to poll progressBatch() in a `while (true)` with no pause, and
+// progressBatch takes progress_mutex_ every time, so the spin contended with
+// every other thread's submit and poll path.
+//
+// The policy is a pure function so its shape can be pinned down without
+// standing up an engine or timing a sleep.
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdint>
+#include <limits>
+
+#include "tent/runtime/transfer_engine_impl.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr uint64_t kHotPolls = 128;
+constexpr auto kMaxDelay = std::chrono::microseconds(200);
+
+// Short transfers must not pay for the fix.
+TEST(PollBackoffTest, StaysHotForTheFirstPolls) {
+    for (uint64_t i = 0; i < kHotPolls; ++i) {
+        EXPECT_EQ(nextPollDelay(i).count(), 0) << "poll " << i;
+    }
+}
+
+TEST(PollBackoffTest, SleepsOnceHotPhaseEnds) {
+    EXPECT_EQ(nextPollDelay(kHotPolls), std::chrono::microseconds(1));
+    EXPECT_EQ(nextPollDelay(kHotPolls + 1), std::chrono::microseconds(2));
+    EXPECT_EQ(nextPollDelay(kHotPolls + 2), std::chrono::microseconds(4));
+}
+
+// The point of the change: a long transfer must stop hammering
+// progress_mutex_, so the delay has to grow.
+TEST(PollBackoffTest, DelayIsNonDecreasing) {
+    auto previous = nextPollDelay(0);
+    for (uint64_t i = 1; i < 4096; ++i) {
+        const auto current = nextPollDelay(i);
+        ASSERT_GE(current, previous) << "poll " << i;
+        previous = current;
+    }
+    EXPECT_GT(previous.count(), 0);
+}
+
+// A cap bounds completion latency; without one the backoff reaches seconds.
+TEST(PollBackoffTest, DelayIsCapped) {
+    for (uint64_t i = kHotPolls; i < 4096; ++i) {
+        ASSERT_LE(nextPollDelay(i), kMaxDelay) << "poll " << i;
+    }
+    EXPECT_EQ(nextPollDelay(4096), kMaxDelay);
+}
+
+// A loop that never terminates must not overflow the shift into a zero delay.
+TEST(PollBackoffTest, SaturatesInsteadOfOverflowing) {
+    EXPECT_EQ(nextPollDelay(std::numeric_limits<uint64_t>::max()), kMaxDelay);
+    EXPECT_EQ(nextPollDelay(uint64_t(1) << 62), kMaxDelay);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/progress_worker_test.cpp b/mooncake-transfer-engine/tent/tests/progress_worker_test.cpp
index f8da23c92e..d9f1b6eff0 100644
--- a/mooncake-transfer-engine/tent/tests/progress_worker_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/progress_worker_test.cpp
@@ -31,6 +31,7 @@
 #include <cstdint>
 #include <cstdlib>
 #include <functional>
+#include <future>
 #include <memory>
 #include <string>
 #include <thread>
@@ -39,13 +40,17 @@
 
 #include "tent/common/config.h"
 #include "tent/common/types.h"
+#include "tent/rpc/rpc.h"
 #include "tent/runtime/segment.h"
+#include "tent/runtime/proxy_manager.h"
 #include "tent/runtime/transfer_engine_impl.h"
 #include "tent/runtime/transport.h"
 #include "tent/transport/fault_proxy/fault_proxy_transport.h"
+#include "remote_stage_operation.h"
 
 namespace mooncake {
 namespace tent {
+
 namespace {
 
 // ---------------------------------------------------------------------------
@@ -188,6 +193,77 @@ class FakeTransport : public Transport {
     PollStatusFactory poll_status_factory_;
 };
 
+class DeferredCleanupProbeTransport : public FakeTransport {
+   public:
+    DeferredCleanupProbeTransport() : FakeTransport(TCP) {}
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request>& request_list) override {
+        const int attempt =
+            submit_attempts.fetch_add(1, std::memory_order_relaxed) + 1;
+        if (attempt == 2) {
+            return Status::InternalError(
+                "injected second staging submission failure" LOC_MARK);
+        }
+        return FakeTransport::submitTransferTasks(batch, request_list);
+    }
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        poll_attempts.fetch_add(1, std::memory_order_relaxed);
+        if (fail_polling.load(std::memory_order_acquire)) {
+            return Status::InternalError(
+                "injected deferred cleanup poll failure" LOC_MARK);
+        }
+
+        auto* fake_batch = static_cast<FakeSubBatch*>(batch);
+        if (task_id < 0 || task_id >= (int)fake_batch->requests.size()) {
+            return Status::InvalidArgument("bad task_id" LOC_MARK);
+        }
+        if (stay_pending.load(std::memory_order_acquire)) {
+            status.s = TransferStatusEnum::PENDING;
+            status.transferred_bytes = 0;
+        } else {
+            status.s = TransferStatusEnum::COMPLETED;
+            status.transferred_bytes = fake_batch->requests[task_id].length;
+        }
+        return Status::OK();
+    }
+
+    Status freeLocalMemory(void* addr, size_t size) override {
+        free_local_memory_calls.fetch_add(1, std::memory_order_relaxed);
+        if (stay_pending.load(std::memory_order_acquire)) {
+            free_local_memory_while_pending.fetch_add(
+                1, std::memory_order_relaxed);
+        }
+        return FakeTransport::freeLocalMemory(addr, size);
+    }
+
+    std::atomic<int> submit_attempts{0};
+    std::atomic<int> poll_attempts{0};
+    std::atomic<int> free_local_memory_calls{0};
+    std::atomic<int> free_local_memory_while_pending{0};
+    std::atomic<bool> stay_pending{true};
+    std::atomic<bool> fail_polling{false};
+};
+
+TransferStatus waitForStagingTerminal(ProxyManager& manager, TaskInfo& task) {
+    TransferStatus status;
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (std::chrono::steady_clock::now() < deadline) {
+        auto poll_status = manager.getStatus(&task, status);
+        if (!poll_status.ok()) {
+            ADD_FAILURE() << "getStatus failed: " << poll_status.ToString();
+            status.s = INVALID;
+            return status;
+        }
+        if (status.s != PENDING) return status;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return status;
+}
+
 std::shared_ptr<Config> makeMinimalP2PConfig() {
     auto cfg = std::make_shared<Config>();
     cfg->set("metadata_type", "p2p");
@@ -553,6 +629,1206 @@ TEST(ProgressWorker, EngineDestructorJoinsWorker) {
     SUCCEED();
 }
 
+TEST(ProxyManager, ConcurrentFirstAllocationIsBounded) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    ProxyManager manager(&engine, 4096, 4);
+    constexpr int kCallers = 8;
+    std::atomic<int> ready{0};
+    std::atomic<int> attempted{0};
+    std::atomic<int> successful{0};
+    std::atomic<int> exhausted{0};
+    std::atomic<int> unpin_failures{0};
+    std::atomic<bool> start{false};
+    std::vector<std::thread> callers;
+    callers.reserve(kCallers);
+
+    for (int i = 0; i < kCallers; ++i) {
+        callers.emplace_back([&] {
+            ready.fetch_add(1, std::memory_order_release);
+            while (!start.load(std::memory_order_acquire))
+                std::this_thread::yield();
+
+            uint64_t addr = 0;
+            auto status = manager.pinStageBuffer(kWildcardLocation, addr);
+            if (status.ok()) {
+                successful.fetch_add(1, std::memory_order_relaxed);
+            } else if (status.IsTooManyRequests()) {
+                exhausted.fetch_add(1, std::memory_order_relaxed);
+            }
+            attempted.fetch_add(1, std::memory_order_release);
+            while (attempted.load(std::memory_order_acquire) != kCallers)
+                std::this_thread::yield();
+            if (status.ok() && !manager.unpinStageBuffer(addr).ok())
+                unpin_failures.fetch_add(1, std::memory_order_relaxed);
+        });
+    }
+
+    while (ready.load(std::memory_order_acquire) != kCallers)
+        std::this_thread::yield();
+    start.store(true, std::memory_order_release);
+    for (auto& caller : callers) caller.join();
+
+    EXPECT_EQ(successful.load(), 4);
+    EXPECT_EQ(exhausted.load(), 4);
+    EXPECT_EQ(unpin_failures.load(), 0);
+}
+
+TEST(ProxyManager, ReclaimsStageBuffersBetweenWorkerTasks) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x21);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    {
+        ProxyManager manager(&engine, 64, 2);
+        Request request;
+        request.opcode = Request::WRITE;
+        request.source = source.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(target.data());
+        request.length = kBufferLength;
+        const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+        for (int i = 0; i < 8; ++i) {
+            TaskInfo task;
+            task.request = request;
+            task.staging = true;
+            Status submit_status;
+            std::thread submitter(
+                [&] { submit_status = manager.submit(&task, 0, params); });
+            submitter.join();
+            ASSERT_TRUE(submit_status.ok());
+
+            TransferStatus status;
+            const auto deadline =
+                std::chrono::steady_clock::now() + std::chrono::seconds(2);
+            while (std::chrono::steady_clock::now() < deadline) {
+                ASSERT_TRUE(manager.getStatus(&task, status).ok());
+                if (status.s != PENDING) break;
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            }
+            ASSERT_TRUE(manager.getStatus(&task, status).ok());
+            EXPECT_EQ(status.s, COMPLETED);
+        }
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+TEST(ProxyManager, DrainsInflightBatchesAfterProgressError) {
+    class FailOncePollTransport : public FakeTransport {
+       public:
+        explicit FailOncePollTransport(TransportType type)
+            : FakeTransport(type) {}
+
+        Status getTransferStatus(SubBatchRef batch, int task_id,
+                                 TransferStatus& status) override {
+            const int attempt =
+                poll_attempts.fetch_add(1, std::memory_order_relaxed) + 1;
+            if (attempt == 1) {
+                return Status::InternalError("injected poll failure" LOC_MARK);
+            }
+            return FakeTransport::getTransferStatus(batch, task_id, status);
+        }
+
+        std::atomic<int> poll_attempts{0};
+    };
+
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<FailOncePollTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x31);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    {
+        ProxyManager manager(&engine, 64, 2);
+        Request request;
+        request.opcode = Request::WRITE;
+        request.source = source.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(target.data());
+        request.length = kBufferLength;
+        const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+        TaskInfo task;
+        task.request = request;
+        task.staging = true;
+        ASSERT_TRUE(manager.submit(&task, 0, params).ok());
+
+        TransferStatus status;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(2);
+        while (std::chrono::steady_clock::now() < deadline) {
+            ASSERT_TRUE(manager.getStatus(&task, status).ok());
+            if (status.s != PENDING) break;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_TRUE(manager.getStatus(&task, status).ok());
+        EXPECT_EQ(status.s, FAILED);
+        EXPECT_GE(fake_tcp->poll_attempts.load(), 3);
+
+        uint64_t first = 0;
+        uint64_t second = 0;
+        uint64_t exhausted = 0;
+        ASSERT_TRUE(manager.pinStageBuffer(kWildcardLocation, first).ok());
+        ASSERT_TRUE(manager.pinStageBuffer(kWildcardLocation, second).ok());
+        EXPECT_TRUE(manager.pinStageBuffer(kWildcardLocation, exhausted)
+                        .IsTooManyRequests());
+        EXPECT_TRUE(manager.unpinStageBuffer(first).ok());
+        EXPECT_TRUE(manager.unpinStageBuffer(second).ok());
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+TEST(TransferEngineImpl, DirectSubmitRejectsBatchCapacityOverflow) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> buffer(kBufferLength, 0x41);
+    ASSERT_TRUE(engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+
+    BatchID batch = engine.allocateBatch(1);
+    ASSERT_NE(batch, (BatchID)0);
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = buffer.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(buffer.data());
+    request.length = buffer.size();
+
+    ASSERT_TRUE(engine.submitTransfer(batch, {request}).ok());
+    EXPECT_TRUE(engine.submitTransfer(batch, {request}).IsTooManyRequests());
+
+    EXPECT_TRUE(engine.waitTransferCompletion(batch).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+}
+
+TEST(ProxyManager, CleansUpDeferredStageBuffersWhenPendingBatchCompletes) {
+    class ControlledTransport : public FakeTransport {
+       public:
+        explicit ControlledTransport(TransportType type)
+            : FakeTransport(type) {}
+
+        Status submitTransferTasks(
+            SubBatchRef batch,
+            const std::vector<Request>& request_list) override {
+            int count =
+                submit_count.fetch_add(1, std::memory_order_relaxed) + 1;
+            if (count == 2) {
+                return Status::InternalError(
+                    "injected submit failure" LOC_MARK);
+            }
+            return FakeTransport::submitTransferTasks(batch, request_list);
+        }
+
+        Status getTransferStatus(SubBatchRef batch, int task_id,
+                                 TransferStatus& status) override {
+            if (stay_pending.load(std::memory_order_relaxed)) {
+                status.s = TransferStatusEnum::PENDING;
+                return Status::OK();
+            }
+            status.s = TransferStatusEnum::COMPLETED;
+            return Status::OK();
+        }
+
+        std::atomic<int> submit_count{0};
+        std::atomic<bool> stay_pending{true};
+    };
+
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<ControlledTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x51);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    {
+        ProxyManager manager(&engine, 64, 2);
+        Request request;
+        request.opcode = Request::WRITE;
+        request.source = source.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(target.data());
+        request.length = kBufferLength;
+        const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+        TaskInfo task1;
+        task1.request = request;
+        task1.staging = true;
+        ASSERT_TRUE(manager.submit(&task1, 0, params).ok());
+
+        TransferStatus status;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(2);
+        while (std::chrono::steady_clock::now() < deadline) {
+            ASSERT_TRUE(manager.getStatus(&task1, status).ok());
+            if (status.s != PENDING) break;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_TRUE(manager.getStatus(&task1, status).ok());
+        EXPECT_EQ(status.s, FAILED);
+
+        // While task1's batch is still PENDING, its stage buffer remains
+        // deferred and pinned.
+        uint64_t addr = 0;
+        EXPECT_TRUE(manager.pinStageBuffer(kWildcardLocation, addr)
+                        .IsTooManyRequests());
+
+        // Allow in-flight batches to complete.
+        fake_tcp->stay_pending.store(false, std::memory_order_relaxed);
+
+        // Submit task2 to trigger flushPendingCleanups() in worker thread.
+        TaskInfo task2;
+        task2.request = request;
+        task2.request.length =
+            64;  // 1 chunk so submitSubBatch count 3 succeeds
+        task2.staging = true;
+        ASSERT_TRUE(manager.submit(&task2, 0, params).ok());
+
+        const auto deadline2 =
+            std::chrono::steady_clock::now() + std::chrono::seconds(2);
+        while (std::chrono::steady_clock::now() < deadline2) {
+            ASSERT_TRUE(manager.getStatus(&task2, status).ok());
+            if (status.s != PENDING) break;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_TRUE(manager.getStatus(&task2, status).ok());
+
+        // Now deferred stage buffers from task1 have been reclaimed!
+        ASSERT_TRUE(manager.pinStageBuffer(kWildcardLocation, addr).ok());
+        EXPECT_TRUE(manager.unpinStageBuffer(addr).ok());
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+TEST(ProxyManager, RetainsBatchToPreventSlabReuseLeak) {
+    class ControlledTransport : public FakeTransport {
+       public:
+        explicit ControlledTransport(TransportType type)
+            : FakeTransport(type) {}
+
+        Status submitTransferTasks(
+            SubBatchRef batch,
+            const std::vector<Request>& request_list) override {
+            int count =
+                submit_count.fetch_add(1, std::memory_order_relaxed) + 1;
+            if (count == 2) {
+                return Status::InternalError(
+                    "injected submit failure" LOC_MARK);
+            }
+            return FakeTransport::submitTransferTasks(batch, request_list);
+        }
+
+        Status getTransferStatus(SubBatchRef batch, int task_id,
+                                 TransferStatus& status) override {
+            if (stay_pending.load(std::memory_order_relaxed)) {
+                status.s = TransferStatusEnum::PENDING;
+                return Status::OK();
+            }
+            status.s = TransferStatusEnum::COMPLETED;
+            return Status::OK();
+        }
+
+        std::atomic<int> submit_count{0};
+        std::atomic<bool> stay_pending{true};
+    };
+
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<ControlledTransport>(TCP);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x61);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    {
+        ProxyManager manager(&engine, 64, 2);
+        Request request;
+        request.opcode = Request::WRITE;
+        request.source = source.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(target.data());
+        request.length = kBufferLength;
+        const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+        TaskInfo task1;
+        task1.request = request;
+        task1.staging = true;
+        ASSERT_TRUE(manager.submit(&task1, 0, params).ok());
+
+        TransferStatus status;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(2);
+        while (std::chrono::steady_clock::now() < deadline) {
+            ASSERT_TRUE(manager.getStatus(&task1, status).ok());
+            if (status.s != PENDING) break;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_TRUE(manager.getStatus(&task1, status).ok());
+        EXPECT_EQ(status.s, FAILED);
+
+        // Allow task1 in-flight batch to finish on transport
+        fake_tcp->stay_pending.store(false, std::memory_order_relaxed);
+
+        // Attempting to allocate a new batch should not collide with retained
+        // batch
+        BatchID new_batch = engine.allocateBatch(1);
+        ASSERT_NE(new_batch, (BatchID)0);
+
+        // Submit task2 to trigger flushPendingCleanups()
+        TaskInfo task2;
+        task2.request = request;
+        task2.request.length = 64;
+        task2.staging = true;
+        ASSERT_TRUE(manager.submit(&task2, 0, params).ok());
+
+        const auto deadline2 =
+            std::chrono::steady_clock::now() + std::chrono::seconds(2);
+        while (std::chrono::steady_clock::now() < deadline2) {
+            ASSERT_TRUE(manager.getStatus(&task2, status).ok());
+            if (status.s != PENDING) break;
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+
+        // Verify task1 stage buffers were successfully reclaimed after retained
+        // batch completed
+        uint64_t addr = 0;
+        ASSERT_TRUE(manager.pinStageBuffer(kWildcardLocation, addr).ok());
+        EXPECT_TRUE(manager.unpinStageBuffer(addr).ok());
+
+        engine.freeBatch(new_batch);
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+TEST(ProxyManager, DeferredCleanupPollErrorKeepsStageBuffersPinned) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<DeferredCleanupProbeTransport>();
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x71);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    {
+        ProxyManager manager(&engine, 64, 2);
+        Request request;
+        request.opcode = Request::WRITE;
+        request.source = source.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(target.data());
+        request.length = kBufferLength;
+        const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+        TaskInfo task;
+        task.request = request;
+        task.staging = true;
+        ASSERT_TRUE(manager.submit(&task, 0, params).ok());
+        ASSERT_EQ(waitForStagingTerminal(manager, task).s, FAILED);
+
+        fake_tcp->fail_polling.store(true, std::memory_order_release);
+        uint64_t addr = 0;
+        auto pin_status = manager.pinStageBuffer(kWildcardLocation, addr);
+        EXPECT_TRUE(pin_status.IsTooManyRequests())
+            << "a polling error must not release an in-flight stage buffer: "
+            << pin_status.ToString();
+        if (pin_status.ok()) {
+            EXPECT_TRUE(manager.unpinStageBuffer(addr).ok());
+        }
+
+        fake_tcp->fail_polling.store(false, std::memory_order_release);
+        fake_tcp->stay_pending.store(false, std::memory_order_release);
+        ASSERT_TRUE(manager.pinStageBuffer(kWildcardLocation, addr).ok());
+        EXPECT_TRUE(manager.unpinStageBuffer(addr).ok());
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+TEST(ProxyManager, RemoteCleanupProbeDoesNotBlockOnPendingOperation) {
+    auto operation = std::make_shared<internal::RemoteStageOperation>();
+    std::vector<internal::RemoteStageOperationPtr> remote_operations = {
+        operation};
+
+    EXPECT_FALSE(internal::pollRemoteOperations(remote_operations));
+    ASSERT_EQ(remote_operations.size(), 1);
+
+    operation->complete(Status::OK(), true);
+    EXPECT_TRUE(internal::pollRemoteOperations(remote_operations));
+    EXPECT_TRUE(remote_operations.empty());
+}
+
+TEST(ProxyManager, UnconfirmedRemoteCompletionKeepsAbandonedBufferPinned) {
+    auto cleanup_calls = std::make_shared<std::atomic<int>>(0);
+    auto callback_done = std::make_shared<std::atomic<bool>>(false);
+    constexpr uint64_t kRemoteBuffer = 0x1234;
+
+    CoroRpcAgent stopped_server;
+    uint16_t port = 0;
+    ASSERT_TRUE(stopped_server.start(port).ok());
+    ASSERT_TRUE(stopped_server.stop().ok());
+    const std::string server_addr =
+        "127.0.0.1:" + std::to_string(static_cast<unsigned>(port));
+
+    auto operation = std::make_shared<internal::RemoteStageOperation>(
+        server_addr, kRemoteBuffer, [cleanup_calls] {
+            cleanup_calls->fetch_add(1, std::memory_order_relaxed);
+        });
+    operation->abandonForCleanup();
+
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = reinterpret_cast<void*>(kRemoteBuffer);
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = kRemoteBuffer;
+    request.length = 1;
+    ControlClient::delegateAsync(
+        server_addr, request,
+        [operation, callback_done](Status status, auto... completion_info) {
+            operation->complete(std::move(status), completion_info...);
+            callback_done->store(true, std::memory_order_release);
+        });
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!callback_done->load(std::memory_order_acquire) &&
+           std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    ASSERT_TRUE(callback_done->load(std::memory_order_acquire));
+    EXPECT_EQ(cleanup_calls->load(std::memory_order_acquire), 0);
+
+    std::vector<internal::RemoteStageOperationPtr> remote_operations = {
+        operation};
+    EXPECT_FALSE(internal::pollRemoteOperations(remote_operations));
+    EXPECT_EQ(remote_operations.size(), 1);
+}
+
+TEST(ProxyManager, LateRemoteCompletionReleasesAbandonedStageBuffer) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    std::string segment_name = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(segment_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 64;
+    std::vector<uint8_t> source(kBufferLength, 0x91);
+    std::vector<uint8_t> remote_stage(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(
+        engine.registerLocalMemory(remote_stage.data(), remote_stage.size())
+            .ok());
+
+    CoroRpcAgent remote_server;
+    std::atomic<bool> buffer_pinned{false};
+    std::atomic<bool> delegate_started{false};
+    std::atomic<bool> release_delegate{false};
+    std::atomic<int> unpin_calls{0};
+    const auto remote_stage_addr =
+        reinterpret_cast<uint64_t>(remote_stage.data());
+
+    ASSERT_TRUE(remote_server
+                    .registerFunction(
+                        Pin,
+                        [&](const std::string_view&, std::string& response) {
+                            bool expected = false;
+                            response = buffer_pinned.compare_exchange_strong(
+                                           expected, true)
+                                           ? std::to_string(remote_stage_addr)
+                                           : "0";
+                        })
+                    .ok());
+    ASSERT_TRUE(remote_server
+                    .registerFunction(
+                        Unpin,
+                        [&](const std::string_view&, std::string&) {
+                            buffer_pinned.store(false,
+                                                std::memory_order_release);
+                            unpin_calls.fetch_add(1, std::memory_order_relaxed);
+                        })
+                    .ok());
+    ASSERT_TRUE(
+        remote_server
+            .registerFunction(
+                Delegate,
+                [&](const std::string_view&, std::string&) {
+                    delegate_started.store(true, std::memory_order_release);
+                    while (!release_delegate.load(std::memory_order_acquire)) {
+                        std::this_thread::sleep_for(
+                            std::chrono::milliseconds(1));
+                    }
+                },
+                /*offload=*/true)
+            .ok());
+
+    uint16_t port = 0;
+    ASSERT_TRUE(remote_server.start(port).ok());
+    const std::string server_addr =
+        "127.0.0.1:" + std::to_string(static_cast<unsigned>(port));
+
+    auto manager = std::make_unique<ProxyManager>(&engine, kBufferLength, 1);
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = source.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = remote_stage_addr;
+    request.length = kBufferLength;
+    const std::vector<std::string> params = {server_addr, "", "remote"};
+
+    TaskInfo task;
+    task.request = request;
+    task.staging = true;
+    ASSERT_TRUE(manager->submit(&task, 0, params).ok());
+
+    const auto start_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (!delegate_started.load(std::memory_order_acquire) &&
+           std::chrono::steady_clock::now() < start_deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    if (!delegate_started.load(std::memory_order_acquire)) {
+        release_delegate.store(true, std::memory_order_release);
+        manager.reset();
+        FAIL() << "remote Delegate never started";
+        return;
+    }
+
+    manager.reset();
+    release_delegate.store(true, std::memory_order_release);
+
+    const auto cleanup_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (unpin_calls.load(std::memory_order_acquire) == 0 &&
+           std::chrono::steady_clock::now() < cleanup_deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    EXPECT_EQ(unpin_calls.load(std::memory_order_acquire), 1);
+
+    uint64_t repinned_addr = 0;
+    ASSERT_TRUE(
+        ControlClient::pinStageBuffer(server_addr, "remote", repinned_addr)
+            .ok());
+    EXPECT_EQ(repinned_addr, remote_stage_addr);
+    if (repinned_addr != 0) {
+        EXPECT_TRUE(
+            ControlClient::unpinStageBuffer(server_addr, repinned_addr).ok());
+    }
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(remote_stage.data(), remote_stage.size())
+            .ok());
+}
+
+TEST(ProxyManager, DestructorWaitsForDeferredBatchBeforeFreeingStageMemory) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_tcp = std::make_shared<DeferredCleanupProbeTransport>();
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x81);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine.registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(target.data(), target.size()).ok());
+
+    auto manager = std::make_unique<ProxyManager>(&engine, 64, 2);
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = source.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(target.data());
+    request.length = kBufferLength;
+    const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+    TaskInfo task;
+    task.request = request;
+    task.staging = true;
+    ASSERT_TRUE(manager->submit(&task, 0, params).ok());
+    ASSERT_EQ(waitForStagingTerminal(*manager, task).s, FAILED);
+
+    std::atomic<bool> destroyed{false};
+    std::thread destroyer([&] {
+        manager.reset();
+        destroyed.store(true, std::memory_order_release);
+    });
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    EXPECT_FALSE(destroyed.load(std::memory_order_acquire));
+    EXPECT_EQ(fake_tcp->free_local_memory_calls.load(std::memory_order_acquire),
+              0);
+    EXPECT_EQ(fake_tcp->free_local_memory_while_pending.load(
+                  std::memory_order_acquire),
+              0);
+
+    fake_tcp->stay_pending.store(false, std::memory_order_release);
+    destroyer.join();
+    EXPECT_TRUE(destroyed.load(std::memory_order_acquire));
+    EXPECT_GT(fake_tcp->free_local_memory_calls.load(std::memory_order_acquire),
+              0);
+    EXPECT_EQ(fake_tcp->free_local_memory_while_pending.load(
+                  std::memory_order_acquire),
+              0);
+
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine.unregisterLocalMemory(target.data(), target.size()).ok());
+}
+
+// ---------------------------------------------------------------------------
+// lazyFreeBatch head-of-line blocking. freelist is insertion-ordered; a batch
+// whose poll fails permanently must not stop every batch behind it from being
+// reclaimed.
+// ---------------------------------------------------------------------------
+
+// Polls succeed except for requests whose source is `poison_source`, which
+// fail permanently. Also counts freeSubBatch so a test can see reclamation.
+class PoisonedPollTransport : public FakeTransport {
+   public:
+    explicit PoisonedPollTransport(TransportType type) : FakeTransport(type) {}
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        auto* fb = static_cast<FakeSubBatch*>(batch);
+        if (task_id >= 0 && task_id < (int)fb->requests.size() &&
+            fb->requests[task_id].source ==
+                poison_source.load(std::memory_order_acquire)) {
+            poisoned_polls.fetch_add(1, std::memory_order_relaxed);
+            return Status::InternalError(
+                "injected permanent poll failure" LOC_MARK);
+        }
+        return FakeTransport::getTransferStatus(batch, task_id, status);
+    }
+
+    Status freeSubBatch(SubBatchRef& batch) override {
+        free_sub_batch_calls.fetch_add(1, std::memory_order_relaxed);
+        return FakeTransport::freeSubBatch(batch);
+    }
+
+    std::atomic<const void*> poison_source{nullptr};
+    std::atomic<int> free_sub_batch_calls{0};
+    std::atomic<int> poisoned_polls{0};
+};
+
+TEST(BatchLifecycle, FreeListSweepSkipsAStuckBatchInsteadOfStopping) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<PoisonedPollTransport>(RDMA);
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_rdma->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, fake_rdma);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> stuck_buf(kBufLen, 0xA1);
+    std::vector<uint8_t> healthy_buf(kBufLen, 0xB2);
+    ASSERT_TRUE(engine.registerLocalMemory(stuck_buf.data(), kBufLen).ok());
+    ASSERT_TRUE(engine.registerLocalMemory(healthy_buf.data(), kBufLen).ok());
+
+    auto make_request = [&](std::vector<uint8_t>& buf) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = buf.data();
+        req.target_id = LOCAL_SEGMENT_ID;
+        req.target_offset = reinterpret_cast<uint64_t>(buf.data());
+        req.length = kBufLen;
+        return req;
+    };
+
+    // Batch A polls with a permanent error, so lazyFreeBatch can neither
+    // reclaim it nor decide it is still pending.
+    BatchID stuck = engine.allocateBatch(1);
+    ASSERT_NE(stuck, (BatchID)0);
+    ASSERT_TRUE(engine.submitTransfer(stuck, {make_request(stuck_buf)}).ok());
+    fake_rdma->poison_source.store(stuck_buf.data(), std::memory_order_release);
+
+    // Batch B completes normally.
+    BatchID healthy = engine.allocateBatch(1);
+    ASSERT_NE(healthy, (BatchID)0);
+    ASSERT_TRUE(
+        engine.submitTransfer(healthy, {make_request(healthy_buf)}).ok());
+    TransferStatus status{};
+    ASSERT_TRUE(engine.getTransferStatus(healthy, status).ok());
+    ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+
+    // A enters the freelist first and stays there; B lands behind it.
+    EXPECT_TRUE(engine.freeBatch(stuck).ok());
+    EXPECT_TRUE(engine.freeBatch(healthy).ok());
+
+    // B must be reclaimed even though A, ahead of it, cannot be: its SubBatch
+    // is returned to the transport and its handle is no longer alive.
+    EXPECT_EQ(fake_rdma->free_sub_batch_calls.load(std::memory_order_acquire),
+              1)
+        << "the healthy batch behind the stuck one was never reclaimed";
+    TransferStatus after_free{};
+    EXPECT_FALSE(engine.getTransferStatus(healthy, after_free).ok())
+        << "a reclaimed batch handle must not stay alive";
+
+    // Unpoison so the stuck batch drains at teardown.
+    fake_rdma->poison_source.store(nullptr, std::memory_order_release);
+    EXPECT_TRUE(engine.unregisterLocalMemory(stuck_buf.data(), kBufLen).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(healthy_buf.data(), kBufLen).ok());
+}
+
+// A batch whose reclaim fails on every pass must eventually be parked: after
+// kMaxReclaimAttempts (4096) consecutive failures the sweep stops polling and
+// warning about it, later frees are unaffected, and engine teardown still
+// reclaims it unconditionally.
+TEST(BatchLifecycle, PermanentlyStuckBatchIsQuarantinedNotRetriedForever) {
+    constexpr size_t kMaxReclaimAttempts = 4096;  // mirrors the impl constant
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> stuck_buf(kBufLen, 0xA1);
+    std::vector<uint8_t> late_buf(kBufLen, 0xB2);
+    auto fake_rdma = std::make_shared<PoisonedPollTransport>(RDMA);
+
+    {
+        auto cfg = makeMinimalP2PConfig();
+        TransferEngineImpl engine(cfg);
+        ASSERT_TRUE(engine.available());
+        std::string seg = engine.getSegmentName();
+        ASSERT_TRUE(fake_rdma->install(seg, nullptr, nullptr).ok());
+        engine.swapTransportForTest(RDMA, fake_rdma);
+        ASSERT_TRUE(engine.registerLocalMemory(stuck_buf.data(), kBufLen).ok());
+        ASSERT_TRUE(engine.registerLocalMemory(late_buf.data(), kBufLen).ok());
+
+        auto make_request = [&](std::vector<uint8_t>& buf) {
+            Request req;
+            req.opcode = Request::WRITE;
+            req.source = buf.data();
+            req.target_id = LOCAL_SEGMENT_ID;
+            req.target_offset = reinterpret_cast<uint64_t>(buf.data());
+            req.length = kBufLen;
+            return req;
+        };
+
+        BatchID stuck = engine.allocateBatch(1);
+        ASSERT_NE(stuck, (BatchID)0);
+        ASSERT_TRUE(
+            engine.submitTransfer(stuck, {make_request(stuck_buf)}).ok());
+        fake_rdma->poison_source.store(stuck_buf.data(),
+                                       std::memory_order_release);
+        ASSERT_TRUE(engine.freeBatch(stuck).ok());
+
+        // Drive sweeps past the quarantine threshold. Re-freeing an already
+        // free-requested batch runs one sweep per call and returns the sweep
+        // error while the batch is still being retried.
+        bool saw_error = false;
+        for (size_t i = 0; i + 1 < kMaxReclaimAttempts; ++i) {
+            saw_error |= !engine.freeBatch(stuck).ok();
+        }
+        EXPECT_TRUE(saw_error);
+
+        // Quarantined: further sweeps neither poll the batch nor report its
+        // error.
+        const int polls_at_quarantine =
+            fake_rdma->poisoned_polls.load(std::memory_order_acquire);
+        for (int i = 0; i < 100; ++i) {
+            EXPECT_TRUE(engine.freeBatch(stuck).ok());
+        }
+        EXPECT_EQ(fake_rdma->poisoned_polls.load(std::memory_order_acquire),
+                  polls_at_quarantine)
+            << "a quarantined batch must not be re-polled";
+
+        // Healthy batches are still reclaimed normally alongside it.
+        BatchID late = engine.allocateBatch(1);
+        ASSERT_NE(late, (BatchID)0);
+        ASSERT_TRUE(engine.submitTransfer(late, {make_request(late_buf)}).ok());
+        TransferStatus status{};
+        ASSERT_TRUE(engine.getTransferStatus(late, status).ok());
+        ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+        EXPECT_TRUE(engine.freeBatch(late).ok());
+        EXPECT_EQ(
+            fake_rdma->free_sub_batch_calls.load(std::memory_order_acquire), 1)
+            << "batches behind a quarantined one must still be reclaimed";
+    }  // engine teardown reclaims the quarantined batch unconditionally
+
+    EXPECT_EQ(fake_rdma->free_sub_batch_calls.load(std::memory_order_acquire),
+              2)
+        << "teardown must reclaim the quarantined batch";
+}
+
+void installFakeRdmaAndTcp(TransferEngineImpl& engine,
+                           const std::shared_ptr<FakeTransport>& fake_rdma,
+                           const std::shared_ptr<FakeTransport>& fake_tcp) {
+    std::string seg = engine.getSegmentName();
+    ASSERT_TRUE(fake_rdma->install(seg, nullptr, nullptr).ok());
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine.swapTransportForTest(RDMA, fake_rdma);
+    engine.swapTransportForTest(TCP, fake_tcp);
+}
+
+Request makeLocalWriteReq(uint8_t* ptr, size_t length) {
+    Request req;
+    req.opcode = Request::WRITE;
+    req.source = ptr;
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(ptr);
+    req.length = length;
+    return req;
+}
+
+template <typename Fn>
+void runOrAbortOnTimeout(Fn&& fn, std::chrono::milliseconds timeout,
+                         const char* what) {
+    std::promise<void> done;
+    auto fut = done.get_future();
+    std::thread worker([&] {
+        fn();
+        done.set_value();
+    });
+    if (fut.wait_for(timeout) != std::future_status::ready) {
+        worker.detach();
+        ADD_FAILURE() << what << " timed out (likely deadlock)";
+        std::_Exit(1);
+    }
+    worker.join();
+}
+
+// ---------------------------------------------------------------------------
+// Lock-sharding: independent batches poll concurrently; poll vs free of the
+// same batch is well-defined; runtime-queue path must not invert lock order.
+// ---------------------------------------------------------------------------
+
+TEST(ProgressLockShard, ConcurrentIndependentBatchPolls) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    constexpr int kThreads = 8;
+    constexpr int kIters = 50;
+    std::vector<uint8_t> buf(kBufLen * kThreads, 0x5A);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    std::atomic<int> failures{0};
+    runOrAbortOnTimeout(
+        [&] {
+            std::vector<std::thread> threads;
+            threads.reserve(kThreads);
+            for (int t = 0; t < kThreads; ++t) {
+                threads.emplace_back([&, t] {
+                    uint8_t* ptr = buf.data() + t * kBufLen;
+                    for (int i = 0; i < kIters; ++i) {
+                        BatchID batch_id = engine.allocateBatch(1);
+                        if (!batch_id) {
+                            ++failures;
+                            return;
+                        }
+                        if (!engine
+                                 .submitTransfer(batch_id, {makeLocalWriteReq(
+                                                               ptr, kBufLen)})
+                                 .ok()) {
+                            ++failures;
+                            (void)engine.freeBatch(batch_id);
+                            return;
+                        }
+                        TransferStatus status{};
+                        if (!engine.getTransferStatus(batch_id, status).ok() ||
+                            status.s != TransferStatusEnum::COMPLETED) {
+                            ++failures;
+                            (void)engine.freeBatch(batch_id);
+                            return;
+                        }
+                        if (!engine.freeBatch(batch_id).ok()) ++failures;
+                    }
+                });
+            }
+            for (auto& th : threads) th.join();
+        },
+        std::chrono::seconds(10), "ConcurrentIndependentBatchPolls");
+
+    EXPECT_EQ(failures.load(), 0);
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
+TEST(ProgressLockShard, PollRacesWithFreeSameBatch) {
+    auto cfg = makeMinimalP2PConfig();
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen, 0x11);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(1);
+    ASSERT_NE(batch_id, (BatchID)0);
+    ASSERT_TRUE(
+        engine
+            .submitTransfer(batch_id, {makeLocalWriteReq(buf.data(), kBufLen)})
+            .ok());
+
+    std::atomic<bool> stop{false};
+    std::atomic<int> invalid_after_free{0};
+    std::atomic<int> unexpected{0};
+    runOrAbortOnTimeout(
+        [&] {
+            std::thread poller([&] {
+                TransferStatus status{};
+                while (!stop.load(std::memory_order_acquire)) {
+                    auto st = engine.getTransferStatus(batch_id, status);
+                    if (st.ok()) continue;
+                    if (st.IsInvalidArgument()) {
+                        ++invalid_after_free;
+                        return;
+                    }
+                    ++unexpected;
+                    return;
+                }
+            });
+            std::this_thread::sleep_for(std::chrono::milliseconds(5));
+            EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+            stop.store(true, std::memory_order_release);
+            poller.join();
+        },
+        std::chrono::seconds(10), "PollRacesWithFreeSameBatch");
+
+    EXPECT_EQ(unexpected.load(), 0);
+    TransferStatus status{};
+    EXPECT_TRUE(engine.getTransferStatus(batch_id, status).IsInvalidArgument());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+TEST(ProgressLockShard, DeferredFreeRegistryReadRacesWithAllocation) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("enable_runtime_queue", false);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::atomic<bool> complete{false};
+    auto pending_poll = [&complete](const Request& request, int) {
+        if (complete.load(std::memory_order_acquire)) {
+            return TransferStatus{TransferStatusEnum::COMPLETED,
+                                  request.length};
+        }
+        return TransferStatus{TransferStatusEnum::PENDING, 0};
+    };
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, FakeTransport::StatusFactory{}, pending_poll);
+    auto fake_tcp = std::make_shared<FakeTransport>(
+        TCP, FakeTransport::StatusFactory{}, pending_poll);
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    constexpr int kPendingBatches = 8;
+    constexpr int kRounds = 512;
+    constexpr int kAllocatorThreads = 4;
+    std::vector<uint8_t> buf(kBufLen, 0x33);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    std::vector<BatchID> pending_batches;
+    pending_batches.reserve(kPendingBatches);
+    for (int i = 0; i < kPendingBatches; ++i) {
+        BatchID batch_id = engine.allocateBatch(1);
+        ASSERT_NE(batch_id, (BatchID)0);
+        ASSERT_TRUE(engine
+                        .submitTransfer(
+                            batch_id, {makeLocalWriteReq(buf.data(), kBufLen)})
+                        .ok());
+        pending_batches.push_back(batch_id);
+    }
+
+    std::atomic<bool> start{false};
+    std::atomic<bool> stop{false};
+    std::atomic<int> allocator_failures{0};
+    std::vector<std::thread> allocators;
+    allocators.reserve(kAllocatorThreads);
+    for (int i = 0; i < kAllocatorThreads; ++i) {
+        allocators.emplace_back([&] {
+            while (!start.load(std::memory_order_acquire))
+                std::this_thread::yield();
+            while (!stop.load(std::memory_order_acquire)) {
+                // Empty batches complete immediately, so this thread mutates
+                // the shard registry without growing the deferred freelist.
+                BatchID batch_id = engine.allocateBatch(0);
+                if (!batch_id) {
+                    ++allocator_failures;
+                    return;
+                }
+                if (!engine.freeBatch(batch_id).ok()) ++allocator_failures;
+            }
+        });
+    }
+    start.store(true, std::memory_order_release);
+
+    int free_failures = 0;
+    for (int round = 0; round < kRounds; ++round) {
+        for (BatchID batch_id : pending_batches) {
+            if (!engine.freeBatch(batch_id).ok()) ++free_failures;
+        }
+    }
+
+    stop.store(true, std::memory_order_release);
+    for (auto& allocator : allocators) allocator.join();
+
+    EXPECT_EQ(free_failures, 0);
+    EXPECT_EQ(allocator_failures.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(engine.aliveBatchCountForTest(), kPendingBatches);
+
+    // Let the deferred batches drain before the engine and registered memory
+    // are torn down.
+    complete.store(true, std::memory_order_release);
+    EXPECT_TRUE(engine.freeBatch(pending_batches.front()).ok());
+    EXPECT_EQ(engine.aliveBatchCountForTest(), 0);
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
+TEST(ProgressLockShard, RuntimeQueuePollAndFreeDoesNotDeadlock) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("enable_runtime_queue", true);
+    cfg->set("runtime_queue/max_outstanding_owners", 16UL);
+    cfg->set("runtime_queue/max_outstanding_bytes", 1UL << 20);
+    cfg->set("runtime_queue/max_dispatch_owners", 4UL);
+    cfg->set("runtime_queue/max_dispatch_bytes", 1UL << 20);
+    cfg->set("runtime_queue/staging_owner_reserve", 0UL);
+    cfg->set("runtime_queue/staging_byte_reserve", 0UL);
+    cfg->set("runtime_queue/progress_fallback_interval_us", 50000UL);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto pending_poll = [](const Request&, int) {
+        return TransferStatus{TransferStatusEnum::PENDING, 0};
+    };
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, FakeTransport::StatusFactory{}, pending_poll);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    constexpr int kBatches = 8;
+    std::vector<uint8_t> buf(kBufLen * kBatches, 0x22);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), buf.size()).ok());
+
+    std::vector<BatchID> batches;
+    batches.reserve(kBatches);
+    for (int i = 0; i < kBatches; ++i) {
+        BatchID batch_id = engine.allocateBatch(1);
+        ASSERT_NE(batch_id, (BatchID)0);
+        ASSERT_TRUE(engine
+                        .submitTransfer(batch_id,
+                                        {makeLocalWriteReq(
+                                            buf.data() + i * kBufLen, kBufLen)})
+                        .ok());
+        batches.push_back(batch_id);
+    }
+
+    runOrAbortOnTimeout(
+        [&] {
+            std::atomic<bool> stop{false};
+            std::vector<std::thread> pollers;
+            pollers.reserve(kBatches);
+            for (int i = 0; i < kBatches; ++i) {
+                pollers.emplace_back([&, i] {
+                    TransferStatus status{};
+                    while (!stop.load(std::memory_order_acquire)) {
+                        (void)engine.getTransferStatus(batches[i], status);
+                    }
+                });
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+            for (auto batch_id : batches) {
+                EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+            }
+            stop.store(true, std::memory_order_release);
+            for (auto& th : pollers) th.join();
+        },
+        std::chrono::seconds(10), "RuntimeQueuePollAndFreeDoesNotDeadlock");
+
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), buf.size()).ok());
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/promotion_policy_test.cpp b/mooncake-transfer-engine/tent/tests/promotion_policy_test.cpp
index ab49faef73..7739d8a858 100644
--- a/mooncake-transfer-engine/tent/tests/promotion_policy_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/promotion_policy_test.cpp
@@ -12,10 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
-// Deterministic reproduction of the promotion issues reported in #2528. The
-// historical head-only policy is contrasted with a per-entry policy on the same
-// inputs so the unintended behavior is unambiguous and re-runnable (no RDMA
-// stack, no timing noise).
+// Pins both promotion policies used by Workers::promoteTimedOutRequests
+// (issue #2528). Head-only is the default; per-entry is opt-in via
+// transports/rdma/priority_promotion_per_entry. Contrasted on the same inputs
+// so the default "flush the tier" behavior stays unambiguous (no RDMA stack,
+// no timing noise).
 
 #include "tent/transport/rdma/promotion_policy.h"
 
@@ -44,7 +45,7 @@ TEST(PromotionPolicyTest, HeadOnlyPromotesFreshEntriesWhenHeadTimedOut) {
 
     auto d = DecidePromotionHeadOnly(q, kNow, kTimeout);
 
-    // BUG: all three are promoted, including the two fresh (non-starving) ones.
+    // Default policy: all three are promoted, including the two fresh ones.
     EXPECT_EQ(d.promote_indices, (std::vector<size_t>{0, 1, 2}));
 
     // The per-entry policy promotes only the genuinely starving head.
@@ -58,7 +59,7 @@ TEST(PromotionPolicyTest, HeadOnlyMissesTimedOutTailWhenHeadFresh) {
 
     auto d = DecidePromotionHeadOnly(q, kNow, kTimeout);
 
-    // BUG: nothing is promoted even though indices 1 and 2 are starving.
+    // Default policy: nothing is promoted even though indices 1 and 2 starve.
     EXPECT_TRUE(d.promote_indices.empty());
 
     auto fixed = DecidePromotionPerEntry(q, kNow, kTimeout);
@@ -86,7 +87,7 @@ TEST(PromotionPolicyTest, ZeroTimestampNeverTimesOut) {
 
 TEST(PromotionPolicyTest, AllTimedOutPromotesAllUnderBothPolicies) {
     // When every entry is starving the two policies agree — this is the case
-    // the historical policy was designed around.
+    // the default head-only policy was designed around.
     std::vector<uint64_t> q = {timedOut(), timedOut(), timedOut()};
     EXPECT_EQ(DecidePromotionHeadOnly(q, kNow, kTimeout).promote_indices,
               (std::vector<size_t>{0, 1, 2}));
diff --git a/mooncake-transfer-engine/tent/tests/proxy_shutdown_timeout_test.cpp b/mooncake-transfer-engine/tent/tests/proxy_shutdown_timeout_test.cpp
new file mode 100644
index 0000000000..47607287bb
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/proxy_shutdown_timeout_test.cpp
@@ -0,0 +1,244 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+//
+// Regression test for PR #3526: ProxyManager::deconstruct() bounds its drain
+// loop with a deadline, and a timed-out drain must not free resources the
+// transport workers can still touch. With a transport whose transfers never
+// leave PENDING, the destructor has to (a) return once the configured
+// deadline expires instead of spinning forever, and (b) hand the undrained
+// batches and their local stage buffer arenas to TransferEngineImpl for
+// deferred teardown instead of releasing them while a worker could still
+// write slice status into them. Runs on plain CPU; no RDMA device required.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <cstdlib>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/segment.h"
+#include "tent/runtime/proxy_manager.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/runtime/transport.h"
+
+namespace mooncake {
+namespace tent {
+
+namespace {
+
+// Minimal shape borrowed from progress_worker_test.cpp, reduced to the one
+// behavior this test needs: every submitted task stays PENDING forever, so
+// the shutdown drain loop can only leave through its deadline.
+class NeverCompletingSubBatch : public Transport::SubBatch {
+   public:
+    size_t size() const override { return task_count; }
+    size_t task_count = 0;
+    std::vector<Request> requests;
+};
+
+class NeverCompletingTransport : public Transport {
+   public:
+    NeverCompletingTransport() { caps.dram_to_dram = true; }
+
+    std::atomic<int> submit_calls{0};
+    std::atomic<int> free_local_memory_calls{0};
+
+    Status install(std::string& /*local_segment_name*/,
+                   std::shared_ptr<ControlService> /*metadata*/,
+                   std::shared_ptr<Topology> /*local_topology*/,
+                   std::shared_ptr<Config> /*conf*/ = nullptr) override {
+        return Status::OK();
+    }
+
+    Status allocateSubBatch(SubBatchRef& batch, size_t /*max_size*/) override {
+        batch = new NeverCompletingSubBatch();
+        return Status::OK();
+    }
+
+    Status freeSubBatch(SubBatchRef& batch) override {
+        delete batch;
+        batch = nullptr;
+        return Status::OK();
+    }
+
+    Status submitTransferTasks(
+        SubBatchRef batch, const std::vector<Request>& request_list) override {
+        ++submit_calls;
+        auto* fb = static_cast<NeverCompletingSubBatch*>(batch);
+        for (const auto& req : request_list) {
+            fb->requests.push_back(req);
+            fb->task_count++;
+        }
+        return Status::OK();
+    }
+
+    Status getTransferStatus(SubBatchRef batch, int task_id,
+                             TransferStatus& status) override {
+        auto* fb = static_cast<NeverCompletingSubBatch*>(batch);
+        if (task_id < 0 || task_id >= (int)fb->requests.size()) {
+            return Status::InvalidArgument("bad task_id" LOC_MARK);
+        }
+        status.s = TransferStatusEnum::PENDING;
+        status.transferred_bytes = 0;
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(BufferDesc& desc,
+                           const MemoryOptions& /*options*/) override {
+        desc.transports.push_back(TCP);
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override {
+        for (auto& d : desc_list) {
+            auto s = addMemoryBuffer(d, options);
+            if (!s.ok()) return s;
+        }
+        return Status::OK();
+    }
+
+    Status removeMemoryBuffer(BufferDesc& /*desc*/) override {
+        return Status::OK();
+    }
+
+    Status allocateLocalMemory(void** addr, size_t size,
+                               MemoryOptions& /*options*/) override {
+        *addr = std::malloc(size);
+        if (!*addr) return Status::InternalError("malloc failed" LOC_MARK);
+        return Status::OK();
+    }
+
+    Status freeLocalMemory(void* addr, size_t /*size*/) override {
+        ++free_local_memory_calls;
+        std::free(addr);
+        return Status::OK();
+    }
+
+    bool warmupMemory(void* /*addr*/, size_t /*length*/) override {
+        return false;
+    }
+
+    const char* getName() const override { return "<never-completing>"; }
+};
+
+std::shared_ptr<Config> makeMinimalP2PConfig() {
+    auto cfg = std::make_shared<Config>();
+    cfg->set("metadata_type", "p2p");
+    cfg->set("metadata_servers", "");
+    cfg->set("rpc_server_hostname", "127.0.0.1");
+    cfg->set("rpc_server_port", "0");
+    cfg->set("log_level", "warning");
+    cfg->set("merge_requests", false);
+
+    cfg->set("transports/tcp/enable", false);
+    cfg->set("transports/shm/enable", false);
+    cfg->set("transports/rdma/enable", false);
+    cfg->set("transports/io_uring/enable", false);
+    cfg->set("transports/nvlink/enable", false);
+    cfg->set("transports/mnnvl/enable", false);
+    cfg->set("transports/gds/enable", false);
+    cfg->set("transports/ascend_direct/enable", false);
+
+    cfg->set("max_failover_attempts", 3);
+    return cfg;
+}
+
+TEST(ProxyShutdownTimeout, TimedOutDrainHandsResourcesToDeferredTeardown) {
+    constexpr long kDrainTimeoutMs = 200;
+
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("staging/shutdown_drain_timeout_ms", kDrainTimeoutMs);
+    auto engine = std::make_unique<TransferEngineImpl>(cfg);
+    ASSERT_TRUE(engine->available());
+
+    auto fake_tcp = std::make_shared<NeverCompletingTransport>();
+    std::string seg = engine->getSegmentName();
+    ASSERT_TRUE(fake_tcp->install(seg, nullptr, nullptr).ok());
+    engine->swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufferLength = 128;
+    std::vector<uint8_t> source(kBufferLength, 0x91);
+    std::vector<uint8_t> target(kBufferLength, 0x00);
+    ASSERT_TRUE(engine->registerLocalMemory(source.data(), source.size()).ok());
+    ASSERT_TRUE(engine->registerLocalMemory(target.data(), target.size()).ok());
+
+    // 64-byte chunks over a 128-byte request: two chunks, each with its own
+    // local-stage batch that will never leave PENDING.
+    auto manager = std::make_unique<ProxyManager>(engine.get(), 64, 2);
+    Request request;
+    request.opcode = Request::WRITE;
+    request.source = source.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(target.data());
+    request.length = kBufferLength;
+    const std::vector<std::string> params = {"", kWildcardLocation, ""};
+
+    TaskInfo task;
+    task.request = request;
+    task.staging = true;
+    ASSERT_TRUE(manager->submit(&task, 0, params).ok());
+
+    // Both chunk batches must be in flight before shutdown, otherwise the
+    // drain loop has nothing to time out on.
+    const auto submit_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (fake_tcp->submit_calls.load(std::memory_order_acquire) < 2 &&
+           std::chrono::steady_clock::now() < submit_deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    ASSERT_GE(fake_tcp->submit_calls.load(std::memory_order_acquire), 2);
+
+    // The destructor must come back once the configured deadline expires:
+    // well past kDrainTimeoutMs, but nowhere near the 30s default (let alone
+    // the unbounded wait this regression test guards against).
+    const auto destroy_start = std::chrono::steady_clock::now();
+    manager.reset();
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - destroy_start);
+    EXPECT_GE(elapsed.count(), kDrainTimeoutMs / 2);
+    EXPECT_LT(elapsed.count(), 10000);
+
+    // The ownership-transfer path must have run: both undrained batches were
+    // detached from the normal lifecycle and adopted by the engine, and the
+    // stage buffer arena they write into was not freed through the transport.
+    EXPECT_EQ(engine->deferredStageTeardownBatchCountForTest(), 2u);
+    EXPECT_EQ(engine->aliveBatchCountForTest(), 0u);
+    EXPECT_EQ(fake_tcp->free_local_memory_calls.load(std::memory_order_acquire),
+              0);
+
+    EXPECT_TRUE(
+        engine->unregisterLocalMemory(source.data(), source.size()).ok());
+    EXPECT_TRUE(
+        engine->unregisterLocalMemory(target.data(), target.size()).ok());
+
+    // Engine teardown abandons the deferred resources only after the
+    // transports quiesce; the arena is intentionally leaked, never released
+    // through a destroyed transport. ASan/LSan in CI verify there is no
+    // double-free, use-after-free, or unreachable allocation on this path.
+    engine.reset();
+    EXPECT_EQ(fake_tcp->free_local_memory_calls.load(std::memory_order_acquire),
+              0);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/quota_accounting_test.cpp b/mooncake-transfer-engine/tent/tests/quota_accounting_test.cpp
new file mode 100644
index 0000000000..7a8a13325d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/quota_accounting_test.cpp
@@ -0,0 +1,263 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Unit tests for the DeviceSelector's per-NIC inflight accounting, the
+// selector half of the charge/release contract the worker relies on:
+//   * allocate charges each slice exactly the bytes it carries, so release
+//     by slice length balances every NIC;
+//   * chargeDevice / release are a matched pair on the device named, and a
+//     charge against an untracked device fails without touching anything;
+//   * a completion with no latency sample (cancel, timeout, failed CQ) moves
+//     no EWMA; a successful one updates it with length / attempt latency;
+//   * baseline (round-robin) mode never touches inflight, so it cannot
+//     underflow.
+// The slice-level half -- which device a slice's charge follows across a
+// fallback or a retry -- lives in rdma_transport_test.cpp
+// (RdmaWorkersChargeTest), where a Workers can be built without hardware.
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <limits>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/types.h"
+#include "tent/runtime/topology.h"
+#include "tent/transport/rdma/quota.h"
+#include "tent/transport/rdma/slice.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr uint64_t kNotFound = std::numeric_limits<uint64_t>::max();
+
+// Two RDMA NICs (dev 0, 1) reachable from host location "cpu:0".
+std::shared_ptr<Topology> MakeTopology() {
+    static const char* kJson = R"json(
+    {
+      "nics": [
+        {"name": "mlx5_0", "pci_bus_id": "0000:01:00.0", "type": 0,
+         "numa_node": 0},
+        {"name": "mlx5_1", "pci_bus_id": "0000:02:00.0", "type": 0,
+         "numa_node": 0}
+      ],
+      "mems": [
+        {"name": "cpu:0", "numa_node": 0,
+         "device_list": {"rank0": [0, 1]}}
+      ]
+    })json";
+    auto topo = std::make_shared<Topology>();
+    EXPECT_TRUE(topo->parse(kJson).ok());
+    return topo;
+}
+
+std::unique_ptr<DeviceSelector> MakeSelector(bool smart) {
+    auto sel = std::make_unique<DeviceSelector>();
+    auto topo = MakeTopology();
+    EXPECT_TRUE(sel->loadTopology(topo).ok());
+    sel->setSmartSelection(smart);
+    return sel;
+}
+
+uint64_t InflightOf(DeviceSelector& sel, const std::string& name) {
+    std::vector<NicLoadStats> stats;
+    sel.getNicLoadStats(stats);
+    for (const auto& s : stats)
+        if (s.device_name == name) return s.inflight_bytes;
+    return kNotFound;
+}
+
+uint64_t TotalInflight(DeviceSelector& sel) {
+    std::vector<NicLoadStats> stats;
+    sel.getNicLoadStats(stats);
+    uint64_t total = 0;
+    for (const auto& s : stats) total += s.inflight_bytes;
+    return total;
+}
+
+double EwmaOf(DeviceSelector& sel, const std::string& name) {
+    std::vector<NicLoadStats> stats;
+    sel.getNicLoadStats(stats);
+    for (const auto& s : stats)
+        if (s.device_name == name) return s.ewma_bandwidth_bps;
+    return -1.0;
+}
+
+}  // namespace
+
+// ---- allocate charges what each slice carries; release by length balances
+
+TEST(QuotaAccounting, AllocateChargesEachSliceItsOwnLength) {
+    auto sel = MakeSelector(/*smart=*/true);
+    std::vector<int> dev_ids;
+    // 1000 bytes in 250-byte blocks: four slices of 250.
+    ASSERT_TRUE(sel->allocate(1000, /*num_slices=*/4, /*slice_bytes=*/250,
+                              "cpu:0", dev_ids)
+                    .ok());
+    ASSERT_EQ(dev_ids.size(), 4u);
+    EXPECT_EQ(TotalInflight(*sel), 1000u);
+
+    for (int dev : dev_ids) ASSERT_TRUE(sel->release(dev, 250, 0.0).ok());
+    EXPECT_EQ(TotalInflight(*sel), 0u);
+}
+
+TEST(QuotaAccounting, ATrailingShortSliceIsChargedItsRealLength) {
+    auto sel = MakeSelector(/*smart=*/true);
+    std::vector<int> dev_ids;
+    // 1000 bytes in 300-byte blocks: 300, 300, 300 and a 100-byte tail.
+    ASSERT_TRUE(sel->allocate(1000, /*num_slices=*/4, /*slice_bytes=*/300,
+                              "cpu:0", dev_ids)
+                    .ok());
+    ASSERT_EQ(dev_ids.size(), 4u);
+    EXPECT_EQ(TotalInflight(*sel), 1000u);  // not 4 * 300
+
+    for (size_t i = 0; i < dev_ids.size(); ++i)
+        ASSERT_TRUE(sel->release(dev_ids[i], i == 3 ? 100 : 300, 0.0).ok());
+    EXPECT_EQ(InflightOf(*sel, "mlx5_0"), 0u);
+    EXPECT_EQ(InflightOf(*sel, "mlx5_1"), 0u);
+}
+
+// A folded tail makes the last slice longer than a block. It has to be
+// charged what it carries: release() returns the slice's real length, and
+// inflight_bytes is unsigned, so charging a block would wrap it around
+// rather than merely under-report it.
+TEST(QuotaAccounting, ALongLastSliceIsChargedItsRealLength) {
+    auto sel = MakeSelector(/*smart=*/true);
+    std::vector<int> dev_ids;
+    // 1000 bytes in 300-byte blocks over three slices: 300, 300 and a last
+    // one of 400 -- a 100-byte tail folded into it.
+    ASSERT_TRUE(sel->allocate(1000, /*num_slices=*/3, /*slice_bytes=*/300,
+                              "cpu:0", dev_ids)
+                    .ok());
+    ASSERT_EQ(dev_ids.size(), 3u);
+    EXPECT_EQ(TotalInflight(*sel), 1000u);  // not 3 * 300
+
+    for (size_t i = 0; i < dev_ids.size(); ++i)
+        ASSERT_TRUE(sel->release(dev_ids[i], i == 2 ? 400 : 300, 0.0).ok());
+    EXPECT_EQ(InflightOf(*sel, "mlx5_0"), 0u);
+    EXPECT_EQ(InflightOf(*sel, "mlx5_1"), 0u);
+}
+
+// The plan and the charging are two pieces of one rule, in two translation
+// units: planRdmaSlices() decides how a request is cut, allocate() has to
+// charge each device the same lengths the transport will hand its slices,
+// and release() returns those lengths. Walk real plans through all three and
+// the inflight bytes must come back to zero -- the folded tail is exactly
+// where the two used to disagree.
+TEST(QuotaAccounting, PlannedSlicesChargeAndReleaseBalance) {
+    constexpr uint64_t kBase = 65536;
+    for (uint64_t max_slices : {32ul, 64ul}) {
+        const uint64_t lengths[] = {
+            kBase + 1,  8 * kBase + 8192, 8 * kBase + kBase / 2,
+            3ull << 20, 10ull << 20,      100 * kBase + 7};
+        for (uint64_t length : lengths) {
+            const auto plan = planRdmaSlices(length, kBase, max_slices);
+            auto sel = MakeSelector(/*smart=*/true);
+            std::vector<int> dev_ids;
+            SCOPED_TRACE("length=" + std::to_string(length) +
+                         " max=" + std::to_string(max_slices));
+            ASSERT_TRUE(sel->allocate(length, static_cast<uint32_t>(plan.count),
+                                      plan.block_size, "cpu:0", dev_ids)
+                            .ok());
+            ASSERT_EQ(dev_ids.size(), plan.count);
+            EXPECT_EQ(TotalInflight(*sel), length);
+
+            uint64_t offset = 0;
+            for (size_t i = 0; i < dev_ids.size(); ++i) {
+                const uint64_t bytes = (i + 1 == dev_ids.size())
+                                           ? length - offset
+                                           : plan.block_size;
+                offset += bytes;
+                ASSERT_TRUE(sel->release(dev_ids[i], bytes, 0.0).ok());
+            }
+            EXPECT_EQ(offset, length);
+            EXPECT_EQ(TotalInflight(*sel), 0u);
+        }
+    }
+}
+
+// ---- chargeDevice / release are a matched pair on the device named ----
+
+TEST(QuotaAccounting, ChargeDeviceAndReleaseBalance) {
+    auto sel = MakeSelector(/*smart=*/true);
+    ASSERT_TRUE(sel->chargeDevice(1, 256).ok());
+    EXPECT_EQ(InflightOf(*sel, "mlx5_0"), 0u);
+    EXPECT_EQ(InflightOf(*sel, "mlx5_1"), 256u);
+
+    ASSERT_TRUE(sel->release(1, 256, 0.0).ok());
+    EXPECT_EQ(TotalInflight(*sel), 0u);
+}
+
+TEST(QuotaAccounting, ChargeOnAnUntrackedDeviceFailsAndChangesNothing) {
+    auto sel = MakeSelector(/*smart=*/true);
+    EXPECT_FALSE(sel->chargeDevice(999, 4096).ok());
+    EXPECT_EQ(TotalInflight(*sel), 0u);
+    EXPECT_FALSE(sel->release(999, 4096, 0.0).ok());
+    EXPECT_EQ(TotalInflight(*sel), 0u);
+}
+
+// ---- EWMA is only learned from successful completions ----
+
+TEST(QuotaAccounting, NonSuccessCompletionDoesNotMoveEwma) {
+    auto sel = MakeSelector(/*smart=*/true);
+    const double before = EwmaOf(*sel, "mlx5_0");
+    ASSERT_TRUE(sel->chargeDevice(0, 4096).ok());
+
+    // cancel / timeout / failed CQ all release with latency <= 0.
+    ASSERT_TRUE(sel->release(0, 4096, 0.0).ok());
+
+    EXPECT_EQ(EwmaOf(*sel, "mlx5_0"), before);  // unchanged
+    EXPECT_EQ(InflightOf(*sel, "mlx5_0"), 0u);
+}
+
+TEST(QuotaAccounting, SuccessUpdatesEwmaWithLengthOverLatency) {
+    auto sel = MakeSelector(/*smart=*/true);
+    const double before = EwmaOf(*sel, "mlx5_0");
+
+    const uint64_t length = 100'000'000;  // 100 MB
+    const double latency = 0.001;         // seconds (attempt latency)
+    ASSERT_TRUE(sel->chargeDevice(0, length).ok());
+
+    ASSERT_TRUE(sel->release(0, length, latency).ok());
+
+    // observed_bw = length / latency; EWMA = a*old + (1-a)*observed, a = 0.01.
+    const double observed = static_cast<double>(length) / latency;  // 1e11 B/s
+    const double alpha = sel->getSchedulingParams().bandwidth_learning_rate;
+    const double expected = alpha * before + (1.0 - alpha) * observed;
+    EXPECT_NEAR(EwmaOf(*sel, "mlx5_0"), expected, expected * 1e-6);
+    EXPECT_NE(EwmaOf(*sel, "mlx5_0"), before);
+}
+
+// ---- baseline (round-robin) mode never tracks inflight ----
+
+TEST(QuotaAccounting, BaselineModeKeepsInflightZero) {
+    auto sel = MakeSelector(/*smart=*/false);
+    std::vector<int> dev_ids;
+    ASSERT_TRUE(sel->allocate(4096, 8, 512, "cpu:0", dev_ids).ok());
+    ASSERT_EQ(dev_ids.size(), 8u);
+    EXPECT_EQ(TotalInflight(*sel), 0u);  // baseline charges nothing
+
+    // Neither a re-charge nor a release moves (or underflows) inflight.
+    ASSERT_TRUE(sel->chargeDevice(0, 512).ok());
+    EXPECT_EQ(TotalInflight(*sel), 0u);
+    for (int dev : dev_ids) ASSERT_TRUE(sel->release(dev, 512, 0.001).ok());
+    EXPECT_EQ(InflightOf(*sel, "mlx5_0"), 0u);  // not ~2^64 (no underflow)
+    EXPECT_EQ(InflightOf(*sel, "mlx5_1"), 0u);
+}
+
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/rail_monitor_test.cpp b/mooncake-transfer-engine/tent/tests/rail_monitor_test.cpp
index fc05c7a411..cfce3f29d6 100644
--- a/mooncake-transfer-engine/tent/tests/rail_monitor_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/rail_monitor_test.cpp
@@ -18,8 +18,8 @@
 #include <thread>
 
 #include "tent/common/config.h"
+#include "tent/runtime/segment.h"
 #include "tent/transport/rdma/rail_monitor.h"
-#include "tent/runtime/topology.h"
 
 namespace mooncake {
 namespace tent {
@@ -58,6 +58,31 @@ static std::shared_ptr<Topology> makeSingleNicTopology(const std::string& nic,
     return topo;
 }
 
+static SegmentDescRef makeSingleNicSegment(const std::string& nic,
+                                           int numa_node = 0) {
+    auto desc = std::make_shared<SegmentDesc>();
+    desc->type = SegmentType::Memory;
+    auto& topology = std::get<MemorySegmentDesc>(desc->detail).topology;
+    auto json_str = R"({
+        "nics": [{"name": ")" +
+                    nic + R"(", "type": 0, "numa_node": )" +
+                    std::to_string(numa_node) + R"(}],
+        "mems": [{
+            "name": "cuda0",
+            "type": 1,
+            "numa_node": )" +
+                    std::to_string(numa_node) +
+                    R"(,
+            "device_list": {"rank0": [0]}
+        }]
+    })";
+    auto status = topology.parse(json_str);
+    if (!status.ok()) {
+        ADD_FAILURE() << "Topology::parse failed: " << status.ToString();
+    }
+    return desc;
+}
+
 static std::shared_ptr<Topology> makeTwoNicTopology(const std::string& first,
                                                     const std::string& second) {
     auto json_str = R"({
@@ -97,7 +122,7 @@ TEST(RailMonitorConfigTest, CustomJsonOverridesAutomaticPeerMapping) {
     })";
 
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get(), rail_json, nullptr).ok());
+    ASSERT_TRUE(rail.load(local, remote, rail_json, nullptr).ok());
     EXPECT_EQ(rail.findBestRemoteDevice(/*local_nic=*/0, /*remote_numa=*/0), 1);
     EXPECT_EQ(rail.findBestRemoteDevice(/*local_nic=*/1, /*remote_numa=*/0), 0);
     EXPECT_TRUE(rail.available(/*local_nic=*/0, /*remote_nic=*/1));
@@ -155,7 +180,7 @@ TEST(RailMonitorCrossNumaTest, CrossNumaPrefersSameNameDevice) {
     // remote NUMA-0 domain: mlx5_y (idx0); remote NUMA-1 domain: mlx5_x (idx1).
     auto remote = makeNamedNumaTopology("mlx5_y", 0, "mlx5_x", 1);
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get()).ok());
+    ASSERT_TRUE(rail.load(local, remote).ok());
     ASSERT_TRUE(rail.ready());
 
     // local mlx5_y (idx1, NUMA 1) reaching the remote NUMA-0 domain: the only
@@ -175,7 +200,7 @@ TEST(RailMonitorRecoverTest, RecoverResetsErrorCount) {
     auto local = makeSingleNicTopology("mlx5_0");
     auto remote = makeSingleNicTopology("mlx5_1");
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get()).ok());
+    ASSERT_TRUE(rail.load(local, remote).ok());
     ASSERT_TRUE(rail.ready());
 
     // Initially available
@@ -202,7 +227,7 @@ TEST(RailMonitorRecoverTest, RecoverUnpausesPausedRail) {
     auto local = makeSingleNicTopology("mlx5_0");
     auto remote = makeSingleNicTopology("mlx5_1");
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get()).ok());
+    ASSERT_TRUE(rail.load(local, remote).ok());
 
     // Drive error_count to the default threshold (3) to trigger pause
     for (int i = 0; i < 3; ++i) rail.markFailed(0, 0);
@@ -224,12 +249,41 @@ TEST(RailMonitorRecoverTest, RecoverUnknownPairIsNoop) {
     auto local = makeSingleNicTopology("mlx5_0");
     auto remote = makeSingleNicTopology("mlx5_1");
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get()).ok());
+    ASSERT_TRUE(rail.load(local, remote).ok());
 
     // NIC IDs 5 and 7 are not in the topology — must not crash
     EXPECT_NO_FATAL_FAILURE(rail.markRecovered(5, 7));
 }
 
+TEST(RailMonitorLifetimeTest, KeepsSegmentSnapshotsAliveForFailureUpdates) {
+    auto local = makeSingleNicSegment("mlx5_0");
+    auto remote = makeSingleNicSegment("mlx5_1");
+    std::weak_ptr<SegmentDesc> weak_local = local;
+    std::weak_ptr<SegmentDesc> weak_remote = remote;
+    auto* local_topology = &local->getMemory().topology;
+    auto* remote_topology = &remote->getMemory().topology;
+
+    {
+        RailMonitor rail;
+        ASSERT_TRUE(
+            rail.load(std::shared_ptr<const Topology>(local, local_topology),
+                      std::shared_ptr<const Topology>(remote, remote_topology))
+                .ok());
+        local.reset();
+        remote.reset();
+
+        EXPECT_FALSE(weak_local.expired());
+        EXPECT_FALSE(weak_remote.expired());
+        EXPECT_NO_FATAL_FAILURE({
+            for (int i = 0; i < 3; ++i) rail.markFailed(0, 0);
+        });
+        EXPECT_FALSE(rail.available(0, 0));
+    }
+
+    EXPECT_TRUE(weak_local.expired());
+    EXPECT_TRUE(weak_remote.expired());
+}
+
 // ---------------------------------------------------------------------------
 // After recovery, findBestRemoteDevice maps back to the (only) available rail
 // ---------------------------------------------------------------------------
@@ -238,7 +292,7 @@ TEST(RailMonitorRecoverTest, FindBestAfterRecovery) {
     auto local = makeSingleNicTopology("mlx5_0");
     auto remote = makeSingleNicTopology("mlx5_1");
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get()).ok());
+    ASSERT_TRUE(rail.load(local, remote).ok());
 
     // Pause the only available rail
     for (int i = 0; i < 3; ++i) rail.markFailed(0, 0);
@@ -262,6 +316,43 @@ TEST(RailMonitorRecoverTest, FindBestAfterRecovery) {
 // pause would expire in ~2s.
 // ---------------------------------------------------------------------------
 
+// Segment metadata is copy-on-write: a new Topology object with the same
+// NIC/memory wiring must not rebuild rail_states_ (that would reset
+// error_count) and must not treat the reload as a first-time config log.
+TEST(RailMonitorLoadTest, SameLayoutReloadPreservesErrorCount) {
+    auto local1 = makeSingleNicTopology("mlx5_0");
+    auto remote1 = makeSingleNicTopology("mlx5_1");
+    auto local2 = makeSingleNicTopology("mlx5_0");
+    auto remote2 = makeSingleNicTopology("mlx5_1");
+    Config cfg;
+    RailMonitor rail;
+    ASSERT_TRUE(rail.load(local1, remote1, "", &cfg).ok());
+
+    rail.markFailed(0, 0);
+    rail.markFailed(0, 0);
+    EXPECT_TRUE(rail.available(0, 0))
+        << "Two failures are below the default threshold of 3";
+
+    ASSERT_TRUE(rail.load(local2, remote2, "", &cfg).ok());
+    rail.markFailed(0, 0);
+    EXPECT_FALSE(rail.available(0, 0))
+        << "COW snapshot refresh must not reset rail error_count";
+}
+
+TEST(RailMonitorLoadTest, DifferentLayoutRebuildsMapping) {
+    auto local = makeSingleNicTopology("mlx5_0");
+    auto remote_old = makeSingleNicTopology("mlx5_1");
+    auto remote_new = makeSingleNicTopology("mlx5_2");
+    RailMonitor rail;
+    ASSERT_TRUE(rail.load(local, remote_old).ok());
+    for (int i = 0; i < 3; ++i) rail.markFailed(0, 0);
+    EXPECT_FALSE(rail.available(0, 0));
+
+    ASSERT_TRUE(rail.load(local, remote_new).ok());
+    EXPECT_TRUE(rail.available(0, 0))
+        << "A real topology change must rebuild rails from a clean state";
+}
+
 TEST(RailMonitorRecoverTest, CooldownDoesNotCarryOverAfterRecovery) {
     auto local = makeSingleNicTopology("mlx5_0");
     auto remote = makeSingleNicTopology("mlx5_1");
@@ -272,7 +363,7 @@ TEST(RailMonitorRecoverTest, CooldownDoesNotCarryOverAfterRecovery) {
     cfg.set(RailMonitor::kCfgCooldownSecs, 1);      // small initial cooldown
 
     RailMonitor rail;
-    ASSERT_TRUE(rail.load(local.get(), remote.get(), "", &cfg).ok());
+    ASSERT_TRUE(rail.load(local, remote, "", &cfg).ok());
 
     // First pause cycle: single failure arms resume_time at now+1s.
     rail.markFailed(0, 0);
@@ -298,6 +389,44 @@ TEST(RailMonitorRecoverTest, CooldownDoesNotCarryOverAfterRecovery) {
            "from the previous cycle.";
 }
 
+// ---------------------------------------------------------------------------
+// Defect A: a burst of failures within one error window must not escalate the
+// cooldown. Previously cooldown doubled on every markFailed call, so N error
+// WQEs in 10s pushed a 1s pause to the 300s cap, forcing a multi-minute
+// TCP fallback after the peer had already recovered. Now the cooldown is set
+// once when a fresh pause arms; errors arriving while already paused are
+// no-ops.
+//
+// error_threshold=1, cooldown=1s. 8 rapid markFailed calls must arm resume_time
+// at now+1s, not now+256s.
+// ---------------------------------------------------------------------------
+
+TEST(RailMonitorBurstTest, BurstFailuresDoNotEscalateCooldown) {
+    auto local = makeSingleNicTopology("mlx5_0");
+    auto remote = makeSingleNicTopology("mlx5_1");
+
+    Config cfg;
+    cfg.set(RailMonitor::kCfgErrorThreshold, 1);
+    cfg.set(RailMonitor::kCfgErrorWindowSecs, 60);
+    cfg.set(RailMonitor::kCfgCooldownSecs, 1);
+
+    RailMonitor rail;
+    ASSERT_TRUE(rail.load(local, remote, "", &cfg).ok());
+
+    // A burst of 8 failures within the error window. With the old per-error
+    // doubling, cooldown would be 1->2->4->...->256s (capped 300). With the
+    // fix, only the first failure arms the pause at +1s; the rest are no-ops.
+    for (int i = 0; i < 8; ++i) rail.markFailed(0, 0);
+    EXPECT_FALSE(rail.available(0, 0));
+
+    // 1.5s > 1s initial cooldown, far below any escalated value. If the burst
+    // had escalated, the rail would still be paused here.
+    std::this_thread::sleep_for(std::chrono::milliseconds(1500));
+    EXPECT_TRUE(rail.available(0, 0))
+        << "A single failure burst must not escalate the cooldown past the "
+           "initial 1s; staying paused past 1.5s indicates per-error doubling.";
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/rdma_async_event_drain_test.cpp b/mooncake-transfer-engine/tent/tests/rdma_async_event_drain_test.cpp
new file mode 100644
index 0000000000..06aa280cde
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/rdma_async_event_drain_test.cpp
@@ -0,0 +1,219 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Workers::handleContextEvents() must empty the async event fd on every call:
+// the fd is edge-triggered, so anything left queued is stranded until an
+// unrelated later event releases it -- and a stranded IBV_EVENT_PORT_ACTIVE
+// leaves its context paused, silently failing every transfer on that NIC.
+// These tests replace the event source with a scripted queue via linker
+// wrapping, so no RDMA device is needed.
+
+#include <gtest/gtest.h>
+#include <infiniband/verbs.h>
+
+#include <cerrno>
+#include <cstring>
+#include <deque>
+#include <memory>
+
+#include "tent/runtime/topology.h"
+#include "tent/transport/rdma/context.h"
+#include "tent/transport/rdma/params.h"
+#include "tent/transport/rdma/rdma_transport.h"
+#include "tent/transport/rdma/workers.h"
+
+namespace {
+
+// Stands in for the kernel's async event queue behind async_fd.
+struct AsyncEventScript {
+    std::deque<ibv_event_type> pending;
+    // Reported once `pending` runs dry. EAGAIN mimics a drained non-blocking
+    // fd; anything else mimics a real read failure.
+    int drained_errno = EAGAIN;
+    // Fail this many reads with EINTR before serving the queue.
+    int pending_eintr = 0;
+    int get_calls = 0;
+    int ack_calls = 0;
+};
+
+AsyncEventScript g_script;
+
+}  // namespace
+
+extern "C" int __wrap_ibv_get_async_event(struct ibv_context* context,
+                                          struct ibv_async_event* event) {
+    (void)context;  // Never dereferenced by the code under test.
+    g_script.get_calls++;
+    if (g_script.pending_eintr > 0) {
+        g_script.pending_eintr--;
+        errno = EINTR;
+        return -1;
+    }
+    if (g_script.pending.empty()) {
+        errno = g_script.drained_errno;
+        return -1;
+    }
+    memset(event, 0, sizeof(*event));
+    event->event_type = g_script.pending.front();
+    g_script.pending.pop_front();
+    return 0;
+}
+
+extern "C" void __wrap_ibv_ack_async_event(struct ibv_async_event* event) {
+    (void)event;
+    g_script.ack_calls++;
+}
+
+namespace mooncake {
+namespace tent {
+
+// Friend accessor for driving the event loop without a full install().
+class RdmaTransportTestPeer {
+   public:
+    static void bindTopology(RdmaTransport& transport,
+                             std::shared_ptr<Topology> topology) {
+        transport.local_topology_ = topology;
+        transport.local_buffer_manager_.setTopology(topology);
+        transport.params_ = std::make_shared<RdmaParams>();
+        transport.conf_ = std::make_shared<Config>();
+    }
+
+    static size_t initializeContexts(RdmaTransport& transport) {
+        return transport.initializeContexts();
+    }
+
+    static std::unique_ptr<Workers> makeWorkers(RdmaTransport& transport) {
+        return std::make_unique<Workers>(&transport);
+    }
+
+    static int handleContextEvents(Workers& workers, int dev_id,
+                                   std::shared_ptr<RdmaContext>& context) {
+        return workers.handleContextEvents(dev_id, context);
+    }
+
+    static RdmaContextSet& contextSet(RdmaTransport& transport) {
+        return transport.context_set_;
+    }
+};
+
+namespace {
+
+// Event types whose handlers touch nothing a device-less context lacks.
+// IBV_EVENT_COMM_EST falls through applyContextEvent()'s default label;
+// IBV_EVENT_PORT_ACTIVE takes the recovery path, where resume() is a no-op on
+// an inert context and the link-speed refresh declines without a device.
+// Together they cover a handled and an unhandled event.
+constexpr ibv_event_type kUnhandledEvent = IBV_EVENT_COMM_EST;
+constexpr ibv_event_type kHandledEvent = IBV_EVENT_PORT_ACTIVE;
+
+class AsyncEventDrainTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        topology_ = std::make_shared<Topology>();
+        // No device is named "mc-absent-rnic-0" on any host, so the context
+        // stays inert: construct() still builds the endpoint store, but no
+        // real async fd is ever opened and only the scripted queue answers.
+        ASSERT_TRUE(
+            topology_
+                ->parse(
+                    R"({"nics":[{"name":"mc-absent-rnic-0","type":0,"numa_node":0}]})")
+                .ok());
+        RdmaTransportTestPeer::bindTopology(transport_, topology_);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+
+        g_script = AsyncEventScript{};
+    }
+
+    int drain() {
+        auto& context = RdmaTransportTestPeer::contextSet(transport_)[kDev];
+        return RdmaTransportTestPeer::handleContextEvents(*workers_, kDev,
+                                                          context);
+    }
+
+    static constexpr int kDev = 0;
+    std::shared_ptr<Topology> topology_;
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+};
+
+// The regression: a burst arriving between two epoll wakeups must be consumed
+// in full, not one event at a time.
+TEST_F(AsyncEventDrainTest, DrainsEveryQueuedEvent) {
+    constexpr int kBurst = 5;
+    for (int i = 0; i < kBurst; ++i)
+        g_script.pending.push_back(kUnhandledEvent);
+
+    EXPECT_EQ(drain(), 0);
+
+    EXPECT_TRUE(g_script.pending.empty())
+        << "one epoll wakeup must drain the whole async event queue; "
+        << g_script.pending.size() << " event(s) were left stranded";
+    // kBurst reads plus the trailing EAGAIN that ends the drain.
+    EXPECT_EQ(g_script.get_calls, kBurst + 1);
+    EXPECT_EQ(g_script.ack_calls, kBurst);
+}
+
+// A PORT_ACTIVE queued behind a burst is the case that wedged a NIC for good,
+// so it must be reached and acked like any other event.
+TEST_F(AsyncEventDrainTest, ReachesHandledEventQueuedBehindOthers) {
+    g_script.pending.push_back(kUnhandledEvent);
+    g_script.pending.push_back(kUnhandledEvent);
+    g_script.pending.push_back(kHandledEvent);
+
+    EXPECT_EQ(drain(), 0);
+
+    EXPECT_TRUE(g_script.pending.empty());
+    EXPECT_EQ(g_script.get_calls, 4);
+    EXPECT_EQ(g_script.ack_calls, 3);
+}
+
+// A wakeup with nothing pending is a drained fd, not a failure.
+TEST_F(AsyncEventDrainTest, EmptyQueueIsNotAnError) {
+    EXPECT_EQ(drain(), 0);
+
+    EXPECT_EQ(g_script.get_calls, 1);
+    EXPECT_EQ(g_script.ack_calls, 0);
+}
+
+// A signal must not end the drain early, or the events behind it are stranded
+// exactly as they were before the fix.
+TEST_F(AsyncEventDrainTest, InterruptedReadIsRetried) {
+    g_script.pending.push_back(kUnhandledEvent);
+    g_script.pending.push_back(kUnhandledEvent);
+    g_script.pending_eintr = 1;
+
+    EXPECT_EQ(drain(), 0);
+
+    EXPECT_TRUE(g_script.pending.empty());
+    // One EINTR, two reads, one trailing EAGAIN.
+    EXPECT_EQ(g_script.get_calls, 4);
+    EXPECT_EQ(g_script.ack_calls, 2);
+}
+
+// A genuine read failure still aborts and propagates, so the loop cannot spin
+// forever on a broken fd.
+TEST_F(AsyncEventDrainTest, RealReadErrorStopsTheDrain) {
+    g_script.pending.push_back(kUnhandledEvent);
+    g_script.drained_errno = EIO;
+
+    EXPECT_EQ(drain(), -1);
+
+    EXPECT_EQ(g_script.get_calls, 2);
+    EXPECT_EQ(g_script.ack_calls, 1);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/rdma_transport_test.cpp b/mooncake-transfer-engine/tent/tests/rdma_transport_test.cpp
index 6e918a21d2..fe353cf4ca 100644
--- a/mooncake-transfer-engine/tent/tests/rdma_transport_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/rdma_transport_test.cpp
@@ -12,16 +12,28 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#include <cerrno>
+#include <dlfcn.h>
 #include <gtest/gtest.h>
 #include <infiniband/verbs.h>
+#include <sys/eventfd.h>
 #include <sys/wait.h>
 #include <unistd.h>
 
+#ifdef USE_CUDA
+#include <cuda.h>
+#include <cuda_runtime.h>
+#endif
+
 #include <algorithm>
+#include <atomic>
 #include <chrono>
 #include <cstdint>
 #include <cstring>
+#include <functional>
 #include <memory>
+#include <mutex>
+#include <stdexcept>
 #include <string>
 #include <thread>
 #include <vector>
@@ -29,11 +41,16 @@
 #include "tent/common/config.h"
 #include "tent/common/types.h"
 #include "tent/transfer_engine.h"
+#include "tent/runtime/platform.h"
 #include "tent/runtime/topology.h"
 #include "tent/transport/rdma/context.h"
-#include "tent/transport/rdma/ibv_loader.h"
+#include "tent/transport/rdma/endpoint.h"
+#include "tent/transport/rdma/endpoint_store.h"
 #include "tent/transport/rdma/params.h"
+#include "tent/transport/rdma/quota.h"
 #include "tent/transport/rdma/rdma_transport.h"
+#include "tent/transport/rdma/slice.h"
+#include "tent/transport/rdma/ibv_loader.h"
 #include "tent/transport/rdma/workers.h"
 
 namespace mooncake {
@@ -50,6 +67,35 @@ class RdmaTransportTestPeer {
         transport.conf_ = std::make_shared<Config>();
     }
 
+    static void bindMetadata(RdmaTransport& transport,
+                             std::shared_ptr<ControlService> metadata) {
+        transport.metadata_ = std::move(metadata);
+    }
+
+    static void bindContexts(RdmaTransport& transport,
+                             RdmaContextSet contexts) {
+        transport.context_set_ = std::move(contexts);
+    }
+
+    // Defaults to a monitor tick: that is what the orphan tests stand in for.
+    static void reapOrphanSlices(RdmaTransport& transport,
+                                 bool on_tick = true) {
+        transport.reapOrphanSlices(on_tick);
+    }
+
+    static size_t orphanSliceCount(RdmaTransport& transport) {
+        std::lock_guard<std::mutex> guard(transport.orphan_slice_mutex_);
+        return transport.orphan_slices_.size();
+    }
+    static size_t orphanWarnings(RdmaTransport& transport) {
+        std::lock_guard<std::mutex> guard(transport.orphan_slice_mutex_);
+        return transport.orphan_warnings_;
+    }
+    static void setOrphanWarnAfterPasses(RdmaTransport& transport,
+                                         uint32_t passes) {
+        transport.orphan_warn_after_passes_ = passes;
+    }
+
     // Runs the monitorThread() 1 Hz reclaim tick without starting any worker
     // threads.
     static void reclaimEndpoints(RdmaTransport& transport) {
@@ -61,9 +107,246 @@ class RdmaTransportTestPeer {
         return transport.initializeContexts();
     }
 
+    // Constructs Workers (which seeds the DeviceSelector from context_set_)
+    // without starting any threads.
+    static std::unique_ptr<Workers> makeWorkers(RdmaTransport& transport) {
+        return std::make_unique<Workers>(&transport);
+    }
+
+    // Drives the decision half of handleContextEvents with a synthesized
+    // event, bypassing ibv_get_async_event/ibv_ack_async_event.
+    static void applyContextEvent(Workers& workers, int dev_id,
+                                  RdmaContext& context,
+                                  const ibv_async_event& event) {
+        workers.applyContextEvent(dev_id, context, event);
+    }
+
+    // Runs the monitorThread() 1 Hz safety net for contexts whose
+    // IBV_EVENT_PORT_ACTIVE never arrived, without starting any threads.
+    static void resumePausedContexts(Workers& workers) {
+        workers.resumePausedContexts();
+    }
+
     static const RdmaContextSet& contextSet(const RdmaTransport& transport) {
         return transport.context_set_;
     }
+
+    static void setNumWorkers(RdmaTransport& transport, int num_workers) {
+        transport.params_->workers.num_workers = num_workers;
+    }
+
+    static void addInflight(Workers& workers, size_t worker_id, int64_t delta) {
+        workers.worker_context_[worker_id].inflight_slices.fetch_add(delta);
+    }
+
+    using NotifyAction = RdmaTransport::NotifyCompletionAction;
+
+    static NotifyAction classifyNotifyCompletion(ibv_wc_status status,
+                                                 bool endpoint_alive,
+                                                 bool endpoint_ready) {
+        return RdmaTransport::classifyNotifyCompletion(status, endpoint_alive,
+                                                       endpoint_ready);
+    }
+
+    static void orderByDeadline(Workers& workers,
+                                std::vector<RdmaSlice*>& slices, int dev_id,
+                                uint64_t now_ns) {
+        workers.orderByDeadline(slices, dev_id, now_ns);
+    }
+
+    static void rechargeSlice(Workers& workers, RdmaSlice* slice, int dev_id) {
+        workers.rechargeSlice(slice, dev_id);
+    }
+
+    static void releaseSliceQuota(Workers& workers, RdmaSlice* slice,
+                                  uint64_t now_ns, double latency) {
+        workers.releaseSliceQuota(slice, now_ns, latency);
+    }
+
+    static void notePostedSlice(Workers& workers, RdmaSlice* slice) {
+        workers.notePostedSlice(slice);
+    }
+
+    static void handleCompletion(Workers& workers,
+                                 Workers::WorkerContext& worker,
+                                 RdmaContext& context, const ibv_wc& wc,
+                                 uint64_t poll_ts, bool last_in_pass = true) {
+        workers.handleCompletion(worker, context, wc, poll_ts, last_in_pass);
+    }
+
+    static void markPosted(Workers& workers, Workers::WorkerContext& worker,
+                           RdmaSlice* slice, uint64_t post_ts) {
+        workers.markPosted(worker, slice, post_ts);
+    }
+
+    using WorkerContext = Workers::WorkerContext;
+
+    // Stands in for start(): the lane array without any threads.
+    static void makeWorkerContexts(Workers& workers, size_t n) {
+        workers.worker_context_ = new WorkerContext[n];
+        workers.num_workers_ = n;
+    }
+    static void destroyWorkerContexts(Workers& workers) {
+        delete[] workers.worker_context_;
+        workers.worker_context_ = nullptr;
+        workers.num_workers_ = 0;
+    }
+    static WorkerContext& workerContext(Workers& workers, size_t i) {
+        return workers.worker_context_[i];
+    }
+    static void retireSweptSlice(Workers& workers, WorkerContext& self,
+                                 RdmaSlice* slice, uint64_t now_ns,
+                                 bool bytes_moved = false) {
+        workers.retireSweptSlice(self, slice, now_ns, nullptr, bytes_moved);
+    }
+    static void drainReclaimed(Workers& workers, WorkerContext& worker) {
+        workers.drainReclaimed(worker);
+    }
+    // Drop the handover list without touching the set, to model a lane that
+    // drained it just before another lane handed an entry over.
+    static void clearReclaimed(WorkerContext& worker) {
+        std::lock_guard<std::mutex> lock(worker.reclaim_mutex);
+        worker.reclaimed.clear();
+    }
+    static bool dropUnpostableSlice(Workers& workers, WorkerContext& worker,
+                                    RdmaSlice* slice) {
+        return workers.dropUnpostableSlice(worker, slice);
+    }
+
+    static void setSliceTimeout(Workers& workers, uint64_t ns) {
+        workers.slice_timeout_ns_ = ns;
+    }
+    static void expireTimedOutSlices(Workers& workers, WorkerContext& ctx,
+                                     uint64_t now_ns) {
+        workers.expireTimedOutSlices(ctx, now_ns);
+    }
+
+    static Status notifyStatusForEndpointFailure(const Status& failure) {
+        return RdmaTransport::notifyStatusForEndpointFailure(failure);
+    }
+};
+
+// Friend accessor for RdmaContext: TENT reaches libibverbs through a table of
+// function pointers the context copies from IbvLoader, so a test can replace
+// individual entries and hand the context a placeholder device instead of
+// needing an RNIC.
+class RdmaContextTestPeer {
+   public:
+    static IbvSymbols& verbs(RdmaContext& context) { return context.verbs_; }
+
+    // Make the context look opened on `native` (never dereferenced by the
+    // port-attribute paths, only passed back to the verbs) with `params`.
+    static void bindDevice(RdmaContext& context, ibv_context* native,
+                           std::shared_ptr<RdmaParams> params) {
+        context.native_context_ = native;
+        context.params_ = std::move(params);
+    }
+
+    // The rest of what enable() would build, for a test that only needs a
+    // context complete enough to construct endpoints on.
+    static void bindResources(RdmaContext& context, ibv_pd* pd,
+                              std::vector<RdmaCQ*> cqs, RdmaCQ* notify_cq) {
+        context.native_pd_ = pd;
+        context.cq_list_ = std::move(cqs);
+        context.notify_cq_ = notify_cq;
+        context.endpoint_store_ =
+            std::make_shared<SIEVEEndpointStore>(context, 16);
+    }
+
+    static void unbindResources(RdmaContext& context) {
+        context.native_pd_ = nullptr;
+        context.cq_list_.clear();
+        context.notify_cq_ = nullptr;
+        context.endpoint_store_.reset();
+    }
+
+    static void seedAddress(RdmaContext& context,
+                            const std::string& device_name, uint32_t lid,
+                            int gid_index, const ibv_gid& gid,
+                            RdmaContext::DeviceStatus status) {
+        std::lock_guard<std::mutex> guard(context.address_mutex_);
+        context.device_name_ = device_name;
+        context.lid_ = lid;
+        context.gid_index_ = gid_index;
+        context.gid_ = gid;
+        context.status_ = status;
+    }
+
+    static void unbindDevice(RdmaContext& context) {
+        context.native_context_ = nullptr;
+    }
+
+    // Everything construct() does before it calls enable(), so a test can
+    // install stand-in verbs in between and then drive enable() itself.
+    static void prepareForEnable(RdmaContext& context,
+                                 const std::string& device_name,
+                                 std::shared_ptr<RdmaParams> params) {
+        context.device_name_ = device_name;
+        context.params_ = params;
+        context.endpoint_store_ = std::make_shared<SIEVEEndpointStore>(
+            context, params->endpoint.endpoint_store_cap);
+        context.status_ = RdmaContext::DEVICE_DISABLED;
+    }
+
+    // What enable() built and disable() has to give back.
+    static size_t compChannelCount(const RdmaContext& context) {
+        return context.comp_channel_.size();
+    }
+    static size_t cqCount(const RdmaContext& context) {
+        return context.cq_list_.size();
+    }
+};
+
+// Friend accessor for RdmaEndPoint. Posting is the one step in the data
+// path that does not go through the injectable verbs table (ibv_post_send is
+// an inline that dispatches through the queue pair), so a test stands in for
+// it and puts the slice on the queue pair the way submitSlices would.
+// Tickets are the lock's only observable state; a test that needs to know a
+// thread is queued on it watches them being handed out.
+class TicketLockTestPeer {
+   public:
+    static int ticketsIssued(const TicketLock& lock) {
+        return lock.next_ticket_.load(std::memory_order_acquire);
+    }
+};
+
+class RdmaEndPointTestPeer {
+   public:
+    static RdmaAddressSnapshot localAddress(const RdmaEndPoint& endpoint) {
+        return endpoint.local_address_;
+    }
+
+    static void pretendPosted(const std::shared_ptr<RdmaEndPoint>& endpoint,
+                              int qp_index, RdmaSlice* slice) {
+        ASSERT_TRUE(endpoint->reserveQuota(qp_index, 1));
+        slice->qp_index = qp_index;
+        slice->ep_weak_ptr = endpoint;
+        std::lock_guard<TicketLock> guard(endpoint->queue_lock_list_[qp_index]);
+        endpoint->slice_queue_[qp_index].push(slice);
+        // submitSlices() counts the completion the post owes; a stand-in that
+        // skipped it would leave the slice looking settled.
+        slice->completions_owed.fetch_add(1, std::memory_order_acq_rel);
+    }
+    static void markReady(const std::shared_ptr<RdmaEndPoint>& endpoint) {
+        endpoint->status_.store(RdmaEndPoint::EP_READY,
+                                std::memory_order_relaxed);
+    }
+    static bool queueEmpty(const std::shared_ptr<RdmaEndPoint>& endpoint,
+                           int qp_index) {
+        return endpoint->slice_queue_[qp_index].empty();
+    }
+    static int wrDepth(const std::shared_ptr<RdmaEndPoint>& endpoint,
+                       int qp_index) {
+        return endpoint->wr_depth_list_[qp_index].value.load();
+    }
+    static int inflightSlices(const std::shared_ptr<RdmaEndPoint>& endpoint) {
+        return endpoint->inflight_slices_.load();
+    }
+    // Held by a test to stall a completion handler inside acknowledge().
+    static TicketLock& qpLock(const std::shared_ptr<RdmaEndPoint>& endpoint,
+                              int qp_index) {
+        return endpoint->queue_lock_list_[qp_index];
+    }
 };
 
 namespace {
@@ -121,6 +404,27 @@ std::shared_ptr<Config> makeRdmaConfig() {
     return config;
 }
 
+std::shared_ptr<Topology> topologyWithRdmaNics(size_t count) {
+    auto topology = std::make_shared<Topology>();
+    for (size_t i = 0; i < count; ++i) {
+        Topology::NicEntry nic;
+        nic.name = "mlx5_" + std::to_string(i);
+        nic.type = Topology::NIC_RDMA;
+        nic.numa_node = 0;
+        topology->nic_list_.push_back(std::move(nic));
+    }
+
+    Topology::MemEntry memory;
+    memory.name = "cpu:0";
+    memory.type = Topology::MEM_HOST;
+    memory.numa_node = 0;
+    for (size_t i = 0; i < count; ++i) {
+        memory.device_list[0].push_back(static_cast<int>(i));
+    }
+    topology->mem_list_.push_back(std::move(memory));
+    return topology;
+}
+
 bool waitBatchDone(TransferEngine& engine, BatchID batch) {
     TransferStatus status;
     for (int i = 0; i < 10000; ++i) {
@@ -153,6 +457,130 @@ TEST(RdmaSubBatchTest, ReportsTaskCount) {
     EXPECT_EQ(batch.size(), 2);
 }
 
+TEST(DeviceSelectorTest, PerSliceAllocationHonorsPolicy) {
+    auto topology = topologyWithRdmaNics(3);
+
+    {
+        DeviceSelector selector;
+        ASSERT_TRUE(selector.loadTopology(topology).ok());
+        int chosen_device = -1;
+        ASSERT_TRUE(
+            selector
+                .allocate(4096, "cpu:0", chosen_device, PRIO_HIGH, 1ULL << 1)
+                .ok());
+        EXPECT_EQ(chosen_device, 1);
+    }
+
+    {
+        DeviceSelector selector;
+        ASSERT_TRUE(selector.loadTopology(topology).ok());
+        auto params = selector.getSchedulingParams();
+        params.device_base_priorities = {0, 1, 2};
+        params.local_rotation_interval_us = 0;
+        params.numa_tier_weights[0] = 1.0;
+        params.numa_tier_weights[1] = 1.0;
+        params.numa_tier_weights[2] = 1.0;
+        params.score_jitter_range = 0.0;
+        selector.setSchedulingParams(params);
+
+        int chosen_device = -1;
+        ASSERT_TRUE(selector
+                        .allocate(4096, "cpu:0", chosen_device, PRIO_LOW,
+                                  (1ULL << 1) | (1ULL << 2))
+                        .ok());
+        EXPECT_EQ(chosen_device, 2);
+    }
+}
+
+// Retiring an endpoint moves its data QPs to ERR and flushes in-flight
+// transfers, so a notify completion error may only do that when it can mean the
+// peer or the path is gone. The notify QP owns its buffers, MRs and CQ, so a
+// local WQE/MR fault says nothing about the data path.
+TEST(RdmaNotifyFaultTriageTest, LocalNotifyFaultsKeepTheDataPath) {
+    using Action = RdmaTransportTestPeer::NotifyAction;
+    const auto classify = &RdmaTransportTestPeer::classifyNotifyCompletion;
+
+    EXPECT_EQ(classify(IBV_WC_LOC_LEN_ERR, true, true),
+              Action::DisableNotification);
+    EXPECT_EQ(classify(IBV_WC_LOC_QP_OP_ERR, true, true),
+              Action::DisableNotification);
+    EXPECT_EQ(classify(IBV_WC_LOC_PROT_ERR, true, true),
+              Action::DisableNotification);
+    EXPECT_EQ(classify(IBV_WC_LOC_ACCESS_ERR, true, true),
+              Action::DisableNotification);
+    EXPECT_EQ(classify(IBV_WC_MW_BIND_ERR, true, true),
+              Action::DisableNotification);
+}
+
+TEST(RdmaNotifyFaultTriageTest, PathAndPeerFaultsRetireTheEndpoint) {
+    using Action = RdmaTransportTestPeer::NotifyAction;
+    const auto classify = &RdmaTransportTestPeer::classifyNotifyCompletion;
+
+    // A restarted peer surfaces here, and the endpoint has to be retired for
+    // the next getEndpoint() to rebuild it with a live notify QP.
+    EXPECT_EQ(classify(IBV_WC_RETRY_EXC_ERR, true, true),
+              Action::RetireEndpoint);
+    EXPECT_EQ(classify(IBV_WC_REM_OP_ERR, true, true), Action::RetireEndpoint);
+    EXPECT_EQ(classify(IBV_WC_REM_ACCESS_ERR, true, true),
+              Action::RetireEndpoint);
+    EXPECT_EQ(classify(IBV_WC_REM_INV_REQ_ERR, true, true),
+              Action::RetireEndpoint);
+    EXPECT_EQ(classify(IBV_WC_FATAL_ERR, true, true), Action::RetireEndpoint);
+    // Nothing put this QP in ERR on our side, so the peer or the path did.
+    EXPECT_EQ(classify(IBV_WC_WR_FLUSH_ERR, true, true),
+              Action::RetireEndpoint);
+}
+
+// A bootstrap RPC that failed says the peer's control plane is not answering,
+// so a notification must not be handed to the RPC fallback: that would only
+// wait out a second RPC timeout on the thread that polls the batch.
+TEST(RdmaNotifyFaultTriageTest, BootstrapRpcFailureNotEligibleForFallback) {
+    const Status mapped = RdmaTransportTestPeer::notifyStatusForEndpointFailure(
+        Status::RpcServiceError("Failed to call RPC function"));
+    EXPECT_TRUE(mapped.IsRpcServiceError()) << mapped.ToString();
+    EXPECT_NE(mapped.message().find("Failed to call RPC function"),
+              std::string_view::npos);
+}
+
+// Every other reason getEndpoint() comes back empty - no enabled context,
+// allocation, QP setup, a stale segment - leaves the control plane reachable,
+// so the engine may still deliver over RPC.
+TEST(RdmaNotifyFaultTriageTest, OtherEndpointFailuresStayEligible) {
+    const Status failures[] = {
+        Status::InternalError("Failed to configure RDMA endpoint"),
+        Status::DeviceNotFound("No enabled RDMA context"),
+        Status::InvalidArgument("Missing peer GID in bootstrap"),
+        Status::NeedsRefreshCache("Empty target segment or device name"),
+    };
+    for (const auto& failure : failures) {
+        const Status mapped =
+            RdmaTransportTestPeer::notifyStatusForEndpointFailure(failure);
+        EXPECT_TRUE(mapped.IsDeviceNotFound())
+            << failure.ToString() << " -> " << mapped.ToString();
+    }
+}
+
+TEST(RdmaNotifyFaultTriageTest, TeardownFlushesStayQuiet) {
+    using Action = RdmaTransportTestPeer::NotifyAction;
+    const auto classify = &RdmaTransportTestPeer::classifyNotifyCompletion;
+
+    // Every WR still posted on a retiring endpoint's notify QP flushes.
+    // Reporting each one floods the log and re-triggers teardown.
+    EXPECT_EQ(classify(IBV_WC_WR_FLUSH_ERR, true, false), Action::SkipSilently);
+    EXPECT_EQ(classify(IBV_WC_WR_FLUSH_ERR, false, false),
+              Action::SkipSilently);
+    // A real fault surfacing after the endpoint is gone has nothing left to
+    // act on.
+    EXPECT_EQ(classify(IBV_WC_RETRY_EXC_ERR, false, false), Action::ReportOnly);
+    // The notify QP stays published while the endpoint retires, so a real
+    // fault can still arrive on a not-ready endpoint: it is triaged as on any
+    // other live endpoint, and only flushes are skipped.
+    EXPECT_EQ(classify(IBV_WC_RETRY_EXC_ERR, true, false),
+              Action::RetireEndpoint);
+    EXPECT_EQ(classify(IBV_WC_LOC_LEN_ERR, true, false),
+              Action::DisableNotification);
+}
+
 // context_set_ is subscripted by NicID, so it must keep one slot per NIC even
 // when a device is skipped. It used to push_back only on the success path,
 // compacting the array so a later dev_id named the wrong RNIC or ran off it.
@@ -165,6 +593,13 @@ void expectInertContextPerNic(const RdmaContextSet& contexts, size_t expected) {
         // Inert contexts must stay safe for the whole-list consumers.
         EXPECT_EQ(contexts[i]->cq(0), nullptr);
         EXPECT_EQ(contexts[i]->notifyCq(), nullptr);
+        EXPECT_LT(contexts[i]->eventFd(), 0);
+        EXPECT_EQ(contexts[i]->nativeContext(), nullptr);
+        // construct() sets device_name_ before it can fail, so an empty name
+        // is what tells a fresh placeholder from a kept half-built context.
+        EXPECT_TRUE(contexts[i]->name().empty())
+            << "slot " << i << " kept a half-built context for "
+            << contexts[i]->name();
     }
 }
 
@@ -213,12 +648,9 @@ TEST(RdmaNicIndexAlignmentTest, ReclaimTickSkipsInertContexts) {
     RdmaTransportTestPeer::reclaimEndpoints(transport);
 }
 
-// The construct()-failure branch. IbvLoader dlcloses libibverbs when no device
-// is present, so construct() cannot be driven safely in that state.
+// The construct()-failure branch. Runs on any host: this binary links
+// libibverbs directly, so IbvLoader's dlclose does not unmap it.
 TEST(RdmaNicIndexAlignmentTest, ContextSetKeepsOneSlotWhenConstructFails) {
-    if (!IbvLoader::Instance().available())
-        GTEST_SKIP() << "no usable libibverbs; construct() cannot be driven";
-
     // Device names that resolve to no real RNIC, so construct() fails on any
     // host, with a non-RDMA entry in the middle to offset the indexes.
     auto topology = std::make_shared<Topology>();
@@ -239,153 +671,3018 @@ TEST(RdmaNicIndexAlignmentTest, ContextSetKeepsOneSlotWhenConstructFails) {
                              topology->getNicCount());
 }
 
-TEST(RdmaTransportIntegrationTest, WriteThenReadAcrossProcesses) {
-    if (!hasRdmaDevice()) GTEST_SKIP() << "no RDMA device detected";
+// A NIC whose construct() failed is still an RDMA entry in the topology, so
+// loadTopology() gives it a DeviceSelector slot. Workers must mark it
+// unavailable: it can carry no traffic, so it must be neither a selection
+// candidate nor part of the aggregate bandwidth the admission queue reads --
+// the configured default speed is for usable NICs only.
+TEST(RdmaNicIndexAlignmentTest, FailedContextIsUnavailableToSelector) {
+    auto topology = std::make_shared<Topology>();
+    ASSERT_TRUE(topology
+                    ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                    .ok());
 
-    constexpr size_t kDataLength = 4 * 1024 * 1024;
-    constexpr size_t kCancelTaskCount = 16;
-    constexpr size_t kCancelStride = 8 * 1024 * 1024;
-    constexpr size_t kBufferLength = kCancelTaskCount * kCancelStride;
-    int ready_pipe[2];
-    int stop_pipe[2];
-    ASSERT_EQ(pipe(ready_pipe), 0);
-    ASSERT_EQ(pipe(stop_pipe), 0);
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport),
+              static_cast<size_t>(0));
 
-    pid_t child = fork();
-    ASSERT_GE(child, 0);
-    if (child == 0) {
-        close(ready_pipe[0]);
-        close(stop_pipe[1]);
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+    auto* selector = workers->getDeviceSelector();
+    ASSERT_NE(selector, nullptr);
+    EXPECT_FALSE(selector->isDeviceAvailable(1));
+    // Nothing usable: no bandwidth to predict with, rather than 400G of it.
+    EXPECT_LT(selector->getAggregateEwmaBandwidth(), 0.0);
+}
 
-        TransferEngine server(makeRdmaConfig());
-        if (!server.available()) _exit(2);
-        std::vector<uint8_t> buffer(kBufferLength);
-        if (!server.registerLocalMemory(buffer.data(), buffer.size()).ok())
-            _exit(3);
+// refreshPortAttributes() is called from the monitor thread on port events.
+// On a slot that never opened a device it must fail cleanly and leave the
+// (zero) speed alone rather than touch a null ibv_context.
+// Port events carry the port they concern, and a device's async fd delivers
+// events for every port of that device. A context opens exactly one port, so
+// an event for another port must not touch its availability. These run on an
+// inert context: pause()/resume() are no-ops there and the decision under
+// test is the selector flip.
+class RdmaContextEventTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        topology_ = std::make_shared<Topology>();
+        ASSERT_TRUE(topology_
+                        ->parse(R"({"nics":[
+                            {"name":"mc-tcp-0","type":1,"numa_node":0},
+                            {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        RdmaTransportTestPeer::bindTopology(transport_, topology_);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_NE(selector_, nullptr);
+        // Init marked the failed context unavailable; pretend it recovered so
+        // the flips below are observable.
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+    }
 
-        const std::string segment = server.getSegmentName();
-        uint32_t length = static_cast<uint32_t>(segment.size());
-        if (write(ready_pipe[1], &length, sizeof(length)) != sizeof(length))
-            _exit(4);
-        if (write(ready_pipe[1], segment.data(), length) !=
-            static_cast<ssize_t>(length))
-            _exit(5);
+    RdmaContext& context() {
+        return *RdmaTransportTestPeer::contextSet(transport_)[kDev];
+    }
 
-        char stop = 0;
-        const ssize_t stop_result = read(stop_pipe[0], &stop, 1);
-        (void)stop_result;
-        (void)server.unregisterLocalMemory(buffer.data(), buffer.size());
-        _exit(0);
+    void fire(ibv_event_type type, int port_num) {
+        ibv_async_event event{};
+        event.event_type = type;
+        event.element.port_num = port_num;
+        RdmaTransportTestPeer::applyContextEvent(*workers_, kDev, context(),
+                                                 event);
     }
 
-    close(ready_pipe[1]);
-    close(stop_pipe[0]);
-    ChildProcessGuard child_guard(child, stop_pipe[1]);
+    int ourPort() { return context().portNum(); }
+    int otherPort() { return ourPort() + 1; }
 
-    uint32_t segment_length = 0;
-    ssize_t received =
-        read(ready_pipe[0], &segment_length, sizeof(segment_length));
-    if (received != static_cast<ssize_t>(sizeof(segment_length))) {
-        const int status = child_guard.reap();
-        GTEST_SKIP() << "RDMA server initialization failed, child status "
-                     << status;
-    }
-    std::string server_segment(segment_length, '\0');
-    ASSERT_EQ(read(ready_pipe[0], server_segment.data(), segment_length),
-              static_cast<ssize_t>(segment_length));
+    static constexpr int kDev = 1;
+    std::shared_ptr<Topology> topology_;
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+};
 
-    TransferEngine client(makeRdmaConfig());
-    ASSERT_TRUE(client.available());
-    std::vector<uint8_t> buffer(kBufferLength);
-    for (size_t i = 0; i < kDataLength; ++i) {
-        buffer[i] = static_cast<uint8_t>((i * 31) & 0xff);
-    }
-    ASSERT_TRUE(client.registerLocalMemory(buffer.data(), buffer.size()).ok());
+TEST_F(RdmaContextEventTest,
+       PortActiveKeepsDeviceUnavailableWhenAddressRefreshFails) {
+    fire(IBV_EVENT_PORT_ERR, ourPort());
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+    EXPECT_LT(selector_->getAggregateEwmaBandwidth(), 0.0);
 
-    SegmentID segment = 0;
-    Status result;
-    for (int i = 0; i < 100; ++i) {
-        result = client.openSegment(segment, server_segment);
-        if (result.ok()) break;
-        std::this_thread::sleep_for(std::chrono::milliseconds(20));
-    }
-    ASSERT_TRUE(result.ok()) << result.ToString();
+    // This fixture deliberately has no usable verbs context. PORT_ACTIVE must
+    // not re-admit a NIC whose current address cannot be queried. The success
+    // path is covered by RdmaAddressRefreshEventTest below.
+    fire(IBV_EVENT_PORT_ACTIVE, ourPort());
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+    EXPECT_LT(selector_->getAggregateEwmaBandwidth(), 0.0);
+}
 
-    SegmentInfo info;
-    ASSERT_TRUE(client.getSegmentInfo(segment, info).ok());
-    ASSERT_FALSE(info.buffers.empty());
+TEST_F(RdmaContextEventTest, EventsForAnotherPortAreIgnored) {
+    fire(IBV_EVENT_PORT_ERR, otherPort());
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
 
-    Request request{};
-    request.opcode = Request::WRITE;
-    request.source = buffer.data();
-    request.target_id = segment;
-    request.target_offset = info.buffers[0].base;
-    request.length = kDataLength;
-    request.transport_hint = RDMA;
+    fire(IBV_EVENT_PORT_ERR, ourPort());
+    ASSERT_FALSE(selector_->isDeviceAvailable(kDev));
+    fire(IBV_EVENT_PORT_ACTIVE, otherPort());
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+}
 
-    BatchID batch = client.allocateBatch(1);
-    ASSERT_TRUE(client.submitTransfer(batch, {request}).ok());
-    ASSERT_TRUE(waitBatchDone(client, batch));
-    ASSERT_TRUE(client.freeBatch(batch).ok());
+TEST_F(RdmaContextEventTest, DeviceFatalMarksUnavailableRegardlessOfPort) {
+    fire(IBV_EVENT_DEVICE_FATAL, otherPort());  // device-scoped: no port
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+}
 
-    request.opcode = Request::READ;
-    request.source = buffer.data() + kDataLength;
-    batch = client.allocateBatch(1);
-    ASSERT_TRUE(client.submitTransfer(batch, {request}).ok());
-    ASSERT_TRUE(waitBatchDone(client, batch));
-    ASSERT_TRUE(client.freeBatch(batch).ok());
-    EXPECT_EQ(
-        std::memcmp(buffer.data(), buffer.data() + kDataLength, kDataLength),
-        0);
+TEST_F(RdmaContextEventTest, CqErrLeavesAvailabilityAlone) {
+    fire(IBV_EVENT_CQ_ERR, ourPort());
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+}
 
-    // Keep one QP/worker and one outstanding WR so the tail task remains in
-    // the worker's unposted set long enough to exercise real cancellation.
-    std::vector<Request> cancel_requests;
-    cancel_requests.reserve(kCancelTaskCount);
-    for (size_t i = 0; i < kCancelTaskCount; ++i) {
-        Request cancel_request{};
-        cancel_request.opcode = Request::WRITE;
-        cancel_request.source = buffer.data() + i * kCancelStride;
-        cancel_request.target_id = segment;
-        cancel_request.target_offset = info.buffers[0].base + i * kCancelStride;
-        cancel_request.length = kDataLength;
-        cancel_request.transport_hint = RDMA;
-        cancel_requests.push_back(cancel_request);
+// ---- how a request is cut into slices ------------------------------------
+
+// Walk a plan the way submitTransferTasks() walks it: a block each, and
+// whatever is left for the last. Returns the lengths handed out.
+std::vector<uint64_t> walkPlan(const RdmaSlicePlan& plan, uint64_t length) {
+    std::vector<uint64_t> lengths;
+    uint64_t offset = 0;
+    for (uint64_t i = 0; i < plan.count; ++i) {
+        const uint64_t n =
+            (i + 1 == plan.count) ? length - offset : plan.block_size;
+        lengths.push_back(n);
+        offset += n;
     }
+    return lengths;
+}
 
-    batch = client.allocateBatch(kCancelTaskCount);
-    ASSERT_TRUE(client.submitTransfer(batch, cancel_requests).ok());
-    const size_t cancel_task_id = kCancelTaskCount - 1;
-    ASSERT_TRUE(client.cancelTransfer(batch, cancel_task_id).ok());
-    ASSERT_TRUE(client.cancelTransfer(batch, cancel_task_id).ok());
+// The whole contract, over a sweep of lengths against both caps: the slices
+// cover the request exactly, none is empty, the cap holds, and the block
+// stays a whole number of configured blocks.
+TEST(RdmaSlicePlanTest, EverySliceCarriesDataAndTheyCoverTheRequest) {
+    constexpr uint64_t kBase = 65536;
+    for (uint64_t max_slices : {32ul, 64ul}) {
+        for (uint64_t length :
+             {1ul, 2ul, kBase - 1, kBase, kBase + 1, 3 * kBase, 3 * kBase + 7,
+              100 * kBase, 100 * kBase + 1, 160 * kBase, 160 * kBase + 8192,
+              1000 * kBase, 1000 * kBase - 1}) {
+            const auto plan = planRdmaSlices(length, kBase, max_slices);
+            SCOPED_TRACE("length=" + std::to_string(length) +
+                         " max=" + std::to_string(max_slices));
+            EXPECT_LE(plan.count, max_slices);
+            EXPECT_GT(plan.count, 0u);
+            EXPECT_EQ(plan.block_size % kBase, 0u);
 
-    std::vector<TransferStatus> statuses;
-    for (int poll = 0; poll < 10000; ++poll) {
-        ASSERT_TRUE(client.getTransferStatus(batch, statuses).ok());
-        if (std::all_of(statuses.begin(), statuses.end(),
-                        [](const TransferStatus& task_status) {
-                            return task_status.s != TransferStatusEnum::PENDING;
-                        }))
-            break;
-        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            const auto lengths = walkPlan(plan, length);
+            uint64_t total = 0;
+            for (size_t i = 0; i < lengths.size(); ++i) {
+                EXPECT_GT(lengths[i], 0u) << "empty slice";
+                if (i + 1 < lengths.size()) {
+                    EXPECT_EQ(lengths[i], plan.block_size);
+                } else {
+                    // The last one carries a folded tail at most.
+                    EXPECT_LE(lengths[i], 2 * plan.block_size);
+                }
+                total += lengths[i];
+            }
+            EXPECT_EQ(total, length);
+        }
     }
-    ASSERT_EQ(statuses.size(), kCancelTaskCount);
-    for (size_t i = 0; i < cancel_task_id; ++i) {
-        EXPECT_EQ(statuses[i].s, TransferStatusEnum::COMPLETED);
+}
+
+// Under the cap nothing is rounded: blocks are not enlarged unasked.
+TEST(RdmaSlicePlanTest, BelowTheCapTheBlockIsTheConfiguredOne) {
+    constexpr uint64_t kBase = 65536;
+    for (uint64_t blocks = 1; blocks <= 32; ++blocks) {
+        const auto exact = planRdmaSlices(blocks * kBase, kBase, 64);
+        EXPECT_EQ(exact.block_size, kBase) << "blocks=" << blocks;
+        EXPECT_EQ(exact.count, blocks) << "blocks=" << blocks;
+
+        // One byte over is a tail far too short to post on its own, so it
+        // joins the slice before it instead of adding one.
+        const auto ragged = planRdmaSlices(blocks * kBase + 1, kBase, 64);
+        EXPECT_EQ(ragged.block_size, kBase) << "blocks=" << blocks;
+        EXPECT_EQ(ragged.count, blocks) << "blocks=" << blocks;
     }
-    EXPECT_EQ(statuses[cancel_task_id].s, TransferStatusEnum::CANCELED);
-    EXPECT_LE(statuses[cancel_task_id].transferred_bytes, kDataLength);
-    ASSERT_TRUE(client.freeBatch(batch).ok());
+}
 
-    EXPECT_TRUE(client.closeSegment(segment).ok());
-    EXPECT_TRUE(
-        client.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+// A tail under a quarter block joins the slice before it: one work request
+// and one completion saved, and the request still spread over as many
+// slices as its size deserves. Reducing the count before choosing the block
+// -- what this used to do -- would round the block up to 128 KB instead,
+// which both halves the slices and leaves the 8 KB tail on its own anyway.
+TEST(RdmaSlicePlanTest, AShortTailJoinsTheSliceBeforeIt) {
+    constexpr uint64_t kBase = 65536;
+    const uint64_t length = 8 * kBase + 8192;  // 520 KB
+
+    const auto plan = planRdmaSlices(length, kBase, 64);
+    EXPECT_EQ(plan.block_size, kBase);  // not widened
+    EXPECT_EQ(plan.count, 8u);          // not 9, and not 5
+
+    const auto lengths = walkPlan(plan, length);
+    ASSERT_EQ(lengths.size(), 8u);
+    EXPECT_EQ(lengths.back(), kBase + 8192);
+    for (size_t i = 0; i + 1 < lengths.size(); ++i)
+        EXPECT_EQ(lengths[i], kBase);
+}
+
+// A tail that is worth a slice of its own keeps one.
+TEST(RdmaSlicePlanTest, ALongTailKeepsItsOwnSlice) {
+    constexpr uint64_t kBase = 65536;
+    const uint64_t length = 8 * kBase + kBase / 2;  // half a block over
+
+    const auto plan = planRdmaSlices(length, kBase, 64);
+    EXPECT_EQ(plan.block_size, kBase);
+    EXPECT_EQ(plan.count, 9u);
+    EXPECT_EQ(walkPlan(plan, length).back(), kBase / 2);
+}
+
+// The ratio is the whole policy, so a caller can turn folding off.
+TEST(RdmaSlicePlanTest, AZeroRatioNeverFolds) {
+    constexpr uint64_t kBase = 65536;
+    const uint64_t length = 8 * kBase + 1;
+
+    const auto folded = planRdmaSlices(length, kBase, 64);
+    const auto plain = planRdmaSlices(length, kBase, 64, /*merge_ratio=*/0.0);
+    EXPECT_EQ(folded.count, 8u);
+    EXPECT_EQ(plain.count, 9u);
+    EXPECT_EQ(walkPlan(plain, length).back(), 1u);
+}
+
+// Folding never empties the plan: two slices whose tail is short become one
+// slice holding everything, not zero.
+TEST(RdmaSlicePlanTest, FoldingNeverDropsTheLastSlice) {
+    constexpr uint64_t kBase = 65536;
+    const auto plan = planRdmaSlices(kBase + 1, kBase, 64);
+    EXPECT_EQ(plan.count, 1u);
+    EXPECT_EQ(walkPlan(plan, kBase + 1).front(), kBase + 1);
+}
+
+// The regression: a 10 MB read asks for 64 slices of 160 KB, rounded up to
+// 192 KB, and 54 of those cover it. Asking for 64 anyway left ten empty.
+TEST(RdmaSlicePlanTest, RoundingUpTheBlockTakesTheSurplusOutOfTheCount) {
+    constexpr uint64_t kBase = 65536;
+    const auto plan = planRdmaSlices(10ull << 20, kBase, 64);
+    EXPECT_EQ(plan.block_size, 3 * kBase);  // 192 KB
+    EXPECT_EQ(plan.count, 54u);             // not 64
+
+    // The same shape one cap down, where writes and CUDA sources live.
+    const auto write = planRdmaSlices(3ull << 20, kBase, 32);
+    EXPECT_EQ(write.block_size, 2 * kBase);  // 128 KB
+    EXPECT_EQ(write.count, 24u);             // not 32
+}
+
+// Dividing evenly needs no rounding, so the count is the cap -- nothing was
+// wasted here before the change either.
+TEST(RdmaSlicePlanTest, ArequestThatDividesEvenlyUsesTheWholeCap) {
+    constexpr uint64_t kBase = 65536;
+    const auto plan = planRdmaSlices(6ull << 20, kBase, 32);
+    EXPECT_EQ(plan.block_size, 3 * kBase);  // 192 KB
+    EXPECT_EQ(plan.count, 32u);
+}
+
+// However large the request, the count stops at the cap and the block grows.
+TEST(RdmaSlicePlanTest, TheCapBoundsTheCountAndTheBlockGrowsInstead) {
+    constexpr uint64_t kBase = 65536;
+    const auto small = planRdmaSlices(1ull << 30, kBase, 32);
+    const auto large = planRdmaSlices(1ull << 30, kBase, 64);
+    EXPECT_LE(small.count, 32u);
+    EXPECT_LE(large.count, 64u);
+    EXPECT_GT(small.block_size, large.block_size);
+    EXPECT_EQ(small.block_size % kBase, 0u);
+    EXPECT_EQ(large.block_size % kBase, 0u);
+}
+
+// A zero-length request keeps its one slice; a zero cap or block is treated
+// as one rather than dividing by zero.
+TEST(RdmaSlicePlanTest, DegenerateInputsStayInRange) {
+    constexpr uint64_t kBase = 65536;
+    const auto empty = planRdmaSlices(0, kBase, 64);
+    EXPECT_EQ(empty.count, 1u);
+    EXPECT_EQ(empty.block_size, kBase);
+
+    const auto no_cap = planRdmaSlices(4096, kBase, 0);
+    EXPECT_EQ(no_cap.count, 1u);
+
+    const auto no_block = planRdmaSlices(4096, 0, 64);
+    EXPECT_GT(no_block.count, 0u);
+    EXPECT_LE(no_block.count, 64u);
+    EXPECT_EQ(walkPlan(no_block, 4096).size(), no_block.count);
+}
+
+// ibv_query_port_speed() exists only in rdma-core >= 62. It must be resolved
+// as an optional symbol: present -> non-null, absent -> null, and either way
+// the mandatory verbs are still there (an older libibverbs must not lose
+// RDMA over it). Compared against a direct dlsym so the expectation is
+// whatever this host's library actually has.
+TEST(RdmaContextPortSpeedTest, EffectiveSpeedVerbIsOptional) {
+    void* lib = dlopen("libibverbs.so.1", RTLD_NOW | RTLD_LOCAL);
+    if (!lib) GTEST_SKIP() << "libibverbs.so.1 not loadable";
+    const bool host_has_verb = dlsym(lib, "ibv_query_port_speed") != nullptr;
+    dlclose(lib);
+
+    const auto& sym = IbvLoader::Instance().sym();
+    EXPECT_EQ(sym.ibv_query_port_speed != nullptr, host_has_verb);
+    // Mandatory symbols resolve regardless of the optional one.
+    EXPECT_NE(sym.ibv_query_port_default, nullptr);
+    EXPECT_NE(sym.ibv_open_device, nullptr);
+}
+
+// Verbs stand-ins wired through RdmaContextTestPeer::verbs(). Plain function
+// pointers, so state lives in one static block.
+struct FakePortVerbs {
+    ibv_context native{};      // placeholder handle, never dereferenced
+    uint8_t active_speed = 0;  // what ibv_query_port reports
+    uint8_t active_width = 0;
+    ibv_port_state state = IBV_PORT_ACTIVE;
+    uint16_t lid = 0;
+    int gid_table_len = 8;
+    int query_port_rc = 0;
+    int query_port_calls = 0;
+    int query_port_fail_from = -1;  // fail that call onwards; -1 = never
+    ibv_gid gid{};
+    int expected_gid_index = 3;
+    int query_gid_rc = 0;
+    int query_gid_calls = 0;
+    uint64_t speed_100mbps = 0;  // what ibv_query_port_speed reports
+    int query_speed_rc = 0;
+    int query_speed_calls = 0;
+};
+FakePortVerbs fake_port;
+
+int fakeQueryPort(ibv_context* context, uint8_t, ibv_port_attr* attr) {
+    const int call = fake_port.query_port_calls++;
+    if (context != &fake_port.native) return EINVAL;
+    if (fake_port.query_port_rc) return fake_port.query_port_rc;
+    if (fake_port.query_port_fail_from >= 0 &&
+        call >= fake_port.query_port_fail_from)
+        return EIO;
+    *attr = {};
+    attr->state = fake_port.state;
+    attr->active_speed = fake_port.active_speed;
+    attr->active_width = fake_port.active_width;
+    attr->lid = fake_port.lid;
+    attr->gid_tbl_len = fake_port.gid_table_len;
+    return 0;
+}
+
+int fakeQueryGid(ibv_context* context, uint8_t, int gid_index, ibv_gid* gid) {
+    ++fake_port.query_gid_calls;
+    if (context != &fake_port.native ||
+        gid_index != fake_port.expected_gid_index)
+        return EINVAL;
+    if (fake_port.query_gid_rc) {
+        errno = fake_port.query_gid_rc;
+        return fake_port.query_gid_rc;
+    }
+    *gid = fake_port.gid;
+    return 0;
+}
+
+int fakeQueryPortSpeed(ibv_context* context, uint32_t, uint64_t* speed) {
+    ++fake_port.query_speed_calls;
+    if (context != &fake_port.native) return EINVAL;
+    if (fake_port.query_speed_rc) return fake_port.query_speed_rc;
+    *speed = fake_port.speed_100mbps;
+    return 0;
+}
+
+// A context whose port-attribute verbs are the fakes above, "opened" on the
+// placeholder device. Exercises refreshPortAttributes()/linkSpeedGbps()
+// exactly as the monitor thread does, without an RNIC.
+class RdmaContextFakeVerbsTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        fake_port = FakePortVerbs{};
+        fake_port.active_speed = 128;  // NDR
+        fake_port.active_width = 2;    // 4x -> 400 Gbps encoded
+        context_ = std::make_unique<RdmaContext>(transport_);
+        auto& verbs = RdmaContextTestPeer::verbs(*context_);
+        verbs.ibv_query_port_default = fakeQueryPort;
+        verbs.ibv_query_gid = fakeQueryGid;
+        verbs.ibv_query_port_speed = fakeQueryPortSpeed;
+        params_ = std::make_shared<RdmaParams>();
+        RdmaContextTestPeer::bindDevice(*context_, &fake_port.native, params_);
+    }
+
+    void TearDown() override {
+        // The context never owned the placeholder; keep its destructor away
+        // from it.
+        RdmaContextTestPeer::unbindDevice(*context_);
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<RdmaContext> context_;
+    std::shared_ptr<RdmaParams> params_;
+};
+
+TEST_F(RdmaContextFakeVerbsTest, EffectiveSpeedPreferredWhenVerbReportsIt) {
+    fake_port.speed_100mbps = 2000;  // LAG down to one 200G PF
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    EXPECT_EQ(fake_port.query_speed_calls, 1);
+}
+
+// A transient verb failure must not revert a degraded LAG to the higher
+// encoded rate: the last known effective speed is held until a query
+// succeeds again (a real recovery re-fires PORT_ACTIVE / SPEED_CHANGE).
+TEST_F(RdmaContextFakeVerbsTest, EffectiveSpeedHeldWhenVerbFails) {
+    fake_port.speed_100mbps = 2000;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    ASSERT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    fake_port.query_speed_rc = EIO;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    EXPECT_EQ(context_->effectiveSpeedQueryFailures(), 2u);
+    // Recovery at a new speed is picked up again.
+    fake_port.query_speed_rc = 0;
+    fake_port.speed_100mbps = 4000;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    EXPECT_EQ(context_->effectiveSpeedQueryFailures(), 2u);
+}
+
+// A verb that succeeds but reports 0 means "nothing to say", not a failure:
+// the encodings decide, as when the verb is absent.
+TEST_F(RdmaContextFakeVerbsTest, EncodedRateWhenVerbReportsZero) {
+    fake_port.speed_100mbps = 2000;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    ASSERT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    fake_port.speed_100mbps = 0;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    EXPECT_EQ(context_->effectiveSpeedQueryFailures(), 0u);
+}
+
+TEST_F(RdmaContextFakeVerbsTest, EncodedRateWhenVerbAbsent) {
+    fake_port.speed_100mbps = 2000;
+    RdmaContextTestPeer::verbs(*context_).ibv_query_port_speed = nullptr;
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    EXPECT_EQ(fake_port.query_speed_calls, 0);
+}
+
+TEST_F(RdmaContextFakeVerbsTest, RefreshSeesRenegotiatedLink) {
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    ASSERT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    fake_port.active_speed = 32;  // came back as EDR 4x
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 100.0);
+}
+
+TEST_F(RdmaContextFakeVerbsTest, RefreshFailsCleanlyWhenQueryPortFails) {
+    ASSERT_EQ(context_->refreshPortAttributes(), 0);
+    fake_port.query_port_rc = EIO;
+    fake_port.active_speed = 32;
+    EXPECT_EQ(context_->refreshPortAttributes(), -1);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);  // cached values kept
+}
+
+// ---- enable() over a whole stand-in RNIC ---------------------------------
+
+// Every verb enable() walks, with counters for what is currently held and a
+// switch to fail one step, so a test can cut enable() short anywhere and
+// assert that whatever it had already acquired was given back. The fds are
+// real: enable() puts the async fd and every completion-channel fd into an
+// epoll set.
+struct FakeRnic {
+    static constexpr int kChannels = 2;
+    static constexpr int kCqs = 8;
+    static constexpr const char* kName = "mc-fake-rnic-0";
+
+    ibv_device device{};
+    ibv_device* device_list[1] = {nullptr};
+    ibv_context native{};
+    ibv_pd pd{};
+    ibv_comp_channel channel[kChannels]{};
+    ibv_cq cq[kCqs]{};
+
+    // What the device reports.
+    int phys_port_cnt = 1;
+    ibv_port_state port_state = IBV_PORT_ACTIVE;
+    uint64_t effective_speed_100mbps = 0;
+
+    // Where to fail; false / -1 means "never".
+    bool fail_open_device = false;
+    bool fail_query_device = false;
+    bool no_valid_gid = false;  // every GID entry unreadable
+    bool fail_alloc_pd = false;
+    int fail_comp_channel_at = -1;  // index of the create call that fails
+    int fail_create_cq_at = -1;     // data CQs first, notification CQ last
+    int fail_query_port_from = -1;  // that call onwards
+
+    // Attempts, so a test can say how far enable() got.
+    int list_calls = 0;
+    int free_list_calls = 0;
+    int open_attempts = 0;
+    int alloc_pd_attempts = 0;
+    int channel_attempts = 0;
+    int cq_attempts = 0;
+    int query_port_calls = 0;
+    int query_speed_calls = 0;
+
+    // Held right now: every one must be back to zero once enable() has
+    // failed or disable() has run.
+    int devices_open = 0;
+    int pds_open = 0;
+    int channels_open = 0;
+    int cqs_open = 0;
+};
+FakeRnic fake_rnic;
+
+ibv_device** fakeGetDeviceList(int* num_devices) {
+    ++fake_rnic.list_calls;
+    fake_rnic.device_list[0] = &fake_rnic.device;
+    *num_devices = 1;
+    return fake_rnic.device_list;
+}
+
+void fakeFreeDeviceList(ibv_device**) { ++fake_rnic.free_list_calls; }
+
+const char* fakeGetDeviceName(ibv_device*) { return FakeRnic::kName; }
+
+ibv_context* fakeOpenDevice(ibv_device* device) {
+    ++fake_rnic.open_attempts;
+    if (fake_rnic.fail_open_device || device != &fake_rnic.device)
+        return nullptr;
+    ++fake_rnic.devices_open;
+    return &fake_rnic.native;
+}
+
+int fakeCloseDevice(ibv_context* context) {
+    if (context != &fake_rnic.native) return EINVAL;
+    --fake_rnic.devices_open;
+    return 0;
+}
+
+int fakeQueryDevice(ibv_context* context, ibv_device_attr* attr) {
+    if (fake_rnic.fail_query_device || context != &fake_rnic.native)
+        return EINVAL;
+    *attr = {};
+    attr->phys_port_cnt = fake_rnic.phys_port_cnt;
+    attr->max_cqe = 4096;
+    attr->max_cq = 64;
+    attr->max_sge = 8;
+    attr->max_qp_wr = 1024;
+    return 0;
+}
+
+int fakeRnicQueryPort(ibv_context* context, uint8_t, ibv_port_attr* attr) {
+    const int call = fake_rnic.query_port_calls++;
+    if (context != &fake_rnic.native) return EINVAL;
+    if (fake_rnic.fail_query_port_from >= 0 &&
+        call >= fake_rnic.fail_query_port_from)
+        return EIO;
+    *attr = {};
+    attr->state = fake_rnic.port_state;
+    attr->active_speed = 128;  // NDR
+    attr->active_width = 2;    // 4x -> 400 Gbps encoded
+    attr->active_mtu = IBV_MTU_1024;
+    attr->lid = 7;
+    attr->gid_tbl_len = 4;
+    return 0;
+}
+
+// One usable entry, index 0: IB type, non-zero, and with no netdev behind it
+// (the stand-in has no sysfs), which is what auto-select settles on.
+int fakeQueryGidEx(ibv_context* context, uint32_t, uint32_t gid_index,
+                   ibv_gid_entry* entry, uint32_t, size_t) {
+    if (fake_rnic.no_valid_gid || context != &fake_rnic.native ||
+        gid_index != 0)
+        return EINVAL;
+    *entry = {};
+    entry->gid_type = IBV_GID_TYPE_IB;
+    entry->gid.raw[15] = 1;
+    return 0;
+}
+
+int fakeRnicQueryGid(ibv_context* context, uint8_t, int index, ibv_gid* gid) {
+    if (fake_rnic.no_valid_gid || context != &fake_rnic.native || index != 0)
+        return EINVAL;
+    *gid = {};
+    gid->raw[15] = 1;
+    return 0;
+}
+
+ibv_pd* fakeAllocPd(ibv_context* context) {
+    ++fake_rnic.alloc_pd_attempts;
+    if (fake_rnic.fail_alloc_pd || context != &fake_rnic.native) return nullptr;
+    ++fake_rnic.pds_open;
+    return &fake_rnic.pd;
+}
+
+int fakeDeallocPd(ibv_pd* pd) {
+    if (pd != &fake_rnic.pd) return EINVAL;
+    --fake_rnic.pds_open;
+    return 0;
+}
+
+ibv_comp_channel* fakeCreateCompChannel(ibv_context* context) {
+    const int index = fake_rnic.channel_attempts++;
+    if (context != &fake_rnic.native || index >= FakeRnic::kChannels) {
+        return nullptr;
+    }
+    if (index == fake_rnic.fail_comp_channel_at) return nullptr;
+    ++fake_rnic.channels_open;
+    return &fake_rnic.channel[index];
+}
+
+int fakeDestroyCompChannel(ibv_comp_channel*) {
+    --fake_rnic.channels_open;
+    return 0;
+}
+
+ibv_cq* fakeCreateCq(ibv_context* context, int, void*, ibv_comp_channel*, int) {
+    const int index = fake_rnic.cq_attempts++;
+    if (context != &fake_rnic.native || index >= FakeRnic::kCqs) return nullptr;
+    if (index == fake_rnic.fail_create_cq_at) return nullptr;
+    ++fake_rnic.cqs_open;
+    return &fake_rnic.cq[index];
+}
+
+int fakeDestroyCq(ibv_cq*) {
+    --fake_rnic.cqs_open;
+    return 0;
+}
+
+int fakeRnicQueryPortSpeed(ibv_context* context, uint32_t, uint64_t* speed) {
+    ++fake_rnic.query_speed_calls;
+    if (context != &fake_rnic.native) return EINVAL;
+    *speed = fake_rnic.effective_speed_100mbps;
+    return 0;
+}
+
+// A context one call short of enable(), with the whole verbs table replaced.
+// The #3325 fix -- release everything already acquired when a later step
+// fails -- has no other way to be exercised without an RNIC.
+class RdmaContextEnableTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        fake_rnic = FakeRnic{};
+        async_fd_ = eventfd(0, 0);
+        ASSERT_GE(async_fd_, 0);
+        fake_rnic.native.async_fd = async_fd_;
+        fake_rnic.native.num_comp_vectors = 4;
+        for (int i = 0; i < FakeRnic::kChannels; ++i) {
+            channel_fd_[i] = eventfd(0, 0);
+            ASSERT_GE(channel_fd_[i], 0);
+            fake_rnic.channel[i].fd = channel_fd_[i];
+        }
+
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                            {"name":"mc-fake-rnic-0","type":0,"numa_node":0}]})")
+                        .ok());
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+
+        context_ = std::make_unique<RdmaContext>(transport_);
+        auto& verbs = RdmaContextTestPeer::verbs(*context_);
+        verbs.ibv_get_device_list = fakeGetDeviceList;
+        verbs.ibv_free_device_list = fakeFreeDeviceList;
+        verbs.ibv_get_device_name = fakeGetDeviceName;
+        verbs.ibv_open_device = fakeOpenDevice;
+        verbs.ibv_close_device = fakeCloseDevice;
+        verbs.ibv_query_device = fakeQueryDevice;
+        verbs.ibv_query_port_default = fakeRnicQueryPort;
+        verbs.ibv_query_gid = fakeRnicQueryGid;
+        verbs.ibv_query_gid_ex = fakeQueryGidEx;
+        verbs.ibv_query_port_speed = fakeRnicQueryPortSpeed;
+        verbs.ibv_alloc_pd = fakeAllocPd;
+        verbs.ibv_dealloc_pd = fakeDeallocPd;
+        verbs.ibv_create_comp_channel = fakeCreateCompChannel;
+        verbs.ibv_destroy_comp_channel = fakeDestroyCompChannel;
+        verbs.ibv_create_cq = fakeCreateCq;
+        verbs.ibv_destroy_cq = fakeDestroyCq;
+
+        params_ = std::make_shared<RdmaParams>();
+        params_->device.num_cq_list = 2;
+        params_->device.num_comp_channels = 1;
+        RdmaContextTestPeer::prepareForEnable(*context_, FakeRnic::kName,
+                                              params_);
+    }
+
+    void TearDown() override {
+        context_.reset();  // ~RdmaContext -> disable()
+        close(async_fd_);
+        for (int fd : channel_fd_)
+            if (fd >= 0) close(fd);
+    }
+
+    // The postcondition the #3325 fix is about, from both sides: the device
+    // holds nothing, and the context points at nothing.
+    void expectNothingHeld() {
+        EXPECT_EQ(fake_rnic.devices_open, 0);
+        EXPECT_EQ(fake_rnic.pds_open, 0);
+        EXPECT_EQ(fake_rnic.channels_open, 0);
+        EXPECT_EQ(fake_rnic.cqs_open, 0);
+        EXPECT_EQ(fake_rnic.free_list_calls, fake_rnic.list_calls);
+        EXPECT_EQ(context_->nativeContext(), nullptr);
+        EXPECT_EQ(context_->nativePD(), nullptr);
+        EXPECT_EQ(context_->eventFd(), -1);
+        EXPECT_EQ(RdmaContextTestPeer::compChannelCount(*context_), 0u);
+        EXPECT_EQ(RdmaContextTestPeer::cqCount(*context_), 0u);
+        EXPECT_EQ(context_->notifyCq(), nullptr);
+        EXPECT_EQ(context_->status(), RdmaContext::DEVICE_DISABLED);
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<RdmaContext> context_;
+    std::shared_ptr<RdmaParams> params_;
+    int async_fd_ = -1;
+    int channel_fd_[FakeRnic::kChannels] = {-1, -1};
+};
+
+TEST_F(RdmaContextEnableTest, EnableBuildsEverythingAndDisableGivesItBack) {
+    ASSERT_EQ(context_->enable(), 0);
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_ENABLED);
+    EXPECT_EQ(fake_rnic.devices_open, 1);
+    EXPECT_EQ(fake_rnic.pds_open, 1);
+    EXPECT_EQ(fake_rnic.channels_open, 1);
+    EXPECT_EQ(fake_rnic.cqs_open, 3);  // two data CQs plus the notification CQ
+    EXPECT_EQ(RdmaContextTestPeer::cqCount(*context_), 2u);
+    EXPECT_NE(context_->notifyCq(), nullptr);
+    EXPECT_GE(context_->eventFd(), 0);
+
+    ASSERT_EQ(context_->disable(), 0);
+    expectNothingHeld();
+}
+
+// Nothing is opened when the name does not match, and the device list is
+// still freed.
+TEST_F(RdmaContextEnableTest, UnknownDeviceNameOpensNothing) {
+    RdmaContextTestPeer::prepareForEnable(*context_, "mc-not-here", params_);
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.open_attempts, 0);
+}
+
+// A port outside the device's range is rejected after the device is open:
+// the scoped handle openDevice holds must close it on the way out.
+TEST_F(RdmaContextEnableTest, PortOutOfRangeClosesTheDeviceItOpened) {
+    params_->device.port = 2;  // the stand-in reports one physical port
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.open_attempts, 1);
+}
+
+// The device list is freed whether or not the open that follows it works.
+TEST_F(RdmaContextEnableTest, OpenDeviceFailureStillFreesTheDeviceList) {
+    fake_rnic.fail_open_device = true;
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.open_attempts, 1);
+    EXPECT_EQ(fake_rnic.alloc_pd_attempts, 0);
+}
+
+// Two more exits with the device already open, one before the port check and
+// one after it: the scoped handle has to close the device on both.
+TEST_F(RdmaContextEnableTest, QueryDeviceFailureClosesTheDevice) {
+    fake_rnic.fail_query_device = true;
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.open_attempts, 1);
+    EXPECT_EQ(fake_rnic.query_port_calls, 0);
+}
+
+TEST_F(RdmaContextEnableTest, NoUsableGidClosesTheDevice) {
+    fake_rnic.no_valid_gid =
+        true;  // auto-select scans the table and finds nothing
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.open_attempts, 1);
+    EXPECT_EQ(fake_rnic.alloc_pd_attempts, 0);
+}
+
+TEST_F(RdmaContextEnableTest, AllocPdFailureClosesTheDevice) {
+    fake_rnic.fail_alloc_pd = true;
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.alloc_pd_attempts, 1);
+}
+
+TEST_F(RdmaContextEnableTest, CompChannelFailureReleasesThePdAndTheDevice) {
+    params_->device.num_comp_channels = 2;
+    fake_rnic.fail_comp_channel_at = 1;  // the second one
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.channel_attempts, 2);
+}
+
+TEST_F(RdmaContextEnableTest, DataCqFailureReleasesTheChannelAndThePd) {
+    fake_rnic.fail_create_cq_at = 1;  // the second data CQ
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.cq_attempts, 2);
+}
+
+TEST_F(RdmaContextEnableTest, NotifyCqFailureReleasesTheDataCqs) {
+    fake_rnic.fail_create_cq_at = 2;  // after the two data CQs
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.cq_attempts, 3);
+}
+
+// The last step of enable() re-reads the port to decide ENABLED vs PAUSED.
+// Everything is built by then, so this is the failure point that releases
+// the most.
+TEST_F(RdmaContextEnableTest, FinalPortQueryFailureReleasesEverything) {
+    fake_rnic.fail_query_port_from = 1;  // openDevice's read is call 0
+    EXPECT_EQ(context_->enable(), -1);
+    expectNothingHeld();
+    EXPECT_EQ(fake_rnic.query_port_calls, 2);
+}
+
+// A port that is not ACTIVE at open is not a failure: everything is built and
+// the context waits in DEVICE_PAUSED for a PORT_ACTIVE event.
+TEST_F(RdmaContextEnableTest, PortThatIsNotActiveEnablesPaused) {
+    fake_rnic.port_state = IBV_PORT_DOWN;
+    ASSERT_EQ(context_->enable(), 0);
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_PAUSED);
+    EXPECT_EQ(fake_rnic.pds_open, 1);
+    EXPECT_EQ(fake_rnic.cqs_open, 3);
+    EXPECT_NE(context_->notifyCq(), nullptr);
+}
+
+// openDevice() seeds the link speed, so a context is never selected on the
+// encoded rate when the effective one is available -- the first transfer
+// does not have to wait for a monitor tick.
+TEST_F(RdmaContextEnableTest, OpenDeviceSeedsTheEffectiveSpeed) {
+    fake_rnic.effective_speed_100mbps = 2000;  // LAG down to one 200G member
+    ASSERT_EQ(context_->enable(), 0);
+    EXPECT_EQ(fake_rnic.query_speed_calls, 1);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+}
+
+TEST_F(RdmaContextEnableTest, OpenDeviceFallsBackToTheEncodedRate) {
+    fake_rnic.effective_speed_100mbps = 0;  // the verb has nothing to say
+    ASSERT_EQ(context_->enable(), 0);
+    EXPECT_EQ(fake_rnic.query_speed_calls, 1);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);  // NDR 4x encoded
+}
+
+// The whole runtime chain: an async event reaches Workers::applyContextEvent,
+// the context re-reads its (fake) port, and the selector is re-seeded only
+// when the speed actually changed -- with the device marked available again
+// on the new rate, not the old one.
+class RdmaContextLinkSpeedEventTest : public ::testing::Test {
+   protected:
+    static constexpr int kDev = 1;
+
+    void SetUp() override {
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        context_ = RdmaTransportTestPeer::contextSet(transport_)[kDev].get();
+
+        fake_port = FakePortVerbs{};
+        fake_port.active_speed = 128;
+        fake_port.active_width = 2;  // 400G
+        fake_port.lid = 1;
+        fake_port.gid.raw[15] = 1;
+        auto& verbs = RdmaContextTestPeer::verbs(*context_);
+        verbs.ibv_query_port_default = fakeQueryPort;
+        verbs.ibv_query_gid = fakeQueryGid;
+        verbs.ibv_query_port_speed = fakeQueryPortSpeed;
+        params_ = std::make_shared<RdmaParams>();
+        params_->device.gid_index = fake_port.expected_gid_index;
+        RdmaContextTestPeer::bindDevice(*context_, &fake_port.native, params_);
+        RdmaContextTestPeer::seedAddress(
+            *context_, "mc-absent-rnic-1", fake_port.lid,
+            fake_port.expected_gid_index, fake_port.gid,
+            RdmaContext::DEVICE_ENABLED);
+        metadata_ = std::make_shared<ControlService>("p2p", "", nullptr);
+        RdmaTransportTestPeer::bindMetadata(transport_, metadata_);
+        ASSERT_TRUE(transport_.setupLocalSegment().ok());
+
+        // Pretend init seeded it at 400G and it learned ~45 GB/s since.
+        ASSERT_EQ(context_->refreshPortAttributes(), 0);
+        ASSERT_TRUE(
+            selector_->setDeviceBandwidth(kDev, context_->linkSpeedGbps())
+                .ok());
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+        for (int i = 0; i < 64; ++i)
+            ASSERT_TRUE(
+                selector_->release(kDev, 1 << 20, (1 << 20) / 45e9).ok());
+        ASSERT_NEAR(selector_->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+    }
+
+    void TearDown() override { RdmaContextTestPeer::unbindDevice(*context_); }
+
+    ibv_async_event portActive() const {
+        ibv_async_event event{};
+        event.event_type = IBV_EVENT_PORT_ACTIVE;
+        event.element.port_num = context_->portNum();
+        return event;
+    }
+
+    // Device-scoped, so it names no port.
+    static ibv_async_event speedChange() {
+        ibv_async_event event{};
+        event.event_type =
+            static_cast<ibv_event_type>(kIbvEventDeviceSpeedChange);
+        return event;
+    }
+
+    void fire(const ibv_async_event& event) {
+        RdmaTransportTestPeer::applyContextEvent(*workers_, kDev, *context_,
+                                                 event);
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    RdmaContext* context_ = nullptr;
+    std::shared_ptr<RdmaParams> params_;
+    std::shared_ptr<ControlService> metadata_;
+};
+
+TEST_F(RdmaContextLinkSpeedEventTest,
+       PortActiveReseedsOnlyWhenTheSpeedChanged) {
+    // Same speed after the flap: keep what was learned.
+    fire(portActive());
+    EXPECT_NEAR(selector_->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+
+    // LAG lost a PF: the effective speed halves, the seed and clamp follow.
+    fake_port.speed_100mbps = 2000;
+    fire(portActive());
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    EXPECT_DOUBLE_EQ(selector_->getAggregateEwmaBandwidth(), 25e9);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+}
+
+// The re-read that decides whether to re-seed is the last step of bringing a
+// port back up, after the address refresh has already succeeded. Losing it
+// must not cost the device its recovery: no re-seed, but selectable again on
+// what is still known about the link.
+TEST_F(RdmaContextLinkSpeedEventTest, PortActiveRecoversWhenTheReReadFails) {
+    fake_port.speed_100mbps = 2000;  // a change the failed read cannot see
+    fake_port.query_port_calls = 0;
+    fake_port.query_port_fail_from = 1;  // the address refresh is call 0
+
+    fire(portActive());
+    EXPECT_EQ(fake_port.query_port_calls, 2);
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);  // last known kept
+    EXPECT_NEAR(selector_->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_ENABLED);
+}
+
+// A speed change with no link flap: re-query and re-seed, but leave
+// availability and the endpoints alone -- the port never went down.
+TEST_F(RdmaContextLinkSpeedEventTest,
+       SpeedChangeReseedsWithoutTouchingTheLink) {
+    fake_port.speed_100mbps = 2000;  // LAG down to one 200G member
+    fire(speedChange());
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 200.0);
+    EXPECT_DOUBLE_EQ(selector_->getAggregateEwmaBandwidth(), 25e9);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_ENABLED);
+}
+
+// The same event when nothing actually changed -- a spurious or duplicated
+// notification -- must not throw away what the EWMA has learned.
+TEST_F(RdmaContextLinkSpeedEventTest, SpeedChangeAtTheSameSpeedKeepsTheEwma) {
+    fake_port.query_port_calls = 0;
+    fire(speedChange());
+    EXPECT_EQ(fake_port.query_port_calls, 1);  // it did re-read
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    EXPECT_NEAR(selector_->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+}
+
+// A failed re-query keeps the last known speed, so there is nothing to
+// re-seed from and the learned estimate stands.
+TEST_F(RdmaContextLinkSpeedEventTest,
+       SpeedChangeWithAFailedReReadChangesNothing) {
+    fake_port.query_port_rc = EIO;
+    fake_port.query_port_calls = 0;
+    fire(speedChange());
+    EXPECT_EQ(fake_port.query_port_calls, 1);  // it tried
+    EXPECT_DOUBLE_EQ(context_->linkSpeedGbps(), 400.0);
+    EXPECT_NEAR(selector_->getAggregateEwmaBandwidth(), 45e9, 45e9 * 0.02);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+}
+
+// The complete address-refresh chain: a GID_CHANGE event re-queries both
+// address components, publishes them into the local segment descriptor, and
+// leaves the device available. All verbs are fakes, so no RNIC is required.
+class RdmaAddressRefreshEventTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        fake_port = FakePortVerbs{};
+        fake_port.active_speed = 128;
+        fake_port.active_width = 2;
+        fake_port.lid = kNewLid;
+        fake_port.gid.raw[15] = kNewGidByte;
+
+        topology_ = std::make_shared<Topology>();
+        ASSERT_TRUE(topology_
+                        ->parse(R"({"nics":[
+                            {"name":"mc-fake-rnic","type":0,"numa_node":0}]})")
+                        .ok());
+        RdmaTransportTestPeer::bindTopology(transport_, topology_);
+
+        metadata_ = std::make_shared<ControlService>("p2p", "", nullptr);
+        RdmaTransportTestPeer::bindMetadata(transport_, metadata_);
+
+        context_ = std::make_shared<RdmaContext>(transport_);
+        params_ = std::make_shared<RdmaParams>();
+        params_->device.port = kPort;
+        params_->device.gid_index = fake_port.expected_gid_index;
+        auto& verbs = RdmaContextTestPeer::verbs(*context_);
+        verbs.ibv_query_port_default = fakeQueryPort;
+        verbs.ibv_query_gid = fakeQueryGid;
+        verbs.ibv_query_port_speed = fakeQueryPortSpeed;
+        RdmaContextTestPeer::bindDevice(*context_, &fake_port.native, params_);
+
+        ibv_gid old_gid{};
+        old_gid.raw[15] = kOldGidByte;
+        RdmaContextTestPeer::seedAddress(*context_, kDeviceName, kOldLid,
+                                         fake_port.expected_gid_index, old_gid,
+                                         RdmaContext::DEVICE_ENABLED);
+        RdmaTransportTestPeer::bindContexts(transport_, {context_});
+
+        ASSERT_TRUE(
+            metadata_->segmentManager()
+                .updateLocal([&](SegmentDesc& segment) -> Status {
+                    segment.name = "local";
+                    segment.type = SegmentType::Memory;
+                    auto& devices =
+                        std::get<MemorySegmentDesc>(segment.detail).devices;
+                    DeviceDesc device;
+                    device.name = kDeviceName;
+                    device.lid = kOldLid;
+                    device.gid = context_->gid();
+                    devices.push_back(std::move(device));
+                    return Status::OK();
+                })
+                .ok());
+
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_NE(selector_, nullptr);
+        ASSERT_TRUE(selector_->isDeviceAvailable(kDev));
+    }
+
+    void TearDown() override {
+        workers_.reset();
+        RdmaTransportTestPeer::bindContexts(transport_, {});
+        RdmaContextTestPeer::unbindDevice(*context_);
+        context_.reset();
+    }
+
+    void fire(ibv_event_type type, int port = kPort) {
+        ibv_async_event event{};
+        event.event_type = type;
+        event.element.port_num = port;
+        RdmaTransportTestPeer::applyContextEvent(*workers_, kDev, *context_,
+                                                 event);
+    }
+
+    DeviceDesc publishedDevice() const {
+        auto local = metadata_->segmentManager().getLocal();
+        auto* device = local ? local->findDevice(kDeviceName) : nullptr;
+        return device ? *device : DeviceDesc{};
+    }
+
+    static constexpr int kDev = 0;
+    static constexpr uint8_t kPort = 1;
+    static constexpr uint16_t kOldLid = 7;
+    static constexpr uint16_t kNewLid = 9;
+    static constexpr uint8_t kOldGidByte = 0x11;
+    static constexpr uint8_t kNewGidByte = 0x22;
+    static constexpr const char* kDeviceName = "mc-fake-rnic";
+
+    RdmaTransport transport_;
+    std::shared_ptr<Topology> topology_;
+    std::shared_ptr<ControlService> metadata_;
+    std::shared_ptr<RdmaContext> context_;
+    std::shared_ptr<RdmaParams> params_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+};
+
+TEST_F(RdmaAddressRefreshEventTest, GidChangeRefreshesPublishedAddress) {
+    fire(IBV_EVENT_GID_CHANGE);
+
+    const auto address = context_->address();
+    EXPECT_EQ(address.lid, kNewLid);
+    EXPECT_EQ(address.gid_index, fake_port.expected_gid_index);
+    EXPECT_EQ(address.gid, "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:22");
+    const auto published = publishedDevice();
+    ASSERT_EQ(published.name, kDeviceName);
+    EXPECT_EQ(published.lid, address.lid);
+    EXPECT_EQ(published.gid, address.gid);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+}
+
+TEST_F(RdmaAddressRefreshEventTest, LidChangeRefreshesPublishedAddress) {
+    fake_port.gid.raw[15] = kOldGidByte;
+    fire(IBV_EVENT_LID_CHANGE);
+
+    const auto address = context_->address();
+    EXPECT_EQ(address.lid, kNewLid);
+    EXPECT_EQ(address.gid, "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:11");
+    const auto published = publishedDevice();
+    ASSERT_EQ(published.name, kDeviceName);
+    EXPECT_EQ(published.lid, kNewLid);
+}
+
+TEST_F(RdmaAddressRefreshEventTest, AddressEventForAnotherPortIsIgnored) {
+    const auto before = context_->address();
+
+    fire(IBV_EVENT_GID_CHANGE, kPort + 1);
+
+    const auto after = context_->address();
+    EXPECT_EQ(after.lid, before.lid);
+    EXPECT_EQ(after.gid, before.gid);
+    EXPECT_EQ(fake_port.query_gid_calls, 0);
+}
+
+TEST_F(RdmaAddressRefreshEventTest,
+       NonPausableContextSkipsAddressAndMetadataRefresh) {
+    ibv_gid old_gid{};
+    old_gid.raw[15] = kOldGidByte;
+    RdmaContextTestPeer::seedAddress(*context_, kDeviceName, kOldLid,
+                                     fake_port.expected_gid_index, old_gid,
+                                     RdmaContext::DEVICE_DISABLED);
+    const auto before = context_->address();
+
+    fire(IBV_EVENT_GID_CHANGE);
+
+    EXPECT_EQ(fake_port.query_gid_calls, 0);
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_DISABLED);
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+    const auto after = context_->address();
+    EXPECT_EQ(after.lid, before.lid);
+    EXPECT_EQ(after.gid, before.gid);
+    const auto published = publishedDevice();
+    EXPECT_EQ(published.lid, before.lid);
+    EXPECT_EQ(published.gid, before.gid);
+}
+
+TEST_F(RdmaAddressRefreshEventTest,
+       AddressChangeWhilePortDownKeepsNicUnavailable) {
+    fake_port.state = IBV_PORT_DOWN;
+    const auto before = context_->address();
+
+    fire(IBV_EVENT_GID_CHANGE);
+
+    const auto after = context_->address();
+    EXPECT_EQ(after.lid, before.lid);
+    EXPECT_EQ(after.gid, before.gid);
+    EXPECT_EQ(fake_port.query_gid_calls, 0);
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_PAUSED);
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+}
+
+TEST_F(RdmaAddressRefreshEventTest, RefreshFailureKeepsOldAddressAndPausesNic) {
+    fake_port.query_gid_rc = EIO;
+    const auto before = context_->address();
+
+    fire(IBV_EVENT_GID_CHANGE);
+
+    const auto after = context_->address();
+    EXPECT_EQ(after.lid, before.lid);
+    EXPECT_EQ(after.gid, before.gid);
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_PAUSED);
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+    const auto published = publishedDevice();
+    ASSERT_EQ(published.name, kDeviceName);
+    EXPECT_EQ(published.lid, before.lid);
+    EXPECT_EQ(published.gid, before.gid);
+}
+
+TEST_F(RdmaAddressRefreshEventTest, PortActivePublishesInitiallyMissingNic) {
+    // The port was down during setupLocalSegment(), so this NIC was omitted.
+    // Its hardware address did not change while down; publication is still
+    // required before it can be made selectable.
+    fake_port.lid = kOldLid;
+    fake_port.gid = {};
+    fake_port.gid.raw[15] = kOldGidByte;
+    ASSERT_TRUE(
+        metadata_->segmentManager()
+            .updateLocal([&](SegmentDesc& segment) -> Status {
+                std::get<MemorySegmentDesc>(segment.detail).devices.clear();
+                return Status::OK();
+            })
+            .ok());
+    context_->pause();
+    ASSERT_TRUE(selector_->setDeviceAvailable(kDev, false).ok());
+
+    fire(IBV_EVENT_PORT_ACTIVE);
+
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_ENABLED);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+    const auto published = publishedDevice();
+    ASSERT_EQ(published.name, kDeviceName);
+    EXPECT_EQ(published.lid, kOldLid);
+    EXPECT_EQ(published.gid, context_->address().gid);
+}
+
+TEST_F(RdmaAddressRefreshEventTest, PortActiveRefreshesBeforeReenable) {
+    context_->pause();
+    ASSERT_TRUE(selector_->setDeviceAvailable(kDev, false).ok());
+
+    fire(IBV_EVENT_PORT_ACTIVE);
+
+    EXPECT_EQ(context_->status(), RdmaContext::DEVICE_ENABLED);
+    EXPECT_TRUE(selector_->isDeviceAvailable(kDev));
+    EXPECT_EQ(context_->address().lid, kNewLid);
+    EXPECT_EQ(publishedDevice().gid, context_->address().gid);
+}
+
+// A slice that hits the software timeout turns terminal here, not on the CQ,
+// and its flush completion is not guaranteed to be polled, so the timeout
+// path must return the selector's inflight charge itself.
+class RdmaWorkersTimeoutTest : public ::testing::Test {
+   protected:
+    static constexpr int kDev = 1;
+    static constexpr uint64_t kLen = 1 << 20;
+
+    void SetUp() override {
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        Topology::MemEntry mem;
+        mem.name = "cpu:0";
+        mem.type = Topology::MEM_HOST;
+        mem.numa_node = 0;
+        mem.device_list[0].push_back(1);
+        topology->mem_list_.push_back(mem);
+
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+
+        // Charge the slice to the NIC exactly as selectOptimalDevice() does.
+        task_ = RdmaTaskStorage::Get().allocate();
+        task_->num_slices = 1;
+        task_->status_word = PENDING;
+        task_->first_error = PENDING;
+        task_->ref();  // the batch's reference
+        task_->ref();  // the slice's reference, dropped by updateSliceStatus()
+        slice_ = RdmaSliceStorage::Get().allocate();
+        slice_->task = task_;
+        slice_->length = kLen;
+        slice_->word = PENDING;
+        slice_->enqueue_ts = 0;  // enqueued at t=0
+        slice_->rail_monitor = nullptr;
+        int chosen = -1;
+        ASSERT_TRUE(selector_->allocate(kLen, "cpu:0", chosen).ok());
+        ASSERT_EQ(chosen, kDev);
+        slice_->source_dev_id = chosen;
+        slice_->charged_dev = chosen;
+        slice_->counted_lane = 0;  // as Workers::submit() marks it
+        ASSERT_EQ(selector_->getInflightBytes(kDev), kLen);
+
+        ctx_.inflight_slice_set.insert(slice_);
+        RdmaTransportTestPeer::setSliceTimeout(*workers_, 1'000'000);  // 1 ms
+    }
+
+    void TearDown() override {
+        if (slice_) RdmaSliceStorage::Get().deallocate(slice_);
+        if (task_) task_->deref();  // drops the batch's reference; frees it
+    }
+
+    void expire() {
+        RdmaTransportTestPeer::expireTimedOutSlices(*workers_, ctx_,
+                                                    /*now_ns=*/2'000'000);
+    }
+
+    void expectTimedOutAndReleased() {
+        EXPECT_EQ(slice_->word, TIMEOUT);
+        EXPECT_TRUE(ctx_.inflight_slice_set.empty());
+        EXPECT_EQ(slice_->charged_dev, -1);
+        EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    RdmaTask* task_ = nullptr;
+    RdmaSlice* slice_ = nullptr;
+    RdmaTransportTestPeer::WorkerContext ctx_;
+};
+
+TEST_F(RdmaWorkersTimeoutTest, EndpointGoneReleasesSelectorInflightCharge) {
+    slice_->ep_weak_ptr.reset();  // endpoint already gone
+    ctx_.inflight_slices.store(1);
+
+    expire();
+
+    expectTimedOutAndReleased();
+    EXPECT_EQ(ctx_.inflight_slices.load(), 0);
+}
+
+// The slice's endpoint is alive but no longer holds it (a neighbour's retry
+// popped it with PENDING and its count), so acknowledge() sweeps nothing;
+// the timeout path still has to fail it and return its charge.
+TEST_F(RdmaWorkersTimeoutTest, NotOnQueueStillReleasesSelectorInflightCharge) {
+    auto endpoint = std::make_shared<RdmaEndPoint>();  // never constructed
+    slice_->ep_weak_ptr = endpoint;
+    slice_->qp_index = 0;
+    ctx_.inflight_slices.store(0);  // already dropped with the neighbour's
+
+    expire();
+
+    expectTimedOutAndReleased();
+    EXPECT_EQ(ctx_.inflight_slices.load(), 0);
+}
+
+// The selector charges every slice when it is allocated, before it reaches a
+// worker queue, so a NIC's inflight bytes already cover the slices being
+// ordered. What actually precedes them is what the NIC owes minus this
+// batch; each slice then also waits for the ones ordered ahead of it.
+class RdmaWorkersArbitrationTest : public ::testing::Test {
+   protected:
+    static constexpr int kDev = 0;
+    static constexpr uint64_t kNow = 1'000'000'000;
+
+    void SetUp() override {
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(
+            topology
+                ->parse(
+                    R"({"nics":[{"name":"mc-absent-rnic-0","type":0,"numa_node":0}]})")
+                .ok());
+        Topology::MemEntry mem;
+        mem.name = "cpu:0";
+        mem.type = Topology::MEM_HOST;
+        mem.numa_node = 0;
+        mem.device_list[0].push_back(kDev);
+        topology->mem_list_.push_back(mem);
+
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+
+        // Pin the transmit estimate at exactly 1 GB/s, so one byte of
+        // queueing is one nanosecond of predicted time: one metered interval
+        // that moved 1 MiB in 1 MiB nanoseconds.
+        auto params = selector_->getSchedulingParams();
+        params.transmit_bandwidth_learning_rate = 0.0;  // adopt outright
+        params.transmit_meter_interval_ns = 0;          // sample on demand
+        selector_->setSchedulingParams(params);
+        ASSERT_TRUE(selector_->setDeviceBandwidth(kDev, 25.0).ok());
+        selector_->notePosted(kDev, 1 << 20, kNow);
+        selector_->maybeSampleTransmit(kDev, kNow);
+        selector_->notePostEnded(kDev, 1 << 20, kNow + (1 << 20));
+        selector_->noteCompleted(kDev, 1 << 20);
+        selector_->maybeSampleTransmit(kDev, kNow + (1 << 20));
+        ASSERT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+        ASSERT_EQ(selector_->getPostedBytes(kDev), 0u);
+    }
+
+    void TearDown() override {
+        for (auto* slice : slices_) RdmaSliceStorage::Get().deallocate(slice);
+        for (auto* task : tasks_) task->deref();
+    }
+
+    // A slice of `length` bytes due `window_ns` from kNow, charged to the NIC
+    // by the selector exactly as selectOptimalDevice() charges it.
+    RdmaSlice* makeSlice(uint64_t length, uint64_t window_ns) {
+        auto* task = RdmaTaskStorage::Get().allocate();
+        task->num_slices = 1;
+        task->status_word = PENDING;
+        task->first_error = PENDING;
+        task->ref();  // the batch's reference, dropped in TearDown
+        task->request.deadline_ns = kNow + window_ns;
+        auto* slice = RdmaSliceStorage::Get().allocate();
+        slice->task = task;
+        slice->length = length;
+        slice->word = PENDING;
+        slice->rail_monitor = nullptr;
+        int chosen = -1;
+        EXPECT_TRUE(selector_->allocate(length, "cpu:0", chosen).ok());
+        EXPECT_EQ(chosen, kDev);
+        slice->source_dev_id = chosen;
+        slice->charged_dev = chosen;
+        tasks_.push_back(task);
+        slices_.push_back(slice);
+        return slice;
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    std::vector<RdmaTask*> tasks_;
+    std::vector<RdmaSlice*> slices_;
+};
+
+TEST_F(RdmaWorkersArbitrationTest, QueueAheadExcludesTheSlicesBeingOrdered) {
+    auto* big = makeSlice(40'000, 200'000);    // 40us of a 200us window: 0.20
+    auto* small = makeSlice(15'000, 100'000);  // 15us of a 100us window: 0.15
+    // Charged to the NIC by the selector, but not yet handed to hardware.
+    ASSERT_EQ(selector_->getInflightBytes(kDev), 55'000u);
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 0u);
+
+    std::vector<RdmaSlice*> slices{small, big};
+    RdmaTransportTestPeer::orderByDeadline(*workers_, slices, kDev, kNow);
+
+    // The NIC has nothing to move yet, so `big` is simply the more urgent of
+    // the two. Reading the allocation charge as queueing would count the
+    // batch's own 55'000 bytes and put `small`'s tighter window on top
+    // instead (0.70 vs 0.48).
+    EXPECT_EQ(slices[0], big);
+    EXPECT_EQ(slices[1], small);
+}
+
+TEST_F(RdmaWorkersArbitrationTest, QueueAheadCountsWorkOutsideTheBatch) {
+    auto* big = makeSlice(40'000, 200'000);
+    auto* small = makeSlice(15'000, 100'000);
+    // Another batch's slices, already posted to this NIC: 200us of work
+    // these two really do wait behind.
+    selector_->notePosted(kDev, 200'000, kNow);
+
+    std::vector<RdmaSlice*> slices{big, small};
+    RdmaTransportTestPeer::orderByDeadline(*workers_, slices, kDev, kNow);
+
+    // Behind it `small`'s 100us window is already gone (2.15) while `big`'s
+    // 200us one is not (1.20), so the order flips.
+    EXPECT_EQ(slices[0], small);
+    EXPECT_EQ(slices[1], big);
+    selector_->notePostEnded(kDev, 200'000, kNow);
+}
+
+// Two RDMA NICs, both reachable from the host buffer, and a Workers whose
+// selector is set to adopt every selection sample outright.
+class RdmaWorkersChargeTest : public ::testing::Test {
+   protected:
+    static constexpr uint64_t kLen = 1 << 20;
+    static constexpr uint64_t kNow = 1'000'000'000;
+
+    void SetUp() override {
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                        {"name":"mc-absent-rnic-0","type":0,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        Topology::MemEntry mem;
+        mem.name = "cpu:0";
+        mem.type = Topology::MEM_HOST;
+        mem.numa_node = 0;
+        mem.device_list[0].push_back(0);
+        mem.device_list[0].push_back(1);
+        topology->mem_list_.push_back(mem);
+
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        auto params = selector_->getSchedulingParams();
+        params.bandwidth_learning_rate = 0.0;  // adopt the sample
+        selector_->setSchedulingParams(params);
+        for (int dev : {0, 1}) {
+            ASSERT_TRUE(selector_->setDeviceAvailable(dev, true).ok());
+            ASSERT_TRUE(selector_->setDeviceBandwidth(dev, 25.0).ok());
+        }
+
+        task_ = RdmaTaskStorage::Get().allocate();
+        task_->num_slices = 1;
+        task_->status_word = PENDING;
+        task_->first_error = PENDING;
+        task_->ref();
+        slice_ = RdmaSliceStorage::Get().allocate();
+        slice_->task = task_;
+        slice_->length = kLen;
+        slice_->word = PENDING;
+        slice_->rail_monitor = nullptr;
+        // Allocated on NIC 0, as submitTransferTasks charges it.
+        int chosen = -1;
+        ASSERT_TRUE(
+            selector_->allocate(kLen, "cpu:0", chosen, PRIO_HIGH, 1ULL << 0)
+                .ok());
+        ASSERT_EQ(chosen, 0);
+        slice_->source_dev_id = chosen;
+        slice_->charged_dev = chosen;
+        ASSERT_EQ(selector_->getInflightBytes(0), kLen);
+    }
+
+    void TearDown() override {
+        RdmaSliceStorage::Get().deallocate(slice_);
+        task_->deref();
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    RdmaTask* task_ = nullptr;
+    RdmaSlice* slice_ = nullptr;
+};
+
+// The CQ error path returns a slice's charge before re-submitting it, and
+// the retry picks its device again. Without a fresh charge the NIC's
+// inflight bytes miss the retry entirely and its completion teaches neither
+// estimate, because the release is a no-op on an uncharged slice.
+TEST_F(RdmaWorkersChargeTest, RetryIsRechargedAndStillLearns) {
+    // The error path hands the charge back and re-submits.
+    RdmaTransportTestPeer::releaseSliceQuota(*workers_, slice_, kNow, 0.0);
+    ASSERT_EQ(slice_->charged_dev, -1);
+    ASSERT_EQ(selector_->getInflightBytes(0), 0u);
+
+    // The retry settles on the fallback NIC.
+    RdmaTransportTestPeer::rechargeSlice(*workers_, slice_, 1);
+    slice_->source_dev_id = 1;  // as selectFallbackDevice does next
+    EXPECT_EQ(slice_->charged_dev, 1);
+    EXPECT_EQ(selector_->getInflightBytes(1), kLen);
+    EXPECT_EQ(selector_->getInflightBytes(0), 0u);
+
+    // Its completion returns the charge and teaches the selector the rate
+    // it saw. Without the recharge above the release would be a no-op on an
+    // uncharged slice: the bytes would stay charged to nobody and the
+    // sample would be lost.
+    const double before = selector_->getAggregateEwmaBandwidth();
+    RdmaTransportTestPeer::releaseSliceQuota(*workers_, slice_, kNow + kLen,
+                                             kLen / 5e8);
+    EXPECT_EQ(selector_->getInflightBytes(1), 0u);
+    // Device 0 is untaught; device 1 adopted 0.5 GB/s in place of its seed.
+    EXPECT_NEAR(selector_->getAggregateEwmaBandwidth(),
+                before - 3.125e9 + 0.5e9, 1.0);
+}
+
+// A first attempt that falls back to another NIC is still charged to the
+// one the allocator picked. The charge moves with the routing: the fallback
+// NIC is charged first, then the original is paid back, so a release racing
+// in between finds one of them on record and never both.
+TEST_F(RdmaWorkersChargeTest, FallbackMovesTheChargeToTheNicItPostsOn) {
+    RdmaTransportTestPeer::rechargeSlice(*workers_, slice_, 1);
+    slice_->source_dev_id = 1;
+
+    EXPECT_EQ(slice_->charged_dev, 1);
+    EXPECT_EQ(selector_->getInflightBytes(0), 0u);
+    EXPECT_EQ(selector_->getInflightBytes(1), kLen);
+
+    RdmaTransportTestPeer::releaseSliceQuota(*workers_, slice_, kNow, 0.0);
+    EXPECT_EQ(slice_->charged_dev, -1);
+    EXPECT_EQ(selector_->getInflightBytes(0), 0u);
+    EXPECT_EQ(selector_->getInflightBytes(1), 0u);
+}
+
+// A device the selector does not track cannot be charged. The slice keeps
+// the charge it has rather than ending up charged to nobody, so the release
+// still balances the NIC that was charged and nothing underflows.
+TEST_F(RdmaWorkersChargeTest, ChargeOnAnUntrackedDeviceKeepsTheOldOne) {
+    RdmaTransportTestPeer::rechargeSlice(*workers_, slice_, 999);
+
+    EXPECT_EQ(slice_->charged_dev, 0);
+    EXPECT_EQ(selector_->getInflightBytes(0), kLen);
+
+    RdmaTransportTestPeer::releaseSliceQuota(*workers_, slice_, kNow, 0.0);
+    EXPECT_EQ(slice_->charged_dev, -1);
+    EXPECT_EQ(selector_->getInflightBytes(0), 0u);
+}
+
+// With qp_pools several worker lanes share a queue pair, so the lane that
+// sweeps a slice off it is often not the lane that enqueued it. The sweep
+// must give the accounting back to the owner: its set entry, its place in
+// its inflight count, and its selector charge.
+TEST(RdmaWorkersOwnershipTest, SweepByAnotherLaneIsRoutedToTheOwner) {
+    constexpr int kDev = 1;
+    constexpr uint64_t kLen = 1 << 20;
+    auto topology = std::make_shared<Topology>();
+    ASSERT_TRUE(topology
+                    ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                    .ok());
+    Topology::MemEntry mem;
+    mem.name = "cpu:0";
+    mem.type = Topology::MEM_HOST;
+    mem.numa_node = 0;
+    mem.device_list[0].push_back(kDev);
+    topology->mem_list_.push_back(mem);
+
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport), 0u);
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+    auto* selector = workers->getDeviceSelector();
+    ASSERT_TRUE(selector->setDeviceAvailable(kDev, true).ok());
+    RdmaTransportTestPeer::makeWorkerContexts(*workers, 2);
+    auto& lane_a = RdmaTransportTestPeer::workerContext(*workers, 0);
+    auto& lane_b = RdmaTransportTestPeer::workerContext(*workers, 1);
+
+    // Lane B enqueued and posted the slice.
+    auto* task = RdmaTaskStorage::Get().allocate();
+    task->num_slices = 1;
+    task->status_word = PENDING;
+    task->first_error = PENDING;
+    task->ref();
+    auto* slice = RdmaSliceStorage::Get().allocate();
+    slice->task = task;
+    slice->length = kLen;
+    slice->word = PENDING;
+    slice->rail_monitor = nullptr;
+    slice->owner_worker = 1;
+    slice->counted_lane = 1;  // as Workers::submit() marks it
+    int chosen = -1;
+    ASSERT_TRUE(selector->allocate(kLen, "cpu:0", chosen).ok());
+    slice->source_dev_id = chosen;
+    slice->charged_dev = chosen;
+    RdmaTransportTestPeer::notePostedSlice(*workers, slice);
+    lane_b.inflight_slice_set.insert(slice);
+    lane_b.inflight_slices.store(1);
+    // Lane A still holds an entry from an earlier attempt of the same slice
+    // (a retry moved it to lane B before A's set was drained).
+    lane_a.inflight_slice_set.insert(slice);
+    ASSERT_EQ(selector->getInflightBytes(kDev), kLen);
+    ASSERT_EQ(selector->getPostedBytes(kDev), kLen);
+
+    // Lane A sweeps it off the shared queue pair.
+    RdmaTransportTestPeer::retireSweptSlice(*workers, lane_a, slice,
+                                            getCurrentTimeInNano());
+
+    EXPECT_EQ(lane_a.inflight_slices.load(), 0);  // not lane A's to discount
+    EXPECT_EQ(lane_b.inflight_slices.load(), 0);
+    // A took out its own stale entry; B's is handed over, not touched.
+    EXPECT_TRUE(lane_a.inflight_slice_set.empty());
+    EXPECT_EQ(lane_b.inflight_slice_set.count(slice), 1u);  // owner erases it
+    EXPECT_EQ(selector->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector->getPostedBytes(kDev), 0u);
+
+    // ...on its own next pass.
+    RdmaTransportTestPeer::drainReclaimed(*workers, lane_b);
+    EXPECT_TRUE(lane_b.inflight_slice_set.empty());
+
+    RdmaTransportTestPeer::destroyWorkerContexts(*workers);
+    RdmaSliceStorage::Get().deallocate(slice);
+    task->deref();
+}
+
+// What the completion path owes the NIC's accounting, driven with a
+// synthesized work completion: a successful one hands back the slice's
+// charge and its place in the backlog, then feeds the meter the bytes it
+// moved. An unsuccessful one returns the same accounting but teaches
+// nothing -- a flush burst must not drag the estimate down.
+class RdmaWorkersCompletionTest : public ::testing::Test {
+   protected:
+    static constexpr int kDev = 1;
+    static constexpr uint64_t kLen = 1 << 20;
+    static constexpr uint64_t kNow = 1'000'000'000;
+
+    void SetUp() override {
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        Topology::MemEntry mem;
+        mem.name = "cpu:0";
+        mem.type = Topology::MEM_HOST;
+        mem.numa_node = 0;
+        mem.device_list[0].push_back(kDev);
+        topology->mem_list_.push_back(mem);
+
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+        auto params = selector_->getSchedulingParams();
+        params.transmit_bandwidth_learning_rate = 0.0;  // adopt outright
+        params.transmit_meter_interval_ns = 0;          // sample on demand
+        selector_->setSchedulingParams(params);
+        ASSERT_TRUE(selector_->setDeviceBandwidth(kDev, 25.0).ok());
+
+        task_ = RdmaTaskStorage::Get().allocate();
+        task_->num_slices = 1;
+        task_->status_word = PENDING;
+        task_->first_error = PENDING;
+        task_->ref();  // the batch's reference
+        task_->ref();  // the slice's, dropped when it turns terminal
+        slice_ = RdmaSliceStorage::Get().allocate();
+        slice_->task = task_;
+        slice_->length = kLen;
+        slice_->word = PENDING;
+        slice_->rail_monitor = nullptr;
+        // Queued for a while before it was posted: the busy stretch must
+        // start at submit_ts, not enqueue_ts.
+        slice_->enqueue_ts = kNow - kLen;
+        slice_->submit_ts = kNow;
+        int chosen = -1;
+        ASSERT_TRUE(selector_->allocate(kLen, "cpu:0", chosen).ok());
+        ASSERT_EQ(chosen, kDev);
+        slice_->source_dev_id = chosen;
+        slice_->charged_dev = chosen;
+        // Posted to the hardware, and its endpoint is still around (never
+        // constructed, so acknowledge() sweeps nothing).
+        endpoint_ = std::make_shared<RdmaEndPoint>();
+        slice_->ep_weak_ptr = endpoint_;
+        RdmaTransportTestPeer::notePostedSlice(*workers_, slice_);
+        ASSERT_EQ(selector_->getPostedBytes(kDev), kLen);
+        // The meter's interval opens with the NIC holding this backlog.
+        selector_->maybeSampleTransmit(kDev, kNow);
+    }
+
+    void TearDown() override {
+        for (auto* slice : extra_slices_)
+            RdmaSliceStorage::Get().deallocate(slice);
+        for (auto* task : extra_tasks_) releaseTask(task);
+        if (slice_) RdmaSliceStorage::Get().deallocate(slice_);
+        if (task_) releaseTask(task_);
+    }
+
+    // The endpoint is never constructed, so acknowledge() sweeps nothing
+    // and a slice completed here never turns terminal; only the cancel
+    // paths drop the slice's reference. Drop whatever is left.
+    static void releaseTask(RdmaTask* task) {
+        for (int n = task->ref_count.load(); n > 0; --n) task->deref();
+    }
+
+    // Another slice on the same NIC, charged and posted at `submit_ts` the
+    // way asyncPostSend does it.
+    RdmaSlice* makeSlice(uint64_t submit_ts) {
+        auto* task = RdmaTaskStorage::Get().allocate();
+        task->num_slices = 1;
+        task->status_word = PENDING;
+        task->first_error = PENDING;
+        task->ref();  // the batch's reference
+        task->ref();  // the slice's, dropped when it turns terminal
+        auto* slice = RdmaSliceStorage::Get().allocate();
+        slice->task = task;
+        slice->length = kLen;
+        slice->word = PENDING;
+        slice->rail_monitor = nullptr;
+        slice->enqueue_ts = submit_ts - kLen;
+        slice->submit_ts = submit_ts;
+        int chosen = -1;
+        EXPECT_TRUE(selector_->allocate(kLen, "cpu:0", chosen).ok());
+        slice->source_dev_id = chosen;
+        slice->charged_dev = chosen;
+        slice->ep_weak_ptr = endpoint_;
+        RdmaTransportTestPeer::notePostedSlice(*workers_, slice);
+        extra_tasks_.push_back(task);
+        extra_slices_.push_back(slice);
+        return slice;
+    }
+
+    void completeAt(RdmaSlice* slice, ibv_wc_status status, uint64_t poll_ts,
+                    bool last_in_pass = true) {
+        ibv_wc wc{};
+        wc.wr_id = reinterpret_cast<uint64_t>(slice);
+        wc.status = status;
+        RdmaTransportTestPeer::handleCompletion(
+            *workers_, ctx_, *RdmaTransportTestPeer::contextSet(transport_)[0],
+            wc, poll_ts, last_in_pass);
+    }
+
+    void complete(ibv_wc_status status) {
+        completeAt(slice_, status, kNow + kLen);  // one byte per nanosecond
+    }
+
+    RdmaTransport transport_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    RdmaTask* task_ = nullptr;
+    RdmaSlice* slice_ = nullptr;
+    std::shared_ptr<RdmaEndPoint> endpoint_;
+    RdmaTransportTestPeer::WorkerContext ctx_;
+    std::vector<RdmaTask*> extra_tasks_;
+    std::vector<RdmaSlice*> extra_slices_;
+};
+
+// One poll pass stamps every completion it reaps with the same timestamp.
+// Sampled at each of them, the first would divide its own bytes by the
+// busy time of the whole group, and the rest -- same timestamp, no later
+// than the baseline it just moved -- would be ignored: 0.5 GB/s for a
+// link that moved 2 MiB in 2 MiB ns. The pass samples once, at its end.
+TEST_F(RdmaWorkersCompletionTest, OnlyTheLastCompletionOfAPassSamples) {
+    auto* second = makeSlice(kNow);  // same burst: 2 MiB posted at kNow
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 2 * kLen);
+
+    completeAt(slice_, IBV_WC_SUCCESS, kNow + 2 * kLen, /*last_in_pass=*/false);
+    completeAt(second, IBV_WC_SUCCESS, kNow + 2 * kLen, /*last_in_pass=*/true);
+
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+TEST_F(RdmaWorkersCompletionTest, SuccessFeedsTheMeter) {
+    complete(IBV_WC_SUCCESS);
+
+    EXPECT_EQ(slice_->charged_dev, -1);
+    EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// The workers' half of the busy-time meter. Which stretches get charged for
+// the bytes is decided by the timestamps this layer hands down -- the
+// slice's submit_ts when it reaches the hardware, the poll timestamp when it
+// leaves -- and nothing else pins that wiring. Two bursts far apart, each
+// moved at one byte per nanosecond, have to read as one byte per nanosecond:
+// the wait between them is the NIC having nothing to do, not a slow link.
+TEST_F(RdmaWorkersCompletionTest, IdleBetweenBurstsIsNotChargedToTheLink) {
+    complete(IBV_WC_SUCCESS);  // kNow -> kNow + kLen
+    ASSERT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 0u);  // the NIC goes idle
+
+    // The next burst starts ten times its own wire time later.
+    const uint64_t start = kNow + 10 * kLen;
+    auto* second = makeSlice(start);
+    completeAt(second, IBV_WC_SUCCESS, start + kLen);
+
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// A slice that fails carries no wire time to learn from, but it does end a
+// busy stretch: the meter must not later charge its bytes-less span to the
+// next sample.
+TEST_F(RdmaWorkersCompletionTest, AFailedSliceEndsItsStretchWithoutTeaching) {
+    task_->cancel_requested.store(true);  // stop short of a re-submit
+    complete(IBV_WC_RETRY_EXC_ERR);
+    ASSERT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);  // seed
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 0u);
+
+    // The failure abandoned the meter's interval: the next completion only
+    // rebuilds the baselines, and its busy time -- not the failed slice's --
+    // is what the completion after that divides its bytes into.
+    const uint64_t start = kNow + 10 * kLen;
+    auto* second = makeSlice(start);
+    completeAt(second, IBV_WC_SUCCESS, start + kLen);
+    ASSERT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);
+
+    auto* third = makeSlice(start + kLen);
+    completeAt(third, IBV_WC_SUCCESS, start + 2 * kLen);  // one byte per ns
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// A slice resolved before its completion is polled -- timed out through a
+// stale entry on another lane, or cancelled by a teardown -- was re-counted
+// here when it was re-queued, and nothing but its completion is left to
+// take it out of this lane's count again.
+TEST_F(RdmaWorkersCompletionTest, ResolvedSliceStillLeavesTheLaneCount) {
+    slice_->word = TIMEOUT;
+    slice_->counted_lane = 0;
+    ctx_.inflight_slices.store(1);
+
+    complete(IBV_WC_SUCCESS);
+
+    EXPECT_EQ(ctx_.inflight_slices.load(), 0);
+    EXPECT_EQ(slice_->charged_dev, -1);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+}
+
+// A predecessor swept along with a COMPLETED slice did move its bytes; its
+// own completion is still coming to credit them, so the meter's interval
+// must survive the sweep.
+TEST_F(RdmaWorkersCompletionTest, SweptAsCompletedKeepsTheMeterInterval) {
+    RdmaTransportTestPeer::retireSweptSlice(*workers_, ctx_, slice_,
+                                            kNow + kLen, /*bytes_moved=*/true);
+    selector_->noteCompleted(kDev, kLen);
+    selector_->maybeSampleTransmit(kDev, kNow + kLen);  // one byte per ns
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// One swept with FAILED or TIMEOUT did not: its busy time has nothing to be
+// divided into, so the next sample only rebuilds the baselines.
+TEST_F(RdmaWorkersCompletionTest, SweptAsFailedAbandonsTheMeterInterval) {
+    RdmaTransportTestPeer::retireSweptSlice(*workers_, ctx_, slice_,
+                                            kNow + kLen);
+    selector_->noteCompleted(kDev, kLen);
+    selector_->maybeSampleTransmit(kDev, kNow + kLen);
+    EXPECT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);  // seed
+}
+
+TEST_F(RdmaWorkersCompletionTest, FlushedCompletionTeachesNothing) {
+    // A queue pair reset flushes every posted work request at once; those
+    // completions carry no wire time.
+    task_->cancel_requested.store(true);  // stop short of a re-submit
+    complete(IBV_WC_WR_FLUSH_ERR);
+
+    EXPECT_EQ(slice_->charged_dev, -1);
+    EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+    EXPECT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);  // seed
+}
+
+// A queue pair shared by two worker lanes (the qp_pools layout): the lane
+// that sweeps a completion off it is not the lane that enqueued the slices,
+// so acknowledge() hands back slices belonging to somebody else. Everything
+// the sweep gives back has to land on the owner.
+class RdmaWorkersSharedQpTest : public ::testing::Test {
+   protected:
+    static constexpr int kDev = 1;
+    static constexpr uint64_t kLen = 1 << 20;
+
+    // Verbs stand-ins: enough for a context to hand out a protection domain
+    // and a completion queue, and for an endpoint to create its queue pairs.
+    struct FakeState {
+        ibv_context native{};
+        ibv_pd pd{};
+        ibv_cq cq{};
+        ibv_qp qp[8]{};
+        int next_qp = 0;
+        ibv_mr mr{};
+    };
+    static FakeState fake;
+    // Posting order as the hardware saw it: postSend appends every work
+    // request it is handed, so a poller can replay completions in that order.
+    static std::mutex post_mutex;
+    static std::vector<RdmaSlice*> post_order;
+
+    static ibv_cq* createCq(ibv_context*, int, void*, ibv_comp_channel*, int) {
+        return &fake.cq;
+    }
+    static int destroyCq(ibv_cq*) { return 0; }
+    static ibv_qp* createQp(ibv_pd*, ibv_qp_init_attr*) {
+        return &fake.qp[fake.next_qp++];
+    }
+    static int destroyQp(ibv_qp*) { return 0; }
+    static int modifyQp(ibv_qp*, ibv_qp_attr*, int) { return 0; }
+    static ibv_mr* regMr(ibv_pd*, void*, size_t, int) { return &fake.mr; }
+    static int deregMr(ibv_mr*) { return 0; }
+    // ibv_post_send is an inline over qp->context->ops, so a fake context
+    // with this op lets submitSlices run for real against the fake QPs.
+    static int postSend(ibv_qp*, ibv_send_wr* wr, ibv_send_wr** bad_wr) {
+        std::lock_guard<std::mutex> guard(post_mutex);
+        for (auto* w = wr; w; w = w->next)
+            post_order.push_back(reinterpret_cast<RdmaSlice*>(w->wr_id));
+        *bad_wr = nullptr;
+        return 0;
+    }
+
+    void SetUp() override {
+        fake = FakeState{};
+        {
+            std::lock_guard<std::mutex> guard(post_mutex);
+            post_order.clear();
+        }
+        fake.native.num_comp_vectors = 1;
+        fake.native.ops.post_send = postSend;
+        for (auto& qp : fake.qp) qp.context = &fake.native;
+
+        auto topology = std::make_shared<Topology>();
+        ASSERT_TRUE(topology
+                        ->parse(R"({"nics":[
+                        {"name":"mc-tcp-0","type":1,"numa_node":0},
+                        {"name":"mc-absent-rnic-1","type":0,"numa_node":0}]})")
+                        .ok());
+        Topology::MemEntry mem;
+        mem.name = "cpu:0";
+        mem.type = Topology::MEM_HOST;
+        mem.numa_node = 0;
+        mem.device_list[0].push_back(kDev);
+        topology->mem_list_.push_back(mem);
+        RdmaTransportTestPeer::bindTopology(transport_, topology);
+        ASSERT_EQ(RdmaTransportTestPeer::initializeContexts(transport_), 0u);
+        workers_ = RdmaTransportTestPeer::makeWorkers(transport_);
+        selector_ = workers_->getDeviceSelector();
+        ASSERT_TRUE(selector_->setDeviceAvailable(kDev, true).ok());
+        RdmaTransportTestPeer::makeWorkerContexts(*workers_, 2);
+
+        // One queue pair for both lanes, the layout that makes the sweep
+        // cross lanes.
+        params_ = std::make_shared<RdmaParams>();
+        params_->device.num_cq_list = 1;
+        params_->endpoint.qp_mul_factor = 1;
+
+        context_ = RdmaTransportTestPeer::contextSet(transport_)[kDev];
+        auto& verbs = RdmaContextTestPeer::verbs(*context_);
+        verbs.ibv_create_cq = createCq;
+        verbs.ibv_destroy_cq = destroyCq;
+        verbs.ibv_create_qp = createQp;
+        verbs.ibv_destroy_qp = destroyQp;
+        verbs.ibv_modify_qp = modifyQp;
+        verbs.ibv_reg_mr_default = regMr;
+        verbs.ibv_dereg_mr = deregMr;
+        RdmaContextTestPeer::bindDevice(*context_, &fake.native, params_);
+        ASSERT_EQ(cq_.construct(context_.get(), 4096, 0), 0);
+        ASSERT_EQ(notify_cq_.construct(context_.get(), 4096, 0), 0);
+        RdmaContextTestPeer::bindResources(*context_, &fake.pd, {&cq_},
+                                           &notify_cq_);
+        ibv_gid local_gid{};
+        local_gid.raw[15] = 0x11;
+        RdmaContextTestPeer::seedAddress(*context_, "mc-absent-rnic-1",
+                                         /*lid=*/7, /*gid_index=*/3, local_gid,
+                                         RdmaContext::DEVICE_ENABLED);
+
+        endpoint_ = std::make_shared<RdmaEndPoint>();
+        ASSERT_EQ(
+            endpoint_->construct(context_.get(), &params_->endpoint, "peer:0"),
+            0);
+    }
+
+    void TearDown() override {
+        // The endpoint goes first: deconstruct() returns its work-request
+        // quota through the context's completion queue, which
+        // unbindResources takes away below.
+        endpoint_.reset();
+        for (auto* slice : slices_) RdmaSliceStorage::Get().deallocate(slice);
+        for (auto* task : tasks_) task->deref();
+        if (workers_) RdmaTransportTestPeer::destroyWorkerContexts(*workers_);
+        if (context_) {
+            RdmaContextTestPeer::unbindResources(*context_);
+            RdmaContextTestPeer::unbindDevice(*context_);
+        }
+    }
+
+    // A slice with a task behind it, not yet posted anywhere.
+    RdmaSlice* makeSlice() {
+        auto* task = RdmaTaskStorage::Get().allocate();
+        task->num_slices = 1;
+        task->status_word = PENDING;
+        task->first_error = PENDING;
+        task->request.opcode = Request::WRITE;
+        task->ref();  // the batch's reference
+        task->ref();  // the slice's, dropped by updateSliceStatus()
+        auto* slice = RdmaSliceStorage::Get().allocate();
+        slice->task = task;
+        slice->length = kLen;
+        slice->word = PENDING;
+        slice->rail_monitor = nullptr;
+        tasks_.push_back(task);
+        slices_.push_back(slice);
+        return slice;
+    }
+
+    // A slice charged to the NIC, owned by `lane`, and posted on the shared
+    // queue pair.
+    RdmaSlice* postSlice(int lane, uint64_t enqueue_ts) {
+        auto* task = RdmaTaskStorage::Get().allocate();
+        task->num_slices = 1;
+        task->status_word = PENDING;
+        task->first_error = PENDING;
+        task->ref();  // the batch's reference
+        task->ref();  // the slice's, dropped by updateSliceStatus()
+        auto* slice = RdmaSliceStorage::Get().allocate();
+        slice->task = task;
+        slice->length = kLen;
+        slice->word = PENDING;
+        slice->rail_monitor = nullptr;
+        slice->enqueue_ts = enqueue_ts;
+        slice->owner_worker = lane;
+        int chosen = -1;
+        EXPECT_TRUE(selector_->allocate(kLen, "cpu:0", chosen).ok());
+        slice->source_dev_id = chosen;
+        slice->charged_dev = chosen;
+        slice->counted_lane = lane;  // as Workers::submit() marks it
+        auto& ctx = RdmaTransportTestPeer::workerContext(*workers_, lane);
+        ctx.inflight_slices.fetch_add(1);
+        // Posted straight away, as the hook inside submitSlices does it.
+        RdmaTransportTestPeer::markPosted(*workers_, ctx, slice, enqueue_ts);
+        RdmaEndPointTestPeer::pretendPosted(endpoint_, 0, slice);
+        tasks_.push_back(task);
+        slices_.push_back(slice);
+        return slice;
+    }
+
+    // Drive one completion for `slice` through lane 0's poll path.
+    void completeWith(RdmaSlice* slice, ibv_wc_status status,
+                      uint64_t poll_ts = 1'000'000) {
+        ibv_wc wc{};
+        wc.wr_id = reinterpret_cast<uint64_t>(slice);
+        wc.status = status;
+        RdmaTransportTestPeer::handleCompletion(
+            *workers_, RdmaTransportTestPeer::workerContext(*workers_, 0),
+            *context_, wc, poll_ts);
+    }
+
+    // What asyncPostSend does with a re-queued slice on its next pass, minus
+    // the routing it needs a live segment for: take it off the lane's queue,
+    // charge it again and put it back on the queue pair at `post_ts`.
+    void repost(RdmaSlice* slice, int lane, uint64_t post_ts = 1'000'000) {
+        auto& ctx = RdmaTransportTestPeer::workerContext(*workers_, lane);
+        std::vector<RdmaSliceList> drained;
+        ctx.queues[slice->priority].pop(drained);
+        ASSERT_EQ(drained.size(), 1u);
+        ASSERT_EQ(drained[0].first, slice);
+        RdmaTransportTestPeer::rechargeSlice(*workers_, slice, kDev);
+        RdmaTransportTestPeer::markPosted(*workers_, ctx, slice, post_ts);
+        RdmaEndPointTestPeer::pretendPosted(endpoint_, 0, slice);
+    }
+
+    RdmaTransport transport_;
+    std::shared_ptr<RdmaParams> params_;
+    std::shared_ptr<RdmaContext> context_;
+    RdmaCQ cq_;
+    RdmaCQ notify_cq_;
+    std::shared_ptr<RdmaEndPoint> endpoint_;
+    std::unique_ptr<Workers> workers_;
+    DeviceSelector* selector_ = nullptr;
+    std::vector<RdmaTask*> tasks_;
+    std::vector<RdmaSlice*> slices_;
+};
+
+RdmaWorkersSharedQpTest::FakeState RdmaWorkersSharedQpTest::fake;
+std::mutex RdmaWorkersSharedQpTest::post_mutex;
+std::vector<RdmaSlice*> RdmaWorkersSharedQpTest::post_order;
+
+TEST_F(RdmaWorkersSharedQpTest, EndpointPinsConstructionAddressGeneration) {
+    const auto endpoint_address =
+        RdmaEndPointTestPeer::localAddress(*endpoint_);
+    ASSERT_EQ(endpoint_address.lid, 7);
+    ASSERT_EQ(endpoint_address.gid_index, 3);
+
+    ibv_gid next_gid{};
+    next_gid.raw[15] = 0x22;
+    RdmaContextTestPeer::seedAddress(*context_, "mc-absent-rnic-1", /*lid=*/9,
+                                     /*gid_index=*/4, next_gid,
+                                     RdmaContext::DEVICE_ENABLED);
+
+    const auto pinned = RdmaEndPointTestPeer::localAddress(*endpoint_);
+    EXPECT_EQ(pinned.lid, endpoint_address.lid);
+    EXPECT_EQ(pinned.gid, endpoint_address.gid);
+    EXPECT_EQ(pinned.gid_index, endpoint_address.gid_index);
+    EXPECT_NE(context_->address().gid, pinned.gid);
+}
+
+TEST_F(RdmaWorkersSharedQpTest, TimeoutSweepGivesTheOtherLaneItsSliceBack) {
+    // Lane 1 posted first, so lane 0's timeout sweeps it off the queue pair
+    // along with lane 0's own slice.
+    auto* theirs = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    auto* ours = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    auto& lane0 = RdmaTransportTestPeer::workerContext(*workers_, 0);
+    auto& lane1 = RdmaTransportTestPeer::workerContext(*workers_, 1);
+    ASSERT_EQ(selector_->getInflightBytes(kDev), 2 * kLen);
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 2 * kLen);
+
+    RdmaTransportTestPeer::setSliceTimeout(*workers_, 1'000'000);  // 1 ms
+    RdmaTransportTestPeer::expireTimedOutSlices(*workers_, lane0,
+                                                /*now_ns=*/2'000'000);
+
+    // Both are terminal and neither is charged to the NIC any more.
+    EXPECT_EQ(ours->word, TIMEOUT);
+    EXPECT_EQ(theirs->word, TIMEOUT);
+    EXPECT_EQ(ours->charged_dev, -1);
+    EXPECT_EQ(theirs->charged_dev, -1);
+    EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+
+    // Each lane's own count came back down, and lane 1's set entry is waiting
+    // for lane 1 rather than having been erased from under it.
+    EXPECT_EQ(lane0.inflight_slices.load(), 0);
+    EXPECT_EQ(lane1.inflight_slices.load(), 0);
+    EXPECT_TRUE(lane0.inflight_slice_set.empty());
+    EXPECT_EQ(lane1.inflight_slice_set.count(theirs), 1u);
+    RdmaTransportTestPeer::drainReclaimed(*workers_, lane1);
+    EXPECT_TRUE(lane1.inflight_slice_set.empty());
+}
+
+// Tearing an endpoint down cancels whatever is still queued on it without
+// going through a sweep, so each lane is left holding a slice that will
+// never complete. The owner's next pass has to take those out: otherwise
+// their NIC charge, their share of its posted backlog and their place in the
+// lane's count are held for the life of the process, and the lane never goes
+// idle again.
+TEST_F(RdmaWorkersSharedQpTest, TeardownLeftoversAreReclaimedByTheirLane) {
+    auto* theirs = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    auto* ours = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    auto& lane0 = RdmaTransportTestPeer::workerContext(*workers_, 0);
+    auto& lane1 = RdmaTransportTestPeer::workerContext(*workers_, 1);
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 2 * kLen);
+
+    ASSERT_EQ(endpoint_->deconstruct(), 0);
+    ASSERT_EQ(ours->word, CANCELED);
+    ASSERT_EQ(theirs->word, CANCELED);
+
+    RdmaTransportTestPeer::setSliceTimeout(*workers_, 1'000'000);
+    RdmaTransportTestPeer::expireTimedOutSlices(*workers_, lane0,
+                                                /*now_ns=*/2'000'000);
+    RdmaTransportTestPeer::expireTimedOutSlices(*workers_, lane1,
+                                                /*now_ns=*/2'000'000);
+
+    EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+    EXPECT_EQ(lane0.inflight_slices.load(), 0);
+    EXPECT_EQ(lane1.inflight_slices.load(), 0);
+    EXPECT_TRUE(lane0.inflight_slice_set.empty());
+    EXPECT_TRUE(lane1.inflight_slice_set.empty());
+}
+
+// A slice whose attempt fails with a transient error is swept off the queue
+// pair and put back on its lane's queue. The sweep takes it out of that
+// lane's count, so the re-submit puts it back in -- and whatever guards the
+// next decrement has to come back with it. Otherwise the completion that
+// finally resolves the slice cannot take it out of the count again, and the
+// lane it belongs to never reaches zero: it stops suspending, and it looks
+// permanently loaded to submit()'s least-loaded-lane pick. The retry's
+// own completion is a transmit sample like any other.
+TEST_F(RdmaWorkersSharedQpTest, RetriedSliceIsStillCountedByItsLane) {
+    auto params = selector_->getSchedulingParams();
+    params.transmit_bandwidth_learning_rate = 0.0;  // adopt outright
+    params.transmit_meter_interval_ns = 0;          // sample on demand
+    selector_->setSchedulingParams(params);
+    ASSERT_TRUE(selector_->setDeviceBandwidth(kDev, 25.0).ok());
+    constexpr uint64_t kPosted = 1'000'000;
+
+    auto* slice = postSlice(/*lane=*/0, /*enqueue_ts=*/kPosted);
+    auto& lane0 = RdmaTransportTestPeer::workerContext(*workers_, 0);
+    ASSERT_EQ(lane0.inflight_slices.load(), 1);
+
+    // First attempt: a transient error, well short of max_retry_count.
+    completeWith(slice, IBV_WC_RETRY_EXC_ERR, kPosted + kLen);
+    ASSERT_EQ(slice->word, PENDING);
+    ASSERT_EQ(slice->retry_count, 1);
+    EXPECT_EQ(lane0.inflight_slices.load(), 1);  // queued again, still counted
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+
+    // Second attempt reaches the hardware and succeeds. The failure ended
+    // the meter's interval, so the next sample only rebuilds its baselines:
+    // taken at the re-post, as a poll pass in between would, so that the
+    // retry's own 1 MiB over its own 1 MiB ns is what the completion
+    // measures.
+    repost(slice, /*lane=*/0, kPosted + 2 * kLen);
+    selector_->maybeSampleTransmit(kDev, kPosted + 2 * kLen);
+    ASSERT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);
+    completeWith(slice, IBV_WC_SUCCESS, kPosted + 3 * kLen);
+
+    EXPECT_EQ(slice->word, COMPLETED);
+    EXPECT_EQ(lane0.inflight_slices.load(), 0);
+    EXPECT_EQ(selector_->getInflightBytes(kDev), 0u);
+    EXPECT_EQ(selector_->getPostedBytes(kDev), 0u);
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// A completion sweeps everything posted before it on the queue pair off
+// with COMPLETED. Those bytes moved -- their own completions, still to be
+// polled, credit them -- so the sweep must not abandon the meter's
+// interval the way a FAILED or TIMEOUT sweep does. The completion samples
+// before it sweeps, so the evidence is the sample after: 1 MiB over the
+// next 1 MiB ns reads 1 GB/s, where a reset would have that sample rebuild
+// its baselines and learn nothing.
+TEST_F(RdmaWorkersSharedQpTest, CompletionSweepKeepsTheMeterInterval) {
+    auto params = selector_->getSchedulingParams();
+    params.transmit_bandwidth_learning_rate = 0.0;  // adopt outright
+    params.transmit_meter_interval_ns = 0;          // sample on demand
+    selector_->setSchedulingParams(params);
+    ASSERT_TRUE(selector_->setDeviceBandwidth(kDev, 25.0).ok());
+    constexpr uint64_t kPosted = 1'000'000;
+
+    auto* first = postSlice(/*lane=*/0, /*enqueue_ts=*/kPosted);
+    auto* second = postSlice(/*lane=*/0, /*enqueue_ts=*/kPosted);
+    selector_->maybeSampleTransmit(kDev, kPosted);  // baseline
+    ASSERT_DOUBLE_EQ(selector_->getTransmitBandwidth(kDev), 3.125e9);
+
+    // Its own sample, with `first` still posted: 1 MiB over 2 MiB ns.
+    completeWith(second, IBV_WC_SUCCESS, kPosted + 2 * kLen);
+    ASSERT_EQ(first->word, COMPLETED);
+    ASSERT_EQ(second->word, COMPLETED);
+    ASSERT_EQ(selector_->getPostedBytes(kDev), 0u);
+    ASSERT_NEAR(selector_->getTransmitBandwidth(kDev), 0.5e9, 1.0);
+
+    auto* third = postSlice(/*lane=*/0, /*enqueue_ts=*/kPosted + 2 * kLen);
+    completeWith(third, IBV_WC_SUCCESS, kPosted + 3 * kLen);
+
+    EXPECT_NEAR(selector_->getTransmitBandwidth(kDev), 1e9, 1.0);
+}
+
+// Same retry, on the layout this fixture exists for: lane 1 enqueued the
+// slice, lane 0 polls the queue pair they share. The re-submit goes onto
+// lane 0's queue, so lane 0 is the lane counting it from then on and the
+// slice's ownership has to move with it. Left pointing at lane 1, the
+// completion that finally resolves it discounts a lane that is no longer
+// carrying it -- lane 1 goes negative and lane 0 never comes back down.
+TEST_F(RdmaWorkersSharedQpTest, RetryPolledByAnotherLaneMovesOwnership) {
+    auto* slice = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    auto& lane0 = RdmaTransportTestPeer::workerContext(*workers_, 0);
+    auto& lane1 = RdmaTransportTestPeer::workerContext(*workers_, 1);
+    ASSERT_EQ(lane1.inflight_slices.load(), 1);
+
+    completeWith(slice, IBV_WC_RETRY_EXC_ERR);  // polled by lane 0
+    ASSERT_EQ(slice->word, PENDING);
+    EXPECT_EQ(lane0.inflight_slices.load(), 1);  // lane 0 queued it
+    EXPECT_EQ(lane1.inflight_slices.load(), 0);
+
+    repost(slice, /*lane=*/0);
+    completeWith(slice, IBV_WC_SUCCESS);
+
+    EXPECT_EQ(slice->word, COMPLETED);
+    EXPECT_EQ(lane0.inflight_slices.load(), 0);
+    EXPECT_EQ(lane1.inflight_slices.load(), 0);
+    EXPECT_TRUE(lane0.inflight_slice_set.empty());
+}
+
+// The same retry seen from the lane the slice is leaving. Lane 1's set still
+// holds an entry for it: the handover goes through lane 1's reclaim list, and
+// until lane 1 drains that list its sweep can still walk onto the entry. What
+// decides whether a lane may take an entry out of its set is whether the entry
+// is in that set -- not whether the lane still owns the slice, which the retry
+// has just changed. Keyed on ownership, lane 1 hands its own entry to lane 0,
+// which does not have it, and lane 1 keeps walking a slice it no longer holds.
+TEST_F(RdmaWorkersSharedQpTest, StaleSetEntryIsTakenOutByTheLaneHoldingIt) {
+    auto* slice = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    auto& lane1 = RdmaTransportTestPeer::workerContext(*workers_, 1);
+
+    completeWith(slice, IBV_WC_RETRY_EXC_ERR);  // lane 0 retries it
+    ASSERT_EQ(lane1.inflight_slice_set.count(slice), 1u);
+
+    // Lane 1 drained just before lane 0 handed the entry over, so the entry
+    // is in its set with nothing queued to take it out.
+    RdmaTransportTestPeer::clearReclaimed(lane1);
+
+    RdmaTransportTestPeer::setSliceTimeout(*workers_, 1'000'000);
+    RdmaTransportTestPeer::expireTimedOutSlices(*workers_, lane1,
+                                                /*now_ns=*/2'000'000);
+
+    EXPECT_TRUE(lane1.inflight_slice_set.empty());
+}
+
+// The other half of that window. While the slice waits on lane 0's queue for
+// its re-post, lane 1's sweep resolves it. Posting it now would move bytes for
+// a transfer that is already over, and its completion returns early at
+// `word != PENDING` -- before any discount -- so lane 0's count would never
+// come back down. The pre-post check has to drop an already-resolved slice the
+// same way it drops a cancelled one.
+TEST_F(RdmaWorkersSharedQpTest, SliceResolvedWhileQueuedIsDroppedNotPosted) {
+    auto* slice = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    auto& lane0 = RdmaTransportTestPeer::workerContext(*workers_, 0);
+    auto& lane1 = RdmaTransportTestPeer::workerContext(*workers_, 1);
+
+    completeWith(slice, IBV_WC_RETRY_EXC_ERR);  // re-queued on lane 0
+    ASSERT_EQ(lane0.inflight_slices.load(), 1);
+
+    RdmaTransportTestPeer::clearReclaimed(lane1);
+    RdmaTransportTestPeer::setSliceTimeout(*workers_, 1'000'000);
+    RdmaTransportTestPeer::expireTimedOutSlices(*workers_, lane1,
+                                                /*now_ns=*/2'000'000);
+    ASSERT_EQ(slice->word, TIMEOUT);
+    ASSERT_FALSE(slice->task->cancel_requested.load());
+
+    // What lane 0's next pass does with it before generating a post path.
+    EXPECT_TRUE(
+        RdmaTransportTestPeer::dropUnpostableSlice(*workers_, lane0, slice));
+    EXPECT_EQ(lane0.inflight_slices.load(), 0);
+}
+
+// A qp_pools layout with fewer queue pairs than lanes has two lanes posting
+// to and acknowledging on one queue pair at once. They share the endpoint's
+// read guard, so the queue pair's slice queue has to serialize them itself:
+// every slice posted is acknowledged exactly once, and the queue and its
+// work-request depth end empty.
+TEST_F(RdmaWorkersSharedQpTest, TwoLanesOnOneQueuePairKeepTheSliceQueueIntact) {
+    constexpr int kSlices = 20000;
+    RdmaEndPointTestPeer::markReady(endpoint_);
+    std::vector<RdmaSlice*> slices;
+    for (int i = 0; i < kSlices; ++i) slices.push_back(makeSlice());
+
+    std::atomic<int> posted{0};
+    std::atomic<int> overflows{0};
+    std::thread poster([&] {
+        for (int i = 0; i < kSlices; ++i) {
+            std::vector<RdmaSlice*> one{slices[i]};
+            for (;;) {
+                int n = 0;
+                try {
+                    n = endpoint_->submitSlices(one, /*qp_index=*/0, nullptr);
+                } catch (const std::runtime_error&) {
+                    overflows.fetch_add(1);
+                    break;
+                }
+                if (n == 1) break;
+                std::this_thread::yield();  // queue pair full; the poller
+                                            // drains
+            }
+            posted.store(i + 1, std::memory_order_release);
+        }
+    });
+    std::thread poller([&] {
+        for (int i = 0; i < kSlices; ++i) {
+            while (posted.load(std::memory_order_acquire) <= i)
+                std::this_thread::yield();
+            endpoint_->acknowledge(slices[i], COMPLETED);
+        }
+    });
+    poster.join();
+    poller.join();
+
+    EXPECT_EQ(overflows.load(), 0);
+    int completed = 0, tasks_completed = 0;
+    for (auto* slice : slices) {
+        completed += (slice->word == COMPLETED);
+        tasks_completed += (slice->task->status_word == COMPLETED);
+    }
+    EXPECT_EQ(completed, kSlices);
+    EXPECT_EQ(tasks_completed, kSlices);
+    EXPECT_TRUE(RdmaEndPointTestPeer::queueEmpty(endpoint_, 0));
+    EXPECT_EQ(RdmaEndPointTestPeer::wrDepth(endpoint_, 0), 0);
+    EXPECT_EQ(RdmaEndPointTestPeer::inflightSlices(endpoint_), 0);
+}
+
+// Two lanes posting to one queue pair must leave the slice queue in the order
+// the hardware received the work requests: acknowledge() retires everything
+// ahead of a completed slice, so a queue that disagrees with the QP would
+// stamp a later slice with an earlier one's outcome. The fake post_send
+// records the hardware order; replaying completions in that order must find
+// each slice at the head and pop exactly one.
+TEST_F(RdmaWorkersSharedQpTest, TwoPostersOnOneQueuePairKeepPostingOrder) {
+    constexpr size_t kPerLane = 10000;
+    RdmaEndPointTestPeer::markReady(endpoint_);
+    std::vector<RdmaSlice*> lane0, lane1;
+    for (size_t i = 0; i < kPerLane; ++i) {
+        lane0.push_back(makeSlice());
+        lane1.push_back(makeSlice());
+    }
+
+    auto post_all = [&](std::vector<RdmaSlice*>& mine) {
+        for (auto* slice : mine) {
+            std::vector<RdmaSlice*> one{slice};
+            while (endpoint_->submitSlices(one, /*qp_index=*/0, nullptr) != 1)
+                std::this_thread::yield();  // queue pair full; the poller
+                                            // drains
+        }
+    };
+    std::atomic<size_t> popped_one{0};
+    std::thread poster0(post_all, std::ref(lane0));
+    std::thread poster1(post_all, std::ref(lane1));
+    std::thread poller([&] {
+        for (size_t i = 0; i < 2 * kPerLane; ++i) {
+            RdmaSlice* next = nullptr;
+            while (!next) {
+                {
+                    std::lock_guard<std::mutex> guard(post_mutex);
+                    if (post_order.size() > i) next = post_order[i];
+                }
+                if (!next) std::this_thread::yield();
+            }
+            if (endpoint_->acknowledge(next, COMPLETED) == 1u)
+                popped_one.fetch_add(1);
+        }
+    });
+    poster0.join();
+    poster1.join();
+    poller.join();
+
+    // Every completion found its slice at the head of the queue.
+    EXPECT_EQ(popped_one.load(), 2 * kPerLane);
+    EXPECT_TRUE(RdmaEndPointTestPeer::queueEmpty(endpoint_, 0));
+    EXPECT_EQ(RdmaEndPointTestPeer::wrDepth(endpoint_, 0), 0);
+    EXPECT_EQ(RdmaEndPointTestPeer::inflightSlices(endpoint_), 0);
+}
+
+// The orphan list is about slice storage outliving a work request; it has
+// nothing to do with lane sharing. The fixture above is borrowed only for
+// its fake verbs and a live endpoint to post on.
+class RdmaSliceOrphanTest : public RdmaWorkersSharedQpTest {
+   protected:
+    // Stop TearDown from freeing this slice: something else owns it now.
+    void forgetSlice(RdmaSlice* slice) {
+        slices_.erase(std::remove(slices_.begin(), slices_.end(), slice),
+                      slices_.end());
+    }
+
+    // A sub-batch holding exactly `slice`, as submitTransferTasks would leave
+    // it, handed to freeSubBatch().
+    void freeBatchHolding(RdmaSlice* slice) {
+        Transport::SubBatchRef batch = nullptr;
+        ASSERT_TRUE(transport_.allocateSubBatch(batch, 1).ok());
+        auto* rdma_batch = dynamic_cast<RdmaSubBatch*>(batch);
+        ASSERT_NE(rdma_batch, nullptr);
+        rdma_batch->slice_chain.push_back(slice);
+        forgetSlice(slice);
+        ASSERT_TRUE(transport_.freeSubBatch(batch).ok());
+    }
+};
+
+// A timeout resolves a slice without waiting for its completion, so the batch
+// can read terminal and be freed while a work request is still live. Returning
+// that slice to the slab would let the stale completion resolve whoever gets
+// the storage next, reporting bytes that never moved.
+TEST_F(RdmaSliceOrphanTest, AFreedBatchHoldsBackASliceStillOwedACompletion) {
+    auto* slice = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    ASSERT_EQ(slice->completions_owed.load(), 1);
+
+    freeBatchHolding(slice);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    // Still nothing to reap: the completion has not arrived and the endpoint
+    // that owes it is alive.
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    completeWith(slice, IBV_WC_SUCCESS);
+    EXPECT_EQ(slice->completions_owed.load(), 0);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// The ordinary path: every slice already polled, nothing held back.
+TEST_F(RdmaSliceOrphanTest, AFreedBatchReturnsASettledSliceStraightAway) {
+    auto* slice = makeSlice();  // never posted
+    ASSERT_EQ(slice->completions_owed.load(), 0);
+    freeBatchHolding(slice);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// The completion may never arrive -- destroying a queue pair clears the
+// completions naming it -- so a gone endpoint settles the orphan too.
+TEST_F(RdmaSliceOrphanTest, AnOrphanIsReapedOnceItsEndpointIsGone) {
+    auto* slice = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    freeBatchHolding(slice);
+    ASSERT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    endpoint_.reset();
+    ASSERT_TRUE(slice->ep_weak_ptr.expired());
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// An orphan is only held while its endpoint is alive, so one that outlives
+// the threshold means a queue pair is not being destroyed. That is reported
+// once per slice, and the slice stays held: freeing it on age would hand the
+// completion queue a dangling address again.
+TEST_F(RdmaSliceOrphanTest, ALingeringOrphanIsReportedOnceAndStillHeld) {
+    RdmaTransportTestPeer::setOrphanWarnAfterPasses(transport_, 3);
+    auto* slice = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    freeBatchHolding(slice);
+
+    for (int pass = 0; pass < 2; ++pass)
+        RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanWarnings(transport_), 0u);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);  // third pass
+    EXPECT_EQ(RdmaTransportTestPeer::orphanWarnings(transport_), 1u);
+    for (int pass = 0; pass < 5; ++pass)
+        RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanWarnings(transport_), 1u);    // once
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);  // held
+
+    completeWith(slice, IBV_WC_SUCCESS);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// The handler reads the slice well past acknowledge(), which is what
+// publishes the terminal status the caller is waiting for. A batch freed in
+// that window must not return the storage, and the reaper must not take it
+// either: the completion is paid at the end of the handler, so both see the
+// slice as still owed until it returns.
+TEST_F(RdmaSliceOrphanTest, ASliceIsHeldWhileItsCompletionIsBeingHandled) {
+    auto* slice = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+
+    // Stall the handler where it resolves the slice: acknowledge() takes the
+    // queue pair's lock, which this thread holds until the checks below are
+    // done.
+    auto& qp_lock = RdmaEndPointTestPeer::qpLock(endpoint_, 0);
+    qp_lock.lock();
+    const int tickets_before = TicketLockTestPeer::ticketsIssued(qp_lock);
+    std::thread poller([&] { completeWith(slice, IBV_WC_SUCCESS); });
+    // It is where we want it once it holds a ticket behind ours: queued on
+    // the lock, past everything the handler does before acknowledge().
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    while (TicketLockTestPeer::ticketsIssued(qp_lock) == tickets_before) {
+        if (std::chrono::steady_clock::now() > deadline) {
+            qp_lock.unlock();
+            poller.join();
+            FAIL() << "the handler never queued on the queue pair lock";
+        }
+        std::this_thread::yield();
+    }
+
+    freeBatchHolding(slice);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    qp_lock.unlock();
+    poller.join();
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// What the counter is for, end to end. A freed slice goes to the back of the
+// thread's ring in the slab, so a ring's worth of allocations is all it takes
+// for the address to come back -- a handful of transfers, not a rare event.
+// Handed out, it would be the work-request id of a live post naming somebody
+// else's slice, and the stale completion would resolve that one instead.
+TEST_F(RdmaSliceOrphanTest, AHeldSliceIsNeverHandedToTheNextTransfer) {
+    auto* held = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    freeBatchHolding(held);
+    ASSERT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    // Drain the ring: without the hold, the address is in here.
+    std::vector<RdmaSlice*> reused;
+    for (size_t i = 0; i < SlabBase::kMaxFreeListSizeInThread; ++i)
+        reused.push_back(RdmaSliceStorage::Get().allocate());
+    EXPECT_EQ(std::count(reused.begin(), reused.end(), held), 0)
+        << "a slice still owed a completion was handed to a new transfer";
+    for (auto* slice : reused) RdmaSliceStorage::Get().deallocate(slice);
+
+    // The completion really is still live: it lands on the held slice and
+    // resolves it, which is what it would have done to whoever had the
+    // storage instead -- COMPLETED, with the length of a transfer that never
+    // ran added to that task's byte count.
+    completeWith(held, IBV_WC_SUCCESS);
+    EXPECT_EQ(held->word, COMPLETED);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+// A batch free reaps opportunistically so a straggler is not held for a whole
+// monitor tick. Those reaps must not age an orphan: counting them would report
+// a lingering one after a handful of transfers instead of after about a
+// minute, which is the only reading that says a queue pair is stuck.
+TEST_F(RdmaSliceOrphanTest, AnOpportunisticReapDoesNotAgeAnOrphan) {
+    RdmaTransportTestPeer::setOrphanWarnAfterPasses(transport_, 1);
+    auto* held = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    freeBatchHolding(held);
+    ASSERT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    // Every one of these runs the reap inside freeSubBatch().
+    for (int pass = 0; pass < 3; ++pass) freeBatchHolding(makeSlice());
+    EXPECT_EQ(RdmaTransportTestPeer::orphanWarnings(transport_), 0u);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u);
+
+    // The monitor's tick is the one that ages it.
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanWarnings(transport_), 1u);
+}
+
+// The reaper empties the list before scanning it, so an unsettled slice has
+// to be put back -- and put back once, not dropped and not duplicated.
+TEST_F(RdmaSliceOrphanTest, AnUnsettledOrphanSurvivesRepeatedReaps) {
+    auto* kept = postSlice(/*lane=*/0, /*enqueue_ts=*/0);
+    auto* settled = postSlice(/*lane=*/1, /*enqueue_ts=*/0);
+    freeBatchHolding(kept);
+    freeBatchHolding(settled);
+    ASSERT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 2u);
+
+    // One of them gets its completion; the other is scanned three times and
+    // stays exactly once in the list.
+    completeWith(settled, IBV_WC_SUCCESS);
+    for (int pass = 0; pass < 3; ++pass) {
+        RdmaTransportTestPeer::reapOrphanSlices(transport_);
+        ASSERT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 1u)
+            << "pass " << pass;
+    }
+    completeWith(kept, IBV_WC_SUCCESS);
+    RdmaTransportTestPeer::reapOrphanSlices(transport_);
+    EXPECT_EQ(RdmaTransportTestPeer::orphanSliceCount(transport_), 0u);
+}
+
+TEST(RdmaContextPortSpeedTest, RefreshOnInertContextIsRejected) {
+    RdmaTransport transport;
+    RdmaContext context(transport);
+    ASSERT_EQ(context.status(), RdmaContext::DEVICE_UNINIT);
+    EXPECT_EQ(context.refreshPortAttributes(), -1);
+    EXPECT_DOUBLE_EQ(context.linkSpeedGbps(), 0.0);
+}
+
+// The 1 Hz recovery poll only reactivates contexts that are actually paused.
+// An inert slot never opened a device, so there is no port to consult and
+// nothing to hand back to the selector.
+TEST_F(RdmaContextEventTest, RecoveryPollLeavesInertContextsAlone) {
+    fire(IBV_EVENT_PORT_ERR, ourPort());
+    ASSERT_FALSE(selector_->isDeviceAvailable(kDev));
+    ASSERT_EQ(context().status(), RdmaContext::DEVICE_UNINIT);
+
+    RdmaTransportTestPeer::resumePausedContexts(*workers_);
+
+    EXPECT_FALSE(selector_->isDeviceAvailable(kDev));
+}
+
+TEST(RdmaContextPauseTest, TransitionAndAlreadyPausedAreSuccessful) {
+    RdmaTransport transport;
+    RdmaContext context(transport);
+    ibv_gid gid{};
+    gid.raw[15] = 1;
+    RdmaContextTestPeer::seedAddress(context, "fake-rnic", /*lid=*/1,
+                                     /*gid_index=*/0, gid,
+                                     RdmaContext::DEVICE_ENABLED);
+
+    EXPECT_EQ(context.pause(), 0);
+    EXPECT_EQ(context.status(), RdmaContext::DEVICE_PAUSED);
+    EXPECT_EQ(context.pause(), 0);  // idempotent
+    EXPECT_EQ(context.status(), RdmaContext::DEVICE_PAUSED);
+}
+
+TEST(RdmaContextPauseTest, RejectsUninitializedAndDisabledStates) {
+    RdmaTransport transport;
+    RdmaContext context(transport);
+    EXPECT_EQ(context.pause(), -1);
+    EXPECT_EQ(context.status(), RdmaContext::DEVICE_UNINIT);
+
+    ibv_gid gid{};
+    gid.raw[15] = 1;
+    RdmaContextTestPeer::seedAddress(context, "fake-rnic", /*lid=*/1,
+                                     /*gid_index=*/0, gid,
+                                     RdmaContext::DEVICE_DISABLED);
+    EXPECT_EQ(context.pause(), -1);
+    EXPECT_EQ(context.status(), RdmaContext::DEVICE_DISABLED);
+}
+
+TEST(RdmaContextPortStateTest, QueryOnInertContextIsRejected) {
+    RdmaTransport transport;
+    RdmaContext context(transport);
+    ASSERT_EQ(context.status(), RdmaContext::DEVICE_UNINIT);
+
+    ibv_port_state state = IBV_PORT_DOWN;
+    EXPECT_EQ(context.queryPortState(&state), -1);
+    EXPECT_EQ(state, IBV_PORT_DOWN) << "a failed query must not invent a state";
+    EXPECT_EQ(context.queryPortState(nullptr), -1);
+}
+
+// A context paused by IBV_EVENT_PORT_ERR whose IBV_EVENT_PORT_ACTIVE never
+// arrives (the async fd is edge-triggered, so a queued event can be stranded)
+// used to stay DEVICE_PAUSED for the rest of the process' life, failing every
+// transfer routed to that NIC. The monitor thread's poll must notice that the
+// hardware reports the port as up and reactivate the context.
+TEST(RdmaPausedContextRecoveryTest, PollActivatesPausedContextWithLivePort) {
+    if (!hasRdmaDevice()) GTEST_SKIP() << "no RDMA device detected";
+
+    int count = 0;
+    ibv_device** devices = ibv_get_device_list(&count);
+    ASSERT_NE(devices, nullptr);
+    ASSERT_GT(count, 0);
+    const std::string device_name = ibv_get_device_name(devices[0]);
+    ibv_free_device_list(devices);
+
+    auto topology = std::make_shared<Topology>();
+    const std::string spec = R"({"nics":[{"name":")" + device_name +
+                             R"(","type":0,"numa_node":0}]})";
+    ASSERT_TRUE(topology->parse(spec).ok());
+
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    RdmaTransportTestPeer::initializeContexts(transport);
+    const auto& contexts = RdmaTransportTestPeer::contextSet(transport);
+    ASSERT_EQ(contexts.size(), 1u);
+    RdmaContext& context = *contexts[0];
+    if (context.status() != RdmaContext::DEVICE_ENABLED)
+        GTEST_SKIP() << device_name << " has no usable active port";
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    RdmaTransportTestPeer::bindMetadata(transport, metadata);
+    ASSERT_TRUE(transport.setupLocalSegment().ok());
+
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+    auto* selector = workers->getDeviceSelector();
+    ASSERT_NE(selector, nullptr);
+
+    // Exactly the state IBV_EVENT_PORT_ERR leaves behind, minus the event
+    // that would have undone it.
+    context.pause();
+    ASSERT_EQ(context.status(), RdmaContext::DEVICE_PAUSED);
+    ASSERT_TRUE(selector->setDeviceAvailable(0, false).ok());
+
+    RdmaTransportTestPeer::resumePausedContexts(*workers);
+
+    EXPECT_EQ(context.status(), RdmaContext::DEVICE_ENABLED);
+    EXPECT_TRUE(selector->isDeviceAvailable(0));
+}
+
+TEST(RdmaTransportIntegrationTest, WriteThenReadAcrossProcesses) {
+    if (!hasRdmaDevice()) GTEST_SKIP() << "no RDMA device detected";
+
+    constexpr size_t kDataLength = 4 * 1024 * 1024;
+    constexpr size_t kCancelTaskCount = 16;
+    constexpr size_t kCancelStride = 8 * 1024 * 1024;
+    constexpr size_t kBufferLength = kCancelTaskCount * kCancelStride;
+    int ready_pipe[2];
+    int stop_pipe[2];
+    ASSERT_EQ(pipe(ready_pipe), 0);
+    ASSERT_EQ(pipe(stop_pipe), 0);
+
+    pid_t child = fork();
+    ASSERT_GE(child, 0);
+    if (child == 0) {
+        close(ready_pipe[0]);
+        close(stop_pipe[1]);
+
+        TransferEngine server(makeRdmaConfig());
+        if (!server.available()) _exit(2);
+        std::vector<uint8_t> buffer(kBufferLength);
+        if (!server.registerLocalMemory(buffer.data(), buffer.size()).ok())
+            _exit(3);
+
+        const std::string segment = server.getSegmentName();
+        uint32_t length = static_cast<uint32_t>(segment.size());
+        if (write(ready_pipe[1], &length, sizeof(length)) != sizeof(length))
+            _exit(4);
+        if (write(ready_pipe[1], segment.data(), length) !=
+            static_cast<ssize_t>(length))
+            _exit(5);
+
+        char stop = 0;
+        const ssize_t stop_result = read(stop_pipe[0], &stop, 1);
+        (void)stop_result;
+        (void)server.unregisterLocalMemory(buffer.data(), buffer.size());
+        _exit(0);
+    }
+
+    close(ready_pipe[1]);
+    close(stop_pipe[0]);
+    ChildProcessGuard child_guard(child, stop_pipe[1]);
+
+    uint32_t segment_length = 0;
+    ssize_t received =
+        read(ready_pipe[0], &segment_length, sizeof(segment_length));
+    if (received != static_cast<ssize_t>(sizeof(segment_length))) {
+        const int status = child_guard.reap();
+        GTEST_SKIP() << "RDMA server initialization failed, child status "
+                     << status;
+    }
+    std::string server_segment(segment_length, '\0');
+    ASSERT_EQ(read(ready_pipe[0], server_segment.data(), segment_length),
+              static_cast<ssize_t>(segment_length));
+
+    TransferEngine client(makeRdmaConfig());
+    ASSERT_TRUE(client.available());
+    std::vector<uint8_t> buffer(kBufferLength);
+    for (size_t i = 0; i < kDataLength; ++i) {
+        buffer[i] = static_cast<uint8_t>((i * 31) & 0xff);
+    }
+    ASSERT_TRUE(client.registerLocalMemory(buffer.data(), buffer.size()).ok());
+
+    SegmentID segment = 0;
+    Status result;
+    for (int i = 0; i < 100; ++i) {
+        result = client.openSegment(segment, server_segment);
+        if (result.ok()) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(result.ok()) << result.ToString();
+
+    SegmentInfo info;
+    ASSERT_TRUE(client.getSegmentInfo(segment, info).ok());
+    ASSERT_FALSE(info.buffers.empty());
+
+    Request request{};
+    request.opcode = Request::WRITE;
+    request.source = buffer.data();
+    request.target_id = segment;
+    request.target_offset = info.buffers[0].base;
+    request.length = kDataLength;
+    request.transport_hint = RDMA;
+
+    BatchID batch = client.allocateBatch(1);
+    ASSERT_TRUE(client.submitTransfer(batch, {request}).ok());
+    ASSERT_TRUE(waitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    request.opcode = Request::READ;
+    request.source = buffer.data() + kDataLength;
+    batch = client.allocateBatch(1);
+    ASSERT_TRUE(client.submitTransfer(batch, {request}).ok());
+    ASSERT_TRUE(waitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+    EXPECT_EQ(
+        std::memcmp(buffer.data(), buffer.data() + kDataLength, kDataLength),
+        0);
+
+    // Keep one QP/worker and one outstanding WR so the tail task remains in
+    // the worker's unposted set long enough to exercise real cancellation.
+    std::vector<Request> cancel_requests;
+    cancel_requests.reserve(kCancelTaskCount);
+    for (size_t i = 0; i < kCancelTaskCount; ++i) {
+        Request cancel_request{};
+        cancel_request.opcode = Request::WRITE;
+        cancel_request.source = buffer.data() + i * kCancelStride;
+        cancel_request.target_id = segment;
+        cancel_request.target_offset = info.buffers[0].base + i * kCancelStride;
+        cancel_request.length = kDataLength;
+        cancel_request.transport_hint = RDMA;
+        cancel_requests.push_back(cancel_request);
+    }
+
+    batch = client.allocateBatch(kCancelTaskCount);
+    ASSERT_TRUE(client.submitTransfer(batch, cancel_requests).ok());
+    const size_t cancel_task_id = kCancelTaskCount - 1;
+    ASSERT_TRUE(client.cancelTransfer(batch, cancel_task_id).ok());
+    ASSERT_TRUE(client.cancelTransfer(batch, cancel_task_id).ok());
+
+    std::vector<TransferStatus> statuses;
+    for (int poll = 0; poll < 10000; ++poll) {
+        ASSERT_TRUE(client.getTransferStatus(batch, statuses).ok());
+        if (std::all_of(statuses.begin(), statuses.end(),
+                        [](const TransferStatus& task_status) {
+                            return task_status.s != TransferStatusEnum::PENDING;
+                        }))
+            break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    ASSERT_EQ(statuses.size(), kCancelTaskCount);
+    for (size_t i = 0; i < cancel_task_id; ++i) {
+        EXPECT_EQ(statuses[i].s, TransferStatusEnum::COMPLETED);
+    }
+    EXPECT_EQ(statuses[cancel_task_id].s, TransferStatusEnum::CANCELED);
+    EXPECT_LE(statuses[cancel_task_id].transferred_bytes, kDataLength);
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    EXPECT_TRUE(client.closeSegment(segment).ok());
+    EXPECT_TRUE(
+        client.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
 
     const int status = child_guard.finish();
     ASSERT_TRUE(WIFEXITED(status));
     EXPECT_EQ(WEXITSTATUS(status), 0);
 }
 
+TEST(RdmaQuiesceTest, TransportQuiesceWithoutInstallIsOk) {
+    RdmaTransport transport;
+    EXPECT_TRUE(transport.quiesce().ok());
+    EXPECT_TRUE(transport.quiesce().ok());
+}
+
+TEST(RdmaQuiesceTest, TransportQuiesceSyncsTopologyDevicesViaPlatform) {
+    auto topology = std::make_shared<Topology>();
+    Topology::MemEntry memory;
+    memory.name = "cuda:0";
+    memory.type = Topology::MEM_CUDA;
+    memory.numa_node = 0;
+    topology->mem_list_.push_back(std::move(memory));
+
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    EXPECT_TRUE(transport.quiesce().ok());
+    EXPECT_TRUE(Platform::getLoader().synchronizeDevices(topology.get()).ok());
+}
+
+#ifdef USE_CUDA
+TEST(RdmaQuiesceTest, SynchronizeDevicesDoesNotCreateIdlePrimaryContexts) {
+    int device_count = 0;
+    if (cudaGetDeviceCount(&device_count) != cudaSuccess || device_count < 2) {
+        GTEST_SKIP() << "need at least 2 CUDA devices";
+    }
+    ASSERT_EQ(cuInit(0), CUDA_SUCCESS);
+
+    auto primary_active = [](int device) {
+        CUdevice cu_dev = 0;
+        if (cuDeviceGet(&cu_dev, device) != CUDA_SUCCESS) return false;
+        unsigned int flags = 0;
+        int active = 0;
+        return cuDevicePrimaryCtxGetState(cu_dev, &flags, &active) ==
+                   CUDA_SUCCESS &&
+               active != 0;
+    };
+
+    int idle = -1;
+    for (int i = 1; i < device_count; ++i) {
+        if (!primary_active(i)) {
+            idle = i;
+            break;
+        }
+    }
+    if (idle < 0) {
+        GTEST_SKIP() << "need an idle GPU besides cuda:0";
+    }
+
+    // Only cuda:0 is in use. Topology still lists every visible GPU.
+    ASSERT_EQ(cudaSetDevice(0), cudaSuccess);
+    ASSERT_TRUE(primary_active(0));
+
+    auto topology = std::make_shared<Topology>();
+    for (int i = 0; i < device_count; ++i) {
+        Topology::MemEntry memory;
+        memory.name = "cuda:" + std::to_string(i);
+        memory.type = Topology::MEM_CUDA;
+        memory.numa_node = 0;
+        topology->mem_list_.push_back(std::move(memory));
+    }
+
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    EXPECT_TRUE(transport.quiesce().ok());
+    EXPECT_TRUE(Platform::getLoader().synchronizeDevices(topology.get()).ok());
+    EXPECT_TRUE(primary_active(0));
+    EXPECT_FALSE(primary_active(idle));
+}
+#endif
+
+TEST(RdmaQuiesceTest, WorkersQuiesceWithoutStartRejectsSubmit) {
+    auto topology = std::make_shared<Topology>();
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+
+    EXPECT_TRUE(workers->quiesce().ok());
+    EXPECT_TRUE(workers->quiesce().ok());
+
+    RdmaSliceList slice_list;
+    EXPECT_TRUE(workers->submit(slice_list).IsInternalError());
+}
+
+TEST(RdmaQuiesceTest, IdleWorkersDrainAndRejectSubmit) {
+    auto topology = std::make_shared<Topology>();
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    RdmaTransportTestPeer::setNumWorkers(transport, 1);
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+    ASSERT_TRUE(workers->start().ok());
+
+    EXPECT_TRUE(workers->quiesce().ok());
+    RdmaSliceList slice_list;
+    EXPECT_TRUE(workers->submit(slice_list).IsInternalError());
+    EXPECT_TRUE(workers->quiesce().ok());
+    ASSERT_TRUE(workers->stop().ok());
+}
+
+TEST(RdmaQuiesceTest, DrainTimeoutLeavesInflight) {
+    auto topology = std::make_shared<Topology>();
+    RdmaTransport transport;
+    RdmaTransportTestPeer::bindTopology(transport, topology);
+    RdmaTransportTestPeer::setNumWorkers(transport, 1);
+    auto workers = RdmaTransportTestPeer::makeWorkers(transport);
+    ASSERT_TRUE(workers->start().ok());
+    RdmaTransportTestPeer::addInflight(*workers, 0, 1);
+
+    const auto started = std::chrono::steady_clock::now();
+    EXPECT_TRUE(workers->quiesce(50'000'000ull).IsInternalError());
+    EXPECT_LT(std::chrono::steady_clock::now() - started,
+              std::chrono::milliseconds(500));
+
+    ASSERT_TRUE(workers->stop().ok());
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/redis_metastore_test.cpp b/mooncake-transfer-engine/tent/tests/redis_metastore_test.cpp
new file mode 100644
index 0000000000..e5636e44b1
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/redis_metastore_test.cpp
@@ -0,0 +1,130 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Tests RedisMetaStore without a live server: a fake runCommand() feeds the
+// real get()/set()/remove() paths fabricated replies. Covers the two fixes:
+// (1) client_mutex_ serializes concurrent ops; (2) get() keeps embedded NULs.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdarg>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/metastore/redis.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// Heap redisReply that freeReplyObject() can release: it frees str and the
+// struct with malloc/free, so allocate the same way; calloc zeros the rest.
+redisReply *makeStringReply(const std::string &data) {
+    auto *reply = static_cast<redisReply *>(std::calloc(1, sizeof(redisReply)));
+    reply->type = REDIS_REPLY_STRING;
+    reply->len = data.size();
+    reply->str = static_cast<char *>(std::malloc(data.size() + 1));
+    std::memcpy(reply->str, data.data(), data.size());
+    reply->str[data.size()] = '\0';
+    return reply;
+}
+
+redisReply *makeStatusReply(const char *status) {
+    auto *reply = static_cast<redisReply *>(std::calloc(1, sizeof(redisReply)));
+    reply->type = REDIS_REPLY_STATUS;
+    const size_t len = std::strlen(status);
+    reply->len = len;
+    reply->str = static_cast<char *>(std::malloc(len + 1));
+    std::memcpy(reply->str, status, len + 1);
+    return reply;
+}
+
+// Fake store: runCommand() fabricates replies and flags if two commands are
+// ever in flight at once. Without client_mutex_ the widened window overlaps.
+class FakeRedisMetaStore : public RedisMetaStore {
+   public:
+    // connected_ is protected; client_ stays nullptr (redisFree() tolerates
+    // it).
+    FakeRedisMetaStore() { connected_ = true; }
+
+    std::atomic<int> in_flight_{0};
+    std::atomic<bool> saw_concurrent_{false};
+    std::atomic<int> command_count_{0};
+
+    // Embedded NUL proves get() does not truncate at the first '\0'.
+    const std::string stored_value_ = std::string("seg\0desc", 8);
+
+   protected:
+    redisReply *runCommand(const char *format, va_list /*ap*/) override {
+        command_count_.fetch_add(1, std::memory_order_relaxed);
+        if (in_flight_.fetch_add(1, std::memory_order_acq_rel) + 1 > 1) {
+            saw_concurrent_.store(true, std::memory_order_relaxed);
+        }
+        // Widen the critical section so a missing lock reliably overlaps.
+        std::this_thread::sleep_for(std::chrono::microseconds(200));
+        in_flight_.fetch_sub(1, std::memory_order_acq_rel);
+
+        if (std::strncmp(format, "GET", 3) == 0) {
+            return makeStringReply(stored_value_);
+        }
+        return makeStatusReply("OK");
+    }
+};
+
+// get() must preserve the full binary value, including embedded NULs.
+TEST(RedisMetaStore, GetPreservesEmbeddedNul) {
+    FakeRedisMetaStore store;
+    std::string value;
+    Status status = store.get("segment/key", value);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(value.size(), store.stored_value_.size());
+    EXPECT_EQ(value, store.stored_value_);
+}
+
+// client_mutex_ must serialize concurrent get()/set()/remove() so that the
+// shared redisContext is never used from two threads at once.
+TEST(RedisMetaStore, ConcurrentAccessIsSerialized) {
+    FakeRedisMetaStore store;
+    constexpr int kThreads = 8;
+    constexpr int kItersPerThread = 40;
+
+    std::vector<std::thread> threads;
+    threads.reserve(kThreads);
+    for (int t = 0; t < kThreads; ++t) {
+        threads.emplace_back([&store] {
+            for (int i = 0; i < kItersPerThread; ++i) {
+                std::string value;
+                store.get("segment/key", value);
+                store.set("segment/key", "payload");
+                store.remove("segment/key");
+            }
+        });
+    }
+    for (auto &thread : threads) {
+        thread.join();
+    }
+
+    EXPECT_FALSE(store.saw_concurrent_.load())
+        << "client_mutex_ failed to serialize access to the shared client";
+    EXPECT_EQ(store.command_count_.load(), kThreads * kItersPerThread * 3);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/request_merge_test.cpp b/mooncake-transfer-engine/tent/tests/request_merge_test.cpp
index 2b5fdef4fc..387e0fe912 100644
--- a/mooncake-transfer-engine/tent/tests/request_merge_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/request_merge_test.cpp
@@ -1,5 +1,6 @@
 #include <array>
 #include <cstdint>
+#include <limits>
 #include <map>
 #include <optional>
 #include <vector>
@@ -23,6 +24,7 @@ struct BufferKey {
 struct RequestBoundaryInfo {
     std::optional<BufferKey> source_key;
     std::optional<BufferKey> target_key;
+    uint64_t max_merge_bytes{std::numeric_limits<uint64_t>::max()};
 };
 
 struct MergeResult {
@@ -90,6 +92,11 @@ TEST(RequestMergeTest, MergesAdjacentRequestsInsideSameRegisteredBuffers) {
     EXPECT_EQ(merged.request_list[0].length, 2048u);
     EXPECT_EQ(merged.task_lookup.at(0), 0u);
     EXPECT_EQ(merged.task_lookup.at(1), 0u);
+    for (uint64_t limit : {1024, 2048}) {
+        for (auto& boundary : boundaries) boundary.max_merge_bytes = limit;
+        EXPECT_EQ(mergeRequests(requests, boundaries, true).request_list.size(),
+                  limit == 1024 ? 2u : 1u);
+    }
 }
 
 TEST(RequestMergeTest, KeepsNonContiguousRequestsSplit) {
@@ -170,6 +177,79 @@ TEST(RequestMergeTest, MergesAdjacentRequestsWithSameTransportHint) {
     EXPECT_EQ(merged.task_lookup.at(1), 0u);
 }
 
+TEST(RequestMergeTest, KeepsDifferentSelectionAttributesSplit) {
+    std::array<char, 8192> source{};
+    const auto source_addr =
+        static_cast<uint64_t>(reinterpret_cast<uintptr_t>(source.data()));
+
+    struct AttributeCase {
+        const char* name;
+        void (*set_different)(Request&, Request&);
+    };
+    const std::array<AttributeCase, 3> cases = {{
+        {"priority",
+         [](Request& first, Request& second) {
+             first.priority = PRIO_HIGH;
+             second.priority = PRIO_LOW;
+         }},
+        {"policy_name",
+         [](Request& first, Request& second) {
+             first.policy_name = "foreground";
+             second.policy_name = "background";
+         }},
+        {"intent_type",
+         [](Request& first, Request& second) {
+             first.intent_type = IntentType::FOREGROUND_GET;
+             second.intent_type = IntentType::MIGRATION;
+         }},
+    }};
+
+    for (const auto& test_case : cases) {
+        SCOPED_TRACE(test_case.name);
+        std::vector<Request> requests = {
+            makeWriteRequest(source.data(), 0, 4096, 1024),
+            makeWriteRequest(source.data(), 1024, 5120, 1024),
+        };
+        test_case.set_different(requests[0], requests[1]);
+        std::vector<RequestBoundaryInfo> boundaries = {
+            {makeBufferKey(source_addr, source.size()),
+             makeBufferKey(4096, 2048)},
+            {makeBufferKey(source_addr, source.size()),
+             makeBufferKey(4096, 2048)},
+        };
+
+        auto merged = mergeRequests(requests, boundaries, true);
+
+        ASSERT_EQ(merged.request_list.size(), 2u);
+        EXPECT_NE(merged.task_lookup.at(0), merged.task_lookup.at(1));
+    }
+}
+
+TEST(RequestMergeTest, MergesMatchingSelectionAttributes) {
+    std::array<char, 2048> source{};
+    const auto source_addr =
+        static_cast<uint64_t>(reinterpret_cast<uintptr_t>(source.data()));
+    std::vector<Request> requests = {
+        makeWriteRequest(source.data(), 0, 4096, 1024),
+        makeWriteRequest(source.data(), 1024, 5120, 1024),
+    };
+    for (auto& request : requests) {
+        request.priority = PRIO_LOW;
+        request.policy_name = "background";
+        request.intent_type = IntentType::MIGRATION;
+    }
+    std::vector<RequestBoundaryInfo> boundaries = {
+        {makeBufferKey(source_addr, source.size()), makeBufferKey(4096, 2048)},
+        {makeBufferKey(source_addr, source.size()), makeBufferKey(4096, 2048)},
+    };
+
+    auto merged = mergeRequests(requests, boundaries, true);
+
+    ASSERT_EQ(merged.request_list.size(), 1u);
+    EXPECT_EQ(merged.request_list[0].length, 2048u);
+    EXPECT_EQ(merged.task_lookup.at(0), merged.task_lookup.at(1));
+}
+
 TEST(RequestMergeTest, MixedHintBatchStillMergesPerHint) {
     std::array<char, 4096> source{};
     const auto source_addr =
diff --git a/mooncake-transfer-engine/tent/tests/rocm_platform_test.cpp b/mooncake-transfer-engine/tent/tests/rocm_platform_test.cpp
index d0b85f955b..a6d3706e0e 100644
--- a/mooncake-transfer-engine/tent/tests/rocm_platform_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/rocm_platform_test.cpp
@@ -98,7 +98,9 @@ class RocmPlatformTest : public ::testing::Test {
     std::shared_ptr<RocmPlatform> platform_;
 };
 
-TEST_F(RocmPlatformTest, TypeString) { EXPECT_EQ(platform_->type(), "rocm"); }
+TEST_F(RocmPlatformTest, TypeString) {
+    EXPECT_EQ(platform_->type(), kAmdGpuLocationType);
+}
 
 TEST_F(RocmPlatformTest, ProbeDiscoversMems) {
     std::vector<Topology::NicEntry> nics;
@@ -110,7 +112,7 @@ TEST_F(RocmPlatformTest, ProbeDiscoversMems) {
     for (const auto& m : mems) {
         if (m.type == Topology::MEM_ROCM) {
             found_rocm = true;
-            EXPECT_EQ(m.name.substr(0, 5), "rocm:");
+            EXPECT_EQ(m.name.substr(0, 4), "hip:");
         }
     }
     EXPECT_TRUE(found_rocm) << "probe() found no MEM_ROCM entries";
@@ -118,7 +120,7 @@ TEST_F(RocmPlatformTest, ProbeDiscoversMems) {
 
 TEST_F(RocmPlatformTest, AllocateAndFreeDeviceMemory) {
     MemoryOptions opts;
-    opts.location = "rocm:0";
+    opts.location = "hip:0";
     void* ptr = nullptr;
     constexpr size_t kSize = 1024 * 1024;  // 1 MiB
 
@@ -150,7 +152,7 @@ TEST_F(RocmPlatformTest, AllocateAndFreeCpuMemory) {
 
 TEST_F(RocmPlatformTest, CopyDeviceToDevice) {
     MemoryOptions opts;
-    opts.location = "rocm:0";
+    opts.location = "hip:0";
     constexpr size_t kSize = 256;
     void *src = nullptr, *dst = nullptr;
 
@@ -177,7 +179,7 @@ TEST_F(RocmPlatformTest, CopyDeviceToDevice) {
 
 TEST_F(RocmPlatformTest, CopyHostToDevice) {
     MemoryOptions dev_opts;
-    dev_opts.location = "rocm:0";
+    dev_opts.location = "hip:0";
     MemoryOptions cpu_opts;
     cpu_opts.location = "cpu:0";
     constexpr size_t kSize = 512;
@@ -203,15 +205,29 @@ TEST_F(RocmPlatformTest, CopyHostToDevice) {
 }
 
 TEST_F(RocmPlatformTest, GetLocationDeviceMemory) {
+    MemoryOptions opts;
+    opts.location = "hip:0";
+    constexpr size_t kSize = 4096;
+    void* ptr = nullptr;
+
+    ASSERT_TRUE(platform_->allocate(&ptr, kSize, opts).ok());
+    auto locs = platform_->getLocation(ptr, kSize);
+    ASSERT_FALSE(locs.empty());
+    EXPECT_EQ(locs[0].location, "hip:0");
+    EXPECT_TRUE(platform_->free(ptr, kSize).ok());
+}
+
+TEST_F(RocmPlatformTest, LegacyRocmPrefixStillAllocates) {
     MemoryOptions opts;
     opts.location = "rocm:0";
     constexpr size_t kSize = 4096;
     void* ptr = nullptr;
 
     ASSERT_TRUE(platform_->allocate(&ptr, kSize, opts).ok());
+    EXPECT_EQ(platform_->getMemoryType(ptr), MTYPE_ROCM);
     auto locs = platform_->getLocation(ptr, kSize);
     ASSERT_FALSE(locs.empty());
-    EXPECT_EQ(locs[0].location, "rocm:0");
+    EXPECT_EQ(locs[0].location, "hip:0");
     EXPECT_TRUE(platform_->free(ptr, kSize).ok());
 }
 
@@ -231,7 +247,7 @@ TEST_F(RocmPlatformTest, AllocateOnSecondGpu) {
     if (getHipDeviceCount() < 2) GTEST_SKIP() << "Requires >= 2 AMD GPUs";
 
     MemoryOptions opts;
-    opts.location = "rocm:1";
+    opts.location = "hip:1";
     void* ptr = nullptr;
     constexpr size_t kSize = 1024;
 
diff --git a/mooncake-transfer-engine/tent/tests/rpc_handler_isolation_test.cpp b/mooncake-transfer-engine/tent/tests/rpc_handler_isolation_test.cpp
new file mode 100644
index 0000000000..5d5123a888
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/rpc_handler_isolation_test.cpp
@@ -0,0 +1,189 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// A slow RPC handler must not stall the rest of the control plane.
+//
+// The server runs one io_context (kRpcThreads == 1) and every connection's
+// coroutine is scheduled on it, so an inline handler pins that thread for its
+// whole duration -- for every peer, not just its own. onDelegate does exactly
+// that: it runs a full transfer to completion. offload=true moves the handler
+// off the io_context so the event loop keeps serving.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <stdexcept>
+#include <string>
+#include <thread>
+
+#include "tent/rpc/rpc.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+using namespace std::chrono_literals;
+
+constexpr int kSlowFunc = 4001;
+constexpr int kFastFunc = 4002;
+constexpr int kThrowingFunc = 4003;
+
+// Long enough that a serialized fast call is unambiguously distinguishable
+// from a concurrent one, short enough to keep the test quick.
+constexpr auto kSlowHandlerDuration = 800ms;
+// A concurrent fast call only pays connect + round trip. Generous enough to
+// survive a loaded CI box, still far below kSlowHandlerDuration.
+constexpr auto kFastCallBudget = 400ms;
+
+class RpcHandlerIsolationTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        server_ = std::make_unique<CoroRpcAgent>();
+        ASSERT_TRUE(
+            server_
+                ->registerFunction(
+                    kSlowFunc,
+                    [this](const std::string_view&, std::string& response) {
+                        slow_running_.store(true);
+                        std::this_thread::sleep_for(kSlowHandlerDuration);
+                        slow_running_.store(false);
+                        response = "slow";
+                    },
+                    /*offload=*/true)
+                .ok());
+        ASSERT_TRUE(
+            server_
+                ->registerFunction(
+                    kFastFunc, [](const std::string_view&,
+                                  std::string& response) { response = "fast"; })
+                .ok());
+        ASSERT_TRUE(server_
+                        ->registerFunction(
+                            kThrowingFunc,
+                            [](const std::string_view&, std::string&) {
+                                throw std::runtime_error("handler blew up");
+                            },
+                            /*offload=*/true)
+                        .ok());
+        uint16_t port = 0;
+        ASSERT_TRUE(server_->start(port).ok());
+        addr_ = "127.0.0.1:" + std::to_string(port);
+    }
+
+    void TearDown() override {
+        if (server_) server_->stop();
+    }
+
+    std::unique_ptr<CoroRpcAgent> server_;
+    std::string addr_;
+    std::atomic<bool> slow_running_{false};
+};
+
+TEST_F(RpcHandlerIsolationTest, SlowOffloadedHandlerDoesNotStallOtherRpcs) {
+    CoroRpcAgent slow_client;
+    CoroRpcAgent fast_client;
+
+    std::atomic<bool> slow_done{false};
+    std::thread slow_thread([&] {
+        std::string response;
+        auto status = slow_client.call(addr_, kSlowFunc, "", response);
+        EXPECT_TRUE(status.ok()) << status.ToString();
+        EXPECT_EQ(response, "slow");
+        slow_done.store(true);
+    });
+
+    // Wait until the slow handler is actually executing, so the fast call
+    // below genuinely overlaps it.
+    const auto deadline = std::chrono::steady_clock::now() + 2s;
+    while (!slow_running_.load() &&
+           std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(1ms);
+    }
+    ASSERT_TRUE(slow_running_.load()) << "slow handler never started";
+
+    const auto started = std::chrono::steady_clock::now();
+    std::string response;
+    auto status = fast_client.call(addr_, kFastFunc, "", response);
+    const auto elapsed = std::chrono::steady_clock::now() - started;
+
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(response, "fast");
+    EXPECT_TRUE(slow_done.load() == false || slow_running_.load() == false);
+    EXPECT_LT(elapsed, kFastCallBudget)
+        << "fast RPC took "
+        << std::chrono::duration_cast<std::chrono::milliseconds>(elapsed)
+               .count()
+        << "ms: it waited for the slow handler instead of being served "
+           "concurrently";
+
+    slow_thread.join();
+    EXPECT_TRUE(slow_done.load());
+}
+
+// Handlers left at the default offload=false keep running inline on the
+// io_context thread, which is what every non-blocking handler wants: no thread
+// hop, no extra latency.
+TEST_F(RpcHandlerIsolationTest, InlineHandlerStillWorks) {
+    CoroRpcAgent client;
+    std::string response;
+    ASSERT_TRUE(client.call(addr_, kFastFunc, "", response).ok());
+    EXPECT_EQ(response, "fast");
+}
+
+TEST_F(RpcHandlerIsolationTest, OffloadedHandlerReturnsItsResponse) {
+    CoroRpcAgent client;
+    std::string response;
+    ASSERT_TRUE(client.call(addr_, kSlowFunc, "", response).ok());
+    EXPECT_EQ(response, "slow");
+}
+
+// Handlers do throw -- onDelegate starts with json::parse. The executor
+// reports that through a Try rather than by unwinding, so it has to be
+// rethrown or the caller would see an empty success.
+TEST_F(RpcHandlerIsolationTest, OffloadedHandlerExceptionReachesTheCaller) {
+    CoroRpcAgent client;
+    std::string response;
+    EXPECT_FALSE(client.call(addr_, kThrowingFunc, "", response).ok());
+}
+
+TEST_F(RpcHandlerIsolationTest, UnknownFunctionReturnsAnError) {
+    CoroRpcAgent client;
+    std::string response;
+    EXPECT_FALSE(client.call(addr_, 0x7fffffff, "", response).ok());
+}
+
+// The handler map is shared between registerFunction() and the serving
+// coroutines under one mutex, so a function may be registered after start()
+// and is served from then on. Every production registration happens before
+// start() today; this pins the contract that makes a later one safe.
+TEST_F(RpcHandlerIsolationTest, FunctionRegisteredAfterStartIsServed) {
+    constexpr int kLateFunc = 4004;
+    CoroRpcAgent client;
+    std::string response;
+    EXPECT_FALSE(client.call(addr_, kLateFunc, "", response).ok());
+
+    ASSERT_TRUE(
+        server_
+            ->registerFunction(kLateFunc,
+                               [](const std::string_view&,
+                                  std::string& response) { response = "late"; })
+            .ok());
+    ASSERT_TRUE(client.call(addr_, kLateFunc, "", response).ok());
+    EXPECT_EQ(response, "late");
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/rpc_reconnect_test.cpp b/mooncake-transfer-engine/tent/tests/rpc_reconnect_test.cpp
new file mode 100644
index 0000000000..88ad625f5c
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/rpc_reconnect_test.cpp
@@ -0,0 +1,269 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// A peer restart invalidates every connection pooled for that peer, not just
+// the one that happens to notice first. These tests pin what a failed pooled
+// call does to the rest of the pool.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/rpc/rpc.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+using namespace std::chrono_literals;
+using std::chrono::steady_clock;
+
+constexpr int kEchoFunc = 5001;
+constexpr int kBarrierFunc = 5002;
+constexpr int kThrowFunc = 5003;
+constexpr int kSideEffectThenThrowFunc = 5004;
+
+// Counts how many times the peer actually ran the handler.
+std::atomic<int> g_side_effects{0};
+
+// How many connections the burst below parks in the pool. Two is what these
+// tests need: enough to tell a whole-pool flush from a single-client discard,
+// and low enough that the burst is genuinely concurrent on any offload pool.
+constexpr int kPooled = 2;
+
+std::atomic<int> g_in_flight{0};
+
+class RpcReconnectTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        g_in_flight.store(0);
+        g_side_effects.store(0);
+    }
+
+    void StartServer(uint16_t port) {
+        server_ = std::make_unique<CoroRpcAgent>();
+        ASSERT_TRUE(server_
+                        ->registerFunction(kEchoFunc,
+                                           [](const std::string_view& request,
+                                              std::string& response) {
+                                               response = std::string(request);
+                                           })
+                        .ok());
+        // Parks until the whole burst has arrived, so the calls are genuinely
+        // concurrent and cannot share one pooled connection.
+        ASSERT_TRUE(
+            server_
+                ->registerFunction(
+                    kBarrierFunc,
+                    [](const std::string_view& request, std::string& response) {
+                        g_in_flight.fetch_add(1);
+                        auto deadline = steady_clock::now() + 3s;
+                        while (g_in_flight.load() < kPooled &&
+                               steady_clock::now() < deadline) {
+                            std::this_thread::sleep_for(1ms);
+                        }
+                        response = std::string(request);
+                    },
+                    /*offload=*/true)
+                .ok());
+        // Runs a side effect and only then fails, standing in for the
+        // control-plane handlers that mutate state before something goes
+        // wrong on the way back.
+        ASSERT_TRUE(
+            server_
+                ->registerFunction(kSideEffectThenThrowFunc,
+                                   [](const std::string_view&, std::string&) {
+                                       g_side_effects.fetch_add(1);
+                                       throw std::runtime_error(
+                                           "after the side effect");
+                                   })
+                .ok());
+        // Fails on the server side, with the connection intact.
+        ASSERT_TRUE(server_
+                        ->registerFunction(
+                            kThrowFunc,
+                            [](const std::string_view&, std::string&) {
+                                throw std::runtime_error("handler failed");
+                            })
+                        .ok());
+        uint16_t requested = port;
+        port_ = port;
+        ASSERT_TRUE(server_->start(port_).ok());
+        // start() takes the port by reference and picks a random one if the
+        // bind fails. A silent change would move the pool key and make these
+        // tests pass without exercising anything.
+        if (requested != 0) ASSERT_EQ(port_, requested) << "port drifted";
+        addr_ = "127.0.0.1:" + std::to_string(port_);
+    }
+
+    void StopServer() { server_.reset(); }
+
+    // The server destructor joins its io threads, so the port is free when
+    // this returns; the sleep lets the client sockets see the FIN first, so
+    // "stale" is deterministic rather than racing the restart.
+    void RestartServerSamePort() {
+        StopServer();
+        std::this_thread::sleep_for(100ms);
+        g_in_flight.store(0);
+        StartServer(port_);
+    }
+
+    // Parks kPooled concurrent calls in the server, so the client has to open
+    // one connection each and pools all of them.
+    void FillPool(CoroRpcAgent& client) {
+        std::atomic<int> ok_count{0};
+        std::vector<std::thread> burst;
+        for (int i = 0; i < kPooled; ++i) {
+            burst.emplace_back([&] {
+                std::string response;
+                if (client.call(addr_, kBarrierFunc, "warm", response).ok()) {
+                    ok_count.fetch_add(1);
+                }
+            });
+        }
+        for (auto& t : burst) t.join();
+        ASSERT_EQ(ok_count.load(), kPooled) << "burst did not fill the pool";
+    }
+
+    std::unique_ptr<CoroRpcAgent> server_;
+    uint16_t port_ = 0;
+    std::string addr_;
+};
+
+// The point of the change. After a restart every pooled connection is stale.
+// The first call to use one fails - a socket only reports the peer's death
+// when it is written to - but that single failure must take the rest of the
+// pool with it, so the next call connects fresh and succeeds. Without the
+// flush the caller pays one failed call per stale connection, and the retry
+// budget above (TcpTransport: max_retry_count) runs out before the pool does.
+TEST_F(RpcReconnectTest, StalePoolIsFlushedSoTheNextCallSucceeds) {
+    StartServer(0);
+    CoroRpcAgent client;
+    ASSERT_NO_FATAL_FAILURE(FillPool(client));
+
+    RestartServerSamePort();
+
+    std::string response;
+    auto first = client.call(addr_, kEchoFunc, "after-restart", response);
+    EXPECT_FALSE(first.ok()) << "expected the stale connection to fail";
+
+    response.clear();
+    auto second = client.call(addr_, kEchoFunc, "after-restart", response);
+    EXPECT_TRUE(second.ok()) << second.ToString();
+    EXPECT_EQ(response, "after-restart");
+}
+
+// Guard, not a regression test: it passes with and without the flush, because
+// a flushed pool simply reconnects. It is here to pin the behaviour a reviewer
+// would ask about - a failure the peer replied with says nothing about the
+// connection, and the pool is shared with every other caller of this address,
+// so a throwing handler must not cost them their connections.
+TEST_F(RpcReconnectTest, HandlerFailureLeavesThePoolAlone) {
+    StartServer(0);
+    CoroRpcAgent client;
+    ASSERT_NO_FATAL_FAILURE(FillPool(client));
+
+    std::string response;
+    EXPECT_FALSE(client.call(addr_, kThrowFunc, "boom", response).ok());
+
+    // The pooled connections are still good, and the server is still up.
+    for (int i = 0; i < kPooled; ++i) {
+        response.clear();
+        auto status = client.call(addr_, kEchoFunc, "still-fine", response);
+        EXPECT_TRUE(status.ok()) << status.ToString();
+        EXPECT_EQ(response, "still-fine");
+    }
+}
+
+// Guard, not a regression test: a peer that is genuinely gone must keep
+// failing, so the flush cannot turn an unreachable server into a false
+// success or a retry storm.
+TEST_F(RpcReconnectTest, DeadPeerStillFails) {
+    StartServer(0);
+    CoroRpcAgent client;
+    ASSERT_NO_FATAL_FAILURE(FillPool(client));
+
+    StopServer();
+
+    std::string response;
+    for (int i = 0; i < 3; ++i) {
+        EXPECT_FALSE(client.call(addr_, kEchoFunc, "gone", response).ok());
+    }
+}
+
+// A failed call is reported, not retried. Several RPCs share this path and
+// mutate remote state - Pin acquires a stage buffer, Unpin releases one,
+// Delegate starts a transfer, Notify runs a user callback - and an
+// unsuccessful result does not tell us the peer skipped the handler: the
+// error code for "never sent" and for "ran, but the reply was lost" is the
+// same io_error. Retrying here would turn those into at-least-once.
+TEST_F(RpcReconnectTest, AFailedCallIsNotRetried) {
+    StartServer(0);
+    CoroRpcAgent client;
+    ASSERT_NO_FATAL_FAILURE(FillPool(client));
+
+    std::string response;
+    EXPECT_FALSE(
+        client.call(addr_, kSideEffectThenThrowFunc, "once", response).ok());
+    EXPECT_EQ(g_side_effects.load(), 1)
+        << "the peer ran the handler " << g_side_effects.load() << " times";
+}
+
+// Several callers notice the same restart at once. Each flushes at most the
+// generation it drew from, so the connection one caller has already
+// re-established is not thrown away by another's later failure, and every
+// caller recovers on its next attempt.
+//
+// Guard, not a regression test: what the generation changes is how many
+// reconnects happen, and the agent exposes no connection count to assert on.
+// What is checked here is the part that is observable - nobody is left
+// permanently broken.
+TEST_F(RpcReconnectTest, ConcurrentStaleCallsAllRecover) {
+    StartServer(0);
+    CoroRpcAgent client;
+    ASSERT_NO_FATAL_FAILURE(FillPool(client));
+
+    RestartServerSamePort();
+
+    constexpr int kCallers = 4;
+    auto round = [&](const char* payload) {
+        std::atomic<int> ok_count{0};
+        std::vector<std::thread> callers;
+        for (int i = 0; i < kCallers; ++i) {
+            callers.emplace_back([&] {
+                std::string response;
+                if (client.call(addr_, kEchoFunc, payload, response).ok() &&
+                    response == payload) {
+                    ok_count.fetch_add(1);
+                }
+            });
+        }
+        for (auto& t : callers) t.join();
+        return ok_count.load();
+    };
+
+    // The first round draws the stale connections; some or all of it fails.
+    (void)round("first");
+    // By the second round every caller is on a fresh connection.
+    EXPECT_EQ(round("second"), kCallers);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/runtime_queue_dispatch_test.cpp b/mooncake-transfer-engine/tent/tests/runtime_queue_dispatch_test.cpp
index 5f3ecfdc13..21a552e28b 100644
--- a/mooncake-transfer-engine/tent/tests/runtime_queue_dispatch_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/runtime_queue_dispatch_test.cpp
@@ -27,6 +27,7 @@
 #include "tent/common/config.h"
 #include "tent/common/types.h"
 #include "tent/runtime/segment.h"
+#include "tent/runtime/control_plane.h"
 #include "tent/runtime/transfer_engine_impl.h"
 #include "tent/runtime/transport.h"
 
@@ -91,10 +92,15 @@ class FakeTransport : public Transport {
             fake->poll_counts.push_back(0);
             ++fake->task_count;
         }
+        last_batch_ = batch;
         if (notify_on_submit_) batch->notifyProgress();
         return Status::OK();
     }
 
+    void notifyLastBatch() {
+        if (last_batch_) last_batch_->notifyProgress();
+    }
+
     Status getTransferStatus(SubBatchRef batch, int task_id,
                              TransferStatus& status) override {
         ++status_calls;
@@ -103,7 +109,9 @@ class FakeTransport : public Transport {
             return Status::InvalidArgument("bad task_id" LOC_MARK);
         }
         ++fake->poll_counts[task_id];
-        if (poll_status_factory_) {
+        if (fake->statuses[task_id].s == TransferStatusEnum::CANCELED) {
+            status = fake->statuses[task_id];
+        } else if (poll_status_factory_) {
             status = poll_status_factory_(fake->requests[task_id],
                                           fake->poll_counts[task_id]);
         } else {
@@ -165,6 +173,7 @@ class FakeTransport : public Transport {
     TransportType self_type_;
     PollStatusFactory poll_status_factory_;
     bool notify_on_submit_;
+    SubBatchRef last_batch_{nullptr};
 };
 
 std::shared_ptr<Config> makeRuntimeQueueConfig(size_t max_dispatch_owners,
@@ -291,7 +300,15 @@ TEST(RuntimeQueueDispatch, DispatchesOnlyOneWindowOnSubmit) {
     TransferEngineImpl engine(cfg);
     ASSERT_TRUE(engine.available());
 
-    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
+    std::atomic<bool> complete_first{false};
+    auto fake_rdma = std::make_shared<FakeTransport>(
+        RDMA, [&complete_first](const Request& request, int) {
+            if (!complete_first.load()) {
+                return TransferStatus{TransferStatusEnum::PENDING, 0};
+            }
+            return TransferStatus{TransferStatusEnum::COMPLETED,
+                                  request.length};
+        });
     installFakeRdma(engine, fake_rdma);
 
     constexpr size_t kReqLen = 4096;
@@ -309,6 +326,8 @@ TEST(RuntimeQueueDispatch, DispatchesOnlyOneWindowOnSubmit) {
             .ok());
     EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
 
+    complete_first.store(true);
+
     TransferStatus first{};
     ASSERT_TRUE(engine.getTransferStatus(batch, 0, first).ok());
     EXPECT_EQ(first.s, TransferStatusEnum::COMPLETED);
@@ -430,7 +449,10 @@ TEST(RuntimeQueueDispatch, CancelsDispatchedRdmaTaskIdempotently) {
     TransferEngineImpl engine(cfg);
     ASSERT_TRUE(engine.available());
 
-    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
+    auto fake_rdma =
+        std::make_shared<FakeTransport>(RDMA, [](const Request&, int) {
+            return TransferStatus{TransferStatusEnum::PENDING, 0};
+        });
     installFakeRdma(engine, fake_rdma);
 
     constexpr size_t kReqLen = 4096;
@@ -499,8 +521,20 @@ TEST(RuntimeQueueDispatch, ProgressWorkerRefillsWindowFromTransportNotify) {
     TransferEngineImpl engine(cfg);
     ASSERT_TRUE(engine.available());
 
+    // Keep the first owner PENDING until after the submit-window assertion.
+    // Otherwise ProgressWorker can observe COMPLETED, refill, and bump
+    // submit_calls to 2 before EXPECT_EQ(..., 1). Same race as #3459.
+    std::atomic<bool> complete_first{false};
     auto fake_rdma = std::make_shared<FakeTransport>(
-        RDMA, FakeTransport::PollStatusFactory{}, true);
+        RDMA,
+        [&complete_first](const Request& request, int) {
+            if (!complete_first.load()) {
+                return TransferStatus{TransferStatusEnum::PENDING, 0};
+            }
+            return TransferStatus{TransferStatusEnum::COMPLETED,
+                                  request.length};
+        },
+        true);
     installFakeRdma(engine, fake_rdma);
 
     constexpr size_t kReqLen = 4096;
@@ -518,6 +552,9 @@ TEST(RuntimeQueueDispatch, ProgressWorkerRefillsWindowFromTransportNotify) {
             .ok());
     EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
 
+    complete_first.store(true);
+    fake_rdma->notifyLastBatch();
+
     const auto deadline =
         std::chrono::steady_clock::now() + std::chrono::milliseconds(1000);
     while (std::chrono::steady_clock::now() < deadline &&
@@ -627,39 +664,236 @@ TEST(RuntimeQueueDispatch, EarlyFreeReclaimsAfterQueuedCompletion) {
 }
 
 TEST(RuntimeQueueDispatch, PollingDerivedTaskCompletesMergedOwner) {
-    auto cfg = makeRuntimeQueueConfig(1, 1UL << 20, true);
-    TransferEngineImpl engine(cfg);
-    ASSERT_TRUE(engine.available());
-
-    auto fake_rdma = std::make_shared<FakeTransport>(RDMA);
-    installFakeRdma(engine, fake_rdma);
-
-    constexpr size_t kReqLen = 4096;
-    std::vector<uint8_t> buffer(kReqLen * 2, 0x44);
-    ASSERT_TRUE(engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+    for (bool queue : {false, true}) {
+        auto cfg = makeRuntimeQueueConfig(1, 1UL << 20, true);
+        cfg->set("enable_runtime_queue", queue);
+        cfg->set("enable_progress_worker", false);
+        TransferEngineImpl engine(cfg);
+        ASSERT_TRUE(engine.available());
+
+        auto fake_rdma = std::make_shared<FakeTransport>(
+            RDMA, [](const Request& request, int) {
+                EXPECT_EQ(request.length, 32u);
+                return TransferStatus{COMPLETED, request.length};
+            });
+        installFakeRdma(engine, fake_rdma);
+
+        constexpr size_t kReqLen = 16;
+        std::vector<uint8_t> buffer(kReqLen * 2, 0x44);
+        ASSERT_TRUE(
+            engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+
+        BatchID batch = engine.allocateBatch(2);
+        ASSERT_NE(batch, (BatchID)0);
+
+        ASSERT_TRUE(
+            engine
+                .submitTransfer(
+                    batch, {makeLocalWrite(buffer.data(), kReqLen),
+                            makeLocalWrite(buffer.data() + kReqLen, kReqLen)})
+                .ok());
+        EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+
+        TransferStatus derived{};
+        ASSERT_TRUE(engine.getTransferStatus(batch, 1, derived).ok());
+        EXPECT_EQ(derived.s, TransferStatusEnum::COMPLETED);
+        EXPECT_EQ(derived.transferred_bytes, 16u);
+
+        TransferStatus owner{};
+        ASSERT_TRUE(engine.getTransferStatus(batch, 0, owner).ok());
+        EXPECT_EQ(owner.s, TransferStatusEnum::COMPLETED);
+        EXPECT_EQ(owner.transferred_bytes, 16u);
+        for (int poll = 0; poll < 2; ++poll) {
+            std::vector<TransferStatus> tasks;
+            ASSERT_TRUE(engine.getTransferStatus(batch, tasks).ok());
+            ASSERT_EQ(tasks.size(), 2u);
+            for (const auto& status : tasks) {
+                EXPECT_EQ(status.s, COMPLETED);
+                EXPECT_EQ(status.transferred_bytes, 16u);
+            }
+            TransferStatus total{};
+            ASSERT_TRUE(engine.getTransferStatus(batch, total).ok());
+            EXPECT_EQ(total.s, COMPLETED);
+            EXPECT_EQ(total.transferred_bytes, 32u);
+        }
 
-    BatchID batch = engine.allocateBatch(2);
-    ASSERT_NE(batch, (BatchID)0);
+        EXPECT_TRUE(engine.freeBatch(batch).ok());
+        EXPECT_TRUE(
+            engine.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+    }
+}
 
-    ASSERT_TRUE(
-        engine
-            .submitTransfer(batch,
-                            {makeLocalWrite(buffer.data(), kReqLen),
-                             makeLocalWrite(buffer.data() + kReqLen, kReqLen)})
-            .ok());
-    EXPECT_EQ(fake_rdma->submit_calls.load(), 1);
+TEST(RuntimeQueueDispatch, BatchNotificationsFollowSubmitIntervals) {
+    for (auto initial : {FAILED, PENDING}) {
+        for (bool same_submit : {false, true}) {
+            SCOPED_TRACE(testing::Message() << initial << "/" << same_submit);
+            auto cfg = makeRuntimeQueueConfig(4, 1024, true);
+            cfg->set("enable_runtime_queue", false);
+            cfg->set("enable_progress_worker", false);
+            cfg->set("enable_auto_failover_on_poll", false);
+            TransferEngineImpl engine(cfg);
+            std::vector<uint8_t> buffer(128);
+            auto second_status = initial;
+            auto fake = std::make_shared<FakeTransport>(
+                RDMA, [&](const Request& request, int) -> TransferStatus {
+                    if (request.source == buffer.data()) {
+                        EXPECT_EQ(request.length, 32u);
+                    }
+                    auto status = request.source == buffer.data() + 64
+                                      ? second_status
+                                      : COMPLETED;
+                    return {status, status == COMPLETED ? request.length : 0};
+                });
+            installFakeRdma(engine, fake);
+            ASSERT_TRUE(
+                engine.registerLocalMemory(buffer.data(), buffer.size()).ok());
+            std::vector<Request> first{makeLocalWrite(buffer.data(), 16),
+                                       makeLocalWrite(buffer.data() + 16, 16)};
+            auto second = makeLocalWrite(buffer.data() + 64, 16);
+            if (same_submit) first.push_back(second);
+            auto batch = engine.allocateBatch(3);
+            ASSERT_TRUE(
+                engine.submitTransfer(batch, first, {"first", "ready"}).ok());
+            if (!same_submit) {
+                ASSERT_TRUE(
+                    engine.submitTransfer(batch, {second}, {"second", "ready"})
+                        .ok());
+            }
+            for (int phase = 0; phase < 2; ++phase) {
+                size_t first_count = 0, second_count = 0;
+                for (int poll = 0; poll < 3; ++poll) {
+                    TransferStatus status{};
+                    ASSERT_TRUE(engine.getTransferStatus(batch, status).ok());
+                    EXPECT_EQ(status.s, second_status);
+                    std::vector<Notification> received;
+                    // No notification transport is installed; an empty poll
+                    // reports unsupported, but self notifications are
+                    // delivered.
+                    (void)engine.receiveNotification(received);
+                    for (const auto& item : received) {
+                        if (item.name == "first")
+                            ++first_count;
+                        else if (item.name == "second")
+                            ++second_count;
+                        else
+                            ADD_FAILURE() << item.name;
+                    }
+                }
+                EXPECT_EQ(first_count, phase == 0
+                                           ? !same_submit
+                                           : same_submit && initial == PENDING);
+                EXPECT_EQ(second_count,
+                          phase == 1 && !same_submit && initial == PENDING);
+                if (initial == PENDING) second_status = COMPLETED;
+            }
+            EXPECT_TRUE(engine.freeBatch(batch).ok());
+            EXPECT_TRUE(
+                engine.unregisterLocalMemory(buffer.data(), buffer.size())
+                    .ok());
+        }
+    }
+}
 
-    TransferStatus derived{};
-    ASSERT_TRUE(engine.getTransferStatus(batch, 1, derived).ok());
-    EXPECT_EQ(derived.s, TransferStatusEnum::COMPLETED);
+class RangeOnlyRecordingTransport : public FakeTransport {
+   public:
+    explicit RangeOnlyRecordingTransport(TransportType type,
+                                         PollStatusFactory poll)
+        : FakeTransport(type, std::move(poll)) {}
+    static constexpr uint64_t kRange = uint64_t{1} << 34;
+    std::vector<Request> posted;
 
-    TransferStatus owner{};
-    ASSERT_TRUE(engine.getTransferStatus(batch, 0, owner).ok());
-    EXPECT_EQ(owner.s, TransferStatusEnum::COMPLETED);
+    Status addMemoryBuffer(BufferDesc& desc,
+                           const MemoryOptions& options) override {
+        // Only the descriptor is large. The fake never accesses its payload.
+        desc.length = kRange;
+        return FakeTransport::addMemoryBuffer(desc, options);
+    }
+    Status submitTransferTasks(SubBatchRef batch,
+                               const std::vector<Request>& requests) override {
+        posted.insert(posted.end(), requests.begin(), requests.end());
+        return FakeTransport::submitTransferTasks(batch, requests);
+    }
+};
 
-    EXPECT_TRUE(engine.freeBatch(batch).ok());
-    EXPECT_TRUE(
-        engine.unregisterLocalMemory(buffer.data(), buffer.size()).ok());
+TEST(RuntimeQueueDispatch, TcpCapsPreservePublicMappingAndOwnerBytes) {
+    for (auto type : {TCP, RDMA, HP_TCP}) {
+        for (auto hint : {UNSPEC, type}) {
+            for (auto opcode : {Request::READ, Request::WRITE}) {
+                SCOPED_TRACE(testing::Message()
+                             << type << "/" << hint << "/" << opcode);
+                const auto cap = tcpMaxTransferBytes(opcode);
+                auto cfg = makeRuntimeQueueConfig(3, 1024, true);
+                cfg->set("enable_runtime_queue", false);
+                cfg->set("enable_progress_worker", false);
+                TransferEngineImpl engine(cfg);
+                std::vector<uint8_t> buffer(64);
+                const auto addr = reinterpret_cast<uintptr_t>(buffer.data());
+                auto tail_status = PENDING;
+                auto fake = std::make_shared<RangeOnlyRecordingTransport>(
+                    type, [&](const Request& request, int) -> TransferStatus {
+                        auto status = reinterpret_cast<uintptr_t>(
+                                          request.source) == addr + cap
+                                          ? tail_status
+                                          : COMPLETED;
+                        return {status,
+                                status == COMPLETED ? request.length : 0};
+                    });
+                engine.swapTransportForTest(type, fake);
+                ASSERT_TRUE(
+                    engine.registerLocalMemory(buffer.data(), buffer.size())
+                        .ok());
+                std::vector<Request> requests;
+                uint64_t offset = 0;
+                for (size_t length : {cap - 1, size_t{1}, size_t{1}}) {
+                    auto request = makeLocalWrite(buffer.data(), length);
+                    request.source = reinterpret_cast<void*>(addr + offset);
+                    request.target_offset = addr + offset;
+                    request.opcode = opcode;
+                    request.transport_hint = hint;
+                    requests.push_back(request);
+                    offset += length;
+                }
+                auto batch = engine.allocateBatch(3);
+                ASSERT_TRUE(engine.submitTransfer(batch, requests).ok());
+                ASSERT_EQ(fake->posted.size(), type == TCP ? 2u : 1u);
+                EXPECT_EQ(fake->posted[0].length, type == TCP ? cap : cap + 1);
+                EXPECT_EQ(fake->posted[0].source, buffer.data());
+                EXPECT_EQ(fake->posted[0].target_offset, addr);
+                if (type == TCP) {
+                    EXPECT_EQ(fake->posted[1].length, 1u);
+                    EXPECT_EQ(
+                        reinterpret_cast<uintptr_t>(fake->posted[1].source),
+                        addr + cap);
+                    EXPECT_EQ(fake->posted[1].target_offset, addr + cap);
+                }
+                for (int poll = 0; poll < 3; ++poll) {
+                    for (size_t task = 0; task < requests.size(); ++task) {
+                        TransferStatus status{};
+                        ASSERT_TRUE(
+                            engine.getTransferStatus(batch, task, status).ok());
+                        const bool pending =
+                            type == TCP && poll == 0 && task == 2;
+                        EXPECT_EQ(status.s, pending ? PENDING : COMPLETED);
+                        EXPECT_EQ(status.transferred_bytes,
+                                  pending ? 0 : requests[task].length);
+                    }
+                    TransferStatus status{};
+                    ASSERT_TRUE(engine.getTransferStatus(batch, status).ok());
+                    EXPECT_EQ(status.s,
+                              type == TCP && poll == 0 ? PENDING : COMPLETED);
+                    EXPECT_EQ(status.transferred_bytes,
+                              type == TCP && poll == 0 ? cap : cap + 1);
+                    tail_status = COMPLETED;
+                }
+                EXPECT_TRUE(engine.freeBatch(batch).ok());
+                EXPECT_TRUE(
+                    engine
+                        .unregisterLocalMemory(
+                            buffer.data(), RangeOnlyRecordingTransport::kRange)
+                        .ok());
+            }
+        }
+    }
 }
 
 }  // namespace
diff --git a/mooncake-transfer-engine/tent/tests/segment_desc_retry.md b/mooncake-transfer-engine/tent/tests/segment_desc_retry.md
new file mode 100644
index 0000000000..b33489dd8d
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/segment_desc_retry.md
@@ -0,0 +1,43 @@
+# GetSegmentDesc 重启恢复测试
+
+## 契约
+
+`ControlClient::getSegmentDesc` 首次遇到 `RpcServiceError` 时额外尝试一次，
+成功及其他错误直接返回。重试只限于读取本端描述的只读 RPC，不改变通用
+`CoroRpcAgent` 和其他 ControlClient 操作的重放语义。
+
+RPC 连接池按线程隔离。同地址服务重启后，某线程成功刷新不代表其他线程的
+旧连接已更新。底层 RPC 在旧连接失败后丢弃该连接；只读调用的第二次尝试可
+建立新连接。若对端仍不可用，最终返回第二次错误，不伪造成功。
+
+“有界”指最多两次 RPC 尝试，仍沿用每次 RPC 的既有超时，不新增总 deadline、
+循环退避或后台重试。健康路径不增加 RPC、锁或 sleep；这不等于承诺零 CPU
+开销。WR/CQ、bootstrap、notify 等路径不受此重试逻辑影响。
+
+## 运行
+
+在 Linux 上按仓库方式启用 `USE_TENT=ON`、`BUILD_UNIT_TESTS=ON` 后：
+
+```bash
+cmake --build build --target tent_segment_desc_retry_test tent_rpc_reconnect_test
+ctest --test-dir build -R 'tent_(segment_desc_retry|rpc_reconnect)_test' --output-on-failure
+build/mooncake-transfer-engine/tent/tests/tent_segment_desc_retry_test --gtest_repeat=20 --gtest_shuffle
+```
+
+新增测试通过真实 ControlClient、CoroRpcAgent 和 loopback socket 覆盖：
+
+- 同端口重启后第一次读取获得新代次描述。
+- 前台已恢复后，长驻 worker 的独立旧池也在第一次读取内恢复。
+- 健康 handler 仅执行一次；持续报错 handler 恰好执行两次。
+- 对端持续失联返回失败；通知副作用仍只执行一次。
+
+每项在独立调用线程运行以隔离 thread-local 池；重启必须保持原端口。
+100ms FIN 前置等待沿用 `rpc_reconnect_test`，不是生产重试策略。
+这些测试不依赖 RDMA 硬件，也不单独证明 RDMA 数据面重启恢复或性能无回退；
+后两项需使用长驻 engine 的双机恢复和独立性能测试验证。
+
+## 兼容与回滚
+
+无需 API、wire format 或配置迁移。调用方可能少看到一次可恢复错误，持续失效
+路径最多多耗费一次 RPC 尝试。回退此独立修复即可恢复原单次调用行为；不要通过
+给通用 RPC 加自动重试来替代它，有副作用的操作可能被执行两次。
diff --git a/mooncake-transfer-engine/tent/tests/segment_desc_retry_test.cpp b/mooncake-transfer-engine/tent/tests/segment_desc_retry_test.cpp
new file mode 100644
index 0000000000..7ab569e3af
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/segment_desc_retry_test.cpp
@@ -0,0 +1,216 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <utility>
+
+#include "tent/rpc/rpc.h"
+#include "tent/runtime/control_plane.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+using namespace std::chrono_literals;
+
+template <typename TestBody>
+void WithFreshCaller(TestBody body) {
+    // ControlClient pools are thread-local. Isolate cases even if a later
+    // server randomly selects a port used by an earlier test or repetition.
+    std::thread caller(std::move(body));
+    caller.join();
+}
+
+class SegmentDescRetryTest : public ::testing::Test {
+   protected:
+    struct Result {
+        Status status;
+        std::string response;
+    };
+
+    Result Read() {
+        Result result;
+        result.status = ControlClient::getSegmentDesc(addr_, result.response);
+        return result;
+    }
+
+    Status StartServer(const std::string& epoch) {
+        server_ = std::make_unique<CoroRpcAgent>();
+        CHECK_STATUS(server_->registerFunction(
+            GetSegmentDesc,
+            [this, epoch](const std::string_view&, std::string& response) {
+                metadata_calls_.fetch_add(1);
+                if (fail_metadata_.load()) {
+                    throw std::runtime_error("metadata handler failed");
+                }
+                response = epoch;
+            }));
+        CHECK_STATUS(server_->registerFunction(
+            Notify, [this](const std::string_view&, std::string&) {
+                notifications_.fetch_add(1);
+                throw std::runtime_error("after notification side effect");
+            }));
+        const auto requested_port = port_;
+        CHECK_STATUS(server_->start(port_));
+        if (requested_port != 0 && port_ != requested_port) {
+            return Status::InvalidArgument("restart changed the peer port");
+        }
+        addr_ = "127.0.0.1:" + std::to_string(port_);
+        return Status::OK();
+    }
+
+    Status RestartServer() {
+        server_.reset();
+        // Match rpc_reconnect_test: let the old client sockets observe FIN.
+        std::this_thread::sleep_for(100ms);
+        return StartServer("epoch2");
+    }
+
+    void TearDown() override {
+        // A fatal assertion must still release and join the parked worker.
+        if (worker_.joinable()) {
+            if (!released_) resume_.set_value();
+            worker_.join();
+        }
+        server_.reset();
+    }
+
+    std::unique_ptr<CoroRpcAgent> server_;
+    uint16_t port_ = 0;
+    std::string addr_;
+    std::atomic<int> metadata_calls_{0};
+    std::atomic<int> notifications_{0};
+    std::atomic<bool> fail_metadata_{false};
+    std::promise<void> warmed_;
+    std::promise<void> resume_;
+    std::thread worker_;
+    bool released_ = false;
+    Result worker_warm_;
+    Result worker_after_restart_;
+    bool worker_resumed_ = false;
+};
+
+TEST_F(SegmentDescRetryTest, FirstMetadataCallRecoversAfterSamePortRestart) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        const auto warm = Read();
+        ASSERT_TRUE(warm.status.ok()) << warm.status.ToString();
+        ASSERT_EQ(warm.response, "epoch1");
+        ASSERT_TRUE(RestartServer().ok());
+
+        const auto result = Read();
+        EXPECT_TRUE(result.status.ok()) << result.status.ToString();
+        EXPECT_EQ(result.response, "epoch2");
+        EXPECT_EQ(metadata_calls_.load(), 2);
+    });
+}
+
+TEST_F(SegmentDescRetryTest, WorkerRecoversAfterMainRefreshesItsOwnPool) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        const auto warm = Read();
+        ASSERT_TRUE(warm.status.ok()) << warm.status.ToString();
+        ASSERT_EQ(warm.response, "epoch1");
+
+        auto warmed = warmed_.get_future();
+        auto resume = resume_.get_future();
+        worker_ = std::thread([this, resume = std::move(resume)] {
+            worker_warm_ = Read();
+            warmed_.set_value();
+            if (resume.wait_for(10s) != std::future_status::ready) return;
+            worker_resumed_ = true;
+            worker_after_restart_ = Read();
+        });
+        ASSERT_EQ(warmed.wait_for(10s), std::future_status::ready);
+        ASSERT_TRUE(worker_warm_.status.ok()) << worker_warm_.status.ToString();
+        ASSERT_EQ(worker_warm_.response, "epoch1");
+        ASSERT_TRUE(RestartServer().ok());
+
+        // Recover main even on the original implementation, so a worker failure
+        // specifically demonstrates its independent thread-local stale pool.
+        auto main_result = Read();
+        if (!main_result.status.ok()) main_result = Read();
+        ASSERT_TRUE(main_result.status.ok()) << main_result.status.ToString();
+        ASSERT_EQ(main_result.response, "epoch2");
+
+        released_ = true;
+        resume_.set_value();
+        worker_.join();
+        ASSERT_TRUE(worker_resumed_);
+        EXPECT_TRUE(worker_after_restart_.status.ok())
+            << worker_after_restart_.status.ToString();
+        EXPECT_EQ(worker_after_restart_.response, "epoch2");
+        EXPECT_EQ(metadata_calls_.load(), 4);
+    });
+}
+
+TEST_F(SegmentDescRetryTest, HealthyMetadataHandlerRunsOnce) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        const auto result = Read();
+        EXPECT_TRUE(result.status.ok()) << result.status.ToString();
+        EXPECT_EQ(result.response, "epoch1");
+        EXPECT_EQ(metadata_calls_.load(), 1);
+    });
+}
+
+TEST_F(SegmentDescRetryTest, ThrowingMetadataHandlerRunsExactlyTwice) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        fail_metadata_.store(true);
+        const auto result = Read();
+        EXPECT_TRUE(result.status.IsRpcServiceError())
+            << result.status.ToString();
+        EXPECT_TRUE(result.response.empty());
+        EXPECT_EQ(metadata_calls_.load(), 2);
+    });
+}
+
+TEST_F(SegmentDescRetryTest, DeadPeerStillReturnsFailure) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        const auto warm = Read();
+        ASSERT_TRUE(warm.status.ok()) << warm.status.ToString();
+        server_.reset();
+        std::this_thread::sleep_for(100ms);
+
+        const auto result = Read();
+        EXPECT_TRUE(result.status.IsRpcServiceError())
+            << result.status.ToString();
+        EXPECT_TRUE(result.response.empty());
+        EXPECT_EQ(metadata_calls_.load(), 1);
+    });
+}
+
+TEST_F(SegmentDescRetryTest, NotificationSideEffectIsNotReplayed) {
+    WithFreshCaller([&] {
+        ASSERT_TRUE(StartServer("epoch1").ok());
+        const auto status =
+            ControlClient::notify(addr_, Notification{"test", "once"});
+        EXPECT_TRUE(status.IsRpcServiceError()) << status.ToString();
+        EXPECT_EQ(notifications_.load(), 1);
+    });
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/segment_manager_test.cpp b/mooncake-transfer-engine/tent/tests/segment_manager_test.cpp
index 77bb31d7fc..5a22dc876d 100644
--- a/mooncake-transfer-engine/tent/tests/segment_manager_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/segment_manager_test.cpp
@@ -186,6 +186,60 @@ TEST(SegmentTrackerTest, AddInBatchCallbackFailureRollsBackRefCounts) {
     EXPECT_TRUE(buffersOf(manager->getLocal()).empty());
 }
 
+TEST(SegmentTrackerTest, FailedBatchHandsOffLastReferenceOutsideWriterLock) {
+    auto manager = makeManager();
+    SegmentTracker tracker(*manager);
+    auto buffer = makeBuffer(0x30000, 0x1000);
+    buffer.transports = {HP_TCP};
+    buffer.transport_attrs[HP_TCP] = "old-registration";
+    buffer.lkey = {7};
+    auto ok = [](std::vector<BufferDesc>&) -> Status { return Status::OK(); };
+    std::vector<BufferDesc> first{buffer};
+    ASSERT_TRUE(tracker.addInBatch(first, ok).ok());
+
+    int owner_removals = 0;
+    int rollback_removals = 0;
+    const auto failure = Status::InternalError("injected transport failure");
+    // Both duplicate pins must be released; only the last one hands off.
+    std::vector<BufferDesc> duplicates{buffer, buffer};
+    auto status = tracker.addInBatch(
+        duplicates,
+        [&](std::vector<BufferDesc>&) -> Status {
+            EXPECT_TRUE(tracker
+                            .remove(buffer.addr, buffer.length,
+                                    [&](BufferDesc&) -> Status {
+                                        owner_removals++;
+                                        return Status::OK();
+                                    })
+                            .ok());
+            EXPECT_EQ(owner_removals, 0);
+            return failure;
+        },
+        [&](BufferDesc& removed) {
+            rollback_removals++;
+            EXPECT_EQ(removed.addr, buffer.addr);
+            EXPECT_EQ(removed.length, buffer.length);
+            EXPECT_EQ(removed.location, buffer.location);
+            EXPECT_EQ(removed.transports, buffer.transports);
+            EXPECT_EQ(removed.transport_attrs, buffer.transport_attrs);
+            EXPECT_EQ(removed.lkey, buffer.lkey);
+            EXPECT_EQ(removed.ref_count, 0);
+            EXPECT_TRUE(buffersOf(manager->getLocal()).empty());
+            // A writer can publish from the callback: the lock is released.
+            EXPECT_TRUE(manager
+                            ->updateLocal([](SegmentDesc& desc) -> Status {
+                                desc.name = "cleanup_callback";
+                                return Status::OK();
+                            })
+                            .ok());
+        });
+    EXPECT_EQ(status.code(), failure.code());
+    EXPECT_EQ(status.message(), failure.message());
+    EXPECT_EQ(rollback_removals, 1);
+    EXPECT_TRUE(buffersOf(manager->getLocal()).empty());
+    EXPECT_EQ(manager->getLocal()->name, "cleanup_callback");
+}
+
 TEST(SegmentTrackerTest, AddProbesRealMemoryAndRefCounts) {
     auto manager = makeManager();
     SegmentTracker tracker(*manager);
diff --git a/mooncake-transfer-engine/tent/tests/shm_transport_test.cpp b/mooncake-transfer-engine/tent/tests/shm_transport_test.cpp
index bf8f99ba01..d9a8af447d 100644
--- a/mooncake-transfer-engine/tent/tests/shm_transport_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/shm_transport_test.cpp
@@ -366,6 +366,66 @@ TEST(ShmTransportTest, NeedsRefreshCacheKeepsExistingMappings) {
     ASSERT_TRUE(transport.uninstall().ok());
 }
 
+// Regression for the all-or-nothing submission contract: a mid-batch
+// relocation failure (the second of three requests targets an unknown
+// segment) must return an error without executing any transfer. The
+// sub-batch must stay empty and the valid first request's data must not
+// have been copied, otherwise the engine's submit-stage failover would
+// execute the accepted prefix twice.
+TEST(ShmTransportTest, SubmitIsAllOrNothingWhenRelocateFailsMidBatch) {
+    constexpr size_t kLen = 16;
+    constexpr SegmentID kUnknownSegment = 0x7fff;
+
+    auto metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+    ShmTransport transport;
+    std::string local_segment_name = "shm_test_segment";
+    ASSERT_TRUE(transport
+                    .install(local_segment_name, metadata, nullptr,
+                             std::make_shared<Config>())
+                    .ok());
+
+    Transport::SubBatchRef batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(batch, 8).ok());
+
+    // Real destination memory for the valid requests; stays zeroed unless
+    // a transfer executes despite the mid-batch failure.
+    std::vector<uint8_t> target(kLen, 0);
+    std::vector<uint8_t> source(kLen, 0xA5);
+    auto makeRequest = [&](SegmentID target_id, uint64_t target_offset) {
+        Request req;
+        req.opcode = Request::WRITE;
+        req.source = source.data();
+        req.target_id = target_id;
+        req.target_offset = target_offset;
+        req.length = kLen;
+        return req;
+    };
+    std::vector<Request> requests{
+        makeRequest(LOCAL_SEGMENT_ID,
+                    reinterpret_cast<uint64_t>(target.data())),
+        // Unknown target segment: relocation fails fast with an error.
+        makeRequest(kUnknownSegment, 0x1000),
+        makeRequest(LOCAL_SEGMENT_ID,
+                    reinterpret_cast<uint64_t>(target.data()))};
+
+    auto status = transport.submitTransferTasks(batch, requests);
+    EXPECT_FALSE(status.ok());
+
+    // Nothing was accepted: the sub-batch is unchanged.
+    auto* shm_batch = dynamic_cast<ShmSubBatch*>(batch);
+    ASSERT_NE(shm_batch, nullptr);
+    EXPECT_EQ(shm_batch->task_list.size(), 0u);
+    TransferStatus ts{};
+    EXPECT_FALSE(transport.getTransferStatus(batch, 0, ts).ok());
+
+    // Nothing was executed: the target still reads as zeroed (the old
+    // per-request loop would have already copied request 0's pattern).
+    for (size_t i = 0; i < kLen; ++i) EXPECT_EQ(target[i], 0u);
+
+    ASSERT_TRUE(transport.freeSubBatch(batch).ok());
+    ASSERT_TRUE(transport.uninstall().ok());
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/stage_buffer_concurrency_test.cpp b/mooncake-transfer-engine/tent/tests/stage_buffer_concurrency_test.cpp
new file mode 100644
index 0000000000..00f58ffec6
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/stage_buffer_concurrency_test.cpp
@@ -0,0 +1,228 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// ProxyManager::stage_buffers_ is reached from the kShards staging workers via
+// StageBufferCache::allocateLocal and from the RPC thread via Pin/Unpin. The
+// chunk bitmaps are atomic_flags, but the map holding them was unsynchronised,
+// so a first-time pin could rehash under another thread's find.
+//
+// These drive the map concurrently. The unlocked failure is a rehash race,
+// which a plain run may not reproduce -- run under -fsanitize=thread for that.
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <cstdlib>
+#include <memory>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/proxy_manager.h"
+#include "tent/runtime/segment.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/runtime/transport.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class FakeSubBatch : public Transport::SubBatch {
+   public:
+    size_t size() const override { return 0; }
+};
+
+// Only the memory hooks matter here: ProxyManager allocates and registers a
+// stage buffer through the engine, which forwards to the transport.
+class FakeTransport : public Transport {
+   public:
+    FakeTransport() { caps.dram_to_dram = true; }
+
+    Status install(std::string&, std::shared_ptr<ControlService>,
+                   std::shared_ptr<Topology>,
+                   std::shared_ptr<Config> = nullptr) override {
+        return Status::OK();
+    }
+
+    Status allocateSubBatch(SubBatchRef& batch, size_t) override {
+        batch = new FakeSubBatch();
+        return Status::OK();
+    }
+
+    Status freeSubBatch(SubBatchRef& batch) override {
+        delete batch;
+        batch = nullptr;
+        return Status::OK();
+    }
+
+    Status submitTransferTasks(SubBatchRef,
+                               const std::vector<Request>&) override {
+        return Status::OK();
+    }
+
+    Status getTransferStatus(SubBatchRef, int,
+                             TransferStatus& status) override {
+        status = {TransferStatusEnum::COMPLETED, 0};
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(BufferDesc& desc, const MemoryOptions&) override {
+        desc.transports.push_back(RDMA);
+        return Status::OK();
+    }
+
+    Status addMemoryBuffer(std::vector<BufferDesc>& desc_list,
+                           const MemoryOptions& options) override {
+        for (auto& d : desc_list) {
+            auto s = addMemoryBuffer(d, options);
+            if (!s.ok()) return s;
+        }
+        return Status::OK();
+    }
+
+    Status removeMemoryBuffer(BufferDesc&) override { return Status::OK(); }
+
+    Status allocateLocalMemory(void** addr, size_t size,
+                               MemoryOptions&) override {
+        *addr = std::malloc(size);
+        if (!*addr) return Status::InternalError("malloc failed" LOC_MARK);
+        return Status::OK();
+    }
+
+    Status freeLocalMemory(void* addr, size_t) override {
+        std::free(addr);
+        return Status::OK();
+    }
+
+    bool warmupMemory(void*, size_t) override { return false; }
+
+    const char* getName() const override { return "<fake>"; }
+};
+
+std::shared_ptr<Config> makeLoopbackP2PConfig() {
+    auto cfg = std::make_shared<Config>();
+    cfg->set("metadata_type", "p2p");
+    cfg->set("metadata_servers", "");
+    cfg->set("rpc_server_hostname", "127.0.0.1");
+    cfg->set("rpc_server_port", "0");
+    cfg->set("log_level", "warning");
+    cfg->set("transports/tcp/enable", false);
+    cfg->set("transports/shm/enable", false);
+    cfg->set("transports/rdma/enable", false);
+    cfg->set("transports/io_uring/enable", false);
+    cfg->set("transports/nvlink/enable", false);
+    cfg->set("transports/mnnvl/enable", false);
+    cfg->set("transports/gds/enable", false);
+    cfg->set("transports/ascend_direct/enable", false);
+    return cfg;
+}
+
+// Small enough to keep the test cheap; ProxyManager's real default would
+// allocate 4 MiB x 64 per location.
+constexpr size_t kChunkSize = 4096;
+constexpr size_t kChunkCount = 8;
+
+class StageBufferConcurrencyTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        engine_ = std::make_unique<TransferEngineImpl>(makeLoopbackP2PConfig());
+        ASSERT_TRUE(engine_->available());
+        auto fake = std::make_shared<FakeTransport>();
+        std::string seg_name = engine_->getSegmentName();
+        ASSERT_TRUE(fake->install(seg_name, nullptr, nullptr).ok());
+        engine_->swapTransportForTest(RDMA, fake);
+        proxy_ = std::make_unique<ProxyManager>(engine_.get(), kChunkSize,
+                                                kChunkCount);
+    }
+
+    // Destruction only: ProxyManager::deconstruct() joins its workers and is
+    // not idempotent, so calling it here as well would join twice.
+    void TearDown() override { proxy_.reset(); }
+
+    std::unique_ptr<TransferEngineImpl> engine_;
+    std::unique_ptr<ProxyManager> proxy_;
+};
+
+// The dangerous shape: every thread inserts a different entry at the same
+// time, so inserts and lookups overlap.
+TEST_F(StageBufferConcurrencyTest, ConcurrentFirstPinOfDistinctLocations) {
+    constexpr int kThreads = 8;
+    std::vector<std::thread> threads;
+    std::atomic<int> succeeded{0};
+    std::vector<uint64_t> addrs(kThreads, 0);
+
+    for (int i = 0; i < kThreads; ++i) {
+        threads.emplace_back([&, i] {
+            uint64_t addr = 0;
+            if (proxy_->pinStageBuffer("cpu:" + std::to_string(i), addr).ok()) {
+                addrs[i] = addr;
+                succeeded.fetch_add(1);
+            }
+        });
+    }
+    for (auto& t : threads) t.join();
+
+    EXPECT_EQ(succeeded.load(), kThreads);
+    std::set<uint64_t> unique(addrs.begin(), addrs.end());
+    EXPECT_EQ(unique.size(), static_cast<size_t>(kThreads))
+        << "two locations handed out the same chunk";
+}
+
+// Same entry from every thread: the bitmap must hand each caller its own
+// chunk, and the entry must be created exactly once.
+TEST_F(StageBufferConcurrencyTest,
+       ConcurrentPinOfOneLocationHandsOutDistinctChunks) {
+    std::vector<std::thread> threads;
+    std::vector<uint64_t> addrs(kChunkCount, 0);
+
+    for (size_t i = 0; i < kChunkCount; ++i) {
+        threads.emplace_back([&, i] {
+            uint64_t addr = 0;
+            if (proxy_->pinStageBuffer("cpu:0", addr).ok()) addrs[i] = addr;
+        });
+    }
+    for (auto& t : threads) t.join();
+
+    std::set<uint64_t> unique(addrs.begin(), addrs.end());
+    EXPECT_EQ(unique.size(), kChunkCount) << "a chunk was pinned twice";
+    EXPECT_EQ(unique.count(0), 0u) << "a pin failed";
+}
+
+// Unpin walks the whole map, so it reads entries other threads are inserting.
+TEST_F(StageBufferConcurrencyTest, PinAndUnpinOverlap) {
+    constexpr int kThreads = 8;
+    std::vector<std::thread> threads;
+    std::atomic<int> failures{0};
+
+    for (int i = 0; i < kThreads; ++i) {
+        threads.emplace_back([&, i] {
+            const std::string location = "cpu:" + std::to_string(i % 4);
+            for (int round = 0; round < 32; ++round) {
+                uint64_t addr = 0;
+                if (!proxy_->pinStageBuffer(location, addr).ok()) continue;
+                if (!proxy_->unpinStageBuffer(addr).ok()) failures.fetch_add(1);
+            }
+        });
+    }
+    for (auto& t : threads) t.join();
+
+    EXPECT_EQ(failures.load(), 0);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/strict_local_numa_test.cpp b/mooncake-transfer-engine/tent/tests/strict_local_numa_test.cpp
new file mode 100644
index 0000000000..e381c9c48a
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/strict_local_numa_test.cpp
@@ -0,0 +1,294 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/topology.h"
+#include "tent/transport/rdma/quota.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+// cuda:0 (NUMA 0): local dev 0 + remote dev 1. cuda:1 (NUMA 2): only remote
+// dev 1.
+constexpr const char* kTwoTierTopology = R"json(
+{
+  "nics": [
+    {"name": "mlx5_local", "type": 0, "numa_node": 0},
+    {"name": "mlx5_remote", "type": 0, "numa_node": 1}
+  ],
+  "mems": [
+    {"name": "cuda:0", "type": 1, "numa_node": 0,
+     "device_list": {"rank0": [0], "rank2": [1]}},
+    {"name": "cuda:1", "type": 1, "numa_node": 2,
+     "device_list": {"rank2": [1]}}
+  ]
+}
+)json";
+
+// Unknown NIC or memory NUMA (-1) must stay selectable.
+constexpr const char* kUnknownNumaTopology = R"json(
+{
+  "nics": [
+    {"name": "mlx5_known", "type": 0, "numa_node": 1},
+    {"name": "mlx5_bond_0", "type": 0, "numa_node": -1}
+  ],
+  "mems": [
+    {"name": "cuda:0", "type": 1, "numa_node": 0,
+     "device_list": {"rank2": [1]}},
+    {"name": "*", "type": 4, "numa_node": -1,
+     "device_list": {"rank2": [0, 1]}}
+  ]
+}
+)json";
+
+// Remote NIC in rank 0 (ROCm / MemoryProber closest-PCIe shape).
+constexpr const char* kRemoteNicInFirstRankTopology = R"json(
+{
+  "nics": [
+    {"name": "mlx5_close_remote", "type": 0, "numa_node": 1},
+    {"name": "mlx5_far_local", "type": 0, "numa_node": 0}
+  ],
+  "mems": [
+    {"name": "hip:0", "type": 2, "numa_node": 0,
+     "device_list": {"rank0": [0], "rank1": [1]}}
+  ]
+}
+)json";
+
+std::shared_ptr<Topology> makeTopology(const char* json = kTwoTierTopology) {
+    auto topo = std::make_shared<Topology>();
+    EXPECT_TRUE(topo->parse(json).ok());
+    return topo;
+}
+
+std::unique_ptr<DeviceSelector> makeSelector(std::shared_ptr<Topology> topo,
+                                             bool strict, bool smart) {
+    auto selector = std::make_unique<DeviceSelector>();
+    EXPECT_TRUE(selector->loadTopology(topo).ok());
+    DeviceSelector::SchedulingParams params;
+    params.strict_local_numa = strict;
+    // Isolate NUMA behavior from QoS priority rotation.
+    params.enable_priority_filtering = false;
+    selector->setSchedulingParams(params);
+    selector->setSmartSelection(smart);
+    return selector;
+}
+
+TEST(StrictLocalNumaTest, SmartModeNeverPicksCrossNumaWhenLocalExists) {
+    auto selector =
+        makeSelector(makeTopology(), /*strict=*/true, /*smart=*/true);
+    for (int i = 0; i < 64; ++i) {
+        std::vector<int> devs;
+        ASSERT_TRUE(selector->allocate(4096, 4, 1024, "cuda:0", devs).ok());
+        ASSERT_FALSE(devs.empty());
+        for (int dev : devs) EXPECT_EQ(dev, 0) << "iteration " << i;
+    }
+}
+
+TEST(StrictLocalNumaTest, SmartModeReturnsDeviceNotFoundWithoutLocalNic) {
+    auto selector =
+        makeSelector(makeTopology(), /*strict=*/true, /*smart=*/true);
+    std::vector<int> devs;
+    auto status = selector->allocate(4096, 4, 1024, "cuda:1", devs);
+    EXPECT_TRUE(status.IsDeviceNotFound()) << status.ToString();
+    EXPECT_TRUE(devs.empty());
+}
+
+TEST(StrictLocalNumaTest, NonStrictModeFallsBackToCrossNuma) {
+    auto selector =
+        makeSelector(makeTopology(), /*strict=*/false, /*smart=*/true);
+    std::vector<int> devs;
+    ASSERT_TRUE(selector->allocate(4096, 4, 1024, "cuda:1", devs).ok());
+    ASSERT_FALSE(devs.empty());
+    for (int dev : devs) EXPECT_EQ(dev, 1);
+}
+
+TEST(StrictLocalNumaTest, BaselineModeExcludesCrossNuma) {
+    auto selector =
+        makeSelector(makeTopology(), /*strict=*/true, /*smart=*/false);
+    for (int i = 0; i < 16; ++i) {
+        std::vector<int> devs;
+        ASSERT_TRUE(selector->allocate(4096, 4, 1024, "cuda:0", devs).ok());
+        ASSERT_FALSE(devs.empty());
+        for (int dev : devs) EXPECT_EQ(dev, 0);
+    }
+    std::vector<int> devs;
+    EXPECT_TRUE(
+        selector->allocate(4096, 4, 1024, "cuda:1", devs).IsDeviceNotFound());
+}
+
+TEST(StrictLocalNumaTest, BaselineNonStrictFallsBackToCrossNuma) {
+    auto selector =
+        makeSelector(makeTopology(), /*strict=*/false, /*smart=*/false);
+    std::vector<int> devs;
+    ASSERT_TRUE(selector->allocate(4096, 4, 1024, "cuda:1", devs).ok());
+    ASSERT_FALSE(devs.empty());
+    for (int dev : devs) EXPECT_EQ(dev, 1);
+}
+
+// Masking the local NIC must not fall back to the remote one under strict mode.
+TEST(StrictLocalNumaTest, FallbackDoesNotReintroduceCrossNuma) {
+    const uint64_t mask = ~(1ULL << 0);  // exclude the local NIC (dev 0)
+
+    auto strict = makeSelector(makeTopology(), /*strict=*/true, /*smart=*/true);
+    std::vector<int> devs;
+    auto status =
+        strict->allocate(4096, 4, 1024, "cuda:0", devs, PRIO_HIGH, mask);
+    EXPECT_TRUE(status.IsDeviceNotFound()) << status.ToString();
+    EXPECT_TRUE(devs.empty());
+
+    // Same mask without strict still reaches the remote NIC.
+    auto relaxed =
+        makeSelector(makeTopology(), /*strict=*/false, /*smart=*/true);
+    std::vector<int> relaxed_devs;
+    ASSERT_TRUE(
+        relaxed
+            ->allocate(4096, 4, 1024, "cuda:0", relaxed_devs, PRIO_HIGH, mask)
+            .ok());
+    ASSERT_FALSE(relaxed_devs.empty());
+    for (int dev : relaxed_devs) EXPECT_EQ(dev, 1);
+}
+
+TEST(StrictLocalNumaTest, UnknownNicNumaIsNotExcluded) {
+    for (bool smart : {true, false}) {
+        auto selector = makeSelector(makeTopology(kUnknownNumaTopology),
+                                     /*strict=*/true, smart);
+        std::vector<int> devs;
+        auto status = selector->allocate(4096, 4, 1024, "cuda:0", devs);
+        ASSERT_TRUE(status.ok()) << status.ToString() << ", smart=" << smart;
+        ASSERT_FALSE(devs.empty());
+        for (int dev : devs) EXPECT_EQ(dev, 1);
+    }
+}
+
+TEST(StrictLocalNumaTest, UnknownMemoryNumaIsNotExcluded) {
+    for (bool smart : {true, false}) {
+        auto selector = makeSelector(makeTopology(kUnknownNumaTopology),
+                                     /*strict=*/true, smart);
+        std::vector<int> devs;
+        auto status =
+            selector->allocate(4096, 4, 1024, kWildcardLocation, devs);
+        ASSERT_TRUE(status.ok()) << status.ToString() << ", smart=" << smart;
+        EXPECT_EQ(devs.size(), 4u);
+    }
+}
+
+TEST(StrictLocalNumaTest, RemoteNicPromotedToFirstRankIsStillExcluded) {
+    for (bool smart : {true, false}) {
+        auto selector =
+            makeSelector(makeTopology(kRemoteNicInFirstRankTopology),
+                         /*strict=*/true, smart);
+        std::vector<int> devs;
+        auto status = selector->allocate(4096, 4, 1024, "hip:0", devs);
+        ASSERT_TRUE(status.ok()) << status.ToString() << ", smart=" << smart;
+        ASSERT_FALSE(devs.empty());
+        // dev 0 is closest by PCIe but on another NUMA node.
+        for (int dev : devs) EXPECT_EQ(dev, 1) << "smart=" << smart;
+    }
+}
+
+// Priority matrix has no NUMA ids, so every NIC stays selectable.
+TEST(StrictLocalNumaTest, PriorityMatrixTopologyKeepsSoftPenalty) {
+    auto topo = std::make_shared<Topology>();
+    ASSERT_TRUE(topo->parsePriorityMatrix(
+                        R"json({"cpu:0": [["mlx5_0"], ["mlx5_1"]]})json")
+                    .ok());
+
+    for (bool smart : {true, false}) {
+        auto selector = makeSelector(topo, /*strict=*/true, smart);
+        std::vector<int> devs;
+        auto status = selector->allocate(4096, 4, 1024, "cpu:0", devs);
+        ASSERT_TRUE(status.ok()) << status.ToString() << ", smart=" << smart;
+        EXPECT_EQ(devs.size(), 4u);
+    }
+}
+
+TEST(StrictLocalNumaTest, IsCrossNumaRequiresBothSidesKnown) {
+    auto topo = makeTopology(kUnknownNumaTopology);
+    const auto* cuda0 = topo->getMemEntry("cuda:0");
+    const auto* wildcard = topo->getMemEntry(kWildcardLocation);
+    ASSERT_NE(cuda0, nullptr);
+    ASSERT_NE(wildcard, nullptr);
+
+    EXPECT_TRUE(topo->isCrossNuma(*cuda0, 0));   // both known, differ
+    EXPECT_FALSE(topo->isCrossNuma(*cuda0, 1));  // NIC unknown
+    EXPECT_FALSE(topo->isCrossNuma(*wildcard, 0));
+    EXPECT_FALSE(topo->isCrossNuma(*wildcard, 1));
+    EXPECT_FALSE(topo->isCrossNuma(*cuda0, 42));
+}
+
+class StrictLocalNumaEnvTest : public ::testing::Test {
+   protected:
+    // Isolate from an ambient MC_TENT_CONF.
+    void SetUp() override { unsetenv("MC_TENT_CONF"); }
+
+    void TearDown() override {
+        unsetenv("MC_STRICT_LOCAL_NUMA");
+        unsetenv("MC_IB_PORT");
+    }
+
+    static bool loadStrictFlag(const char* env_value, bool default_value) {
+        setenv("MC_STRICT_LOCAL_NUMA", env_value, 1);
+        Config config;
+        ConfigHelper helper;
+        EXPECT_TRUE(helper.loadFromEnv(config).ok());
+        return config.get("transports/rdma/strict_local_numa", default_value);
+    }
+};
+
+TEST_F(StrictLocalNumaEnvTest, AcceptsNumericAndTextualBooleans) {
+    for (const char* on : {"1", "true", "TRUE", "yes", "on"}) {
+        EXPECT_TRUE(loadStrictFlag(on, false)) << "value: " << on;
+    }
+    for (const char* off : {"0", "false", "no", "off"}) {
+        EXPECT_FALSE(loadStrictFlag(off, true)) << "value: " << off;
+    }
+}
+
+// Unparsable env must not overwrite an existing JSON value.
+TEST_F(StrictLocalNumaEnvTest, UnrecognizedValueKeepsConfiguredValue) {
+    setenv("MC_STRICT_LOCAL_NUMA", "maybe", 1);
+    ConfigHelper helper;
+
+    Config preset;
+    preset.set("transports/rdma/strict_local_numa", true);
+    ASSERT_TRUE(helper.loadFromEnv(preset).ok());
+    EXPECT_TRUE(preset.get("transports/rdma/strict_local_numa", false));
+
+    Config unset;
+    ASSERT_TRUE(helper.loadFromEnv(unset).ok());
+    EXPECT_FALSE(unset.get("transports/rdma/strict_local_numa", false));
+}
+
+// setFromString() must still store integer env vars as integers.
+TEST_F(StrictLocalNumaEnvTest, IntegerEnvVarsAreUnaffected) {
+    setenv("MC_IB_PORT", "1", 1);
+    Config config;
+    ConfigHelper helper;
+    ASSERT_TRUE(helper.loadFromEnv(config).ok());
+    EXPECT_EQ(config.get("transports/rdma/device/port", -1), 1);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/tcp_datapath_roundtrip_test.cpp b/mooncake-transfer-engine/tent/tests/tcp_datapath_roundtrip_test.cpp
new file mode 100644
index 0000000000..bcc6dd54b2
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/tcp_datapath_roundtrip_test.cpp
@@ -0,0 +1,333 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// End-to-end payload integrity test for the TENT TCP data path: a forked
+// server process serves a registered buffer over loopback, the client WRITEs
+// a pattern into it and READs it back, comparing byte for byte. This covers the
+// SendData/RecvData RPC handlers (including the copy-reduction paths in
+// ControlClient/ControlService) with DRAM and, when enabled, CUDA memory. No
+// RDMA is required.
+
+#include <gtest/gtest.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#ifdef USE_CUDA
+#include <cuda_runtime.h>
+#endif
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/transfer_engine.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr size_t kDataLength = 4 * 1024 * 1024;
+constexpr size_t kTaskCount = 8;
+constexpr size_t kStride = 8 * 1024 * 1024;
+constexpr size_t kBufferLength =
+    2 * kTaskCount * kStride;  // sources in first half, READ dests in second
+
+enum class TestMemory { Dram, Cuda };
+
+class TestBuffer {
+   public:
+    TestBuffer(size_t size, TestMemory memory) : host_(size), memory_(memory) {
+        if (memory_ == TestMemory::Dram) {
+            data_ = host_.data();
+            return;
+        }
+#ifdef USE_CUDA
+        if (cudaMalloc(&data_, size) != cudaSuccess) data_ = nullptr;
+#endif
+    }
+
+    ~TestBuffer() {
+#ifdef USE_CUDA
+        if (memory_ == TestMemory::Cuda && data_) (void)cudaFree(data_);
+#endif
+    }
+
+    TestBuffer(const TestBuffer&) = delete;
+    TestBuffer& operator=(const TestBuffer&) = delete;
+
+    bool available() const { return data_ != nullptr; }
+    void* data() { return data_; }
+    uint8_t* hostData() { return host_.data(); }
+
+    bool copyFromHost() {
+#ifdef USE_CUDA
+        if (memory_ == TestMemory::Cuda) {
+            return cudaMemcpy(data_, host_.data(), host_.size(),
+                              cudaMemcpyHostToDevice) == cudaSuccess;
+        }
+#endif
+        return true;
+    }
+
+    bool copyToHost() {
+#ifdef USE_CUDA
+        if (memory_ == TestMemory::Cuda) {
+            return cudaMemcpy(host_.data(), data_, host_.size(),
+                              cudaMemcpyDeviceToHost) == cudaSuccess;
+        }
+#endif
+        return true;
+    }
+
+   private:
+    std::vector<uint8_t> host_;
+    TestMemory memory_;
+    void* data_{nullptr};
+};
+
+class ChildProcessGuard {
+   public:
+    ChildProcessGuard(pid_t pid, int stop_fd) : pid_(pid), stop_fd_(stop_fd) {}
+
+    ~ChildProcessGuard() {
+        if (pid_ <= 0) return;
+        close(stop_fd_);
+        (void)waitpid(pid_, nullptr, 0);
+    }
+
+    int finish() {
+        close(stop_fd_);
+        int status = 0;
+        (void)waitpid(pid_, &status, 0);
+        pid_ = -1;
+        stop_fd_ = -1;
+        return status;
+    }
+
+    int reap() {
+        int status = 0;
+        (void)waitpid(pid_, &status, 0);
+        close(stop_fd_);
+        pid_ = -1;
+        stop_fd_ = -1;
+        return status;
+    }
+
+   private:
+    pid_t pid_;
+    int stop_fd_;
+};
+
+std::shared_ptr<Config> makeTcpConfig(size_t rpc_server_threads) {
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("metadata_servers", "P2PHANDSHAKE");
+    config->set("transports/tcp/enable", true);
+    config->set("transports/rdma/enable", false);
+    config->set("transports/shm/enable", false);
+    config->set("rpc_server_threads", rpc_server_threads);
+    return config;
+}
+
+bool waitBatchDone(TransferEngine& engine, BatchID batch) {
+    TransferStatus status;
+    for (int i = 0; i < 10000; ++i) {
+        auto result = engine.getTransferStatus(batch, status);
+        if (!result.ok() || status.s == TransferStatusEnum::FAILED)
+            return false;
+        if (status.s == TransferStatusEnum::COMPLETED) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return false;
+}
+
+// Drives WRITE-then-READ of kTaskCount non-contiguous slices between two
+// forked processes and verifies the pattern survives the round trip.
+void runWriteThenReadAcrossProcesses(size_t rpc_server_threads,
+                                     TestMemory memory = TestMemory::Dram) {
+    int ready_pipe[2];
+    int stop_pipe[2];
+    ASSERT_EQ(pipe(ready_pipe), 0);
+    ASSERT_EQ(pipe(stop_pipe), 0);
+
+    pid_t child = fork();
+    ASSERT_GE(child, 0);
+    if (child == 0) {
+        close(ready_pipe[0]);
+        close(stop_pipe[1]);
+
+        TransferEngine server(makeTcpConfig(rpc_server_threads));
+        if (!server.available()) _exit(2);
+        TestBuffer buffer(kBufferLength, memory);
+        if (!buffer.available()) _exit(3);
+        if (!server.registerLocalMemory(buffer.data(), kBufferLength).ok())
+            _exit(4);
+
+        const std::string segment = server.getSegmentName();
+        uint32_t length = static_cast<uint32_t>(segment.size());
+        if (write(ready_pipe[1], &length, sizeof(length)) != sizeof(length))
+            _exit(5);
+        if (write(ready_pipe[1], segment.data(), length) !=
+            static_cast<ssize_t>(length))
+            _exit(6);
+
+        char stop = 0;
+        const ssize_t stop_result = read(stop_pipe[0], &stop, 1);
+        (void)stop_result;
+        (void)server.unregisterLocalMemory(buffer.data(), kBufferLength);
+        _exit(0);
+    }
+
+    close(ready_pipe[1]);
+    close(stop_pipe[0]);
+    ChildProcessGuard child_guard(child, stop_pipe[1]);
+
+#ifdef USE_CUDA
+    if (memory == TestMemory::Cuda) {
+        int device_count = 0;
+        if (cudaGetDeviceCount(&device_count) != cudaSuccess ||
+            device_count <= 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+    }
+#endif
+
+    uint32_t segment_length = 0;
+    ssize_t received =
+        read(ready_pipe[0], &segment_length, sizeof(segment_length));
+    if (received != static_cast<ssize_t>(sizeof(segment_length))) {
+        const int status = child_guard.reap();
+        if (memory == TestMemory::Cuda) {
+            FAIL() << "CUDA TCP server initialization failed, child status "
+                   << status;
+        }
+        GTEST_SKIP() << "TCP server initialization failed, child status "
+                     << status;
+    }
+    std::string server_segment(segment_length, '\0');
+    ASSERT_EQ(read(ready_pipe[0], server_segment.data(), segment_length),
+              static_cast<ssize_t>(segment_length));
+
+    TransferEngine client(makeTcpConfig(rpc_server_threads));
+    ASSERT_TRUE(client.available());
+    TestBuffer buffer(kBufferLength, memory);
+    ASSERT_TRUE(buffer.available());
+    for (size_t task = 0; task < kTaskCount; ++task) {
+        uint8_t* slice = buffer.hostData() + task * kStride;
+        for (size_t i = 0; i < kDataLength; ++i) {
+            slice[i] = static_cast<uint8_t>((task * 131 + i * 7) & 0xff);
+        }
+    }
+    ASSERT_TRUE(buffer.copyFromHost());
+    ASSERT_TRUE(client.registerLocalMemory(buffer.data(), kBufferLength).ok());
+
+    SegmentID segment = 0;
+    Status result;
+    for (int i = 0; i < 100; ++i) {
+        result = client.openSegment(segment, server_segment);
+        if (result.ok()) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(result.ok()) << result.ToString();
+
+    SegmentInfo info;
+    ASSERT_TRUE(client.getSegmentInfo(segment, info).ok());
+    ASSERT_FALSE(info.buffers.empty());
+
+    auto* registered_buffer = static_cast<uint8_t*>(buffer.data());
+
+    // READ destination: a second region of the same registered buffer.
+    std::vector<Request> write_requests;
+    std::vector<Request> read_requests;
+    for (size_t task = 0; task < kTaskCount; ++task) {
+        Request write_request{};
+        write_request.opcode = Request::WRITE;
+        write_request.source = registered_buffer + task * kStride;
+        write_request.target_id = segment;
+        write_request.target_offset = info.buffers[0].base + task * kStride;
+        write_request.length = kDataLength;
+        write_request.transport_hint = TCP;
+        write_requests.push_back(write_request);
+
+        Request read_request{};
+        read_request.opcode = Request::READ;
+        read_request.source =
+            registered_buffer + kBufferLength / 2 + task * kDataLength;
+        read_request.target_id = segment;
+        read_request.target_offset = info.buffers[0].base + task * kStride;
+        read_request.length = kDataLength;
+        read_request.transport_hint = TCP;
+        read_requests.push_back(read_request);
+    }
+    // Patterned sources live in the first half (4MB of each 8MB stride);
+    // READ destinations occupy the second half. No overlap.
+
+    BatchID batch = client.allocateBatch(kTaskCount);
+    ASSERT_TRUE(client.submitTransfer(batch, write_requests).ok());
+    ASSERT_TRUE(waitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    batch = client.allocateBatch(kTaskCount);
+    ASSERT_TRUE(client.submitTransfer(batch, read_requests).ok());
+    ASSERT_TRUE(waitBatchDone(client, batch));
+    ASSERT_TRUE(client.freeBatch(batch).ok());
+
+    ASSERT_TRUE(buffer.copyToHost());
+    for (size_t task = 0; task < kTaskCount; ++task) {
+        const uint8_t* written = buffer.hostData() + task * kStride;
+        // Patterned sources occupy the first 4MB of each 8MB stride in the
+        // buffer's first half; READ destinations are packed contiguously
+        // into the second half, so they never overlap a source.
+        const uint8_t* read_back =
+            buffer.hostData() + kBufferLength / 2 + task * kDataLength;
+        EXPECT_EQ(std::memcmp(written, read_back, kDataLength), 0)
+            << "slice " << task << " mismatch";
+    }
+
+    EXPECT_TRUE(client.closeSegment(segment).ok());
+    EXPECT_TRUE(
+        client.unregisterLocalMemory(buffer.data(), kBufferLength).ok());
+
+    const int status = child_guard.finish();
+    ASSERT_TRUE(WIFEXITED(status));
+    EXPECT_EQ(WEXITSTATUS(status), 0);
+}
+
+TEST(TcpDataPathRoundtripTest, WriteThenReadAcrossProcesses) {
+    runWriteThenReadAcrossProcesses(1);
+}
+
+// Same round trip with a multi-threaded RPC server. SendData/RecvData are
+// offloaded, so this also covers concurrent bulk copies overlapping other
+// RPCs (MC_TENT_RPC_THREADS / rpc_server_threads).
+TEST(TcpDataPathRoundtripTest, WriteThenReadAcrossProcessesMultiThreadedRpc) {
+    runWriteThenReadAcrossProcesses(4);
+}
+
+#ifdef USE_CUDA
+TEST(TcpDataPathRoundtripTest, WriteThenReadCudaAcrossProcesses) {
+    runWriteThenReadAcrossProcesses(1, TestMemory::Cuda);
+}
+#endif
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/tcp_regression_test.cpp b/mooncake-transfer-engine/tent/tests/tcp_regression_test.cpp
new file mode 100644
index 0000000000..716ca8eaee
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/tcp_regression_test.cpp
@@ -0,0 +1,332 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cstdlib>
+#include <future>
+#include <limits>
+#include <new>
+#include <endian.h>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/control_plane.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/transport/tcp/tcp_transport.h"
+
+namespace {
+thread_local size_t fail_allocation_size = 0;
+std::atomic<int> injected_failures{0};
+}  // namespace
+
+// Inject the worker's SendData allocation. Also prevent a regressed size guard
+// from allocating a multi-GiB payload or reading beyond the small test buffer.
+[[gnu::noinline]] void* operator new(size_t size) {
+    if ((size && size == fail_allocation_size) ||
+        size > mooncake::tent::kTcpMaxReadBytes) {
+        fail_allocation_size = 0;
+        ++injected_failures;
+        throw std::bad_alloc();
+    }
+    if (void* ptr = std::malloc(size ? size : 1)) return ptr;
+    throw std::bad_alloc();
+}
+[[gnu::noinline]] void operator delete(void* ptr) noexcept { std::free(ptr); }
+[[gnu::noinline]] void operator delete(void* ptr, size_t) noexcept {
+    std::free(ptr);
+}
+// Pair the nothrow form too: GoogleTest uses it for temporary buffers under
+// ASan.
+[[gnu::noinline]] void* operator new(size_t size,
+                                     const std::nothrow_t&) noexcept {
+    try {
+        return ::operator new(size);
+    } catch (const std::bad_alloc&) {
+        return nullptr;
+    }
+}
+[[gnu::noinline]] void operator delete(void* ptr,
+                                       const std::nothrow_t&) noexcept {
+    ::operator delete(ptr);
+}
+
+namespace mooncake::tent {
+class TcpTransportTestPeer {
+   public:
+    static void arm(TcpTransport& tcp, size_t size) {
+        tcp.thread_pool_->enqueue([size] { fail_allocation_size = size; })
+            .get();
+    }
+    static void drain(TcpTransport& tcp) {
+        tcp.thread_pool_->enqueue([] {}).get();
+    }
+};
+
+namespace {
+using namespace std::chrono_literals;
+
+class ControlledTcp : public TcpTransport {
+   public:
+    bool pause = false;
+    TcpSubBatch* last_batch = nullptr;
+    std::promise<void> entered, resume;
+    std::shared_future<void> resumed = resume.get_future().share();
+    std::weak_ptr<int> callback_lifetime;
+
+    Status submitTransferTasks(SubBatchRef batch,
+                               const std::vector<Request>& requests) override {
+        last_batch = static_cast<TcpSubBatch*>(batch);
+        auto notify = batch->notify_progress;
+        if (pause) {
+            auto marker = std::make_shared<int>(0);
+            callback_lifetime = marker;
+            batch->notify_progress = [this, marker, notify](BatchID id) {
+                // Stack copies keep the test itself safe on the old version.
+                auto wait = resumed;
+                auto callback = notify;
+                entered.set_value();
+                wait.wait();
+                if (callback) callback(id);
+            };
+        }
+        auto status = TcpTransport::submitTransferTasks(batch, requests);
+        batch->notify_progress = std::move(notify);
+        return status;
+    }
+};
+
+class TcpRegression : public testing::Test {
+   protected:
+    std::array<char, 8192> data{};
+    std::unique_ptr<TransferEngineImpl> engine;
+    std::shared_ptr<ControlledTcp> tcp;
+    std::shared_ptr<ControlService> metadata;
+
+    void SetUp() override {
+        auto config = std::make_shared<Config>();
+        config->set("metadata_type", "p2p");
+        config->set("metadata_servers", "");
+        config->set("rpc_server_hostname", "127.0.0.1");
+        config->set("rpc_server_port", "0");
+        config->set("rpc_server_threads", 2);
+        config->set("enable_progress_worker", true);
+        config->set("enable_auto_failover_on_poll", false);
+        config->set("transports/tcp/enable", true);
+        config->set("transports/rdma/enable", false);
+        config->set("transports/shm/enable", false);
+        config->set("transports/tcp/max_concurrent_tasks", 1);
+        config->set("transports/tcp/max_retry_count", 0);
+        engine = std::make_unique<TransferEngineImpl>(config);
+        ASSERT_TRUE(engine->available());
+        tcp = std::make_shared<ControlledTcp>();
+        metadata = std::make_shared<ControlService>("p2p", "", nullptr);
+        auto name = engine->getSegmentName();
+        ASSERT_TRUE(tcp->install(name, metadata, nullptr, config).ok());
+        engine->swapTransportForTest(TCP, tcp);
+        ASSERT_TRUE(engine->registerLocalMemory(data.data(), data.size()).ok());
+        ASSERT_TRUE(metadata->segmentManager()
+                        .updateLocal([&](SegmentDesc& desc) {
+                            desc.type = SegmentType::Memory;
+                            desc.rpc_server_addr = name;
+                            BufferDesc buffer;
+                            buffer.addr =
+                                reinterpret_cast<uint64_t>(data.data());
+                            buffer.length = data.size();
+                            std::get<MemorySegmentDesc>(desc.detail)
+                                .buffers.push_back(buffer);
+                            return Status::OK();
+                        })
+                        .ok());
+    }
+
+    void TearDown() override {
+        if (tcp) {
+            tcp->resume.set_value();
+            EXPECT_TRUE(tcp->uninstall().ok());
+        }
+        if (engine && engine->available()) {
+            EXPECT_TRUE(
+                engine->unregisterLocalMemory(data.data(), data.size()).ok());
+        }
+    }
+
+    Request writeRequest(size_t length = 16) {
+        Request request{};
+        request.opcode = Request::WRITE;
+        request.source = data.data();
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = reinterpret_cast<uint64_t>(data.data() + 4096);
+        request.length = length;
+        request.transport_hint = TCP;
+        return request;
+    }
+
+    void checkImmediateFree(TransferStatusEnum expected) {
+        tcp->pause = true;
+        auto batch = engine->allocateBatch(1);
+        ASSERT_TRUE(engine->submitTransfer(batch, {writeRequest()}).ok());
+        auto entered = tcp->entered.get_future();
+        ASSERT_EQ(entered.wait_for(5s), std::future_status::ready);
+        TransferStatus status{};
+        EXPECT_TRUE(engine->getTransferStatus(batch, status).ok());
+        EXPECT_EQ(status.s, expected);
+        EXPECT_TRUE(engine->freeBatch(batch).ok());
+        EXPECT_EQ(engine->aliveBatchCountForTest(), 0u);
+        EXPECT_FALSE(tcp->callback_lifetime.expired());
+        // TearDown releases and joins the worker before destroying the engine.
+    }
+};
+
+TEST_F(TcpRegression, SuccessfulTerminalAllowsImmediateFreeBatch) {
+    checkImmediateFree(COMPLETED);
+}
+
+TEST_F(TcpRegression, FailedTerminalAllowsImmediateFreeBatch) {
+    ASSERT_TRUE(metadata->segmentManager()
+                    .updateLocal([](SegmentDesc& desc) {
+                        desc.rpc_server_addr.clear();
+                        return Status::OK();
+                    })
+                    .ok());
+    checkImmediateFree(FAILED);
+}
+
+TEST_F(TcpRegression, WorkerThrowFailsBatchAndNextRequestCompletes) {
+    std::fill_n(data.data(), 4096, 'W');
+    injected_failures = 0;
+    // libstdc++ reserve(n) allocates n + one terminating byte.
+    TcpTransportTestPeer::arm(*tcp, sizeof(XferDataDesc) + 4096 + 1);
+    for (auto expected : {FAILED, COMPLETED}) {
+        auto batch = engine->allocateBatch(1);
+        ASSERT_TRUE(engine->submitTransfer(batch, {writeRequest(4096)}).ok());
+        // A FIFO fence on the same single worker also bounds the old PENDING
+        // bug.
+        TcpTransportTestPeer::drain(*tcp);
+        TransferStatus status{};
+        ASSERT_TRUE(engine->getTransferStatus(batch, status).ok());
+        EXPECT_EQ(status.s, expected);
+        EXPECT_EQ(status.transferred_bytes, expected == FAILED ? 0u : 4096u);
+        EXPECT_EQ(injected_failures.load(), 1);
+        EXPECT_EQ(data[4096], expected == FAILED ? '\0' : 'W');
+        if (status.s == PENDING) {
+            // Failed-test cleanup only, after the worker has returned.
+            tcp->last_batch->task_list[0].status_word.store(FAILED);
+        }
+        EXPECT_TRUE(engine->freeBatch(batch).ok());
+        EXPECT_EQ(engine->aliveBatchCountForTest(), 0u);
+    }
+}
+
+TEST_F(TcpRegression, ServerChecksEveryRegistrationPermission) {
+    ASSERT_TRUE(engine->unregisterLocalMemory(data.data(), data.size()).ok());
+    for (auto permission :
+         {kLocalReadWrite, kGlobalReadOnly, kGlobalReadWrite}) {
+        ASSERT_TRUE(
+            engine->registerLocalMemory(data.data(), data.size(), permission)
+                .ok());
+        for (auto opcode : {Request::READ, Request::WRITE}) {
+            SCOPED_TRACE(testing::Message() << permission << "/" << opcode);
+            data.fill('R');
+            std::array<char, 8192> local;
+            local.fill('L');
+            const bool allowed =
+                permission == kGlobalReadWrite ||
+                (permission == kGlobalReadOnly && opcode == Request::READ);
+            auto call = opcode == Request::READ ? ControlClient::recvData
+                                                : ControlClient::sendData;
+            // Direct RPC bypasses client-side registration/routing policy.
+            auto status = call(engine->getSegmentName(),
+                               reinterpret_cast<uint64_t>(data.data()),
+                               local.data(), local.size());
+            EXPECT_EQ(status.ok(), allowed) << status.ToString();
+            if (!allowed) {
+                EXPECT_NE(status.ToString().find("permission denied"),
+                          std::string::npos);
+            }
+            const char remote_value =
+                allowed && opcode == Request::WRITE ? 'L' : 'R';
+            const char local_value =
+                allowed && opcode == Request::READ ? 'R' : 'L';
+            EXPECT_TRUE(std::all_of(data.begin(), data.end(),
+                                    [=](char c) { return c == remote_value; }));
+            EXPECT_TRUE(std::all_of(local.begin(), local.end(),
+                                    [=](char c) { return c == local_value; }));
+        }
+        ASSERT_TRUE(
+            engine->unregisterLocalMemory(data.data(), data.size()).ok());
+    }
+    ASSERT_TRUE(engine->registerLocalMemory(data.data(), data.size()).ok());
+}
+
+TEST_F(TcpRegression, PayloadCapsRejectBeforeAllocationOrDataRpc) {
+    CoroRpcAgent receiver;
+    std::atomic<int> calls{0};
+    for (auto id : {SendData, RecvData}) {
+        ASSERT_TRUE(
+            receiver.registerFunction(id, [&](const auto&, auto&) { ++calls; })
+                .ok());
+    }
+    uint16_t port = 0;
+    ASSERT_TRUE(receiver.start(port).ok());
+    auto address = "127.0.0.1:" + std::to_string(port);
+    ASSERT_TRUE(ControlClient::sendData(address, 0, data.data(), 1).ok());
+    ASSERT_EQ(calls.load(), 1);
+    calls = 0;
+    injected_failures = 0;
+    for (auto opcode : {Request::READ, Request::WRITE}) {
+        for (size_t length : {tcpMaxTransferBytes(opcode) + 1,
+                              std::numeric_limits<size_t>::max()}) {
+            auto call = opcode == Request::READ ? ControlClient::recvData
+                                                : ControlClient::sendData;
+            EXPECT_NO_THROW({
+                EXPECT_TRUE(call(address,
+                                 reinterpret_cast<uint64_t>(data.data()),
+                                 data.data(), length)
+                                .IsInvalidArgument());
+            });
+        }
+    }
+    EXPECT_EQ(injected_failures.load(), 0);
+    EXPECT_EQ(calls.load(), 0);
+    EXPECT_EQ(kTcpMaxWriteBytes + sizeof(XferDataDesc),
+              std::numeric_limits<uint32_t>::max());
+    EXPECT_TRUE(receiver.stop().ok());
+}
+
+TEST_F(TcpRegression, MalformedWriteLengthCannotOverflowOrModifyTarget) {
+    data.fill('T');
+    const auto original = data;
+    CoroRpcAgent rpc;
+    for (size_t length : {size_t{1}, kTcpMaxWriteBytes + 1,
+                          std::numeric_limits<size_t>::max()}) {
+        XferDataDesc header{htole64(reinterpret_cast<uint64_t>(data.data())),
+                            htole64(length)};
+        std::string request(reinterpret_cast<char*>(&header), sizeof(header));
+        std::string response;
+        ASSERT_TRUE(
+            rpc.call(engine->getSegmentName(), SendData, request, response)
+                .ok());
+        EXPECT_EQ(response, "SendData failed: invalid request size");
+        EXPECT_EQ(data, original);
+    }
+}
+
+}  // namespace
+}  // namespace mooncake::tent
diff --git a/mooncake-transfer-engine/tent/tests/tcp_transport_test.cpp b/mooncake-transfer-engine/tent/tests/tcp_transport_test.cpp
index b33d8e1bbb..4b5fb5efb8 100644
--- a/mooncake-transfer-engine/tent/tests/tcp_transport_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/tcp_transport_test.cpp
@@ -14,103 +14,70 @@
 
 #include <gtest/gtest.h>
 
-#include <atomic>
-#include <chrono>
 #include <memory>
-#include <thread>
+#include <string>
 #include <vector>
 
 #include "tent/common/config.h"
-#include "tent/common/types.h"
+#include "tent/runtime/control_plane.h"
 #include "tent/transport/tcp/tcp_transport.h"
 
 namespace mooncake {
 namespace tent {
-namespace {
-
-// ---------------------------------------------------------------------------
-// TcpParams unit tests
-// ---------------------------------------------------------------------------
 
-TEST(TcpParamsTest, DefaultValues) {
-    TcpParams params;
-    EXPECT_EQ(params.max_retry_count, 3);
-    EXPECT_EQ(params.retry_base_delay_ms, 100ULL);
-    EXPECT_EQ(params.retry_max_delay_ms, 2'000ULL);
-    EXPECT_EQ(params.max_concurrent_tasks, 16);
-}
+class TcpTransportTestPeer {
+   public:
+    static const TcpParams& params(const TcpTransport& transport) {
+        return transport.params_;
+    }
+};
 
-// ---------------------------------------------------------------------------
-// TcpTask unit tests — atomic semantics
-// ---------------------------------------------------------------------------
+namespace {
 
-TEST(TcpTaskTest, DefaultConstruction) {
-    TcpTask task;
-    EXPECT_EQ(task.status_word.load(), TransferStatusEnum::PENDING);
-    EXPECT_EQ(task.transferred_bytes.load(), 0u);
-    EXPECT_EQ(task.target_addr, 0u);
+std::shared_ptr<ControlService> makeP2PMetadata() {
+    return std::make_shared<ControlService>("p2p", "", nullptr);
 }
 
-TEST(TcpTaskTest, AtomicStatusTransitions) {
-    TcpTask task;
-    EXPECT_EQ(task.status_word.load(std::memory_order_acquire),
-              TransferStatusEnum::PENDING);
+TEST(TcpTransportConfigTest, InstallWithoutConfigKeepsStructDefaults) {
+    TcpTransport transport;
+    auto metadata = makeP2PMetadata();
+    std::string name = "tcp-config-default";
+    ASSERT_TRUE(transport.install(name, metadata, nullptr).ok());
 
-    task.status_word.store(TransferStatusEnum::COMPLETED,
-                           std::memory_order_release);
-    EXPECT_EQ(task.status_word.load(std::memory_order_acquire),
-              TransferStatusEnum::COMPLETED);
+    const TcpParams defaults;
+    const auto& params = TcpTransportTestPeer::params(transport);
+    EXPECT_EQ(params.max_retry_count, defaults.max_retry_count);
+    EXPECT_EQ(params.retry_base_delay_ms, defaults.retry_base_delay_ms);
+    EXPECT_EQ(params.retry_max_delay_ms, defaults.retry_max_delay_ms);
+    EXPECT_EQ(params.max_concurrent_tasks, defaults.max_concurrent_tasks);
 
-    task.status_word.store(TransferStatusEnum::FAILED,
-                           std::memory_order_release);
-    EXPECT_EQ(task.status_word.load(std::memory_order_acquire),
-              TransferStatusEnum::FAILED);
+    EXPECT_TRUE(transport.uninstall().ok());
 }
 
-TEST(TcpTaskTest, AtomicTransferredBytes) {
-    TcpTask task;
-    constexpr size_t kPayload = 1024 * 1024;
-    task.transferred_bytes.store(kPayload, std::memory_order_release);
-    EXPECT_EQ(task.transferred_bytes.load(std::memory_order_acquire), kPayload);
-}
-
-TEST(TcpTaskTest, MoveConstruction) {
-    TcpTask a;
-    a.status_word.store(TransferStatusEnum::COMPLETED,
-                        std::memory_order_relaxed);
-    a.transferred_bytes.store(4096, std::memory_order_relaxed);
-    a.target_addr = 0xdeadbeef;
-
-    TcpTask b(std::move(a));
-    EXPECT_EQ(b.status_word.load(), TransferStatusEnum::COMPLETED);
-    EXPECT_EQ(b.transferred_bytes.load(), 4096u);
-    EXPECT_EQ(b.target_addr, 0xdeadbeef);
-}
-
-// ---------------------------------------------------------------------------
-// TcpSubBatch unit tests
-// ---------------------------------------------------------------------------
+TEST(TcpTransportConfigTest, InstallReadsConfigKeys) {
+    auto conf = std::make_shared<Config>();
+    conf->set("transports/tcp/max_retry_count", 5);
+    conf->set("transports/tcp/retry_base_delay_ms", 200ULL);
+    conf->set("transports/tcp/retry_max_delay_ms", 4000ULL);
+    conf->set("transports/tcp/max_concurrent_tasks", 32);
 
-TEST(TcpSubBatchTest, EmptyBatch) {
-    TcpSubBatch batch;
-    batch.max_size = 64;
-    EXPECT_EQ(batch.size(), 0u);
-}
+    TcpTransport transport;
+    auto metadata = makeP2PMetadata();
+    std::string name = "tcp-config-override";
+    ASSERT_TRUE(transport.install(name, metadata, nullptr, conf).ok());
 
-TEST(TcpSubBatchTest, EmplaceAndSize) {
-    TcpSubBatch batch;
-    batch.max_size = 64;
-    batch.task_list.reserve(batch.max_size);
+    const auto& params = TcpTransportTestPeer::params(transport);
+    EXPECT_EQ(params.max_retry_count, 5u);
+    EXPECT_EQ(params.retry_base_delay_ms, 200ULL);
+    EXPECT_EQ(params.retry_max_delay_ms, 4000ULL);
+    EXPECT_EQ(params.max_concurrent_tasks, 32u);
 
-    batch.task_list.emplace_back();
-    batch.task_list.emplace_back();
-    batch.task_list.emplace_back();
-    EXPECT_EQ(batch.size(), 3u);
+    EXPECT_TRUE(transport.uninstall().ok());
 }
 
 TEST(TcpSubBatchTest, PointerStabilityAfterReserve) {
-    // Verify that pointers taken after reserve remain valid when more
-    // tasks are emplaced (important for async dispatch correctness).
+    // allocateSubBatch reserves task_list to max_size so submitTransferTasks
+    // can take stable TcpTask* after emplace.
     TcpSubBatch batch;
     batch.max_size = 8;
     batch.task_list.reserve(batch.max_size);
@@ -119,78 +86,15 @@ TEST(TcpSubBatchTest, PointerStabilityAfterReserve) {
     TcpTask* first = &batch.task_list[0];
     first->target_addr = 42;
 
-    // Add more tasks (within reserved capacity)
     for (int i = 1; i < 8; ++i) {
         batch.task_list.emplace_back();
     }
 
-    // First pointer must still be valid
     EXPECT_EQ(first->target_addr, 42u);
     EXPECT_EQ(&batch.task_list[0], first);
 }
 
-// ---------------------------------------------------------------------------
-// TcpTransport config loading test
-// ---------------------------------------------------------------------------
-
-TEST(TcpTransportConfigTest, ConfigOverridesDefaults) {
-    auto conf = std::make_shared<Config>();
-    conf->set("transports/tcp/max_retry_count", 5);
-    conf->set("transports/tcp/retry_base_delay_ms", 200ULL);
-    conf->set("transports/tcp/retry_max_delay_ms", 4000ULL);
-    conf->set("transports/tcp/max_concurrent_tasks", 32);
-
-    EXPECT_EQ(conf->get("transports/tcp/max_retry_count", 0), 5);
-    EXPECT_EQ(conf->get("transports/tcp/retry_base_delay_ms", 0ULL), 200ULL);
-    EXPECT_EQ(conf->get("transports/tcp/retry_max_delay_ms", 0ULL), 4000ULL);
-    EXPECT_EQ(conf->get("transports/tcp/max_concurrent_tasks", 0), 32);
-}
-
-TEST(TcpTransportConfigTest, MissingConfigUsesDefaults) {
-    auto conf = std::make_shared<Config>();
-
-    TcpParams defaults;
-    EXPECT_EQ(
-        conf->get("transports/tcp/max_retry_count", defaults.max_retry_count),
-        3);
-    EXPECT_EQ(conf->get("transports/tcp/max_concurrent_tasks",
-                        defaults.max_concurrent_tasks),
-              16);
-}
-
-// ---------------------------------------------------------------------------
-// Cross-thread visibility test (verifies atomic correctness)
-// ---------------------------------------------------------------------------
-
-TEST(TcpTaskTest, CrossThreadVisibility) {
-    TcpTask task;
-    std::atomic<bool> writer_done{false};
-
-    std::thread writer([&]() {
-        task.transferred_bytes.store(8192, std::memory_order_release);
-        task.status_word.store(TransferStatusEnum::COMPLETED,
-                               std::memory_order_release);
-        writer_done.store(true, std::memory_order_release);
-    });
-
-    // Spin until writer signals done
-    while (!writer_done.load(std::memory_order_acquire)) {
-        std::this_thread::yield();
-    }
-
-    EXPECT_EQ(task.status_word.load(std::memory_order_acquire),
-              TransferStatusEnum::COMPLETED);
-    EXPECT_EQ(task.transferred_bytes.load(std::memory_order_acquire), 8192u);
-
-    writer.join();
-}
-
-// ---------------------------------------------------------------------------
-// Exponential backoff calculation test
-// ---------------------------------------------------------------------------
-
 TEST(TcpRetryBackoffTest, ExponentialGrowthWithCap) {
-    // Simulate the backoff logic from doTransferWithRetry
     const uint64_t base = 100;
     const uint64_t cap = 2000;
     uint64_t delay = base;
@@ -198,16 +102,15 @@ TEST(TcpRetryBackoffTest, ExponentialGrowthWithCap) {
     std::vector<uint64_t> delays;
     for (int attempt = 0; attempt < 6; ++attempt) {
         delays.push_back(delay);
-        delay = std::min(delay * 2, cap);
+        delay = nextTcpRetryDelay(delay, cap);
     }
 
-    // 100 → 200 → 400 → 800 → 1600 → 2000 (capped)
     EXPECT_EQ(delays[0], 100u);
     EXPECT_EQ(delays[1], 200u);
     EXPECT_EQ(delays[2], 400u);
     EXPECT_EQ(delays[3], 800u);
     EXPECT_EQ(delays[4], 1600u);
-    EXPECT_EQ(delays[5], 2000u);  // capped at retry_max_delay_ms
+    EXPECT_EQ(delays[5], 2000u);
 }
 
 }  // namespace
diff --git a/mooncake-transfer-engine/tent/tests/test_python_guards.py b/mooncake-transfer-engine/tent/tests/test_python_guards.py
new file mode 100644
index 0000000000..0976439e11
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/test_python_guards.py
@@ -0,0 +1,48 @@
+"""Check that guard exits return safely and preserve Python exceptions."""
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+import tent
+
+
+class PythonGuardTest(unittest.TestCase):
+    def test_context_manager_exits(self):
+        with tempfile.TemporaryDirectory() as directory:
+            config = Path(directory) / "tent.json"
+            config.write_text(
+                json.dumps(
+                    {
+                        "metadata_type": "p2p",
+                        "rpc_server_hostname": "127.0.0.1",
+                        "rpc_server_port": 0,
+                        "transports": {
+                            "tcp": {"enable": True},
+                            "hp_tcp": {"enable": False},
+                            "rdma": {"enable": False},
+                            "shm": {"enable": False},
+                        },
+                    }
+                )
+            )
+            engine = tent.TransferEngine(str(config))
+            self.assertTrue(engine.available())
+            for name, allocate in (
+                ("memory", lambda: engine.allocate_memory_guard(4096)),
+                ("batch", lambda: engine.allocate_batch_guard(1)),
+            ):
+                with self.subTest(guard=name, exit="normal"):
+                    with allocate():
+                        pass
+                with self.subTest(guard=name, exit="exception"):
+                    expected = ValueError("exception from the with body")
+                    with self.assertRaises(ValueError) as raised:
+                        with allocate():
+                            raise expected
+                    self.assertIs(raised.exception, expected)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-transfer-engine/tent/tests/thread_local_storage_test.cpp b/mooncake-transfer-engine/tent/tests/thread_local_storage_test.cpp
index cb6921a461..6611043c2b 100644
--- a/mooncake-transfer-engine/tent/tests/thread_local_storage_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/thread_local_storage_test.cpp
@@ -22,8 +22,6 @@
 #include <gtest/gtest.h>
 
 #include <atomic>
-#include <chrono>
-#include <cstdio>
 #include <memory>
 #include <thread>
 #include <vector>
@@ -192,43 +190,5 @@ TEST(ThreadLocalStorageTest, OrphanedValuesSweptOnInstanceChurn) {
     }
 }
 
-// Informational: hot-path cost of get(). The remote-desc cache consults this
-// on every transfer submit, so the common case must stay a thread_local
-// access plus a compare.
-TEST(ThreadLocalStorageTest, HotPathMicrobench) {
-    ThreadLocalStorage<Cache> storage;
-    storage.get().value = 1;
-    constexpr uint64_t kOps = 20'000'000;
-    volatile int sink = 0;
-    auto t0 = std::chrono::steady_clock::now();
-    for (uint64_t i = 0; i < kOps; ++i) {
-        sink += storage.get().value;
-    }
-    auto t1 = std::chrono::steady_clock::now();
-    double ns =
-        (double)std::chrono::duration_cast<std::chrono::nanoseconds>(t1 - t0)
-            .count() /
-        (double)kOps;
-    printf("get_hot_path_ns_per_op %.2f\n", ns);
-    (void)sink;
-#if defined(__SANITIZE_THREAD__) || defined(__SANITIZE_ADDRESS__)
-    constexpr bool kSanitized = true;
-#elif defined(__has_feature)
-#if __has_feature(thread_sanitizer) || __has_feature(address_sanitizer)
-    constexpr bool kSanitized = true;
-#else
-    constexpr bool kSanitized = false;
-#endif
-#else
-    constexpr bool kSanitized = false;
-#endif
-    // Wall-clock assertions flake under sanitizers (TSAN alone is ~14x);
-    // elsewhere keep a loose ceiling that still catches syscall- or
-    // contention-class regressions on the hot path.
-    if (!kSanitized) {
-        EXPECT_LT(ns, 100.0);
-    }
-}
-
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/ticket_lock_test.cpp b/mooncake-transfer-engine/tent/tests/ticket_lock_test.cpp
new file mode 100644
index 0000000000..463cd72547
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/ticket_lock_test.cpp
@@ -0,0 +1,144 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Unit tests for TicketLock: mutual exclusion under contention, hand-off in
+// arrival order, and hand-off after a hold long enough to push waiters past
+// the spin budget into the yield path.
+
+#include "tent/common/concurrent/ticket_lock.h"
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+namespace mooncake {
+namespace tent {
+
+// Tickets are the lock's only observable state, and a test that wants to
+// arrange waiters in a known order has to see them handed out: a sleep only
+// makes the order likely, not certain.
+class TicketLockTestPeer {
+   public:
+    static int ticketsIssued(const TicketLock& lock) {
+        return lock.next_ticket_.load(std::memory_order_acquire);
+    }
+};
+
+namespace {
+
+using namespace std::chrono_literals;
+
+// Spin until `n` tickets have been handed out, i.e. n-1 waiters are queued
+// behind the holder.
+void waitForTickets(const TicketLock& lock, int n) {
+    while (TicketLockTestPeer::ticketsIssued(lock) < n)
+        std::this_thread::yield();
+}
+
+TEST(TicketLockTest, UncontendedLockUnlockRoundTrips) {
+    TicketLock lock;
+    for (int i = 0; i < 1000; ++i) {
+        std::lock_guard<TicketLock> guard(lock);
+    }
+}
+
+// Eight threads bump a plain counter under the lock and check that no two
+// of them are ever inside the critical section together. Overlap would lose
+// increments or show a nesting depth above one.
+TEST(TicketLockTest, ExcludesConcurrentCriticalSections) {
+    constexpr int kThreads = 8;
+    constexpr int kIters = 20000;
+    TicketLock lock;
+    long counter = 0;    // deliberately not atomic
+    int in_section = 0;  // deliberately not atomic
+    std::atomic<bool> overlap{false};
+
+    std::vector<std::thread> threads;
+    for (int t = 0; t < kThreads; ++t) {
+        threads.emplace_back([&] {
+            for (int i = 0; i < kIters; ++i) {
+                std::lock_guard<TicketLock> guard(lock);
+                if (++in_section != 1) overlap.store(true);
+                ++counter;
+                --in_section;
+            }
+        });
+    }
+    for (auto& t : threads) t.join();
+
+    EXPECT_EQ(counter, static_cast<long>(kThreads) * kIters);
+    EXPECT_FALSE(overlap.load());
+}
+
+// With the lock held (ticket 0), B queues up (ticket 1) and then C does
+// (ticket 2). On release B must be served before C: tickets are handed out on
+// arrival and served in order. Each waiter is started only once the previous
+// one is seen holding its ticket, so the arrival order is a fact, not a race
+// the test hopes to win.
+TEST(TicketLockTest, ServesWaitersInArrivalOrder) {
+    constexpr int kRounds = 20;
+    for (int round = 0; round < kRounds; ++round) {
+        TicketLock lock;
+        std::vector<char> order;  // written under the lock
+
+        lock.lock();
+        std::thread b([&] {
+            lock.lock();
+            order.push_back('B');
+            lock.unlock();
+        });
+        waitForTickets(lock, 2);  // B holds ticket 1
+        std::thread c([&] {
+            lock.lock();
+            order.push_back('C');
+            lock.unlock();
+        });
+        waitForTickets(lock, 3);  // C holds ticket 2
+        lock.unlock();
+
+        b.join();
+        c.join();
+        ASSERT_EQ(order, (std::vector<char>{'B', 'C'})) << "round " << round;
+    }
+}
+
+// A hold of tens of milliseconds is far past the spin budget, so a waiter
+// that is already queued falls through to yield(); it must still take the
+// lock on release.
+TEST(TicketLockTest, HandsOverAfterAHoldLongerThanTheSpinBudget) {
+    TicketLock lock;
+    std::atomic<bool> acquired{false};
+
+    lock.lock();
+    std::thread waiter([&] {
+        lock.lock();
+        acquired.store(true);
+        lock.unlock();
+    });
+    waitForTickets(lock, 2);            // the waiter is queued...
+    std::this_thread::sleep_for(20ms);  // ...and spins past its budget
+    EXPECT_FALSE(acquired.load());      // still held here
+
+    lock.unlock();
+    waiter.join();
+    EXPECT_TRUE(acquired.load());
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/topology_priority_matrix_test.cpp b/mooncake-transfer-engine/tent/tests/topology_priority_matrix_test.cpp
new file mode 100644
index 0000000000..0ad7d9e15e
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/topology_priority_matrix_test.cpp
@@ -0,0 +1,320 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <string>
+
+#include "tent/common/config.h"
+#include "tent/common/types.h"
+#include "tent/runtime/topology.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class TempTopologyFile {
+   public:
+    explicit TempTopologyFile(const std::string& content) {
+        auto unique_name =
+            "tent-topo-" +
+            std::to_string(
+                std::chrono::steady_clock::now().time_since_epoch().count()) +
+            ".json";
+        path_ = std::filesystem::temp_directory_path() / unique_name;
+        std::ofstream ofs(path_);
+        ofs << content;
+    }
+
+    ~TempTopologyFile() {
+        std::error_code ec;
+        std::filesystem::remove(path_, ec);
+    }
+
+    std::string path() const { return path_.string(); }
+
+   private:
+    std::filesystem::path path_;
+};
+
+TEST(TopologyPriorityMatrixTest, ParsesClassicMatrixRanksAndWildcard) {
+    constexpr const char* kMatrix = R"json(
+        {
+          "cpu:0": [["mlx5_0"], ["mlx5_1"]],
+          "cpu:1": [["mlx5_1"], ["mlx5_0"]],
+          "cuda:0": [["mlx5_0"], ["mlx5_1"]]
+        }
+    )json";
+
+    Topology topology;
+    ASSERT_TRUE(topology.parsePriorityMatrix(kMatrix).ok());
+
+    ASSERT_EQ(topology.getNicCount(), 2u);
+    EXPECT_EQ(topology.getNicName(0), "mlx5_0");
+    EXPECT_EQ(topology.getNicName(1), "mlx5_1");
+    EXPECT_EQ(topology.getNicType(0), Topology::NIC_RDMA);
+
+    const auto* cpu0 = topology.getMemEntry("cpu:0");
+    ASSERT_NE(cpu0, nullptr);
+    EXPECT_EQ(cpu0->type, Topology::MEM_HOST);
+    ASSERT_EQ(cpu0->device_list[0].size(), 1u);
+    EXPECT_EQ(cpu0->device_list[0][0], 0);
+    ASSERT_EQ(cpu0->device_list[1].size(), 1u);
+    EXPECT_EQ(cpu0->device_list[1][0], 1);
+    EXPECT_TRUE(cpu0->device_list[2].empty());
+
+    const auto* cpu1 = topology.getMemEntry("cpu:1");
+    ASSERT_NE(cpu1, nullptr);
+    ASSERT_EQ(cpu1->device_list[0].size(), 1u);
+    EXPECT_EQ(cpu1->device_list[0][0], 1);
+    ASSERT_EQ(cpu1->device_list[1].size(), 1u);
+    EXPECT_EQ(cpu1->device_list[1][0], 0);
+
+    const auto* cuda0 = topology.getMemEntry("cuda:0");
+    ASSERT_NE(cuda0, nullptr);
+    EXPECT_EQ(cuda0->type, Topology::MEM_CUDA);
+
+    const auto* wildcard = topology.getMemEntry(kWildcardLocation);
+    ASSERT_NE(wildcard, nullptr);
+    ASSERT_EQ(wildcard->device_list[0].size(), 2u);
+    EXPECT_EQ(wildcard->device_list[0][0], 0);
+    EXPECT_EQ(wildcard->device_list[0][1], 1);
+    ASSERT_EQ(wildcard->device_list[1].size(), 2u);
+    EXPECT_EQ(wildcard->device_list[1][0], 1);
+    EXPECT_EQ(wildcard->device_list[1][1], 0);
+}
+
+TEST(TopologyPriorityMatrixTest, RejectsMalformedMatrixEntries) {
+    Topology topology;
+    EXPECT_FALSE(topology.parsePriorityMatrix("").ok());
+    EXPECT_FALSE(
+        topology.parsePriorityMatrix(R"({"cpu:0": [["mlx5_0"]]})").ok());
+    EXPECT_FALSE(topology.parsePriorityMatrix(R"({"cpu:0": "mlx5_0"})").ok());
+    EXPECT_FALSE(
+        topology.parsePriorityMatrix(R"({"cpu:0": [[1], ["mlx5_1"]]})").ok());
+}
+
+TEST(TopologyPriorityMatrixTest, AmdGpuLocationUsesHipPrefixAndRocmAlias) {
+    EXPECT_EQ(memTypeFromLocation("hip:0"), Topology::MEM_ROCM);
+    EXPECT_EQ(memTypeFromLocation("rocm:3"), Topology::MEM_ROCM);
+    EXPECT_EQ(makeAmdGpuLocation(2), "hip:2");
+    EXPECT_TRUE(isAmdGpuLocationType("hip"));
+    EXPECT_TRUE(isAmdGpuLocationType("rocm"));
+    EXPECT_FALSE(isAmdGpuLocationType("cuda"));
+    EXPECT_EQ(canonicalizeLocation("rocm:1"), "hip:1");
+    EXPECT_EQ(canonicalizeLocation("hip:1"), "hip:1");
+    EXPECT_EQ(canonicalizeLocation("cpu:0"), "cpu:0");
+
+    Topology topology;
+    ASSERT_TRUE(topology
+                    .parsePriorityMatrix(R"json({
+          "hip:0": [["mlx5_0"], ["mlx5_1"]],
+          "rocm:1": [["mlx5_1"], ["mlx5_0"]]
+        })json")
+                    .ok());
+
+    const auto* hip0 = topology.getMemEntry("hip:0");
+    ASSERT_NE(hip0, nullptr);
+    EXPECT_EQ(hip0->type, Topology::MEM_ROCM);
+
+    // The legacy "rocm:1" key is stored under its canonical name, and both
+    // the canonical and the legacy name resolve to the same entry.
+    const auto* rocm1 = topology.getMemEntry("rocm:1");
+    ASSERT_NE(rocm1, nullptr);
+    EXPECT_EQ(rocm1->name, "hip:1");
+    EXPECT_EQ(rocm1->type, Topology::MEM_ROCM);
+    EXPECT_EQ(topology.getMemEntry("hip:1"), rocm1);
+}
+
+// Regression test: a matrix configured with only the legacy "rocm:N" key
+// must be reachable via the canonical runtime name, so the configured NIC
+// priorities are not silently ignored by exact-name lookups.
+TEST(TopologyPriorityMatrixTest,
+     LegacyRocmMatrixKeyResolvesViaCanonicalHipName) {
+    Topology topology;
+    ASSERT_TRUE(topology
+                    .parsePriorityMatrix(R"json({
+          "rocm:0": [["mlx5_0"], ["mlx5_1"]]
+        })json")
+                    .ok());
+
+    // Stored under the canonical name only.
+    const auto* hip0 = topology.getMemEntry("hip:0");
+    ASSERT_NE(hip0, nullptr);
+    EXPECT_EQ(hip0->name, "hip:0");
+    EXPECT_EQ(hip0->type, Topology::MEM_ROCM);
+
+    // Exact-id lookups with the canonical name resolve to the entry and
+    // carry the configured per-GPU NIC priorities.
+    const auto mem_id = topology.getMemId("hip:0");
+    EXPECT_GE(mem_id, 0);
+    const auto* by_id = topology.getMemEntry(mem_id);
+    ASSERT_NE(by_id, nullptr);
+    ASSERT_EQ(by_id->device_list[0].size(), 1u);
+    EXPECT_EQ(topology.getNicName(by_id->device_list[0][0]), "mlx5_0");
+    ASSERT_EQ(by_id->device_list[1].size(), 1u);
+    EXPECT_EQ(topology.getNicName(by_id->device_list[1][0]), "mlx5_1");
+}
+
+TEST(TopologyPriorityMatrixTest, RejectsConflictingHipAndRocmKeys) {
+    Topology topology;
+    // "rocm:0" and "hip:0" refer to the same device; specifying both is a
+    // config error rather than a silent last-wins.
+    EXPECT_FALSE(topology
+                     .parsePriorityMatrix(R"json({
+          "hip:0": [["mlx5_0"], ["mlx5_1"]],
+          "rocm:0": [["mlx5_1"], ["mlx5_0"]]
+        })json")
+                     .ok());
+}
+
+TEST(TopologyPriorityMatrixTest, ParseCustomRoutesNativeFormat) {
+    constexpr const char* kNative = R"json(
+        {
+          "nics": [{"name": "mlx5_0", "type": 0, "numa_node": 0}],
+          "mems": [{
+            "name": "cpu:0",
+            "type": 0,
+            "numa_node": 0,
+            "device_list": {"rank0": [0]}
+          }]
+        }
+    )json";
+
+    Topology topology;
+    ASSERT_TRUE(topology.parseCustomTopology(kNative).ok());
+    ASSERT_EQ(topology.getNicCount(), 1u);
+    EXPECT_EQ(topology.getNicName(0), "mlx5_0");
+    EXPECT_NE(topology.getMemEntry("cpu:0"), nullptr);
+    // Native path does not synthesize wildcard.
+    EXPECT_EQ(topology.getMemEntry(kWildcardLocation), nullptr);
+}
+
+TEST(TopologyPriorityMatrixTest, ParseCustomRoutesClassicMatrix) {
+    Topology topology;
+    ASSERT_TRUE(
+        topology.parseCustomTopology(R"({"cpu:0": [["erdma_0"],["erdma_1"]]})")
+            .ok());
+    EXPECT_EQ(topology.getNicCount(), 2u);
+    EXPECT_NE(topology.getMemEntry(kWildcardLocation), nullptr);
+}
+
+TEST(TopologyPriorityMatrixTest, LoadFromConfigInlineMatrix) {
+    Config conf;
+    ASSERT_TRUE(conf.load(R"json({
+      "topology": {
+        "priority_matrix": {
+          "cpu:0": [["mlx5_0"], ["mlx5_1"]]
+        },
+        "custom_json_path": "/nonexistent/should_be_ignored.json"
+      }
+    })json")
+                    .ok());
+
+    Topology topology;
+    ASSERT_TRUE(topology.loadFromConfig(conf, {}).ok());
+    EXPECT_EQ(topology.getNicName(0), "mlx5_0");
+    EXPECT_EQ(topology.getNicName(1), "mlx5_1");
+    EXPECT_NE(topology.getMemEntry("cpu:0"), nullptr);
+}
+
+TEST(TopologyPriorityMatrixTest, LoadFromConfigPathFile) {
+    TempTopologyFile file(R"({"cpu:0": [["mlx5_2"], ["mlx5_3"]]})");
+    Config conf;
+    conf.set("topology/custom_json_path", file.path());
+
+    Topology topology;
+    ASSERT_TRUE(topology.loadFromConfig(conf, {}).ok());
+    EXPECT_EQ(topology.getNicName(0), "mlx5_2");
+    EXPECT_EQ(topology.getNicName(1), "mlx5_3");
+}
+
+TEST(TopologyPriorityMatrixTest, LoadFromConfigInlinePreferredOverPath) {
+    TempTopologyFile file(R"({"cpu:0": [["from_file"], []]})");
+    Config conf;
+    ASSERT_TRUE(conf.load(R"json({
+      "topology": {
+        "priority_matrix": {
+          "cpu:0": [["from_inline"], []]
+        }
+      }
+    })json")
+                    .ok());
+    conf.set("topology/custom_json_path", file.path());
+
+    Topology topology;
+    ASSERT_TRUE(topology.loadFromConfig(conf, {}).ok());
+    EXPECT_EQ(topology.getNicName(0), "from_inline");
+}
+
+TEST(TopologyPriorityMatrixTest, LoadFromConfigInvalidInlineFallsBack) {
+    Config conf;
+    ASSERT_TRUE(conf.load(R"json({
+      "topology": {
+        "priority_matrix": {
+          "cpu:0": ["bad"]
+        }
+      }
+    })json")
+                    .ok());
+
+    Topology topology;
+    // Empty platform list → discover yields empty topology.
+    ASSERT_TRUE(topology.loadFromConfig(conf, {}).ok());
+    EXPECT_TRUE(topology.empty());
+}
+
+TEST(ConfigDumpSubtreeTest, DumpsNestedPriorityMatrix) {
+    Config conf;
+    ASSERT_TRUE(conf.load(R"json({
+      "topology": {
+        "priority_matrix": {
+          "cpu:0": [["mlx5_0"], []]
+        }
+      }
+    })json")
+                    .ok());
+
+    std::string dumped;
+    ASSERT_TRUE(conf.dumpSubtree("topology/priority_matrix", &dumped));
+    Topology topology;
+    ASSERT_TRUE(topology.parsePriorityMatrix(dumped).ok());
+    EXPECT_EQ(topology.getNicName(0), "mlx5_0");
+}
+
+TEST(ConfigEnvMappingTest, CustomTopoJsonEnvLoadsPath) {
+    const char* name = "MC_CUSTOM_TOPO_JSON";
+    const char* old = std::getenv(name);
+    std::string old_value = old ? old : "";
+    setenv(name, "/tmp/mooncake-nic-priority-matrix.json", 1);
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+    EXPECT_EQ(config.get("topology/custom_json_path", ""),
+              "/tmp/mooncake-nic-priority-matrix.json");
+
+    if (old) {
+        setenv(name, old_value.c_str(), 1);
+    } else {
+        unsetenv(name);
+    }
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/transfer_engine_config_override_test.cpp b/mooncake-transfer-engine/tent/tests/transfer_engine_config_override_test.cpp
index 5182182762..46246f2dce 100644
--- a/mooncake-transfer-engine/tent/tests/transfer_engine_config_override_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/transfer_engine_config_override_test.cpp
@@ -283,6 +283,72 @@ TEST(TransferEngineConfigOverrideTest,
     EXPECT_EQ(config.get("transports/rdma/bind_address", ""), "10.0.0.2");
 }
 
+TEST(TransferEngineConfigOverrideTest, LegacyForceTcpEnvOverridesTentConfig) {
+    EnvVarGuard conf_guard(
+        "MC_TENT_CONF",
+        R"({"transports":{"tcp":{"enable":false},"rdma":{"enable":true},"hp_tcp":{"enable":true}}})");
+    EnvVarGuard force_tcp_guard("MC_FORCE_TCP", "1");
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+
+    EXPECT_TRUE(config.get("transports/force_tcp", false));
+    EXPECT_TRUE(config.get("transports/tcp/enable", false));
+    EXPECT_FALSE(config.get("transports/rdma/enable", true));
+    EXPECT_FALSE(config.get("transports/hp_tcp/enable", true));
+}
+
+TEST(TransferEngineConfigOverrideTest,
+     ExplicitForceTcpSurvivesMcTentConfThroughConstructor) {
+    EnvVarGuard conf_guard(
+        "MC_TENT_CONF",
+        R"({"transports":{"tcp":{"enable":false},"rdma":{"enable":false},"hp_tcp":{"enable":true},"mpcomm":{"enable":false},"io_uring":{"enable":false}},"metrics":{"enabled":false}})");
+
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "p2p");
+    config->set("local_segment_name", "force-tcp-explicit");
+    config->set("rpc_server_hostname", kLoopbackHostname);
+    config->set("rpc_server_port", 0);
+    ConfigHelper::forceTcp(*config);
+
+    {
+        TransferEngineImpl engine(config);
+        ASSERT_TRUE(engine.available());
+        EXPECT_TRUE(config->get("transports/force_tcp", false));
+        EXPECT_TRUE(config->get("transports/tcp/enable", false));
+        EXPECT_FALSE(config->get("transports/rdma/enable", true));
+        EXPECT_FALSE(config->get("transports/hp_tcp/enable", true));
+    }
+}
+
+// MOONCAKE_LOCAL_HOSTNAME is the classic Transfer Engine + store env var that
+// names the local host for RPC binding and segment identity. TENT must honor
+// the same env so a single MOONCAKE_LOCAL_HOSTNAME works across both engines;
+// otherwise TENT's auto-discovery can pick a container/CNI IP (e.g. 10.154.0.1)
+// instead of the RDMA-network IP, breaking cross-node RDMA handshake.
+TEST(TransferEngineConfigOverrideTest,
+     LocalHostnameEnvLoadsIntoRpcServerHostname) {
+    EnvVarGuard guard("MOONCAKE_LOCAL_HOSTNAME", "10.0.0.2");
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+
+    EXPECT_EQ(config.get("rpc_server_hostname", ""), "10.0.0.2");
+}
+
+TEST(TransferEngineConfigOverrideTest, LocalHostnameEnvOverridesMcTentConf) {
+    EnvVarGuard conf_guard("MC_TENT_CONF",
+                           R"({"rpc_server_hostname":"10.0.0.1"})");
+    EnvVarGuard host_guard("MOONCAKE_LOCAL_HOSTNAME", "10.0.0.2");
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+
+    // Legacy env must override MC_TENT_CONF, same precedence as
+    // MC_RDMA_BIND_ADDRESS (env wins so per-pod injection works).
+    EXPECT_EQ(config.get("rpc_server_hostname", ""), "10.0.0.2");
+}
+
 TEST(TransferEngineConfigOverrideTest,
      LegacyRdmaSliceAffinityLogEnvLoadsIntoTentConfig) {
     EnvVarGuard guard("MC_LOG_RDMA_SLICE_AFFINITY", "true");
@@ -336,6 +402,56 @@ TEST(TransferEngineConfigOverrideTest, FilterNicUnsetLeavesWhitelistEmpty) {
         config.getArray<std::string>("topology/rdma_whitelist").empty());
 }
 
+TEST(TransferEngineConfigOverrideTest, CustomTopoJsonEnvLoadsPath) {
+    EnvVarGuard guard("MC_CUSTOM_TOPO_JSON",
+                      "/tmp/mooncake-nic-priority-matrix.json");
+
+    Config config;
+    ASSERT_TRUE(ConfigHelper().loadFromEnv(config).ok());
+
+    EXPECT_EQ(config.get("topology/custom_json_path", ""),
+              "/tmp/mooncake-nic-priority-matrix.json");
+}
+
+TEST(TransferEngineConfigOverrideTest,
+     ExplicitRdmaWhitelistOverridesLegacyFilterEnv) {
+    EnvVarGuard guard("MC_TE_FILTERS", "mlx5_from_env_0,mlx5_from_env_1");
+
+    auto config = std::make_shared<Config>();
+    const std::vector<std::string> explicit_filter{"mlx5_requested"};
+    config->set("topology/rdma_whitelist", explicit_filter);
+    config->set("rpc_server_hostname", kInvalidHostname);
+
+    TransferEngineImpl engine(config);
+
+    EXPECT_FALSE(engine.available());
+    EXPECT_EQ(config->getArray<std::string>("topology/rdma_whitelist"),
+              explicit_filter);
+}
+
+TEST(TransferEngineConfigOverrideTest,
+     ExplicitRdmaWhitelistOverridesMcTentConf) {
+    TempConfigFile conf_file(R"({
+        "topology": {
+            "rdma_whitelist": ["mlx5_from_env_0", "mlx5_from_env_1"]
+        }
+    })");
+    EnvVarGuard guard("MC_TENT_CONF", conf_file.path());
+
+    auto config = std::make_shared<Config>();
+    const std::vector<std::string> explicit_filter{"mlx5_requested"};
+    config->set("topology/rdma_whitelist", explicit_filter);
+    // Stop construction before platform probing; this test only needs the
+    // constructor's config merge and remains hardware-independent.
+    config->set("rpc_server_hostname", kInvalidHostname);
+
+    TransferEngineImpl engine(config);
+
+    EXPECT_FALSE(engine.available());
+    EXPECT_EQ(config->getArray<std::string>("topology/rdma_whitelist"),
+              explicit_filter);
+}
+
 TEST(TransferEngineConfigOverrideTest,
      ExplicitMetadataOverridesDriveSuccessfulHttpInitialization) {
 #ifdef _WIN32
@@ -351,6 +467,8 @@ TEST(TransferEngineConfigOverrideTest,
 
     const auto live_endpoint = buildHttpMetadataEndpoint(live_port);
     const auto dead_endpoint = buildHttpMetadataEndpoint(dead_port);
+    // The HTTP server keeps this port occupied, so automatic RPC port
+    // selection cannot legitimately choose the value from the file.
     TempConfigFile conf_file(
         "{\n"
         "  \"metadata_type\": \"p2p\",\n"
@@ -360,7 +478,9 @@ TEST(TransferEngineConfigOverrideTest,
         "  \"rpc_server_hostname\": \"" +
         std::string(kLoopbackHostname) +
         "\",\n"
-        "  \"rpc_server_port\": 15011,\n"
+        "  \"rpc_server_port\": " +
+        std::to_string(live_port) +
+        ",\n"
         "  \"log_level\": \"warning\",\n"
         "  \"merge_requests\": false\n"
         "}");
@@ -386,7 +506,7 @@ TEST(TransferEngineConfigOverrideTest,
         EXPECT_EQ(engine.getSegmentName(), kSegmentName);
         EXPECT_EQ(engine.getRpcServerAddress(), kLoopbackHostname);
         EXPECT_NE(engine.getRpcServerPort(), 0);
-        EXPECT_NE(engine.getRpcServerPort(), 15011);
+        EXPECT_NE(engine.getRpcServerPort(), live_port);
 
         EXPECT_EQ(config->get("log_level", ""), "warning");
         EXPECT_FALSE(config->get("merge_requests", true));
@@ -401,6 +521,39 @@ TEST(TransferEngineConfigOverrideTest,
 #endif
 }
 
+TEST(TransferEngineConfigOverrideTest,
+     NestedCallerTransportLeafSurvivesMcTentConf) {
+    TempConfigFile conf_file(R"({
+        "metadata_type": "p2p",
+        "metadata_servers": "127.0.0.1:2379",
+        "rpc_server_hostname": "256.256.256.256",
+        "rpc_server_port": 15014,
+        "transports": {
+            "ascend_direct": {
+                "agent_mode": false,
+                "fabric_mem": false,
+                "transfer_timeout_ms": 1234
+            }
+        }
+    })");
+    EnvVarGuard guard("MC_TENT_CONF", conf_file.path());
+
+    auto config = std::make_shared<Config>();
+    config->set("local_segment_name", "store-segment-C");
+    config->set("transports/ascend_direct/agent_mode", true);
+    config->set("transports/ascend_direct/store_te_init", true);
+
+    TransferEngineImpl engine(config);
+
+    EXPECT_TRUE(config->get("transports/ascend_direct/agent_mode", false));
+    EXPECT_TRUE(config->get("transports/ascend_direct/store_te_init", false));
+    EXPECT_FALSE(config->get("transports/ascend_direct/fabric_mem", true));
+    EXPECT_EQ(config->get("transports/ascend_direct/transfer_timeout_ms", 0),
+              1234);
+    EXPECT_EQ(config->get("local_segment_name", ""), "store-segment-C");
+    EXPECT_EQ(config->get("metadata_type", ""), "p2p");
+}
+
 TEST(TransferEngineConfigOverrideTest,
      MissingExplicitKeysContinueUsingMcTentConfValuesThroughConstructor) {
     TempConfigFile conf_file(R"({
@@ -451,6 +604,61 @@ TEST(TransferEngineConfigOverrideTest,
     }
 }
 
+TEST(TransferEngineConfigOverrideTest,
+     RegisterLocalMemoryIgnoresIncompatibleCallerLocation) {
+#ifdef _WIN32
+    GTEST_SKIP() << "Requires local HTTP metadata server support";
+#else
+    // registerLocalMemory observes existing memory; the NUMA probe is the
+    // source of truth for transport selection. A caller-supplied location
+    // must not overwrite the probe with an unknown or incompatible type.
+    // The store's buildSegmentsLocation() emits "segments:4096:0,1" (a
+    // classic TE NUMA-segment encoding TENT's type system does not
+    // understand); blindly adopting it made getTypeEnum() return
+    // MTYPE_UNKNOWN and broke transport selection (warmup "Unable to find
+    // registered buffer"). The override must validate and keep the probe.
+    const auto live_port = reserveUnusedTcpPort();
+    TestHttpMetadataServer metadata_server(live_port);
+    ASSERT_TRUE(metadata_server.start());
+    const auto live_endpoint = buildHttpMetadataEndpoint(live_port);
+
+    auto config = std::make_shared<Config>();
+    config->set("metadata_type", "http");
+    config->set("metadata_servers", live_endpoint);
+    config->set("local_segment_name", kSegmentName);
+    config->set("rpc_server_hostname", kLoopbackHostname);
+    config->set("rpc_server_port", "0");
+    configureTcpOnlyTransports(*config);
+
+    TransferEngineImpl engine(config);
+    ASSERT_TRUE(engine.available());
+
+    // Register a host buffer with an incompatible caller location. The
+    // probe classifies host memory as "cpu:N"; "segments:..." is an unknown
+    // type to TENT and must be ignored in favor of the probe.
+    constexpr size_t kBufSize = 4096;
+    std::vector<char> buf(kBufSize, 0);
+    MemoryOptions options;
+    options.location = "segments:4096:0,1";
+    std::vector<void*> addrs = {buf.data()};
+    std::vector<size_t> sizes = {kBufSize};
+    ASSERT_TRUE(engine.registerLocalMemory(addrs, sizes, options).ok());
+
+    SegmentInfo info;
+    ASSERT_TRUE(engine.getSegmentInfo(LOCAL_SEGMENT_ID, info).ok());
+    ASSERT_EQ(info.buffers.size(), 1u);
+    // The buffer location must be the probed "cpu:..." form, NOT the
+    // caller-supplied "segments:..." string.
+    const auto& loc = info.buffers[0].location;
+    EXPECT_NE(loc.find("cpu"), std::string::npos)
+        << "expected probed cpu location, got '" << loc << "'";
+    EXPECT_EQ(loc.find("segments"), std::string::npos)
+        << "caller 'segments:' must not leak into buffer location";
+
+    engine.unregisterLocalMemory(buf.data(), kBufSize);
+#endif
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/transport_hint_test.cpp b/mooncake-transfer-engine/tent/tests/transport_hint_test.cpp
index 84cfdc5bb6..e6319f6bd2 100644
--- a/mooncake-transfer-engine/tent/tests/transport_hint_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/transport_hint_test.cpp
@@ -59,6 +59,10 @@ class FakeTransport : public Transport {
     }
 
     std::atomic<int> submit_calls{0};
+    std::vector<uint64_t> submitted_device_masks;
+    std::vector<std::string> submitted_qp_pools;
+    std::vector<size_t> submitted_request_counts;
+    std::string fail_qp_pool_once;
 
     Status install(std::string&, std::shared_ptr<ControlService>,
                    std::shared_ptr<Topology>,
@@ -80,6 +84,13 @@ class FakeTransport : public Transport {
                                const std::vector<Request>& reqs) override {
         ++submit_calls;
         auto* fb = static_cast<FakeSubBatch*>(batch);
+        submitted_device_masks.push_back(fb->device_mask);
+        submitted_qp_pools.push_back(fb->qp_pool);
+        submitted_request_counts.push_back(reqs.size());
+        if (!fail_qp_pool_once.empty() && fb->qp_pool == fail_qp_pool_once) {
+            fail_qp_pool_once.clear();
+            return Status::InternalError("injected submit failure" LOC_MARK);
+        }
         for (const auto& req : reqs) {
             fb->statuses.push_back({TransferStatusEnum::COMPLETED, req.length});
             fb->task_count++;
@@ -215,6 +226,39 @@ TEST(TransportHint, RoutesPinnedRequestsToHintedTransport) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
 }
 
+TEST(TransportHint, ForceTcpOverridesLegacySelection) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("use_legacy_transport_selection", true);
+    cfg->set("transports/force_tcp", true);
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    auto fake_shm = std::make_shared<FakeTransport>(SHM);
+    auto fake_tcp = std::make_shared<FakeTransport>(TCP);
+    std::string seg_name = engine.getSegmentName();
+    ASSERT_TRUE(fake_shm->install(seg_name, nullptr, nullptr).ok());
+    ASSERT_TRUE(fake_tcp->install(seg_name, nullptr, nullptr).ok());
+    engine.swapTransportForTest(SHM, fake_shm);
+    engine.swapTransportForTest(TCP, fake_tcp);
+
+    constexpr size_t kBufLen = 4096;
+    std::vector<uint8_t> buf(kBufLen, 0x01);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    BatchID batch_id = engine.allocateBatch(1);
+    ASSERT_NE(batch_id, (BatchID)0);
+    ASSERT_TRUE(engine
+                    .submitTransfer(
+                        batch_id, {makeLocalWriteRequest(buf.data(), kBufLen)})
+                    .ok());
+
+    EXPECT_EQ(fake_shm->submit_calls.load(), 0);
+    EXPECT_EQ(fake_tcp->submit_calls.load(), 1);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
 // ---------------------------------------------------------------------------
 // 2. Disabled transport rejected before batch state mutates
 // ---------------------------------------------------------------------------
@@ -346,6 +390,137 @@ TEST(TransportHint, MixedHintsInBatchSplitAcrossTransports) {
     EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
 }
 
+// ---------------------------------------------------------------------------
+// 6. Requests using different RDMA policies must not share one scalar
+//    SubBatch policy. The A/B/A order also verifies physical task IDs after
+//    policy grouping remain aligned with the transport's append order.
+// ---------------------------------------------------------------------------
+
+TEST(TransportPolicy, SplitsRdmaSubBatchesByResolvedPolicy) {
+    auto cfg = makeMinimalP2PConfig();
+    cfg->set("merge_requests", true);
+    json topology;
+    topology["cpu:0"] = {{"mlx5_0"}, {"mlx5_1"}};
+    cfg->set("topology/priority_matrix", topology);
+    json policy_a;
+    policy_a["name"] = "rdma-a";
+    policy_a["segment_type"] = "memory";
+    policy_a["transports"] = {"rdma"};
+    policy_a["devices"] = {"mlx5_0"};
+    policy_a["qp_pool"] = "pool-a";
+    json policy_b;
+    policy_b["name"] = "rdma-b";
+    policy_b["segment_type"] = "memory";
+    policy_b["transports"] = {"rdma"};
+    policy_b["devices"] = {"mlx5_1"};
+    policy_b["qp_pool"] = "pool-b";
+    cfg->set("policy", json::array({policy_a, policy_b}));
+
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma, fake_tcp;
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+
+    constexpr size_t kRequestLengths[] = {1024, 2048, 3072};
+    constexpr size_t kBufLen =
+        kRequestLengths[0] + kRequestLengths[1] + kRequestLengths[2];
+    std::vector<uint8_t> buf(kBufLen, 0xCC);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    Request request_a0 = makeLocalWriteRequest(buf.data(), kRequestLengths[0]);
+    request_a0.policy_name = "rdma-a";
+    Request request_b = makeLocalWriteRequest(buf.data() + kRequestLengths[0],
+                                              kRequestLengths[1]);
+    request_b.policy_name = "rdma-b";
+    Request request_a1 = makeLocalWriteRequest(
+        buf.data() + kRequestLengths[0] + kRequestLengths[1],
+        kRequestLengths[2]);
+    request_a1.policy_name = "rdma-a";
+
+    BatchID batch_id = engine.allocateBatch(4);
+    ASSERT_TRUE(
+        engine.submitTransfer(batch_id, {request_a0, request_b, request_a1})
+            .ok());
+
+    ASSERT_EQ(fake_rdma->submit_calls.load(), 2);
+    ASSERT_EQ(fake_rdma->submitted_request_counts.size(), 2u);
+    EXPECT_EQ(fake_rdma->submitted_request_counts[0], 2u);
+    EXPECT_EQ(fake_rdma->submitted_request_counts[1], 1u);
+    ASSERT_EQ(fake_rdma->submitted_device_masks.size(), 2u);
+    EXPECT_EQ(fake_rdma->submitted_device_masks[0], 1ULL);
+    EXPECT_EQ(fake_rdma->submitted_device_masks[1], 1ULL << 1);
+    ASSERT_EQ(fake_rdma->submitted_qp_pools.size(), 2u);
+    EXPECT_EQ(fake_rdma->submitted_qp_pools[0], "pool-a");
+    EXPECT_EQ(fake_rdma->submitted_qp_pools[1], "pool-b");
+
+    for (size_t task_id = 0; task_id < 3; ++task_id) {
+        TransferStatus status;
+        ASSERT_TRUE(engine.getTransferStatus(batch_id, task_id, status).ok());
+        EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED);
+        EXPECT_EQ(status.transferred_bytes, kRequestLengths[task_id]);
+    }
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
+// A failed homogeneous group may return without appending any transport task.
+// The next group must derive its task ID from the SubBatch's actual size, not
+// from the number of requests the engine intended to submit.
+TEST(TransportPolicy, SyncFailureDoesNotShiftLaterGroupTaskIds) {
+    auto cfg = makeMinimalP2PConfig();
+    json topology;
+    topology["cpu:0"] = {{"mlx5_0"}, {"mlx5_1"}};
+    cfg->set("topology/priority_matrix", topology);
+    json failing_policy;
+    failing_policy["name"] = "rdma-fail";
+    failing_policy["segment_type"] = "memory";
+    failing_policy["transports"] = {"rdma"};
+    failing_policy["devices"] = {"mlx5_0"};
+    failing_policy["qp_pool"] = "pool-fail";
+    json succeeding_policy;
+    succeeding_policy["name"] = "rdma-ok";
+    succeeding_policy["segment_type"] = "memory";
+    succeeding_policy["transports"] = {"rdma"};
+    succeeding_policy["devices"] = {"mlx5_1"};
+    succeeding_policy["qp_pool"] = "pool-ok";
+    cfg->set("policy", json::array({failing_policy, succeeding_policy}));
+
+    TransferEngineImpl engine(cfg);
+    ASSERT_TRUE(engine.available());
+
+    std::shared_ptr<FakeTransport> fake_rdma, fake_tcp;
+    installFakeRdmaAndTcp(engine, fake_rdma, fake_tcp);
+    fake_rdma->fail_qp_pool_once = "pool-fail";
+
+    constexpr size_t kRequestLength = 4096;
+    constexpr size_t kBufLen = 2 * kRequestLength;
+    std::vector<uint8_t> buf(kBufLen, 0xDD);
+    ASSERT_TRUE(engine.registerLocalMemory(buf.data(), kBufLen).ok());
+
+    Request failing = makeLocalWriteRequest(buf.data(), kRequestLength);
+    failing.policy_name = "rdma-fail";
+    Request succeeding =
+        makeLocalWriteRequest(buf.data() + kRequestLength, kRequestLength);
+    succeeding.policy_name = "rdma-ok";
+
+    BatchID batch_id = engine.allocateBatch(2);
+    ASSERT_TRUE(engine.submitTransfer(batch_id, {failing, succeeding}).ok());
+    ASSERT_EQ(fake_rdma->submit_calls.load(), 2);
+
+    TransferStatus failed_status;
+    ASSERT_TRUE(engine.getTransferStatus(batch_id, 0, failed_status).ok());
+    EXPECT_EQ(failed_status.s, TransferStatusEnum::FAILED);
+
+    TransferStatus completed_status;
+    ASSERT_TRUE(engine.getTransferStatus(batch_id, 1, completed_status).ok());
+    EXPECT_EQ(completed_status.s, TransferStatusEnum::COMPLETED);
+
+    EXPECT_TRUE(engine.freeBatch(batch_id).ok());
+    EXPECT_TRUE(engine.unregisterLocalMemory(buf.data(), kBufLen).ok());
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/transport_selector_test.cpp b/mooncake-transfer-engine/tent/tests/transport_selector_test.cpp
index 5d3a9ce66f..240c4788d8 100644
--- a/mooncake-transfer-engine/tent/tests/transport_selector_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/transport_selector_test.cpp
@@ -21,6 +21,7 @@
 
 #include "tent/common/config.h"
 #include "tent/common/types.h"
+#include "tent/transfer_engine.h"
 #include "tent/runtime/transport_selector.h"
 #include "tent/runtime/transport.h"
 
@@ -170,6 +171,66 @@ TEST(TransportSelectorTest, DefaultPoliciesMemorySegment) {
         << "Should use first in buffer_transports";
 }
 
+TEST(TransportSelectorTest, ForceTcpOverridesBufferTransportOrder) {
+    auto conf = std::make_shared<Config>();
+    ASSERT_TRUE(
+        conf->load(
+                R"({"policy":[{"name":"prefer-rdma","segment_type":"memory","transports":["rdma"]}]})")
+            .ok());
+    conf->set("transports/force_tcp", true);
+    TransportSelector selector(conf);
+
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[RDMA] = std::make_shared<FakeTransport>(RDMA);
+    transports[TCP] = std::make_shared<FakeTransport>(TCP);
+
+    auto* rdma = static_cast<FakeTransport*>(transports[RDMA].get());
+    rdma->setDramToDram(true);
+    auto* tcp = static_cast<FakeTransport*>(transports[TCP].get());
+    tcp->setDramToDram(true);
+
+    std::vector<TransportType> buffer_transports = {RDMA, TCP};
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::Memory;
+    ctx.same_machine = false;
+    ctx.local_memory_type = MTYPE_CPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.transfer_size = 4096;
+    ctx.priority_level = 0;
+    ctx.buffer_transports = &buffer_transports;
+
+    EXPECT_EQ(selector.select(ctx, transports).transport, TCP);
+    EXPECT_EQ(selector.select(ctx, transports, 1).transport, UNSPEC);
+    EXPECT_EQ(selector.select(ctx, transports, 0, RDMA).transport, UNSPEC);
+}
+
+TEST(TransportSelectorTest, ForceTcpDoesNotOverrideFileTransportPolicy) {
+    auto conf = std::make_shared<Config>();
+    ASSERT_TRUE(
+        conf->load(
+                R"({"policy":[{"name":"file","segment_type":"file","transports":["gds"]}]})")
+            .ok());
+    conf->set("transports/force_tcp", true);
+    TransportSelector selector(conf);
+
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[GDS] = std::make_shared<FakeTransport>(GDS);
+    static_cast<FakeTransport*>(transports[GDS].get())->setDramToFile(true);
+
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::File;
+    ctx.same_machine = true;
+    ctx.local_memory_type = MTYPE_CPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.transfer_size = 4096;
+    ctx.priority_level = 0;
+    ctx.buffer_transports = nullptr;
+
+    EXPECT_EQ(selector.select(ctx, transports).transport, GDS);
+}
+
 // ---------------------------------------------------------------------------
 // Test transport type name parsing
 // ---------------------------------------------------------------------------
@@ -186,6 +247,8 @@ TEST(TransportSelectorTest, TransportTypeNameMapping) {
     EXPECT_STREQ(transportTypeName(AscendDirect), "ascend");
     EXPECT_STREQ(transportTypeName(SUNRISE_LINK), "sunrise_link");
     EXPECT_STREQ(transportTypeName(UB), "ub");
+    EXPECT_STREQ(transportTypeName(MPCOMM), "mpcomm");
+    EXPECT_STREQ(transportTypeName(HP_TCP), "hp_tcp");
 }
 
 TEST(TransportSelectorTest, ParseTransportType) {
@@ -200,6 +263,8 @@ TEST(TransportSelectorTest, ParseTransportType) {
     EXPECT_EQ(parseTransportType("ascend"), AscendDirect);
     EXPECT_EQ(parseTransportType("sunrise_link"), SUNRISE_LINK);
     EXPECT_EQ(parseTransportType("ub"), UB);
+    EXPECT_EQ(parseTransportType("mpcomm"), MPCOMM);
+    EXPECT_EQ(parseTransportType("hp_tcp"), HP_TCP);
     EXPECT_EQ(parseTransportType("unknown"), UNSPEC);
 }
 
@@ -209,7 +274,7 @@ TEST(TransportSelectorTest, UbTransportNameRoundTrips) {
     EXPECT_EQ(parseTransportType(name), UB);
 }
 
-TEST(TransportTypeTest, WireValuesRemainStableWithUbAppended) {
+TEST(TransportTypeTest, WireValuesRemainStableWithXpuAppended) {
     EXPECT_EQ(static_cast<int>(UNSPEC), 0);
     EXPECT_EQ(static_cast<int>(RDMA), 1);
     EXPECT_EQ(static_cast<int>(MNNVL), 2);
@@ -222,7 +287,46 @@ TEST(TransportTypeTest, WireValuesRemainStableWithUbAppended) {
     EXPECT_EQ(static_cast<int>(SUNRISE_LINK), 9);
     EXPECT_EQ(static_cast<int>(TPU), 10);
     EXPECT_EQ(static_cast<int>(UB), 11);
-    EXPECT_EQ(static_cast<int>(kNumTransportTypes), 12);
+    EXPECT_EQ(static_cast<int>(MPCOMM), 12);
+    EXPECT_EQ(static_cast<int>(HP_TCP), 13);
+    EXPECT_EQ(static_cast<int>(XPU), 14);
+    EXPECT_EQ(static_cast<int>(kNumTransportTypes), 15);
+}
+
+// MPComm is appended after UB, so it takes wire value 12. The same integer is
+// exposed through the C API macros and the Python binding, which makes it a
+// compatibility contract rather than an implementation detail. pybind.cpp
+// carries a matching static_assert so a divergence fails the build.
+TEST(TransportTypeTest, MpcommWireValueMatchesCApiAndRoundTrips) {
+    EXPECT_EQ(static_cast<int>(MPCOMM), 12);
+    EXPECT_EQ(TRANSPORT_MPCOMM, static_cast<int>(MPCOMM));
+    EXPECT_EQ(TRANSPORT_UB, static_cast<int>(UB));
+    // The conversion the C API actually performs on an incoming hint.
+    EXPECT_EQ(c_to_transport_hint(TRANSPORT_MPCOMM), MPCOMM);
+    // Name mapping is what policy parsing relies on; a gap here would make
+    // "transports": ["mpcomm"] resolve to UNSPEC silently.
+    EXPECT_STREQ(transportTypeName(MPCOMM), "mpcomm");
+    EXPECT_EQ(parseTransportType("mpcomm"), MPCOMM);
+}
+
+TEST(TransportTypeTest, HpTcpWireValueMatchesCApiAndRoundTrips) {
+    EXPECT_EQ(static_cast<int>(HP_TCP), 13);
+    EXPECT_EQ(TRANSPORT_HP_TCP, static_cast<int>(HP_TCP));
+    EXPECT_EQ(c_to_transport_hint(TRANSPORT_HP_TCP), HP_TCP);
+    EXPECT_STREQ(transportTypeName(HP_TCP), "hp_tcp");
+    EXPECT_EQ(parseTransportType("hp_tcp"), HP_TCP);
+}
+
+// XPU is appended after HP_TCP, so it takes wire value 14. Like the other
+// appended transports its integer is a compatibility contract shared with the
+// C API macro and the Python binding; pybind.cpp carries a matching
+// static_assert.
+TEST(TransportTypeTest, XpuWireValueMatchesCApiAndRoundTrips) {
+    EXPECT_EQ(static_cast<int>(XPU), 14);
+    EXPECT_EQ(TRANSPORT_XPU, static_cast<int>(XPU));
+    EXPECT_EQ(c_to_transport_hint(TRANSPORT_XPU), XPU);
+    EXPECT_STREQ(transportTypeName(XPU), "xpu");
+    EXPECT_EQ(parseTransportType("xpu"), XPU);
 }
 
 // Topology::NicType is serialized as an integer. These values are therefore a
@@ -481,6 +585,143 @@ TEST(TransportSelectorTest, TransportCapabilityGpuToDram) {
         << "RDMA should be available for CUDA-to-CPU";
 }
 
+// The XPU staging transport advertises only gpu_to_dram / dram_to_gpu, and XPU
+// VRAM (MTYPE_XPU) must be treated as a device type by the selector's is_gpu
+// predicate. The local VRAM->host stage is therefore routed to XpuTransport via
+// gpu_to_dram, and because XpuTransport never advertises gpu_to_gpu a VRAM<->
+// VRAM hop is not directly available (the engine stages it through host DRAM).
+TEST(TransportSelectorTest, XpuStagingRoutesDeviceToHostViaGpuToDram) {
+    auto conf = std::make_shared<Config>();
+    TransportSelector selector(conf);
+
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[XPU] = std::make_shared<FakeTransport>(XPU);
+    auto* xpu = static_cast<FakeTransport*>(transports[XPU].get());
+    xpu->setGpuToDram(true);
+    xpu->setDramToGpu(true);
+
+    std::vector<TransportType> buffer_transports = {XPU};
+
+    // Local stage: XPU VRAM -> host DRAM. XpuTransport is a same-machine-only
+    // executor, so the staging hop is always same_machine.
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::Memory;
+    ctx.same_machine = true;
+    ctx.local_segment = true;
+    ctx.local_memory_type = MTYPE_XPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.buffer_transports = &buffer_transports;
+
+    auto result = selector.select(ctx, transports);
+    EXPECT_EQ(result.transport, XPU)
+        << "XPU VRAM->host stage should route to XpuTransport (gpu_to_dram)";
+
+    // The mirrored host->VRAM direction uses dram_to_gpu.
+    ctx.local_memory_type = MTYPE_CPU;
+    ctx.remote_memory_type = MTYPE_XPU;
+    result = selector.select(ctx, transports);
+    EXPECT_EQ(result.transport, XPU)
+        << "host->XPU VRAM stage should route to XpuTransport (dram_to_gpu)";
+
+    // VRAM<->VRAM needs gpu_to_gpu, which XpuTransport never advertises, so it
+    // is not directly available and the engine must stage through host DRAM.
+    ctx.local_memory_type = MTYPE_XPU;
+    ctx.remote_memory_type = MTYPE_XPU;
+    result = selector.select(ctx, transports);
+    EXPECT_EQ(result.transport, UNSPEC)
+        << "XPU VRAM<->VRAM must not be directly routable (forces staging)";
+}
+
+// Regression: XPU is a local-stage-only executor, so it must never be selected
+// for a remote (cross-machine) hop -- the same invariant TPU has. Without XPU
+// in the selector's same-machine guard, an XPU-tagged buffer on a remote
+// segment would be picked via gpu_to_dram and only fail later at execution
+// time.
+TEST(TransportSelectorTest, XpuIsNotRoutableAcrossMachines) {
+    auto conf = std::make_shared<Config>();
+    TransportSelector selector(conf);
+
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[XPU] = std::make_shared<FakeTransport>(XPU);
+    auto* xpu = static_cast<FakeTransport*>(transports[XPU].get());
+    xpu->setGpuToDram(true);
+    xpu->setDramToGpu(true);
+
+    std::vector<TransportType> buffer_transports = {XPU};
+
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::Memory;
+    ctx.same_machine = false;  // remote hop
+    ctx.local_memory_type = MTYPE_XPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.buffer_transports = &buffer_transports;
+
+    EXPECT_EQ(selector.select(ctx, transports).transport, UNSPEC)
+        << "XPU must never carry a remote hop; it is local-stage-only";
+    ctx.same_machine = true;
+    EXPECT_EQ(selector.select(ctx, transports).transport, UNSPEC)
+        << "a different segment on the same host is not process-local";
+}
+
+// Regression: a SelectionPolicy memory pattern of "xpu" must match XPU VRAM
+// (MTYPE_XPU). matchesMemoryPattern maps MTYPE_XPU -> "xpu"; without that arm
+// XPU fell through to "unknown" and no xpu-scoped policy could ever match.
+TEST(TransportSelectorTest, XpuMemoryPatternMatchesPolicy) {
+    auto conf = std::make_shared<Config>();
+    ASSERT_TRUE(
+        conf->load(
+                R"({"policy":[{"name":"xpu_stage","segment_type":"memory","local_memory":"xpu","transports":["xpu"]}]})")
+            .ok());
+    TransportSelector selector(conf);
+
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[XPU] = std::make_shared<FakeTransport>(XPU);
+    static_cast<FakeTransport*>(transports[XPU].get())->setGpuToDram(true);
+
+    std::vector<TransportType> buffer_transports = {XPU};
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::Memory;
+    ctx.same_machine = true;  // XPU stage is same-machine only
+    ctx.local_segment = true;
+    ctx.local_memory_type = MTYPE_XPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.buffer_transports = &buffer_transports;
+
+    EXPECT_EQ(selector.select(ctx, transports).transport, XPU)
+        << "an 'xpu' local_memory policy must match MTYPE_XPU buffers";
+}
+
+TEST(TransportSelectorTest, XpuStagingUsesHostCapsWithoutBypassingPolicy) {
+    auto conf = std::make_shared<Config>();
+    ASSERT_TRUE(conf->load(R"({"policy":[{"name":"xpu_network",
+        "segment_type":"memory","local_memory":"xpu",
+        "transports":["hp_tcp","rdma"]}]})")
+                    .ok());
+    TransportSelector selector(conf);
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    for (auto type : {HP_TCP, RDMA, TCP}) {
+        transports[type] = std::make_shared<FakeTransport>(type);
+        static_cast<FakeTransport*>(transports[type].get())
+            ->setDramToDram(true);
+    }
+    SelectionContext ctx{};
+    ctx.segment_type = SegmentType::Memory;
+    ctx.local_memory_type = ctx.remote_memory_type = MTYPE_XPU;
+    EXPECT_EQ(selector.select(ctx, transports).transport, UNSPEC);
+    ctx.host_staging = true;
+    EXPECT_EQ(selector.select(ctx, transports).transport, HP_TCP);
+    EXPECT_EQ(selector.select(ctx, transports, 0, RDMA).transport, RDMA);
+    EXPECT_EQ(selector.select(ctx, transports, 0, TCP).transport, UNSPEC);
+    EXPECT_EQ(selector.select(ctx, transports, 0, XPU).transport, UNSPEC);
+    ctx.local_memory_type = MTYPE_CPU;
+    EXPECT_EQ(selector.select(ctx, transports).transport, UNSPEC)
+        << "staging must not bypass the original memory policy";
+}
+
 TEST(TransportSelectorTest, FileSegmentDramToFile) {
     auto conf = std::make_shared<Config>();
     TransportSelector selector(conf);
@@ -668,34 +909,18 @@ TEST(TransportSelectorTest, RocmMemoryTypeSupported) {
 
 TEST(TransportSelectorTest, ConfigBasedPolicySelection) {
     auto conf = std::make_shared<Config>();
-
-    // Set up a custom policy via JSON config
-    conf->set("policy", json::array());
-    auto policies = conf->getArray<json>("policy");
-
-    json policy;
-    policy["name"] = "test_memory_policy";
-    policy["segment_type"] = "memory";
-    policy["transports"] = {"tcp", "rdma"};  // Prefer TCP over RDMA
-
-    // We can't easily modify the config's internal JSON structure,
-    // so this test verifies the selector at least loads without error
-
+    ASSERT_TRUE(
+        conf->load(
+                R"({"policy":[{"name":"hp_tcp_memory","segment_type":"memory","transports":["hp_tcp"]}]})")
+            .ok());
     TransportSelector selector(conf);
 
-    // Default behavior should still work
     std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
         transports{};
-    transports[RDMA] = std::make_shared<FakeTransport>(RDMA);
-    transports[TCP] = std::make_shared<FakeTransport>(TCP);
-
-    auto* rdma = static_cast<FakeTransport*>(transports[RDMA].get());
-    rdma->setDramToDram(true);
-    auto* tcp = static_cast<FakeTransport*>(transports[TCP].get());
-    tcp->setDramToDram(true);
-
-    std::vector<TransportType> buffer_transports = {RDMA, TCP};
+    transports[HP_TCP] = std::make_shared<FakeTransport>(HP_TCP);
+    static_cast<FakeTransport*>(transports[HP_TCP].get())->setDramToDram(true);
 
+    const std::vector<TransportType> buffer_transports = {HP_TCP};
     SelectionContext ctx;
     ctx.segment_type = SegmentType::Memory;
     ctx.same_machine = false;
@@ -703,9 +928,7 @@ TEST(TransportSelectorTest, ConfigBasedPolicySelection) {
     ctx.remote_memory_type = MTYPE_CPU;
     ctx.buffer_transports = &buffer_transports;
 
-    auto result = selector.select(ctx, transports);
-    // With default policies, should use buffer_transports order (RDMA first)
-    EXPECT_EQ(result.transport, RDMA);
+    EXPECT_EQ(selector.select(ctx, transports).transport, HP_TCP);
 }
 
 TEST(TransportSelectorTest, PolicyCanPreferUb) {
@@ -1217,6 +1440,117 @@ TEST(TransportSelectorTest, ExplicitPolicyNameOverridesIntentFilter) {
     EXPECT_EQ(selector.select(ctx, transports).transport, TCP);
 }
 
+// ---------------------------------------------------------------------------
+// Device mask resolution (names -> mask, once, at setTopology)
+// ---------------------------------------------------------------------------
+
+std::shared_ptr<Config> configWithDeviceList(
+    const std::vector<std::string>& devices) {
+    json policy;
+    policy["name"] = "device_pinned";
+    policy["segment_type"] = "memory";
+    policy["transports"] = {"tcp"};
+    policy["devices"] = devices;
+
+    auto conf = std::make_shared<Config>();
+    conf->set("policy", json::array({policy}));
+    return conf;
+}
+
+std::shared_ptr<Topology> topologyWithNics(size_t count) {
+    auto topology = std::make_shared<Topology>();
+    for (size_t i = 0; i < count; ++i) {
+        Topology::NicEntry nic;
+        nic.name = "mlx5_" + std::to_string(i);
+        nic.type = Topology::NIC_RDMA;
+        topology->nic_list_.push_back(nic);
+    }
+    return topology;
+}
+
+uint64_t selectDeviceMask(TransportSelector& selector) {
+    std::array<std::shared_ptr<Transport>, kSupportedTransportTypes>
+        transports{};
+    transports[TCP] = std::make_shared<FakeTransport>(TCP);
+    static_cast<FakeTransport*>(transports[TCP].get())->setDramToDram(true);
+
+    SelectionContext ctx;
+    ctx.segment_type = SegmentType::Memory;
+    ctx.same_machine = false;
+    ctx.local_memory_type = MTYPE_CPU;
+    ctx.remote_memory_type = MTYPE_CPU;
+    ctx.transfer_size = 4096;
+    ctx.priority_level = PRIO_HIGH;
+    ctx.buffer_transports = nullptr;
+    return selector.select(ctx, transports).device_mask;
+}
+
+TEST(TransportSelectorTest, DeviceMaskResolvesNamedNics) {
+    TransportSelector selector(configWithDeviceList({"mlx5_1", "mlx5_3"}));
+    selector.setTopology(topologyWithNics(4));
+
+    EXPECT_EQ(selectDeviceMask(selector), (1ULL << 1) | (1ULL << 3));
+}
+
+// The mask is resolved at setTopology, so it must be stable no matter how many
+// times select() runs -- this is the regression guard for resolving (and
+// re-logging) per request.
+TEST(TransportSelectorTest, DeviceMaskIsStableAcrossSelects) {
+    TransportSelector selector(configWithDeviceList({"mlx5_0"}));
+    selector.setTopology(topologyWithNics(4));
+
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 0);
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 0);
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 0);
+}
+
+// A replaced topology must re-resolve; a stale mask would name the wrong NICs.
+TEST(TransportSelectorTest, DeviceMaskReresolvesOnNewTopology) {
+    TransportSelector selector(configWithDeviceList({"mlx5_2"}));
+
+    selector.setTopology(topologyWithNics(4));
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 2);
+
+    // Same name, fewer NICs: mlx5_2 no longer exists, so the filter empties
+    // and falls open rather than pinning a NIC id that is now someone else's.
+    selector.setTopology(topologyWithNics(2));
+    EXPECT_EQ(selectDeviceMask(selector), ~0ULL);
+}
+
+// Fail-open is deliberate: a typo must not stop transfers. The behavior is
+// pinned here so it stays a decision rather than drifting into a hard failure.
+TEST(TransportSelectorTest, DeviceMaskFailsOpenWhenNothingResolves) {
+    TransportSelector selector(configWithDeviceList({"nope_0", "nope_1"}));
+    selector.setTopology(topologyWithNics(4));
+
+    EXPECT_EQ(selectDeviceMask(selector), ~0ULL);
+}
+
+// Partially unresolved: the names that do resolve still restrict the mask.
+TEST(TransportSelectorTest, DeviceMaskKeepsResolvedNamesOnPartialFailure) {
+    TransportSelector selector(configWithDeviceList({"mlx5_1", "nope"}));
+    selector.setTopology(topologyWithNics(4));
+
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 1);
+}
+
+// device_mask is 64 bits wide, so a NIC at index >= 64 cannot be named. It is
+// dropped from the mask, not silently promoted to "all devices".
+TEST(TransportSelectorTest, DeviceMaskDropsNicsPastMaskWidth) {
+    TransportSelector selector(configWithDeviceList({"mlx5_0", "mlx5_64"}));
+    selector.setTopology(topologyWithNics(66));
+
+    EXPECT_EQ(selectDeviceMask(selector), 1ULL << 0);
+}
+
+// No topology bound: nothing to resolve names against, so the policy cannot
+// restrict anything and must not restrict everything either.
+TEST(TransportSelectorTest, DeviceMaskAllowsAllWithoutTopology) {
+    TransportSelector selector(configWithDeviceList({"mlx5_0"}));
+
+    EXPECT_EQ(selectDeviceMask(selector), ~0ULL);
+}
+
 }  // namespace
 }  // namespace tent
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/ub_core_test.cpp b/mooncake-transfer-engine/tent/tests/ub_core_test.cpp
index bcbeeb4ae4..217d729286 100644
--- a/mooncake-transfer-engine/tent/tests/ub_core_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/ub_core_test.cpp
@@ -14,16 +14,18 @@
 
 #include <gtest/gtest.h>
 
+#include <algorithm>
 #include <atomic>
 #include <cstdint>
 #include <thread>
 #include <vector>
 
+#include "tent/transport/ub/device_selection.h"
 #include "tent/transport/ub/quota.h"
 #include "tent/transport/ub/params.h"
 #include "tent/transport/ub/rail_monitor.h"
 #include "tent/transport/ub/slice.h"
-#include "tent/transport/ub/device_selection.h"
+#include "tent/transport/ub/workers.h"
 
 namespace mooncake::tent::ub {
 namespace {
@@ -456,16 +458,96 @@ TEST(UbRailMonitorTest, EndpointRebuildTelemetryDeduplicatesGeneration) {
     const auto first = makePath(0, 1, 10);
     const auto replacement = makePath(0, 1, 11);
 
-    EXPECT_TRUE(monitor.recordEndpointRebuild(first, 100));
+    // The first ready generation is the rail's initial build, not a rebuild,
+    // so it seeds the watermark without advancing telemetry.
+    EXPECT_FALSE(monitor.recordEndpointRebuild(first, 100));
     EXPECT_FALSE(monitor.recordEndpointRebuild(first, 101));
     EXPECT_TRUE(monitor.recordEndpointRebuild(replacement, 102));
     // A late callback for an older incarnation cannot double count it.
     EXPECT_FALSE(monitor.recordEndpointRebuild(first, 103));
 
     const auto stats = monitor.stats(replacement, 103);
-    EXPECT_EQ(stats.endpoint_rebuilds, 2U);
+    EXPECT_EQ(stats.endpoint_rebuilds, 1U);
     EXPECT_EQ(stats.latest_endpoint_generation, 11U);
 }
 
+TEST(UbRailMonitorTest, RebuildBaselineIsPerRail) {
+    RailMonitor monitor;
+    const auto rail_a = makePath(0, 1, 5);
+    const auto rail_b = makePath(0, 2, 9);
+
+    EXPECT_FALSE(monitor.recordEndpointRebuild(rail_a, 100));
+    EXPECT_FALSE(monitor.recordEndpointRebuild(rail_b, 101));
+    EXPECT_TRUE(monitor.recordEndpointRebuild(makePath(0, 1, 6), 102));
+
+    EXPECT_EQ(monitor.stats(rail_a, 102).endpoint_rebuilds, 1U);
+    EXPECT_EQ(monitor.stats(rail_b, 102).endpoint_rebuilds, 0U);
+}
+
+TEST(UbRailMonitorTest, StatsIfPresentDoesNotCreateOrSeedRails) {
+    RailMonitor monitor;
+    const auto unknown = makePath(0, 3, 1);
+
+    const auto before = monitor.statsIfPresent(unknown, 100);
+    EXPECT_FALSE(before.paused);
+    EXPECT_LT(before.ewma_bandwidth_bytes_per_second, 0.0);
+    EXPECT_EQ(monitor.pathCount(), 0U);
+
+    // A real record still creates the rail and a non-creating lookup then
+    // returns that state.
+    monitor.recordError(makePath(0, 1, 7), 101);
+    EXPECT_EQ(monitor.pathCount(), 1U);
+    EXPECT_EQ(monitor.statsIfPresent(makePath(0, 1, 7), 101).completion_errors,
+              1U);
+    EXPECT_EQ(monitor.statsIfPresent(unknown, 101).completion_errors, 0U);
+    EXPECT_EQ(monitor.pathCount(), 1U);
+}
+
+TEST(UbRailSelectionTest, AttemptOrderTakesOneRailPerLocalDevice) {
+    // Pre-score order puts both rails of device 0 above device 1's, which is
+    // what a cold peer with no quota pressure looks like.
+    const std::vector<Topology::NicID> ids{0, 0, 1, 1};
+    const auto order = ubResolutionAttemptOrder(ids);
+    ASSERT_EQ(order.size(), 4U);
+    // Device 0's best rail first, then device 1's, before device 0's second
+    // rail: the first two attempts must not share a device.
+    EXPECT_EQ(order[0], 0U);
+    EXPECT_EQ(order[1], 2U);
+    EXPECT_EQ(order[2], 1U);
+    EXPECT_EQ(order[3], 3U);
+}
+
+TEST(UbRailSelectionTest, AttemptOrderCoversEveryLocalDevice) {
+    const std::vector<Topology::NicID> ids{0, 0, 1, 1, 2, 2, 3, 3};
+    const auto order = ubResolutionAttemptOrder(ids);
+    ASSERT_EQ(order.size(), 8U);
+    EXPECT_EQ(order[0], 0U);
+    EXPECT_EQ(order[1], 2U);
+    EXPECT_EQ(order[2], 4U);
+    EXPECT_EQ(order[3], 6U);
+    // The resolve limit for four local devices is four, so every device is
+    // represented before any device gets a second candidate.
+    for (size_t index = 0; index < 4; ++index) {
+        EXPECT_EQ(ids[order[index]], static_cast<Topology::NicID>(index));
+    }
+}
+
+TEST(UbRailSelectionTest, SingleDeviceKeepsPreScoreOrder) {
+    const std::vector<Topology::NicID> ids{7, 7, 7};
+    // With one device there is nothing to spread across, so the attempt order
+    // is the pre-score order and the caller's floor of two candidates takes two
+    // rails on that device.
+    EXPECT_EQ(ubResolutionAttemptOrder(ids), (std::vector<size_t>{0, 1, 2}));
+}
+
+TEST(UbRailSelectionTest, AttemptOrderVisitsEveryRailExactlyOnce) {
+    const std::vector<Topology::NicID> ids{3, 1, 3, 2, 1};
+    const auto order = ubResolutionAttemptOrder(ids);
+    ASSERT_EQ(order.size(), ids.size());
+    for (size_t index = 0; index < ids.size(); ++index) {
+        EXPECT_EQ(std::count(order.begin(), order.end(), index), 1);
+    }
+}
+
 }  // namespace
 }  // namespace mooncake::tent::ub
diff --git a/mooncake-transfer-engine/tent/tests/ub_native_data_path_test.cpp b/mooncake-transfer-engine/tent/tests/ub_native_data_path_test.cpp
index 367211e828..4dc2694de6 100644
--- a/mooncake-transfer-engine/tent/tests/ub_native_data_path_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/ub_native_data_path_test.cpp
@@ -265,7 +265,12 @@ class FakeUrmaAdapter final : public UrmaAdapter {
         }
         return Status::OK();
     }
-    Status resetJetty(const JettyPtr&) override { return Status::OK(); }
+    Status resetJetty(const JettyPtr&) override {
+        if (fail_resets_.load(std::memory_order_acquire)) {
+            return Status::RdmaError("injected Jetty reset failure");
+        }
+        return Status::OK();
+    }
     Status quiesceJetty(const JettyPtr& jetty, uint32_t timeout_ms,
                         std::vector<Completion>& completions) override {
         completions.clear();
@@ -279,18 +284,20 @@ class FakeUrmaAdapter final : public UrmaAdapter {
         const bool drop_completion = drop_next_quiesced_completion_.exchange(
             false, std::memory_order_acq_rel);
         std::lock_guard<std::mutex> lock(pending_mutex_);
-        auto it = pending_.begin();
-        while (it != pending_.end()) {
-            if (it->jetty_id != fake->id()) {
-                ++it;
-                continue;
-            }
-            if (!drop_completion) {
-                completions.push_back(
-                    Completion{CompletionCategory::ENDPOINT_ERROR, 0,
-                               it->request.token, 0, fake->id()});
+        if (!quiesce_drops_completions_.load(std::memory_order_acquire)) {
+            auto it = pending_.begin();
+            while (it != pending_.end()) {
+                if (it->jetty_id != fake->id()) {
+                    ++it;
+                    continue;
+                }
+                if (!drop_completion) {
+                    completions.push_back(
+                        Completion{CompletionCategory::ENDPOINT_ERROR, 0,
+                                   it->request.token, 0, fake->id()});
+                }
+                it = pending_.erase(it);
             }
-            it = pending_.erase(it);
         }
         quiesce_calls_.fetch_add(1, std::memory_order_relaxed);
         return Status::OK();
@@ -360,6 +367,11 @@ class FakeUrmaAdapter final : public UrmaAdapter {
     void failNextQuiesce() {
         fail_next_quiesce_.store(true, std::memory_order_release);
     }
+    void dropQuiesceCompletions() {
+        quiesce_drops_completions_.store(true, std::memory_order_release);
+    }
+    void failResets() { fail_resets_.store(true, std::memory_order_release); }
+    void allowResets() { fail_resets_.store(false, std::memory_order_release); }
     void failNextShutdown() {
         fail_next_shutdown_.store(true, std::memory_order_release);
     }
@@ -388,6 +400,8 @@ class FakeUrmaAdapter final : public UrmaAdapter {
     std::atomic<bool> hold_next_completion_{false};
     std::atomic<bool> drop_next_quiesced_completion_{false};
     std::atomic<bool> fail_next_quiesce_{false};
+    std::atomic<bool> quiesce_drops_completions_{false};
+    std::atomic<bool> fail_resets_{false};
     std::atomic<bool> fail_next_shutdown_{false};
     mutable std::mutex pending_mutex_;
     std::vector<Pending> pending_;
@@ -574,6 +588,159 @@ TEST(UbNativeDataPathTest,
     EXPECT_TRUE(adapter->shutdown().ok());
 }
 
+TEST(UbNativeDataPathTest,
+     ProviderLostCompletionIsReclaimedAfterSuccessfulFence) {
+    auto adapter = std::make_shared<FakeUrmaAdapter>(fakeDevice());
+    ASSERT_TRUE(adapter->initialize().ok());
+    auto context = std::make_shared<UbContext>(0, fakeDevice(), adapter);
+    ASSERT_TRUE(context->initialize(1, JfcOptions{}).ok());
+    std::vector<UbContextPtr> contexts{context};
+    auto topology = fakeTopology();
+    UbBufferManager buffers(adapter, contexts);
+
+    std::array<char, 64> source{};
+    std::array<char, 64> target{};
+    std::array<char, 64> recovered{};
+    for (size_t i = 0; i < source.size(); ++i) {
+        source[i] = static_cast<char>(i + 1);
+    }
+    BufferDesc source_desc{};
+    source_desc.addr = reinterpret_cast<uint64_t>(source.data());
+    source_desc.length = source.size();
+    source_desc.location = kWildcardLocation;
+    BufferDesc target_desc{};
+    target_desc.addr = reinterpret_cast<uint64_t>(target.data());
+    target_desc.length = target.size();
+    target_desc.location = kWildcardLocation;
+    BufferDesc recovered_desc{};
+    recovered_desc.addr = reinterpret_cast<uint64_t>(recovered.data());
+    recovered_desc.length = recovered.size();
+    recovered_desc.location = kWildcardLocation;
+    MemoryOptions options;
+    options.perm = kGlobalReadWrite;
+    ASSERT_TRUE(buffers.addBuffer(source_desc, options).ok());
+    ASSERT_TRUE(buffers.addBuffer(target_desc, options).ok());
+    ASSERT_TRUE(buffers.addBuffer(recovered_desc, options).ok());
+
+    SegmentManager manager(std::make_unique<NullRegistry>());
+    ASSERT_TRUE(
+        manager
+            .updateLocal([&](SegmentDesc& segment) {
+                segment.name = "local";
+                segment.type = SegmentType::Memory;
+                segment.detail = MemorySegmentDesc{};
+                auto& memory = std::get<MemorySegmentDesc>(segment.detail);
+                memory.topology = *topology;
+                memory.buffers = {source_desc, target_desc, recovered_desc};
+                return Status::OK();
+            })
+            .ok());
+
+    EndpointStore endpoints(adapter, 16, 1);
+    RailMonitor rails;
+    QuotaManager quota;
+    UbParams params;
+    params.worker_count = 1;
+    params.poller_count = 1;
+    params.slice_size = 16;
+    params.max_retries = 1;
+    params.slice_timeout_ms = 20;
+
+    std::shared_ptr<UbEndpoint> fenced_endpoint;
+    EndpointResolver resolver = [&](const EndpointResolveRequest& request,
+                                    std::shared_ptr<UbEndpoint>& endpoint) {
+        UbEndpointKey key{request.local_context->topologyId(),
+                          request.remote_segment_id, request.remote_topology_id,
+                          "local@ub:fake0:eid0"};
+        auto status =
+            endpoints.getOrCreate(key, request.local_context, endpoint);
+        if (!status.ok()) return status;
+        if (!fenced_endpoint) fenced_endpoint = endpoint;
+        if (endpoint->ready()) return status;
+        UbBootstrapDesc peer;
+        peer.local_eid = fakeDevice().eid;
+        peer.endpoint_generation = 100;
+        peer.jetty_ids = {777};
+        return endpoint->bind(peer);
+    };
+    UbWorkers workers(adapter, contexts, topology, &manager, &buffers, &rails,
+                      &quota, params, std::move(resolver),
+                      [&](const std::shared_ptr<UbEndpoint>& endpoint) {
+                          (void)endpoints.retire(endpoint);
+                      });
+    ASSERT_TRUE(workers.start().ok());
+    adapter->holdNextCompletion();
+    adapter->dropQuiesceCompletions();
+
+    Request request{};
+    request.opcode = Request::WRITE;
+    request.source = source.data();
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(target.data());
+    request.length = source.size();
+    auto task = UbTask::create(request);
+    for (size_t offset = 0; offset < request.length; offset += 16) {
+        ASSERT_NE(task->addSlice(UbSliceSpec{
+                      source.data() + offset,
+                      reinterpret_cast<uint64_t>(target.data() + offset), 16,
+                      offset, 1}),
+                  nullptr);
+    }
+    ASSERT_TRUE(task->seal());
+    ASSERT_TRUE(workers.submit(task).ok());
+
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (task->transferStatus().s == PENDING &&
+           std::chrono::steady_clock::now() < deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    EXPECT_EQ(task->transferStatus().s, COMPLETED);
+    EXPECT_EQ(task->transferStatus().transferred_bytes, source.size());
+    EXPECT_EQ(source, target);
+    EXPECT_GE(rails.stats(UbPostPath{0, LOCAL_SEGMENT_ID, 0, 1}).timeouts, 1U);
+    EXPECT_GE(adapter->quiesceCalls(), 1U);
+
+    EXPECT_EQ(workers.inflightCount(), 0U);
+    EXPECT_EQ(quota.activeReservationCount(), 0U);
+    ASSERT_NE(fenced_endpoint, nullptr);
+    EXPECT_EQ(fenced_endpoint->outstandingWrs(), 0U);
+    EXPECT_EQ(fenced_endpoint->outstandingBytes(), 0U);
+
+    Request followup{};
+    followup.opcode = Request::WRITE;
+    followup.source = source.data();
+    followup.target_id = LOCAL_SEGMENT_ID;
+    followup.target_offset = reinterpret_cast<uint64_t>(recovered.data());
+    followup.length = source.size();
+    auto followup_task = UbTask::create(followup);
+    for (size_t offset = 0; offset < followup.length; offset += 16) {
+        ASSERT_NE(followup_task->addSlice(UbSliceSpec{
+                      source.data() + offset,
+                      reinterpret_cast<uint64_t>(recovered.data() + offset), 16,
+                      offset, 1}),
+                  nullptr);
+    }
+    ASSERT_TRUE(followup_task->seal());
+    ASSERT_TRUE(workers.submit(followup_task).ok());
+
+    const auto followup_deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(2);
+    while (followup_task->transferStatus().s == PENDING &&
+           std::chrono::steady_clock::now() < followup_deadline) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    EXPECT_EQ(followup_task->transferStatus().s, COMPLETED);
+    EXPECT_EQ(followup_task->transferStatus().transferred_bytes, source.size());
+    EXPECT_EQ(recovered, source);
+
+    EXPECT_TRUE(workers.stop().ok());
+    EXPECT_TRUE(endpoints.clear().ok());
+    EXPECT_TRUE(buffers.clear().ok());
+    EXPECT_TRUE(context->shutdown().ok());
+    EXPECT_TRUE(adapter->shutdown().ok());
+}
+
 TEST(UbNativeDataPathTest, EndpointStoreNeverReusesRetiredGeneration) {
     auto adapter = std::make_shared<FakeUrmaAdapter>(fakeDevice());
     ASSERT_TRUE(adapter->initialize().ok());
@@ -607,6 +774,38 @@ TEST(UbNativeDataPathTest, EndpointStoreNeverReusesRetiredGeneration) {
     EXPECT_TRUE(adapter->shutdown().ok());
 }
 
+TEST(UbNativeDataPathTest,
+     EndpointStoreDoesNotReplaceEndpointWhenCleanupCannotComplete) {
+    auto adapter = std::make_shared<FakeUrmaAdapter>(fakeDevice());
+    ASSERT_TRUE(adapter->initialize().ok());
+    auto context = std::make_shared<UbContext>(0, fakeDevice(), adapter);
+    ASSERT_TRUE(context->initialize(1, JfcOptions{}).ok());
+    EndpointStore store(adapter, 1, 1);
+    UbEndpointKey key{0, 9, 0, "peer@ub:fake0:eid0"};
+    std::shared_ptr<UbEndpoint> endpoint;
+    ASSERT_TRUE(store.getOrCreate(key, context, endpoint).ok());
+    UbBootstrapDesc peer;
+    peer.local_eid = fakeDevice().eid;
+    peer.endpoint_generation = 100;
+    peer.jetty_ids = {777};
+    ASSERT_TRUE(endpoint->bind(peer).ok());
+
+    adapter->failResets();
+    std::vector<Completion> completions;
+    EXPECT_FALSE(endpoint->quiesce(20, completions).ok());
+
+    std::shared_ptr<UbEndpoint> replacement;
+    const auto status = store.getOrCreate(key, context, replacement);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(replacement, nullptr);
+    EXPECT_EQ(store.size(), 0U);
+
+    adapter->allowResets();
+    EXPECT_TRUE(store.clear().ok());
+    EXPECT_TRUE(context->shutdown().ok());
+    EXPECT_TRUE(adapter->shutdown().ok());
+}
+
 TEST(UbNativeDataPathTest, UbTransportRunsSelfReadWriteOverNativeControlPlane) {
     auto adapter = std::make_shared<FakeUrmaAdapter>(fakeDevice());
     // A serialized discovery snapshot is informational. Current local
@@ -638,6 +837,7 @@ TEST(UbNativeDataPathTest, UbTransportRunsSelfReadWriteOverNativeControlPlane) {
     config->set("transports/ub/jetty_per_endpoint", 1);
     config->set("transports/ub/max_endpoints", 16);
     config->set("transports/ub/slice_size", 16);
+    config->set("transports/ub/max_slices_per_task", 8);
     config->set("transports/ub/max_retries", 1);
     config->set("transports/ub/slice_timeout_ms", 1000);
     config->set("transports/ub/endpoint_cooldown_ms", 100);
@@ -654,6 +854,8 @@ TEST(UbNativeDataPathTest, UbTransportRunsSelfReadWriteOverNativeControlPlane) {
 
     std::array<char, 64> source{};
     std::array<char, 64> target{};
+    std::array<char, 144> oversized_source{};
+    std::array<char, 144> oversized_target{};
     for (size_t i = 0; i < source.size(); ++i) {
         source[i] = static_cast<char>(100 - i);
     }
@@ -666,9 +868,20 @@ TEST(UbNativeDataPathTest, UbTransportRunsSelfReadWriteOverNativeControlPlane) {
     target_desc.addr = reinterpret_cast<uint64_t>(target.data());
     target_desc.length = target.size();
     target_desc.location = kWildcardLocation;
+    BufferDesc oversized_source_desc{};
+    oversized_source_desc.addr =
+        reinterpret_cast<uint64_t>(oversized_source.data());
+    oversized_source_desc.length = oversized_source.size();
+    oversized_source_desc.location = kWildcardLocation;
+    BufferDesc oversized_target_desc{};
+    oversized_target_desc.addr =
+        reinterpret_cast<uint64_t>(oversized_target.data());
+    oversized_target_desc.length = oversized_target.size();
+    oversized_target_desc.location = kWildcardLocation;
     MemoryOptions options;
     options.perm = kGlobalReadWrite;
-    std::vector<BufferDesc> descriptors{source_desc, target_desc};
+    std::vector<BufferDesc> descriptors{
+        source_desc, target_desc, oversized_source_desc, oversized_target_desc};
     ASSERT_TRUE(transport.addMemoryBuffer(descriptors, options).ok());
     ASSERT_TRUE(control->segmentManager()
                     .updateLocal([&](SegmentDesc& segment) {
@@ -678,6 +891,20 @@ TEST(UbNativeDataPathTest, UbTransportRunsSelfReadWriteOverNativeControlPlane) {
                     })
                     .ok());
 
+    Transport::SubBatchRef rejected_batch = nullptr;
+    ASSERT_TRUE(transport.allocateSubBatch(rejected_batch, 1).ok());
+    Request oversized_request{};
+    oversized_request.opcode = Request::WRITE;
+    oversized_request.source = oversized_source.data();
+    oversized_request.target_id = LOCAL_SEGMENT_ID;
+    oversized_request.target_offset =
+        reinterpret_cast<uint64_t>(oversized_target.data());
+    oversized_request.length = oversized_source.size();
+    EXPECT_TRUE(
+        transport.submitTransferTasks(rejected_batch, {oversized_request})
+            .IsInvalidArgument());
+    EXPECT_TRUE(transport.freeSubBatch(rejected_batch).ok());
+
     Transport::SubBatchRef batch = nullptr;
     ASSERT_TRUE(transport.allocateSubBatch(batch, 2).ok());
     Request request{};
diff --git a/mooncake-transfer-engine/tent/tests/ub_teardown_test.cpp b/mooncake-transfer-engine/tent/tests/ub_teardown_test.cpp
index e92d7257e1..07ae1033cd 100644
--- a/mooncake-transfer-engine/tent/tests/ub_teardown_test.cpp
+++ b/mooncake-transfer-engine/tent/tests/ub_teardown_test.cpp
@@ -4,6 +4,7 @@
 #include <gtest/gtest.h>
 
 #include <algorithm>
+#include <chrono>
 #include <cstdint>
 #include <memory>
 #include <string>
@@ -659,5 +660,55 @@ TEST(UbTeardown, EndpointStoreReapsQuarantineBeforeReplacementAtCapacity) {
     EXPECT_TRUE(context->shutdown().ok());
 }
 
+TEST(UbTeardown, EndpointStoreThrottlesQuarantineSweepsAtCapacity) {
+    auto adapter = std::make_shared<FailOnceAdapter>();
+    auto context = makeActiveContext(adapter, 0);
+    // Drive the sweep throttle from a controllable clock so the assertion does
+    // not depend on two adjacent calls landing inside a wall-clock window.
+    auto now = std::chrono::steady_clock::now();
+    EndpointStore store(adapter, 1, 1, {}, [&now] { return now; });
+    const UbEndpointKey old_key{0, 123, 8, "peer/ub:test:8"};
+    std::shared_ptr<UbEndpoint> old_endpoint;
+    ASSERT_TRUE(store.getOrCreate(old_key, context, old_endpoint).ok());
+
+    // Native cleanup keeps failing, so the retired endpoint stays quarantined
+    // and the cache stays at capacity.
+    adapter->delete_jetty_failures = 100;
+    EXPECT_TRUE(store.retire(old_endpoint));
+    EXPECT_EQ(store.size(), 0u);
+
+    std::shared_ptr<UbEndpoint> replacement;
+    EXPECT_FALSE(store
+                     .getOrCreate(UbEndpointKey{0, 123, 9, "peer/ub:test:9"},
+                                  context, replacement)
+                     .ok());
+    const int sweeps_after_first = adapter->delete_jetty_calls;
+    EXPECT_GT(sweeps_after_first, 0);
+
+    // A second attempt inside the sweep interval must not issue native retire
+    // calls again: that is what stops a still-failing device from serializing
+    // provider calls across every posting thread.
+    now += std::chrono::milliseconds(10);
+    EXPECT_FALSE(store
+                     .getOrCreate(UbEndpointKey{0, 123, 10, "peer/ub:test:10"},
+                                  context, replacement)
+                     .ok());
+    EXPECT_EQ(adapter->delete_jetty_calls, sweeps_after_first);
+
+    // Once the interval has elapsed a new attempt is allowed to sweep again.
+    now += std::chrono::milliseconds(300);
+    EXPECT_FALSE(store
+                     .getOrCreate(UbEndpointKey{0, 123, 11, "peer/ub:test:11"},
+                                  context, replacement)
+                     .ok());
+    EXPECT_GT(adapter->delete_jetty_calls, sweeps_after_first);
+
+    // clear() retries regardless of the throttle, so shutdown can still make
+    // progress once the provider recovers.
+    adapter->delete_jetty_failures = 0;
+    EXPECT_TRUE(store.clear().ok());
+    EXPECT_TRUE(context->shutdown().ok());
+}
+
 }  // namespace
 }  // namespace mooncake::tent::ub
diff --git a/mooncake-transfer-engine/tent/tests/xpu/xpu_engine_test.cpp b/mooncake-transfer-engine/tent/tests/xpu/xpu_engine_test.cpp
new file mode 100644
index 0000000000..15dc1b87e3
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/xpu/xpu_engine_test.cpp
@@ -0,0 +1,283 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Exercise registration -> routing -> ProxyManager -> real XPU copies, not
+// just the standalone transport. Two P2P engines need no external metadata
+// server. The same-host peer has a non-local segment ID, just like another
+// process; the test never shares the peer's device address with a local copy.
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <chrono>
+#include <memory>
+#include <string_view>
+#include <thread>
+#include <tuple>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/transfer_engine_impl.h"
+
+namespace mooncake {
+// Report one completed device copy as failed, so ProxyManager has to retry
+// orchestration. The underlying copy is synchronous and no I/O is abandoned.
+class FailOnceXpuTransport : public tent::Transport {
+   public:
+    explicit FailOnceXpuTransport(std::shared_ptr<tent::Transport> delegate)
+        : delegate_(std::move(delegate)) {
+        caps = delegate_->capabilities();
+    }
+    tent::Status allocateSubBatch(SubBatchRef& batch, size_t size) override {
+        return delegate_->allocateSubBatch(batch, size);
+    }
+    tent::Status freeSubBatch(SubBatchRef& batch) override {
+        return delegate_->freeSubBatch(batch);
+    }
+    tent::Status submitTransferTasks(
+        SubBatchRef batch,
+        const std::vector<tent::Request>& requests) override {
+        return delegate_->submitTransferTasks(batch, requests);
+    }
+    tent::Status getTransferStatus(SubBatchRef batch, int id,
+                                   tent::TransferStatus& status) override {
+        auto result = delegate_->getTransferStatus(batch, id, status);
+        if (result.ok() && status.s == tent::COMPLETED &&
+            !failed.exchange(true)) {
+            status.s = tent::FAILED;
+            status.transferred_bytes = 0;
+        }
+        return result;
+    }
+    tent::Status addMemoryBuffer(tent::BufferDesc& desc,
+                                 const tent::MemoryOptions& options) override {
+        return delegate_->addMemoryBuffer(desc, options);
+    }
+    tent::Status removeMemoryBuffer(tent::BufferDesc& desc) override {
+        return delegate_->removeMemoryBuffer(desc);
+    }
+    std::atomic<bool> failed{false};
+
+   private:
+    std::shared_ptr<tent::Transport> delegate_;
+};
+
+class TransferEngineImplTestPeer {
+   public:
+    // Same entry point submitTransfer uses: a stale remote-segment cache or a
+    // pooled RPC connection to a peer that has since exited is refreshed and
+    // retried once, instead of surfacing as a spurious UNSPEC.
+    static tent::SelectionResult route(tent::TransferEngineImpl& engine,
+                                       const tent::Request& request) {
+        return engine.resolveTransport(request, 0);
+    }
+    static bool hasXpuTag(tent::TransferEngineImpl& engine, void* address) {
+        auto desc = engine.metadata_->segmentManager().getLocal();
+        auto* buffer = desc->findBuffer(reinterpret_cast<uint64_t>(address), 1);
+        return buffer &&
+               std::find(buffer->transports.begin(), buffer->transports.end(),
+                         tent::XPU) != buffer->transports.end();
+    }
+    static std::shared_ptr<FailOnceXpuTransport> failNextCopy(
+        tent::TransferEngineImpl& engine) {
+        auto wrapped = std::make_shared<FailOnceXpuTransport>(
+            engine.transport_list_[tent::XPU]);
+        engine.swapTransportForTest(tent::XPU, wrapped);
+        return wrapped;
+    }
+};
+namespace tent {
+namespace {
+using Params = std::tuple<bool, bool, bool>;    // HP TCP, legacy, runtime queue
+constexpr size_t kLength = (4UL << 20) + 4096;  // crosses a staging chunk
+
+class XpuEngineTest : public ::testing::TestWithParam<Params> {
+   protected:
+    std::shared_ptr<Config> config() {
+        auto c = std::make_shared<Config>();
+        c->set("metadata_type", "p2p");
+        c->set("metadata_servers", "");
+        c->set("rpc_server_hostname", "127.0.0.1");
+        c->set("rpc_server_port", "0");
+        c->set("log_level", "warning");
+        c->set("transports/tcp/enable", !std::get<0>(GetParam()));
+        c->set("transports/hp_tcp/enable", std::get<0>(GetParam()));
+        c->set("transports/rdma/enable", false);
+        c->set("transports/shm/enable", false);
+        c->set("transports/io_uring/enable", false);
+        c->set("transports/mpcomm/enable", false);
+        c->set("transports/xpu/enable", true);
+        c->set("use_legacy_transport_selection", std::get<1>(GetParam()));
+        c->set("enable_runtime_queue", std::get<2>(GetParam()));
+        c->set("max_failover_attempts", 1);
+        return c;
+    }
+    void SetUp() override {
+        auto& platform = Platform::getLoader(config());
+        MemoryOptions opts;
+        opts.location = "xpu:0";
+        void* probe = nullptr;
+        if (!platform.allocate(&probe, 4096, opts).ok())
+            GTEST_SKIP() << "No SYCL device available";
+        ASSERT_TRUE(platform.free(probe, 4096).ok());
+        a_ = std::make_unique<TransferEngineImpl>(config());
+        b_ = std::make_unique<TransferEngineImpl>(config());
+        ASSERT_TRUE(a_->available());
+        ASSERT_TRUE(b_->available());
+    }
+    void TearDown() override {
+        for (auto [engine, batch] : batches_)
+            EXPECT_TRUE(engine->freeBatch(batch).ok());
+        // Engine teardown drains staging before releasing tracked allocations.
+        a_.reset();
+        b_.reset();
+    }
+    void allocate(TransferEngineImpl& engine, const char* location, void** out,
+                  TransportType registration = UNSPEC) {
+        MemoryOptions opts;
+        opts.location = location;
+        ASSERT_TRUE(engine.allocateLocalMemory(out, kLength, opts).ok());
+        ASSERT_NE(*out, nullptr);
+        opts.type = registration;
+        ASSERT_TRUE(engine.registerLocalMemory({*out}, {kLength}, opts).ok());
+        EXPECT_TRUE(TransferEngineImplTestPeer::hasXpuTag(engine, *out));
+    }
+    TransferStatus wait(BatchID batch) {
+        TransferStatus status{};
+        auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(15);
+        do {
+            auto s = a_->progressBatch(batch, status);
+            EXPECT_TRUE(s.ok()) << s.ToString();
+            if (!s.ok() || status.s != PENDING) break;
+            std::this_thread::yield();
+        } while (std::chrono::steady_clock::now() < deadline);
+        return status;
+    }
+    void transfer(const char* local_location, const char* peer_location,
+                  Request::OpCode opcode, bool explicit_peer = false) {
+        void *local = nullptr, *peer = nullptr;
+        ASSERT_NO_FATAL_FAILURE(allocate(*a_, local_location, &local));
+        ASSERT_NO_FATAL_FAILURE(
+            allocate(*b_, peer_location, &peer, explicit_peer ? XPU : UNSPEC));
+        std::vector<uint8_t> seed(kLength), zero(kLength, 0), readback(kLength);
+        for (size_t i = 0; i < seed.size(); ++i) seed[i] = i % 251;
+        auto& platform = Platform::getLoader();
+        void* source = opcode == Request::WRITE ? local : peer;
+        void* dest = opcode == Request::WRITE ? peer : local;
+        ASSERT_TRUE(platform.copy(source, seed.data(), kLength).ok());
+        ASSERT_TRUE(platform.copy(dest, zero.data(), kLength).ok());
+        Request request{};
+        request.opcode = opcode;
+        request.source = local;
+        request.target_offset = reinterpret_cast<uint64_t>(peer);
+        request.length = kLength;
+        ASSERT_TRUE(
+            a_->openSegment(request.target_id, b_->getSegmentName()).ok());
+        ASSERT_NE(request.target_id, LOCAL_SEGMENT_ID);
+        const auto network = std::get<0>(GetParam()) ? HP_TCP : TCP;
+        auto route = TransferEngineImplTestPeer::route(*a_, request);
+        ASSERT_EQ(route.transport, network);
+        ASSERT_EQ(route.staging_params.size(), 3u);
+        // Only device sides are staged; the stage location must resolve.
+        EXPECT_EQ(route.staging_params[1].empty(),
+                  std::string_view(local_location) == "cpu:0");
+        EXPECT_EQ(route.staging_params[2].empty(),
+                  std::string_view(peer_location) == "cpu:0");
+        // Submit without a hint: the engine must reach staging on its own.
+        auto batch = a_->allocateBatch(1);
+        ASSERT_NE(batch, 0u);
+        batches_.push_back({a_.get(), batch});
+        ASSERT_TRUE(a_->submitTransfer(batch, {request}).ok());
+        auto status = wait(batch);
+        ASSERT_EQ(status.s, COMPLETED);
+        EXPECT_EQ(status.transferred_bytes, kLength);
+        ASSERT_TRUE(platform.copy(readback.data(), dest, kLength).ok());
+        EXPECT_EQ(readback, seed);
+    }
+    std::unique_ptr<TransferEngineImpl> a_, b_;
+    std::vector<std::pair<TransferEngineImpl*, BatchID>> batches_;
+};
+
+TEST_P(XpuEngineTest, DefaultRegistrationSelectsLocalXpuCopy) {
+    void *device = nullptr, *host = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocate(*a_, "xpu:0", &device));
+    ASSERT_NO_FATAL_FAILURE(allocate(*a_, "cpu:0", &host));
+    Request request{};
+    request.opcode = Request::WRITE;
+    request.source = device;
+    request.target_id = LOCAL_SEGMENT_ID;
+    request.target_offset = reinterpret_cast<uint64_t>(host);
+    request.length = kLength;
+    auto route = TransferEngineImplTestPeer::route(*a_, request);
+    EXPECT_EQ(route.transport, XPU);
+    EXPECT_TRUE(route.staging_params.empty());
+}
+
+TEST_P(XpuEngineTest, StagesDeviceToDeviceReadAndWrite) {
+    ASSERT_NO_FATAL_FAILURE(transfer("xpu:0", "xpu:0", Request::WRITE, true));
+    ASSERT_NO_FATAL_FAILURE(transfer("xpu:0", "xpu:0", Request::READ, true));
+}
+
+TEST_P(XpuEngineTest, StagesOneDeviceSideReadAndWrite) {
+    ASSERT_NO_FATAL_FAILURE(transfer("cpu:0", "xpu:0", Request::WRITE, true));
+    ASSERT_NO_FATAL_FAILURE(transfer("cpu:0", "xpu:0", Request::READ, true));
+    ASSERT_NO_FATAL_FAILURE(transfer("xpu:0", "cpu:0", Request::WRITE));
+    ASSERT_NO_FATAL_FAILURE(transfer("xpu:0", "cpu:0", Request::READ));
+}
+
+TEST_P(XpuEngineTest, RetryKeepsHostTransportBehindStaging) {
+    if (!std::get<0>(GetParam()))
+        GTEST_SKIP() << "TCP can recover inside the device stage";
+    auto injected = TransferEngineImplTestPeer::failNextCopy(*a_);
+    ASSERT_NO_FATAL_FAILURE(transfer("xpu:0", "xpu:0", Request::WRITE, true));
+    EXPECT_TRUE(injected->failed.load());
+}
+
+TEST_P(XpuEngineTest, RejectsXpuHintForPeerSegment) {
+    void *host = nullptr, *device = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocate(*a_, "cpu:0", &host));
+    ASSERT_NO_FATAL_FAILURE(allocate(*b_, "xpu:0", &device));
+    Request request{};
+    request.source = host;
+    request.target_offset = reinterpret_cast<uint64_t>(device);
+    request.length = kLength;
+    request.transport_hint = XPU;
+    ASSERT_TRUE(a_->openSegment(request.target_id, b_->getSegmentName()).ok());
+    auto route = TransferEngineImplTestPeer::route(*a_, request);
+    EXPECT_EQ(route.transport, UNSPEC);
+    EXPECT_TRUE(route.staging_params.empty());
+}
+
+// An unstaged host source is used as-is by the cross stage, so it must carry
+// the host transport itself; XPU-only registration cannot be routed.
+TEST_P(XpuEngineTest, UnstagedHostSourceMustCarryHostTransport) {
+    void *host = nullptr, *device = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocate(*a_, "cpu:0", &host, XPU));
+    ASSERT_NO_FATAL_FAILURE(allocate(*b_, "xpu:0", &device));
+    Request request{};
+    request.source = host;
+    request.target_offset = reinterpret_cast<uint64_t>(device);
+    request.length = kLength;
+    ASSERT_TRUE(a_->openSegment(request.target_id, b_->getSegmentName()).ok());
+    auto route = TransferEngineImplTestPeer::route(*a_, request);
+    EXPECT_EQ(route.transport, UNSPEC);
+}
+
+INSTANTIATE_TEST_SUITE_P(NetworkAndDispatchModes, XpuEngineTest,
+                         ::testing::Combine(::testing::Bool(),
+                                            ::testing::Bool(),
+                                            ::testing::Bool()));
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/xpu/xpu_platform_test.cpp b/mooncake-transfer-engine/tent/tests/xpu/xpu_platform_test.cpp
new file mode 100644
index 0000000000..c069229a93
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/xpu/xpu_platform_test.cpp
@@ -0,0 +1,229 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Acceptance test for the Intel XPU platform. Drives XpuPlatform against the
+// real oneAPI SYCL backend (USE_XPU is a direct-link build: libsycl is linked
+// in, there is no mock adapter). The backend falls back to the OpenCL CPU
+// runtime when no Intel GPU is present, so this test runs on any host with a
+// SYCL runtime; when no SYCL device is visible at all it skips rather than
+// fails.
+
+#include <gtest/gtest.h>
+#include <sycl/sycl.hpp>
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/platform/xpu.h"
+#include "tent/runtime/platform.h"
+#include "tent/runtime/topology.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+class XpuPlatformTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        auto conf = std::make_shared<Config>();
+        platform_ = std::make_shared<XpuPlatform>(conf);
+
+        // Count visible XPU devices via probe(); skip the whole suite when the
+        // host has no SYCL device (e.g. no oneAPI runtime installed).
+        std::vector<Topology::NicEntry> nics;
+        std::vector<Topology::MemEntry> mems;
+        ASSERT_TRUE(platform_->probe(nics, mems).ok());
+        for (const auto &m : mems) {
+            if (m.name.rfind("xpu:", 0) == 0) device_count_++;
+        }
+        if (device_count_ == 0) {
+            GTEST_SKIP() << "no SYCL device available; skipping XPU test";
+        }
+    }
+
+    std::shared_ptr<XpuPlatform> platform_;
+    int device_count_ = 0;
+};
+
+TEST_F(XpuPlatformTest, TypeString) { EXPECT_EQ(platform_->type(), "xpu"); }
+
+TEST_F(XpuPlatformTest, ProbeRegistersOneMemEntryPerDevice) {
+    std::vector<Topology::NicEntry> nics;
+    std::vector<Topology::MemEntry> mems;
+    Status s = platform_->probe(nics, mems);
+    EXPECT_TRUE(s.ok()) << s;
+
+    int xpu_entries = 0;
+    for (const auto &m : mems) {
+        if (m.name.rfind("xpu:", 0) == 0) xpu_entries++;
+    }
+    EXPECT_EQ(xpu_entries, device_count_)
+        << "probe() should register one node per device";
+}
+
+// Acceptance: device allocate -> host->device copy -> device->host copy ->
+// byte-equality -> free, all driven through XpuPlatform.
+TEST_F(XpuPlatformTest, DeviceAllocCopyFreeRoundTrip) {
+    const size_t kSize = 4096;
+    MemoryOptions options;
+    options.location = "xpu:0";
+
+    void *dev = nullptr;
+    Status alloc = platform_->allocate(&dev, kSize, options);
+    ASSERT_TRUE(alloc.ok()) << alloc;
+    ASSERT_NE(dev, nullptr);
+
+    // classify() == MTYPE_XPU for device USM.
+    EXPECT_EQ(platform_->getMemoryType(dev), MTYPE_XPU);
+
+    // getLocation resolves the owning device ordinal.
+    auto locs = platform_->getLocation(dev, kSize);
+    ASSERT_EQ(locs.size(), 1u);
+    EXPECT_EQ(locs[0].location, "xpu:0");
+
+    // host -> device -> host round trip.
+    std::vector<uint8_t> src(kSize);
+    for (size_t i = 0; i < kSize; ++i) src[i] = static_cast<uint8_t>(i * 7 + 1);
+    std::vector<uint8_t> dst(kSize, 0);
+
+    Status h2d = platform_->copy(dev, src.data(), kSize);
+    ASSERT_TRUE(h2d.ok()) << h2d;
+    Status d2h = platform_->copy(dst.data(), dev, kSize);
+    ASSERT_TRUE(d2h.ok()) << d2h;
+
+    EXPECT_EQ(std::memcmp(src.data(), dst.data(), kSize), 0);
+
+    Status freed = platform_->free(dev, kSize);
+    EXPECT_TRUE(freed.ok()) << freed;
+    // Whether the freed address still classifies as device memory is up to the
+    // SYCL runtime (Level Zero keeps freed USM cached and get_pointer_type
+    // still reports it as device), so that is deliberately not asserted.
+}
+
+TEST_F(XpuPlatformTest, HostPointerClassifiesAsCpu) {
+    int host_value = 0;
+    EXPECT_EQ(platform_->getMemoryType(&host_value), MTYPE_CPU);
+}
+
+// USM device memory the platform did not allocate itself -- the way a PyTorch
+// XPU tensor reaches registerLocalMemory -- must still classify as XPU memory
+// and be copyable, including at an interior offset. PyTorch allocates from the
+// platform default context, so mirror that here.
+TEST_F(XpuPlatformTest, ForeignUsmClassifiesAsXpuAndCopies) {
+    sycl::device gpu;
+    bool found = false;
+    for (const auto &d : sycl::device::get_devices()) {
+        if (d.is_gpu() && d.has(sycl::aspect::usm_device_allocations)) {
+            gpu = d;
+            found = true;
+            break;
+        }
+    }
+    if (!found) GTEST_SKIP() << "no SYCL GPU device available";
+
+    sycl::context ctx = gpu.get_platform().ext_oneapi_get_default_context();
+    sycl::queue q(ctx, gpu);
+    const size_t kSize = 8192;
+    auto *dev = static_cast<uint8_t *>(sycl::malloc_device(kSize, gpu, ctx));
+    ASSERT_NE(dev, nullptr);
+
+    EXPECT_EQ(platform_->getMemoryType(dev), MTYPE_XPU);
+    EXPECT_EQ(platform_->getMemoryType(dev + 4096), MTYPE_XPU);
+    auto locs = platform_->getLocation(dev, kSize);
+    ASSERT_EQ(locs.size(), 1u);
+    EXPECT_EQ(locs[0].location.rfind("xpu:", 0), 0u) << locs[0].location;
+
+    std::vector<uint8_t> src(4096), dst(4096, 0);
+    for (size_t i = 0; i < src.size(); ++i)
+        src[i] = static_cast<uint8_t>(i * 11 + 3);
+    Status h2d = platform_->copy(dev + 4096, src.data(), src.size());
+    ASSERT_TRUE(h2d.ok()) << h2d;
+    Status d2h = platform_->copy(dst.data(), dev + 4096, dst.size());
+    ASSERT_TRUE(d2h.ok()) << d2h;
+    EXPECT_EQ(src, dst);
+
+    // Cross-check against the owner's own queue: the platform really wrote
+    // into this allocation, not a stage.
+    std::vector<uint8_t> direct(4096, 0);
+    q.memcpy(direct.data(), dev + 4096, direct.size()).wait();
+    EXPECT_EQ(src, direct);
+
+    // Host and shared USM are host-accessible and stay classified as CPU.
+    void *host_usm = sycl::malloc_host(4096, ctx);
+    ASSERT_NE(host_usm, nullptr);
+    EXPECT_EQ(platform_->getMemoryType(host_usm), MTYPE_CPU);
+    sycl::free(host_usm, ctx);
+
+    sycl::free(dev, ctx);
+}
+
+// Interior addresses (chunked staging hands the backend base + offset) must
+// classify as device memory, or transfers larger than one chunk corrupt.
+TEST_F(XpuPlatformTest, InteriorPointerClassifiesAsXpu) {
+    const size_t kSize = 8192;
+    MemoryOptions options;
+    options.location = "xpu:0";
+
+    void *dev = nullptr;
+    ASSERT_TRUE(platform_->allocate(&dev, kSize, options).ok());
+    auto *bytes = static_cast<uint8_t *>(dev);
+
+    EXPECT_EQ(platform_->getMemoryType(bytes + 4096), MTYPE_XPU);
+    auto locs = platform_->getLocation(bytes + 4096, kSize - 4096);
+    ASSERT_EQ(locs.size(), 1u);
+    EXPECT_EQ(locs[0].location, "xpu:0");
+
+    // Interior-offset staging copy must round-trip correctly.
+    std::vector<uint8_t> src(4096), dst(4096, 0);
+    for (size_t i = 0; i < src.size(); ++i)
+        src[i] = static_cast<uint8_t>(i * 13 + 5);
+    ASSERT_TRUE(platform_->copy(bytes + 4096, src.data(), 4096).ok());
+    ASSERT_TRUE(platform_->copy(dst.data(), bytes + 4096, 4096).ok());
+    EXPECT_EQ(std::memcmp(src.data(), dst.data(), 4096), 0);
+
+    EXPECT_TRUE(platform_->free(dev, kSize).ok());
+}
+
+// A bare "xpu" location (no ordinal) must allocate on device 0, not fall
+// through to the host allocator.
+TEST_F(XpuPlatformTest, BareXpuLocationAllocatesDeviceZero) {
+    MemoryOptions options;
+    options.location = "xpu";
+
+    void *dev = nullptr;
+    Status alloc = platform_->allocate(&dev, 4096, options);
+    ASSERT_TRUE(alloc.ok()) << alloc;
+    ASSERT_NE(dev, nullptr);
+    EXPECT_EQ(platform_->getMemoryType(dev), MTYPE_XPU);
+    EXPECT_TRUE(platform_->free(dev, 4096).ok());
+}
+
+// A malformed ordinal ("xpu:<garbage>") must be rejected rather than silently
+// allocating on device 0.
+TEST_F(XpuPlatformTest, MalformedXpuOrdinalIsRejected) {
+    MemoryOptions options;
+    options.location = "xpu:notanumber";
+
+    void *dev = nullptr;
+    Status alloc = platform_->allocate(&dev, 4096, options);
+    EXPECT_FALSE(alloc.ok());
+    EXPECT_EQ(dev, nullptr);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tent/tests/xpu/xpu_transport_test.cpp b/mooncake-transfer-engine/tent/tests/xpu/xpu_transport_test.cpp
new file mode 100644
index 0000000000..555ad74901
--- /dev/null
+++ b/mooncake-transfer-engine/tent/tests/xpu/xpu_transport_test.cpp
@@ -0,0 +1,212 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Drives XpuTransport's staging hop against the real oneAPI SYCL backend.
+// USE_XPU is a direct-link build, so there is no mock adapter: the transport
+// classifies and copies XPU memory through the active XpuPlatform
+// (Platform::getLoader()). The backend falls back to the OpenCL CPU runtime
+// when no Intel GPU is present, and the suite skips when no SYCL device is
+// visible at all.
+//
+// The cases mirror the requests ProxyManager actually issues: a local stage
+// whose `source` is a device pointer at an interior offset and whose
+// `target_offset` is the host staging buffer, and the delegated remote stage
+// where the device side is `target_offset` instead. The interior offsets are
+// the real detectors of the "device pointer misclassified as host memory"
+// failure mode, since the backend must resolve base + offset against its
+// allocation registry.
+
+#include "tent/transport/xpu/xpu_transport.h"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <vector>
+
+#include "tent/common/config.h"
+#include "tent/runtime/platform.h"
+
+namespace mooncake {
+namespace tent {
+namespace {
+
+constexpr size_t kChunk = 64ul << 10;  // 64 KiB
+constexpr size_t kBufSize = 3 * kChunk;
+
+class XpuTransportTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        // Force the singleton platform loader to exist; in a USE_XPU build this
+        // is an XpuPlatform. Probe for a visible device and skip otherwise.
+        auto conf = std::make_shared<Config>();
+        loader_ = &Platform::getLoader(conf);
+        MemoryOptions options;
+        options.location = "xpu:0";
+        void *probe = nullptr;
+        if (!loader_->allocate(&probe, kChunk, options).ok() || !probe) {
+            GTEST_SKIP() << "no SYCL device available; skipping XPU transport "
+                            "test";
+        }
+        loader_->free(probe, kChunk);
+
+        std::string segment = "local";
+        ASSERT_TRUE(
+            transport_.install(segment, nullptr, nullptr, nullptr).ok());
+    }
+
+    void TearDown() override { transport_.uninstall(); }
+
+    // Aborts the test immediately if device allocation fails, so callers never
+    // operate on a null pointer. ASSERT lives here (void return) and callers
+    // wrap the call in ASSERT_NO_FATAL_FAILURE to propagate the abort.
+    void allocDevice(uint8_t **out, size_t size) {
+        MemoryOptions options;
+        options.location = "xpu:0";
+        *out = nullptr;
+        void *p = nullptr;
+        ASSERT_TRUE(loader_->allocate(&p, size, options).ok());
+        ASSERT_NE(p, nullptr);
+        *out = static_cast<uint8_t *>(p);
+    }
+
+    // Runs one request through the transport and returns its final status.
+    TransferStatus run(const Request &request) {
+        Transport::SubBatchRef batch = nullptr;
+        EXPECT_TRUE(transport_.allocateSubBatch(batch, 1).ok());
+        EXPECT_TRUE(transport_.submitTransferTasks(batch, {request}).ok());
+        TransferStatus status{};
+        EXPECT_TRUE(transport_.getTransferStatus(batch, 0, status).ok());
+        EXPECT_TRUE(transport_.freeSubBatch(batch).ok());
+        return status;
+    }
+
+    static Request makeRequest(Request::OpCode op, void *source,
+                               uint64_t target, size_t length) {
+        Request r;
+        r.opcode = op;
+        r.source = source;
+        r.length = length;
+        r.target_id = LOCAL_SEGMENT_ID;
+        r.target_offset = target;
+        return r;
+    }
+
+    Platform *loader_ = nullptr;
+    XpuTransport transport_;
+};
+
+// The local WRITE stage of chunk #1: source is an interior device address.
+TEST_F(XpuTransportTest, LocalStageCopiesFromInteriorDeviceOffset) {
+    uint8_t *dev = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&dev, kBufSize));
+    std::vector<uint8_t> seed(kBufSize);
+    for (size_t i = 0; i < kBufSize; ++i) seed[i] = (uint8_t)(i % 251);
+    ASSERT_TRUE(loader_->copy(dev, seed.data(), kBufSize).ok());
+    std::vector<uint8_t> staging(kChunk, 0);
+
+    // Chunk #1: device + 64 KiB -> host staging buffer (D2H).
+    auto status = run(makeRequest(Request::WRITE, dev + kChunk,
+                                  (uint64_t)staging.data(), kChunk));
+    ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, kChunk);
+    EXPECT_EQ(0, std::memcmp(staging.data(), seed.data() + kChunk, kChunk));
+
+    loader_->free(dev, kBufSize);
+}
+
+// The mirrored remote stage: the device side is `target_offset`, at an offset.
+TEST_F(XpuTransportTest, RemoteStageCopiesToInteriorDeviceOffset) {
+    uint8_t *dev = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&dev, kBufSize));
+    std::vector<uint8_t> zero(kBufSize, 0);
+    ASSERT_TRUE(loader_->copy(dev, zero.data(), kBufSize).ok());
+    std::vector<uint8_t> staging(kChunk);
+    for (size_t i = 0; i < kChunk; ++i) staging[i] = (uint8_t)(i % 197);
+
+    // WRITE with a device target: host staging -> device + 64 KiB (H2D).
+    auto status = run(makeRequest(Request::WRITE, staging.data(),
+                                  (uint64_t)(dev + kChunk), kChunk));
+    ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+
+    std::vector<uint8_t> readback(kChunk, 0);
+    ASSERT_TRUE(loader_->copy(readback.data(), dev + kChunk, kChunk).ok());
+    EXPECT_EQ(0, std::memcmp(readback.data(), staging.data(), kChunk));
+
+    loader_->free(dev, kBufSize);
+}
+
+// A READ stage moves host staging -> device (H2D).
+TEST_F(XpuTransportTest, ReadStageCopiesHostToDevice) {
+    uint8_t *dev = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&dev, kBufSize));
+    std::vector<uint8_t> staging(kChunk, 0xAB);
+
+    auto status = run(makeRequest(Request::READ, dev + 2 * kChunk,
+                                  (uint64_t)staging.data(), kChunk));
+    ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+
+    std::vector<uint8_t> readback(kChunk, 0);
+    ASSERT_TRUE(loader_->copy(readback.data(), dev + 2 * kChunk, kChunk).ok());
+    EXPECT_EQ(0, std::memcmp(readback.data(), staging.data(), kChunk));
+
+    loader_->free(dev, kBufSize);
+}
+
+// Neither side is device memory: a routing bug or an unclassified pointer. The
+// transport must fail rather than let Platform::copy memcpy between two host
+// buffers as if it were a staging hop.
+TEST_F(XpuTransportTest, FailsWhenNeitherSideIsDeviceMemory) {
+    std::vector<uint8_t> host_a(4096, 1), host_b(4096, 2);
+    auto status = run(makeRequest(Request::WRITE, host_a.data(),
+                                  (uint64_t)host_b.data(), host_a.size()));
+    EXPECT_EQ(status.s, TransferStatusEnum::FAILED);
+    EXPECT_EQ(status.transferred_bytes, 0u);
+    // The destination is untouched -- no silent partial copy.
+    EXPECT_EQ(host_b[0], 2);
+}
+
+// Both sides device: VRAM<->VRAM is not a staging hop and must be rejected.
+TEST_F(XpuTransportTest, FailsWhenBothSidesAreDeviceMemory) {
+    uint8_t *a = nullptr;
+    uint8_t *b = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&a, kChunk));
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&b, kChunk));
+
+    auto status = run(makeRequest(Request::WRITE, a, (uint64_t)b, kChunk));
+    EXPECT_EQ(status.s, TransferStatusEnum::FAILED);
+
+    loader_->free(a, kChunk);
+    loader_->free(b, kChunk);
+}
+
+// XPU VRAM can never be a remote peer; a non-local target is a routing bug.
+TEST_F(XpuTransportTest, FailsOnNonLocalTarget) {
+    uint8_t *dev = nullptr;
+    ASSERT_NO_FATAL_FAILURE(allocDevice(&dev, kChunk));
+    std::vector<uint8_t> staging(kChunk, 0);
+
+    auto request =
+        makeRequest(Request::WRITE, dev, (uint64_t)staging.data(), kChunk);
+    request.target_id = LOCAL_SEGMENT_ID + 1;
+    auto status = run(request);
+    EXPECT_EQ(status.s, TransferStatusEnum::FAILED);
+
+    loader_->free(dev, kChunk);
+}
+
+}  // namespace
+}  // namespace tent
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/CMakeLists.txt b/mooncake-transfer-engine/tests/CMakeLists.txt
index aa00a168e1..f13d3becf6 100644
--- a/mooncake-transfer-engine/tests/CMakeLists.txt
+++ b/mooncake-transfer-engine/tests/CMakeLists.txt
@@ -17,19 +17,59 @@ target_link_libraries(rdma_transport_test PUBLIC transfer_engine gflags::gflags
 add_executable(transport_uint_test ${WORKSPACE}/transport_uint_test.cpp)
 target_link_libraries(transport_uint_test PUBLIC transfer_engine gtest
                                                  gtest_main)
+if(USE_TENT)
+  # Match the compatibility shim public class definition and enable the
+  # MC_USE_TENT regression cases in transport_uint_test.cpp.
+  target_compile_definitions(transport_uint_test PRIVATE USE_TENT)
+endif()
 add_test(NAME transport_uint_test COMMAND transport_uint_test)
 
+# Hardware-free tests for FlagCX transport range and descriptor validation.
+add_executable(flagcx_transport_internal_test
+               ${WORKSPACE}/flagcx_transport_internal_test.cpp)
+target_include_directories(
+  flagcx_transport_internal_test
+  PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../src/transport/flagcx_transport)
+target_link_libraries(flagcx_transport_internal_test PUBLIC gtest gtest_main)
+add_test(NAME flagcx_transport_internal_test
+         COMMAND flagcx_transport_internal_test)
+
 add_executable(endpoint_store_test ${WORKSPACE}/endpoint_store_test.cpp)
 target_link_libraries(endpoint_store_test PUBLIC transfer_engine gtest
                                                  gtest_main)
 add_test(NAME endpoint_store_test COMMAND endpoint_store_test)
 
+# Fingerprint, blob and option checks run without a VMM backend.
+add_executable(shared_segment_test ${WORKSPACE}/shared_segment_test.cpp)
+target_include_directories(
+  shared_segment_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../src/shared_segment)
+target_link_libraries(shared_segment_test PUBLIC transfer_engine gtest
+                                                 gtest_main)
+add_test(NAME shared_segment_test COMMAND shared_segment_test)
+
 add_executable(rdma_endpoint_state_test
                ${WORKSPACE}/rdma_endpoint_state_test.cpp)
 target_link_libraries(rdma_endpoint_state_test PUBLIC transfer_engine gtest
                                                       gtest_main)
 add_test(NAME rdma_endpoint_state_test COMMAND rdma_endpoint_state_test)
 
+# Hardware-free regression tests for peer-rail pausing and the local-WC context
+# breaker. Both are plain per-worker-pool state, so this runs on every CI runner
+# without an RDMA device.
+add_executable(worker_pool_rail_state_test
+               ${WORKSPACE}/worker_pool_rail_state_test.cpp)
+target_link_libraries(worker_pool_rail_state_test PUBLIC transfer_engine gtest
+                                                         gtest_main)
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+  # Control GID I/O to exercise recovery while completion failures arrive.
+  target_link_options(
+    worker_pool_rail_state_test
+    PRIVATE
+    "-Wl,--wrap=_ZN8mooncake11RdmaContext17refreshCurrentGidEPNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEES7_"
+  )
+endif()
+add_test(NAME worker_pool_rail_state_test COMMAND worker_pool_rail_state_test)
+
 # Integration test for the monitorWorker reclaim tick (issue #1845). Self-skips
 # when no RDMA device is present, so safe to register with ctest.
 add_executable(endpoint_store_integration_test
@@ -53,8 +93,35 @@ target_link_libraries(rdma_loopback_test PUBLIC transfer_engine gtest
 # Regression test for #2017 (registerLocalMemory must auto-chunk buffers larger
 # than the device max_mr_size; loopback WRITE past the boundary must succeed).
 add_executable(rdma_large_mr_test ${WORKSPACE}/rdma_large_mr_test.cpp)
-target_link_libraries(rdma_large_mr_test PUBLIC transfer_engine gtest gtest_main )
-# add_test(NAME rdma_large_mr_test COMMAND rdma_large_mr_test)  # needs an RDMA dev + metadata server
+target_link_libraries(rdma_large_mr_test PUBLIC transfer_engine gtest
+                                                gtest_main)
+# add_test(NAME rdma_large_mr_test COMMAND rdma_large_mr_test)  # needs an RDMA
+# dev + metadata server
+
+# Ctrl frame codec + sender credit ledger unit tests (no RDMA device required).
+add_executable(ctrl_frame_test ${WORKSPACE}/ctrl_frame_test.cpp)
+target_link_libraries(ctrl_frame_test PUBLIC transfer_engine gtest gtest_main)
+add_test(NAME ctrl_frame_test COMMAND ctrl_frame_test)
+
+add_executable(sender_credit_test ${WORKSPACE}/sender_credit_test.cpp)
+target_link_libraries(sender_credit_test PUBLIC transfer_engine gtest
+                                                gtest_main)
+add_test(NAME sender_credit_test COMMAND sender_credit_test)
+
+# Ordinary RDMA notifications; independent of the CtrlChannel tests below.
+add_executable(rdma_native_notify_test ${WORKSPACE}/rdma_native_notify_test.cpp)
+target_link_libraries(rdma_native_notify_test PUBLIC transfer_engine gtest
+                                                     gtest_main)
+add_test(NAME rdma_native_notify_test COMMAND rdma_native_notify_test)
+set_tests_properties(rdma_native_notify_test PROPERTIES LABELS "rdma" TIMEOUT
+                                                        120)
+
+# CtrlChannel RDMA notify correctness. Self-skips without RDMA.
+add_executable(rdma_notify_test ${WORKSPACE}/rdma_notify_test.cpp)
+target_link_libraries(rdma_notify_test PUBLIC transfer_engine gflags::gflags
+                                              glog::glog gtest)
+add_test(NAME rdma_notify_test COMMAND rdma_notify_test)
+set_tests_properties(rdma_notify_test PROPERTIES LABELS "rdma")
 
 # This test verifies endpoint re-establishment in RDMATransport.
 add_executable(rdma_endpoint_reestablish_test
@@ -93,6 +160,18 @@ if(USE_CXL)
   add_test(NAME cxl_transport_test COMMAND cxl_transport_test)
 endif()
 
+add_executable(shm_transport_test ${WORKSPACE}/shm_transport_test.cpp)
+target_link_libraries(shm_transport_test PUBLIC transfer_engine gtest
+                                                gtest_main)
+add_test(NAME shm_transport_test COMMAND shm_transport_test)
+
+if(USE_TCP)
+  add_executable(shm_transport_e2e_test ${WORKSPACE}/shm_transport_e2e_test.cpp)
+  target_link_libraries(shm_transport_e2e_test PUBLIC transfer_engine gtest
+                                                      gtest_main)
+  add_test(NAME shm_transport_e2e_test COMMAND shm_transport_e2e_test)
+endif()
+
 if(USE_NVMEOF)
   add_executable(nvmeof_status_test ${WORKSPACE}/nvmeof_status_test.cpp)
   target_link_libraries(nvmeof_status_test PUBLIC transfer_engine gtest
@@ -113,9 +192,22 @@ if(USE_TCP)
 
   add_executable(tcp_write_visibility_test
                  ${WORKSPACE}/tcp_write_visibility_test.cpp)
+  target_compile_definitions(tcp_write_visibility_test
+                             PRIVATE MOONCAKE_TCP_TRANSPORT_TEST_HOOKS)
   target_link_libraries(tcp_write_visibility_test PUBLIC transfer_engine gtest
                                                          gtest_main)
   add_test(NAME tcp_write_visibility_test COMMAND tcp_write_visibility_test)
+
+  if(USE_CUDA)
+    add_executable(tcp_cuda_staging_test ${WORKSPACE}/tcp_cuda_staging_test.cpp)
+    target_compile_definitions(tcp_cuda_staging_test
+                               PRIVATE MOONCAKE_TCP_TRANSPORT_TEST_HOOKS)
+    target_include_directories(tcp_cuda_staging_test
+                               PRIVATE ${CUDAToolkit_INCLUDE_DIRS})
+    target_link_libraries(tcp_cuda_staging_test PUBLIC transfer_engine gtest
+                                                       gtest_main CUDA::cudart)
+    add_test(NAME tcp_cuda_staging_test COMMAND tcp_cuda_staging_test)
+  endif()
 endif()
 
 add_executable(tcp_address_validation_test
@@ -133,17 +225,41 @@ target_link_libraries(connect_pause_tracker_test PUBLIC gtest gtest_main
 add_test(NAME connect_pause_tracker_test COMMAND connect_pause_tracker_test)
 
 # Hardware-free unit tests for DmabufExport struct and
-# RdmaContext::{exportDmabuf, closeDmabufExport}. Runs on every CI runner —
-# no RDMA device or GPU required (host-memory paths only).
+# RdmaContext::{exportDmabuf, closeDmabufExport}. Runs on every CI runner — no
+# RDMA device or GPU required (host-memory paths only).
 add_executable(dmabuf_export_test ${WORKSPACE}/dmabuf_export_test.cpp)
-target_link_libraries(dmabuf_export_test PUBLIC transfer_engine gtest gtest_main)
+target_link_libraries(dmabuf_export_test PUBLIC transfer_engine gtest
+                                                gtest_main)
 add_test(NAME dmabuf_export_test COMMAND dmabuf_export_test)
 
 if(USE_MNNVL)
   add_executable(nvlink_transport_test ${WORKSPACE}/nvlink_transport_test.cpp)
   target_link_libraries(nvlink_transport_test PUBLIC transfer_engine gtest
                                                      gtest_main)
-  add_test(NAME nvlink_transport_test COMMAND nvlink_transport_test)
+  add_test(NAME nvlink_transport_test
+           COMMAND ${CMAKE_COMMAND} -E env GTEST_FILTER=NvlinkTransportTest.*
+                   $<TARGET_FILE:nvlink_transport_test>)
+  set_tests_properties(nvlink_transport_test PROPERTIES LABELS "nvlink_gpu")
+
+  if(USE_CUDA AND NOT USE_HIP)
+    add_test(
+      NAME nvlink_host_numa_registration_test
+      COMMAND
+        ${CMAKE_COMMAND} -E env --unset=MC_USE_NVLINK_IPC
+        GTEST_FILTER=NvlinkHostNumaRegistrationTest.*
+        $<TARGET_FILE:nvlink_transport_test>)
+    set_tests_properties(nvlink_host_numa_registration_test
+                         PROPERTIES LABELS "nvlink_vmm_unit")
+
+    add_executable(nvlink_host_numa_allocation_test
+                   ${WORKSPACE}/nvlink_host_numa_allocation_test.cpp)
+    target_link_libraries(nvlink_host_numa_allocation_test
+                          PUBLIC transfer_engine gtest gtest_main)
+    add_test(NAME nvlink_host_numa_allocation_test
+             COMMAND nvlink_host_numa_allocation_test)
+    set_tests_properties(nvlink_host_numa_allocation_test
+                         PROPERTIES LABELS "nvlink_vmm_unit")
+  endif()
 endif()
 
 if(USE_HIP)
@@ -175,6 +291,12 @@ if(USE_EFA)
   target_link_libraries(efa_single_nic_large_mr_test
                         PUBLIC transfer_engine gflags::gflags glog::glog)
 
+  add_executable(efa_large_mr_test ${WORKSPACE}/efa_large_mr_test.cpp)
+  target_link_libraries(efa_large_mr_test PUBLIC transfer_engine gtest
+                                                 gtest_main)
+  # No add_test(): needs EFA hardware plus MC_MAX_MR_SIZE=67108864 in the
+  # environment, same as rdma_large_mr_test.
+
   add_executable(efa_transfer_test ${WORKSPACE}/efa_transfer_test.cpp)
   target_link_libraries(efa_transfer_test PUBLIC transfer_engine gflags::gflags
                                                  glog::glog)
@@ -297,6 +419,12 @@ add_executable(config_test ${WORKSPACE}/config_test.cpp)
 target_link_libraries(config_test PUBLIC transfer_engine gtest gtest_main)
 add_test(NAME config_test COMMAND config_test)
 
+add_executable(glog_preinitialized_test
+               ${WORKSPACE}/glog_preinitialized_test.cpp)
+target_link_libraries(glog_preinitialized_test PUBLIC transfer_engine gtest
+                                                      gtest_main glog::glog)
+add_test(NAME glog_preinitialized_test COMMAND glog_preinitialized_test)
+
 add_executable(rdma_gid_probe_test ${WORKSPACE}/rdma_gid_probe_test.cpp)
 target_link_libraries(rdma_gid_probe_test PUBLIC transfer_engine gtest
                                                  gtest_main)
@@ -322,6 +450,23 @@ target_link_libraries(rdma_transport_submit_task_test PUBLIC transfer_engine
 add_test(NAME rdma_transport_submit_task_test
          COMMAND rdma_transport_submit_task_test)
 
+add_executable(rdma_buffer_range_index_test
+               ${WORKSPACE}/rdma_buffer_range_index_test.cpp)
+target_link_libraries(rdma_buffer_range_index_test PUBLIC transfer_engine gtest
+                                                          gtest_main)
+add_test(NAME rdma_buffer_range_index_test COMMAND rdma_buffer_range_index_test)
+
+add_executable(rdma_batch_reuse_test ${WORKSPACE}/rdma_batch_reuse_test.cpp)
+target_link_libraries(rdma_batch_reuse_test PUBLIC transfer_engine gtest
+                                                   gtest_main)
+add_test(NAME rdma_batch_reuse_test COMMAND rdma_batch_reuse_test)
+
+add_executable(multi_transport_batch_test
+               ${WORKSPACE}/multi_transport_batch_test.cpp)
+target_link_libraries(multi_transport_batch_test PUBLIC transfer_engine gtest
+                                                        gtest_main)
+add_test(NAME multi_transport_batch_test COMMAND multi_transport_batch_test)
+
 add_executable(topology_test ${WORKSPACE}/topology_test.cpp)
 target_link_libraries(topology_test PUBLIC transfer_engine gtest gtest_main)
 add_test(NAME topology_test COMMAND topology_test)
@@ -359,8 +504,7 @@ if(ENABLE_MULTI_PROTOCOL)
 endif()
 
 add_executable(graceful_shutdown_test ${WORKSPACE}/graceful_shutdown_test.cpp)
-target_link_libraries(graceful_shutdown_test PUBLIC transfer_engine gtest
-                                                    gtest_main)
+target_link_libraries(graceful_shutdown_test PUBLIC transfer_engine gtest)
 add_test(NAME graceful_shutdown_test COMMAND graceful_shutdown_test)
 
 add_executable(show_links_test ${WORKSPACE}/show_links_test.cpp)
@@ -368,15 +512,14 @@ target_link_libraries(show_links_test PUBLIC transfer_engine gtest gtest_main)
 add_test(NAME show_links_test COMMAND show_links_test)
 
 # The NCCL transport library target compiles only host-side setup, while the
-# CUDA example that includes the device helpers is opt-in. This probe instantiates
-# one consumer kernel against both header-only NCCL and IBGDA helpers so a
-# call-shape regression fails the build. Keep nvcc optional for host-only
-# DeviceTransport builds that consume JIT kernels.
+# CUDA example that includes the device helpers is opt-in. This probe
+# instantiates one consumer kernel against both header-only NCCL and IBGDA
+# helpers so a call-shape regression fails the build. Keep nvcc optional for
+# host-only DeviceTransport builds that consume JIT kernels.
 if(USE_NCCL_DEVICE AND NOT USE_CXI)
   if(CMAKE_VERSION VERSION_LESS 3.18)
-    message(STATUS
-      "Skipping NCCL/IBGDA device API compatibility compile test: "
-      "CMake 3.18+ is required for CUDA C++17")
+    message(STATUS "Skipping NCCL/IBGDA device API compatibility compile test: "
+                   "CMake 3.18+ is required for CUDA C++17")
   else()
     include(CheckLanguage)
     check_language(CUDA)
@@ -384,18 +527,22 @@ if(USE_NCCL_DEVICE AND NOT USE_CXI)
       enable_language(CUDA)
       add_library(device_backend_api_compatibility_test OBJECT
                   ${WORKSPACE}/device_backend_api_compatibility_test.cu)
-      target_include_directories(device_backend_api_compatibility_test PRIVATE
-        ${CMAKE_CURRENT_SOURCE_DIR}/../include)
-      target_link_libraries(device_backend_api_compatibility_test PRIVATE
-        NCCL::nccl)
-      target_compile_options(device_backend_api_compatibility_test PRIVATE
-        $<$<COMPILE_LANGUAGE:CUDA>:--expt-relaxed-constexpr>)
-      set_target_properties(device_backend_api_compatibility_test PROPERTIES
-        CUDA_STANDARD 17 CUDA_STANDARD_REQUIRED ON CUDA_EXTENSIONS OFF)
+      target_include_directories(device_backend_api_compatibility_test
+                                 PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../include)
+      target_link_libraries(device_backend_api_compatibility_test
+                            PRIVATE NCCL::nccl)
+      target_compile_options(
+        device_backend_api_compatibility_test
+        PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:--expt-relaxed-constexpr>)
+      set_target_properties(
+        device_backend_api_compatibility_test
+        PROPERTIES CUDA_STANDARD 17
+                   CUDA_STANDARD_REQUIRED ON
+                   CUDA_EXTENSIONS OFF)
     else()
-      message(STATUS
-        "Skipping NCCL/IBGDA device API compatibility compile test: "
-        "nvcc not found")
+      message(
+        STATUS "Skipping NCCL/IBGDA device API compatibility compile test: "
+               "nvcc not found")
     endif()
   endif()
 endif()
diff --git a/mooncake-transfer-engine/tests/ascend_direct_transport_test.cpp b/mooncake-transfer-engine/tests/ascend_direct_transport_test.cpp
index 071b33f47b..ad6e90c543 100644
--- a/mooncake-transfer-engine/tests/ascend_direct_transport_test.cpp
+++ b/mooncake-transfer-engine/tests/ascend_direct_transport_test.cpp
@@ -18,6 +18,7 @@
 #include <acl/acl.h>
 #include <acl/acl_rt.h>
 #include <algorithm>
+#include <cstdint>
 #include <cstdlib>
 #include "transport/ascend_transport/ascend_direct_transport/ascend_direct_transport.h"
 #include "transport/ascend_transport/ascend_direct_transport/context_manager.h"
@@ -43,9 +44,12 @@ constexpr size_t kTransferBufSize = 4096;
 constexpr size_t kRegisterMemSize = 1024 * 1024;
 constexpr int kTransferStatusMaxRetries = 1000;
 
-static int g_device_id = 0;
+// ACL device/context are per-thread; keep the mock that way so engine worker
+// threads do not clobber the test thread's current device.
+static thread_local int g_device_id = 0;
 static int g_device_count = 1;
-static aclrtContext g_context = reinterpret_cast<aclrtContext>(0x1234);
+static thread_local aclrtContext g_context =
+    reinterpret_cast<aclrtContext>(0x10000);
 static aclError g_memcpy_result = ACL_ERROR_NONE;
 static aclError g_memcpy_async_result = ACL_ERROR_NONE;
 static aclError g_memcpy_batch_result = ACL_ERROR_NONE;
@@ -58,11 +62,27 @@ static std::mutex g_acl_mutex;
 static size_t g_malloc_physical_max_success = 0;
 static int g_malloc_physical_call_count = 0;
 
+constexpr uintptr_t kDeviceContextBase = 0x10000;
+
+aclrtContext ContextForDevice(int device_id) {
+    return reinterpret_cast<aclrtContext>(kDeviceContextBase +
+                                          static_cast<uintptr_t>(device_id));
+}
+
+int DeviceForContext(aclrtContext context) {
+    const auto value = reinterpret_cast<uintptr_t>(context);
+    if (value >= kDeviceContextBase && value < kDeviceContextBase + 1024) {
+        return static_cast<int>(value - kDeviceContextBase);
+    }
+    return -1;
+}
+
 namespace mock_acl {
 void reset() {
     std::lock_guard<std::mutex> lock(g_acl_mutex);
     g_device_id = 0;
     g_device_count = 1;
+    g_context = ContextForDevice(0);
     g_memcpy_result = ACL_ERROR_NONE;
     g_memcpy_async_result = ACL_ERROR_NONE;
     g_memcpy_batch_result = ACL_ERROR_NONE;
@@ -151,6 +171,7 @@ aclError aclrtSetDevice(int deviceId) {
         return 1;
     }
     g_device_id = deviceId;
+    g_context = ContextForDevice(deviceId);
     g_set_device_call_count++;
     g_set_device_ids.insert(deviceId);
     return ACL_ERROR_NONE;
@@ -163,6 +184,10 @@ aclError aclrtGetCurrentContext(aclrtContext* context) {
 
 aclError aclrtSetCurrentContext(aclrtContext context) {
     g_context = context;
+    const int device_id = DeviceForContext(context);
+    if (device_id >= 0) {
+        g_device_id = device_id;
+    }
     return ACL_ERROR_NONE;
 }
 
@@ -355,6 +380,10 @@ static int g_transfer_async_count = 0;
 static int g_register_mem_count = 0;
 static int g_deregister_mem_count = 0;
 static std::string g_last_connect_target;
+static std::vector<std::string> g_connect_targets;
+static adxl::Status g_get_capability_result = adxl::SUCCESS;
+static int32_t g_get_capability_value = 0;
+static std::map<std::string, std::string> g_last_init_options;
 
 namespace adxl_mock {
 void reset() {
@@ -380,6 +409,16 @@ void reset() {
     g_register_mem_count = 0;
     g_deregister_mem_count = 0;
     g_last_connect_target.clear();
+    g_connect_targets.clear();
+    g_get_capability_result = adxl::SUCCESS;
+    g_get_capability_value = 0;
+    g_last_init_options.clear();
+}
+
+void set_capability_result(adxl::Status status, int32_t value) {
+    std::lock_guard<std::mutex> lock(g_mutex);
+    g_get_capability_result = status;
+    g_get_capability_value = value;
 }
 
 void set_connect_result(adxl::Status status) {
@@ -478,6 +517,16 @@ std::string get_last_connect_target() {
     std::lock_guard<std::mutex> lock(g_mutex);
     return g_last_connect_target;
 }
+
+std::vector<std::string> get_connect_targets() {
+    std::lock_guard<std::mutex> lock(g_mutex);
+    return g_connect_targets;
+}
+
+std::map<std::string, std::string> get_last_init_options() {
+    std::lock_guard<std::mutex> lock(g_mutex);
+    return g_last_init_options;
+}
 }  // namespace adxl_mock
 
 }  // namespace
@@ -494,8 +543,12 @@ Status AdxlEngine::Initialize(
     const AscendString& name,
     const std::map<AscendString, AscendString>& options) {
     (void)name;
-    (void)options;
     g_was_initialize_called = true;
+    g_last_init_options.clear();
+    for (const auto& kv : options) {
+        g_last_init_options[std::string(kv.first.GetString())] =
+            std::string(kv.second.GetString());
+    }
     return g_initialize_result;
 }
 
@@ -507,6 +560,7 @@ Status AdxlEngine::Connect(const AscendString& remote_engine,
     std::lock_guard<std::mutex> lock(g_mutex);
     g_connected.insert(std::string(remote_engine.GetString()));
     g_last_connect_target = remote_engine.GetString();
+    g_connect_targets.push_back(g_last_connect_target);
     g_connect_count++;
     return g_connect_result;
 }
@@ -611,6 +665,13 @@ Status AdxlEngine::DeregisterMem(MemHandle mem_handle) {
     return SUCCESS;
 }
 
+Status AdxlEngine::GetCapability(FeatureType feature_type, int32_t& value) {
+    (void)feature_type;
+    std::lock_guard<std::mutex> lock(g_mutex);
+    value = g_get_capability_value;
+    return g_get_capability_result;
+}
+
 }  // namespace adxl
 
 class AscendDirectTransportTest : public ::testing::Test {
@@ -684,12 +745,21 @@ class AscendDirectTransportTest : public ::testing::Test {
     void addMultiEndpointRemoteSegment(
         std::shared_ptr<TransferMetadata> meta, int segment_id,
         const std::string& name, const std::string& host_ip,
-        const std::vector<std::string>& endpoints) {
+        const std::vector<std::string>& endpoints, int32_t dest_device_id = -1,
+        uint64_t dest_addr = 0, uint64_t dest_len = 0) {
         auto remote_desc = std::make_shared<TransferMetadata::SegmentDesc>();
         remote_desc->name = name;
         remote_desc->protocol = "ascend";
         remote_desc->rank_info.hostIp = host_ip;
         remote_desc->rank_info.endpoints = endpoints;
+        if (dest_device_id >= 0 && dest_len > 0) {
+            TransferMetadata::BufferDesc buffer;
+            buffer.name = "store";
+            buffer.addr = dest_addr;
+            buffer.length = dest_len;
+            buffer.device_id = dest_device_id;
+            remote_desc->buffers.push_back(buffer);
+        }
         meta->addLocalSegment(segment_id, name, std::move(remote_desc));
     }
 
@@ -785,23 +855,33 @@ class AscendDirectTransportTest : public ::testing::Test {
     }
 
     TransferWaitResult waitForTransfer(AscendDirectTransport* transport,
-                                       uint64_t batch_id) {
+                                       uint64_t batch_id,
+                                       size_t task_count = 1) {
         Transport::TransferStatus status{};
-        for (int i = 0; i < kTransferStatusMaxRetries; ++i) {
-            Status s = transport->getTransferStatus(batch_id, 0, status);
-            if (!s.ok()) {
-                ADD_FAILURE() << "getTransferStatus failed";
-                return {false, false, status};
-            }
-            if (status.s == Transport::FAILED) {
-                return {true, true, status};
+        for (size_t task_id = 0; task_id < task_count; ++task_id) {
+            bool task_done = false;
+            for (int i = 0; i < kTransferStatusMaxRetries; ++i) {
+                Status s =
+                    transport->getTransferStatus(batch_id, task_id, status);
+                if (!s.ok()) {
+                    ADD_FAILURE()
+                        << "getTransferStatus failed for task " << task_id;
+                    return {false, false, status};
+                }
+                if (status.s == Transport::FAILED) {
+                    return {true, true, status};
+                }
+                if (status.s == Transport::COMPLETED) {
+                    task_done = true;
+                    break;
+                }
+                usleep(1000);
             }
-            if (status.s == Transport::COMPLETED) {
-                return {true, false, status};
+            if (!task_done) {
+                return {false, false, status};
             }
-            usleep(1000);
         }
-        return {false, false, status};
+        return {true, false, status};
     }
 
     size_t getLocalBufferCount(AscendDirectTransport* transport) {
@@ -850,21 +930,15 @@ TEST_F(AscendDirectTransportTest,
     ContextManager::getInstance().finalize();
     constexpr int kDeviceCount = 4;
     constexpr int kCallerDeviceId = 1;
-    auto* expected_context = reinterpret_cast<aclrtContext>(0x4321);
 
     mock_acl::set_device_count(kDeviceCount);
     ASSERT_EQ(aclrtSetDevice(kCallerDeviceId), ACL_ERROR_NONE);
-    ASSERT_EQ(aclrtSetCurrentContext(expected_context), ACL_ERROR_NONE);
 
     ASSERT_TRUE(ContextManager::getInstance().initialize());
 
     int current_device_id = -1;
     ASSERT_EQ(aclrtGetDevice(&current_device_id), ACL_ERROR_NONE);
     EXPECT_EQ(current_device_id, kCallerDeviceId);
-
-    aclrtContext current_context = nullptr;
-    ASSERT_EQ(aclrtGetCurrentContext(&current_context), ACL_ERROR_NONE);
-    EXPECT_EQ(current_context, expected_context);
 }
 
 TEST_F(AscendDirectTransportTest,
@@ -1114,12 +1188,12 @@ TEST_F(AscendDirectTransportTest, DummyReal_Roce_LocalCopy_Success) {
 }
 
 TEST_F(AscendDirectTransportTest,
-       DummyReal_Roce_SameHostDifferentProcess_SelectsSameIndex) {
+       DummyReal_Roce_SameHostSelectsDestBufferEngine) {
     globalConfig().ascend_agent_mode = true;
     setenv("HCCL_INTRA_ROCE_ENABLE", "1", 1);
     constexpr int kDeviceCount = 4;
     mock_acl::set_device_count(kDeviceCount);
-    g_device_id = 0;
+    g_device_id = 1;
     ContextManager::getInstance().finalize();
     ASSERT_TRUE(ContextManager::getInstance().initialize());
     auto transport = createTransport();
@@ -1128,25 +1202,79 @@ TEST_F(AscendDirectTransportTest,
                                              "cpu:0", true, true),
               0);
 
-    // Same host with multiple endpoints - dummy-real should use same-index
     std::vector<std::string> endpoints = {"127.0.0.1:9000", "127.0.0.1:9100",
                                           "127.0.0.1:9200", "127.0.0.1:9300"};
     addMultiEndpointRemoteSegment(transport->meta(), 1, "dummy_real_same_host",
-                                  "127.0.0.1", endpoints);
+                                  "127.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
 
     initTestData(kTransferBufSize);
     auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
-    // dummy-real uses same-index pairing: engine_id=0 -> endpoints[0]
-    // Different process so no local copy, ADXL connect happens
-    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:9000")
-        << "Dummy-real should use same-index pairing without offset";
+    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:9200")
+        << "Target engine follows dest buffer device_id, not local engine";
 
     unsetenv("HCCL_INTRA_ROCE_ENABLE");
     globalConfig().ascend_agent_mode = false;
 }
 
+TEST_F(AscendDirectTransportTest,
+       SameSegment_TwoDestBuffers_ConnectsEachEngine) {
+    globalConfig().ascend_agent_mode = true;
+    unsetenv("HCCL_INTRA_ROCE_ENABLE");
+    constexpr int kDeviceCount = 4;
+    mock_acl::set_device_count(kDeviceCount);
+    ContextManager::getInstance().finalize();
+    ASSERT_TRUE(ContextManager::getInstance().initialize());
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+    ASSERT_EQ(transport->registerLocalMemory(test_buffer_src_, kRegisterMemSize,
+                                             "cpu:0", true, true),
+              0);
+
+    std::vector<std::string> endpoints = {"10.0.0.1:5000", "10.0.0.1:5100",
+                                          "10.0.0.1:5200", "10.0.0.1:5300"};
+    addMultiEndpointRemoteSegment(transport->meta(), 1, "two_dests", "10.0.0.1",
+                                  endpoints, /*dest_device_id=*/1, 0x10000,
+                                  kTransferBufSize);
+    auto remote_desc = transport->meta()->getSegmentDescByID(1);
+    ASSERT_NE(remote_desc, nullptr);
+    TransferMetadata::BufferDesc second;
+    second.name = "store";
+    second.addr = 0x20000;
+    second.length = kTransferBufSize;
+    second.device_id = 2;
+    remote_desc->buffers.push_back(second);
+
+    auto batch_id = transport->allocateBatchID(2);
+    ASSERT_NE(batch_id, 0);
+    std::vector<Transport::TransferRequest> requests(2);
+    requests[0].opcode = Transport::TransferRequest::WRITE;
+    requests[0].source = test_buffer_src_;
+    requests[0].target_id = 1;
+    requests[0].target_offset = 0x10000;
+    requests[0].length = kTransferBufSize;
+    requests[1].opcode = Transport::TransferRequest::WRITE;
+    requests[1].source = test_buffer_src_;
+    requests[1].target_id = 1;
+    requests[1].target_offset = 0x20000;
+    requests[1].length = kTransferBufSize;
+    ASSERT_TRUE(transport->submitTransfer(batch_id, requests).ok());
+    auto result = waitForTransfer(transport.get(), batch_id, /*task_count=*/2);
+    transport->freeBatchID(batch_id);
+    ASSERT_TRUE(result.finished);
+    EXPECT_FALSE(result.failed);
+
+    auto targets = adxl_mock::get_connect_targets();
+    EXPECT_NE(std::find(targets.begin(), targets.end(), "10.0.0.1:5100"),
+              targets.end());
+    EXPECT_NE(std::find(targets.begin(), targets.end(), "10.0.0.1:5200"),
+              targets.end());
+
+    globalConfig().ascend_agent_mode = false;
+}
+
 // -----------------------------------------------------------------------------
 // Memory registration tests
 // -----------------------------------------------------------------------------
@@ -1161,6 +1289,21 @@ TEST_F(AscendDirectTransportTest, Memory_RegisterAndUnregister) {
     EXPECT_EQ(transport->unregisterLocalMemory(test_buffer_src_, true), 0);
 }
 
+TEST_F(AscendDirectTransportTest, Memory_RegisterStampsBufferDeviceId) {
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+
+    constexpr int32_t kStampDeviceId = 2;
+    g_device_id = kStampDeviceId;
+    ASSERT_EQ(transport->registerLocalMemory(test_buffer_src_, kRegisterMemSize,
+                                             "cpu:0", true, true),
+              0);
+    auto segment_desc = transport->meta()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(segment_desc, nullptr);
+    ASSERT_FALSE(segment_desc->buffers.empty());
+    EXPECT_EQ(segment_desc->buffers.back().device_id, kStampDeviceId);
+}
+
 TEST_F(AscendDirectTransportTest, Memory_RegisterFailureRollsBackMetadata) {
     adxl_mock::set_register_mem_result(adxl::FAILED);
     auto transport = createTransport();
@@ -1253,10 +1396,14 @@ TEST_F(AscendDirectTransportTest,
     ASSERT_EQ(transport->registerLocalMemory(store_buffer, kRegisterMemSize,
                                              "cpu:0", true, true),
               0);
-    EXPECT_EQ(adxl_mock::get_register_mem_count(), kEngineCount);
+    EXPECT_EQ(adxl_mock::get_register_mem_count(), 1);
+    auto segment_desc = transport->meta()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(segment_desc, nullptr);
+    ASSERT_FALSE(segment_desc->buffers.empty());
+    EXPECT_EQ(segment_desc->buffers.back().device_id, 0);
 
     ASSERT_EQ(transport->unregisterLocalMemory(store_buffer, true), 0);
-    EXPECT_EQ(adxl_mock::get_deregister_mem_count(), kEngineCount);
+    EXPECT_EQ(adxl_mock::get_deregister_mem_count(), 1);
 
     auto registered_handles = adxl_mock::get_registered_mem_handles();
     auto deregistered_handles = adxl_mock::get_deregistered_mem_handles();
@@ -1869,7 +2016,8 @@ TEST_F(AscendDirectTransportTest,
 // Standalone mode tests (non-dummy-real, non-fabric-mem)
 // -----------------------------------------------------------------------------
 
-TEST_F(AscendDirectTransportTest, Standalone_RemoteHost_SelectsPhyDevEndpoint) {
+TEST_F(AscendDirectTransportTest,
+       Standalone_RemoteHost_SelectsDestBufferEngine) {
     globalConfig().ascend_agent_mode = false;
     unsetenv("HCCL_INTRA_ROCE_ENABLE");
     constexpr int kDeviceCount = 4;
@@ -1881,23 +2029,21 @@ TEST_F(AscendDirectTransportTest, Standalone_RemoteHost_SelectsPhyDevEndpoint) {
                                              "cpu:0", true, true),
               0);
 
-    // Remote host with multiple endpoints (different from local host)
     std::vector<std::string> endpoints = {"10.0.0.1:5000", "10.0.0.1:5100",
                                           "10.0.0.1:5200", "10.0.0.1:5300"};
     addMultiEndpointRemoteSegment(transport->meta(), 1, "remote_host",
-                                  "10.0.0.1", endpoints);
+                                  "10.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
 
     initTestData(kTransferBufSize);
     auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
     EXPECT_FALSE(result.failed);
-    // phy_dev=2, different host -> selects endpoints[2]
     EXPECT_EQ(adxl_mock::get_last_connect_target(), "10.0.0.1:5200");
 }
 
-TEST_F(AscendDirectTransportTest,
-       Standalone_SameHostDifferentProcess_OffsetsByOne) {
+TEST_F(AscendDirectTransportTest, Standalone_SameHost_SelectsDestBufferEngine) {
     globalConfig().ascend_agent_mode = false;
     unsetenv("HCCL_INTRA_ROCE_ENABLE");
     constexpr int kDeviceCount = 4;
@@ -1909,27 +2055,28 @@ TEST_F(AscendDirectTransportTest,
                                              "cpu:0", true, true),
               0);
 
-    // Same host (127.0.0.1) with multiple endpoints (different process)
     std::vector<std::string> endpoints = {"127.0.0.1:6000", "127.0.0.1:6100",
                                           "127.0.0.1:6200", "127.0.0.1:6300"};
     addMultiEndpointRemoteSegment(transport->meta(), 1, "same_host_process",
-                                  "127.0.0.1", endpoints);
+                                  "127.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
 
     initTestData(kTransferBufSize);
     auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
     EXPECT_FALSE(result.failed);
-    // phy_dev=1, same host -> offset +1 -> selects endpoints[2]
-    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:6200");
+    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:6200")
+        << "Same-host transfers must not apply a +1 engine offset";
 }
 
-TEST_F(AscendDirectTransportTest, Standalone_SameHostOffset_WrapsAround) {
+TEST_F(AscendDirectTransportTest,
+       Standalone_MissingDestBuffer_UsesFrontEndpoint) {
     globalConfig().ascend_agent_mode = false;
     unsetenv("HCCL_INTRA_ROCE_ENABLE");
     constexpr int kDeviceCount = 4;
     mock_acl::set_device_count(kDeviceCount);
-    g_device_id = 3;  // last device: (3+1)%4 = 0
+    g_device_id = 3;
     auto transport = createTransport();
     ASSERT_NE(transport, nullptr);
     ASSERT_EQ(transport->registerLocalMemory(test_buffer_src_, kRegisterMemSize,
@@ -1946,12 +2093,39 @@ TEST_F(AscendDirectTransportTest, Standalone_SameHostOffset_WrapsAround) {
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
     EXPECT_FALSE(result.failed);
-    // phy_dev=3, same host -> (3+1)%4=0 -> selects endpoints[0]
     EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:7000");
 }
 
 TEST_F(AscendDirectTransportTest,
-       Standalone_FabricMem_SameHostUsesFrontEndpoint) {
+       Standalone_SingleEndpoint_IgnoresDestDeviceId) {
+    globalConfig().ascend_agent_mode = false;
+    unsetenv("HCCL_INTRA_ROCE_ENABLE");
+    constexpr int kDeviceCount = 4;
+    mock_acl::set_device_count(kDeviceCount);
+    g_device_id = 3;
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+    ASSERT_EQ(transport->registerLocalMemory(test_buffer_src_, kRegisterMemSize,
+                                             "cpu:0", true, true),
+              0);
+
+    std::vector<std::string> endpoints = {"127.0.0.1:7400"};
+    addMultiEndpointRemoteSegment(transport->meta(), 1, "single_endpoint",
+                                  "127.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
+
+    initTestData(kTransferBufSize);
+    auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
+                                    0x10000, kTransferBufSize);
+    ASSERT_TRUE(result.finished);
+    EXPECT_FALSE(result.failed);
+    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:7400")
+        << "A single remote endpoint is used as-is, even when dest "
+           "buffer device_id is not 0";
+}
+
+TEST_F(AscendDirectTransportTest,
+       Standalone_FabricMem_SameHostSelectsDestBufferEngine) {
     // Fabric mem is a Store-TE feature, so the TE must be store-init for the
     // transport to capture use_fabric_mem_=true.
     globalConfig().ascend_agent_mode = false;
@@ -1970,15 +2144,16 @@ TEST_F(AscendDirectTransportTest,
     std::vector<std::string> endpoints = {"127.0.0.1:8000", "127.0.0.1:8100",
                                           "127.0.0.1:8200", "127.0.0.1:8300"};
     addMultiEndpointRemoteSegment(transport->meta(), 1, "fabric_same_host",
-                                  "127.0.0.1", endpoints);
+                                  "127.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
 
     initTestData(kTransferBufSize);
     auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
     EXPECT_FALSE(result.failed);
-    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:8000")
-        << "Fabric-mem standalone should not apply same-host offset";
+    EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:8200")
+        << "Fabric-mem target engine follows dest buffer device_id";
 
     globalConfig().ascend_use_fabric_mem = false;
     globalConfig().ascend_store_te_init = false;
@@ -1986,9 +2161,8 @@ TEST_F(AscendDirectTransportTest,
 
 // A non-Store (e.g. P2P/HCCS) TE must NOT inherit a Store TE's fabric flag that
 // leaked into the process-global config: with ascend_use_fabric_mem=true but
-// ascend_store_te_init=false, the transport must capture use_fabric_mem_=false
-// and behave like a normal standalone TE (same-host offset +1), not the fabric
-// path (front endpoint).
+// ascend_store_te_init=false, the transport must capture use_fabric_mem_=false.
+// Routing still follows dest buffer device_id (no same-host offset).
 TEST_F(AscendDirectTransportTest,
        Standalone_FabricFlagWithoutStoreTe_DoesNotInheritFabric) {
     globalConfig().ascend_agent_mode = false;
@@ -2007,17 +2181,16 @@ TEST_F(AscendDirectTransportTest,
     std::vector<std::string> endpoints = {"127.0.0.1:9000", "127.0.0.1:9100",
                                           "127.0.0.1:9200", "127.0.0.1:9300"};
     addMultiEndpointRemoteSegment(transport->meta(), 1, "p2p_no_fabric",
-                                  "127.0.0.1", endpoints);
+                                  "127.0.0.1", endpoints, /*dest_device_id=*/2,
+                                  0x10000, kTransferBufSize);
 
     initTestData(kTransferBufSize);
     auto result = runRemoteTransfer(transport.get(), test_buffer_src_, 1,
                                     0x10000, kTransferBufSize);
     ASSERT_TRUE(result.finished);
     EXPECT_FALSE(result.failed);
-    // phy_dev=1, same host, fabric NOT inherited -> offset +1 -> endpoints[2]
     EXPECT_EQ(adxl_mock::get_last_connect_target(), "127.0.0.1:9200")
-        << "Non-Store TE must not inherit fabric; should apply same-host "
-           "offset";
+        << "Non-Store TE still routes by dest buffer device_id";
 
     globalConfig().ascend_use_fabric_mem = false;
 }
@@ -2039,8 +2212,15 @@ TEST(FabricMemBestEffortAllocTest, PercentileLadderFindsFeasibleSize) {
     size_t actual = 0;
     void* ptr = ascend_allocate_memory_best_effort(kTarget, "ascend", &actual);
     ASSERT_NE(ptr, nullptr);
-    EXPECT_EQ(actual, kExpectGiB * kGiB);
-    EXPECT_GT(mock_acl::malloc_physical_call_count(), 1);
+    if (&adxl::AdxlEngine::MallocMem == nullptr) {
+        EXPECT_EQ(actual, kExpectGiB * kGiB);
+        EXPECT_GT(mock_acl::malloc_physical_call_count(), 1);
+    } else {
+        // AdxlEngine::MallocMem is linked in this CANN build, so the VMM
+        // mock percentile ladder is unused. Still require a feasible step-down.
+        EXPECT_LT(actual, kTarget);
+        EXPECT_GE(actual, kTarget / 2);
+    }
 
     ascend_free_memory("ascend", ptr);
     globalConfig().ascend_use_fabric_mem = false;
@@ -2105,6 +2285,222 @@ TEST(FabricMemBestEffortAllocTest, FullTargetFirstSuccess) {
     mock_acl::reset();
 }
 
+namespace {
+int32_t CurrentAclDevice() {
+    int32_t device_id = -1;
+    EXPECT_EQ(aclrtGetDevice(&device_id), ACL_ERROR_NONE);
+    return device_id;
+}
+
+int g_host_alloc_calls = 0;
+
+void* CountingHostAlloc(size_t size, size_t alignment, bool defer) {
+    (void)alignment;
+    (void)defer;
+    ++g_host_alloc_calls;
+    void* ptr = nullptr;
+    EXPECT_EQ(aclrtMallocHost(&ptr, size), ACL_ERROR_NONE);
+    return ptr;
+}
+
+void* NullHostAlloc(size_t, size_t, bool) { return nullptr; }
+
+struct AgentAllocEnv {
+    explicit AgentAllocEnv(int device_count) {
+        mock_acl::reset();
+        g_host_alloc_calls = 0;
+        globalConfig().ascend_agent_mode = true;
+        globalConfig().ascend_use_fabric_mem = false;
+        mock_acl::set_device_count(device_count);
+        ContextManager::getInstance().finalize();
+        EXPECT_TRUE(ContextManager::getInstance().initialize());
+    }
+    ~AgentAllocEnv() {
+        ContextManager::getInstance().finalize();
+        globalConfig().ascend_agent_mode = false;
+        globalConfig().ascend_use_fabric_mem = false;
+        mock_acl::reset();
+    }
+};
+}  // namespace
+
+TEST(AgentModeAllocTest, ConsecutiveStoreAllocsRotateDevices) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kAllocSize = 4096;
+    AgentAllocEnv env(kDeviceCount);
+
+    int first = -1;
+    for (int i = 0; i < kDeviceCount; ++i) {
+        size_t actual = 0;
+        void* ptr =
+            ascend_allocate_memory_best_effort(kAllocSize, "ascend", &actual);
+        ASSERT_NE(ptr, nullptr);
+        EXPECT_EQ(actual, kAllocSize);
+        if (i == 0) {
+            first = CurrentAclDevice();
+            ASSERT_GE(first, 0);
+            ASSERT_LT(first, kDeviceCount);
+        } else {
+            EXPECT_EQ(CurrentAclDevice(), (first + i) % kDeviceCount);
+        }
+        ascend_free_memory("ascend", ptr);
+    }
+
+    size_t actual = 0;
+    void* wrap =
+        ascend_allocate_memory_best_effort(kAllocSize, "ascend", &actual);
+    ASSERT_NE(wrap, nullptr);
+    EXPECT_EQ(CurrentAclDevice(), first);
+    ascend_free_memory("ascend", wrap);
+}
+
+TEST(AgentModeAllocTest, HostAllocRotatesDevices) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kAllocSize = 4096;
+    AgentAllocEnv env(kDeviceCount);
+
+    int first = -1;
+    for (int i = 0; i < kDeviceCount; ++i) {
+        size_t actual = 0;
+        void* ptr = ascend_allocate_memory_best_effort(
+            kAllocSize, "ascend", &actual, CountingHostAlloc, kAllocSize,
+            false);
+        ASSERT_NE(ptr, nullptr);
+        EXPECT_EQ(actual, kAllocSize);
+        if (i == 0) {
+            first = CurrentAclDevice();
+            ASSERT_GE(first, 0);
+            ASSERT_LT(first, kDeviceCount);
+        } else {
+            EXPECT_EQ(CurrentAclDevice(), (first + i) % kDeviceCount);
+        }
+        ascend_free_memory("ascend", ptr);
+    }
+    EXPECT_EQ(g_host_alloc_calls, kDeviceCount);
+}
+
+TEST(AgentModeAllocTest, FabricMemIgnoresHostAlloc) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kGiB = 1024ULL * 1024 * 1024;
+    AgentAllocEnv env(kDeviceCount);
+    globalConfig().ascend_use_fabric_mem = true;
+    mock_acl::set_malloc_physical_max_success(0);
+
+    size_t actual = 0;
+    void* ptr = ascend_allocate_memory_best_effort(
+        kGiB, "ascend", &actual, CountingHostAlloc, kGiB, false);
+    ASSERT_NE(ptr, nullptr);
+    EXPECT_EQ(g_host_alloc_calls, 0) << "fabric_mem must not call host_alloc";
+    EXPECT_GT(actual, 0);
+    ascend_free_memory("ascend", ptr);
+}
+
+TEST(AgentModeAllocTest, FailedHostAllocDoesNotConsumeSlot) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kAllocSize = 4096;
+    AgentAllocEnv env(kDeviceCount);
+
+    size_t actual = 0;
+    void* marker =
+        ascend_allocate_memory_best_effort(kAllocSize, "ascend", &actual);
+    ASSERT_NE(marker, nullptr);
+    const int d0 = CurrentAclDevice();
+    ascend_free_memory("ascend", marker);
+
+    actual = 0;
+    void* failed = ascend_allocate_memory_best_effort(
+        kAllocSize, "ascend", &actual, NullHostAlloc, kAllocSize, false);
+    EXPECT_EQ(failed, nullptr);
+    EXPECT_EQ(actual, 0);
+
+    actual = 0;
+    void* ok =
+        ascend_allocate_memory_best_effort(kAllocSize, "ascend", &actual);
+    ASSERT_NE(ok, nullptr);
+    EXPECT_EQ(CurrentAclDevice(), (d0 + 1) % kDeviceCount);
+    ascend_free_memory("ascend", ok);
+}
+
+TEST(AgentModeAllocTest, DirectVmmDoesNotRotateSequencer) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kGiB = 1024ULL * 1024 * 1024;
+    AgentAllocEnv env(kDeviceCount);
+
+    size_t actual = 0;
+    void* first = ascend_allocate_memory_best_effort(4096, "ascend", &actual);
+    ASSERT_NE(first, nullptr);
+    const int d0 = CurrentAclDevice();
+    ascend_free_memory("ascend", first);
+
+    void* vmm = ascend_allocate_vmm_memory_direct(kGiB);
+    ASSERT_NE(vmm, nullptr);
+
+    actual = 0;
+    void* second = ascend_allocate_memory_best_effort(4096, "ascend", &actual);
+    ASSERT_NE(second, nullptr);
+    EXPECT_EQ(CurrentAclDevice(), (d0 + 1) % kDeviceCount)
+        << "direct VMM must not consume the agent alloc sequencer";
+
+    ascend_free_memory("ascend", second);
+    ascend_free_memory("ascend", vmm);
+}
+
+TEST(AgentModeAllocTest, FailedBestEffortProbesDoNotSkipDevice) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kGiB = 1024ULL * 1024 * 1024;
+    AgentAllocEnv env(kDeviceCount);
+
+    size_t actual = 0;
+    void* marker = ascend_allocate_memory_best_effort(4096, "ascend", &actual);
+    ASSERT_NE(marker, nullptr);
+    const int d0 = CurrentAclDevice();
+    ascend_free_memory("ascend", marker);
+
+    globalConfig().ascend_use_fabric_mem = true;
+    mock_acl::set_malloc_physical_max_success(35 * kGiB);
+    actual = 0;
+    void* first =
+        ascend_allocate_memory_best_effort(40 * kGiB, "ascend", &actual);
+    ASSERT_NE(first, nullptr);
+    EXPECT_GT(actual, 0);
+    EXPECT_EQ(CurrentAclDevice(), (d0 + 1) % kDeviceCount)
+        << "failed 100%/90% probes must not consume a device slot";
+    ascend_free_memory("ascend", first);
+
+    actual = 0;
+    void* second = ascend_allocate_memory_best_effort(kGiB, "ascend", &actual);
+    ASSERT_NE(second, nullptr);
+    EXPECT_EQ(CurrentAclDevice(), (d0 + 2) % kDeviceCount);
+    ascend_free_memory("ascend", second);
+}
+
+TEST(AgentModeAllocTest, EntireBestEffortFailureDoesNotConsumeSlot) {
+    constexpr int kDeviceCount = 4;
+    constexpr size_t kGiB = 1024ULL * 1024 * 1024;
+    AgentAllocEnv env(kDeviceCount);
+
+    size_t actual = 0;
+    void* marker = ascend_allocate_memory_best_effort(4096, "ascend", &actual);
+    ASSERT_NE(marker, nullptr);
+    const int d0 = CurrentAclDevice();
+    ascend_free_memory("ascend", marker);
+
+    globalConfig().ascend_use_fabric_mem = true;
+    mock_acl::set_malloc_physical_max_success(15 * kGiB);
+    actual = 0;
+    void* failed =
+        ascend_allocate_memory_best_effort(40 * kGiB, "ascend", &actual);
+    EXPECT_EQ(failed, nullptr);
+    EXPECT_EQ(actual, 0);
+
+    mock_acl::set_malloc_physical_max_success(0);
+    actual = 0;
+    void* ok = ascend_allocate_memory_best_effort(kGiB, "ascend", &actual);
+    ASSERT_NE(ok, nullptr);
+    EXPECT_EQ(CurrentAclDevice(), (d0 + 1) % kDeviceCount);
+    ascend_free_memory("ascend", ok);
+}
+
 TEST(RoceModeDetectionTest, GlobalResourceConfig_StringRoceDesc) {
     EXPECT_TRUE(HasRoceProtocolDescInGlobalResourceConfig(
         R"({"comm_resource_config.protocol_desc":"roce:device"})"));
@@ -2235,6 +2631,53 @@ TEST(StoreResourceConfigSplitTest, IsRoceModeEnabled_StoreRoceP2pHccs) {
     unsetenv("ASCEND_GLOBAL_RESOURCE_CONFIG");
 }
 
+// -----------------------------------------------------------------------------
+// Client-Server mode: when capability is supported and user did not set
+// ASCEND_LOCAL_COMM_RES, Mooncake auto-injects LocalCommRes={"version":"1.3"}
+// so EngineFactory selects HixlEngine (HixlCS path).
+// -----------------------------------------------------------------------------
+
+class ClientServerModeTest : public AscendDirectTransportTest {
+   protected:
+    void SetUp() override {
+        AscendDirectTransportTest::SetUp();
+        unsetenv("ASCEND_LOCAL_COMM_RES");
+    }
+    void TearDown() override {
+        unsetenv("ASCEND_LOCAL_COMM_RES");
+        AscendDirectTransportTest::TearDown();
+    }
+};
+
+TEST_F(ClientServerModeTest, AutoInjectLocalCommResWhenSupported) {
+    adxl_mock::set_capability_result(adxl::SUCCESS, 1);
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+    const auto opts = adxl_mock::get_last_init_options();
+    auto it = opts.find("adxl.LocalCommRes");
+    ASSERT_NE(it, opts.end());
+    EXPECT_EQ(it->second, R"({"version":"1.3"})");
+}
+
+TEST_F(ClientServerModeTest, NoInjectWhenNotSupported) {
+    adxl_mock::set_capability_result(adxl::SUCCESS, 0);
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+    const auto opts = adxl_mock::get_last_init_options();
+    EXPECT_EQ(opts.find("adxl.LocalCommRes"), opts.end());
+}
+
+TEST_F(ClientServerModeTest, UserEnvOverridesAutoInject) {
+    adxl_mock::set_capability_result(adxl::SUCCESS, 1);
+    setenv("ASCEND_LOCAL_COMM_RES", R"({"version":"1.2"})", 1);
+    auto transport = createTransport();
+    ASSERT_NE(transport, nullptr);
+    const auto opts = adxl_mock::get_last_init_options();
+    auto it = opts.find("adxl.LocalCommRes");
+    ASSERT_NE(it, opts.end());
+    EXPECT_EQ(it->second, R"({"version":"1.2"})");
+}
+
 int main(int argc, char** argv) {
     ::testing::InitGoogleTest(&argc, argv);
     return RUN_ALL_TESTS();
diff --git a/mooncake-transfer-engine/tests/config_test.cpp b/mooncake-transfer-engine/tests/config_test.cpp
index e3f75d5c6b..88dece4809 100644
--- a/mooncake-transfer-engine/tests/config_test.cpp
+++ b/mooncake-transfer-engine/tests/config_test.cpp
@@ -14,13 +14,20 @@
 
 #include <gtest/gtest.h>
 
+#include <atomic>
+#include <chrono>
+#include <cstddef>
 #include <cstdlib>
+#include <thread>
 
 #include "config.h"
+#include "transport/batch_registration.h"
 
 namespace mooncake {
 namespace {
 
+// --- MC_PKEY_INDEX (stoi with try-catch, range 0-65535) ---
+
 class PkeyIndexEnvTest : public ::testing::Test {
    protected:
     void TearDown() override {
@@ -277,6 +284,56 @@ TEST_F(ConnPauseTtlEnvTest, EmptyStringKeepsDefault) {
     EXPECT_EQ(config.conn_pause_ttl_ms, 17);
 }
 
+// MC_IB_PORT names the RDMA port opened on every device. Port numbers are
+// 1-based, so 0 is not a "disable" value: it makes ibv_query_port fail on
+// every device and takes the whole topology down.
+class IbPortEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_IB_PORT"); }
+};
+
+TEST_F(IbPortEnvTest, DefaultIsPortOneWhenUnset) {
+    ::unsetenv("MC_IB_PORT");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 1);
+}
+
+TEST_F(IbPortEnvTest, ValidOverrideIsApplied) {
+    ASSERT_EQ(::setenv("MC_IB_PORT", "2", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 2);
+}
+
+TEST_F(IbPortEnvTest, ZeroIsRejected) {
+    ASSERT_EQ(::setenv("MC_IB_PORT", "0", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 1);
+}
+
+TEST_F(IbPortEnvTest, OutOfRangeIsRejected) {
+    ASSERT_EQ(::setenv("MC_IB_PORT", "256", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 1);
+}
+
+TEST_F(IbPortEnvTest, NegativeIsRejected) {
+    ASSERT_EQ(::setenv("MC_IB_PORT", "-1", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 1);
+}
+
+TEST_F(IbPortEnvTest, NonNumericIsRejected) {
+    ASSERT_EQ(::setenv("MC_IB_PORT", "abc", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.port, 1);
+}
+
 // MC_MAX_CONCURRENT_REG_MR caps how many buffers registerLocalMemoryBatch()
 // registers at once; 0 (the default) means unbounded. 0 is therefore also what
 // a silent atol() fallback would produce on a typo, which would read as "the
@@ -348,6 +405,78 @@ TEST_F(MaxConcurrentRegMrEnvTest, EmptyStringKeepsDefault) {
     EXPECT_EQ(config.max_concurrent_reg_mr, 17u);
 }
 
+class MaxConcurrentRegMrScope {
+   public:
+    explicit MaxConcurrentRegMrScope(size_t value)
+        : previous_(globalConfig().max_concurrent_reg_mr) {
+        globalConfig().max_concurrent_reg_mr = value;
+    }
+
+    ~MaxConcurrentRegMrScope() {
+        globalConfig().max_concurrent_reg_mr = previous_;
+    }
+
+   private:
+    size_t previous_;
+};
+
+void updatePeak(std::atomic<size_t>& peak, size_t current) {
+    size_t observed = peak.load();
+    while (observed < current &&
+           !peak.compare_exchange_weak(observed, current)) {
+    }
+}
+
+TEST(BatchRegistrationTest, RespectsConfiguredWorkerLimit) {
+    MaxConcurrentRegMrScope limit(3);
+    std::atomic<size_t> active{0};
+    std::atomic<size_t> peak{0};
+    std::atomic<size_t> completed{0};
+
+    int ret = runBoundedRegMrBatch(24, [&](size_t) {
+        size_t current = active.fetch_add(1) + 1;
+        updatePeak(peak, current);
+        std::this_thread::sleep_for(std::chrono::milliseconds(2));
+        active.fetch_sub(1);
+        completed.fetch_add(1);
+        return 0;
+    });
+
+    EXPECT_EQ(ret, 0);
+    EXPECT_EQ(completed.load(), 24u);
+    EXPECT_LE(peak.load(), 3u);
+}
+
+TEST(BatchRegistrationTest, LimitOneRunsSerially) {
+    MaxConcurrentRegMrScope limit(1);
+    std::atomic<size_t> active{0};
+    std::atomic<size_t> peak{0};
+
+    int ret = runBoundedRegMrBatch(8, [&](size_t) {
+        size_t current = active.fetch_add(1) + 1;
+        updatePeak(peak, current);
+        std::this_thread::yield();
+        active.fetch_sub(1);
+        return 0;
+    });
+
+    EXPECT_EQ(ret, 0);
+    EXPECT_EQ(peak.load(), 1u);
+}
+
+TEST(BatchRegistrationTest, AttemptsEveryItemAndReturnsAnError) {
+    MaxConcurrentRegMrScope limit(4);
+    std::atomic<size_t> completed{0};
+
+    int ret = runBoundedRegMrBatch(12, [&](size_t index) {
+        completed.fetch_add(1);
+        return index == 7 ? -7 : 0;
+    });
+
+    EXPECT_EQ(ret, -7);
+    EXPECT_EQ(completed.load(), 12u);
+}
+
 class EfaNicSelectionEnvTest : public ::testing::Test {
    protected:
     void TearDown() override { ::unsetenv("MC_EFA_NIC_SELECTION"); }
@@ -451,5 +580,418 @@ TEST_F(MaxWrEnvTest, OutOfRangeDoesNotSetFlag) {
     EXPECT_EQ(config.max_wr, 256u);
 }
 
+// --- MC_NUM_CQ_PER_CTX (atoi, range 1-255) ---
+
+class NumCqEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_NUM_CQ_PER_CTX"); }
+};
+
+TEST_F(NumCqEnvTest, DefaultIsOneWhenUnset) {
+    ::unsetenv("MC_NUM_CQ_PER_CTX");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.num_cq_per_ctx, 1u);
+}
+
+TEST_F(NumCqEnvTest, ValidOverride) {
+    ASSERT_EQ(::setenv("MC_NUM_CQ_PER_CTX", "4", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.num_cq_per_ctx, 4u);
+}
+
+TEST_F(NumCqEnvTest, ZeroIsRejected) {
+    ASSERT_EQ(::setenv("MC_NUM_CQ_PER_CTX", "0", 1), 0);
+    GlobalConfig config;
+    config.num_cq_per_ctx = 42;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.num_cq_per_ctx, 42u);
+}
+
+TEST_F(NumCqEnvTest, OverMaxIsRejected) {
+    ASSERT_EQ(::setenv("MC_NUM_CQ_PER_CTX", "256", 1), 0);
+    GlobalConfig config;
+    config.num_cq_per_ctx = 42;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.num_cq_per_ctx, 42u);
+}
+
+TEST_F(NumCqEnvTest, AlsoSetsJfcAndJfce) {
+    ASSERT_EQ(::setenv("MC_NUM_CQ_PER_CTX", "8", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.num_jfc_per_ctx, 8u);
+    EXPECT_EQ(config.num_jfce_per_ctx, 8u);
+}
+
+// --- MC_SLICE_SIZE (atoi to size_t, val > 0) ---
+
+class SliceSizeEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_SLICE_SIZE"); }
+};
+
+TEST_F(SliceSizeEnvTest, DefaultIs65536) {
+    ::unsetenv("MC_SLICE_SIZE");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.slice_size, 65536u);
+}
+
+TEST_F(SliceSizeEnvTest, ValidOverride) {
+    ASSERT_EQ(::setenv("MC_SLICE_SIZE", "131072", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.slice_size, 131072u);
+}
+
+TEST_F(SliceSizeEnvTest, ZeroIsRejected) {
+    ASSERT_EQ(::setenv("MC_SLICE_SIZE", "0", 1), 0);
+    GlobalConfig config;
+    config.slice_size = 99999;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.slice_size, 99999u);
+}
+
+TEST_F(SliceSizeEnvTest, NegativeWrapsToLargeValue) {
+    ASSERT_EQ(::setenv("MC_SLICE_SIZE", "-100", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    // atoi("-100") returns -100, cast to size_t wraps to a large value.
+    // val > 0 passes, so config.slice_size gets the wrapped value.
+    // This documents existing (buggy) behavior.
+    EXPECT_NE(config.slice_size, 65536u);
+}
+
+// --- MC_LOG_LEVEL (string match) ---
+
+class LogLevelEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_LOG_LEVEL"); }
+};
+
+TEST_F(LogLevelEnvTest, InfoLevel) {
+    ASSERT_EQ(::setenv("MC_LOG_LEVEL", "INFO", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.log_level, google::INFO);
+    EXPECT_FALSE(config.trace);
+}
+
+TEST_F(LogLevelEnvTest, WarningLevel) {
+    ASSERT_EQ(::setenv("MC_LOG_LEVEL", "WARNING", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.log_level, google::WARNING);
+}
+
+TEST_F(LogLevelEnvTest, ErrorLevel) {
+    ASSERT_EQ(::setenv("MC_LOG_LEVEL", "ERROR", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.log_level, google::ERROR);
+}
+
+TEST_F(LogLevelEnvTest, TraceEnablesTrace) {
+    ASSERT_EQ(::setenv("MC_LOG_LEVEL", "TRACE", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.log_level, google::INFO);
+    EXPECT_TRUE(config.trace);
+}
+
+TEST_F(LogLevelEnvTest, InvalidLevelKeepsDefault) {
+    ASSERT_EQ(::setenv("MC_LOG_LEVEL", "INVALID", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.log_level, google::INFO);
+    EXPECT_FALSE(config.trace);
+}
+
+// --- MC_DISABLE_METACACHE (presence check) ---
+
+class MetacacheEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_DISABLE_METACACHE"); }
+};
+
+TEST_F(MetacacheEnvTest, DefaultEnabled) {
+    ::unsetenv("MC_DISABLE_METACACHE");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_TRUE(config.metacache);
+}
+
+TEST_F(MetacacheEnvTest, DisabledWhenSet) {
+    ASSERT_EQ(::setenv("MC_DISABLE_METACACHE", "1", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_FALSE(config.metacache);
+}
+
+// --- MC_IB_TC (stoi with try-catch, range 0-255) ---
+
+class IbTrafficClassEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_IB_TC"); }
+};
+
+TEST_F(IbTrafficClassEnvTest, DefaultIsNegativeOne) {
+    ::unsetenv("MC_IB_TC");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.ib_traffic_class, -1);
+}
+
+TEST_F(IbTrafficClassEnvTest, ValidOverride) {
+    ASSERT_EQ(::setenv("MC_IB_TC", "106", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.ib_traffic_class, 106);
+}
+
+TEST_F(IbTrafficClassEnvTest, ZeroIsValid) {
+    ASSERT_EQ(::setenv("MC_IB_TC", "0", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.ib_traffic_class, 0);
+}
+
+TEST_F(IbTrafficClassEnvTest, OverMaxIsRejected) {
+    ASSERT_EQ(::setenv("MC_IB_TC", "256", 1), 0);
+    GlobalConfig config;
+    config.ib_traffic_class = -1;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.ib_traffic_class, -1);
+}
+
+TEST_F(IbTrafficClassEnvTest, NonNumericKeepsDefault) {
+    ASSERT_EQ(::setenv("MC_IB_TC", "xyz", 1), 0);
+    GlobalConfig config;
+    config.ib_traffic_class = -1;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.ib_traffic_class, -1);
+}
+
+// --- MC_ENDPOINT_STORE_TYPE (string enum) ---
+
+class EndpointStoreTypeEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_ENDPOINT_STORE_TYPE"); }
+};
+
+TEST_F(EndpointStoreTypeEnvTest, DefaultIsSieve) {
+    ::unsetenv("MC_ENDPOINT_STORE_TYPE");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.endpoint_store_type, EndpointStoreType::SIEVE);
+}
+
+TEST_F(EndpointStoreTypeEnvTest, FifoOverride) {
+    ASSERT_EQ(::setenv("MC_ENDPOINT_STORE_TYPE", "FIFO", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.endpoint_store_type, EndpointStoreType::FIFO);
+}
+
+TEST_F(EndpointStoreTypeEnvTest, InvalidIsRejected) {
+    ASSERT_EQ(::setenv("MC_ENDPOINT_STORE_TYPE", "LRU", 1), 0);
+    GlobalConfig config;
+    config.endpoint_store_type = EndpointStoreType::FIFO;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.endpoint_store_type, EndpointStoreType::FIFO);
+}
+
+// --- ValidatePortRange (pure function) ---
+
+TEST(ValidatePortRangeTest, ValidRangePassesThrough) {
+    auto [min_p, max_p] = ValidatePortRange(15000, 17000, 15000, 17000);
+    EXPECT_EQ(min_p, 15000);
+    EXPECT_EQ(max_p, 17000);
+}
+
+TEST(ValidatePortRangeTest, CustomValidRange) {
+    auto [min_p, max_p] = ValidatePortRange(2000, 3000, 15000, 17000);
+    EXPECT_EQ(min_p, 2000);
+    EXPECT_EQ(max_p, 3000);
+}
+
+TEST(ValidatePortRangeTest, MinGreaterThanMaxFallsBack) {
+    auto [min_p, max_p] = ValidatePortRange(5000, 4000, 15000, 17000);
+    EXPECT_EQ(min_p, 15000);
+    EXPECT_EQ(max_p, 17000);
+}
+
+TEST(ValidatePortRangeTest, WellKnownPortRejected) {
+    auto [min_p, max_p] = ValidatePortRange(80, 443, 15000, 17000);
+    EXPECT_EQ(min_p, 15000);
+    EXPECT_EQ(max_p, 17000);
+}
+
+TEST(ValidatePortRangeTest, EphemeralPortRejected) {
+    auto [min_p, max_p] = ValidatePortRange(32768, 40000, 15000, 17000);
+    EXPECT_EQ(min_p, 15000);
+    EXPECT_EQ(max_p, 17000);
+}
+
+TEST(ValidatePortRangeTest, BoundaryJustAboveEphemeral) {
+    auto [min_p, max_p] = ValidatePortRange(61000, 65000, 15000, 17000);
+    EXPECT_EQ(min_p, 61000);
+    EXPECT_EQ(max_p, 65000);
+}
+
+TEST(ValidatePortRangeTest, MaxPort65535IsValid) {
+    auto [min_p, max_p] = ValidatePortRange(61000, 65535, 15000, 17000);
+    EXPECT_EQ(min_p, 61000);
+    EXPECT_EQ(max_p, 65535);
+}
+
+TEST(ValidatePortRangeTest, FirstValidPort1024) {
+    auto [min_p, max_p] = ValidatePortRange(1024, 2000, 15000, 17000);
+    EXPECT_EQ(min_p, 1024);
+    EXPECT_EQ(max_p, 2000);
+}
+
+TEST(ValidatePortRangeTest, LastBeforeEphemeral32767) {
+    auto [min_p, max_p] = ValidatePortRange(1024, 32767, 15000, 17000);
+    EXPECT_EQ(min_p, 1024);
+    EXPECT_EQ(max_p, 32767);
+}
+
+TEST(ValidatePortRangeTest, AboveMaxRejected) {
+    auto [min_p, max_p] = ValidatePortRange(61000, 65536, 15000, 17000);
+    EXPECT_EQ(min_p, 15000);
+    EXPECT_EQ(max_p, 17000);
+}
+
+// --- MC_MTU (valid values only; invalid is logged and ignored) ---
+
+class MtuEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_MTU"); }
+};
+
+TEST_F(MtuEnvTest, DefaultIs4096) {
+    ::unsetenv("MC_MTU");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_4096);
+}
+
+TEST_F(MtuEnvTest, Mtu512) {
+    ASSERT_EQ(::setenv("MC_MTU", "512", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_512);
+}
+
+TEST_F(MtuEnvTest, Mtu1024) {
+    ASSERT_EQ(::setenv("MC_MTU", "1024", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_1024);
+}
+
+TEST_F(MtuEnvTest, Mtu2048) {
+    ASSERT_EQ(::setenv("MC_MTU", "2048", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_2048);
+}
+
+TEST_F(MtuEnvTest, Mtu4096) {
+    ASSERT_EQ(::setenv("MC_MTU", "4096", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_4096);
+}
+
+TEST_F(MtuEnvTest, InvalidIsIgnored) {
+    ASSERT_EQ(::setenv("MC_MTU", "1500", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.mtu_length, IBV_MTU_4096);
+}
+
+// MC_CONTEXT_PAUSE_TTL_MS bounds how long the context-level circuit breaker
+// holds a tripped local RNIC context inactive before half-open reactivation.
+// The valid range is 1-600000ms. Zero, garbage, negative and out-of-range
+// values must preserve the configured value because zero would re-introduce
+// the permanent-latch behavior this knob exists to fix.
+class ContextPauseTtlEnvTest : public ::testing::Test {
+   protected:
+    void TearDown() override { ::unsetenv("MC_CONTEXT_PAUSE_TTL_MS"); }
+};
+
+TEST_F(ContextPauseTtlEnvTest, DefaultIsFiveThousandWhenUnset) {
+    ::unsetenv("MC_CONTEXT_PAUSE_TTL_MS");
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 5000);
+}
+
+TEST_F(ContextPauseTtlEnvTest, ValidOverrideIsApplied) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "10000", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 10000);
+}
+
+TEST_F(ContextPauseTtlEnvTest, ZeroIsIgnored) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "0", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 99;  // sentinel preserved when rejected
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 99);
+}
+
+TEST_F(ContextPauseTtlEnvTest, MaxBoundaryIsApplied) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "600000", 1), 0);
+    GlobalConfig config;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 600000);
+}
+
+TEST_F(ContextPauseTtlEnvTest, OutOfRangeIsIgnored) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "600001", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 7;  // sentinel preserved when rejected
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 7);
+}
+
+TEST_F(ContextPauseTtlEnvTest, NegativeIsIgnored) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "-1", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 11;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 11);
+}
+
+TEST_F(ContextPauseTtlEnvTest, NonNumericKeepsDefault) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "abc", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 13;  // a typo must NOT re-enable the latch
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 13);
+}
+
+TEST_F(ContextPauseTtlEnvTest, NumericSuffixKeepsDefault) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "5000s", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 15;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 15);
+}
+
+TEST_F(ContextPauseTtlEnvTest, EmptyStringKeepsDefault) {
+    ASSERT_EQ(::setenv("MC_CONTEXT_PAUSE_TTL_MS", "", 1), 0);
+    GlobalConfig config;
+    config.context_pause_ttl_ms = 17;
+    loadGlobalConfig(config);
+    EXPECT_EQ(config.context_pause_ttl_ms, 17);
+}
+
 }  // namespace
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/ctrl_frame_test.cpp b/mooncake-transfer-engine/tests/ctrl_frame_test.cpp
new file mode 100644
index 0000000000..7bad18ba77
--- /dev/null
+++ b/mooncake-transfer-engine/tests/ctrl_frame_test.cpp
@@ -0,0 +1,170 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstring>
+#include <vector>
+
+#include "error.h"
+#include "transport/rdma_twosided/ctrl_frame.h"
+
+using namespace mooncake;
+
+TEST(CtrlFrameTest, NotifyCompatRoundTrip) {
+    TransferMetadata::NotifyDesc in{"hello", "world"};
+    std::vector<uint8_t> payload;
+    ASSERT_EQ(encodeNotifyCompatPayload(in, payload), 0);
+
+    CtrlFrame frame;
+    frame.type = CtrlFrameType::NOTIFY_COMPAT;
+    frame.session = 42;
+    frame.epoch = 7;
+    frame.seq = 3;
+    frame.payload = payload;
+
+    std::vector<uint8_t> wired;
+    ASSERT_EQ(encodeCtrlFrame(frame, wired), 0);
+    EXPECT_TRUE(isCtrlFrameMagic(wired.data(), wired.size()));
+    EXPECT_EQ(wired.size(), kCtrlFrameHeaderSize + payload.size());
+
+    CtrlFrame out;
+    ASSERT_EQ(decodeCtrlFrame(wired.data(), wired.size(), out), 0);
+    EXPECT_EQ(out.type, CtrlFrameType::NOTIFY_COMPAT);
+    EXPECT_EQ(out.session, 42u);
+    EXPECT_EQ(out.epoch, 7u);
+    EXPECT_EQ(out.seq, 3u);
+
+    TransferMetadata::NotifyDesc decoded;
+    ASSERT_EQ(decodeNotifyCompatPayload(out.payload.data(), out.payload.size(),
+                                        decoded),
+              0);
+    EXPECT_EQ(decoded.name, "hello");
+    EXPECT_EQ(decoded.notify_msg, "world");
+}
+
+TEST(CtrlFrameTest, CreditGrantAndDataAckRoundTrip) {
+    std::vector<CreditAmount> grants = {
+        {CreditResource::BounceSlots, 64},
+        {CreditResource::BounceBytes, 64 * 65536},
+    };
+    std::vector<uint8_t> grant_payload;
+    ASSERT_EQ(encodeCreditGrantPayload(grants, grant_payload), 0);
+    std::vector<CreditAmount> grants_out;
+    ASSERT_EQ(decodeCreditGrantPayload(grant_payload.data(),
+                                       grant_payload.size(), grants_out),
+              0);
+    ASSERT_EQ(grants_out.size(), 2u);
+    EXPECT_EQ(grants_out[0].resource, CreditResource::BounceSlots);
+    EXPECT_EQ(grants_out[0].grant_total, 64u);
+
+    std::vector<DataAckEntry> acks = {{11, 100}, {12, 200}};
+    std::vector<uint8_t> ack_payload;
+    ASSERT_EQ(encodeDataAckPayload(acks, ack_payload), 0);
+    std::vector<DataAckEntry> acks_out;
+    ASSERT_EQ(
+        decodeDataAckPayload(ack_payload.data(), ack_payload.size(), acks_out),
+        0);
+    ASSERT_EQ(acks_out.size(), 2u);
+    EXPECT_EQ(acks_out[1].task_id, 12u);
+    EXPECT_EQ(acks_out[1].acked_bytes, 200u);
+}
+
+TEST(CtrlFrameTest, SessionOpenPayload) {
+    std::vector<uint8_t> payload;
+    ASSERT_EQ(encodeSessionOpenPayload(64, 65536 + 64, payload), 0);
+    uint32_t slots = 0, size = 0;
+    ASSERT_EQ(
+        decodeSessionOpenPayload(payload.data(), payload.size(), slots, size),
+        0);
+    EXPECT_EQ(slots, 64u);
+    EXPECT_EQ(size, 65536u + 64u);
+}
+
+TEST(CtrlFrameTest, RejectsBadMagic) {
+    std::vector<uint8_t> junk(kCtrlFrameHeaderSize, 0xAB);
+    CtrlFrame out;
+    EXPECT_NE(decodeCtrlFrame(junk.data(), junk.size(), out), 0);
+    EXPECT_FALSE(isCtrlFrameMagic(junk.data(), junk.size()));
+}
+
+TEST(CtrlFrameTest, RejectsUnsupportedVersionTypeFlagsAndTrailing) {
+    CtrlFrame frame;
+    frame.type = CtrlFrameType::SESSION_CLOSE;
+    frame.session = 1;
+    frame.epoch = 1;
+    frame.seq = 1;
+    std::vector<uint8_t> wired;
+    ASSERT_EQ(encodeCtrlFrame(frame, wired), 0);
+
+    // Trailing byte after an otherwise valid frame.
+    auto with_trail = wired;
+    with_trail.push_back(0xFF);
+    CtrlFrame out;
+    EXPECT_EQ(decodeCtrlFrame(with_trail.data(), with_trail.size(), out),
+              ERR_INVALID_ARGUMENT);
+
+    // Unsupported version.
+    auto bad_ver = wired;
+    bad_ver[4] = 99;  // version field
+    EXPECT_EQ(decodeCtrlFrame(bad_ver.data(), bad_ver.size(), out),
+              ERR_INVALID_ARGUMENT);
+
+    // Unknown type.
+    auto bad_type = wired;
+    bad_type[5] = 0xFE;
+    EXPECT_EQ(decodeCtrlFrame(bad_type.data(), bad_type.size(), out),
+              ERR_INVALID_ARGUMENT);
+
+    // Unknown flag bit.
+    auto bad_flags = wired;
+    uint16_t flags = 0x8000;
+    std::memcpy(bad_flags.data() + 6, &flags, sizeof(flags));
+    EXPECT_EQ(decodeCtrlFrame(bad_flags.data(), bad_flags.size(), out),
+              ERR_INVALID_ARGUMENT);
+}
+
+TEST(CtrlFrameTest, PayloadDecodersRejectTrailingAndPreserveOutputOnFailure) {
+    std::vector<uint8_t> grant_payload;
+    ASSERT_EQ(encodeCreditGrantPayload({{CreditResource::BounceSlots, 3}},
+                                       grant_payload),
+              0);
+    auto grant_trail = grant_payload;
+    grant_trail.push_back(0xAB);
+    std::vector<CreditAmount> grants = {{CreditResource::DataBytes, 42}};
+    EXPECT_EQ(decodeCreditGrantPayload(grant_trail.data(), grant_trail.size(),
+                                       grants),
+              ERR_INVALID_ARGUMENT);
+    ASSERT_EQ(grants.size(), 1u);
+    EXPECT_EQ(grants[0].resource, CreditResource::DataBytes);
+    EXPECT_EQ(grants[0].grant_total, 42u);
+
+    std::vector<uint8_t> session;
+    ASSERT_EQ(encodeSessionOpenPayload(1, 2, session), 0);
+    session.push_back(0);
+    uint32_t slots = 9, size = 9;
+    EXPECT_EQ(
+        decodeSessionOpenPayload(session.data(), session.size(), slots, size),
+        ERR_INVALID_ARGUMENT);
+    EXPECT_EQ(slots, 9u);
+    EXPECT_EQ(size, 9u);
+
+    // Inflated count must not reserve/parse before length check.
+    std::vector<uint8_t> tiny = {0xFF, 0xFF};  // count=65535, no entries
+    std::vector<DataAckEntry> acks = {{1, 2}};
+    EXPECT_EQ(decodeDataAckPayload(tiny.data(), tiny.size(), acks),
+              ERR_INVALID_ARGUMENT);
+    ASSERT_EQ(acks.size(), 1u);
+    EXPECT_EQ(acks[0].task_id, 1u);
+}
diff --git a/mooncake-transfer-engine/tests/cxl_transport_test.cpp b/mooncake-transfer-engine/tests/cxl_transport_test.cpp
index 2907535bf6..af404c13f9 100644
--- a/mooncake-transfer-engine/tests/cxl_transport_test.cpp
+++ b/mooncake-transfer-engine/tests/cxl_transport_test.cpp
@@ -230,7 +230,6 @@ TEST_F(CXLTransportTest, MultipleRead) {
 
         freeMemoryPool(src, kDataLength);
     }
-    engine->unregisterLocalMemory(addr);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/device_backend_api_compatibility_test.cu b/mooncake-transfer-engine/tests/device_backend_api_compatibility_test.cu
index 7485fa5748..ece0d8e36e 100644
--- a/mooncake-transfer-engine/tests/device_backend_api_compatibility_test.cu
+++ b/mooncake-transfer-engine/tests/device_backend_api_compatibility_test.cu
@@ -66,6 +66,27 @@ __global__ void instantiateNccl(NcclOps::Context ctx, int channel, int peer,
                                 void* destination, uint32_t bytes, int lane) {
     exchange<NcclOps>(ctx, channel, peer, qps_per_rank, source, destination,
                       bytes, lane);
+
+    auto* destination_bytes = static_cast<uint8_t*>(destination);
+    mc_nccl_put_value(ctx, channel, peer, qps_per_rank,
+                      reinterpret_cast<uint8_t*>(destination_bytes), uint8_t{1},
+                      lane);
+    mc_nccl_put_value(ctx, channel, peer, qps_per_rank,
+                      reinterpret_cast<uint16_t*>(destination_bytes),
+                      uint16_t{2}, lane);
+    mc_nccl_put_value(ctx, channel, peer, qps_per_rank,
+                      reinterpret_cast<uint32_t*>(destination_bytes),
+                      uint32_t{4}, lane);
+    mc_nccl_put_value(ctx, channel, peer, qps_per_rank,
+                      reinterpret_cast<uint64_t*>(destination_bytes),
+                      uint64_t{8}, lane);
+
+    auto* signal = reinterpret_cast<uint64_t*>(destination_bytes);
+    mc_nccl_gin_signal_add(ctx, peer, channel, qps_per_rank, signal, 1, lane);
+    const uint64_t observed = mc_nccl_gin_read_signal(ctx, channel, signal);
+    mc_nccl_gin_wait_signal(ctx, channel, signal, observed, lane);
+    const int context_count = mc_nccl_gin_context_count(ctx);
+    (void)context_count;
 }
 
 __global__ void instantiateIbgda(IbgdaOps::Context ctx, int channel, int peer,
diff --git a/mooncake-transfer-engine/tests/dmabuf_export_test.cpp b/mooncake-transfer-engine/tests/dmabuf_export_test.cpp
index 2e477a044d..0f8ec48232 100644
--- a/mooncake-transfer-engine/tests/dmabuf_export_test.cpp
+++ b/mooncake-transfer-engine/tests/dmabuf_export_test.cpp
@@ -110,7 +110,7 @@ TEST(CloseDmabufExport, Idempotent) {
 TEST(ExportDmabuf, HostMemoryYieldsHostReg) {
     std::vector<char> buf(4096);
     DmabufExport exp;
-    int ret = RdmaContext::exportDmabuf(buf.data(), exp);
+    int ret = RdmaContext::exportDmabuf(buf.data(), buf.size(), exp);
     EXPECT_EQ(ret, 0);
     EXPECT_EQ(exp.method, DmabufExport::Method::kHostReg);
     EXPECT_EQ(exp.fd, -1);
@@ -122,7 +122,7 @@ TEST(ExportDmabuf, LargeHostBufferYieldsHostReg) {
     constexpr size_t kSize = 8ULL * 1024 * 1024;  // 8 MiB
     std::vector<char> buf(kSize);
     DmabufExport exp;
-    int ret = RdmaContext::exportDmabuf(buf.data(), exp);
+    int ret = RdmaContext::exportDmabuf(buf.data(), kSize, exp);
     EXPECT_EQ(ret, 0);
     EXPECT_EQ(exp.method, DmabufExport::Method::kHostReg);
     EXPECT_EQ(exp.fd, -1);
@@ -134,7 +134,7 @@ TEST(ExportDmabuf, MmapAnonymousYieldsHostReg) {
     ASSERT_NE(p, MAP_FAILED);
 
     DmabufExport exp;
-    int ret = RdmaContext::exportDmabuf(p, exp);
+    int ret = RdmaContext::exportDmabuf(p, 4096, exp);
     EXPECT_EQ(ret, 0);
     EXPECT_EQ(exp.method, DmabufExport::Method::kHostReg);
     EXPECT_EQ(exp.fd, -1);
@@ -145,7 +145,7 @@ TEST(ExportDmabuf, MmapAnonymousYieldsHostReg) {
 TEST(ExportDmabuf, StackAddressYieldsHostReg) {
     char stack_buf[128];
     DmabufExport exp;
-    int ret = RdmaContext::exportDmabuf(stack_buf, exp);
+    int ret = RdmaContext::exportDmabuf(stack_buf, sizeof(stack_buf), exp);
     EXPECT_EQ(ret, 0);
     EXPECT_EQ(exp.method, DmabufExport::Method::kHostReg);
     EXPECT_EQ(exp.fd, -1);
diff --git a/mooncake-transfer-engine/tests/efa_gpu_loopback_test.cpp b/mooncake-transfer-engine/tests/efa_gpu_loopback_test.cpp
index a7735d7788..1269e9f03d 100644
--- a/mooncake-transfer-engine/tests/efa_gpu_loopback_test.cpp
+++ b/mooncake-transfer-engine/tests/efa_gpu_loopback_test.cpp
@@ -30,6 +30,7 @@
 // Requires EFA hardware (fi_info -p efa) AND at least one CUDA GPU.  Self-
 // skips cleanly when either is absent.
 
+#include <cuda.h>
 #include <cuda_runtime.h>
 #include <gflags/gflags.h>
 #include <glog/logging.h>
@@ -37,6 +38,8 @@
 
 #include <cstdlib>
 #include <memory>
+#include <string>
+#include <thread>
 #include <vector>
 
 #include "transfer_engine.h"
@@ -75,17 +78,19 @@ class EFAGpuLoopbackTest : public ::testing::Test {
         void *dev_buf = nullptr;  // CUDA device buffer
         size_t buffer_size = 0;
         SegmentID segment_id = 0;
+        bool registered = false;
         bool ok = false;
     };
 
     // Create engine, install EFA transport, allocate + register a CUDA
     // device buffer, and open our own segment for loopback.
-    EngineSetup createEngine(size_t buffer_size = 1ull << 26 /* 64 MB */) {
+    EngineSetup createEngine(int device_id = 0,
+                             size_t buffer_size = 1ull << 26 /* 64 MB */) {
         EngineSetup s;
         s.buffer_size = buffer_size;
 
-        if (cudaSetDevice(0) != cudaSuccess) {
-            LOG(WARNING) << "cudaSetDevice(0) failed";
+        if (cudaSetDevice(device_id) != cudaSuccess) {
+            LOG(WARNING) << "cudaSetDevice(" << device_id << ") failed";
             return s;
         }
 
@@ -108,9 +113,11 @@ class EFAGpuLoopbackTest : public ::testing::Test {
 
         // Register as GPU memory so the EFA transport tags the MR with
         // FI_HMEM_CUDA (the registration path under test).
-        rc = s.engine->registerLocalMemory(s.dev_buf, buffer_size, "cuda:0");
-        EXPECT_EQ(rc, 0) << "registerLocalMemory(cuda:0) failed";
+        std::string location = "cuda:" + std::to_string(device_id);
+        rc = s.engine->registerLocalMemory(s.dev_buf, buffer_size, location);
+        EXPECT_EQ(rc, 0) << "registerLocalMemory(" << location << ") failed";
         if (rc != 0) return s;
+        s.registered = true;
 
         auto actual_addr = s.engine->getLocalIpAndPort();
         s.segment_id = s.engine->openSegment(actual_addr);
@@ -119,8 +126,9 @@ class EFAGpuLoopbackTest : public ::testing::Test {
     }
 
     void destroyEngine(EngineSetup &s) {
-        if (s.engine && s.dev_buf) {
+        if (s.engine && s.dev_buf && s.registered) {
             s.engine->unregisterLocalMemory(s.dev_buf);
+            s.registered = false;
         }
         if (s.dev_buf) {
             cudaFree(s.dev_buf);
@@ -128,6 +136,17 @@ class EFAGpuLoopbackTest : public ::testing::Test {
         }
     }
 
+    class EngineCleanup {
+       public:
+        EngineCleanup(EFAGpuLoopbackTest *test, EngineSetup &setup)
+            : test_(test), setup_(setup) {}
+        ~EngineCleanup() { test_->destroyEngine(setup_); }
+
+       private:
+        EFAGpuLoopbackTest *test_;
+        EngineSetup &setup_;
+    };
+
     bool submitAndWait(TransferEngine *engine, SegmentID segment_id,
                        void *source, uint64_t target_offset, size_t length,
                        TransferRequest::OpCode opcode) {
@@ -173,6 +192,195 @@ class EFAGpuLoopbackTest : public ::testing::Test {
     std::string local_server_name_;
 };
 
+// A loopback copy submitted from a fresh thread must not activate GPU 0 or
+// leave a CUDA context current on the caller's thread.
+TEST_F(EFAGpuLoopbackTest, LoopbackPreservesEmptyCallerContext) {
+    int device_count = 0;
+    ASSERT_EQ(cudaGetDeviceCount(&device_count), cudaSuccess);
+    if (device_count < 2) GTEST_SKIP() << "At least two CUDA GPUs required";
+
+    CUdevice device_zero;
+    ASSERT_EQ(cuDeviceGet(&device_zero, 0), CUDA_SUCCESS);
+
+    auto setup = createEngine(1);
+    EngineCleanup cleanup(this, setup);
+    if (!setup.ok) GTEST_SKIP() << "EFA/CUDA setup unavailable";
+
+    unsigned int flags = 0;
+    int device_zero_active_before = 0;
+    ASSERT_EQ(cuDevicePrimaryCtxGetState(device_zero, &flags,
+                                         &device_zero_active_before),
+              CUDA_SUCCESS);
+
+    auto segment_desc =
+        setup.engine->getMetadata()->getSegmentDescByID(setup.segment_id);
+    ASSERT_NE(segment_desc, nullptr);
+    uint64_t remote_base = (uint64_t)segment_desc->buffers[0].addr;
+
+    const size_t kDataLength = 4096;
+    uint8_t *dev = (uint8_t *)setup.dev_buf;
+    const uint64_t destination = setup.buffer_size / 2;
+    ASSERT_EQ(cudaMemset(dev, 0xAB, kDataLength), cudaSuccess);
+    ASSERT_EQ(cudaMemset(dev + destination, 0, kDataLength), cudaSuccess);
+    ASSERT_EQ(cudaDeviceSynchronize(), cudaSuccess);
+
+    bool transfer_ok = false;
+    CUresult before_result = CUDA_ERROR_UNKNOWN;
+    CUresult after_result = CUDA_ERROR_UNKNOWN;
+    CUcontext before_context = nullptr;
+    CUcontext after_context = nullptr;
+    std::thread submitter([&] {
+        before_result = cuCtxGetCurrent(&before_context);
+        transfer_ok = submitAndWait(setup.engine.get(), setup.segment_id,
+                                    setup.dev_buf, remote_base + destination,
+                                    kDataLength, TransferRequest::WRITE);
+        after_result = cuCtxGetCurrent(&after_context);
+    });
+    submitter.join();
+
+    ASSERT_EQ(before_result, CUDA_SUCCESS);
+    ASSERT_EQ(before_context, nullptr);
+    ASSERT_TRUE(transfer_ok);
+    ASSERT_EQ(after_result, CUDA_SUCCESS);
+    EXPECT_EQ(after_context, before_context)
+        << "loopback copy changed the caller's CUDA context";
+
+    int device_zero_active_after = 0;
+    ASSERT_EQ(cuDevicePrimaryCtxGetState(device_zero, &flags,
+                                         &device_zero_active_after),
+              CUDA_SUCCESS);
+    if (!device_zero_active_before) {
+        EXPECT_EQ(device_zero_active_after, 0)
+            << "loopback copy activated CUDA device 0";
+    }
+
+    std::vector<uint8_t> readback(kDataLength);
+    ASSERT_EQ(cudaMemcpy(readback.data(), dev + destination, kDataLength,
+                         cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    std::vector<uint8_t> expected(kDataLength, 0xAB);
+    EXPECT_EQ(0, memcmp(readback.data(), expected.data(), kDataLength))
+        << "loopback copy did not produce the expected bytes";
+}
+
+// A loopback copy to another GPU must preserve an existing caller device so
+// subsequent CUDA work remains on the device selected by the application.
+TEST_F(EFAGpuLoopbackTest, LoopbackPreservesCallerDevice) {
+    int device_count = 0;
+    ASSERT_EQ(cudaGetDeviceCount(&device_count), cudaSuccess);
+    if (device_count < 2) GTEST_SKIP() << "At least two CUDA GPUs required";
+
+    auto setup = createEngine(1);
+    EngineCleanup cleanup(this, setup);
+    if (!setup.ok) GTEST_SKIP() << "EFA/CUDA setup unavailable";
+
+    auto segment_desc =
+        setup.engine->getMetadata()->getSegmentDescByID(setup.segment_id);
+    ASSERT_NE(segment_desc, nullptr);
+    uint64_t remote_base = (uint64_t)segment_desc->buffers[0].addr;
+
+    const size_t kDataLength = 4096;
+    ASSERT_EQ(cudaMemset(setup.dev_buf, 0xAB, kDataLength), cudaSuccess);
+
+    bool transfer_ok = false;
+    int device_before = -1;
+    int device_after = -1;
+    int allocation_device = -1;
+    cudaError_t set_result = cudaErrorUnknown;
+    cudaError_t before_result = cudaErrorUnknown;
+    cudaError_t after_result = cudaErrorUnknown;
+    cudaError_t allocation_result = cudaErrorUnknown;
+    cudaError_t attributes_result = cudaErrorUnknown;
+    cudaError_t free_result = cudaErrorUnknown;
+    std::thread submitter([&] {
+        set_result = cudaSetDevice(0);
+        before_result = cudaGetDevice(&device_before);
+        transfer_ok =
+            submitAndWait(setup.engine.get(), setup.segment_id, setup.dev_buf,
+                          remote_base + (setup.buffer_size / 2), kDataLength,
+                          TransferRequest::WRITE);
+        after_result = cudaGetDevice(&device_after);
+
+        void *probe = nullptr;
+        allocation_result = cudaMalloc(&probe, 1 << 20);
+        if (allocation_result == cudaSuccess) {
+            cudaPointerAttributes attributes;
+            attributes_result = cudaPointerGetAttributes(&attributes, probe);
+            if (attributes_result == cudaSuccess) {
+                allocation_device = attributes.device;
+            }
+            free_result = cudaFree(probe);
+        }
+    });
+    submitter.join();
+
+    ASSERT_EQ(set_result, cudaSuccess);
+    ASSERT_EQ(before_result, cudaSuccess);
+    ASSERT_TRUE(transfer_ok);
+    ASSERT_EQ(after_result, cudaSuccess);
+    EXPECT_EQ(device_after, device_before)
+        << "loopback copy changed the caller's CUDA device";
+    ASSERT_EQ(allocation_result, cudaSuccess);
+    ASSERT_EQ(attributes_result, cudaSuccess);
+    EXPECT_EQ(allocation_device, device_before)
+        << "subsequent allocation landed on the wrong GPU";
+    EXPECT_EQ(free_result, cudaSuccess);
+}
+
+// Loopback WRITE between buffers on two different GPUs.  The engine buffer
+// lives on GPU 1 and the source buffer on GPU 0, exercising the cross-device
+// cudaMemcpyDefault path.
+TEST_F(EFAGpuLoopbackTest, CrossDeviceLoopback) {
+    int device_count = 0;
+    ASSERT_EQ(cudaGetDeviceCount(&device_count), cudaSuccess);
+    if (device_count < 2) GTEST_SKIP() << "At least two CUDA GPUs required";
+
+    // Engine buffer on GPU 1.
+    auto setup = createEngine(1);
+    EngineCleanup cleanup(this, setup);
+    if (!setup.ok) GTEST_SKIP() << "EFA/CUDA setup unavailable";
+
+    auto segment_desc =
+        setup.engine->getMetadata()->getSegmentDescByID(setup.segment_id);
+    ASSERT_NE(segment_desc, nullptr);
+    uint64_t remote_base = (uint64_t)segment_desc->buffers[0].addr;
+
+    // Source buffer on GPU 0.
+    const size_t kDataLength = 4096;
+    ASSERT_EQ(cudaSetDevice(0), cudaSuccess);
+    void *dev0_buf = nullptr;
+    ASSERT_EQ(cudaMalloc(&dev0_buf, kDataLength), cudaSuccess);
+
+    std::vector<uint8_t> pattern(kDataLength);
+    for (size_t i = 0; i < kDataLength; ++i) pattern[i] = (uint8_t)(i ^ 0x3C);
+    ASSERT_EQ(cudaMemcpy(dev0_buf, pattern.data(), kDataLength,
+                         cudaMemcpyHostToDevice),
+              cudaSuccess);
+    ASSERT_EQ(cudaDeviceSynchronize(), cudaSuccess);
+
+    // Register the GPU 0 buffer with the engine.
+    int rc = setup.engine->registerLocalMemory(dev0_buf, kDataLength, "cuda:0");
+    ASSERT_EQ(rc, 0) << "registerLocalMemory(cuda:0) failed";
+
+    // WRITE: GPU 0 buffer -> second half of GPU 1 buffer.
+    const uint64_t dst_offset = setup.buffer_size / 2;
+    ASSERT_TRUE(submitAndWait(setup.engine.get(), setup.segment_id, dev0_buf,
+                              remote_base + dst_offset, kDataLength,
+                              TransferRequest::WRITE))
+        << "cross-device WRITE should succeed";
+
+    // Verify bytes landed on GPU 1.
+    std::vector<uint8_t> readback(kDataLength, 0xFF);
+    ASSERT_EQ(cudaMemcpy(readback.data(), (uint8_t *)setup.dev_buf + dst_offset,
+                         kDataLength, cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_EQ(0, memcmp(readback.data(), pattern.data(), kDataLength))
+        << "cross-device loopback did not produce the expected bytes";
+
+    setup.engine->unregisterLocalMemory(dev0_buf);
+    cudaFree(dev0_buf);
+}
+
 // Test 1: GPU loopback WRITE must not crash.
 //
 // Without the fix this segfaults inside the EFA provider's SHM path
diff --git a/mooncake-transfer-engine/tests/efa_large_mr_test.cpp b/mooncake-transfer-engine/tests/efa_large_mr_test.cpp
new file mode 100644
index 0000000000..e696a84e51
--- /dev/null
+++ b/mooncake-transfer-engine/tests/efa_large_mr_test.cpp
@@ -0,0 +1,237 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+// Regression test for issue #3501: a transfer that straddles a BufferDesc chunk
+// boundary must be split at that boundary instead of failing.
+//
+// EfaTransport::registerLocalMemoryInternal() already splits a buffer larger
+// than min(max_mr_size, per-NIC PTE budget) into several chunks and publishes
+// one BufferDesc per chunk (the EFA counterpart of #2644). Submission, however,
+// posted exactly one slice per request and EfaTransport::selectDevice() only
+// accepts a buffer that contains the WHOLE request, so any read/write crossing
+// a seam died with ERR_ADDRESS_NOT_REGISTERED (source side) or "Cannot select
+// device for dest_addr" (target side) -- which is why the Store had to keep
+// splitting EFA segments in GetTransportRegistrationLimit().
+//
+// This forces the condition at a small, hardware-independent size via
+// MC_MAX_MR_SIZE, then runs loopback transfers that cross the first seam.
+//
+// Needs EFA hardware, and MC_MAX_MR_SIZE must be set before the process starts
+// (globalConfig() reads it once):
+//
+//   MC_MAX_MR_SIZE=67108864 ./efa_large_mr_test
+//
+// Not registered with add_test() for that reason, same as rdma_large_mr_test.
+
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <string>
+
+#include "config.h"
+#include "transfer_engine.h"
+#include "transport/transport.h"
+
+using namespace mooncake;
+
+namespace mooncake {
+
+// Small max_mr_size so the multi-chunk path is exercised without a multi-GB
+// allocation. 256 MiB / 64 MiB = 4 chunks.
+static constexpr size_t kMaxMrSize = 64ull << 20;
+static constexpr size_t kBufferSize = 256ull << 20;
+static constexpr size_t kExpectedChunks = kBufferSize / kMaxMrSize;
+static constexpr size_t kDataLength = 1ull << 20;
+
+class EFALargeMrTest : public ::testing::Test {
+   protected:
+    std::unique_ptr<TransferEngine> engine;
+    void *addr = nullptr;
+    SegmentID segment_id = 0;
+
+    void SetUp() override {
+        const char *env = std::getenv("MC_METADATA_SERVER");
+        std::string metadata_server = env ? env : "P2PHANDSHAKE";
+        env = std::getenv("MC_LOCAL_SERVER_NAME");
+        std::string local_server_name = env ? env : "127.0.0.1:12345";
+
+        ASSERT_EQ(globalConfig().max_mr_size, kMaxMrSize)
+            << "Launch this test process with MC_MAX_MR_SIZE=" << kMaxMrSize;
+
+        engine = std::make_unique<TransferEngine>(false);
+        // Manually discover the topology to populate the EFA device list, same
+        // pattern as efa_transport_test.
+        engine->getLocalTopology()->discover({});
+        auto hp = parseHostNameWithPort(local_server_name);
+        ASSERT_EQ(engine->init(metadata_server, local_server_name,
+                               hp.first.c_str(), hp.second),
+                  0);
+        ASSERT_NE(engine->installTransport("efa", nullptr), nullptr)
+            << "installTransport(\"efa\") failed -- EFA hardware required";
+
+        addr = numa_alloc_onnode(kBufferSize, 0);
+        ASSERT_NE(addr, nullptr);
+        ASSERT_EQ(engine->registerLocalMemory(addr, kBufferSize, "cpu:0"), 0);
+
+        segment_id = engine->openSegment(engine->getLocalIpAndPort());
+        auto desc = engine->getMetadata()->getSegmentDescByID(segment_id);
+        ASSERT_NE(desc, nullptr);
+        // The premise of every case below: the registration really did split.
+        size_t chunks = 0;
+        for (const auto &buffer : desc->buffers) {
+            if (buffer.addr >= (uint64_t)addr &&
+                buffer.addr < (uint64_t)addr + kBufferSize) {
+                EXPECT_LE(buffer.length, kMaxMrSize);
+                ++chunks;
+            }
+        }
+        ASSERT_EQ(chunks, kExpectedChunks)
+            << "buffer was not auto-split into " << kExpectedChunks
+            << " chunks; the straddle cases below would be vacuous";
+    }
+
+    void TearDown() override {
+        if (engine && addr) engine->unregisterLocalMemory(addr);
+        if (addr) numa_free(addr, kBufferSize);
+    }
+
+    // Submit one request and poll to a terminal state.
+    TransferStatusEnum submitAndWait(void *source, uint64_t target_offset,
+                                     size_t length,
+                                     TransferRequest::OpCode opcode) {
+        auto batch_id = engine->allocateBatchID(1);
+        TransferRequest entry;
+        entry.opcode = opcode;
+        entry.length = length;
+        entry.source = (uint8_t *)source;
+        entry.target_id = segment_id;
+        entry.target_offset = target_offset;
+
+        Status s = engine->submitTransfer(batch_id, {entry});
+        if (!s.ok()) {
+            LOG(ERROR) << "submitTransfer failed: " << s.ToString();
+            engine->freeBatchID(batch_id);
+            return TransferStatusEnum::FAILED;
+        }
+
+        const int kMaxPollIterations = 10000000;
+        TransferStatus status;
+        status.s = TransferStatusEnum::WAITING;
+        for (int i = 0; i < kMaxPollIterations; ++i) {
+            if (!engine->getTransferStatus(batch_id, 0, status).ok()) {
+                engine->freeBatchID(batch_id);
+                return TransferStatusEnum::FAILED;
+            }
+            if (status.s != TransferStatusEnum::WAITING) break;
+        }
+        engine->freeBatchID(batch_id);
+        return status.s;
+    }
+
+    void fillSource(size_t offset) {
+        for (size_t i = 0; i < kDataLength; ++i)
+            *((char *)addr + offset + i) = (char)('a' + (lrand48() % 26));
+    }
+};
+
+// Baseline: the target lands past the first chunk but inside a single later
+// chunk. This already worked (each chunk is its own MR with its own key) and
+// guards against a regression in the non-straddling multi-chunk path.
+TEST_F(EFALargeMrTest, WritePastFirstChunk) {
+    const size_t kTargetOffset = kBufferSize - kDataLength;  // chunk 3
+    ASSERT_GT(kTargetOffset, kMaxMrSize);
+
+    fillSource(0);
+    memset((char *)addr + kTargetOffset, 0, kDataLength);
+
+    ASSERT_EQ(submitAndWait(addr, (uint64_t)addr + kTargetOffset, kDataLength,
+                            TransferRequest::WRITE),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_EQ(0, memcmp(addr, (char *)addr + kTargetOffset, kDataLength));
+}
+
+// The TARGET range straddles the seam between chunk 0 and chunk 1. Pre-fix the
+// peer-side selectDevice() in EfaContext::submitPostSend() finds no single
+// BufferDesc covering the whole range and the transfer is marked FAILED.
+TEST_F(EFALargeMrTest, WriteStraddlesChunkBoundary) {
+    const size_t kTargetOffset = kMaxMrSize - kDataLength / 2 + 1;
+    ASSERT_LT(kTargetOffset, kMaxMrSize);                // starts in chunk 0
+    ASSERT_GT(kTargetOffset + kDataLength, kMaxMrSize);  // ends in chunk 1
+
+    fillSource(0);
+    memset((char *)addr + kTargetOffset, 0, kDataLength);
+
+    ASSERT_EQ(submitAndWait(addr, (uint64_t)addr + kTargetOffset, kDataLength,
+                            TransferRequest::WRITE),
+              TransferStatusEnum::COMPLETED)
+        << "EFA WRITE straddling a chunk boundary failed -- the request was "
+           "not split at the seam (issue #3501)";
+    ASSERT_EQ(0, memcmp(addr, (char *)addr + kTargetOffset, kDataLength));
+}
+
+// The SOURCE range straddles the seam. Pre-fix EfaTransport::submitTransferTask
+// rejects the request outright with ERR_ADDRESS_NOT_REGISTERED.
+TEST_F(EFALargeMrTest, WriteWithSourceStraddlingChunkBoundary) {
+    const size_t kSourceOffset = kMaxMrSize - kDataLength / 2 + 1;
+    const size_t kTargetOffset = 2 * kMaxMrSize;
+
+    fillSource(kSourceOffset);
+    memset((char *)addr + kTargetOffset, 0, kDataLength);
+
+    ASSERT_EQ(submitAndWait((char *)addr + kSourceOffset,
+                            (uint64_t)addr + kTargetOffset, kDataLength,
+                            TransferRequest::WRITE),
+              TransferStatusEnum::COMPLETED)
+        << "EFA WRITE with a source straddling a chunk boundary failed "
+           "(issue #3501)";
+    ASSERT_EQ(0, memcmp((char *)addr + kSourceOffset,
+                        (char *)addr + kTargetOffset, kDataLength));
+}
+
+// Same seam, opposite direction: READ pulls from a remote range that straddles
+// the boundary into a local range that straddles the NEXT one, so both sides
+// have to be cut.
+TEST_F(EFALargeMrTest, ReadStraddlesChunkBoundaryOnBothSides) {
+    const size_t kRemoteOffset = kMaxMrSize - kDataLength / 2 + 1;
+    const size_t kLocalOffset = 2 * kMaxMrSize - kDataLength / 2 + 1;
+
+    fillSource(kRemoteOffset);
+    memset((char *)addr + kLocalOffset, 0, kDataLength);
+
+    ASSERT_EQ(submitAndWait((char *)addr + kLocalOffset,
+                            (uint64_t)addr + kRemoteOffset, kDataLength,
+                            TransferRequest::READ),
+              TransferStatusEnum::COMPLETED)
+        << "EFA READ straddling a chunk boundary failed (issue #3501)";
+    ASSERT_EQ(0, memcmp((char *)addr + kLocalOffset,
+                        (char *)addr + kRemoteOffset, kDataLength));
+}
+
+}  // namespace mooncake
+
+int main(int argc, char **argv) {
+    gflags::ParseCommandLineFlags(&argc, &argv, false);
+    // Once for the whole binary -- calling InitGoogleLogging() per-test in
+    // SetUp() aborts on the 2nd TEST_F.
+    google::InitGoogleLogging(argv[0]);
+    FLAGS_logtostderr = 1;
+    ::testing::InitGoogleTest(&argc, argv);
+    int rc = RUN_ALL_TESTS();
+    google::ShutdownGoogleLogging();
+    return rc;
+}
diff --git a/mooncake-transfer-engine/tests/endpoint_store_test.cpp b/mooncake-transfer-engine/tests/endpoint_store_test.cpp
index 5f3b121656..8225a9ac93 100644
--- a/mooncake-transfer-engine/tests/endpoint_store_test.cpp
+++ b/mooncake-transfer-engine/tests/endpoint_store_test.cpp
@@ -20,6 +20,8 @@
 #include <gtest/gtest.h>
 
 #include <memory>
+#include <string>
+#include <vector>
 
 #include "transport/rdma_transport/endpoint_store.h"
 #include "transport/rdma_transport/rdma_context.h"
@@ -175,4 +177,38 @@ TEST_F(EndpointStoreTest, ReclaimDoesNotRequireActiveMap) {
     EXPECT_EQ(store.waitingListSize(), 0u);
 }
 
+TEST_F(EndpointStoreTest,
+       StaleRawPointerLookupAndDeleteStressDoesNotDereference) {
+    SIEVEEndpointStore store(4);
+    auto sentinel = makeQuiescentEndpoint(*ctx_);
+    std::vector<RdmaEndPoint*> stale_ptrs;
+    stale_ptrs.reserve(1000);
+
+    for (size_t i = 0; i < 1000; ++i) {
+        auto endpoint = makeQuiescentEndpoint(*ctx_);
+        const std::string peer_nic_path = "peer@" + std::to_string(i);
+        store.testOnlyInsertEndpoint(peer_nic_path, endpoint);
+        stale_ptrs.push_back(endpoint.get());
+        EXPECT_EQ(endpoint, store.getEndpointByPtr(endpoint.get()));
+        EXPECT_EQ(0, store.deleteEndpointByPtr(endpoint.get()));
+    }
+
+    EXPECT_EQ(store.getSize(), 0u);
+    EXPECT_EQ(store.waitingListSize(), 1000u);
+    store.testOnlyInsertEndpoint("sentinel@peer", sentinel);
+    store.reclaimEndpoint();
+    EXPECT_EQ(store.waitingListSize(), 0u);
+    EXPECT_EQ(store.getSize(), 1u);
+
+    // The endpoints were live in the store, deleted by raw pointer, then
+    // reclaimed. The raw pointers are now stale while the sentinel keeps the
+    // active map non-empty. Store APIs must compare pointer identity only;
+    // dereferencing would be caught by ASan builds.
+    for (auto* stale_ptr : stale_ptrs) {
+        EXPECT_EQ(nullptr, store.getEndpointByPtr(stale_ptr));
+        EXPECT_EQ(-1, store.deleteEndpointByPtr(stale_ptr));
+    }
+    EXPECT_EQ(sentinel, store.getEndpointByPtr(sentinel.get()));
+}
+
 }  // namespace
diff --git a/mooncake-transfer-engine/tests/flagcx_transport_internal_test.cpp b/mooncake-transfer-engine/tests/flagcx_transport_internal_test.cpp
new file mode 100644
index 0000000000..411ef0178d
--- /dev/null
+++ b/mooncake-transfer-engine/tests/flagcx_transport_internal_test.cpp
@@ -0,0 +1,53 @@
+// Copyright 2026 KVCache.AI
+//
+// 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
+
+#include "flagcx_transport_internal.h"
+
+#include <gtest/gtest.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+
+namespace mooncake::flagcx_internal {
+namespace {
+
+TEST(FlagCxTransportInternalTest, ContainsRangeAcceptsContainedRanges) {
+    EXPECT_TRUE(containsRange(100, 64, 100, 64));
+    EXPECT_TRUE(containsRange(100, 64, 116, 32));
+    EXPECT_TRUE(containsRange(100, 64, 164, 0));
+}
+
+TEST(FlagCxTransportInternalTest, ContainsRangeRejectsOutsideRanges) {
+    EXPECT_FALSE(containsRange(100, 64, 99, 1));
+    EXPECT_FALSE(containsRange(100, 64, 116, 49));
+    EXPECT_FALSE(containsRange(100, 64, 165, 0));
+}
+
+TEST(FlagCxTransportInternalTest, ContainsRangeDoesNotOverflow) {
+    constexpr uintptr_t kMax = std::numeric_limits<uintptr_t>::max();
+    EXPECT_TRUE(containsRange(kMax - 7, 7, kMax - 3, 3));
+    EXPECT_FALSE(containsRange(kMax - 7, 7, kMax - 3, 4));
+}
+
+TEST(FlagCxTransportInternalTest, DescriptorLengthCapsWithoutWrapping) {
+    constexpr size_t kMaxDescriptor = std::numeric_limits<uint32_t>::max();
+    EXPECT_EQ(descriptorLength(0), 0u);
+    EXPECT_EQ(descriptorLength(1024), 1024u);
+    EXPECT_EQ(descriptorLength(kMaxDescriptor),
+              std::numeric_limits<uint32_t>::max());
+    if constexpr (std::numeric_limits<size_t>::max() > kMaxDescriptor) {
+        EXPECT_EQ(descriptorLength(kMaxDescriptor + 1),
+                  std::numeric_limits<uint32_t>::max());
+        EXPECT_EQ(descriptorLength(std::numeric_limits<size_t>::max()),
+                  std::numeric_limits<uint32_t>::max());
+    }
+}
+
+}  // namespace
+}  // namespace mooncake::flagcx_internal
diff --git a/mooncake-transfer-engine/tests/glog_preinitialized_test.cpp b/mooncake-transfer-engine/tests/glog_preinitialized_test.cpp
new file mode 100644
index 0000000000..3e2129abc3
--- /dev/null
+++ b/mooncake-transfer-engine/tests/glog_preinitialized_test.cpp
@@ -0,0 +1,81 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+
+#include "config.h"
+
+// MOONCAKE_GLOG_HAS_IS_INITIALIZED is provided by FindGLOG.cmake through the
+// glog::glog INTERFACE compile definitions. It is 1 only when glog >= 0.6.0,
+// where google::IsGoogleLoggingInitialized() is publicly exported at the top
+// level. On older glog versions the same function is available in the internal
+// namespace google::glog_internal_namespace_, so we forward-declare it below to
+// exercise the exact same behavior this test verifies in config.cpp.
+#ifndef MOONCAKE_GLOG_HAS_IS_INITIALIZED
+#define MOONCAKE_GLOG_HAS_IS_INITIALIZED 0
+#endif
+
+#if !MOONCAKE_GLOG_HAS_IS_INITIALIZED
+// See config.cpp for the rationale: glog < 0.6.0 keeps this function in the
+// internal namespace; the symbol is exported by libglog, so we forward-declare
+// it here instead of depending on glog's private, non-installed utilities.h.
+namespace google {
+namespace glog_internal_namespace_ {
+bool IsGoogleLoggingInitialized();
+}  // namespace glog_internal_namespace_
+}  // namespace google
+#endif
+
+namespace mooncake {
+namespace {
+
+// Version-agnostic wrapper resolving to the correct glog symbol.
+inline bool testGlogInitialized() {
+#if MOONCAKE_GLOG_HAS_IS_INITIALIZED
+    return google::IsGoogleLoggingInitialized();
+#else
+    return google::glog_internal_namespace_::IsGoogleLoggingInitialized();
+#endif
+}
+
+class GlogPreinitializedTest : public ::testing::Test {
+   protected:
+    void TearDown() override {
+        ::unsetenv("MC_LOG_DIR");
+        if (testGlogInitialized()) {
+            google::ShutdownGoogleLogging();
+        }
+    }
+};
+
+TEST_F(GlogPreinitializedTest, LoadGlobalConfigReusesHostLogging) {
+    // Simulate the caller (host program) having already initialized glog.
+    google::InitGoogleLogging("glog-preinitialized-test");
+    ASSERT_TRUE(testGlogInitialized());
+    ASSERT_EQ(::setenv("MC_LOG_DIR", ".", 1), 0);
+
+    GlobalConfig config;
+    loadGlobalConfig(config);
+
+    // loadGlobalConfig must detect the pre-initialized state and reuse it
+    // rather than re-initializing glog.
+    EXPECT_TRUE(testGlogInitialized());
+    EXPECT_EQ(FLAGS_log_dir, ".");
+}
+
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/graceful_shutdown_test.cpp b/mooncake-transfer-engine/tests/graceful_shutdown_test.cpp
index f0741c82bf..8d8c320002 100644
--- a/mooncake-transfer-engine/tests/graceful_shutdown_test.cpp
+++ b/mooncake-transfer-engine/tests/graceful_shutdown_test.cpp
@@ -13,72 +13,228 @@
 // limitations under the License.
 
 #include <gtest/gtest.h>
+#include <poll.h>
 #include <signal.h>
+#include <spawn.h>
 #include <sys/wait.h>
 #include <unistd.h>
 
+#include <cerrno>
+#include <chrono>
+#include <climits>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
 #include <memory>
 
 #include "transfer_engine.h"
 
+extern char** environ;
+
 using namespace mooncake;
 
 namespace {
 
-void waitChildWithTimeout(pid_t pid, int* status) {
-    for (int i = 0; i < 50; ++i) {
-        pid_t ret = waitpid(pid, status, WNOHANG);
-        ASSERT_NE(ret, -1) << "waitpid() failed";
-        if (ret == pid) return;
-        usleep(100000);
+constexpr char kChildFlag[] = "--graceful-shutdown-child";
+constexpr int kChildTimeoutMs = 5000;
+
+enum class ChildMode { kSingle, kDestroyed, kMultiple };
+
+const char* childModeName(ChildMode mode) {
+    switch (mode) {
+        case ChildMode::kSingle:
+            return "single";
+        case ChildMode::kDestroyed:
+            return "destroyed";
+        case ChildMode::kMultiple:
+            return "multiple";
     }
-    kill(pid, SIGKILL);
-    waitpid(pid, status, 0);
-    FAIL() << "child did not exit before timeout";
+    return "unknown";
 }
 
-}  // namespace
+bool parseChildMode(const char* value, ChildMode* mode) {
+    if (strcmp(value, "single") == 0) {
+        *mode = ChildMode::kSingle;
+    } else if (strcmp(value, "destroyed") == 0) {
+        *mode = ChildMode::kDestroyed;
+    } else if (strcmp(value, "multiple") == 0) {
+        *mode = ChildMode::kMultiple;
+    } else {
+        return false;
+    }
+    return true;
+}
 
-TEST(GracefulShutdownTest, SigtermTriggersCleanExit) {
-    pid_t pid = fork();
-    ASSERT_NE(pid, -1) << "fork() failed";
+int runShutdownChild(ChildMode mode, int ready_fd) {
+    std::unique_ptr<TransferEngine> engine1;
+    std::unique_ptr<TransferEngine> engine2;
 
-    if (pid == 0) {
+    if (mode == ChildMode::kDestroyed) {
         auto engine = std::make_unique<TransferEngine>(false);
         engine->enableGracefulShutdown();
-        pause();
-        _exit(99);
+    } else {
+        engine1 = std::make_unique<TransferEngine>(false);
+        engine1->enableGracefulShutdown();
+        if (mode == ChildMode::kMultiple) {
+            engine2 = std::make_unique<TransferEngine>(false);
+            engine2->enableGracefulShutdown();
+        }
+    }
+
+    const char ready = '1';
+    ssize_t bytes_written;
+    do {
+        bytes_written = write(ready_fd, &ready, sizeof(ready));
+    } while (bytes_written < 0 && errno == EINTR);
+    if (bytes_written != static_cast<ssize_t>(sizeof(ready))) return 111;
+    close(ready_fd);
+    for (;;) pause();
+}
+
+void killAndReap(pid_t pid) {
+    if (kill(pid, SIGKILL) != 0 && errno != ESRCH) {
+        ADD_FAILURE() << "kill(SIGKILL) failed: " << strerror(errno);
+    }
+
+    int status = 0;
+    pid_t ret;
+    do {
+        ret = waitpid(pid, &status, 0);
+    } while (ret < 0 && errno == EINTR);
+    if (ret < 0) {
+        ADD_FAILURE() << "waitpid() failed while reaping child: "
+                      << strerror(errno);
+    }
+}
+
+bool waitChildWithTimeout(pid_t pid, int* status) {
+    auto deadline = std::chrono::steady_clock::now() +
+                    std::chrono::milliseconds(kChildTimeoutMs);
+    for (;;) {
+        pid_t ret = waitpid(pid, status, WNOHANG);
+        if (ret == pid) return true;
+        if (ret < 0) {
+            if (errno == EINTR) continue;
+            int error = errno;
+            if (error != ECHILD) killAndReap(pid);
+            ADD_FAILURE() << "waitpid() failed: " << strerror(error);
+            return false;
+        }
+        if (std::chrono::steady_clock::now() >= deadline) break;
+        usleep(100000);
+    }
+
+    killAndReap(pid);
+    ADD_FAILURE() << "child did not exit before timeout";
+    return false;
+}
+
+bool waitForChildReady(int fd) {
+    pollfd pfd{fd, POLLIN, 0};
+    auto deadline = std::chrono::steady_clock::now() +
+                    std::chrono::milliseconds(kChildTimeoutMs);
+    int ret;
+    for (;;) {
+        auto remaining = std::chrono::duration_cast<std::chrono::milliseconds>(
+                             deadline - std::chrono::steady_clock::now())
+                             .count();
+        if (remaining <= 0) {
+            ret = 0;
+            break;
+        }
+        ret = poll(&pfd, 1, static_cast<int>(remaining));
+        if (ret >= 0 || errno != EINTR) break;
+    }
+
+    if (ret == 0) {
+        ADD_FAILURE() << "child did not report readiness before timeout";
+        return false;
+    }
+    if (ret < 0) {
+        ADD_FAILURE() << "poll() failed: " << strerror(errno);
+        return false;
+    }
+
+    char ready = 0;
+    ssize_t bytes_read;
+    do {
+        bytes_read = read(fd, &ready, sizeof(ready));
+    } while (bytes_read < 0 && errno == EINTR);
+    if (bytes_read == 0) {
+        ADD_FAILURE() << "child exited before reporting readiness";
+        return false;
+    }
+    if (bytes_read < 0) {
+        ADD_FAILURE() << "read() failed while waiting for readiness: "
+                      << strerror(errno);
+        return false;
+    }
+    if (ready != '1') {
+        ADD_FAILURE() << "unexpected readiness marker: "
+                      << static_cast<int>(static_cast<unsigned char>(ready));
+        return false;
+    }
+    return true;
+}
+
+pid_t spawnReadyChild(ChildMode mode) {
+    int ready_pipe[2];
+    if (pipe(ready_pipe) != 0) {
+        ADD_FAILURE() << "pipe() failed: " << strerror(errno);
+        return -1;
+    }
+
+    char ready_fd[32];
+    snprintf(ready_fd, sizeof(ready_fd), "%d", ready_pipe[1]);
+    char* child_argv[] = {
+        const_cast<char*>("/proc/self/exe"), const_cast<char*>(kChildFlag),
+        const_cast<char*>(childModeName(mode)), ready_fd, nullptr};
+
+    pid_t pid = -1;
+    int spawn_error = posix_spawn(&pid, "/proc/self/exe", nullptr, nullptr,
+                                  child_argv, environ);
+    close(ready_pipe[1]);
+    if (spawn_error != 0) {
+        close(ready_pipe[0]);
+        ADD_FAILURE() << "posix_spawn() failed: " << strerror(spawn_error);
+        return -1;
+    }
+
+    bool ready = waitForChildReady(ready_pipe[0]);
+    close(ready_pipe[0]);
+    if (!ready) {
+        killAndReap(pid);
+        return -1;
     }
+    return pid;
+}
 
-    usleep(100000);
-    kill(pid, SIGTERM);
+void expectGracefulExit(ChildMode mode, int signo) {
+    pid_t pid = spawnReadyChild(mode);
+    ASSERT_GT(pid, 0);
 
-    int status;
-    waitChildWithTimeout(pid, &status);
+    if (kill(pid, signo) != 0) {
+        int error = errno;
+        killAndReap(pid);
+        FAIL() << "kill(" << signo << ") failed: " << strerror(error);
+    }
+
+    int status = 0;
+    ASSERT_TRUE(waitChildWithTimeout(pid, &status));
     ASSERT_TRUE(WIFEXITED(status))
         << "Child did not exit normally (signaled: " << WIFSIGNALED(status)
         << ")";
-    EXPECT_EQ(WEXITSTATUS(status), 128 + SIGTERM);
+    EXPECT_EQ(WEXITSTATUS(status), 128 + signo);
 }
 
-TEST(GracefulShutdownTest, SigintTriggersCleanExit) {
-    pid_t pid = fork();
-    ASSERT_NE(pid, -1) << "fork() failed";
-
-    if (pid == 0) {
-        auto engine = std::make_unique<TransferEngine>(false);
-        engine->enableGracefulShutdown();
-        pause();
-        _exit(99);
-    }
+}  // namespace
 
-    usleep(100000);
-    kill(pid, SIGINT);
+TEST(GracefulShutdownTest, SigtermTriggersCleanExit) {
+    expectGracefulExit(ChildMode::kSingle, SIGTERM);
+}
 
-    int status;
-    waitChildWithTimeout(pid, &status);
-    ASSERT_TRUE(WIFEXITED(status)) << "Child did not exit normally";
-    EXPECT_EQ(WEXITSTATUS(status), 128 + SIGINT);
+TEST(GracefulShutdownTest, SigintTriggersCleanExit) {
+    expectGracefulExit(ChildMode::kSingle, SIGINT);
 }
 
 TEST(GracefulShutdownTest, IdempotentEnable) {
@@ -89,25 +245,7 @@ TEST(GracefulShutdownTest, IdempotentEnable) {
 }
 
 TEST(GracefulShutdownTest, EngineDestroyedBeforeSignal) {
-    pid_t pid = fork();
-    ASSERT_NE(pid, -1) << "fork() failed";
-
-    if (pid == 0) {
-        {
-            auto engine = std::make_unique<TransferEngine>(false);
-            engine->enableGracefulShutdown();
-        }
-        pause();
-        _exit(99);
-    }
-
-    usleep(100000);
-    kill(pid, SIGTERM);
-
-    int status;
-    waitChildWithTimeout(pid, &status);
-    ASSERT_TRUE(WIFEXITED(status));
-    EXPECT_EQ(WEXITSTATUS(status), 128 + SIGTERM);
+    expectGracefulExit(ChildMode::kDestroyed, SIGTERM);
 }
 
 TEST(GracefulShutdownTest, ForkAfterInstallDoesNotHangChildSignal) {
@@ -118,15 +256,17 @@ TEST(GracefulShutdownTest, ForkAfterInstallDoesNotHangChildSignal) {
     ASSERT_NE(pid, -1) << "fork() failed";
 
     if (pid == 0) {
-        pause();
-        _exit(99);
+        for (;;) pause();
     }
 
-    usleep(100000);
-    kill(pid, SIGTERM);
+    if (kill(pid, SIGTERM) != 0) {
+        int error = errno;
+        killAndReap(pid);
+        FAIL() << "kill(SIGTERM) failed: " << strerror(error);
+    }
 
-    int status;
-    waitChildWithTimeout(pid, &status);
+    int status = 0;
+    ASSERT_TRUE(waitChildWithTimeout(pid, &status));
     ASSERT_TRUE(WIFEXITED(status))
         << "Child did not exit normally (signaled: " << WIFSIGNALED(status)
         << ")";
@@ -134,23 +274,22 @@ TEST(GracefulShutdownTest, ForkAfterInstallDoesNotHangChildSignal) {
 }
 
 TEST(GracefulShutdownTest, MultipleEngines) {
-    pid_t pid = fork();
-    ASSERT_NE(pid, -1) << "fork() failed";
+    expectGracefulExit(ChildMode::kMultiple, SIGTERM);
+}
 
-    if (pid == 0) {
-        auto engine1 = std::make_unique<TransferEngine>(false);
-        auto engine2 = std::make_unique<TransferEngine>(false);
-        engine1->enableGracefulShutdown();
-        engine2->enableGracefulShutdown();
-        pause();
-        _exit(99);
+int main(int argc, char** argv) {
+    if (argc == 4 && strcmp(argv[1], kChildFlag) == 0) {
+        ChildMode mode;
+        char* end = nullptr;
+        errno = 0;
+        long ready_fd = strtol(argv[3], &end, 10);
+        if (!parseChildMode(argv[2], &mode) || errno != 0 || *end != '\0' ||
+            ready_fd < 0 || ready_fd > INT_MAX) {
+            return 2;
+        }
+        return runShutdownChild(mode, static_cast<int>(ready_fd));
     }
 
-    usleep(100000);
-    kill(pid, SIGTERM);
-
-    int status;
-    waitChildWithTimeout(pid, &status);
-    ASSERT_TRUE(WIFEXITED(status));
-    EXPECT_EQ(WEXITSTATUS(status), 128 + SIGTERM);
+    testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
 }
diff --git a/mooncake-transfer-engine/tests/multi_transport_batch_test.cpp b/mooncake-transfer-engine/tests/multi_transport_batch_test.cpp
new file mode 100644
index 0000000000..0078bb563e
--- /dev/null
+++ b/mooncake-transfer-engine/tests/multi_transport_batch_test.cpp
@@ -0,0 +1,175 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include "common.h"
+#include "config.h"
+#include "multi_transport.h"
+#include "transfer_metadata.h"
+
+namespace mooncake {
+class MultiTransportBatchTestPeer {
+   public:
+    static void install(MultiTransport &multi, const std::string &name,
+                        std::shared_ptr<Transport> transport) {
+        multi.transport_map_[name] = std::move(transport);
+    }
+};
+namespace {
+class RecordingTransport : public Transport {
+   public:
+    std::vector<uint64_t> addresses;
+    Status submitTransfer(BatchID,
+                          const std::vector<TransferRequest> &) override {
+        return Status::OK();
+    }
+    Status submitTransferTask(
+        const std::vector<TransferTask *> &tasks) override {
+        for (auto *task : tasks) {
+            addresses.push_back(task->request->target_offset);
+            task->is_finished = true;
+        }
+        return Status::OK();
+    }
+    Status getTransferStatus(BatchID, size_t, TransferStatus &) override {
+        return Status::OK();
+    }
+
+   private:
+    int registerLocalMemory(void *, size_t, const std::string &, bool,
+                            bool) override {
+        return 0;
+    }
+    int unregisterLocalMemory(void *, bool) override { return 0; }
+    int registerLocalMemoryBatch(const std::vector<BufferEntry> &,
+                                 const std::string &) override {
+        return 0;
+    }
+    int unregisterLocalMemoryBatch(const std::vector<void *> &) override {
+        return 0;
+    }
+    const char *getName() const override { return "recording"; }
+};
+struct ScopedMetacache {
+    bool old;
+    explicit ScopedMetacache(bool enabled) : old(globalConfig().metacache) {
+        globalConfig().metacache = enabled;
+    }
+    ~ScopedMetacache() { globalConfig().metacache = old; }
+};
+class BatchRouting : public ::testing::Test {
+   protected:
+    std::string local = "local:1";
+    std::shared_ptr<TransferMetadata> md =
+        std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    MultiTransport multi{md, local};
+    std::shared_ptr<RecordingTransport> rdma =
+        std::make_shared<RecordingTransport>();
+    std::shared_ptr<RecordingTransport> tcp =
+        std::make_shared<RecordingTransport>();
+    void SetUp() override {
+        MultiTransportBatchTestPeer::install(multi, "rdma", rdma);
+        MultiTransportBatchTestPeer::install(multi, "tcp", tcp);
+    }
+    std::shared_ptr<TransferMetadata::SegmentDesc> add(uint64_t id,
+                                                       std::string proto) {
+        auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+        desc->name = "remote:" + std::to_string(id);
+        desc->protocol = proto;
+        auto held = desc;
+        md->addLocalSegment(id, desc->name, std::move(held));
+        return desc;
+    }
+    Status submit(
+        std::initializer_list<std::pair<uint64_t, uint64_t>> targets) {
+        std::vector<Transport::TransferRequest> entries;
+        for (auto [id, addr] : targets) {
+            Transport::TransferRequest entry{};
+            entry.target_id = id;
+            entry.target_offset = addr;
+            entry.length = 16;
+            entries.push_back(entry);
+        }
+        auto batch = multi.allocateBatchID(entries.size());
+        auto status = multi.submitTransfer(batch, entries);
+        EXPECT_TRUE(multi.freeBatchID(batch).ok());
+        return status;
+    }
+};
+TEST_F(BatchRouting, RepeatedAndAlternatingTargetsReachCorrectTransport) {
+    add(1, "rdma");
+    add(2, "tcp");
+    ASSERT_TRUE(
+        submit({{1, 100}, {1, 200}, {2, 300}, {1, 400}, {2, 500}}).ok());
+    EXPECT_EQ(rdma->addresses, (std::vector<uint64_t>{100, 200, 400}));
+    EXPECT_EQ(tcp->addresses, (std::vector<uint64_t>{300, 500}));
+}
+TEST_F(BatchRouting, NextBatchObservesMetadataReplacement) {
+    add(1, "rdma");
+    ASSERT_TRUE(submit({{1, 100}, {1, 200}}).ok());
+    add(1, "tcp");
+    ASSERT_TRUE(submit({{1, 300}, {1, 400}}).ok());
+    EXPECT_EQ(rdma->addresses.size(), 2u);
+    EXPECT_EQ(tcp->addresses.size(), 2u);
+}
+TEST_F(BatchRouting, UnsupportedTargetDoesNotPartiallySubmit) {
+    add(1, "rdma");
+    add(2, "not-installed");
+    ASSERT_FALSE(submit({{1, 100}, {2, 200}}).ok());
+    EXPECT_TRUE(rdma->addresses.empty());
+}
+TEST_F(BatchRouting, TwoSidedFallbackIsRetained) {
+    auto other = std::make_shared<RecordingTransport>();
+    MultiTransport second(md, local);
+    MultiTransportBatchTestPeer::install(second, "rdma_twosided", other);
+    add(1, "rdma");
+    auto batch = second.allocateBatchID(2);
+    Transport::TransferRequest request{};
+    request.target_id = 1;
+    request.length = 16;
+    ASSERT_TRUE(second.submitTransfer(batch, {request, request}).ok());
+    EXPECT_EQ(other->addresses.size(), 2u);
+    EXPECT_TRUE(second.freeBatchID(batch).ok());
+}
+TEST_F(BatchRouting, DisabledMetacacheStillRoutesLocalSegment) {
+    ScopedMetacache disable(false);
+    // LOCAL_SEGMENT_ID is excluded from getSegmentDescByID's metacache-off
+    // refresh (segment_id != LOCAL_SEGMENT_ID). This only checks that
+    // MC_DISABLE_METACACHE=1 still routes a local segment; it does not
+    // verify per-request remote refresh.
+    add(LOCAL_SEGMENT_ID, "rdma");
+    ASSERT_TRUE(
+        submit({{LOCAL_SEGMENT_ID, 100}, {LOCAL_SEGMENT_ID, 200}}).ok());
+    EXPECT_EQ(rdma->addresses, (std::vector<uint64_t>{100, 200}));
+}
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST_F(BatchRouting, MixedProtocolSameTargetStillRoutesByAddress) {
+    auto desc = add(1, "rdma,tcp");
+    TransferMetadata::BufferDesc a;
+    a.addr = 100;
+    a.length = 100;
+    a.protocol = "rdma";
+    TransferMetadata::BufferDesc b;
+    b.addr = 300;
+    b.length = 100;
+    b.protocol = "tcp";
+    desc->buffers = {a, b};
+    ASSERT_TRUE(submit({{1, 100}, {1, 300}, {1, 116}, {1, 316}}).ok());
+    EXPECT_EQ(rdma->addresses, (std::vector<uint64_t>{100, 116}));
+    EXPECT_EQ(tcp->addresses, (std::vector<uint64_t>{300, 316}));
+}
+#endif
+}  // namespace
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/nvlink_host_numa_allocation_test.cpp b/mooncake-transfer-engine/tests/nvlink_host_numa_allocation_test.cpp
new file mode 100644
index 0000000000..9706055805
--- /dev/null
+++ b/mooncake-transfer-engine/tests/nvlink_host_numa_allocation_test.cpp
@@ -0,0 +1,520 @@
+// Copyright 2026 KVCache.AI
+
+#include "transport/nvlink_transport/nvlink_host_numa_allocation.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace mooncake {
+
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+
+class NvlinkHostNumaAllocationTestPeer {
+   public:
+    using DriverApi = NvlinkHostNumaAllocation::DriverApi;
+    using OwnedRangeResult = NvlinkHostNumaAllocation::OwnedRangeResult;
+
+    static Status Discover(const DriverApi& api, std::vector<int>& nodes) {
+        return NvlinkHostNumaAllocation::DiscoverHostNumaNodesWithDriverApi(
+            api, nodes);
+    }
+
+    static Status Create(
+        int node, size_t length, size_t alignment, const DriverApi& api,
+        std::unique_ptr<NvlinkHostNumaAllocation>& allocation) {
+        return NvlinkHostNumaAllocation::CreateWithDriverApi(
+            node, length, alignment, api, allocation);
+    }
+
+    static bool IsExact(void* base, size_t length) {
+        if (Acquire(base, length) != OwnedRangeResult::kPinned) return false;
+        return Unpin(base, length);
+    }
+
+    static OwnedRangeResult Acquire(void* base, size_t length) {
+        DriverApi ignored;
+        return NvlinkHostNumaAllocation::AcquireOwnedRange(base, length,
+                                                           &ignored);
+    }
+
+    static bool Unpin(void* base, size_t length) {
+        return NvlinkHostNumaAllocation::ReleaseOwnedRange(base, length);
+    }
+
+    static bool IsOwnedBase(void* base) {
+        return NvlinkHostNumaAllocation::IsOwnedRangeBase(base);
+    }
+};
+
+namespace {
+
+struct ThrowingDeviceCount {
+    std::shared_ptr<bool> fail_copy;
+    explicit ThrowingDeviceCount(std::shared_ptr<bool> fail)
+        : fail_copy(std::move(fail)) {}
+    ThrowingDeviceCount(const ThrowingDeviceCount& other)
+        : fail_copy(other.fail_copy) {
+        if (*fail_copy) throw std::runtime_error("injected API copy failure");
+    }
+    CUresult operator()(int* count) const {
+        *count = 3;
+        return CUDA_SUCCESS;
+    }
+};
+
+class FakeCudaDriver {
+   public:
+    enum class Failure { NONE, GRANULARITY, CREATE, RESERVE, MAP, ACCESS };
+
+    NvlinkHostNumaAllocationTestPeer::DriverApi api() {
+        NvlinkHostNumaAllocationTestPeer::DriverApi api;
+        api.device_get_count = [this](int* count) {
+            *count = static_cast<int>(host_nodes.size());
+            return CUDA_SUCCESS;
+        };
+        api.device_get = [](CUdevice* device, int ordinal) {
+            *device = ordinal;
+            return CUDA_SUCCESS;
+        };
+        api.device_get_attribute = [this](int* value,
+                                          CUdevice_attribute attribute,
+                                          CUdevice device) {
+            if (attribute ==
+                CU_DEVICE_ATTRIBUTE_VIRTUAL_MEMORY_MANAGEMENT_SUPPORTED) {
+                *value = vmm_supported;
+            } else if (attribute ==
+                       CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED) {
+                *value = fabric_supported;
+            } else if (attribute == CU_DEVICE_ATTRIBUTE_HOST_NUMA_ID) {
+                if (device == host_numa_id_failure_device)
+                    return CUDA_ERROR_INVALID_DEVICE;
+                *value = host_nodes.at(static_cast<size_t>(device));
+#if CUDA_VERSION >= 12090
+            } else if (
+                attribute ==
+                CU_DEVICE_ATTRIBUTE_HOST_NUMA_VIRTUAL_MEMORY_MANAGEMENT_SUPPORTED) {
+                *value = vmm_supported;
+#endif
+            } else {
+                *value = 0;
+            }
+            return CUDA_SUCCESS;
+        };
+        api.mem_get_allocation_granularity =
+            [this](size_t* value, const CUmemAllocationProp* prop,
+                   CUmemAllocationGranularity_flags) {
+                operations.push_back("granularity");
+                last_prop = *prop;
+                if (failure == Failure::GRANULARITY ||
+                    prop->location.id == granularity_failure_node)
+                    return CUDA_ERROR_INVALID_VALUE;
+                *value = granularity;
+                return CUDA_SUCCESS;
+            };
+        api.mem_create = [this](CUmemGenericAllocationHandle* handle,
+                                size_t size, const CUmemAllocationProp* prop,
+                                unsigned long long) {
+            operations.push_back("create");
+            last_prop = *prop;
+            created_size = size;
+            if (failure == Failure::CREATE) return CUDA_ERROR_INVALID_VALUE;
+            *handle = 7;
+            ++handles;
+            return CUDA_SUCCESS;
+        };
+        api.mem_address_reserve = [this](CUdeviceptr* address, size_t,
+                                         size_t alignment, CUdeviceptr,
+                                         unsigned long long) {
+            operations.push_back("reserve");
+            reserved_alignment = alignment;
+            if (failure == Failure::RESERVE) return CUDA_ERROR_INVALID_VALUE;
+            *address = kAddress;
+            ++reservations;
+            return CUDA_SUCCESS;
+        };
+        api.mem_map = [this](CUdeviceptr, size_t, size_t,
+                             CUmemGenericAllocationHandle, unsigned long long) {
+            operations.push_back("map");
+            if (failure == Failure::MAP) return CUDA_ERROR_INVALID_VALUE;
+            ++mappings;
+            return CUDA_SUCCESS;
+        };
+        api.mem_set_access = [this](CUdeviceptr, size_t,
+                                    const CUmemAccessDesc* access,
+                                    size_t count) {
+            operations.push_back("access");
+            accesses.assign(access, access + count);
+            if (failure == Failure::ACCESS) return CUDA_ERROR_INVALID_VALUE;
+            return CUDA_SUCCESS;
+        };
+        api.mem_unmap = [this](CUdeviceptr, size_t) {
+            operations.push_back("unmap");
+            ++unmap_calls;
+            if (unmap_failures > 0) {
+                --unmap_failures;
+                return CUDA_ERROR_INVALID_VALUE;
+            }
+            --mappings;
+            return CUDA_SUCCESS;
+        };
+        api.mem_address_free = [this](CUdeviceptr, size_t) {
+            operations.push_back("address_free");
+            ++address_free_calls;
+            if (address_free_failures > 0) {
+                --address_free_failures;
+                return CUDA_ERROR_INVALID_VALUE;
+            }
+            --reservations;
+            return CUDA_SUCCESS;
+        };
+        api.mem_release = [this](CUmemGenericAllocationHandle) {
+            operations.push_back("release");
+            ++release_calls;
+            if (release_failures > 0) {
+                --release_failures;
+                return CUDA_ERROR_INVALID_VALUE;
+            }
+            --handles;
+            return CUDA_SUCCESS;
+        };
+        api.mem_retain_allocation_handle =
+            [](CUmemGenericAllocationHandle* handle, void*) {
+                *handle = 9;
+                return CUDA_SUCCESS;
+            };
+        api.mem_export_to_shareable_handle =
+            [](void*, CUmemGenericAllocationHandle, CUmemAllocationHandleType,
+               unsigned long long) { return CUDA_SUCCESS; };
+        return api;
+    }
+
+    static constexpr CUdeviceptr kAddress = 0x100000000ULL;
+    Failure failure = Failure::NONE;
+    std::vector<int> host_nodes{2, 0, 2};
+    int vmm_supported = 1;
+    int fabric_supported = 1;
+    int host_numa_id_failure_device = -1;
+    int granularity_failure_node = -1;
+    size_t granularity = 64 * 1024;
+    int unmap_failures = 0;
+    int address_free_failures = 0;
+    int release_failures = 0;
+    int handles = 0;
+    int reservations = 0;
+    int mappings = 0;
+    int unmap_calls = 0;
+    int address_free_calls = 0;
+    int release_calls = 0;
+    size_t created_size = 0;
+    size_t reserved_alignment = 0;
+    CUmemAllocationProp last_prop = {};
+    std::vector<CUmemAccessDesc> accesses;
+    std::vector<std::string> operations;
+};
+
+TEST(NvlinkHostNumaAllocationTest, DiscoversSortedGpuLocalNodes) {
+    FakeCudaDriver driver;
+    std::vector<int> nodes;
+    ASSERT_TRUE(
+        NvlinkHostNumaAllocationTestPeer::Discover(driver.api(), nodes).ok());
+    EXPECT_EQ(nodes, (std::vector<int>{0, 2}));
+
+    driver.fabric_supported = 0;
+    EXPECT_TRUE(NvlinkHostNumaAllocationTestPeer::Discover(driver.api(), nodes)
+                    .IsNotSupportedTransport());
+    EXPECT_TRUE(nodes.empty());
+}
+
+TEST(NvlinkHostNumaAllocationTest, AlignsAndGrantsCpuAndGpuAccess) {
+    FakeCudaDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 100000, 256 * 1024, driver.api(), allocation)
+                    .ok());
+    ASSERT_NE(allocation, nullptr);
+    EXPECT_EQ(allocation->base(),
+              reinterpret_cast<void*>(FakeCudaDriver::kAddress));
+    EXPECT_EQ(allocation->length(), 256U * 1024);
+    EXPECT_EQ(allocation->numaNode(), 2);
+    EXPECT_EQ(driver.created_size, 256U * 1024);
+    EXPECT_EQ(driver.reserved_alignment, 256U * 1024);
+    EXPECT_EQ(driver.last_prop.location.type, CU_MEM_LOCATION_TYPE_HOST_NUMA);
+    EXPECT_EQ(driver.last_prop.location.id, 2);
+    EXPECT_EQ(driver.last_prop.requestedHandleTypes, CU_MEM_HANDLE_TYPE_FABRIC);
+    ASSERT_EQ(driver.accesses.size(), 4U);
+    EXPECT_EQ(driver.accesses.front().location.type,
+              CU_MEM_LOCATION_TYPE_HOST_NUMA);
+    EXPECT_TRUE(std::all_of(driver.accesses.begin(), driver.accesses.end(),
+                            [](const CUmemAccessDesc& access) {
+                                return access.flags ==
+                                       CU_MEM_ACCESS_FLAGS_PROT_READWRITE;
+                            }));
+    EXPECT_TRUE(NvlinkHostNumaAllocationTestPeer::IsExact(
+        allocation->base(), allocation->length()));
+    EXPECT_FALSE(NvlinkHostNumaAllocationTestPeer::IsExact(
+        allocation->base(), allocation->length() / 2));
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.handles, 0);
+    EXPECT_EQ(driver.reservations, 0);
+    EXPECT_EQ(driver.mappings, 0);
+}
+
+TEST(NvlinkHostNumaAllocationTest,
+     ExplicitNodeIgnoresUnselectedLocalityAndGranularityFailures) {
+    FakeCudaDriver locality_driver;
+    locality_driver.host_numa_id_failure_device = 1;
+    std::vector<int> nodes;
+    EXPECT_FALSE(
+        NvlinkHostNumaAllocationTestPeer::Discover(locality_driver.api(), nodes)
+            .ok());
+
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 64 * 1024, 0, locality_driver.api(), allocation)
+                    .ok());
+    ASSERT_NE(allocation, nullptr);
+    ASSERT_EQ(locality_driver.accesses.size(), 4U);
+    EXPECT_TRUE(allocation->Release().ok());
+
+    allocation.reset();
+    FakeCudaDriver granularity_driver;
+    granularity_driver.granularity_failure_node = 0;
+    EXPECT_FALSE(NvlinkHostNumaAllocationTestPeer::Discover(
+                     granularity_driver.api(), nodes)
+                     .ok());
+    ASSERT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 64 * 1024, 0, granularity_driver.api(), allocation)
+                    .ok());
+    ASSERT_NE(allocation, nullptr);
+    EXPECT_TRUE(allocation->Release().ok());
+}
+
+TEST(NvlinkHostNumaAllocationTest,
+     ExplicitNodeStillRequiresVisibleGpuFabricCapabilities) {
+    FakeCudaDriver driver;
+    driver.fabric_supported = 0;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    EXPECT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 64 * 1024, 0, driver.api(), allocation)
+                    .IsNotSupportedTransport());
+    EXPECT_EQ(allocation, nullptr);
+    EXPECT_TRUE(driver.operations.empty());
+}
+
+TEST(NvlinkHostNumaAllocationTest, RollsBackEveryCreateStage) {
+    for (auto failure :
+         {FakeCudaDriver::Failure::GRANULARITY, FakeCudaDriver::Failure::CREATE,
+          FakeCudaDriver::Failure::RESERVE, FakeCudaDriver::Failure::MAP,
+          FakeCudaDriver::Failure::ACCESS}) {
+        FakeCudaDriver driver;
+        driver.failure = failure;
+        std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+        EXPECT_FALSE(NvlinkHostNumaAllocationTestPeer::Create(
+                         2, 64 * 1024, 0, driver.api(), allocation)
+                         .ok());
+        EXPECT_EQ(allocation, nullptr);
+        EXPECT_EQ(driver.handles, 0);
+        EXPECT_EQ(driver.reservations, 0);
+        EXPECT_EQ(driver.mappings, 0);
+        if (failure == FakeCudaDriver::Failure::MAP) {
+            EXPECT_EQ(std::vector<std::string>(driver.operations.end() - 2,
+                                               driver.operations.end()),
+                      (std::vector<std::string>{"address_free", "release"}));
+        }
+        if (failure == FakeCudaDriver::Failure::ACCESS) {
+            EXPECT_EQ(
+                std::vector<std::string>(driver.operations.end() - 3,
+                                         driver.operations.end()),
+                (std::vector<std::string>{"unmap", "address_free", "release"}));
+        }
+    }
+}
+
+TEST(NvlinkHostNumaAllocationTest, IncompleteRollbackCanBeRetried) {
+    FakeCudaDriver driver;
+    driver.failure = FakeCudaDriver::Failure::ACCESS;
+    driver.unmap_failures = 1;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    EXPECT_FALSE(NvlinkHostNumaAllocationTestPeer::Create(
+                     2, 64 * 1024, 0, driver.api(), allocation)
+                     .ok());
+    ASSERT_NE(allocation, nullptr);
+    driver.failure = FakeCudaDriver::Failure::NONE;
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 2);
+    EXPECT_EQ(driver.address_free_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+}
+
+TEST(NvlinkHostNumaAllocationTest, ReleaseResumesWithoutRepeatingStages) {
+    FakeCudaDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 64 * 1024, 0, driver.api(), allocation)
+                    .ok());
+    driver.address_free_failures = 1;
+    EXPECT_FALSE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 1);
+    EXPECT_EQ(driver.address_free_calls, 1);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 1);
+    EXPECT_EQ(driver.address_free_calls, 2);
+    EXPECT_EQ(driver.release_calls, 1);
+}
+
+TEST(NvlinkHostNumaAllocationTest, HandleReleaseFailureCanBeRetried) {
+    FakeCudaDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(NvlinkHostNumaAllocationTestPeer::Create(
+                    2, 64 * 1024, 0, driver.api(), allocation)
+                    .ok());
+    driver.release_failures = 1;
+    EXPECT_FALSE(allocation->Release().ok());
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.release_calls, 2);
+}
+
+TEST(NvlinkHostNumaAllocationTest, CreateNeverOverwritesExistingOwner) {
+    for (bool partial : {false, true}) {
+        FakeCudaDriver driver;
+        if (partial) {
+            driver.failure = FakeCudaDriver::Failure::ACCESS;
+            driver.unmap_failures = 3;
+        }
+        std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+        EXPECT_EQ(NvlinkHostNumaAllocationTestPeer::Create(
+                      2, 64 * 1024, 0, driver.api(), allocation)
+                      .ok(),
+                  !partial);
+        ASSERT_NE(allocation, nullptr);
+        auto* const owner = allocation.get();
+        const auto operations = driver.operations;
+        EXPECT_FALSE(NvlinkHostNumaAllocationTestPeer::Create(
+                         2, 64 * 1024, 0, driver.api(), allocation)
+                         .ok());
+        EXPECT_EQ(allocation.get(), owner);
+        EXPECT_EQ(driver.operations, operations);
+        if (partial) {
+            EXPECT_FALSE(allocation->Release().ok());
+            EXPECT_FALSE(allocation->Release().ok());
+            EXPECT_EQ(allocation.get(), owner);
+            EXPECT_EQ(driver.address_free_calls, 0);
+            EXPECT_EQ(driver.release_calls, 0);
+        }
+        EXPECT_TRUE(allocation->Release().ok());
+        EXPECT_EQ(driver.unmap_calls, partial ? 4 : 1);
+        EXPECT_EQ(driver.handles, 0);
+        EXPECT_EQ(driver.reservations, 0);
+        EXPECT_EQ(driver.mappings, 0);
+    }
+}
+
+TEST(NvlinkHostNumaAllocationTest, PinsBlockReleaseWithoutClosingRegistration) {
+    using Peer = NvlinkHostNumaAllocationTestPeer;
+    using Result = Peer::OwnedRangeResult;
+    FakeCudaDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(Peer::Create(2, 64 * 1024, 0, driver.api(), allocation).ok());
+    void* const base = allocation->base();
+    const size_t length = allocation->length();
+    ASSERT_EQ(Peer::Acquire(base, length), Result::kPinned);
+    EXPECT_FALSE(allocation->Release().ok());
+    // A rejected Release must not mark the range releasing.
+    ASSERT_EQ(Peer::Acquire(base, length), Result::kPinned);
+    EXPECT_TRUE(Peer::Unpin(base, length));
+    EXPECT_FALSE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 0);
+    EXPECT_EQ(driver.address_free_calls, 0);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_TRUE(Peer::Unpin(base, length));
+    EXPECT_FALSE(Peer::Unpin(base, length));
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_FALSE(Peer::IsOwnedBase(base));
+}
+
+TEST(NvlinkHostNumaAllocationTest, FailedReleaseKeepsRangeUnavailable) {
+    using Peer = NvlinkHostNumaAllocationTestPeer;
+    using Result = Peer::OwnedRangeResult;
+    FakeCudaDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(Peer::Create(2, 64 * 1024, 0, driver.api(), allocation).ok());
+    void* const base = allocation->base();
+    const size_t length = allocation->length();
+    driver.unmap_failures = 1;
+    driver.address_free_failures = 1;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        EXPECT_FALSE(allocation->Release().ok());
+        EXPECT_TRUE(Peer::IsOwnedBase(base));
+        EXPECT_EQ(Peer::Acquire(base, length), Result::kUnavailable);
+        EXPECT_EQ(Peer::Acquire(base, length / 2), Result::kInvalid);
+        EXPECT_EQ(Peer::Acquire(reinterpret_cast<void*>(
+                                    reinterpret_cast<uintptr_t>(base) + 1),
+                                length / 2),
+                  Result::kInvalid);
+    }
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 2);
+    EXPECT_EQ(driver.address_free_calls, 2);
+    EXPECT_EQ(Peer::Acquire(base, length), Result::kNotOwned);
+}
+
+TEST(NvlinkHostNumaAllocationTest, HandleRetryDoesNotEraseReusedAddress) {
+    using Peer = NvlinkHostNumaAllocationTestPeer;
+    FakeCudaDriver old_driver;
+    FakeCudaDriver new_driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> old_owner;
+    std::unique_ptr<NvlinkHostNumaAllocation> new_owner;
+    ASSERT_TRUE(
+        Peer::Create(2, 64 * 1024, 0, old_driver.api(), old_owner).ok());
+    void* const base = old_owner->base();
+    old_driver.release_failures = 1;
+    EXPECT_FALSE(old_owner->Release().ok());
+    EXPECT_EQ(old_owner->base(), nullptr);
+    EXPECT_FALSE(Peer::IsOwnedBase(base));
+    ASSERT_TRUE(
+        Peer::Create(2, 64 * 1024, 0, new_driver.api(), new_owner).ok());
+    EXPECT_EQ(new_owner->base(), base);
+    EXPECT_TRUE(old_owner->Release().ok());
+    EXPECT_TRUE(Peer::IsExact(base, new_owner->length()));
+    EXPECT_EQ(old_driver.unmap_calls, 1);
+    EXPECT_EQ(old_driver.address_free_calls, 1);
+    EXPECT_EQ(old_driver.release_calls, 2);
+    EXPECT_EQ(new_driver.unmap_calls, 0);
+    EXPECT_TRUE(new_owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaAllocationTest, ApiCopyFailureDoesNotPinOrAllowFallback) {
+    using Peer = NvlinkHostNumaAllocationTestPeer;
+    FakeCudaDriver driver;
+    auto fail_copy = std::make_shared<bool>(false);
+    auto api = driver.api();
+    api.device_get_count = ThrowingDeviceCount(fail_copy);
+    std::unique_ptr<NvlinkHostNumaAllocation> allocation;
+    ASSERT_TRUE(Peer::Create(2, 64 * 1024, 0, api, allocation).ok());
+    *fail_copy = true;
+    EXPECT_EQ(Peer::Acquire(allocation->base(), allocation->length()),
+              Peer::OwnedRangeResult::kError);
+    EXPECT_TRUE(allocation->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 1);
+}
+
+}  // namespace
+
+#else
+
+TEST(NvlinkHostNumaAllocationTest, UnsupportedToolchainReturnsStatus) {
+    std::vector<int> nodes;
+    EXPECT_TRUE(NvlinkHostNumaAllocation::DiscoverHostNumaNodes(nodes)
+                    .IsNotSupportedTransport());
+}
+
+#endif
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/nvlink_transport_test.cpp b/mooncake-transfer-engine/tests/nvlink_transport_test.cpp
index f486e48a75..8ff0c4e505 100644
--- a/mooncake-transfer-engine/tests/nvlink_transport_test.cpp
+++ b/mooncake-transfer-engine/tests/nvlink_transport_test.cpp
@@ -4,9 +4,15 @@
 #include <thread>
 #include <memory>
 #include <cstring>
+#include <cstdlib>
+#include <condition_variable>
+#include <future>
 
 #include "cuda_alike.h"
 #include "transfer_engine.h"
+#include "transfer_metadata.h"
+#include "transport/nvlink_transport/nvlink_host_numa_allocation.h"
+#include "transport/nvlink_transport/nvlink_transport.h"
 #include "transport/transport.h"
 
 using namespace mooncake;
@@ -23,6 +29,939 @@ DEFINE_string(local_server_name, "cuda_server:12345", "Local server name");
 DEFINE_string(segment_id, "cuda_server:12345", "Segment ID to access data");
 DEFINE_int32(gpu_id, 0, "GPU ID to use");
 
+#if MOONCAKE_NVLINK_HOST_NUMA_ENABLED
+namespace mooncake {
+
+class NvlinkTransportTestPeer {
+   public:
+    using DriverApi = NvlinkHostNumaAllocation::DriverApi;
+    using AddLocalMemoryBufferOp = NvlinkTransport::AddLocalMemoryBufferOp;
+    using RemoveLocalMemoryBufferOp =
+        NvlinkTransport::RemoveLocalMemoryBufferOp;
+    using UpdateLocalSegmentDescOp = NvlinkTransport::UpdateLocalSegmentDescOp;
+
+    static std::unique_ptr<NvlinkHostNumaAllocation> MakeOwnedRange(
+        void* base, size_t length, const DriverApi& api, bool mapped = false) {
+        auto allocation = std::unique_ptr<NvlinkHostNumaAllocation>(
+            new NvlinkHostNumaAllocation());
+        allocation->base_ = base;
+        allocation->length_ = length;
+        allocation->numa_node_ = 0;
+        allocation->driver_api_ = api;
+        allocation->mapped_ = mapped;
+        allocation->address_reserved_ = mapped;
+        allocation->handle_owned_ = mapped;
+        allocation->allocation_handle_ = 99;
+        allocation->owned_range_registered_ =
+            NvlinkHostNumaAllocation::RegisterOwnedRange(base, length, api);
+        return allocation->owned_range_registered_ ? std::move(allocation)
+                                                   : nullptr;
+    }
+
+    static std::shared_ptr<TransferMetadata> Configure(
+        NvlinkTransport& transport) {
+        auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+        auto segment = std::make_shared<TransferMetadata::SegmentDesc>();
+        segment->name = "local";
+        segment->protocol = "nvlink";
+        EXPECT_EQ(metadata->addLocalSegment(LOCAL_SEGMENT_ID, "local",
+                                            std::move(segment)),
+                  0);
+        transport.meta() = metadata;
+        transport.use_fabric_mem_ = true;
+        return metadata;
+    }
+
+    static int Register(NvlinkTransport& transport, void* base, size_t length) {
+        return transport.registerLocalMemory(base, length, "cpu:0", true, true);
+    }
+
+    static int Unregister(NvlinkTransport& transport, void* base) {
+        return transport.unregisterLocalMemory(base, true);
+    }
+
+    static int RegisterWithOperations(
+        NvlinkTransport& transport, void* base, size_t length,
+        const AddLocalMemoryBufferOp& add_buffer,
+        const RemoveLocalMemoryBufferOp& remove_buffer,
+        const UpdateLocalSegmentDescOp& update_segment,
+        bool update_metadata = true) {
+        std::lock_guard<std::mutex> lock(transport.register_mutex_);
+        return transport
+            .registerHostNumaMemoryLocked(base, length, "cpu:0",
+                                          update_metadata, add_buffer,
+                                          remove_buffer, update_segment)
+            .value_or(ERR_ADDRESS_NOT_REGISTERED);
+    }
+
+    static int UnregisterWithOperations(
+        NvlinkTransport& transport, void* base,
+        const RemoveLocalMemoryBufferOp& remove_buffer,
+        const UpdateLocalSegmentDescOp& update_segment,
+        bool update_metadata = true) {
+        std::lock_guard<std::mutex> lock(transport.register_mutex_);
+        return transport.unregisterHostNumaMemoryLocked(
+            base, update_metadata, remove_buffer, update_segment);
+    }
+
+    static int UnregisterBatch(NvlinkTransport& transport,
+                               const std::vector<void*>& addresses,
+                               const RemoveLocalMemoryBufferOp& remove_buffer,
+                               const UpdateLocalSegmentDescOp& update_segment) {
+        std::lock_guard<std::mutex> lock(transport.register_mutex_);
+        return transport.unregisterHostNumaMemoryBatchLocked(
+            addresses, remove_buffer, update_segment);
+    }
+
+    static size_t RegistrationCount(const NvlinkTransport& transport) {
+        return transport.host_numa_registration_handles_.size();
+    }
+
+    static void MarkMetadataRemovedLocally(NvlinkTransport& transport,
+                                           void* base) {
+        transport.host_numa_registration_handles_.at(base)
+            .metadata_removed_locally = true;
+    }
+};
+
+}  // namespace mooncake
+
+namespace {
+
+struct FakeRegistrationDriver {
+    NvlinkTransportTestPeer::DriverApi api() {
+        NvlinkTransportTestPeer::DriverApi api;
+        api.mem_retain_allocation_handle =
+            [this](CUmemGenericAllocationHandle* handle, void*) {
+                if (before_retain) before_retain();
+                ++retain_calls;
+                if (retain_result != CUDA_SUCCESS) return retain_result;
+                ++live_handles;
+                *handle = 17;
+                return CUDA_SUCCESS;
+            };
+        api.mem_export_to_shareable_handle =
+            [this](void* output, CUmemGenericAllocationHandle,
+                   CUmemAllocationHandleType type, unsigned long long) {
+                ++export_calls;
+                EXPECT_EQ(type, CU_MEM_HANDLE_TYPE_FABRIC);
+                if (export_result != CUDA_SUCCESS) return export_result;
+                std::memset(output, 0x5a, sizeof(CUmemFabricHandle));
+                return CUDA_SUCCESS;
+            };
+        api.mem_release = [this](CUmemGenericAllocationHandle handle) {
+            if (handle == 99) {
+                ++allocation_release_calls;
+                return CUDA_SUCCESS;
+            }
+            EXPECT_EQ(handle, 17);
+            if (before_release) before_release();
+            ++release_calls;
+            if (release_failures > 0) {
+                --release_failures;
+                return CUDA_ERROR_INVALID_VALUE;
+            }
+            --live_handles;
+            return CUDA_SUCCESS;
+        };
+        api.mem_unmap = [this](CUdeviceptr, size_t) {
+            if (before_unmap) before_unmap();
+            ++unmap_calls;
+            if (unmap_failures-- > 0) return CUDA_ERROR_INVALID_VALUE;
+            return CUDA_SUCCESS;
+        };
+        api.mem_address_free = [this](CUdeviceptr, size_t) {
+            ++free_calls;
+            if (free_failures-- > 0) return CUDA_ERROR_INVALID_VALUE;
+            return CUDA_SUCCESS;
+        };
+        return api;
+    }
+
+    std::function<void()> before_retain;
+    std::function<void()> before_release;
+    std::function<void()> before_unmap;
+    int unmap_calls = 0;
+    int free_calls = 0;
+    int unmap_failures = 0;
+    int free_failures = 0;
+    int allocation_release_calls = 0;
+    int retain_calls = 0;
+    int export_calls = 0;
+    int release_calls = 0;
+    int release_failures = 0;
+    int live_handles = 0;
+    CUresult retain_result = CUDA_SUCCESS;
+    CUresult export_result = CUDA_SUCCESS;
+};
+
+TEST(NvlinkHostNumaRegistrationTest,
+     RetainFailureIsReportedWithoutPublication) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x080000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    driver.retain_result = CUDA_ERROR_INVALID_VALUE;
+    NvlinkTransport transport;
+    int publication_calls = 0;
+
+    EXPECT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [&](const TransferMetadata::BufferDesc&, bool) {
+                      ++publication_calls;
+                      return 0;
+                  },
+                  [](void*, bool) { return 0; }, []() { return 0; }),
+              ERR_MEMORY);
+    EXPECT_EQ(driver.retain_calls, 1);
+    EXPECT_EQ(driver.export_calls, 0);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(publication_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     ExportFailureReleasesRetainedHandleWithoutPublication) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x090000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    driver.export_result = CUDA_ERROR_NOT_SUPPORTED;
+    NvlinkTransport transport;
+    int publication_calls = 0;
+
+    EXPECT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [&](const TransferMetadata::BufferDesc&, bool) {
+                      ++publication_calls;
+                      return 0;
+                  },
+                  [](void*, bool) { return 0; }, []() { return 0; }),
+              ERR_MEMORY);
+    EXPECT_EQ(driver.retain_calls, 1);
+    EXPECT_EQ(driver.export_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(publication_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     ExportAndReleaseFailureRetainsHandleForUnregisterRetry) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x0a0000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    driver.export_result = CUDA_ERROR_NOT_SUPPORTED;
+    driver.release_failures = 1;
+    NvlinkTransport transport;
+    int remove_calls = 0;
+
+    EXPECT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [](const TransferMetadata::BufferDesc&, bool) { return 0; },
+                  [&](void*, bool) {
+                      ++remove_calls;
+                      return 0;
+                  },
+                  []() { return 0; }),
+              ERR_MEMORY);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 1);
+    EXPECT_EQ(remove_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterWithOperations(
+                  transport, base,
+                  [&](void*, bool) {
+                      ++remove_calls;
+                      return 0;
+                  },
+                  []() { return 0; }),
+              0);
+    EXPECT_EQ(driver.release_calls, 2);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(remove_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest, PublishesExactRangeAndRetainsHandle) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x100000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+
+    NvlinkTransport transport;
+    auto metadata = NvlinkTransportTestPeer::Configure(transport);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, base, kLength), 0);
+    EXPECT_EQ(driver.retain_calls, 1);
+    EXPECT_EQ(driver.export_calls, 1);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_EQ(driver.live_handles, 1);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+
+    auto segment = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(segment, nullptr);
+    ASSERT_EQ(segment->buffers.size(), 1U);
+    EXPECT_EQ(segment->buffers[0].addr, reinterpret_cast<uint64_t>(base));
+    EXPECT_EQ(segment->buffers[0].length, kLength);
+    EXPECT_EQ(segment->buffers[0].shm_name.size(),
+              sizeof(CUmemFabricHandle) * 2);
+
+    EXPECT_EQ(NvlinkTransportTestPeer::Unregister(transport, base), 0);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+    EXPECT_TRUE(owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest, FailedUnregisterKeepsHandleOwned) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x200000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+
+    NvlinkTransport transport;
+    NvlinkTransportTestPeer::Configure(transport);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, base, kLength), 0);
+    EXPECT_NE(NvlinkTransportTestPeer::Unregister(
+                  transport, reinterpret_cast<void*>(0x300000000ULL)),
+              0);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+    EXPECT_EQ(NvlinkTransportTestPeer::Unregister(transport, base), 0);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_TRUE(owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest, RejectsNonExactOwnedRange) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x400000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+
+    NvlinkTransport transport;
+    NvlinkTransportTestPeer::Configure(transport);
+    EXPECT_EQ(NvlinkTransportTestPeer::Register(transport, base, kLength / 2),
+              ERR_INVALID_ARGUMENT);
+    EXPECT_EQ(driver.retain_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+    EXPECT_TRUE(owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest, RetriesMetadataPublicationBeforeRelease) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x500000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+
+    NvlinkTransport transport;
+    auto metadata = NvlinkTransportTestPeer::Configure(transport);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, base, kLength), 0);
+    ASSERT_EQ(metadata->removeLocalMemoryBuffer(base, false), 0);
+    NvlinkTransportTestPeer::MarkMetadataRemovedLocally(transport, base);
+
+    EXPECT_EQ(NvlinkTransportTestPeer::Unregister(transport, base), 0);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+    EXPECT_TRUE(owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     ReleaseFailureKeepsRegistrationWithoutRepeatingMetadataDelete) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x600000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    driver.release_failures = 1;
+    NvlinkTransport transport;
+    int remove_calls = 0;
+    int update_calls = 0;
+    auto remove_buffer = [&](void*, bool) {
+        ++remove_calls;
+        return 0;
+    };
+    auto update_segment = [&]() {
+        ++update_calls;
+        return 0;
+    };
+
+    ASSERT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [](const TransferMetadata::BufferDesc&, bool) { return 0; },
+                  remove_buffer, update_segment),
+              0);
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterWithOperations(
+                  transport, base, remove_buffer, update_segment),
+              ERR_MEMORY);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+    EXPECT_EQ(remove_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 1);
+
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterWithOperations(
+                  transport, base, remove_buffer, update_segment),
+              0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+    EXPECT_EQ(remove_calls, 1);
+    EXPECT_EQ(update_calls, 0);
+    EXPECT_EQ(driver.release_calls, 2);
+    EXPECT_EQ(driver.live_handles, 0);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     PublicationFailureRollsBackAndReturnsOriginalError) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x700000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    NvlinkTransport transport;
+    int remove_calls = 0;
+
+    EXPECT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [](const TransferMetadata::BufferDesc&, bool) {
+                      return ERR_METADATA;
+                  },
+                  [&](void*, bool) {
+                      ++remove_calls;
+                      return 0;
+                  },
+                  []() { return 0; }),
+              ERR_METADATA);
+    EXPECT_EQ(remove_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     FailedPublicationRollbackCanBeCompletedByUnregister) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x800000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    NvlinkTransport transport;
+    int remove_calls = 0;
+    int update_calls = 0;
+
+    EXPECT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [](const TransferMetadata::BufferDesc&, bool) {
+                      return ERR_METADATA;
+                  },
+                  [&](void*, bool) {
+                      ++remove_calls;
+                      return ERR_METADATA;
+                  },
+                  [&]() {
+                      ++update_calls;
+                      return 0;
+                  }),
+              ERR_METADATA);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+    EXPECT_EQ(driver.release_calls, 0);
+    EXPECT_EQ(driver.live_handles, 1);
+
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterWithOperations(
+                  transport, base,
+                  [&](void*, bool) {
+                      ++remove_calls;
+                      return 0;
+                  },
+                  [&]() {
+                      ++update_calls;
+                      return 0;
+                  }),
+              0);
+    EXPECT_EQ(remove_calls, 1);
+    EXPECT_EQ(update_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     MissingLocalMetadataIsTreatedAsIdempotentDelete) {
+    constexpr size_t kLength = 64 * 1024;
+    void* const base = reinterpret_cast<void*>(0x900000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, kLength, driver.api());
+    ASSERT_NE(owner, nullptr);
+    NvlinkTransport transport;
+    int update_calls = 0;
+
+    ASSERT_EQ(NvlinkTransportTestPeer::RegisterWithOperations(
+                  transport, base, kLength,
+                  [](const TransferMetadata::BufferDesc&, bool) { return 0; },
+                  [](void*, bool) { return ERR_ADDRESS_NOT_REGISTERED; },
+                  [&]() {
+                      ++update_calls;
+                      return 0;
+                  }),
+              0);
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterWithOperations(
+                  transport, base,
+                  [](void*, bool) { return ERR_ADDRESS_NOT_REGISTERED; },
+                  [&]() {
+                      ++update_calls;
+                      return 0;
+                  }),
+              0);
+    EXPECT_EQ(update_calls, 1);
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+}
+
+TEST(NvlinkHostNumaRegistrationTest, DestructorRemovesMetadataAndReleasesPin) {
+    constexpr size_t length = 64 * 1024;
+    void* base = reinterpret_cast<void*>(0xe00000000ULL);
+    FakeRegistrationDriver driver;
+    auto owner = NvlinkTransportTestPeer::MakeOwnedRange(base, length,
+                                                         driver.api(), true);
+    ASSERT_NE(owner, nullptr);
+    std::shared_ptr<TransferMetadata> metadata;
+    {
+        NvlinkTransport transport;
+        metadata = NvlinkTransportTestPeer::Configure(transport);
+        ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, base, length),
+                  0);
+        EXPECT_EQ(driver.live_handles, 1);
+        EXPECT_FALSE(owner->Release().ok());
+    }
+    auto segment = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(segment, nullptr);
+    EXPECT_TRUE(segment->buffers.empty());
+    EXPECT_EQ(driver.release_calls, 1);
+    EXPECT_EQ(driver.live_handles, 0);
+    EXPECT_TRUE(owner->Release().ok());
+    EXPECT_EQ(driver.unmap_calls, 1);
+    EXPECT_EQ(driver.free_calls, 1);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     DestructorCleanupFailureKeepsAllocationPinned) {
+    // Intentionally unrecoverable ownership is confined to this child. Every
+    // acceptance condition contributes to its exit status; gtest assertions
+    // alone would not make an EXPECT_EXIT child fail.
+    EXPECT_EXIT(
+        {
+            constexpr size_t length = 64 * 1024;
+            void* base = reinterpret_cast<void*>(0xf00000000ULL);
+            FakeRegistrationDriver driver;
+            driver.release_failures = 100;
+            auto owner = NvlinkTransportTestPeer::MakeOwnedRange(
+                base, length, driver.api(), true);
+            if (!owner) std::_Exit(1);
+            std::shared_ptr<TransferMetadata> metadata;
+            {
+                NvlinkTransport transport;
+                metadata = NvlinkTransportTestPeer::Configure(transport);
+                if (NvlinkTransportTestPeer::Register(transport, base,
+                                                      length) != 0)
+                    std::_Exit(2);
+            }
+            auto segment = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+            const bool blocked = !owner->Release().ok();
+            const bool retained = driver.live_handles == 1 &&
+                                  driver.release_calls == 1 &&
+                                  driver.retain_calls == 1;
+            const bool untouched = driver.unmap_calls == 0 &&
+                                   driver.free_calls == 0 &&
+                                   driver.allocation_release_calls == 0;
+            const bool unpublished = segment && segment->buffers.empty();
+            std::_Exit(blocked && retained && untouched && unpublished ? 0 : 3);
+        },
+        ::testing::ExitedWithCode(0), "");
+}
+
+struct RegistrationScenario {
+    static constexpr size_t length = 64 * 1024;
+    void* base = reinterpret_cast<void*>(0xb00000000ULL);
+    FakeRegistrationDriver driver;
+    std::unique_ptr<NvlinkHostNumaAllocation> owner =
+        NvlinkTransportTestPeer::MakeOwnedRange(base, length, driver.api(),
+                                                true);
+    NvlinkTransport transport;
+    int add_result = 0;
+    int remove_result = 0;
+    int update_result = 0;
+    int adds = 0;
+    int removes = 0;
+    int updates = 0;
+    std::vector<bool> add_flags;
+    std::vector<bool> remove_flags;
+
+    int Register(bool update = true) {
+        return NvlinkTransportTestPeer::RegisterWithOperations(
+            transport, base, length,
+            [&](const TransferMetadata::BufferDesc&, bool publish) {
+                ++adds;
+                add_flags.push_back(publish);
+                return add_result;
+            },
+            [&](void*, bool publish) {
+                ++removes;
+                remove_flags.push_back(publish);
+                return remove_result;
+            },
+            [&] {
+                ++updates;
+                return update_result;
+            },
+            update);
+    }
+    int Unregister(bool update = true) {
+        return NvlinkTransportTestPeer::UnregisterWithOperations(
+            transport, base,
+            [&](void*, bool publish) {
+                ++removes;
+                remove_flags.push_back(publish);
+                return remove_result;
+            },
+            [&] {
+                ++updates;
+                return update_result;
+            },
+            update);
+    }
+};
+
+TEST(NvlinkHostNumaRegistrationTest,
+     RegisterRetriesExportRollbackBeforeRetain) {
+    RegistrationScenario s;
+    ASSERT_NE(s.owner, nullptr);
+    s.driver.export_result = CUDA_ERROR_NOT_SUPPORTED;
+    s.driver.release_failures = 2;
+    EXPECT_EQ(s.Register(), ERR_MEMORY);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 0);
+    s.driver.export_result = CUDA_SUCCESS;
+    EXPECT_EQ(s.Register(), ERR_MEMORY);
+    EXPECT_EQ(s.driver.retain_calls, 1);
+    EXPECT_EQ(s.Register(), 0);
+    EXPECT_EQ(s.driver.retain_calls, 2);
+    EXPECT_EQ(s.driver.live_handles, 1);
+    EXPECT_EQ(s.Register(), ERR_ADDRESS_OVERLAPPED);
+    EXPECT_EQ(s.driver.retain_calls, 2);
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_TRUE(s.owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     RegisterRetriesPublicationAndReleaseRollback) {
+    RegistrationScenario s;
+    s.add_result = ERR_METADATA;
+    s.driver.release_failures = 1;
+    EXPECT_EQ(s.Register(), ERR_METADATA);
+    EXPECT_EQ(s.removes, 1);
+    EXPECT_EQ(s.driver.live_handles, 1);
+    s.add_result = 0;
+    EXPECT_EQ(s.Register(), 0);
+    EXPECT_EQ(s.removes, 1);
+    EXPECT_EQ(s.driver.release_calls, 2);
+    EXPECT_EQ(s.driver.retain_calls, 2);
+    EXPECT_EQ(s.Unregister(), 0);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     RegistrationRetryProtectsOwnerAndDoesNotLeakTransientPins) {
+    RegistrationScenario s;
+    s.driver.export_result = CUDA_ERROR_NOT_SUPPORTED;
+    s.driver.release_failures = 2;
+    ASSERT_EQ(s.Register(), ERR_MEMORY);
+    int release_callbacks = 0;
+    s.driver.before_release = [&] {
+        ++release_callbacks;
+        EXPECT_FALSE(s.owner->Release().ok());
+        EXPECT_EQ(s.driver.unmap_calls, 0);
+    };
+    s.driver.export_result = CUDA_SUCCESS;
+    EXPECT_EQ(s.Register(), ERR_MEMORY);
+    EXPECT_EQ(release_callbacks, 1);
+    EXPECT_EQ(s.driver.retain_calls, 1);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(s.transport), 1U);
+    s.driver.before_retain = [&] {
+        // Old registration cleanup has completed by this point. The new
+        // registration must already protect the allocation before retain.
+        EXPECT_FALSE(s.owner->Release().ok());
+        EXPECT_EQ(s.driver.unmap_calls, 0);
+    };
+    EXPECT_EQ(s.Register(), 0);
+    EXPECT_EQ(release_callbacks, 2);
+    EXPECT_EQ(s.driver.retain_calls, 2);
+    s.driver.before_release = {};
+    s.driver.before_retain = {};
+    EXPECT_EQ(s.Unregister(), 0);
+    // Neither the failed retry nor the successful transfer may leak a pin.
+    EXPECT_TRUE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 1);
+    EXPECT_EQ(s.driver.live_handles, 0);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     DuplicateBatchAddressAttemptsRetainedReleaseOncePerCall) {
+    RegistrationScenario s;
+    ASSERT_EQ(s.Register(), 0);
+    s.driver.release_failures = 1;
+    int removes = 0;
+    auto remove = [&](void*, bool publish) {
+        EXPECT_FALSE(publish);
+        ++removes;
+        return 0;
+    };
+    auto update = [] { return 0; };
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(
+                  s.transport, {s.base, s.base}, remove, update),
+              ERR_MEMORY);
+    EXPECT_EQ(s.driver.release_calls, 1);
+    EXPECT_EQ(s.driver.live_handles, 1);
+    EXPECT_EQ(removes, 1);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(s.transport), 1U);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(
+                  s.transport, {s.base, s.base}, remove, update),
+              0);
+    EXPECT_EQ(s.driver.release_calls, 2);
+    EXPECT_EQ(removes, 1);
+    EXPECT_EQ(s.driver.live_handles, 0);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(s.transport), 0U);
+    EXPECT_TRUE(s.owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     RegisterFalseCannotDowngradePendingPublication) {
+    RegistrationScenario s;
+    s.add_result = ERR_METADATA;
+    s.remove_result = ERR_METADATA;
+    EXPECT_EQ(s.Register(), ERR_METADATA);
+    s.add_result = 0;
+    s.remove_result = 0;
+    s.update_result = ERR_METADATA;
+    EXPECT_EQ(s.Register(false), ERR_METADATA);
+    EXPECT_EQ(s.removes, 1);
+    EXPECT_EQ(s.driver.release_calls, 0);
+    EXPECT_EQ(s.driver.retain_calls, 1);
+    s.update_result = 0;
+    EXPECT_EQ(s.Register(false), 0);
+    EXPECT_EQ(s.updates, 2);
+    EXPECT_EQ(s.removes, 1);
+    ASSERT_EQ(s.add_flags.size(), 2U);
+    EXPECT_FALSE(s.add_flags.back());
+    EXPECT_EQ(s.Unregister(), 0);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     DeferredUnregisterRetainsPinUntilPublished) {
+    RegistrationScenario s;
+    ASSERT_EQ(s.Register(), 0);
+    EXPECT_EQ(s.Unregister(false), 0);
+    EXPECT_EQ(s.removes, 1);
+    EXPECT_EQ(s.driver.release_calls, 0);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 0);
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_EQ(s.removes, 1);
+    EXPECT_EQ(s.updates, 1);
+    EXPECT_EQ(s.driver.release_calls, 1);
+    EXPECT_TRUE(s.owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest, MultipleTransportsPinSameAllocation) {
+    RegistrationScenario s;
+    NvlinkTransport other;
+    NvlinkTransportTestPeer::Configure(other);
+    ASSERT_EQ(s.Register(), 0);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(other, s.base, s.length), 0);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(NvlinkTransportTestPeer::Unregister(other, s.base), 0);
+    EXPECT_TRUE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 1);
+    EXPECT_EQ(s.driver.free_calls, 1);
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     FailedTeardownRejectsExactAndPartialRegistration) {
+    for (bool fail_unmap : {true, false}) {
+        RegistrationScenario s;
+        s.driver.unmap_failures = fail_unmap ? 1 : 0;
+        s.driver.free_failures = fail_unmap ? 0 : 1;
+        EXPECT_FALSE(s.owner->Release().ok());
+        NvlinkTransportTestPeer::Configure(s.transport);
+        EXPECT_NE(
+            NvlinkTransportTestPeer::Register(s.transport, s.base, s.length),
+            0);
+        EXPECT_NE(NvlinkTransportTestPeer::Register(s.transport, s.base,
+                                                    s.length / 2),
+                  0);
+        EXPECT_NE(NvlinkTransportTestPeer::Register(
+                      s.transport, static_cast<char*>(s.base) + 4096, 4096),
+                  0);
+        EXPECT_EQ(s.driver.retain_calls, 0);
+        EXPECT_TRUE(s.owner->Release().ok());
+    }
+}
+
+// The promise marks entry into a driver call, after the registry decision.
+// A second promise releases it; there are no timing-dependent sleeps.
+TEST(NvlinkHostNumaRegistrationTest, RegisterPinWinsBeforeRelease) {
+    RegistrationScenario s;
+    std::promise<void> entered, resume;
+    auto gate = resume.get_future();
+    s.driver.before_retain = [&] {
+        entered.set_value();
+        gate.wait();
+    };
+    auto registered =
+        std::async(std::launch::async, [&] { return s.Register(); });
+    entered.get_future().wait();
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.unmap_calls, 0);
+    resume.set_value();
+    EXPECT_EQ(registered.get(), 0);
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_TRUE(s.owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest, ReleaseWinsBeforeRegisterPin) {
+    RegistrationScenario s;
+    s.driver.unmap_failures = 1;
+    std::promise<void> entered, resume;
+    auto gate = resume.get_future();
+    s.driver.before_unmap = [&] {
+        entered.set_value();
+        gate.wait();
+    };
+    auto released =
+        std::async(std::launch::async, [&] { return s.owner->Release(); });
+    entered.get_future().wait();
+    std::promise<void> register_started;
+    auto registered = std::async(std::launch::async, [&] {
+        register_started.set_value();
+        return s.Register();
+    });
+    register_started.get_future().wait();
+    resume.set_value();
+    EXPECT_FALSE(released.get().ok());
+    EXPECT_NE(registered.get(), 0);
+    EXPECT_EQ(s.driver.retain_calls, 0);
+    s.driver.before_unmap = {};
+    EXPECT_TRUE(s.owner->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     FailedOldHandleMustBeCleanedBeforeAddressReuse) {
+    RegistrationScenario s;
+    ASSERT_EQ(s.Register(), 0);
+    s.driver.release_failures = 1;
+    EXPECT_EQ(s.Unregister(), ERR_MEMORY);
+    EXPECT_FALSE(s.owner->Release().ok());
+    EXPECT_EQ(s.driver.free_calls, 0);
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_TRUE(s.owner->Release().ok());
+
+    FakeRegistrationDriver next_driver;
+    auto next = NvlinkTransportTestPeer::MakeOwnedRange(
+        s.base, s.length, next_driver.api(), true);
+    ASSERT_NE(next, nullptr);
+    EXPECT_EQ(s.Register(), 0);
+    EXPECT_EQ(next_driver.retain_calls, 1);
+    EXPECT_EQ(s.driver.retain_calls, 1);
+    EXPECT_EQ(s.Unregister(), 0);
+    EXPECT_EQ(next_driver.release_calls, 1);
+    EXPECT_EQ(s.driver.release_calls, 2);
+    EXPECT_TRUE(next->Release().ok());
+}
+
+TEST(NvlinkHostNumaRegistrationTest,
+     BatchRetriesPublicationThenPartialHandleRelease) {
+    constexpr size_t length = 64 * 1024;
+    void* a = reinterpret_cast<void*>(0xc00000000ULL);
+    void* b = reinterpret_cast<void*>(0xd00000000ULL);
+    FakeRegistrationDriver da, db;
+    auto oa =
+        NvlinkTransportTestPeer::MakeOwnedRange(a, length, da.api(), true);
+    auto ob =
+        NvlinkTransportTestPeer::MakeOwnedRange(b, length, db.api(), true);
+    ASSERT_NE(oa, nullptr);
+    ASSERT_NE(ob, nullptr);
+    NvlinkTransport transport;
+    NvlinkTransportTestPeer::Configure(transport);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, a, length), 0);
+    ASSERT_EQ(NvlinkTransportTestPeer::Register(transport, b, length), 0);
+    int removes = 0, updates = 0;
+    int publication_result = ERR_METADATA;
+    auto remove = [&](void*, bool publish) {
+        EXPECT_FALSE(publish);
+        ++removes;
+        return 0;
+    };
+    auto update = [&] {
+        ++updates;
+        return publication_result;
+    };
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(transport, {a, b},
+                                                       remove, update),
+              ERR_METADATA);
+    EXPECT_EQ(removes, 2);
+    EXPECT_EQ(da.release_calls + db.release_calls, 0);
+    EXPECT_FALSE(oa->Release().ok());
+    EXPECT_FALSE(ob->Release().ok());
+    publication_result = 0;
+    db.release_failures = 2;
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(transport, {a, b},
+                                                       remove, update),
+              ERR_MEMORY);
+    EXPECT_EQ(removes, 2);
+    EXPECT_EQ(da.release_calls, 1);
+    EXPECT_EQ(db.release_calls, 1);
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(transport, {a, b},
+                                                       remove, update),
+              ERR_MEMORY);
+    EXPECT_EQ(da.release_calls, 1);
+    EXPECT_EQ(db.release_calls, 2);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 1U);
+    EXPECT_EQ(removes, 2);
+    EXPECT_FALSE(ob->Release().ok());
+    EXPECT_EQ(NvlinkTransportTestPeer::UnregisterBatch(transport, {a, b},
+                                                       remove, update),
+              0);
+    EXPECT_EQ(da.release_calls, 1);
+    EXPECT_EQ(db.release_calls, 3);
+    EXPECT_EQ(NvlinkTransportTestPeer::RegistrationCount(transport), 0U);
+    EXPECT_TRUE(oa->Release().ok());
+    EXPECT_TRUE(ob->Release().ok());
+}
+
+}  // namespace
+#endif
+
 static void checkCudaError(cudaError_t result, const char* message) {
     if (result != cudaSuccess) {
         LOG(ERROR) << message << " (Error code: " << result << " - "
@@ -152,4 +1091,4 @@ int main(int argc, char** argv) {
     gflags::ParseCommandLineFlags(&argc, &argv, false);
     ::testing::InitGoogleTest(&argc, argv);
     return RUN_ALL_TESTS();
-}
\ No newline at end of file
+}
diff --git a/mooncake-transfer-engine/tests/nvmeof_transport_test.cpp b/mooncake-transfer-engine/tests/nvmeof_transport_test.cpp
index 13e285bd58..20b12257ce 100644
--- a/mooncake-transfer-engine/tests/nvmeof_transport_test.cpp
+++ b/mooncake-transfer-engine/tests/nvmeof_transport_test.cpp
@@ -197,8 +197,6 @@ TEST_F(NVMeofTransportTest, MultipleRead) {
                      kDataLength);
         ASSERT_EQ(ret, 0);
     }
-    engine->unregisterLocalMemory(addr);
-    freeMemoryPool(addr, ram_buffer_size);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/rdma_batch_reuse_test.cpp b/mooncake-transfer-engine/tests/rdma_batch_reuse_test.cpp
new file mode 100644
index 0000000000..d295d98f37
--- /dev/null
+++ b/mooncake-transfer-engine/tests/rdma_batch_reuse_test.cpp
@@ -0,0 +1,174 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include "common.h"
+#include "transport/rdma_transport/rdma_batch_cache.h"
+
+using namespace mooncake;
+namespace {
+using Desc = TransferMetadata::SegmentDesc;
+using Buffer = TransferMetadata::BufferDesc;
+std::shared_ptr<Desc> segment(const std::string &location = "cpu:0",
+                              bool multi_rail = false) {
+    auto d = std::make_shared<Desc>();
+    d->name = "test:1234";
+    d->protocol = "rdma";
+    Buffer b;
+    b.addr = 4096;
+    b.length = 8192;
+    b.name = location;
+    b.lkey = {1, 2};
+    b.rkey = {3, 4};
+    d->buffers.push_back(b);
+    d->rebuildBufferRangeIndex();
+    EXPECT_EQ(
+        d->topology.parse(multi_rail ? R"({"cpu:0":[["mlx5_0","mlx5_1"],[]]})"
+                                     : R"({"cpu:0":[["mlx5_0"],[]]})"),
+        0);
+    return d;
+}
+int select(BatchRdmaDeviceCache &cache, const std::shared_ptr<Desc> &d,
+           uint64_t addr, size_t size, int &b, int &dev, int &calls) {
+    return cache.select(d, addr, size, b, dev, [&] {
+        ++calls;
+        return RdmaTransport::selectDevice(d.get(), addr, size, b, dev);
+    });
+}
+// Mirrors WorkerPool::selectPeerDevice's post-select rkey / devices bounds
+// checks. Cache hits must skip this resolve, including those checks.
+int selectPeer(BatchRdmaDeviceCache &cache, const std::shared_ptr<Desc> &d,
+               uint64_t addr, size_t size, int &b, int &dev, int &calls) {
+    return cache.select(d, addr, size, b, dev, [&] {
+        ++calls;
+        const int rc = RdmaTransport::selectDevice(d.get(), addr, size, b, dev);
+        if (rc) return rc;
+        if (b < 0 || static_cast<size_t>(b) >= d->buffers.size() || dev < 0 ||
+            static_cast<size_t>(dev) >= d->buffers[b].rkey.size())
+            return ERR_ADDRESS_NOT_REGISTERED;
+        if (static_cast<size_t>(dev) >= d->devices.size())
+            return ERR_ADDRESS_NOT_REGISTERED;
+        return 0;
+    });
+}
+TEST(BatchRdmaDeviceCache, ReusesSingleRailAcrossOffsets) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    for (int i = 0; i < 16; ++i) {
+        ASSERT_EQ(select(cache, d, 4096 + i * 32, 32, b, dev, calls), 0);
+        EXPECT_EQ(b, 0);
+        EXPECT_EQ(dev, 0);
+    }
+    EXPECT_EQ(calls, 1);
+}
+TEST(BatchRdmaDeviceCache, DoesNotReuseAcrossRegionOrGap) {
+    auto d = segment();
+    auto b2 = d->buffers[0];
+    b2.addr = 16384;
+    d->buffers.push_back(b2);
+    d->rebuildBufferRangeIndex();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    ASSERT_EQ(select(cache, d, 16384, 32, b, dev, calls), 0);
+    EXPECT_EQ(b, 1);
+    EXPECT_NE(select(cache, d, 12288, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 3);
+}
+TEST(BatchRdmaDeviceCache, RejectsCrossBoundaryAndOverflow) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    EXPECT_NE(select(cache, d, 12280, 32, b, dev, calls), 0);
+    EXPECT_NE(select(cache, d, UINT64_MAX - 8, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 3);
+}
+TEST(BatchRdmaDeviceCache, MultiRailRetainsPerRequestSelection) {
+    auto d = segment("cpu:0", true);
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    for (int i = 0; i < 16; ++i)
+        ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 16);
+}
+TEST(BatchRdmaDeviceCache, SegmentedLocationRetainsOffsetResolution) {
+    auto d = segment("segments:4096:0,1");
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    ASSERT_EQ(select(cache, d, 8192, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 2);
+}
+TEST(BatchRdmaDeviceCache, OverlapRetainsFirstMatch) {
+    auto d = segment();
+    auto narrow = d->buffers[0];
+    narrow.addr = 8192;
+    narrow.length = 32;
+    d->buffers.insert(d->buffers.begin(), narrow);
+    d->rebuildBufferRangeIndex();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    EXPECT_EQ(b, 1);
+    ASSERT_EQ(select(cache, d, 8192, 32, b, dev, calls), 0);
+    EXPECT_EQ(b, 0);
+    EXPECT_EQ(calls, 2);
+}
+TEST(BatchRdmaDeviceCache, RefreshUsesNewSnapshot) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    d = segment();
+    d->buffers[0].name = "unknown";
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 2);
+}
+TEST(BatchRdmaDeviceCache, FailureIsNotCached) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    for (int i = 0; i < 2; ++i) {
+        EXPECT_EQ(cache.select(d, 4096, 32, b, dev,
+                               [&] {
+                                   ++calls;
+                                   return ERR_ADDRESS_NOT_REGISTERED;
+                               }),
+                  ERR_ADDRESS_NOT_REGISTERED);
+    }
+    EXPECT_EQ(calls, 2);
+}
+TEST(BatchRdmaDeviceCache, PeerDeviceBoundsFailureIsNotCached) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    for (int i = 0; i < 2; ++i) {
+        EXPECT_EQ(selectPeer(cache, d, 4096, 32, b, dev, calls),
+                  ERR_ADDRESS_NOT_REGISTERED);
+    }
+    EXPECT_EQ(calls, 2);
+}
+TEST(BatchRdmaDeviceCache, InvalidateDropsHit) {
+    auto d = segment();
+    BatchRdmaDeviceCache cache;
+    int calls = 0, b = -1, dev = -1;
+    ASSERT_EQ(select(cache, d, 4096, 32, b, dev, calls), 0);
+    cache.invalidate();
+    ASSERT_EQ(select(cache, d, 4128, 32, b, dev, calls), 0);
+    EXPECT_EQ(calls, 2);
+}
+}  // namespace
diff --git a/mooncake-transfer-engine/tests/rdma_buffer_range_index_test.cpp b/mooncake-transfer-engine/tests/rdma_buffer_range_index_test.cpp
new file mode 100644
index 0000000000..cab31f43e3
--- /dev/null
+++ b/mooncake-transfer-engine/tests/rdma_buffer_range_index_test.cpp
@@ -0,0 +1,346 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <random>
+#include <string>
+#include <vector>
+
+#include "buffer_range_index.h"
+#include "common.h"
+#include "memory_location.h"
+#include "transfer_metadata.h"
+#include "transport/rdma_transport/rdma_transport.h"
+
+using namespace mooncake;
+
+namespace {
+
+using SegmentDesc = TransferMetadata::SegmentDesc;
+using BufferDesc = TransferMetadata::BufferDesc;
+
+BufferDesc MakeBuffer(uint64_t addr, uint64_t length, int index) {
+    BufferDesc buffer;
+    buffer.name = "cpu:0";
+    buffer.addr = addr;
+    buffer.length = length;
+    buffer.lkey = {static_cast<BufferDesc::mr_key_t>(index + 1)};
+    buffer.rkey = {static_cast<BufferDesc::mr_key_t>(index + 1)};
+    return buffer;
+}
+
+SegmentDesc MakeSegment(const std::vector<BufferDesc> &buffers) {
+    SegmentDesc desc;
+    desc.name = "unit-test-server:1234";
+    desc.protocol = "rdma";
+    desc.buffers = buffers;
+    EXPECT_EQ(desc.topology.parse(R"({"cpu:0": [["mlx5_unit_test"], []]})"), 0);
+    desc.rebuildBufferRangeIndex();
+    return desc;
+}
+
+// The rule selectDevice() has to reproduce: lowest buffer index that is
+// selectable, covers the range, and resolves to a device.
+int LinearFirstMatch(SegmentDesc *desc, uint64_t offset, size_t length,
+                     int &buffer_id, int &device_id) {
+    if (!desc) return ERR_ADDRESS_NOT_REGISTERED;
+    for (int i = 0; i < static_cast<int>(desc->buffers.size()); ++i) {
+        const auto &buffer = desc->buffers[static_cast<size_t>(i)];
+#ifdef ENABLE_MULTI_PROTOCOL
+        if (!buffer.protocol.empty() && buffer.protocol != "rdma") continue;
+#endif
+        if (!bufferCoversRange(buffer.addr, buffer.length, offset, length)) {
+            continue;
+        }
+        int selected = desc->topology.selectDevice(buffer.name, 0);
+        if (selected < 0) {
+            selected = desc->topology.selectDevice(kWildcardLocation, 0);
+        }
+        if (selected < 0) continue;
+        buffer_id = i;
+        device_id = selected;
+        return 0;
+    }
+    return ERR_ADDRESS_NOT_REGISTERED;
+}
+
+}  // namespace
+
+TEST(BufferRangeIndex, DisjointLookupMatchesLinearScan) {
+    constexpr int kRegions = 256;
+    constexpr uint64_t kStride = 0x100000;
+    constexpr uint64_t kLength = 0x80000;
+    std::vector<BufferDesc> buffers;
+    buffers.reserve(kRegions);
+    for (int i = 0; i < kRegions; ++i) {
+        buffers.push_back(MakeBuffer(0x100000000ULL + i * kStride, kLength, i));
+    }
+    auto desc = MakeSegment(buffers);
+    ASSERT_FALSE(desc.buffer_range_index.overlaps());
+    ASSERT_EQ(desc.buffer_range_index.size(), static_cast<size_t>(kRegions));
+
+    for (int i = 0; i < kRegions; ++i) {
+        const uint64_t addr = buffers[i].addr + 32;
+        const size_t length = 32256;
+        int linear_buffer = -1, linear_device = -1;
+        int indexed_buffer = -1, indexed_device = -1;
+        ASSERT_EQ(
+            LinearFirstMatch(&desc, addr, length, linear_buffer, linear_device),
+            0);
+        ASSERT_EQ(RdmaTransport::selectDevice(&desc, addr, length,
+                                              indexed_buffer, indexed_device),
+                  0);
+        EXPECT_EQ(indexed_buffer, linear_buffer);
+        EXPECT_EQ(indexed_buffer, i);
+        EXPECT_EQ(indexed_device, linear_device);
+
+        EXPECT_EQ(desc.buffer_range_index.findCovering(addr, length), i);
+        EXPECT_EQ(desc.buffer_range_index.findCovering(addr, 0), i);
+    }
+
+    int missing_buffer = -1, missing_device = -1;
+    EXPECT_EQ(RdmaTransport::selectDevice(
+                  &desc, buffers.back().addr + buffers.back().length, 16,
+                  missing_buffer, missing_device),
+              ERR_ADDRESS_NOT_REGISTERED);
+}
+
+TEST(BufferRangeIndex, LastHitHintSkipsScanWhenStillValid) {
+    std::vector<BufferDesc> buffers = {
+        MakeBuffer(0x1000, 0x1000, 0),
+        MakeBuffer(0x3000, 0x1000, 1),
+        MakeBuffer(0x5000, 0x1000, 2),
+    };
+    auto desc = MakeSegment(buffers);
+
+    int buffer_id = -1, device_id = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x3080, 16, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 1);
+
+    int hinted = -1;
+    ASSERT_EQ(RdmaTransport::selectDevice(&desc, 0x3100, 32, hinted, device_id,
+                                          0, buffer_id),
+              0);
+    EXPECT_EQ(hinted, 1);
+
+    int jumped = -1;
+    ASSERT_EQ(RdmaTransport::selectDevice(&desc, 0x5080, 16, jumped, device_id,
+                                          0, buffer_id),
+              0);
+    EXPECT_EQ(jumped, 2);
+}
+
+TEST(BufferRangeIndex, OverlapLeavesLookupsToTheLinearScan) {
+    // Buffer 0 comes first in the list and overlaps buffer 1. A covering MR is
+    // no longer unique, so the index declines to answer and selectDevice keeps
+    // the original first-match rule.
+    std::vector<BufferDesc> buffers = {
+        MakeBuffer(0x1000, 0x1000, 0),  // [0x1000, 0x2000)
+        MakeBuffer(0x1800, 0x1000, 1),  // [0x1800, 0x2800)
+    };
+    auto desc = MakeSegment(buffers);
+    ASSERT_TRUE(desc.buffer_range_index.overlaps());
+    EXPECT_EQ(desc.buffer_range_index.findCovering(0x1900, 0x80), -1);
+
+    int buffer_id = -1, device_id = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x1900, 0x80, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 0);
+}
+
+TEST(BufferRangeIndex, HintDoesNotOverrideEarlierOverlappingBuffer) {
+    std::vector<BufferDesc> buffers = {
+        MakeBuffer(0x1000, 0x1000, 0),  // [0x1000, 0x2000)
+        MakeBuffer(0x1800, 0x1000, 1),  // [0x1800, 0x2800)
+    };
+    auto desc = MakeSegment(buffers);
+
+    int buffer_id = -1, device_id = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x2100, 16, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 1);
+
+    int hinted = -1;
+    ASSERT_EQ(RdmaTransport::selectDevice(&desc, 0x1900, 0x80, hinted,
+                                          device_id, 0, buffer_id),
+              0);
+    EXPECT_EQ(hinted, 0);
+}
+
+TEST(BufferRangeIndex, RebuildSeesMetadataUpdates) {
+    std::vector<BufferDesc> buffers = {MakeBuffer(0x1000, 0x1000, 0)};
+    auto desc = MakeSegment(buffers);
+
+    int buffer_id = -1, device_id = -1;
+    EXPECT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x2100, 16, buffer_id, device_id),
+        ERR_ADDRESS_NOT_REGISTERED);
+
+    desc.buffers.push_back(MakeBuffer(0x2000, 0x1000, 1));
+    desc.rebuildBufferRangeIndex();
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x2100, 16, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 1);
+}
+
+TEST(BufferRangeIndex, StaleIndexStillAnswersThroughTheLinearScan) {
+    // A descriptor that mutates `buffers` without rebuilding must degrade to
+    // the linear scan, not to a per-lookup rebuild.
+    std::vector<BufferDesc> buffers = {MakeBuffer(0x1000, 0x1000, 0)};
+    auto desc = MakeSegment(buffers);
+    desc.buffers.push_back(MakeBuffer(0x2000, 0x1000, 1));
+    ASSERT_NE(desc.buffer_range_index.size(), desc.buffers.size());
+
+    int linear_buffer = -1, linear_device = -1;
+    int actual_buffer = -1, actual_device = -1;
+    ASSERT_EQ(LinearFirstMatch(&desc, 0x2100, 16, linear_buffer, linear_device),
+              0);
+    ASSERT_EQ(RdmaTransport::selectDevice(&desc, 0x2100, 16, actual_buffer,
+                                          actual_device),
+              0);
+    EXPECT_EQ(actual_buffer, linear_buffer);
+    EXPECT_EQ(actual_device, linear_device);
+}
+
+TEST(BufferRangeIndex, AdjacentRegionsAreNotOverlapping) {
+    std::vector<BufferDesc> buffers = {
+        MakeBuffer(0x1000, 0x1000, 0),
+        MakeBuffer(0x2000, 0x1000, 1),
+    };
+    auto desc = MakeSegment(buffers);
+    const auto &index = desc.buffer_range_index;
+    EXPECT_FALSE(index.overlaps());
+
+    EXPECT_EQ(index.findCovering(0x1fff, 1), 0);
+    EXPECT_EQ(index.findCovering(0x2000, 1), 1);
+    // A zero length is point containment, so the shared boundary belongs to
+    // the second region only. The linear scan has to agree.
+    EXPECT_EQ(index.findCovering(0x2000, 0), 1);
+    int linear_buffer = -1, linear_device = -1;
+    ASSERT_EQ(LinearFirstMatch(&desc, 0x2000, 0, linear_buffer, linear_device),
+              0);
+    EXPECT_EQ(linear_buffer, 1);
+    EXPECT_EQ(index.findCovering(0x3000, 0), -1);
+}
+
+TEST(BufferRangeIndex, LastHitReusesHintDevice) {
+    auto desc = MakeSegment({MakeBuffer(0x1000, 0x1000, 0)});
+    int buffer_id = -1, device_id = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x1080, 16, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 0);
+    const int first_device = device_id;
+
+    int hinted_buffer = -1, hinted_device = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x1100, 32, hinted_buffer,
+                                    hinted_device, 0, buffer_id, first_device),
+        0);
+    EXPECT_EQ(hinted_buffer, 0);
+    EXPECT_EQ(hinted_device, first_device);
+}
+
+TEST(BufferRangeIndex, DeviceHintDoesNotFollowBufferJump) {
+    auto desc = MakeSegment(
+        {MakeBuffer(0x1000, 0x1000, 0), MakeBuffer(0x2000, 0x1000, 1)});
+    int buffer_id = -1, device_id = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x1080, 16, buffer_id, device_id),
+        0);
+    EXPECT_EQ(buffer_id, 0);
+
+    int jumped_buffer = -1, jumped_device = -1;
+    ASSERT_EQ(
+        RdmaTransport::selectDevice(&desc, 0x2080, 16, jumped_buffer,
+                                    jumped_device, 0, buffer_id, device_id),
+        0);
+    EXPECT_EQ(jumped_buffer, 1);
+}
+
+TEST(BufferRangeIndex, SelectDeviceMatchesLinearFirstMatch) {
+    std::mt19937 rng(2262008);
+    std::uniform_int_distribution<int> region_dist(1, 64);
+    std::uniform_int_distribution<uint64_t> gap_dist(0x1000, 0x100000);
+    std::uniform_int_distribution<uint64_t> len_dist(0x100, 0x8000);
+    std::uniform_int_distribution<int> overlap_coin(0, 4);
+    std::uniform_int_distribution<int> query_kind(0, 9);
+
+    int compared = 0;
+    for (int trial = 0; trial < 64; ++trial) {
+        const int n = region_dist(rng);
+        std::vector<BufferDesc> buffers;
+        buffers.reserve(static_cast<size_t>(n));
+        uint64_t cursor = 0x100000000ULL;
+        for (int i = 0; i < n; ++i) {
+            const uint64_t length = len_dist(rng);
+            uint64_t addr = cursor;
+            if (i > 0 && overlap_coin(rng) == 0) {
+                addr = buffers.back().addr + buffers.back().length / 2;
+            }
+            buffers.push_back(MakeBuffer(addr, length, i));
+            cursor = addr + length + gap_dist(rng);
+        }
+        auto desc = MakeSegment(buffers);
+        int hint = -1;
+        for (int q = 0; q < 2048; ++q) {
+            const int src = static_cast<int>(rng() % static_cast<unsigned>(n));
+            const int kind = query_kind(rng);
+            uint64_t addr = 0;
+            size_t length = 0;
+            if (kind == 0) {
+                // Zero length on an exact region boundary, where point and
+                // range containment disagree if they are not kept in sync.
+                addr = buffers[src].addr + buffers[src].length;
+            } else if (kind == 1) {
+                addr = buffers[src].addr;
+                length = static_cast<size_t>(buffers[src].length);
+            } else {
+                const uint64_t offset_in =
+                    rng() % std::max<uint64_t>(1, buffers[src].length / 2);
+                addr = buffers[src].addr + offset_in;
+                length = static_cast<size_t>(
+                    std::min<uint64_t>(64, buffers[src].length - offset_in));
+            }
+            int linear_buffer = -1, linear_device = -1;
+            int indexed_buffer = -1, indexed_device = -1;
+            const int linear_ret = LinearFirstMatch(
+                &desc, addr, length, linear_buffer, linear_device);
+            const int indexed_ret = RdmaTransport::selectDevice(
+                &desc, addr, length, indexed_buffer, indexed_device, 0, hint);
+            ASSERT_EQ(indexed_ret, linear_ret)
+                << "trial=" << trial << " q=" << q << " addr=" << addr
+                << " length=" << length;
+            if (linear_ret == 0) {
+                ASSERT_EQ(indexed_buffer, linear_buffer)
+                    << "trial=" << trial << " q=" << q << " addr=" << addr
+                    << " length=" << length;
+                EXPECT_EQ(indexed_device, linear_device);
+                hint = indexed_buffer;
+            } else {
+                hint = -1;
+            }
+            ++compared;
+        }
+    }
+    EXPECT_GE(compared, 100000);
+}
diff --git a/mooncake-transfer-engine/tests/rdma_context_reprobe_test.cpp b/mooncake-transfer-engine/tests/rdma_context_reprobe_test.cpp
index 66a9454a9e..d89d7e1994 100644
--- a/mooncake-transfer-engine/tests/rdma_context_reprobe_test.cpp
+++ b/mooncake-transfer-engine/tests/rdma_context_reprobe_test.cpp
@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#include <glog/logging.h>
 #include <gtest/gtest.h>
 
 #include <algorithm>
@@ -28,8 +29,12 @@
 #include "error.h"
 #include "rdma_test_peers.h"
 #include "transfer_metadata.h"
+#include "ib_link_speed.h"
 #include "transport/rdma_transport/rdma_context.h"
 #include "transport/rdma_transport/rdma_transport.h"
+#ifdef USE_SHCA
+#include <infiniband/shca_17b_types.h>
+#endif
 
 #if defined(__has_feature)
 #define MC_HAS_FEATURE(x) __has_feature(x)
@@ -54,6 +59,10 @@ struct FakeVerbsDevice {
     ibv_device *device_list[2] = {&device, nullptr};
     ibv_context context = {};
     size_t alloc_pd_calls = 0;
+    // Reported by the interposed ibv_query_port.
+    uint8_t active_speed = 0;
+    uint8_t active_width = 0;
+    uint32_t active_speed_ex = 0;
 };
 
 FakeVerbsDevice fake_verbs;
@@ -65,6 +74,9 @@ class FakeVerbsDeviceScope {
         fake_verbs.context = {};
         fake_verbs.context.num_comp_vectors = num_comp_vectors;
         fake_verbs.alloc_pd_calls = 0;
+        fake_verbs.active_speed = 0;
+        fake_verbs.active_width = 0;
+        fake_verbs.active_speed_ex = 0;
     }
 
     ~FakeVerbsDeviceScope() { fake_verbs.enabled = false; }
@@ -109,8 +121,17 @@ int ibv_query_port(ibv_context *context, uint8_t,
     auto *port_attr = reinterpret_cast<ibv_port_attr *>(compat_port_attr);
     *port_attr = {};
     port_attr->state = IBV_PORT_ACTIVE;
+#ifdef USE_SHCA
+    port_attr->lid = u32_to_17(1);
+#else
     port_attr->lid = 1;
+#endif
     port_attr->active_mtu = IBV_MTU_4096;
+    port_attr->active_speed = fake_verbs.active_speed;
+    port_attr->active_width = fake_verbs.active_width;
+#ifdef HAVE_IBV_ACTIVE_SPEED_EX
+    port_attr->active_speed_ex = fake_verbs.active_speed_ex;
+#endif
     return 0;
 }
 
@@ -176,6 +197,70 @@ TEST_F(RdmaContextConstructionTest, RejectsZeroCompletionChannelsBeforeSetup) {
     EXPECT_FALSE(RdmaContextTestPeer::hasEndpointStore(*context_));
 }
 
+TEST_F(RdmaContextConstructionTest, LogsPortNumberAsIntegerNotCharacter) {
+    // `port` is a uint8_t; streaming it raw into glog renders the byte as a
+    // control character, so the operator sees "on port \x01" instead of the
+    // number they configured. The failure path for a missing device is enough
+    // to exercise the log line.
+    const bool saved_logtostderr = FLAGS_logtostderr;
+    FLAGS_logtostderr = true;
+    ::testing::internal::CaptureStderr();
+    EXPECT_EQ(context_->construct(/*num_cq_list=*/1,
+                                  /*num_comp_channels=*/1,
+                                  /*port=*/1,
+                                  /*gid_index=*/-1),
+              ERR_CONTEXT);
+    const std::string log = ::testing::internal::GetCapturedStderr();
+    FLAGS_logtostderr = saved_logtostderr;
+
+    EXPECT_NE(log.find("on port 1 with GID"), std::string::npos) << log;
+    EXPECT_EQ(log.find(std::string("on port \x01")), std::string::npos) << log;
+}
+
+// openRdmaDevice() records the negotiated speed before construct() goes on
+// to validate completion vectors, so a device with none lets the recorded
+// values be inspected without allocating anything.
+TEST_F(RdmaContextConstructionTest, RecordsNegotiatedPortSpeedAndWidth) {
+#ifdef __linux__
+    FakeVerbsDeviceScope fake_device(/*num_comp_vectors=*/0);
+    fake_verbs.active_speed = 64;  // HDR, 50 Gb/s per lane
+    fake_verbs.active_width = 2;   // 4x
+
+    EXPECT_EQ(context_->construct(1, 1, /*port=*/1, /*gid_index=*/0),
+              ERR_CONTEXT);
+    EXPECT_EQ(context_->activeSpeed(), 64);
+    EXPECT_EQ(context_->activeWidth(), 2);
+    EXPECT_DOUBLE_EQ(
+        ibLinkSpeedGbps(context_->activeSpeed(), context_->activeWidth()),
+        200.0);
+    RdmaContextTestPeer::disableContextForTeardown(*context_);
+#else
+    GTEST_SKIP() << "Requires Linux libibverbs symbol interposition";
+#endif
+}
+
+// XDR's encoding (256) does not fit ibv_port_attr::active_speed (uint8_t),
+// which reads 0; rdma-core carries it in active_speed_ex. show_links must
+// report 800 Gbps for XDR 4x, not 0.
+TEST_F(RdmaContextConstructionTest, PrefersActiveSpeedExForXdr) {
+#if defined(__linux__) && defined(HAVE_IBV_ACTIVE_SPEED_EX)
+    FakeVerbsDeviceScope fake_device(/*num_comp_vectors=*/0);
+    fake_verbs.active_speed = 0;       // what the uint8_t field reads for XDR
+    fake_verbs.active_speed_ex = 256;  // XDR
+    fake_verbs.active_width = 2;       // 4x
+
+    EXPECT_EQ(context_->construct(1, 1, /*port=*/1, /*gid_index=*/0),
+              ERR_CONTEXT);
+    EXPECT_EQ(context_->activeSpeed(), 256);
+    EXPECT_DOUBLE_EQ(
+        ibLinkSpeedGbps(context_->activeSpeed(), context_->activeWidth()),
+        800.0);
+    RdmaContextTestPeer::disableContextForTeardown(*context_);
+#else
+    GTEST_SKIP() << "Requires Linux and ibv_port_attr::active_speed_ex";
+#endif
+}
+
 TEST_F(RdmaContextConstructionTest,
        RejectsDeviceWithoutCompletionVectorsBeforeAllocatingResources) {
 #ifdef __linux__
diff --git a/mooncake-transfer-engine/tests/rdma_endpoint_reestablish_test.cpp b/mooncake-transfer-engine/tests/rdma_endpoint_reestablish_test.cpp
index c98fc20b44..5d2a57c133 100644
--- a/mooncake-transfer-engine/tests/rdma_endpoint_reestablish_test.cpp
+++ b/mooncake-transfer-engine/tests/rdma_endpoint_reestablish_test.cpp
@@ -839,11 +839,11 @@ class RdmaEndPointTestPeer {
         endpoint.qp_list_.clear();
     }
 
-    static int doSetupConnection(RdmaEndPoint &endpoint, int qp_index,
-                                 const ibv_gid &peer_gid, uint16_t peer_lid,
+    static int doSetupConnection(RdmaEndPoint& endpoint, int qp_index,
+                                 const ibv_gid& peer_gid, uint32_t peer_lid,
                                  uint32_t peer_qp_num, int local_gid_index,
-                                 std::string *reply_msg,
-                                 int &out_stage, int &out_sys_errno) {
+                                 std::string* reply_msg, int& out_stage,
+                                 int& out_sys_errno) {
         RdmaEndPoint::SetupConnectionFailureInfo failure_info = {};
         int rc = endpoint.doSetupConnection(qp_index, peer_gid, peer_lid,
                                             peer_qp_num, local_gid_index,
diff --git a/mooncake-transfer-engine/tests/rdma_endpoint_state_test.cpp b/mooncake-transfer-engine/tests/rdma_endpoint_state_test.cpp
index 5a2f4fe818..eca879a725 100644
--- a/mooncake-transfer-engine/tests/rdma_endpoint_state_test.cpp
+++ b/mooncake-transfer-engine/tests/rdma_endpoint_state_test.cpp
@@ -15,15 +15,29 @@
 #include <gtest/gtest.h>
 
 #include <atomic>
+#include <chrono>
+#include <condition_variable>
 #include <cstdint>
+#include <future>
+#include <limits>
 #include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
 #include <utility>
 #include <vector>
 
+#include "common.h"
+#include "config.h"
 #include "error.h"
+#include "transfer_metadata.h"
+#include "transfer_metadata_plugin.h"
+#include "topology.h"
+#include "transport/rdma_transport/endpoint_store.h"
 #include "transport/rdma_transport/rdma_context.h"
 #include "transport/rdma_transport/rdma_endpoint.h"
 #include "transport/rdma_transport/rdma_transport.h"
+#include "transport/rdma_transport/worker_pool.h"
 
 #if defined(__has_feature)
 #define MC_HAS_FEATURE(x) __has_feature(x)
@@ -41,6 +55,143 @@ using namespace mooncake;
 
 namespace mooncake {
 
+class RdmaTransportTestPeer {
+   public:
+    static void bindMetadata(RdmaTransport &transport,
+                             std::shared_ptr<TransferMetadata> metadata,
+                             const std::string &local_server_name) {
+        transport.metadata_ = std::move(metadata);
+        transport.local_server_name_ = local_server_name;
+        transport.rdma_server_name_ = local_server_name;
+    }
+
+    static void bindTopology(RdmaTransport &transport,
+                             std::shared_ptr<Topology> topology) {
+        transport.local_topology_ = std::move(topology);
+    }
+
+    static void addContext(RdmaTransport &transport,
+                           std::shared_ptr<RdmaContext> context) {
+        transport.context_list_.push_back(std::move(context));
+    }
+};
+
+class RdmaContextTestPeer {
+   public:
+    static void bindCompletionQueue(RdmaContext &context, ibv_cq *cq) {
+        context.cq_list_.emplace_back();
+        context.cq_list_.back().native = cq;
+        cq->cq_context = &context.cq_list_.back().outstanding;
+        context.gid_ = {};
+        context.gid_index_ = 0;
+        context.lid_ = 0;
+    }
+
+    static void bindFakeEndpointStore(RdmaContext &context, ibv_cq *cq) {
+        bindCompletionQueue(context, cq);
+        context.endpoint_store_ = std::make_shared<SIEVEEndpointStore>(8);
+        context.transfer_worker_count_ = 1;
+        context.endpoint_lifecycle_locks_.clear();
+        context.endpoint_lifecycle_locks_.push_back(
+            std::make_unique<std::mutex>());
+        context.active_.store(true, std::memory_order_release);
+    }
+
+    static std::unique_lock<std::mutex> tryLockEndpointLifecycle(
+        RdmaContext &context, const std::string &peer_nic_path) {
+        const int owner_thread = context.postingThreadForPeer(peer_nic_path);
+        if (owner_thread < 0 || static_cast<size_t>(owner_thread) >=
+                                    context.endpoint_lifecycle_locks_.size()) {
+            return std::unique_lock<std::mutex>();
+        }
+        return std::unique_lock<std::mutex>(
+            *context.endpoint_lifecycle_locks_[owner_thread], std::try_to_lock);
+    }
+
+    static void insertEndpointForTest(RdmaContext &context,
+                                      const std::string &peer_nic_path,
+                                      std::shared_ptr<RdmaEndPoint> endpoint) {
+        auto store = std::dynamic_pointer_cast<SIEVEEndpointStore>(
+            context.endpoint_store_);
+        ASSERT_NE(store, nullptr);
+        store->testOnlyInsertEndpoint(peer_nic_path, std::move(endpoint));
+    }
+
+    static void clearCompletionQueues(RdmaContext &context) {
+        context.cq_list_.clear();
+    }
+
+    static void clearNativeCompletionQueue(RdmaContext &context, int cq_index) {
+        ASSERT_GE(cq_index, 0);
+        ASSERT_LT(static_cast<size_t>(cq_index), context.cq_list_.size());
+        context.cq_list_[cq_index].native = nullptr;
+    }
+};
+
+class WorkerPoolTestPeer {
+   public:
+    static void stopWorkers(WorkerPool &pool) {
+        if (!pool.workers_running_.load(std::memory_order_acquire)) return;
+        pool.workers_running_.store(false, std::memory_order_release);
+        pool.cond_var_.notify_all();
+        for (auto &entry : pool.worker_thread_) {
+            if (entry.joinable()) entry.join();
+        }
+    }
+
+    static void queueSlice(WorkerPool &pool, int thread_id,
+                           const std::string &peer_nic_path,
+                           Transport::Slice *slice) {
+        pool.collective_slice_queue_[thread_id][peer_nic_path].push_back(slice);
+    }
+
+    static void performPostSend(WorkerPool &pool, int thread_id) {
+        pool.performPostSend(thread_id);
+    }
+
+    static void clearQueuedSlices(WorkerPool &pool) {
+        for (auto &queue : pool.collective_slice_queue_) queue.clear();
+        for (auto &queue : pool.worker_slice_queue_) queue.clear();
+    }
+
+    static uint64_t lastPollTs(const WorkerPool &pool) {
+        return pool.last_poll_ts_ns_.load(std::memory_order_acquire);
+    }
+
+    static bool waitForPollTs(WorkerPool &pool,
+                              std::chrono::milliseconds timeout) {
+        if (lastPollTs(pool) != 0) return true;
+
+        std::mutex mutex;
+        std::condition_variable cv;
+        bool observed = false;
+        std::thread waiter([&] {
+            uint64_t poll_ts =
+                pool.last_poll_ts_ns_.load(std::memory_order_acquire);
+            while (poll_ts == 0) {
+                pool.last_poll_ts_ns_.wait(poll_ts, std::memory_order_acquire);
+                poll_ts = pool.last_poll_ts_ns_.load(std::memory_order_acquire);
+            }
+            {
+                std::lock_guard<std::mutex> lock(mutex);
+                observed = true;
+            }
+            cv.notify_one();
+        });
+
+        std::unique_lock<std::mutex> lock(mutex);
+        const bool ok = cv.wait_for(lock, timeout, [&] { return observed; });
+        if (!ok) {
+            pool.last_poll_ts_ns_.store(std::numeric_limits<uint64_t>::max(),
+                                        std::memory_order_release);
+            pool.last_poll_ts_ns_.notify_all();
+        }
+        lock.unlock();
+        waiter.join();
+        return ok;
+    }
+};
+
 class RdmaEndPointTestPeer {
    public:
     static void setStatus(RdmaEndPoint &endpoint, RdmaEndPoint::Status status) {
@@ -56,12 +207,130 @@ class RdmaEndPointTestPeer {
                               std::vector<uint32_t> peer_qp_nums) {
         endpoint.peer_qp_num_list_ = std::move(peer_qp_nums);
     }
+
+    static int reconstruct(RdmaEndPoint &endpoint) {
+        RWSpinlock::WriteGuard guard(endpoint.lock_);
+        return endpoint.reconstruct();
+    }
 };
 
 }  // namespace mooncake
 
 namespace {
 
+class InProcessRdmaTransport : public RdmaTransport {
+   public:
+    int sendHandshake(const std::string &peer_server_name,
+                      const HandShakeDesc &local_desc,
+                      HandShakeDesc &peer_desc) override {
+        (void)peer_server_name;
+        if (!local_desc.ready_ack) {
+            auto lifecycle_lock = RdmaContextTestPeer::tryLockEndpointLifecycle(
+                *local_context_, local_desc.peer_nic_path);
+            if (!lifecycle_lock.owns_lock()) {
+                lifecycle_gate_was_free_.store(false,
+                                               std::memory_order_release);
+                return ERR_ENDPOINT;
+            }
+            lifecycle_lock.unlock();
+
+            std::unique_lock<std::mutex> lock(barrier_->mutex);
+            ++barrier_->arrivals;
+            barrier_->cv.notify_all();
+            if (!barrier_->cv.wait_for(lock, std::chrono::seconds(5), [&] {
+                    return barrier_->arrivals >= barrier_->required_arrivals ||
+                           barrier_->released;
+                })) {
+                return ERR_ENDPOINT;
+            }
+            if (fail_after_barrier_) return ERR_ENDPOINT;
+        }
+
+        return peer_->onSetupRdmaConnections(local_desc, peer_desc);
+    }
+
+    bool lifecycleGateWasFree() const {
+        return lifecycle_gate_was_free_.load(std::memory_order_acquire);
+    }
+
+    struct Barrier {
+        std::mutex mutex;
+        std::condition_variable cv;
+        int arrivals = 0;
+        int required_arrivals = 2;
+        bool released = false;
+    };
+
+    RdmaContext *local_context_ = nullptr;
+    InProcessRdmaTransport *peer_ = nullptr;
+    std::shared_ptr<Barrier> barrier_;
+    bool fail_after_barrier_ = false;
+
+   private:
+    std::atomic<bool> lifecycle_gate_was_free_{true};
+};
+
+struct FakeRdmaPeer {
+    std::shared_ptr<TransferMetadata> metadata;
+    std::unique_ptr<InProcessRdmaTransport> transport;
+    std::shared_ptr<Topology> topology;
+    std::shared_ptr<RdmaContext> context;
+    ibv_cq cq = {};
+    std::unique_ptr<WorkerPool> worker_pool;
+    std::string server_name;
+    std::string device_name;
+};
+
+void initFakePeer(FakeRdmaPeer &peer, const std::string &server_name,
+                  const std::string &device_name,
+                  std::shared_ptr<InProcessRdmaTransport::Barrier> barrier) {
+    peer.server_name = server_name;
+    peer.device_name = device_name;
+    peer.metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    peer.transport = std::make_unique<InProcessRdmaTransport>();
+    RdmaTransportTestPeer::bindMetadata(*peer.transport, peer.metadata,
+                                        server_name);
+
+    peer.topology = std::make_shared<Topology>();
+    ASSERT_EQ(
+        peer.topology->parse("{\"cpu:0\": [[\"" + device_name + "\"], []]}"),
+        0);
+    RdmaTransportTestPeer::bindTopology(*peer.transport, peer.topology);
+
+    peer.context =
+        std::make_shared<RdmaContext>(*peer.transport, peer.device_name);
+    RdmaContextTestPeer::bindFakeEndpointStore(*peer.context, &peer.cq);
+    RdmaTransportTestPeer::addContext(*peer.transport, peer.context);
+
+    peer.transport->local_context_ = peer.context.get();
+    peer.transport->barrier_ = std::move(barrier);
+
+    peer.worker_pool = std::make_unique<WorkerPool>(*peer.context);
+    WorkerPoolTestPeer::stopWorkers(*peer.worker_pool);
+}
+
+void queueHandshakeSlice(FakeRdmaPeer &peer, const std::string &peer_nic_path,
+                         Transport::Slice &slice,
+                         Transport::TransferTask &task) {
+    slice = Transport::Slice();
+    task = Transport::TransferTask();
+    slice.task = &task;
+    slice.status = Transport::Slice::PENDING;
+    slice.peer_nic_path = peer_nic_path;
+    slice.rdma.retry_cnt = 0;
+    slice.rdma.max_retry_cnt = 8;
+    WorkerPoolTestPeer::queueSlice(*peer.worker_pool, 0, peer_nic_path, &slice);
+}
+
+void installZeroQpEndpoint(FakeRdmaPeer &peer,
+                           const std::string &peer_nic_path) {
+    auto endpoint = std::make_shared<RdmaEndPoint>(*peer.context);
+    ASSERT_EQ(endpoint->construct(&peer.cq, 0), 0);
+    endpoint->setPeerNicPath(peer_nic_path);
+    RdmaContextTestPeer::insertEndpointForTest(*peer.context, peer_nic_path,
+                                               std::move(endpoint));
+}
+
 class RdmaEndPointStateTest : public ::testing::Test {
    protected:
     void SetUp() override {
@@ -73,6 +342,11 @@ class RdmaEndPointStateTest : public ::testing::Test {
         endpoint_ = std::make_unique<RdmaEndPoint>(*context_);
     }
 
+    void TearDown() override {
+        endpoint_->destroyQP();
+        RdmaContextTestPeer::clearCompletionQueues(*context_);
+    }
+
     RdmaTransport *transport_ = nullptr;
     std::unique_ptr<RdmaContext> context_;
     std::unique_ptr<RdmaEndPoint> endpoint_;
@@ -145,4 +419,197 @@ TEST_F(RdmaEndPointStateTest, StaleReadyAckWithDifferentPeerQpDoesNotReset) {
     EXPECT_TRUE(endpoint_->readyAckTimedOut());
 }
 
+TEST_F(RdmaEndPointStateTest,
+       StaleActiveHandshakeReplyDoesNotConnectReconstructedEndpoint) {
+    TransferMetadata server_metadata(P2PHANDSHAKE);
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_NE(port, 0);
+    const std::string host = globalConfig().use_ipv6 ? "::1" : "127.0.0.1";
+    const std::string peer_server_name =
+        maybeWrapIpV6(host) + ":" + std::to_string(port);
+
+    std::mutex callback_mutex;
+    std::condition_variable callback_cv;
+    bool callback_started = false;
+    bool release_reply = false;
+    // Hold the Q1 reply until the test has reconstructed the endpoint as Q2.
+    ASSERT_EQ(server_metadata.startHandshakeDaemon(
+                  [&](const RdmaEndPoint::HandShakeDesc &peer_desc,
+                      RdmaEndPoint::HandShakeDesc &local_desc) {
+                      std::unique_lock<std::mutex> lock(callback_mutex);
+                      callback_started = true;
+                      callback_cv.notify_all();
+                      callback_cv.wait(lock, [&] { return release_reply; });
+
+                      local_desc.local_nic_path = peer_desc.peer_nic_path;
+                      local_desc.peer_nic_path = peer_desc.local_nic_path;
+                      local_desc.local_gid =
+                          "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00";
+                      local_desc.local_lid = 0;
+                      local_desc.qp_num.clear();
+                      local_desc.ready_ack_supported = false;
+                      return 0;
+                  },
+                  port, sockfd),
+              0);
+
+    auto client_metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    RdmaTransportTestPeer::bindMetadata(*transport_, client_metadata,
+                                        "rdma-endpoint-state-client");
+
+    // Zero QPs keep the regression hardware-free while still exercising the
+    // real active-handshake and reconstruct state transitions.
+    ibv_cq fake_cq = {};
+    RdmaContextTestPeer::bindCompletionQueue(*context_, &fake_cq);
+    ASSERT_EQ(endpoint_->construct(&fake_cq, 0), 0);
+    endpoint_->setPeerNicPath(peer_server_name + "@peer-nic");
+
+    auto active_result = std::async(std::launch::async, [&] {
+        return endpoint_->setupConnectionsByActive();
+    });
+
+    bool observed_callback = false;
+    {
+        std::unique_lock<std::mutex> lock(callback_mutex);
+        observed_callback = callback_cv.wait_for(
+            lock, std::chrono::seconds(5), [&] { return callback_started; });
+    }
+    if (!observed_callback) {
+        {
+            std::lock_guard<std::mutex> lock(callback_mutex);
+            release_reply = true;
+        }
+        callback_cv.notify_all();
+        if (active_result.wait_for(std::chrono::seconds(5)) ==
+            std::future_status::ready) {
+            active_result.get();
+        }
+        FAIL() << "Active handshake did not reach the blocking callback";
+    }
+
+    const int reconstruct_result =
+        RdmaEndPointTestPeer::reconstruct(*endpoint_);
+    const bool connected_after_reconstruct = endpoint_->connected();
+
+    // The successful Q1 reply is now stale and must not configure Q2.
+    {
+        std::lock_guard<std::mutex> lock(callback_mutex);
+        release_reply = true;
+    }
+    callback_cv.notify_all();
+
+    const int active_rc = active_result.get();
+    ASSERT_EQ(reconstruct_result, 0);
+    ASSERT_FALSE(connected_after_reconstruct);
+    EXPECT_EQ(active_rc, ERR_ENDPOINT);
+    EXPECT_FALSE(endpoint_->connected());
+}
+
+TEST(RdmaEndpointLifecycleGateTest,
+     BidirectionalActiveHandshakeDoesNotHoldLifecycleGateDuringRpc) {
+    auto barrier = std::make_shared<InProcessRdmaTransport::Barrier>();
+    FakeRdmaPeer peer_a;
+    FakeRdmaPeer peer_b;
+
+    ASSERT_NO_FATAL_FAILURE(
+        initFakePeer(peer_a, "rdma-gate-a:10000", "mlx5_gate_a", barrier));
+    ASSERT_NO_FATAL_FAILURE(
+        initFakePeer(peer_b, "rdma-gate-b:10000", "mlx5_gate_b", barrier));
+    peer_a.transport->peer_ = peer_b.transport.get();
+    peer_b.transport->peer_ = peer_a.transport.get();
+
+    const std::string a_to_b =
+        MakeNicPath(peer_b.server_name, peer_b.device_name);
+    const std::string b_to_a =
+        MakeNicPath(peer_a.server_name, peer_a.device_name);
+
+    ASSERT_NO_FATAL_FAILURE(installZeroQpEndpoint(peer_a, a_to_b));
+    ASSERT_NO_FATAL_FAILURE(installZeroQpEndpoint(peer_b, b_to_a));
+
+    Transport::Slice slice_a;
+    Transport::Slice slice_b;
+    Transport::TransferTask task_a;
+    Transport::TransferTask task_b;
+    queueHandshakeSlice(peer_a, a_to_b, slice_a, task_a);
+    queueHandshakeSlice(peer_b, b_to_a, slice_b, task_b);
+
+    auto active_a = std::async(std::launch::async, [&] {
+        WorkerPoolTestPeer::performPostSend(*peer_a.worker_pool, 0);
+    });
+    auto active_b = std::async(std::launch::async, [&] {
+        WorkerPoolTestPeer::performPostSend(*peer_b.worker_pool, 0);
+    });
+
+    ASSERT_EQ(active_a.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    ASSERT_EQ(active_b.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    active_a.get();
+    active_b.get();
+
+    EXPECT_TRUE(peer_a.transport->lifecycleGateWasFree());
+    EXPECT_TRUE(peer_b.transport->lifecycleGateWasFree());
+
+    auto endpoint_a = peer_a.context->findEndpoint(a_to_b);
+    auto endpoint_b = peer_b.context->findEndpoint(b_to_a);
+    ASSERT_NE(endpoint_a, nullptr);
+    ASSERT_NE(endpoint_b, nullptr);
+    EXPECT_TRUE(endpoint_a->readyToSend());
+    EXPECT_TRUE(endpoint_b->readyToSend());
+
+    WorkerPoolTestPeer::clearQueuedSlices(*peer_a.worker_pool);
+    WorkerPoolTestPeer::clearQueuedSlices(*peer_b.worker_pool);
+}
+
+TEST(RdmaEndpointLifecycleGateTest, ActiveHandshakeWaitDrainsOwnerCq) {
+    auto barrier = std::make_shared<InProcessRdmaTransport::Barrier>();
+    FakeRdmaPeer peer;
+
+    ASSERT_NO_FATAL_FAILURE(
+        initFakePeer(peer, "rdma-drain-a:10000", "mlx5_drain_a", barrier));
+    peer.transport->fail_after_barrier_ = true;
+
+    const std::string peer_nic_path =
+        MakeNicPath("rdma-drain-b:10000", "mlx5_drain_b");
+    ASSERT_NO_FATAL_FAILURE(installZeroQpEndpoint(peer, peer_nic_path));
+
+    // The fake CQ is not a real verbs object. Clearing the native pointer keeps
+    // the regression hardware-free while still proving the owner worker enters
+    // its CQ poll path during the blocked active handshake.
+    RdmaContextTestPeer::clearNativeCompletionQueue(*peer.context, 0);
+    peer.context->cqOutstandingCount(0)->store(1, std::memory_order_relaxed);
+
+    Transport::Slice slice;
+    Transport::TransferTask task;
+    queueHandshakeSlice(peer, peer_nic_path, slice, task);
+    slice.rdma.max_retry_cnt = 1;
+
+    auto active = std::async(std::launch::async, [&] {
+        WorkerPoolTestPeer::performPostSend(*peer.worker_pool, 0);
+    });
+
+    {
+        std::unique_lock<std::mutex> lock(barrier->mutex);
+        ASSERT_TRUE(barrier->cv.wait_for(lock, std::chrono::seconds(5), [&] {
+            return barrier->arrivals >= 1;
+        }));
+    }
+
+    EXPECT_TRUE(WorkerPoolTestPeer::waitForPollTs(*peer.worker_pool,
+                                                  std::chrono::seconds(5)));
+
+    {
+        std::lock_guard<std::mutex> lock(barrier->mutex);
+        barrier->released = true;
+    }
+    barrier->cv.notify_all();
+
+    ASSERT_EQ(active.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    active.get();
+
+    WorkerPoolTestPeer::clearQueuedSlices(*peer.worker_pool);
+}
+
 }  // namespace
diff --git a/mooncake-transfer-engine/tests/rdma_large_mr_test.cpp b/mooncake-transfer-engine/tests/rdma_large_mr_test.cpp
index fdf413703b..f997d2cb24 100644
--- a/mooncake-transfer-engine/tests/rdma_large_mr_test.cpp
+++ b/mooncake-transfer-engine/tests/rdma_large_mr_test.cpp
@@ -226,9 +226,10 @@ class RDMAGpuDmabufChunkTest : public ::testing::Test {
         ASSERT_EQ(cudaSetDevice(0), cudaSuccess);
 
 #if defined(USE_CUDA)
-        ASSERT_FALSE(Environ::Get().GetWithNvidiaPeermem())
-            << "Launch with WITH_NVIDIA_PEERMEM=0 so this test exercises "
-               "ibv_reg_dmabuf_mr instead of the nvidia-peermem fallback";
+        ASSERT_TRUE(Environ::Get().GetRdmaDataDirect() ||
+                    !Environ::Get().GetWithNvidiaPeermem())
+            << "Launch with WITH_NVIDIA_PEERMEM=0 or MC_RDMA_DATA_DIRECT=1 "
+               "so this test exercises DMA-BUF registration";
 #endif
 
         engine = std::make_unique<TransferEngine>(true);
diff --git a/mooncake-transfer-engine/tests/rdma_native_notify_test.cpp b/mooncake-transfer-engine/tests/rdma_native_notify_test.cpp
new file mode 100644
index 0000000000..0d656b938e
--- /dev/null
+++ b/mooncake-transfer-engine/tests/rdma_native_notify_test.cpp
@@ -0,0 +1,650 @@
+// Copyright 2026 KVCache.AI
+// 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.
+
+#include <gtest/gtest.h>
+#include <infiniband/verbs.h>
+#include <atomic>
+#include <chrono>
+#include <cstring>
+#include <optional>
+#include <future>
+#include <thread>
+#include <unordered_set>
+
+#include "config.h"
+#include "error.h"
+#include "transfer_engine.h"
+#include "transport/rdma_transport/rdma_transport.h"
+#include "transport/rdma_transport/rdma_endpoint.h"
+
+using namespace mooncake;
+using Notify = TransferMetadata::NotifyDesc;
+
+namespace mooncake {
+class RdmaContextTestPeer {
+   public:
+    static void drain(RdmaContext &context) {
+        while (context.pollNotificationCq() > 0) {
+        }
+    }
+    static ibv_cq *cq(RdmaContext &context) { return context.notify_cq_; }
+};
+class RdmaNotificationTestPeer {
+   public:
+    static constexpr size_t kSlots = RdmaEndPoint::kNotifySlots;
+    static constexpr size_t kSlotBytes = RdmaEndPoint::kNotifySlotBytes;
+    static constexpr size_t kHeaderBytes = RdmaEndPoint::kNotifyHeaderBytes;
+    static size_t encode(char *slot, const Notify &message) {
+        return RdmaEndPoint::encodeNotification(slot, message);
+    }
+    static bool decode(const char *slot, size_t bytes, Notify &message) {
+        return RdmaEndPoint::decodeNotification(slot, bytes, message);
+    }
+    static RdmaTransport *transport(TransferEngine &engine) {
+        auto *t = engine.getTransport("rdma");
+        if (!t) t = engine.getTransport("rdma_twosided");
+        return dynamic_cast<RdmaTransport *>(t);
+    }
+    static bool hasNativeService(TransferEngine &engine) {
+        auto *rdma = transport(engine);
+        return rdma && !rdma->getContextList().empty() &&
+               rdma->getContextList().front()->nativeNotifyEnabled();
+    }
+    static void stop(TransferEngine &engine) {
+        auto *rdma = transport(engine);
+        ASSERT_NE(rdma, nullptr);
+        for (auto &context : rdma->getContextList())
+            ASSERT_EQ(context->disconnectAllEndpoints(), 0);
+    }
+    static void restart(TransferEngine &engine) { stop(engine); }
+    static std::shared_ptr<RdmaEndPoint> endpoint(TransferEngine &engine,
+                                                  const std::string &peer) {
+        auto *rdma = transport(engine);
+        auto context = rdma->getContextList().front();
+        auto desc = rdma->meta()->getSegmentDescByName(peer);
+        if (!desc || desc->devices.empty()) return nullptr;
+        return context->findEndpoint(
+            MakeNicPath(desc->nicPathServerName(), desc->devices.front().name));
+    }
+    static uint32_t qpn(RdmaEndPoint &endpoint) {
+        return endpoint.notificationQpNum();
+    }
+    static ibv_cq *cq(RdmaEndPoint &endpoint) {
+        std::lock_guard<std::mutex> guard(endpoint.notify_.mutex);
+        return endpoint.notify_.qp ? endpoint.notify_.qp->send_cq : nullptr;
+    }
+    static void stop(RdmaEndPoint &endpoint) { endpoint.stopNotification(); }
+    static void pauseNotifications(TransferEngine &engine) {
+        auto *rdma = transport(engine);
+        ASSERT_NE(rdma, nullptr);
+        rdma->notify_running_.store(false, std::memory_order_release);
+        if (rdma->notify_worker_.joinable()) rdma->notify_worker_.join();
+    }
+};
+}  // namespace mooncake
+
+namespace {
+constexpr size_t kSlots = RdmaNotificationTestPeer::kSlots;
+constexpr size_t kSlotBytes = RdmaNotificationTestPeer::kSlotBytes;
+constexpr size_t kHeaderBytes = RdmaNotificationTestPeer::kHeaderBytes;
+}  // namespace
+
+TEST(NativeNotifyProtocol, BinaryAndBoundaryPayloads) {
+    char frame[kSlotBytes];
+    for (const auto &input : std::vector<Notify>{
+             {"", ""},
+             {std::string("a\0b", 3), std::string("\0\xff", 2)},
+             {"name", std::string(kSlotBytes - kHeaderBytes - 4, 'x')}}) {
+        size_t bytes = RdmaNotificationTestPeer::encode(frame, input);
+        ASSERT_NE(bytes, 0u);
+        Notify output;
+        ASSERT_TRUE(RdmaNotificationTestPeer::decode(frame, bytes, output));
+        EXPECT_EQ(output.name, input.name);
+        EXPECT_EQ(output.notify_msg, input.notify_msg);
+    }
+    EXPECT_EQ(RdmaNotificationTestPeer::encode(
+                  frame, {std::string(kSlotBytes, 'n'), ""}),
+              0u);
+    EXPECT_EQ(RdmaNotificationTestPeer::encode(
+                  frame, {"", std::string(kSlotBytes, 'm')}),
+              0u);
+}
+
+TEST(NativeNotifyProtocol, RejectsTruncatedAndMalformedFrames) {
+    char frame[kSlotBytes];
+    size_t bytes = RdmaNotificationTestPeer::encode(frame, {"name", "message"});
+    Notify output;
+    for (size_t n = 0; n < bytes; ++n)
+        EXPECT_FALSE(RdmaNotificationTestPeer::decode(frame, n, output));
+    EXPECT_FALSE(RdmaNotificationTestPeer::decode(frame, bytes + 1, output));
+    EXPECT_FALSE(
+        RdmaNotificationTestPeer::decode(frame, kSlotBytes + 1, output));
+    frame[0] ^= 1;
+    EXPECT_FALSE(RdmaNotificationTestPeer::decode(frame, bytes, output));
+    RdmaNotificationTestPeer::encode(frame, {"name", "message"});
+    uint32_t impossible = UINT32_MAX;
+    std::memcpy(frame, &impossible, 4);
+    EXPECT_FALSE(RdmaNotificationTestPeer::decode(frame, bytes, output));
+}
+
+namespace {
+// Device discovery and bounded receive helper are shared in shape with the
+// existing rdma_notify_test; that test and its transport stay unchanged.
+bool rdmaDeviceUsable(ibv_device *device) {
+    ibv_context *ctx = ibv_open_device(device);
+    if (!ctx) return false;
+    ibv_device_attr attr{};
+    if (ibv_query_device(ctx, &attr) != 0) {
+        ibv_close_device(ctx);
+        return false;
+    }
+    bool ok = false;
+    for (uint8_t port = 1; port <= attr.phys_port_cnt; ++port) {
+        ibv_port_attr port_attr{};
+        if (ibv_query_port(ctx, port, &port_attr) != 0) continue;
+        if (port_attr.gid_tbl_len > 0 && port_attr.state == IBV_PORT_ACTIVE) {
+            ok = true;
+            break;
+        }
+    }
+    ibv_close_device(ctx);
+    return ok;
+}
+
+std::string pickRdmaDevice() {
+    const char *override_name = std::getenv("MC_TEST_DEVICE_NAME");
+    if (override_name && *override_name) return override_name;
+    int num_devices = 0;
+    ibv_device **list = ibv_get_device_list(&num_devices);
+    if (!list || num_devices == 0) {
+        if (list) ibv_free_device_list(list);
+        return "";
+    }
+    std::string name;
+    for (int i = 0; i < num_devices; ++i) {
+        if (rdmaDeviceUsable(list[i])) {
+            name = ibv_get_device_name(list[i]);
+            break;
+        }
+    }
+    ibv_free_device_list(list);
+    return name;
+}
+
+bool waitForNotifies(TransferEngine &engine, size_t expect,
+                     std::vector<TransferMetadata::NotifyDesc> &out,
+                     int timeout_ms = 5000) {
+    auto deadline = std::chrono::steady_clock::now() +
+                    std::chrono::milliseconds(timeout_ms);
+    out.clear();
+    while (std::chrono::steady_clock::now() < deadline) {
+        std::vector<TransferMetadata::NotifyDesc> batch;
+        engine.getNotifies(batch);
+        out.insert(out.end(), batch.begin(), batch.end());
+        if (out.size() >= expect) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return out.size() >= expect;
+}
+
+}  // namespace
+
+class NativeNotifyTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        original_ = globalConfig();
+        device_ = pickRdmaDevice();
+        if (device_.empty()) GTEST_SKIP() << "no usable RDMA device";
+        for (const auto &entry :
+             std::vector<std::pair<std::string, std::string>>{
+                 {"MC_TE_FILTERS", device_},
+                 {"MC_USE_RDMA_TWOSIDED", "0"},
+                 {"MC_RDMA_NOTIFY_ENABLED", "1"},
+                 {"MC_RDMA_NOTIFY_OOB_FALLBACK", "0"}}) {
+            const char *previous = std::getenv(entry.first.c_str());
+            env_.push_back(
+                {entry.first, previous ? std::optional<std::string>(previous)
+                                       : std::nullopt});
+            setenv(entry.first.c_str(), entry.second.c_str(), 1);
+        }
+        loadGlobalConfig(globalConfig());
+        sender_ = makeEngine("127.0.0.1:0");
+        receiver_ = makeEngine("127.0.0.1:0");
+        ASSERT_NE(sender_, nullptr);
+        ASSERT_NE(receiver_, nullptr);
+        sender_name_ = sender_->getLocalIpAndPort();
+        receiver_name_ = receiver_->getLocalIpAndPort();
+    }
+    std::unique_ptr<TransferEngine> makeEngine(const std::string &name) {
+        auto engine = std::make_unique<TransferEngine>(
+            true, std::vector<std::string>{device_});
+        if (engine->init("P2PHANDSHAKE", name)) return nullptr;
+        return engine;
+    }
+    void TearDown() override {
+        sender_.reset();
+        receiver_.reset();
+        for (const auto &entry : env_) {
+            if (entry.second)
+                setenv(entry.first.c_str(), entry.second->c_str(), 1);
+            else
+                unsetenv(entry.first.c_str());
+        }
+        globalConfig() = original_;
+    }
+    GlobalConfig original_;
+    std::vector<std::pair<std::string, std::optional<std::string>>> env_;
+    std::string device_, sender_name_, receiver_name_;
+    // Keep registered buffers alive until TearDown destroys both engines,
+    // including when an assertion interrupts a transfer test.
+    std::vector<char> source_, target_;
+    std::unique_ptr<TransferEngine> sender_, receiver_;
+    void prepareBuffers() {
+        source_.assign(4096, 'a');
+        target_.assign(4096, 0);
+        ASSERT_EQ(sender_->registerLocalMemory(source_.data(), source_.size()),
+                  0);
+        ASSERT_EQ(
+            receiver_->registerLocalMemory(target_.data(), target_.size()), 0);
+    }
+    void transfer(TransferRequest::OpCode opcode, bool notify = false) {
+        auto segment = sender_->openSegment(receiver_name_);
+        ASSERT_NE(segment, static_cast<SegmentID>(-1));
+        TransferRequest request{};
+        request.opcode = opcode;
+        request.source = source_.data();
+        request.target_id = segment;
+        request.target_offset = reinterpret_cast<uint64_t>(target_.data());
+        request.length = source_.size();
+        auto batch = sender_->allocateBatchID(1);
+        ASSERT_TRUE((notify ? sender_->submitTransferWithNotify(
+                                  batch, {request}, {"batch", "done"})
+                            : sender_->submitTransfer(batch, {request}))
+                        .ok());
+        TransferStatus status{};
+        auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(5);
+        do {
+            ASSERT_TRUE(sender_->getTransferStatus(batch, 0, status).ok());
+            ASSERT_NE(status.s, TransferStatusEnum::FAILED);
+            if (status.s == TransferStatusEnum::COMPLETED) break;
+            std::this_thread::yield();
+        } while (std::chrono::steady_clock::now() < deadline);
+        ASSERT_EQ(status.s, TransferStatusEnum::COMPLETED);
+        ASSERT_TRUE(sender_->freeBatchID(batch).ok());
+        EXPECT_EQ(source_, target_);
+    }
+};
+
+TEST_F(NativeNotifyTest, DataAndNotificationsReuseEndpoint) {
+    ASSERT_NO_FATAL_FAILURE(prepareBuffers());
+    ASSERT_NO_FATAL_FAILURE(transfer(TransferRequest::WRITE));
+    auto endpoint =
+        RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_);
+    ASSERT_NE(endpoint, nullptr);
+    auto qpn = RdmaNotificationTestPeer::qpn(*endpoint);
+    ASSERT_NE(qpn, 0u);
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"explicit", "done"}),
+              0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    std::fill(target_.begin(), target_.end(), 'b');
+    ASSERT_NO_FATAL_FAILURE(transfer(TransferRequest::READ, true));
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, "batch");
+    EXPECT_EQ(RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_),
+              endpoint);
+    EXPECT_EQ(RdmaNotificationTestPeer::qpn(*endpoint), qpn);
+}
+
+TEST_F(NativeNotifyTest, LocalNotificationFailureDoesNotResetDataQps) {
+    ASSERT_NO_FATAL_FAILURE(prepareBuffers());
+    ASSERT_NO_FATAL_FAILURE(transfer(TransferRequest::WRITE));
+    auto endpoint =
+        RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_);
+    ASSERT_NE(endpoint, nullptr);
+    // A local channel failure is sticky. It must not replay via TCP or evict
+    // a healthy data connection merely because a notification was requested.
+    RdmaNotificationTestPeer::stop(*endpoint);
+    globalConfig().rdma_notify_oob_fallback = true;
+    EXPECT_EQ(sender_->sendNotifyByName(receiver_name_, {"failed", "x"}),
+              ERR_ENDPOINT);
+    EXPECT_EQ(RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_),
+              endpoint);
+    EXPECT_TRUE(endpoint->readyToSend());
+    std::fill(source_.begin(), source_.end(), 'c');
+    ASSERT_NO_FATAL_FAILURE(transfer(TransferRequest::WRITE));
+    std::vector<Notify> got;
+    receiver_->getNotifies(got);
+    EXPECT_TRUE(got.empty());
+}
+
+TEST_F(NativeNotifyTest, RetirementWakesSenderWaitingForSlot) {
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"setup", "x"}), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    auto endpoint =
+        RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_);
+    ASSERT_NE(endpoint, nullptr);
+    auto context =
+        RdmaNotificationTestPeer::transport(*sender_)->getContextList().front();
+    RdmaNotificationTestPeer::pauseNotifications(*sender_);
+    // Drain the setup send before suspending CQ progress and filling every
+    // slot.
+    RdmaContextTestPeer::drain(*context);
+    for (size_t i = 0; i < kSlots; ++i)
+        ASSERT_EQ(endpoint->sendNotification({"full", std::to_string(i)}), 0);
+    auto blocked = std::async(std::launch::async, [&] {
+        return sender_->sendNotifyByName(receiver_name_, {"blocked", "x"});
+    });
+    EXPECT_EQ(blocked.wait_for(std::chrono::milliseconds(100)),
+              std::future_status::timeout);
+    context->deleteEndpointByPtr(endpoint.get());
+    EXPECT_EQ(blocked.wait_for(std::chrono::seconds(2)),
+              std::future_status::ready);
+    EXPECT_EQ(blocked.get(), ERR_ENDPOINT);
+}
+
+TEST_F(NativeNotifyTest, DefaultSettingsEnableNativeNotifications) {
+    sender_.reset();
+    receiver_.reset();
+    unsetenv("MC_RDMA_NOTIFY_ENABLED");
+    unsetenv("MC_RDMA_NOTIFY_OOB_FALLBACK");
+    GlobalConfig defaults;
+    globalConfig().rdma_notify_enabled = defaults.rdma_notify_enabled;
+    globalConfig().rdma_notify_oob_fallback = defaults.rdma_notify_oob_fallback;
+    loadGlobalConfig(globalConfig());
+    sender_ = makeEngine("127.0.0.1:0");
+    receiver_ = makeEngine("127.0.0.1:0");
+    ASSERT_NE(sender_, nullptr);
+    ASSERT_NE(receiver_, nullptr);
+    ASSERT_TRUE(RdmaNotificationTestPeer::hasNativeService(*sender_));
+    ASSERT_TRUE(RdmaNotificationTestPeer::hasNativeService(*receiver_));
+    // Disable fallback for this send so a TCP success cannot mask bad routing.
+    globalConfig().rdma_notify_oob_fallback = false;
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_->getLocalIpAndPort(),
+                                        {"default", "rdma"}),
+              0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].notify_msg, "rdma");
+}
+
+TEST_F(NativeNotifyTest, SharedSwitchDisablesNativeServiceAndUsesTcp) {
+    sender_.reset();
+    receiver_.reset();
+    setenv("MC_RDMA_NOTIFY_ENABLED", "0", 1);
+    loadGlobalConfig(globalConfig());
+    sender_ = makeEngine("127.0.0.1:0");
+    receiver_ = makeEngine("127.0.0.1:0");
+    ASSERT_NE(sender_, nullptr);
+    ASSERT_NE(receiver_, nullptr);
+    EXPECT_FALSE(RdmaNotificationTestPeer::hasNativeService(*sender_));
+    EXPECT_FALSE(RdmaNotificationTestPeer::hasNativeService(*receiver_));
+    // TCP is the selected path, even with RDMA fallback disabled. A payload
+    // larger than the native slot also catches accidental RDMA dispatch.
+    Notify message{"disabled", std::string(kSlotBytes, 't')};
+    ASSERT_EQ(
+        sender_->sendNotifyByName(receiver_->getLocalIpAndPort(), message), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].notify_msg, message.notify_msg);
+}
+
+TEST_F(NativeNotifyTest, TwosidedKeepsItsOwnNotificationService) {
+    sender_.reset();
+    receiver_.reset();
+    setenv("MC_USE_RDMA_TWOSIDED", "1", 1);
+    loadGlobalConfig(globalConfig());
+    sender_ = makeEngine("127.0.0.1:0");
+    receiver_ = makeEngine("127.0.0.1:0");
+    ASSERT_NE(sender_, nullptr);
+    ASSERT_NE(receiver_, nullptr);
+    ASSERT_NE(sender_->getTransport("rdma_twosided"), nullptr);
+    ASSERT_NE(receiver_->getTransport("rdma_twosided"), nullptr);
+    EXPECT_FALSE(RdmaNotificationTestPeer::hasNativeService(*sender_));
+    EXPECT_FALSE(RdmaNotificationTestPeer::hasNativeService(*receiver_));
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_->getLocalIpAndPort(),
+                                        {"twosided", "ctrl"}),
+              0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].notify_msg, "ctrl");
+}
+
+TEST_F(NativeNotifyTest, FullSlotRoundTrip) {
+    Notify message{"binary",
+                   std::string(kSlotBytes - kHeaderBytes - 6, '\xff')};
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, message), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, message.name);
+    EXPECT_EQ(got[0].notify_msg, message.notify_msg);
+}
+
+TEST_F(NativeNotifyTest, ConcurrentBurstReusesSlotsWithoutDuplicates) {
+    constexpr int kThreads = 6, kPerThread = 256;
+    std::atomic<int> errors{0};
+    std::vector<std::thread> threads;
+    for (int t = 0; t < kThreads; ++t)
+        threads.emplace_back([&, t] {
+            for (int n = 0; n < kPerThread; ++n) {
+                auto id = std::to_string(t * kPerThread + n);
+                if (sender_->sendNotifyByName(receiver_name_,
+                                              {id, id + std::string(200, 'x')}))
+                    ++errors;
+            }
+        });
+    for (auto &thread : threads) thread.join();
+    ASSERT_EQ(errors.load(), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, kThreads * kPerThread, got));
+    ASSERT_EQ(got.size(), kThreads * kPerThread);
+    std::unordered_set<std::string> unique;
+    for (const auto &msg : got) {
+        EXPECT_EQ(msg.notify_msg, msg.name + std::string(200, 'x'));
+        EXPECT_TRUE(unique.insert(msg.name).second);
+    }
+}
+
+TEST_F(NativeNotifyTest, SimultaneousFirstSendInBothDirections) {
+    std::atomic<int> started{0}, errors{0};
+    auto send = [&](TransferEngine &engine, const std::string &peer) {
+        ++started;
+        while (started.load() != 2) std::this_thread::yield();
+        for (int i = 0; i < 256; ++i)
+            if (engine.sendNotifyByName(peer,
+                                        {"bidirectional", std::to_string(i)}))
+                ++errors;
+    };
+    std::thread a(send, std::ref(*sender_), std::cref(receiver_name_));
+    std::thread b(send, std::ref(*receiver_), std::cref(sender_name_));
+    a.join();
+    b.join();
+    ASSERT_EQ(errors.load(), 0);
+    for (auto *engine : {sender_.get(), receiver_.get()}) {
+        std::vector<Notify> got;
+        ASSERT_TRUE(waitForNotifies(*engine, 256, got));
+        ASSERT_EQ(got.size(), 256u);
+        for (int i = 0; i < 256; ++i)
+            EXPECT_EQ(got[i].notify_msg, std::to_string(i));
+    }
+}
+
+TEST_F(NativeNotifyTest, LoopbackDoesNotDeadlock) {
+    for (int i = 0; i < 128; ++i)
+        ASSERT_EQ(sender_->sendNotifyByName(sender_name_,
+                                            {"self", std::to_string(i)}),
+                  0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*sender_, 128, got));
+    ASSERT_EQ(got.size(), 128u);
+}
+
+TEST_F(NativeNotifyTest, DisabledPeerFallsBackOnlyWhenAllowed) {
+    receiver_.reset();
+    globalConfig().rdma_notify_enabled = false;
+    receiver_ = makeEngine("127.0.0.1:0");
+    ASSERT_NE(receiver_, nullptr);
+    receiver_name_ = receiver_->getLocalIpAndPort();
+    globalConfig().rdma_notify_enabled = true;
+    EXPECT_EQ(sender_->sendNotifyByName(receiver_name_, {"strict", "x"}),
+              ERR_NOT_IMPLEMENTED);
+    std::vector<Notify> got;
+    receiver_->getNotifies(got);
+    EXPECT_TRUE(got.empty());
+    globalConfig().rdma_notify_oob_fallback = true;
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"fallback", "tcp"}),
+              0);
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, "fallback");
+}
+
+TEST_F(NativeNotifyTest, OversizedPayloadFallsBackOnlyWhenAllowed) {
+    Notify large{"large", std::string(kSlotBytes, 'x')};
+    EXPECT_EQ(sender_->sendNotifyByName(receiver_name_, large),
+              ERR_NOT_IMPLEMENTED);
+    globalConfig().rdma_notify_oob_fallback = true;
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, large), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].notify_msg, large.notify_msg);
+}
+
+// P2PHANDSHAKE init always allocates a new TCP port, even if the caller passes
+// the old port. Retire the endpoint while preserving the RPC listener/context
+// so these tests exercise fresh data and notification QPs for the same peer
+// identity.
+TEST_F(NativeNotifyTest, SenderEndpointRestartReusesIdentity) {
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"before", "x"}), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    RdmaNotificationTestPeer::restart(*sender_);
+    ASSERT_EQ(sender_->getLocalIpAndPort(), sender_name_);
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"after", "y"}), 0);
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, "after");
+}
+
+TEST_F(NativeNotifyTest, ReceiverEndpointRestartReportsFailureThenReconnects) {
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, {"before", "x"}), 0);
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    RdmaNotificationTestPeer::stop(*receiver_);
+    bool failed = false;
+    for (int i = 0; i < 100 && !failed; ++i) {
+        failed =
+            sender_->sendNotifyByName(receiver_name_, {"lost-peer", "x"}) != 0;
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    }
+    ASSERT_TRUE(failed);
+    RdmaNotificationTestPeer::restart(*receiver_);
+    ASSERT_EQ(receiver_->getLocalIpAndPort(), receiver_name_);
+    int ret = ERR_ENDPOINT;
+    auto deadline =
+        std::chrono::steady_clock::now() +
+        std::chrono::milliseconds(globalConfig().conn_pause_ttl_ms + 3000);
+    do {
+        ret = sender_->sendNotifyByName(receiver_name_, {"after", "y"});
+        if (!ret) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    } while (std::chrono::steady_clock::now() < deadline);
+    ASSERT_EQ(ret, 0);
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, "after");
+}
+
+TEST_F(NativeNotifyTest, ConcurrentUnreachablePeerIsBounded) {
+    auto start = std::chrono::steady_clock::now();
+    std::atomic<int> failures{0};
+    std::vector<std::thread> threads;
+    for (int i = 0; i < 8; ++i)
+        threads.emplace_back([&] {
+            if (sender_->sendNotifyByName("127.0.0.1:19998", {"missing", "x"}))
+                ++failures;
+        });
+    for (auto &thread : threads) thread.join();
+    EXPECT_EQ(failures.load(), 8);
+    EXPECT_LT(std::chrono::steady_clock::now() - start,
+              std::chrono::seconds(15));
+}
+
+TEST_F(NativeNotifyTest, SharedCqRoutesConcurrentPeers) {
+    auto context = RdmaNotificationTestPeer::transport(*receiver_)
+                       ->getContextList()
+                       .front();
+    // The CQ exists before the first peer and stays fixed as peers connect.
+    auto *cq = RdmaContextTestPeer::cq(*context);
+    ASSERT_NE(cq, nullptr);
+    ASSERT_GE(cq->cqe, globalConfig().max_cqe);
+    const int capacity = cq->cqe;
+    auto second = makeEngine("127.0.0.1:0");
+    auto third = makeEngine("127.0.0.1:0");
+    ASSERT_NE(second, nullptr);
+    ASSERT_NE(third, nullptr);
+    std::vector<TransferEngine *> peers{sender_.get(), second.get(),
+                                        third.get()};
+    std::vector<std::shared_ptr<RdmaEndPoint>> endpoints;
+    for (auto *peer : peers) {
+        ASSERT_EQ(peer->sendNotifyByName(receiver_name_, {"setup", "x"}), 0);
+        endpoints.push_back(RdmaNotificationTestPeer::endpoint(
+            *receiver_, peer->getLocalIpAndPort()));
+        ASSERT_NE(endpoints.back(), nullptr);
+    }
+    std::vector<Notify> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, peers.size(), got));
+    EXPECT_EQ(cq->cqe, capacity);
+    for (const auto &endpoint : endpoints)
+        EXPECT_EQ(RdmaNotificationTestPeer::cq(*endpoint), cq);
+    auto outgoing =
+        RdmaNotificationTestPeer::endpoint(*sender_, receiver_name_);
+    ASSERT_NE(outgoing, nullptr);
+    EXPECT_NE(RdmaNotificationTestPeer::cq(*outgoing), cq);
+    constexpr size_t kMessages = 512;
+    std::atomic<int> errors{0};
+    std::vector<std::thread> threads;
+    for (size_t p = 0; p < peers.size(); ++p)
+        threads.emplace_back([&, p] {
+            for (size_t i = 0; i < kMessages; ++i) {
+                auto id = std::to_string(p) + ":" + std::to_string(i);
+                if (peers[p]->sendNotifyByName(receiver_name_, {id, id}))
+                    ++errors;
+            }
+        });
+    for (auto &thread : threads) thread.join();
+    ASSERT_EQ(errors.load(), 0);
+    ASSERT_TRUE(waitForNotifies(*receiver_, peers.size() * kMessages, got));
+    ASSERT_EQ(got.size(), peers.size() * kMessages);
+    std::unordered_set<std::string> ids;
+    for (const auto &message : got) {
+        EXPECT_EQ(message.name, message.notify_msg);
+        EXPECT_TRUE(ids.insert(message.name).second);
+    }
+    // Retiring one QP must not destroy its siblings' CQ or poison their sends.
+    context->deleteEndpointByPtr(endpoints.front().get());
+    context->reclaimEndpoints();
+    for (size_t p = 1; p < peers.size(); ++p) {
+        EXPECT_EQ(RdmaNotificationTestPeer::cq(*endpoints[p]), cq);
+        ASSERT_EQ(
+            peers[p]->sendNotifyByName(receiver_name_, {"survivor", "ok"}), 0);
+    }
+    ASSERT_TRUE(waitForNotifies(*receiver_, peers.size() - 1, got));
+    EXPECT_EQ(got.size(), peers.size() - 1);
+}
diff --git a/mooncake-transfer-engine/tests/rdma_notify_test.cpp b/mooncake-transfer-engine/tests/rdma_notify_test.cpp
new file mode 100644
index 0000000000..8962ab4b9b
--- /dev/null
+++ b/mooncake-transfer-engine/tests/rdma_notify_test.cpp
@@ -0,0 +1,316 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+//
+// Correctness checks for RDMA CtrlChannel notify path via
+// RdmaTwoSidedTransport. Requires a usable RDMA device (active port with a
+// GID). Self-skips when none is present, including CI runners that enumerate
+// a phantom mlx5_0.
+//
+// Env:
+//   MC_TE_FILTERS / MC_TEST_DEVICE_NAME — pin NIC
+//     (default: first usable ibv device)
+//   MC_USE_RDMA_TWOSIDED=1 — install rdma_twosided (set by test)
+//   MC_RDMA_NOTIFY_OOB_FALLBACK=0 — force RDMA path (set by this test)
+
+#include <gflags/gflags.h>
+#include <glog/logging.h>
+#include <gtest/gtest.h>
+#include <infiniband/verbs.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdlib>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "config.h"
+#include "transfer_engine.h"
+#include "transport/rdma_twosided/rdma_twosided_transport.h"
+
+using namespace mooncake;
+
+namespace {
+
+bool rdmaDeviceUsable(ibv_device *device) {
+    ibv_context *ctx = ibv_open_device(device);
+    if (!ctx) return false;
+    ibv_device_attr attr{};
+    if (ibv_query_device(ctx, &attr) != 0) {
+        ibv_close_device(ctx);
+        return false;
+    }
+    bool ok = false;
+    for (uint8_t port = 1; port <= attr.phys_port_cnt; ++port) {
+        ibv_port_attr port_attr{};
+        if (ibv_query_port(ctx, port, &port_attr) != 0) continue;
+        if (port_attr.gid_tbl_len > 0 && port_attr.state == IBV_PORT_ACTIVE) {
+            ok = true;
+            break;
+        }
+    }
+    ibv_close_device(ctx);
+    return ok;
+}
+
+std::string pickRdmaDevice() {
+    const char *override_name = std::getenv("MC_TEST_DEVICE_NAME");
+    if (override_name && *override_name) return override_name;
+    int num_devices = 0;
+    ibv_device **list = ibv_get_device_list(&num_devices);
+    if (!list || num_devices == 0) {
+        if (list) ibv_free_device_list(list);
+        return "";
+    }
+    std::string name;
+    for (int i = 0; i < num_devices; ++i) {
+        if (rdmaDeviceUsable(list[i])) {
+            name = ibv_get_device_name(list[i]);
+            break;
+        }
+    }
+    ibv_free_device_list(list);
+    return name;
+}
+
+bool waitForNotifies(TransferEngine &engine, size_t expect,
+                     std::vector<TransferMetadata::NotifyDesc> &out,
+                     int timeout_ms = 5000) {
+    auto deadline = std::chrono::steady_clock::now() +
+                    std::chrono::milliseconds(timeout_ms);
+    out.clear();
+    while (std::chrono::steady_clock::now() < deadline) {
+        std::vector<TransferMetadata::NotifyDesc> batch;
+        engine.getNotifies(batch);
+        out.insert(out.end(), batch.begin(), batch.end());
+        if (out.size() >= expect) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return out.size() >= expect;
+}
+
+}  // namespace
+
+class RdmaNotifyTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        device_ = pickRdmaDevice();
+        if (device_.empty()) {
+            GTEST_SKIP() << "no usable RDMA device available";
+        }
+        ASSERT_EQ(setenv("MC_TE_FILTERS", device_.c_str(), 1), 0);
+        ASSERT_EQ(setenv("MC_USE_RDMA_TWOSIDED", "1", 1), 0);
+        ASSERT_EQ(setenv("MC_RDMA_NOTIFY_ENABLED", "1", 1), 0);
+        ASSERT_EQ(setenv("MC_RDMA_NOTIFY_OOB_FALLBACK", "0", 1), 0);
+        ASSERT_EQ(setenv("MC_RDMA_NOTIFY_CONNECT_TIMEOUT_MS", "2000", 1), 0);
+        loadGlobalConfig(globalConfig());
+        ASSERT_TRUE(globalConfig().use_rdma_twosided);
+        ASSERT_TRUE(globalConfig().rdma_notify_enabled);
+        ASSERT_FALSE(globalConfig().rdma_notify_oob_fallback);
+
+        std::vector<std::string> filter{device_};
+        sender_ = std::make_unique<TransferEngine>(true, filter);
+        receiver_ = std::make_unique<TransferEngine>(true, filter);
+        ASSERT_EQ(sender_->init("P2PHANDSHAKE", "127.0.0.1:0"), 0);
+        ASSERT_EQ(receiver_->init("P2PHANDSHAKE", "127.0.0.1:0"), 0);
+        sender_name_ = sender_->getLocalIpAndPort();
+        receiver_name_ = receiver_->getLocalIpAndPort();
+        ASSERT_FALSE(sender_name_.empty());
+        ASSERT_FALSE(receiver_name_.empty());
+        ASSERT_NE(sender_->getTransport("rdma_twosided"), nullptr);
+        ASSERT_NE(receiver_->getTransport("rdma_twosided"), nullptr);
+    }
+
+    void TearDown() override {
+        sender_.reset();
+        receiver_.reset();
+        unsetenv("MC_TE_FILTERS");
+        unsetenv("MC_USE_RDMA_TWOSIDED");
+        unsetenv("MC_RDMA_NOTIFY_ENABLED");
+        unsetenv("MC_RDMA_NOTIFY_OOB_FALLBACK");
+        unsetenv("MC_RDMA_NOTIFY_CONNECT_TIMEOUT_MS");
+        loadGlobalConfig(globalConfig());
+    }
+
+    std::string device_;
+    std::unique_ptr<TransferEngine> sender_;
+    std::unique_ptr<TransferEngine> receiver_;
+    std::string sender_name_;
+    std::string receiver_name_;
+};
+
+TEST_F(RdmaNotifyTest, SingleNotifyCorrectness) {
+    TransferMetadata::NotifyDesc msg;
+    msg.name = "hello";
+    msg.notify_msg = "world-from-rdma-ctrl";
+
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, msg), 0);
+
+    std::vector<TransferMetadata::NotifyDesc> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got))
+        << "timed out waiting for RDMA notify";
+    ASSERT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0].name, msg.name);
+    EXPECT_EQ(got[0].notify_msg, msg.notify_msg);
+}
+
+TEST_F(RdmaNotifyTest, BidirectionalNotify) {
+    TransferMetadata::NotifyDesc a2b{"a2b", "ping"};
+    TransferMetadata::NotifyDesc b2a{"b2a", "pong"};
+
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, a2b), 0);
+    ASSERT_EQ(receiver_->sendNotifyByName(sender_name_, b2a), 0);
+
+    std::vector<TransferMetadata::NotifyDesc> recv_a, recv_b;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, recv_a));
+    ASSERT_TRUE(waitForNotifies(*sender_, 1, recv_b));
+    EXPECT_EQ(recv_a[0].name, "a2b");
+    EXPECT_EQ(recv_a[0].notify_msg, "ping");
+    EXPECT_EQ(recv_b[0].name, "b2a");
+    EXPECT_EQ(recv_b[0].notify_msg, "pong");
+}
+
+TEST_F(RdmaNotifyTest, NotifyLatencySmoke) {
+    constexpr int kWarmup = 32;
+    constexpr int kIters = 2000;
+    TransferMetadata::NotifyDesc warmup{"warmup", "x"};
+    for (int i = 0; i < kWarmup; ++i) {
+        ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, warmup), 0);
+    }
+    std::vector<TransferMetadata::NotifyDesc> drain;
+    ASSERT_TRUE(waitForNotifies(*receiver_, kWarmup, drain, 10000));
+
+    auto start = std::chrono::steady_clock::now();
+    for (int i = 0; i < kIters; ++i) {
+        TransferMetadata::NotifyDesc msg;
+        msg.name = "p";
+        msg.notify_msg = "y";
+        ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, msg), 0);
+    }
+    std::vector<TransferMetadata::NotifyDesc> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, kIters, got, 15000));
+    auto elapsed = std::chrono::steady_clock::now() - start;
+    double us =
+        std::chrono::duration_cast<std::chrono::microseconds>(elapsed).count();
+    double ops = kIters / (us / 1e6);
+    LOG(INFO) << "NotifyLatencySmoke: " << kIters << " notifies in " << us
+              << " us, ~" << ops << " ops/s, avg " << (us / kIters) << " us";
+}
+
+TEST_F(RdmaNotifyTest, BurstNotifyCorrectness) {
+    constexpr int kCount = 128;
+
+    for (int i = 0; i < kCount; ++i) {
+        TransferMetadata::NotifyDesc msg;
+        msg.name = "n" + std::to_string(i);
+        msg.notify_msg = "payload-" + std::to_string(i);
+        ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, msg), 0)
+            << "failed at i=" << i;
+    }
+
+    std::vector<TransferMetadata::NotifyDesc> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, kCount, got, 10000));
+    ASSERT_EQ(got.size(), static_cast<size_t>(kCount));
+    for (int i = 0; i < kCount; ++i) {
+        EXPECT_EQ(got[i].name, "n" + std::to_string(i));
+        EXPECT_EQ(got[i].notify_msg, "payload-" + std::to_string(i));
+    }
+}
+
+// Regression for the unbounded ctrl_cv_ wait: a peer that never completes the
+// ctrl handshake must not park the caller forever. With OOB fallback disabled
+// the notify has to report failure within the connect timeout.
+TEST_F(RdmaNotifyTest, UnreachablePeerNotifyIsBounded) {
+    TransferMetadata::NotifyDesc msg{"unreachable", "x"};
+
+    auto start = std::chrono::steady_clock::now();
+    int ret = sender_->sendNotifyByName("127.0.0.1:19999", msg);
+    auto elapsed = std::chrono::steady_clock::now() - start;
+    auto elapsed_s =
+        std::chrono::duration_cast<std::chrono::seconds>(elapsed).count();
+
+    EXPECT_NE(ret, 0)
+        << "notify to an unreachable peer must not report success";
+    EXPECT_LT(elapsed_s, 30)
+        << "sendNotify blocked far beyond the connect timeout";
+}
+
+// Concurrent notifies to the same unreachable peer: the connect stays
+// serialized, but every waiter must still return. A regression shows up as a
+// hung test rather than a failed assertion.
+TEST_F(RdmaNotifyTest, ConcurrentUnreachablePeerNotifyAllReturn) {
+    constexpr int kThreads = 8;
+    std::atomic<int> finished{0};
+    std::vector<std::thread> threads;
+
+    auto start = std::chrono::steady_clock::now();
+    for (int i = 0; i < kThreads; ++i) {
+        threads.emplace_back([this, &finished] {
+            TransferMetadata::NotifyDesc msg{"concurrent", "x"};
+            (void)sender_->sendNotifyByName("127.0.0.1:19998", msg);
+            finished.fetch_add(1, std::memory_order_relaxed);
+        });
+    }
+    for (auto &thread : threads) thread.join();
+    auto elapsed = std::chrono::steady_clock::now() - start;
+    auto elapsed_s =
+        std::chrono::duration_cast<std::chrono::seconds>(elapsed).count();
+
+    EXPECT_EQ(finished.load(), kThreads);
+    EXPECT_LT(elapsed_s, 60)
+        << "concurrent notifies did not settle within the connect timeout";
+}
+
+// Regression for the dead-channel wait: once a connected CtrlChannel fails
+// because the peer is gone, the stale ctrl_channels_ entry must not park later
+// callers forever. Before the fix the entry stayed behind as "not connected"
+// with nobody left to notify ctrl_cv_, so every later notify blocked.
+TEST_F(RdmaNotifyTest, NotifyAfterPeerGoneIsBounded) {
+    TransferMetadata::NotifyDesc first{"before", "x"};
+    ASSERT_EQ(sender_->sendNotifyByName(receiver_name_, first), 0);
+    std::vector<TransferMetadata::NotifyDesc> got;
+    ASSERT_TRUE(waitForNotifies(*receiver_, 1, got));
+
+    // Drop the peer: the ctrl QP moves to error, connected_ flips to false and
+    // the entry is left stale in ctrl_channels_.
+    receiver_.reset();
+
+    // The error WC lands shortly after the peer is gone. Keep notifying until
+    // the transport reports the failure: it must reclaim the stale entry and
+    // return an error rather than block. Before the fix this loop hung.
+    auto start = std::chrono::steady_clock::now();
+    bool reported_failure = false;
+    for (int i = 0; i < 40 && !reported_failure; ++i) {
+        TransferMetadata::NotifyDesc after{"after", "y"};
+        if (sender_->sendNotifyByName(receiver_name_, after) != 0) {
+            reported_failure = true;
+            break;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(250));
+    }
+    auto elapsed = std::chrono::steady_clock::now() - start;
+    auto elapsed_s =
+        std::chrono::duration_cast<std::chrono::seconds>(elapsed).count();
+
+    EXPECT_TRUE(reported_failure)
+        << "notify kept reporting success after the peer was gone";
+    EXPECT_LT(elapsed_s, 60) << "notify blocked on a stale CtrlChannel entry";
+}
+
+int main(int argc, char **argv) {
+    gflags::ParseCommandLineFlags(&argc, &argv, false);
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
diff --git a/mooncake-transfer-engine/tests/rdma_test_peers.h b/mooncake-transfer-engine/tests/rdma_test_peers.h
index 8fa2840ce7..6750e3be86 100644
--- a/mooncake-transfer-engine/tests/rdma_test_peers.h
+++ b/mooncake-transfer-engine/tests/rdma_test_peers.h
@@ -63,7 +63,7 @@ class RdmaContextTestPeer {
     }
 
     static void seedAutoGidState(RdmaContext &context, ibv_context *verbs_ctx,
-                                 uint8_t port, uint16_t lid, const ibv_gid &gid,
+                                 uint8_t port, uint32_t lid, const ibv_gid &gid,
                                  int gid_index) {
         context.context_ = verbs_ctx;
         context.port_ = port;
diff --git a/mooncake-transfer-engine/tests/rdma_transport_submit_task_test.cpp b/mooncake-transfer-engine/tests/rdma_transport_submit_task_test.cpp
index fc2d2fe8d4..debc6d2a04 100644
--- a/mooncake-transfer-engine/tests/rdma_transport_submit_task_test.cpp
+++ b/mooncake-transfer-engine/tests/rdma_transport_submit_task_test.cpp
@@ -25,6 +25,7 @@
 #include <string>
 
 #include "config.h"
+#include "multi_transport.h"
 #include "rdma_test_peers.h"
 #include "transfer_metadata.h"
 #include "transport/rdma_transport/rdma_context.h"
@@ -165,4 +166,34 @@ TEST_F(SubmitTransferTaskTest, PartialSubmitFailsAllTasks) {
     EXPECT_EQ(transport_->freeBatchID(batch_id), Status::OK());
 }
 
+TEST_F(SubmitTransferTaskTest, GroupedRequestsReportFailurePerRequest) {
+    std::vector<Transport::TransferRequest> requests(2);
+    for (auto &request : requests) {
+        request.opcode = Transport::TransferRequest::WRITE;
+        request.source = reinterpret_cast<void *>(kBufferAddr);
+        request.length = block_size_;
+        request.target_id = LOCAL_SEGMENT_ID;
+        request.target_offset = 0;
+    }
+    requests[1].length = 2 * block_size_;
+    std::string server_name = "unit-test-server:1234";
+    MultiTransport multi_transport(metadata_, server_name);
+    auto batch_id = multi_transport.allocateBatchID(1);
+    auto &task = reinterpret_cast<Transport::BatchDesc *>(batch_id)
+                     ->task_list.emplace_back();
+    task.batch_id = batch_id;
+    task.request = requests.data();
+    task.request_count = requests.size();
+    EXPECT_TRUE(
+        transport_->submitTransferTask({&task}).IsAddressNotRegistered());
+    Transport::TransferStatus status;
+    ASSERT_EQ(transport_->getTransferStatus(batch_id, 0, status), Status::OK());
+    EXPECT_EQ(status.s, Transport::TransferStatusEnum::FAILED);
+    std::vector<Transport::TransferStatusEnum> request_statuses;
+    ASSERT_EQ(multi_transport.getScatterRequestStatuses(batch_id, 0,
+                                                        request_statuses),
+              Status::OK());
+    EXPECT_EQ(request_statuses, std::vector(2, status.s));
+    EXPECT_EQ(multi_transport.freeBatchID(batch_id), Status::OK());
+}
 }  // namespace
diff --git a/mooncake-transfer-engine/tests/rdma_transport_test2.cpp b/mooncake-transfer-engine/tests/rdma_transport_test2.cpp
index 0ea85938f5..851270514d 100644
--- a/mooncake-transfer-engine/tests/rdma_transport_test2.cpp
+++ b/mooncake-transfer-engine/tests/rdma_transport_test2.cpp
@@ -243,8 +243,6 @@ TEST_F(RDMATransportTest, MultipleRead) {
                      kDataLength);
         ASSERT_EQ(ret, 0);
     }
-    engine->unregisterLocalMemory(addr);
-    freeMemoryPool(addr, ram_buffer_size);
 }
 
 }  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/sender_credit_test.cpp b/mooncake-transfer-engine/tests/sender_credit_test.cpp
new file mode 100644
index 0000000000..e8e9b5658b
--- /dev/null
+++ b/mooncake-transfer-engine/tests/sender_credit_test.cpp
@@ -0,0 +1,150 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include "error.h"
+#include "transport/rdma_twosided/sender_credit.h"
+
+using namespace mooncake;
+
+namespace {
+
+const char *kPeer = "127.0.0.1:12345";
+constexpr uint64_t kSession = 99;
+constexpr uint64_t kEpoch = 7;
+
+void grant(SenderCreditLedger &l, uint64_t seq, uint64_t slots = 10,
+           uint64_t bytes = 1000) {
+    int disposition = -1;
+    ASSERT_EQ(l.applyGrant(kPeer, kSession, kEpoch, seq,
+                           {{CreditResource::BounceSlots, slots},
+                            {CreditResource::BounceBytes, bytes}},
+                           disposition),
+              0);
+    ASSERT_EQ(disposition, 0);
+}
+
+}  // namespace
+
+TEST(SenderCreditTest, ReserveIsAtomicAcrossResources) {
+    SenderCreditLedger l;
+    ASSERT_EQ(l.activate(kPeer, kSession, kEpoch), 0);
+    grant(l, 1, 2, 100);
+    ASSERT_EQ(l.tryReserve(kPeer, kSession, kEpoch,
+                           {{CreditResource::BounceSlots, 1},
+                            {CreditResource::BounceBytes, 60}}),
+              0);
+    EXPECT_EQ(l.tryReserve(kPeer, kSession, kEpoch,
+                           {{CreditResource::BounceSlots, 1},
+                            {CreditResource::BounceBytes, 50}}),
+              ERR_TOO_MANY_REQUESTS);
+    uint64_t avail = 0;
+    ASSERT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceSlots,
+                          avail),
+              0);
+    EXPECT_EQ(avail, 1u);
+}
+
+TEST(SenderCreditTest, DuplicateGrantDoesNotMint) {
+    SenderCreditLedger l;
+    ASSERT_EQ(l.activate(kPeer, kSession, kEpoch), 0);
+    grant(l, 2, 10, 100);
+    int disposition = -1;
+    ASSERT_EQ(l.applyGrant(kPeer, kSession, kEpoch, 2,
+                           {{CreditResource::BounceSlots, 999}}, disposition),
+              0);
+    EXPECT_EQ(disposition, 1);
+    uint64_t avail = 0;
+    ASSERT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceSlots,
+                          avail),
+              0);
+    EXPECT_EQ(avail, 10u);
+}
+
+TEST(SenderCreditTest, PartialGrantRetainsOmitted) {
+    SenderCreditLedger l;
+    ASSERT_EQ(l.activate(kPeer, kSession, kEpoch), 0);
+    grant(l, 1, 5, 100);
+    int disposition = -1;
+    ASSERT_EQ(l.applyGrant(kPeer, kSession, kEpoch, 2,
+                           {{CreditResource::BounceBytes, 160}}, disposition),
+              0);
+    EXPECT_EQ(disposition, 0);
+    uint64_t bytes = 0, slots = 0;
+    ASSERT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceBytes,
+                          bytes),
+              0);
+    ASSERT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceSlots,
+                          slots),
+              0);
+    EXPECT_EQ(bytes, 160u);
+    EXPECT_EQ(slots, 5u);
+}
+
+TEST(SenderCreditTest, RollbackRestores) {
+    SenderCreditLedger l;
+    ASSERT_EQ(l.activate(kPeer, kSession, kEpoch), 0);
+    grant(l, 1, 4, 400);
+    ASSERT_EQ(l.tryReserve(kPeer, kSession, kEpoch,
+                           {{CreditResource::BounceSlots, 2},
+                            {CreditResource::BounceBytes, 200}}),
+              0);
+    ASSERT_EQ(l.rollbackReservation(kPeer, kSession, kEpoch,
+                                    {{CreditResource::BounceSlots, 2},
+                                     {CreditResource::BounceBytes, 200}}),
+              0);
+    uint64_t slots = 0;
+    ASSERT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceSlots,
+                          slots),
+              0);
+    EXPECT_EQ(slots, 4u);
+}
+
+TEST(SenderCreditTest, StaleEpochCannotTouchNewGeneration) {
+    SenderCreditLedger l;
+    ASSERT_EQ(l.activate(kPeer, kSession, kEpoch), 0);
+    grant(l, 1, 8, 800);
+    ASSERT_EQ(l.tryReserve(kPeer, kSession, kEpoch,
+                           {{CreditResource::BounceSlots, 2}}),
+              0);
+
+    // Reactivate with a newer epoch clears grants/consumed.
+    constexpr uint64_t kNewEpoch = kEpoch + 1;
+    ASSERT_EQ(l.activate(kPeer, kSession, kNewEpoch), 0);
+    int disposition = -1;
+    ASSERT_EQ(l.applyGrant(kPeer, kSession, kNewEpoch, 1,
+                           {{CreditResource::BounceSlots, 8}}, disposition),
+              0);
+    ASSERT_EQ(disposition, 0);
+
+    EXPECT_EQ(l.tryReserve(kPeer, kSession, kEpoch,
+                           {{CreditResource::BounceSlots, 1}}),
+              ERR_INVALID_ARGUMENT);
+    EXPECT_EQ(l.rollbackReservation(kPeer, kSession, kEpoch,
+                                    {{CreditResource::BounceSlots, 2}}),
+              ERR_INVALID_ARGUMENT);
+    uint64_t avail = 0;
+    EXPECT_EQ(l.available(kPeer, kSession, kEpoch, CreditResource::BounceSlots,
+                          avail),
+              ERR_INVALID_ARGUMENT);
+
+    ASSERT_EQ(l.tryReserve(kPeer, kSession, kNewEpoch,
+                           {{CreditResource::BounceSlots, 1}}),
+              0);
+    ASSERT_EQ(l.available(kPeer, kSession, kNewEpoch,
+                          CreditResource::BounceSlots, avail),
+              0);
+    EXPECT_EQ(avail, 7u);
+}
diff --git a/mooncake-transfer-engine/tests/shared_segment_test.cpp b/mooncake-transfer-engine/tests/shared_segment_test.cpp
new file mode 100644
index 0000000000..8d9457bc66
--- /dev/null
+++ b/mooncake-transfer-engine/tests/shared_segment_test.cpp
@@ -0,0 +1,443 @@
+// Copyright 2024 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstddef>
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <sys/wait.h>
+#include <unistd.h>
+#include <vector>
+
+#include "shared_segment/shared_segment.h"
+#include "shared_segment_internal.h"
+
+#if defined(USE_ASCEND_DIRECT)
+#include <acl/acl.h>
+#endif
+
+namespace mooncake {
+namespace {
+constexpr uint64_t kSegmentSize = 61 * (4096 + 8192);
+
+SharedSegmentOptions KvOptions(uint32_t rank_id = 0, uint32_t world_size = 2) {
+    SharedSegmentOptions options;
+    options.world_size = world_size;
+    options.rank_id = rank_id;
+    options.owner_rank = 0;
+    return options;
+}
+}  // namespace
+
+TEST(SharedSegmentFingerprintTest, ChangesWithEveryDeclaredField) {
+    SharedSegmentOptions options = KvOptions();
+    const auto base = ComputeSegmentFingerprint("kv", kSegmentSize, options);
+
+    EXPECT_NE(ComputeSegmentFingerprint("other", kSegmentSize, options), base);
+    EXPECT_NE(ComputeSegmentFingerprint("kv", kSegmentSize + 1, options), base);
+
+    auto different_world = options;
+    different_world.world_size = 8;
+    EXPECT_NE(ComputeSegmentFingerprint("kv", kSegmentSize, different_world),
+              base);
+
+    auto different_owner = options;
+    different_owner.owner_rank = 1;
+    EXPECT_NE(ComputeSegmentFingerprint("kv", kSegmentSize, different_owner),
+              base);
+
+    // rank_id and device_id are local and must not affect the digest.
+    auto different_rank = options;
+    different_rank.rank_id = 7;
+    different_rank.device_id = 3;
+    EXPECT_EQ(ComputeSegmentFingerprint("kv", kSegmentSize, different_rank),
+              base);
+
+    auto different_mmap = options;
+    different_mmap.mmap = !options.mmap;
+    EXPECT_NE(ComputeSegmentFingerprint("kv", kSegmentSize, different_mmap),
+              base);
+
+    auto different_host_register = options;
+    different_host_register.host_register = !options.host_register;
+    EXPECT_NE(
+        ComputeSegmentFingerprint("kv", kSegmentSize, different_host_register),
+        base);
+}
+
+TEST(SharedSegmentBlobTest, RoundTripsHeaderAndHandle) {
+    SegmentBlobHeader header{};
+    header.backend_id = 1;
+    header.rank_id = 5;
+    header.fingerprint = 0xDEADBEEFCAFEULL;
+    header.alloc_size = 1ULL << 30;
+    const std::vector<uint8_t> handle(kMaxHandleBytes, 0xA5);
+
+    std::string blob;
+    ASSERT_TRUE(EncodeSegmentBlob(header, handle, blob).ok());
+    EXPECT_EQ(blob.size(), kSegmentBlobBytes);
+
+    SegmentBlobHeader decoded{};
+    std::vector<uint8_t> decoded_handle;
+    ASSERT_TRUE(DecodeSegmentBlob(blob, decoded, decoded_handle).ok());
+    EXPECT_EQ(decoded.backend_id, header.backend_id);
+    EXPECT_EQ(decoded.rank_id, header.rank_id);
+    EXPECT_EQ(decoded.fingerprint, header.fingerprint);
+    EXPECT_EQ(decoded.alloc_size, header.alloc_size);
+    EXPECT_EQ(decoded_handle, handle);
+}
+
+TEST(SharedSegmentBlobTest, NonOwnerBlobHasTheSameLengthButNoHandle) {
+    SegmentBlobHeader header{};
+    header.rank_id = 2;
+    std::string blob;
+    ASSERT_TRUE(EncodeSegmentBlob(header, {}, blob).ok());
+    EXPECT_EQ(blob.size(), kSegmentBlobBytes);
+
+    SegmentBlobHeader decoded{};
+    std::vector<uint8_t> decoded_handle;
+    ASSERT_TRUE(DecodeSegmentBlob(blob, decoded, decoded_handle).ok());
+    EXPECT_TRUE(decoded_handle.empty());
+}
+
+TEST(SharedSegmentBlobTest, RejectsHandlesThatDoNotFit) {
+    std::string blob;
+    EXPECT_TRUE(
+        EncodeSegmentBlob({}, std::vector<uint8_t>(kMaxHandleBytes + 1), blob)
+            .IsInvalidArgument());
+}
+
+TEST(SharedSegmentBlobTest, RejectsCorruptedBlobs) {
+    std::vector<uint8_t> decoded_handle;
+    SegmentBlobHeader decoded{};
+
+    EXPECT_TRUE(DecodeSegmentBlob("short", decoded, decoded_handle)
+                    .IsInvalidArgument());
+
+    std::string blob;
+    ASSERT_TRUE(EncodeSegmentBlob({}, {}, blob).ok());
+    auto corrupted = blob;
+    corrupted[0] = static_cast<char>(corrupted[0] + 1);
+    EXPECT_TRUE(DecodeSegmentBlob(corrupted, decoded, decoded_handle)
+                    .IsInvalidArgument());
+
+    auto wrong_version = blob;
+    wrong_version[offsetof(SegmentBlobHeader, version)] += 1;
+    EXPECT_TRUE(DecodeSegmentBlob(wrong_version, decoded, decoded_handle)
+                    .IsInvalidArgument());
+
+    auto oversized_handle = blob;
+    const uint32_t too_many = kMaxHandleBytes + 1;
+    memcpy(oversized_handle.data() + offsetof(SegmentBlobHeader, handle_bytes),
+           &too_many, sizeof(too_many));
+    EXPECT_TRUE(DecodeSegmentBlob(oversized_handle, decoded, decoded_handle)
+                    .IsInvalidArgument());
+}
+
+TEST(SharedSegmentTest, RejectsInvalidOptions) {
+    std::string blob;
+    std::shared_ptr<SharedSegment> segment;
+    SharedSegmentOptions options;
+    options.world_size = 0;
+    EXPECT_TRUE(
+        SharedSegment::Create("kv", kSegmentSize, options, segment, blob)
+            .IsInvalidArgument());
+
+    options.world_size = 2;
+    options.rank_id = 2;
+    EXPECT_TRUE(
+        SharedSegment::Create("kv", kSegmentSize, options, segment, blob)
+            .IsInvalidArgument());
+
+    options.rank_id = 0;
+    options.owner_rank = 5;
+    EXPECT_TRUE(
+        SharedSegment::Create("kv", kSegmentSize, options, segment, blob)
+            .IsInvalidArgument());
+
+    options.owner_rank = 0;
+    EXPECT_TRUE(SharedSegment::Create("kv", 0, options, segment, blob)
+                    .IsInvalidArgument());
+
+    options.owner_rank = 0;
+    options.mmap = false;
+    options.host_register = true;
+    EXPECT_TRUE(
+        SharedSegment::Create("kv", kSegmentSize, options, segment, blob)
+            .IsInvalidArgument());
+}
+
+TEST(SharedSegmentBackendFactoryTest, RejectsUnknownImplementation) {
+    EXPECT_EQ(CreateSharedSegmentBackend("unknown"), nullptr);
+}
+
+TEST(SharedSegmentTest, ReportsWhenNoBackendIsCompiledIn) {
+    if (SharedSegment::Supported(/*mmap=*/false)) {
+        GTEST_SKIP() << "This build has a working VMM backend";
+    }
+    std::string blob;
+    std::shared_ptr<SharedSegment> segment;
+    SharedSegmentOptions options = KvOptions(0, 1);
+    options.mmap = false;
+    EXPECT_TRUE(
+        SharedSegment::Create("kv", kSegmentSize, options, segment, blob)
+            .IsNotImplemented());
+}
+
+TEST(SharedSegmentMmapTest, SupportedForMmapAndOptionalHostRegister) {
+    EXPECT_TRUE(SharedSegment::Supported(/*mmap=*/true));
+#if defined(USE_ASCEND_DIRECT)
+    EXPECT_TRUE(
+        SharedSegment::Supported(/*mmap=*/true, /*host_register=*/true));
+#else
+    EXPECT_FALSE(
+        SharedSegment::Supported(/*mmap=*/true, /*host_register=*/true));
+#endif
+    EXPECT_FALSE(
+        SharedSegment::Supported(/*mmap=*/false, /*host_register=*/true));
+}
+
+TEST(SharedSegmentMmapTest, SingleRankRoundTrip) {
+    if (!SharedSegment::Supported(/*mmap=*/true)) {
+        GTEST_SKIP() << "mmap shared segment unavailable";
+    }
+    SharedSegmentOptions options = KvOptions(0, 1);
+    options.mmap = true;
+
+    std::string blob;
+    std::shared_ptr<SharedSegment> segment;
+    auto status =
+        SharedSegment::Create("mmap-kv", kSegmentSize, options, segment, blob);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    ASSERT_TRUE(segment->Complete({blob}).ok());
+    ASSERT_TRUE(segment->ready());
+    ASSERT_NE(segment->base_addr(), 0u);
+
+    auto* bytes = reinterpret_cast<uint8_t*>(segment->base_addr());
+    bytes[0] = 0x3C;
+    bytes[kSegmentSize - 1] = 0xC3;
+    EXPECT_EQ(bytes[0], 0x3C);
+    EXPECT_EQ(bytes[kSegmentSize - 1], 0xC3);
+}
+
+TEST(SharedSegmentMmapTest, TwoRanksSharePagesInOneProcess) {
+    if (!SharedSegment::Supported(/*mmap=*/true)) {
+        GTEST_SKIP() << "mmap shared segment unavailable";
+    }
+    SharedSegmentOptions owner_opts = KvOptions(0, 2);
+    owner_opts.mmap = true;
+    SharedSegmentOptions peer_opts = KvOptions(1, 2);
+    peer_opts.mmap = true;
+
+    std::string owner_blob;
+    std::string peer_blob;
+    std::shared_ptr<SharedSegment> owner;
+    std::shared_ptr<SharedSegment> peer;
+    auto status = SharedSegment::Create("mmap-tp", kSegmentSize, owner_opts,
+                                        owner, owner_blob);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    ASSERT_TRUE(SharedSegment::Create("mmap-tp", kSegmentSize, peer_opts, peer,
+                                      peer_blob)
+                    .ok());
+
+    const std::vector<std::string> blobs = {owner_blob, peer_blob};
+    ASSERT_TRUE(owner->Complete(blobs).ok());
+    ASSERT_TRUE(peer->Complete(blobs).ok());
+
+    auto* owner_bytes = reinterpret_cast<uint8_t*>(owner->base_addr());
+    auto* peer_bytes = reinterpret_cast<uint8_t*>(peer->base_addr());
+    owner_bytes[0] = 0xAB;
+    owner_bytes[4095] = 0xCD;
+    EXPECT_EQ(peer_bytes[0], 0xAB);
+    EXPECT_EQ(peer_bytes[4095], 0xCD);
+    // Rank-local virtual addresses need not match.
+    EXPECT_NE(owner->base_addr(), peer->base_addr());
+}
+
+TEST(SharedSegmentMmapTest, RejectsMixedBackendBlobs) {
+    if (!SharedSegment::Supported(/*mmap=*/true)) {
+        GTEST_SKIP() << "mmap shared segment unavailable";
+    }
+    SharedSegmentOptions mmap_opts = KvOptions(0, 1);
+    mmap_opts.mmap = true;
+
+    std::string mmap_blob;
+    std::shared_ptr<SharedSegment> mmap_segment;
+    auto status = SharedSegment::Create("mmap-mix", kSegmentSize, mmap_opts,
+                                        mmap_segment, mmap_blob);
+    if (!status.ok()) {
+        GTEST_SKIP() << "mmap shared segment unavailable: "
+                     << status.ToString();
+    }
+
+    // Forge a peer blob that claims a different backend id.
+    SegmentBlobHeader header{};
+    std::vector<uint8_t> handle;
+    ASSERT_TRUE(DecodeSegmentBlob(mmap_blob, header, handle).ok());
+    header.backend_id = 1;  // Ascend VMM id
+    std::string forged;
+    ASSERT_TRUE(EncodeSegmentBlob(header, handle, forged).ok());
+    EXPECT_TRUE(mmap_segment->Complete({forged}).IsInvalidArgument());
+}
+
+TEST(SharedSegmentMmapTest, OwnerHandleIsProcFd) {
+    if (!SharedSegment::Supported(/*mmap=*/true)) {
+        GTEST_SKIP() << "mmap shared segment unavailable";
+    }
+    SharedSegmentOptions options = KvOptions(0, 1);
+    options.mmap = true;
+
+    std::string blob;
+    std::shared_ptr<SharedSegment> segment;
+    auto status =
+        SharedSegment::Create("mmap-fd", kSegmentSize, options, segment, blob);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+
+    SegmentBlobHeader header{};
+    std::vector<uint8_t> handle;
+    ASSERT_TRUE(DecodeSegmentBlob(blob, header, handle).ok());
+    const std::string path(handle.begin(), handle.end());
+    int pid = -1;
+    int fd = -1;
+    ASSERT_EQ(std::sscanf(path.c_str(), "/proc/%d/fd/%d", &pid, &fd), 2);
+    EXPECT_EQ(pid, static_cast<int>(getpid()));
+    EXPECT_GE(fd, 0);
+}
+
+TEST(SharedSegmentMmapTest, TwoProcessesSharePages) {
+    if (!SharedSegment::Supported(/*mmap=*/true)) {
+        GTEST_SKIP() << "mmap shared segment unavailable";
+    }
+
+    int to_peer[2];
+    int to_owner[2];
+    ASSERT_EQ(pipe(to_peer), 0);
+    ASSERT_EQ(pipe(to_owner), 0);
+
+    const pid_t child = fork();
+    ASSERT_GE(child, 0);
+    if (child == 0) {
+        close(to_peer[1]);
+        close(to_owner[0]);
+        SharedSegmentOptions peer_opts = KvOptions(1, 2);
+        peer_opts.mmap = true;
+        std::string peer_blob;
+        std::shared_ptr<SharedSegment> peer;
+        auto status = SharedSegment::Create("mmap-fork", kSegmentSize,
+                                            peer_opts, peer, peer_blob);
+        if (!status.ok() ||
+            write(to_owner[1], peer_blob.data(), peer_blob.size()) !=
+                static_cast<ssize_t>(peer_blob.size())) {
+            _exit(2);
+        }
+        std::string owner_blob(kSegmentBlobBytes, '\0');
+        if (read(to_peer[0], owner_blob.data(), owner_blob.size()) !=
+            static_cast<ssize_t>(owner_blob.size())) {
+            _exit(3);
+        }
+        const std::vector<std::string> blobs = {owner_blob, peer_blob};
+        if (!peer->Complete(blobs).ok()) {
+            _exit(4);
+        }
+        uint8_t ready = 1;
+        if (write(to_owner[1], &ready, 1) != 1) {
+            _exit(5);
+        }
+        if (read(to_peer[0], &ready, 1) != 1) {
+            _exit(6);
+        }
+        auto* bytes = reinterpret_cast<uint8_t*>(peer->base_addr());
+        const int ok = (bytes[0] == 0xA5 && bytes[4095] == 0x5A) ? 0 : 7;
+        _exit(ok);
+    }
+
+    close(to_peer[0]);
+    close(to_owner[1]);
+    SharedSegmentOptions owner_opts = KvOptions(0, 2);
+    owner_opts.mmap = true;
+    std::string owner_blob;
+    std::shared_ptr<SharedSegment> owner;
+    auto status = SharedSegment::Create("mmap-fork", kSegmentSize, owner_opts,
+                                        owner, owner_blob);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    ASSERT_EQ(write(to_peer[1], owner_blob.data(), owner_blob.size()),
+              static_cast<ssize_t>(owner_blob.size()));
+
+    std::string peer_blob(kSegmentBlobBytes, '\0');
+    ASSERT_EQ(read(to_owner[0], peer_blob.data(), peer_blob.size()),
+              static_cast<ssize_t>(peer_blob.size()));
+    const std::vector<std::string> blobs = {owner_blob, peer_blob};
+    ASSERT_TRUE(owner->Complete(blobs).ok());
+
+    uint8_t ready = 0;
+    ASSERT_EQ(read(to_owner[0], &ready, 1), 1);
+    auto* bytes = reinterpret_cast<uint8_t*>(owner->base_addr());
+    bytes[0] = 0xA5;
+    bytes[4095] = 0x5A;
+    ASSERT_EQ(write(to_peer[1], &ready, 1), 1);
+
+    int wstatus = 0;
+    ASSERT_EQ(waitpid(child, &wstatus, 0), child);
+    ASSERT_TRUE(WIFEXITED(wstatus));
+    EXPECT_EQ(WEXITSTATUS(wstatus), 0);
+}
+
+#if defined(USE_ASCEND_DIRECT)
+TEST(SharedSegmentMmapTest, HostRegisterTwoRanksSharePages) {
+    if (!SharedSegment::Supported(/*mmap=*/true, /*host_register=*/true)) {
+        GTEST_SKIP() << "HostRegister unavailable in this build";
+    }
+    if (aclInit(nullptr) != ACL_ERROR_NONE ||
+        aclrtSetDevice(0) != ACL_ERROR_NONE) {
+        GTEST_SKIP() << "aclrtSetDevice(0) unavailable";
+    }
+    SharedSegmentOptions owner_opts = KvOptions(0, 2);
+    owner_opts.mmap = true;
+    owner_opts.host_register = true;
+    owner_opts.device_id = 0;
+    SharedSegmentOptions peer_opts = owner_opts;
+    peer_opts.rank_id = 1;
+
+    std::string owner_blob;
+    std::string peer_blob;
+    std::shared_ptr<SharedSegment> owner;
+    std::shared_ptr<SharedSegment> peer;
+    auto status = SharedSegment::Create("mmap-hr-tp", kSegmentSize, owner_opts,
+                                        owner, owner_blob);
+    if (!status.ok()) {
+        GTEST_SKIP() << "HostRegister create failed: " << status.ToString();
+    }
+    status = SharedSegment::Create("mmap-hr-tp", kSegmentSize, peer_opts, peer,
+                                   peer_blob);
+    if (!status.ok()) {
+        GTEST_SKIP() << "peer HostRegister failed: " << status.ToString();
+    }
+    const std::vector<std::string> blobs = {owner_blob, peer_blob};
+    ASSERT_TRUE(owner->Complete(blobs).ok()) << "owner complete";
+    ASSERT_TRUE(peer->Complete(blobs).ok()) << "peer complete";
+    ASSERT_NE(owner->device_addr(), 0u);
+    ASSERT_NE(peer->device_addr(), 0u);
+
+    auto* owner_bytes = reinterpret_cast<uint8_t*>(owner->base_addr());
+    auto* peer_bytes = reinterpret_cast<uint8_t*>(peer->base_addr());
+    owner_bytes[0] = 0x11;
+    owner_bytes[4095] = 0x22;
+    EXPECT_EQ(peer_bytes[0], 0x11);
+    EXPECT_EQ(peer_bytes[4095], 0x22);
+}
+#endif
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/shm_hugepage_test_util.h b/mooncake-transfer-engine/tests/shm_hugepage_test_util.h
new file mode 100644
index 0000000000..4cb37c2cce
--- /dev/null
+++ b/mooncake-transfer-engine/tests/shm_hugepage_test_util.h
@@ -0,0 +1,87 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#ifndef MOONCAKE_TESTS_SHM_HUGEPAGE_TEST_UTIL_H
+#define MOONCAKE_TESTS_SHM_HUGEPAGE_TEST_UTIL_H
+
+#include <linux/magic.h>
+#include <sys/vfs.h>
+#include <unistd.h>
+
+#include <cstdlib>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "common.h"
+
+namespace mooncake {
+
+inline const char* HugepageSizeLabel(size_t hugepage_size) {
+    if (hugepage_size == SharedMemoryOptions::kHugepage2MB) return "2MB";
+    if (hugepage_size == SharedMemoryOptions::kHugepage512MB) return "512MB";
+    if (hugepage_size == SharedMemoryOptions::kHugepage1GB) return "1GB";
+    return "unknown";
+}
+
+inline const char* HugepageSizeTestName(size_t hugepage_size) {
+    if (hugepage_size == SharedMemoryOptions::kHugepage2MB) return "Size2MB";
+    if (hugepage_size == SharedMemoryOptions::kHugepage512MB)
+        return "Size512MB";
+    if (hugepage_size == SharedMemoryOptions::kHugepage1GB) return "Size1GB";
+    return "Unknown";
+}
+
+inline std::optional<std::string> FindHugetlbfsMount(size_t hugepage_size) {
+    std::vector<const char*> candidates;
+    if (const char* env = std::getenv("MC_HUGETLBFS_PATH");
+        env && hugepage_size == SharedMemoryOptions::kHugepage2MB) {
+        candidates.push_back(env);
+    }
+    if (const char* env = std::getenv("MC_HUGETLBFS_PATH_512M");
+        env && hugepage_size == SharedMemoryOptions::kHugepage512MB) {
+        candidates.push_back(env);
+    }
+    if (const char* env = std::getenv("MC_HUGETLBFS_PATH_1G");
+        env && hugepage_size == SharedMemoryOptions::kHugepage1GB) {
+        candidates.push_back(env);
+    }
+    if (const char* env = std::getenv("MC_HUGETLBFS_PATH"); env) {
+        candidates.push_back(env);
+    }
+    candidates.push_back(
+        SharedMemoryOptions::defaultHugetlbfsPathFor(hugepage_size));
+    if (hugepage_size == SharedMemoryOptions::kHugepage2MB) {
+        candidates.push_back("/tmp/mooncake_hugepages_2m");
+    } else if (hugepage_size == SharedMemoryOptions::kHugepage512MB) {
+        candidates.push_back("/tmp/mooncake_hugepages_512m");
+    } else if (hugepage_size == SharedMemoryOptions::kHugepage1GB) {
+        candidates.push_back("/tmp/mooncake_hugepages_1g");
+    }
+
+    for (const char* dir : candidates) {
+        if (!dir || !*dir) continue;
+        struct statfs sfs;
+        if (statfs(dir, &sfs) != 0) continue;
+        if (sfs.f_type != HUGETLBFS_MAGIC) continue;
+        if (static_cast<size_t>(sfs.f_bsize) != hugepage_size) continue;
+        if (access(dir, W_OK) != 0) continue;
+        return std::string(dir);
+    }
+    return std::nullopt;
+}
+
+}  // namespace mooncake
+
+#endif  // MOONCAKE_TESTS_SHM_HUGEPAGE_TEST_UTIL_H
diff --git a/mooncake-transfer-engine/tests/shm_transport_e2e_test.cpp b/mooncake-transfer-engine/tests/shm_transport_e2e_test.cpp
new file mode 100644
index 0000000000..d3171bae77
--- /dev/null
+++ b/mooncake-transfer-engine/tests/shm_transport_e2e_test.cpp
@@ -0,0 +1,666 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <cstring>
+#include <memory>
+#include <string>
+#include <unistd.h>
+#include <vector>
+
+#include "common.h"
+#include "shm_hugepage_test_util.h"
+#include "transfer_engine.h"
+#include "transfer_metadata.h"
+#include "transport/shm_transport/shm_transport.h"
+
+namespace mooncake {
+
+class ShmTransportTestPeer {
+   public:
+    static size_t mappingCount(ShmTransport& transport,
+                               Transport::SegmentID target_id) {
+        RWSpinlock::ReadGuard guard(transport.relocate_lock_);
+        auto it = transport.relocate_map_.find(target_id);
+        return it == transport.relocate_map_.end() ? 0 : it->second.size();
+    }
+};
+
+namespace {
+
+std::string UniqueServerName(uint16_t extra) {
+    return "127.0.0.1:" +
+           std::to_string(21000 + static_cast<int>(getpid() % 1000) + extra);
+}
+
+class ScopedEnv {
+   public:
+    ScopedEnv(const char* name, const char* value) : name_(name) {
+        const char* old = std::getenv(name);
+        if (old) {
+            had_old_ = true;
+            old_ = old;
+        }
+        if (value)
+            setenv(name_.c_str(), value, 1);
+        else
+            unsetenv(name_.c_str());
+    }
+
+    ~ScopedEnv() {
+        if (had_old_)
+            setenv(name_.c_str(), old_.c_str(), 1);
+        else
+            unsetenv(name_.c_str());
+    }
+
+   private:
+    std::string name_;
+    std::string old_;
+    bool had_old_{false};
+};
+
+bool WaitStatus(TransferEngine& engine, BatchID batch_id,
+                TransferStatusEnum expected) {
+    TransferStatus status;
+    for (int i = 0; i < 1000; ++i) {
+        Status s = engine.getTransferStatus(batch_id, 0, status);
+        if (!s.ok()) return false;
+        if (status.s == expected) return true;
+        if (status.s == TransferStatusEnum::FAILED &&
+            expected != TransferStatusEnum::FAILED)
+            return false;
+        usleep(1000);
+    }
+    return false;
+}
+
+bool WaitCompleted(TransferEngine& engine, BatchID batch_id) {
+    return WaitStatus(engine, batch_id, TransferStatusEnum::COMPLETED);
+}
+
+std::unique_ptr<TransferEngine> MakeEngine(const std::string& server_name,
+                                           bool install_shm = true) {
+    auto engine = std::make_unique<TransferEngine>(false);
+    auto host_port = parseHostNameWithPort(server_name);
+    int rc = engine->init(P2PHANDSHAKE, server_name, host_port.first.c_str(),
+                          host_port.second);
+    EXPECT_EQ(rc, 0);
+    EXPECT_NE(engine->installTransport("tcp", nullptr), nullptr);
+    if (install_shm) {
+        EXPECT_NE(engine->installTransport("shm", nullptr), nullptr);
+        EXPECT_TRUE(engine->isTcpOnly());
+    } else {
+        EXPECT_EQ(engine->getTransport("shm"), nullptr);
+    }
+    return engine;
+}
+
+void ExpectShmWriteAndRead(TransferEngine& owner, TransferEngine& peer,
+                           void* remote, uint64_t remote_base, size_t length) {
+    std::vector<uint8_t> payload(length);
+    std::vector<uint8_t> readback(length, 0);
+    for (size_t i = 0; i < length; ++i) payload[i] = static_cast<uint8_t>(i);
+    ASSERT_EQ(peer.registerLocalMemory(payload.data(), length, "cpu:0"), 0);
+
+    auto segment_id = peer.openSegment(owner.getLocalIpAndPort());
+    {
+        auto batch = peer.allocateBatchID(1);
+        TransferRequest write;
+        write.opcode = TransferRequest::WRITE;
+        write.source = payload.data();
+        write.target_id = segment_id;
+        write.target_offset = remote_base;
+        write.length = length;
+        ASSERT_TRUE(peer.submitTransfer(batch, {write}).ok());
+        ASSERT_TRUE(WaitCompleted(peer, batch));
+        ASSERT_TRUE(peer.freeBatchID(batch).ok());
+    }
+
+    auto* shm = dynamic_cast<ShmTransport*>(peer.getTransport("shm"));
+    ASSERT_NE(shm, nullptr);
+    EXPECT_GE(ShmTransportTestPeer::mappingCount(*shm, segment_id), 1u);
+    EXPECT_EQ(std::memcmp(remote, payload.data(), length), 0);
+
+    ASSERT_EQ(peer.registerLocalMemory(readback.data(), length, "cpu:0"), 0);
+    {
+        auto batch = peer.allocateBatchID(1);
+        TransferRequest read;
+        read.opcode = TransferRequest::READ;
+        read.source = readback.data();
+        read.target_id = segment_id;
+        read.target_offset = remote_base;
+        read.length = length;
+        ASSERT_TRUE(peer.submitTransfer(batch, {read}).ok());
+        ASSERT_TRUE(WaitCompleted(peer, batch));
+        ASSERT_TRUE(peer.freeBatchID(batch).ok());
+    }
+    EXPECT_EQ(readback, payload);
+}
+
+const TransferMetadata::BufferDesc* FindPosixShmBuffer(
+    const TransferMetadata::SegmentDesc& desc) {
+    for (const auto& buffer : desc.buffers) {
+        if (isPosixShmName(buffer.shm_name)) return &buffer;
+    }
+    return nullptr;
+}
+
+}  // namespace
+
+TEST(ShmTransportE2E, WriteAndReadBetweenEngines) {
+    const size_t length = 2 * 1024 * 1024;
+    auto engine_a = MakeEngine(UniqueServerName(0));
+    auto engine_b = MakeEngine(UniqueServerName(1));
+    ASSERT_TRUE(engine_a);
+    ASSERT_TRUE(engine_b);
+
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+
+    auto desc = engine_a->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    ASSERT_FALSE(desc->buffers.empty());
+    EXPECT_NE(desc->protocol.find("shm"), std::string::npos);
+#ifdef ENABLE_MULTI_PROTOCOL
+    EXPECT_NE(desc->protocol.find("tcp"), std::string::npos);
+    auto* shm_buffer = FindPosixShmBuffer(*desc);
+    ASSERT_NE(shm_buffer, nullptr);
+    EXPECT_EQ(shm_buffer->protocol, "shm");
+#else
+    EXPECT_EQ(desc->protocol, "shm");
+#endif
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    ASSERT_FALSE(remote_desc->buffers.empty());
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+    EXPECT_NE(remote_desc->protocol.find("shm"), std::string::npos);
+
+    ASSERT_NO_FATAL_FAILURE(ExpectShmWriteAndRead(*engine_a, *engine_b, remote,
+                                                  remote_base, length));
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+class ShmHugepageE2ETest : public ::testing::TestWithParam<size_t> {};
+
+TEST_P(ShmHugepageE2ETest, WriteAndRead) {
+    const size_t length = GetParam();
+    auto mount = FindHugetlbfsMount(length);
+    if (!mount) {
+        GTEST_SKIP() << "No writable " << HugepageSizeLabel(length)
+                     << " hugetlbfs mount";
+    }
+
+    const uint16_t extra =
+        length == SharedMemoryOptions::kHugepage2MB
+            ? 30
+            : (length == SharedMemoryOptions::kHugepage512MB ? 34 : 32);
+    auto engine_a = MakeEngine(UniqueServerName(extra));
+    auto engine_b = MakeEngine(UniqueServerName(extra + 1));
+    ASSERT_TRUE(engine_a);
+    ASSERT_TRUE(engine_b);
+
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = length;
+    opt.hugetlbfs_path = *mount;
+    opt.populate = false;
+
+    void* remote = engine_a->allocateSharedMemory(length, opt);
+    if (!remote) {
+        GTEST_SKIP() << HugepageSizeLabel(length)
+                     << " hugetlbfs mount present but allocation failed "
+                        "(no free hugepages?)";
+    }
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+
+    auto desc = engine_a->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    auto* shm_buffer = FindPosixShmBuffer(*desc);
+    ASSERT_NE(shm_buffer, nullptr);
+    EXPECT_TRUE(isFilesystemShmPath(shm_buffer->shm_name));
+    EXPECT_EQ(shm_buffer->shm_name.rfind(*mount, 0), 0u);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    EXPECT_TRUE(isFilesystemShmPath(remote_shm->shm_name));
+
+    ASSERT_NO_FATAL_FAILURE(ExpectShmWriteAndRead(*engine_a, *engine_b, remote,
+                                                  remote_shm->addr, length));
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+INSTANTIATE_TEST_SUITE_P(HugepageSizes, ShmHugepageE2ETest,
+                         ::testing::Values(SharedMemoryOptions::kHugepage2MB,
+                                           SharedMemoryOptions::kHugepage512MB,
+                                           SharedMemoryOptions::kHugepage1GB),
+                         [](const testing::TestParamInfo<size_t>& info) {
+                             return HugepageSizeTestName(info.param);
+                         });
+
+TEST(ShmTransportE2E, WriteAndRead4K) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(6));
+    auto engine_b = MakeEngine(UniqueServerName(7));
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+    ASSERT_NO_FATAL_FAILURE(ExpectShmWriteAndRead(*engine_a, *engine_b, remote,
+                                                  remote_base, length));
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+TEST(ShmTransportE2E, WriteAndReadCrossPage) {
+    const size_t length = static_cast<size_t>(sysconf(_SC_PAGESIZE)) + 64;
+    auto engine_a = MakeEngine(UniqueServerName(8));
+    auto engine_b = MakeEngine(UniqueServerName(9));
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+    ASSERT_NO_FATAL_FAILURE(ExpectShmWriteAndRead(*engine_a, *engine_b, remote,
+                                                  remote_base, length));
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+TEST(ShmTransportE2E, RegisterSubRangeFails) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const size_t length = page_size * 2;
+    auto engine_a = MakeEngine(UniqueServerName(24));
+    auto engine_b = MakeEngine(UniqueServerName(25));
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    auto* mid = static_cast<char*>(remote) + page_size;
+    EXPECT_EQ(engine_a->registerLocalMemory(mid, page_size, "cpu:0"),
+              ERR_INVALID_ARGUMENT);
+    EXPECT_EQ(engine_a->registerLocalMemory(remote, length + 1, "cpu:0"),
+              ERR_INVALID_ARGUMENT);
+
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, page_size, "cpu:0"), 0);
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    EXPECT_EQ(remote_shm->length, page_size);
+    ASSERT_NO_FATAL_FAILURE(ExpectShmWriteAndRead(*engine_a, *engine_b, remote,
+                                                  remote_shm->addr, page_size));
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+TEST(ShmTransportE2E, TransferFailsAfterFreeSharedMemory) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(10));
+    auto engine_b = MakeEngine(UniqueServerName(11));
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+
+    std::vector<uint8_t> payload(length, 0x5a);
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_base;
+    write.length = length;
+    EXPECT_FALSE(engine_b->submitTransfer(batch, {write}).ok());
+    auto* shm = dynamic_cast<ShmTransport*>(engine_b->getTransport("shm"));
+    ASSERT_NE(shm, nullptr);
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(*shm, segment_id), 0u);
+    ASSERT_TRUE(WaitStatus(*engine_b, batch, TransferStatusEnum::FAILED));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+}
+
+TEST(ShmTransportE2E, FreeSharedMemoryDoesNotUnregisterMalloc) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(20));
+    auto engine_b = MakeEngine(UniqueServerName(21));
+    std::vector<uint8_t> remote(length, 0);
+    std::vector<uint8_t> payload(length, 0x9a);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote.data(), length, "cpu:0"), 0);
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+    EXPECT_EQ(engine_a->freeSharedMemory(remote.data()), ERR_INVALID_ARGUMENT);
+
+    // Local metadata still has the malloc buffer; freeSharedMemory must not
+    // unregister transports it does not own.
+    auto local_desc =
+        engine_a->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(local_desc);
+    ASSERT_FALSE(local_desc->buffers.empty());
+    EXPECT_EQ(local_desc->buffers[0].addr,
+              reinterpret_cast<uint64_t>(remote.data()));
+
+#ifdef ENABLE_MULTI_PROTOCOL
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    ASSERT_FALSE(remote_desc->buffers.empty());
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_desc->buffers[0].addr;
+    write.length = length;
+    ASSERT_TRUE(engine_b->submitTransfer(batch, {write}).ok());
+    ASSERT_TRUE(WaitCompleted(*engine_b, batch));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+    EXPECT_EQ(remote, payload);
+#else
+    // installTransport("shm") replaced protocol with "shm", so decode skips
+    // malloc buffers (empty shm_name). Do not index buffers[0].
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    EXPECT_EQ(FindPosixShmBuffer(*remote_desc), nullptr);
+    EXPECT_TRUE(remote_desc->buffers.empty());
+#endif
+}
+
+TEST(ShmTransportE2E, TransferAfterFreeAndReallocateSharedMemory) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(22));
+    auto engine_b = MakeEngine(UniqueServerName(23));
+    std::vector<uint8_t> first_payload(length, 0xa1);
+    std::vector<uint8_t> second_payload(length, 0xb2);
+    ASSERT_EQ(
+        engine_b->registerLocalMemory(first_payload.data(), length, "cpu:0"),
+        0);
+    ASSERT_EQ(
+        engine_b->registerLocalMemory(second_payload.data(), length, "cpu:0"),
+        0);
+
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+
+    auto submit_write = [&](std::vector<uint8_t>& payload) -> bool {
+        auto batch = engine_b->allocateBatchID(1);
+        TransferRequest write;
+        write.opcode = TransferRequest::WRITE;
+        write.source = payload.data();
+        write.target_id = segment_id;
+        write.target_offset = remote_base;
+        write.length = length;
+        if (!engine_b->submitTransfer(batch, {write}).ok()) {
+            (void)engine_b->freeBatchID(batch);
+            return false;
+        }
+        if (!WaitCompleted(*engine_b, batch)) {
+            (void)engine_b->freeBatchID(batch);
+            return false;
+        }
+        if (!engine_b->freeBatchID(batch).ok()) return false;
+        return std::memcmp(remote, payload.data(), length) == 0;
+    };
+    EXPECT_TRUE(submit_write(first_payload));
+
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+    remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+
+    // Do not call syncSegmentCache: relocate must notice the unlinked object,
+    // drop the orphaned mmap, and refetch the peer descriptor.
+    if (!submit_write(second_payload)) {
+        remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+        ASSERT_TRUE(remote_desc);
+        remote_shm = FindPosixShmBuffer(*remote_desc);
+        ASSERT_NE(remote_shm, nullptr);
+        remote_base = remote_shm->addr;
+        ASSERT_TRUE(submit_write(second_payload));
+    }
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+TEST(ShmTransportE2E, UnsetMcForceShmDoesNotInstallShm) {
+    ScopedEnv disable_force("MC_FORCE_SHM", nullptr);
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(12), /*install_shm=*/false);
+    auto engine_b = MakeEngine(UniqueServerName(13), /*install_shm=*/false);
+    ASSERT_EQ(engine_a->getTransport("shm"), nullptr);
+    ASSERT_EQ(engine_b->getTransport("shm"), nullptr);
+    EXPECT_EQ(engine_a->allocateSharedMemory(length), nullptr);
+
+    std::vector<uint8_t> remote(length, 0);
+    std::vector<uint8_t> payload(length, 0x3c);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote.data(), length, "cpu:0"), 0);
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    EXPECT_FALSE(isPosixShmName(remote_desc->buffers[0].shm_name));
+
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_desc->buffers[0].addr;
+    write.length = length;
+    ASSERT_TRUE(engine_b->submitTransfer(batch, {write}).ok());
+    ASSERT_TRUE(WaitCompleted(*engine_b, batch));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+    EXPECT_EQ(remote, payload);
+}
+
+#ifndef ENABLE_MULTI_PROTOCOL
+TEST(ShmTransportE2E, McForceShmInstallsShmOnly) {
+    ScopedEnv force_shm("MC_FORCE_SHM", "1");
+    const std::string server_name = UniqueServerName(16);
+    auto engine = std::make_unique<TransferEngine>(true);
+    auto host_port = parseHostNameWithPort(server_name);
+    ASSERT_EQ(engine->init(P2PHANDSHAKE, server_name, host_port.first.c_str(),
+                           host_port.second),
+              0);
+    EXPECT_NE(engine->getTransport("shm"), nullptr);
+    EXPECT_EQ(engine->getTransport("tcp"), nullptr);
+    EXPECT_EQ(engine->getTransport("rdma"), nullptr);
+    auto desc = engine->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    EXPECT_EQ(desc->protocol, "shm");
+    void* buf = engine->allocateSharedMemory(4096);
+    ASSERT_NE(buf, nullptr);
+    EXPECT_EQ(engine->freeSharedMemory(buf), 0);
+}
+#endif
+
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST(ShmTransportE2E, McForceShmCoexistsWithHostTransport) {
+    ScopedEnv force_shm("MC_FORCE_SHM", "1");
+    const std::string server_name = UniqueServerName(18);
+    auto engine = std::make_unique<TransferEngine>(true);
+    auto host_port = parseHostNameWithPort(server_name);
+    ASSERT_EQ(engine->init(P2PHANDSHAKE, server_name, host_port.first.c_str(),
+                           host_port.second),
+              0);
+    EXPECT_NE(engine->getTransport("shm"), nullptr);
+    EXPECT_TRUE(engine->getTransport("tcp") != nullptr ||
+                engine->getTransport("rdma") != nullptr);
+    auto desc = engine->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    EXPECT_NE(desc->protocol.find("shm"), std::string::npos);
+    EXPECT_NE(desc->protocol.find(','), std::string::npos);
+}
+
+TEST(ShmTransportE2E, MallocBufferUsesTcp) {
+    const size_t length = 4096;
+    const std::string name_a = UniqueServerName(2);
+    const std::string name_b = UniqueServerName(3);
+    std::vector<uint8_t> remote(length, 0);
+    std::vector<uint8_t> payload(length, 0x7e);
+
+    auto engine_a = MakeEngine(name_a);
+    auto engine_b = MakeEngine(name_b);
+
+    ASSERT_EQ(engine_a->registerLocalMemory(remote.data(), length, "cpu:0"), 0);
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    uint64_t remote_base = remote_desc->buffers[0].addr;
+    EXPECT_EQ(FindPosixShmBuffer(*remote_desc), nullptr);
+
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_base;
+    write.length = length;
+    ASSERT_TRUE(engine_b->submitTransfer(batch, {write}).ok());
+    ASSERT_TRUE(WaitCompleted(*engine_b, batch));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+
+    auto* shm = dynamic_cast<ShmTransport*>(engine_b->getTransport("shm"));
+    ASSERT_NE(shm, nullptr);
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(*shm, segment_id), 0u);
+    EXPECT_EQ(remote, payload);
+}
+
+TEST(ShmTransportE2E, SubmitTransferPrefersShmOnSameHost) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(4));
+    auto engine_b = MakeEngine(UniqueServerName(5));
+    std::vector<uint8_t> payload(length, 0xa5);
+
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+    auto local_desc =
+        engine_a->getMetadata()->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(local_desc);
+    EXPECT_NE(local_desc->protocol.find("tcp"), std::string::npos);
+    EXPECT_NE(local_desc->protocol.find("shm"), std::string::npos);
+    auto* shm_buffer = FindPosixShmBuffer(*local_desc);
+    ASSERT_NE(shm_buffer, nullptr);
+    EXPECT_EQ(shm_buffer->protocol, "shm");
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+    uint64_t remote_base = remote_shm->addr;
+
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_base;
+    write.length = length;
+    ASSERT_TRUE(engine_b->submitTransfer(batch, {write}).ok());
+    ASSERT_TRUE(WaitCompleted(*engine_b, batch));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+
+    auto* shm = dynamic_cast<ShmTransport*>(engine_b->getTransport("shm"));
+    ASSERT_NE(shm, nullptr);
+    EXPECT_GE(ShmTransportTestPeer::mappingCount(*shm, segment_id), 1u);
+    EXPECT_EQ(std::memcmp(remote, payload.data(), length), 0);
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+
+TEST(ShmTransportE2E, MpSubmitTransferHonorsTcpPreference) {
+    const size_t length = 4096;
+    auto engine_a = MakeEngine(UniqueServerName(14));
+    auto engine_b = MakeEngine(UniqueServerName(15));
+    std::vector<uint8_t> payload(length, 0x3d);
+
+    void* remote = engine_a->allocateSharedMemory(length);
+    ASSERT_NE(remote, nullptr);
+    std::memset(remote, 0, length);
+    ASSERT_EQ(engine_a->registerLocalMemory(remote, length, "cpu:0"), 0);
+    ASSERT_EQ(engine_b->registerLocalMemory(payload.data(), length, "cpu:0"),
+              0);
+
+    auto segment_id = engine_b->openSegment(engine_a->getLocalIpAndPort());
+    auto remote_desc = engine_b->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_TRUE(remote_desc);
+    auto* remote_shm = FindPosixShmBuffer(*remote_desc);
+    ASSERT_NE(remote_shm, nullptr);
+
+    auto batch = engine_b->allocateBatchID(1);
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.source = payload.data();
+    write.target_id = segment_id;
+    write.target_offset = remote_shm->addr;
+    write.length = length;
+    std::string proto = "tcp";
+    ASSERT_TRUE(engine_b->mp_submitTransfer(batch, {write}, proto).ok());
+    ASSERT_TRUE(WaitCompleted(*engine_b, batch));
+    ASSERT_TRUE(engine_b->freeBatchID(batch).ok());
+
+    auto* shm = dynamic_cast<ShmTransport*>(engine_b->getTransport("shm"));
+    ASSERT_NE(shm, nullptr);
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(*shm, segment_id), 0u);
+    EXPECT_EQ(std::memcmp(remote, payload.data(), length), 0);
+    ASSERT_EQ(engine_a->freeSharedMemory(remote), 0);
+}
+#endif
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/shm_transport_test.cpp b/mooncake-transfer-engine/tests/shm_transport_test.cpp
new file mode 100644
index 0000000000..b0963b52c6
--- /dev/null
+++ b/mooncake-transfer-engine/tests/shm_transport_test.cpp
@@ -0,0 +1,1214 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/magic.h>
+#include <stdlib.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/vfs.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cstring>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <vector>
+
+#include "common.h"
+#include "multi_transport.h"
+#include "shm_hugepage_test_util.h"
+#include "transfer_metadata.h"
+#include "transport/shm_transport/shm_transport.h"
+
+namespace mooncake {
+
+class MultiTransportTestPeer {
+   public:
+    static Status selectTransport(MultiTransport& multi,
+                                  const Transport::TransferRequest& entry,
+                                  Transport*& transport,
+                                  bool* allows_reuse = nullptr) {
+        return multi.selectTransport(entry, transport, allows_reuse);
+    }
+
+    static Status selectTransports(
+        MultiTransport& multi,
+        const std::vector<Transport::TransferRequest>& entries,
+        std::vector<Transport*>& transports) {
+        return multi.selectTransports(entries, transports);
+    }
+};
+
+class ShmTransportTestPeer {
+   public:
+    static int install(ShmTransport& transport, std::string& local_server_name,
+                       std::shared_ptr<TransferMetadata> metadata) {
+        std::shared_ptr<Topology> topo;
+        return transport.install(local_server_name, metadata, topo);
+    }
+
+    static Status relocate(ShmTransport& transport, uint64_t& address,
+                           uint64_t length, Transport::SegmentID target_id) {
+        return transport.relocateSharedMemoryAddress(address, length,
+                                                     target_id);
+    }
+
+    static Status relocatePinned(
+        ShmTransport& transport, uint64_t& address, uint64_t length,
+        Transport::SegmentID target_id,
+        std::unique_ptr<ShmTransport::MappingPin>& pin) {
+        pin = std::make_unique<ShmTransport::MappingPin>();
+        return transport.relocateSharedMemoryAddress(address, length, target_id,
+                                                     pin.get());
+    }
+
+    static uint32_t pinCount(ShmTransport& transport,
+                             Transport::SegmentID target_id, uint64_t addr) {
+        RWSpinlock::ReadGuard guard(transport.relocate_lock_);
+        auto it = transport.relocate_map_.find(target_id);
+        if (it == transport.relocate_map_.end()) return 0;
+        auto mapping = it->second.find(addr);
+        if (mapping == it->second.end() || !mapping->second) return 0;
+        return mapping->second->pin_count.load();
+    }
+
+    static size_t mappingCount(ShmTransport& transport,
+                               Transport::SegmentID target_id) {
+        RWSpinlock::ReadGuard guard(transport.relocate_lock_);
+        auto it = transport.relocate_map_.find(target_id);
+        return it == transport.relocate_map_.end() ? 0 : it->second.size();
+    }
+
+    static size_t maxMappingsPerTarget() {
+        return ShmTransport::kMaxMappingsPerTarget;
+    }
+
+    static void* createSharedMemory(ShmTransport& transport,
+                                    const std::string& path, size_t size,
+                                    int* error = nullptr) {
+        return transport.createSharedMemory(path, size, error);
+    }
+
+    static int registerLocalMemory(ShmTransport& transport, void* addr,
+                                   size_t length,
+                                   const std::string& location = "cpu:0") {
+        return transport.registerLocalMemory(addr, length, location, true,
+                                             true);
+    }
+
+    static int registerLocalMemoryBatch(
+        ShmTransport& transport,
+        const std::vector<Transport::BufferEntry>& buffer_list,
+        const std::string& location = "cpu:0") {
+        return transport.registerLocalMemoryBatch(buffer_list, location);
+    }
+};
+
+namespace {
+
+constexpr Transport::SegmentID kPeerSegmentId = 1;
+constexpr uint64_t kRemoteAddress = 0x10000000;
+
+class ScopedShmFile {
+   public:
+    explicit ScopedShmFile(size_t length, const std::string& tag = "test")
+        : name_(std::string(kPosixShmNamePrefix) + tag + "_" +
+                std::to_string(getpid()) + "_" +
+                std::to_string(reinterpret_cast<uintptr_t>(this))),
+          length_(length) {
+        shm_unlink(name_.c_str());
+        fd_ = shm_open(name_.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600);
+        EXPECT_GE(fd_, 0);
+        if (fd_ >= 0) {
+            EXPECT_EQ(ftruncate(fd_, static_cast<off_t>(length_)), 0);
+            addr_ = mmap(nullptr, length_, PROT_READ | PROT_WRITE, MAP_SHARED,
+                         fd_, 0);
+            EXPECT_NE(addr_, MAP_FAILED);
+        }
+    }
+
+    ~ScopedShmFile() {
+        if (addr_ && addr_ != MAP_FAILED) munmap(addr_, length_);
+        if (fd_ >= 0) close(fd_);
+        shm_unlink(name_.c_str());
+    }
+
+    const std::string& name() const { return name_; }
+    void* addr() const { return addr_; }
+
+   private:
+    std::string name_;
+    size_t length_;
+    int fd_{-1};
+    void* addr_{nullptr};
+};
+
+void addPeerBuffers(
+    TransferMetadata& metadata,
+    const std::vector<std::pair<std::string, uint64_t>>& buffers,
+    size_t length) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19001";
+    desc->protocol = "tcp";
+    for (const auto& buffer_info : buffers) {
+        TransferMetadata::BufferDesc buffer;
+        buffer.name = "cpu:0";
+        buffer.addr = buffer_info.second;
+        buffer.length = length;
+        buffer.shm_name = buffer_info.first;
+        desc->buffers.push_back(buffer);
+    }
+    metadata.addLocalSegment(kPeerSegmentId, desc->name, std::move(desc));
+}
+
+void addPeerSegment(TransferMetadata& metadata, const std::string& shm_name,
+                    uint64_t remote_addr, size_t length) {
+    addPeerBuffers(metadata, {{shm_name, remote_addr}}, length);
+}
+
+}  // namespace
+
+TEST(ShmNameTest, PrefixDetectsPosixNames) {
+    EXPECT_TRUE(isPosixShmName("/mooncake_1234_abcdefgh"));
+    EXPECT_TRUE(isPosixShmName("mooncake_1234_abcdefgh"));
+    EXPECT_TRUE(isPosixShmName("/dev/hugepages/mooncake_1234_abcdefgh"));
+    EXPECT_TRUE(isFilesystemShmPath("/dev/hugepages/mooncake_1234_abcdefgh"));
+    EXPECT_FALSE(isFilesystemShmPath("/mooncake_1234_abcdefgh"));
+    EXPECT_TRUE(pathHasDotDotComponent("/dev/hugepages/../../tmp/mooncake_x"));
+    EXPECT_FALSE(isFilesystemShmPath("/dev/hugepages/../../tmp/mooncake_x"));
+    EXPECT_FALSE(pathHasDotDotComponent("/dev/hugepages/mooncake_x"));
+    EXPECT_FALSE(isPosixShmName(""));
+    EXPECT_FALSE(isPosixShmName("/mooncake_"));
+    EXPECT_FALSE(isPosixShmName("mooncake_"));
+    EXPECT_FALSE(isPosixShmName("cuda-ipc-handle"));
+    EXPECT_FALSE(isPosixShmName("/dev/hugepages/other_file"));
+}
+
+TEST(ShmTransportTest, SharesRelocationAcrossThreads) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile shm_file(page_size);
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_file.name(), kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    constexpr size_t kThreadCount = 8;
+    std::vector<uint64_t> relocated(kThreadCount, kRemoteAddress);
+    std::vector<std::thread> threads;
+    threads.reserve(kThreadCount);
+    for (size_t i = 0; i < kThreadCount; ++i) {
+        threads.emplace_back([&transport, &relocated, i, page_size]() {
+            auto status = ShmTransportTestPeer::relocate(
+                transport, relocated[i], page_size, kPeerSegmentId);
+            EXPECT_TRUE(status.ok()) << status.ToString();
+        });
+    }
+    for (auto& thread : threads) thread.join();
+
+    for (uint64_t address : relocated) EXPECT_EQ(address, relocated.front());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+
+    auto* mapped = reinterpret_cast<char*>(relocated.front());
+    mapped[0] = 0x5a;
+    EXPECT_EQ(static_cast<unsigned char*>(shm_file.addr())[0], 0x5a);
+}
+
+TEST(ShmTransportTest, ConsumerDoesNotCreateMissingFile) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const std::string shm_name = std::string(kPosixShmNamePrefix) + "missing_" +
+                                 std::to_string(getpid());
+    shm_unlink(shm_name.c_str());
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_name, kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    auto status = ShmTransportTestPeer::relocate(transport, address, page_size,
+                                                 kPeerSegmentId);
+    EXPECT_FALSE(status.ok());
+
+    std::string_view key = shm_name;
+    if (!key.empty() && key.front() == '/') key.remove_prefix(1);
+    std::string path = std::string("/dev/shm/") + std::string(key);
+    EXPECT_EQ(access(path.c_str(), F_OK), -1);
+    EXPECT_EQ(errno, ENOENT);
+}
+
+TEST(ShmTransportTest, RejectsBackingFileShorterThanBuffer) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const std::string shm_name =
+        std::string(kPosixShmNamePrefix) + "short_" + std::to_string(getpid());
+    shm_unlink(shm_name.c_str());
+    int fd = shm_open(shm_name.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600);
+    ASSERT_GE(fd, 0);
+    ASSERT_EQ(ftruncate(fd, static_cast<off_t>(page_size / 2)), 0);
+    close(fd);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_name, kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    auto status = ShmTransportTestPeer::relocate(transport, address, page_size,
+                                                 kPeerSegmentId);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 0);
+
+    shm_unlink(shm_name.c_str());
+}
+
+TEST(ShmTransportTest, CreateSharedMemoryDoesNotTruncateExisting) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile shm_file(page_size);
+    std::memset(shm_file.addr(), 0x3c, page_size);
+
+    ShmTransport transport;
+    int error = 0;
+    void* mapped = ShmTransportTestPeer::createSharedMemory(
+        transport, shm_file.name(), page_size, &error);
+    EXPECT_EQ(mapped, nullptr);
+    EXPECT_EQ(error, EEXIST);
+    EXPECT_EQ(static_cast<unsigned char*>(shm_file.addr())[0], 0x3c);
+}
+
+TEST(ShmTransportTest, RelocateMissKeepsExistingMappings) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile shm_file(page_size);
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_file.name(), kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+
+    uint64_t missing = kRemoteAddress + page_size * 4;
+    auto status = ShmTransportTestPeer::relocate(transport, missing, page_size,
+                                                 kPeerSegmentId);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+}
+
+TEST(ShmTransportTest, RelocateInvalidatesStaleShmName) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile first(page_size, "first");
+    ScopedShmFile second(page_size, "second");
+    std::memset(first.addr(), 0x11, page_size);
+    std::memset(second.addr(), 0x22, page_size);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, first.name(), kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+    std::memset(reinterpret_cast<void*>(address), 0xaa, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(first.addr())[0], 0xaa);
+    EXPECT_EQ(static_cast<unsigned char*>(second.addr())[0], 0x22);
+
+    addPeerSegment(*metadata, second.name(), kRemoteAddress, page_size);
+    address = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+    std::memset(reinterpret_cast<void*>(address), 0xbb, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(first.addr())[0], 0xaa);
+    EXPECT_EQ(static_cast<unsigned char*>(second.addr())[0], 0xbb);
+}
+
+TEST(ShmTransportTest, RelocateUnlinkedObjectDropsMapping) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile shm_file(page_size);
+    std::memset(shm_file.addr(), 0x11, page_size);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_file.name(), kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+    std::memset(reinterpret_cast<void*>(address), 0xaa, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(shm_file.addr())[0], 0xaa);
+
+    ASSERT_EQ(shm_unlink(shm_file.name().c_str()), 0);
+    address = kRemoteAddress;
+    auto status = ShmTransportTestPeer::relocate(transport, address, page_size,
+                                                 kPeerSegmentId);
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 0);
+    EXPECT_EQ(static_cast<unsigned char*>(shm_file.addr())[0], 0xaa);
+}
+
+TEST(ShmTransportTest, RelocatePrunesAddrsNotInDescriptor) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile first(page_size, "keep");
+    ScopedShmFile second(page_size, "drop");
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerBuffers(*metadata,
+                   {{first.name(), kRemoteAddress},
+                    {second.name(), kRemoteAddress + page_size}},
+                   page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t first_addr = kRemoteAddress;
+    uint64_t second_addr = kRemoteAddress + page_size;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, first_addr, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, second_addr,
+                                               page_size, kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 2);
+
+    addPeerBuffers(*metadata, {{first.name(), kRemoteAddress}}, page_size);
+    first_addr = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, first_addr, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+}
+
+TEST(ShmTransportTest, RelocateCapsMappingsPerTarget) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const size_t cap = ShmTransportTestPeer::maxMappingsPerTarget();
+    std::vector<std::unique_ptr<ScopedShmFile>> files;
+    std::vector<std::pair<std::string, uint64_t>> buffers;
+    files.reserve(cap + 1);
+    buffers.reserve(cap + 1);
+    for (size_t i = 0; i < cap + 1; ++i) {
+        files.push_back(std::make_unique<ScopedShmFile>(
+            page_size, "cap" + std::to_string(i)));
+        buffers.emplace_back(files.back()->name(),
+                             kRemoteAddress + i * page_size);
+    }
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerBuffers(*metadata, buffers, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    for (const auto& buffer : buffers) {
+        uint64_t address = buffer.second;
+        ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address,
+                                                   page_size, kPeerSegmentId)
+                        .ok());
+    }
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId),
+              cap);
+}
+
+TEST(ShmTransportTest, RelocatePinSurvivesCap) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const size_t cap = ShmTransportTestPeer::maxMappingsPerTarget();
+    std::vector<std::unique_ptr<ScopedShmFile>> files;
+    std::vector<std::pair<std::string, uint64_t>> buffers;
+    files.reserve(cap + 1);
+    buffers.reserve(cap + 1);
+    for (size_t i = 0; i < cap + 1; ++i) {
+        files.push_back(std::make_unique<ScopedShmFile>(
+            page_size, "pin-cap" + std::to_string(i)));
+        buffers.emplace_back(files.back()->name(),
+                             kRemoteAddress + i * page_size);
+    }
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerBuffers(*metadata, buffers, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t pinned_addr = buffers.front().second;
+    std::unique_ptr<ShmTransport::MappingPin> pin;
+    ASSERT_TRUE(ShmTransportTestPeer::relocatePinned(
+                    transport, pinned_addr, page_size, kPeerSegmentId, pin)
+                    .ok());
+    ASSERT_TRUE(pin && *pin);
+    EXPECT_EQ(ShmTransportTestPeer::pinCount(transport, kPeerSegmentId,
+                                             buffers.front().second),
+              1u);
+
+    for (size_t i = 1; i < buffers.size(); ++i) {
+        uint64_t address = buffers[i].second;
+        ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, address,
+                                                   page_size, kPeerSegmentId)
+                        .ok());
+    }
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId),
+              cap);
+    EXPECT_EQ(ShmTransportTestPeer::pinCount(transport, kPeerSegmentId,
+                                             buffers.front().second),
+              1u);
+
+    std::memset(reinterpret_cast<void*>(pinned_addr), 0xab, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(files.front()->addr())[0], 0xab);
+
+    pin.reset();
+    EXPECT_EQ(ShmTransportTestPeer::pinCount(transport, kPeerSegmentId,
+                                             buffers.front().second),
+              0u);
+}
+
+TEST(ShmTransportTest, RelocatePinSurvivesPrune) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile first(page_size, "keep");
+    ScopedShmFile second(page_size, "drop");
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerBuffers(*metadata,
+                   {{first.name(), kRemoteAddress},
+                    {second.name(), kRemoteAddress + page_size}},
+                   page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t first_addr = kRemoteAddress;
+    uint64_t second_addr = kRemoteAddress + page_size;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, first_addr, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    std::unique_ptr<ShmTransport::MappingPin> pin;
+    ASSERT_TRUE(ShmTransportTestPeer::relocatePinned(
+                    transport, second_addr, page_size, kPeerSegmentId, pin)
+                    .ok());
+    ASSERT_TRUE(pin && *pin);
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 2);
+
+    addPeerBuffers(*metadata, {{first.name(), kRemoteAddress}}, page_size);
+    first_addr = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, first_addr, page_size,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_EQ(ShmTransportTestPeer::mappingCount(transport, kPeerSegmentId), 1);
+
+    std::memset(reinterpret_cast<void*>(second_addr), 0xcd, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(second.addr())[0], 0xcd);
+
+    pin.reset();
+    std::memset(reinterpret_cast<void*>(first_addr), 0xef, page_size);
+    EXPECT_EQ(static_cast<unsigned char*>(first.addr())[0], 0xef);
+}
+
+TEST(ShmTransportTest, RelocateCopySurvivesConcurrentCap) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const size_t cap = ShmTransportTestPeer::maxMappingsPerTarget();
+    std::vector<std::unique_ptr<ScopedShmFile>> files;
+    std::vector<std::pair<std::string, uint64_t>> buffers;
+    files.reserve(cap + 1);
+    buffers.reserve(cap + 1);
+    for (size_t i = 0; i < cap + 1; ++i) {
+        files.push_back(std::make_unique<ScopedShmFile>(
+            page_size, "race" + std::to_string(i)));
+        buffers.emplace_back(files.back()->name(),
+                             kRemoteAddress + i * page_size);
+    }
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerBuffers(*metadata, buffers, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t pinned_addr = buffers.front().second;
+    std::unique_ptr<ShmTransport::MappingPin> pin;
+    ASSERT_TRUE(ShmTransportTestPeer::relocatePinned(
+                    transport, pinned_addr, page_size, kPeerSegmentId, pin)
+                    .ok());
+    ASSERT_TRUE(pin && *pin);
+
+    std::atomic<bool> stop{false};
+    std::thread copier([&]() {
+        std::vector<char> src(page_size, 0x5a);
+        // The cap loop may finish before this thread is scheduled.
+        do {
+            std::memcpy(reinterpret_cast<void*>(pinned_addr), src.data(),
+                        page_size);
+        } while (!stop.load());
+    });
+    for (int round = 0; round < 4; ++round) {
+        for (const auto& buffer : buffers) {
+            uint64_t address = buffer.second;
+            auto status = ShmTransportTestPeer::relocate(
+                transport, address, page_size, kPeerSegmentId);
+            EXPECT_TRUE(status.ok()) << status.ToString();
+        }
+    }
+    stop.store(true);
+    copier.join();
+    pin.reset();
+    EXPECT_EQ(static_cast<unsigned char*>(files.front()->addr())[0], 0x5a);
+}
+
+TEST(ShmTransportTest, SubmitIsAllOrNothingWhenRelocateFailsMidBatch) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    ScopedShmFile shm_file(page_size);
+    std::memset(shm_file.addr(), 0x11, page_size);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, shm_file.name(), kRemoteAddress, page_size);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    std::vector<char> src(page_size, 0x22);
+    Transport::TransferRequest ok;
+    ok.opcode = Transport::TransferRequest::WRITE;
+    ok.source = src.data();
+    ok.target_id = kPeerSegmentId;
+    ok.target_offset = kRemoteAddress;
+    ok.length = page_size;
+
+    Transport::TransferRequest bad = ok;
+    bad.target_offset = kRemoteAddress + page_size * 8;
+
+    auto batch = transport.allocateBatchID(2);
+    ASSERT_NE(batch, static_cast<Transport::BatchID>(ERR_MEMORY));
+    auto status = transport.submitTransfer(batch, {ok, bad});
+    EXPECT_FALSE(status.ok());
+    EXPECT_EQ(static_cast<unsigned char*>(shm_file.addr())[0], 0x11);
+    ASSERT_TRUE(transport.freeBatchID(batch).ok());
+}
+
+TEST(ShmTransportTest, LocalSegmentCopiesWithoutShmOpen) {
+    const size_t length = 4096;
+    std::vector<char> src(length, 0x44);
+    std::vector<char> dst(length, 0);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    Transport::TransferRequest req;
+    req.opcode = Transport::TransferRequest::WRITE;
+    req.source = src.data();
+    req.target_id = LOCAL_SEGMENT_ID;
+    req.target_offset = reinterpret_cast<uint64_t>(dst.data());
+    req.length = length;
+
+    auto batch = transport.allocateBatchID(1);
+    ASSERT_TRUE(transport.submitTransfer(batch, {req}).ok());
+    Transport::TransferStatus st;
+    ASSERT_TRUE(transport.getTransferStatus(batch, 0, st).ok());
+    EXPECT_EQ(st.s, Transport::TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(dst, src);
+    ASSERT_TRUE(transport.freeBatchID(batch).ok());
+}
+
+TEST(ShmTransportTest, RegisterRejectsSubRangeAndOverflow) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    void* base = transport.allocateSharedMemory(page_size * 2);
+    ASSERT_NE(base, nullptr);
+    auto* mid = static_cast<char*>(base) + page_size;
+    EXPECT_EQ(
+        ShmTransportTestPeer::registerLocalMemory(transport, mid, page_size),
+        ERR_INVALID_ARGUMENT);
+    EXPECT_EQ(ShmTransportTestPeer::registerLocalMemory(transport, base,
+                                                        page_size * 2 + 1),
+              ERR_INVALID_ARGUMENT);
+
+    std::vector<char> heap(page_size);
+    EXPECT_EQ(ShmTransportTestPeer::registerLocalMemory(transport, heap.data(),
+                                                        page_size),
+              0);
+
+    ASSERT_EQ(
+        ShmTransportTestPeer::registerLocalMemory(transport, base, page_size),
+        0);
+    auto desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    ASSERT_EQ(desc->buffers.size(), 1u);
+    EXPECT_EQ(desc->buffers[0].addr, reinterpret_cast<uint64_t>(base));
+    EXPECT_EQ(desc->buffers[0].length, page_size);
+    EXPECT_TRUE(isPosixShmName(desc->buffers[0].shm_name));
+
+    ASSERT_EQ(transport.freeSharedMemory(base), 0);
+}
+
+TEST(ShmTransportTest, RegisterBatchSkipsMallocAndExportsShm) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    std::vector<char> heap(page_size);
+    Transport::BufferEntry heap_entry{heap.data(), page_size};
+    EXPECT_EQ(
+        ShmTransportTestPeer::registerLocalMemoryBatch(transport, {heap_entry}),
+        0);
+    auto desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    for (const auto& buffer : desc->buffers) {
+        EXPECT_FALSE(isPosixShmName(buffer.shm_name));
+    }
+
+    void* base = transport.allocateSharedMemory(page_size);
+    ASSERT_NE(base, nullptr);
+    std::string shm_name;
+    ASSERT_TRUE(transport.getShmName(base, &shm_name));
+    ASSERT_FALSE(shm_name.empty());
+    EXPECT_EQ(shm_name.front(), '/');
+    EXPECT_TRUE(isPosixShmName(shm_name));
+
+    Transport::BufferEntry shm_entry{base, page_size};
+    EXPECT_EQ(ShmTransportTestPeer::registerLocalMemoryBatch(
+                  transport, {heap_entry, shm_entry}),
+              0);
+    desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    int posix_buffers = 0;
+    for (const auto& buffer : desc->buffers) {
+        if (isPosixShmName(buffer.shm_name)) ++posix_buffers;
+    }
+    EXPECT_EQ(posix_buffers, 1);
+    ASSERT_EQ(transport.freeSharedMemory(base), 0);
+}
+
+TEST(ShmTransportTest, RegisterShorterPrefixAndPeerRelocate) {
+    const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE));
+    const size_t alloc_len = page_size * 2;
+    const size_t prefix_len = page_size;
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    void* base = transport.allocateSharedMemory(alloc_len);
+    ASSERT_NE(base, nullptr);
+    std::string shm_name;
+    ASSERT_TRUE(transport.getShmName(base, &shm_name));
+
+    ASSERT_EQ(
+        ShmTransportTestPeer::registerLocalMemory(transport, base, prefix_len),
+        0);
+    auto desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    ASSERT_FALSE(desc->buffers.empty());
+    EXPECT_EQ(desc->buffers[0].length, prefix_len);
+
+    addPeerSegment(*metadata, shm_name, kRemoteAddress, prefix_len);
+    uint64_t relocated = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, relocated, prefix_len,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_NE(relocated, kRemoteAddress);
+    auto* mapped = reinterpret_cast<char*>(relocated);
+    mapped[0] = 0x5d;
+    EXPECT_EQ(static_cast<char*>(base)[0], 0x5d);
+
+    ASSERT_EQ(transport.freeSharedMemory(base), 0);
+}
+
+class ShmHugepageAllocateTest : public ::testing::TestWithParam<size_t> {};
+
+TEST_P(ShmHugepageAllocateTest, AllocateRegisterAndRelocate) {
+    const size_t length = GetParam();
+    auto mount = FindHugetlbfsMount(length);
+    if (!mount) {
+        GTEST_SKIP() << "No writable " << HugepageSizeLabel(length)
+                     << " hugetlbfs mount";
+    }
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = length;
+    opt.hugetlbfs_path = *mount;
+    opt.populate = false;
+
+    void* base = transport.allocateSharedMemory(length, opt);
+    if (!base) {
+        GTEST_SKIP() << HugepageSizeLabel(length)
+                     << " hugetlbfs mount present but allocation failed "
+                        "(no free hugepages?)";
+    }
+    std::string shm_name;
+    ASSERT_TRUE(transport.getShmName(base, &shm_name));
+    EXPECT_TRUE(isFilesystemShmPath(shm_name));
+    EXPECT_TRUE(isPosixShmName(shm_name));
+    EXPECT_EQ(shm_name.rfind(*mount, 0), 0u);
+
+    ASSERT_EQ(
+        ShmTransportTestPeer::registerLocalMemory(transport, base, length), 0);
+    auto desc = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(desc);
+    ASSERT_FALSE(desc->buffers.empty());
+    EXPECT_TRUE(isFilesystemShmPath(desc->buffers[0].shm_name));
+    EXPECT_EQ(desc->buffers[0].length, length);
+
+    addPeerSegment(*metadata, shm_name, kRemoteAddress, length);
+    uint64_t relocated = kRemoteAddress;
+    ASSERT_TRUE(ShmTransportTestPeer::relocate(transport, relocated, length,
+                                               kPeerSegmentId)
+                    .ok());
+    EXPECT_NE(relocated, kRemoteAddress);
+    auto* mapped = reinterpret_cast<char*>(relocated);
+    mapped[0] = 0x5a;
+    EXPECT_EQ(static_cast<char*>(base)[0], 0x5a);
+
+    ASSERT_EQ(transport.freeSharedMemory(base), 0);
+    EXPECT_EQ(access(shm_name.c_str(), F_OK), -1);
+}
+
+INSTANTIATE_TEST_SUITE_P(HugepageSizes, ShmHugepageAllocateTest,
+                         ::testing::Values(SharedMemoryOptions::kHugepage2MB,
+                                           SharedMemoryOptions::kHugepage512MB,
+                                           SharedMemoryOptions::kHugepage1GB),
+                         [](const testing::TestParamInfo<size_t>& info) {
+                             return HugepageSizeTestName(info.param);
+                         });
+
+TEST(ShmTransportTest, HugepageRejectsUnsupportedSize) {
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = 64ULL * 1024;  // not a Store/TE hugepage size
+    opt.hugetlbfs_path = "/tmp/mooncake_hugepages_2m";
+    EXPECT_EQ(transport.allocateSharedMemory(opt.hugepage_size, opt), nullptr);
+}
+
+TEST(ShmTransportTest, HugepageRejectsUnalignedLength) {
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = SharedMemoryOptions::kHugepage2MB;
+    opt.hugetlbfs_path = "/tmp/mooncake_hugepages_2m";
+    opt.populate = false;
+    EXPECT_EQ(transport.allocateSharedMemory(4096, opt), nullptr);
+}
+
+TEST(ShmTransportTest, HugepageRejectsPageSizeMismatch) {
+    auto mount_2m = FindHugetlbfsMount(SharedMemoryOptions::kHugepage2MB);
+    if (!mount_2m) {
+        GTEST_SKIP() << "No writable 2MB hugetlbfs mount";
+    }
+    // Request 1GB against a 2MB mount → must fail (no tmpfs fallback).
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = SharedMemoryOptions::kHugepage1GB;
+    opt.hugetlbfs_path = *mount_2m;
+    opt.populate = false;
+    EXPECT_EQ(
+        transport.allocateSharedMemory(SharedMemoryOptions::kHugepage1GB, opt),
+        nullptr);
+}
+
+TEST(ShmTransportTest, HugepageDoesNotFallbackToTmpfs) {
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = SharedMemoryOptions::kHugepage2MB;
+    opt.hugetlbfs_path = "/tmp/mooncake_not_a_hugetlbfs_mount";
+    opt.populate = false;
+    EXPECT_EQ(
+        transport.allocateSharedMemory(SharedMemoryOptions::kHugepage2MB, opt),
+        nullptr);
+}
+
+TEST(ShmTransportTest, HugepageRejectsRelativeMount) {
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = SharedMemoryOptions::kHugepage2MB;
+    opt.hugetlbfs_path = "hugepages";
+    opt.populate = false;
+    EXPECT_EQ(
+        transport.allocateSharedMemory(SharedMemoryOptions::kHugepage2MB, opt),
+        nullptr);
+}
+
+TEST(ShmTransportTest, HugepageRejectsDotDotMount) {
+    ShmTransport transport;
+    SharedMemoryOptions opt;
+    opt.use_hugepage = true;
+    opt.hugepage_size = SharedMemoryOptions::kHugepage2MB;
+    opt.hugetlbfs_path = "/dev/hugepages/../hugepages";
+    opt.populate = false;
+    EXPECT_EQ(
+        transport.allocateSharedMemory(SharedMemoryOptions::kHugepage2MB, opt),
+        nullptr);
+}
+
+TEST(ShmTransportTest, RelocateRejectsTraversalFilesystemPath) {
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, "/dev/hugepages/../../tmp/mooncake_poison",
+                   kRemoteAddress, 4096);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    EXPECT_FALSE(
+        ShmTransportTestPeer::relocate(transport, address, 4096, kPeerSegmentId)
+            .ok());
+}
+
+TEST(ShmTransportTest, RelocateRejectsNonHugetlbfsFilesystemPath) {
+    char tmpl[] = "/tmp/mooncake_XXXXXX";
+    int fd = mkstemp(tmpl);
+    ASSERT_GE(fd, 0);
+    ASSERT_EQ(ftruncate(fd, 4096), 0);
+    close(fd);
+
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    addPeerSegment(*metadata, tmpl, kRemoteAddress, 4096);
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+
+    uint64_t address = kRemoteAddress;
+    EXPECT_FALSE(
+        ShmTransportTestPeer::relocate(transport, address, 4096, kPeerSegmentId)
+            .ok());
+    unlink(tmpl);
+}
+
+#ifndef ENABLE_MULTI_PROTOCOL
+TEST(ShmTransportTest, InstallReplacesNonShmProtocol) {
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19000";
+    desc->protocol = "tcp";
+    metadata->addLocalSegment(LOCAL_SEGMENT_ID, desc->name, std::move(desc));
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+    auto installed = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(installed);
+    EXPECT_EQ(installed->protocol, "shm");
+}
+#endif
+
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST(ShmTransportTest, InstallDoesNotTreatUbshmemAsShm) {
+    auto metadata = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19000";
+    desc->protocol = "ubshmem";
+    metadata->addLocalSegment(LOCAL_SEGMENT_ID, desc->name, std::move(desc));
+
+    ShmTransport transport;
+    std::string local = "127.0.0.1:19000";
+    ASSERT_EQ(ShmTransportTestPeer::install(transport, local, metadata), 0);
+    auto installed = metadata->getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_TRUE(installed);
+    EXPECT_EQ(installed->protocol, "ubshmem,shm");
+}
+#endif
+
+class ShmRoutingTest : public ::testing::Test {
+   protected:
+    static constexpr uint64_t kRemoteAddr = 0x10000000;
+
+    void SetUp() override {
+        metadata_ = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+        local_name_ = "127.0.0.1:19000";
+        multi_ = std::make_unique<MultiTransport>(metadata_, local_name_);
+        ASSERT_NE(multi_->installTransport("shm", nullptr), nullptr);
+        shm_ = multi_->getTransport("shm");
+        ASSERT_NE(shm_, nullptr);
+    }
+
+    void AddBuffer(TransferMetadata::SegmentDesc& desc,
+                   const std::string& shm_name,
+                   const std::string& buffer_protocol,
+                   uint64_t addr = kRemoteAddr, uint64_t length = 4096) {
+        TransferMetadata::BufferDesc buffer;
+        buffer.name = "cpu:0";
+        buffer.addr = addr;
+        buffer.length = length;
+        buffer.shm_name = shm_name;
+#ifdef ENABLE_MULTI_PROTOCOL
+        buffer.protocol = buffer_protocol;
+#else
+        (void)buffer_protocol;
+#endif
+        desc.buffers.push_back(buffer);
+    }
+
+    Transport::SegmentID AddPeer(const std::string& segment_name,
+                                 const std::string& shm_name,
+                                 const std::string& protocol = "shm",
+                                 const std::string& buffer_protocol = "") {
+        auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+        desc->name = segment_name;
+        desc->protocol = protocol;
+        AddBuffer(*desc, shm_name,
+                  buffer_protocol.empty() ? protocol : buffer_protocol);
+        const Transport::SegmentID id = next_segment_id_++;
+        metadata_->addLocalSegment(id, segment_name, std::move(desc));
+        return id;
+    }
+
+    Transport::TransferRequest MakeWrite(
+        Transport::SegmentID id, uint64_t target_offset = kRemoteAddr) const {
+        Transport::TransferRequest request;
+        request.opcode = Transport::TransferRequest::WRITE;
+        request.source = nullptr;
+        request.target_id = id;
+        request.target_offset = target_offset;
+        request.length = 64;
+        return request;
+    }
+
+    std::shared_ptr<TransferMetadata> metadata_;
+    std::string local_name_;
+    std::unique_ptr<MultiTransport> multi_;
+    Transport* shm_{nullptr};
+    Transport::SegmentID next_segment_id_{10};
+};
+
+TEST_F(ShmRoutingTest, SameHostSelectsShm) {
+    auto id = AddPeer("127.0.0.1:19001", "mooncake_1_abcdefgh");
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(transport, shm_);
+}
+
+#ifndef ENABLE_MULTI_PROTOCOL
+TEST_F(ShmRoutingTest, CrossHostStillSelectsShmWithoutMultiProtocol) {
+    auto id = AddPeer("10.0.0.2:19001", "mooncake_1_abcdefgh");
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(transport, shm_);
+}
+#endif
+
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST_F(ShmRoutingTest, SameHostShmBeatsTcp) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19001";
+    desc->protocol = "tcp,shm";
+    AddBuffer(*desc, "", "tcp");
+    AddBuffer(*desc, "mooncake_1_abcdefgh", "shm");
+    const auto id = next_segment_id_++;
+    metadata_->addLocalSegment(id, desc->name, std::move(desc));
+
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(transport, shm_);
+}
+
+TEST_F(ShmRoutingTest, CrossHostSkipsShm) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "10.0.0.2:19001";
+    desc->protocol = "tcp,shm";
+    AddBuffer(*desc, "", "tcp");
+    AddBuffer(*desc, "mooncake_1_abcdefgh", "shm");
+    const auto id = next_segment_id_++;
+    metadata_->addLocalSegment(id, desc->name, std::move(desc));
+
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.IsNotSupportedTransport()) << status.ToString();
+    EXPECT_NE(transport, shm_);
+}
+
+TEST_F(ShmRoutingTest, TcpOnlyBufferDoesNotSelectShm) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19001";
+    desc->protocol = "tcp,shm";
+    AddBuffer(*desc, "", "tcp");
+    const auto id = next_segment_id_++;
+    metadata_->addLocalSegment(id, desc->name, std::move(desc));
+
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.IsNotSupportedTransport()) << status.ToString();
+    EXPECT_NE(transport, shm_);
+}
+
+TEST_F(ShmRoutingTest, HipBufferDoesNotSelectShm) {
+    auto id =
+        AddPeer("127.0.0.1:19001", "mooncake_1_abcdefgh", "tcp,hip", "hip");
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    auto status =
+        MultiTransportTestPeer::selectTransport(*multi_, request, transport);
+    EXPECT_TRUE(status.IsNotSupportedTransport()) << status.ToString();
+    EXPECT_NE(transport, shm_);
+}
+#endif
+
+TEST_F(ShmRoutingTest, HomogeneousProtocolAllowsReuse) {
+    auto id = AddPeer("127.0.0.1:19001", "mooncake_1_abcdefgh");
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    bool allows_reuse = false;
+    auto status = MultiTransportTestPeer::selectTransport(
+        *multi_, request, transport, &allows_reuse);
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(transport, shm_);
+    EXPECT_TRUE(allows_reuse);
+}
+
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST_F(ShmRoutingTest, CommaProtocolDisablesReuse) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19001";
+    desc->protocol = "tcp,shm";
+    AddBuffer(*desc, "", "tcp");
+    AddBuffer(*desc, "mooncake_1_abcdefgh", "shm");
+    const auto id = next_segment_id_++;
+    metadata_->addLocalSegment(id, desc->name, std::move(desc));
+
+    auto request = MakeWrite(id);
+    Transport* transport = nullptr;
+    bool allows_reuse = true;
+    auto status = MultiTransportTestPeer::selectTransport(
+        *multi_, request, transport, &allows_reuse);
+    EXPECT_TRUE(status.ok()) << status.ToString();
+    EXPECT_EQ(transport, shm_);
+    EXPECT_FALSE(allows_reuse);
+}
+#endif
+
+TEST_F(ShmRoutingTest, InvalidSegmentClearsReuse) {
+    auto request = MakeWrite(9999);
+    Transport* transport = nullptr;
+    bool allows_reuse = true;
+    auto status = MultiTransportTestPeer::selectTransport(
+        *multi_, request, transport, &allows_reuse);
+    EXPECT_FALSE(status.ok());
+    EXPECT_FALSE(allows_reuse);
+}
+
+TEST_F(ShmRoutingTest, ReuseLoopMatchesPerRequestSelect) {
+    auto first = AddPeer("127.0.0.1:19001", "mooncake_1_abcdefgh");
+    auto second = AddPeer("127.0.0.1:19002", "mooncake_2_abcdefgh");
+    const std::vector<Transport::TransferRequest> entries = {
+        MakeWrite(first), MakeWrite(first), MakeWrite(second),
+        MakeWrite(first)};
+
+    std::vector<Transport*> got;
+    auto status =
+        MultiTransportTestPeer::selectTransports(*multi_, entries, got);
+    ASSERT_TRUE(status.ok()) << status.ToString();
+    ASSERT_EQ(got.size(), entries.size());
+    for (size_t i = 0; i < entries.size(); ++i) {
+        Transport* expected = nullptr;
+        auto per_request = MultiTransportTestPeer::selectTransport(
+            *multi_, entries[i], expected);
+        ASSERT_TRUE(per_request.ok()) << per_request.ToString();
+        EXPECT_EQ(got[i], expected) << "index " << i;
+        EXPECT_EQ(got[i], shm_);
+    }
+}
+
+TEST_F(ShmRoutingTest, ReuseLoopDoesNotReuseUnsupportedTarget) {
+    auto first = AddPeer("127.0.0.1:19001", "mooncake_1_abcdefgh");
+    auto second = AddPeer("127.0.0.1:19002", "mooncake_2_abcdefgh", "rdma");
+    const std::vector<Transport::TransferRequest> entries = {
+        MakeWrite(first), MakeWrite(first), MakeWrite(second)};
+
+    std::vector<Transport*> got;
+    auto status =
+        MultiTransportTestPeer::selectTransports(*multi_, entries, got);
+    EXPECT_TRUE(status.IsNotSupportedTransport()) << status.ToString();
+    EXPECT_EQ(got.size(), 2u);
+    EXPECT_EQ(got[0], shm_);
+    EXPECT_EQ(got[1], shm_);
+}
+
+#ifdef ENABLE_MULTI_PROTOCOL
+TEST_F(ShmRoutingTest, ReuseLoopDoesNotSkipMixedProtocolOffsets) {
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "127.0.0.1:19001";
+    desc->protocol = "tcp,shm";
+    AddBuffer(*desc, "", "tcp", kRemoteAddr);
+    AddBuffer(*desc, "mooncake_1_abcdefgh", "shm", kRemoteAddr + 4096);
+    const auto id = next_segment_id_++;
+    metadata_->addLocalSegment(id, desc->name, std::move(desc));
+
+    const std::vector<Transport::TransferRequest> entries = {
+        MakeWrite(id, kRemoteAddr + 4096), MakeWrite(id, kRemoteAddr)};
+    std::vector<Transport*> got;
+    auto status =
+        MultiTransportTestPeer::selectTransports(*multi_, entries, got);
+    EXPECT_TRUE(status.IsNotSupportedTransport()) << status.ToString();
+    EXPECT_EQ(got.size(), 1u);
+    EXPECT_EQ(got[0], shm_);
+}
+#endif
+
+}  // namespace mooncake
diff --git a/mooncake-transfer-engine/tests/tcp_cuda_staging_test.cpp b/mooncake-transfer-engine/tests/tcp_cuda_staging_test.cpp
new file mode 100644
index 0000000000..b4e674a736
--- /dev/null
+++ b/mooncake-transfer-engine/tests/tcp_cuda_staging_test.cpp
@@ -0,0 +1,186 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <optional>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "cuda_alike.h"
+#include "transfer_engine.h"
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+namespace mooncake {
+void tcpTransportResetStagingStatsForTest() noexcept;
+size_t tcpTransportStagingBufferAllocationCountForTest() noexcept;
+size_t tcpTransportStagingDeviceQueryCountForTest() noexcept;
+}  // namespace mooncake
+#endif
+
+namespace {
+
+using namespace mooncake;
+
+class ScopedEnvVar {
+   public:
+    ScopedEnvVar(const char* name, const char* value) : name_(name) {
+        const char* current = std::getenv(name);
+        if (current) old_value_ = current;
+        setenv(name, value, 1);
+    }
+
+    ~ScopedEnvVar() {
+        if (old_value_)
+            setenv(name_.c_str(), old_value_->c_str(), 1);
+        else
+            unsetenv(name_.c_str());
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> old_value_;
+};
+
+class DeviceBuffer {
+   public:
+    ~DeviceBuffer() {
+        if (data_) cudaFree(data_);
+    }
+
+    void** out() { return &data_; }
+    void* get() const { return data_; }
+
+   private:
+    void* data_ = nullptr;
+};
+
+TransferStatusEnum runOne(TransferEngine* engine,
+                          const TransferRequest& request) {
+    auto batch_id = engine->allocateBatchID(1);
+    if (!engine->submitTransfer(batch_id, {request}).ok()) {
+        (void)engine->freeBatchID(batch_id);
+        return TransferStatusEnum::FAILED;
+    }
+    TransferStatus status;
+    status.s = TransferStatusEnum::WAITING;
+    const auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::seconds(15);
+    while (status.s != TransferStatusEnum::COMPLETED &&
+           status.s != TransferStatusEnum::FAILED &&
+           std::chrono::steady_clock::now() < deadline) {
+        if (!engine->getTransferStatus(batch_id, 0, status).ok()) {
+            status.s = TransferStatusEnum::FAILED;
+            break;
+        }
+        if (status.s == TransferStatusEnum::WAITING)
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    if (status.s == TransferStatusEnum::WAITING)
+        status.s = TransferStatusEnum::TIMEOUT;
+    (void)engine->freeBatchID(batch_id);
+    return status.s;
+}
+
+TEST(TcpCudaStagingTest, ReusesStagingAcrossChunksAndRequests) {
+    int device_count = 0;
+    cudaError_t cuda_status = cudaGetDeviceCount(&device_count);
+    if (cuda_status != cudaSuccess || device_count == 0) {
+        GTEST_SKIP() << "CUDA device unavailable";
+    }
+    ASSERT_EQ(cudaSetDevice(0), cudaSuccess);
+
+    ScopedEnvVar connection_pool("MC_TCP_ENABLE_CONNECTION_POOL", "1");
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar slice_size("MC_TCP_SLICE_SIZE", "65536");
+
+    constexpr size_t kChunkSize = 64 * 1024;
+    constexpr size_t kTransferSize = 8 * kChunkSize;
+    constexpr size_t kBufferSize = 3 * kTransferSize;
+
+    DeviceBuffer device_buffer;
+    ASSERT_EQ(cudaMalloc(device_buffer.out(), kBufferSize), cudaSuccess);
+    ASSERT_EQ(cudaMemset(device_buffer.get(), 0, kBufferSize), cudaSuccess);
+
+    std::vector<unsigned char> pattern(kTransferSize);
+    for (size_t i = 0; i < pattern.size(); ++i)
+        pattern[i] = static_cast<unsigned char>((i * 37 + 11) & 0xFF);
+    ASSERT_EQ(cudaMemcpy(device_buffer.get(), pattern.data(), pattern.size(),
+                         cudaMemcpyHostToDevice),
+              cudaSuccess);
+
+    auto engine = std::make_unique<TransferEngine>(false);
+    const std::string server_name = "127.0.0.2:17931";
+    const auto hostname_port = parseHostNameWithPort(server_name);
+    ASSERT_EQ(engine->init(P2PHANDSHAKE, server_name,
+                           hostname_port.first.c_str(), hostname_port.second),
+              0);
+    ASSERT_NE(engine->installTransport("tcp", nullptr), nullptr);
+    ASSERT_EQ(
+        engine->registerLocalMemory(device_buffer.get(), kBufferSize, "cuda:0"),
+        0);
+
+    const auto segment_id = engine->openSegment(engine->getLocalIpAndPort());
+    const auto segment_desc =
+        engine->getMetadata()->getSegmentDescByID(segment_id);
+    ASSERT_NE(segment_desc, nullptr);
+    ASSERT_FALSE(segment_desc->buffers.empty());
+    const uint64_t remote_base = segment_desc->buffers[0].addr;
+    auto* device_bytes = static_cast<unsigned char*>(device_buffer.get());
+
+    tcpTransportResetStagingStatsForTest();
+    TransferRequest write;
+    write.opcode = TransferRequest::WRITE;
+    write.length = kTransferSize;
+    write.source = device_bytes;
+    write.target_id = segment_id;
+    write.target_offset = remote_base + kTransferSize;
+    ASSERT_EQ(runOne(engine.get(), write), TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(tcpTransportStagingDeviceQueryCountForTest(), 2u);
+    EXPECT_EQ(tcpTransportStagingBufferAllocationCountForTest(), 2u);
+
+    std::vector<unsigned char> actual(kTransferSize);
+    ASSERT_EQ(cudaMemcpy(actual.data(), device_bytes + kTransferSize,
+                         actual.size(), cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_EQ(actual, pattern);
+
+    tcpTransportResetStagingStatsForTest();
+    TransferRequest read;
+    read.opcode = TransferRequest::READ;
+    read.length = kTransferSize;
+    read.source = device_bytes + 2 * kTransferSize;
+    read.target_id = segment_id;
+    read.target_offset = remote_base + kTransferSize;
+    ASSERT_EQ(runOne(engine.get(), read), TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(tcpTransportStagingDeviceQueryCountForTest(), 2u);
+    // The client session is new; the persistent server session retains the
+    // staging allocation used by the preceding WRITE.
+    EXPECT_EQ(tcpTransportStagingBufferAllocationCountForTest(), 1u);
+
+    ASSERT_EQ(cudaMemcpy(actual.data(), device_bytes + 2 * kTransferSize,
+                         actual.size(), cudaMemcpyDeviceToHost),
+              cudaSuccess);
+    EXPECT_EQ(actual, pattern);
+
+    EXPECT_EQ(engine->unregisterLocalMemory(device_buffer.get()), 0);
+    engine.reset();
+}
+
+}  // namespace
diff --git a/mooncake-transfer-engine/tests/tcp_write_visibility_test.cpp b/mooncake-transfer-engine/tests/tcp_write_visibility_test.cpp
index 6bc9d23408..5076e78d5c 100644
--- a/mooncake-transfer-engine/tests/tcp_write_visibility_test.cpp
+++ b/mooncake-transfer-engine/tests/tcp_write_visibility_test.cpp
@@ -30,23 +30,53 @@
 #include <gflags/gflags.h>
 #include <glog/logging.h>
 #include <gtest/gtest.h>
+#include <json/json.h>
 #include <sys/mman.h>
 #include <sys/socket.h>
 #include <unistd.h>
 
 #include <algorithm>
 #include <atomic>
+#include <cctype>
 #include <chrono>
+#include <condition_variable>
 #include <cstdlib>
 #include <cstring>
+#include <future>
 #include <memory>
+#include <mutex>
+#include <sstream>
 #include <string>
 #include <thread>
+#include <unordered_map>
 #include <vector>
 
+#include "common.h"
 #include "transfer_engine.h"
 #include "transport/transport.h"
 
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+namespace mooncake {
+void tcpTransportSetLaneConnectHandlerHookForTest(
+    void (*hook)() noexcept) noexcept;
+void tcpTransportSetLaneConnectFailureInjectionHookForTest(
+    bool (*hook)(size_t) noexcept) noexcept;
+void tcpTransportSetLaneObserverHookForTest(
+    void (*hook)(int, size_t, uint64_t, size_t, bool) noexcept) noexcept;
+void tcpTransportSetLaneRetryHandlerHookForTest(
+    void (*hook)() noexcept) noexcept;
+void tcpTransportSetLaneAdmissionHandlerHookForTest(
+    void (*hook)() noexcept) noexcept;
+void tcpTransportSetLaneFailureReasonHookForTest(
+    void (*hook)(int) noexcept) noexcept;
+void tcpTransportSetSessionProgressHookForTest(
+    int (*hook)(int, bool) noexcept) noexcept;
+void tcpTransportSetStartTransferMetadataHookForTest(
+    void (*hook)() noexcept) noexcept;
+bool tcpTransportLaneTypesAreMoveOnlyForTest() noexcept;
+}  // namespace mooncake
+#endif
+
 using namespace mooncake;
 
 namespace {
@@ -57,6 +87,476 @@ constexpr size_t kRegionAlign = 4 * 1024 * 1024;
 constexpr int kIterations = 400;
 constexpr int kNoiseThreads = 3;
 
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+enum LaneTestEvent {
+    kLaneQueueAdmitted = 1,
+    kLaneQueueRejected = 2,
+    kLaneConnecting = 3,
+    kLaneBusy = 4,
+    kLaneTerminal = 5,
+    kLaneShutdownClean = 6,
+    kLaneLateHandler = 7,
+    kLaneRetryArmed = 8,
+    kLaneRetryFired = 9,
+    kLaneRetryLate = 10,
+    kLaneCooldownStarted = 11,
+    kLaneAdmissionPending = 12,
+    kLaneAdmissionPromoted = 13,
+    kLaneAdmissionTimerArmed = 14,
+    kLaneAdmissionTimerFired = 15,
+    kLaneAdmissionTimerLate = 16,
+    kLaneAdmissionHardRejected = 17,
+};
+
+enum WorkFailureReasonForTest {
+    kWorkQueueFull = 0,
+    kWorkQueueTimeout = 1,
+    kWorkRuntimeUnavailable = 2,
+    kWorkConnectFailed = 3,
+    kWorkSessionFailed = 4,
+    kWorkShutdown = 5,
+};
+
+enum SessionProgressTestEvent {
+    kSessionReadBodySuccess = 1,
+    kSessionWriteAckSuccess = 2,
+    kSessionTimeoutCommitted = 3,
+    kSessionTimeoutStale = 4,
+    kSessionTerminal = 5,
+};
+
+enum SessionProgressTestAction {
+    kSessionProgressNoAction = 0,
+    kSessionCommitTimeoutBeforeProgress = 1,
+    kSessionReplayPreviousTimeoutAfterProgress = 2,
+};
+
+std::atomic<bool> lane_connect_handler_entered{false};
+std::atomic<int> lane_connect_injection_call_count{0};
+std::atomic<bool> release_lane_connect_handler{false};
+std::atomic<bool> hold_lane_connect_handler{false};
+std::atomic<bool> hold_lane_connect_after_busy{false};
+std::atomic<bool> connecting_lane_had_current{false};
+std::atomic<bool> retry_handler_entered{false};
+std::atomic<bool> release_retry_handler{false};
+std::atomic<bool> hold_retry_handler{false};
+std::atomic<bool> retry_armed_observer_entered{false};
+std::atomic<bool> release_retry_armed_observer{false};
+std::atomic<bool> hold_retry_armed_observer{false};
+std::atomic<bool> admission_handler_entered{false};
+std::atomic<bool> release_admission_handler{false};
+std::atomic<bool> hold_admission_handler{false};
+std::atomic<size_t> maximum_observed_queue_depth{0};
+std::atomic<size_t> maximum_observed_pending_depth{0};
+std::atomic<size_t> maximum_observed_socket_count{0};
+std::atomic<int> queue_rejection_count{0};
+std::atomic<int> lane_connecting_count{0};
+std::atomic<int> lane_busy_count{0};
+std::atomic<int> lane_terminal_count{0};
+std::atomic<size_t> lane_terminal_socket_count{0};
+std::atomic<int> lane_shutdown_clean_count{0};
+std::atomic<int> late_lane_handler_count{0};
+std::atomic<int> retry_armed_count{0};
+std::atomic<int> retry_fired_count{0};
+std::atomic<int> retry_late_count{0};
+std::atomic<int> cooldown_started_count{0};
+std::atomic<int> admission_pending_count{0};
+std::atomic<int> admission_promoted_count{0};
+std::atomic<int> admission_timer_armed_count{0};
+std::atomic<int> admission_timer_fired_count{0};
+std::atomic<int> admission_timer_late_count{0};
+std::atomic<int> admission_hard_rejection_count{0};
+std::atomic<int> queue_full_failure_count{0};
+std::atomic<int> queue_timeout_failure_count{0};
+std::atomic<int> connect_failure_count{0};
+std::atomic<int> runtime_unavailable_failure_count{0};
+std::atomic<int> session_failure_count{0};
+std::atomic<int> shutdown_failure_count{0};
+std::atomic<int> session_progress_target_event{0};
+std::atomic<int> session_progress_action{0};
+std::atomic<int> session_timeout_committed_count{0};
+std::atomic<int> session_timeout_stale_count{0};
+std::atomic<int> session_terminal_count{0};
+std::atomic<int> session_dirty_terminal_count{0};
+std::atomic<bool> session_timeout_commit_entered{false};
+std::atomic<bool> session_timeout_commit_had_write_in_flight{false};
+std::atomic<bool> hold_session_timeout_commit{false};
+std::atomic<bool> release_session_timeout_commit{false};
+std::atomic<bool> start_transfer_metadata_hook_entered{false};
+std::atomic<bool> release_start_transfer_metadata_hook{false};
+
+template <typename Predicate, typename Rep, typename Period>
+bool waitForPredicate(Predicate&& predicate,
+                      std::chrono::duration<Rep, Period> timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (predicate()) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+    return predicate();
+}
+
+template <typename T>
+void updateMaximum(std::atomic<T>& value, T candidate) noexcept {
+    T previous = value.load(std::memory_order_relaxed);
+    while (previous < candidate &&
+           !value.compare_exchange_weak(previous, candidate,
+                                        std::memory_order_relaxed)) {
+    }
+}
+
+void resetLaneTestState() noexcept {
+    lane_connect_handler_entered.store(false, std::memory_order_release);
+    lane_connect_injection_call_count.store(0, std::memory_order_release);
+    release_lane_connect_handler.store(false, std::memory_order_release);
+    hold_lane_connect_handler.store(false, std::memory_order_release);
+    hold_lane_connect_after_busy.store(false, std::memory_order_release);
+    connecting_lane_had_current.store(false, std::memory_order_release);
+    retry_handler_entered.store(false, std::memory_order_release);
+    release_retry_handler.store(false, std::memory_order_release);
+    hold_retry_handler.store(false, std::memory_order_release);
+    retry_armed_observer_entered.store(false, std::memory_order_release);
+    release_retry_armed_observer.store(false, std::memory_order_release);
+    hold_retry_armed_observer.store(false, std::memory_order_release);
+    admission_handler_entered.store(false, std::memory_order_release);
+    release_admission_handler.store(false, std::memory_order_release);
+    hold_admission_handler.store(false, std::memory_order_release);
+    maximum_observed_queue_depth.store(0, std::memory_order_release);
+    maximum_observed_pending_depth.store(0, std::memory_order_release);
+    maximum_observed_socket_count.store(0, std::memory_order_release);
+    queue_rejection_count.store(0, std::memory_order_release);
+    lane_connecting_count.store(0, std::memory_order_release);
+    lane_busy_count.store(0, std::memory_order_release);
+    lane_terminal_count.store(0, std::memory_order_release);
+    lane_terminal_socket_count.store(0, std::memory_order_release);
+    lane_shutdown_clean_count.store(0, std::memory_order_release);
+    late_lane_handler_count.store(0, std::memory_order_release);
+    retry_armed_count.store(0, std::memory_order_release);
+    retry_fired_count.store(0, std::memory_order_release);
+    retry_late_count.store(0, std::memory_order_release);
+    cooldown_started_count.store(0, std::memory_order_release);
+    admission_pending_count.store(0, std::memory_order_release);
+    admission_promoted_count.store(0, std::memory_order_release);
+    admission_timer_armed_count.store(0, std::memory_order_release);
+    admission_timer_fired_count.store(0, std::memory_order_release);
+    admission_timer_late_count.store(0, std::memory_order_release);
+    admission_hard_rejection_count.store(0, std::memory_order_release);
+    queue_full_failure_count.store(0, std::memory_order_release);
+    queue_timeout_failure_count.store(0, std::memory_order_release);
+    connect_failure_count.store(0, std::memory_order_release);
+    runtime_unavailable_failure_count.store(0, std::memory_order_release);
+    session_failure_count.store(0, std::memory_order_release);
+    shutdown_failure_count.store(0, std::memory_order_release);
+}
+
+void resetSessionProgressTestState() noexcept {
+    session_progress_target_event.store(0, std::memory_order_release);
+    session_progress_action.store(0, std::memory_order_release);
+    session_timeout_committed_count.store(0, std::memory_order_release);
+    session_timeout_stale_count.store(0, std::memory_order_release);
+    session_terminal_count.store(0, std::memory_order_release);
+    session_dirty_terminal_count.store(0, std::memory_order_release);
+    session_timeout_commit_entered.store(false, std::memory_order_release);
+    session_timeout_commit_had_write_in_flight.store(false,
+                                                     std::memory_order_release);
+    hold_session_timeout_commit.store(false, std::memory_order_release);
+    release_session_timeout_commit.store(false, std::memory_order_release);
+}
+
+bool failSecondLaneConnectAttemptOnce(size_t) noexcept {
+    const int attempt = lane_connect_injection_call_count.fetch_add(1) + 1;
+    return attempt == 2;
+}
+
+bool failLaneOneAndTwoConnectAttempt(size_t lane_id) noexcept {
+    lane_connect_injection_call_count.fetch_add(1, std::memory_order_relaxed);
+    return lane_id == 1 || lane_id == 2;
+}
+
+void releaseLaneConnectHandler() noexcept {
+    release_lane_connect_handler.store(true, std::memory_order_release);
+}
+
+void blockLaneConnectHandler() noexcept {
+    if (!hold_lane_connect_handler.load(std::memory_order_acquire)) return;
+    lane_connect_handler_entered.store(true, std::memory_order_release);
+    while (!release_lane_connect_handler.load(std::memory_order_acquire)) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
+void releaseRetryHandler() noexcept {
+    release_retry_handler.store(true, std::memory_order_release);
+}
+
+void blockRetryHandler() noexcept {
+    if (!hold_retry_handler.load(std::memory_order_acquire)) return;
+    retry_handler_entered.store(true, std::memory_order_release);
+    while (!release_retry_handler.load(std::memory_order_acquire)) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
+void releaseRetryArmedObserver() noexcept {
+    release_retry_armed_observer.store(true, std::memory_order_release);
+}
+
+void releaseAdmissionHandler() noexcept {
+    release_admission_handler.store(true, std::memory_order_release);
+}
+
+void blockAdmissionHandler() noexcept {
+    if (!hold_admission_handler.load(std::memory_order_acquire)) return;
+    admission_handler_entered.store(true, std::memory_order_release);
+    while (!release_admission_handler.load(std::memory_order_acquire)) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
+void observeLaneState(int event, size_t queue_depth, uint64_t,
+                      size_t active_sockets, bool lane_has_current) noexcept {
+    if (event < kLaneAdmissionPending || event > kLaneAdmissionHardRejected)
+        updateMaximum(maximum_observed_queue_depth, queue_depth);
+    updateMaximum(maximum_observed_socket_count, active_sockets);
+    if (event == kLaneConnecting && lane_has_current)
+        connecting_lane_had_current.store(true, std::memory_order_release);
+    if (event == kLaneConnecting)
+        lane_connecting_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneBusy) {
+        lane_busy_count.fetch_add(1, std::memory_order_relaxed);
+        if (hold_lane_connect_after_busy.load(std::memory_order_acquire))
+            hold_lane_connect_handler.store(true, std::memory_order_release);
+    }
+    if (event == kLaneQueueRejected)
+        queue_rejection_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneTerminal) {
+        lane_terminal_count.fetch_add(1, std::memory_order_relaxed);
+        lane_terminal_socket_count.store(active_sockets,
+                                         std::memory_order_release);
+    }
+    if (event == kLaneShutdownClean)
+        lane_shutdown_clean_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneLateHandler)
+        late_lane_handler_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneRetryArmed) {
+        retry_armed_count.fetch_add(1, std::memory_order_relaxed);
+        if (hold_retry_armed_observer.load(std::memory_order_acquire)) {
+            retry_armed_observer_entered.store(true, std::memory_order_release);
+            while (
+                !release_retry_armed_observer.load(std::memory_order_acquire)) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            }
+        }
+    }
+    if (event == kLaneRetryFired)
+        retry_fired_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneRetryLate)
+        retry_late_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneCooldownStarted)
+        cooldown_started_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneAdmissionPending) {
+        admission_pending_count.fetch_add(1, std::memory_order_relaxed);
+        updateMaximum(maximum_observed_pending_depth, queue_depth);
+    }
+    if (event == kLaneAdmissionPromoted) {
+        admission_promoted_count.fetch_add(1, std::memory_order_relaxed);
+        updateMaximum(maximum_observed_pending_depth, queue_depth);
+    }
+    if (event == kLaneAdmissionTimerArmed)
+        admission_timer_armed_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneAdmissionTimerFired)
+        admission_timer_fired_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneAdmissionTimerLate)
+        admission_timer_late_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kLaneAdmissionHardRejected)
+        admission_hard_rejection_count.fetch_add(1, std::memory_order_relaxed);
+}
+
+void observeWorkFailureReason(int reason) noexcept {
+    if (reason == kWorkQueueFull)
+        queue_full_failure_count.fetch_add(1, std::memory_order_relaxed);
+    if (reason == kWorkQueueTimeout)
+        queue_timeout_failure_count.fetch_add(1, std::memory_order_relaxed);
+    if (reason == kWorkConnectFailed)
+        connect_failure_count.fetch_add(1, std::memory_order_relaxed);
+    if (reason == kWorkRuntimeUnavailable)
+        runtime_unavailable_failure_count.fetch_add(1,
+                                                    std::memory_order_relaxed);
+    if (reason == kWorkSessionFailed)
+        session_failure_count.fetch_add(1, std::memory_order_relaxed);
+    if (reason == kWorkShutdown)
+        shutdown_failure_count.fetch_add(1, std::memory_order_relaxed);
+}
+
+int observeSessionProgress(int event, bool detail) noexcept {
+    if (event == kSessionTimeoutCommitted) {
+        session_timeout_committed_count.fetch_add(1, std::memory_order_relaxed);
+        session_timeout_commit_had_write_in_flight.store(
+            detail, std::memory_order_release);
+        if (hold_session_timeout_commit.load(std::memory_order_acquire)) {
+            session_timeout_commit_entered.store(true,
+                                                 std::memory_order_release);
+            while (!release_session_timeout_commit.load(
+                std::memory_order_acquire)) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            }
+        }
+    }
+    if (event == kSessionTimeoutStale)
+        session_timeout_stale_count.fetch_add(1, std::memory_order_relaxed);
+    if (event == kSessionTerminal) {
+        session_terminal_count.fetch_add(1, std::memory_order_relaxed);
+        if (!detail)
+            session_dirty_terminal_count.fetch_add(1,
+                                                   std::memory_order_relaxed);
+    }
+    if (event !=
+        session_progress_target_event.load(std::memory_order_acquire)) {
+        return kSessionProgressNoAction;
+    }
+    return session_progress_action.exchange(kSessionProgressNoAction,
+                                            std::memory_order_acq_rel);
+}
+
+void blockStartTransferAfterMetadataLookup() noexcept {
+    start_transfer_metadata_hook_entered.store(true, std::memory_order_release);
+    while (
+        !release_start_transfer_metadata_hook.load(std::memory_order_acquire)) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
+class ScopedStartTransferMetadataHook {
+   public:
+    ScopedStartTransferMetadataHook() {
+        start_transfer_metadata_hook_entered.store(false,
+                                                   std::memory_order_release);
+        release_start_transfer_metadata_hook.store(false,
+                                                   std::memory_order_release);
+        tcpTransportSetStartTransferMetadataHookForTest(
+            blockStartTransferAfterMetadataLookup);
+    }
+
+    ~ScopedStartTransferMetadataHook() { reset(); }
+
+    void release() noexcept {
+        release_start_transfer_metadata_hook.store(true,
+                                                   std::memory_order_release);
+    }
+
+    void reset() noexcept {
+        if (!active_) return;
+        release();
+        tcpTransportSetStartTransferMetadataHookForTest(nullptr);
+        active_ = false;
+    }
+
+   private:
+    bool active_ = true;
+};
+
+class ScopedLaneHooks {
+   public:
+    explicit ScopedLaneHooks(bool block_first_connect_handler = false,
+                             bool block_after_busy = false,
+                             bool block_retry = false,
+                             bool block_retry_armed = false,
+                             bool block_admission = false,
+                             bool fail_second_connect = false) {
+        resetLaneTestState();
+        tcpTransportSetLaneObserverHookForTest(observeLaneState);
+        tcpTransportSetLaneFailureReasonHookForTest(observeWorkFailureReason);
+        if (fail_second_connect) {
+            tcpTransportSetLaneConnectFailureInjectionHookForTest(
+                failSecondLaneConnectAttemptOnce);
+        }
+        if (block_first_connect_handler || block_after_busy) {
+            hold_lane_connect_handler.store(block_first_connect_handler,
+                                            std::memory_order_release);
+            hold_lane_connect_after_busy.store(block_after_busy,
+                                               std::memory_order_release);
+            tcpTransportSetLaneConnectHandlerHookForTest(
+                blockLaneConnectHandler);
+        }
+        if (block_retry) {
+            hold_retry_handler.store(true, std::memory_order_release);
+            tcpTransportSetLaneRetryHandlerHookForTest(blockRetryHandler);
+        }
+        hold_retry_armed_observer.store(block_retry_armed,
+                                        std::memory_order_release);
+        if (block_admission) {
+            hold_admission_handler.store(true, std::memory_order_release);
+            tcpTransportSetLaneAdmissionHandlerHookForTest(
+                blockAdmissionHandler);
+        }
+    }
+
+    ~ScopedLaneHooks() { reset(); }
+
+    void reset() noexcept {
+        if (!active_) return;
+        releaseLaneConnectHandler();
+        releaseRetryHandler();
+        releaseRetryArmedObserver();
+        releaseAdmissionHandler();
+        tcpTransportSetLaneConnectHandlerHookForTest(nullptr);
+        tcpTransportSetLaneConnectFailureInjectionHookForTest(nullptr);
+        tcpTransportSetLaneRetryHandlerHookForTest(nullptr);
+        tcpTransportSetLaneAdmissionHandlerHookForTest(nullptr);
+        tcpTransportSetLaneObserverHookForTest(nullptr);
+        tcpTransportSetLaneFailureReasonHookForTest(nullptr);
+        active_ = false;
+    }
+
+   private:
+    bool active_ = true;
+};
+
+class ScopedSessionProgressHooks {
+   public:
+    ScopedSessionProgressHooks(int target_event = 0,
+                               int action = kSessionProgressNoAction,
+                               bool block_timeout_commit = false) {
+        resetSessionProgressTestState();
+        session_progress_target_event.store(target_event,
+                                            std::memory_order_release);
+        session_progress_action.store(action, std::memory_order_release);
+        hold_session_timeout_commit.store(block_timeout_commit,
+                                          std::memory_order_release);
+        tcpTransportSetSessionProgressHookForTest(observeSessionProgress);
+    }
+
+    ~ScopedSessionProgressHooks() { reset(); }
+
+    void releaseTimeoutCommit() noexcept {
+        release_session_timeout_commit.store(true, std::memory_order_release);
+    }
+
+    void reset() noexcept {
+        if (!active_) return;
+        releaseTimeoutCommit();
+        tcpTransportSetSessionProgressHookForTest(nullptr);
+        active_ = false;
+    }
+
+   private:
+    bool active_ = true;
+};
+#endif
+
+void reclaimBatchDescAfterEngineShutdownForTest(Transport::BatchID batch_id) {
+#ifndef CONFIG_USE_BATCH_DESC_SET
+    // These shutdown tests deliberately destroy TransferEngine with work still
+    // outstanding, so normal freeBatchID cannot be called. The caller must
+    // wait for engine destruction to return (and thus for its worker to join)
+    // before reclaiming a descriptor that no callback can touch anymore.
+    delete &Transport::toBatchDesc(batch_id);
+#else
+    // The batch descriptor registry owns (and may already reclaim) this object.
+    (void)batch_id;
+#endif
+}
+
 class ScopedEnvVar {
    public:
     ScopedEnvVar(const char* name, const char* value) : name_(name) {
@@ -92,6 +592,223 @@ struct TestSessionHeader {
 static_assert(sizeof(TestSessionHeader) == 24,
               "legacy TCP header ABI changed unexpectedly");
 
+// Small in-process implementation of the HTTP metadata key/value contract.
+// It lets refresh tests update the authoritative store first and then exercise
+// TransferEngine::syncSegmentCache(), rather than mutating the cached
+// SegmentDesc returned by getSegmentDescByID().
+class LocalHttpMetadataServer {
+   public:
+    LocalHttpMetadataServer() {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) return;
+        int one = 1;
+        if (setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one,
+                       sizeof(one)) != 0)
+            return;
+
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&addr),
+                 sizeof(addr)) != 0)
+            return;
+        if (listen(listen_fd_, 16) != 0) return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&addr), &len) !=
+            0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+        thread_ = std::thread([this] { serve(); });
+    }
+
+    ~LocalHttpMetadataServer() {
+        stopped_.store(true, std::memory_order_release);
+        if (listen_fd_ >= 0) (void)shutdown(listen_fd_, SHUT_RDWR);
+        if (thread_.joinable()) thread_.join();
+        if (listen_fd_ >= 0) close(listen_fd_);
+    }
+
+    bool ok() const { return ok_; }
+    std::string uri() const {
+        return "http://127.0.0.1:" + std::to_string(port_) + "/metadata";
+    }
+
+    bool rewriteStoredRpcHost(const std::string& server_name,
+                              const std::string& new_host) {
+        std::lock_guard<std::mutex> lock(values_mutex_);
+        size_t rewritten = 0;
+        for (auto& [key, encoded] : values_) {
+            if (key != "mooncake/rpc_meta/" + server_name) continue;
+            Json::CharReaderBuilder reader_builder;
+            Json::Value value;
+            std::string errors;
+            std::unique_ptr<Json::CharReader> reader(
+                reader_builder.newCharReader());
+            if (!reader->parse(encoded.data(), encoded.data() + encoded.size(),
+                               &value, &errors) ||
+                !value.isMember("ip_or_host_name")) {
+                continue;
+            }
+            value["ip_or_host_name"] = new_host;
+            const int64_t now_ns = getCurrentTimeInNano();
+            uint64_t metadata_version =
+                now_ns > 0 ? static_cast<uint64_t>(now_ns / 1000) : 1;
+            if (value.isMember("metadata_version") &&
+                value["metadata_version"].isUInt64() &&
+                value["metadata_version"].asUInt64() >= metadata_version) {
+                metadata_version = value["metadata_version"].asUInt64() + 1;
+            }
+            value["metadata_version"] =
+                static_cast<Json::UInt64>(metadata_version);
+            Json::StreamWriterBuilder writer_builder;
+            writer_builder["indentation"] = "";
+            encoded = Json::writeString(writer_builder, value);
+            ++rewritten;
+        }
+        return rewritten == 1;
+    }
+
+   private:
+    static std::string decodeUrlComponent(const std::string& value) {
+        auto hexDigit = [](char c) -> int {
+            if (c >= '0' && c <= '9') return c - '0';
+            if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+            if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+            return -1;
+        };
+        std::string decoded;
+        decoded.reserve(value.size());
+        for (size_t i = 0; i < value.size(); ++i) {
+            if (value[i] == '%' && i + 2 < value.size()) {
+                const int high = hexDigit(value[i + 1]);
+                const int low = hexDigit(value[i + 2]);
+                if (high >= 0 && low >= 0) {
+                    decoded.push_back(static_cast<char>((high << 4) | low));
+                    i += 2;
+                    continue;
+                }
+            }
+            decoded.push_back(value[i] == '+' ? ' ' : value[i]);
+        }
+        return decoded;
+    }
+
+    static bool sendExact(int fd, const std::string& value) {
+        size_t offset = 0;
+        while (offset < value.size()) {
+            const ssize_t n = send(fd, value.data() + offset,
+                                   value.size() - offset, MSG_NOSIGNAL);
+            if (n <= 0) return false;
+            offset += static_cast<size_t>(n);
+        }
+        return true;
+    }
+
+    static bool readRequest(int fd, std::string& request) {
+        constexpr size_t kMaximumRequestSize = 1 << 20;
+        char buffer[4096];
+        size_t header_end = std::string::npos;
+        while ((header_end = request.find("\r\n\r\n")) == std::string::npos) {
+            const ssize_t n = recv(fd, buffer, sizeof(buffer), 0);
+            if (n <= 0) return false;
+            request.append(buffer, static_cast<size_t>(n));
+            if (request.size() > kMaximumRequestSize) return false;
+        }
+
+        size_t content_length = 0;
+        std::istringstream headers(request.substr(0, header_end));
+        std::string line;
+        std::getline(headers, line);
+        while (std::getline(headers, line)) {
+            if (!line.empty() && line.back() == '\r') line.pop_back();
+            std::string lower = line;
+            std::transform(lower.begin(), lower.end(), lower.begin(),
+                           [](unsigned char c) { return std::tolower(c); });
+            constexpr char kContentLength[] = "content-length:";
+            if (lower.rfind(kContentLength, 0) == 0) {
+                content_length =
+                    std::stoull(line.substr(sizeof(kContentLength) - 1));
+            }
+        }
+
+        const size_t complete_size = header_end + 4 + content_length;
+        while (request.size() < complete_size) {
+            const ssize_t n = recv(fd, buffer, sizeof(buffer), 0);
+            if (n <= 0) return false;
+            request.append(buffer, static_cast<size_t>(n));
+            if (request.size() > kMaximumRequestSize) return false;
+        }
+        return true;
+    }
+
+    void handle(int fd) {
+        std::string request;
+        if (!readRequest(fd, request)) return;
+
+        const size_t request_line_end = request.find("\r\n");
+        if (request_line_end == std::string::npos) return;
+        std::istringstream request_line(request.substr(0, request_line_end));
+        std::string method;
+        std::string target;
+        std::string version;
+        request_line >> method >> target >> version;
+        (void)version;
+        const size_t key_pos = target.find("?key=");
+        if (key_pos == std::string::npos) return;
+        const std::string key = decodeUrlComponent(target.substr(key_pos + 5));
+
+        std::string body = "{}";
+        int status = 200;
+        if (method == "PUT") {
+            const size_t header_end = request.find("\r\n\r\n");
+            const std::string value = request.substr(header_end + 4);
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            values_[key] = value;
+        } else if (method == "GET") {
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            auto it = values_.find(key);
+            if (it == values_.end()) {
+                status = 404;
+            } else {
+                body = it->second;
+            }
+        } else if (method == "DELETE") {
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            values_.erase(key);
+        } else {
+            status = 405;
+        }
+
+        const std::string response =
+            "HTTP/1.1 " + std::to_string(status) +
+            (status == 200 ? " OK\r\n" : " Error\r\n") +
+            "Content-Type: application/json\r\nContent-Length: " +
+            std::to_string(body.size()) + "\r\nConnection: close\r\n\r\n" +
+            body;
+        (void)sendExact(fd, response);
+    }
+
+    void serve() {
+        while (!stopped_.load(std::memory_order_acquire)) {
+            const int fd = accept(listen_fd_, nullptr, nullptr);
+            if (fd < 0) break;
+            handle(fd);
+            close(fd);
+        }
+    }
+
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+    std::thread thread_;
+    std::atomic<bool> stopped_{false};
+    std::mutex values_mutex_;
+    std::unordered_map<std::string, std::string> values_;
+};
+
 // Minimal legacy-server behavior for a flagged WRITE: v1 does not recognize
 // opcode 0x81 as WRITE, so it treats the request as READ and streams payload
 // bytes without consuming the initiator's body. A sequential v2 client then
@@ -209,430 +926,3268 @@ class LegacyReadServer {
     std::atomic<bool> saw_flagged_write_{false};
 };
 
-struct EngineHandle {
-    std::unique_ptr<TransferEngine> engine;
-    void* pool = nullptr;
+// Accepts TCP connections but deliberately never reads request headers or
+// bodies. Large writes therefore remain in progress until closePeer() drops
+// the accepted sockets.
+class HoldingWriteServer {
+   public:
+    HoldingWriteServer() {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) return;
+        int one = 1;
+        if (setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one,
+                       sizeof(one)) != 0)
+            return;
 
-    ~EngineHandle() {
-        engine.reset();  // unregisters memory before the pool goes away
-        free(pool);
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        addr.sin_addr.s_addr = htonl(INADDR_ANY);
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&addr),
+                 sizeof(addr)) != 0)
+            return;
+        if (listen(listen_fd_, 64) != 0) return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&addr), &len) !=
+            0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+        thread_ = std::thread([this] { acceptLoop(); });
     }
-    Transport::SegmentID segment_id = 0;
-    uint64_t remote_base = 0;
-    bool ok = false;  // ASSERT_* in a helper only aborts the helper
 
-    void init(const std::string& metadata_server,
-              const std::string& server_name, size_t pool_size) {
-        // Exercise the pooled-connection path (default off): connection
-        // reuse vs. discard-on-unclean-exchange is part of the contract
-        // under test.
-        setenv("MC_TCP_ENABLE_CONNECTION_POOL", "1", 1);
-        engine = std::make_unique<TransferEngine>(false);
-        auto hp = parseHostNameWithPort(server_name);
-        int rc = engine->init(metadata_server, server_name, hp.first.c_str(),
-                              hp.second);
-        ASSERT_EQ(rc, 0);
-        ASSERT_NE(engine->installTransport("tcp", nullptr), nullptr);
-        pool = malloc(pool_size);
-        ASSERT_NE(pool, nullptr);
-        memset(pool, 0, pool_size);
-        rc = engine->registerLocalMemory(pool, pool_size, "cpu:0");
-        ASSERT_EQ(rc, 0);
-        // The descriptor is fetchable under the name it was registered
-        // with: in P2P-handshake mode the RPC port is auto-assigned, so
-        // that is the engine-reported ip:port; against a real metadata
-        // service (CI runs one at http://...) it is the requested
-        // server_name, matching how production callers open segments.
-        std::string segment_name = (metadata_server == P2PHANDSHAKE)
-                                       ? engine->getLocalIpAndPort()
-                                       : server_name;
-        segment_id = engine->openSegment(segment_name);
-        auto desc = engine->getMetadata()->getSegmentDescByID(segment_id);
-        ASSERT_NE(desc, nullptr);
-        remote_base = (uint64_t)desc->buffers[0].addr;
-        ok = true;
+    ~HoldingWriteServer() {
+        closePeer();
+        if (listen_fd_ >= 0) close(listen_fd_);
     }
-};
 
-// Submit one request and poll until terminal state; returns final status.
-TransferStatusEnum runOne(TransferEngine* engine, TransferRequest entry) {
-    auto batch_id = engine->allocateBatchID(1);
-    Status s = engine->submitTransfer(batch_id, {entry});
-    if (!s.ok()) return TransferStatusEnum::FAILED;
-    TransferStatus status;
-    status.s = TransferStatusEnum::WAITING;
-    auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(15);
-    while (status.s != TransferStatusEnum::COMPLETED &&
-           status.s != TransferStatusEnum::FAILED) {
-        if (std::chrono::steady_clock::now() >= deadline)
-            return TransferStatusEnum::TIMEOUT;
-        s = engine->getTransferStatus(batch_id, 0, status);
-        if (!s.ok()) return TransferStatusEnum::FAILED;
-        std::this_thread::yield();
+    bool ok() const { return ok_; }
+    uint16_t port() const { return port_; }
+    int acceptedCount() const { return accepted_count_.load(); }
+    int maxAcceptedCount() const { return max_accepted_count_.load(); }
+
+    bool waitForAccepted(int count, std::chrono::seconds timeout) const {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (acceptedCount() < count &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        return acceptedCount() >= count;
     }
-    (void)engine->freeBatchID(batch_id);
-    return status.s;
-}
 
-}  // namespace
+    int activeAcceptedCount() const {
+        std::lock_guard<std::mutex> lock(accepted_mutex_);
+        return static_cast<int>(accepted_fds_.size());
+    }
 
-TEST(TcpWriteVisibilityTest, CompletedWriteIsVisibleToSubsequentRead) {
+    bool closeOneAccepted() {
+        int fd = -1;
+        {
+            std::lock_guard<std::mutex> lock(accepted_mutex_);
+            if (accepted_fds_.empty()) return false;
+            fd = accepted_fds_.front();
+            accepted_fds_.erase(accepted_fds_.begin());
+        }
+        (void)shutdown(fd, SHUT_RDWR);
+        close(fd);
+        return true;
+    }
+
+    void closePeer() {
+        if (closed_.exchange(true)) return;
+        if (listen_fd_ >= 0) (void)shutdown(listen_fd_, SHUT_RDWR);
+        if (thread_.joinable()) thread_.join();
+
+        std::vector<int> accepted;
+        {
+            std::lock_guard<std::mutex> lock(accepted_mutex_);
+            accepted.swap(accepted_fds_);
+        }
+        for (int fd : accepted) {
+            (void)shutdown(fd, SHUT_RDWR);
+            close(fd);
+        }
+    }
+
+   private:
+    void acceptLoop() {
+        while (!closed_.load()) {
+            int fd = accept(listen_fd_, nullptr, nullptr);
+            if (fd < 0) break;
+            if (closed_.load()) {
+                close(fd);
+                break;
+            }
+
+            {
+                std::lock_guard<std::mutex> lock(accepted_mutex_);
+                accepted_fds_.push_back(fd);
+            }
+            const int count = accepted_count_.fetch_add(1) + 1;
+            int previous_max = max_accepted_count_.load();
+            while (previous_max < count &&
+                   !max_accepted_count_.compare_exchange_weak(previous_max,
+                                                              count)) {
+            }
+        }
+    }
+
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+    std::thread thread_;
+    mutable std::mutex accepted_mutex_;
+    std::vector<int> accepted_fds_;
+    std::atomic<bool> closed_{false};
+    std::atomic<int> accepted_count_{0};
+    std::atomic<int> max_accepted_count_{0};
+};
+
+// Reads a complete request header and optionally a fixed prefix of the WRITE
+// payload, then stops consuming. The receive window is kept deliberately
+// small so a large request cannot finish in the initiator's kernel buffers.
+// Condition variables expose protocol events; wall-clock time is used only by
+// the test's bounded no-progress watchdog.
+class PayloadStallingWriteServer {
+   public:
+    explicit PayloadStallingWriteServer(size_t payload_prefix_to_read)
+        : payload_prefix_to_read_(payload_prefix_to_read) {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) return;
+        int one = 1;
+        if (setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one,
+                       sizeof(one)) != 0)
+            return;
+
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        addr.sin_addr.s_addr = htonl(INADDR_ANY);
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&addr),
+                 sizeof(addr)) != 0)
+            return;
+        if (listen(listen_fd_, 1) != 0) return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&addr), &len) !=
+            0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+        thread_ = std::thread([this] { serve(); });
+    }
+
+    ~PayloadStallingWriteServer() { release(); }
+
+    bool ok() const { return ok_; }
+    uint16_t port() const { return port_; }
+
+    bool waitForHeader(std::chrono::seconds timeout) {
+        std::unique_lock<std::mutex> lock(event_mutex_);
+        return event_cv_.wait_for(lock, timeout,
+                                  [this] { return header_received_; });
+    }
+
+    bool waitForPayloadPrefix(std::chrono::seconds timeout) {
+        std::unique_lock<std::mutex> lock(event_mutex_);
+        return event_cv_.wait_for(lock, timeout,
+                                  [this] { return payload_prefix_received_; });
+    }
+
+    void release() {
+        {
+            std::lock_guard<std::mutex> lock(event_mutex_);
+            released_ = true;
+        }
+        event_cv_.notify_all();
+        if (listen_fd_ >= 0) (void)shutdown(listen_fd_, SHUT_RDWR);
+        int accepted = -1;
+        {
+            std::lock_guard<std::mutex> lock(socket_mutex_);
+            accepted = accepted_fd_;
+        }
+        if (accepted >= 0) (void)shutdown(accepted, SHUT_RDWR);
+        if (thread_.joinable()) thread_.join();
+        if (accepted >= 0) close(accepted);
+        {
+            std::lock_guard<std::mutex> lock(socket_mutex_);
+            accepted_fd_ = -1;
+        }
+        if (listen_fd_ >= 0) {
+            close(listen_fd_);
+            listen_fd_ = -1;
+        }
+    }
+
+   private:
+    static bool recvExact(int fd, void* buffer, size_t size) {
+        char* out = static_cast<char*>(buffer);
+        while (size) {
+            const ssize_t n = recv(fd, out, size, 0);
+            if (n <= 0) return false;
+            out += n;
+            size -= static_cast<size_t>(n);
+        }
+        return true;
+    }
+
+    void serve() {
+        const int fd = accept(listen_fd_, nullptr, nullptr);
+        if (fd < 0) return;
+        {
+            std::lock_guard<std::mutex> lock(socket_mutex_);
+            accepted_fd_ = fd;
+        }
+        int receive_buffer = 4096;
+        if (payload_prefix_to_read_ == 0) {
+            (void)setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &receive_buffer,
+                             sizeof(receive_buffer));
+        }
+
+        TestSessionHeader header{};
+        if (!recvExact(fd, &header, sizeof(header))) return;
+        {
+            std::lock_guard<std::mutex> lock(event_mutex_);
+            header_received_ = true;
+        }
+        event_cv_.notify_all();
+
+        const size_t prefix =
+            std::min<uint64_t>(payload_prefix_to_read_, le64toh(header.size));
+        std::vector<char> payload(prefix);
+        if (prefix != 0 && !recvExact(fd, payload.data(), prefix)) return;
+        if (prefix != 0) {
+            (void)setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &receive_buffer,
+                             sizeof(receive_buffer));
+        }
+        {
+            std::lock_guard<std::mutex> lock(event_mutex_);
+            payload_prefix_received_ = true;
+        }
+        event_cv_.notify_all();
+
+        std::unique_lock<std::mutex> lock(event_mutex_);
+        event_cv_.wait(lock, [this] { return released_; });
+    }
+
+    const size_t payload_prefix_to_read_;
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+    std::thread thread_;
+    std::mutex socket_mutex_;
+    int accepted_fd_ = -1;
+    std::mutex event_mutex_;
+    std::condition_variable event_cv_;
+    bool header_received_ = false;
+    bool payload_prefix_received_ = false;
+    bool released_ = false;
+};
+
+// Keeps a local TCP port bound but deliberately never listens. Linux rejects
+// connect attempts deterministically, without blackhole-address timing.
+class UnavailableTcpPeer {
+   public:
+    UnavailableTcpPeer() {
+        fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (fd_ < 0) return;
+
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        addr.sin_addr.s_addr = htonl(INADDR_ANY);
+        if (bind(fd_, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) != 0)
+            return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(fd_, reinterpret_cast<sockaddr*>(&addr), &len) != 0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+    }
+
+    ~UnavailableTcpPeer() {
+        if (fd_ >= 0) close(fd_);
+    }
+
+    bool ok() const { return ok_; }
+    uint16_t port() const { return port_; }
+
+   private:
+    int fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+};
+
+// Minimal v2 WRITE server that keeps accepted connections open and processes
+// multiple request/ack exchanges on each one.
+class ReusingWriteServer {
+   public:
+    explicit ReusingWriteServer(bool hold_first_ack = false,
+                                const char* bind_address = nullptr)
+        : hold_first_ack_(hold_first_ack) {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) return;
+        int one = 1;
+        if (setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one,
+                       sizeof(one)) != 0)
+            return;
+
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        if (bind_address) {
+            if (inet_pton(AF_INET, bind_address, &addr.sin_addr) != 1) return;
+        } else {
+            addr.sin_addr.s_addr = htonl(INADDR_ANY);
+        }
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&addr),
+                 sizeof(addr)) != 0)
+            return;
+        if (listen(listen_fd_, 16) != 0) return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&addr), &len) !=
+            0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+        accept_thread_ = std::thread([this] { acceptLoop(); });
+    }
+
+    ~ReusingWriteServer() { stop(); }
+
+    bool ok() const { return ok_; }
+    uint16_t port() const { return port_; }
+    int acceptedCount() const { return accepted_count_.load(); }
+    int activeAcceptedCount() const {
+        std::lock_guard<std::mutex> lock(connection_mutex_);
+        return static_cast<int>(accepted_fds_.size());
+    }
+    bool waitForNoActiveConnections(std::chrono::milliseconds timeout) const {
+        std::unique_lock<std::mutex> lock(connection_mutex_);
+        return connection_cv_.wait_for(
+            lock, timeout, [this] { return accepted_fds_.empty(); });
+    }
+
+    bool waitForRequests(int count, std::chrono::seconds timeout) const {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (request_count_.load() < count &&
+               std::chrono::steady_clock::now() < deadline) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        return request_count_.load() >= count;
+    }
+
+    bool waitForFirstRequest(std::chrono::seconds timeout) const {
+        return waitForPredicate(
+            [this] {
+                return first_request_received_.load(std::memory_order_acquire);
+            },
+            timeout);
+    }
+
+    void releaseFirstAck() noexcept {
+        release_first_ack_.store(true, std::memory_order_release);
+    }
+
+    bool waitForFirstAckSent(std::chrono::seconds timeout) const {
+        return waitForPredicate(
+            [this] { return first_ack_sent_.load(std::memory_order_acquire); },
+            timeout);
+    }
+
+    std::vector<uint64_t> requestAddresses() const {
+        std::lock_guard<std::mutex> lock(request_mutex_);
+        return request_addresses_;
+    }
+
+   private:
+    static bool recvExact(int fd, void* buffer, size_t size) {
+        char* out = static_cast<char*>(buffer);
+        while (size) {
+            ssize_t n = recv(fd, out, size, 0);
+            if (n <= 0) return false;
+            out += n;
+            size -= static_cast<size_t>(n);
+        }
+        return true;
+    }
+
+    static bool sendExact(int fd, const void* buffer, size_t size) {
+        const char* in = static_cast<const char*>(buffer);
+        while (size) {
+            ssize_t n = send(fd, in, size, MSG_NOSIGNAL);
+            if (n <= 0) return false;
+            in += n;
+            size -= static_cast<size_t>(n);
+        }
+        return true;
+    }
+
+    void acceptLoop() {
+        while (!stopped_.load()) {
+            int fd = accept(listen_fd_, nullptr, nullptr);
+            if (fd < 0) break;
+            if (stopped_.load()) {
+                close(fd);
+                break;
+            }
+            {
+                std::lock_guard<std::mutex> lock(connection_mutex_);
+                accepted_fds_.push_back(fd);
+                connection_threads_.emplace_back(
+                    [this, fd] { serveConnection(fd); });
+            }
+            accepted_count_.fetch_add(1);
+        }
+    }
+
+    void serveConnection(int fd) {
+        std::vector<char> payload(64 * 1024);
+        bool keep_serving = true;
+        while (!stopped_.load()) {
+            TestSessionHeader header{};
+            if (!recvExact(fd, &header, sizeof(header))) break;
+            {
+                std::lock_guard<std::mutex> lock(request_mutex_);
+                request_addresses_.push_back(le64toh(header.addr));
+            }
+            uint64_t remaining = le64toh(header.size);
+            while (remaining) {
+                const size_t chunk =
+                    std::min<uint64_t>(payload.size(), remaining);
+                if (!recvExact(fd, payload.data(), chunk)) {
+                    keep_serving = false;
+                    break;
+                }
+                remaining -= chunk;
+            }
+            if (!keep_serving) break;
+
+            const int request_index =
+                requests_received_.fetch_add(1, std::memory_order_acq_rel);
+            if (hold_first_ack_ && request_index == 0) {
+                first_request_received_.store(true, std::memory_order_release);
+                while (!release_first_ack_.load(std::memory_order_acquire) &&
+                       !stopped_.load(std::memory_order_acquire)) {
+                    std::this_thread::sleep_for(std::chrono::milliseconds(1));
+                }
+            }
+
+            constexpr uint64_t kStatusOk = 0x4D435456ull << 32;
+            const uint64_t status = htole64(kStatusOk);
+            if (!sendExact(fd, &status, sizeof(status))) break;
+            if (hold_first_ack_ && request_index == 0)
+                first_ack_sent_.store(true, std::memory_order_release);
+            request_count_.fetch_add(1);
+        }
+        {
+            std::lock_guard<std::mutex> lock(connection_mutex_);
+            auto it = std::find(accepted_fds_.begin(), accepted_fds_.end(), fd);
+            if (it != accepted_fds_.end()) accepted_fds_.erase(it);
+        }
+        connection_cv_.notify_all();
+        close(fd);
+    }
+
+    void stop() {
+        if (stopped_.exchange(true)) return;
+        releaseFirstAck();
+        if (listen_fd_ >= 0) (void)shutdown(listen_fd_, SHUT_RDWR);
+        if (accept_thread_.joinable()) accept_thread_.join();
+
+        {
+            std::lock_guard<std::mutex> lock(connection_mutex_);
+            for (int fd : accepted_fds_) (void)shutdown(fd, SHUT_RDWR);
+        }
+        for (auto& thread : connection_threads_)
+            if (thread.joinable()) thread.join();
+        if (listen_fd_ >= 0) close(listen_fd_);
+    }
+
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+    std::thread accept_thread_;
+    mutable std::mutex connection_mutex_;
+    mutable std::condition_variable connection_cv_;
+    mutable std::mutex request_mutex_;
+    std::vector<int> accepted_fds_;
+    std::vector<std::thread> connection_threads_;
+    std::vector<uint64_t> request_addresses_;
+    std::atomic<bool> stopped_{false};
+    std::atomic<int> accepted_count_{0};
+    std::atomic<int> request_count_{0};
+    const bool hold_first_ack_;
+    std::atomic<int> requests_received_{0};
+    std::atomic<bool> first_request_received_{false};
+    std::atomic<bool> release_first_ack_{false};
+    std::atomic<bool> first_ack_sent_{false};
+};
+
+struct EngineHandle {
+    std::unique_ptr<TransferEngine> engine;
+    void* pool = nullptr;
+
+    ~EngineHandle() {
+        engine.reset();  // unregisters memory before the pool goes away
+        free(pool);
+    }
+    Transport::SegmentID segment_id = 0;
+    uint64_t remote_base = 0;
+    bool ok = false;  // ASSERT_* in a helper only aborts the helper
+
+    void init(const std::string& metadata_server,
+              const std::string& server_name, size_t pool_size,
+              const std::string& remote_segment_name = {}) {
+        // Exercise the pooled-connection path (default off): connection
+        // reuse vs. discard-on-unclean-exchange is part of the contract
+        // under test.
+        setenv("MC_TCP_ENABLE_CONNECTION_POOL", "1", 1);
+        engine = std::make_unique<TransferEngine>(false);
+        auto hp = parseHostNameWithPort(server_name);
+        int rc = engine->init(metadata_server, server_name, hp.first.c_str(),
+                              hp.second);
+        ASSERT_EQ(rc, 0);
+        ASSERT_NE(engine->installTransport("tcp", nullptr), nullptr);
+        pool = malloc(pool_size);
+        ASSERT_NE(pool, nullptr);
+        memset(pool, 0, pool_size);
+        rc = engine->registerLocalMemory(pool, pool_size, "cpu:0");
+        ASSERT_EQ(rc, 0);
+        // The descriptor is fetchable under the name it was registered
+        // with: in P2P-handshake mode the RPC port is auto-assigned, so
+        // that is the engine-reported ip:port; against a real metadata
+        // service (CI runs one at http://...) it is the requested
+        // server_name, matching how production callers open segments.
+        std::string segment_name = remote_segment_name;
+        if (segment_name.empty()) {
+            segment_name = (metadata_server == P2PHANDSHAKE)
+                               ? engine->getLocalIpAndPort()
+                               : server_name;
+        }
+        segment_id = engine->openSegment(segment_name);
+        auto desc = engine->getMetadata()->getSegmentDescByID(segment_id);
+        ASSERT_NE(desc, nullptr);
+        remote_base = (uint64_t)desc->buffers[0].addr;
+        ok = true;
+    }
+};
+
+void pointTcpSegmentAt(EngineHandle& handle, uint16_t port) {
+    auto desc =
+        handle.engine->getMetadata()->getSegmentDescByID(handle.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = port;
+    desc->tcp_proto_version = 2;
+}
+
+std::string publishAndRefreshTcpEndpoint(EngineHandle& handle,
+                                         Transport::SegmentID segment_id,
+                                         uint16_t port,
+                                         const std::string& host = {}) {
+    auto metadata = handle.engine->getMetadata();
+    auto current = metadata->getSegmentDescByID(segment_id);
+    EXPECT_NE(current, nullptr);
+    if (!current) return {};
+    auto authoritative = *current;
+    if (!host.empty()) authoritative.tcp_data_host = host;
+    authoritative.tcp_data_port = port;
+    authoritative.tcp_proto_version = 2;
+    EXPECT_EQ(metadata->updateSegmentDesc(current->name, authoritative), 0);
+    EXPECT_EQ(handle.engine->syncSegmentCache(current->name), 0);
+    auto refreshed = metadata->getSegmentDescByID(segment_id);
+    EXPECT_NE(refreshed, nullptr);
+    if (refreshed) {
+        if (!host.empty()) {
+            EXPECT_EQ(refreshed->tcp_data_host, host);
+        }
+        EXPECT_EQ(refreshed->tcp_data_port, port);
+    }
+    return current->name;
+}
+
+std::string publishAndRefreshTcpEndpoint(EngineHandle& handle, uint16_t port) {
+    return publishAndRefreshTcpEndpoint(handle, handle.segment_id, port);
+}
+
+TransferRequest makeWriteRequest(const EngineHandle& handle, size_t length,
+                                 uint64_t target_offset = 0) {
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = length;
+    request.source = handle.pool;
+    request.target_id = handle.segment_id;
+    request.target_offset =
+        target_offset == 0 ? handle.remote_base : target_offset;
+    return request;
+}
+
+TransferRequest makeReadRequest(const EngineHandle& handle, void* destination,
+                                size_t length, uint64_t target_offset = 0) {
+    TransferRequest request;
+    request.opcode = TransferRequest::READ;
+    request.length = length;
+    request.source = destination;
+    request.target_id = handle.segment_id;
+    request.target_offset =
+        target_offset == 0 ? handle.remote_base : target_offset;
+    return request;
+}
+
+// Submit one request and poll until terminal state; returns final status.
+TransferStatusEnum runOne(TransferEngine* engine, TransferRequest entry) {
+    auto batch_id = engine->allocateBatchID(1);
+    Status s = engine->submitTransfer(batch_id, {entry});
+    if (!s.ok()) return TransferStatusEnum::FAILED;
+    TransferStatus status;
+    status.s = TransferStatusEnum::WAITING;
+    auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(15);
+    while (status.s != TransferStatusEnum::COMPLETED &&
+           status.s != TransferStatusEnum::FAILED) {
+        if (std::chrono::steady_clock::now() >= deadline)
+            return TransferStatusEnum::TIMEOUT;
+        s = engine->getTransferStatus(batch_id, 0, status);
+        if (!s.ok()) return TransferStatusEnum::FAILED;
+        std::this_thread::yield();
+    }
+    (void)engine->freeBatchID(batch_id);
+    return status.s;
+}
+
+bool waitForBatchTerminal(TransferEngine* engine, Transport::BatchID batch_id,
+                          size_t task_count, std::chrono::seconds timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline) {
+        bool all_terminal = true;
+        for (size_t task_id = 0; task_id < task_count; ++task_id) {
+            TransferStatus status;
+            status.s = TransferStatusEnum::WAITING;
+            if (!engine->getTransferStatus(batch_id, task_id, status).ok() ||
+                (status.s != TransferStatusEnum::COMPLETED &&
+                 status.s != TransferStatusEnum::FAILED)) {
+                all_terminal = false;
+            }
+        }
+        if (all_terminal) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+
+    for (size_t task_id = 0; task_id < task_count; ++task_id) {
+        TransferStatus status;
+        status.s = TransferStatusEnum::WAITING;
+        if (!engine->getTransferStatus(batch_id, task_id, status).ok() ||
+            (status.s != TransferStatusEnum::COMPLETED &&
+             status.s != TransferStatusEnum::FAILED)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+template <typename Rep, typename Period>
+bool waitForTaskTerminal(TransferEngine* engine, Transport::BatchID batch_id,
+                         std::chrono::duration<Rep, Period> timeout,
+                         TransferStatusEnum* final_status = nullptr) {
+    TransferStatus status;
+    status.s = TransferStatusEnum::WAITING;
+    const bool terminal = waitForPredicate(
+        [&] {
+            status.s = TransferStatusEnum::WAITING;
+            if (!engine->getTransferStatus(batch_id, 0, status).ok())
+                return false;
+            return status.s == TransferStatusEnum::COMPLETED ||
+                   status.s == TransferStatusEnum::FAILED;
+        },
+        timeout);
+    if (final_status) *final_status = status.s;
+    return terminal;
+}
+
+void expectEverySliceCompletedExactlyOnce(Transport::BatchID batch_id) {
+    const auto& batch = Transport::toBatchDesc(batch_id);
+    for (size_t task_id = 0; task_id < batch.task_list.size(); ++task_id) {
+        const auto& task = batch.task_list[task_id];
+        const uint64_t success =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_RELAXED);
+        const uint64_t failed =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_RELAXED);
+        const uint64_t slices =
+            __atomic_load_n(&task.slice_count, __ATOMIC_RELAXED);
+        EXPECT_EQ(success + failed, slices) << "task " << task_id;
+        for (const auto* slice : task.slice_list) {
+            EXPECT_TRUE(slice->status == Transport::Slice::SUCCESS ||
+                        slice->status == Transport::Slice::FAILED)
+                << "task " << task_id;
+        }
+    }
+}
+
+void expectEverySliceCompletedExactlyOnceAfterShutdown(
+    Transport::BatchID batch_id) {
+    expectEverySliceCompletedExactlyOnce(batch_id);
+}
+
+void expectEverySliceSucceededExactlyOnceAfterShutdown(
+    Transport::BatchID batch_id) {
+    const auto& batch = Transport::toBatchDesc(batch_id);
+    for (size_t task_id = 0; task_id < batch.task_list.size(); ++task_id) {
+        const auto& task = batch.task_list[task_id];
+        const uint64_t success =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_RELAXED);
+        const uint64_t failed =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_RELAXED);
+        const uint64_t slices =
+            __atomic_load_n(&task.slice_count, __ATOMIC_RELAXED);
+        EXPECT_EQ(success, slices) << "task " << task_id;
+        EXPECT_EQ(failed, 0u) << "task " << task_id;
+        for (const auto* slice : task.slice_list)
+            EXPECT_EQ(slice->status, Transport::Slice::SUCCESS)
+                << "task " << task_id;
+    }
+}
+
+}  // namespace
+
+TEST(TcpWriteVisibilityTest, CompletedWriteIsVisibleToSubsequentRead) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    const char* name_env = std::getenv("MC_LOCAL_SERVER_NAME");
+    std::string server_name = name_env ? name_env : "127.0.0.2:17901";
+
+    const size_t pool_size = 64ull << 20;
+    EngineHandle h;
+    h.init(metadata_server, server_name, pool_size);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    // Region layout inside the registered pool (all offsets from pool base):
+    //   [0, kBigLength)                       : WRITE target region
+    //   [kRegionAlign, +kBigLength)           : local staging for WRITE
+    //   [3*kRegionAlign + t*kRegionAlign, ...): per-noise-thread scratch
+    char* base = (char*)h.pool;
+    char* write_src = base + kRegionAlign;
+
+    std::atomic<bool> stop{false};
+    std::atomic<uint64_t> noise_failures{0};
+    std::vector<std::thread> noise;
+    for (int t = 0; t < kNoiseThreads; ++t) {
+        noise.emplace_back([&, t] {
+            char* src = base + (3 + 2 * t) * kRegionAlign;
+            uint64_t dst_off = (4 + 2 * t) * kRegionAlign;
+            memset(src, 0x5A + t, kSmallLength);
+            while (!stop.load(std::memory_order_relaxed)) {
+                TransferRequest entry;
+                entry.opcode = TransferRequest::WRITE;
+                entry.length = kSmallLength;
+                entry.source = src;
+                entry.target_id = h.segment_id;
+                entry.target_offset = h.remote_base + dst_off;
+                if (runOne(h.engine.get(), entry) !=
+                    TransferStatusEnum::COMPLETED)
+                    noise_failures++;
+            }
+        });
+    }
+
+    uint64_t torn_reads = 0;
+    uint64_t torn_bytes_worst = 0;
+    int first_bad_iter = -1;
+    for (int iter = 1; iter <= kIterations; ++iter) {
+        // Generation-stamped pattern: every byte identifies the iteration.
+        memset(write_src, iter & 0xFF, kBigLength);
+
+        TransferRequest w;
+        w.opcode = TransferRequest::WRITE;
+        w.length = kBigLength;
+        w.source = write_src;
+        w.target_id = h.segment_id;
+        w.target_offset = h.remote_base;  // region at pool offset 0
+        ASSERT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED)
+            << "WRITE failed at iteration " << iter;
+
+        // The WRITE is COMPLETED. The API contract (matching RDMA WRITE
+        // semantics, which disaggregated-serving integrations rely on when
+        // they notify the consumer out-of-band) is that destination memory
+        // is now fully written. Verify by direct local inspection of the
+        // destination region — this is exactly what a decode instance does
+        // after the prefill side signals transfer completion. Scan backwards:
+        // the tail chunks are the ones still in flight when the initiator's
+        // final local send completes.
+        size_t bad = 0;
+        for (size_t i = kBigLength; i-- > 0;) {
+            if ((unsigned char)base[i] != (unsigned char)(iter & 0xFF)) {
+                bad = i + 1;  // bytes [0, i] not yet guaranteed; count prefix
+                break;
+            }
+        }
+        if (bad) {
+            torn_reads++;
+            torn_bytes_worst = std::max<uint64_t>(torn_bytes_worst, bad);
+            if (first_bad_iter < 0) first_bad_iter = iter;
+            // Show it is a visibility delay, not data loss: wait for the
+            // server-side drain to finish before the next iteration so
+            // generations do not overlap.
+            while (memcmp(base, write_src, kBigLength) != 0)
+                std::this_thread::yield();
+        }
+    }
+
+    stop = true;
+    for (auto& t : noise) t.join();
+
+    EXPECT_EQ(torn_reads, 0u)
+        << torn_reads << "/" << kIterations
+        << " reads observed destination bytes not matching the COMPLETED "
+           "write (worst: "
+        << torn_bytes_worst << " stale bytes; first at iteration "
+        << first_bad_iter << "; noise failures: " << noise_failures.load()
+        << ")";
+}
+
+// A server-side rejection must surface as FAILED, not silent success: under
+// v1 framing a single-chunk WRITE to an unregistered address reported
+// COMPLETED because the protocol had no channel for the server to say no.
+TEST(TcpWriteVisibilityTest, RejectedWriteMustFail) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17902", 8ull << 20);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    char* src = (char*)h.pool;
+    memset(src, 0xAB, kSmallLength);
+    TransferRequest w;
+    w.opcode = TransferRequest::WRITE;
+    w.length = kSmallLength;
+    w.source = src;
+    w.target_id = h.segment_id;
+    // One page past the registered pool: the server rejects it in address
+    // validation.
+    w.target_offset = h.remote_base + (8ull << 20) + 4096;
+    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
+
+    // The connection that carried the rejected request must not poison
+    // subsequent transfers.
+    w.target_offset = h.remote_base + kRegionAlign;
+    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+}
+
+// A v2 server rejects an invalid destination immediately after the header,
+// while a large client body is still in flight. FAILED is also the caller's
+// source-buffer lifetime boundary, so it must not be published until closing
+// the socket has quiesced the outstanding async_write.
+TEST(TcpWriteVisibilityTest, LargeRejectedWriteQuiescesSourceBeforeFailure) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17906", 8ull << 20);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    constexpr size_t kLength = 32ull << 20;  // exceed the socket buffers
+    void* source = mmap(nullptr, kLength, PROT_READ | PROT_WRITE,
+                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    ASSERT_NE(source, MAP_FAILED);
+    memset(source, 0x6D, kLength);
+
+    TransferRequest w;
+    w.opcode = TransferRequest::WRITE;
+    w.length = kLength;
+    w.source = source;
+    w.target_id = h.segment_id;
+    w.target_offset = h.remote_base + (8ull << 20) + 4096;
+
+    auto start = std::chrono::steady_clock::now();
+    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
+    EXPECT_LT(std::chrono::steady_clock::now() - start,
+              std::chrono::seconds(3));
+
+    ASSERT_EQ(mprotect(source, kLength, PROT_NONE), 0);
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    ASSERT_EQ(mprotect(source, kLength, PROT_READ | PROT_WRITE), 0);
+    ASSERT_EQ(munmap(source, kLength), 0);
+
+    // The rejected exchange is unclean, so the next request must use a fresh
+    // connection rather than inheriting the server's mid-session state.
+    char* small_source = static_cast<char*>(h.pool);
+    memset(small_source, 0x42, kSmallLength);
+    w.length = kSmallLength;
+    w.source = small_source;
+    w.target_offset = h.remote_base + kRegionAlign;
+    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+}
+
+// v2 READ round-trip: exercises the status-frame-then-data framing in both
+// directions, including content integrity and a rejected READ surfacing as
+// FAILED (v1 could only signal that by dropping the connection).
+TEST(TcpWriteVisibilityTest, V2ReadRoundTripAndRejectedRead) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17904", 16ull << 20);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    char* base = (char*)h.pool;
+    char* src = base + kRegionAlign;
+    char* dst = base + 2 * kRegionAlign;
+    for (size_t i = 0; i < kBigLength; ++i) src[i] = (char)(i * 131 + 7);
+
+    TransferRequest w;
+    w.opcode = TransferRequest::WRITE;
+    w.length = kBigLength;
+    w.source = src;
+    w.target_id = h.segment_id;
+    w.target_offset = h.remote_base;
+    ASSERT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+
+    TransferRequest r;
+    r.opcode = TransferRequest::READ;
+    r.length = kBigLength;
+    r.source = dst;
+    r.target_id = h.segment_id;
+    r.target_offset = h.remote_base;
+    ASSERT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
+    // v2 WRITE completion means the destination was already applied, so the
+    // read-back must match immediately — no drain wait.
+    EXPECT_EQ(memcmp(dst, src, kBigLength), 0);
+
+    // A READ of an unregistered range must fail via the error status frame.
+    r.target_offset = h.remote_base + (16ull << 20) + 4096;
+    EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::FAILED);
+
+    // And the pool must still be usable afterwards.
+    r.target_offset = h.remote_base;
+    EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
+}
+
+TEST(TcpWriteVisibilityTest, GroupedScatterReadWritePreservesEveryFragment) {
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.1:17941", 4ull << 20);
+    ASSERT_TRUE(h.ok);
+    auto descriptor = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    auto* local = static_cast<char*>(h.pool) + (2ull << 20);
+    auto* remote = static_cast<char*>(h.pool);
+    constexpr size_t count = 256;
+    constexpr size_t length = 128;
+    std::vector<size_t> local_offsets(count), remote_offsets(count);
+    std::vector<size_t> lengths(count, length);
+    for (size_t i = 0; i < count; ++i) {
+        local_offsets[i] = i * 256;
+        remote_offsets[i] = i * 384;
+    }
+    for (auto opcode : {TransferRequest::READ, TransferRequest::WRITE}) {
+        memset(local, 0, 1ull << 20);
+        memset(remote, 0, 1ull << 20);
+        for (size_t i = 0; i < count; ++i) {
+            auto* source = opcode == TransferRequest::READ
+                               ? remote + remote_offsets[i]
+                               : local + local_offsets[i];
+            memset(source, static_cast<int>(i % 251 + 1), length);
+        }
+        std::vector<size_t> completions(count);
+        TransferEngine::ScatterTransferRange range{
+            .opcode = opcode,
+            .remote_segment = descriptor->name,
+            .remote_base_offset = h.remote_base,
+            .remote_size = 1ull << 20,
+            .local_buffer = local,
+            .local_capacity = 1ull << 20,
+            .local_offsets = local_offsets,
+            .remote_offsets = remote_offsets,
+            .lengths = lengths,
+            .on_fragment_complete =
+                [&](size_t i, const Status& status) {
+                    EXPECT_TRUE(status.ok());
+                    ++completions[i];
+                },
+        };
+        auto operation = h.engine->submitScatter({range});
+        ASSERT_TRUE(operation.wait().ok());
+        for (size_t i = 0; i < count; ++i) {
+            EXPECT_EQ(completions[i], 1u);
+            EXPECT_EQ(memcmp(local + local_offsets[i],
+                             remote + remote_offsets[i], length),
+                      0);
+            EXPECT_EQ(local[local_offsets[i] + length], 0);
+            EXPECT_EQ(remote[remote_offsets[i] + length], 0);
+        }
+    }
+}
+
+TEST(TcpWriteVisibilityTest, GroupedScatterPreservesPartialFailureResults) {
+    EngineHandle h;
+    constexpr size_t pool_size = 4ull << 20;
+    h.init(P2PHANDSHAKE, "127.0.0.1:17942", pool_size);
+    ASSERT_TRUE(h.ok);
+    auto descriptor = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    auto* local = static_cast<char*>(h.pool) + (2ull << 20);
+    std::vector<size_t> local_offsets{0, 256, 512};
+    // The middle fragment passes the supplied descriptor bounds but is
+    // rejected by the peer's actual registration, exercising transport failure.
+    std::vector<size_t> remote_offsets{0, pool_size + 4096, 512};
+    std::vector<size_t> lengths(3, 128);
+    for (auto opcode : {TransferRequest::READ, TransferRequest::WRITE}) {
+        memset(h.pool, 37, 1024);
+        memset(local, 73, 1024);
+        std::vector<size_t> completions(3);
+        std::vector<bool> succeeded(3);
+        TransferEngine::ScatterTransferRange range{
+            .opcode = opcode,
+            .remote_segment = descriptor->name,
+            .remote_base_offset = h.remote_base,
+            .remote_size = pool_size + 8192,
+            .local_buffer = local,
+            .local_capacity = 1024,
+            .local_offsets = local_offsets,
+            .remote_offsets = remote_offsets,
+            .lengths = lengths,
+            .on_fragment_complete =
+                [&](size_t i, const Status& status) {
+                    ++completions[i];
+                    succeeded[i] = status.ok();
+                },
+        };
+        auto operation = h.engine->submitScatter({range});
+        EXPECT_FALSE(operation.wait().ok());
+        EXPECT_EQ(completions, (std::vector<size_t>{1, 1, 1}));
+        EXPECT_EQ(succeeded, (std::vector<bool>{true, false, true}));
+        EXPECT_EQ(local[256], 73);
+        for (size_t i : {0u, 2u})
+            EXPECT_EQ(memcmp(local + local_offsets[i],
+                             static_cast<char*>(h.pool) + remote_offsets[i],
+                             lengths[i]),
+                      0);
+    }
+}
+
+// Mixed-version quadrant: a pooled legacy (v1) initiator against the current
+// server still transfers data correctly over repeated exchanges on one fixed
+// lane (with the old weaker WRITE completion semantics).
+TEST(TcpWriteVisibilityTest,
+     PooledLegacyInitiatorInteroperatesWithCurrentServer) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    // Set the process environment before the engine starts any threads, and
+    // restore it only after those threads have stopped. POSIX does not require
+    // setenv()/unsetenv() to synchronize with concurrent getenv() calls.
+    ScopedEnvVar pooling("MC_TCP_ENABLE_CONNECTION_POOL", "1");
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "2");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "2");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedEnvVar legacy_proto("MC_TCP_PROTO", "1");
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    ScopedLaneHooks hooks;
+#endif
+    {
+        EngineHandle h;
+        h.init(metadata_server, "127.0.0.2:17903", 16ull << 20);
+        ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+        char* base = (char*)h.pool;
+        char* src = base + kRegionAlign;
+        memset(src, 0x3C, kSmallLength);
+        TransferRequest w;
+        w.opcode = TransferRequest::WRITE;
+        w.length = kSmallLength;
+        w.source = src;
+        w.target_id = h.segment_id;
+        w.target_offset = h.remote_base;
+        EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+
+        // v1 completion does not guarantee destination visibility; wait for
+        // the server drain before checking content.
+        auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(10);
+        while (memcmp(base, src, kSmallLength) != 0 &&
+               std::chrono::steady_clock::now() < deadline)
+            std::this_thread::yield();
+        EXPECT_EQ(memcmp(base, src, kSmallLength), 0);
+
+        // Read-back over the transport under v1 framing.
+        char* dst = base + 2 * kRegionAlign;
+        TransferRequest r;
+        r.opcode = TransferRequest::READ;
+        r.length = kSmallLength;
+        r.source = dst;
+        r.target_id = h.segment_id;
+        r.target_offset = h.remote_base;
+        EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
+        EXPECT_EQ(memcmp(dst, src, kSmallLength), 0);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 1);
+        EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+                  1u);
+#endif
+    }
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    hooks.reset();
+#endif
+}
+
+// A cached v2 descriptor can briefly outlive a server downgrade/restart. A
+// legacy server interprets the flagged WRITE opcode as READ and sends payload
+// while the client sends its body. The concurrent status read must break this
+// full-duplex deadlock, and FAILED must not become visible until asio has
+// released the caller-owned source buffer.
+TEST(TcpWriteVisibilityTest,
+     StaleV2DescriptorAgainstLegacyServerQuiescesWriteBeforeFailure) {
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17905", 8ull << 20);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+
+    LegacyReadServer legacy_server;
+    ASSERT_TRUE(legacy_server.ok());
+    desc->tcp_data_port = legacy_server.port();
+    desc->tcp_proto_version = 2;  // deliberately stale capability advertisement
+
+    constexpr size_t kLength = 32ull << 20;  // exceed both socket buffers
+    void* source = mmap(nullptr, kLength, PROT_READ | PROT_WRITE,
+                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
+    ASSERT_NE(source, MAP_FAILED);
+    memset(source, 0x5C, kLength);
+
+    TransferRequest w;
+    w.opcode = TransferRequest::WRITE;
+    w.length = kLength;
+    w.source = source;
+    w.target_id = h.segment_id;
+    w.target_offset = h.remote_base;
+
+    auto start = std::chrono::steady_clock::now();
+    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
+    auto elapsed = std::chrono::steady_clock::now() - start;
+    // The fake legacy peer waits up to 8s for the old mutual-write deadlock.
+    // Leave generous CI headroom while still proving the concurrent-read path.
+    EXPECT_LT(elapsed, std::chrono::seconds(3));
+
+    // Terminal status is the source-buffer lifetime boundary. Protecting the
+    // pages immediately after FAILED would crash if an async_write still owned
+    // them and attempted further progress.
+    ASSERT_EQ(mprotect(source, kLength, PROT_NONE), 0);
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    ASSERT_EQ(mprotect(source, kLength, PROT_READ | PROT_WRITE), 0);
+    ASSERT_EQ(munmap(source, kLength), 0);
+
+    legacy_server.join();
+    EXPECT_TRUE(legacy_server.sawFlaggedWrite());
+}
+
+// A stale v2 descriptor can also point at a legacy server with a request
+// SHORTER than a status frame (1-7 bytes). The v1 peer treats the flagged
+// opcode as READ, streams fewer than 8 "payload" bytes, and then keeps the
+// connection open waiting for the next header — no EOF ever arrives, and for
+// WRITE it is symmetrically stuck parsing our body bytes as a partial
+// header. Without a status-frame deadline both directions wait forever;
+// with it they must fail, and only after actually waiting the deadline out
+// (an early failure would mean something else broke).
+TEST(TcpWriteVisibilityTest, StaleV2DescriptorShortRequestFailsWithinDeadline) {
+    ScopedEnvVar fast_deadline("MC_TCP_STATUS_TIMEOUT_SEC", "2");
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17906", 8ull << 20);
+    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_proto_version = 2;  // deliberately stale capability advertisement
+
+    char buf[4] = {0x11, 0x22, 0x33, 0x44};
+    for (auto opcode : {TransferRequest::WRITE, TransferRequest::READ}) {
+        // One server per direction: the previous connection was (correctly)
+        // discarded rather than re-pooled, so each request dials anew.
+        LegacyReadServer legacy_server(/*keep_open=*/true);
+        ASSERT_TRUE(legacy_server.ok());
+        desc->tcp_data_port = legacy_server.port();
+
+        TransferRequest r;
+        r.opcode = opcode;
+        r.length = sizeof(buf);
+        r.source = buf;
+        r.target_id = h.segment_id;
+        r.target_offset = h.remote_base;
+
+        auto start = std::chrono::steady_clock::now();
+        EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::FAILED)
+            << "opcode " << static_cast<int>(opcode);
+        auto elapsed = std::chrono::steady_clock::now() - start;
+        EXPECT_GE(elapsed, std::chrono::seconds(1))
+            << "failure arrived before the status deadline could have fired; "
+               "the wrong path failed (opcode "
+            << static_cast<int>(opcode) << ")";
+        EXPECT_LT(elapsed, std::chrono::seconds(6))
+            << "deadline did not bound the stale-descriptor wait (opcode "
+            << static_cast<int>(opcode) << ")";
+        legacy_server.join();
+    }
+}
+
+TEST(TcpWriteVisibilityTest, PerPeerLaneAndQueueBoundsHoldUnderLoad) {
+    constexpr int kRounds = 3;
+    constexpr int kRequestCount = 32;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "2");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "64");
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    for (int round = 0; round < kRounds; ++round) {
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        ScopedLaneHooks hooks;
+#endif
+        HoldingWriteServer fake_peer;
+        ASSERT_TRUE(fake_peer.ok()) << "round " << round;
+
+        EngineHandle h;
+        h.init(metadata_server, "127.0.0.2:" + std::to_string(17907 + round),
+               kLength);
+        ASSERT_TRUE(h.ok) << "engine/segment setup failed in round " << round;
+
+        auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+        ASSERT_NE(desc, nullptr);
+        desc->tcp_data_port = fake_peer.port();
+        desc->tcp_proto_version = 2;
+
+        memset(h.pool, 0x4D + round, kLength);
+        std::vector<TransferRequest> requests(kRequestCount);
+        for (auto& request : requests) {
+            request.opcode = TransferRequest::WRITE;
+            request.length = kLength;
+            request.source = h.pool;
+            request.target_id = h.segment_id;
+            request.target_offset = h.remote_base;
+        }
+
+        auto batch_id = h.engine->allocateBatchID(kRequestCount);
+        Status submission = h.engine->submitTransfer(batch_id, requests);
+        ASSERT_TRUE(submission.ok()) << "round " << round;
+
+        EXPECT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)))
+            << "round " << round << " accepted only "
+            << fake_peer.acceptedCount() << " connections";
+        // Give any incorrectly uncapped attempts time to reach accept().
+        std::this_thread::sleep_for(std::chrono::milliseconds(250));
+        EXPECT_LE(fake_peer.maxAcceptedCount(), 2)
+            << "per-peer lane count exceeded in round " << round;
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+        EXPECT_LE(maximum_observed_queue_depth.load(std::memory_order_acquire),
+                  64u);
+        EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+                  2u);
+        EXPECT_FALSE(
+            connecting_lane_had_current.load(std::memory_order_acquire));
+#endif
+
+        fake_peer.closePeer();
+
+        std::vector<TransferStatusEnum> final_states(
+            kRequestCount, TransferStatusEnum::WAITING);
+        bool status_query_failed = false;
+        bool all_terminal = false;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(20);
+        while (!all_terminal && std::chrono::steady_clock::now() < deadline) {
+            all_terminal = true;
+            for (int i = 0; i < kRequestCount; ++i) {
+                if (final_states[i] == TransferStatusEnum::COMPLETED ||
+                    final_states[i] == TransferStatusEnum::FAILED)
+                    continue;
+
+                TransferStatus status;
+                status.s = TransferStatusEnum::WAITING;
+                Status query = h.engine->getTransferStatus(batch_id, i, status);
+                if (!query.ok()) {
+                    status_query_failed = true;
+                    all_terminal = false;
+                    continue;
+                }
+                final_states[i] = status.s;
+                if (status.s != TransferStatusEnum::COMPLETED &&
+                    status.s != TransferStatusEnum::FAILED)
+                    all_terminal = false;
+            }
+            if (!all_terminal)
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+
+        EXPECT_FALSE(status_query_failed) << "round " << round;
+        EXPECT_TRUE(all_terminal) << "round " << round;
+        for (int i = 0; i < kRequestCount; ++i) {
+            EXPECT_NE(final_states[i], TransferStatusEnum::WAITING)
+                << "request " << i << " remained WAITING in round " << round;
+            EXPECT_TRUE(final_states[i] == TransferStatusEnum::COMPLETED ||
+                        final_states[i] == TransferStatusEnum::FAILED)
+                << "request " << i << " was not terminal in round " << round;
+        }
+        if (all_terminal) (void)h.engine->freeBatchID(batch_id);
+    }
+}
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+TEST(TcpWriteVisibilityTest,
+     FailedLaneReconnectsWhileSiblingLaneRemainsUsable) {
+    constexpr int kRequestCount = 3;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "2");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17931", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    memset(h.pool, 0x6B, kLength);
+    const TransferRequest request = makeWriteRequest(h, kLength);
+    std::vector<TransferRequest> requests(kRequestCount, request);
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+
+    ASSERT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 2; },
+        std::chrono::seconds(5)));
+    ASSERT_EQ(fake_peer.activeAcceptedCount(), 2);
+
+    // Drop one busy lane while the sibling remains busy and therefore usable.
+    // The third request remains queued and must be pulled by a replacement
+    // connection for the failed lane, without entering peer-wide cooldown.
+    ASSERT_TRUE(fake_peer.closeOneAccepted());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_terminal_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForAccepted(3, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connecting_count.load(std::memory_order_acquire) >= 3 &&
+                   lane_busy_count.load(std::memory_order_acquire) >= 3;
+        },
+        std::chrono::seconds(5)));
+
+    EXPECT_EQ(fake_peer.activeAcceptedCount(), 2);
+    EXPECT_EQ(cooldown_started_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(retry_armed_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(session_failure_count.load(std::memory_order_acquire), 1);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              2u);
+
+    fake_peer.closePeer();
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), batch_id, kRequestCount,
+                                     std::chrono::seconds(10)));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ConnectFailedLaneRetriesWhileSiblingLaneRemainsUsable) {
+    constexpr int kRequestCount = 2;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "2");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/false,
+                          /*block_retry=*/false,
+                          /*block_retry_armed=*/false,
+                          /*block_admission=*/false,
+                          /*fail_second_connect=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17935", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    memset(h.pool, 0x6C, kLength);
+    const TransferRequest request = makeWriteRequest(h, kLength);
+    std::vector<TransferRequest> requests(kRequestCount, request);
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+
+    ASSERT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_injection_call_count.load(
+                       std::memory_order_acquire) >= 3 &&
+                   lane_busy_count.load(std::memory_order_acquire) >= 2;
+        },
+        std::chrono::seconds(5)));
+
+    EXPECT_EQ(fake_peer.activeAcceptedCount(), 2);
+    EXPECT_EQ(lane_connect_injection_call_count.load(std::memory_order_acquire),
+              3);
+    EXPECT_EQ(cooldown_started_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(retry_armed_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(connect_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              2u);
+
+    fake_peer.closePeer();
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), batch_id, kRequestCount,
+                                     std::chrono::seconds(10)));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest, DirtyLastUsableLaneStartsFreshConnectRound) {
+    constexpr int kRequestCount = 2;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17936", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    memset(h.pool, 0x6E, kLength);
+    const TransferRequest request = makeWriteRequest(h, kLength);
+    const std::vector<TransferRequest> requests(kRequestCount, request);
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+
+    ASSERT_TRUE(fake_peer.waitForAccepted(1, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    ASSERT_EQ(fake_peer.activeAcceptedCount(), 1);
+
+    // The only established lane fails while another request is still queued.
+    // Because this round had a successful connection, the queued request must
+    // get a fresh connect round instead of being failed as CONNECT_FAILED.
+    ASSERT_TRUE(fake_peer.closeOneAccepted());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_terminal_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 2; },
+        std::chrono::seconds(5)));
+
+    EXPECT_EQ(fake_peer.activeAcceptedCount(), 1);
+    EXPECT_EQ(connect_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(session_failure_count.load(std::memory_order_acquire), 1);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              1u);
+
+    fake_peer.closePeer();
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), batch_id, kRequestCount,
+                                     std::chrono::seconds(10)));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ReconnectProbePrefersNeverTriedLanesOverFailedLane) {
+    constexpr int kRequestCount = 5;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "4");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks hooks;
+    tcpTransportSetLaneConnectFailureInjectionHookForTest(
+        failLaneOneAndTwoConnectAttempt);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17937", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    memset(h.pool, 0x6D, kLength);
+    const TransferRequest request = makeWriteRequest(h, kLength);
+    const std::vector<TransferRequest> requests(kRequestCount, request);
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+
+    // Lanes 1 and 2 fail on every probe. A starvation-prone selector retries
+    // lane 1 forever and never reaches the other retryable lane or lane 3.
+    // Each lane gets one probe per round, so lanes 0 and 3 are accepted.
+    ASSERT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_injection_call_count.load(
+                       std::memory_order_acquire) >= 4;
+        },
+        std::chrono::seconds(5)));
+    EXPECT_EQ(fake_peer.activeAcceptedCount(), 2);
+    EXPECT_GE(lane_connect_injection_call_count.load(std::memory_order_acquire),
+              4);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              4u);
+
+    fake_peer.closePeer();
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), batch_id, kRequestCount,
+                                     std::chrono::seconds(10)));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(batch_id);
+}
+#endif
+
+TEST(TcpWriteVisibilityTest,
+     QueuedWorkAndBusyLanesCompleteExactlyOnceDuringShutdown) {
+    constexpr int kRequestCount = 16;
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "2");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "64");
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    ScopedLaneHooks hooks;
+#endif
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17920", kLength);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = fake_peer.port();
+    desc->tcp_proto_version = 2;
+
+    memset(h.pool, 0x5A, kLength);
+    std::vector<TransferRequest> requests(kRequestCount);
+    for (auto& request : requests) {
+        request.opcode = TransferRequest::WRITE;
+        request.length = kLength;
+        request.source = h.pool;
+        request.target_id = h.segment_id;
+        request.target_offset = h.remote_base;
+    }
+
+    auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+    ASSERT_TRUE(fake_peer.waitForAccepted(2, std::chrono::seconds(5)));
+    EXPECT_LE(fake_peer.maxAcceptedCount(), 2);
+
+    const auto start = std::chrono::steady_clock::now();
+    h.engine.reset();
+    const auto elapsed = std::chrono::steady_clock::now() - start;
+    EXPECT_LT(elapsed, std::chrono::seconds(5));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+    EXPECT_LE(maximum_observed_queue_depth.load(std::memory_order_acquire),
+              64u);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              2u);
+    hooks.reset();
+#endif
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+TEST(TcpWriteVisibilityTest,
+     ConnectingLaneShutdownDetachesOwnershipAndIgnoresLateHandler) {
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17921", kLength);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = fake_peer.port();
+    desc->tcp_proto_version = 2;
+
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = kLength;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+    auto batch_id = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, {request}).ok());
+
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_handler_entered.load(std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+    EXPECT_FALSE(connecting_lane_had_current.load(std::memory_order_acquire));
+
+    auto engine = std::move(h.engine);
+    auto destruction =
+        std::async(std::launch::async,
+                   [engine = std::move(engine)]() mutable { engine.reset(); });
+
+    // Let shutdown invalidate the lane epoch before the blocked resolve
+    // handler returns. io_context::stop() cannot interrupt that handler, so
+    // destruction must wait for this explicit release and then join it.
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    EXPECT_EQ(destruction.wait_for(std::chrono::milliseconds(0)),
+              std::future_status::timeout);
+    releaseLaneConnectHandler();
+
+    ASSERT_EQ(destruction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    destruction.get();
+
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+    EXPECT_GE(late_lane_handler_count.load(std::memory_order_acquire), 1);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              1u);
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ReconnectRoundsAreRateLimitedAndCooldownQueueIsBounded) {
+    constexpr int kCooldownRequestCount = 4;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "3");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "500");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    UnavailableTcpPeer unavailable_peer;
+    ASSERT_TRUE(unavailable_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17925", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = unavailable_peer.port();
+    desc->tcp_proto_version = 2;
+
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = 1;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+
+    const auto first_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(first_batch, {request}).ok());
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), first_batch, 1,
+                                     std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return cooldown_started_count.load(std::memory_order_acquire) >= 1;
+        },
+        std::chrono::seconds(2)));
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 1);
+
+    std::vector<TransferRequest> cooldown_requests(kCooldownRequestCount,
+                                                   request);
+    const auto cooldown_batch =
+        h.engine->allocateBatchID(kCooldownRequestCount);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(cooldown_batch, cooldown_requests).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return retry_armed_count.load(std::memory_order_acquire) == 1; },
+        std::chrono::seconds(2)));
+
+    // The first three requests enter the work queue; the fourth waits in the
+    // pending-admission FIFO instead of failing synchronously. No second
+    // connection round starts before the retry timer.
+    for (int task_id = 0; task_id < 3; ++task_id) {
+        TransferStatus status;
+        status.s = TransferStatusEnum::WAITING;
+        ASSERT_TRUE(
+            h.engine->getTransferStatus(cooldown_batch, task_id, status).ok());
+        EXPECT_EQ(status.s, TransferStatusEnum::WAITING);
+    }
+    TransferStatus overflow_status;
+    overflow_status.s = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(
+        h.engine->getTransferStatus(cooldown_batch, 3, overflow_status).ok());
+    EXPECT_EQ(overflow_status.s, TransferStatusEnum::WAITING);
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_pending_count.load(std::memory_order_acquire), 1);
+    EXPECT_LE(maximum_observed_queue_depth.load(std::memory_order_acquire), 3u);
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return queue_timeout_failure_count.load(
+                       std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(2)));
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(retry_armed_count.load(std::memory_order_acquire), 1);
+
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), cooldown_batch,
+                                     kCooldownRequestCount,
+                                     std::chrono::seconds(5)));
+    EXPECT_EQ(retry_fired_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(retry_armed_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 2);
+    EXPECT_EQ(connect_failure_count.load(std::memory_order_acquire), 4);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(first_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(cooldown_batch);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(first_batch);
+    (void)h.engine->freeBatchID(cooldown_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     RetryTimerSerializesDelayedPumpAndCooldownTransition) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "2");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/false,
+                          /*block_retry=*/false,
+                          /*block_retry_armed=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    UnavailableTcpPeer unavailable_peer;
+    ASSERT_TRUE(unavailable_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17928", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = unavailable_peer.port();
+    desc->tcp_proto_version = 2;
+
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = 1;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+
+    const auto exhausted_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(exhausted_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return cooldown_started_count.load(std::memory_order_acquire) >=
+                       1 &&
+                   connect_failure_count.load(std::memory_order_acquire) >= 1;
+        },
+        std::chrono::seconds(2)));
+
+    const auto first_pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(first_pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return retry_armed_observer_entered.load(std::memory_order_acquire);
+        },
+        std::chrono::seconds(2)));
+
+    // The worker is blocked after timer registration and outside the group
+    // mutex. This admission posts a pump before the deadline; keeping the
+    // worker blocked past expiry makes that pump run before the ready timer.
+    const auto second_pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(second_pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return maximum_observed_queue_depth.load(
+                       std::memory_order_acquire) == 2;
+        },
+        std::chrono::seconds(2)));
+    std::this_thread::sleep_for(std::chrono::milliseconds(1200));
+
+    EXPECT_EQ(retry_armed_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(queue_rejection_count.load(std::memory_order_acquire), 0);
+    EXPECT_LE(maximum_observed_queue_depth.load(std::memory_order_acquire), 2u);
+
+    releaseRetryArmedObserver();
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return retry_fired_count.load(std::memory_order_acquire) == 1 &&
+                   connect_failure_count.load(std::memory_order_acquire) == 3;
+        },
+        std::chrono::seconds(5)));
+
+    h.engine.reset();
+    expectEverySliceCompletedExactlyOnceAfterShutdown(exhausted_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(first_pending_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(second_pending_batch);
+    EXPECT_EQ(retry_armed_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(retry_fired_count.load(std::memory_order_acquire), 1);
+    // One initial attempt plus one timer-owned retry proves the delayed pump
+    // neither reset an active round nor created an extra immediate attempt.
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 2);
+    EXPECT_EQ(connect_failure_count.load(std::memory_order_acquire), 3);
+    EXPECT_LE(maximum_observed_queue_depth.load(std::memory_order_acquire), 2u);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(exhausted_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(first_pending_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(second_pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ShutdownWithPendingRetryTimerCompletesAcceptedWorkOnce) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "4");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    UnavailableTcpPeer unavailable_peer;
+    ASSERT_TRUE(unavailable_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17927", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = unavailable_peer.port();
+    desc->tcp_proto_version = 2;
+
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = 1;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+
+    const auto exhausted_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(exhausted_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return cooldown_started_count.load(std::memory_order_acquire) >=
+                       1 &&
+                   connect_failure_count.load(std::memory_order_acquire) >= 1;
+        },
+        std::chrono::seconds(2)));
+
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return retry_armed_count.load(std::memory_order_acquire) == 1; },
+        std::chrono::seconds(2)));
+
+    const auto shutdown_start = std::chrono::steady_clock::now();
+    h.engine.reset();
+    EXPECT_LT(std::chrono::steady_clock::now() - shutdown_start,
+              std::chrono::seconds(5));
+
+    expectEverySliceCompletedExactlyOnceAfterShutdown(exhausted_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(shutdown_failure_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(retry_fired_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(exhausted_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ShutdownInvalidatesPendingRetryAndLateHandlerCannotReconnect) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "4");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/false,
+                          /*block_retry=*/true);
     const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
-    const char* name_env = std::getenv("MC_LOCAL_SERVER_NAME");
-    std::string server_name = name_env ? name_env : "127.0.0.2:17901";
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    UnavailableTcpPeer unavailable_peer;
+    ASSERT_TRUE(unavailable_peer.ok());
 
-    const size_t pool_size = 64ull << 20;
     EngineHandle h;
-    h.init(metadata_server, server_name, pool_size);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    h.init(metadata_server, "127.0.0.2:17926", 64 * 1024);
+    ASSERT_TRUE(h.ok);
 
-    // Region layout inside the registered pool (all offsets from pool base):
-    //   [0, kBigLength)                       : WRITE target region
-    //   [kRegionAlign, +kBigLength)           : local staging for WRITE
-    //   [3*kRegionAlign + t*kRegionAlign, ...): per-noise-thread scratch
-    char* base = (char*)h.pool;
-    char* write_src = base + kRegionAlign;
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = unavailable_peer.port();
+    desc->tcp_proto_version = 2;
 
-    std::atomic<bool> stop{false};
-    std::atomic<uint64_t> noise_failures{0};
-    std::vector<std::thread> noise;
-    for (int t = 0; t < kNoiseThreads; ++t) {
-        noise.emplace_back([&, t] {
-            char* src = base + (3 + 2 * t) * kRegionAlign;
-            uint64_t dst_off = (4 + 2 * t) * kRegionAlign;
-            memset(src, 0x5A + t, kSmallLength);
-            while (!stop.load(std::memory_order_relaxed)) {
-                TransferRequest entry;
-                entry.opcode = TransferRequest::WRITE;
-                entry.length = kSmallLength;
-                entry.source = src;
-                entry.target_id = h.segment_id;
-                entry.target_offset = h.remote_base + dst_off;
-                if (runOne(h.engine.get(), entry) !=
-                    TransferStatusEnum::COMPLETED)
-                    noise_failures++;
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = 1;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+
+    const auto exhausted_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(exhausted_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return cooldown_started_count.load(std::memory_order_acquire) >=
+                       1 &&
+                   connect_failure_count.load(std::memory_order_acquire) >= 1;
+        },
+        std::chrono::seconds(2)));
+
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return retry_armed_count.load(std::memory_order_acquire) == 1; },
+        std::chrono::seconds(2)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return retry_handler_entered.load(std::memory_order_acquire); },
+        std::chrono::seconds(3)));
+
+    auto engine = std::move(h.engine);
+    auto destruction =
+        std::async(std::launch::async,
+                   [engine = std::move(engine)]() mutable { engine.reset(); });
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return shutdown_failure_count.load(std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(2)));
+    EXPECT_EQ(destruction.wait_for(std::chrono::milliseconds(0)),
+              std::future_status::timeout);
+
+    const int connects_before_release =
+        lane_connecting_count.load(std::memory_order_acquire);
+    releaseRetryHandler();
+    ASSERT_EQ(destruction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    destruction.get();
+
+    expectEverySliceCompletedExactlyOnceAfterShutdown(exhausted_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(lane_connecting_count.load(std::memory_order_acquire),
+              connects_before_release);
+    EXPECT_EQ(retry_fired_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(retry_late_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(exhausted_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     TaskGroupShutdownCompletesNotYetStartedSlicesExactlyOnce) {
+    constexpr int kRequestCount = 3;
+    constexpr size_t kLength = 64 * 1024;
+
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedLaneHooks hooks;
+
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17936", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    memset(h.pool, 0x6D, kLength);
+    TransferRequest request = makeWriteRequest(h, kLength);
+    request.task_group_id = 1;
+
+    std::vector<TransferRequest> requests(kRequestCount, request);
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+
+    // Task-group sequencing starts only the first Slice. Hold it BUSY so the
+    // remaining Slices have been created but have not entered the lane queue.
+    ASSERT_TRUE(fake_peer.waitForAccepted(1, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+
+    h.engine.reset();
+
+    // Shutdown must not strand the sequence tail merely because the TCP
+    // io_context has already been stopped. Every pre-created Slice must become
+    // terminal exactly once.
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+
+    const auto& batch = Transport::toBatchDesc(batch_id);
+    ASSERT_EQ(batch.task_list.size(), kRequestCount);
+    for (size_t task_id = 0; task_id < batch.task_list.size(); ++task_id) {
+        const auto& task = batch.task_list[task_id];
+        const uint64_t success =
+            __atomic_load_n(&task.success_slice_count, __ATOMIC_RELAXED);
+        const uint64_t failed =
+            __atomic_load_n(&task.failed_slice_count, __ATOMIC_RELAXED);
+        const uint64_t slices =
+            __atomic_load_n(&task.slice_count, __ATOMIC_RELAXED);
+
+        EXPECT_EQ(slices, 1u) << "task " << task_id;
+        EXPECT_EQ(success, 0u) << "task " << task_id;
+        EXPECT_EQ(failed, 1u) << "task " << task_id;
+        ASSERT_EQ(task.slice_list.size(), 1u);
+        EXPECT_EQ(task.slice_list.front()->status, Transport::Slice::FAILED)
+            << "task " << task_id;
+    }
+
+    EXPECT_EQ(shutdown_failure_count.load(std::memory_order_acquire),
+              kRequestCount);
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest, LaneTerminalTypesAreMoveOnly) {
+    EXPECT_TRUE(tcpTransportLaneTypesAreMoveOnlyForTest());
+}
+#endif
+
+TEST(TcpWriteVisibilityTest, OneLaneReusesCleanSocketInFifoOrder) {
+    constexpr int kRequestCount = 8;
+    constexpr size_t kLength = 64 * 1024;
+    constexpr size_t kPoolSize = kRequestCount * kLength;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "16");
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    ReusingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17922", kPoolSize);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = fake_peer.port();
+    desc->tcp_proto_version = 2;
+
+    memset(h.pool, 0x6B, kLength);
+    std::vector<TransferRequest> requests(kRequestCount);
+    std::vector<uint64_t> expected_addresses;
+    expected_addresses.reserve(kRequestCount);
+    for (int i = 0; i < kRequestCount; ++i) {
+        auto& request = requests[i];
+        request.opcode = TransferRequest::WRITE;
+        request.length = kLength;
+        request.source = h.pool;
+        request.target_id = h.segment_id;
+        request.target_offset = h.remote_base + i * kLength;
+        expected_addresses.push_back(request.target_offset);
+    }
+
+    auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+    ASSERT_TRUE(
+        fake_peer.waitForRequests(kRequestCount, std::chrono::seconds(10)));
+
+    for (int i = 0; i < kRequestCount; ++i) {
+        TransferStatus status;
+        status.s = TransferStatusEnum::WAITING;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(5);
+        while (status.s == TransferStatusEnum::WAITING &&
+               std::chrono::steady_clock::now() < deadline) {
+            ASSERT_TRUE(h.engine->getTransferStatus(batch_id, i, status).ok());
+            if (status.s == TransferStatusEnum::WAITING)
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        EXPECT_EQ(status.s, TransferStatusEnum::COMPLETED) << "request " << i;
+    }
+
+    EXPECT_EQ(fake_peer.acceptedCount(), 1);
+    EXPECT_EQ(fake_peer.requestAddresses(), expected_addresses);
+    (void)h.engine->freeBatchID(batch_id);
+}
+
+#ifdef MOONCAKE_TCP_TRANSPORT_TEST_HOOKS
+TEST(TcpWriteVisibilityTest,
+     PendingAdmissionWaitsInsteadOfFailingSynchronously) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "2");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17929", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto request = makeWriteRequest(h, 1);
+    const auto batch_id = h.engine->allocateBatchID(2);
+    const auto submit_start = std::chrono::steady_clock::now();
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, {request, request}).ok());
+    const auto submit_elapsed = std::chrono::steady_clock::now() - submit_start;
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_handler_entered.load(
+                       std::memory_order_acquire) &&
+                   admission_pending_count.load(std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(5)));
+
+    TransferStatus pending_status;
+    pending_status.s = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(h.engine->getTransferStatus(batch_id, 1, pending_status).ok());
+    EXPECT_EQ(pending_status.s, TransferStatusEnum::WAITING);
+    EXPECT_LT(submit_elapsed, std::chrono::seconds(2));
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(maximum_observed_queue_depth.load(std::memory_order_acquire), 1u);
+    EXPECT_EQ(maximum_observed_pending_depth.load(std::memory_order_acquire),
+              1u);
+
+    releaseLaneConnectHandler();
+    h.engine.reset();
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest, PendingAdmissionTimesOutExactlyOnce) {
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "100");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17930", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto request = makeWriteRequest(h, kLength);
+    const auto active_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(active_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForAccepted(1, std::chrono::seconds(5)));
+
+    const auto queued_batch = h.engine->allocateBatchID(1);
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(queued_batch, {request}).ok());
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return queue_timeout_failure_count.load(
+                       std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(5)));
+
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_timer_fired_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(admission_promoted_count.load(std::memory_order_acquire), 0);
+    h.engine.reset();
+    expectEverySliceCompletedExactlyOnceAfterShutdown(active_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(queued_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(active_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(queued_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest, PendingAdmissionsPromoteInFifoOrder) {
+    constexpr int kRequestCount = 4;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "3");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    ReusingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17931", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    std::vector<TransferRequest> requests;
+    std::vector<uint64_t> expected_addresses;
+    for (int i = 0; i < kRequestCount; ++i) {
+        const uint64_t address = h.remote_base + static_cast<uint64_t>(i);
+        requests.push_back(makeWriteRequest(h, 1, address));
+        expected_addresses.push_back(address);
+    }
+
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_handler_entered.load(
+                       std::memory_order_acquire) &&
+                   admission_pending_count.load(std::memory_order_acquire) == 3;
+        },
+        std::chrono::seconds(5)));
+    EXPECT_EQ(maximum_observed_queue_depth.load(std::memory_order_acquire), 1u);
+    EXPECT_EQ(maximum_observed_pending_depth.load(std::memory_order_acquire),
+              3u);
+
+    releaseLaneConnectHandler();
+    ASSERT_TRUE(
+        fake_peer.waitForRequests(kRequestCount, std::chrono::seconds(10)));
+    ASSERT_TRUE(waitForBatchTerminal(h.engine.get(), batch_id, kRequestCount,
+                                     std::chrono::seconds(5)));
+    EXPECT_EQ(fake_peer.requestAddresses(), expected_addresses);
+    EXPECT_GE(admission_promoted_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+
+    hooks.reset();
+    (void)h.engine->freeBatchID(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest, PendingAdmissionHardBoundRejectsImmediately) {
+    constexpr int kRequestCount = 3;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17923", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    std::vector<TransferRequest> requests(kRequestCount);
+    for (auto& request : requests) {
+        request.opcode = TransferRequest::WRITE;
+        request.length = 1;
+        request.source = h.pool;
+        request.target_id = h.segment_id;
+        request.target_offset = h.remote_base;
+    }
+
+    const auto batch_id = h.engine->allocateBatchID(kRequestCount);
+    ASSERT_TRUE(h.engine->submitTransfer(batch_id, requests).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_handler_entered.load(std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+
+    EXPECT_EQ(queue_rejection_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(admission_hard_rejection_count.load(std::memory_order_acquire),
+              1);
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(connect_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(maximum_observed_queue_depth.load(std::memory_order_acquire), 1u);
+    EXPECT_EQ(maximum_observed_pending_depth.load(std::memory_order_acquire),
+              1u);
+    EXPECT_FALSE(connecting_lane_had_current.load(std::memory_order_acquire));
+    for (int task_id = 0; task_id < kRequestCount; ++task_id) {
+        TransferStatus status;
+        status.s = TransferStatusEnum::WAITING;
+        ASSERT_TRUE(
+            h.engine->getTransferStatus(batch_id, task_id, status).ok());
+        EXPECT_EQ(status.s, task_id == kRequestCount - 1
+                                ? TransferStatusEnum::FAILED
+                                : TransferStatusEnum::WAITING);
+    }
+
+    releaseLaneConnectHandler();
+    h.engine.reset();
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ShutdownWithPendingAdmissionsAndArmedTimerCompletesOnce) {
+    constexpr size_t kLength = 64 * 1024;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks;
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17932", kLength);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto request = makeWriteRequest(h, kLength);
+    const auto active_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(active_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForAccepted(1, std::chrono::seconds(5)));
+
+    const auto queued_batch = h.engine->allocateBatchID(1);
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(queued_batch, {request}).ok());
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_pending_count.load(std::memory_order_acquire) ==
+                       1 &&
+                   admission_timer_armed_count.load(
+                       std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(5)));
+
+    const auto shutdown_start = std::chrono::steady_clock::now();
+    h.engine.reset();
+    EXPECT_LT(std::chrono::steady_clock::now() - shutdown_start,
+              std::chrono::seconds(5));
+    expectEverySliceCompletedExactlyOnceAfterShutdown(active_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(queued_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(shutdown_failure_count.load(std::memory_order_acquire), 3);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_promoted_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_timer_fired_count.load(std::memory_order_acquire), 0);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(active_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(queued_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     AdmissionTimeoutWinsBeforeCapacityReleasePreservesOneOwner) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "100");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/false,
+                          /*block_retry=*/false,
+                          /*block_retry_armed=*/false,
+                          /*block_admission=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    ReusingWriteServer fake_peer(/*hold_first_ack=*/true);
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17933", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto request = makeWriteRequest(h, 1);
+    const auto active_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(active_batch, {request}).ok());
+    ASSERT_TRUE(fake_peer.waitForFirstRequest(std::chrono::seconds(5)));
+
+    const auto queued_batch = h.engine->allocateBatchID(1);
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(queued_batch, {request}).ok());
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_handler_entered.load(std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+
+    // The expired timer handler is paused outside the group mutex. Make the
+    // active session's capacity release ready, then let the timer and queued
+    // completion contend in a deterministic order on the single io worker.
+    fake_peer.releaseFirstAck();
+    ASSERT_TRUE(fake_peer.waitForFirstAckSent(std::chrono::seconds(5)));
+    releaseAdmissionHandler();
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return queue_timeout_failure_count.load(
+                       std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForRequests(2, std::chrono::seconds(5)));
+
+    h.engine.reset();
+    expectEverySliceCompletedExactlyOnceAfterShutdown(active_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(queued_batch);
+    expectEverySliceCompletedExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_promoted_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_timer_fired_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(active_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(queued_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     CapacityReleasePromotesBeforeDeadlineAndCancelledTimerIsLate) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "1");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/false,
+                          /*block_retry=*/false,
+                          /*block_retry_armed=*/false,
+                          /*block_admission=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    ReusingWriteServer fake_peer(/*hold_first_ack=*/true);
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17934", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto request = makeWriteRequest(h, 1);
+    const auto active_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(active_batch, {request}).ok());
+    ASSERT_TRUE(fake_peer.waitForFirstRequest(std::chrono::seconds(5)));
+
+    const auto queued_batch = h.engine->allocateBatchID(1);
+    const auto pending_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine->submitTransfer(queued_batch, {request}).ok());
+    ASSERT_TRUE(h.engine->submitTransfer(pending_batch, {request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_pending_count.load(std::memory_order_acquire) ==
+                       1 &&
+                   admission_timer_armed_count.load(
+                       std::memory_order_acquire) == 1;
+        },
+        std::chrono::seconds(5)));
+
+    // Completing the active exchange frees a work-queue slot before the long
+    // deadline. The pump promotes the pending item, invalidates the timer
+    // epoch, and cancels the now-unneeded shared admission timer.
+    fake_peer.releaseFirstAck();
+    ASSERT_TRUE(fake_peer.waitForFirstAckSent(std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_promoted_count.load(std::memory_order_acquire) >=
+                   1;
+        },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_handler_entered.load(std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(admission_timer_fired_count.load(std::memory_order_acquire), 0);
+
+    releaseAdmissionHandler();
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return admission_timer_late_count.load(std::memory_order_acquire) >=
+                   1;
+        },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForRequests(3, std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_terminal_count.load(std::memory_order_acquire) >= 3; },
+        std::chrono::seconds(5)));
+
+    h.engine.reset();
+    expectEverySliceSucceededExactlyOnceAfterShutdown(active_batch);
+    expectEverySliceSucceededExactlyOnceAfterShutdown(queued_batch);
+    expectEverySliceSucceededExactlyOnceAfterShutdown(pending_batch);
+    EXPECT_EQ(queue_timeout_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_EQ(queue_full_failure_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(admission_promoted_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(admission_timer_fired_count.load(std::memory_order_acquire), 0);
+    EXPECT_GE(admission_timer_late_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(active_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(queued_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(pending_batch);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ConcurrentAdmissionShutdownStressPreservesLaneOwnership) {
+    constexpr size_t kSubmissionCount = 40;
+    constexpr size_t kSubmitterCount = 4;
+    constexpr size_t kQueueCapacity = 8;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "2");
+    ScopedEnvVar queue_capacity("MC_TCP_MAX_QUEUED_TRANSFERS_PER_PEER", "8");
+    ScopedEnvVar pending_capacity("MC_TCP_MAX_PENDING_ADMISSIONS_PER_PEER",
+                                  "1");
+    ScopedEnvVar admission_timeout("MC_TCP_ADMISSION_TIMEOUT_MS", "10000");
+    ScopedLaneHooks hooks(/*block_first_connect_handler=*/false,
+                          /*block_after_busy=*/true);
+    const char* env = std::getenv("MC_METADATA_SERVER");
+    const std::string metadata_server = env ? env : "P2PHANDSHAKE";
+
+    HoldingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(metadata_server, "127.0.0.2:17924", 64 * 1024);
+    ASSERT_TRUE(h.ok);
+
+    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(desc, nullptr);
+    desc->tcp_data_port = fake_peer.port();
+    desc->tcp_proto_version = 2;
+
+    TransferRequest request;
+    request.opcode = TransferRequest::WRITE;
+    request.length = 1;
+    request.source = h.pool;
+    request.target_id = h.segment_id;
+    request.target_offset = h.remote_base;
+
+    const auto busy_batch_id = h.engine->allocateBatchID(2);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(busy_batch_id, {request, request}).ok());
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return lane_connect_handler_entered.load(
+                       std::memory_order_acquire) &&
+                   lane_busy_count.load(std::memory_order_acquire) >= 1;
+        },
+        std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForAccepted(1, std::chrono::seconds(5)));
+
+    std::vector<Transport::BatchID> batch_ids(kSubmissionCount);
+    for (auto& batch_id : batch_ids) batch_id = h.engine->allocateBatchID(1);
+    std::vector<std::atomic<int>> submit_results(kSubmissionCount);
+    for (auto& result : submit_results) result.store(0);
+
+    std::vector<std::thread> submitters;
+    for (size_t thread_id = 0; thread_id < kSubmitterCount; ++thread_id) {
+        submitters.emplace_back([&, thread_id] {
+            for (size_t i = thread_id; i < kSubmissionCount;
+                 i += kSubmitterCount) {
+                submit_results[i].store(
+                    h.engine->submitTransfer(batch_ids[i], {request}).ok() ? 1
+                                                                           : -1,
+                    std::memory_order_release);
             }
         });
     }
+    for (auto& submitter : submitters) submitter.join();
+    for (const auto& result : submit_results)
+        EXPECT_EQ(result.load(std::memory_order_acquire), 1);
 
-    uint64_t torn_reads = 0;
-    uint64_t torn_bytes_worst = 0;
-    int first_bad_iter = -1;
-    for (int iter = 1; iter <= kIterations; ++iter) {
-        // Generation-stamped pattern: every byte identifies the iteration.
-        memset(write_src, iter & 0xFF, kBigLength);
+    EXPECT_EQ(maximum_observed_queue_depth.load(std::memory_order_acquire),
+              kQueueCapacity);
+    EXPECT_LE(maximum_observed_socket_count.load(std::memory_order_acquire),
+              2u);
+    EXPECT_FALSE(connecting_lane_had_current.load(std::memory_order_acquire));
+    EXPECT_EQ(queue_rejection_count.load(std::memory_order_acquire),
+              static_cast<int>(kSubmissionCount - (kQueueCapacity - 1) - 1));
+    EXPECT_LE(maximum_observed_pending_depth.load(std::memory_order_acquire),
+              1u);
 
-        TransferRequest w;
-        w.opcode = TransferRequest::WRITE;
-        w.length = kBigLength;
-        w.source = write_src;
-        w.target_id = h.segment_id;
-        w.target_offset = h.remote_base;  // region at pool offset 0
-        ASSERT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED)
-            << "WRITE failed at iteration " << iter;
+    auto engine = std::move(h.engine);
+    auto destruction =
+        std::async(std::launch::async,
+                   [engine = std::move(engine)]() mutable { engine.reset(); });
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    releaseLaneConnectHandler();
+    ASSERT_EQ(destruction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    destruction.get();
 
-        // The WRITE is COMPLETED. The API contract (matching RDMA WRITE
-        // semantics, which disaggregated-serving integrations rely on when
-        // they notify the consumer out-of-band) is that destination memory
-        // is now fully written. Verify by direct local inspection of the
-        // destination region — this is exactly what a decode instance does
-        // after the prefill side signals transfer completion. Scan backwards:
-        // the tail chunks are the ones still in flight when the initiator's
-        // final local send completes.
-        size_t bad = 0;
-        for (size_t i = kBigLength; i-- > 0;) {
-            if ((unsigned char)base[i] != (unsigned char)(iter & 0xFF)) {
-                bad = i + 1;  // bytes [0, i] not yet guaranteed; count prefix
-                break;
-            }
-        }
-        if (bad) {
-            torn_reads++;
-            torn_bytes_worst = std::max<uint64_t>(torn_bytes_worst, bad);
-            if (first_bad_iter < 0) first_bad_iter = iter;
-            // Show it is a visibility delay, not data loss: wait for the
-            // server-side drain to finish before the next iteration so
-            // generations do not overlap.
-            while (memcmp(base, write_src, kBigLength) != 0)
-                std::this_thread::yield();
-        }
+    expectEverySliceCompletedExactlyOnceAfterShutdown(busy_batch_id);
+    for (const auto batch_id : batch_ids)
+        expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+    EXPECT_EQ(lane_shutdown_clean_count.load(std::memory_order_acquire), 1);
+    EXPECT_GE(late_lane_handler_count.load(std::memory_order_acquire), 1);
+
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(busy_batch_id);
+    for (const auto batch_id : batch_ids)
+        reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ProgressTimeoutWinsAgainstQueuedFinalReadCompletion) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks lane_hooks;
+    ScopedSessionProgressHooks session_hooks(
+        kSessionReadBodySuccess, kSessionCommitTimeoutBeforeProgress);
+
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18052", 16ull << 20);
+    ASSERT_TRUE(h.ok);
+
+    char* source = static_cast<char*>(h.pool);
+    char* first_destination = source + kRegionAlign;
+    for (size_t i = 0; i < kSmallLength; ++i)
+        source[i] = static_cast<char>(i * 17 + 3);
+
+    const auto first_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(h.engine
+                    ->submitTransfer(
+                        first_batch,
+                        {makeReadRequest(h, first_destination, kSmallLength)})
+                    .ok());
+    TransferStatusEnum first_status = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(waitForTaskTerminal(h.engine.get(), first_batch,
+                                    std::chrono::seconds(5), &first_status));
+    EXPECT_EQ(first_status, TransferStatusEnum::FAILED);
+    expectEverySliceCompletedExactlyOnce(first_batch);
+    EXPECT_EQ(session_timeout_committed_count.load(std::memory_order_acquire),
+              1);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 1);
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_terminal_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    EXPECT_EQ(lane_terminal_socket_count.load(std::memory_order_acquire), 0);
+    ASSERT_TRUE(h.engine->freeBatchID(first_batch).ok());
+    EXPECT_EQ(session_terminal_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 1);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ProgressTimeoutWinsAgainstQueuedFinalWriteAndAckCompletion) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "30");
+    ScopedLaneHooks lane_hooks;
+    ScopedSessionProgressHooks session_hooks(
+        kSessionWriteAckSuccess, kSessionCommitTimeoutBeforeProgress);
+    ReusingWriteServer fake_peer;
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18053", 8ull << 20);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+    memset(h.pool, 0x5A, kBigLength);
+
+    const auto first_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(first_batch, {makeWriteRequest(h, kBigLength)})
+            .ok());
+    TransferStatusEnum first_status = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(waitForTaskTerminal(h.engine.get(), first_batch,
+                                    std::chrono::seconds(5), &first_status));
+    EXPECT_EQ(first_status, TransferStatusEnum::FAILED);
+    expectEverySliceCompletedExactlyOnce(first_batch);
+    EXPECT_EQ(session_timeout_committed_count.load(std::memory_order_acquire),
+              1);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 1);
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_terminal_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+    EXPECT_EQ(lane_terminal_socket_count.load(std::memory_order_acquire), 0);
+    ASSERT_TRUE(h.engine->freeBatchID(first_batch).ok());
+    EXPECT_EQ(fake_peer.acceptedCount(), 1);
+    EXPECT_EQ(session_terminal_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 1);
+}
+
+TEST(TcpWriteVisibilityTest, ProgressBeforeDeadlineMakesOldTimerStale) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "30");
+    ScopedSessionProgressHooks session_hooks(
+        kSessionReadBodySuccess, kSessionReplayPreviousTimeoutAfterProgress);
+
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18054", 8ull << 20);
+    ASSERT_TRUE(h.ok);
+
+    char* source = static_cast<char*>(h.pool);
+    char* destination = source + kRegionAlign;
+    for (size_t i = 0; i < kSmallLength; ++i)
+        source[i] = static_cast<char>(i * 29 + 11);
+
+    EXPECT_EQ(
+        runOne(h.engine.get(), makeReadRequest(h, destination, kSmallLength)),
+        TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(memcmp(destination, source, kSmallLength), 0);
+    EXPECT_EQ(session_timeout_committed_count.load(std::memory_order_acquire),
+              0);
+    EXPECT_GE(session_timeout_stale_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(session_terminal_count.load(std::memory_order_acquire), 1);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 0);
+}
+
+TEST(TcpWriteVisibilityTest,
+     ProgressTimeoutWaitsForOutstandingWriteBeforeTerminal) {
+    constexpr size_t kRequestSize = 64ull << 20;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "1");
+    ScopedSessionProgressHooks session_hooks(
+        /*target_event=*/0, kSessionProgressNoAction,
+        /*block_timeout_commit=*/true);
+    PayloadStallingWriteServer fake_peer(/*payload_prefix_to_read=*/0);
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18055", kRequestSize);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto batch_id = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(batch_id, {makeWriteRequest(h, kRequestSize)})
+            .ok());
+    ASSERT_TRUE(fake_peer.waitForHeader(std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return session_timeout_commit_entered.load(
+                std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+    EXPECT_TRUE(session_timeout_commit_had_write_in_flight.load(
+        std::memory_order_acquire));
+
+    TransferStatus status;
+    status.s = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(h.engine->getTransferStatus(batch_id, 0, status).ok());
+    EXPECT_EQ(status.s, TransferStatusEnum::WAITING);
+    EXPECT_EQ(session_terminal_count.load(std::memory_order_acquire), 0);
+
+    session_hooks.releaseTimeoutCommit();
+    TransferStatusEnum final_status = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(waitForTaskTerminal(h.engine.get(), batch_id,
+                                    std::chrono::seconds(5), &final_status));
+    EXPECT_EQ(final_status, TransferStatusEnum::FAILED);
+    expectEverySliceCompletedExactlyOnce(batch_id);
+    EXPECT_EQ(session_dirty_terminal_count.load(std::memory_order_acquire), 1);
+    ASSERT_TRUE(h.engine->freeBatchID(batch_id).ok());
+    fake_peer.release();
+}
+
+TEST(TcpWriteVisibilityTest, WritePayloadNoProgressFailsWithinBoundedDeadline) {
+    constexpr size_t kRequestSize = 64ull << 20;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "1");
+    ScopedLaneHooks hooks;
+    PayloadStallingWriteServer fake_peer(/*payload_prefix_to_read=*/0);
+    ASSERT_TRUE(fake_peer.ok());
+
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18044", kRequestSize);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
+
+    const auto batch_id = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(batch_id, {makeWriteRequest(h, kRequestSize)})
+            .ok());
+    ASSERT_TRUE(fake_peer.waitForHeader(std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+
+    TransferStatusEnum status = TransferStatusEnum::WAITING;
+    const bool terminal = waitForTaskTerminal(
+        h.engine.get(), batch_id, std::chrono::milliseconds(1500), &status);
+    EXPECT_TRUE(terminal)
+        << "RED: a connected WRITE that makes no payload progress has no "
+           "general progress deadline";
+    EXPECT_EQ(status, TransferStatusEnum::FAILED);
+
+    fake_peer.release();
+    if (waitForTaskTerminal(h.engine.get(), batch_id,
+                            std::chrono::seconds(5))) {
+        expectEverySliceCompletedExactlyOnce(batch_id);
+        EXPECT_TRUE(h.engine->freeBatchID(batch_id).ok());
+    } else {
+        h.engine.reset();
+        reclaimBatchDescAfterEngineShutdownForTest(batch_id);
     }
+}
+
+TEST(TcpWriteVisibilityTest,
+     WritePayloadPartialProgressThenStallFailsWithinBoundedDeadline) {
+    constexpr size_t kRequestSize = 64ull << 20;
+    constexpr size_t kObservedPayloadProgress = 128ull << 10;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar status_timeout("MC_TCP_STATUS_TIMEOUT_SEC", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "1");
+    ScopedLaneHooks hooks;
+    PayloadStallingWriteServer fake_peer(kObservedPayloadProgress);
+    ASSERT_TRUE(fake_peer.ok());
 
-    stop = true;
-    for (auto& t : noise) t.join();
+    EngineHandle h;
+    h.init(P2PHANDSHAKE, "127.0.0.2:18045", kRequestSize);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
 
-    EXPECT_EQ(torn_reads, 0u)
-        << torn_reads << "/" << kIterations
-        << " reads observed destination bytes not matching the COMPLETED "
-           "write (worst: "
-        << torn_bytes_worst << " stale bytes; first at iteration "
-        << first_bad_iter << "; noise failures: " << noise_failures.load()
-        << ")";
+    const auto batch_id = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(batch_id, {makeWriteRequest(h, kRequestSize)})
+            .ok());
+    ASSERT_TRUE(fake_peer.waitForHeader(std::chrono::seconds(5)));
+    ASSERT_TRUE(fake_peer.waitForPayloadPrefix(std::chrono::seconds(5)))
+        << "the server must observe real payload progress before stalling";
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
+
+    TransferStatusEnum status = TransferStatusEnum::WAITING;
+    const bool terminal = waitForTaskTerminal(
+        h.engine.get(), batch_id, std::chrono::milliseconds(1500), &status);
+    EXPECT_TRUE(terminal)
+        << "RED: the status-frame timer is not a payload progress deadline "
+           "after real WRITE progress stops";
+    EXPECT_EQ(status, TransferStatusEnum::FAILED);
+
+    fake_peer.release();
+    if (waitForTaskTerminal(h.engine.get(), batch_id,
+                            std::chrono::seconds(5))) {
+        expectEverySliceCompletedExactlyOnce(batch_id);
+        EXPECT_TRUE(h.engine->freeBatchID(batch_id).ok());
+    } else {
+        h.engine.reset();
+        reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+    }
 }
 
-// A server-side rejection must surface as FAILED, not silent success: under
-// v1 framing a single-chunk WRITE to an unregistered address reported
-// COMPLETED because the protocol had no channel for the server to say no.
-TEST(TcpWriteVisibilityTest, RejectedWriteMustFail) {
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+TEST(TcpWriteVisibilityTest, ShutdownWithArmedProgressDeadlineCompletesOnce) {
+    constexpr size_t kRequestSize = 64ull << 20;
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    ScopedEnvVar progress_timeout("MC_TCP_PROGRESS_TIMEOUT_SEC", "10");
+    ScopedLaneHooks hooks;
+    PayloadStallingWriteServer fake_peer(/*payload_prefix_to_read=*/0);
+    ASSERT_TRUE(fake_peer.ok());
+
     EngineHandle h;
-    h.init(metadata_server, "127.0.0.2:17902", 8ull << 20);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    h.init(P2PHANDSHAKE, "127.0.0.2:18051", kRequestSize);
+    ASSERT_TRUE(h.ok);
+    pointTcpSegmentAt(h, fake_peer.port());
 
-    char* src = (char*)h.pool;
-    memset(src, 0xAB, kSmallLength);
-    TransferRequest w;
-    w.opcode = TransferRequest::WRITE;
-    w.length = kSmallLength;
-    w.source = src;
-    w.target_id = h.segment_id;
-    // One page past the registered pool: the server rejects it in address
-    // validation.
-    w.target_offset = h.remote_base + (8ull << 20) + 4096;
-    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
+    const auto batch_id = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(batch_id, {makeWriteRequest(h, kRequestSize)})
+            .ok());
+    ASSERT_TRUE(fake_peer.waitForHeader(std::chrono::seconds(5)));
+    ASSERT_TRUE(waitForPredicate(
+        [] { return lane_busy_count.load(std::memory_order_acquire) >= 1; },
+        std::chrono::seconds(5)));
 
-    // The connection that carried the rejected request must not poison
-    // subsequent transfers.
-    w.target_offset = h.remote_base + kRegionAlign;
-    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+    auto engine = std::move(h.engine);
+    auto destruction =
+        std::async(std::launch::async,
+                   [engine = std::move(engine)]() mutable { engine.reset(); });
+    ASSERT_EQ(destruction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    destruction.get();
+
+    expectEverySliceCompletedExactlyOnceAfterShutdown(batch_id);
+    hooks.reset();
+    reclaimBatchDescAfterEngineShutdownForTest(batch_id);
+    fake_peer.release();
 }
 
-// A v2 server rejects an invalid destination immediately after the header,
-// while a large client body is still in flight. FAILED is also the caller's
-// source-buffer lifetime boundary, so it must not be published until closing
-// the socket has quiesced the outstanding async_write.
-TEST(TcpWriteVisibilityTest, LargeRejectedWriteQuiescesSourceBeforeFailure) {
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+TEST(TcpWriteVisibilityTest, EndpointRefreshRoutesNewWorkToNewTcpEndpoint) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a;
+    ReusingWriteServer endpoint_b;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
+
+    const std::string logical_peer = "127.0.0.2:18041";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
     EngineHandle h;
-    h.init(metadata_server, "127.0.0.2:17906", 8ull << 20);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    h.init(metadata_server.uri(), "127.0.0.2:18141", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_a.port()), logical_peer);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_TRUE(endpoint_a.waitForRequests(1, std::chrono::seconds(5)));
 
-    constexpr size_t kLength = 32ull << 20;  // exceed the socket buffers
-    void* source = mmap(nullptr, kLength, PROT_READ | PROT_WRITE,
-                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
-    ASSERT_NE(source, MAP_FAILED);
-    memset(source, 0x6D, kLength);
+    const auto refreshed_logical_peer =
+        publishAndRefreshTcpEndpoint(h, endpoint_b.port());
+    ASSERT_EQ(refreshed_logical_peer, logical_peer);
 
-    TransferRequest w;
-    w.opcode = TransferRequest::WRITE;
-    w.length = kLength;
-    w.source = source;
-    w.target_id = h.segment_id;
-    w.target_offset = h.remote_base + (8ull << 20) + 4096;
+    EXPECT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    EXPECT_TRUE(endpoint_b.waitForRequests(1, std::chrono::seconds(5)))
+        << "new work did not observe endpoint B after explicit metadata "
+           "refresh";
+    EXPECT_EQ(endpoint_a.acceptedCount(), 1)
+        << "endpoint visibility is a separate observation from old-group "
+           "retirement";
+}
 
-    auto start = std::chrono::steady_clock::now();
-    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
-    EXPECT_LT(std::chrono::steady_clock::now() - start,
-              std::chrono::seconds(3));
+TEST(TcpWriteVisibilityTest,
+     ConcurrentEndpointRefreshNeverCombinesHostAndPortSnapshots) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a(false, "127.0.0.1");
+    ReusingWriteServer endpoint_b(false, "127.0.0.2");
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
 
-    ASSERT_EQ(mprotect(source, kLength, PROT_NONE), 0);
-    std::this_thread::sleep_for(std::chrono::milliseconds(50));
-    ASSERT_EQ(mprotect(source, kLength, PROT_READ | PROT_WRITE), 0);
-    ASSERT_EQ(munmap(source, kLength), 0);
+    const std::string logical_peer = "127.0.0.2:18051";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
+    EngineHandle h;
+    h.init(metadata_server.uri(), "127.0.0.2:18151", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    ASSERT_TRUE(
+        metadata_server.rewriteStoredRpcHost(logical_peer, "127.0.0.1"));
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, h.segment_id, endpoint_a.port(),
+                                           "127.0.0.1"),
+              logical_peer);
 
-    // The rejected exchange is unclean, so the next request must use a fresh
-    // connection rather than inheriting the server's mid-session state.
-    char* small_source = static_cast<char*>(h.pool);
-    memset(small_source, 0x42, kSmallLength);
-    w.length = kSmallLength;
-    w.source = small_source;
-    w.target_offset = h.remote_base + kRegionAlign;
-    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+    // Declare the future first so the hook's destructor releases a blocked
+    // submitter before the future is destroyed on any fatal assertion path.
+    std::future<TransferStatusEnum> transfer;
+    ScopedStartTransferMetadataHook hook;
+    transfer = std::async(std::launch::async, [&] {
+        return runOne(h.engine.get(), makeWriteRequest(h, 1));
+    });
+    ASSERT_TRUE(waitForPredicate(
+        [] {
+            return start_transfer_metadata_hook_entered.load(
+                std::memory_order_acquire);
+        },
+        std::chrono::seconds(5)));
+
+    auto metadata = h.engine->getMetadata();
+    auto old_snapshot = metadata->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(old_snapshot, nullptr);
+    auto authoritative = *old_snapshot;
+    authoritative.tcp_data_host = "127.0.0.2";
+    authoritative.tcp_data_port = endpoint_b.port();
+    ASSERT_TRUE(
+        metadata_server.rewriteStoredRpcHost(logical_peer, "127.0.0.2"));
+    ASSERT_EQ(metadata->updateSegmentDesc(logical_peer, authoritative), 0);
+    ASSERT_EQ(h.engine->syncSegmentCache(logical_peer), 0);
+
+    hook.release();
+    ASSERT_EQ(transfer.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    EXPECT_EQ(transfer.get(), TransferStatusEnum::COMPLETED)
+        << "a transfer that captured endpoint A before refresh must not use "
+           "the new host with endpoint A's old port";
+    EXPECT_TRUE(endpoint_a.waitForRequests(1, std::chrono::seconds(5)));
+
+    hook.reset();
+    EXPECT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    EXPECT_TRUE(endpoint_b.waitForRequests(1, std::chrono::seconds(5)));
+    EXPECT_EQ(endpoint_a.acceptedCount(), 1);
+    EXPECT_EQ(endpoint_b.acceptedCount(), 1);
 }
 
-// v2 READ round-trip: exercises the status-frame-then-data framing in both
-// directions, including content integrity and a rejected READ surfacing as
-// FAILED (v1 could only signal that by dropping the connection).
-TEST(TcpWriteVisibilityTest, V2ReadRoundTripAndRejectedRead) {
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+TEST(TcpWriteVisibilityTest, EndpointRefreshRetiresOldTcpGroup) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a;
+    ReusingWriteServer endpoint_b;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
+
+    const std::string logical_peer = "127.0.0.2:18042";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
     EngineHandle h;
-    h.init(metadata_server, "127.0.0.2:17904", 16ull << 20);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    h.init(metadata_server.uri(), "127.0.0.2:18142", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_a.port()), logical_peer);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_TRUE(endpoint_a.waitForRequests(1, std::chrono::seconds(5)));
+    ASSERT_EQ(endpoint_a.activeAcceptedCount(), 1);
 
-    char* base = (char*)h.pool;
-    char* src = base + kRegionAlign;
-    char* dst = base + 2 * kRegionAlign;
-    for (size_t i = 0; i < kBigLength; ++i) src[i] = (char)(i * 131 + 7);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_b.port()), logical_peer);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_TRUE(endpoint_b.waitForRequests(1, std::chrono::seconds(5)));
 
-    TransferRequest w;
-    w.opcode = TransferRequest::WRITE;
-    w.length = kBigLength;
-    w.source = src;
-    w.target_id = h.segment_id;
-    w.target_offset = h.remote_base;
-    ASSERT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+    EXPECT_TRUE(
+        endpoint_a.waitForNoActiveConnections(std::chrono::milliseconds(500)))
+        << "RED: endpoint B is visible, but the idle group/socket for old "
+           "endpoint A is never retired";
+}
 
-    TransferRequest r;
-    r.opcode = TransferRequest::READ;
-    r.length = kBigLength;
-    r.source = dst;
-    r.target_id = h.segment_id;
-    r.target_offset = h.remote_base;
-    ASSERT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
-    // v2 WRITE completion means the destination was already applied, so the
-    // read-back must match immediately — no drain wait.
-    EXPECT_EQ(memcmp(dst, src, kBigLength), 0);
+TEST(TcpWriteVisibilityTest, SharedEndpointOnePeerMovesDoesNotRetireOtherPeer) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a;
+    ReusingWriteServer endpoint_b;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
 
-    // A READ of an unregistered range must fail via the error status frame.
-    r.target_offset = h.remote_base + (16ull << 20) + 4096;
-    EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::FAILED);
+    const std::string logical_peer_x = "127.0.0.2:18046";
+    const std::string logical_peer_y = "127.0.0.2:18047";
+    EngineHandle target_x;
+    target_x.init(metadata_server.uri(), logical_peer_x, 64 * 1024);
+    ASSERT_TRUE(target_x.ok);
+    EngineHandle target_y;
+    target_y.init(metadata_server.uri(), logical_peer_y, 64 * 1024);
+    ASSERT_TRUE(target_y.ok);
+    EngineHandle h;
+    h.init(metadata_server.uri(), "127.0.0.2:18146", 64 * 1024, logical_peer_x);
+    ASSERT_TRUE(h.ok);
+    const auto segment_y = h.engine->openSegment(logical_peer_y);
+    ASSERT_NE(h.engine->getMetadata()->getSegmentDescByID(segment_y), nullptr);
 
-    // And the pool must still be usable afterwards.
-    r.target_offset = h.remote_base;
-    EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
-}
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, h.segment_id, endpoint_a.port()),
+              logical_peer_x);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, segment_y, endpoint_a.port()),
+              logical_peer_y);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    auto peer_y_request = makeWriteRequest(h, 1);
+    peer_y_request.target_id = segment_y;
+    ASSERT_EQ(runOne(h.engine.get(), peer_y_request),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_TRUE(endpoint_a.waitForRequests(2, std::chrono::seconds(5)));
+    ASSERT_EQ(endpoint_a.acceptedCount(), 1);
 
-// Mixed-version quadrant: a legacy (v1) initiator against the v2 server —
-// selected via the MC_TCP_PROTO=1 escape hatch — still transfers data
-// correctly (with the old weaker completion semantics).
-TEST(TcpWriteVisibilityTest, LegacyInitiatorInteropWithV2Server) {
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
-    // Set the process environment before the engine starts any threads, and
-    // restore it only after those threads have stopped. POSIX does not require
-    // setenv()/unsetenv() to synchronize with concurrent getenv() calls.
-    ScopedEnvVar legacy_proto("MC_TCP_PROTO", "1");
-    {
-        EngineHandle h;
-        h.init(metadata_server, "127.0.0.2:17903", 16ull << 20);
-        ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, h.segment_id, endpoint_b.port()),
+              logical_peer_x);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    ASSERT_TRUE(endpoint_b.waitForRequests(1, std::chrono::seconds(5)));
 
-        char* base = (char*)h.pool;
-        char* src = base + kRegionAlign;
-        memset(src, 0x3C, kSmallLength);
-        TransferRequest w;
-        w.opcode = TransferRequest::WRITE;
-        w.length = kSmallLength;
-        w.source = src;
-        w.target_id = h.segment_id;
-        w.target_offset = h.remote_base;
-        EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(endpoint_a.activeAcceptedCount(), 1)
+        << "moving peer X must not retire endpoint A while peer Y still maps "
+           "to it";
+    ASSERT_EQ(runOne(h.engine.get(), peer_y_request),
+              TransferStatusEnum::COMPLETED);
+    EXPECT_TRUE(endpoint_a.waitForRequests(3, std::chrono::seconds(5)));
+    EXPECT_EQ(endpoint_a.acceptedCount(), 1)
+        << "peer Y should retain and reuse the shared endpoint-A group";
+}
 
-        // v1 completion does not guarantee destination visibility; wait for
-        // the server drain before checking content.
-        auto deadline =
-            std::chrono::steady_clock::now() + std::chrono::seconds(10);
-        while (memcmp(base, src, kSmallLength) != 0 &&
-               std::chrono::steady_clock::now() < deadline)
-            std::this_thread::yield();
-        EXPECT_EQ(memcmp(base, src, kSmallLength), 0);
+TEST(TcpWriteVisibilityTest, EndpointChangesAtoBtoCWithoutLeakingOldGroups) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a;
+    ReusingWriteServer endpoint_b;
+    ReusingWriteServer endpoint_c;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
+    ASSERT_TRUE(endpoint_c.ok());
 
-        // Read-back over the transport under v1 framing.
-        char* dst = base + 2 * kRegionAlign;
-        TransferRequest r;
-        r.opcode = TransferRequest::READ;
-        r.length = kSmallLength;
-        r.source = dst;
-        r.target_id = h.segment_id;
-        r.target_offset = h.remote_base;
-        EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::COMPLETED);
-        EXPECT_EQ(memcmp(dst, src, kSmallLength), 0);
+    const std::string logical_peer = "127.0.0.2:18048";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
+    EngineHandle h;
+    h.init(metadata_server.uri(), "127.0.0.2:18148", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+
+    for (const auto* endpoint : {&endpoint_a, &endpoint_b, &endpoint_c}) {
+        ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint->port()),
+                  logical_peer);
+        ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+                  TransferStatusEnum::COMPLETED);
+        ASSERT_TRUE(endpoint->waitForRequests(1, std::chrono::seconds(5)));
     }
+
+    EXPECT_TRUE(endpoint_a.waitForNoActiveConnections(std::chrono::seconds(5)));
+    EXPECT_TRUE(endpoint_b.waitForNoActiveConnections(std::chrono::seconds(5)));
+    EXPECT_EQ(endpoint_c.activeAcceptedCount(), 1);
+    EXPECT_EQ(endpoint_a.acceptedCount(), 1);
+    EXPECT_EQ(endpoint_b.acceptedCount(), 1);
+    EXPECT_EQ(endpoint_c.acceptedCount(), 1);
 }
 
-// A cached v2 descriptor can briefly outlive a server downgrade/restart. A
-// legacy server interprets the flagged WRITE opcode as READ and sends payload
-// while the client sends its body. The concurrent status read must break this
-// full-duplex deadlock, and FAILED must not become visible until asio has
-// released the caller-owned source buffer.
-TEST(TcpWriteVisibilityTest,
-     StaleV2DescriptorAgainstLegacyServerQuiescesWriteBeforeFailure) {
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
+TEST(TcpWriteVisibilityTest, EndpointRetirementRacesWithBusyCompletion) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a(/*hold_first_ack=*/true);
+    ReusingWriteServer endpoint_b;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
+
+    const std::string logical_peer = "127.0.0.2:18049";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
     EngineHandle h;
-    h.init(metadata_server, "127.0.0.2:17905", 8ull << 20);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+    h.init(metadata_server.uri(), "127.0.0.2:18149", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_a.port()), logical_peer);
 
-    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
-    ASSERT_NE(desc, nullptr);
+    const auto busy_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(busy_batch, {makeWriteRequest(h, 1)}).ok());
+    ASSERT_TRUE(endpoint_a.waitForFirstRequest(std::chrono::seconds(5)));
 
-    LegacyReadServer legacy_server;
-    ASSERT_TRUE(legacy_server.ok());
-    desc->tcp_data_port = legacy_server.port();
-    desc->tcp_proto_version = 2;  // deliberately stale capability advertisement
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_b.port()), logical_peer);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(endpoint_a.activeAcceptedCount(), 1)
+        << "a retiring group must retain a BUSY session until completion";
 
-    constexpr size_t kLength = 32ull << 20;  // exceed both socket buffers
-    void* source = mmap(nullptr, kLength, PROT_READ | PROT_WRITE,
-                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
-    ASSERT_NE(source, MAP_FAILED);
-    memset(source, 0x5C, kLength);
+    endpoint_a.releaseFirstAck();
+    TransferStatusEnum status = TransferStatusEnum::WAITING;
+    ASSERT_TRUE(waitForTaskTerminal(h.engine.get(), busy_batch,
+                                    std::chrono::seconds(5), &status));
+    EXPECT_EQ(status, TransferStatusEnum::COMPLETED);
+    expectEverySliceCompletedExactlyOnce(busy_batch);
+    EXPECT_TRUE(endpoint_a.waitForNoActiveConnections(std::chrono::seconds(5)));
+    EXPECT_TRUE(h.engine->freeBatchID(busy_batch).ok());
+}
 
-    TransferRequest w;
-    w.opcode = TransferRequest::WRITE;
-    w.length = kLength;
-    w.source = source;
-    w.target_id = h.segment_id;
-    w.target_offset = h.remote_base;
+TEST(TcpWriteVisibilityTest, EndpointRetirementRacesWithShutdown) {
+    ScopedEnvVar lanes("MC_TCP_LANES_PER_PEER", "1");
+    LocalHttpMetadataServer metadata_server;
+    ReusingWriteServer endpoint_a(/*hold_first_ack=*/true);
+    ReusingWriteServer endpoint_b;
+    ASSERT_TRUE(metadata_server.ok());
+    ASSERT_TRUE(endpoint_a.ok());
+    ASSERT_TRUE(endpoint_b.ok());
 
-    auto start = std::chrono::steady_clock::now();
-    EXPECT_EQ(runOne(h.engine.get(), w), TransferStatusEnum::FAILED);
-    auto elapsed = std::chrono::steady_clock::now() - start;
-    // The fake legacy peer waits up to 8s for the old mutual-write deadlock.
-    // Leave generous CI headroom while still proving the concurrent-read path.
-    EXPECT_LT(elapsed, std::chrono::seconds(3));
+    const std::string logical_peer = "127.0.0.2:18050";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
+    EngineHandle h;
+    h.init(metadata_server.uri(), "127.0.0.2:18150", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_a.port()), logical_peer);
 
-    // Terminal status is the source-buffer lifetime boundary. Protecting the
-    // pages immediately after FAILED would crash if an async_write still owned
-    // them and attempted further progress.
-    ASSERT_EQ(mprotect(source, kLength, PROT_NONE), 0);
-    std::this_thread::sleep_for(std::chrono::milliseconds(50));
-    ASSERT_EQ(mprotect(source, kLength, PROT_READ | PROT_WRITE), 0);
-    ASSERT_EQ(munmap(source, kLength), 0);
+    const auto busy_batch = h.engine->allocateBatchID(1);
+    ASSERT_TRUE(
+        h.engine->submitTransfer(busy_batch, {makeWriteRequest(h, 1)}).ok());
+    ASSERT_TRUE(endpoint_a.waitForFirstRequest(std::chrono::seconds(5)));
+    ASSERT_EQ(publishAndRefreshTcpEndpoint(h, endpoint_b.port()), logical_peer);
+    ASSERT_EQ(runOne(h.engine.get(), makeWriteRequest(h, 1)),
+              TransferStatusEnum::COMPLETED);
 
-    legacy_server.join();
-    EXPECT_TRUE(legacy_server.sawFlaggedWrite());
+    auto engine = std::move(h.engine);
+    auto destruction =
+        std::async(std::launch::async,
+                   [engine = std::move(engine)]() mutable { engine.reset(); });
+    ASSERT_EQ(destruction.wait_for(std::chrono::seconds(5)),
+              std::future_status::ready);
+    destruction.get();
+    endpoint_a.releaseFirstAck();
+
+    expectEverySliceCompletedExactlyOnceAfterShutdown(busy_batch);
+    reclaimBatchDescAfterEngineShutdownForTest(busy_batch);
 }
 
-// A stale v2 descriptor can also point at a legacy server with a request
-// SHORTER than a status frame (1-7 bytes). The v1 peer treats the flagged
-// opcode as READ, streams fewer than 8 "payload" bytes, and then keeps the
-// connection open waiting for the next header — no EOF ever arrives, and for
-// WRITE it is symmetrically stuck parsing our body bytes as a partial
-// header. Without a status-frame deadline both directions wait forever;
-// with it they must fail, and only after actually waiting the deadline out
-// (an early failure would mean something else broke).
-TEST(TcpWriteVisibilityTest, StaleV2DescriptorShortRequestFailsWithinDeadline) {
-    ScopedEnvVar fast_deadline("MC_TCP_STATUS_TIMEOUT_SEC", "2");
-    const char* env = std::getenv("MC_METADATA_SERVER");
-    std::string metadata_server = env ? env : "P2PHANDSHAKE";
-    EngineHandle h;
-    h.init(metadata_server, "127.0.0.2:17906", 8ull << 20);
-    ASSERT_TRUE(h.ok) << "engine/segment setup failed";
+TEST(TcpWriteVisibilityTest, RpcMetadataRefreshInvalidatesCachedHost) {
+    LocalHttpMetadataServer metadata_server;
+    ASSERT_TRUE(metadata_server.ok());
 
-    auto desc = h.engine->getMetadata()->getSegmentDescByID(h.segment_id);
-    ASSERT_NE(desc, nullptr);
-    desc->tcp_proto_version = 2;  // deliberately stale capability advertisement
+    const std::string logical_peer = "127.0.0.2:18043";
+    EngineHandle target;
+    target.init(metadata_server.uri(), logical_peer, 64 * 1024);
+    ASSERT_TRUE(target.ok);
+    EngineHandle h;
+    h.init(metadata_server.uri(), "127.0.0.2:18143", 64 * 1024, logical_peer);
+    ASSERT_TRUE(h.ok);
+    auto metadata = h.engine->getMetadata();
+    auto segment = metadata->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(segment, nullptr);
+    ASSERT_EQ(segment->name, logical_peer);
 
-    char buf[4] = {0x11, 0x22, 0x33, 0x44};
-    for (auto opcode : {TransferRequest::WRITE, TransferRequest::READ}) {
-        // One server per direction: the previous connection was (correctly)
-        // discarded rather than re-pooled, so each request dials anew.
-        LegacyReadServer legacy_server(/*keep_open=*/true);
-        ASSERT_TRUE(legacy_server.ok());
-        desc->tcp_data_port = legacy_server.port();
+    TransferMetadata::RpcMetaDesc initial_rpc;
+    ASSERT_EQ(metadata->getRpcMetaEntry(logical_peer, initial_rpc), 0);
+    const std::string endpoint_b_host = "198.51.100.29";
+    ASSERT_NE(initial_rpc.ip_or_host_name, endpoint_b_host);
+    ASSERT_TRUE(
+        metadata_server.rewriteStoredRpcHost(logical_peer, endpoint_b_host));
 
-        TransferRequest r;
-        r.opcode = opcode;
-        r.length = sizeof(buf);
-        r.source = buf;
-        r.target_id = h.segment_id;
-        r.target_offset = h.remote_base;
+    auto authoritative = *segment;
+    // Model a peer that predates tcp_data_host publication. Refresh must
+    // resolve the authoritative RPC host once and freeze it into the local
+    // SegmentDesc snapshot before startTransfer can consume it.
+    authoritative.tcp_data_host.clear();
+    authoritative.tcp_data_port =
+        segment->tcp_data_port == 65534 ? 65533 : 65534;
+    ASSERT_EQ(metadata->updateSegmentDesc(logical_peer, authoritative), 0);
+    ASSERT_EQ(h.engine->syncSegmentCache(logical_peer), 0);
+    auto refreshed_segment = metadata->getSegmentDescByID(h.segment_id);
+    ASSERT_NE(refreshed_segment, nullptr);
+    ASSERT_EQ(refreshed_segment->tcp_data_host, endpoint_b_host);
+    ASSERT_EQ(refreshed_segment->tcp_data_port, authoritative.tcp_data_port);
 
-        auto start = std::chrono::steady_clock::now();
-        EXPECT_EQ(runOne(h.engine.get(), r), TransferStatusEnum::FAILED)
-            << "opcode " << static_cast<int>(opcode);
-        auto elapsed = std::chrono::steady_clock::now() - start;
-        EXPECT_GE(elapsed, std::chrono::seconds(1))
-            << "failure arrived before the status deadline could have fired; "
-               "the wrong path failed (opcode "
-            << static_cast<int>(opcode) << ")";
-        EXPECT_LT(elapsed, std::chrono::seconds(6))
-            << "deadline did not bound the stale-descriptor wait (opcode "
-            << static_cast<int>(opcode) << ")";
-        legacy_server.join();
-    }
+    TransferMetadata::RpcMetaDesc refreshed_rpc;
+    ASSERT_EQ(metadata->getRpcMetaEntry(logical_peer, refreshed_rpc), 0);
+    EXPECT_EQ(refreshed_rpc.ip_or_host_name, endpoint_b_host)
+        << "RED: segment metadata refreshed, but getRpcMetaEntry() retained "
+           "the independently cached host "
+        << initial_rpc.ip_or_host_name;
 }
+
+#endif
diff --git a/mooncake-transfer-engine/tests/transfer_metadata_test.cpp b/mooncake-transfer-engine/tests/transfer_metadata_test.cpp
index a890489a3e..1002f3d9df 100644
--- a/mooncake-transfer-engine/tests/transfer_metadata_test.cpp
+++ b/mooncake-transfer-engine/tests/transfer_metadata_test.cpp
@@ -1,3 +1,5 @@
+#include <map>
+#include <memory>
 // Copyright 2024 KVCache.AI
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -22,9 +24,15 @@
 #include <sys/time.h>
 #include <unistd.h>
 
+#include <algorithm>
+#include <atomic>
+#include <cctype>
 #include <chrono>
 #include <cstdlib>
+#include <mutex>
+#include <sstream>
 #include <thread>
+#include <unordered_map>
 
 #include "common.h"
 #include "config.h"
@@ -42,7 +50,7 @@ class TransferMetadataTest : public ::testing::Test {
         google::InitGoogleLogging("TransferMetadataTest");
         FLAGS_logtostderr = 1;  // output to stdout
 
-        const char* env = std::getenv("MC_METADATA_SERVER");
+        const char *env = std::getenv("MC_METADATA_SERVER");
         if (env)
             metadata_server = env;
         else
@@ -104,11 +112,11 @@ TEST_F(TransferMetadataTest, LocalMemoryBufferTest) {
         ASSERT_EQ(re, 0);
     }
     addr = 1000;
-    re = metadata_client->removeLocalMemoryBuffer((void*)addr, false);
+    re = metadata_client->removeLocalMemoryBuffer((void *)addr, false);
     ASSERT_EQ(re, ERR_ADDRESS_NOT_REGISTERED);
     for (int i = 9; i > 0; --i) {
         addr = i * 2048;
-        re = metadata_client->removeLocalMemoryBuffer((void*)addr, false);
+        re = metadata_client->removeLocalMemoryBuffer((void *)addr, false);
         ASSERT_EQ(re, 0);
     }
     re = metadata_client->removeLocalSegment("test_local_segment");
@@ -202,6 +210,189 @@ TEST_F(TransferMetadataTest, RpcMetaEntryTest) {
 
 namespace {
 
+#ifdef USE_HTTP
+class LocalHttpMetadataServer {
+   public:
+    LocalHttpMetadataServer() {
+        listen_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+        if (listen_fd_ < 0) return;
+
+        int one = 1;
+        if (setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one,
+                       sizeof(one)) != 0)
+            return;
+
+        sockaddr_in addr{};
+        addr.sin_family = AF_INET;
+        addr.sin_port = 0;
+        addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        if (bind(listen_fd_, reinterpret_cast<sockaddr*>(&addr),
+                 sizeof(addr)) != 0)
+            return;
+        if (listen(listen_fd_, 16) != 0) return;
+
+        socklen_t len = sizeof(addr);
+        if (getsockname(listen_fd_, reinterpret_cast<sockaddr*>(&addr), &len) !=
+            0)
+            return;
+        port_ = ntohs(addr.sin_port);
+        ok_ = true;
+        thread_ = std::thread([this] { serve(); });
+    }
+
+    ~LocalHttpMetadataServer() {
+        stopped_.store(true, std::memory_order_release);
+        if (listen_fd_ >= 0) (void)shutdown(listen_fd_, SHUT_RDWR);
+        if (thread_.joinable()) thread_.join();
+        if (listen_fd_ >= 0) close(listen_fd_);
+    }
+
+    bool ok() const { return ok_; }
+    std::string uri() const {
+        return "http://127.0.0.1:" + std::to_string(port_) + "/metadata";
+    }
+
+   private:
+    static std::string decodeUrlComponent(const std::string& value) {
+        auto hex_digit = [](char c) -> int {
+            if (c >= '0' && c <= '9') return c - '0';
+            if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+            if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+            return -1;
+        };
+
+        std::string decoded;
+        decoded.reserve(value.size());
+        for (size_t i = 0; i < value.size(); ++i) {
+            if (value[i] == '%' && i + 2 < value.size()) {
+                const int high = hex_digit(value[i + 1]);
+                const int low = hex_digit(value[i + 2]);
+                if (high >= 0 && low >= 0) {
+                    decoded.push_back(static_cast<char>((high << 4) | low));
+                    i += 2;
+                    continue;
+                }
+            }
+            decoded.push_back(value[i] == '+' ? ' ' : value[i]);
+        }
+        return decoded;
+    }
+
+    static bool sendExact(int fd, const std::string& value) {
+        size_t offset = 0;
+        while (offset < value.size()) {
+            const ssize_t n = send(fd, value.data() + offset,
+                                   value.size() - offset, MSG_NOSIGNAL);
+            if (n <= 0) return false;
+            offset += static_cast<size_t>(n);
+        }
+        return true;
+    }
+
+    static bool readRequest(int fd, std::string& request) {
+        constexpr size_t kMaximumRequestSize = 1 << 20;
+        char buffer[4096];
+        size_t header_end = std::string::npos;
+        while ((header_end = request.find("\r\n\r\n")) == std::string::npos) {
+            const ssize_t n = recv(fd, buffer, sizeof(buffer), 0);
+            if (n <= 0) return false;
+            request.append(buffer, static_cast<size_t>(n));
+            if (request.size() > kMaximumRequestSize) return false;
+        }
+
+        size_t content_length = 0;
+        std::istringstream headers(request.substr(0, header_end));
+        std::string line;
+        std::getline(headers, line);
+        while (std::getline(headers, line)) {
+            if (!line.empty() && line.back() == '\r') line.pop_back();
+            std::string lower = line;
+            std::transform(lower.begin(), lower.end(), lower.begin(),
+                           [](unsigned char c) { return std::tolower(c); });
+            constexpr char kContentLength[] = "content-length:";
+            if (lower.rfind(kContentLength, 0) == 0) {
+                content_length =
+                    std::stoull(line.substr(sizeof(kContentLength) - 1));
+            }
+        }
+
+        const size_t complete_size = header_end + 4 + content_length;
+        while (request.size() < complete_size) {
+            const ssize_t n = recv(fd, buffer, sizeof(buffer), 0);
+            if (n <= 0) return false;
+            request.append(buffer, static_cast<size_t>(n));
+            if (request.size() > kMaximumRequestSize) return false;
+        }
+        return true;
+    }
+
+    void handle(int fd) {
+        std::string request;
+        if (!readRequest(fd, request)) return;
+
+        const size_t request_line_end = request.find("\r\n");
+        if (request_line_end == std::string::npos) return;
+        std::istringstream request_line(request.substr(0, request_line_end));
+        std::string method;
+        std::string target;
+        std::string version;
+        request_line >> method >> target >> version;
+        (void)version;
+
+        const size_t key_pos = target.find("?key=");
+        if (key_pos == std::string::npos) return;
+        const std::string key = decodeUrlComponent(target.substr(key_pos + 5));
+
+        std::string body = "{}";
+        int status = 200;
+        if (method == "PUT") {
+            const size_t header_end = request.find("\r\n\r\n");
+            const std::string value = request.substr(header_end + 4);
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            values_[key] = value;
+        } else if (method == "GET") {
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            auto it = values_.find(key);
+            if (it == values_.end()) {
+                status = 404;
+            } else {
+                body = it->second;
+            }
+        } else if (method == "DELETE") {
+            std::lock_guard<std::mutex> lock(values_mutex_);
+            values_.erase(key);
+        } else {
+            status = 405;
+        }
+
+        const std::string response =
+            "HTTP/1.1 " + std::to_string(status) +
+            (status == 200 ? " OK\r\n" : " Error\r\n") +
+            "Content-Type: application/json\r\nContent-Length: " +
+            std::to_string(body.size()) + "\r\nConnection: close\r\n\r\n" +
+            body;
+        (void)sendExact(fd, response);
+    }
+
+    void serve() {
+        while (!stopped_.load(std::memory_order_acquire)) {
+            const int fd = accept(listen_fd_, nullptr, nullptr);
+            if (fd < 0) break;
+            handle(fd);
+            close(fd);
+        }
+    }
+
+    int listen_fd_ = -1;
+    uint16_t port_ = 0;
+    bool ok_ = false;
+    std::thread thread_;
+    std::atomic<bool> stopped_{false};
+    std::mutex values_mutex_;
+    std::unordered_map<std::string, std::string> values_;
+};
+#endif
+
 struct ScopedMetadataRefreshConfig {
     uint64_t old_interval_seconds;
     bool old_metacache;
@@ -232,7 +423,7 @@ TransferMetadata::BufferDesc makeRdmaBufferDesc(uint64_t addr) {
 }
 
 std::shared_ptr<TransferMetadata::SegmentDesc> makeRdmaSegmentDesc(
-    const std::string& name, uint64_t addr) {
+    const std::string &name, uint64_t addr) {
     auto segment_desc = std::make_shared<TransferMetadata::SegmentDesc>();
     segment_desc->name = name;
     segment_desc->protocol = "rdma";
@@ -285,7 +476,7 @@ TEST(TransferMetadataPollingTest, PollingRefreshesCachedRemoteSegmentDesc) {
     ASSERT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
 
     ASSERT_EQ(server.removeLocalMemoryBuffer(
-                  reinterpret_cast<void*>(kInitialAddr), false),
+                  reinterpret_cast<void *>(kInitialAddr), false),
               0);
     ASSERT_EQ(
         server.addLocalMemoryBuffer(makeRdmaBufferDesc(kUpdatedAddr), false),
@@ -306,6 +497,317 @@ TEST(TransferMetadataPollingTest, PollingRefreshesCachedRemoteSegmentDesc) {
     FAIL() << "TE metadata refresh polling did not refresh cached descriptor";
 }
 
+TEST(TransferMetadataVersionTest, SyncAcceptsNewerMetadataVersion) {
+    constexpr uint64_t kInitialAddr = 0x1000;
+    constexpr uint64_t kUpdatedAddr = 0x2000;
+
+    TransferMetadata server(P2PHANDSHAKE);
+    TransferMetadata client(P2PHANDSHAKE);
+
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_GT(port, 0);
+    const std::string remote_segment_name = "127.0.0.1:" + std::to_string(port);
+    const uint64_t base_version =
+        static_cast<uint64_t>(getCurrentTimeInNano() / 1000);
+
+    auto server_desc = makeRdmaSegmentDesc(remote_segment_name, kInitialAddr);
+    server_desc->metadata_version = base_version;
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(server_desc)),
+              0);
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = port;
+    rpc_desc.sockfd = sockfd;
+    ASSERT_EQ(server.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+
+    ASSERT_EQ(
+        client.addLocalSegment(LOCAL_SEGMENT_ID, "127.0.0.1:0",
+                               makeRdmaSegmentDesc("127.0.0.1:0", 0x3000)),
+        0);
+
+    const auto segment_id = client.getSegmentID(remote_segment_name);
+    ASSERT_NE(segment_id, static_cast<TransferMetadata::SegmentID>(-1));
+    auto cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    ASSERT_EQ(cached_desc->metadata_version, base_version);
+    ASSERT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    auto updated_desc = makeRdmaSegmentDesc(remote_segment_name, kUpdatedAddr);
+    updated_desc->metadata_version = base_version + 1;
+    ASSERT_EQ(server.removeLocalSegment(remote_segment_name), 0);
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(updated_desc)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->metadata_version, base_version + 1);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kUpdatedAddr);
+}
+
+TEST(TransferMetadataVersionTest, SyncRejectsOlderMetadataVersion) {
+    constexpr uint64_t kInitialAddr = 0x1000;
+    constexpr uint64_t kStaleAddr = 0x2000;
+
+    TransferMetadata server(P2PHANDSHAKE);
+    TransferMetadata client(P2PHANDSHAKE);
+
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_GT(port, 0);
+    const std::string remote_segment_name = "127.0.0.1:" + std::to_string(port);
+    const uint64_t base_version =
+        static_cast<uint64_t>(getCurrentTimeInNano() / 1000);
+
+    auto server_desc = makeRdmaSegmentDesc(remote_segment_name, kInitialAddr);
+    server_desc->metadata_version = base_version + 1;
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(server_desc)),
+              0);
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = port;
+    rpc_desc.sockfd = sockfd;
+    ASSERT_EQ(server.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+
+    ASSERT_EQ(
+        client.addLocalSegment(LOCAL_SEGMENT_ID, "127.0.0.1:0",
+                               makeRdmaSegmentDesc("127.0.0.1:0", 0x3000)),
+        0);
+
+    const auto segment_id = client.getSegmentID(remote_segment_name);
+    ASSERT_NE(segment_id, static_cast<TransferMetadata::SegmentID>(-1));
+    auto cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    ASSERT_EQ(cached_desc->metadata_version, base_version + 1);
+    ASSERT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    auto stale_desc = makeRdmaSegmentDesc(remote_segment_name, kStaleAddr);
+    stale_desc->metadata_version = base_version;
+    ASSERT_EQ(server.removeLocalSegment(remote_segment_name), 0);
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(stale_desc)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->metadata_version, base_version + 1);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+}
+
+TEST(TransferMetadataVersionTest,
+     SyncAdvancesVersionForUnchangedDescriptorBeforeRejectingOlderUpdate) {
+    constexpr uint64_t kInitialAddr = 0x1000;
+    constexpr uint64_t kStaleAddr = 0x2000;
+
+    TransferMetadata server(P2PHANDSHAKE);
+    TransferMetadata client(P2PHANDSHAKE);
+
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_GT(port, 0);
+    const std::string remote_segment_name = "127.0.0.1:" + std::to_string(port);
+    const uint64_t base_version =
+        static_cast<uint64_t>(getCurrentTimeInNano() / 1000);
+
+    auto server_desc = makeRdmaSegmentDesc(remote_segment_name, kInitialAddr);
+    server_desc->metadata_version = base_version;
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(server_desc)),
+              0);
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = port;
+    rpc_desc.sockfd = sockfd;
+    ASSERT_EQ(server.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+
+    ASSERT_EQ(
+        client.addLocalSegment(LOCAL_SEGMENT_ID, "127.0.0.1:0",
+                               makeRdmaSegmentDesc("127.0.0.1:0", 0x3000)),
+        0);
+
+    const auto segment_id = client.getSegmentID(remote_segment_name);
+    ASSERT_NE(segment_id, static_cast<TransferMetadata::SegmentID>(-1));
+    auto cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    ASSERT_EQ(cached_desc->metadata_version, base_version);
+    ASSERT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    auto same_desc = makeRdmaSegmentDesc(remote_segment_name, kInitialAddr);
+    same_desc->metadata_version = base_version + 2;
+    ASSERT_EQ(server.removeLocalSegment(remote_segment_name), 0);
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(same_desc)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->metadata_version, base_version + 2);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    auto stale_desc = makeRdmaSegmentDesc(remote_segment_name, kStaleAddr);
+    stale_desc->metadata_version = base_version + 1;
+    ASSERT_EQ(server.removeLocalSegment(remote_segment_name), 0);
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(stale_desc)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->metadata_version, base_version + 2);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+}
+
+TEST(TransferMetadataVersionTest,
+     SyncInvalidatesRpcCacheForUnchangedNewerSegmentVersion) {
+#ifdef USE_HTTP
+    constexpr uint64_t kInitialAddr = 0x1000;
+    constexpr uint16_t kInitialRpcPort = 1234;
+    constexpr uint16_t kUpdatedRpcPort = 2345;
+
+    LocalHttpMetadataServer metadata_server;
+    ASSERT_TRUE(metadata_server.ok());
+
+    TransferMetadata publisher(metadata_server.uri());
+    TransferMetadata client(metadata_server.uri());
+
+    const std::string remote_segment_name = "rpc-refresh-segment";
+    ASSERT_EQ(publisher.updateSegmentDesc(
+                  remote_segment_name,
+                  *makeRdmaSegmentDesc(remote_segment_name, kInitialAddr)),
+              0);
+
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = kInitialRpcPort;
+    ASSERT_EQ(publisher.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+
+    const auto segment_id = client.getSegmentID(remote_segment_name);
+    ASSERT_NE(segment_id, static_cast<TransferMetadata::SegmentID>(-1));
+
+    TransferMetadata::RpcMetaDesc cached_rpc_desc;
+    ASSERT_EQ(client.getRpcMetaEntry(remote_segment_name, cached_rpc_desc), 0);
+    ASSERT_EQ(cached_rpc_desc.ip_or_host_name, "127.0.0.1");
+    ASSERT_EQ(cached_rpc_desc.rpc_port, kInitialRpcPort);
+
+    rpc_desc.ip_or_host_name = "127.0.0.2";
+    rpc_desc.rpc_port = kUpdatedRpcPort;
+    ASSERT_EQ(publisher.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+    ASSERT_EQ(publisher.updateSegmentDesc(
+                  remote_segment_name,
+                  *makeRdmaSegmentDesc(remote_segment_name, kInitialAddr)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    auto cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    ASSERT_EQ(client.getRpcMetaEntry(remote_segment_name, cached_rpc_desc), 0);
+    EXPECT_EQ(cached_rpc_desc.ip_or_host_name, "127.0.0.2");
+    EXPECT_EQ(cached_rpc_desc.rpc_port, kUpdatedRpcPort);
+#else
+    GTEST_SKIP() << "HTTP metadata storage is required";
+#endif
+}
+
+TEST(TransferMetadataVersionTest, SyncRejectsConflictingSameVersionMetadata) {
+    constexpr uint64_t kInitialAddr = 0x1000;
+    constexpr uint64_t kConflictingAddr = 0x2000;
+
+    TransferMetadata server(P2PHANDSHAKE);
+    TransferMetadata client(P2PHANDSHAKE);
+
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_GT(port, 0);
+    const std::string remote_segment_name = "127.0.0.1:" + std::to_string(port);
+    const uint64_t base_version =
+        static_cast<uint64_t>(getCurrentTimeInNano() / 1000);
+
+    auto server_desc = makeRdmaSegmentDesc(remote_segment_name, kInitialAddr);
+    server_desc->metadata_version = base_version;
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(server_desc)),
+              0);
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = port;
+    rpc_desc.sockfd = sockfd;
+    ASSERT_EQ(server.addRpcMetaEntry(remote_segment_name, rpc_desc), 0);
+
+    ASSERT_EQ(
+        client.addLocalSegment(LOCAL_SEGMENT_ID, "127.0.0.1:0",
+                               makeRdmaSegmentDesc("127.0.0.1:0", 0x3000)),
+        0);
+
+    const auto segment_id = client.getSegmentID(remote_segment_name);
+    ASSERT_NE(segment_id, static_cast<TransferMetadata::SegmentID>(-1));
+    auto cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    ASSERT_EQ(cached_desc->metadata_version, base_version);
+    ASSERT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+
+    auto conflicting_desc =
+        makeRdmaSegmentDesc(remote_segment_name, kConflictingAddr);
+    conflicting_desc->metadata_version = base_version;
+    ASSERT_EQ(server.removeLocalSegment(remote_segment_name), 0);
+    ASSERT_EQ(server.addLocalSegment(LOCAL_SEGMENT_ID, remote_segment_name,
+                                     std::move(conflicting_desc)),
+              0);
+
+    ASSERT_EQ(client.syncSegmentCache(remote_segment_name), 0);
+    cached_desc = client.getSegmentDescByID(segment_id);
+    ASSERT_NE(cached_desc, nullptr);
+    EXPECT_EQ(cached_desc->metadata_version, base_version);
+    EXPECT_EQ(cached_desc->buffers[0].addr, kInitialAddr);
+}
+
+TEST(TransferMetadataVersionTest, P2PSegmentUpdateKeepsLegacyVersionZero) {
+    TransferMetadata metadata(P2PHANDSHAKE);
+    ASSERT_EQ(
+        metadata.addLocalSegment(LOCAL_SEGMENT_ID, "127.0.0.1:0",
+                                 makeRdmaSegmentDesc("127.0.0.1:0", 0x3000)),
+        0);
+
+    ASSERT_EQ(metadata.updateLocalSegmentDesc(), 0);
+
+    auto desc = metadata.getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(desc, nullptr);
+    EXPECT_EQ(desc->metadata_version, 0U);
+
+    ASSERT_EQ(metadata.updateLocalSegmentDesc(), 0);
+    desc = metadata.getSegmentDescByID(LOCAL_SEGMENT_ID);
+    ASSERT_NE(desc, nullptr);
+    EXPECT_EQ(desc->metadata_version, 0U);
+}
+
+TEST(TransferMetadataVersionTest, P2PRpcMetaKeepsLegacyVersionZero) {
+    TransferMetadata metadata(P2PHANDSHAKE);
+
+    int sockfd = -1;
+    const uint16_t port = findAvailableTcpPort(sockfd);
+    ASSERT_GT(port, 0);
+
+    TransferMetadata::RpcMetaDesc rpc_desc;
+    rpc_desc.ip_or_host_name = "127.0.0.1";
+    rpc_desc.rpc_port = port;
+    rpc_desc.sockfd = sockfd;
+
+    ASSERT_EQ(
+        metadata.addRpcMetaEntry("127.0.0.1:" + std::to_string(port), rpc_desc),
+        0);
+
+    EXPECT_EQ(rpc_desc.metadata_version, 0U);
+    EXPECT_EQ(metadata.localRpcMeta().metadata_version, 0U);
+}
+
 TEST(TransferMetadataPublicationTest, PreservesLocalOnlyBufferWithoutRkey) {
     constexpr uint64_t kRemoteAddr = 0x1000;
     constexpr uint64_t kLocalOnlyAddr = 0x2000;
@@ -555,9 +1057,247 @@ TEST(HandshakeFrameTest, RejectsInvalidLength) {
     close(fds[1]);
 }
 
+namespace {
+
+// Hardware-free in-memory MetadataStoragePlugin. get() returns false for keys
+// absent from the store (a removed/unmounted segment) and can be made to fail
+// a bounded number of times via failNext() to reproduce a transient backend
+// blip. No RDMA/CUDA/etcd is required.
+class FakeMetadataStoragePlugin : public MetadataStoragePlugin {
+   public:
+    bool get(const std::string &key, Json::Value &value) override {
+        auto fit = forced_failures_.find(key);
+        if (fit != forced_failures_.end() && fit->second > 0) {
+            --fit->second;
+            return false;  // transient blip: the key may still be in store_
+        }
+        auto it = store_.find(key);
+        if (it == store_.end()) return false;
+        value = it->second;
+        return true;
+    }
+
+    // Error-aware variant: forced failures report kUnavailable (the key may
+    // still live in the backend), missing keys report kNotFound (the master
+    // removed them), and present keys report kFound.
+    GetResult getWithStatus(const std::string &key,
+                            Json::Value &value) override {
+        auto fit = forced_failures_.find(key);
+        if (fit != forced_failures_.end() && fit->second > 0) {
+            --fit->second;
+            return GetResult::kUnavailable;
+        }
+        auto it = store_.find(key);
+        if (it == store_.end()) return GetResult::kNotFound;
+        value = it->second;
+        return GetResult::kFound;
+    }
+    bool set(const std::string &key, const Json::Value &value) override {
+        store_[key] = value;
+        return true;
+    }
+    bool remove(const std::string &key) override {
+        store_.erase(key);
+        return true;
+    }
+
+    // Simulate the master-side cleanup of a peer's segment key (unmount or
+    // client expiry): the key vanishes from the backend, so every later
+    // get() returns false.
+    void drop(const std::string &key) { store_.erase(key); }
+
+    // Inject n transient get() failures for key without removing the key,
+    // modelling a curl timeout / etcd blip that resolves next sync cycle.
+    void failNext(const std::string &key, int n) { forced_failures_[key] = n; }
+
+   private:
+    std::map<std::string, Json::Value> store_;
+    std::map<std::string, int> forced_failures_;
+};
+
+// A backend that only implements the legacy bool get() and cannot tell a
+// missing key from a backend failure, so it inherits the default
+// getWithStatus() mapping instead of overriding it.
+class OpaqueMetadataStoragePlugin : public MetadataStoragePlugin {
+   public:
+    bool get(const std::string &key, Json::Value &value) override {
+        auto fit = forced_failures_.find(key);
+        if (fit != forced_failures_.end() && fit->second > 0) {
+            --fit->second;
+            return false;
+        }
+        auto it = store_.find(key);
+        if (it == store_.end()) return false;
+        value = it->second;
+        return true;
+    }
+    bool set(const std::string &key, const Json::Value &value) override {
+        store_[key] = value;
+        return true;
+    }
+    bool remove(const std::string &key) override {
+        store_.erase(key);
+        return true;
+    }
+    void failNext(const std::string &key, int n) { forced_failures_[key] = n; }
+
+   private:
+    std::map<std::string, Json::Value> store_;
+    std::map<std::string, int> forced_failures_;
+};
+
+// Exposes the protected storage-plugin injection seam to hardware-free tests.
+class TestableTransferMetadata : public TransferMetadata {
+   public:
+    explicit TestableTransferMetadata(
+        std::shared_ptr<MetadataStoragePlugin> storage_plugin)
+        : TransferMetadata(std::move(storage_plugin)) {}
+};
+
+}  // namespace
+
+class TransferMetadataStaleSegmentInvalidationTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        google::InitGoogleLogging(
+            "TransferMetadataStaleSegmentInvalidationTest");
+        FLAGS_logtostderr = 1;
+    }
+    void TearDown() override { google::ShutdownGoogleLogging(); }
+
+    // Publish a remote rdma segment to the fake backend and cache it locally
+    // (as a non-local id), returning the cached descriptor so callers can
+    // assert on cache state.
+    std::shared_ptr<TransferMetadata::SegmentDesc> seedRemoteSegment(
+        TransferMetadata &client, const std::string &name) {
+        auto desc = makeRdmaSegmentDesc(name, 0x1000);
+        EXPECT_EQ(client.updateSegmentDesc(name, *desc), 0);
+        EXPECT_NE(client.getSegmentID(name),
+                  static_cast<TransferMetadata::SegmentID>(-1));
+        return client.getSegmentDescByName(name);
+    }
+};
+
+// Red on master / green on branch: a cached remote segment whose backend key
+// is removed (peer unmount) is invalidated only after the consecutive-failure
+// streak reaches the threshold -- not on the first failure. On master there
+// is no invalidation branch, so the stale entry is never erased and the final
+// expectation fails.
+TEST_F(TransferMetadataStaleSegmentInvalidationTest,
+       ErasesStaleEntryAfterConsecutiveFailures) {
+    // No background refresh thread (interval == 0) with the cache-hit fast path
+    // on (metacache == true): getSegmentDescByName reflects the local cache,
+    // and we drive syncSegmentCache explicitly to count failures precisely.
+    ScopedMetadataRefreshConfig restore(0, true);
+
+    auto plugin = std::make_shared<FakeMetadataStoragePlugin>();
+    TestableTransferMetadata client(plugin);
+
+    const std::string name = "B";
+    ASSERT_TRUE(seedRemoteSegment(client, name));
+
+    // Peer B unmounts: the master removes mooncake/ram/B; every get() fails.
+    plugin->drop("mooncake/ram/B");
+
+    // First failed sync: streak is 1, below the threshold -> retain the entry,
+    // guarding against a single transient blip purging the whole cache.
+    ASSERT_EQ(client.syncSegmentCache(""), 0);
+    EXPECT_NE(client.getSegmentDescByName(name), nullptr);
+
+    // Second consecutive failed sync: streak reaches the threshold -> the
+    // stale cached entry is invalidated. Red-on-master: master never erases,
+    // so getSegmentDescByName keeps returning the cached descriptor.
+    ASSERT_EQ(client.syncSegmentCache(""), 0);
+    EXPECT_EQ(client.getSegmentDescByName(name), nullptr);
+}
+
+// Transient-failure guard: a segment that fails once and then succeeds on the
+// next cycle must NOT be invalidated -- the successful fetch resets its
+// streak. Guards against an erase-on-first-failure regression.
+TEST_F(TransferMetadataStaleSegmentInvalidationTest,
+       TransientFailureIsRetained) {
+    ScopedMetadataRefreshConfig restore(0, true);
+
+    auto plugin = std::make_shared<FakeMetadataStoragePlugin>();
+    TestableTransferMetadata client(plugin);
+
+    const std::string name = "C";
+    ASSERT_TRUE(seedRemoteSegment(client, name));
+
+    // One transient get() failure: the key still lives in the backend, so the
+    // segment is genuinely alive and must not count toward removal.
+    plugin->failNext("mooncake/ram/C", 1);
+
+    ASSERT_EQ(client.syncSegmentCache(""), 0);
+    EXPECT_NE(client.getSegmentDescByName(name), nullptr);
+
+    // Next cycle the blip clears: get() succeeds again, the streak resets to
+    // zero, and the cached entry survives.
+    ASSERT_EQ(client.syncSegmentCache(""), 0);
+    EXPECT_NE(client.getSegmentDescByName(name), nullptr);
+}
+
+// Backend-outage guard: a sustained transient failure (kUnavailable) must NOT
+// advance the invalidation streak, so the cached entry survives even after
+// many consecutive sync cycles -- only an authoritative key removal
+// (kNotFound) can invalidate. Guards against a metadata-service outage
+// purging the entire live cache.
+TEST_F(TransferMetadataStaleSegmentInvalidationTest,
+       BackendOutageDoesNotInvalidateCache) {
+    ScopedMetadataRefreshConfig restore(0, true);
+
+    auto plugin = std::make_shared<FakeMetadataStoragePlugin>();
+    TestableTransferMetadata client(plugin);
+
+    const std::string name = "D";
+    ASSERT_TRUE(seedRemoteSegment(client, name));
+
+    // Sustained backend outage: every get() fails for 5 sync cycles (well
+    // past the invalidation threshold of 2), but the key still lives in
+    // the backend -- this is kUnavailable, not kNotFound.
+    plugin->failNext("mooncake/ram/D", 5);
+
+    for (int i = 0; i < 5; ++i) {
+        ASSERT_EQ(client.syncSegmentCache(""), 0);
+        EXPECT_NE(client.getSegmentDescByName(name), nullptr)
+            << "entry purged after " << (i + 1) << " transient failures";
+    }
+
+    // Outage clears: get() succeeds again, the entry was never invalidated.
+    ASSERT_EQ(client.syncSegmentCache(""), 0);
+    EXPECT_NE(client.getSegmentDescByName(name), nullptr);
+}
+
+// Default-mapping guard: a backend that only implements the legacy bool
+// get() (no getWithStatus() override) inherits the default mapping, which
+// must fail closed -- an ambiguous false is kUnavailable, never kNotFound --
+// so a sustained failure cannot purge the cached entry. Guards against the
+// default treating an opaque backend failure as an authoritative removal.
+TEST_F(TransferMetadataStaleSegmentInvalidationTest,
+       DefaultPluginMappingFailsClosed) {
+    ScopedMetadataRefreshConfig restore(0, true);
+
+    auto plugin = std::make_shared<OpaqueMetadataStoragePlugin>();
+    TestableTransferMetadata client(plugin);
+
+    const std::string name = "E";
+    ASSERT_TRUE(seedRemoteSegment(client, name));
+
+    // Sustained failures through the inherited default path: 5 sync cycles
+    // of get() == false with no way to prove the key is gone.
+    plugin->failNext("mooncake/ram/E", 5);
+
+    for (int i = 0; i < 5; ++i) {
+        ASSERT_EQ(client.syncSegmentCache(""), 0);
+        EXPECT_NE(client.getSegmentDescByName(name), nullptr)
+            << "default mapping invalidated after " << (i + 1)
+            << " opaque failures";
+    }
+}
+
 }  // namespace mooncake
 
-int main(int argc, char** argv) {
+int main(int argc, char **argv) {
     ::testing::InitGoogleTest(&argc, argv);
     return RUN_ALL_TESTS();
 }
diff --git a/mooncake-transfer-engine/tests/transport_uint_test.cpp b/mooncake-transfer-engine/tests/transport_uint_test.cpp
index 91c3897277..c6e5683fa0 100644
--- a/mooncake-transfer-engine/tests/transport_uint_test.cpp
+++ b/mooncake-transfer-engine/tests/transport_uint_test.cpp
@@ -16,26 +16,64 @@
 #include <glog/logging.h>
 #include <gtest/gtest.h>
 #include <sys/time.h>
+#ifdef USE_TENT
+#include <infiniband/verbs.h>
+#endif
 
 #include <algorithm>
 #include <array>
+#include <chrono>
 #include <condition_variable>
 #include <cstdlib>
+#include <cstring>
 #include <fstream>
 #include <future>
 #include <iomanip>
 #include <memory>
 #include <mutex>
+#include <optional>
+#include <thread>
 #include <utility>
 
+#include "multi_transport.h"
 #include "transfer_engine.h"
 #include "transfer_engine_impl.h"
 #include "transport/transport.h"
+#ifdef USE_TENT
+#include "tent/common/config.h"
+#include "tent/runtime/transfer_engine_impl.h"
+#include "tent/transfer_engine.h"
+#endif
 
 using namespace mooncake;
 
 namespace mooncake {
 
+#ifdef USE_TENT
+class ScopedEnvVar {
+   public:
+    ScopedEnvVar(const char* name, const char* value) : name_(name) {
+        const char* old_value = std::getenv(name);
+        if (old_value) old_value_ = old_value;
+        if (value)
+            setenv(name, value, 1);
+        else
+            unsetenv(name);
+    }
+
+    ~ScopedEnvVar() {
+        if (old_value_)
+            setenv(name_.c_str(), old_value_->c_str(), 1);
+        else
+            unsetenv(name_.c_str());
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> old_value_;
+};
+#endif
+
 class TransferEngineImplTestPeer {
    public:
     static void replaceTransports(TransferEngineImpl& engine,
@@ -55,6 +93,10 @@ class TransferEngineImplTestPeer {
         }
     }
 
+    static TransferEngineImpl& implementation(TransferEngine& engine) {
+        return *engine.impl_;
+    }
+
     static AutoDiscoverConfig autoDiscoverConfig(
         const TransferEngineImpl& engine) {
         return engine.auto_discover_config_;
@@ -67,8 +109,121 @@ class TransferEngineImplTestPeer {
     static void setUseBarex(TransferEngineImpl& engine, bool use_barex) {
         engine.use_barex_ = use_barex;
     }
+
+    static size_t pendingNotifyCount(TransferEngineImpl& engine) {
+        RWSpinlock::ReadGuard guard(engine.send_notifies_lock_);
+        return engine.notifies_to_send_.size();
+    }
+
+    static Status freeBatchWithCallback(
+        TransferEngineImpl& engine, BatchID batch_id,
+        const std::function<void()>& before_delete) {
+        return engine.multi_transports_->freeBatchID(batch_id, before_delete);
+    }
+
+#ifdef USE_TENT
+    static const tent::Config* tentConfig(const TransferEngine& engine) {
+        if (!engine.impl_tent_ || !engine.impl_tent_->impl_) return nullptr;
+        return engine.impl_tent_->impl_->conf_.get();
+    }
+
+    static std::shared_ptr<tent::Config> buildTentConfig(
+        const TransferEngine& engine, const std::string& metadata,
+        const std::string& segment) {
+        return engine.buildTentConfig(metadata, segment);
+    }
+#endif
 };
 
+#ifdef USE_TENT
+class ScopedUnsetEnvVar {
+   public:
+    explicit ScopedUnsetEnvVar(const char* name) : name_(name) {
+        if (const char* old = std::getenv(name)) old_value_ = old;
+        unsetenv(name);
+    }
+
+    ~ScopedUnsetEnvVar() {
+        if (old_value_.has_value())
+            setenv(name_.c_str(), old_value_->c_str(), 1);
+    }
+
+   private:
+    std::string name_;
+    std::optional<std::string> old_value_;
+};
+
+TEST(TransferEngineTentCompatibilityTest,
+     ConstructorDeviceFilterIsForwardedToTentConfig) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    const std::vector<std::string> filter{"mlx5_0", "mlx5_2"};
+    TransferEngine engine(/*auto_discover=*/true, filter);
+    ASSERT_TRUE(engine.isUsingTent());
+
+    auto config = TransferEngineImplTestPeer::buildTentConfig(
+        engine, P2PHANDSHAKE, "local-segment");
+
+    EXPECT_EQ(config->getArray<std::string>("topology/rdma_whitelist"), filter);
+}
+
+TEST(TransferEngineTentCompatibilityTest,
+     SetterDeviceFilterIsForwardedBeforeInit) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    TransferEngine engine(/*auto_discover=*/true);
+    engine.setWhitelistFilters({"mlx5_1"});
+
+    auto config = TransferEngineImplTestPeer::buildTentConfig(
+        engine, P2PHANDSHAKE, "local-segment");
+
+    EXPECT_EQ(config->getArray<std::string>("topology/rdma_whitelist"),
+              (std::vector<std::string>{"mlx5_1"}));
+}
+
+TEST(TransferEngineTentCompatibilityTest,
+     DeviceFilterSurvivesMoveConstructionAndAssignment) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    const std::vector<std::string> filter{"mlx5_move"};
+    TransferEngine source(/*auto_discover=*/true, filter);
+    TransferEngine moved(std::move(source));
+
+    auto moved_config = TransferEngineImplTestPeer::buildTentConfig(
+        moved, P2PHANDSHAKE, "local-segment");
+    EXPECT_EQ(moved_config->getArray<std::string>("topology/rdma_whitelist"),
+              filter);
+
+    TransferEngine assigned(/*auto_discover=*/true);
+    assigned = std::move(moved);
+    auto assigned_config = TransferEngineImplTestPeer::buildTentConfig(
+        assigned, P2PHANDSHAKE, "local-segment");
+    EXPECT_EQ(assigned_config->getArray<std::string>("topology/rdma_whitelist"),
+              filter);
+}
+
+TEST(TransferEngineTentCompatibilityTest,
+     ConstructorDeviceFilterRestrictsDiscoveredTopology) {
+    int count = 0;
+    ibv_device** devices = ibv_get_device_list(&count);
+    if (!devices || count < 2) {
+        if (devices) ibv_free_device_list(devices);
+        GTEST_SKIP() << "Requires at least two RDMA devices";
+    }
+    const std::string selected = ibv_get_device_name(devices[0]);
+    ibv_free_device_list(devices);
+
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    ScopedEnvVar hostname("MOONCAKE_LOCAL_HOSTNAME", "127.0.0.1");
+    ScopedUnsetEnvVar tent_conf("MC_TENT_CONF");
+    ScopedUnsetEnvVar custom_topology("MC_CUSTOM_TOPO_JSON");
+    TransferEngine engine(/*auto_discover=*/true, {selected});
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, ""), 0);
+
+    const auto topology = engine.getLocalTopology();
+    ASSERT_NE(topology, nullptr);
+    EXPECT_EQ(topology->getHcaList(), (std::vector<std::string>{selected}));
+}
+
+#endif
+
 TEST(TransferEngineAutoDiscoverTest, SelectsEfaForEfaProtocol) {
     TransferEngineImpl engine(false);
     engine.setAutoDiscover({.enabled = true, .protocol = "efa"});
@@ -100,6 +255,78 @@ TEST(TransferEngineAutoDiscoverTest, BoolSetterPreservesDefaultSelection) {
               "rdma");
 }
 
+#ifdef USE_TENT
+// RDMA is left enabled and TCP disabled so a regression that drops forceTcp()
+// still comes up with RDMA selected. forceTcp() must flip both flags.
+constexpr const char* kTentConfPrefersRdma =
+    R"({"transports":{"tcp":{"enable":false},"rdma":{"enable":true},"shm":{"enable":false},"hp_tcp":{"enable":false},"mpcomm":{"enable":false},"io_uring":{"enable":false}},"metrics":{"enabled":false}})";
+
+void expectForcedTcpConstraint(const tent::Config& config) {
+    EXPECT_TRUE(config.get("transports/force_tcp", false));
+    EXPECT_TRUE(config.get("transports/tcp/enable", false));
+    EXPECT_FALSE(config.get("transports/rdma/enable", true));
+}
+
+TEST(TransferEngineTentCompatibilityTest, CheckSegmentStatusRejectsDeadPeer) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    ScopedEnvVar force_tcp("MC_FORCE_TCP", nullptr);
+    ScopedEnvVar hostname("MOONCAKE_LOCAL_HOSTNAME", "127.0.0.1");
+    ScopedEnvVar conf("MC_TENT_CONF", kTentConfPrefersRdma);
+
+    TransferEngine engine(true);
+    ASSERT_TRUE(engine.isUsingTent());
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "compat-stale-handle"), 0);
+
+    // Segment handles are handed out from 1 upward when a peer is opened, so a
+    // large handle that was never opened has no id->name mapping. That is the
+    // same "peer gone / handle stale" situation the eviction path must detect:
+    // probePeerAliveByID fails on it, so CheckSegmentStatus must report non-OK
+    // and let the caller close + re-open the segment. Before the fix the shim
+    // returned Status::OK() unconditionally under MC_USE_TENT, so the Python
+    // wrapper's handle_map_ never dropped a dead peer and kept reusing the same
+    // stale handle forever. Refs #3995 (P0-stale-handle).
+    EXPECT_FALSE(engine.CheckSegmentStatus(1ull << 40).ok());
+}
+
+TEST(TransferEngineTentCompatibilityTest, TcpProtocolForcesTcpTransport) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    ScopedEnvVar force_tcp("MC_FORCE_TCP", nullptr);
+    ScopedEnvVar hostname("MOONCAKE_LOCAL_HOSTNAME", "127.0.0.1");
+    ScopedEnvVar conf("MC_TENT_CONF", kTentConfPrefersRdma);
+
+    TransferEngine engine(true);
+    ASSERT_TRUE(engine.isUsingTent());
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "compat-protocol-tcp", "", 0, "tcp"),
+              0);
+    const auto* protocol_config =
+        TransferEngineImplTestPeer::tentConfig(engine);
+    ASSERT_NE(protocol_config, nullptr);
+    expectForcedTcpConstraint(*protocol_config);
+
+    std::array<char, 4096> buffer{};
+    ASSERT_EQ(engine.registerLocalMemory(buffer.data(), buffer.size()), 0);
+    EXPECT_EQ(engine.unregisterLocalMemory(buffer.data()), 0);
+}
+
+TEST(TransferEngineTentCompatibilityTest, ForceTcpEnvForcesTcpTransport) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    ScopedEnvVar force_tcp("MC_FORCE_TCP", "1");
+    ScopedEnvVar hostname("MOONCAKE_LOCAL_HOSTNAME", "127.0.0.1");
+    ScopedEnvVar conf("MC_TENT_CONF", kTentConfPrefersRdma);
+
+    TransferEngine engine(true);
+    ASSERT_TRUE(engine.isUsingTent());
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "compat-force-tcp"), 0);
+    const auto* env_config = TransferEngineImplTestPeer::tentConfig(engine);
+    ASSERT_NE(env_config, nullptr);
+    expectForcedTcpConstraint(*env_config);
+
+    std::array<char, 4096> buffer{};
+    ASSERT_EQ(engine.registerLocalMemory(buffer.data(), buffer.size()), 0);
+    EXPECT_EQ(engine.unregisterLocalMemory(buffer.data()), 0);
+}
+#endif
+
 class BatchResultTransport : public Transport {
    public:
     explicit BatchResultTransport(int unregister_result = 0)
@@ -231,6 +458,72 @@ class BlockingRegistrationTransport : public Transport {
     bool release_first_registration_ = false;
 };
 
+class PartialFailureSubmissionTransport : public BatchResultTransport {
+   public:
+    Status submitTransferTask(
+        const std::vector<TransferTask*>& tasks) override {
+        for (auto* task : tasks) {
+            request_counts.push_back(task->request_count);
+            task->slice_count = task->request_count;
+            task->success_slice_count = 1;
+            task->failed_slice_count = task->request_count - 1;
+            for (size_t i = 0; i < task->request_count; ++i) {
+                auto* slice = new Slice{};
+                slice->length = task->request[i].length;
+                slice->status = i == 0 ? Slice::SUCCESS : Slice::FAILED;
+                task->slice_list.push_back(slice);
+            }
+            if (extra_slice_) task->slice_list.push_back(new Slice{});
+            task->is_finished = true;
+        }
+        return Status::InvalidArgument("synthetic submit failure");
+    }
+
+    Status getTransferStatus(BatchID, size_t, TransferStatus& status) override {
+        status.s = TransferStatusEnum::FAILED;
+        return Status::OK();
+    }
+
+    bool supportsGroupedScatter() const override { return true; }
+
+    void addExtraSlice() { extra_slice_ = true; }
+
+    std::vector<size_t> request_counts;
+
+   private:
+    bool extra_slice_ = false;
+};
+
+class TerminalFailureTransport : public BatchResultTransport {
+   public:
+    explicit TerminalFailureTransport(bool initially_finished)
+        : initially_finished_(initially_finished) {}
+
+    Status submitTransferTask(
+        const std::vector<TransferTask*>& tasks) override {
+        tasks_ = tasks;
+        for (auto* task : tasks_) {
+            task->is_finished = initially_finished_;
+        }
+        return Status::OK();
+    }
+
+    Status getTransferStatus(BatchID, size_t, TransferStatus& status) override {
+        status.s = TransferStatusEnum::FAILED;
+        return Status::OK();
+    }
+
+    void finishTasks() {
+        for (auto* task : tasks_) {
+            task->is_finished = true;
+        }
+    }
+
+   private:
+    bool initially_finished_;
+    std::vector<TransferTask*> tasks_;
+};
+
 class TransportTest : public ::testing::Test {
    protected:
     void SetUp() override {
@@ -241,6 +534,94 @@ class TransportTest : public ::testing::Test {
     void TearDown() override { google::ShutdownGoogleLogging(); }
 };
 
+TEST_F(TransportTest, SegmentBuffersClassicSnapshotAndErrors) {
+#ifdef USE_TENT
+    ScopedUnsetEnvVar use_tent("MC_USE_TENT");
+    ScopedUnsetEnvVar use_tev1("MC_USE_TEV1");
+#endif
+    TransferEngine engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:0"), 0);
+    auto metadata = engine.getMetadata();
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "buffers";
+    desc->protocol = "rdma";
+    desc->buffers.resize(2);
+    desc->buffers[0].name = "cpu:0";
+    desc->buffers[0].addr = 8192;
+    desc->buffers[0].length = 128;
+    desc->buffers[1].name = "cpu:1";
+    desc->buffers[1].addr = 4096;
+    desc->buffers[1].length = 256;
+    metadata->addLocalSegment(LOCAL_SEGMENT_ID, "buffers", std::move(desc));
+
+    std::vector<SegmentBufferInfo> buffers{{1, 1, "old"}};
+    ASSERT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers), 0);
+    ASSERT_EQ(buffers.size(), 2);
+    EXPECT_EQ(buffers[0].addr, 8192);
+    EXPECT_EQ(buffers[0].length, 128);
+    EXPECT_EQ(buffers[0].location, "cpu:0");
+    EXPECT_EQ(buffers[1].addr, 4096);
+    EXPECT_EQ(buffers[1].length, 256);
+    EXPECT_EQ(buffers[1].location, "cpu:1");
+
+    // Replacing the descriptor leaves an already returned snapshot intact.
+    desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "buffers";
+    desc->protocol = "rdma";
+    metadata->addLocalSegment(LOCAL_SEGMENT_ID, "buffers", std::move(desc));
+    EXPECT_EQ(buffers[0].length, 128);
+    EXPECT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers), 0);
+    EXPECT_TRUE(buffers.empty());
+
+    buffers.push_back({1, 1, "old"});
+    EXPECT_EQ(engine.getSegmentBuffers(
+                  static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT), buffers),
+              ERR_METADATA);
+    EXPECT_TRUE(buffers.empty());
+
+    desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "buffers";
+    desc->protocol = "nvmeof";
+    metadata->addLocalSegment(LOCAL_SEGMENT_ID, "buffers", std::move(desc));
+    buffers.push_back({1, 1, "old"});
+    EXPECT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers),
+              ERR_NOT_IMPLEMENTED);
+    EXPECT_TRUE(buffers.empty());
+}
+
+#ifdef USE_TENT
+TEST_F(TransportTest, SegmentBuffersTentMemoryAndInvalidHandle) {
+    ScopedEnvVar use_tent("MC_USE_TENT", "1");
+    ScopedEnvVar hostname("MOONCAKE_LOCAL_HOSTNAME", "127.0.0.1");
+    ScopedEnvVar config(
+        "MC_TENT_CONF",
+        R"({"transports":{"rdma":{"enable":false},"tcp":{"enable":true},"gds":{"enable":false},"shm":{"enable":false}}})");
+    std::array<char, 128> memory{};
+    TransferEngine engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, ""), 0);
+    std::vector<SegmentBufferInfo> buffers{{1, 1, "old"}};
+    ASSERT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers), 0);
+    EXPECT_TRUE(buffers.empty());
+
+    ASSERT_EQ(engine.registerLocalMemory(memory.data(), memory.size()), 0);
+    ASSERT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers), 0);
+    ASSERT_EQ(buffers.size(), 1);
+    EXPECT_EQ(buffers[0].addr, reinterpret_cast<uint64_t>(memory.data()));
+    EXPECT_EQ(buffers[0].length, memory.size());
+    EXPECT_FALSE(buffers[0].location.empty());
+    EXPECT_EQ(engine.unregisterLocalMemory(memory.data()), 0);
+    EXPECT_EQ(buffers[0].length, memory.size());
+    EXPECT_EQ(engine.getSegmentBuffers(LOCAL_SEGMENT_ID, buffers), 0);
+    EXPECT_TRUE(buffers.empty());
+
+    buffers.push_back({1, 1, "old"});
+    EXPECT_EQ(engine.getSegmentBuffers(
+                  static_cast<SegmentHandle>(ERR_INVALID_ARGUMENT), buffers),
+              ERR_METADATA);
+    EXPECT_TRUE(buffers.empty());
+}
+#endif
+
 static int CreateTempFile() {
     char temp_filename[] = "/tmp/testfileXXXXXX";
     int fd = mkstemp(temp_filename);
@@ -607,6 +988,354 @@ TEST_F(TransportTest, RegisterLocalMemoryBatchRollsBackAttemptedTransports) {
         engine.unregisterLocalMemoryBatch({buffer.data(), buffer.data() + 1}),
         0);
 }
+
+TEST_F(TransportTest, FreeBatchClearsPendingNotify) {
+    TransferEngineImpl engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:12345"), 0);
+    auto transport = std::make_shared<TerminalFailureTransport>(true);
+    TransferEngineImplTestPeer::replaceTransports(
+        engine, {{"terminal-failure", transport}});
+
+    constexpr SegmentID kSegmentId = 12;
+    auto descriptor = std::make_shared<TransferMetadata::SegmentDesc>();
+    descriptor->name = "remote";
+    descriptor->protocol = "terminal-failure";
+    engine.getMetadata()->addLocalSegment(kSegmentId, "remote",
+                                          std::move(descriptor));
+
+    std::array<char, 1> buffer{};
+    TransferRequest request{.opcode = TransferRequest::READ,
+                            .source = buffer.data(),
+                            .target_id = kSegmentId,
+                            .target_offset = 0,
+                            .length = buffer.size()};
+    auto batch_id = engine.allocateBatchID(1);
+    ASSERT_TRUE(
+        engine
+            .submitTransferWithNotify(batch_id, {request}, {"name", "payload"})
+            .ok());
+    ASSERT_EQ(TransferEngineImplTestPeer::pendingNotifyCount(engine), 1);
+
+    TransferStatus status;
+    ASSERT_TRUE(engine.getBatchTransferStatus(batch_id, status).ok());
+    ASSERT_EQ(status.s, TransferStatusEnum::FAILED);
+    ASSERT_TRUE(engine.freeBatchID(batch_id).ok());
+    EXPECT_EQ(TransferEngineImplTestPeer::pendingNotifyCount(engine), 0);
+}
+
+TEST_F(TransportTest, BusyBatchKeepsPendingNotify) {
+    TransferEngineImpl engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:12345"), 0);
+    auto transport = std::make_shared<TerminalFailureTransport>(false);
+    TransferEngineImplTestPeer::replaceTransports(
+        engine, {{"terminal-failure", transport}});
+
+    constexpr SegmentID kSegmentId = 12;
+    auto descriptor = std::make_shared<TransferMetadata::SegmentDesc>();
+    descriptor->name = "remote";
+    descriptor->protocol = "terminal-failure";
+    engine.getMetadata()->addLocalSegment(kSegmentId, "remote",
+                                          std::move(descriptor));
+
+    std::array<char, 1> buffer{};
+    TransferRequest request{.opcode = TransferRequest::READ,
+                            .source = buffer.data(),
+                            .target_id = kSegmentId,
+                            .target_offset = 0,
+                            .length = buffer.size()};
+    auto batch_id = engine.allocateBatchID(1);
+    ASSERT_TRUE(
+        engine
+            .submitTransferWithNotify(batch_id, {request}, {"name", "payload"})
+            .ok());
+
+    EXPECT_TRUE(engine.freeBatchID(batch_id).IsBatchBusy());
+    EXPECT_EQ(TransferEngineImplTestPeer::pendingNotifyCount(engine), 1);
+
+    transport->finishTasks();
+    ASSERT_TRUE(engine.freeBatchID(batch_id).ok());
+    EXPECT_EQ(TransferEngineImplTestPeer::pendingNotifyCount(engine), 0);
+}
+
+TEST_F(TransportTest, BatchCleanupRunsAfterBeforeDeleteCallback) {
+    TransferEngineImpl engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:12345"), 0);
+
+    bool before_delete_finished = false;
+    bool cleanup_observed_callback = false;
+    struct CleanupProbe {
+        bool* before_delete_finished;
+        bool* cleanup_observed_callback;
+    };
+    CleanupProbe probe{&before_delete_finished, &cleanup_observed_callback};
+
+    auto batch_id = engine.allocateBatchID(1);
+    auto& batch = Transport::toBatchDesc(batch_id);
+    auto& task = batch.task_list.emplace_back();
+    task.is_finished = true;
+    auto* slice = new Transport::Slice();
+    slice->source_addr = &probe;
+    slice->cleanup_callback = [](Transport::Slice* released) {
+        auto* probe = static_cast<CleanupProbe*>(released->source_addr);
+        *probe->cleanup_observed_callback = *probe->before_delete_finished;
+    };
+    task.slice_list.push_back(slice);
+
+    auto status = TransferEngineImplTestPeer::freeBatchWithCallback(
+        engine, batch_id, [&] { before_delete_finished = true; });
+
+    ASSERT_TRUE(status.ok());
+    EXPECT_TRUE(cleanup_observed_callback);
+}
+
+#ifdef USE_TCP
+TEST_F(TransportTest, TcpScatterCombinesRequestsIntoOneTask) {
+    constexpr size_t kRequestCount = 256;
+    constexpr size_t kRequestBytes = 128;
+    constexpr size_t kBytes = kRequestCount * kRequestBytes;
+    // Keep request metadata and buffers alive until after engine shutdown,
+    // including when an unexpected transport failure aborts the test.
+    std::array<char, 2 * kBytes> buffer{};
+    std::vector<TransferRequest> requests;
+    requests.reserve(kRequestCount);
+    TransferEngineImpl engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:12345"), 0);
+    ASSERT_NE(engine.installTransport("tcp", nullptr), nullptr);
+    ASSERT_EQ(engine.registerLocalMemory(buffer.data(), buffer.size(), "cpu:0"),
+              0);
+    auto segment = engine.openSegment(engine.getLocalIpAndPort());
+    ASSERT_NE(engine.getMetadata()->getSegmentDescByID(segment), nullptr);
+
+    for (auto opcode : {TransferRequest::READ, TransferRequest::WRITE}) {
+        SCOPED_TRACE(opcode == TransferRequest::READ ? "READ" : "WRITE");
+        auto* source = opcode == TransferRequest::READ ? buffer.data() + kBytes
+                                                       : buffer.data();
+        auto* destination = opcode == TransferRequest::READ
+                                ? buffer.data()
+                                : buffer.data() + kBytes;
+        std::fill(buffer.begin(), buffer.end(), 0);
+        std::fill_n(source, kBytes, 37);
+        requests.clear();
+        for (size_t i = 0; i < kRequestCount; ++i) {
+            requests.push_back(TransferRequest{
+                .opcode = opcode,
+                .source = buffer.data() + i * kRequestBytes,
+                .target_id = segment,
+                .target_offset =
+                    reinterpret_cast<uint64_t>(buffer.data() + kBytes) +
+                    i * kRequestBytes,
+                .length = kRequestBytes,
+                .task_group_id = 1,
+            });
+        }
+
+        MultiTransport::ScatterSubmission submission;
+        const auto submitted = engine.submitScatter(requests, submission);
+        ASSERT_NE(submission.batch_id, INVALID_BATCH_ID);
+        const auto& tasks =
+            Transport::toBatchDesc(submission.batch_id).task_list;
+        const size_t task_count = tasks.size();
+        std::vector<size_t> request_counts;
+        for (const auto& task : tasks)
+            request_counts.push_back(task.request_count);
+
+        // Drain every actual task before asserting grouping, so the regression
+        // case (one task per request) also releases its batch normally.
+        std::vector<bool> done(task_count, false);
+        bool successful = true;
+        const auto deadline =
+            std::chrono::steady_clock::now() + std::chrono::seconds(15);
+        size_t remaining = task_count;
+        while (remaining != 0 && std::chrono::steady_clock::now() < deadline) {
+            for (size_t i = 0; i < task_count; ++i) {
+                if (done[i]) continue;
+                TransferStatus status;
+                auto result =
+                    engine.getTransferStatus(submission.batch_id, i, status);
+                if (!result.ok()) continue;
+                if (status.s == TransferStatusEnum::COMPLETED ||
+                    status.s == TransferStatusEnum::FAILED) {
+                    successful &= status.s == TransferStatusEnum::COMPLETED;
+                    done[i] = true;
+                    --remaining;
+                }
+            }
+            if (remaining != 0)
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+        }
+        ASSERT_EQ(remaining, 0u)
+            << "TCP scatter did not reach physical completion";
+        EXPECT_TRUE(engine.freeBatchID(submission.batch_id).ok());
+        EXPECT_TRUE(submitted.ok());
+        EXPECT_TRUE(successful);
+        EXPECT_EQ(memcmp(source, destination, kBytes), 0);
+        EXPECT_EQ(task_count, 1u);
+        EXPECT_EQ(request_counts, (std::vector<size_t>{kRequestCount}));
+        EXPECT_EQ(submission.task_sizes, (std::vector<size_t>{kRequestCount}));
+    }
+    EXPECT_EQ(engine.closeSegment(segment), 0);
+}
+#endif
+
+TEST_F(TransportTest, ScatterSubmitFailurePreservesCompletedFragments) {
+    TransferEngine engine(false);
+    ASSERT_EQ(engine.init(P2PHANDSHAKE, "127.0.0.1:12345"), 0);
+    auto transport = std::make_shared<PartialFailureSubmissionTransport>();
+    auto& impl = TransferEngineImplTestPeer::implementation(engine);
+    TransferEngineImplTestPeer::replaceTransports(
+        impl, {{"partial-failure", transport}});
+
+    constexpr SegmentID kSegmentId = 12;
+    auto descriptor = std::make_shared<TransferMetadata::SegmentDesc>();
+    descriptor->name = "remote";
+    descriptor->protocol = "partial-failure";
+    impl.getMetadata()->addLocalSegment(kSegmentId, "remote",
+                                        std::move(descriptor));
+    std::array<char, 2> buffer{};
+    std::array<size_t, 1> offsets{0};
+    std::array<size_t, 1> lengths{1};
+
+    auto run = [&] {
+        std::vector<bool> fragment_ok;
+        TransferEngine::ScatterTransferRange range{
+            .opcode = TransferRequest::READ,
+            .remote_segment = "remote",
+            .remote_base_offset = 0,
+            .remote_size = buffer.size(),
+            .local_buffer = buffer.data(),
+            .local_capacity = 1,
+            .local_offsets = offsets,
+            .remote_offsets = offsets,
+            .lengths = lengths,
+            .on_fragment_complete =
+                [&](size_t, const Status& status) {
+                    fragment_ok.push_back(status.ok());
+                },
+        };
+        auto operation = engine.submitScatter({range, range});
+        EXPECT_FALSE(operation.wait().ok());
+        return fragment_ok;
+    };
+
+    EXPECT_EQ(run(), (std::vector<bool>{true, false}));
+    EXPECT_EQ(transport->request_counts, (std::vector<size_t>{2}));
+    transport->addExtraSlice();
+    EXPECT_EQ(run(), (std::vector<bool>{false, false}));
+}
+
+// Model the state left by completion events explicitly so these regressions
+// also run in default builds without USE_EVENT_DRIVEN_COMPLETION.
+TEST_F(TransportTest, FailedCompletionEventDoesNotReportSuccess) {
+    std::string server_name = "localhost";
+    MultiTransport transport(nullptr, server_name);
+    Transport::BatchDesc batch{};
+    batch.id = reinterpret_cast<Transport::BatchID>(&batch);
+    batch.batch_size = 1;
+    batch.task_list.resize(1);
+    auto& task = batch.task_list.front();
+    task.batch_id = batch.id;
+    task.slice_count = 1;
+    task.failed_slice_count = 1;
+    task.is_finished = true;
+    batch.has_failure.store(true);
+    batch.is_finished.store(true);
+    ASSERT_FALSE(batch.status_cached.load());
+
+    Transport::TransferStatus status{};
+    ASSERT_TRUE(transport.getBatchTransferStatus(batch.id, status).ok());
+    EXPECT_EQ(status.s, Transport::TransferStatusEnum::FAILED);
+    EXPECT_FALSE(batch.status_cached.load());
+}
+
+TEST_F(TransportTest, SuccessfulCompletionEventPreservesTransferredBytes) {
+    std::string server_name = "localhost";
+    MultiTransport transport(nullptr, server_name);
+    Transport::BatchDesc batch{};
+    batch.id = reinterpret_cast<Transport::BatchID>(&batch);
+    batch.batch_size = 1;
+    batch.task_list.resize(1);
+    auto& task = batch.task_list.front();
+    task.batch_id = batch.id;
+    task.slice_count = 1;
+    task.transferred_bytes = 65536;
+    task.success_slice_count = 1;
+    task.is_finished = true;
+    batch.is_finished.store(true);
+    ASSERT_FALSE(batch.has_failure.load());
+    ASSERT_FALSE(batch.status_cached.load());
+    ASSERT_EQ(batch.finished_transfer_bytes.load(), 0);
+
+    Transport::TransferStatus status{};
+    ASSERT_TRUE(transport.getBatchTransferStatus(batch.id, status).ok());
+    EXPECT_EQ(status.s, Transport::TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, 65536);
+}
+
+TEST_F(TransportTest, RepeatedBatchQueryPreservesAggregatedBytes) {
+    std::string server_name = "localhost";
+    MultiTransport transport(nullptr, server_name);
+    Transport::BatchDesc batch{};
+    batch.id = reinterpret_cast<Transport::BatchID>(&batch);
+    batch.batch_size = 2;
+    batch.task_list.resize(2);
+    const std::array<uint64_t, 2> task_bytes{65536, 131072};
+    for (size_t i = 0; i < batch.task_list.size(); ++i) {
+        auto& task = batch.task_list[i];
+        task.batch_id = batch.id;
+        task.slice_count = 1;
+        task.transferred_bytes = task_bytes[i];
+        task.success_slice_count = 1;
+    }
+    const auto total_bytes = task_bytes[0] + task_bytes[1];
+    ASSERT_FALSE(batch.is_finished.load());
+    ASSERT_FALSE(batch.status_cached.load());
+
+    Transport::TransferStatus status{};
+    ASSERT_TRUE(transport.getBatchTransferStatus(batch.id, status).ok());
+    EXPECT_EQ(status.s, Transport::TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, total_bytes);
+    EXPECT_TRUE(batch.is_finished.load());
+    ASSERT_TRUE(batch.status_cached.load());
+    EXPECT_EQ(batch.finished_transfer_bytes.load(), total_bytes);
+
+    status = {};
+    ASSERT_TRUE(transport.getBatchTransferStatus(batch.id, status).ok());
+    EXPECT_EQ(status.s, Transport::TransferStatusEnum::COMPLETED);
+    EXPECT_EQ(status.transferred_bytes, total_bytes);
+}
+
+#ifdef USE_EVENT_DRIVEN_COMPLETION
+TEST_F(TransportTest, GroupedTaskCompletionWaitsForSubmissionSeal) {
+    Transport::BatchDesc batch{};
+    batch.id = reinterpret_cast<Transport::BatchID>(&batch);
+    batch.batch_size = 1;
+    Transport::TransferTask task;
+    task.batch_id = batch.id;
+    task.request_count = 2;
+    task.submission_sealed = false;
+
+    auto complete_slice = [&] {
+        __atomic_add_fetch(&task.slice_count, 1, __ATOMIC_ACQ_REL);
+        Transport::Slice slice{};
+        slice.task = &task;
+        slice.length = 1;
+        slice.markSuccess();
+    };
+    complete_slice();
+    EXPECT_FALSE(task.is_finished);
+    complete_slice();
+    EXPECT_FALSE(task.is_finished);
+
+    Transport::Slice::sealTaskSubmission(&task);
+    EXPECT_TRUE(task.is_finished);
+    EXPECT_TRUE(batch.is_finished.load());
+    EXPECT_EQ(batch.finished_task_count.load(), 1);
+
+    Transport::Slice::sealTaskSubmission(&task);
+    EXPECT_EQ(batch.finished_task_count.load(), 1);
+}
+#endif
+
 }  // namespace mooncake
 
 int main(int argc, char** argv) {
diff --git a/mooncake-transfer-engine/tests/worker_pool_rail_state_test.cpp b/mooncake-transfer-engine/tests/worker_pool_rail_state_test.cpp
new file mode 100644
index 0000000000..db1129c601
--- /dev/null
+++ b/mooncake-transfer-engine/tests/worker_pool_rail_state_test.cpp
@@ -0,0 +1,543 @@
+// Copyright 2026 KVCache.AI
+//
+// 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.
+
+// Rail-state regression tests for issue #3299. A local completion fault
+// (mlx5 "local length error" and friends) retires the endpoint and hands the
+// slice to another local RNIC, which rebuilds its own endpoint to the same
+// peer NIC. Nothing used to bound that teardown/rebuild cycle, so a recurring
+// fault turned into a reconnect storm. markRailFailed() now counts those
+// faults, and kRailErrorThreshold consecutive ones pause the path.
+//
+// The rail monitor and local-WC context breaker are plain per-worker-pool
+// state, so these tests need no RDMA device: the pool is built over a context
+// whose device never opens.
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+
+#include <glog/logging.h>
+
+#include "rdma_test_peers.h"
+#include "transport/rdma_transport/rdma_context.h"
+#include "transport/rdma_transport/rdma_transport.h"
+#include "transport/rdma_transport/worker_pool.h"
+
+#if defined(__has_feature)
+#define MC_HAS_FEATURE(x) __has_feature(x)
+#else
+#define MC_HAS_FEATURE(x) 0
+#endif
+#if defined(__SANITIZE_ADDRESS__) || MC_HAS_FEATURE(address_sanitizer) || \
+    MC_HAS_FEATURE(leak_sanitizer)
+#include <sanitizer/lsan_interface.h>
+#define MC_LSAN_IGNORE_OBJECT(p) __lsan_ignore_object(p)
+
+// Suppress false positives from libnuma.so's process-wide static cache
+// allocated in numa_node_to_cpus() which is intentionally retained until exit.
+extern "C" __attribute__((weak, visibility("default"))) const char *
+__lsan_default_suppressions() {
+    return "leak:libnuma.so\n";
+}
+#else
+#define MC_LSAN_IGNORE_OBJECT(p) ((void)(p))
+#endif
+
+using namespace mooncake;
+
+#ifdef __linux__
+namespace {
+std::function<GidRefreshResult()> gid_probe;
+}
+
+// Wrap the device probe, leaving the actual WorkerPool recovery path intact.
+extern "C" GidRefreshResult
+wrapRefreshCurrentGid(RdmaContext *, std::string *, std::string *) asm(
+    "__wrap__ZN8mooncake11RdmaContext17refreshCurrentGidEPNSt7__cxx1112basic_"
+    "stringIcSt11char_traitsIcESaIcEEES7_");
+extern "C" GidRefreshResult wrapRefreshCurrentGid(RdmaContext *, std::string *,
+                                                  std::string *) {
+    return gid_probe ? gid_probe() : GidRefreshResult::FAILED;
+}
+#endif
+
+namespace mooncake {
+
+class WorkerPoolTestPeer {
+   public:
+    static void markRailFailed(WorkerPool &pool, const std::string &path,
+                               bool immediate_pause) {
+        pool.markRailFailed(path, immediate_pause);
+    }
+
+    static bool isRailAvailable(WorkerPool &pool, const std::string &path) {
+        return pool.isRailAvailable(path);
+    }
+
+    // Moves the recorded error timestamp back so the decay window can be
+    // exercised without sleeping through it.
+    static void ageLastError(WorkerPool &pool, const std::string &path,
+                             uint64_t age_ns) {
+        std::lock_guard<std::mutex> lock(pool.rail_state_lock_);
+        pool.rail_states_[path].last_error_ns -= age_ns;
+    }
+
+    // These tests only read and write rail state, so the pool's threads have
+    // nothing to do. Left running they busy-poll: the context never opened, so
+    // monitorWorker spins on a failing epoll_wait() for the whole suite. Same
+    // shutdown as ~WorkerPool, ordered so a worker cannot miss the wakeup and
+    // park for its full 1s timeout; the destructor then sees workers_running_
+    // already false and does not join twice.
+    static void stopWorkers(WorkerPool &pool) {
+        if (!pool.workers_running_) return;
+        pool.workers_running_.store(false);
+        pool.cond_var_.notify_all();
+        for (auto &entry : pool.worker_thread_) entry.join();
+    }
+
+    static int errorThreshold() { return WorkerPool::kRailErrorThreshold; }
+
+    static uint64_t errorWindowNs() { return WorkerPool::kRailErrorWindowNs; }
+
+    static int pausedRailCount(WorkerPool &pool) {
+        return pool.paused_rail_count_.load(std::memory_order_acquire);
+    }
+
+    static void expirePause(WorkerPool &pool, const std::string &path) {
+        std::lock_guard<std::mutex> lock(pool.rail_state_lock_);
+        pool.rail_states_[path].pause_until_ns = 1;
+    }
+
+    static void setContextActive(WorkerPool &pool, bool active) {
+        pool.context_.set_active(active);
+    }
+
+    static bool contextActive(WorkerPool &pool) {
+        return pool.context_.active();
+    }
+
+    static bool markLocalContextFailure(WorkerPool &pool) {
+        return pool.markLocalContextFailure();
+    }
+
+    static void markContextSuccess(WorkerPool &pool) {
+        pool.markContextSuccess();
+    }
+
+    static int contextFailureCount(WorkerPool &pool) {
+        return pool.context_failure_count_.load(std::memory_order_relaxed);
+    }
+
+    static uint64_t breakerReactivateAfter(WorkerPool &pool) {
+        std::lock_guard<std::mutex> lock(pool.context_state_lock_);
+        return pool.breaker_reactivate_after_ns_;
+    }
+
+    static bool tryReactivateContext(WorkerPool &pool, uint64_t now_ns) {
+        return pool.tryReactivateContext(now_ns);
+    }
+
+    static void setRecoveryActivateAfter(WorkerPool &pool,
+                                         uint64_t activate_after_ns) {
+        pool.recovery_activate_after_ns_.store(activate_after_ns,
+                                               std::memory_order_relaxed);
+    }
+
+    static void contextEvent(WorkerPool &pool, ibv_event_type event) {
+        pool.processContextEventForTest(event);
+    }
+
+    static uint64_t recoveryActivateAfter(WorkerPool &pool) {
+        return pool.recovery_activate_after_ns_.load(std::memory_order_relaxed);
+    }
+
+    static void recoverContext(WorkerPool &pool) {
+        pool.maybeActivateRecoveredContext();
+    }
+
+    static int contextFailureThreshold() {
+        return WorkerPool::kLocalCompletionFailureThreshold;
+    }
+};
+
+}  // namespace mooncake
+
+namespace {
+
+constexpr const char *kPeerA = "10.0.0.1@mlx5_bond_0";
+constexpr const char *kPeerB = "10.0.0.1@mlx5_bond_1";
+
+class WorkerPoolRailStateTest : public ::testing::Test {
+   protected:
+    void SetUp() override {
+        // The context below is expected to fail to open, and that path is
+        // noisy. Silence it so gtest failures stay readable.
+        previous_min_log_level_ = FLAGS_minloglevel;
+        FLAGS_minloglevel = google::GLOG_FATAL;
+
+        metadata_ = std::make_shared<TransferMetadata>(P2PHANDSHAKE);
+        transport_ = std::make_unique<RdmaTransport>();
+        RdmaTransportTestPeer::bindMetadata(*transport_, metadata_,
+                                            "rail-state-test");
+        context_ = std::make_unique<RdmaContext>(*transport_, "unused");
+        // Always fails, on any host, because no device is named "unused". It
+        // still creates the endpoint store, which the monitor tick can touch
+        // in the window before it is stopped below.
+        context_->construct();
+        worker_pool_ = std::make_unique<WorkerPool>(*context_);
+        WorkerPoolTestPeer::stopWorkers(*worker_pool_);
+    }
+
+    void TearDown() override {
+#ifdef __linux__
+        gid_probe = {};
+#endif
+        worker_pool_.reset();
+        context_.reset();
+        transport_.reset();
+        FLAGS_minloglevel = previous_min_log_level_;
+    }
+
+    void failRail(const std::string &path, bool immediate_pause = false) {
+        WorkerPoolTestPeer::markRailFailed(*worker_pool_, path,
+                                           immediate_pause);
+    }
+
+    bool railAvailable(const std::string &path) {
+        return WorkerPoolTestPeer::isRailAvailable(*worker_pool_, path);
+    }
+
+    int previous_min_log_level_ = 0;
+    std::shared_ptr<TransferMetadata> metadata_;
+    std::unique_ptr<RdmaTransport> transport_;
+    std::unique_ptr<RdmaContext> context_;
+    std::unique_ptr<WorkerPool> worker_pool_;
+};
+
+TEST_F(WorkerPoolRailStateTest, UnknownRailIsAvailable) {
+    EXPECT_TRUE(railAvailable(kPeerA));
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 0);
+}
+
+TEST_F(WorkerPoolRailStateTest, FailuresBelowThresholdDoNotPauseCount) {
+    for (int i = 0; i < WorkerPoolTestPeer::errorThreshold() - 1; ++i)
+        failRail(kPeerA);
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 0);
+    EXPECT_TRUE(railAvailable(kPeerA));
+}
+
+TEST_F(WorkerPoolRailStateTest, PauseIncrementsCountOnce) {
+    for (int i = 0; i < WorkerPoolTestPeer::errorThreshold(); ++i)
+        failRail(kPeerA);
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 1);
+    EXPECT_FALSE(railAvailable(kPeerA));
+
+    failRail(kPeerA, /*immediate_pause=*/true);
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 1);
+}
+
+TEST_F(WorkerPoolRailStateTest, IndependentPausesIncrementCount) {
+    failRail(kPeerA, /*immediate_pause=*/true);
+    failRail(kPeerB, /*immediate_pause=*/true);
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 2);
+    EXPECT_FALSE(railAvailable(kPeerA));
+    EXPECT_FALSE(railAvailable(kPeerB));
+}
+
+TEST_F(WorkerPoolRailStateTest, ExpiredPauseDecrementsCount) {
+    failRail(kPeerA, /*immediate_pause=*/true);
+    ASSERT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 1);
+    WorkerPoolTestPeer::expirePause(*worker_pool_, kPeerA);
+    EXPECT_TRUE(railAvailable(kPeerA));
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 0);
+    EXPECT_TRUE(railAvailable(kPeerB));
+}
+
+TEST_F(WorkerPoolRailStateTest, ExpiredPauseClearsCountOnOtherRailCheck) {
+    failRail(kPeerA, /*immediate_pause=*/true);
+    failRail(kPeerB, /*immediate_pause=*/true);
+    ASSERT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 2);
+    WorkerPoolTestPeer::expirePause(*worker_pool_, kPeerA);
+    EXPECT_FALSE(railAvailable(kPeerB));
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 1);
+    EXPECT_TRUE(railAvailable(kPeerA));
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 1);
+
+    WorkerPoolTestPeer::expirePause(*worker_pool_, kPeerB);
+    constexpr const char *kPeerC = "10.0.0.1@mlx5_bond_2";
+    EXPECT_TRUE(railAvailable(kPeerC));
+    EXPECT_EQ(WorkerPoolTestPeer::pausedRailCount(*worker_pool_), 0);
+    EXPECT_TRUE(railAvailable(kPeerB));
+}
+
+// A single local fault must stay free: the endpoint is rebuilt and the slice
+// retried, exactly as before.
+TEST_F(WorkerPoolRailStateTest, FailuresBelowThresholdDoNotPauseRail) {
+    for (int i = 0; i < WorkerPoolTestPeer::errorThreshold() - 1; ++i) {
+        failRail(kPeerA);
+        EXPECT_TRUE(railAvailable(kPeerA))
+            << "paused after " << (i + 1) << " error(s)";
+    }
+}
+
+// The regression: without this, a recurring local fault re-handshakes the same
+// peer NIC forever because nothing on the local path ever pauses it.
+TEST_F(WorkerPoolRailStateTest, RepeatedFailuresPauseRail) {
+    for (int i = 0; i < WorkerPoolTestPeer::errorThreshold(); ++i)
+        failRail(kPeerA);
+
+    EXPECT_FALSE(railAvailable(kPeerA));
+}
+
+// Remote-path handling is unchanged: one error with immediate_pause set still
+// pauses the rail right away.
+TEST_F(WorkerPoolRailStateTest, ImmediatePauseStillPausesOnFirstError) {
+    failRail(kPeerA, /*immediate_pause=*/true);
+
+    EXPECT_FALSE(railAvailable(kPeerA));
+}
+
+// Errors spread further apart than the window are not consecutive, so a
+// healthy rail cannot accumulate its way to a pause over a long process life.
+TEST_F(WorkerPoolRailStateTest, StaleErrorsDoNotAccumulate) {
+    const int threshold = WorkerPoolTestPeer::errorThreshold();
+    for (int round = 0; round < 3; ++round) {
+        for (int i = 0; i < threshold - 1; ++i) failRail(kPeerA);
+        ASSERT_TRUE(railAvailable(kPeerA));
+        WorkerPoolTestPeer::ageLastError(
+            *worker_pool_, kPeerA, WorkerPoolTestPeer::errorWindowNs() + 1);
+    }
+
+    for (int i = 0; i < threshold - 1; ++i) failRail(kPeerA);
+    EXPECT_TRUE(railAvailable(kPeerA));
+}
+
+// Pausing one peer RNIC must not take the peer's other RNIC with it, otherwise
+// a single bad path would strand every transfer to that server.
+TEST_F(WorkerPoolRailStateTest, RailsArePausedIndependently) {
+    for (int i = 0; i < WorkerPoolTestPeer::errorThreshold(); ++i)
+        failRail(kPeerA);
+
+    EXPECT_FALSE(railAvailable(kPeerA));
+    EXPECT_TRUE(railAvailable(kPeerB));
+}
+
+// Exercise the submit path that used to mistake one peer's unavailable rails
+// for a local RNIC failure, not just the rail-pausing helper.
+TEST_F(WorkerPoolRailStateTest,
+       AllRailsUnavailableSubmitsDoNotDeactivateContext) {
+    constexpr SegmentID target_id = 3559;
+    constexpr uint64_t buffer_addr = 0x10000;
+    auto desc = std::make_shared<TransferMetadata::SegmentDesc>();
+    desc->name = "10.0.0.1";
+    desc->protocol = "rdma";
+    desc->devices.push_back({"mlx5_bond_0", 1, "", ""});
+    desc->devices.push_back({"mlx5_bond_1", 1, "", ""});
+    TransferMetadata::BufferDesc buffer;
+    buffer.name = "cpu:0";
+    buffer.addr = buffer_addr;
+    buffer.length = 4096;
+    buffer.rkey = {11, 22};
+    desc->buffers.push_back(buffer);
+    ASSERT_EQ(desc->topology.parse(
+                  R"({"cpu:0": [["mlx5_bond_0", "mlx5_bond_1"], []]})"),
+              0);
+    metadata_->addLocalSegment(target_id, "10.0.0.1", std::move(desc));
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    Transport::TransferTask task;
+    task.batch_id = transport_->allocateBatchID(1);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i) {
+        failRail(kPeerA, /*immediate_pause=*/true);
+        failRail(kPeerB, /*immediate_pause=*/true);
+        Transport::Slice slice{};
+        slice.task = &task;
+        slice.target_id = target_id;
+        slice.rdma.dest_addr = buffer_addr;
+        slice.length = 64;
+        ASSERT_EQ(worker_pool_->submitPostSend({&slice}), 0);
+        EXPECT_EQ(slice.status, Transport::Slice::FAILED);
+        // Device selection succeeded, so the failure was unavailable rails.
+        EXPECT_TRUE(slice.rdma.dest_rkey == 11 || slice.rdma.dest_rkey == 22);
+        EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+        EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    }
+    EXPECT_EQ(task.failed_slice_count,
+              WorkerPoolTestPeer::contextFailureThreshold());
+    EXPECT_TRUE(transport_->freeBatchID(task.batch_id).ok());
+
+    EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+}
+
+TEST_F(WorkerPoolRailStateTest, LocalFailuresTripContextAtThreshold) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    const int threshold = WorkerPoolTestPeer::contextFailureThreshold();
+    for (int i = 0; i < threshold - 1; ++i) {
+        EXPECT_FALSE(
+            WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+        EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    }
+
+    EXPECT_TRUE(WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_NE(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+}
+
+TEST_F(WorkerPoolRailStateTest, SuccessResetsLocalFailureStreak) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    const int threshold = WorkerPoolTestPeer::contextFailureThreshold();
+    for (int i = 0; i < threshold - 1; ++i)
+        ASSERT_FALSE(
+            WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+
+    WorkerPoolTestPeer::markContextSuccess(*worker_pool_);
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+
+    for (int i = 0; i < threshold - 1; ++i)
+        EXPECT_FALSE(
+            WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+    EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+}
+
+TEST_F(WorkerPoolRailStateTest, BreakerReactivatesAtDeadline) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i)
+        WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_);
+    const uint64_t deadline =
+        WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_);
+    ASSERT_NE(deadline, 0u);
+
+    EXPECT_FALSE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, deadline - 1));
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_TRUE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, deadline));
+    EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+    EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+}
+
+TEST_F(WorkerPoolRailStateTest, GidRecoveryBlocksBreakerDeadline) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i)
+        WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_);
+    const uint64_t deadline =
+        WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_);
+    ASSERT_NE(deadline, 0u);
+
+    WorkerPoolTestPeer::setRecoveryActivateAfter(*worker_pool_, 1);
+    EXPECT_FALSE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, deadline));
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+
+    WorkerPoolTestPeer::setRecoveryActivateAfter(*worker_pool_, 0);
+    EXPECT_TRUE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, deadline));
+}
+
+TEST_F(WorkerPoolRailStateTest, FatalEventOwnershipCancelsBreakerDeadline) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i)
+        WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_);
+    ASSERT_NE(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+
+    WorkerPoolTestPeer::contextEvent(*worker_pool_, IBV_EVENT_DEVICE_FATAL);
+    EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+    EXPECT_FALSE(WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+    EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+    EXPECT_FALSE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, UINT64_MAX));
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+}
+
+TEST_F(WorkerPoolRailStateTest,
+       RedundantPortActivePreservesLocalFailureStreak) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold() - 1; ++i)
+        WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_);
+
+    WorkerPoolTestPeer::contextEvent(*worker_pool_, IBV_EVENT_PORT_ACTIVE);
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 31);
+    EXPECT_EQ(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+    EXPECT_TRUE(WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+    WorkerPoolTestPeer::recoverContext(*worker_pool_);
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_NE(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+}
+
+#ifdef __linux__
+TEST_F(WorkerPoolRailStateTest, GidProbeOwnsRecoveryThroughoutIoAndRetry) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, true);
+    for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i)
+        WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_);
+
+    WorkerPoolTestPeer::contextEvent(*worker_pool_, IBV_EVENT_PORT_ACTIVE);
+    EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 32);
+    EXPECT_NE(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+    int probe_count = 0;
+    gid_probe = [&] {
+        ++probe_count;
+        EXPECT_NE(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+        EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+        // A poller can still deliver late CQEs while the monitor probes.
+        for (int i = 0; i < WorkerPoolTestPeer::contextFailureThreshold(); ++i)
+            EXPECT_FALSE(
+                WorkerPoolTestPeer::markLocalContextFailure(*worker_pool_));
+        EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_),
+                  0u);
+        EXPECT_FALSE(WorkerPoolTestPeer::tryReactivateContext(*worker_pool_,
+                                                              UINT64_MAX));
+        return probe_count == 1 ? GidRefreshResult::FAILED
+                                : GidRefreshResult::UNCHANGED;
+    };
+
+    WorkerPoolTestPeer::setRecoveryActivateAfter(*worker_pool_, 1);
+    WorkerPoolTestPeer::recoverContext(*worker_pool_);
+    EXPECT_EQ(probe_count, 1);
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_NE(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+    EXPECT_EQ(WorkerPoolTestPeer::breakerReactivateAfter(*worker_pool_), 0u);
+
+    WorkerPoolTestPeer::setRecoveryActivateAfter(*worker_pool_, 1);
+    WorkerPoolTestPeer::recoverContext(*worker_pool_);
+    EXPECT_EQ(probe_count, 2);
+    EXPECT_TRUE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_EQ(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+    EXPECT_EQ(WorkerPoolTestPeer::contextFailureCount(*worker_pool_), 0);
+}
+
+TEST_F(WorkerPoolRailStateTest, FatalEventCancelsPendingGidProbe) {
+    WorkerPoolTestPeer::setContextActive(*worker_pool_, false);
+    WorkerPoolTestPeer::contextEvent(*worker_pool_, IBV_EVENT_PORT_ACTIVE);
+    WorkerPoolTestPeer::setRecoveryActivateAfter(*worker_pool_, 1);
+    WorkerPoolTestPeer::contextEvent(*worker_pool_, IBV_EVENT_PORT_ERR);
+    gid_probe = [] {
+        ADD_FAILURE() << "Fatal event must cancel the pending probe";
+        return GidRefreshResult::UNCHANGED;
+    };
+    WorkerPoolTestPeer::recoverContext(*worker_pool_);
+    EXPECT_FALSE(WorkerPoolTestPeer::contextActive(*worker_pool_));
+    EXPECT_EQ(WorkerPoolTestPeer::recoveryActivateAfter(*worker_pool_), 0u);
+    EXPECT_FALSE(
+        WorkerPoolTestPeer::tryReactivateContext(*worker_pool_, UINT64_MAX));
+}
+#endif
+
+}  // namespace
diff --git a/mooncake-wheel/mooncake/__init__.py b/mooncake-wheel/mooncake/__init__.py
index f1bb787f50..4532fdbf4c 100644
--- a/mooncake-wheel/mooncake/__init__.py
+++ b/mooncake-wheel/mooncake/__init__.py
@@ -1,6 +1,9 @@
 """Mooncake public Python package."""
 
+from pkgutil import extend_path
+
 from mooncake.buffer_pool import BufferPool, RegisteredBufferPool
 
-__all__ = ["BufferPool", "RegisteredBufferPool"]
+__path__ = extend_path(__path__, __name__)
 
+__all__ = ["BufferPool", "RegisteredBufferPool"]
diff --git a/mooncake-wheel/mooncake/cli.py b/mooncake-wheel/mooncake/cli.py
deleted file mode 100644
index 2fba48a38f..0000000000
--- a/mooncake-wheel/mooncake/cli.py
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-"""
-Minimal CLI module for mooncake_master.
-"""
-
-import os
-import stat
-import sys
-import subprocess
-
-
-def main():
-    """
-    Main entry point for the mooncake_master command.
-    Simply runs the mooncake_master binary with all arguments passed through.
-    """
-    # Get the path to the mooncake_master binary
-    package_dir = os.path.dirname(os.path.abspath(__file__))
-    bin_path = os.path.join(package_dir, "mooncake_master")
-
-    # Make sure the binary is executable
-    if not os.access(bin_path, os.X_OK):
-        st = os.stat(bin_path)
-        os.chmod(bin_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
-
-    # Run the binary with all arguments passed through
-    return subprocess.call([bin_path] + sys.argv[1:])
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/mooncake-wheel/mooncake/cli_client.py b/mooncake-wheel/mooncake/cli_client.py
deleted file mode 100644
index 0cf20ec717..0000000000
--- a/mooncake-wheel/mooncake/cli_client.py
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-"""
-Minimal CLI module for mooncake_client.
-"""
-
-import os
-import stat
-import sys
-import subprocess
-
-
-def main():
-    """
-    Main entry point for the mooncake_client command.
-    Simply runs the mooncake_client binary with all arguments passed through.
-    """
-    # Get the path to the mooncake_client binary
-    package_dir = os.path.dirname(os.path.abspath(__file__))
-    bin_path = os.path.join(package_dir, "mooncake_client")
-
-    # Make sure the binary is executable
-    if not os.access(bin_path, os.X_OK):
-        st = os.stat(bin_path)
-        os.chmod(bin_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
-
-    # Run the binary with all arguments passed through
-    return subprocess.call([bin_path] + sys.argv[1:])
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/mooncake-wheel/mooncake/dataproto_catalog.py b/mooncake-wheel/mooncake/dataproto_catalog.py
new file mode 100644
index 0000000000..7574fb1e2e
--- /dev/null
+++ b/mooncake-wheel/mooncake/dataproto_catalog.py
@@ -0,0 +1,766 @@
+from __future__ import annotations
+
+import copy
+import logging
+import threading
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+
+logger = logging.getLogger(__name__)
+
+
+class DataProtoCatalog:
+    """Map logical rows and fields to immutable DataProto refs.
+
+    Calls to one catalog instance must be serialized by its host. Direct
+    handles remain metadata-only. DataProtoCatalogTransfer marks only fresh,
+    independent fragments as managed so their physical lifetime, including
+    append-derived handles, can follow logical references and active readers.
+    """
+
+    def __init__(self) -> None:
+        self._partitions: dict[str, dict[str, dict[str, Any]]] = {}
+        self._fragments: dict[str, dict[str, Any]] = {}
+        self._retired: dict[str, dict[str, Any]] = {}
+        self._publications: dict[str, dict[str, Any]] = {}
+        self._fragment_refcounts: dict[str, int] = {}
+        self._managed_fragments: set[str] = set()
+        self._fragment_readers: dict[str, int] = {}
+        self._read_pins: dict[int, tuple[str, ...]] = {}
+        self._next_read_token = 0
+        self._drained = False
+
+    def update(
+        self,
+        partition: str,
+        keys: Sequence[str],
+        *,
+        tags: Sequence[Mapping[str, Any]] | None = None,
+        handle: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._update(partition, keys, tags=tags, handle=handle, managed=False)
+
+    def publish(
+        self,
+        operation_id: str,
+        partition: str,
+        keys: Sequence[str],
+        *,
+        tags: Sequence[Mapping[str, Any]] | None = None,
+        handle: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Idempotently publish one transfer-managed fresh fragment."""
+        operation_id = _nonempty_string(operation_id, "operation_id")
+        previous = self._publications.get(operation_id)
+        if previous is not None:
+            return copy.deepcopy(previous)
+
+        result = self._update(
+            partition,
+            keys,
+            tags=tags,
+            handle=handle,
+            managed=handle is not None,
+        )
+        self._publications[operation_id] = copy.deepcopy(result)
+        return result
+
+    def ack_publication(self, operation_id: str) -> None:
+        self._publications.pop(_nonempty_string(operation_id, "operation_id"), None)
+
+    def publish_append(
+        self,
+        operation_id: str,
+        fragment_id: str,
+        partition: str,
+        keys: Sequence[str],
+        *,
+        previous_handle: Mapping[str, Any],
+        handle: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        """Idempotently replace a managed fragment with its appended handle."""
+        operation_id = _nonempty_string(operation_id, "operation_id")
+        previous = self._publications.get(operation_id)
+        if previous is not None:
+            return copy.deepcopy(previous)
+        if self._drained:
+            return self._reject_append(operation_id, "DataProto catalog is drained")
+        fragment_id = _nonempty_string(fragment_id, "fragment_id")
+        partition = _nonempty_string(partition, "partition")
+        keys = _names(keys, "keys")
+        previous_ref, normalized_previous = _normalize_handle(previous_handle)
+        ref, normalized = _normalize_handle(handle)
+        current = self._fragments.get(fragment_id)
+        if (
+            current is None
+            or fragment_id not in self._managed_fragments
+            or current != normalized_previous
+        ):
+            return self._reject_append(
+                operation_id, f"stale DataProto append handle: {fragment_id!r}"
+            )
+        if (
+            ref.batch_size != previous_ref.batch_size
+            or ref.batch_size != len(keys)
+            or ref.partition != previous_ref.partition
+            or ref.partition != partition
+            or ref._storage_group_id != previous_ref._storage_group_id
+        ):
+            return self._reject_append(
+                operation_id, "appended DataProto handle changed fragment identity"
+            )
+        previous_fields = previous_ref.field_index
+        if any(
+            ref.field_index.get(name) != location
+            for name, location in previous_fields.items()
+        ):
+            return self._reject_append(
+                operation_id, "appended DataProto handle changed existing fields"
+            )
+        new_fields = [
+            field for field in ref.field_index if field not in previous_fields
+        ]
+
+        entries = self._partitions.get(partition, {})
+        missing = [key for key in keys if key not in entries]
+        if missing:
+            return self._reject_append(
+                operation_id,
+                f"keys not found in partition {partition!r}: {missing}",
+            )
+        for row, key in enumerate(keys):
+            for field in new_fields:
+                location = (fragment_id, row)
+                old_location = entries[key]["fields"].get(field)
+                if old_location is not None:
+                    self._drop_fragment_reference(old_location[0])
+                entries[key]["fields"][field] = location
+                self._fragment_refcounts[fragment_id] += 1
+        self._fragments[fragment_id] = normalized
+        result = {
+            "keys": list(keys),
+            "tags": [copy.deepcopy(entries[key]["tag"]) for key in keys],
+            "fields": _field_union(entries, keys),
+            **self._retired_result(),
+        }
+        self._publications[operation_id] = copy.deepcopy(result)
+        return result
+
+    def _reject_append(self, operation_id: str, message: str) -> dict[str, Any]:
+        result = {"append_rejected": message}
+        self._publications[operation_id] = copy.deepcopy(result)
+        return result
+
+    def _update(
+        self,
+        partition: str,
+        keys: Sequence[str],
+        *,
+        tags: Sequence[Mapping[str, Any]] | None,
+        handle: Mapping[str, Any] | None,
+        managed: bool,
+    ) -> dict[str, Any]:
+        if self._drained:
+            raise RuntimeError("DataProto catalog is drained")
+        partition = _nonempty_string(partition, "partition")
+        keys = _names(keys, "keys")
+        normalized_tags = _tags(tags, len(keys))
+        fragment = _fragment(handle, len(keys)) if handle is not None else None
+        if normalized_tags is None and fragment is None:
+            raise ValueError("catalog update requires tags or a DataProto handle")
+
+        if fragment is not None:
+            fragment_id, stored_handle, fields = fragment
+            previous = self._fragments.get(fragment_id)
+            if previous is not None and previous != stored_handle:
+                raise ValueError(f"DataProto fragment id collision: {fragment_id!r}")
+            if (
+                previous is not None
+                and (fragment_id in self._managed_fragments) != managed
+            ):
+                raise ValueError(
+                    f"DataProto fragment management mismatch: {fragment_id!r}"
+                )
+            if fragment_id in self._retired:
+                raise ValueError(
+                    f"DataProto fragment id is pending retirement: {fragment_id!r}"
+                )
+
+        current_entries = self._partitions.get(partition, {})
+        merged_tags = {}
+        response_tags = []
+        for row, key in enumerate(keys):
+            tag = copy.deepcopy(current_entries.get(key, {"tag": {}})["tag"])
+            if normalized_tags is not None:
+                tag.update(normalized_tags[row])
+            merged_tags[key] = tag
+            response_tags.append(copy.deepcopy(tag))
+
+        entries = self._partitions.setdefault(partition, {})
+        if fragment is not None:
+            self._fragments.setdefault(fragment_id, stored_handle)
+            self._fragment_refcounts.setdefault(fragment_id, 0)
+            if managed:
+                self._managed_fragments.add(fragment_id)
+
+        for row, key in enumerate(keys):
+            entry = entries.setdefault(key, {"tag": {}, "fields": {}})
+            entry["tag"] = merged_tags[key]
+            if fragment is None:
+                continue
+            for field in fields:
+                location = (fragment_id, row)
+                old_location = entry["fields"].get(field)
+                if old_location == location:
+                    continue
+                if old_location is not None and old_location[0] == fragment_id:
+                    entry["fields"][field] = location
+                    continue
+                if old_location is not None:
+                    self._drop_fragment_reference(old_location[0])
+                entry["fields"][field] = location
+                self._fragment_refcounts[fragment_id] += 1
+
+        return {
+            "keys": list(keys),
+            "tags": response_tags,
+            "fields": _field_union(entries, keys),
+            **self._retired_result(),
+        }
+
+    def resolve(
+        self,
+        partition: str,
+        keys: Sequence[str],
+        fields: Sequence[str] | None = None,
+        *,
+        pin: bool = False,
+    ) -> dict[str, Any]:
+        """Resolve an ordered logical read into immutable fragment locations."""
+        partition = _nonempty_string(partition, "partition")
+        keys = _names(keys, "keys")
+        entries = self._partitions.get(partition, {})
+        missing = [key for key in keys if key not in entries]
+        if missing:
+            raise ValueError(
+                f"keys were not found in partition {partition!r}: {missing}"
+            )
+
+        selected = (
+            list(_names(fields, "field names"))
+            if fields is not None
+            else _field_union(entries, keys)
+        )
+        if not selected:
+            raise ValueError("requested keys do not contain any fields")
+
+        for key in keys:
+            entry_fields = entries[key]["fields"]
+            unavailable = [field for field in selected if field not in entry_fields]
+            if unavailable:
+                raise ValueError(f"fields are not ready for key {key!r}: {unavailable}")
+
+        grouped_fields: dict[tuple[tuple[str, int], ...], list[str]] = {}
+        fragment_ids: set[str] = set()
+        for field in selected:
+            locations = tuple(entries[key]["fields"][field] for key in keys)
+            grouped_fields.setdefault(locations, []).append(field)
+            fragment_ids.update(location[0] for location in locations)
+
+        handles = {
+            fragment_id: copy.deepcopy(self._fragments[fragment_id])
+            for fragment_id in fragment_ids
+        }
+        meta_info: dict[str, Any] = {}
+        for handle in handles.values():
+            for name, value in handle.get("meta_info", {}).items():
+                if name in meta_info and meta_info[name] != value:
+                    raise ValueError(
+                        f"conflicting DataProto meta_info value for {name!r}"
+                    )
+                meta_info[name] = copy.deepcopy(value)
+
+        result = {
+            "keys": list(keys),
+            "tags": [copy.deepcopy(entries[key]["tag"]) for key in keys],
+            "fields": selected,
+            "field_groups": [
+                {"fields": fields, "locations": list(locations)}
+                for locations, fields in grouped_fields.items()
+            ],
+            "handles": handles,
+            "meta_info": meta_info,
+        }
+        if pin:
+            self._next_read_token += 1
+            token = self._next_read_token
+            pinned = tuple(fragment_ids)
+            self._read_pins[token] = pinned
+            for fragment_id in pinned:
+                self._fragment_readers[fragment_id] = (
+                    self._fragment_readers.get(fragment_id, 0) + 1
+                )
+            result["read_token"] = token
+        return result
+
+    def release_read(self, token: int) -> dict[str, Any]:
+        """Idempotently release a pinned resolve and return pending handles."""
+        fragment_ids = self._read_pins.pop(token, None)
+        if fragment_ids is None:
+            return self._retired_result()
+
+        for fragment_id in fragment_ids:
+            readers = self._fragment_readers[fragment_id] - 1
+            if readers:
+                self._fragment_readers[fragment_id] = readers
+                continue
+            del self._fragment_readers[fragment_id]
+            if fragment_id not in self._fragment_refcounts:
+                self._retire_fragment(fragment_id)
+        return self._retired_result()
+
+    def list(self, partition: str | None = None) -> dict[str, dict[str, Any]]:
+        """Return tags using the same partition/key shape as rollout KV APIs."""
+        if partition is not None:
+            partition = _nonempty_string(partition, "partition")
+            partitions = [partition] if partition in self._partitions else []
+        else:
+            partitions = list(self._partitions)
+        return {
+            partition_id: {
+                key: copy.deepcopy(entry["tag"])
+                for key, entry in self._partitions[partition_id].items()
+            }
+            for partition_id in partitions
+        }
+
+    def remove(self, partition: str, keys: Sequence[str]) -> dict[str, Any]:
+        """Remove logical keys after their writers have finished.
+
+        Returned managed handles can be passed to ``cleanup_dataproto``.
+        """
+        partition = _nonempty_string(partition, "partition")
+        keys = _names(keys, "keys")
+        entries = self._partitions.get(partition)
+        if entries is None:
+            return self._retired_result()
+
+        for key in keys:
+            entry = entries.pop(key, None)
+            if entry is None:
+                continue
+            for fragment_id, _row in entry["fields"].values():
+                self._drop_fragment_reference(fragment_id)
+        if not entries:
+            del self._partitions[partition]
+        return self._retired_result()
+
+    def drain(self) -> dict[str, Any]:
+        """Retire all metadata after clients quiesce and return pending handles."""
+        if self._read_pins:
+            raise RuntimeError(
+                f"cannot drain DataProto catalog with {len(self._read_pins)} active read(s)"
+            )
+        for fragment_id in self._managed_fragments:
+            self._retired[fragment_id] = self._fragments[fragment_id]
+        self._partitions.clear()
+        self._fragments.clear()
+        self._fragment_refcounts.clear()
+        self._managed_fragments.clear()
+        self._fragment_readers.clear()
+        self._publications.clear()
+        self._drained = True
+        return self._retired_result()
+
+    def ack_retired(self, handles: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+        """Forget retired handles whose Store objects were removed successfully."""
+        for handle in handles:
+            ref, normalized = _normalize_handle(handle)
+            fragment_id = next(
+                (
+                    key
+                    for key, pending in self._retired.items()
+                    if pending == normalized
+                ),
+                None,
+            )
+            if fragment_id is not None:
+                del self._retired[fragment_id]
+                continue
+            if len(ref.stage_refs) == 1:
+                fragment_id = next(iter(ref.stage_refs.values())).manifest_key
+                if fragment_id in self._retired:
+                    raise ValueError(
+                        f"retired DataProto fragment mismatch: {fragment_id!r}"
+                    )
+        return self._retired_result()
+
+    def _drop_fragment_reference(self, fragment_id: str) -> None:
+        remaining = self._fragment_refcounts[fragment_id] - 1
+        if remaining:
+            self._fragment_refcounts[fragment_id] = remaining
+            return
+        del self._fragment_refcounts[fragment_id]
+        if self._fragment_readers.get(fragment_id, 0):
+            return
+        self._retire_fragment(fragment_id)
+
+    def _retire_fragment(self, fragment_id: str) -> None:
+        handle = self._fragments.pop(fragment_id)
+        if fragment_id in self._managed_fragments:
+            self._managed_fragments.remove(fragment_id)
+            self._retired[fragment_id] = handle
+
+    def _retired_result(self) -> dict[str, Any]:
+        return {
+            "retired_handles": [
+                copy.deepcopy(handle) for handle in self._retired.values()
+            ]
+        }
+
+
+class DataProtoCatalogTransfer:
+    _RESULTS_ATTR = "_mooncake_catalog_results"
+
+    def __init__(self, transfer: Any, catalog_call: Callable[..., Any]) -> None:
+        self.transfer = transfer
+        self._catalog_call = catalog_call
+        self._pending_publications: list[dict[str, Any]] = []
+        self._pending_publication_acks: list[str] = []
+        self._pending_results: list[Any] = []
+        self._cleanup_lock = threading.RLock()
+
+    def put(
+        self,
+        data: Any,
+        *,
+        partition: str,
+        keys: Sequence[str],
+        tags: Sequence[Mapping[str, Any]] | None = None,
+        **put_kwargs: Any,
+    ) -> dict[str, Any]:
+        """Put one immutable fragment and atomically publish it in Catalog."""
+        self._retry_publication_acks()
+        self._retry_publications(strict=True)
+        partition = _nonempty_string(partition, "partition")
+        normalized_keys = _names(keys, "keys")
+        normalized_tags = _tags(tags, len(normalized_keys))
+        if data is None and normalized_tags is None:
+            raise ValueError("catalog update requires tags or DataProto data")
+
+        handle = None
+        if data is not None:
+            if len(data) != len(normalized_keys):
+                raise ValueError(
+                    f"DataProto batch size {len(data)} does not match {len(normalized_keys)} logical keys"
+                )
+            from mooncake.structured_object_store import export_dataproto_ref
+
+            handle = export_dataproto_ref(
+                self.transfer.put(
+                    data, type="dataproto", partition=partition, **put_kwargs
+                )
+            )
+        publication = {
+            "operation_id": uuid.uuid4().hex,
+            "method": "publish",
+            "args": (partition, normalized_keys),
+            "kwargs": {"tags": normalized_tags, "handle": handle},
+        }
+        for attempt in range(2):
+            try:
+                return self._publish(publication)
+            except Exception:
+                if attempt:
+                    with self._cleanup_lock:
+                        self._pending_publications.append(publication)
+                    raise
+                logger.exception("Retrying DataProto Catalog publication")
+        raise AssertionError("unreachable")
+
+    def append(
+        self,
+        fragment_id: str,
+        handle: Mapping[str, Any],
+        data: Any,
+        *,
+        partition: str,
+        keys: Sequence[str],
+        stage: str,
+        **append_kwargs: Any,
+    ) -> dict[str, Any]:
+        """Append fields and transfer managed-fragment ownership to the result."""
+        self._retry_publication_acks()
+        self._retry_publications(strict=True)
+        fragment_id = _nonempty_string(fragment_id, "fragment_id")
+        partition = _nonempty_string(partition, "partition")
+        normalized_keys = _names(keys, "keys")
+        if append_kwargs.get("overwrite"):
+            raise ValueError("catalog append does not support overwrite")
+        if len(data) != len(normalized_keys):
+            raise ValueError(
+                f"DataProto batch size {len(data)} does not match {len(normalized_keys)} logical keys"
+            )
+        previous_ref, previous_handle = _normalize_handle(handle)
+        if previous_ref.partition != partition:
+            raise ValueError(
+                "DataProto handle partition does not match Catalog partition"
+            )
+        plan = self._catalog_call(
+            "resolve", partition, normalized_keys, list(previous_ref.field_index)
+        )
+        if plan["handles"].get(fragment_id) != previous_handle:
+            raise ValueError(f"stale DataProto append handle: {fragment_id!r}")
+        from mooncake.structured_object_store import export_dataproto_ref
+
+        appended_handle = export_dataproto_ref(
+            self.transfer.append_dataproto_fields(
+                previous_handle, data, stage=stage, **append_kwargs
+            )
+        )
+        publication = {
+            "operation_id": uuid.uuid4().hex,
+            "method": "publish_append",
+            "args": (fragment_id, partition, normalized_keys),
+            "kwargs": {
+                "previous_handle": previous_handle,
+                "handle": appended_handle,
+            },
+        }
+        for attempt in range(2):
+            try:
+                result = self._publish(publication)
+            except Exception:
+                if attempt:
+                    with self._cleanup_lock:
+                        self._pending_publications.append(publication)
+                    raise
+                logger.exception("Retrying DataProto Catalog append publication")
+            else:
+                rejection = result.get("append_rejected")
+                if rejection is not None:
+                    raise ValueError(rejection)
+                return result
+        raise AssertionError("unreachable")
+
+    def resolve(
+        self,
+        partition: str,
+        keys: Sequence[str],
+        fields: Sequence[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._catalog_call("resolve", partition, keys, fields, pin=True)
+
+    def release_read(self, token: int) -> None:
+        self._cleanup_retired(self._catalog_call("release_read", token))
+
+    def attach_results(self, output: Any, results: Sequence[Any]) -> None:
+        setattr(output, self._RESULTS_ATTR, list(results))
+
+    def release_result(self, output: Any) -> None:
+        results = getattr(output, self._RESULTS_ATTR, ()) or ()
+        setattr(output, self._RESULTS_ATTR, [])
+        self.discard_results(results)
+
+    def discard_results(self, results: Sequence[Any], *, strict: bool = False) -> None:
+        self._retry_pending(
+            "_pending_results",
+            results,
+            self.transfer.release_result,
+            "release DataProto read buffer",
+            attempts=2,
+            strict=strict,
+        )
+
+    def list(self, partition: str | None = None) -> dict[str, dict[str, Any]]:
+        return self._catalog_call("list", partition)
+
+    def remove(self, partition: str, keys: Sequence[str]) -> None:
+        self._cleanup_retired(self._catalog_call("remove", partition, keys))
+
+    def drain(self) -> None:
+        for attempt in range(2):
+            try:
+                self._retry_publications(strict=True)
+                self._cleanup_retired(self._catalog_call("drain"), strict=True)
+                return
+            except Exception:
+                if attempt:
+                    raise
+                logger.exception("Retrying DataProto Catalog drain")
+
+    def close(self) -> None:
+        self.discard_results((), strict=True)
+        self._retry_publications(strict=True)
+        self._retry_publication_acks(strict=True)
+
+    def _cleanup_retired(
+        self, result: Mapping[str, Any], *, strict: bool = False
+    ) -> None:
+        removed = []
+        failures = 0
+        for handle in result.get("retired_handles", ()):
+            try:
+                self.transfer.cleanup_dataproto(handle)
+            except Exception:
+                failures += 1
+                logger.exception("Failed to clean up retired DataProto fragment")
+            else:
+                removed.append(handle)
+        if removed:
+            try:
+                self._catalog_call("ack_retired", removed)
+            except Exception:
+                logger.exception("Failed to acknowledge retired DataProto fragments")
+                if strict:
+                    raise
+        if strict and failures:
+            raise RuntimeError(
+                f"failed to clean up {failures} retired DataProto fragment(s)"
+            )
+
+    def _publish(self, publication: Mapping[str, Any]) -> dict[str, Any]:
+        operation_id = publication["operation_id"]
+        result = self._catalog_call(
+            publication["method"],
+            operation_id,
+            *publication["args"],
+            **publication["kwargs"],
+        )
+        if publication["method"] == "publish_append" and result.get(
+            "append_rejected"
+        ):
+            self.transfer.cleanup_dataproto_append(
+                publication["kwargs"]["previous_handle"],
+                publication["kwargs"]["handle"],
+            )
+        self._cleanup_retired(result)
+        self._ack_publication(operation_id)
+        return result
+
+    def _ack_publication(self, operation_id: str) -> None:
+        try:
+            self._catalog_call("ack_publication", operation_id)
+        except Exception:
+            logger.exception("Failed to acknowledge DataProto Catalog publication")
+            with self._cleanup_lock:
+                if operation_id not in self._pending_publication_acks:
+                    self._pending_publication_acks.append(operation_id)
+
+    def _retry_publication_acks(self, *, strict: bool = False) -> None:
+        self._retry_pending(
+            "_pending_publication_acks",
+            (),
+            lambda operation_id: self._catalog_call("ack_publication", operation_id),
+            "acknowledge DataProto Catalog publication",
+            strict=strict,
+        )
+
+    def _retry_publications(self, *, strict: bool = False) -> None:
+        self._retry_pending(
+            "_pending_publications",
+            (),
+            self._publish,
+            "publish pending DataProto fragment",
+            strict=strict,
+        )
+
+    def _retry_pending(
+        self,
+        pending_attr: str,
+        items: Sequence[Any],
+        action: Callable[[Any], None],
+        label: str,
+        *,
+        attempts: int = 1,
+        strict: bool = False,
+    ) -> None:
+        with self._cleanup_lock:
+            pending = [*getattr(self, pending_attr), *items]
+            setattr(self, pending_attr, [])
+        for _attempt in range(attempts):
+            failed = []
+            for item in pending:
+                try:
+                    action(item)
+                except Exception:
+                    logger.exception("Failed to %s", label)
+                    failed.append(item)
+            pending = failed
+        with self._cleanup_lock:
+            getattr(self, pending_attr).extend(pending)
+            pending_count = len(getattr(self, pending_attr))
+        if strict and pending_count:
+            raise RuntimeError(f"failed to {label} for {pending_count} item(s)")
+
+
+def _normalize_handle(
+    handle: Mapping[str, Any],
+) -> tuple[Any, dict[str, Any]]:
+    from mooncake.structured_object_store import (
+        export_dataproto_ref,
+        import_dataproto_ref,
+    )
+
+    ref = import_dataproto_ref(handle)
+    return ref, export_dataproto_ref(ref)
+
+
+def _fragment(
+    handle: Mapping[str, Any], batch_size: int
+) -> tuple[str, dict[str, Any], tuple[str, ...]]:
+    ref, stored_handle = _normalize_handle(handle)
+    if len(ref.stage_refs) != 1:
+        raise ValueError("catalog fragments must contain exactly one DataProto stage")
+    fragment_id = _nonempty_string(
+        next(iter(ref.stage_refs.values())).manifest_key,
+        "manifest_key",
+    )
+    if ref.batch_size != batch_size:
+        raise ValueError(
+            f"DataProto batch size {ref.batch_size!r} does not match "
+            f"{batch_size} logical keys"
+        )
+    fields = _names(ref.field_index, "field names")
+    if not fields:
+        raise ValueError("DataProto catalog fragments cannot be empty")
+    return fragment_id, stored_handle, fields
+
+
+def _field_union(
+    entries: Mapping[str, Mapping[str, Any]], keys: Sequence[str]
+) -> list[str]:
+    return list(
+        dict.fromkeys(field for key in keys for field in entries[key]["fields"])
+    )
+
+
+def _names(values: Sequence[str] | Mapping[str, Any], label: str) -> tuple[str, ...]:
+    if isinstance(values, str):
+        raise ValueError(f"{label} must be a sequence of non-empty strings")
+    result = tuple(values)
+    if not result or any(not isinstance(value, str) or not value for value in result):
+        raise ValueError(f"{label} must be non-empty strings")
+    if len(result) != len(set(result)):
+        raise ValueError(f"{label} must be unique")
+    return result
+
+
+def _tags(
+    tags: Sequence[Mapping[str, Any]] | None, count: int
+) -> list[dict[str, Any]] | None:
+    if tags is None:
+        return None
+    if len(tags) != count:
+        raise ValueError("tags must have the same length as keys")
+    if any(not isinstance(tag, Mapping) for tag in tags):
+        raise TypeError("tags must be mappings")
+    return [copy.deepcopy(dict(tag)) for tag in tags]
+
+
+def _nonempty_string(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
diff --git a/mooncake-wheel/mooncake/ep.py b/mooncake-wheel/mooncake/ep.py
deleted file mode 100644
index 30fc3b5b94..0000000000
--- a/mooncake-wheel/mooncake/ep.py
+++ /dev/null
@@ -1,25 +0,0 @@
-import importlib
-import re
-
-import torch
-
-torch_version = re.match(r"\d+(?:\.\d+)*", torch.__version__).group()
-version_suffix = "_" + torch_version.replace(".", "_")
-
-try:
-    backend_module = importlib.import_module("mooncake.ep" + version_suffix)
-except ModuleNotFoundError:
-    raise ImportError(
-        f"Mooncake EP was not built against torch=={torch_version}.\n"
-        f"Open an issue at https://github.com/kvcache-ai/Mooncake/issues."
-    )
-globals().update({k: v for k, v in backend_module.__dict__.items() if not k.startswith("_")})
-
-try:
-    backend_compat_module = importlib.import_module("mooncake.pg" + version_suffix)
-except ModuleNotFoundError:
-    raise ImportError(
-        f"Mooncake EP was not built against torch=={torch_version}.\n"
-        f"Open an issue at https://github.com/kvcache-ai/Mooncake/issues."
-    )
-globals().update({k: v for k, v in backend_compat_module.__dict__.items() if not k.startswith("_")})
\ No newline at end of file
diff --git a/mooncake-wheel/mooncake/mooncake_elastic_buffer.py b/mooncake-wheel/mooncake/mooncake_elastic_buffer.py
deleted file mode 100644
index df751aef59..0000000000
--- a/mooncake-wheel/mooncake/mooncake_elastic_buffer.py
+++ /dev/null
@@ -1,582 +0,0 @@
-import os
-import warnings
-from typing import Any, List, Optional, Tuple, Union
-
-import torch
-import torch.distributed as dist
-
-from .mooncake_ep_buffer import EventOverlap
-
-
-def _using_musa_backend() -> bool:
-    return os.getenv("MOONCAKE_EP_USE_MUSA", "").upper() in {
-        "1",
-        "ON",
-        "TRUE",
-        "YES",
-    }
-
-
-def _dist_barrier(group: dist.ProcessGroup) -> None:
-    if _using_musa_backend():
-        dist.barrier(group=group, device_ids=[torch.cuda.current_device()])
-    else:
-        group.barrier()
-
-
-def _ceil_div(x: int, y: int) -> int:
-    return (x + y - 1) // y
-
-
-def _align(x: int, alignment: int) -> int:
-    return _ceil_div(x, alignment) * alignment
-
-
-class EPHandle:
-    """
-    Official DeepEP elastic-compatible communication handle.
-
-    The field names and semantics intentionally follow the official DeepEP elastic
-    handle contract so that model code can select Mooncake ElasticBuffer without
-    switching back to the legacy Buffer tuple handle.  Mooncake stores the native
-    legacy handle as an implementation detail while the elastic kernels are being
-    wired to the Device API backend.
-    """
-
-    def __init__(
-        self,
-        do_expand: bool,
-        num_experts: int,
-        expert_alignment: int,
-        num_max_tokens_per_rank: int,
-        num_sms: int,
-        topk_idx: torch.Tensor,
-        num_recv_tokens_per_expert_list: List[int],
-        psum_num_recv_tokens_per_scaleup_rank: torch.Tensor,
-        psum_num_recv_tokens_per_expert: torch.Tensor,
-        recv_src_metadata: torch.Tensor,
-        dst_buffer_slot_idx: torch.Tensor,
-        token_metadata_at_forward: Optional[torch.Tensor],
-        channel_linked_list: Optional[torch.Tensor],
-        native_handle: Optional[Tuple[Any, ...]] = None,
-    ) -> None:
-        assert topk_idx is not None
-        self.do_expand = do_expand
-        self.num_experts = num_experts
-        self.expert_alignment = expert_alignment
-        self.num_max_tokens_per_rank = num_max_tokens_per_rank
-        self.num_sms = num_sms
-        self.topk_idx = topk_idx
-        self.psum_num_recv_tokens_per_scaleup_rank = psum_num_recv_tokens_per_scaleup_rank
-        self.psum_num_recv_tokens_per_expert = psum_num_recv_tokens_per_expert
-        self.num_recv_tokens_per_expert_list = num_recv_tokens_per_expert_list
-        self.recv_src_metadata = recv_src_metadata
-        self.dst_buffer_slot_idx = dst_buffer_slot_idx
-        self.token_metadata_at_forward = token_metadata_at_forward
-        self.channel_linked_list = channel_linked_list
-        self.native_handle = native_handle
-
-        # Same convention as DeepEP: without a CPU sync this is an inferred upper
-        # bound; after CPU sync it tracks the actual received-token count.
-        self.num_recv_tokens = int(recv_src_metadata.shape[0])
-
-
-class ElasticBuffer:
-    """
-    Official DeepEP elastic EP API backed by Mooncake EP transports.
-
-    Public API source of truth: official DeepEP `ElasticBuffer`.  The implementation is
-    deliberately separate from Mooncake's legacy `Buffer` API, while reusing the
-    existing Mooncake Device API transport/bootstrap path for the native data
-    movement backend.
-    """
-
-    # Mirrors DeepEP's fixed workspace assumptions closely enough for sizing and
-    # keeping one reusable buffer for all elastic EP shapes.
-    _NUM_MAX_RANKS = 1024
-    _NUM_MAX_EXPERTS = 2048
-    _NUM_MAX_CHANNELS = 8 * 160
-    _NUM_BARRIER_TAGS = 16
-    _NUM_MAX_INFLIGHT_AGRS = 32
-
-    def __init__(
-        self,
-        group: dist.ProcessGroup,
-        num_bytes: Optional[int] = None,
-        num_max_tokens_per_rank: int = 0,
-        hidden: int = 0,
-        num_topk: int = 0,
-        use_fp8_dispatch: bool = False,
-        deterministic: bool = False,
-        allow_hybrid_mode: bool = True,
-        allow_multiple_reduction: bool = True,
-        prefer_overlap_with_compute: bool = True,
-        sl_idx: int = 3,
-        num_allocated_qps: int = 0,
-        num_cpu_timeout_secs: int = 300,
-        num_gpu_timeout_secs: int = 100,
-        explicitly_destroy: bool = False,
-    ) -> None:
-        if not allow_multiple_reduction:
-            raise NotImplementedError(
-                "Mooncake ElasticBuffer currently supports only "
-                "allow_multiple_reduction=True"
-            )
-        self.group = group
-        self.rank_idx = group.rank()
-        self.num_ranks = group.size()
-        self.allow_hybrid_mode = allow_hybrid_mode
-        self.allow_multiple_reduction = allow_multiple_reduction
-        self.prefer_overlap_with_compute = prefer_overlap_with_compute
-        self.deterministic = deterministic
-        self.sl_idx = int(os.getenv("EP_OVERRIDE_RDMA_SL", sl_idx))
-        self.num_allocated_qps = num_allocated_qps
-        self.num_cpu_timeout_secs = num_cpu_timeout_secs
-        self.num_gpu_timeout_secs = num_gpu_timeout_secs
-        self.explicitly_destroy = explicitly_destroy
-
-        self.num_max_tokens_per_rank = num_max_tokens_per_rank
-        self.hidden = hidden
-        self.num_topk = num_topk
-        self.use_fp8_dispatch = use_fp8_dispatch
-
-        if num_bytes is None:
-            num_bytes = self.get_buffer_size_hint(
-                group,
-                num_max_tokens_per_rank,
-                hidden,
-                num_topk=num_topk,
-                use_fp8_dispatch=use_fp8_dispatch,
-                allow_hybrid_mode=allow_hybrid_mode,
-                allow_multiple_reduction=allow_multiple_reduction,
-            )
-        self.num_bytes = num_bytes
-
-        (
-            self.num_scaleout_ranks,
-            self.num_scaleup_ranks,
-        ) = self._calculate_logical_domain_size(group, allow_hybrid_mode)
-        self.scaleout_rank_idx = self.rank_idx // self.num_scaleup_ranks
-        self.scaleup_rank_idx = self.rank_idx % self.num_scaleup_ranks
-        self.num_rdma_ranks, self.num_nvlink_ranks = self._calculate_physical_domain_size(group)
-
-        self.backend = group
-
-        # Native Mooncake transport/runtime.  This keeps the legacy Buffer ABI
-        # untouched while giving ElasticBuffer users a dedicated native entrypoint.
-        from mooncake import ep
-
-        self.runtime = ep.ElasticBuffer(
-            self.rank_idx,
-            self.num_ranks,
-            num_bytes,
-            num_max_tokens_per_rank,
-            hidden,
-            num_topk,
-            use_fp8_dispatch,
-            deterministic,
-            allow_hybrid_mode,
-            allow_multiple_reduction,
-            prefer_overlap_with_compute,
-            self.sl_idx,
-            num_allocated_qps,
-            num_cpu_timeout_secs,
-            num_gpu_timeout_secs,
-        )
-        self._connect_native()
-
-        torch.cuda.synchronize()
-        _dist_barrier(group)
-        torch.cuda.synchronize()
-
-    def _active_ranks_mask(self) -> list:
-        # `mooncake.ep.get_active_ranks` is a Mooncake PG helper and performs a
-        # native static cast to MooncakeBackend. ElasticBuffer transport
-        # bootstrap can also be driven by a regular NCCL/Gloo ProcessGroup; in
-        # that case every rank in the supplied group is active by definition.
-        if "Mooncake" not in type(self.backend).__name__:
-            return [1] * self.num_ranks
-
-        from mooncake.ep import get_active_ranks
-
-        return get_active_ranks(self.backend).tolist()
-
-    def _connect_native(self, is_update: bool = False) -> None:
-        from mooncake import ep
-
-        if not bool(self.runtime.ibgda_disabled()):
-            raddr, rkey = self.runtime.get_mr_info()
-            raddr_tensor = torch.tensor([raddr], dtype=torch.int64, device="cuda")
-            raddrs = [torch.empty(1, dtype=torch.int64, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_gather(raddrs, raddr_tensor, self.group)
-            raddrs_list = torch.cat(raddrs).tolist()
-
-            rkey_tensor = torch.tensor([rkey], dtype=torch.int32, device="cuda")
-            rkeys = [torch.empty(1, dtype=torch.int32, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_gather(rkeys, rkey_tensor, self.group)
-            rkeys_list = torch.cat(rkeys).tolist()
-
-            all_to_all_size = ep.MAX_QP_COUNT // self.num_ranks
-            if is_update:
-                self.runtime.update_local_qpns()
-
-            local_qpns = torch.tensor(self.runtime.get_local_qpns(), dtype=torch.int32, device="cuda").view(
-                -1, all_to_all_size
-            )
-            remote_qpns = [torch.empty(all_to_all_size, dtype=torch.int32, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_to_all(remote_qpns, list(torch.unbind(local_qpns)), self.group)
-            peer_qpns = [remote_qpns[r].tolist() for r in range(self.num_ranks)]
-
-            local_lids = torch.tensor(self.runtime.get_local_lids(), dtype=torch.int32, device="cuda").view(
-                -1, all_to_all_size
-            )
-            remote_lids = [torch.empty(all_to_all_size, dtype=torch.int32, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_to_all(remote_lids, list(torch.unbind(local_lids)), self.group)
-            peer_lids = [remote_lids[r].tolist() for r in range(self.num_ranks)]
-
-            subnet_prefix, interface_id = self.runtime.get_gid()
-            subnet_prefix_tensor = torch.tensor([subnet_prefix], dtype=torch.int64, device="cuda")
-            subnet_prefixes = [torch.empty(1, dtype=torch.int64, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_gather(subnet_prefixes, subnet_prefix_tensor, self.group)
-            subnet_prefixes_list = torch.cat(subnet_prefixes).tolist()
-
-            interface_id_tensor = torch.tensor([interface_id], dtype=torch.int64, device="cuda")
-            interface_ids = [torch.empty(1, dtype=torch.int64, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_gather(interface_ids, interface_id_tensor, self.group)
-            interface_ids_list = torch.cat(interface_ids).tolist()
-
-            active_ranks_mask = self._active_ranks_mask()
-            self.runtime.sync_ibgda_peers(
-                raddrs_list,
-                rkeys_list,
-                peer_qpns,
-                peer_lids,
-                subnet_prefixes_list,
-                interface_ids_list,
-                active_ranks_mask,
-            )
-
-        try:
-            local_handle_ints = self.runtime.get_ipc_handle()
-            local_handle_tensor = torch.tensor(local_handle_ints, dtype=torch.int32, device="cuda")
-            handles = [torch.empty(len(local_handle_ints), dtype=torch.int32, device="cuda") for _ in range(self.num_ranks)]
-            dist.all_gather(handles, local_handle_tensor, self.group)
-            remote_handles = [h.tolist() for h in handles]
-
-            active_ranks_mask = self._active_ranks_mask()
-            self.runtime.sync_nvlink_ipc_handles(remote_handles, active_ranks_mask)
-        except Exception as exc:
-            if bool(self.runtime.ibgda_disabled()):
-                raise RuntimeError(
-                    f"[Rank {self.rank_idx}] Failed to exchange IPC handles "
-                    "for ElasticBuffer and RDMA is disabled; native elastic "
-                    "mode cannot continue safely."
-                ) from exc
-            warnings.warn(
-                f"[Rank {self.rank_idx}] Failed to exchange IPC handles for ElasticBuffer: {exc}. "
-                "Continuing with RDMA-only routing.",
-                RuntimeWarning,
-                stacklevel=2,
-            )
-
-    def update_ep_member(self) -> None:
-        self._connect_native(True)
-
-    def destroy(self) -> None:
-        # Existing Mooncake Buffer owns native resources through object lifetime.
-        # Keep the method to match the official ElasticBuffer API.
-        self.runtime = None
-
-    @staticmethod
-    def _workspace_num_bytes() -> int:
-        num_bytes = 0
-        num_bytes += ElasticBuffer._NUM_BARRIER_TAGS * (
-            8 + 2 * ElasticBuffer._NUM_MAX_RANKS * 4
-        )
-        num_bytes += (ElasticBuffer._NUM_MAX_RANKS + ElasticBuffer._NUM_MAX_EXPERTS) * 8
-        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 8 * 2
-        num_bytes += ElasticBuffer._NUM_MAX_EXPERTS * 8 * 2
-        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 4
-        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 4 * 2
-        num_bytes += ElasticBuffer._NUM_MAX_EXPERTS * 4 * 2
-        num_bytes += ElasticBuffer._NUM_MAX_RANKS * ElasticBuffer._NUM_MAX_CHANNELS * 8
-        num_bytes += ElasticBuffer._NUM_MAX_RANKS * ElasticBuffer._NUM_MAX_CHANNELS * 4
-        num_bytes += 2 * 2 * 8
-        num_bytes += (ElasticBuffer._NUM_MAX_INFLIGHT_AGRS + 1) * ElasticBuffer._NUM_MAX_RANKS * 4
-        return _align(num_bytes, 32)
-
-    @staticmethod
-    def _atomic_scratch_num_bytes() -> int:
-        # Mirrors the native runtime: RDMA atomics need a local response area
-        # separate from the remote-visible workspace.
-        return ElasticBuffer._workspace_num_bytes()
-
-    @staticmethod
-    def get_buffer_size_hint(
-        group: dist.ProcessGroup,
-        num_max_tokens_per_rank: int,
-        hidden: int,
-        num_topk: int = 0,
-        use_fp8_dispatch: bool = False,
-        allow_hybrid_mode: bool = True,
-        allow_multiple_reduction: bool = True,
-    ) -> int:
-        try:
-            from mooncake import ep
-
-            return int(
-                ep.calculate_elastic_buffer_size(
-                    group.size(),
-                    num_max_tokens_per_rank,
-                    hidden,
-                    num_topk,
-                    use_fp8_dispatch,
-                    allow_hybrid_mode,
-                    allow_multiple_reduction,
-                )
-            )
-        except Exception:
-            pass
-
-        num_ranks = group.size()
-        num_topk = max(1, num_topk)
-        dtype_bytes = 1 if use_fp8_dispatch else 2
-        scale_bytes = _ceil_div(hidden, 128) * 4 if use_fp8_dispatch else 0
-        token_bytes = _align(hidden * dtype_bytes, 32) + _align(scale_bytes, 32)
-        metadata_bytes = _align(num_topk * (4 + 4) + (1 + num_topk) * 4, 32)
-        per_slot_bytes = token_bytes + metadata_bytes
-
-        # Direct elastic send/recv buffers plus room for combine reduce buffers.
-        dispatch_bytes = num_ranks * num_max_tokens_per_rank * num_topk * per_slot_bytes * 2
-        combine_factor = 3 if allow_multiple_reduction else 4
-        combine_bytes = dispatch_bytes * combine_factor
-        hybrid_factor = 2 if allow_hybrid_mode and num_ranks > 1 else 1
-        return int(
-            ElasticBuffer._workspace_num_bytes()
-            + ElasticBuffer._atomic_scratch_num_bytes()
-            + hybrid_factor * (dispatch_bytes + combine_bytes)
-        )
-
-    @staticmethod
-    def get_engram_storage_size_hint(
-        num_entries: int,
-        hidden: int,
-        num_max_tokens_per_rank: int,
-        dtype: torch.dtype = torch.bfloat16,
-    ) -> int:
-        num_sf_packs = _ceil_div(hidden, 128) if dtype.itemsize <= 1 else 0
-        num_bytes_per_entry = _align(hidden * dtype.itemsize + num_sf_packs * 4, 32)
-        return num_bytes_per_entry * (num_entries + num_max_tokens_per_rank)
-
-    @staticmethod
-    def get_pp_buffer_size_hint(num_max_tensor_bytes: int, num_max_inflight_tensors: int) -> int:
-        return _align(num_max_tensor_bytes, 32) * num_max_inflight_tensors * 2 * 2
-
-    @staticmethod
-    def get_agrs_buffer_size_hint(group: dist.ProcessGroup, num_max_session_bytes: int) -> int:
-        return num_max_session_bytes
-
-    @staticmethod
-    def _calculate_physical_domain_size(group: dist.ProcessGroup) -> Tuple[int, int]:
-        num_ranks = group.size()
-        num_local_ranks = int(os.getenv("MOONCAKE_EP_NUM_LOCAL_RANKS", "0"))
-        if num_local_ranks <= 0:
-            try:
-                num_local_ranks = max(1, min(num_ranks, torch.cuda.device_count()))
-            except Exception:
-                num_local_ranks = 1
-        num_local_ranks = max(1, min(num_local_ranks, num_ranks))
-        return _ceil_div(num_ranks, num_local_ranks), num_local_ranks
-
-    @staticmethod
-    def _calculate_logical_domain_size(group: dist.ProcessGroup, allow_hybrid_mode: bool = True) -> Tuple[int, int]:
-        num_ranks = group.size()
-        num_rdma_ranks, num_nvlink_ranks = ElasticBuffer._calculate_physical_domain_size(group)
-        if allow_hybrid_mode and num_rdma_ranks > 1:
-            return num_rdma_ranks, num_nvlink_ranks
-        return 1, num_ranks
-
-    def get_physical_domain_size(self) -> Tuple[int, int]:
-        return self.num_rdma_ranks, self.num_nvlink_ranks
-
-    def get_logical_domain_size(self) -> Tuple[int, int]:
-        return self.num_scaleout_ranks, self.num_scaleup_ranks
-
-    def barrier(self, use_comm_stream: bool = True, with_cpu_sync: bool = False) -> None:
-        if with_cpu_sync:
-            torch.cuda.synchronize()
-        _dist_barrier(self.group)
-        if with_cpu_sync:
-            torch.cuda.synchronize()
-
-    @staticmethod
-    def capture() -> Any:
-        from mooncake import ep
-
-        return ep.EventHandle()
-
-    def get_theoretical_num_sms(self, num_experts: int, num_topk: int) -> int:
-        device = torch.cuda.current_device()
-        sm_count = torch.cuda.get_device_properties(device).multi_processor_count
-        if self.prefer_overlap_with_compute:
-            return max(1, min(24, sm_count // 4))
-        return max(1, min(40, sm_count // 2, num_experts * max(1, num_topk)))
-
-    def dispatch(
-        self,
-        x: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
-        topk_idx: Optional[torch.Tensor] = None,
-        topk_weights: Optional[torch.Tensor] = None,
-        num_experts: Optional[int] = None,
-        num_max_tokens_per_rank: Optional[int] = None,
-        expert_alignment: Optional[int] = None,
-        handle: Optional[EPHandle] = None,
-        do_expand: bool = False,
-        do_cpu_sync: Optional[bool] = None,
-        num_sms: Optional[int] = None,
-        async_with_compute_stream: bool = False,
-    ) -> Tuple[Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]], Optional[torch.Tensor], Optional[torch.Tensor], EPHandle, EventOverlap]:
-        if self.runtime is None:
-            raise RuntimeError("ElasticBuffer has been destroyed")
-        if handle is not None:
-            if topk_idx is not None or topk_weights is not None:
-                raise AssertionError("topk_idx and topk_weights must be None when cached handle is provided")
-            if do_cpu_sync:
-                raise AssertionError("Cannot do CPU sync with cached handle")
-            if handle.native_handle is None:
-                raise RuntimeError("Cached EPHandle is missing its native Mooncake handle")
-            topk_idx = handle.topk_idx
-            num_max_tokens_per_rank = num_max_tokens_per_rank or handle.num_max_tokens_per_rank
-            num_experts = num_experts or handle.num_experts
-            expert_alignment = handle.expert_alignment if expert_alignment is None else expert_alignment
-            num_sms = handle.num_sms if num_sms is None else num_sms
-            do_cpu_sync = False
-        else:
-            if topk_idx is None:
-                raise AssertionError("topk_idx must be provided when cached handle is not provided")
-            expert_alignment = 1 if expert_alignment is None else expert_alignment
-            do_cpu_sync = True if do_cpu_sync is None else do_cpu_sync
-        if do_expand:
-            warnings.warn(
-                "do_expand=True was requested. Mooncake currently returns the native packed expert layout; "
-                "expanded contiguous expert layout will be produced by the native elastic kernels.",
-                RuntimeWarning,
-                stacklevel=2,
-            )
-
-        x_data = x[0] if isinstance(x, tuple) else x
-        sf = x[1] if isinstance(x, tuple) else None
-        if num_experts is None:
-            num_experts = int(torch.max(topk_idx).item()) + 1
-        if num_max_tokens_per_rank is None:
-            num_max_tokens_per_rank = self.num_max_tokens_per_rank or x_data.shape[0]
-        if num_sms is None:
-            num_sms = self.get_theoretical_num_sms(num_experts, topk_idx.shape[1])
-
-        active_ranks = torch.ones(self.num_ranks, dtype=torch.int32, device=x_data.device)
-        output = self.runtime.dispatch(
-            x_data,
-            sf,
-            topk_idx,
-            topk_weights,
-            active_ranks,
-            num_experts,
-            num_max_tokens_per_rank,
-            expert_alignment,
-            num_sms,
-            do_expand,
-            do_cpu_sync,
-            async_with_compute_stream,
-            handle.native_handle if handle is not None else None,
-        )
-        native_handle = output.handle
-
-        elastic_handle = EPHandle(
-            do_expand=native_handle.do_expand,
-            num_experts=native_handle.num_experts,
-            expert_alignment=native_handle.expert_alignment,
-            num_max_tokens_per_rank=native_handle.num_max_tokens_per_rank,
-            num_sms=native_handle.num_sms,
-            topk_idx=native_handle.topk_idx,
-            num_recv_tokens_per_expert_list=list(native_handle.num_recv_tokens_per_expert_list),
-            psum_num_recv_tokens_per_scaleup_rank=native_handle.psum_num_recv_tokens_per_scaleup_rank,
-            psum_num_recv_tokens_per_expert=native_handle.psum_num_recv_tokens_per_expert,
-            recv_src_metadata=native_handle.recv_src_metadata,
-            dst_buffer_slot_idx=native_handle.dst_buffer_slot_idx,
-            token_metadata_at_forward=native_handle.token_metadata_at_forward,
-            channel_linked_list=native_handle.channel_linked_list,
-            native_handle=native_handle,
-        )
-        recv_x = (output.recv_x, output.recv_x_scales) if output.recv_x_scales is not None else output.recv_x
-        tensors_to_record = (
-            x_data,
-            topk_idx,
-            active_ranks,
-            output.recv_x,
-            output.recv_topk_idx,
-            native_handle.topk_idx,
-            native_handle.psum_num_recv_tokens_per_scaleup_rank,
-            native_handle.psum_num_recv_tokens_per_expert,
-            native_handle.recv_src_metadata,
-            native_handle.dst_buffer_slot_idx,
-            *(() if sf is None else (sf,)),
-            *(() if topk_weights is None else (topk_weights,)),
-            *(() if output.recv_x_scales is None else (output.recv_x_scales,)),
-            *(() if output.recv_topk_weights is None else (output.recv_topk_weights,)),
-            *(() if native_handle.token_metadata_at_forward is None else (native_handle.token_metadata_at_forward,)),
-            *(() if native_handle.channel_linked_list is None else (native_handle.channel_linked_list,)),
-        )
-        return (
-            recv_x,
-            output.recv_topk_idx,
-            output.recv_topk_weights,
-            elastic_handle,
-            EventOverlap(output.event, tensors_to_record if async_with_compute_stream else None),
-        )
-
-    def combine(
-        self,
-        x: torch.Tensor,
-        handle: EPHandle,
-        topk_weights: Optional[torch.Tensor] = None,
-        num_sms: Optional[int] = None,
-        async_with_compute_stream: bool = False,
-    ) -> Tuple[torch.Tensor, Optional[torch.Tensor], EventOverlap]:
-        if self.runtime is None:
-            raise RuntimeError("ElasticBuffer has been destroyed")
-        if handle.native_handle is None:
-            raise RuntimeError("Mooncake EPHandle does not contain a native handle")
-        active_ranks = torch.ones(self.num_ranks, dtype=torch.int32, device=x.device)
-        if topk_weights is None:
-            topk_weights = torch.ones_like(handle.topk_idx, dtype=torch.float32, device=x.device)
-        output = self.runtime.combine(
-            x,
-            handle.native_handle,
-            topk_weights,
-            active_ranks,
-            num_sms if num_sms is not None else handle.num_sms,
-            async_with_compute_stream,
-            None,
-        )
-        native_handle = handle.native_handle
-        tensors_to_record = (
-            x,
-            topk_weights,
-            active_ranks,
-            output.combined_x,
-            native_handle.topk_idx,
-            native_handle.psum_num_recv_tokens_per_scaleup_rank,
-            native_handle.psum_num_recv_tokens_per_expert,
-            native_handle.recv_src_metadata,
-            native_handle.dst_buffer_slot_idx,
-            *(() if native_handle.token_metadata_at_forward is None else (native_handle.token_metadata_at_forward,)),
-            *(() if native_handle.channel_linked_list is None else (native_handle.channel_linked_list,)),
-        )
-        return (
-            output.combined_x,
-            output.combined_topk_weights,
-            EventOverlap(output.event, tensors_to_record if async_with_compute_stream else None),
-        )
-
-
-__all__ = ["ElasticBuffer", "EPHandle", "EventOverlap"]
diff --git a/mooncake-wheel/mooncake/mooncake_store_service.py b/mooncake-wheel/mooncake/mooncake_store_service.py
index a78bfb4659..b5bc66b2de 100644
--- a/mooncake-wheel/mooncake/mooncake_store_service.py
+++ b/mooncake-wheel/mooncake/mooncake_store_service.py
@@ -12,6 +12,11 @@
 from mooncake.store import MooncakeDistributedStore
 from mooncake.mooncake_config import MooncakeConfig
 
+# Caps a caller's /api/unmount_local_disk grace period so a malformed value
+# (e.g. milliseconds passed where seconds are expected) blocks a preStop hook
+# for minutes rather than hours.
+_MAX_UNMOUNT_LOCAL_DISK_GRACE_PERIOD_SECONDS = 3600
+
 
 def _timed_handler(operation_name, handler):
     async def wrapper(request):
@@ -251,6 +256,12 @@ async def start_http_service(self, port: int = 8080):
                 web.post(
                     "/api/unmount", _timed_handler("UNMOUNT", self.handle_unmount)
                 ),
+                web.post(
+                    "/api/unmount_local_disk",
+                    _timed_handler(
+                        "UNMOUNT_LOCAL_DISK", self.handle_unmount_local_disk
+                    ),
+                ),
                 web.put("/api/put", _timed_handler("PUT", self.handle_put)),
                 web.get("/api/get/{key}", _timed_handler("GET", self.handle_get)),
                 web.get("/api/exist/{key}", _timed_handler("EXIST", self.handle_exist)),
@@ -614,6 +625,74 @@ async def handle_unmount(self, request):
                 content_type="application/json",
             )
 
+    async def handle_unmount_local_disk(self, request):
+        """Deregister this store's SSD offload tier before the process goes away.
+
+        Meant for a preStop hook. The master stops naming this store as the
+        owner of its offloaded keys, so a reader gets a clean miss instead of a
+        peer that is about to disappear; the call then holds for
+        grace_period_seconds so offload reads already in flight finish here.
+        Runs off the event loop because that wait is seconds long.
+        """
+        try:
+            data = await request.json()
+        except Exception:
+            return web.Response(
+                status=400,
+                text=json.dumps({"error": "Malformed JSON body"}),
+                content_type="application/json",
+            )
+        if not isinstance(data, dict):
+            return web.Response(
+                status=400,
+                text=json.dumps({"error": "Request body must be a JSON object"}),
+                content_type="application/json",
+            )
+
+        grace_period_seconds = data.get("grace_period_seconds", 0)
+        if (
+            type(grace_period_seconds) is not int
+            or grace_period_seconds < 0
+            or grace_period_seconds > _MAX_UNMOUNT_LOCAL_DISK_GRACE_PERIOD_SECONDS
+        ):
+            return web.Response(
+                status=400,
+                text=json.dumps(
+                    {
+                        "error": (
+                            "Invalid grace_period_seconds, must be a non-negative "
+                            "integer no greater than "
+                            f"{_MAX_UNMOUNT_LOCAL_DISK_GRACE_PERIOD_SECONDS}"
+                        )
+                    }
+                ),
+                content_type="application/json",
+            )
+
+        try:
+            ret = await asyncio.to_thread(
+                self.store.unmount_local_disk_segment, grace_period_seconds
+            )
+            if ret != 0:
+                return web.Response(
+                    status=500,
+                    text=json.dumps({"error": f"Unmount local disk failed, ret={ret}"}),
+                    content_type="application/json",
+                )
+
+            return web.Response(
+                status=200,
+                text=json.dumps({"status": "success"}),
+                content_type="application/json",
+            )
+        except Exception as e:
+            logging.error("UNMOUNT_LOCAL_DISK error: %s", e)
+            return web.Response(
+                status=500,
+                text=json.dumps({"error": str(e)}),
+                content_type="application/json",
+            )
+
     async def handle_put(self, request):
         try:
             data = await request.json()
diff --git a/mooncake-wheel/mooncake/structured_object_store.py b/mooncake-wheel/mooncake/structured_object_store.py
index 9b6a7fbda9..7069be1ce0 100644
--- a/mooncake-wheel/mooncake/structured_object_store.py
+++ b/mooncake-wheel/mooncake/structured_object_store.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 import ctypes
 import io
 import json
@@ -7,6 +8,7 @@
 from concurrent.futures import Future, ThreadPoolExecutor, as_completed
 from contextlib import contextmanager
 from dataclasses import dataclass, field
+from types import SimpleNamespace
 from typing import Any, Callable, Iterator, Literal, Mapping, Optional, Protocol, Sequence
 
 import numpy as np
@@ -31,6 +33,8 @@
     -704
 )  # Mooncake remove returns -704 for an already-missing object.
 STRUCTURED_FIELD_SPECS_KEY = "__mooncake_structured_fields__"
+_TYPED_RAGGED_DEFAULT_DTYPE = "int64"
+_RAGGED_TENSOR_DEFAULT_DTYPE = "torch.float32"
 _ENCODING_FALLBACK_ERRORS = (
     TypeError,
     ValueError,
@@ -47,6 +51,8 @@ def get(self, key: str) -> bytes: ...
 
     def remove(self, key: str, force: bool = False) -> int: ...
 
+    def is_exist(self, key: str) -> int: ...
+
 
 @dataclass(frozen=True)
 class BundleTransferPolicy:
@@ -125,6 +131,7 @@ class MooncakeDataProtoRef:
     partition: str = "default"
     global_indexes: list[int] | None = None
     encoded_non_tensor: dict[str, Any] = field(default_factory=dict)
+    _storage_group_id: str | None = field(default=None, repr=False)
 
 
 @dataclass(frozen=True)
@@ -304,6 +311,8 @@ class _DataProtoRowSelection:
 
 DATAPROTO_REF_HANDLE_TYPE = "mooncake_dataproto_ref"
 DATAPROTO_REF_HANDLE_VERSION = 1
+# Optional v1 extension; older readers ignore unknown top-level fields.
+STORAGE_GROUP_ID = "storage_group_id"
 DataProtoRefLike = MooncakeDataProtoRef | Mapping[str, Any]
 
 
@@ -338,6 +347,8 @@ def export_dataproto_ref(ref: MooncakeDataProtoRef) -> dict[str, Any]:
         "meta_info": _json_safe_value(ref.meta_info),
         "encoded_non_tensor": _json_safe_value(ref.encoded_non_tensor),
     }
+    if ref._storage_group_id is not None:
+        handle[STORAGE_GROUP_ID] = ref._storage_group_id
     json.dumps(handle, ensure_ascii=False)
     return handle
 
@@ -346,7 +357,8 @@ def import_dataproto_ref(handle: Mapping[str, Any]) -> MooncakeDataProtoRef:
     """Import a JSON-safe DataProto transport handle into a lazy ref."""
     if not is_dataproto_ref_handle(handle):
         raise ValueError("not a Mooncake DataProto ref handle")
-    if int(handle.get("version", -1)) != DATAPROTO_REF_HANDLE_VERSION:
+    version = int(handle.get("version", -1))
+    if version not in (DATAPROTO_REF_HANDLE_VERSION, 2):
         raise ValueError(
             f"unsupported DataProto ref handle version: {handle.get('version')!r}"
         )
@@ -361,9 +373,14 @@ def import_dataproto_ref(handle: Mapping[str, Any]) -> MooncakeDataProtoRef:
         manifest_key = _require_mapping(stage_ref, f"stage_refs[{stage!r}]").get(
             "manifest_key"
         )
-        if not isinstance(stage, str) or not isinstance(manifest_key, str):
+        if (
+            not isinstance(stage, str)
+            or not stage
+            or not isinstance(manifest_key, str)
+            or not manifest_key
+        ):
             raise ValueError(
-                "DataProto ref handle stage refs must contain string manifest_key values"
+                "DataProto ref handle stage refs must contain non-empty string names and manifest_key values"
             )
         stage_refs[stage] = RemoteBundleRef(manifest_key=manifest_key, manifest={})
     field_index: dict[str, StructuredFieldLocation] = {}
@@ -378,10 +395,15 @@ def import_dataproto_ref(handle: Mapping[str, Any]) -> MooncakeDataProtoRef:
         member = location.get("member")
         if (
             not isinstance(name, str)
+            or not name
             or not isinstance(stage, str)
+            or not stage
             or not isinstance(member, str)
+            or not member
         ):
-            raise ValueError("DataProto ref handle field locations must be strings")
+            raise ValueError(
+                "DataProto ref handle field locations must be non-empty strings"
+            )
         if stage not in stage_refs:
             raise ValueError(
                 f"DataProto ref handle field {name!r} references unknown stage {stage!r}"
@@ -389,6 +411,12 @@ def import_dataproto_ref(handle: Mapping[str, Any]) -> MooncakeDataProtoRef:
         field_index[name] = StructuredFieldLocation(
             stage=stage, member=member, section=section
         )
+    storage_group_id = handle.get(STORAGE_GROUP_ID)
+    if (version == 2 and storage_group_id is None) or (
+        storage_group_id is not None
+        and (not isinstance(storage_group_id, str) or not storage_group_id)
+    ):
+        raise ValueError("DataProto ref handle has invalid storage_group_id")
     return MooncakeDataProtoRef(
         batch_size=int(handle["batch_size"]),
         stage_refs=stage_refs,
@@ -400,6 +428,7 @@ def import_dataproto_ref(handle: Mapping[str, Any]) -> MooncakeDataProtoRef:
         encoded_non_tensor=dict(
             _require_mapping(handle.get("encoded_non_tensor", {}), "encoded_non_tensor")
         ),
+        _storage_group_id=storage_group_id,
     )
 
 
@@ -477,6 +506,35 @@ def __init__(
         )
         self._structured_store = _StructuredObjectLayer(self._bundle_store)
 
+    def _new_storage_group_id(self, config: Any) -> str | None:
+        raw_group_ids = getattr(config, "group_ids", None)
+        if raw_group_ids is None:
+            group_id = None
+        elif isinstance(raw_group_ids, str):
+            group_id = raw_group_ids
+        else:
+            try:
+                group_ids = list(raw_group_ids)
+            except TypeError as error:
+                raise ValueError(
+                    "structured object store config.group_ids must contain strings"
+                ) from error
+            if len(group_ids) > 1:
+                raise ValueError(
+                    "structured object store config.group_ids must contain exactly one "
+                    "logical group id; it is expanded across internal Mooncake keys"
+                )
+            group_id = group_ids[0] if group_ids else None
+        if group_id is None:
+            return f"structured-{uuid.uuid4().hex}"
+        if not isinstance(group_id, str):
+            raise ValueError(
+                "structured object store config.group_ids must contain strings"
+            )
+        if group_id == "":
+            return None
+        return group_id
+
     def put_bundle(
         self,
         meta: bytes | bytearray | memoryview,
@@ -502,6 +560,58 @@ def remove_bundle(self, ref: RemoteBundleRef | Mapping[str, Any]) -> None:
         """Remove all Mooncake objects that belong to a stored bundle."""
         self._bundle_store.remove_bundle(ref)
 
+    def cleanup_dataproto_append(
+        self, previous: DataProtoRefLike, appended: DataProtoRefLike
+    ) -> None:
+        """Remove an unpublished append without touching the previous handle."""
+        previous = _resolve_dataproto_ref(previous)
+        appended = _resolve_dataproto_ref(appended)
+        for stage, stage_ref in appended.stage_refs.items():
+            previous_stage_ref = previous.stage_refs.get(stage)
+            if previous_stage_ref is None:
+                self.remove_bundle(stage_ref)
+                continue
+            if stage_ref.manifest_key == previous_stage_ref.manifest_key:
+                continue
+
+            is_exist = getattr(self.store, "is_exist", None)
+            if callable(is_exist) and is_exist(stage_ref.manifest_key) == 0:
+                continue
+            new_manifest = self._bundle_store.resolve_manifest(stage_ref)
+            old_buffer_names = {
+                location.member
+                for location in previous.field_index.values()
+                if location.stage == stage
+            }
+            for name, encoded in previous.encoded_non_tensor.items():
+                if previous.field_index[name].stage == stage:
+                    old_buffer_names.update(encoded["payload_members"].values())
+            new_payloads = [
+                payload
+                for name, payload in new_manifest["buffers"].items()
+                if name not in old_buffer_names
+            ]
+            new_object_ids = {
+                self._bundle_store._object_id_from_bundle_key(payload["key"])
+                for payload in new_payloads
+            }
+            cleanup_keys = [
+                *self._bundle_store.payload_keys(new_manifest["meta"]),
+                *[
+                    chunk["key"]
+                    for payload in new_payloads
+                    for chunk in payload["chunks"]
+                ],
+            ]
+            cleanup_keys.extend(
+                key
+                for key in new_manifest.get("cleanup_keys", [])
+                if self._bundle_store._object_id_from_bundle_key(key)
+                in new_object_ids
+            )
+            self._bundle_store.remove_keys(cleanup_keys, strict=True)
+            self._bundle_store.remove_keys([stage_ref.manifest_key], strict=True)
+
     def put_structured_object(
         self,
         payload: StructuredObjectPayload,
@@ -602,6 +712,12 @@ def visit(value: Any) -> None:
             items_to_visit = None
             if isinstance(value, Mapping):
                 items_to_visit = value.values()
+            elif hasattr(value, "batch") and hasattr(value, "non_tensor_batch"):
+                items_to_visit = (
+                    value.batch,
+                    value.non_tensor_batch,
+                    getattr(value, "meta_info", None),
+                )
             elif isinstance(value, (list, tuple)):
                 items_to_visit = value
             elif isinstance(value, np.ndarray) and value.dtype == object:
@@ -666,7 +782,7 @@ def get(
         """Materialize a DataProto-like object or flat dict."""
         if type not in {"dataproto", "dict"}:
             raise ValueError(f"unsupported Mooncake payload type: {type!r}")
-        result = self.get_dataproto(
+        result = self._get_dataproto(
             ref,
             fields=fields,
             batch_fields=batch_fields,
@@ -675,6 +791,7 @@ def get(
             data_cls=dict if type == "dict" else data_cls,
             destinations=destinations,
             rows=rows,
+            _flat_dict_output=(type == "dict"),
         )
         return _envelope_to_flat_dict(result) if type == "dict" else result
 
@@ -746,6 +863,31 @@ def get_dataproto(
         data_cls: Optional[Any] = None,
         destinations: Optional[Mapping[str, Any]] = None,
         rows: slice | StructuredMemberSlice | Sequence[int] | None = None,
+    ) -> Any:
+        """Materialize selected DataProto fields from structured object refs."""
+        return self._get_dataproto(
+            ref,
+            fields=fields,
+            batch_fields=batch_fields,
+            non_tensor_fields=non_tensor_fields,
+            meta_info_keys=meta_info_keys,
+            data_cls=data_cls,
+            destinations=destinations,
+            rows=rows,
+        )
+
+    def _get_dataproto(
+        self,
+        ref: DataProtoRefLike,
+        *,
+        fields: Optional[Sequence[str]] = None,
+        batch_fields: Optional[Sequence[str]] = None,
+        non_tensor_fields: Optional[Sequence[str]] = None,
+        meta_info_keys: Optional[Sequence[str]] = None,
+        data_cls: Optional[Any] = None,
+        destinations: Optional[Mapping[str, Any]] = None,
+        rows: slice | StructuredMemberSlice | Sequence[int] | None = None,
+        _flat_dict_output: bool = False,
     ) -> Any:
         """Materialize selected DataProto fields from structured object refs."""
         ref = _resolve_dataproto_ref(ref)
@@ -812,41 +954,61 @@ def get_dataproto(
                     batch[name] = value
                 else:
                     non_tensor_batch[name] = value
-        for name, location in encoded_requests:
-            stage_ref = ref.stage_refs[location.stage]
-            encoded = ref.encoded_non_tensor[name]
-            if row_selection is None:
-                members = list(encoded["payload_members"].values())
+        if row_selection is None and encoded_requests:
+            by_stage_encoded: dict[str, list[tuple[str, StructuredFieldLocation]]] = {}
+            for name, location in encoded_requests:
+                by_stage_encoded.setdefault(location.stage, []).append((name, location))
+            for stage, entries in by_stage_encoded.items():
+                stage_ref = ref.stage_refs[stage]
+                members: list[str] = []
+                for name, _location in entries:
+                    encoded = ref.encoded_non_tensor[name]
+                    members.extend(encoded["payload_members"].values())
                 result = self.materialize(
                     self.read_spec(stage_ref).select_members(members)
                 )
-                payload = {
-                    payload_name: result.objects[member]
-                    for payload_name, member in encoded["payload_members"].items()
-                }
-                values = _decode_structured_non_tensor_encoded(
-                    encoded, payload, ref.batch_size, encoded.get("metadata")
-                )
-            elif row_indices is not None:
-                payload, metadata = self._read_structured_non_tensor_payload_indices(
-                    stage_ref,
-                    encoded,
-                    row_indices,
-                )
-                values = _decode_structured_non_tensor_encoded(
-                    encoded, payload, output_rows, metadata
-                )
-            else:
-                payload, metadata = self._read_structured_non_tensor_payload_slice(
-                    stage_ref,
-                    encoded,
-                    row_slice,
-                    ref.batch_size,
-                )
-                values = _decode_structured_non_tensor_encoded(
-                    encoded, payload, output_rows, metadata
+                for name, _location in entries:
+                    encoded = ref.encoded_non_tensor[name]
+                    payload = {
+                        payload_name: result.objects[member]
+                        for payload_name, member in encoded["payload_members"].items()
+                    }
+                    values = _decode_structured_non_tensor_encoded(
+                        encoded, payload, ref.batch_size, encoded.get("metadata")
+                    )
+                    non_tensor_batch[name] = (
+                        values
+                        if _flat_dict_output
+                        else _object_array_from_decoded_values(values)
+                    )
+        else:
+            for name, location in encoded_requests:
+                stage_ref = ref.stage_refs[location.stage]
+                encoded = ref.encoded_non_tensor[name]
+                if row_indices is not None:
+                    payload, metadata = self._read_structured_non_tensor_payload_indices(
+                        stage_ref,
+                        encoded,
+                        row_indices,
+                    )
+                    values = _decode_structured_non_tensor_encoded(
+                        encoded, payload, output_rows, metadata
+                    )
+                else:
+                    payload, metadata = self._read_structured_non_tensor_payload_slice(
+                        stage_ref,
+                        encoded,
+                        row_slice,
+                        ref.batch_size,
+                    )
+                    values = _decode_structured_non_tensor_encoded(
+                        encoded, payload, output_rows, metadata
+                    )
+                non_tensor_batch[name] = (
+                    values
+                    if _flat_dict_output
+                    else _object_array_from_decoded_values(values)
                 )
-            non_tensor_batch[name] = _object_array_from_decoded_values(values)
         meta_info = _select_mapping(ref.meta_info, meta_info_keys)
         return _build_dataproto_like_result(
             batch, non_tensor_batch, meta_info, data_cls
@@ -871,6 +1033,12 @@ def _read_dataproto_member_indices(
                 member, payload_spec, field_spec, indices, destination
             )
         if encoding == "torch_tensor":
+            if field_spec.get("nested"):
+                result = self.materialize_into(
+                    self.read_spec(stage_ref).select_members([member]),
+                    None if destination is None else {member: destination},
+                )
+                return _select_nested_tensor_rows(result.objects[member], indices)
             return self._read_torch_tensor_member_indices(
                 member, payload_spec, field_spec, indices, destination
             )
@@ -945,6 +1113,15 @@ def _read_torch_tensor_member_indices(
         indices: Sequence[int],
         destination: Any,
     ) -> Any:
+        if payload_spec.get("format") == "torch_save":
+            if destination is not None:
+                raise ValueError(
+                    f"structured torch_save tensor member {name} does not support destinations"
+                )
+            value = _deserialize_torch_save_payload(
+                self._bundle_store.read_payload(payload_spec)
+            )
+            return value[list(indices)]
         metadata_bytes = int(payload_spec.get("metadata_bytes", -1))
         shape = field_spec.get("shape")
         element_size = int(field_spec.get("element_size", 0))
@@ -1424,16 +1601,20 @@ def _append_dataproto_stage_manifest(
             if collisions:
                 raise ValueError(f"structured members already exist: {collisions}")
             merged_buffers.update(new_manifest["buffers"])
+            cleanup_keys = [
+                *old_manifest.get("cleanup_keys", []),
+                self._bundle_store.manifest_key(old_stage_ref),
+                *self._bundle_store.payload_keys(old_manifest["meta"]),
+                self._bundle_store.manifest_key(new_stage_ref),
+                *self._bundle_store.payload_keys(new_manifest["meta"]),
+            ]
             merged_ref = self._bundle_store.put_bundle_manifest(
                 _encode_structured_metadata(merged_metadata),
                 merged_buffers,
                 partition=partition,
                 chunk_bytes=chunk_bytes,
                 policy=policy,
-                cleanup_keys=[
-                    self._bundle_store.manifest_key(old_stage_ref),
-                    *self._bundle_store.payload_keys(old_manifest["meta"]),
-                ],
+                cleanup_keys=cleanup_keys,
                 config=config,
             )
         except Exception:
@@ -1540,7 +1721,9 @@ def _put_dataproto_stage(
                     partition=ref.partition,
                     global_indexes=ref.global_indexes,
                     encoded_non_tensor=dict(ref.encoded_non_tensor),
+                    _storage_group_id=ref._storage_group_id,
                 )
+            group_id = self._new_storage_group_id(config)
             return MooncakeDataProtoRef(
                 batch_size=batch_size,
                 stage_refs={},
@@ -1549,6 +1732,7 @@ def _put_dataproto_stage(
                 namespace=namespace,
                 partition=partition,
                 encoded_non_tensor={},
+                _storage_group_id=group_id,
             )
         duplicates = (
             sorted(set(ref.field_index) & set(field_updates)) if ref is not None else []
@@ -1565,6 +1749,20 @@ def _put_dataproto_stage(
                 raise ValueError(
                     f"DataProto overwrite for stage {stage!r} must include existing fields: {sorted(dangling)}"
                 )
+        if ref is None:
+            group_id = self._new_storage_group_id(config)
+            effective_config = (
+                config
+                if group_id is None
+                else _config_with_group_id(config, group_id)
+            )
+        else:
+            group_id = ref._storage_group_id
+            effective_config = (
+                config
+                if group_id is None
+                else _config_with_group_id(config, group_id)
+            )
         payload = StructuredObjectPayload(
             metadata={
                 "layout": "dataproto_stage",
@@ -1586,7 +1784,7 @@ def _put_dataproto_stage(
                 partition=partition,
                 chunk_bytes=chunk_bytes,
                 policy=policy,
-                config=config,
+                config=effective_config,
             )
         else:
             stage_ref = self.put_structured_object(
@@ -1594,7 +1792,7 @@ def _put_dataproto_stage(
                 partition=partition,
                 chunk_bytes=chunk_bytes,
                 policy=policy,
-                config=config,
+                config=effective_config,
             )
             if (
                 existing_stage_ref is not None
@@ -1627,6 +1825,7 @@ def _put_dataproto_stage(
             partition=partition,
             global_indexes=None if ref is None else ref.global_indexes,
             encoded_non_tensor=encoded_non_tensor,
+            _storage_group_id=group_id,
         )
 
 
@@ -1875,7 +2074,7 @@ def _envelope_to_flat_dict(data: Mapping[str, Any]) -> dict[str, Any]:
     result.update(batch)
     for name, value in non_tensor_batch.items():
         result[name] = (
-            list(value)
+            value.tolist()
             if isinstance(value, np.ndarray) and value.dtype == object
             else value
         )
@@ -2592,81 +2791,57 @@ def _encode_ragged_tensor_values(
 ) -> tuple[dict[str, Any], dict[str, Any]]:
     if _torch is None:
         raise RuntimeError("torch is required to encode ragged tensor fields")
-    tensors: list[Any] = []
-    dtype = None
-    max_ndim = 0
+    # Determine torch dtype and convert all values to numpy arrays.
+    torch_dtype = None
+    converted: list[Any] = []
     for value in values:
         if value is None:
-            tensors.append(None)
+            converted.append(None)
             continue
-        tensor = value.detach()
+        if isinstance(value, np.ndarray):
+            if value.dtype == object:
+                raise ValueError("ragged tensor codec requires numeric ndarray values")
+            if not value.flags.writeable:
+                value = value.copy()
+            tensor = _torch.as_tensor(value)
+        else:
+            tensor = value.detach()
         if tensor.device.type != "cpu" or not tensor.is_contiguous():
             tensor = tensor.cpu().contiguous()
-        dtype = tensor.dtype if dtype is None else dtype
-        if tensor.dtype != dtype:
-            raise ValueError(f"mixed tensor dtype: {dtype} vs {tensor.dtype}")
-        max_ndim = max(max_ndim, tensor.dim())
-        tensors.append(tensor)
-    offsets = _torch.zeros(len(tensors) + 1, dtype=_torch.int64)
-    ndims = _torch.zeros(len(tensors), dtype=_torch.int16)
-    shapes = _torch.zeros((len(tensors), max(max_ndim, 1)), dtype=_torch.int64)
-    nulls = np.asarray([tensor is None for tensor in tensors], dtype=np.bool_)
-    flat_parts = []
-    offset = 0
-    for row, tensor in enumerate(tensors):
-        if tensor is None:
-            offsets[row + 1] = offset
-            continue
-        flat = tensor.reshape(-1)
-        flat_parts.append(flat)
-        offset += flat.numel()
-        offsets[row + 1] = offset
-        ndims[row] = tensor.dim()
-        if tensor.dim() > 0:
-            shapes[row, : tensor.dim()] = _torch.tensor(
-                list(tensor.shape), dtype=_torch.int64
-            )
-    data_dtype = dtype or _torch.float32
-    data = (
-        _torch.cat(flat_parts) if flat_parts else _torch.empty((0,), dtype=data_dtype)
-    )
-    payload = {
-        "data": data.numpy(),
-        "offsets": offsets.numpy(),
-        "shapes": shapes.numpy(),
-        "ndims": ndims.numpy(),
-        "nulls": nulls,
-    }
-    return payload, {
-        "dtype": str(data_dtype),
-        "max_ndim": int(max_ndim),
-        "shape_policy": "ragged",
-    }
-
+        if tensor.dtype == _torch.bfloat16:
+            raise ValueError("ragged tensor codec does not support torch.bfloat16")
+        torch_dtype = tensor.dtype if torch_dtype is None else torch_dtype
+        if tensor.dtype != torch_dtype:
+            raise ValueError(f"mixed tensor dtype: {torch_dtype} vs {tensor.dtype}")
+        converted.append(tensor.numpy())
+    data_dtype = torch_dtype or _parse_torch_dtype(_RAGGED_TENSOR_DEFAULT_DTYPE)
+    np_dtype = np.dtype(_torch_dtype_to_numpy(str(data_dtype)))
+    payload, meta = _encode_typed_ragged_values(converted, np_dtype)
+    meta["dtype"] = str(data_dtype)
+    return payload, meta
 
 def _decode_ragged_tensor_values(
-    payload: dict[str, Any],
-    rows: int,
-    metadata: Optional[Mapping[str, Any]] = None,
+    payload: dict[str, Any], rows: int, metadata: Optional[Mapping[str, Any]] = None
 ) -> list[Any]:
     if _torch is None:
         raise RuntimeError("torch is required to decode ragged tensor fields")
-    data = _torch.from_numpy(payload["data"])
-    offsets = payload["offsets"]
-    shapes = payload["shapes"]
-    ndims = payload["ndims"]
-    nulls = payload["nulls"]
-    values = []
-    for row in range(rows):
-        if bool(nulls[row]):
-            values.append(None)
-            continue
-        begin = int(offsets[row])
-        end = int(offsets[row + 1])
-        ndim = int(ndims[row])
-        shape = tuple(int(v) for v in shapes[row, :ndim].tolist())
-        values.append(data[begin:end].reshape(shape))
-    return values
+    # Metadata stores torch dtype strings (e.g. "torch.int64"); convert to numpy
+    # dtype so _decode_typed_ragged_values can parse it.
+    dtype_str = (metadata or {}).get("dtype", _RAGGED_TENSOR_DEFAULT_DTYPE)
+    np_dtype = _torch_dtype_to_numpy(dtype_str)
+    patched_meta = dict(metadata) if metadata else {}
+    patched_meta["dtype"] = str(np_dtype)
+    np_values = _decode_typed_ragged_values(payload, rows, patched_meta)
+    torch_dtype = _parse_torch_dtype(dtype_str)
+    result: list[Any] = []
+    for v in np_values:
+        if v is None:
+            result.append(None)
+        elif isinstance(v, np.ndarray):
+            result.append(_torch.from_numpy(v).to(torch_dtype))
+        else:
+            result.append(_torch.as_tensor(v, dtype=torch_dtype))
+    return result
 
 def _normalize_ragged_tensor_dict_keys(keys: Any) -> list[str]:
     if isinstance(keys, Mapping):
@@ -2813,15 +2988,20 @@ def _encode_typed_ragged_values(
 ) -> tuple[dict[str, Any], dict[str, Any]]:
     if dtype_hint is None:
         source_arrays = [np.asarray(value) for value in values if value is not None]
-        dtype = np.result_type(*source_arrays) if source_arrays else np.dtype(np.int64)
+        dtype = np.result_type(*source_arrays) if source_arrays else np.dtype(_TYPED_RAGGED_DEFAULT_DTYPE)
     else:
         dtype = np.dtype(dtype_hint)
     if dtype.hasobject:
         raise ValueError("typed_ragged codec requires non-object dtype")
+
+    ndarray_encoded = _encode_typed_ragged_ndarray_rows(values, dtype)
+    if ndarray_encoded is not None:
+        return ndarray_encoded
+
     arrays = [
         np.asarray([], dtype=dtype)
         if value is None
-        else np.ascontiguousarray(np.asarray(value, dtype=dtype))
+        else _as_contiguous_array_preserve_ndim(value, dtype)
         for value in values
     ]
     max_ndim = max((array.ndim for array in arrays), default=0)
@@ -2839,27 +3019,33 @@ def _encode_typed_ragged_values(
         ndims[row] = array.ndim
         if array.ndim > 0:
             shapes[row, : array.ndim] = array.shape
+    total_elems = int(offset)
     if flat_arrays:
         if _concat_arrays_into is not None:
-            data = _DirectCopyPayload.from_flat_arrays(
-                flat_arrays, dtype, int(offset)
-            )
+            data = _DirectCopyPayload.from_flat_arrays(flat_arrays, dtype, total_elems)
         else:
             buffers = tuple(memoryview(flat.data).cast("B") for flat in flat_arrays)
             data = _MultiBufferPayload(
                 buffers=buffers,
                 owners=tuple(flat_arrays),
                 dtype=np.dtype(dtype).str,
-                shape=(int(offset),),
+                shape=(total_elems,),
             )
     else:
         empty = np.empty(0, dtype=dtype)
         data = _MultiBufferPayload(
-            buffers=(memoryview(empty.data).cast("B"),),
-            owners=(empty,),
-            dtype=np.dtype(dtype).str,
-            shape=(0,),
+            buffers=(memoryview(empty.data).cast("B"),), owners=(empty,),
+            dtype=np.dtype(dtype).str, shape=(0,),
         )
+    ndarray_rows = [
+        value is not None and isinstance(value, np.ndarray) for value in values
+    ]
+    if all(value is None or is_array for value, is_array in zip(values, ndarray_rows)):
+        row_format = "ndarray"
+    elif any(ndarray_rows):
+        row_format = "mixed"
+    else:
+        row_format = "list"
     return (
         {
             "data": data,
@@ -2868,18 +3054,47 @@ def _encode_typed_ragged_values(
             "ndims": ndims,
             "nulls": nulls,
         },
-        {"dtype": str(dtype), "max_ndim": int(max_ndim), "shape_policy": "ragged"},
+        {
+            "dtype": str(dtype),
+            "max_ndim": int(max_ndim),
+            "shape_policy": "ragged",
+            "row_format": row_format,
+            "ndarray_rows": ndarray_rows if row_format == "mixed" else None,
+        },
     )
 
-
 def _decode_typed_ragged_values(
     payload: dict[str, Any], rows: int, metadata: Optional[Mapping[str, Any]] = None
 ) -> list[Any]:
-    data = payload["data"]
+    raw = payload["data"]
+    dtype_str = (metadata or {}).get("dtype", _TYPED_RAGGED_DEFAULT_DTYPE)
+    np_dtype = np.dtype(dtype_str)
+    # data may arrive as torch.Tensor, bytes, or numpy (pool-backed or typed)
+    if _torch is not None and isinstance(raw, _torch.Tensor):
+        data = raw.numpy()
+    elif isinstance(raw, (bytes, bytearray, memoryview)):
+        data = np.frombuffer(raw, dtype=np_dtype)
+    elif isinstance(raw, np.ndarray):
+        data = raw if raw.dtype == np_dtype else np.frombuffer(raw, dtype=np_dtype)
+    else:
+        data = np.asarray(raw, dtype=np_dtype)
     offsets = payload["offsets"]
     shapes = payload["shapes"]
     ndims = payload["ndims"]
     nulls = payload["nulls"]
+    metadata = metadata or {}
+    row_format = metadata.get("row_format")
+    if (
+        row_format == "ndarray"
+        and metadata.get("physical_layout") == "contiguous_flat"
+    ):
+        fast_values = _decode_typed_ragged_ndarray_rows_fast(
+            data, offsets, shapes, ndims, nulls, rows, metadata
+        )
+        if fast_values is not None:
+            return fast_values
+
+    ndarray_rows = metadata.get("ndarray_rows") or []
     values = []
     for row in range(rows):
         if bool(nulls[row]):
@@ -2889,7 +3104,13 @@ def _decode_typed_ragged_values(
         end = int(offsets[row + 1])
         ndim = int(ndims[row])
         shape = tuple(int(v) for v in shapes[row, :ndim].tolist())
-        values.append(data[begin:end].reshape(shape).tolist())
+        array = data[begin:end].reshape(shape)
+        if row_format == "ndarray" or (
+            row_format == "mixed" and bool(ndarray_rows[row])
+        ):
+            values.append(array)
+        else:
+            values.append(array.tolist())
     return values
 
 
@@ -3178,6 +3399,22 @@ def _read_torch_tensor_member(
         member_slice: StructuredMemberSlice | None,
         destination: Any,
     ) -> Any:
+        if field_spec.get("nested"):
+            if destination is not None:
+                raise ValueError(
+                    f"structured nested tensor member {name} does not support destinations"
+                )
+            value = _deserialize_nested_tensor_payload(
+                self._bundle_store.read_payload(payload_spec), field_spec
+            )
+            if member_slice is None:
+                return value
+            if member_slice.axis != 0:
+                raise ValueError(
+                    "structured nested tensor slicing currently supports axis=0 only"
+                )
+            start, end, step = _normalized_member_slice(member_slice, len(value))
+            return _select_nested_tensor_rows(value, range(start, end, step))
         if member_slice is not None:
             return self._read_sliced_torch_tensor_member(
                 name, payload_spec, field_spec, member_slice, destination
@@ -3209,6 +3446,20 @@ def _read_sliced_torch_tensor_member(
         member_slice: StructuredMemberSlice,
         destination: Any,
     ) -> Any:
+        if payload_spec.get("format") == "torch_save":
+            if destination is not None:
+                raise ValueError(
+                    f"structured torch_save tensor member {name} does not support destinations"
+                )
+            if member_slice.axis != 0:
+                raise ValueError(
+                    "structured tensor slicing currently supports axis=0 only"
+                )
+            value = _deserialize_torch_save_payload(
+                self._bundle_store.read_payload(payload_spec)
+            )
+            start, end, step = _normalized_member_slice(member_slice, len(value))
+            return value[start:end:step]
         metadata_bytes = int(payload_spec.get("metadata_bytes", -1))
         shape = field_spec.get("shape")
         element_size = int(field_spec.get("element_size", 0))
@@ -3467,23 +3718,24 @@ def put_bundle_manifest(
                 config=config,
             )
             written_keys.extend(meta_keys)
+            cleanup_key_list = list(dict.fromkeys(cleanup_keys or []))
+            buffer_object_ids = {
+                self._object_id_from_bundle_key(str(payload_spec["key"]))
+                for payload_spec in buffers.values()
+            }
+            buffer_object_ids.update(
+                self._object_id_from_bundle_key(key) for key in cleanup_key_list
+            )
             manifest = {
                 "version": 1,
                 "layout": "bundle",
                 "object_id": object_id,
                 "meta": meta_spec,
                 "buffers": dict(buffers),
-                "buffer_object_ids": sorted(
-                    {
-                        str(payload_spec["key"])
-                        .removeprefix(f"{self._key_prefix}/")
-                        .split("/buffer/", 1)[0]
-                        for payload_spec in buffers.values()
-                    }
-                ),
+                "buffer_object_ids": sorted(item for item in buffer_object_ids if item),
             }
-            if cleanup_keys:
-                manifest["cleanup_keys"] = list(dict.fromkeys(cleanup_keys))
+            if cleanup_key_list:
+                manifest["cleanup_keys"] = cleanup_key_list
             self._validate_manifest(manifest)
             manifest_blob = _encode_manifest(manifest)
             _check_status(
@@ -3498,11 +3750,39 @@ def put_bundle_manifest(
         return RemoteBundleRef(manifest_key=manifest_key, manifest=manifest)
 
     def remove_bundle(self, ref: RemoteBundleRef | Mapping[str, Any]) -> None:
-        manifest = self.resolve_manifest(ref)
+        manifest_key = (
+            ref.manifest_key
+            if isinstance(ref, RemoteBundleRef)
+            else ref.get("manifest_key")
+        )
+        embedded_manifest = (
+            ref.manifest if isinstance(ref, RemoteBundleRef) else ref.get("manifest")
+        )
+        is_exist = getattr(self._store, "is_exist", None)
+        if (
+            not embedded_manifest
+            and isinstance(manifest_key, str)
+            and callable(is_exist)
+        ):
+            status = is_exist(manifest_key)
+            if status == 0:
+                return
+            if status != 1:
+                raise RuntimeError(f"is_exist failed for {manifest_key}: {status}")
+        try:
+            manifest = self.resolve_manifest(ref)
+        except Exception:
+            if (
+                isinstance(manifest_key, str)
+                and callable(is_exist)
+                and is_exist(manifest_key) == 0
+            ):
+                return
+            raise
         keys = self._payload_keys(manifest)
         keys.extend(manifest.get("cleanup_keys", []))
-        keys.append(self._manifest_key(ref, manifest))
         _cleanup_keys(self._store, keys, strict=True)
+        _cleanup_keys(self._store, [self._manifest_key(ref, manifest)], strict=True)
 
     def manifest_key(self, ref: RemoteBundleRef | Mapping[str, Any]) -> str:
         return self._manifest_key(ref, self.resolve_manifest(ref))
@@ -3673,7 +3953,6 @@ def _put_tensor_payload(
             memoryview(payload),
             len(payload) or 1,
             transfer_policy,
-            pre_registered=False,
             config=config,
         )
         payload_spec["metadata_bytes"] = metadata_bytes
@@ -3895,6 +4174,21 @@ def _policy(
             raise ValueError(f"unsupported copy_mode: {result.copy_mode}")
         return result
 
+    def _object_id_from_bundle_key(self, key: str) -> str | None:
+        prefix = f"{self._key_prefix}/"
+        if not key.startswith(prefix):
+            return None
+        suffix = key[len(prefix) :]
+        if suffix.endswith("/manifest"):
+            return suffix[: -len("/manifest")]
+        if suffix.endswith("/meta"):
+            return suffix[: -len("/meta")]
+        for marker in ("/meta/", "/buffer/"):
+            index = suffix.find(marker)
+            if index > 0:
+                return suffix[:index]
+        return None
+
     def _validate_manifest(self, manifest: Mapping[str, Any]) -> None:
         if manifest.get("version") != 1 or manifest.get("layout") != "bundle":
             raise ValueError("invalid bundle manifest")
@@ -4248,16 +4542,25 @@ def put_tensor_payload_direct(
         value: _TensorPayload,
         config: Any = None,
     ) -> dict[str, Any] | None:
-        if config is not None:
-            return None
-        put_tensor = getattr(self._store, "put_tensor", None)
+        put_tensor = getattr(
+            self._store, "put_tensor" if config is None else "pub_tensor", None
+        )
         if not callable(put_tensor):
             return None
         tensor = value.tensor
         nbytes = int(getattr(tensor, "nbytes", 0))
         metadata_bytes = _tensor_metadata_size()
         total_bytes = metadata_bytes + nbytes
-        _check_status(put_tensor(key, tensor), "put_tensor", key)
+        _check_status(
+            _call_write_with_optional_config(
+                put_tensor,
+                key,
+                tensor,
+                config=_config_for_grouped_keys(config, 1),
+            ),
+            "put_tensor",
+            key,
+        )
         return {
             "key": key,
             "kind": "tensor",
@@ -4319,6 +4622,8 @@ def batch_put_buffer_groups_from(
         # Stream one chunk at a time: acquire -> memcpy -> put -> release.
         # This keeps pool pressure minimal and allows RDMA transfers to pipeline.
         for chunk_key, group, size in zip(chunk_keys, chunk_groups, sizes):
+            # Each pool lease maps to one physical key, so a single logical group id
+            # stays length-1 for each batch_put_from call in this path.
             lease = pool.acquire(size)
             try:
                 _copy_memoryviews_to_lease(group, lease)
@@ -4896,6 +5201,25 @@ def _normalized_member_slice(
     )
 
 
+def _select_nested_tensor_rows(value: Any, indices: Sequence[int]) -> Any:
+    rows = value.unbind()
+    selected = [rows[int(index)] for index in indices]
+    if selected:
+        result = _torch.nested.as_nested_tensor(selected, layout=value.layout)
+    else:
+        offsets = _torch.zeros(
+            1,
+            dtype=value.offsets().dtype,
+            device=value.offsets().device,
+        )
+        result = _torch.nested.nested_tensor_from_jagged(
+            value.values()[:0], offsets=offsets
+        )
+    if hasattr(value, "_ragged_idx"):
+        result._ragged_idx = value._ragged_idx
+    return result
+
+
 def _bytes_view(value: Any, name: str) -> memoryview:
     try:
         view = memoryview(value)
@@ -5128,6 +5452,10 @@ def _encode_structured_field(value: Any) -> tuple[dict[str, Any], Any]:
 
 
 def _encode_torch_tensor_field(value: Any) -> tuple[dict[str, Any], Any]:
+    if value.is_nested:
+        if value.layout != _torch.jagged:
+            raise ValueError("structured nested tensor fields require torch.jagged layout")
+        return _encode_nested_tensor_field(value)
     return {
         "encoding": "torch_tensor",
         "dtype": str(value.dtype),
@@ -5293,7 +5621,313 @@ def _normalize_structured_scalar(value: Any) -> Any:
 
 
 
+def _encode_typed_ragged_regular_ndarray_rows(
+    values: list[Any], dtype: np.dtype[Any]
+) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    row_count = len(values)
+    if row_count < 2:
+        return None
+    first = values[0]
+    if (
+        not isinstance(first, np.ndarray)
+        or first.dtype != dtype
+        or not first.flags.c_contiguous
+    ):
+        return None
+    shape = first.shape
+    for value in values[1:]:
+        if (
+            not isinstance(value, np.ndarray)
+            or value.dtype != dtype
+            or not value.flags.c_contiguous
+            or value.shape != shape
+        ):
+            return None
+
+    row_elems = int(first.size)
+    total_elems = row_count * row_elems
+    if row_elems:
+        flat_arrays = [value.reshape(-1) for value in values]
+        if _concat_arrays_into is not None:
+            data = _DirectCopyPayload.from_flat_arrays(flat_arrays, dtype, total_elems)
+        else:
+            data = _MultiBufferPayload(
+                buffers=tuple(memoryview(flat.data).cast("B") for flat in flat_arrays),
+                owners=tuple(flat_arrays),
+                dtype=np.dtype(dtype).str,
+                shape=(total_elems,),
+            )
+    else:
+        data = np.asarray(values, dtype=dtype).reshape(-1)
+    offsets = np.arange(row_count + 1, dtype=np.int64) * row_elems
+    nulls = np.zeros(row_count, dtype=np.bool_)
+    max_ndim = int(first.ndim)
+    if max_ndim == 0:
+        shapes = np.zeros((row_count, 1), dtype=np.int64)
+        ndims = np.zeros(row_count, dtype=np.int16)
+    else:
+        shapes = np.empty((row_count, max_ndim), dtype=np.int64)
+        shapes[:] = shape
+        ndims = np.full(row_count, max_ndim, dtype=np.int16)
+    return (
+        {
+            "data": data,
+            "offsets": offsets,
+            "shapes": shapes,
+            "ndims": ndims,
+            "nulls": nulls,
+        },
+        {
+            "dtype": str(dtype),
+            "max_ndim": max_ndim,
+            "shape_policy": "ragged",
+            "row_format": "ndarray",
+            "ndarray_rows": None,
+            "physical_layout": "contiguous_flat",
+        },
+    )
+
+
+def _encode_typed_ragged_ndarray_rows(
+    values: list[Any], dtype: np.dtype[Any]
+) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    regular_encoded = _encode_typed_ragged_regular_ndarray_rows(values, dtype)
+    if regular_encoded is not None:
+        return regular_encoded
+
+    row_count = len(values)
+    if row_count == 0:
+        return None
+
+    nulls = np.empty(row_count, dtype=np.bool_)
+    lengths = np.empty(row_count, dtype=np.int64)
+    arrays: list[np.ndarray] = []
+    tail_shape: tuple[int, ...] | None = None
+    row_ndim: int | None = None
+    tail_compatible = True
+    saw_scalar = False
+    saw_non_scalar = False
+
+    for row, value in enumerate(values):
+        if value is None:
+            nulls[row] = True
+            lengths[row] = 0
+            continue
+        if not isinstance(value, np.ndarray):
+            return None
+
+        array = _as_contiguous_array_preserve_ndim(value, dtype)
+        arrays.append(array)
+        nulls[row] = False
+        lengths[row] = array.size
+        if array.ndim == 0:
+            saw_scalar = True
+            if saw_non_scalar:
+                tail_compatible = False
+            continue
+
+        saw_non_scalar = True
+        if saw_scalar:
+            tail_compatible = False
+        current_tail = array.shape[1:]
+        if tail_shape is None:
+            tail_shape = current_tail
+            row_ndim = array.ndim
+        elif array.ndim != row_ndim or current_tail != tail_shape:
+            tail_compatible = False
 
+    if tail_compatible and tail_shape is not None and any(dim == 0 for dim in tail_shape):
+        tail_compatible = False
+
+    offsets = np.empty(row_count + 1, dtype=np.int64)
+    offsets[0] = 0
+    np.cumsum(lengths, out=offsets[1:])
+    total_elems = int(offsets[-1])
+    if len(arrays) == 1:
+        flat = arrays[0].reshape(-1)
+        data = _MultiBufferPayload(
+            buffers=(memoryview(flat.data).cast("B"),),
+            owners=(flat,),
+            dtype=np.dtype(dtype).str,
+            shape=(total_elems,),
+        )
+    elif total_elems:
+        flat_arrays = [arr.reshape(-1) for arr in arrays]
+        if _concat_arrays_into is not None:
+            data = _DirectCopyPayload.from_flat_arrays(flat_arrays, dtype, total_elems)
+        else:
+            buffers = tuple(memoryview(flat.data).cast("B") for flat in flat_arrays)
+            data = _MultiBufferPayload(
+                buffers=buffers,
+                owners=tuple(flat_arrays),
+                dtype=np.dtype(dtype).str,
+                shape=(total_elems,),
+            )
+    else:
+        empty = np.empty(0, dtype=dtype)
+        data = _MultiBufferPayload(
+            buffers=(memoryview(empty.data).cast("B"),),
+            owners=(empty,),
+            dtype=np.dtype(dtype).str,
+            shape=(0,),
+        )
+
+    if not arrays or saw_scalar and not saw_non_scalar:
+        max_ndim = 0
+    elif tail_compatible:
+        max_ndim = int(row_ndim or 1)
+    else:
+        max_ndim = max(array.ndim for array in arrays)
+
+    ndims = np.zeros(row_count, dtype=np.int16)
+    if max_ndim == 0:
+        shapes = np.zeros((row_count, 1), dtype=np.int64)
+    elif tail_compatible:
+        shapes = np.zeros((row_count, max_ndim), dtype=np.int64)
+        tail = tail_shape or ()
+        tail_elems = int(np.prod(tail, dtype=np.int64)) if tail else 1
+        shapes[:, 0] = lengths // tail_elems
+        if max_ndim > 1:
+            shapes[:, 1:] = tail
+        ndims[~nulls] = max_ndim
+    else:
+        shapes = np.zeros((row_count, max(max_ndim, 1)), dtype=np.int64)
+        array_index = 0
+        for row, is_null in enumerate(nulls):
+            if bool(is_null):
+                continue
+            array = arrays[array_index]
+            array_index += 1
+            ndims[row] = array.ndim
+            if array.ndim > 0:
+                shapes[row, : array.ndim] = array.shape
+
+    return (
+        {
+            "data": data,
+            "offsets": offsets,
+            "shapes": shapes,
+            "ndims": ndims,
+            "nulls": nulls,
+        },
+        {
+            "dtype": str(dtype),
+            "max_ndim": int(max_ndim),
+            "shape_policy": "ragged",
+            "row_format": "ndarray",
+            "ndarray_rows": None,
+            "physical_layout": "contiguous_flat",
+        },
+    )
+
+
+def _as_contiguous_array_preserve_ndim(value: Any, dtype: np.dtype[Any]) -> np.ndarray:
+    if isinstance(value, np.ndarray) and value.dtype == dtype and value.flags.c_contiguous:
+        return value
+    array = np.asarray(value, dtype=dtype)
+    if array.flags.c_contiguous:
+        return array
+    return np.array(array, dtype=dtype, order="C", copy=True)
+
+
+def _decode_typed_ragged_ndarray_rows_fast(
+    data: np.ndarray,
+    offsets: np.ndarray,
+    shapes: np.ndarray,
+    ndims: np.ndarray,
+    nulls: np.ndarray,
+    rows: int,
+    metadata: Mapping[str, Any],
+) -> list[Any] | None:
+    # Returned ndarray rows are views into data; _OwnerBackedList preserves any
+    # pool owner attached to that data for the lifetime of the row list.
+    max_ndim = int(metadata.get("max_ndim", 0))
+    owner = getattr(data, "_mooncake_pool_owner", None)
+    source = data.view(np.ndarray) if isinstance(data, np.ndarray) else data
+    has_nulls = bool(nulls.any())
+
+    def attach_owner(values: list[Any]) -> list[Any]:
+        if owner is None:
+            return values
+        return _OwnerBackedList(values, owner)
+
+    if max_ndim == 1:
+        if not has_nulls:
+            row_width = _regular_offsets_width(offsets, rows)
+            if row_width is not None:
+                return attach_owner(list(source.reshape((rows, row_width))))
+            begins = offsets[:-1].tolist()
+            ends = offsets[1:].tolist()
+            return attach_owner(
+                [source[b:e] for b, e in zip(begins, ends)]
+            )
+        values: list[Any] = []
+        for row, is_null in enumerate(nulls):
+            if bool(is_null):
+                values.append(None)
+            else:
+                begin = int(offsets[row])
+                end = int(offsets[row + 1])
+                values.append(source[begin:end])
+        return attach_owner(values)
+
+    if max_ndim <= 1 or rows == 0:
+        return None
+
+    non_null_rows = np.flatnonzero(~nulls)
+    if non_null_rows.size == 0:
+        return [None] * rows
+    first_row = int(non_null_rows[0])
+    if int(ndims[first_row]) != max_ndim:
+        return None
+    tail = tuple(int(v) for v in shapes[first_row, 1:max_ndim])
+    if any(dim == 0 for dim in tail):
+        return None
+    for row in non_null_rows:
+        row_index = int(row)
+        if int(ndims[row_index]) != max_ndim:
+            return None
+        if tuple(int(v) for v in shapes[row_index, 1:max_ndim]) != tail:
+            return None
+
+    tail_elems = int(np.prod(tail, dtype=np.int64)) if tail else 1
+    if tail_elems <= 0:
+        return None
+    if int(offsets[-1]) % tail_elems != 0:
+        return None
+    flat_rows = source.reshape((-1, *tail))
+    first_axis_offsets = offsets // tail_elems
+
+    if not has_nulls:
+        row_width = _regular_offsets_width(first_axis_offsets, rows)
+        if row_width is not None:
+            return attach_owner(list(flat_rows.reshape((rows, row_width, *tail))))
+        fa_begins = first_axis_offsets[:-1].tolist()
+        fa_ends = first_axis_offsets[1:].tolist()
+        return attach_owner(
+            [flat_rows[b:e] for b, e in zip(fa_begins, fa_ends)]
+        )
+    values = []
+    for row, is_null in enumerate(nulls):
+        if bool(is_null):
+            values.append(None)
+        else:
+            begin = int(first_axis_offsets[row])
+            end = int(first_axis_offsets[row + 1])
+            values.append(flat_rows[begin:end])
+    return attach_owner(values)
+
+
+def _regular_offsets_width(offsets: np.ndarray, rows: int) -> int | None:
+    if rows <= 0 or int(offsets[0]) != 0:
+        return None
+    total = int(offsets[-1])
+    if total < 0 or total % rows != 0:
+        return None
+    row_width = total // rows
+    if not bool(np.all(offsets[1:] - offsets[:-1] == row_width)):
+        return None
+    return row_width
 
 def _encode_msgpack_ragged_values(
     path: str, values: list[Any]
@@ -5323,8 +5957,6 @@ def _encode_msgpack_ragged_values(
         {},
     )
 
-
-
 def _decode_msgpack_ragged_values(payload: dict[str, Any], rows: int) -> list[Any]:
     data = payload["data"]
     offsets = payload["offsets"]
@@ -5338,14 +5970,24 @@ def _decode_msgpack_ragged_values(payload: dict[str, Any], rows: int) -> list[An
             f"msgpack_ragged nulls length {len(nulls)} does not match rows {rows}"
         )
     raw_data = bytes(data) if not isinstance(data, bytes) else data
+    if rows == 0 or not bool(nulls.any()):
+        unpacker = _msgpack.Unpacker(raw=False)
+        unpacker.feed(raw_data)
+        values = list(unpacker)
+        if len(values) != rows:
+            raise ValueError(
+                f"msgpack_ragged decoded {len(values)} rows, expected {rows}"
+            )
+        return values
+    unpacker = _msgpack.Unpacker(raw=False)
+    unpacker.feed(raw_data)
+    non_null_iter = iter(unpacker)
     values = []
-    for row, is_null in enumerate(nulls):
+    for is_null in nulls:
         if bool(is_null):
             values.append(None)
         else:
-            begin = int(offsets[row])
-            end = int(offsets[row + 1])
-            values.append(_msgpack.unpackb(raw_data[begin:end], raw=False))
+            values.append(next(non_null_iter))
     return values
 
 
@@ -5354,8 +5996,6 @@ def __init__(self, values: Sequence[Any], owner: Any) -> None:
         super().__init__(values)
         self._mooncake_pool_owner = owner
 
-
-
 class _OwnerBackedObjectArray(np.ndarray):
     def __array_finalize__(self, obj: Any) -> None:
         if obj is not None:
@@ -5368,8 +6008,6 @@ def tolist(self) -> list[Any]:
             return values
         return _OwnerBackedList(values, owner)
 
-
-
 def _object_array_from_decoded_values(values: list[Any]) -> np.ndarray:
     array = np.empty(len(values), dtype=object)
     array[:] = values
@@ -5413,6 +6051,106 @@ def _deserialize_torch_save_payload(payload: bytes) -> Any:
     return _torch.load(io.BytesIO(payload), weights_only=True)
 
 
+def _encode_nested_tensor_field(value: Any) -> tuple[dict[str, Any], Any]:
+    field_spec = {
+        "encoding": "torch_tensor",
+        "dtype": str(value.dtype),
+        "nested": True,
+        "format": "torch_save",
+    }
+    values = value.values()
+    offsets = value.offsets()
+    lengths = value.lengths()
+    tensors = [values, offsets]
+    if lengths is not None:
+        tensors.append(lengths)
+
+    if _has_tensor_codec_helpers() and all(
+        tensor.device.type == "cpu" for tensor in tensors
+    ):
+        parts = [
+            _tensor_payload_bytes(_TensorPayload(tensor=tensor))[0]
+            for tensor in tensors
+        ]
+        field_spec.update(
+            {
+                "format": "tensor_parts",
+                "part_bytes": [len(part) for part in parts],
+                "has_lengths": lengths is not None,
+                "ragged_idx": int(getattr(value, "_ragged_idx", 1)),
+            }
+        )
+        return field_spec, _MultiBufferPayload(
+            buffers=tuple(memoryview(part) for part in parts)
+        )
+
+    return field_spec, memoryview(_torch_save_payload_bytes(value))
+
+
+def _deserialize_nested_tensor_payload(
+    payload: bytes, field_spec: Mapping[str, Any]
+) -> Any:
+    payload_format = field_spec.get("format", "torch_save")
+    if payload_format == "torch_save":
+        value = _deserialize_torch_save_payload(payload)
+        return _nested_tensor_from_parts(
+            value.values(),
+            value.offsets(),
+            value.lengths(),
+            int(getattr(value, "_ragged_idx", 1)),
+        )
+    if payload_format != "tensor_parts":
+        raise ValueError(f"unsupported nested tensor payload format: {payload_format}")
+
+    part_bytes = field_spec.get("part_bytes")
+    expected_parts = 3 if field_spec.get("has_lengths") else 2
+    if not isinstance(part_bytes, list) or len(part_bytes) != expected_parts:
+        raise ValueError("nested tensor payload has invalid part metadata")
+
+    tensors = []
+    offset = 0
+    for part_size in part_bytes:
+        if (
+            not isinstance(part_size, int)
+            or isinstance(part_size, bool)
+            or part_size <= 0
+        ):
+            raise ValueError("nested tensor payload has invalid part size")
+        end = offset + int(part_size)
+        if end > len(payload):
+            raise ValueError("nested tensor payload is truncated")
+        tensors.append(_deserialize_tensor_payload(payload[offset:end]))
+        offset = end
+    if offset != len(payload):
+        raise ValueError("nested tensor payload has trailing bytes")
+
+    return _nested_tensor_from_parts(
+        tensors[0],
+        tensors[1],
+        tensors[2] if expected_parts == 3 else None,
+        int(field_spec.get("ragged_idx", 1)),
+    )
+
+
+def _nested_tensor_from_parts(
+    values: Any, offsets: Any, lengths: Any, ragged_idx: int
+) -> Any:
+    sequence_lengths = lengths if lengths is not None else offsets.diff()
+    if sequence_lengths.numel():
+        min_seqlen = int(sequence_lengths.min().item())
+        max_seqlen = int(sequence_lengths.max().item())
+    else:
+        min_seqlen = max_seqlen = 0
+    return _torch.nested.nested_tensor_from_jagged(
+        values,
+        offsets=offsets,
+        lengths=lengths,
+        jagged_dim=ragged_idx,
+        min_seqlen=min_seqlen,
+        max_seqlen=max_seqlen,
+    )
+
+
 def _slice_tensor_metadata(
     metadata: bytes, shape: Sequence[int], data_bytes: int
 ) -> bytes:
@@ -5504,15 +6242,106 @@ def _call_write_with_optional_config(fn: Any, *args: Any, config: Any = None) ->
     return fn(*args, config=config)
 
 
+_WRITE_CONFIG_COPY_FIELDS = (
+    "data_type",
+    "group_ids",
+    "nof_replica_num",
+    "prefer_alloc_in_same_node",
+    "preferred_nof_segments",
+    "preferred_segment",
+    "preferred_segments",
+    "replica_num",
+    "with_hard_pin",
+    "with_soft_pin",
+)
+
+
+def _config_for_grouped_keys(config: Any, key_count: int) -> Any:
+    """Return a write config whose group_ids match the physical key count."""
+    if config is None or key_count <= 0:
+        return config
+    group_ids = getattr(config, "group_ids", None)
+    if group_ids is None:
+        return config
+    normalize_to_list = isinstance(group_ids, str)
+    if normalize_to_list:
+        group_ids = [group_ids]
+    else:
+        group_ids = list(group_ids)
+    if not group_ids:
+        ungrouped_config = _copy_write_config(config)
+        ungrouped_config.group_ids = None
+        return ungrouped_config
+    if len(group_ids) != 1:
+        raise ValueError(
+            "structured object store config.group_ids must contain exactly one "
+            "logical group id; it is expanded across internal Mooncake keys"
+        )
+    if key_count == 1 and not normalize_to_list:
+        return config
+    grouped_config = _copy_write_config(config)
+    grouped_config.group_ids = [group_ids[0]] * key_count
+    return grouped_config
+
+
+def _copy_write_config(config: Any) -> Any:
+    try:
+        return copy.copy(config)
+    except TypeError:
+        pass
+    try:
+        copied = type(config)()
+    except Exception as error:
+        raise TypeError(
+            "structured object store config must be copyable or default-constructible"
+        ) from error
+    for name in _WRITE_CONFIG_COPY_FIELDS:
+        if not hasattr(config, name):
+            continue
+        try:
+            value = getattr(config, name)
+        except Exception:
+            continue
+        if isinstance(value, list):
+            value = list(value)
+        elif isinstance(value, tuple):
+            value = tuple(value)
+        try:
+            setattr(copied, name, value)
+        except Exception as error:
+            raise TypeError(
+                f"structured object store config field {name!r} is not writable"
+            ) from error
+    return copied
+
+
+def _config_with_group_id(config: Any, group_id: str) -> Any:
+    configured_ids = getattr(_config_for_grouped_keys(config, 1), "group_ids", None)
+    if configured_ids and configured_ids[0] and configured_ids[0] != group_id:
+        raise ValueError(
+            "config.group_ids conflicts with the DataProto storage group"
+        )
+    grouped_config = (
+        getattr(_mooncake_store, "ReplicateConfig", SimpleNamespace)()
+        if config is None
+        else _copy_write_config(config)
+    )
+    grouped_config.group_ids = [group_id]
+    return grouped_config
+
+
 def _put_with_optional_config(
     store: BundleStore, key: str, value: Any, config: Any = None
 ) -> int:
-    return _call_write_with_optional_config(store.put, key, value, config=config)
+    return _call_write_with_optional_config(
+        store.put, key, value, config=_config_for_grouped_keys(config, 1)
+    )
 
 
 def _put_from_with_optional_config(
     store: BundleStore, key: str, ptr: int, size: int, config: Any = None
 ) -> int:
+    config = _config_for_grouped_keys(config, 1)
     put_tensor_from = getattr(store, "put_tensor_from", None)
     if config is None and callable(put_tensor_from):
         return put_tensor_from(key, ptr, size)
@@ -5530,7 +6359,11 @@ def _batch_put_from_with_optional_config(
     config: Any = None,
 ) -> Sequence[int]:
     return _call_write_with_optional_config(
-        batch_put_from, list(keys), list(ptrs), list(sizes), config=config
+        batch_put_from,
+        list(keys),
+        list(ptrs),
+        list(sizes),
+        config=_config_for_grouped_keys(config, len(keys)),
     )
 
 
@@ -5604,7 +6437,21 @@ def _cleanup_keys(store: BundleStore, keys: Sequence[str], strict: bool) -> None
     _torch = None  # type: ignore[assignment]
 
 
+def _parse_torch_dtype(dtype_str: str) -> Any:
+    """Parse torch dtype string (e.g. 'torch.float32') to torch.dtype object."""
+    name = dtype_str.removeprefix("torch.")
+    dtype = getattr(_torch, name, None)
+    if dtype is None or not isinstance(dtype, _torch.dtype):
+        raise ValueError(f"unknown torch dtype: {dtype_str}")
+    return dtype
+
 
+def _torch_dtype_to_numpy(dtype_str: str) -> np.dtype:
+    """Convert value-preserving torch dtypes to numpy dtypes."""
+    torch_dtype = _parse_torch_dtype(dtype_str)
+    if torch_dtype == _torch.bfloat16:
+        raise ValueError("torch.bfloat16 has no value-preserving numpy dtype")
+    return _torch.empty(0, dtype=torch_dtype).numpy().dtype
 
 @dataclass
 class _CodecDecision:
diff --git a/mooncake-wheel/mooncake/transfer_engine_topology_dump.py b/mooncake-wheel/mooncake/transfer_engine_topology_dump.py
deleted file mode 100644
index c12a8b9026..0000000000
--- a/mooncake-wheel/mooncake/transfer_engine_topology_dump.py
+++ /dev/null
@@ -1,28 +0,0 @@
-import argparse
-import sys
-import os
-
-def parse_args():
-    """Parse command line arguments."""
-    parser = argparse.ArgumentParser(
-        description="Dump device topology",
-        formatter_class=argparse.ArgumentDefaultsHelpFormatter
-    )
-    parser.add_argument(
-        "--device-name", 
-        type=str, 
-        default="", 
-        help="Filter topology by given device name"
-    )
-    return parser.parse_args()
-    
-def main():
-    args = parse_args()
-    os.environ['MC_LOG_LEVEL'] = 'ERROR'
-    os.environ['MC_CUSTOM_TOPO_JSON'] = ''
-    from mooncake.engine import TransferEngine
-    engine = TransferEngine()
-    print('Local topology: ', engine.get_local_topology(device_name=args.device_name))
-
-if __name__ == "__main__":
-    sys.exit(main())
\ No newline at end of file
diff --git a/mooncake-wheel/pyproject.toml b/mooncake-wheel/pyproject.toml
index 87deee582f..3a1bd8d38f 100644
--- a/mooncake-wheel/pyproject.toml
+++ b/mooncake-wheel/pyproject.toml
@@ -23,18 +23,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mooncake-transfer-engine"
-version = "0.3.12.post1"
+version = "0.3.13"
 description = "A KVCache-centric Disaggregated Architecture for large-scale LLM inference and training."
 authors = [
     { name = "Mooncake Authors" }
 ]
 requires-python = ">=3.10"
 readme = "README.md"   # local copy of ../README.md, materialized at build time by scripts/build_wheel.sh
-dependencies = ["aiohttp", "requests", "msgpack"]
+dependencies = ["aiohttp", "requests", "msgpack", "typing_extensions>=4.0; python_version < '3.10'"]
 # Single-line arrays: sed-substituted by scripts/build_wheel.sh for each variant.
 keywords = ["mooncake", "transfer engine", "kv cache", "llm inference", "rdma"]
 classifiers = ["Development Status :: 5 - Production/Stable", "Environment :: GPU :: NVIDIA CUDA", "Intended Audience :: Developers", "Intended Audience :: Science/Research", "License :: OSI Approved :: Apache Software License", "Operating System :: POSIX :: Linux", "Programming Language :: C++", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "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", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Topic :: System :: Distributed Computing"]
 
+[project.optional-dependencies]
+administration = ["paramiko"]
+
 [project.urls]
 Homepage = "https://github.com/kvcache-ai/Mooncake"
 Documentation = "https://kvcache-ai.github.io/Mooncake"
diff --git a/mooncake-wheel/tests/test_cuda_fabric_compat.py b/mooncake-wheel/tests/test_cuda_fabric_compat.py
new file mode 100644
index 0000000000..dee2c7fa8b
--- /dev/null
+++ b/mooncake-wheel/tests/test_cuda_fabric_compat.py
@@ -0,0 +1,97 @@
+"""Compile the compatibility declarations without requiring a CUDA toolkit."""
+
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2] / "mooncake-transfer-engine"
+COMPILER = shutil.which("c++")
+
+
+@unittest.skipUnless(COMPILER, "C++ compiler is unavailable")
+class CudaFabricCompatTest(unittest.TestCase):
+    def test_old_and_new_toolkits_and_both_include_orders(self):
+        for version in (12000, 12030, 13000):
+            for tent_first in (False, True):
+                with self.subTest(version=version, tent_first=tent_first):
+                    headers = [
+                        '"cuda_fabric_compat.h"',
+                        '"tent/common/cuda_fabric_compat.h"',
+                    ]
+                    if tent_first:
+                        headers.reverse()
+                    source = f"""#define USE_CUDA 1
+#define CUDA_VERSION {version}
+enum CUdevice_attribute : unsigned int {{}};
+enum CUmemAllocationHandleType : unsigned int {{}};
+"""
+                    if version >= 12030:
+                        source += """
+#define CU_IPC_HANDLE_SIZE 64
+struct CUmemFabricHandle { unsigned char data[64]; };
+constexpr auto CU_MEM_HANDLE_TYPE_FABRIC = (CUmemAllocationHandleType)8;
+constexpr auto CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED =
+    (CUdevice_attribute)128;
+"""
+                    source += "\n".join(f"#include {header}" for header in headers)
+                    source += """
+static_assert(sizeof(CUmemFabricHandle) == 64);
+static_assert((int)CU_MEM_HANDLE_TYPE_FABRIC == 8);
+static_assert((int)CU_DEVICE_ATTRIBUTE_HANDLE_TYPE_FABRIC_SUPPORTED == 128);
+"""
+                    subprocess.run(
+                        [
+                            COMPILER,
+                            "-std=c++17",
+                            "-fsyntax-only",
+                            "-x",
+                            "c++",
+                            "-I",
+                            str(ROOT / "include"),
+                            "-I",
+                            str(ROOT / "tent/include"),
+                            "-",
+                        ],
+                        input=source,
+                        text=True,
+                        check=True,
+                        capture_output=True,
+                    )
+
+    def test_standalone_mnnvl_header_does_not_need_classic_include_path(self):
+        with tempfile.TemporaryDirectory() as directory:
+            stubs = Path(directory)
+            # Isolate the include boundary from unrelated toolkit/RPC headers.
+            for name in (
+                "cuda.h",
+                "cuda_runtime.h",
+                "tent/runtime/control_plane.h",
+                "tent/runtime/transport.h",
+                "tent/platform/cuda.h",
+            ):
+                path = stubs / name
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text("")
+            subprocess.run(
+                [
+                    COMPILER,
+                    "-E",
+                    "-x",
+                    "c++",
+                    "-I",
+                    str(stubs),
+                    "-I",
+                    str(ROOT / "tent/include"),
+                    "-",
+                ],
+                input='#include "tent/transport/mnnvl/mnnvl_transport.h"\n',
+                text=True,
+                check=True,
+                capture_output=True,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-wheel/tests/test_dataproto_catalog.py b/mooncake-wheel/tests/test_dataproto_catalog.py
new file mode 100644
index 0000000000..5fdf2f45b5
--- /dev/null
+++ b/mooncake-wheel/tests/test_dataproto_catalog.py
@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import copy
+from types import SimpleNamespace
+
+import pytest
+
+from mooncake.dataproto_catalog import DataProtoCatalog, DataProtoCatalogTransfer
+from mooncake.structured_object_store import import_dataproto_ref
+
+
+def handle(name: str, fields: list[str], batch_size: int = 2) -> dict:
+    return {
+        "type": "mooncake_dataproto_ref",
+        "version": 1,
+        "kind": "bundle_stages",
+        "batch_size": batch_size,
+        "stage_refs": {"rollout": {"manifest_key": f"manifest/{name}"}},
+        "field_index": {
+            field: {
+                "stage": "rollout",
+                "member": f"batch.{field}",
+                "section": "batch",
+            }
+            for field in fields
+        },
+    }
+
+
+def test_catalog_merges_tags_and_resolves_fragmented_fields_in_key_order() -> None:
+    catalog = DataProtoCatalog()
+    catalog.update(
+        "train",
+        ["a", "b"],
+        tags=[{"status": "running"}, {"status": "running"}],
+        handle=handle("base", ["input_ids", "attention_mask"]),
+    )
+    result = catalog.update(
+        "train",
+        ["b", "a"],
+        tags=[{"status": "done"}, {"status": "done"}],
+        handle=handle("scores", ["score"]),
+    )
+
+    assert result["fields"] == ["input_ids", "attention_mask", "score"]
+    assert catalog.list("train") == {
+        "train": {
+            "a": {"status": "done"},
+            "b": {"status": "done"},
+        }
+    }
+    plan = catalog.resolve("train", ["a", "b"], ["score", "input_ids"])
+    assert plan["fields"] == ["score", "input_ids"]
+    assert plan["field_groups"] == [
+        {
+            "fields": ["score"],
+            "locations": [("manifest/scores", 1), ("manifest/scores", 0)],
+        },
+        {
+            "fields": ["input_ids"],
+            "locations": [("manifest/base", 0), ("manifest/base", 1)],
+        },
+    ]
+    assert set(plan["handles"]) == {"manifest/base", "manifest/scores"}
+    grouped = catalog.resolve("train", ["b", "a"], ["input_ids", "attention_mask"])
+    assert catalog.resolve("train", ["a", "b"])["fields"] == [
+        "input_ids",
+        "attention_mask",
+        "score",
+    ]
+    assert grouped["field_groups"] == [
+        {
+            "fields": ["input_ids", "attention_mask"],
+            "locations": [("manifest/base", 1), ("manifest/base", 0)],
+        }
+    ]
+
+
+def test_catalog_drops_replaced_and_removed_locations() -> None:
+    catalog = DataProtoCatalog()
+    base = handle("base", ["value"])
+    replacement = handle("replacement", ["value"])
+    catalog.update("train", ["a", "b"], handle=base)
+
+    catalog.update("train", ["a"], handle={**replacement, "batch_size": 1})
+    catalog.update("train", ["b", "a"], handle=base)
+    plan = catalog.resolve("train", ["a", "b"], ["value"])
+    assert plan["field_groups"] == [
+        {
+            "fields": ["value"],
+            "locations": [("manifest/base", 1), ("manifest/base", 0)],
+        }
+    ]
+    catalog.remove("train", ["b"])
+    catalog.remove("train", ["a"])
+    assert catalog.list() == {}
+
+
+def test_catalog_rejects_missing_or_incomplete_reads_without_mutation() -> None:
+    catalog = DataProtoCatalog()
+    catalog.update("train", ["a", "b"], tags=[{}, {}])
+    catalog.update("train", ["a"], handle=handle("one", ["value"], batch_size=1))
+
+    with pytest.raises(ValueError, match="were not found"):
+        catalog.resolve("train", ["missing"])
+    with pytest.raises(ValueError, match="not ready"):
+        catalog.resolve("train", ["a", "b"], ["value"])
+    with pytest.raises(ValueError, match="do not contain any fields"):
+        catalog.resolve("train", ["b"])
+    with pytest.raises(ValueError, match="same length"):
+        catalog.update("train", ["a", "b"], tags=[{}])
+    with pytest.raises(ValueError, match="sequence"):
+        catalog.resolve("train", "a")
+    with pytest.raises(ValueError, match="sequence"):
+        catalog.resolve("train", ["a"], "value")
+    invalid_handle = handle("invalid", ["value"], batch_size=1)
+    invalid_handle["version"] = 999
+    with pytest.raises(ValueError, match="unsupported.*version"):
+        catalog.update("invalid", ["a"], handle=invalid_handle)
+    multi_stage = handle("multi", ["value"], batch_size=1)
+    multi_stage["stage_refs"]["extra"] = {"manifest_key": "manifest/extra"}
+    with pytest.raises(ValueError, match="exactly one.*stage"):
+        catalog.update("invalid", ["a"], handle=multi_stage)
+
+    assert catalog.list("train") == {"train": {"a": {}, "b": {}}}
+    assert "invalid" not in catalog.list()
+
+
+def test_catalog_only_retires_managed_fragments() -> None:
+    catalog = DataProtoCatalog()
+    external = handle("external", ["value"], batch_size=1)
+    catalog.update("train", ["a"], handle=external)
+    assert catalog.remove("train", ["a"])["retired_handles"] == []
+
+    managed = handle("managed", ["value"], batch_size=1)
+    catalog.publish("managed-op", "train", ["a"], handle=managed)
+    assert catalog.publish("managed-op", "other", ["x"], handle=external)["fields"] == [
+        "value"
+    ]
+    assert "other" not in catalog.list()
+    catalog.ack_publication("managed-op")
+    retired = catalog.remove("train", ["a"])["retired_handles"]
+    assert len(retired) == 1
+    assert retired[0]["stage_refs"] == managed["stage_refs"]
+    mismatched = copy.deepcopy(retired[0])
+    mismatched["field_index"]["value"]["member"] = "batch.other"
+    with pytest.raises(ValueError, match="fragment mismatch"):
+        catalog.ack_retired([mismatched])
+    assert catalog.ack_retired(retired)["retired_handles"] == []
+
+
+def test_catalog_drain_is_terminal() -> None:
+    catalog = DataProtoCatalog()
+    managed = handle("managed", ["value"], batch_size=1)
+    catalog.publish("pending-op", "train", ["a"], handle=managed)
+
+    retired = catalog.drain()["retired_handles"]
+    with pytest.raises(RuntimeError, match="catalog is drained"):
+        catalog.publish("pending-op", "train", ["a"], handle=managed)
+    assert catalog.ack_retired(retired)["retired_handles"] == []
+
+
+def test_catalog_append_replaces_managed_handle_ownership() -> None:
+    catalog = DataProtoCatalog()
+    base = handle("base", ["input", "value"], batch_size=1)
+    base["storage_group_id"] = "structured-test"
+    base["partition"] = "train"
+    catalog.publish("put-op", "train", ["a"], handle=base)
+    catalog.ack_publication("put-op")
+    catalog.update(
+        "train", ["a"], handle=handle("replacement", ["value"], batch_size=1)
+    )
+
+    appended = copy.deepcopy(base)
+    appended["stage_refs"]["value"] = {"manifest_key": "manifest/value"}
+    appended["field_index"]["score"] = {
+        "stage": "value",
+        "member": "batch.score",
+        "section": "batch",
+    }
+    assert "fragment identity" in catalog.publish_append(
+        "wrong-partition",
+        "manifest/base",
+        "other",
+        ["a"],
+        previous_handle=base,
+        handle=appended,
+    )["append_rejected"]
+    catalog.publish_append(
+        "append-op",
+        "manifest/base",
+        "train",
+        ["a"],
+        previous_handle=base,
+        handle=appended,
+    )
+    assert catalog.publish_append(
+        "append-op",
+        "manifest/base",
+        "train",
+        ["a"],
+        previous_handle=base,
+        handle=appended,
+    )["fields"] == ["input", "value", "score"]
+    assert "stale" in catalog.publish_append(
+        "stale-op",
+        "manifest/base",
+        "train",
+        ["a"],
+        previous_handle=base,
+        handle=appended,
+    )["append_rejected"]
+
+    plan = catalog.resolve("train", ["a"])
+    assert plan["fields"] == ["input", "value", "score"]
+    assert set(plan["handles"]) == {"manifest/base", "manifest/replacement"}
+    assert plan["handles"]["manifest/base"]["stage_refs"] == appended["stage_refs"]
+    assert plan["field_groups"][1]["locations"] == [("manifest/replacement", 0)]
+    retired = catalog.remove("train", ["a"])["retired_handles"]
+    assert retired == [plan["handles"]["manifest/base"]]
+    assert catalog.ack_retired(retired)["retired_handles"] == []
+
+
+class FakeTransfer:
+    def __init__(self) -> None:
+        self.count = self.release_attempts = 0
+        self.cleaned = []
+
+    def put(self, data, **_kwargs):
+        self.count += 1
+        return import_dataproto_ref(
+            handle(f"put-{self.count}", list(data.fields), len(data))
+        )
+
+    def cleanup_dataproto(self, ref) -> None:
+        self.cleaned.append(next(iter(ref["stage_refs"].values()))["manifest_key"])
+
+    def release_result(self, _result) -> None:
+        self.release_attempts += 1
+        if self.release_attempts == 1:
+            raise RuntimeError("release failed")
+
+
+def test_catalog_transfer_lifecycle_and_failure_retries() -> None:
+    catalog, transfer = DataProtoCatalog(), FakeTransfer()
+
+    def call(method, *args, **kwargs):
+        return getattr(catalog, method)(*args, **kwargs)
+
+    client = DataProtoCatalogTransfer(transfer, call)
+    data = type("FakeData", (list,), {"fields": ("value",)})([None])
+    client.put(data, partition="train", keys=["a"])
+    first_read = client.resolve("train", ["a"])
+    second_read = client.resolve("train", ["a"])
+    client.remove("train", ["a"])
+    client.release_read(first_read["read_token"])
+    assert transfer.cleaned == []
+    with pytest.raises(RuntimeError, match="active read"):
+        client.drain()
+    client.release_read(second_read["read_token"])
+    assert transfer.cleaned == ["manifest/put-1"]
+
+    output = SimpleNamespace()
+    result = SimpleNamespace(batch={}, non_tensor_batch={}, meta_info={})
+    client.attach_results(output, [result])
+    client.release_result(output)
+    assert transfer.release_attempts == 2
+
+    publication_failure = "before_commit"
+    lost_responses = 0
+
+    def fail_update(method, *args, **kwargs):
+        nonlocal publication_failure, lost_responses
+        if method != "publish":
+            return call(method, *args, **kwargs)
+        if publication_failure == "before_commit":
+            raise RuntimeError("publication failed")
+        result = call(method, *args, **kwargs)
+        if publication_failure == "after_commit" and lost_responses:
+            lost_responses -= 1
+            raise RuntimeError("response lost after commit")
+        return result
+
+    client._catalog_call = fail_update
+    with pytest.raises(RuntimeError, match="publication failed"):
+        client.put(data, partition="train", keys=["b"])
+    assert transfer.cleaned == ["manifest/put-1"]
+
+    publication_failure = None
+    client.close()
+    assert catalog.resolve("train", ["b"])["fields"] == ["value"]
+    client.remove("train", ["b"])
+    assert transfer.cleaned[-1] == "manifest/put-2"
+
+    publication_failure = "after_commit"
+    lost_responses = 2
+    with pytest.raises(RuntimeError, match="response lost"):
+        client.put(data, partition="train", keys=["c"])
+    assert catalog.resolve("train", ["c"])["fields"] == ["value"]
+    assert transfer.cleaned[-1] == "manifest/put-2"
+
+    publication_failure = None
+    client.close()
+    client.remove("train", ["c"])
+    assert transfer.cleaned[-1] == "manifest/put-3"
+
+
+def test_catalog_transfer_drain_resolves_pending_publications() -> None:
+    catalog, transfer = DataProtoCatalog(), FakeTransfer()
+    fail_publication = True
+
+    def call(method, *args, **kwargs):
+        if method == "publish" and fail_publication:
+            raise RuntimeError("publication failed")
+        return getattr(catalog, method)(*args, **kwargs)
+
+    client = DataProtoCatalogTransfer(transfer, call)
+    data = type("FakeData", (list,), {"fields": ("value",)})([None])
+    with pytest.raises(RuntimeError, match="publication failed"):
+        client.put(data, partition="train", keys=["a"])
+    with pytest.raises(RuntimeError, match="publish pending"):
+        client.drain()
+
+    fail_publication = False
+    client.drain()
+    assert transfer.cleaned == ["manifest/put-1"]
+
+
+def test_catalog_retry_does_not_resurrect_a_superseded_fragment() -> None:
+    catalog, transfer = DataProtoCatalog(), FakeTransfer()
+
+    def call(method, *args, **kwargs):
+        return getattr(catalog, method)(*args, **kwargs)
+
+    lost_responses = 2
+
+    def lose_publish_response(method, *args, **kwargs):
+        nonlocal lost_responses
+        result = call(method, *args, **kwargs)
+        if method == "publish" and lost_responses:
+            lost_responses -= 1
+            raise RuntimeError("response lost after commit")
+        return result
+
+    data = type("FakeData", (list,), {"fields": ("value",)})([None])
+    first = DataProtoCatalogTransfer(transfer, lose_publish_response)
+    with pytest.raises(RuntimeError, match="response lost"):
+        first.put(data, partition="train", keys=["a"])
+
+    second = DataProtoCatalogTransfer(transfer, call)
+    second.put(data, partition="train", keys=["a"])
+    assert transfer.cleaned == ["manifest/put-1"]
+
+    first.close()
+    plan = catalog.resolve("train", ["a"])
+    assert set(plan["handles"]) == {"manifest/put-2"}
+    assert transfer.cleaned == ["manifest/put-1"]
+
+
+def test_catalog_ack_retry_does_not_republish_a_superseded_fragment() -> None:
+    catalog, transfer = DataProtoCatalog(), FakeTransfer()
+
+    def call(method, *args, **kwargs):
+        return getattr(catalog, method)(*args, **kwargs)
+
+    lose_ack = True
+
+    def lose_ack_response(method, *args, **kwargs):
+        nonlocal lose_ack
+        result = call(method, *args, **kwargs)
+        if method == "ack_publication" and lose_ack:
+            lose_ack = False
+            raise RuntimeError("ack response lost")
+        return result
+
+    data = type("FakeData", (list,), {"fields": ("value",)})([None])
+    first = DataProtoCatalogTransfer(transfer, lose_ack_response)
+    first.put(data, partition="train", keys=["a"])
+
+    second = DataProtoCatalogTransfer(transfer, call)
+    second.put(data, partition="train", keys=["a"])
+    first.close()
+
+    plan = catalog.resolve("train", ["a"])
+    assert set(plan["handles"]) == {"manifest/put-2"}
+    assert transfer.cleaned == ["manifest/put-1"]
diff --git a/mooncake-wheel/tests/test_distributed_object_store.py b/mooncake-wheel/tests/test_distributed_object_store.py
index 880a3b532c..bbb967ec6b 100644
--- a/mooncake-wheel/tests/test_distributed_object_store.py
+++ b/mooncake-wheel/tests/test_distributed_object_store.py
@@ -2,7 +2,8 @@
 import os
 import time
 import threading
-from mooncake.store import MooncakeDistributedStore
+import random
+from mooncake.store import MooncakeDistributedStore, SoftPinAction
 
 # The lease time of the kv object, should be set equal to
 # the master's value.
@@ -53,6 +54,27 @@ def get_config_dict(global_segment_size, local_buffer_size):
     }
 
 
+class TestReplicateConfig(unittest.TestCase):
+    """Test ReplicateConfig bindings without a running store service."""
+
+    def test_soft_pin_ttl_optional_conversion(self):
+        from mooncake.store import ReplicateConfig
+
+        config = ReplicateConfig()
+        self.assertIsNone(config.soft_pin_ttl_ms)
+
+        config.soft_pin_ttl_ms = 1000
+        self.assertEqual(config.soft_pin_ttl_ms, 1000)
+
+        config.soft_pin_ttl_ms = None
+        self.assertIsNone(config.soft_pin_ttl_ms)
+
+        with self.assertRaises(TypeError):
+            config.soft_pin_ttl_ms = -1
+        with self.assertRaises(TypeError):
+            config.soft_pin_ttl_ms = 1 << 64
+
+
 class TestConfigDictSetup(unittest.TestCase):
     """Test configuration-dictionary setup through the Python store wrapper."""
 
@@ -156,6 +178,33 @@ def test_basic_put_get_exist_operations(self):
         time.sleep(default_kv_lease_ttl / 1000)
         self.assertEqual(self.store.remove(key), 0)
 
+    def test_soft_pin_config_forwarding(self):
+        """Test soft-pin action and TTL forwarding through Store operations."""
+        from mooncake.store import ReplicateConfig
+
+        key = f"test_soft_pin_config_forwarding_{os.getpid()}"
+        test_data = b"soft-pin forwarding"
+
+        enable_config = ReplicateConfig()
+        enable_config.soft_pin_action = SoftPinAction.ENABLE
+        enable_config.soft_pin_ttl_ms = 1000
+        self.assertEqual(self.store.put(key, test_data, enable_config), 0)
+
+        preserve_with_ttl = ReplicateConfig()
+        preserve_with_ttl.soft_pin_ttl_ms = 1000
+        self.assertEqual(self.store.upsert(key, test_data, preserve_with_ttl), -600)
+
+        disable_with_ttl = ReplicateConfig()
+        disable_with_ttl.soft_pin_action = SoftPinAction.DISABLE
+        disable_with_ttl.soft_pin_ttl_ms = 1000
+        self.assertEqual(self.store.upsert(key, test_data, disable_with_ttl), -600)
+
+        self.assertEqual(self.store.upsert(key, test_data), 0)
+
+        disable_config = ReplicateConfig()
+        disable_config.soft_pin_action = SoftPinAction.DISABLE
+        self.assertEqual(self.store.upsert(key, test_data, disable_config), 0)
+
     def test_batch_is_exist_operations(self):
         """Test batch is_exist operations through the Python interface."""
         batch_size = 20
@@ -662,16 +711,16 @@ def test_replicate_config_creation_and_properties(self):
         # Test default constructor
         config = ReplicateConfig()
         self.assertEqual(config.replica_num, 1)
-        self.assertEqual(config.with_soft_pin, False)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.PRESERVE)
         self.assertEqual(config.preferred_segment, "")
         
         # Test property assignment
         config.replica_num = 3
-        config.with_soft_pin = True
+        config.soft_pin_action = SoftPinAction.ENABLE
         config.preferred_segment = "node1:12345"
         
         self.assertEqual(config.replica_num, 3)
-        self.assertEqual(config.with_soft_pin, True)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.ENABLE)
         self.assertEqual(config.preferred_segment, "node1:12345")
         
         # Test string representation
diff --git a/mooncake-wheel/tests/test_distributed_object_store_cxl.py b/mooncake-wheel/tests/test_distributed_object_store_cxl.py
index a08382f5dc..e41e6f5c49 100644
--- a/mooncake-wheel/tests/test_distributed_object_store_cxl.py
+++ b/mooncake-wheel/tests/test_distributed_object_store_cxl.py
@@ -3,7 +3,7 @@
 import time
 import threading
 import tempfile
-from mooncake.store import MooncakeDistributedStore
+from mooncake.store import MooncakeDistributedStore, SoftPinAction
 
 CXL_SIM_FILE = os.path.join(tempfile.gettempdir(), "tmp_dax_sim")
 CXL_SIM_SIZE = 8 * 1024 * 1024 * 1024
@@ -588,16 +588,16 @@ def test_replicate_config_creation_and_properties(self):
         # Test default constructor
         config = ReplicateConfig()
         self.assertEqual(config.replica_num, 1)
-        self.assertEqual(config.with_soft_pin, False)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.PRESERVE)
         self.assertEqual(config.preferred_segment, "")
 
         # Test property assignment
         config.replica_num = 3
-        config.with_soft_pin = True
+        config.soft_pin_action = SoftPinAction.ENABLE
         config.preferred_segment = "node1:12345"
 
         self.assertEqual(config.replica_num, 3)
-        self.assertEqual(config.with_soft_pin, True)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.ENABLE)
         self.assertEqual(config.preferred_segment, "node1:12345")
 
         # Test string representation
diff --git a/mooncake-wheel/tests/test_dummy_client.py b/mooncake-wheel/tests/test_dummy_client.py
index c35c9d9492..2cd5e72cb3 100644
--- a/mooncake-wheel/tests/test_dummy_client.py
+++ b/mooncake-wheel/tests/test_dummy_client.py
@@ -1,40 +1,301 @@
-import unittest
+import json
+import math
 import os
-import time
 import threading
+import time
+import unittest
 
 try:
     import torch
-except ImportError:
+except ModuleNotFoundError as error:
+    if error.name != "torch":
+        raise
     torch = None
 
-from mooncake.store import MooncakeDistributedStore
+import mooncake.store as mooncake_store
+from mooncake.store import MooncakeDistributedStore, SoftPinAction
 
 # The lease time of the kv object, should be set equal to
 # the master's value.
-DEFAULT_DEFAULT_KV_LEASE_TTL = 5000 # 5000 milliseconds
+DEFAULT_DEFAULT_KV_LEASE_TTL = 5000  # 5000 milliseconds
 # Use environment variable if set, otherwise use default
-default_kv_lease_ttl = int(os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL))
+default_kv_lease_ttl = int(
+    os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL)
+)
+
+CUDA_IPC_STREAM_READINESS_PAYLOAD_BYTES = 16 * 1024 * 1024
+_CUDA_IPC_INITIAL_BYTE = 0x31
+_CUDA_IPC_FINAL_BYTE = 0xA7
+_CUDA_LAUNCH_BLOCKING_DISABLED_VALUES = {"", "0", "false", "no", "off"}
+
+
+class _CudaIpcStreamReadinessFailure(AssertionError):
+    """A CUDA readiness failure whose diagnostics are safe to publish."""
+
+    def __init__(self, diagnostics):
+        self.diagnostics = diagnostics
+        compact = json.dumps(diagnostics, sort_keys=True, separators=(",", ":"))
+        super().__init__(f"CUDA IPC stream readiness case failed: {compact}")
+
+
+def _cuda_launch_blocking_is_active():
+    value = os.environ.get("CUDA_LAUNCH_BLOCKING")
+    return (
+        value is not None
+        and value.strip().lower() not in _CUDA_LAUNCH_BLOCKING_DISABLED_VALUES
+    )
+
+
+def _cuda_stream_readiness_skip_reason():
+    if torch is None:
+        return "PyTorch is not available"
+    if getattr(torch.version, "cuda", None) is None:
+        return "PyTorch does not have CUDA support"
+    if not torch.cuda.is_available():
+        return "CUDA is not available"
+    if not callable(getattr(torch.cuda, "_sleep", None)):
+        return "torch.cuda._sleep is not available"
+    if _cuda_launch_blocking_is_active():
+        return "CUDA_LAUNCH_BLOCKING disables the asynchronous window"
+    return None
+
+
+def _calibrate_cuda_sleep_cycles():
+    target_ms = 300.0
+    minimum_ms = 200.0
+    maximum_ms = 750.0
+    minimum_cycles = 1
+    maximum_cycles = 2_000_000_000
+    cycles = 1_000_000
+    device = torch.device("cuda", torch.cuda.current_device())
+    calibration_stream = torch.cuda.Stream(device=device)
+
+    for _ in range(6):
+        start = torch.cuda.Event(enable_timing=True)
+        end = torch.cuda.Event(enable_timing=True)
+        with torch.cuda.stream(calibration_stream):
+            start.record()
+            torch.cuda._sleep(cycles)
+            end.record()
+        end.synchronize()
+        elapsed_ms = float(start.elapsed_time(end))
+        if minimum_ms <= elapsed_ms <= maximum_ms:
+            return cycles
+        if not math.isfinite(elapsed_ms) or elapsed_ms <= 0.0:
+            break
+        cycles = round(cycles * target_ms / elapsed_ms)
+        cycles = max(minimum_cycles, min(maximum_cycles, cycles))
+
+    raise AssertionError("Unable to establish the CUDA asynchronous window")
+
+
+def _put_cuda_readiness_tensors(store, keys, tensors, batch_width):
+    if batch_width == 1:
+        return store.put_tensor(keys[0], tensors[0]) == 0
+    return list(store.batch_put_tensor(keys, tensors)) == [0] * batch_width
+
+
+def _get_cuda_readiness_tensors(store, keys, batch_width):
+    if batch_width == 1:
+        return [store.get_tensor(keys[0])]
+    return list(store.batch_get_tensor(keys))
+
+
+def _validate_cuda_readiness_payloads(
+    retrieved, batch_width, payload_bytes, expected_byte
+):
+    if len(retrieved) != batch_width:
+        return False, -1, 0
+
+    metadata_ok = True
+    mismatch_count = 0
+    checksum = 0
+    for actual in retrieved:
+        if not isinstance(actual, torch.Tensor):
+            metadata_ok = False
+            mismatch_count = -1
+            continue
+        actual_cpu = actual.detach().cpu()
+        checksum += int(actual_cpu.sum(dtype=torch.int64).item())
+        if actual_cpu.dtype != torch.uint8 or tuple(actual_cpu.shape) != (
+            payload_bytes,
+        ):
+            metadata_ok = False
+            mismatch_count = -1
+            continue
+        if mismatch_count >= 0:
+            mismatch_count += int(
+                torch.count_nonzero(actual_cpu != expected_byte).item()
+            )
+    return metadata_ok, mismatch_count, checksum
+
+
+def _new_cuda_readiness_diagnostics(batch_width, explicit_sync):
+    return {
+        "mode": "control" if explicit_sync else "async",
+        "batch_width": batch_width,
+        "pending_at_call": None,
+        "ready_at_return": None,
+        "latency_ms": None,
+        "mismatch_count": None,
+        "checksum": None,
+    }
+
+
+def _run_dummy_cuda_ipc_stream_readiness_case(
+    store,
+    batch_width,
+    explicit_sync,
+    sleep_cycles,
+    payload_bytes=CUDA_IPC_STREAM_READINESS_PAYLOAD_BYTES,
+):
+    if batch_width not in (1, 2) or payload_bytes <= 0:
+        raise ValueError("invalid synthetic CUDA readiness parameters")
+
+    diagnostics = _new_cuda_readiness_diagnostics(batch_width, explicit_sync)
+    prefix = f"dummy_cuda_ipc_readiness_{os.getpid()}_{time.monotonic_ns()}"
+    warm_keys = [f"{prefix}_warm_{index}" for index in range(batch_width)]
+    measured_keys = [f"{prefix}_measured_{index}" for index in range(batch_width)]
+    cleanup_keys = [*warm_keys, *measured_keys]
+    tensors = []
+    primary_failed = False
+    cleanup_failed = False
+
+    try:
+        device = torch.device("cuda", torch.cuda.current_device())
+        with torch.cuda.device(device):
+            current = torch.cuda.current_stream(device)
+            tensors = [
+                torch.full(
+                    (payload_bytes,),
+                    _CUDA_IPC_INITIAL_BYTE,
+                    dtype=torch.uint8,
+                    device=device,
+                ).contiguous()
+                for _ in range(batch_width)
+            ]
+
+            # Make the initial value host-ready before opening the async window.
+            current.synchronize()
+            if not all(
+                tensor.is_contiguous()
+                and tensor.dtype == torch.uint8
+                and tuple(tensor.shape) == (payload_bytes,)
+                for tensor in tensors
+            ):
+                primary_failed = True
+
+            if not primary_failed:
+                warm_ok = _put_cuda_readiness_tensors(
+                    store, warm_keys, tensors, batch_width
+                )
+                warm_payloads = _get_cuda_readiness_tensors(
+                    store, warm_keys, batch_width
+                )
+                warm_metadata_ok, warm_mismatch_count, _ = (
+                    _validate_cuda_readiness_payloads(
+                        warm_payloads,
+                        batch_width,
+                        payload_bytes,
+                        _CUDA_IPC_INITIAL_BYTE,
+                    )
+                )
+                if not warm_ok or not warm_metadata_ok or warm_mismatch_count != 0:
+                    primary_failed = True
+
+            if not primary_failed:
+                producer = torch.cuda.Stream(device=device)
+                ready = torch.cuda.Event()
+                try:
+                    with torch.cuda.stream(producer):
+                        torch.cuda._sleep(sleep_cycles)
+                        for tensor in tensors:
+                            tensor.fill_(_CUDA_IPC_FINAL_BYTE)
+                        ready.record(producer)
+
+                    current.wait_stream(producer)
+                    if explicit_sync:
+                        current.synchronize()
+
+                    ready_before_put = bool(ready.query())
+                    diagnostics["pending_at_call"] = not ready_before_put
+                    valid_window = (
+                        ready_before_put if explicit_sync else not ready_before_put
+                    )
+                    if not valid_window:
+                        primary_failed = True
+                    else:
+                        put_started = time.perf_counter()
+                        try:
+                            put_ok = _put_cuda_readiness_tensors(
+                                store, measured_keys, tensors, batch_width
+                            )
+                        finally:
+                            diagnostics["latency_ms"] = round(
+                                (time.perf_counter() - put_started) * 1000.0, 3
+                            )
+                        diagnostics["ready_at_return"] = bool(ready.query())
+                        if not put_ok or not diagnostics["ready_at_return"]:
+                            primary_failed = True
+                finally:
+                    producer.synchronize()
+
+            if not primary_failed:
+                retrieved = _get_cuda_readiness_tensors(
+                    store, measured_keys, batch_width
+                )
+                metadata_ok, mismatch_count, checksum = (
+                    _validate_cuda_readiness_payloads(
+                        retrieved,
+                        batch_width,
+                        payload_bytes,
+                        _CUDA_IPC_FINAL_BYTE,
+                    )
+                )
+                diagnostics["mismatch_count"] = mismatch_count
+                diagnostics["checksum"] = checksum
+                expected_checksum = _CUDA_IPC_FINAL_BYTE * payload_bytes * batch_width
+                if (
+                    not metadata_ok
+                    or mismatch_count != 0
+                    or checksum != expected_checksum
+                ):
+                    primary_failed = True
+    except Exception:
+        primary_failed = True
+    finally:
+        for key in cleanup_keys:
+            try:
+                if store.remove(key, force=True) != 0:
+                    cleanup_failed = True
+            except Exception:
+                cleanup_failed = True
+
+    # Preserve primary failure precedence while suppressing raw exception text,
+    # which may contain identifiers forbidden from public diagnostics.
+    if primary_failed:
+        raise _CudaIpcStreamReadinessFailure(diagnostics) from None
+    if cleanup_failed:
+        raise _CudaIpcStreamReadinessFailure(diagnostics) from None
+    return diagnostics
 
 
 def get_client(store, local_buffer_size_param=None):
     """Initialize and setup the distributed store client."""
     mem_pool_size = 3200 * 1024 * 1024  # 3200 MB
     local_buffer_size = (
-        local_buffer_size_param if local_buffer_size_param is not None
+        local_buffer_size_param
+        if local_buffer_size_param is not None
         else 512 * 1024 * 1024  # 512 MB
     )
     real_client_address = "127.0.0.1:50052"
 
-    retcode = store.setup_dummy(
-        mem_pool_size,
-        local_buffer_size,
-        real_client_address
-    )
+    retcode = store.setup_dummy(mem_pool_size, local_buffer_size, real_client_address)
 
     if retcode:
         raise RuntimeError(f"Failed to setup store client. Return code: {retcode}")
 
+
 class TestDistributedObjectStoreSingleStore(unittest.TestCase):
     """Test class for single store operations (no replication)."""
 
@@ -73,7 +334,7 @@ def test_batch_is_exist_operations(self):
         keys = [f"test_batch_exist_key_{i}" for i in range(batch_size)]
 
         # Put only the first half of the keys
-        existing_keys = keys[:batch_size // 2]
+        existing_keys = keys[: batch_size // 2]
         for key in existing_keys:
             self.assertEqual(self.store.put(key, test_data), 0)
 
@@ -85,11 +346,15 @@ def test_batch_is_exist_operations(self):
 
         # First half should exist (result = 1)
         for i in range(batch_size // 2):
-            self.assertEqual(results[i], 1, f"Key {keys[i]} should exist but got {results[i]}")
+            self.assertEqual(
+                results[i], 1, f"Key {keys[i]} should exist but got {results[i]}"
+            )
 
         # Second half should not exist (result = 0)
         for i in range(batch_size // 2, batch_size):
-            self.assertEqual(results[i], 0, f"Key {keys[i]} should not exist but got {results[i]}")
+            self.assertEqual(
+                results[i], 0, f"Key {keys[i]} should not exist but got {results[i]}"
+            )
 
         # Test with empty keys list
         empty_results = self.store.batch_is_exist([])
@@ -167,7 +432,11 @@ def test_get_into_ranges_operations(self):
         self.assertLess(destination_overflow_results[0][0][0], 0)
 
         missing_key_results = self.store.get_into_ranges(
-            [buffer_ptr0], [["missing-key", key1]], [[[0], [8]]], [[[0], [0]]], [[[4], [4]]]
+            [buffer_ptr0],
+            [["missing-key", key1]],
+            [[[0], [8]]],
+            [[[0], [0]]],
+            [[[4], [4]]],
         )
         self.assertLess(missing_key_results[0][0][0], 0)
         self.assertEqual(missing_key_results[0][1][0], 4)
@@ -178,6 +447,164 @@ def test_get_into_ranges_operations(self):
         self.assertEqual(self.store.remove(key1), 0)
         self.assertEqual(self.store.remove(key2), 0)
 
+    def test_external_host_registered_tensor_roundtrip(self):
+        """Registered pageable CPU tensors support bounded raw transfers."""
+        if torch is None:
+            self.skipTest("PyTorch is not available")
+        self._check_registered_cpu_tensor_roundtrip(pinned=False)
+
+    def test_external_host_registered_pinned_tensor_roundtrip(self):
+        """Pinned CPU tensors preserve data and guards across Dummy RPC."""
+        if torch is None or not torch.cuda.is_available():
+            self.skipTest("Pinned host allocation requires CUDA")
+        self._check_registered_cpu_tensor_roundtrip(pinned=True)
+
+    def _check_registered_cpu_tensor_roundtrip(self, pinned):
+        source = torch.empty(64, dtype=torch.int32, pin_memory=pinned)
+        source.copy_(torch.arange(64, dtype=torch.int32))
+        destination = torch.empty(80, dtype=torch.int32, pin_memory=pinned)
+        destination.fill_(-1)
+        self.assertEqual(source.is_pinned(), pinned)
+        self.assertEqual(destination.is_pinned(), pinned)
+        source_ptr = source.data_ptr()
+        destination_ptr = destination.data_ptr()
+        size = source.numel() * source.element_size()
+        capacity = destination.numel() * destination.element_size()
+        offset = 8 * destination.element_size()
+        key = f"test_dummy_registered_tensor_{os.getpid()}_{pinned}"
+        self.assertEqual(self.store.register_buffer(source_ptr, size), 0)
+        try:
+            self.assertEqual(self.store.register_buffer(destination_ptr, capacity), 0)
+            try:
+                self.assertEqual(self.store.put_from(key, source_ptr, size), 0)
+                self.assertEqual(
+                    self.store.get_into(key, destination_ptr + offset, size),
+                    size,
+                )
+                expected = torch.full((80,), -1, dtype=torch.int32)
+                expected[8:72] = source
+                self.assertTrue(torch.equal(destination, expected))
+
+                source.add_(100)
+                self.assertEqual(
+                    list(self.store.batch_upsert_from([key], [source_ptr], [size])),
+                    [0],
+                )
+                self.assertEqual(
+                    list(
+                        self.store.batch_get_into(
+                            [key], [destination_ptr + offset], [size]
+                        )
+                    ),
+                    [size],
+                )
+                expected[8:72] = source
+                self.assertTrue(torch.equal(destination, expected))
+
+                destination.fill_(-1)
+                self.assertEqual(
+                    self.store.get_into_ranges(
+                        [destination_ptr],
+                        [[key]],
+                        [[[offset]]],
+                        [[[source.element_size()]]],
+                        [[[16]]],
+                    ),
+                    [[[16]]],
+                )
+                expected.fill_(-1)
+                expected[8:12] = source[1:5]
+                self.assertTrue(torch.equal(destination, expected))
+                self.assertLess(
+                    self.store.get_into(key, destination_ptr + capacity - 4, size),
+                    0,
+                )
+                self.assertTrue(torch.equal(destination, expected))
+            finally:
+                self.assertEqual(self.store.unregister_buffer(destination_ptr), 0)
+            self.assertLess(self.store.get_into(key, destination_ptr, size), 0)
+            self.assertTrue(torch.equal(destination, expected))
+        finally:
+            self.assertEqual(self.store.unregister_buffer(source_ptr), 0)
+            self.store.remove(key, force=True)
+
+    def test_external_host_get_into_ranges_staging(self):
+        """Range reads stage a registered process-local host destination."""
+        import ctypes
+
+        keys = [
+            f"test_dummy_external_ranges_{os.getpid()}_0",
+            f"test_dummy_external_ranges_{os.getpid()}_1",
+        ]
+        values = [b"0123456789", b"abcdefghijklm"]
+        for key, value in zip(keys, values):
+            self.assertEqual(self.store.put(key, value), 0)
+
+        capacity = 64
+        destination = (ctypes.c_ubyte * capacity)()
+        destination_ptr = ctypes.addressof(destination)
+        self.assertEqual(self.store.register_buffer(destination_ptr, capacity), 0)
+        try:
+            ctypes.memset(destination_ptr, ord("_"), capacity)
+            range_results = self.store.get_into_ranges(
+                [destination_ptr],
+                [keys],
+                [[[1, 12], [24]]],
+                [[[2, 7], [3]]],
+                [[[4, 3], [5]]],
+            )
+            self.assertEqual(range_results, [[[4, 3], [5]]])
+            self.assertEqual(bytes(destination[1:5]), values[0][2:6])
+            self.assertEqual(bytes(destination[12:15]), values[0][7:10])
+            self.assertEqual(bytes(destination[24:29]), values[1][3:8])
+            self.assertEqual(destination[0], ord("_"))
+            self.assertEqual(bytes(destination[5:12]), b"_" * 7)
+        finally:
+            self.assertEqual(self.store.unregister_buffer(destination_ptr), 0)
+            for key in keys:
+                self.store.remove(key, force=True)
+
+    def test_external_host_multi_buffer_read_staging(self):
+        """Multi-buffer reads copy only returned bytes from host staging."""
+        import ctypes
+
+        keys = [
+            f"test_dummy_external_multi_read_{os.getpid()}_0",
+            f"test_dummy_external_multi_read_{os.getpid()}_1",
+        ]
+        values = [b"0123456789", b"abcdefghijklm"]
+        for key, value in zip(keys, values):
+            self.assertEqual(self.store.put(key, value), 0)
+
+        capacity = 64
+        destination = (ctypes.c_ubyte * capacity)()
+        destination_ptr = ctypes.addressof(destination)
+        self.assertEqual(self.store.register_buffer(destination_ptr, capacity), 0)
+        try:
+            ctypes.memset(destination_ptr, ord("_"), capacity)
+            multi_buffer_results = self.store.batch_get_into_multi_buffers(
+                keys,
+                [
+                    [
+                        destination_ptr + 50,
+                        destination_ptr,
+                        destination_ptr + 4,
+                    ],
+                    [destination_ptr + 20, destination_ptr + 25],
+                ],
+                [[0, 4, 6], [5, 8]],
+                False,
+            )
+            self.assertEqual(list(multi_buffer_results), [10, 13])
+            self.assertEqual(bytes(destination[0:10]), values[0])
+            self.assertEqual(bytes(destination[20:33]), values[1])
+            self.assertEqual(bytes(destination[10:20]), b"_" * 10)
+            self.assertEqual(bytes(destination[33:35]), b"__")
+        finally:
+            self.assertEqual(self.store.unregister_buffer(destination_ptr), 0)
+            for key in keys:
+                self.store.remove(key, force=True)
+
     def test_batch_get_into_operations(self):
         """Test batch_get_into operations for multiple keys."""
         import ctypes
@@ -202,7 +629,9 @@ def test_batch_get_into_operations(self):
         # Allocate one large buffer with significant spacing
         total_buffer_size = buffer_spacing * batch_size
         large_buffer_ptr = self.store.alloc_from_mem_pool(total_buffer_size)
-        large_buffer = (ctypes.c_char * total_buffer_size).from_address(large_buffer_ptr)
+        large_buffer = (ctypes.c_char * total_buffer_size).from_address(
+            large_buffer_ptr
+        )
 
         # Register the entire large buffer once
         result = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
@@ -229,28 +658,46 @@ def test_batch_get_into_operations(self):
         self.assertEqual(len(results), batch_size, "Should return result for each key")
 
         for i, (expected_data, result) in enumerate(zip(test_data, results)):
-            self.assertGreater(result, 0, f"batch_get_into should succeed for key {keys[i]}")
-            self.assertEqual(result, len(expected_data), f"Should read correct number of bytes for key {keys[i]}")
+            self.assertGreater(
+                result, 0, f"batch_get_into should succeed for key {keys[i]}"
+            )
+            self.assertEqual(
+                result,
+                len(expected_data),
+                f"Should read correct number of bytes for key {keys[i]}",
+            )
 
             # Verify data integrity - read from the correct offset in the large buffer
             offset = i * buffer_spacing
-            read_data = bytes(large_buffer[offset:offset + result])
-            self.assertEqual(read_data, expected_data, f"Data should match for key {keys[i]}")
+            read_data = bytes(large_buffer[offset : offset + result])
+            self.assertEqual(
+                read_data, expected_data, f"Data should match for key {keys[i]}"
+            )
 
         # Test error cases
         # Test with mismatched array sizes
-        mismatched_results = self.store.batch_get_into(keys[:2], buffer_ptrs[:3], buffer_sizes[:3])
-        self.assertEqual(len(mismatched_results), 2, "Should return results for provided keys")
+        mismatched_results = self.store.batch_get_into(
+            keys[:2], buffer_ptrs[:3], buffer_sizes[:3]
+        )
+        self.assertEqual(
+            len(mismatched_results), 2, "Should return results for provided keys"
+        )
         for result in mismatched_results:
             self.assertLess(result, 0, "Should fail with mismatched array sizes")
 
         # Test with empty arrays
         empty_results = self.store.batch_get_into([], [], [])
-        self.assertEqual(len(empty_results), 0, "Should return empty results for empty input")
+        self.assertEqual(
+            len(empty_results), 0, "Should return empty results for empty input"
+        )
 
         # Cleanup
         time.sleep(default_kv_lease_ttl / 1000)
-        self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration should succeed")
+        self.assertEqual(
+            self.store.unregister_buffer(large_buffer_ptr),
+            0,
+            "Buffer unregistration should succeed",
+        )
         for key in keys:
             self.assertEqual(self.store.remove(key), 0)
 
@@ -273,7 +720,9 @@ def test_batch_put_from_operations(self):
         # Allocate one large buffer with significant spacing
         total_buffer_size = buffer_spacing * batch_size
         large_buffer_ptr = self.store.alloc_from_mem_pool(total_buffer_size)
-        large_buffer = (ctypes.c_char * total_buffer_size).from_address(large_buffer_ptr)
+        large_buffer = (ctypes.c_char * total_buffer_size).from_address(
+            large_buffer_ptr
+        )
 
         # Register the entire large buffer once
         result = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
@@ -303,27 +752,43 @@ def test_batch_put_from_operations(self):
         self.assertEqual(len(results), batch_size, "Should return result for each key")
 
         for i, result in enumerate(results):
-            self.assertEqual(result, 0, f"batch_put_from should succeed for key {keys[i]}")
+            self.assertEqual(
+                result, 0, f"batch_put_from should succeed for key {keys[i]}"
+            )
 
         # Verify data was stored correctly using regular get
         for i, (key, expected_data) in enumerate(zip(keys, test_data)):
             retrieved_data = self.store.get(key)
-            self.assertEqual(retrieved_data, expected_data, f"Data should match after batch_put_from for key {key}")
+            self.assertEqual(
+                retrieved_data,
+                expected_data,
+                f"Data should match after batch_put_from for key {key}",
+            )
 
         # Test error cases
         # Test with mismatched array sizes
-        mismatched_results = self.store.batch_put_from(keys[:2], buffer_ptrs[:3], buffer_sizes[:3])
-        self.assertEqual(len(mismatched_results), 2, "Should return results for provided keys")
+        mismatched_results = self.store.batch_put_from(
+            keys[:2], buffer_ptrs[:3], buffer_sizes[:3]
+        )
+        self.assertEqual(
+            len(mismatched_results), 2, "Should return results for provided keys"
+        )
         for result in mismatched_results:
             self.assertLess(result, 0, "Should fail with mismatched array sizes")
 
         # Test with empty arrays
         empty_results = self.store.batch_put_from([], [], [])
-        self.assertEqual(len(empty_results), 0, "Should return empty results for empty input")
+        self.assertEqual(
+            len(empty_results), 0, "Should return empty results for empty input"
+        )
 
         # Cleanup
         time.sleep(default_kv_lease_ttl / 1000)
-        self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration should succeed")
+        self.assertEqual(
+            self.store.unregister_buffer(large_buffer_ptr),
+            0,
+            "Buffer unregistration should succeed",
+        )
         for key in keys:
             self.assertEqual(self.store.remove(key), 0)
 
@@ -338,24 +803,18 @@ def test_tensor_operations(self):
         key_from = f"{key}_from"
         batch_keys = [f"{key}_batch_{i}" for i in range(2)]
         upsert_key = f"{key}_upsert"
+        cuda_upsert_key = f"{key}_cuda_upsert"
         pub_key = f"{key}_pub"
         tp_key = f"{key}_tp"
         batch_tp_key = f"{key}_batch_tp"
-        parallel_key = f"{key}_parallel"
-        parallel_batch_keys = [f"{key}_parallel_batch_{i}" for i in range(2)]
-        parallel_from_key = f"{key}_parallel_from"
-        parallel_upsert_key = f"{key}_parallel_upsert"
-        parallel_upsert_from_key = f"{key}_parallel_upsert_from"
-        cleanup_keys = [key, key_from, *batch_keys, upsert_key, pub_key]
-        cleanup_keys.extend(
-            [
-                parallel_key,
-                *parallel_batch_keys,
-                parallel_from_key,
-                parallel_upsert_key,
-                parallel_upsert_from_key,
-            ]
-        )
+        cleanup_keys = [
+            key,
+            key_from,
+            *batch_keys,
+            upsert_key,
+            cuda_upsert_key,
+            pub_key,
+        ]
         cleanup_keys.extend(f"{tp_key}_tp_{rank}" for rank in range(2))
         cleanup_keys.extend(f"{batch_tp_key}_tp_{rank}" for rank in range(2))
         tensor = torch.arange(12, dtype=torch.float32).reshape(3, 4)
@@ -404,20 +863,26 @@ def test_tensor_operations(self):
             self.assertEqual(self.store.upsert_tensor(upsert_key, updated), 0)
             self.assertTrue(torch.equal(self.store.get_tensor(upsert_key), updated))
 
+            if torch.cuda.is_available():
+                cuda_updated = updated.to("cuda")
+                torch.cuda.synchronize()
+                self.assertEqual(
+                    self.store.upsert_tensor(cuda_upsert_key, cuda_updated), 0
+                )
+                self.assertTrue(
+                    torch.equal(self.store.get_tensor(cuda_upsert_key), updated)
+                )
+
             self.assertEqual(self.store.pub_tensor(pub_key, tensor + 3), 0)
             self.assertTrue(torch.equal(self.store.get_tensor(pub_key), tensor + 3))
 
             self.assertEqual(
-                self.store.put_tensor_with_tp(
-                    tp_key, tensor, tp_size=2, split_dim=1
-                ),
+                self.store.put_tensor_with_tp(tp_key, tensor, tp_size=2, split_dim=1),
                 0,
             )
             tp_shards = torch.chunk(tensor, 2, dim=1)
             for rank, expected in enumerate(tp_shards):
-                actual = self.store.get_tensor_with_tp(
-                    tp_key, tp_rank=rank, tp_size=2
-                )
+                actual = self.store.get_tensor_with_tp(tp_key, tp_rank=rank, tp_size=2)
                 self.assertIsNotNone(actual)
                 self.assertTrue(torch.equal(actual, expected.contiguous()))
 
@@ -425,63 +890,265 @@ def test_tensor_operations(self):
                 [batch_tp_key], [tensor], tp_size=2, split_dim=1
             )
             self.assertEqual(list(batch_tp_results), [0])
+        finally:
+            self.store.unregister_buffer(buffer_ptr)
+            for cleanup_key in cleanup_keys:
+                self.store.remove(cleanup_key)
+
+    def test_tensor_from_external_host_staging(self):
+        """Raw tensor *_from APIs accept a pageable host object buffer."""
+        import ctypes
 
+        if torch is None:
+            self.skipTest("PyTorch is not available")
+
+        tensor = torch.arange(12, dtype=torch.float32).reshape(3, 4)
+        metadata, _, payload_size, _ = mooncake_store._serialize_tensor(tensor)
+        metadata_size = len(metadata)
+        total_size = metadata_size + payload_size
+        raw = (ctypes.c_ubyte * total_size)()
+        raw_ptr = ctypes.addressof(raw)
+        ctypes.memmove(raw_ptr, metadata, metadata_size)
+        ctypes.memmove(raw_ptr + metadata_size, tensor.numpy().tobytes(), payload_size)
+
+        prefix = f"test_dummy_tensor_external_{os.getpid()}"
+        keys = [f"{prefix}_{i}" for i in range(3)]
+        try:
+            self.assertEqual(self.store.register_buffer(raw_ptr, total_size), 0)
             self.assertEqual(
-                self.store.put_tensor_with_parallelism(parallel_key, tensor),
-                0,
+                self.store.put_tensor_from(keys[0], raw_ptr, total_size), 0
             )
-            self.assertTrue(torch.equal(self.store.get_tensor(parallel_key), tensor))
+            self.assertTrue(torch.equal(self.store.get_tensor(keys[0]), tensor))
 
-            parallel_batch = [tensor + 4, tensor + 5]
-            parallel_batch_results = self.store.batch_put_tensor_with_parallelism(
-                parallel_batch_keys, parallel_batch
-            )
-            self.assertEqual(list(parallel_batch_results), [0, 0])
-            parallel_batch_retrieved = self.store.batch_get_tensor(
-                parallel_batch_keys
+            self.assertEqual(
+                list(
+                    self.store.batch_put_tensor_from(
+                        keys[1:], [raw_ptr, raw_ptr], [total_size, total_size]
+                    )
+                ),
+                [0, 0],
             )
-            for expected, actual in zip(parallel_batch, parallel_batch_retrieved):
-                self.assertIsNotNone(actual)
-                self.assertTrue(torch.equal(actual, expected))
+            for key in keys[1:]:
+                self.assertTrue(torch.equal(self.store.get_tensor(key), tensor))
 
+            updated = tensor + 5
+            ctypes.memmove(
+                raw_ptr + metadata_size, updated.numpy().tobytes(), payload_size
+            )
             self.assertEqual(
-                self.store.put_tensor_with_parallelism_from(
-                    parallel_from_key, buffer_ptr, buffer_size
-                ),
-                0,
+                self.store.upsert_tensor_from(keys[0], raw_ptr, total_size), 0
             )
-            self.assertTrue(
-                torch.equal(self.store.get_tensor(parallel_from_key), tensor)
+            self.assertTrue(torch.equal(self.store.get_tensor(keys[0]), updated))
+            self.assertEqual(
+                list(
+                    self.store.batch_upsert_tensor_from(
+                        keys[1:], [raw_ptr, raw_ptr], [total_size, total_size]
+                    )
+                ),
+                [0, 0],
             )
+            for key in keys[1:]:
+                self.assertTrue(torch.equal(self.store.get_tensor(key), updated))
+        finally:
+            self.store.unregister_buffer(raw_ptr)
+            for key in keys:
+                self.store.remove(key, force=True)
+
+    def test_tensor_from_external_pinned_host_staging(self):
+        """Raw tensor *_from APIs accept a registered pinned host buffer."""
+        import ctypes
 
-            parallel_update = tensor + 6
+        if torch is None:
+            self.skipTest("PyTorch is not available")
+
+        try:
+            tensor = torch.arange(12, dtype=torch.float32).reshape(3, 4)
+            metadata, _, payload_size, _ = mooncake_store._serialize_tensor(tensor)
+            metadata_size = len(metadata)
+            total_size = metadata_size + payload_size
+            raw = torch.empty(total_size, dtype=torch.uint8, pin_memory=True)
+        except RuntimeError as error:
+            self.skipTest(f"Pinned host allocation is unavailable: {error}")
+
+        raw_ptr = raw.data_ptr()
+        ctypes.memmove(raw_ptr, metadata, metadata_size)
+        ctypes.memmove(raw_ptr + metadata_size, tensor.numpy().tobytes(), payload_size)
+
+        self.assertTrue(raw.is_pinned())
+        self._check_external_tensor_writes(raw, tensor, "pinned")
+
+    def _check_external_tensor_writes(self, raw, tensor, label):
+        raw_ptr = raw.data_ptr()
+        total_size = raw.numel()
+        keys = [f"test_dummy_{label}_tensor_{os.getpid()}_{i}" for i in range(3)]
+        self.assertEqual(self.store.register_buffer(raw_ptr, total_size), 0)
+        try:
             self.assertEqual(
-                self.store.upsert_tensor_with_parallelism(
-                    parallel_upsert_key, parallel_update
+                self.store.put_tensor_from(keys[0], raw_ptr, total_size), 0
+            )
+            self.assertEqual(
+                list(
+                    self.store.batch_put_tensor_from(
+                        keys[1:], [raw_ptr] * 2, [total_size] * 2
+                    )
                 ),
-                0,
+                [0, 0],
             )
-            self.assertTrue(
-                torch.equal(
-                    self.store.get_tensor(parallel_upsert_key), parallel_update
-                )
+            for key in keys:
+                self.assertTrue(torch.equal(self.store.get_tensor(key), tensor))
+
+            updated = tensor + 7
+            metadata, _, _, _ = mooncake_store._serialize_tensor(updated)
+            serialized = torch.tensor(
+                list(metadata + updated.numpy().tobytes()), dtype=torch.uint8
+            )
+            raw.copy_(serialized)
+            if raw.is_cuda:
+                torch.cuda.synchronize(raw.device)
+            self.assertEqual(
+                self.store.upsert_tensor_from(keys[0], raw_ptr, total_size), 0
+            )
+            self.assertEqual(
+                list(
+                    self.store.batch_upsert_tensor_from(
+                        keys[1:], [raw_ptr] * 2, [total_size] * 2
+                    )
+                ),
+                [0, 0],
             )
+            for key in keys:
+                self.assertTrue(torch.equal(self.store.get_tensor(key), updated))
+        finally:
+            self.assertEqual(self.store.unregister_buffer(raw_ptr), 0)
+            for key in keys:
+                self.store.remove(key, force=True)
 
-            parallel_upsert_from_results = (
-                self.store.batch_upsert_tensor_with_parallelism_from(
-                    [parallel_upsert_from_key], [buffer_ptr], [buffer_size]
-                )
+    def test_tensor_from_external_cuda_staging(self):
+        """Exercise all four raw APIs with a registered CUDA serialized object."""
+        if torch is None or not torch.cuda.is_available():
+            self.skipTest("CUDA is not available")
+        tensor = torch.arange(12, dtype=torch.float32).reshape(3, 4)
+        metadata, _, _, _ = mooncake_store._serialize_tensor(tensor)
+        raw = torch.tensor(
+            list(metadata + tensor.numpy().tobytes()), dtype=torch.uint8, device="cuda"
+        )
+        torch.cuda.synchronize(raw.device)
+        self._check_external_tensor_writes(raw, tensor, "cuda")
+
+    def test_tensor_from_invalid_object_ranges(self):
+        """Reject malformed objects and overflow before dereferencing the header."""
+        import ctypes
+
+        if torch is None:
+            self.skipTest("PyTorch is not available")
+        tensor = torch.arange(4, dtype=torch.float32)
+        metadata, _, payload_size, _ = mooncake_store._serialize_tensor(tensor)
+        size = len(metadata) + payload_size
+        raw = (ctypes.c_ubyte * size)()
+        ptr = ctypes.addressof(raw)
+        ctypes.memmove(ptr, metadata, len(metadata))
+        max_address = (1 << (8 * ctypes.sizeof(ctypes.c_void_p))) - 1
+        key = f"test_dummy_invalid_tensor_{os.getpid()}"
+        self.assertEqual(self.store.register_buffer(ptr, size), 0)
+        try:
+            for address, length in [
+                (0, size),
+                (max_address - 8, size),
+                (ptr, len(metadata) - 1),
+                (ptr, size - 1),
+            ]:
+                with self.subTest(address=address, length=length):
+                    self.assertLess(self.store.put_tensor_from(key, address, length), 0)
+                    self.assertLess(
+                        self.store.upsert_tensor_from(key, address, length), 0
+                    )
+                    self.assertLess(
+                        self.store.batch_put_tensor_from([key], [address], [length])[0],
+                        0,
+                    )
+                    self.assertLess(
+                        self.store.batch_upsert_tensor_from([key], [address], [length])[
+                            0
+                        ],
+                        0,
+                    )
+                    self.assertEqual(self.store.is_exist(key), 0)
+        finally:
+            self.assertEqual(self.store.unregister_buffer(ptr), 0)
+            self.store.remove(key, force=True)
+
+    def test_tensor_from_external_zero_payload_staging(self):
+        """Dummy raw tensor writes preserve metadata-only tensor objects."""
+        import ctypes
+
+        if torch is None:
+            self.skipTest("PyTorch is not available")
+
+        tensor = torch.empty((2, 0, 3), dtype=torch.float32)
+        metadata, _, payload_size, _ = mooncake_store._serialize_tensor(tensor)
+        self.assertEqual(payload_size, 0)
+        raw = (ctypes.c_ubyte * len(metadata))()
+        raw_ptr = ctypes.addressof(raw)
+        ctypes.memmove(raw_ptr, metadata, len(metadata))
+
+        prefix = f"test_dummy_zero_payload_tensor_{os.getpid()}"
+        keys = [f"{prefix}_{i}" for i in range(4)]
+        try:
+            self.assertEqual(self.store.register_buffer(raw_ptr, len(metadata)), 0)
+            self.assertEqual(
+                self.store.put_tensor_from(keys[0], raw_ptr, len(metadata)), 0
             )
-            self.assertEqual(list(parallel_upsert_from_results), [0])
-            self.assertTrue(
-                torch.equal(
-                    self.store.get_tensor(parallel_upsert_from_key), tensor
-                )
+            self.assertEqual(
+                list(
+                    self.store.batch_put_tensor_from(
+                        keys[1:3], [raw_ptr, raw_ptr], [len(metadata)] * 2
+                    )
+                ),
+                [0, 0],
+            )
+            self.assertEqual(
+                list(
+                    self.store.batch_upsert_tensor_from(
+                        keys[1:3], [raw_ptr, raw_ptr], [len(metadata)] * 2
+                    )
+                ),
+                [0, 0],
+            )
+            self.assertEqual(
+                self.store.upsert_tensor_from(keys[3], raw_ptr, len(metadata)), 0
             )
+            for key in keys:
+                stored = self.store.get_tensor(key)
+                self.assertIsNotNone(stored)
+                self.assertEqual(tuple(stored.shape), tuple(tensor.shape))
+                self.assertEqual(stored.dtype, tensor.dtype)
+                self.assertEqual(stored.numel(), 0)
         finally:
-            self.store.unregister_buffer(buffer_ptr)
-            for cleanup_key in cleanup_keys:
-                self.store.remove(cleanup_key)
+            self.store.unregister_buffer(raw_ptr)
+            for key in keys:
+                self.store.remove(key, force=True)
+
+    def _run_dummy_cuda_ipc_stream_readiness_regression(self, batch_width):
+        skip_reason = _cuda_stream_readiness_skip_reason()
+        if skip_reason is not None:
+            self.skipTest(skip_reason)
+
+        sleep_cycles = _calibrate_cuda_sleep_cycles()
+        for explicit_sync in (False, True):
+            mode = "control" if explicit_sync else "async"
+            with self.subTest(mode=mode, batch_width=batch_width):
+                _run_dummy_cuda_ipc_stream_readiness_case(
+                    self.store,
+                    batch_width=batch_width,
+                    explicit_sync=explicit_sync,
+                    sleep_cycles=sleep_cycles,
+                )
+
+    def test_dummy_cuda_ipc_put_tensor_waits_for_current_stream(self):
+        self._run_dummy_cuda_ipc_stream_readiness_regression(batch_width=1)
+
+    def test_dummy_cuda_ipc_batch_put_tensor_waits_for_current_stream(self):
+        self._run_dummy_cuda_ipc_stream_readiness_regression(batch_width=2)
 
     def test_00_mixed_put_and_put_tensor_concurrency(self):
         """Regression test for regular put and tensor put sharing dummy SHM."""
@@ -493,8 +1160,7 @@ def test_00_mixed_put_and_put_tensor_concurrency(self):
         regular_keys = [f"{prefix}_regular_{i}" for i in range(iterations)]
         tensor_keys = [f"{prefix}_tensor_{i}" for i in range(iterations)]
         regular_values = [
-            (f"regular-payload-{i}-".encode() * 4096)
-            for i in range(iterations)
+            (f"regular-payload-{i}-".encode() * 4096) for i in range(iterations)
         ]
         tensors = [
             (torch.arange(4096, dtype=torch.float32) + i).reshape(64, 64)
@@ -557,67 +1223,70 @@ def put_tensors():
 
     # Mark this test as zzz_ so that it is the last test to run
     def zzz_test_dict_fuzz_e2e(self):
-         """End-to-end fuzz test comparing distributed store behavior with dict.
-         Performs ~1000 random operations (put, get, remove) with random value sizes between 1KB and 64MB.
-         After testing, all keys are removed.
-         """
-         import random
-         # Local reference dict to simulate expected dict behavior
-         reference = {}
-         operations = 1000
-         # Use a pool of keys to limit memory consumption
-         keys_pool = [f"key_{i}" for i in range(100)]
-         # Track which keys have values assigned to ensure consistency
-         key_values = {}
-         # Fuzz record for debugging in case of errors
-         fuzz_record = []
-         try:
-             for i in range(operations):
-                 op = random.choice(["put", "get", "remove"])
-                 key = random.choice(keys_pool)
-                 if op == "put":
-                     # If key already exists, use the same value to ensure consistency
-                     if key in key_values:
-                         value = key_values[key]
-                         size = len(value)
-                     else:
-                         size = random.randint(1, 64 * 1024 * 1024)
-                         value = os.urandom(size)
-                         key_values[key] = value
-
-                     fuzz_record.append(f"{i}: put {key} [size: {size}]")
-                     error_code = self.store.put(key, value)
-                     if error_code == -200:
-                         # The space is not enough, continue to next operation
-                         continue
-                     elif error_code == 0:
-                         reference[key] = value
-                     else:
-                         raise RuntimeError(f"Put operation failed for key {key}. Error code: {error_code}")
-                 elif op == "get":
-                     fuzz_record.append(f"{i}: get {key}")
-                     retrieved = self.store.get(key)
-                     if retrieved != b"": # Otherwise the key may have been evicted
+        """End-to-end fuzz test comparing distributed store behavior with dict.
+        Performs ~1000 random operations (put, get, remove) with random value sizes between 1KB and 64MB.
+        After testing, all keys are removed.
+        """
+        import random
+
+        # Local reference dict to simulate expected dict behavior
+        reference = {}
+        operations = 1000
+        # Use a pool of keys to limit memory consumption
+        keys_pool = [f"key_{i}" for i in range(100)]
+        # Track which keys have values assigned to ensure consistency
+        key_values = {}
+        # Fuzz record for debugging in case of errors
+        fuzz_record = []
+        try:
+            for i in range(operations):
+                op = random.choice(["put", "get", "remove"])
+                key = random.choice(keys_pool)
+                if op == "put":
+                    # If key already exists, use the same value to ensure consistency
+                    if key in key_values:
+                        value = key_values[key]
+                        size = len(value)
+                    else:
+                        size = random.randint(1, 64 * 1024 * 1024)
+                        value = os.urandom(size)
+                        key_values[key] = value
+
+                    fuzz_record.append(f"{i}: put {key} [size: {size}]")
+                    error_code = self.store.put(key, value)
+                    if error_code == -200:
+                        # The space is not enough, continue to next operation
+                        continue
+                    elif error_code == 0:
+                        reference[key] = value
+                    else:
+                        raise RuntimeError(
+                            f"Put operation failed for key {key}. Error code: {error_code}"
+                        )
+                elif op == "get":
+                    fuzz_record.append(f"{i}: get {key}")
+                    retrieved = self.store.get(key)
+                    if retrieved != b"":  # Otherwise the key may have been evicted
                         expected = reference.get(key, b"")
                         self.assertEqual(retrieved, expected)
-                 elif op == "remove":
-                     fuzz_record.append(f"{i}: remove {key}")
-                     error_code = self.store.remove(key)
-                     # if remove did not fail due to the key has a lease
-                     if error_code != -706:
+                elif op == "remove":
+                    fuzz_record.append(f"{i}: remove {key}")
+                    error_code = self.store.remove(key)
+                    # if remove did not fail due to the key has a lease
+                    if error_code != -706:
                         reference.pop(key, None)
                         # Also remove from key_values to allow new value if key is reused
                         key_values.pop(key, None)
-         except Exception as e:
-             print(f"Error: {e}")
-             print('\nFuzz record (operations so far):')
-             for record in fuzz_record:
-                 print(record)
-             raise e
-         # Cleanup: ensure all remaining keys are removed
-         time.sleep(default_kv_lease_ttl / 1000)
-         for key in list(reference.keys()):
-             self.store.remove(key)
+        except Exception as e:
+            print(f"Error: {e}")
+            print("\nFuzz record (operations so far):")
+            for record in fuzz_record:
+                print(record)
+            raise e
+        # Cleanup: ensure all remaining keys are removed
+        time.sleep(default_kv_lease_ttl / 1000)
+        for key in list(reference.keys()):
+            self.store.remove(key)
 
     def test_replicate_config_creation_and_properties(self):
         """Test ReplicateConfig class creation and property access."""
@@ -626,16 +1295,16 @@ def test_replicate_config_creation_and_properties(self):
         # Test default constructor
         config = ReplicateConfig()
         self.assertEqual(config.replica_num, 1)
-        self.assertEqual(config.with_soft_pin, False)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.PRESERVE)
         self.assertEqual(config.preferred_segment, "")
 
         # Test property assignment
         config.replica_num = 3
-        config.with_soft_pin = True
+        config.soft_pin_action = SoftPinAction.ENABLE
         config.preferred_segment = "node1:12345"
 
         self.assertEqual(config.replica_num, 3)
-        self.assertEqual(config.with_soft_pin, True)
+        self.assertEqual(config.soft_pin_action, SoftPinAction.ENABLE)
         self.assertEqual(config.preferred_segment, "node1:12345")
 
         # Test string representation
@@ -643,6 +1312,7 @@ def test_replicate_config_creation_and_properties(self):
         self.assertIsInstance(config_str, str)
         self.assertIn("3", config_str)  # Should contain replica_num
 
-if __name__ == '__main__':
+
+if __name__ == "__main__":
     # Show which test is running; stop on first failure
     unittest.main(verbosity=2, failfast=True)
diff --git a/mooncake-wheel/tests/test_mooncake_ep.py b/mooncake-wheel/tests/test_mooncake_ep.py
deleted file mode 100644
index 0dd9630faf..0000000000
--- a/mooncake-wheel/tests/test_mooncake_ep.py
+++ /dev/null
@@ -1,194 +0,0 @@
-import random
-import os
-import torch
-import torch.distributed as dist
-from functools import partial
-
-from mooncake.mooncake_ep_buffer import Buffer
-from ep_test_utils import init_dist, bench, bench_kineto, calc_diff, hash_tensor, per_token_cast_back
-
-_USE_MACA = (
-    os.getenv("MOONCAKE_EP_USE_MACA", "").upper() in {"1", "ON", "TRUE", "YES"}
-    or bool(getattr(torch.version, "maca", None))
-)
-
-
-def test_main(num_tokens: int, hidden: int, num_experts: int, num_topk: int,
-              rank: int, num_ranks: int, group: dist.ProcessGroup, cpu_group: dist.ProcessGroup, buffer: Buffer, seed: int = 0):
-    torch.manual_seed(seed + rank)
-    random.seed(seed + rank)
-
-    assert num_experts % num_ranks == 0
-    num_local_experts = num_experts // num_ranks
-
-    # NOTES: the integers greater than 256 exceeds the BF16 precision limit
-    rank_offset = 128
-    assert num_ranks - rank_offset < 257, 'Too many ranks (exceeding test precision limit)'
-
-    x = torch.ones((num_tokens, hidden), dtype=torch.bfloat16, device='cuda') * (rank - rank_offset)
-    x[:, -128:] = torch.arange(num_tokens, device='cuda').to(torch.bfloat16).view(-1, 1)
-    scores = torch.randn((num_tokens, num_experts), dtype=torch.float32, device='cuda').abs() + 1
-    topk_idx = torch.topk(scores, num_topk, dim=-1, largest=True, sorted=True)[1]
-    topk_weights = torch.randn((num_tokens, num_topk), dtype=torch.float32, device='cuda').abs()
-
-    # Randomly mask some positions
-    for i in range(10):
-        topk_idx[random.randint(0, num_tokens - 1), random.randint(0, num_topk - 1)] = -1
-
-    # Check dispatch correctness
-    do_check = True
-    hash_value, num_times = 0, 0
-    active_ranks = torch.ones((num_tokens, ), dtype=torch.int32, device='cuda')
-    for return_recv_hook in (False, True):
-        for dispatch_use_fp8 in ([False] if _USE_MACA else [False, True]):
-            num_times += 1
-            for i in range((num_times % 2) + 1):
-                packed_recv_x, packed_recv_count, handle, event, hook = \
-                    buffer.dispatch(x, topk_idx, active_ranks, num_tokens, num_experts, -1, use_fp8=dispatch_use_fp8,
-                                    async_finish=not return_recv_hook, return_recv_hook=return_recv_hook)
-                hook() if return_recv_hook else event.current_stream_wait()
-            packed_recv_x = (packed_recv_x[0], packed_recv_x[1].contiguous()) if dispatch_use_fp8 else packed_recv_x
-            simulated_gemm_x = per_token_cast_back(packed_recv_x[0].view(-1, hidden), packed_recv_x[1].view(-1, hidden // 128)).view(packed_recv_x[0].shape) \
-                if dispatch_use_fp8 else packed_recv_x.clone()
-            all_topk_idx = torch.empty((num_ranks, num_tokens, num_topk), dtype=topk_idx.dtype, device='cuda')
-            dist.all_gather_into_tensor(all_topk_idx, topk_idx, group=group)
-            for i in range(num_local_experts if do_check else 0):
-                expert_id = rank * num_local_experts + i
-                recv_x = per_token_cast_back(packed_recv_x[0][i], packed_recv_x[1][i]) if dispatch_use_fp8 else packed_recv_x[i]
-                recv_count, recv_src_info, recv_layout_range = packed_recv_count[i], handle[0][i], handle[1][i]
-
-                # Check expert indices
-                int_mask = (2 ** 32) - 1
-                num_valid_tokens = recv_count.item()
-                assert num_valid_tokens == (recv_layout_range & int_mask).sum().item(), f'{num_valid_tokens} != {recv_layout_range & int_mask}.sum().item()'
-                assert num_valid_tokens == (all_topk_idx == expert_id).sum().item(), f'{num_valid_tokens} != {(all_topk_idx == expert_id).sum().item()}'
-
-                # Check received data
-                recv_x = recv_x[:num_valid_tokens]
-                recv_x_amin = recv_x[:, :-128].amin(dim=-1)
-                recv_src_info = recv_src_info[:num_valid_tokens]
-                assert torch.equal(recv_x_amin, recv_x[:, :-128].amax(dim=-1))
-                assert (recv_x[:, -128:] - recv_src_info.view(-1, 1) % num_tokens).sum().item() == 0
-                for j in range(num_ranks):
-                    begin_idx, count = (recv_layout_range[j] >> 32).item(), (recv_layout_range[j] & int_mask).item()
-                    assert (recv_x_amin == j - rank_offset).sum().item() == (all_topk_idx[j] == expert_id).sum().item()
-                    assert (recv_x[begin_idx:begin_idx + count][:-128] - j).sum().item() == 0
-                if dispatch_use_fp8:
-                    hash_value ^= hash_tensor(packed_recv_x[0][i, :num_valid_tokens])
-                    hash_value ^= hash_tensor(packed_recv_x[1][i, :num_valid_tokens])
-                else:
-                    hash_value ^= hash_tensor(packed_recv_x[i, :num_valid_tokens])
-
-            # Check combine correctness
-            for zero_copy in (False, True):
-                if zero_copy:
-                    buffer.get_next_combine_buffer(handle)[:, :, :] = simulated_gemm_x
-                out = torch.empty((num_tokens, hidden), dtype=torch.bfloat16, device='cuda')
-                combined_x, event, hook = buffer.combine(simulated_gemm_x, topk_idx, topk_weights, active_ranks, -1, handle,
-                                                         async_finish=not return_recv_hook, zero_copy=zero_copy,
-                                                         return_recv_hook=return_recv_hook, out=out)
-                hook() if return_recv_hook else event.current_stream_wait()
-                if do_check:
-                    diff = calc_diff(x * topk_weights.masked_fill(topk_idx == -1, 0).sum(dim=1).view(-1, 1), combined_x)
-                    assert torch.isnan(combined_x).sum().item() == 0
-                    assert diff < 1e-5, f'Error: {diff=}, {zero_copy=}'
-                    hash_value ^= hash_tensor(combined_x)
-
-    # noinspection PyShadowingNames
-    def large_gemm_with_hook(hook):
-        mat_0 = torch.randn((8192, 8192), dtype=torch.float)
-        mat_1 = torch.randn((8192, 8192), dtype=torch.float)
-        mat_0 @ mat_1
-        hook()
-
-    # noinspection PyShadowingNames
-    def test_func(zero_copy: bool, return_recv_hook: bool):
-        recv_x, recv_count, handle, event, hook = \
-            buffer.dispatch(x, topk_idx, active_ranks, num_tokens, num_experts, -1,
-                            async_finish=False, return_recv_hook=return_recv_hook)
-        large_gemm_with_hook(hook) if return_recv_hook else None
-        if zero_copy:
-            buffer.get_next_combine_buffer(handle)[:, :, :] = simulated_gemm_x
-        combined_x, event, hook = buffer.combine(simulated_gemm_x, topk_idx, topk_weights, active_ranks, -1, handle,
-                                                 zero_copy=zero_copy, return_recv_hook=return_recv_hook)
-        large_gemm_with_hook(hook) if return_recv_hook else None
-
-    # Calculate bandwidth
-    num_fp8_bytes, num_bf16_bytes = (hidden + hidden / 128 * 4 + 16), hidden * 2
-    num_dispatch_comm_bytes, num_combine_comm_bytes = 0, 0
-    for i in range(num_tokens):
-        num_selections = (topk_idx[i] != -1).sum().item()
-        num_dispatch_comm_bytes += num_fp8_bytes * num_selections
-        num_combine_comm_bytes += num_bf16_bytes * num_selections
-
-    # Dispatch + combine testing
-    avg_t, min_t, max_t = bench(partial(test_func, zero_copy=False, return_recv_hook=False))
-    print(f'[rank {rank}] Dispatch + combine bandwidth: {(num_dispatch_comm_bytes + num_combine_comm_bytes) / 1e9 / avg_t:.2f} GB/s, '
-          f'avg_t={avg_t * 1e6:.2f} us, min_t={min_t * 1e6:.2f} us, max_t={max_t * 1e6:.2f} us', flush=True)
-
-    # Separate profiling
-    # Skip profiling in fallback mode as kernels are Python functions, not CUDA kernels
-    if not buffer._use_fallback:
-        for return_recv_hook in (False, True):
-            cpu_group.barrier()
-            dispatch_t, combine_t = bench_kineto(partial(test_func, zero_copy=True, return_recv_hook=return_recv_hook),
-                                                 kernel_names=('dispatch', 'combine'), barrier_comm_profiling=True,
-                                                 suppress_kineto_output=True)
-            if not return_recv_hook:
-                # In fallback mode, kernels may not be found (they're Python functions)
-                # So we skip bandwidth calculation if time is 0
-                if dispatch_t > 0 and combine_t > 0:
-                    print(f'[rank {rank}] Dispatch bandwidth: {num_dispatch_comm_bytes / 1e9 / dispatch_t:.2f} GB/s, avg_t={dispatch_t * 1e6:.2f} us | '
-                          f'Combine bandwidth: {num_combine_comm_bytes / 1e9 / combine_t:.2f} GB/s, avg_t={combine_t * 1e6:.2f} us', flush=True)
-                else:
-                    print(f'[rank {rank}] Profiling skipped (kernels not found in CUDA profiler)', flush=True)
-            else:
-                if dispatch_t > 0 and combine_t > 0:
-                    print(f'[rank {rank}] Dispatch send/recv time: {dispatch_t * 2 * 1e6:.2f} us | '
-                          f'Combine send/recv time: {combine_t * 2 * 1e6:.2f} us', flush=True)
-                else:
-                    print(f'[rank {rank}] Profiling skipped (kernels not found in CUDA profiler)', flush=True)
-    else:
-        if rank == 0:
-            print(f'[rank {rank}] Profiling skipped (fallback mode - using Python implementation)', flush=True)
-
-    return hash_value
-
-
-# noinspection PyUnboundLocalVariable
-def test_loop(local_rank: int, num_local_ranks: int):
-    rank, num_ranks, group, cpu_group = init_dist(local_rank, num_local_ranks)
-    num_tokens, hidden, num_topk, num_experts = 128, 7168, 8, 288
-
-    num_ep_buffer_bytes = Buffer.get_ep_buffer_size_hint(num_tokens, hidden, num_ranks, num_experts)
-    if local_rank == 0:
-        print(f'Allocating buffer size: {num_ep_buffer_bytes / 1e6} MB ...', flush=True)
-    buffer = Buffer(group, num_ep_buffer_bytes=num_ep_buffer_bytes)
-    # Mock a broken rank 1 to test effectiveness of EP recovery
-    if local_rank != 1:
-        buffer.update_ep_member()
-    else:
-        buffer = Buffer(group, num_ep_buffer_bytes=num_ep_buffer_bytes)
-
-    test_main(num_tokens, hidden, num_experts, num_topk, rank, num_ranks, group, cpu_group, buffer, seed=1)
-
-    do_pressure_test = False
-    for seed in range(int(1e9) if do_pressure_test else 0):
-        if local_rank == 0:
-            print(f'Testing with seed {seed} ...', flush=True)
-        ref_hash = test_main(num_tokens, hidden, num_experts, num_topk, rank, num_ranks, group, cpu_group, buffer, seed=seed)
-        for i in range(20):
-            assert test_main(num_tokens, hidden, num_experts, num_topk, rank, num_ranks, group, cpu_group, buffer, seed=seed) == ref_hash, f'Error: seed={seed}'
-
-    # Cleanup with error handling (TCPStore warnings are expected in mooncake backend)
-    try:
-        dist.destroy_process_group()
-    except Exception as e:
-        # Ignore cleanup errors (TCPStore connection errors are expected)
-        pass
-
-
-if __name__ == '__main__':
-    # TODO: you may modify NUMA binding for less CPU overhead
-    num_processes = 2
-    torch.multiprocessing.spawn(test_loop, args=(num_processes,), nprocs=num_processes)
diff --git a/mooncake-wheel/tests/test_mooncake_store_service_api.py b/mooncake-wheel/tests/test_mooncake_store_service_api.py
index d5b118c265..f6b49cad9f 100644
--- a/mooncake-wheel/tests/test_mooncake_store_service_api.py
+++ b/mooncake-wheel/tests/test_mooncake_store_service_api.py
@@ -61,6 +61,8 @@ def __init__(self):
         self.unmount_failures = set()
         self.allocated_mount_calls = []
         self.free_unmount_calls = []
+        self.unmount_local_disk_calls = []
+        self.fail_unmount_local_disk = False
         self.setup_calls = []
 
     def setup(self, *args):
@@ -103,12 +105,19 @@ def unmount_and_free_segment(self, segment_ids, grace_period_seconds=0):
         self.free_unmount_calls.append((list(segment_ids), grace_period_seconds))
         return 0
 
+    def unmount_local_disk_segment(self, grace_period_seconds=0):
+        self.unmount_local_disk_calls.append(grace_period_seconds)
+        return -1 if self.fail_unmount_local_disk else 0
+
 
 class FakeRequest:
-    def __init__(self, body):
+    def __init__(self, body, json_error=None):
         self.body = body
+        self.json_error = json_error
 
     async def json(self):
+        if self.json_error is not None:
+            raise self.json_error
         return self.body
 
 
@@ -490,6 +499,82 @@ async def test_unmount_shm_requires_segment_ids(self):
         body = json.loads(resp.text)
         self.assertIn("Missing segment_ids", body["error"])
 
+    # ============= /api/unmount_local_disk tests =============
+
+    async def test_unmount_local_disk_malformed_json_rejected(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest(None, json_error=json.JSONDecodeError("bad", "doc", 0))
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_non_object_body(self):
+        resp = await self.service.handle_unmount_local_disk(FakeRequest([1, 2, 3]))
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_bool_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": True})
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_string_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": "30"})
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_float_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": 1.5})
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_negative_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": -1})
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_rejects_grace_period_above_bound(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": 3601})
+        )
+        self.assertEqual(resp.status, 400)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [])
+
+    async def test_unmount_local_disk_accepts_bound_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": 3600})
+        )
+        self.assertEqual(resp.status, 200)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [3600])
+
+    async def test_unmount_local_disk_defaults_grace_period_to_zero(self):
+        resp = await self.service.handle_unmount_local_disk(FakeRequest({}))
+        self.assertEqual(resp.status, 200)
+        body = json.loads(resp.text)
+        self.assertEqual(body["status"], "success")
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [0])
+
+    async def test_unmount_local_disk_passes_positive_grace_period(self):
+        resp = await self.service.handle_unmount_local_disk(
+            FakeRequest({"grace_period_seconds": 30})
+        )
+        self.assertEqual(resp.status, 200)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [30])
+
+    async def test_unmount_local_disk_store_failure(self):
+        self.fake_store.fail_unmount_local_disk = True
+        resp = await self.service.handle_unmount_local_disk(FakeRequest({}))
+        self.assertEqual(resp.status, 500)
+        self.assertEqual(self.fake_store.unmount_local_disk_calls, [0])
+
     # ==================== /api/put tests ====================
 
     async def test_handle_put_success(self):
diff --git a/mooncake-wheel/tests/test_promotion_on_hit.py b/mooncake-wheel/tests/test_promotion_on_hit.py
index 19efc17722..266c20822d 100644
--- a/mooncake-wheel/tests/test_promotion_on_hit.py
+++ b/mooncake-wheel/tests/test_promotion_on_hit.py
@@ -9,10 +9,13 @@
 Test scenario:
   1. Push enough data to overflow DRAM, so eviction + offload turns warm
      keys into LOCAL_DISK-only objects.
-  2. Identify one such key from the replica descriptors.
+  2. Identify one such key from the replica descriptors (condition-polled,
+     not a fixed sleep).
   3. Read it repeatedly to clear ``promotion_admission_threshold``.
-  4. Wait long enough for one master heartbeat (which queues the task) plus
-     one FileStorage heartbeat (which executes it).
+  4. Poll single-key ``batch_get_replica_desc`` until the key regains a
+     MEMORY replica; each poll re-fires the promotion gate for that key,
+     so the wait is condition-based and self-healing rather than a bet on
+     the heartbeat phase.
   5. Assert the key now also has a MEMORY replica.
 
 Prerequisites:
@@ -22,10 +25,17 @@
       ``--promotion_on_hit=true``
       ``--promotion_admission_threshold=1``  (any positive int; we send
           enough reads to clear up to 4)
+      ``--promotion_max_per_heartbeat=16``  (raise the delivery cap so a
+          burst of admissions from the phase-2 batch query drains within
+          the wait window instead of starving individual keys at the
+          default 1-per-heartbeat)
       ``--root_fs_dir=<dir>``  (so the master tells the client to init
           its FileStorage; without this, no offload heartbeat runs and
           no LOCAL_DISK replicas are ever created)
   - ``MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=<dir>`` set on the client side.
+  - ``MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS=2`` recommended on the
+    client (pins the master/client clock phase; the 10s default makes the
+    wait windows racy against offload draining).
   - ``MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT=10`` and
     ``MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES=10485760`` on the client.
     The default bucket-flush thresholds (500 keys / 256 MB) are too high
@@ -52,8 +62,9 @@
 SEGMENT_SIZE = int(os.getenv("SEGMENT_SIZE_BYTES", str(32 * 1024 * 1024)))
 LOCAL_BUFFER_SIZE = int(os.getenv("LOCAL_BUFFER_SIZE_BYTES", str(64 * 1024 * 1024)))
 
-# Wait window for a full master+client heartbeat round-trip. The default
-# heartbeat interval is 10s on both sides, so 25s is comfortably > 2 ticks.
+# Timeout ceiling for the condition polls below (not a fixed sleep). CI runs
+# the client offload heartbeat at 2s (MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_
+# SECONDS); 25s leaves ample room even at the 10s default interval.
 PROMOTION_WAIT_SECONDS = int(os.getenv("PROMOTION_WAIT_SECONDS", "25"))
 
 
@@ -101,6 +112,28 @@ def _replica_types(descs, key):
     return tags
 
 
+def wait_until(cond, timeout_s, interval=1.0, desc=""):
+    """Poll ``cond()`` (which returns (ok, detail)) until ok or timeout.
+
+    Returns the detail on success; raises AssertionError on timeout with the
+    last observed detail. Polling beats fixed sleeps here for two reasons:
+    the wait adapts to however long the offload/promotion heartbeat actually
+    takes on a loaded CI runner, and — for the promotion waits below — every
+    poll is a single-key ``batch_get_replica_desc``, which re-fires the
+    master's promotion gate for that key (re-admitting it if the task was
+    never queued or was dropped after a transient failure)."""
+    t0 = time.monotonic()
+    while True:
+        ok, detail = cond()
+        if ok:
+            return detail
+        if time.monotonic() - t0 >= timeout_s:
+            raise AssertionError(
+                f"timeout ({timeout_s}s) waiting for {desc}; last={detail}"
+            )
+        time.sleep(interval)
+
+
 class TestPromotionOnHit(unittest.TestCase):
     """Python-binding test for the L2->L1 promotion-on-hit behavioral
     contract."""
@@ -110,6 +143,17 @@ def setUpClass(cls):
         cls.store = MooncakeDistributedStore()
         get_client(cls.store)
 
+    @classmethod
+    def tearDownClass(cls):
+        # Unmount this class's segment from the master. Without this, each
+        # test class's segment stays mounted for the rest of the run,
+        # inflating the master's mem_total_capacity and pushing used_ratio
+        # right onto the eviction high-watermark boundary — the promotion
+        # watermark gate then becomes timing-dependent (flaky).
+        if getattr(cls, "store", None) is not None:
+            cls.store.close()
+            cls.store = None
+
     def test_promotion_after_repeated_hits(self):
         """A LOCAL_DISK-only key must regain a MEMORY replica after
         clearing the admission threshold via repeated reads.
@@ -142,33 +186,37 @@ def test_promotion_after_repeated_hits(self):
                 len(reference), 0, "No PUTs succeeded — cannot run promotion test"
             )
 
-            # Phase 2: wait long enough for offload heartbeat to flush the
-            # evicted keys to LOCAL_DISK.
-            time.sleep(PROMOTION_WAIT_SECONDS)
-
-            descs = self.store.batch_get_replica_desc(list(reference.keys()))
-            type_hist = {}
-            cold_key = None
-            for key in reference.keys():
-                types = _replica_types(descs, key)
-                hist_key = ",".join(sorted(set(types)))
-                type_hist[hist_key] = type_hist.get(hist_key, 0) + 1
-                if (
-                    cold_key is None
-                    and types
-                    and all("MEMORY" not in t for t in types)
-                    and any("LOCAL_DISK" in t for t in types)
-                ):
-                    cold_key = key
-            print(f"replica-type histogram after phase 2: {type_hist}")
-
-            self.assertIsNotNone(
-                cold_key,
-                "No LOCAL_DISK-only key found after eviction — is "
-                "offload_on_evict=true and the segment small enough to "
-                "overflow? master config / SEGMENT_SIZE_BYTES env may need "
-                "tuning. Histogram above shows the actual replica state.",
+            # Phase 2: poll until the offload heartbeat has flushed at least
+            # one evicted key to a LOCAL_DISK-only state (instead of betting
+            # on a fixed sleep matching the heartbeat phase).
+            def _find_cold_key():
+                descs = self.store.batch_get_replica_desc(list(reference.keys()))
+                type_hist = {}
+                found = None
+                for key in reference.keys():
+                    types = _replica_types(descs, key)
+                    hist_key = ",".join(sorted(set(types)))
+                    type_hist[hist_key] = type_hist.get(hist_key, 0) + 1
+                    if (
+                        found is None
+                        and types
+                        and all("MEMORY" not in t for t in types)
+                        and any("LOCAL_DISK" in t for t in types)
+                    ):
+                        found = key
+                return (found is not None), (found, type_hist)
+
+            cold_key, type_hist = wait_until(
+                _find_cold_key,
+                PROMOTION_WAIT_SECONDS,
+                desc=(
+                    "a LOCAL_DISK-only key after eviction — is "
+                    "offload_on_evict=true and the segment small enough to "
+                    "overflow? master config / SEGMENT_SIZE_BYTES env may "
+                    "need tuning"
+                ),
             )
+            print(f"replica-type histogram after phase 2: {type_hist}")
 
             # Phase 3: clear the admission threshold via per-key reads.
             # ``store.get`` goes through ``Client::Query`` → master's
@@ -192,21 +240,28 @@ def test_promotion_after_repeated_hits(self):
                     f"read path is broken — promotion cannot be tested.",
                 )
 
-            # Phase 4: wait for the master to enqueue the promotion task and
-            # for the client's next FileStorage heartbeat to execute it.
-            time.sleep(PROMOTION_WAIT_SECONDS)
-
-            descs_after = self.store.batch_get_replica_desc([cold_key])
-            types_after = _replica_types(descs_after, cold_key)
-            print(f"replica types for {cold_key} after promotion: {types_after}")
-            self.assertTrue(
-                "MEMORY" in types_after,
-                f"Expected a MEMORY replica for {cold_key} after promotion, "
-                f"got types={types_after}. Either promotion_on_hit is not "
-                f"enabled in the master, the admission threshold was not "
-                f"cleared, or the heartbeat tick did not fire within "
-                f"{PROMOTION_WAIT_SECONDS}s.",
+            # Phase 4: poll until the promotion lands. Each poll is a
+            # single-key batch_get_replica_desc, which re-fires the master's
+            # promotion gate for cold_key only — re-admitting it if the task
+            # was never queued or was dropped after a transient failure —
+            # so polling doubles as a self-healing re-trigger rather than a
+            # passive wait.
+            def _promoted():
+                descs = self.store.batch_get_replica_desc([cold_key])
+                types = _replica_types(descs, cold_key)
+                return ("MEMORY" in types), types
+
+            types_after = wait_until(
+                _promoted,
+                PROMOTION_WAIT_SECONDS,
+                desc=(
+                    f"MEMORY replica for {cold_key} after promotion "
+                    f"(check master metrics promotion_admitted / "
+                    f"promotion_rejected_watermark / promotion_completed "
+                    f"and the client's 'ProcessPromotionTasks pulled' log)"
+                ),
             )
+            print(f"replica types for {cold_key} after promotion: {types_after}")
 
             # Phase 5: post-promotion bytes-back AND prove MEMORY was the
             # replica actually served. SelectBestReplica should prefer the
@@ -269,6 +324,17 @@ def setUpClass(cls):
         cls.store = MooncakeDistributedStore()
         get_client(cls.store)
 
+    @classmethod
+    def tearDownClass(cls):
+        # Unmount this class's segment from the master. Without this, each
+        # test class's segment stays mounted for the rest of the run,
+        # inflating the master's mem_total_capacity and pushing used_ratio
+        # right onto the eviction high-watermark boundary — the promotion
+        # watermark gate then becomes timing-dependent (flaky).
+        if getattr(cls, "store", None) is not None:
+            cls.store.close()
+            cls.store = None
+
     def test_below_watermark_workload_stays_memory_only(self):
         VALUE_SIZE = 1024  # 1 KB
         NUM_KEYS = 16  # 16 KB total, well below the 32 MB segment
@@ -346,6 +412,17 @@ def setUpClass(cls):
         cls.store = MooncakeDistributedStore()
         get_client(cls.store)
 
+    @classmethod
+    def tearDownClass(cls):
+        # Unmount this class's segment from the master. Without this, each
+        # test class's segment stays mounted for the rest of the run,
+        # inflating the master's mem_total_capacity and pushing used_ratio
+        # right onto the eviction high-watermark boundary — the promotion
+        # watermark gate then becomes timing-dependent (flaky).
+        if getattr(cls, "store", None) is not None:
+            cls.store.close()
+            cls.store = None
+
     def test_latency_comparison(self):
         VALUE_SIZE = 1024 * 1024  # 1 MB
         NUM_KEYS = 96
@@ -364,18 +441,27 @@ def test_latency_comparison(self):
 
             time.sleep(PROMOTION_WAIT_SECONDS)
 
-            descs = self.store.batch_get_replica_desc(list(reference.keys()))
-            cold_key = None
-            for key in reference.keys():
-                types = _replica_types(descs, key)
-                if (
-                    cold_key is None
-                    and types
-                    and all("MEMORY" not in t for t in types)
-                    and any("LOCAL_DISK" in t for t in types)
-                ):
-                    cold_key = key
-            self.assertIsNotNone(cold_key, "no LOCAL_DISK-only key after eviction")
+            def _find_cold_key():
+                descs = self.store.batch_get_replica_desc(list(reference.keys()))
+                found = None
+                for key in reference.keys():
+                    types = _replica_types(descs, key)
+                    if (
+                        found is None
+                        and types
+                        and all("MEMORY" not in t for t in types)
+                        and any("LOCAL_DISK" in t for t in types)
+                    ):
+                        found = key
+                return (found is not None), found
+
+            # Keep the initial fixed wait (the pre-promotion read loop below
+            # wants a quiet system), then poll for the cold key.
+            cold_key = wait_until(
+                _find_cold_key,
+                PROMOTION_WAIT_SECONDS,
+                desc="no LOCAL_DISK-only key after eviction",
+            )
 
             # Pre-promotion: timed LOCAL_DISK reads, bail when a read
             # serves from MEMORY (= worker raced the loop).
@@ -406,11 +492,18 @@ def test_latency_comparison(self):
                 "lower LATENCY_SAMPLES.",
             )
 
-            # Wait for promotion to complete.
-            time.sleep(PROMOTION_WAIT_SECONDS)
-            descs_after = self.store.batch_get_replica_desc([cold_key])
-            types_after = _replica_types(descs_after, cold_key)
-            self.assertIn("MEMORY", types_after)
+            # Wait for promotion to complete (poll; each poll re-fires the
+            # promotion gate for cold_key, doubling as a re-trigger).
+            def _promoted():
+                descs_after = self.store.batch_get_replica_desc([cold_key])
+                types_after = _replica_types(descs_after, cold_key)
+                return ("MEMORY" in types_after), types_after
+
+            wait_until(
+                _promoted,
+                PROMOTION_WAIT_SECONDS,
+                desc=f"MEMORY replica for {cold_key} after promotion",
+            )
 
             # Post-promotion: timed MEMORY reads; the counter must stay
             # put (otherwise at least one read still hit LOCAL_DISK).
diff --git a/mooncake-wheel/tests/test_put_get_tensor.py b/mooncake-wheel/tests/test_put_get_tensor.py
index edf8d8c8c9..b619cff4fa 100644
--- a/mooncake-wheel/tests/test_put_get_tensor.py
+++ b/mooncake-wheel/tests/test_put_get_tensor.py
@@ -10,36 +10,43 @@
     _torch = None
 
 from mooncake.store import MooncakeDistributedStore
+from mooncake.structured_object_store import (
+    MISSING,
+    _choose_leaf_codec,
+    _escape_key,
+    infer_structure,
+)
 
 # The lease time of the kv object, should be set equal to
 # the master's value.
-DEFAULT_DEFAULT_KV_LEASE_TTL = 5000 # 5000 milliseconds
+DEFAULT_DEFAULT_KV_LEASE_TTL = 5000  # 5000 milliseconds
 # Use environment variable if set, otherwise use default
-default_kv_lease_ttl = int(os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL))
+default_kv_lease_ttl = int(
+    os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL)
+)
+
 
 def cuda_available():
     return _torch is not None and _torch.cuda.is_available()
 
+
 # Define a test class for serialization
 class TestClass:
     def __init__(self, version=1, shape=(1, 2, 3)):
         self.version = version
         self.shape = shape
-    
-    def serialize_into(self, buffer):
-        struct.pack_into("i", buffer, 0, self.version)
-        struct.pack_into("3i", buffer, 4, *self.shape)
-        
+
     def serialize_into(self):
         version_bytes = struct.pack("i", self.version)
         shape_bytes = struct.pack("3i", *self.shape)
         return (version_bytes, shape_bytes)
-        
+
     def deserialize_from(buffer):
         version = struct.unpack_from("i", buffer, 0)[0]
         shape = struct.unpack_from("3i", buffer, 4)
         return TestClass(version, shape)
-         
+
+
 def get_client(store):
     """Initialize and setup the distributed store client."""
     protocol = os.getenv("PROTOCOL", "tcp")
@@ -47,19 +54,19 @@ def get_client(store):
     local_hostname = os.getenv("LOCAL_HOSTNAME", "localhost")
     metadata_server = os.getenv("MC_METADATA_SERVER", "127.0.0.1:2379")
     global_segment_size = 3200 * 1024 * 1024  # 3200 MB
-    local_buffer_size = 512 * 1024 * 1024     # 512 MB
+    local_buffer_size = 512 * 1024 * 1024  # 512 MB
     master_server_address = os.getenv("MASTER_SERVER", "127.0.0.1:50051")
-    
+
     retcode = store.setup(
-        local_hostname, 
-        metadata_server, 
+        local_hostname,
+        metadata_server,
         global_segment_size,
-        local_buffer_size, 
-        protocol, 
+        local_buffer_size,
+        protocol,
         device_name,
-        master_server_address
+        master_server_address,
     )
-    
+
     if retcode:
         raise RuntimeError(f"Failed to setup store client. Return code: {retcode}")
 
@@ -87,7 +94,7 @@ def test_put_get_tensor(self):
         self.assertTrue(torch.allclose(tensor, retrieved))
 
         # Int tensor
-        tensor_int = torch.tensor([1,2,3,4], dtype=torch.int32)
+        tensor_int = torch.tensor([1, 2, 3, 4], dtype=torch.int32)
         key_int = "test_tensor_int"
         result = self.store.put_tensor(key_int, tensor_int)
         self.assertEqual(result, 0)
@@ -126,6 +133,32 @@ def test_put_get_tensor(self):
         self.store.remove(key_bool)
         self.store.remove(key_rand)
 
+    def test_batch_tensor_default_config(self):
+        import torch
+
+        prefix = f"test_batch_tensor_default_{os.getpid()}"
+        keys = [f"{prefix}_{i}" for i in range(2)]
+        tensors = [
+            torch.arange(16, dtype=torch.float32).reshape(4, 4),
+            torch.arange(24, dtype=torch.int64).reshape(2, 3, 4),
+        ]
+        self.assertEqual(self.store.batch_put_tensor(keys, tensors), [0, 0])
+        for key, tensor in zip(keys, tensors):
+            self.assertTrue(torch.equal(self.store.get_tensor(key), tensor))
+            self.store.remove(key)
+
+        upsert_keys = [f"{prefix}_upsert_{i}" for i in range(2)]
+        upsert_tensors = [
+            torch.arange(8, dtype=torch.float32),
+            torch.arange(12, dtype=torch.int32),
+        ]
+        self.assertEqual(
+            self.store.batch_upsert_tensor(upsert_keys, upsert_tensors), [0, 0]
+        )
+        for key, tensor in zip(upsert_keys, upsert_tensors):
+            self.assertTrue(torch.equal(self.store.get_tensor(key), tensor))
+            self.store.remove(key)
+
     @unittest.skipUnless(cuda_available(), "CUDA is not available")
     def test_cuda_local_copy_paths(self):
         """Test CUDA source writes and CUDA destination reads."""
@@ -137,19 +170,87 @@ def test_cuda_local_copy_paths(self):
         raw_key = f"{prefix}_raw"
 
         tensor = torch.arange(16, dtype=torch.float32, device="cuda")
+        torch.cuda.synchronize()
         self.assertEqual(self.store.put_tensor(put_key, tensor), 0)
         self.assertEqual(self.store.upsert_tensor(upsert_key, tensor), 0)
+        self.assertTrue(torch.equal(self.store.get_tensor(put_key), tensor.cpu()))
+        self.assertTrue(torch.equal(self.store.get_tensor(upsert_key), tensor.cpu()))
+
+        # RealClient writes directly to a registered CUDA destination.
+        cuda_destination = torch.empty_like(tensor)
+        destination_bytes = tensor.numel() * tensor.element_size()
+        self.assertEqual(
+            self.store.register_buffer(cuda_destination.data_ptr(), destination_bytes),
+            0,
+        )
+        try:
+            self.assertEqual(
+                self.store.get_tensor_into_cuda(put_key, cuda_destination),
+                destination_bytes,
+            )
+            torch.cuda.synchronize()
+            self.assertTrue(torch.equal(cuda_destination, tensor))
+        finally:
+            self.store.unregister_buffer(cuda_destination.data_ptr())
+
+        batch_put_keys = [f"{prefix}_batch_put_{i}" for i in range(2)]
+        batch_upsert_keys = [f"{prefix}_batch_upsert_{i}" for i in range(2)]
+        batch_tensors = [
+            torch.arange(16, dtype=torch.float32, device="cuda").reshape(4, 4),
+            torch.arange(24, dtype=torch.int64, device="cuda").reshape(2, 3, 4),
+        ]
+        torch.cuda.synchronize()
+        self.assertEqual(
+            self.store.batch_put_tensor(batch_put_keys, batch_tensors), [0, 0]
+        )
+        self.assertEqual(
+            self.store.batch_upsert_tensor(batch_upsert_keys, batch_tensors),
+            [0, 0],
+        )
+        batch_destinations = [torch.empty_like(value) for value in batch_tensors]
+        destination_bytes = [
+            value.numel() * value.element_size() for value in batch_tensors
+        ]
+        for destination, size in zip(batch_destinations, destination_bytes):
+            self.assertEqual(
+                self.store.register_buffer(destination.data_ptr(), size), 0
+            )
+        try:
+            self.assertEqual(
+                self.store.batch_get_tensor_into_cuda(
+                    batch_put_keys, batch_destinations
+                ),
+                destination_bytes,
+            )
+            torch.cuda.synchronize()
+            for destination, expected in zip(batch_destinations, batch_tensors):
+                self.assertTrue(torch.equal(destination, expected))
+        finally:
+            for destination in batch_destinations:
+                self.store.unregister_buffer(destination.data_ptr())
+        for key, expected_tensor in zip(batch_put_keys, batch_tensors):
+            self.assertTrue(
+                torch.equal(self.store.get_tensor(key), expected_tensor.cpu())
+            )
+        for key, expected_tensor in zip(batch_upsert_keys, batch_tensors):
+            self.assertTrue(
+                torch.equal(self.store.get_tensor(key), expected_tensor.cpu())
+            )
 
         raw = bytes(range(32))
         self.assertEqual(self.store.put(raw_key, raw), 0)
 
         dst = torch.empty(len(raw), dtype=torch.uint8, device="cuda")
-        self.assertEqual(self.store.get_into(raw_key, dst.data_ptr(), len(raw)), len(raw))
+        self.assertEqual(
+            self.store.get_into(raw_key, dst.data_ptr(), len(raw)), len(raw)
+        )
         expected = torch.tensor(list(raw), dtype=torch.uint8, device="cuda")
         self.assertTrue(torch.equal(dst, expected))
 
         self.store.remove(put_key)
         self.store.remove(upsert_key)
+        for key in batch_put_keys + batch_upsert_keys:
+            self.store.remove(key)
         self.store.remove(raw_key)
 
     def test_put_get_tensor_with_metadata(self):
@@ -169,9 +270,11 @@ def test_put_get_tensor_with_metadata(self):
         self.assertTrue(torch.allclose(tensor_2d, retrieved_tensor))
 
         # Test with 3D int tensor
-        tensor_3d = torch.tensor([[[1, 2], [3, 4]], [[5, 6], [7, 8]]], dtype=torch.int64)
+        tensor_3d = torch.tensor(
+            [[[1, 2], [3, 4]], [[5, 6], [7, 8]]], dtype=torch.int64
+        )
         key_3d = "test_tensor_with_metadata_3d"
-        
+
         result = self.store.put_tensor(key_3d, tensor_3d)
         self.assertEqual(result, 0)
 
@@ -185,7 +288,6 @@ def test_put_get_tensor_with_metadata(self):
         self.store.remove(key_2d)
         self.store.remove(key_3d)
 
-             
     def _assert_empty_tensor_equal(self, expected, actual):
         import torch
 
@@ -239,7 +341,9 @@ def test_zero_tensor_into_and_from(self):
             retrieved = self.store.get_tensor_into(key, buffer_ptr, buffer_size)
             self._assert_empty_tensor_equal(tensor, retrieved)
 
-            self.assertEqual(self.store.put_tensor_from(key_from, buffer_ptr, total_length), 0)
+            self.assertEqual(
+                self.store.put_tensor_from(key_from, buffer_ptr, total_length), 0
+            )
             self._assert_empty_tensor_equal(tensor, self.store.get_tensor(key_from))
         finally:
             self.store.unregister_buffer(buffer_ptr)
@@ -256,7 +360,9 @@ def test_zero_tensor_with_tp(self):
         split_dim = 0
 
         self.assertEqual(
-            self.store.put_tensor_with_tp(key, tensor, tp_size=tp_size, split_dim=split_dim),
+            self.store.put_tensor_with_tp(
+                key, tensor, tp_size=tp_size, split_dim=split_dim
+            ),
             0,
         )
         for rank in range(tp_size):
@@ -268,30 +374,29 @@ def test_zero_tensor_with_tp(self):
             self.store.remove(f"{key}_tp_{rank}")
 
 
-from mooncake.structured_object_store import (
-    MISSING,
-    _choose_leaf_codec,
-    _escape_key,
-    infer_structure,
-)
-
-
 class TestCodecInference(unittest.TestCase):
-
     def test_tensor(self):
         import torch
+
         d = _choose_leaf_codec([torch.tensor([1, 2]), torch.tensor([3])])
         self.assertTrue(d.accepted)
         self.assertEqual(d.codec, "ragged_tensor")
 
     def test_tensor_mixed_dtype(self):
         import torch
-        d = _choose_leaf_codec([torch.tensor([1], dtype=torch.float32), torch.tensor([1], dtype=torch.int64)])
+
+        d = _choose_leaf_codec(
+            [
+                torch.tensor([1], dtype=torch.float32),
+                torch.tensor([1], dtype=torch.int64),
+            ]
+        )
         self.assertFalse(d.accepted)
         self.assertEqual(d.codec, "ragged_tensor")
 
     def test_tensor_mixed_ndim(self):
         import torch
+
         d = _choose_leaf_codec([torch.tensor([1]), torch.tensor([[1, 2]])])
         self.assertTrue(d.accepted)
         self.assertEqual(d.codec, "ragged_tensor")
@@ -459,5 +564,5 @@ def test_depth_limit(self):
             infer_structure("r", [deep, deep], [], [])
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     unittest.main()
diff --git a/mooncake-wheel/tests/test_replicated_distributed_object_store.py b/mooncake-wheel/tests/test_replicated_distributed_object_store.py
index 0ad91d3e6a..d4922a0d97 100644
--- a/mooncake-wheel/tests/test_replicated_distributed_object_store.py
+++ b/mooncake-wheel/tests/test_replicated_distributed_object_store.py
@@ -1,7 +1,7 @@
 import unittest
 import os
 import time
-from mooncake.store import MooncakeDistributedStore, ReplicateConfig
+from mooncake.store import MooncakeDistributedStore, ReplicateConfig, SoftPinAction
 
 # The lease time of the kv object, should be set equal to
 # the master's value.
@@ -173,7 +173,7 @@ def test_put_from_with_config_parameter(self):
         # Test with custom config
         config = ReplicateConfig()
         config.replica_num = self.max_replicate_num
-        config.with_soft_pin = False
+        config.soft_pin_action = SoftPinAction.PRESERVE
         config.with_hard_pin = False
         
         key2 = "test_put_from_config_key2"
@@ -244,7 +244,7 @@ def test_batch_put_from_with_config_parameter(self):
         # Test with custom config
         config = ReplicateConfig()
         config.replica_num = self.max_replicate_num
-        config.with_soft_pin = False
+        config.soft_pin_action = SoftPinAction.PRESERVE
         config.with_hard_pin = False
 
         keys2 = ["test_batch_put_from_config_key4", "test_batch_put_from_config_key5", "test_batch_put_from_config_key6"]
diff --git a/mooncake-wheel/tests/test_ssd_offload_in_evict.py b/mooncake-wheel/tests/test_ssd_offload_in_evict.py
index cc85c7ab90..ecea2ab54e 100644
--- a/mooncake-wheel/tests/test_ssd_offload_in_evict.py
+++ b/mooncake-wheel/tests/test_ssd_offload_in_evict.py
@@ -7,15 +7,21 @@
 
 # The lease time of the kv object, should be set equal to
 # the master's value.
-DEFAULT_DEFAULT_KV_LEASE_TTL = 5000 # 5000 milliseconds
+DEFAULT_DEFAULT_KV_LEASE_TTL = 5000  # 5000 milliseconds
 # Use environment variable if set, otherwise use default
-default_kv_lease_ttl = int(os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL))
-ADD_OPERATION_COUNT_ONE = 1 
-ADD_OPERATION_COUNT_ZERO = 0   
-NO_ADD_LATENCY = 0              
-NO_ADD_DATA_SIZE = 0            
+default_kv_lease_ttl = int(
+    os.getenv("DEFAULT_KV_LEASE_TTL", DEFAULT_DEFAULT_KV_LEASE_TTL)
+)
+ADD_OPERATION_COUNT_ONE = 1
+ADD_OPERATION_COUNT_ZERO = 0
+NO_ADD_LATENCY = 0
+NO_ADD_DATA_SIZE = 0
+PUT_RETRY_TIMEOUT_SECONDS = 120
+CLEANUP_RETRY_TIMEOUT_SECONDS = 30
+RETRYABLE_REMOVE_RESULTS = {-703, -706, -708}
 
-# This test need to set the environment valid client storage root path. 
+
+# This test need to set the environment valid client storage root path.
 # Put data is more than segment size,so some data will be eviced ,and get from local file later
 def get_client(store):
     """Initialize and setup the distributed store client."""
@@ -23,29 +29,31 @@ def get_client(store):
     device_name = os.getenv("DEVICE_NAME", "eth0")
     local_hostname = os.getenv("LOCAL_HOSTNAME", "localhost")
     metadata_server = os.getenv("MC_METADATA_SERVER", "127.0.0.1:2379")
-    global_segment_size = 512 * 1024 * 1024   # 512 MB
-    local_buffer_size = 512 * 1024 * 1024     # 512 MB
+    global_segment_size = 512 * 1024 * 1024  # 512 MB
+    local_buffer_size = 512 * 1024 * 1024  # 512 MB
     master_server_address = os.getenv("MASTER_SERVER", "127.0.0.1:50051")
-    
+
     retcode = store.setup(
-        local_hostname, 
-        metadata_server, 
+        local_hostname,
+        metadata_server,
         global_segment_size,
-        local_buffer_size, 
-        protocol, 
+        local_buffer_size,
+        protocol,
         device_name,
-        master_server_address
+        master_server_address,
     )
-    
+
     if retcode:
         raise RuntimeError(f"Failed to setup store client. Return code: {retcode}")
 
+
 class TestStats:
     """Helper class for collecting and reporting test statistics."""
+
     def __init__(self, test_name):
         self.test_name = test_name
         self.reset()
-        
+
     def reset(self):
         self.start_time = 0
         self.end_time = 0
@@ -55,13 +63,13 @@ def reset(self):
         self.latencies = []
         self.error_codes = defaultdict(int)
         self.data_transferred = 0
-        
+
     def start_timer(self):
         self.start_time = time.perf_counter()
-        
+
     def stop_timer(self):
         self.end_time = time.perf_counter()
-        
+
     def get_duration(self):
         return self.end_time - self.start_time if self.end_time > self.start_time else 0
 
@@ -71,24 +79,23 @@ def combine(self, other):
         self.operation_count += other.operation_count
         self.success_count += other.success_count
         self.failure_count += other.failure_count
-        
+
         # Merge latency data
         self.latencies.extend(other.latencies)
-        
+
         # Merge error codes
         for code, count in other.error_codes.items():
             self.error_codes[code] += count
-        
+
         # Merge data volume
         self.data_transferred += other.data_transferred
-        
+
         # Merge thread duration (used for computing concurrency efficiency)
-        if hasattr(other, 'thread_duration'):
-            if not hasattr(self, 'thread_duration'):
+        if hasattr(other, "thread_duration"):
+            if not hasattr(self, "thread_duration"):
                 self.thread_duration = 0
             self.thread_duration = max(self.thread_duration, other.thread_duration)
 
-        
     def record_operation(self, success, num, latency, data_size=0, error_code=None):
         self.operation_count += num
         if success:
@@ -109,7 +116,7 @@ def record_throughput(self, total_ops, total_data, duration):
         self.duration = duration
         self.ops_per_sec = total_ops / duration if duration > 0 else 0
         self.mb_per_sec = total_data / duration / (1024 * 1024) if duration > 0 else 0
-        
+
     def print_throughput(self, thread_put_stats, thread_get_stats):
         """Print throughput statistics"""
         # Calculate PUT concurrency efficiency
@@ -117,10 +124,10 @@ def print_throughput(self, thread_put_stats, thread_get_stats):
             # Calculate average thread time
             total_put_time = sum(s.thread_duration for s in thread_put_stats)
             avg_put_time = total_put_time / len(thread_put_stats)
-            
+
             # Calculate slowest thread time
             max_put_time = max(s.thread_duration for s in thread_put_stats)
-            
+
             # Calculate concurrency efficiency (using average time)
             put_efficiency = total_put_time / avg_put_time if avg_put_time > 0 else 0
         else:
@@ -133,20 +140,24 @@ def print_throughput(self, thread_put_stats, thread_get_stats):
             # Calculate average thread time
             total_get_time = sum(s.thread_duration for s in thread_get_stats)
             avg_get_time = total_get_time / len(thread_get_stats)
-            
+
             # Calculate slowest thread time
             max_get_time = max(s.thread_duration for s in thread_get_stats)
-            
+
             # Calculate concurrency efficiency (using average time)
             get_efficiency = total_get_time / avg_get_time if avg_get_time > 0 else 0
         else:
             avg_get_time = 0
             max_get_time = 0
             get_efficiency = 0
-            
+
         print(f"\n=== {self.test_name} STATISTICS ===")
-        print(f"Concurrent Throughput: {self.ops_per_sec:.2f} ops/sec, {self.mb_per_sec:.2f} MB/s")
-        print(f"Total Operations: {self.total_ops}, Duration: {self.duration:.2f} seconds")
+        print(
+            f"Concurrent Throughput: {self.ops_per_sec:.2f} ops/sec, {self.mb_per_sec:.2f} MB/s"
+        )
+        print(
+            f"Total Operations: {self.total_ops}, Duration: {self.duration:.2f} seconds"
+        )
 
         print(f"Put Concurrency Efficiency: {put_efficiency*100:.2f}%")
         print(f"  • Average Thread Time: {avg_put_time:.4f}s")
@@ -157,40 +168,59 @@ def print_throughput(self, thread_put_stats, thread_get_stats):
         print(f"  • Average Thread Time: {avg_get_time:.4f}s")
         print(f"  • Slowest Thread Time: {max_get_time:.4f}s")
         print(f"  • Efficiency Ratio: {avg_get_time/max_get_time:.2f}")
-            
+
     def print_stats(self):
         """Print comprehensive statistics for the test."""
         duration = self.get_duration()
-        success_rate = (self.success_count / self.operation_count * 100) if self.operation_count > 0 else 0
-        
+        success_rate = (
+            (self.success_count / self.operation_count * 100)
+            if self.operation_count > 0
+            else 0
+        )
+
         # Calculate latency statistics
         min_latency = min(self.latencies) * 1000 if self.latencies else 0
         max_latency = max(self.latencies) * 1000 if self.latencies else 0
-        avg_latency = (sum(self.latencies) / len(self.latencies) * 1000) if self.latencies else 0
-        
+        avg_latency = (
+            (sum(self.latencies) / len(self.latencies) * 1000) if self.latencies else 0
+        )
+
         # Calculate percentiles
         p90 = p99 = p999 = 0
         if self.latencies:
             sorted_latencies = sorted(self.latencies)
             p90 = sorted_latencies[int(len(sorted_latencies) * 0.9)] * 1000
-            p99 = sorted_latencies[int(len(sorted_latencies) * 0.99)] * 1000 if len(sorted_latencies) > 100 else p90
-            p999 = sorted_latencies[int(len(sorted_latencies) * 0.999)] * 1000 if len(sorted_latencies) > 1000 else p99
-        
+            p99 = (
+                sorted_latencies[int(len(sorted_latencies) * 0.99)] * 1000
+                if len(sorted_latencies) > 100
+                else p90
+            )
+            p999 = (
+                sorted_latencies[int(len(sorted_latencies) * 0.999)] * 1000
+                if len(sorted_latencies) > 1000
+                else p99
+            )
+
         print(f"\n=== {self.test_name} STATISTICS ===")
-        print(f"Operations: {self.operation_count} (Success: {self.success_count}, Failure: {self.failure_count})")
+        print(
+            f"Operations: {self.operation_count} (Success: {self.success_count}, Failure: {self.failure_count})"
+        )
         print(f"Success Rate: {success_rate:.2f}%")
         print(f"Duration: {duration:.2f} seconds")
         print(f"Data Transferred: {self.data_transferred / (1024 * 1024):.2f} MB")
-        print(f"Latency (ms): Min={min_latency:.2f}, Max={max_latency:.2f}, Avg={avg_latency:.2f}")
+        print(
+            f"Latency (ms): Min={min_latency:.2f}, Max={max_latency:.2f}, Avg={avg_latency:.2f}"
+        )
         print(f"Percentiles (ms): P90={p90:.2f}, P99={p99:.2f}, P999={p999:.2f}")
-        
+
         if self.error_codes:
             print("Error Codes:")
             for code, count in self.error_codes.items():
                 print(f"  Code {code}: {count} times")
-        
+
         print("=" * 50)
-    
+
+
 class TestDistributedObjectStore(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
@@ -200,15 +230,16 @@ def setUpClass(cls):
 
     def test_put_get_in_evict_operations(self):
         """Test basic Put/Get operations with eviction scenario
-        
+
         Verifies:
         1. Data eviction to file when exceeding memory capacity
         2. Correct retrieval of evicted data
-        """ 
-        VALUE_SIZE = 1024 * 1024 
+        """
+        VALUE_SIZE = 1024 * 1024
         MAX_REQUESTS = 1000
+        KEY_PREFIX = "put_get_k_"
         reference = {}
-        
+
         # Initialize statistics
         put_stats = TestStats("Put Operations")
         get_stats = TestStats("Get Operations")
@@ -219,80 +250,99 @@ def test_put_get_in_evict_operations(self):
         put_stats.start_timer()
         index = 0
         while index < MAX_REQUESTS:
-            key = "k_" + str(index)
+            key = KEY_PREFIX + str(index)
             value = os.urandom(VALUE_SIZE)
-            
+
             # Record operation start time
             op_start = time.perf_counter()
             retcode = self.store.put(key, value)
             op_end = time.perf_counter()
             latency = op_end - op_start
-            
+
             if retcode == -200:
                 # The space is not enough, continue to next operation
-                put_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode)
+                put_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode
+                )
                 continue
             elif retcode == 0:
                 reference[key] = value
-                put_stats.record_operation(True, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE)
+                put_stats.record_operation(
+                    True, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE
+                )
             else:
-                put_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode)
-                raise RuntimeError(f"Put operation failed for key {key}. Error code: {retcode}")
-            
+                put_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode
+                )
+                raise RuntimeError(
+                    f"Put operation failed for key {key}. Error code: {retcode}"
+                )
+
             index = index + 1
             if index % 500 == 0:
                 print("completed", index, "entries")
-        
+
         put_stats.stop_timer()
         time.sleep(5)
 
-
         # --------------------------
         # Phase 2: Data verification
         # --------------------------
         get_stats.start_timer()
+        failed_keys = []
         index = 0
         while index < MAX_REQUESTS:
-            key = "k_" + str(index)
-            
+            key = KEY_PREFIX + str(index)
+
             op_start = time.perf_counter()
             retrieved = self.store.get(key)
             op_end = time.perf_counter()
             latency = op_end - op_start
-            
+
             if len(retrieved) != 0:
                 expected = reference.get(key)
-                success = (retrieved == expected)
-                get_stats.record_operation(success, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE)
+                success = retrieved == expected
+                get_stats.record_operation(
+                    success, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE
+                )
                 if not success:
+                    failed_keys.append(key)
                     print(f"Data mismatch for key: {key}")
             else:
-                get_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, -1)
-            
+                failed_keys.append(key)
+                get_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, -1
+                )
+
             index = index + 1
             if index % 500 == 0:
                 print("completed", index, "entries")
-        
+
         get_stats.stop_timer()
-        
+
         # Print statistics
         put_stats.print_stats()
         get_stats.print_stats()
-            
+
         # --------------------------
         # Phase 3: Cleanup
         # --------------------------
         time.sleep(default_kv_lease_ttl / 1000)
         index = 0
         while index < MAX_REQUESTS:
-            key = "k_" + str(index)
+            key = KEY_PREFIX + str(index)
             self.store.remove(key)
             index = index + 1
-        print("Cleanup completed")  
+        print("Cleanup completed")
+        self.assertEqual(
+            get_stats.failure_count,
+            0,
+            f"{get_stats.failure_count} read(s) failed; first failed keys: {failed_keys[:10]}",
+        )
 
     def test_concurrent_stress(self):
         """Multi-threaded stress test for Put/Get operations
-        
+
         Verifies:
         1. Correctness under concurrent access
         2. Thread safety
@@ -300,137 +350,229 @@ def test_concurrent_stress(self):
         NUM_THREADS = 4
         VALUE_SIZE = 1024 * 1024
         OPERATIONS_PER_THREAD = 1000
+        KEY_PREFIX = "concurrent_k_"
 
         thread_exceptions = []
         references = {}
-        
+        # Track keys that were successfully written by any thread. Concurrent puts
+        # to the same keys can fail with -200 (NO_AVAILABLE_HANDLE) at this segment
+        # size, so the GET phase only asserts on keys that were actually written.
+        successful_puts = set()
+        successful_puts_lock = threading.Lock()
+
         # Create independent PUT and GET statistics objects
         put_stats = TestStats("Concurrent Put Operations")
         get_stats = TestStats("Concurrent Get Operations")
-        
+
         # Create thread-level statistics objects
         thread_put_stats = [TestStats(f"Thread-{i}-Put") for i in range(NUM_THREADS)]
         thread_get_stats = [TestStats(f"Thread-{i}-Get") for i in range(NUM_THREADS)]
-        
+        put_get_barrier = threading.Barrier(NUM_THREADS)
+
         index = 0
         while index < OPERATIONS_PER_THREAD:
-            key = "k_" + str(index)
+            key = KEY_PREFIX + str(index)
             value = os.urandom(VALUE_SIZE)
             references[key] = value
             index = index + 1
-        
+
         def worker(thread_id, put_stats, get_stats):
             try:
-                print(f"Thread {thread_id} started") 
-                
+                print(f"Thread {thread_id} started")
+
                 # PUT operation phase
                 put_start = time.perf_counter()
                 index = 0
+                retry_start = None
+                retry_count = 0
                 while index < OPERATIONS_PER_THREAD:
-                    key = "k_" + str(index)
+                    key = KEY_PREFIX + str(index)
                     test_data = references[key]
-                    
+
                     op_start = time.perf_counter()
                     result = self.store.put(key, test_data)
                     op_end = time.perf_counter()
                     latency = op_end - op_start
-                    success = (result == 0)
-                    put_stats.record_operation(success, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, result if not success else None)
+                    if result == -200:
+                        # Memory pressure can temporarily prevent a new
+                        # replica from starting while eviction is in flight.
+                        # Retry this logical PUT before reading the key.
+                        if retry_start is None:
+                            retry_start = time.monotonic()
+                        retry_count += 1
+                        if time.monotonic() - retry_start >= PUT_RETRY_TIMEOUT_SECONDS:
+                            raise RuntimeError(
+                                f"Put operation did not make progress for key "
+                                f"{key} after {retry_count} retries and "
+                                f"{PUT_RETRY_TIMEOUT_SECONDS}s"
+                            )
+                        put_stats.record_operation(
+                            False,
+                            ADD_OPERATION_COUNT_ONE,
+                            latency,
+                            VALUE_SIZE,
+                            result,
+                        )
+                        time.sleep(0.01)
+                        continue
+                    if result != 0:
+                        raise RuntimeError(
+                            f"Put operation failed for key {key}: {result}"
+                        )
+                    retry_start = None
+                    retry_count = 0
+                    with successful_puts_lock:
+                        successful_puts.add(key)
+                    put_stats.record_operation(
+                        True, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE
+                    )
                     index = index + 1
                 put_end = time.perf_counter()
-                put_stats.thread_duration = put_end - put_start  # Record thread PUT duration
-                
+                put_stats.thread_duration = (
+                    put_end - put_start
+                )  # Record thread PUT duration
+
+                # Keep the concurrent PUT and GET phases separate so reads do not
+                # race with writes that are still being committed by another thread.
+                put_get_barrier.wait()
+                time.sleep(5)
+
                 # GET operation phase
                 get_start = time.perf_counter()
                 index = 0
                 while index < OPERATIONS_PER_THREAD:
-                    key = "k_" + str(index)
-                    
+                    key = KEY_PREFIX + str(index)
+
                     op_start = time.perf_counter()
                     retrieved_data = self.store.get(key)
                     op_end = time.perf_counter()
                     latency = op_end - op_start
+                    with successful_puts_lock:
+                        key_was_written = key in successful_puts
+                    if not key_was_written:
+                        # This key was never written by any thread (-200 puts are
+                        # expected at this segment size), so an empty read here is
+                        # expected and not a test failure.
+                        index = index + 1
+                        continue
                     if len(retrieved_data) != 0:
                         expected_value = references[key]
-                        success = (retrieved_data == expected_value)
-                        get_stats.record_operation(success, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE)
+                        success = retrieved_data == expected_value
+                        get_stats.record_operation(
+                            success, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE
+                        )
                         if not success:
                             print(f"Thread {thread_id}: Data mismatch for key {key}")
                     else:
-                        get_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, -1)
-                    
+                        get_stats.record_operation(
+                            False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, -1
+                        )
+
                     index = index + 1
                 get_end = time.perf_counter()
-                get_stats.thread_duration = get_end - get_start  # Record thread GET duration
-                
-                print(f"Thread {thread_id} completed")  
+                get_stats.thread_duration = (
+                    get_end - get_start
+                )  # Record thread GET duration
+
+                print(f"Thread {thread_id} completed")
             except Exception as e:
+                put_get_barrier.abort()
                 thread_exceptions.append(f"Thread {thread_id} failed: {str(e)}")
                 print("Exception in thread:", str(e))
-        
+
         # Record overall start time
         overall_start = time.perf_counter()
-        
+
         # Create and start threads
         threads = []
         for i in range(NUM_THREADS):
-            t = threading.Thread(target=worker, 
-                                args=(i, thread_put_stats[i], thread_get_stats[i]))
+            t = threading.Thread(
+                target=worker, args=(i, thread_put_stats[i], thread_get_stats[i])
+            )
             threads.append(t)
             t.start()
 
         # Wait for all threads to complete
         for t in threads:
             t.join()
-        
+
         # Record overall end time
         overall_end = time.perf_counter()
-        
+
+        # Cleanup before checking worker errors so partial writes do not
+        # contaminate subsequent test cases. Replication may still be
+        # completing after the lease expires, so retry transient remove
+        # failures and report any key that cannot be removed.
+        time.sleep(default_kv_lease_ttl / 1000)
+        cleanup_failures = []
+        cleanup_deadline = time.monotonic() + CLEANUP_RETRY_TIMEOUT_SECONDS
+        index = 0
+        while index < OPERATIONS_PER_THREAD:
+            key = KEY_PREFIX + str(index)
+            while True:
+                result = self.store.remove(key)
+                if result in (0, -704):
+                    break
+                if result not in RETRYABLE_REMOVE_RESULTS:
+                    cleanup_failures.append(f"{key}: remove failed with {result}")
+                    break
+                if time.monotonic() >= cleanup_deadline:
+                    cleanup_failures.append(
+                        f"{key}: remove did not make progress for "
+                        f"{CLEANUP_RETRY_TIMEOUT_SECONDS}s; last result "
+                        f"{result}"
+                    )
+                    break
+                time.sleep(0.01)
+            index += 1
+        print("Cleanup completed")
+
         # Check for exceptions
-        self.assertEqual(len(thread_exceptions), 0, "\n".join(thread_exceptions))
+        failures = thread_exceptions + [
+            f"Cleanup failed: {failure}" for failure in cleanup_failures
+        ]
+        self.assertEqual(len(failures), 0, "\n".join(failures))
 
         # Merge thread statistics into main statistics objects
         for i in range(NUM_THREADS):
             put_stats.combine(thread_put_stats[i])
             get_stats.combine(thread_get_stats[i])
-        
+
         # Calculate overall throughput statistics
         total_duration = overall_end - overall_start
         total_put_ops = OPERATIONS_PER_THREAD * NUM_THREADS
         total_get_ops = OPERATIONS_PER_THREAD * NUM_THREADS
         total_ops = total_put_ops + total_get_ops
         total_data = total_ops * VALUE_SIZE
-        
+
         # Create throughput statistics object
         throughput_stats = TestStats("Concurrent overall")
         throughput_stats.record_throughput(total_ops, total_data, total_duration)
-        
+
         # Print detailed statistics
         put_stats.print_stats()
         get_stats.print_stats()
         throughput_stats.print_throughput(thread_put_stats, thread_get_stats)
 
-        # Cleanup
-        time.sleep(default_kv_lease_ttl / 1000)
-        index = 0
-        while index < OPERATIONS_PER_THREAD:
-            key = "k_" + str(index)
-            self.store.remove(key)
-            index += 1
-        print("Cleanup completed")  
+        self.assertEqual(
+            get_stats.failure_count,
+            0,
+            f"{get_stats.failure_count} concurrent read(s) failed",
+        )
 
     def test_batch_get_in_evict_operations(self):
         """Test batch Put/Get operations with eviction scenario
-        
+
         Verifies:
         1. Data eviction to file when exceeding memory capacity using batch operations
         2. Correct retrieval of evicted data in batches
-        """ 
-        VALUE_SIZE = 1024 * 1024 
+        """
+        VALUE_SIZE = 1024 * 1024
         MAX_REQUESTS = 1000
         BATCH_SIZE = 4
+        KEY_PREFIX = "batch_get_k_"
         reference = {}
-        
+
         # Initialize statistics
         put_stats = TestStats("Put Operations")
         get_stats = TestStats("Batch Get Operations")
@@ -441,29 +583,37 @@ def test_batch_get_in_evict_operations(self):
         put_stats.start_timer()
         index = 0
         while index < MAX_REQUESTS:
-            key = "k_" + str(index)
+            key = KEY_PREFIX + str(index)
             value = os.urandom(VALUE_SIZE)
-            
+
             op_start = time.perf_counter()
             retcode = self.store.put(key, value)
             op_end = time.perf_counter()
             latency = op_end - op_start
-            
+
             if retcode == -200:
                 # The space is not enough, continue to next operation
-                put_stats.record_operation(False, ADD_OPERATION_COUNT_ONE ,latency, VALUE_SIZE, retcode)
+                put_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode
+                )
                 continue
             elif retcode == 0:
                 reference[key] = value
-                put_stats.record_operation(True, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE)
+                put_stats.record_operation(
+                    True, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE
+                )
             else:
-                put_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode)
-                raise RuntimeError(f"Put operation failed for key {key}. Error code: {retcode}")
-            
+                put_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ONE, latency, VALUE_SIZE, retcode
+                )
+                raise RuntimeError(
+                    f"Put operation failed for key {key}. Error code: {retcode}"
+                )
+
             index = index + 1
             if index % 500 == 0:
                 print("completed", index, "entries")
-        
+
         put_stats.stop_timer()
         time.sleep(5)
 
@@ -485,85 +635,114 @@ def test_batch_get_in_evict_operations(self):
         self.assertEqual(result, 0, "Buffer registration should succeed")
 
         get_stats.start_timer()
+        failed_keys = []
         index = 0
         while index < MAX_REQUESTS:
             batch_keys = []
-            
+
             # Prepare a batch of keys to get
             for _ in range(BATCH_SIZE):
                 if index >= MAX_REQUESTS:
                     break
-                key = "k_" + str(index)
+                key = KEY_PREFIX + str(index)
                 batch_keys.append(key)
                 index += 1
-                
+
             if not batch_keys:  # No more keys to process
                 break
-                
+
             # Prepare buffer pointers and sizes for this batch
             buffer_ptrs = []
             buffer_sizes = []
-            
+
             for i in range(len(batch_keys)):
                 offset = i * buffer_spacing
                 buffer_ptr = large_buffer_ptr + offset
                 buffer_ptrs.append(buffer_ptr)
                 buffer_sizes.append(VALUE_SIZE)  # Each value is 1MB
-                
+
             # Execute batch_get_into
             op_start = time.perf_counter()
             results = self.store.batch_get_into(batch_keys, buffer_ptrs, buffer_sizes)
             op_end = time.perf_counter()
             latency = op_end - op_start
-            
+
             # Verify results
-            self.assertEqual(len(results), len(batch_keys), "Should return result for each key")
-            
+            self.assertEqual(
+                len(results), len(batch_keys), "Should return result for each key"
+            )
+
             success_counter = 0
             for i, result in enumerate(results):
                 current_key = batch_keys[i]
                 expected = reference.get(current_key)
-                
+
                 if expected is not None:
                     if result > 0:
                         # Verify data integrity
                         offset = i * buffer_spacing
-                        read_data = bytes(large_buffer[offset:offset + result])
-                        success = (read_data == expected)
-                        get_stats.record_operation(success, ADD_OPERATION_COUNT_ONE, NO_ADD_LATENCY, VALUE_SIZE)
+                        read_data = bytes(large_buffer[offset : offset + result])
+                        success = read_data == expected
+                        get_stats.record_operation(
+                            success, ADD_OPERATION_COUNT_ONE, NO_ADD_LATENCY, VALUE_SIZE
+                        )
                         if not success:
+                            failed_keys.append(current_key)
                             print(f"Data mismatch for key {current_key}")
                     else:
-                        get_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, NO_ADD_LATENCY, VALUE_SIZE, result)
+                        failed_keys.append(current_key)
+                        get_stats.record_operation(
+                            False,
+                            ADD_OPERATION_COUNT_ONE,
+                            NO_ADD_LATENCY,
+                            VALUE_SIZE,
+                            result,
+                        )
                 else:
-                    get_stats.record_operation(False, ADD_OPERATION_COUNT_ONE, NO_ADD_LATENCY, VALUE_SIZE, -2)
+                    failed_keys.append(current_key)
+                    get_stats.record_operation(
+                        False, ADD_OPERATION_COUNT_ONE, NO_ADD_LATENCY, VALUE_SIZE, -2
+                    )
 
             if success_counter == BATCH_SIZE:
-                get_stats.record_operation(True, ADD_OPERATION_COUNT_ZERO, latency, NO_ADD_DATA_SIZE)
+                get_stats.record_operation(
+                    True, ADD_OPERATION_COUNT_ZERO, latency, NO_ADD_DATA_SIZE
+                )
             else:
-                get_stats.record_operation(False, ADD_OPERATION_COUNT_ZERO, latency, NO_ADD_DATA_SIZE)
-            
+                get_stats.record_operation(
+                    False, ADD_OPERATION_COUNT_ZERO, latency, NO_ADD_DATA_SIZE
+                )
+
             if index % 500 == 0:
                 print("completed", index, "entries")
-        
+
         get_stats.stop_timer()
-        
+
         # Print statistics
         put_stats.print_stats()
         get_stats.print_stats()
-        
+
         # --------------------------
         # Phase 3: Cleanup (still using single remove for simplicity)
         # --------------------------
         time.sleep(default_kv_lease_ttl / 1000)
-        self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration should succeed")
+        self.assertEqual(
+            self.store.unregister_buffer(large_buffer_ptr),
+            0,
+            "Buffer unregistration should succeed",
+        )
         index = 0
         while index < MAX_REQUESTS:
-            key = "k_" + str(index)
+            key = KEY_PREFIX + str(index)
             self.store.remove(key)
             index += 1
         print("Cleanup completed")
-    
+        self.assertEqual(
+            get_stats.failure_count,
+            0,
+            f"{get_stats.failure_count} batch read(s) failed; first failed keys: {failed_keys[:10]}",
+        )
+
 
 if __name__ == "__main__":
-    unittest.main()
\ No newline at end of file
+    unittest.main()
diff --git a/mooncake-wheel/tests/test_structured_object_store.py b/mooncake-wheel/tests/test_structured_object_store.py
index ad0060d1d0..bc942a578f 100644
--- a/mooncake-wheel/tests/test_structured_object_store.py
+++ b/mooncake-wheel/tests/test_structured_object_store.py
@@ -10,6 +10,7 @@
 import pytest
 
 import mooncake.structured_object_store as sos
+from mooncake.dataproto_catalog import DataProtoCatalog, DataProtoCatalogTransfer
 from mooncake.structured_object_store import (
     BundleTransferPolicy,
     FieldSchema,
@@ -43,6 +44,17 @@ def __init__(self) -> None:
         pass
 
 
+class GroupConfig:
+    def __init__(self, group_ids, replica_num: int = 1) -> None:
+        self.group_ids = group_ids
+        self.replica_num = replica_num
+
+
+class UncopyableGroupConfig(GroupConfig):
+    def __copy__(self):
+        raise TypeError("not copyable")
+
+
 class InMemoryStore:
     def __init__(self) -> None:
         self.objects: dict[str, bytes] = {}
@@ -62,9 +74,12 @@ def __init__(self) -> None:
         self.put_tensor_from_calls = 0
         self.batch_remove_calls = 0
         self.put_tensor_calls = 0
+        self.pub_tensor_calls = 0
         self.get_tensor_calls = 0
         self.put_configs: list[object] = []
+        self.pub_tensor_configs: list[object] = []
         self.batch_put_from_configs: list[object] = []
+        self.events: list[tuple[str, str]] = []
 
     def _enter_put(self) -> None:
         with self.lock:
@@ -86,6 +101,7 @@ def _exit_get(self, count: int = 1) -> None:
 
     def put(self, key: str, value, config=None) -> int:
         self.put_configs.append(config)
+        self.events.append(("put", key))
         self._enter_put()
         try:
             time.sleep(0.01)
@@ -96,6 +112,7 @@ def put(self, key: str, value, config=None) -> int:
             self._exit_put()
 
     def get(self, key: str) -> bytes:
+        self.events.append(("get", key))
         self._enter_get()
         try:
             time.sleep(0.01)
@@ -104,6 +121,10 @@ def get(self, key: str) -> bytes:
         finally:
             self._exit_get()
 
+    def is_exist(self, key: str) -> int:
+        with self.lock:
+            return int(key in self.objects or key in self.tensor_objects)
+
     def remove(self, key: str, force: bool = False) -> int:
         with self.lock:
             self.objects.pop(key, None)
@@ -116,6 +137,13 @@ def put_tensor(self, key: str, value) -> int:
             self.tensor_objects[key] = value.detach().clone()
         return 0
 
+    def pub_tensor(self, key: str, value, config=None) -> int:
+        self.pub_tensor_calls += 1
+        self.pub_tensor_configs.append(config)
+        with self.lock:
+            self.tensor_objects[key] = value.detach().clone()
+        return 0
+
     def get_tensor(self, key: str):
         self.get_tensor_calls += 1
         with self.lock:
@@ -304,6 +332,7 @@ class PutTensorOnlyStore(InMemoryStore):
 
 class NoTensorFastPathStore(InMemoryStore):
     put_tensor = None
+    pub_tensor = None
     get_tensor = None
 
 
@@ -434,6 +463,1034 @@ def write_manifest(
     )
 
 
+def test_default_bundle_chunk_tuning_matches_rollout_transfer_target() -> None:
+    assert sos.DEFAULT_BUNDLE_CHUNK_BYTES == 64 * 1024**2
+    assert sos.AUTO_PARALLEL_MIN_BYTES == sos.DEFAULT_BUNDLE_CHUNK_BYTES
+
+
+def test_small_dict_sized_groups_enable_auto_parallel_put() -> None:
+    class SizedBuffer:
+        def __init__(self, size: int) -> None:
+            self._size = size
+
+        def __len__(self) -> int:
+            return self._size
+
+    _store, transfer = make_transfer()
+    groups = [[SizedBuffer(1024**2)] for _ in range(128)]
+    policy = BundleTransferPolicy(max_inflight_put=8)
+    assert transfer._transport._resolve_buffer_group_put_mode(groups, policy) == "parallel"
+
+
+def _seen_group_ids(configs: list[object]) -> list[list[str]]:
+    return [
+        list(config.group_ids)
+        for config in configs
+        if config is not None and hasattr(config, "group_ids")
+    ]
+
+
+def _storage_group_id(ref) -> str:
+    group_id = ref._storage_group_id
+    assert group_id is not None
+    return group_id
+
+
+def _multi_buffer_payload(values: range) -> sos._MultiBufferPayload:
+    arrays = tuple(np.asarray([value], dtype=np.int32) for value in values)
+    return sos._MultiBufferPayload(
+        buffers=tuple(memoryview(array.data).cast("B") for array in arrays),
+        owners=arrays,
+        dtype=arrays[0].dtype.str,
+        shape=(len(arrays),),
+    )
+
+
+def test_structured_object_expands_store_replicate_config() -> None:
+    mooncake_store = pytest.importorskip("mooncake.store")
+    store, transfer = make_transfer(buffer_pool=FakeBufferPool())
+    config = mooncake_store.ReplicateConfig()
+    config.replica_num = 2
+    config.group_ids = ["rollout-group"]
+    payload = structured_payload(
+        {"kind": "replicated"}, values=_multi_buffer_payload(range(8))
+    )
+
+    ref = transfer.put_structured_object(
+        payload,
+        chunk_bytes=8,
+        policy=BundleTransferPolicy(put_mode="batch"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["values"].tolist() == list(range(8))
+    grouped_configs = [
+        seen_config
+        for seen_config in store.batch_put_from_configs
+        if seen_config is not None and hasattr(seen_config, "group_ids")
+    ]
+    assert grouped_configs
+    assert all(
+        list(seen_config.group_ids) == ["rollout-group"]
+        for seen_config in grouped_configs
+    )
+    assert all(seen_config.replica_num == 2 for seen_config in grouped_configs)
+    assert config.group_ids == ["rollout-group"]
+    expanded = sos._config_for_grouped_keys(config, 2)
+    assert expanded is not config
+    assert list(expanded.group_ids) == ["rollout-group", "rollout-group"]
+    assert expanded.replica_num == 2
+    assert config.group_ids == ["rollout-group"]
+
+
+def test_structured_object_preserves_group_id_for_streamed_batch_put() -> None:
+    store, transfer = make_transfer(buffer_pool=FakeBufferPool())
+    config = GroupConfig(["rollout-group"])
+    payload = structured_payload(
+        {"kind": "grouped"}, values=_multi_buffer_payload(range(8))
+    )
+
+    ref = transfer.put_structured_object(
+        payload,
+        chunk_bytes=8,
+        policy=BundleTransferPolicy(put_mode="batch"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["values"].tolist() == list(range(8))
+    batch_group_ids = _seen_group_ids(store.batch_put_from_configs)
+    assert batch_group_ids
+    assert all(group_ids == ["rollout-group"] for group_ids in batch_group_ids)
+    manifest_group_ids = _seen_group_ids(store.put_configs)[-1]
+    assert manifest_group_ids == ["rollout-group"]
+
+
+def test_structured_object_direct_copy_preserves_group_id(monkeypatch) -> None:
+    def copy_arrays(arrays, destination, expected_bytes, start, count):
+        payload = b"".join(
+            bytes(memoryview(array.data).cast("B"))
+            for array in arrays[start : start + count]
+        )
+        assert len(payload) == expected_bytes
+        ctypes.memmove(destination, payload, len(payload))
+        return len(payload)
+
+    monkeypatch.setattr(sos, "_concat_arrays_into", copy_arrays)
+    pool = FakeBufferPool()
+    store, transfer = make_transfer(buffer_pool=pool)
+    config = GroupConfig(["rollout-group"])
+    arrays = [
+        np.asarray([1, 2], dtype=np.int32),
+        np.asarray([3, 4], dtype=np.int32),
+    ]
+    values = sos._DirectCopyPayload.from_flat_arrays(
+        arrays, np.dtype(np.int32), total_elems=4
+    )
+
+    ref = transfer.put_structured_object(
+        structured_payload({"kind": "direct"}, values=values),
+        chunk_bytes=8,
+        config=config,
+    )
+    assert store.batch_put_from_calls > 0
+    assert pool.acquire_count == pool.release_count > 0
+    assert store.register_buffer_calls == store.unregister_buffer_calls == 0
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["values"].tolist() == [1, 2, 3, 4]
+    group_ids = _seen_group_ids(
+        [*store.put_configs, *store.batch_put_from_configs]
+    )
+    assert group_ids
+    assert all(ids == ["rollout-group"] for ids in group_ids)
+
+
+def test_structured_object_normalizes_string_group_id() -> None:
+    store, transfer = make_transfer()
+    config = GroupConfig("rollout-group")
+
+    ref = transfer.put_structured_object(
+        structured_payload({"kind": "grouped"}, value=b"payload"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["value"] == b"payload"
+    assert _seen_group_ids(store.put_configs)[-1] == ["rollout-group"]
+    assert config.group_ids == "rollout-group"
+
+
+def test_structured_object_normalizes_empty_group_ids_as_ungrouped() -> None:
+    class StrictGroupStore(InMemoryStore):
+        def put(self, key: str, value, config=None) -> int:
+            group_ids = getattr(config, "group_ids", None)
+            if group_ids is not None and len(group_ids) != 1:
+                raise ValueError("group_ids must match the number of keys")
+            return super().put(key, value, config=config)
+
+    store, transfer = make_transfer(StrictGroupStore())
+    config = GroupConfig([])
+
+    ref = transfer.put_structured_object(
+        structured_payload({"kind": "ungrouped"}, value=b"payload"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["value"] == b"payload"
+    seen_configs = [seen for seen in store.put_configs if seen is not None]
+    assert seen_configs
+    assert all(seen.group_ids is None for seen in seen_configs)
+    assert config.group_ids == []
+
+
+def test_structured_object_parallel_put_preserves_group_id() -> None:
+    store, transfer = make_transfer(buffer_pool=FakeBufferPool())
+    config = GroupConfig(["rollout-group"])
+    payload = structured_payload(
+        {"kind": "parallel"}, values=_multi_buffer_payload(range(8))
+    )
+
+    ref = transfer.put_structured_object(
+        payload,
+        chunk_bytes=8,
+        policy=BundleTransferPolicy(max_inflight_put=4, put_mode="parallel"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["values"].tolist() == list(range(8))
+    assert store.max_active_puts > 1
+    batch_group_ids = _seen_group_ids(store.batch_put_from_configs)
+    assert batch_group_ids
+    assert all(set(group_ids) == {"rollout-group"} for group_ids in batch_group_ids)
+    assert config.group_ids == ["rollout-group"]
+
+
+def test_structured_object_multi_buffer_put_preserves_group_id() -> None:
+    pool = FakeBufferPool()
+    store, transfer = make_transfer(buffer_pool=pool)
+    config = GroupConfig(["rollout-group"])
+    multi = _multi_buffer_payload(range(8))
+
+    ref = transfer.put_structured_object(
+        structured_payload({"kind": "multi"}, values=multi),
+        chunk_bytes=64,
+        policy=BundleTransferPolicy(put_mode="batch"),
+        config=config,
+    )
+    result = transfer.materialize(transfer.read_spec(ref))
+
+    assert result.objects["values"].tolist() == list(range(8))
+    batch_group_ids = _seen_group_ids(store.batch_put_from_configs)
+    assert batch_group_ids
+    assert all(group_ids == ["rollout-group"] for group_ids in batch_group_ids)
+
+
+def test_bundle_manifest_update_allows_meta_only_cleanup_keys() -> None:
+    store, transfer = make_transfer()
+    old_ref = transfer.put_structured_object(structured_payload({"kind": "old"}))
+    cleanup_keys = [
+        old_ref.manifest_key,
+        *transfer._bundle_store.payload_keys(old_ref.manifest["meta"]),
+    ]
+
+    merged_ref = transfer._bundle_store.put_bundle_manifest(
+        json.dumps({"kind": "merged"}, separators=(",", ":")).encode("utf-8"),
+        {},
+        partition="default",
+        chunk_bytes=None,
+        policy=None,
+        cleanup_keys=cleanup_keys,
+    )
+    result = transfer.materialize(transfer.read_spec(merged_ref))
+    manifest = sos._decode_manifest(store.objects[merged_ref.manifest_key])
+
+    assert result.metadata == {"kind": "merged"}
+    assert result.objects == {}
+    assert set(cleanup_keys).issubset(set(manifest["cleanup_keys"]))
+    assert old_ref.manifest["object_id"] in manifest["buffer_object_ids"]
+
+    transfer.remove_bundle(merged_ref)
+
+    assert old_ref.manifest_key not in store.objects
+    assert merged_ref.manifest_key not in store.objects
+    assert all(key not in store.objects for key in cleanup_keys)
+
+
+def test_dataproto_append_updates_manifest_with_grouped_config() -> None:
+    store, transfer = make_transfer()
+    config = GroupConfig(["rollout-group"])
+    ref = transfer.put(
+        {"input_ids": np.arange(6, dtype=np.int64).reshape(3, 2)},
+        type="dict",
+        stage="rollout",
+        chunk_bytes=16,
+        policy=BundleTransferPolicy(put_mode="batch"),
+        config=config,
+    )
+    old_manifest_key = ref.stage_refs["rollout"].manifest_key
+
+    ref = transfer.append_dataproto_fields(
+        ref,
+        SimpleDataProto(batch={"rewards": np.arange(3, dtype=np.float32)}),
+        stage="rollout",
+        chunk_bytes=16,
+        policy=BundleTransferPolicy(put_mode="batch"),
+        config=config,
+    )
+    result = transfer.get(ref, type="dict")
+    view = transfer.dataproto_manifest_view(ref)
+
+    assert ref.stage_refs["rollout"].manifest_key != old_manifest_key
+    assert np.array_equal(
+        result["input_ids"], np.arange(6, dtype=np.int64).reshape(3, 2)
+    )
+    assert np.array_equal(result["rewards"], np.arange(3, dtype=np.float32))
+    assert set(view["batch_fields"]) == {"input_ids", "rewards"}
+    stage_manifest = store.objects[ref.stage_refs["rollout"].manifest_key]
+    manifest = sos._decode_manifest(stage_manifest)
+    assert set(manifest["buffers"]) == {"batch.input_ids", "batch.rewards"}
+    assert old_manifest_key in manifest["cleanup_keys"]
+    write_group_ids = _seen_group_ids(
+        [*store.put_configs, *store.batch_put_from_configs]
+    )
+    assert write_group_ids
+    assert all(group_ids == ["rollout-group"] for group_ids in write_group_ids)
+
+
+def test_dataproto_repeated_same_stage_append_preserves_cleanup_lineage() -> None:
+    store, transfer = make_transfer()
+    ref = transfer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(4, dtype=np.int64)}),
+        stage="rollout",
+    )
+    initial_manifest_key = ref.stage_refs["rollout"].manifest_key
+    ref = transfer.append_dataproto_fields(
+        ref,
+        SimpleDataProto(batch={"values": np.arange(4, dtype=np.float32)}),
+        stage="rollout",
+    )
+    first_merged_manifest_key = ref.stage_refs["rollout"].manifest_key
+    ref = transfer.append_dataproto_fields(
+        ref,
+        SimpleDataProto(batch={"rewards": np.arange(4, dtype=np.float32)}),
+        stage="rollout",
+    )
+    final_manifest = sos._decode_manifest(
+        store.objects[ref.stage_refs["rollout"].manifest_key]
+    )
+
+    assert initial_manifest_key in final_manifest["cleanup_keys"]
+    assert first_merged_manifest_key in final_manifest["cleanup_keys"]
+    transfer.cleanup_dataproto(ref)
+    assert store.objects == {}
+
+
+def test_structured_object_rejects_ambiguous_group_ids() -> None:
+    _store, transfer = make_transfer()
+
+    with pytest.raises(ValueError, match="config.group_ids"):
+        transfer.put_structured_object(
+            structured_payload({"kind": "bad"}, value=b"payload"),
+            config=GroupConfig(["group-a", "group-b"]),
+        )
+
+
+@pytest.mark.parametrize("payload_type", ["dict", "dataproto"])
+def test_high_level_put_auto_creates_opaque_storage_group(payload_type) -> None:
+    store, transfer = make_transfer()
+    config = GroupConfig(None, replica_num=2)
+    data = (
+        {"input_ids": np.arange(4)}
+        if payload_type == "dict"
+        else SimpleDataProto(batch={"input_ids": np.arange(4)})
+    )
+
+    ref = transfer.put(data, type=payload_type, stage="rollout", config=config)
+
+    group_id = _storage_group_id(ref)
+    handle = export_dataproto_ref(ref)
+    assert group_id.startswith("structured-")
+    assert handle["version"] == 1
+    assert handle["storage_group_id"] == group_id
+    assert all(
+        list(write_config.group_ids) == [group_id]
+        for write_config in store.put_configs
+    )
+    assert all(
+        write_config.replica_num == 2
+        for write_config in store.put_configs
+    )
+    assert config.group_ids is None
+    assert config.replica_num == 2
+
+
+def test_high_level_put_preserves_explicit_ungrouped_config() -> None:
+    store, transfer = make_transfer()
+    config = GroupConfig([""], replica_num=2)
+
+    ref = transfer.put(
+        {"input_ids": np.arange(4)},
+        type="dict",
+        config=config,
+    )
+    handle = export_dataproto_ref(ref)
+    first_put_count = len(store.put_configs)
+    appended = MooncakeBundleTransfer(
+        store, key_prefix=transfer.key_prefix
+    ).append_dataproto_fields(
+        handle,
+        SimpleDataProto(batch={"values": np.arange(4) + 10}),
+        stage="value",
+    )
+    result = transfer.get_dataproto(appended)
+
+    assert ref._storage_group_id is None
+    assert handle["version"] == 1
+    assert "storage_group_id" not in handle
+    assert all(
+        list(write_config.group_ids) == [""]
+        for write_config in store.put_configs
+        if write_config is not None
+    )
+    assert all(
+        seen_config is None
+        for seen_config in store.put_configs[first_put_count:]
+    )
+    assert appended._storage_group_id is None
+    assert np.array_equal(result["batch"]["input_ids"], np.arange(4))
+    assert np.array_equal(result["batch"]["values"], np.arange(4) + 10)
+    assert config.group_ids == [""]
+    assert config.replica_num == 2
+
+
+@pytest.mark.parametrize("object_type", ["dict", "dataproto"])
+def test_high_level_put_preserves_grouped_tensor_fast_path(object_type) -> None:
+    torch = pytest.importorskip("torch")
+    store, transfer = make_transfer()
+    tensor = torch.arange(12, dtype=torch.int64).reshape(4, 3)
+
+    if object_type == "dict":
+        ref = transfer.put({"input_ids": tensor}, type="dict", stage="rollout")
+        result = transfer.get(ref, type="dict")
+        actual = result["input_ids"]
+    else:
+        ref = transfer.put_dataproto(
+            SimpleDataProto(batch={"input_ids": tensor}),
+            stage="rollout",
+        )
+        result = transfer.get_dataproto(ref)
+        actual = result["batch"]["input_ids"]
+
+    group_id = _storage_group_id(ref)
+    payload = ref.stage_refs["rollout"].manifest["buffers"]["batch.input_ids"]
+    assert payload["kind"] == "tensor"
+    assert store.pub_tensor_calls == 1
+    assert store.put_tensor_calls == 0
+    assert store.batch_put_from_calls == 0
+    assert store.get_tensor_calls == 1
+    assert _seen_group_ids(store.pub_tensor_configs) == [[group_id]]
+    assert torch.equal(actual, tensor)
+
+
+def test_high_level_append_preserves_grouped_tensor_fast_path() -> None:
+    torch = pytest.importorskip("torch")
+    store, transfer = make_transfer()
+    input_ids = torch.arange(12, dtype=torch.int64).reshape(4, 3)
+    rewards = torch.arange(4, dtype=torch.float32)
+    ref = transfer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": input_ids}),
+        stage="rollout",
+    )
+    group_id = _storage_group_id(ref)
+    old_payload_key = ref.stage_refs["rollout"].manifest["buffers"][
+        "batch.input_ids"
+    ]["key"]
+
+    ref = transfer.append_dataproto_fields(
+        ref,
+        SimpleDataProto(batch={"rewards": rewards}),
+        stage="rollout",
+    )
+    result = transfer.get_dataproto(ref)
+    buffers = ref.stage_refs["rollout"].manifest["buffers"]
+
+    assert ref._storage_group_id == group_id
+    assert buffers["batch.input_ids"]["key"] == old_payload_key
+    assert buffers["batch.input_ids"]["kind"] == "tensor"
+    assert buffers["batch.rewards"]["kind"] == "tensor"
+    assert store.pub_tensor_calls == 2
+    assert store.put_tensor_calls == 0
+    assert store.batch_put_from_calls == 0
+    assert store.get_tensor_calls == 2
+    assert _seen_group_ids(store.pub_tensor_configs) == [[group_id], [group_id]]
+    assert torch.equal(result["batch"]["input_ids"], input_ids)
+    assert torch.equal(result["batch"]["rewards"], rewards)
+
+    transfer.cleanup_dataproto(ref)
+    assert store.objects == {}
+    assert store.tensor_objects == {}
+
+
+def test_grouped_tensor_falls_back_when_pub_tensor_is_unavailable() -> None:
+    torch = pytest.importorskip("torch")
+    store, transfer = make_transfer(NoTensorFastPathStore())
+    tensor = torch.arange(12, dtype=torch.int64).reshape(4, 3)
+
+    ref = transfer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": tensor}),
+        stage="rollout",
+    )
+    result = transfer.get_dataproto(ref)
+
+    group_id = _storage_group_id(ref)
+    payload = ref.stage_refs["rollout"].manifest["buffers"]["batch.input_ids"]
+    assert payload.get("kind") != "tensor"
+    assert store.put_tensor_calls == 0
+    assert store.pub_tensor_calls == 0
+    assert store.get_tensor_calls == 0
+    assert _seen_group_ids(store.put_configs) == [
+        [group_id],
+        [group_id],
+        [group_id],
+    ]
+    assert torch.equal(result["batch"]["input_ids"], tensor)
+
+
+@pytest.mark.parametrize(
+    ("group_ids", "expected_group_id"),
+    [("metadata-group", "metadata-group"), ([], None)],
+)
+def test_metadata_only_initial_put_does_not_copy_config(
+    group_ids, expected_group_id
+) -> None:
+    store, transfer = make_transfer()
+    config = UncopyableGroupConfig(group_ids)
+
+    ref = transfer.put_dataproto(
+        SimpleDataProto(meta_info={"step": 1}),
+        config=config,
+    )
+
+    group_id = _storage_group_id(ref)
+    if expected_group_id is None:
+        assert group_id.startswith("structured-")
+    else:
+        assert group_id == expected_group_id
+    assert store.events == []
+    assert config.group_ids == group_ids
+
+
+def test_high_level_put_rejects_non_string_group_before_write() -> None:
+    store, transfer = make_transfer()
+
+    with pytest.raises(ValueError, match="must contain strings"):
+        transfer.put_dataproto(
+            SimpleDataProto(batch={"input_ids": np.arange(4)}),
+            config=GroupConfig([123]),
+        )
+
+    assert store.put_configs == []
+
+
+def test_imported_handle_append_recovers_group_without_scanning_old_stage() -> None:
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="cross-instance")
+    reader = MooncakeBundleTransfer(store, key_prefix="cross-instance")
+    ref = writer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(4)}),
+        stage="rollout",
+    )
+    group_id = _storage_group_id(ref)
+    first_append_record = len(store.put_configs)
+    store.events.clear()
+
+    appended = reader.append_dataproto_fields(
+        export_dataproto_ref(ref),
+        SimpleDataProto(batch={"values": np.arange(4)}),
+        stage="value",
+    )
+
+    assert not any(event == "get" for event, _key in store.events)
+    assert appended._storage_group_id == group_id
+    assert all(
+        list(config.group_ids) == [group_id]
+        for config in store.put_configs[first_append_record:]
+    )
+    third = MooncakeBundleTransfer(store, key_prefix="cross-instance")
+    final = third.append_dataproto_fields(
+        export_dataproto_ref(appended),
+        SimpleDataProto(batch={"rewards": np.arange(4) + 10}),
+        stage="rollout",
+    )
+    result = third.get_dataproto(final)
+
+    assert final._storage_group_id == group_id
+    assert np.array_equal(result["batch"]["values"], np.arange(4))
+    assert np.array_equal(result["batch"]["rewards"], np.arange(4) + 10)
+    assert all(
+        list(config.group_ids) == [group_id]
+        for config in store.put_configs[first_append_record:]
+    )
+
+
+@pytest.mark.parametrize("append_stage", ["rollout", "value"])
+@pytest.mark.parametrize("ungrouped", [False, True])
+@pytest.mark.parametrize("response_error", [None, RuntimeError, ValueError])
+def test_catalog_manages_appended_handle_lifetime(
+    append_stage, ungrouped, response_error
+) -> None:
+    class SizedDataProto(SimpleDataProto):
+        def __len__(self) -> int:
+            return len(next(iter(self.batch.values())))
+
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="catalog-append")
+    appender = MooncakeBundleTransfer(store, key_prefix="catalog-append")
+    catalog = DataProtoCatalog()
+    lost_responses = 2 if response_error is not None else 0
+
+    def call(method, *args, **kwargs):
+        nonlocal lost_responses
+        result = getattr(catalog, method)(*args, **kwargs)
+        if method == "publish_append" and lost_responses:
+            lost_responses -= 1
+            raise response_error("response lost after commit")
+        return result
+
+    writer_client = DataProtoCatalogTransfer(writer, call)
+    appender_client = DataProtoCatalogTransfer(appender, call)
+    writer_client.put(
+        SizedDataProto(batch={"input_ids": np.arange(2)}),
+        partition="train",
+        keys=["a", "b"],
+        stage="rollout",
+        config=GroupConfig([""]) if ungrouped else None,
+    )
+    base_plan = writer_client.resolve("train", ["a", "b"])
+    fragment_id, base_handle = next(iter(base_plan["handles"].items()))
+    writer_client.put(
+        SizedDataProto(batch={"partial_score": np.arange(1)}),
+        partition="train",
+        keys=["a"],
+        stage="score",
+    )
+
+    with pytest.raises(ValueError, match="overwrite"):
+        appender_client.append(
+            fragment_id,
+            base_handle,
+            SizedDataProto(batch={"input_ids": np.arange(2) + 10}),
+            partition="train",
+            keys=["a", "b"],
+            stage="rollout",
+            overwrite=True,
+        )
+    stored_keys = (set(store.objects), set(store.tensor_objects))
+    with pytest.raises(ValueError, match="keys were not found"):
+        appender_client.append(
+            fragment_id,
+            base_handle,
+            SizedDataProto(batch={"values": np.arange(2) + 10}),
+            partition="train",
+            keys=["a", "missing"],
+            stage=append_stage,
+        )
+    assert (set(store.objects), set(store.tensor_objects)) == stored_keys
+    append_args = (
+        fragment_id,
+        base_handle,
+        SizedDataProto(batch={"values": np.arange(2) + 10}),
+    )
+    append_kwargs = {
+        "partition": "train",
+        "keys": ["a", "b"],
+        "stage": append_stage,
+    }
+    if response_error is not None:
+        with pytest.raises(response_error, match="response lost"):
+            appender_client.append(*append_args, **append_kwargs)
+    else:
+        appender_client.append(*append_args, **append_kwargs)
+    latest_plan = appender_client.resolve(
+        "train", ["a", "b"], fields=["input_ids", "values"]
+    )
+    appended = import_dataproto_ref(latest_plan["handles"][fragment_id])
+    assert appended._storage_group_id == base_handle.get("storage_group_id")
+    assert np.array_equal(
+        appender.get_dataproto(appended)["batch"]["values"], np.arange(2) + 10
+    )
+    old_reader = writer.get_dataproto(import_dataproto_ref(base_handle))
+    assert np.array_equal(old_reader["batch"]["input_ids"], np.arange(2))
+    stored_keys = (set(store.objects), set(store.tensor_objects))
+    with pytest.raises(ValueError, match="stale"):
+        appender_client.append(
+            fragment_id,
+            base_handle,
+            SizedDataProto(batch={"rewards": np.arange(2) + 20}),
+            partition="train",
+            keys=["a", "b"],
+            stage="reward",
+        )
+    assert (set(store.objects), set(store.tensor_objects)) == stored_keys
+    appender_client.close()
+
+    appender_client.remove("train", ["a", "b"])
+    assert store.objects or store.tensor_objects
+    appender_client.release_read(latest_plan["read_token"])
+    assert store.objects or store.tensor_objects
+    writer_client.release_read(base_plan["read_token"])
+    assert store.objects == {}
+    assert store.tensor_objects == {}
+
+
+def test_legacy_v1_handle_append_get_and_cleanup_uses_caller_group() -> None:
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="legacy-v1")
+    reader = MooncakeBundleTransfer(store, key_prefix="legacy-v1")
+    ref = writer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(4)}),
+        stage="rollout",
+    )
+    legacy_handle = export_dataproto_ref(ref)
+    legacy_handle["version"] = 1
+    legacy_handle.pop("storage_group_id")
+    store.put_configs.clear()
+    store.batch_put_from_configs.clear()
+    config = GroupConfig(["legacy-group"], replica_num=2)
+
+    appended = reader.append_dataproto_fields(
+        legacy_handle,
+        SimpleDataProto(batch={"values": np.arange(4) + 10}),
+        stage="value",
+        config=config,
+    )
+    result = reader.get_dataproto(appended)
+    reader.cleanup_dataproto(appended)
+
+    assert np.array_equal(result["batch"]["input_ids"], np.arange(4))
+    assert np.array_equal(result["batch"]["values"], np.arange(4) + 10)
+    assert appended._storage_group_id is None
+    group_ids = _seen_group_ids(
+        [*store.put_configs, *store.batch_put_from_configs]
+    )
+    assert group_ids
+    assert all(
+        write_group_ids == ["legacy-group"] for write_group_ids in group_ids
+    )
+    assert config.group_ids == ["legacy-group"]
+    assert config.replica_num == 2
+    assert store.objects == {}
+
+
+def test_metadata_only_append_preserves_group_without_store_io() -> None:
+    store, transfer = make_transfer()
+    ref = transfer.put_dataproto(SimpleDataProto(meta_info={"step": 1}))
+    group_id = _storage_group_id(ref)
+    store.events.clear()
+
+    appended = transfer.append_dataproto_fields(
+        export_dataproto_ref(ref),
+        SimpleDataProto(meta_info={"stage": "metadata"}),
+        stage="metadata",
+    )
+
+    assert appended._storage_group_id == group_id
+    assert store.events == []
+
+
+def test_concurrent_append_branches_inherit_group_without_merging_refs() -> None:
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="concurrent-append")
+    ref = writer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(4)}),
+        stage="rollout",
+    )
+    handle = export_dataproto_ref(ref)
+    group_id = _storage_group_id(ref)
+    barrier = threading.Barrier(3)
+    branches = {}
+    failures = []
+
+    def append(name: str) -> None:
+        try:
+            transfer = MooncakeBundleTransfer(
+                store, key_prefix="concurrent-append"
+            )
+            barrier.wait()
+            branches[name] = transfer.append_dataproto_fields(
+                handle,
+                SimpleDataProto(batch={name: np.arange(4)}),
+                stage="rollout",
+            )
+        except BaseException as error:
+            failures.append(error)
+
+    value_thread = threading.Thread(target=append, args=("values",))
+    reward_thread = threading.Thread(target=append, args=("rewards",))
+    store.put_configs.clear()
+    value_thread.start()
+    reward_thread.start()
+    barrier.wait()
+    value_thread.join(timeout=5)
+    reward_thread.join(timeout=5)
+
+    assert not value_thread.is_alive()
+    assert not reward_thread.is_alive()
+    assert failures == []
+    assert branches["values"]._storage_group_id == group_id
+    assert branches["rewards"]._storage_group_id == group_id
+    assert set(branches["values"].field_index) == {"input_ids", "values"}
+    assert set(branches["rewards"].field_index) == {"input_ids", "rewards"}
+    value_result = writer.get_dataproto(branches["values"])
+    reward_result = writer.get_dataproto(branches["rewards"])
+    assert set(value_result["batch"]) == {"input_ids", "values"}
+    assert set(reward_result["batch"]) == {"input_ids", "rewards"}
+    assert all(
+        list(config.group_ids) == [group_id]
+        for config in store.put_configs
+    )
+
+
+@pytest.mark.parametrize("append_stage", ["rollout", "value"])
+@pytest.mark.parametrize("cleanup_failures", [0, 2])
+def test_catalog_concurrent_append_cleans_stale_loser(
+    append_stage, cleanup_failures, monkeypatch
+) -> None:
+    class SizedDataProto(SimpleDataProto):
+        def __len__(self) -> int:
+            return len(next(iter(self.batch.values())))
+
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="catalog-concurrent-append")
+    first = MooncakeBundleTransfer(store, key_prefix="catalog-concurrent-append")
+    second = MooncakeBundleTransfer(store, key_prefix="catalog-concurrent-append")
+    catalog = DataProtoCatalog()
+    publish_barrier = threading.Barrier(3)
+    catalog_lock = threading.Lock()
+    publication_lock = threading.Lock()
+    seen_publications = set()
+
+    def call(method, *args, **kwargs):
+        if method == "publish_append":
+            with publication_lock:
+                first_attempt = args[0] not in seen_publications
+                seen_publications.add(args[0])
+            if first_attempt:
+                publish_barrier.wait(timeout=5)
+        with catalog_lock:
+            return getattr(catalog, method)(*args, **kwargs)
+
+    writer_client = DataProtoCatalogTransfer(writer, call)
+    first_client = DataProtoCatalogTransfer(first, call)
+    second_client = DataProtoCatalogTransfer(second, call)
+    remaining_cleanup_failures = cleanup_failures
+
+    def fail_cleanup(transfer):
+        original = transfer.cleanup_dataproto_append
+
+        def cleanup(*args):
+            nonlocal remaining_cleanup_failures
+            if remaining_cleanup_failures:
+                remaining_cleanup_failures -= 1
+                raise RuntimeError("injected append cleanup failure")
+            original(*args)
+
+        monkeypatch.setattr(transfer, "cleanup_dataproto_append", cleanup)
+
+    fail_cleanup(first)
+    fail_cleanup(second)
+    writer_client.put(
+        SizedDataProto(batch={"input_ids": np.arange(2)}),
+        partition="train",
+        keys=["a", "b"],
+        stage="rollout",
+    )
+    base_plan = writer_client.resolve("train", ["a", "b"])
+    fragment_id, base_handle = next(iter(base_plan["handles"].items()))
+
+    results = {}
+    failures = []
+    clients = {"first": first_client, "second": second_client}
+
+    def append(name: str) -> None:
+        try:
+            results[name] = clients[name].append(
+                fragment_id,
+                base_handle,
+                SizedDataProto(batch={name: np.arange(2) + 10}),
+                partition="train",
+                keys=["a", "b"],
+                stage=append_stage,
+            )
+        except BaseException as error:
+            failures.append(error)
+
+    first_thread = threading.Thread(target=append, args=("first",))
+    second_thread = threading.Thread(target=append, args=("second",))
+    first_thread.start()
+    second_thread.start()
+    publish_barrier.wait(timeout=5)
+    first_thread.join(timeout=5)
+    second_thread.join(timeout=5)
+
+    assert not first_thread.is_alive()
+    assert not second_thread.is_alive()
+    assert len(results) == 1
+    assert len(failures) == 1
+    if cleanup_failures:
+        assert isinstance(failures[0], RuntimeError)
+        assert "cleanup failure" in str(failures[0])
+        pending_client = next(
+            client for client in clients.values() if client._pending_publications
+        )
+        pending_client.close()
+    else:
+        assert isinstance(failures[0], ValueError)
+        assert "stale" in str(failures[0])
+    assert first_client._pending_publications == []
+    assert second_client._pending_publications == []
+
+    winner_name = next(iter(results))
+    winner_client = clients[winner_name]
+    winner_plan = winner_client.resolve("train", ["a", "b"])
+    winner = import_dataproto_ref(winner_plan["handles"][fragment_id])
+    winner_data = winner_client.transfer.get_dataproto(winner)
+    assert set(winner_data["batch"]) == {"input_ids", winner_name}
+    assert np.array_equal(
+        winner_data["batch"][winner_name], np.arange(2) + 10
+    )
+    old_data = writer.get_dataproto(import_dataproto_ref(base_handle))
+    assert np.array_equal(old_data["batch"]["input_ids"], np.arange(2))
+
+    winner_client.remove("train", ["a", "b"])
+    winner_client.release_read(winner_plan["read_token"])
+    old_data = writer.get_dataproto(import_dataproto_ref(base_handle))
+    assert np.array_equal(old_data["batch"]["input_ids"], np.arange(2))
+    writer_client.release_read(base_plan["read_token"])
+    writer_client.close()
+    first_client.close()
+    second_client.close()
+    assert store.objects == {}
+    assert store.tensor_objects == {}
+
+
+@pytest.mark.parametrize("append_stage", ["rollout", "value"])
+@pytest.mark.parametrize("race", ["remove", "drain"])
+def test_catalog_cleans_append_rejected_after_remove_or_drain(
+    append_stage, race
+) -> None:
+    class SizedDataProto(SimpleDataProto):
+        def __len__(self) -> int:
+            return len(next(iter(self.batch.values())))
+
+    store = InMemoryStore()
+    writer = MooncakeBundleTransfer(store, key_prefix="catalog-append-race")
+    appender = MooncakeBundleTransfer(store, key_prefix="catalog-append-race")
+    catalog = DataProtoCatalog()
+    raced = False
+
+    def direct_call(method, *args, **kwargs):
+        return getattr(catalog, method)(*args, **kwargs)
+
+    writer_client = DataProtoCatalogTransfer(writer, direct_call)
+    drainer_client = DataProtoCatalogTransfer(writer, direct_call)
+
+    def call(method, *args, **kwargs):
+        nonlocal raced
+        if method == "publish_append" and not raced:
+            raced = True
+            if race == "remove":
+                writer_client.remove("train", ["a"])
+            else:
+                drainer_client.drain()
+        return direct_call(method, *args, **kwargs)
+
+    appender_client = DataProtoCatalogTransfer(appender, call)
+    writer_client.put(
+        SizedDataProto(batch={"input_ids": np.arange(2)}),
+        partition="train",
+        keys=["a", "b"],
+        stage="rollout",
+    )
+    plan = catalog.resolve("train", ["a", "b"])
+    fragment_id, base_handle = next(iter(plan["handles"].items()))
+
+    match = "keys not found" if race == "remove" else "catalog is drained"
+    with pytest.raises(ValueError, match=match):
+        appender_client.append(
+            fragment_id,
+            base_handle,
+            SizedDataProto(batch={"values": np.arange(2) + 10}),
+            partition="train",
+            keys=["a", "b"],
+            stage=append_stage,
+        )
+
+    appender_client.close()
+    if race == "remove":
+        writer_client.remove("train", ["b"])
+    assert store.objects == {}
+    assert store.tensor_objects == {}
+
+
+def test_same_stage_append_cleanup_tolerates_lost_manifest_remove_response(
+    monkeypatch,
+) -> None:
+    store, transfer = make_transfer(key_prefix="append-cleanup-response-loss")
+    base = transfer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(2)}), stage="rollout"
+    )
+    appended = transfer.append_dataproto_fields(
+        base,
+        SimpleDataProto(batch={"values": np.arange(2) + 10}),
+        stage="rollout",
+    )
+    appended_manifest = appended.stage_refs["rollout"].manifest_key
+    batch_remove = store.batch_remove
+    lose_response = True
+
+    def remove_then_lose_response(keys, force=False):
+        nonlocal lose_response
+        results = batch_remove(keys, force)
+        if lose_response and keys == [appended_manifest]:
+            lose_response = False
+            raise RuntimeError("manifest remove response lost")
+        return results
+
+    monkeypatch.setattr(store, "batch_remove", remove_then_lose_response)
+    with pytest.raises(RuntimeError, match="response lost"):
+        transfer.cleanup_dataproto_append(base, appended)
+    transfer.cleanup_dataproto_append(base, appended)
+
+    result = transfer.get_dataproto(base)
+    assert np.array_equal(result["batch"]["input_ids"], np.arange(2))
+    transfer.cleanup_dataproto(base)
+    assert store.objects == {}
+    assert store.tensor_objects == {}
+
+
+def test_append_rejects_conflicting_group_before_write() -> None:
+    store, transfer = make_transfer()
+    ref = transfer.put_dataproto(
+        SimpleDataProto(batch={"input_ids": np.arange(4)})
+    )
+    before_puts = len(store.put_configs)
+
+    with pytest.raises(ValueError, match="conflicts"):
+        transfer.append_dataproto_fields(
+            export_dataproto_ref(ref),
+            SimpleDataProto(batch={"values": np.arange(4)}),
+            stage="value",
+            config=GroupConfig(["other-group"]),
+        )
+
+    assert len(store.put_configs) == before_puts
+
+
 def test_put_object_roundtrips_numpy_and_torch_tensor_fields() -> None:
     torch = pytest.importorskip("torch")
     store, transfer = make_transfer()
@@ -507,6 +1564,27 @@ def test_put_object_torch_tensor_raw_fallback_roundtrip() -> None:
     assert store.batch_get_into_calls > 0
 
 
+def test_dataproto_torch_save_fallback_supports_row_selection(monkeypatch) -> None:
+    torch = pytest.importorskip("torch")
+    monkeypatch.setattr(sos, "_has_tensor_codec_helpers", lambda: False)
+    _store, transfer = make_transfer(NoTensorFastPathStore())
+    tensor = torch.arange(24, dtype=torch.float32).reshape(6, 4)
+
+    ref = transfer.put_dataproto(SimpleDataProto(batch={"tensor": tensor}))
+    payload = ref.stage_refs["default"].manifest["buffers"]["batch.tensor"]
+
+    assert payload["format"] == "torch_save"
+    for rows in (slice(1, 6, 2), [4, 1, 4], [], [-1, 0]):
+        assert torch.equal(
+            transfer.get_dataproto(ref, rows=rows)["batch"]["tensor"],
+            tensor[rows],
+        )
+    with pytest.raises(ValueError, match="does not support destinations"):
+        transfer.get_dataproto(
+            ref, rows=[1], destinations={"tensor": object()}
+        )
+
+
 def test_bundle_read_spec_full_read_is_partial_special_case() -> None:
     store, transfer = make_transfer()
     array = np.arange(16, dtype=np.int32).reshape(4, 4)
@@ -891,7 +1969,7 @@ def test_bundle_remove_deletes_payload_and_manifest() -> None:
     transfer.remove_bundle(ref)
 
     assert store.objects == {}
-    assert store.batch_remove_calls == 1
+    assert store.batch_remove_calls == 2
 
 
 def test_bundle_partial_put_failure_cleans_payloads() -> None:
@@ -920,7 +1998,7 @@ def test_bundle_remove_uses_force_batch_remove_when_available() -> None:
     transfer.materialize(transfer.read_spec(ref))
     transfer.remove_bundle(ref)
 
-    assert store.batch_remove_forces == [True]
+    assert store.batch_remove_forces == [True, True]
     assert store.objects == {}
 
 
@@ -931,7 +2009,36 @@ def test_bundle_remove_recovers_after_transient_batch_failure() -> None:
     transfer.remove_bundle(ref)
 
     assert store.objects == {}
-    assert store.batch_remove_calls == 1
+    assert store.batch_remove_calls == 2
+
+
+def test_bundle_remove_keeps_manifest_until_payload_cleanup_succeeds(
+    monkeypatch,
+) -> None:
+    store, transfer = make_transfer()
+    ref = transfer.put_bundle(b"meta", {"payload": b"abcdef"}, chunk_bytes=2)
+    failed_key = ref.manifest["buffers"]["payload"]["chunks"][0]["key"]
+    remove = store.remove
+    monkeypatch.setattr(
+        store,
+        "remove",
+        lambda key, force=False: -1 if key == failed_key else remove(key, force),
+    )
+    monkeypatch.setattr(
+        store,
+        "batch_remove",
+        lambda keys, force=False: [store.remove(key, force) for key in keys],
+    )
+
+    with pytest.raises(RuntimeError, match="failed to remove"):
+        transfer.remove_bundle(ref)
+
+    assert failed_key in store.objects
+    assert ref.manifest_key in store.objects
+    monkeypatch.setattr(store, "remove", remove)
+    transfer.remove_bundle(ref)
+    transfer.remove_bundle({"manifest_key": ref.manifest_key})
+    assert store.objects == {}
 
 
 def test_bundle_batch_get_failure_unregisters_buffer() -> None:
@@ -1603,9 +2710,9 @@ def test_dataproto_field_schema_encodes_typed_ragged_non_tensor_field() -> None:
     )
     result = transfer.get_dataproto(ref)["non_tensor_batch"]["tokens"]
 
-    assert result[0] == [1, 2]
+    assert result[0].tolist() == [1, 2]
     assert result[1] is None
-    assert result[2] == [3]
+    assert result[2].tolist() == [3]
 
     bad_text = np.asarray([object()], dtype=object)
     with pytest.raises(AttributeError, match="failed to encode.*'text'.*utf8_ragged"):
@@ -1814,6 +2921,59 @@ def test_unified_put_get_roundtrips_flat_dict() -> None:
     assert result["step"] == 7
 
 
+def test_unified_dict_get_returns_flat_lists_without_changing_dataproto_shape() -> None:
+    _store, transfer = make_transfer()
+    data = {
+        "tokens": [
+            np.asarray([1, 2], dtype=np.int32),
+            np.asarray([3], dtype=np.int32),
+            np.asarray([4, 5, 6], dtype=np.int32),
+        ],
+        "json": [{"rank": 0}, {"rank": 1}, {"rank": 2}],
+    }
+    schemas = {
+        "tokens": FieldSchema(
+            codec="typed_ragged",
+            metadata={"section": "non_tensor_batch", "dtype": "int32"},
+        ),
+        "json": FieldSchema(
+            codec="msgpack_ragged",
+            metadata={"section": "non_tensor_batch"},
+        ),
+    }
+
+    ref = transfer.put(data, type="dict", field_schemas=schemas)
+
+    flat = transfer.get(ref, type="dict")
+    assert isinstance(flat["tokens"], list)
+    assert isinstance(flat["json"], list)
+    assert [row.tolist() for row in flat["tokens"]] == [[1, 2], [3], [4, 5, 6]]
+    assert flat["json"] == [{"rank": 0}, {"rank": 1}, {"rank": 2}]
+
+    sliced = transfer.get(ref, type="dict", rows=slice(1, 3))
+    assert isinstance(sliced["tokens"], list)
+    assert isinstance(sliced["json"], list)
+    assert [row.tolist() for row in sliced["tokens"]] == [[3], [4, 5, 6]]
+    assert sliced["json"] == [{"rank": 1}, {"rank": 2}]
+
+    envelope = transfer.get_dataproto(ref, data_cls=dict)
+    non_tensor_batch = envelope["non_tensor_batch"]
+    assert isinstance(non_tensor_batch["tokens"], np.ndarray)
+    assert non_tensor_batch["tokens"].dtype == object
+    assert isinstance(non_tensor_batch["json"], np.ndarray)
+    assert non_tensor_batch["json"].dtype == object
+    assert [row.tolist() for row in non_tensor_batch["tokens"]] == [
+        [1, 2],
+        [3],
+        [4, 5, 6],
+    ]
+    assert non_tensor_batch["json"].tolist() == [
+        {"rank": 0},
+        {"rank": 1},
+        {"rank": 2},
+    ]
+
+
 def test_unified_put_rejects_unknown_type() -> None:
     _store, transfer = make_transfer()
 
@@ -1830,7 +2990,7 @@ def test_unified_put_rejects_unknown_type() -> None:
 )
 def test_unified_dict_put_passes_store_config_to_writes(policy, config_attr, use_pool) -> None:
     store, transfer = make_transfer(buffer_pool=FakeBufferPool() if use_pool else None)
-    config = object()
+    config = GroupConfig(None)
     data = {"input_ids": np.arange(12, dtype=np.int64).reshape(4, 3)}
     kwargs = {"config": config}
     if policy is not None:
@@ -1842,7 +3002,10 @@ def test_unified_dict_put_passes_store_config_to_writes(policy, config_attr, use
     assert np.array_equal(result["input_ids"], data["input_ids"])
     configs = getattr(store, config_attr)
     assert configs
-    assert all(item is config for item in configs)
+    group_ids = _seen_group_ids(configs)
+    assert group_ids
+    assert all(ids == group_ids[0] for ids in group_ids)
+    assert config.group_ids is None
 
 
 def test_unified_dict_put_accepts_field_schemas() -> None:
@@ -1879,7 +3042,8 @@ def schema(codec: str, section: str, dtype: str | None = None) -> FieldSchema:
     result = transfer.get(ref, type="dict")
 
     assert np.array_equal(result["input_ids"], np.arange(2))
-    assert result["tokens"] == [[1, 2], None]
+    assert result["tokens"][0].tolist() == [1, 2]
+    assert result["tokens"][1] is None
     assert result["partition"] == [0, 1]
     assert result["response_lengths"] == [2, 0]
     assert result["global_batch_sizes"] == [2]
@@ -1989,8 +3153,24 @@ def test_dataproto_ref_handle_roundtrip_materializes_and_cleans_up() -> None:
     assert handle["stage_refs"] == {
         "rollout": {"manifest_key": ref.stage_refs["rollout"].manifest_key}
     }
+    assert handle["storage_group_id"] == ref._storage_group_id
     imported = import_dataproto_ref(handle)
     assert imported.stage_refs["rollout"].manifest == {}
+    assert imported._storage_group_id == ref._storage_group_id
+    legacy_handle = dict(handle)
+    legacy_handle["version"] = 1
+    legacy_handle.pop("storage_group_id")
+    assert import_dataproto_ref(legacy_handle)._storage_group_id is None
+    invalid_handle = dict(handle)
+    invalid_handle["storage_group_id"] = ""
+    with pytest.raises(ValueError, match="storage_group_id"):
+        import_dataproto_ref(invalid_handle)
+    transitional_v2_handle = dict(handle)
+    transitional_v2_handle["version"] = 2
+    assert (
+        import_dataproto_ref(transitional_v2_handle)._storage_group_id
+        == ref._storage_group_id
+    )
 
     result = transfer.get_dataproto(handle)
     assert np.array_equal(result["batch"]["input_ids"], input_ids)
@@ -2037,6 +3217,26 @@ def test_dataproto_ref_handle_rejects_unknown_field_stage() -> None:
         import_dataproto_ref(handle)
 
 
+@pytest.mark.parametrize(
+    ("path", "value"),
+    [
+        (("stage_refs", "default", "manifest_key"), ""),
+        (("field_index", "input_ids", "member"), ""),
+    ],
+)
+def test_dataproto_ref_handle_rejects_empty_locations(path, value) -> None:
+    _store, transfer = make_transfer()
+    ref = transfer.put_dataproto(SimpleDataProto(batch={"input_ids": np.arange(4)}))
+    handle = export_dataproto_ref(ref)
+    target = handle
+    for key in path[:-1]:
+        target = target[key]
+    target[path[-1]] = value
+
+    with pytest.raises(ValueError, match="non-empty"):
+        import_dataproto_ref(handle)
+
+
 def test_dataproto_helper_appends_stage_fields_without_rewriting_existing() -> None:
     store, transfer = make_transfer()
     rollout = SimpleDataProto(
@@ -2899,7 +4099,11 @@ def test_dataproto_helper_typed_ragged_uses_multi_buffer_put() -> None:
 
     assert ref.encoded_non_tensor["tokens"]["codec"] == "typed_ragged"
     tokens = result["non_tensor_batch"]["tokens"].tolist()
-    assert tokens == [[1, 2], None, [3, 4, 5]]
+    assert [None if row is None else row.tolist() for row in tokens] == [
+        [1, 2],
+        None,
+        [3, 4, 5],
+    ]
     assert rows[0].nbytes + rows[2].nbytes in pool.acquire_sizes
 
 
@@ -2933,7 +4137,11 @@ def test_dataproto_helper_typed_ragged_fast_copy_put() -> None:
     result = transfer.get_dataproto(ref)
 
     tokens = result["non_tensor_batch"]["tokens"].tolist()
-    assert tokens == [[1, 2], None, [3, 4, 5]]
+    assert [None if row is None else row.tolist() for row in tokens] == [
+        [1, 2],
+        None,
+        [3, 4, 5],
+    ]
     assert store.batch_put_from_calls > 0
     assert rows[0].nbytes + rows[2].nbytes in pool.acquire_sizes
 
@@ -2992,6 +4200,135 @@ def test_dataproto_helper_typed_ragged_zero_copy_rejects_source_buffers() -> Non
         )
 
 
+def test_typed_ragged_packs_ndarray_rows_contiguously() -> None:
+    _store, transfer = make_transfer()
+    rows = [
+        np.asarray(7, dtype=np.int32),
+        np.arange(3, dtype=np.int32),
+        None,
+        np.arange(4, dtype=np.int32).reshape(2, 2),
+        np.arange(6, dtype=np.int32).reshape(2, 3),
+    ]
+
+    ref = transfer.put(
+        {"values": rows},
+        field_schemas={
+            "values": FieldSchema(
+                codec="typed_ragged",
+                metadata={"section": "non_tensor_batch"},
+            )
+        },
+        type="dict",
+    )
+    result = transfer.get(ref, type="dict")
+    view = transfer.dataproto_manifest_view(ref)
+
+    encoded = ref.encoded_non_tensor["values"]
+    assert encoded["codec"] == "typed_ragged"
+    assert encoded["metadata"]["physical_layout"] == "contiguous_flat"
+    assert view["non_tensor_fields"]["values"]["spec"]["payload_specs"]["data"][
+        "shape"
+    ] == [14]
+    assert [
+        None if row is None else row.tolist() for row in result["values"]
+    ] == [
+        None if row is None else row.tolist() for row in rows
+    ]
+    assert all(
+        row is None or isinstance(row, np.ndarray) for row in result["values"]
+    )
+    assert result["values"][0].shape == ()
+    assert [row.dtype for row in result["values"] if row is not None] == [
+        np.dtype(np.int32)
+    ] * 4
+    gathered = transfer.get_dataproto(
+        ref, non_tensor_fields=["values"], rows=[4, 2, 0]
+    )
+    assert [
+        None if row is None else row.tolist()
+        for row in gathered["non_tensor_batch"]["values"]
+    ] == [
+        rows[4].tolist(),
+        None,
+        rows[0].tolist(),
+    ]
+    assert gathered["non_tensor_batch"]["values"][2].shape == ()
+
+
+def _typed_ragged_payload_array(
+    payload: dict[str, object], dtype: np.dtype
+) -> np.ndarray:
+    data = payload["data"]
+    arrays = getattr(data, "arrays", None)
+    if arrays is not None:
+        flat_arrays = [
+            np.asarray(array, dtype=dtype).reshape(-1) for array in arrays
+        ]
+        if not flat_arrays:
+            return np.asarray([], dtype=dtype)
+        return np.concatenate(flat_arrays)
+    return np.concatenate([np.frombuffer(buf, dtype=dtype) for buf in data.buffers])
+
+def test_typed_ragged_fast_decodes_equal_shape_ndarray_views() -> None:
+    rows = [np.arange(6, dtype=np.int32).reshape(2, 3) + i * 10 for i in range(3)]
+    payload, metadata = sos._encode_typed_ragged_values(rows, np.dtype(np.int32))
+    data = _typed_ragged_payload_array(payload, np.dtype(np.int32))
+
+    decoded = sos._decode_typed_ragged_values({**payload, "data": data}, 3, metadata)
+
+    assert metadata["physical_layout"] == "contiguous_flat"
+    assert all(isinstance(row, np.ndarray) for row in decoded)
+    assert all(np.shares_memory(row, data) for row in decoded)
+    assert [row.tolist() for row in decoded] == [row.tolist() for row in rows]
+
+
+def test_typed_ragged_single_ndarray_row_uses_general_layout() -> None:
+    rows = [np.arange(6, dtype=np.int32).reshape(2, 3)]
+
+    assert sos._encode_typed_ragged_regular_ndarray_rows(
+        rows, np.dtype(np.int32)
+    ) is None
+    payload, metadata = sos._encode_typed_ragged_values(rows, np.dtype(np.int32))
+    data = _typed_ragged_payload_array(payload, np.dtype(np.int32))
+
+    decoded = sos._decode_typed_ragged_values({**payload, "data": data}, 1, metadata)
+
+    assert metadata["physical_layout"] == "contiguous_flat"
+    assert isinstance(decoded[0], np.ndarray)
+    assert np.shares_memory(decoded[0], data)
+    assert decoded[0].tolist() == rows[0].tolist()
+
+
+def test_typed_ragged_equal_shape_rows_with_nulls_use_general_layout() -> None:
+    rows = [
+        np.arange(6, dtype=np.int32).reshape(2, 3),
+        None,
+        np.arange(6, 12, dtype=np.int32).reshape(2, 3),
+    ]
+
+    assert sos._encode_typed_ragged_regular_ndarray_rows(
+        rows, np.dtype(np.int32)
+    ) is None
+    payload, metadata = sos._encode_typed_ragged_values(rows, np.dtype(np.int32))
+    data = _typed_ragged_payload_array(payload, np.dtype(np.int32))
+
+    decoded = sos._decode_typed_ragged_values({**payload, "data": data}, 3, metadata)
+
+    assert metadata["physical_layout"] == "contiguous_flat"
+    assert decoded[1] is None
+    assert all(
+        row is None or isinstance(row, np.ndarray) for row in decoded
+    )
+    assert all(
+        row is None or np.shares_memory(row, data) for row in decoded
+    )
+    assert [None if row is None else row.tolist() for row in decoded] == [
+        rows[0].tolist(),
+        None,
+        rows[2].tolist(),
+    ]
+
+
 def test_dataproto_helper_rejects_unsupported_object_non_tensor() -> None:
     _store, transfer = make_transfer()
     data = SimpleDataProto(
@@ -3026,6 +4363,7 @@ def test_dataproto_helper_ragged_tensor_non_tensor_roundtrip() -> None:
     result = transfer.get_dataproto(ref)
 
     assert ref.encoded_non_tensor["ragged"]["codec"] == "ragged_tensor"
+    assert ref.encoded_non_tensor["ragged"]["metadata"]["dtype"] == "torch.float32"
     actual = result["non_tensor_batch"]["ragged"]
     assert torch.equal(actual[0], ragged[0])
     assert actual[1] is None
@@ -3040,6 +4378,80 @@ def test_dataproto_helper_ragged_tensor_non_tensor_roundtrip() -> None:
     with pytest.raises(ValueError, match="mixed tensor dtype"):
         transfer.put_dataproto(SimpleDataProto(non_tensor_batch={"ragged": mixed}))
 
+    bfloat = np.empty(1, dtype=object)
+    bfloat[0] = torch.zeros(1, dtype=torch.bfloat16)
+    with pytest.raises(ValueError, match="bfloat16"):
+        transfer.put_dataproto(SimpleDataProto(non_tensor_batch={"ragged": bfloat}))
+
+
+def test_dataproto_helper_jagged_nested_batch_tensor_roundtrip() -> None:
+    torch = pytest.importorskip("torch")
+    _store, transfer = make_transfer()
+    rows = [
+        torch.arange(2, dtype=torch.int64),
+        torch.arange(10, 14, dtype=torch.int64),
+        torch.arange(20, 21, dtype=torch.int64),
+    ]
+    nested = torch.nested.as_nested_tensor(rows, layout=torch.jagged)
+
+    ref = transfer.put_dataproto(SimpleDataProto(batch={"tokens": nested}))
+    view = transfer.dataproto_manifest_view(ref)
+
+    field_spec = view["batch_fields"]["tokens"]["spec"]
+    assert field_spec["encoding"] == "torch_tensor"
+    assert field_spec["dtype"] == "torch.int64"
+    assert field_spec["nested"] is True
+    assert field_spec["format"] in {"tensor_parts", "torch_save"}
+    if field_spec["format"] == "tensor_parts":
+        assert len(field_spec["part_bytes"]) == 2
+
+    for selection, expected_rows in (
+        (None, rows),
+        (slice(1, 3), rows[1:3]),
+        ([2, 0], [rows[2], rows[0]]),
+        ([], []),
+    ):
+        result = transfer.get_dataproto(ref, rows=selection)["batch"]["tokens"]
+        assert result.is_nested
+        assert result.layout == torch.jagged
+        assert len(result) == len(expected_rows)
+        for actual, expected in zip(result.unbind(), expected_rows):
+            assert torch.equal(actual, expected)
+
+    matrix_rows = [
+        torch.arange(6, dtype=torch.int64).reshape(2, 3),
+        torch.arange(10, dtype=torch.int64).reshape(2, 5),
+    ]
+    matrix = torch.nested.as_nested_tensor(matrix_rows, layout=torch.jagged)
+    matrix_ref = transfer.put_dataproto(SimpleDataProto(batch={"position_ids": matrix}))
+    matrix_result = transfer.get_dataproto(matrix_ref)["batch"]["position_ids"]
+
+    assert matrix_result.is_nested
+    assert matrix_result.layout == torch.jagged
+    assert matrix_result._ragged_idx == 2
+    for actual, expected in zip(matrix_result.unbind(), matrix_rows):
+        assert torch.equal(actual, expected)
+
+
+def test_dataproto_helper_refreshes_stale_jagged_sequence_cache(monkeypatch) -> None:
+    torch = pytest.importorskip("torch")
+    monkeypatch.setattr(sos, "_has_tensor_codec_helpers", lambda: False)
+    _store, transfer = make_transfer()
+    offsets = torch.arange(0, 513, 64)
+    nested = torch.nested.nested_tensor_from_jagged(
+        torch.arange(512, dtype=torch.float32),
+        offsets=offsets,
+        min_seqlen=512,
+        max_seqlen=512,
+    )
+
+    ref = transfer.put_dataproto(SimpleDataProto(batch={"log_probs": nested}))
+    result = transfer.get_dataproto(ref)["batch"]["log_probs"]
+
+    assert result.offsets().tolist() == offsets.tolist()
+    assert result._min_seqlen == result._max_seqlen == 64
+    assert torch.nested.to_padded_tensor(result, 0).shape == (8, 64)
+
 
 def _assert_tensor_object_equal(actual, expected) -> None:
     torch = pytest.importorskip("torch")
@@ -3170,11 +4582,13 @@ def test_dataproto_helper_dict_of_native_object_leaves_uses_recursive_codec() ->
     assert ref.encoded_non_tensor["samples"]["codec"] == "structured_recursive"
     assert actual[0]["media"] == [b"a", b"bc"]
     assert actual[0]["blob"] == b"payload-0"
-    assert actual[0]["scores"] == [1, 2]
+    assert isinstance(actual[0]["scores"], np.ndarray)
+    assert actual[0]["scores"].tolist() == [1, 2]
     assert actual[0]["label"] == "x"
     assert actual[1]["media"] == []
     assert actual[1]["blob"] == b"payload-1"
-    assert actual[1]["scores"] == [3]
+    assert isinstance(actual[1]["scores"], np.ndarray)
+    assert actual[1]["scores"].tolist() == [3]
     assert actual[1]["label"] == "y"
     assert actual[2] == {"label": "missing-native"}
     assert actual[3] is None
diff --git a/mooncake-wheel/tests/test_tensor_read_snapshot.py b/mooncake-wheel/tests/test_tensor_read_snapshot.py
new file mode 100644
index 0000000000..cc81c8ed6f
--- /dev/null
+++ b/mooncake-wheel/tests/test_tensor_read_snapshot.py
@@ -0,0 +1,129 @@
+"""RealClient tensor read regressions; requires a running Mooncake master."""
+
+import os
+import time
+import unittest
+import uuid
+
+try:
+    import torch
+except ImportError:
+    torch = None
+
+from mooncake.store import MooncakeDistributedStore
+
+
+class TensorAfterMetadata:
+    """Run a callback when the binding inspects the destination after its read."""
+
+    def __init__(self, tensor, callback):
+        self.tensor = tensor
+        self.callback = callback
+
+    def is_contiguous(self):
+        callback, self.callback = self.callback, None
+        if callback is not None:
+            callback()
+        return self.tensor.is_contiguous()
+
+    def __getattr__(self, name):
+        return getattr(self.tensor, name)
+
+
+@unittest.skipIf(torch is None, "PyTorch is unavailable")
+class TensorReadSnapshotTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.store = MooncakeDistributedStore()
+        rc = cls.store.setup(
+            os.getenv("LOCAL_HOSTNAME", "localhost"),
+            os.getenv("MC_METADATA_SERVER", "P2PHANDSHAKE"),
+            32 * 1024 * 1024,
+            16 * 1024 * 1024,
+            os.getenv("PROTOCOL", "tcp"),
+            os.getenv("DEVICE_NAME", ""),
+            os.getenv("MASTER_SERVER", "127.0.0.1:50051"),
+        )
+        if rc != 0:
+            raise RuntimeError(f"Store setup failed: {rc}")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.store.close()
+
+    def test_upsert_between_metadata_and_payload(self):
+        devices = ["cpu"] + (["cuda"] if torch.cuda.is_available() else [])
+        for device in devices:
+            for batched in (False, True):
+                with self.subTest(device=device, batched=batched):
+                    key = f"tensor_snapshot_{uuid.uuid4().hex}"
+                    original = torch.arange(8, dtype=torch.float32)
+                    replacement = original + 100
+                    destination = torch.full_like(original, -1, device=device)
+                    size = destination.numel() * destination.element_size()
+                    self.assertEqual(self.store.put_tensor(key, original), 0)
+                    self.assertEqual(
+                        self.store.register_buffer(destination.data_ptr(), size), 0
+                    )
+                    upserts = []
+
+                    def upsert():
+                        upserts.append(self.store.upsert_tensor(key, replacement))
+
+                    proxy = TensorAfterMetadata(destination, upsert)
+                    try:
+                        if batched:
+                            result = self.store.batch_get_tensor_into_cuda(
+                                [key], [proxy]
+                            )
+                            self.assertEqual(result, [size])
+                        else:
+                            result = self.store.get_tensor_into_cuda(key, proxy)
+                            self.assertEqual(result, size)
+                        self.assertEqual(upserts, [0])
+                        self.assertTrue(torch.equal(destination.cpu(), original))
+                        self.assertTrue(
+                            torch.equal(self.store.get_tensor(key), replacement)
+                        )
+                    finally:
+                        self.store.unregister_buffer(destination.data_ptr())
+
+    def test_batch_preserves_missing_key_error_and_valid_item(self):
+        key = f"tensor_snapshot_{uuid.uuid4().hex}"
+        original = torch.arange(8, dtype=torch.float32)
+        destinations = [torch.empty_like(original), torch.empty_like(original)]
+        size = original.numel() * original.element_size()
+        self.assertEqual(self.store.put_tensor(key, original), 0)
+        for destination in destinations:
+            self.assertEqual(
+                self.store.register_buffer(destination.data_ptr(), size), 0
+            )
+        try:
+            result = self.store.batch_get_tensor_into_cuda(
+                [key + "_missing", key], destinations
+            )
+            # OBJECT_NOT_FOUND from the metadata query must survive the wrapper.
+            self.assertEqual(result, [-704, size])
+            self.assertTrue(torch.equal(destinations[1], original))
+        finally:
+            for destination in destinations:
+                self.store.unregister_buffer(destination.data_ptr())
+
+    def test_expired_payload_snapshot_preserves_lease_error(self):
+        key = f"tensor_snapshot_{uuid.uuid4().hex}"
+        original = torch.arange(8, dtype=torch.float32)
+        destination = torch.empty_like(original)
+        size = original.numel() * original.element_size()
+        self.assertEqual(self.store.put_tensor(key, original), 0)
+        self.assertEqual(self.store.register_buffer(destination.data_ptr(), size), 0)
+        # Match the master's configured TTL, as in test_put_get_tensor.py.
+        ttl_seconds = int(os.getenv("DEFAULT_KV_LEASE_TTL", "5000")) / 1000
+        proxy = TensorAfterMetadata(destination, lambda: time.sleep(ttl_seconds + 0.1))
+        try:
+            self.assertEqual(self.store.get_tensor_into_cuda(key, proxy), -707)
+        finally:
+            self.store.unregister_buffer(destination.data_ptr())
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-wheel/tests/test_testpypi_wheel_gate.py b/mooncake-wheel/tests/test_testpypi_wheel_gate.py
new file mode 100644
index 0000000000..d80a6f7e8a
--- /dev/null
+++ b/mooncake-wheel/tests/test_testpypi_wheel_gate.py
@@ -0,0 +1,196 @@
+"""Focused tests for the TestPyPI pre-release wheel gate."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from zipfile import ZipFile
+
+import pytest
+from packaging.version import Version
+
+
+def _load_gate_module():
+    repository = Path(__file__).resolve().parents[2]
+    script = repository / "scripts" / "ci" / "testpypi_wheel_gate.py"
+    spec = importlib.util.spec_from_file_location("testpypi_wheel_gate", script)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+gate = _load_gate_module()
+
+
+def _wheel(package: str, version: str, python_tag: str, architecture: str) -> str:
+    distribution = package.replace("-", "_")
+    return (
+        f"{distribution}-{version}-{python_tag}-{python_tag}-"
+        f"manylinux_2_28_{architecture}.whl"
+    )
+
+
+def _complete_matrix(version: str) -> list[str]:
+    return [
+        _wheel(package, version, python_tag, architecture)
+        for package in gate.CORE_PACKAGES
+        for python_tag in gate.PYTHON_TAGS
+        for architecture in gate.ARCHITECTURES
+    ]
+
+
+def _write_wheel(
+    directory: Path,
+    package: str,
+    filename_version: str,
+    python_tag: str,
+    architecture: str,
+    *,
+    metadata_version: str | None = None,
+) -> Path:
+    path = directory / _wheel(package, filename_version, python_tag, architecture)
+    dist_info = f"{package.replace('-', '_')}-{filename_version}.dist-info"
+    with ZipFile(path, "w") as wheel:
+        wheel.writestr(
+            f"{dist_info}/METADATA",
+            "\n".join(
+                (
+                    "Metadata-Version: 2.1",
+                    f"Name: {package}",
+                    f"Version: {metadata_version or filename_version}",
+                    "",
+                )
+            ),
+        )
+    return path
+
+
+def _write_complete_matrix(directory: Path, version: str) -> list[Path]:
+    return [
+        _write_wheel(directory, package, version, python_tag, architecture)
+        for package in gate.CORE_PACKAGES
+        for python_tag in gate.PYTHON_TAGS
+        for architecture in gate.ARCHITECTURES
+    ]
+
+
+def _artifacts(
+    wheels: list[Path],
+    hashes: dict[str, str | None] | None = None,
+) -> list[gate.IndexedArtifact]:
+    hashes = hashes or {}
+    return [
+        gate.IndexedArtifact(
+            wheel.name,
+            hashes[wheel.name] if wheel.name in hashes else gate._sha256(wheel),
+        )
+        for wheel in wheels
+    ]
+
+
+def test_prerelease_tag_normalization_rejects_non_public_versions() -> None:
+    assert str(gate.normalize_prerelease_tag("v1.2.0-rc1")) == "1.2.0rc1"
+
+    for tag in ("1.2.0-rc1", "v1.2.0", "v1.2.0rc1+local", "vnot-a-version"):
+        with pytest.raises(gate.GateError):
+            gate.normalize_prerelease_tag(tag)
+
+
+def test_complete_matrix_requires_exact_version_and_all_24_targets() -> None:
+    filenames = _complete_matrix("1.2.0rc1")
+
+    gate.validate_wheel_set(filenames, Version("1.2.0-rc1"))
+
+    with pytest.raises(gate.GateError, match="missing targets"):
+        gate.validate_wheel_set(filenames[:-1], Version("1.2.0rc1"))
+
+    wrong_version = [*filenames[:-1], filenames[-1].replace("1.2.0rc1", "1.2.0rc2")]
+    with pytest.raises(gate.GateError, match="has version 1.2.0rc2"):
+        gate.validate_wheel_set(wrong_version, Version("1.2.0rc1"))
+
+    equivalent_version = _complete_matrix("1.2rc1")
+    with pytest.raises(gate.GateError, match="has version 1.2rc1"):
+        gate.validate_wheel_set(equivalent_version, Version("1.2.0rc1"))
+
+
+def test_local_validation_reads_each_wheel_metadata(tmp_path: Path) -> None:
+    _write_complete_matrix(tmp_path, "1.2.0rc1")
+    gate.validate_local(tmp_path, Version("1.2.0rc1"))
+
+    package = gate.CORE_PACKAGES[-1]
+    for bad_version in ("1.2.0rc2", "1.2rc1"):
+        _write_wheel(
+            tmp_path,
+            package,
+            "1.2.0rc1",
+            gate.PYTHON_TAGS[-1],
+            gate.ARCHITECTURES[-1],
+            metadata_version=bad_version,
+        )
+        with pytest.raises(gate.GateError, match=f"metadata version {bad_version}"):
+            gate.validate_local(tmp_path, Version("1.2.0rc1"))
+
+
+def test_upload_state_accepts_only_hash_matching_partial_uploads(
+    tmp_path: Path,
+) -> None:
+    wheels = _write_complete_matrix(tmp_path, "1.2.0rc1")
+    existing = wheels[:7]
+
+    gate.validate_upload_state(
+        tmp_path,
+        Version("1.2.0rc1"),
+        fetcher=lambda _index_url: _artifacts(existing),
+    )
+
+    changed = existing[0]
+    with pytest.raises(gate.GateError, match="refusing to mix builds"):
+        gate.validate_upload_state(
+            tmp_path,
+            Version("1.2.0rc1"),
+            fetcher=lambda _index_url: _artifacts([changed], {changed.name: "0" * 64}),
+        )
+
+
+def test_upload_state_rejects_unverifiable_or_unexpected_artifacts(
+    tmp_path: Path,
+) -> None:
+    wheels = _write_complete_matrix(tmp_path, "1.2.0rc1")
+    existing = wheels[0]
+
+    with pytest.raises(gate.GateError, match="did not advertise a SHA-256"):
+        gate.validate_upload_state(
+            tmp_path,
+            Version("1.2.0rc1"),
+            fetcher=lambda _index_url: _artifacts([existing], {existing.name: None}),
+        )
+
+    unexpected = existing.name.replace("x86_64", "ppc64le")
+    with pytest.raises(gate.GateError, match="unexpected artifact"):
+        gate.validate_upload_state(
+            tmp_path,
+            Version("1.2.0rc1"),
+            fetcher=lambda _index_url: [gate.IndexedArtifact(unexpected, "0" * 64)],
+        )
+
+
+def test_upload_state_waits_for_the_complete_hash_matching_matrix(
+    tmp_path: Path,
+) -> None:
+    wheels = _write_complete_matrix(tmp_path, "1.2.0rc1")
+    responses = iter((_artifacts(wheels[:-1]), _artifacts(wheels)))
+    sleeps = []
+
+    gate.wait_for_upload_state(
+        tmp_path,
+        gate.DEFAULT_INDEX_URL,
+        Version("1.2.0rc1"),
+        attempts=3,
+        initial_delay=1,
+        max_delay=4,
+        fetcher=lambda _index_url: next(responses),
+        sleeper=sleeps.append,
+    )
+
+    assert sleeps == [1]
diff --git a/mooncake-wheel/tests/test_transfer_engine_flagcx_source.py b/mooncake-wheel/tests/test_transfer_engine_flagcx_source.py
new file mode 100644
index 0000000000..c5e6ca8991
--- /dev/null
+++ b/mooncake-wheel/tests/test_transfer_engine_flagcx_source.py
@@ -0,0 +1,20 @@
+from pathlib import Path
+import unittest
+
+
+class TransferEngineFlagCxSourceTest(unittest.TestCase):
+    def test_python_transfer_engine_installs_flagcx_transport(self):
+        source_path = (
+            Path(__file__).resolve().parents[2]
+            / "mooncake-integration"
+            / "transfer_engine"
+            / "transfer_engine_py.cpp"
+        )
+        source = source_path.read_text()
+
+        self.assertIn('proto == "flagcx"', source)
+        self.assertIn('installTransport("flagcx", nullptr)', source)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-wheel/tests/test_weight_snapshot_api.py b/mooncake-wheel/tests/test_weight_snapshot_api.py
new file mode 100644
index 0000000000..4945e52cdb
--- /dev/null
+++ b/mooncake-wheel/tests/test_weight_snapshot_api.py
@@ -0,0 +1,54 @@
+"""Installed-wheel API checks for model-weight snapshot entry points."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+import mooncake.store as native_store
+from mooncake.reshard.weight.store import WeightStoreWriter
+
+
+class TestWeightSnapshotApi(unittest.TestCase):
+    def test_native_store_forwards_snapshot_factory(self) -> None:
+        store = native_store.MooncakeDistributedStore()
+        snapshot = object()
+        adapter = object()
+        expected = object()
+
+        with patch(
+            "mooncake.reshard.weight.store.begin_weight_snapshot",
+            return_value=expected,
+        ) as factory:
+            result = store.begin_weight_snapshot(snapshot, adapter)
+
+        self.assertIs(result, expected)
+        self.assertEqual(factory.call_args.args[1:], (snapshot, adapter))
+        self.assertIsInstance(
+            factory.call_args.args[0], native_store.MooncakeDistributedStore
+        )
+
+    def test_weight_store_writer_replaces_parallelism_api(self) -> None:
+        store = native_store.MooncakeDistributedStore()
+
+        self.assertTrue(callable(store.begin_weight_snapshot))
+        self.assertTrue(issubclass(WeightStoreWriter, object))
+
+        for name in (
+            "get_tensor_with_parallelism",
+            "batch_get_tensor_with_parallelism",
+            "get_tensor_with_parallelism_into",
+            "batch_get_tensor_with_parallelism_into",
+            "put_tensor_with_parallelism",
+            "batch_put_tensor_with_parallelism",
+            "put_tensor_with_parallelism_from",
+            "batch_put_tensor_with_parallelism_from",
+            "upsert_tensor_with_parallelism",
+            "upsert_tensor_with_parallelism_from",
+            "batch_upsert_tensor_with_parallelism",
+            "batch_upsert_tensor_with_parallelism_from",
+        ):
+            self.assertFalse(hasattr(store, name), name)
+
+        for name in ("ParallelAxis", "TensorParallelism", "ReadTarget"):
+            self.assertFalse(hasattr(native_store, name), name)
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000000..cf7cf42c87
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,115 @@
+[build-system]
+requires = [
+    "scikit-build-core>=1.0",
+    "pybind11>=2.13",
+    "numpy>=1.24",
+    # Mooncake PG still builds its Torch ABI extensions through setup.py.
+    "setuptools>=61",
+    # Multi-ABI PG builds install the requested Torch wheels at build time.
+    "pip>=23",
+]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "mooncake-transfer-engine"
+version = "0.3.12.post1"
+description = "A KVCache-centric disaggregated architecture for large-scale LLM inference and training."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE-APACHE" }
+authors = [
+    { name = "Mooncake Authors" },
+]
+dependencies = [
+    "aiohttp",
+    "msgpack",
+    "requests",
+]
+keywords = ["mooncake", "transfer engine", "kv cache", "llm inference", "rdma"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: GPU :: NVIDIA CUDA",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: C++",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "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",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Distributed Computing",
+]
+
+[project.optional-dependencies]
+structured = [
+    "numpy",
+    "pillow",
+]
+vllm = [
+    "fastapi",
+    "httpx",
+    "msgspec",
+    "numpy",
+    "pyzmq",
+    "torch",
+    "vllm",
+]
+administration = [
+    "paramiko",
+]
+hardware = [
+    "torch",
+]
+dev = [
+    "build",
+    "cmake-format==0.6.13",
+    "codespell==2.2.6",
+    "pre-commit==3.7.1",
+    "pyright==1.1.411",
+    "pytest",
+    "ruff==0.6.9",
+    "tomli; python_version < '3.11'",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/kvcache-ai/Mooncake"
+Documentation = "https://kvcache-ai.github.io/Mooncake"
+Source = "https://github.com/kvcache-ai/Mooncake"
+Issues = "https://github.com/kvcache-ai/Mooncake/issues"
+Blog = "https://kvcache.ai/blog"
+Changelog = "https://github.com/kvcache-ai/Mooncake/releases"
+Slack = "https://join.slack.com/t/mooncake-project/shared_invite/zt-3qx4x35ea-zSSTqTHItHJs9SCoXLOSPA"
+
+[project.scripts]
+mooncake_master = "mooncake.cli:main"
+mooncake_client = "mooncake.cli_client:main"
+transfer_engine_bench = "mooncake.cli_bench:main"
+mooncake_http_metadata_server = "mooncake.http_metadata_server:main"
+mc_store_rest_server = "mooncake.mooncake_store_service:sync_main"
+transfer_engine_topology_dump = "mooncake.transfer_engine_topology_dump:main"
+
+[tool.scikit-build]
+minimum-version = "build-system.requires"
+build-dir = "build/python/{wheel_tag}"
+wheel.packages = ["python/mooncake"]
+install.components = ["python"]
+sdist.include = [
+    "extern/yalantinglibs/**",
+    "!extern/yalantinglibs/.git",
+]
+sdist.exclude = ["extern/yalantinglibs/.git"]
+
+[tool.scikit-build.cmake.define]
+BUILD_BENCHMARK = false
+BUILD_UNIT_TESTS = false
+USE_CUDA = false
+WITH_EP = false
+WITH_P2P_STORE = false
+WITH_STORE_GO = false
+WITH_STORE_RUST = false
diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt
new file mode 100644
index 0000000000..6cb7b26ebf
--- /dev/null
+++ b/python/CMakeLists.txt
@@ -0,0 +1,32 @@
+find_package(
+  Python3
+  COMPONENTS Interpreter Development.Module NumPy
+  REQUIRED)
+find_package(Threads REQUIRED)
+
+# This extension remains in its legacy source location until its subsystem is
+# migrated. CMake installs it directly into the backend-owned wheel tree.
+python3_add_library(
+  _fast_copy MODULE WITH_SOABI
+  "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/_fast_copy.c")
+target_link_libraries(_fast_copy PRIVATE Python3::NumPy Threads::Threads)
+target_compile_options(_fast_copy PRIVATE -O2)
+install(TARGETS _fast_copy LIBRARY DESTINATION mooncake COMPONENT python)
+
+# Phase 1 consumes unmigrated modules from their authoritative source locations.
+# Nothing is copied into python/mooncake or another tracked source directory.
+# These rules disappear subsystem by subsystem during Phase 2.
+install(
+  DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-wheel/mooncake/"
+  DESTINATION mooncake
+  COMPONENT python
+  FILES_MATCHING
+  PATTERN "*.py"
+  PATTERN "__init__.py" EXCLUDE)
+install(
+  DIRECTORY
+    "${CMAKE_CURRENT_SOURCE_DIR}/../mooncake-reshard/python/mooncake/reshard/"
+  DESTINATION mooncake/reshard
+  COMPONENT python
+  FILES_MATCHING
+  PATTERN "*.py")
diff --git a/python/mooncake/__init__.py b/python/mooncake/__init__.py
new file mode 100644
index 0000000000..4169a5edc3
--- /dev/null
+++ b/python/mooncake/__init__.py
@@ -0,0 +1,9 @@
+"""Public Python package for Mooncake."""
+
+from pkgutil import extend_path
+
+from mooncake.buffer_pool import BufferPool, RegisteredBufferPool
+
+__path__ = extend_path(__path__, __name__)
+
+__all__ = ["BufferPool", "RegisteredBufferPool"]
diff --git a/python/mooncake/_administration.py b/python/mooncake/_administration.py
new file mode 100644
index 0000000000..9dbc03816a
--- /dev/null
+++ b/python/mooncake/_administration.py
@@ -0,0 +1,15 @@
+"""Optional dependencies for the SSD administration tools."""
+
+
+def require_paramiko():
+    """Load SSH support only when an administration operation needs it."""
+    try:
+        import paramiko
+    except ModuleNotFoundError as exc:
+        if exc.name != "paramiko":
+            raise
+        raise RuntimeError(
+            "SSH administration requires paramiko. Install it with: "
+            "python -m pip install 'mooncake-transfer-engine[administration]'"
+        ) from None
+    return paramiko
diff --git a/python/mooncake/_launcher.py b/python/mooncake/_launcher.py
new file mode 100644
index 0000000000..092a97c7ab
--- /dev/null
+++ b/python/mooncake/_launcher.py
@@ -0,0 +1,40 @@
+"""
+Locate and launch native binaries bundled with the Mooncake wheel.
+
+The CLI entry points in ``mooncake.cli`` / ``mooncake.cli_client`` /
+``mooncake.cli_bench`` are Python shims that ``exec`` a compiled C++ binary
+shipped inside the wheel. The binary is resolved through
+:func:`importlib.resources.files` so it stays agnostic to where the package is
+installed, and is made executable on the fly because ``setuptools``
+``package-data`` does not preserve the execute bit.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from importlib.resources import files
+
+
+def locate(name: str) -> str:
+    """
+    Return the absolute path of a native binary bundled in this package.
+
+    The named binary must live next to the package (``mooncake/<name>``). It is
+    chmodded to be executable if needed. A clear :class:`FileNotFoundError` is
+    raised when the binary is absent instead of silently falling back to
+    ``PATH`` (which could run a mismatched system build).
+    """
+    path = files("mooncake") / name
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"{name!r} not found in the mooncake package; "
+            "reinstall the package so the native CLI binary is bundled"
+        )
+    file_path = str(path)
+    if not os.access(file_path, os.X_OK):
+        os.chmod(
+            file_path,
+            os.stat(file_path).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH,
+        )
+    return file_path
diff --git a/mooncake-integration/store/async_store.py b/python/mooncake/async_store.py
similarity index 74%
rename from mooncake-integration/store/async_store.py
rename to python/mooncake/async_store.py
index 67f1d900f3..e96c81cc56 100644
--- a/mooncake-integration/store/async_store.py
+++ b/python/mooncake/async_store.py
@@ -1,16 +1,23 @@
 import asyncio
 import functools
+
 from mooncake.store import MooncakeDistributedStore
 
+
 class MooncakeDistributedStoreAsync(MooncakeDistributedStore):
     def __getattr__(self, name: str):
         if not name.startswith("async_"):
-            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no attribute '{name}'"
+            )
 
         sync_method_name = name[6:]
 
         if not hasattr(self, sync_method_name):
-            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}' (nor '{sync_method_name}')")
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no attribute '{name}' "
+                f"(nor '{sync_method_name}')"
+            )
 
         sync_method = getattr(self, sync_method_name)
 
@@ -29,4 +36,4 @@ async def wrapper(*args, **kwargs):
             func = functools.partial(sync_method, *args, **kwargs)
             return await loop.run_in_executor(None, func)
 
-        return wrapper
\ No newline at end of file
+        return wrapper
diff --git a/mooncake-wheel/mooncake/buffer_pool.py b/python/mooncake/buffer_pool.py
similarity index 100%
rename from mooncake-wheel/mooncake/buffer_pool.py
rename to python/mooncake/buffer_pool.py
diff --git a/python/mooncake/cli.py b/python/mooncake/cli.py
new file mode 100644
index 0000000000..cfdef22504
--- /dev/null
+++ b/python/mooncake/cli.py
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""
+Minimal CLI module for mooncake_master.
+"""
+
+import os
+import sys
+
+from mooncake._launcher import locate
+
+
+def main():
+    """
+    Main entry point for the mooncake_master command.
+    Simply runs the mooncake_master binary with all arguments passed through.
+    """
+    bin_path = locate("mooncake_master")
+
+    # Preserve the CLI process ID so callers can reliably stop the server.
+    os.execv(bin_path, [bin_path] + sys.argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/mooncake-wheel/mooncake/cli_bench.py b/python/mooncake/cli_bench.py
similarity index 52%
rename from mooncake-wheel/mooncake/cli_bench.py
rename to python/mooncake/cli_bench.py
index f4bf27d766..421ee1400d 100644
--- a/mooncake-wheel/mooncake/cli_bench.py
+++ b/python/mooncake/cli_bench.py
@@ -3,10 +3,10 @@
 Minimal CLI module for transfer_engine_bench.
 """
 
-import os
-import stat
-import sys
 import subprocess
+import sys
+
+from mooncake._launcher import locate
 
 
 def main():
@@ -14,14 +14,7 @@ def main():
     Main entry point for the transfer_engine_bench command.
     Simply runs the transfer_engine_bench binary with all arguments passed through.
     """
-    # Get the path to the transfer_engine_bench binary
-    package_dir = os.path.dirname(os.path.abspath(__file__))
-    bin_path = os.path.join(package_dir, "transfer_engine_bench")
-
-    # Make sure the binary is executable
-    if not os.access(bin_path, os.X_OK):
-        st = os.stat(bin_path)
-        os.chmod(bin_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    bin_path = locate("transfer_engine_bench")
 
     # Run the binary with all arguments passed through
     return subprocess.call([bin_path] + sys.argv[1:])
diff --git a/python/mooncake/cli_client.py b/python/mooncake/cli_client.py
new file mode 100644
index 0000000000..226c943fad
--- /dev/null
+++ b/python/mooncake/cli_client.py
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""
+Minimal CLI module for mooncake_client.
+"""
+
+import os
+import sys
+
+from mooncake._launcher import locate
+
+
+def main():
+    """
+    Main entry point for the mooncake_client command.
+    Simply runs the mooncake_client binary with all arguments passed through.
+    """
+    bin_path = locate("mooncake_client")
+
+    # Preserve the CLI process ID so callers can reliably stop the client.
+    os.execv(bin_path, [bin_path] + sys.argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/python/mooncake/ep.py b/python/mooncake/ep.py
new file mode 100644
index 0000000000..688527a0a1
--- /dev/null
+++ b/python/mooncake/ep.py
@@ -0,0 +1,30 @@
+import importlib
+import re
+
+import torch
+
+
+torch_version = re.match(r"\d+(?:\.\d+)*", torch.__version__).group()
+version_suffix = "_" + torch_version.replace(".", "_")
+
+try:
+    backend_module = importlib.import_module("mooncake._ep")
+except ModuleNotFoundError:
+    raise ImportError(
+        "Mooncake EP was not built. Please rebuild Mooncake with WITH_EP=ON.\n"
+        "Open an issue at https://github.com/kvcache-ai/Mooncake/issues."
+    )
+globals().update(
+    {k: v for k, v in backend_module.__dict__.items() if not k.startswith("_")}
+)
+
+try:
+    backend_compat_module = importlib.import_module("mooncake.pg" + version_suffix)
+except ModuleNotFoundError:
+    raise ImportError(
+        f"Mooncake PG was not built against torch=={torch_version}.\n"
+        f"Open an issue at https://github.com/kvcache-ai/Mooncake/issues."
+    )
+globals().update(
+    {k: v for k, v in backend_compat_module.__dict__.items() if not k.startswith("_")}
+)
diff --git a/mooncake-wheel/mooncake/mooncake_config.py b/python/mooncake/mooncake_config.py
similarity index 99%
rename from mooncake-wheel/mooncake/mooncake_config.py
rename to python/mooncake/mooncake_config.py
index 9b494ebe42..8290e53c98 100644
--- a/mooncake-wheel/mooncake/mooncake_config.py
+++ b/python/mooncake/mooncake_config.py
@@ -23,6 +23,7 @@
 - efa: AWS Elastic Fabric Adapter transport (libfabric-based)
 - nvmeof: NVMe over Fabric for direct NVMe storage access
 - nvlink: NVIDIA NVLink for inter-GPU communication across nodes
+- musa: Moore Threads GPU IPC/P2P communication over MTLink
 - nvlink_intra: NVIDIA NVLink for intra-node GPU communication
 - hip: ROCm/HIP for AMD GPU communication using IPC/Shareable handles
 - barex: Bare-metal RDMA extension protocol
@@ -100,6 +101,7 @@
         "efa",
         "nvmeof",
         "nvlink",
+        "musa",
         "nvlink_intra",
         "hip",
         "barex",
diff --git a/python/mooncake/mooncake_elastic_buffer.py b/python/mooncake/mooncake_elastic_buffer.py
new file mode 100644
index 0000000000..6daf9efd8f
--- /dev/null
+++ b/python/mooncake/mooncake_elastic_buffer.py
@@ -0,0 +1,1359 @@
+import os
+import warnings
+from typing import Any, List, Optional, Sequence, Tuple, Union
+
+import torch
+import torch.distributed as dist
+
+from .mooncake_ep_buffer import EventOverlap, _native_current_stream_ptr
+
+
+_VALID_TRANSPORTS = {"auto", "ibgda", "nccl"}
+_TRANSPORT_TO_CODE = {"auto": 0, "ibgda": 1, "nccl": 2}
+_CODE_TO_TRANSPORT = {code: name for name, code in _TRANSPORT_TO_CODE.items()}
+
+
+def _requested_transport(transport: str) -> str:
+    """Return the normalized user request, including the rollout override."""
+    requested = transport.strip().lower()
+    if requested == "auto":
+        requested = os.getenv("MOONCAKE_EP_TRANSPORT", "auto").strip().lower()
+    if requested not in _VALID_TRANSPORTS:
+        choices = ", ".join(sorted(_VALID_TRANSPORTS))
+        raise ValueError(
+            f"ElasticBuffer transport must be one of {choices}, got {requested!r}"
+        )
+    return requested
+
+
+def _nccl_topology_supported(
+    num_ranks: int,
+    num_rdma_ranks: int,
+    num_nvlink_ranks: int,
+    allow_hybrid_mode: bool,
+) -> bool:
+    """Whether the compiled NCCL kernels cover the inferred EP topology."""
+    if num_ranks != num_rdma_ranks * num_nvlink_ranks:
+        return False
+    if num_rdma_ranks == 1:
+        return num_nvlink_ranks in {2, 8}
+    if not allow_hybrid_mode:
+        return False
+    if num_rdma_ranks == 2:
+        return num_nvlink_ranks in {4, 8}
+    return num_rdma_ranks == 4 and num_nvlink_ranks == 4
+
+
+def _select_transport(
+    requested: str,
+    nccl_available: bool,
+    num_ranks: int,
+    num_rdma_ranks: int,
+    num_nvlink_ranks: int,
+    allow_hybrid_mode: bool,
+) -> str:
+    """Prefer NCCL for auto mode without breaking unsupported deployments."""
+    if requested != "auto":
+        return requested
+    if nccl_available and _nccl_topology_supported(
+        num_ranks,
+        num_rdma_ranks,
+        num_nvlink_ranks,
+        allow_hybrid_mode,
+    ):
+        return "nccl"
+    return "ibgda"
+
+
+def _resolve_transport_consensus(
+    rank_states: Sequence[Tuple[str, bool, Optional[str]]],
+) -> str:
+    """Resolve rank-local NCCL readiness into one group-wide choice."""
+    if not rank_states:
+        raise RuntimeError(
+            "cannot select an ElasticBuffer transport for an empty group"
+        )
+
+    requested_modes = {requested for requested, _, _ in rank_states}
+    if len(requested_modes) != 1:
+        details = ", ".join(
+            f"rank {rank}={requested!r}"
+            for rank, (requested, _, _) in enumerate(rank_states)
+        )
+        raise RuntimeError(
+            "ElasticBuffer transport requests differ across process-group ranks: "
+            f"{details}. Pass the same transport argument and "
+            "MOONCAKE_EP_TRANSPORT setting to every rank."
+        )
+
+    required_modes = {
+        required for _, _, required in rank_states if required is not None
+    }
+    if len(required_modes) > 1:
+        details = ", ".join(
+            f"rank {rank}={required!r}"
+            for rank, (_, _, required) in enumerate(rank_states)
+            if required is not None
+        )
+        raise RuntimeError(
+            "ElasticBuffer transport requirements differ across process-group "
+            f"ranks: {details}"
+        )
+
+    requested = rank_states[0][0]
+    required = next(iter(required_modes), None)
+    if required is not None and requested not in {"auto", required}:
+        raise RuntimeError(
+            f"ElasticBuffer transport {required!r} is required by an existing "
+            f"buffer generation, but the group requested {requested!r}"
+        )
+
+    unready_ranks = [
+        rank for rank, (_, nccl_ready, _) in enumerate(rank_states) if not nccl_ready
+    ]
+    if requested == "nccl" or required == "nccl":
+        if unready_ranks:
+            ranks = ", ".join(str(rank) for rank in unready_ranks)
+            raise RuntimeError(
+                "transport='nccl' requires NCCL Device API support and a "
+                "supported NCCL kernel topology on every process-group rank; "
+                f"requirements are not met on ranks: {ranks}"
+            )
+        return "nccl"
+    if required == "ibgda":
+        return "ibgda"
+
+    # In auto mode, a single rank that cannot use NCCL makes the whole group
+    # choose IBGDA. No rank enters transport-specific bootstrap until this
+    # collective decision has completed.
+    if requested == "auto" and not unready_ranks:
+        return "nccl"
+    return "ibgda"
+
+
+def _resolve_nccl_membership_masks(rank_masks: Sequence[Sequence[int]]) -> None:
+    """Require one consistent, fully restored fixed-world membership view."""
+    if not rank_masks:
+        raise RuntimeError("cannot reconfigure NCCL for an empty group")
+    num_ranks = len(rank_masks)
+    malformed_observers = [
+        rank for rank, mask in enumerate(rank_masks) if len(mask) != num_ranks
+    ]
+    inactive_slots = sorted(
+        {
+            slot
+            for mask in rank_masks
+            for slot, active in enumerate(mask[:num_ranks])
+            if int(active) != 1
+        }
+    )
+    if malformed_observers or inactive_slots:
+        details = []
+        if inactive_slots:
+            details.append(f"inactive or inconsistent logical slots: {inactive_slots}")
+        if malformed_observers:
+            details.append(f"invalid membership views on ranks: {malformed_observers}")
+        raise RuntimeError(
+            "NCCL ElasticBuffer reconfiguration requires the complete fixed "
+            "logical rank set to be restored; " + "; ".join(details)
+        )
+
+
+def _bootstrap_collective_device(group: dist.ProcessGroup) -> str:
+    """Choose metadata tensors independently of the GPU EP data path."""
+    backend = str(dist.get_backend(group)).lower()
+    return "cpu" if backend in {"gloo", "mooncake-cpu"} else "cuda"
+
+
+def _select_transport_for_group(
+    group: dist.ProcessGroup,
+    requested: str,
+    nccl_available: bool,
+    num_ranks: int,
+    num_rdma_ranks: int,
+    num_nvlink_ranks: int,
+    allow_hybrid_mode: bool,
+    required_transport: Optional[str] = None,
+) -> str:
+    """Agree on one transport before starting transport-specific bootstrap."""
+    if required_transport not in {None, "ibgda", "nccl"}:
+        raise ValueError(f"invalid required transport: {required_transport!r}")
+
+    local_auto_choice = _select_transport(
+        "auto",
+        nccl_available,
+        num_ranks,
+        num_rdma_ranks,
+        num_nvlink_ranks,
+        allow_hybrid_mode,
+    )
+    collective_device = _bootstrap_collective_device(group)
+    group_size = group.size()
+    local_state = torch.tensor(
+        [
+            _TRANSPORT_TO_CODE[requested],
+            int(local_auto_choice == "nccl"),
+            _TRANSPORT_TO_CODE[required_transport or "auto"],
+            num_ranks,
+        ],
+        dtype=torch.int32,
+        device=collective_device,
+    )
+    gathered_states = [torch.full_like(local_state, -1) for _ in range(group_size)]
+    dist.all_gather(gathered_states, local_state, group=group)
+
+    rank_states = []
+    mismatched_world_sizes = []
+    for rank, state in enumerate(gathered_states):
+        values = [int(value) for value in state.cpu().tolist()]
+        if values == [-1, -1, -1, -1]:
+            rank_states.append((requested, False, None))
+            continue
+        requested_code, rank_nccl_ready, required_code, rank_world_size = values
+        if rank_world_size != group_size:
+            mismatched_world_sizes.append(f"rank {rank}={rank_world_size}")
+        if (
+            requested_code not in _CODE_TO_TRANSPORT
+            or required_code not in _CODE_TO_TRANSPORT
+        ):
+            raise RuntimeError(
+                "received an invalid ElasticBuffer transport state during "
+                "group consensus"
+            )
+        required_name = _CODE_TO_TRANSPORT[required_code]
+        rank_states.append(
+            (
+                _CODE_TO_TRANSPORT[requested_code],
+                bool(rank_nccl_ready),
+                None if required_name == "auto" else required_name,
+            )
+        )
+    # Exchange the expected world size in this fixed-width collective, before
+    # the membership exchange uses num_ranks-sized tensors. Survivors retain
+    # their original size while a new buffer sees the current PG size; a local
+    # check alone could leave replacements entering a different collective.
+    if mismatched_world_sizes:
+        raise RuntimeError(
+            "ElasticBuffer requires a fixed logical world size during bootstrap; "
+            f"the process group has {group_size} ranks, but buffers expect "
+            + ", ".join(mismatched_world_sizes)
+            + ". Restore the original logical rank set or recreate all buffers "
+            "for the new group size."
+        )
+    return _resolve_transport_consensus(rank_states)
+
+
+def _using_musa_backend() -> bool:
+    return os.getenv("MOONCAKE_EP_USE_MUSA", "").upper() in {
+        "1",
+        "ON",
+        "TRUE",
+        "YES",
+    }
+
+
+def _dist_barrier(group: dist.ProcessGroup) -> None:
+    if _using_musa_backend():
+        dist.barrier(group=group, device_ids=[torch.cuda.current_device()])
+    else:
+        dist.barrier(group=group)
+
+
+def _ceil_div(x: int, y: int) -> int:
+    return (x + y - 1) // y
+
+
+def _align(x: int, alignment: int) -> int:
+    return _ceil_div(x, alignment) * alignment
+
+
+class EPHandle:
+    """
+    Official DeepEP elastic-compatible communication handle.
+
+    The field names and semantics intentionally follow the official DeepEP elastic
+    handle contract so that model code can select Mooncake ElasticBuffer without
+    switching back to the legacy Buffer tuple handle.  Mooncake stores the native
+    legacy handle as an implementation detail while the elastic kernels are being
+    wired to the Device API backend.
+    """
+
+    def __init__(
+        self,
+        do_expand: bool,
+        num_experts: int,
+        expert_alignment: int,
+        num_max_tokens_per_rank: int,
+        num_sms: int,
+        topk_idx: torch.Tensor,
+        num_recv_tokens_per_expert_list: List[int],
+        psum_num_recv_tokens_per_scaleup_rank: torch.Tensor,
+        psum_num_recv_tokens_per_expert: torch.Tensor,
+        recv_src_metadata: torch.Tensor,
+        dst_buffer_slot_idx: torch.Tensor,
+        token_metadata_at_forward: Optional[torch.Tensor],
+        channel_linked_list: Optional[torch.Tensor],
+        native_handle: Optional[Tuple[Any, ...]] = None,
+        generation: Optional[Tuple[int, ...]] = None,
+    ) -> None:
+        assert topk_idx is not None
+        self.do_expand = do_expand
+        self.num_experts = num_experts
+        self.expert_alignment = expert_alignment
+        self.num_max_tokens_per_rank = num_max_tokens_per_rank
+        self.num_sms = num_sms
+        self.topk_idx = topk_idx
+        self.psum_num_recv_tokens_per_scaleup_rank = (
+            psum_num_recv_tokens_per_scaleup_rank
+        )
+        self.psum_num_recv_tokens_per_expert = psum_num_recv_tokens_per_expert
+        self.num_recv_tokens_per_expert_list = num_recv_tokens_per_expert_list
+        self.recv_src_metadata = recv_src_metadata
+        self.dst_buffer_slot_idx = dst_buffer_slot_idx
+        self.token_metadata_at_forward = token_metadata_at_forward
+        self.channel_linked_list = channel_linked_list
+        self.native_handle = native_handle
+        self._generation = generation
+
+        # Same convention as DeepEP: without a CPU sync this is an inferred upper
+        # bound; after CPU sync it tracks the actual received-token count.
+        self.num_recv_tokens = int(recv_src_metadata.shape[0])
+
+
+class ElasticBuffer:
+    """
+    Official DeepEP elastic EP API backed by Mooncake EP transports.
+
+    Public API source of truth: official DeepEP `ElasticBuffer`.  The implementation is
+    deliberately separate from Mooncake's legacy `Buffer` API, while reusing the
+    existing Mooncake Device API transport/bootstrap path for the native data
+    movement backend.
+
+    The default ``transport="auto"`` prefers NCCL when the extension contains
+    NCCL Device API support and the current topology has a compiled NCCL kernel.
+    It otherwise retains the IPC + IBGDA backend. Set ``transport="ibgda"`` or
+    ``MOONCAKE_EP_TRANSPORT=ibgda`` to force the legacy backend during rollout.
+    """
+
+    # Mirrors DeepEP's fixed workspace assumptions closely enough for sizing and
+    # keeping one reusable buffer for all elastic EP shapes.
+    _NUM_MAX_RANKS = 1024
+    _NUM_MAX_EXPERTS = 2048
+    _NUM_MAX_CHANNELS = 8 * 160
+    _NUM_BARRIER_TAGS = 16
+    _NUM_MAX_INFLIGHT_AGRS = 32
+    _NCCL_UNIQUE_ID_WORDS = 32
+
+    def __init__(
+        self,
+        group: dist.ProcessGroup,
+        num_bytes: Optional[int] = None,
+        num_max_tokens_per_rank: int = 0,
+        hidden: int = 0,
+        num_topk: int = 0,
+        use_fp8_dispatch: bool = False,
+        deterministic: bool = False,
+        allow_hybrid_mode: bool = True,
+        allow_multiple_reduction: bool = True,
+        prefer_overlap_with_compute: bool = True,
+        sl_idx: int = 3,
+        num_allocated_qps: int = 0,
+        num_cpu_timeout_secs: int = 300,
+        num_gpu_timeout_secs: int = 100,
+        explicitly_destroy: bool = False,
+        transport: str = "auto",
+    ) -> None:
+        if not allow_multiple_reduction:
+            raise NotImplementedError(
+                "Mooncake ElasticBuffer currently supports only "
+                "allow_multiple_reduction=True"
+            )
+        self.group = group
+        self.rank_idx = group.rank()
+        self.num_ranks = group.size()
+        self._device_index = torch.cuda.current_device()
+        self.requested_transport = _requested_transport(transport)
+        self.allow_hybrid_mode = allow_hybrid_mode
+        self.allow_multiple_reduction = allow_multiple_reduction
+        self.prefer_overlap_with_compute = prefer_overlap_with_compute
+        self.deterministic = deterministic
+        self.sl_idx = int(os.getenv("EP_OVERRIDE_RDMA_SL", sl_idx))
+        self.num_allocated_qps = num_allocated_qps
+        self.num_cpu_timeout_secs = num_cpu_timeout_secs
+        self.num_gpu_timeout_secs = num_gpu_timeout_secs
+        self.explicitly_destroy = explicitly_destroy
+
+        self.num_max_tokens_per_rank = num_max_tokens_per_rank
+        self.hidden = hidden
+        self.num_topk = num_topk
+        self.use_fp8_dispatch = use_fp8_dispatch
+
+        if num_bytes is None:
+            num_bytes = self.get_buffer_size_hint(
+                group,
+                num_max_tokens_per_rank,
+                hidden,
+                num_topk=num_topk,
+                use_fp8_dispatch=use_fp8_dispatch,
+                allow_hybrid_mode=allow_hybrid_mode,
+                allow_multiple_reduction=allow_multiple_reduction,
+            )
+        self.num_bytes = num_bytes
+
+        (
+            self.num_scaleout_ranks,
+            self.num_scaleup_ranks,
+        ) = self._calculate_logical_domain_size(group, allow_hybrid_mode)
+        self.scaleout_rank_idx = self.rank_idx // self.num_scaleup_ranks
+        self.scaleup_rank_idx = self.rank_idx % self.num_scaleup_ranks
+        self.num_rdma_ranks, self.num_nvlink_ranks = (
+            self._calculate_physical_domain_size(group)
+        )
+
+        self.backend = group
+        self._generation: Optional[Tuple[int, ...]] = None
+
+        # Native Mooncake transport/runtime.  This keeps the legacy Buffer ABI
+        # untouched while giving ElasticBuffer users a dedicated native entrypoint.
+        from mooncake import ep
+
+        self.transport = _select_transport_for_group(
+            self.group,
+            self.requested_transport,
+            ep.has_nccl_device_support(),
+            self.num_ranks,
+            self.num_rdma_ranks,
+            self.num_nvlink_ranks,
+            self.allow_hybrid_mode,
+        )
+
+        nccl_unique_id = []
+        if self.transport == "nccl":
+            self._require_full_nccl_membership()
+            nccl_unique_id = self._exchange_nccl_unique_id(ep)
+            self._generation = tuple(nccl_unique_id)
+        self.runtime = ep.ElasticBuffer(
+            self.rank_idx,
+            self.num_ranks,
+            num_bytes,
+            num_max_tokens_per_rank,
+            hidden,
+            num_topk,
+            use_fp8_dispatch,
+            deterministic,
+            allow_hybrid_mode,
+            allow_multiple_reduction,
+            prefer_overlap_with_compute,
+            self.sl_idx,
+            num_allocated_qps,
+            num_cpu_timeout_secs,
+            num_gpu_timeout_secs,
+            self.transport,
+            nccl_unique_id,
+        )
+        # NCCL's LSA team is the transport authority for the local domain; it
+        # may differ from the CUDA-visible-device heuristic used before native
+        # initialization. Keep the public topology fields in sync with the
+        # exact native launch topology for both backends.
+        self._refresh_topology_from_runtime()
+        self._connect_native()
+        # The native elastic kernels currently use fixed communicator
+        # membership. Reuse this compatibility argument instead of allocating
+        # and filling a CUDA tensor for every dispatch and combine call.
+        self._active_ranks = torch.ones(
+            self.num_ranks, dtype=torch.int32, device="cuda"
+        )
+
+        torch.cuda.synchronize()
+        _dist_barrier(group)
+        torch.cuda.synchronize()
+
+    def _active_ranks_mask(self) -> list:
+        # `mooncake.ep.get_active_ranks` is a Mooncake PG helper and performs a
+        # native static cast to MooncakeBackend. PyTorch exposes custom process
+        # groups through its base ProcessGroup type, so query the registered
+        # backend name instead of relying on the Python wrapper's type name.
+        if "mooncake" not in str(dist.get_backend(self.backend)).lower():
+            return [1] * self.num_ranks
+
+        from mooncake.ep import get_active_ranks
+
+        # Mooncake PG refreshes this CUDA mirror on its own stream. Wait for
+        # that update before taking the host snapshot used for membership
+        # agreement, including the replacement process's initial snapshot.
+        torch.cuda.synchronize(self._device_index)
+        return get_active_ranks(self.backend).cpu().tolist()
+
+    def _require_full_nccl_membership(self) -> None:
+        """Agree that every fixed logical rank has rejoined before bootstrap."""
+        try:
+            active_mask = self._active_ranks_mask()
+        except Exception:
+            active_mask = []
+        collective_device = _bootstrap_collective_device(self.group)
+        local_mask = torch.full(
+            (self.num_ranks,), -1, dtype=torch.int32, device=collective_device
+        )
+        # Mooncake PG masks cover max_group_size (or a larger user-provided
+        # tensor), not just the logical ranks used by this fixed-world buffer.
+        if len(active_mask) >= self.num_ranks:
+            local_mask.copy_(
+                torch.tensor(
+                    active_mask[: self.num_ranks],
+                    dtype=torch.int32,
+                    device=collective_device,
+                )
+            )
+        gathered_masks = [
+            torch.full_like(local_mask, -1) for _ in range(self.num_ranks)
+        ]
+        dist.all_gather(gathered_masks, local_mask, group=self.group)
+        _resolve_nccl_membership_masks(
+            [rank_mask.cpu().tolist() for rank_mask in gathered_masks]
+        )
+
+    def _refresh_topology_from_runtime(self) -> None:
+        self.num_rdma_ranks, self.num_nvlink_ranks = (
+            self.runtime.get_physical_domain_size()
+        )
+        self.num_scaleout_ranks, self.num_scaleup_ranks = (
+            self.runtime.get_logical_domain_size()
+        )
+        self.scaleout_rank_idx = self.rank_idx // self.num_scaleup_ranks
+        self.scaleup_rank_idx = self.rank_idx % self.num_scaleup_ranks
+
+    def _validate_handle_generation(self, handle: EPHandle) -> None:
+        handle_generation = getattr(handle, "_generation", None)
+        if self._generation is not None and handle_generation != self._generation:
+            raise RuntimeError(
+                "EPHandle belongs to an obsolete NCCL ElasticBuffer generation; "
+                "dispatch again after update_ep_member()"
+            )
+
+    def _connect_native(self, is_update: bool = False) -> None:
+        from mooncake import ep
+
+        if self.transport == "nccl":
+            return
+
+        if not bool(self.runtime.ibgda_disabled()):
+            raddr, rkey = self.runtime.get_mr_info()
+            raddr_tensor = torch.tensor([raddr], dtype=torch.int64, device="cuda")
+            raddrs = [
+                torch.empty(1, dtype=torch.int64, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_gather(raddrs, raddr_tensor, self.group)
+            raddrs_list = torch.cat(raddrs).tolist()
+
+            rkey_tensor = torch.tensor([rkey], dtype=torch.int32, device="cuda")
+            rkeys = [
+                torch.empty(1, dtype=torch.int32, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_gather(rkeys, rkey_tensor, self.group)
+            rkeys_list = torch.cat(rkeys).tolist()
+
+            all_to_all_size = ep.MAX_QP_COUNT // self.num_ranks
+            if is_update:
+                self.runtime.update_local_qpns()
+
+            local_qpns = torch.tensor(
+                self.runtime.get_local_qpns(), dtype=torch.int32, device="cuda"
+            ).view(-1, all_to_all_size)
+            remote_qpns = [
+                torch.empty(all_to_all_size, dtype=torch.int32, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_to_all(remote_qpns, list(torch.unbind(local_qpns)), self.group)
+            peer_qpns = [remote_qpns[r].tolist() for r in range(self.num_ranks)]
+
+            local_lids = torch.tensor(
+                self.runtime.get_local_lids(), dtype=torch.int32, device="cuda"
+            ).view(-1, all_to_all_size)
+            remote_lids = [
+                torch.empty(all_to_all_size, dtype=torch.int32, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_to_all(remote_lids, list(torch.unbind(local_lids)), self.group)
+            peer_lids = [remote_lids[r].tolist() for r in range(self.num_ranks)]
+
+            subnet_prefix, interface_id = self.runtime.get_gid()
+            subnet_prefix_tensor = torch.tensor(
+                [subnet_prefix], dtype=torch.int64, device="cuda"
+            )
+            subnet_prefixes = [
+                torch.empty(1, dtype=torch.int64, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_gather(subnet_prefixes, subnet_prefix_tensor, self.group)
+            subnet_prefixes_list = torch.cat(subnet_prefixes).tolist()
+
+            interface_id_tensor = torch.tensor(
+                [interface_id], dtype=torch.int64, device="cuda"
+            )
+            interface_ids = [
+                torch.empty(1, dtype=torch.int64, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_gather(interface_ids, interface_id_tensor, self.group)
+            interface_ids_list = torch.cat(interface_ids).tolist()
+
+            active_ranks_mask = self._active_ranks_mask()
+            self.runtime.sync_ibgda_peers(
+                raddrs_list,
+                rkeys_list,
+                peer_qpns,
+                peer_lids,
+                subnet_prefixes_list,
+                interface_ids_list,
+                active_ranks_mask,
+            )
+
+        try:
+            local_handle_ints = self.runtime.get_ipc_handle()
+            local_handle_tensor = torch.tensor(
+                local_handle_ints, dtype=torch.int32, device="cuda"
+            )
+            handles = [
+                torch.empty(len(local_handle_ints), dtype=torch.int32, device="cuda")
+                for _ in range(self.num_ranks)
+            ]
+            dist.all_gather(handles, local_handle_tensor, self.group)
+            remote_handles = [h.tolist() for h in handles]
+
+            active_ranks_mask = self._active_ranks_mask()
+            self.runtime.sync_nvlink_ipc_handles(remote_handles, active_ranks_mask)
+        except Exception as exc:
+            if bool(self.runtime.ibgda_disabled()):
+                raise RuntimeError(
+                    f"[Rank {self.rank_idx}] Failed to exchange IPC handles "
+                    "for ElasticBuffer and RDMA is disabled; native elastic "
+                    "mode cannot continue safely."
+                ) from exc
+            warnings.warn(
+                f"[Rank {self.rank_idx}] Failed to exchange IPC handles for ElasticBuffer: {exc}. "
+                "Continuing with RDMA-only routing.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+    def _exchange_nccl_unique_id(self, ep: Any) -> List[int]:
+        create_unique_id = getattr(ep, "create_nccl_unique_id", None)
+        collective_device = _bootstrap_collective_device(self.group)
+        root_global_rank = dist.get_global_rank(self.group, 0)
+
+        # NCCL requires ncclGetUniqueId to be called once per communicator.
+        # Catch root-side failures and broadcast the status first so every
+        # subgroup rank either receives the same ID or raises instead of
+        # waiting forever in the payload broadcast.
+        local_unique_id: List[int] = []
+        root_error: Optional[str] = None
+        if self.rank_idx == 0:
+            try:
+                if create_unique_id is None:
+                    raise RuntimeError(
+                        "Mooncake EP was built without NCCL Device API support"
+                    )
+                local_unique_id = list(create_unique_id())
+                if len(local_unique_id) != self._NCCL_UNIQUE_ID_WORDS:
+                    raise RuntimeError(
+                        "NCCL returned an invalid communicator unique ID: "
+                        f"expected {self._NCCL_UNIQUE_ID_WORDS} int32 words, "
+                        f"got {len(local_unique_id)}"
+                    )
+            except Exception as exc:
+                root_error = f"{type(exc).__name__}: {exc}"
+
+        status = torch.tensor(
+            [int(root_error is not None)],
+            dtype=torch.int32,
+            device=collective_device,
+        )
+        dist.broadcast(
+            status,
+            src=root_global_rank,
+            group=self.group,
+        )
+        if int(status.item()) != 0:
+            detail = f": {root_error}" if root_error is not None else ""
+            raise RuntimeError(
+                f"group root failed to create the NCCL communicator unique ID{detail}"
+            )
+
+        unique_id = torch.zeros(
+            self._NCCL_UNIQUE_ID_WORDS,
+            dtype=torch.int32,
+            device=collective_device,
+        )
+        if self.rank_idx == 0:
+            unique_id.copy_(
+                torch.tensor(
+                    local_unique_id,
+                    dtype=torch.int32,
+                    device=collective_device,
+                )
+            )
+        dist.broadcast(
+            unique_id,
+            src=root_global_rank,
+            group=self.group,
+        )
+        return unique_id.cpu().tolist()
+
+    def update_ep_member(self) -> None:
+        if self.transport != "nccl":
+            self._connect_native(True)
+            return
+        if self.runtime is None:
+            raise RuntimeError("ElasticBuffer has been destroyed")
+
+        # NCCL cannot patch one peer in place. Join the same bootstrap sequence
+        # used by a replacement rank's constructor and publish a complete new
+        # communicator/device/window generation at a quiescent EP boundary.
+        # Restore the device captured at construction because applications may
+        # change the thread's current CUDA device between EP calls.
+        with torch.cuda.device(self._device_index):
+            torch.cuda.synchronize()
+            from mooncake import ep
+
+            selected_transport = _select_transport_for_group(
+                self.group,
+                self.requested_transport,
+                ep.has_nccl_device_support(),
+                self.num_ranks,
+                self.num_rdma_ranks,
+                self.num_nvlink_ranks,
+                self.allow_hybrid_mode,
+                required_transport=self.transport,
+            )
+            if selected_transport != "nccl":
+                raise RuntimeError(
+                    "NCCL ElasticBuffer recovery no longer has a supported NCCL "
+                    "topology; recreate the buffer with transport='ibgda'"
+                )
+            self._require_full_nccl_membership()
+            nccl_unique_id = self._exchange_nccl_unique_id(ep)
+            self.runtime.reconfigure_nccl(nccl_unique_id)
+            # The native generation changes atomically when reconfigure_nccl()
+            # returns. Publish the matching Python generation before any other
+            # fallible work so an old handle cannot be accepted afterward.
+            self._generation = tuple(nccl_unique_id)
+            self._refresh_topology_from_runtime()
+            self._active_ranks.fill_(1)
+
+            torch.cuda.synchronize()
+            _dist_barrier(self.group)
+            torch.cuda.synchronize()
+
+    def destroy(self) -> None:
+        runtime = self.runtime
+        if runtime is None:
+            return
+        is_nccl = self.transport == "nccl"
+        if is_nccl:
+            # Quiesce every local CUDA stream before any rank deregisters the
+            # symmetric window. The following process-group barrier then makes
+            # that quiescence visible across all ranks.
+            torch.cuda.synchronize()
+            _dist_barrier(self.group)
+        try:
+            native_destroy = getattr(runtime, "destroy", None)
+            if native_destroy is not None:
+                native_destroy()
+        finally:
+            self.runtime = None
+            if is_nccl:
+                _dist_barrier(self.group)
+
+    @staticmethod
+    def _workspace_num_bytes() -> int:
+        num_bytes = 0
+        num_bytes += ElasticBuffer._NUM_BARRIER_TAGS * (
+            8 + 2 * ElasticBuffer._NUM_MAX_RANKS * 4
+        )
+        num_bytes += (ElasticBuffer._NUM_MAX_RANKS + ElasticBuffer._NUM_MAX_EXPERTS) * 8
+        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 8 * 2
+        num_bytes += ElasticBuffer._NUM_MAX_EXPERTS * 8 * 2
+        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 4
+        num_bytes += ElasticBuffer._NUM_MAX_RANKS * 4 * 2
+        num_bytes += ElasticBuffer._NUM_MAX_EXPERTS * 4 * 2
+        num_bytes += ElasticBuffer._NUM_MAX_RANKS * ElasticBuffer._NUM_MAX_CHANNELS * 8
+        num_bytes += ElasticBuffer._NUM_MAX_RANKS * ElasticBuffer._NUM_MAX_CHANNELS * 4
+        num_bytes += 2 * 2 * 8
+        num_bytes += (
+            (ElasticBuffer._NUM_MAX_INFLIGHT_AGRS + 1)
+            * ElasticBuffer._NUM_MAX_RANKS
+            * 4
+        )
+        return _align(num_bytes, 32)
+
+    @staticmethod
+    def _atomic_scratch_num_bytes() -> int:
+        # Mirrors the native runtime: this is IBGDA response scratch or NCCL
+        # GIN-only signal storage, separate from the regular workspace signals.
+        return ElasticBuffer._workspace_num_bytes()
+
+    @staticmethod
+    def get_buffer_size_hint(
+        group: dist.ProcessGroup,
+        num_max_tokens_per_rank: int,
+        hidden: int,
+        num_topk: int = 0,
+        use_fp8_dispatch: bool = False,
+        allow_hybrid_mode: bool = True,
+        allow_multiple_reduction: bool = True,
+    ) -> int:
+        try:
+            from mooncake import ep
+
+            return int(
+                ep.calculate_elastic_buffer_size(
+                    group.size(),
+                    num_max_tokens_per_rank,
+                    hidden,
+                    num_topk,
+                    use_fp8_dispatch,
+                    allow_hybrid_mode,
+                    allow_multiple_reduction,
+                )
+            )
+        except Exception:
+            pass
+
+        num_ranks = group.size()
+        num_topk = max(1, num_topk)
+        dtype_bytes = 1 if use_fp8_dispatch else 2
+        scale_bytes = _ceil_div(hidden, 128) * 4 if use_fp8_dispatch else 0
+        token_bytes = _align(hidden * dtype_bytes, 32) + _align(scale_bytes, 32)
+        metadata_bytes = _align(num_topk * (4 + 4) + (1 + num_topk) * 4, 32)
+        per_slot_bytes = token_bytes + metadata_bytes
+
+        # Direct elastic send/recv buffers plus room for combine reduce buffers.
+        dispatch_bytes = (
+            num_ranks * num_max_tokens_per_rank * num_topk * per_slot_bytes * 2
+        )
+        combine_factor = 3 if allow_multiple_reduction else 4
+        combine_bytes = dispatch_bytes * combine_factor
+        hybrid_factor = 2 if allow_hybrid_mode and num_ranks > 1 else 1
+        return int(
+            ElasticBuffer._workspace_num_bytes()
+            + ElasticBuffer._atomic_scratch_num_bytes()
+            + hybrid_factor * (dispatch_bytes + combine_bytes)
+        )
+
+    @staticmethod
+    def get_engram_storage_size_hint(
+        num_entries: int,
+        hidden: int,
+        num_max_tokens_per_rank: int,
+        dtype: torch.dtype = torch.bfloat16,
+    ) -> int:
+        num_sf_packs = _ceil_div(hidden, 128) if dtype.itemsize <= 1 else 0
+        num_bytes_per_entry = _align(hidden * dtype.itemsize + num_sf_packs * 4, 32)
+        return num_bytes_per_entry * (num_entries + num_max_tokens_per_rank)
+
+    @staticmethod
+    def get_pp_buffer_size_hint(
+        num_max_tensor_bytes: int, num_max_inflight_tensors: int
+    ) -> int:
+        return _align(num_max_tensor_bytes, 32) * num_max_inflight_tensors * 2 * 2
+
+    @staticmethod
+    def get_agrs_buffer_size_hint(
+        group: dist.ProcessGroup, num_max_session_bytes: int
+    ) -> int:
+        return num_max_session_bytes
+
+    @staticmethod
+    def _calculate_physical_domain_size(group: dist.ProcessGroup) -> Tuple[int, int]:
+        num_ranks = group.size()
+        num_local_ranks = int(
+            os.getenv(
+                "MOONCAKE_EP_NUM_LOCAL_RANKS",
+                os.getenv("LOCAL_WORLD_SIZE", "0"),
+            )
+        )
+        if num_local_ranks <= 0:
+            try:
+                num_local_ranks = max(1, min(num_ranks, torch.cuda.device_count()))
+            except Exception:
+                num_local_ranks = 1
+        num_local_ranks = max(1, min(num_local_ranks, num_ranks))
+        return _ceil_div(num_ranks, num_local_ranks), num_local_ranks
+
+    @staticmethod
+    def _calculate_logical_domain_size(
+        group: dist.ProcessGroup, allow_hybrid_mode: bool = True
+    ) -> Tuple[int, int]:
+        num_ranks = group.size()
+        num_rdma_ranks, num_nvlink_ranks = (
+            ElasticBuffer._calculate_physical_domain_size(group)
+        )
+        if allow_hybrid_mode and num_rdma_ranks > 1:
+            return num_rdma_ranks, num_nvlink_ranks
+        return 1, num_ranks
+
+    def get_physical_domain_size(self) -> Tuple[int, int]:
+        return self.num_rdma_ranks, self.num_nvlink_ranks
+
+    def get_logical_domain_size(self) -> Tuple[int, int]:
+        return self.num_scaleout_ranks, self.num_scaleup_ranks
+
+    def _hybrid_num_channels(self, num_sms: int) -> int:
+        channels_per_sm = 8 if self.transport == "nccl" else 4
+        return max(1, num_sms) * channels_per_sm
+
+    def _hybrid_num_max_tokens_per_channel(
+        self, num_max_tokens_per_rank: int, num_sms: int
+    ) -> int:
+        return _ceil_div(num_max_tokens_per_rank, self._hybrid_num_channels(num_sms))
+
+    def barrier(
+        self, use_comm_stream: bool = True, with_cpu_sync: bool = False
+    ) -> None:
+        if with_cpu_sync:
+            torch.cuda.synchronize()
+        _dist_barrier(self.group)
+        if with_cpu_sync:
+            torch.cuda.synchronize()
+
+    @staticmethod
+    def capture() -> Any:
+        from mooncake import ep
+
+        return ep.EventHandle(_native_current_stream_ptr())
+
+    def get_theoretical_num_sms(self, num_experts: int, num_topk: int) -> int:
+        device = torch.cuda.current_device()
+        sm_count = torch.cuda.get_device_properties(device).multi_processor_count
+        if self.prefer_overlap_with_compute:
+            return max(1, min(24, sm_count // 4))
+        return max(1, min(40, sm_count // 2, num_experts * max(1, num_topk)))
+
+    def dispatch(
+        self,
+        x: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
+        topk_idx: Optional[torch.Tensor] = None,
+        topk_weights: Optional[torch.Tensor] = None,
+        num_experts: Optional[int] = None,
+        num_max_tokens_per_rank: Optional[int] = None,
+        expert_alignment: Optional[int] = None,
+        handle: Optional[EPHandle] = None,
+        do_expand: bool = False,
+        do_cpu_sync: Optional[bool] = None,
+        num_sms: Optional[int] = None,
+        async_with_compute_stream: bool = False,
+    ) -> Tuple[
+        Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
+        Optional[torch.Tensor],
+        Optional[torch.Tensor],
+        EPHandle,
+        EventOverlap,
+    ]:
+        if self.runtime is None:
+            raise RuntimeError("ElasticBuffer has been destroyed")
+        if handle is not None:
+            self._validate_handle_generation(handle)
+            if topk_idx is not None or topk_weights is not None:
+                raise AssertionError(
+                    "topk_idx and topk_weights must be None when cached handle is provided"
+                )
+            if do_cpu_sync:
+                raise AssertionError("Cannot do CPU sync with cached handle")
+            if do_expand or handle.do_expand:
+                raise AssertionError(
+                    "Cached EPHandle currently supports only do_expand=False"
+                )
+            if handle.native_handle is None:
+                raise RuntimeError(
+                    "Cached EPHandle is missing its native Mooncake handle"
+                )
+            topk_idx = handle.topk_idx
+            num_max_tokens_per_rank = (
+                num_max_tokens_per_rank or handle.num_max_tokens_per_rank
+            )
+            num_experts = num_experts or handle.num_experts
+            expert_alignment = (
+                handle.expert_alignment
+                if expert_alignment is None
+                else expert_alignment
+            )
+            num_sms = handle.num_sms if num_sms is None else num_sms
+            do_cpu_sync = False
+        else:
+            if topk_idx is None:
+                raise AssertionError(
+                    "topk_idx must be provided when cached handle is not provided"
+                )
+            expert_alignment = 1 if expert_alignment is None else expert_alignment
+            do_cpu_sync = True if do_cpu_sync is None else do_cpu_sync
+        if do_expand:
+            warnings.warn(
+                "do_expand=True was requested. Mooncake currently returns the native packed expert layout; "
+                "expanded contiguous expert layout will be produced by the native elastic kernels.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        x_data = x[0] if isinstance(x, tuple) else x
+        sf = x[1] if isinstance(x, tuple) else None
+        assert x_data.dim() == 2 and x_data.is_contiguous()
+        if num_experts is None:
+            num_experts = int(torch.max(topk_idx).item()) + 1
+        if num_max_tokens_per_rank is None:
+            num_max_tokens_per_rank = self.num_max_tokens_per_rank or x_data.shape[0]
+        if num_sms is None:
+            num_sms = self.get_theoretical_num_sms(num_experts, topk_idx.shape[1])
+        num_tokens = int(x_data.shape[0])
+        hidden = int(x_data.shape[1])
+        num_topk = int(topk_idx.shape[1])
+        num_local_experts = num_experts // self.num_ranks
+        max_num_recv_tokens = num_max_tokens_per_rank * self.num_ranks
+        num_recv_tokens = (
+            int(handle.recv_src_metadata.shape[0])
+            if handle is not None
+            else max_num_recv_tokens
+        )
+        num_recv_output_capacity = (
+            num_recv_tokens * num_topk if do_expand else num_recv_tokens
+        )
+        use_hybrid = self.num_scaleout_ranks != 1
+        hybrid_channels = self._hybrid_num_channels(num_sms) if use_hybrid else 0
+        hybrid_max_tokens_per_channel = (
+            self._hybrid_num_max_tokens_per_channel(num_max_tokens_per_rank, num_sms)
+            if use_hybrid
+            else 0
+        )
+        num_sf_packs = int(sf.shape[1]) if sf is not None else 0
+        sf_token_stride = int(sf.stride(0)) if sf is not None else 0
+        sf_hidden_stride = int(sf.stride(1)) if sf is not None else 0
+
+        active_ranks = self._active_ranks
+        full_psum_num_recv_tokens_per_expert = (
+            handle.psum_num_recv_tokens_per_expert
+            if handle is not None and do_expand
+            else (
+                torch.cat(
+                    (
+                        torch.zeros(1, dtype=torch.int32, device=x_data.device),
+                        handle.psum_num_recv_tokens_per_expert,
+                    )
+                )
+                if handle is not None
+                else torch.empty(
+                    num_local_experts + 1, dtype=torch.int32, device=x_data.device
+                )
+            )
+        )
+        psum_num_recv_tokens_per_scaleup_rank = (
+            handle.psum_num_recv_tokens_per_scaleup_rank
+            if handle is not None
+            else torch.empty(
+                self.num_scaleup_ranks, dtype=torch.int32, device=x_data.device
+            )
+        )
+        dst_buffer_slot_idx = (
+            handle.dst_buffer_slot_idx
+            if handle is not None
+            else (
+                torch.empty(
+                    (
+                        hybrid_channels,
+                        self.num_scaleout_ranks,
+                        hybrid_max_tokens_per_channel,
+                        num_topk,
+                    ),
+                    dtype=torch.int32,
+                    device=x_data.device,
+                )
+                if use_hybrid
+                else torch.empty(
+                    (num_tokens, num_topk), dtype=torch.int32, device=x_data.device
+                )
+            )
+        )
+        token_metadata_at_forward = (
+            handle.token_metadata_at_forward
+            if handle is not None
+            else (
+                torch.empty(
+                    (
+                        hybrid_channels,
+                        self.num_scaleout_ranks * hybrid_max_tokens_per_channel + 1,
+                        2 + num_topk * 2,
+                    ),
+                    dtype=torch.int32,
+                    device=x_data.device,
+                )
+                if use_hybrid
+                else None
+            )
+        )
+        channel_linked_list = (
+            handle.channel_linked_list
+            if handle is not None
+            else (
+                torch.empty(
+                    (
+                        hybrid_channels,
+                        self.num_scaleout_ranks * hybrid_max_tokens_per_channel + 1,
+                        self.num_scaleup_ranks,
+                    ),
+                    dtype=torch.int32,
+                    device=x_data.device,
+                )
+                if use_hybrid
+                else None
+            )
+        )
+        recv_x = torch.empty(
+            (num_recv_output_capacity, hidden), dtype=x_data.dtype, device=x_data.device
+        )
+        recv_x_scales = (
+            torch.empty(
+                (num_recv_output_capacity, num_sf_packs),
+                dtype=sf.dtype,
+                device=sf.device,
+            )
+            if sf is not None
+            else None
+        )
+        recv_topk_idx = torch.empty(
+            (num_recv_tokens, num_topk), dtype=topk_idx.dtype, device=topk_idx.device
+        )
+        recv_topk_weights = (
+            torch.empty(
+                (num_recv_output_capacity,)
+                if do_expand
+                else (num_recv_tokens, num_topk),
+                dtype=topk_weights.dtype,
+                device=topk_weights.device,
+            )
+            if topk_weights is not None
+            else None
+        )
+        recv_src_metadata = (
+            handle.recv_src_metadata
+            if handle is not None
+            else torch.empty(
+                (num_recv_tokens, num_topk + 2),
+                dtype=torch.int32,
+                device=x_data.device,
+            )
+        )
+        event = self.runtime.dispatch(
+            x_data.data_ptr(),
+            x_data.element_size(),
+            0 if sf is None else sf.data_ptr(),
+            num_tokens,
+            hidden,
+            num_sf_packs,
+            sf_token_stride,
+            sf_hidden_stride,
+            topk_idx.data_ptr(),
+            num_topk,
+            0 if topk_weights is None else topk_weights.data_ptr(),
+            active_ranks.data_ptr(),
+            num_experts,
+            num_max_tokens_per_rank,
+            expert_alignment,
+            num_sms,
+            do_expand,
+            async_with_compute_stream,
+            _native_current_stream_ptr(),
+            handle is not None,
+            num_recv_tokens,
+            psum_num_recv_tokens_per_scaleup_rank.data_ptr(),
+            full_psum_num_recv_tokens_per_expert.data_ptr(),
+            dst_buffer_slot_idx.data_ptr(),
+            0
+            if token_metadata_at_forward is None
+            else token_metadata_at_forward.data_ptr(),
+            0 if channel_linked_list is None else channel_linked_list.data_ptr(),
+            recv_x.data_ptr(),
+            0 if recv_x_scales is None else recv_x_scales.data_ptr(),
+            recv_topk_idx.data_ptr(),
+            0 if recv_topk_weights is None else recv_topk_weights.data_ptr(),
+            recv_src_metadata.data_ptr(),
+        )
+        handle_psum_num_recv_tokens_per_expert = (
+            full_psum_num_recv_tokens_per_expert
+            if do_expand
+            else full_psum_num_recv_tokens_per_expert[1:]
+        )
+
+        num_recv_tokens_per_expert_list: List[int] = []
+        if do_cpu_sync:
+            scaleup_psum_cpu = psum_num_recv_tokens_per_scaleup_rank.cpu()
+            expert_psum_cpu = full_psum_num_recv_tokens_per_expert.cpu()
+            actual_num_recv_tokens = int(
+                scaleup_psum_cpu[self.num_scaleup_ranks - 1].item()
+            )
+            actual_num_output_tokens = actual_num_recv_tokens
+
+            def _align_count(value: int) -> int:
+                return _ceil_div(value, expert_alignment) * expert_alignment
+
+            if do_expand:
+                previous_psum = 0
+                for i in range(num_local_experts):
+                    current_psum = int(expert_psum_cpu[i].item())
+                    count = current_psum - _align_count(previous_psum)
+                    num_recv_tokens_per_expert_list.append(count)
+                    previous_psum = current_psum
+                actual_num_output_tokens = (
+                    0
+                    if num_local_experts == 0
+                    else int(expert_psum_cpu[num_local_experts - 1].item())
+                )
+            else:
+                for i in range(num_local_experts):
+                    count = int(
+                        expert_psum_cpu[i + 1].item() - expert_psum_cpu[i].item()
+                    )
+                    num_recv_tokens_per_expert_list.append(count)
+
+            recv_x = recv_x[:actual_num_output_tokens]
+            if recv_x_scales is not None:
+                recv_x_scales = recv_x_scales[:actual_num_output_tokens]
+            recv_topk_idx = recv_topk_idx[:actual_num_recv_tokens]
+            if recv_topk_weights is not None:
+                recv_topk_weights = recv_topk_weights[:actual_num_output_tokens]
+            recv_src_metadata = recv_src_metadata[:actual_num_recv_tokens]
+
+        elastic_handle = handle
+        if elastic_handle is None:
+            elastic_handle = EPHandle(
+                do_expand=do_expand,
+                num_experts=num_experts,
+                expert_alignment=expert_alignment,
+                num_max_tokens_per_rank=num_max_tokens_per_rank,
+                num_sms=num_sms,
+                topk_idx=topk_idx.clone(),
+                num_recv_tokens_per_expert_list=num_recv_tokens_per_expert_list,
+                psum_num_recv_tokens_per_scaleup_rank=psum_num_recv_tokens_per_scaleup_rank,
+                psum_num_recv_tokens_per_expert=handle_psum_num_recv_tokens_per_expert,
+                recv_src_metadata=recv_src_metadata,
+                dst_buffer_slot_idx=dst_buffer_slot_idx,
+                token_metadata_at_forward=token_metadata_at_forward,
+                channel_linked_list=channel_linked_list,
+                native_handle=True,
+                generation=self._generation,
+            )
+        recv_x_out = (recv_x, recv_x_scales) if recv_x_scales is not None else recv_x
+        tensors_to_record = None
+        if async_with_compute_stream:
+            tensors_to_record = (
+                x_data,
+                topk_idx,
+                active_ranks,
+                recv_x,
+                recv_topk_idx,
+                elastic_handle.topk_idx,
+                elastic_handle.psum_num_recv_tokens_per_scaleup_rank,
+                elastic_handle.psum_num_recv_tokens_per_expert,
+                elastic_handle.recv_src_metadata,
+                elastic_handle.dst_buffer_slot_idx,
+                *(() if sf is None else (sf,)),
+                *(() if topk_weights is None else (topk_weights,)),
+                *(() if recv_x_scales is None else (recv_x_scales,)),
+                *(() if recv_topk_weights is None else (recv_topk_weights,)),
+                *(
+                    ()
+                    if elastic_handle.token_metadata_at_forward is None
+                    else (elastic_handle.token_metadata_at_forward,)
+                ),
+                *(
+                    ()
+                    if elastic_handle.channel_linked_list is None
+                    else (elastic_handle.channel_linked_list,)
+                ),
+            )
+        return (
+            recv_x_out,
+            recv_topk_idx,
+            recv_topk_weights,
+            elastic_handle,
+            EventOverlap(event, tensors_to_record),
+        )
+
+    def combine(
+        self,
+        x: torch.Tensor,
+        handle: EPHandle,
+        topk_weights: Optional[torch.Tensor] = None,
+        num_sms: Optional[int] = None,
+        async_with_compute_stream: bool = False,
+    ) -> Tuple[torch.Tensor, Optional[torch.Tensor], EventOverlap]:
+        if self.runtime is None:
+            raise RuntimeError("ElasticBuffer has been destroyed")
+        self._validate_handle_generation(handle)
+        if handle.native_handle is None:
+            raise RuntimeError("Mooncake EPHandle does not contain a native handle")
+        assert x.dim() == 2 and x.is_contiguous()
+        assert x.dtype == torch.bfloat16
+        active_ranks = self._active_ranks
+        if topk_weights is None:
+            topk_weights = torch.ones_like(
+                handle.topk_idx, dtype=torch.float32, device=x.device
+            )
+        combined_x = torch.empty(
+            (handle.topk_idx.shape[0], x.shape[1]), dtype=x.dtype, device=x.device
+        )
+        event = self.runtime.combine(
+            x.data_ptr(),
+            x.shape[0],
+            x.shape[1],
+            handle.topk_idx.data_ptr(),
+            handle.topk_idx.shape[0],
+            handle.topk_idx.shape[1],
+            topk_weights.data_ptr(),
+            handle.psum_num_recv_tokens_per_scaleup_rank.data_ptr(),
+            handle.recv_src_metadata.data_ptr(),
+            0
+            if handle.token_metadata_at_forward is None
+            else handle.token_metadata_at_forward.data_ptr(),
+            0
+            if handle.channel_linked_list is None
+            else handle.channel_linked_list.data_ptr(),
+            active_ranks.data_ptr(),
+            handle.num_experts,
+            handle.num_max_tokens_per_rank,
+            handle.do_expand,
+            num_sms if num_sms is not None else handle.num_sms,
+            async_with_compute_stream,
+            _native_current_stream_ptr(),
+            combined_x.data_ptr(),
+        )
+        tensors_to_record = None
+        if async_with_compute_stream:
+            tensors_to_record = (
+                x,
+                topk_weights,
+                active_ranks,
+                combined_x,
+                handle.topk_idx,
+                handle.psum_num_recv_tokens_per_scaleup_rank,
+                handle.psum_num_recv_tokens_per_expert,
+                handle.recv_src_metadata,
+                handle.dst_buffer_slot_idx,
+                *(
+                    ()
+                    if handle.token_metadata_at_forward is None
+                    else (handle.token_metadata_at_forward,)
+                ),
+                *(
+                    ()
+                    if handle.channel_linked_list is None
+                    else (handle.channel_linked_list,)
+                ),
+            )
+        return (
+            combined_x,
+            None,
+            EventOverlap(event, tensors_to_record),
+        )
+
+
+__all__ = ["ElasticBuffer", "EPHandle", "EventOverlap"]
diff --git a/mooncake-wheel/mooncake/mooncake_ep_buffer.py b/python/mooncake/mooncake_ep_buffer.py
similarity index 79%
rename from mooncake-wheel/mooncake/mooncake_ep_buffer.py
rename to python/mooncake/mooncake_ep_buffer.py
index 8f9a720027..8df866a5cd 100644
--- a/mooncake-wheel/mooncake/mooncake_ep_buffer.py
+++ b/python/mooncake/mooncake_ep_buffer.py
@@ -1,7 +1,11 @@
 import os
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Tuple, Union
+
 import torch
 import torch.distributed as dist
-from typing import Any, Callable, List, Tuple, Optional, Union
+
+if TYPE_CHECKING:
+    from mooncake import ep
 
 
 def _env_enabled(name: str, default: bool = False) -> bool:
@@ -11,16 +15,25 @@ def _env_enabled(name: str, default: bool = False) -> bool:
     return value.upper() in {"1", "ON", "TRUE", "YES"}
 
 
-_USE_MACA = (
-    _env_enabled("MOONCAKE_EP_USE_MACA")
-    or bool(getattr(torch.version, "maca", None))
+_USE_MACA = _env_enabled("MOONCAKE_EP_USE_MACA") or bool(
+    getattr(torch.version, "maca", None)
 )
-_USE_SPLIT_SEND_RECV = (
-    _env_enabled("MOONCAKE_EP_USE_MUSA")
-    or _USE_MACA
+_USE_SPLIT_SEND_RECV = _USE_MACA
+
+_ZERO_COPY_COMBINE_UNSUPPORTED = (
+    "Mooncake EP zero-copy combine is not supported; pass the expert output "
+    "tensor to combine() with zero_copy=False"
 )
 
 
+def _native_current_stream_ptr() -> int:
+    return int(torch.cuda.current_stream().cuda_stream)
+
+
+def _wait_native_event_on_current_stream(event: "ep.EventHandle") -> None:
+    event.current_stream_wait(_native_current_stream_ptr())
+
+
 class EventOverlap:
     """
     A wrapper class to manage CUDA events, also for better overlapping convenience.
@@ -53,7 +66,7 @@ def current_stream_wait(self) -> None:
         The current stream `torch.cuda.current_stream()` waits for the event to be finished.
         """
         assert self.event is not None
-        self.event.current_stream_wait()
+        _wait_native_event_on_current_stream(self.event)
 
     def __enter__(self) -> Any:
         """
@@ -76,11 +89,16 @@ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         Please follow the example in the `__enter__` function.
         """
         if self.event is not None:
-            self.event.current_stream_wait()
+            _wait_native_event_on_current_stream(self.event)
 
 
 class Buffer:
-    def __init__(self, group: dist.ProcessGroup, num_ep_buffer_bytes: int = 0):
+    def __init__(
+        self,
+        group: dist.ProcessGroup,
+        num_ep_buffer_bytes: int = 0,
+        disable_p2p: bool = False,
+    ):
         from mooncake import ep
 
         # Initialize the CPP runtime
@@ -91,7 +109,7 @@ def __init__(self, group: dist.ProcessGroup, num_ep_buffer_bytes: int = 0):
         self.backend = self.group
         # NIC auto-detection happens inside ep.Buffer via Topology::discover().
         self.runtime = ep.Buffer(
-            self.rank, self.group_size, num_ep_buffer_bytes
+            self.rank, self.group_size, num_ep_buffer_bytes, disable_p2p
         )
         # Fallback flag and buffers.
         # Note: `sync_nvlink_ipc_handles()` can mutate C++ `ibgda_disabled_` (True->False when
@@ -139,11 +157,7 @@ def wait_send_done() -> None:
         for peer in range(self.group_size):
             if peer == self.rank:
                 continue
-            ops.append(
-                dist.P2POp(
-                    dist.isend, self._maca_phase_token, peer, self.group
-                )
-            )
+            ops.append(dist.P2POp(dist.isend, self._maca_phase_token, peer, self.group))
             ops.append(
                 dist.P2POp(
                     dist.irecv,
@@ -172,6 +186,7 @@ def connect(self, is_update: bool = False):
 
         if not self._use_fallback:
             (raddr, rkey) = self.runtime.get_mr_info()
+            # torchada maps the CUDA device namespace to MUSA when enabled.
 
             raddr = torch.tensor([raddr], dtype=torch.int64, device="cuda")
             raddrs = [
@@ -225,7 +240,9 @@ def connect(self, is_update: bool = False):
             peer_lids = [remote_lids[r].tolist() for r in range(self.group_size)]
 
             (subnet_prefix, interface_id) = self.runtime.get_gid()
-            subnet_prefix_t = torch.tensor([subnet_prefix], dtype=torch.int64, device="cuda")
+            subnet_prefix_t = torch.tensor(
+                [subnet_prefix], dtype=torch.int64, device="cuda"
+            )
             subnet_prefixes_list = [
                 torch.empty(1, dtype=torch.int64, device="cuda")
                 for _ in range(self.group_size)
@@ -233,7 +250,9 @@ def connect(self, is_update: bool = False):
             dist.all_gather(subnet_prefixes_list, subnet_prefix_t, self.group)
             subnet_prefixes = torch.cat(subnet_prefixes_list).tolist()
 
-            interface_id_t = torch.tensor([interface_id], dtype=torch.int64, device="cuda")
+            interface_id_t = torch.tensor(
+                [interface_id], dtype=torch.int64, device="cuda"
+            )
             interface_ids_list = [
                 torch.empty(1, dtype=torch.int64, device="cuda")
                 for _ in range(self.group_size)
@@ -243,8 +262,13 @@ def connect(self, is_update: bool = False):
 
             active_ranks_mask = self._active_ranks_list(torch.device("cuda"))
             self.runtime.sync_ibgda_peers(
-                raddrs, rkeys, peer_qpns, peer_lids,
-                subnet_prefixes, interface_ids, active_ranks_mask
+                raddrs,
+                rkeys,
+                peer_qpns,
+                peer_lids,
+                subnet_prefixes,
+                interface_ids,
+                active_ranks_mask,
             )
 
         if self.group_size == 1:
@@ -252,7 +276,7 @@ def connect(self, is_update: bool = False):
             # export also avoids unnecessary driver IPC calls on MACA.
             self._use_fallback = False
             return
-        else:
+        if self.runtime.p2p_enabled():
             try:
                 local_handle_ints = self.runtime.get_ipc_handle()
                 # pybind11 converts std::vector<int32_t> to a list of integers
@@ -260,7 +284,9 @@ def connect(self, is_update: bool = False):
                     local_handle_ints, dtype=torch.int32, device="cuda"
                 )
                 handles = [
-                    torch.empty(len(local_handle_ints), dtype=torch.int32, device="cuda")
+                    torch.empty(
+                        len(local_handle_ints), dtype=torch.int32, device="cuda"
+                    )
                     for _ in range(self.group_size)
                 ]
                 dist.all_gather(handles, local_handle_tensor, self.group)
@@ -275,6 +301,8 @@ def connect(self, is_update: bool = False):
                     RuntimeWarning,
                     stacklevel=2,
                 )
+        else:
+            return
 
         use_fast_path = False
         try:
@@ -316,7 +344,7 @@ def _active_ranks_tensor(
             return torch.ones((self.group_size,), dtype=dtype, device=device)
 
         try:
-            from mooncake.ep import get_active_ranks
+            from mooncake.pg import get_active_ranks
 
             return get_active_ranks(self.backend).to(device=device, dtype=dtype)
         except Exception:
@@ -357,15 +385,32 @@ def dispatch(
         EventOverlap,
         Callable,
     ]:
+        assert x.dim() == 2 and x.is_contiguous()
+        assert x.dtype == torch.bfloat16
+        assert topk_idx.dim() == 2 and topk_idx.is_contiguous()
+        assert topk_idx.dtype == torch.int64
+        assert x.size(0) == topk_idx.size(0)
+        assert x.size(0) <= num_max_dispatch_tokens_per_rank
+        assert x.size(1) % 16 == 0 and x.size(1) % 128 == 0
+        assert num_experts % self.group_size == 0
+        caller_active_ranks = active_ranks
+        if active_ranks is None:
+            active_ranks = self._active_ranks_tensor(device=x.device, dtype=torch.int32)
+        else:
+            assert active_ranks.dim() == 1 and active_ranks.is_contiguous()
+            assert active_ranks.dtype == torch.int32
+            if active_ranks.numel() != self.group_size:
+                active_ranks = torch.ones(
+                    (self.group_size,), dtype=torch.int32, device=x.device
+                )
+
         if use_fp8 is None:
             use_fp8 = not _USE_MACA
         elif _USE_MACA and use_fp8:
             raise NotImplementedError("FP8 dispatch is not supported on MACA")
 
-        # MUSA/MACA do not support cooperative grid sync, so the C++ runtime
-        # splits no-hook calls into SEND -> phase-ack -> RECV instead of using
-        # a single cooperative kernel.  async_finish still returns a stream
-        # event, but it is not the CUDA single-kernel cooperative path.
+        # MUSA and MACA use split SEND/RECV launches because they do not expose
+        # CUDA cooperative-grid synchronization. Only MACA adds a phase fence.
         if _USE_SPLIT_SEND_RECV and async_finish:
             import warnings
 
@@ -377,7 +422,7 @@ def dispatch(
             )
 
         runtime_return_recv_hook = return_recv_hook or (
-            _USE_MACA and not self._use_fallback
+            _USE_SPLIT_SEND_RECV and not self._use_fallback
         )
 
         if self._use_fallback:
@@ -400,29 +445,73 @@ def dispatch(
             backend_active_ranks = self._active_ranks_tensor(
                 device=active_ranks.device, dtype=active_ranks.dtype
             )
-            if active_ranks.numel() == backend_active_ranks.numel():
+            if (
+                caller_active_ranks is not None
+                and active_ranks.numel() == backend_active_ranks.numel()
+            ):
                 active_ranks.copy_(backend_active_ranks)
         else:
-            (
-                packed_recv_x,
-                packed_recv_x_scales,
-                packed_recv_count,
-                packed_recv_src_info,
-                packed_recv_layout_range,
-                event,
-                hook,
-            ) = self.runtime.dispatch(
-                x,
-                topk_idx,
-                active_ranks,
+            num_local_experts = num_experts // self.group_size
+            packed_recv_x = torch.empty(
+                (
+                    num_local_experts,
+                    self.group_size * num_max_dispatch_tokens_per_rank,
+                    x.size(1),
+                ),
+                dtype=torch.float8_e4m3fn if use_fp8 else torch.bfloat16,
+                device=x.device,
+            )
+            # The dispatch SEND phase resets every local-expert counter before
+            # the RECV phase reads it, so this output need not be pre-cleared.
+            packed_recv_count = torch.empty(
+                (num_local_experts,), dtype=torch.int32, device=x.device
+            )
+            packed_recv_src_info = torch.empty(
+                (
+                    num_local_experts,
+                    self.group_size * num_max_dispatch_tokens_per_rank,
+                ),
+                dtype=torch.int32,
+                device=x.device,
+            )
+            packed_recv_layout_range = torch.empty(
+                (num_local_experts, self.group_size),
+                dtype=torch.int64,
+                device=x.device,
+            )
+            packed_recv_x_scales = None
+            if use_fp8:
+                assert (self.group_size * num_max_dispatch_tokens_per_rank) % 4 == 0
+                packed_recv_x_scales = torch.empty(
+                    (
+                        num_local_experts,
+                        x.size(1) // 128,
+                        self.group_size * num_max_dispatch_tokens_per_rank,
+                    ),
+                    dtype=torch.float32,
+                    device=x.device,
+                ).transpose(1, 2)
+            event, hook = self.runtime.dispatch(
+                x.data_ptr(),
+                topk_idx.data_ptr(),
+                active_ranks.data_ptr(),
+                x.size(0),
+                x.size(1),
+                topk_idx.size(1),
                 num_max_dispatch_tokens_per_rank,
                 num_experts,
                 timeout_us,
                 use_fp8,
+                packed_recv_x.data_ptr(),
+                0 if packed_recv_x_scales is None else packed_recv_x_scales.data_ptr(),
+                packed_recv_count.data_ptr(),
+                packed_recv_src_info.data_ptr(),
+                packed_recv_layout_range.data_ptr(),
                 async_finish,
                 runtime_return_recv_hook,
+                _native_current_stream_ptr(),
             )
-            if _USE_MACA:
+            if _USE_SPLIT_SEND_RECV:
                 hook = self._wrap_maca_recv_hook(hook, event)
                 if not return_recv_hook:
                     hook()
@@ -447,7 +536,7 @@ def dispatch(
             (packed_recv_x, packed_recv_x_scales) if use_fp8 else packed_recv_x,
             packed_recv_count,
             handle,
-            EventOverlap(event, tensors_to_record if async_finish else None),
+            EventOverlap(event, tensors_to_record if async_finish or return_recv_hook else None),
             hook,
         )
 
@@ -465,6 +554,25 @@ def combine(
         return_recv_hook: bool = False,
         out: Optional[torch.Tensor] = None,
     ) -> Tuple[torch.Tensor, EventOverlap, Callable]:
+        if zero_copy:
+            raise NotImplementedError(_ZERO_COPY_COMBINE_UNSUPPORTED)
+
+        assert x.dim() == 3 and x.is_contiguous()
+        assert x.dtype == torch.bfloat16
+        assert topk_idx.dim() == 2 and topk_idx.is_contiguous()
+        assert topk_idx.dtype == torch.int64
+        assert topk_weights.dim() == 2 and topk_weights.is_contiguous()
+        assert topk_weights.dtype == torch.float32
+        caller_active_ranks = active_ranks
+        if active_ranks is None:
+            active_ranks = self._active_ranks_tensor(device=x.device, dtype=torch.int32)
+        else:
+            assert active_ranks.dim() == 1 and active_ranks.is_contiguous()
+            assert active_ranks.dtype == torch.int32
+            if active_ranks.numel() != self.group_size:
+                active_ranks = torch.ones(
+                    (self.group_size,), dtype=torch.int32, device=x.device
+                )
         # Same split-kernel behavior as dispatch().
         if _USE_SPLIT_SEND_RECV and async_finish:
             import warnings
@@ -484,7 +592,7 @@ def combine(
             num_experts,
         ) = handle
         runtime_return_recv_hook = return_recv_hook or (
-            _USE_MACA and not self._use_fallback
+            _USE_SPLIT_SEND_RECV and not self._use_fallback
         )
 
         if self._use_fallback:
@@ -503,25 +611,58 @@ def combine(
             backend_active_ranks = self._active_ranks_tensor(
                 device=active_ranks.device, dtype=active_ranks.dtype
             )
-            if active_ranks.numel() == backend_active_ranks.numel():
+            if (
+                caller_active_ranks is not None
+                and active_ranks.numel() == backend_active_ranks.numel()
+            ):
                 active_ranks.copy_(backend_active_ranks)
         else:
-            combined_x, event, hook = self.runtime.combine(
-                x,
-                topk_idx,
-                topk_weights,
-                src_info,
-                layout_range,
-                active_ranks,
+            assert x.size(0) == num_experts // self.group_size
+            assert x.size(1) == self.group_size * num_max_dispatch_tokens_per_rank
+            assert x.size(2) == hidden
+            assert x.size(2) % 16 == 0 and x.size(2) % 128 == 0
+            assert topk_idx.size() == topk_weights.size()
+            assert topk_weights.size(0) <= num_max_dispatch_tokens_per_rank
+            assert src_info.dim() == 2 and src_info.is_contiguous()
+            assert src_info.dtype == torch.int32
+            assert src_info.size(0) == x.size(0)
+            assert layout_range.dim() == 2 and layout_range.is_contiguous()
+            assert layout_range.dtype == torch.int64
+            assert layout_range.size(0) == num_experts // self.group_size
+            assert layout_range.size(1) == self.group_size
+            combined_x = (
+                out
+                if out is not None
+                else torch.empty(
+                    (topk_weights.size(0), hidden), dtype=x.dtype, device=x.device
+                )
+            )
+            if out is not None:
+                assert out.dim() == 2 and out.is_contiguous()
+                assert out.size(0) == topk_weights.size(0)
+                assert out.size(1) == hidden
+                assert out.dtype == x.dtype
+            event, hook = self.runtime.combine(
+                x.data_ptr(),
+                topk_idx.data_ptr(),
+                topk_weights.data_ptr(),
+                src_info.data_ptr(),
+                layout_range.data_ptr(),
+                active_ranks.data_ptr(),
+                x.size(0),
+                topk_weights.size(0),
+                hidden,
+                topk_weights.size(1),
                 num_max_dispatch_tokens_per_rank,
                 num_experts,
                 timeout_us,
                 zero_copy,
+                combined_x.data_ptr(),
                 async_finish,
                 runtime_return_recv_hook,
-                out,
+                _native_current_stream_ptr(),
             )
-            if _USE_MACA:
+            if _USE_SPLIT_SEND_RECV:
                 hook = self._wrap_maca_recv_hook(hook, event)
                 if not return_recv_hook:
                     hook()
@@ -536,47 +677,21 @@ def combine(
         )
         return (
             combined_x,
-            EventOverlap(event, tensors_to_record if async_finish else None),
+            EventOverlap(event, tensors_to_record if async_finish or return_recv_hook else None),
             hook,
         )
 
     def get_next_combine_buffer(self, handle: object):
-        (
-            src_info,
-            layout_range,
-            num_max_dispatch_tokens_per_rank,
-            hidden,
-            num_experts,
-        ) = handle
-        if self._use_fallback:
-            if (
-                self._fallback_next_combine_buffer is None
-                or self._fallback_next_combine_buffer.shape
-                != (
-                    num_experts // self.group_size,
-                    num_max_dispatch_tokens_per_rank * self.group_size,
-                    hidden,
-                )
-            ):
-                self._fallback_next_combine_buffer = torch.empty(
-                    (
-                        num_experts // self.group_size,
-                        num_max_dispatch_tokens_per_rank * self.group_size,
-                        hidden,
-                    ),
-                    dtype=torch.bfloat16,
-                    device="cuda",
-                )
-            return self._fallback_next_combine_buffer
-        return self.runtime.get_next_combine_buffer(
-            num_max_dispatch_tokens_per_rank, hidden, num_experts
-        )
+        raise NotImplementedError(_ZERO_COPY_COMBINE_UNSUPPORTED)
 
     # -----------------
     # Fallback helpers
     # -----------------
     class _DummyEvent:
-        def current_stream_wait(self):
+        def current_stream_wait(self, stream_ptr: Optional[int] = None):
+            torch.cuda.synchronize()
+
+        def synchronize(self):
             torch.cuda.synchronize()
 
     @staticmethod
diff --git a/mooncake-wheel/mooncake/mooncake_ssd_register.py b/python/mooncake/mooncake_ssd_register.py
similarity index 65%
rename from mooncake-wheel/mooncake/mooncake_ssd_register.py
rename to python/mooncake/mooncake_ssd_register.py
index bd49ee58e9..13d424dd21 100644
--- a/mooncake-wheel/mooncake/mooncake_ssd_register.py
+++ b/python/mooncake/mooncake_ssd_register.py
@@ -8,7 +8,7 @@
 import shlex
 from typing import List, Dict, Any
 
-import paramiko
+from mooncake._administration import require_paramiko
 
 from mooncake.store import MooncakeDistributedNoFRegister
 
@@ -29,9 +29,11 @@ def __init__(self, cli_config: dict = None, spdk_targets: List[str] = None):
             # Only support getting SSD info from remote SPDK targets
             if self.spdk_targets:
                 # Get SSD info from remote SPDK targets
-                master_server_address = self.cli_config.get('master_server_address')
+                master_server_address = self.cli_config.get("master_server_address")
                 if not master_server_address:
-                    raise ValueError("master_server_address is required when using spdk_target_info")
+                    raise ValueError(
+                        "master_server_address is required when using spdk_target_info"
+                    )
                 self.config_list = self._get_remote_ssd_info(master_server_address)
             else:
                 raise ValueError("spdk_target_info is required")
@@ -57,8 +59,6 @@ def __init__(self, cli_config: dict = None, spdk_targets: List[str] = None):
             logging.error("Configuration load failed: %s", e)
             raise
 
-
-
     def _remove_duplicate_ssds(self):
         """
         Remove duplicate SSD configurations from the config list
@@ -68,24 +68,24 @@ def _remove_duplicate_ssds(self):
 
         for config in self.config_list:
             # Generate unique key directly without calling _get_ssd_unique_key
-            key = (config['nqn'], config['nsid'], config['traddr'], config['trsvcid'])
+            key = (config["nqn"], config["nsid"], config["traddr"], config["trsvcid"])
             if key not in seen_keys:
                 seen_keys.add(key)
                 unique_configs.append(config)
 
         if len(unique_configs) < len(self.config_list):
-            logging.info(f"Removed {len(self.config_list) - len(unique_configs)} duplicate SSD configuration(s)")
+            logging.info(
+                f"Removed {len(self.config_list) - len(unique_configs)} duplicate SSD configuration(s)"
+            )
 
         self.config_list = unique_configs
 
-
-
     def _parse_spdk_target_info(self, target_info: str) -> Dict[str, str]:
         """
         Parse spdk target info string like "ip:192.168.65.56 path:/home"
         """
         result = {}
-        parts = re.findall(r'(\w+):([^\s]+)', target_info)
+        parts = re.findall(r"(\w+):([^\s]+)", target_info)
         for key, value in parts:
             result[key] = value
         return result
@@ -94,22 +94,23 @@ def _execute_ssh_command(self, ip: str, command: str, path: str) -> str:
         """
         Execute command on remote server via SSH
         """
+        paramiko = require_paramiko()
         ssh = paramiko.SSHClient()
         ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
         try:
             ssh.connect(
                 ip,
-                port=int(self.cli_config.get('port', 22)),
-                username=self.cli_config.get('username', 'root'),
-                password=self.cli_config.get('password'),
-                key_filename=self.cli_config.get('key_file'),
-                timeout=10
+                port=int(self.cli_config.get("port", 22)),
+                username=self.cli_config.get("username", "root"),
+                password=self.cli_config.get("password"),
+                key_filename=self.cli_config.get("key_file"),
+                timeout=10,
             )
 
             # Try multiple possible paths to find the RPC script
             possible_paths = [
                 path,  # Direct path provided by user
-                f"{path}/spdk"  # Common case: spdk is a subdirectory
+                f"{path}/spdk",  # Common case: spdk is a subdirectory
             ]
 
             for test_path in possible_paths:
@@ -120,15 +121,17 @@ def _execute_ssh_command(self, ip: str, command: str, path: str) -> str:
                     full_command = f"cd {shlex.quote(test_path)} && {command}"
                     stdin, stdout, stderr = ssh.exec_command(full_command, timeout=30)
                     exit_status = stdout.channel.recv_exit_status()
-                    output = stdout.read().decode('utf-8')
-                    error = stderr.read().decode('utf-8')
+                    output = stdout.read().decode("utf-8")
+                    error = stderr.read().decode("utf-8")
                     if exit_status != 0:
                         logging.error(f"SSH command error on {ip}: {error}")
                         raise RuntimeError(f"SSH command failed: {error or output}")
                     return output
 
             # If we get here, none of the paths worked
-            raise RuntimeError(f"Could not find scripts/rpc.py in any of the possible paths: {possible_paths}")
+            raise RuntimeError(
+                f"Could not find scripts/rpc.py in any of the possible paths: {possible_paths}"
+            )
         finally:
             ssh.close()
 
@@ -140,8 +143,8 @@ def _get_remote_ssd_info(self, master_server_address: str) -> List[Dict[str, Any
 
         for target_info in self.spdk_targets:
             target = self._parse_spdk_target_info(target_info)
-            ip = target.get('ip')
-            path = target.get('path')
+            ip = target.get("ip")
+            path = target.get("path")
 
             if not ip or not path:
                 logging.error(f"Invalid target info: {target_info}")
@@ -157,27 +160,27 @@ def _get_remote_ssd_info(self, master_server_address: str) -> List[Dict[str, Any
 
                 # Process each subsystem
                 for subsystem in subsystems:
-                    if subsystem.get('subtype') != 'NVMe':
+                    if subsystem.get("subtype") != "NVMe":
                         continue
 
-                    nqn = subsystem.get('nqn')
-                    listen_addresses = subsystem.get('listen_addresses', [])
+                    nqn = subsystem.get("nqn")
+                    listen_addresses = subsystem.get("listen_addresses", [])
 
                     if not nqn or not listen_addresses:
                         continue
 
                     # Get transport info from first listen address
-                    traddr = listen_addresses[0].get('traddr')
-                    trsvcid = listen_addresses[0].get('trsvcid')
+                    traddr = listen_addresses[0].get("traddr")
+                    trsvcid = listen_addresses[0].get("trsvcid")
 
                     if not traddr or not trsvcid:
                         continue
 
                     # Process each namespace
-                    namespaces = subsystem.get('namespaces', [])
+                    namespaces = subsystem.get("namespaces", [])
                     for namespace in namespaces:
-                        nsid = namespace.get('nsid')
-                        bdev_name = namespace.get('bdev_name')
+                        nsid = namespace.get("nsid")
+                        bdev_name = namespace.get("bdev_name")
 
                         if not nsid or not bdev_name:
                             continue
@@ -191,24 +194,26 @@ def _get_remote_ssd_info(self, master_server_address: str) -> List[Dict[str, Any
                             continue
 
                         bdev = bdevs[0]
-                        block_size = bdev.get('block_size', 512)
-                        num_blocks = bdev.get('num_blocks', 0)
+                        block_size = bdev.get("block_size", 512)
+                        num_blocks = bdev.get("num_blocks", 0)
                         size = block_size * num_blocks
 
                         # Create SSD config
                         ssd_config = {
-                            'nqn': nqn,
-                            'nsid': nsid,
-                            'traddr': traddr,
-                            'trsvcid': int(trsvcid),  # Ensure trsvcid is integer
-                            'base': 0,
-                            'size': size,
-                            'master_server_address': master_server_address,
-                            'metadata_server': ''
+                            "nqn": nqn,
+                            "nsid": nsid,
+                            "traddr": traddr,
+                            "trsvcid": int(trsvcid),  # Ensure trsvcid is integer
+                            "base": 0,
+                            "size": size,
+                            "master_server_address": master_server_address,
+                            "metadata_server": "",
                         }
 
                         ssd_configs.append(ssd_config)
-                        logging.info(f"Found SSD: nqn={nqn}, nsid={nsid}, traddr={traddr}, size={size}")
+                        logging.info(
+                            f"Found SSD: nqn={nqn}, nsid={nsid}, traddr={traddr}, size={size}"
+                        )
 
             except Exception as e:
                 logging.error(f"Failed to get SSD info from {ip}: {e}")
@@ -222,7 +227,7 @@ def _get_remote_ssd_info(self, master_server_address: str) -> List[Dict[str, Any
     def _setup_logging(self):
         logging.basicConfig(
             level=logging.INFO,
-            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         )
 
     def start_ssd_service(self):
@@ -233,7 +238,13 @@ def start_ssd_service(self):
 
         for i, cfg in enumerate(self.config_list):
             try:
-                logging.info("Registering SSD %d/%d: nqn=%s, traddr=%s", i + 1, total, cfg.get("nqn"), cfg.get("traddr"))
+                logging.info(
+                    "Registering SSD %d/%d: nqn=%s, traddr=%s",
+                    i + 1,
+                    total,
+                    cfg.get("nqn"),
+                    cfg.get("traddr"),
+                )
 
                 # Create register instance and register SSD
                 self.register = MooncakeDistributedNoFRegister()
@@ -244,7 +255,7 @@ def start_ssd_service(self):
                     cfg["trsvcid"],
                     cfg["base"],
                     cfg["size"],
-                    cfg["master_server_address"]
+                    cfg["master_server_address"],
                 )
 
                 if ret != 0:
@@ -255,9 +266,16 @@ def start_ssd_service(self):
 
             except Exception as e:
                 # Check if the error is due to the segment already existing on the server
-                if "SEGMENT_ALREADY_EXISTS" in str(e) or "segment already exists" in str(e):
-                    logging.info("SSD %d/%d (nqn=%s, traddr=%s) already registered on server, skipping",
-                                i + 1, total, cfg.get("nqn"), cfg.get("traddr"))
+                if "SEGMENT_ALREADY_EXISTS" in str(
+                    e
+                ) or "segment already exists" in str(e):
+                    logging.info(
+                        "SSD %d/%d (nqn=%s, traddr=%s) already registered on server, skipping",
+                        i + 1,
+                        total,
+                        cfg.get("nqn"),
+                        cfg.get("traddr"),
+                    )
                     skipped_count += 1
                 else:
                     logging.error("Failed to register SSD %d/%d: %s", i + 1, total, e)
@@ -275,24 +293,37 @@ def start_ssd_service(self):
 
 
 def parse_arguments():
-    parser = argparse.ArgumentParser(description='Mooncake SSD Register with REST API')
-    parser.add_argument('--master_server_address', type=str,
-                        help='Master server address (e.g., 192.168.65.81:50051)',
-                        required=True)
-    parser.add_argument('--spdk_target_info', action='append',
-                        help='SPDK target information (e.g., "ip:192.168.65.56 path:/home")',
-                        required=True)
-    parser.add_argument('--username', type=str, default='root',
-                        help='SSH username for target nodes (default: root)')
-    parser.add_argument('--port', type=int, default=22,
-                        help='SSH port for target nodes (default: 22)')
-    parser.add_argument('--password', type=str,
-                        help='SSH password for target nodes')
-    parser.add_argument('--key-file', type=str,
-                        help='SSH private key file path')
-    parser.add_argument('-D', '--define', action='append',
-                        help='Override configuration fields globally (e.g., -Dtrsvcid=4420)',
-                        default=[])
+    parser = argparse.ArgumentParser(description="Mooncake SSD Register with REST API")
+    parser.add_argument(
+        "--master_server_address",
+        type=str,
+        help="Master server address (e.g., 192.168.65.81:50051)",
+        required=True,
+    )
+    parser.add_argument(
+        "--spdk_target_info",
+        action="append",
+        help='SPDK target information (e.g., "ip:192.168.65.56 path:/home")',
+        required=True,
+    )
+    parser.add_argument(
+        "--username",
+        type=str,
+        default="root",
+        help="SSH username for target nodes (default: root)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=22, help="SSH port for target nodes (default: 22)"
+    )
+    parser.add_argument("--password", type=str, help="SSH password for target nodes")
+    parser.add_argument("--key-file", type=str, help="SSH private key file path")
+    parser.add_argument(
+        "-D",
+        "--define",
+        action="append",
+        help="Override configuration fields globally (e.g., -Dtrsvcid=4420)",
+        default=[],
+    )
     return parser.parse_args()
 
 
@@ -301,26 +332,27 @@ def main():
 
     cli_config = {}
     for item in args.define:
-        if '=' in item:
-            key, value = item.split('=', 1)
+        if "=" in item:
+            key, value = item.split("=", 1)
             cli_config[key] = value
         else:
             logging.warning(f"Ignoring invalid CLI config: {item}")
 
     # Add master_server_address to cli_config if provided
     if args.master_server_address:
-        cli_config['master_server_address'] = args.master_server_address
-    cli_config['username'] = args.username
-    cli_config['port'] = args.port
+        cli_config["master_server_address"] = args.master_server_address
+    cli_config["username"] = args.username
+    cli_config["port"] = args.port
     if args.password:
-        cli_config['password'] = args.password
+        cli_config["password"] = args.password
     if args.key_file:
-        cli_config['key_file'] = args.key_file
+        cli_config["key_file"] = args.key_file
 
     register = MooncakeNoFRegister(cli_config, args.spdk_target_info)
     success = register.start_ssd_service()
     if not success:
         exit(1)
 
+
 if __name__ == "__main__":
     main()
diff --git a/mooncake-wheel/mooncake/mooncake_ssd_unregister.py b/python/mooncake/mooncake_ssd_unregister.py
similarity index 59%
rename from mooncake-wheel/mooncake/mooncake_ssd_unregister.py
rename to python/mooncake/mooncake_ssd_unregister.py
index 3c8a42d330..1599dce5f9 100644
--- a/mooncake-wheel/mooncake/mooncake_ssd_unregister.py
+++ b/python/mooncake/mooncake_ssd_unregister.py
@@ -7,7 +7,7 @@
 import shlex
 from typing import List, Dict, Any
 
-import paramiko
+from mooncake._administration import require_paramiko
 
 from mooncake.store import MooncakeDistributedNoFRegister
 
@@ -28,9 +28,11 @@ def __init__(self, cli_config: dict = None, spdk_targets: List[str] = None):
             # Only support getting SSD info from command line
             if self.spdk_targets:
                 # Get SSD info from command line parameters
-                master_server_address = self.cli_config.get('master_server_address')
+                master_server_address = self.cli_config.get("master_server_address")
                 if not master_server_address:
-                    raise ValueError("master_server_address is required when using spdk_target_info")
+                    raise ValueError(
+                        "master_server_address is required when using spdk_target_info"
+                    )
                 self.config_list = self._parse_spdk_targets(master_server_address)
             else:
                 raise ValueError("spdk_target_info is required")
@@ -51,7 +53,9 @@ def __init__(self, cli_config: dict = None, spdk_targets: List[str] = None):
             # Remove duplicate SSDs based on their unique identifiers
             self._remove_duplicate_ssds()
 
-            logging.info("Loaded %d SSD configuration(s) to unregister", len(self.config_list))
+            logging.info(
+                "Loaded %d SSD configuration(s) to unregister", len(self.config_list)
+            )
         except Exception as e:
             logging.error("Configuration load failed: %s", e)
             raise
@@ -65,13 +69,15 @@ def _remove_duplicate_ssds(self):
 
         for config in self.config_list:
             # Generate unique key directly
-            key = (config['nqn'], config['nsid'], config['traddr'], config['trsvcid'])
+            key = (config["nqn"], config["nsid"], config["traddr"], config["trsvcid"])
             if key not in seen_keys:
                 seen_keys.add(key)
                 unique_configs.append(config)
 
         if len(unique_configs) < len(self.config_list):
-            logging.info(f"Removed {len(self.config_list) - len(unique_configs)} duplicate SSD configuration(s)")
+            logging.info(
+                f"Removed {len(self.config_list) - len(unique_configs)} duplicate SSD configuration(s)"
+            )
 
         self.config_list = unique_configs
 
@@ -79,22 +85,23 @@ def _execute_ssh_command(self, ip: str, command: str, path: str) -> str:
         """
         Execute command on remote server via SSH
         """
+        paramiko = require_paramiko()
         ssh = paramiko.SSHClient()
         ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
         try:
             ssh.connect(
                 ip,
-                port=int(self.cli_config.get('port', 22)),
-                username=self.cli_config.get('username', 'root'),
-                password=self.cli_config.get('password'),
-                key_filename=self.cli_config.get('key_file'),
-                timeout=10
+                port=int(self.cli_config.get("port", 22)),
+                username=self.cli_config.get("username", "root"),
+                password=self.cli_config.get("password"),
+                key_filename=self.cli_config.get("key_file"),
+                timeout=10,
             )
 
             # Try multiple possible paths to find the RPC script
             possible_paths = [
                 path,  # Direct path provided by user
-                f"{path}/spdk"  # Common case: spdk is a subdirectory
+                f"{path}/spdk",  # Common case: spdk is a subdirectory
             ]
 
             for test_path in possible_paths:
@@ -105,15 +112,17 @@ def _execute_ssh_command(self, ip: str, command: str, path: str) -> str:
                     full_command = f"cd {shlex.quote(test_path)} && {command}"
                     stdin, stdout, stderr = ssh.exec_command(full_command, timeout=30)
                     exit_status = stdout.channel.recv_exit_status()
-                    output = stdout.read().decode('utf-8')
-                    error = stderr.read().decode('utf-8')
+                    output = stdout.read().decode("utf-8")
+                    error = stderr.read().decode("utf-8")
                     if exit_status != 0:
                         logging.error(f"SSH command error on {ip}: {error}")
                         raise RuntimeError(f"SSH command failed: {error or output}")
                     return output
 
             # If we get here, none of the paths worked
-            raise RuntimeError(f"Could not find scripts/rpc.py in any of the possible paths: {possible_paths}")
+            raise RuntimeError(
+                f"Could not find scripts/rpc.py in any of the possible paths: {possible_paths}"
+            )
         finally:
             ssh.close()
 
@@ -129,123 +138,137 @@ def _parse_spdk_targets(self, master_server_address: str) -> List[Dict[str, Any]
             target = {}
             parts = target_info.split()
             for part in parts:
-                if ':' in part:
-                    key, value = part.split(':', 1)
+                if ":" in part:
+                    key, value = part.split(":", 1)
                     target[key.strip()] = value.strip()
 
             # Validate required fields
-            if 'ip' not in target:
+            if "ip" not in target:
                 raise ValueError("spdk_target_info must contain 'ip' field")
 
-            ip = target['ip']
-            specified_ns = int(target['ns']) if 'ns' in target else None
-            path = target.get('path')
+            ip = target["ip"]
+            specified_ns = int(target["ns"]) if "ns" in target else None
+            path = target.get("path")
 
             # We need to know the NQN to build the te_endpoint
             # For now, we'll use a default NQN pattern (this should be improved)
             default_nqn = "nqn.2016-06.io.spdk:cnode1"
-            nqn = target.get('nqn', default_nqn)
+            nqn = target.get("nqn", default_nqn)
 
             # Default transport parameters
-            trsvcid = int(target.get('port', '4420'))
+            trsvcid = int(target.get("port", "4420"))
 
             # Create SSD config for each namespace (or specified ns only)
             if specified_ns is not None:
                 # Unregister specific namespace
                 ssd_config = {
-                    'nqn': nqn,
-                    'nsid': specified_ns,
-                    'traddr': ip,
-                    'trsvcid': trsvcid,
-                    'base': 0,
-                    'size': 0,  # Size is not needed for unregister
-                    'master_server_address': master_server_address,
-                    'metadata_server': ''
+                    "nqn": nqn,
+                    "nsid": specified_ns,
+                    "traddr": ip,
+                    "trsvcid": trsvcid,
+                    "base": 0,
+                    "size": 0,  # Size is not needed for unregister
+                    "master_server_address": master_server_address,
+                    "metadata_server": "",
                 }
                 ssd_configs.append(ssd_config)
-                logging.info(f"Will unregister SSD: nqn={nqn}, nsid={specified_ns}, traddr={ip}")
+                logging.info(
+                    f"Will unregister SSD: nqn={nqn}, nsid={specified_ns}, traddr={ip}"
+                )
             elif path is not None:
                 # Get actual namespaces from SPDK target
                 logging.info(f"Getting namespace info from target: {ip} (path: {path})")
                 try:
                     # Get subsystems info
                     subsystems_cmd = "./scripts/rpc.py nvmf_get_subsystems"
-                    subsystems_output = self._execute_ssh_command(ip, subsystems_cmd, path)
+                    subsystems_output = self._execute_ssh_command(
+                        ip, subsystems_cmd, path
+                    )
                     subsystems = json.loads(subsystems_output)
 
                     # Process each subsystem
                     for subsystem in subsystems:
-                        if subsystem.get('subtype') != 'NVMe':
+                        if subsystem.get("subtype") != "NVMe":
                             continue
 
-                        subsystem_nqn = subsystem.get('nqn')
-                        listen_addresses = subsystem.get('listen_addresses', [])
+                        subsystem_nqn = subsystem.get("nqn")
+                        listen_addresses = subsystem.get("listen_addresses", [])
 
                         if not subsystem_nqn or not listen_addresses:
                             continue
 
                         # Get transport info from first listen address
-                        traddr = listen_addresses[0].get('traddr')
-                        target_trsvcid = listen_addresses[0].get('trsvcid')
+                        traddr = listen_addresses[0].get("traddr")
+                        target_trsvcid = listen_addresses[0].get("trsvcid")
 
                         if not traddr or not target_trsvcid:
                             continue
 
                         # Use the nqn from the subsystem if not specified
                         current_nqn = nqn if nqn != default_nqn else subsystem_nqn
-                        current_trsvcid = int(target_trsvcid) if target_trsvcid else trsvcid
+                        current_trsvcid = (
+                            int(target_trsvcid) if target_trsvcid else trsvcid
+                        )
 
                         # Process each namespace
-                        namespaces = subsystem.get('namespaces', [])
+                        namespaces = subsystem.get("namespaces", [])
                         for namespace in namespaces:
-                            nsid = namespace.get('nsid')
+                            nsid = namespace.get("nsid")
 
                             if not nsid:
                                 continue
 
                             # Create SSD config
                             ssd_config = {
-                                'nqn': current_nqn,
-                                'nsid': nsid,
-                                'traddr': traddr,
-                                'trsvcid': current_trsvcid,
-                                'base': 0,
-                                'size': 0,  # Size is not needed for unregister
-                                'master_server_address': master_server_address,
-                                'metadata_server': ''
+                                "nqn": current_nqn,
+                                "nsid": nsid,
+                                "traddr": traddr,
+                                "trsvcid": current_trsvcid,
+                                "base": 0,
+                                "size": 0,  # Size is not needed for unregister
+                                "master_server_address": master_server_address,
+                                "metadata_server": "",
                             }
                             ssd_configs.append(ssd_config)
-                            logging.info(f"Will unregister SSD: nqn={current_nqn}, nsid={nsid}, traddr={traddr}")
+                            logging.info(
+                                f"Will unregister SSD: nqn={current_nqn}, nsid={nsid}, traddr={traddr}"
+                            )
 
                 except Exception as e:
                     logging.error(f"Failed to get namespace info from {ip}: {e}")
-                    logging.warning("Falling back to unregistering default namespace (nsid=1)")
+                    logging.warning(
+                        "Falling back to unregistering default namespace (nsid=1)"
+                    )
                     # Fall back to unregistering default namespace
                     ssd_config = {
-                        'nqn': nqn,
-                        'nsid': 1,
-                        'traddr': ip,
-                        'trsvcid': trsvcid,
-                        'base': 0,
-                        'size': 0,
-                        'master_server_address': master_server_address,
-                        'metadata_server': ''
+                        "nqn": nqn,
+                        "nsid": 1,
+                        "traddr": ip,
+                        "trsvcid": trsvcid,
+                        "base": 0,
+                        "size": 0,
+                        "master_server_address": master_server_address,
+                        "metadata_server": "",
                     }
                     ssd_configs.append(ssd_config)
-                    logging.info(f"Will unregister SSD (fallback): nqn={nqn}, nsid=1, traddr={ip}")
+                    logging.info(
+                        f"Will unregister SSD (fallback): nqn={nqn}, nsid=1, traddr={ip}"
+                    )
             else:
                 # No path provided, unregister default namespace only
-                logging.warning("No 'path' provided in spdk_target_info, cannot query actual namespaces from SPDK target")
+                logging.warning(
+                    "No 'path' provided in spdk_target_info, cannot query actual namespaces from SPDK target"
+                )
                 logging.warning("Will unregister default namespace (nsid=1) only")
                 ssd_config = {
-                    'nqn': nqn,
-                    'nsid': 1,
-                    'traddr': ip,
-                    'trsvcid': trsvcid,
-                    'base': 0,
-                    'size': 0,
-                    'master_server_address': master_server_address,
-                    'metadata_server': ''
+                    "nqn": nqn,
+                    "nsid": 1,
+                    "traddr": ip,
+                    "trsvcid": trsvcid,
+                    "base": 0,
+                    "size": 0,
+                    "master_server_address": master_server_address,
+                    "metadata_server": "",
                 }
                 ssd_configs.append(ssd_config)
                 logging.info(f"Will unregister SSD: nqn={nqn}, nsid=1, traddr={ip}")
@@ -258,7 +281,7 @@ def _parse_spdk_targets(self, master_server_address: str) -> List[Dict[str, Any]
     def _setup_logging(self):
         logging.basicConfig(
             level=logging.INFO,
-            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         )
 
     def start_ssd_unregister_service(self):
@@ -268,7 +291,14 @@ def start_ssd_unregister_service(self):
 
         for i, cfg in enumerate(self.config_list):
             try:
-                logging.info("Unregistering SSD %d/%d: nqn=%s, traddr=%s, nsid=%d", i + 1, total, cfg.get("nqn"), cfg.get("traddr"), cfg.get("nsid"))
+                logging.info(
+                    "Unregistering SSD %d/%d: nqn=%s, traddr=%s, nsid=%d",
+                    i + 1,
+                    total,
+                    cfg.get("nqn"),
+                    cfg.get("traddr"),
+                    cfg.get("nsid"),
+                )
 
                 # Create register instance and unregister SSD
                 self.register = MooncakeDistributedNoFRegister()
@@ -277,7 +307,7 @@ def start_ssd_unregister_service(self):
                     cfg["nsid"],
                     cfg["traddr"],
                     cfg["trsvcid"],
-                    cfg["master_server_address"]
+                    cfg["master_server_address"],
                 )
 
                 if ret != 0:
@@ -301,29 +331,44 @@ def start_ssd_unregister_service(self):
 
 
 def parse_arguments():
-    parser = argparse.ArgumentParser(description='Mooncake SSD Unregister with REST API')
-    parser.add_argument('--master_server_address', type=str,
-                        help='Master server address (e.g., 192.168.65.81:50051)',
-                        default='192.168.65.81:50051')
-    parser.add_argument('--spdk_target_info', action='append',
-                        help='SPDK target information (e.g., "ip:192.168.65.56 ns:2 nqn:nqn.2016-06.io.spdk:cnode1" or "ip:192.168.65.56 path:/home/spdk")',
-                        default=None)
-    parser.add_argument('--username', type=str, default='root',
-                        help='SSH username for target nodes (default: root)')
-    parser.add_argument('--port', type=int, default=22,
-                        help='SSH port for target nodes (default: 22)')
-    parser.add_argument('--password', type=str,
-                        help='SSH password for target nodes')
-    parser.add_argument('--key-file', type=str,
-                        help='SSH private key file path')
-    parser.add_argument('-D', '--define', action='append',
-                        help='Override configuration fields globally (e.g., -Dtrsvcid=4420)',
-                        default=[])
+    parser = argparse.ArgumentParser(
+        description="Mooncake SSD Unregister with REST API"
+    )
+    parser.add_argument(
+        "--master_server_address",
+        type=str,
+        help="Master server address (e.g., 192.168.65.81:50051)",
+        default="192.168.65.81:50051",
+    )
+    parser.add_argument(
+        "--spdk_target_info",
+        action="append",
+        help='SPDK target information (e.g., "ip:192.168.65.56 ns:2 nqn:nqn.2016-06.io.spdk:cnode1" or "ip:192.168.65.56 path:/home/spdk")',
+        default=None,
+    )
+    parser.add_argument(
+        "--username",
+        type=str,
+        default="root",
+        help="SSH username for target nodes (default: root)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=22, help="SSH port for target nodes (default: 22)"
+    )
+    parser.add_argument("--password", type=str, help="SSH password for target nodes")
+    parser.add_argument("--key-file", type=str, help="SSH private key file path")
+    parser.add_argument(
+        "-D",
+        "--define",
+        action="append",
+        help="Override configuration fields globally (e.g., -Dtrsvcid=4420)",
+        default=[],
+    )
     args = parser.parse_args()
 
     # If no spdk_target_info is provided, use default
     if args.spdk_target_info is None:
-        args.spdk_target_info = ['ip:192.168.65.56 ns:1 nqn:nqn.2016-06.io.spdk:cnode1']
+        args.spdk_target_info = ["ip:192.168.65.56 ns:1 nqn:nqn.2016-06.io.spdk:cnode1"]
 
     return args
 
@@ -333,26 +378,27 @@ def main():
 
     cli_config = {}
     for item in args.define:
-        if '=' in item:
-            key, value = item.split('=', 1)
+        if "=" in item:
+            key, value = item.split("=", 1)
             cli_config[key] = value
         else:
             logging.warning(f"Ignoring invalid CLI config: {item}")
 
     # Add master_server_address to cli_config if provided
     if args.master_server_address:
-        cli_config['master_server_address'] = args.master_server_address
-    cli_config['username'] = args.username
-    cli_config['port'] = args.port
+        cli_config["master_server_address"] = args.master_server_address
+    cli_config["username"] = args.username
+    cli_config["port"] = args.port
     if args.password:
-        cli_config['password'] = args.password
+        cli_config["password"] = args.password
     if args.key_file:
-        cli_config['key_file'] = args.key_file
+        cli_config["key_file"] = args.key_file
 
     unregister = MooncakeNoFUnregister(cli_config, args.spdk_target_info)
     success = unregister.start_ssd_unregister_service()
     if not success:
         exit(1)
 
+
 if __name__ == "__main__":
     main()
diff --git a/mooncake-wheel/mooncake/spdk_tgt_create.py b/python/mooncake/spdk_tgt_create.py
similarity index 55%
rename from mooncake-wheel/mooncake/spdk_tgt_create.py
rename to python/mooncake/spdk_tgt_create.py
index f5d8554369..302496425b 100644
--- a/mooncake-wheel/mooncake/spdk_tgt_create.py
+++ b/python/mooncake/spdk_tgt_create.py
@@ -2,13 +2,19 @@
 # Tool to remotely create SPDK targets on multiple nodes
 # Usage: python3 -m mooncake.spdk_tgt_create --spdk_target_info="ip:192.168.65.56 path:/home/spdk pci:0000:01:00.0,0000:02:00.0" --spdk_target_info="ip:192.168.65.57 path:/home/spdk"
 
+from __future__ import annotations
+
 import argparse
 import logging
-import paramiko
 import re
 import shlex
 import time
-from typing import List, Dict, Any, Optional
+from typing import TYPE_CHECKING, List, Dict, Any, Optional
+
+from mooncake._administration import require_paramiko
+
+if TYPE_CHECKING:
+    import paramiko
 
 
 class SPDKTgtCreator:
@@ -17,32 +23,39 @@ class SPDKTgtCreator:
     """
 
     DEFAULT_TRANSPORT_OPTIONS = {
-        'trtype': 'RDMA',
-        'max_queue_depth': 128,
-        'max_io_qpairs_per_ctrlr': 127,
-        'max_io_size': 4096,
-        'in_capsule_data_size': 131072,
-        'io_unit_size': 131072,
-        'max_aq_depth': 128,
-        'num_shared_buffers': 4096,
-        'buf_cache_size': 32,
+        "trtype": "RDMA",
+        "max_queue_depth": 128,
+        "max_io_qpairs_per_ctrlr": 127,
+        "max_io_size": 4096,
+        "in_capsule_data_size": 131072,
+        "io_unit_size": 131072,
+        "max_aq_depth": 128,
+        "num_shared_buffers": 4096,
+        "buf_cache_size": 32,
     }
 
     TRANSPORT_RPC_FLAGS = {
-        'trtype': '-t',
-        'max_queue_depth': '-q',
-        'max_io_qpairs_per_ctrlr': '-m',
-        'max_io_size': '-c',
-        'in_capsule_data_size': '-i',
-        'io_unit_size': '-u',
-        'max_aq_depth': '-a',
-        'num_shared_buffers': '-n',
-        'buf_cache_size': '-b',
+        "trtype": "-t",
+        "max_queue_depth": "-q",
+        "max_io_qpairs_per_ctrlr": "-m",
+        "max_io_size": "-c",
+        "in_capsule_data_size": "-i",
+        "io_unit_size": "-u",
+        "max_aq_depth": "-a",
+        "num_shared_buffers": "-n",
+        "buf_cache_size": "-b",
     }
 
-    def __init__(self, spdk_targets: List[str], transport_options: Dict[str, Any] = None, core_mask: str = '0xff'):
+    def __init__(
+        self,
+        spdk_targets: List[str],
+        transport_options: Dict[str, Any] = None,
+        core_mask: str = "0xff",
+        port: int = 22,
+    ):
         self.spdk_targets = spdk_targets
         self.core_mask = core_mask
+        self.port = port
         self.transport_options = dict(self.DEFAULT_TRANSPORT_OPTIONS)
         if transport_options:
             self.transport_options.update(transport_options)
@@ -52,7 +65,7 @@ def __init__(self, spdk_targets: List[str], transport_options: Dict[str, Any] =
     def _setup_logging(self):
         logging.basicConfig(
             level=logging.INFO,
-            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         )
         self.logger = logging.getLogger(self.__class__.__name__)
 
@@ -64,11 +77,7 @@ def _parse_spdk_targets(self) -> List[Dict[str, Any]]:
         target_configs = []
 
         for target_info in self.spdk_targets:
-            target = {
-                'ip': None,
-                'path': None,
-                'pci_devices': []
-            }
+            target = {"ip": None, "path": None, "pci_devices": []}
 
             # Split the target info by spaces
             parts = target_info.split()
@@ -77,69 +86,95 @@ def _parse_spdk_targets(self) -> List[Dict[str, Any]]:
             state = None  # Can be 'ip', 'path', or 'pci'
 
             for part in parts:
-                if ':' in part:
+                if ":" in part:
                     # This is a key-value pair
-                    key, value = part.split(':', 1)
+                    key, value = part.split(":", 1)
                     key = key.strip()
                     value = value.strip()
 
-                    if key == 'ip':
-                        target['ip'] = value
-                        state = 'ip'
-                    elif key == 'path':
-                        target['path'] = value
-                        state = 'path'
-                    elif key == 'pci':
+                    if key == "ip":
+                        target["ip"] = value
+                        state = "ip"
+                    elif key == "path":
+                        target["path"] = value
+                        state = "path"
+                    elif key == "pci":
                         # Parse PCI devices separated by commas
                         if value:
                             # Split by commas and strip whitespace
-                            pci_list = [dev.strip() for dev in value.split(',') if dev.strip()]
-                            target['pci_devices'].extend(pci_list)
-                        state = 'pci'
-                    elif state == 'pci':
-                        pci_list = [dev.strip() for dev in part.split(',') if dev.strip()]
-                        target['pci_devices'].extend(pci_list)
+                            pci_list = [
+                                dev.strip() for dev in value.split(",") if dev.strip()
+                            ]
+                            target["pci_devices"].extend(pci_list)
+                        state = "pci"
+                    elif state == "pci":
+                        pci_list = [
+                            dev.strip() for dev in part.split(",") if dev.strip()
+                        ]
+                        target["pci_devices"].extend(pci_list)
                 else:
                     # This is a continuation of the current state
-                    if state == 'path':
+                    if state == "path":
                         # Path might contain spaces (unlikely but possible)
-                        target['path'] += ' ' + part
-                    elif state == 'pci':
-                        pci_list = [dev.strip() for dev in part.split(',') if dev.strip()]
-                        target['pci_devices'].extend(pci_list)
+                        target["path"] += " " + part
+                    elif state == "pci":
+                        pci_list = [
+                            dev.strip() for dev in part.split(",") if dev.strip()
+                        ]
+                        target["pci_devices"].extend(pci_list)
 
             # Validate required fields
-            if not target['ip']:
+            if not target["ip"]:
                 raise ValueError("Each spdk_target_info must contain 'ip' field")
-            if not target['path']:
+            if not target["path"]:
                 raise ValueError("Each spdk_target_info must contain 'path' field")
 
             target_configs.append(target)
-            pci_info = target['pci_devices'] if target['pci_devices'] else 'auto-discover'
-            self.logger.info(f"Parsed target: IP={target['ip']}, Path={target['path']}, PCI devices={pci_info}")
+            pci_info = (
+                target["pci_devices"] if target["pci_devices"] else "auto-discover"
+            )
+            self.logger.info(
+                f"Parsed target: IP={target['ip']}, Path={target['path']}, PCI devices={pci_info}"
+            )
 
         return target_configs
 
-    def _ssh_connect(self, ip: str, username: str = 'root', password: str = None, key_file: str = None) -> paramiko.SSHClient:
+    def _ssh_connect(
+        self,
+        ip: str,
+        username: str = "root",
+        password: str = None,
+        key_file: str = None,
+        port: int = 22,
+    ) -> paramiko.SSHClient:
         """
         Establish an SSH connection to the target host.
         """
+        paramiko = require_paramiko()
         ssh = paramiko.SSHClient()
         ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
 
         try:
             if key_file:
                 self.logger.info(f"Connecting to {ip} using key file {key_file}")
-                ssh.connect(ip, username=username, key_filename=key_file)
+                ssh.connect(ip, port=port, username=username, key_filename=key_file)
             else:
                 self.logger.info(f"Connecting to {ip} using password authentication")
-                ssh.connect(ip, username=username, password=password)
+                ssh.connect(ip, port=port, username=username, password=password)
             return ssh
         except Exception as e:
             self.logger.error(f"Failed to connect to {ip}: {e}")
             raise
 
-    def _execute_command(self, ssh: paramiko.SSHClient, command: str, working_dir: str = None, sudo: bool = False, log_errors: bool = True, timeout: Optional[int] = 30) -> tuple:
+    def _execute_command(
+        self,
+        ssh: paramiko.SSHClient,
+        command: str,
+        working_dir: str = None,
+        sudo: bool = False,
+        log_errors: bool = True,
+        timeout: Optional[int] = 30,
+    ) -> tuple:
         """
         Execute a command on the remote host via SSH.
         """
@@ -153,8 +188,8 @@ def _execute_command(self, ssh: paramiko.SSHClient, command: str, working_dir: s
 
         stdin, stdout, stderr = ssh.exec_command(command, timeout=timeout)
         exit_status = stdout.channel.recv_exit_status()
-        output = stdout.read().decode('utf-8')
-        error = stderr.read().decode('utf-8')
+        output = stdout.read().decode("utf-8")
+        error = stderr.read().decode("utf-8")
 
         if output:
             self.logger.debug(f"Command output: {output}")
@@ -162,7 +197,9 @@ def _execute_command(self, ssh: paramiko.SSHClient, command: str, working_dir: s
             self.logger.debug(f"Command error: {error}")
         if exit_status != 0:
             if log_errors:
-                self.logger.error(f"Command failed with exit code {exit_status}: {command}")
+                self.logger.error(
+                    f"Command failed with exit code {exit_status}: {command}"
+                )
                 if output:
                     self.logger.error(f"Command output: {output}")
                 self.logger.error(f"Error output: {error}")
@@ -174,7 +211,9 @@ def _discover_nvme_pci_devices(self, ssh: paramiko.SSHClient) -> List[str]:
         """
         Discover SPDK-ready or unmounted NVMe controller PCI addresses on the target host.
         """
-        self.logger.info("No PCI devices specified, discovering SPDK-ready or unmounted NVMe PCI devices")
+        self.logger.info(
+            "No PCI devices specified, discovering SPDK-ready or unmounted NVMe PCI devices"
+        )
         output, _ = self._execute_command(
             ssh,
             r"""for dev in /sys/bus/pci/devices/*; do
@@ -213,38 +252,44 @@ def _discover_nvme_pci_devices(self, ssh: paramiko.SSHClient) -> List[str]:
   else
     echo "SKIP $pci mounted"
   fi
-done"""
+done""",
         )
 
         pci_devices = []
         pci_pattern = re.compile(
-            r'^(?:[0-9a-fA-F]{4}:)?[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-7]$'
+            r"^(?:[0-9a-fA-F]{4}:)?[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-7]$"
         )
         for line in output.splitlines():
             fields = line.split()
             if len(fields) < 2:
                 continue
             action, pci = fields[0], fields[1]
-            if action == 'USE' and pci_pattern.match(pci):
+            if action == "USE" and pci_pattern.match(pci):
                 pci_devices.append(pci)
-            elif action == 'SKIP' and pci_pattern.match(pci):
-                reason = ' '.join(fields[2:]) or 'not eligible'
+            elif action == "SKIP" and pci_pattern.match(pci):
+                reason = " ".join(fields[2:]) or "not eligible"
                 self.logger.warning(f"Skipping NVMe PCI device {pci}: {reason}")
 
         if not pci_devices:
-            raise RuntimeError("No SPDK-ready or unmounted NVMe PCI devices found on the target host")
+            raise RuntimeError(
+                "No SPDK-ready or unmounted NVMe PCI devices found on the target host"
+            )
 
-        self.logger.info(f"Selected NVMe PCI devices for SPDK setup: {', '.join(pci_devices)}")
+        self.logger.info(
+            f"Selected NVMe PCI devices for SPDK setup: {', '.join(pci_devices)}"
+        )
         return pci_devices
 
-    def _filter_spdk_ready_pci_devices(self, ssh: paramiko.SSHClient, pci_devices: List[str], strict: bool) -> List[str]:
+    def _filter_spdk_ready_pci_devices(
+        self, ssh: paramiko.SSHClient, pci_devices: List[str], strict: bool
+    ) -> List[str]:
         """
         Keep PCI devices that are bound to an SPDK-compatible userspace driver.
         """
         if not pci_devices:
             return []
 
-        pci_args = ' '.join(shlex.quote(pci) for pci in pci_devices)
+        pci_args = " ".join(shlex.quote(pci) for pci in pci_devices)
         output, _ = self._execute_command(
             ssh,
             f"""for pci in {pci_args}; do
@@ -254,7 +299,7 @@ def _filter_spdk_ready_pci_devices(self, ssh: paramiko.SSHClient, pci_devices: L
     "") echo "NOT_READY $pci no_driver" ;;
     *) echo "NOT_READY $pci $driver" ;;
   esac
-done"""
+done""",
         )
 
         ready_devices = []
@@ -264,19 +309,23 @@ def _filter_spdk_ready_pci_devices(self, ssh: paramiko.SSHClient, pci_devices: L
             if len(fields) < 3:
                 continue
             state, pci, driver = fields[0], fields[1], fields[2]
-            if state == 'READY':
+            if state == "READY":
                 ready_devices.append(pci)
-            elif state == 'NOT_READY':
+            elif state == "NOT_READY":
                 not_ready_devices.append((pci, driver))
 
         if not_ready_devices:
-            details = ', '.join(f"{pci} ({driver})" for pci, driver in not_ready_devices)
+            details = ", ".join(
+                f"{pci} ({driver})" for pci, driver in not_ready_devices
+            )
             if strict:
                 raise RuntimeError(
                     "Some PCI devices are not available to SPDK after setup.sh: "
                     f"{details}. Check whether they are mounted or still bound to the kernel driver."
                 )
-            self.logger.warning(f"Skipping PCI devices not available to SPDK after setup.sh: {details}")
+            self.logger.warning(
+                f"Skipping PCI devices not available to SPDK after setup.sh: {details}"
+            )
 
         if not ready_devices:
             raise RuntimeError("No PCI devices are available to SPDK after setup.sh")
@@ -304,18 +353,22 @@ def _start_spdk_tgt(self, ssh: paramiko.SSHClient, spdk_path: str) -> None:
         self._execute_command(
             ssh,
             f"nohup {tgt_binary} -m {shlex.quote(self.core_mask)} > {log_file} 2>&1 &",
-            timeout=None
+            timeout=None,
         )
         time.sleep(3)  # Give it time to start
 
-    def _setup_spdk(self, ssh: paramiko.SSHClient, spdk_path: str, pci_devices: List[str]) -> None:
+    def _setup_spdk(
+        self, ssh: paramiko.SSHClient, spdk_path: str, pci_devices: List[str]
+    ) -> None:
         """
         Setup SPDK with the specified PCI devices.
         """
         self.logger.info(f"Setting up SPDK with PCI devices: {', '.join(pci_devices)}")
-        pci_allowed = ' '.join(pci_devices)
+        pci_allowed = " ".join(pci_devices)
         setup_script = f"{spdk_path}/scripts/setup.sh"
-        self._execute_command(ssh, f"PCI_ALLOWED='{pci_allowed}' {setup_script}", sudo=True)
+        self._execute_command(
+            ssh, f"PCI_ALLOWED='{pci_allowed}' {setup_script}", sudo=True
+        )
 
     def _format_transport_options(self) -> str:
         """
@@ -325,7 +378,7 @@ def _format_transport_options(self) -> str:
         for option, flag in self.TRANSPORT_RPC_FLAGS.items():
             value = self.transport_options[option]
             formatted_options.extend([flag, shlex.quote(str(value))])
-        return ' '.join(formatted_options)
+        return " ".join(formatted_options)
 
     def _create_transport(self, ssh: paramiko.SSHClient, spdk_path: str) -> None:
         """
@@ -334,9 +387,13 @@ def _create_transport(self, ssh: paramiko.SSHClient, spdk_path: str) -> None:
         self.logger.info(f"Creating {self.transport_options['trtype']} transport")
         rpc_script = f"{spdk_path}/scripts/rpc.py"
         transport_options = self._format_transport_options()
-        self._execute_command(ssh, f"{rpc_script} nvmf_create_transport {transport_options}")
+        self._execute_command(
+            ssh, f"{rpc_script} nvmf_create_transport {transport_options}"
+        )
 
-    def _create_bdevs(self, ssh: paramiko.SSHClient, spdk_path: str, pci_devices: List[str]) -> List[str]:
+    def _create_bdevs(
+        self, ssh: paramiko.SSHClient, spdk_path: str, pci_devices: List[str]
+    ) -> List[str]:
         """
         Create block devices for the specified PCI devices.
         """
@@ -345,7 +402,10 @@ def _create_bdevs(self, ssh: paramiko.SSHClient, spdk_path: str, pci_devices: Li
         for i, pci in enumerate(pci_devices):
             bdev_name = f"Nvme{i}"
             self.logger.info(f"Creating bdev {bdev_name} for PCI {pci}")
-            self._execute_command(ssh, f"{rpc_script} bdev_nvme_attach_controller -b {bdev_name} -t PCIe -a {pci}")
+            self._execute_command(
+                ssh,
+                f"{rpc_script} bdev_nvme_attach_controller -b {bdev_name} -t PCIe -a {pci}",
+            )
             bdevs.append(f"{bdev_name}n1")
             self.logger.info(f"Attached PCI {pci} as bdev {bdev_name}n1")
         return bdevs
@@ -357,56 +417,74 @@ def _create_subsystem(self, ssh: paramiko.SSHClient, spdk_path: str) -> str:
         subsystem_nqn = "nqn.2016-06.io.spdk:cnode1"
         self.logger.info(f"Creating subsystem {subsystem_nqn}")
         rpc_script = f"{spdk_path}/scripts/rpc.py"
-        self._execute_command(ssh, f"{rpc_script} nvmf_create_subsystem {subsystem_nqn} -a -s SPDK00000000000001 -m 12")
+        self._execute_command(
+            ssh,
+            f"{rpc_script} nvmf_create_subsystem {subsystem_nqn} -a -s SPDK00000000000001 -m 12",
+        )
         return subsystem_nqn
 
-    def _add_namespaces(self, ssh: paramiko.SSHClient, spdk_path: str, subsystem_nqn: str, bdevs: List[str]) -> None:
+    def _add_namespaces(
+        self,
+        ssh: paramiko.SSHClient,
+        spdk_path: str,
+        subsystem_nqn: str,
+        bdevs: List[str],
+    ) -> None:
         """
         Add namespaces to the subsystem.
         """
         rpc_script = f"{spdk_path}/scripts/rpc.py"
         for bdev in bdevs:
             self.logger.info(f"Adding namespace {bdev} to subsystem {subsystem_nqn}")
-            self._execute_command(ssh, f"{rpc_script} nvmf_subsystem_add_ns {subsystem_nqn} {bdev}")
+            self._execute_command(
+                ssh, f"{rpc_script} nvmf_subsystem_add_ns {subsystem_nqn} {bdev}"
+            )
 
-    def _add_listener(self, ssh: paramiko.SSHClient, spdk_path: str, subsystem_nqn: str, ip: str) -> None:
+    def _add_listener(
+        self, ssh: paramiko.SSHClient, spdk_path: str, subsystem_nqn: str, ip: str
+    ) -> None:
         """
         Add a listener to the subsystem.
         """
-        trtype = self.transport_options['trtype']
+        trtype = self.transport_options["trtype"]
         self.logger.info(f"Adding {trtype} listener on {ip}:4420")
         rpc_script = f"{spdk_path}/scripts/rpc.py"
-        self._execute_command(ssh, f"{rpc_script} nvmf_subsystem_add_listener {subsystem_nqn} -t {shlex.quote(str(trtype))} -a {ip} -s 4420")
+        self._execute_command(
+            ssh,
+            f"{rpc_script} nvmf_subsystem_add_listener {subsystem_nqn} -t {shlex.quote(str(trtype))} -a {ip} -s 4420",
+        )
 
     def deploy_target(self, target_config: Dict[str, Any]) -> bool:
         """
         Deploy SPDK target on a single node.
         """
-        ip = target_config['ip']
-        spdk_path = target_config['path']
-        pci_devices = target_config['pci_devices']
+        ip = target_config["ip"]
+        spdk_path = target_config["path"]
+        pci_devices = target_config["pci_devices"]
 
         self.logger.info(f"Deploying SPDK target on {ip}")
 
         try:
             # Establish SSH connection
-            ssh = self._ssh_connect(ip)
+            ssh = self._ssh_connect(ip, port=self.port)
 
             try:
                 auto_discovered = not pci_devices
                 if not pci_devices:
                     pci_devices = self._discover_nvme_pci_devices(ssh)
                 else:
-                    self.logger.info(f"Using explicitly specified PCI devices for {ip}: {', '.join(pci_devices)}")
+                    self.logger.info(
+                        f"Using explicitly specified PCI devices for {ip}: {', '.join(pci_devices)}"
+                    )
 
                 # Setup SPDK
                 self._setup_spdk(ssh, spdk_path, pci_devices)
                 pci_devices = self._filter_spdk_ready_pci_devices(
-                    ssh,
-                    pci_devices,
-                    strict=not auto_discovered
+                    ssh, pci_devices, strict=not auto_discovered
+                )
+                self.logger.info(
+                    f"Target {ip} will expose PCI devices: {', '.join(pci_devices)}"
                 )
-                self.logger.info(f"Target {ip} will expose PCI devices: {', '.join(pci_devices)}")
 
                 # Start tgt service
                 self._start_spdk_tgt(ssh, spdk_path)
@@ -455,60 +533,112 @@ def deploy_all_targets(self) -> bool:
 
 
 def parse_arguments():
-    parser = argparse.ArgumentParser(description='SPDK Target Creator Tool')
+    parser = argparse.ArgumentParser(description="SPDK Target Creator Tool")
+    parser.add_argument(
+        "--spdk_target_info",
+        action="append",
+        help=(
+            'SPDK target information (e.g., "ip:192.168.65.56 '
+            'path:/home/spdk pci:0000:01:00.0,0000:02:00.0"). If pci is '
+            "omitted, SPDK-ready or unmounted NVMe devices on the target are used."
+        ),
+        required=True,
+    )
+    parser.add_argument(
+        "--core-mask",
+        type=str,
+        default="0xff",
+        help="CPU core mask used to start nvmf_tgt with -m (default: 0xff)",
+    )
     parser.add_argument(
-        '--spdk_target_info',
-        action='append',
-        help=('SPDK target information (e.g., "ip:192.168.65.56 '
-              'path:/home/spdk pci:0000:01:00.0,0000:02:00.0"). If pci is '
-              'omitted, SPDK-ready or unmounted NVMe devices on the target are used.'),
-        required=True
+        "--transport-type",
+        type=str,
+        default="RDMA",
+        help="NVMe-oF transport type for nvmf_create_transport (default: RDMA)",
     )
-    parser.add_argument('--core-mask', type=str, default='0xff',
-                        help='CPU core mask used to start nvmf_tgt with -m (default: 0xff)')
-    parser.add_argument('--transport-type', type=str, default='RDMA',
-                        help='NVMe-oF transport type for nvmf_create_transport (default: RDMA)')
-    parser.add_argument('--max-queue-depth', type=int, default=128,
-                        help='Max number of outstanding I/O per queue (default: 128)')
-    parser.add_argument('--max-io-qpairs-per-ctrlr', type=int, default=127,
-                        help='Max number of I/O qpairs per controller (default: 127)')
-    parser.add_argument('--max-io-size', type=int, default=4096,
-                        help='Max I/O size in bytes (default: 4096)')
-    parser.add_argument('--in-capsule-data-size', type=int, default=131072,
-                        help='Max in-capsule data size in bytes (default: 131072)')
-    parser.add_argument('--io-unit-size', type=int, default=131072,
-                        help='I/O unit size in bytes (default: 131072)')
-    parser.add_argument('--max-aq-depth', type=int, default=128,
-                        help='Max number of admin commands per admin queue (default: 128)')
-    parser.add_argument('--num-shared-buffers', type=int, default=4096,
-                        help='Number of pooled data buffers available to the transport (default: 4096)')
-    parser.add_argument('--buf-cache-size', type=int, default=32,
-                        help='Number of shared buffers reserved for each poll group (default: 32)')
-    parser.add_argument('--username', type=str, default='root',
-                        help='SSH username for target nodes (default: root)')
-    parser.add_argument('--password', type=str,
-                        help='SSH password for target nodes')
-    parser.add_argument('--key-file', type=str,
-                        help='SSH private key file path')
+    parser.add_argument(
+        "--max-queue-depth",
+        type=int,
+        default=128,
+        help="Max number of outstanding I/O per queue (default: 128)",
+    )
+    parser.add_argument(
+        "--max-io-qpairs-per-ctrlr",
+        type=int,
+        default=127,
+        help="Max number of I/O qpairs per controller (default: 127)",
+    )
+    parser.add_argument(
+        "--max-io-size",
+        type=int,
+        default=4096,
+        help="Max I/O size in bytes (default: 4096)",
+    )
+    parser.add_argument(
+        "--in-capsule-data-size",
+        type=int,
+        default=131072,
+        help="Max in-capsule data size in bytes (default: 131072)",
+    )
+    parser.add_argument(
+        "--io-unit-size",
+        type=int,
+        default=131072,
+        help="I/O unit size in bytes (default: 131072)",
+    )
+    parser.add_argument(
+        "--max-aq-depth",
+        type=int,
+        default=128,
+        help="Max number of admin commands per admin queue (default: 128)",
+    )
+    parser.add_argument(
+        "--num-shared-buffers",
+        type=int,
+        default=4096,
+        help="Number of pooled data buffers available to the transport (default: 4096)",
+    )
+    parser.add_argument(
+        "--buf-cache-size",
+        type=int,
+        default=32,
+        help="Number of shared buffers reserved for each poll group (default: 32)",
+    )
+    parser.add_argument(
+        "--username",
+        type=str,
+        default="root",
+        help="SSH username for target nodes (default: root)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=22, help="SSH port for target nodes (default: 22)"
+    )
+    parser.add_argument("--password", type=str, help="SSH password for target nodes")
+    parser.add_argument("--key-file", type=str, help="SSH private key file path")
     return parser.parse_args()
 
 
 def main():
     args = parse_arguments()
     transport_options = {
-        'trtype': args.transport_type,
-        'max_queue_depth': args.max_queue_depth,
-        'max_io_qpairs_per_ctrlr': args.max_io_qpairs_per_ctrlr,
-        'max_io_size': args.max_io_size,
-        'in_capsule_data_size': args.in_capsule_data_size,
-        'io_unit_size': args.io_unit_size,
-        'max_aq_depth': args.max_aq_depth,
-        'num_shared_buffers': args.num_shared_buffers,
-        'buf_cache_size': args.buf_cache_size,
+        "trtype": args.transport_type,
+        "max_queue_depth": args.max_queue_depth,
+        "max_io_qpairs_per_ctrlr": args.max_io_qpairs_per_ctrlr,
+        "max_io_size": args.max_io_size,
+        "in_capsule_data_size": args.in_capsule_data_size,
+        "io_unit_size": args.io_unit_size,
+        "max_aq_depth": args.max_aq_depth,
+        "num_shared_buffers": args.num_shared_buffers,
+        "buf_cache_size": args.buf_cache_size,
     }
 
     try:
-        creator = SPDKTgtCreator(args.spdk_target_info, transport_options, args.core_mask)
+        creator = SPDKTgtCreator(
+            args.spdk_target_info,
+            transport_options,
+            args.core_mask,
+            args.port,
+        )
         success = creator.deploy_all_targets()
         exit(0 if success else 1)
     except Exception as e:
@@ -516,5 +646,5 @@ def main():
         exit(1)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()
diff --git a/python/mooncake/transfer_engine_topology_dump.py b/python/mooncake/transfer_engine_topology_dump.py
new file mode 100644
index 0000000000..7482b3670d
--- /dev/null
+++ b/python/mooncake/transfer_engine_topology_dump.py
@@ -0,0 +1,203 @@
+import argparse
+import json
+import os
+import sys
+import tempfile
+
+
+def parse_args():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Dump device topology for classic Transfer Engine or TENT. "
+            "By default clears custom topology overrides so the output "
+            "reflects auto-discovery. Use --use-custom-topo or "
+            "--custom-topo-json to load a custom NIC priority matrix instead. "
+            "TENT backend prints native {nics,mems} JSON with rank0/1/2."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--device-name",
+        type=str,
+        default="",
+        help=(
+            "Filter topology by IB device name(s), comma-separated. "
+            "Under TENT this maps to MC_TE_FILTERS."
+        ),
+    )
+    parser.add_argument(
+        "--backend",
+        choices=("auto", "te", "tent"),
+        default="auto",
+        help=(
+            "Topology backend: te=classic Transfer Engine, tent=Mooncake TENT, "
+            "auto=follow MC_USE_TENT/MC_USE_TEV1"
+        ),
+    )
+    parser.add_argument(
+        "--use-custom-topo",
+        action="store_true",
+        help=(
+            "Keep existing MC_CUSTOM_TOPO_JSON / TENT topology overrides "
+            "(compare discover vs custom by running with and without this flag)"
+        ),
+    )
+    parser.add_argument(
+        "--custom-topo-json",
+        type=str,
+        default=None,
+        help=(
+            "Path to custom topology JSON; sets MC_CUSTOM_TOPO_JSON "
+            "(also honored by TENT as topology/custom_json_path)"
+        ),
+    )
+    return parser.parse_args()
+
+
+def resolve_backend(backend: str) -> str:
+    if backend == "auto":
+        if os.environ.get("MC_USE_TENT") or os.environ.get("MC_USE_TEV1"):
+            return "tent"
+        return "te"
+    return backend
+
+
+def apply_backend(backend: str) -> None:
+    if backend == "tent":
+        os.environ.setdefault("MC_USE_TENT", "1")
+    else:
+        os.environ.pop("MC_USE_TENT", None)
+        os.environ.pop("MC_USE_TEV1", None)
+
+
+def _load_tent_conf_object(conf: str):
+    if not conf:
+        return None, False
+    if os.path.isfile(conf):
+        with open(conf, "r", encoding="utf-8") as f:
+            return json.load(f), True
+    try:
+        return json.loads(conf), False
+    except json.JSONDecodeError:
+        return None, False
+
+
+def sanitize_tent_conf_for_discover():
+    """
+    Remove topology/priority_matrix and topology/custom_json_path from
+    MC_TENT_CONF so discover mode is not overridden by an existing conf.
+    Returns a temp file path that the caller should delete, or None.
+    """
+    conf = os.environ.get("MC_TENT_CONF", "")
+    data, _ = _load_tent_conf_object(conf)
+    if not isinstance(data, dict):
+        return None
+    topo = data.get("topology")
+    if not isinstance(topo, dict):
+        return None
+    if "priority_matrix" not in topo and "custom_json_path" not in topo:
+        return None
+
+    sanitized = dict(data)
+    new_topo = dict(topo)
+    new_topo.pop("priority_matrix", None)
+    new_topo.pop("custom_json_path", None)
+    sanitized["topology"] = new_topo
+
+    fd, path = tempfile.mkstemp(prefix="tent-topo-dump-", suffix=".json")
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(sanitized, f)
+    os.environ["MC_TENT_CONF"] = path
+    return path
+
+
+def dump_te_topology(device_name: str) -> str:
+    from mooncake.engine import TransferEngine
+
+    engine = TransferEngine()
+    return engine.get_local_topology(device_name=device_name or None)
+
+
+def dump_tent_topology(device_name: str) -> str:
+    """
+    Prefer the native tent Python module (same engine path as tebench).
+    Fall back to mooncake.engine under MC_USE_TENT, which returns native
+    {"nics","mems"} via get_local_topology / getLocalTopologyString.
+    """
+    if device_name:
+        os.environ["MC_TE_FILTERS"] = device_name
+
+    try:
+        import tent
+
+        engine = tent.TransferEngine()
+        if not engine.available():
+            raise RuntimeError("tent.TransferEngine is not available")
+        return engine.get_local_topology()
+    except ImportError:
+        return dump_te_topology(device_name)
+
+
+def main():
+    args = parse_args()
+    os.environ["MC_LOG_LEVEL"] = "ERROR"
+
+    backend = resolve_backend(args.backend)
+    apply_backend(backend)
+
+    temp_conf = None
+    if args.custom_topo_json is not None:
+        os.environ["MC_CUSTOM_TOPO_JSON"] = args.custom_topo_json
+        mode = f"custom ({args.custom_topo_json})"
+    elif args.use_custom_topo:
+        custom_path = os.environ.get("MC_CUSTOM_TOPO_JSON", "")
+        has_inline = False
+        if backend == "tent":
+            data, _ = _load_tent_conf_object(os.environ.get("MC_TENT_CONF", ""))
+            topo = data.get("topology") if isinstance(data, dict) else None
+            has_inline = isinstance(topo, dict) and (
+                "priority_matrix" in topo or "custom_json_path" in topo
+            )
+        if not custom_path and not has_inline:
+            print(
+                "error: --use-custom-topo requires MC_CUSTOM_TOPO_JSON "
+                "or TENT topology/priority_matrix|custom_json_path in "
+                "MC_TENT_CONF",
+                file=sys.stderr,
+            )
+            return 1
+        mode = (
+            f"custom ({custom_path})"
+            if custom_path
+            else "custom (MC_TENT_CONF topology)"
+        )
+    else:
+        # Force discover path. Empty string still makes getenv non-null in C++,
+        # which falls back to auto-detect when the path cannot be loaded.
+        os.environ["MC_CUSTOM_TOPO_JSON"] = ""
+        if backend == "tent":
+            temp_conf = sanitize_tent_conf_for_discover()
+        mode = "discover"
+
+    try:
+        if backend == "tent":
+            topo = dump_tent_topology(args.device_name)
+        else:
+            topo = dump_te_topology(args.device_name)
+        print(f"Local topology [{backend}/{mode}]: ", end="")
+        print(topo)
+        return 0
+    except Exception as exc:
+        print(f"error: failed to dump topology: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        if temp_conf and os.path.exists(temp_conf):
+            try:
+                os.unlink(temp_conf)
+            except OSError:
+                pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/mooncake-wheel/tests/ep_test_utils.py b/python/tests/ep/ep_test_utils.py
similarity index 78%
rename from mooncake-wheel/tests/ep_test_utils.py
rename to python/tests/ep/ep_test_utils.py
index fa6b97acd3..fb1e780341 100644
--- a/mooncake-wheel/tests/ep_test_utils.py
+++ b/python/tests/ep/ep_test_utils.py
@@ -12,23 +12,24 @@
 
 def init_dist(local_rank: int, num_local_ranks: int):
     # NOTES: you may rewrite this function with your own cluster settings
-    ip = os.getenv('MASTER_ADDR', '127.0.0.1')
-    port = int(os.getenv('MASTER_PORT', '8361'))
-    num_nodes = int(os.getenv('WORLD_SIZE', 1))
-    node_rank = int(os.getenv('RANK', 0))
+    ip = os.getenv("MASTER_ADDR", "127.0.0.1")
+    port = int(os.getenv("MASTER_PORT", "8361"))
+    num_nodes = int(os.getenv("WORLD_SIZE", 1))
+    node_rank = int(os.getenv("RANK", 0))
     assert (num_local_ranks < 8 and num_nodes == 1) or num_local_ranks == 8
 
     torch.cuda.set_device(local_rank)
     dist.init_process_group(
-        backend='mooncake',
-        init_method=f'tcp://{ip}:{port}',
+        backend="mooncake",
+        init_method=f"tcp://{ip}:{port}",
         world_size=num_nodes * num_local_ranks,
-        rank=node_rank * num_local_ranks + local_rank
+        rank=node_rank * num_local_ranks + local_rank,
     )
     torch.set_default_dtype(torch.bfloat16)
-    torch.set_default_device('cuda')
+    torch.set_default_device("cuda")
 
-    return dist.get_rank(), dist.get_world_size(), dist.new_group(list(range(num_local_ranks * num_nodes))), dist.new_group(list(range(num_local_ranks * num_nodes)), backend="mooncake-cpu")
+    group = dist.new_group(list(range(num_local_ranks * num_nodes)))
+    return dist.get_rank(), dist.get_world_size(), group
 
 
 def calc_diff(x: torch.Tensor, y: torch.Tensor):
@@ -43,7 +44,9 @@ def per_token_cast_to_fp8(x: torch.Tensor):
     m, n = x.shape
     x_view = x.view(m, -1, 128)
     x_amax = x_view.abs().float().amax(dim=2).view(m, -1).clamp(1e-4)
-    return (x_view * (448.0 / x_amax.unsqueeze(2))).to(torch.float8_e4m3fn).view(m, n), (x_amax / 448.0).view(m, -1)
+    return (x_view * (448.0 / x_amax.unsqueeze(2))).to(torch.float8_e4m3fn).view(
+        m, n
+    ), (x_amax / 448.0).view(m, -1)
 
 
 def per_token_cast_back(x_fp8: torch.Tensor, x_scales: torch.Tensor):
@@ -67,7 +70,9 @@ def inplace_unique(x: torch.Tensor, num_slots: int):
     x[:, :valid_len] = sorted_bin_idx[:, :valid_len]
 
 
-def create_grouped_scores(scores: torch.Tensor, group_idx: torch.Tensor, num_groups: int):
+def create_grouped_scores(
+    scores: torch.Tensor, group_idx: torch.Tensor, num_groups: int
+):
     num_tokens, num_experts = scores.shape
     scores = scores.view(num_tokens, num_groups, -1)
     mask = torch.zeros((num_tokens, num_groups), dtype=torch.bool, device=scores.device)
@@ -78,7 +83,7 @@ def create_grouped_scores(scores: torch.Tensor, group_idx: torch.Tensor, num_gro
 def bench(fn, num_warmups: int = 20, num_tests: int = 30, post_fn=None):
     # Flush L2 cache with 256 MB data
     torch.cuda.synchronize()
-    cache = torch.empty(int(256e6 // 4), dtype=torch.int, device='cuda')
+    cache = torch.empty(int(256e6 // 4), dtype=torch.int, device="cuda")
 
     # Warmup
     for _ in range(num_warmups):
@@ -99,7 +104,9 @@ def bench(fn, num_warmups: int = 20, num_tests: int = 30, post_fn=None):
             post_fn()
     torch.cuda.synchronize()
 
-    times = np.array([s.elapsed_time(e) / 1e3 for s, e in zip(start_events, end_events)])[1:]
+    times = np.array(
+        [s.elapsed_time(e) / 1e3 for s, e in zip(start_events, end_events)]
+    )[1:]
     return np.average(times), np.min(times), np.max(times)
 
 
@@ -113,8 +120,8 @@ def __exit__(self, *_):
 
 class suppress_stdout_stderr:
     def __enter__(self):
-        self.outnull_file = open(os.devnull, 'w')
-        self.errnull_file = open(os.devnull, 'w')
+        self.outnull_file = open(os.devnull, "w")
+        self.errnull_file = open(os.devnull, "w")
 
         self.old_stdout_fileno_undup = sys.stdout.fileno()
         self.old_stderr_fileno_undup = sys.stderr.fileno()
@@ -146,20 +153,28 @@ def __exit__(self, *_):
         self.errnull_file.close()
 
 
-def bench_kineto(fn, kernel_names, num_tests: int = 30, suppress_kineto_output: bool = False,
-                 trace_path: Optional[str] = None, barrier_comm_profiling: bool = False):
+def bench_kineto(
+    fn,
+    kernel_names,
+    num_tests: int = 30,
+    suppress_kineto_output: bool = False,
+    trace_path: Optional[str] = None,
+    barrier_comm_profiling: bool = False,
+):
     # Profile
     suppress = suppress_stdout_stderr if suppress_kineto_output else empty_suppress
     with suppress():
         schedule = torch.profiler.schedule(wait=0, warmup=1, active=1, repeat=1)
-        with torch.profiler.profile(activities=[torch.profiler.ProfilerActivity.CUDA], schedule=schedule) as prof:
+        with torch.profiler.profile(
+            activities=[torch.profiler.ProfilerActivity.CUDA], schedule=schedule
+        ) as prof:
             for i in range(2):
                 # NOTES: use a large kernel and a barrier to eliminate the unbalanced CPU launch overhead
                 if barrier_comm_profiling:
-                    lhs = torch.randn((8192, 8192), dtype=torch.float, device='cuda')
-                    rhs = torch.randn((8192, 8192), dtype=torch.float, device='cuda')
+                    lhs = torch.randn((8192, 8192), dtype=torch.float, device="cuda")
+                    rhs = torch.randn((8192, 8192), dtype=torch.float, device="cuda")
                     lhs @ rhs
-                    dist.all_reduce(torch.ones(1, dtype=torch.float, device='cuda'))
+                    dist.all_reduce(torch.ones(1, dtype=torch.float, device="cuda"))
                 for _ in range(num_tests):
                     fn()
                 prof.step()
@@ -167,8 +182,12 @@ def bench_kineto(fn, kernel_names, num_tests: int = 30, suppress_kineto_output:
     # Parse the profiling table
     assert isinstance(kernel_names, str) or isinstance(kernel_names, tuple)
     is_tupled = isinstance(kernel_names, tuple)
-    prof_lines = prof.key_averages().table(sort_by='cuda_time_total', max_name_column_width=100).split('\n')
-    kernel_names = (kernel_names, ) if isinstance(kernel_names, str) else kernel_names
+    prof_lines = (
+        prof.key_averages()
+        .table(sort_by="cuda_time_total", max_name_column_width=100)
+        .split("\n")
+    )
+    kernel_names = (kernel_names,) if isinstance(kernel_names, str) else kernel_names
     assert all([isinstance(name, str) for name in kernel_names])
 
     # In fallback mode, kernels may not appear in profiling table (they're Python functions)
@@ -178,17 +197,21 @@ def bench_kineto(fn, kernel_names, num_tests: int = 30, suppress_kineto_output:
         if count == 0:
             # Kernel not found - might be fallback mode, return 0 time
             import warnings
-            warnings.warn(f'Kernel {name} not found in profiling table (might be fallback mode)', UserWarning)
+
+            warnings.warn(
+                f"Kernel {name} not found in profiling table (might be fallback mode)",
+                UserWarning,
+            )
         elif count != 1:
             # Multiple matches - this is an error
-            assert False, f'Errors of the kernel {name} in the profiling table: found {count} times'
+            assert False, f"Errors of the kernel {name} in the profiling table: found {count} times"
 
     # Save chrome traces
     if trace_path is not None:
         prof.export_chrome_trace(trace_path)
 
     # Return average kernel times
-    units = {'ms': 1e3, 'us': 1e6}
+    units = {"ms": 1e3, "us": 1e6}
     kernel_times = []
     for name in kernel_names:
         found = False
@@ -197,7 +220,7 @@ def bench_kineto(fn, kernel_names, num_tests: int = 30, suppress_kineto_output:
                 time_str = line.split()[-2]
                 for unit, scale in units.items():
                     if unit in time_str:
-                        kernel_times.append(float(time_str.replace(unit, '')) / scale)
+                        kernel_times.append(float(time_str.replace(unit, "")) / scale)
                         found = True
                         break
                 if found:
diff --git a/mooncake-ep/tests/test_elastic_buffer.py b/python/tests/ep/test_elastic_buffer.py
similarity index 78%
rename from mooncake-ep/tests/test_elastic_buffer.py
rename to python/tests/ep/test_elastic_buffer.py
index 53f049303c..0443cbaf34 100644
--- a/mooncake-ep/tests/test_elastic_buffer.py
+++ b/python/tests/ep/test_elastic_buffer.py
@@ -10,7 +10,7 @@
 
     MOONCAKE_EP_NUM_LOCAL_RANKS=8 \
     torchrun --standalone --nproc_per_node=8 \
-      mooncake-ep/tests/test_elastic_buffer.py --quick
+      python/tests/ep/test_elastic_buffer.py --quick
 
 For multi-node hybrid validation, launch the same script with ``torchrun
 --nnodes`` and set ``MOONCAKE_EP_NUM_LOCAL_RANKS`` to the number of GPUs per
@@ -67,6 +67,12 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--num-experts", type=int, default=256)
     parser.add_argument("--num-topk", type=int, default=8)
     parser.add_argument("--num-sms", type=int, default=24)
+    parser.add_argument(
+        "--transport",
+        choices=("auto", "ibgda", "nccl"),
+        default=os.getenv("MOONCAKE_EP_TRANSPORT", "auto"),
+        help="Device transport; auto prefers NCCL and falls back to IPC + IBGDA.",
+    )
     parser.add_argument(
         "--route",
         choices=("alltoall", "local", "cross"),
@@ -78,6 +84,11 @@ def parse_args() -> argparse.Namespace:
         action=argparse.BooleanOptionalAction,
         default=True,
     )
+    parser.add_argument(
+        "--reconfigure",
+        action="store_true",
+        help="Rebuild the NCCL generation and verify post-update correctness.",
+    )
     parser.add_argument("--seed", type=int, default=2026)
     parser.add_argument(
         "--quick",
@@ -116,7 +127,9 @@ def make_route_plan(
     if local_experts <= 0:
         raise ValueError("num_experts must be at least world_size")
 
-    expert_offsets = torch.arange(num_topk, device="cuda", dtype=torch.long) % local_experts
+    expert_offsets = (
+        torch.arange(num_topk, device="cuda", dtype=torch.long) % local_experts
+    )
 
     if route == "cross" and buffer.num_scaleout_ranks > 1:
         dst_scaleout = (buffer.scaleout_rank_idx + 1) % buffer.num_scaleout_ranks
@@ -136,7 +149,9 @@ def make_route_plan(
             1,
         )
 
-    dst_ranks = (rank + torch.arange(num_topk, device="cuda", dtype=torch.long)) % world_size
+    dst_ranks = (
+        rank + torch.arange(num_topk, device="cuda", dtype=torch.long)
+    ) % world_size
     choices = dst_ranks * local_experts + expert_offsets
     unique_dst_ranks = int(torch.unique(dst_ranks).numel())
     return RoutePlan(
@@ -181,7 +196,7 @@ def check_dispatch_payload(
 
     base = torch.arange(num_tokens * hidden, device="cuda", dtype=torch.float32)
     base = base.view(num_tokens, hidden)
-    expected = (base[src_token] + src_rank.view(-1, 1).float() * multiplier + addend)
+    expected = base[src_token] + src_rank.view(-1, 1).float() * multiplier + addend
     expected = expected.to(torch.bfloat16)
     if not torch.equal(recv_x[:actual], expected):
         diff = (recv_x[:actual].float() - expected.float()).abs().max().item()
@@ -213,6 +228,7 @@ def main() -> None:
     if num_experts % world_size != 0:
         raise ValueError("num_experts must be divisible by world_size")
 
+    transport_kwargs = {} if args.transport == "auto" else {"transport": args.transport}
     buffer = ElasticBuffer(
         dist.group.WORLD,
         num_max_tokens_per_rank=max_tokens,
@@ -223,6 +239,7 @@ def main() -> None:
         allow_hybrid_mode=args.allow_hybrid_mode,
         allow_multiple_reduction=True,
         num_gpu_timeout_secs=10,
+        **transport_kwargs,
     )
 
     route_plan = make_route_plan(
@@ -234,7 +251,9 @@ def main() -> None:
         num_experts=num_experts,
         route=args.route,
     )
-    weights = torch.ones((args.num_tokens, args.num_topk), device="cuda", dtype=torch.float32)
+    weights = torch.ones(
+        (args.num_tokens, args.num_topk), device="cuda", dtype=torch.float32
+    )
 
     # CPU-sync dispatch: exact output extent and CPU-side expert counts.
     x0 = make_input(
@@ -355,7 +374,9 @@ def main() -> None:
         addend=31,
     )
     if handle2.num_recv_tokens_per_expert_list:
-        raise AssertionError(f"rank={rank}: no-CPU-sync path should not return CPU counts")
+        raise AssertionError(
+            f"rank={rank}: no-CPU-sync path should not return CPU counts"
+        )
     combined2, _, event3 = buffer.combine(
         recv2[:actual2].contiguous(),
         handle2,
@@ -382,7 +403,9 @@ def main() -> None:
         async_with_compute_stream=False,
     )
     torch.cuda.synchronize()
-    expanded_actual = int(expanded_handle.psum_num_recv_tokens_per_scaleup_rank[-1].item())
+    expanded_actual = int(
+        expanded_handle.psum_num_recv_tokens_per_scaleup_rank[-1].item()
+    )
     if expanded_actual != route_plan.expected_recv_tokens:
         raise AssertionError(f"rank={rank}: expanded dispatch received-token mismatch")
     expanded_output = int(expanded_handle.psum_num_recv_tokens_per_expert[-1].item())
@@ -393,18 +416,93 @@ def main() -> None:
     if expanded_idx.shape[0] != expanded_actual:
         raise AssertionError(f"rank={rank}: expanded metadata extent mismatch")
 
+    if args.reconfigure:
+        if buffer.transport != "nccl":
+            raise RuntimeError("--reconfigure requires the NCCL transport")
+
+        stale_handle = handle0
+        # Exercise retirement of more than one obsolete communicator/window
+        # generation before checking the new data path.
+        for _ in range(2):
+            buffer.update_ep_member()
+
+        try:
+            buffer.dispatch(
+                x0,
+                handle=stale_handle,
+                num_experts=num_experts,
+                num_max_tokens_per_rank=max_tokens,
+                num_sms=args.num_sms,
+            )
+        except RuntimeError as exc:
+            if "obsolete NCCL ElasticBuffer generation" not in str(exc):
+                raise
+        else:
+            raise AssertionError(
+                f"rank={rank}: cached dispatch accepted a stale EPHandle"
+            )
+
+        x3 = make_input(
+            rank=rank,
+            num_tokens=args.num_tokens,
+            hidden=args.hidden,
+            multiplier=4_000_000,
+            addend=47,
+        )
+        recv3, _idx3, w3, handle3, _ = buffer.dispatch(
+            x3,
+            topk_idx=route_plan.topk_idx,
+            topk_weights=weights,
+            num_experts=num_experts,
+            num_max_tokens_per_rank=max_tokens,
+            expert_alignment=1,
+            do_cpu_sync=True,
+            num_sms=args.num_sms,
+            async_with_compute_stream=False,
+        )
+        torch.cuda.synchronize()
+        actual3 = check_dispatch_payload(
+            rank=rank,
+            recv_x=recv3,
+            handle=handle3,
+            expected_recv_tokens=route_plan.expected_recv_tokens,
+            max_tokens=max_tokens,
+            num_tokens=args.num_tokens,
+            hidden=args.hidden,
+            multiplier=4_000_000,
+            addend=47,
+        )
+        combined3, _, _ = buffer.combine(
+            recv3[:actual3].contiguous(),
+            handle3,
+            topk_weights=w3[:actual3].contiguous(),
+            num_sms=args.num_sms,
+            async_with_compute_stream=False,
+        )
+        torch.cuda.synchronize()
+        expected3 = (x3.float() * route_plan.expected_combine_factor).to(torch.bfloat16)
+        check_combined(
+            rank=rank,
+            combined=combined3,
+            expected=expected3,
+            label="post-reconfiguration",
+        )
+
     distributed_barrier()
     if rank == 0:
         print(
             "MOONCAKE_ELASTIC_TEST_OK",
             f"world={world_size}",
             f"route={args.route}",
+            f"transport={buffer.transport}",
             f"recv={route_plan.expected_recv_tokens}",
             f"expanded={expanded_output}",
             f"scaleout={buffer.num_scaleout_ranks}",
             f"scaleup={buffer.num_scaleup_ranks}",
+            f"reconfigured={args.reconfigure}",
             flush=True,
         )
+    buffer.destroy()
     dist.destroy_process_group()
 
 
diff --git a/python/tests/ep/test_elastic_buffer_recovery.py b/python/tests/ep/test_elastic_buffer_recovery.py
new file mode 100644
index 0000000000..8d29ccce37
--- /dev/null
+++ b/python/tests/ep/test_elastic_buffer_recovery.py
@@ -0,0 +1,317 @@
+# Copyright 2026 KVCache.AI
+
+"""NCCL EP recovery integration tests using the Mooncake PG worker harness."""
+
+import os
+import sys
+import unittest
+from pathlib import Path
+
+import torch
+import torch.distributed as dist
+import torch.multiprocessing as mp
+
+try:
+    from mooncake import pg
+except ImportError as exc:
+    raise unittest.SkipTest(f"Mooncake PG is unavailable: {exc}") from exc
+
+# Reuse the source-tree PG harness without copying its process lifecycle logic.
+# Keep this import available to spawned workers and both pytest and unittest.
+sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "mooncake-pg" / "tests"))
+from pg_test_utils import (  # noqa: E402
+    MooncakePGCUDABackendTestCase,
+    MooncakePGWorkerContext,
+    wait_until,
+)
+
+
+BROKEN_RANK = 1
+_NCCL_ELASTIC_MAX_TOKENS = 128
+_NCCL_ELASTIC_HIDDEN = 4096
+_NCCL_ELASTIC_NUM_EXPERTS = 256
+_NCCL_ELASTIC_NUM_TOPK = 8
+_NCCL_ELASTIC_NUM_SMS = 24
+
+
+def _make_nccl_elastic_buffer():
+    """Construct the production two-rank NCCL elastic-kernel configuration."""
+    from mooncake.mooncake_elastic_buffer import ElasticBuffer
+
+    return ElasticBuffer(
+        dist.group.WORLD,
+        num_max_tokens_per_rank=_NCCL_ELASTIC_MAX_TOKENS,
+        hidden=_NCCL_ELASTIC_HIDDEN,
+        num_topk=_NCCL_ELASTIC_NUM_TOPK,
+        use_fp8_dispatch=False,
+        deterministic=False,
+        allow_hybrid_mode=True,
+        allow_multiple_reduction=True,
+        num_gpu_timeout_secs=10,
+        transport="nccl",
+    )
+
+
+def _run_nccl_elastic_data_round(
+    buffer,
+    logical_rank: int,
+    generation: int,
+):
+    """Dispatch and combine data through both logical ranks."""
+    num_tokens = 8
+    world_size = buffer.num_ranks
+    if world_size != 2:
+        raise AssertionError("NCCL ElasticBuffer recovery test expects two ranks")
+
+    local_experts = _NCCL_ELASTIC_NUM_EXPERTS // world_size
+    expert_offsets = torch.arange(
+        _NCCL_ELASTIC_NUM_TOPK, device="cuda", dtype=torch.long
+    )
+    dst_ranks = (
+        logical_rank
+        + torch.arange(_NCCL_ELASTIC_NUM_TOPK, device="cuda", dtype=torch.long)
+    ) % world_size
+    topk_idx = (
+        (dst_ranks * local_experts + expert_offsets)
+        .view(1, _NCCL_ELASTIC_NUM_TOPK)
+        .repeat(num_tokens, 1)
+        .contiguous()
+    )
+    topk_weights = torch.ones(
+        (num_tokens, _NCCL_ELASTIC_NUM_TOPK),
+        device="cuda",
+        dtype=torch.float32,
+    )
+
+    base = torch.arange(
+        num_tokens * _NCCL_ELASTIC_HIDDEN,
+        device="cuda",
+        dtype=torch.float32,
+    ).view(num_tokens, _NCCL_ELASTIC_HIDDEN)
+    rank_offset = logical_rank * 100000
+    generation_offset = generation * 17
+    x = (base + rank_offset + generation_offset).to(torch.bfloat16).contiguous()
+
+    recv_x, _recv_idx, recv_weights, handle, _event = buffer.dispatch(
+        x,
+        topk_idx=topk_idx,
+        topk_weights=topk_weights,
+        num_experts=_NCCL_ELASTIC_NUM_EXPERTS,
+        num_max_tokens_per_rank=_NCCL_ELASTIC_MAX_TOKENS,
+        expert_alignment=1,
+        do_cpu_sync=True,
+        num_sms=_NCCL_ELASTIC_NUM_SMS,
+        async_with_compute_stream=False,
+    )
+    torch.cuda.synchronize()
+
+    expected_recv_tokens = num_tokens * world_size
+    actual_recv_tokens = int(handle.psum_num_recv_tokens_per_scaleup_rank[-1].item())
+    if actual_recv_tokens != expected_recv_tokens:
+        raise AssertionError(
+            f"rank {logical_rank}: expected {expected_recv_tokens}"
+            f" received tokens, got {actual_recv_tokens}"
+        )
+
+    src_global = handle.recv_src_metadata[:actual_recv_tokens, 0].long()
+    src_rank = torch.div(
+        src_global,
+        _NCCL_ELASTIC_MAX_TOKENS,
+        rounding_mode="floor",
+    )
+    src_token = src_global % _NCCL_ELASTIC_MAX_TOKENS
+    expected_recv = (
+        base[src_token] + src_rank.view(-1, 1).float() * 100000 + generation_offset
+    ).to(torch.bfloat16)
+    if not torch.equal(recv_x[:actual_recv_tokens], expected_recv):
+        raise AssertionError(f"rank {logical_rank}: dispatch payload mismatch")
+
+    combined_x, _, _ = buffer.combine(
+        recv_x[:actual_recv_tokens].contiguous(),
+        handle,
+        topk_weights=recv_weights[:actual_recv_tokens].contiguous(),
+        num_sms=_NCCL_ELASTIC_NUM_SMS,
+        async_with_compute_stream=False,
+    )
+    torch.cuda.synchronize()
+    torch.testing.assert_close(
+        combined_x,
+        (x.float() * world_size).to(torch.bfloat16),
+        rtol=0.05,
+        atol=0.001,
+        msg=lambda msg: f"rank {logical_rank}: combine mismatch: {msg}",
+    )
+
+    return handle, x
+
+
+def _nccl_elastic_buffer_recovery_worker(
+    ctx: MooncakePGWorkerContext,
+    pre_failure_barrier: mp.Barrier,
+    broken_exited: mp.Event,
+    start_recovery: mp.Event,
+    membership_restored: mp.Event,
+    max_group_size: int | None = None,
+) -> None:
+    """Replace rank 1 and rebuild the NCCL ElasticBuffer generation."""
+    logical_rank = ctx.rank if ctx.proc_rank < ctx.world_size else BROKEN_RANK
+    capacity = ctx.world_size if max_group_size is None else max_group_size
+    reserved_slots = [0] * (capacity - ctx.world_size)
+
+    if ctx.proc_rank < ctx.world_size:
+        device = ctx.init_group(rank=logical_rank, max_group_size=max_group_size)
+        # The control PG may use CPU tensors while EP still runs on this GPU.
+        torch.cuda.set_device(logical_rank)
+        backend = ctx.get_backend()
+        buffer = _make_nccl_elastic_buffer()
+        stale_handle, stale_x = _run_nccl_elastic_data_round(
+            buffer, logical_rank, generation=0
+        )
+        ctx.synchronize()
+        pre_failure_barrier.wait(timeout=60.0)
+
+        if logical_rank == BROKEN_RANK:
+            ctx.record_result({"role": "broken"})
+            # Exit without destroying the process group or ElasticBuffer. This
+            # models an abrupt worker loss with a live NCCL generation.
+            os._exit(0)
+
+        if not broken_exited.wait(timeout=60.0):
+            raise TimeoutError("timed out waiting for departed NCCL EP rank")
+
+        # Force Mooncake PG to observe the failed peer and commit the reduced
+        # active-rank view before a replacement joins.
+        probe = torch.tensor([logical_rank], device=device)
+        work = dist.isend(probe, dst=BROKEN_RANK)
+        work.wait()
+        if pg.get_local_success(work):
+            raise AssertionError("P2P probe to departed rank unexpectedly succeeded")
+        active_ranks = pg.get_active_ranks(backend).cpu().tolist()
+        if active_ranks != [1, 0] + reserved_slots:
+            raise AssertionError(
+                "expected rank 1 to be inactive, " f"got active_ranks={active_ranks}"
+            )
+
+        start_recovery.set()
+        wait_until(
+            lambda: pg.get_peer_state(backend, [BROKEN_RANK])[0],
+            timeout_s=60.0,
+            poll_interval_s=0.05,
+            description="survivor waiting for replacement rank",
+        )
+
+        response = pg.recover_ranks(backend, [BROKEN_RANK])
+        if response.status != pg.ProposalStatus.Applied:
+            raise AssertionError(
+                "recover_ranks should apply before NCCL rebuild, got "
+                f"{response.status}: {response.reject_reason}"
+            )
+        membership_restored.set()
+        role = "survivor"
+    else:
+        if not start_recovery.wait(timeout=60.0):
+            raise TimeoutError("timed out waiting to start NCCL EP replacement")
+        device = ctx.init_group(
+            rank=logical_rank, max_group_size=max_group_size, is_extension=True
+        )
+        # The control PG may use CPU tensors while EP still runs on this GPU.
+        torch.cuda.set_device(logical_rank)
+        backend = ctx.get_backend()
+        pg.join_group(backend)
+        if not membership_restored.wait(timeout=60.0):
+            raise TimeoutError("timed out waiting for restored PG membership")
+        role = "replacement"
+
+    # The fixed-world NCCL bootstrap is collective. Wait until every live
+    # process has applied the fully restored logical-rank view before either
+    # survivors or replacements enter it.
+    wait_until(
+        lambda: pg.get_active_ranks(backend).cpu().tolist() == [1, 1] + reserved_slots,
+        timeout_s=60.0,
+        poll_interval_s=0.05,
+        description=f"rank {logical_rank} waiting for restored active-rank view",
+    )
+
+    if role == "survivor":
+        buffer.update_ep_member()
+        try:
+            buffer.dispatch(
+                stale_x,
+                handle=stale_handle,
+                num_experts=_NCCL_ELASTIC_NUM_EXPERTS,
+                num_max_tokens_per_rank=_NCCL_ELASTIC_MAX_TOKENS,
+                num_sms=_NCCL_ELASTIC_NUM_SMS,
+            )
+        except RuntimeError as exc:
+            if "obsolete NCCL ElasticBuffer generation" not in str(exc):
+                raise
+        else:
+            raise AssertionError("survivor accepted a handle from the old generation")
+    else:
+        buffer = _make_nccl_elastic_buffer()
+
+    _run_nccl_elastic_data_round(buffer, logical_rank, generation=1)
+    buffer.destroy()
+    ctx.record_result({"role": role})
+
+
+class TestNcclElasticBufferRecovery(MooncakePGCUDABackendTestCase):
+    world_size = 2
+
+    def test_nccl_elastic_buffer_recovery(self) -> None:
+        """NCCL EP rebuilds after Mooncake PG replaces a logical rank."""
+        self._run_nccl_elastic_buffer_recovery()
+
+    def test_nccl_elastic_buffer_recovery_with_reserved_capacity(self) -> None:
+        """Unused PG slots do not prevent NCCL construction or recovery."""
+        self._run_nccl_elastic_buffer_recovery(max_group_size=4)
+
+    def test_nccl_elastic_buffer_recovery_with_cpu_pg(self) -> None:
+        """A CPU control PG can bootstrap and recover the GPU NCCL data path."""
+        self.backend_name = "mooncake-cpu"
+        self.device_type = "cpu"
+        self._run_nccl_elastic_buffer_recovery(max_group_size=4)
+
+    def _run_nccl_elastic_buffer_recovery(
+        self, max_group_size: int | None = None
+    ) -> None:
+        if torch.cuda.device_count() < 2:
+            self.skipTest("NCCL ElasticBuffer recovery requires two CUDA devices")
+        try:
+            from mooncake import ep
+        except ImportError as exc:
+            self.skipTest(f"Mooncake EP is unavailable: {exc}")
+
+        if not ep.has_nccl_device_support():
+            self.skipTest("Mooncake EP was built without NCCL Device API support")
+
+        spawn_ctx = mp.get_context("spawn")
+        pre_failure_barrier = spawn_ctx.Barrier(2)
+        broken_exited = spawn_ctx.Event()
+        start_recovery = spawn_ctx.Event()
+        membership_restored = spawn_ctx.Event()
+
+        rows = self.spawn_backend_and_collect(
+            _nccl_elastic_buffer_recovery_worker,
+            pre_failure_barrier,
+            broken_exited,
+            start_recovery,
+            membership_restored,
+            max_group_size,
+            world_size=2,
+            nprocs=3,
+            timeout_s=180.0,
+            process_exit_events={BROKEN_RANK: broken_exited},
+        )
+        self.assert_all_ok(rows)
+        self.assertEqual(len([row for row in rows if row.get("role") == "survivor"]), 1)
+        self.assertEqual(
+            len([row for row in rows if row.get("role") == "replacement"]), 1
+        )
+        self.assertGreaterEqual(
+            len([row for row in rows if row.get("role") == "broken"]), 1
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/mooncake-ep/tests/test_ep_grid.py b/python/tests/ep/test_ep_grid.py
similarity index 95%
rename from mooncake-ep/tests/test_ep_grid.py
rename to python/tests/ep/test_ep_grid.py
index c48dff165d..473d201372 100644
--- a/mooncake-ep/tests/test_ep_grid.py
+++ b/python/tests/ep/test_ep_grid.py
@@ -23,10 +23,12 @@ def using_musa_backend() -> bool:
 
 
 def using_maca_backend() -> bool:
-    return (
-        os.getenv("MOONCAKE_EP_USE_MACA", "").upper() in {"1", "ON", "TRUE", "YES"}
-        or bool(getattr(torch.version, "maca", None))
-    )
+    return os.getenv("MOONCAKE_EP_USE_MACA", "").upper() in {
+        "1",
+        "ON",
+        "TRUE",
+        "YES",
+    } or bool(getattr(torch.version, "maca", None))
 
 
 def import_torchada_if_needed():
@@ -62,11 +64,12 @@ def run_test_iteration(
     return_recv_hook: bool,
     use_fallback: bool,
     fail_rank: int,
+    disable_p2p: bool = False,
     buf: Buffer = None,
 ):
-    assert not (async_finish and return_recv_hook), (
-        "Should be filtered out by generate_tests."
-    )
+    assert not (
+        async_finish and return_recv_hook
+    ), "Should be filtered out by generate_tests."
 
     torch.manual_seed(2026 + rank)
     scale = 1.0 - 0.05 * (rank / num_ranks)
@@ -111,7 +114,7 @@ def get_mock_factor(expert_id):
         max_tokens, hidden, num_ranks, num_experts
     )
     if buf is None:
-        buf = Buffer(group, num_ep_buffer_bytes)
+        buf = Buffer(group, num_ep_buffer_bytes, disable_p2p=disable_p2p)
 
     if use_fallback:
         buf._use_fallback = True
@@ -355,9 +358,9 @@ def get_mock_factor(expert_id):
     event.current_stream_wait()
     torch.cuda.synchronize()
 
-    assert active_ranks[fail_rank].item() == 0, (
-        f"[Rank {rank}] active_ranks[{fail_rank}] should be 0 after timeout"
-    )
+    assert (
+        active_ranks[fail_rank].item() == 0
+    ), f"[Rank {rank}] active_ranks[{fail_rank}] should be 0 after timeout"
     assert not torch.isnan(combined_x).any().item()
     testing.assert_close(
         combined_x,
@@ -443,6 +446,8 @@ def make_test_name(cfg):
         flags.append("hook")
     if cfg["use_fallback"]:
         flags.append("fallback")
+    if cfg["disable_p2p"]:
+        flags.append("no_p2p")
 
     if flags:
         parts.append("_".join(flags))
@@ -467,11 +472,12 @@ def generate_tests():
     fp8_options = [False] if using_maca_backend() else [False, True]
     test_grid = {
         "use_fp8": fp8_options,
-        "zero_copy": [False, True],
+        "zero_copy": [False],
         "async_finish": [False, True],
         "return_recv_hook": [False, True],
         "use_fallback": [False, True],
         "fail_rank": [-1, 1],
+        "disable_p2p": [False, True],
         "shapes": [
             {"max_tokens": 256, "hidden": 2048, "num_experts": 288, "top_k": 8},
         ],
diff --git a/python/tests/ep/test_mooncake_elastic_buffer_transport.py b/python/tests/ep/test_mooncake_elastic_buffer_transport.py
new file mode 100644
index 0000000000..a920bb33c7
--- /dev/null
+++ b/python/tests/ep/test_mooncake_elastic_buffer_transport.py
@@ -0,0 +1,414 @@
+# Copyright 2026 KVCache.AI
+
+from __future__ import annotations
+
+import inspect
+import sys
+import types
+
+import pytest
+import torch
+import torch.distributed as dist
+
+from mooncake.mooncake_elastic_buffer import (
+    ElasticBuffer,
+    _bootstrap_collective_device,
+    _requested_transport,
+    _resolve_nccl_membership_masks,
+    _resolve_transport_consensus,
+    _select_transport,
+    _select_transport_for_group,
+)
+
+
+def test_public_constructor_defaults_are_backward_compatible() -> None:
+    parameters = inspect.signature(ElasticBuffer).parameters
+    assert parameters["transport"].default == "auto"
+    assert parameters["explicitly_destroy"].default is False
+
+
+@pytest.mark.parametrize(
+    ("num_ranks", "num_rdma_ranks", "num_nvlink_ranks"),
+    [
+        (2, 1, 2),
+        (8, 1, 8),
+        (8, 2, 4),
+        (16, 2, 8),
+        (16, 4, 4),
+    ],
+)
+def test_auto_prefers_nccl_for_compiled_topologies(
+    num_ranks: int, num_rdma_ranks: int, num_nvlink_ranks: int
+) -> None:
+    assert (
+        _select_transport(
+            "auto",
+            True,
+            num_ranks,
+            num_rdma_ranks,
+            num_nvlink_ranks,
+            True,
+        )
+        == "nccl"
+    )
+
+
+@pytest.mark.parametrize(
+    ("nccl_available", "num_ranks", "num_rdma_ranks", "num_nvlink_ranks"),
+    [
+        (False, 8, 1, 8),
+        (True, 1, 1, 1),
+        (True, 4, 1, 4),
+        (True, 32, 4, 8),
+        (True, 10, 2, 4),
+    ],
+)
+def test_auto_falls_back_to_ibgda_when_nccl_cannot_run(
+    nccl_available: bool,
+    num_ranks: int,
+    num_rdma_ranks: int,
+    num_nvlink_ranks: int,
+) -> None:
+    assert (
+        _select_transport(
+            "auto",
+            nccl_available,
+            num_ranks,
+            num_rdma_ranks,
+            num_nvlink_ranks,
+            True,
+        )
+        == "ibgda"
+    )
+
+
+@pytest.mark.parametrize("requested", ["ibgda", "nccl"])
+def test_explicit_transport_is_never_rewritten(requested: str) -> None:
+    assert _select_transport(requested, False, 4, 1, 4, True) == requested
+
+
+def test_auto_falls_back_without_required_hybrid_mode() -> None:
+    assert _select_transport("auto", True, 8, 2, 4, False) == "ibgda"
+
+
+def test_torchrun_local_world_size_drives_topology(monkeypatch) -> None:
+    class Group:
+        @staticmethod
+        def size() -> int:
+            return 16
+
+    monkeypatch.delenv("MOONCAKE_EP_NUM_LOCAL_RANKS", raising=False)
+    monkeypatch.setenv("LOCAL_WORLD_SIZE", "4")
+    assert ElasticBuffer._calculate_physical_domain_size(Group()) == (4, 4)
+
+
+def test_environment_can_roll_auto_mode_back_to_ibgda(monkeypatch) -> None:
+    monkeypatch.setenv("MOONCAKE_EP_TRANSPORT", "IBGDA")
+    assert _requested_transport("auto") == "ibgda"
+    assert _requested_transport("nccl") == "nccl"
+
+
+def test_invalid_transport_is_rejected(monkeypatch) -> None:
+    monkeypatch.setenv("MOONCAKE_EP_TRANSPORT", "tcp")
+    with pytest.raises(ValueError, match="transport must be one of"):
+        _requested_transport("auto")
+
+
+@pytest.mark.parametrize("backend_name", ["gloo", "mooncake-cpu"])
+def test_group_transport_selection_uses_every_rank_capability(
+    monkeypatch, backend_name: str
+) -> None:
+    class Group:
+        @staticmethod
+        def size() -> int:
+            return 2
+
+    test_group = Group()
+    monkeypatch.setattr(dist, "get_backend", lambda _: backend_name)
+
+    def fake_all_gather(gathered_states, local_state, group=None) -> None:
+        assert group is test_group
+        assert local_state.device.type == "cpu"
+        for state in gathered_states:
+            state.copy_(local_state)
+        # Simulate rank 1 having the same request but no usable NCCL backend.
+        gathered_states[1][1] = 0
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    assert (
+        _select_transport_for_group(test_group, "auto", True, 2, 1, 2, True) == "ibgda"
+    )
+
+
+@pytest.mark.parametrize("rank_world_sizes", [[2, 2, 8, 8, 8, 8, 8, 8], [8, 8]])
+def test_nccl_consensus_rejects_changed_world_size_on_every_rank(
+    monkeypatch, rank_world_sizes: list[int]
+) -> None:
+    class Group:
+        @staticmethod
+        def size() -> int:
+            return len(rank_world_sizes)
+
+    test_group = Group()
+    monkeypatch.setattr(dist, "get_backend", lambda _: "gloo")
+
+    def fake_all_gather(gathered_states, local_state, group=None) -> None:
+        assert group is test_group
+        assert len(gathered_states) == test_group.size()
+        assert local_state.numel() == 4
+        for state, world_size in zip(gathered_states, rank_world_sizes):
+            # Survivors require NCCL; newly constructed buffers request auto.
+            required_code = 2 if world_size != test_group.size() else 0
+            state.copy_(
+                torch.tensor([0, 1, required_code, world_size], dtype=torch.int32)
+            )
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    for world_size in rank_world_sizes:
+        with pytest.raises(RuntimeError, match="fixed logical world size"):
+            _select_transport_for_group(
+                test_group,
+                "auto",
+                True,
+                world_size,
+                1,
+                world_size,
+                True,
+                required_transport="nccl" if world_size != test_group.size() else None,
+            )
+
+
+def test_nccl_consensus_rejects_missing_rank_state(monkeypatch) -> None:
+    class Group:
+        @staticmethod
+        def size() -> int:
+            return 2
+
+    test_group = Group()
+    monkeypatch.setattr(dist, "get_backend", lambda _: "gloo")
+
+    def fake_all_gather(gathered_states, local_state, group=None) -> None:
+        # Mooncake PG can leave inactive ranks' output slots untouched.
+        gathered_states[0].copy_(local_state)
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    with pytest.raises(RuntimeError, match="requirements are not met on ranks: 1"):
+        _select_transport_for_group(test_group, "nccl", True, 2, 1, 2, True)
+
+
+def test_transport_consensus_selects_nccl_when_every_rank_is_ready() -> None:
+    assert (
+        _resolve_transport_consensus([("auto", True, None), ("auto", True, None)])
+        == "nccl"
+    )
+
+
+@pytest.mark.parametrize(
+    "rank_states",
+    [
+        [("auto", True, None), ("auto", False, None)],
+        [("auto", False, None), ("auto", True, None)],
+    ],
+)
+def test_transport_consensus_falls_back_to_ibgda_group_wide(
+    rank_states: list[tuple[str, bool, str | None]],
+) -> None:
+    assert _resolve_transport_consensus(rank_states) == "ibgda"
+
+
+def test_transport_consensus_rejects_inconsistent_requests() -> None:
+    with pytest.raises(RuntimeError, match="requests differ"):
+        _resolve_transport_consensus([("auto", True, None), ("ibgda", True, None)])
+
+
+def test_transport_consensus_rejects_explicit_nccl_when_a_rank_is_unready() -> None:
+    with pytest.raises(RuntimeError, match="requirements are not met on ranks: 1"):
+        _resolve_transport_consensus([("nccl", True, None), ("nccl", False, None)])
+
+
+def test_transport_consensus_preserves_existing_nccl_generation() -> None:
+    assert (
+        _resolve_transport_consensus([("auto", True, "nccl"), ("auto", True, None)])
+        == "nccl"
+    )
+
+
+def test_existing_nccl_generation_rejects_an_unready_replacement() -> None:
+    with pytest.raises(RuntimeError, match="requirements are not met on ranks: 1"):
+        _resolve_transport_consensus([("auto", True, "nccl"), ("auto", False, None)])
+
+
+def test_transport_consensus_preserves_existing_ibgda_generation() -> None:
+    assert (
+        _resolve_transport_consensus([("auto", True, "ibgda"), ("auto", True, None)])
+        == "ibgda"
+    )
+
+
+def test_nccl_reconfiguration_accepts_consistent_full_membership() -> None:
+    _resolve_nccl_membership_masks([[1, 1], [1, 1]])
+
+
+@pytest.mark.parametrize(
+    "rank_masks",
+    [
+        [[1, 0], [1, 0]],
+        [[1, 1], [1, 0]],
+        [[1, 1], [1]],
+    ],
+)
+def test_nccl_reconfiguration_rejects_incomplete_membership(
+    rank_masks: list[list[int]],
+) -> None:
+    with pytest.raises(RuntimeError, match="complete fixed logical rank set"):
+        _resolve_nccl_membership_masks(rank_masks)
+
+
+@pytest.mark.parametrize("backend_name", ["gloo", "mooncake-cpu"])
+@pytest.mark.parametrize("active_mask", [[1, 1], [1, 1, 0, 0]])
+def test_nccl_membership_accepts_reserved_capacity(
+    monkeypatch, active_mask, backend_name: str
+) -> None:
+    buffer = object.__new__(ElasticBuffer)
+    buffer.num_ranks = 2
+    buffer.group = object()
+    monkeypatch.setattr(buffer, "_active_ranks_mask", lambda: active_mask)
+    monkeypatch.setattr(dist, "get_backend", lambda _: backend_name)
+
+    def fake_all_gather(gathered_masks, local_mask, group=None) -> None:
+        assert group is buffer.group
+        assert local_mask.device.type == "cpu"
+        assert local_mask.tolist() == [1, 1]
+        assert len(gathered_masks) == buffer.num_ranks
+        for mask in gathered_masks:
+            mask.copy_(local_mask)
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    buffer._require_full_nccl_membership()
+
+
+@pytest.mark.parametrize("active_mask", [[1, 0, 0, 0], [1], []])
+def test_nccl_membership_rejects_missing_logical_ranks(
+    monkeypatch, active_mask
+) -> None:
+    buffer = object.__new__(ElasticBuffer)
+    buffer.num_ranks = 2
+    buffer.group = object()
+    monkeypatch.setattr(buffer, "_active_ranks_mask", lambda: active_mask)
+    monkeypatch.setattr(dist, "get_backend", lambda _: "gloo")
+
+    def fake_all_gather(gathered_masks, local_mask, group=None) -> None:
+        for mask in gathered_masks:
+            mask.copy_(local_mask)
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    with pytest.raises(RuntimeError, match="complete fixed logical rank set"):
+        buffer._require_full_nccl_membership()
+
+
+def test_nccl_membership_rejects_incomplete_remote_view(monkeypatch) -> None:
+    buffer = object.__new__(ElasticBuffer)
+    buffer.num_ranks = 2
+    buffer.group = object()
+    monkeypatch.setattr(buffer, "_active_ranks_mask", lambda: [1, 1, 0, 0])
+    monkeypatch.setattr(dist, "get_backend", lambda _: "gloo")
+
+    def fake_all_gather(gathered_masks, local_mask, group=None) -> None:
+        gathered_masks[0].copy_(local_mask)
+        gathered_masks[1].copy_(torch.tensor([1, 0], dtype=torch.int32))
+
+    monkeypatch.setattr(dist, "all_gather", fake_all_gather)
+    with pytest.raises(RuntimeError, match=r"logical slots: \[1\]"):
+        buffer._require_full_nccl_membership()
+
+
+def test_nccl_generation_rejects_stale_handle() -> None:
+    class Handle:
+        _generation = (1, 2, 3)
+
+    buffer = object.__new__(ElasticBuffer)
+    buffer._generation = (4, 5, 6)
+    with pytest.raises(RuntimeError, match="obsolete NCCL ElasticBuffer generation"):
+        buffer._validate_handle_generation(Handle())
+
+
+def test_handle_without_generation_is_rejected_by_nccl_generation() -> None:
+    class LegacyHandle:
+        pass
+
+    buffer = object.__new__(ElasticBuffer)
+    buffer._generation = (4, 5, 6)
+    with pytest.raises(RuntimeError, match="obsolete NCCL ElasticBuffer generation"):
+        buffer._validate_handle_generation(LegacyHandle())
+
+
+def test_handle_without_generation_remains_valid_for_ibgda() -> None:
+    class LegacyHandle:
+        pass
+
+    buffer = object.__new__(ElasticBuffer)
+    buffer._generation = None
+    buffer._validate_handle_generation(LegacyHandle())
+
+
+@pytest.mark.parametrize("backend_name", ["mooncake", "mooncake-cpu"])
+def test_active_rank_mask_uses_registered_mooncake_backend(
+    monkeypatch, backend_name: str
+) -> None:
+    backend = object()
+    buffer = object.__new__(ElasticBuffer)
+    buffer.backend = backend
+    buffer.num_ranks = 2
+    buffer._device_index = 3
+
+    fake_ep = types.ModuleType("mooncake.ep")
+    fake_ep.get_active_ranks = lambda group: torch.tensor([1, 0])
+    monkeypatch.setitem(sys.modules, "mooncake.ep", fake_ep)
+    monkeypatch.setattr(dist, "get_backend", lambda group: backend_name)
+    synchronized_devices = []
+    monkeypatch.setattr(torch.cuda, "synchronize", synchronized_devices.append)
+
+    assert buffer._active_ranks_mask() == [1, 0]
+    assert synchronized_devices == [3]
+
+
+@pytest.mark.parametrize("backend_name", ["gloo", "nccl"])
+def test_non_mooncake_group_uses_full_membership(monkeypatch, backend_name) -> None:
+    buffer = object.__new__(ElasticBuffer)
+    buffer.backend = object()
+    buffer.num_ranks = 2
+    monkeypatch.setattr(dist, "get_backend", lambda _: backend_name)
+    # No native EP/PG helper is available for these process-group backends.
+    monkeypatch.setitem(sys.modules, "mooncake.ep", types.ModuleType("mooncake.ep"))
+    assert buffer._active_ranks_mask() == [1, 1]
+
+
+@pytest.mark.parametrize(
+    ("backend_name", "device"),
+    [("gloo", "cpu"), ("mooncake-cpu", "cpu"), ("mooncake", "cuda"), ("nccl", "cuda")],
+)
+def test_bootstrap_collective_device(monkeypatch, backend_name, device) -> None:
+    monkeypatch.setattr(dist, "get_backend", lambda _: backend_name)
+    assert _bootstrap_collective_device(object()) == device
+
+
+@pytest.mark.parametrize("backend_name", ["gloo", "mooncake-cpu"])
+def test_nccl_unique_id_exchange_uses_cpu_metadata(monkeypatch, backend_name) -> None:
+    buffer = object.__new__(ElasticBuffer)
+    buffer.group = object()
+    buffer.rank_idx = 0
+    expected_id = list(range(buffer._NCCL_UNIQUE_ID_WORDS))
+    fake_ep = types.SimpleNamespace(create_nccl_unique_id=lambda: expected_id)
+    monkeypatch.setattr(dist, "get_backend", lambda _: backend_name)
+    monkeypatch.setattr(dist, "get_global_rank", lambda group, rank: 0)
+    broadcasts = []
+
+    def fake_broadcast(tensor, src, group) -> None:
+        assert group is buffer.group
+        assert src == 0
+        assert tensor.device.type == "cpu"
+        broadcasts.append(tensor.tolist())
+
+    monkeypatch.setattr(dist, "broadcast", fake_broadcast)
+    assert buffer._exchange_nccl_unique_id(fake_ep) == expected_id
+    assert broadcasts == [[0], expected_id]
diff --git a/python/tests/ep/test_mooncake_ep.py b/python/tests/ep/test_mooncake_ep.py
new file mode 100644
index 0000000000..746afeb52e
--- /dev/null
+++ b/python/tests/ep/test_mooncake_ep.py
@@ -0,0 +1,354 @@
+import random
+import os
+import torch
+import torch.distributed as dist
+from functools import partial
+
+from mooncake.mooncake_ep_buffer import Buffer
+from ep_test_utils import (
+    init_dist,
+    bench,
+    bench_kineto,
+    calc_diff,
+    hash_tensor,
+    per_token_cast_back,
+)
+
+_USE_MACA = os.getenv("MOONCAKE_EP_USE_MACA", "").upper() in {
+    "1",
+    "ON",
+    "TRUE",
+    "YES",
+} or bool(getattr(torch.version, "maca", None))
+
+
+def test_main(
+    num_tokens: int,
+    hidden: int,
+    num_experts: int,
+    num_topk: int,
+    rank: int,
+    num_ranks: int,
+    group: dist.ProcessGroup,
+    buffer: Buffer,
+    seed: int = 0,
+):
+    torch.manual_seed(seed + rank)
+    random.seed(seed + rank)
+
+    assert num_experts % num_ranks == 0
+    num_local_experts = num_experts // num_ranks
+
+    # NOTES: the integers greater than 256 exceeds the BF16 precision limit
+    rank_offset = 128
+    assert (
+        num_ranks - rank_offset < 257
+    ), "Too many ranks (exceeding test precision limit)"
+
+    x = torch.ones((num_tokens, hidden), dtype=torch.bfloat16, device="cuda") * (
+        rank - rank_offset
+    )
+    x[:, -128:] = torch.arange(num_tokens, device="cuda").to(torch.bfloat16).view(-1, 1)
+    scores = (
+        torch.randn((num_tokens, num_experts), dtype=torch.float32, device="cuda").abs()
+        + 1
+    )
+    topk_idx = torch.topk(scores, num_topk, dim=-1, largest=True, sorted=True)[1]
+    topk_weights = torch.randn(
+        (num_tokens, num_topk), dtype=torch.float32, device="cuda"
+    ).abs()
+
+    # Randomly mask some positions
+    for i in range(10):
+        topk_idx[
+            random.randint(0, num_tokens - 1), random.randint(0, num_topk - 1)
+        ] = -1
+
+    # Check dispatch correctness
+    do_check = True
+    hash_value, num_times = 0, 0
+    active_ranks = torch.ones((num_tokens,), dtype=torch.int32, device="cuda")
+    for return_recv_hook in (False, True):
+        for dispatch_use_fp8 in [False] if _USE_MACA else [False, True]:
+            num_times += 1
+            for i in range((num_times % 2) + 1):
+                packed_recv_x, packed_recv_count, handle, event, hook = buffer.dispatch(
+                    x,
+                    topk_idx,
+                    active_ranks,
+                    num_tokens,
+                    num_experts,
+                    -1,
+                    use_fp8=dispatch_use_fp8,
+                    async_finish=not return_recv_hook,
+                    return_recv_hook=return_recv_hook,
+                )
+                hook() if return_recv_hook else event.current_stream_wait()
+            packed_recv_x = (
+                (packed_recv_x[0], packed_recv_x[1].contiguous())
+                if dispatch_use_fp8
+                else packed_recv_x
+            )
+            simulated_gemm_x = (
+                per_token_cast_back(
+                    packed_recv_x[0].view(-1, hidden),
+                    packed_recv_x[1].view(-1, hidden // 128),
+                ).view(packed_recv_x[0].shape)
+                if dispatch_use_fp8
+                else packed_recv_x.clone()
+            )
+            all_topk_idx = torch.empty(
+                (num_ranks, num_tokens, num_topk), dtype=topk_idx.dtype, device="cuda"
+            )
+            dist.all_gather_into_tensor(all_topk_idx, topk_idx, group=group)
+            for i in range(num_local_experts if do_check else 0):
+                expert_id = rank * num_local_experts + i
+                recv_x = (
+                    per_token_cast_back(packed_recv_x[0][i], packed_recv_x[1][i])
+                    if dispatch_use_fp8
+                    else packed_recv_x[i]
+                )
+                recv_count, recv_src_info, recv_layout_range = (
+                    packed_recv_count[i],
+                    handle[0][i],
+                    handle[1][i],
+                )
+
+                # Check expert indices
+                int_mask = (2**32) - 1
+                num_valid_tokens = recv_count.item()
+                assert (
+                    num_valid_tokens == (recv_layout_range & int_mask).sum().item()
+                ), f"{num_valid_tokens} != {recv_layout_range & int_mask}.sum().item()"
+                assert (
+                    num_valid_tokens == (all_topk_idx == expert_id).sum().item()
+                ), f"{num_valid_tokens} != {(all_topk_idx == expert_id).sum().item()}"
+
+                # Check received data
+                recv_x = recv_x[:num_valid_tokens]
+                recv_x_amin = recv_x[:, :-128].amin(dim=-1)
+                recv_src_info = recv_src_info[:num_valid_tokens]
+                assert torch.equal(recv_x_amin, recv_x[:, :-128].amax(dim=-1))
+                assert (
+                    recv_x[:, -128:] - recv_src_info.view(-1, 1) % num_tokens
+                ).sum().item() == 0
+                for j in range(num_ranks):
+                    begin_idx, count = (
+                        (recv_layout_range[j] >> 32).item(),
+                        (recv_layout_range[j] & int_mask).item(),
+                    )
+                    assert (recv_x_amin == j - rank_offset).sum().item() == (
+                        all_topk_idx[j] == expert_id
+                    ).sum().item()
+                    assert (
+                        recv_x[begin_idx : begin_idx + count][:-128] - j
+                    ).sum().item() == 0
+                if dispatch_use_fp8:
+                    hash_value ^= hash_tensor(packed_recv_x[0][i, :num_valid_tokens])
+                    hash_value ^= hash_tensor(packed_recv_x[1][i, :num_valid_tokens])
+                else:
+                    hash_value ^= hash_tensor(packed_recv_x[i, :num_valid_tokens])
+
+            # Check combine correctness
+            for zero_copy in (False, True):
+                if zero_copy:
+                    buffer.get_next_combine_buffer(handle)[:, :, :] = simulated_gemm_x
+                out = torch.empty(
+                    (num_tokens, hidden), dtype=torch.bfloat16, device="cuda"
+                )
+                combined_x, event, hook = buffer.combine(
+                    simulated_gemm_x,
+                    topk_idx,
+                    topk_weights,
+                    active_ranks,
+                    -1,
+                    handle,
+                    async_finish=not return_recv_hook,
+                    zero_copy=zero_copy,
+                    return_recv_hook=return_recv_hook,
+                    out=out,
+                )
+                hook() if return_recv_hook else event.current_stream_wait()
+                if do_check:
+                    diff = calc_diff(
+                        x
+                        * topk_weights.masked_fill(topk_idx == -1, 0)
+                        .sum(dim=1)
+                        .view(-1, 1),
+                        combined_x,
+                    )
+                    assert torch.isnan(combined_x).sum().item() == 0
+                    assert diff < 1e-5, f"Error: {diff=}, {zero_copy=}"
+                    hash_value ^= hash_tensor(combined_x)
+
+    # noinspection PyShadowingNames
+    def large_gemm_with_hook(hook):
+        mat_0 = torch.randn((8192, 8192), dtype=torch.float)
+        mat_1 = torch.randn((8192, 8192), dtype=torch.float)
+        mat_0 @ mat_1
+        hook()
+
+    # noinspection PyShadowingNames
+    def test_func(zero_copy: bool, return_recv_hook: bool):
+        recv_x, recv_count, handle, event, hook = buffer.dispatch(
+            x,
+            topk_idx,
+            active_ranks,
+            num_tokens,
+            num_experts,
+            -1,
+            async_finish=False,
+            return_recv_hook=return_recv_hook,
+        )
+        large_gemm_with_hook(hook) if return_recv_hook else None
+        if zero_copy:
+            buffer.get_next_combine_buffer(handle)[:, :, :] = simulated_gemm_x
+        combined_x, event, hook = buffer.combine(
+            simulated_gemm_x,
+            topk_idx,
+            topk_weights,
+            active_ranks,
+            -1,
+            handle,
+            zero_copy=zero_copy,
+            return_recv_hook=return_recv_hook,
+        )
+        large_gemm_with_hook(hook) if return_recv_hook else None
+
+    # Calculate bandwidth
+    num_fp8_bytes, num_bf16_bytes = (hidden + hidden / 128 * 4 + 16), hidden * 2
+    num_dispatch_comm_bytes, num_combine_comm_bytes = 0, 0
+    for i in range(num_tokens):
+        num_selections = (topk_idx[i] != -1).sum().item()
+        num_dispatch_comm_bytes += num_fp8_bytes * num_selections
+        num_combine_comm_bytes += num_bf16_bytes * num_selections
+
+    # Dispatch + combine testing
+    avg_t, min_t, max_t = bench(
+        partial(test_func, zero_copy=False, return_recv_hook=False)
+    )
+    print(
+        f"[rank {rank}] Dispatch + combine bandwidth: {(num_dispatch_comm_bytes + num_combine_comm_bytes) / 1e9 / avg_t:.2f} GB/s, "
+        f"avg_t={avg_t * 1e6:.2f} us, min_t={min_t * 1e6:.2f} us, max_t={max_t * 1e6:.2f} us",
+        flush=True,
+    )
+
+    # Separate profiling
+    # Skip profiling in fallback mode as kernels are Python functions, not CUDA kernels
+    if not buffer._use_fallback:
+        for return_recv_hook in (False, True):
+            group.barrier()
+            dispatch_t, combine_t = bench_kineto(
+                partial(test_func, zero_copy=True, return_recv_hook=return_recv_hook),
+                kernel_names=("dispatch", "combine"),
+                barrier_comm_profiling=True,
+                suppress_kineto_output=True,
+            )
+            if not return_recv_hook:
+                # In fallback mode, kernels may not be found (they're Python functions)
+                # So we skip bandwidth calculation if time is 0
+                if dispatch_t > 0 and combine_t > 0:
+                    print(
+                        f"[rank {rank}] Dispatch bandwidth: {num_dispatch_comm_bytes / 1e9 / dispatch_t:.2f} GB/s, avg_t={dispatch_t * 1e6:.2f} us | "
+                        f"Combine bandwidth: {num_combine_comm_bytes / 1e9 / combine_t:.2f} GB/s, avg_t={combine_t * 1e6:.2f} us",
+                        flush=True,
+                    )
+                else:
+                    print(
+                        f"[rank {rank}] Profiling skipped (kernels not found in CUDA profiler)",
+                        flush=True,
+                    )
+            else:
+                if dispatch_t > 0 and combine_t > 0:
+                    print(
+                        f"[rank {rank}] Dispatch send/recv time: {dispatch_t * 2 * 1e6:.2f} us | "
+                        f"Combine send/recv time: {combine_t * 2 * 1e6:.2f} us",
+                        flush=True,
+                    )
+                else:
+                    print(
+                        f"[rank {rank}] Profiling skipped (kernels not found in CUDA profiler)",
+                        flush=True,
+                    )
+    else:
+        if rank == 0:
+            print(
+                f"[rank {rank}] Profiling skipped (fallback mode - using Python implementation)",
+                flush=True,
+            )
+
+    return hash_value
+
+
+# noinspection PyUnboundLocalVariable
+def test_loop(local_rank: int, num_local_ranks: int):
+    rank, num_ranks, group = init_dist(local_rank, num_local_ranks)
+    num_tokens, hidden, num_topk, num_experts = 128, 7168, 8, 288
+
+    num_ep_buffer_bytes = Buffer.get_ep_buffer_size_hint(
+        num_tokens, hidden, num_ranks, num_experts
+    )
+    if local_rank == 0:
+        print(f"Allocating buffer size: {num_ep_buffer_bytes / 1e6} MB ...", flush=True)
+    buffer = Buffer(group, num_ep_buffer_bytes=num_ep_buffer_bytes)
+    # Mock a broken rank 1 to test effectiveness of EP recovery
+    if local_rank != 1:
+        buffer.update_ep_member()
+    else:
+        buffer = Buffer(group, num_ep_buffer_bytes=num_ep_buffer_bytes)
+
+    test_main(
+        num_tokens,
+        hidden,
+        num_experts,
+        num_topk,
+        rank,
+        num_ranks,
+        group,
+        buffer,
+        seed=1,
+    )
+
+    do_pressure_test = False
+    for seed in range(int(1e9) if do_pressure_test else 0):
+        if local_rank == 0:
+            print(f"Testing with seed {seed} ...", flush=True)
+        ref_hash = test_main(
+            num_tokens,
+            hidden,
+            num_experts,
+            num_topk,
+            rank,
+            num_ranks,
+            group,
+            buffer,
+            seed=seed,
+        )
+        for i in range(20):
+            assert (
+                test_main(
+                    num_tokens,
+                    hidden,
+                    num_experts,
+                    num_topk,
+                    rank,
+                    num_ranks,
+                    group,
+                    buffer,
+                    seed=seed,
+                )
+                == ref_hash
+            ), f"Error: seed={seed}"
+
+    # Cleanup with error handling (TCPStore warnings are expected in mooncake backend)
+    try:
+        dist.destroy_process_group()
+    except Exception:
+        # Ignore cleanup errors (TCPStore connection errors are expected)
+        pass
+
+
+if __name__ == "__main__":
+    # TODO: you may modify NUMA binding for less CPU overhead
+    num_processes = 2
+    torch.multiprocessing.spawn(test_loop, args=(num_processes,), nprocs=num_processes)
diff --git a/mooncake-wheel/tests/test_regmr_overhead.py b/python/tests/ep/test_regmr_overhead.py
similarity index 82%
rename from mooncake-wheel/tests/test_regmr_overhead.py
rename to python/tests/ep/test_regmr_overhead.py
index 424a701e16..9600ec14e1 100644
--- a/mooncake-wheel/tests/test_regmr_overhead.py
+++ b/python/tests/ep/test_regmr_overhead.py
@@ -8,12 +8,7 @@
 3. Performance difference between async vs sync memset
 
 Usage:
-    # Run as a module
-    python -m mooncake-wheel.tests.test_memset_regmr_overhead
-    
-    # Or run directly
-    cd mooncake-wheel/tests
-    python test_memset_regmr_overhead.py
+    python python/tests/ep/test_regmr_overhead.py
 """
 
 import os
@@ -24,9 +19,6 @@
 import numpy as np
 import unittest
 
-# Add project root to path for importing mooncake module
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../..'))
-
 from mooncake.mooncake_ep_buffer import Buffer
 from mooncake.engine import TransferEngine
 
@@ -39,58 +31,60 @@ def test_cuda_memset_overhead():
     print("\n" + "=" * 60)
     print("Testing CUDA memset overhead (sync vs async)")
     print("=" * 60)
-    
+
     if not torch.cuda.is_available():
         print("Skipped: CUDA not available")
         return
-    
-    sizes = [1 * 1024 * 1024,      # 1 MB
-             10 * 1024 * 1024,     # 10 MB
-             100 * 1024 * 1024,    # 100 MB
-             1024 * 1024 * 1024]   # 1 GB
-    
+
+    sizes = [
+        1 * 1024 * 1024,  # 1 MB
+        10 * 1024 * 1024,  # 10 MB
+        100 * 1024 * 1024,  # 100 MB
+        1024 * 1024 * 1024,
+    ]  # 1 GB
+
     for size in sizes:
         print(f"\nTest size: {size / 1e6:.2f} MB")
-        
+
         # Allocate memory
-        gpu_mem = torch.empty(size // 4, dtype=torch.float32, device='cuda')
+        gpu_mem = torch.empty(size // 4, dtype=torch.float32, device="cuda")
         stream = torch.cuda.Stream()
-        
+
         # Test sync memset (using tensor.fill_ which internally uses memset)
         sync_times = []
         for _ in range(10):
             torch.cuda.synchronize()
             start = time.perf_counter()
-            
+
             # Use tensor.fill_ which internally calls cudaMemset
             gpu_mem.fill_(0)
             torch.cuda.synchronize()
-            
+
             end = time.perf_counter()
             sync_times.append((end - start) * 1e6)
-        
+
         # Test async memset (using tensor.fill_ with stream)
         async_times = []
         for _ in range(10):
             torch.cuda.synchronize()
             start = time.perf_counter()
-            
+
             with torch.cuda.stream(stream):
                 # Use tensor.fill_ which can work with streams
                 gpu_mem.fill_(0)
             stream.synchronize()
-            
+
             end = time.perf_counter()
             async_times.append((end - start) * 1e6)
-        
+
         sync_avg = np.mean(sync_times)
         async_avg = np.mean(async_times)
-        
+
         print(f"  Sync memset: {sync_avg:.2f} us (avg)")
         print(f"  Async memset: {async_avg:.2f} us (avg)")
         if sync_avg > 0:
             print(f"  Improvement: {((sync_avg - async_avg) / sync_avg * 100):.1f}%")
-        
+
         del gpu_mem
         torch.cuda.empty_cache()
 
@@ -100,76 +94,80 @@ def test_ctrl_buf_init_overhead():
     print("\n" + "=" * 60)
     print("Testing ctrl_buf initialization overhead (simulated)")
     print("=" * 60)
-    
+
     if not torch.cuda.is_available():
         print("Skipped: CUDA not available")
         return
-    
+
     CTRL_BUF_SIZE = 1024 * 1024 * 1024  # 1 GB
-    
+
     print(f"ctrl_buf size: {CTRL_BUF_SIZE / 1e6:.2f} MB")
-    
+
     # Test 1: Allocation only, no memset
     times_alloc_only = []
     for _ in range(5):
         torch.cuda.synchronize()
         start = time.perf_counter()
-        
-        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device='cuda')
+
+        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device="cuda")
         torch.cuda.synchronize()
-        
+
         end = time.perf_counter()
         times_alloc_only.append((end - start) * 1e6)
         del mem
         torch.cuda.empty_cache()
-    
+
     # Test 2: Allocation + sync memset
     times_alloc_sync_memset = []
     for _ in range(5):
         torch.cuda.synchronize()
         start = time.perf_counter()
-        
-        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device='cuda')
+
+        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device="cuda")
         # Use tensor.fill_ which internally calls cudaMemset
         mem.fill_(0)
         torch.cuda.synchronize()
-        
+
         end = time.perf_counter()
         times_alloc_sync_memset.append((end - start) * 1e6)
         del mem
         torch.cuda.empty_cache()
-    
+
     # Test 3: Allocation + async memset
     times_alloc_async_memset = []
     stream = torch.cuda.Stream()
     for _ in range(5):
         torch.cuda.synchronize()
         start = time.perf_counter()
-        
-        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device='cuda')
+
+        mem = torch.empty(CTRL_BUF_SIZE // 4, dtype=torch.float32, device="cuda")
         with torch.cuda.stream(stream):
             # Use tensor.fill_ which can work with streams
             mem.fill_(0)
         stream.synchronize()
         torch.cuda.synchronize()
-        
+
         end = time.perf_counter()
         times_alloc_async_memset.append((end - start) * 1e6)
         del mem
         torch.cuda.empty_cache()
-    
+
     alloc_only_avg = np.mean(times_alloc_only)
     sync_memset_avg = np.mean(times_alloc_sync_memset)
     async_memset_avg = np.mean(times_alloc_async_memset)
-    
-    print(f"\nResults:")
+
+    print("\nResults:")
     print(f"  Allocation only: {alloc_only_avg:.2f} us")
     print(f"  Allocation + sync memset: {sync_memset_avg:.2f} us")
     print(f"  Allocation + async memset: {async_memset_avg:.2f} us")
     print(f"\nSync memset overhead: {sync_memset_avg - alloc_only_avg:.2f} us")
     print(f"Async memset overhead: {async_memset_avg - alloc_only_avg:.2f} us")
     if (sync_memset_avg - alloc_only_avg) > 0:
-        improvement = ((sync_memset_avg - async_memset_avg) / (sync_memset_avg - alloc_only_avg) * 100)
+        improvement = (
+            (sync_memset_avg - async_memset_avg)
+            / (sync_memset_avg - alloc_only_avg)
+            * 100
+        )
         print(f"Improvement: {improvement:.1f}%")
 
 
@@ -178,23 +176,24 @@ def test_transfer_engine_reg_mr_overhead():
     print("\n" + "=" * 60)
     print("Testing Transfer Engine reg_mr overhead")
     print("=" * 60)
-    
+
     if not torch.cuda.is_available():
         print("Skipped: CUDA not available")
         return
-    
+
     try:
         # Initialize Transfer Engine
         # Note: TransferEngine requires initialize() with parameters, not init()
         # For testing reg_mr overhead, we can use a minimal setup
         engine = TransferEngine()
-        
+
         # Get local hostname for initialization
         import socket
+
         hostname = socket.gethostname()
         local_ip = socket.gethostbyname(hostname)
         local_server_name = f"{local_ip}:0"  # Port 0 means auto-assign
-        
+
         # Initialize with P2PHANDSHAKE mode (no external metadata server needed)
         ret = engine.initialize(local_server_name, "P2PHANDSHAKE", "rdma", "")
         if ret != 0:
@@ -202,58 +201,64 @@ def test_transfer_engine_reg_mr_overhead():
             print("Note: This test requires RDMA support. Trying TCP instead...")
             ret = engine.initialize(local_server_name, "P2PHANDSHAKE", "tcp", "")
             if ret != 0:
-                print(f"Skipped: Transfer Engine initialization failed with TCP as well: {ret}")
+                print(
+                    f"Skipped: Transfer Engine initialization failed with TCP as well: {ret}"
+                )
                 return
-        
+
         # Test memory registration with different sizes
-        sizes = [1 * 1024 * 1024,      # 1 MB
-                 10 * 1024 * 1024,     # 10 MB
-                 100 * 1024 * 1024,     # 100 MB
-                 1024 * 1024 * 1024]    # 1 GB
-        
+        sizes = [
+            1 * 1024 * 1024,  # 1 MB
+            10 * 1024 * 1024,  # 10 MB
+            100 * 1024 * 1024,  # 100 MB
+            1024 * 1024 * 1024,
+        ]  # 1 GB
+
         for size in sizes:
             print(f"\nTest size: {size / 1e6:.2f} MB")
-            
+
             # Allocate GPU memory
             torch.cuda.synchronize()
             start_alloc = time.perf_counter()
-            gpu_mem = torch.empty(size // 4, dtype=torch.float32, device='cuda')
+            gpu_mem = torch.empty(size // 4, dtype=torch.float32, device="cuda")
             torch.cuda.synchronize()
             alloc_time = (time.perf_counter() - start_alloc) * 1e6
-            
+
             # Test registration overhead
             times = []
             for i in range(5):
                 torch.cuda.synchronize()
                 start = time.perf_counter()
-                
+
                 # Register memory
                 # Note: Python API uses register_memory (not registerLocalMemory)
                 # and it only takes 2 parameters: buffer_addr (uintptr_t) and capacity (size_t)
                 addr = gpu_mem.data_ptr()
                 ret = engine.register_memory(addr, size)
-                
+
                 torch.cuda.synchronize()
                 end = time.perf_counter()
-                
+
                 if ret == 0:
                     reg_time = (end - start) * 1e6
                     times.append(reg_time)
-                    
+
                     # Unregister
                     engine.unregister_memory(addr)
                 else:
                     print(f"  Registration failed: {ret}")
-            
+
             if times:
                 avg_time = np.mean(times)
                 min_time = np.min(times)
                 max_time = np.max(times)
-                
+
                 print(f"  Allocation time: {alloc_time:.2f} us")
-                print(f"  Registration time - avg: {avg_time:.2f} us, min: {min_time:.2f} us, max: {max_time:.2f} us")
+                print(
+                    f"  Registration time - avg: {avg_time:.2f} us, min: {min_time:.2f} us, max: {max_time:.2f} us"
+                )
                 print(f"  Total overhead: {alloc_time + avg_time:.2f} us")
-            
+
             del gpu_mem
             torch.cuda.empty_cache()
     except Exception as e:
@@ -265,80 +270,85 @@ def test_buffer_init_overhead():
     print("\n" + "=" * 60)
     print("Testing Buffer initialization overhead")
     print("=" * 60)
-    
+
     if not dist.is_initialized():
         print("Skipped: Distributed environment not initialized")
         print("Hint: Requires at least 2 GPUs and distributed environment")
         return
-    
+
     if not torch.cuda.is_available():
         print("Skipped: CUDA not available")
         return
-    
+
     try:
         num_tokens, hidden, num_ranks, num_experts = 128, 7168, 2, 288
-        num_ep_buffer_bytes = Buffer.get_ep_buffer_size_hint(num_tokens, hidden, num_ranks, num_experts)
-        
+        num_ep_buffer_bytes = Buffer.get_ep_buffer_size_hint(
+            num_tokens, hidden, num_ranks, num_experts
+        )
+
         print(f"Buffer size: {num_ep_buffer_bytes / 1e6:.2f} MB")
-        
+
         # Warmup
         for _ in range(3):
             try:
-                buffer = Buffer(dist.group.WORLD, num_ep_buffer_bytes=num_ep_buffer_bytes)
+                buffer = Buffer(
+                    dist.group.WORLD, num_ep_buffer_bytes=num_ep_buffer_bytes
+                )
                 del buffer
                 torch.cuda.empty_cache()
-            except:
+            except Exception:
                 pass
-        
+
         # Test multiple initializations
         times = []
         for i in range(10):
             torch.cuda.synchronize()
             start = time.perf_counter()
-            
+
             buffer = Buffer(dist.group.WORLD, num_ep_buffer_bytes=num_ep_buffer_bytes)
-            
+
             torch.cuda.synchronize()
             end = time.perf_counter()
-            
+
             init_time = (end - start) * 1e6  # Convert to microseconds
             times.append(init_time)
-            
+
             print(f"  Run {i+1}: {init_time:.2f} us")
-            
+
             del buffer
             torch.cuda.empty_cache()
             time.sleep(0.1)  # Brief rest
-        
+
         avg_time = np.mean(times[1:])  # Exclude first run
         min_time = np.min(times[1:])
         max_time = np.max(times[1:])
         std_time = np.std(times[1:])
-        
-        print(f"\nResults:")
+
+        print("\nResults:")
         print(f"  Average: {avg_time:.2f} us")
         print(f"  Min: {min_time:.2f} us")
         print(f"  Max: {max_time:.2f} us")
         print(f"  Std dev: {std_time:.2f} us")
-        
+
         return avg_time
     except Exception as e:
         print(f"Skipped: Buffer initialization test failed: {e}")
         import traceback
+
         traceback.print_exc()
 
 
 class TestMemsetRegMrOverhead(unittest.TestCase):
     """Unittest wrapper class for running with pytest or unittest"""
-    
+
     def test_cuda_memset(self):
         """Test CUDA memset overhead"""
         test_cuda_memset_overhead()
-    
+
     def test_ctrl_buf_init(self):
         """Test ctrl_buf initialization overhead"""
         test_ctrl_buf_init_overhead()
-    
+
     def test_transfer_engine_reg_mr(self):
         """Test Transfer Engine reg_mr overhead"""
         test_transfer_engine_reg_mr_overhead()
@@ -348,53 +358,62 @@ def main():
     """Main function"""
     print("Memset and reg_mr Overhead Test")
     print("=" * 60)
-    
+
     # Initialize distributed environment (if needed)
     # Note: Distributed tests require multiple processes, so we skip them by default
     # Users can manually set up distributed environment if needed
     dist_initialized = False
-    
+
     # Check if distributed environment is already initialized
     if dist.is_initialized():
         dist_initialized = True
-        print(f"Using existing distributed environment: rank={dist.get_rank()}, world_size={dist.get_world_size()}")
+        print(
+            f"Using existing distributed environment: rank={dist.get_rank()}, world_size={dist.get_world_size()}"
+        )
     else:
         # Don't try to initialize distributed environment automatically
         # This requires multiple processes and proper setup
         print("Note: Distributed environment not initialized")
-        print("Tests that require distributed environment (Buffer initialization) will be skipped")
-        print("To enable distributed tests, initialize the environment before running this script:")
+        print(
+            "Tests that require distributed environment (Buffer initialization) will be skipped"
+        )
+        print(
+            "To enable distributed tests, initialize the environment before running this script:"
+        )
         print("  - Use torch.multiprocessing.spawn with multiple processes")
         print("  - Or manually initialize dist.init_process_group() in each process")
         print("  - Or set environment variables and ensure all processes are running")
-    
+
     try:
         # Test 1: CUDA memset overhead (no distributed env needed)
         test_cuda_memset_overhead()
-        
+
         # Test 2: ctrl_buf initialization overhead (no distributed env needed)
         test_ctrl_buf_init_overhead()
-        
+
         # Test 3: Transfer Engine reg_mr overhead (no distributed env needed)
         test_transfer_engine_reg_mr_overhead()
-        
+
         # Test 4: Buffer initialization overhead (requires distributed environment)
         if dist_initialized:
             test_buffer_init_overhead()
         else:
             print("\n" + "=" * 60)
-            print("Skipping Buffer initialization test (requires distributed environment)")
+            print(
+                "Skipping Buffer initialization test (requires distributed environment)"
+            )
             print("=" * 60)
-        
+
     except Exception as e:
         print(f"\nError: {e}")
         import traceback
+
         traceback.print_exc()
     finally:
         if dist_initialized:
             try:
                 dist.destroy_process_group()
-            except:
+            except Exception:
                 pass
 
 
@@ -402,30 +421,32 @@ def main():
     # If run as script, execute main
     # If run as unittest, execute TestMemsetRegMrOverhead class
     import sys
-    
+
     # Check if we should run with multiprocessing (for distributed tests)
-    if len(sys.argv) > 1 and sys.argv[1] == '--distributed':
+    if len(sys.argv) > 1 and sys.argv[1] == "--distributed":
         # Run with multiprocessing for distributed tests
         import torch.multiprocessing as mp
-        
+
         def run_distributed_test(rank, world_size):
             """Run test in a distributed process"""
-            os.environ['MASTER_ADDR'] = '127.0.0.1'
-            os.environ['MASTER_PORT'] = '8361'
-            dist.init_process_group(backend='mooncake', rank=rank, world_size=world_size)
-            
+            os.environ["MASTER_ADDR"] = "127.0.0.1"
+            os.environ["MASTER_PORT"] = "8361"
+            dist.init_process_group(
+                backend="mooncake", rank=rank, world_size=world_size
+            )
+
             try:
                 main()
             finally:
                 dist.destroy_process_group()
-        
-        world_size = int(os.getenv('WORLD_SIZE', '2'))
+
+        world_size = int(os.getenv("WORLD_SIZE", "2"))
         if world_size < 2:
             print("Error: WORLD_SIZE must be at least 2 for distributed tests")
             sys.exit(1)
-        
+
         mp.spawn(run_distributed_test, args=(world_size,), nprocs=world_size, join=True)
-    elif len(sys.argv) > 1 and sys.argv[1] == '--unittest':
+    elif len(sys.argv) > 1 and sys.argv[1] == "--unittest":
         unittest.main(argv=sys.argv[1:])
     else:
         main()
diff --git a/mooncake-wheel/tests/test_cli.py b/python/tests/integration/test_cli.py
similarity index 85%
rename from mooncake-wheel/tests/test_cli.py
rename to python/tests/integration/test_cli.py
index 885411de24..3a1fc6946b 100644
--- a/mooncake-wheel/tests/test_cli.py
+++ b/python/tests/integration/test_cli.py
@@ -13,9 +13,7 @@ def test_entry_point_installed():
     try:
         # Check if mooncake_master is in PATH
         result = subprocess.run(
-            ["which", "mooncake_master"],
-            capture_output=True,
-            text=True
+            ["which", "mooncake_master"], capture_output=True, text=True
         )
 
         if result.returncode != 0:
@@ -24,9 +22,7 @@ def test_entry_point_installed():
 
         print(f"✅ mooncake_master entry point found at: {result.stdout.strip()}")
         result = subprocess.run(
-            ["which", "mooncake_client"],
-            capture_output=True,
-            text=True
+            ["which", "mooncake_client"], capture_output=True, text=True
         )
 
         if result.returncode != 0:
@@ -35,9 +31,7 @@ def test_entry_point_installed():
 
         print(f"✅ mooncake_client entry point found at: {result.stdout.strip()}")
         result = subprocess.run(
-            ["which", "transfer_engine_bench"],
-            capture_output=True,
-            text=True
+            ["which", "transfer_engine_bench"], capture_output=True, text=True
         )
 
         if result.returncode != 0:
@@ -67,10 +61,14 @@ def test_run_master_and_client():
         #    and the default 9003 is still held by a lingering master from the
         #    prior CXL test step when this smoke test runs.
         process = subprocess.Popen(
-            ["mooncake_master", "--port=61351", "--max_threads=2",
-             "--metrics_port=19003"],
+            [
+                "mooncake_master",
+                "--port=61351",
+                "--max_threads=2",
+                "--metrics_port=19003",
+            ],
             stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE
+            stderr=subprocess.PIPE,
         )
 
         # Give it a moment to start
@@ -80,9 +78,13 @@ def test_run_master_and_client():
         if process.poll() is None:
             print("✅ mooncake_master process started successfully")
             client_process = subprocess.Popen(
-                ["mooncake_client", "--master_server_address=127.0.0.1:61351", "--port=61352"],
+                [
+                    "mooncake_client",
+                    "--master_server_address=127.0.0.1:61351",
+                    "--port=61352",
+                ],
                 stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE
+                stderr=subprocess.PIPE,
             )
 
             # Give the client some time to connect
@@ -95,7 +97,7 @@ def test_run_master_and_client():
                 print("✅ mooncake_client process terminated successfully")
             else:
                 stdout, stderr = client_process.communicate()
-                print(f"❌ mooncake_client failed to start")
+                print("❌ mooncake_client failed to start")
                 print(f"stdout: {stdout.decode()}")
                 print(f"stderr: {stderr.decode()}")
             # Terminate the process
@@ -105,7 +107,7 @@ def test_run_master_and_client():
             return True
         else:
             stdout, stderr = process.communicate()
-            print(f"❌ mooncake_master process failed to start")
+            print("❌ mooncake_master process failed to start")
             print(f"stdout: {stdout.decode()}")
             print(f"stderr: {stderr.decode()}")
             return False
diff --git a/python/tests/packaging/test_installed_wheel.py b/python/tests/packaging/test_installed_wheel.py
new file mode 100644
index 0000000000..01d2970cdd
--- /dev/null
+++ b/python/tests/packaging/test_installed_wheel.py
@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import stat
+import subprocess
+import sys
+
+import pytest
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[3]
+
+
+def _project_version(project_file: str) -> str:
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+        import tomli as tomllib
+
+    project = tomllib.loads((REPOSITORY_ROOT / project_file).read_text())
+    return project["project"]["version"]
+
+
+@pytest.mark.parametrize(
+    ("wheel_variable", "project_file"),
+    [
+        ("MOONCAKE_TEST_WHEEL", "pyproject.toml"),
+        ("MOONCAKE_TEST_LEGACY_WHEEL", "mooncake-wheel/pyproject.toml"),
+    ],
+    ids=["unified", "legacy"],
+)
+def test_wheel_imports_outside_the_repository(
+    tmp_path: Path, wheel_variable: str, project_file: str
+) -> None:
+    wheel_value = os.environ.get(wheel_variable)
+    if not wheel_value:
+        pytest.skip(f"set {wheel_variable} to run the installed-wheel smoke test")
+
+    wheel = Path(wheel_value).resolve()
+    assert wheel.is_file(), f"wheel does not exist: {wheel}"
+
+    environment = tmp_path / "environment"
+    subprocess.run([sys.executable, "-m", "venv", str(environment)], check=True)
+    python = environment / "bin" / "python"
+    subprocess.run(
+        [str(python), "-m", "pip", "install", "--no-deps", str(wheel)],
+        check=True,
+    )
+
+    clean_environment = os.environ.copy()
+    clean_environment.pop("PYTHONPATH", None)
+    clean_environment["PYTHONNOUSERSITE"] = "1"
+    smoke_script = f"""
+from importlib import import_module, metadata, util
+from pathlib import Path
+import sys
+import mooncake
+
+cli_modules = (
+    "mooncake.cli",
+    "mooncake.cli_client",
+    "mooncake.cli_bench",
+    "mooncake.transfer_engine_topology_dump",
+)
+assert all(module not in sys.modules for module in cli_modules)
+
+import mooncake.cli
+import mooncake.cli_bench
+import mooncake.cli_client
+import mooncake.transfer_engine_topology_dump
+
+assert "mooncake.engine" not in sys.modules
+
+import mooncake.async_store
+import mooncake.engine
+import mooncake.mooncake_config
+import mooncake.reshard
+import mooncake.store
+
+package_path = Path(mooncake.__file__).resolve()
+repository_path = Path({str(REPOSITORY_ROOT)!r}).resolve()
+assert not package_path.is_relative_to(repository_path), (package_path, repository_path)
+assert metadata.version("mooncake-transfer-engine") == {_project_version(project_file)!r}
+assert "administration" in metadata.metadata("mooncake-transfer-engine").get_all("Provides-Extra", [])
+assert mooncake.BufferPool is mooncake.store.BufferPool
+assert issubclass(
+    mooncake.async_store.MooncakeDistributedStoreAsync,
+    mooncake.store.MooncakeDistributedStore,
+)
+assert Path(mooncake.async_store.__file__).resolve().parent == package_path.parent
+assert mooncake.engine.TransferEngine is not None
+assert mooncake.mooncake_config.MooncakeConfig is not None
+for ep_module in (
+    "ep.py",
+    "mooncake_ep_buffer.py",
+    "mooncake_elastic_buffer.py",
+):
+    assert (package_path.parent / ep_module).is_file(), ep_module
+entry_points = {{
+    entry_point.name: entry_point.value
+    for entry_point in metadata.entry_points(group="console_scripts")
+}}
+expected_entry_points = {{
+    "mooncake_master": "mooncake.cli:main",
+    "mooncake_client": "mooncake.cli_client:main",
+    "transfer_engine_bench": "mooncake.cli_bench:main",
+    "transfer_engine_topology_dump": "mooncake.transfer_engine_topology_dump:main",
+}}
+assert {{name: entry_points[name] for name in expected_entry_points}} == expected_entry_points
+
+for module in (
+    "mooncake.mooncake_ssd_register",
+    "mooncake.mooncake_ssd_unregister",
+    "mooncake.spdk_tgt_create",
+):
+    import_module(module)
+assert util.find_spec("paramiko") is None
+assert "paramiko" not in sys.modules
+
+installed_files = {{str(path) for path in metadata.files("mooncake-transfer-engine") or []}}
+assert {{
+    "mooncake/_administration.py",
+    "mooncake/mooncake_ssd_register.py",
+    "mooncake/mooncake_ssd_unregister.py",
+    "mooncake/spdk_tgt_create.py",
+}} <= installed_files
+"""
+    subprocess.run(
+        [str(python), "-I", "-c", smoke_script],
+        cwd=tmp_path,
+        env=clean_environment,
+        check=True,
+    )
+
+    package_query = "from pathlib import Path; import mooncake; print(Path(mooncake.__file__).parent)"
+    package_result = subprocess.run(
+        [str(python), "-I", "-c", package_query],
+        cwd=tmp_path,
+        env=clean_environment,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    package_directory = Path(package_result.stdout.strip())
+    fake_binary = "#!/bin/sh\nprintf '%s\\n' \"$*\"\n"
+    for binary_name in ("mooncake_master", "mooncake_client", "transfer_engine_bench"):
+        binary = package_directory / binary_name
+        binary.write_text(fake_binary)
+        binary.chmod(binary.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    module_commands = {
+        "mooncake_master": "mooncake.cli",
+        "mooncake_client": "mooncake.cli_client",
+        "transfer_engine_bench": "mooncake.cli_bench",
+    }
+    for command_name, module_name in module_commands.items():
+        command_result = subprocess.run(
+            [str(environment / "bin" / command_name), "console-script-smoke"],
+            cwd=tmp_path,
+            env=clean_environment,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        assert command_result.stdout.strip() == "console-script-smoke"
+
+        module_result = subprocess.run(
+            [str(python), "-I", "-m", module_name, "module-smoke"],
+            cwd=tmp_path,
+            env=clean_environment,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        assert module_result.stdout.strip() == "module-smoke"
+
+    topology_commands = (
+        [str(environment / "bin" / "transfer_engine_topology_dump"), "--help"],
+        [
+            str(python),
+            "-I",
+            "-m",
+            "mooncake.transfer_engine_topology_dump",
+            "--help",
+        ],
+    )
+    for command in topology_commands:
+        result = subprocess.run(
+            command,
+            cwd=tmp_path,
+            env=clean_environment,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        assert "Dump device topology" in result.stdout
+
+    def check_help():
+        for module in (
+            "mooncake.mooncake_ssd_register",
+            "mooncake.mooncake_ssd_unregister",
+            "mooncake.spdk_tgt_create",
+        ):
+            result = subprocess.run(
+                [str(python), "-I", "-m", module, "--help"],
+                cwd=tmp_path,
+                env=clean_environment,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            assert "usage:" in result.stdout
+
+    check_help()
+    subprocess.run(
+        [str(python), "-m", "pip", "install", f"{wheel}[administration]"],
+        check=True,
+    )
+    subprocess.run(
+        [str(python), "-I", "-c", "import paramiko; assert paramiko.SSHClient"],
+        cwd=tmp_path,
+        env=clean_environment,
+        check=True,
+    )
+    check_help()
diff --git a/python/tests/packaging/test_project.py b/python/tests/packaging/test_project.py
new file mode 100644
index 0000000000..2455281b75
--- /dev/null
+++ b/python/tests/packaging/test_project.py
@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+    import tomli as tomllib
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[3]
+CLI_MODULES = (
+    "cli.py",
+    "cli_client.py",
+    "cli_bench.py",
+    "transfer_engine_topology_dump.py",
+)
+CLI_ENTRY_POINTS = {
+    "mooncake_master": "mooncake.cli:main",
+    "mooncake_client": "mooncake.cli_client:main",
+    "transfer_engine_bench": "mooncake.cli_bench:main",
+    "transfer_engine_topology_dump": "mooncake.transfer_engine_topology_dump:main",
+}
+
+
+def test_scikit_build_core_is_the_only_build_backend() -> None:
+    project = tomllib.loads((REPOSITORY_ROOT / "pyproject.toml").read_text())
+
+    assert project["build-system"]["build-backend"] == "scikit_build_core.build"
+    assert project["tool"]["scikit-build"]["wheel"]["packages"] == ["python/mooncake"]
+    assert project["tool"]["scikit-build"]["install"]["components"] == ["python"]
+    assert project["tool"]["scikit-build"]["sdist"]["include"] == [
+        "extern/yalantinglibs/**",
+        "!extern/yalantinglibs/.git",
+    ]
+    assert project["tool"]["scikit-build"]["sdist"]["exclude"] == [
+        "extern/yalantinglibs/.git"
+    ]
+    assert "setuptools>=61" in project["build-system"]["requires"]
+    assert "pip>=23" in project["build-system"]["requires"]
+    assert project["tool"]["scikit-build"]["cmake"]["define"]["USE_CUDA"] is False
+    assert project["tool"]["scikit-build"]["cmake"]["define"]["WITH_EP"] is False
+
+
+def test_dependency_boundaries_are_declared() -> None:
+    project = tomllib.loads((REPOSITORY_ROOT / "pyproject.toml").read_text())
+    metadata = project["project"]
+
+    assert set(metadata["dependencies"]) == {"aiohttp", "msgpack", "requests"}
+    assert set(metadata["optional-dependencies"]) == {
+        "administration",
+        "dev",
+        "hardware",
+        "structured",
+        "vllm",
+    }
+    assert metadata["optional-dependencies"]["administration"] == ["paramiko"]
+
+
+def test_legacy_wheel_administration_extra_matches_root_project() -> None:
+    project = tomllib.loads((REPOSITORY_ROOT / "pyproject.toml").read_text())
+    legacy = tomllib.loads(
+        (REPOSITORY_ROOT / "mooncake-wheel" / "pyproject.toml").read_text()
+    )
+
+    assert (
+        legacy["project"]["optional-dependencies"]["administration"]
+        == project["project"]["optional-dependencies"]["administration"]
+    )
+    assert not any("paramiko" in dep for dep in legacy["project"]["dependencies"])
+
+
+def test_tracked_source_roots_contain_no_generated_native_artifacts() -> None:
+    package_root = REPOSITORY_ROOT / "python" / "mooncake"
+
+    assert (package_root / "__init__.py").is_file()
+    assert not list(package_root.rglob("*.so"))
+    assert not list((REPOSITORY_ROOT / "mooncake-pg" / "torch").rglob("*.so"))
+
+
+def test_async_store_has_one_authoritative_source() -> None:
+    canonical_module = REPOSITORY_ROOT / "python" / "mooncake" / "async_store.py"
+    legacy_module = (
+        REPOSITORY_ROOT / "mooncake-integration" / "store" / "async_store.py"
+    )
+
+    assert canonical_module.is_file()
+    assert not legacy_module.exists()
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "store" / "test_async_store.py"
+    ).is_file()
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "store" / "async_store_integration.py"
+    ).is_file()
+    assert not (REPOSITORY_ROOT / "scripts" / "test_async_store.py").exists()
+
+    cmake = (REPOSITORY_ROOT / "mooncake-integration" / "CMakeLists.txt").read_text()
+    legacy_builder = (REPOSITORY_ROOT / "scripts" / "build_wheel.sh").read_text()
+    assert '../python/mooncake/async_store.py"' in cmake
+    assert 'CMAKE_CURRENT_SOURCE_DIR}/store/async_store.py"' not in cmake
+    assert "cp python/mooncake/async_store.py " in legacy_builder
+    assert "cp mooncake-integration/store/async_store.py " not in legacy_builder
+
+
+def test_ep_modules_have_one_authoritative_source() -> None:
+    package_root = REPOSITORY_ROOT / "python" / "mooncake"
+    legacy_package_root = REPOSITORY_ROOT / "mooncake-wheel" / "mooncake"
+
+    for module in (
+        "ep.py",
+        "mooncake_ep_buffer.py",
+        "mooncake_elastic_buffer.py",
+    ):
+        assert (package_root / module).is_file()
+        assert not (legacy_package_root / module).exists()
+
+    test_root = REPOSITORY_ROOT / "python" / "tests" / "ep"
+    for test_file in (
+        "ep_test_utils.py",
+        "test_elastic_buffer.py",
+        "test_ep_grid.py",
+        "test_mooncake_ep.py",
+        "test_regmr_overhead.py",
+    ):
+        assert (test_root / test_file).is_file()
+
+    for legacy_test in (
+        REPOSITORY_ROOT / "mooncake-ep" / "tests" / "test_elastic_buffer.py",
+        REPOSITORY_ROOT / "mooncake-ep" / "tests" / "test_ep_grid.py",
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "ep_test_utils.py",
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_mooncake_ep.py",
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_regmr_overhead.py",
+    ):
+        assert not legacy_test.exists()
+
+
+def test_cli_has_one_authoritative_source_and_test_location() -> None:
+    package_root = REPOSITORY_ROOT / "python" / "mooncake"
+    legacy_package_root = REPOSITORY_ROOT / "mooncake-wheel" / "mooncake"
+
+    for module in CLI_MODULES:
+        assert (package_root / module).is_file()
+        assert not (legacy_package_root / module).exists()
+
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "integration" / "test_cli.py"
+    ).is_file()
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "unit" / "test_cli_modules.py"
+    ).is_file()
+    assert not (REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_cli.py").exists()
+
+
+def test_scikit_build_consumes_unified_python_sources() -> None:
+    """Lock the Phase-2 cut-over invariants for the scikit-build wheel path.
+
+    These are read-only source checks. The scikit-build backend uses the
+    repository-root CMakeLists.txt, which must pull in python/CMakeLists.txt
+    (the \"unified\" Python sources) while mooncake-integration installs the
+    CLI binaries next to the package so the console scripts resolve them.
+
+    The legacy mooncake-wheel tree still supplies the not-yet-migrated pure-
+    Python modules at install time (Python/CMakeLists.txt DIRECTORY rule);
+    Phase 2 should move those into python/mooncake and drop the rule.
+    """
+    root_cmake = (REPOSITORY_ROOT / "CMakeLists.txt").read_text()
+    # SKBUILD must route through the unified python/CMakeLists.txt.
+    assert "if(SKBUILD)" in root_cmake
+    assert "add_subdirectory(python)" in root_cmake
+
+    python_cmake = (REPOSITORY_ROOT / "python" / "CMakeLists.txt").read_text()
+    assert "../mooncake-wheel/mooncake/" in python_cmake
+    assert 'PATTERN "__init__.py" EXCLUDE' in python_cmake
+    # Modules still supplied from the legacy tree at build time. Phase 2 should
+    # migrate these into python/mooncake and drop the DIRECTORY rule above.
+    for module in (
+        "http_metadata_server.py",
+        "mooncake_store_service.py",
+        "mooncake_connector_v1.py",
+        "vllm_v1_proxy_server.py",
+        "pg.py",
+        "structured_object_store.py",
+        "dataproto_catalog.py",
+    ):
+        assert (REPOSITORY_ROOT / "mooncake-wheel" / "mooncake" / module).is_file()
+
+    integration_cmake = (
+        REPOSITORY_ROOT / "mooncake-integration" / "CMakeLists.txt"
+    ).read_text()
+    # The store CLI binaries ship next to the package under SKBUILD so the
+    # mooncake.cli / mooncake.cli_client wrappers resolve them in place.
+    assert "install(TARGETS mooncake_master mooncake_client" in integration_cmake
+    assert "RUNTIME DESTINATION ${MOONCAKE_PYTHON_INSTALL_DIR}" in integration_cmake
+    assert "if(WITH_TE AND BUILD_EXAMPLES)" in integration_cmake
+
+
+def test_python_package_init_keeps_namespace_extension() -> None:
+    """The unified python/mooncake package must behave like the legacy wheel
+    package: both extend the namespace so independently installed mooncake
+    subpackages (e.g. mooncake-reshard / mooncake-pg) remain importable."""
+    init = (REPOSITORY_ROOT / "python" / "mooncake" / "__init__.py").read_text()
+    assert "extend_path" in init
+    assert "__path__ = extend_path(__path__, __name__)" in init
+
+    legacy_init = (
+        REPOSITORY_ROOT / "mooncake-wheel" / "mooncake" / "__init__.py"
+    ).read_text()
+    assert "extend_path" in legacy_init
+
+
+def test_cli_entry_points_remain_stable_across_build_interfaces() -> None:
+    for project_file in (
+        REPOSITORY_ROOT / "pyproject.toml",
+        REPOSITORY_ROOT / "mooncake-wheel" / "pyproject.toml",
+    ):
+        project = tomllib.loads(project_file.read_text())
+        scripts = project["project"]["scripts"]
+        assert {name: scripts[name] for name in CLI_ENTRY_POINTS} == CLI_ENTRY_POINTS
+
+
+def test_cli_build_inputs_use_the_canonical_sources() -> None:
+    legacy_build = (REPOSITORY_ROOT / "scripts" / "build_wheel.sh").read_text()
+    assert 'MIGRATED_PYTHON_SOURCE_DIR="python/mooncake"' in legacy_build
+    for module in CLI_MODULES:
+        assert module in legacy_build
+    # The shared launcher must also be staged so the setuptools wheel has it.
+    assert "_launcher.py" in legacy_build
+
+    integration_cmake = (
+        REPOSITORY_ROOT / "mooncake-integration" / "CMakeLists.txt"
+    ).read_text()
+    for module in (
+        "cli.py",
+        "cli_client.py",
+        "cli_bench.py",
+        "transfer_engine_topology_dump.py",
+    ):
+        assert f"../python/mooncake/{module}" in integration_cmake
+        assert f"../mooncake-wheel/mooncake/{module}" not in integration_cmake
+
+
+def test_lightweight_modules_have_one_authoritative_source() -> None:
+    package_root = REPOSITORY_ROOT / "python" / "mooncake"
+    legacy_package_root = REPOSITORY_ROOT / "mooncake-wheel" / "mooncake"
+
+    for module in ("buffer_pool.py", "mooncake_config.py"):
+        assert (package_root / module).is_file()
+        assert not (legacy_package_root / module).exists()
+
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "unit" / "test_mooncake_config.py"
+    ).is_file()
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "store" / "test_buffer_pool_native.py"
+    ).is_file()
+    assert not (
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_mooncake_config.py"
+    ).exists()
+    assert not (
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_buffer_pool_native.py"
+    ).exists()
+
+
+def test_ssd_administration_modules_have_one_authoritative_source() -> None:
+    package_root = REPOSITORY_ROOT / "python" / "mooncake"
+    legacy_package_root = REPOSITORY_ROOT / "mooncake-wheel" / "mooncake"
+    direct_install = (
+        REPOSITORY_ROOT / "mooncake-integration" / "CMakeLists.txt"
+    ).read_text()
+    legacy_builder = (REPOSITORY_ROOT / "scripts" / "build_wheel.sh").read_text()
+    modules = (
+        "_administration.py",
+        "mooncake_ssd_register.py",
+        "mooncake_ssd_unregister.py",
+        "spdk_tgt_create.py",
+    )
+
+    for module in modules:
+        assert (package_root / module).is_file()
+        assert not (legacy_package_root / module).exists()
+        assert f"../python/mooncake/{module}" in direct_install
+        assert f"../mooncake-wheel/mooncake/{module}" not in direct_install
+        assert module in legacy_builder
+
+    assert (
+        REPOSITORY_ROOT / "python" / "tests" / "ssd" / "test_spdk_tgt_create.py"
+    ).is_file()
+    assert not (
+        REPOSITORY_ROOT / "mooncake-wheel" / "tests" / "test_spdk_tgt_create.py"
+    ).exists()
+
+
+def test_pg_extension_build_stages_outside_the_source_tree(
+    tmp_path: Path,
+) -> None:
+    cmake = shutil.which("cmake")
+    if cmake is None:
+        pytest.skip("CMake is required to exercise the PG staging script")
+
+    source = tmp_path / "source" / "mooncake-pg" / "torch"
+    common = tmp_path / "source" / "mooncake-common"
+    source.mkdir(parents=True)
+    common.mkdir(parents=True)
+    (common / "SetupPyTorchEnv.cmake").write_text("")
+    (source / "setup.py").write_text(
+        """\
+from pathlib import Path
+import sys
+
+build_lib = Path(sys.argv[sys.argv.index("--build-lib") + 1])
+package = build_lib / "mooncake"
+package.mkdir(parents=True, exist_ok=True)
+(package / "pg_fake.so").write_bytes(b"extension")
+"""
+    )
+
+    core = tmp_path / "libmooncake_pg.so"
+    device = tmp_path / "libmooncake_pg_device.so"
+    core.write_bytes(b"core")
+    device.write_bytes(b"device")
+    staging = tmp_path / "staging"
+    build = tmp_path / "build"
+
+    subprocess.run(
+        [
+            cmake,
+            f"-DSOURCE_DIR={source}",
+            "-DEP_TORCH_VERSIONS=",
+            f"-DSTAGING_DIR={staging}",
+            f"-DBUILD_DIR={build}",
+            f"-DPG_CORE_SO_PATH={core}",
+            f"-DPG_DEVICE_SO_PATH={device}",
+            f"-DPython3_EXECUTABLE={sys.executable}",
+            "-P",
+            str(REPOSITORY_ROOT / "mooncake-pg" / "torch" / "BuildPgExt.cmake"),
+        ],
+        check=True,
+    )
+
+    assert (staging / "pg_fake.so").read_bytes() == b"extension"
+    assert (staging / device.name).read_bytes() == b"device"
+    assert (build / "current" / "lib" / "mooncake" / "pg_fake.so").is_file()
+    assert not list(source.rglob("*.so"))
diff --git a/python/tests/ssd/test_administration.py b/python/tests/ssd/test_administration.py
new file mode 100644
index 0000000000..34ca944c48
--- /dev/null
+++ b/python/tests/ssd/test_administration.py
@@ -0,0 +1,35 @@
+import builtins
+from unittest.mock import Mock, patch
+
+import pytest
+
+from mooncake._administration import require_paramiko
+from mooncake.spdk_tgt_create import SPDKTgtCreator
+
+
+def test_missing_paramiko_reports_install_command():
+    real_import = builtins.__import__
+
+    def without_paramiko(name, *args, **kwargs):
+        if name == "paramiko":
+            raise ModuleNotFoundError("No module named 'paramiko'", name=name)
+        return real_import(name, *args, **kwargs)
+
+    with patch("builtins.__import__", side_effect=without_paramiko):
+        creator = SPDKTgtCreator(["ip:127.0.0.1 path:/home/spdk"])
+        with pytest.raises(RuntimeError, match=r"pip install .*\[administration\]"):
+            creator._ssh_connect("127.0.0.1")
+
+
+def test_paramiko_is_loaded_on_demand():
+    paramiko = Mock()
+    with patch.dict("sys.modules", {"paramiko": paramiko}):
+        assert require_paramiko() is paramiko
+
+
+def test_broken_transitive_dependency_is_not_hidden():
+    error = ModuleNotFoundError("No module named 'cryptography'", name="cryptography")
+    with patch("builtins.__import__", side_effect=error):
+        with pytest.raises(ModuleNotFoundError) as caught:
+            require_paramiko()
+    assert caught.value is error
diff --git a/python/tests/ssd/test_spdk_tgt_create.py b/python/tests/ssd/test_spdk_tgt_create.py
new file mode 100644
index 0000000000..a1537c0d44
--- /dev/null
+++ b/python/tests/ssd/test_spdk_tgt_create.py
@@ -0,0 +1,36 @@
+import sys
+from unittest.mock import patch
+
+from mooncake.spdk_tgt_create import SPDKTgtCreator, parse_arguments
+
+
+def test_parse_arguments_accepts_ssh_port():
+    with patch.object(
+        sys,
+        "argv",
+        [
+            "spdk_tgt_create",
+            "--spdk_target_info",
+            "ip:127.0.0.1 path:/home/spdk",
+            "--port",
+            "2222",
+        ],
+    ):
+        args = parse_arguments()
+
+    assert args.port == 2222
+
+
+def test_ssh_connect_uses_requested_port():
+    creator = SPDKTgtCreator(["ip:127.0.0.1 path:/home/spdk"])
+
+    with patch("mooncake.spdk_tgt_create.require_paramiko") as require_paramiko:
+        ssh_client = require_paramiko.return_value.SSHClient
+        creator._ssh_connect("127.0.0.1", port=2222)
+
+    ssh_client.return_value.connect.assert_called_once_with(
+        "127.0.0.1",
+        port=2222,
+        username="root",
+        password=None,
+    )
diff --git a/scripts/test_async_store.py b/python/tests/store/async_store_integration.py
similarity index 85%
rename from scripts/test_async_store.py
rename to python/tests/store/async_store_integration.py
index fea5c69407..5cb7558d6a 100644
--- a/scripts/test_async_store.py
+++ b/python/tests/store/async_store_integration.py
@@ -27,15 +27,17 @@
 
 DEFAULT_MOONCAKE_CONFIG_PATH_ENV = "MOONCAKE_CONFIG_PATH"
 DEFAULT_GLOBAL_SEGMENT_SIZE = 16 * 1024 * 1024 * 1024  # 16 GiB
-DEFAULT_LOCAL_BUFFER_SIZE = 8 * 1024 * 1024 * 1024    # 8 GB
+DEFAULT_LOCAL_BUFFER_SIZE = 8 * 1024 * 1024 * 1024  # 8 GB
 DEFAULT_MASTER_METRICS_PORT = 9003
 DEFAULT_CHECK_SERVER = False
 
+
 def verify_tensor_equality(original, received, rtol=0, atol=0, verbose=True):
     """
     Utility to compare two tensors (CPU/GPU/Numpy).
     Identical to the synchronous version.
     """
+
     def to_numpy(x):
         if isinstance(x, torch.Tensor):
             if x.is_cuda:
@@ -56,12 +58,16 @@ def to_numpy(x):
 
     if orig_np.shape != recv_np.shape:
         if verbose:
-            print(f"❌ Shape mismatch: original {orig_np.shape} vs received {recv_np.shape}")
+            print(
+                f"❌ Shape mismatch: original {orig_np.shape} vs received {recv_np.shape}"
+            )
         return False
 
     if orig_np.dtype != recv_np.dtype:
         if verbose:
-            print(f"❌ Dtype mismatch: original {orig_np.dtype} vs received {recv_np.dtype}")
+            print(
+                f"❌ Dtype mismatch: original {orig_np.dtype} vs received {recv_np.dtype}"
+            )
         return False
 
     if np.array_equal(orig_np, recv_np):
@@ -80,8 +86,10 @@ def to_numpy(x):
                 print(f"   Received: {recv_val}")
         return False
 
+
 def parse_global_segment_size(value) -> int:
-    if isinstance(value, int): return value
+    if isinstance(value, int):
+        return value
     if isinstance(value, str):
         s = value.strip().lower()
         if s.endswith("gb"):
@@ -97,18 +105,23 @@ def generate_tensors(num_tensors, size_mb):
     dim = int(np.sqrt(num_elements))
     dim = (dim // 8) * 8
 
-    tensors = [torch.randn(dim, dim, dtype=torch.float32).contiguous() for _ in range(num_tensors)]
+    tensors = [
+        torch.randn(dim, dim, dtype=torch.float32).contiguous()
+        for _ in range(num_tensors)
+    ]
     keys = [f"test_tensor_{i}_{int(time.time()*1000)}" for i in range(num_tensors)]
     return keys, tensors
 
+
 # ==========================================
 #  Module Level Setup/Teardown
 # ==========================================
 
+
 def setUpModule():
     """
     Initialize the Async wrapper globally.
-    Note: We invoke setup() synchronously via asyncio.run() to ensure C++ client is ready 
+    Note: We invoke setup() synchronously via asyncio.run() to ensure C++ client is ready
     before any tests run. This mimics the sync script's behavior.
     """
     global GLOBAL_STORE, GLOBAL_CONFIG
@@ -121,7 +134,9 @@ def setUpModule():
         # Increase max_workers to simulate high async concurrency
         GLOBAL_STORE = MooncakeDistributedStoreAsync()
 
-        print(f"[{os.getpid()}] (Async) Connecting to Mooncake Master at {GLOBAL_CONFIG.master_server_address}...")
+        print(
+            f"[{os.getpid()}] (Async) Connecting to Mooncake Master at {GLOBAL_CONFIG.master_server_address}..."
+        )
 
         def _do_setup():
             return GLOBAL_STORE.setup(
@@ -146,6 +161,7 @@ def _do_setup():
         print(f"❌ Failed to establish global store connection: {e}")
         sys.exit(1)
 
+
 def tearDownModule():
     global GLOBAL_STORE
     if GLOBAL_STORE:
@@ -157,10 +173,12 @@ def tearDownModule():
         finally:
             GLOBAL_STORE = None
 
+
 # ==========================================
 #  Base Test Class (Async)
 # ==========================================
 
+
 class MooncakeAsyncTestBase(unittest.IsolatedAsyncioTestCase):
     async def asyncSetUp(self):
         """Executed before each test method."""
@@ -176,10 +194,12 @@ async def asyncSetUp(self):
         # For now, we assume remove_all wraps C++ synchronous logic nicely in a thread.
         await self.store.async_remove_all()
 
+
 # ==========================================
 #  Basic Bytes I/O & Auxiliary Tests
 # ==========================================
 
+
 class TestMooncakeBasicFunctional(MooncakeAsyncTestBase):
     async def test_01_bytes_put_get(self):
         """Test basic single key-value (bytes) storage."""
@@ -201,7 +221,7 @@ async def test_02_bytes_batch_io(self):
         count = 10
         keys = [f"test_bytes_batch_{i}" for i in range(count)]
         # Generate different length values
-        values = [f"value_{i}_{'x'*i}".encode('utf-8') for i in range(count)]
+        values = [f"value_{i}_{'x'*i}".encode("utf-8") for i in range(count)]
 
         # 1. Batch Put
         rcs = await self.store.async_put_batch(keys, values)
@@ -287,7 +307,7 @@ async def test_05_remove_by_regex(self):
     async def test_07_large_bytes_io(self):
         """Test larger bytes payload (non-tensor path)."""
         key = "test_large_bytes"
-        size = 10 * 1024 * 1024 # 10MB
+        size = 10 * 1024 * 1024  # 10MB
         # Create random bytes
         data = os.urandom(size)
 
@@ -298,10 +318,12 @@ async def test_07_large_bytes_io(self):
         self.assertEqual(len(retrieved), size)
         self.assertEqual(retrieved, data)
 
+
 # ==========================================
 #  Tensor Functional Tests
 # ==========================================
 
+
 class TestMooncakeTensorFunctional(MooncakeAsyncTestBase):
     async def test_01_basic_put_get(self):
         """Verify basic put and get functionality."""
@@ -329,7 +351,9 @@ async def test_02_tp_single_tensor(self):
         target_tensor = tensors[0]
 
         # 1. Put with TP
-        rc = await self.store.async_put_tensor_with_tp(key, target_tensor, tp_size=tp_size, split_dim=split_dim)
+        rc = await self.store.async_put_tensor_with_tp(
+            key, target_tensor, tp_size=tp_size, split_dim=split_dim
+        )
         self.assertEqual(rc, 0, "put_tensor_with_tp failed")
 
         # 2. Verify existence of shards
@@ -344,16 +368,25 @@ async def test_02_tp_single_tensor(self):
         # Launch all gets in parallel
         tasks = []
         for rank in range(tp_size):
-            tasks.append(self.store.async_get_tensor_with_tp(key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim))
+            tasks.append(
+                self.store.async_get_tensor_with_tp(
+                    key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim
+                )
+            )
 
         slices = await asyncio.gather(*tasks)
 
         for rank, t_slice in enumerate(slices):
             self.assertIsNotNone(t_slice, f"Slice for rank {rank} is None")
-            self.assertTrue(torch.equal(t_slice, expected_chunks[rank]), f"Data mismatch for rank {rank}")
+            self.assertTrue(
+                torch.equal(t_slice, expected_chunks[rank]),
+                f"Data mismatch for rank {rank}",
+            )
 
         reconstructed = torch.cat(slices, dim=split_dim)
-        self.assertTrue(torch.equal(reconstructed, target_tensor), "Reconstruction mismatch")
+        self.assertTrue(
+            torch.equal(reconstructed, target_tensor), "Reconstruction mismatch"
+        )
 
     async def test_03_tp_batch(self):
         tp_size = 2
@@ -362,15 +395,23 @@ async def test_03_tp_batch(self):
         keys, tensors = generate_tensors(num_tensors, 8)
 
         # 1. Batch Put with TP
-        results = await self.store.async_batch_put_tensor_with_tp(keys, tensors, tp_size=tp_size, split_dim=split_dim)
-        self.assertTrue(all(r == 0 for r in results), f"Batch put failed. Results: {results}")
+        results = await self.store.async_batch_put_tensor_with_tp(
+            keys, tensors, tp_size=tp_size, split_dim=split_dim
+        )
+        self.assertTrue(
+            all(r == 0 for r in results), f"Batch put failed. Results: {results}"
+        )
 
         # 2. Batch Get per Rank (Concurrently fetch both ranks)
         tasks = []
         for rank in range(tp_size):
-            tasks.append(self.store.async_batch_get_tensor_with_tp(keys, tp_rank=rank, tp_size=tp_size))
+            tasks.append(
+                self.store.async_batch_get_tensor_with_tp(
+                    keys, tp_rank=rank, tp_size=tp_size
+                )
+            )
 
-        all_shards = await asyncio.gather(*tasks) # List of lists
+        all_shards = await asyncio.gather(*tasks)  # List of lists
 
         # 3. Verify & Reconstruct
         for i in range(num_tensors):
@@ -380,8 +421,10 @@ async def test_03_tp_batch(self):
 
             for rank in range(tp_size):
                 shard = all_shards[rank][i]
-                self.assertTrue(torch.equal(shard, expected_chunks[rank]),
-                                f"Tensor {i} Rank {rank} data mismatch")
+                self.assertTrue(
+                    torch.equal(shard, expected_chunks[rank]),
+                    f"Tensor {i} Rank {rank} data mismatch",
+                )
                 reconstruction_parts.append(shard)
 
             recon = torch.cat(reconstruction_parts, dim=split_dim)
@@ -391,13 +434,19 @@ async def test_04_tp_consistency(self):
         input_tensor = torch.arange(12).view(3, 4)
         tp_size = 2
 
-        await self.store.async_batch_put_tensor_with_tp(['key'], [input_tensor], tp_size=tp_size, split_dim=1)
+        await self.store.async_batch_put_tensor_with_tp(
+            ["key"], [input_tensor], tp_size=tp_size, split_dim=1
+        )
         chunked_tensors = input_tensor.chunk(chunks=2, dim=1)
 
         # Parallel fetch
         t0, t1 = await asyncio.gather(
-            self.store.async_batch_get_tensor_with_tp(['key'], tp_rank=0, tp_size=tp_size),
-            self.store.async_batch_get_tensor_with_tp(['key'], tp_rank=1, tp_size=tp_size)
+            self.store.async_batch_get_tensor_with_tp(
+                ["key"], tp_rank=0, tp_size=tp_size
+            ),
+            self.store.async_batch_get_tensor_with_tp(
+                ["key"], tp_rank=1, tp_size=tp_size
+            ),
         )
         tmp_tensor_0 = t0[0]
         tmp_tensor_1 = t1[0]
@@ -420,9 +469,11 @@ async def test_04_tp_consistency(self):
 
         # Parallel get_into
         t2_task = self.store.async_batch_get_tensor_with_tp_into(
-            ['key'], [buffer_ptr_2], [buffer_spacing], tp_rank=0, tp_size=tp_size)
+            ["key"], [buffer_ptr_2], [buffer_spacing], tp_rank=0, tp_size=tp_size
+        )
         t3_task = self.store.async_batch_get_tensor_with_tp_into(
-            ['key'], [buffer_ptr_3], [buffer_spacing], tp_rank=1, tp_size=tp_size)
+            ["key"], [buffer_ptr_3], [buffer_spacing], tp_rank=1, tp_size=tp_size
+        )
 
         t2_res, t3_res = await asyncio.gather(t2_task, t3_task)
         tmp_tensor_2 = t2_res[0]
@@ -447,7 +498,9 @@ async def test_05_put_get_into(self):
         rc = await self.store.async_put_tensor(key, tensor)
         self.assertEqual(rc, 0)
 
-        retrieved = await self.store.async_get_tensor_into(key, large_buffer_ptr, total_buffer_size)
+        retrieved = await self.store.async_get_tensor_into(
+            key, large_buffer_ptr, total_buffer_size
+        )
         self.assertIsNotNone(retrieved)
         self.assertTrue(torch.equal(tensor, retrieved))
 
@@ -475,7 +528,9 @@ async def test_06_batch_put_get_into(self):
         results = await self.store.async_batch_put_tensor(keys, tensors)
         self.assertTrue(all(r == 0 for r in results))
 
-        res = await self.store.async_batch_get_tensor_into(keys, buffer_ptrs, buffer_sizes)
+        res = await self.store.async_batch_get_tensor_into(
+            keys, buffer_ptrs, buffer_sizes
+        )
 
         self.assertEqual(len(res), len(tensors))
         for j in range(batch_size):
@@ -489,7 +544,9 @@ async def test_07_put_get_into_with_tp(self):
         key = "get_into_with_tp_test"
         tensor = torch.randn(1024, 1024, dtype=torch.float32)
 
-        result = await self.store.async_put_tensor_with_tp(key, tensor, tp_size=tp_size, split_dim=split_dim)
+        result = await self.store.async_put_tensor_with_tp(
+            key, tensor, tp_size=tp_size, split_dim=split_dim
+        )
         self.assertEqual(result, 0)
 
         all_shards = []
@@ -516,7 +573,7 @@ async def _fetch_rank(rank):
 
         for _, shard, buf, ptr in results:
             all_shards.append(shard)
-            registered_buffers.append((buf, ptr)) # Keep buf alive
+            registered_buffers.append((buf, ptr))  # Keep buf alive
 
         # Validate
         original = tensor
@@ -540,7 +597,9 @@ async def test_08_batch_put_get_into_with_tp(self):
         num_tensors = 4
         keys, tensors = generate_tensors(num_tensors, 8)
 
-        results = await self.store.async_batch_put_tensor_with_tp(keys, tensors, tp_size=tp_size, split_dim=split_dim)
+        results = await self.store.async_batch_put_tensor_with_tp(
+            keys, tensors, tp_size=tp_size, split_dim=split_dim
+        )
         self.assertTrue(all(r == 0 for r in results))
 
         async def _fetch_batch_rank(rank):
@@ -551,7 +610,7 @@ async def _fetch_batch_rank(rank):
             l_buf = (ctypes.c_ubyte * total_size)()
             l_ptr = ctypes.addressof(l_buf)
 
-            ptrs = [l_ptr + i*spacing for i in range(batch_size)]
+            ptrs = [l_ptr + i * spacing for i in range(batch_size)]
             sizes = [spacing] * batch_size
 
             await self.store.async_register_buffer(l_ptr, total_size)
@@ -586,8 +645,12 @@ async def _fetch_batch_rank(rank):
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Async Mooncake Store Tests")
-    parser.add_argument("--mode", type=str, default="all", choices=["all", "Tensorfunc", "Basicfunc"])
-    parser.add_argument("--threads", type=int, default=8, help="Number of concurrent tasks")
+    parser.add_argument(
+        "--mode", type=str, default="all", choices=["all", "Tensorfunc", "Basicfunc"]
+    )
+    parser.add_argument(
+        "--threads", type=int, default=8, help="Number of concurrent tasks"
+    )
     parser.add_argument("--count", type=int, default=800, help="Total items")
     parser.add_argument("--size_mb", type=float, default=0.5, help="Tensor MB")
 
@@ -604,4 +667,4 @@ async def _fetch_batch_rank(rank):
 
     runner = unittest.TextTestRunner(verbosity=2)
     result = runner.run(suite)
-    sys.exit(not result.wasSuccessful())
\ No newline at end of file
+    sys.exit(not result.wasSuccessful())
diff --git a/python/tests/store/test_async_store.py b/python/tests/store/test_async_store.py
new file mode 100644
index 0000000000..9ac82aa18f
--- /dev/null
+++ b/python/tests/store/test_async_store.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+import importlib
+from pathlib import Path
+import sys
+import threading
+from types import ModuleType
+
+import pytest
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[3]
+PYTHON_ROOT = REPOSITORY_ROOT / "python"
+CANONICAL_MODULE = PYTHON_ROOT / "mooncake" / "async_store.py"
+_MISSING = object()
+
+
+class MockMooncakeDistributedStore:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, bytes, int, int]] = []
+        self.non_callable = 42
+
+    def put(self, key: str, value: bytes, *, ttl: int = 0) -> tuple[str, int]:
+        self.calls.append((key, value, ttl, threading.get_ident()))
+        return key, ttl
+
+
+@pytest.fixture()
+def async_store_module() -> Iterator[ModuleType]:
+    module_names = (
+        "mooncake",
+        "mooncake.async_store",
+        "mooncake.store",
+    )
+    saved_modules = {name: sys.modules.get(name, _MISSING) for name in module_names}
+    for name in module_names:
+        sys.modules.pop(name, None)
+
+    package = ModuleType("mooncake")
+    package.__path__ = [str(PYTHON_ROOT / "mooncake")]
+    store = ModuleType("mooncake.store")
+    store.MooncakeDistributedStore = MockMooncakeDistributedStore
+    sys.modules["mooncake"] = package
+    sys.modules["mooncake.store"] = store
+
+    try:
+        yield importlib.import_module("mooncake.async_store")
+    finally:
+        for name in module_names:
+            sys.modules.pop(name, None)
+            saved = saved_modules[name]
+            if saved is not _MISSING:
+                sys.modules[name] = saved
+
+
+def test_source_tree_import_uses_canonical_module(
+    async_store_module: ModuleType,
+) -> None:
+    assert Path(async_store_module.__file__).resolve() == CANONICAL_MODULE
+    assert (
+        async_store_module.MooncakeDistributedStoreAsync.__module__
+        == "mooncake.async_store"
+    )
+
+
+def test_async_wrapper_forwards_arguments_and_is_cached(
+    async_store_module: ModuleType,
+) -> None:
+    store = async_store_module.MooncakeDistributedStoreAsync()
+    calling_thread = threading.get_ident()
+
+    async_put = store.async_put
+    assert async_put is store.async_put
+    assert async_put.__name__ == "put"
+    assert asyncio.run(async_put("key", b"value", ttl=7)) == ("key", 7)
+    assert store.calls[0][:3] == ("key", b"value", 7)
+    assert store.calls[0][3] != calling_thread
+
+
+def test_async_wrapper_rejects_invalid_attributes(
+    async_store_module: ModuleType,
+) -> None:
+    store = async_store_module.MooncakeDistributedStoreAsync()
+
+    with pytest.raises(AttributeError, match="has no attribute 'missing'"):
+        getattr(store, "missing")
+    with pytest.raises(AttributeError, match="nor 'missing'"):
+        getattr(store, "async_missing")
+    with pytest.raises(AttributeError, match="'non_callable' is not callable"):
+        getattr(store, "async_non_callable")
diff --git a/mooncake-wheel/tests/test_buffer_pool_native.py b/python/tests/store/test_buffer_pool_native.py
similarity index 98%
rename from mooncake-wheel/tests/test_buffer_pool_native.py
rename to python/tests/store/test_buffer_pool_native.py
index 14067aedc0..0099f5c33b 100644
--- a/mooncake-wheel/tests/test_buffer_pool_native.py
+++ b/python/tests/store/test_buffer_pool_native.py
@@ -98,9 +98,7 @@ def test_buffer_pool_rejects_invalid_alignment() -> None:
 @pytest.mark.parametrize("size", [0, 1, 128 * 1024 + 1])
 def test_buffer_pool_supports_arbitrary_sizes(size: int) -> None:
     store = create_store()
-    pool = BufferPool(
-        store, 1024 * 1024, max_size_class=128 * 1024, alignment=4096
-    )
+    pool = BufferPool(store, 1024 * 1024, max_size_class=128 * 1024, alignment=4096)
 
     lease = pool.acquire(size)
     assert lease.size == size
diff --git a/python/tests/unit/test_cli_modules.py b/python/tests/unit/test_cli_modules.py
new file mode 100644
index 0000000000..b90f4f9dcd
--- /dev/null
+++ b/python/tests/unit/test_cli_modules.py
@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+import stat
+import subprocess
+import sys
+from types import ModuleType, SimpleNamespace
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2] / "mooncake"
+
+
+@pytest.fixture
+def mooncake_pkg(monkeypatch: pytest.MonkeyPatch) -> ModuleType:
+    """Make ``mooncake`` importable as a real package backed by ``python/mooncake``.
+
+    The wrappers do ``from mooncake._launcher import locate``. A stub is injected
+    into ``sys.modules`` so importing ``mooncake`` does not run the real
+    ``python/mooncake/__init__.py`` (which imports ``mooncake.buffer_pool``,
+    absent in the source tree).
+    """
+    pkg = ModuleType("mooncake")
+    pkg.__path__ = [str(PACKAGE_ROOT)]
+    pkg.__package__ = "mooncake"
+    monkeypatch.setitem(sys.modules, "mooncake", pkg)
+    return pkg
+
+
+def _load_module(filename: str) -> ModuleType:
+    module_path = PACKAGE_ROOT / filename
+    spec = importlib.util.spec_from_file_location(
+        f"_mooncake_cli_test_{module_path.stem}", module_path
+    )
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_CLI_CASES = [
+    ("cli.py", "mooncake_master", True),
+    ("cli_client.py", "mooncake_client", True),
+    ("cli_bench.py", "transfer_engine_bench", False),
+]
+
+
+@pytest.mark.parametrize(("filename", "binary_name", "uses_exec"), _CLI_CASES)
+def test_cli_wrappers_forward_arguments_via_launcher(
+    monkeypatch: pytest.MonkeyPatch,
+    mooncake_pkg: ModuleType,
+    filename: str,
+    binary_name: str,
+    uses_exec: bool,
+) -> None:
+    module = _load_module(filename)
+    located = f"/pkg/mooncake/{binary_name}"
+    locate_calls: list[str] = []
+    runner_calls: list[tuple[str, list[str]]] = []
+
+    def fake_locate(name: str) -> str:
+        locate_calls.append(name)
+        return located
+
+    monkeypatch.setattr(module, "locate", fake_locate)
+    monkeypatch.setattr(module.sys, "argv", [filename, "--flag", "value"])
+
+    expected_arguments = [located, "--flag", "value"]
+    if uses_exec:
+        monkeypatch.setattr(
+            module.os, "execv", lambda path, args: runner_calls.append((path, args))
+        )
+        assert module.main() is None
+    else:
+        monkeypatch.setattr(
+            module.subprocess,
+            "call",
+            lambda args: runner_calls.append((args[0], args)) or 17,
+        )
+        assert module.main() == 17
+
+    assert locate_calls == [binary_name]
+    assert runner_calls == [(located, expected_arguments)]
+
+
+def test_launcher_locates_binary_and_sets_exec_bit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    launcher = _load_module("_launcher.py")
+
+    class FakePath:
+        def __init__(self, path: str) -> None:
+            self.path = path
+
+        def __truediv__(self, name: str) -> "FakePath":
+            return FakePath(os.path.join(self.path, name))
+
+        def is_file(self) -> bool:
+            return True
+
+        def __str__(self) -> str:
+            return self.path
+
+        def __fspath__(self) -> str:
+            return self.path
+
+    chmod_calls: list[tuple[str, int]] = []
+    mode = stat.S_IFREG | 0o640
+    monkeypatch.setattr(launcher, "files", lambda package: FakePath("/pkg/mooncake"))
+    monkeypatch.setattr(launcher.os, "access", lambda _path, _mode: False)
+    monkeypatch.setattr(
+        launcher.os, "stat", lambda _path: SimpleNamespace(st_mode=mode)
+    )
+    monkeypatch.setattr(
+        launcher.os, "chmod", lambda path, m: chmod_calls.append((path, m))
+    )
+
+    assert launcher.locate("mooncake_master") == "/pkg/mooncake/mooncake_master"
+    expected_bits = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+    assert chmod_calls == [("/pkg/mooncake/mooncake_master", mode | expected_bits)]
+
+
+def test_launcher_raises_when_binary_is_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    launcher = _load_module("_launcher.py")
+
+    class FakePath:
+        def __truediv__(self, name: str) -> "FakePath":
+            return FakePath()
+
+        def is_file(self) -> bool:
+            return False
+
+    monkeypatch.setattr(launcher, "files", lambda package: FakePath())
+
+    with pytest.raises(FileNotFoundError):
+        launcher.locate("mooncake_master")
+
+
+def test_topology_cli_import_keeps_native_backends_lazy(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delitem(sys.modules, "mooncake.engine", raising=False)
+    monkeypatch.delitem(sys.modules, "tent", raising=False)
+
+    module = _load_module("transfer_engine_topology_dump.py")
+
+    assert module.resolve_backend("te") == "te"
+    assert "mooncake.engine" not in sys.modules
+    assert "tent" not in sys.modules
+
+
+def test_topology_cli_runs_from_the_canonical_source_tree() -> None:
+    result = subprocess.run(
+        [
+            sys.executable,
+            str(PACKAGE_ROOT / "transfer_engine_topology_dump.py"),
+            "--help",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    assert "Dump device topology" in result.stdout
+    assert "--custom-topo-json" in result.stdout
diff --git a/mooncake-wheel/tests/test_mooncake_config.py b/python/tests/unit/test_mooncake_config.py
similarity index 99%
rename from mooncake-wheel/tests/test_mooncake_config.py
rename to python/tests/unit/test_mooncake_config.py
index b160fe03f7..f29e0a3dac 100644
--- a/mooncake-wheel/tests/test_mooncake_config.py
+++ b/python/tests/unit/test_mooncake_config.py
@@ -409,6 +409,7 @@ def test_known_protocols_normalized_to_lowercase(self):
             "  rdma  ": "rdma",
             "cxl": "cxl",
             "ascend": "ascend",
+            "musa": "musa",
             "nvlink_intra": "nvlink_intra",
             "ub": "ub",
             "ubshmem": "ubshmem",
diff --git a/requirements.txt b/requirements.txt
index 11f5e714c9..ecc2ada0ae 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -3,6 +3,9 @@
 # Then enable hooks: pre-commit install
 pre-commit==3.7.1
 ruff==0.6.9
+pyright==1.1.411
+hypothesis==6.141.0
+typing_extensions==4.13.2
 codespell==2.2.6
 cmake-format==0.6.13
 # clang-format is provided via system package (e.g., sudo apt-get install -y clang-format-20) or toolchain
diff --git a/scripts/ascend/dependencies_ascend.sh b/scripts/ascend/dependencies_ascend.sh
index 357b490391..917c746014 100644
--- a/scripts/ascend/dependencies_ascend.sh
+++ b/scripts/ascend/dependencies_ascend.sh
@@ -15,7 +15,7 @@
 
 # If git clone fails, you can place dependencies and Mooncake source code in a directory for compilation and installation.
 
-# ASCEND TRANSPORT is scheduled for deprecation, please use ASCEND DIRECT TRANSPORT on ASCEND platform. 
+# ASCEND TRANSPORT is scheduled for deprecation, please use ASCEND DIRECT TRANSPORT on ASCEND platform.
 # Use dependencies_ascend_installation.sh to install dependencies instead.
 
 #!/bin/bash
@@ -113,19 +113,6 @@ export CPLUS_INCLUDE_PATH=$(echo $CPLUS_INCLUDE_PATH | tr ':' '\n' | grep -v "/u
 cd "$TARGET_DIR"
 pwd
 
-# Install yalantinglibs
-clone_repo_if_not_exists "yalantinglibs" "https://github.com/alibaba/yalantinglibs.git"
-cd yalantinglibs || exit
-git checkout 0.5.5
-rm -rf build
-mkdir -p build && cd build
-cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-make -j$(nproc)
-make install
-cd ../..
-
-echo -e "yalantinglibs installed successfully."
-
 # Install Mooncake
 cd Mooncake || exit
 if ! git submodule update --init --recursive; then
@@ -145,7 +132,7 @@ rm -rf build
 mkdir -p build
 cd build
 cmake -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..
-make -j 
+make -j
 make install -j
 cd ..
 
diff --git a/scripts/ascend/dependencies_ascend_installation.sh b/scripts/ascend/dependencies_ascend_installation.sh
index ff5944bb10..fbeb8d666d 100644
--- a/scripts/ascend/dependencies_ascend_installation.sh
+++ b/scripts/ascend/dependencies_ascend_installation.sh
@@ -133,16 +133,3 @@ check_success "Failed to install system packages"
 echo -e "system packages installed successfully."
 
 export CPLUS_INCLUDE_PATH=$(echo $CPLUS_INCLUDE_PATH | tr ':' '\n' | grep -v "/usr/local/Ascend" | paste -sd: -)
-
-# Install yalantinglibs
-clone_repo_if_not_exists "yalantinglibs" "https://github.com/alibaba/yalantinglibs.git"
-cd yalantinglibs || exit
-git checkout 0.5.5
-rm -rf build
-mkdir -p build && cd build
-cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-make -j$(nproc)
-make install
-cd ../..
-
-echo -e "yalantinglibs installed successfully."
diff --git a/scripts/ascend/dependencies_openeuler.sh b/scripts/ascend/dependencies_openeuler.sh
index e2016395c8..7e31214131 100644
--- a/scripts/ascend/dependencies_openeuler.sh
+++ b/scripts/ascend/dependencies_openeuler.sh
@@ -72,8 +72,7 @@ echo -e "${YELLOW}Mooncake openEuler Dependencies Installer${NC}"
 echo "Repository root: ${REPO_ROOT}"
 echo "This script installs (same scope as root dependencies.sh):"
 echo "  - openEuler/RHEL system packages (dnf/yum)"
-echo "  - Git submodules (pybind11, yalantinglibs, ...)"
-echo "  - yalantinglibs (from extern/ submodule)"
+echo "  - Git submodules (pybind11)"
 echo "  - Go ${GOVER} (for USE_ETCD / libetcd_wrapper.so)"
 echo "Run scripts/ascend/dependencies_ascend_installation.sh afterward for Ascend extras."
 echo
@@ -207,34 +206,6 @@ if [ "$submodule_updated" != true ]; then
 fi
 print_success "Git submodules initialized"
 
-print_section "Installing yalantinglibs from extern/ submodule"
-if [ -d "${REPO_ROOT}/extern/yalantinglibs" ]; then
-    cd "${REPO_ROOT}/extern/yalantinglibs"
-    rm -rf build
-    mkdir -p build && cd build
-    cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-    check_success "Failed to configure yalantinglibs"
-    cmake --build . -j"$(nproc)"
-    check_success "Failed to build yalantinglibs"
-    cmake --install .
-    check_success "Failed to install yalantinglibs"
-    print_success "yalantinglibs installed from submodule"
-    cd "${REPO_ROOT}"
-else
-    print_warn "extern/yalantinglibs missing, building from upstream clone"
-    mkdir -p "${DEPS_BUILD_DIR}"
-    cd "${DEPS_BUILD_DIR}"
-    clone_repo_if_not_exists "yalantinglibs" "https://github.com/alibaba/yalantinglibs.git"
-    cd yalantinglibs
-    git checkout 0.5.5
-    rm -rf build && mkdir -p build && cd build
-    cmake .. -DBUILD_EXAMPLES=OFF -DBUILD_BENCHMARK=OFF -DBUILD_UNIT_TESTS=OFF
-    cmake --build . -j"$(nproc)"
-    cmake --install .
-    cd "${REPO_ROOT}"
-    print_success "yalantinglibs installed from git clone"
-fi
-
 print_section "Verifying essential build tools"
 for tool in getconf ldd patchelf cmake git; do
     command -v "$tool" >/dev/null || print_error "${tool} not found after dependency installation"
@@ -307,4 +278,4 @@ echo "Next steps (example NPU release build):"
 echo "  source /usr/local/Ascend/cann-9.0.0/set_env.sh"
 echo "  mkdir -p build && cd build"
 echo "  cmake .. -DUSE_ASCEND_DIRECT=ON -DUSE_CUDA=OFF -DWITH_EP=OFF -DUSE_HTTP=ON -DUSE_ETCD=ON -DSTORE_USE_ETCD=ON"
-echo "  cmake --build . -j\$(nproc) && cmake --install ."
\ No newline at end of file
+echo "  cmake --build . -j\$(nproc) && cmake --install ."
diff --git a/scripts/bench_engram_store_27b.py b/scripts/bench_engram_store_27b.py
index 7a961ca3e3..fa1d91f7c5 100644
--- a/scripts/bench_engram_store_27b.py
+++ b/scripts/bench_engram_store_27b.py
@@ -24,6 +24,7 @@
 import sys
 import time
 import uuid
+from contextlib import contextmanager
 
 import numpy as np
 
@@ -46,7 +47,7 @@
 NUM_WARMUP = 10
 NUM_ITER = 50
 TABLE_VOCAB_SIZES = [50000] * 8
-EMBEDDING_DIM = 16
+ROW_BYTES = 64
 ALLOW_POPULATE_FALLBACK = (
     os.environ.get("ENGRAM_STORE_ALLOW_POPULATE_FALLBACK", "0") == "1"
 )
@@ -55,7 +56,7 @@
 def create_engram_store_config():
     cfg = store.EngramStoreConfig()
     cfg.table_vocab_sizes = TABLE_VOCAB_SIZES
-    cfg.embedding_dim = EMBEDDING_DIM
+    cfg.row_bytes = ROW_BYTES
     return cfg
 
 
@@ -111,9 +112,7 @@ def populate_store_via_cxl_segment(store_obj, keys, embedding_buffers):
             key = keys[head_idx]
             rc = store_obj.put_from(key, cursor, nbytes)
             if rc != 0:
-                raise RuntimeError(
-                    f"CXL put_from fallback failed for {key}, rc={rc}"
-                )
+                raise RuntimeError(f"CXL put_from fallback failed for {key}, rc={rc}")
             published_keys.append(key)
             cursor += aligned
     except Exception:
@@ -121,17 +120,22 @@ def populate_store_via_cxl_segment(store_obj, keys, embedding_buffers):
         raise
 
 
-def populate_store(engram_store, store_obj):
-    keys = engram_store.get_store_keys()
+def populate_store(engram_store, layer_id, store_obj):
+    keys = engram_store.get_store_keys(layer_id)
     embedding_buffers = []
-    for vocab_size in engram_store.get_table_vocab_sizes():
-        emb = np.random.randn(vocab_size, engram_store.get_embedding_dim()).astype(np.float32)
+    for vocab_size in engram_store.get_table_vocab_sizes(layer_id):
+        emb = np.random.randint(
+            0,
+            256,
+            size=(vocab_size, engram_store.get_row_bytes(layer_id)),
+            dtype=np.uint8,
+        )
         embedding_buffers.append(emb)
 
     t0 = time.perf_counter()
     mode = "engram_store.populate"
     try:
-        engram_store.populate(embedding_buffers)
+        engram_store.populate(layer_id, embedding_buffers)
     except RuntimeError:
         if not ALLOW_POPULATE_FALLBACK:
             raise
@@ -158,32 +162,49 @@ def populate_store(engram_store, store_obj):
     return embedding_buffers, populate_ms, mode
 
 
-def make_row_ids(engram_store, batch_size, seq_len):
+def make_row_ids(engram_store, layer_id, batch_size, seq_len):
     row_ids = []
     for b in range(batch_size):
         batch = []
-        for l in range(seq_len):
+        for pos in range(seq_len):
             token_rows = []
-            for head, vocab_size in enumerate(engram_store.get_table_vocab_sizes()):
-                token_rows.append((b * seq_len + l + head) % vocab_size)
+            for head, vocab_size in enumerate(
+                engram_store.get_table_vocab_sizes(layer_id)
+            ):
+                token_rows.append((b * seq_len + pos + head) % vocab_size)
             batch.append(token_rows)
         row_ids.append(batch)
-    return row_ids
+    return np.asarray(row_ids, dtype=np.int64)
+
 
+@contextmanager
+def registered_output(store_obj, engram_store, layer_id, row_ids):
+    output = np.empty(
+        (*row_ids.shape, engram_store.get_row_bytes(layer_id)), dtype=np.uint8
+    )
+    if store_obj.register_buffer(output.ctypes.data, output.nbytes) != 0:
+        raise RuntimeError("Could not register benchmark output")
+    try:
+        yield output
+    finally:
+        if store_obj.unregister_buffer(output.ctypes.data) != 0:
+            raise RuntimeError("Could not unregister benchmark output")
 
-def run_benchmark(engram_store, batch_size, num_warmup, num_iter):
+
+def run_benchmark(engram_store, layer_id, store_obj, batch_size, num_warmup, num_iter):
     seq_len = 1
-    row_ids = make_row_ids(engram_store, batch_size, seq_len)
+    row_ids = make_row_ids(engram_store, layer_id, batch_size, seq_len)
 
-    for _ in range(num_warmup):
-        engram_store.lookup(row_ids)
+    with registered_output(store_obj, engram_store, layer_id, row_ids) as output:
+        for _ in range(num_warmup):
+            engram_store.lookup_into(layer_id, row_ids, output)
 
-    total_ms_list = []
-    for _ in range(num_iter):
-        t0 = time.perf_counter()
-        engram_store.lookup(row_ids)
-        t1 = time.perf_counter()
-        total_ms_list.append((t1 - t0) * 1000)
+        total_ms_list = []
+        for _ in range(num_iter):
+            t0 = time.perf_counter()
+            engram_store.lookup_into(layer_id, row_ids, output)
+            t1 = time.perf_counter()
+            total_ms_list.append((t1 - t0) * 1000)
 
     total_ms = np.array(total_ms_list)
     mean_total = np.mean(total_ms)
@@ -194,9 +215,8 @@ def run_benchmark(engram_store, batch_size, num_warmup, num_iter):
     bytes_per_request = (
         batch_size
         * seq_len
-        * engram_store.get_num_heads()
-        * engram_store.get_embedding_dim()
-        * 4
+        * engram_store.get_num_heads(layer_id)
+        * engram_store.get_row_bytes(layer_id)
     )
     gbps = (bytes_per_request / 1e9) / (mean_total / 1000)
 
@@ -210,9 +230,10 @@ def run_benchmark(engram_store, batch_size, num_warmup, num_iter):
     }
 
 
-def validate_lookup_correctness(engram_store, embedding_buffers):
-    row_ids = make_row_ids(engram_store, batch_size=1, seq_len=1)
-    output = np.asarray(engram_store.lookup(row_ids))
+def validate_lookup_correctness(engram_store, layer_id, store_obj, embedding_buffers):
+    row_ids = make_row_ids(engram_store, layer_id, batch_size=1, seq_len=1)
+    with registered_output(store_obj, engram_store, layer_id, row_ids) as output:
+        engram_store.lookup_into(layer_id, row_ids, output)
 
     max_abs_err = 0.0
     for head_idx in range(output.shape[2]):
@@ -251,11 +272,15 @@ def main():
     try:
         cfg = create_engram_store_config()
         layer_id = uuid.uuid4().int & 0x7FFFFFFF
-        engram_store = store.EngramStore(layer_id=layer_id, config=cfg, store=store_obj)
-        embedding_buffers, populate_ms, mode = populate_store(engram_store, store_obj)
+        engram_store = store.EngramStore({layer_id: cfg}, store_obj)
+        embedding_buffers, populate_ms, mode = populate_store(
+            engram_store, layer_id, store_obj
+        )
         print(f"Populate mode: {mode}, took {populate_ms:.2f} ms")
 
-        max_abs_err = validate_lookup_correctness(engram_store, embedding_buffers)
+        max_abs_err = validate_lookup_correctness(
+            engram_store, layer_id, store_obj, embedding_buffers
+        )
         print(f"Max abs error: {max_abs_err:.6f}")
 
         print("\nResults:")
@@ -263,7 +288,9 @@ def main():
             f"{'Batch':>8} {'Mean(ms)':>10} {'P50(ms)':>10} {'P99(ms)':>10} {'Tok/s':>12} {'GB/s':>10}"
         )
         for batch_size in BATCH_SIZES:
-            result = run_benchmark(engram_store, batch_size, NUM_WARMUP, NUM_ITER)
+            result = run_benchmark(
+                engram_store, layer_id, store_obj, batch_size, NUM_WARMUP, NUM_ITER
+            )
             print(
                 f"{result['batch_size']:>8} {result['mean_total_ms']:>10.3f} {result['p50_ms']:>10.3f} "
                 f"{result['p99_ms']:>10.3f} {result['tokens_per_sec']:>12.1f} {result['gbps']:>10.3f}"
@@ -271,7 +298,7 @@ def main():
     finally:
         if engram_store is not None:
             try:
-                engram_store.remove_from_store(force=True)
+                engram_store.remove_from_store(layer_id, force=True)
             except Exception as exc:
                 print(f"Warning: failed to clean up benchmark layer: {exc}")
         store_obj.close()
diff --git a/scripts/build_wheel.sh b/scripts/build_wheel.sh
index bfbcc3c3b1..1f6e46866a 100755
--- a/scripts/build_wheel.sh
+++ b/scripts/build_wheel.sh
@@ -10,14 +10,15 @@ set -x
 PYTHON_VERSION=${PYTHON_VERSION:-${1:-$(python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")}}
 # Get output directory from environment variable or argument
 OUTPUT_DIR=${OUTPUT_DIR:-${2:-"dist"}}
-# CMake build directory (default: build).  EP/PG extensions are staged under
-# ${BUILD_DIR}/ep_pg_staging when the project was built with -DWITH_EP=ON.
+# CMake build directory (default: build).  EP/PG device extensions are staged
+# under ${BUILD_DIR}/ep_pg_staging. Host extensions are copied directly from
+# their normal CMake output paths before auditwheel, like the PG core library.
 BUILD_DIR="${BUILD_DIR:-build}"
 BUILD_DIR_ABS="$(pwd)/${BUILD_DIR}"
 echo "Building wheel for Python ${PYTHON_VERSION} with output directory ${OUTPUT_DIR}"
 
 # Ensure LD_LIBRARY_PATH includes /usr/local/lib
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${BUILD_DIR_ABS}/mooncake-common:${BUILD_DIR_ABS}/mooncake-common/etcd:${BUILD_DIR_ABS}/mooncake-common/k8s-lease:/usr/local/lib
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${BUILD_DIR_ABS}/mooncake-common:${BUILD_DIR_ABS}/mooncake-common/etcd:${BUILD_DIR_ABS}/mooncake-common/k8s-lease:${BUILD_DIR_ABS}/ep_pg_staging:/usr/local/lib
 
 echo "Cleaning wheel-build directory"
 rm -rf mooncake-wheel/mooncake_transfer_engine*
@@ -38,6 +39,18 @@ if [ -f "${BUILD_DIR}/mooncake-pg/src/libmooncake_pg.so" ]; then
     cp "${BUILD_DIR}/mooncake-pg/src/libmooncake_pg.so" mooncake-wheel/mooncake/libmooncake_pg.so
 fi
 
+# Copy the native EP host binding to mooncake directory before auditwheel.
+# CUDA EP device libraries remain in the shared EP/PG staging directory and
+# are injected after auditwheel, matching the existing PG packaging flow.
+EP_HOST_SO=$(compgen -G "${BUILD_DIR}/mooncake-ep/src/_ep.*.so" | head -1 || true)
+if [ -n "$EP_HOST_SO" ]; then
+    echo "Copying native EP host extension..."
+    cp "$EP_HOST_SO" mooncake-wheel/mooncake/
+fi
+
+# Copy the shared segment wrapper, which builds on engine.so
+cp mooncake-integration/shared_segment.py mooncake-wheel/mooncake/shared_segment.py
+
 # Copy libasio.so to mooncake directory (runtime dependency of engine.so)
 cp ${BUILD_DIR}/mooncake-common/libasio.so mooncake-wheel/mooncake/libasio.so
 
@@ -50,8 +63,8 @@ if compgen -G "${BUILD_DIR}/mooncake-integration/store.*.so" >/dev/null; then
     cp ${BUILD_DIR}/mooncake-store/src/mooncake_master mooncake-wheel/mooncake/
     # Copy client binary
     cp ${BUILD_DIR}/mooncake-store/src/mooncake_client mooncake-wheel/mooncake/
-    # Copy async_store.py
-    cp mooncake-integration/store/async_store.py mooncake-wheel/mooncake/async_store.py
+    # Stage the canonical async Store client for the legacy wheel builder.
+    cp python/mooncake/async_store.py mooncake-wheel/mooncake/async_store.py
 else
     echo "Skipping store.so (not built - likely WITH_STORE is set to OFF)"
 fi
@@ -129,10 +142,10 @@ else
     echo "Skipping libascend_transport_mem.so (not built - Ascend disabled)"
 fi
 
-# EP/PG CUDA extensions are built during the cmake/make process when the
-# project is configured with -DWITH_EP=ON.  The resulting .so files land in
-# ${BUILD_DIR}/ep_pg_staging and are injected into the wheel AFTER auditwheel
-# so that patchelf never touches CUDA fatbins (see injection step below).
+# EP/PG extensions are built during the cmake/make process when the project is
+# configured with -DWITH_EP=ON. Host extensions are repaired by auditwheel;
+# CUDA device libraries and PG extensions remain in the post-repair staging
+# directory so patchelf never touches CUDA fatbins.
 # Use an absolute path: the script later `cd`s into mooncake-wheel/ and a
 # relative path would silently point to the wrong location.
 CUDA_EP_STAGING_DIR="${BUILD_DIR_ABS}/ep_pg_staging"
@@ -155,6 +168,10 @@ if [ "$CI" = "true" ] || [ "$FREE_BUILD_DIR" = "1" ]; then
     fi
 fi
 
+# Make the post-repair device library discoverable while auditwheel resolves
+# the host extension.  It is explicitly excluded below and injected later.
+export LD_LIBRARY_PATH="${CUDA_EP_STAGING_DIR}:${LD_LIBRARY_PATH}"
+
 if [ "$NPU_BUILD" = "1" ]; then
     echo "Stripping shared libraries to reduce wheel size..."
     find mooncake-wheel/mooncake -name "*.so" -exec strip --strip-unneeded {} \;
@@ -163,6 +180,42 @@ if [ "$NPU_BUILD" = "1" ]; then
 fi
 
 echo "Building wheel package..."
+# Stage migrated root Python modules and the legacy Reshard package for the
+# combined-wheel builder. Each tracked source remains in its authoritative tree.
+MIGRATED_PYTHON_SOURCE_DIR="python/mooncake"
+MIGRATED_PYTHON_STAGING_DIR="$(pwd)/mooncake-wheel/mooncake"
+MIGRATED_PYTHON_MODULES=(
+    _launcher.py
+    cli.py
+    cli_bench.py
+    cli_client.py
+    transfer_engine_topology_dump.py
+    buffer_pool.py
+    mooncake_config.py
+    ep.py
+    mooncake_ep_buffer.py
+    mooncake_elastic_buffer.py
+    _administration.py
+    mooncake_ssd_register.py
+    mooncake_ssd_unregister.py
+    spdk_tgt_create.py
+)
+RESHARD_SOURCE_DIR="mooncake-reshard/python/mooncake/reshard"
+RESHARD_STAGING_DIR="$(pwd)/mooncake-wheel/mooncake/reshard"
+cleanup_migrated_python_staging() {
+    for module in "${MIGRATED_PYTHON_MODULES[@]}"; do
+        rm -f "${MIGRATED_PYTHON_STAGING_DIR}/${module}"
+    done
+    rm -rf "${RESHARD_STAGING_DIR}"
+}
+trap cleanup_migrated_python_staging EXIT
+cleanup_migrated_python_staging
+for module in "${MIGRATED_PYTHON_MODULES[@]}"; do
+    cp "${MIGRATED_PYTHON_SOURCE_DIR}/${module}" \
+       "${MIGRATED_PYTHON_STAGING_DIR}/${module}"
+done
+cp -R "${RESHARD_SOURCE_DIR}" "${RESHARD_STAGING_DIR}"
+
 # Build the wheel package
 cd mooncake-wheel
 
@@ -176,6 +229,7 @@ WHEEL_DIR="$(pwd)"
 cleanup_wheel_metadata_state() {
     [[ -f "${WHEEL_DIR}/pyproject.toml.backup" ]] && mv "${WHEEL_DIR}/pyproject.toml.backup" "${WHEEL_DIR}/pyproject.toml"
     rm -f "${WHEEL_DIR}/README.md"
+    cleanup_migrated_python_staging
 }
 trap cleanup_wheel_metadata_state EXIT
 
@@ -291,6 +345,11 @@ rm -rf ${OUTPUT_DIR}/
 mkdir -p ${OUTPUT_DIR}
 
 echo "Installing required build packages"
+# patchelf is installed from PyPI alongside auditwheel: auditwheel >= 6.8
+# requires patchelf >= 0.14.5, but the distro package on Ubuntu 22.04 (and the
+# rocm/musa CI images built on it) is 0.14.3, which makes `auditwheel repair`
+# abort. The PyPI wheel lands ahead of /usr/bin on PATH and works everywhere
+# the Python toolchain does.
 if [ "$NPU_BUILD" = "1" ]; then
     PYTHON_CMD="python${PYTHON_VERSION}"
     if ! command -v "$PYTHON_CMD" &>/dev/null; then
@@ -300,7 +359,7 @@ if [ "$NPU_BUILD" = "1" ]; then
     max_attempts=3
     attempt=1
     while [ $attempt -le $max_attempts ]; do
-        if "$PYTHON_CMD" -m pip install --upgrade pip build setuptools wheel auditwheel numpy; then
+        if "$PYTHON_CMD" -m pip install --upgrade pip build setuptools wheel auditwheel patchelf numpy; then
             break
         fi
         echo "pip install attempt $attempt/$max_attempts failed, retrying in 5s..."
@@ -312,10 +371,10 @@ if [ "$NPU_BUILD" = "1" ]; then
         exit 1
     fi
 elif command -v pip &>/dev/null; then
-    python${PYTHON_VERSION} -m pip install --upgrade pip build setuptools wheel auditwheel
+    python${PYTHON_VERSION} -m pip install --upgrade pip build setuptools wheel auditwheel patchelf
 elif command -v uv &>/dev/null; then
     uv pip install --upgrade pip
-    uv pip install build setuptools wheel auditwheel
+    uv pip install build setuptools wheel auditwheel patchelf
 else
     echo "Error: Neither python${PYTHON_VERSION}, pip nor uv found"
     exit 1
@@ -388,6 +447,19 @@ else
     AUDITWHEEL_CMD="auditwheel"
 fi
 
+# Bundle OpenSSL when required: the OSS adapter links libcrypto directly, and
+# target systems may not provide the OpenSSL ABI used by the wheel builder.
+# Keep libssl eligible too, so auditwheel can repair its libcrypto dependency.
+#
+# `--exclude libmpcomm.so*` below is deliberate, not an oversight. MPComm ships
+# its own wheel / CMake install and is upgraded independently of Mooncake, so
+# engine.so keeps its DT_NEEDED on libmpcomm.so.<N> and the dynamic linker
+# resolves it at run time (e.g. LD_LIBRARY_PATH=$MPCOMM_ROOT/lib). Vendoring it
+# would: (a) freeze one MPComm build inside the wheel, where the RPATH injected
+# by auditwheel outranks LD_LIBRARY_PATH and would silently shadow any newer
+# libmpcomm.so; and (b) let patchelf rewrite a library carrying CUDA fatbins
+# (MPComm builds TMA kernels with USE_CUDA_KERNELS=ON by default), the same
+# corruption risk the EP/PG extensions are kept away from below.
 ${AUDITWHEEL_CMD} repair ${OUTPUT_DIR}/*.whl \
     --exclude libcurl.so* \
     --exclude libfabric.so* \
@@ -403,8 +475,6 @@ ${AUDITWHEEL_CMD} repair ${OUTPUT_DIR}/*.whl \
     --exclude librtmp.so* \
     --exclude libssh.so* \
     --exclude libpsl.so* \
-    --exclude libssl.so* \
-    --exclude libcrypto.so* \
     --exclude libgssapi_krb5.so* \
     --exclude libldap.so* \
     --exclude liblber.so* \
@@ -432,7 +502,9 @@ ${AUDITWHEEL_CMD} repair ${OUTPUT_DIR}/*.whl \
     --exclude libffi.so* \
     --exclude libcuda.so* \
     --exclude libcudart.so* \
+    --exclude libmooncake_ep_device.so* \
     --exclude libmooncake_pg_device.so* \
+    --exclude libnccl.so* \
     --exclude libmusa.so* \
     --exclude libmusart.so* \
     --exclude libamdhip64.so* \
@@ -479,6 +551,7 @@ ${AUDITWHEEL_CMD} repair ${OUTPUT_DIR}/*.whl \
     --exclude ascend_transport*.so \
     --exclude libaccl_barex.so* \
     --exclude liburma.so* \
+    --exclude libmpcomm.so* \
     -w ${REPAIRED_DIR}/ --plat ${PLATFORM_TAG}
 
 # Inject CUDA extensions into the repaired wheel.  patchelf (used by auditwheel)
@@ -497,6 +570,15 @@ if [ -d "$CUDA_EP_STAGING_DIR" ] && ls "$CUDA_EP_STAGING_DIR"/*.so &>/dev/null;
                 cp "$so_file" "$UNPACKED_PKG_DIR/mooncake/$(basename "$so_file")"
             fi
         done
+        # The host EP extension is repaired before the device library is
+        # injected.  auditwheel therefore only adds its vendored .libs path;
+        # add the package directory as well so the sibling device library is
+        # found at runtime.
+        for ep_host_so in "$UNPACKED_PKG_DIR"/mooncake/_ep*.so; do
+            if [ -f "$ep_host_so" ]; then
+                patchelf --add-rpath '$ORIGIN' "$ep_host_so"
+            fi
+        done
         rm "$REPAIRED_WHEEL"
         python${PYTHON_VERSION} -m wheel pack "$UNPACKED_PKG_DIR" -d "${REPAIRED_DIR}/"
         rm -rf "$WHEEL_UNPACK_DIR"
@@ -509,7 +591,6 @@ fi
 if [ -n "$CUDA_EP_STAGING_TEMP" ]; then
     rm -rf "$CUDA_EP_STAGING_TEMP"
 fi
-
 # NPU only: move auditwheel-vendored .libs into mooncake/ and set RPATH=$ORIGIN
 # on all ELF files so everything resolves from a single directory.
 if [ "$NPU_BUILD" = "1" ]; then
diff --git a/scripts/check_reshard_types.sh b/scripts/check_reshard_types.sh
new file mode 100755
index 0000000000..903fa1c18e
--- /dev/null
+++ b/scripts/check_reshard_types.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Validate the canonical reshard contracts and their required negative examples.
+set -euo pipefail
+
+pyright --project mooncake-reshard/pyrightconfig.json
+
+if negative_output=$(pyright --project mooncake-reshard/typecheck/negative/pyrightconfig.json 2>&1); then
+    echo "Expected invalid reshard contract examples to fail static checking."
+    exit 1
+fi
+
+printf '%s\n' "${negative_output}"
+printf '%s\n' "${negative_output}" | grep -F "ParticipantId" >/dev/null
+printf '%s\n' "${negative_output}" | grep -F "SplitAxisKind" >/dev/null
diff --git a/scripts/ci/run_rpc_smoke.sh b/scripts/ci/run_rpc_smoke.sh
new file mode 100755
index 0000000000..15a4ff11e8
--- /dev/null
+++ b/scripts/ci/run_rpc_smoke.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+: "${RUNNER_TEMP:=${TMPDIR:-/tmp}}"
+source scripts/ci/services.sh
+
+trap 'ci_cleanup_services "$?"' EXIT
+
+ci_start_service rpc "$RUNNER_TEMP/rpc-server.log" \
+  python -u mooncake-transfer-engine/tests/rpc_communicator_test.py \
+  server --url 127.0.0.1:9004 --data-size 1
+ci_wait_service rpc 9004
+
+client_rc=0
+timeout 10 python -u \
+  mooncake-transfer-engine/tests/rpc_communicator_test.py \
+  client --url 127.0.0.1:9004 --threads 2 --data-size 1 \
+  >"$RUNNER_TEMP/rpc-client.log" 2>&1 || \
+  client_rc=$?
+cat "$RUNNER_TEMP/rpc-client.log"
+if [ "$client_rc" -ne 0 ] && [ "$client_rc" -ne 124 ]; then
+  echo "::error::RPC communicator client failed with exit code $client_rc"
+  exit "$client_rc"
+fi
+if ! grep -q '^bandwidth:' "$RUNNER_TEMP/rpc-client.log"; then
+  echo "::error::RPC communicator did not complete a successful transfer"
+  exit 1
+fi
diff --git a/scripts/ci/run_ssd_offload_smoke.sh b/scripts/ci/run_ssd_offload_smoke.sh
new file mode 100755
index 0000000000..3a362dfc6d
--- /dev/null
+++ b/scripts/ci/run_ssd_offload_smoke.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+: "${RUNNER_TEMP:=${TMPDIR:-/tmp}}"
+source scripts/ci/services.sh
+
+export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-}:/usr/local/lib
+
+cleanup() {
+  local status=$?
+  ci_cleanup_services "$status" || true
+  rm -rf /tmp/mooncake_ci_ssd_offload /tmp/mooncake_ci_promotion
+  exit "$status"
+}
+trap cleanup EXIT
+
+ci_start_service metadata "$RUNNER_TEMP/mooncake-metadata.log" \
+  mooncake_http_metadata_server --port 8080
+ci_wait_service metadata 8080
+
+mkdir -p /tmp/mooncake_ci_ssd_offload
+ci_start_service ssd "$RUNNER_TEMP/mooncake-ssd-master.log" mooncake_master \
+  --default_kv_lease_ttl=500 \
+  --root_fs_dir=/tmp/mooncake_ci_ssd_offload
+ci_wait_service ssd 50051
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
+  DEFAULT_KV_LEASE_TTL=500 \
+  python mooncake-wheel/tests/test_ssd_offload_in_evict.py
+ci_stop_service ssd
+
+mkdir -p /tmp/mooncake_ci_promotion
+ci_start_service promotion "$RUNNER_TEMP/mooncake-promotion-master.log" mooncake_master \
+  --default_kv_lease_ttl=500 \
+  --root_fs_dir=/tmp/mooncake_ci_promotion \
+  --enable_offload=true \
+  --offload_on_evict=true \
+  --promotion_on_hit=true \
+  --promotion_admission_threshold=1 \
+  --promotion_max_per_heartbeat=16
+ci_wait_service promotion 50051
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
+  DEFAULT_KV_LEASE_TTL=500 \
+  MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=/tmp/mooncake_ci_promotion \
+  MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS=2 \
+  MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT=10 \
+  MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES=10485760 \
+  python mooncake-wheel/tests/test_promotion_on_hit.py
+ci_stop_service promotion
diff --git a/scripts/ci/run_store_api_smoke.sh b/scripts/ci/run_store_api_smoke.sh
new file mode 100755
index 0000000000..ee1deac4f2
--- /dev/null
+++ b/scripts/ci/run_store_api_smoke.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+: "${RUNNER_TEMP:=${TMPDIR:-/tmp}}"
+source scripts/ci/services.sh
+
+trap 'ci_cleanup_services "$?"' EXIT
+
+mkdir -p /tmp/mooncake_storage
+ci_start_service master "$RUNNER_TEMP/mooncake-master.log" mooncake_master \
+  --default_kv_lease_ttl=500 \
+  --eviction_high_watermark_ratio=0.95 \
+  --cluster_id=ci_store_api_smoke \
+  --port 50051 \
+  --enable_http_metadata_server=true
+ci_wait_service master 50051 8080
+
+python scripts/test_upsert_api.py
+python -m unittest mooncake-wheel.tests.test_weight_snapshot_api
+python python/tests/store/async_store_integration.py
+python scripts/test_copy_move_api.py
+python -m unittest mooncake-wheel.tests.test_safetensor_functions
+python scripts/test_drain_http_api.py --timeout-sec 90
+
+# Exercise the serialized-object and external read paths through Dummy RPC.
+ci_start_service dummy-client "$RUNNER_TEMP/mooncake-dummy-client.log" \
+  mooncake_client --host=127.0.0.1 --global_segment_size="128 MB" \
+  --local_buffer_size="64 MB"
+ci_wait_service dummy-client 50052
+DEFAULT_KV_LEASE_TTL=500 python -m unittest discover \
+  -s mooncake-wheel/tests -p test_dummy_client.py \
+  -k tensor_from -k test_external_host -v
diff --git a/scripts/ci/run_store_go_integration.sh b/scripts/ci/run_store_go_integration.sh
index 482f93cf6c..71f9580d77 100755
--- a/scripts/ci/run_store_go_integration.sh
+++ b/scripts/ci/run_store_go_integration.sh
@@ -2,6 +2,11 @@
 
 set -e -o pipefail
 
+# shellcheck source=scripts/ci/services.sh
+source "$(dirname "${BASH_SOURCE[0]}")/services.sh"
+: "${RUNNER_TEMP:=${TMPDIR:-/tmp}}"
+trap 'ci_cleanup_services "$?"' EXIT
+
 : "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE must be set}"
 : "${MOONCAKE_STORE_CLUSTER_ID:?MOONCAKE_STORE_CLUSTER_ID must be set}"
 
@@ -14,50 +19,41 @@ case "${MOONCAKE_STORE_GO_SANITIZED:-0}" in
         ;;
 esac
 
-case "${MOONCAKE_STORE_GO_LINK_COMMON:-0}" in
-    0) link_common=false ;;
-    1) link_common=true ;;
-    *)
-        echo "MOONCAKE_STORE_GO_LINK_COMMON must be 0 or 1" >&2
-        exit 2
-        ;;
-esac
-
-"$GITHUB_WORKSPACE/build/mooncake-store/src/mooncake_master" \
+# The Go test client publishes rpc_meta over HTTP to the master's embedded
+# metadata server (see integration_test.go's run instructions). Older runs
+# got 8080 served by an unrelated shared master that no longer exists in this
+# job, so this master must serve metadata itself.
+ci_start_service master "$RUNNER_TEMP/mooncake-master.log" \
+    "$GITHUB_WORKSPACE/build/mooncake-store/src/mooncake_master" \
     --eviction_high_watermark_ratio=0.95 \
     --cluster_id="$MOONCAKE_STORE_CLUSTER_ID" \
-    --port 50051 &
-master_pid=$!
-sleep 3
+    --port 50051 \
+    --enable_http_metadata_server=true
+ci_wait_service master 50051
 
 cd "$GITHUB_WORKSPACE/mooncake-store/go"
-export LD_LIBRARY_PATH="$GITHUB_WORKSPACE/build/mooncake-common:$GITHUB_WORKSPACE/build/mooncake-store/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base:$GITHUB_WORKSPACE/build/mooncake-common/etcd"
+export LD_LIBRARY_PATH="$GITHUB_WORKSPACE/build/mooncake-common:$GITHUB_WORKSPACE/build/mooncake-store/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base:$GITHUB_WORKSPACE/build/mooncake-common/etcd:${LD_LIBRARY_PATH:-}"
 export CGO_ENABLED=1
 export CGO_CFLAGS="-I$GITHUB_WORKSPACE/mooncake-store/include -I$GITHUB_WORKSPACE/mooncake-transfer-engine/include"
 
+# master_service.cpp (inside libmooncake_store.a) calls into LocalSsdManager,
+# which lives in its own static archive under local_ssd/. It is built
+# unconditionally and is a required dependency of mooncake_store, so link it
+# inside the group where cyclic references resolve.
 linker_flags=(
     "-L$GITHUB_WORKSPACE/build/mooncake-store/src"
     "-L$GITHUB_WORKSPACE/build/mooncake-store/src/cachelib_memory_allocator"
+    "-L$GITHUB_WORKSPACE/build/mooncake-store/src/local_ssd"
     "-L$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src"
     "-L$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base"
     "-L$GITHUB_WORKSPACE/build/mooncake-common"
+    "-L$GITHUB_WORKSPACE/build/mooncake-common/src"
+    "-L$GITHUB_WORKSPACE/build/mooncake-common/etcd"
+    -Wl,--start-group
+    -lmooncake_store -lmooncake_local_ssd -lcachelib_memory_allocator -ltransfer_engine -lbase
+    -lmooncake_common
+    -Wl,--end-group
 )
-if $link_common; then
-    linker_flags+=("-L$GITHUB_WORKSPACE/build/mooncake-common/src")
-fi
-linker_flags+=("-L$GITHUB_WORKSPACE/build/mooncake-common/etcd")
-if $link_common; then
-    linker_flags+=(
-        -Wl,--start-group
-        -lmooncake_store -lcachelib_memory_allocator -ltransfer_engine -lbase
-        -lmooncake_common
-        -Wl,--end-group
-    )
-else
-    linker_flags+=(
-        -lmooncake_store -lcachelib_memory_allocator -ltransfer_engine -lbase
-    )
-fi
 linker_flags+=(
     -lasio -letcd_wrapper -lstdc++ -lnuma -lglog -lgflags -libverbs -lmlx5
     -ljsoncpp -lzstd -lcurl -luring
@@ -72,10 +68,29 @@ fi
 linker_flags+=(-lxxhash -lyaml-cpp)
 export CGO_LDFLAGS="${linker_flags[*]}"
 
+# OSS adapter request signing uses OpenSSL HMAC (EVP_sha256). Static archives
+# carry no transitive deps, so the Go link needs libcrypto explicitly when the
+# adapter was compiled in (CURL + OpenSSL found at CMake time).
+if grep -q '^MOONCAKE_OSS_ADAPTER_ENABLED:INTERNAL=TRUE$' "$GITHUB_WORKSPACE/build/CMakeCache.txt"; then
+    export CGO_LDFLAGS="$CGO_LDFLAGS -lcrypto"
+fi
+
 # Link cudart if CUDA is available (needed for D2H staging in mooncake_store).
 if [ -d /usr/local/cuda/lib64 ]; then
     export CGO_LDFLAGS="$CGO_LDFLAGS -L/usr/local/cuda/lib64 -lcudart"
 fi
+# USE_CUDA links transfer_engine against the CUDA Driver API in addition to the
+# runtime API. Reuse the exact driver library that CMake selected.
+if grep -q '^USE_CUDA:BOOL=ON$' "$GITHUB_WORKSPACE/build/CMakeCache.txt"; then
+    cuda_driver_library=$(sed -n \
+        's/^CUDA_cuda_driver_LIBRARY:FILEPATH=//p' \
+        "$GITHUB_WORKSPACE/build/CMakeCache.txt")
+    if [ -z "$cuda_driver_library" ] || [ ! -f "$cuda_driver_library" ]; then
+        echo "CMake did not resolve the CUDA driver library" >&2
+        exit 1
+    fi
+    export CGO_LDFLAGS="$CGO_LDFLAGS -L$(dirname "$cuda_driver_library") -lcuda"
+fi
 # The KV events publisher is optional and linked when libzmq is installed.
 if ldconfig -p 2>/dev/null | grep -q libzmq; then
     export CGO_LDFLAGS="$CGO_LDFLAGS -lzmq"
@@ -86,5 +101,3 @@ if $sanitized; then
     test_env=(ASAN_OPTIONS=detect_leaks=0:verify_asan_link_order=0 "${test_env[@]}")
 fi
 env "${test_env[@]}" go test -v ./tests/...
-
-kill "$master_pid" 2>/dev/null || true
diff --git a/scripts/ci/run_store_rust_smoke.sh b/scripts/ci/run_store_rust_smoke.sh
index a2de303818..33f6cfab45 100755
--- a/scripts/ci/run_store_rust_smoke.sh
+++ b/scripts/ci/run_store_rust_smoke.sh
@@ -2,6 +2,11 @@
 
 set -e -o pipefail
 
+# shellcheck source=scripts/ci/services.sh
+source "$(dirname "${BASH_SOURCE[0]}")/services.sh"
+: "${RUNNER_TEMP:=${TMPDIR:-/tmp}}"
+trap 'ci_cleanup_services "$?"' EXIT
+
 : "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE must be set}"
 : "${MOONCAKE_STORE_CLUSTER_ID:?MOONCAKE_STORE_CLUSTER_ID must be set}"
 
@@ -16,12 +21,12 @@ case "${MOONCAKE_STORE_RUST_LINK_ASAN:-0}" in
         ;;
 esac
 
-"$GITHUB_WORKSPACE/build/mooncake-store/src/mooncake_master" \
+ci_start_service master "$RUNNER_TEMP/mooncake-master.log" \
+    "$GITHUB_WORKSPACE/build/mooncake-store/src/mooncake_master" \
     --eviction_high_watermark_ratio=0.95 \
     --cluster_id="$MOONCAKE_STORE_CLUSTER_ID" \
-    --port 50051 &
-master_pid=$!
-sleep 3
+    --port 50051
+ci_wait_service master 50051
 
 cd "$GITHUB_WORKSPACE/mooncake-store/rust"
 export LD_LIBRARY_PATH="$GITHUB_WORKSPACE/build/mooncake-asio:$GITHUB_WORKSPACE/build/mooncake-store/src:$GITHUB_WORKSPACE/build/mooncake-store/src/cachelib_memory_allocator:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src:$GITHUB_WORKSPACE/build/mooncake-transfer-engine/src/common/base:$GITHUB_WORKSPACE/build/mooncake-common/etcd:${LD_LIBRARY_PATH:-}"
@@ -40,5 +45,3 @@ MC_RUST_BENCH_ITERATIONS=4 \
     MC_RUST_BENCH_VALUE_SIZE=4096 \
     MC_RUST_BENCH_WARMUP=1 \
     cargo run --release --example store_benchmark
-
-kill "$master_pid" 2>/dev/null || true
diff --git a/scripts/ci/run_transfer_engine_rust_smoke.sh b/scripts/ci/run_transfer_engine_rust_smoke.sh
new file mode 100755
index 0000000000..701bd6630d
--- /dev/null
+++ b/scripts/ci/run_transfer_engine_rust_smoke.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail
+
+: "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE must be set}"
+
+# ASan-enabled CI libraries require the Rust package to link libasan first.
+# Release-style nightly builds intentionally leave the ASan runtime unlinked.
+case "${MOONCAKE_TE_RUST_LINK_ASAN:-0}" in
+    0) unset MOONCAKE_LINK_ASAN ;;
+    1) export MOONCAKE_LINK_ASAN=1 ;;
+    *)
+        echo "MOONCAKE_TE_RUST_LINK_ASAN must be 0 or 1" >&2
+        exit 2
+        ;;
+esac
+
+cd "$GITHUB_WORKSPACE/mooncake-transfer-engine/rust"
+
+# Allow CI jobs that build the project into a non-default directory (e.g.
+# tent-ci's build-tent) to point at the right libraries.
+: "${MOONCAKE_BUILD_DIR:=$GITHUB_WORKSPACE/build}"
+export MOONCAKE_BUILD_DIR
+export LD_LIBRARY_PATH="$MOONCAKE_BUILD_DIR/mooncake-asio:$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src:$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src/common/base:$MOONCAKE_BUILD_DIR/mooncake-common:$MOONCAKE_BUILD_DIR/mooncake-common/etcd:${LD_LIBRARY_PATH:-}"
+if [ -d "$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/tent/src" ]; then
+    export LD_LIBRARY_PATH="$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/tent/src:${LD_LIBRARY_PATH}"
+fi
+if [ -d /usr/local/cuda/lib64/stubs ]; then
+    export LD_LIBRARY_PATH="/usr/local/cuda/lib64/stubs:${LD_LIBRARY_PATH}"
+fi
+if [ -d /usr/local/cuda/lib64 ]; then
+    export LD_LIBRARY_PATH="/usr/local/cuda/lib64:${LD_LIBRARY_PATH}"
+fi
+
+export MOONCAKE_TE_LIB_DIR="$MOONCAKE_BUILD_DIR/mooncake-transfer-engine/src"
+export MOONCAKE_TE_INCLUDE_DIR="$GITHUB_WORKSPACE/mooncake-transfer-engine/include"
+export MC_METADATA_SERVER="${MC_METADATA_SERVER:-http://127.0.0.1:8080/metadata}"
+export MC_RUST_TE_RUN_INTEGRATION=1
+export MC_RUST_TE_PROTOCOL="${MC_RUST_TE_PROTOCOL:-tcp}"
+export MC_RUST_TE_LOCAL_HOSTNAME="${MC_RUST_TE_LOCAL_HOSTNAME:-127.0.0.1:$((20000 + $$ % 10000))}"
+
+cargo test --lib
+cargo test --test minimal_smoke -- --nocapture
+cargo test --examples --tests --no-run
diff --git a/scripts/ci/services.sh b/scripts/ci/services.sh
new file mode 100644
index 0000000000..12e6a20c64
--- /dev/null
+++ b/scripts/ci/services.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+
+# Source from a suite and install `trap 'ci_cleanup_services "$?"' EXIT`.
+# Commands must stay in the foreground so their PID remains owned by the suite.
+declare -A CI_SERVICE_PIDS=()
+declare -A CI_SERVICE_LOGS=()
+declare -a CI_SERVICE_ORDER=()
+
+ci_start_service() {
+  local name=$1 log=$2
+  shift 2
+  "$@" >"$log" 2>&1 &
+  CI_SERVICE_PIDS[$name]=$!
+  CI_SERVICE_LOGS[$name]=$log
+  CI_SERVICE_ORDER+=("$name")
+}
+
+ci_wait_service() {
+  local name=$1 port ready _
+  shift
+  local pid=${CI_SERVICE_PIDS[$name]}
+  for _ in {1..50}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      echo "::error::$name exited before becoming ready"
+      return 1
+    fi
+    ready=true
+    for port in "$@"; do
+      if ! ss -H -ltn "sport = :$port" | grep -q .; then
+        ready=false
+        break
+      fi
+    done
+    if "$ready"; then
+      return 0
+    fi
+    sleep 0.1
+  done
+  echo "::error::$name did not listen on ports $* within 5 seconds"
+  return 1
+}
+
+ci_stop_service() {
+  local name=$1
+  local pid=${CI_SERVICE_PIDS[$name]:-}
+  if [ -n "$pid" ]; then
+    kill "$pid" 2>/dev/null || true
+    wait "$pid" 2>/dev/null || true
+    unset 'CI_SERVICE_PIDS[$name]'
+  fi
+}
+
+ci_cleanup_services() {
+  local status=$1 name index
+  # Stop dependents before services started earlier (e.g. the metadata server).
+  for ((index=${#CI_SERVICE_ORDER[@]}-1; index>=0; index--)); do
+    ci_stop_service "${CI_SERVICE_ORDER[$index]}"
+  done
+  if [ "$status" -ne 0 ]; then
+    for name in "${CI_SERVICE_ORDER[@]}"; do
+      echo "=== $name ==="
+      cat "${CI_SERVICE_LOGS[$name]}" 2>/dev/null || true
+    done
+  fi
+  return "$status"
+}
diff --git a/scripts/ci/testpypi_wheel_gate.py b/scripts/ci/testpypi_wheel_gate.py
new file mode 100644
index 0000000000..e89e5353c1
--- /dev/null
+++ b/scripts/ci/testpypi_wheel_gate.py
@@ -0,0 +1,412 @@
+#!/usr/bin/env python3
+"""Validate the core Mooncake pre-release wheel set on disk or TestPyPI."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import NamedTuple
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+from zipfile import BadZipFile, ZipFile
+
+from packaging.metadata import InvalidMetadata, Metadata
+from packaging.utils import (
+    InvalidSdistFilename,
+    InvalidWheelFilename,
+    canonicalize_name,
+    parse_sdist_filename,
+    parse_wheel_filename,
+)
+from packaging.version import InvalidVersion, Version
+
+CORE_PACKAGES = (
+    "mooncake-transfer-engine",
+    "mooncake-transfer-engine-cuda13",
+    "mooncake-transfer-engine-non-cuda",
+)
+PYTHON_TAGS = ("cp310", "cp311", "cp312", "cp313")
+ARCHITECTURES = ("x86_64", "aarch64")
+DEFAULT_INDEX_URL = "https://test.pypi.org/simple"
+
+WheelTarget = tuple[str, str, str]
+
+
+class IndexedArtifact(NamedTuple):
+    """One artifact advertised by a package's Simple API page."""
+
+    filename: str
+    sha256: str | None
+
+
+ArtifactFetcher = Callable[[str], list[IndexedArtifact]]
+
+
+class GateError(RuntimeError):
+    """A release gate invariant was not satisfied."""
+
+
+def expected_targets() -> set[WheelTarget]:
+    """Return every package/Python/architecture target in the core matrix."""
+    return {
+        (canonicalize_name(package), python_tag, architecture)
+        for package in CORE_PACKAGES
+        for python_tag in PYTHON_TAGS
+        for architecture in ARCHITECTURES
+    }
+
+
+def normalize_prerelease_tag(tag: str) -> Version:
+    """Normalize a public PEP 440 pre-release tag starting with ``v``."""
+    if not tag.startswith("v"):
+        raise GateError(f"pre-release tag must start with v: {tag!r}")
+    try:
+        version = Version(tag[1:])
+    except InvalidVersion as error:
+        raise GateError(f"invalid PEP 440 version in tag {tag!r}: {error}") from error
+    if not version.is_prerelease or version.local is not None:
+        raise GateError(f"tag {tag!r} must identify a public PEP 440 pre-release")
+    return version
+
+
+def _target_from_wheel(filename: str, expected_version: Version) -> WheelTarget:
+    try:
+        package, version, _build, tags = parse_wheel_filename(filename)
+    except InvalidWheelFilename as error:
+        raise GateError(f"invalid wheel filename {filename!r}: {error}") from error
+
+    if str(version) != str(expected_version):
+        raise GateError(
+            f"wheel {filename!r} has version {version}, expected {expected_version}"
+        )
+
+    package = canonicalize_name(package)
+    candidates = {
+        (package, tag.interpreter, architecture)
+        for tag in tags
+        if tag.interpreter in PYTHON_TAGS
+        for architecture in ARCHITECTURES
+        if tag.platform.endswith(f"_{architecture}")
+    }
+    if len(candidates) != 1:
+        raise GateError(
+            f"wheel {filename!r} does not identify exactly one expected "
+            f"Python/architecture target: {sorted(candidates)}"
+        )
+    return candidates.pop()
+
+
+def validate_wheel_set(filenames: Iterable[str], version: Version) -> None:
+    """Require exactly one wheel for each target at ``version``."""
+    files_by_target: dict[WheelTarget, str] = {}
+    for filename in filenames:
+        target = _target_from_wheel(filename, version)
+        if target in files_by_target:
+            raise GateError(
+                f"duplicate wheels for {target}: "
+                f"{files_by_target[target]!r} and {filename!r}"
+            )
+        files_by_target[target] = filename
+
+    actual = set(files_by_target)
+    expected = expected_targets()
+    missing = sorted(expected - actual)
+    unexpected = sorted(actual - expected)
+    if missing or unexpected:
+        details = []
+        if missing:
+            details.append(f"missing targets: {missing}")
+        if unexpected:
+            details.append(f"unexpected targets: {unexpected}")
+        raise GateError("; ".join(details))
+
+
+def _validate_wheel_metadata(path: Path, expected_version: Version) -> None:
+    expected_package = _target_from_wheel(path.name, expected_version)[0]
+    try:
+        with ZipFile(path) as wheel:
+            metadata_files = [
+                name
+                for name in wheel.namelist()
+                if name.endswith(".dist-info/METADATA")
+            ]
+            if len(metadata_files) != 1:
+                raise GateError(
+                    f"wheel {path.name!r} contains {len(metadata_files)} "
+                    ".dist-info/METADATA files, expected exactly one"
+                )
+            metadata = Metadata.from_email(
+                wheel.read(metadata_files[0]), validate=False
+            )
+            metadata_package = canonicalize_name(metadata.name)
+            metadata_version = metadata.version
+    except (BadZipFile, InvalidMetadata, OSError) as error:
+        raise GateError(f"cannot read wheel {path.name!r}: {error}") from error
+
+    if metadata_package != expected_package:
+        raise GateError(
+            f"wheel {path.name!r} has metadata name {metadata.name!r}, "
+            f"expected {expected_package!r}"
+        )
+    if str(metadata_version) != str(expected_version):
+        raise GateError(
+            f"wheel {path.name!r} has metadata version {metadata_version}, "
+            f"expected {expected_version}"
+        )
+
+
+def validate_local(directory: Path, version: Version) -> None:
+    """Validate all wheels collected for publication."""
+    wheels = sorted(directory.glob("*.whl"))
+    if not wheels:
+        raise GateError(f"no wheels found in {directory}")
+    validate_wheel_set((path.name for path in wheels), version)
+    for path in wheels:
+        _validate_wheel_metadata(path, version)
+    print(f"Validated {len(wheels)} local wheels for {version}")
+
+
+def _fetch_package_artifacts(index_url: str, package: str) -> list[IndexedArtifact]:
+    """Read artifact filenames and hashes from a Simple API project page."""
+    project_url = f"{index_url.rstrip('/')}/{canonicalize_name(package)}/"
+    request = Request(
+        project_url,
+        headers={
+            "Accept": "application/vnd.pypi.simple.v1+json",
+            "User-Agent": "Mooncake-TestPyPI-release-gate/1",
+        },
+    )
+    try:
+        with urlopen(request, timeout=30) as response:
+            payload = json.load(response)
+    except HTTPError as error:
+        if error.code == 404:
+            return []
+        raise
+    return [
+        IndexedArtifact(item["filename"], item.get("hashes", {}).get("sha256"))
+        for item in payload.get("files", [])
+    ]
+
+
+def fetch_index_artifacts(index_url: str) -> list[IndexedArtifact]:
+    return [
+        artifact
+        for package in CORE_PACKAGES
+        for artifact in _fetch_package_artifacts(index_url, package)
+    ]
+
+
+def _artifact_version(filename: str) -> Version | None:
+    try:
+        if filename.endswith(".whl"):
+            return parse_wheel_filename(filename)[1]
+        return parse_sdist_filename(filename)[1]
+    except (InvalidSdistFilename, InvalidWheelFilename, InvalidVersion):
+        return None
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as wheel:
+        for chunk in iter(lambda: wheel.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _local_wheel_hashes(directory: Path, version: Version) -> dict[str, str]:
+    validate_local(directory, version)
+    return {path.name: _sha256(path) for path in sorted(directory.glob("*.whl"))}
+
+
+def _indexed_version_artifacts(
+    index_url: str,
+    version: Version,
+    fetcher: ArtifactFetcher,
+) -> dict[str, str | None]:
+    indexed: dict[str, str | None] = {}
+    for artifact in fetcher(index_url):
+        if _artifact_version(artifact.filename) != version:
+            continue
+        if artifact.filename in indexed:
+            raise GateError(f"TestPyPI lists {artifact.filename!r} more than once")
+        indexed[artifact.filename] = artifact.sha256
+    return indexed
+
+
+def _validate_indexed_hashes(
+    local_hashes: dict[str, str],
+    indexed: dict[str, str | None],
+    version: Version,
+    *,
+    require_complete: bool,
+) -> None:
+    """Require every visible artifact to match and optionally require all files."""
+    if require_complete:
+        missing = sorted(set(local_hashes) - set(indexed))
+        if missing:
+            raise GateError(
+                f"TestPyPI is missing {len(missing)} artifacts for {version}: {missing}"
+            )
+
+    for filename, indexed_hash in sorted(indexed.items()):
+        local_hash = local_hashes.get(filename)
+        if local_hash is None:
+            raise GateError(
+                f"TestPyPI contains unexpected artifact {filename!r} for {version}"
+            )
+        if not indexed_hash:
+            raise GateError(
+                f"TestPyPI did not advertise a SHA-256 hash for {filename!r}"
+            )
+        if indexed_hash.lower() != local_hash:
+            raise GateError(
+                f"TestPyPI artifact {filename!r} has SHA-256 {indexed_hash}, "
+                f"but the local wheel has {local_hash}; refusing to mix builds"
+            )
+
+
+def validate_upload_state(
+    directory: Path,
+    version: Version,
+    fetcher: ArtifactFetcher = fetch_index_artifacts,
+    *,
+    index_url: str = DEFAULT_INDEX_URL,
+) -> None:
+    """Allow an empty index or an exact, hash-matching partial upload.
+
+    TestPyPI filenames do not identify build contents. Comparing the hashes
+    advertised by the Simple API prevents a retry from combining wheels from
+    two different builds under one immutable version.
+    """
+    local_hashes = _local_wheel_hashes(directory, version)
+    indexed = _indexed_version_artifacts(index_url, version, fetcher)
+    _validate_indexed_hashes(
+        local_hashes,
+        indexed,
+        version,
+        require_complete=False,
+    )
+
+    if indexed:
+        print(
+            f"Validated {len(indexed)} matching existing TestPyPI artifacts; "
+            "the upload can safely resume"
+        )
+    else:
+        print(f"TestPyPI has no existing core artifacts for {version}")
+
+
+def wait_for_upload_state(
+    directory: Path,
+    index_url: str,
+    version: Version,
+    attempts: int,
+    initial_delay: float,
+    max_delay: float,
+    fetcher: ArtifactFetcher = fetch_index_artifacts,
+    sleeper: Callable[[float], None] = time.sleep,
+) -> None:
+    """Wait until every published wheel is visible with its local SHA-256."""
+    if attempts < 1:
+        raise GateError("attempts must be at least 1")
+
+    local_hashes = _local_wheel_hashes(directory, version)
+    delay = initial_delay
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            indexed = _indexed_version_artifacts(index_url, version, fetcher)
+            _validate_indexed_hashes(
+                local_hashes,
+                indexed,
+                version,
+                require_complete=True,
+            )
+        except (GateError, OSError) as error:
+            last_error = error
+            if attempt == attempts:
+                break
+            print(
+                "TestPyPI hashes are not ready "
+                f"(attempt {attempt}/{attempts}): {error}; "
+                f"retrying in {delay:g}s",
+                flush=True,
+            )
+            sleeper(delay)
+            delay = min(delay * 2, max_delay)
+        else:
+            print(
+                f"Validated all {len(indexed)} published TestPyPI hashes for {version}"
+            )
+            return
+
+    raise GateError(
+        f"TestPyPI did not expose the complete, hash-matching wheel set for "
+        f"{version} after {attempts} attempts: {last_error}"
+    )
+
+
+def _version(value: str) -> Version:
+    try:
+        return Version(value)
+    except InvalidVersion as error:
+        raise argparse.ArgumentTypeError(str(error)) from error
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    normalize = subparsers.add_parser("normalize-version")
+    normalize.add_argument("--tag", required=True)
+
+    upload = subparsers.add_parser("validate-upload-state")
+    upload.add_argument("--directory", type=Path, required=True)
+    upload.add_argument("--index-url", default=DEFAULT_INDEX_URL)
+    upload.add_argument("--version", type=_version, required=True)
+
+    wait_upload = subparsers.add_parser("wait-upload-state")
+    wait_upload.add_argument("--directory", type=Path, required=True)
+    wait_upload.add_argument("--index-url", default=DEFAULT_INDEX_URL)
+    wait_upload.add_argument("--version", type=_version, required=True)
+    wait_upload.add_argument("--attempts", type=int, default=8)
+    wait_upload.add_argument("--initial-delay", type=float, default=5)
+    wait_upload.add_argument("--max-delay", type=float, default=30)
+
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    try:
+        if args.command == "normalize-version":
+            print(normalize_prerelease_tag(args.tag))
+        elif args.command == "validate-upload-state":
+            validate_upload_state(
+                args.directory,
+                args.version,
+                index_url=args.index_url,
+            )
+        elif args.command == "wait-upload-state":
+            wait_for_upload_state(
+                args.directory,
+                args.index_url,
+                args.version,
+                args.attempts,
+                args.initial_delay,
+                args.max_delay,
+            )
+    except GateError as error:
+        print(f"release gate failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/ci/tests/test_nightly_rocm_publish.py b/scripts/ci/tests/test_nightly_rocm_publish.py
new file mode 100644
index 0000000000..27f3114026
--- /dev/null
+++ b/scripts/ci/tests/test_nightly_rocm_publish.py
@@ -0,0 +1,76 @@
+from pathlib import Path
+import unittest
+
+import yaml
+
+
+REPOSITORY = Path(__file__).resolve().parents[3]
+WORKFLOWS = REPOSITORY / ".github" / "workflows"
+
+
+def load_workflow(name):
+    with (WORKFLOWS / name).open() as workflow_file:
+        return yaml.safe_load(workflow_file)
+
+
+def step_named(job, name):
+    return next(step for step in job["steps"] if step.get("name") == name)
+
+
+def step_index(job, name):
+    return next(
+        index for index, step in enumerate(job["steps"]) if step.get("name") == name
+    )
+
+
+class NightlyRocmPublishTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.nightly = load_workflow("nightly.yml")
+        cls.rocm = load_workflow("ci_rocm.yml")
+
+    def test_rocm_builder_accepts_and_applies_version_override(self):
+        triggers = self.rocm.get("on", self.rocm.get(True))
+        version_input = triggers["workflow_call"]["inputs"]["version_override"]
+        self.assertEqual(version_input["default"], "")
+        self.assertEqual(version_input["type"], "string")
+
+        build = self.rocm["jobs"]["build-wheel-rocm"]
+        version_step = step_named(build, "Apply wheel version override")
+        self.assertEqual(version_step["if"], "${{ inputs.version_override != '' }}")
+        self.assertEqual(
+            version_step["env"]["VERSION_OVERRIDE"],
+            "${{ inputs.version_override }}",
+        )
+        self.assertIn("mooncake-wheel/pyproject.toml", version_step["run"])
+        self.assertLess(
+            step_index(build, "Apply wheel version override"),
+            step_index(build, "Build Python wheel"),
+        )
+
+    def test_nightly_publishes_versioned_rocm_artifacts(self):
+        jobs = self.nightly["jobs"]
+        rocm_build = jobs["build-wheel-rocm"]
+        self.assertEqual(rocm_build["needs"], "version-stamp")
+        self.assertEqual(
+            rocm_build["with"]["version_override"],
+            "${{ needs.version-stamp.outputs.nightly_version }}",
+        )
+
+        publisher = jobs["publish-testpypi"]
+        self.assertIn("build-wheel-rocm", publisher["needs"])
+        patterns = {
+            step.get("with", {}).get("pattern")
+            for step in publisher["steps"]
+            if step.get("uses") == "actions/download-artifact@v4"
+        }
+        self.assertIn("nightly-*", patterns)
+        self.assertIn("mooncake-wheel-rocm-ubuntu-*", patterns)
+        self.assertLess(
+            step_index(publisher, "Download ROCm nightly wheel artifacts"),
+            step_index(publisher, "Collect wheels for nightly publication"),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/ci/tests/test_rpc_smoke.py b/scripts/ci/tests/test_rpc_smoke.py
new file mode 100644
index 0000000000..f282e0d41b
--- /dev/null
+++ b/scripts/ci/tests/test_rpc_smoke.py
@@ -0,0 +1,84 @@
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "run_rpc_smoke.sh"
+
+
+class RpcSmokeTest(unittest.TestCase):
+    def test_transfer_result_and_server_cleanup(self):
+        # The bandwidth client runs continuously. A timeout is only acceptable
+        # after it has reported an actual transfer; other failures must propagate.
+        for client_status, bandwidth, expected_status in [
+            (0, True, 0),
+            (124, True, 0),
+            (2, True, 2),
+            (124, False, 1),
+            (0, False, 1),
+        ]:
+            with self.subTest(client_status=client_status, bandwidth=bandwidth):
+                with tempfile.TemporaryDirectory() as directory:
+                    root = Path(directory)
+                    ready = root / "ready"
+                    os.mkfifo(ready)
+                    commands = {
+                        "python": """#!/usr/bin/python3
+import os
+import signal
+from pathlib import Path
+root = Path(os.environ['RUNNER_TEMP'])
+(root / 'server.pid').write_text(str(os.getpid()))
+with (root / 'ready').open('w') as pipe:
+    pipe.write('listening\\n')
+signal.pause()
+""",
+                        # Coordinate readiness through a pipe rather than timing
+                        # the background process or binding a real network port.
+                        "ss": '#!/bin/sh\ncat "$RUNNER_TEMP/ready"\n',
+                        "timeout": """#!/bin/sh
+if [ "$REPORT_BANDWIDTH" = true ]; then
+    echo 'bandwidth: 1 GB/s'
+fi
+exit "$CLIENT_STATUS"
+""",
+                    }
+                    for name, content in commands.items():
+                        command = root / name
+                        command.write_text(content)
+                        command.chmod(0o755)
+
+                    result = subprocess.run(
+                        ["bash", str(SCRIPT)],
+                        env={
+                            **os.environ,
+                            "PATH": f"{root}:{os.environ['PATH']}",
+                            "RUNNER_TEMP": directory,
+                            "CLIENT_STATUS": str(client_status),
+                            "REPORT_BANDWIDTH": str(bandwidth).lower(),
+                        },
+                        capture_output=True,
+                        text=True,
+                        timeout=10,
+                    )
+                    pid = int((root / "server.pid").read_text())
+                    try:
+                        with self.assertRaises(ProcessLookupError):
+                            os.kill(pid, 0)
+                    finally:
+                        # Do not leave a server behind if cleanup regresses.
+                        try:
+                            os.kill(pid, 9)
+                        except ProcessLookupError:
+                            pass
+                    self.assertEqual(
+                        result.returncode,
+                        expected_status,
+                        result.stdout + result.stderr,
+                    )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/ci/tests/test_run_ctest.py b/scripts/ci/tests/test_run_ctest.py
new file mode 100644
index 0000000000..21b16b82e1
--- /dev/null
+++ b/scripts/ci/tests/test_run_ctest.py
@@ -0,0 +1,135 @@
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+
+SCRIPT = Path(__file__).resolve().parents[3] / ".github/actions/run-ctest/run.sh"
+
+
+class RunCTestTest(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name).resolve()
+        (self.root / "build").mkdir()
+
+    def run_suite(self, **overrides):
+        env = {
+            **os.environ,
+            "SCRIPT": str(SCRIPT),
+            "SUITE_TMP": str(self.root),
+            "GITHUB_WORKSPACE": str(self.root),
+            "RESERVE_RPC_PORT": "false",
+            "JUNIT_REPORT": "",
+            "LD_LIBRARY_PATH": "/test/lib",
+            "EXISTING_PORTS": "",
+            "CTEST_STATUS": "0",
+        }
+        # An inherited workflow setting must not affect the unset-value case.
+        env.pop("CTEST_LABEL_EXCLUDE", None)
+        env.update(overrides)
+        return subprocess.run(
+            [
+                "bash",
+                "-c",
+                """
+nproc() { echo 6; }
+sysctl() {
+  printf '%s\\0' "$@" >> "$SUITE_TMP/sysctl.args"
+  if [ "$1" = -n ]; then printf '%s\\n' "$EXISTING_PORTS"; fi
+}
+sudo() {
+  printf '%s\\0' "$@" >> "$SUITE_TMP/sudo.args"
+  "$@"
+}
+ctest() {
+  printf '%s\\0' "$@" > "$SUITE_TMP/ctest.args"
+  printf '%s\\0' "$PWD" "$LD_LIBRARY_PATH" "$MC_METADATA_SERVER" \\
+    "$DEFAULT_KV_LEASE_TTL" > "$SUITE_TMP/ctest.env"
+  return "$CTEST_STATUS"
+}
+source "$SCRIPT"
+""",
+            ],
+            cwd=self.root,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+    def recorded(self, name):
+        return (self.root / name).read_bytes().decode().split("\0")[:-1]
+
+    def test_unset_or_empty_filter_preserves_default_sweep(self):
+        for overrides in ({}, {"CTEST_LABEL_EXCLUDE": ""}):
+            with self.subTest(overrides=overrides):
+                result = self.run_suite(**overrides)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertEqual(
+                    self.recorded("ctest.args"),
+                    ["--parallel", "6", "--output-on-failure"],
+                )
+                self.assertEqual(
+                    self.recorded("ctest.env"),
+                    [
+                        str(self.root / "build"),
+                        "/test/lib:/usr/local/lib",
+                        "http://127.0.0.1:8080/metadata",
+                        "500",
+                    ],
+                )
+                self.assertFalse((self.root / "sudo.args").exists())
+                self.assertFalse((self.root / "sysctl.args").exists())
+
+    def test_label_regex_is_one_literal_argument(self):
+        regex = "^(nvlink_gpu|other hardware[0-9]*)$"
+        result = self.run_suite(CTEST_LABEL_EXCLUDE=regex)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(
+            self.recorded("ctest.args"),
+            ["--parallel", "6", "--output-on-failure", "--label-exclude", regex],
+        )
+
+    def test_junit_report_and_filter_coexist(self):
+        report = "build/test results/ctest.xml"
+        result = self.run_suite(JUNIT_REPORT=report, CTEST_LABEL_EXCLUDE="^nvlink_gpu$")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        args = self.recorded("ctest.args")
+        self.assertEqual(args[:3], ["--parallel", "6", "--output-on-failure"])
+        self.assertEqual(len(args), 7)
+        self.assertEqual(
+            args[args.index("--output-junit") + 1], str(self.root / report)
+        )
+        self.assertEqual(args[args.index("--label-exclude") + 1], "^nvlink_gpu$")
+        self.assertTrue((self.root / report).parent.is_dir())
+
+    def test_port_reservation_preserves_existing_ports(self):
+        for existing in ("", "12345,23456-23460"):
+            with self.subTest(existing=existing):
+                for name in ("sysctl.args", "sudo.args"):
+                    (self.root / name).unlink(missing_ok=True)
+                result = self.run_suite(
+                    RESERVE_RPC_PORT="true", EXISTING_PORTS=existing
+                )
+                self.assertEqual(result.returncode, 0, result.stderr)
+                value = f"{existing},50052" if existing else "50052"
+                assignment = f"net.ipv4.ip_local_reserved_ports={value}"
+                self.assertEqual(
+                    self.recorded("sysctl.args"),
+                    ["-n", "net.ipv4.ip_local_reserved_ports", "-w", assignment],
+                )
+                self.assertEqual(
+                    self.recorded("sudo.args"), ["sysctl", "-w", assignment]
+                )
+
+    def test_ctest_failure_status_propagates(self):
+        result = self.run_suite(CTEST_STATUS="23", CTEST_LABEL_EXCLUDE="nvlink_gpu")
+        self.assertEqual(result.returncode, 23, result.stdout + result.stderr)
+        self.assertIn("--label-exclude", self.recorded("ctest.args"))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/ci/tests/test_services.py b/scripts/ci/tests/test_services.py
new file mode 100644
index 0000000000..fac9839513
--- /dev/null
+++ b/scripts/ci/tests/test_services.py
@@ -0,0 +1,107 @@
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+
+SERVICES = Path(__file__).resolve().parents[1] / "services.sh"
+
+
+class ServicesTest(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        os.mkfifo(self.root / "ready")
+        os.mkfifo(self.root / "hold")
+
+    def run_suite(self, body):
+        return subprocess.run(
+            ["bash", "-e", "-o", "pipefail", "-c", body],
+            env={**os.environ, "SERVICES": str(SERVICES), "SUITE_TMP": str(self.root)},
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+    def test_failure_preserves_status_logs_and_cleans_all_services(self):
+        result = self.run_suite(
+            """
+source "$SERVICES"
+trap 'ci_cleanup_services "$?"' EXIT
+for name in metadata master; do
+  ci_start_service "$name" "$SUITE_TMP/$name.log" bash -c '
+    echo "startup: $1"
+    echo ready > "$2/ready"
+    exec cat "$2/hold"
+  ' _ "$name" "$SUITE_TMP"
+  echo "${CI_SERVICE_PIDS[$name]}" >> "$SUITE_TMP/pids"
+  read -r ready < "$SUITE_TMP/ready"
+done
+exit 23
+"""
+        )
+        self.assertEqual(result.returncode, 23, result.stderr)
+        self.assertIn("startup: metadata", result.stdout)
+        self.assertIn("startup: master", result.stdout)
+        for pid in (self.root / "pids").read_text().splitlines():
+            with self.assertRaises(ProcessLookupError):
+                os.kill(int(pid), 0)
+
+    def test_wait_requires_every_port_and_stop_is_idempotent(self):
+        result = self.run_suite(
+            """
+source "$SERVICES"
+trap 'ci_cleanup_services "$?"' EXIT
+ci_start_service master "$SUITE_TMP/master.log" cat "$SUITE_TMP/hold"
+ss() {
+  echo "$*" >> "$SUITE_TMP/probes"
+  if [[ "$*" == *50051 ]]; then
+    echo listening
+  elif [ -f "$SUITE_TMP/retried" ]; then
+    echo listening
+  fi
+}
+sleep() { touch "$SUITE_TMP/retried"; }
+ci_wait_service master 50051 8080
+ci_stop_service master
+ci_stop_service master
+"""
+        )
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        probes = (self.root / "probes").read_text()
+        self.assertEqual(probes.count(":8080"), 2)
+        self.assertEqual(probes.count(":50051"), 2)
+
+    def test_startup_exit_is_reported_with_server_log(self):
+        result = self.run_suite(
+            """
+source "$SERVICES"
+trap 'ci_cleanup_services "$?"' EXIT
+ci_start_service master "$SUITE_TMP/master.log" bash -c 'echo startup-failed; exit 7'
+wait "${CI_SERVICE_PIDS[master]}" || true
+ci_wait_service master 50051
+"""
+        )
+        self.assertEqual(result.returncode, 1, result.stderr)
+        self.assertIn("exited before becoming ready", result.stdout)
+        self.assertIn("startup-failed", result.stdout)
+
+    def test_readiness_timeout_fails_without_wall_clock_delay(self):
+        result = self.run_suite(
+            """
+source "$SERVICES"
+trap 'ci_cleanup_services "$?"' EXIT
+ci_start_service master "$SUITE_TMP/master.log" cat "$SUITE_TMP/hold"
+ss() { return 0; }
+sleep() { :; }
+ci_wait_service master 50051
+"""
+        )
+        self.assertEqual(result.returncode, 1, result.stderr)
+        self.assertIn("did not listen", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/hygon/redact_ci_logs.py b/scripts/hygon/redact_ci_logs.py
new file mode 100644
index 0000000000..aa909dcb30
--- /dev/null
+++ b/scripts/hygon/redact_ci_logs.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+# Copyright 2026 Hygon Information Technology Co., Ltd.
+#
+# 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.
+
+"""Create redacted log copies for artifact upload; never modify raw logs."""
+
+import ipaddress
+import os
+from pathlib import Path
+import re
+import sys
+from urllib.parse import urlsplit
+
+
+def redact_ipv6(match):
+    try:
+        ipaddress.IPv6Address(match.group())
+    except ValueError:
+        return match.group()  # Preserve colon-separated timestamps and error text.
+    return "[REDACTED_IP]"
+
+
+def main():
+    source, destination = map(Path, sys.argv[1:])
+    replacements = {}
+    for name in (
+        "DTK_PKG_URL",
+        "PIP_INDEX_URL",
+        "TARGET_HOST",
+        "INITIATOR_HOST",
+        "TARGET_FILTER",
+        "INITIATOR_FILTER",
+    ):
+        value = os.environ.get(name, "")
+        if not value:
+            raise SystemExit("ERROR: missing redaction configuration: " + name)
+        marker = "[REDACTED_" + name + "]"
+        replacements[value] = marker
+        if name.endswith("URL"):
+            url = urlsplit(value)
+            for component in (url.netloc, url.hostname):
+                if component:
+                    replacements[component] = marker
+        elif name.endswith("HOST"):
+            try:
+                ipaddress.ip_address(value)
+            except ValueError:
+                replacements[value.split(".")[0]] = marker
+
+    # Match original values in one pass so replacement markers stay intact.
+    pattern = re.compile(
+        "|".join(
+            re.escape(value) for value in sorted(replacements, key=len, reverse=True)
+        )
+    )
+    destination.mkdir(parents=True, exist_ok=True)
+    for log in sorted(source.glob("*.log")):
+        text = log.read_text(encoding="utf-8", errors="surrogateescape")
+        text = pattern.sub(lambda match: replacements[match.group()], text)
+        # RDMA logs may encode addresses as 16 colon-separated hex bytes.
+        text = re.sub(
+            r"(?i)(?<![\w:])(?:[0-9a-f]{2}:){15}[0-9a-f]{2}(?![\w:])",
+            "[REDACTED_GID]",
+            text,
+        )
+        text = re.sub(
+            r"(?i)(?<![\w:])(?:[0-9a-f]{0,4}:){2,}[0-9a-f]{0,4}(?![\w:])",
+            redact_ipv6,
+            text,
+        )
+        text = re.sub(
+            r"(?<![\w.])(?:\d{1,3}\.){3}\d{1,3}(?![\w.])", "[REDACTED_IP]", text
+        )
+        text = re.sub(r"\bmlx5_\d+\b", "[REDACTED_RDMA_DEVICE]", text)
+        (destination / log.name).write_text(
+            text, encoding="utf-8", errors="surrogateescape"
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/hygon/test_mooncake_store_cross_node.sh b/scripts/hygon/test_mooncake_store_cross_node.sh
new file mode 100644
index 0000000000..626cd704f1
--- /dev/null
+++ b/scripts/hygon/test_mooncake_store_cross_node.sh
@@ -0,0 +1,542 @@
+#!/usr/bin/env bash
+# Copyright 2026 Hygon Information Technology Co., Ltd.
+#
+# 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.
+
+set -Eeuo pipefail
+
+activate_runtime() {
+    set +u
+    source /opt/dtk/env.sh
+    set -u
+}
+
+check_ports_available() {
+    local node_name="$1"
+    shift
+    python3 - "${node_name}" "$@" <<'PY'
+import socket
+import sys
+
+node_name = sys.argv[1]
+sockets = []
+try:
+    for raw_port in sys.argv[2:]:
+        port = int(raw_port)
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 0)
+        try:
+            # This socket is only a conservative availability probe and is
+            # closed before any service starts; it is not a listening service.
+            sock.bind(("0.0.0.0", port))
+        except OSError as exc:
+            print(f"ERROR: {node_name} TCP port {port} is unavailable: {exc}", file=sys.stderr)
+            sys.exit(1)
+        sockets.append(sock)
+    print(f"Store CI ports are available on {node_name}: {' '.join(sys.argv[2:])}")
+finally:
+    for sock in sockets:
+        sock.close()
+PY
+}
+
+allocate_free_ports() {
+    local count="$1"
+    local range_min="$2"
+    local range_max="$3"
+    python3 - "${count}" "${range_min}" "${range_max}" <<'PY'
+import random
+import socket
+import sys
+
+count, range_min, range_max = map(int, sys.argv[1:])
+candidates = list(range(range_min, range_max + 1))
+random.SystemRandom().shuffle(candidates)
+sockets = []
+ports = []
+try:
+    for port in candidates:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 0)
+        try:
+            # Hold every candidate socket until the full unique set is chosen.
+            sock.bind(("0.0.0.0", port))
+        except OSError:
+            sock.close()
+            continue
+        sockets.append(sock)
+        ports.append(port)
+        if len(ports) == count:
+            print(" ".join(map(str, ports)))
+            break
+    else:
+        print(
+            f"ERROR: could not allocate {count} ports from {range_min}-{range_max}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+finally:
+    for sock in sockets:
+        sock.close()
+PY
+}
+
+prepare_container() {
+    local wheel_path="$1"
+    local dtk_tarball="/tmp/$(basename "${DTK_PKG_URL}")"
+    local dtk_dir=""
+
+    wget -q "${DTK_PKG_URL}" -O "${dtk_tarball}"
+    tar -xzf "${dtk_tarball}" -C /opt
+    dtk_dir="$(find /opt -mindepth 1 -maxdepth 1 -type d -name 'dtk-*' -print -quit)"
+    if [ -z "${dtk_dir}" ]; then
+        echo "ERROR: the DTK archive did not create /opt/dtk-*" >&2
+        exit 1
+    fi
+    ln -s "${dtk_dir}" /opt/dtk
+    activate_runtime
+
+    python3 -m pip install "${wheel_path}"
+    command -v mooncake_master >/dev/null
+    command -v mooncake_client >/dev/null
+    python3 -c 'from mooncake.store import MooncakeDistributedStore, ReplicateConfig'
+
+}
+
+run_master() {
+    local local_ip="$1"
+    local rpc_port="$2"
+    local metrics_port="$3"
+    local metadata_port="$4"
+    activate_runtime
+    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
+    exec mooncake_master \
+        --enable_ha=false \
+        --rpc_address="${local_ip}" \
+        --rpc_port="${rpc_port}" \
+        --metrics_port="${metrics_port}" \
+        --enable_http_metadata_server=true \
+        --http_metadata_server_host=0.0.0.0 \
+        --http_metadata_server_port="${metadata_port}" \
+        --default_kv_lease_ttl=300000 \
+        --logtostderr=true
+}
+
+run_client() {
+    local local_ip="$1"
+    local primary_ip="$2"
+    local device_filter="$3"
+    local master_rpc_port="$4"
+    local metadata_port="$5"
+    local client_port="$6"
+    activate_runtime
+    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
+    if [ "${device_filter}" = "__auto__" ]; then
+        device_filter=""
+    fi
+    if [ -n "${device_filter}" ]; then
+        export MC_TE_FILTERS="${device_filter}"
+    else
+        unset MC_TE_FILTERS || true
+    fi
+    exec mooncake_client \
+        --host="${local_ip}" \
+        --port="${client_port}" \
+        --global_segment_size=4GB \
+        --local_buffer_size=0 \
+        --master_server_address="${primary_ip}:${master_rpc_port}" \
+        --metadata_server="http://${primary_ip}:${metadata_port}/metadata" \
+        --protocol=rdma \
+        --logtostderr=true
+}
+
+run_store_benchmark() {
+    local local_ip="$1"
+    local primary_ip="$2"
+    local device_filter="$3"
+    local master_rpc_port="$4"
+    local metadata_port="$5"
+    local bench_port="$6"
+    activate_runtime
+    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
+    if [ "${device_filter}" = "__auto__" ]; then
+        device_filter=""
+    fi
+    if [ -n "${device_filter}" ]; then
+        export MC_TE_FILTERS="${device_filter}"
+    else
+        unset MC_TE_FILTERS || true
+    fi
+    exec python3 /work/store_kv_bench.py \
+        --scenario=verify_write \
+        --local-hostname="${local_ip}:${bench_port}" \
+        --metadata-server="http://${primary_ip}:${metadata_port}/metadata" \
+        --master-server="${primary_ip}:${master_rpc_port}" \
+        --protocol=rdma \
+        --device-name="" \
+        --global-segment-size=0 \
+        --local-buffer-size=134217728 \
+        --io-api=plain \
+        --numjobs=1 \
+        --iodepth=1 \
+        --batch-size=4 \
+        --nr-objects=16 \
+        --key-prefix=ci-store \
+        --key-size=32 \
+        --value-size=1048576 \
+        --memory-replica-num=1 \
+        --nof-replica-num=0 \
+        --verify \
+        --pattern=rdma \
+        --log-level=INFO
+}
+
+case "${1:-}" in
+    __container_prepare)
+        prepare_container "$2"
+        exit 0
+        ;;
+    __container_check_ports)
+        shift
+        check_ports_available "$@"
+        exit 0
+        ;;
+    __host_allocate_ports)
+        allocate_free_ports "$2" "$3" "$4"
+        exit 0
+        ;;
+    __container_master)
+        run_master "$2" "$3" "$4" "$5"
+        exit 0
+        ;;
+    __container_client)
+        run_client "$2" "$3" "$4" "$5" "$6" "$7"
+        exit 0
+        ;;
+    __container_benchmark)
+        shift
+        run_store_benchmark "$@"
+        exit 0
+        ;;
+esac
+
+: "${TEST_IMAGE:?TEST_IMAGE is required}"
+: "${DTK_PKG_URL:?DTK_PKG_URL is required}"
+test "$#" -eq 1
+
+for command_name in ip cut awk docker flock getent grep python3 realpath scp ssh timeout; do
+    command -v "${command_name}" >/dev/null 2>&1 || {
+        echo "ERROR: required command is missing: ${command_name}" >&2
+        exit 1
+    }
+done
+
+WHEEL_PATH="$(realpath "$1")"
+SELF_PATH="$(realpath "${BASH_SOURCE[0]}")"
+BENCH_PY_PATH="$(realpath "$(dirname "${BASH_SOURCE[0]}")/../../mooncake-store/benchmarks/store_kv_bench.py")"
+if [ ! -f "${WHEEL_PATH}" ]; then
+    echo "ERROR: wheel not found: ${WHEEL_PATH}" >&2
+    exit 1
+fi
+
+: "${TARGET_HOST:?TARGET_HOST is required}"
+: "${INITIATOR_HOST:?INITIATOR_HOST is required}"
+: "${TARGET_FILTER:?TARGET_FILTER is required}"
+: "${INITIATOR_FILTER:?INITIATOR_FILTER is required}"
+PRIMARY_HOST="${TARGET_HOST}"
+SECONDARY_HOST="${INITIATOR_HOST}"
+PRIMARY_FILTER="${TARGET_FILTER}"
+SECONDARY_FILTER="${INITIATOR_FILTER}"
+REMOTE_USER=github
+SSH_PORT=22
+PORT_RANGE_MIN=20000
+PORT_RANGE_MAX=29999
+LOCK_FILE=/tmp/mooncake-ci-cross-node.lock
+LOCK_TIMEOUT=900
+SETUP_TIMEOUT=900
+READY_TIMEOUT=180
+RUN_TIMEOUT=600
+LOG_DIR="${RUNNER_TEMP}/mooncake-store-logs"
+RUN_TOKEN="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-$$"
+PRIMARY_CONTAINER="mooncake-store-primary-${RUN_TOKEN}"
+SECONDARY_CONTAINER="mooncake-store-secondary-${RUN_TOKEN}"
+REMOTE_WORK_DIR="/tmp/mooncake-ci-store-${RUN_TOKEN}"
+WHEEL_BASENAME="$(basename "${WHEEL_PATH}")"
+
+resolve_ipv4() {
+    getent ahostsv4 "$1" 2>/dev/null | awk 'NR == 1 { print $1 }'
+}
+
+PRIMARY_IP="$(resolve_ipv4 "${PRIMARY_HOST}")"
+SECONDARY_IP="$(resolve_ipv4 "${SECONDARY_HOST}")"
+if [ -z "${PRIMARY_IP}" ] || [ -z "${SECONDARY_IP}" ]; then
+    echo "ERROR: failed to determine the primary or secondary IPv4 address" >&2
+    exit 1
+fi
+if [ "${PRIMARY_IP}" = "${SECONDARY_IP}" ]; then
+    echo "ERROR: primary and secondary resolve to the same IP" >&2
+    exit 1
+fi
+if ! ip -o -4 address show | awk '{print $4}' | cut -d/ -f1 | grep -Fxq "${PRIMARY_IP}"; then
+    echo "ERROR: TARGET_HOST must resolve to this runner's local service address" >&2
+    exit 1
+fi
+SECONDARY_SSH_HOST="${SECONDARY_HOST}"
+REMOTE="${REMOTE_USER}@${SECONDARY_SSH_HOST}"
+
+SSH_OPTIONS=(-p "${SSH_PORT}" -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=yes)
+SCP_OPTIONS=(-P "${SSH_PORT}" -o BatchMode=yes -o ConnectTimeout=10 -o StrictHostKeyChecking=yes)
+
+mkdir -p "${LOG_DIR}"
+LOG_NAMES=(primary-lock secondary-lock primary-port-check secondary-port-check primary-prepare secondary-prepare primary-master secondary-client store-kv-bench)
+for log_name in "${LOG_NAMES[@]}"; do
+    : >"${LOG_DIR}/${log_name}.log"
+done
+
+PRIMARY_LOCK_PID=""
+SECONDARY_LOCK_PID=""
+
+print_logs() {
+    local log_file=""
+    for log_file in "${LOG_DIR}"/*.log; do
+        echo "===== $(basename "${log_file}") ====="
+        cat "${log_file}"
+    done
+}
+
+cleanup() {
+    local rc=$?
+    trap - EXIT
+    set +e
+    docker rm -f "${PRIMARY_CONTAINER}" >/dev/null 2>&1 || true
+    ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- "${SECONDARY_CONTAINER}" "${REMOTE_WORK_DIR}" <<'REMOTE_CLEANUP' >/dev/null 2>&1
+container_name="$1"
+remote_dir="$2"
+docker rm -f "${container_name}" >/dev/null 2>&1 || true
+case "${remote_dir}" in
+    /tmp/mooncake-ci-store-*) rm -rf -- "${remote_dir}" ;;
+    *) echo "Refusing to remove unexpected path: ${remote_dir}" >&2 ;;
+esac
+REMOTE_CLEANUP
+    if [ -n "${SECONDARY_LOCK_PID}" ]; then
+        kill "${SECONDARY_LOCK_PID}" >/dev/null 2>&1 || true
+        wait "${SECONDARY_LOCK_PID}" >/dev/null 2>&1 || true
+    fi
+    if [ -n "${PRIMARY_LOCK_PID}" ]; then
+        kill "${PRIMARY_LOCK_PID}" >/dev/null 2>&1 || true
+        wait "${PRIMARY_LOCK_PID}" >/dev/null 2>&1 || true
+    fi
+    if [ "${rc}" -ne 0 ]; then
+        print_logs
+    fi
+    exit "${rc}"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+wait_for_log() {
+    local log_file="$1"
+    local pattern="$2"
+    local process_id="$3"
+    local description="$4"
+    local attempt=0
+    for ((attempt = 1; attempt <= READY_TIMEOUT; attempt++)); do
+        if grep -q "${pattern}" "${log_file}"; then
+            return 0
+        fi
+        if ! kill -0 "${process_id}" 2>/dev/null; then
+            echo "ERROR: ${description} exited before becoming ready" >&2
+            return 1
+        fi
+        sleep 1
+    done
+    echo "ERROR: ${description} was not ready within ${READY_TIMEOUT}s" >&2
+    return 1
+}
+
+wait_for_lock() {
+    local log_file="$1"
+    local process_id="$2"
+    local node_name="$3"
+    local attempt=0
+    for ((attempt = 1; attempt <= LOCK_TIMEOUT + 10; attempt++)); do
+        if grep -q '^LOCK_ACQUIRED$' "${log_file}"; then
+            return 0
+        fi
+        if ! kill -0 "${process_id}" 2>/dev/null; then
+            echo "ERROR: failed to acquire the cross-node test lock on ${node_name}" >&2
+            return 1
+        fi
+        sleep 1
+    done
+    echo "ERROR: timed out waiting for the cross-node test lock on ${node_name}" >&2
+    return 1
+}
+
+echo "Primary:   ${PRIMARY_HOST}"
+echo "Secondary: ${SECONDARY_HOST}"
+echo "Image:     ${TEST_IMAGE}"
+
+echo "Acquiring the cross-node test lock on ${PRIMARY_HOST}..."
+PARENT_PID="$$"
+(
+    exec 9>"${LOCK_FILE}"
+    if ! flock -w "${LOCK_TIMEOUT}" 9; then
+        echo "ERROR: lock wait timed out"
+        exit 75
+    fi
+    echo "LOCK_ACQUIRED"
+    while kill -0 "${PARENT_PID}" 2>/dev/null; do sleep 5; done
+) >"${LOG_DIR}/primary-lock.log" 2>&1 &
+PRIMARY_LOCK_PID=$!
+wait_for_lock "${LOG_DIR}/primary-lock.log" "${PRIMARY_LOCK_PID}" "${PRIMARY_HOST}"
+
+echo "Acquiring the cross-node test lock on ${SECONDARY_HOST}..."
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- "${LOCK_FILE}" "${LOCK_TIMEOUT}" \
+    >"${LOG_DIR}/secondary-lock.log" 2>&1 <<'REMOTE_LOCK' &
+set -Eeuo pipefail
+lock_file="$1"
+lock_timeout="$2"
+session_parent="$PPID"
+command -v flock >/dev/null
+exec 9>"${lock_file}"
+if ! flock -w "${lock_timeout}" 9; then
+    echo "ERROR: lock wait timed out"
+    exit 75
+fi
+echo "LOCK_ACQUIRED"
+while kill -0 "${session_parent}" 2>/dev/null; do sleep 5; done
+REMOTE_LOCK
+SECONDARY_LOCK_PID=$!
+wait_for_lock "${LOG_DIR}/secondary-lock.log" "${SECONDARY_LOCK_PID}" "${SECONDARY_HOST}"
+echo "Cross-node test locks acquired."
+
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" mkdir -p "${REMOTE_WORK_DIR}"
+scp "${SCP_OPTIONS[@]}" "${WHEEL_PATH}" "${SELF_PATH}" "${REMOTE}:${REMOTE_WORK_DIR}/"
+
+DOCKER_ENV_ARGS=(
+    -e "DTK_PKG_URL=${DTK_PKG_URL}"
+    -e "PIP_INDEX_URL=${PIP_INDEX_URL}"
+)
+
+docker run -d --name "${PRIMARY_CONTAINER}" --network host --privileged \
+    --volume "${WHEEL_PATH}:/work/${WHEEL_BASENAME}:ro" \
+    --volume "${SELF_PATH}:/work/test_mooncake_store_cross_node.sh:ro" \
+    --volume "${BENCH_PY_PATH}:/work/store_kv_bench.py:ro" \
+    "${DOCKER_ENV_ARGS[@]}" --entrypoint /bin/bash "${TEST_IMAGE}" -lc 'exec sleep infinity' >/dev/null
+
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- \
+    "${REMOTE_WORK_DIR}" "${WHEEL_BASENAME}" "$(basename "${SELF_PATH}")" \
+    "${SECONDARY_CONTAINER}" "${TEST_IMAGE}" "${DTK_PKG_URL}" \
+    "${PIP_INDEX_URL}" <<'REMOTE_CONTAINER' >/dev/null
+set -Eeuo pipefail
+remote_dir="$1"; wheel="$2"; script="$3"; container="$4"; image="$5"
+dtk_url="$6"; pip_index="$7"
+env_args=(-e "DTK_PKG_URL=${dtk_url}")
+[ -n "${pip_index}" ] && env_args+=(-e "PIP_INDEX_URL=${pip_index}")
+docker run -d --name "${container}" --network host --privileged \
+    --volume "${remote_dir}/${wheel}:/work/${wheel}:ro" \
+    --volume "${remote_dir}/${script}:/work/test_mooncake_store_cross_node.sh:ro" \
+    "${env_args[@]}" --entrypoint /bin/bash "${image}" -lc 'exec sleep infinity'
+REMOTE_CONTAINER
+
+echo "Preparing DTK and standard wheel on both nodes in parallel..."
+timeout "${SETUP_TIMEOUT}" docker exec "${PRIMARY_CONTAINER}" /bin/bash /work/test_mooncake_store_cross_node.sh \
+    __container_prepare "/work/${WHEEL_BASENAME}" >"${LOG_DIR}/primary-prepare.log" 2>&1 &
+PRIMARY_PREP_PID=$!
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- "${SECONDARY_CONTAINER}" "${WHEEL_BASENAME}" "${SETUP_TIMEOUT}" \
+    >"${LOG_DIR}/secondary-prepare.log" 2>&1 <<'REMOTE_PREPARE' &
+set -Eeuo pipefail
+timeout "$3" docker exec "$1" /bin/bash /work/test_mooncake_store_cross_node.sh __container_prepare "/work/$2"
+REMOTE_PREPARE
+SECONDARY_PREP_PID=$!
+
+set +e
+wait "${PRIMARY_PREP_PID}"; PRIMARY_PREP_RC=$?
+wait "${SECONDARY_PREP_PID}"; SECONDARY_PREP_RC=$?
+set -e
+if [ "${PRIMARY_PREP_RC}" -ne 0 ] || [ "${SECONDARY_PREP_RC}" -ne 0 ]; then
+    echo "ERROR: Store environment preparation failed (primary=${PRIMARY_PREP_RC}, secondary=${SECONDARY_PREP_RC})" >&2
+    exit 1
+fi
+
+read -r PRIMARY_MASTER_RPC_PORT PRIMARY_MASTER_METRICS_PORT PRIMARY_METADATA_PORT BENCH_PORT \
+    <<<"$(allocate_free_ports 4 "${PORT_RANGE_MIN}" "${PORT_RANGE_MAX}")"
+read -r SECONDARY_CLIENT_PORT \
+    <<<"$(ssh "${SSH_OPTIONS[@]}" "${REMOTE}" /bin/bash \
+        "${REMOTE_WORK_DIR}/$(basename "${SELF_PATH}")" __host_allocate_ports \
+        1 "${PORT_RANGE_MIN}" "${PORT_RANGE_MAX}")"
+
+for allocated_port in \
+    "${PRIMARY_MASTER_RPC_PORT}" "${PRIMARY_MASTER_METRICS_PORT}" "${PRIMARY_METADATA_PORT}" \
+    "${BENCH_PORT}" \
+    "${SECONDARY_CLIENT_PORT}"; do
+    if ! [[ "${allocated_port}" =~ ^[0-9]+$ ]]; then
+        echo "ERROR: automatic Store port allocation returned an invalid value" >&2
+        exit 1
+    fi
+done
+echo "Primary ports:   master=${PRIMARY_MASTER_RPC_PORT}/${PRIMARY_MASTER_METRICS_PORT} metadata=${PRIMARY_METADATA_PORT} bench=${BENCH_PORT}"
+echo "Secondary ports: client=${SECONDARY_CLIENT_PORT}"
+
+echo "Checking auto-allocated Store CI ports on both nodes..."
+docker exec "${PRIMARY_CONTAINER}" /bin/bash /work/test_mooncake_store_cross_node.sh \
+    __container_check_ports "${PRIMARY_HOST}" \
+    "${PRIMARY_MASTER_RPC_PORT}" "${PRIMARY_MASTER_METRICS_PORT}" "${PRIMARY_METADATA_PORT}" \
+    "${BENCH_PORT}" \
+    >"${LOG_DIR}/primary-port-check.log" 2>&1
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" docker exec "${SECONDARY_CONTAINER}" \
+    /bin/bash /work/test_mooncake_store_cross_node.sh \
+    __container_check_ports "${SECONDARY_HOST}" \
+    "${SECONDARY_CLIENT_PORT}" \
+    >"${LOG_DIR}/secondary-port-check.log" 2>&1
+
+docker exec "${PRIMARY_CONTAINER}" /bin/bash /work/test_mooncake_store_cross_node.sh __container_master \
+    "${PRIMARY_IP}" "${PRIMARY_MASTER_RPC_PORT}" "${PRIMARY_MASTER_METRICS_PORT}" "${PRIMARY_METADATA_PORT}" \
+    >"${LOG_DIR}/primary-master.log" 2>&1 &
+PRIMARY_MASTER_PID=$!
+wait_for_log "${LOG_DIR}/primary-master.log" 'Master service started' "${PRIMARY_MASTER_PID}" "primary master"
+
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" docker exec "${SECONDARY_CONTAINER}" \
+    /bin/bash /work/test_mooncake_store_cross_node.sh __container_client \
+    "${SECONDARY_IP}" "${PRIMARY_IP}" "${SECONDARY_FILTER}" "${PRIMARY_MASTER_RPC_PORT}" "${PRIMARY_METADATA_PORT}" "${SECONDARY_CLIENT_PORT}" \
+    >"${LOG_DIR}/secondary-client.log" 2>&1 &
+SECONDARY_CLIENT_PID=$!
+wait_for_log "${LOG_DIR}/secondary-client.log" 'Starting real client service' "${SECONDARY_CLIENT_PID}" "secondary client"
+
+timeout "${RUN_TIMEOUT}" docker exec "${PRIMARY_CONTAINER}" /bin/bash /work/test_mooncake_store_cross_node.sh \
+    __container_benchmark "${PRIMARY_IP}" "${PRIMARY_IP}" "${PRIMARY_FILTER}" \
+    "${PRIMARY_MASTER_RPC_PORT}" "${PRIMARY_METADATA_PORT}" "${BENCH_PORT}" \
+    >"${LOG_DIR}/store-kv-bench.log" 2>&1
+
+for phase in write_verify verify_read; do
+    grep -q "=== phase ${phase} ===" "${LOG_DIR}/store-kv-bench.log"
+done
+if grep -Eq 'failed_requests=[1-9]|failed_kvs=[1-9]|misses=[1-9]|verify_failures=[1-9]| ERROR |Traceback' \
+    "${LOG_DIR}/store-kv-bench.log"; then
+    echo "ERROR: Mooncake Store benchmark reported failures" >&2
+    exit 1
+fi
+
+echo "Mooncake Store RDMA write/read verification passed."
+grep -E '=== |failed_requests|failed_kvs|misses|verify_failures|overall summary' \
+    "${LOG_DIR}/store-kv-bench.log"
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    {
+        echo "### Mooncake Store RDMA KV benchmark"
+        echo
+        echo "- write_verify: passed"
+        echo "- Storage provider: secondary node only"
+    } >>"${GITHUB_STEP_SUMMARY}"
+fi
diff --git a/scripts/hygon/test_transfer_engine_cross_node.sh b/scripts/hygon/test_transfer_engine_cross_node.sh
new file mode 100644
index 0000000000..637388ae54
--- /dev/null
+++ b/scripts/hygon/test_transfer_engine_cross_node.sh
@@ -0,0 +1,468 @@
+#!/usr/bin/env bash
+# Copyright 2026 Hygon Information Technology Co., Ltd.
+#
+# 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.
+
+set -Eeuo pipefail
+
+prepare_container_runtime() {
+    local wheel_path="$1"
+    local dtk_tarball="/tmp/$(basename "${DTK_PKG_URL}")"
+    local dtk_dir=""
+
+    echo "Installing DTK from ${DTK_PKG_URL}..."
+    wget -q "${DTK_PKG_URL}" -O "${dtk_tarball}"
+    tar -xzf "${dtk_tarball}" -C /opt
+    dtk_dir="$(find /opt -mindepth 1 -maxdepth 1 -type d -name 'dtk-*' -print -quit)"
+    if [ -z "${dtk_dir}" ]; then
+        echo "ERROR: the DTK archive did not create /opt/dtk-*" >&2
+        exit 1
+    fi
+    ln -s "${dtk_dir}" /opt/dtk
+    set +u
+    source /opt/dtk/env.sh
+    set -u
+
+    echo "Installing standard wheel ${wheel_path}..."
+    python3 -m pip install "${wheel_path}"
+    python3 -m pip show mooncake-transfer-engine
+    if ! command -v transfer_engine_bench >/dev/null 2>&1; then
+        echo "ERROR: transfer_engine_bench was not installed by the wheel" >&2
+        exit 1
+    fi
+}
+
+activate_container_runtime() {
+    set +u
+    # shellcheck disable=SC1091
+    source /opt/dtk/env.sh
+    set -u
+    if ! command -v transfer_engine_bench >/dev/null 2>&1; then
+        echo "ERROR: prepared container does not contain transfer_engine_bench" >&2
+        exit 1
+    fi
+}
+
+run_container_target() {
+    local target_ip="$1"
+
+    activate_container_runtime
+    export MC_TE_FILTERS="${TARGET_FILTER}"
+    echo "Starting target on ${target_ip} with MC_TE_FILTERS=${MC_TE_FILTERS}..."
+    exec transfer_engine_bench \
+        --mode=target \
+        --auto_discovery \
+        --protocol=rdma \
+        --metadata_server=P2PHANDSHAKE \
+        --threads=2 \
+        --local_server_name="${target_ip}"
+}
+
+run_container_initiator() {
+    local initiator_ip="$1"
+    local target_ip="$2"
+    local target_port="$3"
+    local operation="$4"
+    local initiator_filter="$5"
+
+    activate_container_runtime
+    export MC_TE_FILTERS="${initiator_filter}"
+    echo "Starting ${operation} initiator on ${initiator_ip}; target is ${target_ip}:${target_port}; MC_TE_FILTERS=${MC_TE_FILTERS}..."
+    exec transfer_engine_bench \
+        --mode=initiator \
+        --operation="${operation}" \
+        --auto_discovery \
+        --protocol=rdma \
+        --metadata_server=P2PHANDSHAKE \
+        --local_server_name="${initiator_ip}" \
+        --segment_id="${target_ip}:${target_port}" \
+        --threads=2 \
+        --duration=10
+}
+
+# The same file is mounted into each container and used as its entry point.
+case "${1:-}" in
+    __container_prepare)
+        prepare_container_runtime "$2"
+        exit 0
+        ;;
+    __container_target)
+        run_container_target "$2"
+        exit 0
+        ;;
+    __container_initiator)
+        run_container_initiator "$2" "$3" "$4" "$5" "$6"
+        exit 0
+        ;;
+esac
+
+: "${TEST_IMAGE:?TEST_IMAGE is required}"
+: "${DTK_PKG_URL:?DTK_PKG_URL is required}"
+test "$#" -eq 1
+
+for command_name in ip cut awk docker flock getent grep realpath scp sed ssh timeout; do
+    if ! command -v "${command_name}" >/dev/null 2>&1; then
+        echo "ERROR: required command is missing: ${command_name}" >&2
+        exit 1
+    fi
+done
+
+WHEEL_PATH="$(realpath "$1")"
+SELF_PATH="$(realpath "${BASH_SOURCE[0]}")"
+if [ ! -f "${WHEEL_PATH}" ]; then
+    echo "ERROR: wheel not found: ${WHEEL_PATH}" >&2
+    exit 1
+fi
+
+: "${TARGET_HOST:?TARGET_HOST is required}"
+: "${INITIATOR_HOST:?INITIATOR_HOST is required}"
+: "${TARGET_FILTER:?TARGET_FILTER is required}"
+: "${INITIATOR_FILTER:?INITIATOR_FILTER is required}"
+REMOTE_USER=github
+SSH_PORT=22
+SETUP_TIMEOUT=600
+READY_TIMEOUT=300
+SETTLE_SECONDS=5
+RUN_TIMEOUT=300
+LOCK_FILE=/tmp/mooncake-ci-cross-node.lock
+LOCK_TIMEOUT=900
+LOG_DIR="${RUNNER_TEMP}/transfer-engine-logs"
+RUN_TOKEN="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-$$"
+TARGET_CONTAINER="mooncake-ci-target-${RUN_TOKEN}"
+INITIATOR_CONTAINER="mooncake-ci-initiator-${RUN_TOKEN}"
+REMOTE_WORK_DIR="/tmp/mooncake-ci-standard-${RUN_TOKEN}"
+WHEEL_BASENAME="$(basename "${WHEEL_PATH}")"
+TARGET_LOG="${LOG_DIR}/target.log"
+INITIATOR_LOG="${LOG_DIR}/initiator.log"
+TARGET_LOCK_LOG="${LOG_DIR}/target-lock.log"
+INITIATOR_LOCK_LOG="${LOG_DIR}/initiator-lock.log"
+
+resolve_ipv4() {
+    getent ahostsv4 "$1" 2>/dev/null | awk 'NR == 1 { print $1 }'
+}
+
+TARGET_IP="$(resolve_ipv4 "${TARGET_HOST}")"
+INITIATOR_IP="$(resolve_ipv4 "${INITIATOR_HOST}")"
+if [ -z "${TARGET_IP}" ] || [ -z "${INITIATOR_IP}" ]; then
+    echo "ERROR: failed to determine the target or initiator IPv4 address" >&2
+    exit 1
+fi
+if [ "${TARGET_IP}" = "${INITIATOR_IP}" ]; then
+    echo "ERROR: target and initiator resolve to the same IP" >&2
+    exit 1
+fi
+if ! ip -o -4 address show | awk '{print $4}' | cut -d/ -f1 | grep -Fxq "${TARGET_IP}"; then
+    echo "ERROR: TARGET_HOST must resolve to this runner's local service address" >&2
+    exit 1
+fi
+INITIATOR_SSH_HOST="${INITIATOR_HOST}"
+REMOTE="${REMOTE_USER}@${INITIATOR_SSH_HOST}"
+
+mkdir -p "${LOG_DIR}"
+: >"${TARGET_LOG}"
+: >"${INITIATOR_LOG}"
+: >"${TARGET_LOCK_LOG}"
+: >"${INITIATOR_LOCK_LOG}"
+TARGET_LOCK_PID=""
+INITIATOR_LOCK_PID=""
+
+SSH_OPTIONS=(
+    -p "${SSH_PORT}"
+    -o BatchMode=yes
+    -o ConnectTimeout=10
+    -o ServerAliveInterval=10
+    -o ServerAliveCountMax=3
+    -o StrictHostKeyChecking=yes
+)
+SCP_OPTIONS=(
+    -P "${SSH_PORT}"
+    -o BatchMode=yes
+    -o ConnectTimeout=10
+    -o StrictHostKeyChecking=yes
+)
+DOCKER_ENV_ARGS=(
+    -e "DTK_PKG_URL=${DTK_PKG_URL}"
+    -e "PIP_INDEX_URL=${PIP_INDEX_URL}"
+)
+
+print_logs() {
+    echo "===== target lock (${TARGET_HOST}) ====="
+    cat "${TARGET_LOCK_LOG}"
+    echo "===== initiator lock (${INITIATOR_HOST}) ====="
+    cat "${INITIATOR_LOCK_LOG}"
+    echo "===== target (${TARGET_HOST}) full log ====="
+    cat "${TARGET_LOG}"
+    echo "===== initiator (${INITIATOR_HOST}) full log ====="
+    cat "${INITIATOR_LOG}"
+}
+
+cleanup() {
+    local rc=$?
+    trap - EXIT
+    set +e
+
+    if docker inspect "${TARGET_CONTAINER}" >/dev/null 2>&1; then
+        docker rm -f "${TARGET_CONTAINER}" >/dev/null 2>&1
+    fi
+
+    ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- \
+        "${INITIATOR_CONTAINER}" "${REMOTE_WORK_DIR}" <<'REMOTE_CLEANUP' >/dev/null 2>&1
+container_name="$1"
+remote_dir="$2"
+docker rm -f "${container_name}" >/dev/null 2>&1 || true
+case "${remote_dir}" in
+    /tmp/mooncake-ci-standard-*) rm -rf -- "${remote_dir}" ;;
+    *) echo "Refusing to remove unexpected path: ${remote_dir}" >&2 ;;
+esac
+REMOTE_CLEANUP
+
+    if [ -n "${INITIATOR_LOCK_PID}" ]; then
+        kill "${INITIATOR_LOCK_PID}" >/dev/null 2>&1 || true
+        wait "${INITIATOR_LOCK_PID}" >/dev/null 2>&1 || true
+    fi
+    if [ -n "${TARGET_LOCK_PID}" ]; then
+        kill "${TARGET_LOCK_PID}" >/dev/null 2>&1 || true
+        wait "${TARGET_LOCK_PID}" >/dev/null 2>&1 || true
+    fi
+
+    if [ "${rc}" -ne 0 ]; then
+        print_logs
+    fi
+    exit "${rc}"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+wait_for_lock() {
+    local log_file="$1"
+    local process_id="$2"
+    local node_name="$3"
+    local attempt=0
+    for ((attempt = 1; attempt <= LOCK_TIMEOUT + 10; attempt++)); do
+        if grep -q '^LOCK_ACQUIRED$' "${log_file}"; then
+            return 0
+        fi
+        if ! kill -0 "${process_id}" 2>/dev/null; then
+            echo "ERROR: failed to acquire the cross-node test lock on ${node_name}" >&2
+            return 1
+        fi
+        sleep 1
+    done
+    echo "ERROR: timed out waiting for the cross-node test lock on ${node_name}" >&2
+    return 1
+}
+
+echo "Target:    ${TARGET_HOST}"
+echo "Initiator: ${INITIATOR_HOST}"
+echo "Image:     ${TEST_IMAGE}"
+
+echo "Acquiring the cross-node test lock on ${TARGET_HOST}..."
+PARENT_PID="$$"
+(
+    exec 9>"${LOCK_FILE}"
+    if ! flock -w "${LOCK_TIMEOUT}" 9; then
+        echo "ERROR: lock wait timed out"
+        exit 75
+    fi
+    echo "LOCK_ACQUIRED"
+    while kill -0 "${PARENT_PID}" 2>/dev/null; do sleep 5; done
+) >"${TARGET_LOCK_LOG}" 2>&1 &
+TARGET_LOCK_PID=$!
+wait_for_lock "${TARGET_LOCK_LOG}" "${TARGET_LOCK_PID}" "${TARGET_HOST}"
+
+echo "Acquiring the cross-node test lock on ${INITIATOR_HOST}..."
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- "${LOCK_FILE}" "${LOCK_TIMEOUT}" \
+    >"${INITIATOR_LOCK_LOG}" 2>&1 <<'REMOTE_LOCK' &
+set -Eeuo pipefail
+lock_file="$1"
+lock_timeout="$2"
+session_parent="$PPID"
+command -v flock >/dev/null
+exec 9>"${lock_file}"
+if ! flock -w "${lock_timeout}" 9; then
+    echo "ERROR: lock wait timed out"
+    exit 75
+fi
+echo "LOCK_ACQUIRED"
+while kill -0 "${session_parent}" 2>/dev/null; do sleep 5; done
+REMOTE_LOCK
+INITIATOR_LOCK_PID=$!
+wait_for_lock "${INITIATOR_LOCK_LOG}" "${INITIATOR_LOCK_PID}" "${INITIATOR_HOST}"
+echo "Cross-node test locks acquired."
+
+echo "Copying the wheel and test scripts to ${INITIATOR_HOST}..."
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" mkdir -p "${REMOTE_WORK_DIR}"
+scp "${SCP_OPTIONS[@]}" "${WHEEL_PATH}" "${SELF_PATH}" \
+    "${REMOTE}:${REMOTE_WORK_DIR}/"
+
+echo "Creating target container ${TARGET_CONTAINER} on ${TARGET_HOST}..."
+docker run -d \
+    --name "${TARGET_CONTAINER}" \
+    --network host \
+    --privileged \
+    --volume "${WHEEL_PATH}:/work/${WHEEL_BASENAME}:ro" \
+    --volume "${SELF_PATH}:/work/test_transfer_engine_cross_node.sh:ro" \
+    "${DOCKER_ENV_ARGS[@]}" \
+    -e "TARGET_FILTER=${TARGET_FILTER}" \
+    --entrypoint /bin/bash \
+    "${TEST_IMAGE}" \
+    -lc 'exec sleep infinity' >/dev/null
+
+echo "Creating initiator container ${INITIATOR_CONTAINER} on ${INITIATOR_HOST}..."
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- \
+    "${REMOTE_WORK_DIR}" "${WHEEL_BASENAME}" "$(basename "${SELF_PATH}")" \
+    "${INITIATOR_CONTAINER}" "${TEST_IMAGE}" "${DTK_PKG_URL}" \
+    "${PIP_INDEX_URL}" <<'REMOTE_START' >/dev/null
+set -Eeuo pipefail
+remote_dir="$1"
+wheel_basename="$2"
+script_basename="$3"
+container_name="$4"
+image="$5"
+dtk_pkg_url="$6"
+pip_index_url="$7"
+
+docker_env_args=(-e "DTK_PKG_URL=${dtk_pkg_url}")
+[ -n "${pip_index_url}" ] && docker_env_args+=(-e "PIP_INDEX_URL=${pip_index_url}")
+
+docker run -d \
+    --name "${container_name}" \
+    --network host \
+    --privileged \
+    --volume "${remote_dir}/${wheel_basename}:/work/${wheel_basename}:ro" \
+    --volume "${remote_dir}/${script_basename}:/work/test_transfer_engine_cross_node.sh:ro" \
+    "${docker_env_args[@]}" \
+    --entrypoint /bin/bash \
+    "${image}" \
+    -lc 'exec sleep infinity'
+REMOTE_START
+
+echo "Preparing DTK and wheel on ${TARGET_HOST} and ${INITIATOR_HOST} in parallel..."
+timeout "${SETUP_TIMEOUT}" docker exec "${TARGET_CONTAINER}" \
+    /bin/bash /work/test_transfer_engine_cross_node.sh \
+    __container_prepare "/work/${WHEEL_BASENAME}" \
+    >"${TARGET_LOG}" 2>&1 &
+TARGET_PREP_PID=$!
+
+ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- \
+    "${INITIATOR_CONTAINER}" "${WHEEL_BASENAME}" "${SETUP_TIMEOUT}" \
+    >"${INITIATOR_LOG}" 2>&1 <<'REMOTE_PREPARE' &
+set -Eeuo pipefail
+container_name="$1"
+wheel_basename="$2"
+setup_timeout="$3"
+timeout "${setup_timeout}" docker exec "${container_name}" \
+    /bin/bash /work/test_transfer_engine_cross_node.sh \
+    __container_prepare "/work/${wheel_basename}"
+REMOTE_PREPARE
+INITIATOR_PREP_PID=$!
+
+set +e
+wait "${TARGET_PREP_PID}"
+TARGET_PREP_RC=$?
+wait "${INITIATOR_PREP_PID}"
+INITIATOR_PREP_RC=$?
+set -e
+
+if [ "${TARGET_PREP_RC}" -ne 0 ] || [ "${INITIATOR_PREP_RC}" -ne 0 ]; then
+    echo "ERROR: environment preparation failed (target=${TARGET_PREP_RC}, initiator=${INITIATOR_PREP_RC})" >&2
+    exit 1
+fi
+echo "Both test containers are ready."
+
+echo "Starting target service on ${TARGET_HOST}..."
+docker exec -e "TARGET_FILTER=${TARGET_FILTER}" "${TARGET_CONTAINER}" \
+    /bin/bash /work/test_transfer_engine_cross_node.sh \
+    __container_target "${TARGET_IP}" \
+    >>"${TARGET_LOG}" 2>&1 &
+TARGET_PROCESS_PID=$!
+
+TARGET_PORT=""
+for ((attempt = 1; attempt <= READY_TIMEOUT; attempt++)); do
+    TARGET_PORT="$(
+        sed -nE 's/.*Transfer Engine RPC using .*, listening on [^:[:space:]]+:([0-9]+).*/\1/p' \
+            "${TARGET_LOG}" | tail -n 1
+    )"
+    if [ -n "${TARGET_PORT}" ]; then
+        break
+    fi
+    if ! kill -0 "${TARGET_PROCESS_PID}" 2>/dev/null; then
+        echo "ERROR: target service exited before publishing its RPC port" >&2
+        exit 1
+    fi
+    sleep 1
+done
+
+if [ -z "${TARGET_PORT}" ]; then
+    echo "ERROR: target did not publish an RPC port within ${READY_TIMEOUT}s" >&2
+    exit 1
+fi
+echo "Target endpoint: ${TARGET_HOST}:${TARGET_PORT}"
+sleep "${SETTLE_SECONDS}"
+
+if ! kill -0 "${TARGET_PROCESS_PID}" 2>/dev/null; then
+    echo "ERROR: target service exited during initialization" >&2
+    exit 1
+fi
+
+for operation in read write; do
+    echo "Starting ${operation} initiator on ${INITIATOR_HOST}..."
+    if ! ssh "${SSH_OPTIONS[@]}" "${REMOTE}" bash -s -- \
+        "${INITIATOR_CONTAINER}" "${INITIATOR_IP}" "${TARGET_IP}" \
+        "${TARGET_PORT}" "${operation}" "${INITIATOR_FILTER}" "${RUN_TIMEOUT}" \
+        >>"${INITIATOR_LOG}" 2>&1 <<'REMOTE_TEST'; then
+set -Eeuo pipefail
+container_name="$1"
+initiator_ip="$2"
+target_ip="$3"
+target_port="$4"
+operation="$5"
+initiator_filter="$6"
+run_timeout="$7"
+
+timeout "${run_timeout}" docker exec "${container_name}" \
+    /bin/bash /work/test_transfer_engine_cross_node.sh \
+    __container_initiator "${initiator_ip}" "${target_ip}" "${target_port}" \
+    "${operation}" "${initiator_filter}"
+REMOTE_TEST
+        echo "ERROR: ${operation} initiator failed" >&2
+        exit 1
+    fi
+done
+
+if ! kill -0 "${TARGET_PROCESS_PID}" 2>/dev/null; then
+    echo "ERROR: target service exited unexpectedly during the test" >&2
+    exit 1
+fi
+
+SUCCESS_COUNT="$(grep -c 'Test completed:' "${INITIATOR_LOG}" || true)"
+if [ "${SUCCESS_COUNT}" -ne 2 ]; then
+    echo "ERROR: expected two successful read/write completions, found ${SUCCESS_COUNT}" >&2
+    exit 1
+fi
+
+echo "Cross-node RDMA read/write tests passed:"
+grep 'Test completed:' "${INITIATOR_LOG}"
+
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    {
+        echo "### Transfer Engine cross-node test"
+        echo
+        echo "- Read/write result: passed"
+        echo
+        echo '```text'
+        grep 'Test completed:' "${INITIATOR_LOG}"
+        echo '```'
+    } >>"${GITHUB_STEP_SUMMARY}"
+fi
diff --git a/scripts/run_tests.sh b/scripts/run_tests.sh
index 3c89735870..8e61dc6827 100755
--- a/scripts/run_tests.sh
+++ b/scripts/run_tests.sh
@@ -138,6 +138,12 @@ MASTER_PID=$!
 sleep 1
 MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_distributed_object_store.py
 MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_replicated_distributed_object_store.py
+
+pip install torch numpy safetensors packaging
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_put_get_tensor.py
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_tensor_read_snapshot.py
+python test_cuda_fabric_compat.py
+MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_safetensor_functions.py
 sleep 1
 mooncake_client &
 CLIENT_PID=$!
@@ -149,14 +155,6 @@ MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 pytho
 DUMMY_TEST_PID_2=$!
 wait $DUMMY_TEST_PID_1 $DUMMY_TEST_PID_2
 kill $CLIENT_PID || true
-
-pip install numpy safetensors packaging
-# Keep the test torch aligned with the EP/PG variants packaged into the CI wheel.
-pip install "${MOONCAKE_TEST_TORCH_SPEC:-torch==2.11.0+cu128}" \
-    --index-url "${MOONCAKE_TEST_TORCH_INDEX_URL:-https://download.pytorch.org/whl/cu128}" \
-    --extra-index-url https://pypi.org/simple
-MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_put_get_tensor.py
-MC_METADATA_SERVER=http://127.0.0.1:8080/metadata DEFAULT_KV_LEASE_TTL=500 python test_safetensor_functions.py
 kill $MASTER_PID || true
 wait $MASTER_PID 2>/dev/null || true
 
@@ -189,21 +187,30 @@ if [ -n "$TEST_PROMOTION_ON_HIT" ]; then
     # deterministic. --root_fs_dir is required so the master returns a non-
     # empty fsdir from GetStorageConfig, which is the trigger that initializes
     # the client's FileStorage (and therefore the offload heartbeat).
+    # promotion_max_per_heartbeat=16 raises the delivery cap so a burst of
+    # admissions (the phase-2 batch query promotes every LOCAL_DISK-only key)
+    # drains within the test's wait window instead of starving individual keys
+    # at the default 1-per-heartbeat.
     mooncake_master \
         --default_kv_lease_ttl=500 \
         --root_fs_dir=$TEST_ROOT_DIR \
         --enable_offload=true \
         --offload_on_evict=true \
         --promotion_on_hit=true \
-        --promotion_admission_threshold=1 &
+        --promotion_admission_threshold=1 \
+        --promotion_max_per_heartbeat=16 &
     MASTER_PID=$!
     sleep 1
     # Lower bucket-flush thresholds so the test workload (~64 MB) actually
     # writes to disk rather than sitting in the bucket backend's ungrouped
-    # pool until the default 500-key / 256-MB bucket fills.
+    # pool until the default 500-key / 256-MB bucket fills. The 2s offload
+    # heartbeat (default 10s) pins the master/client clock phase so offload
+    # draining and promotion delivery complete well inside the test's wait
+    # windows.
     MC_METADATA_SERVER=http://127.0.0.1:8080/metadata \
         DEFAULT_KV_LEASE_TTL=500 \
         MOONCAKE_OFFLOAD_FILE_STORAGE_PATH=$TEST_ROOT_DIR \
+        MOONCAKE_OFFLOAD_HEARTBEAT_INTERVAL_SECONDS=2 \
         MOONCAKE_OFFLOAD_BUCKET_KEYS_LIMIT=10 \
         MOONCAKE_OFFLOAD_BUCKET_SIZE_LIMIT_BYTES=10485760 \
         python test_promotion_on_hit.py
@@ -236,7 +243,7 @@ else
 fi
 
 echo "Running CLI entry point tests..."
-python test_cli.py
+python ../../python/tests/integration/test_cli.py
 
 ENABLE_EMBEDDED_METADATA_SERVER=true
 if [ "$RUN_TESTS_METADATA_SERVER_MODE" = "managed" ]; then
diff --git a/scripts/test_engram_store.py b/scripts/test_engram_store.py
index 759fcd7f34..095ead2b77 100755
--- a/scripts/test_engram_store.py
+++ b/scripts/test_engram_store.py
@@ -5,7 +5,7 @@
 This suite validates:
 1. metadata-only construction and store-backed construction
 2. populate / lookup / remove on the simplified Store interface
-3. Python-list and NumPy row-id lookup paths
+3. caller-owned registered output buffers and strict NumPy inputs
 4. error handling and cleanup behavior
 """
 
@@ -21,6 +21,7 @@
 import urllib.error
 import urllib.request
 import uuid
+from contextlib import contextmanager
 from pathlib import Path
 
 import numpy as np
@@ -35,7 +36,7 @@
     if path.is_dir() and str(path) not in sys.path:
         sys.path.insert(0, str(path))
 
-from mooncake.mooncake_config import MooncakeConfig
+from mooncake.mooncake_config import MooncakeConfig  # noqa: E402
 
 GLOBAL_STORE = None
 STORE_MODULE = None
@@ -256,14 +257,15 @@ def setUp(self):
     def tearDown(self):
         for engram_store in reversed(self._created_engram_stores):
             try:
-                engram_store.remove_from_store(force=True)
+                for layer_id in engram_store.get_layer_ids():
+                    engram_store.remove_from_store(layer_id, force=True)
             except Exception as exc:
                 print(f"Warning: failed to clean up EngramStore test layer: {exc}")
 
     def create_config(self):
         cfg = self.EngramStoreConfig()
         cfg.table_vocab_sizes = [17, 19, 23, 29]
-        cfg.embedding_dim = 8
+        cfg.row_bytes = 32
         return cfg
 
     def create_engram_store(self, layer_id=None, store_marker=Ellipsis):
@@ -272,50 +274,118 @@ def create_engram_store(self, layer_id=None, store_marker=Ellipsis):
             self._next_layer_id += 1
 
         cfg = self.create_config()
+        self.layer_id = layer_id
         if store_marker is Ellipsis:
-            engram_store = self.EngramStore(layer_id=layer_id, config=cfg, store=self.store)
+            engram_store = self.EngramStore(layers={layer_id: cfg}, store=self.store)
             self._created_engram_stores.append(engram_store)
         elif store_marker is None:
-            engram_store = self.EngramStore(layer_id=layer_id, config=cfg)
+            engram_store = self.EngramStore(layers={layer_id: cfg})
         else:
-            engram_store = self.EngramStore(layer_id=layer_id, config=cfg, store=store_marker)
+            engram_store = self.EngramStore(layers={layer_id: cfg}, store=store_marker)
             self._created_engram_stores.append(engram_store)
         return cfg, engram_store
 
     def make_embedding_tables(self, engram_store):
-        embed_dim = engram_store.get_embedding_dim()
+        row_bytes = engram_store.get_row_bytes(self.layer_id)
         tables = []
-        for head_idx, vocab_size in enumerate(engram_store.get_table_vocab_sizes()):
-            base = np.arange(vocab_size * embed_dim, dtype=np.float32).reshape(
-                vocab_size, embed_dim
+        for head_idx, vocab_size in enumerate(
+            engram_store.get_table_vocab_sizes(self.layer_id)
+        ):
+            base = np.arange(vocab_size * row_bytes, dtype=np.int64).reshape(
+                vocab_size, row_bytes
             )
-            tables.append(base + head_idx * 1000)
+            tables.append((base + head_idx * 37).astype(np.uint8))
         return tables
 
     def populate_store(self, engram_store):
         tables = self.make_embedding_tables(engram_store)
-        engram_store.populate(tables)
+        engram_store.populate(self.layer_id, tables)
         return tables
 
+    @contextmanager
+    def registered_output(self, table, shape, layer_id=None):
+        layer_id = self.layer_id if layer_id is None else layer_id
+        output = np.empty((*shape, table.get_row_bytes(layer_id)), dtype=np.uint8)
+        if output.nbytes:
+            self.assertEqual(
+                self.store.register_buffer(output.ctypes.data, output.nbytes), 0
+            )
+        try:
+            yield output
+        finally:
+            if output.nbytes:
+                self.assertEqual(self.store.unregister_buffer(output.ctypes.data), 0)
+
+    def read_rows(self, table, row_ids):
+        ids = np.asarray(row_ids, dtype=np.int64)
+        with self.registered_output(table, ids.shape) as output:
+            table.lookup_into(self.layer_id, ids, output)
+        return output
+
 
 class TestEngramStoreMetadata(EngramStoreTestBase):
+    def test_local_tables_lifetime_and_bounds(self):
+        import gc
+        import weakref
+
+        cfg = self.create_config()
+        cfg.row_bytes = 264
+        table = self.EngramStore({1: cfg, 14: cfg})
+        arrays = [
+            np.arange(n * 264, dtype=np.uint32).astype(np.uint8).reshape(n, 264)
+            for n in cfg.table_vocab_sizes
+        ]
+        expected = np.stack([a[-1].copy() for a in arrays])
+        refs = [weakref.ref(a) for a in arrays]
+        for a in arrays:
+            a.flags.writeable = False
+        table.bind_local(1, arrays)
+        del arrays, a
+        gc.collect()
+        assert all(ref() is not None for ref in refs)
+        ids = (np.array(cfg.table_vocab_sizes, dtype=np.int64) - 1)[None, None]
+        output = np.empty((1, 1, len(cfg.table_vocab_sizes), 264), dtype=np.uint8)
+        table.lookup_into(1, ids, output)  # No Store or registered output.
+        np.testing.assert_array_equal(output[0, 0], expected)
+        with self.assertRaises(RuntimeError):
+            table.lookup_into(14, ids, output)
+        ids[0, 0, 0] += 1
+        with self.assertRaises(RuntimeError):
+            table.lookup_into(1, ids, output)
+        assert not output.any()
+        del table
+        gc.collect()
+        assert all(ref() is None for ref in refs)
+
     def test_creation_and_metadata(self):
         cfg, engram_store = self.create_engram_store()
-        self.assertEqual(engram_store.get_num_heads(), len(cfg.table_vocab_sizes))
-        self.assertEqual(engram_store.get_embedding_dim(), cfg.embedding_dim)
-        self.assertEqual(engram_store.get_table_vocab_sizes(), cfg.table_vocab_sizes)
-        self.assertEqual(len(engram_store.get_store_keys()), len(cfg.table_vocab_sizes))
+        self.assertEqual(
+            engram_store.get_num_heads(self.layer_id), len(cfg.table_vocab_sizes)
+        )
+        self.assertEqual(engram_store.get_row_bytes(self.layer_id), cfg.row_bytes)
+        self.assertEqual(
+            engram_store.get_table_vocab_sizes(self.layer_id), cfg.table_vocab_sizes
+        )
+        self.assertEqual(
+            len(engram_store.get_store_keys(self.layer_id)), len(cfg.table_vocab_sizes)
+        )
 
     def test_creation_without_store_keeps_metadata_accessible(self):
         layer_id = self._next_layer_id
-        cfg, engram_store = self.create_engram_store(layer_id=layer_id, store_marker=None)
-        self.assertEqual(engram_store.get_num_heads(), len(cfg.table_vocab_sizes))
-        self.assertEqual(engram_store.get_embedding_dim(), cfg.embedding_dim)
-        self.assertEqual(engram_store.get_store_keys()[0], f"engram:l{layer_id}:h0")
+        cfg, engram_store = self.create_engram_store(
+            layer_id=layer_id, store_marker=None
+        )
+        self.assertEqual(
+            engram_store.get_num_heads(self.layer_id), len(cfg.table_vocab_sizes)
+        )
+        self.assertEqual(engram_store.get_row_bytes(self.layer_id), cfg.row_bytes)
+        self.assertEqual(
+            engram_store.get_store_keys(self.layer_id)[0], f"engram:l{layer_id}:h0"
+        )
 
 
 class TestStorePopulateAndLookup(EngramStoreTestBase):
-    def test_populate_and_lookup_shape_with_python_lists(self):
+    def test_populate_and_lookup_batch_shape(self):
         _, engram_store = self.create_engram_store()
         self.populate_store(engram_store)
 
@@ -323,17 +393,16 @@ def test_populate_and_lookup_shape_with_python_lists(self):
             [[0, 1, 2, 3], [4, 5, 6, 7]],
             [[1, 2, 3, 4], [8, 9, 10, 11]],
         ]
-        output = engram_store.lookup(row_ids)
+        output = self.read_rows(engram_store, row_ids)
 
         expected_shape = (
             len(row_ids),
             len(row_ids[0]),
-            engram_store.get_num_heads(),
-            engram_store.get_embedding_dim(),
+            engram_store.get_num_heads(self.layer_id),
+            engram_store.get_row_bytes(self.layer_id),
         )
         self.assertEqual(output.shape, expected_shape)
-        self.assertFalse(np.any(np.isnan(output)))
-        self.assertFalse(np.any(np.isinf(output)))
+        self.assertEqual(output.dtype, np.uint8)
 
     def test_lookup_matches_stored_rows_from_numpy_ids(self):
         _, engram_store = self.create_engram_store()
@@ -342,38 +411,35 @@ def test_lookup_matches_stored_rows_from_numpy_ids(self):
         row_ids = np.array(
             [[[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11]]], dtype=np.int64
         )
-        output = np.asarray(engram_store.lookup(row_ids))
+        output = np.asarray(self.read_rows(engram_store, row_ids))
 
         for pos in range(row_ids.shape[1]):
-            for head in range(engram_store.get_num_heads()):
+            for head in range(engram_store.get_num_heads(self.layer_id)):
                 idx = row_ids[0, pos, head]
-                np.testing.assert_allclose(output[0, pos, head], tables[head][idx])
-
-    def test_lookup_list_and_numpy_paths_match(self):
-        _, engram_store = self.create_engram_store()
-        self.populate_store(engram_store)
-
-        row_ids_list = [
-            [[0, 1, 2, 3], [4, 5, 6, 7]],
-            [[1, 2, 3, 4], [8, 9, 10, 11]],
-        ]
-        row_ids_numpy = np.asarray(row_ids_list, dtype=np.int64)
-
-        output_from_list = np.asarray(engram_store.lookup(row_ids_list))
-        output_from_numpy = np.asarray(engram_store.lookup(row_ids_numpy))
-        np.testing.assert_allclose(output_from_list, output_from_numpy)
+                np.testing.assert_array_equal(output[0, pos, head], tables[head][idx])
+
+    def test_lookup_rejects_implicit_input_conversion(self):
+        _, table = self.create_engram_store()
+        self.populate_store(table)
+        ids = np.zeros((1, 2, table.get_num_heads(self.layer_id)), dtype=np.int64)
+        with self.registered_output(table, ids.shape) as output:
+            for bad_ids in (ids.tolist(), ids.astype(np.int32), ids[..., ::-1]):
+                with self.subTest(input_type=type(bad_ids)), self.assertRaises(
+                    TypeError
+                ):
+                    table.lookup_into(self.layer_id, bad_ids, output)
 
     def test_remove_from_store(self):
         _, engram_store = self.create_engram_store()
         self.populate_store(engram_store)
 
-        removed = engram_store.remove_from_store(force=True)
-        self.assertEqual(removed, engram_store.get_num_heads())
+        removed = engram_store.remove_from_store(self.layer_id, force=True)
+        self.assertEqual(removed, engram_store.get_num_heads(self.layer_id))
 
-        for key in engram_store.get_store_keys():
+        for key in engram_store.get_store_keys(self.layer_id):
             self.assertEqual(self.store.is_exist(key), 0)
 
-        self.assertEqual(engram_store.remove_from_store(force=True), 0)
+        self.assertEqual(engram_store.remove_from_store(self.layer_id, force=True), 0)
 
 
 class TestErrorHandling(EngramStoreTestBase):
@@ -381,38 +447,172 @@ def test_populate_rejects_reusing_existing_layer_keys(self):
         _, engram_store = self.create_engram_store()
         self.populate_store(engram_store)
         with self.assertRaises(Exception):
-            engram_store.populate(self.make_embedding_tables(engram_store))
+            engram_store.populate(
+                self.layer_id, self.make_embedding_tables(engram_store)
+            )
 
     def test_lookup_rejects_missing_tables(self):
         _, engram_store = self.create_engram_store()
         with self.assertRaises(Exception):
-            engram_store.lookup([[[0, 1, 2, 3]]])
+            self.read_rows(engram_store, [[[0, 1, 2, 3]]])
 
     def test_populate_rejects_wrong_table_shape(self):
         _, engram_store = self.create_engram_store()
         tables = self.make_embedding_tables(engram_store)
         tables[0] = tables[0][:-1]
         with self.assertRaises(Exception):
-            engram_store.populate(tables)
+            engram_store.populate(self.layer_id, tables)
 
-    def test_lookup_rejects_empty_input(self):
-        _, engram_store = self.create_engram_store()
-        self.populate_store(engram_store)
-        with self.assertRaises(Exception):
-            engram_store.lookup([])
+    def test_lookup_empty_batch_is_noop(self):
+        _, table = self.create_engram_store()
+        ids = np.empty((1, 0, table.get_num_heads(self.layer_id)), dtype=np.int64)
+        output = np.empty(
+            (*ids.shape, table.get_row_bytes(self.layer_id)), dtype=np.uint8
+        )
+        self.assertIsNone(table.lookup_into(self.layer_id, ids, output))
 
     def test_lookup_rejects_wrong_head_dimension(self):
         _, engram_store = self.create_engram_store()
         self.populate_store(engram_store)
-        row_ids = np.zeros((1, 1, engram_store.get_num_heads() - 1), dtype=np.int64)
+        row_ids = np.zeros(
+            (1, 1, engram_store.get_num_heads(self.layer_id) - 1), dtype=np.int64
+        )
         with self.assertRaises(Exception):
-            engram_store.lookup(row_ids)
+            self.read_rows(engram_store, row_ids)
 
     def test_lookup_rejects_out_of_range_row_id(self):
         _, engram_store = self.create_engram_store()
         self.populate_store(engram_store)
         with self.assertRaises(Exception):
-            engram_store.lookup([[[999, 1, 2, 3]]])
+            self.read_rows(engram_store, [[[999, 1, 2, 3]]])
+
+
+class TestByteRows(EngramStoreTestBase):
+    def create_config(self):
+        cfg = super().create_config()
+        cfg.row_bytes = 264
+        return cfg
+
+    def test_lookup_and_registered_output(self):
+        cfg, table = self.create_engram_store()
+        buffers = [
+            np.arange(n * cfg.row_bytes, dtype=np.int64).astype(np.uint8).reshape(n, -1)
+            for n in cfg.table_vocab_sizes
+        ]
+        replica = STORE_MODULE.ReplicateConfig()
+        replica.with_hard_pin = True
+        table.populate(self.layer_id, buffers, replica)
+        ids = np.array([[[0, 1, 2, 3], [16, 18, 22, 28], [0, 1, 2, 3]]], dtype=np.int64)
+        expected = np.stack([buffers[h][ids[..., h]] for h in range(4)], axis=2)
+        with self.registered_output(table, ids.shape) as output:
+            for _ in range(3):
+                output.fill(99)
+                self.assertIsNone(table.lookup_into(self.layer_id, ids, output))
+                np.testing.assert_array_equal(output, expected)
+            bad_ids = ids.copy()
+            bad_ids[0, 0, 0] = -1
+            with self.assertRaises(RuntimeError):
+                table.lookup_into(self.layer_id, bad_ids, output)
+            self.assertFalse(output.any())
+            # Failed reads must also preserve the caller's registration.
+            table.lookup_into(self.layer_id, ids, output)
+            np.testing.assert_array_equal(output, expected)
+            with self.assertRaises(RuntimeError):
+                table.lookup_into(self.layer_id, ids, output[..., ::-1])
+            with self.assertRaises(RuntimeError):
+                table.lookup_into(self.layer_id, ids, output.astype(np.float32))
+            with self.assertRaises(RuntimeError):
+                table.lookup_into(self.layer_id, ids, output[..., :-1])
+            output.setflags(write=False)
+            with self.assertRaises(RuntimeError):
+                table.lookup_into(self.layer_id, ids, output)
+
+    def test_populate_does_not_cast(self):
+        cfg, table = self.create_engram_store()
+        buffers = [
+            np.zeros((n, cfg.row_bytes), dtype=np.float32)
+            for n in cfg.table_vocab_sizes
+        ]
+        with self.assertRaises(RuntimeError):
+            table.populate(self.layer_id, buffers)
+        buffers = [
+            np.zeros((n, cfg.row_bytes * 2), dtype=np.uint8)[:, ::2]
+            for n in cfg.table_vocab_sizes
+        ]
+        with self.assertRaises(RuntimeError):
+            table.populate(self.layer_id, buffers)
+
+    def test_row_size_validation(self):
+        cfg = self.create_config()
+        for row_bytes in (0, -1):
+            with self.subTest(row_bytes=row_bytes):
+                cfg.row_bytes = row_bytes
+                with self.assertRaises(ValueError):
+                    self.EngramStore({1: cfg})
+        cfg.row_bytes = 264
+        cfg.table_vocab_sizes = [2**63 - 1]
+        with self.assertRaises(ValueError):
+            self.EngramStore({1: cfg})
+
+
+class TestMultipleLayers(EngramStoreTestBase):
+    def test_layer_isolation_and_shared_backend(self):
+        first, second = self._next_layer_id, self._next_layer_id + 1
+        cfg1 = self.create_config()
+        cfg2 = self.EngramStoreConfig()
+        cfg2.table_vocab_sizes = [7, 11]
+        cfg2.row_bytes = 264
+        configs = {first: cfg1, second: cfg2}
+        table = self.EngramStore(configs, self.store)
+        self._created_engram_stores.append(table)
+        self.assertEqual(table.get_layer_ids(), [first, second])
+        for layer_id, cfg in configs.items():
+            arrays = [
+                np.full(
+                    (n, cfg.row_bytes), h + 31 + (layer_id - first) * 50, dtype=np.uint8
+                )
+                for h, n in enumerate(cfg.table_vocab_sizes)
+            ]
+            table.populate(layer_id, arrays)
+        # A second handle reads the same keys without populating another copy.
+        peer = self.EngramStore(configs, self.store)
+        for layer_id, cfg in configs.items():
+            self.assertEqual(
+                table.get_store_keys(layer_id), peer.get_store_keys(layer_id)
+            )
+            ids = np.zeros((1, 2, len(cfg.table_vocab_sizes)), dtype=np.int64)
+            with self.registered_output(table, ids.shape, layer_id) as output:
+                for reader in (table, peer):
+                    reader.lookup_into(layer_id, ids, output)
+                    for h in range(ids.shape[-1]):
+                        self.assertTrue(
+                            np.all(
+                                output[..., h, :] == h + 31 + (layer_id - first) * 50
+                            )
+                        )
+        table.remove_from_store(first, force=True)
+        ids = np.zeros((1, 1, 2), dtype=np.int64)
+        with self.registered_output(table, ids.shape, second) as output:
+            peer.lookup_into(second, ids, output)
+            self.assertTrue(np.all(output[..., 0, :] == 81))
+            with self.assertRaisesRegex(ValueError, "Unknown Engram layer"):
+                table.lookup_into(second + 1, ids, output)
+            self.assertTrue(np.all(output[..., 0, :] == 81))
+        for operation in (
+            table.get_store_keys,
+            table.get_row_bytes,
+            table.remove_from_store,
+        ):
+            with self.assertRaisesRegex(ValueError, "Unknown Engram layer"):
+                operation(second + 1)
+        with self.assertRaisesRegex(ValueError, "Unknown Engram layer"):
+            table.populate(second + 1, [])
+
+    def test_invalid_layer_configuration(self):
+        with self.assertRaises(ValueError):
+            self.EngramStore({})
+        with self.assertRaises(ValueError):
+            self.EngramStore({-1: self.create_config()})
 
 
 if __name__ == "__main__":
diff --git a/scripts/test_installation.sh b/scripts/test_installation.sh
index 68cfd181d6..04a9798efa 100755
--- a/scripts/test_installation.sh
+++ b/scripts/test_installation.sh
@@ -32,18 +32,27 @@ sudo apt-get install -y $SYSTEM_PACKAGES
 
 echo "Verifying that import succeeds after installation..."
 python -c "import mooncake.engine" && echo "Success: Import succeeded after installation" || { echo "ERROR: Import failed after installation!"; exit 1; }
+python -c "import mooncake.reshard.weight" && echo "Success: Reshard import succeeded after installation" || { echo "ERROR: Reshard import failed after installation!"; exit 1; }
+python -c "import mooncake.cli, mooncake.cli_bench, mooncake.cli_client, mooncake.transfer_engine_topology_dump" && echo "Success: CLI imports succeeded after installation" || { echo "ERROR: CLI imports failed after installation!"; exit 1; }
 
 echo "Running import structure test..."
 # Run the import structure test
 cp -r mooncake-wheel/tests test_env/
+cp -r python/tests/unit test_env/unit_tests
+cp -r mooncake-reshard/tests test_env/reshard_tests
+cp -r python/tests/ssd test_env/ssd_tests
 cd test_env
-pip install torch==2.11.0 numpy
+pip install torch numpy
 python -c "import mooncake._fast_copy"
 python tests/test_fast_copy.py
 python tests/test_import_structure.py
 
 echo "Running mooncake config test..."
-python tests/test_mooncake_config.py
+python unit_tests/test_mooncake_config.py
+
+echo "Running reshard contract tests..."
+python -m pip install pytest hypothesis==6.141.0 paramiko
+python -m pytest reshard_tests ssd_tests -q
 
 echo "Verifying mooncake_master entry point..."
 # Check if the mooncake_master entry point is installed and executable
@@ -60,6 +69,11 @@ echo "Verifying transfer_engine_bench entry point..."
 which transfer_engine_bench || { echo "ERROR: transfer_engine_bench entry point not found!"; exit 1; }
 echo "Success: transfer_engine_bench entry point found"
 
+echo "Verifying transfer_engine_topology_dump entry point..."
+transfer_engine_topology_dump --help >/dev/null
+python -m mooncake.transfer_engine_topology_dump --help >/dev/null
+echo "Success: transfer_engine_topology_dump entry point and module execution work"
+
 cd ..
 
 echo "Installation test completed successfully!"
diff --git a/scripts/test_tensor_api.py b/scripts/test_tensor_api.py
deleted file mode 100644
index 8a9e260594..0000000000
--- a/scripts/test_tensor_api.py
+++ /dev/null
@@ -1,2774 +0,0 @@
-import ctypes
-import os
-import sys
-import time
-import argparse
-import unittest
-import torch
-import numpy as np
-from dataclasses import dataclass
-import mooncake.store as mooncake_store
-from mooncake.store import MooncakeDistributedStore
-from mooncake.store import ReplicateConfig
-
-from mooncake.mooncake_config import MooncakeConfig
-
-import concurrent.futures
-
-
-@dataclass
-class WriterPartition:
-    rank: int
-    size: int
-    split_dim: int
-
-
-# ==========================================
-#  Global Variables & Configuration
-# ==========================================
-
-# Global Store instance to ensure only one connection is established during the entire test session
-GLOBAL_STORE = None
-GLOBAL_CONFIG = None
-
-DEFAULT_MOONCAKE_CONFIG_PATH_ENV = "MOONCAKE_CONFIG_PATH"
-DEFAULT_GLOBAL_SEGMENT_SIZE = 16 * 1024 * 1024 * 1024  # 16 GiB
-DEFAULT_LOCAL_BUFFER_SIZE = 8 * 1024 * 1024 * 1024    # 8 GB
-DEFAULT_MASTER_METRICS_PORT = 9003
-DEFAULT_CHECK_SERVER = False
-
-# Must match current C++ TensorMetadata layout.
-# TensorObjectHeader (40) + TensorLayoutMetadata (264) = 304 bytes.
-TENSOR_METADATA_SIZE = 304
-
-
-def serialized_tensor_size(tensor):
-    """Size in bytes of [TensorObjectHeader+layout metadata][tensor data]."""
-    return TENSOR_METADATA_SIZE + tensor.numel() * tensor.element_size()
-
-def verify_tensor_equality(original, received, rtol=0, atol=0, verbose=True):
-    """
-    compare two tensors.
-    """
-    def to_numpy(x):
-        if isinstance(x, torch.Tensor):
-            if x.is_cuda:
-                x = x.cpu()
-            return x.detach().numpy()
-        elif isinstance(x, np.ndarray):
-            return x
-        else:
-            raise TypeError(f"Unsupported tensor type: {type(x)}")
-
-    try:
-        orig_np = to_numpy(original)
-        recv_np = to_numpy(received)
-    except Exception as e:
-        if verbose:
-            print(f"❌ Error converting tensors: {e}")
-        return False
-
-    if orig_np.shape != recv_np.shape:
-        if verbose:
-            print(f"❌ Shape mismatch: original {orig_np.shape} vs received {recv_np.shape}")
-        return False
-
-    if orig_np.dtype != recv_np.dtype:
-        if verbose:
-            print(f"❌ Dtype mismatch: original {orig_np.dtype} vs received {recv_np.dtype}")
-        return False
-
-    if np.array_equal(orig_np, recv_np):
-#        if verbose:
-#            print("✅ Tensors are identical!")
-        return True
-    else:
-        diff_mask = orig_np != recv_np
-        diff_indices = np.where(diff_mask)
-        if len(diff_indices[0]) > 0:
-            first_diff_idx = tuple(idx[0] for idx in diff_indices)
-            orig_val = orig_np[first_diff_idx]
-            recv_val = recv_np[first_diff_idx]
-            if verbose:
-                print(f"❌ Tensors differ at index {first_diff_idx}")
-                print(f"   Original: {orig_val}")
-                print(f"   Received: {recv_val}")
-                print(f"   Difference: {abs(orig_val - recv_val)}")
-        return False
-
-def parse_global_segment_size(value) -> int:
-    """Parse human-readable size strings (e.g., '4GB') into bytes."""
-    if isinstance(value, int): return value
-    if isinstance(value, str):
-        s = value.strip().lower()
-        if s.endswith("gb"):
-            return int(s[:-2].strip()) * 1024**3
-        return int(s)
-    return int(value)
-
-def create_store_connection():
-    """Create and connect to the Store (called only once by setUpModule)."""
-    store = MooncakeDistributedStore()
-    config = MooncakeConfig.load_from_env()
-    print(f"[{os.getpid()}] Connecting to Mooncake Master at {config.master_server_address} using {config.protocol}...")
-    rc = store.setup(
-        config.local_hostname,
-        config.metadata_server,
-        config.global_segment_size,
-        config.local_buffer_size,
-        config.protocol,
-        config.device_name,
-        config.master_server_address,
-    )
-    if rc != 0:
-        raise RuntimeError(f"Failed to setup mooncake store, error code: {rc}")
-    return store, config
-
-def generate_tensors(num_tensors, size_mb):
-    """Generate random Tensors suitable for TP testing."""
-    size_bytes = int(size_mb * 1024 * 1024)
-    element_size = 4  # float32
-    num_elements = size_bytes // element_size
-    dim = int(np.sqrt(num_elements))
-    dim = (dim // 8) * 8  # Adjust dimension to be divisible by common TP sizes (2, 4, 8)
-
-    # Use random data and ensure the tensor is contiguous in memory
-    tensors = [torch.randn(dim, dim, dtype=torch.float32).contiguous() for _ in range(num_tensors)]
-    # Use timestamp to prevent key collision in rare edge cases (though we remove_all anyway)
-    keys = [f"test_tensor_{i}_{int(time.time()*1000)}" for i in range(num_tensors)]
-    return keys, tensors
-
-# ==========================================
-#  Module Level Setup/Teardown (Hooks)
-# ==========================================
-
-def setUpModule():
-    """Executed once before all tests in this file: establishes the global connection."""
-    global GLOBAL_STORE, GLOBAL_CONFIG
-    try:
-        GLOBAL_STORE, GLOBAL_CONFIG = create_store_connection()
-        print("✅ Global Store connection established.")
-    except Exception as e:
-        print(f"❌ Failed to establish global store connection: {e}")
-        sys.exit(1)
-
-
-def require_unified_parallelism_api(test_case):
-    missing = [
-        name for name in ["ParallelAxis", "TensorParallelism", "ReadTarget"]
-        if not hasattr(mooncake_store, name)
-    ]
-    if missing:
-        test_case.skipTest(
-            "Unified parallelism Python bindings are not available in the installed extension: "
-            + ", ".join(missing)
-        )
-
-
-def make_parallel_axis(kind, rank, size, split_dim=None):
-    axis = mooncake_store.ParallelAxis()
-    axis.kind = kind
-    axis.rank = rank
-    axis.size = size
-    axis.split_dim = split_dim
-    return axis
-
-
-def make_tensor_parallelism(axes):
-    parallelism = mooncake_store.TensorParallelism()
-    parallelism.axes = axes
-    return parallelism
-
-
-def make_read_target(mode, parallelism=None):
-    target = mooncake_store.ReadTarget()
-    target.mode = mode
-    target.parallelism = parallelism
-    return target
-
-
-def make_writer_partition(rank, size, split_dim):
-    return WriterPartition(rank=rank, size=size, split_dim=split_dim)
-
-
-def build_tp_parallelism(tp_size, split_dim, rank=0):
-    return make_tensor_parallelism([
-        make_parallel_axis("tp", rank=rank, size=tp_size, split_dim=split_dim)
-    ])
-
-
-def build_dp_tp_parallelism(dp_rank, dp_size, tp_rank, tp_size, split_dim):
-    return make_tensor_parallelism([
-        make_parallel_axis("dp", rank=dp_rank, size=dp_size),
-        make_parallel_axis("tp", rank=tp_rank, size=tp_size, split_dim=split_dim),
-    ])
-
-
-def build_pp_tp_parallelism(pp_rank, pp_size, stage_id, tp_rank, tp_size, split_dim):
-    pp_axis = make_parallel_axis("pp", rank=pp_rank, size=pp_size)
-    pp_axis.stage_id = stage_id
-    return make_tensor_parallelism([
-        pp_axis,
-        make_parallel_axis("tp", rank=tp_rank, size=tp_size, split_dim=split_dim),
-    ])
-
-
-def build_ep_parallelism(ep_rank, ep_size, expert_id):
-    ep_axis = make_parallel_axis("ep", rank=ep_rank, size=ep_size)
-    ep_axis.expert_id = expert_id
-    return make_tensor_parallelism([ep_axis])
-
-
-def build_ep_tp_parallelism(ep_rank, ep_size, expert_id, tp_rank, tp_size, split_dim):
-    ep_axis = make_parallel_axis("ep", rank=ep_rank, size=ep_size)
-    ep_axis.expert_id = expert_id
-    return make_tensor_parallelism([
-        ep_axis,
-        make_parallel_axis("tp", rank=tp_rank, size=tp_size, split_dim=split_dim),
-    ])
-
-
-def build_parallelism_mode(mode, tp_rank, tp_size, split_dim):
-    if mode == "tp":
-        return build_tp_parallelism(tp_size, split_dim, rank=tp_rank)
-    if mode == "dp_tp":
-        return build_dp_tp_parallelism(0, 2, tp_rank, tp_size, split_dim)
-    if mode == "pp_tp":
-        return build_pp_tp_parallelism(0, 2, 7, tp_rank, tp_size, split_dim)
-    if mode == "ep_tp":
-        return build_ep_tp_parallelism(0, 2, 11, tp_rank, tp_size, split_dim)
-    raise ValueError(f"unsupported parallelism mode: {mode}")
-
-
-def put_full_tensor_with_parallelism_mode(store, key, tensor, split_dim, put_tp_size, mode):
-    if mode == "tp":
-        shards = tensor.chunk(put_tp_size, split_dim)
-        for rank, shard in enumerate(shards):
-            rc = store.put_tensor_with_parallelism(
-                key,
-                shard.contiguous(),
-                build_parallelism_mode(mode, rank, put_tp_size, split_dim),
-            )
-            if rc != 0:
-                return rc
-        return 0
-
-    for rank in range(put_tp_size):
-        rc = store.put_tensor_with_parallelism(
-            key,
-            tensor,
-            build_parallelism_mode(mode, rank, put_tp_size, split_dim),
-        )
-        if rc != 0:
-            return rc
-    return 0
-
-
-def clone_parallelism(parallelism):
-    cloned_axes = []
-    for axis in parallelism.axes:
-        cloned_axis = make_parallel_axis(
-            axis.kind,
-            rank=axis.rank,
-            size=axis.size,
-            split_dim=axis.split_dim,
-        )
-        if getattr(axis, "expert_id", None) is not None:
-            cloned_axis.expert_id = axis.expert_id
-        if getattr(axis, "stage_id", None) is not None:
-            cloned_axis.stage_id = axis.stage_id
-        cloned_axes.append(cloned_axis)
-    return make_tensor_parallelism(cloned_axes)
-
-
-def put_full_tensor_with_parallelism_template(store, key, tensor, parallelism):
-    tp_axis = next(axis for axis in parallelism.axes if axis.kind == "tp")
-    for rank in range(tp_axis.size):
-        shard_parallelism = clone_parallelism(parallelism)
-        for axis in shard_parallelism.axes:
-            if axis.kind == "tp":
-                axis.rank = rank
-                axis.size = tp_axis.size
-                axis.split_dim = tp_axis.split_dim
-                break
-        rc = store.put_tensor_with_parallelism(
-            key,
-            tensor,
-            shard_parallelism,
-        )
-        if rc != 0:
-            return rc
-    return 0
-
-
-def expected_target_shard(tensor, split_dim, target_tp_size, target_rank):
-    return chunk_tensor_for_rank(tensor, target_tp_size, split_dim, target_rank).contiguous()
-
-
-def reorder_parallelism_axes(parallelism, ordered_kinds):
-    axis_by_kind = {axis.kind: axis for axis in parallelism.axes}
-    return make_tensor_parallelism([axis_by_kind[kind] for kind in ordered_kinds])
-
-
-def make_deterministic_tensor(shape, dtype=torch.float32):
-    numel = 1
-    for dim in shape:
-        numel *= dim
-    return torch.arange(numel, dtype=dtype).view(*shape).contiguous()
-
-
-def chunk_tensor_for_rank(tensor, tp_size, split_dim, rank):
-    return tensor.chunk(tp_size, split_dim)[rank]
-
-
-def put_full_tensor_with_unified_tp(store, key, tensor, tp_size, split_dim):
-    for rank, shard in enumerate(tensor.chunk(tp_size, split_dim)):
-        rc = store.put_tensor_with_parallelism(
-            key,
-            shard.contiguous(),
-            build_tp_parallelism(tp_size, split_dim, rank=rank),
-        )
-        if rc != 0:
-            return rc
-    return 0
-
-
-def batch_put_full_tensors_with_unified_tp(store, keys, tensors, tp_size, split_dim):
-    results = [0 for _ in keys]
-    for rank in range(tp_size):
-        shard_tensors = [chunk_tensor_for_rank(tensor, tp_size, split_dim, rank).contiguous() for tensor in tensors]
-        rank_results = store.batch_put_tensor_with_parallelism(
-            keys,
-            shard_tensors,
-            [build_tp_parallelism(tp_size, split_dim, rank=rank) for _ in keys],
-        )
-        results = rank_results
-        if any(rc != 0 for rc in rank_results):
-            return rank_results
-    return results
-
-
-def reconstruction_case_name(shape, split_dim, tp_size):
-    shape_str = "x".join(str(dim) for dim in shape)
-    return f"shape={shape_str}, split_dim={split_dim}, tp_size={tp_size}"
-
-
-def is_uniform_tp_case(shape, split_dim, tp_size):
-    return shape[split_dim] % tp_size == 0
-
-
-def put_uniform_full_tensor_with_unified_tp(store, key, tensor, tp_size, split_dim):
-    if not is_uniform_tp_case(tuple(tensor.shape), split_dim, tp_size):
-        return -1
-    return put_full_tensor_with_unified_tp(store, key, tensor, tp_size, split_dim)
-
-
-def make_mb_scale_original_tensor(dtype=torch.float32):
-    return make_deterministic_tensor((16, 16, 16), dtype=dtype)
-
-
-def assert_tensor_matches_expected_shard(test_case, original_tensor, received_tensor,
-                                         split_dim, target_tp_size, target_rank,
-                                         context):
-    expected_tensor = expected_target_shard(
-        original_tensor, split_dim, target_tp_size, target_rank
-    )
-    test_case.assertIsNotNone(received_tensor, f"missing tensor for {context}")
-    test_case.assertTrue(
-        torch.equal(received_tensor, expected_tensor),
-        f"mismatch for {context}",
-    )
-
-
-def tearDownModule():
-    """Executed once after all tests in this file: closes the global connection."""
-    global GLOBAL_STORE
-    if GLOBAL_STORE:
-        print("\nClosing global store connection...")
-        GLOBAL_STORE.close()
-        GLOBAL_STORE = None
-
-# ==========================================
-#  Base Test Class
-# ==========================================
-
-class MooncakeTestBase(unittest.TestCase):
-    def setUp(self):
-        """Executed before each test method (test_xxx)."""
-        # 1. Access the global connection
-        if GLOBAL_STORE is None:
-            self.skipTest("Store not initialized")
-
-        self.store = GLOBAL_STORE
-        self.config = GLOBAL_CONFIG
-
-        # 2. [Critical] Clean environment before the test starts
-        # This ensures no stale data from previous tests affects the current one
-        self.store.remove_all()
-
-# ==========================================
-#  Functional Tests
-# ==========================================
-
-class TestMooncakeFunctional(MooncakeTestBase):
-    def assert_full_reconstruction_case(self, key, tensor, split_dim, tp_size):
-        rc = put_uniform_full_tensor_with_unified_tp(
-            self.store, key, tensor, tp_size, split_dim
-        )
-        self.assertEqual(rc, 0, f"put_tensor_with_parallelism failed for {key}")
-
-        shard_reads = []
-        expected_shards = tensor.chunk(tp_size, split_dim)
-        for rank, expected_shard in enumerate(expected_shards):
-            wrapper_shard = self.store.get_tensor_with_tp(
-                key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertIsNotNone(wrapper_shard, f"wrapper shard missing for rank {rank}")
-            self.assertTrue(
-                torch.equal(wrapper_shard, expected_shard),
-                f"wrapper shard mismatch for rank {rank}",
-            )
-
-            shard_parallelism = build_tp_parallelism(tp_size, split_dim, rank=rank)
-            shard_target = make_read_target("shard", shard_parallelism)
-            unified_shard = self.store.get_tensor_with_parallelism(key, shard_target)
-            self.assertIsNotNone(unified_shard, f"unified shard missing for rank {rank}")
-            self.assertTrue(
-                torch.equal(unified_shard, expected_shard),
-                f"unified shard mismatch for rank {rank}",
-            )
-            self.assertTrue(torch.equal(unified_shard, wrapper_shard))
-            shard_reads.append(unified_shard)
-
-        reconstructed_from_shards = torch.cat(shard_reads, dim=split_dim)
-        self.assertTrue(torch.equal(reconstructed_from_shards, tensor))
-
-        full_parallelism = build_tp_parallelism(tp_size, split_dim, rank=min(tp_size - 1, 1))
-        full_target = make_read_target("full", full_parallelism)
-        full_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-        self.assertIsNotNone(full_tensor)
-        self.assertTrue(torch.equal(full_tensor, tensor))
-
-    def assert_full_into_reconstruction_case(self, key, tensor, split_dim, tp_size, buffer_spacing):
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            parallelism = build_tp_parallelism(tp_size, split_dim, rank=min(tp_size - 1, 1))
-            rc = put_uniform_full_tensor_with_unified_tp(
-                self.store, key, tensor, tp_size, split_dim
-            )
-            self.assertEqual(rc, 0)
-
-            target = make_read_target("full", parallelism)
-            full_tensor = self.store.get_tensor_with_parallelism(key, target)
-            reconstructed = self.store.get_tensor_with_parallelism_into(
-                key, buffer_ptr, buffer_spacing, target=target
-            )
-            self.assertIsNotNone(full_tensor)
-            self.assertIsNotNone(reconstructed)
-            self.assertTrue(torch.equal(full_tensor, tensor))
-            self.assertTrue(torch.equal(reconstructed, tensor))
-            self.assertTrue(torch.equal(reconstructed, full_tensor))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def assert_full_reconstruction_for_all_read_ranks(self, key, tensor, split_dim, tp_size):
-        rc = put_uniform_full_tensor_with_unified_tp(
-            self.store, key, tensor, tp_size, split_dim
-        )
-        self.assertEqual(rc, 0, f"put_tensor_with_parallelism failed for {key}")
-
-        expected_rank_count = len(tensor.chunk(tp_size, split_dim))
-        for rank in range(tp_size):
-            full_target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=rank))
-            full_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-            self.assertIsNotNone(full_tensor, f"full tensor missing for read rank {rank}")
-            self.assertTrue(torch.equal(full_tensor, tensor), f"full tensor mismatch for read rank {rank}")
-
-            if rank < expected_rank_count:
-                shard_target = make_read_target("shard", build_tp_parallelism(tp_size, split_dim, rank=rank))
-                shard_tensor = self.store.get_tensor_with_parallelism(key, shard_target)
-                expected_shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, rank)
-                self.assertIsNotNone(shard_tensor, f"shard missing for read rank {rank}")
-                self.assertTrue(torch.equal(shard_tensor, expected_shard), f"shard mismatch for read rank {rank}")
-
-    def assert_writer_shard_full_reconstruction_case(self, key, tensor, split_dim, shard_count):
-        for rank in range(shard_count):
-            rc = self.store.put_tensor_with_parallelism(
-                key,
-                tensor,
-                writer_partition=make_writer_partition(rank, shard_count, split_dim),
-            )
-            self.assertEqual(rc, 0, f"writer shard put failed for rank {rank}")
-
-        full_target = make_read_target("full")
-        full_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-        self.assertIsNotNone(full_tensor)
-        self.assertTrue(torch.equal(full_tensor, tensor))
-
-        for rank in range(shard_count):
-            shard_target = make_read_target(
-                "shard", build_tp_parallelism(shard_count, split_dim, rank=rank)
-            )
-            shard_tensor = self.store.get_tensor_with_parallelism(key, shard_target)
-            self.assertIsNotNone(shard_tensor)
-            self.assertTrue(torch.equal(shard_tensor, tensor.chunk(shard_count, split_dim)[rank]))
-
-    def test_01_basic_put_get(self):
-        """Verify basic put and get functionality."""
-        key = "func_test_single"
-        tensor = torch.randn(1024, 1024, dtype=torch.float32)
-
-        # Perform Put
-        rc = self.store.put_tensor(key, tensor)
-        self.assertEqual(rc, 0, f"put_tensor failed with rc={rc}")
-        self.assertTrue(self.store.is_exist(key), "Key not found after put")
-
-        # Perform Get
-        retrieved = self.store.get_tensor(key)
-        self.assertIsNotNone(retrieved, "Get returned None")
-        self.assertTrue(torch.equal(tensor, retrieved), "Data mismatch between original and retrieved tensor")
-
-    def test_02_tp_single_tensor(self):
-        """Verify TP (Tensor Parallelism) splitting and reconstruction for a single Tensor."""
-        tp_size = 4
-        split_dim = 1
-        key = "func_test_tp_single"
-
-        # Create a small tensor (e.g., 16MB)
-        _, tensors = generate_tensors(1, 16)
-        target_tensor = tensors[0]
-
-        # 1. Put with TP
-        rc = self.store.put_tensor_with_tp(key, target_tensor, tp_size=tp_size, split_dim=split_dim)
-        self.assertEqual(rc, 0, "put_tensor_with_tp failed")
-
-        # 2. Verify existence of shards (White-box check: key_tp_0, key_tp_1...)
-        for rank in range(tp_size):
-            shard_key = f"{key}_tp_{rank}"
-            self.assertTrue(self.store.is_exist(shard_key), f"Shard key {shard_key} is missing in store")
-
-        # 3. Get shards and Reconstruct
-        slices = []
-        expected_chunks = target_tensor.chunk(tp_size, split_dim)
-        for rank in range(tp_size):
-            t_slice = self.store.get_tensor_with_tp(key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim)
-            self.assertIsNotNone(t_slice, f"Slice for rank {rank} is None")
-            self.assertTrue(torch.equal(t_slice, expected_chunks[rank]), f"Data mismatch for rank {rank}")
-            slices.append(t_slice)
-
-        reconstructed = torch.cat(slices, dim=split_dim)
-        self.assertTrue(torch.equal(reconstructed, target_tensor), "Reconstructed tensor does not match original")
-
-    def test_03_tp_batch(self):
-        """Verify TP splitting and reconstruction for a Batch of Tensors."""
-        tp_size = 2
-        split_dim = 0
-        num_tensors = 4
-        keys, tensors = generate_tensors(num_tensors, 8) # Small size for functional testing
-
-        # 1. Batch Put with TP
-        results = self.store.batch_put_tensor_with_tp(keys, tensors, tp_size=tp_size, split_dim=split_dim)
-        self.assertTrue(all(r == 0 for r in results), f"Batch put failed. Results: {results}")
-
-        # 2. Batch Get per Rank
-        all_shards = [] # List of lists: [ [shards_rank0...], [shards_rank1...] ]
-        for rank in range(tp_size):
-            shards = self.store.batch_get_tensor_with_tp(keys, tp_rank=rank, tp_size=tp_size)
-            self.assertEqual(len(shards), num_tensors)
-            all_shards.append(shards)
-
-        # 3. Verify & Reconstruct
-        for i in range(num_tensors):
-            original = tensors[i]
-            expected_chunks = original.chunk(tp_size, split_dim)
-            reconstruction_parts = []
-
-            for rank in range(tp_size):
-                shard = all_shards[rank][i]
-                self.assertTrue(torch.equal(shard, expected_chunks[rank]), 
-                                f"Tensor {i} Rank {rank} data mismatch")
-                reconstruction_parts.append(shard)
-
-            recon = torch.cat(reconstruction_parts, dim=split_dim)
-            self.assertTrue(torch.equal(recon, original), f"Tensor {i} final reconstruction mismatch")
-
-    def test_04_tp_consistency(self):
-        input_tensor = torch.arange(12).view(3, 4)
-        tp_size = 2
-        split_dim = 1
-        buffer_spacing = 1 * 1024 * 1024
-        full_buffer = (ctypes.c_ubyte * buffer_spacing)()
-        shard_buffer_0 = (ctypes.c_ubyte * buffer_spacing)()
-        shard_buffer_1 = (ctypes.c_ubyte * buffer_spacing)()
-        full_buffer_ptr = ctypes.addressof(full_buffer)
-        shard_buffer_ptr_0 = ctypes.addressof(shard_buffer_0)
-        shard_buffer_ptr_1 = ctypes.addressof(shard_buffer_1)
-
-        for ptr in [full_buffer_ptr, shard_buffer_ptr_0, shard_buffer_ptr_1]:
-            res = self.store.register_buffer(ptr, buffer_spacing)
-            self.assertEqual(res, 0, f"Buffer registration failed for buffer at {ptr}")
-
-        rc = self.store.put_tensor("key_seed_full", input_tensor)
-        self.assertEqual(rc, 0, f"put_tensor(seed) failed with rc={rc}")
-        retrieved = self.store.get_tensor_into("key_seed_full", full_buffer_ptr, buffer_spacing)
-        self.assertIsNotNone(retrieved)
-        full_size = serialized_tensor_size(retrieved)
-
-        rc = self.store.put_tensor_with_tp_from(
-            "key", full_buffer_ptr, full_size,
-            tp_rank=1, tp_size=tp_size, split_dim=split_dim
-        )
-        self.assertEqual(rc, 0, f"put_tensor_with_tp_from failed with rc={rc}")
-
-        chunked_tensors = input_tensor.chunk(chunks=2, dim=split_dim)
-        tmp_tensor_0 = self.store.batch_get_tensor_with_tp(['key'], tp_rank=0, tp_size=tp_size)[0]
-        tmp_tensor_1 = self.store.batch_get_tensor_with_tp(['key'], tp_rank=1, tp_size=tp_size)[0]
-        self.assertTrue(torch.equal(tmp_tensor_0, chunked_tensors[0]))
-        self.assertTrue(torch.equal(tmp_tensor_1, chunked_tensors[1]))
-
-        tmp_tensor_2 = self.store.get_tensor_with_tp_into(
-            'key', shard_buffer_ptr_0, buffer_spacing,
-            tp_rank=0, tp_size=tp_size, split_dim=split_dim
-        )
-        tmp_tensor_3 = self.store.get_tensor_with_tp_into(
-            'key', shard_buffer_ptr_1, buffer_spacing,
-            tp_rank=1, tp_size=tp_size, split_dim=split_dim
-        )
-        self.assertTrue(torch.equal(tmp_tensor_2, chunked_tensors[0]))
-        self.assertTrue(torch.equal(tmp_tensor_3, chunked_tensors[1]))
-
-        for ptr in [full_buffer_ptr, shard_buffer_ptr_0, shard_buffer_ptr_1]:
-            res = self.store.unregister_buffer(ptr)
-            self.assertEqual(res, 0, f"Buffer unregistration failed for buffer at {ptr}")
-
-    def test_05_put_get_into(self):
-        """Verify basic put and get into functionality (zero-copy put + get_into)."""
-        key = "get_into_test"
-        seed_key = "get_into_test_seed"
-        tensor = torch.randn(1024, 1024, dtype=torch.float32)
-        buffer_spacing = 64 * 1024 * 1024
-        total_buffer_size = buffer_spacing
-
-        buf_put = (ctypes.c_ubyte * total_buffer_size)()
-        buf_get = (ctypes.c_ubyte * total_buffer_size)()
-        buf_put_ptr = ctypes.addressof(buf_put)
-        buf_get_ptr = ctypes.addressof(buf_get)
-        res = self.store.register_buffer(buf_put_ptr, total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration failed for put buffer")
-        res = self.store.register_buffer(buf_get_ptr, total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration failed for get buffer")
-
-        # Zero-copy put: fill buffer from seed, then put_tensor_from (use actual serialized size)
-        rc = self.store.put_tensor(seed_key, tensor)
-        self.assertEqual(rc, 0, f"put_tensor(seed) failed with rc={rc}")
-        retrieved_seed = self.store.get_tensor_into(seed_key, buf_put_ptr, total_buffer_size)
-        self.assertIsNotNone(retrieved_seed)
-        put_size = serialized_tensor_size(retrieved_seed)
-        rc = self.store.put_tensor_from(key, buf_put_ptr, put_size)
-        self.assertEqual(rc, 0, f"put_tensor_from failed with rc={rc}")
-        self.assertTrue(self.store.is_exist(key), "Key not found after put")
-
-        retrieved = self.store.get_tensor_into(key, buf_get_ptr, total_buffer_size)
-        self.assertIsNotNone(retrieved, "Get returned None")
-        self.assertTrue(torch.equal(tensor, retrieved), f"Data mismatch between original and retrieved tensor, tensor: {tensor}, retrieved: {retrieved}")
-        self.assertEqual(self.store.unregister_buffer(buf_put_ptr), 0, "Buffer unregistration failed for put buffer")
-        self.assertEqual(self.store.unregister_buffer(buf_get_ptr), 0, "Buffer unregistration failed for get buffer")
-
-    def test_06_batch_put_get_into(self):
-        """Zero copy Batch Put and Batch Get."""
-        num_tensors = 4
-        keys, tensors = generate_tensors(num_tensors, 8)
-        seed_keys = [f"{k}_seed" for k in keys]
-        buffer_spacing = 64 * 1024 * 1024  # 64MB per tensor slot
-        batch_size = len(keys)
-        total_buffer_size = buffer_spacing * batch_size * 2  # put slots + get slots
-
-        large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        large_buffer_ptr = ctypes.addressof(large_buffer)
-        put_ptrs = [large_buffer_ptr + i * buffer_spacing for i in range(batch_size)]
-        get_ptrs = [large_buffer_ptr + (batch_size + i) * buffer_spacing for i in range(batch_size)]
-        buffer_sizes = [buffer_spacing] * batch_size
-
-        res = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration failed")
-
-        results = self.store.batch_put_tensor(seed_keys, tensors)
-        self.assertTrue(all(r == 0 for r in results), f"Batch put(seed) failed. Results: {results}")
-        self.store.batch_get_tensor_into(seed_keys, put_ptrs, buffer_sizes)
-        put_sizes = [serialized_tensor_size(tensors[j]) for j in range(batch_size)]
-        results = self.store.batch_put_tensor_from(keys, put_ptrs, put_sizes)
-        self.assertTrue(all(r == 0 for r in results), f"Batch put_tensor_from failed. Results: {results}")
-
-        res = self.store.batch_get_tensor_into(keys, get_ptrs, buffer_sizes)
-        self.assertEqual(len(res), len(tensors))
-        for j in range(batch_size):
-            self.assertTrue(
-                verify_tensor_equality(tensors[j], res[j]),
-                f"Tensor {j} content mismatch, tensor: {tensors[j]}, res: {res[j]}"
-            )
-        self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration failed")
-
-    def test_07_put_get_into_with_tp(self):
-        """Zero-copy TP put_from consumes one full tensor buffer and writes all shards."""
-        tp_size = 4
-        split_dim = 0
-        key = "get_into_with_tp_test"
-        seed_key = "get_into_with_tp_seed"
-        tensor = torch.randn(1024, 1024, dtype=torch.float32)
-        buffer_spacing = 64 * 1024 * 1024
-        total_buffer_size = buffer_spacing * (1 + tp_size)
-
-        large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        large_buffer_ptr = ctypes.addressof(large_buffer)
-        full_ptr = large_buffer_ptr
-        get_ptrs = [large_buffer_ptr + (rank + 1) * buffer_spacing for rank in range(tp_size)]
-
-        self.assertEqual(self.store.register_buffer(large_buffer_ptr, total_buffer_size), 0)
-        try:
-            rc = self.store.put_tensor(seed_key, tensor)
-            self.assertEqual(rc, 0, f"Put(seed) failed. Result: {rc}")
-            full_tensor = self.store.get_tensor_into(seed_key, full_ptr, buffer_spacing)
-            self.assertIsNotNone(full_tensor)
-            full_size = serialized_tensor_size(full_tensor)
-
-            rc = self.store.put_tensor_with_tp_from(
-                key, full_ptr, full_size,
-                tp_rank=2, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertEqual(rc, 0, f"put_tensor_with_tp_from failed with rc={rc}")
-
-            all_shards = []
-            for rank in range(tp_size):
-                shard = self.store.get_tensor_with_tp_into(
-                    key, get_ptrs[rank], buffer_spacing,
-                    tp_rank=rank, tp_size=tp_size
-                )
-                self.assertIsNotNone(shard)
-                all_shards.append(shard)
-
-            expected_chunks = tensor.chunk(tp_size, split_dim)
-            reconstruction_parts = []
-            for rank in range(tp_size):
-                shard = all_shards[rank]
-                self.assertTrue(
-                    torch.equal(shard, expected_chunks[rank]),
-                    f"Tensor Rank {rank} data mismatch"
-                )
-                reconstruction_parts.append(shard)
-            recon = torch.cat(reconstruction_parts, dim=split_dim)
-            self.assertTrue(torch.equal(recon, tensor), "Tensor final reconstruction mismatch")
-        finally:
-            self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Unregister buffer failed")
-
-    def test_08_batch_put_get_into_with_tp(self):
-        """Zero-copy batch TP put_from consumes full tensor buffers for each item."""
-        tp_size = 4
-        split_dim = 0
-        num_tensors = 4
-        keys, tensors = generate_tensors(num_tensors, 8)
-        seed_keys = [f"{k}_seed" for k in keys]
-        batch_size = len(keys)
-        buffer_spacing = 64 * 1024 * 1024
-        total_buffer_size = buffer_spacing * batch_size * (1 + tp_size)
-
-        large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        large_buffer_ptr = ctypes.addressof(large_buffer)
-        full_ptrs = [large_buffer_ptr + i * buffer_spacing for i in range(batch_size)]
-        get_ptrs_by_rank = [
-            [large_buffer_ptr + ((rank + 1) * batch_size + i) * buffer_spacing for i in range(batch_size)]
-            for rank in range(tp_size)
-        ]
-        buffer_sizes = [buffer_spacing] * batch_size
-
-        res = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration failed")
-        try:
-            results = self.store.batch_put_tensor(seed_keys, tensors)
-            self.assertTrue(all(r == 0 for r in results), f"Batch put(seed) failed. Results: {results}")
-            full_tensors = self.store.batch_get_tensor_into(seed_keys, full_ptrs, buffer_sizes)
-            self.assertEqual(len(full_tensors), num_tensors)
-            put_sizes = [serialized_tensor_size(full_tensors[j]) for j in range(num_tensors)]
-
-            results = self.store.batch_put_tensor_with_tp_from(
-                keys, full_ptrs, put_sizes,
-                tp_rank=3, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertTrue(all(r == 0 for r in results), f"batch_put_tensor_with_tp_from failed: {results}")
-
-            all_shards = []
-            for rank in range(tp_size):
-                shards = self.store.batch_get_tensor_with_tp_into(
-                    keys, get_ptrs_by_rank[rank], buffer_sizes,
-                    tp_rank=rank, tp_size=tp_size
-                )
-                self.assertEqual(len(shards), num_tensors)
-                all_shards.append(shards)
-
-            for i in range(num_tensors):
-                original = tensors[i]
-                expected_chunks = original.chunk(tp_size, split_dim)
-                reconstruction_parts = []
-                for rank in range(tp_size):
-                    shard = all_shards[rank][i]
-                    self.assertTrue(
-                        torch.equal(shard, expected_chunks[rank]),
-                        f"Tensor {i} Rank {rank} data mismatch"
-                    )
-                    reconstruction_parts.append(shard)
-                recon = torch.cat(reconstruction_parts, dim=split_dim)
-                self.assertTrue(torch.equal(recon, original), f"Tensor {i} final reconstruction mismatch")
-        finally:
-            self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration failed")
-
-    def test_09_pub_get(self):
-        """Verify pub and get functionality."""
-        key = "func_pub_test"
-        tensor = torch.randn(1024, 1024, dtype=torch.float32)
-
-        repconfig = ReplicateConfig()
-        repconfig.replica_num = 1
-
-        # Perform Put
-        rc = self.store.pub_tensor(key, tensor, repconfig)
-        self.assertEqual(rc, 0, f"put_tensor failed with rc={rc}")
-        self.assertTrue(self.store.is_exist(key), "Key not found after put")
-
-        # Perform Get
-        retrieved = self.store.get_tensor(key)
-        self.assertIsNotNone(retrieved, "Get returned None")
-        self.assertTrue(torch.equal(tensor, retrieved), "Data mismatch between original and retrieved tensor")
-
-    def test_10_pub_tp_single_tensor(self):
-        """Verify TP (Tensor Parallelism) splitting and reconstruction for a single Tensor."""
-        tp_size = 4
-        split_dim = 1
-        key = "func_pub_tp_single"
-
-        # Create a small tensor (e.g., 16MB)
-        _, tensors = generate_tensors(1, 16)
-        target_tensor = tensors[0]
-
-        repconfig = ReplicateConfig()
-        repconfig.replica_num = 1
-
-        # 1. Pub with TP
-        rc = self.store.pub_tensor_with_tp(key, target_tensor, config=repconfig, tp_size=tp_size, split_dim=split_dim)
-        self.assertEqual(rc, 0, "pub_tensor_with_tp failed")
-
-        # 2. Verify existence of shards (White-box check: key_tp_0, key_tp_1...)
-        for rank in range(tp_size):
-            shard_key = f"{key}_tp_{rank}"
-            self.assertTrue(self.store.is_exist(shard_key), f"Shard key {shard_key} is missing in store")
-
-        # 3. Get shards and Reconstruct
-        slices = []
-        expected_chunks = target_tensor.chunk(tp_size, split_dim)
-        for rank in range(tp_size):
-            t_slice = self.store.get_tensor_with_tp(key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim)
-            self.assertIsNotNone(t_slice, f"Slice for rank {rank} is None")
-            self.assertTrue(torch.equal(t_slice, expected_chunks[rank]), f"Data mismatch for rank {rank}")
-            slices.append(t_slice)
-
-        reconstructed = torch.cat(slices, dim=split_dim)
-        self.assertTrue(torch.equal(reconstructed, target_tensor), "Reconstructed tensor does not match original")
-
-    def test_11_pub_tp_batch(self):
-        """Verify TP splitting and reconstruction for a Batch of Tensors."""
-        tp_size = 2
-        split_dim = 0
-        num_tensors = 4
-        keys, tensors = generate_tensors(num_tensors, 8) # Small size for functional testing
-
-        repconfig = ReplicateConfig()
-        repconfig.replica_num = 1
-
-        # 1. Batch Pub with TP
-        results = self.store.batch_pub_tensor_with_tp(keys, tensors, config=repconfig, tp_size=tp_size, split_dim=split_dim)
-        self.assertTrue(all(r == 0 for r in results), f"Batch put failed. Results: {results}")
-
-        # 2. Batch Get per Rank
-        all_shards = [] # List of lists: [ [shards_rank0...], [shards_rank1...] ]
-        for rank in range(tp_size):
-            shards = self.store.batch_get_tensor_with_tp(keys, tp_rank=rank, tp_size=tp_size)
-            self.assertEqual(len(shards), num_tensors)
-            all_shards.append(shards)
-
-        # 3. Verify & Reconstruct
-        for i in range(num_tensors):
-            original = tensors[i]
-            expected_chunks = original.chunk(tp_size, split_dim)
-            reconstruction_parts = []
-
-            for rank in range(tp_size):
-                shard = all_shards[rank][i]
-                self.assertTrue(torch.equal(shard, expected_chunks[rank]),
-                                f"Tensor {i} Rank {rank} data mismatch")
-                reconstruction_parts.append(shard)
-
-            recon = torch.cat(reconstruction_parts, dim=split_dim)
-            self.assertTrue(torch.equal(recon, original), f"Tensor {i} final reconstruction mismatch")
-
-    def test_12_unified_parallelism_as_stored_round_trip(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_as_stored"
-        tensor = torch.randn(16, 16, dtype=torch.float32)
-
-        rc = self.store.put_tensor_with_parallelism(key, tensor)
-        self.assertEqual(rc, 0, f"put_tensor_with_parallelism failed with rc={rc}")
-
-        retrieved_default = self.store.get_tensor_with_parallelism(key)
-        self.assertIsNotNone(retrieved_default)
-        self.assertTrue(torch.equal(retrieved_default, tensor))
-
-        target = make_read_target("as_stored")
-        retrieved_target = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(retrieved_target)
-        self.assertTrue(torch.equal(retrieved_target, tensor))
-
-    def test_13_unified_parallelism_tp_matches_wrapper(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_single"
-        tensor = torch.arange(24, dtype=torch.float32).view(4, 6).contiguous()
-        tp_size = 3
-        split_dim = 1
-
-        parallelism = make_tensor_parallelism([
-            make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)
-        ])
-
-        shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, 0).contiguous()
-        rc = self.store.put_tensor_with_parallelism(key, shard, parallelism)
-        self.assertEqual(rc, 0, f"put_tensor_with_parallelism failed with rc={rc}")
-
-        expected = shard
-        rank = 0
-        wrapper_shard = self.store.get_tensor_with_tp(
-            key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim
-        )
-        self.assertIsNotNone(wrapper_shard)
-        self.assertTrue(torch.equal(wrapper_shard, expected))
-
-        shard_parallelism = make_tensor_parallelism([
-            make_parallel_axis("tp", rank=rank, size=tp_size, split_dim=split_dim)
-        ])
-
-        target = make_read_target("shard", shard_parallelism)
-        unified_shard = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(unified_shard)
-        self.assertTrue(torch.equal(unified_shard, expected))
-        self.assertTrue(torch.equal(unified_shard, wrapper_shard))
-
-        for rank in range(1, tp_size):
-            wrapper_shard = self.store.get_tensor_with_tp(
-                key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertIsNone(wrapper_shard)
-
-            shard_parallelism = make_tensor_parallelism([
-                make_parallel_axis("tp", rank=rank, size=tp_size, split_dim=split_dim)
-            ])
-
-            target = make_read_target("shard", shard_parallelism)
-            unified_shard = self.store.get_tensor_with_parallelism(key, target)
-            self.assertIsNone(unified_shard)
-
-    def test_14_batch_unified_parallelism_tp_matches_wrapper(self):
-        require_unified_parallelism_api(self)
-        tp_size = 2
-        split_dim = 0
-        num_tensors = 2
-        keys, tensors = generate_tensors(num_tensors, 1)
-
-        results = batch_put_full_tensors_with_unified_tp(
-            self.store, keys, tensors, tp_size, split_dim
-        )
-        self.assertTrue(all(r == 0 for r in results), f"Batch unified put failed. Results: {results}")
-
-        parallelism = make_tensor_parallelism([
-            make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)
-        ])
-        invalid_results = self.store.batch_put_tensor_with_parallelism(
-            keys,
-            tensors,
-            [parallelism for _ in keys],
-            writer_partitions=[make_writer_partition(0, 2, split_dim) for _ in keys],
-        )
-        self.assertTrue(all(r != 0 for r in invalid_results), f"expected invalid combined routing request: {invalid_results}")
-
-        for rank in range(tp_size):
-            wrapper_shards = self.store.batch_get_tensor_with_tp(
-                keys, tp_rank=rank, tp_size=tp_size
-            )
-
-            shard_parallelism = make_tensor_parallelism([
-                make_parallel_axis("tp", rank=rank, size=tp_size, split_dim=split_dim)
-            ])
-
-            target = make_read_target("shard", shard_parallelism)
-            unified_shards = self.store.batch_get_tensor_with_parallelism(
-                keys, [target for _ in keys]
-            )
-
-            self.assertEqual(len(wrapper_shards), num_tensors)
-            self.assertEqual(len(unified_shards), num_tensors)
-            for i in range(num_tensors):
-                expected = tensors[i].chunk(tp_size, split_dim)[rank]
-                self.assertTrue(torch.equal(wrapper_shards[i], expected))
-                self.assertTrue(torch.equal(unified_shards[i], expected))
-                self.assertTrue(torch.equal(unified_shards[i], wrapper_shards[i]))
-
-    def test_15_unified_parallelism_multi_axis_shard_round_trip(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_dp_tp_shard"
-        tensor = make_deterministic_tensor((4, 6))
-        parallelism = build_dp_tp_parallelism(
-            dp_rank=1, dp_size=2, tp_rank=0, tp_size=3, split_dim=1
-        )
-
-        rc = put_full_tensor_with_parallelism_template(
-            self.store, key, tensor, parallelism
-        )
-        self.assertEqual(rc, 0)
-
-        target = make_read_target("shard", parallelism)
-        result = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(result)
-        self.assertTrue(torch.equal(result, tensor.chunk(3, 1)[0]))
-
-    def test_16_unified_parallelism_multi_axis_into_round_trip(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_pp_tp_into"
-        tensor = make_deterministic_tensor((6, 8))
-        parallelism = build_pp_tp_parallelism(
-            pp_rank=0, pp_size=2, stage_id=7, tp_rank=1, tp_size=2, split_dim=0
-        )
-        buffer_spacing = 1 * 1024 * 1024
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            rc = put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            self.assertEqual(rc, 0)
-            target = make_read_target("shard", parallelism)
-            result = self.store.get_tensor_with_parallelism_into(
-                key, buffer_ptr, buffer_spacing, target=target
-            )
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, tensor.chunk(2, 0)[1]))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_17_unified_parallelism_rejects_invalid_axis_fields(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_invalid_axis"
-        tensor = torch.randn(8, 8, dtype=torch.float32)
-
-        invalid_dp = make_tensor_parallelism([
-            make_parallel_axis("dp", rank=0, size=2, split_dim=0)
-        ])
-        self.assertNotEqual(
-            self.store.put_tensor_with_parallelism(key, tensor, invalid_dp), 0
-        )
-
-        invalid_ep = make_tensor_parallelism([
-            make_parallel_axis("ep", rank=0, size=2)
-        ])
-        self.assertNotEqual(
-            self.store.put_tensor_with_parallelism(key, tensor, invalid_ep), 0
-        )
-
-    def test_18_batch_unified_parallelism_multi_axis_round_trip(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (
-                "func_unified_batch_dp_tp_0",
-                make_deterministic_tensor((4, 6)),
-                build_dp_tp_parallelism(0, 2, 1, 3, 1),
-                lambda tensor: tensor.chunk(3, 1)[1],
-            ),
-            (
-                "func_unified_batch_pp_tp_1",
-                make_deterministic_tensor((6, 8)),
-                build_pp_tp_parallelism(1, 2, 9, 0, 2, 0),
-                lambda tensor: tensor.chunk(2, 0)[0],
-            ),
-        ]
-        keys = [key for key, _, _, _ in cases]
-        tensors = [tensor for _, tensor, _, _ in cases]
-        parallelisms = [parallelism for _, _, parallelism, _ in cases]
-        results = [
-            put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            for key, tensor, parallelism in zip(keys, tensors, parallelisms)
-        ]
-        self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        targets = [make_read_target("shard", parallelism) for parallelism in parallelisms]
-        shard_reads = self.store.batch_get_tensor_with_parallelism(keys, targets)
-        self.assertEqual(len(shard_reads), len(cases))
-        for i, (_, tensor, _, expected_fn) in enumerate(cases):
-            self.assertIsNotNone(shard_reads[i], f"batch shard missing for tensor {i}")
-            self.assertTrue(torch.equal(shard_reads[i], expected_fn(tensor)))
-
-    def test_19_batch_unified_parallelism_multi_axis_into_round_trip(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (
-                "func_unified_batch_into_dp_tp_0",
-                make_deterministic_tensor((4, 9)),
-                build_dp_tp_parallelism(1, 2, 2, 3, 1),
-                lambda tensor: tensor.chunk(3, 1)[2],
-            ),
-            (
-                "func_unified_batch_into_pp_tp_1",
-                make_deterministic_tensor((8, 6)),
-                build_pp_tp_parallelism(0, 2, 5, 1, 2, 0),
-                lambda tensor: tensor.chunk(2, 0)[1],
-            ),
-        ]
-        keys = [key for key, _, _, _ in cases]
-        tensors = [tensor for _, tensor, _, _ in cases]
-        parallelisms = [parallelism for _, _, parallelism, _ in cases]
-        results = [
-            put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            for key, tensor, parallelism in zip(keys, tensors, parallelisms)
-        ]
-        self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        buffer_sizes = [max(serialized_tensor_size(tensor) + 4096, 1 * 1024 * 1024) for tensor in tensors]
-        total_buffer_size = sum(buffer_sizes)
-        backing_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        backing_buffer_ptr = ctypes.addressof(backing_buffer)
-        buffer_ptrs = []
-        offset = 0
-        for size in buffer_sizes:
-            buffer_ptrs.append(backing_buffer_ptr + offset)
-            offset += size
-
-        targets = [make_read_target("shard", parallelism) for parallelism in parallelisms]
-        self.assertEqual(self.store.register_buffer(backing_buffer_ptr, total_buffer_size), 0)
-        try:
-            shard_reads = self.store.batch_get_tensor_with_parallelism_into(
-                keys, buffer_ptrs, buffer_sizes, targets
-            )
-            self.assertEqual(len(shard_reads), len(cases))
-            for i, (_, tensor, _, expected_fn) in enumerate(cases):
-                self.assertIsNotNone(shard_reads[i], f"batch shard into missing for tensor {i}")
-                self.assertTrue(torch.equal(shard_reads[i], expected_fn(tensor)))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(backing_buffer_ptr), 0)
-
-    def test_20_unified_parallelism_full_reconstructs_tensor(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_full"
-        tensor = torch.arange(32, dtype=torch.float32).view(4, 8).contiguous()
-        tp_size = 4
-        split_dim = 1
-
-        rc = put_uniform_full_tensor_with_unified_tp(
-            self.store, key, tensor, tp_size, split_dim
-        )
-        self.assertEqual(rc, 0)
-
-        target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=0))
-        unified_full = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(unified_full)
-        self.assertTrue(torch.equal(unified_full, tensor))
-
-    def test_21_unified_parallelism_multi_axis_full_reconstructs_tensor(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_multi_axis_full"
-        tensor = make_deterministic_tensor((6, 8))
-        parallelism = build_dp_tp_parallelism(
-            dp_rank=1, dp_size=2, tp_rank=0, tp_size=4, split_dim=1
-        )
-
-        rc = put_full_tensor_with_parallelism_template(
-            self.store, key, tensor, parallelism
-        )
-        self.assertEqual(rc, 0)
-
-        full_target = make_read_target(
-            "full",
-            build_dp_tp_parallelism(
-                dp_rank=1, dp_size=2, tp_rank=2, tp_size=4, split_dim=1
-            ),
-        )
-        result = self.store.get_tensor_with_parallelism(key, full_target)
-        self.assertIsNotNone(result)
-        self.assertTrue(torch.equal(result, tensor))
-
-    def test_22_unified_parallelism_multi_axis_full_into_reconstructs_tensor(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_multi_axis_full_into"
-        tensor = make_deterministic_tensor((8, 6))
-        parallelism = build_pp_tp_parallelism(
-            pp_rank=0, pp_size=2, stage_id=4, tp_rank=0, tp_size=2, split_dim=0
-        )
-        buffer_spacing = 1 * 1024 * 1024
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            rc = put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            self.assertEqual(rc, 0)
-            full_target = make_read_target(
-                "full",
-                build_pp_tp_parallelism(
-                    pp_rank=0, pp_size=2, stage_id=4, tp_rank=1, tp_size=2, split_dim=0
-                ),
-            )
-            result = self.store.get_tensor_with_parallelism_into(
-                key, buffer_ptr, buffer_spacing, target=full_target
-            )
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, tensor))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_23_unified_parallelism_into_matches_wrapper(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_into"
-        tensor = torch.randn(16, 16, dtype=torch.float32)
-        tp_size = 2
-        split_dim = 0
-        buffer_spacing = 1 * 1024 * 1024
-        total_buffer_size = buffer_spacing * 2
-
-        large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        large_buffer_ptr = ctypes.addressof(large_buffer)
-        wrapper_ptr = large_buffer_ptr
-        unified_ptr = large_buffer_ptr + buffer_spacing
-
-        self.assertEqual(self.store.register_buffer(large_buffer_ptr, total_buffer_size), 0)
-        try:
-            parallelism = make_tensor_parallelism([
-                make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)
-            ])
-            shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, 0).contiguous()
-            rc = self.store.put_tensor_with_parallelism(key, shard, parallelism)
-            self.assertEqual(rc, 0)
-
-            target = make_read_target("shard", parallelism)
-            wrapper_tensor = self.store.get_tensor_with_tp_into(
-                key, wrapper_ptr, buffer_spacing, tp_rank=0, tp_size=tp_size, split_dim=split_dim
-            )
-            unified_tensor = self.store.get_tensor_with_parallelism_into(
-                key, unified_ptr, buffer_spacing, target=target
-            )
-            self.assertIsNotNone(wrapper_tensor)
-            self.assertIsNotNone(unified_tensor)
-            self.assertTrue(torch.equal(unified_tensor, wrapper_tensor))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0)
-
-    def test_24_unified_parallelism_from_matches_wrapper(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_from"
-        seed_key = "func_unified_tp_from_seed"
-        tensor = torch.randn(16, 16, dtype=torch.float32)
-        tp_size = 2
-        split_dim = 1
-        buffer_spacing = 1 * 1024 * 1024
-
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            rc = self.store.put_tensor(seed_key, tensor)
-            self.assertEqual(rc, 0)
-            full_tensor = self.store.get_tensor_into(seed_key, buffer_ptr, buffer_spacing)
-            self.assertIsNotNone(full_tensor)
-            full_size = serialized_tensor_size(full_tensor)
-
-            parallelism = make_tensor_parallelism([
-                make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)
-            ])
-            rc = self.store.put_tensor_with_parallelism_from(
-                key, buffer_ptr, full_size, parallelism
-            )
-            self.assertEqual(rc, 0)
-
-            target = make_read_target("shard", parallelism)
-            unified_shard = self.store.get_tensor_with_parallelism(key, target)
-            wrapper_shard = self.store.get_tensor_with_tp(
-                key, tp_rank=0, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertIsNotNone(unified_shard)
-            self.assertTrue(torch.equal(unified_shard, wrapper_shard))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_25_unified_parallelism_full_into_reconstructs_tensor(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_full_into"
-        tensor = torch.arange(4 * 9 * 6, dtype=torch.float32).view(4, 9, 6).contiguous()
-        self.assert_full_into_reconstruction_case(
-            key=key,
-            tensor=tensor,
-            split_dim=1,
-            tp_size=3,
-            buffer_spacing=1 * 1024 * 1024,
-        )
-
-    def test_26_unified_parallelism_full_reconstruction_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((8, 12), 0, 4),
-            ((8, 12), 0, 8),
-            ((8, 12), 0, 16),
-            ((10, 12), 0, 4),
-            ((12, 9), 1, 3),
-            ((12, 9), 1, 9),
-            ((12, 9), 1, 16),
-            ((12, 10), 1, 4),
-            ((4, 10, 6), 1, 4),
-            ((4, 5, 7), 2, 8),
-        ]
-
-        for index, (shape, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(case=reconstruction_case_name(shape, split_dim, tp_size)):
-                tensor = make_deterministic_tensor(shape)
-                key = f"func_unified_tp_matrix_{index}"
-                if is_uniform_tp_case(shape, split_dim, tp_size):
-                    self.assert_full_reconstruction_case(
-                        key=key,
-                        tensor=tensor,
-                        split_dim=split_dim,
-                        tp_size=tp_size,
-                    )
-                else:
-                    rc = put_uniform_full_tensor_with_unified_tp(
-                        self.store, key, tensor, tp_size, split_dim
-                    )
-                    self.assertNotEqual(rc, 0)
-
-    def test_27_unified_parallelism_full_into_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((8, 12), 0, 16),
-            ((12, 10), 1, 4),
-            ((4, 10, 6), 1, 4),
-            ((4, 5, 7), 2, 8),
-        ]
-
-        for index, (shape, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(case=reconstruction_case_name(shape, split_dim, tp_size)):
-                tensor = make_deterministic_tensor(shape)
-                key = f"func_unified_tp_full_into_matrix_{index}"
-                if is_uniform_tp_case(shape, split_dim, tp_size):
-                    buffer_spacing = max(serialized_tensor_size(tensor) + 4096, 1 * 1024 * 1024)
-                    self.assert_full_into_reconstruction_case(
-                        key=key,
-                        tensor=tensor,
-                        split_dim=split_dim,
-                        tp_size=tp_size,
-                        buffer_spacing=buffer_spacing,
-                    )
-                else:
-                    rc = put_uniform_full_tensor_with_unified_tp(
-                        self.store, key, tensor, tp_size, split_dim
-                    )
-                    self.assertNotEqual(rc, 0)
-
-    def test_27b_unified_parallelism_full_into_formula_all_split_dims_and_hetero_tp(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((8, 12, 16), 0, 4, [2, 4, 8]),
-            ((8, 12, 16), 1, 4, [2, 3, 4, 6]),
-            ((8, 12, 16), 2, 4, [2, 4, 8, 16]),
-        ]
-        for case_index, (shape, split_dim, write_tp_size, read_tp_sizes) in enumerate(cases):
-            tensor = make_deterministic_tensor(shape)
-            for read_tp_size in read_tp_sizes:
-                with self.subTest(
-                    case=f"split_dim={split_dim},write_tp={write_tp_size},read_tp={read_tp_size}"
-                ):
-                    key = f"func_unified_formula_split_{case_index}_{read_tp_size}"
-                    self.assertEqual(shape[split_dim] % read_tp_size, 0)
-                    rc = put_uniform_full_tensor_with_unified_tp(
-                        self.store, key, tensor, write_tp_size, split_dim
-                    )
-                    self.assertEqual(rc, 0)
-                    target = make_read_target(
-                        "full",
-                        build_tp_parallelism(
-                            read_tp_size, split_dim, rank=read_tp_size - 1
-                        ),
-                    )
-                    full_result = self.store.get_tensor_with_parallelism(
-                        key, target
-                    )
-                    self.assertIsNotNone(full_result)
-                    self.assertTrue(torch.equal(full_result, tensor))
-
-                    buffer_spacing = max(
-                        serialized_tensor_size(tensor) + 4096, 1 * 1024 * 1024
-                    )
-                    buffer = (ctypes.c_ubyte * buffer_spacing)()
-                    buffer_ptr = ctypes.addressof(buffer)
-                    self.assertEqual(
-                        self.store.register_buffer(buffer_ptr, buffer_spacing), 0
-                    )
-                    try:
-                        into_result = self.store.get_tensor_with_parallelism_into(
-                            key, buffer_ptr, buffer_spacing, target=target
-                        )
-                        self.assertIsNotNone(into_result)
-                        self.assertTrue(torch.equal(into_result, tensor))
-                    finally:
-                        self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_28_writer_shard_full_reconstruction(self):
-        require_unified_parallelism_api(self)
-        key = "func_writer_shard_full"
-        tensor = make_deterministic_tensor((6, 8))
-        self.assert_writer_shard_full_reconstruction_case(
-            key=key, tensor=tensor, split_dim=1, shard_count=4
-        )
-
-    def test_29_writer_shard_full_into_reconstruction(self):
-        require_unified_parallelism_api(self)
-        key = "func_writer_shard_full_into"
-        tensor = make_deterministic_tensor((8, 6))
-        buffer_spacing = max(serialized_tensor_size(tensor) + 4096, 1 * 1024 * 1024)
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            for rank in range(3):
-                rc = self.store.put_tensor_with_parallelism(
-                    key,
-                    tensor,
-                    writer_partition=make_writer_partition(rank, 3, 1),
-                )
-                self.assertEqual(rc, 0)
-
-            result = self.store.get_tensor_with_parallelism_into(
-                key, buffer_ptr, buffer_spacing, target=make_read_target("full")
-            )
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, tensor))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_30_batch_writer_partition_full_reconstruction(self):
-        require_unified_parallelism_api(self)
-        tensors = [
-            make_deterministic_tensor((8, 12)),
-            make_deterministic_tensor((6, 9, 4)),
-            make_deterministic_tensor((12, 12)),
-        ]
-        keys = [f"func_writer_partition_batch_{i}" for i in range(len(tensors))]
-        writer_partitions = [
-            make_writer_partition(rank=0, size=4, split_dim=1),
-            make_writer_partition(rank=1, size=3, split_dim=0),
-            make_writer_partition(rank=2, size=4, split_dim=1),
-        ]
-
-        for rank in range(4):
-            batch_writer_partitions = [
-                make_writer_partition(rank=min(rank, part.size - 1), size=part.size, split_dim=part.split_dim)
-                for part in writer_partitions
-            ]
-            results = self.store.batch_put_tensor_with_parallelism(
-                keys,
-                tensors,
-                writer_partitions=batch_writer_partitions,
-            )
-            self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        full_targets = [make_read_target("full") for _ in tensors]
-        full_reads = self.store.batch_get_tensor_with_parallelism(keys, full_targets)
-        self.assertEqual(len(full_reads), len(tensors))
-        for i, tensor in enumerate(tensors):
-            self.assertTrue(torch.equal(full_reads[i], tensor), f"full reconstruction mismatch for tensor {i}")
-
-    def test_31_batch_writer_partition_into_round_trip(self):
-        require_unified_parallelism_api(self)
-        tensors = [
-            make_deterministic_tensor((7, 9)),
-            make_deterministic_tensor((8, 6)),
-        ]
-        keys = [f"func_writer_partition_batch_into_{i}" for i in range(len(tensors))]
-        writer_layouts = [
-            make_writer_partition(rank=0, size=3, split_dim=1),
-            make_writer_partition(rank=0, size=2, split_dim=0),
-        ]
-        for rank in range(3):
-            batch_writer_partitions = [
-                make_writer_partition(rank=min(rank, layout.size - 1), size=layout.size, split_dim=layout.split_dim)
-                for layout in writer_layouts
-            ]
-            results = self.store.batch_put_tensor_with_parallelism(
-                keys,
-                tensors,
-                writer_partitions=batch_writer_partitions,
-            )
-            self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        buffer_sizes = [max(serialized_tensor_size(tensor) + 4096, 1 * 1024 * 1024) for tensor in tensors]
-        total_buffer_size = sum(buffer_sizes)
-        backing_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        backing_buffer_ptr = ctypes.addressof(backing_buffer)
-        buffer_ptrs = []
-        offset = 0
-        for size in buffer_sizes:
-            buffer_ptrs.append(backing_buffer_ptr + offset)
-            offset += size
-
-        self.assertEqual(self.store.register_buffer(backing_buffer_ptr, total_buffer_size), 0)
-        try:
-            full_reads = self.store.batch_get_tensor_with_parallelism_into(
-                keys, buffer_ptrs, buffer_sizes, [make_read_target("full") for _ in tensors]
-            )
-            self.assertEqual(len(full_reads), len(tensors))
-            for i, tensor in enumerate(tensors):
-                self.assertIsNotNone(full_reads[i], f"batch full into missing for tensor {i}")
-                self.assertTrue(torch.equal(full_reads[i], tensor), f"batch full into mismatch for tensor {i}")
-        finally:
-            self.assertEqual(self.store.unregister_buffer(backing_buffer_ptr), 0)
-
-    def test_32_batch_unified_parallelism_full_reconstruction(self):
-        require_unified_parallelism_api(self)
-        tp_size = 4
-        split_dim = 1
-        tensors = [
-            make_deterministic_tensor((8, 12)),
-            make_deterministic_tensor((6, 12, 4)),
-            make_deterministic_tensor((12, 12)),
-        ]
-        keys = [f"func_unified_tp_full_batch_{i}" for i in range(len(tensors))]
-        results = batch_put_full_tensors_with_unified_tp(self.store, keys, tensors, tp_size, split_dim)
-        self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        full_targets = [make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=1)) for _ in tensors]
-        full_reads = self.store.batch_get_tensor_with_parallelism(keys, full_targets)
-        self.assertEqual(len(full_reads), len(tensors))
-        for i, tensor in enumerate(tensors):
-            self.assertTrue(torch.equal(full_reads[i], tensor), f"full reconstruction mismatch for tensor {i}")
-
-        shard_targets = [make_read_target("shard", build_tp_parallelism(tp_size, split_dim, rank=2)) for _ in tensors]
-        shard_reads = self.store.batch_get_tensor_with_parallelism(keys, shard_targets)
-        self.assertEqual(len(shard_reads), len(tensors))
-        for i, tensor in enumerate(tensors):
-            expected_shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, 2)
-            self.assertTrue(torch.equal(shard_reads[i], expected_shard), f"shard mismatch for tensor {i}")
-
-    def test_31_batch_unified_parallelism_multi_axis_full_reconstruction(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (
-                "func_unified_batch_multi_full_0",
-                make_deterministic_tensor((6, 8)),
-                build_dp_tp_parallelism(1, 2, 0, 4, 1),
-                build_dp_tp_parallelism(1, 2, 2, 4, 1),
-            ),
-            (
-                "func_unified_batch_multi_full_1",
-                make_deterministic_tensor((8, 6)),
-                build_pp_tp_parallelism(0, 2, 6, 0, 2, 0),
-                build_pp_tp_parallelism(0, 2, 6, 1, 2, 0),
-            ),
-        ]
-        keys = [key for key, _, _, _ in cases]
-        tensors = [tensor for _, tensor, _, _ in cases]
-        write_parallelisms = [parallelism for _, _, parallelism, _ in cases]
-        results = [
-            put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            for key, tensor, parallelism in zip(keys, tensors, write_parallelisms)
-        ]
-        self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        full_targets = [make_read_target("full", target_parallelism) for _, _, _, target_parallelism in cases]
-        full_reads = self.store.batch_get_tensor_with_parallelism(keys, full_targets)
-        self.assertEqual(len(full_reads), len(cases))
-        for i, tensor in enumerate(tensors):
-            self.assertIsNotNone(full_reads[i], f"multi-axis full missing for tensor {i}")
-            self.assertTrue(torch.equal(full_reads[i], tensor), f"multi-axis full mismatch for tensor {i}")
-
-    def test_32_unified_parallelism_multi_axis_full_remaps_axis_order(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_multi_axis_full_remap_order"
-        tensor = make_deterministic_tensor((6, 8))
-        write_parallelism = build_dp_tp_parallelism(
-            dp_rank=1, dp_size=2, tp_rank=0, tp_size=4, split_dim=1
-        )
-        read_parallelism = reorder_parallelism_axes(write_parallelism, ["tp", "dp"])
-        read_parallelism.axes[0].rank = 3
-
-        rc = put_full_tensor_with_parallelism_template(
-            self.store, key, tensor, write_parallelism
-        )
-        self.assertEqual(rc, 0)
-
-        full_target = make_read_target("full", read_parallelism)
-        result = self.store.get_tensor_with_parallelism(key, full_target)
-        self.assertIsNotNone(result)
-        self.assertTrue(torch.equal(result, tensor))
-
-    def test_33_unified_parallelism_multi_axis_full_into_remaps_axis_order(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_multi_axis_full_into_remap_order"
-        tensor = make_deterministic_tensor((8, 6))
-        write_parallelism = build_pp_tp_parallelism(
-            pp_rank=0, pp_size=2, stage_id=4, tp_rank=0, tp_size=2, split_dim=0
-        )
-        read_parallelism = reorder_parallelism_axes(write_parallelism, ["tp", "pp"])
-        read_parallelism.axes[0].rank = 1
-        buffer_spacing = 1 * 1024 * 1024
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        try:
-            rc = put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, write_parallelism
-            )
-            self.assertEqual(rc, 0)
-            full_target = make_read_target("full", read_parallelism)
-            result = self.store.get_tensor_with_parallelism_into(
-                key, buffer_ptr, buffer_spacing, target=full_target
-            )
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, tensor))
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_34_batch_unified_parallelism_multi_axis_full_remaps_axis_order(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (
-                "func_unified_batch_multi_full_remap_0",
-                make_deterministic_tensor((6, 8)),
-                build_dp_tp_parallelism(1, 2, 0, 4, 1),
-                reorder_parallelism_axes(build_dp_tp_parallelism(1, 2, 2, 4, 1), ["tp", "dp"]),
-            ),
-            (
-                "func_unified_batch_multi_full_remap_1",
-                make_deterministic_tensor((8, 6)),
-                build_pp_tp_parallelism(0, 2, 6, 0, 2, 0),
-                reorder_parallelism_axes(build_pp_tp_parallelism(0, 2, 6, 1, 2, 0), ["tp", "pp"]),
-            ),
-        ]
-        keys = [key for key, _, _, _ in cases]
-        tensors = [tensor for _, tensor, _, _ in cases]
-        write_parallelisms = [parallelism for _, _, parallelism, _ in cases]
-        read_parallelisms = [parallelism for _, _, _, parallelism in cases]
-        results = [
-            put_full_tensor_with_parallelism_template(
-                self.store, key, tensor, parallelism
-            )
-            for key, tensor, parallelism in zip(keys, tensors, write_parallelisms)
-        ]
-        self.assertTrue(all(r == 0 for r in results), f"batch put failed: {results}")
-
-        full_targets = [make_read_target("full", target_parallelism) for target_parallelism in read_parallelisms]
-        full_reads = self.store.batch_get_tensor_with_parallelism(keys, full_targets)
-        self.assertEqual(len(full_reads), len(cases))
-        for i, tensor in enumerate(tensors):
-            self.assertIsNotNone(full_reads[i], f"multi-axis remap full missing for tensor {i}")
-            self.assertTrue(torch.equal(full_reads[i], tensor), f"multi-axis remap full mismatch for tensor {i}")
-
-    def test_35_unified_parallelism_full_large_payload(self):
-        require_unified_parallelism_api(self)
-        key = "func_unified_tp_full_large"
-        tensor = make_deterministic_tensor((32, 32))
-        split_dim = 1
-        tp_size = 4
-        buffer_spacing = serialized_tensor_size(tensor) + 1 * 1024 * 1024
-
-        rc = put_uniform_full_tensor_with_unified_tp(
-            self.store, key, tensor, tp_size, split_dim
-        )
-        self.assertEqual(rc, 0)
-
-        full_target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=1))
-        full_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-        self.assertIsNotNone(full_tensor)
-        self.assertTrue(torch.equal(full_tensor, tensor))
-
-        shard_rank = 3
-        shard_target = make_read_target("shard", build_tp_parallelism(tp_size, split_dim, rank=shard_rank))
-        shard_tensor = self.store.get_tensor_with_parallelism(key, shard_target)
-        expected_shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, shard_rank)
-        self.assertIsNotNone(shard_tensor)
-        self.assertTrue(torch.equal(shard_tensor, expected_shard))
-
-        self.assert_full_into_reconstruction_case(
-            key=f"{key}_into",
-            tensor=tensor,
-            split_dim=split_dim,
-            tp_size=tp_size,
-            buffer_spacing=buffer_spacing,
-        )
-
-    def test_36_unified_parallelism_full_reconstruction_edge_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((7,), 0, 8),
-            ((9,), 0, 4),
-            ((3, 5, 7), 2, 16),
-            ((5, 11, 3), 1, 8),
-        ]
-
-        for index, (shape, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(case=reconstruction_case_name(shape, split_dim, tp_size)):
-                tensor = make_deterministic_tensor(shape)
-                key = f"func_unified_tp_edge_matrix_{index}"
-                rc = put_uniform_full_tensor_with_unified_tp(
-                    self.store, key, tensor, tp_size, split_dim
-                )
-                self.assertNotEqual(rc, 0)
-
-    def test_37_batch_unified_parallelism_full_into_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (make_deterministic_tensor((7,)), 0, 8),
-            (make_deterministic_tensor((8, 12)), 0, 16),
-            (make_deterministic_tensor((4, 5, 7)), 2, 8),
-        ]
-        for index, (tensor, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(case=reconstruction_case_name(tuple(tensor.shape), split_dim, tp_size)):
-                rc = put_uniform_full_tensor_with_unified_tp(
-                    self.store,
-                    f"func_unified_tp_batch_full_into_{index}",
-                    tensor,
-                    tp_size,
-                    split_dim,
-                )
-                self.assertNotEqual(rc, 0)
-
-    def test_38_batch_unified_parallelism_full_ragged_cases(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (make_deterministic_tensor((7,)), 0, 8),
-            (make_deterministic_tensor((8, 12)), 0, 16),
-            (make_deterministic_tensor((11, 9)), 1, 4),
-            (make_deterministic_tensor((3, 5, 7)), 2, 16),
-        ]
-        for index, (tensor, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(case=reconstruction_case_name(tuple(tensor.shape), split_dim, tp_size)):
-                rc = put_uniform_full_tensor_with_unified_tp(
-                    self.store,
-                    f"func_unified_tp_batch_ragged_{index}",
-                    tensor,
-                    tp_size,
-                    split_dim,
-                )
-                self.assertNotEqual(rc, 0)
-
-    def test_39_unified_parallelism_full_dtype_smoke(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            (torch.float16, (8, 12), 1, 4),
-            (torch.bfloat16, (9,), 0, 16),
-        ]
-
-        for index, (dtype, shape, split_dim, tp_size) in enumerate(cases):
-            with self.subTest(dtype=str(dtype), case=reconstruction_case_name(shape, split_dim, tp_size)):
-                tensor = make_deterministic_tensor(shape, dtype=dtype)
-                key = f"func_unified_tp_dtype_{index}"
-                if is_uniform_tp_case(shape, split_dim, tp_size):
-                    self.assert_full_reconstruction_case(
-                        key=key,
-                        tensor=tensor,
-                        split_dim=split_dim,
-                        tp_size=tp_size,
-                    )
-                else:
-                    rc = put_uniform_full_tensor_with_unified_tp(
-                        self.store, key, tensor, tp_size, split_dim
-                    )
-                    self.assertNotEqual(rc, 0)
-
-    def test_40_unified_parallelism_target_shard_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((8, 12, 6), 0, 4, 2, "tp"),
-            ((8, 12, 6), 1, 4, 2, "dp_tp"),
-            ((8, 12, 6), 2, 2, 4, "pp_tp"),
-            ((8, 12, 6), 1, 2, 4, "ep_tp"),
-            ((12, 8, 6), 0, 2, 2, "tp"),
-            ((12, 8, 8), 2, 4, 4, "dp_tp"),
-        ]
-
-        for index, (shape, split_dim, put_tp_size, get_tp_size, mode) in enumerate(cases):
-            with self.subTest(shape=shape, split_dim=split_dim, put_tp_size=put_tp_size, get_tp_size=get_tp_size, mode=mode):
-                tensor = make_deterministic_tensor(shape)
-                key = f"func_unified_target_shard_matrix_{index}"
-                rc = put_full_tensor_with_parallelism_mode(
-                    self.store, key, tensor, split_dim, put_tp_size, mode
-                )
-                self.assertEqual(rc, 0)
-
-                if not is_uniform_tp_case(shape, split_dim, get_tp_size):
-                    target_parallelism = build_parallelism_mode(
-                        mode, 0, get_tp_size, split_dim
-                    )
-                    target = make_read_target("shard", target_parallelism)
-                    shard = self.store.get_tensor_with_parallelism(key, target)
-                    self.assertIsNone(shard)
-                    continue
-
-                for target_rank in range(get_tp_size):
-                    target_parallelism = build_parallelism_mode(
-                        mode, target_rank, get_tp_size, split_dim
-                    )
-                    target = make_read_target("shard", target_parallelism)
-                    shard = self.store.get_tensor_with_parallelism(key, target)
-                    expected = expected_target_shard(
-                        tensor, split_dim, get_tp_size, target_rank
-                    )
-                    self.assertIsNotNone(shard)
-                    self.assertTrue(
-                        torch.equal(shard, expected),
-                        f"target shard mismatch for mode={mode}, rank={target_rank}",
-                    )
-
-    def test_41_unified_parallelism_target_shard_into_matrix(self):
-        require_unified_parallelism_api(self)
-        cases = [
-            ((8, 12, 6), 0, 4, 2, "tp"),
-            ((8, 12, 6), 1, 4, 2, "dp_tp"),
-            ((8, 12, 6), 2, 2, 4, "pp_tp"),
-            ((8, 12, 6), 1, 2, 4, "ep_tp"),
-        ]
-
-        for index, (shape, split_dim, put_tp_size, get_tp_size, mode) in enumerate(cases):
-            with self.subTest(shape=shape, split_dim=split_dim, put_tp_size=put_tp_size, get_tp_size=get_tp_size, mode=mode):
-                tensor = make_deterministic_tensor(shape)
-                key = f"func_unified_target_shard_into_matrix_{index}"
-                rc = put_full_tensor_with_parallelism_mode(
-                    self.store, key, tensor, split_dim, put_tp_size, mode
-                )
-                self.assertEqual(rc, 0)
-
-                if not is_uniform_tp_case(shape, split_dim, get_tp_size):
-                    buffer_spacing = 1 * 1024 * 1024
-                    buffer = (ctypes.c_ubyte * buffer_spacing)()
-                    buffer_ptr = ctypes.addressof(buffer)
-                    self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-                    try:
-                        target_parallelism = build_parallelism_mode(
-                            mode, 0, get_tp_size, split_dim
-                        )
-                        target = make_read_target("shard", target_parallelism)
-                        shard = self.store.get_tensor_with_parallelism_into(
-                            key, buffer_ptr, buffer_spacing, target=target
-                        )
-                        self.assertIsNone(shard)
-                    finally:
-                        self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-                    continue
-
-                for target_rank in range(get_tp_size):
-                    expected = expected_target_shard(
-                        tensor, split_dim, get_tp_size, target_rank
-                    )
-                    buffer_spacing = max(serialized_tensor_size(expected) + 4096, 1 * 1024 * 1024)
-                    buffer = (ctypes.c_ubyte * buffer_spacing)()
-                    buffer_ptr = ctypes.addressof(buffer)
-                    self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-                    try:
-                        target_parallelism = build_parallelism_mode(
-                            mode, target_rank, get_tp_size, split_dim
-                        )
-                        target = make_read_target("shard", target_parallelism)
-                        shard = self.store.get_tensor_with_parallelism_into(
-                            key, buffer_ptr, buffer_spacing, target=target
-                        )
-                        self.assertIsNotNone(shard)
-                        self.assertTrue(
-                            torch.equal(shard, expected),
-                            f"target shard into mismatch for mode={mode}, rank={target_rank}",
-                        )
-                    finally:
-                        self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_42_unified_parallelism_mb_scale_target_shard_matrix(self):
-        require_unified_parallelism_api(self)
-        original = make_mb_scale_original_tensor()
-        cases = [
-            (0, 4, 2, "tp"),
-            (1, 4, 2, "dp_tp"),
-            (2, 4, 2, "pp_tp"),
-            (2, 4, 2, "ep_tp"),
-        ]
-
-        for index, (split_dim, put_tp_size, get_tp_size, mode) in enumerate(cases):
-            key = f"func_unified_mb_target_shard_{index}"
-            with self.subTest(split_dim=split_dim, put_tp_size=put_tp_size,
-                              get_tp_size=get_tp_size, mode=mode):
-                rc = put_full_tensor_with_parallelism_mode(
-                    self.store, key, original, split_dim, put_tp_size, mode
-                )
-                self.assertEqual(rc, 0)
-                for target_rank in range(get_tp_size):
-                    target_parallelism = build_parallelism_mode(
-                        mode, target_rank, get_tp_size, split_dim
-                    )
-                    target = make_read_target("shard", target_parallelism)
-                    shard = self.store.get_tensor_with_parallelism(key, target)
-                    assert_tensor_matches_expected_shard(
-                        self, original, shard, split_dim, get_tp_size, target_rank,
-                        context=(
-                            f"mb shard read mode={mode} split_dim={split_dim} "
-                            f"target_rank={target_rank}"
-                        ),
-                    )
-
-    def test_43_unified_parallelism_mb_scale_target_shard_into_matrix(self):
-        require_unified_parallelism_api(self)
-        original = make_mb_scale_original_tensor()
-        cases = [
-            (0, 4, 2, "tp"),
-            (1, 4, 2, "dp_tp"),
-            (2, 4, 2, "pp_tp"),
-            (2, 4, 2, "ep_tp"),
-        ]
-
-        for index, (split_dim, put_tp_size, get_tp_size, mode) in enumerate(cases):
-            key = f"func_unified_mb_target_shard_into_{index}"
-            with self.subTest(split_dim=split_dim, put_tp_size=put_tp_size,
-                              get_tp_size=get_tp_size, mode=mode):
-                rc = put_full_tensor_with_parallelism_mode(
-                    self.store, key, original, split_dim, put_tp_size, mode
-                )
-                self.assertEqual(rc, 0)
-                for target_rank in range(get_tp_size):
-                    expected = expected_target_shard(
-                        original, split_dim, get_tp_size, target_rank
-                    )
-                    buffer_spacing = max(
-                        serialized_tensor_size(expected) + 4096,
-                        1 * 1024 * 1024,
-                    )
-                    buffer = (ctypes.c_ubyte * buffer_spacing)()
-                    buffer_ptr = ctypes.addressof(buffer)
-                    self.assertEqual(
-                        self.store.register_buffer(buffer_ptr, buffer_spacing), 0
-                    )
-                    try:
-                        target_parallelism = build_parallelism_mode(
-                            mode, target_rank, get_tp_size, split_dim
-                        )
-                        target = make_read_target("shard", target_parallelism)
-                        shard = self.store.get_tensor_with_parallelism_into(
-                            key, buffer_ptr, buffer_spacing, target=target
-                        )
-                        assert_tensor_matches_expected_shard(
-                            self, original, shard, split_dim, get_tp_size,
-                            target_rank,
-                            context=(
-                                f"mb shard into mode={mode} split_dim={split_dim} "
-                                f"target_rank={target_rank}"
-                            ),
-                        )
-                    finally:
-                        self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-    def test_44_unified_parallelism_concurrency_relation_matrix(self):
-        require_unified_parallelism_api(self)
-        original = make_mb_scale_original_tensor()
-        scenarios = [
-            (2, 4, [(0, 4, 2, "tp"), (1, 4, 2, "dp_tp"), (2, 4, 2, "pp_tp")]),
-            (3, 3, [(0, 4, 2, "tp"), (1, 4, 2, "dp_tp"), (2, 4, 2, "ep_tp")]),
-            (6, 3, [(0, 4, 2, "tp"), (1, 4, 2, "pp_tp"), (2, 4, 2, "ep_tp")]),
-        ]
-
-        def expand_jobs(cases, worker_count):
-            jobs = list(enumerate(cases))
-            if worker_count <= len(cases):
-                return jobs
-            extra_jobs = worker_count - len(cases)
-            for extra_index in range(extra_jobs):
-                case_index = extra_index % len(cases)
-                jobs.append((case_index, cases[case_index]))
-            return jobs
-
-        def put_worker(key, split_dim, put_tp_size, mode):
-            return put_full_tensor_with_parallelism_mode(
-                self.store, key, original, split_dim, put_tp_size, mode
-            )
-
-        def get_worker(key, split_dim, get_tp_size, mode):
-            for target_rank in range(get_tp_size):
-                target_parallelism = build_parallelism_mode(
-                    mode, target_rank, get_tp_size, split_dim
-                )
-                target = make_read_target("shard", target_parallelism)
-                shard = self.store.get_tensor_with_parallelism(key, target)
-                expected = expected_target_shard(
-                    original, split_dim, get_tp_size, target_rank
-                )
-                if shard is None or not torch.equal(shard, expected):
-                    return (
-                        f"concurrency shard mismatch key={key} split_dim={split_dim} "
-                        f"mode={mode} rank={target_rank}"
-                    )
-            return None
-
-        for scenario_index, (put_workers, get_workers, cases) in enumerate(scenarios):
-            with self.subTest(put_workers=put_workers, get_workers=get_workers):
-                put_jobs = [
-                    (
-                        case_index,
-                        f"func_unified_concurrency_{scenario_index}_put_{job_index}_case_{case_index}",
-                        split_dim,
-                        put_tp_size,
-                        get_tp_size,
-                        mode,
-                    )
-                    for job_index, (case_index, (split_dim, put_tp_size, get_tp_size, mode)) in enumerate(
-                        expand_jobs(cases, put_workers)
-                    )
-                ]
-                case_keys = {}
-                for case_index, key, split_dim, put_tp_size, get_tp_size, mode in put_jobs:
-                    case_keys.setdefault(case_index, []).append(
-                        (key, split_dim, put_tp_size, get_tp_size, mode)
-                    )
-
-                get_jobs = []
-                case_read_counts = {}
-                for case_index, (split_dim, put_tp_size, get_tp_size, mode) in expand_jobs(cases, get_workers):
-                    read_index = case_read_counts.get(case_index, 0)
-                    key, _split_dim, _put_tp_size, _get_tp_size, _mode = case_keys[case_index][
-                        read_index % len(case_keys[case_index])
-                    ]
-                    get_jobs.append((key, split_dim, put_tp_size, get_tp_size, mode))
-                    case_read_counts[case_index] = read_index + 1
-
-                with concurrent.futures.ThreadPoolExecutor(max_workers=max(put_workers, get_workers)) as executor:
-                    put_futures = [
-                        executor.submit(put_worker, key, split_dim, put_tp_size, mode)
-                        for _case_index, key, split_dim, put_tp_size, _get_tp_size, mode in put_jobs
-                    ]
-                    for future in concurrent.futures.as_completed(put_futures):
-                        self.assertEqual(future.result(), 0)
-
-                    get_futures = [
-                        executor.submit(get_worker, key, split_dim, get_tp_size, mode)
-                        for key, split_dim, _put_tp_size, get_tp_size, mode in get_jobs
-                    ]
-                    for future in concurrent.futures.as_completed(get_futures):
-                        error = future.result()
-                        if error:
-                            self.fail(error)
-
-# ==========================================
-#  Performance/Benchmark Tests
-# ==========================================
-
-class TestMooncakeBenchmark(MooncakeTestBase):
-    # Benchmark Settings
-    BENCH_ITERATIONS = 5
-    TENSOR_SIZE_MB = 16
-    TOTAL_SIZE_MB = 256
-
-    def _run_unified_full_manual_gather(self, key, tensor, split_dim, tp_size):
-        shards = []
-        for rank in range(tp_size):
-            shard = self.store.get_tensor_with_tp(
-                key, tp_rank=rank, tp_size=tp_size, split_dim=split_dim
-            )
-            self.assertIsNotNone(shard)
-            shards.append(shard)
-        reconstructed = torch.cat(shards, dim=split_dim)
-        self.assertTrue(torch.equal(reconstructed, tensor))
-        return reconstructed
-
-    def _run_unified_full_into(self, key, target, buffer_ptr, buffer_spacing, tensor):
-        reconstructed = self.store.get_tensor_with_parallelism_into(
-            key, buffer_ptr, buffer_spacing, target
-        )
-        self.assertIsNotNone(reconstructed)
-        self.assertTrue(torch.equal(reconstructed, tensor))
-        return reconstructed
-
-    def setUp(self):
-        """Benchmark-specific setUp."""
-        # 1. Call parent setUp to clean the store (remove_all)
-        super().setUp()
-
-        # 2. Generate test data
-        total_bytes = int(self.TOTAL_SIZE_MB * 1024**2)
-        tensor_bytes = self.TENSOR_SIZE_MB * 1024**2
-        self.num_tensors = max(1, total_bytes // tensor_bytes)
-
-        print(f"\n[Gen] Generating {self.num_tensors} tensors (~{self.TENSOR_SIZE_MB}MB each)...")
-        self.keys, self.tensors = generate_tensors(self.num_tensors, self.TENSOR_SIZE_MB)
-        self.total_bits = (tensor_bytes * self.num_tensors) * 8
-
-    def _print_perf(self, name, times):
-        avg_time = np.mean(times)
-        avg_gbps = (self.total_bits / 1e9) / avg_time
-        print(f"👉 [Result] {name:30} | Avg Time: {avg_time:.4f}s | Throughput: {avg_gbps:.2f} Gbps")
-
-    def test_benchmark_01_batch_put_get(self):
-        """Benchmark: Standard Batch Put/Get."""
-        put_times = []
-        get_times = []
-
-        print(f"--- Running Standard Batch Benchmark ({self.BENCH_ITERATIONS} iters) ---")
-        for i in range(self.BENCH_ITERATIONS):
-            # Clean store before each iteration for "cold" writes
-            self.store.remove_all()
-
-            # Measure Put
-            t0 = time.perf_counter()
-            self.store.batch_put_tensor(self.keys, self.tensors)
-            put_times.append(time.perf_counter() - t0)
-
-            # Measure Get
-            t0 = time.perf_counter()
-            res = self.store.batch_get_tensor(self.keys)
-            get_times.append(time.perf_counter() - t0)
-            self.assertEqual(len(res), len(self.tensors))
-
-        self._print_perf("Standard Batch Put", put_times)
-        self._print_perf("Standard Batch Get", get_times)
-
-    def test_benchmark_02_tp_batch(self):
-        """Benchmark: TP Batch Put/Get."""
-        tp_size = 4
-        split_dim = 0
-        put_times = []
-        get_times = []
-
-        print(f"--- Running TP Batch Benchmark (TP={tp_size}) ---")
-        for i in range(self.BENCH_ITERATIONS):
-            self.store.remove_all()
-
-            # Measure TP Put (Auto-chunking)
-            t0 = time.perf_counter()
-            self.store.batch_put_tensor_with_tp(self.keys, self.tensors, tp_size=tp_size, split_dim=split_dim)
-            put_times.append(time.perf_counter() - t0)
-
-            # Measure TP Get (Simulating gathering all ranks)
-            t_get_start = time.perf_counter()
-            for rank in range(tp_size):
-                res = self.store.batch_get_tensor_with_tp(self.keys, tp_rank=rank, tp_size=tp_size)
-                self.assertEqual(len(res), len(self.tensors))
-            get_times.append(time.perf_counter() - t_get_start)
-
-        self._print_perf(f"TP Batch Put (TP={tp_size})", put_times)
-        self._print_perf(f"TP Batch Get (TP={tp_size})", get_times)
-
-    def test_benchmark_03_batch_put_get_into(self):
-        """Benchmark: Zero copy Batch Put and Batch Get."""
-        self.store.remove_all()
-        buffer_spacing = 300 * 1024 * 1024  # 300MB per tensor slot
-        batch_size = len(self.keys)
-        total_buffer_size = buffer_spacing * batch_size
-        seed_keys = [f"seed_{k}" for k in self.keys]
-
-        large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-        large_buffer_ptr = ctypes.addressof(large_buffer)
-        buffer_ptrs = []
-        buffer_sizes = []
-        for i in range(batch_size):
-            offset = i * buffer_spacing
-            buffer_ptrs.append(large_buffer_ptr + offset)
-            buffer_sizes.append(buffer_spacing)
-
-        res = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration should succeed")
-
-        print(f"--- Running zero copy Batch Put/Get Benchmark ({self.BENCH_ITERATIONS} iters) ---")
-        put_times = []
-        get_times = []
-
-        put_sizes = [serialized_tensor_size(self.tensors[j]) for j in range(batch_size)]
-        for i in range(self.BENCH_ITERATIONS):
-            self.store.remove_all()
-            self.store.batch_put_tensor(seed_keys, self.tensors)
-            self.store.batch_get_tensor_into(seed_keys, buffer_ptrs, buffer_sizes)
-
-            t0 = time.perf_counter()
-            self.store.batch_put_tensor_from(self.keys, buffer_ptrs, put_sizes)
-            put_times.append(time.perf_counter() - t0)
-
-            t0 = time.perf_counter()
-            res = self.store.batch_get_tensor_into(self.keys, buffer_ptrs, buffer_sizes)
-            get_times.append(time.perf_counter() - t0)
-            self.assertEqual(len(res), len(self.tensors))
-            for j in range(batch_size):
-                self.assertTrue(
-                    verify_tensor_equality(self.tensors[j], res[j]),
-                    f"Tensor {j} content mismatch"
-                )
-
-        self._print_perf("Zero copy Batch Put (put_tensor_from)", put_times)
-        self._print_perf("Zero copy Batch Get", get_times)
-        self.assertEqual(self.store.unregister_buffer(large_buffer_ptr), 0, "Buffer unregistration failed")
-
-    def test_benchmark_04_batch_put_get_into_with_tp(self):
-        """Benchmark: Zero-copy Batch Put/Get with TP using full tensor buffers."""
-        tp_size = 4
-        split_dim = 0
-        batch_size = len(self.keys)
-        self.store.remove_all()
-        buffer_spacing = 64 * 1024 * 1024  # 64MB per tensor slot
-        seed_keys = [f"seed_{k}" for k in self.keys]
-
-        full_total_buffer_size = buffer_spacing * batch_size
-        full_buffer = (ctypes.c_ubyte * full_total_buffer_size)()
-        full_buffer_ptr = ctypes.addressof(full_buffer)
-        full_ptrs = [full_buffer_ptr + i * buffer_spacing for i in range(batch_size)]
-        full_sizes = [buffer_spacing] * batch_size
-        res = self.store.register_buffer(full_buffer_ptr, full_total_buffer_size)
-        self.assertEqual(res, 0, "Buffer registration failed for full buffers")
-
-        rank_buffers = []
-        for rank in range(tp_size):
-            total_buffer_size = buffer_spacing * batch_size
-            large_buffer = (ctypes.c_ubyte * total_buffer_size)()
-            large_buffer_ptr = ctypes.addressof(large_buffer)
-            buffer_ptrs = [large_buffer_ptr + i * buffer_spacing for i in range(batch_size)]
-            buffer_sizes = [buffer_spacing] * batch_size
-            res = self.store.register_buffer(large_buffer_ptr, total_buffer_size)
-            self.assertEqual(res, 0, f"Buffer registration failed for rank {rank}")
-            rank_buffers.append({
-                'buffer_obj': large_buffer,
-                'ptrs': buffer_ptrs,
-                'sizes': buffer_sizes,
-                'base_ptr': large_buffer_ptr,
-            })
-
-        print(f"--- Running zero copy Batch Put/Get Benchmark (TP={tp_size}, {self.BENCH_ITERATIONS} iters) ---")
-        put_times = []
-        get_times = []
-
-        for i in range(self.BENCH_ITERATIONS):
-            self.store.remove_all()
-            self.store.batch_put_tensor(seed_keys, self.tensors)
-            self.store.batch_get_tensor_into(seed_keys, full_ptrs, full_sizes)
-            put_sizes = [serialized_tensor_size(self.tensors[j]) for j in range(batch_size)]
-
-            t0 = time.perf_counter()
-            self.store.batch_put_tensor_with_tp_from(
-                self.keys, full_ptrs, put_sizes,
-                tp_rank=1, tp_size=tp_size, split_dim=split_dim
-            )
-            put_times.append(time.perf_counter() - t0)
-
-            t0 = time.perf_counter()
-            all_res = []
-            for rank in range(tp_size):
-                res = self.store.batch_get_tensor_with_tp_into(
-                    self.keys,
-                    rank_buffers[rank]['ptrs'],
-                    rank_buffers[rank]['sizes'],
-                    tp_rank=rank,
-                    tp_size=tp_size
-                )
-                self.assertEqual(len(res), batch_size)
-                all_res.append(res)
-            get_times.append(time.perf_counter() - t0)
-
-            for j in range(batch_size):
-                original = self.tensors[j]
-                expected_shard = original.chunk(tp_size, split_dim)[0]
-                actual = all_res[0][j]
-                self.assertTrue(
-                    torch.equal(actual, expected_shard),
-                    f"Tensor {j} content mismatch on rank 0"
-                )
-
-        self._print_perf(f"Zero copy Batch Put with tp (TP={tp_size})", put_times)
-        self._print_perf(f"Zero copy Batch Get with tp (TP={tp_size})", get_times)
-        self.assertEqual(self.store.unregister_buffer(full_buffer_ptr), 0, "Full buffer unregistration failed")
-        for buf_info in rank_buffers:
-            self.assertEqual(self.store.unregister_buffer(buf_info['base_ptr']), 0, "Buffer unregistration failed")
-
-    def test_benchmark_05_batch_pub_get(self):
-        """Benchmark: Standard Batch Pub/Get."""
-        put_times = []
-        get_times = []
-        repconfig = ReplicateConfig()
-        repconfig.replica_num = 1
-
-        print(f"--- Running Standard Batch Benchmark ({self.BENCH_ITERATIONS} iters) ---")
-        for i in range(self.BENCH_ITERATIONS):
-            # Clean store before each iteration for "cold" writes
-            self.store.remove_all()
-
-            # Measure Put
-            t0 = time.perf_counter()
-            self.store.batch_pub_tensor(self.keys, self.tensors, repconfig)
-            put_times.append(time.perf_counter() - t0)
-
-            # Measure Get
-            t0 = time.perf_counter()
-            res = self.store.batch_get_tensor(self.keys)
-            get_times.append(time.perf_counter() - t0)
-            self.assertEqual(len(res), len(self.tensors))
-
-        self._print_perf("Standard Batch Pub", put_times)
-        self._print_perf("Standard Batch Get", get_times)
-
-    def test_benchmark_06_pub_tp_batch(self):
-        """Benchmark: TP Batch Pub/Get."""
-        tp_size = 4
-        split_dim = 0
-        put_times = []
-        get_times = []
-        repconfig = ReplicateConfig()
-        repconfig.replica_num = 1
-
-        print(f"--- Running TP Batch Benchmark (TP={tp_size}) ---")
-        for i in range(self.BENCH_ITERATIONS):
-            self.store.remove_all()
-
-            # Measure TP Put (Auto-chunking)
-            t0 = time.perf_counter()
-            self.store.batch_pub_tensor_with_tp(self.keys, self.tensors, config=repconfig, tp_size=tp_size, split_dim=split_dim)
-            put_times.append(time.perf_counter() - t0)
-
-            # Measure TP Get (Simulating gathering all ranks)
-            t_get_start = time.perf_counter()
-            for rank in range(tp_size):
-                res = self.store.batch_get_tensor_with_tp(self.keys, tp_rank=rank, tp_size=tp_size)
-                self.assertEqual(len(res), len(self.tensors))
-            get_times.append(time.perf_counter() - t_get_start)
-
-        self._print_perf(f"TP Batch Pub (TP={tp_size})", put_times)
-        self._print_perf(f"TP Batch Get (TP={tp_size})", get_times)
-
-    def test_benchmark_07_unified_full_reconstruction(self):
-        require_unified_parallelism_api(self)
-        key = "bench_unified_full"
-        tensor = make_deterministic_tensor((4, 8))
-        tp_size = 4
-        split_dim = 1
-        full_target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=1))
-        manual_times = []
-        unified_times = []
-
-        print(f"--- Running Unified Full Reconstruction Benchmark (TP={tp_size}) ---")
-        for _ in range(self.BENCH_ITERATIONS):
-            self.store.remove_all()
-            rc = put_uniform_full_tensor_with_unified_tp(
-                self.store, key, tensor, tp_size, split_dim
-            )
-            self.assertEqual(rc, 0)
-
-            t0 = time.perf_counter()
-            unified_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-            unified_times.append(time.perf_counter() - t0)
-            self.assertIsNotNone(unified_tensor)
-            self.assertTrue(torch.equal(unified_tensor, tensor))
-
-            t0 = time.perf_counter()
-            self._run_unified_full_manual_gather(key, tensor, split_dim, tp_size)
-            manual_times.append(time.perf_counter() - t0)
-
-        self.total_bits = tensor.numel() * tensor.element_size() * 8
-        self._print_perf("Unified Full Get", unified_times)
-        self._print_perf("Manual TP Gather", manual_times)
-
-    def test_benchmark_08_unified_full_into(self):
-        require_unified_parallelism_api(self)
-        key = "bench_unified_full_into"
-        tensor = self.tensors[0]
-        tp_size = 4
-        split_dim = 0
-        full_target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=2))
-        buffer_spacing = serialized_tensor_size(tensor) + 1 * 1024 * 1024
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        self.assertEqual(self.store.register_buffer(buffer_ptr, buffer_spacing), 0)
-        into_times = []
-        try:
-            print(f"--- Running Unified Full Into Benchmark (TP={tp_size}) ---")
-            for _ in range(self.BENCH_ITERATIONS):
-                self.store.remove_all()
-                rc = put_uniform_full_tensor_with_unified_tp(
-                    self.store, key, tensor, tp_size, split_dim
-                )
-                self.assertEqual(rc, 0)
-
-                t0 = time.perf_counter()
-                self._run_unified_full_into(key, full_target, buffer_ptr, buffer_spacing, tensor)
-                into_times.append(time.perf_counter() - t0)
-        finally:
-            self.assertEqual(self.store.unregister_buffer(buffer_ptr), 0)
-
-        self.total_bits = tensor.numel() * tensor.element_size() * 8
-        self._print_perf("Unified Full Into", into_times)
-
-# ==========================================
-#  Stress/Concurrency Tests
-# ==========================================
-class TestMooncakeStress(MooncakeTestBase):
-    """
-    Stress tests with Fixed Operation Count and Pre-generated Data.
-    """
-    # Default Config (Overridden by main)
-    NUM_THREADS = 8
-    TOTAL_ITEMS = 800    # Total number of items to process across all threads
-    TENSOR_SIZE_MB = 4    # Size per tensor
-
-    def _run_unified_full_worker(self, worker_id, split_dim, tp_size, use_into=False, mixed_reads=False):
-        key = f"stress_unified_full_{worker_id}"
-        if split_dim == 0:
-            tensor = make_deterministic_tensor((8, 8))
-        elif split_dim == 1:
-            tensor = make_deterministic_tensor((4, 8))
-        else:
-            tensor = make_deterministic_tensor((2, 2, 8))
-
-        rc = put_uniform_full_tensor_with_unified_tp(
-            self.store, key, tensor, tp_size, split_dim
-        )
-        if rc != 0:
-            return f"put failed for {key}, rc={rc}"
-
-        full_target = make_read_target("full", build_tp_parallelism(tp_size, split_dim, rank=min(tp_size - 1, 1)))
-        full_tensor = self.store.get_tensor_with_parallelism(key, full_target)
-        if full_tensor is None or not torch.equal(full_tensor, tensor):
-            return f"full reconstruction mismatch for {key}, split_dim={split_dim}, tp_size={tp_size}"
-
-        if mixed_reads:
-            shard_rank = min(tp_size - 1, 2)
-            shard_target = make_read_target("shard", build_tp_parallelism(tp_size, split_dim, rank=shard_rank))
-            shard_tensor = self.store.get_tensor_with_parallelism(key, shard_target)
-            expected_shard = chunk_tensor_for_rank(tensor, tp_size, split_dim, shard_rank)
-            if shard_tensor is None or not torch.equal(shard_tensor, expected_shard):
-                return f"shard mismatch for {key}, split_dim={split_dim}, tp_size={tp_size}, rank={shard_rank}"
-
-        if use_into:
-            buffer_spacing = serialized_tensor_size(tensor) + 64 * 1024
-            buffer = (ctypes.c_ubyte * buffer_spacing)()
-            buffer_ptr = ctypes.addressof(buffer)
-            if self.store.register_buffer(buffer_ptr, buffer_spacing) != 0:
-                return f"register_buffer failed for {key}"
-            try:
-                into_tensor = self.store.get_tensor_with_parallelism_into(
-                    key, buffer_ptr, buffer_spacing, target=full_target
-                )
-                if into_tensor is None or not torch.equal(into_tensor, tensor):
-                    return f"full into mismatch for {key}, split_dim={split_dim}, tp_size={tp_size}"
-            finally:
-                self.store.unregister_buffer(buffer_ptr)
-
-        return None
-
-    def _run_stress_worker(self, thread_id, items_per_thread):
-        """
-        Worker function:
-        1. PRE-GENERATES data (to exclude generation time from benchmark).
-        2. Performs Put -> Get -> Verify loop.
-        """
-        ops_count = 0
-        failure_msg = None
-
-        # Pre-calculate dimensions
-        element_size = 4 # float32
-        num_elements = (self.TENSOR_SIZE_MB * 1024 * 1024) // element_size
-        dim = int(np.sqrt(num_elements))
-
-        # --- Phase 1: Pre-generate Data ---
-        # "Don't keep generating random data" -> We generate a pool first.
-        # This ensures we measure store performance, not RNG performance.
-        print(f"   [Thread {thread_id}] Pre-generating {items_per_thread} tensors...")
-        data_pool = []
-        for i in range(items_per_thread):
-            key = f"stress_fixed_t{thread_id}_{i}"
-            # Create random tensor
-            tensor = torch.randn(dim, dim, dtype=torch.float32)
-            data_pool.append((key, tensor))
-
-        # Barrier logic simulation: wait for main test to indicate start? 
-        # In simple unittest, we just start processing.
-
-        # --- Phase 2: Execution (Timed) ---
-        t_start = time.perf_counter()
-
-        try:
-            for key, original_tensor in data_pool:
-                # 1. WRITE (Put)
-                rc = self.store.put_tensor(key, original_tensor)
-                if rc != 0:
-                    raise RuntimeError(f"Put failed for {key}, rc={rc}")
-
-                # 2. READ (Get)
-                retrieved_tensor = self.store.get_tensor(key)
-
-                # 3. VALIDATE
-                if retrieved_tensor is None:
-                    raise RuntimeError(f"Get returned None for key {key}")
-
-                if not torch.equal(original_tensor, retrieved_tensor):
-                    raise RuntimeError(f"Data Mismatch for {key}!")
-
-                remove_rc = self.store.remove(key, True)
-                if remove_rc != 0:
-                    raise RuntimeError(f"Remove failed for {key}, rc={remove_rc}")
-
-                ops_count += 1
-
-        except Exception as e:
-            failure_msg = str(e)
-
-        t_duration = time.perf_counter() - t_start
-        return ops_count, t_duration, failure_msg
-
-    def test_stress_consistency_fixed(self):
-        """
-        Run a fixed number of operations with data consistency checks.
-        """
-        items_per_thread = self.TOTAL_ITEMS // self.NUM_THREADS
-        # Adjust for remainder if any
-
-        print(f"\n--- [Stress] Running Fixed Count Test ({self.TOTAL_ITEMS} items total) ---")
-        print(f"--- Config: {self.NUM_THREADS} Threads, ~{items_per_thread} items/thread, {self.TENSOR_SIZE_MB}MB each ---")
-
-        futures = []
-        total_ops = 0
-        errors = []
-
-        # We measure wall time from when threads are submitted until all are done
-        t0 = time.perf_counter()
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=self.NUM_THREADS) as executor:
-            # Distribute work
-            for i in range(self.NUM_THREADS):
-                count = items_per_thread + (1 if i < (self.TOTAL_ITEMS % self.NUM_THREADS) else 0)
-                futures.append(executor.submit(self._run_stress_worker, i, count))
-
-            # Gather results
-            for future in concurrent.futures.as_completed(futures):
-                ops, duration, error = future.result()
-                total_ops += ops
-                if error:
-                    errors.append(error)
-
-        elapsed = time.perf_counter() - t0
-
-        # Reporting
-        print(f"\n--- [Stress Report] ---")
-        if errors:
-            print(f"❌ FAILED with {len(errors)} errors.")
-            print(f"First Error: {errors[0]}")
-            self.fail(f"Stress test failed with {len(errors)} errors.")
-        else:
-            total_data_gb = (total_ops * self.TENSOR_SIZE_MB) / 1024
-            throughput_gbps = (total_data_gb * 8) / elapsed
-
-            print(f"✅ PASSED (No Consistency Errors)")
-            print(f"Total Items:    {total_ops}")
-            print(f"Wall Time:      {elapsed:.4f} s")
-            print(f"Avg QPS:        {total_ops / elapsed:.2f} ops/s")
-            print(f"Avg Goodput:    {throughput_gbps:.2f} Gbps")
-
-    def test_stress_unified_parallelism_full_reads(self):
-        require_unified_parallelism_api(self)
-        worker_cases = [
-            (0, 0, 2, False, False),
-            (1, 1, 2, False, True),
-            (2, 0, 4, True, False),
-            (3, 1, 4, True, True),
-            (4, 2, 4, False, True),
-            (5, 2, 4, True, True),
-        ]
-        errors = []
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=len(worker_cases)) as executor:
-            futures = [
-                executor.submit(self._run_unified_full_worker, *case)
-                for case in worker_cases
-            ]
-            for future in concurrent.futures.as_completed(futures):
-                error = future.result()
-                if error:
-                    errors.append(error)
-
-        if errors:
-            self.fail(errors[0])
-
-
-# ==========================================
-#  Data Type & Precision Tests (Full Enum)
-# ==========================================
-
-class TestMooncakeDataTypes(MooncakeTestBase):
-    def _test_dtype_roundtrip(self, dtype, name, expected_enum_name=None):
-        """
-        Generic test for put/get consistency.
-        Args:
-            dtype: The torch.dtype to test.
-            name: Readable name for logging.
-            expected_enum_name: (Optional) If we could inspect the C++ enum value, we would check this.
-        """
-        key = f"dtype_check_{name}"
-        shape = (64, 64)
-
-        if dtype == torch.bool:
-            original = torch.randint(0, 2, shape).bool()
-        elif dtype.is_floating_point:
-            original = torch.randn(shape, dtype=torch.float32).to(dtype)
-        else:
-            if dtype == torch.int8:
-                original = torch.randint(-128, 127, shape, dtype=dtype)
-            elif dtype == torch.uint8:
-                original = torch.randint(0, 255, shape, dtype=dtype)
-            else:
-                original = torch.randint(-1000, 1000, shape, dtype=dtype)
-
-        # The C++ store will infer the Enum based on original.dtype
-        rc = self.store.put_tensor(key, original)
-        if rc != 0:
-            print(f"   [Fail] {name:<15} Put failed with rc={rc}")
-            self.fail(f"Put failed for {name}")
-
-        retrieved = self.store.get_tensor(key)
-        if retrieved is None:
-            print(f"   [Fail] {name:<15} Get returned None")
-            self.fail(f"Get returned None for {name}")
-
-        # We expect the retrieved tensor to have the same dtype as input
-        if original.dtype != retrieved.dtype:
-            msg = f"Dtype mismatch for {name}! Input: {original.dtype}, Output: {retrieved.dtype}"
-            print(f"   [Fail] {name:<15} {msg}")
-            self.fail(msg)
-
-        # Use byte-view comparison for robustness (especially for FP8/BF16 on CPU)
-        try:
-            # Cast to untyped storage byte view (or uint8 view)
-            t1_bytes = original.view(torch.uint8) if original.element_size() > 0 else original
-            t2_bytes = retrieved.view(torch.uint8) if retrieved.element_size() > 0 else retrieved
-            is_equal = torch.equal(t1_bytes, t2_bytes)
-        except Exception:
-            # Fallback for types that might fail view() or equal()
-            is_equal = torch.equal(original.cpu(), retrieved.cpu())
-
-        if not is_equal:
-            print(f"   [Fail] {name:<15} Data content mismatch")
-            self.fail(f"Data content mismatch for {name}")
-
-        buffer_spacing = 1 * 1024 * 1024
-        buffer = (ctypes.c_ubyte * buffer_spacing)()
-        buffer_ptr = ctypes.addressof(buffer)
-        res = self.store.register_buffer(buffer_ptr, buffer_spacing)
-        self.assertEqual(res, 0, f"Buffer registration failed for buffer at {buffer_ptr}")
-        retrieved = self.store.get_tensor_into(key, buffer_ptr, buffer_spacing)
-        if retrieved is None:
-            print(f"   [Fail] {name:<15} Get returned None")
-            self.fail(f"Get returned None for {name}")
-
-        # We expect the retrieved tensor to have the same dtype as input
-        if original.dtype != retrieved.dtype:
-            msg = f"Dtype mismatch for {name}! Input: {original.dtype}, Output: {retrieved.dtype}"
-            print(f"   [Fail] {name:<15} {msg}")
-            self.fail(msg)
-
-        # Use byte-view comparison for robustness (especially for FP8/BF16 on CPU)
-        try:
-            # Cast to untyped storage byte view (or uint8 view)
-            t1_bytes = original.view(torch.uint8) if original.element_size() > 0 else original
-            t2_bytes = retrieved.view(torch.uint8) if retrieved.element_size() > 0 else retrieved
-            is_equal = torch.equal(t1_bytes, t2_bytes)
-        except Exception:
-            # Fallback for types that might fail view() or equal()
-            is_equal = torch.equal(original.cpu(), retrieved.cpu())
-
-        if not is_equal:
-            print(f"   [Fail] {name:<15} Data content mismatch")
-            self.fail(f"Data content mismatch for {name}")
-        res = self.store.unregister_buffer(buffer_ptr)
-        self.assertEqual(res, 0, f"Buffer unregistration failed for buffer at {buffer_ptr}")
-
-        print(f"   [Pass] {name:<15} {str(dtype)}")
-
-
-    def test_all_dtypes(self):
-        print("\n--- Testing All Supported PyTorch Data Types ---")
-
-        test_cases = [
-            ("FLOAT32",     torch.float32),
-            ("FLOAT64",     torch.float64),
-            ("INT8",        torch.int8),
-            ("UINT8",       torch.uint8),
-            ("INT16",       torch.int16),
-            ("INT32",       torch.int32),
-            ("INT64",       torch.int64),
-            ("BOOL",        torch.bool),
-            ("FLOAT16",     torch.float16),
-            ("BFLOAT16",    torch.bfloat16),
-        ]
-
-        for name, dtype in test_cases:
-            with self.subTest(dtype=name):
-                self._test_dtype_roundtrip(dtype, name)
-
-    def test_fp8_types(self):
-        print("\n--- Testing FP8 Types ---")
-
-        fp8_cases = []
-        # Check support dynamically
-        if hasattr(torch, 'float8_e4m3fn'):
-            fp8_cases.append(("FLOAT8_E4M3", torch.float8_e4m3fn)) # Enum 13
-        else:
-            print("   [Skip] FLOAT8_E4M3 (Not supported in this PyTorch version)")
-
-        if hasattr(torch, 'float8_e5m2'):
-            fp8_cases.append(("FLOAT8_E5M2", torch.float8_e5m2))   # Enum 14
-        else:
-            print("   [Skip] FLOAT8_E5M2 (Not supported in this PyTorch version)")
-
-        for name, dtype in fp8_cases:
-            with self.subTest(dtype=name):
-                self._test_dtype_roundtrip(dtype, name)
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Mooncake Distributed Store Tests")
-    parser.add_argument("--mode", type=str, default="all", choices=["all", "func", "perf", "stress", "types"],
-                        help="Run mode")
-    parser.add_argument("--threads", type=int, default=8, help="Number of threads")
-    parser.add_argument("--count", type=int, default=800, help="Total number of items to process")
-    parser.add_argument("--size_mb", type=float, default=0.5, help="Tensor size in MB")
-
-    args, unknown = parser.parse_known_args()
-
-    # Update Stress Test Config
-    TestMooncakeStress.NUM_THREADS = args.threads
-    TestMooncakeStress.TOTAL_ITEMS = args.count
-    TestMooncakeStress.TENSOR_SIZE_MB = args.size_mb
-
-    suite = unittest.TestSuite()
-    loader = unittest.TestLoader()
-
-    if args.mode in ["all", "func"]:
-        print(">> Loading Functional Tests...")
-        suite.addTests(loader.loadTestsFromTestCase(TestMooncakeFunctional))
-
-    if args.mode in ["all", "perf"]:
-        print(">> Loading Performance Benchmark Tests...")
-        suite.addTests(loader.loadTestsFromTestCase(TestMooncakeBenchmark))
-
-    if args.mode in ["all", "stress"]:
-        print(f">> Loading Stress Tests ({args.count} items, {args.threads} threads)...")
-        suite.addTests(loader.loadTestsFromTestCase(TestMooncakeStress))
-
-    if args.mode in ["all", "types", "func"]: # 'types' can be part of 'func' or standalone
-        print(">> Loading Data Type Tests...")
-        suite.addTests(loader.loadTestsFromTestCase(TestMooncakeDataTypes))
-
-    runner = unittest.TextTestRunner(verbosity=2)
-    result = runner.run(suite)
-
-    sys.exit(not result.wasSuccessful())
diff --git a/scripts/test_upsert_api.py b/scripts/test_upsert_api.py
index 6e119980db..995370d4df 100644
--- a/scripts/test_upsert_api.py
+++ b/scripts/test_upsert_api.py
@@ -29,12 +29,9 @@
 import ctypes
 import os
 import unittest
-from dataclasses import dataclass
 
 import torch
 import numpy as np
-import mooncake.store as mooncake_store
-
 from mooncake.store import MooncakeDistributedStore, ReplicateConfig
 
 # ==========================================
@@ -65,13 +62,16 @@ def setUpModule():
     protocol = os.getenv("MOONCAKE_PROTOCOL", "tcp")
     device_name = os.getenv("MOONCAKE_DEVICE", "")
     local_hostname = os.getenv("MOONCAKE_LOCAL_HOSTNAME", "localhost")
-    segment_size = int(os.getenv("MOONCAKE_GLOBAL_SEGMENT_SIZE",
-                                  str(64 * 1024 * 1024)))  # 64 MB default
-    buffer_size = int(os.getenv("MOONCAKE_LOCAL_BUFFER_SIZE",
-                                 str(64 * 1024 * 1024)))   # 64 MB default
-
-    print(f"\n[{os.getpid()}] Connecting to master at {master_addr} "
-          f"({protocol})...")
+    segment_size = int(
+        os.getenv("MOONCAKE_GLOBAL_SEGMENT_SIZE", str(64 * 1024 * 1024))
+    )  # 64 MB default
+    buffer_size = int(
+        os.getenv("MOONCAKE_LOCAL_BUFFER_SIZE", str(64 * 1024 * 1024))
+    )  # 64 MB default
+
+    print(
+        f"\n[{os.getpid()}] Connecting to master at {master_addr} " f"({protocol})..."
+    )
     store = MooncakeDistributedStore()
     rc = store.setup(
         local_hostname,
@@ -95,51 +95,6 @@ def tearDownModule():
         GLOBAL_STORE = None
 
 
-def require_unified_parallelism_api(test_case):
-    missing = [
-        name for name in ["ParallelAxis", "TensorParallelism", "ReadTarget"]
-        if not hasattr(mooncake_store, name)
-    ]
-    if missing:
-        test_case.skipTest(
-            "Unified parallelism Python bindings are not available in the installed extension: "
-            + ", ".join(missing)
-        )
-
-
-def make_parallel_axis(kind, rank, size, split_dim=None):
-    axis = mooncake_store.ParallelAxis()
-    axis.kind = kind
-    axis.rank = rank
-    axis.size = size
-    axis.split_dim = split_dim
-    return axis
-
-
-def make_tensor_parallelism(axes):
-    parallelism = mooncake_store.TensorParallelism()
-    parallelism.axes = axes
-    return parallelism
-
-
-def make_read_target(mode, parallelism=None):
-    target = mooncake_store.ReadTarget()
-    target.mode = mode
-    target.parallelism = parallelism
-    return target
-
-
-@dataclass
-class WriterPartition:
-    rank: int
-    size: int
-    split_dim: int
-
-
-def make_writer_partition(rank, size, split_dim):
-    return WriterPartition(rank=rank, size=size, split_dim=split_dim)
-
-
 class UpsertTestBase(unittest.TestCase):
     """Base class that provides self.store and cleans up before each test."""
 
@@ -154,6 +109,7 @@ def setUp(self):
 #  1. Raw Bytes — Non-Zero-Copy
 # ==========================================
 
+
 class TestUpsertRawBytes(UpsertTestBase):
     """upsert(key, bytes) — copy semantics, single key."""
 
@@ -227,6 +183,7 @@ def test_overwrite(self):
 #  2. Raw Bytes — Zero-Copy
 # ==========================================
 
+
 class TestUpsertFrom(UpsertTestBase):
     """upsert_from(key, buffer_ptr, size) — zero-copy, single key.
 
@@ -308,6 +265,7 @@ def test_overwrite(self):
 #  3. Tensor — Non-Zero-Copy
 # ==========================================
 
+
 class TestUpsertTensor(UpsertTestBase):
     """upsert_tensor(key, tensor) — tensor copy, single key."""
 
@@ -357,8 +315,9 @@ class TestBatchUpsertTensor(UpsertTestBase):
 
     def test_basic(self):
         keys = ["btensor_0", "btensor_1", "btensor_2"]
-        tensors = [torch.randn(20, 20, dtype=torch.float32).contiguous()
-                   for _ in range(3)]
+        tensors = [
+            torch.randn(20, 20, dtype=torch.float32).contiguous() for _ in range(3)
+        ]
         rets = self.store.batch_upsert_tensor(keys, tensors)
         self.assertEqual(list(rets), [0, 0, 0])
         for k, t in zip(keys, tensors):
@@ -382,6 +341,7 @@ def test_overwrite(self):
 #  4. Tensor — Zero-Copy
 # ==========================================
 
+
 class TestUpsertTensorFrom(UpsertTestBase):
     """upsert_tensor_from(key, buffer_ptr, size) — tensor zero-copy, single key."""
 
@@ -434,8 +394,10 @@ def _alloc_and_register(self, size):
 
     def test_basic(self):
         keys = ["btfrom_0", "btfrom_1"]
-        tensors = [torch.randn(50, dtype=torch.float32).contiguous(),
-                   torch.randn(50, dtype=torch.float32).contiguous()]
+        tensors = [
+            torch.randn(50, dtype=torch.float32).contiguous(),
+            torch.randn(50, dtype=torch.float32).contiguous(),
+        ]
 
         # Put initial tensors
         for k, t in zip(keys, tensors):
@@ -475,6 +437,7 @@ def test_basic(self):
 #  5. Tensor with ReplicateConfig (pub variants)
 # ==========================================
 
+
 class TestUpsertPubTensor(UpsertTestBase):
     """upsert_pub_tensor / batch_upsert_pub_tensor — with ReplicateConfig."""
 
@@ -491,8 +454,7 @@ def test_batch(self):
         config = ReplicateConfig()
         config.replica_num = 1
         keys = ["pub_batch_0", "pub_batch_1"]
-        tensors = [torch.randn(15, 15).contiguous(),
-                   torch.randn(15, 15).contiguous()]
+        tensors = [torch.randn(15, 15).contiguous(), torch.randn(15, 15).contiguous()]
         rets = self.store.batch_upsert_pub_tensor(keys, tensors, config)
         self.assertEqual(list(rets), [0, 0])
         for k, t in zip(keys, tensors):
@@ -512,559 +474,11 @@ def test_overwrite_with_config(self):
         self.assertTrue(torch.equal(t2, got))
 
 
-class TestUnifiedParallelismUpsert(UpsertTestBase):
-    def test_put_tensor_with_parallelism_rejects_nonuniform_multi_axis(self):
-        require_unified_parallelism_api(self)
-        key = "unified_nonuniform_multi_axis_reject"
-        tensor = torch.arange(6, dtype=torch.float32).view(2, 3).contiguous()
-        parallelism = make_tensor_parallelism([
-            make_parallel_axis("dp", rank=0, size=2),
-            make_parallel_axis("tp", rank=0, size=2, split_dim=1),
-        ])
-
-        rc = self.store.put_tensor_with_parallelism(key, tensor, parallelism)
-        self.assertNotEqual(rc, 0)
-        self.assertIsNone(
-            self.store.get_tensor_with_parallelism(key, make_read_target("shard", parallelism))
-        )
-
-    def test_put_tensor_with_parallelism_from_rejects_nonuniform_multi_axis(self):
-        require_unified_parallelism_api(self)
-        seed_key = "unified_nonuniform_multi_axis_from_seed"
-        key = "unified_nonuniform_multi_axis_from_reject"
-        tensor = torch.arange(6, dtype=torch.float32).view(2, 3).contiguous()
-        self.assertEqual(self.store.put_tensor(seed_key, tensor), 0)
-
-        buffer_size = serialized_tensor_size(tensor)
-        buf = ctypes.create_string_buffer(buffer_size)
-        ptr = ctypes.addressof(buf)
-        self.assertEqual(self.store.register_buffer(ptr, buffer_size), 0)
-        try:
-            got = self.store.get_tensor_into(seed_key, ptr, buffer_size)
-            self.assertIsNotNone(got)
-            parallelism = make_tensor_parallelism([
-                make_parallel_axis("dp", rank=1, size=2),
-                make_parallel_axis("tp", rank=1, size=2, split_dim=1),
-            ])
-            rc = self.store.put_tensor_with_parallelism_from(
-                key, ptr, buffer_size, parallelism
-            )
-            self.assertNotEqual(rc, 0)
-            self.assertIsNone(
-                self.store.get_tensor_with_parallelism(
-                    key, make_read_target("shard", parallelism)
-                )
-            )
-        finally:
-            self.store.unregister_buffer(ptr)
-
-    def test_put_tensor_with_writer_partition_rejects_nonuniform(self):
-        require_unified_parallelism_api(self)
-        key = "writer_partition_nonuniform_reject"
-        tensor = torch.arange(6, dtype=torch.float32).view(2, 3).contiguous()
-
-        rc = self.store.put_tensor_with_parallelism(
-            key,
-            tensor,
-            writer_partition=make_writer_partition(rank=0, size=2, split_dim=1),
-        )
-        self.assertNotEqual(rc, 0)
-        self.assertIsNone(self.store.get_tensor_with_parallelism(key, make_read_target("full")))
-
-    def test_batch_put_tensor_with_parallelism_rejects_nonuniform_and_preserves_uniform_data(self):
-        require_unified_parallelism_api(self)
-        keys = ["uniform_batch_ok", "nonuniform_batch_reject"]
-        tensors = [
-            torch.arange(8, dtype=torch.float32).view(2, 4).contiguous(),
-            torch.arange(6, dtype=torch.float32).view(2, 3).contiguous(),
-        ]
-        parallelisms = [
-            make_tensor_parallelism([
-                make_parallel_axis("dp", rank=0, size=2),
-                make_parallel_axis("tp", rank=1, size=2, split_dim=1),
-            ]),
-            make_tensor_parallelism([
-                make_parallel_axis("dp", rank=1, size=2),
-                make_parallel_axis("tp", rank=0, size=4, split_dim=1),
-            ]),
-        ]
-
-        results = list(
-            self.store.batch_put_tensor_with_parallelism(keys, tensors, parallelisms)
-        )
-        self.assertEqual(results[0], 0)
-        self.assertNotEqual(results[1], 0)
-
-        got_uniform = self.store.get_tensor_with_parallelism(
-            keys[0], make_read_target("shard", parallelisms[0])
-        )
-        self.assertIsNotNone(got_uniform)
-        self.assertTrue(torch.equal(got_uniform, tensors[0].chunk(2, 1)[1]))
-        self.assertIsNone(
-            self.store.get_tensor_with_parallelism(
-                keys[1], make_read_target("shard", parallelisms[1])
-            )
-        )
-
-    def test_upsert_tensor_with_parallelism_multi_axis(self):
-        require_unified_parallelism_api(self)
-        key = "unified_multi_axis_upsert"
-        original = torch.arange(8, dtype=torch.float32).view(2, 4).contiguous()
-        updated = (original + 50).contiguous()
-
-        dp_axis = make_parallel_axis("dp", rank=1, size=2)
-        tp_axis = make_parallel_axis("tp", rank=0, size=2, split_dim=1)
-        parallelism = make_tensor_parallelism([dp_axis, tp_axis])
-
-        for rank in range(2):
-            rank_parallelism = clone_parallelism(parallelism)
-            rank_parallelism.axes[1].rank = rank
-            self.assertEqual(
-                self.store.put_tensor_with_parallelism(key, original, rank_parallelism),
-                0,
-            )
-            self.assertEqual(
-                self.store.upsert_tensor_with_parallelism(key, updated, rank_parallelism),
-                0,
-            )
-
-        target = make_read_target("shard", parallelism)
-        got = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(got)
-        self.assertTrue(torch.equal(got, updated.chunk(2, 1)[0]))
-
-    def test_batch_upsert_tensor_with_parallelism_multi_axis(self):
-        require_unified_parallelism_api(self)
-        keys = ["unified_multi_axis_batch_upsert_0", "unified_multi_axis_batch_upsert_1"]
-        originals = [
-            torch.arange(8, dtype=torch.float32).view(2, 4).contiguous(),
-            torch.arange(8, 16, dtype=torch.float32).view(4, 2).contiguous(),
-        ]
-        updates = [(tensor + 100).contiguous() for tensor in originals]
-
-        base_parallelisms = []
-        dp_tp = make_tensor_parallelism([
-            make_parallel_axis("dp", rank=1, size=2),
-            make_parallel_axis("tp", rank=1, size=2, split_dim=1),
-        ])
-        pp_tp = make_tensor_parallelism([
-            make_parallel_axis("pp", rank=0, size=2),
-            make_parallel_axis("tp", rank=1, size=2, split_dim=0),
-        ])
-        pp_tp.axes[0].stage_id = 3
-        base_parallelisms.extend([dp_tp, pp_tp])
-
-        rank_parallelisms = []
-        for base_parallelism in base_parallelisms:
-            tp_axis = next(axis for axis in base_parallelism.axes if axis.kind == "tp")
-            for rank in range(tp_axis.size):
-                parallelism = clone_parallelism(base_parallelism)
-                for axis in parallelism.axes:
-                    if axis.kind == "tp":
-                        axis.rank = rank
-                        break
-                rank_parallelisms.append(parallelism)
-        batch_keys = [keys[0]] * 2 + [keys[1]] * 2
-        batch_originals = [originals[0]] * 2 + [originals[1]] * 2
-        batch_updates = [updates[0]] * 2 + [updates[1]] * 2
-
-        self.assertEqual(
-            list(self.store.batch_put_tensor_with_parallelism(batch_keys, batch_originals, rank_parallelisms)),
-            [0, 0, 0, 0],
-        )
-        self.assertEqual(
-            list(self.store.batch_upsert_tensor_with_parallelism(batch_keys, batch_updates, rank_parallelisms)),
-            [0, 0, 0, 0],
-        )
-        invalid_results = list(
-            self.store.batch_put_tensor_with_parallelism(
-                keys,
-                originals,
-                parallelisms=base_parallelisms,
-                writer_partitions=[
-                    make_writer_partition(0, 2, 0),
-                    make_writer_partition(1, 2, 0),
-                ],
-            )
-        )
-        self.assertTrue(
-            all(result != 0 for result in invalid_results),
-            f"expected invalid combined routing request: {invalid_results}",
-        )
-
-        targets = []
-        for parallelism in base_parallelisms:
-            target = mooncake_store.ReadTarget()
-            target.mode = "shard"
-            target.parallelism = parallelism
-            targets.append(target)
-        results = self.store.batch_get_tensor_with_parallelism(keys, targets)
-        self.assertEqual(len(results), 2)
-        self.assertTrue(torch.equal(results[0], updates[0].chunk(2, 1)[1]))
-        self.assertTrue(torch.equal(results[1], updates[1].chunk(2, 0)[1]))
-
-    def test_upsert_tensor_with_parallelism_from_multi_axis(self):
-        require_unified_parallelism_api(self)
-        key = "unified_multi_axis_upsert_from"
-        seed_key = "unified_multi_axis_upsert_from_seed"
-        tensor = torch.arange(8, dtype=torch.float32).view(2, 4).contiguous()
-        updated = (tensor + 77).contiguous()
-
-        self.assertEqual(self.store.put_tensor(seed_key, updated), 0)
-        buffer_size = serialized_tensor_size(updated)
-        buf = ctypes.create_string_buffer(buffer_size)
-        ptr = ctypes.addressof(buf)
-        self.assertEqual(self.store.register_buffer(ptr, buffer_size), 0)
-        try:
-            got = self.store.get_tensor_into(seed_key, ptr, buffer_size)
-            self.assertIsNotNone(got)
-
-            dp_axis = make_parallel_axis("dp", rank=0, size=2)
-            tp_axis = make_parallel_axis("tp", rank=1, size=2, split_dim=1)
-            parallelism = make_tensor_parallelism([dp_axis, tp_axis])
-
-            for rank in range(2):
-                rank_parallelism = clone_parallelism(parallelism)
-                rank_parallelism.axes[1].rank = rank
-                self.assertEqual(
-                    self.store.upsert_tensor_with_parallelism_from(
-                        key, ptr, buffer_size, rank_parallelism
-                    ),
-                    0,
-                )
-
-            target = mooncake_store.ReadTarget()
-            target.mode = "shard"
-            target.parallelism = parallelism
-            result = self.store.get_tensor_with_parallelism(key, target)
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, updated.chunk(2, 1)[1]))
-        finally:
-            self.store.unregister_buffer(ptr)
-
-    def test_upsert_tensor_with_writer_partition(self):
-        require_unified_parallelism_api(self)
-        key = "writer_partition_upsert"
-        original = torch.arange(8, dtype=torch.float32).view(2, 4).contiguous()
-        updated = (original + 33).contiguous()
-
-        for rank in range(2):
-            self.assertEqual(
-                self.store.put_tensor_with_parallelism(
-                    key,
-                    original,
-                    writer_partition=make_writer_partition(rank, 2, 1),
-                ),
-                0,
-            )
-        for rank in range(2):
-            self.assertEqual(
-                self.store.upsert_tensor_with_parallelism(
-                    key,
-                    updated,
-                    writer_partition=make_writer_partition(rank, 2, 1),
-                ),
-                0,
-            )
-
-        target = make_read_target("full")
-        got = self.store.get_tensor_with_parallelism(key, target)
-        self.assertIsNotNone(got)
-        self.assertTrue(torch.equal(got, updated))
-
-    def test_upsert_tensor_with_writer_partition_from(self):
-        require_unified_parallelism_api(self)
-        key = "writer_partition_upsert_from"
-        seed_key = "writer_partition_upsert_from_seed"
-        tensor = torch.arange(16, dtype=torch.float32).view(4, 4).contiguous()
-
-        self.assertEqual(self.store.put_tensor(seed_key, tensor), 0)
-        for rank in range(4):
-            self.assertEqual(
-                self.store.put_tensor_with_parallelism(
-                    key,
-                    tensor,
-                    writer_partition=make_writer_partition(rank, 4, 0),
-                ),
-                0,
-            )
-        buffer_size = serialized_tensor_size(tensor)
-        buf = ctypes.create_string_buffer(buffer_size)
-        ptr = ctypes.addressof(buf)
-        self.assertEqual(self.store.register_buffer(ptr, buffer_size), 0)
-        try:
-            got = self.store.get_tensor_into(seed_key, ptr, buffer_size)
-            self.assertIsNotNone(got)
-
-            for rank in range(4):
-                self.assertEqual(
-                    self.store.upsert_tensor_with_parallelism_from(
-                        key,
-                        ptr,
-                        buffer_size,
-                        writer_partition=make_writer_partition(rank, 4, 0),
-                    ),
-                    0,
-                )
-
-            target = mooncake_store.ReadTarget()
-            target.mode = "full"
-            target.parallelism = None
-            result = self.store.get_tensor_with_parallelism(key, target)
-            self.assertIsNotNone(result)
-            self.assertTrue(torch.equal(result, tensor))
-        finally:
-            self.store.unregister_buffer(ptr)
-
-    def test_batch_upsert_tensor_with_writer_partitions(self):
-        require_unified_parallelism_api(self)
-        keys = ["writer_partition_batch_upsert_0", "writer_partition_batch_upsert_1"]
-        originals = [
-            torch.arange(8, dtype=torch.float32).view(2, 4).contiguous(),
-            torch.arange(8, 16, dtype=torch.float32).view(2, 4).contiguous(),
-        ]
-        updates = [(tensor + 100).contiguous() for tensor in originals]
-
-        for rank in range(2):
-            writer_partitions = [
-                make_writer_partition(rank=rank, size=2, split_dim=1),
-                make_writer_partition(rank=rank, size=2, split_dim=1),
-            ]
-            self.assertEqual(
-                list(
-                    self.store.batch_put_tensor_with_parallelism(
-                        keys,
-                        originals,
-                        writer_partitions=writer_partitions,
-                    )
-                ),
-                [0, 0],
-            )
-            self.assertEqual(
-                list(
-                    self.store.batch_upsert_tensor_with_parallelism(
-                        keys,
-                        updates,
-                        writer_partitions=writer_partitions,
-                    )
-                ),
-                [0, 0],
-            )
-
-        results = self.store.batch_get_tensor_with_parallelism(
-            keys, [make_read_target("full"), make_read_target("full")]
-        )
-        self.assertEqual(len(results), 2)
-        self.assertTrue(torch.equal(results[0], updates[0]))
-        self.assertTrue(torch.equal(results[1], updates[1]))
-
-    def test_batch_upsert_tensor_with_writer_partitions_from(self):
-        require_unified_parallelism_api(self)
-        keys = ["writer_partition_batch_upsert_from_0", "writer_partition_batch_upsert_from_1"]
-        seed_keys = [f"{key}_seed" for key in keys]
-        tensors = [
-            torch.arange(16, dtype=torch.float32).view(4, 4).contiguous(),
-            torch.arange(16, 32, dtype=torch.float32).view(4, 4).contiguous(),
-        ]
-
-        for seed_key, tensor in zip(seed_keys, tensors):
-            self.assertEqual(self.store.put_tensor(seed_key, tensor), 0)
-
-        for rank in range(4):
-            writer_partitions = [
-                make_writer_partition(rank=rank, size=4, split_dim=0),
-                make_writer_partition(rank=rank, size=4, split_dim=0),
-            ]
-            self.assertEqual(
-                list(
-                    self.store.batch_put_tensor_with_parallelism(
-                        keys,
-                        tensors,
-                        writer_partitions=writer_partitions,
-                    )
-                ),
-                [0, 0],
-            )
-
-        buffer_sizes = [serialized_tensor_size(tensor) for tensor in tensors]
-        backing_buffer = ctypes.create_string_buffer(sum(buffer_sizes))
-        base_ptr = ctypes.addressof(backing_buffer)
-        buffer_ptrs = []
-        offset = 0
-        for size in buffer_sizes:
-            buffer_ptrs.append(base_ptr + offset)
-            offset += size
-        self.assertEqual(self.store.register_buffer(base_ptr, len(backing_buffer)), 0)
-        try:
-            for seed_key, ptr, size in zip(seed_keys, buffer_ptrs, buffer_sizes):
-                got = self.store.get_tensor_into(seed_key, ptr, size)
-                self.assertIsNotNone(got)
-
-            for rank in range(4):
-                writer_partitions = [
-                    make_writer_partition(rank=rank, size=4, split_dim=0),
-                    make_writer_partition(rank=rank, size=4, split_dim=0),
-                ]
-                self.assertEqual(
-                    list(
-                        self.store.batch_upsert_tensor_with_parallelism_from(
-                            keys,
-                            buffer_ptrs,
-                            buffer_sizes,
-                            writer_partitions=writer_partitions,
-                        )
-                    ),
-                    [0, 0],
-                )
-
-            results = self.store.batch_get_tensor_with_parallelism(
-                keys, [make_read_target("full"), make_read_target("full")]
-            )
-            self.assertEqual(len(results), 2)
-            self.assertTrue(torch.equal(results[0], tensors[0]))
-            self.assertTrue(torch.equal(results[1], tensors[1]))
-        finally:
-            self.store.unregister_buffer(base_ptr)
-
-
-def clone_parallelism(parallelism):
-    cloned_axes = []
-    for axis in parallelism.axes:
-        cloned_axis = make_parallel_axis(
-            axis.kind,
-            rank=axis.rank,
-            size=axis.size,
-            split_dim=axis.split_dim,
-        )
-        if getattr(axis, "expert_id", None) is not None:
-            cloned_axis.expert_id = axis.expert_id
-        if getattr(axis, "stage_id", None) is not None:
-            cloned_axis.stage_id = axis.stage_id
-        cloned_axes.append(cloned_axis)
-    return make_tensor_parallelism(cloned_axes)
-
-
-class TestUpsertParallelTensor(UpsertTestBase):
-    """Parallelism-based tensor upsert coverage for TP cases."""
-
-    def test_upsert_tensor_with_parallelism_tp(self):
-        require_unified_parallelism_api(self)
-        tp_size = 2
-        split_dim = 1
-        key = "tp_upsert_single"
-        original = torch.arange(6, dtype=torch.float32).view(2, 3).contiguous()
-        updated = (original + 100).contiguous()
-        original_shard = original.chunk(tp_size, split_dim)[0].contiguous()
-        updated_shard = updated.chunk(tp_size, split_dim)[0].contiguous()
-        parallelism = make_tensor_parallelism(
-            [make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)]
-        )
-        target = make_read_target("shard", parallelism)
-
-        self.assertEqual(
-            self.store.put_tensor_with_parallelism(key, original_shard, parallelism),
-            0,
-        )
-        self.assertEqual(
-            self.store.upsert_tensor_with_parallelism(key, updated_shard, parallelism),
-            0,
-        )
-
-        got = self.store.get_tensor_with_parallelism(key, target)
-        self.assertTrue(torch.equal(got, updated_shard))
-
-    def test_batch_upsert_tensor_with_parallelism_tp(self):
-        require_unified_parallelism_api(self)
-        tp_size = 2
-        split_dim = 0
-        keys = ["tp_batch_upsert_0", "tp_batch_upsert_1"]
-        originals = [torch.arange(16, dtype=torch.float32).view(4, 4).contiguous(),
-                     torch.arange(16, 32, dtype=torch.float32).view(4, 4).contiguous()]
-        updates = [(t + 1000).contiguous() for t in originals]
-        original_shards = [tensor.chunk(tp_size, split_dim)[0].contiguous() for tensor in originals]
-        update_shards = [tensor.chunk(tp_size, split_dim)[0].contiguous() for tensor in updates]
-        parallelism = make_tensor_parallelism(
-            [make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)]
-        )
-        targets = [make_read_target("shard", parallelism) for _ in keys]
-
-        self.assertEqual(
-            list(self.store.batch_put_tensor_with_parallelism(keys, original_shards, [parallelism] * len(keys))),
-            [0, 0],
-        )
-        self.assertEqual(
-            list(self.store.batch_upsert_tensor_with_parallelism(keys, update_shards, [parallelism] * len(keys))),
-            [0, 0],
-        )
-
-        got_shards = self.store.batch_get_tensor_with_parallelism(keys, targets)
-        for got, expected in zip(got_shards, update_shards):
-            self.assertTrue(torch.equal(got, expected))
-
-    def test_upsert_tensor_with_parallelism_tp_with_config(self):
-        require_unified_parallelism_api(self)
-        tp_size = 2
-        split_dim = 1
-        key = "tp_upsert_pub_single"
-        config = ReplicateConfig()
-        config.replica_num = 1
-        base = torch.ones(4, 6, dtype=torch.float32).contiguous()
-        updated = torch.full((4, 6), 7.0, dtype=torch.float32).contiguous()
-        base_shard = base.chunk(tp_size, split_dim)[0].contiguous()
-        updated_shard = updated.chunk(tp_size, split_dim)[0].contiguous()
-        parallelism = make_tensor_parallelism(
-            [make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)]
-        )
-        target = make_read_target("shard", parallelism)
-
-        self.assertEqual(
-            self.store.put_tensor_with_parallelism(key, base_shard, parallelism, config=config),
-            0,
-        )
-        self.assertEqual(
-            self.store.upsert_tensor_with_parallelism(key, updated_shard, parallelism, config=config),
-            0,
-        )
-
-        got = self.store.get_tensor_with_parallelism(key, target)
-        self.assertTrue(torch.equal(got, updated_shard))
-
-    def test_batch_upsert_tensor_with_parallelism_tp_with_config(self):
-        require_unified_parallelism_api(self)
-        tp_size = 2
-        split_dim = 0
-        config = ReplicateConfig()
-        config.replica_num = 1
-        keys = ["tp_upsert_pub_batch_0", "tp_upsert_pub_batch_1"]
-        base = [torch.ones(4, 4, dtype=torch.float32).contiguous(),
-                torch.full((4, 4), 2.0, dtype=torch.float32).contiguous()]
-        updates = [torch.full((4, 4), 9.0, dtype=torch.float32).contiguous(),
-                   torch.full((4, 4), 11.0, dtype=torch.float32).contiguous()]
-        base_shards = [tensor.chunk(tp_size, split_dim)[0].contiguous() for tensor in base]
-        update_shards = [tensor.chunk(tp_size, split_dim)[0].contiguous() for tensor in updates]
-        parallelism = make_tensor_parallelism(
-            [make_parallel_axis("tp", rank=0, size=tp_size, split_dim=split_dim)]
-        )
-        targets = [make_read_target("shard", parallelism) for _ in keys]
-
-        self.assertEqual(
-            list(self.store.batch_put_tensor_with_parallelism(keys, base_shards, [parallelism] * len(keys), config=config)),
-            [0, 0],
-        )
-        self.assertEqual(
-            list(self.store.batch_upsert_tensor_with_parallelism(keys, update_shards, [parallelism] * len(keys), config=config)),
-            [0, 0],
-        )
-
-        got_shards = self.store.batch_get_tensor_with_parallelism(keys, targets)
-        for got, expected in zip(got_shards, update_shards):
-            self.assertTrue(torch.equal(got, expected))
-
-
 # ==========================================
 #  6. Mixed Scenarios
 # ==========================================
 
+
 class TestUpsertMixed(UpsertTestBase):
     """Cross-interface scenarios."""
 
@@ -1117,9 +531,7 @@ def test_multiple_sequential_upserts(self):
     print("   Raw bytes:  upsert, upsert_parts, upsert_batch,")
     print("               upsert_from, batch_upsert_from")
     print("   Tensor:     upsert_tensor, batch_upsert_tensor,")
-    print("               upsert_tensor_from, batch_upsert_tensor_from,")
-    print("               upsert_tensor_with_parallelism,")
-    print("               batch_upsert_tensor_with_parallelism")
+    print("               upsert_tensor_from, batch_upsert_tensor_from")
     print("   Pub tensor: upsert_pub_tensor, batch_upsert_pub_tensor")
     print("   Mixed:      cross-interface, sequential, size changes")
     unittest.main(verbosity=2)
diff --git a/scripts/tone_tests/README_en.md b/scripts/tone_tests/README_en.md
index c2cc8f4535..e8b01da39b 100644
--- a/scripts/tone_tests/README_en.md
+++ b/scripts/tone_tests/README_en.md
@@ -23,6 +23,15 @@ This directory contains end-to-end (E2E) test cases for the Mooncake project. Th
 
 **Description**: Prefill-Decode disaggregation test with different TP configurations
 
+### 4. test_vllm_1p1d_erdma.sh
+
+**Description**: vLLM Prefill-Decode disaggregation test with the Mooncake connector
+
+The ROCm core tier runs this as serialized smoke coverage with
+`num_workers=1`. It validates basic connector and transfer behavior, but it
+does not validate concurrent sender workers while
+[vLLM issue #44238](https://github.com/vllm-project/vllm/issues/44238) remains unresolved.
+
 ## T-One/tone-cli Support
 
 [tone-cli](https://gitee.com/anolis/tone-cli/tree/master/tests/mooncake-ci-test) provides the following automation features:
@@ -184,7 +193,7 @@ run_test()
     ${docker_exec} "\
         cd /test_workspace && \
         python3 -m pytest test_demo.py -v -s --tb=long" | tee "$log_file"
-    
+
     return ${PIPESTATUS[0]}
 }
 
@@ -210,7 +219,7 @@ if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
     if ! run_test; then
         exit_code=1
     fi
-    
+
     parse $exit_code
     exit $?
 fi
diff --git a/scripts/tone_tests/README_zh.md b/scripts/tone_tests/README_zh.md
index b29ceedc99..96baffe1e6 100644
--- a/scripts/tone_tests/README_zh.md
+++ b/scripts/tone_tests/README_zh.md
@@ -23,6 +23,15 @@
 
 **用例说明**：不同 TP 配置的 Prefill-Decode 分离架构测试
 
+### 4. test_vllm_1p1d_erdma.sh
+
+**用例说明**：使用 Mooncake connector 的 vLLM Prefill-Decode 分离测试
+
+ROCm core tier 使用 `num_workers=1` 运行串行 smoke test。该用例验证基础的
+connector 和传输行为，但在
+[vLLM issue #44238](https://github.com/vllm-project/vllm/issues/44238)
+解决前，不覆盖并发 sender worker 场景。
+
 
 ## T-One/tone-cli 支持
 
@@ -185,7 +194,7 @@ run_test()
     ${docker_exec} "\
         cd /test_workspace && \
         python3 -m pytest test_demo.py -v -s --tb=long" | tee "$log_file"
-    
+
     return ${PIPESTATUS[0]}
 }
 
@@ -211,7 +220,7 @@ if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
     if ! run_test; then
         exit_code=1
     fi
-    
+
     parse $exit_code
     exit $?
 fi
diff --git a/scripts/tone_tests/python/test_hicache_storage_mooncake_backend.py b/scripts/tone_tests/python/test_hicache_storage_mooncake_backend.py
index e3d751c356..f736b60c45 100644
--- a/scripts/tone_tests/python/test_hicache_storage_mooncake_backend.py
+++ b/scripts/tone_tests/python/test_hicache_storage_mooncake_backend.py
@@ -22,6 +22,8 @@
     is_in_ci,
 )
 
+ROCM_MHA_MODEL_NAME_FOR_TEST = "Qwen/Qwen3-8B"
+
 
 class HiCacheStorageMooncakeBackendBaseMixin(HiCacheStorageBaseMixin):
     """Base mixin class with common setup and utilities"""
@@ -30,6 +32,12 @@ class HiCacheStorageMooncakeBackendBaseMixin(HiCacheStorageBaseMixin):
     mooncake_master_port_base = 50051
     mooncake_metadata_port_base = 8080
 
+    @classmethod
+    def _get_model_name(cls):
+        if os.getenv("CI_ACCELERATOR") == "rocm":
+            return ROCM_MHA_MODEL_NAME_FOR_TEST
+        return super()._get_model_name()
+
     @classmethod
     def setUpClass(cls):
         """Set up test environment and launch Mooncake services before server setup"""
@@ -285,9 +293,45 @@ def _get_additional_server_args_and_env(cls):
 
     def test_eval_accuracy(self):
         """Test eval accuracy with cache persistence across cache flushes"""
-        from test_hicache_storage_file_backend import run_eval_accuracy_test
-
-        run_eval_accuracy_test(self)
+        if os.getenv("CI_ACCELERATOR") != "rocm":
+            from test_hicache_storage_file_backend import run_eval_accuracy_test
+
+            run_eval_accuracy_test(self)
+            return
+
+        # Qwen3 can spend the upstream 512-token budget entirely in its
+        # thinking trace, leaving no final GSM8K answer. Give ROCm CI enough
+        # room to finish the answer so this remains a cache-accuracy test rather
+        # than a reasoning-length lottery.
+        from types import SimpleNamespace
+
+        from sglang.test.run_eval import run_eval
+
+        args = SimpleNamespace(
+            base_url=f"http://{self.base_host}:{self.base_port}",
+            eval_name="gsm8k",
+            api="completion",
+            max_tokens=2048,
+            num_examples=200,
+            num_threads=64,
+        )
+        metrics_initial = run_eval(args)
+        self.flush_cache()
+        metrics_cached = run_eval(args)
+
+        accuracy_diff = abs(metrics_initial["score"] - metrics_cached["score"])
+        print(f"Accuracy difference: {accuracy_diff:.4f}")
+        self.assertGreater(
+            metrics_initial["score"], 0.6, "Initial accuracy should be reasonable"
+        )
+        self.assertGreater(
+            metrics_cached["score"], 0.6, "Cached accuracy should be reasonable"
+        )
+        self.assertLess(
+            accuracy_diff,
+            0.03,
+            "Accuracy should be consistent between cache states",
+        )
 
 
 if __name__ == "__main__":
diff --git a/scripts/tone_tests/python/test_moe_mooncake.py b/scripts/tone_tests/python/test_moe_mooncake.py
index cce365dfeb..c6a87e4493 100644
--- a/scripts/tone_tests/python/test_moe_mooncake.py
+++ b/scripts/tone_tests/python/test_moe_mooncake.py
@@ -1,8 +1,9 @@
-'''
+"""
 this test case is from https://github.com/HanHan009527/sglang/blob/a100-ci/test/manual/ep/test_moe_mooncake.py
 End-to-End Integration Test for SGLang with Mooncake Elastic EP Backend.
-'''
+"""
 
+import os
 import unittest
 from types import SimpleNamespace
 
@@ -17,8 +18,7 @@
     popen_launch_server,
 )
 
-ib_devices = get_rdma_devices_args()
-
+ib_devices = os.getenv("MOONCAKE_DEVICE") or get_rdma_devices_args()
 
 
 class TestMooncakeBackend(CustomTestCase):
diff --git a/scripts/tone_tests/python/verify_rocm_wheel.py b/scripts/tone_tests/python/verify_rocm_wheel.py
new file mode 100644
index 0000000000..f247611844
--- /dev/null
+++ b/scripts/tone_tests/python/verify_rocm_wheel.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+
+"""Verify that the active Mooncake native modules belong to the ROCm wheel."""
+
+import base64
+import hashlib
+import importlib
+import importlib.metadata as metadata
+from pathlib import Path
+
+
+def record_digest(path: Path, algorithm: str) -> str:
+    digest = hashlib.new(algorithm, path.read_bytes()).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+
+def main() -> None:
+    distribution = metadata.distribution("mooncake-transfer-engine-rocm")
+    package = importlib.import_module("mooncake")
+    package_dir = Path(package.__file__).resolve().parent
+    records = {str(item): item for item in distribution.files or ()}
+    expected_files = {
+        "mooncake/engine.so": "mooncake.engine",
+        "mooncake/store.so": "mooncake.store",
+        "mooncake/mooncake_master": None,
+    }
+
+    print("Mooncake package:", package.__file__)
+    print("Mooncake ROCm distribution:", distribution.version)
+    for relative_path, module_name in expected_files.items():
+        record = records.get(relative_path)
+        if record is None or record.hash is None:
+            raise RuntimeError(f"Missing hashed wheel record: {relative_path}")
+
+        installed_path = Path(distribution.locate_file(record)).resolve()
+        package_path = (package_dir / Path(relative_path).name).resolve()
+        if installed_path != package_path:
+            raise RuntimeError(
+                f"{relative_path} resolves outside the active Mooncake package: "
+                f"{installed_path} != {package_path}"
+            )
+
+        digest = record_digest(installed_path, record.hash.mode)
+        if digest != record.hash.value:
+            raise RuntimeError(f"Installed file does not match wheel: {installed_path}")
+
+        if module_name is not None:
+            module = importlib.import_module(module_name)
+            if Path(module.__file__).resolve() != installed_path:
+                raise RuntimeError(
+                    f"{module_name} loaded from an unexpected path: {module.__file__}"
+                )
+
+        print(relative_path, installed_path, f"{record.hash.mode}={digest}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/tone_tests/rocm_runner.env.example b/scripts/tone_tests/rocm_runner.env.example
new file mode 100644
index 0000000000..c72725d515
--- /dev/null
+++ b/scripts/tone_tests/rocm_runner.env.example
@@ -0,0 +1,32 @@
+# Host-owned profile for the controller-only ROCm self-hosted runner.
+# Install as /etc/mooncake-ci/runner.env; do not store credentials here.
+CI_ACCELERATOR=rocm
+MOONCAKE_CI_TIER=core-4gpu
+LOCAL_IP=192.168.210.1
+REMOTE_IP=192.168.210.2
+REMOTE_SSH_TARGET=mooncake-worker
+REMOTE_TEST_DIR=/var/lib/mooncake-ci/work
+MODEL_CACHE=/var/lib/mooncake-ci/cache
+# Keep compiler/JIT output off the runner root filesystem. The harness creates
+# a separate subdirectory per pinned container image.
+MOONCAKE_RUNTIME_CACHE=/data/mooncake-ci/runtime-cache
+MOONCAKE_RENDER_DEVICES="/dev/dri/renderD129 /dev/dri/renderD137 /dev/dri/renderD145 /dev/dri/renderD153"
+MOONCAKE_GPU_INDICES=0,1,2,3
+MOONCAKE_CPUSET_CPUS=0-95
+MOONCAKE_CPUSET_MEMS=0
+MOONCAKE_SGLANG_BASE_GPU_ID=0
+MOONCAKE_EPD_ENCODER_GPU_ID=0
+MOONCAKE_EPD_PREFILL_GPU_ID=2
+MOONCAKE_EPD_DECODE_GPU_ID=0
+MOONCAKE_VLLM_VISIBLE_DEVICES=0,1
+MOONCAKE_SGLANG_MEM_FRACTION_STATIC=0.5
+MOONCAKE_RDMA_DEVICES=ionic_0,ionic_1,ionic_2,ionic_3
+MOONCAKE_RDMA_NETDEVS=eth2,eth3,eth4,eth5
+# Keep Mooncake traffic on one verified local/remote rail. NCCL may still use
+# every device listed in MOONCAKE_RDMA_DEVICES.
+MOONCAKE_TRANSFER_DEVICE=ionic_0
+MOONCAKE_GID_INDEX=1
+AINIC_VERSION=1.117.5
+MOONCAKE_SSH_CONFIG=/etc/mooncake-ci/runner_ssh_config
+MOONCAKE_LOCK_FILE=/var/lib/mooncake-ci/run/mooncake.lock
+CONTAINER_NAME=mooncake-rocm-ci
diff --git a/scripts/tone_tests/scripts/common.sh b/scripts/tone_tests/scripts/common.sh
index 68e5518ea0..c26da80d03 100755
--- a/scripts/tone_tests/scripts/common.sh
+++ b/scripts/tone_tests/scripts/common.sh
@@ -1,16 +1,16 @@
 #!/bin/bash
 
-TEST_CASE_RESULT_PATH="run/logs/$test_case_name"
+TEST_CASE_RESULT_PATH="run/logs/${test_case_name:-}"
 docker_exec="docker exec ${CONTAINER_NAME} bash -c"
 
 setup_directory(){
     local dir_path=$1
-    
+
     if [ -z "$dir_path" ]; then
         echo "ERROR: Directory path not provided" >&2
         return 1
     fi
-    
+
     if [ -d "$dir_path" ]; then
         echo "Directory already exists: $dir_path"
         return 0
@@ -27,7 +27,7 @@ setup_directory(){
 
 setup_log_directory(){
     local log_dir="$1"
-    
+
     if [ -d "$log_dir" ]; then
         echo "Removing existing log directory: $log_dir"
         rm -rf "$log_dir"
@@ -36,24 +36,218 @@ setup_log_directory(){
     echo "Log directory set up at: $log_dir"
 }
 
+prepare_rocm_runtime_cache_args() {
+    local registry_addr=$1
+    local cache_root=${MOONCAKE_RUNTIME_CACHE:-}
+    local cache_key image_cache_dir cache_dir
+
+    if [ -z "$cache_root" ]; then
+        echo "ERROR: MOONCAKE_RUNTIME_CACHE is required for ROCm" >&2
+        return 1
+    fi
+    if ! [[ "$cache_root" =~ ^/[A-Za-z0-9._/-]+$ ]]; then
+        echo "ERROR: MOONCAKE_RUNTIME_CACHE must be an absolute path without spaces: $cache_root" >&2
+        return 1
+    fi
+    mkdir -p -- "$cache_root" || return 1
+    cache_root=$(cd -P -- "$cache_root" && pwd) || return 1
+    if [ "$cache_root" = "/" ]; then
+        echo "ERROR: MOONCAKE_RUNTIME_CACHE must not resolve to /" >&2
+        return 1
+    fi
+
+    cache_key=${registry_addr##*@sha256:}
+    if [ "$cache_key" = "$registry_addr" ]; then
+        cache_key=$(printf '%s' "$registry_addr" | cksum | awk '{print $1}')
+    fi
+    cache_key=${cache_key:0:16}
+    image_cache_dir="${cache_root}/${cache_key}"
+    for cache_dir in \
+        aiter-jit pip tmp torch-extensions torchinductor triton xdg; do
+        mkdir -p -- "${image_cache_dir}/${cache_dir}" || return 1
+        [ -w "${image_cache_dir}/${cache_dir}" ] || {
+            echo "ERROR: ROCm runtime cache is not writable: ${image_cache_dir}/${cache_dir}" >&2
+            return 1
+        }
+    done
+
+    ROCM_RUNTIME_CACHE_ARGS=(
+        -v "${image_cache_dir}:/runtime-cache"
+        -e AITER_JIT_DIR=/runtime-cache/aiter-jit
+        -e PIP_CACHE_DIR=/runtime-cache/pip
+        -e TMPDIR=/runtime-cache/tmp
+        -e TORCH_EXTENSIONS_DIR=/runtime-cache/torch-extensions
+        -e TORCHINDUCTOR_CACHE_DIR=/runtime-cache/torchinductor
+        -e TRITON_CACHE_DIR=/runtime-cache/triton
+        -e XDG_CACHE_HOME=/runtime-cache/xdg
+    )
+    echo "Using image-scoped ROCm runtime cache: $image_cache_dir"
+}
+
 docker_launch(){
     local registry_addr=$1
     local extra_args=$2
 
-    docker_run_cmd="docker run  --init --name ${CONTAINER_NAME} \
-    -d --ipc=host --cap-add=SYS_PTRACE --network=host --gpus all \
-    --ulimit memlock=-1 --ulimit stack=67108864 --shm-size=128g \
-    -v ${MODEL_CACHE}:/root/.cache $extra_args --privileged \
-    -v $BASE_DIR:/test_run \
-    -v /root/test.jsonl:/tmp/test.jsonl \
-    --entrypoint bash \
-    ${registry_addr} -c \"hostname;sleep 360000\""
-
-    echo "Executing Docker run command:"
-    echo "$docker_run_cmd"
-    if ! eval "$docker_run_cmd"; then
-        echo "ERROR: Failed to launch docker container" >&2
-        return 1
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        local -a docker_args=(
+            run --init --name "${CONTAINER_NAME}" -d
+            --network=host
+            --device=/dev/kfd
+            --cpuset-cpus="${MOONCAKE_CPUSET_CPUS}"
+            --cpuset-mems="${MOONCAKE_CPUSET_MEMS}"
+            --cap-drop=ALL
+            # apt/dpkg drops privileges to _apt while installing the standard
+            # verbs userspace. Retain only the filesystem/identity capabilities
+            # needed for that setup; serving never receives the default Docker
+            # capability set.
+            --cap-add=CHOWN
+            --cap-add=DAC_OVERRIDE
+            --cap-add=FOWNER
+            --cap-add=IPC_LOCK
+            --cap-add=SETGID
+            --cap-add=SETUID
+            # Mooncake queries page placement with move_pages(2) to select the
+            # nearest RoCE rail. Docker's default seccomp profile rejects that
+            # syscall with EPERM even for the container's own pages. Keep the
+            # capability and device allowlists above as the security boundary.
+            --security-opt=seccomp=unconfined
+            --security-opt=no-new-privileges:true
+            --pids-limit=32768
+            --ulimit memlock=-1:-1
+            --ulimit stack=67108864:67108864
+            --shm-size=128g
+            --stop-timeout=120
+            -e CI_ACCELERATOR=rocm
+            -e CI=true
+            -e PYTHONDONTWRITEBYTECODE=1
+            -e PYTHONFAULTHANDLER=1
+            -e PYTHONUNBUFFERED=1
+            -e "PYTEST_ADDOPTS=-p no:cacheprovider"
+            -e NCCL_GIN_TYPE=0
+            -e "NCCL_IB_HCA=${MOONCAKE_RDMA_DEVICES}"
+            -e "NCCL_SOCKET_IFNAME=${MOONCAKE_RDMA_NETDEVS}"
+            -e "MOONCAKE_DEVICE=${MOONCAKE_TRANSFER_DEVICE}"
+            -e "MC_GID_INDEX=${MOONCAKE_GID_INDEX}"
+            -e MC_FORCE_HCA=1
+            # The MI35x image enables a host-wide SGLang affinity heuristic.
+            # It ignores Docker's cpuset and assigns TP rank 1 to CPU96+, which
+            # is outside this NUMA0 allocation. Docker already enforces the
+            # correct affinity, so disable the conflicting inner policy.
+            -e SGLANG_SET_CPU_AFFINITY=0
+            -v "${MODEL_CACHE}:/root/.cache"
+            -v "${BASE_DIR}:/test_run"
+            --entrypoint bash
+        )
+        prepare_rocm_runtime_cache_args "$registry_addr" || return 1
+        docker_args+=("${ROCM_RUNTIME_CACHE_ARGS[@]}")
+        local host_libionic=""
+        if command -v ldconfig >/dev/null 2>&1; then
+            host_libionic=$(ldconfig -p 2>/dev/null | awk '/libionic[.]so[.]1/{print $NF; exit}')
+        fi
+        if [ -z "$host_libionic" ]; then
+            local ionic_candidate
+            for ionic_candidate in \
+                /usr/lib/x86_64-linux-gnu/libionic.so.1 \
+                /lib/x86_64-linux-gnu/libionic.so.1; do
+                if [ -r "$ionic_candidate" ]; then
+                    host_libionic=$ionic_candidate
+                    break
+                fi
+            done
+        fi
+        if [ -n "$host_libionic" ]; then
+            host_libionic=$(readlink -f "$host_libionic")
+        fi
+        if [ -n "$host_libionic" ] && [ -r "$host_libionic" ]; then
+            echo "Using host-matched Ionic provider library: $host_libionic"
+            docker_args+=(-v "${host_libionic}:/opt/mooncake-host-rdma/libionic.so.1:ro")
+        else
+            echo "WARNING: Host libionic.so.1 is unavailable; ROCm images must provide a compatible Ionic provider" >&2
+        fi
+        local -a render_nodes
+        read -r -a render_nodes <<<"${MOONCAKE_RENDER_DEVICES:-}"
+        if [ "${#render_nodes[@]}" -eq 0 ]; then
+            echo "ERROR: ROCm profile must expose at least one render node" >&2
+            return 1
+        fi
+        local device
+        for device in "${render_nodes[@]}"; do
+            if [[ ! "$device" =~ ^/dev/dri/render[D][0-9]+$ ]] || [ ! -c "$device" ]; then
+                echo "ERROR: Invalid or missing ROCm render node: $device" >&2
+                return 1
+            fi
+            docker_args+=(--device="$device")
+        done
+        if [ -z "${MOONCAKE_RDMA_DEVICES:-}" ]; then
+            echo "ERROR: MOONCAKE_RDMA_DEVICES is required for ROCm" >&2
+            return 1
+        fi
+        local rdma_device verbs_path uverbs_node uverbs_found
+        local -A mounted_uverbs=()
+        for rdma_device in ${MOONCAKE_RDMA_DEVICES//,/ }; do
+            verbs_path="/sys/class/infiniband/${rdma_device}/device/infiniband_verbs"
+            [ -d "$verbs_path" ] || {
+                echo "ERROR: Missing verbs mapping for RDMA device $rdma_device" >&2
+                return 1
+            }
+            uverbs_found=0
+            for uverbs_node in "$verbs_path"/uverbs*; do
+                [ -e "$uverbs_node" ] || continue
+                uverbs_found=1
+                device="/dev/infiniband/$(basename "$uverbs_node")"
+                [ -c "$device" ] || {
+                    echo "ERROR: Missing RDMA character device $device" >&2
+                    return 1
+                }
+                if [ -z "${mounted_uverbs[$device]:-}" ]; then
+                    docker_args+=(--device="$device")
+                    mounted_uverbs[$device]=1
+                fi
+            done
+            if [ "$uverbs_found" -eq 0 ]; then
+                echo "ERROR: No userspace verbs device found for RDMA device $rdma_device" >&2
+                return 1
+            fi
+        done
+        if [ -c /dev/infiniband/rdma_cm ]; then
+            docker_args+=(--device=/dev/infiniband/rdma_cm)
+        fi
+        if [ "${USE_HUGGINGFACE_MIRROR}" = "true" ]; then
+            docker_args+=(-e "HF_ENDPOINT=${HUGGINGFACE_MIRROR}" -e HF_HUB_ENABLE_HF_TRANSFER=1)
+        fi
+        if [ "${USE_MODELSCOPE}" = "true" ]; then
+            docker_args+=(-e SGLANG_USE_MODELSCOPE=true)
+        fi
+        if [ -n "${HF_TOKEN_FILE:-}" ] && [ -r "$HF_TOKEN_FILE" ]; then
+            local hf_token
+            hf_token=$(<"$HF_TOKEN_FILE")
+            [ -n "$hf_token" ] || { echo "ERROR: $HF_TOKEN_FILE is empty" >&2; return 1; }
+            export HF_TOKEN="$hf_token"
+            docker_args+=(-e HF_TOKEN)
+        fi
+        printf 'Executing Docker run command:'
+        printf ' %q' docker "${docker_args[@]}" "$registry_addr" -c 'hostname; sleep 360000'
+        printf '\n'
+        if ! docker "${docker_args[@]}" "$registry_addr" -c 'hostname; sleep 360000'; then
+            echo "ERROR: Failed to launch ROCm container" >&2
+            return 1
+        fi
+    else
+        docker_run_cmd="docker run  --init --name ${CONTAINER_NAME} \
+        -d --ipc=host --cap-add=SYS_PTRACE --network=host --gpus all \
+        --ulimit memlock=-1 --ulimit stack=67108864 --shm-size=128g \
+        -v ${MODEL_CACHE}:/root/.cache $extra_args --privileged \
+        -v $BASE_DIR:/test_run \
+        -v /root/test.jsonl:/tmp/test.jsonl \
+        --entrypoint bash \
+        ${registry_addr} -c \"hostname;sleep 360000\""
+
+        echo "Executing Docker run command:"
+        echo "$docker_run_cmd"
+        if ! eval "$docker_run_cmd"; then
+            echo "ERROR: Failed to launch docker container" >&2
+            return 1
+        fi
     fi
 
     pip_cmd=""
@@ -86,7 +280,17 @@ docker_launch(){
     fi
     local relative_path=${TEST_RUN_DIR#$BASE_DIR}
     local cleaned_path=${relative_path#/}
-    pip_cmd=$(append_str "${pip_cmd}" "pip install --force-reinstall /test_run/$cleaned_path/whls/$mooncake_whl_file")
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        # SGLang and vLLM images may already contain the CUDA distribution.
+        # The CUDA and ROCm distributions share the same `mooncake` package,
+        # so installing the ROCm wheel on top leaves a mixture of old and new
+        # Python modules/native libraries and breaks the Store RPC ABI.
+        pip_cmd=$(append_str "${pip_cmd}" \
+            "python3 -m pip uninstall -y mooncake-transfer-engine mooncake-transfer-engine-rocm")
+        pip_cmd=$(append_str "${pip_cmd}" \
+            "python3 -c 'import shutil, site, sysconfig; from pathlib import Path; roots={Path(path).resolve() for path in (*site.getsitepackages(), site.getusersitepackages(), sysconfig.get_path(\"purelib\"), sysconfig.get_path(\"platlib\")) if path}; packages=sorted({root / \"mooncake\" for root in roots}); [(print(\"Removing orphaned Mooncake package:\", package), shutil.rmtree(package)) for package in packages if package.is_dir()]'")
+    fi
+    pip_cmd=$(append_str "${pip_cmd}" "python3 -m pip install --force-reinstall /test_run/$cleaned_path/whls/$mooncake_whl_file")
 
     # Check if sglang-router is needed and missing
     if [[ "$registry_addr" == *"sglang"* ]]; then
@@ -100,23 +304,110 @@ docker_launch(){
         else
             echo "sglang-router already installed, skipping"
         fi
+        # Reuse SGLang CI's single source of truth for the git-only evaluator
+        # pin instead of duplicating the commit here.
+        pip_cmd=$(append_str "${pip_cmd}" \
+            'source /sgl-workspace/sglang/scripts/ci/utils/sgl_eval_ref.sh && pip install "$SGL_EVAL_SPEC"')
+    fi
+
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        local rocm_rdma_cmd="set -euo pipefail
+rdma_ready=false
+if command -v ibv_devinfo >/dev/null 2>&1 && ibv_devinfo >/tmp/mooncake-ibv-devinfo.log 2>&1; then
+    rdma_ready=true
+    echo 'ROCm RoCE userspace is functional'
+else
+    echo 'Initial ibv_devinfo failure:' >&2
+    cat /tmp/mooncake-ibv-devinfo.log >&2 2>/dev/null || true
+    echo 'Installing AMD Pensando AINIC userspace ${AINIC_VERSION}'
+    apt-get update
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        apt-transport-https ca-certificates curl gnupg
+    install -d -m 0755 /etc/apt/keyrings
+    curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key \
+        | gpg --dearmor --yes --output /etc/apt/keyrings/amdainic.gpg
+    echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/amdainic.gpg] https://repo.radeon.com/amdainic/pensando/ubuntu/${AINIC_VERSION} ${ubuntu_codename} main' \
+        > /etc/apt/sources.list.d/amdainic.list
+    apt-get update
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        ibverbs-utils ionic-common libionic-dev librdmacm1
+    rm -rf /var/lib/apt/lists/*
+fi
+
+if [ \"\$rdma_ready\" != true ] && [ -r /opt/mooncake-host-rdma/libionic.so.1 ]; then
+    echo 'Overlaying host-matched Ionic provider library'
+    # Let the package installation update the loader cache before replacing
+    # its ABI-incompatible provider. Running ldconfig afterwards would restore
+    # libionic.so.1 to the newer container library.
+    ldconfig
+    install -m 0644 /opt/mooncake-host-rdma/libionic.so.1 \
+        /usr/lib/x86_64-linux-gnu/libionic-host.so.1
+    ln -sfn libionic-host.so.1 /usr/lib/x86_64-linux-gnu/libionic.so.1
+    ln -sfn libionic-host.so.1 /usr/lib/x86_64-linux-gnu/libionic.so
+
+    verbs_abi=\$(find /usr/lib/x86_64-linux-gnu/libibverbs -maxdepth 1 \
+        \( -type f -o -type l \) 2>/dev/null \
+        | sed -n 's/.*-rdmav\([0-9][0-9]*\)[.]so$/\1/p' | head -n 1)
+    if [ -n \"\$verbs_abi\" ]; then
+        ln -sfn ../libionic-host.so.1 \
+            /usr/lib/x86_64-linux-gnu/libibverbs/libionic-rdmav\${verbs_abi}.so
+        echo 'Ionic provider path:' \
+            \"\$(readlink -f /usr/lib/x86_64-linux-gnu/libibverbs/libionic-rdmav\${verbs_abi}.so)\"
+    else
+        echo 'WARNING: Unable to determine the container libibverbs provider ABI' >&2
+    fi
+    echo 'Ionic provider checksums:'
+    sha256sum /opt/mooncake-host-rdma/libionic.so.1 \
+        /usr/lib/x86_64-linux-gnu/libionic-host.so.1
+fi"
+        echo "Checking ROCm RoCE userspace"
+        if ! ${docker_exec} "${rocm_rdma_cmd}"; then
+            echo "ERROR: Failed to install ROCm RoCE userspace" >&2
+            return 1
+        fi
+    else
+        echo "Installing ERDMA drivers"
+        echo "Executing ERDMA driver installation command:"
+        echo "${erdma_driver_cmd}"
+        if ! ${docker_exec} "${erdma_driver_cmd}"; then
+            echo "ERROR: Failed to install ERDMA drivers" >&2
+            return 1
+        fi
     fi
 
-    echo "Installing ERDMA drivers"
-    echo "Executing ERDMA driver installation command:"
-    echo "${erdma_driver_cmd}"
-    if ! ${docker_exec} "${erdma_driver_cmd}"; then
-        echo "ERROR: Failed to install ERDMA drivers" >&2
-        return 1
-    fi
-
-    echo "Checking RDMA devices"
-    echo "Executing ibv_devinfo check command:"
-    echo "ibv_devinfo"
-    if ! ${docker_exec} "ibv_devinfo" >/dev/null 2>&1; then
-        echo "ibv_devinfo execution failed" >&2
-        return 1
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        local rdma_device=${MOONCAKE_TRANSFER_DEVICE:-}
+        if [ -z "$rdma_device" ]; then
+            echo "ERROR: MOONCAKE_TRANSFER_DEVICE is required for ROCm" >&2
+            return 1
+        fi
+        if ! [[ "$rdma_device" =~ ^[a-zA-Z0-9_.-]+$ ]]; then
+            echo "ERROR: Invalid MOONCAKE_TRANSFER_DEVICE: $rdma_device" >&2
+            return 1
+        fi
+        echo "Checking ROCm RDMA device ${rdma_device}"
+        local rdma_preflight_cmd="set -e
+echo '=== ibv_devinfo ==='
+ibv_devinfo -d '${rdma_device}'
+echo '=== RDMA link state ==='
+if command -v rdma >/dev/null 2>&1; then rdma link show; fi
+state=\$(cat '/sys/class/infiniband/${rdma_device}/ports/1/state')
+echo '${rdma_device} port 1 state:' \"\$state\"
+case \"\$state\" in *ACTIVE*) ;; *) echo 'RDMA port is not active' >&2; exit 1;; esac
+	gid=\$(cat '/sys/class/infiniband/${rdma_device}/ports/1/gids/${MOONCAKE_GID_INDEX}')
+	echo '${rdma_device} GID index ${MOONCAKE_GID_INDEX}:' \"\$gid\"
+case \"\$gid\" in ''|'::'|'0:0:0:0:0:0:0:0') echo 'RDMA GID is empty' >&2; exit 1;; esac"
+        if ! ${docker_exec} "${rdma_preflight_cmd}"; then
+            echo "RDMA preflight failed for $rdma_device" >&2
+            return 1
+        fi
+        echo "RDMA preflight successful"
     else
+        echo "Checking RDMA devices"
+        if ! ${docker_exec} "ibv_devinfo" >/dev/null 2>&1; then
+            echo "ibv_devinfo execution failed" >&2
+            return 1
+        fi
         echo "ibv_devinfo execution successful"
     fi
 
@@ -131,7 +422,15 @@ docker_launch(){
         echo "ERROR: Failed to install Mooncake dependencies" >&2
         return 1
     fi
-    
+
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        local mooncake_install_check="python3 /test_run/python/verify_rocm_wheel.py && ! python3 -m pip show mooncake-transfer-engine >/dev/null 2>&1"
+        if ! ${docker_exec} "${mooncake_install_check}"; then
+            echo "ERROR: The ROCm wheel did not replace all image-provided Mooncake files" >&2
+            return 1
+        fi
+    fi
+
     return 0
 }
 
@@ -141,7 +440,7 @@ clean_container(){
         echo "No container name provided"
         return 1
     fi
-    
+
     # check if container exists
     if docker ps -a --format '{{.Names}}' | grep -q "^${container_name}$"; then
         echo "Stopping and removing existing container: ${container_name}"
@@ -165,7 +464,7 @@ clean_container(){
 append_str() {
     local original_str="$1"
     local append_value="$2"
-    
+
     if [ -z "$original_str" ]; then
         echo "$append_value"
     else
@@ -173,7 +472,7 @@ append_str() {
     fi
 }
 
-check_server_ready() { 
+check_server_ready() {
     local server_log_path=$1
     local max_attempts=${2:-120}
 
@@ -193,7 +492,7 @@ check_server_ready() {
             sleep 2
         fi
     done
-    
+
     echo "ERROR: Server failed to start within timeout"
     return 1
 }
@@ -215,11 +514,17 @@ check_server_ready_with_pattern() {
                 echo "Server is ready!"
                 return 0
             fi
+            if grep -qE 'Fatal Python error|Segfault encountered|Subprocess .* crashed with exit code' \
+                "$server_log_path" 2>/dev/null; then
+                echo "ERROR: Server process crashed during startup; see $server_log_path" >&2
+                tail -n 80 "$server_log_path" >&2
+                return 1
+            fi
             echo "Waiting... ($i/$max_attempts)"
             sleep 2
         fi
     done
-    
+
     echo "ERROR: Server did not become ready in time" >&2
     return 1
 }
@@ -229,10 +534,26 @@ get_whl(){
     echo "whls_path: $whls_path and mkdir..."
     mkdir -p "$whls_path"
 
-    echo "get whl file from github action"
+    echo "get whl file from CI artifacts"
     rm -f "$whls_path/mooncake.zip"
     rm -f "$whls_path"/*.whl
 
+    if [ -n "${WHEEL_DIR:-}" ]; then
+        local local_wheel=""
+        local local_wheel_count=0
+        while IFS= read -r wheel; do
+            local_wheel=$wheel
+            local_wheel_count=$((local_wheel_count + 1))
+        done < <(find "$WHEEL_DIR" -type f -name '*.whl' -print)
+        if [ "$local_wheel_count" -ne 1 ]; then
+            echo "ERROR: Expected exactly one wheel in $WHEEL_DIR, found $local_wheel_count" >&2
+            return 1
+        fi
+        cp -L "$local_wheel" "$whls_path/"
+        echo "Copied self-hosted Actions wheel: $(basename "$local_wheel")"
+        return 0
+    fi
+
     local max_retries=5
     local base_delay=5 # seconds
     local success=false
@@ -273,7 +594,7 @@ get_whl(){
         return 1
     fi
     echo "Found wheel file: $mooncake_whl_file"
-    
+
     echo "Successfully downloaded and extracted wheel file to $whls_path"
     return 0
 }
@@ -293,7 +614,7 @@ get_image(){
     return 0
 }
 
-check_proxy_ready() { 
+check_proxy_ready() {
     local proxy_log_path=$1
     local max_attempts=${2:-60}
     local expected_workers=2
@@ -305,7 +626,7 @@ check_proxy_ready() {
 
     echo "Waiting for SGLang Router to be ready and $expected_workers workers to be activated..."
     echo "Checking log file: $proxy_log_path"
-    
+
     for i in $(seq 1 $max_attempts); do
         activated_count=0
         tokenizer_ready=0
@@ -313,13 +634,13 @@ check_proxy_ready() {
         if [ -f "$proxy_log_path" ]; then
             # "Activated 1 worker(s) (marked as healthy)"
             activated_count=$(grep -cF "Activated 1 worker(s) (marked as healthy)" "$proxy_log_path" 2>/dev/null) || activated_count=0
-            
+
             # "Successfully loaded tokenizer"
             tokenizer_ready=$(grep -cE "Successfully (loaded|registered) tokenizer" "$proxy_log_path" 2>/dev/null) || tokenizer_ready=0
 
             # "Starting server on 0.0.0.0:8000"
             server_started=$(grep -cF "Starting server on 0.0.0.0" "$proxy_log_path" 2>/dev/null) || server_started=0
-            
+
             if [ "$activated_count" -ge "$expected_workers" ] && [ "$tokenizer_ready" -gt 0 ]; then
                 echo "Router is ready!"
                 echo "  - Workers activated: $activated_count/$expected_workers"
@@ -330,7 +651,7 @@ check_proxy_ready() {
                 return 0
             fi
         fi
-        
+
         if [ "$activated_count" -gt 0 ]; then
              echo "Waiting... ($i/$max_attempts) [Workers: $activated_count/$expected_workers, Tokenizer: $tokenizer_ready]"
         else
@@ -338,7 +659,7 @@ check_proxy_ready() {
         fi
         sleep 2
     done
-    
+
     echo "ERROR: Router failed to start or workers failed to register within timeout"
     return 1
 }
@@ -346,26 +667,31 @@ check_proxy_ready() {
 
 stop_container(){
     local container_name=${1:-$CONTAINER_NAME}
-    local remote_host=$2
+    local remote_host=${2:-}
     local location="local"
-    
+
     if [ -z "$container_name" ]; then
         echo "ERROR: No container name provided" >&2
         return 1
     fi
-    
+
     if [ -n "$remote_host" ]; then
         location="remote"
     fi
-    
+
     echo "Stopping ${location} Docker container: ${container_name}"
-    
+
     if [ "$location" == "remote" ]; then
-        ssh -o StrictHostKeyChecking=no $remote_host "docker stop ${container_name} >/dev/null 2>&1"
+        local ssh_target=$remote_host
+        if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+            ssh_target=${REMOTE_SSH_TARGET:-$remote_host}
+        fi
+        ${SSH_CMD:-ssh -o StrictHostKeyChecking=no} "$ssh_target" \
+            "docker stop ${container_name} >/dev/null 2>&1"
     else
         docker stop ${container_name} >/dev/null 2>&1
     fi
-    
+
     if [ $? -eq 0 ]; then
         echo "Successfully stopped ${location} container: ${container_name}"
         return 0
@@ -379,9 +705,9 @@ save_test_result() {
     local test_case_name=$1
     local status=$2
     local result_dir=$3
-    
+
     local result_json="${result_dir}/test_results.json"
-    
+
     echo "{\"test_case\": \"$test_case_name\", \"status\": \"$status\", \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > "$result_json"
     echo "Test results saved to: $result_json"
     echo "$test_case_name: $status"
@@ -389,36 +715,93 @@ save_test_result() {
 
 cleanup_test_env() {
     local test_type=$1
-    
+    local cleanup_failed=false
+
     echo "===== Cleaning up $test_type machine environment ====="
-    
-    stop_container "${CONTAINER_NAME}"
-    
-    if [ "$test_type" = "double" ] && [ -n "$REMOTE_IP" ]; then
-        stop_container "${CONTAINER_NAME}" "$REMOTE_IP"
-    fi
-    
-    echo "Cleanup completed"
+
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        if ! cleanup_rocm_node "local"; then
+            cleanup_failed=true
+        fi
+
+        if [ "$test_type" = "double" ] && [ -n "${REMOTE_IP:-}" ]; then
+            echo "===== Running ROCm postflight on remote node ${REMOTE_IP} ====="
+            if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "
+                source ${REMOTE_TEST_DIR}/run/.shrc && \
+                source ${REMOTE_TEST_DIR}/scripts/common.sh && \
+                cleanup_rocm_node remote
+            "; then
+                echo "ERROR: Remote ROCm cleanup/postflight failed on ${REMOTE_IP}" >&2
+                cleanup_failed=true
+            fi
+        fi
+    else
+        if ! stop_container "${CONTAINER_NAME}"; then
+            cleanup_failed=true
+        fi
+
+        if [ "$test_type" = "double" ] && [ -n "${REMOTE_IP:-}" ]; then
+            if ! stop_container "${CONTAINER_NAME}" "$REMOTE_IP"; then
+                cleanup_failed=true
+            fi
+        fi
+    fi
+
+    if $cleanup_failed; then
+        echo "ERROR: Cleanup did not complete successfully" >&2
+        return 1
+    fi
+
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        echo "Cleanup and postflight completed"
+    else
+        echo "Cleanup completed"
+    fi
+    return 0
+}
+
+# Return the maximum used memory, in MiB, for only this CI allocation.
+gpu_max_used_mb() {
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        command -v rocm-smi >/dev/null 2>&1 || return 1
+        rocm-smi --showmeminfo vram --json 2>/dev/null | python3 -c '
+import json, sys
+indices = {f"card{i}" for i in sys.argv[1].split(",")}
+data = json.load(sys.stdin)
+used = {}
+for card, values in data.items():
+    if card not in indices:
+        continue
+    for key, value in values.items():
+        if "VRAM Total Used Memory" in key:
+            used[card] = int(value) // (1024 * 1024)
+missing = sorted(indices - used.keys())
+if missing:
+    print("Missing ROCm memory data for: " + ", ".join(missing), file=sys.stderr)
+    print(-1)
+else:
+    print(max(used.values()))
+' "${MOONCAKE_GPU_INDICES:-0,1,2,3}"
+    else
+        command -v nvidia-smi >/dev/null 2>&1 || return 1
+        nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null \
+            | sort -n | tail -n 1
+    fi
 }
 
-# Wait until GPU memory on the local host drains below a threshold.
+# Wait until GPU memory on the allocated devices drains below a threshold.
 # Returns 0 once drained, 1 if it times out.
 wait_gpu_idle() {
     local max_seconds=${1:-90}
     local threshold_mb=${2:-1024}
 
-    if ! command -v nvidia-smi >/dev/null 2>&1; then
-        echo "ERROR: nvidia-smi not available; cannot verify GPU drain" >&2
-        return 1
-    fi
-
     echo "Waiting for GPU memory to drain (threshold ${threshold_mb}MB, timeout ${max_seconds}s)..."
     local elapsed=0
     local max_used=0
     while [ $elapsed -lt $max_seconds ]; do
-        max_used=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | sort -n | tail -n 1)
+        max_used=$(gpu_max_used_mb)
         if ! [[ "$max_used" =~ ^[0-9]+$ ]]; then
-            echo "ERROR: nvidia-smi query failed; cannot verify GPU drain" >&2
+            echo "ERROR: ${CI_ACCELERATOR:-CUDA} GPU memory query failed; cannot verify GPU drain" >&2
             return 1
         fi
         if [ "$max_used" -le "$threshold_mb" ]; then
@@ -432,6 +815,135 @@ wait_gpu_idle() {
     return 1
 }
 
+# Fail closed if KFD still reports a process with a queue on one of this
+# allocation's GPUs. Mapping the configured render nodes through KFD topology
+# keeps this check scoped to the shared host's ROCm CI partition.
+verify_no_allocated_gpu_processes() {
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        return 0
+    fi
+
+    local topology_root=${MOONCAKE_KFD_TOPOLOGY_ROOT:-/sys/class/kfd/kfd/topology/nodes}
+    local process_root=${MOONCAKE_KFD_PROCESS_ROOT:-/sys/class/kfd/kfd/proc}
+    if [ ! -d "$topology_root" ] || [ ! -d "$process_root" ]; then
+        echo "ERROR: KFD topology or process sysfs is unavailable" >&2
+        return 1
+    fi
+
+    local -a render_nodes
+    read -r -a render_nodes <<<"${MOONCAKE_RENDER_DEVICES:-}"
+    if [ "${#render_nodes[@]}" -eq 0 ]; then
+        echo "ERROR: MOONCAKE_RENDER_DEVICES is empty; cannot check ROCm processes" >&2
+        return 1
+    fi
+
+    local device render_minor node_dir node_render_minor gpu_id
+    local allocation_gpu_ids=""
+    for device in "${render_nodes[@]}"; do
+        if [ ! -e "$device" ] || [[ ! "$device" =~ /render[D]([0-9]+)$ ]]; then
+            echo "ERROR: Allocated ROCm render device is missing: $device" >&2
+            return 1
+        fi
+        render_minor=${BASH_REMATCH[1]}
+
+        gpu_id=""
+        for node_dir in "$topology_root"/*; do
+            [ -r "$node_dir/properties" ] && [ -r "$node_dir/gpu_id" ] || continue
+            node_render_minor=$(awk '$1 == "drm_render_minor" { print $2; exit }' \
+                "$node_dir/properties")
+            if [ "$node_render_minor" = "$render_minor" ]; then
+                gpu_id=$(tr -d '[:space:]' < "$node_dir/gpu_id")
+                break
+            fi
+        done
+        if ! [[ "$gpu_id" =~ ^[0-9]+$ ]] || [ "$gpu_id" = 0 ]; then
+            echo "ERROR: Could not map $device to a KFD GPU ID" >&2
+            return 1
+        fi
+        allocation_gpu_ids="${allocation_gpu_ids}${gpu_id}"$'\n'
+    done
+
+    local proc_dir queue_gpu_file queue_gpu_id pid
+    local remaining_pids=""
+    for proc_dir in "$process_root"/[0-9]*; do
+        [ -d "$proc_dir" ] || continue
+        pid=${proc_dir##*/}
+        for queue_gpu_file in "$proc_dir"/queues/*/gpuid; do
+            [ -r "$queue_gpu_file" ] || continue
+            queue_gpu_id=$(tr -d '[:space:]' < "$queue_gpu_file")
+            if printf '%s' "$allocation_gpu_ids" | grep -Fxq -- "$queue_gpu_id"; then
+                remaining_pids="${remaining_pids}${pid}"$'\n'
+                break
+            fi
+        done
+    done
+
+    remaining_pids=$(printf '%s' "$remaining_pids" | sort -nu)
+    if [ -n "$remaining_pids" ]; then
+        echo "ERROR: KFD processes remain on allocated ROCm GPUs:" >&2
+        ps -o pid,ppid,stat,args -p \
+            "$(printf '%s\n' "$remaining_pids" | paste -sd, -)" \
+            >&2 2>/dev/null || true
+        return 1
+    fi
+
+    echo "No KFD processes remain on the allocated ROCm GPUs"
+    return 0
+}
+
+# Final ROCm teardown is intentionally stricter than the reusable between-test
+# reset: remove the named container, then prove the allocated GPUs and device
+# handles are clean before releasing the cluster lock.
+cleanup_rocm_node() {
+    local location=${1:-local}
+    local cleanup_failed=false
+    local container_names
+
+    echo "Stopping and removing ${location} ROCm container: ${CONTAINER_NAME}"
+    if ! container_names=$(docker ps -a --format '{{.Names}}'); then
+        echo "ERROR: Failed to list ${location} Docker containers" >&2
+        cleanup_failed=true
+        container_names=""
+    fi
+
+    if printf '%s\n' "$container_names" | grep -Fxq -- "${CONTAINER_NAME}"; then
+        if ! docker stop "${CONTAINER_NAME}" >/dev/null 2>&1; then
+            echo "ERROR: Failed to stop ${location} container: ${CONTAINER_NAME}" >&2
+            cleanup_failed=true
+        fi
+        if ! docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1; then
+            echo "ERROR: Failed to remove ${location} container: ${CONTAINER_NAME}" >&2
+            cleanup_failed=true
+        fi
+    else
+        echo "No ${location} container named ${CONTAINER_NAME}"
+    fi
+
+    if ! container_names=$(docker ps -a --format '{{.Names}}'); then
+        echo "ERROR: Failed to verify ${location} Docker container removal" >&2
+        cleanup_failed=true
+    elif printf '%s\n' "$container_names" | grep -Fxq -- "${CONTAINER_NAME}"; then
+        echo "ERROR: ${location} container still exists: ${CONTAINER_NAME}" >&2
+        cleanup_failed=true
+    else
+        echo "Verified ${location} container removal: ${CONTAINER_NAME}"
+    fi
+
+    if ! wait_gpu_idle "${MOONCAKE_CLEANUP_TIMEOUT_SECONDS:-90}" \
+        "${MOONCAKE_GPU_IDLE_THRESHOLD_MB:-1024}"; then
+        echo "ERROR: ${location} ROCm GPU allocation did not drain" >&2
+        cleanup_failed=true
+    fi
+    if ! verify_no_allocated_gpu_processes; then
+        echo "ERROR: ${location} ROCm process postflight failed" >&2
+        cleanup_failed=true
+    fi
+
+    $cleanup_failed && return 1
+    echo "ROCm cleanup/postflight passed on ${location} node"
+    return 0
+}
+
 # Kill only GPU processes whose cgroup still identifies them as belonging to
 # the reused test container. Unknown or unrelated processes must be left alone;
 # the caller will quarantine the environment if GPU memory remains occupied.
@@ -442,6 +954,10 @@ gpu_pid_belongs_to_container() {
 }
 
 force_kill_container_gpu_procs() {
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        echo "ROCm cleanup refuses host PID killing; quarantine the allocation if container restart does not drain it" >&2
+        return 1
+    fi
     command -v nvidia-smi >/dev/null 2>&1 || return 1
 
     local container_id
@@ -511,6 +1027,13 @@ drain_gpu_local() {
 # state on both the local and (for double-machine runs) remote nodes via a
 # lightweight container restart (no wheel / ERDMA driver reinstall).
 drain_gpu_between_tests() {
+    # The reset protocol is currently defined only for the dedicated ROCm
+    # allocation. Preserve the existing CUDA/T-one lifecycle until an
+    # accelerator-neutral reset contract is introduced and validated there.
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        return 0
+    fi
+
     echo "===== Resetting environment between test cases ====="
     local reset_failed=false
     if ! drain_gpu_local; then
@@ -520,7 +1043,7 @@ drain_gpu_between_tests() {
 
     if [ -n "$REMOTE_IP" ]; then
         echo "Resetting environment on remote node $REMOTE_IP..."
-        if ! ${SSH_CMD} "$REMOTE_IP" "
+        if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "
             source ${REMOTE_TEST_DIR}/run/.shrc && \
             source ${REMOTE_TEST_DIR}/scripts/common.sh && \
             drain_gpu_local
@@ -537,7 +1060,7 @@ drain_gpu_between_tests() {
 setup_node_env() {
     local registry_addr=$1
     echo "===== Setting up docker environment ====="
-    
+
     if ! get_image "$registry_addr"; then
         echo "ERROR: Failed to get the required image"
         return 1
@@ -550,7 +1073,9 @@ setup_node_env() {
 
     local extra_args=""
     extra_args="$extra_args -e NCCL_GIN_TYPE=0 "
-    extra_args="$extra_args --device=/dev/infiniband/uverbs0 --device=/dev/infiniband/uverbs1 --device=/dev/infiniband/rdma_cm "
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        extra_args="$extra_args --device=/dev/infiniband/uverbs0 --device=/dev/infiniband/uverbs1 --device=/dev/infiniband/rdma_cm "
+    fi
     if [ "${USE_HUGGINGFACE_MIRROR}" = "true" ]; then
         extra_args="$extra_args -e HF_ENDPOINT=${HUGGINGFACE_MIRROR} -e HF_HUB_ENABLE_HF_TRANSFER=1"
     fi
@@ -568,40 +1093,93 @@ setup_node_env() {
 }
 
 launch_and_track_process() {
-    local full_cmd="$1"
-    local grep_pattern="$2"
-    local pid_file="$3"
+    local process_cmd=$1
+    local log_path=$2
+    local pid_file=$3
+    local grep_pattern=${4:-}
+
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        if [ -z "$grep_pattern" ]; then
+            echo "ERROR: CUDA process tracking requires a grep pattern" >&2
+            return 1
+        fi
 
-    echo "Executing command..."
-    echo "$full_cmd"
-    eval "$full_cmd"
+        local escaped_log launch_cmd
+        printf -v escaped_log '%q' "$log_path"
+        launch_cmd="${process_cmd} > ${escaped_log} 2>&1 &"
+        echo "Executing command..."
+        printf 'docker exec %q bash -c %q\n' "${CONTAINER_NAME}" "$launch_cmd"
+        if ! docker exec "${CONTAINER_NAME}" bash -c "$launch_cmd"; then
+            echo "ERROR: Failed to launch process in ${CONTAINER_NAME}" >&2
+            return 1
+        fi
 
-    echo "Waiting for process to initialize..."
-    for i in {1..15}; do
-        local container_main_pid=$(docker inspect --format '{{.State.Pid}}' "${CONTAINER_NAME}" 2>/dev/null)
-        if [ -n "$container_main_pid" ] && [ "$container_main_pid" != "0" ]; then
-            pid=$(ps -eo pid,ppid,cmd | awk -v root="$container_main_pid" -v pattern="$grep_pattern" '
-                BEGIN { pids[root] = 1 }
-                {
-                    if ($2 in pids && $0 ~ pattern) {
-                        print $1
-                        exit
+        echo "Waiting for process to initialize..."
+        local container_main_pid pid
+        for i in {1..15}; do
+            container_main_pid=$(docker inspect --format '{{.State.Pid}}' \
+                "${CONTAINER_NAME}" 2>/dev/null)
+            if [ -n "$container_main_pid" ] && [ "$container_main_pid" != "0" ]; then
+                pid=$(ps -eo pid,ppid,cmd | awk \
+                    -v root="$container_main_pid" -v pattern="$grep_pattern" '
+                    BEGIN { pids[root] = 1 }
+                    {
+                        if ($2 in pids && $0 ~ pattern) {
+                            print $1
+                            exit
+                        }
                     }
-                }
-            ')
-        fi
+                ')
+            fi
+
+            if [ -n "${pid:-}" ]; then
+                mkdir -p "$(dirname "$pid_file")"
+                echo "$pid" > "$pid_file"
+                echo "PID $pid (on host) saved to $pid_file"
+                return 0
+            fi
+
+            echo "  Attempt $i/15..."
+            sleep 2
+        done
+
+        echo "Process not found after 30 seconds"
+        return 1
+    fi
 
-        if [ -n "$pid" ]; then
-            echo "$pid" > "$pid_file"
-            echo "PID $pid (on host) saved to $pid_file"
+    local escaped_cmd escaped_log launch_cmd container_pid process_group
+
+    printf -v escaped_cmd '%q' "$process_cmd"
+    printf -v escaped_log '%q' "$log_path"
+    launch_cmd="setsid bash -c ${escaped_cmd} > ${escaped_log} 2>&1 < /dev/null & echo \$!"
+
+    echo "Executing command in a dedicated container process group..."
+    echo "$process_cmd"
+    container_pid=$(docker exec "${CONTAINER_NAME}" bash -c "$launch_cmd") || {
+        echo "ERROR: Failed to launch process in ${CONTAINER_NAME}" >&2
+        return 1
+    }
+    container_pid=$(printf '%s\n' "$container_pid" | tail -n 1 | tr -d '[:space:]')
+    if ! [[ "$container_pid" =~ ^[0-9]+$ ]]; then
+        echo "ERROR: Invalid container PID returned by launcher: $container_pid" >&2
+        return 1
+    fi
+
+    for i in {1..15}; do
+        process_group=$(docker exec "${CONTAINER_NAME}" \
+            ps -o pgid= -p "$container_pid" 2>/dev/null | tr -d '[:space:]')
+        if [[ "$process_group" =~ ^[0-9]+$ ]]; then
+            mkdir -p "$(dirname "$pid_file")"
+            echo "$process_group" > "$pid_file"
+            echo "Container process group $process_group saved to $pid_file"
             return 0
         fi
-        
-        echo "  Attempt $i/15..."
+
+        echo "  Waiting for process group... ($i/15)"
         sleep 2
     done
 
-    echo "Process not found after 30 seconds"
+    echo "ERROR: Container process group not found after 30 seconds" >&2
     return 1
 }
 
@@ -614,25 +1192,86 @@ kill_process() {
         return 0
     fi
 
-    local pid=$(cat "$pid_file")
-    if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        local pid
+        pid=$(cat "$pid_file")
+        if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
+            rm -f "$pid_file"
+            return 0
+        fi
+
+        echo "Stopping $service_name (PID: $pid)..."
+        kill -TERM "$pid" 2>/dev/null
+        sleep 2
+        if kill -0 "$pid" 2>/dev/null; then
+            kill -KILL "$pid" 2>/dev/null
+        fi
+
+        rm -f "$pid_file"
+        echo "✓ $service_name stopped"
+        return 0
+    fi
+
+    local process_group
+    process_group=$(tr -d '[:space:]' < "$pid_file")
+    if ! [[ "$process_group" =~ ^[0-9]+$ ]]; then
+        echo "ERROR: Invalid process group in $pid_file" >&2
+        rm -f "$pid_file"
+        return 1
+    fi
+
+    if ! docker exec "${CONTAINER_NAME}" bash -c \
+        "kill -0 -- -${process_group} 2>/dev/null"; then
         rm -f "$pid_file"
         return 0
     fi
 
-    echo "Stopping $service_name (PID: $pid)..."
-    
-    kill -TERM "$pid" 2>/dev/null
+    echo "Stopping $service_name (container process group: $process_group)..."
+    docker exec "${CONTAINER_NAME}" bash -c \
+        "kill -TERM -- -${process_group} 2>/dev/null || true"
+    local attempt
+    for attempt in {1..15}; do
+        if ! docker exec "${CONTAINER_NAME}" bash -c \
+            "kill -0 -- -${process_group} 2>/dev/null"; then
+            rm -f "$pid_file"
+            echo "✓ $service_name stopped"
+            return 0
+        fi
+        sleep 2
+    done
+
+    echo "Process group $process_group did not stop after SIGTERM; sending SIGKILL" >&2
+    docker exec "${CONTAINER_NAME}" bash -c \
+        "kill -KILL -- -${process_group} 2>/dev/null || true"
     sleep 2
-    if kill -0 "$pid" 2>/dev/null; then
-        kill -KILL "$pid" 2>/dev/null
+    if docker exec "${CONTAINER_NAME}" bash -c \
+        "kill -0 -- -${process_group} 2>/dev/null"; then
+        echo "ERROR: $service_name process group $process_group survived SIGKILL" >&2
+        return 1
     fi
-    
+
     rm -f "$pid_file"
     echo "✓ $service_name stopped"
     return 0
 }
 
+verify_model_processes_stopped() {
+    if [ "${CI_ACCELERATOR:-cuda}" != "rocm" ]; then
+        return 0
+    fi
+
+    local process_pattern='sglang[.]launch_server|sglang_router[.]launch_router|sglang::router|vllm[.]entrypoints[.]openai[.]api_server|mooncake_connector_proxy[.]py|toy_proxy_server[.]py'
+    local remaining
+    remaining=$(docker exec "${CONTAINER_NAME}" bash -c \
+        "ps -eo pid,ppid,pgid,stat,args | grep -E '${process_pattern}' | grep -v grep" 2>/dev/null || true)
+    if [ -n "$remaining" ]; then
+        echo "ERROR: Model processes remain in ${CONTAINER_NAME}:" >&2
+        echo "$remaining" >&2
+        return 1
+    fi
+    return 0
+}
+
 check_vllm_server_ready(){
     local server_log_path=$1
     local max_attempts=${2:-120}
@@ -653,7 +1292,7 @@ check_vllm_server_ready(){
             sleep 2
         fi
     done
-    
+
     echo "ERROR: Server failed to start within timeout"
     return 1
 }
@@ -680,7 +1319,7 @@ check_vllm_proxy_ready(){
             sleep 2
         fi
     done
-    
+
     echo "ERROR: Proxy failed to start within timeout"
     return 1
 }
@@ -701,7 +1340,7 @@ wait_for_server_ready() {
     for i in $(seq 1 $max_attempts); do
         local response_code
         response_code=$(curl -o /dev/null -s -w "%{http_code}" "http://$host:$port$endpoint" 2>/dev/null)
-        
+
         if [ "$response_code" = "200" ]; then
             echo "Server is ready! Health check returned 200."
             return 0
@@ -711,10 +1350,10 @@ wait_for_server_ready() {
         else
             echo "Waiting... ($i/$max_attempts) - Server not ready yet (response: $response_code)"
         fi
-        
+
         sleep 2
     done
-    
+
     echo "ERROR: Server failed to become ready within timeout (last response: $response_code)"
     return 1
 }
@@ -742,50 +1381,60 @@ convert_container_path_to_host() {
 setup_log_directory_dual() {
     local test_case_name=$1
     local model_name_clean=$2
-    
+
     setup_log_directory "$TEST_RUN_DIR/logs/$test_case_name/$model_name_clean"
-    
+
     if [ -n "$REMOTE_IP" ]; then
-        ${SSH_CMD} $REMOTE_IP "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && source ./common.sh && setup_log_directory \"\$TEST_RUN_DIR/logs/$test_case_name/$model_name_clean\""
+        ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && source ./common.sh && setup_log_directory \"\$TEST_RUN_DIR/logs/$test_case_name/$model_name_clean\""
     fi
 }
 
 cleanup_model_processes() {
     local pid_dir=$1
     local test_case_name=$2
-    
+
     echo "===== Killing model processes ====="
-    
+    local cleanup_failed=false
+
     if [ -d "$pid_dir" ]; then
         echo "Cleaning up by PID files in $pid_dir..."
         for pid_file in "${pid_dir}"/*.pid; do
             if [ -f "$pid_file" ]; then
                 local service_name=$(basename "$pid_file" .pid)
-                kill_process "$pid_file" "$service_name"
+                kill_process "$pid_file" "$service_name" || cleanup_failed=true
             fi
         done
     fi
-    
+
+    verify_model_processes_stopped || cleanup_failed=true
+
     if [ "$ISREMOTE" == "0" ] && [ -n "$REMOTE_IP" ]; then
         echo "===== Killing model processes (remote: $REMOTE_IP) ====="
-        ${SSH_CMD} "$REMOTE_IP" "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh stop_server" 2>/dev/null || true
+        if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" \
+            "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh stop_server"; then
+            echo "ERROR: Remote model-process cleanup failed" >&2
+            cleanup_failed=true
+        fi
     fi
-    
+
     echo "Process cleanup completed."
+    $cleanup_failed && return 1
+    return 0
 }
 
 collect_remote_log_file() {
     local model_name_clean=$1
     local remote_log_filename=$2
     local test_case_name=$3
-    
+
     local remote_log_dir="${REMOTE_TEST_DIR}/${TEST_CASE_RESULT_PATH}/${model_name_clean}"
     local local_log_dir="${BASE_DIR}/${TEST_CASE_RESULT_PATH}/${model_name_clean}"
-    
+
     echo "  Copying remote ${remote_log_filename}..."
-    scp ${REMOTE_IP}:${remote_log_dir}/${remote_log_filename} \
-        ${local_log_dir}/ 2>/dev/null
-    
+    ${SCP_CMD:-scp} \
+        "${REMOTE_SSH_TARGET:-$REMOTE_IP}:${remote_log_dir}/${remote_log_filename}" \
+        "${local_log_dir}/" 2>/dev/null
+
     if [ $? -eq 0 ]; then
         echo "  ✓ Successfully copied ${remote_log_filename} for $model_name_clean"
         return 0
@@ -799,14 +1448,14 @@ collect_remote_log_file() {
 validate_json_response_error() {
     local response=$1
     local model_name=${2:-"unknown"}
-    
+
     if echo "$response" | grep -q "\"object\":\"error\""; then
         local error_message=$(echo "$response" | grep -o '"message":"[^"]*"' | sed 's/"message":"//' | sed 's/"$//')
         echo "  ERROR: $error_message" >&2
         echo "  $model_name: Fail"
         return 1
     fi
-    
+
     return 0
 }
 
@@ -814,17 +1463,17 @@ validate_json_response_error() {
 validate_http_status() {
     local status_code=$1
     local expected_code=${2:-200}
-    
+
     if [ -z "$status_code" ]; then
         echo "ERROR: HTTP status code is empty" >&2
         return 1
     fi
-    
+
     if ! [[ "$status_code" =~ ^[0-9]+$ ]]; then
         echo "ERROR: HTTP status code is not a valid number: '$status_code'" >&2
         return 1
     fi
-    
+
     if [ "$status_code" -eq "$expected_code" ]; then
         return 0
     else
@@ -842,13 +1491,13 @@ validate_response_content() {
     if [ -z "$json_query" ]; then
         return 0
     fi
-    
+
     local content=$(echo "$response" | jq -r "$json_query" 2>/dev/null)
     if [ -z "$content" ] || [ "$content" = "null" ]; then
         echo "ERROR: Failed to extract content from JSON with query: $json_query" >&2
         return 1
     fi
-    
+
     if [ -n "$expected_pattern" ]; then
         if [[ "${content,,}" =~ ${expected_pattern,,} ]]; then
             echo "Content validation passed: found '$expected_pattern'"
@@ -860,7 +1509,7 @@ validate_response_content() {
             return 1
         fi
     fi
-    
+
     echo "Content extracted successfully: $content"
     return 0
 }
@@ -870,15 +1519,15 @@ validate_api_response() {
     local status_code=$2
     local json_query=${3:-""}
     local expected_pattern=${4:-""}
-    
+
     if ! validate_http_status "$status_code" 200; then
         return 1
     fi
-    
+
     if ! validate_json_response_error "$response_body"; then
         return 1
     fi
-    
+
     if [ -n "$json_query" ]; then
         if ! validate_response_content "$response_body" "$json_query" "$expected_pattern"; then
             return 1
@@ -886,7 +1535,7 @@ validate_api_response() {
     else
         echo "Basic validation passed"
     fi
-    
+
     return 0
 }
 
@@ -894,24 +1543,24 @@ validate_curl_response_from_log() {
     local log_file=$1
     local model_name=$2
     local expected_pattern=${3:-""}
-    
+
     if [ ! -f "$log_file" ]; then
         echo "  ERROR: Curl response log not found at $log_file" >&2
         echo "  $model_name: Fail"
         return 1
     fi
-    
+
     local curl_response=$(cat "$log_file")
     if [ -z "$curl_response" ]; then
         echo "  ERROR: Curl response log is empty" >&2
         echo "  $model_name: Fail"
         return 1
     fi
-    
+
     if ! validate_json_response_error "$curl_response" "$model_name"; then
         return 1
     fi
-    
+
     if [ -n "$expected_pattern" ]; then
         if echo "$curl_response" | grep -qEi "$expected_pattern"; then
             echo "  $model_name: Pass (pattern matched)"
@@ -923,7 +1572,7 @@ validate_curl_response_from_log() {
     else
         echo "  $model_name: Pass"
     fi
-    
+
     return 0
 }
 
@@ -933,40 +1582,40 @@ collect_and_validate_model_results() {
     local remote_log_filename=$2
     local test_case_name=$3
     local expected_pattern=${4:-""}
-    
+
     local all_passed=true
-    
+
     if [ -z "$REMOTE_IP" ]; then
         echo "ERROR: No REMOTE_IP specified, skipping result parsing" >&2
         return 1
     fi
-    
+
     echo "Getting remote results from remote server..."
-    
+
     for model in "${models[@]}"; do
         local model_name_clean=$(sanitize_model_name "$model")
-        
+
         local remote_log_dir="${REMOTE_TEST_DIR}/${TEST_CASE_RESULT_PATH}/${model_name_clean}"
         local local_log_dir="${BASE_DIR}/${TEST_CASE_RESULT_PATH}/${model_name_clean}"
-        
+
         echo "Processing model: $model_name_clean"
         echo "  Remote log dir: $remote_log_dir"
         echo "  Local log dir: $local_log_dir"
-        
+
         collect_remote_log_file "$model_name_clean" "$remote_log_filename" "$test_case_name"
-        
+
         local log_file="${local_log_dir}/curl_response.log"
         echo "  Checking results for model: $model"
-        
+
         if ! validate_curl_response_from_log "$log_file" "$model" "$expected_pattern"; then
             all_passed=false
         fi
-        
+
         echo ""
     done
-    
+
     echo "Remote log collection completed"
-    
+
     if [ "$all_passed" = true ]; then
         return 0
     else
@@ -974,15 +1623,61 @@ collect_and_validate_model_results() {
     fi
 }
 
-# Echo an offline env prefix when the given model already exists in the
-# container's HuggingFace cache, so servers use the local snapshot instead of
-# querying the hub (skips downloads and avoids hf-mirror 429 rate limiting).
-# Models are pre-cached under MODEL_CACHE (mounted at /root/.cache) on both nodes.
+# Echo an offline env prefix only when a complete set of model weights exists.
+# A config-only or interrupted snapshot must stay online so Hugging Face can
+# resume it instead of failing later with "Cannot find any model weights".
 hf_offline_prefix() {
     local model_name=$1
     [ -z "$model_name" ] && return 0
     local cache_dir="models--$(echo "$model_name" | sed 's#/#--#g')"
-    if ${docker_exec} "ls /root/.cache/huggingface/hub/${cache_dir}/snapshots/*/config.json >/dev/null 2>&1"; then
+    if docker exec -i "${CONTAINER_NAME}" python3 - \
+        "/root/.cache/huggingface/hub/${cache_dir}" <<'PY'
+import glob
+import json
+import os
+import re
+import sys
+
+
+def snapshot_complete(snapshot):
+    if not os.path.isfile(os.path.join(snapshot, "config.json")):
+        return False
+    for index_name in ("model.safetensors.index.json", "pytorch_model.bin.index.json"):
+        index_path = os.path.join(snapshot, index_name)
+        if not os.path.isfile(index_path):
+            continue
+        try:
+            with open(index_path, encoding="utf-8") as index_file:
+                weights = set(json.load(index_file).get("weight_map", {}).values())
+        except (OSError, ValueError):
+            return False
+        return bool(weights) and all(
+            os.path.isfile(os.path.join(snapshot, weight))
+            and os.path.getsize(os.path.join(snapshot, weight)) > 0
+            for weight in weights
+        )
+    return any(
+        os.path.isfile(path) and os.path.getsize(path) > 0
+        for pattern in ("*.safetensors", "pytorch_model*.bin", "*.pt")
+        for path in glob.glob(os.path.join(snapshot, pattern))
+    )
+
+
+repository = sys.argv[1]
+ref_path = os.path.join(repository, "refs", "main")
+try:
+    with open(ref_path, encoding="utf-8") as ref_file:
+        revision = ref_file.read().strip()
+except OSError:
+    sys.exit(1)
+
+if re.fullmatch(r"[0-9a-fA-F]{40,64}", revision) is None:
+    sys.exit(1)
+
+snapshot = os.path.join(repository, "snapshots", revision)
+sys.exit(0 if snapshot_complete(snapshot) else 1)
+PY
+    then
         echo "HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 "
     fi
 }
@@ -995,30 +1690,32 @@ launch_sglang_server() {
     local pid_suffix=$5
     local extra_args=${6:-""}
     local ready_pattern=${7:-"The server is fired up and ready to roll!"}
-    
+
     if [ -z "$model_path" ] || [ -z "$host" ] || [ -z "$port" ] || [ -z "$log_path" ] || [ -z "$pid_suffix" ]; then
         echo "ERROR: Missing required parameters for launch_sglang_server" >&2
         echo "Usage: launch_sglang_server <model_path> <host> <port> <log_path> <pid_suffix> [extra_args] [ready_pattern]" >&2
         return 1
     fi
-    
+
     local offline_prefix=$(hf_offline_prefix "$model_path")
-    local sglang_cmd="${docker_exec} \"${offline_prefix}python -m sglang.launch_server --model-path ${model_path} --host ${host} --port ${port}"
+    local sglang_cmd="${offline_prefix}python -m sglang.launch_server --model-path ${model_path} --host ${host} --port ${port}"
     if [ -n "$extra_args" ]; then
         sglang_cmd="${sglang_cmd} ${extra_args}"
     fi
-    
+    if [ -n "${MOONCAKE_SGLANG_MEM_FRACTION_STATIC:-}" ] && \
+        [[ " $extra_args " != *" --mem-fraction-static "* ]]; then
+        sglang_cmd="${sglang_cmd} --mem-fraction-static ${MOONCAKE_SGLANG_MEM_FRACTION_STATIC}"
+    fi
+
 
-    sglang_cmd="${sglang_cmd} > ${log_path} 2>&1 &\""
-    
     local pid_file="${PID_DIR}/server_${pid_suffix}.pid"
     local grep_pattern="python -m sglang.launch_server.*${model_path}"
-    
+
     echo "Starting SGLang Server..."
-    if ! launch_and_track_process "$sglang_cmd" "$grep_pattern" "$pid_file"; then
+    if ! launch_and_track_process "$sglang_cmd" "$log_path" "$pid_file" "$grep_pattern"; then
         return 1
     fi
-    
+
     local host_log_path=$(convert_container_path_to_host "$log_path")
     if ! check_server_ready_with_pattern "$host_log_path" "$ready_pattern"; then
         return 1
@@ -1030,7 +1727,7 @@ launch_sglang_server() {
         return 1
     fi
     echo "${pid_suffix} health check passed"
-    
+
     return 0
 }
 
@@ -1042,45 +1739,43 @@ launch_vllm_server() {
     local pid_suffix=$5
     local extra_args=${6:-""}
     local env_vars=${7:-""}
-    
+
     if [ -z "$model_path" ] || [ -z "$host" ] || [ -z "$port" ] || [ -z "$log_path" ] || [ -z "$pid_suffix" ]; then
         echo "ERROR: Missing required parameters for launch_vllm_server" >&2
         echo "Usage: launch_vllm_server <model_path> <host> <port> <log_path> <pid_suffix> [extra_args] [env_vars]" >&2
         return 1
     fi
-    
+
     local env_prefix=""
     if [ -n "$env_vars" ]; then
         env_prefix="${env_vars} "
     fi
     env_prefix="${env_prefix}$(hf_offline_prefix "$model_path")"
-    
-    local vllm_cmd="${docker_exec} \"${env_prefix}python3 -m vllm.entrypoints.openai.api_server --model '${model_path}' --host '${host}' --port ${port}"
-    
+
+    local vllm_cmd="${env_prefix}python3 -m vllm.entrypoints.openai.api_server --model '${model_path}' --host '${host}' --port ${port}"
+
     if [ -n "$extra_args" ]; then
         vllm_cmd="${vllm_cmd} ${extra_args}"
     fi
-    
-    vllm_cmd="${vllm_cmd} > '${log_path}' 2>&1 &\""
-    
+
     local pid_file="${PID_DIR}/server_${pid_suffix}.pid"
     local grep_pattern="python3 -m vllm.entrypoints.openai.api_server.*${model_path}"
-    
+
     echo "Starting vLLM Server..."
     echo "Command: $vllm_cmd"
-    if ! launch_and_track_process "$vllm_cmd" "$grep_pattern" "$pid_file"; then
+    if ! launch_and_track_process "$vllm_cmd" "$log_path" "$pid_file" "$grep_pattern"; then
         return 1
     fi
-    
+
     local host_log_path=$(convert_container_path_to_host "$log_path")
     if ! check_vllm_server_ready "$host_log_path"; then
         return 1
     fi
-    
+
     if ! wait_for_server_ready "$host" "$port" "/health"; then
         return 1
     fi
-    
+
     return 0
 }
 
@@ -1091,35 +1786,33 @@ launch_sglang_router() {
     local port=$4
     local log_path=$5
     local extra_args=${6:-""}
-    
+
     if [ -z "$prefill_url" ] || [ -z "$decode_url" ] || [ -z "$host" ] || [ -z "$port" ] || [ -z "$log_path" ]; then
         echo "ERROR: Missing required parameters for launch_sglang_router" >&2
         echo "Usage: launch_sglang_router <prefill_url> <decode_url> <host> <port> <log_path> [extra_args]" >&2
         return 1
     fi
-    
+
     echo "===== Starting SGLang Router ====="
-    
-    local router_cmd="${docker_exec} \"python3 -m sglang_router.launch_router --pd-disaggregation --prefill ${prefill_url} --decode ${decode_url} --host ${host} --port ${port}"
+
+    local router_cmd="python3 -m sglang_router.launch_router --pd-disaggregation --prefill ${prefill_url} --decode ${decode_url} --host ${host} --port ${port}"
     if [ -n "$extra_args" ]; then
         router_cmd="${router_cmd} ${extra_args}"
     fi
-    
-    router_cmd="${router_cmd} > ${log_path} 2>&1 &\""
-    
+
     local pid_file="${PID_DIR}/proxy.pid"
     local grep_pattern="sglang::router"
-    
+
     echo "Load balancer starting..."
     echo "Command: $router_cmd"
-    if ! launch_and_track_process "$router_cmd" "$grep_pattern" "$pid_file"; then
+    if ! launch_and_track_process "$router_cmd" "$log_path" "$pid_file" "$grep_pattern"; then
         return 1
     fi
-    
+
     local host_log_path=$(convert_container_path_to_host "$log_path")
     if ! check_proxy_ready "$host_log_path"; then
         return 1
     fi
-    
+
     return 0
-}
\ No newline at end of file
+}
diff --git a/scripts/tone_tests/scripts/run_test.sh b/scripts/tone_tests/scripts/run_test.sh
index 30ff521bbe..1a7553f867 100755
--- a/scripts/tone_tests/scripts/run_test.sh
+++ b/scripts/tone_tests/scripts/run_test.sh
@@ -2,30 +2,106 @@
 
 CONTAINER_NAME=${CONTAINER_NAME:-"mooncake-ci-test"}
 MODEL_CACHE=${MODEL_CACHE:-"/root/.cache"}
-REGISTRY_ADDR_SGLANG=${REGISTRY_ADDR_SGLANG:-"lmsysorg/sglang:latest"}
-REGISTRY_ADDR_VLLM=${REGISTRY_ADDR_VLLM:-"vllm/vllm-openai:latest"}
-USE_HUGGINGFACE_MIRROR=${USE_HUGGINGFACE_MIRROR:-true}
+MOONCAKE_RUNTIME_CACHE=${MOONCAKE_RUNTIME_CACHE:-}
+HF_TOKEN_FILE=${HF_TOKEN_FILE:-"/etc/mooncake-ci/huggingface.token"}
+CI_ACCELERATOR=${CI_ACCELERATOR:-"cuda"}
+if [ "$CI_ACCELERATOR" = "rocm" ]; then
+    : "${REGISTRY_ADDR_SGLANG:?REGISTRY_ADDR_SGLANG is required for ROCm}"
+    : "${REGISTRY_ADDR_VLLM:?REGISTRY_ADDR_VLLM is required for ROCm}"
+    : "${MOONCAKE_CI_TIER:?MOONCAKE_CI_TIER is required for ROCm}"
+    : "${MOONCAKE_RENDER_DEVICES:?MOONCAKE_RENDER_DEVICES is required for ROCm}"
+    : "${MOONCAKE_GPU_INDICES:?MOONCAKE_GPU_INDICES is required for ROCm}"
+    : "${MOONCAKE_CPUSET_CPUS:?MOONCAKE_CPUSET_CPUS is required for ROCm}"
+    : "${MOONCAKE_CPUSET_MEMS:?MOONCAKE_CPUSET_MEMS is required for ROCm}"
+    : "${MOONCAKE_RDMA_DEVICES:?MOONCAKE_RDMA_DEVICES is required for ROCm}"
+    : "${MOONCAKE_RDMA_NETDEVS:?MOONCAKE_RDMA_NETDEVS is required for ROCm}"
+    : "${MOONCAKE_TRANSFER_DEVICE:?MOONCAKE_TRANSFER_DEVICE is required for ROCm}"
+    : "${MOONCAKE_GID_INDEX:?MOONCAKE_GID_INDEX is required for ROCm}"
+    : "${MOONCAKE_SGLANG_BASE_GPU_ID:?MOONCAKE_SGLANG_BASE_GPU_ID is required for ROCm}"
+    : "${MOONCAKE_EPD_ENCODER_GPU_ID:?MOONCAKE_EPD_ENCODER_GPU_ID is required for ROCm}"
+    : "${MOONCAKE_EPD_PREFILL_GPU_ID:?MOONCAKE_EPD_PREFILL_GPU_ID is required for ROCm}"
+    : "${MOONCAKE_EPD_DECODE_GPU_ID:?MOONCAKE_EPD_DECODE_GPU_ID is required for ROCm}"
+    : "${MOONCAKE_VLLM_VISIBLE_DEVICES:?MOONCAKE_VLLM_VISIBLE_DEVICES is required for ROCm}"
+    : "${MOONCAKE_SGLANG_MEM_FRACTION_STATIC:?MOONCAKE_SGLANG_MEM_FRACTION_STATIC is required for ROCm}"
+    : "${MOONCAKE_RUNTIME_CACHE:?MOONCAKE_RUNTIME_CACHE is required for ROCm}"
+    : "${AINIC_VERSION:?AINIC_VERSION is required for ROCm}"
+    USE_HUGGINGFACE_MIRROR=${USE_HUGGINGFACE_MIRROR:-false}
+else
+    REGISTRY_ADDR_SGLANG=${REGISTRY_ADDR_SGLANG:-"lmsysorg/sglang:latest"}
+    REGISTRY_ADDR_VLLM=${REGISTRY_ADDR_VLLM:-"vllm/vllm-openai:latest"}
+    MOONCAKE_SGLANG_BASE_GPU_ID=${MOONCAKE_SGLANG_BASE_GPU_ID:-6}
+    MOONCAKE_EPD_ENCODER_GPU_ID=${MOONCAKE_EPD_ENCODER_GPU_ID:-0}
+    MOONCAKE_EPD_PREFILL_GPU_ID=${MOONCAKE_EPD_PREFILL_GPU_ID:-4}
+    MOONCAKE_EPD_DECODE_GPU_ID=${MOONCAKE_EPD_DECODE_GPU_ID:-6}
+    MOONCAKE_VLLM_VISIBLE_DEVICES=${MOONCAKE_VLLM_VISIBLE_DEVICES:-6,7}
+    MOONCAKE_SGLANG_MEM_FRACTION_STATIC=${MOONCAKE_SGLANG_MEM_FRACTION_STATIC:-}
+    MOONCAKE_CI_TIER=${MOONCAKE_CI_TIER:-"full"}
+    MOONCAKE_RDMA_DEVICES=${MOONCAKE_RDMA_DEVICES:-}
+    MOONCAKE_RDMA_NETDEVS=${MOONCAKE_RDMA_NETDEVS:-}
+    MOONCAKE_TRANSFER_DEVICE=${MOONCAKE_TRANSFER_DEVICE:-}
+    MOONCAKE_GID_INDEX=${MOONCAKE_GID_INDEX:-}
+    USE_HUGGINGFACE_MIRROR=${USE_HUGGINGFACE_MIRROR:-true}
+fi
+MOONCAKE_RENDER_DEVICES=${MOONCAKE_RENDER_DEVICES:-}
+MOONCAKE_GPU_INDICES=${MOONCAKE_GPU_INDICES:-}
+MOONCAKE_CPUSET_CPUS=${MOONCAKE_CPUSET_CPUS:-}
+MOONCAKE_CPUSET_MEMS=${MOONCAKE_CPUSET_MEMS:-}
+AINIC_VERSION=${AINIC_VERSION:-}
 HUGGINGFACE_MIRROR=${HUGGINGFACE_MIRROR:-"https://hf-mirror.com"}
 USE_MODELSCOPE=${USE_MODELSCOPE:-false}
 REMOTE_TEST_DIR=${REMOTE_TEST_DIR:-"/tmp/Mooncake_tone/mooncake_ci_test"}
 LOCAL_IP=${LOCAL_IP}
 REMOTE_IP=${REMOTE_IP}
-ARTIFACT_ID=${ARTIFACT_ID}
-GIT_REPO=${GIT_REPO}
-
-All_TEST_SCRIPTS_SGLANG=(
-    "test_hicache_storage_mooncake_backend.sh"
-    "test_disaggregation_different_tp.sh"
-    "test_1p1d_erdma.sh"
-    "test_epd_sglang.sh"
-    "test_moe_mooncake.sh"
-)
+ARTIFACT_ID=${ARTIFACT_ID:-}
+ARTIFACT_ID_SGLANG=${ARTIFACT_ID_SGLANG:-$ARTIFACT_ID}
+ARTIFACT_ID_VLLM=${ARTIFACT_ID_VLLM:-$ARTIFACT_ID}
+WHEEL_DIR=${WHEEL_DIR:-}
+WHEEL_DIR_SGLANG=${WHEEL_DIR_SGLANG:-$WHEEL_DIR}
+WHEEL_DIR_VLLM=${WHEEL_DIR_VLLM:-$WHEEL_DIR}
+GIT_REPO=${GIT_REPO:-}
+MOONCAKE_ENV_UNHEALTHY=false
+
+if [ "$MOONCAKE_CI_TIER" = "core-4gpu" ]; then
+    # The upstream heterogeneous-TP test starts TP4 and TP2 workers on the
+    # same host and therefore needs eight GPUs. Mooncake Elastic EP is also
+    # CUDA-only, so neither test belongs in the permanent 4+4 ROCm tier.
+    All_TEST_SCRIPTS_SGLANG=(
+        "test_hicache_storage_mooncake_backend.sh"
+        "test_1p1d_erdma.sh"
+        "test_epd_sglang.sh"
+    )
+elif [ "$MOONCAKE_CI_TIER" = "full" ]; then
+    All_TEST_SCRIPTS_SGLANG=(
+        "test_hicache_storage_mooncake_backend.sh"
+        "test_disaggregation_different_tp.sh"
+        "test_1p1d_erdma.sh"
+        "test_epd_sglang.sh"
+        "test_moe_mooncake.sh"
+    )
+else
+    echo "ERROR: unsupported MOONCAKE_CI_TIER: $MOONCAKE_CI_TIER" >&2
+    exit 2
+fi
 
 All_TEST_SCRIPTS_VLLM=(
     "test_vllm_1p1d_erdma.sh"
 )
 
-readonly SSH_CMD="ssh -o StrictHostKeyChecking=no"
+if [ "$CI_ACCELERATOR" = "rocm" ]; then
+    # The ROCm cluster uses a dedicated CI identity and pinned host key. Keep
+    # the serving/RDMA address separate from the SSH management endpoint.
+    : "${REMOTE_SSH_TARGET:?REMOTE_SSH_TARGET is required for ROCm}"
+    : "${MOONCAKE_SSH_CONFIG:?MOONCAKE_SSH_CONFIG is required for ROCm}"
+    SSH_CMD=${SSH_CMD:-"ssh -F ${MOONCAKE_SSH_CONFIG}"}
+    RSYNC_RSH=${RSYNC_RSH:-"ssh -F ${MOONCAKE_SSH_CONFIG}"}
+    SCP_CMD=${SCP_CMD:-"scp -F ${MOONCAKE_SSH_CONFIG}"}
+else
+    REMOTE_SSH_TARGET=${REMOTE_SSH_TARGET:-"$REMOTE_IP"}
+    SSH_CMD=${SSH_CMD:-"ssh -o StrictHostKeyChecking=no"}
+    RSYNC_RSH=${RSYNC_RSH:-"ssh -o StrictHostKeyChecking=no"}
+    SCP_CMD=${SCP_CMD:-"scp -o StrictHostKeyChecking=no"}
+fi
+readonly REMOTE_SSH_TARGET SSH_CMD RSYNC_RSH SCP_CMD
 
 TONE_TESTS_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)
 RUN_DIR="$TONE_TESTS_DIR/run"
@@ -34,26 +110,26 @@ RUN_DIR="$TONE_TESTS_DIR/run"
 
 get_test_type() {
     local test_name=$1
-    
+
     if [ ! -f "$TONE_TESTS_DIR/scripts/$test_name" ]; then
         echo "unknown"
         return 1
     fi
-    
+
     local test_type=$(grep "^TEST_TYPE=" "$TONE_TESTS_DIR/scripts/$test_name" | head -n 1 | cut -d'"' -f2)
-    
+
     if [ -z "$test_type" ]; then
         echo "unknown"
         return 1
     fi
-    
+
     echo "$test_type"
     return 0
 }
 
 get_framework_from_test_array() {
     local test_array_name=$1
-    
+
     case $test_array_name in
         "All_TEST_SCRIPTS_SGLANG")
             echo "SGLANG"
@@ -69,14 +145,14 @@ get_framework_from_test_array() {
 
 get_framework_from_test_name() {
     local test_name=$1
-    
+
     for vllm_test in "${All_TEST_SCRIPTS_VLLM[@]}"; do
         if [ "$test_name" = "$vllm_test" ]; then
             echo "VLLM"
             return 0
         fi
     done
-    
+
     # default SGLANG
     echo "SGLANG"
 }
@@ -101,11 +177,15 @@ is_base_env_prepared() {
         return 1  # config file doesn't exist
     fi
 
-    # Check if ARTIFACT_ID matches current environment
+    # Check if the wheel source matches the current environment.
     local current_artifact_id=$(grep "^export ARTIFACT_ID=" "$RUN_DIR/.shrc" | cut -d'=' -f2-)
+    local current_wheel_dir=$(grep "^export WHEEL_DIR=" "$RUN_DIR/.shrc" | cut -d'=' -f2-)
     if [ "$current_artifact_id" != "$ARTIFACT_ID" ]; then
         return 1  # ARTIFACT_ID mismatch
     fi
+    if [ "$current_wheel_dir" != "$WHEEL_DIR" ]; then
+        return 1  # self-hosted artifact path mismatch
+    fi
 
     # Check if whl package exists
     local whl_count=$(find "$RUN_DIR/whls/" -name "*.whl" -type f 2>/dev/null | wc -l)
@@ -113,7 +193,7 @@ is_base_env_prepared() {
 }
 
 prepare_single_env(){
-    local registry_addr=$1 
+    local registry_addr=$1
     local framework_type=$2
 
     if is_base_env_prepared; then
@@ -122,20 +202,25 @@ prepare_single_env(){
     fi
 
     echo "===== Preparing environment for $framework_type (registry: $registry_addr) ====="
-    
+
     setup_directory $RUN_DIR
     setup_directory $RUN_DIR/logs
 
     cat > $RUN_DIR/.shrc << EOF
 # Mooncake CI Test Environment Variables - Main Controller
 export CONTAINER_NAME=${CONTAINER_NAME}
+export CI_ACCELERATOR=${CI_ACCELERATOR}
+export MOONCAKE_CI_TIER=${MOONCAKE_CI_TIER}
 export MODEL_CACHE=${MODEL_CACHE}
+export MOONCAKE_RUNTIME_CACHE=${MOONCAKE_RUNTIME_CACHE}
+export HF_TOKEN_FILE=${HF_TOKEN_FILE}
 export REGISTRY_ADDR_SGLANG=${REGISTRY_ADDR_SGLANG}
 export REGISTRY_ADDR_VLLM=${REGISTRY_ADDR_VLLM}
 export USE_HUGGINGFACE_MIRROR=${USE_HUGGINGFACE_MIRROR}
 export HUGGINGFACE_MIRROR=${HUGGINGFACE_MIRROR}
 export USE_MODELSCOPE=${USE_MODELSCOPE}
 export ARTIFACT_ID=${ARTIFACT_ID}
+export WHEEL_DIR=${WHEEL_DIR}
 export GIT_REPO=${GIT_REPO}
 export LOCAL_IP=${LOCAL_IP}
 export REMOTE_IP=${REMOTE_IP}
@@ -143,6 +228,21 @@ export BASE_DIR=${TONE_TESTS_DIR}
 export TEST_RUN_DIR=${RUN_DIR}
 export TEST_RESULT_DIR=${RUN_DIR}/logs
 export REMOTE_TEST_DIR=${REMOTE_TEST_DIR}
+export MOONCAKE_RENDER_DEVICES="${MOONCAKE_RENDER_DEVICES}"
+export MOONCAKE_GPU_INDICES=${MOONCAKE_GPU_INDICES}
+export MOONCAKE_CPUSET_CPUS=${MOONCAKE_CPUSET_CPUS}
+export MOONCAKE_CPUSET_MEMS=${MOONCAKE_CPUSET_MEMS}
+export MOONCAKE_SGLANG_BASE_GPU_ID=${MOONCAKE_SGLANG_BASE_GPU_ID}
+export MOONCAKE_EPD_ENCODER_GPU_ID=${MOONCAKE_EPD_ENCODER_GPU_ID}
+export MOONCAKE_EPD_PREFILL_GPU_ID=${MOONCAKE_EPD_PREFILL_GPU_ID}
+export MOONCAKE_EPD_DECODE_GPU_ID=${MOONCAKE_EPD_DECODE_GPU_ID}
+export MOONCAKE_VLLM_VISIBLE_DEVICES=${MOONCAKE_VLLM_VISIBLE_DEVICES}
+export MOONCAKE_SGLANG_MEM_FRACTION_STATIC=${MOONCAKE_SGLANG_MEM_FRACTION_STATIC}
+export MOONCAKE_RDMA_DEVICES=${MOONCAKE_RDMA_DEVICES}
+export MOONCAKE_RDMA_NETDEVS=${MOONCAKE_RDMA_NETDEVS}
+export MOONCAKE_TRANSFER_DEVICE=${MOONCAKE_TRANSFER_DEVICE}
+export MOONCAKE_GID_INDEX=${MOONCAKE_GID_INDEX}
+export AINIC_VERSION=${AINIC_VERSION}
 EOF
 
     echo "===== Preparing local machine ====="
@@ -157,12 +257,43 @@ EOF
     return 0
 }
 
+validated_remote_test_dir() {
+    local remote_dir=$1
+    local allowed_root
+    if [ "$CI_ACCELERATOR" = "rocm" ]; then
+        allowed_root=/var/lib/mooncake-ci/work
+    else
+        allowed_root=/tmp/Mooncake_tone/mooncake_ci_test
+    fi
+
+    if ! [[ "$remote_dir" =~ ^/[A-Za-z0-9._/-]+$ ]]; then
+        echo "ERROR: REMOTE_TEST_DIR contains unsupported characters: $remote_dir" >&2
+        return 1
+    fi
+
+    local normalized_root normalized_dir
+    normalized_root=$(realpath -m -- "$allowed_root") || return 1
+    normalized_dir=$(realpath -m -- "$remote_dir") || return 1
+    case "$normalized_dir" in
+        "$normalized_root"|"$normalized_root"/*)
+            printf '%s\n' "$normalized_dir"
+            ;;
+        *)
+            echo "ERROR: REMOTE_TEST_DIR must remain under $normalized_root: $normalized_dir" >&2
+            return 1
+            ;;
+    esac
+}
+
 prepare_double_env(){
     local registry_addr=$1
     local framework_type=$2
 
     echo "===== Preparing Double-Machine Environment (local + remote) ====="
 
+    REMOTE_TEST_DIR=$(validated_remote_test_dir "$REMOTE_TEST_DIR") || return 1
+    export REMOTE_TEST_DIR
+
     if ! prepare_single_env "$registry_addr" "$framework_type"; then
         echo "ERROR: prepare_single_env failed"
         return 1
@@ -174,18 +305,26 @@ prepare_double_env(){
     fi
 
     echo "Preparing remote machine $REMOTE_IP..."
-    ${SSH_CMD} $REMOTE_IP "rm -rf ${REMOTE_TEST_DIR} && mkdir -p ${REMOTE_TEST_DIR}"
-    
-    rsync -av ${TONE_TESTS_DIR}/ $REMOTE_IP:${REMOTE_TEST_DIR}/
-    if [ $? -ne 0 ]; then
-        echo "Failed to sync files to remote server"
+    if ! ${SSH_CMD} "$REMOTE_SSH_TARGET" \
+        "set -eu; remote_test_dir='${REMOTE_TEST_DIR}'; rm -rf -- \"\$remote_test_dir\"; mkdir -p -- \"\$remote_test_dir\""; then
+        echo "ERROR: Failed to prepare remote test directory on $REMOTE_IP" >&2
+        return 1
+    fi
+
+    if ! rsync -av -e "$RSYNC_RSH" "${TONE_TESTS_DIR}/" \
+        "$REMOTE_SSH_TARGET:${REMOTE_TEST_DIR}/"; then
+        echo "ERROR: Failed to sync files to remote server" >&2
         return 1
     fi
-    
-    ${SSH_CMD} $REMOTE_IP "sed -i 's|^export BASE_DIR=.*$|export BASE_DIR=${REMOTE_TEST_DIR}|' ${REMOTE_TEST_DIR}/run/.shrc && \
-                            sed -i 's|^export TEST_RUN_DIR=.*$|export TEST_RUN_DIR=${REMOTE_TEST_DIR}/run|' ${REMOTE_TEST_DIR}/run/.shrc && \
-                            sed -i 's|^export TEST_RESULT_DIR=.*$|export TEST_RESULT_DIR=${REMOTE_TEST_DIR}/logs|' ${REMOTE_TEST_DIR}/run/.shrc"
-    
+
+    if ! ${SSH_CMD} "$REMOTE_SSH_TARGET" \
+        "sed -i 's|^export BASE_DIR=.*$|export BASE_DIR=${REMOTE_TEST_DIR}|' ${REMOTE_TEST_DIR}/run/.shrc && \
+         sed -i 's|^export TEST_RUN_DIR=.*$|export TEST_RUN_DIR=${REMOTE_TEST_DIR}/run|' ${REMOTE_TEST_DIR}/run/.shrc && \
+         sed -i 's|^export TEST_RESULT_DIR=.*$|export TEST_RESULT_DIR=${REMOTE_TEST_DIR}/logs|' ${REMOTE_TEST_DIR}/run/.shrc"; then
+        echo "ERROR: Failed to configure the remote test environment on $REMOTE_IP" >&2
+        return 1
+    fi
+
     echo "Remote preparation completed successfully"
 
     return 0
@@ -198,6 +337,22 @@ setup_env_for_test() {
     [ "$target" = "all" ] && type="double"
 
     local registry_addr=$(get_registry_addr_for_framework "$framework_type")
+    case "$framework_type" in
+        SGLANG)
+            ARTIFACT_ID=$ARTIFACT_ID_SGLANG
+            WHEEL_DIR=$WHEEL_DIR_SGLANG
+            ;;
+        VLLM)
+            ARTIFACT_ID=$ARTIFACT_ID_VLLM
+            WHEEL_DIR=$WHEEL_DIR_VLLM
+            ;;
+        *) echo "ERROR: unknown framework type: $framework_type" >&2; return 1 ;;
+    esac
+    [ -n "$ARTIFACT_ID" ] || [ -n "$WHEEL_DIR" ] || {
+        echo "ERROR: no wheel source configured for $framework_type" >&2
+        return 1
+    }
+    export ARTIFACT_ID WHEEL_DIR
 
     if [ "$type" = "double" ]; then
         prepare_double_env "$registry_addr" "$framework_type" || return 1
@@ -209,13 +364,13 @@ setup_env_for_test() {
 
     if [ "$type" = "double" ]; then
         echo "Initializing remote node $REMOTE_IP..."
-        ${SSH_CMD} "$REMOTE_IP" "
+        ${SSH_CMD} "$REMOTE_SSH_TARGET" "
             source ${REMOTE_TEST_DIR}/run/.shrc && \
             source ${REMOTE_TEST_DIR}/scripts/common.sh && \
             setup_node_env '${registry_addr}'
         " || { echo "ERROR: Remote setup failed"; return 1; }
     fi
-    
+
     echo "All environments are ready."
 }
 
@@ -226,9 +381,14 @@ run_single_test(){
 
     local framework_type=$(get_framework_from_test_name "$test_name")
     echo "Test $test_name will use framework: $framework_type"
-    
-    setup_env_for_test "$test_name" "$framework_type" || return 1
-    
+
+    local type
+    type=$(get_test_type "$test_name") || return 1
+    if ! setup_env_for_test "$test_name" "$framework_type"; then
+        cleanup_test_env "$type" || true
+        return 1
+    fi
+
     source "$RUN_DIR/.shrc"
     cd "$TONE_TESTS_DIR/scripts"
     source "./$test_name"
@@ -238,19 +398,21 @@ run_single_test(){
 
     local exit_code=0
     run_test "$@" || exit_code=1
-    
+
     if declare -f parse >/dev/null 2>&1; then
         parse "$exit_code" || exit_code=1
     fi
 
-    local type=$(get_test_type "$test_name")
-    cleanup_test_env "$type"
+    if ! cleanup_test_env "$type"; then
+        echo "ERROR: Test cleanup/postflight failed" >&2
+        exit_code=1
+    fi
     return $exit_code
 }
 
 run_all_tests(){
     local input_tests=$1
-    if ! [[ -v "$input_tests" ]]; then
+    if ! declare -p "$input_tests" >/dev/null 2>&1; then
         echo "ERROR: Variable '$input_tests' does not exist"
         return 1
     fi
@@ -259,12 +421,16 @@ run_all_tests(){
 
     local framework_type=$(get_framework_from_test_array "$input_tests")
     echo "===== Running All Tests for $framework_type Framework (Double Machine Mode) ====="
-    
-    setup_env_for_test "all" "$framework_type" || return 1
-    
+
+    if ! setup_env_for_test "all" "$framework_type"; then
+        MOONCAKE_ENV_UNHEALTHY=true
+        cleanup_test_env "double" || true
+        return 1
+    fi
+
     source "$RUN_DIR/.shrc"
     cd "$TONE_TESTS_DIR/scripts"
-    
+
     local all_passed=true
     local test_index=0
     local test_count=${#tests[@]}
@@ -282,11 +448,11 @@ run_all_tests(){
         source "./$test_name"
         local exit_code=0
         run_test || exit_code=1
-        
+
         if declare -f parse >/dev/null 2>&1; then
             parse "$exit_code" || exit_code=1
         fi
-        
+
         [ $exit_code -ne 0 ] && all_passed=false
 
         # Container is shared across cases in run-all. Do not schedule another
@@ -296,11 +462,16 @@ run_all_tests(){
             echo "ERROR: Shared test environment is unhealthy after ${test_name}." >&2
             echo "ERROR: Skipping ${remaining_count} remaining test case(s); node intervention is required." >&2
             all_passed=false
+            MOONCAKE_ENV_UNHEALTHY=true
             break
         fi
     done
-    
-    cleanup_test_env "double"
+
+    if ! cleanup_test_env "double"; then
+        echo "ERROR: Test cleanup/postflight failed" >&2
+        all_passed=false
+        MOONCAKE_ENV_UNHEALTHY=true
+    fi
     $all_passed && return 0 || return 1
 }
 
@@ -316,34 +487,46 @@ show_help(){
     echo "  run-all VLLM                       - Run all VLLM tests (using VLLM image)"
 }
 
-case "$1" in
-    "run-single")
-        shift
-        run_single_test "$@"
-        ;;
- "run-all")
-    shift
-    if [ -z "$1" ]; then
-        # No parameter specified, run both SGLANG and VLLM tests
-        echo "No framework specified, running all SGLANG tests..."
-        run_all_tests "All_TEST_SCRIPTS_SGLANG"
-        
-        echo "Running all VLLM tests..."
-        run_all_tests "All_TEST_SCRIPTS_VLLM"
-    else
-        FRAMEWORK=$1
-        if [ "$FRAMEWORK" = "VLLM" ]; then
-            run_all_tests "All_TEST_SCRIPTS_VLLM"
-        elif [ "$FRAMEWORK" = "SGLANG" ]; then
-            run_all_tests "All_TEST_SCRIPTS_SGLANG"
-        else
-            echo "ERROR: Unknown framework '$FRAMEWORK'. Use SGLANG or VLLM."
+main() {
+    case "${1:-}" in
+        "run-single")
+            shift
+            run_single_test "$@"
+            ;;
+        "run-all")
+            shift
+            if [ -z "${1:-}" ]; then
+                # No parameter specified, run both SGLANG and VLLM tests
+                all_frameworks_passed=true
+                echo "No framework specified, running all SGLANG tests..."
+                run_all_tests "All_TEST_SCRIPTS_SGLANG" || all_frameworks_passed=false
+
+                if $MOONCAKE_ENV_UNHEALTHY; then
+                    echo "ERROR: Skipping VLLM because the shared environment is unhealthy" >&2
+                else
+                    echo "Running all VLLM tests..."
+                    run_all_tests "All_TEST_SCRIPTS_VLLM" || all_frameworks_passed=false
+                fi
+                $all_frameworks_passed
+            else
+                FRAMEWORK=$1
+                if [ "$FRAMEWORK" = "VLLM" ]; then
+                    run_all_tests "All_TEST_SCRIPTS_VLLM"
+                elif [ "$FRAMEWORK" = "SGLANG" ]; then
+                    run_all_tests "All_TEST_SCRIPTS_SGLANG"
+                else
+                    echo "ERROR: Unknown framework '$FRAMEWORK'. Use SGLANG or VLLM."
+                    show_help
+                    return 1
+                fi
+            fi
+            ;;
+        *)
             show_help
-            return 1
-        fi
-    fi
-    ;;
-    *)
-        show_help
-        ;;
-esac
+            ;;
+    esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+    main "$@"
+fi
diff --git a/scripts/tone_tests/scripts/test_1p1d_erdma.sh b/scripts/tone_tests/scripts/test_1p1d_erdma.sh
index 4fb6c2b47f..c565a1dc68 100755
--- a/scripts/tone_tests/scripts/test_1p1d_erdma.sh
+++ b/scripts/tone_tests/scripts/test_1p1d_erdma.sh
@@ -12,13 +12,13 @@ detect_remote_mode
 mkdir -p "$PID_DIR"
 
 start_server()
-{   
+{
     local host
     local model_name=$1
     local model_name_clean=$2
     local sglang_server_log_path
     local mode_name
-    if [ "$ISREMOTE" == "0" ]; then 
+    if [ "$ISREMOTE" == "0" ]; then
         host=$LOCAL_IP
         sglang_server_log_path=/test_run/run/logs/$test_case_name/$model_name_clean/sglang_server_local.log
         mode_name=prefill
@@ -28,7 +28,10 @@ start_server()
         mode_name=decode
     fi
 
-    local extra_args="--disaggregation-mode $mode_name --tp-size 2 --base-gpu-id=6"
+    local extra_args="--disaggregation-mode $mode_name --tp-size 2 --base-gpu-id=${MOONCAKE_SGLANG_BASE_GPU_ID:-6}"
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        extra_args="${extra_args} --disaggregation-ib-device=${MOONCAKE_TRANSFER_DEVICE:-ionic_0}"
+    fi
     if ! launch_sglang_server "$model_name" "$host" "30001" "$sglang_server_log_path" "$mode_name" "$extra_args"; then
         return 1
     fi
@@ -44,7 +47,7 @@ run_proxy(){
         echo "ERROR: Failed to start SGLang Router"
         return 1
     fi
-    
+
     return 0
 }
 
@@ -84,16 +87,16 @@ run_single_model()
     local model_name_clean=$(sanitize_model_name "$model_name")
     local status=0
 
-    setup_log_directory_dual "$test_case_name" "$model_name_clean"   
+    setup_log_directory_dual "$test_case_name" "$model_name_clean"
 
-    echo "===== Run MODEL NAME: $model_name ====="    
+    echo "===== Run MODEL NAME: $model_name ====="
     # Local start server
     if ! start_server $model_name $model_name_clean; then
         echo "ERROR: Failed to start local server for model $model_name"
         status=1
     else
         # Remote start server
-        if ! ${SSH_CMD} $REMOTE_IP "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_server $model_name $model_name_clean"; then
+        if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_server $model_name $model_name_clean"; then
             echo "ERROR: Failed to start remote server for model $model_name"
             status=1
         else
@@ -113,8 +116,10 @@ run_single_model()
     fi
 
     echo "===== Cleaning up model processes for $model_name ====="
-    kill_model_processes
-    sleep 2
+    if ! kill_model_processes; then
+        echo "ERROR: Model process cleanup failed for $model_name" >&2
+        status=1
+    fi
 
     return $status
 }
@@ -127,25 +132,36 @@ run_test()
     fi
     echo "===== Running test case: $test_case_name for all supported models ====="
 
+    if [ "$#" -gt 0 ]; then
+        SUPPORT_MODELS=("$@")
+    fi
+
     local test_failed=false
+    local model_index=0
+    local model_count=${#SUPPORT_MODELS[@]}
     for model in "${SUPPORT_MODELS[@]}"; do
+        model_index=$((model_index + 1))
         if ! run_single_model "$model"; then
             echo "ERROR: Test case $test_case_name failed for model $model"
             test_failed=true
         fi
+        if [ "$model_index" -lt "$model_count" ] && ! drain_gpu_between_tests; then
+            echo "ERROR: Failed to isolate the next model from $model" >&2
+            return 1
+        fi
     done
 
     if [ "$test_failed" = true ]; then
         return 1
     fi
-    
+
     return 0
 }
 
 parse()
 {
     echo "===== Parsing test results ====="
-    
+
     if collect_and_validate_model_results "SUPPORT_MODELS" "sglang_server_remote.log" "$test_case_name"; then
         save_test_result "$test_case_name" "Pass" "${BASE_DIR}/${TEST_CASE_RESULT_PATH}"
         echo "✓ Test PASSED"
@@ -165,7 +181,7 @@ case "$1" in
         ;;
     "stop_server")
         kill_model_processes
-        exit 0
+        exit $?
         ;;
     *)
         if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
diff --git a/scripts/tone_tests/scripts/test_epd_sglang.sh b/scripts/tone_tests/scripts/test_epd_sglang.sh
index f345048479..fffbb62caf 100755
--- a/scripts/tone_tests/scripts/test_epd_sglang.sh
+++ b/scripts/tone_tests/scripts/test_epd_sglang.sh
@@ -17,21 +17,23 @@ start_epd_component()
     local component_type=$1  # encoder，prefill, decode
     local model_name=$2
     local model_name_clean=$3
-    
+
     local host
     local port
     local log_path
     local pid_suffix
     local extra_args
     local ready_pattern
-    
     case $component_type in
         "encoder")
             host=$LOCAL_IP
             port=30000
             log_path="/test_run/run/logs/$test_case_name/$model_name_clean/encoder.log"
             pid_suffix="encoder"
-            extra_args="--encoder-only --encoder-transfer-backend mooncake --tp-size 2"
+            extra_args="--encoder-only --encoder-transfer-backend mooncake --tp-size 2 --base-gpu-id=${MOONCAKE_EPD_ENCODER_GPU_ID:-0}"
+            if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+                extra_args="${extra_args} --mooncake-ib-device=${MOONCAKE_TRANSFER_DEVICE}"
+            fi
             ready_pattern="Application startup complete."
             echo "Starting Encoder..."
             ;;
@@ -40,7 +42,10 @@ start_epd_component()
             port=30002
             log_path="/test_run/run/logs/$test_case_name/$model_name_clean/sglang_server_prefill.log"
             pid_suffix="prefill"
-            extra_args="--disaggregation-mode prefill --language-only --encoder-urls http://${LOCAL_IP}:30000 --tp-size 2 --encoder-transfer-backend mooncake --base-gpu-id=4"
+            extra_args="--disaggregation-mode prefill --language-only --encoder-urls http://${LOCAL_IP}:30000 --tp-size 2 --encoder-transfer-backend mooncake --base-gpu-id=${MOONCAKE_EPD_PREFILL_GPU_ID:-4}"
+            if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+                extra_args="${extra_args} --disaggregation-ib-device=${MOONCAKE_TRANSFER_DEVICE} --mooncake-ib-device=${MOONCAKE_TRANSFER_DEVICE}"
+            fi
             ready_pattern="The server is fired up and ready to roll!"
             echo "Starting Prefill Server..."
             ;;
@@ -49,7 +54,10 @@ start_epd_component()
             port=30003
             log_path="/test_run/run/logs/$test_case_name/$model_name_clean/sglang_server_decode.log"
             pid_suffix="decode"
-            extra_args="--disaggregation-mode decode --tp-size 2 --base-gpu-id=6"
+            extra_args="--disaggregation-mode decode --tp-size 2 --base-gpu-id=${MOONCAKE_EPD_DECODE_GPU_ID:-6}"
+            if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+                extra_args="${extra_args} --disaggregation-ib-device=${MOONCAKE_TRANSFER_DEVICE}"
+            fi
             ready_pattern="The server is fired up and ready to roll!"
             echo "Starting Decode Server..."
             ;;
@@ -58,12 +66,12 @@ start_epd_component()
             return 1
             ;;
     esac
-    
+
     if ! launch_sglang_server "$model_name" "$host" "$port" "$log_path" "$pid_suffix" "$extra_args" "$ready_pattern"; then
         echo "ERROR: Failed to start $component_type"
         return 1
     fi
-    
+
     return 0
 }
 
@@ -76,7 +84,7 @@ run_proxy()
         echo "ERROR: Failed to start SGLang Router"
         return 1
     fi
-    
+
     return 0
 }
 
@@ -84,8 +92,12 @@ run_request()
 {
     local model_name=$1
     local image_file_path=${2:-"${BASE_DIR}/assets/test_cat.jpg"}
+    local request_timeout=60
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        request_timeout=180
+    fi
     echo "===== Sending Test Request ====="
-    
+
     if [ ! -f "$image_file_path" ]; then
         echo "ERROR: Image file not found: $image_file_path"
         return 1
@@ -125,20 +137,20 @@ with open('$temp_json_file', 'w') as f:
 
 print("✓ JSON file generated successfully")
 EOF
-    
+
     if [ $? -ne 0 ]; then
         echo "ERROR: Failed to generate JSON request file"
         rm -f "$temp_json_file"
         return 1
     fi
-    
+
     curl_response=$(curl -s -w "\n%{http_code}" -X POST http://127.0.0.1:8000/v1/chat/completions \
       -H "Content-Type: application/json" \
       -d @$temp_json_file \
-      --max-time 60)
-    
+      --max-time "$request_timeout")
+
     rm -f "$temp_json_file"
-    
+
     response_body=$(echo "$curl_response" | head -n -1)
     status_code=$(echo "$curl_response" | tail -n 1)
     echo "Curl Response:"
@@ -166,7 +178,7 @@ start_local_components()
     local model_name=$1
     local model_name_clean=$2
     local components=("encoder" "prefill")
-    
+
     for component in "${components[@]}"; do
         start_epd_component "$component" "$model_name" "$model_name_clean" || return 1
     done
@@ -177,12 +189,12 @@ start_remote_decode()
 {
     local model_name=$1
     local model_name_clean=$2
-    
-    if ! ${SSH_CMD} $REMOTE_IP "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_component decode $model_name $model_name_clean"; then
+
+    if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_component decode $model_name $model_name_clean"; then
         echo "ERROR: Failed to start remote decode component"
         return 1
     fi
-    
+
     return 0
 }
 
@@ -192,9 +204,9 @@ run_single_model()
     local model_name_clean=$(sanitize_model_name "$model_name")
 
     setup_log_directory_dual "$test_case_name" "$model_name_clean"
-    
+
     echo "===== Run MODEL NAME: $model_name ====="
-    
+
     # Encoders → Local Prefill → Remote Decode → Router → Test
     if start_local_components "$model_name" "$model_name_clean" && \
        start_remote_decode "$model_name" "$model_name_clean" && \
@@ -207,8 +219,10 @@ run_single_model()
     fi
 
     echo "===== Cleaning up model processes for $model_name ====="
-    kill_model_processes
-    sleep 2
+    if ! kill_model_processes; then
+        echo "ERROR: Model process cleanup failed for $model_name" >&2
+        status=1
+    fi
 
     return $status
 }
@@ -219,7 +233,7 @@ run_test()
         echo "ERROR: Please specify LOCAL_IP and REMOTE_IP"
         return 1
     fi
-    
+
     echo "===== Running EPD test case: $test_case_name for all supported models ====="
 
     local test_failed=false
@@ -233,14 +247,14 @@ run_test()
     if [ "$test_failed" = true ]; then
         return 1
     fi
-    
+
     return 0
 }
 
 parse()
 {
     echo "===== Parsing test results ====="
-    
+
     if collect_and_validate_model_results "SUPPORT_MODELS" "sglang_server_decode.log" "$test_case_name" "cat|kitten|feline"; then
         save_test_result "$test_case_name" "Pass" "${BASE_DIR}/${TEST_CASE_RESULT_PATH}"
         echo "✓ Test PASSED"
@@ -260,7 +274,7 @@ case "$1" in
         ;;
     "stop_server")
         kill_model_processes
-        exit 0
+        exit $?
         ;;
     *)
         if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
diff --git a/scripts/tone_tests/scripts/test_hicache_storage_mooncake_backend.sh b/scripts/tone_tests/scripts/test_hicache_storage_mooncake_backend.sh
index 8206ea88de..a72097e004 100644
--- a/scripts/tone_tests/scripts/test_hicache_storage_mooncake_backend.sh
+++ b/scripts/tone_tests/scripts/test_hicache_storage_mooncake_backend.sh
@@ -10,13 +10,18 @@ run_test()
 {
     echo "===== Running pytest tests ====="
     local log_file="${BASE_DIR}/${TEST_CASE_RESULT_PATH}/${test_case_name}.log"
+    local pytest_env=""
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        pytest_env="SGLANG_IS_IN_CI=1 "
+    fi
 
     echo "Running tests in container and saving output to: $log_file"
     ${docker_exec} "\
         export PYTHONPATH=/sgl-workspace/sglang/test/registered/hicache:\$PYTHONPATH && \
         cd /test_run/python && \
-        python3 -m pytest test_hicache_storage_mooncake_backend.py -v -s --tb=long" | tee "$log_file"
-    
+        ${pytest_env}python3 -m pytest test_hicache_storage_mooncake_backend.py -v -s --tb=long" \
+        2>&1 | tee "$log_file"
+
     return ${PIPESTATUS[0]}
 }
 
@@ -41,7 +46,7 @@ if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
     if ! run_test; then
         exit_code=1
     fi
-    
+
     parse $exit_code
     exit $?
 fi
diff --git a/scripts/tone_tests/scripts/test_moe_mooncake.sh b/scripts/tone_tests/scripts/test_moe_mooncake.sh
index 477e3cfdc0..fb457fe68d 100644
--- a/scripts/tone_tests/scripts/test_moe_mooncake.sh
+++ b/scripts/tone_tests/scripts/test_moe_mooncake.sh
@@ -8,19 +8,26 @@ BASE_DIR=${BASE_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)}
 . ${BASE_DIR}/scripts/common.sh
 
 run_test()
-{ 
+{
     echo "===== Running pytest tests ====="
     local log_file="${BASE_DIR}/${TEST_CASE_RESULT_PATH}/${test_case_name}.log"
 
     echo "Running tests in container and saving output to: $log_file"
 
+    if ! ${docker_exec} "command -v sgl-eval >/dev/null 2>&1"; then
+        echo "ERROR: sgl-eval is missing from the SGLang test container" >&2
+        echo "The T-One setup must install the pinned sgl-eval dependency before pytest." >&2
+        return 1
+    fi
+
     # Use local HF cache (offline) when the model is already downloaded.
     local offline_prefix=$(hf_offline_prefix "deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct")
 
     ${docker_exec} "\
         export PYTHONPATH=/sgl-workspace/sglang:\$PYTHONPATH && \
         cd /test_run/python && \
-        ${offline_prefix}python3 -m pytest test_moe_mooncake.py -v -s --tb=long" | tee "$log_file"
+        ${offline_prefix}python3 -m pytest test_moe_mooncake.py -v -s --tb=long" \
+        2>&1 | tee "$log_file"
 
     return ${PIPESTATUS[0]}
 }
@@ -46,7 +53,7 @@ if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
     if ! run_test; then
         exit_code=1
     fi
-    
+
     parse $exit_code
     exit $?
-fi
\ No newline at end of file
+fi
diff --git a/scripts/tone_tests/scripts/test_vllm_1p1d_erdma.sh b/scripts/tone_tests/scripts/test_vllm_1p1d_erdma.sh
index 150aa98ecb..580faa0bae 100755
--- a/scripts/tone_tests/scripts/test_vllm_1p1d_erdma.sh
+++ b/scripts/tone_tests/scripts/test_vllm_1p1d_erdma.sh
@@ -2,7 +2,11 @@
 
 test_case_name="test_vllm_1p1d_erdma"
 TEST_TYPE="double"
-SUPPORT_MODELS=("Qwen/Qwen3-8B" "deepseek-ai/DeepSeek-V2-Lite")
+if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+    SUPPORT_MODELS=("Qwen/Qwen3-8B")
+else
+    SUPPORT_MODELS=("Qwen/Qwen3-8B" "deepseek-ai/DeepSeek-V2-Lite")
+fi
 
 PID_DIR=${BASE_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)}/run/pids/${test_case_name}
 BASE_DIR=${BASE_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)}
@@ -20,7 +24,7 @@ start_server()
     local port
     local kv_role
 
-    if [ "$ISREMOTE" == "0" ]; then 
+    if [ "$ISREMOTE" == "0" ]; then
         host=$LOCAL_IP
         vllm_server_log_path=/test_run/run/logs/$test_case_name/$model_name_clean/vllm_server_local.log
         port=8020
@@ -32,12 +36,32 @@ start_server()
         kv_role="kv_producer"
     fi
 
-    local kv_config_json="{\\\"kv_connector\\\":\\\"MooncakeConnector\\\",\\\"kv_role\\\":\\\"$kv_role\\\"}"
+    local kv_config_json
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        # This lane is serialized smoke coverage for basic connector
+        # correctness. It does not exercise concurrent sender workers; that
+        # remains separate coverage while vllm-project/vllm#44238 is unresolved.
+        echo "ROCm vLLM coverage: serialized Mooncake connector smoke (num_workers=1)"
+        kv_config_json="{\"kv_connector\":\"MooncakeConnector\",\"kv_role\":\"$kv_role\",\"kv_connector_extra_config\":{\"num_workers\":1}}"
+    else
+        kv_config_json="{\"kv_connector\":\"MooncakeConnector\",\"kv_role\":\"$kv_role\"}"
+    fi
+
+    local env_vars
+    if [ "${CI_ACCELERATOR:-cuda}" = "rocm" ]; then
+        # The MI350X default allocates roughly 233 GiB of KV cache per rank,
+        # producing 72 multi-GiB dma-buf registrations against every visible
+        # RNIC. The connector smoke test needs only a small cache and the RoCE
+        # rail selected by the runner profile.
+        local gpu_memory_utilization=0.3
+        env_vars="ROCR_VISIBLE_DEVICES=${MOONCAKE_VLLM_VISIBLE_DEVICES:-0,1} HIP_VISIBLE_DEVICES=${MOONCAKE_VLLM_VISIBLE_DEVICES:-0,1} MC_MAX_CONCURRENT_REG_MR=1 MC_TE_FILTERS=${MOONCAKE_TRANSFER_DEVICE:-ionic_0}"
+    else
+        local gpu_memory_utilization=0.85
+        env_vars="CUDA_VISIBLE_DEVICES=${MOONCAKE_VLLM_VISIBLE_DEVICES:-6,7}"
+    fi
+
+    local extra_args="--tensor-parallel-size 2 --max-model-len 32768 --gpu-memory-utilization ${gpu_memory_utilization} --no-enable-prefix-caching --kv-transfer-config '$kv_config_json'"
 
-    local extra_args="--tensor-parallel-size 2 --max-model-len 32768 --gpu-memory-utilization 0.85 --no-enable-prefix-caching --kv-transfer-config '$kv_config_json'"
-    
-    local env_vars="CUDA_VISIBLE_DEVICES=6,7"
-    
     if ! launch_vllm_server "$model_name" "$host" "$port" "$vllm_server_log_path" "$kv_role" "$extra_args" "$env_vars"; then
         return 1
     fi
@@ -51,18 +75,28 @@ run_proxy()
     local proxy_log_path="/test_run/run/logs/$test_case_name/$model_name/proxy.log"
 
     echo "===== Proxy Run ====="
-    
+
     # Get vLLM version and decide which proxy to use
     local vllm_version=$(${docker_exec} "python3 -c 'import vllm; print(vllm.__version__)' 2>/dev/null" || echo "0.15.0")
     echo "Detected vLLM version: $vllm_version"
-    
+
     # Determine proxy script and ready check strategy
     local proxy_script
     local ready_pattern
     local use_health_check=0
     if python3 -c "from packaging import version; import sys; sys.exit(0 if version.parse('$vllm_version') >= version.parse('0.16.0') else 1)" 2>/dev/null; then
         echo "Using Mooncake Connector Proxy (vLLM >= 0.16.0)"
-        proxy_script="python3 -u /vllm-workspace/examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py --prefill http://$REMOTE_IP:8010 --decode http://$LOCAL_IP:8020 --host 0.0.0.0 --port 8000"
+        local proxy_path
+        proxy_path=$(${docker_exec} "for path in \
+            /app/vllm/examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \
+            /vllm-workspace/examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py; do \
+                if [ -f \"\$path\" ]; then printf '%s' \"\$path\"; break; fi; \
+            done")
+        if [ -z "$proxy_path" ]; then
+            echo "ERROR: vLLM Mooncake connector proxy not found in a supported image layout" >&2
+            return 1
+        fi
+        proxy_script="python3 -u $proxy_path --prefill http://$REMOTE_IP:8010 --decode http://$LOCAL_IP:8020 --host 0.0.0.0 --port 8000"
         ready_pattern="All prefiller instances are ready."
     else
         echo "Using NIXL Proxy (vLLM < 0.16.0)"
@@ -72,13 +106,12 @@ run_proxy()
     fi
 
     # Launch proxy
-    local lb_cmd="${docker_exec} \"$proxy_script > $proxy_log_path 2>&1 &\""
     local pid_file="${PID_DIR}/proxy.pid"
-    # Extract Python script path (second word) and get filename
-    local grep_pattern=$(echo "$proxy_script" | grep -oE '[^/]+\.py')
-    
+    local grep_pattern
+    grep_pattern=$(echo "$proxy_script" | grep -oE '[^/]+\.py')
+
     echo "Starting proxy server..."
-    if ! launch_and_track_process "$lb_cmd" "$grep_pattern" "$pid_file"; then
+    if ! launch_and_track_process "$proxy_script" "$proxy_log_path" "$pid_file" "$grep_pattern"; then
         return 1
     fi
 
@@ -90,7 +123,7 @@ run_proxy()
 
     # Additional health check for toy_proxy_server
     if [ "$use_health_check" -eq 1 ]; then
-        if ! wait_for_server_ready "$LOCAL_IP" "8000" "/health"; then
+        if ! wait_for_server_ready "$LOCAL_IP" "8000" "/healthcheck"; then
             return 1
         fi
     fi
@@ -141,14 +174,14 @@ run_single_model()
 
     setup_log_directory_dual "$test_case_name" "$model_name_clean"
 
-    echo "===== Run MODEL NAME: $model_name ====="    
+    echo "===== Run MODEL NAME: $model_name ====="
     # Local start server
     if ! start_server $model_name $model_name_clean; then
         echo "ERROR: Failed to start local server for model $model_name"
         status=1
     else
         # Remote start server
-        if ! ${SSH_CMD} $REMOTE_IP "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_server $model_name $model_name_clean"; then
+        if ! ${SSH_CMD} "${REMOTE_SSH_TARGET:-$REMOTE_IP}" "source $REMOTE_TEST_DIR/run/.shrc; cd \$BASE_DIR/scripts && ./$test_case_name.sh start_server $model_name $model_name_clean"; then
             echo "ERROR: Failed to start remote server for model $model_name"
             status=1
         else
@@ -168,8 +201,10 @@ run_single_model()
     fi
 
     echo "===== Cleaning up model processes for $model_name ====="
-    kill_model_processes
-    sleep 2
+    if ! kill_model_processes; then
+        echo "ERROR: Model process cleanup failed for $model_name" >&2
+        status=1
+    fi
 
     return $status
 }
@@ -183,17 +218,24 @@ run_test()
     echo "===== Running test case: $test_case_name for all supported models ====="
 
     local test_failed=false
+    local model_index=0
+    local model_count=${#SUPPORT_MODELS[@]}
     for model in "${SUPPORT_MODELS[@]}"; do
+        model_index=$((model_index + 1))
         if ! run_single_model "$model"; then
             echo "ERROR: Test case $test_case_name failed for model $model"
             test_failed=true
         fi
+        if [ "$model_index" -lt "$model_count" ] && ! drain_gpu_between_tests; then
+            echo "ERROR: Failed to isolate the next model from $model" >&2
+            return 1
+        fi
     done
 
     if [ "$test_failed" = true ]; then
         return 1
     fi
-    
+
     return 0
 }
 
@@ -220,11 +262,11 @@ case "$1" in
         ;;
     "stop_server")
         kill_model_processes
-        exit 0
+        exit $?
         ;;
     *)
         if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
             run_test && parse || parse
         fi
         ;;
-esac
\ No newline at end of file
+esac
diff --git a/scripts/tone_tests/tests/test_common_cleanup.sh b/scripts/tone_tests/tests/test_common_cleanup.sh
new file mode 100755
index 0000000000..cc6b1e0d34
--- /dev/null
+++ b/scripts/tone_tests/tests/test_common_cleanup.sh
@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TEST_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+COMMON_SH="${TEST_DIR}/../scripts/common.sh"
+
+fail() {
+    echo "FAIL: $*" >&2
+    return 1
+}
+
+test_rocm_stop_failure_is_not_masked() (
+    export CI_ACCELERATOR=rocm
+    export CONTAINER_NAME=mooncake-cleanup-test
+    export REMOTE_IP=
+    export MOONCAKE_RENDER_DEVICES=/dev/dri/renderD129
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    call_log=$(mktemp)
+    trap 'rm -f "$call_log"' EXIT
+    container_present=true
+
+    docker() {
+        printf '%s\n' "$*" >> "$call_log"
+        case "$1" in
+            ps)
+                if $container_present; then
+                    printf '%s\n' "$CONTAINER_NAME"
+                fi
+                ;;
+            stop)
+                return 42
+                ;;
+            rm)
+                container_present=false
+                return 0
+                ;;
+            *)
+                fail "unexpected docker command: $*"
+                ;;
+        esac
+    }
+    wait_gpu_idle() {
+        echo wait_gpu_idle >> "$call_log"
+        return 0
+    }
+    verify_no_allocated_gpu_processes() {
+        echo verify_no_allocated_gpu_processes >> "$call_log"
+        return 0
+    }
+
+    if cleanup_test_env single; then
+        fail "cleanup succeeded after docker stop failed"
+    fi
+    grep -Fq "stop $CONTAINER_NAME" "$call_log" \
+        || fail "docker stop was not attempted"
+    grep -Fq "rm -f $CONTAINER_NAME" "$call_log" \
+        || fail "docker rm was not attempted after stop failed"
+    grep -Fq wait_gpu_idle "$call_log" \
+        || fail "GPU drain was skipped after stop failed"
+    grep -Fq verify_no_allocated_gpu_processes "$call_log" \
+        || fail "process postflight was skipped after stop failed"
+)
+
+test_rocm_cleanup_is_idempotent() (
+    export CI_ACCELERATOR=rocm
+    export CONTAINER_NAME=mooncake-cleanup-test
+    export REMOTE_IP=
+    export MOONCAKE_RENDER_DEVICES=/dev/dri/renderD129
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    call_log=$(mktemp)
+    trap 'rm -f "$call_log"' EXIT
+    container_present=true
+
+    docker() {
+        printf '%s\n' "$*" >> "$call_log"
+        case "$1" in
+            ps)
+                if $container_present; then
+                    printf '%s\n' "$CONTAINER_NAME"
+                fi
+                ;;
+            stop)
+                return 0
+                ;;
+            rm)
+                container_present=false
+                return 0
+                ;;
+            *)
+                fail "unexpected docker command: $*"
+                ;;
+        esac
+    }
+    wait_gpu_idle() { return 0; }
+    verify_no_allocated_gpu_processes() { return 0; }
+
+    cleanup_test_env single || fail "first cleanup failed"
+    cleanup_test_env single || fail "second cleanup should accept an absent container"
+    [ "$(grep -Fc "stop $CONTAINER_NAME" "$call_log")" -eq 1 ] \
+        || fail "idempotent cleanup stopped the container more than once"
+)
+
+test_remote_rocm_failure_is_aggregated() (
+    export CI_ACCELERATOR=rocm
+    export CONTAINER_NAME=mooncake-cleanup-test
+    export REMOTE_IP=192.0.2.2
+    export REMOTE_SSH_TARGET=mooncake-worker
+    export REMOTE_TEST_DIR=/var/lib/mooncake-ci/work
+    export SSH_CMD=mock_ssh
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    docker() {
+        case "$1" in
+            ps) return 0 ;;
+            *) fail "unexpected local docker command: $*" ;;
+        esac
+    }
+    wait_gpu_idle() { return 0; }
+    verify_no_allocated_gpu_processes() { return 0; }
+    mock_ssh() { return 17; }
+
+    if cleanup_test_env double; then
+        fail "cleanup succeeded after remote postflight failed"
+    fi
+)
+
+test_rocm_process_postflight_detects_allocated_device_holder() (
+    export CI_ACCELERATOR=rocm
+    export CONTAINER_NAME=mooncake-cleanup-test
+    temp_dir=$(mktemp -d)
+    trap 'rm -rf "$temp_dir"' EXIT
+    export MOONCAKE_RENDER_DEVICES="$temp_dir/dev/dri/renderD129"
+    export MOONCAKE_KFD_TOPOLOGY_ROOT="$temp_dir/kfd/topology/nodes"
+    export MOONCAKE_KFD_PROCESS_ROOT="$temp_dir/kfd/proc"
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    mkdir -p "$temp_dir/dev/dri" \
+        "$MOONCAKE_KFD_TOPOLOGY_ROOT/7" \
+        "$MOONCAKE_KFD_PROCESS_ROOT/321/queues/9"
+    : > "$MOONCAKE_RENDER_DEVICES"
+    printf 'drm_render_minor 129\n' \
+        > "$MOONCAKE_KFD_TOPOLOGY_ROOT/7/properties"
+    printf '42\n' > "$MOONCAKE_KFD_TOPOLOGY_ROOT/7/gpu_id"
+    printf '42\n' > "$MOONCAKE_KFD_PROCESS_ROOT/321/queues/9/gpuid"
+    ps() { return 0; }
+
+    if verify_no_allocated_gpu_processes; then
+        fail "ROCm postflight ignored a process holding an allocated device"
+    fi
+)
+
+test_rocm_memory_query_requires_every_allocated_gpu() (
+    export CI_ACCELERATOR=rocm
+    export CONTAINER_NAME=mooncake-cleanup-test
+    export MOONCAKE_GPU_INDICES=0,1
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    rocm-smi() {
+        printf '%s\n' '{"card0":{"VRAM Total Used Memory (B)":0}}'
+    }
+
+    [ "$(gpu_max_used_mb)" = -1 ] \
+        || fail "ROCm memory query accepted an incomplete allocation"
+)
+
+test_rocm_runtime_cache_is_image_scoped() (
+    export CONTAINER_NAME=mooncake-cache-test
+    temp_dir=$(mktemp -d)
+    trap 'rm -rf "$temp_dir"' EXIT
+    export MOONCAKE_RUNTIME_CACHE="$temp_dir/runtime-cache"
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    registry_addr='example/sglang@sha256:0123456789abcdef0123456789abcdef'
+    prepare_rocm_runtime_cache_args "$registry_addr" \
+        || { fail "ROCm runtime cache preparation failed"; return 1; }
+
+    expected_dir="$(cd -P "$MOONCAKE_RUNTIME_CACHE" && pwd)/0123456789abcdef"
+    for cache_dir in \
+        aiter-jit pip tmp torch-extensions torchinductor triton xdg; do
+        [ -d "$expected_dir/$cache_dir" ] \
+            || { fail "missing runtime cache directory: $cache_dir"; return 1; }
+    done
+
+    args=$(printf '%s\n' "${ROCM_RUNTIME_CACHE_ARGS[@]}")
+    printf '%s\n' "$args" | grep -Fxq "$expected_dir:/runtime-cache" \
+        || { fail "runtime cache bind mount is missing"; return 1; }
+    printf '%s\n' "$args" | grep -Fxq 'AITER_JIT_DIR=/runtime-cache/aiter-jit' \
+        || { fail "AITER JIT cache is not redirected"; return 1; }
+    printf '%s\n' "$args" | grep -Fxq 'TRITON_CACHE_DIR=/runtime-cache/triton' \
+        || { fail "Triton cache is not redirected"; return 1; }
+)
+
+test_rocm_runtime_cache_rejects_unsafe_root() (
+    export CONTAINER_NAME=mooncake-cache-test
+    export MOONCAKE_RUNTIME_CACHE=/
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    if prepare_rocm_runtime_cache_args example/sglang:latest; then
+        fail "ROCm runtime cache accepted the filesystem root"
+    fi
+)
+
+test_cuda_cleanup_aggregates_both_nodes() (
+    export CI_ACCELERATOR=cuda
+    export CONTAINER_NAME=mooncake-cleanup-test
+    export REMOTE_IP=192.0.2.2
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    call_log=$(mktemp)
+    trap 'rm -f "$call_log"' EXIT
+    stop_container() {
+        printf '%s\n' "$*" >> "$call_log"
+        if [ "$#" -eq 1 ]; then
+            return 9
+        fi
+        return 0
+    }
+
+    if cleanup_test_env double; then
+        fail "CUDA cleanup succeeded after the local stop failed"
+    fi
+    [ "$(wc -l < "$call_log" | tr -d ' ')" -eq 2 ] \
+        || fail "CUDA cleanup did not attempt both nodes"
+)
+
+test_cuda_process_launch_keeps_legacy_pid_tracking() (
+    export CI_ACCELERATOR=cuda
+    export CONTAINER_NAME=mooncake-cleanup-test
+    test_case_name=cleanup_unit
+    # shellcheck disable=SC1090
+    source "$COMMON_SH"
+
+    temp_dir=$(mktemp -d)
+    trap 'rm -rf "$temp_dir"' EXIT
+    call_log="$temp_dir/docker.log"
+    pid_file="$temp_dir/server.pid"
+    process_cmd='CUDA_VISIBLE_DEVICES=6,7 python3 -m server --config '\''{"workers":2}'\'''
+
+    docker() {
+        printf '%s\n' "$*" >> "$call_log"
+        if [ "$1" = inspect ]; then
+            printf '100\n'
+        fi
+        return 0
+    }
+    ps() {
+        printf '200 100 python3 -m server --config {"workers":2}\n'
+    }
+    sleep() { return 0; }
+
+    launch_and_track_process "$process_cmd" /tmp/server.log "$pid_file" \
+        'python3 -m server' || fail "CUDA legacy process launch failed"
+    grep -Fq -- "--config '{\"workers\":2}'" "$call_log" \
+        || fail "CUDA launch command lost its quoted JSON"
+    [ "$(cat "$pid_file")" = 200 ] \
+        || fail "CUDA launch did not record the legacy host PID"
+)
+
+test_run_all_propagates_cleanup_failure() (
+    export CI_ACCELERATOR=cuda
+    export LOCAL_IP=127.0.0.1
+    export REMOTE_IP=
+    export ARTIFACT_ID=unit-test
+    export GIT_REPO=example/Mooncake
+    # shellcheck disable=SC1090
+    source "${TEST_DIR}/../scripts/run_test.sh"
+
+    temp_dir=$(mktemp -d)
+    trap 'rm -rf "$temp_dir"' EXIT
+    TONE_TESTS_DIR=$temp_dir
+    RUN_DIR="$temp_dir/run"
+    mkdir -p "$RUN_DIR" "$TONE_TESTS_DIR/scripts"
+    printf 'test_case_name="cleanup_caller"\nTEST_TYPE="double"\nrun_test() { return 0; }\nparse() { return 0; }\n' \
+        > "$TONE_TESTS_DIR/scripts/fake_test.sh"
+    UNIT_TESTS=(fake_test.sh)
+
+    setup_env_for_test() {
+        printf 'export BASE_DIR=%s\nexport TEST_RUN_DIR=%s\n' \
+            "$TONE_TESTS_DIR" "$RUN_DIR" > "$RUN_DIR/.shrc"
+        return 0
+    }
+    cleanup_test_env() { return 1; }
+
+    if run_all_tests UNIT_TESTS; then
+        fail "run_all_tests masked a cleanup failure"
+    fi
+    [ "$MOONCAKE_ENV_UNHEALTHY" = true ] \
+        || fail "run_all_tests did not quarantine the shared environment"
+)
+
+run_test_case() {
+    local name=$1
+    if "$name"; then
+        echo "PASS: $name"
+    else
+        echo "FAIL: $name" >&2
+        return 1
+    fi
+}
+
+run_test_case test_rocm_stop_failure_is_not_masked
+run_test_case test_rocm_cleanup_is_idempotent
+run_test_case test_remote_rocm_failure_is_aggregated
+run_test_case test_rocm_process_postflight_detects_allocated_device_holder
+run_test_case test_rocm_memory_query_requires_every_allocated_gpu
+run_test_case test_rocm_runtime_cache_is_image_scoped
+run_test_case test_rocm_runtime_cache_rejects_unsafe_root
+run_test_case test_cuda_cleanup_aggregates_both_nodes
+run_test_case test_cuda_process_launch_keeps_legacy_pid_tracking
+run_test_case test_run_all_propagates_cleanup_failure
diff --git a/scripts/tone_tests/tests/test_hicache_model_selection.py b/scripts/tone_tests/tests/test_hicache_model_selection.py
new file mode 100644
index 0000000000..559442fc48
--- /dev/null
+++ b/scripts/tone_tests/tests/test_hicache_model_selection.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+import importlib.util
+import os
+import sys
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+class FakeHiCacheStorageBaseMixin:
+    @classmethod
+    def _get_model_name(cls):
+        return "upstream-default-model"
+
+
+def load_test_module():
+    requests = types.ModuleType("requests")
+    requests.RequestException = Exception
+    sys.modules["requests"] = requests
+
+    file_backend = types.ModuleType("test_hicache_storage_file_backend")
+    file_backend.HiCacheStorageBaseMixin = FakeHiCacheStorageBaseMixin
+    sys.modules["test_hicache_storage_file_backend"] = file_backend
+
+    sglang = types.ModuleType("sglang")
+    sglang.__path__ = []
+    sglang_test = types.ModuleType("sglang.test")
+    sglang_test.__path__ = []
+    test_utils = types.ModuleType("sglang.test.test_utils")
+    test_utils.DEFAULT_MLA_MODEL_NAME_FOR_TEST = "upstream-mla-model"
+    test_utils.CustomTestCase = unittest.TestCase
+    test_utils.find_available_port = lambda base: base
+    test_utils.is_in_ci = lambda: False
+    sys.modules.update(
+        {
+            "sglang": sglang,
+            "sglang.test": sglang_test,
+            "sglang.test.test_utils": test_utils,
+        }
+    )
+
+    module_path = (
+        Path(__file__).resolve().parents[1]
+        / "python"
+        / "test_hicache_storage_mooncake_backend.py"
+    )
+    spec = importlib.util.spec_from_file_location("mooncake_hicache_test", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestModelSelection(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.module = load_test_module()
+
+    def test_cuda_inherits_upstream_default(self):
+        with mock.patch.dict(os.environ, {"CI_ACCELERATOR": "cuda"}):
+            self.assertEqual(
+                self.module.HiCacheStorageMooncakeBackendBaseMixin._get_model_name(),
+                "upstream-default-model",
+            )
+
+    def test_rocm_uses_ci_model(self):
+        with mock.patch.dict(os.environ, {"CI_ACCELERATOR": "rocm"}):
+            self.assertEqual(
+                self.module.HiCacheStorageMooncakeBackendBaseMixin._get_model_name(),
+                "Qwen/Qwen3-8B",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()